diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index da8b007afc..f8fbf6edd7 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -19,10 +19,14 @@ } ], "branch_target_mapping": { + "duncan_mos_rs3_pdf": [ + "Publish", + "Pdf" + ], "live": [ "Publish", "Pdf" - ] + ] }, "Targets": { "Pdf": { @@ -31,8 +35,7 @@ }, "notification_subscribers": [], "branches_to_filter": [], - "git_repository_url_open_to_public_contributors": "https://github.com/Microsoft/windows-driver-docs", - "git_repository_branch_open_to_public_contributors": "staging", + "git_repository_url_open_to_public_contributors": "https://cpubwin.visualstudio.com/_git/drivers", "skip_source_output_uploading": false, "need_preview_pull_request": false, "dependent_repositories": [ @@ -47,5 +50,6 @@ "branch": "master" } ], - "need_generate_pdf_url_template": true + "need_generate_pdf_url_template": true, + "resolve_user_profile_using_github": true } \ No newline at end of file diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 69ead9f497..4fa88ed0eb 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -736,28 +736,154 @@ "redirect_document_id": true }, { - "source_path": "windows-driver-docs-pr/sensors/architecture-overview", + "source_path": "windows-driver-docs-pr/sensors/architecture-overview.md", "redirect_URL": "/windows-hardware/drivers/sensors/architecture-overview-for-sensor-drivers ", "redirect_document_id": true }, { - "source_path": "windows-driver-docs-pr/display/performing-copp-operations2", + "source_path": "windows-driver-docs-pr/display/performing-copp-operations2.md", "redirect_URL": "/windows-hardware/drivers/display/performing-copp-operations-example ", "redirect_document_id": true }, { - "source_path": "windows-driver-docs-pr/dashboard/walkthrough--how-to-get-a-driver-signed-by-microsoft-for-multiple-versions-of-windows", + "source_path": "windows-driver-docs-pr/dashboard/walkthrough--how-to-get-a-driver-signed-by-microsoft-for-multiple-versions-of-windows.md", "redirect_URL": "/windows-hardware/drivers/dashboard/get-drivers-signed-by-microsoft-for-multiple-windows-versions", "redirect_document_id": true }, { - "source_path": "windows-driver-docs-pr/nfc/p2p-rf-data-exchagne-sequence", + "source_path": "windows-driver-docs-pr/nfc/p2p-rf-data-exchagne-sequence.md", "redirect_URL": "/windows-hardware/drivers/nfc/p2p-rf-data-exchange-sequence", "redirect_document_id": true - },{ + }, + { + "source_path": "windows-driver-docs-pr/install/using-a-configurable-inf-file.md", + "redirect_URL": "/windows-hardware/drivers/install/using-a-universal-inf-file", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/install/creating-an-extensible-inf-file.md", + "redirect_URL": "/windows-hardware/drivers/install/using-an-extension-inf-file", + "redirect_document_id": true + }, + { "source_path": "windows-driver-docs-pr/nfc/tag-rf-data-exchagne-sequence.md", "redirect_URL": "/windows-hardware/drivers/nfc/tag-rf-data-exchange-sequence", "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/install/Windows10SDriverGuidelines.md", + "redirect_URL": "/windows-hardware/drivers/install/Windows10SDriverRequirements", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/wdf/what-s-new-for-wdf-drivers.md", + "redirect_URL": "/windows-hardware/drivers/wdf/index", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/ndis-versions-in-network-drivers.md", + "redirect_URL": "/windows-hardware/drivers/network/overview-of-ndis-versions", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis--rndis.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-communication", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-control-messages2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-control-messages", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-initialize-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-initialize-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-initialize-cmplt2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-initialize-cmplt", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-halt-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-halt-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-query-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-query-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-query-cmplt2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-query-cmplt", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-set-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-set-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-set-cmplt2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-set-cmplt", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-reset-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-reset-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-reset-cmplt2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-reset-cmplt", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-indicate-status-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-indicate-status-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-keepalive-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-keepalive-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-keepalive-cmplt", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-data-message2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-data-message", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/network/remote-ndis-packet-msg2.md", + "redirect_URL": "/windows-hardware/drivers/network/remote-ndis-packet-msg", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/devapps/custom-capabilities-for-universal-windows-platform-apps.md", + "redirect_URL": "/windows-hardware/drivers/devapps/creating-a-custom-capability-to-pair-driver-with-hsa", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/devapps/developing-a-universal-windows-platform-app-with-custom-capabilities.md", + "redirect_URL": "/windows-hardware/drivers/devapps/using-a-custom-capability-to-pair-hsa-with-driver", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/install/adding-software-components-with-an-inf-file.md", + "redirect_URL": "/windows-hardware/drivers/install/using-a-component-inf-file", + "redirect_document_id": true + }, + { + "source_path": "windows-driver-docs-pr/develop/installing-the-enterprise-wdk.md", + "redirect_URL": "/windows-hardware/drivers/develop/using-the-enterprise-wdk", + "redirect_document_id": true } ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb0f64cf3c..eb9c83bc9a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,60 +1,49 @@ # Contributing to Windows Driver Documentation -Thank you for your interest in the Windows driver documentation! We appreciate your feedback, edits, and additions to our docs. -This page covers the basic steps for contributing to our technical documentation. +This page covers the basic steps for contributing to the Windows driver documentation. There's also an [introductory video](https://channel9.msdn.com/Blogs/WinHEC/Contributing-to-MSDN-and-TechNet-Documentation) that shows you how to propose changes. ## Sign a CLA -All contributors who are ***not*** a Microsoft employee must [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) before contributing to any Microsoft repositories. -If you've already contributed to Microsoft repositories in the past, congratulations! -You've already completed this step. +If you want to contribute more than a couple lines and you're not a Microsoft employee, you need to [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/). -## Public and private repos +If you are a Microsoft employee, be sure to [link your GitHub account and alias](https://opensource.microsoft.com/link). -The driver docs are hosted in two different repos which are then merged and updated to a single site: one repo is for contributions from anyone and the other is only for Microsoft employees. +If you've already contributed to Microsoft repositories in the past, congratulations! +You've already completed this step. -If you are ***not*** a Microsoft employee, work in the [public content repository](https://github.com/Microsoft/windows-driver-docs). -If you ***are*** a Microsoft employee, you can work in either the public repo or the [private content repository](https://cpubwin.visualstudio.com/drivers/_git/drivers). Typically, employees use the public repo for changes that can go live in the near term, and the private repo for changes that need to stay under wraps until some future date. +## Proposing a change -## Editing topics +If you'd like to suggest a change to the docs, follow these steps: -We've tried to make editing an existing file as simple as possible. -- If you're already in the repo, just navigate to the file and click the **Edit** button. -- Alternatively, if you're viewing an MSDN page in your browser, click the **Contribute** button on the top right of the page. You will be redirected to the correct Markdown source file in the repo, where you can click the **Edit** button. +1. If you're viewing a Docs.microsoft.com page, 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. +5. When you're done, commit your changes and open a pull request. -> **Note** We're actively moving docs into the repo, so the one you want might not be there yet. If you don't see a **Contribute** button for a page you'd like to change, please open an issue in the repo and be sure to provide the URL of the page in question. - -If you're using the GitHub-based public repo, GitHub automatically forks the official repo into your personal GitHub account, where you can make your changes. +After you create the pull request, a member of the Windows Driver Documentation team will review your changes. -If you're using the VSO-based private repo, use the drop-down arrow next to the Commit button and select **Commit to new branch**. +If your request is accepted, updates are published to https://docs.microsoft.com/windows-hardware/drivers. -Either way, when you're done, submit a pull request back to the staging branch (if using GitHub) or master branch (if using VSO) of the official repository. -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 https://msdn.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. ## Making more substantial changes -To make substantial changes to an existing article, add or change images, or contribute a new article, you will need to create a local clone of the content. -For info about creating a fork or clone, see the GitHub help topic, [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. -If you are using the public repo, fork the official repo into your personal GitHub account, and then clone the fork down to your local computer. Work locally, then push your changes back into your fork. Then open a pull request back to the staging branch of the official public repo. - -If you are using the private repo, clone the private repo to your local computer. Create a new branch from master, make your changes, and then push your new branch back into the VSO private repo. Then open a pull request back to the master branch. +For more info, see [Fork a Repo](https://help.github.com/articles/fork-a-repo/). ## Using issues to provide feedback on Windows driver documentation -If you just want to provide feedback rather than directly modifying actual documentation pages, you can create an issue in the appropriate (public or private) repository. -At the top of a topic page you'll see an **Issues** tab. Click the tab and then click the **New issue** button. -Be sure to include the topic title and the URL for the page, if it's different from the page you launched the New issue dialog from. +If you would like to provide feedback rather than suggesting a change to documentation, [create an issue](https://github.com/MicrosoftDocs/windows-driver-docs/issues). -Members of the Windows driver documentation team review issues regularly, and we triage, assign, and address them accordingly. +Be sure to include the topic title and the URL for the page. ## Resources You can use your favorite text editor to edit Markdown. We recommend [Visual Studio Code](https://code.visualstudio.com/), a free lightweight open source editor from Microsoft. You can learn the basics of Markdown in just a few minutes. To get started, check out [Mastering Markdown](https://guides.github.com/features/mastering-markdown/). - diff --git a/README.md b/README.md index fec138f74d..aaa28a680f 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 Driver Kit documentation available on [MSDN](https://msdn.microsoft.com/windows/hardware/drivers). +Welcome to the Windows driver docs repository, housing the source for the official Windows Driver Kit documentation available on [Docs.microsoft.com](https://docs.microsoft.com/windows-hardware/drivers). ## Contributing 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 e421888531..4d2eaf90c1 100644 --- a/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md +++ b/windows-driver-docs-pr/3dprint/3d-manufacturing-keywords-overview.md @@ -24,7 +24,7 @@ Keyword instances appearing within a PrintCapabilities or PrintTicket document S The namespace URI for the Print Schema keywords for 3D manufacturing is: -``` syntax +``` http://schemas.microsoft.com/3dmanufacturing/2013/01/pskeywords3d ``` diff --git a/windows-driver-docs-pr/3dprint/index.md b/windows-driver-docs-pr/3dprint/index.md index 7704f85672..2c82aa4bf5 100644 --- a/windows-driver-docs-pr/3dprint/index.md +++ b/windows-driver-docs-pr/3dprint/index.md @@ -34,7 +34,6 @@ For the latest information about 3D printing in Windows 10, see the following r - [3D Builder app](http://go.microsoft.com/fwlink/p/?LinkId=627556) - [3D Builder user's guide](http://go.microsoft.com/fwlink/p/?LinkId=627557) - [Channel 9 3D printing blog](http://go.microsoft.com/fwlink/p/?LinkId=624519) -- [Join the 3D Builder community](http://go.microsoft.com/fwlink/p/?LinkId=624526) Download the [Windows 3D Printing SDK](http://go.microsoft.com/fwlink/p/?LinkId=394375) to start developing drivers for printing to a 3D printer. diff --git a/windows-driver-docs-pr/404.md b/windows-driver-docs-pr/404.md index 435ea67921..aeeaf8598c 100644 --- a/windows-driver-docs-pr/404.md +++ b/windows-driver-docs-pr/404.md @@ -1,10 +1,10 @@ # 404 -![Trying to reel in a big fish](fish.png) +![Trying to reel in a big fish](/windows-hardware/drivers/images/fish.png) ## We couldn't quite reel this one in! We can't find the page that you're looking for. Please try again from your favorite search engine, or [send us a mail](mailto:windowsdriverdev@microsoft.com). -You can also go to [Windows Driver Kit (WDK)](https://msdn.microsoft.com/windows/hardware/drivers/) and navigate using the table of contents. +You can also go to [Windows Driver Kit (WDK)](https://docs.microsoft.com/windows-hardware/drivers/) and navigate using the table of contents. diff --git a/windows-driver-docs-pr/TOC.md b/windows-driver-docs-pr/TOC.md index 5d595bcf0c..ffb2233566 100644 --- a/windows-driver-docs-pr/TOC.md +++ b/windows-driver-docs-pr/TOC.md @@ -3,27 +3,33 @@ # [Bring up guide](bringup/index.md) # [Developing, Testing, and Deploying Drivers](develop/index.md) # [Device and Driver Installation](install/index.md) +# [Kernel-Mode Driver Architecture Design Guide](kernel/index.md) # [Windows Driver Frameworks](wdf/index.md) +# [Windows Debugging Tools](debugger/index.md) # [Windows Store Device Apps](devapps/index.md) # [Device and Driver Technologies](device-and-driver-technologies.md) ## [3D print devices](3dprint/index.md) ## [ACPI](acpi/index.md) +## [Audio](audio/index.md) ## [Battery Drivers](battery/index.md) ## [Biometric Drivers](biometric/index.md) ## [Bluetooth Drivers](bluetooth/index.md) ## [Display drivers](display/index.md) ## [Driver Development Tools](devtest/index.md) +## [Getting started with Windows drivers](gettingstarted/index.md) +## [GNSS drivers](gnss/index.md) +## [GPIO drivers](gpio/index.md) ## [HID Drivers](hid/index.md) ## [IEEE Drivers](ieee/index.md) ## [Imaging device drivers](image/index.md) ## [Installable file system drivers](ifs/index.md) -## [Getting started with Windows drivers](gettingstarted/index.md) -## [GNSS drivers](gnss/index.md) -## [GPIO drivers](gpio/index.md) +## [Kernel-mode driver technology](kernel/index.md) ## [Mobile broadband](mobilebroadband/index.md) ## [Multifunction device drivers](multifunction/index.md) +## [NetAdapterCx](netcx/index.md) ## [Network drivers](network/index.md) ## [NFC device drivers](nfc/index.md) +## [Parallel port drivers](parports/index.md) ## [Partner application development](partnerapps/index.md) ## [PCI drivers](pci/index.md) ## [PCMCIA drivers](pcmcia/index.md) @@ -32,6 +38,7 @@ ## [Print device drivers](print/index.md) ## [SD card bus drivers](sd/index.md) ## [Sensor drivers](sensors/index.md) +## [Serial port drivers](serports/index.md) ## [Smartcard device drivers](smartcard/index.md) ## [SPB drivers](spb/index.md) ## [Storage device drivers](storage/index.md) diff --git a/windows-driver-docs-pr/acpi/TOC.md b/windows-driver-docs-pr/acpi/TOC.md index 630a1d77be..7edbd5a2ea 100644 --- a/windows-driver-docs-pr/acpi/TOC.md +++ b/windows-driver-docs-pr/acpi/TOC.md @@ -17,4 +17,12 @@ ### [Enumerating Child Devices and Control Methods](enumerating-child-devices-and-control-methods.md) #### [Sending an IOCTL_ACPI_ENUM_CHILDREN Request](sending-an-ioctl-acpi-enum-children-request.md) ### [Control Method Macros](control-method-macros.md) - +#### [ACPI_METHOD_SET_ARGUMENT_INTEGER](acpi-method-set-argument-integer.md) +#### [ACPI_METHOD_SET_ARGUMENT_STRING](acpi-method-set-argument-string.md) +#### [ACPI_METHOD_SET_ARGUMENT_BUFFER](acpi-method-set-argument-buffer.md) +#### [ACPI_ENUM_CHILD_NEXT](acpi-enum-child-next.md) +#### [ACPI_ENUM_CHILD_LENGTH_FROM_CHILD](acpi-enum-child-length-from-child.md) +#### [ACPI_METHOD_ARGUMENT_LENGTH](acpi-method-argument-length.md) +#### [ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT](acpi-method-argument-length-from-argument.md) +#### [ACPI_METHOD_NEXT_ARGUMENT](acpi-method-next-argument.md) +#### [ACPI_MANIPULATE_LOCK_BUFFER](acpi-manipulate-lock-buffer.md) 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 new file mode 100644 index 0000000000..54f1b12f8a --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-enum-child-length-from-child.md @@ -0,0 +1,84 @@ +--- +title: ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro +author: windows-driver-content +description: The ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro calculates the size, in bytes, of a variable-length ACPI_ENUM_CHILD structure. +ms.assetid: 62be7cb5-4b71-4b8e-bad5-807623cd812a +keywords: +- ACPI_ENUM_CHILD_LENGTH_FROM_CHILD macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_ENUM\_CHILD\_LENGTH\_FROM\_CHILD macro + + +The ACPI\_ENUM\_CHILD\_LENGTH\_FROM\_CHILD macro calculates the size, in bytes, of a variable-length [**ACPI\_ENUM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536109) structure. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_ENUM_CHILD_LENGTH_FROM_CHILD( +   Child +); +``` + +Parameters +---------- + +*Child* +A pointer to a structure of type ACPI\_ENUM\_CHILD for which to calculate the size, in bytes, of the structure. + +Return value +------------ + +The size, in bytes, of the ACPI\_ENUM\_CHILD structure that *Child* points to. + +Remarks +------- + +A driver can use this macro to calculate the size, in bytes, of the ACPI\_ENUM\_CHILD structures in an [**ACPI\_ENUM\_CHILDREN\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536112) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows Vista and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_ENUM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536109) + +[**ACPI\_ENUM\_CHILDREN\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536112) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_ENUM_CHILD_LENGTH_FROM_CHILD%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/acpi/acpi-enum-child-next.md b/windows-driver-docs-pr/acpi/acpi-enum-child-next.md new file mode 100644 index 0000000000..5edbc600ca --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-enum-child-next.md @@ -0,0 +1,86 @@ +--- +title: ACPI_ENUM_CHILD_NEXT macro +author: windows-driver-content +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. +ms.assetid: 1ff37770-b0ea-4275-9568-611ec125a0b6 +keywords: +- ACPI_ENUM_CHILD_NEXT macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_ENUM\_CHILD\_NEXT macro + + +The ACPI\_ENUM\_CHILD\_NEXT macro calculates a pointer to the next [**ACPI\_ENUM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536109) structure in an array of variable length ACPI\_ENUM\_CHILD structures. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_ENUM_CHILD_NEXT( +   Child +); +``` + +Parameters +---------- + +*Child* +A pointer to a variable of type ACPI\_ENUM\_CHILD for which to return a nonaligned pointer to the next ACPI\_ENUM\_CHILD structure in an array of variable-length ACPI\_ENUM\_CHILD structures. + +Return value +------------ + +A pointer to the next ACPI\_ENUM\_CHILD structure in an array of variable-length ACPI\_ENUM\_CHILD structures. + +Remarks +------- + +After a driver uses an [**IOCTL\_ACPI\_ENUM\_CHILDREN**](https://msdn.microsoft.com/library/windows/hardware/ff536147) request to retrieve an array of child device names in an [**ACPI\_ENUM\_CHILDREN\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536112) request, the driver can use this macro to determine a sequence of pointers to the variable-length ACPI\_ENUM\_CHILD structures in the **Children** array that the output buffer contains. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows Vista and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_ENUM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536109) + +[**ACPI\_ENUM\_CHILDREN\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536112) + +[**IOCTL\_ACPI\_ENUM\_CHILDREN**](https://msdn.microsoft.com/library/windows/hardware/ff536147) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_ENUM_CHILD_NEXT%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md b/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md new file mode 100644 index 0000000000..637b5f2021 --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-manipulate-lock-buffer.md @@ -0,0 +1,55 @@ +--- +title: ACPI_MANIPULATE_LOCK_BUFFER structure +author: windows-driver-content +description: The ACPI_MANIPULATE_LOCK_BUFFER macro is reserved for internal use only with an IOCTL_ACPI_ACQUIRE_GLOBAL_LOCK and IIOCTL_ACPI_RELEASE_GLOBAL_LOCK. +ms.assetid: 7af24f15-66e1-4f68-8d8a-d22617616806 +keywords: +- ACPI_MANIPULATE_LOCK_BUFFER structure ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_MANIPULATE\_LOCK\_BUFFER structure + + +The ACPI\_MANIPULATE\_LOCK\_BUFFER macro is reserved for internal use only with an [**IOCTL\_ACPI\_ACQUIRE\_GLOBAL\_LOCK**](https://msdn.microsoft.com/library/windows/hardware/ff536144) and [**IOCTL\_ACPI\_RELEASE\_GLOBAL\_LOCK**](https://msdn.microsoft.com/library/windows/hardware/ff536150). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows Vista and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**IOCTL\_ACPI\_ACQUIRE\_GLOBAL\_LOCK**](https://msdn.microsoft.com/library/windows/hardware/ff536144) + +[**IOCTL\_ACPI\_RELEASE\_GLOBAL\_LOCK**](https://msdn.microsoft.com/library/windows/hardware/ff536150) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_MANIPULATE_LOCK_BUFFER%20structure%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + 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 new file mode 100644 index 0000000000..71689f3578 --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-argument-length-from-argument.md @@ -0,0 +1,82 @@ +--- +title: ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro +author: windows-driver-content +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. +ms.assetid: 46fe0382-1496-49eb-988d-2007885d2210 +keywords: +- ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_ARGUMENT\_LENGTH\_FROM\_ARGUMENT macro + + +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**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT( +   Argument +); +``` + +Parameters +---------- + +*Argument* +A pointer to an ACPI\_METHOD\_ARGUMENT structure. + +Return value +------------ + +The size, in bytes, of the data that is contained in the **Data** array of the ACPI\_METHOD\_ARGUMENT structure that *Argument* points to. + +Remarks +------- + +A driver can use this macro to determine the size, in bytes, of the data in the **Data** array of an ACPI\_METHOD\_ARGUMENT structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_ARGUMENT_LENGTH_FROM_ARGUMENT%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/acpi/acpi-method-argument-length.md b/windows-driver-docs-pr/acpi/acpi-method-argument-length.md new file mode 100644 index 0000000000..f71d2f06ad --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-argument-length.md @@ -0,0 +1,82 @@ +--- +title: ACPI_METHOD_ARGUMENT_LENGTH macro +author: windows-driver-content +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. +ms.assetid: 8329c2eb-a787-4590-8de9-95078bbb85da +keywords: +- ACPI_METHOD_ARGUMENT_LENGTH macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_ARGUMENT\_LENGTH macro + + +The ACPI\_METHOD\_ARGUMENT\_LENGTH macro calculates the size, in bytes, of a variable-length [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure that contains data of a specified size, in bytes. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_METHOD_ARGUMENT_LENGTH( +   DataLength +); +``` + +Parameters +---------- + +*DataLength* +The size, in bytes, of data in the **Data** array of an ACPI\_METHOD\_ARGUMENT structure. + +Return value +------------ + +The size, in bytes, of a variable-length ACPI\_METHOD\_ARGUMENT structure that can contains a **Data** array whose size, in bytes, is *DataLength*. + +Remarks +------- + +A driver can use this macro to calculate the required size, in bytes, of a variable-length ACPI\_METHOD\_ARGUMENT structure that can contain a **Data** array of a specified size, in bytes. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_ARGUMENT_LENGTH%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/acpi/acpi-method-next-argument.md b/windows-driver-docs-pr/acpi/acpi-method-next-argument.md new file mode 100644 index 0000000000..0b7c2d42c9 --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-next-argument.md @@ -0,0 +1,82 @@ +--- +title: ACPI_METHOD_NEXT_ARGUMENT macro +author: windows-driver-content +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. +ms.assetid: c723b11b-1657-4a78-a6a1-26bd916604a4 +keywords: +- ACPI_METHOD_NEXT_ARGUMENT macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_NEXT\_ARGUMENT macro + + +The ACPI\_METHOD\_NEXT\_ARGUMENT structure returns a pointer to the next [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure in an array of ACPI\_METHOD\_ARGUMENT structures. + +Syntax +------ + +```ManagedCPlusPlus + ACPI_METHOD_NEXT_ARGUMENT( +   Argument +); +``` + +Parameters +---------- + +*Argument* +A pointer to an ACPI\_METHOD\_ARGUMENT structure in an array of ACPI\_METHOD\_ARGUMENT structures. + +Return value +------------ + +A pointer to the next ACPI\_METHOD\_ARGUMENT structure in an array of ACPI\_METHOD\_ARGUMENT structures. + +Remarks +------- + +Given a pointer to an ACPI\_METHOD\_ARGUMENT structure in an array of such structures, a driver can use this macro to calculate a pointer to the next structure in the array, if one exists. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_NEXT_ARGUMENT%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + 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 new file mode 100644 index 0000000000..ef6ec4cfcd --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-buffer.md @@ -0,0 +1,90 @@ +--- +title: ACPI_METHOD_SET_ARGUMENT_BUFFER macro +author: windows-driver-content +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. +ms.assetid: 1f335814-fa9f-45c6-b970-10884e971ec1 +keywords: +- ACPI_METHOD_SET_ARGUMENT_BUFFER macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_SET\_ARGUMENT\_BUFFER macro + + +The ACPI\_METHOD\_SET\_ARGUMENT\_BUFFER macro sets the members of an [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure for custom data that is supplied in a data buffer. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_METHOD_SET_ARGUMENT_BUFFER( +   Argument, +   BuffData, +   BuffLength +); +``` + +Parameters +---------- + +*Argument* +A pointer to an ACPI\_METHOD\_ARGUMENT structure. + +*BuffData* +A pointer to a data buffer that contains custom data. + +*BuffLength* +The size, in bytes, of the custom data. + +Return value +------------ + +This macro does not return a value. + +Remarks +------- + +A driver can use this macro to set the members of an ACPI\_METHOD\_ARGUMENT structure that supplies custom data. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_SET_ARGUMENT_BUFFER%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + 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 new file mode 100644 index 0000000000..7cc1c85b2c --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-integer.md @@ -0,0 +1,86 @@ +--- +title: ACPI_METHOD_SET_ARGUMENT_INTEGER macro +author: windows-driver-content +description: The ACPI_METHOD_SET_ARGUMENT_INTEGER macro sets the members of an ACPI_METHOD_ARGUMENT structure for a single integer value. +ms.assetid: a79f9149-0ffe-483f-a45e-427b05ff0a11 +keywords: +- ACPI_METHOD_SET_ARGUMENT_INTEGER macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_SET\_ARGUMENT\_INTEGER macro + + +The ACPI\_METHOD\_SET\_ARGUMENT\_INTEGER macro sets the members of an [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure for a single integer value. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_METHOD_SET_ARGUMENT_INTEGER( +   MethodArgument, +   IntData +); +``` + +Parameters +---------- + +*MethodArgument* +A pointer to an ACPI\_METHOD\_ARGUMENT structure. + +*IntData* +An integer value of type ULONG. + +Return value +------------ + +This macro does not return a value. + +Remarks +------- + +A driver can use this macro to set the members of an ACPI\_METHOD\_ARGUMENT structure that supplies a single integer value of type ULONG. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_SET_ARGUMENT_INTEGER%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + 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 new file mode 100644 index 0000000000..e6c8687e8a --- /dev/null +++ b/windows-driver-docs-pr/acpi/acpi-method-set-argument-string.md @@ -0,0 +1,86 @@ +--- +title: ACPI_METHOD_SET_ARGUMENT_STRING macro +author: windows-driver-content +description: The ACPI_METHOD_SET_ARGUMENT_STRING macro sets the members of an ACPI_METHOD_ARGUMENT structure for a string value. +ms.assetid: e0c037a9-65b6-4d6a-9ed6-d9296c14df07 +keywords: +- ACPI_METHOD_SET_ARGUMENT_STRING macro ACPI Devices +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI\_METHOD\_SET\_ARGUMENT\_STRING macro + + +The ACPI\_METHOD\_SET\_ARGUMENT\_STRING macro sets the members of an [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structure for a string value. + +Syntax +------ + +```ManagedCPlusPlus +void ACPI_METHOD_SET_ARGUMENT_STRING( +   Argument, +   StrData +); +``` + +Parameters +---------- + +*Argument* +A pointer to an ACPI\_METHOD\_ARGUMENT structure. + +*StrData* +A pointer to a NULL-terminated ASCII string. + +Return value +------------ + +This macro does not return a value. + +Remarks +------- + +A driver can use this macro to set the members of an ACPI\_METHOD\_ARGUMENT structure that supplies a NULL-terminated ASCII string. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Windows 2000 and later versions of Windows.

Header

Acpiioct.h (include Acpiioct.h)
+ +## See also + + +[**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bacpi\acpi%5D:%20ACPI_METHOD_SET_ARGUMENT_STRING%20macro%20%20RELEASE:%20%287/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/acpi/control-method-macros.md b/windows-driver-docs-pr/acpi/control-method-macros.md index e5b605e716..a1d761e610 100644 --- a/windows-driver-docs-pr/acpi/control-method-macros.md +++ b/windows-driver-docs-pr/acpi/control-method-macros.md @@ -17,25 +17,25 @@ ms.technology: windows-devices A driver can use the following macros to set input arguments that are used with the ACPI IOCTLs that [evaluate control methods](evaluating-acpi-control-methods.md): -[**ACPI\_METHOD\_SET\_ARGUMENT\_INTEGER**](https://msdn.microsoft.com/library/windows/hardware/ff536130) +[**ACPI\_METHOD\_SET\_ARGUMENT\_INTEGER**](acpi-method-set-argument-integer.md) -[**ACPI\_METHOD\_SET\_ARGUMENT\_STRING**](https://msdn.microsoft.com/library/windows/hardware/ff536131) +[**ACPI\_METHOD\_SET\_ARGUMENT\_STRING**](acpi-method-set-argument-string.md) -[**ACPI\_METHOD\_SET\_ARGUMENT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536129) +[**ACPI\_METHOD\_SET\_ARGUMENT\_BUFFER**](acpi-method-set-argument-buffer.md) The ACPI IOCTLs that evaluate control methods return output arguments in the **Argument** member of an [**ACPI\_EVAL\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536123) structure, where the **Argument** member is an array of [**ACPI\_METHOD\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536125) structures. A driver can use the following macros to help process an array of ACPI\_METHOD\_ARGUMENT structures: -[**ACPI\_METHOD\_ARGUMENT\_LENGTH**](https://msdn.microsoft.com/library/windows/hardware/ff536126) +[**ACPI\_METHOD\_ARGUMENT\_LENGTH**](acpi-method-argument-length.md) -[**ACPI\_METHOD\_ARGUMENT\_LENGTH\_FROM\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536127) +[**ACPI\_METHOD\_ARGUMENT\_LENGTH\_FROM\_ARGUMENT**](acpi-method-argument-length-from-argument.md) -[**ACPI\_METHOD\_NEXT\_ARGUMENT**](https://msdn.microsoft.com/library/windows/hardware/ff536128) +[**ACPI\_METHOD\_NEXT\_ARGUMENT**](acpi-method-next-argument.md) An [**IOCTL\_ACPI\_ENUM\_CHILDREN**](https://msdn.microsoft.com/library/windows/hardware/ff536147) request retrieves the path and name of child objects in the namespace of the device to which the request is sent. The ACPI driver returns the full path and name of the enumerated object beginning with the root of the ACPI namespace. The path and name of the child objects are returned in the **Children** member of an [**ACPI\_ENUM\_CHILDREN\_OUTPUT\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff536112) structure, where the **Children** member is an array of [**ACPI\_ENUM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536109) structures. A driver can use the following macros to help process an array of ACPI\_ENUM\_CHILD structures: -[**ACPI\_ENUM\_CHILD\_NEXT**](https://msdn.microsoft.com/library/windows/hardware/ff536114) +[**ACPI\_ENUM\_CHILD\_NEXT**](acpi-enum-child-next.md) -[**ACPI\_ENUM\_CHILD\_LENGTH\_FROM\_CHILD**](https://msdn.microsoft.com/library/windows/hardware/ff536113) +[**ACPI\_ENUM\_CHILD\_LENGTH\_FROM\_CHILD**](acpi-enum-child-length-from-child.md)   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 f23bc07522..4af294845c 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 +title: Sending an IOCTL_ACPI_ENUM_CHILDREN Request author: windows-driver-content -description: Sending an IOCTL\_ACPI\_ENUM\_CHILDREN Request +description: Sending an IOCTL_ACPI_ENUM_CHILDREN Request ms.assetid: cbad53dd-4320-4920-9d16-231d0aaae839 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/audio/TOC.md b/windows-driver-docs-pr/audio/TOC.md index 28dd11725b..efe6effdff 100644 --- a/windows-driver-docs-pr/audio/TOC.md +++ b/windows-driver-docs-pr/audio/TOC.md @@ -126,6 +126,8 @@ ##### [Obtaining an HDAUDIO_BUS_INTERFACE_V2 DDI Object](obtaining-an-hdaudio-bus-interface-v2-ddi-object.md) ##### [Obtaining an HDAUDIO_BUS_INTERFACE_BDL DDI Object](obtaining-an-hdaudio-bus-interface-bdl-ddi-object.md) # [WDM Audio Support in Different Versions of Windows](wdm-audio-support-in-different-versions-of-windows.md) +## [Implementing Audio Module Communication](implementing-audio-module-communication.md) +### [Configure and query audio device modules](configure-and-query-audiodevicemodules.md) ## [Low Latency Audio](low-latency-audio.md) ## [Voice Activation](voice-activation.md) ## [Audio Hardware Resource Management](audio-hardware-resource-management.md) 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 92547c438a..6c921788eb 100644 --- a/windows-driver-docs-pr/audio/audio-processing-object-architecture.md +++ b/windows-driver-docs-pr/audio/audio-processing-object-architecture.md @@ -27,7 +27,7 @@ Audio processing objects (APOs), provide software based digital signal processin **Software APOs vs. Hardware DSP** -A hardware digital signal processor (DSP) is a specialized microprocessor (or a SIP block), with its architecture optimized for the operational needs of digital signal processing. There can be significant advantageous to implement audio processing in purpose built hardware vs. using a software APO. One advantage is that the CPU use and associated power consumption may be lower with a hardware implemented DSP. +A hardware digital signal processor (DSP) is a specialized microprocessor (or a SIP block), with its architecture optimized for the operational needs of digital signal processing. There can be significant advantages to implement audio processing in purpose built hardware vs. using a software APO. One advantage is that the CPU use and associated power consumption may be lower with a hardware implemented DSP. There are other advantages and disadvantages to consider, specific your projects goals and constraints that you will want to consider before implementing a software based APO. @@ -122,8 +122,6 @@ This diagram shows the possible locations for stream (SFX), mode (MFX) and endpo It is possible to configure multiple APO based effects to work with different applications. -**Software Mode Effects and Hardware Endpoint Effects for Render and Capture** - This diagram illustrates how multiple applications can access multiple combinations of stream, mode and endpoint APO effects. All of the APOs are COM based and run in user mode. In this scenario, none of the effects are running in hardware or in kernel mode. ![diagram showing how multiple applications can access multiple combinations of stream, mode and endpoint apo effects](images/audio-apo-software-effects-1.png) diff --git a/windows-driver-docs-pr/audio/audio-universal-drivers.md b/windows-driver-docs-pr/audio/audio-universal-drivers.md index b0d7084069..00486315b6 100644 --- a/windows-driver-docs-pr/audio/audio-universal-drivers.md +++ b/windows-driver-docs-pr/audio/audio-universal-drivers.md @@ -14,7 +14,7 @@ ms.technology: windows-devices In Windows 10 you can write a universal audio driver that will work across many types of hardware. This topics discusses the benefits of this approach as well as the differences between different platforms. In addition to the Universal Windows drivers for audio, Windows continues to support previous audio driver technologies, such as WDM. -## Getting Started with Universal Windows drivers for Audio +## Getting Started with Universal Windows drivers for Audio IHVs can develop a Universal Windows driver that works on all devices (desktops, laptops, tablets, phones). This can reduces development time and cost for initial development and later code maintenance. @@ -27,7 +27,7 @@ These tools are available to develop Universal Windows driver support: - Updated DDI reference documentation: The DDI reference documentation is being updated to indicate which DDIs are supported by Universal Windows drivers. For more information, see [Audio Devices Reference](https://msdn.microsoft.com/library/windows/hardware/ff536192). -## Create a Universal Audio Driver +## Create a Universal Audio Driver For step-by-step guidance, see [Getting Started with Universal Windows Drivers](https://msdn.microsoft.com/windows-drivers/develop/getting_started_with_universal_drivers). Here is a summary of the steps: @@ -40,12 +40,12 @@ For step-by-step guidance, see [Getting Started with Universal Windows Drivers]( 4. Build, install, deploy, and debug the driver for Windows 10 for desktop editions or Windows 10 Mobile. -## Sample Code +## Sample Code Sysvad and SwapAPO have been converted to be Universal Windows driver samples. For more information, see [Sample Audio Drivers](sample-audio-drivers.md). -## Available Programming Interfaces for Universal Windows drivers for Audio +## Available Programming Interfaces for Universal Windows drivers for Audio Starting with Windows 10, the driver programming interfaces are part of OneCoreUAP-based editions of Windows. By using that common set, you can write a Universal Windows driver. Those drivers will run on both Windows 10 for desktop editions and Windows 10 Mobile, and other Windows 10 versions. @@ -66,7 +66,7 @@ The following DDIs to are available when working with universal audio drivers. - [Port Class Audio Driver Reference](https://msdn.microsoft.com/library/windows/hardware/ff537764) -## Convert an Existing Audio Driver to a Universal Windows driver +## Convert an Existing Audio Driver to a Universal Windows driver Follow this process to convert an existing audio driver to a Universal Windows driver. @@ -81,7 +81,109 @@ Follow this process to convert an existing audio driver to a Universal Windows d 5. Replace those calls with alternate calls, or create a code workaround, or write a new driver. -## Building the Sysvad Universal Audio Sample for Windows 10 Desktop + +## Creating a componentized audio driver installation + +### Overview + +To create a smoother and more reliable install experience and to better support component servicing, divide the driver installation process into the following components. + +- DSP (if present) and Codec +- APO +- OEM Customizations + +Optionally, separate INF files can be used for the DSP and Codec. + +This diagram summarizes a componentized audio installation. + +![The componentized audio stack showing DSP driver codec and APOs](images/audio-componentized-stack-diagram.png) + +A separate extension INF file is used for each software component. For more information, see +[Using an Extension INF File](https://docs.microsoft.com/windows-hardware/drivers/install/using-an-extension-inf-file). + +An extension INF file must be a universal INF file. For more information, see [Using a Universal INF File](https://docs.microsoft.com/windows-hardware/drivers/install/using-a-universal-inf-file). + +For information about adding software using INF files, see [Using a Component INF File](https://docs.microsoft.com/windows-hardware/drivers/install/using-a-component-inf-file). + + +### 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. + +| File name | Description | +|----------------------------------------|--------------------------------------------------------------------------------| +| ComponentizedAudioSample.inf | The base componentized sample audio INF file. | +| ComponentizedAudioSampleExtension.inf | The extension driver for the sysvad base with additional OEM customizations. | +| ComponentizedApoSample.inf | An APO sample extension INF file. | + +The traditional INF files continue to be available in the SYSVAD sample. + +| File name | Description | +|--------------------------------|--------------------------------------------------------------------------------| +| tabletaudiosample.inf | A desktop monolitic INF file that contains all of the information needed to install the driver. | +| phoneaudiosample.inf | A phone monolitic INF file that contains all of the information needed to install the driver. | + + + +### APO vendor specific tuning parameters and feature configuration + +All APO vendor system specific settings, parameters, and tuning values must be installed via the audio OEM extension INF package. In many cases, this can be performed in a simple manner with the AddReg directive. In more complex cases, a tuning file can be used.  +  +Base driver packages must not depend on these customizations in order to function (although of course functionality may be reduced).  + + +### Programmatically launching UWP Hardware Support Apps + +To programmatically launch a UWP Hardware Support App, based on a driver event (for example, when a new audio device is connected), use the Windows Shell APIs. The Windows 10 Shell APIs support a method for launching UWP UI based on resource activation, or directly via [IApplicationActivationManager](https://msdn.microsoft.com/library/windows/desktop/hh706903.aspx). You can find more details on automated launching for UWP applications in [Automate launching Windows 10 UWP apps](https://docs.microsoft.com/windows/uwp/xbox-apps/automate-launching-uwp-apps#launch-activation).  + +### APO and device driver vendor use of the AudioModules API + +The Audio Modules API/DDI is designed to standardize the communication transport (but not the protocol) for commands passed between a UWP application or user-mode service to a kernel driver module or DSP processing block. Audio Modules requires a driver implementing the correct DDI to support module enumeration and communication. The commands are passed as binary and interpretation/definition is left up to the creator.  +  +Audio Modules is not currently designed to facilitate direct communication between a UWP app and a SW APO running in the audio engine. + +For more information about audio modules, see [Implementing Audio Module Communication](https://docs.microsoft.com/windows-hardware/drivers/audio/implementing-audio-module-communication) and [Configure and query audio device modules](https://docs.microsoft.com/windows-hardware/drivers/audio/configure-and-query-audiodevicemodules). + + +### APO HWID strings construction  +  +APO Hardware IDs incorporate both standard information and vendor-defined strings. + +They are constructed as follows: + +``` +APO\VEN_v(4)&AID_a(4)&SUBSYS_ n(4)s(4) &REV_r(4) +APO\VEN_v(4)&AID_a(4)&SUBSYS_ n(4)s(4) +APO\VEN_v(4)&AID_a(4) +``` + +Where: + +- v(4) is the 4-character identifier for the APO device vendor. This will be managed by Microsoft.  +- a(4) is the 4-character identifier for the APO, defined by the APO vendor.  +- n(4) is the 4-character PCI SIG-assigned identifier for the vendor of the subsystem for the parent device. This is typically the OEM identifier. +- s(4) is the 4-character vendor-defined subsystem identifier for the parent device. This is typically the OEM product identifier. + + +### Plug and Play INF version and date evaluation for driver update + +The Windows Plug and Play system evaluates the date and the driver version to determine which drive to install when multiple drivers exist. For more information, see [How Windows Ranks Drivers](https://docs.microsoft.com/windows-hardware/drivers/install/how-setup-ranks-drivers--windows-vista-and-later-). + +To allow the latest driver to be used, be sure and update the date and version, for each new version of the driver. + + +### APO driver registry key + +For third party-defined audio driver/APO registry keys, use the HKR with the exception of HKLM\System\CurrentControlSet. +  + +### Use a Windows Service to facilitate UWP <-> APO communication +  +A Windows Service is not strictly required for management of user-mode components like APOs, however, if your design includes an RPC server to facilitate UWP <-> APO communication, we recommend implementing that functionality in a Windows Service that then controls the APO running in the audio engine.  + + + +## Building the Sysvad Universal Audio Sample for Windows 10 Desktop Complete the following steps to build the sysvad sample for Windows 10 desktop. @@ -127,7 +229,7 @@ Follow these steps to install the driver using the PnpUtil on the target system. 5. Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the Microsoft Virtual Audio Device (WDM) - Sysvad Sample driver. -## Building the Sysvad Universal Audio Sample for Windows 10 Mobile +## Building the Sysvad Universal Audio Sample for Windows 10 Mobile Complete the following steps to build the sysvad sample for Windows 10 Mobile. diff --git a/windows-driver-docs-pr/audio/configure-and-query-audiodevicemodules.md b/windows-driver-docs-pr/audio/configure-and-query-audiodevicemodules.md new file mode 100644 index 0000000000..363dca621f --- /dev/null +++ b/windows-driver-docs-pr/audio/configure-and-query-audiodevicemodules.md @@ -0,0 +1,141 @@ +--- +Description: This article shows how to send commands and receive change notifications from audio device modules. from a Universal Windows Platform (UWP) app. +ms.assetid: AA053196-F331-4CBE-B032-4E9CBEAC699C +title: Configure and query audio device modules +label: Configure and query audio device modules +template: +ms.author: drewbat +ms.date: 06/28/2017 +ms.topic: article +ms.prod: windows +ms.technology: uwp +keywords: windows 10, uwp +--- + +# Configure and query audio device modules + +This article shows how to send commands and receive change notifications from audio device modules from a UWP app. An audio device module may be a hardware effect processing unit or any other audio configuration module defined by an audio driver. This feature was designed to enable module providers to create UWP apps that allow users to control and get status information from an audio processing module running in a DSP. In order to use the audio device module APIs shown in this article, you must specify the restricted *audioDeviceConfiguration* capability in your app package manifest. + +## Get an instance of the AudioDeviceModulesManager class +All audio device module operations shown in this article begin by obtaining an instance of the **[AudioDeviceModulesManager](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulesmanager)**. Do this by first calling the static **[GetDefaultAudioRenderId](https://docs.microsoft.com/uwp/api/windows.media.devices.mediadevice#Windows_Media_Devices_MediaDevice_GetDefaultAudioRenderId_Windows_Media_Devices_AudioDeviceRole_)** method of the **[MediaDevice](https://docs.microsoft.com/uwp/api/windows.media.devices.mediadevice)** class. This returns the ID of the default audio render device, which is then passed into the constructor for **AudioDeviceModulesManager** to create an instance of the class that is associated with the audio device. + +C# +```csharp +var endpointId = MediaDevice.GetDefaultAudioRenderId(AudioDeviceRole.Default); +var audioModuleManager = new AudioDeviceModulesManager(endpointId); +``` + +## Query for installed audio device modules + +Query for all installed audio device modules by calling the **[FindAll](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulesmanager#Windows_Media_Devices_AudioDeviceModulesManager_FindAll)** of the the **[AudioDeviceModulesManager](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulesmanager)** class. Query for a specific set of audio device modules by calling **[FindAllById](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulesmanager#Windows_Media_Devices_AudioDeviceModulesManager_FindAllById_System_String_)** and passing in the ID of the requested modules. The following example defines an ID for a set of modules, calls **FindAllById** to retrieve a list of **[AudioDeviceModule](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodule)** objects, and then prints the details of each module to the debug output. + +C# +```csharp +public const string Contoso_AudioDeviceModuleId = "F72E09C3-FEBA-4C50-93BE-2CA56123AF09"; +``` + +C# +```csharp +var endpointId = MediaDevice.GetDefaultAudioRenderId(AudioDeviceRole.Default); +var audioModuleManager = new AudioDeviceModulesManager(endpointId); +var modules = audioModuleManager.FindAllById(Contoso_AudioDeviceModuleId); + +foreach (var module in modules) +{ + var classId = module.ClassId; + var name = module.DisplayName; + var minorVersion = module.MinorVersion; + var majorVersion = module.MajorVersion; + var instanceId = module.InstanceId; + + Debug.WriteLine($"{classId} : {name} : {minorVersion} : {majorVersion} : {instanceId}"); +} +``` +## Send a command to an audio device module and receive result data +Send commands to an audio device module by calling **[SendCommandAsync](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodule#Windows_Media_Devices_AudioDeviceModule_SendCommandAsync_Windows_Storage_Streams_IBuffer_)** on the **[AudioDeviceModule](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodule)** object. The **SendCommandAsync** method takes a byte array as an argument. Typically this byte array contains a command identifier followed by the data associated with the command, but the command format and values are entirely vendor-defined and are treated as transparent by the system. + +The **SendCommandAsync** method returns an asynchronous operation that, upon completion, returns a **[ModuleCommandResult](https://docs.microsoft.com/uwp/api/windows.media.devices.modulecommandresult)** object representing the result of the command. The **[Status](https://docs.microsoft.com/uwp/api/windows.media.devices.modulecommandresult#Windows_Media_Devices_ModuleCommandResult_Status)** property contains an enumeration value that indicates whether the system was able to execute the command. This does not necessarily indicate that the audio device module was able to execute the command successfully. The **[Result](https://docs.microsoft.com/uwp/api/windows.media.devices.modulecommandresult#Windows_Media_Devices_ModuleCommandResult_Result)** property contains a byte array that is returned by the audio device module to indicate the status of the command. Typically, this will be a value that indicates success or failure followed by the data result of the command. As with module commands, module response formats and values are vendor-defined. + +The following example calls **FindAllAsync** to retrieve a set of audio device modules. A **[DataWriter](https://docs.microsoft.com/uwp/api/windows.storage.streams.datawriter)** is used to create a byte array containing an example command and data. **SendCommandAsync** is called to send the command buffer and, after the asynchronous operation completes, a **ModuleCommandResult** is returned. If the command execution was successful, a **[DataReader](https://docs.microsoft.com/uwp/api/windows.storage.streams.datareader)** is first used to read an integer status value returned from the module. If this value is the vendor-defined success value, the rest of the result data is read and used by the app, such as to update the UI. + + +C# +```csharp +public const byte Contoso_ReverbLevel_Command = 30; +public const byte Contoso_SendCommand_Success = 99; +``` + +C# +```csharp +var endpointId = MediaDevice.GetDefaultAudioRenderId(AudioDeviceRole.Default); +var audioModuleManager = new AudioDeviceModulesManager(endpointId); +var modules = audioModuleManager.FindAllById(Contoso_AudioDeviceModuleId); + +foreach (var module in modules) +{ + var writer = new Windows.Storage.Streams.DataWriter(); + writer.WriteByte(Contoso_ReverbLevel_Command); + writer.WriteByte(100); + + var command = writer.DetachBuffer(); + + var result = await module.SendCommandAsync(command); + + if (result.Status == SendCommandStatus.Success) + { + using (DataReader reader = DataReader.FromBuffer(result.Result)) + { + int bufferStatus = reader.ReadInt32(); + if (bufferStatus == Contoso_SendCommand_Success) + { + byte[] data = { 0, 0 }; + reader.ReadBytes(data); + // Do something with returned data, such as update UI + } + } + } +} +``` + +## Receive notifications when audio device modules are modified +Apps can receive notifications when an audio device module has been updated by registering for the **[ModuleNotificationReceived](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulesmanager#Windows_Media_Devices_AudioDeviceModulesManager_ModuleNotificationReceived)** event. + +C# +```csharp +var endpointId = MediaDevice.GetDefaultAudioRenderId(AudioDeviceRole.Default); +var audioModuleManager = new AudioDeviceModulesManager(endpointId); + +audioModuleManager.ModuleNotificationReceived += AudioModuleManager_ModuleNotificationReceived; +``` + +**ModuleNotificationReceived** will be raised when any audio device module associated with the current audio device is modified. To determine if the event is associated with a particular module, get an instance of **AudioDeviceModule** by accessing the **[Module](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulenotificationeventargs#Windows_Media_Devices_AudioDeviceModuleNotificationEventArgs_Module)** property of the **[AudioDeviceModuleNoticiationEventArgs](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulenotificationeventargs)** passed into the event handler, and then checking the **[ClassId](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodule#Windows_Media_Devices_AudioDeviceModule_ClassId)** property that identifies the module. The data associated with the event is passed as a byte array stored in the **[NotificationData](https://docs.microsoft.com/uwp/api/windows.media.devices.audiodevicemodulenotificationeventargs#Windows_Media_Devices_AudioDeviceModuleNotificationEventArgs_NotificationData)** property of the event args. As with commands and results, the format of the returned byte array is vendor-defined. In the example below, if the first byte of the notification data contains the example value for the module's reverb level setting, the data is read and used to update the UI. + +C# +```csharp +public const byte Contoso_ReverbLevel_Data = 25; +``` + +C# +```csharp +private void AudioModuleManager_ModuleNotificationReceived(AudioDeviceModulesManager sender, AudioDeviceModuleNotificationEventArgs args) +{ + if (args.Module.ClassId == Contoso_AudioDeviceModuleId) + { + // Get the coefficient data from the reverb module. + using (DataReader reader = DataReader.FromBuffer(args.NotificationData)) + { + // read notification data. + byte item = reader.ReadByte(); + + // if reverb coefficient data are changed. + if (item == Contoso_ReverbLevel_Data) + { + // read the new value + byte[] data = { 0 }; + reader.ReadBytes(data); + ReverbLevelSlider.Value = data[0]; + } + } + } +} +``` \ No newline at end of file diff --git a/windows-driver-docs-pr/audio/directmusic-ddi-overview.md b/windows-driver-docs-pr/audio/directmusic-ddi-overview.md index eb2b7c0546..fa38ef1e66 100644 --- a/windows-driver-docs-pr/audio/directmusic-ddi-overview.md +++ b/windows-driver-docs-pr/audio/directmusic-ddi-overview.md @@ -33,12 +33,15 @@ DirectMusic uses the following user-mode interfaces to control user-mode synthes [IDirectMusicSynth](https://msdn.microsoft.com/library/windows/hardware/ff536519) This is the user-mode interface for implementing custom software synths. + [IDirectMusicSynthSink](https://msdn.microsoft.com/library/windows/hardware/ff536520) This is the user-mode interface for implementing custom wave sinks in Microsoft DirectX 6.1 and DirectX 7. In DirectX 8 and later, DirectMusic always uses its private wave sink with a user-mode synth, and no public interface is supported for user-mode wave sinks. + [IKsControl](https://msdn.microsoft.com/library/windows/hardware/ff559766) DirectMusic uses this interface to access the properties of kernel-streaming drivers from user mode in DirectX 6.1 and later. + Kernel-mode terminology differs slightly from user-mode because of the port-miniport driver model (see [Introduction to Port Class](introduction-to-port-class.md)), which delegates generic kernel-streaming tasks to the [DMus port driver](dmus-port-driver.md) and assigns hardware-specific functions to the DMus miniport driver. The port and miniport drivers share responsibilities for the synth. The kernel-mode wave sink is part of the kernel-resident port driver. Unlike the user-mode wave sink in DirectX 6.1 and DirectX 7, the kernel-mode wave sink is not replaceable. Most of the work that is required to build a custom kernel-mode driver is in the writing of the miniport driver. In most cases, the miniport driver is the only component that the driver writer needs to implement to support a piece of hardware, or to implement a custom software synth for DirectMusic. Custom DMus miniport drivers use the following kernel-mode interfaces: diff --git a/windows-driver-docs-pr/audio/dmus-miniport-driver.md b/windows-driver-docs-pr/audio/dmus-miniport-driver.md index ba8e43263d..faebebe720 100644 --- a/windows-driver-docs-pr/audio/dmus-miniport-driver.md +++ b/windows-driver-docs-pr/audio/dmus-miniport-driver.md @@ -33,40 +33,51 @@ The miniport interface, [IMiniportDMus](https://msdn.microsoft.com/library/windo [**IMiniportDMus::Init**](https://msdn.microsoft.com/library/windows/hardware/ff536700) Initializes the miniport object. + [**IMiniportDMus::NewStream**](https://msdn.microsoft.com/library/windows/hardware/ff536701) Creates a new stream object. + [**IMiniportDMus::Service**](https://msdn.microsoft.com/library/windows/hardware/ff536702) Notifies the miniport driver of a request for service. + The stream interface, [IMXF](https://msdn.microsoft.com/library/windows/hardware/ff536782), inherits the methods in the **IUnknown** interface. **IMXF** provides the following additional methods: [**IMXF::ConnectOutput**](https://msdn.microsoft.com/library/windows/hardware/ff536785) Connects this stream object, which is a data source, to the **IMXF** interface of another stream object, which is a data sink. + [**IMXF::DisconnectOutput**](https://msdn.microsoft.com/library/windows/hardware/ff536787) Disconnects this stream object from the **IMXF** interface of another stream object that is a data sink. + [**IMXF::PutMessage**](https://msdn.microsoft.com/library/windows/hardware/ff536791) Passes a [**DMUS\_KERNEL\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff536340) structure to the data sink. + [**IMXF::SetState**](https://msdn.microsoft.com/library/windows/hardware/ff536792) Sets the state of the stream. + In addition, the DMus miniport driver's [ISynthSinkDMus](https://msdn.microsoft.com/library/windows/hardware/ff537011) interface provides DLS functionality for software synthesizers. **ISynthSinkDMus** inherits the methods in base interface **IMXF**. **ISynthSinkDMus** provides the following additional methods: [**ISynthSinkDMus::RefTimeToSample**](https://msdn.microsoft.com/library/windows/hardware/ff537013) Converts a reference time to a sample time. + [**ISynthSinkDMus::Render**](https://msdn.microsoft.com/library/windows/hardware/ff537015) Renders wave data into a buffer for the wave sink. + [**ISynthSinkDMus::SampleToRefTime**](https://msdn.microsoft.com/library/windows/hardware/ff537018) Converts a sample time to a reference time. + [**ISynthSinkDMus::SyncToMaster**](https://msdn.microsoft.com/library/windows/hardware/ff537019) Synchronizes the sample clock to the master clock. + The port driver's wave sink calls **ISynthSinkDMus::Render** to read the wave PCM data that the synthesizer generates from its MIDI input stream. For more information about the wave sink, see [A Wave Sink for Kernel-Mode Software Synthesizers](a-wave-sink-for-kernel-mode-software-synthesizers.md). The miniport driver calls the following interfaces on the DMus port driver: diff --git a/windows-driver-docs-pr/audio/dmus-port-driver.md b/windows-driver-docs-pr/audio/dmus-port-driver.md index 33c3450d7f..9deec32ed9 100644 --- a/windows-driver-docs-pr/audio/dmus-port-driver.md +++ b/windows-driver-docs-pr/audio/dmus-port-driver.md @@ -28,6 +28,7 @@ The DMus port driver exposes an [IPortDMus](https://msdn.microsoft.com/library/w [**IPortDMus::Notify**](https://msdn.microsoft.com/library/windows/hardware/ff536880) Notifies the port driver that the MIDI synthesizer or capture device has advanced to a new position in the MIDI stream. + [**IPortDMus::RegisterServiceGroup**](https://msdn.microsoft.com/library/windows/hardware/ff536882) Registers a service group object with the port driver. @@ -38,12 +39,15 @@ The DMus port driver also creates a memory [allocator](allocator.md) for each st [**IAllocatorMXF::GetBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff536492) Gets a buffer for a MIDI event or list of events that is too large to fit within a [**DMUS\_KERNEL\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff536340) structure. + [**IAllocatorMXF::GetBufferSize**](https://msdn.microsoft.com/library/windows/hardware/ff536493) Gets the size in bytes of the buffer retrieved by the **GetBuffer** method. + [**IAllocatorMXF::GetMessage**](https://msdn.microsoft.com/library/windows/hardware/ff536494) Gets a message buffer containing storage for a single structure of type DMUS\_KERNEL\_EVENT. + [**IAllocatorMXF::PutBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff536495) Not used. diff --git a/windows-driver-docs-pr/audio/dsspeaker-directout-speaker-configuration.md b/windows-driver-docs-pr/audio/dsspeaker-directout-speaker-configuration.md index 7b6a4ed523..77a809fe2c 100644 --- a/windows-driver-docs-pr/audio/dsspeaker-directout-speaker-configuration.md +++ b/windows-driver-docs-pr/audio/dsspeaker-directout-speaker-configuration.md @@ -1,6 +1,6 @@ --- -title: DSSPEAKER\_DIRECTOUT Speaker Configuration -description: DSSPEAKER\_DIRECTOUT Speaker Configuration +title: DSSPEAKER_DIRECTOUT Speaker Configuration +description: DSSPEAKER_DIRECTOUT Speaker Configuration ms.assetid: a4198fb7-157f-40e3-8cca-5a9e392087d2 keywords: - DSSPEAKER_DIRECTOUT speaker configuration WDK audio diff --git a/windows-driver-docs-pr/audio/dsspeaker-surround-speaker-configuration.md b/windows-driver-docs-pr/audio/dsspeaker-surround-speaker-configuration.md index 143a826321..5b3084b4fe 100644 --- a/windows-driver-docs-pr/audio/dsspeaker-surround-speaker-configuration.md +++ b/windows-driver-docs-pr/audio/dsspeaker-surround-speaker-configuration.md @@ -1,6 +1,6 @@ --- -title: DSSPEAKER\_SURROUND Speaker Configuration -description: DSSPEAKER\_SURROUND Speaker Configuration +title: DSSPEAKER_SURROUND Speaker Configuration +description: DSSPEAKER_SURROUND Speaker Configuration ms.assetid: de8f861b-f190-4915-b3f0-95d39965b612 keywords: - DSSPEAKER_SURROUND speaker configuration WDK audio diff --git a/windows-driver-docs-pr/audio/images/audio-chained-keyword-activation.png b/windows-driver-docs-pr/audio/images/audio-chained-keyword-activation.png new file mode 100644 index 0000000000..bbb8b03127 Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-chained-keyword-activation.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-componentized-stack-diagram.png b/windows-driver-docs-pr/audio/images/audio-componentized-stack-diagram.png new file mode 100644 index 0000000000..2866e3e6db Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-componentized-stack-diagram.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-simple-voice-recon-diagram1.png b/windows-driver-docs-pr/audio/images/audio-simple-voice-recon-diagram1.png new file mode 100644 index 0000000000..104d64dddb Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-simple-voice-recon-diagram1.png differ diff --git a/windows-driver-docs-pr/audio/images/audio-voice-activation-settings-2017.png b/windows-driver-docs-pr/audio/images/audio-voice-activation-settings-2017.png new file mode 100644 index 0000000000..07a9f6792b Binary files /dev/null and b/windows-driver-docs-pr/audio/images/audio-voice-activation-settings-2017.png differ diff --git a/windows-driver-docs-pr/audio/implementing-audio-module-communication.md b/windows-driver-docs-pr/audio/implementing-audio-module-communication.md index c7b16dade8..53b87920a5 100644 --- a/windows-driver-docs-pr/audio/implementing-audio-module-communication.md +++ b/windows-driver-docs-pr/audio/implementing-audio-module-communication.md @@ -1,22 +1,33 @@ +--- +title: Implementing Audio Module Communication +description: An Audio Module is a distinct piece of audio processing logic performing a relatively atomic function. +ms.author: windowsdriverdev +ms.date: 07/07/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + Implementing Audio Module Communication ======================================================================================== -# Overview An Audio Module is a distinct piece of audio processing logic performing a relatively atomic function. An audio module may reside in the audio driver or in audio DSP. An example audio module would be DSP-based audio processing. Starting in Windows 10, release 1703, there are both APIs and DDIs to support communication from Universal Windows Platform (UWP) apps and kernel mode device drivers. -This topic provides information on Implementing Audio Module Communication in the kernel device driver. For information on creating and UWP HSA, Hardware Support Application (HSA), see [Windows.Media.Devices Namespace](https://docs.microsoft.com/en-us/uwp/api/Windows.Media.Devices) +This topic provides information on Implementing Audio Module Communication in the kernel device driver. + +For information on how to send commands and receive change notifications from audio device modules using a UWP app, see [Configure and query audio device modules](https://docs.microsoft.com/windows-hardware/drivers/audio/configure-and-query-audiodevicemodules). -# Why Use Audio Modules? +## Why Use Audio Modules? OEMs typically bundle a configuration application on their system that allows the customer to control aspects of this audio system and tune it to their preference. The audio subsystem can contain various components such as on-host audio processing objects, hardware DSP processing, and specialized hardware such as a smart amp (all in addition to the audio codec itself). In most cases these components are created and sold by different vendors. Historically, IHVs have created their own private APIs to integrate with one another and send information between the individual components. Existing WIN32 configuration applications then would leverage these private APIs. -The [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide), provides a set of APIs that enable a single application to run across a breadth of devices. UWP also introduced a new look-and-feel that has become the customer expectation for applications running on Windows 10. +The [Universal Windows Platform (UWP)](https://docs.microsoft.com/windows/uwp/get-started/universal-application-platform-guide), provides a set of APIs that enable a single application to run across a breadth of devices. UWP also introduced a new look-and-feel that has become the customer expectation for applications running on Windows 10. So many OEMs would like to build their audio configuration applications on UWP. However, a core security feature of UWP (the AppContainer sandbox) prevents communication from an application to other components in the audio subsystem. This renders the private APIs previously used by configuration apps inaccessible in UWP. Starting in Windows 10, release 1703, the Audio Modules UWP API allows the configuration application and user mode components to communicate with modules in the kernel and hardware layer that are discoverable through a new KS property set. -Audio IHV and ISVs can write applications and services that can communicate with their hardware modules using a well-defined interface provided by Windows. For more information about the audio modules API, see [Windows.Media.Devices Namespace](https://docs.microsoft.com/en-us/uwp/api/Windows.Media.Devices) +Audio IHV and ISVs can write applications and services that can communicate with their hardware modules using a well-defined interface provided by Windows. For more information about the audio modules API, see [Windows.Media.Devices Namespace](https://docs.microsoft.com/uwp/api/Windows.Media.Devices) Audio Module Definitions @@ -54,7 +65,7 @@ The Audio Module API provides access to the modules through two different target HSAs and other applications will only be able to access the modules available through the filter handle. The individual APOs loaded on a stream are the only objects that will have access to the stream targeted audio modules. -For more information about APOs, see [Windows Audio Processing Objects](https://msdn.microsoft.com/en-us/windows/hardware/drivers/audio/windows-audio-processing-objects). +For more information about APOs, see [Windows Audio Processing Objects](https://msdn.microsoft.com/windows/hardware/drivers/audio/windows-audio-processing-objects). ### Sending Commands @@ -75,7 +86,7 @@ The recommended approach is exposing a global driver module. The global driver m **Kernel Streaming Audio Module Properties** -A new KS Property Set, identified by [KSPROPSETID_AudioModule](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808144(v=vs.85).aspx), has been defined for three properties specific to audio modules. +A new KS Property Set, identified by [KSPROPSETID_AudioModule](https://msdn.microsoft.com/library/windows/hardware/mt808144(v=vs.85).aspx), has been defined for three properties specific to audio modules. A PortCls miniport driver needs to directly handle the response for each property as no helper interface is provided. @@ -96,7 +107,7 @@ typedef enum { ### Audio Module Descriptors -Support for the [KSPROPERTY_AUDIOMODULE_DESCRIPTORS](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808142(v=vs.85).aspx) property identifies the driver as being Audio Module aware. The property will be queried through the filter or pin handle and a KSPROPERTY is passed as the input buffer for the DeviceIoControl call. [KSAUDIOMODULE_DESCRIPTOR](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808137(v=vs.85).aspx) has been defined to describe each module within the audio hardware. An array of these descriptors is returned in response to this request +Support for the [KSPROPERTY_AUDIOMODULE_DESCRIPTORS](https://msdn.microsoft.com/library/windows/hardware/mt808142(v=vs.85).aspx) property identifies the driver as being Audio Module aware. The property will be queried through the filter or pin handle and a KSPROPERTY is passed as the input buffer for the DeviceIoControl call. [KSAUDIOMODULE_DESCRIPTOR](https://msdn.microsoft.com/library/windows/hardware/mt808137(v=vs.85).aspx) has been defined to describe each module within the audio hardware. An array of these descriptors is returned in response to this request #### ksmedia.h: @@ -112,11 +123,11 @@ typedef struct _KSAUDIOMODULE_DESCRIPTOR WCHAR Name[AUDIOMODULE_MAX_NAME_SIZE]; } KSAUDIOMODULE_DESCRIPTOR, *PKSAUDIOMODULE_DESCRIPTOR; ``` -For more information, see [KSAUDIOMODULE_DESCRIPTOR](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808137(v=vs.85).aspx). +For more information, see [KSAUDIOMODULE_DESCRIPTOR](https://msdn.microsoft.com/library/windows/hardware/mt808137(v=vs.85).aspx). ### Audio Module Command -Support for the [KSPROPERTY_AUDIOMODULE_COMMAND](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808141(v=vs.85).aspx) property allows Audio Module clients to send custom commands to query and set parameters on Audio Modules. The property can be sent through the filter or pin handle and a [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808139(v=vs.85).aspx) is passed as the input buffer for the DeviceIoControl call. A client can optionally send additional information immediately adjacent to the [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808139(v=vs.85).aspx) in the input buffer to send custom commands. +Support for the [KSPROPERTY_AUDIOMODULE_COMMAND](https://msdn.microsoft.com/library/windows/hardware/mt808141(v=vs.85).aspx) property allows Audio Module clients to send custom commands to query and set parameters on Audio Modules. The property can be sent through the filter or pin handle and a [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/library/windows/hardware/mt808139(v=vs.85).aspx) is passed as the input buffer for the DeviceIoControl call. A client can optionally send additional information immediately adjacent to the [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/library/windows/hardware/mt808139(v=vs.85).aspx) in the input buffer to send custom commands. #### ksmedia.h: @@ -131,14 +142,14 @@ typedef struct _KSPAUDIOMODULE_PROPERTY } KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY; ``` -For more information, see [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808139(v=vs.85).aspx). +For more information, see [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/library/windows/hardware/mt808139(v=vs.85).aspx). ### Audio Module Notification Device ID -Support for the [KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808143(v=vs.85).aspx) is required to enable the miniport to signal notifications and pass information to Audio Module clients. The lifetime of this ID is tied to the lifetime of the audio device being exposed and active to the Windows Audio stack. The property can be sent through the filter or pin handle and a KSPROPERTY is passed as the input buffer for the DeviceIoControl call. +Support for the [KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID](https://msdn.microsoft.com/library/windows/hardware/mt808143(v=vs.85).aspx) is required to enable the miniport to signal notifications and pass information to Audio Module clients. The lifetime of this ID is tied to the lifetime of the audio device being exposed and active to the Windows Audio stack. The property can be sent through the filter or pin handle and a KSPROPERTY is passed as the input buffer for the DeviceIoControl call. -For more information, see [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808139(v=vs.85).aspx). +For more information, see [KSAUDIOMODULE_PROPERTY](https://msdn.microsoft.com/library/windows/hardware/mt808139(v=vs.85).aspx). PortCls Helper - Audio Module Notifications @@ -200,13 +211,13 @@ typedef struct _KSAUDIOMODULE_NOTIFICATION { ``` For more information, see: - [IPortClsNotifications](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808133(v=vs.85).aspx) + [IPortClsNotifications](https://msdn.microsoft.com/library/windows/hardware/mt808133(v=vs.85).aspx) - [IPortClsNotifications::AllocNotificationBuffer](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808134(v=vs.85).aspx) + [IPortClsNotifications::AllocNotificationBuffer](https://msdn.microsoft.com/library/windows/hardware/mt808134(v=vs.85).aspx) - [IPortClsNotifications::FreeNotificationBuffer](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808135(v=vs.85).aspx) + [IPortClsNotifications::FreeNotificationBuffer](https://msdn.microsoft.com/library/windows/hardware/mt808135(v=vs.85).aspx) - [IPortClsNotifications::SendNotificationBuffer](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808136(v=vs.85).aspx) + [IPortClsNotifications::SendNotificationBuffer](https://msdn.microsoft.com/library/windows/hardware/mt808136(v=vs.85).aspx) ### Calling Sequence 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 badc0113e1..58874ac638 100644 --- a/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md +++ b/windows-driver-docs-pr/audio/implementing-audio-processing-objects.md @@ -71,7 +71,7 @@ All custom APOs must have the following general characteristics: ## Using Sample Code to Accelerate the Development Process -Using the SYVAD Swap APO code sample as a template can accelerate the custom APO development process. The swap sample is the sample that was developed to illustrate some features of audio processing objects. The swap APO sample swaps the left channel with the right channel and implements both SFX and MFX effects. You can enable and disable the channel swap audio effects using the properties dialog. +Using the SYSVAD Swap APO code sample as a template can accelerate the custom APO development process. The Swap sample is the sample that was developed to illustrate some features of audio processing objects. The Swap APO sample swaps the left channel with the right channel and implements both SFX and MFX effects. You can enable and disable the channel swap audio effects using the properties dialog. The SYSVAD audio sample is available on the [Windows Driver Samples GitHub](https://github.com/Microsoft/Windows-driver-samples). @@ -119,7 +119,7 @@ The other projects in the Sysvad sample are summarized below. |------------------------|--------------------------------------------| | **Project** | **Description** | | PhoneAudioSample | Sample code for a mobile audio driver. | -| TabletAudioSample | ample code for a mobile audio driver. | +| TabletAudioSample | Sample code for an alternate audio driver. | | KeywordDetectorAdapter | Sample code for a keyword detector adapter | | EndpointsCommon | Sample code for common endpoints. | @@ -130,7 +130,7 @@ The primary header files for the SwapAPO sample is swapapo.h. The other primary | | | |----------------------|-------------------------------------------------------------------| | **File** | **Description** | -| Swap.cpp | C++ code that contains the implementation of the of the swap APO. | +| Swap.cpp | C++ code that contains the implementation of the Swap APO. | | SwapAPOMFX.cpp | Implementation of CSwapAPOMFX | | SwapAPOSFX.cpp | Implementation of CSwapAPOSFX | | SwapAPODll.cpp | Implementation of DLL Exports. | @@ -208,9 +208,9 @@ For desktop PCs, you can provide a user interface to configure the features that ## Replacing System-supplied APOs -When implementing the APO interfaces, there are two approaches, you can write your own implementation, or you can call into the inbox APOs. +When implementing the APO interfaces, there are two approaches: you can write your own implementation, or you can call into the inbox APOs. -This pseudo code illustrates wrapping a system APOs. +This pseudocode illustrates wrapping a system APO. ``` CMyWrapperAPO::CMyWrapperAPO { @@ -222,7 +222,7 @@ CMyWrapperAPO::IsInputFormatSupported { } ``` -This pseudo code illustrates creating your own custom APO. +This pseudocode illustrates creating your own custom APO. ``` CMyFromScratchAPO::IsInputFormatSupported { @@ -241,30 +241,16 @@ Implement the following interfaces and methods for the COM component: - [IAudioProcessingObjectRT](https://msdn.microsoft.com/library/windows/hardware/ff536505). The required method for this interface is [**APOProcess**](https://msdn.microsoft.com/library/windows/hardware/ff536506) and it is the method that implements the DSP algorithm. - [IAudioSystemEffects](https://msdn.microsoft.com/library/windows/hardware/ff536514). This interface makes the audio engine recognize a DLL as an APO. -## Enable the use of Unsigned APOs - - -**** - -The audio engine does not load unsigned APOs into the audio processing graph. So while you are testing your APO, you must disable the protected process for Audiodg.exe. To disable the protected process, set the value of the **DisableProtectedAudioDG** registry key to '1'. The following registry excerpt shows this. - -``` -... -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Audio - "DisableProtectedAudioDG" = dword:00000001 -... -``` - ## Working with Visual Studio and APOs -When working with APOs in Visual Studio perform these tasks for each APO project. +When working with APOs in Visual Studio, perform these tasks for each APO project. -**Linking to the CRT** +**Link to the CRT** Drivers that are targeting Windows 10 should dynamically link against the universal CRT. -if you need to support Windows 8,1, enable static linking by setting the project properties in C/C++, Code Generation. Set "Runtime Library" to */MT* for release builds or */MTd* for debug builds. This change is made, because for a driver it is difficult to redistribute the MSVCRT<n>.dll binary, the solution is to statically link libcmt.dll. For more information see [/MD, /MT, /LD (Use Run-Time Library)](http://msdn.microsoft.com/library/2kzt1wy3.aspx) . +If you need to support Windows 8,1, enable static linking by setting the project properties in C/C++, Code Generation. Set "Runtime Library" to */MT* for release builds or */MTd* for debug builds. This change is made, because for a driver it is difficult to redistribute the MSVCRT<n>.dll binary. The solution is to statically link libcmt.dll. For more information see [/MD, /MT, /LD (Use Run-Time Library)](http://msdn.microsoft.com/library/2kzt1wy3.aspx) . **Disable Use of an Embedded Manifest** @@ -287,9 +273,9 @@ The custom APO and the configuration UI are packaged as separate DLLs. The devic The following paragraphs and INF file fragments show the modifications that are necessary to use the standard INF file to copy and register APOs and the configuration UI. -The tabletaudiosample.inf and phoneaudiosample.inf files included with the Sysvad sample, illustrate how the SwapApo.dll APOs are registered. +The tabletaudiosample.inf and phoneaudiosample.inf files included with the Sysvad sample illustrate how the SwapApo.dll APOs are registered. -## Register APOs for Processing Modes and Effects in the INF File +## Registering APOs for Processing Modes and Effects in the INF File You can register APOs for specific modes using certain allowable combinations of registry keys. For more information on which effects are available and general information about APOs, see [Audio Processing Object Architecture](audio-processing-object-architecture.md). @@ -321,9 +307,9 @@ There is one additional valid combination that is not shown in these samples. **SYSVAD Tablet Multi-Mode Streaming Effect APO INF Sample** -This sample shows a multi-mode streaming effects being registered using AddReg entries in the SYSVAD Tablet INF file. +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 it is available on GitHub here . +This sample code is from the SYSVAD audio sample and is available on GitHub here: . This sample illustrates this combination of system effects: @@ -393,7 +379,7 @@ AUDIO_SIGNALPROCESSINGMODE_DEFAULT = "{C18E2F7E-933D-4965-B7D1-1EEF228D2AF3}" **APO INF Audio Sample** -This sample INF file illustrates this following combination of system effects: +This sample INF file illustrates the following combination of system effects: - PKEY\_FX\_StreamEffectClsid with PKEY\_SFX\_ProcessingModes\_Supported\_For\_Streaming @@ -488,7 +474,7 @@ HKCR,AudioEngine\AudioProcessingObjects\%FX_DISCOVER_EFFECTS_APO_CLSID%, "APOInt ## APO Registration -APO registration is used to support a process that dynamically matches the effects to endpoint using a weighted calculation. The weighted calculation, use the following property stores. Every audio interface has zero or more *endpoint property stores* and *effects property stores* registered either via the .inf or at runtime. The most specific endpoint property store and the most specific effects property store has the highest weight and is used. All other property stores are ignored. +APO registration is used to support a process that dynamically matches the effects to endpoints using a weighted calculation. The weighted calculation uses the following property stores. Every audio interface has zero or more *endpoint property stores* and *effects property stores* registered either via the .inf or at runtime. The most specific endpoint property store and the most specific effects property store have the highest weights and are used. All other property stores are ignored. Specificity is calculated as follows: @@ -498,12 +484,14 @@ Endpoint property stores weighting 2. FX with KSNODETYPE\_ANY 3. MSFX with specific KSNODETYPE 4. MSFX with KSNODETYPE\_ANY + Effects property stores weighting 1. EP with specific KSNODETYPE 2. EP with KSNODETYPE\_ANY 3. MSEP with specific KSNODETYPE 4. MSEP with KSNODETYPE\_ANY + Numbers must start at 0 and increase sequentially: MSEP\\0, MSEP\\1, …, MSEP\\n If (for example) EP\\3 is missing, Windows will stop looking for EP\\n and will not see EP\\4, even if it exists The value of PKEY\_FX\_Association (for effects property stores) or PKEY\_EP\_Association (for endpoint property stores) is compared against the KSPINDESCRIPTOR.Category value for the pin factory at the hardware end of the signal path, as exposed by Kernel Streaming. @@ -554,7 +542,7 @@ The following information is provided to help you understand how failure is moni The audio system monitors APO return codes to determine whether APOs are being successfully incorporated into the graph. It monitors the return codes by tracking the HRESULT values that are returned by any one of the designated methods. The system maintains a separate failure count value for each SFX, MFX and EFX APO that is being incorporated into the graph. -The audio system monitors the returned HRESULT values form the following four methods. +The audio system monitors the returned HRESULT values from the following four methods. - CoCreateInstance diff --git a/windows-driver-docs-pr/audio/implementing-hardware-offloaded-apo-effects.md b/windows-driver-docs-pr/audio/implementing-hardware-offloaded-apo-effects.md index 818a7346ee..90d9e4165a 100644 --- a/windows-driver-docs-pr/audio/implementing-hardware-offloaded-apo-effects.md +++ b/windows-driver-docs-pr/audio/implementing-hardware-offloaded-apo-effects.md @@ -18,6 +18,9 @@ Two types of APOs can be loaded during hardware offload playback. 1. Offload Stream Effects (OSFX) 2. Offload Mode Effects (OMFX) + + + ## Hardware Offloaded APO Effects Overview diff --git a/windows-driver-docs-pr/audio/loudness-equalization-dsp.md b/windows-driver-docs-pr/audio/loudness-equalization-dsp.md index 48f1589325..243e6c6a5f 100644 --- a/windows-driver-docs-pr/audio/loudness-equalization-dsp.md +++ b/windows-driver-docs-pr/audio/loudness-equalization-dsp.md @@ -14,7 +14,7 @@ ms.technology: windows-devices The loudness equalization DSP ensures that the volume level across different sources of audio signal stays constant. A TV program, for example, might be at just the right volume level whereas the commercial breaks within the program can vary widely in volume. This requires users to adjust the volume setting accordingly. Some of today's expensive HD-capable TVs can equalize volume so that the sound stays at a somewhat constant level. That works well if you rely on your TV for sound playback, but most home theater and home audio enthusiasts connect the TV audio directly to their stereo sound systems. In addition, today's loudness equalization solutions are often not effective for different audio content and sources. -can maintain a more uniform perceived loudness across different digital audio files or sources than earlier Windows technologies. This means that loudness always stays within a specified range, even for different digital signals. +Versions of Windows with this audio effect can maintain a more uniform perceived loudness across different digital audio files or sources than earlier Windows technologies. This means that loudness always stays within a specified range, even for different digital signals.   diff --git a/windows-driver-docs-pr/audio/midi-miniport-driver.md b/windows-driver-docs-pr/audio/midi-miniport-driver.md index 59947580de..ddaedc5928 100644 --- a/windows-driver-docs-pr/audio/midi-miniport-driver.md +++ b/windows-driver-docs-pr/audio/midi-miniport-driver.md @@ -32,26 +32,33 @@ The miniport interface, [IMiniportMidi](https://msdn.microsoft.com/library/windo [**IMiniportMidi::Init**](https://msdn.microsoft.com/library/windows/hardware/ff536709) Initializes the miniport object. + [**IMiniportMidi::NewStream**](https://msdn.microsoft.com/library/windows/hardware/ff536710) Creates a new stream object. + [**IMiniportMidi::Service**](https://msdn.microsoft.com/library/windows/hardware/ff536711) Notifies the miniport driver of a request for service. + The stream interface, [IMiniportMidiStream](https://msdn.microsoft.com/library/windows/hardware/ff536704), inherits the methods in the **IUnknown** interface. **IMiniportMidiStream** provides the following additional methods: [**IMiniportMidiStream::Read**](https://msdn.microsoft.com/library/windows/hardware/ff536705) Reads input data from a MIDI capture device. + [**IMiniportMidiStream::SetFormat**](https://msdn.microsoft.com/library/windows/hardware/ff536706) Sets the data format of the MIDI stream. + [**IMiniportMidiStream::SetState**](https://msdn.microsoft.com/library/windows/hardware/ff536707) Sets the state of the MIDI stream. + [**IMiniportMidiStream::Write**](https://msdn.microsoft.com/library/windows/hardware/ff536708) Writes output data to a MIDI synthesizer. + The MIDI port driver handles all timing issues in both directions and relies on the miniport driver to promptly move data on and off the adapter in response to the port driver's calls to the **IMiniportMidiStream** read and write methods. PortCls contains built-in MIDI miniport drivers for MIDI devices that have FM synth and UART functions. For more information, see [**PcNewMiniport**](https://msdn.microsoft.com/library/windows/hardware/ff537714). diff --git a/windows-driver-docs-pr/audio/miniport-interfaces.md b/windows-driver-docs-pr/audio/miniport-interfaces.md index b8ae4a8a8d..f7fce97f15 100644 --- a/windows-driver-docs-pr/audio/miniport-interfaces.md +++ b/windows-driver-docs-pr/audio/miniport-interfaces.md @@ -24,22 +24,26 @@ ms.technology: windows-devices ## -As described in [Supporting a Device](supporting-a-device.md), the PortCls system driver provides a set of five built-in port drivers for managing wave and MIDI devices. To use one of these port drivers to manage a particular type of audio device, the adapter driver must provide a corresponding miniport driver that complements the port driver by managing all the device's hardware-dependent functions. +As described in [Supporting a Device](supporting-a-device.md), the PortCls system driver provides a set of built-in port drivers for managing wave and MIDI devices. To use one of these port drivers to manage a particular type of audio device, the adapter driver must provide a corresponding miniport driver that complements the port driver by managing all the device's hardware-dependent functions. -This section discusses the following five miniport driver types: +This section discusses the following miniport driver types: [WaveRT Miniport Driver](wavert-miniport-driver.md) Complements the WaveRT port driver by managing the hardware-dependent functions of a wave rendering or capture device that uses a cyclic buffer for audio data. + [Topology Miniport Driver](topology-miniport-driver.md) Complements the Topology port driver by managing the various hardware controls (for example, volume level) in the audio adapter's mixer circuitry. + [MIDI Miniport Driver](midi-miniport-driver.md) Complements the MIDI port driver by managing the hardware-dependent functions of a simple MIDI device. + [DMus Miniport Driver](dmus-miniport-driver.md) Complements the DMus port driver by managing the hardware-dependent functions of an advanced MIDI device. + Each port driver implements an **IPortXxx** interface, which it presents to the miniport driver. In turn, the miniport driver must implement an **IMiniportXxx** interface, which the port driver uses to communicate with the miniport driver. The following table shows the **IPortXxx** interface and the corresponding **IMiniportXxx** interface for each device type. diff --git a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-bdl-ddi-object.md b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-bdl-ddi-object.md index 32457a1df5..da892c48d4 100644 --- a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-bdl-ddi-object.md +++ b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-bdl-ddi-object.md @@ -1,6 +1,6 @@ --- -title: Obtaining an HDAUDIO\_BUS\_INTERFACE\_BDL DDI Object -description: Obtaining an HDAUDIO\_BUS\_INTERFACE\_BDL DDI Object +title: Obtaining an HDAUDIO_BUS_INTERFACE_BDL DDI Object +description: Obtaining an HDAUDIO_BUS_INTERFACE_BDL DDI Object ms.assetid: 142eb2f0-6c6d-4441-8ad7-0875546c1ab2 keywords: - HDAUDIO_BUS_INTERFACE_BDL structure diff --git a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-ddi-object.md b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-ddi-object.md index ad473fcdfe..513109543f 100644 --- a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-ddi-object.md +++ b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-ddi-object.md @@ -1,6 +1,6 @@ --- -title: Obtaining an HDAUDIO\_BUS\_INTERFACE DDI Object -description: Obtaining an HDAUDIO\_BUS\_INTERFACE DDI Object +title: Obtaining an HDAUDIO_BUS_INTERFACE DDI Object +description: Obtaining an HDAUDIO_BUS_INTERFACE DDI Object ms.assetid: 78667254-62a6-41fe-af36-43dbdea63aa8 keywords: - HDAUDIO_BUS_INTERFACE structure diff --git a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-v2-ddi-object.md b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-v2-ddi-object.md index cdd9b2c142..a3cfd68e29 100644 --- a/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-v2-ddi-object.md +++ b/windows-driver-docs-pr/audio/obtaining-an-hdaudio-bus-interface-v2-ddi-object.md @@ -1,6 +1,6 @@ --- -title: Obtaining an HDAUDIO\_BUS\_INTERFACE\_V2 DDI Object -description: Obtaining an HDAUDIO\_BUS\_INTERFACE\_V2 DDI Object +title: Obtaining an HDAUDIO_BUS_INTERFACE_V2 DDI Object +description: Obtaining an HDAUDIO_BUS_INTERFACE_V2 DDI Object ms.assetid: 3aad8c7a-8c89-499a-bfe8-e3facdffcd15 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/audio/subdevice-creation.md b/windows-driver-docs-pr/audio/subdevice-creation.md index e62beaf40e..aac11514dd 100644 --- a/windows-driver-docs-pr/audio/subdevice-creation.md +++ b/windows-driver-docs-pr/audio/subdevice-creation.md @@ -81,10 +81,10 @@ The following code example shows how the adapter driver performs these actions: MiniportClassId, NULL, NonPagedPool); } else // Ask PortCls for one of its built-in miniports. - { + { ntStatus = PcNewMiniport((PMINIPORT*)&miniport, MiniportClassId); - } + } if (NT_SUCCESS(ntStatus)) { diff --git a/windows-driver-docs-pr/audio/troubleshooting-sapo-load-failures.md b/windows-driver-docs-pr/audio/troubleshooting-sapo-load-failures.md index 61e2338dad..933837f637 100644 --- a/windows-driver-docs-pr/audio/troubleshooting-sapo-load-failures.md +++ b/windows-driver-docs-pr/audio/troubleshooting-sapo-load-failures.md @@ -22,7 +22,7 @@ The following information is provided to help you understand how failure is moni The audio system monitors sAPO return codes to determine whether sAPOs are being successfully incorporated into the graph. It monitors the return codes by tracking the HRESULT values that are returned by any one of the designated methods. The system maintains a separate failure count value for each LFX sAPO and the GFX sAPO that is being incorporated into the graph. -The audio system monitors the returned HRESULT values form the following four methods. +The audio system monitors the returned HRESULT values from the following four methods. - CoCreateInstance diff --git a/windows-driver-docs-pr/audio/voice-activation.md b/windows-driver-docs-pr/audio/voice-activation.md index 92de985a7f..7e5b563bb0 100644 --- a/windows-driver-docs-pr/audio/voice-activation.md +++ b/windows-driver-docs-pr/audio/voice-activation.md @@ -12,7 +12,7 @@ ms.technology: windows-devices # Voice Activation -Cortana, the personal assistant technology introduced on Windows Phone 8.1, is now supported on Windows 10 devices. 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. +Cortana, the personal assistant technology introduced on Windows Phone 8.1, is supported on Windows 10 devices. 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. **Note**   Implementing voice activation is a significant project and is a task completed by SoC vendors. OEMs can contact their SoC vendor for information on their SoC's implementation of voice activation. @@ -37,7 +37,7 @@ To understand the voice interaction experience available in Windows, review thes **"Hey Cortana" Voice Activation** -The "Hey Cortana" Voice Activation (VA) feature allows users to quickly engage an experience (e.g., Cortana) outside of his or her active context (i.e., what is currently on screen) by using his or her voice. Users often want to be able to instantly access an experience without having to physically interact touch a device. For phone users this may be due to driving in the car and having their attention and hands engaged with operating the vehicle. For an Xbox user this may be due not wanting to find and connect a controller. For PC users, this may be due to rapid access to an experience without having to perform multiple mouse, touch and/or keyboard actions, e.g. a computer in the kitchen. +The "Hey Cortana" Voice Activation (VA) feature allows users to quickly engage the Cortana experience outside of his or her active context (i.e., what is currently on screen) by using his or her voice. Users often want to be able to instantly access an experience without having to physically interact touch a device. For phone users this may be due to driving in the car and having their attention and hands engaged with operating the vehicle. For an Xbox user this may be due not wanting to find and connect a controller. For PC users, this may be due to rapid access to an experience without having to perform multiple mouse, touch and/or keyboard actions, e.g. a computer in the kitchen. Voice activation provides always listening speech input via predefined key phrase(s) or "activation phrases". Key phrases may be uttered by themselves ("Hey Cortana") as a staged command, or followed by a speech action, for example, "Hey Cortana, where is my next meeting?", a chained command. @@ -47,27 +47,47 @@ The term *Keyword Detection*, describes the detection of the keyword by either h A *chained command* describes the ability of issuing a command immediately following the keyword (like “Hey Cortana, call John”) and have Cortana start (if not already started) and follow the command (starting a phone call with John). -The *Software Keyword Spotter* is the software voice activation software detection of keyword when device is powered on in the absence of hardware keyword detection. Hardware keyword detection might be absent because it is not available on device or because it is turned off. +This diagram illustrates chained and keyword only activation. + +![chained and keyword activation diagram showing audio buffer and time sequence](images/audio-chained-keyword-activation.png) + +Microsoft provides an OS default keyword spotter (software keyword spotter) that is used to ensure quality of hardware keyword detections and to provide the Hey Cortana experience in cases where hardware keyword detection is absent or unavailable. **The "Learn my voice" feature** -The "Learn my voice" feature allows the user to train Cortana to recognize their unique voice. This is accomplished by the user clicking on "Learn my voice" in the Cortana settings screen. The user then repeats six carefully chosen phrases that provide a sufficient variety of phonetic patterns to identify the unique attributes of the users voice. +The "Learn my voice" feature allows the user to train Cortana to recognize their unique voice. This is accomplished by the user clicking on *Learn how I say "Hey Cortana"* in the Cortana settings screen. The user then repeats six carefully chosen phrases that provide a sufficient variety of phonetic patterns to identify the unique attributes of the users voice. -![cortana settings showing the respond best to anyone option](images/cortana-settings-respond-to-anyone.png) +![cortana desktop settings for hw keyword spotter wake on voice](images/audio-voice-activation-settings-2017.png) -When voice activation is paired with "Learn my voice", where the two algorithms will work together to reduce false activations. This is especially valuable for the meeting room scenario, where one person says "Hey Cortana" in a room full of devices. +When voice activation is paired with "Learn my voice", the two algorithms will work together to reduce false activations. This is especially valuable for the meeting room scenario, where one person says "Hey Cortana" in a room full of devices. -Voice activation is powered by a keyword spotter (KWS) which reacts if the key phrase is detected. If the KWS is to wake the device from a low powered state, the hardware offloaded solution is known as Wake on Voice (WoV). For more information, see [Wake on Voice](#wake_on_voice). +Voice activation is powered by a keyword spotter (KWS) which reacts if the key phrase is detected. If the 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). -## Implementing Voice Activation +## Glossary of Terms -To implement voice activation SoC vendors must complete the following tasks. +This glossary summarizes terms related to voice activation. +| | | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Staged Command | Example: Hey Cortana What’s the weather? This is sometimes referred to as “Two-shot command” or “Keyword-only” | +|Chained Command | Example: Hey Cortana what’s the weather? This is sometimes referred to as a “One-shot command” | +| Voice Activation | The scenario of providing keyword detection of a predefined activation keyphrase. For example, "Hey Cortana" is the Microsoft Voice Activation scenario. | +|WoV | Wake-on-Voice – 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](https://msdn.microsoft.com/en-us/library/windows/hardware/mt282515(v=vs.85).aspx) | +|KWS |Keyword spotter – the algorithm that provides the detection of “Hey Cortana” | +| 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-offloaded 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. | +|Keyword Detector OEM Adapter |A driver-level shim that enables the WoV-enabled HW to communicate with Windows and the Cortana stack. | +|Model | The acoustic model data file used by the KWS algorithm. The data file is static. Models are localized, one per locale.| -- Create a custom keyword detector based on the SYSVAD sample described later in this topic. You will implement these methods in a COM DLL, described in [OEM COM DLL Interface](#oem_com_dll_interface). -- To help ensure glitch-free operation, audio drivers should register their streaming resources with portcls. This allows the OS to manage resources to avoid interference between audio streaming and other subystems. For more information, see [Audio Streaming Resource DDI](#audio_streaming_resource_ddi). -- For optimal performance implement WAVE RT enhancements described in [WAVERT Enhancements](#wavert_enhancements). -- Optionally design any custom APOs to enhance the audio capture process. For more information, see [Windows Audio Processing Objects](windows-audio-processing-objects.md). +## Integrating a Hardware Keyword Spotter + +To implement a hardware keyword spotter (HW KWS) SoC vendors must complete the following tasks. + +- Create a custom keyword detector based on the SYSVAD sample described later in this topic. You will implement these methods in a COM DLL, described in [Keyword Detector OEM Adapter Interface](#keyword_detector). +- Implement WAVE RT enhancements described in [WAVERT Enhancements](#wavert_enhancements). - Provide INF file entries to describe any custom APOs used for keyword detection. - [PKEY\_FX\_KeywordDetector\_StreamEffectClsid](https://msdn.microsoft.com/library/windows/hardware/mt244268) - [PKEY\_FX\_KeywordDetector\_ModeEffectClsid](https://msdn.microsoft.com/library/windows/hardware/mt244267) @@ -77,6 +97,9 @@ To implement voice activation SoC vendors must complete the following tasks. - [PKEY\_EFX\_KeywordDetector\_ProcessingModes\_Supported\_For\_Streaming](https://msdn.microsoft.com/library/windows/hardware/mt244264) - Review the hardware recommendations in [Cortana Device Recommendation](https://msdn.microsoft.com/library/windows/hardware/dn957008). This topic provides guidance and recommendations for the design and development of audio input devices intended for use with Microsoft’s Speech Platform. - Review the hardware recommendation [Cortana Device Test Setup](https://msdn.microsoft.com/library/windows/hardware/dn957009). This topic provides test guidance of audio input devices intended for use with Microsoft’s Speech Platform. +- Support both staged and chained commands. +- Support “Hey Cortana” for each of the supported Cortana locales. +- Optionally design any custom APOs to enhance the audio capture process. For more information, see [Windows Audio Processing Objects](windows-audio-processing-objects.md). ## Sample Code Overview @@ -94,54 +117,56 @@ For more information about the SYSVAD sample audio driver, see [Sample Audio Dri The audio stack external interfaces for enabling Voice Activation serves as the communication pipeline for the speech platform and the audio drivers. The external interfaces are divided into three parts. -- *Keyword detector Device Driver Interface (DDI)*. This interface is responsible for plumbing audio data/metadata from the software clients to the drivers. This interface is also responsible for enabling low power capture paths for hardware that supports buffering after keyword detection for chained command scenarios. -- *OEM keyword model adapter DLL*. This DLL implements a COM interface to adapt the driver specific opaque data for use by the OS. -- *WaveRT streaming enhancements*. These enhancements improve the performance of keyword recognition. +- *Keyword detector Device Driver Interface (DDI)*. The Keyword 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. +- *Keyword Detector OEM Adapter DLL*. 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. **Audio Endpoint Properties** -The ID of IAudioClient activate-able device information object is the primary audio endpoint property. This is optional and is included only if the endpoint supports buffering and streaming from the keyword detector. The keyword detector client gets the device interface path from the endpoint property store and passes this to [ActivateAudioInterfaceAsync function](https://msdn.microsoft.com/library/windows/desktop/jj128298.aspx) to get a streaming interface. 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”. +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** -The driver exposes a KS filter for its capture device as usual. This filter supports several filter KS properties and a KS event to configure the keyword detector and get status from it. The filter also includes an additional pin factory identified as a keyword detector pin. This pin is used to stream audio from the keyword detector. +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. The properties are: - Supported keyword types - [**KSPROPERTY\_SOUNDDETECTOR\_PATTERNS**](https://msdn.microsoft.com/library/windows/hardware/dn932151). This property is set by the operating system to configure the keywords to be detected. -- Current set of keyword patterns - [**KSPROPERTY\_SOUNDDETECTOR\_SUPPORTEDPATTERNS**](https://msdn.microsoft.com/library/windows/hardware/dn932152). This read/write property is an array of keyword patterns. The OS sets this to download keywords. -- Armed - [**KSPROPERTY\_SOUNDDETECTOR\_ARMED**](https://msdn.microsoft.com/library/windows/hardware/dn932149). This read/write property is a simply Boolean status indicating whether the detector is armed. The OS sets this engage the keyword detector. The OS can clear this to disengage. The driver automatically clears this when keyword patterns are set and also after a keyword is detected. (The OS must rearm.) -- Match result - [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](https://msdn.microsoft.com/library/windows/hardware/dn932150). This read property indicates matched audio data with a header after detection. +- List of keyword patterns GUIDs - [**KSPROPERTY\_SOUNDDETECTOR\_SUPPORTEDPATTERNS**](https://msdn.microsoft.com/library/windows/hardware/dn932152). This property is used to get a list of GUIDs that identify the types of supported patterns. +- Armed - [**KSPROPERTY\_SOUNDDETECTOR\_ARMED**](https://msdn.microsoft.com/library/windows/hardware/dn932149). This read/write property is a simply Boolean status indicating whether the detector is armed. The OS sets this to engage the keyword detector. The OS can clear this to disengage. The driver automatically clears this when keyword patterns are set and also after a keyword is detected. (The OS must rearm.) +- Match result - [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](https://msdn.microsoft.com/library/windows/hardware/dn932150). This read property holds the result data after detection has occurred. The event that is fired when a keyword is detected is a [**KSEVENT\_SOUNDDETECTOR\_MATCHDETECTED**](https://msdn.microsoft.com/library/windows/hardware/dn932148) event. **Sequence of Operation** -System Startup +*System Startup* 1. The OS reads the supported keyword types to verify it has keywords in that format. 2. The OS registers for the detector status change event. 3. The OS sets the keyword patterns. 4. The OS arms the detector. -On Receiving the KS Event + +*On Receiving the KS Event* 1. The driver disarms the detector. 2. The OS reads the keyword detector status, parses the returned data, and determines which pattern was detected. 3. The OS rearms the detector. + **Internal Driver and Hardware Operation** -While the detector is armed, the hardware is continuously capturing and buffering audio data in a small FIFO. (The size of this FIFO is determined by requirements outside of this document, but might typically be hundreds of milliseconds to several seconds.) The detection algorithm operates on the data streaming through this buffer. The design of the driver and hardware are such that while armed there is no interaction between the driver and hardware and no interrupts to the “application” processors until a keyword is detected. This allows the system to reach a lower power state if there is no other activity. +While the detector is armed, the hardware can be continuously capturing and buffering audio data in a small FIFO buffer. (The size of this FIFO buffer is determined by requirements outside of this document, but might typically be hundreds of milliseconds to several seconds.) The detection algorithm operates on the data streaming through this buffer. The design of the driver and hardware are such that while armed there is no interaction between the driver and hardware and no interrupts to the “application” processors until a keyword is detected. This allows the system to reach a lower power state if there is no other activity. -When the hardware detects a keyword, it generates an interrupt. While waiting for the driver to service the interrupt, the hardware continues to capture audio into the FIFO, ensuring no data after the keyword is lost, within buffering limits. +When the hardware detects a keyword, it generates an interrupt. While waiting for the driver to service the interrupt, the hardware continues to capture audio into the buffer, ensuring no data after the keyword is lost, within buffering limits. **Keyword Timestamps** -After detecting a keyword, some of the voice activation solutions may buffer some or all of the spoken keyword. If the audio driver streams some or all of the spoken keyword after detection, then the audio driver must provide timestamps identifying the end (and optionally the start) of the key phrase in the stream. Otherwise the audio driver must stream only the portion of the speech following the keyword. +After detecting a keyword, all voice activation solutions must buffer all of the spoken keyword, including 250ms before the start of the keyword. The audio driver must provide timestamps identifying the start and end of the key phrase in the stream. In order to support the keyword start/end timestamps, DSP software may need to internally timestamp events based on a DSP clock. Once a keyword is detected, the DSP software interacts with the driver to prepare a KS event. The driver and DSP software will need to map the DSP timestamps to a Windows performance counter value. The method of doing this is specific to the hardware design. One possible solution is for the driver to read current performance counter, query the current DSP timestamp, read current performance counter again, and then estimate a correlation between performance counter and DSP time. Then given the correlation, the driver can map the keyword DSP timestamps to Windows performance counter timestamps. -## OEM COM DLL Interface +## Keyword Detector OEM Adapter Interface The OEM supplies a COM object implementation that acts as an intermediary between the OS and the driver, helping to compute or parse the opaque data that is written and read to the audio driver through [**KSPROPERTY\_SOUNDDETECTOR\_PATTERNS**](https://msdn.microsoft.com/library/windows/hardware/dn932151) and [**KSPROPERTY\_SOUNDDETECTOR\_MATCHRESULT**](https://msdn.microsoft.com/library/windows/hardware/dn932150). @@ -149,7 +174,7 @@ The CLSID of the COM object is a detector pattern type GUID returned by the [**K **COM Threading Model requirements** -The OS supplies a proxy-stub for [IKeywordDetectorOemAdapter](https://msdn.microsoft.com/library/windows/hardware/dn957504). The OEM’s implementation may choose any of the COM threading models. +The OEM’s implementation may choose any of the COM threading models. **IKeywordDetectorOemAdapter** @@ -191,7 +216,7 @@ typedef struct **Handling Model Data** -*Static user independent model* - The OEM DLL would typically include some status user independent model data either built into the DLL or in a separate data file included with the DLL. The set of supported keyword IDs returned by the GetCapabilities routine would depend on this data. For example, if the list of supported keyword IDs returned by GetCapabilities includes KwHeyCortana, the static user independent model data would include data for “Hey Cortana” (or its translation) for all the supported languages. +*Static user independent model* - The OEM DLL would typically include some static user independent model data either built into the DLL or in a separate data file included with the DLL. The set of supported keyword IDs returned by the GetCapabilities routine would depend on this data. For example, if the list of supported keyword IDs returned by GetCapabilities includes KwHeyCortana, the static user independent model data would include data for “Hey Cortana” (or its translation) for all the supported languages. *Dynamic user dependent model* - IStream provides a random access storage model. The OS passes an IStream interface pointer to many of the methods on the IKeywordDetectorOemAdapter interface. The OS backs the IStream implementation with appropriate storage for up to 1MB of data. @@ -221,24 +246,24 @@ Audio is processed in a unique way for voice activation training. The following - + - + - + - + - + - + - +
Voice Recognition
ModeMode RawSpeechRaw or Speech
PinPin NormalBurstKWS
Audio FormatAudio Format 32-bit float (Type = Audio, Subtype = IEEE_FLOAT, Sampling Rate = 16 kHz, bits = 32) Managed by OS audio stack
MicMic Mic 0All mics in arrayAll mics in array, or mono
@@ -250,7 +275,7 @@ Audio is processed in a unique way for voice activation training. The following This diagram provides an overview of the keyword recognition system. -![keyword recognition system including cortana the speech runtime and the voice activation manager](images/audio-voice-activation-and-speaker-id.png) +![keyword recognition system including cortana the speech runtime and the voice activation manager](images/audio-simple-voice-recon-diagram1.png) ## Keyword Recognition Sequence Diagrams @@ -278,6 +303,8 @@ Miniport interfaces are defined to be implemented by WaveRT miniport drivers. Th 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. +HW-KWS solutions must support audio capture sizes of at least 100ms and up to 200ms. + The driver expresses the buffer size constraints by setting the DEVPKEY\_KsAudio\_PacketSize\_Constraints device property on the KSCATEGORY\_AUDIO PnP device interface of the KS filter that has the KS streaming pin(s). This property should remain valid and stable while the KS filter interface is enabled. The OS can read this value at any time without having to open a handle to the driver and call on the driver. **DEVPKEY\_KsAudio\_PacketSize\_Constraints** @@ -312,80 +339,30 @@ To burst data that has been captured prior to transition to KSSTATE\_RUN, the dr 1. After the stream transitions to KSSTATE\_RUN, the driver immediately sets the buffer notification event because it already has data available. 2. On this event, the OS calls GetReadPacket() to get information about the available data. -a. The driver returns the packet number of the valid captured data (0 for the first packet after the transition from KSSTATE\_STOP to KSSTATE\_RUN), from which the OS can derive the packet position within the WaveRT buffer as well as the packet position relative to start of stream. -b. The driver also returns the performance counter value that corresponds to the sampling instant of the first sample in the packet. Note that this performance counter value might be relatively old, depending on how much capture data has been buffered within the hardware or driver (outside of the WaveRT buffer). -c. If there is more unread buffered data available the driver either: -i. Immediately transfers that data into the available space of WaveRT buffer (i.e. space not used by the packet returned from GetReadPacket), returns true for MoreData, and sets the buffer notification event before returning from this routine. Or, -ii. Programs hardware to burst the next packet into the available space of the WaveRT buffer, returns false for MoreData, and later sets the buffer event when the transfer completes. + + a. The driver returns the packet number of the valid captured data (0 for the first packet after the transition from KSSTATE\_STOP to KSSTATE\_RUN), from which the OS can derive the packet position within the WaveRT buffer as well as the packet position relative to start of stream. + + b. The driver also returns the performance counter value that corresponds to the sampling instant of the first sample in the packet. Note that this performance counter value might be relatively old, depending on how much capture data has been buffered within the hardware or driver (outside of the WaveRT buffer). + + c. If there is more unread buffered data available the driver either: + i. Immediately transfers that data into the available space of WaveRT buffer (i.e. space not used by the packet returned from GetReadPacket), returns true for MoreData, and sets the buffer notification event before returning from this routine. Or, + ii. Programs hardware to burst the next packet into the available space of the WaveRT buffer, returns false for MoreData, and later sets the buffer event when the transfer completes. 3. The OS reads data from the WaveRT buffer using the information returned by GetReadPacket(). 4. The OS waits for the next buffer notification event. The wait might terminate immediately if the driver set the buffer notification in step (2c). 5. If the driver did not immediately set the event in step (2c), the driver sets the event after it transfers more captured data into the WaveRT buffer and makes it available for the OS to read 6. Go to (2). For [**KSNODETYPE\_AUDIO\_KEYWORDDETECTOR**](https://msdn.microsoft.com/library/windows/hardware/dn965563) keyword detector pins, drivers should allocate enough internal burst buffering for at least 5000ms of audio data. If the OS fails to create a stream on the pin before the buffer overflows then the driver may end the internal buffering activity and free associated resources. -## Audio Streaming Resource DDI - - -To help ensure glitch-free operation, audio drivers should register their streaming resources with portcls. This allows the OS to manage resources to avoid interference between audio streaming and other subystems. - -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. - -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. - -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. - -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: - -(1) 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. -(2) 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. -(3) 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: -(a) registers its bus driver’s resources, and -(b) 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. - -**Related Code Elements** - -[**PcAddStreamResource**](https://msdn.microsoft.com/library/windows/hardware/mt298188) - Adds a stream resource. - -[**PcStreamResourceType**](https://msdn.microsoft.com/library/windows/hardware/mt298190) - Describes a PcStreamResource. - -[**IPortClsStreamResourceManager**](https://msdn.microsoft.com/library/windows/hardware/mt270106) - A WaveRT miniport optionally can use this interface instead of hard-linking with [**PcAddStreamResource**](https://msdn.microsoft.com/library/windows/hardware/mt298188) and [**PcRemoveStreamResource**](https://msdn.microsoft.com/library/windows/hardware/mt298189). - -[**IPortClsStreamResourceManager::AddStreamResource**](https://msdn.microsoft.com/library/windows/hardware/mt270107) - Adds a stream resource. - -[**IPortClsStreamResourceManager::RemoveStreamResource**](https://msdn.microsoft.com/library/windows/hardware/mt270108)- Removes a stream resource. - -[**IPortClsStreamResourceManager2::AddStreamResource2**](https://msdn.microsoft.com/library/windows/hardware/mt604863) - Adds a stream resource. Takes a PDO and can be used when portcls is linked with non-audio miniports. - -**wdmaudio.inf** - -Note that 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. - -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 include/needs wdmaudio.inf. This code installs the PortCls and its dependent files. - -``` -[] -Include=wdmaudio.inf -Needs=WDMPORTCLS.CopyFilesOnly -``` ## Wake on Voice +Wake On Voice (WoV) enables the user to activate and query a speech recognition engine from a screen off, lower power state, to a screen on, full power state by saying a certain keyword, such as "Hey Cortana". -**** - -Wake On Voice (WoV) enables the user to activate and query a speech recognition engine from various device power states by saying a certain keyword, such as "Cortana". - -This feature allows for the device to be always listening for the user’s voice while the device is in a low power state, including when the screen is off and the device is idle. It does this by using a low-power listening mode which uses in the order of single-digit milliamps of power compared to the much higher usage seen during normal microphone recording. The low-power speech recognition allows a user to simply say a pre-defined key phrase like "Hey Cortana", followed by a chained speech phrase like "when’s my next appointment" to invoke speech in a hands-free manner. This will work regardless of whether the device is in use or idle with the screen off. - -If the device supports wake on voice with chained commands using a hardware keyword spotter, the entire request would be buffered and available for processing when the device has woken up. A sound is played to indicate to the user that the voice recognition system has responded to their voice. +This feature allows for the device to be always listening for the user’s voice while the device is in a low power state, including when the screen is off and the device is idle. It does this by using a listening mode, which is lower power when compared to the much higher power usage seen during normal microphone recording. The low power speech recognition allows a user to simply say a pre-defined key phrase like "Hey Cortana", followed by a chained speech phrase like "when’s my next appointment" to invoke speech in a hands-free manner. This will work regardless of whether the device is in use or idle with the screen off. -If the device does not support wake on voice with chained commands, after saying the keyword, the speech experience should be launched with a short delay (<=250mS), at which point the user can say the phrase as they normally would. +The audio stack is responsible for communicating the wake data (speaker ID, keyword trigger, confidence level) as well as notifying interested clients that the keyword has been detected. -The audio stack is responsible for communicating the wake data (speaker ID, keyword trigger, confidence level) that the hardware exposes as well as notifying interested clients that the keyword has been detected. - -  - -  +   -------------------- diff --git a/windows-driver-docs-pr/audio/wavecyclic-miniport-driver.md b/windows-driver-docs-pr/audio/wavecyclic-miniport-driver.md index 3b2c69fbd3..b6bc9e1b1c 100644 --- a/windows-driver-docs-pr/audio/wavecyclic-miniport-driver.md +++ b/windows-driver-docs-pr/audio/wavecyclic-miniport-driver.md @@ -42,26 +42,33 @@ The miniport interface, [IMiniportWaveCyclic](https://msdn.microsoft.com/library [**IMiniportWaveCyclic::Init**](https://msdn.microsoft.com/library/windows/hardware/ff536722) Initializes the miniport object. + [**IMiniportWaveCyclic::NewStream**](https://msdn.microsoft.com/library/windows/hardware/ff536723) Creates a new stream object. + The stream interface, [IMiniportWaveCyclicStream](https://msdn.microsoft.com/library/windows/hardware/ff536715), inherits the methods in the [**IUnknown**](https://msdn.microsoft.com/library/windows/desktop/ms680509) interface. IMiniportWaveCyclicStream provides the following additional methods: [**IMiniportWaveCyclicStream::GetPosition**](https://msdn.microsoft.com/library/windows/hardware/ff536716) Gets the device's current position in the wave stream. + [**IMiniportWaveCyclicStream::NormalizePhysicalPosition**](https://msdn.microsoft.com/library/windows/hardware/ff536717) Converts a physical buffer position value into a time-based value. + [**IMiniportWaveCyclicStream::SetFormat**](https://msdn.microsoft.com/library/windows/hardware/ff536718) Sets the data format of the wave stream. + [**IMiniportWaveCyclicStream::SetNotificationFreq**](https://msdn.microsoft.com/library/windows/hardware/ff536719) Sets the frequency at which notification interrupts occur. + [**IMiniportWaveCyclicStream::SetState**](https://msdn.microsoft.com/library/windows/hardware/ff536720) Sets the state of the wave stream. + [**IMiniportWaveCyclicStream::Silence**](https://msdn.microsoft.com/library/windows/hardware/ff536721) Copies silence into a buffer. diff --git a/windows-driver-docs-pr/audio/wavecyclic-port-driver.md b/windows-driver-docs-pr/audio/wavecyclic-port-driver.md index f604ad5e26..e2f580bf10 100644 --- a/windows-driver-docs-pr/audio/wavecyclic-port-driver.md +++ b/windows-driver-docs-pr/audio/wavecyclic-port-driver.md @@ -31,12 +31,15 @@ The WaveCyclic port driver exposes an [IPortWaveCyclic](https://msdn.microsoft.c [**IPortWaveCyclic::NewMasterDmaChannel**](https://msdn.microsoft.com/library/windows/hardware/ff536900) Creates a new master DMA channel object for an audio device with a built-in DMA controller. + [**IPortWaveCyclic::NewSlaveDmaChannel**](https://msdn.microsoft.com/library/windows/hardware/ff536902) Creates a new subordinate DMA channel object for an audio device without a built-in DMA controller. + [**IPortWaveCyclic::Notify**](https://msdn.microsoft.com/library/windows/hardware/ff536903) Notifies the port driver that the DMA controller has advanced to a new position in the audio stream. + The WaveCyclic port and miniport driver objects communicate with each other through their respective [IPortWaveCyclic](https://msdn.microsoft.com/library/windows/hardware/ff536899) and [IMiniportWaveCyclic](https://msdn.microsoft.com/library/windows/hardware/ff536714) interfaces. In addition, the port driver communicates with the miniport driver's stream objects through their [IMiniportWaveCyclicStream](https://msdn.microsoft.com/library/windows/hardware/ff536715) interfaces.   diff --git a/windows-driver-docs-pr/audio/wavepci-miniport-driver.md b/windows-driver-docs-pr/audio/wavepci-miniport-driver.md index 1b90247881..e55282f4a1 100644 --- a/windows-driver-docs-pr/audio/wavepci-miniport-driver.md +++ b/windows-driver-docs-pr/audio/wavepci-miniport-driver.md @@ -36,35 +36,45 @@ The miniport interface, [IMiniportWavePci](https://msdn.microsoft.com/library/wi [**IMiniportWavePci::Init**](https://msdn.microsoft.com/library/windows/hardware/ff536734) Initializes the miniport object. + [**IMiniportWavePci::NewStream**](https://msdn.microsoft.com/library/windows/hardware/ff536735) Creates a new stream object. + [**IMiniportWavePci::Service**](https://msdn.microsoft.com/library/windows/hardware/ff536736) Notifies the miniport driver of a request for service. + The stream interface, [IMiniportWavePciStream](https://msdn.microsoft.com/library/windows/hardware/ff536725), inherits the methods from the [**IUnknown**](https://msdn.microsoft.com/library/windows/desktop/ms680509) interface. IMiniportWavePciStream provides the following additional methods: [**IMiniportWavePciStream::GetAllocatorFraming**](https://msdn.microsoft.com/library/windows/hardware/ff536726) Gets the miniport driver's preferred allocator-framing parameters for the wave stream. + [**IMiniportWavePciStream::GetPosition**](https://msdn.microsoft.com/library/windows/hardware/ff536727) Gets the device's current position in the wave stream. + [**IMiniportWavePciStream::MappingAvailable**](https://msdn.microsoft.com/library/windows/hardware/ff536728) Indicates that a new mapping is available from the port driver. + [**IMiniportWavePciStream::NormalizePhysicalPosition**](https://msdn.microsoft.com/library/windows/hardware/ff536729) Converts a physical buffer position value into a time-based value. + [**IMiniportWavePciStream::RevokeMappings**](https://msdn.microsoft.com/library/windows/hardware/ff536730) Revokes previously issued mappings. + [**IMiniportWavePciStream::Service**](https://msdn.microsoft.com/library/windows/hardware/ff536731) Notifies the stream object of a request for service. + [**IMiniportWavePciStream::SetFormat**](https://msdn.microsoft.com/library/windows/hardware/ff536732) Sets the data format of the wave stream. + [**IMiniportWavePciStream::SetState**](https://msdn.microsoft.com/library/windows/hardware/ff536733) Sets the state of the wave stream. diff --git a/windows-driver-docs-pr/audio/wdm-audio-extensions-to-legacy-windows-multimedia-apis.md b/windows-driver-docs-pr/audio/wdm-audio-extensions-to-legacy-windows-multimedia-apis.md index 1d26c817e6..19f74fd6a3 100644 --- a/windows-driver-docs-pr/audio/wdm-audio-extensions-to-legacy-windows-multimedia-apis.md +++ b/windows-driver-docs-pr/audio/wdm-audio-extensions-to-legacy-windows-multimedia-apis.md @@ -23,7 +23,7 @@ Recent versions of Windows have extended the audio functions in the Windows mult The [**auxGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd756712), [**midiInGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd798453), [**midiOutGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd798469), [**mixerGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd757300), [**waveInGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd743841), and [**waveOutGetDevCaps**](https://msdn.microsoft.com/library/windows/desktop/dd743857) functions can retrieve driver-specific information that uniquely identifies an audio device. -The Windows multimedia functions [**waveInMessage**](https://msdn.microsoft.com/library/windows/desktop/dd743846), [**waveOutMessage**](https://msdn.microsoft.com/library/windows/desktop/dd743865), [**midiInMessage**](https://msdn.microsoft.com/library/windows/desktop/dd798457), [**midiOutMessage**](https://msdn.microsoft.com/library/windows/desktop/dd798475), and [**mixerMessage**](https://msdn.microsoft.com/library/windows/desktop/dd757307) can retrieve the device interface name of a wave, MIDI, or mixer device. In addition, the **midiOutMessage**, **waveInMessage**, and **waveOutMessage** functions can retrieve the device IDs of the preferred audio devices for wave I/O, MIDI, and voice communications. +The Windows multimedia functions [**waveInMessage**](https://msdn.microsoft.com/library/windows/desktop/dd743846), [**waveOutMessage**](https://msdn.microsoft.com/library/windows/desktop/dd743865), [**midiInMessage**](https://msdn.microsoft.com/library/windows/desktop/dd798457), [**midiOutMessage**](https://msdn.microsoft.com/library/windows/desktop/dd798475), and [**mixerMessage**](https://msdn.microsoft.com/library/windows/desktop/dd757307) can retrieve the device interface name of a wave, MIDI, or mixer device. In addition, the **waveOutMessage**, **midiOutMessage**, and **waveInMessage** functions can retrieve the device IDs of the preferred audio devices for wave I/O, MIDI, and voice communications, respectively. The following topics are discussed in this section: 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 a81600f207..38ce4208b1 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 @@ -11,8 +11,17 @@ ms.technology: windows-devices # WDM Audio Support in Different Versions of Windows +This section describes the operating system support for audio devices and drivers in different versions of Windows. -This section describes the operating system support for audio devices and drivers in the versions of Windows since Windows 98. The topics in this section are: +[Implementing Audio Module Communication](implementing-audio-module-communication.md) + +[Low Latency Audio](low-latency-audio.md) + +[Voice Activation](voice-activation.md) + +[Audio Hardware Resource Management](audio-hardware-resource-management.md) + +----------------------------------------------------------------------------------------------- [Bluetooth Bypass Guidelines for Audio Drivers](bluetooth-bypass-guidelines-for-audio-drivers.md) @@ -28,9 +37,7 @@ This section describes the operating system support for audio devices and driver [Factors Governing Wave-Output Latency](factors-governing-wave-output-latency.md) -[Implementation Issues for WavePci Devices](implementation-issues-for-wavepci-devices.md) - -[Audio System Effects](audio-system-effects.md) +[Windows Vista Audio System Effects](audio-system-effects.md)   diff --git a/windows-driver-docs-pr/audio/windows-audio-architecture.md b/windows-driver-docs-pr/audio/windows-audio-architecture.md index 72a472d1c5..b210df8fa9 100644 --- a/windows-driver-docs-pr/audio/windows-audio-architecture.md +++ b/windows-driver-docs-pr/audio/windows-audio-architecture.md @@ -66,7 +66,7 @@ The audio engine consists of two related components, the Audio Device Graph (aud The audio engine: - Mixes and processes audio streams. For more information about how the audio engine uses buffers to transfer audio, see [Understanding the WaveRT Port Driver](understanding-the-wavert-port-driver.md). -- Loads �Audio Processing Objects� (APOs), which are H/W-specific plugins that process the audio signal. For more information about APOs, see [Windows Audio Processing Objects](windows-audio-processing-objects.md). +- Loads Audio Processing Objects (APOs), which are H/W-specific plugins that process the audio signal. For more information about APOs, see [Windows Audio Processing Objects](windows-audio-processing-objects.md). ## Audio Service (audiosrv.dll) @@ -90,7 +90,7 @@ Audio drivers: - Follow the port-miniport model. For more information, see [WDM Audio Terminology](wdm-audio-terminology.md) and [Developing a WaveRT Miniport Driver](developing-a-wavert-miniport-driver.md). - Allow the audio stack to render and capture audio from several audio devices, including: integrated speakers and microphones, headsets/headphones, USB devices, Bluetooth devices, HDMI, etc. -- The port-minport model corresponds to the Advanced Linux Sound Architecture � ALSA +- The port-minport model corresponds to the Advanced Linux Sound Architecture ALSA - For information on sample driver code, see [Sample Audio Drivers](sample-audio-drivers.md). ## Hardware @@ -104,9 +104,9 @@ The audio hardware that is present on any give device varies but can include: - External devices: USB audio devices, Bluetooth audio devices, HDMI audio, etc. - Signal processing can also be implemented in the H/W (e.g. the codec or the DSP), instead of or in addition to the APOs. -� -� + + -------------------- diff --git a/windows-driver-docs-pr/audio/windows-threshold--what-s-new-for-audio.md b/windows-driver-docs-pr/audio/windows-threshold--what-s-new-for-audio.md index 2226afb736..a6e3f04799 100644 --- a/windows-driver-docs-pr/audio/windows-threshold--what-s-new-for-audio.md +++ b/windows-driver-docs-pr/audio/windows-threshold--what-s-new-for-audio.md @@ -19,6 +19,8 @@ This topic provides a high level summary of what's new in audio for Windows 10. Here are the new audio features in Windows 10. +- [Implementing Audio Module Communication](implementing-audio-module-communication.md) + - [Low Latency Audio Improvements](#lowlatency) - [Signal Processing Modes and Audio Categories](#signalprocessing) @@ -51,7 +53,7 @@ The total latency of a device is the sum of the latencies of the following compo - Audio Driver - Audio Hardware -In Windows 10 work was done to reduce the latency ion the OS. Without any driver changes, applications in Windows 10 will experience 4.5-16ms lower latency. In addition, if the driver has been updated to take advantage of the new low latency DDIs that use small buffers to process audio data, then the latency will be reduced even more. If a driver supports 3ms audio buffers, then the roundtrip latency is ~10ms. +In Windows 10 work was done to reduce the latency in the OS. Without any driver changes, applications in Windows 10 will experience 4.5-16ms lower latency. In addition, if the driver has been updated to take advantage of the new low latency DDIs that use small buffers to process audio data, then the latency will be reduced even more. If a driver supports 3ms audio buffers, then the roundtrip latency is ~10ms. ![low latency audio stack diagram showing apps, audio engine driver and h/w](images/low-latency-audio-stack-diagram-1.png) @@ -166,7 +168,7 @@ For more information, see [Implementing Hardware Offloaded APO Effects](implemen ## Cortana Voice Activation - Wake on Voice -Cortana, the personal assistant technology introduced on Windows Phone 8.1, is now supported on Windows 10 devices. 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". The "Hey Cortana" Voice Activation (VA) feature allows users to quickly engage an experience (e.g., Cortana) outside of his or her active context (i.e., what is currently on screen) by using his or her voice. The feature is targeted for scenarios when the screen is off, idle or when it is fully active. If the hardware supports buffering, users can the chain the key phrase and command phrase together. This improves the end to end wake on voice experience for the user. For more information, see [Voice Activation](voice-activation.md). +Cortana, the personal assistant technology introduced on Windows Phone 8.1, is now supported on Windows 10 devices. 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". The "Hey Cortana" Voice Activation (VA) feature allows users to quickly engage an experience (e.g., Cortana) outside of his or her active context (i.e., what is currently on screen) by using his or her voice. The feature is targeted for scenarios when the screen is off, idle or when it is fully active. If the hardware supports buffering, users can then chain the key phrase and command phrase together. This improves the end to end wake on voice experience for the user. For more information, see [Voice Activation](voice-activation.md). ## Windows Universal Drivers for Audio 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 c53366529d..c21af412f9 100644 --- a/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md +++ b/windows-driver-docs-pr/battery/ups-serviceproviders-registry-entries.md @@ -1,6 +1,6 @@ --- -title: UPS\ServiceProviders Registry Entries -description: UPS\ServiceProviders Registry Entries +title: UPS ServiceProviders Registry Entries +description: Create a vendor-specific subkey under the UPS ServiceProviders registry key for each UPS model. ms.assetid: fa206f16-e136-4bfe-9823-7c324d62e1fb ms.author: windowsdriverdev ms.date: 04/20/2017 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 e0d00f7b31..cb6121a9cb 100644 --- a/windows-driver-docs-pr/battery/ups-status-registry-entries.md +++ b/windows-driver-docs-pr/battery/ups-status-registry-entries.md @@ -1,6 +1,6 @@ --- -title: UPS\Status Registry Entries -description: UPS\Status Registry Entries +title: UPS Status Registry Entries +description: UPS minidrivers must set certain UPS Status Registry Entries ms.assetid: c24ef185-ba8d-4cfd-9d33-b70682905f00 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/beta.md b/windows-driver-docs-pr/beta.md new file mode 100644 index 0000000000..7622929d16 --- /dev/null +++ b/windows-driver-docs-pr/beta.md @@ -0,0 +1,5 @@ +--- +title: Beta warning +--- +> [!WARNING] +> Some information relates to prereleased 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. \ No newline at end of file diff --git a/windows-driver-docs-pr/breadcrumbs/toc.yml b/windows-driver-docs-pr/breadcrumbs/toc.yml index 6b5b920cc4..34b9cd8630 100644 --- a/windows-driver-docs-pr/breadcrumbs/toc.yml +++ b/windows-driver-docs-pr/breadcrumbs/toc.yml @@ -22,6 +22,9 @@ - name: Windows Driver Frameworks tocHref: /windows-hardware/drivers/wdf/ topicHref: /windows-hardware/drivers/wdf/index + - name: Windows Debugging Tools + tocHref: /windows-hardware/drivers/debugger/ + topicHref: /windows-hardware/drivers/debugger/index - name: Device and Driver Technologies tocHref: /windows-hardware/drivers/device-and-driver-technologies/ topicHref: /windows-hardware/drivers/device-and-driver-technologies @@ -83,6 +86,9 @@ - name: Multifunction tocHref: /windows-hardware/drivers/multifunction/ topicHref: /windows-hardware/drivers/multifunction/index + - name: NetCx + tocHref: /windows-hardware/drivers/netcx/ + topicHref: /windows-hardware/drivers/netcx/index - name: Network tocHref: /windows-hardware/drivers/network/ topicHref: /windows-hardware/drivers/network/index diff --git a/windows-driver-docs-pr/bringup/acpi-device-specific-methods.md b/windows-driver-docs-pr/bringup/acpi-device-specific-methods.md index 45aafc28be..cc15d86956 100644 --- a/windows-driver-docs-pr/bringup/acpi-device-specific-methods.md +++ b/windows-driver-docs-pr/bringup/acpi-device-specific-methods.md @@ -1,7 +1,7 @@ --- -title: Device-specific methods (\_DSM) +title: Device-specific methods (_DSM) author: windows-driver-content -description: To support increased functionality and extension to select technology stacks, Windows define Device-Specific Methods (\_DSM) for the device. +description: To support increased functionality and extension to select technology stacks, Windows define Device-Specific Methods (_DSM) for the device. ms.assetid: E49BE897-28A5-42FE-875C-A8EB56EABF8B ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/acpi-namespace-hierarchy.md b/windows-driver-docs-pr/bringup/acpi-namespace-hierarchy.md index 77407e5167..96e08b6290 100644 --- a/windows-driver-docs-pr/bringup/acpi-namespace-hierarchy.md +++ b/windows-driver-docs-pr/bringup/acpi-namespace-hierarchy.md @@ -1,7 +1,7 @@ --- title: ACPI namespace hierarchy author: windows-driver-content -description: The ACPI namespace hierarchy must accurately model the platform's hardware topology, starting with the processor's system bus ( \ 0034;\\\_SB \ 0034;). +description: The ACPI namespace hierarchy must accurately model the platform's hardware topology, starting with the processor's system bus ( \ 0034;\\_SB \ 0034;). ms.assetid: 14B5F787-65B1-4BC3-90CD-D4AD1C8044D1 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/acpi-system-description-tables.md b/windows-driver-docs-pr/bringup/acpi-system-description-tables.md index f20454d841..ce1d63b267 100644 --- a/windows-driver-docs-pr/bringup/acpi-system-description-tables.md +++ b/windows-driver-docs-pr/bringup/acpi-system-description-tables.md @@ -110,7 +110,7 @@ The Windows SMM Security Mitigations Table (WSMT) specification contains details This information applies to the following operating systems: -Windows Server 2016 Technical Preview +Windows Server 2016 Windows 10, version 1607 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-completion-token.md b/windows-driver-docs-pr/bringup/efi-battery-charging-completion-token.md index 6d09e53ab5..8200824a6d 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-completion-token.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-completion-token.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_COMPLETION\_TOKEN +title: EFI_BATTERY_CHARGING_COMPLETION_TOKEN author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_COMPLETION\_TOKEN +description: EFI_BATTERY_CHARGING_COMPLETION_TOKEN ms.assetid: 1151643e-8b22-4034-b043-ac4d44c01082 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-protocol.md b/windows-driver-docs-pr/bringup/efi-battery-charging-protocol.md index 47c399d81a..2067b5118a 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-protocol.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-protocol.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_PROTOCOL +title: EFI_BATTERY_CHARGING_PROTOCOL author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_PROTOCOL +description: EFI_BATTERY_CHARGING_PROTOCOL ms.assetid: 978d063e-f864-44be-9f58-4e4c6b2193b8 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolchargebattery.md b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolchargebattery.md index 6efdf37536..965ca270b1 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolchargebattery.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolchargebattery.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_PROTOCOL.ChargeBattery +title: EFI_BATTERY_CHARGING_PROTOCOL.ChargeBattery author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_PROTOCOL.ChargeBattery +description: EFI_BATTERY_CHARGING_PROTOCOL.ChargeBattery ms.assetid: 362b812f-b64b-4b6c-84a6-61c09a60f8a3 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatteryinformation.md b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatteryinformation.md index c03f553631..d8cf6afa80 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatteryinformation.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatteryinformation.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_PROTOCOL.GetBatteryInformation +title: EFI_BATTERY_CHARGING_PROTOCOL.GetBatteryInformation author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_PROTOCOL.GetBatteryInformation +description: EFI_BATTERY_CHARGING_PROTOCOL.GetBatteryInformation ms.assetid: 497cd001-5180-4dee-a070-ccf8c987bd71 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatterystatus.md b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatterystatus.md index 3496bab8e2..8123041249 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatterystatus.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-protocolgetbatterystatus.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_PROTOCOL.GetBatteryStatus +title: EFI_BATTERY_CHARGING_PROTOCOL.GetBatteryStatus author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_PROTOCOL.GetBatteryStatus +description: EFI_BATTERY_CHARGING_PROTOCOL.GetBatteryStatus ms.assetid: dc2b647b-b3b6-4d85-9faf-9e401fa67571 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-battery-charging-status.md b/windows-driver-docs-pr/bringup/efi-battery-charging-status.md index fad0e0f33d..faaff633d3 100644 --- a/windows-driver-docs-pr/bringup/efi-battery-charging-status.md +++ b/windows-driver-docs-pr/bringup/efi-battery-charging-status.md @@ -1,7 +1,7 @@ --- -title: EFI\_BATTERY\_CHARGING\_STATUS +title: EFI_BATTERY_CHARGING_STATUS author: windows-driver-content -description: EFI\_BATTERY\_CHARGING\_STATUS +description: EFI_BATTERY_CHARGING_STATUS ms.assetid: dc267920-2c2f-447b-8772-35160886a24c ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-checksig-protocolefichecksignatureandhash.md b/windows-driver-docs-pr/bringup/efi-checksig-protocolefichecksignatureandhash.md index f0cc6daa80..1a0dcb180c 100644 --- a/windows-driver-docs-pr/bringup/efi-checksig-protocolefichecksignatureandhash.md +++ b/windows-driver-docs-pr/bringup/efi-checksig-protocolefichecksignatureandhash.md @@ -1,7 +1,7 @@ --- -title: EFI\_CHECKSIG\_PROTOCOL.EfiCheckSignatureAndHash +title: EFI_CHECKSIG_PROTOCOL.EfiCheckSignatureAndHash author: windows-driver-content -description: EFI\_CHECKSIG\_PROTOCOL.EfiCheckSignatureAndHash +description: EFI_CHECKSIG_PROTOCOL.EfiCheckSignatureAndHash ms.assetid: 7c6d1756-a3db-4754-9edb-af6ba1ecf65b ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-display-power-protocol.md b/windows-driver-docs-pr/bringup/efi-display-power-protocol.md index 5a51f15e19..b11fe4745a 100644 --- a/windows-driver-docs-pr/bringup/efi-display-power-protocol.md +++ b/windows-driver-docs-pr/bringup/efi-display-power-protocol.md @@ -1,7 +1,7 @@ --- -title: EFI\_DISPLAY\_POWER\_PROTOCOL +title: EFI_DISPLAY_POWER_PROTOCOL author: windows-driver-content -description: EFI\_DISPLAY\_POWER\_PROTOCOL +description: EFI_DISPLAY_POWER_PROTOCOL ms.assetid: 61ccf856-7e0b-4f1b-9be9-7b8a31339a6b ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-display-power-protocolgetdisplaypowerstate.md b/windows-driver-docs-pr/bringup/efi-display-power-protocolgetdisplaypowerstate.md index 37439085e0..125d4053fb 100644 --- a/windows-driver-docs-pr/bringup/efi-display-power-protocolgetdisplaypowerstate.md +++ b/windows-driver-docs-pr/bringup/efi-display-power-protocolgetdisplaypowerstate.md @@ -1,7 +1,7 @@ --- -title: EFI\_DISPLAY\_POWER\_PROTOCOL.GetDisplayPowerState +title: EFI_DISPLAY_POWER_PROTOCOL.GetDisplayPowerState author: windows-driver-content -description: EFI\_DISPLAY\_POWER\_PROTOCOL.GetDisplayPowerState +description: EFI_DISPLAY_POWER_PROTOCOL.GetDisplayPowerState ms.assetid: 8c5fe55f-903e-4ef0-b3cf-8b764af767cf ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-display-power-protocolsetdisplaypowerstate.md b/windows-driver-docs-pr/bringup/efi-display-power-protocolsetdisplaypowerstate.md index e5a6f27fbb..e34b7e89ae 100644 --- a/windows-driver-docs-pr/bringup/efi-display-power-protocolsetdisplaypowerstate.md +++ b/windows-driver-docs-pr/bringup/efi-display-power-protocolsetdisplaypowerstate.md @@ -1,7 +1,7 @@ --- -title: EFI\_DISPLAY\_POWER\_PROTOCOL.SetDisplayPowerState +title: EFI_DISPLAY_POWER_PROTOCOL.SetDisplayPowerState author: windows-driver-content -description: EFI\_DISPLAY\_POWER\_PROTOCOL.SetDisplayPowerState +description: EFI_DISPLAY_POWER_PROTOCOL.SetDisplayPowerState ms.assetid: ee638d05-4d0e-45b0-a733-73923a7c045a ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-display-power-state.md b/windows-driver-docs-pr/bringup/efi-display-power-state.md index e7c539d06f..a5fc0287d4 100644 --- a/windows-driver-docs-pr/bringup/efi-display-power-state.md +++ b/windows-driver-docs-pr/bringup/efi-display-power-state.md @@ -1,7 +1,7 @@ --- -title: EFI\_DISPLAY\_POWER\_STATE +title: EFI_DISPLAY_POWER_STATE author: windows-driver-content -description: EFI\_DISPLAY\_POWER\_STATE +description: EFI_DISPLAY_POWER_STATE ms.assetid: b4b0980b-db87-44e8-842c-afce0c8df0a0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-rng-algorithm-list.md b/windows-driver-docs-pr/bringup/efi-rng-algorithm-list.md index 5d403f08dd..f04e2220fd 100644 --- a/windows-driver-docs-pr/bringup/efi-rng-algorithm-list.md +++ b/windows-driver-docs-pr/bringup/efi-rng-algorithm-list.md @@ -1,5 +1,5 @@ --- -title: EFI\_RNG\_ALGORITHM\_LIST structure +title: EFI_RNG_ALGORITHM_LIST structure author: windows-driver-content description: This data structure contains a list of the supported Random Number Generation (RNG) algorithms. ms.assetid: 1481330F-78F3-4C18-BD19-3B4984E0138F diff --git a/windows-driver-docs-pr/bringup/efi-rng-protocol-getinfo.md b/windows-driver-docs-pr/bringup/efi-rng-protocol-getinfo.md index 9bc1deb145..c1daa3982c 100644 --- a/windows-driver-docs-pr/bringup/efi-rng-protocol-getinfo.md +++ b/windows-driver-docs-pr/bringup/efi-rng-protocol-getinfo.md @@ -1,7 +1,7 @@ --- -title: EFI\_RNG\_PROTOCOL.GetInfo +title: EFI_RNG_PROTOCOL.GetInfo author: windows-driver-content -description: EFI\_RNG\_PROTOCOL.GetInfo +description: EFI_RNG_PROTOCOL.GetInfo ms.assetid: 11E9927B-8BC6-4B01-A12D-C75B636E3988 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-rng-protocol-getrng.md b/windows-driver-docs-pr/bringup/efi-rng-protocol-getrng.md index 55b053514b..81fba2f36d 100644 --- a/windows-driver-docs-pr/bringup/efi-rng-protocol-getrng.md +++ b/windows-driver-docs-pr/bringup/efi-rng-protocol-getrng.md @@ -1,7 +1,7 @@ --- -title: EFI\_RNG\_PROTOCOL.GetRNG +title: EFI_RNG_PROTOCOL.GetRNG author: windows-driver-content -description: EFI\_RNG\_PROTOCOL.GetRNG +description: EFI_RNG_PROTOCOL.GetRNG ms.assetid: 5C2E0C8F-FF3A-4F57-BC28-3BC540852CB0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-rng-protocol.md b/windows-driver-docs-pr/bringup/efi-rng-protocol.md index 33aa218d43..a05f587ec9 100644 --- a/windows-driver-docs-pr/bringup/efi-rng-protocol.md +++ b/windows-driver-docs-pr/bringup/efi-rng-protocol.md @@ -1,7 +1,7 @@ --- -title: EFI\_RNG\_PROTOCOL +title: EFI_RNG_PROTOCOL author: windows-driver-content -description: The EFI\_RNG\_PROTOCOL is used to obtain a Random Number Generation (RNG) value from an EFI driver. +description: The EFI_RNG_PROTOCOL is used to obtain a Random Number Generation (RNG) value from an EFI driver. ms.assetid: 927E2C40-973B-49AB-ACD5-2A3532827D74 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-rng-service-binding-protocol.md b/windows-driver-docs-pr/bringup/efi-rng-service-binding-protocol.md index 262f2ddbec..002a1bd0fa 100644 --- a/windows-driver-docs-pr/bringup/efi-rng-service-binding-protocol.md +++ b/windows-driver-docs-pr/bringup/efi-rng-service-binding-protocol.md @@ -1,5 +1,5 @@ --- -title: EFI\_RNG\_SERVICE\_BINDING\_PROTOCOL +title: EFI_RNG_SERVICE_BINDING_PROTOCOL author: windows-driver-content description: Used to locate RNG services provided by a driver, and to create and destroy instances so that multiple drivers can use the underlying RNG services. ms.assetid: 3CAD0FD8-DD26-4D26-A9E9-4B2750985E00 diff --git a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolgetmaxpacketsize.md b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolgetmaxpacketsize.md index a0d05a8202..c27ffeeb94 100644 --- a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolgetmaxpacketsize.md +++ b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolgetmaxpacketsize.md @@ -1,7 +1,7 @@ --- -title: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.GetMaxPacketSize +title: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.GetMaxPacketSize author: windows-driver-content -description: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.GetMaxPacketSize +description: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.GetMaxPacketSize ms.assetid: 8808bb5d-e00d-4b19-87ad-4a071a896e22 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolinitialize.md b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolinitialize.md index 3a90a976b2..afbe6489a2 100644 --- a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolinitialize.md +++ b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolinitialize.md @@ -1,7 +1,7 @@ --- -title: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Initialize +title: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Initialize author: windows-driver-content -description: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Initialize +description: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Initialize ms.assetid: e27ed767-7854-4b2f-8043-35c39357eee4 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolread.md b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolread.md index b5714edfd1..c7f3577546 100644 --- a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolread.md +++ b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolread.md @@ -1,7 +1,7 @@ --- -title: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Read +title: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Read author: windows-driver-content -description: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Read +description: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Read ms.assetid: 9b5525a4-d98c-4328-8ebe-55ede53befca ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolwrite.md b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolwrite.md index 0277fea0bc..d7e12fcd0e 100644 --- a/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolwrite.md +++ b/windows-driver-docs-pr/bringup/efi-simple-winphone-io-protocolwrite.md @@ -1,7 +1,7 @@ --- -title: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Write +title: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Write author: windows-driver-content -description: EFI\_SIMPLE\_WINPHONE\_IO\_PROTOCOL.Write +description: EFI_SIMPLE_WINPHONE_IO_PROTOCOL.Write ms.assetid: 55475573-e904-4adc-91cf-62afe9e67927 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-bos-descriptor.md b/windows-driver-docs-pr/bringup/efi-usb-bos-descriptor.md index 349586f0e7..41e922bf8f 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-bos-descriptor.md +++ b/windows-driver-docs-pr/bringup/efi-usb-bos-descriptor.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_BOS\_DESCRIPTOR +title: EFI_USB_BOS_DESCRIPTOR author: windows-driver-content -description: EFI\_USB\_BOS\_DESCRIPTOR +description: EFI_USB_BOS_DESCRIPTOR ms.assetid: A12E3678-E5B6-4AB0-8F28-FCDA57C9D397 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-bus-speed.md b/windows-driver-docs-pr/bringup/efi-usb-bus-speed.md index 351c0947fa..188ec4a9b3 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-bus-speed.md +++ b/windows-driver-docs-pr/bringup/efi-usb-bus-speed.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_BUS\_SPEED +title: EFI_USB_BUS_SPEED author: windows-driver-content -description: EFI\_USB\_BUS\_SPEED +description: EFI_USB_BUS_SPEED ms.assetid: 2888cff6-db12-47ea-866f-de218e2b08e5 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-config-info.md b/windows-driver-docs-pr/bringup/efi-usb-config-info.md index 407f51da93..681d34cad8 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-config-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-config-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_CONFIG\_INFO +title: EFI_USB_CONFIG_INFO author: windows-driver-content -description: EFI\_USB\_CONFIG\_INFO +description: EFI_USB_CONFIG_INFO ms.assetid: 74d5cb02-2648-4bd1-990e-61156b5dc8cd ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-device-info.md b/windows-driver-docs-pr/bringup/efi-usb-device-info.md index 9685704a52..27d99fb25f 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-device-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-device-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_DEVICE\_INFO +title: EFI_USB_DEVICE_INFO author: windows-driver-content -description: EFI\_USB\_DEVICE\_INFO +description: EFI_USB_DEVICE_INFO ms.assetid: b44f77fc-f496-488f-b53a-b54420da9360 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-endpoint-type.md b/windows-driver-docs-pr/bringup/efi-usb-endpoint-type.md index 3cf33a48cb..226b7047b3 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-endpoint-type.md +++ b/windows-driver-docs-pr/bringup/efi-usb-endpoint-type.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_ENDPOINT\_TYPE +title: EFI_USB_ENDPOINT_TYPE author: windows-driver-content -description: EFI\_USB\_ENDPOINT\_TYPE +description: EFI_USB_ENDPOINT_TYPE ms.assetid: 5cdb0efc-2355-42e2-929b-df19257e35c1 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-interface-info.md b/windows-driver-docs-pr/bringup/efi-usb-interface-info.md index 80d6644809..7b3c7006ea 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-interface-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-interface-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_INTERFACE\_INFO +title: EFI_USB_INTERFACE_INFO author: windows-driver-content -description: EFI\_USB\_INTERFACE\_INFO +description: EFI_USB_INTERFACE_INFO ms.assetid: d20b78bd-8369-4f50-b161-e8ad0bb4c52f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-superspeed-config-info.md b/windows-driver-docs-pr/bringup/efi-usb-superspeed-config-info.md index 61de654a3b..7d24e3d6c2 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-superspeed-config-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-superspeed-config-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_SUPERSPEED\_CONFIG\_INFO +title: EFI_USB_SUPERSPEED_CONFIG_INFO author: windows-driver-content -description: EFI\_USB\_SUPERSPEED\_CONFIG\_INFO +description: EFI_USB_SUPERSPEED_CONFIG_INFO ms.assetid: 9827B0A9-AC69-43FA-922F-384E3AE140F7 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-superspeed-device-info.md b/windows-driver-docs-pr/bringup/efi-usb-superspeed-device-info.md index e4d56ddb13..faa22ae9ff 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-superspeed-device-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-superspeed-device-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_SUPERSPEED\_DEVICE\_INFO +title: EFI_USB_SUPERSPEED_DEVICE_INFO author: windows-driver-content -description: EFI\_USB\_SUPERSPEED\_DEVICE\_INFO +description: EFI_USB_SUPERSPEED_DEVICE_INFO ms.assetid: 7861BA16-7499-48A1-9D6A-9BB8F5AA36CE ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-companion-descriptor.md b/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-companion-descriptor.md index 7fdb0cfee4..c9398dcad7 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-companion-descriptor.md +++ b/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-companion-descriptor.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_SUPERSPEED\_ENDPOINT\_COMPANION\_DESCRIPTOR +title: EFI_USB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR author: windows-driver-content -description: EFI\_USB\_SUPERSPEED\_ENDPOINT\_COMPANION\_DESCRIPTOR +description: EFI_USB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR ms.assetid: 5449A10A-17BC-40CB-A8FC-19F867CFC9D0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-descriptor.md b/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-descriptor.md index 059a755f4d..3ea04b0ea3 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-descriptor.md +++ b/windows-driver-docs-pr/bringup/efi-usb-superspeed-endpoint-descriptor.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_SUPERSPEED\_ENDPOINT\_DESCRIPTOR +title: EFI_USB_SUPERSPEED_ENDPOINT_DESCRIPTOR author: windows-driver-content -description: EFI\_USB\_SUPERSPEED\_ENDPOINT\_DESCRIPTOR +description: EFI_USB_SUPERSPEED_ENDPOINT_DESCRIPTOR ms.assetid: 3254C0F1-85C2-472B-938A-F71645703540 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usb-superspeed-interface-info.md b/windows-driver-docs-pr/bringup/efi-usb-superspeed-interface-info.md index 4be2eb5774..6bae18a89b 100644 --- a/windows-driver-docs-pr/bringup/efi-usb-superspeed-interface-info.md +++ b/windows-driver-docs-pr/bringup/efi-usb-superspeed-interface-info.md @@ -1,7 +1,7 @@ --- -title: EFI\_USB\_SUPERSPEED\_INTERFACE\_INFO +title: EFI_USB_SUPERSPEED_INTERFACE_INFO author: windows-driver-content -description: EFI\_USB\_SUPERSPEED\_INTERFACE\_INFO +description: EFI_USB_SUPERSPEED_INTERFACE_INFO ms.assetid: 1B0C04D0-5254-4B9A-A94D-4FF1CEAD4627 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-device-info-id.md b/windows-driver-docs-pr/bringup/efi-usbfn-device-info-id.md index c7bd727e2e..8177ddeb1b 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-device-info-id.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-device-info-id.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_DEVICE\_INFO\_ID +title: EFI_USBFN_DEVICE_INFO_ID author: windows-driver-content -description: EFI\_USBFN\_DEVICE\_INFO\_ID +description: EFI_USBFN_DEVICE_INFO_ID ms.assetid: bc0391b4-876a-4c3c-920c-a16a781a84b0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-endpoint-direction.md b/windows-driver-docs-pr/bringup/efi-usbfn-endpoint-direction.md index be70459f22..6291eefd2e 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-endpoint-direction.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-endpoint-direction.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_ENDPOINT\_DIRECTION +title: EFI_USBFN_ENDPOINT_DIRECTION author: windows-driver-content -description: EFI\_USBFN\_ENDPOINT\_DIRECTION +description: EFI_USBFN_ENDPOINT_DIRECTION ms.assetid: 910f7ab5-b4c0-4385-9306-37d863d19bf7 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocol-configureenableendpointsex.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocol-configureenableendpointsex.md index c439bb0a61..4849c03411 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocol-configureenableendpointsex.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocol-configureenableendpointsex.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.ConfigureEnableEndpointsEx +title: EFI_USBFN_IO_PROTOCOL.ConfigureEnableEndpointsEx author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.ConfigureEnableEndpointsEx +description: EFI_USBFN_IO_PROTOCOL.ConfigureEnableEndpointsEx ms.assetid: 54DE0D7F-788F-49C3-AF5C-7EDAA0D09D20 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolaborttransfer.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolaborttransfer.md index ab599568fd..9a7d53d971 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolaborttransfer.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolaborttransfer.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.AbortTransfer +title: EFI_USBFN_IO_PROTOCOL.AbortTransfer author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.AbortTransfer +description: EFI_USBFN_IO_PROTOCOL.AbortTransfer ms.assetid: 204998d6-7d8d-482b-8d9c-b96d2e2729bf ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolallocatetransferbuffer.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolallocatetransferbuffer.md index a771a56a9a..6557b4b3b5 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolallocatetransferbuffer.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolallocatetransferbuffer.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.AllocateTransferBuffer +title: EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.AllocateTransferBuffer +description: EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer ms.assetid: dbaa4f18-97b5-4867-9e03-de19b2253722 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolconfigureenableendpoints.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolconfigureenableendpoints.md index 8933214cca..5d5565e0b2 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolconfigureenableendpoints.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolconfigureenableendpoints.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.ConfigureEnableEndpoints +title: EFI_USBFN_IO_PROTOCOL.ConfigureEnableEndpoints author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.ConfigureEnableEndpoints +description: EFI_USBFN_IO_PROTOCOL.ConfigureEnableEndpoints ms.assetid: 31bc58a0-ec2b-4b5e-ad1b-e6107cc083b1 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoldetectport.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoldetectport.md index 0bef77513c..86aa68fb19 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoldetectport.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoldetectport.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.DetectPort +title: EFI_USBFN_IO_PROTOCOL.DetectPort author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.DetectPort +description: EFI_USBFN_IO_PROTOCOL.DetectPort ms.assetid: 66f7500e-e075-495b-9ce0-aed2aa11f66a ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoleventhandler.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoleventhandler.md index e1e422bda8..beb165cd87 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoleventhandler.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoleventhandler.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.EventHandler +title: EFI_USBFN_IO_PROTOCOL.EventHandler author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.EventHandler +description: EFI_USBFN_IO_PROTOCOL.EventHandler ms.assetid: d493de90-cb8c-44d1-8999-f1ceb26e5c15 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolfreetransferbuffer.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolfreetransferbuffer.md index 29fe7aa126..d2ed27b039 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolfreetransferbuffer.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolfreetransferbuffer.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.FreeTransferBuffer +title: EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.FreeTransferBuffer +description: EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer ms.assetid: 236b925f-2c7b-4df8-b5c8-e8c2f7b853d2 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetdeviceinfo.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetdeviceinfo.md index f67f0ceca5..f842a1d2ff 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetdeviceinfo.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetdeviceinfo.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetDeviceInfo +title: EFI_USBFN_IO_PROTOCOL.GetDeviceInfo author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetDeviceInfo +description: EFI_USBFN_IO_PROTOCOL.GetDeviceInfo ms.assetid: b72f6ba1-7704-4661-8855-1ff88bd08e5a ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointmaxpacketsize.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointmaxpacketsize.md index eab3e1daa1..01fdb64366 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointmaxpacketsize.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointmaxpacketsize.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointMaxPacketSize +title: EFI_USBFN_IO_PROTOCOL.GetEndpointMaxPacketSize author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointMaxPacketSize +description: EFI_USBFN_IO_PROTOCOL.GetEndpointMaxPacketSize ms.assetid: 0af72372-7c58-490d-8eec-bd38bce09b0d ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointpolicy.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointpolicy.md index aee2714e85..28e1680b72 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointpolicy.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointpolicy.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointPolicy +title: EFI_USBFN_IO_PROTOCOL.GetEndpointPolicy author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointPolicy +description: EFI_USBFN_IO_PROTOCOL.GetEndpointPolicy ms.assetid: 143ee448-2c29-46f4-b62c-6429a4a1d890 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointstallstate.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointstallstate.md index a39719e117..1f51328e71 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointstallstate.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetendpointstallstate.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointStallState +title: EFI_USBFN_IO_PROTOCOL.GetEndpointStallState author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetEndpointStallState +description: EFI_USBFN_IO_PROTOCOL.GetEndpointStallState ms.assetid: abf53ee7-8460-4861-a82d-827ad1dc6c40 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetmaxtransfersize.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetmaxtransfersize.md index 12408e8af9..f921094d75 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetmaxtransfersize.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetmaxtransfersize.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetMaxTransferSize +title: EFI_USBFN_IO_PROTOCOL.GetMaxTransferSize author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetMaxTransferSize +description: EFI_USBFN_IO_PROTOCOL.GetMaxTransferSize ms.assetid: 61160708-029b-4691-87fe-22d06424220d ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetvendoridproductid.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetvendoridproductid.md index 1975961f82..6506cde89d 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetvendoridproductid.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolgetvendoridproductid.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.GetVendorIdProductId +title: EFI_USBFN_IO_PROTOCOL.GetVendorIdProductId author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.GetVendorIdProductId +description: EFI_USBFN_IO_PROTOCOL.GetVendorIdProductId ms.assetid: 78dbc589-3ffd-4ee2-9d80-4570b3b20b2f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointpolicy.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointpolicy.md index 626940bd67..38f6cb931d 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointpolicy.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointpolicy.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.SetEndpointPolicy +title: EFI_USBFN_IO_PROTOCOL.SetEndpointPolicy author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.SetEndpointPolicy +description: EFI_USBFN_IO_PROTOCOL.SetEndpointPolicy ms.assetid: d7ab0529-1925-47b5-9706-2e6288a6a5cf ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointstallstate.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointstallstate.md index d1b217d718..c5d2328dc4 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointstallstate.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolsetendpointstallstate.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.SetEndpointStallState +title: EFI_USBFN_IO_PROTOCOL.SetEndpointStallState author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.SetEndpointStallState +description: EFI_USBFN_IO_PROTOCOL.SetEndpointStallState ms.assetid: bd754296-5002-48b6-9986-fa09c2094470 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstartcontroller.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstartcontroller.md index 7b24642d8f..8cef8acf81 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstartcontroller.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstartcontroller.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.StartController +title: EFI_USBFN_IO_PROTOCOL.StartController author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.StartController +description: EFI_USBFN_IO_PROTOCOL.StartController ms.assetid: 431406c3-6b96-4815-a8a0-01100e8a5a5f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstopcontroller.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstopcontroller.md index 046a1ca9cd..4108ec3ed4 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstopcontroller.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocolstopcontroller.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.StopController +title: EFI_USBFN_IO_PROTOCOL.StopController author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.StopController +description: EFI_USBFN_IO_PROTOCOL.StopController ms.assetid: 531fd280-bcb1-4b6f-a2fa-9052318171b3 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoltransfer.md b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoltransfer.md index 4c164c926b..7016d6f48b 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoltransfer.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-io-protocoltransfer.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_IO\_PROTOCOL.Transfer +title: EFI_USBFN_IO_PROTOCOL.Transfer author: windows-driver-content -description: EFI\_USBFN\_IO\_PROTOCOL.Transfer +description: EFI_USBFN_IO_PROTOCOL.Transfer ms.assetid: 0585de75-9268-4964-8c5f-dcc3338e5287 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-message-payload.md b/windows-driver-docs-pr/bringup/efi-usbfn-message-payload.md index cbf87192a2..6f2531816f 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-message-payload.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-message-payload.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_MESSAGE\_PAYLOAD +title: EFI_USBFN_MESSAGE_PAYLOAD author: windows-driver-content -description: EFI\_USBFN\_MESSAGE\_PAYLOAD +description: EFI_USBFN_MESSAGE_PAYLOAD ms.assetid: 88d32ce1-460d-4c0f-b42a-426f42e2f969 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-message.md b/windows-driver-docs-pr/bringup/efi-usbfn-message.md index c6ad264a4a..d5f041d909 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-message.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-message.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_MESSAGE +title: EFI_USBFN_MESSAGE author: windows-driver-content -description: EFI\_USBFN\_MESSAGE +description: EFI_USBFN_MESSAGE ms.assetid: 411890e1-8913-4e47-acd5-1b36b1b05f34 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-policy-type.md b/windows-driver-docs-pr/bringup/efi-usbfn-policy-type.md index 02d4969bb7..000aee79db 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-policy-type.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-policy-type.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_POLICY\_TYPE +title: EFI_USBFN_POLICY_TYPE author: windows-driver-content -description: EFI\_USBFN\_POLICY\_TYPE +description: EFI_USBFN_POLICY_TYPE ms.assetid: 51f615d4-a226-45d5-b5e9-fea4859640a9 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-port-type.md b/windows-driver-docs-pr/bringup/efi-usbfn-port-type.md index 65bc417227..cbd51ad073 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-port-type.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-port-type.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_PORT\_TYPE +title: EFI_USBFN_PORT_TYPE author: windows-driver-content -description: EFI\_USBFN\_PORT\_TYPE +description: EFI_USBFN_PORT_TYPE ms.assetid: 2596dd4f-26bd-454b-9550-a89c7e1f790b ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-transfer-result.md b/windows-driver-docs-pr/bringup/efi-usbfn-transfer-result.md index 56d25f3a10..2e93bb0e11 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-transfer-result.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-transfer-result.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_TRANSFER\_RESULT +title: EFI_USBFN_TRANSFER_RESULT author: windows-driver-content -description: EFI\_USBFN\_TRANSFER\_RESULT +description: EFI_USBFN_TRANSFER_RESULT ms.assetid: d101b061-2a83-4bf8-9502-ccb6e56f5cea ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/efi-usbfn-transfer-status.md b/windows-driver-docs-pr/bringup/efi-usbfn-transfer-status.md index a3578fbaef..794a3ecfd3 100644 --- a/windows-driver-docs-pr/bringup/efi-usbfn-transfer-status.md +++ b/windows-driver-docs-pr/bringup/efi-usbfn-transfer-status.md @@ -1,7 +1,7 @@ --- -title: EFI\_USBFN\_TRANSFER\_STATUS +title: EFI_USBFN_TRANSFER_STATUS author: windows-driver-content -description: EFI\_USBFN\_TRANSFER\_STATUS +description: EFI_USBFN_TRANSFER_STATUS ms.assetid: 60631dad-a617-4ed4-a975-5e480cf324e3 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/esrt-table-definition.md b/windows-driver-docs-pr/bringup/esrt-table-definition.md index 888168f9f6..f36e21544d 100644 --- a/windows-driver-docs-pr/bringup/esrt-table-definition.md +++ b/windows-driver-docs-pr/bringup/esrt-table-definition.md @@ -1,7 +1,7 @@ --- title: ESRT table definition author: windows-driver-content -description: The pointer to the ESRT table is identified via its corresponding GUID in the EFI\_CONFIGURATION\_TABLE. +description: The pointer to the ESRT table is identified via its corresponding GUID in the EFI_CONFIGURATION_TABLE. ms.assetid: F332CCF3-AE6D-4B02-A63E-DB05910C8E6E ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/gpio-controller-device-specific-method---dsm-.md b/windows-driver-docs-pr/bringup/gpio-controller-device-specific-method---dsm-.md index ecdec1e0e9..5487c70ba2 100644 --- a/windows-driver-docs-pr/bringup/gpio-controller-device-specific-method---dsm-.md +++ b/windows-driver-docs-pr/bringup/gpio-controller-device-specific-method---dsm-.md @@ -1,7 +1,7 @@ --- -title: GPIO controller Device-Specific Method (\_DSM) +title: GPIO controller Device-Specific Method (_DSM) author: windows-driver-content -description: To support a variety of device-class-specific communications between the general-purpose I/O (GPIO) driver stack in Windows and the platform firmware, Microsoft defines a Device-Specific Method (\_DSM) that can be included under a GPIO controller in the ACPI namespace. +description: To support a variety of device-class-specific communications between the general-purpose I/O (GPIO) driver stack in Windows and the platform firmware, Microsoft defines a Device-Specific Method (_DSM) that can be included under a GPIO controller in the ACPI namespace. ms.assetid: 2891A78C-8C4F-4FE4-AB69-402F04DFA885 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/hidi2c-device-specific-method---dsm-.md b/windows-driver-docs-pr/bringup/hidi2c-device-specific-method---dsm-.md index f5ecf9bc1b..58901b3cf4 100644 --- a/windows-driver-docs-pr/bringup/hidi2c-device-specific-method---dsm-.md +++ b/windows-driver-docs-pr/bringup/hidi2c-device-specific-method---dsm-.md @@ -1,7 +1,7 @@ --- -title: HIDI2C Device-Specific Method (\_DSM) +title: HIDI2C Device-Specific Method (_DSM) author: windows-driver-content -description: The \_DSM method is defined in section 9.14.1, \ 0034;\_DSM (Device Specific Method) \ 0034;, in the ACPI 5.0 specification. +description: The _DSM method is defined in section 9.14.1, \ 0034;_DSM (Device Specific Method) \ 0034;, in the ACPI 5.0 specification. ms.assetid: D78077F4-9995-4DC6-9DF6-89D0F8E0C545 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/index.md b/windows-driver-docs-pr/bringup/index.md index bb93b4b110..9ac1604c29 100644 --- a/windows-driver-docs-pr/bringup/index.md +++ b/windows-driver-docs-pr/bringup/index.md @@ -10,14 +10,12 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# Bring up +# Bring up guide +> [!NOTE] +>  Some topics in this section may apply only to Windows 10 Mobile and certain processor architectures. -**Note**  Some information in this section may apply only to Windows 10 Mobile and certain processor architectures. - -  - -This section of the partner documentation is designed for hardware engineers and developers who need to understand how to get started with bringing up hardware on Windows 10. +This section of the partner documentation is designed for hardware engineers and developers who need to understand how to get started with bringing up hardware on Windows 10 and Windows Server 2016. ## In this section @@ -36,15 +34,15 @@ This section of the partner documentation is designed for hardware engineers and

[Boot and UEFI](boot-and-uefi.md)

-

Provides guidance about the boot process and UEFI implementation requirements for devices that run Windows 10.

+

Provides guidance about the boot process and UEFI implementation requirements for devices that run Windows 10 and Windows Server 2016.

[Windows ACPI design guide for SoC platforms](windows-acpi-design-guide-for-soc-platforms.md)

-

The Advanced Configuration and Power Interface Specification, Revision 5.0 ([ACPI 5.0 specification](http://www.acpi.info)), defines a new set of features to support low-power, mobile devices that are based on System on a Chip (SoC) integrated circuits and that implement the connected standby power model. Starting with Windows 8 and Windows 8.1, Windows supports the new ACPI 5.0 features for SoC-based platforms.

+

The Advanced Configuration and Power Interface Specification, Revision 5.0 ([ACPI 5.0 specification](http://www.acpi.info)), defines a new set of features to support low-power, mobile devices that are based on System on a Chip (SoC) integrated circuits and that implement the connected standby power model. Starting with Windows 8 and Windows 8.1, and Windows Server 2012 and 2012 R2, Windows supports the new ACPI 5.0 features for SoC-based platforms.

[Security](security-overview.md)

-

Use the topics in this section to learn more about security in Windows 10 Mobile.

+

Use the topics in this section to learn more about security in Windows 10 Mobile and Windows Server 2016.

[Windows 10 Mobile partition layout](partition-layout.md)

Learn how to configure storage partitions and partitions sizes on Windows 10 Mobile devices.

@@ -53,12 +51,6 @@ This section of the partner documentation is designed for hardware engineers and   - -  - -  - - -------------------- diff --git a/windows-driver-docs-pr/bringup/overview-of-windows-support-for-acpi-5-0.md b/windows-driver-docs-pr/bringup/overview-of-windows-support-for-acpi-5-0.md index aea441f344..e135795b84 100644 --- a/windows-driver-docs-pr/bringup/overview-of-windows-support-for-acpi-5-0.md +++ b/windows-driver-docs-pr/bringup/overview-of-windows-support-for-acpi-5-0.md @@ -13,14 +13,14 @@ ms.technology: windows-devices # Overview of Windows support for ACPI 5.0 -The [ACPI 5.0 specification](http://www.acpi.info) enables support of SoC-based mobile platforms that run Windows 8 and later, but continues to support many useful features that were introduced in earlier versions Windows. This design guide directs implementers to the parts of ACPI 5.0 that specifically apply to SoC-based platforms, and describes best practices for implementing the SoC-specific features in ACPI to run Windows on these platforms. +The [ACPI 5.0 specification](http://www.acpi.info) enables support of SoC-based mobile platforms that run Windows 8 and later, and enables and support of Windows Server 2016 and later, but continues to support many useful features that were introduced in earlier versions Windows. This design guide directs implementers to the parts of ACPI 5.0 that specifically apply to SoC-based platforms as well as for systems designed for Windows Server 2016, and describes best practices for implementing the SoC-specific features in ACPI to run Windows on these platforms. ## Scope -The target audience for this design guide is firmware developers and system designers who require guidance for firmware support and implementation. Observation and adherence to these guidelines will help ensure proper functionality of Windows on SoC platforms. +The target audience for this design guide is firmware developers and system designers who require guidance for firmware support and implementation. Observation and adherence to these guidelines will help ensure proper functionality of Windows on SoC platforms and Windows Server 2016 systems. -This design guidance specifically targets hardware-reduced ACPI platforms that support low-power S0 idle. However, most of the guidance also applies to any platform that is compliant with ACPI 5.0 and that runs Windows 8 or later. In addition, this topic assumes either a clamshell form factor or a wireless, multi-touch-only mobile platform. It therefore limits itself to technologies that are expected to be widely used on such platforms. For technologies that are not covered in this document, the reader is referred to the ACPI specification itself for implementation information. +This design guidance specifically targets hardware-reduced ACPI platforms that support low-power S0 idle. However, most of the guidance also applies to any platform that is compliant with ACPI 5.0 and that runs Windows 8 or later, or Windows Server 2012 or later. In addition, this topic assumes either a clamshell form factor or a wireless, multi-touch-only mobile platform. It therefore limits itself to technologies that are expected to be widely used on such platforms. For technologies that are not covered in this document, the reader is referred to the ACPI specification itself for implementation information. ## Firmware revision support diff --git a/windows-driver-docs-pr/bringup/secure-boot-and-device-encryption-overview.md b/windows-driver-docs-pr/bringup/secure-boot-and-device-encryption-overview.md index 8a3452fe98..96050b401c 100644 --- a/windows-driver-docs-pr/bringup/secure-boot-and-device-encryption-overview.md +++ b/windows-driver-docs-pr/bringup/secure-boot-and-device-encryption-overview.md @@ -1,10 +1,9 @@ --- title: Secure boot and device encryption overview -author: windows-driver-content -description: Secure boot and device encryption overview +description: This topic provides an overview of secure boot and device encryption functionality, with emphasis on key OEM requirements and considerations. ms.assetid: 4e206bd2-7bb4-48c2-9e01-8da041e798ef ms.author: windowsdriverdev -ms.date: 04/20/2017 +ms.date: 05/02/2017 ms.topic: article ms.prod: windows-hardware ms.technology: windows-devices @@ -15,6 +14,10 @@ ms.technology: windows-devices This topic provides an overview of secure boot and device encryption functionality, with emphasis on key OEM requirements and considerations. +**Applies to** + +- Windows 10 Mobile + ## Secure boot diff --git a/windows-driver-docs-pr/bringup/security-overview.md b/windows-driver-docs-pr/bringup/security-overview.md index 1e109b947f..c367768e45 100644 --- a/windows-driver-docs-pr/bringup/security-overview.md +++ b/windows-driver-docs-pr/bringup/security-overview.md @@ -75,22 +75,22 @@ The following table describes a subset of the SDL practices that are most useful

Driver

-

[FxCop](http://go.microsoft.com/fwlink/p/?LinkId=190283)

+

FxCop

FxCop is a static analyzer. It analyzes managed-code assemblies and reports information about the assemblies such as possible design, localization, performance, and security improvements.

Partner apps

-

[BinScope](http://go.microsoft.com/fwlink/p/?LinkId=190284)

+

BinScope

The BinScope Binary Analyzer is a verification tool that analyzes binaries to ensure that they have been built in compliance with the SDL requirements and recommendations. BinScope checks that SDL-required compiler/linker flags are being set, strong-named assemblies are in use, up-to-date build tools are in place, and the latest good ATL headers are being used. BinScope also reports on dangerous constructs that are prohibited by SDL.

Drivers and partner applications

-

[MiniFuzz](http://go.microsoft.com/fwlink/p/?LinkId=190286)

+

MiniFuzz

The MiniFuzz File Fuzzer is a basic testing tool designed to help detect issues that may expose security vulnerabilities in file-handling code. This tool could be helpful for developers that parse files in their apps.

Drivers and partner applications

-

[Banned.h](http://go.microsoft.com/fwlink/p/?LinkId=190287)

+

Banned.h

The banned.h header file is a sanitizing resource that supports the SDL requirement to remove banned functions from code. It lists all banned APIs and allows any developer to locate them in code.

Drivers and partner applications

@@ -100,10 +100,6 @@ The following table describes a subset of the SDL practices that are most useful     - -  - - -------------------- diff --git a/windows-driver-docs-pr/bringup/usb-device-specific-method---dsm-.md b/windows-driver-docs-pr/bringup/usb-device-specific-method---dsm-.md index 3e8784b59d..763eb2e01d 100644 --- a/windows-driver-docs-pr/bringup/usb-device-specific-method---dsm-.md +++ b/windows-driver-docs-pr/bringup/usb-device-specific-method---dsm-.md @@ -1,7 +1,7 @@ --- -title: USB Device-Specific Method (\_DSM) +title: USB Device-Specific Method (_DSM) author: windows-driver-content -description: To support device-class-specific configuration of the USB subsystem, Windows defines a Device-Specific Method (\_DSM) that has the functions that are described in this article. +description: To support device-class-specific configuration of the USB subsystem, Windows defines a Device-Specific Method (_DSM) that has the functions that are described in this article. ms.assetid: 8F0EDE17-9895-4C24-B061-963DA0D7882B ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/bringup/windows-acpi-design-guide-for-soc-platforms.md b/windows-driver-docs-pr/bringup/windows-acpi-design-guide-for-soc-platforms.md index c3445e21f2..21c437b5e7 100644 --- a/windows-driver-docs-pr/bringup/windows-acpi-design-guide-for-soc-platforms.md +++ b/windows-driver-docs-pr/bringup/windows-acpi-design-guide-for-soc-platforms.md @@ -38,7 +38,7 @@ This section contains guidelines for implementing Windows PCs and devices that s

[ACPI system description tables](acpi-system-description-tables.md)

-

Implementation of the Advanced Configuration and Power Interface (ACPI) Hardware Specification is not required on SoC-based platforms, but much of the ACPI Software Specification is (or can be) required. ACPI defines a generic, extensible table-passing mechanism, plus specific tables for describing the platform to the operating system.

+

Implementation of the Advanced Configuration and Power Interface (ACPI) Hardware Specification is not required on SoC-based platforms or Windows Server systems that are BIOS-based, but much of the ACPI Software Specification is (or can be) required. ACPI defines a generic, extensible table-passing mechanism, plus specific tables for describing the platform to the operating system.

[Device management namespace objects](device-management-namespace-objects.md)

diff --git a/windows-driver-docs-pr/bringup/windows-button-array-device-specific-method---dsm-.md b/windows-driver-docs-pr/bringup/windows-button-array-device-specific-method---dsm-.md index b8f35ba1a2..105e2727d6 100644 --- a/windows-driver-docs-pr/bringup/windows-button-array-device-specific-method---dsm-.md +++ b/windows-driver-docs-pr/bringup/windows-button-array-device-specific-method---dsm-.md @@ -1,7 +1,7 @@ --- -title: Windows button array Device-Specific Method (\_DSM) +title: Windows button array Device-Specific Method (_DSM) author: windows-driver-content -description: To support evolution of the Windows Button user interface (UI), Windows defines a Device-Specific Method (\_DSM) for the Windows button array device with the function that is described in this article. +description: To support evolution of the Windows Button user interface (UI), Windows defines a Device-Specific Method (_DSM) for the Windows button array device with the function that is described in this article. ms.assetid: B79ED0F9-B46A-4915-8FF3-5CF3D2E0E945 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/dashboard/TOC.md b/windows-driver-docs-pr/dashboard/TOC.md index bcd5d02fd5..78ce38bacc 100644 --- a/windows-driver-docs-pr/dashboard/TOC.md +++ b/windows-driver-docs-pr/dashboard/TOC.md @@ -23,7 +23,6 @@ ## [Legacy Dashboard](dashboard-services.md) ### [Get Started](get-started.md) ### [Dashboard FAQ](dashboard-faq.md) -### [Hardware Certification Submissions](hardware-certification-submissions.md) #### [Create a new WLK device certification submission](create-a-new-hardware-logo-submission.md) ##### [Winqual Submission Tool (winqual.exe)](winqual-submission-tool--winqualexe-.md) #### [Manage Hardware Submissions](manage-hardware-submissions.md) diff --git a/windows-driver-docs-pr/dashboard/attestation-signing-a-kernel-driver-for-public-release.md b/windows-driver-docs-pr/dashboard/attestation-signing-a-kernel-driver-for-public-release.md index f31702f49e..60ffdda5d8 100644 --- a/windows-driver-docs-pr/dashboard/attestation-signing-a-kernel-driver-for-public-release.md +++ b/windows-driver-docs-pr/dashboard/attestation-signing-a-kernel-driver-for-public-release.md @@ -13,16 +13,14 @@ ms.technology: windows-devices This topic describes how to sign a driver using attestation signing. - -**Important**  You must still use [Hardware Dev Center (Sysdev)](dashboard-services.md) to sign a driver using attestation signing until driver signing is available through the new Windows Hardware Dev Center dashboard. -   -**Note**  Attestation signing has the following properties. -- Attestation signing supports Windows 10 Desktop kernel mode and user mode drivers. Although user mode drivers do not need to be signed by Microsoft for Windows 10, the same attestation process can be used for both user and kernel mode drivers. -- Attestation signing requires the use of an EV Certificate to submit the driver to the Hardware Dev Center (Sysdev) dashboard. -- An attestation signed driver will only work for Windows 10 Desktop. It will not work for other versions of Windows, such as Windows Server 2016,Windows 8.1, or Windows 7. - +> [!Note]   +> Attestation signing has the following properties. +> - Attestation signing supports Windows 10 Desktop kernel mode and user mode drivers. Although user mode drivers do not need to be signed by Microsoft for Windows 10, the same attestation process can be used for both user and kernel mode drivers. +> - Attestation signing requires the use of an EV Certificate to submit the driver to the Hardware Dev Center (Sysdev) dashboard. +> - An attestation signed driver will only work for Windows 10 Desktop. It will not work for other versions of Windows, such as Windows Server 2016,Windows 8.1, or Windows 7. +> - Attestation signing requires driver folder names to contain no special characters, and to be less than 40 characters long.   ## Attestation Signing a Kernel Mode Driver @@ -104,7 +102,7 @@ MAKECAB [/V[n]] [/D var=value ...] /F directive_file [...] ``` ;*** Echo.ddf example ; -.OPTION EXPLICIT ; Generate errors +.OPTION EXPLICIT ; Generate errors .Set CabinetFileCountThreshold=0 .Set FolderFileCountThreshold=0 .Set FolderSizeThreshold=0 @@ -117,7 +115,7 @@ MAKECAB [/V[n]] [/D var=value ...] /F directive_file [...] ;Specify file name for new cab file .Set CabinetNameTemplate=Echo.cab ; Specify the subdirectory for the files. -; Your cab file should not have files at the root level, +; Your cab file should not have files at the root level, ; and each driver package must be in a separate subfolder. .Set DestinationDir=Echo ;Specify files to be included in cab file @@ -242,7 +240,7 @@ Prepare a cab file DDF input file that references the subdirectories. It might l ``` ;*** Submission.ddf multiple driver example ; -.OPTION EXPLICIT ; Generate errors +.OPTION EXPLICIT ; Generate errors .Set CabinetFileCountThreshold=0 .Set FolderFileCountThreshold=0 .Set FolderSizeThreshold=0 @@ -272,7 +270,3 @@ Follow the steps previously described to sign, submit and test the driver files.   [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhw_dashboard\hw_dashboard%5D:%20Attestation%20signing%20a%20kernel%20driver%20for%20public%20release%20%20RELEASE:%20%281/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") - - - - diff --git a/windows-driver-docs-pr/dashboard/create-a-new-hardware-submission.md b/windows-driver-docs-pr/dashboard/create-a-new-hardware-submission.md index 49ed986201..39c3e012f8 100644 --- a/windows-driver-docs-pr/dashboard/create-a-new-hardware-submission.md +++ b/windows-driver-docs-pr/dashboard/create-a-new-hardware-submission.md @@ -31,13 +31,15 @@ For information about creating and digitally signing an **.hckx** file, see the 3. Either drag and drop, or browse to the **.hlkx/.hckx** file that you want to submit. The file will begin to upload. ![screenshot that shows the driver name field](images/drivers-name.png) -4. Select any applicable additional certifications if available. This option allows you to specify which down-level operating system signatures should be included with your driver. Available certifications vary depending on your driver submission package, so there may not be any certifications listed. +4. If you wish to test a driver prior to release, you can select the checkbox labled "perform test-signing only". Test-signed drivers are similar to drivers signed for public release, but do not require HLK testing. They are also not distributed through Windows Update, but can be downloaded from the hardware submission site. For more information about test-signing driver packages, see [WHQL Test Signature Program](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/whql-test-signature-program) and [How to test-sign a driver package](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/how-to-test-sign-a-driver-package). -5. Select **Finalize**. You will not be able to select the **Finalize** button until your file upload is complete. Note: Your signature properties and name cannot be changed after you click **Finalize**. +5. Select any applicable additional certifications if available. This option allows you to specify which down-level operating system signatures should be included with your driver. Available certifications vary depending on your driver submission package, so there may not be any certifications listed. + +6. Select **Finalize**. You will not be able to select the **Finalize** button until your file upload is complete. Note: Your signature properties and name cannot be changed after you click **Finalize**. ![screenshot that shows possible certifications for a driver submission, and the finalize button](images/additionalcertifications.png) -6. In the **Certification** section, complete the following information: +7. In the **Certification** section, complete the following information: @@ -86,15 +88,15 @@ For information about creating and digitally signing an **.hckx** file, see the ![screenshot that shows the certification section](images/drivers-certification.png) -7. Select **Submit**. +8. Select **Submit**. -8. The **Distribution** section is used to publish your driver to Windows Update. For information about how to use the **Distribution** section, see [Manage driver distribution with shipping labels](manage-driver-distribution-by-submission.md). +9. The **Distribution** section is used to publish your driver to Windows Update. For information about how to use the **Distribution** section, see [Manage driver distribution with shipping labels](manage-driver-distribution-by-submission.md). -9. You can monitor the progress of your submission with the progress tracker at the top of the page. Once all steps show a green check, the submission is complete and your organization will receive a notification in the dashboard header. +10. You can monitor the progress of your submission with the progress tracker at the top of the page. Once all steps show a green check, the submission is complete and your organization will receive a notification in the dashboard header. ![screenshot that shows the progress tracker](images/drivers-allgreen-new.png) -10. Review the results. If your submission failed, make any necessary changes and resubmit. +11. Review the results. If your submission failed, make any necessary changes and resubmit. ## Related topics diff --git a/windows-driver-docs-pr/dashboard/dashboard-faq.md b/windows-driver-docs-pr/dashboard/dashboard-faq.md index a52efd0088..b3a95018f3 100644 --- a/windows-driver-docs-pr/dashboard/dashboard-faq.md +++ b/windows-driver-docs-pr/dashboard/dashboard-faq.md @@ -57,22 +57,21 @@ This includes both EV and Standard – there is no restriction on the number of - + - + - +
Hardware certification

Windows Certification Program Testing Agreement v1.0

-

Windows Logo License Agreement for Hardware 2017

Windows Hardware Compatibility Program Test Agreement (Required)

+

Windows Logo License Agreement for Hardware 2017*

Software certification

Windows Certification Program Testing Agreement v1.0

-

Windows Logo License Agreement For Software v1.9

Windows Hardware Compatibility Program Test Agreement (Required)

+

Windows Logo License Agreement For Software v1.9*

File driver signing

Windows Compatibility Program and Driver Quality Attestment Testing Agreement

-

Windows Certification Program Testing Agreement v1.0

Windows Compatibility Program and Driver Quality Attestment Testing Agreement (Required)

- +*These agreements are optional unless you are using features or asssts in the associated agreement.   ### How do I sign legal agreements? @@ -127,13 +126,13 @@ Check that the announcement date that has been set. If it is not, set the date f In an effort to make Windows 10 more secure without affecting performance, all binaries now receive embedded signatures. This applies to all the submissions submitted for certification, not only submissions based on Windows 10. -### How to get a single cat file if drivers are uniform for all operating systems +### How do I get a single cat file if my drivers are uniform for all operating systems? Make sure your final package has a single driver folder on the **Package** tab and the driver’s properties include all the operating systems you have tested. ![package tab](images/packagetab.png) -### Unable to add new marketing names to the approved submission +### I'm unable to add new marketing names to the approved submission. Please check the announcement date that has been set. If the announcement date set has passed, you will be not able to add a new name. You need to contact [Sysdev@Microsoft.com](http://go.microsoft.com/fwlink/p/?LinkID=624170). diff --git a/windows-driver-docs-pr/dashboard/file-a-new-bug.md b/windows-driver-docs-pr/dashboard/file-a-new-bug.md index 06d525c7ae..e013ea7df3 100644 --- a/windows-driver-docs-pr/dashboard/file-a-new-bug.md +++ b/windows-driver-docs-pr/dashboard/file-a-new-bug.md @@ -115,38 +115,50 @@ You can create a new bug online, and then submit it to be filed with Microsoft. -   +5. Click **Browse** below the Attachments label to attach a file to the bug. (Recommended) -5. Click **Browse** below the Attachments label to attach a file to the bug. (Optional) + Attaching data at the time of bug submission helps us efficiently manage the bug process toward closure. Please use the appropriate process below for the specific issue being reported. - Please include all files as appropriate so that Microsoft can analyze the issue quickly. For Windows deployment/setup issues, please attach the following files in zip format to speed up the diagnosis: + **For Windows Phone and IoT(ARM) devices**: + Please download the [FieldMedic tool](http://www.windowsphone.com/en-us/store/app/field-medic/73c58570-d5a7-46f8-b1b2-2a90024fc29c) and run it on the devices that reproduce the issue you are reporting. + > [!NOTE] + > Be sure that all providers associated with the problem you are reporting are enabled. This can be done by going to the **Advanced** menu within Field Medic, and selecting **Choose which ETW Providers ...**. - ``` syntax - %windir%\Panther\*.* - %windir%\inf\setupap.dev.log - %windir%\winsxs\popexec.log - %windir%\inf\setupapi.dev.log - %windir%\logs\cbs\cbs.log - %windir%\windowsupdate.log - %windir%\winsxs\pending*.xml - %windir%\*.dmp (if BSOD issue) - ``` + **For Windows x86 and x64**: Please use the log collection tool, [UCSLogTool](https://www.microsoft.com/en-us/download/details.aspx?id=54322), posted on Connect and Microsoft Download Center. This tool will gather logs and traces relevant to the specific feature area selected. Follow these steps to use the tool: - For Display/GPU-related issues please include: + 1. Download and install UCSLogTool on the problem device. When the installation is complete, start the tool using the desktop short-cut. - ``` syntax - dxdiag log [start - dxdiag.exe - save all info] - dispdiag log [run dispdiag.exe from command-prompt and send the .DAT file] - ``` + 2. After UCSLogTool starts, you’ll be presented with a user interface in the Command Prompt. Locate the scenario or feature that’s closest to the problem you’re reporting, enter the corresponding number, and then press Enter. -6. When all information is complete, click **Save** at the top of the form. + 3. After you’ve selected the scenario to be traced, a list of the selected features will be displayed. You can view additional features by entering **Y**, or continue by entering **N**. -  + 4. By default, any feature that’s selected will also include the General windows log collection feature. Please confirm that the correct traces have been selected, and then follow the prompts to either add additional features or to continue with the current selection. -  + 5. You’ll be prompted to keep the temporary folder containing a copy of the trace data. Follow the prompt, and press Enter. -[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhw_dashboard\hw_dashboard%5D:%20File%20a%20New%20Bug%20%20RELEASE:%20%281/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + > [!NOTE] + > Many UCSLogTool features will open in a new window to capture their respective traces. When this occurs, follow the instructions in the new window, and then return to the UCSLogTool command window for the final steps. + + 6. After the tool collects the traces, the collected trace data and logs will be compressed into a single ZIP file on the desktop (for example, `GeneralDataCollection_15063.rs2_release.170317-1834.zip`). + > [!IMPORTANT] + > Do not rename the file. Renaming the file will interfere with the automated processes that check it for validity + 7. Attach this .zip file to the bug + > [!NOTE] + > If you are unable to execute the USCLogTool due to the system state, run the script manually by doing the following: + 1. Download and install the UCSLogTool on a working system. + 2. Copy the "UCSLogTool" directory (typically C:\Program Files\UCSLogTool) and its contents onto a USB Flash Drive. + 3. Connect the flash drive to the problem system when booted to OOBE or Windows PE. + 4. Press Shift+F10 on the keyboard to get to a command prompt. + 5. Change directory to the location on the USB Flash Drive that UCSLogTool was copied to. + 6. Run the following script manually to collect the General Windows log collection: `UCSLogTool\WINDOWS_LOG\GetLogs.cmd LOGDIR` + 7. After the tool collects the data, copy the data onto the flash drive and attach to the bug in a ZIP file format. + We recommend submitting a memory dump file when the problem system is in a non-responsive state. This file will help Microsoft investigate the issue you are encountering. + +6. When all information is complete, click **Save** at the top of the form. + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhw_dashboard\hw_dashboard%5D:%20File%20a%20New%20Bug%20%20RELEASE:%20%281/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/dashboard/hardware-dashboard-faq.md b/windows-driver-docs-pr/dashboard/hardware-dashboard-faq.md index c0b02e3bad..1b4f049286 100644 --- a/windows-driver-docs-pr/dashboard/hardware-dashboard-faq.md +++ b/windows-driver-docs-pr/dashboard/hardware-dashboard-faq.md @@ -24,7 +24,10 @@ There is no restriction on the number of certificates (both EV and Standard) ass ## What agreements need to be signed? -The following agreements can be signed as part of the registration process: +The following agreements can be signed as part of the registration process. + +> [!NOTE] +> Signing the Windows Hardware Compatibility Program Test Agreement is a requirement for all registrations. All other agreements are optional unless you are using features or assets in the other associated agreements. - Windows Hardware Compatibility Program Test Agreement (ver 2.0) @@ -46,10 +49,6 @@ See [Managing User Roles](managing-user-roles.md) for more information. All hardware submissions to the dashboard will be processed within five business days or less, depending on whether the submission requires manual review. Manual review may be required if your submission's tests fail, if it does not have a valid filter applied, or due to internal business policy. -### How do I get my product listed on Windows Compatible Products List? - -Check that the announcement date that has been set. If it is not, set the date for either the current date or your preferred date. The product will be listed the day after the date you set. - ### Why do I see a difference in download signed files? In order to make Windows 10 more secure without affecting performance, all binaries are now receiving embedded signatures. This applies to all submissions for certification, not only Windows 10 submissions. @@ -62,6 +61,21 @@ Make sure your final package has a single driver folder on the **Package** tab a Check the announcement date that has been set. If the announcement date has passed, you won't be able to add a new name. +### How can I share a link to a Windows Certification Verification Report? +- A sharable URL contains three identification numbers separated by slashes as shown below: `https://developer.microsoft.com/dashboard/hardware/driver/DownloadCertificationReport/SellerID/PrivateProductID/SubmissionID` + +- The identification numbers used in the URL, and their locations are as follows: + +| Component | Description | +| --- | --- | +|SellerID | The identification number of your partner account. This can be found on the account management page, under **Account settings**. | +|PrivateProductID | The identification number generated with each product creation. Located on the driver details page for your product. See [Dashboard ID definitions](https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/id-definitions) for more information. | +|SubmissionID | The idenfication number given to each submission and submission update. Located on the driver details page for your product. See [Dashboard ID definitions](https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/id-definitions) for more information. | + +- To create a sharable link, replace **SellerID**, **PrivateProductID**, and **SubmissionID** in the example URL above with the appropriate identification numbers. +- This URL allows the report to be accessed and downloaded without prior authorization or access to the Windows Hardware Dev Center Dashboard. + + ## Troubleshooting submission upload errors @@ -73,7 +87,7 @@ The failure is caused by an incorrect .cab file structure. The .cab structure wa If you continue to experience issues with your package submission, contact Support in the dashboard header. -### File is using Zip64(4gb+file Size) +### "File is using Zip64(4gb+file Size)" This error is caused when the uploaded archive's filetype is .zip64 instead of .zip. This is caused by a large filesize. To fix this error, repackage the submission using the below steps. diff --git a/windows-driver-docs-pr/dashboard/id-definitions.md b/windows-driver-docs-pr/dashboard/id-definitions.md index 725aaab061..a52347babb 100644 --- a/windows-driver-docs-pr/dashboard/id-definitions.md +++ b/windows-driver-docs-pr/dashboard/id-definitions.md @@ -37,10 +37,10 @@ The Windows Hardware Dev Center Dashboard lists each of these IDs on the driver

Private Product ID

-

The private product ID is the top level identifier that is generated with each new product creation. This ID is most useful for personal reference of specific products, and predicting their URLs.

- +

The private product ID is the top level identifier that is generated with each new product creation. This ID is most useful for personal reference of specific products, and predicting their URLs. > [!NOTE] > when you share a driver with someone else, they will be assigned a new private product ID. If you want to communicate about a product, use the Shared Product ID. +

diff --git a/windows-driver-docs-pr/dashboard/images/drivers-name.png b/windows-driver-docs-pr/dashboard/images/drivers-name.png index fbc4a38843..e86e6f68d6 100644 Binary files a/windows-driver-docs-pr/dashboard/images/drivers-name.png and b/windows-driver-docs-pr/dashboard/images/drivers-name.png differ diff --git a/windows-driver-docs-pr/dashboard/images/win-cloud-checkboxes.png b/windows-driver-docs-pr/dashboard/images/win-cloud-checkboxes.png new file mode 100644 index 0000000000..de8b8fbd1e Binary files /dev/null and b/windows-driver-docs-pr/dashboard/images/win-cloud-checkboxes.png differ diff --git a/windows-driver-docs-pr/dashboard/index.md b/windows-driver-docs-pr/dashboard/index.md index 681001a6b4..48ff3b6655 100644 --- a/windows-driver-docs-pr/dashboard/index.md +++ b/windows-driver-docs-pr/dashboard/index.md @@ -26,19 +26,20 @@ The Windows Hardware Dev Center dashboard replaces the [Hardware Dev Center (Sys - Sharing your driver with another company (Resell) - Customizing your driver after initial certification (DUA) - Managing your users and legal agreements +- System/Hardware certification submissions ## Currently unsupported tasks You must continue to use [Hardware Dev Center (Sysdev)](dashboard-services.md) to complete the following tasks. -**Important**  The dashboard submission REST APIs will no longer be available for use as of November 10th, 2016. APIs for driver submissions are under consideration for a future release. +> [!IMPORTANT]   +> The dashboard submission REST APIs will no longer be available for use as of November 10th, 2016. APIs for driver submissions are under consideration for a future release.   - [WLK device certification submissions](https://go.microsoft.com/fwlink/?linkid=830380) - [Attestation signing](attestation-signing-a-kernel-driver-for-public-release.md) -- [System certification submissions](https://go.microsoft.com/fwlink/?linkid=830382) - [Device Metadata](https://go.microsoft.com/fwlink/?linkid=830383) - [Bug management](https://go.microsoft.com/fwlink/?linkid=830385) - [Remote Debugging](https://go.microsoft.com/fwlink/?linkid=830386) (WRD) @@ -52,10 +53,10 @@ This transition timeframe table contains estimates of when features will be avai | Task | Transition timeframe | |--------------------------------------|----------------------| -| WLK device certification submissions | 2017 | -| Attestation signing | End of 2016 | -| Hardware certification submissions | 2017 | -| UEFI and LSA | To be scheduled | +| WLK device certification submissions | End of 2017 | +| Attestation signing | January 2016 | +| Hardware certification submissions | End of 2017 | +| UEFI and LSA | Early 2018 | | Device metadata | To be scheduled | | Bug management | To be scheduled | | Remote debugging (WRD) | To be scheduled | @@ -77,7 +78,3 @@ This transition timeframe table contains estimates of when features will be avai   [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhw_dashboard\hw_dashboard%5D:%20Windows%20Hardware%20Dev%20Center%20dashboard%20%20RELEASE:%20%281/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") - - - - diff --git a/windows-driver-docs-pr/dashboard/publish-a-driver-to-windows-update.md b/windows-driver-docs-pr/dashboard/publish-a-driver-to-windows-update.md index d5a9ceed45..0b66a6bd74 100644 --- a/windows-driver-docs-pr/dashboard/publish-a-driver-to-windows-update.md +++ b/windows-driver-docs-pr/dashboard/publish-a-driver-to-windows-update.md @@ -81,11 +81,25 @@ To publish a driver to Windows Update, [create a hardware submission](create-a-n ![screenshot that shows targeting section and pnps](images/publish-targeting-windows-update.png) -7. If you want to add Computer Hardware IDs (CHIDs), enter each CHID into the text box and select **Add CHID(s)**. To bulk add multiple CHIDs, ensure that each CHID is separated by a newline, select **Add multiple CHIDs**, and paste your CHIDs into the text box. You can view all added CHIDs in the list below the text box. +7. If you want to add Computer Hardware IDs (CHIDs), enter each CHID into the text box and select **Add CHID(s)**. To bulk add multiple CHIDs, ensure that each CHID is separated by a newline, select **Add multiple CHIDs**, and paste your CHIDs into the text box. You can view all added CHIDs in the list below the text box. To remove a CHID from the list, select **Remove** - To remove a CHID from the list, select **Remove** +> [!NOTE] +> CHIDs are not supported for all versions of Windows. Do not add CHIDs if your driver targets the following operating systems: +> * Windows 8.1 or earlier +> * Windows Server 2012 R2 or earlier -8. Select **Publish** to send your request to Windows Update. If you do not want to publish the shipping label right now, you can select **Save**. You can publish the shipping label later by either opening the shipping label and selecting **Publish**, or you can select **Publish all pending** from the hardware submission page. Note that selecting **Publish all pending** will publish all unpublished shipping labels. + + + +8. If your driver targets Windows 10 S, you must select both boxes, confirming the following: + + * Your driver is compatible with and follows the driver policies outlined in the [Windows 10 S Driver Requirements](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/Windows10SDriverRequirements). + * You verify that your driver follows the additional code integrity policies outlined in the Windows 10 S guidelines. + * Your driver does not contain any non-Microsoft UI components or applications in the driver package. + + ![A screenshot of the two checkboxes you must select when submitting a driver for Windows 10 S](images/win-cloud-checkboxes.png) + +9. Select **Publish** to send your request to Windows Update. If you do not want to publish the shipping label right now, you can select **Save**. You can publish the shipping label later by either opening the shipping label and selecting **Publish**, or you can select **Publish all pending** from the hardware submission page. Note that selecting **Publish all pending** will publish all unpublished shipping labels.   diff --git a/windows-driver-docs-pr/dashboard/register-for-the-hardware-program.md b/windows-driver-docs-pr/dashboard/register-for-the-hardware-program.md index 9b449bc778..3c2d1df4b0 100644 --- a/windows-driver-docs-pr/dashboard/register-for-the-hardware-program.md +++ b/windows-driver-docs-pr/dashboard/register-for-the-hardware-program.md @@ -32,7 +32,7 @@ Review the following requirements before you start the registration process. ## Registration steps -There are four main steps to the Hardware Program registration. +There are five main steps to the Hardware Program registration. 1. Get a code signing certificate @@ -40,23 +40,24 @@ There are four main steps to the Hardware Program registration. - If you do not have a certificate, you must buy one and have it available. -2. Sign and upload a file +2. Download signtool.exe + - signtool.exe is available as part of the [Windows SDK download](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) - - Download the provided signable file. +3. Sign and upload a file + > [!NOTE] + > The following three steps no longer need to be completed within the same browser session. + + 1. Download the provided signable file. + 2. Sign the file with signtool.exe and your code signing certificate. + 3. Upload the signed file. Your company name and ID number is extracted from the signed file. - - Download the signtool.exe signing tool. The tool is available as part of the [Windows SDK download](http://go.microsoft.com/fwlink/p/?linkid=84091). - - - Sign the signable file with your code signing certificate. - - - Upload the signed file. Your company name and ID number is extracted from the signed file. - -3. Sign in with an Azure AD Global administrator account +4. Sign in with an Azure AD Global administrator account - If your company already has an Azure AD directory, sign in with a [Global administrator](http://go.microsoft.com/fwlink/?LinkId=746654) account. - If your company does not have an Azure AD directory, you must create one and sign in. -4. Account details +5. Account details - Enter in account details, such as company display name and personal contact information. diff --git a/windows-driver-docs-pr/dashboard/windows-certified-products-list.md b/windows-driver-docs-pr/dashboard/windows-certified-products-list.md index 138080279e..18b98de754 100644 --- a/windows-driver-docs-pr/dashboard/windows-certified-products-list.md +++ b/windows-driver-docs-pr/dashboard/windows-certified-products-list.md @@ -16,6 +16,11 @@ The [Windows Certified Products List](http://sysdev.microsoft.com/hardware/lpl/) You can find devices and systems by filtering the list or by running a search for a specific product name. + +> [!IMPORTANT] +> The Windows Certified Products List only exists on the legacy dashboard, and does not include submissions made through the Windows Hardware Dev Center Dashboard. + + ### To find a product by searching To find a product by searching (in this case, Arc Mouse), follow these steps: @@ -28,12 +33,12 @@ To find a product by searching (in this case, Arc Mouse), follow these steps: 4. Click the product name to get further details about the product. The list of details includes the product name, company, compatibility status, product type, and certification status. -**Note**   -Search is limited to **Product Name** and **Company**. +> [!Note]   +> Search is limited to **Product Name** and **Company**. -Search will run an AND operation on any word entered in the **Search** box. +> Search will run an AND operation on any word entered in the **Search** box. -Search treats multiple words enclosed in quotation marks as one search string. +> Search treats multiple words enclosed in quotation marks as one search string.   @@ -67,10 +72,6 @@ To view a Windows Certification Verification Report: - On the Details page of a product, click any of the links in the **Verification report** section. The Certification Verification Report will open in PDF format. -### To get listed on the Windows Certified Products List - -The only way for vendors to ensure a listing on the Windows Certified Products List is to submit their products to the Hardware Dev Center Dashboard for certification. For more information, see [Hardware Certification Submissions](https://msdn.microsoft.com/library/windows/hardware/br230796.aspx). -     diff --git a/windows-driver-docs-pr/debugger/-----------------------a---run-script-file-.md b/windows-driver-docs-pr/debugger/-----------------------a---run-script-file-.md new file mode 100644 index 0000000000..8ab8f623c7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-----------------------a---run-script-file-.md @@ -0,0 +1,198 @@ +--- +title: $ , $ , $$ , $$ , $$ a (Run Script File) +description: The $ , $ , $$ , $$ , and $$ a commands read the contents of the specified script file and use its contents as debugger command input. +ms.assetid: b3584680-765d-4aaf-ad43-c7d73552e5fb +keywords: ["$ (Run Script File) command", "$$ (Run Script File) command", "$$ (Run Script File) command", "Run Script File ($ ) command", "Run Script File ($ ) command", "Run Script File ($$ ) command", "Run Script File ($$ ) comm", "$ , $ , $$ , $$ , $$ a (Run Script File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- $ , $ , $$ , $$ , $$ a (Run Script File) +api_type: +- NA +--- + +# $<, $><, $$<, $$><, $$ >a< (Run Script File) + + +The **$<**, **$><**, **$$<**, **$$><**, and **$$>a<** commands read the contents of the specified script file and use its contents as debugger command input. + +``` +$aParameters + + + *Filename* +Specifies a file that contains valid debugger command text. The file name must follow Microsoft Windows file name conventions. The file name may contain spaces. + + *argn* +Specifies any number of string arguments for the debugger to pass to the script. The debugger will replace any string of the form ${$arg*n*} in the script file with the corresponding *argn* before executing the script. Arguments may not contain quotation marks or semicolons. Multiple arguments must be separated by spaces; if an argument contains a space it must be enclosed in quotation marks. All arguments are optional. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **$$<** and **$<** tokens execute the commands that are found in the script file literally. However, with **$<** you can specify any file name, including one that contains semicolons. Because **$<** allows semicolons to be used in the file name, you cannot concatenate **$<** with other debugger commands, because a semicolon cannot be used both as a command separator and as part of a file name. + +The **$$><** and **$><** tokens execute the commands that are found in the script file literally, which means they open the script file, replace all carriage returns with semicolons, and execute the resulting text as a single command block. As with **$<** discussed previously, the **$><** variation permits file names that contains semicolons, which means you cannot concatenate **$><** with other debugger commands. + +The **$$><** and **$><** tokens are useful if you are running scripts that contain debugger command programs. For more information about these programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Unless you have file names that contain semicolons, you do not need to use either **$<** or **$><**. + +The **$$>a<** token allows the debugger to pass arguments to the script. If *Filename* contains spaces, it must be enclosed in quotation marks. If too many arguments are supplied, the excess arguments are ignored. If too few arguments are supplied, any token in the source file of the form ${$arg*n*} where *n* is larger than the number of supplied arguments will remain in its literal form and will not be replaced with anything. You can follow this command with a semicolon and additional commands; the presence of a semicolon terminates the argument list. + +When the debugger executes a script file, the commands and their output are displayed in the [Debugger Command window](debugger-command-window.md). When the end of the script file is reached, control returns to the debugger. + +The following table summarizes how you can use these tokens. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TokenAllows file names that contain semicolonsAllows concatenation of additional commands separated by semicolonsCondenses to single command blockAllows script arguments

$<

Yes

No

No

No

$><

Yes

No

Yes

No

$$<

No

Yes

No

No

$$><

No

Yes

Yes

No

$$>a<

No

Yes

Yes

Yes

+ +  + +The **$<**, **$><**, **$$<**, and **$$><** commands echo the commands contained in the script file and display the output of these commands. The **$$>a<** command does not echo the commands found in the script file, but merely displays their output. + +Script files can be nested. If the debugger encounters one of these tokens in a script file, execution moves to the new script file and returns to the previous location when the new script file has been completed. Scripts can also be called recursively. + +In WinDbg, you can paste the additional command text in the Debugger Command window. + +Examples +-------- + +The following example demonstrates how to pass arguments to a script file, Myfile.txt. Assume that the file contains the following text: + +``` +.echo The first argument is ${$arg1}. +.echo The second argument is ${$arg2}. +``` + +Then you can pass arguments to this file by using a command like this: + +``` +0:000> $$>a $$>a< "c:\binl\my script.txt" "First one" Two "Three More" Four; recx +The first argument is First one. +The fifth argument is ${$arg5}. +The fourth argument is Four. +ecx=0021f4ac +``` + +In the preceding example, the file name is enclosed in quotation marks because it contains a space, and arguments that contain spaces are enclosed in quotation marks as well. Although a fifth argument seems to be expected by the script, the semicolon terminates the **$$>a<** command after the fourth argument. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20$<,%20$><,%20$$<,%20$$><,%20$$>a<%20%28Run%20Script%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-------alias-interpreter-.md b/windows-driver-docs-pr/debugger/-------alias-interpreter-.md new file mode 100644 index 0000000000..70922dbbac --- /dev/null +++ b/windows-driver-docs-pr/debugger/-------alias-interpreter-.md @@ -0,0 +1,75 @@ +--- +title: $ (Alias Interpreter) +description: A dollar sign followed by a pair of braces ( $ ) evaluates to a variety of values related to the specified user-named alias. +ms.assetid: 5182ed99-259e-4e58-8d69-38a702bd8113 +keywords: ["$ (Alias Interpreter) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- $ (Alias Interpreter) +api_type: +- NA +--- + +# ${ } (Alias Interpreter) + + +A dollar sign followed by a pair of braces ( **${ }** ) evaluates to a variety of values related to the specified user-named alias. + +``` +Text ${Alias} Text +Text ${/d:Alias} Text +Text ${/f:Alias} Text +Text ${/n:Alias} Text +Text ${/v:Alias} Text +``` + +## Parameters + + +*Alias* +Specifies the name of the alias to be expanded or evaluated. *Alias* must be a user-named alias or the *Variable* value used by the [**.foreach**](-foreach.md) token. + +**/d** +Evaluates to one or zero depending on whether the alias is currently defined. If the alias is defined, **${/v:***Alias***}** is replaced by 1; if the alias is not defined, **${/v:***Alias***}** is replaced by 0. + +**/f** +Evaluates to the alias equivalent if the alias is currently defined. If the alias is defined, **${/f:***Alias***}** is replaced by the alias equivalent; if the alias is not defined, **${/f:***Alias***}** is replaced by an empty string. + +**/n** +Evaluates to the alias name if the alias is currently defined. If the alias is defined, **${/n:***Alias***}** is replaced by the alias name; if the alias is not defined, **${/n:***Alias***}** is not replaced but retains its literal value of **${/n:***Alias***}**. + +**/v** +Prevents any alias evaluation. Regardless of whether *Alias* is defined, **${/v:***Alias***}** always retains its literal value of **${/v:***Alias***}**. + +### Additional Information + +For an explanation of how to use aliases, see [Using Aliases](using-aliases.md). + +Remarks +------- + +If no switches are used and the alias is currently defined, **${***Alias***}** is replaced by the alias equivalent. If no switches are used and the alias is not defined, **${***Alias***}** always retains its literal value of **${***Alias***}**. + +One advantage of using the **${ }** token is that the alias will be evaluated even if it is adjacent to other characters. Without this token, the debugger only replaces aliases that are separated from other tokens by a space. + +As indicated, there are circumstances where the **${ }** token is not replaced by anything but retains its literal value. This occurs when no switch is used and *Alias* is undefined, when the **/n** switch is used and *Alias* is undefined, and always when the **/v** switch is used. In these circumstances, the token retains its literal value, including the dollar sign and the braces. Therefore, if this is used as the parameter of a command, a syntax error will result, unless that parameter accepts arbitrary text strings. + +There is, however, one exception to this. If you use **${/v:***Alias***}** as the first parameter to the [**as (Set Alias)**](as--as--set-alias-.md) or **aS (Set Alias)** command, this token will be treated as the string *Alias* alone, not as the string **${/v:***Alias***}**. This only works with the **as**, **aS**, and **ad** commands, and it only works when the **/v** switch is used—it will not work with **${/n:***Alias***}** or **${***Alias***}** when they retain their literal values. + +*Alias* must be a user-named alias or the *Variable* value used by the [**.foreach**](-foreach.md) token—not a fixed-name alias. If there is a fixed-name alias within the string *Alias*, it will be replaced before the **${ }** token is evaluated. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20${%20}%20%20%28Alias%20Interpreter%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/------block-delimiter-.md b/windows-driver-docs-pr/debugger/------block-delimiter-.md new file mode 100644 index 0000000000..fa4c3f7fb5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/------block-delimiter-.md @@ -0,0 +1,50 @@ +--- +title: (Block Delimiter) +description: A pair of braces ( ) is used to surround a block of statements within a debugger command program. +ms.assetid: 1391fa51-61ce-40e5-8bf5-b5a2215c2bd9 +keywords: ["(Block Delimiter) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Block Delimiter) +api_type: +- NA +--- + +# { } (Block Delimiter) + + +A pair of braces ( **{ }** ) is used to surround a block of statements within a debugger command program. + +``` +Statements { Statements } Statements +``` + +## + + +### Additional Information + +For information about debugger command programs and control flow tokens, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +When each block is entered, all aliases within the block are evaluated. If you alter the value of an alias at some point within a command block, commands subsequent to that point will not use the new alias value unless they are within a subordinate block. + +Each block must begin with a control flow token. If you wish to create a block for the sole purpose of evaluating aliases, you should prefix it with the [**.block**](-block.md) token. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20{%20}%20%20%28Block%20Delimiter%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-----comment-specifier-.md b/windows-driver-docs-pr/debugger/-----comment-specifier-.md new file mode 100644 index 0000000000..220fe857cf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-----comment-specifier-.md @@ -0,0 +1,51 @@ +--- +title: $$ (Comment Specifier) +description: If two dollar signs ( $$ ) appear at the start of a command, then the rest of the line is treated as a comment, unless the comment is terminated by a semicolon. +ms.assetid: bafd5e97-d443-4bfc-b3ee-c2867ed139a2 +keywords: ["comment token ($$)", "$$ (Comment Specifier) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- $$ (Comment Specifier) +api_type: +- NA +--- + +# $$ (Comment Specifier) + + +If two dollar signs ( **$$** ) appear at the start of a command, then the rest of the line is treated as a comment, unless the comment is terminated by a semicolon. + +``` +$$ [any text] +``` + +Remarks +------- + +The **$$** token is parsed like any other debugger command. Therefore, if you want to create a comment after another command, you must precede the **$$** token with a semicolon. + +The **$$** token will cause the text after it to be ignored until the end of the line or until a semicolon is encountered. A semicolon terminates the comment; text after the semicolon is parsed as a standard command. This differs from [**\* (Comment Line Specifier)**](----comment-line-specifier-.md), which makes the remainder of the line a comment even if a semicolon is present. + +For example, the following command will display **eax** and **ebx**, but not **ecx**: + +``` +0:000> r eax; $$ some text; r ebx; * more text; r ecx +``` + +Text prefixed by the [**\***](----comment-line-specifier-.md) or **$$** tokens is not processed in any way. If you are performing remote debugging, a comment entered in the debugging server will not be visible in the debugging client, nor vice-versa. If you wish to make comment text appear in the Debugger Command window in a way visible to all parties, you should use [**.echo (Echo Comment)**](-echo--echo-comment-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20$$%20%20%28Comment%20Specifier%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/----command-separator-.md b/windows-driver-docs-pr/debugger/----command-separator-.md new file mode 100644 index 0000000000..0fe5259e0f --- /dev/null +++ b/windows-driver-docs-pr/debugger/----command-separator-.md @@ -0,0 +1,55 @@ +--- +title: ; (Command Separator) +description: The semicolon ( ; ) character is used to separate multiple commands on a single line. +ms.assetid: efa59a34-1d1d-4df4-bbb9-b8066c6f3b3c +keywords: ["; (Command Separator) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ; (Command Separator) +api_type: +- NA +--- + +# ; (Command Separator) + + +The semicolon ( **;** ) character is used to separate multiple commands on a single line. + +``` + Command1 ; Command2 [; Command3 ...] +``` + +## Parameters + + + *Command1*, *Command2*, ... +The commands to be executed. + +Remarks +------- + +Commands are executed sequentially from left to right. All commands on a single line refer to the current thread, unless otherwise specified. If a command causes the thread to execute, the remaining commands on the line will be deferred until that thread stops on a debug event. + +A small number of commands cannot be followed by a semicolon, because they automatically take the entire remainder of the line as their argument. These include [**as (Set Alias)**](as--as--set-alias-.md), [**$< (Run Script File)**](-----------------------a---run-script-file-.md), **$>< (Run Script File)**, and any command beginning with the [**\* (Comment Line Specifier)**](----comment-line-specifier-.md) token. + +Here is an example. This executes the current program to source line 123, prints the value of **counter**, then resumes execution: + +``` +0:000> g `:123`; ? poi(counter); g +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20;%20%20%28Command%20Separator%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/----comment-line-specifier-.md b/windows-driver-docs-pr/debugger/----comment-line-specifier-.md new file mode 100644 index 0000000000..be98a33499 --- /dev/null +++ b/windows-driver-docs-pr/debugger/----comment-line-specifier-.md @@ -0,0 +1,51 @@ +--- +title: * (Comment Line Specifier) +description: If the asterisk (*) character is at the start of a command, then the rest of the line is treated as a comment, even if a semicolon appears after it. +ms.assetid: 46f68e92-0758-49f2-82bb-bc4d25ddb641 +keywords: ["comment line token ( )", "(Comment Line Specifier) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Comment Line Specifier) +api_type: +- NA +--- + +# \* (Comment Line Specifier) + + +If the asterisk ( **\*** ) character is at the start of a command, then the rest of the line is treated as a comment, even if a semicolon appears after it. + +``` +* [any text] +``` + +Remarks +------- + +The **\*** token is parsed like any other debugger command. Therefore, if you want to create a comment after another command, you must precede the **\*** token with a semicolon. + +The **\*** token will cause the remainder of the line to be ignored, even if a semicolon appears after it. This differs from [**$$ (Comment Specifier)**](-----comment-specifier-.md), which creates a comment that can be terminated by a semicolon. + +For example, the following command will display **eax** and **ebx**, but not **ecx**: + +``` +0:000> r eax; $$ some text; r ebx; * more text; r ecx +``` + +Text prefixed by the **\*** or [**$$**](-----comment-specifier-.md) tokens is not processed in any way. If you are performing remote debugging, a comment entered in the debugging server will not be visible in the debugging client, nor vice-versa. If you wish to make comment text appear in the Debugger Command window in a way visible to all parties, you should use [**.echo (Echo Comment)**](-echo--echo-comment-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20*%20%20%28Comment%20Line%20Specifier%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/----evaluate-c---expression-.md b/windows-driver-docs-pr/debugger/----evaluate-c---expression-.md new file mode 100644 index 0000000000..3c464396ef --- /dev/null +++ b/windows-driver-docs-pr/debugger/----evaluate-c---expression-.md @@ -0,0 +1,82 @@ +--- +title: (Evaluate C++ Expression) +description: The double question mark ( ) command evaluates and displays the value of an expression according to C++ expression rules. +ms.assetid: 3a15a0a3-03d0-4807-a6df-054de819c0a0 +keywords: ["(Evaluate C++ Expression) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Evaluate C++ Expression) +api_type: +- NA +--- + +# ?? (Evaluate C++ Expression) + + +The double question mark (**??**) command evaluates and displays the value of an expression according to C++ expression rules. + +``` +?? Expression +``` + +## Parameters + + + *Expression* +Specifies the C++ expression to evaluate. For more information about the syntax, see [C++ Numbers and Operators](c---numbers-and-operators.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **??** command evaluates symbols in the expression in the context of the current thread and process. + +If you want to evaluate a part of the **Expression** expression according to MASM expression rules, enclose that part in parentheses and add two at signs ( **@@** ) before it. For more information about MASM expressions and C++ expressions, see [Evaluating Expressions](evaluating-expressions.md) and [Numerical Expression Syntax](numerical-expression-syntax.md). + +## See also + + +[**? (Evaluate Expression)**](---evaluate-expression-.md) + +[**.formats (Show Number Formats)**](-formats--show-number-formats-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20??%20%28Evaluate%20C++%20Expression%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/----system-status-.md b/windows-driver-docs-pr/debugger/----system-status-.md new file mode 100644 index 0000000000..0a49e1b737 --- /dev/null +++ b/windows-driver-docs-pr/debugger/----system-status-.md @@ -0,0 +1,106 @@ +--- +title: (System Status) +description: The double vertical bar ( ) command prints status for the specified system or for all systems that you are currently debugging.Do not confuse this command with the (Process Status) command. +ms.assetid: fcea61b1-2ec5-4c80-abd7-269b95d56cd4 +keywords: ["(System Status) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (System Status) +api_type: +- NA +--- + +# || (System Status) + + +The double vertical bar (**||**) command prints status for the specified system or for all systems that you are currently debugging. + +Do not confuse this command with the [**| (Process Status)**](---process-status-.md) command. + +``` +|| System +``` + +## Parameters + + + *System* +Specifies the system to display. If you omit this parameter, all systems that you are debugging are displayed. For more information about the syntax, see [System Syntax](system-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Multiple target debugging

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **||** command is useful only when you are debugging multiple targets. Many, but not all, multiple-target debugging sessions involve multiple systems. For more information about these sessions, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +Each system listing includes the server name and the protocol details. The system that the debugger is running on is identified as **<Local>**. + +The following examples show you how to use this command. The following command displays all systems. + +``` +3:2:005> || +``` + +The following command also displays all systems. + +``` +3:2:005> ||* +``` + +The following command displays the currently active system. + +``` +3:2:005> ||. +``` + +The following command displays the system that had the most recent exception or break. + +``` +3:2:005> ||# +``` + +The following command displays system number 2. + +``` +3:2:005> ||2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20||%20%28System%20Status%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/---command-help-.md b/windows-driver-docs-pr/debugger/---command-help-.md new file mode 100644 index 0000000000..d5887134f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/---command-help-.md @@ -0,0 +1,73 @@ +--- +title: (Command Help) +description: The question mark ( ) character displays a list of all commands and operators.Note  A question mark by itself displays command help. +ms.assetid: 89b61021-43a4-46b7-ae43-a52dd9d40948 +keywords: ["(Command Help) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Command Help) +api_type: +- NA +--- + +# ? (Command Help) + + +The question mark (**?**) character displays a list of all commands and operators. + +**Note**   A question mark by itself displays command help. The [**? expression**](---evaluate-expression-.md) syntax evaluates the given expression. + +  + +``` +? +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +For more information about standard commands, use **?**. For more information about meta-commands, use [**.help**](-help--meta-command-help-.md). For more information about extension commands, use [**!help**](-help.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20?%20%28Command%20Help%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/---evaluate-expression-.md b/windows-driver-docs-pr/debugger/---evaluate-expression-.md new file mode 100644 index 0000000000..a0608e0bd2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/---evaluate-expression-.md @@ -0,0 +1,119 @@ +--- +title: (Evaluate Expression) +description: The question mark ( ) command evaluates and displays the value of an expression.Note  A question mark by itself ( ) displays command help. +ms.assetid: fae689b3-47c9-44bd-992d-8344805fb4b7 +keywords: ["(Evaluate Expression) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Evaluate Expression) +api_type: +- NA +--- + +# ? (Evaluate Expression) + + +The question mark (**?**) command evaluates and displays the value of an expression. + +**Note**   A question mark by itself ([**?**](---command-help-.md)) displays command help. The **?** *expression* command evaluates the given expression. + +  + +``` +? Expression +``` + +## Parameters + + + *Expression* +Specifies the expression to evaluate. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The input and output of the **?** command depend on whether you are using MASM expression syntax or C++ expression syntax. For more information about these kinds of expression syntax, see [Evaluating Expressions](evaluating-expressions.md) and [Numerical Expression Syntax](numerical-expression-syntax.md). + +If you are using MASM syntax, the input and output depend on the current radix. To change the radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. + +The **?** command evaluates symbols in the expression in the context of the current thread and process. + +Some strings may contain escapes, such as **\\n**, **\\"**, **\\r**, and **\\b**, that are meant to be read literally, rather than interpreted by the evaluator. If an escape within a string is interpreted by the evaluator, errors in evaluation can occur. For example: + +``` +0:000> as AliasName c:\dir\name.txt +0:000> al + Alias Value + ------- ------- + AliasName c:\dir\name.txt +0:001> ? $spat( "c:\dir\name.txt", "*name*" ) +Evaluate expression: 0 = 00000000 +0:001> ? $spat( "${AliasName}", "*name*" ) +Evaluate expression: 0 = 00000000 +0:001> ? $spat( "c:\dir\", "*filename*" ) +Syntax error at '( "c:\dir\", "*filename*" ) +``` + +In the first two examples, even though the string does match the pattern, the evaluator is returning a value of **FALSE**. In the third, the evaluator cannot make a comparison because the string ends in a backslash ( \\ ), and so the **\\"** is translated by the evaluator. + +To get the evaluator to interpret a string literally, you must use the **@"***String***"** syntax. The following code example shows the correct results: + +``` +0:000> ? $spat( @"c:\dir\name.txt", "*name*" ) +Evaluate expression: 1 = 00000000`00000001 +0:000> ? $spat( @"${AliasName}", "*name*" ) +Evaluate expression: 1 = 00000000`00000001 +0:001> ? $spat( @"c:\dir\", "*filename*" ) +Evaluate expression: 0 = 00000000 +``` + +In the preceding examples, the **$spat** MASM operator checks the first string to determine whether it matches (case-insensitive) the pattern of the second string. For more information about MASM operators, see the [MASM Numbers and Operators](masm-numbers-and-operators.md) topic. + +## See also + + +[**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) + +[**.formats (Show Number Formats)**](-formats--show-number-formats-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20?%20%28Evaluate%20Expression%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/---process-status-.md b/windows-driver-docs-pr/debugger/---process-status-.md new file mode 100644 index 0000000000..d77e1a1085 --- /dev/null +++ b/windows-driver-docs-pr/debugger/---process-status-.md @@ -0,0 +1,123 @@ +--- +title: (Process Status) +description: The pipe ( ) command displays status for the specified process, or for all processes that you are currently debugging.Do not confuse this command with the (System Status) command. +ms.assetid: 78f53049-e949-4431-b6b1-0710da047ced +keywords: ["(Process Status) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Process Status) +api_type: +- NA +--- + +# | (Process Status) + + +The pipe (**|**) command displays status for the specified process, or for all processes that you are currently debugging. + +Do not confuse this command with the [**|| (System Status)**](----system-status-.md) command. + +``` +| Process +``` + +## Parameters + + + *Process* +Specifies the process to display. If you omit this parameter, all processes that you are debugging are displayed. For more information about the syntax, see [Process Syntax](process-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information and other methods of displaying or controlling processes and threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify processes only in user mode. + +You can add a process symbol before many commands. For more information about the meaning of a pipe (**|**) followed by a command, see the entry for the command itself. + +Unless you enabled the debugging of child processes when you started the debugging session, there is only one process that is available to the debugger. + +The following examples show you how to use this command. The following command displays all processes. + +``` +2:005> | +``` + +The following command also displays all processes. + +``` +2:005> |* +``` + +The following command displays the currently active process. + +``` +2:005> |. +``` + +The following command displays the process that originally caused the exception (or that the debugger originally attached to). + +``` +2:005> |# +``` + +The following command displays process number 2. + +``` +2:005> |2 +``` + +The previous command displays the following output. + +``` +0:002> | +# 0 id: 224 name: myprog.exe + 1 id: 228 name: onechild.exe +. 2 id: 22c name: anotherchild.exe +``` + +On the first line of this output, 0 is the decimal process number, 224 is the hexadecimal process ID, and *Myprog.exe* is the application name of the process. The period (.) before process 2 means that this process is the current process. The number sign (\#) before process 0 means that this process was the one that originally caused the exception or that the debugger attached to. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20|%20%28Process%20Status%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/---search-for-disassembly-pattern-.md b/windows-driver-docs-pr/debugger/---search-for-disassembly-pattern-.md new file mode 100644 index 0000000000..d3118e413a --- /dev/null +++ b/windows-driver-docs-pr/debugger/---search-for-disassembly-pattern-.md @@ -0,0 +1,119 @@ +--- +title: # (Search for Disassembly Pattern) +description: The number sign (#) command searches for the specified pattern in the disassembly code. +ms.assetid: 834dd432-94b8-4bf6-9318-09a118eab5ab +keywords: ["(Search for Disassembly Pattern) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- (Search for Disassembly Pattern) +api_type: +- NA +--- + +# \# (Search for Disassembly Pattern) + + +The number sign (**\#**) command searches for the specified pattern in the disassembly code. + +``` +# [Pattern] [Address [ L Size ]] +``` + +## Parameters + + + *Pattern* +Specifies the pattern to search for in the disassembly code. *Pattern* can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). If you want to include spaces in *Pattern*, you must enclose the pattern in quotation marks. The pattern is not case sensitive. If you have previously used the **\#** command and you omit *Pattern*, the command reuses the most recently used pattern. + + *Address* +Specifies the address where the search begins. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Size* +Specifies the number of instructions to search. If you omit *Size*, the search continues until the first match occurs. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +If you previously used the **\#** command and you omit *Address*, the search begins where the previous search ended. + +This command works by searching the disassembled text for the specified pattern. You can use this command to find register names, constants, or any other string that appears in the disassembly output. You can repeat the command without the *Address* parameter to find successive occurrences of the pattern. + +You can view disassembly instructions by using the [**u (Unassemble)**](u--unassemble-.md) command or by using the [Disassembly window](disassembly-window.md) in WinDbg. The disassembly display contains up to four parts: Address offset, Binary code, Assembly language mnemonic, and Assembly language details. The following example shows a possible display. + +``` +0040116b 45 inc ebp +0040116c fc cld +0040116d 8945b0 mov eax,[ebp-0x1c] +``` + +The **\#** command can search for text within any single part of the disassembly display. For example, you could use **\# eax 0040116b** to find the **mov eax,\[ebp-0x1c\]** instruction at address 0040116d. The following commands also find this instruction. + +``` +# [ebp?0x 0040116b +# mov 0040116b +# 8945* 0040116b +# 116d 0040116b +``` + +However, you cannot search for **mov eax\*** as a single unit, because **mov** and **eax** appear in different parts of the display. Instead, use **mov\*eax**. + +As an additional example, you could issue the following command to search for the first reference to the **strlen** function after the entry point **main**. + +``` +# strlen main +``` + +Similarly, you could issue the following two commands to find the first **jnz** instruction after address 0x779F9FBA and then find the next **jnz** instruction after that. + +``` +# jnz 779f9fba# +``` + +When you omit *Pattern* or *Address*, their values are based on the previous use of the **\#** command. If you omit either parameter the first time that you issue the **\#** command, no search is performed. However, the values of *Pattern* and *Address* are initialized even in this situation. + +If you include *Pattern* or *Address*, its value is set to the entered value. If you omit *Address*, it is initialized to the current value of the program counter. If you omit *Pattern*, it is initialized to an empty pattern. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20#%20%28Search%20for%20Disassembly%20Pattern%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/---thread-status-.md b/windows-driver-docs-pr/debugger/---thread-status-.md new file mode 100644 index 0000000000..4f1483de37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/---thread-status-.md @@ -0,0 +1,119 @@ +--- +title: ~ (Thread Status) +description: The tilde (~) command displays status for the specified thread or for all threads in the current process. +ms.assetid: c27e4c72-86da-459d-833f-d27d26bdea0e +keywords: ["~ (Thread Status) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~ (Thread Status) +api_type: +- NA +--- + +# ~ (Thread Status) + + +The tilde (**~**) command displays status for the specified thread or for all threads in the current process. + +``` +~ Thread +``` + +## Parameters + + + *Thread* +Specifies the thread to display. If you omit this parameter, all threads are displayed. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information and other methods of displaying or controlling processes and threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (**~**) refers to a processor. + +You can add a thread symbol before many commands. For more information about the meaning of a tilde (**~**) followed by a command, see the entry for the command itself. + +The following examples show you how to use this command. The following command displays all threads. + +``` +0:001> ~ +``` + +The following command also displays all threads. + +``` +0:001> ~* +``` + +The following command displays the currently active thread. + +``` +0:001> ~. +``` + +The following command displays the thread that originally caused the exception (or that was active when the debugger attached to the process). + +``` +0:001> ~# +``` + +The following command displays thread number 2. + +``` +0:001> ~2 +``` + +The previous command displays the following output. + +``` +0:001> ~ + 0 id: 4dc.470 Suspend: 0 Teb 7ffde000 Unfrozen +. 1 id: 4dc.534 Suspend: 0 Teb 7ffdd000 Unfrozen +# 2 id: 4dc.5a8 Suspend: 0 Teb 7ffdc000 Unfrozen +``` + +On the first line of this output, 0 is the decimal thread number, 4DC is the hexadecimal process ID, 470 is the hexadecimal thread ID, 0x7FFDE000 is the address of the TEB, and **Unfrozen** is the thread status. The period (.) before thread 1 means this thread is the current thread. The number sign (\#) before thread 2 means this thread was the one that originally caused the exception or it was active when the debugger attached to the process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~%20%28Thread%20Status%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/--s--set-current-system-.md b/windows-driver-docs-pr/debugger/--s--set-current-system-.md new file mode 100644 index 0000000000..22ba48a5e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/--s--set-current-system-.md @@ -0,0 +1,83 @@ +--- +title: s (Set Current System) +description: The s command sets or displays the current system number. +ms.assetid: 33ad3a63-166f-4669-868c-49100c9b4d8c +keywords: ["s (Set Current System) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- s (Set Current System) +api_type: +- NA +--- + +# ||s (Set Current System) + + +The **||s** command sets or displays the current system number. + +``` +||System s +|| s +``` + +Do not confuse this command with the [**s (Search Memory)**](s--search-memory-.md), [**~s (Change Current Processor)**](-s--change-current-processor-.md), [**~s (Set Current Thread)**](-s--set-current-thread-.md), or [**|s (Set Current Process)**](-s--set-current-process-.md) command. + + +## Parameters + + + *System* +Specifies the system number to activate. For more information about the syntax, see [System Syntax](system-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Multiple target debugging

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **||s** command is useful when you are debugging multiple targets or working with multiple dump files. For more information about these kinds of sessions, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +If you use the **||s** syntax, the debugger displays information about the current system. + +This command also disassembles the current instruction for the current system, process, and thread. + +  +**Note**   There are complications, when you debug live targets and dump targets together, because commands behave differently for each type of debugging. For example, if you use the **g (Go)** command when the current system is a dump file, the debugger begins executing, but you cannot break back into the debugger, because the break command is not recognized as valid for dump file debugging. + + + + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20||s%20%28Set%20Current%20System%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-abandon--abandon-process-.md b/windows-driver-docs-pr/debugger/-abandon--abandon-process-.md new file mode 100644 index 0000000000..f746678ac4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-abandon--abandon-process-.md @@ -0,0 +1,76 @@ +--- +title: .abandon (Abandon Process) +description: The .abandon command ends the debugging session, but leaves the target application in a debugging state. This returns the debugger to dormant mode. +ms.assetid: e44ae9b8-b6a2-4648-911d-61ff3c94527c +keywords: [".abandon (Abandon Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .abandon (Abandon Process) +api_type: +- NA +--- + +# .abandon (Abandon Process) + + +The **.abandon** command ends the debugging session, but leaves the target application in a debugging state. This returns the debugger to dormant mode. + +``` + .abandon [/h|/n] +``` + +## Parameters + + + **/h** +Any outstanding debug event will be continued and marked as handled. This is the default. + + **/n** +Any outstanding debug event will be continued unhandled. + +### Environment + +This command is only supported in Windows XP and later versions of Windows. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +If the target is left in a debugging state, a new debugger can be attached to it. See [Re-attaching to the Target Application](reattaching-to-the-target-application.md) for details. However, after a process has been abandoned once, it can never be restored to a running state without a debugger attached. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.abandon%20%28Abandon%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-acl.md b/windows-driver-docs-pr/debugger/-acl.md new file mode 100644 index 0000000000..c1ac27dfe7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-acl.md @@ -0,0 +1,81 @@ +--- +title: acl +description: The acl extension formats and displays the contents of an access control list (ACL). +ms.assetid: 591f56b6-5a70-4037-a285-a1bffd5bd387 +keywords: ["acl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- acl +api_type: +- NA +--- + +# !acl + + +The **!acl** extension formats and displays the contents of an access control list (ACL). + +Syntax + +``` + !acl Address [Flags] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the ACL. + + *Flags* +Displays the friendly name of the ACL, if the value of *Flags* is 1. This friendly name includes the security identifier (SID) type and the domain and user name for the SID. + +### DLL + +Exts.dll + +### Additional Information + +For more information about access control lists, see [**!sid**](-sid.md), [**!sd**](-sd.md), and [Determining the ACL of an Object](determining-the-acl-of-an-object.md). Also, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +The following example shows the **!acl** extension. + +``` +kd> !acl e1bf35d4 1 +ACL is: +ACL is: ->AclRevision: 0x2 +ACL is: ->Sbz1 : 0x0 +ACL is: ->AclSize : 0x40 +ACL is: ->AceCount : 0x2 +ACL is: ->Sbz2 : 0x0 +ACL is: ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +ACL is: ->Ace[0]: ->AceFlags: 0x0 +ACL is: ->Ace[0]: ->AceSize: 0x24 +ACL is: ->Ace[0]: ->Mask : 0x10000000 +ACL is: ->Ace[0]: ->SID: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser) + +ACL is: ->Ace[1]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +ACL is: ->Ace[1]: ->AceFlags: 0x0 +ACL is: ->Ace[1]: ->AceSize: 0x14 +ACL is: ->Ace[1]: ->Mask : 0x10000000 +ACL is: ->Ace[1]: ->SID: S-1-5-18 (Well Known Group: NT AUTHORITY\SYSTEM) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!acl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-acpicache.md b/windows-driver-docs-pr/debugger/-acpicache.md new file mode 100644 index 0000000000..de363bda32 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-acpicache.md @@ -0,0 +1,67 @@ +--- +title: acpicache +description: The acpicache extension displays all of the Advanced Configuration and Power Interface (ACPI) tables cached by the HAL. +ms.assetid: 488bbc40-0f67-4d13-8615-944ff8a6a177 +keywords: ["acpicache Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- acpicache +api_type: +- NA +--- + +# !acpicache + + +The **!acpicache** extension displays all of the Advanced Configuration and Power Interface (ACPI) tables cached by the HAL. + +``` +!acpicache [DisplayLevel] +``` + +## Parameters + + + *DisplayLevel* +Specifies the detail level of the display. This value is either 0 for an abbreviated display or 1 for a more detailed display. The default value is 0. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the ACPI, see the Microsoft Windows Driver Kit (WDK) documentation, the Windows SDK documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These books and resources may not be available in some languages and countries.) Also see [ACPI Debugging](acpi-debugging.md) for information about other extensions that are associated with the ACPI. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!acpicache%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-acpiinf.md b/windows-driver-docs-pr/debugger/-acpiinf.md new file mode 100644 index 0000000000..8566bf7f39 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-acpiinf.md @@ -0,0 +1,61 @@ +--- +title: acpiinf +description: The acpiinf extension displays information on the configuration of the ACPI, including system tables and the contents of the ACPI fixed feature hardware. +ms.assetid: 06e3e57b-f486-4165-87ea-37d80a00c34c +keywords: ["acpiinf Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- acpiinf +api_type: +- NA +--- + +# !acpiinf + + +The **!acpiinf** extension displays information on the configuration of the Advanced Configuration and Power Interface (ACPI), including the location of system tables and the contents of the ACPI fixed feature hardware. + +``` +!acpiinf +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the ACPI, see the Microsoft Windows Driver Kit (WDK) documentation, the Windows SDK documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These books and resources may not be available in some languages and countries.) Also see [ACPI Debugging](acpi-debugging.md) for information about other extensions that are associated with the ACPI. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!acpiinf%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-acpiirqarb.md b/windows-driver-docs-pr/debugger/-acpiirqarb.md new file mode 100644 index 0000000000..8e5761f441 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-acpiirqarb.md @@ -0,0 +1,61 @@ +--- +title: acpiirqarb +description: The acpiirqarb extension displays the contents of the ACPI IRQ arbiter structure, which contains the configuration of I/O devices to system interrupt controller inputs and processor IDT entries. +ms.assetid: c57884cd-c70c-4091-871d-c2a35db8d73f +keywords: ["acpiirqarb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- acpiirqarb +api_type: +- NA +--- + +# !acpiirqarb + + +The **!acpiirqarb** extension displays the contents of the Advanced Configuration and Power Interface (ACPI) IRQ arbiter structure, which contains the configuration of I/O devices to system interrupt controller inputs and processor interrupt dispatch table (IDT) entries. + +``` +!acpiirqarb +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the ACPI, see the Microsoft Windows Driver Kit (WDK) documentation, the Windows SDK documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These books and resources may not be available in some languages and countries.) Also see [ACPI Debugging](acpi-debugging.md) for information about other extensions that are associated with the ACPI. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!acpiirqarb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-acpikd-help.md b/windows-driver-docs-pr/debugger/-acpikd-help.md new file mode 100644 index 0000000000..9b9b70f81b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-acpikd-help.md @@ -0,0 +1,64 @@ +--- +title: acpikd.help +description: The acpikd.help extension displays a Help text in the Debugger Command window showing all Acpikd.dll extension commands. +ms.assetid: 46062e9d-bd68-43d4-90dd-4e481c48f5ee +keywords: ["acpikd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- acpikd.help +api_type: +- NA +--- + +# !acpikd.help + + +The **!acpikd.help** extension displays a Help text in the Debugger Command window showing all Acpikd.dll extension commands. + +``` + !acpikd.help +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Acpikd.dll

Windows XP and later

Acpikd.dll

+ +  + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!acpikd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-address.md b/windows-driver-docs-pr/debugger/-address.md new file mode 100644 index 0000000000..29edea22b6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-address.md @@ -0,0 +1,432 @@ +--- +title: address +description: The address extension displays information about the memory that the target process or target computer uses. +ms.assetid: 9bbde680-8523-4db2-bb7e-fdacdaf1aa89 +keywords: ["address Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- address +api_type: +- NA +--- + +# !address + + +The **!address** extension displays information about the memory that the target process or target computer uses. + +User-Mode + +``` +!address Address +!address -summary +!address [-f:F1,F2,...] {[-o:{csv | tsv | 1}] | [-c:"Command"]} +!address -? | -help +``` + +Kernel-Mode + +``` +!address Address +!address +``` + +## Parameters + + + *Address* +Displays only the region of the address space that contains *Address*. + + **-summary** +Displays only summary information. + + **-f**:*F1*, *F2*, ... +Displays only the regions specified by the filters *F1*, *F2*, and so on. + +The following filter values specify memory regions by the way that the target process is using them. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Filter valueMemory regions displayed

VAR

Busy regions. These regions include all virtual allocation blocks, the SBH heap, memory from custom allocators, and all other regions of the address space that fall into no other classification.

Free

Free memory. This includes all memory that has not been reserved.

Image

Memory that is mapped to a file that is part of an executable image.

Stack

Memory used for thread stacks.

Teb

Memory used for thread environment blocks (TEBs).

Peb

Memory used for the process environment block (PEB).

Heap

Memory used for heaps.

PageHeap

The memory region used for the full-page heap.

CSR

CSR shared memory.

Actx

Memory used for activation context data.

NLS

Memory used for National Language Support (NLS) tables.

FileMap

Memory used for memory-mapped files. This filter is applicable only during live debugging.

+ +  + +The following filter values specify memory regions by the memory type. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Filter valueMemory regions displayed

MEM_IMAGE

Memory that is mapped to a file that is part of an executable image.

MEM_MAPPED

Memory that is mapped to a file that is not part of an executable image. This includes memory that is mapped to the paging file.

MEM_PRIVATE

Private memory. This memory is not shared by any other process, and it is not mapped to any file.

+ +  + +The following filter values specify memory regions by the state of the memory. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Filter valueMemory regions displayed

MEM_COMMIT

Committed memory.

MEM_FREE

Free memory. This includes all memory that has not been reserved.

MEM_RESERVE

Reserved memory.

+ +  + +The following filter values specify memory regions by the protection applied to the memory. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Filter valueMemory regions displayed

PAGE_NOACCESS

Memory that cannot be accessed.

PAGE_READONLY

Memory that is readable, but not writable and not executable.

PAGE_READWRITE

Memory that is readable and writable, but not executable.

PAGE_WRITECOPY

Memory that has copy-on-write behavior.

PAGE_EXECUTE

Memory that is executable, but not readable and not writeable.

PAGE_EXECUTE_READ

Memory that is executable and readable, but not writable.

PAGE_EXECUTE_READWRITE

Memory that is executable, readable, and writable.

PAGE_EXECUTE_WRITECOPY

Memory that is executable and has copy-on-write behavior.

PAGE_GUARD

Memroy that acts as a guard page.

PAGE_NOCACHE

Memory that is not cached.

PAGE_WRITECOMBINE

Memory that has write-combine access enabled.

+ +  + + **-o:**{**csv** | **tsv** | **1**} +Displays the output according to one of the following options. + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionOutput format

csv

Displays the output as comma-separated values.

tsv

Displays the output as tab-separated values.

1

Displays the output in bare format. This format works well when !address is used as input to [.foreach](-foreach.md).

+ +  + + **-c**:"*Command*" +Executes a custom command for each memory region. You can use the following placeholders in your command to represent output fields of the **!address** extension. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlaceholderOutput field

%1

Base address

%2

End address + 1

%3

Region size

%4

Type

%5

State

%6

Protection

%7

Usage

+ +  + +For example, `!address -f:Heap -c:".echo %1 %3 %5"` displays the base address, size, and state for each memory region of type **Heap**. + +Quotes in the command must be preceded by a back slash (\\"). For example, !address -f:Heap -c:"s -a %1 %2 \\"pad\\"" searches each memory region of type **Heap** for the string "pad". + +Multiple commands separated by semicolons are not supported. + + **-?** +Displays minimal Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about how to display and search memory, see [Reading and Writing Memory](reading-and-writing-memory.md). For additional extensions that display memory properties, see [**!vm**](-vm.md) (kernel mode) and [**!vprot**](-vprot.md) (user mode). + +Remarks +------- + +Without any parameters, the **!address** extension displays information about the whole address space. The **!address -summary** command shows only the summary. + +In kernel mode, this extension searches only kernel memory, even if you used [**.process (Set Process Context)**](-process--set-process-context-.md) to specify a given process' virtual address space. In user mode, the **!address** extension always refers to the memory that the target process owns. + +In user mode, **!address** *Address* shows the characteristics of the region that the specified address belongs to. Without parameters, **!address** shows the characteristics of all memory regions. These characteristics include the memory usage, memory type, memory state, and memory protection. For more information about the meaning of this information, see the earlier tables in the description of the **-f** parameter. + +The following example uses **!address** to retrieve information about a region of memory that is mapped to kernel32.dll. + +``` +0:000> !address 75831234 +Usage: Image +Base Address: 75831000 +End Address: 758f6000 +Region Size: 000c5000 +Type: 01000000MEM_IMAGE +State: 00001000MEM_COMMIT +Protect: 00000020PAGE_EXECUTE_READ +More info: lmv m kernel32 +More info: !lmi kernel32 +More info: ln 0x75831234 +``` + +This example uses an *Address* value of 0x75831234. The display shows that this address is in a memory region that begins with the address 0x75831000 and ends with the address 0x758f6000. The region has usage **Image**, type **MEM\_IMAGE**, state **MEM\_COMMIT**, and protection **PAGE\_EXECUTE\_READ**. (For more information about the meaning of these values, see the earlier tables.) The display also lists three other debugger commands that you can use to get more information about this memory address. + +If you are starting with an address and trying to determine information about it, the usage information is frequently the most valuable. After you know the usage, you can use additional extensions to learn more about this memory. For example, if the usage is **Heap**, you can use the [**!heap**](-heap.md) extension to learn more. + +The following example uses the [**s (Search Memory)**](s--search-memory-.md) command to search each memory region of type **Image** for the wide-character string "Note". + +``` +!address /f:Image /c:"s -u %1 %2 \"Note\"" + +*** Executing: s -u 0xab0000 0xab1000 "Note" +*** Executing: s -u 0xab1000 0xabc000 "Note" +00ab2936 004e 006f 0074 0065 0070 0061 0064 0000 N.o.t.e.p.a.d... +00ab2f86 004e 006f 0074 0065 0070 0061 0064 005c N.o.t.e.p.a.d.\. +00ab32e4 004e 006f 0074 0065 0070 0061 0064 0000 N.o.t.e.p.a.d... +*** Executing: s -u 0xabc000 0xabd000 "Note" +. . . +``` + +In kernel mode, the output of **!address** is similar to the user mode output but contains less information. The following example example shows the kernel mode output. + +``` +kd> !address + 804de000 - 00235000 + Usage KernelSpaceUsageImage + ImageName ntoskrnl.exe + + 80c00000 - 001e1000 + Usage KernelSpaceUsagePFNDatabase + +.... + + f85b0000 - 00004000 + Usage KernelSpaceUsageKernelStack + KernelStack 817b4da0 : 324.368 + + f880d000 - 073d3000 + Usage KernelSpaceUsageNonPagedPoolExpansion +``` + +The meaning of "usage" is the same as in user mode. "ImageName" indicates the module that is associated with this address. "KernelStack" shows the address of this thread's ETHREAD block (0x817B4DA0), the process ID (0x324), and the thread ID (0x368). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!address%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ahcache.md b/windows-driver-docs-pr/debugger/-ahcache.md new file mode 100644 index 0000000000..8146cc6ecf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ahcache.md @@ -0,0 +1,69 @@ +--- +title: ahcache +description: The ahcache extension displays the application compatibility cache. +ms.assetid: 65a7c320-3ea3-4657-b271-ec3d9c2bd5de +keywords: ["ahcache Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ahcache +api_type: +- NA +--- + +# !ahcache + + +The **!ahcache** extension displays the application compatibility cache. + +``` + !ahcache [Flags] +``` + +## Parameters + + + *Flags* +Specifies the information to include in the display. This can be any combination of the following bits (the default is zero): + +Bit 0 (0x1) +Displays the RTL\_GENERIC\_TABLE list instead of the LRU list. + +Bit 4 (0x10) +Verbose display: includes all entry details, not just the names. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ahcache%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-alignmentfaults.md b/windows-driver-docs-pr/debugger/-alignmentfaults.md new file mode 100644 index 0000000000..23541b7773 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-alignmentfaults.md @@ -0,0 +1,66 @@ +--- +title: alignmentfaults +description: The alignmentfaults extension displays all current type alignment faults by location and image, sorted by frequencies. +ms.assetid: 6720a4de-ba75-4449-ab47-559bc7323002 +keywords: ["alignmentfaults Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- alignmentfaults +api_type: +- NA +--- + +# !alignmentfaults + + +The **!alignmentfaults** extension displays all current type alignment faults by location and image, sorted by frequencies. + +``` +!alignmentfaults +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about alignment faults, see the Microsoft Windows SDK documentation. + +Remarks +------- + +This is only available on checked builds. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!alignmentfaults%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-allow-exec-cmds--allow-execution-commands-.md b/windows-driver-docs-pr/debugger/-allow-exec-cmds--allow-execution-commands-.md new file mode 100644 index 0000000000..5602b1bc41 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-allow-exec-cmds--allow-execution-commands-.md @@ -0,0 +1,83 @@ +--- +title: .allow_exec_cmds (Allow Execution Commands) +description: The .allow_exec_cmds command controls whether execution commands can be used. +ms.assetid: c6e37cf1-42cc-4f82-9eb8-d252f0b6e196 +keywords: [".allow_exec_cmds (Allow Execution Commands) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .allow_exec_cmds (Allow Execution Commands) +api_type: +- NA +--- + +# .allow\_exec\_cmds (Allow Execution Commands) + + +The **.allow\_exec\_cmds** command controls whether execution commands can be used. + +``` +.allow_exec_cmds 0 +.allow_exec_cmds 1 +.allow_exec_cmds +``` + +## Parameters + + + **0** +Prevents execution commands from being used. + + **1** +Allows execution commands to be used. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode and kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For a complete list of execution commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +With no parameters, **.allow\_exec\_cmds** will display whether execution commands are currently permitted. + +Execution commands include [**g (Go)**](g--go-.md), [**t (Trace)**](t--trace-.md), [**p (Step)**](p--step-.md), and any other command or WinDbg graphical interface action that would cause the target to execute. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.allow_exec_cmds%20%28Allow%20Execution%20Commands%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-allow-image-mapping--allow-image-mapping-.md b/windows-driver-docs-pr/debugger/-allow-image-mapping--allow-image-mapping-.md new file mode 100644 index 0000000000..eb515c353f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-allow-image-mapping--allow-image-mapping-.md @@ -0,0 +1,82 @@ +--- +title: .allow_image_mapping (Allow Image Mapping) +description: The .allow_image_mapping command controls whether image files will be mapped. +ms.assetid: 3d216d17-f2af-48f7-9d91-e12c3c305a67 +keywords: [".allow_image_mapping (Allow Image Mapping) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .allow_image_mapping (Allow Image Mapping) +api_type: +- NA +--- + +# .allow\_image\_mapping (Allow Image Mapping) + + +The **.allow\_image\_mapping** command controls whether image files will be mapped. + +``` +.allow_image_mapping [/r] 0 +.allow_image_mapping [/r] 1 +.allow_image_mapping +``` + +## Parameters + + + **/r** +Reloads all modules in the debugger's module list. This is equivalent to [**.reload /d**](-reload--reload-module-.md). + + **0** +Prevents image files from being mapped. + + **1** +Allows image files to be mapped. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode and kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +With no parameters, **.allow\_image\_mapping** will display whether image file mapping is currently allowed. By default, this mapping is allowed. + +Image mapping is most common when a minidump is being debugged. Image mapping can also occur if DbgHelp is unable to access debug records (for example, during kernel debugging when memory has been paged out). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.allow_image_mapping%20%28Allow%20Image%20Mapping%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli--.md b/windows-driver-docs-pr/debugger/-amli--.md new file mode 100644 index 0000000000..79481e1b07 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli--.md @@ -0,0 +1,52 @@ +--- +title: amli +description: The amli extension displays some Help text in the Debugger Command window for the amli extension commands. +ms.assetid: bb632778-5266-4d71-bef5-943aaa682db4 +keywords: ["amli Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli +api_type: +- NA +--- + +# !amli ? + + +The **!amli ?** extension displays some Help text in the Debugger Command window for the **!amli** extension commands. + +Syntax + +``` +!amli ? [Command] +``` + +## Parameters + + + *Command* +Specifies the **!amli** command whose help is to be displayed. For example, **!amli ? set** displays help for the [**!amli set**](-amli-set.md) command. If *Command* is omitted, a list of all commands is displayed. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20?%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-bc.md b/windows-driver-docs-pr/debugger/-amli-bc.md new file mode 100644 index 0000000000..441bb8f8a3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-bc.md @@ -0,0 +1,61 @@ +--- +title: amli bc +description: The amli bc extension permanently clears an AML breakpoint. +ms.assetid: e975ee10-cd2f-4944-8d00-b2eda2dd099a +keywords: ["amli bc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli bc +api_type: +- NA +--- + +# !amli bc + + +The **!amli bc** extension permanently clears an AML breakpoint. + +Syntax + +``` +!amli bc Breakpoint +!amli bc * +``` + +## Parameters + + + *Breakpoint* +Specifies the number of the breakpoint to be cleared. + + **\*** +Specifies that all breakpoints should be cleared. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +To determine the breakpoint number of a breakpoint, use the [**!amli bl**](-amli-bl.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20bc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-bd.md b/windows-driver-docs-pr/debugger/-amli-bd.md new file mode 100644 index 0000000000..1fd4f9800c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-bd.md @@ -0,0 +1,74 @@ +--- +title: amli bd +description: The amli bd extension temporarily disables an AML breakpoint. +ms.assetid: a7fb4f51-8984-425b-858d-1e1e69825891 +keywords: ["amli bd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli bd +api_type: +- NA +--- + +# !amli bd + + +The **!amli bd** extension temporarily disables an AML breakpoint. + +Syntax + +``` +!amli bd Breakpoint!amli bd * +``` + +## Parameters + + + *Breakpoint* +Specifies the number of the breakpoint to be disabled. + + **\*** +Specifies that all breakpoints should be disabled. + +### DLL + +Kdexts.dll + +  + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +A disabled breakpoint can be re-enabled by using the [**!amli be**](-amli-be.md) extension. + +To determine the breakpoint number of a breakpoint, use the [**!amli bl**](-amli-bl.md) extension. + +Here is an example of this command: + +``` +kd> !amli bl + 0: c29accf5 [\_WAK] + 1: c29c20a5 [\_SB.PCI0.ISA.BAT1._BST] + +kd> !amli bd 1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20bd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-be.md b/windows-driver-docs-pr/debugger/-amli-be.md new file mode 100644 index 0000000000..b1e388afc6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-be.md @@ -0,0 +1,62 @@ +--- +title: amli be +description: The amli be extension enables an AML breakpoint. +ms.assetid: 75c0c05f-8c56-4489-a798-2e5ec6ca26d8 +keywords: ["amli be Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli be +api_type: +- NA +--- + +# !amli be + + +The **!amli be** extension enables an AML breakpoint. + +Syntax + +``` +!amli be Breakpoint!amli be * +``` + +## Parameters + + + *Breakpoint* +Specifies the breakpoint number of the breakpoint to be enabled. + + **\*** +Specifies that all breakpoints should be enabled. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +All breakpoints are enabled when they are created. Breakpoints are only disabled if you have used the [**!amli bd**](-amli-bd.md) extension. + +To determine the breakpoint number of a breakpoint, use the [**!amli bl**](-amli-bl.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20be%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-bl.md b/windows-driver-docs-pr/debugger/-amli-bl.md new file mode 100644 index 0000000000..cc383ce3e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-bl.md @@ -0,0 +1,66 @@ +--- +title: amli bl +description: The amli bl extension displays a list of all AML breakpoints. +ms.assetid: 4ce52006-d44e-40ab-b669-2aa9509b6b21 +keywords: ["amli bl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli bl +api_type: +- NA +--- + +# !amli bl + + +The **!amli bl** extension displays a list of all AML breakpoints. + +Syntax + +``` +!amli bl +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +The AMLI Debugger supports a maximum of ten breakpoints. + +Here is an example of the **!amli bl** extension: + +``` +kd> !amli bl + 0: ffffffff80e5e2f1:[\_SB.LNKD._SRS] + 1: ffffffff80e5d969:[\_SB.LNKB._STA] + 2: ffffffff80e630c9:[\_WAK] + 3: ffffffff80e612c9:[\_SB.MBRD._CRS] +``` + +The first column gives the breakpoint number. The **<e>** and **<d>** marks indicate whether the breakpoint is enabled or disabled. The address of the breakpoint is in the next column. Finally, the method containing the breakpoint is listed, with the offset of the breakpoint if it is not set at the start of the method. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20bl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-bp.md b/windows-driver-docs-pr/debugger/-amli-bp.md new file mode 100644 index 0000000000..47628ec0cb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-bp.md @@ -0,0 +1,66 @@ +--- +title: amli bp +description: The amli bp extension places a breakpoint in AML code. +ms.assetid: 830df6b8-835c-4485-a28a-e9a028f166f5 +keywords: ["amli bp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli bp +api_type: +- NA +--- + +# !amli bp + + +The **!amli bp** extension places a breakpoint in AML code. + +Syntax + +``` +!amli bp { MethodName | CodeAddress } +``` + +## Parameters + + + *MethodName* +Specifies the full path of the method name on which the breakpoint will be set. + + *CodeAddress* +Specifies the address of the AML code at which the breakpoint will be set. If *CodeAddress* is prefixed with two percent signs (**%%**), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +The AMLI Debugger supports a maximum of 10 breakpoints. + +Here is an example. The following command will set a breakpoint on the \_DCK method: + +``` +kd> !amli bp \_sb.pci0.dock._dck +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20bp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-cl.md b/windows-driver-docs-pr/debugger/-amli-cl.md new file mode 100644 index 0000000000..3e75e32bb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-cl.md @@ -0,0 +1,49 @@ +--- +title: amli cl +description: The amli cl extension clears the AML interpreter's event log. +ms.assetid: cfba2929-b524-49e8-bbe8-f0feb69e22f9 +keywords: ["amli cl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli cl +api_type: +- NA +--- + +# !amli cl + + +The **!amli cl** extension clears the AML interpreter's event log. + +Syntax + +``` +!amli cl +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20cl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-debugger.md b/windows-driver-docs-pr/debugger/-amli-debugger.md new file mode 100644 index 0000000000..6136411e6b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-debugger.md @@ -0,0 +1,56 @@ +--- +title: amli debugger +description: The amli debugger extension breaks into the AMLI Debugger. +ms.assetid: ef55a45f-445a-4b05-a2a9-b21be3667ec3 +keywords: ["amli debugger Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli debugger +api_type: +- NA +--- + +# !amli debugger + + +The **!amli debugger** extension breaks into the AMLI Debugger. + +Syntax + +``` +!amli debugger +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +When this command is issued, notification is sent to the AML interpreter. The next time the interpreter is active, it will immediately break into the AMLI Debugger. + +The **!amli debugger** extension only causes one break. If you want it to break again, you need to use this extension again, or set a breakpoint. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-dh.md b/windows-driver-docs-pr/debugger/-amli-dh.md new file mode 100644 index 0000000000..5f84a1029b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-dh.md @@ -0,0 +1,52 @@ +--- +title: amli dh +description: The amli dh extension displays the AML interpreter's internal heap block. +ms.assetid: 52027a44-3308-4d9e-be66-8b45cdd88b3b +keywords: ["amli dh Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli dh +api_type: +- NA +--- + +# !amli dh + + +The **!amli dh** extension displays the AML interpreter's internal heap block. + +Syntax + +``` +!amli dh [HeapAddress] +``` + +## Parameters + + + *HeapAddress* +Specifies the address of the heap block. If this is omitted, the global heap is displayed. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20dh%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-dl.md b/windows-driver-docs-pr/debugger/-amli-dl.md new file mode 100644 index 0000000000..4c3cde04ec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-dl.md @@ -0,0 +1,68 @@ +--- +title: amli dl +description: The amli dl extension displays a portion of the AML interpreter's event log. +ms.assetid: 06565760-d7f0-4f22-8670-7706d3b4b3a8 +keywords: ["amli dl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli dl +api_type: +- NA +--- + +# !amli dl + + +The **!amli dl** extension displays a portion of the AML interpreter's event log. + +Syntax + +``` +!amli dl +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +The event log chronicles the most recent 150 events that occurred in the interpreter. + +Here is an example of the log display: + +``` +kd> !amli dl +RUN!: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000000: Ctx=c18b4000,rc=0 +KICK: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000000: rc=0 +SYNC: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000002,LockPhase=0,Locked=0,IRQL=00: Obj=\_WAK +ASYN: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000002,LockPhase=0,Locked=0,IRQL=00: Obj=\_WAK +REST: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000002: Ctx=c18b4000,Obj=\_WAK +INSQ: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000002: Ctx=c18b4000,Obj=\_WAK +EVAL: [c15a6618]QTh=00000000,QCt=00000000,QFg=00000002: Ctx=c18b4000,Obj=\_WAK +RUNC: [c15a6618]QTh=c15a6618,QCt=c18b4000,QFg=00000002: Ctx=c18b4000,Obj=\_WAK +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20dl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-dns.md b/windows-driver-docs-pr/debugger/-amli-dns.md new file mode 100644 index 0000000000..c856a516a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-dns.md @@ -0,0 +1,109 @@ +--- +title: amli dns +description: The amli dns extension displays an ACPI namespace object. +ms.assetid: 7db937ba-109f-4f4e-8dd3-4aa5d0dc13b2 +keywords: ["amli dns Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli dns +api_type: +- NA +--- + +# !amli dns + + +The **!amli dns** extension displays an ACPI namespace object. + +Syntax + +``` +!amli dns [/s] [Name | Address] +``` + +## Parameters + + + **/s** +Causes the entire namespace subtree under the specified object to be displayed recursively. + + *Name* +Specifies the namespace path. + + *Address* +Specifies the address of the namespace node. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +If neither *Name* nor *Address* is specified, the entire ACPI namespace tree is displayed recursively. The **/s** parameter is always assumed in this case, even if it is not specified. + +This command is useful for determining what a particular namespace object is—whether it is a method, a field unit, a device, or another type of object. + +Without the **/s** parameter, this extension is equivalent to the [**!nsobj**](-nsobj.md) extension. With the **/s** parameter, it is equivalent to the [**!nstree**](-nstree.md) extension. + +Here are some examples. The following command displays the namespace for the object **bios**: + +``` +AMLI(? for help)-> dns \bios + +ACPI Name Space: \BIOS (80E5F378) +OpRegion(BIOS:RegionSpace=SystemMemory,Offset=0xfcb07500,Len=2816) +``` + +The following command displays the namespace for the object \_BST, and the tree subordinate to it: + +``` +kd> !amli dns /s \_sb.pci0.isa.bat1._bst + +ACPI Name Space: \_SB.PCI0.ISA.BAT1._BST (c29c2044) +Method(_BST:Flags=0x0,CodeBuff=c29c20a5,Len=103) +``` + +To display the namespace for the device BAT1, type: + +``` +kd> !amli dns /s \_sb.pci0.isa.bat1 +``` + +To display the namespace of everything subordinate to the DOCK device, type: + +``` +kd> !amli dns /s \_sb.pci0.dock +``` + +To display the namespace subordinate to the \_DCK method, type: + +``` +kd> !amli dns /s \_sb.pci0.dock._dck +``` + +To display the entire namespace, type: + +``` +kd> !amli dns +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20dns%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-do.md b/windows-driver-docs-pr/debugger/-amli-do.md new file mode 100644 index 0000000000..2218a33b43 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-do.md @@ -0,0 +1,52 @@ +--- +title: amli do +description: The amli do extension displays an AML data object. +ms.assetid: 5597f691-5402-42da-84f5-d5993231191e +keywords: ["amli do Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli do +api_type: +- NA +--- + +# !amli do + + +The **!amli do** extension displays an AML data object. + +Syntax + +``` +!amli do Address +``` + +## Parameters + + + *Address* +Specifies the address of the data object. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20do%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-ds.md b/windows-driver-docs-pr/debugger/-amli-ds.md new file mode 100644 index 0000000000..6b4c4379a3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-ds.md @@ -0,0 +1,55 @@ +--- +title: amli ds +description: The amli ds extension displays an AML stack. +ms.assetid: 62a1a1dd-c0d8-4509-a29f-16ad2b96b412 +keywords: ["amli ds Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli ds +api_type: +- NA +--- + +# !amli ds + + +The **!amli ds** extension displays an AML stack. + +Syntax + +``` + !amli ds [/v] [Address] +``` + +## Parameters + + + **/v** +Causes the display to be verbose. In Windows 2000, this option is available only if you are using the checked build of this extension (w2kchk\\Acpikd.dll). + + *Address* +Specifies the address of the context block whose stack is desired. If *Address* is omitted, the current context is used. + +### DLL + +The !stacks extension displays information about the kernel stacks. + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20ds%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-find.md b/windows-driver-docs-pr/debugger/-amli-find.md new file mode 100644 index 0000000000..711a1f70d3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-find.md @@ -0,0 +1,84 @@ +--- +title: amli find +description: The amli find extension finds an ACPI namespace object. +ms.assetid: bacb1be2-f079-49da-a8d2-1e9821b20ed3 +keywords: ["amli find Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli find +api_type: +- NA +--- + +# !amli find + + +The **!amli find** extension finds an ACPI namespace object. + +Syntax + +``` +!amli find Name +``` + +## Parameters + + + *Name* +Specifies the name of the namespace object (without the path). + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +The **!amli find** command takes the name of the object and returns the full path and name. The *Name* parameter must be the final segment of the full path and name. + +Here are some examples. The following command will find all declarations of the object \_SRS: + +``` +kd> !amli find _srs +\_SB.LNKA._SRS +\_SB.LNKB._SRS +\_SB.LNKC._SRS +\_SB.LNKD._SRS +``` + +This is not simply a text search. The command **!amli find srs** does not display any hits, because the final segment of each of these declarations is "\_SRS", not "SRS". The command **!amli find LNK** similarly does not return hits. The command **!amli find LNKB** would display the single node that terminates in "LNKB", not the four children of this node shown in the previous display: + +``` +kd> !amli find lnkb +\_SB.LNKB. +``` + +If you need to see the children of a node, use the [**!amli dns**](-amli-dns.md) command with the **/s** parameter. + +Here is another example, issued from the AMLI Debugger prompt. This shows all declarations of the object \_BST in the namespace: + +``` +AMLI(? for help)-> find _bst +\_SB.PCI0.ISA.BAT1._BST +\_SB.PCI0.ISA.BAT2._BST +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20find%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-lc.md b/windows-driver-docs-pr/debugger/-amli-lc.md new file mode 100644 index 0000000000..0c98e60883 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-lc.md @@ -0,0 +1,126 @@ +--- +title: amli lc +description: The amli lc extension lists all active ACPI contexts. +ms.assetid: 070db570-ab8c-47ce-88fa-dc5f16c1c2ee +keywords: ["amli lc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli lc +api_type: +- NA +--- + +# !amli lc + + +The **!amli lc** extension lists all active ACPI contexts. + +Syntax + +``` +!amli lc +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +Each context corresponds to a method currently running in the AML interpreter. + +Here is an example: + +``` +AMLI(? for help)-> lc + Ctxt=80e3f000, ThID=00000000, Flgs=A--C-----, pbOp=00000000, Obj=\_SB.LNKA._STA + Ctxt=80e41000, ThID=00000000, Flgs=A--C-----, pbOp=00000000, Obj=\_SB.LNKB._STA + Ctxt=80e9a000, ThID=00000000, Flgs=A--C-----, pbOp=00000000, Obj=\_SB.LNKC._STA + Ctxt=80ea8000, ThID=00000000, Flgs=A--C-----, pbOp=00000000, Obj=\_SB.LNKD._STA +*Ctxt=80e12000, ThID=80e6eda8, Flgs=---CR----, pbOp=80e5d5ac, Obj=\_SB.LNKA._STA +``` + +The **Obj** field gives the full path and name of the method as it appears in the ACPI tables. + +The **Ctxt** field gives the address of the context block. The asterisk (**\***) indicates the *current context*. This is the context that was being executed by the interpreter when the break occurred. + +The abbreviation **pbOp** indicates the instruction pointer (pointer to binary op codes). + +There are nine flags that can be displayed in the **Flgs** section. If a flag is not set, a hyphen is displayed instead. The full list of flags is as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning

A

Asynchronous evaluation

N

Nested evaluation

Q

In the ready queue

C

Needs a callback

R

Running

W

Ready

T

Time-out

D

Timer dispatch

P

Timer pending

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20lc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-ln.md b/windows-driver-docs-pr/debugger/-amli-ln.md new file mode 100644 index 0000000000..1fe88ca143 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-ln.md @@ -0,0 +1,69 @@ +--- +title: amli ln +description: The amli ln extension displays the specified method or the method containing a given address. +ms.assetid: f763f185-cce2-4bfb-948d-243acfb53aaa +keywords: ["amli ln Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli ln +api_type: +- NA +--- + +# !amli ln + + +The **!amli ln** extension displays the specified method or the method containing a given address. + +Syntax + +``` +!amli ln [ MethodName | CodeAddress ] +``` + +## Parameters + + + *MethodName* +Specifies the full path of the method name. If *MethodName* specifies an object that is not actually a method, an error results. + + *CodeAddress* +Specifies the address of the AML code that is contained in the desired method. If *CodeAddress* is prefixed with two percent signs (**%%**), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +If neither *MethodName* nor *CodeAddress* is specified, the method associated with the current context is displayed. + +The following command shows the method being currently run: + +``` +kd> !amli ln +c29accf5: \_WAK +``` + +The method \_WAK is shown, with address 0xC29ACCF5. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20ln%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-r.md b/windows-driver-docs-pr/debugger/-amli-r.md new file mode 100644 index 0000000000..78de9a0ae4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-r.md @@ -0,0 +1,88 @@ +--- +title: amli r +description: The amli r extension displays information about the current context or the specified context. +ms.assetid: 1a8977ed-a420-4f68-8580-8e7446075283 +keywords: ["amli r Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli r +api_type: +- NA +--- + +# !amli r + + +The **!amli r** extension displays information about the current context or the specified context. + +Syntax + +``` +!amli r [ContextAddress] +``` + +## Parameters + + + *ContextAddress* +Specifies the address of the context block to be displayed. The address of a context block can be determined from the **Ctxt** field in the [**!amli lc**](-amli-lc.md) display. If *ContextAddress* is prefixed with two percent signs (**%%**), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. If this parameter is omitted, the current context is displayed. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +If the AMLI Debugger prompt appears suddenly, this is a useful command to use. + +For example, the following command will display the current context of the interpreter: + +``` +AMLI(? for help)-> r + +Context=c18b4000*, Queue=00000000, ResList=00000000 +ThreadID=c15a6618, Flags=00000010 +StackTop=c18b5eec, UsedStackSize=276 bytes, FreeStackSize=7636 bytes +LocalHeap=c18b40c0, CurrentHeap=c18b40c0, UsedHeapSize=88 bytes +Object=\_WAK, Scope=\_WAK, ObjectOwner=c18b4108, SyncLevel=0 +AsyncCallBack=ff06b5d0, CallBackData=0, CallBackContext=c99efddc + +MethodObject=\_WAK +80e0ff5c: Local0=Unknown() +80e0ff70: Local1=Unknown() +80e0ff84: Local2=Unknown() +80e0ff98: Local3=Unknown() +80e0ffac: Local4=Unknown() +80e0ffc0: Local5=Unknown() +80e0ffd4: Local6=Unknown() +80e0ffe8: Local7=Unknown() +80e0e040: RetObj=Unknown() + +Next AML Pointer: ffffffff80e630df:[\_WAK+16] + +ffffffff80e630df : If(S4BW +ffffffff80e630e5 : { +ffffffff80e630e5 : | Store(Zero, S4BW) +ffffffff80e630eb : } +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20r%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-set.md b/windows-driver-docs-pr/debugger/-amli-set.md new file mode 100644 index 0000000000..d98e95b14f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-set.md @@ -0,0 +1,115 @@ +--- +title: amli set +description: The amli set extension sets or displays the AMLI Debugger options. +ms.assetid: 521fa305-8073-4d94-bc28-fdb35cbc2acd +keywords: ["amli set Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli set +api_type: +- NA +--- + +# !amli set + + +The **!amli set** extension sets or displays the AMLI Debugger options. + +``` +!amli set Options +``` + +## Parameters + + + *Options* +Specifies one or more options to be set. Separate multiple options with spaces. Possible values include: + +**spewon** +Causes full debug output to be sent from the target computer. This option should be left on at all times for effective AML debugging. See the Remarks section for details. + +**spewoff** +Suppresses debug output. + +**verboseon** +Turns on verbose mode. This causes the AMLI Debugger to display the names of AML methods as they are evaluated. + +**verboseoff** +Turns off verbose mode. + +**traceon** +Activates ACPI tracing. This produces much more output than the **verboseon** option. This option is very useful for tracking SMI-related hard hangs. + +**traceoff** +Deactivates ACPI tracing. + +**nesttraceon** +Activates nest tracing. This option is only effective if the **traceon** option is also selected. + +**dbgbrkon** +Enables breaking into the AMLI Debugger. + +**dbgbrkoff** +Deactivates the dbgbrkon option. + +**nesttraceoff** +Deactivates nest tracing. + +**lbrkon** +Breaks into the AMLI Debugger when DDB loading is completed. + +**lbrkoff** +Deactivates the **lbrkon** option. + +**errbrkon** +Breaks into the AMLI Debugger whenever the interpreter has a problem evaluating AML code. + +**errbrkoff** +Deactivates the **errbrkon** option. + +**logon** +Enables event logging. + +**logoff** +Disables event logging. + +**logmuton** +Enables mutex event logging. + +**logmutoff** +Disables mutex event logging. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +If no options are specified, the current status of all options is displayed. + +By default, many messages are filtered out, you may need to turn this output on with **!amli set spewon**. Otherwise, numerous AMLI Debugger messages will be lost. + +If the AML interpreter breaks into the AMLI Debugger, this output will be automatically turned on. + +For more details on this output filtering, see **DbgPrintEx** and **KdPrintEx** in the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20set%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-amli-u.md b/windows-driver-docs-pr/debugger/-amli-u.md new file mode 100644 index 0000000000..a39e1e3068 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-amli-u.md @@ -0,0 +1,84 @@ +--- +title: amli u +description: The amli u extension unassembles AML code. +ms.assetid: 0a8b160f-9aae-4ef0-a569-8e701de9679c +keywords: ["amli u Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- amli u +api_type: +- NA +--- + +# !amli u + + +The **!amli u** extension unassembles AML code. + +Syntax + +``` +!amli u [ MethodName | CodeAddress ] +``` + +## Parameters + + + *MethodName* +Specifies the full path of the method name to be disassembled. + + *CodeAddress* +Specifies the address of the AML code where disassembly will begin. If *CodeAddress* is prefixed with two percent signs (**%%**), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about related commands and their uses, see [The AMLI Debugger](the-amli-debugger.md). + +Remarks +------- + +If neither *MethodName* nor *CodeAddress* is specified and you are issuing this command from an AMLI + +The disassembly display will continue until the end of the method is reached. + +**Note**   The standard [**u (Unassemble)**](u--unassemble-.md) command will not give proper results with AML code. + +  + +Here are some examples. To disassemble the object at address 0x80E5D701, use the following command: + +``` +kd> !amli u 80e5d701 + +ffffffff80e5d701 : CreateWordField(CRES, 0x1, IRQW) +ffffffff80e5d70c : And(\_SB_.PCI0.LPC_.PIRA, 0xf, Local0) +ffffffff80e5d723 : Store(One, Local1) +ffffffff80e5d726 : ShiftLeft(Local1, Local0, IRQW) +ffffffff80e5d72d : Return(CRES) +``` + +The following command will disassemble the \_DCK method: + +``` +kd> u \_sb.pci0.dock._dck +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!amli%20u%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-analyze.md b/windows-driver-docs-pr/debugger/-analyze.md new file mode 100644 index 0000000000..2ecbdf1a97 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-analyze.md @@ -0,0 +1,100 @@ +--- +title: analyze +description: The analyze extension displays information about the current exception or bug check. +ms.assetid: dec760fb-0af6-4504-9855-8fe63c1c9783 +keywords: ["analyze Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- analyze +api_type: +- NA +--- + +# !analyze + + +The **!analyze** extension displays information about the current exception or bug check. + +User-Mode + +``` +!analyze [-v] [-f | -hang] [-D BucketID] +!analyze -c [-load KnownIssuesFile | -unload | -help ] +``` + +Kernel-Mode + +``` +!analyze [-v] [-f | -hang] [-D BucketID] +!analyze -c [-load KnownIssuesFile | -unload | -help ] +!analyze -show BugCheckCode [BugParameters] +``` + +## Parameters + + + **-v** +Displays verbose output. + +**-f** +Generates the **!analyze** exception output. Use this parameter to see an exception analysis even when the debugger does not detect an exception. + +**-hang** +Generates **!analyze** hung-application output. Use this parameter when the target has experienced a bug check or exception, but an analysis of why an application hung is more relevant to your problem. In kernel mode, **!analyze** **-hang** investigates locks that the system holds and then scans the DPC queue chain. In user mode, **!analyze** **-hang** analyzes the thread stack to determine whether any threads are blocking other threads. + +Before you run this extension in user mode, consider changing the current thread to the thread that you think has stopped responding (that is, hung), because the exception might have changed the current thread to a different one. + + **-D** *BucketID* +Displays only those items that are relevant to the specified *BucketID*. + + **-show** *BugCheckCode* \[*BugParameters*\] +Displays information about the bug check specified by *BugCheckCode*. *BugParameters* specifies up to four bug check parameters separated by spaces. These parameters enable you to further refine your search. + + **-c** +Continues execution when the debugger encounters a known issue. If the issue is not a "known" issue, the debugger remains broken into the target. + +You can use the **-c** option with the following subparameters. These subparameters configure the list of known issues. They do not cause execution to occur by themselves. Until you run **!analyze** **-c** **** **-load** at least one time, **!analyze** **-c** has no effect. + +**-load** *KnownIssuesFile* +Loads the specified known-issues file. *KnownIssuesFile* specifies the path and file name of this file. This file must be in XML format. You can find a sample file in the sdk\\samples\\analyze\_continue subdirectory of the debugger installation directory. (You must have performed a full installation of Debugging Tools for Windows to have this file.) + +The list of known issues in the *KnownIssuesFile* file is used for all later **-c** commands until you use **-c** **** **-unload**, or until you use **-c** **** **-load** again (at which point the new data replaces the old data). + +**-unload** +Unloads the current list of known issues. + +**-help** +Displays help for the **!analyze** **-c** extension commands extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + +Ext.dll + +### Additional Information + +For sample analysis of a user-mode exception and of a kernel-mode stop error (that is, crash), and for more information about how **!analyze** uses the triage.ini file, see [Using the !analyze Extension](using-the--analyze-extension.md). + +Remarks +------- + +In user mode, **!analyze** displays information about the current exception. + +In kernel mode, **!analyze** displays information about the most recent bug check. If a bug check occurs, the **!analyze** display is automatically generated. You can use **!analyze** **-v** to show additional information. If you want to see only the basic bug check parameters, you can use the [**.bugcheck (Display Bug Check Data)**](-bugcheck--display-bug-check-data-.md) command. + +For drivers that use User-Mode Driver Framework (UMDF) version 2.15 or later, **!analyze** provides information about UMDF verifier failures and unhandled exceptions. This functionality is available when performing live kernel-mode debugging, as well when analyzing a user-mode memory dump file. For UMDF driver crashes, **!analyze** attempts to identify the responsible driver. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!analyze%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-analyzebugcheck.md b/windows-driver-docs-pr/debugger/-analyzebugcheck.md new file mode 100644 index 0000000000..77e629e7ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/-analyzebugcheck.md @@ -0,0 +1,29 @@ +--- +title: analyzebugcheck +description: analyzebugcheck +ms.assetid: e1d50d3f-558d-4d2a-be30-5124076fff52 +keywords: ["analyzebugcheck extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !analyzebugcheck + + +## + + +The **!analyzebugcheck** extension command is obsolete. Use [**!analyze**](-analyze.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!analyzebugcheck%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-apc.md b/windows-driver-docs-pr/debugger/-apc.md new file mode 100644 index 0000000000..9a0cf9fc9d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-apc.md @@ -0,0 +1,109 @@ +--- +title: apc +description: The apc extension formats and displays the contents of one or more asynchronous procedure calls (APCs). +ms.assetid: 0c5a9d1e-ab61-4b14-b06b-25cde582cc73 +keywords: ["apc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- apc +api_type: +- NA +--- + +# !apc + + +The **!apc** extension formats and displays the contents of one or more asynchronous procedure calls (APCs). + +``` +!apc +!apc proc Process +!apc thre Thread +!apc KAPC +``` + +## Parameters + + +*Process* +Specifies the address of the process whose APCs are to be displayed. + +*Thread* +Specifies the address of the thread whose APCs are to be displayed. + + *KAPC* +Specifies the address of the kernel APC to be displayed. + +## DLL + + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +## Additional Information + + +For information about APCs, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon. + +Remarks +------- + +Without any parameters, **!apc** displays all APCs. + +Here is an example: + +``` +kd> !apc +*** Enumerating APCs in all processes +Process e0000000858ba8b0 System +Process e0000165fff86040 smss.exe +Process e0000165fff8c040 csrss.exe +Process e0000165fff4e1d0 winlogon.exe +Process e0000165fff101d0 services.exe +Process e0000165fffa81d0 lsass.exe +Process e0000165fff201d0 svchost.exe +Process e0000165fff8e040 svchost.exe +Process e0000165fff3e040 svchost.exe +Process e0000165fff6e040 svchost.exe +Process e0000165fff24040 spoolsv.exe +Process e000000085666640 wmiprvse.exe +Process e00000008501e520 wmiprvse.exe +Process e0000000856db480 explorer.exe +Process e0000165fff206a0 ctfmon.exe +Process e0000000850009d0 ctfmon.exe +Process e0000165fff51600 conime.exe +Process e000000085496340 taskmgr.exe +Process e000000085489c30 userinit.exe +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!apc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-apicerr.md b/windows-driver-docs-pr/debugger/-apicerr.md new file mode 100644 index 0000000000..4aecc953c6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-apicerr.md @@ -0,0 +1,75 @@ +--- +title: apicerr +description: The apicerr extension displays the local Advanced Programmable Interrupt Controller (APIC) error log. +ms.assetid: b058412b-a4df-42cc-8550-b5db4e0bbccc +keywords: ["APIC (Advanced Programmable Interrupt Controller)", "apicerr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- apicerr +api_type: +- NA +--- + +# !apicerr + + +The **!apicerr** extension displays the local Advanced Programmable Interrupt Controller (APIC) error log. + +``` + !apicerr [Format] +``` + +## Parameters + + + *Format* +Specifies the order in which to display the error log contents. This can be any one of the following values: + +0x0 +Displays the error log according to order of occurrence. + +0x1 +Displays the error log according to processor. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based or an x64-based target computer. + +### Additional Information + +For information about APICs, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!apicerr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-apply-dbp--apply-data-breakpoint-to-context-.md b/windows-driver-docs-pr/debugger/-apply-dbp--apply-data-breakpoint-to-context-.md new file mode 100644 index 0000000000..ff6d431c7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-apply-dbp--apply-data-breakpoint-to-context-.md @@ -0,0 +1,84 @@ +--- +title: .apply_dbp (Apply Data Breakpoint to Context) +description: The .apply_dbp command applies the current process' existing data breakpoints to the specified register context. +ms.assetid: c74fd4b3-3335-4e03-a57a-6a9aa883dd9f +keywords: [".apply_dbp (Apply Data Breakpoint to Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .apply_dbp (Apply Data Breakpoint to Context) +api_type: +- NA +--- + +# .apply\_dbp (Apply Data Breakpoint to Context) + + +The **.apply\_dbp** command applies the current process' existing data breakpoints to the specified register context. + +``` + .apply_dbp [/m Context] +``` + +## Parameters + + + **/m** *Context* +Specifies the address of a register context (CONTEXT structure) in memory to which to apply the current process' data breakpoints. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode and kernel mode

Targets

live target only

Platforms

all

+ +  + +### Additional Information + +For more information about breakpoints controlled by the processor, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). For more information about the register context (thread context), see [Register Context](changing-contexts.md#register-context). + +Remarks +------- + +Breakpoints that are controlled by the processor are called *data breakpoints* or *processor breakpoints*. These breakpoints are created by the [**ba (Break on Access)**](ba--break-on-access-.md) command. + +These breakpoints are associated with a memory location in the address space of a specific process. The **.apply\_dbp** command modifies the specified register context so that these data breakpoints will be active when this context is used. + +If the **/m** *Address* parameter is not used, data breakpoints will be applied to the current register context. + +This command can only be used if the target is in native machine mode. For example, if the target is running on a 64-bit machine emulating an x86 processor using [*WOW64*](https://msdn.microsoft.com/library/windows/hardware/ff556347#wdkgloss-wow64), this command cannot be used. + +One example of a time this command is useful is when you are in an exception filter. The **.apply\_dbp** command can update the exception filter's stored context. Data breakpoints will then be applied when the exception filter exits and the stored context is resumed. Without such a modification it is possible that data breakpoints would be lost. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.apply_dbp%20%28Apply%20Data%20Breakpoint%20to%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-arbinst.md b/windows-driver-docs-pr/debugger/-arbinst.md new file mode 100644 index 0000000000..72467c81b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-arbinst.md @@ -0,0 +1,99 @@ +--- +title: arbinst +description: The arbinst extension displays information about a specified arbiter. +ms.assetid: 6aa06283-9cd7-4579-9e5d-40bbaf53f782 +keywords: ["arbiter", "arbinst Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- arbinst +api_type: +- NA +--- + +# !arbinst + + +The **!arbinst** extension displays information about a specified arbiter. + +``` +!arbinst Address [Flags] +``` + +## Parameters + + +*Address* +Specifies the hexadecimal address of the arbiter to be displayed. + +*Flags* +Specifies how much information to display for each arbiter. At present, the only flag is 0x100. If this flag is set, then the aliases are displayed. + +## DLL + + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +## Additional Information + + +See also the [**!arbiter**](-arbiter.md) extension. + +Remarks +------- + +For the arbiter specified, **!arbinst** displays each allocated range of system resources, some optional flags, the PDO attached to that range (in other words, the range's owner), and the service name of this owner (if known). + +Here is an example: + +``` +kd> !arbinst e0000106002ee8e8 +Port Arbiter "PCI I/O Port (b=02)" at e0000106002ee8e8 + Allocated ranges: + 0000000000000000 - 0000000000001fff 00000000 + 0000000000002000 - 00000000000020ff P e0000000858bea20 (ql1280) + 0000000000003000 - ffffffffffffffff 00000000 + Possible allocation: + < none > +kd> !arbinst e0000106002ec458 +Memory Arbiter "PCI Memory (b=02)" at e0000106002ec458 + Allocated ranges: + 0000000000000000 - 00000000ebffffff 00000000 + 00000000effdef00 - 00000000effdefff B e0000000858be560 + 00000000effdf000 - 00000000effdffff e0000000858bea20 (ql1280) + 00000000f0000000 - ffffffffffffffff 00000000 + Possible allocation: + < none > +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!arbinst%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-arbiter.md b/windows-driver-docs-pr/debugger/-arbiter.md new file mode 100644 index 0000000000..7b71b6656f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-arbiter.md @@ -0,0 +1,168 @@ +--- +title: arbiter +description: The arbiter extension displays the current system resource arbiters and arbitrated ranges. +ms.assetid: 95149538-6fcd-4638-b35f-4e1a562e5231 +keywords: ["arbiter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- arbiter +api_type: +- NA +--- + +# !arbiter + + +The **!arbiter** extension displays the current system resource arbiters and arbitrated ranges. + +``` +!arbiter [Flags] +``` + +## Parameters + + + *Flags* +Specifies which classes of arbiters are displayed. If omitted, all arbiters are displayed. These bits can be combined freely. + +Bit 0 (0x1) +Display I/O arbiters. + +Bit 1 (0x2) +Display memory arbiters. + +Bit 2 (0x4) +Display IRQ arbiters. + +Bit 3 (0x8) +Display DMA arbiters. + +Bit 4 (0x10) +Display bus number arbiters. + +Bit 8 (0x100) +Do not display aliases. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. + +Remarks +------- + +For each arbiter, **!arbiter** displays each allocated range of system resources, some optional flags, the PDO attached to that range (in other words, the range's owner), and the service name of this owner (if known). + +The flags have the following meanings: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning

S

Range is shared

C

Range in conflict

B

Range is boot-allocated

D

Range is driver-exclusive

A

Range alias

P

Range positive decode

+ +  + +Here is an example: + +``` +kd> !arbiter 4 + +DEVNODE 80e203b8 (HTREE\ROOT\0) + Interrupt Arbiter "" at 80167140 + Allocated ranges: + 0000000000000000 - 0000000000000000 B 80e1d3d8 + 0000000000000001 - 0000000000000001 B 80e1d3d8 + ..... + 00000000000001a2 - 00000000000001a2 + 00000000000001a2 - 00000000000001a2 CB 80e1d3d8 + 00000000000001a2 - 00000000000001a2 CB 80e52538 (Serial) + 00000000000001a3 - 00000000000001a3 80e52778 (i8042prt) + 00000000000001b3 - 00000000000001b3 80e1b618 (i8042prt) + Possible allocation: + < none > +``` + +In this example, the next-to-last line shows the resource range (which consists of 0x1A3 alone), the PDO of 0x80E52778, and the service of i8042prt.sys. No flags are listed on this line. + +You can now use [**!devobj**](-devobj.md) with this PDO address to find the device extension and device node addresses: + +``` +kd> !devobj 80e52778 +Device object (80e52778) is for: + 00000034 \Driver\PnpManager DriverObject 80e20610 +Current Irp 00000000 RefCount 1 Type 00000004 Flags 00001040 +DevExt 80e52830 DevObjExt 80e52838 DevNode 80e52628 +ExtensionFlags (0000000000) +AttachedDevice (Upper) 80d78b28 \Driver\i8042prt +Device queue is not busy. +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!arbiter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-asd.md b/windows-driver-docs-pr/debugger/-asd.md new file mode 100644 index 0000000000..70c27d3b93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-asd.md @@ -0,0 +1,75 @@ +--- +title: asd +description: The asd extension displays a specified number of failure analysis entries from the data cache, starting at the specified address. +ms.assetid: fb0eeedd-d50b-4385-b35f-4ac46fb97ce0 +keywords: ["failure analysis entries, display from data cache", "asd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- asd +api_type: +- NA +--- + +# !asd + + +The **!asd** extension displays a specified number of failure analysis entries from the data cache, starting at the specified address. + +``` +!asd Address DataUsed +``` + +## Parameters + + + *Address* +Specifies the address of the first failure analysis entry to display. + + *DataUsed* +Determines the number of tokens to display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +You can use the [**!dumpfa**](-dumpfa.md) extension to debug the [**!analyze**](-analyze.md) extension. + +Remarks +------- + +The **!asd** extension is useful only when you are debugging the [**!analyze**](-analyze.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!asd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-asm--change-disassembly-options-.md b/windows-driver-docs-pr/debugger/-asm--change-disassembly-options-.md new file mode 100644 index 0000000000..cfd1784e5b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-asm--change-disassembly-options-.md @@ -0,0 +1,94 @@ +--- +title: .asm (Change Disassembly Options) +description: The .asm command controls how disassembly code will be displayed. +ms.assetid: c963c4f2-3bfc-4551-9b7b-74473a63eb11 +keywords: ["Change Disassembly Options (.asm) command", "assembly debugging, Change Disassembly Options (.asm) command", ".asm (Change Disassembly Options) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .asm (Change Disassembly Options) +api_type: +- NA +--- + +# .asm (Change Disassembly Options) + + +The **.asm** command controls how disassembly code will be displayed. + +``` +.asm +.asm[-] Options +``` + +## Parameters + + + **-** +Causes the specified options to be disabled. If no minus sign is used, the specified options will be enabled. + + *Options* +Can be any number of the following options: + +**ignore\_output\_width** +Prevents the debugger from checking the width of lines in the disassembly display. + +**no\_code\_bytes** +(x86 and x64 targets only) Suppresses the display of raw bytes. + +**source\_line** +Prefixes each line of disassembly with the line number of the source code. + +**verbose** +(Itanium target only) Causes bundle-type information to be displayed along with the standard disassembly information. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For a description of assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +Using **.asm** by itself displays the current state of the options. + +This command affects the display of any disassembly instructions in the Debugger Command window. In WinDbg it also changes the contents of the Disassembly window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.asm%20%28Change%20Disassembly%20Options%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ate.md b/windows-driver-docs-pr/debugger/-ate.md new file mode 100644 index 0000000000..8855710875 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ate.md @@ -0,0 +1,147 @@ +--- +title: ate +description: The ate extension displays the alternate page table entry (ATE) for the specified address. +ms.assetid: 8ec98fa5-4939-49cb-8678-e412b9cbe7e3 +keywords: ["ate Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ate +api_type: +- NA +--- + +# !ate + + +The **!ate** extension displays the alternate page table entry (ATE) for the specified address. + +``` +!ate Address +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Address* +Specifies the ATE to display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about page tables and page directories, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +This extension is only available on Itanium-based computers. + +The status flags for the ATE are shown in the following table. The **!ate** display indicates these bits with capital letters or dashes and adds additional information as well. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Display when setDisplay when clearMeaning

V

-

Commit.

G

-

Not accessed.

E

-

Execute.

W

R

Writeable or read-only.

L

-

Locked. The ATE is locked, therefore, any faults on the page that contain the ATE will be retried until the current fault is satisfied. This can happen on multi-processor systems.

Z

-

Fill zero.

N

-

No access.

C

-

Copy on Write.

I

-

PTE indirect. This ATE indirectly references another physical page. The page that contains the ATE might have two conflicting ATE attributes.

P

Reserved.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ate%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-atom.md b/windows-driver-docs-pr/debugger/-atom.md new file mode 100644 index 0000000000..c6fd694805 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-atom.md @@ -0,0 +1,69 @@ +--- +title: atom +description: The atom extension displays the formatted atom table for the specified atom or for all atoms of the current process. +ms.assetid: b4127e4f-a20b-497f-ad84-efea0df0dc80 +keywords: ["atom Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- atom +api_type: +- NA +--- + +# !atom + + +The **!atom** extension displays the formatted atom table for the specified atom or for all atoms of the current process. + +``` + !atom [Address] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal virtual address of the atom to display. If you omit this parameter or specify zero, the atom table for the current process is displayed. This table lists all atoms for the process. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +For more information about atoms and atom tables, see the Microsoft Windows SDK documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!atom%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-attach--attach-to-process-.md b/windows-driver-docs-pr/debugger/-attach--attach-to-process-.md new file mode 100644 index 0000000000..6b5549f1e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-attach--attach-to-process-.md @@ -0,0 +1,108 @@ +--- +title: .attach (Attach to Process) +description: The .attach command attaches to a new target application. +ms.assetid: e637c7eb-9c3c-4501-b972-a9293a6da52a +keywords: ["Attach to Process (.attach) command", "process, Attach to Process (.attach) command", ".attach (Attach to Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .attach (Attach to Process) +api_type: +- NA +--- + +# .attach (Attach to Process) + + +The **.attach** command attaches to a new target application. + +``` +.attach [-premote RemoteOptions] AttachOptions PID +``` + +## Parameters + + + *RemoteOptions* +Specifies a process server to attach to. The options are the same as those for the command line **-premote** option. See [**Activating a Smart Client**](activating-a-smart-client.md) for syntax details. + + *AttachOptions* +Specifies how the attach is to be done. This can include any of the following options: + +**-b** +(Windows XP and later) Prevents the debugger from requesting an initial break-in when attaching to a target process. This can be useful if the application is already suspended, or if you want to avoid creating a break-in thread in the target. + +**-e** +(Windows XP and later) Allows the debugger to attach to a process that is already being debugged. See [Re-attaching to the Target Application](reattaching-to-the-target-application.md) for details. + +**-k** +(Windows XP and later) Begins a local kernel debugging session. See [Performing Local Kernel Debugging](performing-local-kernel-debugging.md) for details. + +**-f** +Freezes all threads in all target applications, except in the new target being attached to. These threads will remain frozen until an exception occurs in the newly-attached process. Note that an initial breakpoint qualifies as an exception. Individual threads can be unfrozen by using the [**~u (Unfreeze Thread)**](-u--unfreeze-thread-.md) command. + +**-r** +(Windows XP and later) + +Causes the debugger to start the target process running when it attaches to it. This can be useful if the application is already suspended and you want it to resume execution. + +**-v** +Causes the specified process to be debugged noninvasively. + + *PID* +Specifies the process ID of the new target application. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +This command can be used when CDB is dormant, or if it is already debugging one or more processes. It cannot be used when WinDbg is dormant. + +If this command is successful, the debugger will attach to the specified process the next time the debugger issues an execution command. If this command is used several times in a row, execution will have to be requested as many times as this command was used. + +Because execution is not permitted during noninvasive debugging, the debugger is not able to noninvasively debug more than one process at a time. This also means that using the **.attach -v** command may render an already-existing invasive debugging session less useful. + +Multiple target processes will always be executed together, unless some of their threads are frozen or suspended. + +If you wish to attach to a new process and freeze all your existing targets, use the **-f** option. For example, you might be debugging a crash in a client application and want to attach to the server process without letting the client application continue running. + +If the **-premote** option is used, the new process will be part of a new system. For details, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.attach%20%28Attach%20to%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-avrf.md b/windows-driver-docs-pr/debugger/-avrf.md new file mode 100644 index 0000000000..2cd34b491a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-avrf.md @@ -0,0 +1,145 @@ +--- +title: avrf +description: The avrf extension controls the settings of Application Verifier and displays a variety of output produced by Application Verifier. +ms.assetid: e9313954-a1fa-45a9-bc1a-78be2451f5aa +keywords: ["avrf Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- avrf +api_type: +- NA +--- + +# !avrf + + +The **!avrf** extension controls the settings of [Application Verifier](application-verifier.md) and displays a variety of output produced by Application Verifier. + +``` +!avrf +!avrf -vs { Length | -a Address } +!avrf -hp { Length | -a Address } +!avrf -cs { Length | -a Address } +!avrf -dlls [ Length ] +!avrf -trm +!avrf -ex [ Length ] +!avrf -threads [ ThreadID ] +!avrf -tp [ ThreadID ] +!avrf -srw [ Address | Address Length ] [ -stats ] +!avrf -leak [ -m ModuleName] [ -r ResourceType] [ -a Address ] [ -t ] +!avrf -trace TraceIndex +!avrf -cnt +!avrf -brk [BreakEventType] +!avrf -flt [EventType Probability] +!avrf -flt break EventType +!avrf -flt stacks Length +!avrf -trg [ Start End | dll Module | all ] +!avrf -settings +!avrf -skp [ Start End | dll Module | all | Time ] +``` + +## Parameters + + +**-vs {** *Length* **| -a** *Address* **}** +Displays the virtual space operation log. *Length* specifies the number of records to display, starting with the most recent. *Address* specifies the virtual address. Records of the virtual operations that contain this virtual address are displayed. + +**-hp {** *Length* **| -a** *Address* **}** +Displays the heap operation log. *Address* specifies the heap address. Records of the heap operations that contain this heap address are displayed. + +**-cs {** *Length* **| -a** *Address* **}** +Displays the critical section delete log. *Length* specifies the number of records to display, starting with the most recent. *Address* specifies the critical section address. Records for the particular critical section are displayed when *Address* is specified. + +**-dlls \[** *Length* **\]** +Displays the DLL load/unload log. *Length* specifies the number of records to display, starting with the most recent. + +**-trm** +Displays a log of all terminated and suspended threads. + +**-ex \[** *Length* **\]** +Displays the exception log. Application Verifier tracks all the exceptions in the application. + +**-threads \[** *ThreadID* **\]** +Displays information about threads in the target process. For child threads, the stack size and the **CreateThread** flags specified by the parent are also displayed. If you provide a thread ID, information for only that thread is displayed. + +**-tp \[** *ThreadID* **\]** +Displays the threadpool log. This log contains stack traces for various operations such as changing the thread affinity mask, changing thread priority, posting thread messages, and initializing or uninitializing COM from within the threadpool callback. If you provide a thread ID, information for that thread only is displayed. + +**-srw \[** *Address* **|** *Address Length* **\] \[ -stats \]** +Displays the Slim Reader/Writer (SRW) log. If you specify *Address*, records for the SRW lock at that address are displayed. If you specify *Address* and *Length*, records for SRW locks in that address range are displayed. If you include the **-stats** option, the SRW lock statistics are displayed. + +**-leak \[ -m** *ModuleName***\] \[ -r** *ResourceType***\] \[ -a** *Address* **\] \[ -t \]** +Displays the outstanding resources log. These resources may or may not be leaks at any given point. If you specify *Modulename* (including the extension), all outstanding resources in the specified module are displayed. If you specify *ResourceType*, all outstanding resources of that resource type are displayed. If you specify *Address*, records of outstanding resources with that address are displayed. *ResourceType* can be one of the following: + +Heap: Displays heap allocations using Win32 Heap APIs + +Local: Displays Local/Global allocations + +CRT: Displays allocations using CRT APIs + +Virtual: Displays Virtual reservations + +BSTR: Displays BSTR allocations + +Registry: Displays Registry key opens + +Power: Displays power notification objects + +Handle: Displays thread, file, and event handle allocations + +**-trace** *TraceIndex* +Displays a stack trace for the specified trace index. Some structures use this 16-bit index number to identify a stack trace. This index points to a location within the stack trace database. + +**-cnt** +Displays a list of global counters. + +**-brk \[** *BreakEventType* **\]** +Specifies a break event. *BreakEventType* is the type number of the break event. For a list of possible types, and a list of the current break event settings, enter **!avrf -brk**. + +**-flt \[** *EventType Probability* **\]** +Specifies a fault injection. *EventType* is the type number of the event. *Probability* is the frequency with which the event will fail. This can be any integer between 0 and 1,000,000 (0xF4240). If you enter **!avrf -flt** with no additional parameters, the current fault injection settings are displayed. + +-**flt break** *EventType* +Causes Application Verifier to break into the debugger each time this fault, specified by *EventType*, is injected. + +**-flt stacks** *Length* +Displays *Length* number of stack traces for the most recent fault-injected operations. + +**-trg \[** *Start End* **| dll** *Module* **| all \]** +Specifies a target range. *Start* is the beginning address of the target range. *End* is the ending address of the target range. *Module* specifies the name (including the .exe or .dll extension, but not including the path) of a module to be targeted. If you enter **-trg all**, all target ranges are reset. If you enter **-trg** with no additional parameters, the current target ranges are displayed. + +**-skp \[** *Start End* **| dll** *Module* **| all |** *Time* **\]** +Specifies an exclusion range. *Start* is the beginning address of the exclusion range. *End* is the ending address of the exclusion range. Module specifies the name of a module to be targeted or excluded. *Module* specifies the name (including the .exe or .dll extension, but not including the path) of a module to be excluded. If you enter **-skp all**, all target ranges or exclusion ranges are reset. If you enter a*Time* value, all faults are suppressed for *Time* milliseconds after execution resumes. + +### DLL + +exts.dll + +### Additional Information + +For information about how to download and install Application Verifier and its documentation, see [Application Verifier](application-verifier.md). + +Remarks +------- + +When the **!avrf** extension is used with no parameters, it displays the current Application Verifier options. If the **Full page heap** or **Fast fill heap** option has been enabled, information about active page heaps is displayed as well. For some examples, see "Heap Operation Logs" in the Application Verifier documentation. + +If an Application Verifier Stop has occurred, the **!avrf** extension with no parameters will reveal the nature of the stop and its cause. For some examples, see "Debugging Application Verifier Stops" in the Application Verifier documentation. + +If symbols for ntdll.dll and verifier.dll are missing, the **!avrf** extension generates an error message. For information about how to address this problem, see "Setting Up a Debugger for Application Verifier" in the Application Verifier documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!avrf%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bcb.md b/windows-driver-docs-pr/debugger/-bcb.md new file mode 100644 index 0000000000..6d28a5220d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bcb.md @@ -0,0 +1,74 @@ +--- +title: bcb +description: The bcb extension displays the specified buffer control block. +ms.assetid: 4e98e900-5e9d-40a4-9c39-4dc3611d8ea3 +keywords: ["cache manager", "bcb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bcb +api_type: +- NA +--- + +# !bcb + + +The **!bcb** extension displays the specified buffer control block. + +``` +!bcb Address +``` + +## Parameters + + + *Address* +Specifies the address of the buffer control block. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable (see Remarks section)

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For information about other cache management extensions, use the [**!cchelp**](-cchelp.md) extension. + +Remarks +------- + +This extension is available for Windows 2000 only. In Windows XP or later, use the [**dt nt!\_BCB Address**](dt--display-type-.md) command to display the buffer control block directly. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bcb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-beep--speaker-beep-.md b/windows-driver-docs-pr/debugger/-beep--speaker-beep-.md new file mode 100644 index 0000000000..c8d16873f8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-beep--speaker-beep-.md @@ -0,0 +1,63 @@ +--- +title: .beep (Speaker Beep) +description: The .beep command makes noise on the computer speaker. +ms.assetid: b7edc3a6-9d15-461b-bcc6-8f34807d1c0c +keywords: [".beep (Speaker Beep) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .beep (Speaker Beep) +api_type: +- NA +--- + +# .beep (Speaker Beep) + + +The **.beep** command makes noise on the computer speaker. + +``` + .beep +``` + +### Environment + +This command cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.beep%20%28Speaker%20Beep%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bitcount.md b/windows-driver-docs-pr/debugger/-bitcount.md new file mode 100644 index 0000000000..4efd5e0c4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bitcount.md @@ -0,0 +1,69 @@ +--- +title: bitcount +description: The !bitcount extension counts the number of "1" bits in a memory range. +ms.assetid: dacf3d63-6241-4779-afca-514905b37e26 +keywords: ["bitcount Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bitcount +api_type: +- NA +--- + +# !bitcount + + +The **!bitcount** extension counts the number of "1" bits in a memory range. + +``` +!bitcount StartAddress TotalBits +``` + +## Parameters + + + *StartAddress* +Specifies the starting address of the memory range whose "1" bits will be counted. + + *TotalBits* +Specifies the size of the memory range, in bits. + + **-?** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bitcount%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-block.md b/windows-driver-docs-pr/debugger/-block.md new file mode 100644 index 0000000000..b3b735947c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-block.md @@ -0,0 +1,52 @@ +--- +title: .block +description: The .block token performs no action; it is used solely to introduce a block of statements. +ms.assetid: 8f1ac6b5-fea5-4e3f-8d4c-5e0533722885 +keywords: [".block Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .block +api_type: +- NA +--- + +# .block + + +The **.block** token performs no action; it is used solely to introduce a block of statements. + +``` + Commands ; .block { Commands } ; Commands +``` + +## + + +### Additional Information + +For information about using a new block to evaluate an alias, see [Using Aliases](using-aliases.md) and [**as, aS (Set Alias)**](as--as--set-alias-.md). + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +Blocks of commands are surrounded by braces. When each block is entered, all aliases within the block are evaluated. If you alter the value of an alias at some point within a command block, commands subsequent to that point will not use the new alias value unless they are within a subordinate block. + +Each block must begin with a control flow token. If you wish to create a block for the sole purpose of evaluating aliases, you should prefix it with the **.block** token, since this token has no effect other than to allow a block to be introduced. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.block%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-blockeddrv.md b/windows-driver-docs-pr/debugger/-blockeddrv.md new file mode 100644 index 0000000000..876acb5541 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-blockeddrv.md @@ -0,0 +1,77 @@ +--- +title: blockeddrv +description: The blockeddrv extension displays the list of blocked drivers on the target computer. +ms.assetid: 38331ff6-1957-4b28-90c0-10b2c77339fb +keywords: ["blocked drivers", "blockeddrv Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- blockeddrv +api_type: +- NA +--- + +# !blockeddrv + + +The **!blockeddrv** extension displays the list of blocked drivers on the target computer. + +``` + !blockeddrv +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example: + +``` +kd> !blockeddrv +Driver: Status GUID +afd.sys 0: {00000008-0206-0001-0000-000030C964E1} +agp440.sys 0: {0000005C-175A-E12D-5000-010020885580} +atapi.sys 0: {0000005C-B04A-E12E-5600-000020885580} +audstub.sys 0: {0000005C-B04A-E12E-5600-000020885580} +Beep.SYS 0: {0000005C-B04A-E12E-5600-000020885580} +Cdfs.SYS 0: {00000008-0206-0001-0000-000008F036E1} +..... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!blockeddrv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bpcmds--display-breakpoint-commands-.md b/windows-driver-docs-pr/debugger/-bpcmds--display-breakpoint-commands-.md new file mode 100644 index 0000000000..e5d811950e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bpcmds--display-breakpoint-commands-.md @@ -0,0 +1,127 @@ +--- +title: .bpcmds (Display Breakpoint Commands) +description: The .bpcmds command displays the commands that were used to set each of the current breakpoints. +ms.assetid: 96c13c54-8d85-414c-9775-a0373459dc7a +keywords: [".bpcmds (Display Breakpoint Commands) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .bpcmds (Display Breakpoint Commands) +api_type: +- NA +--- + +# .bpcmds (Display Breakpoint Commands) + + +The **.bpcmds** command displays the commands that were used to set each of the current breakpoints. + +``` + .bpcmds +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, see [Using Breakpoints](using-breakpoints.md). + +Remarks +------- + +If it is unclear whether a particular breakpoint is set at an address, at a symbolic reference, or at a symbol, use the **.bpcmds** command to shows which breakpoint command was used to create it. The command that was used to create a breakpoint determines its nature: + +- The [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command sets a breakpoint at an address. + +- The [**bu (Set Unresolved Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command sets a breakpoint on a symbolic reference. + +- The [**bm (Set Symbol Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command sets a breakpoint on symbols that match a specified pattern. If the **/d** switch is included, it creates zero or more breakpoints on addresses (like bp), otherwise it creates zero or more breakpoints on symbolic references (like bu). + +- The [**ba (Break on Access)**](ba--break-on-access-.md) command sets a data breakpoint at an address. + +The output of **.bpcmds** reflects the current nature of each breakpoint. Each line of the **.bpcmds** display begins with the command used to create it (**bp**, **bu**, or **ba**) followed by the breakpoint ID, and then the location of the breakpoint. + +If the breakpoint was created by **ba**, the access type and size are displayed as well. + +If the breakpoint was created by **bm** without the **/d** switch, the display indicates the breakpoint type as **bu**, followed by the evaluated symbol enclosed in the **@!""** token (which indicates it is a literal symbol and not a numeric expression or register). If the breakpoint was created by **bm** with the **/d** switch, the display indicates the breakpoint type as **bp**. + +Here is an example: + +``` +0:000> bp notepad!winmain + +0:000> .bpcmds +bp0 0x00000001`00003340 ; + +0:000> bu myprog!winmain +breakpoint 0 redefined + +0:000> .bpcmds +bu0 notepad!winmain; + +0:000> bu myprog!LoadFile + +0:000> bp myprog!LoadFile+10 + +0:000> bm myprog!openf* + 3: 00421200 @!"myprog!openFile" + 4: 00427800 @!"myprog!openFilter" + +0:000> bm /d myprog!closef* + 5: 00421600 @!"myprog!closeFile" + +0:000> ba r2 myprog!LoadFile+2E + +0:000> .bpcmds +bu0 notepad!winmain; +bu1 notepad!LoadFile; +bp2 0x0042cc10 ; +bu3 @!"myprog!openFile"; +bu4 @!"myprog!openFilter"; +bp5 0x00421600 ; +ba6 r2 0x0042cc2e ; +``` + +In this example, notice that the output of **.bpcmds** begins with the relevant command ("bu", "bp", or "ba"), followed by the breakpoint number (with no intervening space). + +Notice that because breakpoint number 0 was originally set using **bp**, and then was redefined using **bu**, the display shows its type as "bu". + +Notice also that breakpoints 3, 4, and 5, which were created by the **bm** commands shown in this example, are displayed as either type "bp" or type "bu", depending on whether the **/d** switch was included when **bm** was used. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.bpcmds%20%28Display%20Breakpoint%20Commands%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bpid.md b/windows-driver-docs-pr/debugger/-bpid.md new file mode 100644 index 0000000000..4b4990af73 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bpid.md @@ -0,0 +1,112 @@ +--- +title: bpid +description: The bpid extension requests that a process on the target computer break into the debugger or requests that a user-mode debugger be attached to a process on the target computer. +ms.assetid: 47091651-3b39-4e3d-86cf-a8e95779a025 +keywords: ["bpid Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bpid +api_type: +- NA +--- + +# !bpid + + +The **!bpid** extension requests that a process on the target computer break into the debugger or requests that a user-mode debugger be attached to a process on the target computer. + +``` + !bpid [Options] PID +``` + +## Parameters + + + *Option* +Controls the additional activities of this command. + +The valid values for *Option* appear in the following table. + + ++++ + + + + + + + + + + + + + + +

-a

Attaches a new user-mode debugger to the process specified by PID. The user-mode debugger runs on the target machine.

-s

Adds a breakpoint that occurs in the WinLogon process immediately before the break in the user-mode process specified by PID. This allows the user to verify the request before attempting the action.

-w

Stores the request in the memory in the target computer. The target system can then repeat the request, but this is not usually necessary.

+ +  + + *PID* +Specifies the process ID of the desired process on the target computer. If you are using this to control a user-mode debugger on the target computer, *PID* should be the process ID of the target application, not of the user-mode debugger. (Because process IDs are usually listed in decimal format, you might need to prefix this with **0n** or convert it to hexadecimal format.) + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command is supported on x86-based, x64-based, and Itanium-based target computers. + +Remarks +------- + +This command is especially useful when redirecting input and output from a user-mode debugger to the kernel debugger. It causes the user-mode target application to break into the user-mode debugger, which in turn requests input from the kernel debugger. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +If this command is used in another situation, the user-mode process calls **DbgBreakPoint**. This will usually break directly into the kernel debugger. + +The **-s** option causes a break in WinLogon just before the break in the specified process occurs. This is useful if you want to perform debugging actions within WinLogon's process context. The [**g (Go)**](g--go-.md) command can then be used to move on to the second break. + +Note that there are ways in which this extension can fail to execute: + +- Lack of resources. The **!bpid** extension injects a thread into the target process, so the system must have enough resources to create a thread. Using the **-a** option requires even more system resources since **!bpid -a** must run a full instance of a debugger on the target computer. + +- The loader lock is already held. Both **!bpid** and **!bpid -a** require a thread to run in the target process in order to make it break into the debugger. If another thread is holding the loader lock, then the **!bpid** thread will not be able to run and a break into the debugger may not occur. Thus, if **!bpid** fails when there is enough user-mode memory available for the target process, it is possible that the loader lock is held. + +- Lack of permission. The operation of the !bpid extension requires permission sufficient for WinLogon to create a remote thread and attach a debugger to a given process. + +- No access to ntsd.exe. If ntsd.exe is not found in a commonly known path, !bpid will fail to set an appropriate PID. Note that ntsd.exe is not included by default with Windows Vista. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bpid%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bpsync--synchronize-threads-at-breakpoint-.md b/windows-driver-docs-pr/debugger/-bpsync--synchronize-threads-at-breakpoint-.md new file mode 100644 index 0000000000..200371af87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bpsync--synchronize-threads-at-breakpoint-.md @@ -0,0 +1,85 @@ +--- +title: .bpsync (Synchronize Threads at Breakpoint) +description: When a thread reaches a breakpoint, the .bpsync command freezes all other threads, until the thread to which the breakpoint applies has stepped through the breakpoint. +ms.assetid: 3e97ea97-77b8-4a22-b49c-c99739b42d59 +keywords: [".bpsync (Synchronize Threads at Breakpoint) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .bpsync (Synchronize Threads at Breakpoint) +api_type: +- NA +--- + +# .bpsync (Synchronize Threads at Breakpoint) + + +When a thread reaches a breakpoint, the **.bpsync** command freezes all other threads, until the thread to which the breakpoint applies has stepped through the breakpoint. + +``` +.bpsync 1 +.bpsync 0 +.bpsync +``` + +## Parameters + + + **1** +Causes all threads to freeze when one thread has reached a breakpoint. After the thread to which the breakpoint applies has stepped through the breakpoint, the other threads are unfrozen. + + **0** +Allows other threads to continue executing when one thread has reached a breakpoint. This is the default behavior. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +With no parameters. the **.bpsync** command displays the current rule governing breakpoint synchronization behavior. + +The **.bpsync** command applies both to software breakpoints (set with [**bp**](bp--bu--bm--set-breakpoint-.md), **bu**, or **bm**) and to processor breakpoints (set with [**ba**](ba--break-on-access-.md)). + +If there is a possibility of multiple threads running through the same code, the **.bpsync 1** command can be useful for capturing all breakpoint occurrences. Without this command, a breakpoint occurrence could be missed because the first thread to reach the breakpoint always causes the debugger to temporarily remove the breakpoint. In the short period when the breakpoint is removed, other threads could reach the same place in the code and not trigger the breakpoint as intended. + +The temporary removal of breakpoints is a normal aspect of debugger operation. When the target reaches a breakpoint and is resumed, the debugger has to remove the breakpoint temporarily so that the target can execute the real code. After the real instruction has been executed, the debugger reinserts the break. To do this, the debugger restores the code (or turns off data breaks), does a single-step, and then puts the break back. + +Note that if you use **.bpsync 1**, there is a risk of deadlocks among the threads that have been frozen. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.bpsync%20%28Synchronize%20Threads%20at%20Breakpoint%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-break3.md b/windows-driver-docs-pr/debugger/-break3.md new file mode 100644 index 0000000000..b105e6e433 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-break3.md @@ -0,0 +1,54 @@ +--- +title: .break +description: The .break token behaves like the break keyword in C. +ms.assetid: 577e74d1-824f-424a-b30e-a82fe2d682f1 +keywords: [".break Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .break +api_type: +- NA +--- + +# .break + + +The **.break** token behaves like the **break** keyword in C. + +``` + .for (...) { ... ; .if (Condition) .break ; ...} + +.while (...) { ... ; .if (Condition) .break ; ...} + +.do { ... ; .if (Condition) .break ; ...} (...) +``` + +## + + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The **.break** token can be used within any [**.for**](-for.md), [**.while**](-while.md), or [**.do**](-do.md) loop. + +Since there is no control flow token equivalent to the C **goto** statement, you will usually use the **.break** token within an [**.if**](-if.md) conditional, as shown in the syntax examples above. However, this is not actually required. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.break%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-breakin--break-to-the-kernel-debugger-.md b/windows-driver-docs-pr/debugger/-breakin--break-to-the-kernel-debugger-.md new file mode 100644 index 0000000000..7790433328 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-breakin--break-to-the-kernel-debugger-.md @@ -0,0 +1,81 @@ +--- +title: .breakin (Break to the Kernel Debugger) +description: The .breakin command switches from user-mode debugging to kernel-mode debugging. This command is particularly useful when you are controlling the user-mode debugger from the kernel debugger. +ms.assetid: f0dab2c2-60f4-4a85-91bd-6379b247ceaf +keywords: [".breakin (Break to the Kernel Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .breakin (Break to the Kernel Debugger) +api_type: +- NA +--- + +# .breakin (Break to the Kernel Debugger) + + +The **.breakin** command switches from user-mode debugging to kernel-mode debugging. This command is particularly useful when you are controlling the user-mode debugger from the kernel debugger. + +``` + .breakin +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +If kernel-mode debugging was enabled during the boot process and you are running a user-mode debugger, you can use the **.breakin** command to halt the operating system and transfer control to a kernel debugger. + +The **.breakin** command causes a kernel-mode break in the debugger's process context. If a kernel debugger is attached, it will become active. The kernel debugger's [process context](changing-contexts.md) will automatically be set to the process of the user-mode debugger, not the user-mode debugger's target process. + +This command is primarily useful when debugging a user-mode problem requires retrieving information about the kernel state of the system. Resuming execution in the kernel debugger is necessary before the user-mode debugging session can continue. + +When you are [controlling the user-mode debugger from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) and the user-mode debugger prompt is visible in the kernel debugger, this command will pause the user-mode debugger and make the kernel-mode debugging prompt appear. + +If the system is unable to break into the kernel debugger, an error message is displayed. + +This command is also useful if you use the kernel debugger to set a breakpoint in user space and that breakpoint is caught by a user-mode debugger instead of the kernel debugger. Issuing this command in the user-mode debugger will transfer control to the kernel debugger. + +If the **.breakin** command is used on a system that was not booted with debugging enabled, it has no effect. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.breakin%20%28Break%20to%20the%20Kernel%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-browse--display-command-in-browser-.md b/windows-driver-docs-pr/debugger/-browse--display-command-in-browser-.md new file mode 100644 index 0000000000..be93bfd5a0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-browse--display-command-in-browser-.md @@ -0,0 +1,51 @@ +--- +title: .browse (Display Command in Browser) +description: The .browse command displays the output of a specified command in a new Command Browser window. +ms.assetid: 37822DDE-8AA8-4DB9-8213-08E73110ACE5 +keywords: [".browse (Display Command in Browser) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .browse (Display Command in Browser) +api_type: +- NA +--- + +# .browse (Display Command in Browser) + + +The **.browse** command displays the output of a specified command in a new [Command Browser window](command-browser-window.md). + +``` +.browse Command +``` + +## Parameters + + +*Command* +The command to be executed and displayed in a new Command Browser window. + +Remarks +------- + +The following example uses the **.browse** command to display the output of the [**.chain /D**](-chain--list-debugger-extensions-.md) command in a Command Browser window. + +``` +.browse .chain /D +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.browse%20%28Display%20Command%20in%20Browser%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-btb.md b/windows-driver-docs-pr/debugger/-btb.md new file mode 100644 index 0000000000..5b065d73b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-btb.md @@ -0,0 +1,63 @@ +--- +title: btb +description: The btb extension displays the Itanium-based processor, branch traces buffer (BTB) configuration and trace registers for the current processor. +ms.assetid: ca09198a-3c3e-4a1b-90be-158d4ecac7c4 +keywords: ["branch tree buffer", "btb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- btb +api_type: +- NA +--- + +# !btb + + +The **!btb** extension displays the Itanium-based processor, branch traces buffer (BTB) configuration and trace registers for the current processor. + +``` +!btb +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!btb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bth.md b/windows-driver-docs-pr/debugger/-bth.md new file mode 100644 index 0000000000..5f38773ada --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bth.md @@ -0,0 +1,69 @@ +--- +title: bth +description: The bth extension displays the Itanium-based branch traces history for the specified processor. +ms.assetid: e6bf1452-adb7-4b1d-8614-03fcf0306c70 +keywords: ["branch trace history", "bth Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bth +api_type: +- NA +--- + +# !bth + + +The **!bth** extension displays the Itanium-based branch traces history for the specified processor. + +``` +!bth [Processor] +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Processor* +Specifies a processor. If *Processor* is omitted, then the branch trace history for all of processors is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bth%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthdevinfo.md b/windows-driver-docs-pr/debugger/-bthkd-bthdevinfo.md new file mode 100644 index 0000000000..cd17efc488 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthdevinfo.md @@ -0,0 +1,53 @@ +--- +title: bthkd.bthdevinfo +description: The bthkd.bthdevinfo command displays the information about a given BTHENUM created device PDO. +ms.assetid: 2FFC6E17-F257-4EE3-B5F0-F81684E9B290 +keywords: ["bthkd.bthdevinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthdevinfo +api_type: +- NA +--- + +# !bthkd.bthdevinfo + + +The **!bthkd.bthdevinfo** command displays the information about a given BTHENUM created device PDO. + +``` +!bthkd.bthdevinfo addr +``` + +## Parameters + + + *addr* +The address of a BTHENUM created device PDO extension. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthdevinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthenuminfo.md b/windows-driver-docs-pr/debugger/-bthkd-bthenuminfo.md new file mode 100644 index 0000000000..33bead14a9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthenuminfo.md @@ -0,0 +1,47 @@ +--- +title: bthkd.bthenuminfo +description: The bthkd.bthenuminfo command displays information about the BTHENUM FDO. +ms.assetid: 6280EA4C-1A1B-477C-AB6C-EB53177FA88E +keywords: ["bthkd.bthenuminfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthenuminfo +api_type: +- NA +--- + +# !bthkd.bthenuminfo + + +The **!bthkd.bthenuminfo** command displays information about the BTHENUM FDO. + +``` +!bthkd.bthenuminfo +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthenuminfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthhelp.md b/windows-driver-docs-pr/debugger/-bthkd-bthhelp.md new file mode 100644 index 0000000000..f43187f5cf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthhelp.md @@ -0,0 +1,47 @@ +--- +title: bthkd.bthhelp +description: The bthkd.bthhelp command displays help for the Bluetooth debug extension commands. +ms.assetid: 6D1BE829-16F5-45D4-A0AA-4CFBDA019840 +keywords: ["bthkd.bthhelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthhelp +api_type: +- NA +--- + +# !bthkd.bthhelp + + +The **!bthkd.bthhelp** command displays help for the Bluetooth debug extension commands. + +``` +!bthkd.bthhelp +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthhelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthinfo-.md b/windows-driver-docs-pr/debugger/-bthkd-bthinfo-.md new file mode 100644 index 0000000000..401317e03f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthinfo-.md @@ -0,0 +1,47 @@ +--- +title: bthkd.bthinfo +description: The bthkd.bthinfo command displays details about the BTHPORT FDO. This command is a good starting point for Bluetooth investigations. +ms.assetid: 6D0294FA-8A37-4590-A3B0-83E6950D0950 +keywords: ["bthkd.bthinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthinfo +api_type: +- NA +--- + +# !bthkd.bthinfo + + +The **!bthkd.bthinfo** command displays details about the BTHPORT FDO. This command is a good starting point for Bluetooth investigations as it displays address information that can be used to access many of the other Bluetooth debug extension commands. + +``` +!bthkd.bthinfo +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthinfo%20%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthtree.md b/windows-driver-docs-pr/debugger/-bthkd-bthtree.md new file mode 100644 index 0000000000..ef46823187 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthtree.md @@ -0,0 +1,47 @@ +--- +title: bthkd.bthtree +description: The bthkd.bthtree command displays the complete Bluetooth device tree. +ms.assetid: A51F4747-0013-4483-92B2-D14B3917CC72 +keywords: ["bthkd.bthtree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthtree +api_type: +- NA +--- + +# !bthkd.bthtree + + +The **!bthkd.bthtree** command displays the complete Bluetooth device tree. + +``` +!bthkd.bthtree +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthtree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-bthusbtransfer.md b/windows-driver-docs-pr/debugger/-bthkd-bthusbtransfer.md new file mode 100644 index 0000000000..1f05894c15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-bthusbtransfer.md @@ -0,0 +1,58 @@ +--- +title: bthkd.bthusbtransfer +description: The bthkd.bthusbtransfer command displays the Bluetooth usb transfer context including Irp, Bip and transfer buffer information. +ms.assetid: 61323238-E741-4291-A03C-F4060820D384 +keywords: ["bthkd.bthusbtransfer Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.bthusbtransfer +api_type: +- NA +--- + +# !bthkd.bthusbtransfer + + +The **!bthkd.bthusbtransfer** command displays the Bluetooth usb transfer context including Irp, Bip and transfer buffer information. + +``` +!bthkd.bthusbtransfer addr +``` + +## Parameters + + + *addr* +Address of the Bluetooth USB transfer context. + +## Remarks + + +You can use the !bthinfo command to display the address of USB transfer context. It is listed under the transfer list section. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.bthusbtransfer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-dibflags.md b/windows-driver-docs-pr/debugger/-bthkd-dibflags.md new file mode 100644 index 0000000000..2c764764f8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-dibflags.md @@ -0,0 +1,53 @@ +--- +title: bthkd.dibflags +description: The bthkd.dibflags command displays DEVICE_INFO_BLOCK.DibFlags dumps flags set in _DEVICE_INFO_BLOCK.DibFlags. +ms.assetid: 767E6ECB-5B7E-4A63-8503-733CBD7E2E6A +keywords: ["bthkd.dibflags Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.dibflags +api_type: +- NA +--- + +# !bthkd.dibflags + + +The **!bthkd.dibflags** command displays DEVICE\_INFO\_BLOCK.DibFlags dumps flags set in \_DEVICE\_INFO\_BLOCK.DibFlags. + +``` +!bthkd.dibflags flags +``` + +## Parameters + + + *flags* +The value of \_DEVICE\_INFO\_BLOCK.DibFlags Dumps Flags set in \_DEVICE\_INFO\_BLOCK.DibFlags. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.dibflags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-hcicmd.md b/windows-driver-docs-pr/debugger/-bthkd-hcicmd.md new file mode 100644 index 0000000000..80f2260f7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-hcicmd.md @@ -0,0 +1,47 @@ +--- +title: bthkd.hcicmd +description: The bthkd.hcicmd command displays a list of the currently pending commands. +ms.assetid: 40958642-0EAE-40A2-BFA1-60C2EB4BFC7B +keywords: ["bthkd.hcicmd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.hcicmd +api_type: +- NA +--- + +# !bthkd.hcicmd + + +The **!bthkd.hcicmd** command displays a list of the currently pending commands. + +``` +!bthkd.hcicmd +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.hcicmd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-hciinterface.md b/windows-driver-docs-pr/debugger/-bthkd-hciinterface.md new file mode 100644 index 0000000000..41c582a79f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-hciinterface.md @@ -0,0 +1,47 @@ +--- +title: bthkd.hciinterface +description: The bthkd.hciinterface command displays the bthport _HCI_INTERFACE structure. +ms.assetid: C91AF3CE-CDB8-491A-A486-8836C8EBB9A3 +keywords: ["bthkd.hciinterface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.hciinterface +api_type: +- NA +--- + +# !bthkd.hciinterface + + +The **!bthkd.hciinterface** command displays the bthport!\_HCI\_INTERFACE structure. + +``` +!bthkd.hciinterface +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.hciinterface%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-l2capinterface-.md b/windows-driver-docs-pr/debugger/-bthkd-l2capinterface-.md new file mode 100644 index 0000000000..5ae805c6a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-l2capinterface-.md @@ -0,0 +1,47 @@ +--- +title: bthkd.l2capinterface +description: The bthkd.l2capinterface command displays information about the L2CAP interface. +ms.assetid: 8290A422-04DD-427B-B816-85DD27F845C8 +keywords: ["bthkd.l2capinterface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.l2capinterface +api_type: +- NA +--- + +# !bthkd.l2capinterface + + +The **!bthkd.l2capinterface** command displays information about the L2CAP interface. + +``` +!bthkd.l2capinterface +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.l2capinterface%20%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-rfcommchannel.md b/windows-driver-docs-pr/debugger/-bthkd-rfcommchannel.md new file mode 100644 index 0000000000..cedc0e5d15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-rfcommchannel.md @@ -0,0 +1,53 @@ +--- +title: bthkd.rfcommchannel +description: The bthkd.rfcommchannel command displays information about a given RFCOMM channel CB. +ms.assetid: FAA0BABB-E479-47CD-85AC-5A710FFCDE89 +keywords: ["bthkd.rfcommchannel Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.rfcommchannel +api_type: +- NA +--- + +# !bthkd.rfcommchannel + + +The **!bthkd.rfcommchannel** command displays information about a given RFCOMM channel CB. + +``` +!bthkd.rfcommchannel addr +``` + +## Parameters + + + *addr* +The address of a rfcomm!\_CHANNEL\_CB structure. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.rfcommchannel%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-rfcommconnection.md b/windows-driver-docs-pr/debugger/-bthkd-rfcommconnection.md new file mode 100644 index 0000000000..b8759c68fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-rfcommconnection.md @@ -0,0 +1,53 @@ +--- +title: bthkd.rfcommconnection +description: The bthkd.rfcommconnection command displays information about a given RFCOMM connection object. +ms.assetid: 0F56B937-BE56-4B45-B30F-F6D1BAB8FCCB +keywords: ["bthkd.rfcommconnection Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.rfcommconnection +api_type: +- NA +--- + +# !bthkd.rfcommconnection + + +The **!bthkd.rfcommconnection** command displays information about a given RFCOMM connection object. + +``` +!bthkd.rfcommconnection addr +``` + +## Parameters + + + *addr* +The address of a rfcomm!\_RFCOMM\_CONN\_OBJ structure. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.rfcommconnection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-rfcomminfo.md b/windows-driver-docs-pr/debugger/-bthkd-rfcomminfo.md new file mode 100644 index 0000000000..5215ef364a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-rfcomminfo.md @@ -0,0 +1,47 @@ +--- +title: bthkd.rfcomminfo +description: The bthkd.rfcomminfo command displays information about the RFCOMM FDO and the TDI Device Object. +ms.assetid: 3C9237AD-7683-4486-95FA-E95AEC68F6C8 +keywords: ["bthkd.rfcomminfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.rfcomminfo +api_type: +- NA +--- + +# !bthkd.rfcomminfo + + +The **!bthkd.rfcomminfo** command displays information about the RFCOMM FDO and the TDI Device Object. + +``` +!bthkd.rfcomminfo +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.rfcomminfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-scointerface-.md b/windows-driver-docs-pr/debugger/-bthkd-scointerface-.md new file mode 100644 index 0000000000..21645377ca --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-scointerface-.md @@ -0,0 +1,47 @@ +--- +title: bthkd.scointerface +description: The bthkd.scointerface command displays information about the SCO interface. +ms.assetid: FF689CCB-E3AB-4A4B-A77A-91FB69987C06 +keywords: ["bthkd.scointerface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.scointerface +api_type: +- NA +--- + +# !bthkd.scointerface + + +The **!bthkd.scointerface** command displays information about the SCO interface. + +``` +!bthkd.scointerface +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.scointerface%20%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-sdpinterface.md b/windows-driver-docs-pr/debugger/-bthkd-sdpinterface.md new file mode 100644 index 0000000000..fb6b037ef3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-sdpinterface.md @@ -0,0 +1,47 @@ +--- +title: bthkd.sdpinterface +description: The bthkd.sdpinterface command displays information about the SDP interface. +ms.assetid: 931A7785-2E0C-426B-A8CC-84F507438B0D +keywords: ["bthkd.sdpinterface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.sdpinterface +api_type: +- NA +--- + +# !bthkd.sdpinterface + + +The **!bthkd.sdpinterface** command displays information about the SDP interface. + +``` +!bthkd.sdpinterface +``` + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.sdpinterface%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-sdpnode.md b/windows-driver-docs-pr/debugger/-bthkd-sdpnode.md new file mode 100644 index 0000000000..5e55de1d9a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-sdpnode.md @@ -0,0 +1,60 @@ +--- +title: bthkd.sdpnode +description: The bthkd.sdpnode command displays information about a node in an sdp tree. +ms.assetid: 3B5D1903-53C0-4FF5-8542-E419E555AFC1 +keywords: ["bthkd.sdpnode Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.sdpnode +api_type: +- NA +--- + +# !bthkd.sdpnode + + +The **!bthkd.sdpnode** command displays information about a node in an sdp tree. + +``` +!bthkd.sdpnode addr [flags] +``` + +## Parameters + + + *addr* +Address of the sdp tree node to display. + + *flags* +0x1 - Recurse node + +0x2 - Verbose + +default is 0x0 + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.sdpnode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bthkd-sdpstream.md b/windows-driver-docs-pr/debugger/-bthkd-sdpstream.md new file mode 100644 index 0000000000..46171cb861 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bthkd-sdpstream.md @@ -0,0 +1,56 @@ +--- +title: bthkd.sdpstream +description: The bthkd.sdpstream command displays the contents of a SDP stream. +ms.assetid: 238A10D2-1DAB-4826-AE60-1FD69B0ABABC +keywords: ["bthkd.sdpstream Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bthkd.sdpstream +api_type: +- NA +--- + +# !bthkd.sdpstream + + +The **!bthkd.sdpstream** command displays the contents of a SDP stream. + +``` +!bthkd.sdpstream streamaddr streamlength +``` + +## Parameters + + + *streamaddr* +A pointer to beginning of stream. + + *streamlength* +The length of SDP stream in bytes to display. + +## DLL + + +Bthkd.dll + +## See also + + +[Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bthkd.sdpstream%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-bugcheck--display-bug-check-data-.md b/windows-driver-docs-pr/debugger/-bugcheck--display-bug-check-data-.md new file mode 100644 index 0000000000..0999d7e3e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bugcheck--display-bug-check-data-.md @@ -0,0 +1,77 @@ +--- +title: .bugcheck (Display Bug Check Data) +description: The .bugcheck command displays the data from a bug check on the target computer. +ms.assetid: 4b453b5a-4a3c-4056-92e7-b6a17f987fa4 +keywords: [".bugcheck (Display Bug Check Data) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .bugcheck (Display Bug Check Data) +api_type: +- NA +--- + +# .bugcheck (Display Bug Check Data) + + +The **.bugcheck** command displays the data from a bug check on the target computer. + +``` + .bugcheck +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about bug checks, see [Bug Checks (Blue Screens)](bug-checks--blue-screens-.md). For a description of individual bug checks, see the [Bug Check Code Reference](bug-check-code-reference2.md) section. + +Remarks +------- + +This command displays the current bug check data. (This bug check data will be accessible until the crashed machine is rebooted.) + +You can also display bug check data on 32-bit systems by using **dd NT!KiBugCheckData L5**, or on 64-bit systems by using **dq NT!KiBugCheckData L5**. However, the .bugcheck command is more reliable, because it works in some scenarios that the [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command will not (such as user-mode minidumps). + +The [**!analyze**](-analyze.md) extension command is also useful after a bug check occurs. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.bugcheck%20%28Display%20Bug%20Check%20Data%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bugdump.md b/windows-driver-docs-pr/debugger/-bugdump.md new file mode 100644 index 0000000000..1e48cf4c62 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bugdump.md @@ -0,0 +1,78 @@ +--- +title: bugdump +description: The bugdump extension formats and displays the information contained in the bug check callback buffers. +ms.assetid: cbea92de-e45b-416c-87f1-6faba95788d0 +keywords: ["bugdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bugdump +api_type: +- NA +--- + +# !bugdump + + +The **!bugdump** extension formats and displays the information contained in the bug check callback buffers. + +``` + !bugdump [Component] +``` + +## Parameters + + + *Component* +Specifies the component whose callback data is to be examined. If omitted, all bug check callback data is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For more information, see [Reading Bug Check Callback Data](reading-bug-check-callback-data.md). + +Remarks +------- + +This extension can only be used after a bug check has occurred, or when you are debugging a kernel-mode crash dump file. + +The *Component* parameter corresponds to the final parameter used in [**KeRegisterBugCheckCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553105). + +The buffers that hold callback data are not available in a Small Memory Dump. These buffers are present in Kernel Memory Dumps and Full Memory Dumps. However, in Windows XP SP1, Windows Server 2003, and later versions of Windows, the dump file is created before the drivers' **BugCheckCallback** routines are called, and therefore these buffers will not contain the data written by these routines. + +If you are performing live debugging of a crashed system, all callback data will be present. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bugdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-bushnd.md b/windows-driver-docs-pr/debugger/-bushnd.md new file mode 100644 index 0000000000..155db85fc9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-bushnd.md @@ -0,0 +1,63 @@ +--- +title: bushnd +description: The bushnd extension displays a HAL BUS_HANDLER structure. +ms.assetid: dd2cb9c1-9abe-4209-a4fa-dc50965e807e +keywords: ["bushnd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bushnd +api_type: +- NA +--- + +# !bushnd + + +The **!bushnd** extension displays a HAL BUS\_HANDLER structure. + +``` + !bushnd [Address] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the HAL BUS\_HANDLER structure. If omitted, **!bushnd** displays a list of buses and the base address of the handler. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!bushnd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ca.md b/windows-driver-docs-pr/debugger/-ca.md new file mode 100644 index 0000000000..dd63f2d980 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ca.md @@ -0,0 +1,201 @@ +--- +title: ca +description: The ca extension displays information about a control area. +ms.assetid: 7e9164a5-238e-4327-bd2a-a814bff5f7db +keywords: ["control area", "ca Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ca +api_type: +- NA +--- + +# !ca + + +The **!ca** extension displays information about a control area. + +``` +!ca [Address | 0 | -1] [Flags] +``` + +## Parameters + + + *Address* +Address of the control area. If you specify 0 for this parameter, information is displayed about all control areas. If you specify -1 for this parameter, information is displayed about the unused segment list. + + *Flags* +Flags that specify which information is displayed. This parameter is a bitwise OR of one or more of the following flags. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription

0x1

Display segment information.

0x2

Display subsection information.

0x4

Display the list of mapped views. (Windows 7 and later)

0x8

Display compact (single line) output.

0x10

Display file-backed control areas.

0x20

Display control areas backed by the page file.

0x40

Display image control areas.

+ +  + +If none of the last three flags are specified, all three types of control area are displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about control areas, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +To get a list of the control areas of all mapped files, use the [**!memusage**](-memusage.md) extension. + +Here is an example: + +``` +kd> !memusage + loading PFN database +loading (99% complete) + Zeroed: 16 ( 64 kb) + Free: 0 ( 0 kb) + Standby: 2642 ( 10568 kb) + Modified: 720 ( 2880 kb) + ModifiedNoWrite: 0 ( 0 kb) + Active/Valid: 13005 ( 52020 kb) + Transition: 0 ( 0 kb) + Unknown: 0 ( 0 kb) + TOTAL: 16383 ( 65532 kb) + Building kernel map + Finished building kernel map + + Usage Summary (in Kb): +Control Valid Standby Dirty Shared Locked PageTables name +ff8636e8 56 376 0 0 0 0 mapped_file( browseui.dll ) +ff8cf388 24 0 0 0 0 0 mapped_file( AVH32DLL.DLL ) +ff8d62c8 12 0 0 0 0 0 mapped_file( PSAPI.DLL ) +ff8dd468 156 28 0 0 0 0 mapped_file( INOJOBSV.EXE ) +fe424808 136 88 0 52 0 0 mapped_file( oleaut32.dll ) +fe4228a8 152 44 0 116 0 0 mapped_file( MSVCRT.DLL ) +ff8ec848 4 0 0 0 0 0 No Name for File +ff859de8 0 32 0 0 0 0 mapped_file( timedate.cpl ) +. . . . . + +kd> !ca ff8636e8 + +ControlArea @ff8636e8 + Segment: e1b74548 Flink 0 Blink: 0 + Section Ref 0 Pfn Ref 6c Mapped Views: 1 + User Ref 1 Subsections 5 Flush Count: 0 + File Object ff86df88 ModWriteCount 0 System Views: 0 + WaitForDel 0 Paged Usage 380 NonPaged Usage e0 + Flags (10000a0) Image File HadUserReference + + File: \WINNT\System32\browseui.dll + +Segment @ e1b74548: + Base address 0 Total Ptes c8 NonExtendPtes: c8 + Image commit 1 ControlArea ff8636e8 SizeOfSegment: c8000 + Image Base 0 Committed 0 PTE Template: 31b8438 + Based Addr 76e10000 ProtoPtes e1b74580 Image Info: e1b748a4 + +Subsection 1. @ ff863720 + ControlArea: ff8636e8 Starting Sector 0 Number Of Sectors 2 + Base Pte e1b74580 Ptes In subsect 1 Unused Ptes 0 + Flags 15 Sector Offset 0 Protection 1 + ReadOnly CopyOnWrite + +Subsection 2. @ ff863740 + ControlArea: ff8636e8 Starting Sector 2 Number Of Sectors 3d0 + Base Pte e1b74584 Ptes In subsect 7a Unused Ptes 0 + Flags 35 Sector Offset 0 Protection 3 + ReadOnly CopyOnWrite + +Subsection 3. @ ff863760 + ControlArea: ff8636e8 Starting Sector 3D2 Number Of Sectors 7 + Base Pte e1b7476c Ptes In subsect 1 Unused Ptes 0 + Flags 55 Sector Offset 0 Protection 5 + ReadOnly CopyOnWrite + +Subsection 4. @ ff863780 + ControlArea: ff8636e8 Starting Sector 3D9 Number Of Sectors 21f + Base Pte e1b74770 Ptes In subsect 44 Unused Ptes 0 + Flags 15 Sector Offset 0 Protection 1 + ReadOnly CopyOnWrite + +Subsection 5. @ ff8637a0 + ControlArea: ff8636e8 Starting Sector 5F8 Number Of Sectors 3a + Base Pte e1b74880 Ptes In subsect 8 Unused Ptes 0 + Flags 15 Sector Offset 0 Protection 1 + ReadOnly CopyOnWrite +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ca%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cache--set-cache-size-.md b/windows-driver-docs-pr/debugger/-cache--set-cache-size-.md new file mode 100644 index 0000000000..d9857be30d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cache--set-cache-size-.md @@ -0,0 +1,113 @@ +--- +title: .cache (Set Cache Size) +description: The .cache command sets the size of the cache used to hold data obtained from the target. Also sets a number of cache and memory options. +ms.assetid: 638cb2e6-b333-4311-967c-d86c2e93b4ec +keywords: [".cache (Set Cache Size) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .cache (Set Cache Size) +api_type: +- NA +--- + +# .cache (Set Cache Size) + + +The **.cache** command sets the size of the cache used to hold data obtained from the target. Also sets a number of cache and memory options. + +``` +.cache Size +.cache Option +.cache +``` + +## Parameters + + + *Size* +The size of the kernel debugging cache, in kilobytes. If *Size* is zero, the cache is disabled. The command output displays the cache size in bytes. (The default size is 1000 KB.) + + *Option* +Can be any one of the following options: + +**hold** +Automatic cache flushing is disabled. + +**unhold** +Turns off the **hold** option. (This is the default setting.) + +**decodeptes** +All transition page table entries (PTEs) will be implicitly decoded. (This is the default setting.) + +**nodecodeptes** +Turns off the **decodeptes** option. + +**forcedecodeptes** +All virtual addresses will be translated into physical addresses before access. This option also causes the cache to be disabled. Unless you are concerned with kernel-mode memory, it is more efficient to use **forcedecodeuser** instead. + +**forcedecodeuser** +All user-mode virtual addresses will be translated into physical addresses before access. This option also causes the cache to be disabled. + +**Note**   You must activate **forcedecodeuser** (or **forcedecodeptes**) before using [**.thread (Set Register Context)**](-thread--set-register-context-.md), [**.context (Set User-Mode Address Context)**](-context--set-user-mode-address-context-.md), [**.process (Set Process Context)**](-process--set-process-context-.md), or [**!session**](-session.md) during live debugging. If you use the **/p** option with **.thread** and **.process**, the **forcedecodeuser** option is automatically set. In any other case, you will need to use the **.cache forcedecodeuser** command explicitly. + +  + +**noforcedecodeptes** +Turns off the **forcedecodeptes** and **forcedecodeuser** options. (This is the default setting.) + +**flushall** +Deletes the entire virtual memory cache. + +**flushu** +Deletes all entries of ranges with errors from the cache, as well as all user-mode entries. + +**flush** *Address* +Deletes a 4096-byte block of the cache, beginning at *Address*. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +If **.cache** is used with no arguments, the current cache size, status, and options are displayed. + +The **.cache forcedecodeuser** or **.cache forcedecodeptes** option will only last as long as the debugger remains broken into the target computer. If any stepping or execution of the target takes place, the **noforcedecodeptes** state will again take effect. This prevents the debugger from interfering with execution or a reboot in an unproductive manner. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.cache%20%28Set%20Cache%20Size%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-call--call-function-.md b/windows-driver-docs-pr/debugger/-call--call-function-.md new file mode 100644 index 0000000000..fbf4365b5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-call--call-function-.md @@ -0,0 +1,114 @@ +--- +title: .call (Call Function) +description: The .call command causes the target process to execute a function. +ms.assetid: 93265c2a-ea4d-4523-928c-1bb75a9356b1 +keywords: [".call (Call Function) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .call (Call Function) +api_type: +- NA +--- + +# .call (Call Function) + + +The **.call** command causes the target process to execute a function. + +``` +.call [/v] Function( Arguments ) +.call /s Prototype Function( Arguments ) +.call /c +.call /C +``` + +## Parameters + + + **/v** +Verbose information about the call and its arguments is displayed. + + **/s** *Prototype* +Allows you to call the function that is specified by *Function* even though you do not have the correct symbols. In this case, you must have symbols for another function that has the same calling prototype as the function you are trying to call. The *Prototype* parameter is the name of this prototype function. + + *Function* +Specifies the function being called. This can be the name of the function (preferably qualified with a module name), or any other expression that evaluates to the function address. If you need to call a constructor or destructor, you must supply the address -- or else use a C++ expression to evaluate named syntax for the operators (see [Numerical Expression Syntax](numerical-expression-syntax.md) for details). + + *Arguments* +Specifies the arguments passed to the function. If you are calling a method, the first argument must be **this**, and all other arguments follow it. Arguments should be separated with commas and should match the usual argument syntax. Variable-length argument lists are supported. Expressions within an argument are parsed by the C++ expression evaluator; see [C++ Numbers and Operators](c---numbers-and-operators.md) for details. You cannot enter a literal string as an argument, but you can use a pointer to a string, or any other memory accessible to the target process. + + **/c** +Clears any existing call on the current thread. + + **/C** +Clears any existing call on the current thread, and resets the context of the current thread to the context stored by the outstanding call. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

x86 and x64 only

+ +  + +Remarks +------- + +The specified function is called by the current thread of the current process. + +Only the **cdecl**, **stdcall**, **fastcall**, and **thiscall** calling conventions are supported. Managed code cannot be called by this command. + +After **.call** is used, the debugger will update the stack, change the instruction pointer to point to the beginning of the called function, and then stop. Use [**g (Go)**](g--go-.md) to resume execution, or **~. g** to execute just the thread making the call. + +When the function returns, a break occurs and the debugger displays the return value of the function. The return value is also stored in the **$callret** pseudo-register, which acquires the type of the return value. + +If you have broken into the target using CTRL+C or CTRL+BREAK, the current thread is an additional thread created to handle the breakin. If you issue a **.call** command at this point, the extra thread will be used for the called function. + +If you have reached a predefined breakpoint, there is no extra breakin thread. If you use **.call** while at a breakpoint in user mode, you could use [**g**](g--go-.md) to execute the entire process, or **~. g** to execute just the current thread. Using **g** may distort your program's behavior, since you have taken one thread and diverted it to this new function. On the other hand, this thread will still have its locks and other attributes, and thus **~. g** may risk deadlocks. + +The safest way to use **.call** is to set a breakpoint in your code at a location where a certain function could be safely called. When that breakpoint is hit, you can use **.call** if you desire that function to run. If you use **.call** at a point where this function could not normally be called, a deadlock or target corruption could result. + +It may be useful to add extra functions to your source code that are not called by the existing code, but are intended to be called by the debugger. For example, you could add functions that are used to investigate the current state of your code and its environment and store information about the state in a known memory location. Be sure not to optimize your code, or these functions may be removed by the compiler. Use this technique only as a last resort, because if your application crashes **.call** will not be available when debugging the dump file. + +The **.call /c** and **.call /C** commands should only be used if an attempt to use **.call** has failed, or if you changed your mind before entering the [**g**](g--go-.md) command. These should not be used casually, since abandoning an uncompleted call can lead to a corrupted target state. + +The following code example shows how the **.call /s** command is used. + +``` +.call /s KnownFunction UnknownFunction( 1 ) +``` + +In this example, you have private symbols for **KnownFunction**, which takes an integer as its only argument and returns, for example, a pointer to an array. You do not have symbols, or possibly you only have public symbols for **UnknownFunction**, but you do know that it takes an integer as its only argument and returns a pointer to an array. By using the **/s** option, you can specify that **UnknownFunction** will work the same way that **KnownFunction** does. Thus, you can successfully generate a call to **UnknownFunction**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.call%20%28Call%20Function%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-callback.md b/windows-driver-docs-pr/debugger/-callback.md new file mode 100644 index 0000000000..3aee9235c6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-callback.md @@ -0,0 +1,77 @@ +--- +title: callback +description: The callback extension displays the callback data related to the trap for the specified thread. +ms.assetid: afbd7884-d63d-4e37-a437-91bc910a3ae2 +keywords: ["callback data for system traps", "callback Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- callback +api_type: +- NA +--- + +# !callback + + +The **!callback** extension displays the callback data related to the trap for the specified thread. + +``` +!callback Address [Number] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the thread. If this is -1 or omitted, the current thread is used. + + *Number* +Specifies the number of the desired callback frame. This frame is noted in the display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +### Additional Information + +For information about system traps, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +If the system has not experienced a system trap, this extension will not produce useful data. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!callback%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-calldata.md b/windows-driver-docs-pr/debugger/-calldata.md new file mode 100644 index 0000000000..a580b5cf00 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-calldata.md @@ -0,0 +1,63 @@ +--- +title: calldata +description: The calldata extension displays performance information in the form of procedure call statistics from the named table. +ms.assetid: 50f63fd3-a0fa-44f0-a7aa-752ae098f4e8 +keywords: ["calldata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- calldata +api_type: +- NA +--- + +# !calldata + + +The **!calldata** extension displays performance information in the form of procedure call statistics from the named table. + +``` + !calldata Table +``` + +## Parameters + + + *Table* +Name of the table that collects the call data. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!calldata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-can-write-kdump.md b/windows-driver-docs-pr/debugger/-can-write-kdump.md new file mode 100644 index 0000000000..a2ac5f77a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-can-write-kdump.md @@ -0,0 +1,91 @@ +--- +title: can_write_kdump +description: The can_write_kdump extension verifies that there is enough disk space on the target computer to write a kernel dump file of the specified type. +ms.assetid: e9fdf8a4-3294-4625-a854-5e42a69374a6 +keywords: ["kernel dump", "can_write_kdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- can_write_kdump +api_type: +- NA +--- + +# !can\_write\_kdump + + +The **!can\_write\_kdump** extension verifies that there is enough disk space on the target computer to write a kernel dump file of the specified type. + +``` +!can_write_kdump [-dn] [Options] +``` + +## Parameters + + + **-dn** +Specifies that the file system on the target computer is an NTFS file system. If this parameter is omitted, then the amount of disk free space cannot be determined, and a warning will be shown. However, the amount of space required will still be displayed. + + *Options* +The following options are valid: + +**-t** +Specifies that the extension should determine if there is enough space for a minidump. + +**-s** +Specifies that the extension should determine if there is enough space for a summary kernel dump. This is the default value. + +**-f** +Specifies that the extension should determine if there is enough space for a full kernel dump. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kext.dll

Windows XP and later

Kext.dll

+ +  + +Remarks +------- + +If no *Option* is specified, then the extension will determine if there is enough space for a summary kernel dump. + +In the following example, the file system is not specified: + +``` +kd> !can_write_kdump +Checking kernel summary dump... +WARNING: Can't predict how many pages will be used, assuming worst-case. +Physical memory: 285560 KB +Page file size: 1572864 KB +NO: Page file too small +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!can_write_kdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-catch.md b/windows-driver-docs-pr/debugger/-catch.md new file mode 100644 index 0000000000..1ba826bc6e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-catch.md @@ -0,0 +1,56 @@ +--- +title: .catch +description: The .catch token is used to prevent a program from terminating if an error occurs.It does not behave like the catch keyword in C++. +ms.assetid: cda195d8-c0b8-4fb2-99a8-e2e8d338482b +keywords: [".catch Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .catch +api_type: +- NA +--- + +# .catch + + +The **.catch** token is used to prevent a program from terminating if an error occurs. + +It does not behave like the **catch** keyword in C++. + +``` + Commands ; .catch { Commands } ; Commands +``` + +## + + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The **.catch** token is followed by braces enclosing one or more commands. + +If a command within a **.catch** block generates an error, the error message is displayed, all remaining commands within the braces are ignored, and execution resumes with the first command after the closing brace. + +If **.catch** is not used, an error will terminate the entire debugger command program. + +You can use [**.leave**](-leave.md) to exit from a **.catch** block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.catch%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cbreg.md b/windows-driver-docs-pr/debugger/-cbreg.md new file mode 100644 index 0000000000..5c6ab83383 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cbreg.md @@ -0,0 +1,74 @@ +--- +title: cbreg +description: The cbreg extension displays CardBus Socket registers and CardBus Exchangable Card Architecture (ExCA) registers. +ms.assetid: 7943e152-b1c9-464c-a0ad-3beac48884d2 +keywords: ["CardBus", "ExCA registers", "cbreg Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cbreg +api_type: +- NA +--- + +# !cbreg + + +The **!cbreg** extension displays CardBus Socket registers and CardBus Exchangable Card Architecture (ExCA) registers. + +``` + !cbreg [%%]Address +``` + +## Parameters + + + **%%** +Indicates that *Address* is a physical address rather than a virtual address. + + *Address* +Specifies the address of the register to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kext.dll +Kdextx86.dll

Windows XP and later

Kext.dll

+ +  + +The **!cbreg** extension is only available for an x86-based target computer. + +### Additional Information + +The [**!exca**](-exca.md) extension can be used to display PCIC ExCA registers by socket number. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cbreg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cchelp.md b/windows-driver-docs-pr/debugger/-cchelp.md new file mode 100644 index 0000000000..ad5bf93f53 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cchelp.md @@ -0,0 +1,63 @@ +--- +title: cchelp +description: The cchelp extension displays some brief Help text in the Debugger command window for some of the cache management extensions. +ms.assetid: ad9b217b-22fc-433a-87ba-47e5ac5537ec +keywords: ["cache manager", "cchelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cchelp +api_type: +- NA +--- + +# !cchelp + + +The **!cchelp** extension displays some brief Help text in the Debugger command window for some of the cache management extensions. + +``` +!cchelp +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +The **!cchelp** extension displays help for the [**!bcb**](-bcb.md), [**!defwrites**](-defwrites.md), [**!finddata**](-finddata.md), and [**!scm**](-scm.md) cache management extensions. Other cache management extensions include [**!openmaps**](-openmaps.md) and [**!pcm**](-pcm.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cchelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-chain--list-debugger-extensions-.md b/windows-driver-docs-pr/debugger/-chain--list-debugger-extensions-.md new file mode 100644 index 0000000000..1e9cb7d8a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-chain--list-debugger-extensions-.md @@ -0,0 +1,75 @@ +--- +title: .chain (List Debugger Extensions) +description: The .chain command lists all loaded debugger extensions in their default search order. +ms.assetid: 73139b02-265a-424d-9de8-f4f3736e62db +keywords: [".chain (List Debugger Extensions) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .chain (List Debugger Extensions) +api_type: +- NA +--- + +# .chain (List Debugger Extensions) + + +The **.chain** command lists all loaded debugger extensions in their default search order. + +``` +.chain +.chain /D +``` + +## Parameters + + + **/D** +Displays the output using [Debugger Markup Language](debugger-markup-language-commands.md). In the output, each listed module is a link that you can click to get information about the extensions that are implemented by the module. + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details on loading, unloading, and controlling extensions, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). For details on executing extension commands and an explanation of the default search order, see [Using Debugger Extension Commands](using-debugger-extension-commands.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.chain%20%28List%20Debugger%20Extensions%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-childdbg--debug-child-processes-.md b/windows-driver-docs-pr/debugger/-childdbg--debug-child-processes-.md new file mode 100644 index 0000000000..1c42bab57b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-childdbg--debug-child-processes-.md @@ -0,0 +1,81 @@ +--- +title: .childdbg (Debug Child Processes) +description: The .childdbg command controls the debugging of child processes. +ms.assetid: 87d70d3b-d9d5-4a37-b8a7-1616ba78b2f3 +keywords: [".childdbg (Debug Child Processes) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .childdbg (Debug Child Processes) +api_type: +- NA +--- + +# .childdbg (Debug Child Processes) + + +The **.childdbg** command controls the debugging of child processes. + +``` +.childdbg 0 +.childdbg 1 +.childdbg +``` + +## Parameters + + + **0** +Prevents the debugger from debugging child processes. + + **1** +Causes the debugger to debug child processes. + +### Environment + +This command is only supported in Windows XP and later versions of Windows. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

x86, x64, and Itanium only

+ +  + +Remarks +------- + +**Child processes** are additional processes launched by the original target application. + +With no parameters, **.childdbg** will display the current status of child-process debugging. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.childdbg%20%28Debug%20Child%20Processes%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-chkimg.md b/windows-driver-docs-pr/debugger/-chkimg.md new file mode 100644 index 0000000000..0ca9f593a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-chkimg.md @@ -0,0 +1,291 @@ +--- +title: chkimg +description: The chkimg extension detects corruption in the images of executable files by comparing them to the copy on a symbol store or other file repository. +ms.assetid: 8079676c-1138-4c60-95df-62fd270fee62 +keywords: ["executable files and paths, corruption", "chkimg Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- chkimg +api_type: +- NA +--- + +# !chkimg + + +The **!chkimg** extension detects corruption in the images of executable files by comparing them to the copy on a symbol store or other file repository. + +``` +!chkimg [Options] [-mmw LogFile LogOptions] [Module] +``` + +## Parameters + + + *Options* +Any combination of the following options: + +**-p** **** *SearchPath* +Recursively searches *SearchPath* for the file before accessing the symbol server. + +**-f** +Fixes errors in the image. Whenever the scan detects differences between the file on the symbol store and the image in memory, the contents of the file on the symbol store are copied over the image. If you are performing live debugging, you can create a dump file before you execute the **!chkimg -f** extension. + +**-nar** +Prevents the mapped image of the file on the symbol server from being moved. By default, when the copy of the file is located on the symbol server and mapped into memory, **!chkimg** moves the image of the file on the symbol server. However, if you use the **-nar** option, the image of the file from the server is not moved. + +The executable image that is already in memory (that is, the one that is being scanned) is moved, because the debugger always relocates images that it loads. + +This switch is useful only if the operating system already moved the original image. If the image has not been moved, **!chkimg** and the debugger will move the image. Use of this switch is rare. + +**-ss** **** *SectionName* +Limits the scan to those sections whose names contain the string *SectionName*. The scan will include any non-discardable section whose name contains this string. *SectionName* is case sensitive and cannot exceed 8 characters. + +**-as** +Causes the scan to include all sections of the image except discardable sections. By default, (if you do not use **-as** or **-ss**), the scan skips sections that are writeable, sections that are not executable, sections that have "PAGE" in their name, and discardable sections. + +**-r** **** *StartAddress* **** *EndAddress* +Limits the scan to the memory range that begins with *StartAddress* and ends with *EndAddress*. Within this range, any sections that would typically be scanned are scanned. If a section partially overlaps with this range, only that part of the section that overlaps with this range is scanned. The scan is limited to this range even if you also use the **-as** or **-ss** switch. + +**-nospec** +Causes the scan to include the reserved sections of Hal.dll and Ntoskrnl.exe. By default, **!chkimg** does not check certain parts of these files. + +**-noplock** +Displays areas that mismatch by having a byte value of 0x90 (a **nop** instruction) and a byte value of 0xF0 (a **lock** instruction). By default, these mismatches are not displayed. + +**-np** +Causes patched instructions to be recognized. + +**-d** +Displays a summary of all mismatched areas while the scan is occurring. For more information about this summary text, see the Remarks section. + +**-db** +Displays mismatched areas in a format that is similar to the [**db debugger command**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md). Therefore, each display line shows the address of the first byte in the line, followed by up to 16 hexadecimal byte values. The byte values are immediately followed by the corresponding ASCII values. All nonprintable characters, such as carriage returns and line feeds, are displayed as periods (.). The mismatched bytes are marked by an asterisk (\*). + +**-lo** **** *lines* +Limits the number of output lines that **-d** or **-db** display to the lines number of lines. + +**-v** +Displays verbose information. + + **-mmw** +Creates a log file and records the activity of **!chkimg** in this file. Each line of the log file represents a single mismatch. + + *LogFile* +Specifies the full path of the log file. If you specify a relative path, the path is relative to the current path. + + *LogOptions* +Specifies the contents of the log file. *LogOptions* is a string that consists of a concatenation of various letters. Each line in the log file contains several columns that are separated by commas. These columns include the items that the following option letters specify, in the order that the letters appear in the *LogOptions* string. You can include the following options multiple times. You must include at least one option. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Log optionInformation included in the log file

v

The virtual address of the mismatch

r

The offset (relative address) of the mismatch within the module

s

The symbol that corresponds to the address of the mismatch

S

The name of the section that contains the mismatch

e

The correct value that was expected at the mismatch location

w

The incorrect value that was at the mismatch location

+ +  + +*LogOptions* can also include some, or none, of the following additional options. + + ++++ + + + + + + + + + + + + + + + + +
Log optionEffect

o

If a file that has the name LogFile already exists, the existing file is overwritten. By default, the debugger appends new information to the end of any existing file.

tString

Adds an extra column to the log file. Each entry in this column contains String. The tString option is useful if you are appending new information to an existing log file and you have to distinguish the new records from the old. You cannot add space between t and String. If you use the tIString option, it must be the final option in LogOptions, because String is taken to include all of the characters that are present before the next space.

+ +  + +For example, if *LogOptions* is **rSewo**, each line of the log file contains the relative address and section name of the mismatch location and the expected and actual values at that location. This option also causes any previous file to be overwritten. You can use the **-mmw** switch multiple times if you want to create several log files that have different options. You can create up to 10 log files at the same time. + + *Module* +Specifies the module to check. *Module* can be the name of the module, the starting address of the module, or any address that is contained in the module. If you omit *Module*, the debugger uses the module that contains the current instruction pointer. + + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +When you use **!chkimg**, it compares the image of an executable file in memory to the copy of the file that resides on a symbol store. + +All sections of the file are compared, except for sections that are discardable, that are writeable, that are not executable, that have "PAGE" in their name, or that are from INITKDBG. You can change this behavior can by using the **-ss**, **-as**, or **-r** switches. + +**!chkimg** displays any mismatch between the image and the file as an image error, with the following exceptions: + +- Addresses that are occupied by the Import Address Table (IAT) are not checked. + +- Certain specific addresses in Hal.dll and Ntoskrnl.exe are not checked, because certain changes occur when these sections are loaded. To check these addresses, include the **-nospec** option. + +- If the byte value 0x90 is present in the file, and if the value 0xF0 is present in the corresponding byte of the image (or vice versa), this situation is considered a match. Typically, the symbol server holds one version of a binary that exists in both uniprocessor and multiprocessor versions. On an x86-based processor, the **lock** instruction is 0xF0, and this instruction corresponds to a **nop** (0x90) instruction in the uniprocessor version. If you want **!chkimg** to display this pair as a mismatch, set the **-noplock** option. + +**Note**   If you use the **-f** option to fix image mismatches, **!chkimg** fixes only those mismatches that it considers to be errors. For example, **!chkimg** does not change an 0x90 byte to an 0xF0 byte unless you include **-noplock**. + +  + +When you include the **-d** option, **!chkimg** displays a summary of all mismatched areas while the scan is occurring. Each mismatch is displayed on two lines. The first line includes the start of the range, the end of the range, the size of the range, the symbol name and offset that corresponds to the start of the range, and the number of bytes since the last error (in parentheses). The second line is enclosed in brackets and includes the hexadecimal byte values that were expected, a colon, and then the hexadecimal byte values that were actually encountered in the image. If the range is longer than 8 bytes, only the first 8 bytes are shown before the colon and after the colon. The following example shows this situation. + +``` +be000015-be000016 2 bytes - win32k!VeryUsefulFunction+15 (0x8) + [ 85 dd:95 23 ] +``` + +Occasionally, a driver alters part of the Microsoft Windows kernel by using hooks, redirection, or other methods. Even a driver that is no longer on the stack might have altered part of the kernel. You can use the **!chkimg** extension as a file comparison tool to determine which parts of the Windows kernel (or any other image) are being altered by drivers and exactly how the parts are being changed. This comparison is most effective on full dump files. + +You can also use **!chkimg** together with the [**!for\_each\_module**](-for-each-module.md) extension to check the image of each loaded module. The following example shows this situation. + +``` +!for_each_module !chkimg @#ModuleName +``` + +Suppose that you encounter a bug check, for example, and begin by using [**!analyze**](-analyze.md). + +``` +kd> !analyze +.... +BugCheck 1000008E, {c0000005, bf920e48, baf75b38, 0} +Probably caused by : memory_corruption +CHKIMG_EXTENSION: !chkimg !win32k +.... +``` + +In this example, the [**!analyze**](-analyze.md) output suggests that memory corruption has occurred and includes a CHKIMG\_EXTENSION line that suggests that Win32k.sys could be the corrupted module. (Even if this line is not present, you might consider possible corruption in the module on top of the stack.) Start by using **!chkimg** without any switches, as the following example shows. + +``` +kd> !chkimg win32k +Number of different bytes for win32k: 31 +``` + +The following example shows that there are indeed memory corruptions. Use **!chkimg -d** to display all of the errors for the Win32k module. + +``` +kd> !chkimg win32k -d + bf920e40-bf920e46 7 bytes - win32k!HFDBASIS32::vSteadyState+1f + [ 78 08 d3 78 0c c2 04:00 00 00 00 00 01 00 ] + bf920e48-bf920e5f 24 bytes - win32k!HFDBASIS32::vHalveStepSize (+0x08) + [ 8b 51 0c 8b 41 08 56 8b:00 00 00 00 00 00 00 00 ] +Number of different bytes for win32k: 31 +``` + +When you try to disassemble the corrupted image of the second section that is listed, the following output might occur. + +``` +kd> u win32k!HFDBASIS32::vHalveStepSize +win32k!HFDBASIS32::vHalveStepSize: +bf920e48 0000 add [eax],al +bf920e4a 0000 add [eax],al +bf920e4c 0000 add [eax],al +bf920e4e 0000 add [eax],al +bf920e50 7808 js win32k!HFDBASIS32::vHalveStepSize+0x12 (bf920e5a) +bf920e52 d3780c sar dword ptr [eax+0xc],cl +bf920e55 c20400 ret 0x4 +bf920e58 8b510c mov edx,[ecx+0xc] +``` + +Then, use **!chkimg -f**to fix the memory corruption. + +``` +kd> !chkimg win32k -f +Warning: Any detected errors will be fixed to what we expect! +Number of different bytes for win32k: 31 (fixed) +``` + +Now you can disassemble the corrected view and see the changes that you have made. + +``` +kd> u win32k!HFDBASIS32::vHalveStepSize +win32k!HFDBASIS32::vHalveStepSize: +bf920e48 8b510c mov edx,[ecx+0xc] +bf920e4b 8b4108 mov eax,[ecx+0x8] +bf920e4e 56 push esi +bf920e4f 8b7104 mov esi,[ecx+0x4] +bf920e52 03c2 add eax,edx +bf920e54 c1f803 sar eax,0x3 +bf920e57 2bf0 sub esi,eax +bf920e59 d1fe sar esi,1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!chkimg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-chklowmem.md b/windows-driver-docs-pr/debugger/-chklowmem.md new file mode 100644 index 0000000000..14dd7e38be --- /dev/null +++ b/windows-driver-docs-pr/debugger/-chklowmem.md @@ -0,0 +1,62 @@ +--- +title: chklowmem +description: The chklowmem extension determines whether physical memory pages below 4 GB are filled with the required fill pattern on a computer that was booted with the /pae and /nolowmem options. +ms.assetid: cc1054e2-b824-4fcf-b353-9ee8c0d3dbf3 +keywords: ["PAE (physical address extension)", "chklowmem Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- chklowmem +api_type: +- NA +--- + +# !chklowmem + + +The **!chklowmem** extension determines whether physical memory pages below 4 GB are filled with the required fill pattern on a computer that was booted with the [**/pae**](https://msdn.microsoft.com/library/windows/hardware/ff557168) and [**/nolowmem**](https://msdn.microsoft.com/library/windows/hardware/ff557144) options. + +``` +!chklowmem +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +This extension is useful when you are verifying that kernel-mode drivers operate properly with physical memory above the 4 GB boundary. Typically, drivers fail by truncating a physical address to 32 bits and then in writing below the 4 GB boundary. The **!chklowmem** extension will detect any writes below the 4 GB boundary. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!chklowmem%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-chksym.md b/windows-driver-docs-pr/debugger/-chksym.md new file mode 100644 index 0000000000..e37ded12ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/-chksym.md @@ -0,0 +1,75 @@ +--- +title: chksym +description: The chksym extension tests the validity of a module against a symbol file. +ms.assetid: 52ea75cb-44a2-4c84-a3af-b3fc027348f4 +keywords: ["chksym Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- chksym +api_type: +- NA +--- + +# !chksym + + +The **!chksym** extension tests the validity of a module against a symbol file. + +``` + !chksym Module [Symbol] +``` + +## Parameters + + + *Module* +Specifies the name of the module by its name or base address. + + *Symbol* +Specifies the name of a symbol file. + +### DLL + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Vista and later

Dbghelp.dll

+ +  + +Remarks +------- + +If you do not specify a symbol filed, the loaded symbol is tested. Otherwise, if you specify a .pdb or .dbg symbol file path, the loaded symbol is tested against the loaded module. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!chksym%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-clients--list-debugging-clients-.md b/windows-driver-docs-pr/debugger/-clients--list-debugging-clients-.md new file mode 100644 index 0000000000..49fcd785bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-clients--list-debugging-clients-.md @@ -0,0 +1,68 @@ +--- +title: .clients (List Debugging Clients) +description: The .clients command lists all debugging clients currently connected to the debugging session. +ms.assetid: a5f760d7-f454-49c5-853d-bcb545c0b05e +keywords: [".clients (List Debugging Clients) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .clients (List Debugging Clients) +api_type: +- NA +--- + +# .clients (List Debugging Clients) + + +The **.clients** command lists all debugging clients currently connected to the debugging session. + +``` + .clients +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more details and other commands that can be used while performing remote debugging through the debugger, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.clients%20%28List%20Debugging%20Clients%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-closehandle--close-handle-.md b/windows-driver-docs-pr/debugger/-closehandle--close-handle-.md new file mode 100644 index 0000000000..69d370cbfc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-closehandle--close-handle-.md @@ -0,0 +1,76 @@ +--- +title: .closehandle (Close Handle) +description: The .closehandle command closes a handle owned by the target application. +ms.assetid: 1513cbdd-327f-447a-8267-633cb123d17d +keywords: [".closehandle (Close Handle) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .closehandle (Close Handle) +api_type: +- NA +--- + +# .closehandle (Close Handle) + + +The **.closehandle** command closes a handle owned by the target application. + +``` +.closehandle Handle +.closehandle -a +``` + +## Parameters + + + *Handle* +Specifies the handle to be closed. + + **-a** +Causes all handles owned by the target application to be closed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +You can use the [**!handle**](-handle.md) extension to display the existing handles. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.closehandle%20%28Close%20Handle%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cls--clear-screen-.md b/windows-driver-docs-pr/debugger/-cls--clear-screen-.md new file mode 100644 index 0000000000..a8dff44882 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cls--clear-screen-.md @@ -0,0 +1,64 @@ +--- +title: .cls (Clear Screen) +description: The .cls command clears the Debugger Command window display. +ms.assetid: 95f3083f-19c4-42c6-b9be-32818b0e64e1 +keywords: [".cls (Clear Screen) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .cls (Clear Screen) +api_type: +- NA +--- + +# .cls (Clear Screen) + + +The **.cls** command clears the Debugger Command window display. + +``` + .cls +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.cls%20%28Clear%20Screen%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cmreslist.md b/windows-driver-docs-pr/debugger/-cmreslist.md new file mode 100644 index 0000000000..1e52cceb87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cmreslist.md @@ -0,0 +1,67 @@ +--- +title: cmreslist +description: The cmreslist extension displays the CM_RESOURCE_LIST structure for the specified device object. +ms.assetid: 56b48f62-c638-4082-95d7-5a0c62c94212 +keywords: ["CM_RESOURCE_LIST", "cmreslist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cmreslist +api_type: +- NA +--- + +# !cmreslist + + +The **!cmreslist** extension displays the CM\_RESOURCE\_LIST structure for the specified device object. + +``` +!cmreslist Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the CM\_RESOURCE\_LIST structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about the CM\_RESOURCE\_LIST structure, see the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cmreslist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-context--set-user-mode-address-context-.md b/windows-driver-docs-pr/debugger/-context--set-user-mode-address-context-.md new file mode 100644 index 0000000000..0a8c7eee58 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-context--set-user-mode-address-context-.md @@ -0,0 +1,135 @@ +--- +title: .context (Set User-Mode Address Context) +description: The .context command specifies which page directory of a process will be used for the user-mode address context, or displays the current user-mode address context. +ms.assetid: f859b9bf-c05a-44cd-b6f0-8ff4561ddd4e +keywords: ["Set User-Mode Address Context (.context) command", "addresses, Set User-Mode Address Context (.context) command", "context, Set User-Mode Address Context (.context) command", ".context (Set User-Mode Address Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .context (Set User-Mode Address Context) +api_type: +- NA +--- + +# .context (Set User-Mode Address Context) + + +The **.context** command specifies which page directory of a process will be used for the user-mode address context, or displays the current user-mode address context. + +``` +.context [PageDirectoryBase] +``` + +## Parameters + + + *PageDirectoryBase* +Specifies the base address for a page directory of a desired process. The user-mode address context will be set to this page directory. If *PageDirectoryBase* is zero, the user-mode address context will be set to the page directory for the current system state. If *PageDirectoryBase* is omitted, the current user-mode address context is displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about the user-mode address context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +Generally, when you are doing kernel debugging, the only visible user-mode address space is the one associated with the current process. + +The **.context** command instructs the kernel debugger to use the specified page directory as the *user-mode address context*. After this command is executed, the debugger will have access to this virtual address space. The page tables for this address space will be used to interpret all user-mode memory addresses. This allows you to read and write to this memory. + +The [**.process (Set Process Context)**](-process--set-process-context-.md) command has a similar effect. However, the **.context** command sets the user-mode address context to a specific page directory, while the **.process** command sets the *process context* to a specific process. On an x86 processor, these two commands have essentially the same effect. However, on an Itanium processor, a single process may have more than one page directory. In this case, the **.process** command is more powerful, because it will allow access to all the page directories associated with a process. See [Process Context](changing-contexts.md#process-context) for more details. + +If you are doing live debugging, you should issue a [**.cache forcedecodeuser**](-cache--set-cache-size-.md) command in addition to the **.context** command. This forces the debugger to look up the physical addresses of the memory space needed. (This can be slow, because it often means a huge amount of data must be transferred across the debug cable.) + +If you are doing crash dump debugging, the [**.cache**](-cache--set-cache-size-.md) command is not needed. However, you will not have access to any portions of the virtual address space of the user-mode process that were paged to disk when the crash occurred. + +Here is an example. Use the [**!process**](-process.md) extension to find the directory base for the desired process: + +``` +kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +PROCESS fe5039e0 SessionId: 0 Cid: 0008 Peb: 00000000 ParentCid: 0000 + DirBase: 00030000 ObjectTable: fe529b68 TableSize: 50. + Image: System + +... + +PROCESS fe3c0d60 SessionId: 0 Cid: 0208 Peb: 7ffdf000 ParentCid: 00d4 + DirBase: 0011f000 ObjectTable: fe3d0f48 TableSize: 30. + Image: regsvc.exe +``` + +Now use the **.context** command with this page directory base. + +``` +kd> .context 0011f000 +``` + +This enables you to examine the address space in various ways. For example, here is the output of the [**!peb**](-peb.md) extension: + +``` +kd> !peb +PEB at 7FFDF000 + InheritedAddressSpace: No + ReadImageFileExecOptions: No + BeingDebugged: No + ImageBaseAddress: 01000000 + Ldr.Initialized: Yes + Ldr.InInitializationOrderModuleList: 71f40 . 77f68 + Ldr.InLoadOrderModuleList: 71ec0 . 77f58 + Ldr.InMemoryOrderModuleList: 71ec8 . 77f60 + 01000000 C:\WINNT\system32\regsvc.exe + 77F80000 C:\WINNT\System32\ntdll.dll + 77DB0000 C:\WINNT\system32\ADVAPI32.dll + 77E80000 C:\WINNT\system32\KERNEL32.DLL + 77D40000 C:\WINNT\system32\RPCRT4.DLL + 77BE0000 C:\WINNT\system32\secur32.dll + SubSystemData: 0 + ProcessHeap: 70000 + ProcessParameters: 20000 + WindowTitle: 'C:\WINNT\system32\regsvc.exe' + ImageFile: 'C:\WINNT\system32\regsvc.exe' + CommandLine: 'C:\WINNT\system32\regsvc.exe' + DllPath: 'C:\WINNT\system32;.;C:\WINNT\System32;C:\WINNT\system;C:\WINNT;C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\PROGRA~1\COMMON~1\AUTODE~1' + Environment: 0x10000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.context%20%28Set%20User-Mode%20Address%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-continue.md b/windows-driver-docs-pr/debugger/-continue.md new file mode 100644 index 0000000000..b85cdb3305 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-continue.md @@ -0,0 +1,54 @@ +--- +title: .continue +description: The .continue token behaves like the continue keyword in C. +ms.assetid: c8f6c69c-d912-4ce4-a9c2-d82c349484a9 +keywords: [".continue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .continue +api_type: +- NA +--- + +# .continue + + +The **.continue** token behaves like the **continue** keyword in C. + +``` +.for (...) { ... ; .if (Condition) .continue ; ... } + +.while (...) { ... ; .if (Condition) .continue ; ... } + +.do { ... ; .if (Condition) .continue ; ... } (...) +``` + +## + + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The **.continue** token can be used within any [**.for**](-for.md), [**.while**](-while.md), or [**.do**](-do.md) loop. + +Since there is no control flow token equivalent to the C goto statement, you will usually use the **.continue** token within an [**.if**](-if.md) conditional, as shown in the syntax examples above. However, this is not actually required. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.continue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-copysym--copy-symbol-files-.md b/windows-driver-docs-pr/debugger/-copysym--copy-symbol-files-.md new file mode 100644 index 0000000000..6eedc3a65d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-copysym--copy-symbol-files-.md @@ -0,0 +1,75 @@ +--- +title: .copysym (Copy Symbol Files) +description: The .copysym command copies the current symbol files to the specified directory. +ms.assetid: f90d1402-4bf3-4cd0-993e-a42c220beb7a +keywords: [".copysym (Copy Symbol Files) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .copysym (Copy Symbol Files) +api_type: +- NA +--- + +# .copysym (Copy Symbol Files) + + +The **.copysym** command copies the current symbol files to the specified directory. + +``` + .copysym [/l] Path +``` + +## Parameters + + + **/l** +Causes each symbol file to be loaded as it is copied. + + *Path* +Specifies the directory to which the symbol files should be copied. Copies do not overwrite existing files. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +Many times, symbols are stored on a network. The symbol access can often be slow, or you may need to transport your debugging session to another computer where you no longer have network access. In such scenarios, the **.copysym** command can be used to copy the symbols you need for your session to a local directory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.copysym%20%28Copy%20Symbol%20Files%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cordll--control-clr-debugging-.md b/windows-driver-docs-pr/debugger/-cordll--control-clr-debugging-.md new file mode 100644 index 0000000000..d295f1366a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cordll--control-clr-debugging-.md @@ -0,0 +1,131 @@ +--- +title: .cordll (Control CLR Debugging) +description: The .cordll command controls managed code debugging and the Microsoft .NET common language runtime (CLR). +ms.assetid: d46965b3-4f20-4e25-82e6-79e7fb9b4838 +keywords: ["Control CLR Debugging (.cordll) command", "CLR (common language runtime)", ".cordll (Control CLR Debugging) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .cordll (Control CLR Debugging) +api_type: +- NA +--- + +# .cordll (Control CLR Debugging) + + +The **.cordll** command controls managed code debugging and the Microsoft .NET common language runtime (CLR). + +``` +.cordll [Options] +``` + +## Parameters + + + *Options* +One or more of the following options: + +**-l** (lower-case L) +Loads the CLR debugging modules. + +**-I** **** *Module* (upper-case i) +Specifies the name or base address of the CLR module to be debugged. For more information, see Remarks. + +**-u** +Unloads the CLR debugging modules. + +**-e** +Enables CLR debugging. + +**-d** +Disables CLR debugging. + +**-D** +Disables CLR debugging and unloads the CLR debugging modules. + +**-N** +Reloads the CLR debugging modules. + +**-lp** **** *Path* +Specifies the directory path of the CLR debugging modules. + +**-se** +Enables using the short name of the CLR debugging module, mscordacwks.dll. + +**-sd** +Disables using the short name of the CLR debugging module, mscordacwks.dll. Instead, the debugger uses the long name of the CLR debugging module, mscordacwks\_<spec>.dll. Turning off short name usage enables you to avoid having your local CLR used if you are concerned about mismatches. + +**-ve** +Turns on verbose mode for CLR module loading. + +**-vd** +Turns off verbose mode for CLR module loading. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +To debug a managed application, the debugger must load a data access component (DAC) that corresponds to the CLR that the application has loaded. However, in some cases, the application loads more than one CLR. In that case, you can use the **I** parameter to specify which DAC the debugger should load. Version 2 of the CLR is named Mscorwks.dll, and version 4 of the CLR is named Clr.dll. The following example shows how to specify that the debugger should load the DAC for version 2 (mscorwks). + +``` +.cordll -I mscorwks -lp c:\dacFolder +``` + +If you omit the **I** parameter, the debugger uses version 4 by default. For example, the following two commands are equivalent. + +``` +.cordll -lp c:\dacFolder +.cordll -I clr -lp c:\dacFolder +``` + +Sos.dll is a component that is used for debugging managed code. The current version of Debugging Tools for Windows does not include any version of sos.dll. For information about how to get sos.dll, see [Getting the SOS Debugging Extension (sos.dll)](debugging-managed-code.md#getting-the-sos-debugging-extension). + +The **.cordll** command is supported in kernel-mode debugging. However, this command might not work unless the necessary memory is paged in. + +## See also + + +[Debugging Managed Code Using the Windows Debugger](debugging-managed-code.md) + +[SOS Debugging Extension](http://go.microsoft.com/fwlink/p/?linkid=223345) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.cordll%20%28Control%20CLR%20Debugging%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-cppexr.md b/windows-driver-docs-pr/debugger/-cppexr.md new file mode 100644 index 0000000000..c440676c52 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cppexr.md @@ -0,0 +1,76 @@ +--- +title: cppexr +description: The cppexr extension displays the contents of a C++ exception record. +ms.assetid: 568c98e9-31d9-4c49-9b7a-bc8eccfed24a +keywords: ["exception records", "cppexr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cppexr +api_type: +- NA +--- + +# !cppexr + + +The **!cppexr** extension displays the contents of a C++ exception record. + +``` + !cppexr Address +``` + +## Parameters + + + *Address* +Specifies the address of the C++ exception record to display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about exceptions, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md), the Windows Driver Kit (WDK) documentation, the Windows SDK documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) Use the [**.exr**](-exr--display-exception-record-.md) command to display other exception records. + +Remarks +------- + +The **!cppexr** extension displays information that is related to a C++ exception that the target encounters, including the exception code, the address of the exception, and the exception flags. This exception must be one of the standard C++ exceptions that are defined in Msvcrt.dll. + +You can typically obtain the *Address* parameter by using the [**!analyze -v**](-analyze.md) command. + +The **!cppexr** extension is useful for determining the type of a C++ exception. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cppexr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cpuid.md b/windows-driver-docs-pr/debugger/-cpuid.md new file mode 100644 index 0000000000..de06ce4cb3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cpuid.md @@ -0,0 +1,89 @@ +--- +title: cpuid +description: The cpuid extension displays information about the processors on the system. +ms.assetid: 3dbd1079-d129-4e17-8d06-18b25fdd17c9 +keywords: ["cpuid Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cpuid +api_type: +- NA +--- + +# !cpuid + + +The **!cpuid** extension displays information about the processors on the system. + +``` +!cpuid [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor whose information will be displayed. If you omit this parameter, all processors are displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about how to debug multiprocessor computers, see [Multiprocessor Syntax](multiprocessor-syntax.md). + +Remarks +------- + +The **!cpuid** extension works during live user-mode or kernel-mode debugging, local kernel debugging, and debugging of dump files. However, user-mode minidump files contain only information about the active processor. + +If you are debugging in user mode, the **!cpuid** extension describes the computer that the target application is running on. In kernel mode, it describes the target computer. + +The following example shows this extension. + +``` +kd> !cpuid +CP F/M/S Manufacturer MHz + 0 6,5,1 GenuineIntel 700 + 1 8,1,5 AuthenticAMD 700 +``` + +The **CP** column gives the processor number. (These numbers are always sequential, starting with zero). The **Manufacturer** column specifies the processor manufacturer. The **MHz** column specifies the processor speed, if it is available. + +For an x86-based processor or an x64-based processor, the **F** column displays the processor family number, the **M** column displays the processor model number, and the **S** column displays the stepping size. + +For an Itanium-based processor, the **M** column displays the processor model number, the R column displays the processor revision number, the **F** column displays the processor family number, and the **A** column displays the architecture revision number. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cpuid%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cpuinfo.md b/windows-driver-docs-pr/debugger/-cpuinfo.md new file mode 100644 index 0000000000..0ccb680d6c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cpuinfo.md @@ -0,0 +1,84 @@ +--- +title: cpuinfo +description: The cpuinfo extension displays detailed information about the target computer's CPU. +ms.assetid: 1e7c348b-0de8-4925-b0a9-300391b6064e +keywords: ["cpuinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cpuinfo +api_type: +- NA +--- + +# !cpuinfo + + +The **!cpuinfo** extension displays detailed information about the target computer's CPU. + +Syntax + +``` +!cpuinfo [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor to be displayed. If this is omitted, all processors are displayed. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information about debugging multiprocessor computers, see [Multiprocessor Syntax](multiprocessor-syntax.md). + +Remarks +------- + +The **!cpuinfo** extension command can be used when performing [local kernel debugging](performing-local-kernel-debugging.md). + +Here is an example generated by an x86-based processor: + +``` +kd> !cpuinfo +CP F/M/S Manufacturer MHz Update Signature Features + 0 6,1,9 GenuineIntel 198 000000d200000000 000000ff +``` + +Here is an example generated by an Itanium-based processor: + +``` +kd> !cpuinfo +CP M/R/F/A Manufacturer SerialNumber Features Speed + 0 2,1,31,0 GenuineIntel 0000000000000000 0000000000000001 1300 Mhz + 1 2,1,31,0 GenuineIntel 0000000000000000 0000000000000001 1300 Mhz +``` + +The **CP** column indicates the processor number. The **Manufacturer** column specifies the processor manufacturer. The **MHz** or **Speed** column specifies the speed, in MHz, of the processor, if it is available. + +For an x86-based processor or an x64-based processor, the **F** column displays the processor family number, the **M** column displays the processor model number, and the **S** column displays the stepping size. + +For an Itanium-based processor, the **M** column displays the processor model number, the **R** column displays the processor revision number, the **F** column displays the processor family number, and the **A** column displays the architecture revision number. + +Other columns will also appear, depending on your machine's specific architecture. + +For details on how to interpret specific values for each entry, as well as any additional columns, consult the processor manual. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cpuinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-crash--force-system-crash-.md b/windows-driver-docs-pr/debugger/-crash--force-system-crash-.md new file mode 100644 index 0000000000..78b060d837 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-crash--force-system-crash-.md @@ -0,0 +1,77 @@ +--- +title: .crash (Force System Crash) +description: The .crash command causes the target computer to issue a bug check. +ms.assetid: 625d174d-7011-4b15-aad7-1b39aa3742a4 +keywords: [".crash (Force System Crash) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .crash (Force System Crash) +api_type: +- NA +--- + +# .crash (Force System Crash) + + +The **.crash** command causes the target computer to issue a bug check. + +``` +.crash +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For an overview of related commands and a description of the options available after a system crash, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +Remarks +------- + +This command will immediately cause the target computer to crash. + +If you are already in a bug check handler, do not use **.crash**. Use [**g (Go)**](g--go-.md) instead to continue execution of the handler, which will generate a crash dump. + +A kernel-mode dump file will be written if crash dumps have been enabled. See [Creating a Kernel-Mode Dump File](creating-a-kernel-mode-dump-file.md) for details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.crash%20%28Force%20System%20Crash%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-create--create-process-.md b/windows-driver-docs-pr/debugger/-create--create-process-.md new file mode 100644 index 0000000000..4d343d741c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-create--create-process-.md @@ -0,0 +1,86 @@ +--- +title: .create (Create Process) +description: The .create command creates a new target application. +ms.assetid: 9e34eadf-1f68-4eec-ad6b-d70163d5d876 +keywords: [".create (Create Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .create (Create Process) +api_type: +- NA +--- + +# .create (Create Process) + + +The **.create** command creates a new target application. + +``` +.create [-premote RemoteOptions] [-f] CommandLine +``` + +## Parameters + + + *RemoteOptions* +Specifies a process server to which to attach. The options are the same as those for the command line **-premote** option. See [**Activating a Smart Client**](activating-a-smart-client.md) for syntax details. + + **-f** +Freezes all threads in all target applications, except in the new target being created. These threads will remain frozen until an exception occurs in the newly-created process. Note that an initial breakpoint qualifies as an exception. Individual threads can be unfrozen by using the [**~u (Unfreeze Thread)**](-u--unfreeze-thread-.md) command. + + *CommandLine* +Specifies the complete command line for the new process. *CommandLine* may contain spaces, and must not be surrounded with quotes. All text after the **.create** command is taken as part of *CommandLine*; this command cannot be followed with a semicolon and additional debugger commands. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +This command can be used when CDB is dormant, or if it is already debugging one or more processes. It cannot be used when WinDbg is dormant. + +If this command is successful, the debugger will create the specified process the next time the debugger issues an execution command. If this command is used several times in a row, execution will have to be requested as many times as this command was used. + +Multiple target processes will always be executed together, unless some of their threads are frozen or suspended. + +If you wish to create a new process and freeze all your existing targets, use the -f option. + +If the **-premote** option is used, the new process will be part of a new system. For details, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.create%20%28Create%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-createdir--set-created-process-directory-.md b/windows-driver-docs-pr/debugger/-createdir--set-created-process-directory-.md new file mode 100644 index 0000000000..41256b60a4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-createdir--set-created-process-directory-.md @@ -0,0 +1,82 @@ +--- +title: .createdir (Set Created Process Directory) +description: The .createdir command controls the starting directory and handle inheritance for any processes created by the debugger. +ms.assetid: 797f5398-f0b4-48e9-bc5f-eac5a53cad67 +keywords: [".createdir (Set Created Process Directory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .createdir (Set Created Process Directory) +api_type: +- NA +--- + +# .createdir (Set Created Process Directory) + + +The **.createdir** command controls the starting directory and handle inheritance for any processes created by the debugger. + +``` +.createdir [-i | -I] [Path] +``` + +## Parameters + + + **-i** +Causes processes created by the debugger to inherit handles from the debugger. This is the default. + + **-I** +Prevents processes created by the debugger from inheriting handles from the debugger. + + *Path* +Specifies the starting directory for all child processes created by any target process. If *Path* contains spaces, it must be enclosed in quotation marks. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +If **.createdir** is used with no parameters, the current starting directory and handle inheritance status are displayed. + +If **.createdir** has never been used, any created process will use its usual default directory as its starting directory. If you have already set a path with **.createdir** and want to return to the default status, use **.createdir ""** with nothing inside the quotation marks. + +The **.createdir** setting affects all processes created by [**.create (Create Process)**](-create--create-process-.md). It also affects processes created by WinDbg's [File | Open Executable](file---open-executable.md) menu command, unless the **Start directory** text box is used to override this setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.createdir%20%28Set%20Created%20Process%20Directory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-critsec.md b/windows-driver-docs-pr/debugger/-critsec.md new file mode 100644 index 0000000000..ddac69ec7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-critsec.md @@ -0,0 +1,86 @@ +--- +title: critsec +description: The critsec extension displays a critical section. +ms.assetid: 7e30efd5-2bdc-420c-b3ed-504280ddd8f7 +keywords: ["critsec Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- critsec +api_type: +- NA +--- + +# !critsec + + +The **!critsec** extension displays a critical section. + +``` +!critsec Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the critical section. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +### Additional Information + +For other commands and extensions that can display critical section information, see [Displaying a Critical Section](displaying-a-critical-section.md). For information about critical sections, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +If you do not know the address of the critical section, you should use the [**!ntsdexts.locks**](-locks---ntsdexts-locks-.md) extension. This displays all critical sections that have been initialized by calling **RtlInitializeCriticalSection**. + +Here is an example: + +``` +0:000> !critsec 3a8c0e9c + +CritSec +3a8c0e9c at 3A8C0E9C +LockCount 1 +RecursionCount 1 +OwningThread 99 +EntryCount 472 +ContentionCount 1 +*** Locked +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!critsec%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cs.md b/windows-driver-docs-pr/debugger/-cs.md new file mode 100644 index 0000000000..c7d92cd89e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cs.md @@ -0,0 +1,216 @@ +--- +title: cs +description: The cs extension displays one or more critical sections or the whole critical section tree. +ms.assetid: 767ad508-013b-4cf7-808d-38ff64418879 +keywords: ["cs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- cs +api_type: +- NA +--- + +# !cs + + +The **!cs** extension displays one or more critical sections or the whole critical section tree. + +``` +!cs [-s] [-l] [-o] +!cs [-s] [-o] Address +!cs [-s] [-l] [-o] StartAddress EndAddress +!cs [-s] [-o] -d InfoAddress +!cs [-s] -t [TreeAddress] +!cs -? +``` + +## Parameters + + + **-s** +Displays each critical section's initialization stack trace, if this information is available. + + **-l** +Display only the locked critical sections. + + **-o** +Displays the owner's stack for any locked critical section that is being displayed. + + *Address* +Specifies the address of the critical section to display. If you omit this parameter, the debugger displays all critical sections in the current process. + + *StartAddress* +Specifies the beginning of the address range to search for critical sections. + + *EndAddress* +Specifies the end of the address range to search for critical sections. + + **-d** +Displays critical sections that are associated with DebugInfo. + + *InfoAddress* +Specifies the address of the DebugInfo. + + **-t** +Displays a critical section tree. Before you can use the **-t** option, you must activate [Application Verifier](application-verifier.md) for the target process and select the **Check lock usage** option. + + *TreeAddress* +Specifies the address of the root of the critical section tree. If you omit this parameter or specify zero, the debugger displays the critical section tree for the current process. + + **-?** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +For other commands and extensions that can display critical section information, see [Displaying a Critical Section](displaying-a-critical-section.md). For more information about critical sections, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The **!cs** extension requires full symbols (including type information) for the process that is being debugged and for Ntdll.dll. If you do not have symbols for Ntdll.dll, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +The following examples shows you how to use **!cs**. The following command displays information about the critical section at address 0x7803B0F8 and shows its initialization stack trace. + +``` +0:001> !cs -s 0x7803B0F8 +Critical section = 0x7803B0F8 (MSVCRT!__app_type+0x4) +DebugInfo = 0x6A262080 +NOT LOCKED +LockSemaphore = 0x0 +SpinCount = 0x0 + +Stack trace for DebugInfo = 0x6A262080: + +0x6A2137BD: ntdll!RtlInitializeCriticalSectionAndSpinCount+0x9B +0x6A207A4C: ntdll!LdrpCallInitRoutine+0x14 +0x6A205569: ntdll!LdrpRunInitializeRoutines+0x1D9 +0x6A20DCE1: ntdll!LdrpInitializeProcess+0xAE5 +``` + +The following command displays information about the critical section whose DebugInfo is at address 0x6A262080. + +``` +0:001> !cs -d 0x6A262080 +DebugInfo = 0x6A262080 +Critical section = 0x7803B0F8 (MSVCRT!__app_type+0x4) +NOT LOCKED +LockSemaphore = 0x0 +SpinCount = 0x0 +``` + +The following command displays information about all of the active critical sections in the current process. + +``` +## 0:001> !cs + +DebugInfo = 0x6A261D60 +Critical section = 0x6A262820 (ntdll!RtlCriticalSectionLock+0x0) +LOCKED +LockCount = 0x0 +OwningThread = 0x460 +RecursionCount = 0x1 +LockSemaphore = 0x0 +## SpinCount = 0x0 + +DebugInfo = 0x6A261D80 +Critical section = 0x6A262580 (ntdll!DeferedCriticalSection+0x0) +NOT LOCKED +LockSemaphore = 0x7FC +## SpinCount = 0x0 + +DebugInfo = 0x6A262600 +Critical section = 0x6A26074C (ntdll!LoaderLock+0x0) +NOT LOCKED +LockSemaphore = 0x0 +## SpinCount = 0x0 + +DebugInfo = 0x77fbde20 +Critical section = 0x77c8ba60 (GDI32!semColorSpaceCache+0x0) +LOCKED +LockCount = 0x0 +OwningThread = 0x00000dd8 +RecursionCount = 0x1 +LockSemaphore = 0x0 +## SpinCount = 0x00000000 + +... +``` + +The following command displays the critical section tree. + +``` +0:001> !cs -t + +Tree root 00bb08c0 + +Level Node CS Debug InitThr EnterThr WaitThr TryEnThr LeaveThr EnterCnt WaitCnt +## + + + 0 00bb08c0 77c7e020 77fbcae0 4c8 4c8 0 0 4c8 c 0 + 1 00dd6fd0 0148cfe8 01683fe0 4c8 4c8 0 0 4c8 2 0 + 2 00bb0aa0 008e8b84 77fbcc20 4c8 0 0 0 0 0 0 + 3 00bb09e0 008e8704 77fbcba0 4c8 0 0 0 0 0 0 + 4 00bb0a40 008e8944 77fbcbe0 4c8 0 0 0 0 0 0 + 5 00bb0a10 008e8824 77fbcbc0 4c8 0 0 0 0 0 0 + 5 00bb0a70 008e8a64 77fbcc00 4c8 0 0 0 0 0 0 + 3 00bb0b00 008e8dc4 77fbcc60 4c8 0 0 0 0 0 0 + 4 00bb0ad0 008e8ca4 77fbcc40 4c8 0 0 0 0 0 0 + 4 00bb0b30 008e8ee4 77fbcc80 4c8 0 0 0 0 0 0 + 5 00dd4fd0 0148afe4 0167ffe0 4c8 0 0 0 0 0 0 + 2 00bb0e90 77c2da98 00908fe0 4c8 4c8 0 0 4c8 3a 0 + 3 00bb0d70 77c2da08 008fcfe0 4c8 0 0 0 0 0 0 +``` + +The following items appear in this **!cs -t** display: + +- **InitThr** is the thread ID for the thread that initialized the CS. + +- **EnterThr** is the ID of the thread that called **EnterCriticalSection** last time. + +- **WaitThr** is the ID of the thread that found the critical section that another thread owned and waited for it last time. + +- **TryEnThr** is the ID of the thread that called **TryEnterCriticalSection** last time. + +- **LeaveThr** is the ID of the thread that called **LeaveCriticalSection** last time + +- **EnterCnt** is the count of **EnterCriticalSection**. + +- **WaitCnt** is the contention count. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cxr--display-context-record-.md b/windows-driver-docs-pr/debugger/-cxr--display-context-record-.md new file mode 100644 index 0000000000..bb204fd003 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cxr--display-context-record-.md @@ -0,0 +1,93 @@ +--- +title: .cxr (Display Context Record) +description: The .cxr command displays the context record saved at the specified address. It also sets the register context. +ms.assetid: 0e882639-6029-4512-8d46-050228e95cb6 +keywords: ["Display Context Record (.cxr) command", "context record", ".cxr (Display Context Record) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .cxr (Display Context Record) +api_type: +- NA +--- + +# .cxr (Display Context Record) + + +The **.cxr** command displays the context record saved at the specified address. It also sets the register context. + +``` +.cxr [Options] [Address] +``` + +## Parameters + + + *Options* +Can be any combination of the following options: + +**/f** **** *Size* +Forces the context size to equal the value of *Size*, in bytes. This can be useful when the context does not match the actual target -- for example, when using an x86 context on a 64-bit target during [*WOW64*](https://msdn.microsoft.com/library/windows/hardware/ff556347#wdkgloss-wow64) debugging. If an invalid or inconsistent size is specified, the error "Unable to convert context to canonical form" will be displayed. + +**/w** +Writes the current context to memory, and displays the address of the location where it was written. + + *Address* +Address of the system context record. + +Omitting the address does not display any context record information, but it does reset the register context. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +The information from a context record can be used to assist in debugging a system halt where an unhandled exception has occurred and an exact stack trace is not available. The **.cxr** command displays the important registers for the specified context record. + +This command also instructs the debugger to use the specified context record as the register context. After this command is executed, the debugger will have access to the most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command ([**.thread**](-thread--set-register-context-.md), [**.ecxr**](-ecxr--display-exception-context-record-.md), [**.trap**](-trap--display-trap-frame-.md) , or **.cxr** again). In user mode, it will also be reset if you change the current process or thread. See [Register Context](changing-contexts.md#register-context) for details. + +The **.cxr** command is often used to debug bug check 0x1E. For more information and an example, see [**Bug Check 0x1E**](bug-check-0x1e--kmode-exception-not-handled.md) (KMODE\_EXCEPTION\_NOT\_HANDLED). + +The **.cxr /w** command writes the context to memory and displays the address where it has been stored. This address can be passed to [**.apply\_dbp (Apply Data Breakpoint to Context)**](-apply-dbp--apply-data-breakpoint-to-context-.md) if you need to apply data breakpoints to this context. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.cxr%20%28Display%20Context%20Record%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-cxr.md b/windows-driver-docs-pr/debugger/-cxr.md new file mode 100644 index 0000000000..b578be377b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-cxr.md @@ -0,0 +1,29 @@ +--- +title: cxr +description: cxr +ms.assetid: c1e05916-25ab-48b2-8855-78b619b45192 +keywords: ["cxr extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !cxr + + +## + + +The **!cxr** extension command is obsolete. Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!cxr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-db---dc---dd---dp---dq---du---dw.md b/windows-driver-docs-pr/debugger/-db---dc---dd---dp---dq---du---dw.md new file mode 100644 index 0000000000..1810dadbba --- /dev/null +++ b/windows-driver-docs-pr/debugger/-db---dc---dd---dp---dq---du---dw.md @@ -0,0 +1,133 @@ +--- +title: db, dc, dd, dp, dq, du, dw +description: The db, dc, dd, dp, dq, du, and dw extensions display data at the specified physical address on the target computer. +ms.assetid: d34eebb7-bc91-4bff-9787-d92f74195ee1 +keywords: ["db extension", "dc extension", "dd extension", "dp extension", "dq extension", "du extension", "dw extension", "memory, Display Physical ( d ) extensions", "db, dc, dd, dp, dq, du, dw Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- db, dc, dd, dp, dq, du, dw +api_type: +- NA +--- + +# !db, !dc, !dd, !dp, !dq, !du, !dw + + +The **!db**, **!dc**, **!dd**, **!dp**, **!dq**, **!du**, and **!dw** extensions display data at the specified physical address on the target computer. + +These extension commands should not be confused with the [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command, or with the [**!ntsdexts.dp**](-dp---ntsdexts-dp-.md) extension command. + +``` +!db [Caching] [-m] [PhysicalAddress] [L Size] +!dc [Caching] [-m] [PhysicalAddress] [L Size] +!dd [Caching] [-m] [PhysicalAddress] [L Size] +!dp [Caching] [-m] [PhysicalAddress] [L Size] +!dq [Caching] [-m] [PhysicalAddress] [L Size] +!du [Caching] [-m] [PhysicalAddress] [L Size] +!dw [Caching] [-m] [PhysicalAddress] [L Size] +``` + +## Parameters + + + *Caching* +Can be any one of the following values. The *Caching* value must be surrounded by square brackets: + +**\[c\]** +Causes this extension to read from cached memory. + +**\[uc\]** +Causes this extension to read from uncached memory. + +**\[wc\]** +Causes this extension to read from write-combined memory. + + **-m** +Causes memory to be read one unit at a time. For example, **!db -m** reads memory in 8-bit chunks and **!dw -m** reads memory in 16-bit chunks. If your hardware does not support 32-bit physical memory reads, it may be necessary to use the **-m** option. This option does not affect the length or appearance of the display -- it only affects how the memory is accessed. + + *PhysicalAddress* +Specifies the first physical address to be displayed, in hexadecimal format. If this is omitted the first time this command is used, the address defaults to zero. If this is omitted on a subsequent use, the display will begin where the last display ended. + + **L** **** *Size* +Specifies the number of chunks of memory to display. The size of a chunk is determined by the precise extension used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kext.dll +Kdextx86.dll

Windows XP and later

Kext.dll

+ +  + +### Additional Information + +To write to physical memory, use the [**!e\***](-eb---ed.md) extensions. For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +These extensions each display physical memory, but their display formats and default length differ: + +- The **!db** extension displays hexadecimal bytes and their ASCII character equivalents. The default length is 128 bytes. + +- The **!dc** extension displays DWORD values and their ASCII character equivalents. The default length is 32 DWORDs (128 total bytes). + +- The **!dd** extension displays DWORD values. The default length is 32 DWORDs (128 total bytes). + +- The **!dp** extension displays ULONG\_PTR values. These are either 32-bit or 64-bit words, depending on the instruction size. The default length is 128 total bytes. + +- The **!dq** extension displays ULONG64\_PTR values. These are 32-bit words. The default length is 128 total bytes. + +- The **!du** extension displays UNICODE characters. The default length is 16 characters (32 total bytes), or until a NULL character is encountered. + +- The **!dw** extension displays WORD values. The default length is 64 DWORDs (128 total bytes). + +Consequently, using two of these extensions that are distinct with the same value of *Size* will most likely result in a difference in the total amount of memory displayed. For example, using the command **!db L 32** results in 32 bytes being displayed (as hexadecimal bytes), whereas the command **!dd L 32** results in 128 bytes being displayed (as DWORD values). + +Here is an example in which the caching attribute flag is needed: + +``` +kd> !dc e9000 +physical memory read at e9000 failed +If you know the caching attributes used for the memory, +try specifying [c], [uc] or [wc], as in !dd [c] . +WARNING: Incorrect use of these flags will cause unpredictable +processor corruption. This may immediately (or at any time in +the future until reboot) result in a system hang, incorrect data +being displayed or other strange crashes and corruption. + +kd> !dc [c] e9000 +# e9000 000ea002 000ea002 000ea002 000ea002 ................ +# e9010 000ea002 000ea002 000ea002 000ea002 ................ +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!db,%20!dc,%20!dd,%20!dp,%20!dq,%20!du,%20!dw%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dbgdbg--debug-current-debugger-.md b/windows-driver-docs-pr/debugger/-dbgdbg--debug-current-debugger-.md new file mode 100644 index 0000000000..601323fbd0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dbgdbg--debug-current-debugger-.md @@ -0,0 +1,69 @@ +--- +title: .dbgdbg (Debug Current Debugger) +description: The .dbgdbg command launches a new instance of CDB; this new debugger takes the current debugger as its target. +ms.assetid: a90392b5-d8ae-495d-8074-060e4ec89037 +keywords: [".dbgdbg (Debug Current Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dbgdbg (Debug Current Debugger) +api_type: +- NA +--- + +# .dbgdbg (Debug Current Debugger) + + +The **.dbgdbg** command launches a new instance of CDB; this new debugger takes the current debugger as its target. + +``` +.dbgdbg +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +The **.dbgdbg** command is similar to the [**CTRL+P (Debug Current Debugger)**](ctrl-p--debug-current-debugger-.md) control key. However, **.dbgdbg** is more versatile, because it can be used from WinDbg as well as KD and CDB, and it can be used to debug a debugging server on a remote computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dbgdbg%20%28Debug%20Current%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dbgprint.md b/windows-driver-docs-pr/debugger/-dbgprint.md new file mode 100644 index 0000000000..e6bc0b7f52 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dbgprint.md @@ -0,0 +1,73 @@ +--- +title: dbgprint +description: The dbgprint extension displays a string that was previously sent to the DbgPrint buffer. +ms.assetid: bf25ac2a-5a07-43df-946b-3b2237b1816b +keywords: ["dbgprint Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dbgprint +api_type: +- NA +--- + +# !dbgprint + + +The **!dbgprint** extension displays a string that was previously sent to the **DbgPrint** buffer. + +``` +!dbgprint +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about **DbgPrint**, **KdPrint**, **DbgPrintEx**, and **KdPrintEx**, see [Sending Output to the Debugger](sending-output-to-the-debugger.md). + +Remarks +------- + +The kernel-mode routines **DbgPrint**, **KdPrint**, **DbgPrintEx**, and **KdPrintEx** send a formatted string to a buffer on the target computer. The string is automatically displayed in the Debugger Command window on the host computer unless such printing has been disabled. + +Generally, messages sent to this buffer are displayed automatically in the Debugger Command window. However, this display can be disabled through the Global Flags (gflags.exe) utility. Moreover, this display does not automatically appear during local kernel debugging. For more information, see [The DbgPrint Buffer](reading-and-filtering-debugging-messages.md#the-dbgprint-buffer). + +The **!dbgprint** extension causes the contents of this buffer to be displayed (regardless of whether automatic printing has been disabled). It will not show messages that have been filtered out based on their component and importance level. (For details on this filtering, see [Reading and Filtering Debugging Messages](reading-and-filtering-debugging-messages.md).) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dbgprint%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dblink.md b/windows-driver-docs-pr/debugger/-dblink.md new file mode 100644 index 0000000000..0216ee7b45 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dblink.md @@ -0,0 +1,76 @@ +--- +title: dblink +description: The dblink extension displays a linked list in the backward direction. +ms.assetid: d57b07a6-217b-475e-adf5-7dc0f972c494 +keywords: ["dblink Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dblink +api_type: +- NA +--- + +# !dblink + + +The **!dblink** extension displays a linked list in the backward direction. + +``` +!dblink Address [Count] [Bias] +``` + +## Parameters + + + *Address* +Specifies the address of a LIST\_ENTRY structure. The display will begin with this node. + + *Count* +Specifies the maximum number of list entries to display. If this is omitted, the default is 32. + + *Bias* +Specifies a mask of bits to ignore in each pointer. Each **Blink** address is ANDed with (NOT *Bias*) before following it to the next location. The default is zero (in other words, do not ignore any bits). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The **!dblink** extension traverses the **Blink** fields of the LIST\_ENTRY structure and displays up to four ULONGs at each address. To go in the other direction, use [**!dflink**](-dflink.md). + +The [**dl (Display Linked List)**](dl--display-linked-list-.md) command is more versatile than **!dblink** and [**!dflink**](-dflink.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dblink%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dcr.md b/windows-driver-docs-pr/debugger/-dcr.md new file mode 100644 index 0000000000..fce89204ee --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dcr.md @@ -0,0 +1,109 @@ +--- +title: dcr +description: The dcr extension displays the default control register (DCR) at the specified address. +ms.assetid: 294fc3a9-5182-47ae-a261-53be6389bcf1 +keywords: ["DCR (default control register)", "dcr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dcr +api_type: +- NA +--- + +# !dcr + + +The **!dcr** extension displays the default control register (DCR) at the specified address. + +``` +!dcr Expression [DisplayLevel] +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Expression* +Specifies the hexadecimal address of the DCR to display. The expression **@dcr** can also be used for this parameter. In that case, information about the current processor DCR is displayed. + + *DisplayLevel* +Can be any one of the following options: + +**0** +Causes only the values of each DCR field to be displayed. This is the default value. + +**1** +Causes the display to include more in-depth information about each of the DCR fields that is not reserved or ignored. + +**2** +Causes the display to include more in-depth information about all of the DCR fields, including those that are ignored or reserved. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +Remarks +------- + +The DCR specifies default parameters for the processor status register values on interruption. The DCR also specifies some additional global controls, as well as whether or not speculative load faults can be deferred. + +Here are a couple of examples: + +``` +kd> !dcr @dcr +dcr:pp be lc dm dp dk dx dr da dd +1 0 1 1 1 1 1 1 1 1 + +kd> !dcr @dcr 2 + + pp : 1 : Privileged Performance Monitor Default + be : 0 : Big-Endian Default + lc : 1 : IA-32 Lock check Enable + rv : 0 : reserved1 + dm : 1 : Defer TLB Miss faults only + dp : 1 : Defer Page Not Present faults only + dk : 1 : Defer Key Miss faults only + dx : 1 : Defer Key Permission faults only + dr : 1 : Defer Access Rights faults only + da : 1 : Defer Access Bit faults only + dd : 0 : Defer Debug faults only + rv : 0 : reserved2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dcr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dcs.md b/windows-driver-docs-pr/debugger/-dcs.md new file mode 100644 index 0000000000..c33294e0c4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dcs.md @@ -0,0 +1,29 @@ +--- +title: dcs +description: dcs +ms.assetid: 947adf2d-9596-4260-b500-3169a13741a8 +keywords: ["dcs extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !dcs + + +## + + +The **!dcs** extension is obsolete. To display the PCI configuration space, use [**!pci 100**](-pci.md)*Bus Device Function*. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dcs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-deadlock.md b/windows-driver-docs-pr/debugger/-deadlock.md new file mode 100644 index 0000000000..7b3af52e25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-deadlock.md @@ -0,0 +1,176 @@ +--- +title: deadlock +description: The deadlock extension displays information about deadlocks collected by the Deadlock Detection option of Driver Verifier. +ms.assetid: c0e6074f-8afe-4526-a30f-427aac67ab99 +keywords: ["Deadlock Detection (Driver Verifier)", "deadlock Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- deadlock +api_type: +- NA +--- + +# !deadlock + + +The **!deadlock** extension displays information about deadlocks collected by the **Deadlock Detection** option of Driver Verifier. + +``` +!deadlock +!deadlock 1 +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +This extension will only provide useful information if Driver Verifier's **Deadlock Detection** option has detected a lock hierarchy violation and issued [**bug check 0xC4**](bug-check-0xc4--driver-verifier-detected-violation.md) (DRIVER\_VERIFIER\_DETECTED\_VIOLATION). + +Without any arguments, the **!deadlock** extension causes the basic lock hierarchy topology to be displayed. If the problem is not a simple cyclical deadlock, this command will describe the situation that has occurred. + +The **!deadlock 1** extension causes stack traces to be displayed. The stacks displayed will be the ones active at the time the locks were acquired. + +Here is an example: + +``` +0:kd> !deadlock + +Deadlock detected (2 resources in 2 threads): + +Thread 0: A B +Thread 1: B A + +Where: +Thread 0 = 8d3ba030 +Thread 1 = 8d15c030 +Lock A = bba2af30 Type 'Spinlock' +Lock B = dummy!GlobalLock Type 'Spinlock' +``` + +This tells you which threads and which locks are involved. However, it is intended to be a summary and may not be enough information to adequately debug the situation. + +Use **!deadlock 1** to print out the contents of the call stacks at the time that each lock participating in the deadlock was acquired. Because these are run-time stack traces, they will be more complete if a checked build is being used. On a free build, they may be truncated after as little as one line. + +``` +0:kd> !deadlock 1 + +Deadlock detected (2 resources in 2 threads): + +Thread 0 (8D14F750) took locks in the following order: + + Lock A -- b7906f30 (Spinlock) + Stack: dummy!DummyActivateVcComplete+0x63 + dummy!dummyOpenVcChannels+0x2E1 + dummy!DummyAllocateRecvBufferComplete+0x436 + dummy!DummyAllocateComplete+0x55 + NDIS!ndisMQueuedAllocateSharedHandler+0xC9 + NDIS!ndisWorkerThread+0xEE + + Lock B -- dummy!GlobalLock (Spinlock) + Stack: dummy!dummyQueueRecvBuffers+0x2D + dummy!DummyActivateVcComplete+0x90 + dummy!dummyOpenVcChannels+0x2E1 + dummy!DummyAllocateRecvBufferComplete+0x436 + dummy!DummyAllocateComplete+0x55 + +Thread 1 (8D903030) took locks in the following order: + + Lock B -- dummy!GlobalLock (Spinlock) + Stack: dummy!dummyRxInterruptOnCompletion+0x25D + dummy!DummyHandleInterrupt+0x32F + NDIS!ndisMDpcX+0x3C + ntkrnlpa!KiRetireDpcList+0x5D + + Lock A -- b7906f30 (Spinlock) + Stack: << Current stack >> +``` + +With this information, you have almost everything you need, except the current stack: + +``` +0: kd> k +ChildEBP RetAddr +f78aae6c 80664c58 ntkrnlpa!DbgBreakPoint +f78aae74 8066523f ntkrnlpa!ViDeadlockReportIssue+0x2f +f78aae9c 806665df ntkrnlpa!ViDeadlockAnalyze+0x253 +f78aaee8 8065d944 ntkrnlpa!VfDeadlockAcquireResource+0x20b +f78aaf08 bfd6df46 ntkrnlpa!VerifierKeAcquireSpinLockAtDpcLevel+0x44 +f78aafa4 b1bf2d2d dummy!dummyRxInterruptOnCompletion+0x2b5 +f78aafc4 bfde9d8c dummy!DummyHandleInterrupt+0x32f +f78aafd8 804b393b NDIS!ndisMDpcX+0x3c +f78aaff4 804b922b ntkrnlpa!KiRetireDpcList+0x5d +``` + +From this you can see which locks were involved and where they were acquired. This should be enough information for you to debug the deadlock. If the source code is available, you can use the debugger to see exactly where the problem occurred: + +``` +0: kd> .lines +Line number information will be loaded + +0: kd> u dummy!DummyActivateVcComplete+0x63 l1 +dummy!DummyActivateVcComplete+63 [d:\nt\drivers\dummy\vc.c @ 2711]: +b1bfe6c9 837d0c00 cmp dword ptr [ebp+0xc],0x0 + +0: kd> u dummy!dummyQueueRecvBuffers+0x2D l1 +dummy!dummyQueueRecvBuffers+2d [d:\nt\drivers\dummy\receive.c @ 2894]: +b1bf4e39 807d0c01 cmp byte ptr [ebp+0xc],0x1 + +0: kd> u dummy!dummyRxInterruptOnCompletion+0x25D l1 +dummy!dummyRxInterruptOnCompletion+25d [d:\nt\drivers\dummy\receive.c @ 1424]: +b1bf5d05 85f6 test esi,esi + +0: kd> u dummy!dummyRxInterruptOnCompletion+0x2b5 l1 +dummy!dummyRxInterruptOnCompletion+2b5 [d:\nt\drivers\dummy\receive.c @ 1441]: +b1bf5d5d 8b4648 mov eax,[esi+0x48] +``` + +Now you know the name of the source file and the line number where the acquisition took place. In this case, the source files will show that the threads behaved as follows: + +- Thread 1: **DummyActivateVcComplete** took the **dummy** miniport lock. It then called **dummyQueueRecvBuffers**, which took the **dummy** global lock. + +- Thread 2: **dummyRxInterruptOnCompletion** took the global lock. Then, a few lines later, it took the miniport lock. + +At this point, the deadlock becomes entirely clear. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!deadlock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-defwrites.md b/windows-driver-docs-pr/debugger/-defwrites.md new file mode 100644 index 0000000000..7543b79f37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-defwrites.md @@ -0,0 +1,89 @@ +--- +title: defwrites +description: The defwrites extension displays the values of the kernel variables used by the cache manager. +ms.assetid: da576e05-3d9f-4599-bf8e-b1fa05093d77 +keywords: ["cache manager", "defwrites Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- defwrites +api_type: +- NA +--- + +# !defwrites + + +The **!defwrites** extension displays the values of the kernel variables used by the cache manager. + +``` +!defwrites +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about write throttling, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +For information about other cache management extensions, use the [**!cchelp**](-cchelp.md) extension. + +Remarks +------- + +When the number of deferred writes ("dirty pages") becomes too large, page writing will be throttled. This extension allows you to see whether your system has reached this point. + +Here is an example: + +``` +kd> !defwrites +*** Cache Write Throttle Analysis *** + + CcTotalDirtyPages: 0 ( 0 Kb) + CcDirtyPageThreshold: 1538 ( 6152 Kb) + MmAvailablePages: 2598 ( 10392 Kb) + MmThrottleTop: 250 ( 1000 Kb) + MmThrottleBottom: 30 ( 120 Kb) + MmModifiedPageListHead.Total: 699 ( 2796 Kb) + +Write throttles not engaged +``` + +In this case, there are no dirty pages. If **CcTotalDirtyPages** reaches 1538 (the value of **CcDirtyPageThreshold**), writing will be delayed until the number of dirty pages is reduced. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!defwrites%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-detach--detach-from-process-.md b/windows-driver-docs-pr/debugger/-detach--detach-from-process-.md new file mode 100644 index 0000000000..1ce8dbbebf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-detach--detach-from-process-.md @@ -0,0 +1,87 @@ +--- +title: .detach (Detach from Process) +description: The .detach command ends the debugging session, but leaves any user-mode target application running. +ms.assetid: 4f0fbd8b-3037-4549-99da-be40a091a363 +keywords: [".detach (Detach from Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .detach (Detach from Process) +api_type: +- NA +--- + +# .detach (Detach from Process) + + +The **.detach** command ends the debugging session, but leaves any user-mode target application running. + +``` +.detach [ /h | /n ] +``` + +## Parameters + + + **/h** +Any outstanding debug event will be continued and marked as handled. This is the default. + + **/n** +Any outstanding debug event will be continued without being marked as handled. + +### Environment + +For live user-mode debugging, this command is only supported in Windows XP and later versions of Windows. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +This command will end the debugging session in any of the following scenarios: + +- When you are debugging a user-mode or kernel-mode dump file. + +- (Windows XP and later) When you are debugging a live user-mode target. + +- When you are noninvasively debugging a user-mode target. + +If you are only debugging a single target, the debugger will return to dormant mode after it detaches. + +If you are [debugging multiple targets](debugging-multiple-targets.md), the debugging session will continue with the remaining targets. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.detach%20%28Detach%20from%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-devext.md b/windows-driver-docs-pr/debugger/-devext.md new file mode 100644 index 0000000000..ce847d5315 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-devext.md @@ -0,0 +1,168 @@ +--- +title: devext +description: The devext extension displays bus-specific device extension information for devices on a variety of buses. +ms.assetid: b4d4f595-9b0b-40e2-8790-2c913a50c8fe +keywords: ["usbhub extension (obsolete)", "hidfdo extension (obsolete)", "hidpdo extension (obsolete)", "device extension", "bus", "devext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- devext +api_type: +- NA +--- + +# !devext + + +The **!devext** extension displays bus-specific device extension information for devices on a variety of buses. + +``` +!devext Address TypeCode +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the device extension to be displayed. + + *TypeCode* +Specifies the type of object that owns the device extension to be displayed. Type codes are not case-sensitive. Valid type codes are: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeCodeObject

PCI

(Windows 2000 only) PCI device extension

ISAPNP

ISA PnP device extension

PCMCIA

PCMCIA device extension

HID

HID device extension

USBD

(Windows 2000 only) USB bus driver extension

UHCD

(Windows 2000 only) UHCD host controller extension

OpenHCI

(Windows 2000 only) Open HCI host controller extension

USBHUB

(Windows 2000 only) USB hub extension

MF

(Windows 2000 only) MF device extension

+ +  + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For more information about device extensions, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The **!usbhub**, **!hidfdo**, and **!hidpdo** extensions are obsolete; their functionality has been integrated into **!devext**. + +For those object types that are no longer supported by **!devext**, use the [**dt (Display Type)**](dt--display-type-.md) debugger command. + +Here is an example for an ISA PnP device extension: + +``` +kd> !devext e0000165fff32190 ISAPNP +ISA PnP FDO @ 0x00000000, DevExt @ 0xe0000165fff32190, Bus # 196639 +Flags (0x854e2530) DF_ACTIVATED, DF_QUERY_STOPPED, + DF_STOPPED, DF_RESTARTED_NOMOVE, + DF_BUS + Unknown flags 0x054e2000 + +NumberCSNs - -536870912 +ReadDataPort - 0x0000000d (mapped) +AddressPort - 0x00000000 (not mapped) +CommandPort - 0x00000000 (not mapped) +DeviceList - 0xe000000085007b50 +CardList - 0x00000000 +PhysicalBusDevice - 0x00000000 +AttachedDevice - 0x00000000 +SystemPowerState - Unspecified +DevicePowerState - Unspecified +``` + +Here is an example for a PCI device: + +``` +kd> !devext e0000000858c31b0 PCI +PDO Extension, Bus 0x0, Device 0, Function 0. + DevObj 0xe0000000858c3060 PCI Parent Bus FDO DevExt 0xe0000000858c4960 + Device State = PciNotStarted + Vendor ID 8086 (INTEL) Device ID 123D + Class Base/Sub 08/00 (Base System Device/Interrupt Controller) + Programming Interface: 20, Revision: 01, IntPin: 00, Line Raw/Adj 00/00 + Enables ((cmd & 7) = 106): BM Capabilities Pointer = + CurrentState: System Working, Device D0 + WakeLevel: System Unspecified, Device Unspecified + Requirements: +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!devext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-devhandles.md b/windows-driver-docs-pr/debugger/-devhandles.md new file mode 100644 index 0000000000..3468839437 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-devhandles.md @@ -0,0 +1,90 @@ +--- +title: devhandles +description: The devhandles extension displays the open handles for the specified device. +ms.assetid: a473dd58-1571-4969-b8b7-f7a71128d824 +keywords: ["devhandles Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- devhandles +api_type: +- NA +--- + +# !devhandles + + +The **!devhandles** extension displays the open handles for the specified device. + +``` +!devhandles Address +``` + +## Parameters + + + *Address* +Specifies the address of the device for which to display the open handles. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +To display complete handle information, this extension requires private symbols. + +The address of a device object can be obtained using the [**!drvobj**](-drvobj.md) or [**!devnode**](-devnode.md) extensions. + +Here is a truncated example: + +``` +lkd> !devhandles 0x841153d8 + +Checking handle table for process 0x840d3940 +Handle table at 95fea000 with 578 Entries in use + +Checking handle table for process 0x86951d90 +Handle table at 8a8ef000 with 28 Entries in use + +... + +Checking handle table for process 0x87e63650 +Handle table at 947bc000 with 308 Entries in use + +Checking handle table for process 0x87e6f4f0 +00000000: Unable to read handle table +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!devhandles%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-devnode.md b/windows-driver-docs-pr/debugger/-devnode.md new file mode 100644 index 0000000000..d7fcebd8c5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-devnode.md @@ -0,0 +1,102 @@ +--- +title: devnode +description: The devnode extension displays information about a node in the device tree. +ms.assetid: 0c8cb743-f756-461e-b92b-352b550706c1 +keywords: ["device node", "device tree", "devnode Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- devnode +api_type: +- NA +--- + +# !devnode + + +The **!devnode** extension displays information about a node in the device tree. + +``` +!devnode Address [Flags] [Service] +!devnode 1 +!devnode 2 +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the device extension whose node is to be displayed. If this is zero, the root of the main device tree is displayed. + + *Flags* +Specifies the level of output to be displayed. This can be any combination of the following bits: + +Bit 0 (0x1) +Causes the display to include all children of the device node. + +Bit 1 (0x2) +Causes the display to include resources used (CM\_RESOURCE\_LIST). These include the boot configuration reported by IRP\_MN\_QUERY\_RESOURCES, as well as the resources allocated to the device in the *AllocatedResources* parameter of IRP\_MN\_START\_DEVICE. + +Bit 2 (0x4) +Causes the display to include resources required (IO\_RESOURCE\_REQUIREMENTS\_LIST) as reported by IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS. + +Bit 3 (0x8) +Causes the display to include a list of translated resources as allocated to the device in the *AllocatedResourcesTranslated* parameter of IRP\_MN\_START\_DEVICE. + +Bit 4 (0x10) +Specifies that only device nodes that are not started should be displayed. + +Bit 5 (0x20) +Specifies that only device nodes with problems should be displayed. (These are nodes that contain the flag bits DNF\_HAS\_PROBLEM or DNF\_HAS\_PRIVATE\_PROBLEM.) + + *Service* +Specifies the name of a service. If this is included, only those device nodes driven by this service will be displayed. (If *Flags* includes bit 0x1, device nodes driven by this service and all their children will be displayed.) + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about device trees, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The **!devnode 1** command lists all pending removals of device objects. + +The **!devnode 2** command lists all pending ejects of device objects. + +You can use **!devnode 0 1** to see the entire device tree. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!devnode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-devobj.md b/windows-driver-docs-pr/debugger/-devobj.md new file mode 100644 index 0000000000..7486c08136 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-devobj.md @@ -0,0 +1,107 @@ +--- +title: devobj +description: The devobj extension displays detailed information about a DEVICE_OBJECT structure. +ms.assetid: cf722d95-fbd3-4d80-8679-f8fb348ab4b0 +keywords: ["devobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- devobj +api_type: +- NA +--- + +# !devobj + + +The **!devobj** extension displays detailed information about a DEVICE\_OBJECT structure. + +``` +!devobj DeviceObject +``` + +## Parameters + + + *DeviceObject* +Specifies the device object. This can be the hexadecimal address of this structure or the name of the device. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for examples and applications of this extension command. For information about device objects, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +If *DeviceObject* specifies the name of the device but supplies no prefix, the prefix "\\Device\\" is assumed. Note that this command will check to see if *DeviceObject* is a valid address or device name before using the expression evaluator. + +The information displayed includes the device name of the object, information about the device's current IRP, and a list of addresses of any pending IRPs in the device's queue. It also includes information about device objects layered on top of this object (listed as "AttachedDevice") and those layered under this object (listed as "AttachedTo"). + +The address of a device object can be obtained using the [**!drvobj**](-drvobj.md) or [**!devnode**](-devnode.md) extensions. + +Here is one example: + +``` +kd> !devnode +Dumping IopRootDeviceNode (= 0x80e203b8) +DevNode 0x80e203b8 for PDO 0x80e204f8 + Parent 0000000000 Sibling 0000000000 Child 0x80e56dc8 + InstancePath is "HTREE\ROOT\0" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[04] = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[03] = DeviceNodeStarted (0x308) + StateHistory[02] = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[01] = DeviceNodeStarted (0x308) + StateHistory[00] = DeviceNodeUninitialized (0x301) + StateHistory[19] = Unknown State (0x0) + ..... + StateHistory[05] = Unknown State (0x0) + Flags (0x00000131) DNF_MADEUP, DNF_ENUMERATED, + DNF_IDS_QUERIED, DNF_NO_RESOURCE_REQUIRED + DisableableDepends = 11 (from children) + +kd> !devobj 80e204f8 +Device object (80e204f8) is for: + \Driver\PnpManager DriverObject 80e20610 +Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001000 +DevExt 80e205b0 DevObjExt 80e205b8 DevNode 80e203b8 +ExtensionFlags (0000000000) +Device queue is not busy. +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!devobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-devstack.md b/windows-driver-docs-pr/debugger/-devstack.md new file mode 100644 index 0000000000..c7f7b60239 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-devstack.md @@ -0,0 +1,84 @@ +--- +title: devstack +description: The devstack extension displays a formatted view of the device stack associated with a device object. +ms.assetid: 2215f166-2053-4525-80cd-be3817510dbd +keywords: ["devstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- devstack +api_type: +- NA +--- + +# !devstack + + +The **!devstack** extension displays a formatted view of the device stack associated with a device object. + +``` +!devstack DeviceObject +``` + +## Parameters + + + *DeviceObject* +Specifies the device object. This can be the hexadecimal address of the DEVICE\_OBJECT structure or the name of the device. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about device stacks, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +If *DeviceObject* specifies the name of the device but supplies no prefix, the prefix "\\Device\\" is assumed. Note that this command will check to see if *DeviceObject* is a valid address or device name before using the expression evaluator. + +Here is an example: + +``` +kd> !devstack e000000085007b50 + !DevObj !DrvObj !DevExt ObjectName + e0000165fff32040 \Driver\kmixer e0000165fff32190 +> e000000085007b50 \Driver\swenum e000000085007ca0 KSENUM#00000005 +!DevNode e0000165fff2e010 : + DeviceInst is "SW\{b7eafdc0-a680-11d0-96d8-00aa0051e51d}\{9B365890-165F-11D0-A195-0020AFD156E4}" + ServiceName is "kmixer" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!devstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dflink.md b/windows-driver-docs-pr/debugger/-dflink.md new file mode 100644 index 0000000000..33cf9d2021 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dflink.md @@ -0,0 +1,76 @@ +--- +title: dflink +description: The dflink extension displays a linked list in the forward direction. +ms.assetid: b75a01f6-557c-4602-83fa-629e16ba8c5d +keywords: ["dflink Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dflink +api_type: +- NA +--- + +# !dflink + + +The **!dflink** extension displays a linked list in the forward direction. + +``` +!dflink Address [Count] [Bias] +``` + +## Parameters + + + *Address* +Specifies the address of a LIST\_ENTRY structure. The display will begin with this node. + + *Count* +Specifies the maximum number of list entries to display. If this is omitted, the default is 32. + + *Bias* +Specifies a mask of bits to ignore in each pointer. Each **Flink** address is ANDed with (NOT *Bias*) before following it to the next location. The default is zero (in other words, do not ignore any bits). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The **!dflink** extension traverses the **Flink** fields of the LIST\_ENTRY structure and displays up to four ULONGs at each address. To go in the other direction, use [**!dblink**](-dblink.md). + +The [**dl (Display Linked List)**](dl--display-linked-list-.md) command is more versatile than [**!dblink**](-dblink.md) and **!dflink**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dflink%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dh.md b/windows-driver-docs-pr/debugger/-dh.md new file mode 100644 index 0000000000..98442768c3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dh.md @@ -0,0 +1,87 @@ +--- +title: dh +description: The dh extension displays the headers for the specified image. +ms.assetid: 1b4f94ae-42cc-4381-a2d1-c2f248e4d5a6 +keywords: ["NTFS file object", "dh Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dh +api_type: +- NA +--- + +# !dh + + +The **!dh** extension displays the headers for the specified image. + +``` +!dh [Options] Address +!dh -h +``` + +## Parameters + + + *Options* +Any one of the following options: + +**-f** +Displays file headers. + +**-s** +Displays section headers. + +**-a** +Displays all header information. + + *Address* +Specifies the hexadecimal address of the image. + + **-h** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Dbghelp.dll +Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Dbghelp.dll

+ +  + +Remarks +------- + +The [**!lmi**](-lmi.md) extension extracts the most important information from the image header and displays it in a concise summary format. That extension is frequently more useful than **!dh**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dh%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-diskspace.md b/windows-driver-docs-pr/debugger/-diskspace.md new file mode 100644 index 0000000000..b03144f690 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-diskspace.md @@ -0,0 +1,82 @@ +--- +title: diskspace +description: The diskspace extension displays the amount of free space on a hard disk of the target computer. +ms.assetid: 9153cdc0-addf-4804-a898-1e4280ac60ea +keywords: ["diskspace Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- diskspace +api_type: +- NA +--- + +# !diskspace + + +The **!diskspace** extension displays the amount of free space on a hard disk of the target computer. + +``` +!diskspace Drive[:] +``` + +## Parameters + + + *Drive* +Specifies the drive letter of the disk. The colon (:) after *Drive* is optional. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kext.dll

Windows XP and later

Kext.dll

+ +  + +Remarks +------- + +Here is an example: + +``` +kd> !diskspace c: +Checking Free Space for c: .......... + Cluster Size 0 KB + Total Clusters 4192901 KB + Free Clusters 1350795 KB + Total Space 1 GB (2096450 KB) + Free Space 659.567871 MB (675397 KB) + +kd> !diskspace f: +Checking Free Space for f: +f: is a CDROM drive. This function is not supported! +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!diskspace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dlls.md b/windows-driver-docs-pr/debugger/-dlls.md new file mode 100644 index 0000000000..6c890e466e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dlls.md @@ -0,0 +1,236 @@ +--- +title: dlls +description: The dlls extension displays the table entries of all loaded modules or all modules that a specified thread or process are using. +ms.assetid: a47ec828-ba5a-4f0d-be85-18633c4e4185 +keywords: ["DLL table entry", "dlls Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dlls +api_type: +- NA +--- + +# !dlls + + +The **!dlls** extension displays the table entries of all loaded modules or all modules that a specified thread or process are using. + +``` +!dlls [Options] [LoaderEntryAddress] +!dlls -h +``` + +## Parameters + + + *Options* +Specifies the level of output. This parameter can be any combination of the following values: + +**-f** +Displays file headers. + +**-s** +Displays section headers. + +**-a** +Displays complete module information. (This option is equivalent to -f -s.) + +**-c** **** *ModuleAddress* +Displays the module that contains *ModuleAddress*. + +**-i** +Sorts the display by initialization order. + +**-l** +Sorts the display by load order. This situation is the default. + +**-m** +Sorts the display by memory order. + +**-v** +(Windows XP and later) Displays version information. This information is taken from the resource section of each module. + + *LoaderEntryAddress* +Specifies the address of the loader entry for a module. If you include this parameter, the debugger displays only this specific module. + + **-h** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Exts.dll

+ +  + +Remarks +------- + +The module listing includes all entry points into each module. + +The **.dlls** extension works only in live debugging (not with crash dump analysis). + +In kernel mode, this extension displays the modules for the current [process context](changing-contexts.md#process-context). You cannot use **!dlls** together with a system process or the idle process. + +The following examples shows you how to use the **!dlls** extension. + +``` +kd> !dlls -c 77f60000 +Dump dll containing 0x77f60000: + +0x00091f38: E:\WINDOWS\System32\ntdll.dll + Base 0x77f60000 EntryPoint 0x00000000 Size 0x00097000 + Flags 0x00004004 LoadCount 0x0000ffff TlsIndex 0x00000000 + LDRP_IMAGE_DLL + LDRP_ENTRY_PROCESSED + +kd> !dlls -a 91ec0 + +0x00091ec0: E:\WINDOWS\system32\winmine.exe + Base 0x01000000 EntryPoint 0x01003e2e Size 0x00020000 + Flags 0x00005000 LoadCount 0x0000ffff TlsIndex 0x00000000 + LDRP_LOAD_IN_PROGRESS + LDRP_ENTRY_PROCESSED + +File Type: EXECUTABLE IMAGE +FILE HEADER VALUES + 14C machine (i386) + 3 number of sections +3A98E856 time date stamp Sun Feb 25 03:11:18 2001 + + 0 file pointer to symbol table + 0 number of symbols + E0 size of optional header + 10F characteristics + Relocations stripped + Executable + Line numbers stripped + Symbols stripped + 32 bit word machine + +OPTIONAL HEADER VALUES + 10B magic # + 7.00 linker version + 3A00 size of code + 19E00 size of initialized data + 0 size of uninitialized data + 3E2E address of entry point + 1000 base of code + ----- new ----- +01000000 image base + 1000 section alignment + 200 file alignment + 2 subsystem (Windows GUI) + 5.01 operating system version + 5.01 image version + 4.00 subsystem version + 20000 size of image + 400 size of headers + 21970 checksum +00040000 size of stack reserve +00001000 size of stack commit +00100000 size of heap reserve +00001000 size of heap commit +01000100 Opt Hdr + 0 [ 0] address [size] of Export Directory + 40B4 [ B4] address [size] of Import Directory + 6000 [ 19170] address [size] of Resource Directory + 0 [ 0] address [size] of Exception Directory + 0 [ 0] address [size] of Security Directory + 0 [ 0] address [size] of Base Relocation Directory + 11B0 [ 1C] address [size] of Debug Directory + 0 [ 0] address [size] of Description Directory + 0 [ 0] address [size] of Special Directory + 0 [ 0] address [size] of Thread Storage Directory + 0 [ 0] address [size] of Load Configuration Directory + 258 [ A8] address [size] of Bound Import Directory + 1000 [ 1B0] address [size] of Import Address Table Directory + 0 [ 0] address [size] of Reserved Directory + 0 [ 0] address [size] of Reserved Directory + 0 [ 0] address [size] of Reserved Directory + + +SECTION HEADER #1 + .text name + 3992 virtual size + 1000 virtual address + 3A00 size of raw data + 400 file pointer to raw data + 0 file pointer to relocation table + 0 file pointer to line numbers + 0 number of relocations + 0 number of line numbers +60000020 flags + Code + (no align specified) + Execute Read + + +Debug Directories(1) + Type Size Address Pointer + + cv 1c 13d0 7d0 Format: NB10, 3a98e856, 1, winmi +ne.pdb + +SECTION HEADER #2 + .data name + BB8 virtual size + 5000 virtual address + 200 size of raw data + 3E00 file pointer to raw data + 0 file pointer to relocation table + 0 file pointer to line numbers + 0 number of relocations + 0 number of line numbers +C0000040 flags + Initialized Data + (no align specified) + Read Write + +SECTION HEADER #3 + .rsrc name + 19170 virtual size + 6000 virtual address + 19200 size of raw data + 4000 file pointer to raw data + 0 file pointer to relocation table + 0 file pointer to line numbers + 0 number of relocations + 0 number of line numbers +40000040 flags + Initialized Data + (no align specified) + Read Only +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dlls%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dma.md b/windows-driver-docs-pr/debugger/-dma.md new file mode 100644 index 0000000000..8be8c5bc4c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dma.md @@ -0,0 +1,191 @@ +--- +title: dma +description: The dma extension displays information about the Direct Memory Access (DMA) subsystem, and the DMA Verifier option of Driver Verifier. +ms.assetid: 4ccf679f-5804-4644-935a-18ff8711ae9a +keywords: ["DMA Verification (Driver Verifier)", "dma Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dma +api_type: +- NA +--- + +# !dma + + +The **!dma** extension displays information about the Direct Memory Access (DMA) subsystem, and the **DMA Verifier** option of Driver Verifier. + +``` +!dma +!dma Adapter [Flags] +``` + +## Parameters + + + *Adapter* +Specifies the hexadecimal address of the DMA adapter to be displayed. If this is zero, all DMA adapters will be displayed. + + *Flags* +Specifies the information to include in the display. This can be any combination of the following bits. The default is 0x1. + +Bit 0 (0x1) +Causes the display to include generic adapter information. + +Bit 1 (0x2) +Causes the display to include map register information. (Only when DMA Verification is active.) + +Bit 2 (0x4) +Causes the display to include common buffer information. (Only when DMA Verification is active.) + +Bit 3 (0x8) +Causes the display to include scatter/gather list information. (Only when DMA Verification is active.) + +Bit 4 (0x10) +Causes the display to include the device description for the hardware device. (Only when DMA Verification is active.) + +Bit 5 (0x20) +Causes the display to include Wait context block information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation. For information about DMA, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Invalid arguments (for example, **!dma 1**) generate a brief help text. + +When the **!dma** extension is used with no parameters, it displays a concise list of all DMA adapters and their addresses. This can be used to obtain the address of an adapter for use in the longer versions of this command. + +Here is an example of how this extension can be used when the Driver Verifier's **DMA Verification** option is active: + +``` +0:kd> !dma + +Dumping all DMA adapters... + +Adapter: 82faebd0 Owner: SCSIPORT!ScsiPortGetUncachedExtension +Adapter: 82f88930 Owner: SCSIPORT!ScsiPortGetUncachedExtension +Adapter: 82f06cd0 Owner: NDIS!NdisMAllocateMapRegisters +Master adapter: 80076800 +``` + +From this output, you can see that there are three DMA adapters in the system. SCSIPORT owns two and NDIS owns the third. To examine the NDIS adapter in detail, use the **!dma** extension with its address: + +``` +0:kd> !dma 82f06cd0 +Adapter: 82f06cd0 Owner: NDIS!NdisMAllocateMapRegisters (0x9fe24351) + MasterAdapter: 00000000 + Adapter base Va 00000000 + Map register base: 00000000 + WCB: 82f2b604 + Map registers: 00000000 mapped, 00000000 allocated, 00000002 max + + Dma verifier additional information: + DeviceObject: 82f98690 + Map registers: 00000840 allocated, 00000000 freed + Scatter-gather lists: 00000000 allocated, 00000000 freed + Common buffers: 00000004 allocated, 00000000 freed + Adapter channels: 00000420 allocated, 00000420 freed + Bytes mapped since last flush: 000000f2 +``` + +The first block of data is specific information that a HAL developer can use to debug the problem. For your purposes, the data below "Dma verifier additional information" is what is interesting. In this example, you see that NDIS has allocated 0x840 map registers. This is a huge number, especially because NDIS had indicated that it planned to use a maximum of two map registers. This adapter apparently does not use scatter/gather lists and has put away all its adapter channels. Look at the map registers in more detail: + +``` +0:kd> !dma 82f06cd0 2 +Adapter: 82f06cd0 Owner: NDIS!NdisMAllocateMapRegisters +... + + Map register file 82f06c58 (0/2 mapped) + Double buffer mdl: 82f2c188 + Map registers: + 82f06c80: Not mapped + 82f06c8c: Not mapped + + Map register file 82f06228 (1/2 mapped) + Double buffer mdl: 82f1b678 + Map registers: + 82f06250: 00bc bytes mapped to f83c003c + 82f0625c: Not mapped + + Map register file 82fa5ad8 (1/2 mapped) + Double buffer mdl: 82f1b048 + Map registers: + 82fa5b00: 0036 bytes mapped to 82d17102 + 82fa5b0c: Not mapped +... +``` + +In this example, you see that certain map registers have been mapped. Each *map register file* is an allocation of map registers by the driver. In other words, it represents a single call to **AllocateAdapterChannel**. NDIS collects a large number of these map register files, while some drivers create them one at a time and dispose of them when they are finished. + +The map register files are also the addresses that are returned to the device under the name "MapRegisterBase". Note that DMA verifier only hooks the first 64 map registers for each driver. The rest are ignored for reasons of space (each map register represents three physical pages). + +In this example, two map register files are in use. This means that the driver has mapped a buffer so it is visible to the hardware. In the first case, 0xBC bytes are mapped to the system virtual address 0xF83C003C. + +An examination of the common buffers reveals: + +``` +0:kd> !dma 82f06cd0 4 +Adapter: 82f06cd0 Owner: NDIS!NdisMAllocateMapRegisters +... + Common buffer allocated by NDIS!NdisMAllocateSharedMemory: + Length: 1000 + Virtual address: 82e77000 + Physical address: 2a77000 + + Common buffer allocated by NDIS!NdisMAllocateSharedMemory: + Length: 12010 + Virtual address: 82e817f8 + Physical address: 2a817f8 + + Common buffer allocated by NDIS!NdisMAllocateSharedMemory: + Length: 4300 + Virtual address: 82e95680 + Physical address: 2a95680 + + Common buffer allocated by NDIS!NdisMAllocateSharedMemory: + Length: 4800 + Virtual address: 82e9d400 + Physical address: 2a9d400 +``` + +This is fairly straightforward; there are four common buffers of varying lengths. The physical and virtual addresses are all given. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dma%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dml-flow.md b/windows-driver-docs-pr/debugger/-dml-flow.md new file mode 100644 index 0000000000..cd9e39f9ba --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dml-flow.md @@ -0,0 +1,81 @@ +--- +title: .dml_flow (Unasemmble with Links) +description: The .dml_flow command displays a disassembled code block and provides links that you can use to construct a code flow graph. +ms.assetid: 32B50228-05A5-4BA7-88B1-54D4E502EB85 +keywords: [".dml_flow (Unasemmble with Links) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dml_flow (Unasemmble with Links) +api_type: +- NA +--- + +# .dml\_flow (Unasemmble with Links) + + +The **.dml\_flow** command displays a disassembled code block and provides links that you can use to construct a code flow graph. + +``` +.dml_flow Start Target +``` + +## Parameters + + +*Start* +The address of an instruction from which the target address can be reached. + +*Target* +An address in the code block to be disassembled. + +Remarks +------- + +Consider the call stack shown in the following example. + +``` +0: kd> kL +Child-SP RetAddr Call Site +fffff880`0335c688 fffff800`01b41f1c nt!IofCallDriver +fffff880`0335c690 fffff800`01b3b6b4 nt!IoSynchronousPageWrite+0x1cc +fffff880`0335c700 fffff800`01b4195e nt!MiFlushSectionInternal+0x9b8 +... +``` + +Suppose you want to examine all code paths from the start of **nt!MiFlushSectionInternal** to the code block that contains the return adress, `` fffff800`01b3b6b4 ``. The following command gets you started. + +``` +.browse .dml_flow nt!MiFlushSectionInternal fffff800`01b3b6b4 +``` + +The output, in the [Command Browser window](command-browser-window.md), is shown in the following image. + +![screen shot of .dml\-flow output](images/dmlflow01.png) + +The preceding image shows the code block that contains the target address, `` fffff800`01b3b6b4 ``. There is only one link (`` fffff800`01b3b681 ``) at the top of the image. That indicates that there is only one code block from which the current code block can be reached. If you click the link, you will see that code block disassembled, and you will see links that enable you to further explore the code flow graph. + +The two links at the bottom of the preceding image indicate that there are two code blocks that can be reached from the current code block. + +## See also + + +[Debugger Markup Language Commands](debugger-markup-language-commands.md) + +[**uf (Unasemmble Function)**](uf--unassemble-function-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dml_flow%20%28Unasemmble%20with%20Links%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-dml-proc.md b/windows-driver-docs-pr/debugger/-dml-proc.md new file mode 100644 index 0000000000..5dc1538c3b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dml-proc.md @@ -0,0 +1,55 @@ +--- +title: dml_proc +description: The dml_proc extension displays a list of processes and provides links for obtaining more detailed information about processes. +ms.assetid: 35B5B2E7-07CE-4F44-819D-9B7C76273F9A +keywords: ["dml_proc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dml_proc +api_type: +- NA +--- + +# !dml\_proc + + +The **!dml\_proc** extension displays a list of processes and provides links for obtaining more detailed information about processes. + +``` +!dml_proc +``` + +Remarks +------- + +The following image shows a portion of the output displayed by **!dml\_proc**. + +![screen shot of !dml\-proc output](images/dmlproc01.png) + +In the preceding output, the process addresses are links that you can click to see more detailed information. For example, if you click **fffffa80\`04e2b700** (the address for mobsync.exe), you will see detailed information about the mobsync.exe process as shown in the following image. + +![screen shot of process details](images/dmlproc02.png) + +The preceding output, which describes an individual process, contains links that you can click to explore the process and its threads in more detail. + +## See also + + +[Debugger Markup Language Commands](debugger-markup-language-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dml_proc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-dml-start.md b/windows-driver-docs-pr/debugger/-dml-start.md new file mode 100644 index 0000000000..e3d00ec7a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dml-start.md @@ -0,0 +1,91 @@ +--- +title: .dml_start (Display DML Starting Point) +description: The .dml_start command displays output that serves as a starting point for exploration using commands that support Debugger Markup Language (DML). +ms.assetid: 1CFCACDC-B253-4E9B-9877-EE9F1E91395F +keywords: [".dml_start (Display DML Starting Point) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dml_start (Display DML Starting Point) +api_type: +- NA +--- + +# .dml\_start (Display DML Starting Point) + + +The **.dml\_start** command displays output that serves as a starting point for exploration using commands that support [Debugger Markup Language](debugger-markup-language-commands.md) (DML). + +``` +.dml_start +.dml_start filename +``` + +## Parameters + + +*filename* +The name of a DML file to be displayed as the starting output. + +## Using the Default Starting Output + + +If *filename* is omitted, the debugger displays a default DML starting output as illustrated in the following image. + +![screen shot of .dml\-start output](images/dmlstart01.png) + +Each line of output in the preceding example is a link that you can click to invoke other commands. + +## Providing a DML File + + +If you supply a path to a DML file, the file is used as the starting output. For example, suppose the file c:\\MyFavoriteCommands.txt contains the following text and DML tags. + +``` +Display all device nodes. + !devnode 0 1 + +Display all device nodes that are driven by a specified service. +Include child nodes in the display. + !devnode 0 1 ServiceName + Example: !devnode 0 1 usbehci + +Explore device stacks, device objects, and driver objects. + !devstack List the device objects in a device stack. + !devobj Display information about a device object. + !drvobj Display information about a driver object. +``` + +The command **.dml\_start c:\\MyFavoriteCommands.txt** will display the file as shown in the following image. + +![screen shot of dml file output](images/dmlstart02.png) + +Remarks +------- + +For information about DML tags that can be used in DML files, see dml.doc in the installation folder for Debugging Tools for Windows. + +DML output often works well in the [Command Browser window](command-browser-window.md). To display a DML file in the Command Browser window, use **.browse .dml\_start** *filename*. + +## See also + + +[Debugger Markup Language Commands](debugger-markup-language-commands.md) + +[**.browse**](-browse--display-command-in-browser-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dml_start%20%28Display%20DML%20Starting%20Point%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-do.md b/windows-driver-docs-pr/debugger/-do.md new file mode 100644 index 0000000000..c98f667c12 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-do.md @@ -0,0 +1,54 @@ +--- +title: .do +description: The .do token behaves like the do keyword in C, except that the word "while" is not used before the condition. +ms.assetid: 254413bd-7fa5-4401-b242-470f9c0cf11a +keywords: [".do Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .do +api_type: +- NA +--- + +# .do + + +The **.do** token behaves like the **do** keyword in C, except that the word "while" is not used before the condition. + +``` +.do { Commands } (Condition) +``` + +## Syntax Elements + + + *Commands* +Specifies one or more commands that will be executed repeatedly as long as the condition is true -- but will always be executed at least once. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + + *Condition* +Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing *Condition* in parentheses is optional. *Condition* must be an expression, not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The [**.break**](https://msdn.microsoft.com/library/windows/hardware/ff556242) and [**.continue**](-continue.md) tokens can be used to exit or restart the *Commands* block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.do%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dp---ntsdexts-dp-.md b/windows-driver-docs-pr/debugger/-dp---ntsdexts-dp-.md new file mode 100644 index 0000000000..fc19e5f304 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dp---ntsdexts-dp-.md @@ -0,0 +1,84 @@ +--- +title: dp ( ntsdexts.dp) +description: The dp extension in Ntsdexts.dll displays a CSR process. +ms.assetid: 9e489cfc-2105-4605-b94d-88eea7883420 +keywords: ["dp ( ntsdexts.dp) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dp ( ntsdexts.dp) +api_type: +- NA +--- + +# !dp (!ntsdexts.dp) + + +The **!dp** extension in Ntsdexts.dll displays a CSR process. + +This extension command should not be confused with the [**dp (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command, or with the [**!kdext\*.dp**](-db---dc---dd---dp---dq---du---dw.md) extension command. + +``` +!dp [v] [ PID | CSR-Process ] +``` + +## Parameters + + + **v** +Verbose mode. Causes the display to include structure and thread list. + + *PID* +Specifies the process ID of the CSR process. + + *CSR-Process* +Specifies the hexadecimal address of the CSR process. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +Remarks +------- + +This extension displays the process address, process ID, sequence number, flags, and reference count. If verbose mode is selected, additional details are displayed, and thread information is shown for each process. + +If no process is specified, all processes are displayed. + +## See also + + +[**!dt**](-dt.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dp%20%28!ntsdexts.dp%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-dpa.md b/windows-driver-docs-pr/debugger/-dpa.md new file mode 100644 index 0000000000..1958173e9d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dpa.md @@ -0,0 +1,90 @@ +--- +title: dpa +description: The dpa extension displays pool allocation information. +ms.assetid: 1eb31741-bc50-4188-823d-b6324d2dfdf1 +keywords: ["pool allocation", "dpa Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dpa +api_type: +- NA +--- + +# !dpa + + +The **!dpa** extension displays pool allocation information. + +``` +!dpa Options +!dpa -? +``` + +## Parameters + + + *Options* +Must be exactly one of the following options: + +**-c** +Displays current pool allocation statistics. + +**-v** +Displays all current pool allocations. + +**-vs** +Causes the display to include stack traces. + +**-f** +Displays failed pool allocations. + +**-r** +Displays free pool allocations. + +**-p** **** *Ptr* +Displays all pool allocations that contain the pointer *Ptr*. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Pool instrumentation must be enabled in Win32k.sys in order for this extension to work. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dpa%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dpcs.md b/windows-driver-docs-pr/debugger/-dpcs.md new file mode 100644 index 0000000000..6a8513ed00 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dpcs.md @@ -0,0 +1,71 @@ +--- +title: dpcs +description: The dpcs extension displays the deferred procedure call (DPC) queues for a specified processor. +ms.assetid: b5f71fb5-6fc7-4e8f-a439-1edb188e9876 +keywords: ["DPC (deferred procedure call)", "dpcs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dpcs +api_type: +- NA +--- + +# !dpcs + + +The **!dpcs** extension displays the deferred procedure call (DPC) queues for a specified processor. + +``` +!dpcs [Processor] +``` + +## Parameters + + + *Processor* +Specifies a processor. If *Processor* is omitted, then the DPC queues for all processors are displayed. + +### DLL + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Server 2003 and later

Kdexts.dll

+ +  + +### Additional Information + +For information about DPCs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dpcs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dreg.md b/windows-driver-docs-pr/debugger/-dreg.md new file mode 100644 index 0000000000..668e1a5713 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dreg.md @@ -0,0 +1,122 @@ +--- +title: dreg +description: The dreg extension displays registry information. +ms.assetid: a54ed14e-eb9d-48fd-877d-d6d0fe4a8d3f +keywords: ["dreg Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dreg +api_type: +- NA +--- + +# !dreg + + +The **!dreg** extension displays registry information. + +``` +!dreg [-d|-w] KeyPath[!Value] +!dreg +``` + +## Parameters + + + **-d** +Causes binary values to be displayed as DWORDs. + + **-w** +Causes binary values to be displayed as WORDs. + + *KeyPath* +Specifies the registry key path. It can begin with any of the following abbreviations: + +**hklm** +HKEY\_LOCAL\_MACHINE + +**hkcu** +HKEY\_CURRENT\_USER + +**hkcr** +HKEY\_CLASSES\_ROOT + +**hku** +HKEY\_USERS + +If no abbreviation is used, HKEY\_LOCAL\_MACHINE is assumed. + + *Value* +Specifies the name of the registry value to be displayed. If an asterisk (\*) is used, all values are displayed. If *Value* is omitted, all subkeys are displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +### Additional Information + +For information about the registry, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The **!dreg** extension can be used to display the registry during user-mode debugging. + +It is most useful during remote debugging, as it allows you to browse the registry of the remote machine. It is also useful when controlling the user-mode debugger from the kernel debugger, because you cannot run a standard registry editor on the target machine when it is frozen. (You can use the [**.sleep**](-sleep--pause-debugger-.md) command for this purpose as well. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details.) + +It is also useful when debugging locally, as the information is presented in an easily readable format. + +If **!dreg** is used during kernel-mode debugging, the results shown will be for the host computer, and not the target computer. To display raw registry information for the target computer, use the [**!reg**](-reg.md) extension instead. + +Here are some examples. The following will display all subkeys of the specified registry key: + +``` +!dreg hkcu\Software\Microsoft +``` + +The following will display all values in the specified registry key: + +``` +!dreg System\CurrentControlSet\Services\Tcpip!* +``` + +The following will display the value Start in the specified registry key: + +``` +!dreg System\CurrentControlSet\Services\Tcpip!Start +``` + +Typing **!dreg** without any arguments will display some brief Help text for this extension in the Debugger Command window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dreg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-driveinfo.md b/windows-driver-docs-pr/debugger/-driveinfo.md new file mode 100644 index 0000000000..f80f63d870 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-driveinfo.md @@ -0,0 +1,85 @@ +--- +title: driveinfo +description: The driveinfo extension displays volume information for the specified drive. +ms.assetid: cc63c07a-4556-4b79-9dff-c0ac09371651 +keywords: ["driveinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- driveinfo +api_type: +- NA +--- + +# !driveinfo + + +The **!driveinfo** extension displays volume information for the specified drive. + +``` +!driveinfo Drive[:] +!driveinfo +``` + +## Parameters + + + *Drive* +Specifies a drive. The colon at the end of the drive name is optional. + + *No parameters* +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The drive information displayed by this extension is obtained by querying the underlying file system; for example: + +``` +kd> !driveinfo c: +Drive c:, DriveObject e136cd88 + Directory Object: e1001408 Name: C: + Target String is '\Device\HarddiskVolume1' + Drive Letter Index is 3 (C:) + Volume DevObj: 82254a68 + Vpb: 822549e0 DeviceObject: 82270718 + FileSystem: \FileSystem\Ntfs + Volume has 0x229236 (free) / 0x2ee1a7 (total) clusters of size 0x1000 + 8850.21 of 12001.7 MB free +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!driveinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-drivers.md b/windows-driver-docs-pr/debugger/-drivers.md new file mode 100644 index 0000000000..a2dd33b40f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-drivers.md @@ -0,0 +1,145 @@ +--- +title: drivers +description: In Windows XP and later versions of Windows, the drivers extension is obsolete. Instead use the lm command. +ms.assetid: 48b69af3-bf00-43d3-ac1a-e9513ead8647 +keywords: ["drivers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- drivers +api_type: +- NA +--- + +# !drivers + +In Windows XP and later versions of Windows, the **!drivers** extension is obsolete. To display information about loaded drivers and other modules, use the [**lm**](lm--list-loaded-modules-.md) command. The command lm t n displays information in a format very similar to the old **!drivers** extension. However, this command will not display the memory usage of the drivers as the **!drivers** extension did. It will only display the drivers' start and end addresses, image names, and timestamps. The [**!vm**](-vm.md) and [**!memusage**](-memusage.md) extensions can be used to display memory usage statistics. + +``` +!drivers [Flags] +``` + +## Parameters + + + *Flags* +Can be any combination of the following values. (The default is 0x0.) + +Bit 0 (0x1) +Causes the display to include information about resident and standby memory. + +Bit 1 (0x2) +If this bit is set and bit 2 (0x4) is not set, the display will include information about resident, standby, and locked memory, as well as the loader entry address. If bit 2 is set, this causes the display to be a much longer and more detailed list of the driver image. Information about the headers is included, as is section information. + +Bit 2 (0x4) +Causes the display to be a much longer and more detailed list of the driver image. Information about each section is included. If bit 1 (0x2) is set, this will also include header information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about drivers and their memory use, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +An explanation of this command's display is given in the following table: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnMeaning

Base

The starting address of the device driver code, in hexadecimal. When the memory address used by the code that causes a stop falls between the base address for a driver and the base address for the next driver in the list, that driver is frequently the cause of the fault. For instance, the base for Ncrc810.sys is 0x80654000. Any address between that and 0x8065a000 belongs to this driver.

Code Size

The size, in kilobytes, of the driver code, in both hexadecimal and decimal.

Data Size

The amount of space, in kilobytes, allocated to the driver for data, in both hexadecimal and decimal.

Locked

(Only when Flag 0x2 is used) The amount of memory locked by the driver.

Resident

(Only when Flag 0x1 or 0x2 is used) The amount of the driver's memory that actually resides in physical memory.

Standby

(Only when Flag 0x1 or 0x2 is used) The amount of the driver's memory that is on standby.

Loader Entry

(Only when Flag 0x2 is used) The loader entry address.

Driver Name

The driver file name.

Creation Time

The link date of the driver. Do not confuse this with the file date of the driver, which can be set by external tools. The link date is set by the compiler when a driver or executable file is compiled. It should be close to the file date, but it is not always the same.

+ +  + +The following is a truncated example of this command: + +``` +kd> !drivers +Loaded System Driver Summary +Base Code Size Data Size Driver Name Creation Time +80080000 f76c0 (989 kb) 1f100 (124 kb) ntoskrnl.exe Fri May 26 15:13:00 +80400000 d980 ( 54 kb) 4040 ( 16 kb) hal.dll Tue May 16 16:50:34 +80654000 3f00 ( 15 kb) 1060 ( 4 kb) ncrc810.sys Fri May 05 20:07:04 +8065a000 a460 ( 41 kb) 1e80 ( 7 kb) SCSIPORT.SYS Fri May 05 20:08:05 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!drivers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-drvobj.md b/windows-driver-docs-pr/debugger/-drvobj.md new file mode 100644 index 0000000000..6c3ad464a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-drvobj.md @@ -0,0 +1,109 @@ +--- +title: drvobj +description: The drvobj extension displays detailed information about a DRIVER_OBJECT. +ms.assetid: 98f3cacf-311c-4000-8336-4964cc2cb9b0 +keywords: ["drvobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- drvobj +api_type: +- NA +--- + +# !drvobj + + +The **!drvobj** extension displays detailed information about a DRIVER\_OBJECT. + +``` +!drvobj DriverObject [Flags] +``` + +## Parameters + + + *DriverObject* +Specifies the driver object. This can be the hexadecimal address of the DRIVER\_OBJECT structure or the name of the driver. + + *Flags* +Can be any combination of the following bits. (The default is 0x01.) + +Bit 0 (0x1) +Causes the display to include device objects owned by the driver. + +Bit 1 (0x2) +Causes the display to include entry points for the driver's dispatch routines. + +Bit 2 (0x4) +Lists with detailed information the device objects owned by the driver (requires bit 0 (0x1)). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for examples and applications of this extension command. For information about driver objects, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +If *DriverObject* specifies the name of the device but supplies no prefix, the prefix "\\Driver\\" is assumed. Note that this command will check to see if *DriverObject* is a valid address or device name before using the expression evaluator. + +If *DriverObject* is an address, it must be the address of the DRIVER\_OBJECT structure. This can be obtained by examining the arguments passed to the driver's **DriverEntry** routine. + +This extension command will display a list of all device objects created by a specified driver. It will also display all fast I/O routines registered with this driver object. + +The following is an example for the Symbios Logic 810 SCSI miniport driver: + +``` +kd> bp DriverEntry // breakpoint at DriverEntry + +kd> g +symc810!DriverEntry+0x40: +80006a20: b07e0050 stl t2,50(sp) + +kd> r a0 //address of DevObj (the first parameter) +a0=809d5550 + +kd> !drvobj 809d5550 // display the driver object +Driver object is for: +\Driver\symc810 +Device Object list: +809d50d0 +``` + +You can also use [**!devobj 809d50d0**](-devobj.md) to get information about the device object. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!drvobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dskheap.md b/windows-driver-docs-pr/debugger/-dskheap.md new file mode 100644 index 0000000000..56c8fc5fde --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dskheap.md @@ -0,0 +1,105 @@ +--- +title: dskheap +description: The dskheap extension displays desktop heap information for a specified session. +ms.assetid: e49c816f-963c-4383-a3bf-c03b2c0cfa39 +keywords: ["desktops", "dskheap Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dskheap +api_type: +- NA +--- + +# !dskheap + + +The **!dskheap** extension displays desktop heap information for a specified session. + +``` +!dskheap [-v] [-s SessionID] +``` + +## Parameters + + + **-v** +Causes the display to include more detailed output. + + **-s** **** *SessionID* +Specifies a session. If this parameter is omitted, then the desktop heap information for session 0 is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about desktops or desktop heaps, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The desktop heap information for the session is arranged by window station. + +Here are a couple of examples: + +``` +kd> !dskheap -s 3 +## Winstation\Desktop Heap Size(KB) Used Rate(%) + + WinSta0\Screen-saver 3072 0% + WinSta0\Default 3072 0% + WinSta0\Disconnect 64 4% +## WinSta0\Winlogon 128 5% + + Total Desktop: ( 6336 KB - 4 desktops) +# Session ID: 3 + +kd> !dskheap +## Winstation\Desktop Heap Size(KB) Used Rate(%) + + WinSta0\Default 3072 0% + WinSta0\Disconnect 64 4% + WinSta0\Winlogon 128 9% + Service-0x0-3e7$\Default 512 4% + Service-0x0-3e5$\Default 512 0% + Service-0x0-3e4$\Default 512 1% +## SAWinSta\SADesktop 512 0% + + Total Desktop: ( 5312 KB - 7 desktops) +# Session ID: 0 + +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dskheap%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dt.md b/windows-driver-docs-pr/debugger/-dt.md new file mode 100644 index 0000000000..b52c755a27 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dt.md @@ -0,0 +1,79 @@ +--- +title: dt +description: The dt extension displays information about a CSR thread.This extension command should not be confused with the dt (Display Type) command. +ms.assetid: 7fbca028-8d11-42b5-b64e-41eb3edc56cc +keywords: ["dt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dt +api_type: +- NA +--- + +# !dt + + +The **!dt** extension displays information about a CSR thread. + +This extension command should not be confused with the [**dt (Display Type)**](dt--display-type-.md) command. + +``` +!dt [v] CSR-Thread +``` + +## Parameters + + + **v** +Verbose mode. + + *CSR-Thread* +Specifies the hexadecimal address of the CSR thread. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +Remarks +------- + +This extension displays the thread, process, client ID, flags, and reference count associated with the CSR thread. If verbose mode is selected, the display will also include list pointers, thread handle, and the wait block. + +## See also + + +[**!dp (!ntsdexts.dp)**](-dp---ntsdexts-dp-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-dump--create-dump-file-.md b/windows-driver-docs-pr/debugger/-dump--create-dump-file-.md new file mode 100644 index 0000000000..53468d13e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dump--create-dump-file-.md @@ -0,0 +1,250 @@ +--- +title: .dump (Create Dump File) +description: The .dump command creates a user-mode or kernel-mode crash dump file. +ms.assetid: df6bcf7f-eb2e-4605-87a0-c0a7e9e4776b +keywords: ["Create Dump File (.dump) command", "dump file, Create Dump File (.dump) command", ".dump (Create Dump File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dump (Create Dump File) +api_type: +- NA +--- + +# .dump (Create Dump File) + + +The **.dump** command creates a user-mode or kernel-mode crash dump file. + +``` +.dump Options FileName +.dump /? +``` + +## Parameters + + + *Options* +Represents one or more of the following options + +**/o** +Overwrites an existing dump file with the same name. If this option is not used and there is a file with the same file name, the dump file is not written. + +**/f\[***FullOptions***\]** +(Kernel mode:) Creates a [complete memory dump](complete-memory-dump.md). + +(User mode:) Creates a [full user-mode dump](full-user-mode-dumps.md). Despite their names, the largest minidump file actually contains more information than a full user-mode dump. For example, **.dump /mf** or **.dump /ma** creates a larger and more complete file than **.dump /f**. In user mode, **.dump** **/m\[***MiniOptions***\]** is always preferable to **.dump /f**. + +You can add the following *FullOptions* to change the contents of the dump file; the option is case-sensitive. + + ++++ + + + + + + + + + + +
FullOptionEffect

y

Adds AVX register information to the dump file.
+ +  + +**/m\[***MiniOptions***\]** +Creates a [small memory dump](cdb-and-windbg.md) (in kernel mode) or a [minidump](minidumps.md) (in user mode). If neither **/f** nor **/m** is specified, **/m** is the default. + +In user mode, **/m** can be followed with additional *MiniOptions* specifying extra data that is to be included in the dump. If no *MiniOptions* are included, the dump will include module, thread, and stack information, but no additional data. You can add any of the following *MiniOptions* to change the contents of the dump file; they are case-sensitive. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MiniOptionEffect

a

Creates a minidump with all optional additions. The /ma option is equivalent to /mfFhut -- it adds full memory data, handle data, unloaded module information, basic memory information, and thread time information to the minidump. Any failure to read inaccessable memory results in termination of the minidump generation.

A

The /mA option is equivalent to /ma except that it ignores any failure to read inaccessable memory and continues generating the minidump.

f

Adds full memory data to the minidump. All accessible committed pages owned by the target application will be included.

F

Adds all basic memory information to the minidump. This adds a stream to the minidump that contains all basic memory information, not just information about valid memory. This allows the debugger to reconstruct the complete virtual memory layout of the process when the minidump is being debugged.

h

Adds data about the handles associated with the target application to the minidump.

u

Adds unloaded module information to the minidump. This is available only in Windows Server 2003 and later versions of Windows.

t

Adds additional thread information to the minidump. This includes thread times, which can be displayed by using the [!runaway](-runaway.md) extension or the [.ttime (Display Thread Times)](-ttime--display-thread-times-.md) command when debugging the minidump.

i

Adds secondary memory to the minidump. Secondary memory is any memory referenced by a pointer on the stack or backing store, plus a small region surrounding this address.

p

Adds process environment block (PEB) and thread environment block (TEB) data to the minidump. This can be useful if you need access to Windows system information regarding the application's processes and threads.

w

Adds all committed read-write private pages to the minidump.

d

Adds all read-write data segments within the executable image to the minidump.

c

Adds code sections within images.

r

Deletes from the minidump those portions of the stack and store memory that are not useful for recreating the stack trace. Local variables and other data type values are deleted as well. This option does not make the minidump smaller (because these memory sections are simply zeroed), but it is useful if you want to protect the privacy of other applications.

R

Deletes the full module paths from the minidump. Only the module names will be included. This is a useful option if you want to protect the privacy of the user's directory structure.

y

Adds AVX register information to the dump file.

+ +  + +These *MiniOptions* can only be used when creating a user-mode minidump. They should follow the **/m** specifier. + +**/u** +Appends the date, time, and PID to the dump file names. This ensures that dump file names are unique. + +**/a** +Generates dumps for all currently-debugged processes. If **/a** is used, the **/u** option should also be used to ensure that each file has a unique name. + +**/b**\[**a**\] +Creates a .cab file. If this option is included, *FileName* is interpreted as the CAB file name, not the dump file name. A temporary dump file will be created, this file will be packaged into a CAB, and then the dump file will be deleted. If the **b** option is followed by **a**, all symbol and image files also will be packaged into the CAB. + +**/c "***Comment***"** +Specifies a comment string that will be written to the dump file. If *Comment* contains spaces, it must be enclosed in double quotes. When the dump file is loaded, the *Comment* string will be displayed. + +**/xc** *Address* +(User mode minidumps only) Adds a context record to the dump file. *Address* must specify the address of the context record. + +**/xr** *Address* +(User mode minidumps only) Adds an exception record to the dump file. *Address* must specify the address of the exception record. + +**/xp** *Address* +(User mode minidumps only) Adds a context record and an exception record to the dump file. *Address* must specify the address of an EXCEPTION\_POINTERS structure which contains pointers to the context record and the exception record. + +**/xt** *ThreadID* +(User mode minidumps only) Specifies the thread ID of the system thread that will be used as the exception thread for this dump file. + +**/kpmf** *File* +(Only when creating a kernel-mode Complete Memory Dump) Specifies a file that contains physical memory page data. + +**/j** *Address* +Adds the JIT\_DEBUG\_INFO structure to the dump file in user mode. *Address* must specify the address of the JIT\_DEBUG\_INFO structure. This address is normally provided via the %p parameter when the .jdinfo command is used as part of a just in time postmortem debugging process. For more information, see [**.jdinfo (Use JIT\_DEBUG\_INFO)**](-jdinfo--use-jit-debug-info-.md) and [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + + *FileName* +Specifies the name of the dump file. You can specify a full path and file name or just the file name. If the file name contains spaces, *FileName* should be enclosed in quotation marks. If no path is specified, the current directory is used. + + **-?** +Displays help for this command. This text is different in kernel mode and in user mode. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For a description of kernel-mode dump files and an explanation of their use, see [Kernel-Mode Dump Files](kernel-mode-dump-files.md). For a description of user-mode dump files and an explanation of their use, see [User-Mode Dump Files](user-mode-dump-files.md). + +Remarks +------- + +This command can be used in a variety of situations: + +- During live user-mode debugging, this command directs the target application to generate a dump file, but the target application does not terminate. + +- During live kernel-mode debugging, this command directs the target computer to generate a dump file, but the target computer does not crash. + +- During crash dump debugging, this command creates a new crash dump file from the old one. This is useful if you have a large crash dump file and want to create a smaller one. + +You can control what type of dump file will be produced: + +- In kernel mode, to produce a [complete memory dump](complete-memory-dump.md), use the **/f** option. To produce a [small memory dump](small-memory-dump.md), use the **/m** option (or no options). The .dump command cannot produce a [kernel memory dump](kernel-memory-dump.md). + +- In user mode, **.dump** **/m\[***MiniOptions***\]** is the best choice. Although "m" stands for "minidump", the dump files created by using this *MiniOption* can vary in size from very small to very large. By specifying the proper *MiniOptions* you can control exactly what information is included. For example, **.dump /ma** produces a dump with a great deal of information. The older command, **.dump /f**, produces a moderately large "standard dump" file and cannot be customized. + +You cannot specify which process is dumped. All running processes will be dumped. + +The **/xc**, **/xr**, **/xp**, and **/xt** options are used to store exception and context information in the dump file. This allows the [**.ecxr (Display Exception Context Record)**](-ecxr--display-exception-context-record-.md) command to be run on this dump file. + +The following example will create a user-mode minidump, containing full memory and handle information: + +``` +0:000> .dump /mfh myfile.dmp +``` + +Handle information can be read by using the [**!handle**](-handle.md) extension command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dump%20%28Create%20Dump%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dumpcab--create-dump-file-cab-.md b/windows-driver-docs-pr/debugger/-dumpcab--create-dump-file-cab-.md new file mode 100644 index 0000000000..59a70d654d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dumpcab--create-dump-file-cab-.md @@ -0,0 +1,83 @@ +--- +title: .dumpcab (Create Dump File CAB) +description: The .dumpcab command creates a CAB file containing the current dump file. +ms.assetid: 65ed766f-b049-47b0-90d7-e21d510a35ba +keywords: [".dumpcab (Create Dump File CAB) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dumpcab (Create Dump File CAB) +api_type: +- NA +--- + +# .dumpcab (Create Dump File CAB) + + +The **.dumpcab** command creates a CAB file containing the current dump file. + +``` +.dumpcab [-a] CabName +``` + +## Parameters + + + **-a** +Causes all currently loaded symbols to be included in the CAB file. For minidumps, all loaded images will be included as well. Use [**lml**](lm--list-loaded-modules-.md) to determine which symbols and images are loaded. + + *CabName* +The CAB file name, including extension. *CabName* can include an absolute or relative path; relative paths are relative to the directory in which the debugger was started. It is recommended that you choose the extension .cab. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

crash dump

Platforms

all

+ +  + +### Additional Information + +For more details on crash dumps, see [Crash Dump Files](crash-dump-files.md). + +Remarks +------- + +This command can only be used if you are already debugging a dump file. + +If you are debugging a live target and want to create a dump file and place it in a CAB, you should use the [**.dump (Create Dump File)**](-dump--create-dump-file-.md) command. Next, start a new debugging session with the dump file as its target, and use **.dumpcab**. + +The **.dumpcab** command cannot be used to place multiple dump files into one CAB file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dumpcab%20%28Create%20Dump%20File%20CAB%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dumpfa.md b/windows-driver-docs-pr/debugger/-dumpfa.md new file mode 100644 index 0000000000..38dd64c313 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dumpfa.md @@ -0,0 +1,94 @@ +--- +title: dumpfa +description: The dumpfa extension displays the contents of a failure analysis entry. +ms.assetid: 4516252d-b6c9-4bf4-b435-6c0b3cb0fbc3 +keywords: ["failure analysis entries, display", "failure analysis entries", "dumpfa Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dumpfa +api_type: +- NA +--- + +# !dumpfa + + +The **!dumpfa** extension displays the contents of a failure analysis entry. + +``` +!dumpfa Address +``` + +## Parameters + + + *Address* +Specifies the address of the failure analysis entry that is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +The **.dumpfa** extension is useful only to debug the [**!analyze**](-analyze.md) extension, as the following example shows. + +``` +0:000> !dumpfa 0x00a34140 +DataUsed 3b0 +Type = DEBUG_FLR_MARKER_BUCKET 00010016 - Size = 9 +Type = DEBUG_FLR_MARKER_FILE 0001000d - Size = 16 +Type = DEBUG_FLR_SYSXML_LOCALEID 00004200 - Size = 4 +Type = DEBUG_FLR_SYSXML_CHECKSUM 00004201 - Size = 4 +Type = DEBUG_FLR_READ_ADDRESS 0000000e - Size = 8 +Type = DEBUG_FLR_FAULTING_IP 80000000 - Size = 8 +Type = DEBUG_FLR_MM_INTERNAL_CODE 00001004 - Size = 8 +Type = DEBUG_FLR_CPU_MICROCODE_VERSION 0000301f - Size = 28 +Type = DEBUG_FLR_CUSTOMER_CRASH_COUNT 0000300b - Size = 8 +Type = DEBUG_FLR_DEFAULT_BUCKET_ID 00010008 - Size = 12 +Type = DEBUG_FLR_BUGCHECK_STR 00000600 - Size = 5 +Type = DEBUG_FLR_LAST_CONTROL_TRANSFER 0000000a - Size = 18 +Type = DEBUG_FLR_TRAP_FRAME c0000002 - Size = 8 +Type = DEBUG_FLR_STACK_TEXT 00010005 - Size = 1fb +Type = DEBUG_FLR_STACK_COMMAND 00010004 - Size = 17 +Type = DEBUG_FLR_OS_BUILD_NAME 0000301e - Size = 9 +Type = DEBUG_FLR_MODULE_NAME 00010006 - Size = 8 +Type = DEBUG_FLR_IMAGE_NAME 00010001 - Size = c +Type = DEBUG_FLR_IMAGE_TIMESTAMP 80000002 - Size = 8 +``` + +You can also use the [**!asd**](-asd.md) extension to debug the [**!analyze**](-analyze.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!dumpfa%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dvalloc--allocate-memory-.md b/windows-driver-docs-pr/debugger/-dvalloc--allocate-memory-.md new file mode 100644 index 0000000000..fc1bf9d025 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dvalloc--allocate-memory-.md @@ -0,0 +1,83 @@ +--- +title: .dvalloc (Allocate Memory) +description: The .dvalloc command causes Windows to allocate additional memory to the target process. +ms.assetid: 5bb0660e-0c88-4100-91ae-cd89834174f6 +keywords: [".dvalloc (Allocate Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dvalloc (Allocate Memory) +api_type: +- NA +--- + +# .dvalloc (Allocate Memory) + + +The **.dvalloc** command causes Windows to allocate additional memory to the target process. + +``` +.dvalloc [Options] Size +``` + +## Parameters + + + *Options* +Can be any number of the following options: + +**/b** **** *BaseAddress* +Specifies the virtual address of the beginning of the allocation. + +**/r** +Reserves the memory in the virtual address space but does not actually allocate any physical memory. If this option is used, the debugger calls **VirtualAllocEx** with the *flAllocationType* parameter equal to MEM\_RESERVE. If this option is not used, the value MEM\_COMMIT | MEM\_RESERVE is used. See the Microsoft Windows SDK for details. + + *Size* +Specifies the amount of memory to be allocated, in bytes. The amount of memory available to the program will equal *Size*. The amount of memory actually used may be slightly larger, since it is always a whole number of pages. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +The **.dvalloc** command calls **VirtualAllocEx** to allocate new memory for the target process. The allocated memory permits reading, writing, and execution. + +To free this memory, use [**.dvfree (Free Memory)**](-dvfree--free-memory-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dvalloc%20%28Allocate%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-dvfree--free-memory-.md b/windows-driver-docs-pr/debugger/-dvfree--free-memory-.md new file mode 100644 index 0000000000..e08183d3d5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-dvfree--free-memory-.md @@ -0,0 +1,80 @@ +--- +title: .dvfree (Free Memory) +description: The .dvfree command frees a memory allocation owned by the target process. +ms.assetid: 46845a5c-6ec4-4ae4-b89d-886df367dc5e +keywords: [".dvfree (Free Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .dvfree (Free Memory) +api_type: +- NA +--- + +# .dvfree (Free Memory) + + +The **.dvfree** command frees a memory allocation owned by the target process. + +``` +.dvfree [/d] BaseAddress Size +``` + +## Parameters + + + **/d** +Decommits the allocation, but does not actually release the pages containing the allocation. If this option is used, the debugger calls **VirtualFreeEx** with the *dwFreeType* parameter equal to MEM\_DECOMMIT. If this option is not used, the value MEM\_RELEASE is used. See the Microsoft Windows SDK for details. + + *BaseAddress* +Specifies the virtual address of the beginning of the allocation. + + *Size* +Specifies the amount of memory to be freed, in bytes. The actual memory freed will always be a whole number of memory pages. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +The **.dvfree** command calls **VirtualFreeEx** to free an existing memory allocation. Unless the **/d** option is specified, the pages containing this memory are released. + +This command can be used to free an allocation made by [**.dvalloc (Allocate Memory)**](-dvalloc--allocate-memory-.md). It can also be used to free any block of memory owned by the target process, but freeing memory that was not acquired through **.dvalloc** will naturally pose risks to the stability of the target process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.dvfree%20%28Free%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-e--thread-specific-command-.md b/windows-driver-docs-pr/debugger/-e--thread-specific-command-.md new file mode 100644 index 0000000000..2abced05b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-e--thread-specific-command-.md @@ -0,0 +1,103 @@ +--- +title: ~e (Thread-Specific Command) +description: The ~e command executes one or more commands for a specific thread or for all threads in the target process.Do not confuse this command with the e (Enter Values) command. +ms.assetid: a14f0a5f-48f9-46dd-baa6-b7d91b15772c +keywords: ["Thread-Specific Command (~e) command", "thread, Thread-Specific Command (~e) command", "~e (Thread-Specific Command) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~e (Thread-Specific Command) +api_type: +- NA +--- + +# ~e (Thread-Specific Command) + + +The **~e** command executes one or more commands for a specific thread or for all threads in the target process. + +Do not confuse this command with the [**e (Enter Values)**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) command. + +``` +~Thread e CommandString +``` + +## Parameters + + + *Thread* +Specifies the thread or threads that the debugger will execute *CommandString* for. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + + *CommandString* +Specifies one or more commands to execute. You should separate multiple commands by using semicolons. *CommandString* includes the rest of the input line. All of the text that follows the letter "e" is interpreted as part of this string. Do not enclose *CommandString* in quotation marks. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about other commands that control threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +When you use the **~e** command together with one thread, the **~e** command only saves some typing. For example, the following two commands are equivalent. + +``` +0:000> ~2e r; k; kd + +0:000> ~2r; ~2k; ~2kd +``` + +However, you can use the **~e** qualifier to repeat a command or extension command several times. When you use the qualifier in this manner, it can eliminate extra typing. For example, the following command repeats the [**!gle**](-gle.md) extension command for every thread that you are debugging. + +``` +0:000> ~*e !gle +``` + +If an error occurs in the execution of one command, execution continues with the next command. + +You cannot use the **~e** qualifier together with execution commands ([**g**](g--go-.md), [**gh**](gh--go-with-exception-handled-.md), [**gn**](gn--gn--go-with-exception-not-handled-.md), **gN**, [**gu**](gu--go-up-.md), [**p**](p--step-.md), [**pa**](pa--step-to-address-.md), [**pc**](pc--step-to-next-call-.md), [**t**](t--trace-.md), [**ta**](ta--trace-to-address-.md), [**tb**](tb--trace-to-next-branch-.md), [**tc**](tc--trace-to-next-call-.md), [**wt**](wt--trace-and-watch-data-.md)). + +You cannot use the **~e** qualifier together with the [**j (Execute If-Else)**](j--execute-if---else-.md) or [**z (Execute While)**](z--execute-while-.md) conditional commands. + +If you are debugging more than one process, you cannot use the **~e** command to access the virtual memory space for a inactive process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~e%20%28Thread-Specific%20Command%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-eb---ed.md b/windows-driver-docs-pr/debugger/-eb---ed.md new file mode 100644 index 0000000000..ad577bbb7c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-eb---ed.md @@ -0,0 +1,87 @@ +--- +title: eb, ed +description: The eb and ed extensions write a sequence of values into a specified physical address. These extension commands should not be confused with the e\\ (Enter Values) command. +ms.assetid: 368937e4-0989-4dca-983a-65bc63142108 +keywords: ["eb extension", "ed extension", "memory, Write Physical ( e ) extensions", "eb, ed Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- eb, ed +api_type: +- NA +--- + +# !eb, !ed + + +The **!eb** and **!ed** extensions write a sequence of values into a specified physical address. + +These extension commands should not be confused with the [**e\* (Enter Values)**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) command. + +``` +!eb [Flag] PhysicalAddress Data [ ... ] +!ed [Flag] PhysicalAddress Data [ ... ] +``` + +## Parameters + + + *Flag* +Can be any one of the following values. The *Flag* value must be surrounded by square brackets: + +**\[c\]** +Writes to cached memory. + +**\[uc\]** +Writes to uncached memory. + +**\[wc\]** +Writes to write-combined memory. + + *PhysicalAddress* +Specifies the first physical address on the target computer to which the data will be written, in hexadecimal. + + *Data* +Specifies one or more values to be written sequentially into physical memory. Enter these values in hexadecimal format. For the **!eb** extension, each value must be 1 byte (two hexadecimal digits). For the **!ed** extension, each value must be one DWORD (eight hexadecimal digits). You can include any number of *Data* values on one line. To separate multiple values, use commas or spaces. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kext.dll +Kdextx86.dll

Windows XP and later

Kext.dll

+ +  + +### Additional Information + +To read physical memory, use the [**!d\***](-db---dc---dd---dp---dq---du---dw.md) extensions. For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!eb,%20!ed%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ecb---ecd---ecw.md b/windows-driver-docs-pr/debugger/-ecb---ecd---ecw.md new file mode 100644 index 0000000000..0c09f38cec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ecb---ecd---ecw.md @@ -0,0 +1,88 @@ +--- +title: ecb, ecd, ecw +description: The ecb, ecd, and ecw extensions write to the PCI configuration space. +ms.assetid: ab5f5164-7666-48ac-aeba-5f238c2625f6 +keywords: ["ecb, ecd, ecw Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ecb, ecd, ecw +api_type: +- NA +--- + +# !ecb, !ecd, !ecw + + +The **!ecb**, **!ecd**, and **!ecw** extensions write to the PCI configuration space. + +``` +!ec Bus.Device.Function Offset Data +``` + +## Parameters + + + *Bus* +Specifies the bus. *Bus* can range from 0 to 0xFF. + + *Device* +Specifies the slot device number for the device. + + *Function* +Specifies the slot function number for the device. + + *Offset* +Specifies the address at which to write. + + *Data* +Specifies the value to be written. For the **!ecb** extension, *Data* must be 1 byte (two hexadecimal digits). For the **!ecw** extension, *Data* must be one WORD (four hexadecimal digits). For the **!ecd** extension, *Data* must be one DWORD (eight hexadecimal digits). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kext.dll

Windows XP and later

Kext.dll

+ +  + +These extension commands can only be used with an x86-based target computer. + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command, and some additional examples. For information about PCI buses, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +You cannot use these extension commands to write a sequence of *Data* values. This can only be done by repeated use of this extension. + +To display the PCI configuration space, use [**!pci 100**](-pci.md)*Bus Device Function*. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ecb,%20!ecd,%20!ecw%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-echo--echo-comment-.md b/windows-driver-docs-pr/debugger/-echo--echo-comment-.md new file mode 100644 index 0000000000..3f429a2435 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-echo--echo-comment-.md @@ -0,0 +1,83 @@ +--- +title: .echo (Echo Comment) +description: The .echo command displays a comment string. +ms.assetid: 4a291952-695c-4292-8aa5-82d497f0141c +keywords: [".echo (Echo Comment) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .echo (Echo Comment) +api_type: +- NA +--- + +# .echo (Echo Comment) + + +The **.echo** command displays a comment string. + +``` +.echo String +.echo "String" +``` + +## Parameters + + + *String* +Specifies the text to display. You can also enclose *String* in quotation marks ("). Regardless of whether you use quotation marks, *String* can contain any number of spaces, commas, and single quotation marks ('). If you enclose *String* in quotation marks, it can include semicolons, but not additional quotation marks. If you do not enclose *String* in quotation marks, it can include quotation marks in any location except the first character, but it cannot include semicolons. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.echo** command causes the debugger to display *String* immediately after you enter the command. + +An **.echo** command is ended if the debugger encounters a semicolon (unless the semicolon occurs within a quoted string). This restriction enables you to use **.echo** in complex constructions such as [conditional breakpoints](setting-a-conditional-breakpoint.md), as the following example shows. + +``` +0:000> bp `:143` "j (poi(MyVar)>5) '.echo MyVar Too Big'; '.echo MyVar Acceptable; gc' " +``` + +The **.echo** command also provides an easy way for users of debugging servers and debugging clients to communicate with one another. For more information about this situation, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +The **.echo** command differs from the [**$$ (Comment Specifier)**](-----comment-specifier-.md) token and the [**\* (Comment Line Specifier)**](----comment-line-specifier-.md) token, because these tokens cause the debugger to ignore the input text without displaying it. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.echo%20%28Echo%20Comment%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-echocpunum--show-cpu-number-.md b/windows-driver-docs-pr/debugger/-echocpunum--show-cpu-number-.md new file mode 100644 index 0000000000..2c83703bec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-echocpunum--show-cpu-number-.md @@ -0,0 +1,83 @@ +--- +title: .echocpunum (Show CPU Number) +description: The .echocpunum command turns on or turns off the display of the processor number when you are debugging a multiprocessor target computer. +ms.assetid: a238b291-8c6e-4a4c-adc3-3be5a9916a29 +keywords: ["Show CPU Number (.echocpunum) command", "multiprocessor computer, Show CPU Number (.echocpunum) command", ".echocpunum (Show CPU Number) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .echocpunum (Show CPU Number) +api_type: +- NA +--- + +# .echocpunum (Show CPU Number) + + +The **.echocpunum** command turns on or turns off the display of the processor number when you are debugging a multiprocessor target computer. + +``` +.echocpunum 0 +.echocpunum 1 +.echocpunum +``` + +## Parameters + + + **0** +Turns off the display of the processor number. + + **1** +Turns on the display of the processor number. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to debug multiprocessor computers, see [Multiprocessor Syntax](multiprocessor-syntax.md). + +Remarks +------- + +If you use the **.echocpunum** command without any arguments, the display of processor numbers is turned on or off, and the new state is displayed. + +By default, the display is turned off. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.echocpunum%20%28Show%20CPU%20Number%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-echotime--show-current-time-.md b/windows-driver-docs-pr/debugger/-echotime--show-current-time-.md new file mode 100644 index 0000000000..e3717fba7a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-echotime--show-current-time-.md @@ -0,0 +1,69 @@ +--- +title: .echotime (Show Current Time) +description: The .echotime command displays the current time. +ms.assetid: 08da8914-0882-4525-8e15-e23176484915 +keywords: [".echotime (Show Current Time) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .echotime (Show Current Time) +api_type: +- NA +--- + +# .echotime (Show Current Time) + + +The **.echotime** command displays the current time. + +``` +.echotime +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.echotime** command displays the time to the computer that the debugger is running on. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.echotime%20%28Show%20Current%20Time%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-echotimestamps--show-time-stamps-.md b/windows-driver-docs-pr/debugger/-echotimestamps--show-time-stamps-.md new file mode 100644 index 0000000000..3959f3ee7e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-echotimestamps--show-time-stamps-.md @@ -0,0 +1,87 @@ +--- +title: .echotimestamps (Show Time Stamps) +description: The .echotimestamps command turns on or turns off the display of time stamp information. +ms.assetid: c70dc71b-83c2-41de-90f3-638e231c0476 +keywords: ["Show Time Stamps (.echotimestamps) command", "time stamps", "DbgPrint time stamps", ".echotimestamps (Show Time Stamps) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .echotimestamps (Show Time Stamps) +api_type: +- NA +--- + +# .echotimestamps (Show Time Stamps) + + +The **.echotimestamps** command turns on or turns off the display of time stamp information. + +``` +.echotimestamps 0 +.echotimestamps 1 +.echotimestamps +``` + +## Parameters + + + **0** +Turns off the display of time stamp information. This is the default behavior of the Debugger. + + **1** +Turns on the display of time stamp information. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about **DbgPrint**, **KdPrint**, **DbgPrintEx**, and **KdPrintEx**, see [The DbgPrint Buffer](reading-and-filtering-debugging-messages.md#the-dbgprint-buffer) or see the Microsoft Windows Driver Kit (WDK) documentation. + +Remarks +------- + +When you use the **.echotimestamps** command without parameters, the display of time stamps is turned on or off, and the new state is displayed. + +If you turn on this display, the debugger shows time stamps for module loads, thread creations, exceptions, and other events. + +The **DbgPrint**, **KdPrint**, **DbgPrintEx**, and **KdPrintEx** kernel-mode routines send a formatted string to a buffer on the host computer. The string is displayed in the [Debugger Command window](debugger-command-window.md) (unless you have disabled such printing). You can also display the formatted string by using the [**!dbgprint**](-dbgprint.md) extension command. + +When you use **.echotimestamps** to turn on the display of time stamps, the time and date of each comment in the **DbgPrint** buffer is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.echotimestamps%20%28Show%20Time%20Stamps%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ecs.md b/windows-driver-docs-pr/debugger/-ecs.md new file mode 100644 index 0000000000..2c0005dda6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ecs.md @@ -0,0 +1,29 @@ +--- +title: ecs +description: ecs +ms.assetid: ab353f5f-6b92-4ccd-b063-a67fcd9b00ef +keywords: ["ecs extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !ecs + + +## + + +The **!ecs** extension is obsolete. To edit the PCI configuration space, use [**!ecb**](-ecb---ecd---ecw.md), **!ecd**, or **!ecw**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ecs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ecxr--display-exception-context-record-.md b/windows-driver-docs-pr/debugger/-ecxr--display-exception-context-record-.md new file mode 100644 index 0000000000..a0f3b1bc40 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ecxr--display-exception-context-record-.md @@ -0,0 +1,83 @@ +--- +title: .ecxr (Display Exception Context Record) +description: The .ecxr command displays the context record that is associated with the current exception. +ms.assetid: 020dfa99-ba25-4af3-929a-143d5c91ad87 +keywords: ["Display Exception Context Record (.cxr) command", "exceptions, exception context record", ".ecxr (Display Exception Context Record) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .ecxr (Display Exception Context Record) +api_type: +- NA +--- + +# .ecxr (Display Exception Context Record) + + +The **.ecxr** command displays the context record that is associated with the current exception. + +``` +.ecxr +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Crash dump only (minidumps only)

Platforms

All

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +The **.ecxr** command locates the current exception's context information and displays the important registers for the specified context record. + +This command also instructs the debugger to use the context record that is associated with the current exception as the register context. After you run **.ecxr**, the debugger can access the most important registers and the stack trace for this thread. This register context persists until you enable the target to execute, change the current process or thread, or use another register context command ([**.cxr**](-cxr--display-context-record-.md) or **.ecxr**). For more information about register contexts, see [Register Context](changing-contexts.md#register-context). + +The [**.excr**](-excr--display-exception-context-record-.md) command is a synonym command and has identical functionality. + +## See also + + +[**.excr**](-excr--display-exception-context-record-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.ecxr%20%28Display%20Exception%20Context%20Record%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-effmach--effective-machine-.md b/windows-driver-docs-pr/debugger/-effmach--effective-machine-.md new file mode 100644 index 0000000000..2cd5100563 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-effmach--effective-machine-.md @@ -0,0 +1,115 @@ +--- +title: .effmach (Effective Machine) +description: The .effmach command displays or changes the processor mode that the debugger uses. +ms.assetid: bf4dfdc0-2f0b-416a-8bf2-0e7d81339905 +keywords: ["Effective Machine (.effmach) command", ".effmach (Effective Machine) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .effmach (Effective Machine) +api_type: +- NA +--- + +# .effmach (Effective Machine) + + +The **.effmach** command displays or changes the processor mode that the debugger uses. + +``` +.effmach [MachineType] +``` + +## Parameters + + + *MachineType* +Specifies the processor type that the debugger uses for this session. If you omit this parameter, the debugger displays the current machine type. + +You can enter one of the following machine types. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Machine type

Description

.

Use the processor mode of the target computer's native processor mode.

#

Use the processor mode of the code that is executing for the most recent event.

x86

Use an x86-based processor mode.

amd64

Use an x64-based processor mode.

ebc

Use an EFI byte code processor mode.

+ +  + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The processor mode influences many debugger features: + +- Which processor is used for stack tracing. + +- Whether the process uses 32-bit or 64-bit pointers. + +- Which processor's register set is active. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.effmach%20%28Effective%20Machine%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-elog-str.md b/windows-driver-docs-pr/debugger/-elog-str.md new file mode 100644 index 0000000000..dfe9e0bdd9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-elog-str.md @@ -0,0 +1,68 @@ +--- +title: elog_str +description: The elog_str extension adds a string to the event log. +ms.assetid: 142ef480-8095-428e-9b7d-f4c8bfb78075 +keywords: ["event log", "elog_str Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- elog_str +api_type: +- NA +--- + +# !elog\_str + + +The **!elog\_str** extension adds a string to the event log. + +``` +!elog_str String +``` + +## Parameters + + + *String* +Specifies the string to add to the event log. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +Because a registered event source does not send *String*, the string appears in the event log with a warning that no event ID was determined. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!elog_str%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-else.md b/windows-driver-docs-pr/debugger/-else.md new file mode 100644 index 0000000000..ae0d61f621 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-else.md @@ -0,0 +1,48 @@ +--- +title: .else +description: The .else token behaves like the else keyword in C. +ms.assetid: aa783a66-2b28-40d1-a943-67a26e668612 +keywords: [".else Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .else +api_type: +- NA +--- + +# .else + + +The **.else** token behaves like the **else** keyword in C. + +``` +.if (Condition) { Commands } .else { Commands } + +.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands } +``` + +## Syntax Elements + + + *Commands* +Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.else%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-elsif.md b/windows-driver-docs-pr/debugger/-elsif.md new file mode 100644 index 0000000000..8640bad428 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-elsif.md @@ -0,0 +1,51 @@ +--- +title: .elsif +description: The .elsif token behaves like the else if keyword combination in C. +ms.assetid: f5612326-9fcf-4f2e-9692-cc75e7ff4664 +keywords: [".elsif Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .elsif +api_type: +- NA +--- + +# .elsif + + +The **.elsif** token behaves like the **else if** keyword combination in C. + +``` +.if (Condition) { Commands } .elsif (Condition) { Commands } + +.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands } +``` + +## Syntax Elements + + + *Condition* +Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing *Condition* in parentheses is optional. *Condition* must be an expression, not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Commands* +Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.elsif%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-enable-long-status--enable-long-integer-display-.md b/windows-driver-docs-pr/debugger/-enable-long-status--enable-long-integer-display-.md new file mode 100644 index 0000000000..5d273ec701 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-enable-long-status--enable-long-integer-display-.md @@ -0,0 +1,88 @@ +--- +title: .enable_long_status (Enable Long Integer Display) +description: The .enable_long_status command specifies whether the debugger displays long integers in decimal format or in the default radix. +ms.assetid: e08f5a40-5246-4120-ae43-37e876269463 +keywords: ["Enable Long Integer Display (.enable_long_status) command", ".enable_long_status (Enable Long Integer Display) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .enable_long_status (Enable Long Integer Display) +api_type: +- NA +--- + +# .enable\_long\_status (Enable Long Integer Display) + + +The **.enable\_long\_status** command specifies whether the debugger displays long integers in decimal format or in the default radix. + +``` +.enable_long_status 0 +.enable_long_status 1 +``` + +## Parameters + + + **0** +Displays all long integers in decimal format. This is the default behavior of the debugger. + + **1** +Displays all long integers in the default radix. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.enable\_long\_status** command affects the output of the [**dt (Display Type)**](dt--display-type-.md) command. + +In WinDbg, **.enable\_long\_status** also affects the display in the [Locals window](locals-window.md) and the + +Watch window. These windows are automatically updated after you issue **.enable\_long\_status**. + +This command affects only the display of long integers. To control whether standard integers are displayed in decimal format or the default radix, use the [**.force\_radix\_output (Use Radix for Integers)**](-force-radix-output--use-radix-for-integers-.md) command. + +**Note**   The [**dv (Display Local Variables)**](dv--display-local-variables-.md) command always displays long integers in the current number base. + +  + +To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.enable_long_status%20%28Enable%20Long%20Integer%20Display%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-enable-unicode--enable-unicode-display-.md b/windows-driver-docs-pr/debugger/-enable-unicode--enable-unicode-display-.md new file mode 100644 index 0000000000..01cc536051 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-enable-unicode--enable-unicode-display-.md @@ -0,0 +1,86 @@ +--- +title: .enable_unicode (Enable Unicode Display) +description: The .enable_unicode command specifies whether the debugger displays USHORT pointers and arrays as Unicode strings. +ms.assetid: bb029ff4-1802-4d91-ba4b-9db10fa7c055 +keywords: ["Enable Unicode Display (.enable_unicode) command", "UNICODE_STRING structure", ".enable_unicode (Enable Unicode Display) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .enable_unicode (Enable Unicode Display) +api_type: +- NA +--- + +# .enable\_unicode (Enable Unicode Display) + + +The **.enable\_unicode** command specifies whether the debugger displays USHORT pointers and arrays as Unicode strings. + +``` +.enable_unicode 0 +.enable_unicode 1 +``` + +## Parameters + + + **0** +Displays all 16-bit (USHORT) arrays and pointers as short integers. This is the default behavior of the debugger. + + **1** +Displays all 16-bit (USHORT) arrays and pointers as Unicode strings. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.enable\_unicode** command affects the output of the [**dt (Display Type)**](dt--display-type-.md) command. + +In WinDbg, the **.enable\_unicode** command also affects the display in the [Locals window](locals-window.md) and the Watch window. These windows are automatically updated after you issue **.enable\_unicode**. + +You can also select or clear **Display 16-bit values** as Unicode on the shortcut menu of the Locals or Watch window to specify the display for USHORT arrays and pointers. + +## See also + + +[**ds, dS (Display String)**](ds--ds--display-string-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.enable_unicode%20%28Enable%20Unicode%20Display%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-endpsrv--end-process-server-.md b/windows-driver-docs-pr/debugger/-endpsrv--end-process-server-.md new file mode 100644 index 0000000000..3da7e072d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-endpsrv--end-process-server-.md @@ -0,0 +1,79 @@ +--- +title: .endpsrv (End Process Server) +description: The .endpsrv command causes the current process server or KD connection server to close. +ms.assetid: 3f8d0a85-f0f4-4c13-ab52-e4d99ba3599c +keywords: [".endpsrv (End Process Server) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .endpsrv (End Process Server) +api_type: +- NA +--- + +# .endpsrv (End Process Server) + + +The **.endpsrv** command causes the current process server or KD connection server to close. + +``` +.endpsrv +``` + +## + + +### Environment + +You can use this command only when you are performing remote debugging through a process server or KD connection server. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about these servers, see [Process Servers (User Mode)](process-servers--user-mode-.md) or [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md) + +Remarks +------- + +The **.endpsrv** command terminates the process server or KD connection server currently connected to your smart client. + +If you wish to terminate a process server or KD connection server from the computer on which it is running, use Task Manager to end the process (dbgsrv.exe or kdsrv.exe). + +The **.endpsrv** command can terminate a process server or KD connection server, but it cannot terminate a debugging server. For information on how to do that, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.endpsrv%20%28End%20Process%20Server%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-endsrv--end-debugging-server-.md b/windows-driver-docs-pr/debugger/-endsrv--end-debugging-server-.md new file mode 100644 index 0000000000..5861fdcb4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-endsrv--end-debugging-server-.md @@ -0,0 +1,130 @@ +--- +title: .endsrv (End Debugging Server) +description: The .endsrv command causes the debugger to cancel an active debugging server. +ms.assetid: 6be6c774-fe6b-4bd4-8174-55ef207db3e6 +keywords: [".endsrv (End Debugging Server) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .endsrv (End Debugging Server) +api_type: +- NA +--- + +# .endsrv (End Debugging Server) + + +The **.endsrv** command causes the debugger to cancel an active debugging server. + +``` +.endsrv ServerID +``` + +## Parameters + + + *ServerID* +Specifies the ID of the debugging server. + +### Environment + +You can use this command only when you are performing remote debugging through the debugger. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about remote debugging, see [Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md). + +Remarks +------- + +You must issue the **.endsrv** command from the debugging server or from one of the debugging clients that are connected to the debugging server. + +To determine the ID of a debugging server, use the [**.servers (List Debugging Servers)**](-servers--list-debugging-servers-.md) command. + +The **.endsrv** command can terminate a debugging server, but it cannot terminate a process server or KD connection server. For information on how to end these servers, see [Controlling a Process Server Session](controlling-a-process-server-session.md) and [Controlling a KD Connection Server Session](controlling-a-kd-connection-server-session.md). (There is, however, one exceptional case when **.endsrv** can end a process server that has been launched programmatically; for details, see [**IDebugClient::StartProcessServer**](https://msdn.microsoft.com/library/windows/hardware/ff558810).) + +If you cancel a debugging server, you prevent any future debugging clients from attaching to the server. However, if you cancel a debugging server, you do not detach any clients that are currently attached through the server. + +Consider the following situation. Suppose that you start some debugging servers, as the following example shows. + +``` +0:000> .server npipe:pipe=rabbit +Server started with 'npipe:pipe=rabbit' +0:000> .server tcp:port=7 +Server started with 'tcp:port=7' +``` + +Then, you decide to use a password, as the following example shows. + +``` +0:000> .server npipe:pipe=tiger,password=hardtoguess +Server started with 'npipe:pipe=tiger,password=hardtoguess' +``` + +But the earlier servers are still running, so you should cancel them, as the following example shows. + +``` +0:000> .servers +0 - Debugger Server - npipe:Pipe=rabbit +1 - Debugger Server - tcp:Port=7 +2 - Debugger Server - npipe:Pipe=tiger,Password=* +0:000> .endsrv 0 +Server told to exit. Actual exit may be delayed until +the next connection attempt. +0:000> .endsrv 1 +Server told to exit. Actual exit may be delayed until +the next connection attempt. +0:000> .servers +0 - +1 - +2 - Debugger Server - npipe:Pipe=tiger,Password=* +``` + +Finally, to make sure that nothing attached to your computer while the earlier servers were active, use the [**.clients (List Debugging Clients)**](-clients--list-debugging-clients-.md) command. + +``` +0:000> .clients +HotMachine\HostUser, last active Mon Mar 04 16:05:21 2002 +``` + +**Caution**   Using a password with TCP, NPIPE, or COM protocol offers only a small amount of protection, because the password is not encrypted. When you use a password together with a SSL or SPIPE protocol, the password is encrypted. If you want to establish a secure remote session, you must use the SSL or SPIPE protocol. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.endsrv%20%28End%20Debugging%20Server%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-enumtag--enumerate-secondary-callback-data-.md b/windows-driver-docs-pr/debugger/-enumtag--enumerate-secondary-callback-data-.md new file mode 100644 index 0000000000..ebb07ae73c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-enumtag--enumerate-secondary-callback-data-.md @@ -0,0 +1,97 @@ +--- +title: .enumtag (Enumerate Secondary Callback Data) +description: The .enumtag command displays secondary bug check callback data and all data tags. +ms.assetid: 2146ebb9-96ce-4eb0-8c23-c9aaa5ed7f73 +keywords: [".enumtag (Enumerate Secondary Callback Data) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .enumtag (Enumerate Secondary Callback Data) +api_type: +- NA +--- + +# .enumtag (Enumerate Secondary Callback Data) + + +The **.enumtag** command displays secondary bug check callback data and all data tags. + +``` +.enumtag +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information and for other ways of displaying this data, see [Reading Bug Check Callback Data](reading-bug-check-callback-data.md). + +Remarks +------- + +You can use the **.enumtag** command only after a bug check has occurred or when you are debugging a kernel-mode crash dump file. + +For each block of secondary bug check callback data, the **.enumtag** command displays the tag (in GUID format) and the data (as bytes and ASCII characters). + +Consider the following example. + +``` +kd> .enumtag +{87654321-0000-0000-0000000000000000} - 0xf9c bytes + 4D 5A 90 00 03 00 00 00 04 00 00 00 FF FF 00 00 MZ.............. + B8 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00 ........@....... + 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + .... + 00 00 00 00 00 00 00 00 00 00 00 00 ............ + +{12345678-0000-0000-0000000000000000} - 0x298 bytes + F4 BF 7B 80 F4 BF 7B 80 00 00 00 00 00 00 00 00 ..{...{......... + 4B 44 42 47 98 02 00 00 00 20 4D 80 00 00 00 00 KDBG..... M..... + 54 A5 57 80 00 00 00 00 A0 50 5A 80 00 00 00 00 T.W......PZ..... + 40 01 08 00 18 00 00 00 BC 7D 50 80 00 00 00 00 @........}P..... + .... + 00 00 00 00 00 00 00 00 ........ +``` + +In this example, the first batch of secondary data has a GUID ){87654321-0000-0000-0000000000000000}) as its tag, and the second batch of data has a GUID ({12345678-0000-0000-0000000000000000}) as its tag. However, the data is not in a useful format. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.enumtag%20%28Enumerate%20Secondary%20Callback%20Data%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-envvar.md b/windows-driver-docs-pr/debugger/-envvar.md new file mode 100644 index 0000000000..c47b259a53 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-envvar.md @@ -0,0 +1,77 @@ +--- +title: envvar +description: The envvar extension displays the value of the specified environment variable. +ms.assetid: 7a6e1796-08e0-414e-a092-326b30c8ce8f +keywords: ["envvar Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- envvar +api_type: +- NA +--- + +# !envvar + + +The **!envvar** extension displays the value of the specified environment variable. + +``` +!envvar Variable +``` + +## Parameters + + + *Variable* +Specifies the environment variable whose value is displayed. *Variable* is not case sensitive. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +For more information about environment variables, see [Environment Variables](environment-variables.md) and the Microsoft Windows SDK documentation. + +Remarks +------- + +The **!envvar** extension works both in user mode and in kernel mode. However, in kernel mode, when you set the idle thread as the current process, the pointer to the Process Environment Block (PEB) is **NULL**, so it fails. In kernel mode, the **!envvar** extension displays the environment variables on the target computer, as the following example shows. + +``` +0:000> !envvar _nt_symbol_path + _nt_symbol_path = srv*C:\mysyms*https://msdl.microsoft.com/download/symbols +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!envvar%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-errlog.md b/windows-driver-docs-pr/debugger/-errlog.md new file mode 100644 index 0000000000..96ad75f0e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-errlog.md @@ -0,0 +1,73 @@ +--- +title: errlog +description: The errlog extension displays the contents of any pending entries in the I/O system's error log. +ms.assetid: 2ef6331e-fa83-4515-8d70-5094e40b8497 +keywords: ["errlog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- errlog +api_type: +- NA +--- + +# !errlog + + +The **!errlog** extension displays the contents of any pending entries in the I/O system's error log. + +``` +!errlog +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about [**IoWriteErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff550527), see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +This command displays information about any pending events in the I/O system's error log. These are events queued by calls to the [**IoWriteErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff550527) function, to be written to the system's event log for subsequent viewing by the **Event Viewer**. + +Only entries that were queued by [**IoWriteErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff550527) but have not been committed to the error log will be displayed. + +This command can be used as a diagnostic aid after a system crash because it reveals pending error information that was unable to be committed to the error log before the system halted. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!errlog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-error.md b/windows-driver-docs-pr/debugger/-error.md new file mode 100644 index 0000000000..6f4075ed6c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-error.md @@ -0,0 +1,86 @@ +--- +title: error +description: The error extension decodes and displays information about an error value. +ms.assetid: 4999ab4b-2f55-47d4-b9a7-6f1231271fcc +keywords: ["error codes", "Win32 error codes", "WinSock error codes", "error Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- error +api_type: +- NA +--- + +# !error + + +The **!error** extension decodes and displays information about an error value. + +``` +!error Value [Flags] +``` + +## Parameters + + + *Value* +Specifies one of the following error codes: + +- Win32 + +- Winsock + +- NTSTATUS + +- NetAPI + + *Flags* +If *Flags* is set to 1, the error code is read as an NTSTATUS code. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +The following example shows you how to use **!error**. + +``` +0:000> !error 2 +Error code: (Win32) 0x2 (2) - The system cannot find the file specified. +0:000> !error 2 1 +Error code: (NTSTATUS) 0x2 - STATUS_WAIT_2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!error%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-errpkt.md b/windows-driver-docs-pr/debugger/-errpkt.md new file mode 100644 index 0000000000..e70ec7e01b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-errpkt.md @@ -0,0 +1,110 @@ +--- +title: errpkt +description: The errpkt extension displays the contents of a Windows Hardware Error Architecture (WHEA) hardware error packet. +ms.assetid: cf4b1dfa-3b15-45d4-b5e2-1da7cdbca350 +keywords: ["errpkt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- errpkt +api_type: +- NA +--- + +# !errpkt + + +The **!errpkt** extension displays the contents of a Windows Hardware Error Architecture (WHEA) hardware error packet. + +``` +!errpkt Address +``` + +## Parameters + + + *Address* +Specifies the address of the hardware error packet. + +### DLL + + ++++ + + + + + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Server 2003

Unavailable

Windows Vista and later

Kdexts.dll

+ +  + +This extension can be used only in Windows Vista and later versions of Windows. + +### Additional Information + +The [**!whea**](-whea.md) and [**!errrec**](-errrec.md) extensions can be used to display additional WHEA information. For general information about WHEA, see [Windows Hardware Error Architecture (WHEA)](http://go.microsoft.com/fwlink/p/?linkid=153571) in the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The following example shows the output of the **!errpkt** extension: + +``` +3: kd> !errpkt fffffa8007cf44da + WHEA Error Packet Info Section (@ fffffa8007cf44da) + Flags : 0x00000000 + Size : 0x218 + RawDataLength : 0x392 + Context : 0x0000000000000000 + ErrorType : 0x0 - Processor + ErrorSeverity : 0x1 - Fatal + ErrorSourceId : 0x0 + ErrorSourceType : 0x0 - MCE + Version : 00000002 + Cpu : 0000000000000002 + RawDataFormat : 0x2 - Intel64 MCA + + Raw Data : Located @ FFFFFA8007CF45F2 + +Processor Error: (Internal processor error) +This error means either the processor is damaged or perhaps +voltage and/or temperature thresholds have been exceeded. +If the problem continues to occur, replace the processor. +Processor Number : 2 +Bank Number : 0 + Status : 0 + Address : 0000000000000000 (I) + Misc : 0000000000000000 (I) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!errpkt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-errrec.md b/windows-driver-docs-pr/debugger/-errrec.md new file mode 100644 index 0000000000..8fcb5b7241 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-errrec.md @@ -0,0 +1,169 @@ +--- +title: errrec +description: The errrec extension displays the contents of a Windows Hardware Error Architecture (WHEA) error record. +ms.assetid: 372e4700-0cd7-468d-98e8-b0ead4ebc92f +keywords: ["errrec Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- errrec +api_type: +- NA +--- + +# !errrec + + +The **!errrec** extension displays the contents of a Windows Hardware Error Architecture (WHEA) error record. + +``` +!errrec Address +``` + +## Parameters + + + *Address* +Specifies the address of the error record. + +### DLL + + ++++ + + + + + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Server 2003

Unavailable

Windows Vista and later

Kdexts.dll

+ +  + +This extension can be used only in Windows Vista and later versions of Windows. + +### Additional Information + +The [**!whea**](-whea.md) and [**!errpkt**](-errpkt.md) extensions can be used to display additional WHEA information. For general information about WHEA, see [Windows Hardware Error Architecture (WHEA)](http://go.microsoft.com/fwlink/p/?linkid=153571) in the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The following example shows how the [**!whea**](-whea.md) extension can be used to obtain the address of an error record, and then the contents of this record can be displayed by the **!errrec** extension: + +``` +3: kd> !whea +Error Source Table @ fffff800019ca250 +13 Error Sources +Error Source 0 @ fffffa80064132c0 + Notify Type : Machine Check Exception + Type : 0x0 (MCE) + Error Count : 8 + Record Count : 10 + Record Length : c3e + Error Records : wrapper @ fffffa8007cf4000 record @ fffffa8007cf4030 + +. . . . + +# 3: kd> !errrec fffffa8007cf4030 +=============================================================================== +## Common Platform Error Record @ fffffa8007cf4030 +------------------------------------------------------------------------------- +Revision : 2.1 +Record Id : 01c9c7ff04e0ff7d +Severity : Fatal (1) +Length : 1730 +Creator : Microsoft +Notify Type : Machine Check Exception +Timestamp : 4/28/2009 12:54:47 +Flags : 0x00000000 +# +=============================================================================== +## Section 0 : Processor Generic +------------------------------------------------------------------------------- +Descriptor @ fffffa8007cf40b0 +Section @ fffffa8007cf4188 +Offset : 344 +Length : 192 +Flags : 0x00000001 Primary +Severity : Fatal + +No valid data fields are present. +# +=============================================================================== +## Section 1 : {390f56d5-ca86-4649-95c4-73a408ae5834} +------------------------------------------------------------------------------- +Descriptor @ fffffa8007cf40f8 +Section @ fffffa8007cf4248 +Offset : 536 +Length : 658 +Flags : 0x00000000 +Severity : Fatal + +*** Unknown section format *** +# +=============================================================================== +## Section 2 : Error Packet +------------------------------------------------------------------------------- +Descriptor @ fffffa8007cf4140 +Section @ fffffa8007cf44da +Offset : 1194 +Length : 536 +Flags : 0x00000000 +Severity : Fatal + + WHEA Error Packet Info Section (@ fffffa8007cf44da) + Flags : 0x00000000 + Size : 0x218 + RawDataLength : 0x392 + Context : 0x0000000000000000 + ErrorType : 0x0 - Processor + ErrorSeverity : 0x1 - Fatal + ErrorSourceId : 0x0 + ErrorSourceType : 0x0 - MCE + Version : 00000002 + Cpu : 0000000000000002 + RawDataFormat : 0x2 - Intel64 MCA + + Raw Data : Located @ FFFFFA8007CF45F2 + +Processor Error: (Internal processor error) +This error means either the processor is damaged or perhaps +voltage and/or temperature thresholds have been exceeded. +If the problem continues to occur, replace the processor. +Processor Number : 2 +Bank Number : 0 + Status : 0 + Address : 0000000000000000 (I) + Misc : 0000000000000000 (I) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!errrec%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-event-code--display-event-code-.md b/windows-driver-docs-pr/debugger/-event-code--display-event-code-.md new file mode 100644 index 0000000000..66b97f0ddf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-event-code--display-event-code-.md @@ -0,0 +1,66 @@ +--- +title: .event_code (Display Event Code) +description: The .event_code command displays the current event instructions. +ms.assetid: f2ab0f4d-493c-4b8b-a7a0-82c10586d485 +keywords: [".event_code (Display Event Code) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .event_code (Display Event Code) +api_type: +- NA +--- + +# .event\_code (Display Event Code) + + +The **.event\_code** command displays the current event instructions. + +``` +.event_code +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +Remarks +------- + +The **.event\_code** command displays the hexadecimal instructions at the current event's instruction pointer. The display includes up to 64 bytes of instructions if they are available. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.event_code%20%28Display%20Event%20Code%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-eventlog--display-recent-events-.md b/windows-driver-docs-pr/debugger/-eventlog--display-recent-events-.md new file mode 100644 index 0000000000..7af48cde33 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-eventlog--display-recent-events-.md @@ -0,0 +1,86 @@ +--- +title: .eventlog (Display Recent Events) +description: The .eventlog command displays the recent Microsoft Win32 debug events, such as module loading, process creation and termination, and thread creation and termination. +ms.assetid: 8075007a-42a2-4973-bb04-cca9a4a1b9b6 +keywords: [".eventlog (Display Recent Events) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .eventlog (Display Recent Events) +api_type: +- NA +--- + +# .eventlog (Display Recent Events) + + +The **.eventlog** command displays the recent Microsoft Win32 debug events, such as module loading, process creation and termination, and thread creation and termination. + +``` +.eventlog +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.eventlog** command shows only 1024 characters. + +The following example shows the **.eventlog** command. + +``` +0:000> .eventlog +0904.1014: Load module C:\Windows\system32\ADVAPI32.dll at 000007fe`fed80000 +0904.1014: Load module C:\Windows\system32\RPCRT4.dll at 000007fe`fe8c0000 +0904.1014: Load module C:\Windows\system32\GDI32.dll at 000007fe`fea00000 +0904.1014: Load module C:\Windows\system32\USER32.dll at 00000000`76b10000 +0904.1014: Load module C:\Windows\system32\msvcrt.dll at 000007fe`fe450000 +0904.1014: Load module C:\Windows\system32\COMDLG32.dll at 000007fe`fecf0000 +0904.1014: Load module C:\Windows\system32\SHLWAPI.dll at 000007fe`fe1f0000 +0904.1014: Load module C:\Windows\WinSxS\amd64_microsoft.windows.common-controls_6595b6414 +4ccf1df_6.0.6000.16386_none_1559f1c6f365a7fa\COMCTL32.dll at 000007fe`fbda0000 +0904.1014: Load module C:\Windows\system32\SHELL32.dll at 000007fe`fd4a0000 +0904.1014: Load module C:\Windows\system32\WINSPOOL.DRV at 000007fe`f77d0000 +0904.1014: Load module C:\Windows\system32\ole32.dll at 000007fe`feb10000 +0904.1014: Load module C:\Windows\system32\OLEAUT32.dll at 000007fe`feeb0000 +Last event: Break instruction exception - code 80000003 (first chance) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.eventlog%20%28Display%20Recent%20Events%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-evlog.md b/windows-driver-docs-pr/debugger/-evlog.md new file mode 100644 index 0000000000..c47d786fc9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-evlog.md @@ -0,0 +1,253 @@ +--- +title: evlog +description: The evlog extension displays, changes, or backs up the event log. +ms.assetid: 72038e3e-ff12-4df1-8f55-c02258d764aa +keywords: ["event log", "evlog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- evlog +api_type: +- NA +--- + +# !evlog + + +The **!evlog** extension displays, changes, or backs up the event log. + +``` +!evlog addsource [-d] [-s Source] [-t Type] [-f MsgFile] +!evlog backup [-d] [-l EventLog] [-f BackupFile] +!evlog clear [-!] [-d] [-l EventLog] [-f BackupFile] +!evlog info +!evlog option [-d] [-!] [-n Count] [ -l EventLog [ -+ | -r RecordBound ]] [-o Order] [-w Width] +!evlog read [-d] [-l EventLog] [-s Source] [-e ID] [-c Category] [-t Type] [-n Count] [-r Record] +!evlog report [-s Source] [-e ID] [-c Category] [-t Type] Message +!evlog [Option] -? +``` + +## Parameters + + + **addsource** +Adds an event source to the registry. By default, this only adds events from the DebuggerExtensions source (to support **!evlog report**). + + **backup** +Makes a backup of the specified event log and writes it to a file. + + **clear** +Erases the specified event log, and optionally creates a file recording its old contents. + + **info** +Displays summary information about the event log. + + **option** +Sets the default search options. These options will be used in future **!evlog read** commands. + + **read** +Displays a list of events logged to the specified event log. Details of this display -- such as the number of records displayed and the chronological order of the display -- can be controlled by the **!evlog read** parameters or by a previous use of **!evlog option**. + + **report** +Writes an event record to the application event log. + + **-d** +Specifies that all default values should be used. The **-d** option is only required if you are omitting all other parameters. However, with the **!evlog option** command this option displays the existing default settings. + + **-!** +With **!evlog option**, this resets all defaults. With **!evlog clear**, this prevents a backup file from being written. + + *Source* +Specifies the event source. The default value is **DebuggerExtensions**. + + *Type* +Specifies the success type. Possible *Type* values are 1 (Error), 2 (Warning), 4 (Information), 8 (Audit\_Success), or 16 (Audit\_Failure). A value of 0 represents Success. For **!evlog read** and **!evlog report**, the default is Success (0). For **!evlog addsource**, these bits can be combined, and the default is all bits (31). + + *MsgFile* +Specifies the path and file name of the message file. If the path is omitted, the directory of the current Uext.dll is used. + + *EventLog* +For **!evlog read**, **!evlog backup**, and **!evlog clear**, *EventLog* specifies the event log from which to read. The possible values are **Application**, **System**, and **Security**. The default is **Application**. + +For **!evlog option**, *EventLog* specifies the event log whose maximum count is to be set. The possible values are **All**, **Application**, **System**, and **Security**. The default is **All**. + + *BackupFile* +Specifies the path and file name of the backup file. The default location is the current directory. The default file name is *EventLog*\_backup.evt, where *EventLog* is the event log used in this command. If this file already exists, the command will be terminated. + + *Count* +Specifies the maximum number of records to retrieve. The default is 20. + + **-+** +Specifies that the current maximum record number should be the highest record number retrieved in future **!evlog read** commands. (In other words, no records will be shown as long as the search is performed forward.) + + *RecordBound* +Specifies the highest record number to retrieve in future **!evlog read** commands. If zero is specified, no bound is set -- this is the default. + + *Record* +If **-n** **** *Count* is not included, **-r** **** *Record* specifies the record number to retrieve. If **-n** **** *Count* is included, *Record* specifies the record number at which the display should begin. + + *Order* +Specifies the search order, either **Forwards** or **Backwards**. The default is **Forwards**. A backward search order causes searches to start from the most recent record logged to the event log, and continue in reverse-chronological order as matching records are found. + + *Width* +Specifies the data display width, in characters. This is the width displayed in the Data section. The default is 8 characters. + + *ID* +Specifies the prefix to display before the event. Possible values are 0 (no prefix), 1000 (Information), 2000 (Success), 3000 (Warning), and 4000 (Error). + +The default is 0. + + *Category* +Specifies the event category. + +Possible values are 0 (no category), 1 (Devices), 2 (Disk), 3 (Printers), 4 (Services), 5 (Shell), 6 (System\_Event), and 7 (Network). The default is 0. + + *Message* +Specifies a text message to add to the event description. + + *Option* +Specifies the **!evlog** option whose help text is to be displayed. + + **-?** +Displays some brief Help text for this extension or one of its options in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Uext.dll

Windows XP and later

Uext.dll

+ +  + +The **!evlog** extension can only be used during live debugging. + +Remarks +------- + +After you have added an event source to the registry with **!evlog addsource**, you can view the values with [**!dreg**](-dreg.md). For example: + +``` +0:000> !dreg hklm\system\currentcontrolset\services\eventlog\Application\!* +``` + +The **!evlog option** command is used to set new defaults for the **!evlog read** command. This lets you avoid retyping all the parameters every time you use **!evlog read**. Setting a maximum record bound with the **-+** parameter or the **-r** **** *Records* parameter allows you to terminate all searches after a known record number is encountered. This can be useful if you are only interested in all records logged after a certain event. + +Before using **!evlog report**, you should use **!evlog addsource** to configure an event source in the registry. After this has been configured, the event viewer will recognize the various event IDs. + +Here is an example of the **!evlog info** extension: + +``` +## 0:000> !evlog info -? + +Application Event Log: +# Records : 4362 + Oldest Record # : 1 + Newest Record # : 4362 +## Event Log Full : false + +System Event Log: +# Records : 2296 + Oldest Record # : 1 + Newest Record # : 2296 +## Event Log Full : false + +Security Event Log: +# Records : 54544 + Oldest Record # : 1 + Newest Record # : 54544 +## Event Log Full : false + + +0:000> !evlog option -n 4 +## Default EvLog Option Settings: + +Max Records Returned: 4 +Search Order: Backwards +## Data Display Width: 8 + +Bounding Record Numbers: + Application Event Log: 0 + System Event Log: 0 +## Security Event Log: 0 + + +0:000> !evlog read -l application +-------------- 01 -------------- +Record #: 4364 + +Event Type: Error (1) +Event Source: Userenv +Event Category: None (0) +Event ID: 1000 (0xC00003E8) +Date: 06/06/2002 +Time: 18:03:17 +Description: (1 strings) +The Group Policy client-side extension Security was passed flags (17) and returned a failure status code of (87). + +-------------- 02 -------------- +Record #: 4363 + +Event Type: Warning (2) +Event Source: SceCli +Event Category: None (0) +Event ID: 1202 (0x800004B2) +Date: 06/06/2002 +Time: 18:03:17 +Description: (1 strings) +0x57 : The parameter is incorrect. +Please look for more details in TroubleShooting section in Security Help. + +-------------- 03 -------------- +Record #: 4362 + +Event Type: Error (1) +Event Source: Userenv +Event Category: None (0) +Event ID: 1000 (0xC00003E8) +Date: 06/06/2002 +Time: 16:04:08 +Description: (1 strings) +The Group Policy client-side extension Security was passed flags (17) and returned a failure status code of (87). + +-------------- 04 -------------- +Record #: 4361 + +Event Type: Warning (2) +Event Source: SceCli +Event Category: None (0) +Event ID: 1202 (0x800004B2) +Date: 06/06/2002 +Time: 16:04:08 +Description: (1 strings) +0x57 : The parameter is incorrect. +Please look for more details in TroubleShooting section in Security Help. +WARNING: Max record count (4) exceeded, increase record count to view more +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!evlog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-exca.md b/windows-driver-docs-pr/debugger/-exca.md new file mode 100644 index 0000000000..c2fcb61ea3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exca.md @@ -0,0 +1,74 @@ +--- +title: exca +description: The exca extension displays PC-Card Interrupt Controller (PCIC) Exchangable Card Architecture (ExCA) registers. +ms.assetid: a395f7f3-0e1d-4f4c-80a1-018ca52a20fd +keywords: ["PCIC (PC Card Interrupt Controller)", "ExCA registers", "exca Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- exca +api_type: +- NA +--- + +# !exca + + +The **!exca** extension displays PC-Card Interrupt Controller (PCIC) Exchangable Card Architecture (ExCA) registers. + +``` +!exca BasePort.SocketNumber +``` + +## Parameters + + + *BasePort* +Specifies the base port of the PCIC. + + *SocketNumber* +Specifies the socket number of the ExCA register on the PCIC. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kext.dll +Kdextx86.dll

Windows XP and later

Kext.dll

+ +  + +The **!exca** extension is only available for an x86-based target computer. + +### Additional Information + +The [**!cbreg**](-cbreg.md) extension can be used to display CardBus Socket registers and CardBus ExCA registers by address. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!exca%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-exchain.md b/windows-driver-docs-pr/debugger/-exchain.md new file mode 100644 index 0000000000..c57795a45f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exchain.md @@ -0,0 +1,92 @@ +--- +title: exchain +description: The exchain extension displays the current exception handler chain. +ms.assetid: 6e5c935b-e475-4213-83d8-94510a58fde5 +keywords: ["exchain Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- exchain +api_type: +- NA +--- + +# !exchain + + +The **!exchain** extension displays the current exception handler chain. + +``` +!exchain [Options] +``` + +## Parameters + + + *Options* +One of the following values: + +**/c** +Displays information that is relevant for debugging a C++ **try**/**catch** exception, if such an exception is detected. + +**/C** +Displays information that is relevant for debugging a C++ **try**/**catch** exception, even when such an exception has not been detected. + +**/f** +Displays information that is obtained by walking the CRT function tables, even if a CRT exception handler was not detected. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +The **!exchain** extension is available only for an x86-based target computer. + +Remarks +------- + +The **!exchain** extension displays the list of exception handlers for the current thread. + +The list begins with the first handler on the chain (the one that is given the first opportunity to handle an exception) and continues on to the end. The following example shows this extension. + +``` +0:000> !exchain +0012fea8: Prymes!_except_handler3+0 (00407604) + CRT scope 0, filter: Prymes!dzExcepError+e6 (00401576) + func: Prymes!dzExcepError+ec (0040157c) +0012ffb0: Prymes!_except_handler3+0 (00407604) + CRT scope 0, filter: Prymes!mainCRTStartup+f8 (004021b8) + func: Prymes!mainCRTStartup+113 (004021d3) +0012ffe0: KERNEL32!GetThreadContext+1c (77ea1856) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!exchain%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-excr--display-exception-context-record-.md b/windows-driver-docs-pr/debugger/-excr--display-exception-context-record-.md new file mode 100644 index 0000000000..91027f73a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-excr--display-exception-context-record-.md @@ -0,0 +1,83 @@ +--- +title: .excr (Display Exception Context Record) +description: The .excr command displays the context record that is associated with the current exception. +ms.assetid: 18FD32B9-93DE-4E23-A73C-18CC3665417A +keywords: [".excr (Display Exception Context Record) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .excr (Display Exception Context Record) +api_type: +- NA +--- + +# .excr (Display Exception Context Record) + + +The **.excr** command displays the context record that is associated with the current exception. + +``` +.excr +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Crash dump only (minidumps only)

Platforms

All

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +The **.excr** command locates the current exception's context information and displays the important registers for the specified context record. + +This command also instructs the debugger to use the context record that is associated with the current exception as the register context. After you run **.excr**, the debugger can access the most important registers and the stack trace for this thread. This register context persists until you enable the target to execute, change the current process or thread, or use another register context command ([**.cxr**](-cxr--display-context-record-.md) or **.excr**). For more information about register contexts, see [Register Context](changing-contexts.md#register-context). + +The [**.ecxr**](-ecxr--display-exception-context-record-.md) command is a synonym command and has identical functionality. + +## See also + + +[**.ecxr**](-ecxr--display-exception-context-record-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.excr%20%28Display%20Exception%20Context%20Record%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-exepath--set-executable-path-.md b/windows-driver-docs-pr/debugger/-exepath--set-executable-path-.md new file mode 100644 index 0000000000..176d273b22 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exepath--set-executable-path-.md @@ -0,0 +1,70 @@ +--- +title: .exepath (Set Executable Path) +description: The .exepath command sets or displays the executable file search path. +ms.assetid: 09f8c2f6-4df7-4039-bb92-66d42015c3dc +keywords: [".exepath (Set Executable Path) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .exepath (Set Executable Path) +api_type: +- NA +--- + +# .exepath (Set Executable Path) + + +The **.exepath** command sets or displays the executable file search path. + +``` +.exepath[+] [Directory [; ...]] +``` + +## Parameters + + + **+** +Specifies that the debugger should append the new directories to the previous executable file search path (instead of replacing the path). + + *Directory* +Specifies one or more directories to put in the search path. If you do not specify *Directory*, the current path is displayed. You can separate multiple directories with semicolons. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.exepath%20%28Set%20Executable%20Path%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-expr--choose-expression-evaluator-.md b/windows-driver-docs-pr/debugger/-expr--choose-expression-evaluator-.md new file mode 100644 index 0000000000..3d50a54e11 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-expr--choose-expression-evaluator-.md @@ -0,0 +1,87 @@ +--- +title: .expr (Choose Expression Evaluator) +description: The .expr command specifies the default expression evaluator. +ms.assetid: 96d246c2-10fe-4688-a04f-1325ac51e4b3 +keywords: [".expr (Choose Expression Evaluator) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .expr (Choose Expression Evaluator) +api_type: +- NA +--- + +# .expr (Choose Expression Evaluator) + + +The **.expr** command specifies the default expression evaluator. + +``` +.expr /s masm +.expr /s c++ +.expr /q +.expr +``` + +## Parameters + + + **/s masm** +Changes the default expression type to Microsoft Assembler expression evaluator (MASM). This type is the default value when you start the debugger. + + **/s c++** +Changes the default expression type to the C++ expression evaluator. + + **/q** +Displays the list of possible expression types. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +When you use the **.expr** command without an argument, the debugger displays the current default expression type. + +The [**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) command, the + +Watch window, and the [Locals window](locals-window.md) always use C++ expression syntax. All other commands and debugging information windows use the default expression evaluator. + +For more information about how to control which syntax is used, see [Evaluating Expressions](evaluating-expressions.md). For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.expr%20%28Choose%20Expression%20Evaluator%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-exptr--display-exception-pointers-.md b/windows-driver-docs-pr/debugger/-exptr--display-exception-pointers-.md new file mode 100644 index 0000000000..d37e239e3a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exptr--display-exception-pointers-.md @@ -0,0 +1,67 @@ +--- +title: .exptr (Display Exception Pointers) +description: The .exptr command displays an EXCEPTION_POINTERS structure. +ms.assetid: ef98bf22-10a1-4fd2-80f1-fd7eb75015c1 +keywords: [".exptr (Display Exception Pointers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .exptr (Display Exception Pointers) +api_type: +- NA +--- + +# .exptr (Display Exception Pointers) + + +The **.exptr** command displays an EXCEPTION\_POINTERS structure. + +``` +.exptr Address +``` + +## Parameters + + + *Address* +Specifies the address of the EXCEPTION\_POINTERS structure. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.exptr%20%28Display%20Exception%20Pointers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-exr--display-exception-record-.md b/windows-driver-docs-pr/debugger/-exr--display-exception-record-.md new file mode 100644 index 0000000000..475f22cfb6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exr--display-exception-record-.md @@ -0,0 +1,77 @@ +--- +title: .exr (Display Exception Record) +description: The .exr command displays the contents of an exception record. +ms.assetid: 786d7ee0-45d7-489c-b53b-28349ea10e36 +keywords: ["Display Exception Record (.exr) command", "exception record", ".exr (Display Exception Record) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .exr (Display Exception Record) +api_type: +- NA +--- + +# .exr (Display Exception Record) + + +The **.exr** command displays the contents of an exception record. + +``` +.exr Address +.exr -1 +``` + +## Parameters + + + *Address* +Specifies the address of the exception record. If you specify **-1** as the address, the debugger displays the most recent exception. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.exr**command displays information that is related to an exception that the debugger encountered on the target computer. The information that is displayed includes the exception address, the exception code, the exception flags, and a variable list of parameters to the exception. + +You can usually obtain the *Address* by using the [**!pcr**](-pcr.md) extension. + +The **.exr** command is often used to debug bug check 0x1E. For more information and an example, see [**Bug Check 0x1E**](bug-check-0x1e--kmode-exception-not-handled.md) (KMODE\_EXCEPTION\_NOT\_HANDLED). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.exr%20%28Display%20Exception%20Record%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-exr.md b/windows-driver-docs-pr/debugger/-exr.md new file mode 100644 index 0000000000..e0146e425a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-exr.md @@ -0,0 +1,29 @@ +--- +title: exr +description: exr +ms.assetid: b7ba5e47-07f1-4835-af87-022ddd3857f2 +keywords: ["exr extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !exr + + +## + + +The **!exr** extension command is obsolete. Use the [**.exr (Display Exception Record)**](-exr--display-exception-record-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!exr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-extmatch--display-all-matching-extensions-.md b/windows-driver-docs-pr/debugger/-extmatch--display-all-matching-extensions-.md new file mode 100644 index 0000000000..1cd7b426af --- /dev/null +++ b/windows-driver-docs-pr/debugger/-extmatch--display-all-matching-extensions-.md @@ -0,0 +1,108 @@ +--- +title: .extmatch (Display All Matching Extensions) +description: The .extmatch command displays extension commands exported by the currently loaded extension DLLs that match the specified pattern. +ms.assetid: 068a32ce-c5ac-4fee-9e9d-e47393097675 +keywords: [".extmatch (Display All Matching Extensions) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .extmatch (Display All Matching Extensions) +api_type: +- NA +--- + +# .extmatch (Display All Matching Extensions) + + +The **.extmatch** command displays extension commands exported by the currently loaded extension DLLs that match the specified pattern. + +``` +.extmatch [Options] Pattern +``` + +## Parameters + + + *Options* +Specifies the searching options. You can use one or more of the following options: + +**/e** **** *ExtDLLPattern* +Limits the enumeration to extension commands exported by extension DLLs that match the specified pattern string. *ExtDLLPattern* is matched against the extension DLL filename. + +**/n** +Excludes the extension name when the extensions are displayed. Thus, if this option is specified, then only the extension name itself will be displayed. + + **/D** +Displays the output using [Debugger Markup Language (DML)](debugger-markup-language-commands.md). In the output, each listed extension is a link that you can click to get more information about the extension. Not all extension modules support DML. + + *Pattern* +Specifies a pattern that the extension must contain. *Pattern*can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +To display a list of loaded extension DLLs, use the [**.chain**](-chain--list-debugger-extensions-.md) command. + +Here is an example of this command, showing all the loaded extension DLLs that have an export named !help: + +``` +0:000> .extmatch help +!ext.help +!exts.help +!uext.help +!ntsdexts.help +``` + +The following example lists all extension commands beginning with the string "he" that are exported by extension DLLs whose names begin with the string "ex": + +``` +0:000> .extmatch /e ext* he* +!ext.heap +!ext.help +!exts.heap +!exts.help +``` + +The following example lists all extension commands, so we can see which ones support DML. + +![screen shot of .extmatch /d output](images/extmatch01.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.extmatch%20%28Display%20All%20Matching%20Extensions%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-extpath--set-extension-path-.md b/windows-driver-docs-pr/debugger/-extpath--set-extension-path-.md new file mode 100644 index 0000000000..a892814a3e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-extpath--set-extension-path-.md @@ -0,0 +1,91 @@ +--- +title: .extpath (Set Extension Path) +description: The .extpath command sets or displays the extension DLL search path. +ms.assetid: 957028ff-d8f4-41ab-bdaa-ff1bbe886bec +keywords: [".extpath (Set Extension Path) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .extpath (Set Extension Path) +api_type: +- NA +--- + +# .extpath (Set Extension Path) + + +The **.extpath** command sets or displays the extension DLL search path. + +``` +.extpath[+] [Directory[;...]] +``` + +## Parameters + + + + +Signifies that the debugger should append new directories to the previous extension DLL search path (instead of replacing the path). + + *Directory* +Specifies one or more directories to put in the search path. If you do not specify *Directory*, the current path is displayed. You can separate multiple directories with semicolons. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the extension search path and loading extension DLLs, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +Remarks +------- + +The extension DLL search path is reset to its default value at the start of each debugging session. + +During live kernel-mode debugging, a reboot of the target computer results in the start of a new debugging session. So any changes that you make to the extension DLL search path during kernel-mode debugging will not persist across a reboot of the target computer. + +The default value of the extension DLL search path contains all the extension paths known to the debugger and all the paths in the %PATH% environment variable. For example, suppose your %PATH% environment variable has a value of `C:\Windows\system32;C:\Windows`. Then the default value of the DLL extension search path might look like this. + +``` +0:000> .extpath +Extension search path is: C:\Program Files\Debugging Tools for Windows (x64)\WINXP;C:\Program Files\ +Debugging Tools for Windows (x64)\winext;C:\Program Files\Debugging Tools for Windows (x64)\winext\ +arcade;C:\Program Files\Debugging Tools for Windows (x64);C:\Program Files\Debugging Tools for +Windows (x64)\winext\arcade;C:\Windows\system32;C:\Windows +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.extpath%20%28Set%20Extension%20Path%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-f----f---shift-local-context-.md b/windows-driver-docs-pr/debugger/-f----f---shift-local-context-.md new file mode 100644 index 0000000000..8682e4cc4d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-f----f---shift-local-context-.md @@ -0,0 +1,87 @@ +--- +title: .f+, .f- (Shift Local Context) +description: The .f+ command shifts the frame index to the next frame in the current stack. The .f- command shifts the frame index to the previous frame in the current stack. +ms.assetid: aade5ec0-4d40-4ff1-9d4b-f3ad81b54b79 +keywords: [".f+, .f- (Shift Local Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .f+, .f- (Shift Local Context) +api_type: +- NA +--- + +# .f+, .f- (Shift Local Context) + + +The **.f+** command shifts the frame index to the next frame in the current stack. The **.f-** command shifts the frame index to the previous frame in the current stack. + +``` +.f+ +.f- +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the local context and other context settings, see [Changing Contexts](changing-contexts.md). For more information about how to display local variables and other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The *frame* specifies the local context (scope) that the debugger uses to interpret local variables + +The **.f+** and .f- commands are shortcuts for moving to the next and previous frames in the current stack. These commands are equivalent to the following [**.frame**](-frame--set-local-context-.md) commands, but the **.f** commands are shorter for convenience: + +- **.f+** is the same as **.frame @$frame + 1**. + +- **.f-** is the same as **.frame @$frame - 1**. + +The dollar sign ($) identifies the frame value as a [pseudo-register](pseudo-register-syntax.md). The at sign (@ causes the debugger to access the value more quickly, because it notifies the debugger that a string is a register or pseudo-register. + +When an application is running, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the function that they are defined in. Unless you use an **.f+** or **.f-** command (or a [**.frame**](-frame--set-local-context-.md) command), the debugger uses the scope of the current function (the current frame on the stack) as the local context. + +The *frame number* is the position of the stack frame within the stack trace. You can view this stack trace by using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command or the [Calls window](calls-window.md). The first line (the current frame) represents frame number 0. The subsequent lines represent frame numbers 1, 2, 3, and so on. + +You can set the local context to a different stack frame to view new local variable information. However, the actual variables that are available depend on the code that is executed. + +The debugger resets the local context to the scope of the program counter if any program execution occurs. The local context is reset to the top stack frame if the register context is changed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.f+,%20.f-%20%28Shift%20Local%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-f--freeze-thread-.md b/windows-driver-docs-pr/debugger/-f--freeze-thread-.md new file mode 100644 index 0000000000..8f17318cbc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-f--freeze-thread-.md @@ -0,0 +1,104 @@ +--- +title: ~f (Freeze Thread) +description: The ~f command freezes the given thread, causing it to stop and wait until it is unfrozen.Do not confuse this command with the f (Fill Memory) command. +ms.assetid: 86fbbcee-c752-4425-a330-4d95a4069b0d +keywords: ["~f (Freeze Thread) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~f (Freeze Thread) +api_type: +- NA +--- + +# ~f (Freeze Thread) + + +The **~f** command freezes the given thread, causing it to stop and wait until it is unfrozen. + +Do not confuse this command with the [**f (Fill Memory)**](f--fp--fill-memory-.md) command. + +``` +~Thread f +``` + +## Parameters + + + *Thread* +Specifies the thread to freeze. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how frozen threads behave and a list of other commands that control the freezing and suspending of threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +The **~f** command causes the specified thread to freeze. When the debugger enables the target application to resume execution, other threads execute as expected while this thread remains stopped. + +The following examples show you how to use this command. The following command displays the current status of all threads. + +``` +0:000> ~* k +``` + +The following command freezes the thread that caused the current exception. + +``` +0:000> ~# f +``` + +The following command checks that the status of this thread is suspended. + +``` +0:000> ~* k +``` + +The following command unfreezes thread number 123. + +``` +0:000> ~123 u +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~f%20%28Freeze%20Thread%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-facs.md b/windows-driver-docs-pr/debugger/-facs.md new file mode 100644 index 0000000000..0d4d86c18c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-facs.md @@ -0,0 +1,52 @@ +--- +title: facs +description: The facs extension displays a Firmware ACPI Control Structure (FACS). +ms.assetid: eb6f5eb6-c1ef-479d-95fa-6faa9ca9d097 +keywords: ["facs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- facs +api_type: +- NA +--- + +# !facs + + +The **!facs** extension displays a Firmware ACPI Control Structure (FACS). + +Syntax + +``` +!facs Address +``` + +## Parameters + + + *Address* +Specifies the address of the FACS. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!facs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fadt.md b/windows-driver-docs-pr/debugger/-fadt.md new file mode 100644 index 0000000000..050620582a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fadt.md @@ -0,0 +1,52 @@ +--- +title: fadt +description: The fadt extension displays a Fixed ACPI Description Table (FADT). +ms.assetid: 700409f8-4f30-438a-a8a8-bad9a25f1d3e +keywords: ["fadt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- fadt +api_type: +- NA +--- + +# !fadt + + +The **!fadt** extension displays a Fixed ACPI Description Table (FADT). + +Syntax + +``` +!fadt Address +``` + +## Parameters + + + *Address* +Specifies the address of the FADT. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!fadt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fiber--set-fiber-context-.md b/windows-driver-docs-pr/debugger/-fiber--set-fiber-context-.md new file mode 100644 index 0000000000..d73c1933e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fiber--set-fiber-context-.md @@ -0,0 +1,71 @@ +--- +title: .fiber (Set Fiber Context) +description: The .fiber command specifies which fiber is used for the fiber context. +ms.assetid: 37473c90-018c-417f-a2b2-3723b9d03ca7 +keywords: ["Set Fiber Context (.fiber) command", "context, Set Fiber Context (.fiber) command", "fibers", ".fiber (Set Fiber Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .fiber (Set Fiber Context) +api_type: +- NA +--- + +# .fiber (Set Fiber Context) + + +The **.fiber** command specifies which fiber is used for the fiber context. + +``` +.fiber [Address] +``` + +## Parameters + + + *Address* +Specifies the address of the fiber. If you omit this parameter or specify zero, the fiber context is reset to the current fiber. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the process context, the register context, and the local context, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.fiber%20%28Set%20Fiber%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-filecache.md b/windows-driver-docs-pr/debugger/-filecache.md new file mode 100644 index 0000000000..df3ee0e085 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-filecache.md @@ -0,0 +1,171 @@ +--- +title: filecache +description: The filecache extension displays information regarding the system file cache memory and PTE use. +ms.assetid: 38dbff14-5144-455c-a9b8-1ac6292f4200 +keywords: ["file cache", "filecache Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- filecache +api_type: +- NA +--- + +# !filecache + + +The **!filecache** extension displays information regarding the system file cache memory and PTE use. + +``` +!filecache [Flags] +``` + +## Parameters + + + *Flags* +Optional. Default value is 0x0. Set *Flags* to 0x1 to sort the output by shared cache map. This way you can locate all the system cache views for a given control area. + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For information about file system drivers, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Each line of this extension's output represents a virtual address control block (VACB). When named files are mapped into the VACB, the names of these files are displayed. If "no name for file" is specified, this means that this VACB is being used to cache metadata. + +Here is an example of the output from this extension from a Windows XP system: + +``` +kd> !filecache +***** Dump file cache****** + Reading and sorting VACBs ... + Removed 1811 nonactive VACBs, processing 235 active VACBs ... +File Cache Information + Current size 28256 kb + Peak size 30624 kb + 235 Control Areas +Skipping view @ c1040000 - no VACB, but PTE is valid! + Loading file cache database (100% of 131072 PTEs) + SkippedPageTableReads = 44 + File cache has 4056 valid pages + + + Usage Summary (in Kb): +Control Valid Standby/Dirty Shared Locked Name +817da668 4 0 0 0 $MftMirr +8177ae68 304 920 0 0 $LogFile +81776160 188 0 0 0 $BitMap +817cf370 4 0 0 0 $Mft +81776a00 8 0 0 0 $Directory +817cfdd0 4 0 0 0 $Directory +81776740 36 0 0 0 No Name for File +817cf7c8 20 0 0 0 $Directory +817cfb98 304 0 0 0 $Directory +8177be40 16 0 0 0 $Directory +817dadc0 2128 68 0 0 $Mft +817cf008 4 0 0 0 $Directory +817d0258 8 4 0 0 $Directory +817763f8 4 0 0 0 $Directory +... +8173f058 4 0 0 0 $Directory +8173e628 32 0 0 0 $Directory +8173e4c8 32 0 0 0 $Directory +8173da38 4 0 0 0 $Directory +817761f8 4 0 0 0 $Directory +81740530 32 0 0 0 $Directory +8173d518 4 0 0 0 $Directory +817d9560 8 0 0 0 $Directory +8173f868 4 0 0 0 $Directory +8173fc00 4 0 0 0 $Directory +81737278 4 0 0 0 $MftMirr +81737c88 44 0 0 0 $LogFile +81735fa0 48 0 0 0 $Mft +81737e88 188 0 0 0 $BitMap +817380b0 4 0 0 0 $Mft +817399e0 4 0 0 0 $Directory +817382b8 4 0 0 0 $Directory +817388d8 12 0 0 0 No Name for File +81735500 8 0 0 0 $Directory +81718e38 232 0 0 0 default +81735d40 48 20 0 0 SECURITY +81723008 8632 0 0 0 software +816da3a0 24 44 0 0 SAM +8173dfa0 4 0 0 0 $Directory +... +8173ba90 4 0 0 0 $Directory +8170ee30 4 36 4 0 AppEvent.Evt +816223f8 4 0 0 0 $Directory +8170ec28 8 28 4 0 SecEvent.Evt +816220a8 4 0 0 0 $Directory +8170ea20 4 32 4 0 SysEvent.Evt +8170d188 232 0 0 0 NTUSER.DAT +81709f10 8 0 0 0 UsrClass.dat +81708918 232 0 0 0 NTUSER.DAT +81708748 8 0 0 0 UsrClass.dat +816c58f8 12 0 0 0 change.log +815c3880 4 0 0 0 $Directory +81706aa8 4 0 0 0 SchedLgU.Txt +815ba2d8 4 0 0 0 $Directory +815aa5f8 8 0 0 0 $Directory +8166d728 44 0 0 0 Netlogon.log +81701120 8 16 4 0 es.dll +816ff0a8 4 8 4 0 stdole2.tlb +8159a358 4 0 0 0 $Directory +8159da70 4 0 0 0 $Directory +8159c158 4 0 0 0 $Directory +815cb9b0 4 0 0 0 00000001 +81779b20 4 0 0 0 $Directory +8159ac20 4 0 0 0 $Directory +815683f8 4 0 0 0 $Directory +81566978 580 0 0 0 NTUSER.DAT +81568460 4 0 0 0 $Directory +815675d8 68 0 0 0 UsrClass.dat +81567640 4 0 0 0 $Directory +... +81515878 4 0 0 0 $Directory +81516870 8 0 0 0 $Directory +8150df60 4 0 0 0 $Directory +... +816e5300 4 0 0 0 $Directory +8152afa0 16 212 0 0 msmsgs.exe +8153bbd8 4 32 0 0 stdole32.tlb +8172f950 488 392 0 0 OBJECTS.DATA +8173e9c0 4 0 0 0 $Directory +814f4538 4 0 0 0 $Directory +81650790 344 48 0 0 INDEX.BTR +814f55f8 4 0 0 0 $Directory +... +814caef8 4 0 0 0 $Directory +8171cd90 1392 36 0 0 system +815f07f0 4 0 0 0 $Directory +814a2298 4 0 0 0 $Directory +81541538 4 0 0 0 $Directory +81585288 28 0 0 0 $Directory +8173f708 4 0 0 0 $Directory +... +8158cf10 4 0 0 0 $Directory +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!filecache%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-filelock.md b/windows-driver-docs-pr/debugger/-filelock.md new file mode 100644 index 0000000000..27d228d1ec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-filelock.md @@ -0,0 +1,56 @@ +--- +title: filelock +description: The filelock extension displays a file lock structure. +ms.assetid: 943a0ed8-b7a5-4ab6-8579-6a27e06e1dac +keywords: ["filelock Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- filelock +api_type: +- NA +--- + +# !filelock + + +The **!filelock** extension displays a file lock structure. + +Syntax + +``` +!filelock FileLockAddress +!filelock ObjectAddress +``` + +## Parameters + + + *FileLockAddress* +Specifies the hexadecimal address of the file lock structure. + + *ObjectAddress* +Specifies the hexadecimal address of a file object that owns the file lock. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about file objects, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!filelock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fileobj.md b/windows-driver-docs-pr/debugger/-fileobj.md new file mode 100644 index 0000000000..e0d7fe0fa8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fileobj.md @@ -0,0 +1,72 @@ +--- +title: fileobj +description: The fileobj extension displays detailed information about a FILE_OBJECT structure. +ms.assetid: ee9237e7-8a1f-473c-9e30-f2b0731a7519 +keywords: ["FILE_OBJECT", "fileobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- fileobj +api_type: +- NA +--- + +# !fileobj + + +The **!fileobj** extension displays detailed information about a FILE\_OBJECT structure. + +``` +!fileobj FileObject +``` + +## Parameters + + + *FileObject* +Specifies the address of a FILE\_OBJECT structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about file objects, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +If the FILE\_OBJECT structure has an associated cache, **!fileobj** tries to parse and display cache information.. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!fileobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-filetime.md b/windows-driver-docs-pr/debugger/-filetime.md new file mode 100644 index 0000000000..2d1cf1b37e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-filetime.md @@ -0,0 +1,73 @@ +--- +title: filetime +description: The filetime extension converts a 64-bit FILETIME structure into a human-readable time. +ms.assetid: 26ee9219-ad37-4b0e-b204-5ed6d93355b0 +keywords: ["FILETIME", "filetime Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- filetime +api_type: +- NA +--- + +# !filetime + + +The **!filetime** extension converts a 64-bit FILETIME structure into a human-readable time. + +``` +!filetime Time +``` + +## Parameters + + + *Time* +Specifies a 64-bit FILETIME structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !filetime 1c4730984712348 + 7/26/2004 04:10:18.712 (Pacific Standard Time) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!filetime%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-finddata.md b/windows-driver-docs-pr/debugger/-finddata.md new file mode 100644 index 0000000000..b9a1572ed9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-finddata.md @@ -0,0 +1,72 @@ +--- +title: finddata +description: The finddata extension displays the cached data at a given offset within a specified file object. +ms.assetid: 1d6f920b-5716-4ccc-8c2d-08b422f57124 +keywords: ["cache manager", "finddata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- finddata +api_type: +- NA +--- + +# !finddata + + +The **!finddata** extension displays the cached data at a given offset within a specified file object. + +``` +!finddata FileObject Offset +``` + +## Parameters + + + *FileObject* +Specifies the address of the file object. + + *Offset* +Specifies the offset. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For information about other cache management extensions, see the [**!cchelp**](-cchelp.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!finddata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-findfilelockowner.md b/windows-driver-docs-pr/debugger/-findfilelockowner.md new file mode 100644 index 0000000000..2d1373c307 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-findfilelockowner.md @@ -0,0 +1,74 @@ +--- +title: findfilelockowner +description: The findfilelockowner extension attempts to find the owner of a file object lock by examining all threads for a thread that is blocked. +ms.assetid: 0d6eabf4-e7ac-4536-beab-d3027720efa8 +keywords: ["findfilelockowner Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- findfilelockowner +api_type: +- NA +--- + +# !findfilelockowner + + +The **!findfilelockowner** extension attempts to find the owner of a file object lock by examining all threads for a thread that is blocked in an IopSynchronousServiceTail assert and that has the file object as a parameter. + +``` +!findfilelockowner [FileObject] +``` + +## Parameters + + + *FileObject* +Specifies the address of a file object. If *FileObject* is omitted, the extension searches for any thread in the current process that is stuck in **IopAcquireFileObjectLock** and retrieves the file object address from the stack trace. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about file objects, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +This extension is most useful after a critical section timeout in which the thread that times out was waiting for the file inside **IopAcquireFileObjectLock**. After the offending thread is found, the extension attempts to recover the IRP that was used for the request and to display the driver that was processing the IRP. + +The extension takes some time to complete because it walks the stack of all threads in the system until it finds the offending thread.You can stop \` at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!findfilelockowner%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-findstack.md b/windows-driver-docs-pr/debugger/-findstack.md new file mode 100644 index 0000000000..24507dca1b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-findstack.md @@ -0,0 +1,129 @@ +--- +title: findstack +description: The findstack extension locates all of the stacks that contain a specified symbol or module. +ms.assetid: 68a696f1-81fb-401e-ad68-ebc616eaf41a +keywords: ["findstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- findstack +api_type: +- NA +--- + +# !findstack + + +The **!findstack** extension locates all of the stacks that contain a specified symbol or module. + +``` +!findstack Symbol [DisplayLevel] +!findstack -? +``` + +## Parameters + + + *Symbol* +Specifies a symbol or module. + + *DisplayLevel* +Specifies what the display should contain. This can be any one of the following values. The default value is 1. + +**0** +Displays only the thread ID for each thread that contains *Symbol*. + +**1** +Displays both the thread ID and the frame for each thread that contains *Symbol*. + +**2** +Displays the entire thread stack for each thread that contains *Symbol*. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Uext.dll

Windows XP and later

Uext.dll

+ +  + +### Additional Information + +For more information about stack traces, see the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands. + +Remarks +------- + +The [**!stacks**](-stacks.md) kernel-mode extension also display information about stacks, including a brief summary of the state of every thread. + +The following are some examples of the output from this extension: + +``` +0:023> !uext.findstack wininet +Thread 009, 2 frame(s) match + * 06 03eaffac 771d9263 wininet!ICAsyncThread::SelectThread+0x22a + * 07 03eaffb4 7c80b50b wininet!ICAsyncThread::SelectThreadWrapper+0xd + +Thread 011, 2 frame(s) match + * 04 03f6ffb0 771cda1d wininet!AUTO_PROXY_DLLS::DoThreadProcessing+0xa1 + * 05 03f6ffb4 7c80b50b wininet!AutoProxyThreadFunc+0xb + +Thread 020, 6 frame(s) match + * 18 090dfde8 771db73a wininet!CheckForNoNetOverride+0x9c + * 19 090dfe18 771c5e4d wininet!InternetAutodialIfNotLocalHost+0x220 + * 20 090dfe8c 771c5d6a wininet!ParseUrlForHttp_Fsm+0x135 + * 21 090dfe98 771bcb2c wininet!CFsm_ParseUrlForHttp::RunSM+0x2b + * 22 090dfeb0 771d734a wininet!CFsm::Run+0x39 + * 23 090dfee0 77f6ad84 wininet!CFsm::RunWorkItem+0x79 + +Thread 023, 9 frame(s) match + * 16 0bd4fe00 771bd256 wininet!ICSocket::Connect_Start+0x17e + * 17 0bd4fe0c 771bcb2c wininet!CFsm_SocketConnect::RunSM+0x42 + * 18 0bd4fe24 771bcada wininet!CFsm::Run+0x39 + * 19 0bd4fe3c 771bd22b wininet!DoFsm+0x25 + * 20 0bd4fe4c 771bd706 wininet!ICSocket::Connect+0x32 + * 21 0bd4fe8c 771bd4cb wininet!HTTP_REQUEST_HANDLE_OBJECT::OpenConnection_Fsm+0x391 + * 22 0bd4fe98 771bcb2c wininet!CFsm_OpenConnection::RunSM+0x33 + * 23 0bd4feb0 771d734a wininet!CFsm::Run+0x39 + * 24 0bd4fee0 77f6ad84 wininet!CFsm::RunWorkItem+0x79 + +0:023> !uext.findstack wininet!CFsm::Run 0 +Thread 020, 2 frame(s) match +Thread 023, 3 frame(s) match + +0:023> !uext.findstack wininet!CFsm 0 +Thread 020, 3 frame(s) match +Thread 023, 5 frame(s) match + +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!findstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-findthreads.md b/windows-driver-docs-pr/debugger/-findthreads.md new file mode 100644 index 0000000000..be6422edcd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-findthreads.md @@ -0,0 +1,119 @@ +--- +title: findthreads +description: The findthreads extension displays summary information about one or more threads on the target system based on supplied search criteria. +ms.assetid: ED14E503-0AF2-4444-81B0-7E00A6E424E5 +keywords: ["findthreads Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- findthreads +api_type: +- NA +--- + +# !findthreads + + +The !findthreads extension displays summary information about one or more threads on the target system based on supplied search criteria. Thread information will be displayed when the associated stack(s) reference the supplied object. This command can be used only during kernel-mode debugging. + +Syntax + +``` +!findthreads [-v][-t |-i |-d |( -a -e | -l )] +``` + +## Parameters + + + **-v** +Displays verbose information on all criteria matches. + + **-t** **** *Thread Address* +The search criteria will be all modules, wait objects, and IRPs for the thread, as well as device objects and modules generated from the attached IRPs. This option will generally provide the broadest search criteria. + + **-i** **** *IRP Address* +The search criteria will be all modules and devices for the indicated IRP, as well as any reference to the IRP itself. + + **-d** **** *Device Address* +The search criteria will be based from the device object. This will include the module associated with the device object (through the driver object), the device extension, any IRP attached to the device, and similar information for any attached to the device object. + + **-a** **** *Pointer Address* +Add a base address to the criteria. If -e or -l is correctly specified, this value will be the base of a memory range. Otherwise it is interpreted as a pointer. + + **-e** **** *End Address* +Specifies the end address of the memory range specified with -a. + + **-l** **** *Range Length* +Specifies the length of the memory range specified with -a. + +### DLL + + ++++ + + + + + + +

Windows 10 and later

Kdexts.dll

+ +  + +### Additional Information + +For information about threads in kernel mode, see [Changing Contexts](changing-contexts.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +Here is example output using the -v and -t options: + +``` +kd> !findthreads -v -t ffffd001ee29cdc0 + +Added criterion for THREAD 0xffffd001ee29cdc0 + Added criterion for THREAD STACK 0xffffd001ee2bac20 + ERROR: Object 0xffffffffffffffe0 is not an IRP +ERROR: unable to completely walk thread IRP list. + Added criterion for MODULE kdnic(0xfffff80013120000) + +Found 63 threads matching the search criteria + +Found 6 criteria matches for THREAD 0xffffe0016a383740, PROCESS 0xffffe0016a220200 + Kernel stack location 0xffffd001f026a0c0 references THREAD 0xffffd001ee29cdc0 + Kernel stack location 0xffffd001f026a418 references THREAD 0xffffd001ee29cdc0 + Kernel stack location 0xffffd001f026a460 references THREAD 0xffffd001ee29cdc0 + Kernel stack location 0xffffd001f026a4d0 references THREAD 0xffffd001ee29cdc0 + Kernel stack location 0xffffd001f026a4f0 references THREAD 0xffffd001ee29cdc0 + Kernel stack location 0xffffd001f026a670 references THREAD 0xffffd001ee29cdc0 + + + ffffd001f026a0e0 nt!KiSwapContext+76 + ffffd001f026a190 nt!KiSwapThread+1c8 + ffffd001f026a220 nt!KiCommitThreadWait+148 + ffffd001f026a2e0 nt!KeWaitForMultipleObjects+21e + ffffd001f026a800 nt!ObWaitForMultipleObjects+2b7 + ffffd001f026aa80 nt!NtWaitForMultipleObjects+f6 + 000000c8d220fa98 nt!KiSystemServiceCopyEnd+13 + 000000c8d220fa98 ntdll!ZwWaitForMultipleObjects+a +... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!findthreads%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-findxmldata.md b/windows-driver-docs-pr/debugger/-findxmldata.md new file mode 100644 index 0000000000..244a7ef51e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-findxmldata.md @@ -0,0 +1,142 @@ +--- +title: findxmldata +description: The findxmldata extension retrieves XML data from a CAB file that contains a kernel-mode Small Memory Dump file. +ms.assetid: 6d0b5294-b086-4b33-ac0d-0428521a3489 +keywords: ["XML data in CAB files", "sysdata.xml", "findxmldata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- findxmldata +api_type: +- NA +--- + +# !findxmldata + + +The **!findxmldata** extension retrieves XML data from a CAB file that contains a kernel-mode Small Memory Dump file. + +``` +!findxmldata [ -d DeviceName | -h HwId ] +!findxmldata -r Driver +!findxmldata -chksum [ -z CabFile ] +!findxmldata -v +``` + +## Parameters + + + **-d** *DeviceName* +Displays all devices whose device name contains the string that *DeviceName* specifies. + + **-h** *HwId* +Displays all devices whose hardware IDs contain the string that *HwId* specifies. If you use both **-d** and **-h**, the debugger displays only those devices that satisfy both matches. + + **-r** *Driver* +Displays information about the driver that the *Driver* parameter specifies, including all devices that use this driver. + + **-chksum** +Displays the XML file's checksum. + + **-z** *CabFile* +Enables you to perform a checksum on the CAB file that the CabFile parameter specifies, instead of on the default Sysdata.xml file. + + **-v** +Displays system version information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +The **!findxmldata** extension works only on a kernel-mode Small Memory Dump file that is stored in a CAB file. + +### Additional Information + +For more information about how to put dump files into CAB files, see [**.dumpcab (Create Dump File CAB)**](-dumpcab--create-dump-file-cab-.md). For information more about how to debug a kernel-mode dump file, including dump files that are stored inside CAB files, see [Analyzing a Kernel-Mode Dump File](analyzing-a-kernel-mode-dump-file.md). + +Remarks +------- + +The **!findxmldata** extension retrieves data from the Sysdata.xml file that is stored in a CAB file that contains a kernel-mode [Small Memory Dump](small-memory-dump.md) file. + +When you do not use any options, the extension displays all devices. + +The following examples show you how to use **!findxmldata**. + +``` +kd> !findxmldata -v +SYSTEM Info: +OSVER: 5.1.2600 2.0 +OSLANGUAGE: 2052 +OSNAME: Microsoft Windows XP Home Edition +kd> !findxmldata -d MIDI +Node DEVICE + DESCRIPTION : MPU-401 Compatible MIDI Device + HARDWAREID : ACPI\PNPB006 + SERVICE : ms_mpu401 + DRIVER : msmpu401.sys + +kd> !findxmldata -r msmpu +Node DRIVER + FILENAME : msmpu401.sys + FILESIZE : 2944 + CREATIONDATE : 05-06-2005 09:18:34 + VERSION : 5.1.2600.0 + MANUFACTURER : Microsoft Corporation + PRODUCTNAME : Microsoft« Windows« Operating System +Node DEVICE + DESCRIPTION : MPU-401 Compatible MIDI Device + HARDWAREID : ACPI\PNPB006 + SERVICE : ms_mpu401 + DRIVER : msmpu401.sys + +kd> !findxmldata -h PCI\VEN_8086&DEV_24C3&SUBSYS_24C28086 +Node DEVICE + DESCRIPTION : Intel(R) 82801DB/DBM SMBus Controller - 24C3 + HARDWAREID : PCI\VEN_8086&DEV_24C3&SUBSYS_24C28086&REV_01 +kd> !findxmldata -h USB\ROOT_HUB&VID8086&PID24C4&REV0001 +Node DEVICE + DESCRIPTION : USB Root Hub + HARDWAREID : USB\ROOT_HUB&VID8086&PID24C4&REV0001 + SERVICE : usbhub + DRIVER : usbhub.sys + +kd> !findxmldata -h ACPI\PNPB006 +Node DEVICE + DESCRIPTION : MPU-401 Compatible MIDI Device + HARDWAREID : ACPI\PNPB006 + SERVICE : ms_mpu401 + DRIVER : msmpu401.sys +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!findxmldata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fiximports--fix-target-module-imports-.md b/windows-driver-docs-pr/debugger/-fiximports--fix-target-module-imports-.md new file mode 100644 index 0000000000..df1759d430 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fiximports--fix-target-module-imports-.md @@ -0,0 +1,74 @@ +--- +title: .fiximports (Fix Target Module Imports) +description: The .fiximports command validates and corrects all static import links for a target module. +ms.assetid: 584a5060-5ab5-4126-bfec-e2fe647d50ff +keywords: ["Fix Target Module Imports (.fiximports) command", ".fiximports (Fix Target Module Imports) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .fiximports (Fix Target Module Imports) +api_type: +- NA +--- + +# .fiximports (Fix Target Module Imports) + + +The **.fiximports** command validates and corrects all static import links for a target module. + +``` +.fiximports Module +``` + +## Parameters + + + *Module* +Specifies the target module whose imports the debugger corrects. *Module* can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). If you want to include spaces in *Module*, you must enclose the parameter in quotation marks. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Crash dump only (minidump only)

Platforms

All

+ +  + +Remarks +------- + +You can use the **.fiximports** command only when the target is a minidump that does not contain its own executable images. + +When the debugger maps images for use as memory, the debugger does not automatically connect image imports to exporters. Therefore, instructions that refer to imports are disassembled in the same manner as in a live debugging session. You can use **.fiximports** to request that the debugger perform the appropriate import linking. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.fiximports%20%28Fix%20Target%20Module%20Imports%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-flash-on-break--flash-on-break-.md b/windows-driver-docs-pr/debugger/-flash-on-break--flash-on-break-.md new file mode 100644 index 0000000000..f79f379693 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-flash-on-break--flash-on-break-.md @@ -0,0 +1,79 @@ +--- +title: .flash_on_break (Flash on Break) +description: The .flash_on_break command specifies whether the WinDbg taskbar entry flashes when WinDbg is minimized and the target breaks. +ms.assetid: b2f0a8c5-5b32-44f4-9546-c75859476ce0 +keywords: [".flash_on_break (Flash on Break) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .flash_on_break (Flash on Break) +api_type: +- NA +--- + +# .flash\_on\_break (Flash on Break) + + +The **.flash\_on\_break** command specifies whether the WinDbg taskbar entry flashes when WinDbg is minimized and the target breaks. + +``` +.flash_on_break on +.flash_on_break off +.flash_on_break +``` + +## Parameters + + + **on** +Causes the WinDbg taskbar entry to flash if WinDbg is minimized and the target breaks into the debugger. This is the default behavior for WinDbg. + + **off** +Prevents the WinDbg taskbar entry from flashing. + +### Environment + +The **.flash\_on\_break** command is available only in WinDbg. You cannot use this command in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +If you use the **.flash\_on\_break** command without parameters, the debugger displays the current flash setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.flash_on_break%20%28Flash%20on%20Break%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fnent--display-function-data-.md b/windows-driver-docs-pr/debugger/-fnent--display-function-data-.md new file mode 100644 index 0000000000..17b12711ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fnent--display-function-data-.md @@ -0,0 +1,95 @@ +--- +title: .fnent (Display Function Data) +description: The .fnent command displays information about the function table entry for a specified function. +ms.assetid: 914caf55-2fbf-4f30-af6e-e666dc47c7da +keywords: ["Display Function Data (.fnent) command", ".fnent (Display Function Data) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .fnent (Display Function Data) +api_type: +- NA +--- + +# .fnent (Display Function Data) + + +The **.fnent** command displays information about the function table entry for a specified function. + +``` +.fnent Address +``` + +## Parameters + + + *Address* +Specifies the address of the function. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The symbol search algorithm for the **.fnent** command is the same as that of the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) command. The display first shows the nearest symbols. Then, the debugger displays the function entry for the first of these symbols. + +If the nearest symbol is not in the function table, no information is displayed. + +The following example shows a possible display. + +``` +0:001> .fnent 77f9f9e7 +Debugger function entry 00b61f50 for: +(77f9f9e7) ntdll!RtlpBreakWithStatusInstruction | (77f9fa98) ntdll!DbgPrintReturnControlC + +Params: 1 +Locals: 0 +Registers: 0 + +0:001> .fnent 77f9fa98 +Debugger function entry 00b61f70 for: +(77f9fa98) ntdll!DbgPrintReturnControlC | (77f9fb21) ntdll!DbgPrompt + +Non-FPO + +0:001> .fnent 01005a60 +No function entry for 01005a60 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.fnent%20%28Display%20Function%20Data%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fnret--display-function-return-value-.md b/windows-driver-docs-pr/debugger/-fnret--display-function-return-value-.md new file mode 100644 index 0000000000..aca6765f9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fnret--display-function-return-value-.md @@ -0,0 +1,80 @@ +--- +title: .fnret (Display Function Return Value) +description: The .fnret command displays information about a function's return value. +ms.assetid: b7ce3047-5b0a-43ba-877f-76235139d66c +keywords: [".fnret (Display Function Return Value) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .fnret (Display Function Return Value) +api_type: +- NA +--- + +# .fnret (Display Function Return Value) + + +The **.fnret** command displays information about a function's return value. + +``` +.fnret [/s] Address [Value] +``` + +## Parameters + + + **/s** +Sets the **$callret** pseudo-register equal to the return value that is being displayed, including type information. + + *Address* +Specifies the address of the function. + + *Value* +Specifies the return value to display. If you include *Value*, **.fnret** casts *Value* to the return type of the specified function and displays it in the format of the return type. If you omit *Value*, the debugger obtains the return value of the function from the return value registers. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +If you include the *Value* parameter, the **.fnret** command only casts this value to the proper type and displays the results. + +If you omit *Value*, the debugger uses the return value registers to determine this value. If a function has returned more recently than the function that the *Address* parameter specifies, the value that is displayed will probably not be a value that this function returned. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.fnret%20%28Display%20Function%20Return%20Value%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-frame.md b/windows-driver-docs-pr/debugger/-for-each-frame.md new file mode 100644 index 0000000000..72d9090782 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-frame.md @@ -0,0 +1,86 @@ +--- +title: for_each_frame +description: The for_each_frame extension executes a debugger command one time for each frame in the stack of the current thread. +ms.assetid: 7294dc5e-190f-486f-9079-1fb28d6d484b +keywords: ["for_each_frame Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_frame +api_type: +- NA +--- + +# !for\_each\_frame + + +The **!for\_each\_frame** extension executes a debugger command one time for each frame in the stack of the current thread. + +``` +!for_each_frame ["CommandString"] +!for_each_frame -? +``` + +## Parameters + + + *CommandString* +Specifies the debugger commands to execute one time for each frame. If *CommandString* includes multiple commands, you must separate them with semicolons and enclose *CommandString* in quotation marks. If you include multiple commands, the individual commands within *CommandString* cannot contain quotation marks. If you want to refer to the index of the current frame within *CommandString*, use the @$frame pseudoregister. + + **-?** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about the local context, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +If you do not specify any arguments, the **!for\_each\_frame** extension displays a list of all frames and their frame indexes. For a more detailed list of all frames, use the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. + +The [**k**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command walks up to 256 frames. For each enumerated frame, that frame temporarily becomes the current local context (similar to the [**.frame (Set Local Context)**](-frame--set-local-context-.md) command). After the context has been set, *CommandString* is executed. After all frames have been used, the local context is reset to the value that it had before you used the **!for\_each\_frame** extension. + +If you include *CommandString*, the debugger displays the frame and its index before the command is executed for that frame. + +The following command displays all local variables for the current stack. + +``` +!for_each_frame !for_each_local dt @#Local +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_frame%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-function.md b/windows-driver-docs-pr/debugger/-for-each-function.md new file mode 100644 index 0000000000..79f26780bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-function.md @@ -0,0 +1,175 @@ +--- +title: for_each_function +description: The for_each_function extension executes a debugger command for each function, in a specified module, whose name matches a specified pattern. +ms.assetid: D51C3562-3D49-4528-A208-71A8756EBC8E +keywords: ["for_each_function Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_function +api_type: +- NA +--- + +# !for\_each\_function + + +The **!for\_each\_function** extension executes a debugger command for each function, in a specified module, whose name matches a specified pattern. + +``` +!for_each_function -m:ModuleName -p:Pattern -c:CommandString +!for_each_function -? +``` + +## Parameters + + + -m:*ModuleName* +Specifies the module name. This name is typically the file name without the file name extension. In some cases, the module name differs significantly from the file name. + +-p:*Pattern* +Specifies the pattern to be matched. + + -c:*CommandString* +Specifies the debugger command to execute for each function, in the specified module, that matches the pattern. + +You can use the following aliases in *CommandString*. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AliasData typeValue

@#SymbolName

string

The symbol name.

@#SymbolAddress

ULONG64

The symbol address.

@#ModName

string

The module name.

@#FunctionName

string

The function name.

+ +  + + -? +Displays help for this extension. + +### DLL + +Ext.dll + +Remarks +------- + +The following example shows how to list all function names, in the PCI module, that match the pattern \*read\*. + +``` +1: kd> !for_each_function -m:pci -p:*read* -c:.echo @#FunctionName + +PciReadDeviceConfig +PciReadDeviceSpace +PciReadSlotIdData +PciExternalReadDeviceConfig +PiRegStateReadStackCreationSettingsFromKey +VmProxyReadDevicePathsFromRegistry +PpRegStateReadCreateClassCreationSettings +ExpressRootPortReadConfigSpace +PciReadRomImage +PciDevice_ReadConfig +PciReadDeviceConfigEx +PciReadSlotConfig +``` + +If an alias is not preceded and followed by a blank space, you must put the alias inside the [**${} Alias Interpreter**](-------alias-interpreter-.md) token. + +The following example shows how to list all symbols, in all modules, whose function names match the pattern \*CreateFile\*. The alias @\#ModuleName is not preceded by a blank space. Therefore, it is put inside the [**${} Alias Interpreter**](-------alias-interpreter-.md) token. + +**Note**  Do not confuse the @\#ModuleName alias with the @\#ModName alias. The @\#ModuleName alias belongs to the [**!for\_each\_module**](-for-each-module.md) extension, and the @\#ModName alias belongs to the **!for\_each\_function** extension. + +  + +``` +1: kd> !for_each_module !for_each_function -m:${@#ModuleName} -p:*CreateFile* -c:.echo @#SymbolName +nt!BiCreateFileDeviceElement +nt!NtCreateFile +... +Wdf01000!FxFileObject::_CreateFileObject +fltmgr!FltCreateFileEx2$fin$0 +fltmgr!FltCreateFileEx2 +... +Ntfs!TxfIoCreateFile +Ntfs!NtfsCreateFileLock +... +MpFilter!MpTxfpCreateFileEntryUnsafe +mrxsmb10!MRxSmbFinishLongNameCreateFile +... +srv!SrvIoCreateFile +``` + +You can put a sequence of commands in a command file, and use [**$$>< (Run Script File)**](-----------------------a---run-script-file-.md) to execute those commands for each function that matches the pattern. Suppose that a file named Commands.txt contains the following commands: + +``` +.echo +.echo @#FunctionName +u @#SymbolAddress L1 +``` + +In the following example, the commands in the Commands.text file are executed for each function, in the PCI module, that matches the pattern \*read\*. + +``` +1: kd> !for_each_function -m:pci -p:*read* -c:$$>See also + + +[**!for\_each\_module**](-for-each-module.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_function%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-local.md b/windows-driver-docs-pr/debugger/-for-each-local.md new file mode 100644 index 0000000000..d5fc22af2a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-local.md @@ -0,0 +1,82 @@ +--- +title: for_each_local +description: The for_each_local extension executes a debugger command one time for each local variable in the current frame. +ms.assetid: 2b1d65e6-6322-404e-a94b-90a46035fe9e +keywords: ["for_each_local Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_local +api_type: +- NA +--- + +# !for\_each\_local + + +The **!for\_each\_local** extension executes a debugger command one time for each local variable in the current frame. + +``` +!for_each_local ["CommandString"] +!for_each_local -? +``` + +## Parameters + + + *CommandString* +Specifies the debugger commands to execute one time for each local variable in the current stack frame. If *CommandString* includes multiple commands, you must separate them with semicolons and enclose *CommandString* in quotation marks. If you include multiple commands, the individual commands in *CommandString* cannot contain quotation marks. + +Within *CommandString*, or within any script that the commands in *CommandString* execute, you can use the **@\#Local** alias. This alias is replaced by the name of the local variable. This replacement occurs before *CommandString* is executed and before any other parsing occurs. This alias is case sensitive, and you must add a space before it and add a space after it, even if you enclose the alias in parentheses. If you use C++ expression syntax, you must reference this alias as **@@( @\#Local )**. + +This alias is available only during the lifetime of the call to **!for\_each\_local**. Do not confuse this alias with pseudo-registers, fixed-name aliases, or user-named aliases. + + **-?** +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about how to display and change local variables and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +If you do not specify any arguments, the **!for\_each\_local** extension lists local variables. For more information about the local variables, use the [**dv (Display Local Variables)**](dv--display-local-variables-.md) command. + +If you enable verbose debugger output, the display includes the total number of local variables when the extension is called, and every time that *CommandString* is executed for a local variable, that variable and the text of *CommandString* are echoed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_local%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-module.md b/windows-driver-docs-pr/debugger/-for-each-module.md new file mode 100644 index 0000000000..bb480c5d2a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-module.md @@ -0,0 +1,253 @@ +--- +title: for_each_module +description: The for_each_module extension executes a debugger command one time for each loaded module. +ms.assetid: 607947d8-be06-4012-8901-13bf27e382b1 +keywords: ["for_each_module Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_module +api_type: +- NA +--- + +# !for\_each\_module + + +The **!for\_each\_module** extension executes a debugger command one time for each loaded module. + +``` +!for_each_module ["CommandString"] +!for_each_module -? +``` + +## Parameters + + + *CommandString* +Specifies the debugger commands to execute one time for each module in the debugger's module list. If *CommandString* includes multiple commands, you must separate them with semicolons and enclose *CommandString* in quotation marks. If you include multiple commands, the individual commands within *CommandString* cannot contain quotation marks. + +You can use the following aliases in *CommandString* or in any script that the commands in *CommandString* executes. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AliasData typeValue

@#FileVersion

string

The file version of the module.

@#ProductVersion

string

The product version of the module.

@#ModuleIndex

ULONG

The module number. Modules are enumerated consecutively, starting with zero.

@#ModuleName

string

The module name. This name is typically the file name without the file name extension. In some situations, the module name differs significantly from the file name.

@#ImageName

string

The name of the executable file, including the file name extension. Typically, the full path is included in user mode but not in kernel mode.

@#LoadedImageName

string

Unless Microsoft CodeView symbols are present, this alias is the same as the image name.

@#MappedImageName

string

In most situations, this alias is NULL. If the debugger is mapping an image file (for example, during minidump debugging), this alias is the name of the mapped image.

@#SymbolFileName

string

The path and name of the symbol file. If you have not loaded any symbols, this alias is the name of the executable file instead.

@#ModuleNameSize

ULONG

The string length of the module name string, plus one.

@#ImageNameSize

ULONG

The string length of the image name string, plus one.

@#LoadedImageNameSize

ULONG

The string length of the loaded image name string, plus one.

@#MappedImageNameSize

ULONG

The string length of the mapped image name string, plus one.

@#SymbolFileNameSize

ULONG

The string length of the symbol file name string, plus one.

@#Base

ULONG64

The address of the start of the image.

@#Size

ULONG

The size of the image, in bytes.

@#End

ULONG64

The address of the end of the image.

@#TimeDateStamp

ULONG

The time and date stamp of the image. If you want to expand this time and date stamp into a readable date, use the [.formats (Show Number Formats)](-formats--show-number-formats-.md) command.

@#Checksum

ULONG

The checksum of the module.

@#Flags

ULONG

The module flags. For a list of the DEBUG_MODULE_Xxx values, see Dbgeng.h.

@#SymbolType

USHORT

The symbol type. For a list of the DEBUG_SYMTYPE_Xxx values, see Dbgeng.h.

+ +  + +These aliases are all replaced before *CommandString* is executed for each module and before any other parsing occurs. These aliases are case sensitive. You must add a space before the alias and a space after it, even if the alias is enclosed in parentheses. If you use C++ expression syntax, you must reference these aliases as @@( @\#*alias*). + +These aliases are available only during the lifetime of the call to **!for\_each\_module**. Do not confuse them with pseudo-registers, fixed-name aliases, or user-named aliases. + + -? +Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about how to define and use aliases as shortcuts for entering character strings (including use of the ${ } token), see [Using Aliases](using-aliases.md). + +Remarks +------- + +If you do not specify any arguments, the **!for\_each\_module** extension displays general information about the loaded modules. This information is similar to the information that the following command shows. + +``` +!for_each_module .echo @#ModuleIndex : @#Base @#End @#ModuleName @#ImageName @#LoadedImageName +``` + +For more information about loaded and unloaded modules, use the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command. + +If you enable verbose debugger output, the debugger displays the total number of loaded and unloaded modules when the extension is called, and the debugger displays detailed information about each module (including the values of each available alias) before *CommandString* is executed for that module. + +The following examples show how to use the **!for\_each\_module** extension. The following commands display the global debug flags. + +``` +!for_each_module x ${@#ModuleName}!*Debug*Flag* +!for_each_module x ${@#ModuleName}!g*Debug* +``` + +The following command checks for binary corruption in every loaded module, by using the [**!chkimg**](-chkimg.md) extension: + +``` +!for_each_module !chkimg @#ModuleName +``` + +The following command searches for the pattern "MZ" in every loaded image. + +``` +!for_each_module s-a @#Base @#End "MZ" +``` + +The following example demonstrates the use of @\#FileVersion and @\#ProductVersion for each module name: + +``` +0:000> !for_each_module .echo @#ModuleName fver = @#FileVersion pver = @#ProductVersion +USER32 fver = 6.0.6000.16438 (vista_gdr.070214-1610) pver = 6.0.6000.16438 +kernel32 fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +ntdll fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +notepad fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +WINSPOOL fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +COMCTL32 fver = 6.10 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +SHLWAPI fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +msvcrt fver = 7.0.6000.16386 (vista_rtm.061101-2205) pver = 7.0.6000.16386 +GDI32 fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +RPCRT4 fver = 6.0.6000.16525 (vista_gdr.070716-1600) pver = 6.0.6000.16525 +SHELL32 fver = 6.0.6000.16513 (vista_gdr.070626-1505) pver = 6.0.6000.16513 +ole32 fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +ADVAPI32 fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +COMDLG32 fver = 6.0.6000.16386 (vista_rtm.061101-2205) pver = 6.0.6000.16386 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_module%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-process.md b/windows-driver-docs-pr/debugger/-for-each-process.md new file mode 100644 index 0000000000..d571e48058 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-process.md @@ -0,0 +1,82 @@ +--- +title: for_each_process +description: The for_each_process extension executes the specified debugger command once for each process in the target. +ms.assetid: 28cc0982-43a4-41ba-a26f-6910cc1b77b8 +keywords: ["for_each_process Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_process +api_type: +- NA +--- + +# !for\_each\_process + + +The **!for\_each\_process** extension executes the specified debugger command once for each process in the target. + +``` +!for_each_process ["CommandString"] +!for_each_process -? +``` + +## Parameters + + + *CommandString* +Specifies the debugger commands to be executed for each process. + +If *CommandString* includes multiple commands, separate them with semicolons (;) and enclose *CommandString* in quotation marks ("). If *CommandString* is enclosed in quotations marks, the individual commands within *CommandString* cannot contain quotation marks. Within *CommandString*, **@\#Process** is replaced by the process address. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + +This extension works only in kernel mode, even though it resides in Ext.dll. + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For general information about processes, see [Threads and Processes](controlling-threads-and-processes.md). For information about manipulating or obtaining information about processes, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +If no arguments are supplied, the debugger displays a list of all processes, along with time and priority statistics. This is equivalent to entering [**!process @\#Process 0**](-process.md) as the *CommandString* value. + +To terminate execution at any point, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-register.md b/windows-driver-docs-pr/debugger/-for-each-register.md new file mode 100644 index 0000000000..0ecd0795a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-register.md @@ -0,0 +1,90 @@ +--- +title: for_each_register +description: The for_each_register extension executes a specified command for each register. +ms.assetid: 496DC161-D082-4C83-A6B6-6BBCE932BE76 +keywords: ["for_each_register Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_register +api_type: +- NA +--- + +# !for\_each\_register + + +The **!for\_each\_register** extension executes a specified command for each register. + +``` +!for_each_register -c:CommandString +!for_each_register -? +``` + +## Parameters + + + **-c:***CommandString* +Specifies the command to be executed for each register. The aliases @\#RegisterName and @\#RegisterValue are valid during the execution of the command. + + **-?** +Displays help for the **!for\_each\_register** extension. + +## DLL + + +Ext.dll + +## Examples + + +This example lists the name of each register. + +``` +0:000> !for_each_register -c:.echo @#RegisterName +rax +rcx +rdx +rbx +... +``` + +This example executes [**!address**](-address.md) for each register value. + +``` +0:000> !for_each_register -c:!address ${@#RegisterValue} +... +Usage: Stack +Base Address: 00000008`a568f000 +End Address: 00000008`a56a0000 +Region Size: 00000000`00011000 +State: 00001000 MEM_COMMIT +Protect: 00000004 PAGE_READWRITE +Type: 00020000 MEM_PRIVATE +Allocation Base: 00000008`a5620000 +Allocation Protect: 00000004 PAGE_READWRITE +More info: ~0k +... +``` + +Remarks +------- + +When an alias is an argument to a debugger extension (for example, [**!address**](-address.md)), use the alias interpreter [**${} (Alias Interpreter)**](-------alias-interpreter-.md) token so that the alias is resolved correctly. + +For more information about how to define and use aliases as shortcuts for entering character strings (including use of the [**${}**](-------alias-interpreter-.md) token), see [Using Aliases](using-aliases.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_register%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for-each-thread.md b/windows-driver-docs-pr/debugger/-for-each-thread.md new file mode 100644 index 0000000000..88853cbace --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for-each-thread.md @@ -0,0 +1,80 @@ +--- +title: for_each_thread +description: The for_each_thread extension executes the specified debugger command once for each thread in the target. +ms.assetid: 4ca8e1bd-1a1b-4fef-a2d9-42c26f9b746b +keywords: ["for_each_thread Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- for_each_thread +api_type: +- NA +--- + +# !for\_each\_thread + + +The **!for\_each\_thread** extension executes the specified debugger command once for each thread in the target. + +``` +!for_each_thread ["CommandString"] +!for_each_thread -? +``` + +## Parameters + + + *CommandString* +Specifies the debugger commands to be executed for each thread. If *CommandString* includes multiple commands, separate them with semicolons (;) and enclose *CommandString* in quotation marks ("). If *CommandString* is enclosed in quotations marks, the individual commands within *CommandString* cannot contain quotation marks. Within *CommandString*, **@\#Thread** is replaced by the thread address. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + +This extension works only in kernel mode, even though it resides in Ext.dll. + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more general information about threads, see [Threads and Processes](controlling-threads-and-processes.md). For more information about manipulating or obtaining information about threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +If no arguments are supplied, the debugger displays a list of all threads, along with thread wait states. This is equivalent to entering [**!thread @\#Thread 2**](-process.md) as the *CommandString* value. + +You can terminate execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!for_each_thread%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-for.md b/windows-driver-docs-pr/debugger/-for.md new file mode 100644 index 0000000000..59524a1676 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-for.md @@ -0,0 +1,68 @@ +--- +title: .for +description: The .for token behaves like the for keyword in C, except that multiple increment commands must be separated by semicolons, not by commas. +ms.assetid: 35f54c4c-e7f5-42a9-b579-1e4958b7286b +keywords: [".for Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .for +api_type: +- NA +--- + +# .for + + +The **.for** token behaves like the **for** keyword in C, except that multiple increment commands must be separated by semicolons, not by commas. + +``` +.for (InitialCommand ; Condition ; IncrementCommands) { Commands } +``` + +## Syntax Elements + + + *InitialCommand* +Specifies a command that will be executed before the loop begins. Only a single initial command is permitted. + + *Condition* +Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing *Condition* in parentheses is optional. *Condition* must be an expression, not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *IncrementCommands* +Specifies one or more commands that will be executed at the conclusion of each loop. If you wish to use multiple increment commands, separate them by semicolons but do not enclose them in braces. + + *Commands* +Specifies one or more commands that will be executed repeatedly as long as the condition is true. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +If all the work is being done by the increment commands, you can omit *Condition* entirely and simply use an empty pair of braces. + +Here is an example of a **.for** statement with multiple increment commands: + +``` +0:000> .for (r eax=0; @eax < 7; r eax=@eax+1; r ebx=@ebx+1) { .... } +``` + +The [**.break**](https://msdn.microsoft.com/library/windows/hardware/ff556242) and [**.continue**](-continue.md) tokens can be used to exit or restart the *Commands* block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.for%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-force-radix-output--use-radix-for-integers-.md b/windows-driver-docs-pr/debugger/-force-radix-output--use-radix-for-integers-.md new file mode 100644 index 0000000000..f4cf342847 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-force-radix-output--use-radix-for-integers-.md @@ -0,0 +1,82 @@ +--- +title: .force_radix_output (Use Radix for Integers) +description: The .force_radix_output command specifies whether integers are displayed in decimal format or in the default radix. +ms.assetid: 9ce79919-69fd-426f-8de1-34d0721c35a5 +keywords: ["Use Radix for Integers (.force_radix_output) command", ".force_radix_output (Use Radix for Integers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .force_radix_output (Use Radix for Integers) +api_type: +- NA +--- + +# .force\_radix\_output (Use Radix for Integers) + + +The **.force\_radix\_output** command specifies whether integers are displayed in decimal format or in the default radix. + +``` +.force_radix_output 0 +.force_radix_output 1 +``` + +## Parameters + + + **0** +Displays all integers (except for long integers) in decimal format. This is the default behavior for the Debugger. + + **1** +Displays all integers (except for long integers) in the default radix. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.force\_radix\_output** command affects the output of the [**dt (Display Type)**](dt--display-type-.md) command. + +In WinDbg, **.force\_radix\_output** also affects the display in the [Locals window](locals-window.md) and the Watch window. You can select or clear **Always display numbers in default radix** on the shortcut menu of the Locals or Watch window to have the same effect as **.force\_radix\_output**. These windows are automatically updated after you issue this command. + +The **.force\_radix\_output** command affects only the display of standard integers. To specify whether long integers are displayed in decimal format or the default radix, use the [**.enable\_long\_status (Enable Long Integer Display)**](-enable-long-status--enable-long-integer-display-.md) command. + +To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.force_radix_output%20%28Use%20Radix%20for%20Integers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-force-tb--forcibly-allow-branch-tracing-.md b/windows-driver-docs-pr/debugger/-force-tb--forcibly-allow-branch-tracing-.md new file mode 100644 index 0000000000..32a59bc1f2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-force-tb--forcibly-allow-branch-tracing-.md @@ -0,0 +1,71 @@ +--- +title: .force_tb (Forcibly Allow Branch Tracing) +description: The .force_tb command forces the processor to trace branches early in the boot process. +ms.assetid: ac4aabfa-6d00-4478-9c13-213bf89f613a +keywords: [".force_tb (Forcibly Allow Branch Tracing) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .force_tb (Forcibly Allow Branch Tracing) +api_type: +- NA +--- + +# .force\_tb (Forcibly Allow Branch Tracing) + + +The **.force\_tb** command forces the processor to trace branches early in the boot process. + +``` +.force_tb +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +Typically, branch tracing is enabled after the debugger initializes the processor control block (PRCB). This initialization occurs early in the boot process. + +However, if you have to use the [**tb (Trace to Next Branch)**](tb--trace-to-next-branch-.md) command before this initialization, you can use the **.force\_tb** command to enable branch tracing earlier. Use this command carefully because it can corrupt your processor state. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.force_tb%20%28Forcibly%20Allow%20Branch%20Tracing%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-foreach.md b/windows-driver-docs-pr/debugger/-foreach.md new file mode 100644 index 0000000000..ee1e9308df --- /dev/null +++ b/windows-driver-docs-pr/debugger/-foreach.md @@ -0,0 +1,94 @@ +--- +title: .foreach +description: The .foreach token parses the output of one or more debugger commands and uses each value in this output as the input to one or more additional commands. +ms.assetid: 646c86c2-a436-43d6-b0d8-32dbd423120e +keywords: [".foreach Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .foreach +api_type: +- NA +--- + +# .foreach + + +The **.foreach** token parses the output of one or more debugger commands and uses each value in this output as the input to one or more additional commands. + +``` +.foreach [Options] ( Variable { InCommands } ) { OutCommands } + +.foreach [Options] /s ( Variable "InString" ) { OutCommands } + +.foreach [Options] /f ( Variable "InFile" ) { OutCommands } +``` + +## Syntax Elements + + + *Options* +Can be any combination of the following options: + +**/pS** *InitialSkipNumber* +Causes some initial tokens to be skipped. *InitialSkipNumber* specifies the number of output tokens that will not be passed to the specified *OutCommands*. + +**/ps** *SkipNumber* +Causes tokens to be skipped repeatedly each time a command is processed. After each time a token is passed to the specified *OutCommands*, a number of tokens equal to the value of *SkipNumber* will be ignored. + + *Variable* +Specifies a variable name. This variable will be used to hold the output from each command in the *InCommands* string; you can reference *Variable* by name in the parameters passed to the *OutCommands*. Any alphanumeric string can be used, although using a string that can also pass for a valid hexadecimal number or debugger command is not recommended. If the name used for *Variable* happens to match an existing global variable, local variable, or alias, their values will not be affected by the **.foreach** command. + + *InCommands* +Specifies one or more commands whose output will be parsed; the resulting tokens will be passed to *OutCommands*. The output from *InCommands* is not displayed. + + *InString* +Used with **/s**. Specifies a string that will be parsed; the resulting tokens will be passed to *OutCommands*. + + *InFile* +Used with **/f**. Specifies a text file that will be parsed; the resulting tokens will be passed to *OutCommands*. The file name *InFile* must be enclosed in quotation marks. + + *OutCommands* +Specifies one or more commands which will be executed for each token. Whenever the *Variable* string occurs it will be replaced by the current token. + +**Note**   When the string *Variable* appears within *OutCommands*, it must be surrounded by spaces. If it is adjacent to any other text -- even a parenthesis -- it will not be replaced by the current token value, unless you use the [**${ } (Alias Interpreter)**](-------alias-interpreter-.md) token. + +  + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +When the output from *InCommands*, the *InString* string, or the *InFile* file is parsed, any number of spaces, tabs, or carriage returns is treated as a single delimiter. Each of the resulting pieces of text is used to replace *Variable* when it appears within *OutCommands*. + +Here is an example of a **.foreach** statement that uses the [**dds**](dds--dps--dqs--display-words-and-symbols-.md) command on each token found in the file *myfile.txt*: + +``` +0:000> .foreach /f ( place "g:\myfile.txt") { dds place } +``` + +The **/pS** and **/ps** flags can be used to pass only certain tokens to the specified *OutCommands*. For example, the following statement will skip the first two tokens in the *myfile.txt* file and then pass the third to [**dds**](dds--dps--dqs--display-words-and-symbols-.md). After each token that is passed, it will skip four tokens. The result is that **dds** will be used with the 3rd, 8th, 13th, 18th, and 23rd tokens, and so on: + +``` +0:000> .foreach /pS 2 /ps 4 /f ( place "g:\myfile.txt") { dds place } +``` + +For more examples that use the **.foreach** token, see [Debugger Command Program Examples](debugger-command-program-examples.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.foreach%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-formats--show-number-formats-.md b/windows-driver-docs-pr/debugger/-formats--show-number-formats-.md new file mode 100644 index 0000000000..5662973e22 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-formats--show-number-formats-.md @@ -0,0 +1,97 @@ +--- +title: .formats (Show Number Formats) +description: The .formats command evaluates an expression or symbol in the context of the current thread and process and displays it in multiple numeric formats. +ms.assetid: 9eac92b3-5137-4adb-a074-31510dc9bff7 +keywords: [".formats (Show Number Formats) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .formats (Show Number Formats) +api_type: +- NA +--- + +# .formats (Show Number Formats) + + +The **.formats** command evaluates an expression or symbol in the context of the current thread and process and displays it in multiple numeric formats. + +``` +.formats expression +``` + +## Parameters + + + *expression* +Specifies the expression to evaluate. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The evaluated expression is displayed in hexadecimal, decimal, octal, and binary formats, as well as single-precision and double-precision floating-point format. ASCII character formats are also displayed when the bytes correspond to standard ASCII characters. The expression is also interpreted as a time stamp if it is in the allowed range. + +The following example shows a **.formats** command. + +``` +0:000> .formats 1c407e62 +Evaluate expression: + Hex: 1c407e62 + Decimal: 473988706 + Octal: 03420077142 + Binary: 00011100 01000000 01111110 01100010 + Chars: .@~b + Time: Mon Jan 07 15:31:46 1985 + Float: low 6.36908e-022 high 0 + Double: 2.34182e-315 +``` + +The **Time** field displays a 32-bit value in CRT time stamp format and displays a 64-bit value in FILETIME format. You can distinguish these formats because the FILETIME format includes milliseconds and the CRT format does not. + +## See also + + +[**? (Evaluate Expression)**](---evaluate-expression-.md) + +[**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.formats%20%28Show%20Number%20Formats%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-fpo--control-fpo-overrides-.md b/windows-driver-docs-pr/debugger/-fpo--control-fpo-overrides-.md new file mode 100644 index 0000000000..445420a9bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fpo--control-fpo-overrides-.md @@ -0,0 +1,148 @@ +--- +title: .fpo (Control FPO Overrides) +description: The .fpo command controls the frame pointer omission (FPO) overrides. +ms.assetid: a1a20f5d-71c9-487b-bcba-a87b60d74588 +keywords: [".fpo (Control FPO Overrides) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .fpo (Control FPO Overrides) +api_type: +- NA +--- + +# .fpo (Control FPO Overrides) + + +The **.fpo** command controls the frame pointer omission (FPO) overrides. + +``` +.fpo -s [-fFlag] Address +.fpo -d Address +.fpo -x Address +.fpo -o Address +.fpo Address +``` + +## Parameters + + + **-s** +Sets an FPO override at the specified address. + + **-f***Flag* +Specifies FPO flags for the override. You must not add a space between **-f** and *Flag*. If the flag takes an argument, you must add a space between the flag and that argument. If you want multiple flags, you must repeat the **-f** switch (for example, **-fb -fp 4 -fe**). You can use the **-f** switch only with **-s**. You can use one of the following values for *Flag*. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagEffect

b

Sets fUseBP equal to TRUE.

e

Sets fUseSEH equal to TRUE.

n

Sets cbFrame equal to FRAME_NONFPO. (By default, cbFrame is set to FRAME_FPO.)

l Term

Sets cdwLocals equal to Term. Term should specify the local DWORD count that you want.

p Term

Sets cdwParams equal to Term. Term should specify the parameter DWORD count that you want.

r Term

Sets cbRegs equal to Term. Term should specify the register count that you want.

s Term

Sets cbProcSize equal to Term. Term should specify the procedure size that you want.

t Term

Sets cbFrame equal to Term. Term should specify one of the following frame types:

+
    +
  • FRAME_FPO 0

  • +
  • FRAME_TRAP 1

  • +
  • FRAME_TSS 2

  • +
  • FRAME_NONFPO 3

  • +
+ +  + + *Address* +Specifies the address where the debugger sets or removes the override or the address whose overrides the debugger should display. This address must be within a module in the current module list. + + -**d** +Removes the FPO overrides at the specified address. + + **-x** +Removes all FPO overrides within the module that contains the *Address* address. + + **-o** +Displays all FPO overrides within the module that contains the *Address* address. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

all

+ +  + +Remarks +------- + +Without parameters, the **.fpo** command displays the FPO overrides for the specified address. + +Some compilers (including Microsoft Visual Studio 6.0 and earlier versions) generate FPO information to indicate how the stack frame is set up. During stack walking, the debugger uses these FPO records to understand the stack. If the compiler generated incorrect FPO information, you can use the **.fpo** command to fix this problem. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.fpo%20%28Control%20FPO%20Overrides%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fpsearch.md b/windows-driver-docs-pr/debugger/-fpsearch.md new file mode 100644 index 0000000000..af13ef9f18 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fpsearch.md @@ -0,0 +1,129 @@ +--- +title: fpsearch +description: The fpsearch extension searches the freed special pool for a specified address. +ms.assetid: 70375723-7156-47ec-b6e1-b3c51b5caaf9 +keywords: ["special pool", "fpsearch Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- fpsearch +api_type: +- NA +--- + +# !fpsearch + + +The **!fpsearch** extension searches the freed special pool for a specified address. + +``` +!fpsearch [Address] [Flag] +``` + +## Parameters + + + *Address* +Specifies a virtual address. + + *Flag* +If set, the debugger displays the raw content of each page on the free list as it searches the freed special pool. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The display for an address includes the virtual address, the page frame number (PFN), the pool tag, size, whether the data at the address is pageable, the thread ID, and the call stack at the time of deallocation. + +If *Address* is set to -1, the debugger displays the entire freed special pool. + +If the debugger cannot find the specified address in the freed special pool, it does not display anything.Here is an example of the output from this extension: + +``` +kd> !fpsearch -1 1 +Searching the free page list (8 entries) for all freed special pool + +1EC4000 04000200 e56b6f54 000001f4 0000059c ....Tok......... +1EC4000 00000800 00000000 00000000 00000000 ................ +1EC4000 bad0b0b0 82100000 00000000 00000000 ................ +1EC4000 72657355 20203233 0000bac5 00000000 User32 ........ +1EC4000 00028b94 00000000 0000bac9 00000000 ................ +1EC4000 00000000 00000000 ffffffff 7fffffff ................ +1EC4000 8153b1b8 00028aff 00000000 00000000 ..S............. +1EC4000 0000001b 00000000 00000012 00000514 ................ + +26A2000 000a0008 00adecb0 000e000c 00adecba ................ +26A2000 000a0008 00adecc8 000e000c 00adecd2 ................ +26A2000 000e000c 00adece0 000e000c 00adecee ................ +26A2000 00120010 00adecfc 000e000c 00aded0e ................ +26A2000 000e000c 00aded1c 000e000c 00aded2a ............*... +26A2000 000e000c 00aded38 000e000c 00aded46 ....8.......F... +26A2000 000a0008 00aded54 000e000c 00aded5e ....T.......^... +26A2000 00120010 00aded6c 000e000c 00aded7e ....l.......~... + +2161000 000a0008 00adeccc 000e000c 00adecd6 ................ +2161000 000a0008 00adece4 000e000c 00adecee ................ +2161000 000e000c 00adecfc 000e000c 00aded0a ................ +2161000 00120010 00aded18 000e000c 00aded2a ............*... +2161000 000e000c 00aded38 000e000c 00aded46 ....8.......F... +2161000 000e000c 00aded54 000e000c 00aded62 ....T.......b... +2161000 000a0008 00aded70 000e000c 00aded7a ....p.......z... +2161000 00120010 00aded88 000e000c 00aded9a ................ + +... + +CEC8000 0311ffa4 03120000 0311c000 00000000 ................ +CEC8000 00001e00 00000000 7ff88000 00000000 ................ +CEC8000 00000328 00000704 00000000 00000000 (............... +CEC8000 7ffdf000 00000000 00000000 00000000 ................ +CEC8000 e18ba8c0 00000000 00000000 00000000 ................ +CEC8000 00000000 00000000 00000000 00000000 ................ +CEC8000 00000000 00000000 00000000 00000000 ................ +CEC8000 00000000 00000000 00000000 00000000 ................ + +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +CEAD000 00000000 00000000 00000000 00000000 ................ +``` + +You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20%20!fpsearch%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-frame--set-local-context-.md b/windows-driver-docs-pr/debugger/-frame--set-local-context-.md new file mode 100644 index 0000000000..362332525d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-frame--set-local-context-.md @@ -0,0 +1,108 @@ +--- +title: .frame (Set Local Context) +description: The .frame command specifies which local context (scope) is used to interpret local variables or displays the current local context. +ms.assetid: eb843712-204f-4bbd-b711-a10756c9279a +keywords: ["Set Local Context (.frame) command", "memory, Set Local Context (.frame) command", "context, Set Local Context (.frame) command", ".frame (Set Local Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .frame (Set Local Context) +api_type: +- NA +--- + +# .frame (Set Local Context) + + +The **.frame** command specifies which local context (scope) is used to interpret local variables or displays the current local context. + +``` +.frame [/c] [/r] [FrameNumber] +.frame [/c] [/r] = BasePtr [FrameIncrement] +.frame [/c] [/r] = BasePtr StackPtr InstructionPtr +``` + +## Parameters + + + **/c** +Sets the specified frame as the current local override context. This action allows a user to access the nonvolatile registers for any function in the call stack. + + **/r** +Displays registers and other information about the specified local context. + + *FrameNumber* +Specifies the number of the frame whose local context you want. If this parameter is zero, the command specifies the current frame. If you omit this parameter, this command displays the current local context. + + *BasePtr* +Specifies the base pointer for the stack trace that is used to determine the frame, if you add an equal sign (=) after the command name (**.frame**). On an x86-based processor, you add another argument after *BasePtr* (which is interpreted as *FrameIncrement*) or two more arguments after *BasePtr* (which are interpreted as *InstructionPtr* and *StackPtr*). + + *FrameIncrement* +(x86-based processor only) + +Specifies an additional quantity of frames past the base pointer. For example, if the base pointer 0x0012FF00 is the address of frame 3, the command **.frame 12ff00** is equivalent to **.frame 3**, and **.frame 12ff00 2** is equivalent to **.frame 5**. + + *StackPtr* +(x86-based processor only) Specifies the stack pointer for the stack trace that is used to determine the frame. If you omit *StackPtr* and *InstructionPtr*, the debugger uses the stack pointer that the **esp** register specifies and the instruction pointer that the **eip** register specifies. + + *InstructionPtr* +(x86-based processor only) Specifies the instruction pointer for the stack trace that is used to determine the frame. If you omit *StackPtr* and *InstructionPtr*, the debugger uses the stack pointer that the **esp** register specifies and the instruction pointer that the **eip** register specifies. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the local context and other context settings, see [Changing Contexts](changing-contexts.md). For more information about how to display local variables and other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +When an application is running, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the function that they are defined in. If you do not use the **.frame** command, the debugger uses the scope of the current function (the current frame on the stack) as the [local context](changing-contexts.md#local-context). + +To change the local context, use the **.frame** command and specify the frame number that you want. + +The *frame number* is the position of the stack frame within the stack trace. You can view this stack trace with the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command or the [Calls window](calls-window.md). The first line (the current frame) is frame number 0. The subsequent lines represent frame numbers 1, 2, 3, and so on. + +If you use the **n** parameter with the [**k**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command, the **k** command displays frame numbers together with the stack trace. These frame numbers are always displayed in hexadecimal form. On the other hand, the **.frame** command interprets its argument in the default radix, unless you override this setting with a prefix such as 0x. To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. + +You can set the local context to a different stack frame to enable you to view new local variable information. However, the actual variables that are available depend on the code that is being executed. + +The local context is reset to the scope of the program counter if any application execution occurs. The local context is reset to the top stack frame if the register context is changed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.frame%20%28Set%20Local%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-frozen.md b/windows-driver-docs-pr/debugger/-frozen.md new file mode 100644 index 0000000000..ca91e9f458 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-frozen.md @@ -0,0 +1,69 @@ +--- +title: frozen +description: The frozen extension displays the state of each processor. +ms.assetid: aa2761b7-e7e1-435e-98d3-bfaac64925bf +keywords: ["processor states", "frozen Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- frozen +api_type: +- NA +--- + +# !frozen + + +The **!frozen** extension displays the state of each processor. + +``` +!frozen +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example of the output from this extension: + +``` +0: kd> !frozen +Processor states: + 0 : Current + 1 : Frozen +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!frozen%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fwver.md b/windows-driver-docs-pr/debugger/-fwver.md new file mode 100644 index 0000000000..f23f82bbc7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fwver.md @@ -0,0 +1,88 @@ +--- +title: fwver +description: The fwver extension displays the Itanium firmware version. +ms.assetid: 0b1a2fb2-9df6-45b4-bd5b-cbcdde38ddad +keywords: ["fwver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- fwver +api_type: +- NA +--- + +# !fwver + + +The **!fwver** extension displays the Itanium firmware version. + +``` +!fwver +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium target computer. + +### Additional Information + +For more information, consult an Intel architecture manual. + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !fwver + +Firmware Version + + Sal Revision: 0 + SAL_A_VERSION: 0 + SAL_B_VERSION: 0 + PAL_A_VERSION: 6623 + PAL_B_VERSION: 6625 + smbiosString: W460GXBS2.86E.0117A.P08.200107261041 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!fwver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-fxdevice.md b/windows-driver-docs-pr/debugger/-fxdevice.md new file mode 100644 index 0000000000..a432ebb524 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-fxdevice.md @@ -0,0 +1,146 @@ +--- +title: fxdevice +description: The fxdevice extension displays summary information about all Power Management Framework (PoFx) registered devices. This command can be used only during kernel-mode debugging. +ms.assetid: 98E34825-467F-46E5-BC29-AF241FF30B90 +keywords: ["fxdevice Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- fxdevice +api_type: +- NA +--- + +# !fxdevice + + +The !fxdevice extension displays summary information about all Power Management Framework (PoFx) registered devices. This command can be used only during kernel-mode debugging. + +For more information about PoFX, see [Overview of the Power Management Framework](https://msdn.microsoft.com/library/windows/hardware/hh406637). + +Syntax + +``` +!fxdevice[] +``` + +## Parameters + + + **< FxDevice Address>** +Provides the address of the FxDevice to display. + +## DLL + + + ++++ + + + + + + +

Windows 10 and later

Kdexts.dll

+ +  + +Remarks +------- + +The !fxdevice extension displays the following information when it is present on the target system. + +- Non-idle PoFx devices +- Idle D0 PoFx devices +- Idle non-D0 PoFx devices + +The following is example out from the !fxdevice extension with a supplied device address. + +``` +kd> !fxdevice ffffe0012ccbda60 +!fxdevice 0xffffe0012ccbda60 + DevNode: 0xffffe0012bbb09f0 + UniqueId: "HDAUDIO\FUNC_01&VEN_10EC&DEV_0662&SUBSYS_103C304A&REV_1001\4&25ff998c&0&0001" + InstancePath: "HDAUDIO\FUNC_01&VEN_10EC&DEV_0662&SUBSYS_103C304A&REV_1001\4&25ff998c&0&0001" + Device Power State: PowerDeviceD0 + PEP Owner: Default PEP + Acpi Plugin: 0 + Acpi Handle: 0 + Device Status Flags: IdleTimerOn DevicePowerNotRequired_ReceivedFromPEP + Device Idle Timeout: 0x1869ffffe7960 + Device Power On: No Activity + Device Power Off: No Activity + Device Unregister: No Activity + Component Count: 1 + Component 0: F0/F0 - IDLE (RefCount = 0) + Pep Component: 0xffffe0012cfe1800 + Active: 0 Latency: 0 Residency: 0 Wake: 0 Dx IRP: 0 WW IRP: 0 + Component Idle State Change: No Activity + Component Activation: No Activity + Component Active: No Activity +``` + +The following is the default output from the !fxdevice extension. + +``` +kd> !fxdevice +******************************************************************************** +Dumping non-idle PoFx devices +******************************************************************************** +!fxdevice 0xffffe0012bbd08d0 + DevNode: 0xffffe0012b3f87b0 + UniqueId: "\_SB.PCI0" + InstancePath: "ACPI\PNP0A08\2&daba3ff&1" + Device Power State: PowerDeviceD0 + Component Count: 1 + Component 0: F0/F1 - ACTIVE (RefCount = 28) + +!fxdevice 0xffffe0012c587940 + DevNode: 0xffffe0012b3f9d30 + UniqueId: "\_SB.PCI0.PEGL" + InstancePath: "PCI\VEN_8086&DEV_D138&SUBSYS_304A103C&REV_11\3&33fd14ca&0&18" + Device Power State: PowerDeviceD0 + Component Count: 1 + Component 0: F0/F1 - ACTIVE (RefCount = 1) + +... + +******************************************************************************** +Dumping idle D0 PoFx devices +******************************************************************************** +!fxdevice 0xffffe0012c5838c0 + DevNode: 0xffffe0012bbdfd30 + UniqueId: "\_SB.PCI0.PCX1" + InstancePath: "PCI\VEN_8086&DEV_3B42&SUBSYS_304A103C&REV_05\3&33fd14ca&0&E0" + Device Power State: PowerDeviceD0 + Component Count: 1 + Component 0: F1/F1 - IDLE (RefCount = 0) + +!fxdevice 0xffffe0012c581ac0 + DevNode: 0xffffe0012bbdfa50 + UniqueId: "\_SB.PCI0.PCX5" + InstancePath: "PCI\VEN_8086&DEV_3B4A&SUBSYS_304A103C&REV_05\3&33fd14ca&0&E4" + Device Power State: PowerDeviceD0 + Component Count: 1 + Component 0: F1/F1 - IDLE (RefCount = 0) + +... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!fxdevice%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gatom.md b/windows-driver-docs-pr/debugger/-gatom.md new file mode 100644 index 0000000000..d0bb8ef891 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gatom.md @@ -0,0 +1,64 @@ +--- +title: gatom +description: The gatom extension displays the global atom table. +ms.assetid: effaf07a-4a5f-477c-8d4f-8f955b38cb6a +keywords: ["gatom Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gatom +api_type: +- NA +--- + +# !gatom + + +The **!gatom** extension displays the global atom table. + +``` +!gatom +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +### Additional Information + +For information about the global atom table, see the Microsoft Windows SDK documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gatom%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gbl.md b/windows-driver-docs-pr/debugger/-gbl.md new file mode 100644 index 0000000000..75855f395b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gbl.md @@ -0,0 +1,67 @@ +--- +title: gbl +description: The gbl extension displays header information from the ACPI BIOS Root System Description (RSDT) table of the target computer. +ms.assetid: 1fc59112-27c4-465c-b460-8d6b0e83a39b +keywords: ["ACPI (Advanced Configuration and Power Interface), RSDT header information", "global lock", "gbl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gbl +api_type: +- NA +--- + +# !gbl + + +The **!gbl** extension displays header information from the ACPI BIOS Root System Description (RSDT) table of the target computer. + +``` +!gbl [-v] +``` + +## Parameters + + + **-v** +Verbose. Displays detailed information about the table. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the ACPI and ACPI tables, see [Other ACPI Debugging Extensions](other-acpi-debugging-extensions.md) and the [ACPI Specification](http://go.microsoft.com/fwlink/p/?linkid=57185) Web site. Also see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gbl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gdikdx-verifier.md b/windows-driver-docs-pr/debugger/-gdikdx-verifier.md new file mode 100644 index 0000000000..bae12c5da1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gdikdx-verifier.md @@ -0,0 +1,80 @@ +--- +title: gdikdx.verifier +description: The gdikdx.verifier extension displays the status of Driver Verifier during the verification of a graphics driver. +ms.assetid: a7e189bb-ed63-4da3-ab7a-bf502ec131ed +keywords: ["gdikdx.verifier Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gdikdx.verifier +api_type: +- NA +--- + +# !gdikdx.verifier + + +The **!gdikdx.verifier** extension displays the status of Driver Verifier during the verification of a graphics driver. + +``` +!gdikdx.verifier [-Flags] +``` + +## Parameters + + + *Flags* +Specifies what information will be displayed in the output from this command. Any combination of the following (preceded by a hyphen) is allowed: + +**d** +Causes the display to include statistics on **Memory Pool Tracking**. This includes the address, size, and tag of each pool. + +**h** (or **?**) +Displays some brief Help text for this command in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Gdikdx.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +When verifying drivers that are not graphics drivers, the standard kernel-mode extension [**!verifier**](-verifier.md) should be used instead of **!gdikdx.verifier**. + +Regardless of which flags are selected, this extension will display the Driver Verifier options that are active. It will also display statistics on the frequency of random failure. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gdikdx.verifier%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gentable.md b/windows-driver-docs-pr/debugger/-gentable.md new file mode 100644 index 0000000000..655f9dcc23 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gentable.md @@ -0,0 +1,51 @@ +--- +title: gentable +description: The gentable extension displays an RTL_GENERIC_TABLE. +ms.assetid: acf85ff8-9004-4c8e-b67f-20202c577aab +keywords: ["gentable Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gentable +api_type: +- NA +--- + +# !gentable + + +The **!gentable** extension displays an RTL\_GENERIC\_TABLE. + +Syntax + +``` +!gentable Address[Flag] +``` + +## Parameters + + + *Address* +Specifies the address of the RTL\_GENERIC\_TABLE. + + *Flag* +Specifies the table source. If *Flag* is 1, the AVL table is used. If *Flag* is 0 or omitted, the non-AVL table is used. + +### DLL + +Kdexts.dll + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gentable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gflag.md b/windows-driver-docs-pr/debugger/-gflag.md new file mode 100644 index 0000000000..d7be9420d2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gflag.md @@ -0,0 +1,264 @@ +--- +title: gflag +description: The gflag extension sets or displays the global flags. +ms.assetid: b661f775-a313-4a4d-a3db-1e4dacf830de +keywords: ["gflag Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gflag +api_type: +- NA +--- + +# !gflag + + +The **!gflag** extension sets or displays the global flags. + +``` +!gflag [+|-] Value +!gflag {+|-} Abbreviation +!gflag -? +!gflag +``` + +## Parameters + + + *Value* +Specifies a 32-bit hexadecimal number. If you do not use a plus sign (**+**) or minus sign (**-**), this number becomes the new value of the global flag bit field. If you add a plus sign (**+**) before this number, the number specifies one or more global flag bits to set to 1. If you add a minus sign (**-**) before this number, the number specifies one or more global flag bits to set to zero. + + *Abbreviation* +Specifies a single global flag. *Abbreviation* is a three-letter abbreviation for a global flag that is set to 1 (**+**) or to zero (**-**). + + **-?** +Displays some Help text for this extension, including a list of global flag abbreviations, in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +You can also set these flags by using the Global Flags utility (Gflags.exe). + +Remarks +------- + +If you do not specify any arguments, the **!gflag** extension displays the current global flag settings. + +The following table contains the abbreviations that you can use for the *Abbreviation* parameter. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueNameDescription

0x00000001

"soe"

Stop on exception.

0x00000002

"sls"

Show loader snaps.

0x00000004

"dic"

Debug initial command.

0x00000008

"shg"

Stop if the GUI stops responding (that is, hangs).

0x00000010

"htc"

Enable heap tail checking.

0x00000020

"hfc"

Enable heap free checking.

0x00000040

"hpc"

Enable heap parameter checking.

0x00000080

"hvc"

Enable heap validation on call.

0x00000100

"ptc"

Enable pool tail checking.

0x00000200

"pfc"

Enable pool free checking.

0x00000400

"ptg"

Enable pool tagging.

0x00000800

"htg"

Enable heap tagging.

0x00001000

"ust"

Create a user-mode stack trace DB.

0x00002000

"kst"

Create a kernel-mode stack trace DB.

0x00004000

"otl"

Maintain a list of objects for each type.

0x00008000

"htd"

Enable heap tagging by DLL.

0x00010000

"idp"

Unused.

0x00020000

"d32"

Enable debugging of the Microsoft Win32 subsystem.

0x00040000

"ksl"

Enable loading of kernel debugger symbols.

0x00080000

"dps"

Disable paging of kernel stacks.

0x00100000

"scb"

Enable critical system breaks.

0x00200000

"dhc"

Disable heap coalesce on free.

0x00400000

"ece"

Enable close exception.

0x00800000

"eel"

Enable exception logging.

0x01000000

"eot"

Enable object handle type tagging.

0x02000000

"hpa"

Put heap allocations at the end of pages.

0x04000000

"dwl"

Debug WINLOGON.

0x08000000

"ddp"

Disable kernel-mode DbgPrint and KdPrint output.

0x10000000

NULL

Unused.

0x20000000

"sue"

Stop on unhandled user-mode exception

0x40000000

NULL

Unused.

0x80000000

"dpd"

Disable protected DLL verification.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gflag%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gle.md b/windows-driver-docs-pr/debugger/-gle.md new file mode 100644 index 0000000000..1a94519a05 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gle.md @@ -0,0 +1,76 @@ +--- +title: gle +description: The gle extension displays the last error value for the current thread. +ms.assetid: bed3ce17-6860-421f-ae20-11faa50310ed +keywords: ["thread, error value", "error value", "gle Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gle +api_type: +- NA +--- + +# !gle + + +The **!gle** extension displays the last error value for the current thread. + +``` +!gle [-all] +``` + +## Parameters + + + **-all** +Displays the last error for each user-mode thread on the target system. If you omit this parameter in user mode, the debugger displays the last error for the current thread. If you omit this parameter in kernel mode, the debugger displays the last error for the thread that the current [register context](changing-contexts.md#register-context) specifies. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Ext.dll +Ntsdexts.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about the [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360) routine, see the Micorosft Windows SDK documentation. + +Remarks +------- + +The **!gle** extension displays the value of [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360) and tries to decode this value. + +In kernel mode, the **!gle** extension work only if the debugger can read the thread environment block (TEB). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-bankinfo.md b/windows-driver-docs-pr/debugger/-gpiokd-bankinfo.md new file mode 100644 index 0000000000..02f68c424a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-bankinfo.md @@ -0,0 +1,85 @@ +--- +title: gpiokd.bankinfo +description: The gpiokd.bankinfo command displays information about a GPIO bank. +ms.assetid: C4AFF469-0624-4D59-AE78-9D7FC407AC3A +keywords: ["gpiokd.bankinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.bankinfo +api_type: +- NA +--- + +# !gpiokd.bankinfo + + +The **!gpiokd.bankinfo** command displays information about a GPIO bank. + +``` +!gpiokd.bankinfo BankAddress [Flags] +``` + +## Parameters + + + *BankAddress* +Address of a [\_GPIO\_BANK\_ENTRY](gpio-extensions.md#data-structures-used-by-the-gpio-commands) structure that represents a bank of a GPIO controller. + + *Flags* +Flags that specify which information is displayed. This parameter is a bitwise OR of one or more of the following flags. + + ++++ + + + + + + + + + + + + + + + + + + + + +
FlagDescription

0x1

Displays the pin table.

0x2

Displays the Enable and Mask registers.

0x4

If bit 0 (0x1) is set and this flag (0x4) is set, the display includes unconfigured pins.

+ +  + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.bankinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-clientlist.md b/windows-driver-docs-pr/debugger/-gpiokd-clientlist.md new file mode 100644 index 0000000000..06e2f464b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-clientlist.md @@ -0,0 +1,82 @@ +--- +title: gpiokd.clientlist +description: The gpiokd.clientlist command displays all registered GPIO controllers. +ms.assetid: 4951C2D2-FA98-4600-A98D-1BC98080D2EB +keywords: ["gpiokd.clientlist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.clientlist +api_type: +- NA +--- + +# !gpiokd.clientlist + + +The **!gpiokd.clientlist** command displays all registered GPIO controllers. + +``` +!gpiokd.clientlist [Flags] +``` + +## Parameters + + + *Flags* +Flags that specify which information is displayed. This parameter is a bitwise OR of one or more of the following flags. + + ++++ + + + + + + + + + + + + + + + + + + + + +
FlagDescription

0x1

For each controller, displays detailed information including all of its banks.

0x2

If bit 0 (0x1) is set and this flag (0x2) is set, displays the Enable and Mask registers for each bank.

0x4

If bit 0 (0x1) is set and this flag (0x4) is set, the display includes unconfigured pins.

+ +  + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.clientlist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-gpioext.md b/windows-driver-docs-pr/debugger/-gpiokd-gpioext.md new file mode 100644 index 0000000000..000e5b5f54 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-gpioext.md @@ -0,0 +1,85 @@ +--- +title: gpiokd.gpioext +description: The gpiokd.gpioext command displays information about a GPIO controller. +ms.assetid: D5DB5166-A173-409E-A6A1-3872A22D19E1 +keywords: ["gpiokd.gpioext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.gpioext +api_type: +- NA +--- + +# !gpiokd.gpioext + + +The **!gpiokd.gpioext** command displays information about a GPIO controller. + +``` +!gpiokd.gpioext ExtensionAddress [Flags] +``` + +## Parameters + + + *ExtensionAddress* +Address of the [\_DEVICE\_EXTENSION](gpio-extensions.md#data-structures-used-by-the-gpio-commands) structure that represents the GPIO controller. + + *Flags* +Flags that specify which information is displayed. This parameter is a bitwise OR of one or more of the following flags. + + ++++ + + + + + + + + + + + + + + + + + + + + +
FlagDescription

0x1

Displays the pin table for each bank.

0x2

If bit 0 (0x1) is set and this flag (0x2) is set, the display includes the Enable and Mask registers for each bank.

0x4

If bit 0 (0x1) is set and this flag (0x4) is set, the display includes unconfigured pins.

+ +  + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.gpioext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-help.md b/windows-driver-docs-pr/debugger/-gpiokd-help.md new file mode 100644 index 0000000000..ae391926df --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-help.md @@ -0,0 +1,43 @@ +--- +title: gpiokd.help +description: The gpiokd.help command displays help for the GPIO debugger extension commands. +ms.assetid: 02F66960-8B4F-49A7-93EB-DF80C4A5D011 +keywords: ["gpiokd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.help +api_type: +- NA +--- + +# !gpiokd.help + + +The **!gpiokd.help** command displays help for the [GPIO debugger extension commands](gpio-extensions.md). + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-pininfo.md b/windows-driver-docs-pr/debugger/-gpiokd-pininfo.md new file mode 100644 index 0000000000..4599d4252a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-pininfo.md @@ -0,0 +1,53 @@ +--- +title: gpiokd.pininfo +description: The gpiokd.pininfo command displays information about a specified GPIO pin. +ms.assetid: 67A8F87A-E1E4-42AC-B626-66C2CB177A61 +keywords: ["gpiokd.pininfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.pininfo +api_type: +- NA +--- + +# !gpiokd.pininfo + + +The **!gpiokd.pininfo** command displays information about a specified GPIO pin. + +``` +!gpiokd.pininfo PinAddress +``` + +## Parameters + + + *PinAddress* +Address of the [\_GPIO\_PIN\_INFORMATION\_ENTRY](gpio-extensions.md#data-structures-used-by-the-gpio-commands) data structure that represents the pin. + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.pininfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-pinisrvec.md b/windows-driver-docs-pr/debugger/-gpiokd-pinisrvec.md new file mode 100644 index 0000000000..2857e021f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-pinisrvec.md @@ -0,0 +1,53 @@ +--- +title: gpiokd.pinisrvec +description: The gpiokd.pinisrvec command displays Interrupt Service Routine (ISR) vector information for a specified pin. +ms.assetid: 83D4C072-92B2-4F61-A099-0BA4F8255BE8 +keywords: ["gpiokd.pinisrvec Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.pinisrvec +api_type: +- NA +--- + +# !gpiokd.pinisrvec + + +The **!gpiokd.pinisrvec** command displays Interrupt Service Routine (ISR) vector information for a specified pin. + +``` +!gpiokd.bankinfo PinAddress +``` + +## Parameters + + + *PinAddress* +Address of the [\_GPIO\_PIN\_INFORMATION\_ENTRY](gpio-extensions.md#data-structures-used-by-the-gpio-commands) data structure that represents the pin. + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.pinisrvec%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gpiokd-pintable.md b/windows-driver-docs-pr/debugger/-gpiokd-pintable.md new file mode 100644 index 0000000000..cfb962454e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gpiokd-pintable.md @@ -0,0 +1,88 @@ +--- +title: gpiokd.pintable +description: The gpiokd.pintable command displays information about an array of GPIO pins. +ms.assetid: CBBC9BC7-D1BF-44C2-836B-703F5384D690 +keywords: ["gpiokd.pintable Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gpiokd.pintable +api_type: +- NA +--- + +# !gpiokd.pintable + + +The **!gpiokd.pintable** command displays information about an array of GPIO pins. + +``` +!gpiokd.pintable PinBase PinCount [Flags] +``` + +## Parameters + + + *PinBase* +Address of an array of [\_GPIO\_PIN\_INFORMATION\_ENTRY](gpio-extensions.md#data-structures-used-by-the-gpio-commands) structures. + + *PinCount* +The number of pins to display. + + *Flags* +Flags that specify which information is displayed. This parameter is a bitwise OR of one or more of the following flags. + + ++++ + + + + + + + + + + + + + + + + + + + + +
FlagDescription

0x1

Not used by this command.

0x2

Not used by this command.

0x4

The display includes unconfigured pins.

+ +  + +## DLL + + +Gpiokd.dll + +## See also + + +[GPIO Extensions](gpio-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gpiokd.pintable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-gs.md b/windows-driver-docs-pr/debugger/-gs.md new file mode 100644 index 0000000000..cbeeac93e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-gs.md @@ -0,0 +1,100 @@ +--- +title: gs +description: The gs extension analyzes a /GS stack overflow. +ms.assetid: 4c73fd73-e476-4836-80f7-ab9b9c797d8b +keywords: ["gs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gs +api_type: +- NA +--- + +# !gs + + +The **!gs** extension analyzes a /GS stack overflow. + +``` +!gs +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +The **!gs**extension helps debug buffer overruns. Run **!gs**when you encounter a STATUS\_STACK\_BUFFER\_OVERRUN error, as the following example shows. + +``` +0:000> !gs +Corruption occurred in mshtml!CDoc::OnPaint or one of its callers +Real canary not found at 0x74866010 +Canary at gsfailure frame 0x292ea4e7 +Corrupted canary 0x0013e2c8: 0x00000000 +Corrupted cookie value too generic, skipping init bit-flip check +a caller of mshtml!CDoc::OnPaint has corrupted the EBP from 0x0013e254 to 0x0013 +e234 +check callers (without canary) of mshtml!CDoc::OnPaint for 0x1 bytes of overflow + +The canary doesn't look corrupted. Not sure how we got here +EBP/ESP check skipped: No saved EBP in exception context +Function mshtml!CDoc::OnPaint: + 00000000 - 00000004 this CDoc* + 0013de40 - 0013e180 rd CDoc::OnPaint::__l39::REGION_DAT +A + 0013e180 - 0013e18c Lock CDoc::CLock + 0013e18c - 0013e224 DI CFormDrawInfo + 0013e23c - 0013e240 hwndInplace HWND__* + 0013e240 - 0013e244 prc tagRECT* + 0013e248 - 0013e250 ptBefore tagPOINT + 0013e250 - 0013e254 fViewIsReady int + 0013e250 - 0013e254 fHtPalette int + 0013e254 - 0013e258 fNoPaint int + 0013e258 - 0013e260 ptAfter tagPOINT + 0013e260 - 0013e264 c int + 0013e264 - 0013e268 hrgn HRGN__* + 0013e268 - 0013e2a8 ps tagPAINTSTRUCT +Candidate buffer : ps 0013e268 to 0013e2a7 + 0013e268 ea 04 01 a7 00 00 00 00-10 01 00 00 f3 00 00 00 ................ + 0013e278 ed 03 00 00 44 02 00 00-84 e5 13 00 f4 e2 13 00 ....D........... + ... + 0013e2ac 38 20 01 03 10 e3 13 00-68 6b e6 01 d0 e6 03 00 8 ......hk...... + 0013e2bc 80 fa 03 00 0d 00 00 00-10 08 19 00 00 00 00 00 ................ +0:000> +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!gs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-handle.md b/windows-driver-docs-pr/debugger/-handle.md new file mode 100644 index 0000000000..526a172c7a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-handle.md @@ -0,0 +1,233 @@ +--- +title: handle +description: The handle extension displays information about a handle or handles that one or all processes in the target system own. +ms.assetid: ae3b7e7e-cdc1-4b83-88d7-63fe207044e3 +keywords: ["handle", "handle, handle extension", "handle Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- handle +api_type: +- NA +--- + +# !handle + + +The **!handle** extension displays information about a handle or handles that one or all processes in the target system own. + +User-Mode + +``` +!handle [Handle [UMFlags [TypeName]]] +!handle -? +``` + +Kernel-Mode + +``` + !handle [Handle [KMFlags [Process [TypeName]]]] +``` + +## Parameters + + + *Handle* +Specifies the index of the handle to display. If *Handle* is -1 or if you omit this parameter, the debugger displays data for all handles that are associated with the current process. If *Handle* is 0, the debugger displays data for all handles. + + *UMFlags* +(User mode only) Specifies what the display should contain. This parameter can be a sum of any of the following bit values. (The default value is 0x1.) + +Bit 0 (0x1) +Displays handle type information. + +Bit 1 (0x2) +Displays basic handle information. + +Bit 2 (0x4) +Displays handle name information. + +Bit 3 (0x8) +Displays object-specific handle information, when available. + + *KMFlags* +(Kernel mode only) Specifies what the display should contain. This parameter can be a sum of any of the following bit values. (The default value is 0x3.) + +Bit 0 (0x1) +Displays basic handle information. + +Bit 1 (0x2) +Displays information about objects. + +Bit 2 (0x4) +Displays free handle entries. If you do not set this bit and you omit *Handle* or set it to zero, the list of handles that are displayed does not include free handles. If *Handle* specifies a single free handle, it is displayed even if you do not set this bit. + +Bit 4 (0x10) +(Windows XP and later) Displays the handle from the kernel handle table instead of the current process. + +Bit 5 (0x20) +(Windows XP and later) Interprets the handle as a thread ID or process ID and displays information about the corresponding kernel object. + + *Process* +(Kernel mode only) Specifies a process. You can use the process ID or the hexadecimal address of the process object. This parameter must refer to a currently running process on the target system. If this parameter is -1 or if you omit it, the current process is used. If this parameter is 0, handle information from all processes is displayed. + + *TypeName* +Specifies the type of handle that you want to examine. Only handles that match this type are displayed. *TypeName* is case sensitive. Valid types include Event, Section, File, Port, Directory, SymbolicLink, Mutant, WindowStation, Semaphore, Key, Token, Process, Thread, Desktop, IoCompletion, Timer, Job, and WaitablePort. + + **-?** +(User mode only) Displays some Help text for this extension in the [Debugger Command window](debugger-command-window.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Uext.dll +Ntsdexts.dll

Windows XP and later

+Kdexts.dll +Uext.dll +Ntsdexts.dll
+ +  + +### Additional Information + +For more information about handles, see the [**!htrace**](-htrace.md) extension, the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +You can use the **!handle** extension during user-mode and kernel-mode live debugging. You can also use this extension on kernel-mode dump files. However, you cannot use this extension on user-mode dump files, unless you specifically created them with handle information. (You can create create such dump files by using the [**.dump /mh (Create Dump File)**](-dump--create-dump-file-.md) command.) + +During live user-mode debugging, you can use the [**.closehandle (Close Handle)**](-closehandle--close-handle-.md) command to close one or more handles. + +The following examples are user-mode examples of the **!handle** extension. The following command displays a list of all handles. + +``` +0:000> !handle +Handle 4 + Type Section +Handle 8 + Type Event +Handle c + Type Event +Handle 10 + Type Event +Handle 14 + Type Directory +Handle 5c + Type File +6 Handles +Type Count +Event 3 +Section 1 +File 1 +Directory 1 +``` + +The following command displays detailed information about handle 0x8. + +``` +0:000> !handle 8 f +Handle 8 + Type Event + Attributes 0 + GrantedAccess 0x100003: + Synch + QueryState,ModifyState + HandleCount 2 + PointerCount 3 + Name + Object Specific Information + Event Type Auto Reset + Event is Waiting +``` + +The following examples are kernel-mode examples of **!handle**. The following command lists all handles, including free handles. + +``` +kd> !handle 0 4 +processor number 0 +PROCESS 80559800 SessionId: 0 Cid: 0000 Peb: 00000000 ParentCid: 0000 + DirBase: 00039000 ObjectTable: e1000d60 TableSize: 380. + Image: Idle + +New version of handle table at e1002000 with 380 Entries in use + +0000: free handle, Entry address e1002000, Next Entry fffffffe +0004: Object: 80ed5238 GrantedAccess: 001f0fff +0008: Object: 80ed46b8 GrantedAccess: 00000000 +000c: Object: e1281d00 GrantedAccess: 000f003f +0010: Object: e1013658 GrantedAccess: 00000000 +...... +0168: Object: ffb6c748 GrantedAccess: 00000003 (Protected) +016c: Object: ff811f90 GrantedAccess: 0012008b +0170: free handle, Entry address e10022e0, Next Entry 00000458 +0174: Object: 80dfd5c8 GrantedAccess: 001f01ff +...... +``` + +The following command show detailed information about handle 0x14 in the kernel handle table. + +``` +kd> !handle 14 13 +processor number 0 +PROCESS 80559800 SessionId: 0 Cid: 0000 Peb: 00000000 ParentCid: 0000 + DirBase: 00039000 ObjectTable: e1000d60 TableSize: 380. + Image: Idle + +Kernel New version of handle table at e1002000 with 380 Entries in use +0014: Object: e12751d0 GrantedAccess: 0002001f +Object: e12751d0 Type: (80ec8db8) Key + ObjectHeader: e12751b8 + HandleCount: 1 PointerCount: 1 + Directory Object: 00000000 Name: \REGISTRY\MACHINE\SYSTEM\CONTROLSET001\CONTROL\SESSION MANAGER\EXECUTIVE +``` + +The following command shows information about all handles to Section objects in all processes. + +``` +!handle 0 3 0 Section +... +PROCESS fffffa8004f48940 + SessionId: none Cid: 0138 Peb: 7f6639bf000 ParentCid: 0004 + DirBase: 10cb74000 ObjectTable: fffff8a00066f700 HandleCount: 39. + Image: smss.exe + +Handle table at fffff8a00066f700 with 39 entries in use + +0040: Object: fffff8a000633f00 GrantedAccess: 00000006 (Inherit) Entry: fffff8a000670100 +Object: fffff8a000633f00 Type: (fffffa80035fef20) Section + ObjectHeader: fffff8a000633ed0 (new version) + HandleCount: 1 PointerCount: 262144 +... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!handle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-heap.md b/windows-driver-docs-pr/debugger/-heap.md new file mode 100644 index 0000000000..4041e422a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-heap.md @@ -0,0 +1,723 @@ +--- +title: heap +description: The heap extension displays heap usage information, controls breakpoints in the heap manager, detects leaked heap blocks, searches for heap blocks, or displays page heap information. +ms.assetid: 70947b56-1a8c-4e78-85d0-d5df87f3150c +keywords: ["heap usage", "GFlags, enabling page heap", "heap Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- heap +api_type: +- NA +--- + +# !heap + + +The **!heap** extension displays heap usage information, controls breakpoints in the heap manager, detects leaked heap blocks, searches for heap blocks, or displays page heap information. + +This extension supports the segment heap and the NT heap. Use !heap with no parameter to list all heaps and their type. + +``` +!heap [HeapOptions] [ValidationOptions] [Heap] +!heap -b [{alloc|realloc|free} [Tag]] [Heap | BreakAddress] +!heap -B {alloc|realloc|free} [Heap | BreakAddress] +!heap -l +!heap -s [SummaryOptions] [StatHeapAddress] +!heap -i HeapAddress +!heap -x [-v] Address +!heap -p [PageHeapOptions] +!heap -srch [Size] Pattern +!heap -flt FilterOptions +!heap -stat [-h Handle [-grp GroupBy [MaxDisplay]]] +!heap [-p] -? +!heap -triage [Handle | Address] +``` + +## Segment and NT Heap Parameters + + +These parameters work with Segment and NT heaps. + + **-s** +Specifies that summary information is being requested. If *SummaryOptions* and *StatHeapAddress* are omitted, then summary information is displayed for all heaps associated with the current process. + + *SummaryOptions* +Can be any combination of the following options. The *SummaryOptions* are not case-sensitive. Type !heap -s -? for additional information. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-v

Verifies all data blocks.

-b BucketSize

Specifies the bucket size. The default is 1024 bits.

-d DumpBlockSize

Specifies the bucket size.

-a

Dumps all heap blocks.

-c

Specifies that the contents of each block should be displayed.

+ +  + + **-triage \[***Handle* **|** *Address***\]** +Causes the debugger to automatically search for failures in a process's heaps. If a heap handle is specified as an argument, that heap is examined; otherwise, all the heaps are searched for one that contains the given address, and if one is found, it is examined. Using **-triage** is the only way to validate low-fragmentation heap (LFH) corruption. + + **-x** **** \[**-v**\] +Causes the debugger to search for the heap block containing the specified address. If -v is added, the command will search the entire virtual memory space of the current process for pointers to this heap block. + + **-l** +Causes the debugger to detect leaked heap blocks. + + **-i** **** *Address* **-h** *HeapAddress* +Displays information about the specified *Heap*. + + *Address* +Specifies the address to search for. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. Use **!heap -?** for generic help, and **!heap -p -?** for page heap help. + +## NT Heap Parameters + + +These parameters work only with the NT Heap. + + *HeapOptions* +Can be any combination of the following options. The *HeapOptions* values are case-sensitive. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-v

Causes the debugger to validate the specified heap.

+
+Note  This option does not detect low fragmentation heap (LFH) corruption. Use -triage instead. +
+
+  +

-a

Causes the display to include all information for the specified heap. Size, in this case, is rounded up to the heap granularity. (Running !heap with the -a option is equivalent to running it with the three options -h -f -m, which can take a long time.)

-h

Causes the display to include all non-LFH entries for the specified heap.

-hl

Causes the display to include all the entries for the specified heap(s), including LFH entries.

-f

Causes the display to include all the free list entries for the specified heap.

-m

Causes the display to include all the segment entries for the specified heap.

-t

Causes the display to include the tag information for the specified heap.

-T

Causes the display to include the pseudo-tag entries for the specified heap.

-g

Causes the display to include the global tag information. Global tags are associated with each untagged allocation.

-s

Causes the display to include summary information for the specified heap.

-k

(x86-based targets only) Causes the display to include the stack backtrace associated with each entry.

+ +  + + *ValidationOptions* +Can be any single one of the following options. The *ValidationOptions* are case-sensitive. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-D

Disables validate-on-call for the specified heap.

-E

Enables validate-on-call for the specified heap.

-d

Disables heap checking for the specified heap.

-e

Enables heap checking for the specified heap.

+ +  + + **-i** **** *Heap* **** *Address* **or** *HeapAddress* +Displays information about the specified *Heap*. + + *BreakAddress* +Specifies the address of a block where a breakpoint is to be set or removed. + + **-b** +Causes the debugger to create a conditional breakpoint in the heap manager. The **-b** option can be followed by **alloc**, **realloc**, or **free**; this specifies whether the breakpoint will be activated by allocating, reallocating, or freeing memory. If *BreakAddress* is used to specify the address of the block, the breakpoint type can be omitted. If *Heap* is used to specify the heap address or heap index, the type must be included, as well as the *Tag* parameter. + + *Tag* +Specifies the tag name within the heap. + + **-B** +Causes the debugger to remove a conditional breakpoint from the heap manager. The breakpoint type (**alloc**, **realloc**, or **free**) must be specified, and must be the same as that used with the **-b** option. + + *StatHeapAddress* +Specifies the address of the heap. If this is 0 or omitted, all heaps associated with the current process are displayed. + + **-p** +Specifies that page heap information is being requested. If this is used without any *PageHeapOptions*, all page heaps will be displayed. + + *PageHeapOptions* +Can be any single one of the following options. The *PageHeapOptions* are case-sensitive. If no options are specified, then all possible page heap handles will be displayed. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-h Handle

Causes the debugger to display detailed information about a page heap with handle Handle.

-a Address

Causes the debugger to find the page heap whose block contains Address. Full details of how this address relates to full-page heap blocks will be included, such as whether this address is part of a page heap, its offset inside the block, and whether the block is allocated or was freed. Stack traces are included whenever available. When using this option, size is displayed in multiples of the heap allocation granularity.

-t[c|s] [Traces]

Causes the debugger to display the collected traces of the heavy heap users. Traces specifies the number of traces to display; the default is four. If there are more traces than the specified number, the earliest traces are displayed. If -t or -tc is used, the traces are sorted by count usage. If -ts is used, the traces are sorted by size. (The -tc and -ts options are supported in Windows XP only; the -t option is supported only in Windows XP and earlier versions of Windows.)

-fi [Traces]

Causes the debugger to display the most recent fault injection traces. Traces specifies the quantity to be displayed; the default is 4.

-all

Causes the debugger to display detailed information about all page heaps.

-?

Causes the debugger to display page heap help, including a diagram of heap blocks. (These diagrams can also be seen in the following Remarks section.)

+ +  + +Before you can use any **!heap -p** extension command, the page heap must be enabled for your target process. See details in the following Remarks section. + + **-srch** +Scans all heaps for the given pattern. + + *Pattern* +Specifies a pattern for which to look. + + *Size* +Can be any single one of the following options. This specifies the size of the pattern. The '-' is required. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-b

The pattern is one BYTE in size.

-w

The pattern is one WORD in size.

-d

The pattern is one DWORD in size.

-q

The pattern is one QWORD in size.

+ +  + +If none of the above are specified, then the pattern is assumed to be of the same size as the machine pointer. + + **-flt** +Limits the display to include only heaps with the specified size or size range. + + *FilterOptions* +Can be any single one of the following options. The *FilterOptions* are case-sensitive. + + ++++ + + + + + + + + + + + + + + + + +
OptionEffect

s Size

Limits the display to include only heaps of the specified size.

r SizeMin SizeMax

Limits the display to include only heaps within the specified size range.

+ +  + + **-stat** +Displays usage statistics for the specified heap. + + **-h** *Handle* +Causes usage statistics for only the heap at *Handle* to be displayed. If *Handle* is 0 or omitted, then usage statistics for all heaps are displayed. + + **-grp** **** *GroupBy* +Reorders the display as specified by *GroupBy*. The options for *GroupBy* can be found in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionEffect

A

Displays the usage statistics according to allocation size.

B

Displays the usage statistics according to block count.

S

Displays the usage statistics according to the total size of each allocation.

+ +  + + *MaxDisplay* +Limits the output to only *MaxDisplay* number of lines. + +### DLL + + ++++ + + + + + + +

Windows XP and later

+Ext.dll +Exts.dll
+ +  + +### Additional Information + +For information about heaps, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +This extension command can be used to perform a variety of tasks. + +The standard **!heap** command is used to display heap information for the current process. (This should be used only for user-mode processes. The [**!pool**](-pool.md) extension command should be used for system processes.) + +The **!heap -b** and **!heap -B** commands are used to create and delete conditional breakpoints in the heap manager. + +The **!heap -l** command detects leaked heap blocks. It uses a garbage collector algorithm to detect all busy blocks from the heaps that are not referenced anywhere in the process address space. For huge applications, it can take a few minutes to complete. This command is only available in Windows XP and later versions of Windows. + +The **!heap -x** command searches for a heap block containing a given address. If the **-v** option is used, this command will additionally search the entire virtual memory space of the current process for pointers to this heap block. This command is only available in Windows XP and later versions of Windows. + +The **!heap -p** command displays various forms of page heap information. Before using **!heap -p**, you must enable the page heap for the target process. This is done through the Global Flags (gflags.exe) utility. To do this, start the utility, fill in the name of the target application in the **Image File Name** text box, select **Image File Options** and **Enable page heap**, and click **Apply**. Alternatively, you can start the Global Flags utility from a Command Prompt window by typing **gflags /i** *xxx.exe* **+hpa**, where *xxx.exe* is the name of the target application. + +The **!heap -p -t\[c|s\]** commands are not supported beyond Windows XP. Use the [UMDH](umdh.md) tool provided with the debugger package to obtain similar results. + +The **!heap -srch** command displays those heap entries that contain a certain specified pattern. + +The **!heap -flt** command limits the display to only heap allocations of a specified size. + +The **!heap -stat** command displays heap usage statistics. + +Here is an example of the standard **!heap** command: + +``` +0:000> !ntsdexts.heap -a +Index Address Name Debugging options enabled + 1: 00250000 + Segment at 00250000 to 00350000 (00056000 bytes committed) + Flags: 50000062 + ForceFlags: 40000060 + Granularity: 8 bytes + Segment Reserve: 00100000 + Segment Commit: 00004000 + DeCommit Block Thres:00000400 + DeCommit Total Thres:00002000 + Total Free Size: 000003be + Max. Allocation Size:7ffddfff + Lock Variable at: 00250b54 + Next TagIndex: 0012 + Maximum TagIndex: 07ff + Tag Entries: 00350000 + PsuedoTag Entries: 00250548 + Virtual Alloc List: 00250050 + UCR FreeList: 002504d8 + 128-bit bitmap of free lists + FreeList Usage: 00000014 00000000 00000000 00000000 + Free Free + List List +# Head Blink Flink + FreeList[ 00 ] at 002500b8: 002a4378 . 002a4378 + 0x02 - HEAP_ENTRY_EXTRA_PRESENT + 0x04 - HEAP_ENTRY_FILL_PATTERN + Entry Prev Cur 0x10 - HEAP_ENTRY_LAST_ENTRY + +Address Size Size flags +002a4370: 00098 . 01c90 [14] - free + FreeList[ 02 ] at 002500c8: 0025cb30 . 002527b8 +002527b0: 00058 . 00010 [04] - free +0025cb28: 00088 . 00010 [04] - free + FreeList[ 04 ] at 002500d8: 00269a08 . 0026e530 +0026e528: 00038 . 00020 [04] - free +0026a4d0: 00038 . 00020 [06] - free +0026f9b8: 00038 . 00020 [04] - free +0025cda0: 00030 . 00020 [06] - free +00272660: 00038 . 00020 [04] - free +0026ab60: 00038 . 00020 [06] - free +00269f20: 00038 . 00020 [06] - free +00299818: 00038 . 00020 [04] - free +0026c028: 00038 . 00020 [06] - free +00269a00: 00038 . 00020 [46] - free + + Segment00 at 00250b90: +Flags: 00000000 +Base: 00250000 +First Entry: 00250bc8 +Last Entry: 00350000 +Total Pages: 00000080 +Total UnCommit: 00000055 +Largest UnCommit:000aa000 +UnCommitted Ranges: (1) + 002a6000: 000aa000 + + Heap entries for Segment00 in Heap 250000 + 0x01 - HEAP_ENTRY_BUSY + 0x02 - HEAP_ENTRY_EXTRA_PRESENT + 0x04 - HEAP_ENTRY_FILL_PATTERN + 0x08 - HEAP_ENTRY_VIRTUAL_ALLOC + 0x10 - HEAP_ENTRY_LAST_ENTRY + 0x20 - HEAP_ENTRY_SETTABLE_FLAG1 + 0x40 - HEAP_ENTRY_SETTABLE_FLAG2 +Entry Prev Cur 0x80 - HEAP_ENTRY_SETTABLE_FLAG3 + +Address Size Size flags (Bytes used) (Tag name) +00250000: 00000 . 00b90 [01] - busy (b90) +00250b90: 00b90 . 00038 [01] - busy (38) +00250bc8: 00038 . 00040 [07] - busy (24), tail fill (NTDLL!LDR Database) +00250c08: 00040 . 00060 [07] - busy (48), tail fill (NTDLL!LDR Database) +00250c68: 00060 . 00028 [07] - busy (10), tail fill (NTDLL!LDR Database) +00250c90: 00028 . 00060 [07] - busy (48), tail fill (NTDLL!LDR Database) +00250cf0: 00060 . 00050 [07] - busy (38), tail fill (Objects= 80) +00250d40: 00050 . 00048 [07] - busy (2e), tail fill (NTDLL!LDR Database) +00250d88: 00048 . 00c10 [07] - busy (bf4), tail fill (Objects>1024) +00251998: 00c10 . 00030 [07] - busy (12), tail fill (NTDLL!LDR Database) +... +002525c0: 00030 . 00060 [07] - busy (48), tail fill (NTDLL!LDR Database) +00252620: 00060 . 00050 [07] - busy (38), tail fill (NTDLL!LDR Database) +00252670: 00050 . 00040 [07] - busy (22), tail fill (NTDLL!CSRSS Client) +002526b0: 00040 . 00040 [07] - busy (24), tail fill (Objects= 64) +002526f0: 00040 . 00040 [07] - busy (24), tail fill (Objects= 64) +00252730: 00040 . 00028 [07] - busy (10), tail fill (Objects= 40) +00252758: 00028 . 00058 [07] - busy (3c), tail fill (Objects= 88) +002527b0: 00058 . 00010 [04] free fill +002527c0: 00010 . 00058 [07] - busy (3c), tail fill (NTDLL!LDR Database) +00252818: 00058 . 002d0 [07] - busy (2b8), tail fill (Objects= 720) +00252ae8: 002d0 . 00330 [07] - busy (314), tail fill (Objects= 816) +00252e18: 00330 . 00330 [07] - busy (314), tail fill (Objects= 816) +00253148: 00330 . 002a8 [07] - busy (28c), tail fill (NTDLL!LocalAtom) +002533f0: 002a8 . 00030 [07] - busy (18), tail fill (NTDLL!LocalAtom) +00253420: 00030 . 00030 [07] - busy (18), tail fill (NTDLL!LocalAtom) +00253450: 00030 . 00098 [07] - busy (7c), tail fill (BASEDLL!LMEM) +002534e8: 00098 . 00060 [07] - busy (44), tail fill (BASEDLL!TMP) +00253548: 00060 . 00020 [07] - busy (1), tail fill (Objects= 32) +00253568: 00020 . 00028 [07] - busy (10), tail fill (Objects= 40) +00253590: 00028 . 00030 [07] - busy (16), tail fill (Objects= 48) +... +0025ccb8: 00038 . 00060 [07] - busy (48), tail fill (NTDLL!LDR Database) +0025cd18: 00060 . 00058 [07] - busy (3c), tail fill (NTDLL!LDR Database) +0025cd70: 00058 . 00030 [07] - busy (18), tail fill (NTDLL!LDR Database) +0025cda0: 00030 . 00020 [06] free fill (NTDLL!Temporary) +0025cdc0: 00020 . 00258 [07] - busy (23c), tail fill (Objects= 600) +0025d018: 00258 . 01018 [07] - busy (1000), tail fill (Objects>1024) +0025e030: 01018 . 00060 [07] - busy (48), tail fill (NTDLL!LDR Database) +... +002a4190: 00028 . 00118 [07] - busy (100), tail fill (BASEDLL!GMEM) +002a42a8: 00118 . 00030 [07] - busy (18), tail fill (Objects= 48) +002a42d8: 00030 . 00098 [07] - busy (7c), tail fill (Objects= 152) +002a4370: 00098 . 01c90 [14] free fill +002a6000: 000aa000 - uncommitted bytes. +``` + +Here is an example of the **!heap -l** command: + +``` +1:0:011> !heap -l +1:Heap 00170000 +Heap 00280000 +Heap 00520000 +Heap 00b50000 +Heap 00c60000 +Heap 01420000 +Heap 01550000 +Heap 016d0000 +Heap 019b0000 +Heap 01b40000 +Scanning VM ... +## Entry User Heap Segment Size PrevSize Flags + +001b2958 001b2960 00170000 00000000 40 18 busy extra +001b9cb0 001b9cb8 00170000 00000000 80 300 busy extra +001ba208 001ba210 00170000 00000000 80 78 busy extra +001cbc90 001cbc98 00170000 00000000 e0 48 busy extra +001cbd70 001cbd78 00170000 00000000 d8 e0 busy extra +001cbe90 001cbe98 00170000 00000000 68 48 busy extra +001cbef8 001cbf00 00170000 00000000 58 68 busy extra +001cc078 001cc080 00170000 00000000 f8 128 busy extra +001cc360 001cc368 00170000 00000000 80 50 busy extra +001cc3e0 001cc3e8 00170000 00000000 58 80 busy extra +001fe550 001fe558 00170000 00000000 150 278 busy extra +001fe6e8 001fe6f0 00170000 00000000 48 48 busy extra +002057a8 002057b0 00170000 00000000 58 58 busy extra +00205800 00205808 00170000 00000000 48 58 busy extra +002058b8 002058c0 00170000 00000000 58 70 busy extra +00205910 00205918 00170000 00000000 48 58 busy extra +00205958 00205960 00170000 00000000 90 48 busy extra +00246970 00246978 00170000 00000000 60 88 busy extra +00251168 00251170 00170000 00000000 78 d0 busy extra user_flag +00527730 00527738 00520000 00000000 40 40 busy extra +00527920 00527928 00520000 00000000 40 80 busy extra +21 leaks detected. +``` + +The table in this example contains all 21 leaks found. + +Here is an example of the **!heap -x** command: + +``` +0:011> !heap 002057b8 -x +## Entry User Heap Segment Size PrevSize Flags + +002057a8 002057b0 00170000 00170640 58 58 busy extra +``` + +Here is an example of the **!heap -x -v** command: + +``` +1:0:011> !heap 002057b8 -x -v +## 1:Entry User Heap Segment Size PrevSize Flags + +002057a8 002057b0 00170000 00170640 58 58 busy extra + +Search VM for address range 002057a8 - 002057ff : 00205990 (002057d0), +``` + +In this example, there is a pointer to this heap block at address 0x00205990. + +Here is an example of the **!heap -flt s** command: + +``` +0:001>!heap -flt s 0x50 +``` + +This will display all of the allocations of size 0x50. + +Here is an example of the **!heap -flt r** command: + +``` +0:001>!heap -flt r 0x50 0x80 +``` + +This will display each allocation whose size is between 0x50 and 0x7F. + +Here is an example of the **!heap -srch** command. + +``` +0:001> !heap -srch 77176934 + _HEAP @ 00090000 + in HEAP_ENTRY: Size : Prev Flags - UserPtr UserSize - state + 00099A48: 0018 : 0005 [01] - 00099A50 (000000B8) - (busy) + ole32!CALLFRAME_CACHE::`vftable' + _HEAP @ 00090000 + in HEAP_ENTRY: Size : Prev Flags - UserPtr UserSize - state + 00099B58: 0018 : 0005 [01] - 00099B60 (000000B8) - (busy) + ole32!CALLFRAME_CACHE::`vftable' +``` + +The following diagrams show the arrangement of heap blocks. + +Light page heap block -- allocated: + +``` + +-----+---------------+---+ + | | | | + +-----+---------------+---+ + ^ ^ ^ + | | 8 suffix bytes (filled with 0xA0) + | User allocation (filled with E0 if zeroing not requested) + Block header (starts with 0xABCDAAAA and ends with 0xDCBAAAAA) +``` + +Light page heap block -- freed: + +``` + +-----+---------------+---+ + | | | | + +-----+---------------+---+ + ^ ^ ^ + | | 8 suffix bytes (filled with 0xA0) + | User allocation (filled with F0 bytes) + Block header (starts with 0xABCDAAA9 and ends with 0xDCBAAA9) +``` + +Full page heap block -- allocated: + +``` + +-----+---------+---+------- + | | | | ... N/A page + +-----+---------+---+------- + ^ ^ ^ + | | 0-7 suffix bytes (filled with 0xD0) + | User allocation (if zeroing not requested, filled + with E0 in Windows 2000 and C0 in Windows XP) + Block header (starts with 0xABCDBBBB and ends with 0xDCBABBBB) +``` + +Full page heap block -- freed: + +``` + +-----+---------+---+------- + | | | | ... N/A page + +-----+---------+---+------- + ^ ^ ^ + | | 0-7 suffix bytes (filled with 0xD0) + | User allocation (filled with F0 bytes) + Block header (starts with 0xABCDBBA and ends with 0xDCBABBBA) +``` + +To see the stack trace of the allocation or the freeing of a heap block or full page heap block, use [**dt DPH\_BLOCK\_INFORMATION**](dt--display-type-.md) with the header address, followed by [**dds**](dds--dps--dqs--display-words-and-symbols-.md) with the block's **StackTrace** field. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!heap%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-help--meta-command-help-.md b/windows-driver-docs-pr/debugger/-help--meta-command-help-.md new file mode 100644 index 0000000000..3ede4aa3e3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-help--meta-command-help-.md @@ -0,0 +1,76 @@ +--- +title: .help (Meta-Command Help) +description: The .help command displays a list of all meta-commands. +ms.assetid: aafd873d-3280-4873-8149-d43f684ec01d +keywords: [".help (Meta-Command Help) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .help (Meta-Command Help) +api_type: +- NA +--- + +# .help (Meta-Command Help) + + +The **.help** command displays a list of all meta-commands. + +``` +.help +.help /D +``` + +## Parameters + + + **/D** +Displays output using [Debugger Markup Language](debugger-markup-language-commands.md). The output contains a list of links that you can click to see the meta-commands that beging with a particular letter. + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +For more information about meta-commands, use the **.help** command. For more information about standard commands, use the [**?**](---command-help-.md) command. For more information about extension commands, use the [**!help**](-help.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.help%20%28Meta-Command%20Help%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-help.md b/windows-driver-docs-pr/debugger/-help.md new file mode 100644 index 0000000000..3436cad3e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-help.md @@ -0,0 +1,61 @@ +--- +title: help +description: The help extension displays help text that describes the extension commands exported from the extension DLL. +ms.assetid: 9d01856e-4906-43cb-a445-71cce011a973 +keywords: ["help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- help +api_type: +- NA +--- + +# !help + + +The **!help** extension displays help text that describes the extension commands exported from the extension DLL. + +Do not confuse this extension command with the [**? (Command Help)**](---command-help-.md) or [**.help (Meta-Command Help)**](-help--meta-command-help-.md) commands. + +``` +![ExtensionDLL.]help [-v] [CommandName] +``` + +## Parameters + + + *ExtensionDLL* +Displays help for the specified extension DLL. Type the name of an extension DLL without the .dll file name extension. If the DLL file is not in the extension search path (as displayed by using [**.chain (List Debugger Extensions)**](-chain--list-debugger-extensions-.md)), include the path to the DLL file. For example, to display help for uext.dll, type **!uext.help** or **!***Path***\\winext\\uext.help**. + +If you omit the *ExtensionDLL*, the debugger will display the help text for the first extension DLL in the list of loaded DLLs. + + **-v** +Displays the most detailed help text available. This feature is not supported in all DLLs. + + *CommandName* +Displays only the help text for the specified command. This feature is not supported in all DLLs or for all commands. + +### DLL + +This extension is supported by most extension DLLs. + +Remarks +------- + +Some individual commands will also display a help text if you use the **/?** or **-?** parameter with the command name. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-hh--open-html-help-file-.md b/windows-driver-docs-pr/debugger/-hh--open-html-help-file-.md new file mode 100644 index 0000000000..04503bd7a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hh--open-html-help-file-.md @@ -0,0 +1,78 @@ +--- +title: .hh (Open HTML Help File) +description: The .hh command opens the Debugging Tools for Windows documentation. +ms.assetid: 6c6d5b33-ad54-4325-93d7-ed63f9f012e8 +keywords: [".hh (Open HTML Help File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .hh (Open HTML Help File) +api_type: +- NA +--- + +# .hh (Open HTML Help File) + + +The **.hh** command opens the Debugging Tools for Windows documentation. + +``` +.hh [Text] +``` + +## Parameters + + + *Text* +Specifies the text to find in the index of the Help documentation. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +You cannot use this command when you are performing [remote debugging through Remote.exe](remote-debugging-through-remote-exe.md). + +### Additional Information + +For more information about the Help documentation, see [Using the Help File](using-the-help-documentation.md). + +Remarks +------- + +The **.hh** command opens the Debugging Tools for Windows documentation (Debugger.chm). If you specify *Text*, the debugger opens the **Index** pane in the documentation and searches for *Text* as a keyword in the index. If you do not specify *Text*, the debugger opens the **Contents** pane of the documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.hh%20%28Open%20HTML%20Help%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-hideinjectedcode.md b/windows-driver-docs-pr/debugger/-hideinjectedcode.md new file mode 100644 index 0000000000..9b15b26f87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hideinjectedcode.md @@ -0,0 +1,55 @@ +--- +title: .hideinjectedcode (Hide Injected Code) +description: The .hideinjectedcode command turns on, or off, the hiding of injected code. +ms.assetid: 08C5DAC1-1D5B-431F-9E17-E8F0FF60F782 +keywords: [".hideinjectedcode (Hide Injected Code) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .hideinjectedcode (Hide Injected Code) +api_type: +- NA +--- + +# .hideinjectedcode (Hide Injected Code) + + +The **.hideinjectedcode** command turns on, or off, the hiding of injected code. + +``` +.hideinjectedcode { on | off } +.hideinjectedcode help +.hideinjectedcode +``` + +## Parameters + + + **on** +Turns on the hiding of injected code. + + **off** **** +Turns off the hiding of injected code + + **help** +Displays help for this command. + +Remarks +------- + +If you enter this command with no parameter, it displays help for the command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.hideinjectedcode%20%28Hide%20Injected%20Code%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-help.md b/windows-driver-docs-pr/debugger/-hidkd-help.md new file mode 100644 index 0000000000..112bbce8e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-help.md @@ -0,0 +1,43 @@ +--- +title: hidkd.help +description: The hidkd.help command displays help for the HID debugger extension commands. +ms.assetid: 1CCE25B1-E6D4-4402-83FB-214C92650739 +keywords: ["hidkd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.help +api_type: +- NA +--- + +# !hidkd.help + + +The **!hidkd.help** command displays help for the HID debugger extension commands. + +## DLL + + +Hidkd.dll + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-hidfdo.md b/windows-driver-docs-pr/debugger/-hidkd-hidfdo.md new file mode 100644 index 0000000000..5b628dff01 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-hidfdo.md @@ -0,0 +1,81 @@ +--- +title: hidkd.hidfdo +description: The hidkd.hidfdo command displays HID information associated with a functional device object (FDO). +ms.assetid: CB8E8844-B5A7-4273-8401-D4F3C8CBAC4C +keywords: ["hidkd.hidfdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.hidfdo +api_type: +- NA +--- + +# !hidkd.hidfdo + + +The **!hidkd.hidfdo** command displays HID information associated with a functional device object (FDO). + +``` +!hidkd.hidfdo fdo +``` + +## Parameters + + + *fdo* +Address of an FDO. To get the addresses of FDOs that are associated with HID drivers, use the [**!usbhid.hidtree**](-hidkd-hidtree.md) command. + +## DLL + + +Hidkd.dll + +Examples +-------- + +Here is an example of the output of the **!hidfdo** command. The example first calls [**!hidtree**](-hidkd-hidtree.md) to get the address of an FDO. + +``` +0: kd> !hidkd.hidtree +HID Device Tree +... +FDO VendorID:0x045E(Microsoft Corporation) ProductID:0x0745 Version:0x0634 +!hidfdo 0xffffe00004f466e0 +... +0: kd> !hidfdo 0xffffe00004f466e0 +# FDO 0xffffe00004f466e0 (!devobj/!devstack) + + Name : \Device\_HID00000002 + Vendor ID : 0x045E(Microsoft Corporation) + Product ID : 0x0745 + Version Number : 0x0634 + Is Present? : Y + Report Descriptor : !hidrd 0xffffe00004281a80 0x127 + Per-FDO IFR Log : !rcdrlogdump HIDCLASS -a 0xFFFFE0000594D000 + + Position in HID tree + + dt FDO_EXTENSION 0xffffe00004f46850 +``` + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.hidfdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-hidpdo.md b/windows-driver-docs-pr/debugger/-hidkd-hidpdo.md new file mode 100644 index 0000000000..2c5a2fe96f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-hidpdo.md @@ -0,0 +1,90 @@ +--- +title: hidkd.hidpdo +description: The hidkd.hidpdo command displays HID information associated with a physical device object (PDO). +ms.assetid: B7FF3B62-AC41-4CFC-A9D6-609B1204E4CA +keywords: ["hidkd.hidpdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.hidpdo +api_type: +- NA +--- + +# !hidkd.hidpdo + + +The **!hidkd.hidpdo** command displays HID information associated with a physical device object (PDO). + +``` +!hidkd.hidpdo pdo +``` + +## Parameters + + + *pdo* +Address of a PDO. To get the addresses of PDOs that are associated with HID drivers, use the [**!usbhid.hidtree**](-hidkd-hidtree.md) command. + +## DLL + + +Hidkd.dll + +Examples +-------- + +Here is an example of the output of the **!hidpdo** command. The example first calls [**!hidtree**](-hidkd-hidtree.md) to get the address of a PDO. + +``` +0: kd> !hidkd.hidtree +HID Device Tree +... +FDO VendorID:0x045E(Microsoft Corporation) ProductID:0x0745 Version:0x0634 +... + PDO Generic Desktop Controls (0x01) | Mouse (0x02) + !hidpdo 0xffffe000056281e0 + ... + +0: kd> !hidpdo 0xffffe000056281e0 +# PDO 0xffffe000056281e0 (!devobj/!devstack) + + Collection Num : 1 + Name : \Device\_HID00000002#COLLECTION00000001 + FDO : !hidfdo 0xffffe00004f466e0 + Per-FDO IFR Log : !rcdrlogdump HIDCLASS -a 0xFFFFE0000594D000 + + Usage Page : Generic Desktop Controls (0x01) + Usage : Mouse (0x02) + Report Length : 0xa(Input) 0x0(Output) 0x2(Feature) + Pre-parsed Data : 0xffffe00003742840 + Position in HID tree + + dt PDO_EXTENSION 0xffffe00005628350 + +## Power States + + Power States : S0/D0 + Wait Wake IRP : !irp 0xffffe00004fc57d0 (pending on \Driver\HidUsb) +``` + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.hidpdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-hidppd.md b/windows-driver-docs-pr/debugger/-hidkd-hidppd.md new file mode 100644 index 0000000000..545271833d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-hidppd.md @@ -0,0 +1,92 @@ +--- +title: hidkd.hidppd HID extension +description: The hidkd.hidppd command displays HID preparsed data. +ms.assetid: 049D206D-669D-49F4-81FE-2D8E443F9A9E +keywords: ["hidkd.hidppd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.hidppd +api_type: +- NA +--- + +# !hidkd.hidppd + + +The **!hidkd.hidppd** command displays HID preparsed data. + +``` +!hidkd.hidppd ppd +``` + +## Parameters + + + *ppd* +Address of a **HIDP\_PREPARSED\_DATA** structure. To get the address of a **HIDP\_PREPARSED\_DATA** structure, use [**!hidfdo**](-hidkd-hidfdo.md) or [**!hidpdo**](-hidkd-hidpdo.md). + +## DLL + + +Hidkd.dll + +Examples +-------- + +This example shows how to use [**!hidpdo**](-hidkd-hidpdo.md) followed by **!hidppd**. The output of **!hidpdo** shows the address of a **HIDP\_PREPARSED\_DATA** structure. + +``` + +0: kd> !hidpdo 0xffffe000029f6060 +## PDO 0xffffe000029f6060 (!devobj/!devstack) + + Collection Num : 1 + Name : \Device\_HID00000000#COLLECTION00000001 + ... + Pre-parsed Data : 0xffffe000029d1010 + ... + +0: kd> !hidkd.hidppd 0xffffe000029d1010 +Reading preparsed data... +Preparsed Data at 0xffffe000029d1010 + +## Summary + + UsagePage : Vendor-defined (0xFFA0) + Usage : 0x01 + Report Length : 0x2(Input) 0x2(Output) 0x0(Feature) + Link Collection Nodes : 2 + Button Caps : 0(Input) 0(Output) 0(Feature) + Value Caps : 1(Input) 1(Output) 0(Feature) + Data Indices : 1(Input) 1(Output) 0(Feature) + +## Input Value Capability #0 + + Report ID : 0x0 + Usage Page : Vendor-defined (0xFFA1) + Bit Size : 0x8 + Report Count : 0x1 + ... +``` + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.hidppd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-hidrd.md b/windows-driver-docs-pr/debugger/-hidkd-hidrd.md new file mode 100644 index 0000000000..733f567a57 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-hidrd.md @@ -0,0 +1,93 @@ +--- +title: hidkd.hidrd +description: The hidkd.hidrd command displays a HID report descriptor in both raw and parsed format. +ms.assetid: 8A9D76F2-7A36-4458-83A4-EDCB153EC45A +keywords: ["hidkd.hidrd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.hidrd +api_type: +- NA +--- + +# !hidkd.hidrd + + +The **!hidkd.hidrd** command displays a HID report descriptor in both raw and parsed format. + +``` +!hidkd.hidrd rd Length +``` + +## Parameters + + + *rd* +Address of the raw report descriptor data. To get the address of the descriptor data, use the [**!hidfdo**](-hidkd-hidfdo.md) command. + + *Length* +The length, in bytes, of the raw report descriptor data. To get the length, use the [**!hidfdo**](-hidkd-hidfdo.md) command. + +## DLL + + +Hidkd.dll + +Examples +-------- + +This example shows how to use the [**!hidfdo**](-hidkd-hidfdo.md) command followed by the **!hidrd** command. The output of **!hidfdo** shows both the address and length of the raw report descriptor data. + +``` +0: kd> !hidfdo 0xffffe00004f466e0 +# FDO 0xffffe00004f466e0 (!devobj/!devstack) + + Name : \Device\_HID00000002 + ... + Report Descriptor : !hidrd 0xffffe00004281a80 0x127 + ... + +0: kd> !hidrd 0xffffe00004281a80 0x127 +Report Descriptor at 0xffffe00004281a80 + +## Raw Data + +0x0000: 05 01 09 02 A1 01 05 01-09 02 A1 02 85 1A 09 01 +0x0010: A1 00 05 09 19 01 29 05-95 05 75 01 15 00 25 01 +0x0020: 81 02 75 03 95 01 81 01-05 01 09 30 09 31 95 02 +... + +## Parsed + +Usage Page (Generic Desktop Controls)....................0x0000: 05 01 +Usage (Mouse)............................................0x0002: 09 02 +Collection (Application).................................0x0004: A1 01 +..Usage Page (Generic Desktop Controls)..................0x0006: 05 01 +..Usage (Mouse)..........................................0x0008: 09 02 +..Collection (Logical)...................................0x000A: A1 02 +....Report ID (26).......................................0x000C: 85 1A +... +End Collection ()........................................0x0126: C0 +``` + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.hidrd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidkd-hidtree.md b/windows-driver-docs-pr/debugger/-hidkd-hidtree.md new file mode 100644 index 0000000000..f37fc975fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidkd-hidtree.md @@ -0,0 +1,65 @@ +--- +title: hidkd.hidtree +description: The hidkd.hidtree command displays a list of all device nodes that have a HID function driver along with their child nodes. +ms.assetid: 50FD5526-3B0E-4585-BFFD-72ED363D007A +keywords: ["hidkd.hidtree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidkd.hidtree +api_type: +- NA +--- + +# !hidkd.hidtree + + +The **!hidkd.hidtree** command displays a list of all device nodes that have a HID function driver along with their child nodes. The child nodes have a physical device object (PDO) that was created by the parent node's HID function driver. + +``` +!hidkd.hidtree +``` + +This screen shot shows an example of the output of the **!hidtree** command. + +![output of the hidtree command](images/hidkd01.png) + +O + +In this example, there are two device nodes that have a HID function driver. A functional device object (FDO) represents the HID driver in those two nodes. The first FDO node has two child nodes, and the second FDO node has one child node. In the debugger output, the child nodes have the PDO heading. + +**Note**  This set of device nodes does not form a tree that has a single root node. The device nodes that have HID function drivers can be isolated from each other. + +  + +When you are debugging a HID issue, the **!hidtree** is a good place to start, because the command displays several addresses that you can pass to other HID debugger commands. The output uses [Debugger Markup Language (DML)](debugger-markup-language-commands.md) to provide links. The links execute commands that give detailed information related to an individual device node. For example, you could get information about an FDO by clicking one of the [**!hidfdo**](-hidkd-hidfdo.md) links. As an alternative to clicking a link, you can enter a command. For example, to see detailed information about the first node in the preceding output, you could enter the command **!devnode 0xffffe00003b18d30**. + +**Note**  The DML feature is available in WinDbg, but not in Visual Studio or KD. + +  + +## DLL + + +Hidkd.dll + +## See also + + +[HID Extensions](hid-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidkd.hidtree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hidppd.md b/windows-driver-docs-pr/debugger/-hidppd.md new file mode 100644 index 0000000000..0313cb4538 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hidppd.md @@ -0,0 +1,67 @@ +--- +title: hidppd +description: The hidppd extension displays the contents of the HIDP_PREPARSED_DATA structure. +ms.assetid: 9d92d254-442d-4e42-8a6f-ce8b7ff6312c +keywords: ["HIDP_PREPARSED_DATA", "hidppd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hidppd +api_type: +- NA +--- + +# !hidppd + + +The **!hidppd** extension displays the contents of the HIDP\_PREPARSED\_DATA structure. + +``` +!hidppd Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the HIDP\_PREPARSED\_DATA structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about human input devices (HID), see the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hidppd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-holdmem--hold-and-compare-memory-.md b/windows-driver-docs-pr/debugger/-holdmem--hold-and-compare-memory-.md new file mode 100644 index 0000000000..a3453bd6c1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-holdmem--hold-and-compare-memory-.md @@ -0,0 +1,94 @@ +--- +title: .holdmem (Hold and Compare Memory) +description: The .holdmem command saves memory ranges and compares them to other memory ranges. +ms.assetid: d8caa0df-c87d-4378-9a39-cc04760ca0db +keywords: ["Hold and Compare Memory (.holdmem) command", "memory, Hold and Compare Memory (.holdmem) command", ".holdmem (Hold and Compare Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .holdmem (Hold and Compare Memory) +api_type: +- NA +--- + +# .holdmem (Hold and Compare Memory) + + +The **.holdmem** command saves memory ranges and compares them to other memory ranges. + +``` +.holdmem -a Range +.holdmem -d { Range | Address } +.holdmem -D +.holdmem -o +.holdmem -c Range +``` + +## Parameters + + + **-a** **** *Range* +Specifies the memory range to save. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + **-d** **** { *Range* | *Address* } +Specifies memory ranges to delete. If you specify *Address*, the debugger deletes any saved range that contains that address. If you specify *Range*, the debugger deletes any saved range that overlaps with *Range*. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + **-D** +Deletes all saved memory ranges. + + **-o** +Displays all saved memory ranges. + + **-c** *Range* +Compares the specified range to all saved memory ranges. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to manipulate memory and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The **.holdmem** command compares memory ranges byte-for-byte. + +If any of the specified memory locations do not exist in the virtual address space, the command returns an error. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.holdmem%20%28Hold%20and%20Compare%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-homedir.md b/windows-driver-docs-pr/debugger/-homedir.md new file mode 100644 index 0000000000..fe8ddbb6b8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-homedir.md @@ -0,0 +1,73 @@ +--- +title: homedir +description: The homedir extension sets the default directory used by the symbol server and the source server. +ms.assetid: 6bebd7df-03d8-4413-8a0c-a0d5ad913173 +keywords: ["homedir Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- homedir +api_type: +- NA +--- + +# !homedir + + +The **!homedir** extension sets the default directory used by the symbol server and the source server. + +``` +!homedir Directory +!homedir +``` + +## Parameters + + + *Directory* +Specifies the new directory to use as the home directory. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Dbghelp.dll

Windows XP and later

Dbghelp.dll

+ +  + +Remarks +------- + +If the **!homedir** extension is used with no argument, the current home directory is displayed. + +The cache for a source server is located in the src subdirectory of the home directory. The downstream store for a symbol server defaults to the sym subdirectory of the home directory, unless a different location is specified. + +When WinDbg is started, the home directory is the directory where Debugging Tools for Windows was installed. The **!homedir** extension can be used to change this value. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!homedir%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-hstring.md b/windows-driver-docs-pr/debugger/-hstring.md new file mode 100644 index 0000000000..87fed597e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hstring.md @@ -0,0 +1,57 @@ +--- +title: hstring +description: The hstring extension displays the fields of an HSTRING. The last item in the display is the string itself. +ms.assetid: 6FB85609-0FB1-457E-A58E-804F69016406 +keywords: ["hstring Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hstring +api_type: +- NA +--- + +# !hstring + + +The **!hstring** extension displays the fields of an **HSTRING**. The last item in the display is the string itself. + +``` +!hstring Address +``` + +## Parameters + + +*Address* +The address of an **HSTRING**. + +Remarks +------- + +The **HSTRING** data type supports strings that have embedded NULL characters. However, the **!hstring** extension displays the string only up to the first NULL character. To see the entire string including the embedded NULL characters, use the [**!hstring2**](-hstring2.md) extension. + +## See also + + +[Windows Runtime Debugger Commands](windows-runtime-debugger-commands.md) + +[**!hstring2**](-hstring2.md) + +[**!winrterr**](-winrterr.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hstring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-hstring2.md b/windows-driver-docs-pr/debugger/-hstring2.md new file mode 100644 index 0000000000..73549c080f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-hstring2.md @@ -0,0 +1,52 @@ +--- +title: hstring2 +description: The hstring2 extension displays an entire HSTRING including any embedded NULL characters in the string itself. +ms.assetid: CA3C6945-B93B-4717-9349-0968DCD50A5B +keywords: ["hstring2 Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- hstring2 +api_type: +- NA +--- + +# !hstring2 + + +The **!hstring2** extension displays an entire **HSTRING** including any embedded NULL characters in the string itself. + +``` +!hstring2 Address +``` + +## Parameters + + +*Address* +The address of an **HSTRING**. + +## See also + + +[Windows Runtime Debugger Commands](windows-runtime-debugger-commands.md) + +[**!hstring**](-hstring.md) + +[**!winrterr**](-winrterr.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!hstring2%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-htrace.md b/windows-driver-docs-pr/debugger/-htrace.md new file mode 100644 index 0000000000..17d103e728 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-htrace.md @@ -0,0 +1,170 @@ +--- +title: htrace +description: The htrace extension displays stack trace information for one or more handles. +ms.assetid: 1da92c8d-8f77-4b30-a908-bcc33ad05cce +keywords: ["handle, htrace extension", "htrace Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- htrace +api_type: +- NA +--- + +# !htrace + + +The **!htrace** extension displays stack trace information for one or more handles. + +User-Mode Syntax + +``` +!htrace [Handle [Max_Traces]] +!htrace -enable [Max_Traces] +!htrace -snapshot +!htrace -diff +!htrace -disable +!htrace -? +``` + +Kernel-Mode Syntax + +``` + !htrace [Handle [Process [Max_Traces]]] +!htrace -? +``` + +## Parameters + + + *Handle* +Specifies the handle whose stack trace will be displayed. If *Handle* is 0 or omitted, stack traces for all handles in the process will be displayed. + + *Process* +(Kernel mode only) Specifies the process whose handles will be displayed. If *Process* is 0 or omitted, then the current process is used. In user mode, the current process is always used. + + *Max\_Traces* +Specifies the maximum number of stack traces to display. In user mode, if this parameter is omitted, then all the stack traces for the target process will be displayed. + + **-enable** +(User mode only) Enables handle tracing and takes the first snapshot of the handle information to use as the initial state by the **-diff** option. + + **-snapshot** +(User mode only) Takes a snapshot of the current handle information to use as the initial state by the **-diff** option. + + **-diff** +(User mode only) Compares current handle information with the last snapshot of handle information that was taken. Displays all handles that are still open. + + **-disable** +(User mode only; Windows Server 2003 and later only) Disables handle tracing. In Windows XP, handle tracing can be disabled only by terminating the target process. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

+Kdexts.dll +Ntsdexts.dll
+ +  + +### Additional Information + +For information about handles, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) To display further information about a specific handle, use the [**!handle**](-handle.md) extension. + +Remarks +------- + +Before **!htrace** can be used, handle tracing must be enabled. One way to enable handle tracing is to enter the **!htrace -enable** command. When handle tracing is enabled, stack trace information is saved each time the process opens a handle, closes a handle, or references an invalid handle. It is this stack trace information that **!htrace** displays. + +**Note**   You can also enable handle tracing by activating Application Verifier for the target process and selecting the **Handles** option. + +  + +Some of the traces reported by **!htrace** may be from a different process context. In this case, the return addresses may not resolve properly in the current process context, or may resolve to the wrong symbols. + +The following example displays information about all handles in process 0x81400300: + +``` +kd> !htrace 0 81400300 +Process 0x81400300 +ObjectTable 0xE10CCF60 +## + +Handle 0x7CC - CLOSE: +0x8018FCB9: ntoskrnl!ExDestroyHandle+0x103 +0x801E1D12: ntoskrnl!ObpCloseHandleTableEntry+0xE4 +0x801E1DD9: ntoskrnl!ObpCloseHandle+0x85 +0x801E1EDD: ntoskrnl!NtClose+0x19 +0x010012C1: badhandle!mainCRTStartup+0xE3 +## 0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D + +Handle 0x7CC - OPEN: +0x8018F44A: ntoskrnl!ExCreateHandle+0x94 +0x801E3390: ntoskrnl!ObpCreateUnnamedHandle+0x10C +0x801E7317: ntoskrnl!ObInsertObject+0xC3 +0x77DE23B2: KERNEL32!CreateSemaphoreA+0x66 +0x010011C5: badhandle!main+0x45 +0x010012C1: badhandle!mainCRTStartup+0xE3 +## 0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D + +Handle 0x7DC - BAD REFERENCE: +0x8018F709: ntoskrnl!ExMapHandleToPointerEx+0xEA +0x801E10F2: ntoskrnl!ObReferenceObjectByHandle+0x12C +0x801902BE: ntoskrnl!NtSetEvent+0x6C +0x80154965: ntoskrnl!_KiSystemService+0xC4 +0x010012C1: badhandle!mainCRTStartup+0xE3 +## 0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D + +Handle 0x7DC - CLOSE: +0x8018FCB9: ntoskrnl!ExDestroyHandle+0x103 +0x801E1D12: ntoskrnl!ObpCloseHandleTableEntry+0xE4 +0x801E1DD9: ntoskrnl!ObpCloseHandle+0x85 +0x801E1EDD: ntoskrnl!NtClose+0x19 +0x010012C1: badhandle!mainCRTStartup+0xE3 +## 0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D + +Handle 0x7DC - OPEN: +0x8018F44A: ntoskrnl!ExCreateHandle+0x94 +0x801E3390: ntoskrnl!ObpCreateUnnamedHandle+0x10C +0x801E7317: ntoskrnl!ObInsertObject+0xC3 +0x77DE265C: KERNEL32!CreateEventA+0x66 +0x010011A0: badhandle!main+0x20 +0x010012C1: badhandle!mainCRTStartup+0xE3 +0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D +## + +Parsed 0x6 stack traces. +Dumped 0x5 stack traces. +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!htrace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ib---id---iw.md b/windows-driver-docs-pr/debugger/-ib---id---iw.md new file mode 100644 index 0000000000..af688f0a39 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ib---id---iw.md @@ -0,0 +1,29 @@ +--- +title: ib, id, iw +description: ib, id, iw +ms.assetid: b026acd9-f655-4649-bc28-6d7b835d8634 +keywords: ["ib extension (obsolete)", "id extension (obsolete)", "iw extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !ib, !id, !iw + + +## + + +The **!ib**, **!id**, and **!iw** extension commands are obsolete. Use the [**ib, id, iw (Input from Port)**](ib--iw--id--input-from-port-.md) commands instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ib,%20!id,%20!iw%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-icpleak.md b/windows-driver-docs-pr/debugger/-icpleak.md new file mode 100644 index 0000000000..91ce62ea55 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-icpleak.md @@ -0,0 +1,76 @@ +--- +title: icpleak +description: The icpleak extension examines all I/O completion objects in the system for the object with the largest number of queued entries. +ms.assetid: 8644a41a-44da-47bc-94ef-5024bb457c7d +keywords: ["I/O completion", "icpleak Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- icpleak +api_type: +- NA +--- + +# !icpleak + + +The **!icpleak** extension examines all I/O completion objects in the system for the object with the largest number of queued entries. + +``` +!icpleak [HandleFlag] +``` + +## Parameters + + + *HandleFlag* +If this flag is set, the display also includes all processes that have a handle to the object with the largest number of queued entries. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about I/O completion ports, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +This extension is useful when there is a leak in the I/O completion pool. I/O completion pool leaks can occur when a process is allocating I/O completion packets by calling [**PostQueuedCompletionStatus**](https://msdn.microsoft.com/library/windows/desktop/aa365458), but is not calling [**GetQueuedCompletionStatus**](https://msdn.microsoft.com/library/windows/desktop/aa364986) to free them, or when a process is queuing completion entries to a port, but there is no thread retrieving the entries. To detect a leak run the [**!poolused**](-poolused.md) extension and check the value of ICP pool tag. If pool use with the ICP tag is significant, a leak might have occurred. + +This extension works only if the system maintains type lists. If the *HandleFlag* is set and the system has many processes, this extension will take a long time to run. + +You can stop at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!icpleak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-idle-cmd--set-idle-command-.md b/windows-driver-docs-pr/debugger/-idle-cmd--set-idle-command-.md new file mode 100644 index 0000000000..900c37894f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-idle-cmd--set-idle-command-.md @@ -0,0 +1,89 @@ +--- +title: .idle_cmd (Set Idle Command) +description: The .idle_cmd command sets the idle command. This is a command that is executed whenever control returns from the target to the debugger. +ms.assetid: 8cfe7aa8-4e31-4e97-b61d-9e8bb1b7be61 +keywords: [".idle_cmd (Set Idle Command) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .idle_cmd (Set Idle Command) +api_type: +- NA +--- + +# .idle\_cmd (Set Idle Command) + + +The **.idle\_cmd** command sets the *idle command*. This is a command that is executed whenever control returns from the target to the debugger. For example, when the target reaches a breakpoint, this command executes. + +``` +.idle_cmd +.idle_cmd String +.idle_cmd /d +``` + +## Parameters + + + *String* +Specifies the string to which the idle command should be set. + + **/d** +Clears the idle command. + +### Environment + +This command cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +When **.idle\_cmd** is used with no parameters it displays the current idle command. + +In WinDbg, idle commands are stored in workspaces. + +Here is an example. The idle command is set to [**r eax**](r--registers-.md). Then, because the debugger is already idle, this command immediately executes, displaying the **eax** register: + +``` +windbg> .idle_cmd r eax +Execute when idle: r eax +eax=003b0de8 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.idle_cmd%20%28Set%20Idle%20Command%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-idt.md b/windows-driver-docs-pr/debugger/-idt.md new file mode 100644 index 0000000000..ac014494f5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-idt.md @@ -0,0 +1,112 @@ +--- +title: idt +description: The idt extension displays the interrupt service routines (ISRs) for a specified interrupt dispatch table (IDT). +ms.assetid: 6b289fde-85a3-4a40-8354-db6861ca8cb2 +keywords: ["ISR (interrupt service routine)", "IDT (interrupt dispatch table)", "idt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- idt +api_type: +- NA +--- + +# !idt + + +The **!idt** extension displays the interrupt service routines (ISRs) for a specified interrupt dispatch table (IDT). + +``` +!idt IDT +!idt [-a] +!idt -? +``` + +## Parameters + + + *IDT* +Specifies the IDT to display. + + **-a** +When *IDT* is not specified, the debugger displays the IDTs of all processors on the target computer in an abbreviated format. If **-a** is specified, the ISRs for each IDT are also displayed. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x64-based or x86-based target computer. + +### Additional Information + +For information about ISRs and IDTs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For more information about how to display the interrupt vector tables on an Itanium target computer, see [**!ivt**](-ivt.md). + +Remarks +------- + +Here is an example of the output from this extension: + +``` +0: kd> !idt + +Dumping IDT: + +37:806ba78c hal!PicSpuriousService37 +3d:806bbc90 hal!HalpApcInterrupt +41:806bbb04 hal!HalpDispatchInterrupt +50:806ba864 hal!HalpApicRebootService +63:8641376c VIDEOPRT!pVideoPortInterrupt (KINTERRUPT 86413730) +73:862aa044 portcls!CInterruptSyncServiceRoutine (KINTERRUPT 862aa008) +82:86594314 atapi!IdePortInterrupt (KINTERRUPT 865942d8) +83:86591bec SCSIPORT!ScsiPortInterrupt (KINTERRUPT 86591bb0) +92:862b53dc serial!SerialCIsrSw (KINTERRUPT 862b53a0) +93:86435844 i8042prt!I8042KeyboardInterruptService (KINTERRUPT 86435808) +a3:863b366c i8042prt!I8042MouseInterruptService (KINTERRUPT 863b3630) +a4:8636bbec USBPORT!USBPORT_InterruptService (KINTERRUPT 8636bbb0) +b1:86585bec ACPI!ACPIInterruptServiceRoutine (KINTERRUPT 86585bb0) +b2:863c0524 serial!SerialCIsrSw (KINTERRUPT 863c04e8) +b4:86391a54 NDIS!ndisMIsr (KINTERRUPT 86391a18) + USBPORT!USBPORT_InterruptService (KINTERRUPT 863ae890) +c1:806ba9d0 hal!HalpBroadcastCallService +d1:806b9dd4 hal!HalpClockInterrupt +e1:806baf30 hal!HalpIpiHandler +e3:806baca8 hal!HalpLocalApicErrorService +fd:806bb460 hal!HalpProfileInterrupt +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!idt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-if.md b/windows-driver-docs-pr/debugger/-if.md new file mode 100644 index 0000000000..ee16795473 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-if.md @@ -0,0 +1,55 @@ +--- +title: .if +description: The .if token behaves like the if keyword in C. +ms.assetid: ccd74461-759f-400d-90da-efba2e4498e6 +keywords: [".if Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .if +api_type: +- NA +--- + +# .if + + +The **.if** token behaves like the **if** keyword in C. + +``` +.if (Condition) { Commands } + +.if (Condition) { Commands } .else { Commands } + +.if (Condition) { Commands } .elsif (Condition) { Commands } + +.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands } +``` + +## Syntax Elements + + + *Condition* +Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing *Condition* in parentheses is optional. *Condition* must be an expression, not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Commands* +Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.if%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ignore-missing-pages--suppress-missing-page-errors-.md b/windows-driver-docs-pr/debugger/-ignore-missing-pages--suppress-missing-page-errors-.md new file mode 100644 index 0000000000..1bd3bad5fc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ignore-missing-pages--suppress-missing-page-errors-.md @@ -0,0 +1,81 @@ +--- +title: .ignore_missing_pages (Suppress Missing Page Errors) +description: The .ignore_missing_pages command suppresses the error messages when a Kernel Memory Dump has missing pages. +ms.assetid: 74f4944e-6f0b-4541-b32f-a2da58df7f03 +keywords: ["Suppress Missing Page Errors (.ignore_missing_pages) command", ".ignore_missing_pages (Suppress Missing Page Errors) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .ignore_missing_pages (Suppress Missing Page Errors) +api_type: +- NA +--- + +# .ignore\_missing\_pages (Suppress Missing Page Errors) + + +The **.ignore\_missing\_pages** command suppresses the error messages when a Kernel Memory Dump has missing pages. + +``` +.ignore_missing_pages 0 +.ignore_missing_pages 1 +.ignore_missing_pages +``` + +## Parameters + + + **0** +Displays all missing page errors while debugging a Kernel Memory Dump. This is the default behavoir of the debugger. + + **1** +Suppresses the display of missing page errors while debugging a Kernel Memory Dump. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Dump file debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to debug these dump files, see [Kernel Memory Dump](kernel-memory-dump.md). + +Remarks +------- + +Without parameters, **.ignore\_missing\_pages** displays the current status of this setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.ignore_missing_pages%20%28Suppress%20Missing%20Page%20Errors%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-igrep.md b/windows-driver-docs-pr/debugger/-igrep.md new file mode 100644 index 0000000000..e69bc1483a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-igrep.md @@ -0,0 +1,66 @@ +--- +title: igrep +description: The igrep extension searches for a pattern in disassembly. +ms.assetid: f76aa84b-6d52-4b36-b2d0-d4a8d47d510e +keywords: ["igrep Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- igrep +api_type: +- NA +--- + +# !igrep + + +The **!igrep** extension searches for a pattern in disassembly. + +``` +!igrep [Pattern [StartAddress]] +``` + +## Parameters + + + *Pattern* +Specifies the pattern to search for. If omitted, the last *Pattern* is used. + + *StartAddress* +Specifies the hexadecimal address at which to begin searching. If omitted, the current program counter is used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Unavailable

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!igrep%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ih.md b/windows-driver-docs-pr/debugger/-ih.md new file mode 100644 index 0000000000..1555301473 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ih.md @@ -0,0 +1,109 @@ +--- +title: ih +description: The ih extension displays the interrupt history record for the specified processor. +ms.assetid: 4c81bde4-da8b-4c44-8013-6c586c08e22b +keywords: ["interrupt history record", "ih Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ih +api_type: +- NA +--- + +# !ih + + +The **!ih** extension displays the interrupt history record for the specified processor. + +``` +!ih Processor +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Processor* +Specifies a processor. If *Processor* is omitted, the current processor is used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +Remarks +------- + +This extension displays the interrupt history record without referencing the program counter symbols. To display the interrupt history record using the program counter symbols, use the [**!ihs**](-ihs.md) extension. To enable the interrupt history record, add **/configflag=32** to the boot entry options. + +Here is an example of the output from this extension: + +``` +kd> !ih +Total # of interruptions = 2093185 +Vector IIP IPSR ExtraField + VHPT FAULT e0000000830d3190 1010092a6018 IFA= 6fc00a0200c + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe00001de2d0 + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe01befff338 + VHPT FAULT e0000000830d3190 1010092a6018 IFA= 6fc00a0200c + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe00001d9188 + VHPT FAULT e0000000830d3880 1010092a6018 IFA= 1ffffe01befff250 + VHPT FAULT e0000000830d3fb0 1010092a6018 IFA= e0000165f82dc1c0 + VHPT FAULT e000000083063390 1010092a6018 IFA= e0000000fffe0018 + THREAD SWITCH e000000085896040 e00000008588c040 OSP= e0000165f82dbd40 + VHPT FAULT e00000008329b130 1210092a6018 IFA= e0000165f7edaf30 + VHPT FAULT e0000165f7eda640 1210092a6018 IFA= e0000165fff968a9 + PROCESS SWITCH e0000000818bbe10 e000000085896040 OSP= e0000165f8281de0 + VHPT FAULT e00000008307cfc0 1010092a2018 IFA= e00000008189fe50 +EXTERNAL INTERRUPT e0000000830623b0 1010092a6018 IVR= d0 + VHPT FAULT e00000008314e310 1010092a2018 IFA= e0000165f88203f0 + VHPT FAULT e000000083580760 1010092a2018 IFA= e0000000f00ff3fd + PROCESS SWITCH e00000008558c990 e0000000818bbe10 OSP= e00000008189fe20 + VHPT FAULT e00000008307cfc0 1010092a2018 IFA= e0000165f02433f0 + VHPT FAULT 77cfbda0 1013082a6018 IFA= 77cfbda0 + VHPT FAULT 77cfbdb0 1213082a6018 IFA= 6fbfee0ff98 + DATA ACCESS BIT 77b8e150 1213082a6018 IFA= 77c16ab8 + VHPT FAULT 77ed5d60 1013082a6018 IFA= 6fbfffa6048 + DATA ACCESS BIT 77ed5d60 1213082a6018 IFA= 77c229c0 + DATA ACCESS BIT 77b8e1b0 1013082a6018 IFA= 77c1c320 + USER SYSCALL 77cafa40 10082a6018 Num= 42 + VHPT FAULT e00000008344dc20 1010092a6018 IFA= e000010600703784 +... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ih%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ihs.md b/windows-driver-docs-pr/debugger/-ihs.md new file mode 100644 index 0000000000..45740365b8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ihs.md @@ -0,0 +1,109 @@ +--- +title: ihs +description: The ihs extension displays the interrupt history record for the specified processor, using program counter symbols. +ms.assetid: 3b91e8aa-5639-4273-9da4-1927d2ae8c62 +keywords: ["interrupt history record", "ihs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ihs +api_type: +- NA +--- + +# !ihs + + +The **!ihs** extension displays the interrupt history record for the specified processor, using program counter symbols. + +``` +!ihs Processor +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Processor* +Specifies a processor. If *Processor* is omitted, the current processor is used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium target computer. + +Remarks +------- + +To display the interrupt history record without using program counter symbols, use the [**!ih**](-ih.md) extension. To enable the interrupt history record, add **/configflag=32** to the boot entry options. + +Here is an example of the output from this extension: + +``` +kd> !ihs +Total # of interruptions = 2093185 +Vector IIP IPSR ExtraField IIP Symbol + VHPT FAULT e0000000830d3190 1010092a6018 IFA= 6fc00a0200c nt!MiAgeAndEstimateAvailableInWorkingSet+0x70 + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe00001de2d0 nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0 + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe01befff338 nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0 + VHPT FAULT e0000000830d3190 1010092a6018 IFA= 6fc00a0200c nt!MiAgeAndEstimateAvailableInWorkingSet+0x70 + VHPT FAULT e0000000830d33d0 1010092a6018 IFA= 1ffffe00001d9188 nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0 + VHPT FAULT e0000000830d3880 1010092a6018 IFA= 1ffffe01befff250 nt!MiAgeAndEstimateAvailableInWorkingSet+0x760 + VHPT FAULT e0000000830d3fb0 1010092a6018 IFA= e0000165f82dc1c0 nt!MiCheckAndSetSystemTrimCriteria+0x190 + VHPT FAULT e000000083063390 1010092a6018 IFA= e0000000fffe0018 nt!KeQuerySystemTime+0x30 + THREAD SWITCH e000000085896040 e00000008588c040 OSP= e0000165f82dbd40 + VHPT FAULT e00000008329b130 1210092a6018 IFA= e0000165f7edaf30 nt!IopProcessWorkItem+0x30 + VHPT FAULT e0000165f7eda640 1210092a6018 IFA= e0000165fff968a9 netbios!RunTimerForLana+0x60 + PROCESS SWITCH e0000000818bbe10 e000000085896040 OSP= e0000165f8281de0 + VHPT FAULT e00000008307cfc0 1010092a2018 IFA= e00000008189fe50 nt!SwapFromIdle+0x1e0 +EXTERNAL INTERRUPT e0000000830623b0 1010092a6018 IVR= d0 nt!Kil_TopOfIdleLoop + VHPT FAULT e00000008314e310 1010092a2018 IFA= e0000165f88203f0 nt!KdReceivePacket+0x10 + VHPT FAULT e000000083580760 1010092a2018 IFA= e0000000f00ff3fd hal!READ_PORT_UCHAR+0x80 + PROCESS SWITCH e00000008558c990 e0000000818bbe10 OSP= e00000008189fe20 + VHPT FAULT e00000008307cfc0 1010092a2018 IFA= e0000165f02433f0 nt!SwapFromIdle+0x1e0 + VHPT FAULT 77cfbda0 1013082a6018 IFA= 77cfbda0 0x0000000077cfbda0 + VHPT FAULT 77cfbdb0 1213082a6018 IFA= 6fbfee0ff98 0x0000000077cfbdb0 + DATA ACCESS BIT 77b8e150 1213082a6018 IFA= 77c16ab8 0x0000000077b8e150 + VHPT FAULT 77ed5d60 1013082a6018 IFA= 6fbfffa6048 0x0000000077ed5d60 + DATA ACCESS BIT 77ed5d60 1213082a6018 IFA= 77c229c0 0x0000000077ed5d60 + DATA ACCESS BIT 77b8e1b0 1013082a6018 IFA= 77c1c320 0x0000000077b8e1b0 + USER SYSCALL 77cafa40 10082a6018 Num= 42 0x0000000077cafa40 + VHPT FAULT e00000008344dc20 1010092a6018 IFA= e000010600703784 nt!ExpLookupHandleTableEntry+0x20 +... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ihs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-imggp.md b/windows-driver-docs-pr/debugger/-imggp.md new file mode 100644 index 0000000000..ead2965bb0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-imggp.md @@ -0,0 +1,63 @@ +--- +title: imggp +description: The imggp extension displays the global pointer (GP) directory entry value for a 64-bit image. +ms.assetid: fa566b11-ac41-442a-b843-decd64bd596e +keywords: ["global pointer (GP)", "GP (global pointer)", "imggp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- imggp +api_type: +- NA +--- + +# !imggp + + +The **!imggp** extension displays the global pointer (GP) directory entry value for a 64-bit image. + +``` +!imggp Address +``` + +## Parameters + + + *Address* +Specifies the base address of the image. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!imggp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-imgreloc.md b/windows-driver-docs-pr/debugger/-imgreloc.md new file mode 100644 index 0000000000..e85fc796d3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-imgreloc.md @@ -0,0 +1,76 @@ +--- +title: imgreloc +description: The imgreloc extension displays the addresses of each loaded module and indicates their former addresses before they were relocated. +ms.assetid: 79b729bd-7e4f-4167-b049-8a5c23cb8787 +keywords: ["imgreloc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- imgreloc +api_type: +- NA +--- + +# !imgreloc + + +The **!imgreloc** extension displays the addresses of each loaded module and indicates their former addresses before they were relocated. + +``` +!imgreloc Address +``` + +## Parameters + + + *Address* +Specifies the base address of the image. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +Here is an example: + +``` +0:000> !imgreloc 00400000 +00400000 Prymes - at preferred address +010e0000 appvcore - RELOCATED from 00400000 +5b2f0000 verifier - at preferred address +5d160000 ShimEng - at preferred address +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!imgreloc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-imgscan--find-image-headers-.md b/windows-driver-docs-pr/debugger/-imgscan--find-image-headers-.md new file mode 100644 index 0000000000..0732c8997a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-imgscan--find-image-headers-.md @@ -0,0 +1,94 @@ +--- +title: .imgscan (Find Image Headers) +description: The .imgscan command scans virtual memory for image headers. +ms.assetid: 8b524665-0471-4634-aa31-1c82d6cc8569 +keywords: ["Find Image Headers (.imgscan) command", ".imgscan (Find Image Headers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .imgscan (Find Image Headers) +api_type: +- NA +--- + +# .imgscan (Find Image Headers) + + +The **.imgscan** command scans virtual memory for image headers. + +``` +.imgscan [Options] +``` + +## Parameters + + + *Options* +Any of the following options: + +**/r** **** *Range* +Specifies the range to search. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If you specify only one address, the debugger searches a range that begins at that address and extends 0x10000 bytes. + +**/l** +Loads module information for any image header that is found. + +**/v** +Displays verbose information. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +If you do not use the **/r** parameter, the debugger searches all virtual memory regions. + +The **.imgscan** command displays any image headers that it finds and the header type. Header types include Portable Executable (PE) headers and Microsoft MS-DOS MZ headers. + +The following example shows the **.imgscan** command. + +``` +0:000> .imgscan +MZ at 00400000, prot 00000002, type 01000000 - size 2d000 +MZ at 77f80000, prot 00000002, type 01000000 - size 7d000 + Name: ntdll.dll +MZ at 7c570000, prot 00000002, type 01000000 - size b8000 + Name: KERNEL32.dll +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.imgscan%20%28Find%20Image%20Headers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-inline--toggle-inline-debugging-.md b/windows-driver-docs-pr/debugger/-inline--toggle-inline-debugging-.md new file mode 100644 index 0000000000..146f19cd9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-inline--toggle-inline-debugging-.md @@ -0,0 +1,52 @@ +--- +title: .inline (Toggle Inline Function Debugging) +description: The .inline command enables or disables inline function debugging. +ms.assetid: 7B6CB75D-E318-4832-935F-239531B8DC66 +keywords: [".inline (Toggle Inline Function Debugging) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .inline (Toggle Inline Function Debugging) +api_type: +- NA +--- + +# .inline (Toggle Inline Function Debugging) + + +The **.inline** command enables or disables inline function debugging. + +``` +.inline 0 +.inline 1 +``` + +## Parameters + + + **0** +Disables inline function debugging. + + **1** +Enables inline function debugging. + +## See also + + +[Debugging Optimized Code and Inline Functions](debugging-optimized-code-and-inline-functions-external.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.inline%20%28Toggle%20Inline%20Function%20Debugging%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ioctldecode.md b/windows-driver-docs-pr/debugger/-ioctldecode.md new file mode 100644 index 0000000000..74d28aa0e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ioctldecode.md @@ -0,0 +1,128 @@ +--- +title: ioctldecode +description: The ioctldecode extension displays the Device Type, Required Access, Function Code and Transfer Type as specified by the given IOCTL code. +ms.assetid: 50B12034-E5C7-43F2-A31E-AAC824A05D46 +keywords: ["ioctldecode Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ioctldecode +api_type: +- NA +--- + +# !ioctldecode + + +The **!ioctldecode** extension displays the *Device Type*, *Required Access*, *Function Code* and *Transfer Type* as specified by the given IOCTL code. For more information about IOCTL control codes, see [Defining I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff543023). + +``` +!ioctldecode IoctlCode +``` + +## Parameters + + + *IoctlCode* +Specifies the hexadecimal IOCTL Code. The [**!irp**](-irp.md) command displays the IOCTL code in its output. + +### DLL + + +++ + + + + + +

Kdexts.dll

+ +  + +### Additional Information + +To see information on the IOCTL, we first locate an IRP of interest. You can use the [**!irpfind**](-irpfind.md) command to locate an irp of interest. + +Use the [**!irp**](-irp.md) command to display information about the irp. + +``` +0: kd> !irp ffffd581a6c6cd30 +Irp is active with 6 stacks 6 is current (= 0xffffd581a6c6cf68) +No Mdl: No System Buffer: Thread 00000000: Irp stack trace. + cmd flg cl Device File Completion-Context +[N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +[N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +[N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +[N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +[N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +>[IRP_MJ_INTERNAL_DEVICE_CONTROL(f), N/A(0)] + 0 e1 ffffd581a5fbd050 00000000 fffff806d2412cf0-ffffd581a5cce050 Success Error Cancel pending + \Driver\usbehci (IopUnloadSafeCompletion) + Args: ffffd581a6c61a50 00000000 0x220003 00000000 +``` + +The third argument displayed, in this case *0x220003*, is the IOCTL code. Use the IOCTL code to display information about the IOCTL, in this case [**IOCTL\_INTERNAL\_USB\_SUBMIT\_URB**](https://msdn.microsoft.com/library/windows/hardware/ff537271). + +``` +0: kd> !ioctldecode 0x220003 + +IOCTL_INTERNAL_USB_SUBMIT_URB + +Device Type : 0x22 (FILE_DEVICE_WINLOAD) (FILE_DEVICE_USER_MODE_BUS) (FILE_DEVICE_USB) (FILE_DEVICE_UNKNOWN) +Method : 0x3 METHOD_NEITHER +Access : FILE_ANY_ACCESS +Function : 0x0 +``` + +If you provide an IOCTL code that is not available, you will see this type of output. + +``` +0: kd> !ioctldecode 0x1280ce + +Unknown IOCTL : 0x1280ce + +Device Type : 0x12 (FILE_DEVICE_NETWORK) +Method : 0x2 METHOD_OUT_DIRECT +Access : FILE_WRITE_ACCESS +Function : 0x33 +``` + +Although the IOCTL is not identified, information about the IOCTL fields are displayed. + +Note that only a subset of publically defined IOCTLs are able to be identified by the **!ioctldecode** command. + +For more information about IOCTLs see [Introduction to I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff548059). + +For more general information about IRPs and IOCTLs, refer to *Windows Internals* by Mark E. Russinovich, David A. Solomon and Alex Ionescu. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ioctldecode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ioresdes.md b/windows-driver-docs-pr/debugger/-ioresdes.md new file mode 100644 index 0000000000..6fc5af5164 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ioresdes.md @@ -0,0 +1,67 @@ +--- +title: ioresdes +description: The ioresdes extension displays the IO_RESOURCE_DESCRIPTOR structure at the specified address. +ms.assetid: a57dd414-16d6-4515-9eee-dac91398906b +keywords: ["ioresdes Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ioresdes +api_type: +- NA +--- + +# !ioresdes + + +The **!ioresdes** extension displays the IO\_RESOURCE\_DESCRIPTOR structure at the specified address. + +``` +!ioresdes Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the IO\_RESOURCE\_DESCRIPTOR structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about the IO\_RESOURCE\_DESCRIPTOR structure, see the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ioresdes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ioreslist.md b/windows-driver-docs-pr/debugger/-ioreslist.md new file mode 100644 index 0000000000..9b9ba3a915 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ioreslist.md @@ -0,0 +1,130 @@ +--- +title: ioreslist +description: The ioreslist extension displays an IO_RESOURCE_REQUIREMENTS_LIST structure. +ms.assetid: cb599656-2e0a-41ec-8358-a42047974dea +keywords: ["ioreslist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ioreslist +api_type: +- NA +--- + +# !ioreslist + + +The **!ioreslist** extension displays an IO\_RESOURCE\_REQUIREMENTS\_LIST structure. + +``` +!ioreslist Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the IO\_RESOURCE\_REQUIREMENTS\_LIST structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about the IO\_RESOURCE\_REQUIREMENTS\_LIST structure, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !ioreslist 0xe122b768 + +IoResList at 0xe122b768 : Interface 0x5 Bus 0 Slot 0xe + Alternative 0 (Version 1.1) + Preferred Descriptor 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000100 byte range with alignment 0x000100 + 1000 - 0x10ff + Alternative Descriptor 1 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000100 byte range with alignment 0x000100 + 0 - 0xffffffff + Descriptor 2 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data: : 0x1 0x0 0x0 + Preferred Descriptor 3 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + 0x001000 byte range with alignment 0x001000 + 40080000 - 0x40080fff + Alternative Descriptor 4 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + 0x001000 byte range with alignment 0x001000 + 0 - 0xffffffff + Descriptor 5 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data: : 0x1 0x1 0x0 + Descriptor 6 - Interrupt (0x2) Shared (0x3) + Flags (0000) - LEVEL_SENSITIVE + 0xb - 0xb +``` + +The IO\_RESOURCE\_REQUIREMENTS\_LIST contains information about: + +- Resource types + + There are four types of resources: I/O, Memory, IRQ, DMA. + +- Descriptors + + Each preferred setting has a "Preferred" descriptor and a number of "Alternative" descriptors. + +This resource list contains the following requests: + +- I/O Ranges + + Prefers a range of 0x1000 to 0x10FF inclusive, but can use any 0x100 range between 0 and 0xFFFFFFFF, provided it is 0x100-aligned. (For example, 0x1100 to 0x11FF is acceptable.) + +- Memory + + Prefers a range of 0x40080000 to 0x40080FFF, but can use any range that is of size 0x1000, is 0x1000-aligned, and is located between 0 and 0xFFFFFFFF. + +- IRQ + + Must use IRQ 0xB. + +Interrupts and DMA channels are represented as ranges with the same beginning and end. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ioreslist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-iovirp.md b/windows-driver-docs-pr/debugger/-iovirp.md new file mode 100644 index 0000000000..a84b707e34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-iovirp.md @@ -0,0 +1,107 @@ +--- +title: iovirp +description: The iovirp extension displays detailed information for a specified I/O Verifier IRP. +ms.assetid: 9b05061c-2a57-4e01-bbe0-2e2f5f676947 +keywords: ["I/O Verifier", "iovirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- iovirp +api_type: +- NA +--- + +# !iovirp + + +The **!iovirp** extension displays detailed information for a specified I/O Verifier IRP. + +``` +!iovirp [IRP] +``` + +## Parameters + + + *IRP* +Specifies the address of an IRP tracked by the Driver Verifier. If *IRP* is 0 or is omitted, the summary information for each outstanding IRP is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !iovirp 947cef68 +IovPacket 84509af0 +TrackedIrp 947cef68 +HeaderLock 84509d61 +LockIrql 0 +ReferenceCount 1 +PointerCount 1 +HeaderFlags 00000000 +ChainHead 84509af0 +Flags 00200009 +DepartureIrql 0 +ArrivalIrql 0 +StackCount 1 +QuotaCharge 00000000 +QuotaProcess 0 +RealIrpCompletionRoutine 0 +RealIrpControl 0 +RealIrpContext 0 +TopStackLocation 2 +PriorityBoost 0 +LastLocation 0 +RefTrackingCount 0 +SystemDestVA 0 +VerifierSettings 84509d08 +pIovSessionData 84509380 +Allocation Stack: + nt!IovAllocateIrp+1a (817df356) + nt!IopXxxControlFile+40c (8162de20) + nt!NtDeviceIoControlFile+2a (81633090) + nt!KiFastCallEntry+164 (81513c64) + nt!EtwpFlushBuffer+10f (817606d7) + nt!EtwpFlushBuffersWithMarker+bd (817608cb) + nt!EtwpFlushActiveBuffers+2b4 (81760bc2) + nt!EtwpLogger+213 (8176036f) +``` + +You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!iovirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ipi.md b/windows-driver-docs-pr/debugger/-ipi.md new file mode 100644 index 0000000000..6bf0660059 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ipi.md @@ -0,0 +1,101 @@ +--- +title: ipi +description: The ipi extension displays the interprocessor interrupt (IPI) state for a specified processor. +ms.assetid: 2727d429-82f5-44a6-943b-0a3f2d3385a3 +keywords: ["IPI (interprocessor interrupt)", "ipi Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ipi +api_type: +- NA +--- + +# !ipi + + +The **!ipi** extension displays the interprocessor interrupt (IPI) state for a specified processor. + +``` +!ipi [Processor] +``` + +## Parameters + + + *Processor* +Specifies a processor. If *Processor* is omitted, the IPI state for every processor is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +### Additional Information + +For information about IPIs, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +Here is an example of the output from this extension: + +``` +0: kd> !ipi +IPI State for Processor 0 + Worker Routine: nt!KiFlushTargetMultipleTb [Stale] + Parameter[0]: 0 + Parameter[1]: 3 + Parameter[2]: F7C98770 + Ipi Trap Frame: F7CCCCDC [.trap F7CCCCDC] + Signal Done: 0 + IPI Frozen: 24 [FreezeActive] [Owner] + Request Summary: 0 + Target Set: 0 + Packet Barrier: 0 + +IPI State for Processor 1 + Worker Routine: nt!KiFlushTargetMultipleTb [Stale] + Parameter[0]: 1 + Parameter[1]: 3 + Parameter[2]: F7CDCD28 + Ipi Trap Frame: F7C8CCC4 [.trap F7C8CCC4] + Signal Done: 0 + IPI Frozen: 2 [Frozen] + Request Summary: 0 + Target Set: 0 + Packet Barrier: 0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ipi%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-irp.md b/windows-driver-docs-pr/debugger/-irp.md new file mode 100644 index 0000000000..f0dfb6f442 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-irp.md @@ -0,0 +1,521 @@ +--- +title: irp extension command +description: The irp extension displays information about an I/O request packet (IRP). +ms.assetid: 2260255d-813b-4b89-8dbe-6ce7e5596ccf +keywords: ["IRP", "IRP, See "I/O Request Packet (IRP)"", "irp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- irp +api_type: +- NA +--- + +# !irp + + +The **!irp** extension displays information about an I/O request packet (IRP). + +``` +!irp Address [Detail] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the IRP. + + *Detail* +If this parameter is included with any value, such as 1, the output includes the status of the IRP, the address of its memory descriptor list (MDL), its owning thread, and stack information for all of its I/O stacks, and information about each stack location for the IRP, including hexadecimal versions of the major function code and the minor function code. If this parameter omitted, the output includes only a summary of the information. + +### DLL + + ++++ + + + + + + +

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) and [Debugging Interrupt Storms](debugging-an-interrupt-storm.md) for applications of this extension command. For information about IRPs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. For further information on the major and minor function codes, see the Windows Driver Kit (WDK) documentation. (These resources may not be available in some languages and countries.) + +This MSDN topic describes the IRP structure, [**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694). + +Remarks +------- + +The output also indicates under what conditions the completion routine for each stack location will be called once the IRP has completed and the stack location is processed. There are three possibilities: + + **Success** +Indicates that the completion routine will be called when the IRP is completed with a success code. + + **Error** +Indicates that the completion routine will be called when the IRP is completed with an error code. + + **Cancel** +Indicates that the completion routine will be called if an attempt was made to cancel the IRP. + +Any combination of these three may appear, and if any of the conditions shown are satisfied, the completion routine will be called. The appropriate values are listed at the end of the first row of information about each stack location, immediately after the **Completion-Context** entry. + +Here is an example of the output from this extension for Windows 10: + +``` +0: kd> !irp ac598dc8 +Irp is active with 2 stacks 1 is current (= 0xac598e38) + No Mdl: No System Buffer: Thread 8d1c7bc0: Irp stack trace. + cmd flg cl Device File Completion-Context +>[IRP_MJ_FILE_SYSTEM_CONTROL(d), N/A(0)] + 1 e1 8a6434d8 ac598d40 853220cb-a89682d8 Success Error Cancel pending + \FileSystem\Npfs fltmgr!FltpPassThroughCompletion + Args: 00000000 00000000 00110008 00000000 + [IRP_MJ_FILE_SYSTEM_CONTROL(d), N/A(0)] + 1 0 8a799710 ac598d40 00000000-00000000 + \FileSystem\FltMgr + Args: 00000000 00000000 0x00110008 00000000 +``` + +Starting with Windows 10 the IRP major and minor code text is displayed, for example, "IRP\_MJ\_FILE\_SYSTEM\_CONTROL" The code value is also shown in hex, in this example "(d)". + +The third argument displayed in the output, is the IOCTL code. Use the [**!ioctldecode**](-ioctldecode.md) command to display information about the IOCTL. + +Here is an example of the output from this extension from Windows Vista. + +``` +0: kd> !irp 0x831f4a00 +Irp is active with 8 stacks 5 is current (= 0x831f4b00) + Mdl = 82b020d8 Thread 8c622118: Irp stack trace. + cmd flg cl Device File Completion-Context + [ 0, 0] 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [ 0, 0] 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [ 0, 0] 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [ 0, 0] 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 +>[ 3,34] 40 e1 828517a8 00000000 842511e0-00000000 Success Error Cancel pending + \Driver\disk partmgr!PmReadWriteCompletion + Args: 00007000 00000000 fe084e00 00000004 + [ 3, 0] 40 e0 82851450 00000000 842414d4-82956350 Success Error Cancel + \Driver\PartMgr volmgr!VmpReadWriteCompletionRoutine + Args: 129131bb 000000de fe084e00 00000004 + [ 3, 0] 0 e0 82956298 00000000 847eeed0-829e2ba8 Success Error Cancel + \Driver\volmgr Ntfs!NtfsMasterIrpSyncCompletionRoutine + Args: 00007000 00000000 1bdae400 00000000 + [ 3, 0] 0 0 82ac2020 8e879410 00000000-00000000 + \FileSystem\Ntfs + Args: 00007000 00000000 00018400 00000000 +``` + +Note that the completion routine next to the driver name is set on that stack location, and it was set by the driver in the line below. In the preceding example, **Ntfs!NtfsMasterIrpSyncCompletionRoutine** was set by **\\FileSystem\\Ntfs**. The **Completion-Context** entry above **Ntfs!NtfsMasterIrpSyncCompletionRoutine**, **847eeed0-829e2ba8**, indicates the address of the completion routine, as well as the context that will be passed to **Ntfs!NtfsMasterIrpSyncCompletionRoutine**. From this we can see that the address of **Ntfs!NtfsMasterIrpSyncCompletionRoutine** is **847eeed0**, and the context that will be passed to this routine when it is called is **829e2ba8**. + +**IRP major function codes** + +The following information is included to help you interpret the output from this extension command. + +The IRP major function codes are as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Major Function CodeHexadecimal Code

IRP_MJ_CREATE

0x00

IRP_MJ_CREATE_NAMED_PIPE

0x01

IRP_MJ_CLOSE

0x02

IRP_MJ_READ

0x03

IRP_MJ_WRITE

0x04

IRP_MJ_QUERY_INFORMATION

0x05

IRP_MJ_SET_INFORMATION

0x06

IRP_MJ_QUERY_EA

0x07

IRP_MJ_SET_EA

0x08

IRP_MJ_FLUSH_BUFFERS

0x09

IRP_MJ_QUERY_VOLUME_INFORMATION

0x0A

IRP_MJ_SET_VOLUME_INFORMATION

0x0B

IRP_MJ_DIRECTORY_CONTROL

0x0C

IRP_MJ_FILE_SYSTEM_CONTROL

0x0D

IRP_MJ_DEVICE_CONTROL

0x0E

+IRP_MJ_INTERNAL_DEVICE_CONTROL +IRP_MJ_SCSI

0x0F

IRP_MJ_SHUTDOWN

0x10

IRP_MJ_LOCK_CONTROL

0x11

IRP_MJ_CLEANUP

0x12

IRP_MJ_CREATE_MAILSLOT

0x13

IRP_MJ_QUERY_SECURITY

0x14

IRP_MJ_SET_SECURITY

0x15

IRP_MJ_POWER

0x16

IRP_MJ_SYSTEM_CONTROL

0x17

IRP_MJ_DEVICE_CHANGE

0x18

IRP_MJ_QUERY_QUOTA

0x19

IRP_MJ_SET_QUOTA

0x1A

+IRP_MJ_PNP +IRP_MJ_MAXIMUM_FUNCTION

0x1B

+ +  + +The Plug and Play minor function codes are as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Minor Function CodeHexadecimal Code

IRP_MN_START_DEVICE

0x00

IRP_MN_QUERY_REMOVE_DEVICE

0x01

IRP_MN_REMOVE_DEVICE

0x02

IRP_MN_CANCEL_REMOVE_DEVICE

0x03

IRP_MN_STOP_DEVICE

0x04

IRP_MN_QUERY_STOP_DEVICE

0x05

IRP_MN_CANCEL_STOP_DEVICE

0x06

IRP_MN_QUERY_DEVICE_RELATIONS

0x07

IRP_MN_QUERY_INTERFACE

0x08

IRP_MN_QUERY_CAPABILITIES

0x09

IRP_MN_QUERY_RESOURCES

0x0A

IRP_MN_QUERY_RESOURCE_REQUIREMENTS

0x0B

IRP_MN_QUERY_DEVICE_TEXT

0x0C

IRP_MN_FILTER_RESOURCE_REQUIREMENTS

0x0D

IRP_MN_READ_CONFIG

0x0F

IRP_MN_WRITE_CONFIG

0x10

IRP_MN_EJECT

0x11

IRP_MN_SET_LOCK

0x12

IRP_MN_QUERY_ID

0x13

IRP_MN_QUERY_PNP_DEVICE_STATE

0x14

IRP_MN_QUERY_BUS_INFORMATION

0x15

IRP_MN_DEVICE_USAGE_NOTIFICATION

0x16

IRP_MN_SURPRISE_REMOVAL

0x17

IRP_MN_QUERY_LEGACY_BUS_INFORMATION

0x18

+ +  + +The WMI minor function codes are as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Minor Function CodeHexadecimal Code

IRP_MN_QUERY_ALL_DATA

0x00

IRP_MN_QUERY_SINGLE_INSTANCE

0x01

IRP_MN_CHANGE_SINGLE_INSTANCE

0x02

IRP_MN_CHANGE_SINGLE_ITEM

0x03

IRP_MN_ENABLE_EVENTS

0x04

IRP_MN_DISABLE_EVENTS

0x05

IRP_MN_ENABLE_COLLECTION

0x06

IRP_MN_DISABLE_COLLECTION

0x07

IRP_MN_REGINFO

0x08

IRP_MN_EXECUTE_METHOD

0x09

+ +  + +The power management minor function codes are as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Minor Function CodeHexadecimal Code

IRP_MN_WAIT_WAKE

0x00

IRP_MN_POWER_SEQUENCE

0x01

IRP_MN_SET_POWER

0x02

IRP_MN_QUERY_POWER

0x03

+ +  + +The SCSI minor function codes are as follows: + + ++++ + + + + + + + + + + + + +
Minor Function CodeHexadecimal Code

IRP_MN_SCSI_CLASS

0x01

+ +  + +## See also + + +[**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694) + +[**!irpfind**](-irpfind.md) + +[**!ioctldecode**](-ioctldecode.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!irp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-irpfind.md b/windows-driver-docs-pr/debugger/-irpfind.md new file mode 100644 index 0000000000..e8fc03deef --- /dev/null +++ b/windows-driver-docs-pr/debugger/-irpfind.md @@ -0,0 +1,139 @@ +--- +title: irpfind +description: The irpfind extension displays information about all I/O request packets (IRP) currently allocated in the target system, or about those IRPs matching the specified search criteria. +ms.assetid: f0d850d9-8804-40df-90a3-b9c6a6b4540f +keywords: ["irpfind Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- irpfind +api_type: +- NA +--- + +# !irpfind + + +The **!irpfind** extension displays information about all I/O request packets (IRP) currently allocated in the target system, or about those IRPs matching the specified search criteria. + +Syntax + +``` +!irpfind [-v][PoolType[RestartAddress[CriteriaData]]] +``` + +## Parameters + + + **-v** +Displays verbose information. + + *PoolType* +Specifies the type of pool to be searched. The following values are permitted: + +0 +Specifies nonpaged memory pool. This is the default. + +1 +Specifies paged memory pool. + +2 +Specifies the special pool. + +4 +Specifies the session pool. + + *RestartAddress* +Specifies the hexadecimal address at which to begin the search. This is useful if the previous search was terminated prematurely. The default is zero. + + *Criteria* +Specifies the criteria for the search. Only those IRPs that satisfy the given match will be displayed. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CriteriaMatch

arg

Finds all IRPs with a stack location where one of the arguments equals Data.

device

Finds all IRPs with a stack location where DeviceObject equals Data.

fileobject

Finds all IRPs whose Irp.Tail.Overlay.OriginalFileObject equals Data.

mdlprocess

Finds all IRPs whose Irp.MdlAddress.Process equals Data.

thread

Finds all IRPs whose Irp.Tail.Overlay.Thread equals Data.

userevent

Finds all IRPs whose Irp.UserEvent equals Data.

+ +  + + *Data* +Specifies the data to be matched in the search. + +### DLL + +Kdexts.dll + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about IRPs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +This example finds the IRP in the nonpaged pool that is going to set user event FF9E4F48 upon completion: + +``` +kd> !irpfind 0 0 userevent ff9e4f48 +``` + +The following example produces a full listing of all IRPs in the nonpaged pool: + +``` +kd> !irpfind +Searching NonPaged pool (8090c000 : 8131e000) for Tag: Irp +8097c008 Thread 8094d900 current stack belongs to \Driver\symc810 +8097dec8 Thread 8094dda0 current stack belongs to \FileSystem\Ntfs +809861a8 Thread 8094dda0 current stack belongs to \Driver\symc810 +809864e8 Thread 80951ba0 current stack belongs to \Driver\Mouclass +80986608 Thread 80951ba0 current stack belongs to \Driver\Kbdclass +80986728 Thread 8094dda0 current stack belongs to \Driver\symc810 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!irpfind%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-irpzone.md b/windows-driver-docs-pr/debugger/-irpzone.md new file mode 100644 index 0000000000..4d18eeeb59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-irpzone.md @@ -0,0 +1,29 @@ +--- +title: irpzone +description: irpzone +ms.assetid: 85da1a2d-ca80-412a-bb46-dad450cb2d15 +keywords: ["irpzone extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !irpzone + + +## + + +The **!irpzone** extension command is obsolete. Use [**!irpfind**](-irpfind.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!irpzone%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-irql.md b/windows-driver-docs-pr/debugger/-irql.md new file mode 100644 index 0000000000..a61ec19f5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-irql.md @@ -0,0 +1,110 @@ +--- +title: irql extension command +description: The irql extension displays the interrupt request level (IRQL) of a processor on the target computer before the debugger break. +ms.assetid: 52dd3b9f-c03c-4b90-a01b-25289de67f5a +keywords: ["IRQL (Interrupt Request Level)", "IRQL (Interrupt Request Level), See "Interrupt Request Level (IRQL)"", "irql Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- irql +api_type: +- NA +--- + +# !irql + + +The **!irql** extension displays the interrupt request level (IRQL) of a processor on the target computer before the debugger break. + +``` +!irql [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor. Enter the processor number. If this parameter is omitted, the debugger displays the IRQL of the current processor. + +### DLL + +The **!irql** extension is only available in Windows Server 2003 and later versions of Windows. + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Server 2003 and later

Kdexts.dll

+ +  + +### Additional Information + +For information about IRQLs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +When the target computer breaks into the debugger, the IRQL changes, but the IRQL that was effective just before the debugger break is saved. The **!irql** extension displays the saved IRQL. + +Similarly, when a bug check occurs and a crash dump file is created, the IRQL saved in the crash dump file is the one immediately prior to the bug check, not the IRQL at which the [**KeBugCheckEx**](https://msdn.microsoft.com/library/windows/hardware/ff551961) routine was executed. + +In both cases, the current IRQL is raised to DISPATCH\_LEVEL, except on x86 architectures. Thus, if more than one such event occurs, the IRQL displayed will also be DISPATCH\_LEVEL, making it useless for debugging purposes. + +The [**!pcr**](-pcr.md) extension displays the current IRQL on all versions of Windows, but the current IRQL is usually not useful. The IRQL that existed just before the bug check or debugger connection is more interesting, and this is displayed only with **!irql**. + +If you supply an invalid processor number, or there has been kernel corruption, the debugger displays a message "Cannot get PRCB address". + +Here is an example of the output from this extension from a dual-processor x86 computer: + +``` +kd> !irql 0 +Debugger saved IRQL for processor 0x0 -- 28 (CLOCK2_LEVEL) + +kd> !irql 1 +Debugger saved IRQL for processor 0x1 -- 0 (LOW_LEVEL) +``` + +If the debugger is in verbose mode, a description of the IRQL itself is included. Here is an example from an Itanium processor: + +``` +kd> !irql +Debugger saved IRQL for processor 0x0 -- 12 (PC_LEVEL) [Performance counter level] +``` + +The meaning of the IRQL number often depends on the processor. Here is an example from an x64 processor. Note that the IRQL number is the same as in the previous example, but the IRQL meaning is different: + +``` +kd> !irql +Debugger saved IRQL for processor 0x0 -- 12 (SYNCH_LEVEL) [Synchronization level] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!irql%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-isainfo.md b/windows-driver-docs-pr/debugger/-isainfo.md new file mode 100644 index 0000000000..6e7ef313e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-isainfo.md @@ -0,0 +1,78 @@ +--- +title: isainfo +description: The isainfo extension displays information about PNPISA cards or devices present in the system.. +ms.assetid: 8caa501e-3bb7-4af8-a7ea-e8b255b9f24c +keywords: ["I/O Bus", "CARD_INFORMATION", "isainfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- isainfo +api_type: +- NA +--- + +# !isainfo + + +The **!isainfo** extension displays information about PNPISA cards or devices present in the system.. + +``` +!isainfo [Card] +``` + +## Parameters + + + *Card* +Specifies a PNPISA Card. If *Card* is 0 or omitted, all the devices and cards on the PNPISA (that is, the PC I/O) Bus are displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example of the output from this extension: + +``` +0: kd> !isainfo +ISA PnP FDO @ 0x867b9938, DevExt @ 0x867b99f0, Bus # 0 +Flags (0x80000000) DF_BUS + + ISA PnP PDO @ 0x867B9818, DevExt @ 0x86595388 + Flags (0x40000818) DF_ENUMERATED, DF_ACTIVATED, + DF_REQ_TRIMMED, DF_READ_DATA_PORT +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!isainfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-isr.md b/windows-driver-docs-pr/debugger/-isr.md new file mode 100644 index 0000000000..4a843118f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-isr.md @@ -0,0 +1,110 @@ +--- +title: isr +description: The isr extension displays the Itanium Interruption Status Register (ISR) at the specified address. +ms.assetid: 35cf1749-2417-4fd9-9de2-0884ee795ab3 +keywords: ["ISR (Interruption Status Register)", "Interruption Status Register (ISR)", "isr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- isr +api_type: +- NA +--- + +# !isr + + +The !isr extension displays the Itanium Interruption Status Register (ISR) at the specified address. + +``` +!isr Expression [DisplayLevel] +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Expression* +Specifies the hexadecimal address of the ISR register to display. The expression **@isr** can also be used for this parameter. In that case, information about the current processor ISR register is displayed. + + *DisplayLevel* +Can be any one of the following options: + +**0** +Displays only the values of each ISR field. This is the default. + +**1** +Displays detailed information about ISR fields that are not reserved or ignored. + +**2** +Displays details about all ISR fields, including those that are ignored or reserved. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium target computer. + +Remarks +------- + +Here are a couple of examples of output from this extension: + +``` +kd> !isr @isr +isr:ed ei so ni ir rs sp na r w x vector code + 0 0 0 0 0 0 0 0 0 0 0 0 0 + +kd> !isr @isr 2 + + cod : 0 : interruption Code + vec : 0 : IA32 exception vector number + rv : 0 : reserved0 + x : 0 : eXecute exception + w : 0 : Write exception + r : 0 : Read exception + na : 0 : Non-Access exception + sp : 0 : Speculative load exception + rs : 0 : Register Stack + ir : 0 : Invalid Register frame + ni : 0 : Nested Interruption + so : 0 : IA32 Supervisor Override + ei : 0 : Exception IA64 Instruction + ed : 0 : Exception Deferral + rv : 0 : reserved1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!isr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ivt.md b/windows-driver-docs-pr/debugger/-ivt.md new file mode 100644 index 0000000000..bac5c381dc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ivt.md @@ -0,0 +1,117 @@ +--- +title: ivt +description: The ivt extension displays the Itanium interrupt vector table. +ms.assetid: 855c50ed-361e-4236-a1b0-e1b2a3ae2a62 +keywords: ["interrupt vector table", "ivt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ivt +api_type: +- NA +--- + +# !ivt + + +The !ivt extension displays the Itanium interrupt vector table. + +``` +!ivt [-v] [-a] [Vector] +!ivt -? +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Vector* +Specifies an interrupt vector table entry for the current processor. If *Vector* is omitted, the entire interrupt vector table for the current processor on the target computer is displayed. Interrupt vectors that have not been assigned are not displayed unless the **-a** option is specified. + + **-a** +Displays all interrupt vectors, including those that are unassigned. + + **-v** +Displays detailed output. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium target computer. + +### Additional Information + +For more information about how to display the interrupt dispatch tables on an x64 or x86 target computer, see [**!idt**](-idt.md). + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !ivt + +Dumping IA64 IVT: + +00:e000000083005f60 nt!KiPassiveRelease +0f:e000000083576830 hal!HalpPCIISALine2Pin +10:e0000000830067f0 nt!KiApcInterrupt +20:e000000083006790 nt!KiDispatchInterrupt +30:e000000083576b30 hal!HalpCMCIHandler +31:e000000083576b20 hal!HalpCPEIHandler +41:e000000085039680 i8042prt!I8042KeyboardInterruptService (KINTERRUPT e000000085039620) +51:e000000085039910 i8042prt!I8042MouseInterruptService (KINTERRUPT e0000000850398b0) +61:e0000000854484f0 VIDEOPRT!pVideoPortInterrupt (KINTERRUPT e000000085448490) +71:e0000000856c9450 NDIS!ndisMIsr (KINTERRUPT e0000000856c93f0) +81:e0000000857fd000 SCSIPORT!ScsiPortInterrupt (KINTERRUPT e0000000857fcfa0) +91:e0000000857ff510 atapi!IdePortInterrupt (KINTERRUPT e0000000857ff4b0) +a1:e0000000857d84b0 atapi!IdePortInterrupt (KINTERRUPT e0000000857d8450) +a2:e0000165fff2cab0 portcls!CInterruptSyncServiceRoutine (KINTERRUPT e0000165fff2ca50) +b1:e0000000858c7460 ACPI!ACPIInterruptServiceRoutine (KINTERRUPT e0000000858c7400) +b2:e0000000850382e0 USBPORT!USBPORT_InterruptService (KINTERRUPT e000000085038280) +d0:e0000000835768d0 hal!HalpClockInterrupt +e0:e000000083576850 hal!HalpIpiInterruptHandler +f0:e0000000835769c0 hal!HalpProfileInterrupt +f1:e000000083576830 hal!HalpPCIISALine2Pin +fd:e000000083576b10 hal!HalpMcRzHandler +fe:e000000083576830 hal!HalpPCIISALine2Pin +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ivt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-jdinfo--use-jit-debug-info-.md b/windows-driver-docs-pr/debugger/-jdinfo--use-jit-debug-info-.md new file mode 100644 index 0000000000..b004ec0bc9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-jdinfo--use-jit-debug-info-.md @@ -0,0 +1,226 @@ +--- +title: .jdinfo (Use JIT_DEBUG_INFO) +description: The .jdinfo command uses a JIT_DEBUG_INFO structure as the source of the exception and context for just in time (JIT) debugging. +ms.assetid: C35A2A04-CF0E-475e-8471-2A8562BB3650 +keywords: ["Use JIT_DEBUG_INFO (.jdinfo) command ----- Appendix", "JIT_DEBUG_INFO ----- Appendix", ".jdinfo (Use JIT_DEBUG_INFO) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .jdinfo (Use JIT_DEBUG_INFO) +api_type: +- NA +--- + +# .jdinfo (Use JIT\_DEBUG\_INFO) + + +The **.jdinfo** command uses a JIT\_DEBUG\_INFO structure as the source of the exception and context for just in time (JIT) debugging. The address to the structure is passed to the **.jdinfo** command using the %p parameter that is specified in the AeDebug registry entry. + +For more information about the registry keys used, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). For more information about register contexts, see [Changing Contexts](changing-contexts.md). + +``` +.jdinfo Address +``` + +## Parameters + + + *Address* +Specifies the address of the JIT\_DEBUG\_INFO structure. The address to the structure is passed to the **.jdinfo** command using the %p parameter that is specified in the AeDebug registry entry. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Example + +This example show how the AeDebug registry entry can be configured to use the WinDbg can be used as the JIT debugger. + +``` +Debugger = "Path\WinDbg.EXE -p %ld -e %ld -c ".jdinfo 0x%p" +``` + +Then, when a crash occurs, the configured JIT debugger is invoked and the %p parameter is used to pass the address of the JIT\_DEBUG\_INFO structure to the **.jdinfo** command that is executed after the debugger is started. + +``` +nMicrosoft (R) Windows Debugger Version 10.0.10240.9 AMD64 +Copyright (c) Microsoft Corporation. All rights reserved. + +*** wait with pending attach +Executable search path is: +... +ModLoad: 00000000`68a20000 00000000`68ac3000 C:\WINDOWS\WinSxS\amd64_microsoft.vc90.crt_1fc8b3b9a1e18e3b_9.0.30729.9247_none_08e394a1a83e212f\MSVCR90.dll +(153c.5d0): Break instruction exception - code 80000003 (first chance) +Processing initial command '.jdinfo 0x00000000003E0000' +ntdll!DbgBreakPoint: +00007ffc`81a986a0 cc int 3 +0:003> .jdinfo 0x00000000003E0000 +----- Exception occurred on thread 0:15c8 +ntdll!ZwWaitForMultipleObjects+0x14: +00007ffc`81a959a4 c3 ret + +----- Exception record at 00000000`003e0028: +ExceptionAddress: 00007ff791d81014 (CrashAV_x64!wmain+0x0000000000000014) + ExceptionCode: c0000005 (Access violation) + ExceptionFlags: 00000000 +NumberParameters: 2 + Parameter[0]: 0000000000000001 + Parameter[1]: 0000000000000000 +Attempt to write to address 0000000000000000 + +----- Context record at 00000000`003e00c0: +rax=0000000000000000 rbx=0000000000000000 rcx=00007ffc81a954d4 +rdx=0000000000000000 rsi=0000000000000000 rdi=0000000000000001 +rip=00007ff791d81014 rsp=00000000006ff8b0 rbp=0000000000000000 + r8=00000000006ff808 r9=0000000000000000 r10=0000000000000000 +r11=0000000000000000 r12=0000000000000000 r13=0000000000000000 +r14=0000000000000000 r15=0000000000000000 +iopl=0 nv up ei pl zr na po nc +cs=0033 ss=002b ds=002b es=002b fs=0053 gs=002b efl=00010246 +CrashAV_x64!wmain+0x14: +00007ff7`91d81014 45891b mov dword ptr [r11],r11d ds:00000000`00000000=???????? +``` + +Remarks +------- + +The **.jdinfo** command uses the **AeDebug** registry information introduced in Windows Vista. For more information about the registry keys used, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). The **.jdinfo** command takes the address of a JIT\_DEBUG\_INFO that the system set up for **AeDebug** and sets the context to the exception that caused the crash. + +You can use the **.jdinfo** command instead of **-g** in **AeDebug** to have your debugger set to the **AeDebug** state without requiring execution. + +This state can be advantageous, because under usual conditions, when a user-mode exception occurs, the following sequence occurs: + +1. The Microsoft Windows operating system halts execution of the application. + +2. The postmortem debugger is started. + +3. The debugger attaches to the application. + +4. The debugger issues a "Go" command. (This command is caused by the **-g** in the **AeDebug** key.) + +5. The target attempts to execute and may or may not encounter the same exception. + +6. This exception breaks into the debugger. + +There are several problems that can occur because of these events: + +- Exceptions do not always repeat, possibly because of a transient condition that no longer exists when the exception is restarted. + +- Another event, such as a different exception, might occur. There is no way of knowing whether it is identical to the original event. + +- Attaching a debugger involves injecting a new thread, which can be blocked if a thread is holding the loader lock. Injecting a new thread can be a significant disturbance of the process. + +If you use **-c .jdinfo** instead of **-g** in your **AeDebug** key, no execution occurs. Instead, the exception information is retrieved from the JIT\_DEBUG\_INFO structure using the %p variable. + +For example, consider the following **AeDebug** key. + +``` +ntsd -p %ld -e %ld -c ".jdinfo 0x%p" +``` + +The following example is even less invasive. The **-pv** switch causes the debugger to attach noninvasively, which does not inject any new threads into the target. + +``` +ntsd -pv -p %ld -e %ld -c ".jdinfo 0x%p" +``` + +If you use this noninvasive option, exiting the debugger does not end the process. You can use the [**.kill (Kill Process)**](-kill--kill-process-.md) command to end the process. + +If you want to use this for dump file debugging, you should use [**.dump /j**](-dump--create-dump-file-.md) to add the JIT\_DEBUG\_INFO structure to your dump file, when the dump file is created. + +The JIT\_DEBUG\_INFO structure is defined as follows. + +``` +typedef struct _JIT_DEBUG_INFO { + DWORD dwSize; + DWORD dwProcessorArchitecture; + DWORD dwThreadID; + DWORD dwReserved0; + ULONG64 lpExceptionAddress; + ULONG64 lpExceptionRecord; + ULONG64 lpContextRecord; +} JIT_DEBUG_INFO, *LPJIT_DEBUG_INFO; +``` + +You can use the dt command to display the JIT\_DEBUG\_INFO structure. + +``` +0: kd> dt JIT_DEBUG_INFO +nt!JIT_DEBUG_INFO + +0x000 dwSize : Uint4B + +0x004 dwProcessorArchitecture : Uint4B + +0x008 dwThreadID : Uint4B + +0x00c dwReserved0 : Uint4B + +0x010 lpExceptionAddress : Uint8B + +0x018 lpExceptionRecord : Uint8B + +0x020 lpContextRecord : Uint8B +``` + +**Viewing the Exception Record, Call Stack and LastEvent Using WinDbg** + +After the .jdinfo command has been used to set the context to the moment of failure, you can view the exception record returned by .jdinfo, the call stack and the lastevent, as shown below, to investigate cause. + +``` +0:000> .jdinfo 0x00000000003E0000 +----- Exception occurred on thread 0:15c8 +ntdll!NtWaitForMultipleObjects+0x14: +00007ffc`81a959a4 c3 ret + +----- Exception record at 00000000`003e0028: +ExceptionAddress: 00007ff791d81014 (CrashAV_x64!wmain+0x0000000000000014) + ExceptionCode: c0000005 (Access violation) + ExceptionFlags: 00000000 +NumberParameters: 2 + Parameter[0]: 0000000000000001 + Parameter[1]: 0000000000000000 +Attempt to write to address 0000000000000000 +... + +0:000> k + *** Stack trace for last set context - .thread/.cxr resets it +# Child-SP RetAddr Call Site +00 00000000`006ff8b0 00007ff7`91d811d2 CrashAV_x64!wmain+0x14 [c:\my\my_projects\crash\crashav\crashav.cpp @ 14] +01 00000000`006ff8e0 00007ffc`7fa38364 CrashAV_x64!__tmainCRTStartup+0x11a [f:\dd\vctools\crt_bld\self_64_amd64\crt\src\crtexe.c @ 579] +02 00000000`006ff910 00007ffc`81a55e91 KERNEL32!BaseThreadInitThunk+0x14 +03 00000000`006ff940 00000000`00000000 ntdll!RtlUserThreadStart+0x21 + +0:000> .lastevent +Last event: 153c.5d0: Break instruction exception - code 80000003 (first chance) + debugger time: Thu Sep 8 12:55:08.968 2016 (UTC - 7:00) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.jdinfo%20%28Use%20JIT_DEBUG_INFO%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-job.md b/windows-driver-docs-pr/debugger/-job.md new file mode 100644 index 0000000000..4b4608ab70 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-job.md @@ -0,0 +1,112 @@ +--- +title: job +description: The job extension displays a job object. +ms.assetid: 1fbadcc7-d81b-4cfb-a54a-7843e2f78ea1 +keywords: ["job Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- job +api_type: +- NA +--- + +# !job + + +The **!job** extension displays a job object. + +``` +!job [Process [Flags]] +``` + +## Parameters + + + *Process* +Specifies the hexadecimal address of a process or a thread whose associated job object is to be examined. If this is omitted, or equal to -1 (in Windows 2000), or equal to zero (in Windows XP and later), the job associated with the current process is displayed. + + *Flags* +Specifies what the display should contain. This can be a sum of any of the following bit values. The default is 0x1: + +Bit 0 (0x1) +Causes the display to include job settings and statistics. + +Bit 1 (0x2) +Causes the display to include a list of all processes in the job. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about job objects, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +Here is an example of the output from this extension: + +``` +kd> !process 52c +Searching for Process with Cid == 52c +PROCESS 8276c550 SessionId: 0 Cid: 052c Peb: 7ffdf000 ParentCid: 0060 + DirBase: 01289000 ObjectTable: 825f0368 TableSize: 24. + Image: cmd.exe + VadRoot 825609e8 Vads 30 Clone 0 Private 77. Modified 0. Locked 0. + DeviceMap e1733f38 + Token e1681610 + ElapsedTime 0:00:12.0949 + UserTime 0:00:00.0359 + ..... + CommitCharge 109 + Job 8256e1f0 + +kd> !job 8256e1f0 +Job at ffffffff8256e1f0 + TotalPageFaultCount 0 + TotalProcesses 1 + ActiveProcesses 1 + TotalTerminatedProcesses 0 + LimitFlags 0 + MinimumWorkingSetSize 0 + MaximumWorkingSetSize 0 + ActiveProcessLimit 0 + PriorityClass 0 + UIRestrictionsClass 0 + SecurityLimitFlags 0 + Token 00000000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!job%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-kb---kv.md b/windows-driver-docs-pr/debugger/-kb---kv.md new file mode 100644 index 0000000000..12f346c53d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kb---kv.md @@ -0,0 +1,29 @@ +--- +title: kb, kv +description: kb, kv +ms.assetid: 400c9398-eee5-4d8d-8f8f-8229dfd54753 +keywords: ["kb extension (obsolete)", "kv extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !kb, !kv + + +## + + +The !kb and !kv extension commands are obsolete. Use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) and **kv (Display Stack Backtrace)** commands instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!kb,%20!kv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-kdfiles--set-driver-replacement-map-.md b/windows-driver-docs-pr/debugger/-kdfiles--set-driver-replacement-map-.md new file mode 100644 index 0000000000..48ea9070f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kdfiles--set-driver-replacement-map-.md @@ -0,0 +1,122 @@ +--- +title: .kdfiles (Set Driver Replacement Map) +description: The .kdfiles command reads a file and uses its contents as the driver replacement map. +ms.assetid: 3b0ac8c1-f0bd-4878-9303-23d6999650ee +keywords: ["Set Driver Replacement Map (.kdfiles) command", "driver replacement map, Set Driver Replacement Map (.kdfiles) command", ".kdfiles (Set Driver Replacement Map) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .kdfiles (Set Driver Replacement Map) +api_type: +- NA +--- + +# .kdfiles (Set Driver Replacement Map) + + +The **.kdfiles** command reads a file and uses its contents as the driver replacement map. + +``` +.kdfiles MapFile +.kdfiles -m OldDriver NewDriver +.kdfiles -s SaveFile +.kdfiles -c +.kdfiles +``` + +## Parameters + + + *MapFile* +Specifies the driver replacement map file to read. + + **-m** +Adds a driver replacement association to the current association list. + + *OldDriver* +Specifies the path and file name of the previous driver on the target computer. The syntax for *OldDriver* is the same as that of the first line after **map** in a driver replacement file. For more information about this syntax, see [Mapping Driver Files](mapping-driver-files.md). + + *NewDriver* +Specifies the path and file name of the new driver. This driver can be on the host computer or at some other network location. The syntax for *NewDriver* is the same as that of the second line after **map** in a driver replacement file. For more information about this syntax, see [Mapping Driver Files](mapping-driver-files.md). + + **-s** +Creates a file and writes the current driver replacement associations to that file. + + *SaveFile* +Specifies the name of the file to create. + + **-c** +Deletes the existing driver replacement map. (This option does not alter the map file itself. Instead, this option clears the debugger's current map settings.) + +### Environment + +You can use the **.kdfiles** command in Microsoft Windows XP and later versions of Windows. If you use this command in earlier versions of Windows, the command has no effect and does not generate an error. + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

x86-based and Itanium-based processors only

+ +  + +### Additional Information + +For more information about and examples of driver replacement and the replacement of other kernel-mode modules, a description of the format for driver replacement map files, and restrictions for using this feature, see [Mapping Driver Files](mapping-driver-files.md). + +Remarks +------- + +If you use the **.kdfiles** command without parameters, the debugger displays the path and name of the current driver replacement map file and the current set of replacement associations. + +When you run this command, the specified *MapFile*file is read. If the file is not found or if it does not contain text in the proper format, the debugger displays a message that states, "Unable to load file associations". + +If the specified file is in the correct driver replacement map file format, the debugger loads the file's contents and uses them as the driver replacement map. This map remains until you exit the debugger, or until you issue another **.kdfiles** command. + +After the file has been read, the driver replacement map is not affected by subsequent changes to the file (unless these changes are followed by another **.kdfiles** command). + +Requirements +------------ + + ++++ + + + + + + +

Version

Supported in Windows XP and later versions of the Windows operating system.

+ +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.kdfiles%20%28Set%20Driver%20Replacement%20Map%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-kdtargetmac--display-target-mac-address-.md b/windows-driver-docs-pr/debugger/-kdtargetmac--display-target-mac-address-.md new file mode 100644 index 0000000000..a8a6ad7594 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kdtargetmac--display-target-mac-address-.md @@ -0,0 +1,93 @@ +--- +title: .kdtargetmac (Display Target MAC Address) +description: Display Target MAC Address. +ms.assetid: 95042682-BD92-44B0-AAA8-AB8661393230 +keywords: [".kdtargetmac (Display Target MAC Address) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .kdtargetmac (Display Target MAC Address) +api_type: +- NA +--- + +# .kdtargetmac (Display Target MAC Address) + + +Display Target MAC Address + +``` +.kdtargetmac +``` + +## Parameters + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +Use the .kdtargetmac command to display the MAC (media access control) address of the target system. + +``` +0: kd> .kdtargetmac + +The target machine MAC address in open-device format is: XXXXXXXXXXXX +``` + +The .kdtargetmac is command is available if KDNET is enabled on the target system. Use the BCDEdit command with the /dbgsettings option to display the configuration on the target system. A debugtype of *NET* indicates that KDNET is configured. + +``` +C:\WINDOWS\system32>bcdedit /dbgsettings +key 1.2.3.4 +debugtype NET +hostip 192.168.1.10 +port 50000 +dhcp Yes +The operation completed successfully. +``` + +For more information, see [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md). + +Remarks +------- + +Knowing the MAC address of the target system can be useful for network tracing and other utilities. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.kdtargetmac%20%28Display%20Target%20MAC%20Address%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-kframes--set-stack-length-.md b/windows-driver-docs-pr/debugger/-kframes--set-stack-length-.md new file mode 100644 index 0000000000..ae959830f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kframes--set-stack-length-.md @@ -0,0 +1,82 @@ +--- +title: .kframes (Set Stack Length) +description: The .kframes command sets the default length of a stack trace display. +ms.assetid: 4f11a197-add1-4957-8345-dfbdb2037605 +keywords: ["Set Stack Length (.kframes) command", ".kframes (Set Stack Length) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .kframes (Set Stack Length) +api_type: +- NA +--- + +# .kframes (Set Stack Length) + + +The **.kframes** command sets the default length of a stack trace display. + +``` +.kframes FrameCountDefault +``` + +## Parameters + + + *FrameCountDefault* +Specifies the number of stack frames to display when a stack trace command is used. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +You can use the **.kframes** command to set the default length of a stack trace display. This length controls the number of frames that the [**k, kb, kp, kP, and kv**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands display and the number of DWORD\_PTRs that the **kd** command displays. + +You can override this default length by using the *FrameCount* or *WordCount* parameters for these commands. + +If you never issue the **.kframes** command, the default count is 20 (0x14). + +## See also + + +[**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.kframes%20%28Set%20Stack%20Length%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-kill--kill-process-.md b/windows-driver-docs-pr/debugger/-kill--kill-process-.md new file mode 100644 index 0000000000..33c7d59073 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kill--kill-process-.md @@ -0,0 +1,156 @@ +--- +title: .kill (Kill Process) +description: In user mode, the .kill command ends a process that is being debugged. +ms.assetid: e4bc13e4-2566-4438-9ae7-a5ba05b727de +keywords: [".kill (Kill Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .kill (Kill Process) +api_type: +- NA +--- + +# .kill (Kill Process) + + +In user mode, the **.kill** command ends a process that is being debugged. + +In kernel mode, the **.kill** command ends a process on the target computer. + +User-Mode Syntax + +``` +.kill [ /h | /n ] +``` + +Kernel-Mode Syntax + +``` +.kill Process +``` + +## Parameters + + + **/h** +(User mode only) Any outstanding debug event will be continued and marked as handled. This is the default. + + **/n** +(User mode only) Any outstanding debug event will be continued without being marked as handled. + + *Process* +Specifies the address of the process to be terminated. If *Process* is omitted or zero, the default process for the current system state will be terminated. + +### Environment + +In kernel mode, this command is supported on Microsoft Windows Server 2003 and later versions of Windows. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +In user mode, this command ends a process that is being debugged. If the debugger is attached to a child process, you can use **.kill** to end the child process without ending the parent process. For more information, see Examples. + +In kernel mode, this command schedules the selected process on the target computer for termination. The next time that the target can run (for example, by using a [**g (Go)**](g--go-.md) command), the specified process is ended. + +You cannot use this command during local kernel debugging. + +Examples +-------- + +**Using .childdbg** + +Suppose you attach a debugger to parent process (Parent.exe) before it creates a child process. You can enter the command [**.childdbg 1**](-childdbg--debug-child-processes-.md) to tell the debugger to attach to any child process that the parent creates. + +``` +1:001> .childdbg 1 +Processes created by the current process will be debugged +``` + +Now let the parent process run, and break in after it has created the child process. Use the [**| (Process Status)**](---process-status-.md) command to see the process numbers for the parent and child processes. + +``` +0:002> |* +. 0 id: 7f8 attach name: C:\Parent\x64\Debug\Parent.exe + 1 id: 2d4 child name: notepad.exe +``` + +In the preceding output, the number of the child process (notepad.exe) is 1. The dot (.) at the beginning of the first line tells us that the parent process is the current process. To make the child process the current process, enter **|1s**. + +``` +0:002> |1s +... +1:001> |* +# 0 id: 7f8 attach name: C:\Parent\x64\Debug\Parent.exe +. 1 id: 2d4 child name: notepad.exe +``` + +To kill the child process, enter the command **.kill**. The parent process continues to run. + +``` +1:001> .kill +Terminated. Exit thread and process events will occur. +1:001> g +``` + +**Using the -o parameter** + +When you start WinDbg or CDB, you can use the **-o** parameter to tell the debugger that it should attach to child processes. For example, the following command starts WinDbg, which starts and attaches to Parent.exe. When Parent.exe creates a child process, WinDbg attaches to the child process. + +**windbg -g -G -o Parent.exe** + +For more information, see [**WinDbg Command-Line Options**](windbg-command-line-options.md) and [**CDB Command-Line Options**](cdb-command-line-options.md). + +Requirements +------------ + + ++++ + + + + + + +

Version

Versions:(Kernel mode) Supported in Windows Server 2003 and later.

+ +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.kill%20%28Kill%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-allstreams.md b/windows-driver-docs-pr/debugger/-ks-allstreams.md new file mode 100644 index 0000000000..c711c0ece5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-allstreams.md @@ -0,0 +1,103 @@ +--- +title: ks.allstreams +description: The ks.allstreams extension walks the entire device tree and finds every kernel streaming device in the system. +ms.assetid: 3a9f4ad4-a3aa-46dc-887d-c83296bc8f84 +keywords: ["ks.allstreams Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.allstreams +api_type: +- NA +--- + +# !ks.allstreams + + +The **!ks.allstreams** extension walks the entire device tree and finds every kernel streaming device in the system. + +``` +!ks.allstreams [Flags] [Level] +``` + +## Parameters + + + *Flags* +Optional. Specifies the kind of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x1: + +Bit 0 (0x1) +Causes the display to include streams. + +Bit 2 (0x4) +Causes the display to include proxy instances. + +Bit 3 (0x8) +Causes the display to include queued IRPs. + +Bit 4 (0x10) +Causes the display to include an unformatted display of all streams. + +Bit 5 (0x20) +Causes the display to include an unformatted display of all stream formats. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +This command can take some time to execute (a minute is not unusual). + +Here is an example of the **!ks.allstreams** display: + +``` +kd> !allstreams +6 Kernel Streaming FDOs found: + Functional Device 82a17690 [\Driver\smwdm] + Functional Device 8296eb08 [\Driver\wdmaud] + Functional Device 82490388 [\Driver\sysaudio] + Functional Device 82970cb8 [\Driver\MSPQM] + Functional Device 824661b8 [\Driver\MSPCLOCK] + Functional Device 8241c020 [\Driver\avssamp] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.allstreams%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-automation.md b/windows-driver-docs-pr/debugger/-ks-automation.md new file mode 100644 index 0000000000..25ce04c567 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-automation.md @@ -0,0 +1,173 @@ +--- +title: ks.automation +description: The ks.automation extension displays any automation items associated with the given object. +ms.assetid: a8fd790f-2793-4e6e-a500-f61646be2c89 +keywords: ["ks.automation Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.automation +api_type: +- NA +--- + +# !ks.automation + + +The **!ks.automation** extension displays any automation items associated with the given object. + +``` +!ks.automation Object +``` + +## Parameters + + + *Object* +Specifies a pointer to the object for which to display automation items. (Automation items are properties, methods, and events.) *Object* must be one of the following types: PKSPIN, PKSFILTER, CKsPin\*, CKsFilter\*, PIRP. If *Object* is a pointer to an automation IRP, the command returns property information and handlers. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +You can use this command with a filter address obtained from [**!ks.enumdevobj**](-ks-enumdevobj.md). + +Here is an example of the **!ks.automation** display. The argument is the address of a filter: + +``` +kd> !automation 829493c4 +Filter 829493c4 has the following automation items: + Property Items: + Set KSPROPSETID_Pin + Item ID = KSPROPERTY_PIN_CINSTANCES + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000008 + Item ID = KSPROPERTY_PIN_CTYPES + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000018 + MinData = 00000004 + Item ID = KSPROPERTY_PIN_DATAFLOW + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000004 + Item ID = KSPROPERTY_PIN_DATARANGES + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000000 + Item ID = KSPROPERTY_PIN_DATAINTERSECTION + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000028 + MinData = 00000000 + Item ID = KSPROPERTY_PIN_INTERFACES + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000000 + Item ID = KSPROPERTY_PIN_MEDIUMS + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000000 + Item ID = KSPROPERTY_PIN_COMMUNICATION + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000004 + Item ID = KSPROPERTY_PIN_NECESSARYINSTANCES + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000004 + Item ID = KSPROPERTY_PIN_CATEGORY + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000010 + Item ID = KSPROPERTY_PIN_NAME + Get Handler = ks!CKsFilter::Property_Pin + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000000 + Set KSPROPSETID_Topology + Item ID = KSPROPERTY_TOPOLOGY_CATEGORIES + Get Handler = ks!CKsFilter::Property_Topology + Set Handler = NULL + MinProperty = 00000018 + MinData = 00000000 + Item ID = KSPROPERTY_TOPOLOGY_NODES + Get Handler = ks!CKsFilter::Property_Topology + Set Handler = NULL + MinProperty = 00000018 + MinData = 00000000 + Item ID = KSPROPERTY_TOPOLOGY_CONNECTIONS + Get Handler = ks!CKsFilter::Property_Topology + Set Handler = NULL + MinProperty = 00000018 + MinData = 00000000 + Item ID = KSPROPERTY_TOPOLOGY_NAME + Get Handler = ks!CKsFilter::Property_Topology + Set Handler = NULL + MinProperty = 00000020 + MinData = 00000000 + Set KSPROPSETID_General + Item ID = KSPROPERTY_GENERAL_COMPONENTID + Get Handler = ks!CKsFilter::Property_General_ComponentId + Set Handler = NULL + MinProperty = 00000018 + MinData = 00000048 + Set [ks!KSPROPSETID_Frame] a60d8368-5324-4893-b020-c431a50bcbe3 + Item ID = 0 + Get Handler = ks!CKsFilter::Property_Frame_Holding + Set Handler = ks!CKsFilter::Property_Frame_Holding + MinProperty = 00000018 + MinData = 00000004 + Method Items: + NO SETS FOUND! + Event Items: + NO SETS FOUND! +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.automation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-devhdr.md b/windows-driver-docs-pr/debugger/-ks-devhdr.md new file mode 100644 index 0000000000..05e2026bf7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-devhdr.md @@ -0,0 +1,84 @@ +--- +title: ks.devhdr +description: The ks.devhdr extension displays the kernel streaming device header associated with the given WDM object. +ms.assetid: 1418ccfe-3842-422c-b2ce-124d0019d7b8 +keywords: ["ks.devhdr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.devhdr +api_type: +- NA +--- + +# !ks.devhdr + + +The **!ks.devhdr** extension displays the kernel streaming device header associated with the given WDM object. + +``` +!ks.devhdr DeviceObject +``` + +## Parameters + + + *DeviceObject* +This parameter specifies a pointer to a WDM device object. If *DeviceObject* is not valid, the command returns an error. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The output from [**!ks.allstreams**](-ks-allstreams.md) can be used as the input for **!ks.devhdr**. + +Here is an example of the **!ks.devhdr** display: + +``` +kd> !devhdr 827aedf0 7 +Device Header 824ca1e0 + Child Create Handler List: + Create Item eb3a7284 + CreateFunction = sysaudio!CFilterInstance::FilterDispatchCreate+0x00 + ObjectClass = NULL + Flags = 0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.devhdr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dhdr.md b/windows-driver-docs-pr/debugger/-ks-dhdr.md new file mode 100644 index 0000000000..f9c7aba9a3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dhdr.md @@ -0,0 +1,20 @@ +--- +title: ks.dhdr +description: ks.dhdr +ms.assetid: 891eff1f-8d1b-48fb-bfe4-8ff461c186cf +--- + +# !ks.dhdr + + +The **!ks.dhdr** extension command is obsolete; use [**!ks.dump**](-ks-dump.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dhdr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dump.md b/windows-driver-docs-pr/debugger/-ks-dump.md new file mode 100644 index 0000000000..7ada8de53d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dump.md @@ -0,0 +1,209 @@ +--- +title: ks.dump +description: The ks.dump extension displays the specified object. +ms.assetid: 7878c79f-9de6-4fd2-9641-c636212429eb +keywords: ["ks.dump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.dump +api_type: +- NA +--- + +# !ks.dump + + +The **!ks.dump** extension displays the specified object. + +``` +!ks.dump Object [Level] [Flags] +``` + +## Parameters + + + *Object* +Specifies a pointer to an AVStream structure, an AVStream class object, or a PortCls object. Can also specify a pointer to an an IRP or a file object. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. You can see more information about levels by issuing a **!ks.dump** command with no arguments. + + *Flags* +Optional. Specifies the kind of information to be displayed. *Flags* can be any combination of the following bits. + +Bit 0 (0x1) +Display all queued IRPs. + +Bit 1 (0x2) +Display all pending IRPs. + +Bit 2 (0x4) +Analyze a stalled graph for suspects. + +Bit 3 (0x8) +Show all pin states. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The **!ks.dump** command recognizes most AVStream objects, including pins, filters, factories, devices, pipes, and stream pointers. This command also recognizes some stream class structures, including stream objects, filter instances, device extensions, and SRBs. + +Following is an example of the **!ks.dump** display for a filter: + +``` +kd> !dump 829493c4 +Filter object 829493c4 [CKsFilter = 82949350] + Descriptor f7a233c8: + Context 829dce28 +``` + +Following is an example of the **!ks.dump** display for a pin: + +``` +kd> !dump 8160DDE0 7 +Pin object 8160DDE0 [CKsPin = 8160DD50] + DeviceState KSSTATE_RUN + ClientState KSSTATE_RUN + ResetState KSRESET_END + CKsPin object 8160DD50 [KSPIN = 8160DDE0] + State KSSTATE_RUN + Processing Mutex 8160DFD0 is not held + And Gate & 8160DF88 + And Gate Count 1 +``` + +Some important parts of this display are included in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Meaning

DeviceState

The state that the pin was requested to enter. If different from ClientState, this is the state that the minidriver will transition to next.

ClientState

The state that the minidriver is actually in. This reflects the state of the pipe.

ResetState

Indicates whether or not the object is in the middle of a flush.

+

KSRESET_BEGIN indicates a flush.

+

KSRESET_END indicates no flush.

State

The internal state of the pin's transport to non-AVStream filters.

+ +  + +Following is an example of the **!ks.dump** display for a stream class driver: + +``` +kd> !dump 81a0a170 7 +Device Extension 81a0a228: + Device Object 81a0a170 [\Driver\TESTCAP] + Next Device Object 81bd56d8 [\Driver\PnpManager] + Physical Device Object 81bd56d8 [\Driver\PnpManager] + REGISTRY FLAGS: + Page out driver when closed + No suspend if running + MINIDRIVER Data: + Device Extension 81a0a44c + Interrupt Routine 00000000 + Synchronize Routine STREAM!StreamClassSynchronizeExecution + Receive Device SRB testcap!AdapterReceivePacket + Cancel Packet testcap!AdapterCancelPacket + Timeout Packet testcap!AdapterTimeoutPacket + Size (d / r / s / f) 1a0(416), 14(20), 978(2424), 0(0) + Sync Mode Driver Synchronizes + Filter Type 0: + Symbolic Links: + Information Paged Out + Instances: + 816b7bd8 +``` + +Note that the sizes are listed both in hexadecimal numbers, and then, parenthetically in the decimal equivalent. The Size abbreviations in this display are listed in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Size

Explanation

d

Device

r

Request

s

Stream

f

Filter. If the filter size is 0, the filter is single instance. If it is greater than 0, it is multi-instance.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dumpbag.md b/windows-driver-docs-pr/debugger/-ks-dumpbag.md new file mode 100644 index 0000000000..a5f692e3c2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dumpbag.md @@ -0,0 +1,84 @@ +--- +title: ks.dumpbag +description: The ks.dumpbag extension displays the contents of the object bag for the specified object. +ms.assetid: a97b4794-b5dc-45a8-b1e9-5a626959020e +keywords: ["ks.dumpbag Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.dumpbag +api_type: +- NA +--- + +# !ks.dumpbag + + +The **!ks.dumpbag** extension displays the contents of the object bag for the specified object. + +``` +!ks.dumpbag Object [Level] +``` + +## Parameters + + + *Object* +Specifies a pointer to a valid client viewable object structure, or to the private class object. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Here is an example of the **!ks.dumpbag** display for a filter: + +``` +kd> !dumpbag 829493c4 +Filter 829493c4 [CKsFilter = 82949350]: + Object Bag 829493d0: + Object Bag Item 829dce28: + Reference Count : 1 + Item Cleanup Handler : f7a21730 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dumpbag%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dumpcircuit.md b/windows-driver-docs-pr/debugger/-ks-dumpcircuit.md new file mode 100644 index 0000000000..e479c9536e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dumpcircuit.md @@ -0,0 +1,87 @@ +--- +title: ks.dumpcircuit +description: The ks.dumpcircuit extension lists details of the transport circuit associated with the given object. +ms.assetid: 34e6fa0f-7479-4616-ba7e-f2b12ccc836d +keywords: ["ks.dumpcircuit Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.dumpcircuit +api_type: +- NA +--- + +# !ks.dumpcircuit + + +The **!ks.dumpcircuit** extension lists details of the transport circuit associated with the given object. + +``` +!ks.dumpcircuitextension Object [Level] +``` + +## Parameters + + + *Object* +Specifies a pointer to the object for which to display the transport circuit. For AVStream, *Object* must be one of the following types: CKsPin\*, CKsQueue\*, CKsRequestor\*, CKsSplitter\*, CKsSplitterBranch\*. + +For PortCls, object must be one of the following types: CPortPin\*, CKsShellRequestor\*, or CIrpStream\*. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Note that **!ks.dumpcircuit** starts walking the circuit at the specified object, which does not always correspond to the data source. + +You can first use [**!ks.graph**](-ks-graph.md) with a filter address to list pin addresses, and then use these addresses with **!ks.dumpcircuit**. + +Here is an example of the **!ks.dumpcircuit** display: + +``` +kd> !dumpcircuit 8293f4f0 +Pin8293f4f0 0 (snk, out) +Queue82990e20 r/w/c=2489/2/0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dumpcircuit%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dumplog.md b/windows-driver-docs-pr/debugger/-ks-dumplog.md new file mode 100644 index 0000000000..a0ad695a08 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dumplog.md @@ -0,0 +1,74 @@ +--- +title: ks.dumplog +description: The ks.dumplog extension displays the internal kernel streaming debug log. +ms.assetid: 09829517-c01c-4cbd-bd0f-2ad0c1554f39 +keywords: ["ks.dumplog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.dumplog +api_type: +- NA +--- + +# !ks.dumplog + + +The **!ks.dumplog** extension displays the internal kernel streaming debug log. + +``` +!ks.dumplog [Entries] +``` + +## Parameters + + + *Entries* +Optional. Specifies the number of log entries to display. If *Entries* is zero or omitted, the entire log is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +You can stop the log display by pressing [**CTRL+C**](ctrl-c--break-.md). + +This extension requires that the target computer be running a checked (debug) version of Ks.sys. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dumplog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-dumpqueue.md b/windows-driver-docs-pr/debugger/-ks-dumpqueue.md new file mode 100644 index 0000000000..ba0c9db34a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-dumpqueue.md @@ -0,0 +1,101 @@ +--- +title: ks.dumpqueue +description: The ks.dumpqueue extension displays information about the queues associated with a given AVStream object, or the stream associated with a port class object. +ms.assetid: d641b4e6-73d9-4c44-b2c6-0b6c688da368 +keywords: ["ks.dumpqueue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.dumpqueue +api_type: +- NA +--- + +# !ks.dumpqueue + + +The **!ks.dumpqueue** extension displays information about the queues associated with a given AVStream object, or the stream associated with a port class object. + +``` +!ks.dumpqueue Object [Level] +``` + +## Parameters + + + *Object* +Specifies a pointer to the object for which to display the queue. *Object* must be of type PKSPIN, PKSFILTER, CKsPin\*, CKsFilter\*, CKsQueue\*, CPortPin\*, or CPortFilter\*. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +*Object* must be a filter or a pin. For a pin, a single queue is displayed. For a filter, multiple queues are displayed. + +This command can take some time to execute. + +Here is an example of the **!ks.dumpqueue** display: + +``` +kd> !dumpqueue 829493c4 +Filter 829493c4: Output Queue 82990e20: + Queue 82990e20: + Frames Received : 1889 + Frames Waiting : 3 + Frames Cancelled : 0 + And Gate 82949464 : count = 1, next = 00000000 + Frame Gate NULL + Frame Header 82aaef78: + NextFrameHeaderInIrp = 00000000 + OriginalIrp = 82169e48 + Mdl = 8292e358 + Irp = 82169e48 + StreamHeader = 8298dea0 + FrameBuffer = edba3000 + StreamHeaderSize = 00000000 + FrameBufferSize = 00025800 + Context = 00000000 + Refcount = 1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.dumpqueue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-enumdevobj.md b/windows-driver-docs-pr/debugger/-ks-enumdevobj.md new file mode 100644 index 0000000000..ddffac003e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-enumdevobj.md @@ -0,0 +1,82 @@ +--- +title: ks.enumdevobj +description: The ks.enumdevobj extension displays the KSDEVICE associated with a given WDM device object, and lists the filter types and filters currently instantiated on this device. +ms.assetid: 3730fe3e-df7a-47fd-825b-ef31be6f7620 +keywords: ["ks.enumdevobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.enumdevobj +api_type: +- NA +--- + +# !ks.enumdevobj + + +The **!ks.enumdevobj** extension displays the KSDEVICE associated with a given WDM device object, and lists the filter types and filters currently instantiated on this device. + +``` +!ks.enumdevobj DeviceObject +``` + +## Parameters + + + *DeviceObject* +Specifies a pointer to a WDM device object. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The output from [**!ks.allstreams**](-ks-allstreams.md) can be used as the input for **!ks.enumdevobj**. + +Here is an example of the **!ks.enumdevobj** display: + +``` +kd> !enumdevobj 8241c020 +WDM device object 8241c020: + Corresponding KSDEVICE 823b8430 + Factory 829782dc [Descriptor f7a233c8] instances: + 829493c4 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.enumdevobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-enumdrvobj.md b/windows-driver-docs-pr/debugger/-ks-enumdrvobj.md new file mode 100644 index 0000000000..efe2b7d02c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-enumdrvobj.md @@ -0,0 +1,72 @@ +--- +title: ks.enumdrvobj +description: The ks.enumdrvobj extension displays all KSDEVICE structures associated with a given WDM driver object, and lists the filter types and filters currently instantiated on these devices. +ms.assetid: 8fcb8c83-48b6-402a-8374-6b1f0314837e +keywords: ["ks.enumdrvobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.enumdrvobj +api_type: +- NA +--- + +# !ks.enumdrvobj + + +The **!ks.enumdrvobj** extension displays all KSDEVICE structures associated with a given WDM driver object, and lists the filter types and filters currently instantiated on these devices. + +``` +!ks.enumdrvobj DriverObject +``` + +## Parameters + + + *DriverObject* +Specifies a pointer to a WDM driver object. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Since **!ks.enumdrvobj** enumerates every device chained off a WDM driver object, it is equivalent to invoking [**!ks.enumdevobj**](-ks-enumdevobj.md) on every device chained off a given driver. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.enumdrvobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-eval.md b/windows-driver-docs-pr/debugger/-ks-eval.md new file mode 100644 index 0000000000..96f87db944 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-eval.md @@ -0,0 +1,98 @@ +--- +title: ks.eval +description: The ks.eval extension evaluates an expression using an extension-specific expression evaluator. +ms.assetid: 68c9cfb0-ff87-47ea-bd0d-5f45c1de0639 +keywords: ["ks.eval Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.eval +api_type: +- NA +--- + +# !ks.eval + + +The **!ks.eval** extension evaluates an expression using an extension-specific expression evaluator. + +``` +!ks.eval Expression +``` + +## Parameters + + + *Expression* +Specifies the expression to evaluate. *Expression* can include any MASM operators, symbols, or numerical syntax, as well as the extension-specific operators described below. For more information about MASM expressions, see [MASM Numbers and Operators](masm-numbers-and-operators.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The extension module includes two extension-specific operators which can be used in address parameters to extension commands: + + **fdo(** *x* **)** +Returns the functional device object associated with the object at address **x**. + + **driver(** *x* **)** +Returns the driver object associated with **fdo(***x***)**. + +You can use the **!ks.eval** command to parse expressions that contain these extension-specific operators as well as [MASM Numbers and Operators](masm-numbers-and-operators.md). + +Note that all operators supported by **!ks.eval** are also supported by all other extension commands in the Ks.dll extension module. + +Here is an example of the **!ks.eval** extension being used with the address of a filter. Note the presence of the 0x8241C020 address in the [**!ks.allstreams**](-ks-allstreams.md) output: + +``` +kd> !eval fdo(829493c4) +Resulting Evaluation: 8241c020 + +kd> !allstreams +6 Kernel Streaming FDOs found: + Functional Device 82a17690 [\Driver\smwdm] + Functional Device 8296eb08 [\Driver\wdmaud] + Functional Device 82490388 [\Driver\sysaudio] + Functional Device 82970cb8 [\Driver\MSPQM] + Functional Device 824661b8 [\Driver\MSPCLOCK] + Functional Device 8241c020 [\Driver\avssamp] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.eval%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-findlive.md b/windows-driver-docs-pr/debugger/-ks-findlive.md new file mode 100644 index 0000000000..aec4fef814 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-findlive.md @@ -0,0 +1,80 @@ +--- +title: ks.findlive +description: The ks.findlive extension searches the internal Ks.sys debug log to attempt to find live objects of a specified type. +ms.assetid: 71372144-3f39-460b-859c-ac4cba0c766d +keywords: ["ks.findlive Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.findlive +api_type: +- NA +--- + +# !ks.findlive + + +The **!ks.findlive** extension searches the internal Ks.sys debug log to attempt to find live objects of a specified type. + +``` +!ks.findlive Type [Entries] [Level] +``` + +## Parameters + + + *Type* +Specifies the type of object for which to search. Enter one of the following as a literal value: **Queue**, **Requestor**, **Pin**, **Filter**, or **Irp**. + +Entries +If this parameter is zero or omitted, the entire log is searched. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The **!ks.findlive** command may not find all possible specified live objects. + +This extension requires that the target computer be running a checked (debug) version of Ks.sys. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.findlive%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-forcedump.md b/windows-driver-docs-pr/debugger/-ks-forcedump.md new file mode 100644 index 0000000000..22ebe06085 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-forcedump.md @@ -0,0 +1,133 @@ +--- +title: ks.forcedump +description: The ks.forcedump command displays information about memory contents at a caller-supplied address. +ms.assetid: 2829d324-a346-47af-a5f8-1808f329cadf +keywords: ["ks.forcedump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.forcedump +api_type: +- NA +--- + +# !ks.forcedump + + +The **!ks.forcedump** command displays information about memory contents at a caller-supplied address. + +``` +!ks.forcedump Object Type [Level] +``` + +## Parameters + + + *Object* +Specifies a pointer to the object for which to display information. + + *Type* +Specifies the type of object. + +For AVStream/KS objects, *Type* must be one of the following values: CKsQueue, CKsDevice, CKsFilterFactory, CKsFilter, CKsPin, CKsRequestor, CKsSplitter, CKsSplitterBranch, CKsPipeSection, KSPIN, KSFILTER, KSFILTERFACTORY, KSDEVICE, KSSTREAM\_POINTER, KSPFRAME\_HEADER, KSIOBJECT\_HEADER, KSPDO\_EXTENSION, KSIDEVICE\_HEADER, KSSTREAM\_HEADER, KSPIN\_DESCRIPTOR\_EX, CKsProxy, CKsInputPin, CKsOutputPin, CasyncItemHandler. + +For Port Class objects, *Type* must be one of the following values: DEVICE\_CONTEXT, CPortWaveCyclic, CPortPinWaveCyclic, CPortTopology, CPortDMus, CIrpStream, CKsShellRequestor, CPortFilterWaveCyclic, CDmaChannel, CPortWavePci, CportPinWavePci. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Normally, you can use [**!ks.dump**](-ks-dump.md) to display data structures. + +However, if symbols are loaded incorrectly or too much information is paged out, the type identification logic in the [**!ks.dump**](-ks-dump.md) command may fail to identify the type of structure at a given address. + +If this happens, try using the **!ks.forcedump** command. This command works just like [**!ks.dump**](-ks-dump.md) except that the user specifies the type of the object. + +**Note**   The **!ks.forcedump** command does not verify that *Type* is the correct type of structure found at the address provided in *Object*. The command assumes that this is the type of structure found at *Object* and displays data accordingly. + +  + +A listing of all supported objects can be retrieved by issuing a **!ks.forcedump** command with no arguments. + +Here are two examples of the output from **!ks.forcedump**, using the address of a filter for the *Object* argument but with different levels of detail: + +``` +kd> !forcedump 829493c4 KSFILTER +WARNING: I am dumping 829493c4 as a KSFILTER. + No checking has been performed to ensure that it is this type!!! + +Filter object 829493c4 [CKsFilter = 82949350] + Descriptor f7a233c8: + Context 829dce28 + +kd> !forcedump 829493c4 KSFILTER 7 +WARNING: I am dumping 829493c4 as a KSFILTER. + No checking has been performed to ensure that it is this type!!! + +Filter object 829493c4 [CKsFilter = 82949350] + Descriptor f7a233c8: + Filter Category GUIDs: + Video + Capture + Context 829dce28 + INTERNAL INFORMATION: + Public Parent Factory 829782dc + Aggregated Unknown 00000000 + Device Interface 823b83c8 + Control Mutex 829493f8 is not held + Object Event List: + None + CKsFilter object 82949350 [KSFILTER = 829493c4] + Processing Mutex 82949484 is not held + Gate & 82949464 + Gate.Count 1 + Pin Factories: + Pin ID 0 [Video/General Capture Out]: + Child Count 1 + Bound Child Count 1 + Necessary Count 0 + Specific Instances: + 8293f580 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.forcedump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-graph.md b/windows-driver-docs-pr/debugger/-ks-graph.md new file mode 100644 index 0000000000..19cbd411b1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-graph.md @@ -0,0 +1,102 @@ +--- +title: ks.graph +description: The ks.graph extension command displays a textual description of the kernel mode graph in topologically sorted order. +ms.assetid: b9725499-9db3-422f-850b-97db4865b74d +keywords: ["ks.graph Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.graph +api_type: +- NA +--- + +# !ks.graph + + +The **!ks.graph** extension command displays a textual description of the kernel mode graph in topologically sorted order. + +``` +!ks.graph Object [Level] [Flags] +``` + +## Parameters + + + *Object* +Specifies a pointer to the object to use as a starting point for the graph. Must be a pointer to one of the following: file object, IRP, pin, or filter. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. The levels for **!ks.graph** are the same as those for [**!ks.dump**](-ks-dump.md). + + *Flags* +Optional. Specifies the kind of information to be displayed. *Flags* can be any combination of the following bits. + +Bit 0 (0x1) +Display a list of IRPs queued to each pin instance in the graph. + +Bit 1 (0x2) +Display a list of IRPs that are pending from each pin instance in the graph. Only IRPs that the pin knows it is waiting for are displayed. + +Bit 4 (0x10) +Analyze a stalled graph for suspect filters. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +This command may take a bit of time to process. + +Issue a **!ks.graph** command with no arguments for help. + +Here is an example of the **!ks.graph** display, with the address of a filter object: + +``` +kd> !graph 829493c4 +Attempting a graph build on 829493c4... Please be patient... + +Graph With Starting Point 829493c4: + +"avssamp" Filter 82949350, Child Factories 1 + Output Factory 0 [Video/General Capture]: + Pin 8293f4f0 (File 82503498) Irps(q/p) = 2, 0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.graph%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-help.md b/windows-driver-docs-pr/debugger/-ks-help.md new file mode 100644 index 0000000000..8ab9a7f802 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-help.md @@ -0,0 +1,61 @@ +--- +title: ks.help +description: The ks.help extension displays a help text showing all AVStream-specific Ks.dll extension commands. +ms.assetid: c9e6e3fb-1dd8-4de6-8996-2482457f3979 +keywords: ["ks.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.help +api_type: +- NA +--- + +# !ks.help + + +The **!ks.help** extension displays a help text showing all AVStream-specific Ks.dll extension commands. + +``` +!ks.help +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-kshelp.md b/windows-driver-docs-pr/debugger/-ks-kshelp.md new file mode 100644 index 0000000000..54ce16d374 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-kshelp.md @@ -0,0 +1,61 @@ +--- +title: ks.kshelp +description: The ks.kshelp extension displays a help text showing original KS 1.0-specific Ks.dll extension commands. +ms.assetid: 672446ad-74a0-4caa-9801-eafef80929cb +keywords: ["ks.kshelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.kshelp +api_type: +- NA +--- + +# !ks.kshelp + + +The **!ks.kshelp** extension displays a help text showing original KS 1.0-specific Ks.dll extension commands. + +``` +!ks.kshelp +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.kshelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-libexts.md b/windows-driver-docs-pr/debugger/-ks-libexts.md new file mode 100644 index 0000000000..dabde105df --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-libexts.md @@ -0,0 +1,92 @@ +--- +title: ks.libexts +description: The ks.libexts extension provides access to Microsoft-supplied library extensions that are statically linked to the extension module. +ms.assetid: 03328041-9922-4367-b6e9-d822a9c03f32 +keywords: ["ks.libexts Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.libexts +api_type: +- NA +--- + +# !ks.libexts + + +The **!ks.libexts** extension provides access to Microsoft-supplied library extensions that are statically linked to the extension module. + +``` +!ks.libexts [Command] [Libext] +``` + +## Parameters + + +*Command* +Optional. Specifies one of the following values. If this argument is omitted, **!ks.libexts** returns help information. + +**disableall** +Disable all library extensions. When this is used, omit the *Libext* parameter. + + **disable** +Disable a specific library extension by name. When this is used, specify the name in the *Libext* parameter. + + **enableall** +Enable all library extensions. Only loaded components with correct symbols are enabled. When this is used, omit the *Libext* parameter. + +**enable** +Enable a specific library extension by name. When this is used, specify the name in the *Libext* parameter. Only loaded components with correct symbols can be enabled. + + **details** +Show details about all currently linked library extensions. When this is used, omit the *Libext* parameter. + + *Libext* +Specifies the name of a library extension. Required only for *Command* values of **enable** or **disable**. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The extension module contains an extensibility framework that allows separate components to be built and linked into Ks.dll. These extra components are called library extensions. + +The **!ks.libexts** command allows viewing of statistics about those library extensions as well as control over them. For details, issue **!ks.libexts** with no arguments. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.libexts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-objhdr.md b/windows-driver-docs-pr/debugger/-ks-objhdr.md new file mode 100644 index 0000000000..f0fd25c7e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-objhdr.md @@ -0,0 +1,143 @@ +--- +title: ks.objhdr +description: The ks.objhdr extension displays the kernel streaming object header associated with the specified file object. +ms.assetid: 105b1c03-fc89-4c0f-91d0-42e88f07c71c +keywords: ["ks.objhdr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.objhdr +api_type: +- NA +--- + +# !ks.objhdr + + +The **!ks.objhdr** extension displays the kernel streaming object header associated with the specified file object. + +``` +!ks.objhdr FileObject [Level] [Flags] +``` + +## Parameters + + + *FileObject* +This parameter specifies a pointer to a WDM file object. If *FileObject* is not valid, the command returns an error. + + *Level* +Optional. Values are the same as those for [**!ks.dump**](-ks-dump.md). + + *Flags* +Optional. Values are the same as those for [**!ks.dump**](-ks-dump.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Levels and flags for **!ks.objhdr** are identical to those described in [**!ks.dump**](-ks-dump.md). + +The output from [**!ks.allstreams**](-ks-allstreams.md) and [**!ks.enumdevobj**](-ks-enumdevobj.md) can be used as the input for **!ks.objhdr**. To do this with the *avssamp* sample, for instance, issue the following commands: + +``` +kd> !ks.allstreams +6 Kernel Streaming FDOs found: + Functional Device 8299be18 [\Driver\smwdm] + Functional Device 827c86d8 [\Driver\wdmaud] + Functional Device 827c0f08 [\Driver\sysaudio] + Functional Device 82424590 [\Driver\avssamp] + Functional Device 82423720 [\Driver\MSPQM] + Functional Device 82b91a88 [\Driver\MSPCLOCK] +kd> !ks.enumdevobj 82424590 +WDM device object 82424590: + Corresponding KSDEVICE 82427540 + Factory 8285baa4 [Descriptor f7a333c8] instances: + 82837a34 +kd> !ks.objhdr 82837a34 7 +``` + +The results of this command might be lengthy. Issue a Ctrl-BREAK (WinDbg) or Ctrl-C (NTSD, CDB, KD) to stop the output. + +Here's a separate example: + +``` +kd> !ks.objhdr 81D828B8 7 +Adjusting file object 81D828B8 to object header 81BC1008 + +Object Header 81BC1008 + Associated Create Items: + Create Item F9F77E98 + CreateFunction = ks!CKsFilter::DispatchCreatePin+0x00 + ObjectClass = {146F1A80-4791-11D0-A5D6-28DB04C10000} + Flags = 0 + Child Create Handler List: + Create Item F9F85AA0 + CreateFunction = ks!CKsPin::DispatchCreateAllocator+0x00 + ObjectClass = {642F5D00-4791-11D0-A5D6-28DB04C10000} + Flags = 0 + Create Item F9F85AB8 + CreateFunction = ks!CKsPin::DispatchCreateClock+0x00 + ObjectClass = {53172480-4791-11D0-A5D6-28DB04C10000} + Flags = 0 + Create Item F9F85AD0 + CreateFunction = ks!CKsPin::DispatchCreateNode+0x00 + ObjectClass = {0621061A-EE75-11D0-B915-00A0C9223196} + Flags = 0 + DispatchTable: + Dispatch Table F9F85AE8 + DeviceIoControl = ks!CKsPin::DispatchDeviceIoControl+0x00 + Read = ks!KsDispatchInvalidDeviceRequest+0x00 + Write = ks!KsDispatchInvalidDeviceRequest+0x00 + Flush = ks!KsDispatchInvalidDeviceRequest+0x00 + Close = ks!CKsPin::DispatchClose+0x00 + QuerySecurity = ks!KsDispatchQuerySecurity+0x00 + SetSecurity = ks!KsDispatchSetSecurity+0x00 + FastDeviceIoControl = ks!KsDispatchFastIoDeviceControlFailure+0x00 + FastRead = ks!KsDispatchFastReadFailure+0x00 + FastWrite = ks!KsDispatchFastReadFailure+0x00 + TargetState: KSTARGET_STATE_ENABLED + TargetDevice: 00000000 + BaseDevice : 81BBDF10 + Stack Depth : 1 + Corresponding AVStream object = 81A971B0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.objhdr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-ohdr.md b/windows-driver-docs-pr/debugger/-ks-ohdr.md new file mode 100644 index 0000000000..3f45aa4bf1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-ohdr.md @@ -0,0 +1,82 @@ +--- +title: ks.ohdr +description: The ks.ohdr extension displays details of a kernel streaming object header. +ms.assetid: 0080565a-537d-44f4-9329-9ebe7fc926a1 +keywords: ["ks.ohdr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.ohdr +api_type: +- NA +--- + +# !ks.ohdr + + +The **!ks.ohdr** extension displays details of a kernel streaming object header. + +``` +!ks.ohdr Object [Level] [Flags] +``` + +## Parameters + + + *Object* +This parameter specifies a pointer to a KS object header. If *Object* is not valid, the command returns an error. + + *Level* +Optional. Values are the same as those for [**!ks.dump**](-ks-dump.md). + + *Flags* +Optional. Values are the same as those for [**!ks.dump**](-ks-dump.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +The **!ks.ohdr** command works similarly to [**!ks.objhdr**](-ks-objhdr.md) in that it displays details of a KS object header. The difference is that the caller provides the direct address of the KS object header, instead of the address of the associated file object. + +Levels and flags for **!ks.ohdr** are identical to those described in [**!ks.dump**](-ks-dump.md). + +If the data you are querying is not paged out, consider using [**!ks.dump**](-ks-dump.md) instead of **!ks.ohdr**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.ohdr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-pchelp.md b/windows-driver-docs-pr/debugger/-ks-pchelp.md new file mode 100644 index 0000000000..3da3a13a4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-pchelp.md @@ -0,0 +1,61 @@ +--- +title: ks.pchelp +description: The ks.pchelp extension displays a help text showing PortCls-specific Ks.dll extension commands. +ms.assetid: 6724deae-fceb-415b-991c-370347d5ff15 +keywords: ["ks.pchelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.pchelp +api_type: +- NA +--- + +# !ks.pchelp + + +The **!ks.pchelp** extension displays a help text showing PortCls-specific Ks.dll extension commands. + +``` +!ks.pchelp +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.pchelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-pciaudio.md b/windows-driver-docs-pr/debugger/-ks-pciaudio.md new file mode 100644 index 0000000000..6b287c1aa8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-pciaudio.md @@ -0,0 +1,90 @@ +--- +title: ks.pciaudio +description: The ks.pciaudio extension displays a list of FDOs currently attached to PortCls. +ms.assetid: 30d74f14-1cff-4b18-996a-8c91c20edebe +keywords: ["ks.pciaudio Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.pciaudio +api_type: +- NA +--- + +# !ks.pciaudio + + +The **!ks.pciaudio** extension displays a list of FDOs currently attached to PortCls. + +``` +!ks.pciaudio [Options] [Level] +``` + +## Parameters + + + *Options* +Optional. Specifies the kind of information to be displayed. *Options* can be any combination of the following bits. + +Bit 0 (0x1) +Display a list of running streams. + +Bit 1 (0x2) +Display a list all streams. + +Bit 3 (0x4) +Output displayed streams. *Level* has meaning only when this bit is set. + + *Level* +Optional, and applicable only if Bit 3 is set in *Options*. Levels are the same as those for [**!ks.dump**](-ks-dump.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +Here is an example of the output from **!ks.pciaudio**: + +``` +kd> !ks.pciaudio +1 Audio FDOs found: + Functional Device 8299be18 [\Driver\smwdm] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.pciaudio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-pciks.md b/windows-driver-docs-pr/debugger/-ks-pciks.md new file mode 100644 index 0000000000..298d2cb71b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-pciks.md @@ -0,0 +1,101 @@ +--- +title: ks.pciks +description: The ks.pciks extension lists functional devices for kernel streaming devices that are attached to the PCI bus. Optionally, it can display information about active streams on those functional devices. +ms.assetid: 525eb1eb-4b96-46da-90ae-d3c5f8d7511a +keywords: ["ks.pciks Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.pciks +api_type: +- NA +--- + +# !ks.pciks + + +The **!ks.pciks** extension lists functional devices for kernel streaming devices that are attached to the PCI bus. Optionally, it can display information about active streams on those functional devices. + +``` +!ks.pciks [Flags] [Level] +``` + +## Parameters + + + *Flags* +Optional. Specifies the kind of information to be displayed. *Flags* can be any combination of the following bits. + +Bit 0 (0x1) +List all currently running streams. + +Bit 1 (0x2) +Recurse graphs to find non-PCI devices. + +Bit 2 (0x4) +Display a list of proxy instances. + +Bit 3 (0x8) +Display currently queued Irps. + +Bit 4 (0x10) +Display information about all streams. + +Bit 5 (0x20) +Display active stream formats. + + *Level* +Optional, and applicable only to flag combinations that cause data to be displayed. Levels are the same as those for [**!ks.dump**](-ks-dump.md). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +This command may take time to execute, especially if the ACPI filter driver is loaded, or if Driver Verifier is enabled and driver names are paged out. + +Here is an example of the **!ks.pciks** display: + +``` +kd> !pciks +1 Kernel Streaming FDOs found: + Functional Device 82a17690 [\Driver\smwdm] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.pciks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-shdr.md b/windows-driver-docs-pr/debugger/-ks-shdr.md new file mode 100644 index 0000000000..76d357e320 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-shdr.md @@ -0,0 +1,20 @@ +--- +title: ks.shdr +description: ks.shdr +ms.assetid: 033d8ca2-b777-40e6-9aab-f06554c1a61c +--- + +# !ks.shdr + + +The **!ks.shdr** extension command is obsolete; use [**!ks.dump**](-ks-dump.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.shdr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ks-topology.md b/windows-driver-docs-pr/debugger/-ks-topology.md new file mode 100644 index 0000000000..1a0cf2e491 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ks-topology.md @@ -0,0 +1,80 @@ +--- +title: ks.topology +description: The ks.topology extension displays a sorted graph of the internal topology of the filter closest to Object. +ms.assetid: 04ef6920-c022-4136-a42a-800679fe7ff4 +keywords: ["ks.topology Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ks.topology +api_type: +- NA +--- + +# !ks.topology + + +The **!ks.topology** extension displays a sorted graph of the internal topology of the filter closest to *Object*. + +``` +!ks.topology Object [Level] [Flags] +``` + +## Parameters + + + *Object* +Specifies a pointer to the object to use as a base for the graph. Can be a pointer to a file object, IRP, pin, filter, or other KS object. + + *Level* +Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a value of 7. + + *Flags* +Not currently available. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

winxp\Ks.dll

Windows XP and later

Ks.dll

+ +  + +### Additional Information + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +Remarks +------- + +For help, issue a **!ks.topology** command with no arguments. + +Note that this command may take a few moments to execute. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ks.topology%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-kuser.md b/windows-driver-docs-pr/debugger/-kuser.md new file mode 100644 index 0000000000..500a5e5774 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-kuser.md @@ -0,0 +1,79 @@ +--- +title: kuser +description: The kuser extension displays the shared user-mode page (KUSER_SHARED_DATA). +ms.assetid: 352a2f96-ff66-41be-94ee-045edbb1f81f +keywords: ["kuser Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- kuser +api_type: +- NA +--- + +# !kuser + + +The **!kuser** extension displays the shared user-mode page (KUSER\_SHARED\_DATA). + +``` +!kuser +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Exts.dll

+ +  + +Remarks +------- + +The KUSER\_SHARED\_DATA page gives resource and other information about the user who is currently logged on. + +Here is an example. Note that, in this example, the tick count is displayed in both its raw form and in a more user-friendly form, which is in parentheses. The user-friendly display is available only in Windows XP and later. + +``` +kd> !kuser +_KUSER_SHARED_DATA at 7ffe0000 +TickCount: fa00000 * 00482006 (0:20:30:56.093) +TimeZone Id: 2 +ImageNumber Range: [14c .. 14c] +Crypto Exponent: 0 +SystemRoot: 'F:\WINDOWS' +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!kuser%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lastevent--display-last-event-.md b/windows-driver-docs-pr/debugger/-lastevent--display-last-event-.md new file mode 100644 index 0000000000..9f46b3bf59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lastevent--display-last-event-.md @@ -0,0 +1,73 @@ +--- +title: .lastevent (Display Last Event) +description: The .lastevent command displays the most recent exception or event that occurred. +ms.assetid: 6f722c22-cb0f-4a10-b719-a168f7ba0943 +keywords: [".lastevent (Display Last Event) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .lastevent (Display Last Event) +api_type: +- NA +--- + +# .lastevent (Display Last Event) + + +The **.lastevent** command displays the most recent exception or event that occurred. + +``` +.lastevent +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about exceptions and events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +Remarks +------- + +Breaking into the debugger always creates an exception. There is always a *last event* when the debugger accepted command input. If you break into the debugger by using [**CTRL+C**](ctrl-c--break-.md), [CTRL+BREAK](debug---break.md), or Debug | Break, an exception code of 0x80000003 is created. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.lastevent%20%28Display%20Last%20Event%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-leave.md b/windows-driver-docs-pr/debugger/-leave.md new file mode 100644 index 0000000000..ed1a48b41f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-leave.md @@ -0,0 +1,50 @@ +--- +title: .leave +description: The .leave token is used to exit from a .catch block. +ms.assetid: 82c5cbf7-bccd-4abf-b52a-2db65e0a0c2c +keywords: [".leave Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .leave +api_type: +- NA +--- + +# .leave + + +The **.leave** token is used to exit from a [**.catch**](-catch.md) block. + +``` +.catch { ... ; .if (Condition) .leave ; ... } +``` + +## + + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +When a **.leave** token is encountered within a [**.catch**](-catch.md) block, the program exits from the block, and execution resumes with the first command after the closing brace. + +Since there is no control flow token equivalent to the C **goto** statement, you will usually use the **.leave** token within an [**.if**](-if.md) conditional, as shown in the syntax examples above. However, this is not actually required. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.leave%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lines--toggle-source-line-support-.md b/windows-driver-docs-pr/debugger/-lines--toggle-source-line-support-.md new file mode 100644 index 0000000000..89445cfc69 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lines--toggle-source-line-support-.md @@ -0,0 +1,86 @@ +--- +title: .lines (Toggle Source Line Support) +description: The .lines command enables or disables support for source-line information. +ms.assetid: 5d923592-7aba-42a0-893b-2c6621e4b87f +keywords: [".lines (Toggle Source Line Support) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .lines (Toggle Source Line Support) +api_type: +- NA +--- + +# .lines (Toggle Source Line Support) + + +The **.lines** command enables or disables support for source-line information. + +``` +.lines [-e|-d|-t] +``` + +## Parameters + + + **-e** +Enables source line support. + + **-d** +Disables source line support. + + **-t** +Turns source line support on or off. If you do not specify parameters for **.lines**, the default behavior of the **.lines** command is this switching of source line support. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about source debugging and related commands, see [Debugging in Source Mode](debugging-in-source-mode.md). + +Remarks +------- + +You must enable source line support before you can perform source-level debugging. This support enables the debugger to load source line symbols. + +You can enable source line support by using the **.lines** command or the [-lines command-line option](command-line-options.md). If source line support is already enabled, using the **.lines** command disables this support. + +By default, if you do not use the **.lines** command, WinDbg turns on source line support, and console debuggers (KD, CDB, NTSD) turn off the support. For more information about how to change this setting, see [Setting Symbol Options](symbol-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.lines%20%28Toggle%20Source%20Line%20Support%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-list.md b/windows-driver-docs-pr/debugger/-list.md new file mode 100644 index 0000000000..037d44fb9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-list.md @@ -0,0 +1,136 @@ +--- +title: list +description: The list extension executes the specified debugger commands repeatedly, once for every element in a linked list. +ms.assetid: 763742f3-1cb8-4263-861b-b9d01483245e +keywords: ["list Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- list +api_type: +- NA +--- + +# !list + + +The **!list** extension executes the specified debugger commands repeatedly, once for every element in a linked list. + +``` +!list -t [Module!]Type.Field -x "Commands" [-a "Arguments"] [Options] StartAddress +!list " -t [Module!]Type.Field -x \"Commands\" [-a \"Arguments\"] [Options] StartAddress " +!list -h +``` + +## Parameters + + + *Module* +An optional parameter specifying the module that defines this structure. If there is a chance that *Type* may match a valid symbol in a different module, you should include *Module* to eliminate the ambiguity. + + *Type* +Specifies the name of a data structure. + + *Field* +Specifies the field containing the list link. This can actually be a sequence of fields separated by periods (in other words, **Type.Field.Subfield.Subsubfield**, and so on). + + **-x "***Commands***"** +Specifies the commands to execute. This can be any combination of debugger commands. It must be enclosed in quotation marks. If multiple commands are specified, separate them with semicolons, enclose the entire collection of **!list** arguments in quotation marks, and use an escape character ( \\ ) before each quotation mark inside these outer quotation marks. If *Commands* is omitted, the default is [**dp (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md). + + **-a "***Arguments***"** +Specifies the arguments to pass to the *Commands* parameter. This must be enclosed in quotation marks. *Arguments* can be any valid argument string that would normally be allowed to follow this command, except that *Arguments* cannot contain quotation marks. If the pseudo-register **$extret** is included in *Commands*, the **-a "***Arguments***"** parameter can be omitted. + + *Options* +Can be any number of the following options: + +**-e** +Echoes the command being executed for each element. + +**-m** *Max* +Specifies the maximum number of elements to execute the command for. + + *StartAddress* +Specifies the address of the first data structure. This is the address at the top of the structure, not necessarily the address of the link field. + + **-h** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +The **!list** extension will go through the linked list and issue the specified command once for each list element. + +The pseudo-register **$extret** is set to the value of the list-entry address for each list element. For each element, the command string *Commands* is executed. This command string can reference this pseudo-register using the **$extret** syntax. If this does not appear in the command string, the value of the list-entry address is appended to the end of the command string before execution. If you need to specify where this value should appear in your command, you must specify this pseudo-register explicitly. + +This command sequence will run until the list terminates in a null pointer, or terminates by looping back onto the first element. If the list loops back onto a later element, this command will not stop. However, you can stop this command at any time by using [**CTRL+C**](ctrl-c--break-.md) in KD and CDB, or [Debug | Break](debug---break.md) or CTRL+BREAK in WinDbg. + +Each time a command is executed, the address of the current structure will be used as the *default address* if the command being used has optional address parameters. + +Following are two examples of how to use this command in user mode. Note that kernel mode usage is also possible but follows a different syntax. + +As a simple example, assume that you have a structure whose type name is **MYTYPE**, and which has links within its **.links.Flink** and **.links.Blink** fields. You have a linked list that begins with the structure at 0x6BC000. The following extension command will go through the list and for each element will execute a [**dd**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) L2 command. Because no address is being specified to the **dd** command, it will take the address of the list head as the desired address. This causes the first two DWORDs in each structure to be displayed. + +``` +0:000> !list -t MYTYPE.links.Flink -x "dd" -a "L2" 0x6bc00 +``` + +As a more complex example, consider the case of using **$extret**. It follows the list of type \_LIST\_ENTRY at **RtlCriticalSectionList**. For each element, it displays the first four DWORDS, and then displays the \_RTL\_CRITICAL\_SECTION\_DEBUG structure located at an offset of eight bytes prior to the **Flink** element of the list entry. + +``` +0:000> !list "-t ntdll!_LIST_ENTRY.Flink -e -x \"dd @$extret l4; dt ntdll!_RTL_CRITICAL_SECTION_DEBUG @$extret-0x8\" ntdll!RtlCriticalSectionList" +dd @$extret l4; dt ntdll!_RTL_CRITICAL_SECTION_DEBUG @$extret-0x8 +7c97c0c8 7c97c428 7c97c868 01010000 00000080 + +0x000 Type : 1 + +0x002 CreatorBackTraceIndex : 0 + +0x004 CriticalSection : (null) + +0x008 ProcessLocksList : _LIST_ENTRY [ 0x7c97c428 - 0x7c97c868 ] + +0x010 EntryCount : 0x1010000 + +0x014 ContentionCount : 0x80 + +0x018 Spare : [2] 0x7c97c100 + +dd @$extret l4; dt ntdll!_RTL_CRITICAL_SECTION_DEBUG @$extret-0x8 +7c97c428 7c97c448 7c97c0c8 00000000 00000000 + +0x000 Type : 0 + +0x002 CreatorBackTraceIndex : 0 + +0x004 CriticalSection : 0x7c97c0a0 + +0x008 ProcessLocksList : _LIST_ENTRY [ 0x7c97c448 - 0x7c97c0c8 ] + +0x010 EntryCount : 0 + +0x014 ContentionCount : 0 + +0x018 Spare : [2] 0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!list%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lmi.md b/windows-driver-docs-pr/debugger/-lmi.md new file mode 100644 index 0000000000..39e856f066 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lmi.md @@ -0,0 +1,107 @@ +--- +title: lmi +description: The lmi extension displays detailed information about a module. +ms.assetid: 00438edf-618a-401e-818f-24add7861487 +keywords: ["lmi Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lmi +api_type: +- NA +--- + +# !lmi + + +The **!lmi** extension displays detailed information about a module. + +``` +!lmi Module +``` + +## Parameters + + + *Module* +Specifies a loaded module, either by name or by base address. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Dbghelp.dll

Windows XP and later

Dbghelp.dll

+ +  + +Remarks +------- + +Module addresses can be determined by using the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command. + +The **!lmi** extension analyzes the module headers and displays a formatted summary of the information therein. If the module headers are paged out, an error message is displayed. To see a more extensive display of header information, use the [**!dh**](-dh.md) extension command. + +This command shows a number of fields, each with a different title. Some of these titles have specific meanings: + +- The **Image Name** field shows the name of the executable file, including the extension. Typically, the full path is included in user mode but not in kernel mode. + +- The **Module** field shows the *module name*. This is usually just the file name without the extension. In a few cases, the module name differs significantly from the file name. + +- The **Symbol Type** field shows information about the debugger's attempts to load this module's symbols. For an explanation of the various status values, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). If symbols have been loaded, the symbol file name follows this. + +- The first address in the module is shown as **Base Address**. The size of the module is shown as **Size**. Thus, if **Base Address** is "faab4000" and **Size** is "2000", the module extends from 0xFAAB4000 to 0xFAAB5FFF, inclusive. + +Here is an example: + +``` +0:000> lm +start end module name +00400000 0042d000 Prymes C (pdb symbols) Prymes.pdb +77e80000 77f35000 KERNEL32 (export symbols) C:\WINNT\system32\KERNEL32.dll +77f80000 77ffb000 ntdll (export symbols) ntdll.dll + +0:000> !lmi 00400000 +Loaded Module Info: [00400000] + Module: Prymes + Base Address: 00400000 + Image Name: Prymes.exe + Machine Type: 332 (I386) + Time Stamp: 3c76c346 Fri Feb 22 14:16:38 2002 + Size: 2d000 + CheckSum: 0 +Characteristics: 230e stripped +Debug Data Dirs: Type Size VA Pointer + MISC 110, 0, 77a00 [Data not mapped] + Symbol Type: EXPORT - PDB not found + Load Report: export symbols +``` + +For an explanation of the abbreviations shown on the **Characteristics** line of this example, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!lmi%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-load---loadby--load-extension-dll-.md b/windows-driver-docs-pr/debugger/-load---loadby--load-extension-dll-.md new file mode 100644 index 0000000000..5dae97bf90 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-load---loadby--load-extension-dll-.md @@ -0,0 +1,91 @@ +--- +title: .load, .loadby (Load Extension DLL) +description: The .load and .loadby commands load a new extension DLL into the debugger. +ms.assetid: bf54064a-6f30-4f31-a373-fbc643e2660c +keywords: [".load (Load Extension DLL) command", "loadby (Load Extension DLL) command", "Load Extension DLL (.load - .loadby) command", "extension commands ( commands), Load Extension DLL (.load - .loadby) command", ".load, .loadby (Load Extension DLL) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .load, .loadby (Load Extension DLL) +api_type: +- NA +--- + +# .load, .loadby (Load Extension DLL) + + +The **.load** and **.loadby** commands load a new extension DLL into the debugger. + +``` +.load DLLName +!DLLName.load +.loadby DLLName ModuleName +``` + +## Parameters + + + *DLLName* +Specifies the debugger extension DLL to load. If you use the **.load** command, *DLLName* should include the full path. If you use the **.loadby** command, *DLLName* should include only the file name. + + *ModuleName* +Specifies the module name of a module that is located in the same directory as the extension DLL that *DLLName* specifies. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to load, unload, and control extensions, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +Remarks +------- + +When you use the **.load** command, you must specify the full path. + +When you use the **.loadby** command, you do not specify the path. Instead, the debugger finds the module that the *ModuleName* parameter specifies, determines the path of that module, and then uses that path when the debugger loads the extension DLL. If the debugger cannot find the module or if it cannot find the extension DLL, you receive an error message that specifies the problem. There does not have to be any relationship between the specified module and the extension DLL. Using the **.loadby** command is therefore simply a way to avoid typing a long path. + +After the **.load** or **.loadby** command has been completed, you can access the commands that are stored in the loaded extension. + +To load an extension DLL, you can do one of the following: + +- Use the **.load** or **.loadby** command. + +- Execute an extension by issuing the full **!***DLLName***.***ExtensionCommand* syntax. If the debugger has not yet loaded *DLLName*.dll, it loads the DLL at this point. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.load,%20.loadby%20%28Load%20Extension%20DLL%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-loadermemorylist.md b/windows-driver-docs-pr/debugger/-loadermemorylist.md new file mode 100644 index 0000000000..055d8e062a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-loadermemorylist.md @@ -0,0 +1,75 @@ +--- +title: loadermemorylist +description: The loadermemorylist extension displays the memory allocation list that the Windows boot loader passes to Windows. +ms.assetid: 3e5dff7a-ea8f-4029-93e3-7c160487e968 +keywords: ["OSLOADER", "loadermemorylist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- loadermemorylist +api_type: +- NA +--- + +# !loadermemorylist + + +The **!loadermemorylist** extension displays the memory allocation list that the Windows boot loader passes to Windows. + +``` +!loadermemorylist ListHeadAddress +``` + +## Parameters + + + *ListHeadAddress* +Specifies the address of a list header. + +### DLL + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Kdexts.dll

Windows XP

+

Windows Server 2003

Kdexts.dll

Windows Vista and later

Kdexts.dll

+ +  + +Remarks +------- + +This extension is designed to be used at the beginning of the system boot process while Ntldr is running. It displays a memory allocation list that includes the start, end, and type of each page range. + +You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!loadermemorylist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-locale--set-locale-.md b/windows-driver-docs-pr/debugger/-locale--set-locale-.md new file mode 100644 index 0000000000..134b21a4e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-locale--set-locale-.md @@ -0,0 +1,92 @@ +--- +title: .locale (Set Locale) +description: The .locale command sets the locale or displays the current locale. +ms.assetid: 66c2a522-886f-41ef-ab90-176a3e0b7d88 +keywords: [".locale (Set Locale) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .locale (Set Locale) +api_type: +- NA +--- + +# .locale (Set Locale) + + +The **.locale** command sets the locale or displays the current locale. + +``` +.locale [Locale] +``` + +## Parameters + + + *Locale* +Specifies the locale that you want. If you omit this parameter, the debugger displays the current locale. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about locale, see the **setlocale** routine in the MSDN Library. + +Remarks +------- + +The locale controls how Unicode strings are displayed. + +The following examples show the **.locale** command. + +``` +kd> .locale +Locale: C + +kd> .locale E +Locale: English_United States.1252 + +kd> .locale c +Locale: Catalan_Spain.1252 + +kd> .locale C +Locale: C +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.locale%20%28Set%20Locale%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lockedpages.md b/windows-driver-docs-pr/debugger/-lockedpages.md new file mode 100644 index 0000000000..776a2b243d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lockedpages.md @@ -0,0 +1,53 @@ +--- +title: lockedpages +description: The lockedpages extension displays driver-locked pages for a specified process. +ms.assetid: a3f70b5f-350c-482f-a172-3abb2b22f408 +keywords: ["driver-locked pages", "lockedpages Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lockedpages +api_type: +- NA +--- + +# !lockedpages + + +The **!lockedpages** extension displays driver-locked pages for a specified process. + +Syntax + +``` +!lockedpages [Process] +``` + +## Parameters + + + *Process* +Specifies a process. If *Process* is omitted, the current process is used. + +### DLL + +Kdexts.dll + +Remarks +------- + +You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!lockedpages%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-locks---kdext--locks-.md b/windows-driver-docs-pr/debugger/-locks---kdext--locks-.md new file mode 100644 index 0000000000..4afa384f36 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-locks---kdext--locks-.md @@ -0,0 +1,137 @@ +--- +title: !locks (!kdext*.locks) +description: The locks extension in Kdextx86.dll and Kdexts.dll displays information about kernel ERESOURCE locks. +ms.assetid: c1be6c6c-0028-459f-9c92-61df52cbc4b6 +keywords: ["kdext .locks extension", "ERESOURCE locks", "deadlocks", "locks ( kdext .locks) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- locks ( kdext .locks) +api_type: +- NA +--- + +# !locks (!kdext\*.locks) + + +The **!locks** extension in Kdextx86.dll and Kdexts.dll displays information about kernel ERESOURCE locks. + +This extension command should not be confused with the [**!ntsdexts.locks**](-locks---ntsdexts-locks-.md) extension command. + +``` +!locks [Options] [Address] +``` + +## Parameters + + + *Options* +Specifies the amount of information to be displayed. Any combination of the following options can be used: + +**-v** +Displays detailed information about each lock. + +**-p** +Display all available information about the locks, including performance statistics. + +**-d** +Display information about all locks. Otherwise, only locks with contention are displayed.) + + *Address* +Specifies the hexadecimal address of the ERESOURCE lock to be displayed. If *Address* is 0 or omitted, information about all ERESOURCE locks in the system will be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The **!locks** extension displays all locks held on resources by threads. A lock can be shared or exclusive, which means no other threads can gain access to that resource. This information is useful when a deadlock occurs on a system. A deadlock is caused by one non-executing thread holding an exclusive lock on a resource that the executing thread needs. + +You can usually pinpoint a deadlock in Microsoft Windows 2000 by finding one non-executing thread that holds an exclusive lock on a resource that is required by an executing thread. Most of the locks are shared. + +Here is an example of the basic **!locks** output: + +``` +kd> !locks +**** DUMP OF ALL RESOURCE OBJECTS **** +KD: Scanning for held locks...... + +Resource @ 0x80e97620 Shared 4 owning threads + Threads: ff688da0-01<*> ff687da0-01<*> ff686da0-01<*> ff685da0-01<*> +KD: Scanning for held locks....................................................... + +Resource @ 0x80e23f38 Shared 1 owning threads + Threads: 80ed0023-01<*> *** Actual Thread 80ed0020 +KD: Scanning for held locks. + +Resource @ 0x80d8b0b0 Shared 1 owning threads + Threads: 80ed0023-01<*> *** Actual Thread 80ed0020 +2263 total locks, 3 locks currently held +``` + +Note that the address for each thread displayed is followed by its thread count (for example, "-01"). If a thread is followed by "<\*>", that thread is one of the owners of the lock. In some instances, the initial thread address contains an offset. In that case, the actual thread address is displayed as well. + +If you want to find more information about one of these resource objects, use the address that follows "Resource @" as an argument for future commands. To investigate the second resource shown in the preceding example, you could use [**dt ERESOURCE 80d8b0b0**](dt--display-type-.md) or [**!thread 80ed0020**](-thread.md). Or you could use the **!locks** extension again with the **-v** option: + +``` +kd> !locks -v 80d8b0b0 + +Resource @ 0x80d8b0b0 Shared 1 owning threads + Threads: 80ed0023-01<*> *** Actual Thread 80ed0020 + + THREAD 80ed0020 Cid 4.2c Teb: 00000000 Win32Thread: 00000000 WAIT: (WrQueue) KernelMode Non-Alertable + 8055e100 Unknown + Not impersonating +GetUlongFromAddress: unable to read from 00000000 + Owning Process 80ed5238 + WaitTime (ticks) 44294977 + Context Switch Count 147830 + UserTime 0:00:00.0000 + KernelTime 0:00:02.0143 + Start Address nt!ExpWorkerThread (0x80506aa2) + Stack Init fafa4000 Current fafa3d18 Base fafa4000 Limit fafa1000 Call 0 + Priority 13 BasePriority 13 PriorityDecrement 0 +ChildEBP RetAddr +fafa3d30 804fe997 nt!KiSwapContext+0x25 (FPO: [EBP 0xfafa3d48] [0,0,4]) [D:\NT\base\ntos\ke\i386\ctxswap.asm @ 139] +fafa3d48 80506a17 nt!KiSwapThread+0x85 (FPO: [Non-Fpo]) (CONV: fastcall) [d:\nt\base\ntos\ke\thredsup.c @ 1960] +fafa3d78 80506b36 nt!KeRemoveQueue+0x24c (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ke\queueobj.c @ 542] +fafa3dac 805ad8bb nt!ExpWorkerThread+0xc6 (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ex\worker.c @ 1130] +fafa3ddc 8050ec72 nt!PspSystemThreadStartup+0x2e (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ps\create.c @ 2164] +00000000 00000000 nt!KiThreadStartup+0x16 [D:\NT\base\ntos\ke\i386\threadbg.asm @ 81] + +1 total locks, 1 locks currently held +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!locks%20%28!kdext*.locks%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-locks---ntsdexts-locks-.md b/windows-driver-docs-pr/debugger/-locks---ntsdexts-locks-.md new file mode 100644 index 0000000000..9a057924f7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-locks---ntsdexts-locks-.md @@ -0,0 +1,102 @@ +--- +title: locks ( ntsdexts.locks) +description: The locks extension in Ntsdexts.dll displays a list of critical sections associated with the current process.This extension command should not be confused with the kdext*.locks extension command. +ms.assetid: f33a68e8-1ddc-4d49-bb22-8f8b097c8ada +keywords: ["locks ( ntsdexts.locks) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- locks ( ntsdexts.locks) +api_type: +- NA +--- + +# !locks (!ntsdexts.locks) + + +The **!locks** extension in Ntsdexts.dll displays a list of critical sections associated with the current process. + +This extension command should not be confused with the [**!kdext\*.locks**](-locks---kdext--locks-.md) extension command. + +``` + !locks [Options] +``` + +## Parameters + + + *Options* +Specifies the amount of information to be displayed. Any combination of the following options can be used: + +**-v** +Causes the display to include all critical sections, even those that are not currently owned. + +**-o** +(Windows XP and later) Causes the display to only include orphaned information (pointers that do not actually point to valid critical sections). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Ntsdexts.dll

+ +  + +### Additional Information + +For other commands and extensions that can display critical section information, see [Displaying a Critical Section](displaying-a-critical-section.md). For information about critical sections, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +This extension command shows all critical sections that have been initialized by calling **RtlInitializeCriticalSection**. If there are no critical sections, then no output will result. + +Here is an example: + +``` +0:000> !locks + +CritSec w3svc!g_pWamDictator+a0 at 68C2C298 +LockCount 0 +RecursionCount 1 +OwningThread d1 +EntryCount 1 +ContentionCount 0 +*** Locked + +CritSec SMTPSVC+66a30 at 67906A30 +LockCount 0 +RecursionCount 1 +OwningThread d0 +EntryCount 1 +ContentionCount 0 +*** Locked +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!locks%20%28!ntsdexts.locks%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logappend--append-log-file-.md b/windows-driver-docs-pr/debugger/-logappend--append-log-file-.md new file mode 100644 index 0000000000..a5ff5199c8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logappend--append-log-file-.md @@ -0,0 +1,79 @@ +--- +title: .logappend (Append Log File) +description: The .logappend command appends a copy of the events and commands from the Debugger Command window to the specified log file. +ms.assetid: e1c58c34-1fc5-4ec3-bd37-6c7816735aec +keywords: ["Append Log File (.logappend) command", "log file, Append Log File (.logappend) command", ".logappend (Append Log File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .logappend (Append Log File) +api_type: +- NA +--- + +# .logappend (Append Log File) + + +The **.logappend** command appends a copy of the events and commands from the [Debugger Command window](debugger-command-window.md) to the specified log file. + +``` +.logappend [/u] [FileName] +``` + +## Parameters + + + **/u** +Writes the log file in Unicode format. If you omit this parameter, the debugger writes the log file in ASCII (ANSI) format. + +**Note**   When you are appending to an existing log file, you should use the **/u** parameter only if you created the log file by using the **/u** option. Otherwise, your log file will contain ASCII and Unicode characters, which might make it more difficult to read. + +  + + *FileName* +Specifies the name of the log file. You can specify a full path or only the file name. If the file name contains spaces, enclose *FileName* in quotation marks. If you do not specify the path, the debugger uses the current directory. If you omit *FileName*, the debugger names the file Dbgeng.log. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +If you already have a log file open when you run the **.logappend** command, the debugger closes the log file. If you specify the name of a file that already exists, the debugger appends new information to the file. If the file does not exist, the debugger creates it. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.logappend%20%28Append%20Log%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logclose--close-log-file-.md b/windows-driver-docs-pr/debugger/-logclose--close-log-file-.md new file mode 100644 index 0000000000..8be753e8c8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logclose--close-log-file-.md @@ -0,0 +1,64 @@ +--- +title: .logclose (Close Log File) +description: The .logclose command closes any open log file. +ms.assetid: 730cfab3-5529-4054-ba62-8a780572603d +keywords: [".logclose (Close Log File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .logclose (Close Log File) +api_type: +- NA +--- + +# .logclose (Close Log File) + + +The **.logclose** command closes any open log file. + +``` + .logclose +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.logclose%20%28Close%20Log%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-help.md b/windows-driver-docs-pr/debugger/-logexts-help.md new file mode 100644 index 0000000000..1d1072f196 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-help.md @@ -0,0 +1,64 @@ +--- +title: logexts.help +description: The logexts.help extension displays a Help text in the Command Prompt window showing all Logexts.dll extension commands. +ms.assetid: 6b3f8aed-b0c5-448d-b1f8-41cfaf357ebb +keywords: ["logexts.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.help +api_type: +- NA +--- + +# !logexts.help + + +The **!logexts.help** extension displays a Help text in the Command Prompt window showing all Logexts.dll extension commands. + +``` +!logexts.help +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logb.md b/windows-driver-docs-pr/debugger/-logexts-logb.md new file mode 100644 index 0000000000..22514186d4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logb.md @@ -0,0 +1,80 @@ +--- +title: logexts.logb +description: The logexts.logb extension displays or flushes the output buffer. +ms.assetid: 3c6ec412-f800-469b-9a9f-ebc2940d00fe +keywords: ["logexts.logb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logb +api_type: +- NA +--- + +# !logexts.logb + + +The **!logexts.logb** extension displays or flushes the output buffer. + +``` +!logexts.logb p +!logexts.logb f +``` + +## Parameters + + + **p** +Causes the contents of the output buffer to be displayed in the debugger. + + **f** +Flushes the output buffer to the disk. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +As a performance consideration, log output is flushed to disk only when the output buffer is full. By default, the buffer is 2144 bytes. + +The **!logexts.logb p** extension displays the contents of the buffer in the debugger. + +The **!logexts.logb f** extension flushes the buffer to the log files. Because the buffer memory is managed by the target application, the automatic writing of the buffer to disk will not occur if there is an access violation or some other nonrecoverable error in the target application. In such cases, you should use this command to manually flush the buffer to the disk. Otherwise, the most recently-logged APIs might not appear in the log files. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logc.md b/windows-driver-docs-pr/debugger/-logexts-logc.md new file mode 100644 index 0000000000..36077409f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logc.md @@ -0,0 +1,115 @@ +--- +title: logexts.logc +description: The logexts.logc extension displays all API categories, displays all APIs in a specific category, or enables and disables the logging of APIs in one or more categories. +ms.assetid: b0132055-da13-45a8-8e83-06ddcb8b90d7 +keywords: ["logexts.logc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logc +api_type: +- NA +--- + +# !logexts.logc + + +The **!logexts.logc** extension displays all API categories, displays all APIs in a specific category, or enables and disables the logging of APIs in one or more categories. + +``` +!logexts.logc e Categories +!logexts.logc d Categories +!logexts.logc p Category +!logexts.logc +``` + +## Parameters + + + **e** +Enables logging of the specified categories. + + **d** +Disables logging of the specified categories. + + *Categories* +Specifies the categories to be enabled or disabled. If multiple categories are listed, separate them with spaces. An asterisk (\*) can be used to indicate all categories. + + **p** +Displays all APIs that belong to the specified category. + + *Category* +Specifies the category whose APIs will be displayed. Only one category can be specified with the **p** option. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +Without any options, **!logexts.logc** will display the current list of available categories and will indicate which ones are enabled and disabled. + +If a category is disabled, the hooks for all APIs in that category will be removed so there is no longer any performance overhead. COM hooks are not removed, because they cannot be re-enabled at will. + +Enabling only certain categories can be useful when you are only interested in a particular type of interaction that the program is having with Windows (for example, file operations). This reduces the log file size and also reduces the effect that Logger has on the execution speed of the process. + +The following command will enable the logging of all categories: + +``` +0:000> !logexts.logc e * +``` + +The following command will disable the logging of category 7: + +``` +0:000> !logexts.logc d 7 +``` + +The following command will enable the logging of categories 13 and 15: + +``` +0:000> !logexts.logc e 13 15 +``` + +The following command will display all APIs belonging to category 3: + +``` +0:000> !logexts.logc p 3 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logd.md b/windows-driver-docs-pr/debugger/-logexts-logd.md new file mode 100644 index 0000000000..3301b1142d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logd.md @@ -0,0 +1,69 @@ +--- +title: logexts.logd +description: The logexts.logd extension disables logging. +ms.assetid: d3c3403d-f86b-4f2a-a261-c00eb0b2b756 +keywords: ["logexts.logd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logd +api_type: +- NA +--- + +# !logexts.logd + + +The **!logexts.logd** extension disables logging. + +``` + !logexts.logd +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +This will cause all API hooks to be removed in an effort to allow the program to run freely. COM hooks are not removed, because they cannot be re-enabled at will. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-loge.md b/windows-driver-docs-pr/debugger/-logexts-loge.md new file mode 100644 index 0000000000..0b068658ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-loge.md @@ -0,0 +1,74 @@ +--- +title: logexts.loge +description: The logexts.loge extension enables logging. If logging has not been initialized, it will be initialized and enabled. +ms.assetid: d8b621f1-19e7-4c42-a428-8572d29b666f +keywords: ["logexts.loge Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.loge +api_type: +- NA +--- + +# !logexts.loge + + +The **!logexts.loge** extension enables logging. If logging has not been initialized, it will be initialized and enabled. + +``` + !logexts.loge [OutputDirectory] +``` + +## Parameters + + + *OutputDirectory* +Specifies the directory to use for output. If *OutputDirectory* is specified, it must exist -- the debugger will not create it. If a relative path is specified, it will be relative to the directory from which the debugger was started. If *OutputDirectory* is omitted, the path to the Desktop will be used. The debugger will create a LogExts subdirectory of *OutputDirectory*, and all Logger output will be placed in this subdirectory. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +If Logger has not yet been injected into the target application by the [**!logexts.logi**](-logexts-logi.md) extension, the **!logexts.loge** extension will inject Logger into the target and then enable logging. + +If [**!logexts.logi**](-logexts-logi.md) has already been run, you cannot include *OutputDirectory*, because the output directory will have already been set. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.loge%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logi.md b/windows-driver-docs-pr/debugger/-logexts-logi.md new file mode 100644 index 0000000000..94ecadc6b4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logi.md @@ -0,0 +1,72 @@ +--- +title: logexts.logi +description: The logexts.logi extension initializes logging by injecting Logger into the target application. +ms.assetid: c02d2799-c83a-455d-90c0-401244062365 +keywords: ["logexts.logi Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logi +api_type: +- NA +--- + +# !logexts.logi + + +The **!logexts.logi** extension initializes logging by injecting Logger into the target application. + +``` + !logexts.logi [OutputDirectory] +``` + +## Parameters + + + *OutputDirectory* +Specifies the directory to use for output. If *OutputDirectory* is specified, it must exist -- the debugger will not create it. If a relative path is specified, it will be relative to the directory from which the debugger was started. If *OutputDirectory* is omitted, the path to the Desktop will be used. The debugger will create a LogExts subdirectory of *OutputDirectory*, and all Logger output will be placed in this subdirectory. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +This command initializes logging, but does not actually enable it. Logging can be enabled with the [**!logexts.loge**](-logexts-loge.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logi%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logm.md b/windows-driver-docs-pr/debugger/-logexts-logm.md new file mode 100644 index 0000000000..ce612611ea --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logm.md @@ -0,0 +1,114 @@ +--- +title: logexts.logm +description: The logexts.logm extension creates or displays a module inclusion list or a module exclusion list. +ms.assetid: 1037ba25-ffa6-4edd-99fd-bd0e249f4b37 +keywords: ["logexts.logm Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logm +api_type: +- NA +--- + +# !logexts.logm + + +The **!logexts.logm** extension creates or displays a module inclusion list or a module exclusion list. + +``` +!logexts.logm i Modules +!logexts.logm x Modules +!logexts.logm +``` + +## Parameters + + + **i** +Causes Logger to use a module inclusion list. It will consist of the specified *Modules*. + + **x** +Causes Logger to use a module exclusion list. It will consist of Logexts.dll, kernel32.dll, and the specified *Modules*. + + *Modules* +Specifies the modules to be included or excluded. This list is not cumulative; each use of this command creates an entirely new list. If multiple modules are listed, separate them with spaces. An asterisk (\*) can be used to indicate all modules. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +With no parameters, the **!logexts.logm** extension displays the current inclusion list or exclusion list. + +The extensions **!logexts.logm x \*** and **!logexts.logm i** are equivalent: they result in a completely empty inclusion list. + +The extensions **!logexts.logm i \*** and **!logexts.logm x** are equivalent: they result in an exclusion list that contains only Logexts.dll and kernel32.dll. These two modules are always excluded, because Logger is not permitted to log itself. + +Here are some examples: + +``` +0:001> !logm +Excluded modules: + LOGEXTS.DLL [mandatory] + KERNEL32.DLL [mandatory] + USER32.DLL + GDI32.DLL + ADVAPI32.DLL + +0:001> !logm x winmine.exe +Excluded modules: + Logexts.dll [mandatory] + kernel32.dll [mandatory] + winmine.exe + +0:001> !logm x user32.dll gdi32.dll +Excluded modules: + Logexts.dll [mandatory] + kernel32.dll [mandatory] + user32.dll + gdi32.dll + +0:001> !logm i winmine.exe mymodule2.dll +Included modules: + winmine.exe + mymodule2.dll +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logm%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logexts-logo.md b/windows-driver-docs-pr/debugger/-logexts-logo.md new file mode 100644 index 0000000000..e5d792693b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logexts-logo.md @@ -0,0 +1,101 @@ +--- +title: logexts.logo +description: The logexts.logo extension sets or displays the Logger output options. +ms.assetid: b094cf4b-1d01-4b84-9032-aa865d680df4 +keywords: ["logexts.logo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logexts.logo +api_type: +- NA +--- + +# !logexts.logo + + +The **!logexts.logo** extension sets or displays the Logger output options. + +``` +!logexts.logo {e|d} {d|t|v} +!logexts.logo +``` + +## Parameters + + + **e|d** +Specifies whether to enable (e) or disable (d) the indicated output type. + + **d|t|v** +Specifies the output type. Three types of Logger output are possible: messages sent directly to the debugger (d), a text file (t), or a verbose .lgv file (v). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Logexts.dll

Windows XP and later

Logexts.dll

+ +  + +### Additional Information + +For more information, see [Logger and LogViewer](logger-and-logviewer.md). + +Remarks +------- + +If **!logexts.logo** is used without any parameters, then the current logging status, the output directory, and the current settings for the debugger, text file, and verbose log are displayed: + +``` +0:000> !logo +Logging currently enabled. + +Output directory: MyLogs\LogExts\ + +Output settings: + Debugger Disabled + Text file Enabled + Verbose log Enabled +``` + +In the previous example, the output directory is a relative path, so it is located relative to the directory in which the debuggers were started. + +To disable verbose logging, you would use the following command: + +``` +0:000> !logo d v + Debugger Disabled + Text file Enabled + Verbose log Disabled +``` + +Text file and .lgv files will be placed in the current output directory. To read an .lgv file, use LogViewer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logexts.logo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logfile--display-log-file-status-.md b/windows-driver-docs-pr/debugger/-logfile--display-log-file-status-.md new file mode 100644 index 0000000000..9fdfb41a97 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logfile--display-log-file-status-.md @@ -0,0 +1,64 @@ +--- +title: .logfile (Display Log File Status) +description: The .logfile command determines whether a log file exists and displays the file's status. +ms.assetid: 30aaa2bc-2ae5-474f-871b-3e3a164b2dee +keywords: [".logfile (Display Log File Status) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .logfile (Display Log File Status) +api_type: +- NA +--- + +# .logfile (Display Log File Status) + + +The **.logfile** command determines whether a log file exists and displays the file's status. + +``` + .logfile +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.logfile%20%28Display%20Log%20File%20Status%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logonsession.md b/windows-driver-docs-pr/debugger/-logonsession.md new file mode 100644 index 0000000000..3a762e4442 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logonsession.md @@ -0,0 +1,137 @@ +--- +title: logonsession +description: The logonsession extension displays information about a specified logon session. +ms.assetid: 95746bc0-ab36-43a7-83ad-9f6fdbb15b39 +keywords: ["logon session", "logonsession Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- logonsession +api_type: +- NA +--- + +# !logonsession + + +The **!logonsession** extension displays information about a specified logon session. + +Free Build Syntax + +``` +!logonsession LUID +``` + +Checked Build Syntax + +``` +!logonsession LUID [InfoLevel] +``` + +## Parameters + + + *LUID* +Specifies the locally unique identifier (LUID) of a logon session to display. If *LUID*is 0, information about all logon sessions is displayed. + +To display information about the system session and all system tokens in a checked build, enter **!logonsession 3e7 1**. + + *InfoLevel* +(Checked Build Only) Specifies how much token information is displayed. The *InfoLevel* parameter can take values from 0 to 4, with 0 representing the least information and 4 representing the most information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about logon sessions, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Here is an example of the output from this extension on a free build: + +``` +kd> !logonsession 0 + +Dumping all logon sessions. + +** Session 0 = 0x0 + LogonId = {0x0 0x0} + References = 0 +** Session 1 = 0x8ebb50 + LogonId = {0xe9f1 0x0} + References = 21 +** Session 2 = 0x6e31e0 + LogonId = {0x94d1 0x0} + References = 1 +** Session 3 = 0x8ecd60 + LogonId = {0x6b31 0x0} + References = 0 +** Session 4 = 0xe0000106 + LogonId = {0x0 0x0} + References = 0 +** Session 5 = 0x0 + LogonId = {0x0 0x0} + References = 0 +** Session 6 = 0x8e9720 + LogonId = {0x3e4 0x0} + References = 6 +** Session 7 = 0xe0000106 + LogonId = {0x0 0x0} + References = 0 +** Session 8 = 0xa2e160 + LogonId = {0x3e5 0x0} + References = 3 +** Session 9 = 0xe0000106 + LogonId = {0x0 0x0} + References = 0 +** Session 10 = 0x3ca0 + LogonId = {0x3e6 0x0} + References = 2 +** Session 11 = 0xe0000106 + LogonId = {0x0 0x0} + References = 0 +** Session 12 = 0x1cd0 + LogonId = {0x3e7 0x0} + References = 33 +** Session 13 = 0xe0000106 + LogonId = {0x0 0x0} + References = 0 +14 sessions in the system. +``` + +You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!logonsession%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-logopen--open-log-file-.md b/windows-driver-docs-pr/debugger/-logopen--open-log-file-.md new file mode 100644 index 0000000000..087c41f85b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-logopen--open-log-file-.md @@ -0,0 +1,92 @@ +--- +title: .logopen (Open Log File) +description: The .logopen command sends a copy of the events and commands from the Debugger Command window to a new log file. +ms.assetid: 00ccc09b-3fd7-462f-a688-2f7b45b584fb +keywords: ["Open Log File (.logopen) command", "log file, Open Log File (.logopen) command", ".logopen (Open Log File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .logopen (Open Log File) +api_type: +- NA +--- + +# .logopen (Open Log File) + + +The **.logopen** command sends a copy of the events and commands from the [Debugger Command window](debugger-command-window.md) to a new log file. + +``` +.logopen [Options] [FileName] +.logopen /d +``` + +## Parameters + + + *Options* +Any of the following options: + +**/t** +Appends the process ID with the current date and time to the log file name. This data is inserted after the file name and before the file name extension. + +**/u** +Writes the log file in Unicode format. If you omit this option, the debugger writes the log file in ASCII (ANSI) format. + + *FileName* +Specifies the name of the log file. You can specify a full path or only the file name. If the file name contains spaces, enclose *FileName* in quotation marks. If you do not specify a path, the debugger uses the current directory. If you omit *FileName*, the debugger names the file Dbgeng.log. + + **/d** +Automatically chooses a file name based on the name of the target process or target computer and the state of the target. The file always has the .log file name extension. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +If you already have a log file open when you run the **.logopen** command, the debugger closes it. If you specify a file name that already exists, the file's contents are overwritten. + +The **.logopen /t** command appends the process ID, date, and time to the log file name. In the following example, the process ID in hexadecimal is 0x02BC, the date is February 28, 2005, and the time is 9:05:50.935. + +``` +0:000> .logopen /t c:\logs\mylogfile.txt +Opened log file 'c:\logs\mylogfile_02BC_2005-02-28_09-05-50-935.txt' +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.logopen%20%28Open%20Log%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lookaside.md b/windows-driver-docs-pr/debugger/-lookaside.md new file mode 100644 index 0000000000..d213d5a39f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lookaside.md @@ -0,0 +1,108 @@ +--- +title: lookaside +description: The lookaside extension displays information about look-aside lists, resets the counters of look-aside lists, or modifies the depth of a look-aside list. +ms.assetid: ec343563-f293-4ddf-96c8-69fc7b9b4377 +keywords: ["lookaside list", "lookaside Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lookaside +api_location: +- Kdexts.dll +api_type: +- DllExport +--- + +# !lookaside + + +The **!lookaside** extension displays information about look-aside lists, resets the counters of look-aside lists, or modifies the depth of a look-aside list. + +``` +!lookaside [Address [Options [Depth]]] +!lookaside [-all] +!lookaside 0 [-all] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of a look-aside list to be displayed or modified. + +If *Address* is omitted (or 0) and the **-all** option is not specified, a set of well-known, standard system look-aside lists is displayed. The set of lists is not exhaustive; that is, it does not include all system look-aside lists. Also, the set does not include custom look-aside lists that were created by calls to [**ExInitializePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545309) or [**ExInitializeNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545301). + +If *Address* is omitted (or 0) and the **-all** option is specified, all look-aside lists are displayed. + + *Options* +Controls what operation will be taken. The following possible *Options* are supported. The default is zero: + +0 +Displays information about the specified look-aside list or lists. + +1 +Resets the counters of the specified look-aside list. + +2 +Modifies the depth of the specified look-aside list. This option can only be used if *Address* is nonzero. + + *Depth* +Specifies the new maximum depth of the specified look-aside list. This parameter is permitted only if *Address* is nonzero and *Options* is equal to 2. + +### Additional Information + +For information about look-aside lists, see the [Windows Driver Kit (WDK) documentation](http://go.microsoft.com/fwlink/p/?linkid=201141) and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Look-aside lists are multiprocessor-safe mechanisms for managing pools of fixed-size entries from either paged or nonpaged memory. + +Look-aside lists are efficient, because the routines do not use spin locks on most platforms. + +Note that if the current depth of a look-aside list exceeds the maximum depth of that list, then freeing a structure associated with that list will result in freeing it into pool memory, rather than list memory. + +Here is an example of the output from this extension: + +``` +!lookaside 0xfffff88001294f80 + +Lookaside "" @ 0xfffff88001294f80 Tag(hex): 0x7366744e "Ntfs" + Type = 0011 PagedPool RaiseIfAllocationFailure + Current Depth = 0 Max Depth = 4 + Size = 496 Max Alloc = 1984 + AllocateMisses = 8 FreeMisses = 0 + TotalAllocates = 272492 TotalFrees = 272488 + Hit Rate = 99% Hit Rate = 100% +``` + +Requirements +------------ + + ++++ + + + + + + +

DLL

Kdexts.dll
+ +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!lookaside%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-lpc.md b/windows-driver-docs-pr/debugger/-lpc.md new file mode 100644 index 0000000000..868ee433c8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-lpc.md @@ -0,0 +1,230 @@ +--- +title: lpc +description: The lpc extension displays information about all local procedure call (LPC) ports and messages in the target system. +ms.assetid: d474aeca-fb12-424a-b57e-360215d0305c +keywords: ["LPC (local/light-weight procedure call)", "lpc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lpc +api_type: +- NA +--- + +# !lpc + + +**Important**   +This extension is not supported in Windows Vista and later versions of Windows. Lpc is now emulated in alpc, use the !alpc extension instead. + +  + +The **!lpc** extension displays information about all local procedure call (LPC) ports and messages in the target system. + +Syntax in Windows 2000 + +``` +!lpc message MessageID +!lpc port Port +!lpc scan Port +!lpc thread Thread +!lpc +``` + +Syntax in Windows Server 2003 and Windows XP + +``` +!lpc message MessageID +!lpc port Port +!lpc scan Port +!lpc thread Thread +!lpc PoolSearch +!lpc +``` + +## Parameters + + + **message** +(Windows Server 2003, Windows XP, and Windows 2000 only) Displays information about a message, such as the server port that contains the message in the queue, and the thread waiting for this message, if any. + + *MessageID* +(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the message ID of the message to be displayed. If the value of this parameter is 0 or this parameter is omitted, the **!lpc message** command displays a summary list of messages. (In Windows 2000 with Service Pack 1 (SP1), the summary includes all messages in the LPC zone. In Windows 2000 with Service Pack 2 (SP2), Windows XP, and later versions of Windows, the summary includes all messages in the kernel pool. Paged-out messages are not included.) + + **port** +(Windows Server 2003, Windows XP, and Windows 2000 only) Displays port information, such as the name of the port, its semaphore state, messages in its queues, threads in its rundown queue, its handle count, its references, and related ports. + + **scan** +(Windows Server 2003, Windows XP, and Windows 2000 only) Displays summary information about the specified port and about all ports that are connected to it. + + *Port* +(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the hexadecimal address of the port to be displayed. If the **!lpc port** command is used, and *Port* is 0 or is omitted, a summary list of all LPC ports is displayed. If the **!lpc scan** command is used, *Port* must specify the address of an actual port. + + **thread** +(Windows Server 2003, Windows XP, and Windows 2000 only) Displays port information for all ports that contain the specified thread in their rundown port queues. + + *Thread* +(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the hexadecimal address of the thread. If this is 0 or omitted, the **!lpc thread** command displays a summary list of all threads that are performing any LPC operations. + + **PoolSearch** +(Windows Server 2003 and Windows XP only) Determines whether the **!lpc message** command searches for messages in the kernel pool. Each time **!lpc PoolSearch** is used, this setting toggles on or off (the initial setting is to not search the kernel pool). This only affects **!lpc message** commands that specify a nonzero value for *MessageID*. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP

+

Windows Server 2003

Kdexts.dll

+ +  + +### Additional Information + +For information about LPCs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +This extension is not supported in Windows Vista and later versions of Windows. + +In Windows Server 2003, Windows XP, and Windows 2000, using **!lpc** with no arguments displays help for this extension in the Debugger Command window. + +If you have a thread that is marked as waiting for a reply to a message, use the **!lpc message** command with the ID of the delayed message. This command displays the specified message, the port that contains it, and all related threads. + +If the message is not found and there were no read errors (such as "Unable to access zone segment"), the server received the message. + +In this case, the server port can usually be found by using the **!lpc thread** command. Threads that are waiting for replies are linked into a server communication queue. This command will display all ports that contain the specified thread. After you know the port address, use the **!lpc port** command. More specific information about each thread can then be obtained by using the **!lpc thread**command with the address of each thread. + +Here are several examples of the output from this extension from a Windows XP system: + +In this example, all port LPC ports are displayed. + +``` +kd> !lpc port +Scanning 225 objects + 1 Port: 0xe1405650 Connection: 0xe1405650 Communication: 0x00000000 'SeRmCommandPort' + 1 Port: 0xe141ef50 Connection: 0xe141ef50 Communication: 0x00000000 'SmApiPort' + 1 Port: 0xe13c5740 Connection: 0xe13c5740 Communication: 0x00000000 'ApiPort' + 1 Port: 0xe13d9550 Connection: 0xe13d9550 Communication: 0x00000000 'SbApiPort' + 3 Port: 0xe13d8830 Connection: 0xe141ef50 Communication: 0xe13d8910 ' +80000004 Port: 0xe13d8910 Connection: 0xe141ef50 Communication: 0xe13d8830 ' + 3 Port: 0xe13d8750 Connection: 0xe13d9550 Communication: 0xe13a4030 ' + ..... +``` + +In the previous example, the port at address e14ae238 has no messages; that is, all messages have been picked up and no new messages have arrived. + +``` +kd> !lpc port e14ae238 + +Server connection port e14ae238 Name: ApiPort + Handles: 1 References: 107 + Server process : 84aa0140 (csrss.exe) + Queue semaphore : 84a96da8 + Semaphore state 0 (0x0) + The message queue is empty + The LpcDataInfoChainHead queue is empty +``` + +In the previous example, the port at 0xe14ae238 has messages which have been queued, but not yet picked up by the server. + +``` +kd> !lpc port 0xe14ae238 + +Server connection port e14ae238 Name: ApiPort + Handles: 1 References: 108 + Server process : 84aa0140 (csrss.exe) + Queue semaphore : 84a96da8 + Semaphore state 0 (0x0) + Messages in queue: + 0000 e20d9b80 - Busy Id=0002249c From: 0584.0680 Context=00000021 [e14ae248 . e14ae248] + Length=0098007c Type=00000001 (LPC_REQUEST) + Data: 00000000 0002021e 00000584 00000680 002f0001 00000007 + The message queue contains 1 messages + The LpcDataInfoChainHead queue is empty +``` + +The remaining Windows XP examples concern the other options that can be used with this extension. + +``` +kd> !lpc message 222be +Searching message 222be in threads ... +Client thread 842a4db0 waiting a reply from 222be +Searching thread 842a4db0 in port rundown queues ... + +Server communication port 0xe114a3c0 + Handles: 1 References: 1 + The LpcDataInfoChainHead queue is empty + Connected port: 0xe1e7b948 Server connection port: 0xe14ae238 + +Client communication port 0xe1e7b948 + Handles: 1 References: 3 + The LpcDataInfoChainHead queue is empty + +Server connection port e14ae238 Name: ApiPort + Handles: 1 References: 107 + Server process : 84aa0140 (csrss.exe) + Queue semaphore : 84a96da8 + Semaphore state 0 (0x0) + The message queue is empty + The LpcDataInfoChainHead queue is empty +Done. +``` + +``` +kd> !lpc thread 842a4db0 +Searching thread 842a4db0 in port rundown queues ... + +Server communication port 0xe114a3c0 + Handles: 1 References: 1 + The LpcDataInfoChainHead queue is empty + Connected port: 0xe1e7b948 Server connection port: 0xe14ae238 + +Client communication port 0xe1e7b948 + Handles: 1 References: 3 + The LpcDataInfoChainHead queue is empty + +Server connection port e14ae238 Name: ApiPort + Handles: 1 References: 107 + Server process : 84aa0140 (csrss.exe) + Queue semaphore : 84a96da8 + Semaphore state 0 (0x0) + The message queue is empty + The LpcDataInfoChainHead queue is empty +``` + +``` +kd> !lpc scan e13d8830 +Scanning 225 objects + 3 Port: 0xe13d8830 Connection: 0xe141ef50 Communication: 0xe13d8910 ' +80000004 Port: 0xe13d8910 Connection: 0xe141ef50 Communication: 0xe13d8830 ' +Scanning 3 objects +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!lpc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-m--resume-thread-.md b/windows-driver-docs-pr/debugger/-m--resume-thread-.md new file mode 100644 index 0000000000..0aa90f20a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-m--resume-thread-.md @@ -0,0 +1,80 @@ +--- +title: ~m (Resume Thread) +description: The ~m command resumes execution of the specified thread.Do not confuse this command with the m (Move Memory) command. +ms.assetid: fc4eec45-2a28-4571-abf5-3896b77a52c9 +keywords: ["~m (Resume Thread) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~m (Resume Thread) +api_type: +- NA +--- + +# ~m (Resume Thread) + + +The **~m** command resumes execution of the specified thread. + +Do not confuse this command with the [**m (Move Memory)**](m--move-memory-.md) command. + +``` +~Thread m +``` + +## Parameters + + + *Thread* +Specifies the thread or threads to resume. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about the suspend count and how suspended threads behave and for a list of other commands that control the suspending and freezing of threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +Every time that you use the **~m** command, the thread's suspend count is decreased by one. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~m%20%28Resume%20Thread%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mapic.md b/windows-driver-docs-pr/debugger/-mapic.md new file mode 100644 index 0000000000..e39751dfd0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mapic.md @@ -0,0 +1,52 @@ +--- +title: mapic +description: The mapic extension displays an ACPI Multiple APIC table. +ms.assetid: 064f887b-39d1-4251-9043-3c0dc9775bfe +keywords: ["mapic Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mapic +api_type: +- NA +--- + +# !mapic + + +The **!mapic** extension displays an ACPI Multiple APIC table. + +Syntax + +``` +!mapic Address +``` + +## Parameters + + + *Address* +Specifies the address of the Multiple APIC Table. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mapic%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mapped-file.md b/windows-driver-docs-pr/debugger/-mapped-file.md new file mode 100644 index 0000000000..31d40d5ebb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mapped-file.md @@ -0,0 +1,85 @@ +--- +title: mapped_file +description: The mapped_file extension displays the name of the file that backs the file mapping that contains a specified address. +ms.assetid: 1d6d4d14-01ca-47ce-a044-778c9a56e9a5 +keywords: ["mapped_file Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mapped_file +api_type: +- NA +--- + +# !mapped\_file + + +The **!mapped\_file** extension displays the name of the file that backs the file mapping that contains a specified address. + +``` +!mapped_file Address +``` + +## Parameters + + + *Address* +Specifies the address of the file mapping. If *Address* is not in a mapping, the command fails. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Uext.dll

Windows XP and later

Uext.dll

+ +  + +The **!mapped\_file** extension can only be used during live, nonremote debugging. + +### Additional Information + +For more information about file mapping, see [MapViewOfFile](http://go.microsoft.com/fwlink/p/?linkid=123354) in the Windows SDK. + +Remarks +------- + +Here are three examples. The first two addresses used are mapped from a file, and the third is not. + +``` +0:000> !mapped_file 4121ec +Mapped file name for 004121ec: '\Device\HarddiskVolume2\CODE\TimeTest\Debug\TimeTest.exe' + +0:000> !mapped_file 77150000 +Mapped file name for 77150000: '\Device\HarddiskVolume2\Windows\System32\kernel32.dll' + +0:000> !mapped_file 80310000 +No information found for 80310000: error 87 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mapped_file%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mca.md b/windows-driver-docs-pr/debugger/-mca.md new file mode 100644 index 0000000000..5941550489 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mca.md @@ -0,0 +1,638 @@ +--- +title: mca +description: On an x86 target computer, the mca extension displays the machine check architecture (MCA) registers. On an Itanium target computer, the mca extension displays the MCA error record. +ms.assetid: 452bfbf2-fcab-4a71-bfd0-b02afe30df74 +keywords: ["machine check architecture (MCA)", "MCA (machine check architecture)", "mca Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mca +api_type: +- NA +--- + +# !mca + + +On an x86 target computer, the !mca extension displays the machine check architecture (MCA) registers. On an Itanium target computer, the **!mca** extension displays the MCA error record. + +Syntax for x86 target computer + +``` +!mca +``` + +Syntax for Itanium target computer + +``` +!mca Address [Flags] +``` + +## Parameters + + + *Address* +(Itanium target only) Specifies the address of the MCA error record. + + *Flags* +(Itanium target only) Specifies the level of output. *Flags* can be any combination of the following bits. The default value is 0xFF, which displays all sections present in the log. + +Bit 0 (0x1) +Displays the processor section. + +Bit 1 (0x2) +Displays the platform-specific section. + +Bit 2 (0x4) +Displays the memory section. + +Bit 3 (0x8) +Displays the PCI component section. + +Bit 4 (0x10) +Displays the PCI bus section. + +Bit 5 (0x20) +Displays the SystemEvent Log section. + +Bit 6 (0x40) +Displays the platform host controller section. + +Bit 7 (0x80) +Displays to include the platform bus section. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based or Itanium target computer. + +Remarks +------- + +On an Itanium target, **!mca** displays the MCA error record from the system abstraction layer (SAL). Here is an example of the output from this extension: + +``` +kd> !mca e0000165f3f58000 +hal!HalpFeatureBits: 0xf [HAL_PERF_EVENTS|HAL_MCA_PRESENT|HAL_CMC_PRESENT|HAL_CPE_PRESENT] + +MCA Error Record Header @ 0xe0000165f3f58000 0xe0000165f3f597a8 + Id : 8 + Revision : + Revision : 2 + Minor : 0x2 ' + Major : 0 ' + ErrorSeverity : 0 ' + Valid : + Valid : 0 ' + OemPlatformID : 0y0 + Reserved : 0y0000000 (0) + Length : 0x17a8 + TimeStamp : + TimeStamp : 0x20031106`00134944 + Seconds : 0x44 'D' + Minutes : 0x49 'I' + Hours : 0x13 ' + Reserved : 0 ' + Day : 0x6 ' + Month : 0x11 ' + Year : 0x3 ' + Century : 0x20 ' ' + OemPlatformId : [16] "" + + + Severity : ErrorRecoverable + +MCA Error Section Header @ 0xe0000165f3f58028 0xe0000165f3f59578 [Processor] + Header : + Guid : + Data1 : 0xe429faf1 + Data2 : 0x3cb7 + Data3 : 0x11d4 + Data4 : [8] "???" + Revision : + Revision : 2 + Minor : 0x2 ' + Major : 0 ' + RecoveryInfo : + RecoveryInfo : 0 ' + Corrected : 0y0 + NotContained : 0y0 + Reset : 0y0 + Reserved : 0y0000 + Valid : 0y0 + Reserved : 0 ' + Length : 0x1550 + Valid : + Valid : 0x100101f + ErrorMap : 0y1 + StateParameter : 0y1 + CRLid : 0y1 + StaticStruct : 0y1 + CacheCheckNum : 0y0001 + TlbCheckNum : 0y0000 + BusCheckNum : 0y0001 + RegFileCheckNum : 0y0000 + MsCheckNum : 0y0000 + CpuIdInfo : 0y1 + Reserved : 0y000000000000000000000000000000000000000 (0) + ErrorMap : + ErrorMap : 0x1002000 + Cid : 0y0000 + Tid : 0y0000 + Eic : 0y0000 + Edc : 0y0010 + Eit : 0y0000 + Edt : 0y0000 + Ebh : 0y0001 + Erf : 0y0000 + Ems : 0y0000000000000000 (0) + Reserved : 0y0000000000000000 (0) + StateParameter : + StateParameter : 0x28000000`fff21130 + reserved0 : 0y00 + rz : 0y0 + ra : 0y0 + me : 0y1 + mn : 0y1 + sy : 0y0 + co : 0y0 + ci : 0y1 + us : 0y0 + hd : 0y0 + tl : 0y0 + mi : 0y1 + pi : 0y0 + pm : 0y0 + dy : 0y0 + in : 0y0 + rs : 0y1 + cm : 0y0 + ex : 0y0 + cr : 0y1 + pc : 0y1 + dr : 0y1 + tr : 0y1 + rr : 0y1 + ar : 0y1 + br : 0y1 + pr : 0y1 + fp : 0y1 + b1 : 0y1 + b0 : 0y1 + gr : 0y1 + dsize : 0y0000000000000000 (0) + reserved1 : 0y00000000000 (0) + cc : 0y1 + tc : 0y0 + bc : 0y1 + rc : 0y0 + uc : 0y0 + CRLid : + LocalId : 0 + reserved : 0y0000000000000000 (0) + eid : 0y00000000 (0) + id : 0y00000000 (0) + ignored : 0y00000000000000000000000000000000 (0) + + CacheErrorInfo[0]: + + Valid : 1 + CheckInfo : 0y1 + RequestorIdentifier : 0y0 + ResponderIdentifier : 0y0 + TargetIdentifier : 0y0 + PreciseIP : 0y0 + Reserved : 0y00000000000000000000000000000000000000000000000000000000000 (0) + CheckInfo : 0x0 + RequestorId : 0x0 + ResponderId : 0x0 + TargetIp : 0x0 + TargetId : 0x0 + PreciseIp : 0x0 + + CheckInfo: + + CacheCheck : 0 + Operation : 0y0000 + Level : 0y00 + Reserved1 : 0y00 + DataLine : 0y0 + TagLine : 0y0 + DataCache : 0y0 + InstructionCache : 0y0 + MESI : 0y000 + MESIValid : 0y0 + Way : 0y00000 (0) + WayIndexValid : 0y0 + Reserved2 : 0y0000000000 (0) + Index : 0y00000000000000000000 (0) + Reserved3 : 0y00 + InstructionSet : 0y0 + InstructionSetValid : 0y0 + PrivilegeLevel : 0y00 + PrivilegeLevelValid : 0y0 + MachineCheckCorrected : 0y0 + TargetAddressValid : 0y0 + RequestIdValid : 0y0 + ResponderIdValid : 0y0 + PreciseIPValid : 0y0 + + + BusErrorInfo[0]: + + Valid : 9 + CheckInfo : 0y1 + RequestorIdentifier : 0y0 + ResponderIdentifier : 0y0 + TargetIdentifier : 0y1 + PreciseIP : 0y0 + Reserved : 0y00000000000000000000000000000000000000000000000000000000000 (0) + CheckInfo : 0x1080000003000144 + RequestorId : 0x0 + ResponderId : 0x0 + TargetIp : 0x0 + TargetId : 0xd0022004 + PreciseIp : 0x0 + + CheckInfo: + + BusCheck : 0x10800000`03000144 + Size : 0y00100 (0x4) + Internal : 0y0 + External : 0y1 + CacheTransfer : 0y0 + Type : 0y00000001 (0x1) + Severity : 0y00000 (0) + Hierarchy : 0y00 + Reserved1 : 0y0 + Status : 0y00000011 (0x3) + Reserved2 : 0y0000000000000000000000 (0) + InstructionSet : 0y0 + InstructionSetValid : 0y1 + PrivilegeLevel : 0y00 + PrivilegeLevelValid : 0y0 + MachineCheckCorrected : 0y0 + TargetAddressValid : 0y1 + RequestIdValid : 0y0 + ResponderIdValid : 0y0 + PreciseIPValid : 0y0 + + StaticInfo @ 0xe0000165f3f580f0 0xe0000165f3f59578 + + Valid @ 0xe0000165f3f580f0 + + Valid : 0x3f + MinState : 0y1 + BR : 0y1 + CR : 0y1 + AR : 0y1 + RR : 0y1 + FR : 0y1 + Reserved : 0y0000000000000000000000000000000000000000000000000000000000 (0) + + MinState @ 0xe0000165f3f580f8 0xe0000165f3f584f0 + + IntNats : 0 + IntGp : 0xe0000165`f1a99b00 + IntT0 : 0 + IntT1 : 0xe0f0e0f0`e0f0e000 + IntS0 : 0 + IntS1 : 1 + IntS2 : 0xe0000000`83068300 + IntS3 : 0xe0000000`832f8780 + IntV0 : 0x4600 + IntT2 : 0x230 + IntT3 : 0x3ff + IntT4 : 0xe0000165`f38c6000 + IntSp : 0xe0000165`f0f97da0 + IntTeb : 0 + IntT5 : 0 + IntT6 : 0xfffff630 + B0R16 : 0x1010`082a6018 + B0R17 : 0 + B0R18 : 0xe0000000`830067c0 + B0R19 : 0x101 + B0R20 : 0x80000000`00000308 + B0R21 : 0 + B0R22 : 0xe0000000`84bedd20 + B0R23 : 0xe0000000`84bedd20 + B0R24 : 0xe0000165`f213df5a + B0R25 : 0xfff80000`597c84f0 + B0R26 : 0x6081 + B0R27 : 0xfffffe00`00165f20 + B0R28 : 0x8000465 + B0R29 : 0x8000465 + B0R30 : 0x60 + B0R31 : 0xa04`00000000 + IntT7 : 0x44 + IntT8 : 0x200 + IntT9 : 0xe0000165`f38c6000 + IntT10 : 0xe0000165`f3cb81bc + IntT11 : 0xe0000165`f3cb81b8 + IntT12 : 0xe0000000`8363f7b0 + IntT13 : 0xe0000165`f1899d08 + IntT14 : 0x9804c`8a70433f + IntT15 : 0xe0000000`832821f8 + IntT16 : 0xe0000000`836536e0 + IntT17 : 0xe0000000`8363f7b8 + IntT18 : 0xffffffff`fffffbc3 + IntT19 : 0xe0000165`f1ff6000 + IntT20 : 0x2400580 + IntT21 : 0xe0000165`f1ff6004 + IntT22 : 0xe0000165`f3cb8dc0 + Preds : 0x2277 + BrRp : 0xe0000165`ea212df0 + RsRSC : 3 + StIIP : 0xe0000165`f1895370 + StIPSR : 0x1010`082a6018 + StIFS : 0x80000000`00000285 + XIP : 0xe0000165`ea212c50 + XPSR : 0x1010`082a6018 + XFS : 0x80000000`00000b1c + + BR @ 0xe0000165f3f584f8 0xe0000165f3f58530 + +e0000165`f3f584f8 e0000165`ea212df0 USBPORT!USBPORT_StopDevice+0x850 +e0000165`f3f58500 00000000`00000000 +e0000165`f3f58508 00000000`00000000 +e0000165`f3f58510 00000000`00000000 +e0000165`f3f58518 00000000`00000000 +e0000165`f3f58520 00000000`00000000 +e0000165`f3f58528 e0000000`832cb061 nt!NtClose+0x1 +e0000165`f3f58530 e0000165`f1895320 usbohci!OHCI_StopController + + CR @ 0xe0000165f3f58538 0xe0000165f3f58930 + +e0000165`f3f58538 00000000`00007e05 +e0000165`f3f58540 00000154`a7047201 +e0000165`f3f58548 e0000000`83230000 nt!KiVhptTransVector +e0000165`f3f58550 00000000`00000000 +... +e0000165`f3f585c8 00000000`00000000 +e0000165`f3f585d0 e0000165`f1895370 usbohci!OHCI_StopController+0x50 +e0000165`f3f585d8 e0000165`f213df5a +e0000165`f3f585e0 00000000`00000060 +e0000165`f3f585e8 e0000165`f1895360 usbohci!OHCI_StopController+0x40 +e0000165`f3f585f0 80000000`00000285 +... +e0000165`f3f58930 00000000`00000000 + + AR @ 0xe0000165f3f58938 0xe0000165f3f58d30 + +e0000165`f3f58938 00000000`00000000 +e0000165`f3f58940 00000000`00000000 +e0000165`f3f58948 00000000`00000000 +e0000165`f3f58950 00000000`00000000 +e0000165`f3f58958 00000000`00000000 +e0000165`f3f58960 00000000`00000006 +e0000165`f3f58968 e0000000`8301add0 nt!KiMemoryFault +e0000165`f3f58970 00000000`00000000 +e0000165`f3f58978 00000000`00000000 +e0000165`f3f58980 00000000`00000000 +e0000165`f3f58988 00000000`00000000 +e0000165`f3f58990 00000000`00000000 +e0000165`f3f58998 00000000`00000000 +e0000165`f3f589a0 00000000`00000000 +e0000165`f3f589a8 00000000`00000000 +e0000165`f3f589b0 00000000`00000000 +e0000165`f3f589b8 e0000165`f1895370 usbohci!OHCI_StopController+0x50 +e0000165`f3f589c0 e0000165`f0f988e0 +... +e0000165`f3f58d30 00000000`00000000 + + RR @ 0xe0000165f3f58d38 0xe0000165f3f58d70 + +e0000165`f3f58d38 00000000`00000535 +e0000165`f3f58d40 00000000`00000535 +e0000165`f3f58d48 00000000`00000535 +e0000165`f3f58d50 00000000`00000535 +e0000165`f3f58d58 00000000`00000535 +e0000165`f3f58d60 00000000`00000535 +e0000165`f3f58d68 00000000`00000535 +e0000165`f3f58d70 00000000`00000535 + + FR @ 0xe0000165f3f58d78 0xe0000165f3f59570 + +e0000165`f3f58d78 00000000`00000000 +e0000165`f3f58d80 00000000`00000000 +e0000165`f3f58d88 80000000`00000000 +e0000165`f3f58d90 00000000`0000ffff +e0000165`f3f58d98 00000000`00000000 +e0000165`f3f58da0 00000000`00000000 +e0000165`f3f58da8 00000000`00000000 +e0000165`f3f58db0 00000000`00000000 +... +e0000165`f3f59570 00000000`00000000 + + +MCA Error Section Header @ 0xe0000165f3f59578 0xe0000165f3f596a0 [PciComponent] + Header : + Guid : + Data1 : 0xe429faf6 + Data2 : 0x3cb7 + Data3 : 0x11d4 + Data4 : [8] "???" + Revision : + Revision : 2 + Minor : 0x2 ' + Major : 0 ' + RecoveryInfo : + RecoveryInfo : 0x80 ' + Corrected : 0y0 + NotContained : 0y0 + Reset : 0y0 + Reserved : 0y0000 + Valid : 0y1 + Reserved : 0 ' + Length : 0x128 + Valid : + Valid : 0x23 + ErrorStatus : 0y1 + Info : 0y1 + MemoryMappedRegistersPairs : 0y0 + ProgrammedIORegistersPairs : 0y0 + RegistersDataPairs : 0y0 + OemData : 0y1 + Reserved : 0y0000000000000000000000000000000000000000000000000000000000 (0) + ErrorStatus : + Status : 0x121900 + Reserved0 : 0y00000000 (0) + Type : 0y00011001 (0x19) + Address : 0y0 + Control : 0y1 + Data : 0y0 + Responder : 0y0 + Requestor : 0y1 + FirstError : 0y0 + Overflow : 0y0 + Reserved1 : 0y00000000000000000000000000000000000000000 (0) + Info : + VendorId : 0x8086 + DeviceId : 0x100e + ClassCodeInterface : 0 ' + ClassCodeSubClass : 0 ' + ClassCodeBaseClass : 0x2 ' + FunctionNumber : 0 ' + DeviceNumber : 0x3 ' + BusNumber : 0xa0 ' + SegmentNumber : 0 ' + Reserved0 : 0 ' + Reserved1 : 0 + MemoryMappedRegistersPairs : 0 + ProgrammedIORegistersPairs : 0 + + OemData @ 0xe0000165f3f595b8 0xe0000165f3f596a0 + + Data Length = 0xe6 + Data: +e0000165`f3f595ba 00 00 00 00 00 00 91 d3-86 d3 7a 5e 7e 48 a4 0a ..........z^~H.. +e0000165`f3f595ca 2b f6 f7 a6 cc ca 00 ff-ff ff ff ff ff ff 09 00 +............... +e0000165`f3f595da 00 00 00 00 00 00 00 00-00 00 08 00 00 00 86 80 ................ +e0000165`f3f595ea 0e 10 47 01 30 22 08 00-00 00 08 00 00 00 02 00 ..G.0".......... +e0000165`f3f595fa 00 02 20 80 00 00 10 00-00 00 08 00 00 00 00 00 .. ............. +e0000165`f3f5960a 00 d0 00 00 00 00 18 00-00 00 08 00 00 00 81 a0 ................ +e0000165`f3f5961a 00 00 00 00 00 00 20 00-00 00 08 00 00 00 00 00 ...... ......... +e0000165`f3f5962a 00 00 00 00 00 00 28 00-00 00 08 00 00 00 00 00 ......(......... +e0000165`f3f5963a 00 00 3c 10 74 12 30 00-00 00 08 00 00 00 00 00 ..<.t.0......... +e0000165`f3f5964a 00 00 dc 00 00 00 38 00-00 00 08 00 00 00 00 00 ......8......... +e0000165`f3f5965a 00 00 2a 01 ff 00 e4 00-00 00 08 00 00 00 07 f0 ..*............. +e0000165`f3f5966a 1e 00 00 00 40 04 00 00-00 00 00 00 00 00 00 00 ....@........... +e0000165`f3f5967a 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ +e0000165`f3f5968a 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ +e0000165`f3f5969a 00 00 00 00 00 00 ...... + + +MCA Error Section Header @ 0xe0000165f3f596a0 0xe0000165f3f597a8 [PciBus] + Header : + Guid : + Data1 : 0xe429faf4 + Data2 : 0x3cb7 + Data3 : 0x11d4 + Data4 : [8] "???" + Revision : + Revision : 2 + Minor : 0x2 ' + Major : 0 ' + RecoveryInfo : + RecoveryInfo : 0x84 ' + Corrected : 0y0 + NotContained : 0y0 + Reset : 0y1 + Reserved : 0y0000 + Valid : 0y1 + Reserved : 0 ' + Length : 0x108 + Valid : + Valid : 0x74f + ErrorStatus : 0y1 + ErrorType : 0y1 + Id : 0y1 + Address : 0y1 + Data : 0y0 + CmdType : 0y0 + RequestorId : 0y1 + ResponderId : 0y0 + TargetId : 0y1 + OemId : 0y1 + OemData : 0y1 + Reserved : 0y00000000000000000000000000000000000000000000000000000 (0) + ErrorStatus : + Status : 0x121900 + Reserved0 : 0y00000000 (0) + Type : 0y00011001 (0x19) + Address : 0y0 + Control : 0y1 + Data : 0y0 + Responder : 0y0 + Requestor : 0y1 + FirstError : 0y0 + Overflow : 0y0 + Reserved1 : 0y00000000000000000000000000000000000000000 (0) + Type : + Type : 0x4 ' + Reserved : 0 ' + Id : + BusNumber : 0xa0 ' + SegmentNumber : 0 ' + Reserved : [4] "" + Address : 0xd0022054 + Data : 0 + CmdType : 0 + RequestorId : 0xfed2a000 + ResponderId : 0 + TargetId : 0xd0022054 + OemId : [16] ".???" + OemData : + Length : 0x98 + + + +CP M/R/F/A Manufacturer SerialNumber Features Speed + 0 1,5,31,0 GenuineIntel 0000000000000000 0000000000000001 1000 Mhz +``` + +On an x86 target, **!mca** displays the machine check registers supported by the active processor. It also displays basic CPU information (identical to that displayed by [**!cpuinfo**](-cpuinfo.md)). Here is an example of the output from this extension: + +``` +0: kd> !mca +MCE: Enabled, Cycle Address: 0x00000001699f7a00, Type: 0x0000000000000000 + +MCA: Enabled, Banks 5, Control Reg: Supported, Machine Check: None. +Bank Error Control Register Status Register + 0. None 0x000000000000007f 0x0000000000000000 + + 1. None 0x00000000ffffffff 0x0000000000000000 + + 2. None 0x00000000000fffff 0x0000000000000000 + + 3. None 0x0000000000000007 0x0000000000000000 + + 4. None 0x0000000000003fff 0x0000000000000000 + +No register state available. + +CP F/M/S Manufacturer MHz Update Signature Features + 0 15,5,0 SomeBrandName 1394 0000000000000000 a0017fff +``` + +Note that this extension requires private HAL symbols. Without these symbols, the extension will display the message "HalpFeatureBits not found" along with basic CPU information. For example: + +``` +kd> !mca +HalpFeatureBits not found +CP F/M/S Manufacturer MHz Update Signature Features + 0 6,5,1 GenuineIntel 334 0000004000000000 00001fff +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mca%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-memlist.md b/windows-driver-docs-pr/debugger/-memlist.md new file mode 100644 index 0000000000..9c0b9c8564 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-memlist.md @@ -0,0 +1,75 @@ +--- +title: memlist +description: The memlist extension scans physical memory lists from the page frame number (PFN) database in order to check them for consistency. +ms.assetid: 9d5307df-5e46-4d95-8c96-ab6da0f54cd0 +keywords: ["PFN database", "memlist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- memlist +api_type: +- NA +--- + +# !memlist + + +The **!memlist** extension scans physical memory lists from the page frame number (PFN) database in order to check them for consistency. + +``` +!memlist Flags +``` + +## Parameters + + + *Flags* +Specifies which memory lists to verify. At present, only one value has been implemented: + +Bit 0 (0x1) +Causes the zeroed pages list to be verified. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdexts.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +At present, this extension will only check the zeroed pages list to make sure that all pages in that list are zeroed. The appropriate syntax is: + +``` +kd> !memlist 1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!memlist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-memusage.md b/windows-driver-docs-pr/debugger/-memusage.md new file mode 100644 index 0000000000..19182ea339 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-memusage.md @@ -0,0 +1,150 @@ +--- +title: memusage +description: The memusage extension displays summary statistics about physical memory use. +ms.assetid: 32796ada-53ee-465f-b284-db6ee5481878 +keywords: ["memusage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- memusage +api_type: +- NA +--- + +# !memusage + + +The **!memusage** extension displays summary statistics about physical memory use. + +Syntax + +``` +!memusage [Flags] +``` + +## Parameters + + + *Flags* +Can be any one of the following values. The default is 0x0. + +0x0 +Displays general summary information, along with a more detailed description of the pages in the PFN database. See the Remarks section for an example of this type of output. + +0x1 +Displays only summary information about the modified no-write pages in the PFN database.. + +0x2 +Displays only detailed information about the modified no-write pages in the PFN database. + +0x8 +Displays only general summary information about memory use. + +### Environment + +| | | +|-------|------------------| +| Modes | kernel mode only | + +  + +### DLL + +Kdexts.dll + +### Additional Information + +Physical memory statistics are collected from the Memory Manager's page frame number (PFN) database table. + +This command takes a long time to run, especially if the target computer is running in 64-bit mode, due to the greater amount of data to obtain. While it is loading the PFN database, a counter shows its progress. To speed up this loading, increase the COM port speed with the [**CTRL+A (Toggle Baud Rate)**](ctrl-a--toggle-baud-rate-.md) key, or use the [**.cache (Set Cache Size)**](-cache--set-cache-size-.md) command to increase the cache size (perhaps to around 10 MB). + +The **!memusage** command can also be used while performing [local kernel debugging](performing-local-kernel-debugging.md). + +Here is an example of the output from this extension: + +``` +kd> !memusage + loading PFN database +loading (98% complete) + +Compiling memory usage data (100% Complete). + Zeroed: 49 ( 196 kb) + Free: 5 ( 20 kb) + Standby: 5489 ( 21956 kb) + Modified: 714 ( 2856 kb) + ModifiedNoWrite: 1 ( 4 kb) + Active/Valid: 10119 ( 40476 kb) + Transition: 6 ( 24 kb) + Unknown: 0 ( 0 kb) + TOTAL: 16383 ( 65532 kb) + + Building kernel map + Finished building kernel map +Scanning PFN database - (99% complete) + + Usage Summary (in Kb): + + +Control Valid Standby Dirty Shared Locked PageTables name + +8251a258 12 108 0 0 0 0 mapped_file( cscui.dll ) +827ab1b8 8 1708 0 0 0 0 mapped_file( $Mft ) +8263c408 908 48 0 0 0 0 mapped_file( win32k.sys ) +8252dda8 0 324 0 0 0 0 mapped_file( ShellIconCache ) +8272f638 128 112 0 116 0 0 mapped_file( advapi32.dll ) +...... +82755958 0 4 0 0 0 0 mapped_file( $Directory ) +8250b518 0 4 0 0 0 0 No Name for File +8254d8d8 0 4 0 0 0 0 mapped_file( $Directory ) +82537be8 0 4 0 0 0 0 mapped_file( Windows Explorer.lnk ) + +-------- 1348 0 0 ----- ----- 904 process ( System ) +-------- 492 0 0 ----- ----- 72 process ( winmine.exe ) +-------- 3364 1384 1396 ----- ----- 188 process ( explorer.exe ) +-------- 972 0 0 ----- ----- 88 process ( services.exe ) +-------- 496 1456 384 ----- ----- 164 process ( winmgmt.exe ) +-------- 1144 0 0 ----- ----- 120 process ( svchost.exe ) +-------- 944 0 0 ----- ----- 156 process ( winlogon.exe ) +-------- 412 0 0 ----- ----- 64 process ( csrss.exe ) +...... +-------- 12 0 0 ----- ----- 8 process ( wmiadap.exe ) + +-------- 316 0 0 ----- ----- 0 pagefile section (346e) +-------- 4096 0 0 ----- ----- 0 pagefile section (9ad) + +-------- 884 280 36 ----- 0 ----- driver ( ntoskrnl.exe ) +-------- 88 8 0 ----- 0 ----- driver ( hal.dll ) +-------- 8 0 0 ----- 0 ----- driver ( kdcom.dll ) +-------- 12 0 0 ----- 0 ----- driver ( BOOTVID.dll ) +...... +-------- 8 0 0 ----- 0 ----- driver ( ndisuio.sys ) +-------- 16 0 0 ----- 0 ----- driver ( dump_scsiport.sys ) +-------- 56 0 0 ----- 0 ----- driver ( dump_aic78xx.sys ) +-------- 2756 1060 876 ----- 0 ----- driver ( Paged Pool ) +-------- 1936 128 148 ----- 0 ----- driver ( Kernel Stacks ) +-------- 0 0 0 ----- 0 ----- driver ( NonPaged Pool ) +``` + +The first column displays the address of the control area structure that describes each mapped structure. Use the [**!ca**](-ca.md) extension command to display these control areas. + +Remarks +------- + +You can use the [**!vm**](-vm.md) extension command to analyze virtual memory use. This extension is typically more useful than **!memusage**. For more information about memory management, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +The [**!pfn**](-pfn.md) extension command can be used to display a particular page frame entry in the PFN database. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!memusage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-adapter.md b/windows-driver-docs-pr/debugger/-minipkd-adapter.md new file mode 100644 index 0000000000..4afd8b6ee4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-adapter.md @@ -0,0 +1,72 @@ +--- +title: minipkd.adapter +description: The minipkd.adapter extension displays information about the specified adapter. +ms.assetid: 86cde6f0-9690-41b6-8e81-b9d25d7d6de5 +keywords: ["minipkd.adapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.adapter +api_type: +- NA +--- + +# !minipkd.adapter + + +The **!minipkd.adapter** extension displays information about the specified adapter. + +``` +!minipkd.adapter Address +``` + +## Parameters + + + *Address* +Specifies the address of an adapter. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +The address of of an adapter can be found in the **DevExt** field of the [**!minipkd.adapters**](-minipkd-adapters.md) display. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.adapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-adapters.md b/windows-driver-docs-pr/debugger/-minipkd-adapters.md new file mode 100644 index 0000000000..d1f24a5146 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-adapters.md @@ -0,0 +1,134 @@ +--- +title: minipkd.adapters +description: The minipkd.adapters extension displays all of the adapters that work with the SCSI Port driver that have been identified in the system, and the individual devices associated with each adapter. +ms.assetid: 8571b9ec-1ec9-4adb-8a65-5306e45c3aa6 +keywords: ["minipkd.adapters Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.adapters +api_type: +- NA +--- + +# !minipkd.adapters + + +The **!minipkd.adapters** extension displays all of the adapters that work with the SCSI Port driver that have been identified in the system, and the individual devices associated with each adapter. + +``` +!minipkd.adapters +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +The display includes the driver name, the device object address, and the device extension address for each adapter. The display for each adapter also includes a list of each device on the adapter. The display for each device includes the device extension address, the SCSI address, the device object address, and some flags for the device. Information about the Plug and Play state and the power state is also included. + +The flags in the display are explained in the following table: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning

c

Claimed. Indicates that the device has a driver on it.

m

Missing. Indicates that the device was present on the bus in a prior scan but was not present during the latest scan.

e

Enumerated. Indicates that the device has been reported to the Plug and Play manager.

v

Visible. Indicates that the device has been enumerated by the system. This flag is more significant when it is not present for a device.

p

Paging. Indicates that the device is in the paging path.

d

Dump. Indicates that the device is in the crash dump path and will be used for a crash dump.

h

Hibernate. Indicates that the device is hibernating.

+ +  + +Here is an example of the **!minipkd.adapters** display: + +``` +0: kd> !minipkd.adapters +Adapter \Driver\lp6nds35 DO 86334a70 DevExt 86334b28 +Adapter \Driver\adpu160m DO 8633da70 DevExt 8633db28 + LUN 862e60f8 @(0,0,0) c ev pnp(00/ff) pow(0,0) DevObj 862e6040 + LUN 863530f8 @(0,1,0) c ev p d pnp(00/ff) pow(0,0) DevObj 86353040 + LUN 862e50f8 @(0,2,0) c ev pnp(00/ff) pow(0,0) DevObj 862e5040 + LUN 863520f8 @(0,6,0) ev pnp(00/ff) pow(0,0) DevObj 86352040 +Adapter \Driver\adpu160m DO 86376040 DevExt 863760f8 +``` + +An error message similar to the following indicates that either the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols, or that Windows has not identified any adapters that work with the SCSI Port driver. + +``` +minipkd error (0) ... \minipkd\minipkd.c @ line 435 +``` + +If the [**!minipkd.help**](-minipkd-help.md) extension command returns help information successfully, the SCSI Port symbols are correct. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.adapters%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-exports.md b/windows-driver-docs-pr/debugger/-minipkd-exports.md new file mode 100644 index 0000000000..d5d72e1b37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-exports.md @@ -0,0 +1,67 @@ +--- +title: minipkd.exports +description: The minipkd.exports extension displays the addresses of the miniport exports for the specified adapter. +ms.assetid: 7d92539c-26b5-4cab-84df-b643612a98d0 +keywords: ["minipkd.exports Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.exports +api_type: +- NA +--- + +# !minipkd.exports + + +The **!minipkd.exports** extension displays the addresses of the miniport exports for the specified adapter. + +``` +!minipkd.exports Adapter +``` + +## Parameters + + + *Adapter* +Specifies the address of an adapter. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.exports%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-help.md b/windows-driver-docs-pr/debugger/-minipkd-help.md new file mode 100644 index 0000000000..651d9b5b29 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-help.md @@ -0,0 +1,72 @@ +--- +title: minipkd.help +description: The minipkd.help extension displays help text for the Minipkd.dll extension commands. +ms.assetid: 5629aec8-8c9d-4ed0-91fb-c8d020f78405 +keywords: ["minipkd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.help +api_type: +- NA +--- + +# !minipkd.help + + +The **!minipkd.help** extension displays help text for the Minipkd.dll extension commands. + +``` +!minipkd.help +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +If an error message similar to the following appears, it indicates that the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols. + +``` +minipkd error (0) ... \minipkd\minipkd.c @ line 435 +``` + +Use the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command to display the current path and change the path. Use the [**.reload (Reload Module)**](-reload--reload-module-.md) command to reload symbols from the current path. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-lun.md b/windows-driver-docs-pr/debugger/-minipkd-lun.md new file mode 100644 index 0000000000..21e4cdaaae --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-lun.md @@ -0,0 +1,78 @@ +--- +title: minipkd.lun +description: The minipkd.lun extension displays detailed information about the specified Logical Unit Extension (LUN). +ms.assetid: f78b2c15-ecfc-4138-b595-a6e3f0f7f93c +keywords: ["minipkd.lun Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.lun +api_type: +- NA +--- + +# !minipkd.lun + + +The **!minipkd.lun** extension displays detailed information about the specified Logical Unit Extension (LUN). + +``` +!minipkd.lun LUN +!minipkd.lun Device +``` + +## Parameters + + + *LUN* +Specifies the address of the LUN. + + *Device* +Specifies the physical device object (PDO) for the LUN. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +A LUN is typically referred to as a *device*. Thus, this extension displays information about a device on an adapter. + +The LUN can be specified either by its address (which can be found in the **LUN** field of the [**!minipkd.adapters**](-minipkd-adapters.md) display), or by its physical device object (which can be found in the **DevObj** field of the **!minipkd.adapters** display). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.lun%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-portconfig.md b/windows-driver-docs-pr/debugger/-minipkd-portconfig.md new file mode 100644 index 0000000000..9544206be9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-portconfig.md @@ -0,0 +1,72 @@ +--- +title: minipkd.portconfig +description: The minipkd.portconfig extension displays information about the specified PORT_CONFIGURATION_INFORMATION data structure. +ms.assetid: efc527c4-0340-4976-9126-d3e32286fc64 +keywords: ["minipkd.portconfig Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.portconfig +api_type: +- NA +--- + +# !minipkd.portconfig + + +The **!minipkd.portconfig** extension displays information about the specified PORT\_CONFIGURATION\_INFORMATION data structure. + +``` +!minipkd.portconfig PortConfig +``` + +## Parameters + + + *PortConfig* +Specifies the address of a PORT\_CONFIGURATION\_INFORMATION data structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +The *PortConfig* address can be found in the **Port Config Info** field of the [**!minipkd.adapter**](-minipkd-adapter.md) display. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.portconfig%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-req.md b/windows-driver-docs-pr/debugger/-minipkd-req.md new file mode 100644 index 0000000000..1bc15d8944 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-req.md @@ -0,0 +1,76 @@ +--- +title: minipkd.req +description: The minipkd.req extension displays information about all of the currently active requests on the specified adapter or device. +ms.assetid: 5edc00dd-9a0b-4576-a3ec-11ce22163e95 +keywords: ["minipkd.req Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.req +api_type: +- NA +--- + +# !minipkd.req + + +The **!minipkd.req** extension displays information about all of the currently active requests on the specified adapter or device. + +``` +!minipkd.req Adapter +!minipkd.req Device +``` + +## Parameters + + + *Adapter* +Specifies the address of the adapter. + + *Device* +Specifies the physical device object (PDO) for the Logical Unit Extension (LUN) device. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +The PDO for a LUN can be found in the **DevObj** field of the [**!minipkd.adapters**](-minipkd-adapters.md) display. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.req%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-minipkd-srb.md b/windows-driver-docs-pr/debugger/-minipkd-srb.md new file mode 100644 index 0000000000..7651f0c260 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-minipkd-srb.md @@ -0,0 +1,74 @@ +--- +title: minipkd.srb +description: The minipkd.srb extension displays the specified SCSI request block (SRB) data structure. +ms.assetid: d742a900-f8a8-43a8-b00a-12bb82ca1460 +keywords: ["minipkd.srb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- minipkd.srb +api_type: +- NA +--- + +# !minipkd.srb + + +The **!minipkd.srb** extension displays the specified SCSI request block (SRB) data structure. + +``` +!minipkd.srb SRB +``` + +## Parameters + + + *SRB* +Specifies the address of an SRB. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Minipkd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +The addresses of all currently active requests can be found in the *SRB* fields of the output from the [**!minipkd.req**](-minipkd-req.md) command. + +This extension displays the status of the SRB, the driver it is addressed to, the SCSI that issued the SRB and its address, and a hexadecimal flag value. If 0x10000 is set in the flag value, this request is currently in the miniport. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!minipkd.srb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mps.md b/windows-driver-docs-pr/debugger/-mps.md new file mode 100644 index 0000000000..cbe5e46bf5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mps.md @@ -0,0 +1,69 @@ +--- +title: mps +description: The mps extension displays BIOS information for the Intel Multiprocessor Specification (MPS) of the target computer. +ms.assetid: b6ee2eac-ef3c-403a-83ca-fe45506a8c4e +keywords: ["mps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mps +api_type: +- NA +--- + +# !mps + + +The **!mps** extension displays BIOS information for the Intel Multiprocessor Specification (MPS) of the target computer. + +``` +!mps [Address] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the MPS table in the BIOS. If this is omitted, the information is obtained from the HAL. This will require HAL symbols. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +### Additional Information + +For more information about BIOS debugging, see [Debugging BIOS Code](debugging-bios-code.md). For more information about the MPS, refer to the appropriate version of the Intel MultiProcessor Specification. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mtrr.md b/windows-driver-docs-pr/debugger/-mtrr.md new file mode 100644 index 0000000000..9515975358 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mtrr.md @@ -0,0 +1,62 @@ +--- +title: mtrr +description: The mtrr extension displays the contents of the MTRR register. +ms.assetid: 6dbaaf48-1434-41aa-a00f-f85112353bbe +keywords: ["MTRR register", "registers, MTRR register", "mtrr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mtrr +api_type: +- NA +--- + +# !mtrr + + +The **!mtrr** extension displays the contents of the MTRR register. + +``` +!mtrr +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mtrr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-mui.md b/windows-driver-docs-pr/debugger/-mui.md new file mode 100644 index 0000000000..7bb191053d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-mui.md @@ -0,0 +1,103 @@ +--- +title: mui +description: The mui extension displays the Multilingual User Interface (MUI) cache information. The implementation of MUI was improved in Windows Vista. +ms.assetid: f485450f-0dd2-4f1c-85fe-dbf272c2dbae +keywords: ["multi-language user interface", "mui Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- mui +api_type: +- NA +--- + +# !mui + + +The **!mui** extension displays the Multilingual User Interface (MUI) cache information. The implementation of MUI was improved in Windows Vista. As a result, the behavior of this extension on earlier implementations is undefined. + +``` +!mui -c +!mui -s +!mui -r ModuleAddress +!mui -i +!mui -f +!mui -t +!mui -u +!mui -d ModuleAddress +!mui -e ModuleAddress +!mui -? +``` + +## Parameters + + + **-c** +Causes the output to include the language identifier (ID), a pointer to the module, a pointer to the resource configuration data, and a pointer to the associated MUI DLL for each module. + + **-s** +(Kernel Mode Only) Causes the display to include the full file paths for the module and associated MUI DLL for each module. + + **-r** **** *ModuleAddress* +Causes the resource configuration data for the module at *ModuleAddress* to be displayed. This includes the file type, the checksum value, and the resource types. + + **-i** +Causes the output to include the installed and licensed MUI languages and their associated information. + + **-f** +Causes the output to include the loader merged language fallback list. + + **-t** +Causes the output to include the thread preference language. + + **-u** +Causes the output to include the current thread user UI language setting. + + **-d** **** *ModuleAddress* +Causes the output to include contained resources for the module at *ModuleAddress*. + + **-e** **** *ModuleAddress* +Causes the output to include contained resource types for the module at *ModuleAddress*. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows XP

Unavailable

Windows Vista and later

Exts.dll

+ +  + +### Additional Information + +For information about MUI and resource configuration data format, see the Microsoft Windows SDK documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!mui%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-n--suspend-thread-.md b/windows-driver-docs-pr/debugger/-n--suspend-thread-.md new file mode 100644 index 0000000000..4425c5db63 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-n--suspend-thread-.md @@ -0,0 +1,82 @@ +--- +title: ~n (Suspend Thread) +description: The ~n command suspends execution of the specified thread.Do not confuse this command with the n (Set Number Base) command. +ms.assetid: 4b1063ad-edba-4cd3-9084-dc6c08c69f55 +keywords: ["~n (Suspend Thread) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~n (Suspend Thread) +api_type: +- NA +--- + +# ~n (Suspend Thread) + + +The **~n** command suspends execution of the specified thread. + +Do not confuse this command with the [**n (Set Number Base)**](n--set-number-base-.md) command. + +``` +~Thread n +``` + +## Parameters + + + *Thread* +Specifies the thread or threads to suspend. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about the suspend count and how suspended threads behave and for a list of other commands that control the suspending and freezing of threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +Every time that you use the **~n** command, the thread's suspend count is increased by one. + +The thread's start address is displayed when you use this command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~n%20%28Suspend%20Thread%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-af.md b/windows-driver-docs-pr/debugger/-ndiskd-af.md new file mode 100644 index 0000000000..aa53503615 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-af.md @@ -0,0 +1,140 @@ +--- +title: ndiskd.af +description: The ndiskd.af extension displays a Connection-Oriented NDIS (CoNDIS) address family (AF). +ms.assetid: 737AB46E-DFAA-42D6-A9BD-B7223167D0DD +keywords: ["ndiskd.af Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.af +api_type: +- NA +--- + +# !ndiskd.af + + +The **!ndiskd.af** extension displays a Connection-Oriented NDIS (CoNDIS) address family (AF). + +``` +!ndiskd.af [-handle ] +``` + +## Parameters + + + *-handle* +Required. Handle of a CoNDIS address family. + +### DLL + +Ndiskd.dll + +Remarks +------- + +For more information about CoNDIS, see [Connection-Oriented NDIS](https://msdn.microsoft.com/windows/hardware/drivers/network/connection-oriented-ndis). + +For more information about CoNDIS address families, see [Address Families](https://msdn.microsoft.com/windows/hardware/drivers/network/address-families). + +Examples +-------- + +CoNDIS is used in certain situations such as connecting to a VPN, so running **!ndiskd.af** will not show you results unless a miniport driver on your system has created and activated a CoNDIS virtual connection. The following example shows results from a machine that is connected to a VPN network. First, run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension with no parameters to see a list of miniports and miniport drivers on the system. In the following output, look for the miniport driver for the Marvell AVASTAR Wireless-AC Network Controller network adapter. Its handle is ffffc804af2e3710. + +``` +1: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffc804af2e3710 ffffc804b9e6f1a0 Marvell AVASTAR Wireless-AC Network Controller + ffffc804b99b9020 ffffc804b9c301a0 WAN Miniport (Network Monitor) + ffffc804b99b9020 ffffc804b9c2a1a0 WAN Miniport (IPv6) + ffffc804b99b9020 ffffc804b8a8a1a0 WAN Miniport (IP) + ffffc804ae9d7020 ffffc804b9ceb1a0 WAN Miniport (PPPOE) + ffffc804b9ca5900 ffffc804b9e601a0 WAN Miniport (PPTP) + ffffc804b99dc720 ffffc804b99b01a0 WAN Miniport (L2TP) + ffffc804b86581b0 ffffc804b9c6c1a0 WAN Miniport (IKEv2) + ffffc804ad4a7250 ffffc804b99651a0 WAN Miniport (SSTP) + ffffc804b11c4020 ffffc804b85821a0 Microsoft ISATAP Adapter + ffffc804b11c4020 ffffc804b71731a0 Microsoft ISATAP Adapter #2 + ffffc804ad725020 ffffc804b05e71a0 Surface Ethernet Adapter #2 + ffffc804b0bf0020 ffffc804b0c011a0 Bluetooth Device (Personal Area Network) + ffffc804aef695e0 ffffc804aed331a0 TAP-Windows Adapter V9 +``` + +Next, enter the **!ndiskd.af** command with the miniport driver's handle to see the address family for this miniport driver, which is acting as a connection-oriented client. + +``` +1: kd> !ndiskd.af ffffc804af2e3710 + + +ADDRESS FAMILY + + Ndis handle ffffc804af2e3710 + Flags [Unrecognized flags 399b9020] AF_CLOSING + References ffffc804 + Close Requested? 0 + + Miniport 0 - [Unreadable NetAdapter] + + Call Manager ffffc804b90a4ac0 - [Invalid Open] + Call Manager Context 007a0078 + + Client 00060000 - [Unreadable Open] + Client Context ffffc804af2e3888 + + +CLIENT HANDLERS + + Client Handler Function pointer Symbol (if available) + ClCreateVcHandler fffff80965fd5888 mrvlpcie8897!Globals+8 + ClDeleteVcHandler [None] + ClRequestHandler ffffc804af96fd78 + ClRequestCompleteHandler ffffc804af96fd78 + ClOpenAfCompleteHandler [None] + ClCloseAfCompleteHandler [None] + ClRegisterSapCompleteHandler 000132060098028a + ClDeregisterSapCompleteHandler [None] + ClMakeCallCompleteHandler fffff80965ff9ec0 wdiwifi!MPWrapperSetOptions + ClCloseCallCompleteHandler fffff80965ff9c70 wdiwifi!MPWrapperHalt + ClModifyCallQoSCompleteHandler fffff80965ff9b50 wdiwifi!MPWrapperInitializeEx + ClAddPartyCompleteHandler fffff80965e71a08 mrvlpcie8897!MPUnload + ClDropPartyCompleteHandler fffff80965ffa070 wdiwifi!MPWrapperPause + ClIncomingDropPartyHandler fffff80965ffaa20 wdiwifi!MPWrapperReturnNetBufferLists + ClIncomingCallHandler fffff80965ffa1e0 wdiwifi!MPWrapperRestart + ClCallConnectedHandler fffff80965ffaad0 wdiwifi!MPWrapperCancelSendNetBufferLists + ClIncomingCloseCallHandler fffff80965ffa870 wdiwifi!MPWrapperSendNetBufferLists + ClIncomingCallQoSChangeHandler fffff80965ffa610 wdiwifi!MPWrapperOidRequest +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Connection-Oriented NDIS](https://msdn.microsoft.com/windows/hardware/drivers/network/connection-oriented-ndis) + +[Address Families](https://msdn.microsoft.com/windows/hardware/drivers/network/address-families) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.af%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-compartments.md b/windows-driver-docs-pr/debugger/-ndiskd-compartments.md new file mode 100644 index 0000000000..9fb3ff5ec5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-compartments.md @@ -0,0 +1,81 @@ +--- +title: ndiskd.compartments +description: The ndiskd.compartments extension displays all network compartments. +ms.assetid: F9BF319D-77E9-4D12-84E9-655058F57AC4 +keywords: ["ndiskd.compartments Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.compartments +api_type: +- NA +--- + +# !ndiskd.compartments + + +The **!ndiskd.compartments** extension displays all network compartments. + +``` +!ndiskd.compartments +``` + +## Parameters + + +This extension has no parameters. + +### DLL + +Ndiskd.dll + +Remarks +------- + +Compartments are a way that NDIS manages interfaces. Third party interface providers only use the primary compartment, as described in the **CompartmentId** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure. + +Examples +-------- + +Run the **!ndiskd.compartments** extension to see a list of all network compartments. In this example, there is only one compartment (the primary one). + +``` +3: kd> !ndiskd.compartments + Compartment ffffdf80139b9940 + ID 1 + Loopback Network ffffdf80139b8900 + Loopback Interface ffffdf80139b6a20 + Networks: + ffffdf80139b8900 [Unnamed network] +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.compartments%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-cxadapter.md b/windows-driver-docs-pr/debugger/-ndiskd-cxadapter.md new file mode 100644 index 0000000000..703831cd65 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-cxadapter.md @@ -0,0 +1,217 @@ +--- +title: ndiskd.cxadapter +description: The ndiskd.cxadapter extension displays information about a NETADAPTER object. +ms.assetid: 5BE91B1C-9795-4E2C-834A-B7424FF1FCDB +keywords: ["ndiskd.cxadapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.cxadapter +api_type: +- NA +--- + +# !ndiskd.cxadapter + + +The **!ndiskd.cxadapter** extension displays information about a NETADAPTER object. + +For more information about the Network Adapter WDF Class Extension (NetAdapterCx), see [Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx). + +``` +!ndiskd.cxadapter [-handle ] [-basic] [-power] [-datapath] +``` + +## Parameters + + + *-handle* +Required. Handle of a NETADAPTER. + + *-basic* +Displays basic information. + + *-power* +Displays information about the NETPOWERSETTINGS object of the NETADAPTER. + + *-datapath* +Displays information about the datapath queues. + +### DLL + +Ndiskd.dll + +Examples +-------- + +To obtain a handle for a NETADAPTER object, first run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) command to see a list of all NIC drivers and NetAdapters on the system. In the following example, look for the handle for the NetAdapter named Realtek PCIe GBE Family Controller NetAdapter Sample Driver \#2. Its handle is ffffd1022d048030. + +``` +0: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffd1022e8ecae0 ffffd1022d048030 Realtek PCIe GBE Family Controller NetAdapter Sample Driver #2 + ffffd1022ed908e0 ffffd1022e8611a0 Microsoft Kernel Debug Network Adapter +``` + +By clicking on this NetAdapter's handle or by entering the **!ndiskd.netadapter -handle** command with its handle on the command line, you can see details for this NetAdapter, including its NETADAPTER object. The Realtek PCIe GBE Family Controller NetAdapter Sample Driver \#2's NETADAPTER handle is 00002efdd0e5f988. + +``` +0: kd> !ndiskd.netadapter ffffd1022d048030 + + +NETADAPTER + + Realtek PCIe GBE Family Controller NetAdapter Sample Driver #2 + + Ndis handle ffffd1022d048030 + NETADAPTER 00002efdd0e5f988 More information + WDFDEVICE 00002efdcf45f2f8 + Driver ffffd1022e8ecae0 - RtEthSample v0.0 + Network interface ffffd1022e395a20 + + Media type 802.3 + Device instance PCI\VEN_10EC&DEV_8168&SUBSYS_816810EC&REV_03\4&22bb23f1&0&0038 + Device object ffffd1022de127f0 More information + MAC address 00-e0-4c-68-00-8b + + +STATE + + Miniport Running + Device PnP Started Show state history + Datapath Normal + Interface Up + Media Connected + Power D0 + References 0n10 Show detail + Total resets 0 + Pending OID None + Flags NOT_BUS_MASTER, WDF, DEFAULT_PORT_ACTIVATED, + SUPPORTS_MEDIA_SENSE, DOES_NOT_DO_LOOPBACK, + MEDIA_CONNECTED + PnP flags PM_SUPPORTED, DEVICE_POWER_ENABLED, + DEVICE_POWER_WAKE_ENABLE, HARDWARE_DEVICE, + NDIS_WDM_DRIVER, WAKE_CAPABLE + + +IP ADDRESS SUMMARY + + 10.137.188.169 See all IP addresses on this adapter + fe80::3cad:81bb:5dad:1066 + + +BINDINGS + + Protocol list Driver Open Context + MSLLDP ffffd1023043f6a0 ffffd1022e786a90 ffffd102307465c0 + LLTDIO ffffd1022c6b7830 ffffd1022ef8cc00 ffffd1022f1e5730 + TCPIP6 ffffd1022e2c7c10 ffffd10230b98310 ffffd102304d9010 + (RASPPPOE) Not running + (RDMANDK) ffffd1022d574a70 Declined with NDIS_STATUS_NOT_RECOGNIZED + RSPNDR ffffd1022c71a830 ffffd1022de0cc00 ffffd1022d03f6a0 + TCPIP ffffd1022e2cbc10 ffffd1022de067f0 ffffd1022d03f010 + NDISUIO ffffd1022de07670 ffffd1022cd648d0 ffffd10231131970 + + Filter list Driver Module Context + WFP 802.3 MAC Layer LightWeight Filter-0000 + ffffd1022e384d70 ffffd1022f271660 ffffd10230cfe2c0 + QoS Packet Scheduler-0000 + ffffd1022d56f220 ffffd1022f26d660 ffffd10231778700 + WFP Native MAC Layer LightWeight Filter-0000 + ffffd1022e384ad0 ffffd1022f26b660 ffffd1022ed59c20 + + + +MORE INFORMATION + + Driver handlers Task offloads + Power management PM protocol offloads + Pending OIDs + Pending NBLs Receive side throttling + Wake-on-LAN (WoL) Packet filter + Receive queues Receive filtering + RSS NIC switch + Selective suspend + NDIS ports WMI guids + Diagnostic log +``` + +Because the NETADAPTER object is a WDF object, clicking its handle will cause the debugger to run the [**!wdfkd.wdfhandle**](-wdfkd-wdfhandle.md) command which will give you more information about it from a WDF perspective. To see more detailed information about the NETADAPTER from a networking perspective, click the "More Information" link to the right of the NETADAPTER's handle to run the **!ndiskd.cxadapter** command with its handle. + +``` +0: kd> !ndiskd.cxadapter ffffd1022f1a0720 + + +NETADAPTER + + Miniport ffffd1022d048030 - Realtek PCIe GBE Family Controller NetAdapter Sample Driver #2 + NETADAPTER 00002efdd0e5f988 + WDFDEVICE 00002efdcf45f2f8 + + Event Callbacks Function pointer Symbol (if available) + EvtAdapterSetCapabilities fffff800341519ac RtEthSample+19ac + EvtAdapterCreateTxQueue fffff80034151508 RtEthSample+1508 + EvtAdapterCreateRxQueue fffff800341510ec RtEthSample+10ec + + Show datapath info + Show NETPOWERSETTINGS info +``` + +You can also combine this command other parameters such as *-datapath* to see more information for this NETADAPTER. + +``` +0: kd> !ndiskd.cxadapter ffffd1022f1a0720 -basic -datapath + + +NETADAPTER + + Miniport ffffd1022d048030 - Realtek PCIe GBE Family Controller NetAdapter Sample Driver #2 + NETADAPTER 00002efdd0e5f988 + WDFDEVICE 00002efdcf45f2f8 + + Event Callbacks Function pointer Symbol (if available) + EvtAdapterSetCapabilities fffff800341519ac RtEthSample+19ac + EvtAdapterCreateTxQueue fffff80034151508 RtEthSample+1508 + EvtAdapterCreateRxQueue fffff800341510ec RtEthSample+10ec + + +DATAPATH QUEUES + + NETTXQUEUE ffffd1022f512700 + NETRXQUEUE ffffd1022cc7b0d0 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!wdfkd.wdfhandle**](-wdfkd-wdfhandle.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.cxadapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-dbglevel.md b/windows-driver-docs-pr/debugger/-ndiskd-dbglevel.md new file mode 100644 index 0000000000..1e30198861 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-dbglevel.md @@ -0,0 +1,115 @@ +--- +title: ndiskd.dbglevel +description: The ndiskd.dbglevel extension displays and optionally changes the current NDIS debug level. Warning: ndiskd.dbglevel has been superceded by WPP and Driver Verifier. +ms.assetid: D134FD03-DABA-4558-A5C3-C365F77BD69A +keywords: ["ndiskd.dbglevel Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.dbglevel +api_type: +- NA +--- + +# !ndiskd.dbglevel + + +The **!ndiskd.dbglevel** extension displays and optionally changes the current NDIS debug level. + +**Warning**   +**!ndiskd.dbglevel** has been superceded by WPP (Windows software trace preprocessor) and Driver Verifier. !ndiskd will give you the following warning if your target system does not support **!ndiskd.dbglevel**. + +``` +0: kd> !ndiskd.dbglevel + This target does not support tracing through !ndiskd.dbglevel or + !ndiskd.dbgsystems. + Learn how to collect traces with WPP +``` + +If you click on the link at the bottom of the warning, !ndiskd will give you more information. + +``` +0: kd> !ndiskd.help wpptracing + WPP traces are fast, flexible, and detailed. Plus, starting with Windows 8 + and Windows Server 2012, you can automatically decode NDIS traces using the + symbol file. Just point TraceView (or tracepdb.exe) at NDIS.PDB, and it + will be able to get all the TMFs it needs to trace NDIS activity. + + If you would like traces to be printed in the debugger window, you use the + !wmitrace extension. For example, you might enable traces with this: + + !wmitrace.searchpath c:\path\to\TMF\files + !wmitrace.start ndis -kd + !wmitrace.enable ndis {DD7A21E6-A651-46D4-B7C2-66543067B869} -level 4 -flag 0x31f3 +``` + +  + +For more information about WPP, see [WPP Software Tracing](https://msdn.microsoft.com/windows/hardware/drivers/devtest/wpp-software-tracing). + +For more information about Driver Verifier, see [Driver Verifier](https://msdn.microsoft.com/windows/hardware/drivers/devtest/driver-verifier). + +For more information about WMI tracing, see [WMI Tracing Extensions (Wmitrace.dll)](https://msdn.microsoft.com/library/windows/hardware/ff561362). + +``` +!ndiskd.dbglevel [-level ] +``` + +## Parameters + + + *-level* +The level of debugging verbosity. Possible values are: + +- NONE - disables debug tracing +- FATAL - enables fatal errors to be printed +- ERROR - enables errors to be printed +- WARN - enables warnings to be printed +- INFO - enables informational messages to be printed +- VERBOSE - enables all debug traces to be printed + +### DLL + +Ndiskd.dll + +Remarks +------- + +This extension applies to checked NDIS.sys only. To check the build info of NDIS.sys, run the [**!ndiskd.ndis**](-ndiskd-ndis.md) extension. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.ndis**](-ndiskd-ndis.md) + +[WPP Software Tracing](https://msdn.microsoft.com/windows/hardware/drivers/devtest/wpp-software-tracing) + +[Driver Verifier](https://msdn.microsoft.com/windows/hardware/drivers/devtest/driver-verifier) + +[WMI Tracing Extensions (Wmitrace.dll)](https://msdn.microsoft.com/library/windows/hardware/ff561362) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.dbglevel%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-dbgsystems.md b/windows-driver-docs-pr/debugger/-ndiskd-dbgsystems.md new file mode 100644 index 0000000000..f700ecc2f1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-dbgsystems.md @@ -0,0 +1,205 @@ +--- +title: ndiskd.dbgsystems +description: The ndiskd.dbgsystems extension displays and optionally changes the NDIS subsystems that have debug traces enabled. ndiskd.dbgsystems has been superceded by WPP and Driver Verifier. +ms.assetid: f36a26b6-18a8-4a01-96c7-99826e6b662f +keywords: ["ndiskd.dbgsystems Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.dbgsystems +api_type: +- NA +--- + +# !ndiskd.dbgsystems + + +The **!ndiskd.dbgsystems** extension displays and optionally changes the NDIS subsystems that have debug traces enabled. + +**Warning**   +**!ndiskd.dbgsystems** has been superceded by WPP (Windows software trace preprocessor) and Driver Verifier. !ndiskd will give you the following warning if your target system does not support **!ndiskd.dbgsystems**. + +``` +0: kd> !ndiskd.dbgsystems + This target does not support tracing through !ndiskd.dbglevel or + !ndiskd.dbgsystems. + Learn how to collect traces with WPP +``` + +If you click on the link at the bottom of the warning, !ndiskd will give you more information. + +``` +0: kd> !ndiskd.help wpptracing + WPP traces are fast, flexible, and detailed. Plus, starting with Windows 8 + and Windows Server 2012, you can automatically decode NDIS traces using the + symbol file. Just point TraceView (or tracepdb.exe) at NDIS.PDB, and it + will be able to get all the TMFs it needs to trace NDIS activity. + + If you would like traces to be printed in the debugger window, you use the + !wmitrace extension. For example, you might enable traces with this: + + !wmitrace.searchpath c:\path\to\TMF\files + !wmitrace.start ndis -kd + !wmitrace.enable ndis {DD7A21E6-A651-46D4-B7C2-66543067B869} -level 4 -flag 0x31f3 +``` + +  + +For more information about WPP, see [WPP Software Tracing](https://msdn.microsoft.com/windows/hardware/drivers/devtest/wpp-software-tracing). + +For more information about Driver Verifier, see [Driver Verifier](https://msdn.microsoft.com/windows/hardware/drivers/devtest/driver-verifier). + +For more information about WMI tracing, see [WMI Tracing Extensions (Wmitrace.dll)](https://msdn.microsoft.com/library/windows/hardware/ff561362). + +``` +!ndiskd.dbgsystems [-subsystem ] +``` + +## Parameters + + + *-subsystem* +The subsystem to toggle. + +If multiple components are selected, separate them with spaces. If a previously-selected component is repeated, its debug monitoring will be toggled off. The following values are possible: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Value

Meaning

INIT

Traces adapter initialization.

CONFIG

Traces adapter configuration.

SEND

Traces sending data over the network.

RECV

Traces receiving data from the network.

PROTOCOL

Traces protocol operations.

BIND

Traces binding operations.

BUS_QUERY

Traces bus queries.

REGISTRY

Traces registry operations.

MEMORY

Traces memory management.

FILTER

Traces filter operations.

REQUEST

Traces requests.

WORK_ITEM

Traces work-item operations.

PNP

Traces Plug and Play operations.

PM

Traces Power Management operations.

OPEN

Traces operations that open reference objects.

LOCKS

Traces locking operations.

RESET

Traces resetting operations.

WMI

Traces Windows Management Instrumentation operations.

NDIS_CO

Traces Connection-Oriented NDIS.

REFERENCE

Traces reference operations.

+ +  + +### DLL + +Ndiskd.dll + +Remarks +------- + +This extension applies to checked NDIS.sys only. To check the build info of NDIS.sys, run the [**!ndiskd.ndis**](-ndiskd-ndis.md) extension. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.ndis**](-ndiskd-ndis.md) + +[WPP Software Tracing](https://msdn.microsoft.com/windows/hardware/drivers/devtest/wpp-software-tracing) + +[Driver Verifier](https://msdn.microsoft.com/windows/hardware/drivers/devtest/driver-verifier) + +[WMI Tracing Extensions (Wmitrace.dll)](https://msdn.microsoft.com/library/windows/hardware/ff561362) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.dbgsystems%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-filter.md b/windows-driver-docs-pr/debugger/-ndiskd-filter.md new file mode 100644 index 0000000000..0bb5ac5631 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-filter.md @@ -0,0 +1,111 @@ +--- +title: ndiskd.filter +description: The ndiskd.filter extension displays information about an NDIS light-weight filter (LWF). If you run this extension with no parameters, ndiskd will display a list of all LWFs. +ms.assetid: 4cf0f8bc-a15a-49db-b7db-13d60fd0c767 +keywords: ["ndiskd.filter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.filter +api_type: +- NA +--- + +# !ndiskd.filter + + +The **!ndiskd.filter** extension displays information about an NDIS light-weight filter (LWF). If you run this extension with no parameters, !ndiskd will display a list of all LWFs. + +``` +!ndiskd.filter [-handle ] [-findname ] [-handlers] +``` + +## Parameters + + + *-handle* +Handle of an NDIS light-weight filter. + + *-findname* +Filters LWFs by name prefix. + + *-handlers* +Displays this LWF's filter handlers. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Enter the **!ndiskd.filter** command with no parameters to get a list of all filters. In this example, look for the ffff8083e14e8460 handle. Note that this handle is for the filter itself and is nested under its associated filter *driver*, the QoS Packet Scheduler. + +``` +3: kd> !ndiskd.filter +ffff8083e1a7fd90 - QoS Packet Scheduler + Filter ffff8083e14e8460, Miniport ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter +ffff8083e1a96b80 - Virtual WiFi Filter Driver +ffff8083e19c4b70 - WFP vSwitch Layers LightWeight Filter +ffff8083e19a6ad0 - WFP Native MAC Layer LightWeight Filter + Filter ffff8083e43df8f0, Miniport ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter +ffff8083e19a6d70 - WFP 802.3 MAC Layer LightWeight Filter + Filter ffff8083e0d89c70, Miniport ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter +``` + +By using this filter handle we can now see more detailed information about it, such as it State, Higher filter handle, and Lower filter handle. + +``` +3: kd> !ndiskd.filter ffff8083e14e8460 + + +FILTER + + Microsoft Kernel Debug Network Adapter-QoS Packet Scheduler-0000 + + Ndis handle ffff8083e14e8460 + Filter driver ffff8083e1a7fd90 - QoS Packet Scheduler + Module context ffff8083e26953e0 + Miniport ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Network interface ffff8083e200f010 + + State Running + Datapath Send only + References 1 + Flags RUNNING + More flags OID_TOP + + Higher filter ffff8083e0d89c70 - Microsoft Kernel Debug Network Adapter-WFP 802.3 MAC Layer LightWeight Filter-0000 + Lower filter ffff8083e43df8f0 - Microsoft Kernel Debug Network Adapter-WFP Native MAC Layer LightWeight Filter-0000 + + Driver handlers +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.filter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-filterdriver.md b/windows-driver-docs-pr/debugger/-ndiskd-filterdriver.md new file mode 100644 index 0000000000..26db0e2d22 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-filterdriver.md @@ -0,0 +1,132 @@ +--- +title: ndiskd.filterdriver +description: The ndiskd.filterdriver extension displays information about an NDIS filter driver. If you run this extension with no parameters, ndiskd will display a list of all filter drivers. +ms.assetid: 9FE3E885-98BC-4FCC-9E1C-DBECD070F92A +keywords: ["ndiskd.filterdriver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.filterdriver +api_type: +- NA +--- + +# !ndiskd.filterdriver + + +The **!ndiskd.filterdriver** extension displays information about an NDIS filter driver. If you run this extension with no parameters, !ndiskd will display a list of all filter drivers. + +``` +!ndiskd.filterdriver [-handle ] [-filters] [-handlers] +``` + +## Parameters + + + *-handle* +Handle of an NDIS filter driver. + + *-filters* +Displays instances of this driver's filters. + + *-handlers* +Displays this driver's filter handlers. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run **!ndiskd.filterdriver** with no parameters to see a list of all filter drivers on the system. In the following example, look for the Virtual WiFi Filter Driver, whose handle is ffffbc064cc83be0. + +``` +0: kd> !ndiskd.filterdriver + ffffbc064ccd4900 - QoS Packet Scheduler + ffffbc064cc83be0 - Virtual WiFi Filter Driver + ffffbc064cb91a10 - WFP vSwitch Layers LightWeight Filter + ffffbc064cb8fd70 - WFP Native MAC Layer LightWeight Filter + ffffbc064cb59b00 - WFP 802.3 MAC Layer LightWeight Filter +``` + +By clicking the filter driver handle from the previous example or by using it to enter the **!ndiskd.filterdriver -handle** command in the command window, you can get see more detailed information about that filter driver. In this case, for example, there are no filter modules for this filter driver. + +``` +0: kd> !ndiskd.filterdriver ffffbc064cc83be0 + + +FILTER DRIVER + + Virtual WiFi Filter Driver + + Ndis handle ffffbc064cc83be0 + Driver context ffffbc064cc8e9d0 + Ndis API version v6.50 + Driver version v1.0 + Driver object ffffbc064cc8e9d0 + Driver image vwififlt.sys + + Bind flags Optional, Modifying + Class [Zero-length string] + References 1 + + +FILTER MODULES + + Filter module + [No filter modules were found] + + +HANDLERS + + Filter handler Function pointer Symbol (if available) + SetOptionsHandler [None] + SetFilterModuleOptionsHandler [None] + AttachHandler fffff80787d83b60 bp + DetachHandler fffff80787d84800 bp + RestartHandler fffff80787d86e20 bp + PauseHandler fffff80787d863e0 bp + SendNetBufferListsHandler fffff80787d814d0 bp + SendNetBufferListsCompleteHandler fffff80787d81940 bp + CancelSendNetBufferListsHandler fffff80787d842f0 bp + ReceiveNetBufferListsHandler fffff80787d817e0 bp + ReturnNetBufferListsHandler fffff80787d81a80 bp + OidRequestHandler fffff80787d85ae0 bp + OidRequestCompleteHandler fffff80787d85fd0 bp + DirectOidRequestHandler fffff80787d84af0 bp + DirectOidRequestCompleteHandler fffff80787d84e80 bp + CancelDirectOidRequestHandler fffff80787d841d0 bp + DevicePnPEventNotifyHandler fffff80787d849e0 bp + NetPnPEventHandler fffff80787d85a40 bp + StatusHandler fffff80787d877c0 bp +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.filterdriver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-findpacket.md b/windows-driver-docs-pr/debugger/-ndiskd-findpacket.md new file mode 100644 index 0000000000..d5c3b04f80 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-findpacket.md @@ -0,0 +1,63 @@ +--- +title: ndiskd.findpacket +description: Warning  This extension is for legacy NDIS 5.x drivers. The NDIS_PACKET structure and its associated architecture have been deprecated. The ndiskd.findpacket extension finds the specified packets. +ms.assetid: fc07b2d8-85ca-4be1-ae9d-40b7c7f81b08 +keywords: ["ndiskd.findpacket Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.findpacket +api_type: +- NA +--- + +# !ndiskd.findpacket + + +**Warning**  This extension is for legacy NDIS 5.x drivers. The [NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) structure and its associated architecture have been deprecated. + +  + +The **!ndiskd.findpacket** extension finds the specified packets. + +``` +!ndiskd.findpacket [-VirtualAddress] [-PoolAddress] +``` + +## Parameters + + + *VirtualAddress* +Specifies a virtual address that is contained in the desired packet. + + *PoolAddress* +Specifies a pool address. All unreturned packets in this pool will be displayed. + +### DLL + +Ndiskd.dll + +## See also + + +[Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849) + +[Windows 2000 and Windows XP Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff565850) + +[NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.findpacket%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-help.md b/windows-driver-docs-pr/debugger/-ndiskd-help.md new file mode 100644 index 0000000000..15e288219c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-help.md @@ -0,0 +1,145 @@ +--- +title: ndiskd.help +description: The ndiskd.help command displays a list of available ndiskd commands with a brief description of each one. +ms.assetid: ba9a1364-173b-4258-9894-09271e47786e +keywords: ["ndiskd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.help +api_type: +- NA +--- + +# !ndiskd.help + + +The **!ndiskd.help** command displays a list of available !ndiskd commands with a brief description of each one. + +``` +!ndiskd.help +``` + +## DLL + + +Ndiskd.dll + +Examples +-------- + +The following example shows the list of help commands using **!ndiskd.help**. + +``` +3: kd> !ndiskd.help + +NDIS KD EXTENSIONS + + help This help and lots more + netadapter Show network adapters (this is a good starting place) + protocol Show protocol drivers + mopen Show open bindings between netadapter and protocol + filter Show light-weight filters + nbl Show information about an NET_BUFFER_LIST + oid Show pending OID Requests + ndis Show NDIS.sys build info + netreport Draw a box diagram of your network stack + + Show more extensions + View examples & tutorials online + +``` + +By using **!ndiskd.help -all**, you'll get a more detailed list, as shown in the following example. + +**Note**   +Some alternate commands are listed at the bottom of this example. These commands are available for NDIS driver developers who have used them before but we recommend using the primary commands instead. + +  + +``` +3: kd> !ndiskd.help -all + +NDIS KD EXTENSIONS + + Primary commands: + help This help and lots more + netadapter Show network adapters (this is a good starting place) + minidriver Show network adapter drivers + rcvqueue Show a receive queue (c.f. VMQ) + protocol Show protocol drivers + mopen Show open bindings between netadapter and protocol + filter Show light-weight filters + filterdriver Show filter drivers (not to be confused with filters) + nbl Show information about an NET_BUFFER_LIST + nb Show information about an NET_BUFFER + nblpool Show information about an NET_BUFFER_LIST pool + nbpool Show information about an NET_BUFFER pool + pendingnbls Show all NET_BUFFER_LISTs that are in transit + nbllog Show a log of all NET_BUFFER_LIST activity + oid Show pending OID Requests + interfaces Show interfaces (à la NDISIF) + ifprovider Show registered NDIS interface providers + ifstacktable Show the ifStackTable + networks Show networks (probably not what you think) + compartments Show compartments + pkt Show a NDIS_PACKET structure + pktpools Show all allocated packet pools + findpacket Find a packet in memory + vc Show a CoNDIS virtual connection + af Show a CoNDIS address family + ndisref Show a debug log of refcounts + ndisevent Show a debug log of events + ndisstack Show a debug stack trace + wdiadapter Shows one or more WDIWiFi!CAdapter structures + wdiminidriver Shows one or more CMiniportDriver structures + nwadapter Shows one or more nwifi!ADAPT structures + ndisrwlock Show an NDIS_RW_LOCK_EX lock + ndisslot Show an NDIS per-processor slot + ndis Show NDIS.sys build info + dbglevel Change the debugging level [checked NDIS.sys only] + dbgsystems Toggle subsystems being debugged [checked NDIS.sys only] + ndiskdversion Show info about NDISKD itself + netreport Draw a box diagram of your network stack + + Alternate commands: + miniport Same as !ndiskd.netadapter + gminiports Same as !ndiskd.netadapter + miniports "Classic" version of !ndiskd.netadapter + filterdb Same as !ndiskd.netadapter -filterdb + offload Same as !ndiskd.netadapter -offloads + ports Same as !ndiskd.netadapter -ports + rcvqueues Same as !ndiskd.netadapter -rcvqueues + filters Same as !ndiskd.filter + opens Same as !ndiskd.mopen + protocols Same as !ndiskd.protocol + nblpools Same as !ndiskd.nblpool + nbpools Same as !ndiskd.nbpool +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ifprovider.md b/windows-driver-docs-pr/debugger/-ndiskd-ifprovider.md new file mode 100644 index 0000000000..b74b8b5e89 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ifprovider.md @@ -0,0 +1,107 @@ +--- +title: ndiskd.ifprovider +description: The ndiskd.ifprovider extension displays information about an NDIS interface provider (IfProvider). +ms.assetid: 89C406E5-81D3-42AA-BA15-3D7C093BCD3C +keywords: ["ndiskd.ifprovider Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ifprovider +api_type: +- NA +--- + +# !ndiskd.ifprovider + + +The **!ndiskd.ifprovider** extension displays information about an [NDIS interface provider](https://msdn.microsoft.com/windows/hardware/drivers/network/registering-as-an-interface-provider) (IfProvider). If you run this extension with no parameters, !ndiskd will display a list of all registered NDIS interface providers. + +``` +!ndiskd.ifprovider [-handle ] +``` + +## Parameters + + + *-handle* +Handle of an IfProvider. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.ifprovider** extension with no parameters to get a list of all registered IfProviders. + +``` +1: kd> !ndiskd.ifprovider + IfProvider + ffffd20d14334180 - wanarp + ffffd20d1264a950 - wfplwfs + ffffd20d11deae00 - The NDIS loopback provider + ffffd20d11deae70 - The NDIS interface provider +``` + +You can see from the previous example that the debugee machine has four interface providers registered. Two of them are NDIS interface providers. + +**Note**  Interface providers are a generic concept and aren't required to be miniport drivers. While a miniport driver may choose to register as an interface provider if desired, most miniport drivers do not do so because NDIS has a built-in interface provider. The NDIS built-in interface provider automatically provides interfaces for every miniport driver, every Light-Weight Filter (LWF) module, and the loopback interface. For more information, see [NDIS interface provider](https://msdn.microsoft.com/windows/hardware/drivers/network/registering-as-an-interface-provider). + +  + +The following example shows the details for the "wanarp" interface provider in the previous example, whose handle is ffffd20d14334180. + +``` +1: kd> !ndiskd.ifprovider ffffd20d14334180 + + +IF PROVIDER + + wanarp + Ndis handle ffffd20d14334180 + + +INTERFACES + + Interface + [No interfaces found] + + +HANDLERS + + Protocol handler Function pointer Symbol (if available) + QueryObjectHandler fffff80d2f0414b0 bp wanarp!WanNdisIfQueryHandler + SetObjectHandler fffff80d2f04bd10 bp wanarp!WanNdisIfSetHandler +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Registering as an Interface Provider](https://msdn.microsoft.com/windows/hardware/drivers/network/registering-as-an-interface-provider) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ifprovider%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ifstacktable.md b/windows-driver-docs-pr/debugger/-ndiskd-ifstacktable.md new file mode 100644 index 0000000000..1a1aa56dbc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ifstacktable.md @@ -0,0 +1,190 @@ +--- +title: ndiskd.ifstacktable +description: The ndiskd.ifstacktable extension displays the network interface stack table (ifStackTable). +ms.assetid: 8166C088-9366-49C4-9C3A-0089807352A9 +keywords: ["ndiskd.ifstacktable Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ifstacktable +api_type: +- NA +--- + +# !ndiskd.ifstacktable + + +The **!ndiskd.ifstacktable** extension displays the network interface stack table (ifStackTable). + +For more information about the interface stack table, see [Maintaining a Network Interface Stack](https://msdn.microsoft.com/windows/hardware/drivers/network/maintaining-a-network-interface-stack). + +``` +!ndiskd.ifstacktable +``` + +## Parameters + + +This extension has no parameters. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.ifstacktable** command to see the ifStackTable. + +``` +3: kd> !ndiskd.ifstacktable + + +INTERFACE STACK TABLE + + Lower interface Lower IfIndex Higher IfIndex Higher interface + ffffdf80139b3a20 6 15 ffffdf801494fa20 + ffffdf801494fa20 15 16 ffffdf801494c010 + ffffdf801494c010 16 17 ffffdf801494ba20 +``` + +NDIS maintains the stack table for NDIS miniport adapters, NDIS 5.x filter intermediate drivers, and NDIS filter modules, whereas [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/windows/hardware/drivers/network/ndis-mux-intermediate-drivers) drivers are required to specify the internal interface relationship between the virtual miniport interface and the protocol lower interface. Therefore, the ifStackTable could be useful for seeing the interface stack relationships in a system with more complicated MUX drivers installed. + +Since there are no NDIS MUX Intermediate drivers installed on this example system, the ifStackTable only shows the stack relationships that NDIS has provided. In the following example, clicking on the handle for the Lower interface of the third row (handle ffffdf801494c010, Lower IfIndex 16) shows the interface for the QoS Packet Scheduler. + +``` +3: kd> !ndiskd.interface ffffdf801494c010 + + +INTERFACE + + [Zero-length string] + + Ndis handle ffffdf801494c010 + IfProvider ffffdf80131ca8d0 - The NDIS interface provider + NDIS filter ffffdf801494dc70 - Microsoft Kernel Debug Network Adapter-QoS Packet Scheduler-0000 + + ifType IF_TYPE_ETHERNET_CSMACD + Media type 802.3 + Physical medium NdisPhysicalMediumOther + Access type BROADCAST + Direction type SEND_AND_RECEIVE + Connection type DEDICATED + + ifConnectorPresent No + + Network ffffdf80139b8900 - [Unnamed network] + Compartment ffffdf80139b9940 - Compartment #1 + + +IDENTIFIERS + + ifAlias [Zero-length string] + ifDescr Microsoft Kernel Debug Network Adapter-QoS Packet Scheduler-0000 + ifName (NET_LUID) 06:01 + ifPhysAddress 18-03-73-c1-e8-72 + + ifIndex 0n16 + ifGuid fc2a0ae1-b103-11e6-b724-806e6f6e6963 + + +STATE + + Connected Connected + ifOperStatus DORMANT + ifOperStatusFlags DORMANT_PAUSED + + Link speed 1000000000 (1 Gbps) + ifMtu 0n1500 + Duplex FullDuplex + + Refer to RFC 2863 for definitions of many of these terms +``` + +Continuing the same example, clicking the handle for the Higher interface of the third row (handle ffffdf801494ba20, Higher IfIndex 17) shows the interface for the WFP 802.3 MAC Layer LightWeight Filter. + +``` +3: kd> !ndiskd.interface ffffdf801494ba20 + + +INTERFACE + + [Zero-length string] + + Ndis handle ffffdf801494ba20 [type it] + IfProvider ffffdf80131ca8d0 - The NDIS interface provider + NDIS filter ffffdf801494c670 - Microsoft Kernel Debug Network Adapter-WFP 802.3 MAC Layer LightWeight Filter-0000 + + ifType IF_TYPE_ETHERNET_CSMACD + Media type 802.3 + Physical medium NdisPhysicalMediumOther + Access type BROADCAST + Direction type SEND_AND_RECEIVE + Connection type DEDICATED + + ifConnectorPresent No + + Network ffffdf80139b8900 - [Unnamed network] + Compartment ffffdf80139b9940 - Compartment #1 + + +IDENTIFIERS + + ifAlias [Zero-length string] + ifDescr Microsoft Kernel Debug Network Adapter-WFP 802.3 MAC Layer LightWeight Filter-0000 + ifName (NET_LUID) 06:02 + ifPhysAddress 18-03-73-c1-e8-72 + + ifIndex 0n17 + ifGuid fc2a0ae0-b103-11e6-b724-806e6f6e6963 + + +STATE + + Connected Connected + ifOperStatus DORMANT + ifOperStatusFlags DORMANT_PAUSED + + Link speed 1000000000 (1 Gbps) + ifMtu 0n1500 + Duplex FullDuplex + + Refer to RFC 2863 for definitions of many of these terms +``` + +This shows that the WFP 802.3 MAC Layer LightWeight Filter sits above the QoS Packet Scheudler filter in the network interface stack. You can confirm this by running the [**!ndiskd.netreport**](-ndiskd-netreport.md) extension, which shows you the network stack visually. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Maintaining a Network Interface Stack](https://msdn.microsoft.com/windows/hardware/drivers/network/maintaining-a-network-interface-stack) + +[NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/windows/hardware/drivers/network/ndis-mux-intermediate-drivers) + +[**!ndiskd.netreport**](-ndiskd-netreport.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ifstacktable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-interfaces.md b/windows-driver-docs-pr/debugger/-ndiskd-interfaces.md new file mode 100644 index 0000000000..a6a6ae4b0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-interfaces.md @@ -0,0 +1,146 @@ +--- +title: ndiskd.interfaces +description: The ndiskd.interfaces extension displays information about a network interface. +ms.assetid: AC458FDF-CCB6-4A65-8C9C-38C436062017 +keywords: ["ndiskd.interfaces Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.interfaces +api_type: +- NA +--- + +# !ndiskd.interfaces + + +The **!ndiskd.interfaces** extension displays information about a network interface. If you run this extension with no parameters, !ndiskd will display a list of all network interfaces. + +For more information about network interfaces, see [NDIS Network Interfaces](https://msdn.microsoft.com/windows/hardware/drivers/network/ndis-network-interfaces2). + +``` +!ndiskd.interfaces [-handle ] [-luid ] +``` + +## Parameters + + + *-handle* +Handle of a network interface. + + *-luid* +[NetLuid](https://msdn.microsoft.com/windows/hardware/drivers/network/net-luid-value) (Net Locally Unique Identifier) of a network interface. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.interfaces** extension with no parameters to see a list of all network interfaces on the system. In this example, look for the Intel(R) 82579LM Gigabit Network Connection interface. Its handle is ffffdf80139f8a20. + +``` +1: kd> !ndiskd.interfaces + Interface + ffffdf801494fa20 - Microsoft Kernel Debug Network Adapter-WFP Native MAC Layer LightWeight Filter-0000 + ffffdf801494c010 - Microsoft Kernel Debug Network Adapter-QoS Packet Scheduler-0000 + ffffdf801494ba20 - Microsoft Kernel Debug Network Adapter-WFP 802.3 MAC Layer LightWeight Filter-0000 + ffffdf80139b3a20 - Microsoft Kernel Debug Network Adapter + ffffdf80139f8a20 - Intel(R) 82579LM Gigabit Network Connection + ffffdf80139baa20 - WAN Miniport (IP) + ffffdf80139a4a20 - WAN Miniport (IPv6) + ffffdf80131d0010 - WAN Miniport (Network Monitor) + ffffdf80131cda20 - WAN Miniport (PPPOE) + ffffdf80139b6a20 - Software Loopback Interface 1 + ffffdf80139b0a20 - Microsoft ISATAP Adapter + ffffdf80139ada20 - WAN Miniport (SSTP) + ffffdf80131cf010 - WAN Miniport (IKEv2) + ffffdf80139fea20 - WAN Miniport (L2TP) + ffffdf80139a7a20 - WAN Miniport (PPTP) + ffffdf80139aaa20 - Microsoft ISATAP Adapter #2 + ffffdf80139fba20 - Teredo Tunneling Pseudo-Interface +``` + +By clicking on the handle for an interface or by entering the **!ndiskd.interfaces -handle** command, you can see the details about that interface, including its Identifier information and its current state. In this example, you can see that the Intel(R) 82579LM Gigabit Network Connection is an Ethernet connection (its ifAlias) and is in a MediaConnectUnknown state for its connection (as it has been reserved for use by the Windows kernel debugger). + +``` +1: kd> !ndiskd.interfaces ffffdf80139f8a20 + + +INTERFACE + + Ethernet + + Ndis handle ffffdf80139f8a20 + IfProvider ffffdf80131ca8d0 - The NDIS interface provider + Provider context ffffdf80139f8a20 + + ifType IF_TYPE_ETHERNET_CSMACD + Media type 802.3 + Physical medium 802.3 + Access type BROADCAST + Direction type SEND_AND_RECEIVE + Connection type DEDICATED + + ifConnectorPresent No + + Network ffffdf80139b8900 - [Unnamed network] + Compartment ffffdf80139b9940 - Compartment #1 + + +IDENTIFIERS + + ifAlias Ethernet + ifDescr Intel(R) 82579LM Gigabit Network Connection + ifName (NET_LUID) 06:8001 + ifPhysAddress 18-03-73-c1-e8-72 + + ifIndex 0n14 + ifGuid cbddfde1-5570-4c65-9d47-52d63abce00c + + +STATE + + Connected MediaConnectUnknown + ifOperStatus NOT_PRESENT + + Link speed 0 [Speed is not applicable] + ifMtu 0 + Duplex UnknownDuplex + + Refer to RFC 2863 for definitions of many of these terms +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[NDIS Network Interfaces](https://msdn.microsoft.com/windows/hardware/drivers/network/ndis-network-interfaces2) + +[NET\_LUID Value](https://msdn.microsoft.com/windows/hardware/drivers/network/net-luid-value) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.interfaces%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-minidriver.md b/windows-driver-docs-pr/debugger/-ndiskd-minidriver.md new file mode 100644 index 0000000000..4450bda94d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-minidriver.md @@ -0,0 +1,112 @@ +--- +title: ndiskd.minidriver +description: The ndiskd.minidriver command displays information about an NDIS miniport driver. +ms.assetid: CD349B10-8363-4D48-A830-CC9EF5EA75BF +keywords: ["ndiskd.minidriver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.minidriver +api_type: +- NA +--- + +# !ndiskd.minidriver + + +The **!ndiskd.minidriver** command displays information about an NDIS miniport driver. If you run this extension with no parameters, !ndiskd will display a list of NDIS miniport drivers that are active on the system. + +``` +!ndiskd.minidriver [-handle ] [-basic] [-miniports] [-devices] [-handlers] +``` + +## Parameters + + + *-handle* +Handle of an NDIS miniport driver. + + *-basic* +Displays basic information about the miniport driver. + + *-miniports* +Displays the miniports associated with this miniport driver. + + *-devices* +Displays devices associated with this miniport driver. + + *-handlers* +Displays this driver's miniport handlers. + +## DLL + + +Ndiskd.dll + +Examples +-------- + +Enter the **!ndiskd.minidriver** command with no parameters to get a list of all NDIS miniport drivers active on the system. In the following example, look for the kdnic adapter's handle, ffffd20d12dec020 + +``` +1: kd> !ndiskd.minidriver -basic + ffffd20d173deae0 - tunnel + ffffd20d12dec020 - kdnic +``` + +Using the handle for the kdnic adapter, you can now click on the handle or enter the **!ndiskd.minidriver -handle** command to see detailed information for the tunnel miniport driver, as well as a list of miniports associated with it. + +``` +1: kd> !ndiskd.minidriver ffffd20d12dec020 + + +MINIPORT DRIVER + + kdnic + + Ndis handle ffffd20d12dec020 [type it] + Driver context fffff80d2fa15100 + DRIVER_OBJECT ffffd20d12dee540 + Driver image kdnic.sys + Registry path \REGISTRY\MACHINE\SYSTEM\ControlSet001\Services\kdnic + Reference Count 2 + Flags [No flags set] + + +MINIPORTS + + Miniport + ffffd20d12dd71a0 - Microsoft Kernel Debug Network Adapter + + Handlers + Device objects +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.minidriver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-mopen.md b/windows-driver-docs-pr/debugger/-ndiskd-mopen.md new file mode 100644 index 0000000000..e1f27c8cfe --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-mopen.md @@ -0,0 +1,126 @@ +--- +title: ndiskd.mopen +description: The ndiskd.mopen extension displays information about bindings between miniports and protocols. +ms.assetid: 439c4647-8f3e-4473-aca8-364b5d2206e9 +keywords: ["ndiskd.mopen Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.mopen +api_type: +- NA +--- + +# !ndiskd.mopen + + +The **!ndiskd.mopen** extension displays information about bindings between miniports and protocols. If you run this extension with no parameters, !ndiskd will display a list of all open bindings between NDIS miniport drivers and protocol drivers. + +``` +!ndiskd.mopen [-handle ] [-ref] +``` + +## Parameters + + + *-handle* +Handle of an NDIS open binding. + + *-ref* +Shows refcounts of open bindings. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Enter the !ndiskd.mopen command to get a list of all open bindings. In this example, look for the binding between the Microsoft ISATAP Adapter \#2 miniport and the TCPIP6TUNNEL protocol. Its handle is ffff8083e56b8110. + +``` +3: kd> !ndiskd.mopen +Open ffff8083e56b8110 + Miniport: ffff8083e02ce1a0 - Microsoft ISATAP Adapter #2 + Protocol: ffff8083e1a95c00 - TCPIP6TUNNEL + +Open ffff8083e11902c0 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e3e8f6b0 - RSPNDR + +Open ffff8083e55f3010 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e0114730 - NDISUIO + +Open ffff8083e15537d0 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e3e90800 - LLTDIO + +Open ffff8083e3926010 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e3e90c10 - MSLLDP + +Open ffff8083e0c565a0 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e11cec10 - TCPIP + +Open ffff8083e504c770 + Miniport: ffff8083e0f501a0 - Microsoft Kernel Debug Network Adapter + Protocol: ffff8083e19bfc10 - TCPIP6 +``` + +Now you can either click on the handle or use the handle to enter the **!ndiskd.mopen -handle** command, which enables you to see more details about that open binding such as its Datapath state and Receive path information. + +``` +3: kd> !ndiskd.mopen ffff8083e56b8110 + + +OPEN + + Ndis handle ffff8083e56b8110 + Flags [No flags set] + References 1 Show detail + Source 1 + Datapath state Running + + Protocol ffff8083e1a95c00 - TCPIP6TUNNEL + Protocol context ffff8083e15b62e0 + + Miniport ffff8083e02ce1a0 - Microsoft ISATAP Adapter #2 + Miniport context ffff8083e0772010 + + +RECEIVE PATH + + Packet filter [No flags set] + Frame Type(s) 0x86dd +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.mopen%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nb.md b/windows-driver-docs-pr/debugger/-ndiskd-nb.md new file mode 100644 index 0000000000..cda2b2cafc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nb.md @@ -0,0 +1,113 @@ +--- +title: ndiskd.nb +description: The ndiskd.nb extension displays information about a NET_BUFFER (NB) structure. +ms.assetid: 7351264c-4adc-43ac-9eca-41deb3d35983 +keywords: ["ndiskd.nb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nb +api_type: +- NA +--- + +# !ndiskd.nb + + +The **!ndiskd.nb** extension displays information about a [**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) (NB) structure. + +``` +!ndiskd.nb [-handle ] [-verbosity ] [-basic] [-chain] [-data] +``` + +## Parameters + + + *-handle* +Required. Address of a **NET\_BUFFER** structure. + + *-verbosity* +Level of detail to display. + + *-basic* +Displays basic information about an NB. + + *-chain* +Displays all the MDLs associated with an NB. + + *-data* +Dumps the actual data payload of an NB. + +### DLL + +Ndiskd.dll + +Examples +-------- + +The **NET\_BUFFER** in the following examples was obtained from the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) in the Examples section of the [**!ndiskd.nbl**](-ndiskd-nbl.md) topic. The NB's handle is ffffdf8014952610. + +``` +2: kd> !ndiskd.nbl ffffdf80149524a0 -data +NET_BUFFER ffffdf8014952610 +``` + +You can click the **NET\_BUFFER**'s handle or run the **!ndiskd.nb -handle** command to see its details. + +``` +2: kd> !ndiskd.nb ffffdf8014952610 + NB ffffdf8014952610 Next NB 0 + Length 0 Source pool ffffdf80147e4a40 + First MDL ffffdf8014a37930 DataOffset 0 + Current MDL [First MDL] Current MDL offset 0 + + View associated NBL +``` + +Use the **!ndiskd.nb -chain** command to see this **NET\_BUFFER**'s MDL chain in addition to its basic details. In the following example, there is only one MDL. Its handle is ffffdf8014a37930. + +``` +2: kd> !ndiskd.nb ffffdf8014952610 -chain + NB ffffdf8014952610 Next NB 0 + Length 0 Source pool ffffdf80147e4a40 + First MDL ffffdf8014a37930 DataOffset 0 + Current MDL [First MDL] Current MDL offset 0 + MDL [current] ffffdf8014a37930 MDL Flags c + MappedSystemVa ffffdf8014bf0024 ByteCount 0n1514 + Process [System process] ByteOffset 0n36 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) + +[**!ndiskd.nbl**](-ndiskd-nbl.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nbl.md b/windows-driver-docs-pr/debugger/-ndiskd-nbl.md new file mode 100644 index 0000000000..f7ccb7f81a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nbl.md @@ -0,0 +1,129 @@ +--- +title: ndiskd.nbl +description: The ndiskd.nbl extension displays information about a NET_BUFFER_LIST (NBL) structure. +ms.assetid: 1806ac7c-b438-4c28-bab0-1b65dba651ea +keywords: ["ndiskd.nbl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nbl +api_type: +- NA +--- + +# !ndiskd.nbl + + +The **!ndiskd.nbl** extension displays information about a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) (NBL) structure. + +``` + !ndiskd.nbl [-handle ] [-basic] [-chain] [-info] [-data] + [-netmon] [-capfile ] [-launch] [-overwrite] [-log] + [-stacks] [-NblCurrentOwner] +``` + +## Parameters + + + *-handle* +Required. Address of a **NET\_BUFFER\_LIST** structure. + + *-basic* +Displays basic information about an NBL. + + *-chain* +Displays all the NBLs and [**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure)s in an NBL chain. + + *-info* +Displays all the out-of-band information that is associated with an NBL. + + *-data* +Displays the actual data payload of an NBL. + + *-netmon* +Views the NBL chain in Microsoft Network Monitor. + + *-capfile* +Specifies the path to which a netmon capture is saved. + + *-launch* +Automatically launches netmon.exe after saving the capture file. + + *-overwrite* +Allows overwriting the capture file if it already exists. + + *-log* +Shows NBL log if NBL history logging is enabled. + + *-stacks* +Includes callstacks with NBL log (use with -log). + + *-NblCurrentOwner* +Shows the current owner of the NBL. + +### DLL + +Ndiskd.dll + +Examples +-------- + +In the following example, NBL tracking has been enabled to extract a handle for an NBL from the NBL log. For more information about NBL tracking and the NBL log, see [**!ndiskd.nbllog**](-ndiskd-nbllog.md). + +At the time of log collection, the NBL in this example was returned by the TCPIP6 protocol to the WFP Native Mac Layer LightWeight Filter. + +``` +2: kd> !ndiskd.nbl ffffdf80149524a0 + NBL ffffdf80149524a0 Next NBL NULL + First NB ffffdf8014952610 Source ffffdf80140c71a0 - Microsoft Kernel Debug Network Adapter + Flags INDICATED, RETURNED, NBL_ALLOCATED, PROTOCOL_020_0, + PROTOCOL_200_0 + + Walk the NBL chain Dump data payload + Show out-of-band information + Review NBL history +``` + +By clicking on the "Dump data payload" link from the previous example or by entering the **!ndiskd.nbl -handle -data** command, you can see the data payload of this NBL. In the following example, the NBL contains only one **NET\_BUFFER** structure. To further explore the contents of that **NET\_BUFFER** structure, run the [**!ndiskd.nb -handle**](-ndiskd-nb.md) command with its handle. + +``` +2: kd> !ndiskd.nbl ffffdf80149524a0 -data +NET_BUFFER ffffdf8014952610 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) + +[**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) + +[**!ndiskd.nbllog**](-ndiskd-nbllog.md) + +[**!ndiskd.nb**](-ndiskd-nb.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nbl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nbllog.md b/windows-driver-docs-pr/debugger/-ndiskd-nbllog.md new file mode 100644 index 0000000000..5675847d1b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nbllog.md @@ -0,0 +1,130 @@ +--- +title: ndiskd.nbllog +description: The ndiskd.nbllog extension displays the log of all NBL (NET_BUFFER_LIST) activity on the system. +ms.assetid: 59CB6B60-E0B3-435E-A6F6-82A715E87C69 +keywords: ["ndiskd.nbllog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nbllog +api_type: +- NA +--- + +# !ndiskd.nbllog + + +The **!ndiskd.nbllog** extension displays the log of all NBL ([**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure)) activity on the system. + +``` +!ndiskd.nbllog [-stacks] +``` + +## Parameters + + + *-stacks* +Include callstacks. + +### DLL + +Ndiskd.dll + +Remarks +------- + +**Important**   +**!ndiskd.nbllog** requires NBL tracking to be enabled on the debugee target machine. NBL tracking is not enabled by default in all configurations of Windows. If NBL tracking is not enabled, !ndiskd will give you instructions on how to enable it, as shown in the following snippet. + +``` +0: kd> !ndiskd.nbllog + This command requires NBL tracking to be enabled on the debugee target + machine. (By default, client operating systems have level 1, and servers + have level 0). To enable, set this REG_DWORD value to a nonzero value on + the target machine and reboot the target machine: + + HKLM\SYSTEM\CurrentControlSet\Services\NDIS\Parameters ! TrackNblOwner + Possible Values (features are cumulative) + * 0: Disable all tracking. + * 1: Track the most recent owner of each NBL (enables !ndiskd.pendingnbls) + * 2: Scan for leaks at runtime (use with StuckNblReaction) + * 3: Keep a full history of all activity (enables !ndiskd.nbl -log) + * 4: Take stack capture snapshots (enables !ndiskd.nbl -log -stacks) + This command requires level 3 or higher. +``` + +  + +The NBL log shows network traffic on the system. [**!ndiskd.netreport**](-ndiskd-netreport.md) parses the NBL tracking log to display this network traffic visually. Therefore, if NBL tracking is not enabled, **!ndiskd.netreport** will not be able to show you this information. + +Examples +-------- + +After you have enabled NBL tracking on the target debugee machine, enter the **!ndiskd.nbllog** command to see the log of all NBL traffic on the system. As shown in the example below, running **!ndiskd.nbllog** with no parameters will limit output to 200 events, which can be bypassed by rerunning the command with the *-force* option. The middle of the output in this example has been excised for brevity. + +``` +0: kd> !ndiskd.nbllog + NBLs Processor Event Detail + + ffffe00bc71453f0 CPU 0 Freed + ffffe00bc7163b40 CPU 2 Allocated + ffffe00bc7163b40 CPU 2 ProtocolSent ffffe00bc5ac4880 - QoS Packet Scheduler-0000 + ffffe00bc7163b40 CPU 2 FilterSent ffffe00bc5ac5c70 - WFP Native MAC Layer LightWeight Filter-0000 + ffffe00bc7163b40 CPU 2, IRQL=DPC FilterSent ffffe00bc3f701a0 - Microsoft Kernel Debug Network Adapter + ffffe00bc7163b40 CPU 2, IRQL=DPC SentToMiniport ffffe00bc3f701a0 - Microsoft Kernel Debug Network Adapter + ffffe00bc7163b40 CPU 0, IRQL=DPC MiniportSendCompleted ffffe00bc5ac5c70 - WFP Native MAC Layer LightWeight Filter-0000 + ffffe00bc7163b40 CPU 0, IRQL=DPC FilterSendCompleted ffffe00bc5ac4880 - QoS Packet Scheduler-0000 + ffffe00bc7163b40 CPU 0, IRQL=DPC FilterSendCompleted send complete in NDIS, sorting to Opens + ffffe00bc7163b40 CPU 0, IRQL=DPC SendCompleted ffffe00bc5ab7c10 - TCPIP6 + +... + + ffffe00bc6b469b0 CPU 2 Allocated + ffffe00bc6b469b0 CPU 2 Freed + ffffe00bc64a3690 CPU 2 Allocated + ffffe00bc64a3690 CPU 2 ProtocolSent ffffe00bc5ac4880 - QoS Packet Scheduler-0000 + ffffe00bc64a3690 CPU 2 FilterSent ffffe00bc5ac5c70 - WFP Native MAC Layer LightWeight Filter-0000 + ffffe00bc64a3690 CPU 2, IRQL=DPC FilterSent ffffe00bc3f701a0 - Microsoft Kernel Debug Network Adapter + ffffe00bc64a3690 CPU 2, IRQL=DPC SentToMiniport ffffe00bc3f701a0 - Microsoft Kernel Debug Network Adapter + ffffe00bc3cf2d10 CPU 1 Allocated + ffffe00bc7bc6030 CPU 1 Allocated + ffffe00bc3cf2d10 CPU 1 ProtocolSent ffffe00bc5ac4880 - QoS Packet Scheduler-0000 + + Maximum of 200 events printed; quitting early. + Rerun with the '-force' option to bypass this limit. +``` + +For a more detailed description of how to interpret the results of **!ndiskd.nbllog**, see [!ndiskd.nbl -log](https://go.microsoft.com/fwlink/p/?linkid=846176) on the NDIS blog. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) + +[!ndiskd.nbl -log](https://go.microsoft.com/fwlink/p/?linkid=846176) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nbllog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nblpool.md b/windows-driver-docs-pr/debugger/-ndiskd-nblpool.md new file mode 100644 index 0000000000..fb4ad0d9dd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nblpool.md @@ -0,0 +1,184 @@ +--- +title: ndiskd.nblpool +description: The ndiskd.nblpool extension displays information about a NET_BUFFER_LIST (NBL) pool. If you run this extension with no parameters, ndiskd will display a list of all allocated NBL pools in the system. +ms.assetid: 78F8E45C-D13D-4628-A387-529291B4C50C +keywords: ["ndiskd.nblpool Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nblpool +api_type: +- NA +--- + +# !ndiskd.nblpool + + +The **!ndiskd.nblpool** extension displays information about a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) (NBL) pool. If you run this extension with no parameters, !ndiskd will display a list of all allocated NBL pools in the system. + +``` +!ndiskd.nblpool [-handle ] [-basic] [-allocations] [-find ] [-findnb ] + [-findctx ] [-findctxtype ] [-findva ] [-findpa ] +``` + +## Parameters + + + *-handle* +Handle of an NBL pool. + + *-basic* +Displays basic information about the NBL pool. + + *-allocations* +Displays all allocated NBLs. + + *-find* +Filter the list of allocated NBLs using a debugger expression. + + *-findnb* +Filter the list of allocated NBLs by linked [**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure)s (NBs). + + *-findctx* +Filter the list of allocated NBLs by context area. + + *-findctxtype* +Override the datatype of the context area. + + *-findva* +Find NBLs that contain an NB that straddles the given virtual address. + + *-findpa* +Find NBLs that contain an NB that straddles the given physical address. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Enter the **!ndiskd.nblpool** command with no parameters to see a list of all allocated NBL pools. In this example, look for the NBL pool allocated by the kernel debugger network interface card (kdnic) with the KDNr Tag. Its handle is ffffdf80147e4a40. + +``` +2: kd> !ndiskd.nblpool + NBL Pool Tag Allocated by + ffffdf80179b6a40 NiBP WdNisDrv!CWFPLayer::Initialize+c6 + ffffdf8015ac6a40 EUNP tunnel!TunnelEtherUdpGlobalInit+81 + ffffdf8015a78040 Nuio ndisuio!ndisuioCreateBinding+15f + ffffdf8015a77800 Nuio ndisuio!ndisuioCreateBinding+13c + ffffdf8015a63040 BaNB rspndr!TopStartNetBufferModule+6d + ffffdf8015a68a40 LLnb mslldp!lldpProtSetOptions+49 + ffffdf8014654040 BaNB lltdio!TopStartNetBufferModule+6d + ffffdf801494ca40 Pcsb pacer!PcFilterAttach+142 + ffffdf80147e4a40 KDNr kdnic!NICAllocAdapter+178 + ffffdf80131ce040 bnvW wfplwfs!DriverEntry+7a0 + ffffdf80139ffa40 Wfdp wfplwfs!WfpRioInitialize+a4 + ffffdf8012061200 UNbl NETIO!NetioAllocateNetBufferListNetBufferMdlAndDataPool+49 + ffffdf8013968a40 TcDN NETIO!NetioAllocateNetBufferListNetBufferMdlAndDataPool+49 + ffffdf8013969a40 TNbl NETIO!NetioAllocateNetBufferListNetBufferMdlAndDataPool+49 + ffffdf801397c040 StBn NETIO!StreamPoolsInit+c1 + ffffdf8013088040 Wfra NETIO!WfpNblInfoLibraryInit+b8 + ffffdf8012067440 Nnnn NETIO!NetioInitializeNetBufferListLibrary+13e + ffffdf8012067a40 Nnbl NETIO!NetioInitializeNetBufferListLibrary+112 + ffffdf80131caa40 NDrt ndis!ndisInitializePeriodicReceives+22f + ffffdf80131d5a40 NDnd ndis!DriverEntry+5e9 +``` + +Click on the NBL pool's handle or enter the **!ndiskd.nblpool -handle** command to examine its details. + +``` +2: kd> !ndiskd.nblpool ffffdf80147e4a40 + + +NBL POOL + + Ndis handle ffffdf80147e4a40 + Allocation tag KDNr + Owner + Allocated by kdnic!NICAllocAdapter+178 + + Flags CONTAINS_NET_BUFFER + Structure size 0n544 + Context size 0 + Data size 0 + + All allocated NBLs +``` + +To explore the NBLs contained in this NBL pool, click on the "All allocated NBLs" link at the bottom. Alternatively, you can also enter the **!ndiskd.nblpool -handle -allocations** command. As shown in the following example, this NBL pool contains more than 1024 NBLs so !ndiskd quit early. You can use the -force option to work around this limit and see all of the NBLs in this NBL pool. + +``` +2: kd> !ndiskd.nblpool ffffdf80147e4a40 -allocations + + +ALL ALLOCATED NBLs + + NBL Active? + ffffdf8014951940 Allocated + ffffdf8014951b90 Allocated + ffffdf8014951de0 Allocated + ffffdf8014951030 Allocated + ffffdf80149524a0 Allocated + ffffdf80149526f0 Allocated + ffffdf8014952940 Allocated + ffffdf8014952b90 Allocated + ffffdf8014952de0 Allocated + ffffdf8014952030 Allocated + ffffdf80149534a0 Allocated + ffffdf80149536f0 Allocated + ffffdf8014953940 Allocated + ffffdf8014953b90 Allocated + ffffdf8014953de0 Allocated + ffffdf8014953030 Allocated + ffffdf80149544a0 Allocated + ffffdf80149546f0 Allocated + ffffdf8014954940 Allocated + +... + + ffffdf80148b0b90 Allocated + ffffdf80148b0de0 Allocated + ffffdf80148b0030 Allocated + ffffdf80148b14a0 Allocated + ffffdf80148b16f0 Allocated + ffffdf80148b1940 Allocated + ffffdf80148b1b90 Allocated + ffffdf80148b1de0 Allocated + ffffdf80148b1030 Allocated + [Maximum of 1024 items read; quitting early. Rerun with the '-force' option + to bypass this limit.] +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) + +[**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nblpool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nbpool.md b/windows-driver-docs-pr/debugger/-ndiskd-nbpool.md new file mode 100644 index 0000000000..2bab110e16 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nbpool.md @@ -0,0 +1,159 @@ +--- +title: ndiskd.nbpool +description: The ndiskd.nbpool extension displays information about a NET_BUFFER (NB) pool. +ms.assetid: 4FCD48B7-C469-4057-A279-20522B00E80B +keywords: ["ndiskd.nbpool Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nbpool +api_type: +- NA +--- + +# !ndiskd.nbpool + + +The **!ndiskd.nbpool** extension displays information about a [**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) (NB) pool. If you run this extension with no parameters, !ndiskd will display a list of all allocated NB pools in the system. + +``` +!ndiskd.nbpool [-handle ] [-allocations] [-find ] [-findva ] [-findpa ] +``` + +## Parameters + + + *-handle* +Handle of an NB pool. + + *-allocations* +Displays all allocated NBs. + + *-find* +Filter the list of allocated NBs using a debugger expression. + + *-findva* +Find NBs that straddle the given virtual address. + + *-findpa* +Find NBs that straddle the given physical address. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Enter the **!ndiskd.nbpool** command with no parameters to see a list of all allocated NB pools. In this example, look for the NB pool allocated by the Netio service with the Nnbf Tag. Its handle is ffffdf801308ca40. + +``` +2: kd> !ndiskd.nbpool + NB Pool Tag Allocated by + ffffdf8013963a40 UDNb NETIO!NetioAllocateNetBufferMdlAndDataPool+3c + ffffdf801396aa40 TSNb NETIO!NetioAllocateNetBufferMdlAndDataPool+3c + ffffdf801397d4c0 StBn NETIO!StreamPoolsInit+90 + ffffdf801308ca40 Nnbf NETIO!NetioInitializeNetBufferListLibrary+dd + ffffdf80131cba40 NDnd ndis!DriverEntry+615 +``` + +Click on the NB pool's handle or enter the **!ndiskd.nbpool -handle** command to examine its details. + +``` +2: kd> !ndiskd.nbpool ffffdf801308ca40 + + +NB POOL + + Ndis handle ffffdf801308ca40 + Allocation tag Nnbf + Owner + Allocated by NETIO!NetioInitializeNetBufferListLibrary+dd + + Flags [No flags set] + Structure size 0n176 + Data size 0 + + All allocated NBs +``` + +To explore the NBs contained in this NB pool, click on the "All allocated NBs" link at the bottom. Alternatively, you can also enter the **!ndiskd.nbpool -handle -allocations** command. As shown in the following example, this NB pool contains more than 1024 NBs so !ndiskd quit early. You can use the -force option to work around this limit and see all of the NBs in this NB pool. + +``` +2: kd> !ndiskd.nbpool ffffdf801308ca40 -allocations + + +ALL ALLOCATED NBs + + NB Active? + ffffdf8016ea4360 Allocated + ffffdf801744df50 Allocated + ffffdf8016932860 Allocated + ffffdf8016e31500 Allocated + ffffdf80174eade0 Allocated + ffffdf8017daa900 Allocated + ffffdf8017c8c680 Allocated + ffffdf80166b23b0 Allocated + ffffdf80164fea70 Allocated + ffffdf8012845990 Allocated + ffffdf8017d692d0 Allocated + ffffdf8017cdc090 Allocated + ffffdf8012771780 Allocated + ffffdf80158a3550 Allocated + ffffdf8012eef5c0 Allocated + ffffdf80127719d0 Allocated + ffffdf8015119570 Allocated + ffffdf8012e18d40 Allocated + ffffdf8017929b10 Allocated + ffffdf8016d4e430 Allocated + +... + + ffffdf8015ffbbd0 Allocated + ffffdf8015ec1b10 Freed + ffffdf80158e56d0 Allocated + ffffdf8016272110 Freed + ffffdf8015d8e030 Freed + ffffdf8015d8e770 Freed + ffffdf80158ddc30 Freed + ffffdf801584acc0 Freed + ffffdf8015846b40 Freed + ffffdf8015a06c50 Freed + ffffdf801480c300 Freed + ffffdf8015e48f50 Freed + ffffdf8015de64e0 Freed + ffffdf8015ddff50 Freed + [Maximum of 1024 items read; quitting early. Rerun with the '-force' option + to bypass this limit.] +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nbpool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndis.md b/windows-driver-docs-pr/debugger/-ndiskd-ndis.md new file mode 100644 index 0000000000..3a1992b150 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndis.md @@ -0,0 +1,55 @@ +--- +title: ndiskd.ndis +description: The ndiskd.ndis extension displays build information about ndis.sys. +ms.assetid: d852d6cc-7eba-4dad-aba5-3a2c9eac2f46 +keywords: ["ndiskd.ndis Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndis +api_type: +- NA +--- + +# !ndiskd.ndis + + +The **!ndiskd.ndis** extension displays build information about ndis.sys. + +``` +!ndiskd.ndis +``` + +## Parameters + + +This extension has no parameters. + +### DLL + +Ndiskd.dll + +Examples +-------- + +The following example shows that the debugee machine has a Checked Ndis build. + +``` +0: kd> !ndiskd.ndis +Checked Ndis +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndis%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndisevent.md b/windows-driver-docs-pr/debugger/-ndiskd-ndisevent.md new file mode 100644 index 0000000000..c666cb40db --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndisevent.md @@ -0,0 +1,183 @@ +--- +title: ndiskd.ndisevent +description: The !ndiskd.ndisevent extension displays an NDIS debug event log. +ms.assetid: E042CA22-6521-4DD4-9396-39EC587706D6 +keywords: ["ndiskd.ndisevent Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndisevent +api_type: +- NA +--- + +# !ndiskd.ndisevent + + +**Note**  Third party network driver developers are not expected to manually use this extension command. You can run it to see the information it displays but you are not able to reuse the details it provides in your driver. + +  + +The **!ndiskd.ndisevent** extension displays an NDIS debug event log. + +``` +!ndiskd.ndisevent [-handle ] [-tagtype ] +``` + +## Parameters + + + *-handle* +Required. Handle of the event log. + + *-tagtype* +Enum type of the tags. + +### DLL + +Ndiskd.dll + +Examples +-------- + +To see the output of the event log for a network adapter, !ndiskd provides a link to it in the State section of the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) output. This is easier than the manual method of finding an event log's handle from a miniport block and using that to run the **!ndiskd.ndisevent** extension. + +First, enter the **!ndiskd.netadapter** command with no parameters to see a list of network adapters and miniport drivers on the system. In the following example, look for the handle for the Marvell AVASTAR Wireless-AC Network Controller, ffffc804b9e6f1a0. + +``` +1: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffc804af2e3710 ffffc804b9e6f1a0 Marvell AVASTAR Wireless-AC Network Controller + ffffc804b99b9020 ffffc804b9c301a0 WAN Miniport (Network Monitor) + ffffc804b99b9020 ffffc804b9c2a1a0 WAN Miniport (IPv6) + ffffc804b99b9020 ffffc804b8a8a1a0 WAN Miniport (IP) + ffffc804ae9d7020 ffffc804b9ceb1a0 WAN Miniport (PPPOE) + ffffc804b9ca5900 ffffc804b9e601a0 WAN Miniport (PPTP) + ffffc804b99dc720 ffffc804b99b01a0 WAN Miniport (L2TP) + ffffc804b86581b0 ffffc804b9c6c1a0 WAN Miniport (IKEv2) + ffffc804ad4a7250 ffffc804b99651a0 WAN Miniport (SSTP) + ffffc804b11c4020 ffffc804b85821a0 Microsoft ISATAP Adapter + ffffc804b11c4020 ffffc804b71731a0 Microsoft ISATAP Adapter #2 + ffffc804ad725020 ffffc804b05e71a0 Surface Ethernet Adapter #2 + ffffc804b0bf0020 ffffc804b0c011a0 Bluetooth Device (Personal Area Network) + ffffc804aef695e0 ffffc804aed331a0 TAP-Windows Adapter V9 +``` + +Now, click on the link for that NetAdapter or enter the **!ndiskd.netadapter -handle** command to see its details. Look for the "Show state history" link to the right of the Device PnP field, in the State section. + +``` +1: kd> !ndiskd.netadapter ffffc804b9e6f1a0 + + +MINIPORT + + Marvell AVASTAR Wireless-AC Network Controller + + Ndis handle ffffc804b9e6f1a0 + Ndis API version v6.50 + Adapter context ffffc804af3b1100 + Driver ffffc804af2e3710 - mrvlpcie8897 v1.0 + Network interface ffffc804aea60a20 + + Media type 802.3 + Physical medium NdisPhysicalMediumUnspecified + Device instance PCI\VEN_11AB&DEV_2B38&SUBSYS_045E0001&REV_00\4&379f07b2&0&00E0 + Device object ffffc804b9e6f050 More information + MAC address c0-33-5e-13-22-f7 + + +STATE + + Miniport INITIALIZING + Device PnP ADDED Show state history + Datapath Normal + Operational status DOWN + Operational flags [No flags set] + Admin status ADMIN_UP + Media MediaConnectUnknown + Power D0 + References 1 Show detail + Total resets 0 + Pending OID None + Flags IN_INITIALIZE, NOT_BUS_MASTER, DEFAULT_PORT_ACTIVATED, + NOT_SUPPORTS_MEDIA_SENSE, DOES_LOOPBACK, MEDIA_CONNECTED + PnP flags PM_SUPPORTED, RECEIVED_START, HARDWARE_DEVICE + + +WDI + + This system supports WDI. + Learn more about the associated WDI state + + +BINDINGS + + Protocol list Driver Open Context + No protocols are bound to this miniport + + Filter list Driver Module Context + No filters are bound to this miniport + + + +MORE INFORMATION + + Driver handlers Task offloads + Power management PM protocol offloads + Pending OIDs Timers + Pending NBLs Receive side throttling + Wake-on-LAN (WoL) Packet filter + Receive queues Receive filtering + RSS NIC switch + Hardware resources Selective suspend + NDIS ports WMI guids + Diagnostic log +``` + +Now you can click the "Show state history" link or use the net adapter's handle to enter the **!ndiskd.netadapter -handle -log** command, which will show you the PnP event log for this miniport's miniport driver. + +``` +1: kd> !ndiskd.netadapter ffffc804b9e6f1a0 -log + + +MINIPORT PM & PNP EVENTS + + Event Timestamp (most recent event at bottom) + DeviceAdded + 13 ms later + DeviceStart + Mon Mar 20 21:27:07.106 2017 (UTC - 7:00) Now? + + Set a breakpoint on the next event +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndisevent%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndiskdversion.md b/windows-driver-docs-pr/debugger/-ndiskd-ndiskdversion.md new file mode 100644 index 0000000000..2870657495 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndiskdversion.md @@ -0,0 +1,75 @@ +--- +title: ndiskd.ndiskdversion +description: The ndiskd.ndiskdversion extension displays information about ndiskd itself. +ms.assetid: 12EB9E0F-7D2F-447B-B678-1E23EFF522FE +keywords: ["ndiskd.ndiskdversion Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndiskdversion +api_type: +- NA +--- + +# !ndiskd.ndiskdversion + + +The **!ndiskd.ndiskdversion** extension displays information about !ndiskd itself. + +``` +!ndiskd.ndiskdversion +``` + +## Parameters + + +This extension has no parameters. + +### DLL + +Ndiskd.dll + +Examples +-------- + +The following example shows output for **!ndiskd.ndiskdversion**. + +``` +1: kd> !ndiskd.ndiskdversion + NDISKD Version 17.01.00 (NDISKD codename "All your WDF are belong to us") + Build Release + Debugger CPU AMD64 + NDIS symbols Private More info + Hyperlinks (DML) Enabled + Unicode Enabled + Debug NDISKD Enabled +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndiskdversion%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndisref.md b/windows-driver-docs-pr/debugger/-ndiskd-ndisref.md new file mode 100644 index 0000000000..b13375b510 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndisref.md @@ -0,0 +1,121 @@ +--- +title: ndiskd.ndisref +description: The ndiskd.ndisref extension displays a debug log of a tracked reference count. +ms.assetid: 6860A567-1017-4184-B8DF-157467360FB9 +keywords: ["ndiskd.ndisref Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndisref +api_type: +- NA +--- + +# !ndiskd.ndisref + + +The **!ndiskd.ndisref** extension displays a debug log of a tracked reference count. + +``` +!ndiskd.ndisref [-handle ] [-tagtype ] [-stacks] [-tag ] [-refdebug] +``` + +## Parameters + + + *-handle* +Required. Handle of the refcount block. + + *-tagtype* +Enum type of the tags. + + *-stacks* +Includes stack traces (if available). + + *-tag* +Limits display to a single tag. + + *-refdebug* +Shows detailed debug log, if available. + +### DLL + +Ndiskd.dll + +Examples +-------- + +The following example passes the handle of an NDIS miniport driver to the **!ndiskd.ndisref** extension to display the refcount block for that driver. First, run [**!ndiskd.minidriver**](-ndiskd-minidriver.md) with no parameters to see a list of all miniport drivers on the system. In the example output below, look for the handle for the kdnic driver, ffffdf801418d650. + +``` +3: kd> !ndiskd.minidriver + ffffdf8015a98380 - tunnel + ffffdf801418d650 - kdnic +``` + +Using the miniport driver's handle, enter the **!ndiskd.ndisref -handle** command to see the refcount block for this miniport driver. The following example has the middle of the refcount block excised for brevity. + +``` +3: kd> !ndiskd.ndisref ffffdf801418d650 + + +REFCOUNT BLOCK + + Tag Number of references + 0n0 0n6293 Show stacks + 0n1 0n1045 Show stacks + 0n2 0n4294966717 Show stacks + 0n5 0n25048 Show stacks + 0n18 0n4294967293 Show stacks + 0n19 0n4294967295 Show stacks + 0n21 0n4294967036 Show stacks + 0n23 0n30818 Show stacks + 0n24 0n24693 Show stacks + 0n25 0n25808 Show stacks + +... + + 0n153 0n7 Show stacks + 0n154 0n3 Show stacks + 0n156 0n29972 Show stacks + 0n159 0n4294959128 Show stacks + 0n160 0n30892 Show stacks + 0n161 0n136 Show stacks + 0n162 0n4294951910 Show stacks + 0n163 0n30892 Show stacks + 0n164 0n136 Show stacks + 0n167 0n4294965996 Show stacks + + Include inactive tags +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.minidriver**](-ndiskd-minidriver.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndisref%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndisrwlock.md b/windows-driver-docs-pr/debugger/-ndiskd-ndisrwlock.md new file mode 100644 index 0000000000..9f7b4795fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndisrwlock.md @@ -0,0 +1,105 @@ +--- +title: ndiskd.ndisrwlock +description: The ndiskd.ndisrwlock extension displays information about an NDIS_RW_LOCK_EX lock structure. +ms.assetid: 853CBAFE-3899-4983-BFC7-933D3BC7ADA1 +keywords: ["ndiskd.ndisrwlock Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndisrwlock +api_type: +- NA +--- + +# !ndiskd.ndisrwlock + + +The **!ndiskd.ndisrwlock** extension displays information about an [**NDIS\_RW\_LOCK\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff567279) lock structure. + +``` +!ndiskd.ndisrwlock [-handle ] +``` + +## Parameters + + + *-handle* +Required. Handle of the lock structure. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Use the **!ndiskd.ndisrwlock** extension if you create your own RW lock and would want to inspect it. To obtain the handle for an RW lock, use the *poi* command to dereference the address of your driver's lock. The following snippet shows how to look at a lock that the TCIPIP protocol was using at the time of the example. + +``` +0: kd> !ndiskd.ndisrwlock poi(tcpip!gAleHashtableLock) + + +NDIS READ-WRITE LOCK + + Allocated by [NDIS generic object] + Exclusive access Not acquired + Read-only access 0 references + + Set a breakpoint on acquire/release +``` + +To observe the driver using this RW lock, click on the "Set a breakpoint on acquire/release" link at the bottom of the RW lock's details. After setting the breakpoint, enter the **g** command to let the debugee machine run and hit the breakpoint. + +``` +0: kd> ba r4 ffffe00bc3fc22f8 +0: kd> g +Breakpoint 0 hit +nt!KeTestSpinLock+0x3: +fffff802`0d69eb53 4885c0 test rax,rax +``` + +Now you can re-run the same **!ndiskd.ndisrwlock** command to see that this RW lock has one Read-only access reference. + +``` +0: kd> !ndiskd.ndisrwlock poi(tcpip!gAleHashtableLock) + + +NDIS READ-WRITE LOCK + + Allocated by [NDIS generic object] + Exclusive access Not acquired + Read-only access 1 reference + + Set a breakpoint on acquire/release +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NDIS\_RW\_LOCK\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff567279) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndisrwlock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndisslot.md b/windows-driver-docs-pr/debugger/-ndiskd-ndisslot.md new file mode 100644 index 0000000000..67bbd0884b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndisslot.md @@ -0,0 +1,118 @@ +--- +title: ndiskd.ndisslot +description: The **!ndiskd.ndisslot** extension displays the contents of an NDIS per-processor variable. +ms.assetid: 0EF37FE7-31A1-4A71-9CAC-E2A43F0EEBCF +keywords: ["ndiskd.ndisslot Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndisslot +api_type: +- NA +--- + +# !ndiskd.ndisslot + + +**Note**  Third party network driver developers are not expected to manually use this extension command. You can run it to see the information it displays but you are not able to reuse the details it provides in your driver. + +  + +The **!ndiskd.ndisslot** extension displays the contents of an NDIS per-processor variable. If you run this extension with no parameters, !ndiskd will display a list of all NDIS per-processor variables on the system. + +``` +!ndiskd.ndisslot [-handle ] [-itemtype ] +``` + +## Parameters + + + *-handle* +Handle of the slot. + + *-itemtype* +Type of the value stored in the slot. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.ndisslot** extension with no parameters to see a list of all per-processor slot variables. The following example output has excised the middle portion of the list for brevity. + +``` +1: kd> !ndiskd.ndisslot + Per-processor slot Summary of contents + ffffc804ae060000 - NDrw All values are zero + ffffc804ae060008 - NDrw All values are zero + ffffc804ae060010 - NDrw All values are zero + ffffc804ae060018 - NDrw All values are zero + ffffc804ae060020 - NDrw All values are zero + ffffc804ae060028 - NDrw All values are zero + ffffc804ae060030 - NDrw All values are zero + ffffc804ae060038 - NDrw All values are zero + ffffc804ae060040 - NDrw All values are zero + ffffc804ae060048 - NDrw All values are zero + +... + + ffffc804ae060910 - NDtk All values are zero + ffffc804ae060918 - NDtk All values are zero + ffffc804ae060920 - tsR All values are non-zero + ffffc804ae060928 - NDrw All values are zero + ffffc804ae060930 - NDtk All values are zero + ffffc804ae060938 - NDtk All values are zero + ffffc804ae060940 - NDtk All values are zero + ffffc804ae060948 - NDtk All values are zero + ffffc804ae060950 - NDrw All values are zero + ffffc804ae060958 - NDrw All values are zero + + Statistics + Descriptors 1 + Total slots 512 + Slots available 275 + Slots used 237 + Efficiency 46% +``` + +Clicking on one of the handles for the per-processor slot variables will show you the details for that variable. The following example uses the handle ffffc804ae060920 for the tsR variable, from the previous example. + +``` +1: kd> !ndiskd.ndisslot ffffc804ae060920 + Processor Slot value + 00 00000006 + 01 00000006 + 02 00000006 + 03 00000006 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndisslot%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-ndisstack.md b/windows-driver-docs-pr/debugger/-ndiskd-ndisstack.md new file mode 100644 index 0000000000..8aab9a7930 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-ndisstack.md @@ -0,0 +1,67 @@ +--- +title: ndiskd.ndisstack +description: The !ndiskd.ndisstack extension displays a debug stack trace. +ms.assetid: 939DEC34-3D20-41FE-B5A8-DDF810195B07 +keywords: ["ndiskd.ndisstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.ndisstack +api_type: +- NA +--- + +# !ndiskd.ndisstack + + +**Note**  Third party network driver developers are not expected to manually use this extension command. You can run it to see the information it displays but you are not able to reuse the details it provides in your driver. + +  + +The **!ndiskd.ndisstack** extension displays a debug stack trace. + +``` +!ndiskd.ndisstack [-handle ] [-statistics] +``` + +## Parameters + + + *-handle* +Required. Handle of the stack block. + + *-statistics* +Shows debugging statistics. + +### DLL + +Ndiskd.dll + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.ndisstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netadapter.md b/windows-driver-docs-pr/debugger/-ndiskd-netadapter.md new file mode 100644 index 0000000000..2d853c7cd9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netadapter.md @@ -0,0 +1,295 @@ +--- +title: ndiskd.netadapter +description: The ndiskd.netadapter extension displays information about NDIS miniports, or network adapters, that are active on the system. +ms.assetid: 7D55F7CE-5DDB-4C80-8C27-F619F2FB7F15 +keywords: ["ndiskd.netadapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netadapter +api_type: +- NA +--- + +# !ndiskd.netadapter + + +The **!ndiskd.netadapter** extension displays information about NDIS miniports, or network adapters, that are active on the system. If you run this command with no parameters, !ndiskd will display a list of all network adapters. + +``` + !ndiskd.netadapter [-handle ] [-basic] [-diag] [-state] [-bindings] + [-ports] [-offloads] [-filterdb] [-timers] [-rst] + [-pm] [-ss] [-aoac] [-wol] [-protocoloffloads] + [-rss] [-hw] [-device] [-wmi] [-customwmi] + [-ndiswmi] [-ref] [-log] [-grovel] [-findname ] + [-rcvfilter] [-nicswitch] [-rcvqueues] [-nicswitches] [-iov] + [-vfs] [-vports] [-iftrace] [-ip] +``` + +## Parameters + + + *-handle* +Handle of an NDIS miniport. + + *-basic* +Displays summary information about the miniport. + + *-diag* +Displays auto-diagnostic alerts (if any). + + *-state* +Displays the miniport's current state. + + *-bindings* +Displays miniport bindings. + + *-ports* +Shows a list of NDIS ports. + + *-offloads* +Shows task offload state and capabilities. + + *-filterdb* +Shows the current packet filter. + + *-timers* +Shows timer objects allocated by the miniport. + + *-rst* +Shows Receive-Side Throttling state. + + *-pm* +Shows power management state and capabilities. + + *-ss* +Shows Selective Suspend state. + + *-aoac* +Shows AOAC (Connected Standby) state. + + *-wol* +Shows Wake-on-LAN (WoL) configuration. + + *-protocoloffloads* +Shows active power management protocol offloads. + + *-rss* +Shows Receive Side Scaling parameters. + + *-hw* +Displays hardware resources. + + *-device* +Shows information about the underlying NT device object. + + *-wmi* +Shows WMI GUIDs registered to the adapter. + + *-customwmi* +Shows custom WMI GUIDs registered by the miniport. + + *-ndiswmi* +Shows NDIS-provided WMI GUIDs. + + *-ref* +Shows a breakdown of references on the miniport. + + *-log* +Displays a PnP and Power event log. + + *-grovel* +Forces a search for miniport blocks in memory. + + *-findname* +Filters miniports by name prefix. + + *-rcvfilter* +Shows receive filtering capabilities. + + *-nicswitch* +Shows NIC switch capabilities. + + *-rcvqueues* +Shows receive queues. + + *-nicswitches* +Shows NIC switches. + + *-iov* +Shows SR-IOV (Single Root I/O Virtualization) capabilities. + + *-vfs* +Shows SR-IOV VFs (Virtual Filters). + + *-vports* +Shows Vports (Virtual ports). + + *-ifrtrace* +Shows the in-flight recorder's trace. + + *-ip* +Shows IP addresses on the network's interface. + +### DLL + +Ndiskd.dll + +Examples +-------- + +By running **!ndiskd.netadapter** with no parameters, you can get a list of all network adapters on the system along with their associated miniport drivers. In this example output, look for the Microsoft Kernel Debug Network Adapter, whose handle is ffffdf80140c71a0. For more information about what the Kernel Debug Network Adapter is, see [Kernel debugging over the network](https://go.microsoft.com/fwlink/p/?linkid=845868) on the NDIS blog. + +``` +3: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffdf8015a98380 ffffdf8015aa11a0 Microsoft ISATAP Adapter #2 + ffffdf801418d650 ffffdf80140c71a0 Microsoft Kernel Debug Network Adapter +``` + +By clicking on the handle for the miniport driver or entering the **!ndiskd.netadapter -handle**, you can now see all of NDIS's state on that device. This can be very helpful as a starting place for troubleshooting a network driver or for figuring out where an issue is in the network stack. For example, you can see the Datapath state for the driver and see whether it is connected or not. + +At the bottom of the report for this net adapter, there are many other links you can click on to explore further information, such as any pending OIDs and the state of task offloads. These links correspond to many of the parameters for **!ndiskd.netadapter**. + +``` +3: kd> !ndiskd.netadapter ffffdf80140c71a0 + + +MINIPORT + + Microsoft Kernel Debug Network Adapter + + Ndis handle ffffdf80140c71a0 + Ndis API version v6.20 + Adapter context ffffdf80147d7230 + Driver ffffdf801418d650 - kdnic v4.2 + Network interface ffffdf80139b3a20 + + Media type 802.3 + Physical medium NdisPhysicalMediumOther + Device instance ROOT\KDNIC\0000 + Device object ffffdf80140c7050 More information + MAC address 18-03-73-c1-e8-72 + + +STATE + + Miniport Running + Device PnP Started Show state history + Datapath Normal + Interface Up + Media Connected + Power D0 + References 0n10 Show detail + Total resets 0 + Pending OID None + Flags NOT_BUS_MASTER, ALLOW_BUGCHECK_CALLBACK, + BUGCHECK_CALLBACK_REGISTERED, DEFAULT_PORT_ACTIVATED, + SUPPORTS_MEDIA_SENSE, DOES_NOT_DO_LOOPBACK, + MEDIA_CONNECTED + PnP flags VIRTUAL_DEVICE, HIDDEN, NO_HALT_ON_SUSPEND, + RECEIVED_START + + +BINDINGS + + Protocol list Driver Open Context + MSLLDP ffffdf80120a5c10 ffffdf8015a749c0 ffffdf8015d325e0 + TCPIP ffffdf80131cc010 ffffdf801494a650 ffffdf801494aa50 + NDISUIO ffffdf8015a58140 ffffdf8015a78c10 ffffdf8015a77e00 + TCPIP6 ffffdf80131c9c10 ffffdf80147875a0 ffffdf801494f010 + (RASPPPOE) Not running + RSPNDR ffffdf80120a0c10 ffffdf8015a79c10 ffffdf8015a79010 + LLTDIO ffffdf8015a5f9b0 ffffdf801406f010 ffffdf8015a786c0 + (RDMANDK) ffffdf801406d8f0 Declined with NDIS_STATUS_NOT_RECOGNIZED + + Filter list Driver Module Context + WFP 802.3 MAC Layer LightWeight Filter-0000 + ffffdf80139a5a70 ffffdf801494c670 ffffdf801494a010 + QoS Packet Scheduler-0000 + ffffdf8014039d90 ffffdf801494dc70 ffffdf80147dc2b0 + WFP Native MAC Layer LightWeight Filter-0000 + ffffdf80139fcd70 ffffdf8014950c70 ffffdf8014950880 + + + +MORE INFORMATION + + Driver handlers Task offloads + Power management PM protocol offloads + Pending OIDs Timers + Pending NBLs Receive side throttling + Wake-on-LAN (WoL) Packet filter + Receive queues Receive filtering + RSS NIC switch + Hardware resources Selective suspend + NDIS ports WMI guids + Diagnostic log + +``` + +As example of using **!ndiskd.netadapter** as a starting place for further debugging, click on the "Driver handlers" link at the bottom of the report to see a list of all registered driver callback handlers for this net adapter's miniport driver. In the following example, clicking the link causes !ndiskd to run the [**!ndiskd.minidriver**](-ndiskd-minidriver.md) extension with the handle of this net adapter's miniport driver. The miniport driver is the kdnic 4.2 and its handle is ffffdf801418d650. + +``` +3: kd> !ndiskd.minidriver ffffdf801418d650 -handlers + + +HANDLERS + + NDIS Handler Function pointer Symbol (if available) + InitializeHandlerEx fffff80f1fd78230 bp + SetOptionsHandler fffff80f1fd72800 bp + HaltHandlerEx fffff80f1fd78040 bp + ShutdownHandlerEx fffff80f1fd722c0 bp + + CheckForHangHandlerEx fffff80f1fd72810 bp + ResetHandlerEx fffff80f1fd72f70 bp + + PauseHandler fffff80f1fd78000 bp + RestartHandler fffff80f1fd78940 bp + + OidRequestHandler fffff80f1fd71c90 bp + CancelOidRequestHandler fffff80f1fd722c0 bp + DirectOidRequestHandler [None] + CancelDirectOidRequestHandler [None] + DevicePnPEventNotifyHandler fffff80f1fd789a0 bp + + SendNetBufferListsHandler fffff80f1fd71870 bp + ReturnNetBufferListsHandler fffff80f1fd71b50 bp + CancelSendHandler fffff80f1fd722c0 bp +``` + +You can now click the "bp" link to the right of each handler to set a breakpoint on that handler to debug a particular problem. For example, if there is a hang in the datapath, you can investigate the driver's SendNetBufferListsHandler or ReturnNetBufferListsHandler. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Kernel debugging over the network](https://go.microsoft.com/fwlink/p/?linkid=845868) + +[**!ndiskd.minidriver**](-ndiskd-minidriver.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netadapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netpacket.md b/windows-driver-docs-pr/debugger/-ndiskd-netpacket.md new file mode 100644 index 0000000000..201380110e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netpacket.md @@ -0,0 +1,181 @@ +--- +title: ndiskd.netpacket +description: The ndiskd.netpacket extension displays information about a NET_PACKET structure. +ms.assetid: 304BA2CF-B6BC-452C-8543-9B872054AA9E +keywords: ["ndiskd.netpacket Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netpacket +api_type: +- NA +--- + +# !ndiskd.netpacket + + +The **!ndiskd.netpacket** extension displays information about a [NET\_PACKET](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet) structure. + +For more information about the Network Adapter WDF Class Extension (NetAdapterCx), see [Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx). + +``` +!ndiskd.netpacket [-handle ] [-basic] [-layout] [-checksum] [-data] +``` + +## Parameters + + + *-handle* +Required. Address of a NET\_PACKET. + + *-basic* +Displays basic information. + + *-layout* +Displays packet protocol layout. + + *-checksum* +Displays packet checksum information. + + *-data* +Dumps the payload memory. + +### DLL + +Ndiskd.dll + +Examples +-------- + +**Note**  See [Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) to see a diagram explaining the relationship of the NET\_PACKET object with other objects in the NetAdapterCx. + +  + +To obtain a handle for a NET\_PACKET, follow these steps: + +1. Run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension. +2. Click on the handle for a NetAdapter that has a NetAdapterCx driver installed. +3. Click the "More Information" link to the right of the NetAdapter's NETADAPTER object to run the [**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) extension. +4. Enter the **!ndiskd.cxadapter** command with the *-datapath* parameter to see that NETADAPTER's datapath queues. +5. Click on the handle for one of the datapath queues. +6. Click on the handle for that datapath queue's ring buffer. +7. Click on the "List all elements" link at the bottom of the ring buffer details to see the elements it contains. + +For details on Steps 1-4 of this procedure, see the examples on the **!ndiskd.cxadapter** topic. For details on Step 5 of this procedure, see the examples on the [**!ndiskd.netqueue**](-ndiskd-netqueue.md) topic. For details on Steps 6-7 of this procedure, see the examples on the [**!ndiskd.netrb**](-ndiskd-netrb.md) topic. +In the following example, look for the handle for the first NET\_PACKET, ffffd1022d000040. + +``` +0: kd> !ndiskd.netrb ffffd1022d000000 -dump + + [000] ffffd1022d000040 - NET_PACKET + [001] ffffd1022d0000c0 - NET_PACKET + [002] ffffd1022d000140 - NET_PACKET + [003] ffffd1022d0001c0 - NET_PACKET + [004] ffffd1022d000240 - NET_PACKET + [005] ffffd1022d0002c0 - NET_PACKET + + ... + + [07b] ffffd1022d003dc0 - NET_PACKET + [07c] ffffd1022d003e40 - NET_PACKET + [07d] ffffd1022d003ec0 - NET_PACKET + [07e] ffffd1022d003f40 - NET_PACKET + [07f] ffffd1022d003fc0 - NET_PACKET +``` + +By clicking on the handle for this NET\_PACKET or by entering **!ndiskd.netpacket -handle** on the command line, you can see details for this NET\_PACKET, including the ring buffer that contains it, the datapath queue that contains its ring buffer, and the handle for its first fragment. + +``` +0: kd> !ndiskd.netpacket ffffd1022d000040 + + + NET_PACKET ffffd1022d000040 Ring Buffer ffffd1022d000000 + First fragment ffffd1022d000040 NETTXQUEUE ffffd1022f512700 + + Client Context ffffd1022d000090 + + Show protocol layout + Show checksum information + Dump data payload +``` + +You can now combine the basic description with any of the other **!ndiskd.netpacket** parameters, or all of them, to see specific information for this fragment. The following example uses all parameters. + +``` +0: kd> !ndiskd.netpacket ffffd1022d000040 -basic -layout -checksum -data + + NET_PACKET ffffd1022d000040 Ring Buffer ffffd1022d000000 + First fragment ffffd1022d000040 NETTXQUEUE ffffd1022f512700 + + Client Context ffffd1022d000090 + + + Protocol Layout + + Layer 2 Type ETHERNET + Header Length 0n14 + + Layer 3 Type IPV4_NO_OPTIONS + Header Length 0n20 + + Layer 4 Type UDP + Header Length 8 + + + Checksum Information + + Layer 2 TX_PASSTHROUGH + Layer 3 TX_REQUIRED + Layer 4 TX_PASSTHROUGH + + + Payload data + + Fragment ffffd1022d000040 + ffffd102303e8332 00 00 01 02 71 68 0a 89-be 39 e0 00 00 16 94 04 ····qh···9······ + ffffd102303e8342 00 00 22 00 fa 01 00 00-00 01 03 00 00 00 e0 00 ··"············· + ffffd102303e8352 00 fc +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx) + +[Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) + +[NET\_PACKET](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) + +[**!ndiskd.netqueue**](-ndiskd-netqueue.md) + +[**!ndiskd.netrb**](-ndiskd-netrb.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netpacket%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netpacketfragment.md b/windows-driver-docs-pr/debugger/-ndiskd-netpacketfragment.md new file mode 100644 index 0000000000..21ce133d45 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netpacketfragment.md @@ -0,0 +1,130 @@ +--- +title: ndiskd.netpacketfragment +description: The ndiskd.netpacketfragment extension displays information about a NET_PACKET_FRAGMENT structure. +ms.assetid: 2075D682-45F5-414D-A8ED-0494B3550C77 +keywords: ["ndiskd.netpacketfragment Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netpacketfragment +api_type: +- NA +--- + +# !ndiskd.netpacketfragment + + +The **!ndiskd.netpacketfragment** extension displays information about a [NET\_PACKET\_FRAGMENT](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet-fragment) structure. + +For more information about the Network Adapter WDF Class Extension (NetAdapterCx), see [Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx). + +``` +!ndiskd.netpacketfragment [-handle ] +``` + +## Parameters + + + *-handle* +Required. Address of a NET\_PACKET\_FRAGMENT. + +### DLL + +Ndiskd.dll + +Examples +-------- + +**Note**  See [Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) to see a diagram explaining the relationship of the NET\_PACKET object with other objects in the NetAdapterCx. + +  + +To obtain a handle for a NET\_PACKET, follow these steps: + +1. Run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension. +2. Click on the handle for a NetAdapter that has a NetAdapterCx driver installed. +3. Click the "More Information" link to the right of the NetAdapter's NETADAPTER object to run the [**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) extension. +4. Enter the **!ndiskd.cxadapter** command with the *-datapath* parameter to see that NETADAPTER's datapath queues. +5. Click on the handle for one of the datapath queues. +6. Click on the handle for that datapath queue's ring buffer. +7. Click on the "List all elements" link at the bottom of the ring buffer details to see the elements it contains. +8. Click on one of the [NET\_PACKET](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet) objects in the ring buffer's list of elements. + +For details on Steps 1-4 of this procedure, see the examples on the **!ndiskd.cxadapter** topic. For details on Step 5 of this procedure, see the examples on the [**!ndiskd.netqueue**](-ndiskd-netqueue.md) topic. For details on Steps 6-7 of this procedure, see the examples on the [**!ndiskd.netrb**](-ndiskd-netrb.md) topic. For details on Step 8 of this procedure, see the examples on the [**!ndiskd.netpacket**](-ndiskd-netpacket.md) topic. +In the following example, look for the handle for the first fragment of this NET\_PACKET, ffffd1022d000040. + +``` +0: kd> !ndiskd.netpacket ffffd1022d000040 + + + NET_PACKET ffffd1022d000040 Ring Buffer ffffd1022d000000 + First fragment ffffd1022d000040 NETTXQUEUE ffffd1022f512700 + + Client Context ffffd1022d000090 + + Show protocol layout + Show checksum information + Dump data payload +``` + +By clicking on the handle for the first fragment or by entering the **!ndiskd.netpacketfragment -handle** command on the command line, you can see details for this NET\_PACKET\_FRAGMENT, including its Virtual Address, capacity, and whether or not it is the last packet in the NET\_PACKET chain of fragments. + +``` +0: kd> !ndiskd.netpacketfragment ffffd1022d000040 + + NET_PACKET_FRAGMENT ffffd1022d000040 + + Virtual Address ffffd102303e82f8 + Capacity 0n92 + Valid Length 0n34 + Offset 0n58 + + Last packet of chain +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx) + +[Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) + +[NET\_PACKET\_FRAGMENT](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet-fragment) + +[NET\_PACKET](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-packet) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) + +[**!ndiskd.netqueue**](-ndiskd-netqueue.md) + +[**!ndiskd.netrb**](-ndiskd-netrb.md) + +[**!ndiskd.netpacket**](-ndiskd-netpacket.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netpacketfragment%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netqueue.md b/windows-driver-docs-pr/debugger/-ndiskd-netqueue.md new file mode 100644 index 0000000000..96ff48d171 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netqueue.md @@ -0,0 +1,128 @@ +--- +title: ndiskd.netqueue +description: The ndiskd.netqueue extension displays information about a NETTXQUEUE or NETRXQUEUE object. +ms.assetid: 101F29AA-5CEE-41F8-A3EC-AA2E74B8E074 +keywords: ["ndiskd.netqueue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netqueue +api_type: +- NA +--- + +# !ndiskd.netqueue + + +The **!ndiskd.netqueue** extension displays information about a NETTXQUEUE or NETRXQUEUE object. + +For more information about the Network Adapter WDF Class Extension (NetAdapterCx), see [Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx). + +``` +!ndiskd.netqueue [-handle ] [-basic] +``` + +## Parameters + + + *-handle* +Required. Handle of a NETTXQUEUE or NETRXQUEUE. + + *-basic* +Displays basic information. + +### DLL + +Ndiskd.dll + +Examples +-------- + +**Note**  See [Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) to see a diagram explaining the relationship of the NETTXQUEUE and NETRXQUEUE objects with other objects in the NetAdapterCx. + +  + +To obtain a handle for a NETTXQUEUE or NETRXQUEUE, follow these steps: + +1. Run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension. +2. Click on the handle for a NetAdapter that has a NetAdapterCx driver installed. +3. Click the "More Information" link to the right of the NetAdapter's NETADAPTER object to run the [**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) extension. +4. Enter the **!ndiskd.cxadapter** command with the *-datapath* parameter to see that NETADAPTER's datapath queues. + +For details on this procedure, see the examples on the **!ndiskd.cxadapter** topic. +In the following example, look for the handle for this NETADAPTER's NETTXQUEUE, ffffd1022f512700. + +``` +0: kd> !ndiskd.cxadapter ffffd1022f1a0720 -basic -datapath + + +NETADAPTER + + Miniport ffffd1022d048030 - Realtek PCIe GBE Family Controller NetAdapter Sample Driver #2 + NETADAPTER 00002efdd0e5f988 + WDFDEVICE 00002efdcf45f2f8 + + Event Callbacks Function pointer Symbol (if available) + EvtAdapterSetCapabilities fffff800341519ac RtEthSample+19ac + EvtAdapterCreateTxQueue fffff80034151508 RtEthSample+1508 + EvtAdapterCreateRxQueue fffff800341510ec RtEthSample+10ec + + +DATAPATH QUEUES + + NETTXQUEUE ffffd1022f512700 + NETRXQUEUE ffffd1022cc7b0d0 +``` + +By clicking on the NETTXQUEUE's handle or entering the **!ndiskd.netqueue -handle** command on the command line, you can see details for this queue, including the handle to its companion WDF object, the handle to its ring buffer, and function pointers for its registered callbacks. + +``` +0: kd> !ndiskd.netqueue ffffd1022f512700 + + NETTXQUEUE 00002efdd0aed9a8 + Ring buffer ffffd1022d000000 + + Switch to EC thread + + Event Callbacks Function pointer Symbol (if available) + EvtQueueAdvance fffff80034152af8 RtEthSample+2af8 + EvtQueueArmNotification fffff80034159a94 RtEthSample+9a94 + EvtQueueCancel fffff800341598d8 RtEthSample+98d8 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx) + +[Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netqueue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netrb.md b/windows-driver-docs-pr/debugger/-ndiskd-netrb.md new file mode 100644 index 0000000000..477ff405cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netrb.md @@ -0,0 +1,154 @@ +--- +title: ndiskd.netrb +description: The ndiskd.netrb extension displays information about a NET_RING_BUFFER structure. +ms.assetid: 2D749E7E-00A5-422B-B785-B8DB3393A74F +keywords: ["ndiskd.netrb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netrb +api_type: +- NA +--- + +# !ndiskd.netrb + + +The **!ndiskd.netrb** extension displays information about a [NET\_RING\_BUFFER](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-ring-buffer) structure. + +For more information about the Network Adapter WDF Class Extension (NetAdapterCx), see [Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx). + +``` +!ndiskd.netrb [-handle ] [-basic] [-dump] [-elementtype ] +``` + +## Parameters + + + *-handle* +Required. Address of a NET\_RING\_BUFFER. + + *-basic* +Displays basic information. + + *-dump* +Displays information about each element in the NET\_RING\_BUFFER. + + *-elementtype* +A string for the data type to use when referring to a ring buffer element. + +### DLL + +Ndiskd.dll + +Examples +-------- + +**Note**  See [Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) to see a diagram explaining the relationship of the NET\_RING\_BUFFER object with other objects in the NetAdapterCx. + +  + +To obtain a handle for a NET\_RING\_BUFFER, follow these steps: + +1. Run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension. +2. Click on the handle for a NetAdapter that has a NetAdapterCx driver installed. +3. Click the "More Information" link to the right of the NetAdapter's NETADAPTER object to run the [**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) extension. +4. Enter the **!ndiskd.cxadapter** command with the *-datapath* parameter to see that NETADAPTER's datapath queues. +5. Click on the handle for one of the datapath queues. + +For details on Steps 1-4 of this procedure, see the examples on the **!ndiskd.cxadapter** topic. For details on Step 5 of this procedure, see the examples on the [**!ndiskd.netqueue**](-ndiskd-netqueue.md) topic. +In the following example, look for the handle for this NETTXQUEUE's ring buffer, ffffd1022d000000. + +``` +0: kd> !ndiskd.netqueue ffffd1022f512700 + + NETTXQUEUE 00002efdd0aed9a8 + Ring buffer ffffd1022d000000 + + Switch to EC thread + + Event Callbacks Function pointer Symbol (if available) + EvtQueueAdvance fffff80034152af8 RtEthSample+2af8 + EvtQueueArmNotification fffff80034159a94 RtEthSample+9a94 + EvtQueueCancel fffff800341598d8 RtEthSample+98d8 +``` + +By clicking on the handle for the ring buffer or by entering the **!ndiskd.netrb -handle** command on the command line, you can see details for this NET\_RING\_BUFFER, including how many elements it contains and the address of its Begin and End indices. + +``` +0: kd> !ndiskd.netrb ffffd1022d000000 + + NET_RING_BUFFER ffffd1022d000000 + + Number of elements 0x080 + Owned by OS 0x080 + Owned by Client 00000 + + Begin Index 0x078 (ffffd1022d003c40 - NET_PACKET) + Next Index 0x078 (ffffd1022d003c40 - NET_PACKET) + End Index 0x078 (ffffd1022d003c40 - NET_PACKET) + + List all elements +``` + +To see this NET\_RING\_BUFFER's elements, either click the "List all elements" link at the bottom of its details or enter the **!ndiskd.netrb -dump** command on the command line. The following example has had the middle elements excised for brevity. + +``` +0: kd> !ndiskd.netrb ffffd1022d000000 -dump + + [000] ffffd1022d000040 - NET_PACKET + [001] ffffd1022d0000c0 - NET_PACKET + [002] ffffd1022d000140 - NET_PACKET + [003] ffffd1022d0001c0 - NET_PACKET + [004] ffffd1022d000240 - NET_PACKET + [005] ffffd1022d0002c0 - NET_PACKET + + ... + + [07b] ffffd1022d003dc0 - NET_PACKET + [07c] ffffd1022d003e40 - NET_PACKET + [07d] ffffd1022d003ec0 - NET_PACKET + [07e] ffffd1022d003f40 - NET_PACKET + [07f] ffffd1022d003fc0 - NET_PACKET +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Network Adapter WDF Class Extension (Cx)](https://docs.microsoft.com/windows-hardware/drivers/netcx) + +[Summary of Objects](https://docs.microsoft.com/windows-hardware/drivers/netcx/summary-of-objects) + +[NET\_RING\_BUFFER](https://docs.microsoft.com/windows-hardware/drivers/netcx/net-ring-buffer) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) + +[**!ndiskd.netqueue**](-ndiskd-netqueue.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netrb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-netreport.md b/windows-driver-docs-pr/debugger/-ndiskd-netreport.md new file mode 100644 index 0000000000..46ef1d0fbf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-netreport.md @@ -0,0 +1,108 @@ +--- +title: ndiskd.netreport +description: The ndiskd.netreport extension generates a visual report of the entire network stack. +ms.assetid: 0FC134A8-8D91-4299-8D15-4E8EDD9ED855 +keywords: ["ndiskd.netreport Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.netreport +api_type: +- NA +--- + +# !ndiskd.netreport + + +The **!ndiskd.netreport** extension generates a visual report of the entire network stack. The report **!ndiskd.netreport** generates is an HTML file, and it will give you a link to its location. The HTML file contains detailed information about the network stack, so if you need to share it for analysis you can email it instead of having to send a large crash dump file. + +``` +!ndiskd.netreport [-outputpath ] [-jsononly] +``` + +## Parameters + + + *-outputpath* +Specifies where to write the report file. + + *-jsononly* +Only writes the raw data, no HTML. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.netreport** extension to draw a box diagram of your network stack. + +``` +1: kd> !ndiskd.netreport + + +NETWORK STACK REPORT + + + Want more stuff? Rerun with the -verbose flag + + + Report was saved to C:\Users\******\AppData\Local\Temp\NKDFE9F.html + View the report Send in email +``` + +Click the "View the report" link at the bottom to see the report generated. The following image shows a net report generated from a crash dump file. Each vertical stack is a network adapter, broken down into layers showing the components of the stack. The color of each box is generated by hashing the name of the component, which means the same components will render with the same color every time you run the report. This means you can easily pick out a particular driver or adapter if you are debugging an issue with it. + +![network debug report from crash dump](images/!ndiskd-netreport-crashdump.png) + +As a comparison, the following image shows a net report generated from an active system instead of a crash dump file. Note that there are two more options at the bottom of the HTML page to "Show data flows" and "Simulate packets," and there is a fourth tab at the top of the report for "Data flows." These options appeared because the debugee machine had NBL tracking enabled, which lets **!ndiskd.netreport** parse the NBL tracking log to display the information visually. If NBL tracking is not turned on, these options will not appear. For more information about NBL tracking and the NBL log, see [**!ndiskd.nbllog**](-ndiskd-nbllog.md). + +By checking the "Show data flows" box, you can see the paths where the data is flowing. By checking the "Simulate packets" box, you can see animated circles moving up and down the data flow paths. Each circle represents a network packet. + +![network debug report from active system](images/!ndiskd-netreport-activesystem.png) + +This second example from an active system also shows another difference from the first example, which used a crash dump file. The target debugee machine in the second example was provisioned for kernel debugging over a network, so you can see the network adapter on the stack with the data flows is the Microsoft Kernel Debug Network Adapter. This adapter is usually hidden unless kernel debugging has been enabled on the debugee machine. In reality, the Kernel Debug Network Adapter has reserved the machine's Ethernet adapter for the debug session, so traffic is flowing over Ethernet. + +The ability to visualize the network stack and see where traffic is flowing can enable you to quickly identify where a problem might be. This can be particularly helpful for virtual switches or servers, which have more complicated network diagrams than the previous examples. For example, on a Windows Server that uses NIC Teaming, you can see if multiple network stacks cross each other to balance the traffic load and identify if there is an issue at the bottom of one stack that is affecting another stack. To see an example of a network debug report that shows this, see [Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311). For more information about NIC Teaming, see [Using NIC Teaming for Network Subsystem Performance](https://msdn.microsoft.com/library/windows/hardware/dn567652). + +**!ndiskd.netreport** also has other tabs at the top of the page for System, Summaries, and Data Flows (if applicable). These tabs contain further useful information about the state of the network stack. The following image shows the Network Interfaces tab, under the Summaries tab. The table in this tab lets you see more information about the names and identifiers for the network interfaces in the system. + +![network debug report network interfaces](images/!ndiskd-netreport-activesystem-networkinterfaces.png) + +The Data flows tab, which appears if NBL tracking was enabled on the target system, shows a table of traffic events and details about each one. The following image shows the Data flows tab from the active system in the second example debug report described previously. + +![network debug report data flows](images/!ndiskd-netreport-activesystem-dataflows.png) + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.nbllog**](-ndiskd-nbllog.md) + +[Using NIC Teaming for Network Subsystem Performance](https://msdn.microsoft.com/library/windows/hardware/dn567652) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.netreport%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-nwadapter.md b/windows-driver-docs-pr/debugger/-ndiskd-nwadapter.md new file mode 100644 index 0000000000..74ad10b032 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-nwadapter.md @@ -0,0 +1,60 @@ +--- +title: ndiskd.nwadapter +description: The ndiskd.nwadapter extension displays information about one or more nwifi ADAPT structures. If you run this extension with no parameters, ndiskd will display a list of all nwifi ADAPT structures. +ms.assetid: 6CDB8F35-B686-45FD-A940-A770D4D62E51 +keywords: ["ndiskd.nwadapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.nwadapter +api_type: +- NA +--- + +# !ndiskd.nwadapter + + +The **!ndiskd.nwadapter** extension displays information about one or more nwifi!ADAPT structures. If you run this extension with no parameters, !ndiskd will display a list of all nwifi!ADAPT structures. + +``` +!ndiskd.nwadapter [-handle ] +``` + +## Parameters + + + *-handle* +Address of an ADAPT block. + +### DLL + +Ndiskd.dll + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.nwadapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-oid.md b/windows-driver-docs-pr/debugger/-ndiskd-oid.md new file mode 100644 index 0000000000..78d897ce34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-oid.md @@ -0,0 +1,157 @@ +--- +title: ndiskd.oid +description: The ndiskd.oid extension displays information about an NDIS OID request. +ms.assetid: FCDE2F78-98C0-4437-999A-4566FEB5D7BB +keywords: ["ndiskd.oid Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.oid +api_type: +- NA +--- + +# !ndiskd.oid + + +The **!ndiskd.oid** extension displays information about an NDIS OID request. If you run this extension with no parameters, !ndiskd will display a list of all pending OID requests on all miniports and filters. Each miniport or filter has at most one pending OID request and any number of queued OID requests. + +Note that filters typically clone OID requests and pass the clone down. This means that even if a protocol issues a single OID request, there may be multiple instances of cloned requests: one in each filter and another in the miniport. **!ndiskd.oid** will show each clone separately, so you may see more pending OIDs than the protocol has actually issued. + +``` +!ndiskd.oid [-handle ] [-legacyoid] [-nolimit>] [-miniport ] +``` + +## Parameters + + + *-handle* +Handle of an NDIS\_OID\_REQUEST + + *-legacyoid* +Treats as a legacy NDIS\_REQUEST instead of an NDIS\_OID\_REQUEST. + + *-nolimit* +Does not limit the number of pending OIDs that are displayed. + + *-miniport* +Finds pending OID requests on this miniport's stack. + +### DLL + +Ndiskd.dll + +Remarks +------- + +**!ndiskd.oid** shows you a list of all the pending OIDs on the system at a time, so it can be very helpful in debugging system hangs or [0x9F bug check](https://msdn.microsoft.com/library/windows/hardware/ff559329) situations (DRIVER\_POWER\_STATE\_FAILURE). For example, suppose analyzing a fictitious 0x9F bug check revealed that the system was hung on an IRP and was waiting for NDIS. In NDIS, IRPs from the OS are translated into OIDs, including power transitions, so by running **!ndiskd.oid** you could see that, in this example, a device at the bottom of the stack might have been clinging to an [OID\_PNP\_SET\_POWER](https://msdn.microsoft.com/library/windows/hardware/ff569780) and hung the rest of the stack. NDIS drivers should not pend an OID for more than one second, so you could then investigate why that device kept the OID pending for too long to try to solve the issue. + +Examples +-------- + +To see an example of pending OIDS on a system that is running normally, set a breakpoint on a miniport's OID request handler routine (in the miniport's corresponding miniport driver). First, run the [**!ndiskd.minidriver**](-ndiskd-minidriver.md) command with no parameters to get a list of miniport drivers on the system. In this example output, look for the handle for the kdnic minidriver, ffffdf801418d650.. + +``` +3: kd> !ndiskd.minidriver + ffffdf8015a98380 - tunnel + ffffdf801418d650 - kdnic +``` + +Click on the handle for the minidriver, then click on the "Handlers" link at the bottom of its details page to see the list of its handlers. You can alternatively enter the **!ndiskd.minidriver -handle -handlers** command. Once you have the list of the minidriver's handlers, look for the OidRequestHandler, whose handle is fffff80f1fd71c90 in this example. + +``` +2: kd> !ndiskd.minidriver ffffdf801418d650 -handlers + + +HANDLERS + + NDIS Handler Function pointer Symbol (if available) + InitializeHandlerEx fffff80f1fd78230 bp + SetOptionsHandler fffff80f1fd72800 bp + HaltHandlerEx fffff80f1fd78040 bp + ShutdownHandlerEx fffff80f1fd722c0 bp + + CheckForHangHandlerEx fffff80f1fd72810 bp + ResetHandlerEx fffff80f1fd72f70 bp + + PauseHandler fffff80f1fd78000 bp + RestartHandler fffff80f1fd78940 bp + + OidRequestHandler fffff80f1fd71c90 bp + CancelOidRequestHandler fffff80f1fd722c0 bp + DirectOidRequestHandler [None] + CancelDirectOidRequestHandler [None] + DevicePnPEventNotifyHandler fffff80f1fd789a0 bp + + SendNetBufferListsHandler fffff80f1fd71870 bp + ReturnNetBufferListsHandler fffff80f1fd71b50 bp + CancelSendHandler fffff80f1fd722c0 bp +``` + +Now either click on the "bp" link to the right of the OidRequestHandler or enter the [**bp -handle**](bp--bu--bm--set-breakpoint-.md) command with its handle to set a breakpoint on that routine. Next, type the **g** command to allow your debugee target machine to run and hit the breakpoint you just set. + +``` +2: kd> bp fffff80f1fd71c90 +2: kd> g +Breakpoint 1 hit +fffff80f`1fd71c90 448b4204 mov r8d,dword ptr [rdx+4] +``` + +Once you have triggered the breakpoint on a minidriver's OID request handler routine as shown by the previous example, you can run the !ndiskd.oid command to see a list of all the pending OIDs on the system. + +``` +1: kd> !ndiskd.oid + + +ALL PENDING OIDs + + NetAdapter ffffdf80140c71a0 - Microsoft Kernel Debug Network Adapter + Current OID OID_GEN_STATISTICS + Filter ffffdf8014950c70 - Microsoft Kernel Debug Network Adapter-WFP Native MAC Layer LightWeight Filter-0000 + Current OID OID_GEN_STATISTICS + Filter ffffdf801494dc70 - Microsoft Kernel Debug Network Adapter-QoS Packet Scheduler-0000 + Current OID OID_GEN_STATISTICS +``` + +In this example, the OID pending is [OID\_GEN\_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/ff569640). When you look at the results of !ndiskd.oid, recall that filters clone OID requests and pass them down the stack, and OIDs typically get passed from filter to filter to miniport. Therefore, although it may look like there are three separate OID requests with the same name in this example, there is actually one logical operation taking place which was physically spread across 3 OIDs and on 3 drivers. + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[0x9F bug check](https://msdn.microsoft.com/library/windows/hardware/ff559329) + +[OID\_PNP\_SET\_POWER](https://msdn.microsoft.com/library/windows/hardware/ff569780) + +[**bp, bu, bm (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) + +[OID\_GEN\_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/ff569640) + +[NDIS OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566707) + +[NDIS OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff566713) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.oid%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-pendingnbls.md b/windows-driver-docs-pr/debugger/-ndiskd-pendingnbls.md new file mode 100644 index 0000000000..01e5fe9933 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-pendingnbls.md @@ -0,0 +1,147 @@ +--- +title: ndiskd.pendingnbls +description: The ndiskd.pendingnbls extension displays pending NBLs (NET_BUFFER_LISTs) that are in transit. +ms.assetid: 9137B995-FCCA-4E25-85D3-FCB5B717EBDF +keywords: ["ndiskd.pendingnbls Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.pendingnbls +api_type: +- NA +--- + +# !ndiskd.pendingnbls + + +The **!ndiskd.pendingnbls** extension displays pending NBLs ([**NET\_BUFFER\_LISTs**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure)) that are in transit. + +``` +!ndiskd.pendingnbls [-handle ] [-fullstack] [-verbosity ] +``` + +## Parameters + + + *-handle* +Handle of an NDIS miniport, filter, or open. + + *-fullstack* +Shows pending NBLs from the entire stack associated with the handle. + + *-verbosity* +Level of detail to display. + +### DLL + +Ndiskd.dll + +Examples +-------- + +**!ndiskd.pendingnbls** can be passed the handle of an NDIS miniport, filter, or open. The following series of examples use a miniport handle. To see a list of all miniports and their associated minidrivers, run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension with no parameters. In the following example output, look for the Microsoft Kernel Debug Network Adapter, whose handle is ffffe00bc3f701a0. Its minidriver's handle is ffffe00bc51b9ae0. + +``` +0: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffe00bc6e12ae0 ffffe00bc6e4e1a0 Microsoft ISATAP Adapter #2 + ffffe00bc51b9ae0 ffffe00bc3f701a0 Microsoft Kernel Debug Network Adapter +``` + +To see the pending NBLs for a miniport, set a breakpoint on its minidriver's SendNetBufferListsHandler. Use the minidriver's handle to run the [**!ndiskd.minidriver -handle -handlers**](-ndiskd-minidriver.md) command to see a list of its handlers, then click the "bp" link to the right of the SendNetBufferListsHandler. You can alternatively enter the [**bp -handle**](bp--bu--bm--set-breakpoint-.md) command in the command line. + +``` +0: kd> !ndiskd.minidriver ffffe00bc51b9ae0 -handlers + + +HANDLERS + + NDIS Handler Function pointer Symbol (if available) + InitializeHandlerEx fffff80ae9618230 bp + SetOptionsHandler fffff80ae9612800 bp + HaltHandlerEx fffff80ae9618040 bp + ShutdownHandlerEx fffff80ae96122c0 bp + + CheckForHangHandlerEx fffff80ae9612810 bp + ResetHandlerEx fffff80ae9612f70 bp + + PauseHandler fffff80ae9618000 bp + RestartHandler fffff80ae9618940 bp + + OidRequestHandler fffff80ae9611c90 bp + CancelOidRequestHandler fffff80ae96122c0 bp + DirectOidRequestHandler [None] + CancelDirectOidRequestHandler [None] + DevicePnPEventNotifyHandler fffff80ae96189a0 bp + + SendNetBufferListsHandler fffff80ae9611870 bp + ReturnNetBufferListsHandler fffff80ae9611b50 bp + CancelSendHandler fffff80ae96122c0 bp +``` + +After setting the breakpoint on the SendNetBufferListsHandler, enter the **g** command to let the debugee target machine run and hit the breakpoint. + +``` +0: kd> bp fffff80ae9611870 +0: kd> g +Breakpoint 0 hit +fffff80a`e9611870 4053 push rbx +``` + +Now, after hitting the minidriver's SendNetBufferListsHandler breakpoint, you can see any pending NBLs for the miniport by entering the **!ndiskd.pendingnbls -handle** command with the miniport's handle. + +**Note**   +The debugee target machine in this example was loading a web page when it hit the breakpoint, so traffic was flowing through the miniport's datapath. Therefore, it had a pending NBL to send. Even after setting a breakpoint on one or more of the NBL handlers for the minidriver, you may not see any pending NBLs if there were no activity in the datapath. + +  + +``` +0: kd> !ndiskd.pendingnbls ffffe00bc3f701a0 + +PHASE 1/3: Found 20 NBL pool(s). +PHASE 2/3: Found 342 freed NBL(s). + + Pending Nbl Currently held by + ffffe00bc5545c60 ffffe00bc3f701a0 - Microsoft Kernel Debug Network Adapter [NetAdapter] + + +PHASE 3/3: Found 1 pending NBL(s) of 4817 total NBL(s). +Search complete. +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +[**!ndiskd.minidriver**](-ndiskd-minidriver.md) + +[**bp, bu, bm (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.pendingnbls%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-pkt.md b/windows-driver-docs-pr/debugger/-ndiskd-pkt.md new file mode 100644 index 0000000000..ae76ba4152 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-pkt.md @@ -0,0 +1,63 @@ +--- +title: ndiskd.pkt +description: Warning  This extension is for legacy NDIS 5.x drivers. The ndiskd.pkt extension displays information about an NDIS_PACKET structure. +ms.assetid: 8e704173-3b09-4377-b73a-ba67a3c3c930 +keywords: ["ndiskd.pkt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.pkt +api_type: +- NA +--- + +# !ndiskd.pkt + + +**Warning**  This extension is for legacy NDIS 5.x drivers. The [NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) structure and its associated architecture have been deprecated. + +  + +The **!ndiskd.pkt** extension displays information about an [NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) structure. + +``` +!ndiskd.pkt [-packet] [-verbosity] +``` + +## Parameters + + + *Packet* +Specifies the address of the packet. + + *Verbosity* +Specifies the amount of detail to be displayed. + +### DLL + +Ndiskd.dll + +## See also + + +[Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849) + +[Windows 2000 and Windows XP Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff565850) + +[NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.pkt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-pktpools.md b/windows-driver-docs-pr/debugger/-ndiskd-pktpools.md new file mode 100644 index 0000000000..ac107507bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-pktpools.md @@ -0,0 +1,69 @@ +--- +title: ndiskd.pktpools +description: Warning  This extension is for legacy NDIS 5.x drivers. The ndiskd.pktpools extension displays a list of all allocated packet pools. +ms.assetid: 0aceb22c-17ab-4199-a313-ecbc4c8f0b6e +keywords: ["ndiskd.pktpools Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.pktpools +api_type: +- NA +--- + +# !ndiskd.pktpools + + +**Warning**  This extension is for legacy NDIS 5.x drivers. The [NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) structure and its associated architecture have been deprecated. + +  + +The **!ndiskd.pktpools** extension displays a list of all allocated packet pools. + +``` +!ndiskd.pktpools +``` + +## + + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.pktpools** extension to see a list of all allocated packet pools on the system. Note that the handles for the packet pools are not clickable, which means you can't explore further information about the packet pool. This is because NDIS does not use packet pools starting with NDIS 6.0, so these pools are allocated only for legacy drivers which may still be on older systems. The debugee machine in this example does not have any legacy NDIS 5.x drivers installed so the packet pools are not used. This example is for illustrative purposes only. + +``` +3: kd> !ndiskd.pktpools +Pool Allocator BlocksAllocated BlockSize PktsPerBlock PacketLength +ffffdf80131d58c0 fffff80f1fbe3e8f 0x1 0x1000 0xa 0x190 ndis!DriverEntry+6af +ffffdf80131d5940 fffff80f1fbe3e71 0x1 0x1000 0xa 0x180 ndis!DriverEntry+691 +``` + +## See also + + +[Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849) + +[Windows 2000 and Windows XP Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff565850) + +[NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.pktpools%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-protocol.md b/windows-driver-docs-pr/debugger/-ndiskd-protocol.md new file mode 100644 index 0000000000..e4318ed767 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-protocol.md @@ -0,0 +1,142 @@ +--- +title: ndiskd.protocol +description: The ndiskd.protocol command displays information about an NDIS protocol driver. +ms.assetid: c1d349d5-b0ba-4665-a399-1bc5cd55dde6 +keywords: ["ndiskd.protocol Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.protocol +api_type: +- NA +--- + +# !ndiskd.protocol + + +The **!ndiskd.protocol** command displays information about an NDIS protocol driver. If you run this extension with no parameters, !ndiskd will display a list of NDIS protocol drivers that are active on the system. + +``` +!ndiskd.protocol [-handle ] [-findname ] +``` + +## Parameters + + + *-handle* +Handle of an NDIS protocol. + + *-findname* +Filters protocols by name prefix. + +## DLL + + +Ndiskd.dll + +Examples +-------- + +Enter the **!ndiskd.protocol** command to see a list of all NDIS protocols, their handles, and open bindings to miniports (if any). In the following example, look for the TCPIP6TUNNEL protocol's handle, ffff8083e1a95c00. + +``` +3: kd> !ndiskd.protocol +ffff8083e0114730 - NDISUIO + ffff8083e55f3010 - Microsoft Kernel Debug Network Adapter + +ffff8083e3e90c10 - MSLLDP + ffff8083e3926010 - Microsoft Kernel Debug Network Adapter + +ffff8083e3e98c10 - WANARPV6 + +ffff8083e3e97010 - WANARP + +ffff8083e3e8f6b0 - RSPNDR + ffff8083e11902c0 - Microsoft Kernel Debug Network Adapter + +ffff8083e3e90800 - LLTDIO + ffff8083e15537d0 - Microsoft Kernel Debug Network Adapter + +ffff8083e1a9ac10 - RDMANDK + +ffff8083e1a95c00 - TCPIP6TUNNEL + ffff8083e56b8110 - Microsoft ISATAP Adapter #2 + +ffff8083e19bec10 - TCPIPTUNNEL + +ffff8083e19bfc10 - TCPIP6 + ffff8083e504c770 - Microsoft Kernel Debug Network Adapter + +ffff8083e11cec10 - TCPIP + ffff8083e0c565a0 - Microsoft Kernel Debug Network Adapter +``` + +With the protocol's handle, now you can enter either click the handle or enter the **!ndiskd.protocol -handle** command to see information for that protocol, such as the handles for the miniports that are bound to it. + +``` +3: kd> !ndiskd.protocol ffff8083e1a95c00 + + +PROTOCOL + + TCPIP6TUNNEL + + Ndis handle ffff8083e1a95c00 + Ndis API version v6.40 + Driver context fffff80e2e4f9de0 + Driver version v0.0 + Reference count 2 + Flags [No flags set] + Driver image [Not available] Why not? + + +BINDINGS + + Open Miniport Miniport Name + ffff8083e56b8110 ffff8083e02ce1a0 Microsoft ISATAP Adapter #2 + + +HANDLERS + + Protocol handler Function pointer Symbol (if available) + BindAdapterHandlerEx fffff80e2e3baab0 bp + UnbindAdapterHandlerEx fffff80e2e3c1c80 bp + OpenAdapterCompleteHandlerEx fffff80e2e4bc940 bp + CloseAdapterCompleteHandlerEx fffff80e2e3d19b0 bp + NetPnPEventHandler fffff80e2e3bb140 bp + UninstallHandler [None] + SendNetBufferListsCompleteHandler fffff80e2e3919a0 bp + ReceiveNetBufferListsHandler fffff80e2e3918a0 bp + StatusHandlerEx fffff80e2e3a9550 bp + OidRequestCompleteHandler fffff80e2e398120 bp + DirectOidRequestCompleteHandler fffff80e2e398120 bp +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.protocol%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-rcvqueue.md b/windows-driver-docs-pr/debugger/-ndiskd-rcvqueue.md new file mode 100644 index 0000000000..cbdbe0da2f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-rcvqueue.md @@ -0,0 +1,133 @@ +--- +title: ndiskd.rcvqueue +description: The ndiskd.rcvqueue command displays information about a receive queue. +ms.assetid: 776A459F-A698-4BF6-8DAD-BEB15858AD7F +keywords: ["ndiskd.rcvqueue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.rcvqueue +api_type: +- NA +--- + +# !ndiskd.rcvqueue + + +The **!ndiskd.rcvqueue** command displays information about a receive queue. + +``` +!ndiskd.rcvqueue [-handle ] [-filters] [-mem] [-verbose] [-rcvqueueverbosity ] +``` + +## Parameters + + + *-handle* +Required. Handle of a receive queue. + + *-filters* +Shows filters on the queue. + + *-mem* +Shows shared memory allocations. + + *-verbose* +Shows additional details. + + *-rcvqueueverbosity* +Level of detail to display. + +## DLL + + +Ndiskd.dll + +Examples +-------- + +To obtain the receive queue handle, first enter the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) command with no parameters to see the list of net adapters, their drivers, and their handles. In the following example, look for the Microsoft ISATAP Adapter \#2's NetAdapter handle, ffff8083e02ce1a0. + +``` +3: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffff8083e2668970 ffff8083e02ce1a0 Microsoft ISATAP Adapter #2 + ffff8083e210fae0 ffff8083e0f501a0 Microsoft Kernel Debug Network Adapter +``` + +Next, with the net adapter's handle, use the **!ndiskd.netadapter -handle -rcvqueues** command to obtain a list of receive queues for this net adapter along with their handles. In this example, there is only one receive queue (the default one) with a handle of ffff8083e3a3d3a0. + +``` +3: kd> !ndiskd.netadapter ffff8083e02ce1a0 -rcvqueues + + +RECEIVE QUEUES + + QueueId Queue Handle Processor Affinity + 0 [Default] ffff8083e3a3d3a0 0:0000000000000000 (group:mask) + Queue Name: [Zero-length string] + VM Name: [Zero-length string] +``` + +Now you can use the queue handle to examine the receive queue details with the **!ndiskd.rcvqueue** command. + +``` +3: kd> !ndiskd.rcvqueue ffff8083e3a3d3a0 + + +RECEIVE QUEUE + + [Zero-length string] + + VM name [Zero-length string] + QueueId 0 + Ndis handle ffff8083e3a3d3a0 + + Miniport ffff8083e02ce1a0 - Microsoft ISATAP Adapter #2 + Open [No associated Open] + + Type Unspecified + Flags [No flags set] + Allocated Yes + References 1 + + Num filters 0 + Num buffers hint 0 + MSI-X entry 0 + Lookahead size 0 + Processor affinity 0:0000000000000000 (group:mask) + + Receive filter list + Shared memory allocations +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.rcvqueue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-vc.md b/windows-driver-docs-pr/debugger/-ndiskd-vc.md new file mode 100644 index 0000000000..b7a9113fff --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-vc.md @@ -0,0 +1,123 @@ +--- +title: ndiskd.vc +description: The ndiskd.vc extension displays a Connection-Oriented (CoNDIS) virtual connection (VC). +ms.assetid: 8F172026-3FBC-4686-A3A4-F54F1A0D08E5 +keywords: ["ndiskd.vc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.vc +api_type: +- NA +--- + +# !ndiskd.vc + + +The **!ndiskd.vc** extension displays a Connection-Oriented (CoNDIS) virtual connection (VC). + +``` +!ndiskd.vc [-handle ] +``` + +## Parameters + + + *-handle* +Required. Handle of a VC pointer. + +### DLL + +Ndiskd.dll + +Remarks +------- + +For more information about CoNDIS, see [Connection-Oriented NDIS](https://msdn.microsoft.com/windows/hardware/drivers/network/connection-oriented-ndis). + +For more information about CoNDIS virtual connections, see [Virtual Connections](https://msdn.microsoft.com/windows/hardware/drivers/network/virtual-connections). + +Examples +-------- + +CoNDIS is used in certain situations such as connecting to a VPN, so running **!ndiskd.vc** will not show you results unless a miniport driver on your system has created and activated a CoNDIS virtual connection. The following example shows results from a machine that is connected to a VPN network. First, run the [**!ndiskd.netadapter**](-ndiskd-netadapter.md) extension with no parameters to see a list of miniports and miniport drivers on the system. In the following output, look for the miniport driver for the Marvell AVASTAR Wireless-AC Network Controller network adapter. Its handle is ffffc804af2e3710. + +``` +1: kd> !ndiskd.netadapter + Driver NetAdapter Name + ffffc804af2e3710 ffffc804b9e6f1a0 Marvell AVASTAR Wireless-AC Network Controller + ffffc804b99b9020 ffffc804b9c301a0 WAN Miniport (Network Monitor) + ffffc804b99b9020 ffffc804b9c2a1a0 WAN Miniport (IPv6) + ffffc804b99b9020 ffffc804b8a8a1a0 WAN Miniport (IP) + ffffc804ae9d7020 ffffc804b9ceb1a0 WAN Miniport (PPPOE) + ffffc804b9ca5900 ffffc804b9e601a0 WAN Miniport (PPTP) + ffffc804b99dc720 ffffc804b99b01a0 WAN Miniport (L2TP) + ffffc804b86581b0 ffffc804b9c6c1a0 WAN Miniport (IKEv2) + ffffc804ad4a7250 ffffc804b99651a0 WAN Miniport (SSTP) + ffffc804b11c4020 ffffc804b85821a0 Microsoft ISATAP Adapter + ffffc804b11c4020 ffffc804b71731a0 Microsoft ISATAP Adapter #2 + ffffc804ad725020 ffffc804b05e71a0 Surface Ethernet Adapter #2 + ffffc804b0bf0020 ffffc804b0c011a0 Bluetooth Device (Personal Area Network) + ffffc804aef695e0 ffffc804aed331a0 TAP-Windows Adapter V9 +``` + +Next, enter the **!ndiskd.vc** command with the miniport driver's handle to see the virtual connections opened by that miniport driver. + +``` +1: kd> !ndiskd.vc ffffc804af2e3710 + + +VIRTUAL CALL + + [Zero-length string] + Ndis handle ffffc804af2e3710 + VC Index 0 + + AF fffff80965fd5888 + Call Flags [No flags set] + VC Flags [Unrecognized flags 04a80100] VC_ACTIVATE_PENDING + + Miniport fffff80965ffaa20 - [Invalid NetAdapter] + Miniport Context fffff80965ffaad0 + + Call Manager fffff80965ff9b50 - [Invalid Open] + Call Manager Context fffff80965ff9c70 + + Client ffffc804af96fd78 - [Invalid Open] + Client Context 00003206 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[Connection-Oriented NDIS](https://msdn.microsoft.com/windows/hardware/drivers/network/connection-oriented-ndis) + +[Virtual Connections](https://msdn.microsoft.com/windows/hardware/drivers/network/virtual-connections) + +[**!ndiskd.netadapter**](-ndiskd-netadapter.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.vc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-wdiadapter.md b/windows-driver-docs-pr/debugger/-ndiskd-wdiadapter.md new file mode 100644 index 0000000000..5130f41ab4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-wdiadapter.md @@ -0,0 +1,160 @@ +--- +title: ndiskd.wdiadapter +description: The ndiskd.wdiadapter extension displays information about a WDIWiFi CAdapter structure. If you run this extension with no parameters, ndiskd will display a list of all WDIWiFi CAdapter structures. +ms.assetid: 1AC069E8-CF87-459B-9C56-DDC1A6F765A8 +keywords: ["ndiskd.wdiadapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.wdiadapter +api_type: +- NA +--- + +# !ndiskd.wdiadapter + + +The **!ndiskd.wdiadapter** extension displays information about a WDIWiFi!CAdapter structure. If you run this extension with no parameters, !ndiskd will display a list of all WDIWiFi!CAdapter structures. + +For more information about WDI miniport drivers, see the [WDI Miniport Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/wdi-miniport-driver-design-guide). + +For more information about WDI miniport driver reference, see [WDI Miniport Driver Reference](https://msdn.microsoft.com/library/windows/hardware/dn926075). + +``` +!ndiskd.wdiadapter [-handle ] [-pm] [-rcvfilter] +``` + +## Parameters + + + *-handle* +Handle of a CAdapter object. + + *-pm* +Shows power management state and capabilities. + + *-rcvfilter* +Shows receive filtering capabilities. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.wdiadapter** extension with no parameters to see a list of all CAdapter objects, along with details for each of their WDI Adapters. In the following example, there is only one CAdapter structure. The handle for its associated WDI Adapter is ffffc804af396000. + +``` +1: kd> !ndiskd.wdiadapter + CAdapter + ffffc804af396000 - WDI Adapter + + +WDI ADAPTER + + Object ffffc804af396000 + Miniport ffffc804b9e6f1a0 + WDI driver ffffc804b8ce7c40 - WDI MiniDriver + NetGuid 47cb3aa5-e29c-4628-80bd-5023c53fcccb + Power D0 + + CCtlPlane ffffc804af396080 + CTxMgr ffffc804af399790 + + +DEVICE COMMANDS + + Scheduler state DeviceCommandSchedulerStateInit + [No queued device commands found] + +Device Command Scheduler + + +SERIALIZED JOBS + + Job State Type Child + ffffc804b9f33000 StepPending WiFiJobMiniportInitialize + + + +ACTIVE JOBS + + Job State Type Child + ffffc804b9f33000 StepPending WiFiJobMiniportInitialize + + + +EVENTS + + Processing? No + + Event Status Type + [No events found] + +Event Queue + + +MORE INFORMATION + + Power management Receive filtering +``` + +Now you can either click on the "Power management" and "Receive filtering" links at the bottom of the CAdapter structure's description, or you can enter the **!ndiskd.wdiadapter -handle** command with either the *-pm* or *-rcvfilter* option. The following example shows output for the *-rcvfilter* option. + +``` +1: kd> !ndiskd.wdiadapter ffffc804af396000 -rcvfilter + + +RECEIVE FILTER + + Current Configuration + + Revision 0 + Flags 0 + Enabled filter types [No flags set] + Enabled queue types [No flags set] + Max Queues 0 + Queue properties [No flags set] + Filter tests [No flags set] + Header types [No flags set] + MAC header fields [No flags set] + Max MAC header filters 0 + Max queue groups 0 + Max queues per group 0 + Min lookahead split size 0 + Max lookahead split size 0 +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[WDI Miniport Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/wdi-miniport-driver-design-guide) + +[WDI Miniport Driver Reference](https://msdn.microsoft.com/library/windows/hardware/dn926075) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.wdiadapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ndiskd-wdiminidriver.md b/windows-driver-docs-pr/debugger/-ndiskd-wdiminidriver.md new file mode 100644 index 0000000000..4dfe08a409 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ndiskd-wdiminidriver.md @@ -0,0 +1,151 @@ +--- +title: ndiskd.wdiminidriver +description: The ndiskd.wdiminidriver extension displays information about one or more CMiniportDriver structures. +ms.assetid: C7022CD7-6F3A-485B-8686-A686A5305DA5 +keywords: ["ndiskd.wdiminidriver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ndiskd.wdiminidriver +api_type: +- NA +--- + +# !ndiskd.wdiminidriver + + +The **!ndiskd.wdiminidriver** extension displays information about one or more CMiniportDriver structures. If you run this extension with no parameters, !ndiskd will display a list of all CMiniportDriver structures. + +For more information about WDI miniport drivers, see the [WDI Miniport Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/wdi-miniport-driver-design-guide). + +For more information about WDI miniport driver reference, see [WDI Miniport Driver Reference](https://msdn.microsoft.com/library/windows/hardware/dn926075). + +``` +!ndiskd.wdiminidriver [-handle ] [-pm] [-rcvfilter] +``` + +## Parameters + + + *-handle* +Handle of a CMiniportDriver object. + + *-basic* +Displays basic information about the miniport driver. + + *-handlers* +Displays this driver's miniport handlers. + +### DLL + +Ndiskd.dll + +Examples +-------- + +Run the **!ndiskd.wdiminidriver** extension with no parameters to see a list of all CMiniportDriver objects. In the following example, there is only one CMiniportDriver object. The handle of its WdiMiniDriver is ffffc804b8ce7c40. + +``` +1: kd> !ndiskd.wdiminidriver + WdiMiniDriver Name + ffffc804b8ce7c40 - WDI MiniDriver +``` + +Click on the WdiMiniDriver's handle or enter the **!ndiskd.wdiminidriver -handle** command to see details for this WDI miniport driver. + +``` +1: kd> !ndiskd.wdiminidriver ffffc804b8ce7c40 + + +WDI MINIPORT DRIVER + + Object ffffc804b8ce7c40 + DRIVER_OBJECT ffffc804b90a4ac0 + + Ndis API version v6.50 + NDIS driver ffffc804af2e3710 - mrvlpcie8897 + Driver version v1.0 + WDI API version v1.0.1 + + + Handlers +``` + +Now you can click the "Handlers" link at the bottom of the WDI Miniport Driver's details, or you can use the handle to enter the **!ndiskd.wdiminidriver -handle -handlers** command, to see a list of all this WDI Miniport Driver's handlers. + +``` +1: kd> !ndiskd.wdiminidriver ffffc804b8ce7c40 -handlers + + +HANDLERS + + Miniport Handler Function pointer Symbol (if available) + InitializeHandlerEx [None] + SetOptionsHandler fffff80965e8cae0 mrvlpcie8897!wlan_cmd_queue_deinit + UnloadHandler fffff80965e71a08 mrvlpcie8897!MPUnload + HaltHandlerEx [None] + ShutdownHandlerEx fffff80965e71974 mrvlpcie8897!MPShutdown + + CheckForHangHandlerEx [None] + ResetHandlerEx [None] + + PauseHandler [None] + RestartHandler [None] + + OidRequestHandler [None] + SendNetBufferListsHandler [None] + ReturnNetBufferListsHandler [None] + CancelSendHandler [None] + CancelOidRequestHandler [None] + DirectOidRequestHandler [None] + CancelDirectOidRequestHandler [None] + DevicePnPEventNotifyHandler fffff80965e71868 mrvlpcie8897!MPPnPEventNotify + + AllocateAdapterHandler fffff80965e713ec mrvlpcie8897!MPAllocateTalAdapter + FreeAdapterHandler fffff80965e717e8 mrvlpcie8897!MPFreeTalAdapter + OpenAdapterHandler fffff80965e719b8 mrvlpcie8897!MPTaskOpenHandler + CloseAdapterHandler fffff80965e719ac mrvlpcie8897!MPTaskCloseHandler + StartOperationHandler [None] + StopOperationHandler [None] + PostPauseHandler [None] + PostRestartHandler [None] + HangDiagnoseHandler fffff80965e715d8 mrvlpcie8897!MPDiagnosticHandler + TalTxRxInitializeHandler fffff80965e752d4 mrvlpcie8897!TalDataPathInitialize + TalTxRxDeinitializeHandler fffff80965e7527c mrvlpcie8897!TalDataPathDeinitialize + + OpenAdapterCompleteHandler fffff80965ffab50 wdiwifi!WDIOpenAdapterCompleteHandler + CloseAdapterCompleteHandler fffff80965fface0 wdiwifi!WDICloseAdapterCompleteHandler +``` + +## See also + + +[Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index) + +[Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081) + +[Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311) + +[**NDIS extensions (Ndiskd.dll)**](ndis-extensions--ndiskd-dll-.md) + +[**!ndiskd.help**](-ndiskd-help.md) + +[WDI Miniport Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/wdi-miniport-driver-design-guide) + +[WDI Miniport Driver Reference](https://msdn.microsoft.com/library/windows/hardware/dn926075) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ndiskd.wdiminidriver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-net-send.md b/windows-driver-docs-pr/debugger/-net-send.md new file mode 100644 index 0000000000..0403644b81 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-net-send.md @@ -0,0 +1,72 @@ +--- +title: net_send +description: The net_send extension sends a message over a local network. +ms.assetid: 13d5fe3f-6477-4610-8928-020726ccb3c8 +keywords: ["network messages", "net_send Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- net_send +api_type: +- NA +--- + +# !net\_send + + +The **!net\_send** extension sends a message over a local network. + +``` +!net_send SendingMachine TargetMachine Sender Message +``` + +## Parameters + + + *SendingMachine* +Specifies the computer that will process the command. It is recommended that this be the name of the computer that the debugger is running on, since your network configuration may refuse to send the message otherwise. *SendingMachine* should not include leading backslashes (\\\). + + *TargetMachine* +Specifies the computer to which the message will be sent. *TargetMachine* should not include leading backslashes (\\\). + + *Sender* +Specifies the sender of the message. It is recommended that *Sender* be identical to *SendingMachine*, since your network configuration may refuse to send the message otherwise. When the message is displayed, this string will be identified as the sender of the message. + + *Message* +Specifies the message itself. All text after the *Sender* parameter will be treated as part of *Message*, including spaces and quotation marks, although a [**semicolon**](----command-separator-.md) will terminate *Message* and begin a new command. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!net_send%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-netsyms.md b/windows-driver-docs-pr/debugger/-netsyms.md new file mode 100644 index 0000000000..daaff77f57 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-netsyms.md @@ -0,0 +1,66 @@ +--- +title: .netsyms (Disable Network Symbol Loading) +description: .netsyms (Disable Network Symbol Loading) +ms.assetid: 09347909-47C8-4a4d-8246-C32A1791F46B +--- + +# .netsyms (Disable Network Symbol Loading) + + +## + + +Use the .netsyms command to allow or disallow loading symbols from a network path. + +### Syntax + +**.netsyms** *{yes|no}* + +### Parameters + +*yes* +Enables network symbol loading. This is the default. + +*no* +Disables network symbol loading. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Remarks + +Use .netsyms with no argument to display the current state of this setting. + +Use [**!sym noisy**](-sym.md) or the *-n* [**WinDbg Command-Line Option**](windbg-command-line-options.md) to display additional detail as symbols are loaded. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.netsyms%20%28Disable%20Network%20Symbol%20Loading%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-netuse--control-network-connections-.md b/windows-driver-docs-pr/debugger/-netuse--control-network-connections-.md new file mode 100644 index 0000000000..717af67a67 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-netuse--control-network-connections-.md @@ -0,0 +1,92 @@ +--- +title: .netuse (Control Network Connections) +description: The .netuse command adds a connection to a network share. +ms.assetid: f27e5ae5-1beb-4d2b-987e-5e91d0742e2d +keywords: [".netuse (Control Network Connections) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .netuse (Control Network Connections) +api_type: +- NA +--- + +# .netuse (Control Network Connections) + + +The **.netuse** command adds a connection to a network share. + +``` +.netuse /a "[Local]" "Remote" "[User]" "[Password]" +``` + +## Parameters + + + **/a** +Adds a new connection. You must always use the **/a** switch. + + *Local* +Specifies the drive letter to use for the connection. You must enclose *Local* in quotation marks. If you omit this parameter, you must include an empty pair of quotation marks as the parameter. + + *Remote* +Specifies the UNC path of the share that is being connected. You must enclose *Remote* in quotation marks. + + *User* +Specifies the user name of an account that is authorized to establish the connection. You must enclose *User* in quotation marks. If you omit this parameter, you must include an empty pair of quotation marks as the parameter. + + *Password* +Specifies the password that is associated with the *User* account. You must enclose *Password* in quotation marks. If you omit this parameter, you must include an empty pair of quotation marks as the parameter. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **.netuse** command behaves like the **net use** Microsoft MS-DOS command. + +If you use **.netuse** during a remote debugging session, this command affects the debugging server, not the debugging client. + +The following example shows this command. + +``` +0:000> .netuse "m:" "\\myserver\myshare" "" "" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.netuse%20%28Control%20Network%20Connections%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-noshell--prohibit-shell-commands-.md b/windows-driver-docs-pr/debugger/-noshell--prohibit-shell-commands-.md new file mode 100644 index 0000000000..52601584a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-noshell--prohibit-shell-commands-.md @@ -0,0 +1,75 @@ +--- +title: .noshell (Prohibit Shell Commands) +description: The .noshell command prevents you from using .shell commands. +ms.assetid: 49a83e46-1390-4b60-bd61-a5da80c513e3 +keywords: [".noshell (Prohibit Shell Commands) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .noshell (Prohibit Shell Commands) +api_type: +- NA +--- + +# .noshell (Prohibit Shell Commands) + + +The **.noshell** command prevents you from using [**.shell**](-shell--command-shell-.md) commands. + +``` +.noshell +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the command shell and for other ways to disable shell commands, see [Using Shell Commands](using-shell-commands.md). + +Remarks +------- + +If you use the **.noshell** command, you cannot use [**.shell (Command Shell)**](-shell--command-shell-.md) commands as long as the debugger is running, even if you start a new debugging session. + +If you are performing remote debugging, this command is useful for security purposes. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.noshell%20%28Prohibit%20Shell%20Commands%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-noversion--disable-version-checking-.md b/windows-driver-docs-pr/debugger/-noversion--disable-version-checking-.md new file mode 100644 index 0000000000..4aa146eafd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-noversion--disable-version-checking-.md @@ -0,0 +1,73 @@ +--- +title: .noversion (Disable Version Checking) +description: The .noversion command disables all version checking of extension DLLs. +ms.assetid: ce7fbff4-7936-4bef-8236-a13957ada7f4 +keywords: ["Disable Version Checking (.noversion) command", ".noversion (Disable Version Checking) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .noversion (Disable Version Checking) +api_type: +- NA +--- + +# .noversion (Disable Version Checking) + + +The **.noversion** command disables all version checking of extension DLLs. + +``` +.noversion +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The build number of extension DLLs should match the build number of the computer that you are debugging, because the DLLs are compiled and linked with dependencies on specific versions of data structures. If the versions do not match, you typically receive the following message. + +``` +*** Extension DLL(1367 Free) does not match target system(1552 Free) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.noversion%20%28Disable%20Version%20Checking%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-npx.md b/windows-driver-docs-pr/debugger/-npx.md new file mode 100644 index 0000000000..4281aaeedb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-npx.md @@ -0,0 +1,65 @@ +--- +title: npx +description: The npx extension displays the contents of the floating-point register save area. +ms.assetid: 1601e4fe-0aba-4507-90a1-402c02fba59d +keywords: ["registers, floating-point register save area", "npx Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- npx +api_type: +- NA +--- + +# !npx + + +The **!npx** extension displays the contents of the floating-point register save area. + +``` +!npx Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the FLOATING\_SAVE\_AREA structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!npx%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-nsobj.md b/windows-driver-docs-pr/debugger/-nsobj.md new file mode 100644 index 0000000000..ad188e68be --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nsobj.md @@ -0,0 +1,57 @@ +--- +title: nsobj +description: The nsobj extension displays an ACPI namespace object. +ms.assetid: 348aeb42-41c6-42de-bb43-b075f55076c4 +keywords: ["nsobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- nsobj +api_type: +- NA +--- + +# !nsobj + + +The **!nsobj** extension displays an ACPI namespace object. + +Syntax + +``` +!nsobj [Address] +``` + +## Parameters + + + *Address* +Specifies the address of the namespace object. If this is omitted, the root of the namespace tree is used. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +Remarks +------- + +This extension is equivalent to [**!amli dns**](-amli-dns.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!nsobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-nstree.md b/windows-driver-docs-pr/debugger/-nstree.md new file mode 100644 index 0000000000..0a9d6ffae5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nstree.md @@ -0,0 +1,57 @@ +--- +title: nstree +description: The nstree extension displays an ACPI namespace object and its children in the namespace tree. +ms.assetid: 0dec2a5a-ca77-4f91-9128-2d3dd8cd035f +keywords: ["nstree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- nstree +api_type: +- NA +--- + +# !nstree + + +The **!nstree** extension displays an ACPI namespace object and its children in the namespace tree. + +Syntax + +``` +!nstree [Address] +``` + +## Parameters + + + *Address* +Specifies the address of the namespace object. This object and the entire namespace tree subordinate to it will be displayed. If *Address* is omitted, the entire namespace tree is displayed. + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +Remarks +------- + +This extension is equivalent to [**!amli dns /s**](-amli-dns.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!nstree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-nvlist--natvis-list-.md b/windows-driver-docs-pr/debugger/-nvlist--natvis-list-.md new file mode 100644 index 0000000000..1c3ba8f4f7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nvlist--natvis-list-.md @@ -0,0 +1,71 @@ +--- +title: .nvlist (NatVis List) +description: The .nvllist command lists the NatVis files loaded into the debugger environment. +ms.assetid: 90974599-6F8E-4898-B8B6-F9502659AD77 +keywords: [".nvlist (NatVis List) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .nvlist (NatVis List) +api_type: +- NA +--- + +# .nvlist (NatVis List) + + +The .nvllist command lists the NatVis files loaded into the debugger environment. + +``` +.nvlist +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information, see [Writing debugger type visualizers for C++ using .natvis files](http://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2). + +## See also + + +[**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.nvlist%20%28NatVis%20List%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-nvload--natvis-load-.md b/windows-driver-docs-pr/debugger/-nvload--natvis-load-.md new file mode 100644 index 0000000000..b1c3f7431c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nvload--natvis-load-.md @@ -0,0 +1,82 @@ +--- +title: .nvload (NatVis Load) +description: The .nvload command loads a NatVis file into the debugger environment. After the visualization is loaded, it will be used to render data defined in the visualization. +ms.assetid: 9B14B3B4-EA90-426E-8555-0E5B8F63E0A9 +keywords: [".nvload (NatVis Load) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .nvload (NatVis Load) +api_type: +- NA +--- + +# .nvload (NatVis Load) + + +The .nvload command loads a NatVis file into the debugger environment. After the visualization is loaded, it will be used to render data defined in the visualization. + +``` +.nvload FileName|ModuleName + +``` + +## Parameters + + + *FileName | ModuleName* +Specifies the NatVis file name or module name to load. + +The **FileName** is the explicit name of a .natvis file to load. A fully qualified path can be used. + +The **ModuleName** is the name of a module in the target process being debugged. All NatVis files which are embedded within the symbol file (PDB) of the named module name are loaded, if there are any available. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information, see [Writing debugger type visualizers for C++ using .natvis files](http://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2). + +## See also + + +[**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.nvload%20%28NatVis%20Load%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-nvunload--natvis-unload-.md b/windows-driver-docs-pr/debugger/-nvunload--natvis-unload-.md new file mode 100644 index 0000000000..d1f20905cb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nvunload--natvis-unload-.md @@ -0,0 +1,79 @@ +--- +title: .nvunload (NatVis Unload) +description: The .nvunload command unloads a NatVis file from the debugger environment. +ms.assetid: E63BE2B5-291B-4F78-98FF-C1D7663A184E +keywords: [".nvunload (NatVis Unload) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .nvunload (NatVis Unload) +api_type: +- NA +--- + +# .nvunload (NatVis Unload) + + +The .nvunload command unloads a NatVis file from the debugger environment. + +``` +.nvunload FileName|ModuleName + +``` + + *FileName | ModuleName* +Specifies the NatVis file name or module name to unload. + +The **FileName** is the explicit name of a .natvis file to unload. A fully qualified path can be used. + +The **ModuleName** is the name of a module in the target process being debugged. All NatVis files which are embedded within the symbol file (PDB) of the named module name are unloaded. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information, see [Writing debugger type visualizers for C++ using .natvis files](http://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2). + +## See also + + +[**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.nvunload%20%28NatVis%20Unload%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-nvunloadall--natvis-unload-all-.md b/windows-driver-docs-pr/debugger/-nvunloadall--natvis-unload-all-.md new file mode 100644 index 0000000000..ea25472235 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-nvunloadall--natvis-unload-all-.md @@ -0,0 +1,71 @@ +--- +title: .nvunloadall (NatVis Unload All) +description: The .nvunloadall command unloads all of the NatVis files from the debugger environment. +ms.assetid: E018D09A-1B52-4D9E-944E-7F61841EAE1A +keywords: [".nvunloadall (NatVis Unload All) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .nvunloadall (NatVis Unload All) +api_type: +- NA +--- + +# .nvunloadall (NatVis Unload All) + + +The .nvunloadall command unloads all of the NatVis files from the debugger environment. + +``` + .nvunloadall +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information, see [Writing debugger type visualizers for C++ using .natvis files](http://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2). + +## See also + + +[**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.nvunloadall%20%28NatVis%20Unload%20All%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ob---od---ow.md b/windows-driver-docs-pr/debugger/-ob---od---ow.md new file mode 100644 index 0000000000..ed5a7fbeb5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ob---od---ow.md @@ -0,0 +1,29 @@ +--- +title: ob, od, ow +description: ob, od, ow +ms.assetid: ebb00538-49ec-462e-990e-4c4cb86ae3bd +keywords: ["ob extension (obsolete)", "od extension (obsolete)", "ow extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !ob, !od, !ow + + +## + + +The **!ob**, **!od**, and **!ow** extension commands are obsolete. Use the [**ob, od, ow (Output to Port)**](ob--ow--od--output-to-port-.md) commands instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ob,%20!od,%20!ow%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-obja.md b/windows-driver-docs-pr/debugger/-obja.md new file mode 100644 index 0000000000..df4d5f2344 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-obja.md @@ -0,0 +1,94 @@ +--- +title: obja +description: The obja extension displays the attributes of an object in the object manager. +ms.assetid: dc263ec2-72bf-4cb1-8583-4e9142d0bbdb +keywords: ["object manager", "obja Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- obja +api_type: +- NA +--- + +# !obja + + +The **!obja** extension displays the attributes of an object in the object manager. + +``` +!obja Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the object header you want to examine. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Ext.dll +Kdextx86.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For information about objects and the object manager, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The attributes pertaining to the specified object are listed. Valid attributes are: + +``` +#define OBJ_INHERIT 0x00000002L +#define OBJ_PERMANENT 0x00000010L +#define OBJ_EXCLUSIVE 0x00000020L +#define OBJ_CASE_INSENSITIVE 0x00000040L +#define OBJ_OPENIF 0x00000080L +#define OBJ_OPENLINK 0x00000100L +#define OBJ_VALID_ATTRIBUTES 0x000001F2L +``` + +Here is an example: + +``` +kd> !obja 80967768 +Obja +80967768 at 80967768: + OBJ_INHERIT + OBJ_PERMANENT + OBJ_EXCLUSIVE +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!obja%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-object.md b/windows-driver-docs-pr/debugger/-object.md new file mode 100644 index 0000000000..8740b4c644 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-object.md @@ -0,0 +1,192 @@ +--- +title: object +description: The object extension displays information about a system object. +ms.assetid: dc6d862b-3246-4d5b-992c-8723a0347f1d +keywords: ["object Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- object +api_type: +- NA +--- + +# !object + + +The **!object** extension displays information about a system object. + +``` +!object Address [Flags] +!object Path +!object 0 Name +!object -p +!object {-h|-?} +``` + +## Parameters + + + *Address* +If the first argument is a nonzero hexadecimal number, it specifies the hexadecimal address of the system object to be displayed. + + *Flags* +Specifies the level of detail in the command output. + +Set *Flags* to a bitwise OR of these values: + +**0x0** +Display object type. + +**0x1** +Display object type, object name, and reference counts. + +**0x8** +Display the contents of an object directory or the target of a symbolic link. This flag has an effect only if **0x1** is also set. + +**0x10** +Display optional object headers. + +**0x20** +Display the full path to a named object. This flag has an effect only if **0x1** is also set. + +The *Flags* parameter is optional. The default value is 0x9. + + *Path* +If the first argument begins with a backslash (\), **!object** interprets it as an object path name. When this option is used, the display will be arranged according to the directory structure used by the Object Manager. + + *Name* +If the first argument is zero, the second argument is interpreted as the name of a class of system objects for which to display all instances. + + **-p** +Display private object name spaces. + +{**-h**|**-?**} +Display help for this command. + +### DLL + +Kdexts.dll + +### Examples + +This example passes the path of the \\Device directory to **!object**. The output lists all objects in the \\Device directory. + +``` +0: kd> !object \Device +Object: ffffc00b074166a0 Type: (ffffe0083b768690) Directory + ObjectHeader: ffffc00b07416670 (new version) + HandleCount: 0 PointerCount: 224 + Directory Object: ffffc00b074092e0 Name: Device + + Hash Address Type Name + ---- ------- ---- ---- + 00 ffffe0083e6a61f0 Device 00000044 + ffffe0083dcc4050 Device 00000030 + ffffe0083d34f050 Device NDMP2 + ffffe0083bdf7060 Device NTPNP_PCI0002 + ... + ffffe0083b85d060 Device USBPDO-8 + ffffe0083d33d050 Device USBFDO-6 + ... + ffffe0083bdf0060 Device NTPNP_PCI0001 +``` + +Choose one of listed objects, say USBPDO-8. Pass the address of USBPDO-8 (ffffe0083b85d060) to **!objec**t. Set *Flags* to 0x0 to get minimal information. + +``` +0: kd> !object ffffe0083b85d060 0x0 +Object: ffffe0083b85d060 Type: (ffffe0083b87df20) Device + ObjectHeader: ffffe0083b85d030 (new version) +``` + +Include name and reference count information for the same object by setting *Flags* to 0x1. + +``` +0: kd> !object ffffe0083b85d060 0x1 +Object: ffffe0083b85d060 Type: (ffffe0083b87df20) Device + ObjectHeader: ffffe0083b85d030 (new version) + HandleCount: 0 PointerCount: 6 + Directory Object: ffffc00b074166a0 Name: USBPDO-8 +``` + +Get optional header information for the same object by setting *Flags* to 0x10. + +``` +0: kd> !object ffffe0083b85d060 0x10 +Object: ffffe0083b85d060 Type: (ffffe0083b87df20) Device + ObjectHeader: ffffe0083b85d030 (new version) +Optional Headers: + NameInfo(ffffe0083b85d010) +``` + +The following example calls **!object** twice for a Directory object. The first time, the contents of the directory are not displayed because the 0x8 flag is not set. The second time, the contents of the directory are displayed because both the 0x8 and 0x1 flags are set (Flags = 0x9). + +``` +0: kd> !object ffffc00b07481d00 0x1 +Object: ffffc00b07481d00 Type: (ffffe0083b768690) Directory + ObjectHeader: ffffc00b07481cd0 (new version) + HandleCount: 0 PointerCount: 3 + Directory Object: ffffc00b07481eb0 Name: Filters + +0: kd> !object ffffc00b07481d00 0x9 +Object: ffffc00b07481d00 Type: (ffffe0083b768690) Directory + ObjectHeader: ffffc00b07481cd0 (new version) + HandleCount: 0 PointerCount: 3 + Directory Object: ffffc00b07481eb0 Name: Filters + + Hash Address Type Name + ---- ------- ---- ---- + 19 ffffe0083c5f56e0 Device FltMgrMsg + 21 ffffe0083c5f5060 Device FltMgr +``` + +The following example calls **!object** twice for a SymbolicLink object. The first time, the target of the symbolic link is not displayed because the 0x8 flag is not set. The second time, the target of the symbolic link is splayed because both the 0x8 and 0x1 flags are set (Flags = 0x9). + +``` +0: kd> !object ffffc00b07628fb0 0x1 +Object: ffffc00b07628fb0 Type: (ffffe0083b769450) SymbolicLink + ObjectHeader: ffffc00b07628f80 (new version) + HandleCount: 0 PointerCount: 1 + Directory Object: ffffc00b074166a0 Name: Ip6 + +0: kd> !object ffffc00b07628fb0 0x9 +Object: ffffc00b07628fb0 Type: (ffffe0083b769450) SymbolicLink + ObjectHeader: ffffc00b07628f80 (new version) + HandleCount: 0 PointerCount: 1 + Directory Object: ffffc00b074166a0 Name: Ip6 + Target String is '\Device\Tdx' +``` + +### Additional Information + +For information about objects and the object manager, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +## See also + + +[Object Reference Tracing](object-reference-tracing.md) + +[**!obtrace**](-obtrace.md) + +[**!handle**](-handle.md) + +[Determining the ACL of an Object](determining-the-acl-of-an-object.md) + +[Kernel-Mode Extension Commands](kernel-mode-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!object%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-obtrace.md b/windows-driver-docs-pr/debugger/-obtrace.md new file mode 100644 index 0000000000..8021709d15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-obtrace.md @@ -0,0 +1,159 @@ +--- +title: obtrace +description: The obtrace extension displays object reference tracing data for the specified object. +ms.assetid: 6a124f9f-1c2f-4303-b84f-0032fb912cc1 +keywords: ["obtrace Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- obtrace +api_type: +- NA +--- + +# !obtrace + + +The **!obtrace** extension displays object reference tracing data for the specified object. + +``` +!obtrace Object +``` + +## Parameters + + + *Object* +A pointer to the object or a path. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For more information about the Global Flags utility (GFlags), see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +The object reference tracing feature of Windows records sequential stack traces whenever an object reference counter is incremented or decremented. + +Before using this extension to display object reference tracing data, you must use [GFlags](gflags.md) to enable [object reference tracing](object-reference-tracing.md) for the specified object. You can enable object reference tracing as a kernel flag (run-time) setting, in which the change is effective immediately, but disappears if you shut down or restart; or as a registry setting, which requires a restart, but remains effective until you change it. + +Here is an example of the output from the **!obtrace** extension: + +``` +kd> !obtrace 0xfa96f700 +Object: fa96f700 Image: cmd.exe +Sequence (+/-) Stack +-------- ----- --------------------------------------------------- + 2421d +1 nt!ObCreateObject+180 + nt!NtCreateEvent+92 + nt!KiFastCallEntry+104 + nt!ZwCreateEvent+11 + win32k!UserThreadCallout+6f + win32k!W32pThreadCallout+38 + nt!PsConvertToGuiThread+174 + nt!KiBBTUnexpectedRange+c + + 2421e -1 nt!ObfDereferenceObject+19 + nt!NtCreateEvent+d4 + nt!KiFastCallEntry+104 + nt!ZwCreateEvent+11 + win32k!UserThreadCallout+6f + win32k!W32pThreadCallout+38 + nt!PsConvertToGuiThread+174 + nt!KiBBTUnexpectedRange+c + + 2421f +1 nt!ObReferenceObjectByHandle+1c3 + win32k!xxxCreateThreadInfo+37d + win32k!UserThreadCallout+6f + win32k!W32pThreadCallout+38 + nt!PsConvertToGuiThread+174 + nt!KiBBTUnexpectedRange+c + + 24220 +1 nt!ObReferenceObjectByHandle+1c3 + win32k!ProtectHandle+22 + win32k!xxxCreateThreadInfo+3a0 + win32k!UserThreadCallout+6f + win32k!W32pThreadCallout+38 + nt!PsConvertToGuiThread+174 + nt!KiBBTUnexpectedRange+c + + 24221 -1 nt!ObfDereferenceObject+19 + win32k!xxxCreateThreadInfo+3a0 + win32k!UserThreadCallout+6f + win32k!W32pThreadCallout+38 + nt!PsConvertToGuiThread+174 + nt!KiBBTUnexpectedRange+c + +---- ---------------------------------------------------------- +References: 3, Dereferences 2 +``` + +The primary indicators in the **!obtrace 0xfa96f700** display are listed in the following table. + + ++++ + + + + + + + + + + + + + + + + +
ParameterMeaning

Sequence

Represents the order of operations.

+/-

Indicates a reference or a dereference operation.

+

+1 indicates a reference operation.

+

-1 indicates a dereference operation.

+

+/- n indicates multiple reference/dereference operations.

+ +  + +The object reference traces on x64-based target computers might be incomplete because it is not always possible to acquire stack traces at IRQL levels higher than PASSIVE\_LEVEL. + +You can stop execution at any time by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!obtrace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ocommand--expect-commands-from-target-.md b/windows-driver-docs-pr/debugger/-ocommand--expect-commands-from-target-.md new file mode 100644 index 0000000000..c5f542ba9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ocommand--expect-commands-from-target-.md @@ -0,0 +1,115 @@ +--- +title: .ocommand (Expect Commands from Target) +description: The .ocommand command enables the target application to send commands to the debugger. +ms.assetid: a4363395-111f-48eb-b1da-c17c0ad9f067 +keywords: ["Expect Commands from Target (.ocommand) command", ".ocommand (Expect Commands from Target) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .ocommand (Expect Commands from Target) +api_type: +- NA +--- + +# .ocommand (Expect Commands from Target) + + +The **.ocommand** command enables the target application to send commands to the debugger. + +``` +.ocommand String +.ocommand -d +.ocommand +``` + +## Parameters + + + *String* +Specifies the command prefix string. *String* can include spaces, but you cannot use C-style control characters such as **\\"** and **\\n**. You can also enclose *String* in quotation marks. However, if *String* includes a semicolon, leading spaces, or trailing spaces, you must enclose *String* in quotation marks. + + **-d** +Deletes the command prefix string. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about [**OutputDebugString**](https://msdn.microsoft.com/library/windows/desktop/aa363362) and other user-mode functions that communicate with a debugger, see the Microsoft Windows SDK documentation. + +Remarks +------- + +If you use the **.ocommand** command without parameters, the debugger displays the current command prefix string. To clear the existing string, use **.ocommand -d**. + +When you have set a command prefix string, any target output (such as the contents of an [**OutputDebugString**](https://msdn.microsoft.com/library/windows/desktop/aa363362) command) is scanned. If this output begins with the command prefix string, the text of the output that follows the prefix string is treated as a debugger command string and is run. When this text is executed, the command string is not displayed. + +The target can include an [**.echo (Echo Comment)**](-echo--echo-comment-.md) command in the output string if you want additional messages. Target output that does not begin with the prefix string is displayed in the typical manner. + +After the commands within the command string have been executed, the target remains broken into the debugger, unless the final command is [**g (Go)**](g--go-.md). + +The comparison between the command prefix string and the target output is not case sensitive. (However, subsequent uses of **.ocommand** display the string that you entered with the case preserved). + +For this example, assume that you enter the following command in the debugger. + +``` +0:000> .ocommand magiccommand +``` + +Then, the target application executes the following line. + +``` +OutputDebugString("MagicCommand kb;g"); +``` + +The debugger recognizes the command string prefix and executes **kb;g** immediately. + +However, the following line does not cause any commands to be executed. + +``` +OutputDebugString("Command on next line.\nmagiccommand kb;g"); +``` + +There are no commands executed from the preceding example because the command string prefix is not at the beginning of the output, even though it does begin a new line. + +**Note**   You should choose a command string prefix that will not likely appear in any target output other than your own commands. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.ocommand%20%28Expect%20Commands%20from%20Target%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ofilter--filter-target-output-.md b/windows-driver-docs-pr/debugger/-ofilter--filter-target-output-.md new file mode 100644 index 0000000000..748d753956 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ofilter--filter-target-output-.md @@ -0,0 +1,87 @@ +--- +title: .ofilter (Filter Target Output) +description: The .ofilter command filters the output from the target application or target computer. +ms.assetid: 0b94d177-0e41-4781-b0bc-ed58cee584f1 +keywords: ["Filter Target Output (.ofilter) command", ".ofilter (Filter Target Output) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .ofilter (Filter Target Output) +api_type: +- NA +--- + +# .ofilter (Filter Target Output) + + +The **.ofilter** command filters the output from the target application or target computer. + +``` +.ofilter [/!] String +.ofilter "" +.ofilter +``` + +## Parameters + + + **/!** +Reverses the filter so that the debugger displays only output that does not contain *String*. If you do not use this parameter, the debugger displays only output that contains *String*. + + *String* +Specifies the string to match in the target's output. *String* can include spaces, but you cannot use C-style control characters such as **\\"** and **\\n**. *String* might contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). + +You can enclose *String* in quotation marks. However, if *String* includes a semicolon, leading spaces, or trailing spaces, you must use quotation marks. Alphanumeric characters in *String* are converted to uppercase letters, but the actual pattern matching is case insensitive. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about [**OutputDebugString**](https://msdn.microsoft.com/library/windows/desktop/aa363362) and other user-mode routines, see the Microsoft Windows SDK documentation. For more information about **DbgPrint**, **DbgPrintEx**, and other kernel-mode routines, see the Windows Driver Kit (WDK). + +Remarks +------- + +If you use the **.ofilter** command without parameters, the debugger displays the current pattern-matching criteria. + +To clear the existing filter, use **.ofilter ""**. This command filters any data that is sent by user-mode routines (such as [**OutputDebugString**](https://msdn.microsoft.com/library/windows/desktop/aa363362)) and kernel-mode routines (such as **DbgPrint**). However, the debugger always displays prompts that **DbgPrompt** sends. + +The **DbgPrintEx** and **KdPrintEx** routines supply another method of filtering debugging messages that you do not want. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.ofilter%20%28Filter%20Target%20Output%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-open--open-source-file-.md b/windows-driver-docs-pr/debugger/-open--open-source-file-.md new file mode 100644 index 0000000000..185d671fbd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-open--open-source-file-.md @@ -0,0 +1,82 @@ +--- +title: .open (Open Source File) +description: The .open command searches the source path for a source file and opens this file. +ms.assetid: 49944fc8-5ecb-47a4-a046-0df18a242e72 +keywords: [".open (Open Source File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .open (Open Source File) +api_type: +- NA +--- + +# .open (Open Source File) + + +The **.open** command searches the source path for a source file and opens this file. + +``` +.open [-m Address] FileName +.open -a Address +``` + +## Parameters + + + *FileName* +Specifies the source file name. This name can include an absolute or relative path. Unless you specify an absolute path, the path is interpreted as relative to a directory in the source path. + + **-m** **** *Address* +Specifies an address within the source file. This address must be contained in a known module. You should use the **-m** **** *Address* parameter if the file that *FileName* specifies is not unique. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +The **-m** parameter is required if you are using a [source server](using-a-source-server.md) to retrieve the source files. + + **-a** *Address* +Specifies an address within the source file. This address must be contained in a known module. If the debugger can find the source file, the debugger loads and opens the file, and the line that corresponds to the specified address is highlighted. If the debugger cannot find the source file, the address is displayed in the [Disassembly window](disassembly-window.md). For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + +You can use the **.open** command only in WinDbg, and you cannot use it in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about source files and source paths and for other ways to load source files, see [Source Path](source-path.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.open%20%28Open%20Source%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-opendump--open-dump-file-.md b/windows-driver-docs-pr/debugger/-opendump--open-dump-file-.md new file mode 100644 index 0000000000..eace102d99 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-opendump--open-dump-file-.md @@ -0,0 +1,83 @@ +--- +title: .opendump (Open Dump File) +description: The .opendump command opens a dump file for debugging. +ms.assetid: 751af9ea-be7e-4aef-a6f6-fc99e3b3a56e +keywords: [".opendump (Open Dump File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .opendump (Open Dump File) +api_type: +- NA +--- + +# .opendump (Open Dump File) + + +The **.opendump** command opens a dump file for debugging. + +``` +.opendump DumpFile +.opendump /c "DumpFileInArchive" [CabFile] +``` + +## Parameters + + + *DumpFile* +Specifies the name of the dump file to open. *DumpFile* should include the file name extension (typically .dmp or .mdmp) and can include an absolute or relative path. Relative paths are relative to the directory that you started the debugger in. + + **/c** **"***DumpFileInArchive***"** +Specifies the name of a dump file to debug. This dump file must be contained in the archive file that *CabFile* specifies. You must enclose the *DumpFileInArchive* file in quotation marks. + + *CabFile* +Specifies the name of an archive file to open. *CabFile*should include the file name extension (typically .cab) and can include an absolute or relative path. Relative paths are relative to the directory that you started the debugger in. If you use the **/c** switch to specify a dump file in an archive but you omit *CabFile*, the debugger reuses the archive file that you most recently opened. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Crash dump only (but you can use this command if other sessions are running)

Platforms

All

+ +  + +Remarks +------- + +After you use the **.opendump** command, you must use the [**g (Go)**](g--go-.md) command to finish loading the dump file. + +When you are opening an archive file (such as a CAB file), you should use the **/c** switch. If you do not use this switch and you specify an archive for *DumpFile*, the debugger opens the first file that has an .mdmp or .dmp file name extension within this archive. + +You can use **.opendump** even if a debugging session is already in progress. This feature enables you to debug more than one crash dump at the same time. For more information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +  +**Note**   There are complications, when you debug live targets and dump targets together, because commands behave differently for each type of debugging. For example, if you use the **g (Go)** command when the current system is a dump file, the debugger begins executing, but you cannot break back into the debugger, because the break command is not recognized as valid for dump file debugging. +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.opendump%20%28Open%20Dump%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-openmaps.md b/windows-driver-docs-pr/debugger/-openmaps.md new file mode 100644 index 0000000000..9b1a7920be --- /dev/null +++ b/windows-driver-docs-pr/debugger/-openmaps.md @@ -0,0 +1,72 @@ +--- +title: openmaps +description: The openmaps extension displays the referenced buffer control blocks (BCBs) and virtual address control blocks (VACBs) for the specified shared cache map. +ms.assetid: 4ecce331-c18e-462a-807a-b8929059b897 +keywords: ["BCB (buffer control block)", "VACB (virtual address control block)", "shared cache map", "cache manager", "openmaps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- openmaps +api_type: +- NA +--- + +# !openmaps + + +The **!openmaps** extension displays the referenced buffer control blocks (BCBs) and virtual address control blocks (VACBs) for the specified shared cache map. + +``` +!openmaps Address [Flag] +``` + +## Parameters + + + *Address* +Specifies the address of the shared cache map. + + *Flag* +Determines which control blocks are displayed. If *Flag* is **1**, the debugger displays all control blocks. If *Flag* is **0**, the debugger displays only referenced control blocks. The default is **0**. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For information about other cache management extensions, see the [**!cchelp**](-cchelp.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!openmaps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-outmask--control-output-mask-.md b/windows-driver-docs-pr/debugger/-outmask--control-output-mask-.md new file mode 100644 index 0000000000..9f074e30e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-outmask--control-output-mask-.md @@ -0,0 +1,159 @@ +--- +title: .outmask (Control Output Mask) +description: The .outmask command controls the current output mask. +ms.assetid: a925f948-a746-4fed-9ccd-95513f41e3bf +keywords: ["Control Output Mask (.outmask) command", ".outmask (Control Output Mask) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .outmask (Control Output Mask) +api_type: +- NA +--- + +# .outmask (Control Output Mask) + + +The **.outmask** command controls the current output mask. + +``` +.outmask[-] [/l] Expression +.outmask /a +.outmask /d +``` + +## Parameters + + + *Expression* +Specifies the flags to add to the mask. *Expression* can be any ULONG value that specifies the flag bits that you want. For a list of the possible flags, see the table in the Remarks section. + + **-** +Removes the bits that *Expression* specifies from the mask, instead of adding them to the mask. + + **/l** +Preserves the current value of the log file's output mask. If you do not include **/l**, the log file's output mask is the same as the regular output mask. + + **/a** +Activates all mask flags. This parameter is equivalent to **.outmask 0xFFFFFFFF**. + + **/d** +Restores the output mask to the default value. This parameter is equivalent to **.outmask 0x3F7**. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +Each output mask flag enables the debugger to display certain output in the [Debugger Command Window](debugger-command-window.md). If all of the mask flags are set, all output is displayed. + +You should remove output mask flags with caution, because you might be unable to read debugger output. + +The following flag values exist. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDefault settingDescription

1

On

Normal output

2

On

Error output

4

On

Warnings

8

Off

Additional output

0x10

On

Prompt output

0x20

On

Register dump before prompt

0x40

On

Warnings that are specific to extension operation

0x80

On

Debug output from the target (for example, OutputDebugString or DbgPrint)

0x100

On

Debug input expected by the target (for example, DbgPrompt)

0x200

On

Symbol messages (for example, !sym noisy)

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.outmask%20%28Control%20Output%20Mask%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-owner.md b/windows-driver-docs-pr/debugger/-owner.md new file mode 100644 index 0000000000..c551604a2f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-owner.md @@ -0,0 +1,77 @@ +--- +title: owner +description: The owner extension displays the owner of a module or function. +ms.assetid: f881bd86-89cf-49fd-9bca-3ecc96123be8 +keywords: ["owner Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- owner +api_type: +- NA +--- + +# !owner + + +The **!owner** extension displays the owner of a module or function. + +``` +!owner [Module[!Symbol]] +``` + +## Parameters + + + *Module* +Specifies the module whose owner is desired. An asterisk (\*) at the end of *Module* represents any number of additional characters. + + *Symbol* +Specifies the symbol within *Module* whose owner is desired. An asterisk (\*) at the end of *Symbol* represents any number of additional characters. If *Symbol* is omitted, the owner of the entire module is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +Remarks +------- + +If no parameters are used and a fault has occurred, **!owner** will display the name of the owner of the faulting module or function. + +When you pass a module or function name to the **!owner** extension, the debugger displays the word **Followup** followed by the name of owner of the specified module or function. + +For this extension to display useful information, you must first create a triage.ini file containing the names of the module and function owners. + +For details on the triage.ini file and an example of the **!owner** extension, see [Specifying Module and Function Owners](specifying-module-and-function-owners.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!owner%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pagein--page-in-memory-.md b/windows-driver-docs-pr/debugger/-pagein--page-in-memory-.md new file mode 100644 index 0000000000..d5c74a43f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pagein--page-in-memory-.md @@ -0,0 +1,107 @@ +--- +title: .pagein (Page In Memory) +description: The .pagein command pages in the specified region of memory. +ms.assetid: 5fb8f9d2-d07a-49c3-b844-aade9bdba367 +keywords: ["Page In Memory (.pagein) command", "memory, Page In Memory (.pagein) command", ".pagein (Page In Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .pagein (Page In Memory) +api_type: +- NA +--- + +# .pagein (Page In Memory) + + +The **.pagein** command pages in the specified region of memory. + +``` +.pagein [Options] Address +``` + +## Parameters + + + *Options* +Any of the following options: + +**/p** **** *Process* +Specifies the address of the process that owns the memory that you want to page in. (More precisely, this parameter specifies the address of the EPROCESS block for the process.) If you omit *Process* or specify zero, the debugger uses the current process setting. For more information about the process setting, see [**.process (Set Process Context)**](-process--set-process-context-.md) + +**/f** +Forces the memory to be paged in, even if the address is in kernel memory and the version of the Microsoft Windows operating system does not support this action. + + *Address* +Specifies the address to page in. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only (but not during local kernel debugging)

Targets

Live debugging only

Platforms

All

+ +  + +Remarks +------- + +After you run the **.pagein** command, you must use the [**g (Go)**](g--go-.md) command to resume program execution. After a brief time, the target computer automatically breaks into the debugger again. + +At this point, the address that you specify is paged in. If you use the **/p** option, the process context is also set to the specified process, exactly as if you used the [**.process /i Process**](-process--set-process-context-.md) command. + +If the address is already paged in, the **.pagein** command still checks that the address is paged in and then breaks back into the debugger. If the address is invalid, this command only breaks back into the debugger. + +In Windows Server 2003 and Windows XP, you can page in only user-mode addresses by using **.pagein**. You can override this restriction by using the **/f** switch, but we do not recommend that you use this switch. In Windows Vista, you can safely page in user-mode and kernel-mode memory. + +**Warning**   If you use **.pagein** on an address in a kernel stack in Windows Server 2003 or Windows XP, a bug check might occur. + +  + +Requirements +------------ + + ++++ + + + + + + +

Version

Supported in Windows XP and later versions of Windows.

+ +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.pagein%20%28Page%20In%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pars.md b/windows-driver-docs-pr/debugger/-pars.md new file mode 100644 index 0000000000..1e01c86937 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pars.md @@ -0,0 +1,69 @@ +--- +title: pars +description: The pars extension displays a specified processor application registers file. +ms.assetid: cd952f00-a135-411c-99e0-20153f2539cd +keywords: ["processor application register", "pars Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pars +api_type: +- NA +--- + +# !pars + + +The **!pars** extension displays a specified processor application registers file. + +``` +!pars Address +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Address* +Specifies the address of a processor application registers file. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pars%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pat.md b/windows-driver-docs-pr/debugger/-pat.md new file mode 100644 index 0000000000..f4db730fbb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pat.md @@ -0,0 +1,66 @@ +--- +title: pat +description: The pat extension displays the Page Attribute Table (PAT) registers for the target processor. +ms.assetid: 41583410-08cc-49b5-96b2-b59d935f623e +keywords: ["PAT", "pat Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pat +api_type: +- NA +--- + +# !pat + + +The **!pat** extension displays the Page Attribute Table (PAT) registers for the target processor. + +``` +!pat Flag +!pat +``` + +## Parameters + + + *Flag* +If *Flag* is set, the debugger verifies that the PAT feature is present before the PAT is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pat%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pci.md b/windows-driver-docs-pr/debugger/-pci.md new file mode 100644 index 0000000000..15d3dad926 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pci.md @@ -0,0 +1,247 @@ +--- +title: pci +description: The pci extension displays the current status of the peripheral component interconnect (PCI) buses, as well as any devices attached to those buses. +ms.assetid: 37b767db-18c9-4fd3-8910-4be03f41e764 +keywords: ["PCI bus", "PCI device", "PCI configuration space", "pci Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pci +api_type: +- NA +--- + +# !pci + + +The **!pci** extension displays the current status of the peripheral component interconnect (PCI) buses, as well as any devices attached to those buses. + +``` +!pci [Flags [Segment] [Bus [Device [Function [MinAddress MaxAddress]]]]] +``` + +## Parameters + + + *Flags* +Specifies the level of output. Can be any combination of the following bits: + +Bit 0 (0x1) +Causes a verbose display. + +Bit 1 (0x2) +Causes the display to include all buses in the range from bus 0 (zero) to the specified *Bus*. + +Bit 2 (0x4) +Causes the display to include information in raw byte format. If *MinAddress*, *MaxAddress*, or flag bit 0x8 is set, this bit is automatically set as well. + +Bit 3 (0x8) +Causes the display to include information in raw DWORD format. + +Bit 4 (0x10) +Causes the display to include invalid device numbers. If *Device* is specified, this flag is ignored. + +Bit 5 (0x20) +Causes the display to include invalid function numbers. + +Bit 6 (0x40) +Causes the display to include capabilities. + +Bit 7 (0x80) +Causes the display to include Intel 8086 device-specific information. + +Bit 8 (0x100) +Causes the display to include the PCI configuration space. + +Bit 9 (0x200) +Causes the display to include segment information. When this bit is included, the *Segment* parameter must be included. + +Bit 10 (0x400) +Causes the display to include all valid segments in the range from segment 0 to the specified segment. When this bit is included, the *Segment* parameter must be included. + + *Segment* +Specifies the number of the segment to be displayed. Segment numbers range from 0 to 0xFFFF. If *Segment* is omitted, information about the primary segment (segment 0) is displayed. If *Flags* includes bit 10 (0x400), *Segment* specifies the highest valid segment to be displayed. + + *Bus* +Specifies the bus to be displayed. *Bus* can range from 0 to 0xFF. If it is omitted, information about the primary bus (bus 0) is displayed. If *Flags* includes bit 1 (0x2), *Bus* specifies the highest bus number to be displayed. + + *Device* +Specifies the slot device number for the device. If this is omitted, information about all devices is printed. + + *Function* +Specifies the slot function number for the device. If this is omitted, all information about all device functions is printed. + + *MinAddress* +Specifies the first address from which raw bytes or DWORDs are to be displayed. This must be between 0 and 0xFF. + + *MaxAddress* +Specifies the last address from which raw bytes or DWORDs are to be displayed. This must be between 0 and 0xFF, and not less than *MinAddress*. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kext.dll +Kdextx86.dll

Windows XP and later

Kext.dll

+ +  + +This extension command can only be used with an x86-based target computer. + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command and additional examples. For information about PCI buses, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +To edit the PCI configuration space, use [**!ecb**](-ecb---ecd---ecw.md), **!ecd**, or **!ecw**. + +The following example displays a list of all buses and their devices. This command will take a long time to execute. You will see a moving counter at the bottom of the display while the debugger scans the target system for PCI buses: + +``` +kd> !pci 2 ff +PCI Bus 0 +00:0 8086:1237.02 Cmd[0106:.mb..s] Sts[2280:.....] Device Host bridge +0d:0 8086:7000.01 Cmd[0007:imb...] Sts[0280:.....] Device ISA bridge +0d:1 8086:7010.00 Cmd[0005:i.b...] Sts[0280:.....] Device IDE controller +0e:0 1011:0021.02 Cmd[0107:imb..s] Sts[0280:.....] PciBridge 0->1-1 PCI-PCI bridge +10:0 102b:0519.01 Cmd[0083:im....] Sts[0280:.....] Device VGA compatible controller +PCI Bus 1 +08:0 10b7:9050.00 Cmd[0107:imb..s] Sts[0200:.....] Device Ethernet +09:0 9004:8178.00 Cmd[0117:imb..s] Sts[0280:.....] Device SCSI controller +``` + +This example displays verbose information about the devices on the primary bus. The two-digit number at the beginning of each line is the device number; the one-digit number following it is the function number: + +``` +kd> !pci 1 0 +PCI Bus 0 +00:0 8086:1237.02 Cmd[0106:.mb..s] Sts[2280:.....] Device Host bridge + cf8:80000000 IntPin:0 IntLine:0 Rom:0 cis:0 cap:0 + +0d:0 8086:7000.01 Cmd[0007:imb...] Sts[0280:.....] Device ISA bridge + cf8:80006800 IntPin:0 IntLine:0 Rom:0 cis:0 cap:0 + +0d:1 8086:7010.00 Cmd[0005:i.b...] Sts[0280:.....] Device IDE controller + cf8:80006900 IntPin:0 IntLine:0 Rom:0 cis:0 cap:0 + IO[4]:fff1 + +0e:0 1011:0021.02 Cmd[0107:imb..s] Sts[0280:.....] PciBridge 0->1-1 PCI-PCI bridge + cf8:80007000 IntPin:0 IntLine:0 Rom:0 cap:0 2sts:2280 BCtrl:6 ISA + IO:f000-ffff Mem:fc000000-fdffffff PMem:fff00000-fffff + +10:0 102b:0519.01 Cmd[0083:im....] Sts[0280:.....] Device VGA compatible controller + cf8:80008000 IntPin:1 IntLine:9 Rom:80000000 cis:0 cap:0 + MEM[0]:fe800000 MPF[1]:fe000008 +``` + +This example shows even more detailed information about bus 0 (zero), device 0x0D, and function 0x1, including the raw DWORDS from addresses between 0x00 and 0x3F: + +``` +kd> !pci f 0 d 1 0 3f +PCI Bus 0 +0d:1 8086:7010.00 Cmd[0005:i.b...] Sts[0280:.....] Device IDE controller + cf8:80006900 IntPin:0 IntLine:0 Rom:0 cis:0 cap:0 + IO[4]:fff1 + 00000000: 70108086 02800005 01018000 00002000 + 00000010: 00000000 00000000 00000000 00000000 + 00000020: 0000fff1 00000000 00000000 00000000 + 00000030: 00000000 00000000 00000000 00000000 +``` + +This example displays the configuration space for segment 1, bus 0, device 1: + +``` +0: kd> !pci 301 1 0 1 + +PCI Configuration Space (Segment:0001 Bus:00 Device:01 Function:00) +Common Header: + 00: VendorID 14e4 Broadcom Corporation + 02: DeviceID 16c7 + 04: Command 0146 MemSpaceEn BusInitiate PERREn SERREn + 06: Status 02b0 CapList 66MHzCapable FB2BCapable DEVSELTiming:1 +. +. +. + 5a: MsgCtrl 64BitCapable MultipleMsgEnable:0 (0x1) MultipleMsgCapable:3 (0x8) + 5c: MsgAddr 2d4bff00 + 60: MsgAddrHi 1ae09097 + 64: MsData 9891 + +``` + +To display all devices and buses on valid segments, issue the command **!pci 602 ffff ff**: + +``` +0: kd> !pci 602 ffff ff +Scanning the following PCI segments: 0 0x1 +PCI Segment 0 Bus 0 +01:0 14e4:16c7.10 Cmd[0146:.mb.ps] Sts[02b0:c6...] Ethernet Controller SubID:103c:1321 +02:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +02:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +03:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +03:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +PCI Segment 0 Bus 0x38 +01:0 14e4:1644.12 Cmd[0146:.mb.ps] Sts[02b0:c6...] Ethernet Controller SubID:10b7:1000 +PCI Segment 0 Bus 0x54 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0x54->0x55-0x55 +PCI Segment 0 Bus 0x70 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0x70->0x71-0x71 +PCI Segment 0 Bus 0xa9 +01:0 8086:b154.00 Cmd[0147:imb.ps] Sts[0ab0:c6.A.] Intel PCI-PCI Bridge 0xa9->0xaa-0xaa +PCI Segment 0 Bus 0xaa +04:0 1033:0035.41 Cmd[0146:.mb.ps] Sts[0210:c....] NEC USB Controller SubID:103c:1293 +04:1 1033:0035.41 Cmd[0146:.mb.ps] Sts[0210:c....] NEC USB Controller SubID:103c:aa55 +04:2 1033:00e0.02 Cmd[0146:.mb.ps] Sts[0210:c....] NEC USB2 Controller SubID:103c:aa55 +05:0 1002:5159.00 Cmd[0187:imb..s] Sts[0290:c....] ATI VGA Compatible Controller SubID:103c:1292 +PCI Segment 0 Bus 0xc6 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0xc6->0xc7-0xc7 +PCI Segment 0 Bus 0xe3 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0xe3->0xe4-0xe4 +PCI Segment 0x1 Bus 0 +01:0 14e4:16c7.10 Cmd[0146:.mb.ps] Sts[02b0:c6...] Ethernet Controller SubID:103c:1321 +02:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +02:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +03:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +03:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...] LSI SCSI Controller SubID:103c:1323 +PCI Segment 0x1 Bus 0x54 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0x54->0x55-0x55 +PCI Segment 0x1 Bus 0x55 +00:0 8086:10b9.06 Cmd[0147:imb.ps] Sts[0010:c....] Intel Ethernet Controller SubID:8086:1083 +PCI Segment 0x1 Bus 0x70 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0x70->0x71-0x71 +PCI Segment 0x1 Bus 0xc6 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0xc6->0xc7-0xc7 +PCI Segment 0x1 Bus 0xe3 +00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....] HP PCI-PCI Bridge 0xe3->0xe4-0xe4 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pci%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pciir.md b/windows-driver-docs-pr/debugger/-pciir.md new file mode 100644 index 0000000000..f594928e49 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pciir.md @@ -0,0 +1,70 @@ +--- +title: pciir +description: The pciir extension displays the contents of the hardware routing of peripheral component interconnect (PCI) devices to interrupt controller inputs. +ms.assetid: 83d1b716-adfe-4712-bdbb-25960c38fff0 +keywords: ["PCI IRQ routing table", "peripheral component interconnect (PCI)", "pciir Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pciir +api_type: +- NA +--- + +# !pciir + + +The **!pciir** extension displays the contents of the hardware routing of peripheral component interconnect (PCI) devices to interrupt controller inputs. + +``` +!pciir +``` + +### DLL + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP

+

Windows Server 2003

Kdexts.dll

Windows Vista and later

Unavailable

+ +  + +This extension command can only be used with an x86-based target computer that does not have the Advanced Configuration and Power Interface (ACPI) enabled. + +### Additional Information + +For similar information on any ACPI-enabled computer, use the [**!acpiirqarb**](-acpiirqarb.md) extension. + +For information about PCI buses, see the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pciir%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pcitree.md b/windows-driver-docs-pr/debugger/-pcitree.md new file mode 100644 index 0000000000..1878817c7e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pcitree.md @@ -0,0 +1,98 @@ +--- +title: pcitree +description: The pcitree extension displays information about PCI device objects, including child PCI buses and CardBus buses, and the devices attached to them. +ms.assetid: cd1b2f85-b8de-4396-8b37-79bb3d62092c +keywords: ["PCI bus", "PCI device", "pcitree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pcitree +api_type: +- NA +--- + +# !pcitree + + +The **!pcitree** extension displays information about PCI device objects, including child PCI buses and CardBus buses, and the devices attached to them. + +``` +!pcitree +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about PCI buses and PCI device objects, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +Here is an example: + +``` +kd> !pcitree + +Bus 0x0 (FDO Ext fe517338) + 0600 12378086 (d=0, f=0) devext fe4f4ee8 Bridge/HOST to PCI + 0601 70008086 (d=d, f=0) devext fe4f4ce8 Bridge/PCI to ISA + 0101 70108086 (d=d, f=1) devext fe4f4ae8 Mass Storage Controller/IDE + 0604 00211011 (d=e, f=0) devext fe4f4788 Bridge/PCI to PCI + +Bus 0x1 (FDO Ext fe516998) + 0200 905010b7 (d=8, f=0) devext fe515ee8 Network Controller/Ethernet + 0100 81789004 (d=9, f=0) devext fe515ce8 Mass Storage Controller/SCSI + 0300 0519102b (d=10, f=0) devext fe4f4428 Display Controller/VGA + +Total PCI Root busses processed = 1 +``` + +To understand this display, consider the final device shown. Its base class is 03, its subclass is 00, its Device ID is 0x0519, and its Vendor ID is 0x102B. These values are all intrinsic to the device itself. + +The number after "d=" is the device number; the number after "f=" is the function number. After "devext" is the device extension address, 0xFE4F4428. Finally, the base class name and the subclass name appear. + +To obtain more information about a device, use the [**!devext**](-devext.md) extension command with the device extension address as the argument. For this particular device, the command to use would be: + +``` +kd> !devext fe4f4428 pci +``` + +If the **!pcitree** extension generates an error, this often means that your PCI symbols were not loaded properly. Use [**.reload pci.sys**](-reload--reload-module-.md) to fix this problem. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pcitree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pcm.md b/windows-driver-docs-pr/debugger/-pcm.md new file mode 100644 index 0000000000..1dd8a35521 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pcm.md @@ -0,0 +1,74 @@ +--- +title: pcm +description: The pcm extension displays the specified private cache map. This extension is only available in Windows 2000. +ms.assetid: a6880ad0-5326-4bea-ac84-3311a2ec01da +keywords: ["private cache map", "cache manager", "pcm Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pcm +api_type: +- NA +--- + +# !pcm + + +The **!pcm** extension displays the specified private cache map. This extension is only available in Windows 2000. + +``` +!pcm Address +``` + +## Parameters + + + *Address* +Specifies the address of the private cache map. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable (see Remarks section)

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For information about other cache management extensions, see the [**!cchelp**](-cchelp.md) extension reference. + +Remarks +------- + +This extension is supported only in Windows 2000. In Windows XP and later versions of Windows, use the [**dt nt!\_PRIVATE\_CACHE\_MAP Address**](dt--display-type-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pcm%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pcmd--set-prompt-command-.md b/windows-driver-docs-pr/debugger/-pcmd--set-prompt-command-.md new file mode 100644 index 0000000000..fd2de93597 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pcmd--set-prompt-command-.md @@ -0,0 +1,122 @@ +--- +title: .pcmd (Set Prompt Command) +description: The .pcmd command causes the debugger to issue a command whenever the target stops executing and to display a prompt in the Debugger Command window with register or target state information. +ms.assetid: 8cda10c3-860c-453d-9fdd-0dfc74d71c53 +keywords: [".pcmd (Set Prompt Command) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .pcmd (Set Prompt Command) +api_type: +- NA +--- + +# .pcmd (Set Prompt Command) + + +The **.pcmd** command causes the debugger to issue a command whenever the target stops executing and to display a prompt in the [Debugger Command window](debugger-command-window.md) with register or target state information. + +``` +.pcmd -s CommandString +.pcmd -c +.pcmd +``` + +## Parameters + + + **-s** **** *CommandString* +Specifies a new prompt command string. Whenever the target stops executing, the debugger issues and immediately runs the *CommandString* command. If *CommandString* contains spaces or semicolons, you must enclose it in quotation marks. + + **-c** +Deletes any existing prompt command string. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the Debugger Command window prompt, see [Using Debugger Commands](using-debugger-commands.md). + +Remarks +------- + +If you use the **.pcmd** command without parameters, the current prompt command is displayed. + +When you set a prompt command by using **.pcmd -s**, the specified *CommandString* is issued whenever the target stops executing (for example, when a [**g**](g--go-.md), [**p**](p--step-.md), or [**t**](t--trace-.md) command ends). The *CommandString* command is not issued when you use a non-execution command, unless that command displays registers or target state information. + +In the following example, the first use of **.pcmd** sets a fixed string that appears with the prompt. The second use of **.pcmd** causes the debugger to display the target's current process ID and thread ID every time that the prompt appears. The special prompt does not appear after the [**.ttime**](-ttime--display-thread-times-.md) command is used, because that command does not involve execution. + +``` +0:000> .pcmd +No per-prompt command + +0:000> .pcmd -s ".echo Execution is done." +Per-prompt command is '.echo Execution is done.' + +0:000> t +Prymes!isPrime+0xd0: +004016c0 837dc400 cmp dword ptr [ebp-0x3c],0x0 ss:0023:0012fe70=00000002 +Execution is done. + +0:000> t +Prymes!isPrime+0xd4: +004016c4 7507 jnz Prymes!isPrime+0xdd (004016cd) + [br=1] +Execution is done. + +0:000> .ttime +Created: Thu Aug 21 13:18:59 2003 +Kernel: 0 days 0:00:00.031 +User: 0 days 0:00:00.000 + +0:000> .pcmd -s "r $tpid, $tid" +Per-prompt command is 'r $tpid, $tid' + +0:000> t +Prymes!isPrime+0xdd: +004016cd ebc0 jmp Prymes!isPrime+0x9f (0040168f) +$tpid=0000080c $tid=00000514 + +0:000> t +Prymes!isPrime+0x9f: +0040168f 8b55fc mov edx,[ebp-0x4] ss:0023:0012fea8=00000005 +$tpid=0000080c $tid=00000514 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.pcmd%20%28Set%20Prompt%20Command%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pcr.md b/windows-driver-docs-pr/debugger/-pcr.md new file mode 100644 index 0000000000..d5d145c0c1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pcr.md @@ -0,0 +1,106 @@ +--- +title: pcr +description: The pcr extension displays the current status of the Processor Control Region (PCR) on a specific processor. +ms.assetid: a9d82aa4-57de-4170-80fd-b7cd5b82f1e5 +keywords: ["processor control region (PCR)", "pcr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pcr +api_type: +- NA +--- + +# !pcr + + +The **!pcr** extension displays the current status of the Processor Control Region (PCR) on a specific processor. + +``` +!pcr [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor to retrieve the PCR information from. If *Processor* is omitted, the current processor is used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the PCR and the PRCB, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon.(This book may not be available in some languages and countries.) + +Remarks +------- + +The processor control block (PRCB) is an extension of the PCR. It can be displayed with the [**!prcb**](-prcb.md) extension. + +Here is an example of the **!pcr** extension on an x86 target computer: + +``` +kd> !pcr 0 +KPCR for Processor 0 at ffdff000: + Major 1 Minor 1 + NtTib.ExceptionList: 801626e0 + NtTib.StackBase: 801628f0 + NtTib.StackLimit: 8015fb00 + NtTib.SubSystemTib: 00000000 + NtTib.Version: 00000000 + NtTib.UserPointer: 00000000 + NtTib.SelfTib: 00000000 + + SelfPcr: ffdff000 + Prcb: ffdff120 + Irql: 00000000 + IRR: 00000000 + IDR: ffffffff + InterruptMode: 00000000 + IDT: 80043400 + GDT: 80043000 + TSS: 803cc000 + + CurrentThread: 8015e8a0 + NextThread: 00000000 + IdleThread: 8015e8a0 + + DpcQueue: 0x80168ee0 0x80100d04 ntoskrnl!KiTimerExpiration + +``` + +One of the entries in this display shows the interrupt request level (IRQL). The **!pcr** extension shows the current IRQL, but the current IRQL is usually not of much interest. The IRQL that existed just before the bug check or debugger connection is more interesting. This is displayed by [**!irql**](-irql.md), which is only available on computers running Windows Server 2003 or later versions of Windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pcr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pcrs.md b/windows-driver-docs-pr/debugger/-pcrs.md new file mode 100644 index 0000000000..80bd3dd977 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pcrs.md @@ -0,0 +1,74 @@ +--- +title: pcrs +description: The pcrs extension displays the Intel Itanium-specific processor control registers. +ms.assetid: 45a84a95-86df-4176-ba30-ac93b509f7f7 +keywords: ["processor control register (PCR)", "PCR (processor control register)", "pcrs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pcrs +api_type: +- NA +--- + +# !pcrs + + +The **!pcrs** extension displays the Intel Itanium-specific processor control registers. + +``` +!pcrs Address +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Address* +Specifies the address of a processor control registers file. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +This extension command can only be used with an Itanium-based target computer. + +Remarks +------- + +Do not confuse the **!pcrs** extension with the [**!pcr**](-pcr.md) extension, which displays the current status of the processor control region. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pcrs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-peb.md b/windows-driver-docs-pr/debugger/-peb.md new file mode 100644 index 0000000000..519880fd9a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-peb.md @@ -0,0 +1,112 @@ +--- +title: peb +description: The peb extension displays a formatted view of the information in the process environment block (PEB). +ms.assetid: 01687f13-9eb7-48f0-a0d6-54fee00084ab +keywords: ["PEB (process environment block)", "process, process environment block (PEB)", "peb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- peb +api_type: +- NA +--- + +# !peb + + +The **!peb** extension displays a formatted view of the information in the process environment block (PEB). + +``` +!peb [PEB-Address] +``` + +## Parameters + + + *PEB-Address* +The hexadecimal address of the process whose PEB you want to examine. (This is not the address of the PEB as derived from the kernel process block for the process.) If *PEB-Address* is omitted in user mode, the PEB for the current process is used. If it is omitted in kernel mode, the PEB corresponding to the current [process context](changing-contexts.md#process-context) is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Kdextx86.dll +Ntsdexts.dll

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +For information about process environment blocks, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The PEB is the user-mode portion of Microsoft Windows process control structures. + +If the **!peb** extension with no argument gives you an error in kernel mode, you should use the [**!process**](-process.md) extension to determine the PEB address for the desired process. Make sure your [process context](changing-contexts.md#process-context) is set to the desired process, and then use the PEB address as the argument for **!peb**. + +The exact output displayed depends on the Windows version and on whether you are debugging in kernel mode or user mode. The following example is taken from a kernel debugger attached to a Windows Server 2003 target: + +``` +kd> !peb +PEB at 7ffdf000 + InheritedAddressSpace: No + ReadImageFileExecOptions: No + BeingDebugged: No + ImageBaseAddress: 4ad00000 + Ldr 77fbe900 + Ldr.Initialized: Yes + Ldr.InInitializationOrderModuleList: 00241ef8 . 00242360 + Ldr.InLoadOrderModuleList: 00241e90 . 00242350 + Ldr.InMemoryOrderModuleList: 00241e98 . 00242358 + Base TimeStamp Module + 4ad00000 3d34633c Jul 16 11:17:32 2002 D:\WINDOWS\system32\cmd.exe + 77f40000 3d346214 Jul 16 11:12:36 2002 D:\WINDOWS\system32\ntdll.dll + 77e50000 3d3484ef Jul 16 13:41:19 2002 D:\WINDOWS\system32\kernel32.dll +.... + SubSystemData: 00000000 + ProcessHeap: 00140000 + ProcessParameters: 00020000 + WindowTitle: 'D:\Documents and Settings\Administrator\Desktop\Debuggers.lnk' + ImageFile: 'D:\WINDOWS\system32\cmd.exe' + CommandLine: '"D:\WINDOWS\system32\cmd.exe" ' + DllPath: 'D:\WINDOWS\system32;D:\WINDOWS\system32;.... + Environment: 00010000 + ALLUSERSPROFILE=D:\Documents and Settings\All Users + APPDATA=D:\Documents and Settings\UserTwo\Application Data + CLIENTNAME=Console +.... + windir=D:\WINDOWS +``` + +The similar [**!teb**](-teb.md) extension displays the thread environment block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!peb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pfn.md b/windows-driver-docs-pr/debugger/-pfn.md new file mode 100644 index 0000000000..372ddc5bd7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pfn.md @@ -0,0 +1,95 @@ +--- +title: pfn +description: The pfn extension displays information about a specific page frame or the entire page frame database. +ms.assetid: cbdb1f04-30bc-4e12-b073-9882e4457e1a +keywords: ["page frame", "pfn Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pfn +api_type: +- NA +--- + +# !pfn + + +The **!pfn** extension displays information about a specific page frame or the entire page frame database. + +``` +!pfn PageFrame +``` + +## Parameters + + + *PageFrame* +Specifies the hexadecimal number of the page frame to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about page tables, page directories, and page frames, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The page frame number for a virtual address can be obtained by using the [**!pte**](-pte.md) extension. + +Here is an example of the output from this extension: + +``` +kd> !pte 801544f4 +801544F4 - PDE at C0300800 PTE at C0200550 + contains 0003B163 contains 00154121 + pfn 3b G-DA--KWV pfn 154 G--A--KRV + +kd> !pfn 3b + PFN 0000003B at address 82350588 + flink 00000000 blink / share count 00000221 pteaddress C0300800 + reference count 0001 color 0 + restore pte 00000000 containing page 000039 Active + + +kd> !pfn 154 + PFN 00000154 at address 82351FE0 + flink 00000000 blink / share count 00000001 pteaddress C0200550 + reference count 0001 color 0 + restore pte 00000060 containing page 00003B Active M + Modified +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pfn%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pmc.md b/windows-driver-docs-pr/debugger/-pmc.md new file mode 100644 index 0000000000..d3d20bc7d1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pmc.md @@ -0,0 +1,94 @@ +--- +title: pmc +description: The pmc extension displays the Performance Monitor Counter (PMC) register at the specified address. +ms.assetid: ff9a03af-f0e9-4aef-b583-c3092eb5f89c +keywords: ["Performance Monitor Counter (PMC)", "pmc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pmc +api_type: +- NA +--- + +# !pmc + + +The **!pmc** extension displays the Performance Monitor Counter (PMC) register at the specified address. + +This extension is supported only on an Itanium-based target computer. + +``` +!pmc [- Option] Expression [DisplayLevel] +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Option* +Can be any one of the following values: + +**gen** +Displays the register as a generic PMC register. + +**btb** +Displays the register as a branch trace buffer (BTB) PMC register. + + *Expression* +Specifies the hexadecimal address of a PMC. The expressions **@kpfcgen** and **@kpfcbtb** can be used as values for this parameter. + +If *Expression* is **@kpfcgen**, the debugger displays the current processor PMC register as a generic PMC register. You can also display the current processor PMC register as a generic PMC register by setting *Option* to **gen** and using **@kpfc4**, **@kpfc5**, **@kpfc6**, or **@kpfc7** for the *Expression* value. + +If *Expression* is **@kpfcbtb**, the debugger displays the current processor PMC register as a BTB PMC register. You can also display the current processor PMC register as a BTB PMC register by setting *Option* to **btb** and using @kpfc12 for the *Expression* value. + + *DisplayLevel* +Can be any one of the following values: + +**0** +Displays only the values of each PMC register field. This is the default. + +**1** +Displays detailed information about the PMC register fields that are not reserved or ignored. + +**2** +Displays detailed information about all PMC register fields, including those that are ignored or reserved. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pmc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pmssa.md b/windows-driver-docs-pr/debugger/-pmssa.md new file mode 100644 index 0000000000..815edea82f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pmssa.md @@ -0,0 +1,69 @@ +--- +title: pmssa +description: The pmssa extension displays a specified processor Minimal State Save Area (also known as Min-StateSave Area). +ms.assetid: 55d605bd-0621-4366-8b37-62d462ee1f34 +keywords: ["processor minstate save area", "pmssa Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pmssa +api_type: +- NA +--- + +# !pmssa + + +The **!pmssa** extension displays a specified processor Minimal State Save Area (also known as Min-StateSave Area). + +This extension can only be used with an Itanium-based target computer. + +``` +!pmssa Address +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Address* +Specifies the address of a processor Min-StateSave Area. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pmssa%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pnpevent.md b/windows-driver-docs-pr/debugger/-pnpevent.md new file mode 100644 index 0000000000..6b080af911 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pnpevent.md @@ -0,0 +1,73 @@ +--- +title: pnpevent +description: The pnpevent extension displays the Plug and Play device event queue. +ms.assetid: 5f70fbf8-1313-4238-a917-c3fba8c80927 +keywords: ["pnpevent Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pnpevent +api_type: +- NA +--- + +# !pnpevent + + +The **!pnpevent** extension displays the Plug and Play device event queue. + +``` +!pnpevent [DeviceEvent] +``` + +## Parameters + + + *DeviceEvent* +Specifies the address of a device event to display. If this is zero or omitted, the tree of all device events in the queue is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about Plug and Play drivers, see the Windows Driver Kit (WDK) documentation. + +## See also + + +[Plug and Play and Power Debugger Commands](plug-and-play-and-power-debugger-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pnpevent%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-pocaps.md b/windows-driver-docs-pr/debugger/-pocaps.md new file mode 100644 index 0000000000..d5689d6730 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pocaps.md @@ -0,0 +1,84 @@ +--- +title: pocaps +description: The pocaps extension displays the power capabilities of the target computer. +ms.assetid: 011d923a-a5c4-4d3b-ba06-fe5dc884adaa +keywords: ["pocaps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pocaps +api_type: +- NA +--- + +# !pocaps + + +The **!pocaps** extension displays the power capabilities of the target computer. + +``` +!pocaps +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +To view the system's power policy, use the [**!popolicy**](-popolicy.md) extension command. For information about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Here is an example of this command's output: + +``` +kd> !pocaps +PopCapabilities @ 0x8016b100 + Misc Supported Features: S4 FullWake + Processor Features: + Disk Features: SpinDown + Battery Features: + Wake Caps + Ac OnLine Wake: Sx + Soft Lid Wake: Sx + RTC Wake: Sx + Min Device Wake: Sx + Default Wake: Sx +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pocaps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pool.md b/windows-driver-docs-pr/debugger/-pool.md new file mode 100644 index 0000000000..0d98e45ca9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pool.md @@ -0,0 +1,131 @@ +--- +title: pool extension command +description: The pool extension displays information about a specific pool allocation or about the entire system-wide pool. +ms.assetid: 1c224e0c-d50c-487e-8238-9be054368ac2 +keywords: ["pool", "pool, See "memory"", "pooltag.txt file", "pool tag", "memory, pool tag", "pool Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pool +api_type: +- NA +--- + +# !pool + + +The **!pool** extension displays information about a specific pool allocation or about the entire system-wide pool. + +``` +!pool [Address [Flags]] +``` + +## Parameters + + + *Address* +Specifies the pool entry to be displayed. If *Address* is -1, this command displays information about all heaps in the process. + +If *Address* is 0 or omitted, this command displays information about the process heap. + + *Flags* +Specifies the level of detail to be used. This can be any combination of the following bit values; the default is zero: + +Bit 0 (0x1) +Causes the display to include the pool contents, not just the pool headers. + +Bit 1 (0x2) +Causes the display to suppress pool header information for all pools, except the one that actually contains the specified *Address*. + +Bit 31 (0x80000000) +(Windows XP and later) Suppresses the description of the pool type and pool tag in the display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about memory pools, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +In Windows XP and later versions of Windows, the **!pool** extension displays the pool tag associated with each allocation. The owner of that pool tag is also displayed. This display is based on the contents of the pooltag.txt file. This file is located in the triage subdirectory of your Debugging Tools for Windows installation. If you want , you can edit this file to add additional pool tags relevant to your project. + +**Warning**   If you install an updated version of Debugging Tools for Windows in the same directory as the current version, it overwrites all of the files in that directory, including pooltag.txt. If you modify or replace the sample pooltag.txt file, be sure to save a copy of it to a different directory. After reinstalling the debuggers, you can copy the saved pooltag.txt over the default version. + +  + +If the **!pool** extension reports pool corruption, you should use [**!poolval**](-poolval.md) to investigate. + +Here is an example. If *Address* specifies 0xE1001050, the headers of all pools in this block are displayed, and 0xE1001050 itself is marked with an asterisk (\*). + +``` +kd> !pool e1001050 + e1001000 size: 40 previous size: 0 (Allocated) MmDT + e1001040 size: 10 previous size: 40 (Free) Mm +*e1001050 size: 10 previous size: 10 (Allocated) *ObDi + e1001060 size: 10 previous size: 10 (Allocated) ObDi + e1001070 size: 10 previous size: 10 (Allocated) Symt + e1001080 size: 40 previous size: 10 (Allocated) ObDm + e10010c0 size: 10 previous size: 40 (Allocated) ObDi +..... +``` + +In this example, the right-most column shows the pool tag. The column to the left of this shows whether the pool is free or allocated. + +The following command shows the pool headers and pool contents: + +``` +kd> !pool e1001050 1 + e1001000 size: 40 previous size: 0 (Allocated) MmDT + e1001008 ffffffff 0057005c 004e0049 004f0044 + e1001018 ffffffff 0053005c 00730079 00650074 + + e1001040 size: 10 previous size: 40 (Free) Mm + e1001048 ffffffff e1007ba8 e1501a58 01028101 + e1001058 ffffffff 00000000 e1000240 01028101 + +*e1001050 size: 10 previous size: 10 (Allocated) *ObDi + e1001058 ffffffff 00000000 e1000240 01028101 + e1001068 ffffffff 00000000 e10009c0 01028101 + + e1001060 size: 10 previous size: 10 (Allocated) ObDi + e1001068 ffffffff 00000000 e10009c0 01028101 + e1001078 ffffffff 00000000 00000000 04028101 + +...... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-poolfind.md b/windows-driver-docs-pr/debugger/-poolfind.md new file mode 100644 index 0000000000..67ee75d673 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-poolfind.md @@ -0,0 +1,140 @@ +--- +title: poolfind +description: The poolfind extension finds all instances of a specific pool tag in either nonpaged or paged memory pools. +ms.assetid: 01783b6b-0117-49ca-87ca-bbe3c1b0e730 +keywords: ["poolfind Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- poolfind +api_type: +- NA +--- + +# !poolfind + + +The **!poolfind** extension finds all instances of a specific pool tag in either nonpaged or paged memory pools. + +``` +!poolfind TagString [PoolType] +!poolfind TagValue [PoolType] +``` + +## Parameters + + + *TagString* +Specifies the pool tag. *TagString* is a case-sensitive ASCII string. The asterisk (\*) can be used to represent any number of characters; the question mark (?) can be used to represent exactly one character. Unless an asterisk is used, *TagString* must be exactly four characters in length. + + *TagValue* +Specifies the pool tag. *TagValue* must begin with "0x", even if the default radix is 16. If this parameter begins with any other value (including "0X") it will be interpreted as an ASCII tag string. + + *PoolType* +Specifies the type of pool to be searched. The following values are permitted: + +0 +Specifies nonpaged memory pool. This is the default. + +1 +Specifies paged memory pool. + +2 +Specifies the special pool. + +4 +(Windows XP and later) Specifies the session pool. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about memory pools and pool tags, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +This command can take a significant amount of time to execute, depending on the size of pool memory that must be searched. To speed up this execution, increase the COM port speed with the [**CTRL+A (Toggle Baud Rate)**](ctrl-a--toggle-baud-rate-.md) key, or use the [**.cache (Set Cache Size)**](-cache--set-cache-size-.md) command to increase the cache size (to approximately 10 MB). + +The pool tag is the same tag passed to the **ExAllocate***Xxx* family of routines. + +Here is an example. The entire nonpaged pool is searched and then the paged pool is searched, but the command is terminated before completion (after an hour of operation): + +``` +kd> !poolfind SeSd 0 + +Scanning large pool allocation table for Tag: SeSd (827d1000 : 827e9000) + +Searching NonPaged pool (823b1000 : 82800000) for Tag: SeSd + +826fa130 size: c0 previous size: 40 (Allocated) SeSd +82712000 size: c0 previous size: 0 (Allocated) SeSd +82715940 size: a0 previous size: 60 (Allocated) SeSd +8271da30 size: c0 previous size: 10 (Allocated) SeSd +82721c00 size: 10 previous size: 30 (Free) SeSd +8272b3f0 size: 60 previous size: 30 (Allocated) SeSd +8272d770 size: 60 previous size: 40 (Allocated) SeSd +8272d7d0 size: a0 previous size: 60 (Allocated) SeSd +8272d960 size: a0 previous size: 70 (Allocated) SeSd +82736f30 size: a0 previous size: 10 (Allocated) SeSd +82763840 size: a0 previous size: 10 (Allocated) SeSd +8278b730 size: 100 previous size: 290 (Allocated) SeSd +8278b830 size: 10 previous size: 100 (Free) SeSd +82790130 size: a0 previous size: 20 (Allocated) SeSd +82799180 size: a0 previous size: 10 (Allocated) SeSd +827c00e0 size: a0 previous size: 30 (Allocated) SeSd +827c8320 size: a0 previous size: 60 (Allocated) SeSd +827ca180 size: a0 previous size: 50 (Allocated) SeSd +827ec140 size: a0 previous size: 10 (Allocated) SeSd + +Searching NonPaged pool (fe7c3000 : ffbe0000) for Tag: SeSd + +kd> !poolfind SeSd 1 + +Scanning large pool allocation table for Tag: SeSd (827d1000 : 827e9000) + +Searching Paged pool (e1000000 : e4400000) for Tag: SeSd + +e10000b0 size: d0 previous size: 20 (Allocated) SeSd +e1000260 size: d0 previous size: 60 (Allocated) SeSd +...... +e1221dc0 size: a0 previous size: 60 (Allocated) SeSd +e1224250 size: a0 previous size: 30 (Allocated) SeSd + +...terminating - searched pool to e1224000 +kd> +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!poolfind%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-poolused.md b/windows-driver-docs-pr/debugger/-poolused.md new file mode 100644 index 0000000000..1e0c53c5c2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-poolused.md @@ -0,0 +1,145 @@ +--- +title: poolused +description: The poolused extension displays memory use summaries, based on the tag used for each pool allocation. +ms.assetid: e801342d-2536-43a3-992b-99942eb3c5ae +keywords: ["poolused Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- poolused +api_type: +- NA +--- + +# !poolused + + +The **!poolused** extension displays memory use summaries, based on the tag used for each pool allocation. + +``` +!poolused [Flags [TagString]] +``` + +## Parameters + + + *Flags* +Specifies the amount of output to be displayed and the method of sorting the output. This can be any combination of the following bit values, except that bits 1 (0x2) and 2 (0x4) cannot be used together. The default is 0x0, which produces summary information, sorted by pool tag. + +Bit 0 (0x1) +Displays more detailed (verbose) information. + +Bit 1 (0x2) +Sorts the display by the amount of nonpaged memory use. + +Bit 2 (0x4) +Sorts the display by the amount of paged memory use. + +Bit 3 (0x8) +(Windows Server 2003 and later) Displays the session pool instead of the standard pool. + +**Note**  You can use the [**!session**](-session.md) command to switch between sessions. + +  + + *TagString* +Specifies the pool tag. *TagString* is a case-sensitive ASCII string. The asterisk (\*) can be used to represent any number of characters; the question mark (?) can be used to represent exactly one character. Unless an asterisk is used, *TagString* must be exactly four characters in length. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about memory pools and pool tags, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The **!poolused** extension gathers data from the pool tagging feature of Windows. Pool tagging is permanently enabled on Windows Server 2003 and later versions of Windows. On Windows XP and earlier versions of Windows, you must enable pool tagging by using [Gflags](gflags.md). + +If you stop executing the extension before it completes, the debugger displays partial results. + +The display for this command shows the memory use for each tag in paged pool and nonpaged pool. In both cases, the display includes the number of currently outstanding allocations for the given tag and the number of bytes being consumed by those allocations. + +Here is a partial example of the output from this extension: + +``` +0: kd> !poolused + Sorting by Tag + + Pool Used: + NonPaged Paged + Tag Allocs Used Allocs Used + 1394 1 520 0 0UNKNOWN pooltag '1394', please update pooltag.txt + 1MEM 1 3368 0 0UNKNOWN pooltag '1MEM', please update pooltag.txt + 2MEM 1 3944 0 0UNKNOWN pooltag '2MEM', please update pooltag.txt + 3MEM 3 248 0 0UNKNOWN pooltag '3MEM', please update pooltag.txt + 8042 4 3944 0 0PS/2 kb and mouse , Binary: i8042prt.sys + AGP 1 344 2 384UNKNOWN pooltag 'AGP ', please update pooltag.txt + AcdN 2 1072 0 0TDI AcdObjectInfoG + AcpA 3 192 1 504ACPI Pooltags , Binary: acpi.sys + AcpB 0 0 4 576ACPI Pooltags , Binary: acpi.sys + AcpD 40 13280 0 0ACPI Pooltags , Binary: acpi.sys + AcpF 6 240 0 0ACPI Pooltags , Binary: acpi.sys + AcpM 0 0 1 128ACPI Pooltags , Binary: acpi.sys + AcpO 4 208 0 0ACPI Pooltags , Binary: acpi.sys + +... + + WmiG 30 6960 0 0Allocation of WMIGUID + WmiR 63 4032 0 0Wmi Registration info blocks + Wmip 146 3504 182 18600Wmi General purpose allocation + Wmit 1 4096 7 49480Wmi Trace + Wrpa 2 720 0 0WAN_ADAPTER_TAG + Wrpc 1 72 0 0WAN_CONN_TAG + Wrpi 1 120 0 0WAN_INTERFACE_TAG + Wrps 2 128 0 0WAN_STRING_TAG + aEoP 1 672 0 0UNKNOWN pooltag 'aEoP', please update pooltag.txt + fEoP 1 16 0 0UNKNOWN pooltag 'fEoP', please update pooltag.txt + hSVD 0 0 1 40Shared Heap Tag , Binary: mrxdav.sys + hibr 0 0 1 24576UNKNOWN pooltag 'hibr', please update pooltag.txt + iEoP 1 24 0 0UNKNOWN pooltag 'iEoP', please update pooltag.txt + idle 2 208 0 0Power Manager idle handler + jEoP 1 24 0 0UNKNOWN pooltag 'jEoP', please update pooltag.txt + mEoP 1 88 0 0UNKNOWN pooltag 'mEoP', please update pooltag.txt + ohci 1 136 0 01394 OHCI host controller driver + rx.. 3 1248 0 0UNKNOWN pooltag ' rx', please update pooltag.txt + sidg 2 48 0 0GDI spooler events + thdd 0 0 1 20480DirectDraw/3D handle manager table + usbp 18 77056 2 96UNKNOWN pooltag 'usbp', please update pooltag.txt + vPrt 0 0 18 68160UNKNOWN pooltag 'vPrt', please update pooltag.txt + TOTAL 3570214 209120008 38769 13066104 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!poolused%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-poolval.md b/windows-driver-docs-pr/debugger/-poolval.md new file mode 100644 index 0000000000..4b64b8113f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-poolval.md @@ -0,0 +1,82 @@ +--- +title: poolval +description: The poolval extension analyzes the headers for a pool page and diagnoses any possible corruption. This extension is only available in Windows XP and later versions. +ms.assetid: b67ab2d4-c765-4721-81ed-c6b7c9a0ba6d +keywords: ["poolval Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- poolval +api_type: +- NA +--- + +# !poolval + + +The **!poolval** extension analyzes the headers for a pool page and diagnoses any possible corruption. This extension is only available in Windows XP and later versions. + +``` +!poolval Address [DisplayLevel] +``` + +## Parameters + + + *Address* +Specifies the address of the pool whose header is to be analyzed. + + *DisplayLevel* +Specifies the information to include in the display. This can be any of the following values (the default is zero): + +0 +Causes basic information to be displayed. + +1 +Causes basic information and linked header lists to be displayed. + +2 +Causes basic information, linked header lists, and basic header information to be displayed. + +3 +Causes basic information, linked header lists, and full header information to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about memory pools, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!poolval%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pop--restore-debugger-state-.md b/windows-driver-docs-pr/debugger/-pop--restore-debugger-state-.md new file mode 100644 index 0000000000..27336f7cf1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pop--restore-debugger-state-.md @@ -0,0 +1,77 @@ +--- +title: .pop (Restore Debugger State) +description: The .pop command restores the state of the debugger to a state that has previously been saved by using the .push (Save Debugger State) command. +ms.assetid: 31f94b2a-3597-40e4-845a-d686274e36c3 +keywords: ["Restore Debugger State (.pop) command", ".pop (Restore Debugger State) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .pop (Restore Debugger State) +api_type: +- NA +--- + +# .pop (Restore Debugger State) + + +The **.pop** command restores the state of the debugger to a state that has previously been saved by using the [**.push (Save Debugger State)**](-push--save-debugger-state-.md) command. + +``` +.pop +.pop /r +.pop /r /q +``` + +## Parameters + + + **/r** +Specifies that the saved values of the pseudo-registers $t0 to $t19 should be restored. If **/r** is not included, these values are not affected by the **.pop** command. + + **/q** +Specifies that the command executes quietly. That is, the command executes without displaying any output. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +This command is most useful when used with [scripts](using-script-files.md) and [debugger command programs](using-debugger-command-programs.md) so that they can work with one fixed state. If the command is successful, no output is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.pop%20%28Restore%20Debugger%20State%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-popolicy.md b/windows-driver-docs-pr/debugger/-popolicy.md new file mode 100644 index 0000000000..696c353d83 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-popolicy.md @@ -0,0 +1,96 @@ +--- +title: popolicy +description: The popolicy extension displays the power policy of the target computer. +ms.assetid: 4917e6e8-982f-41d7-acd8-047e590e1253 +keywords: ["popolicy Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- popolicy +api_type: +- NA +--- + +# !popolicy + + +The **!popolicy** extension displays the power policy of the target computer. + +``` +!popolicy [Address] +``` + +## Parameters + + + *Address* +Specifies the address of the power policy structure to display. If this is omitted, then nt!PopPolicy is displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +To view the system's power capabilities, use the [**!pocaps**](-pocaps.md) extension command. For information about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Here is an example of this command's output: + +``` +kd> !popolicy +SYSTEM_POWER_POLICY (R.1) @ 0x80164d58 + PowerButton: Shutdown Flags: 00000003 Event: 00000000 Query UI + SleepButton: None Flags: 00000003 Event: 00000000 Query UI + LidClose: None Flags: 00000001 Event: 00000000 Query + Idle: None Flags: 00000001 Event: 00000000 Query + OverThrottled: None Flags: c0000004 Event: 00000000 Override NoWakes Critical + IdleTimeout: 0 IdleSensitivity: 50% + MinSleep: S0 MaxSleep: S0 + LidOpenWake: S0 FastSleep: S0 + WinLogonFlags: 1 S4Timeout: 0 + VideoTimeout: 0 VideoDim: 209 + SpinTimeout: 0 OptForPower: 1 + FanTolerance: 0% ForcedThrottle: 0% + MinThrottle: 0% +``` + +## See also + + +[Plug and Play and Power Debugger Commands](plug-and-play-and-power-debugger-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!popolicy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-powertriage.md b/windows-driver-docs-pr/debugger/-powertriage.md new file mode 100644 index 0000000000..39a1d4e700 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-powertriage.md @@ -0,0 +1,148 @@ +--- +title: powertriage +description: The powertriage extension displays summary information about the system and device power related components. +ms.assetid: A202ED64-B706-42AC-B058-C44321C9171F +keywords: ["powertriage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- powertriage +api_type: +- NA +--- + +# !powertriage + + +The !powertriage extension displays summary information about the system and device power related components. It also provides links to related commands that can be used to gather additional information. The !powertriage command has no parameters. This command can be used with both live kernel-mode debugging and for crash dump file analysis. + +Syntax + +``` +!powertriage +``` + +## Parameters + + +None + +### DLL + + ++++ + + + + + + +

Windows 10 and later

Kdexts.dll

+ +  + +Remarks +------- + +The !powertriage extension displays the following information. + +1. Power state of the device node along with !podev for all the device objects. +2. Links to [**!rcdrkd.rcdrlogdump**](-rcdrkd-rcdrlogdump.md) if the driver has enabled the IFR. For more information about IFR, see [Using Inflight Trace Recorder (IFR) in KMDF and UMDF 2 Drivers](https://msdn.microsoft.com/library/windows/hardware/dn940485). +3. Links to [**!wdfkd.wdfdriverinfo**](-wdfkd-wdfdriverinfo.md) and [**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) for WDF drivers. +4. Links to !fxdevice for PoFx devices. For more information about PoFX, see [Overview of the Power Management Framework](https://msdn.microsoft.com/library/windows/hardware/hh406637). +Here is example output from the !powertriage command. + +``` +kd> !powertriage + +System Capabilities : + Machine is not AOAC capable. + +Power Capabilities: +PopCapabilities @ 0xfffff8022f6c4380 + Misc Supported Features: PwrButton S1 S3 S4 S5 HiberFile FullWake + Processor Features: + Disk Features: + Battery Features: + Wake Caps + Ac OnLine Wake: Sx + Soft Lid Wake: Sx + RTC Wake: S4 + Min Device Wake: Sx + Default Wake: Sx + + + +Power Action: + +PopAction :fffff8022f6ba550 + Current System State..: Working + Target System State...: Unspecified + State.................: - Idle(0) + +Devices with allocated Power IRPs: + + + ACPI\PNP0C0C\2&daba3ff&1 + 0xffffe00023939ad0 ACPI D0 !podev WAIT_WAKE_IRP !irp Related Threads + + + USB\ROOT_HUB30\5&2c60645a&0&0 + 0xffffe0002440ac40 USBXHCI D2 !podev WAIT_WAKE_IRP !irp Related Threads !rcdrlogdump !wdfdriverinfo !wdflogdump + Upper DO 0xffffe00024415a10 USBHUB3 !podev + + + + USB\ROOT_HUB30\5&d91dce5&0&0 + 0xffffe00023ed4d30 USBXHCI D2 !podev WAIT_WAKE_IRP !irp Related Threads !rcdrlogdump !wdfdriverinfo !wdflogdump + Upper DO 0xffffe000249d8040 USBHUB3 !podev + + + PCI\VEN_8086&DEV_27E2&SUBSYS_01DE1028&REV_01\3&172e68dd&0&E5 + 0xffffe000239e5880 pci D0 !podev FxDevice: !fxdevice WAIT_WAKE_IRP !irp Related Threads + Upper DO 0xffffe000239c0e50 ACPI !podev + Upper DO 0xffffe000239f7040 pci !podev + + + + PCI\VEN_14E4&DEV_167A&SUBSYS_01DE1028&REV_02\4&24ac2e11&0&00E5 + 0xffffe000231e6060 pci D0 !podev WAIT_WAKE_IRP !irp Related Threads + Upper DO 0xffffe00024359050 b57nd60a !podev + + +Device Tree Info: + + !devpowerstate + + !devpowerstate Complete + + +Links: +!poaction +!cstriage +!pdctriage +!pdcclients +!fxdevice +!pnptriage +``` + +**Dump File Power Failure Analysis** + +The !powertriage extension can be useful in examining system crashes related to incorrect power state information. For example, in the case of [**Bug Check 0x9F: DRIVER\_POWER\_STATE\_FAILURE**](bug-check-0x9f--driver-power-state-failure.md), the extension will display all the allocated power IRPs, the associated device stacks along with: + +1. Links to the [**!irp**](-irp.md) command for the related IRPs. +2. Links to the [**!findthreads**](-findthreads.md) command with the related IRP. The IRP is added as part of the search criteria and displays the threads starting with higher correlation to the search criteria threads listed first. +Dumping all device stacks with power IRPs can help in debugging cases where !analyze has not been able to correctly identify the IRP associated with the crash. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!powertriage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pplookaside.md b/windows-driver-docs-pr/debugger/-pplookaside.md new file mode 100644 index 0000000000..ad09044107 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pplookaside.md @@ -0,0 +1,44 @@ +--- +title: pplookaside +description: The pplookaside command displays Lookaside Lists for processors in the target computer. +ms.assetid: AA5DD47A-849F-462E-AFA6-E743E9737E1A +keywords: ["pplookaside Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pplookaside +api_type: +- NA +--- + +# !pplookaside + + +The **!pplookaside** command displays [Lookaside Lists](https://msdn.microsoft.com/library/windows/hardware/ff565416) for processors in the target computer. + +``` +!pplookaside
+``` + +## Parameters + + +*ParamName* +The address of the processor. + +### DLL + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pplookaside%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmidle.md b/windows-driver-docs-pr/debugger/-ppmidle.md new file mode 100644 index 0000000000..b34dd861ec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmidle.md @@ -0,0 +1,51 @@ +--- +title: ppmidle +description: The ppmidle command +ms.assetid: 40037C2E-DE68-42BB-AFEB-C012F042082D +keywords: ["ppmidle Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmidle +api_type: +- NA +--- + +# !ppmidle + + +The **!ppmidle** command displays processor idle states. + +``` +!ppmidle +``` + +## Parameters + +None + +This command is supported on the following versions of Windows: + +- Windows 7 +- Windows 8 +- Windows 8.1 +- Windows 10, Version 1511 +- Windows 10, Version 1607 +- Windows 10, Version 1703 + +### DLL + +Kdexts.dll + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmidle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmidleaccounting.md b/windows-driver-docs-pr/debugger/-ppmidleaccounting.md new file mode 100644 index 0000000000..58c913e5fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmidleaccounting.md @@ -0,0 +1,50 @@ +--- +title: ppmidleaccounting +description: The ppmidleaccounting command +ms.assetid: DD0D35EE-874B-43E4-BF47-09C5BF305B12 +keywords: ["ppmidleaccounting Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmidleaccounting +api_type: +- NA +--- + +# !ppmidleaccounting + + +The **!ppmidleaccounting** command displays processor idle state accounting information. + +``` +!ppmidleaccounting +``` + +## Parameters +None + +This command is supported on the following versions of Windows: + +- Windows 7 +- Windows 8 +- Windows 8.1 +- Windows 10, Version 1511 +- Windows 10, Version 1607 +- Windows 10, Version 1703 + +### DLL + + Kdexts.dll + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmidleaccounting%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmidlepolicy.md b/windows-driver-docs-pr/debugger/-ppmidlepolicy.md new file mode 100644 index 0000000000..2a22e995bf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmidlepolicy.md @@ -0,0 +1,45 @@ +--- +title: ppmidlepolicy +description: The ppmidlepolicy command +ms.assetid: FA77159F-95B3-42F9-9452-CE4827DD4EC5 +keywords: ["ppmidlepolicy Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 06/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmidlepolicy +api_type: +- NA +--- + +# !ppmidlepolicy + +The **!ppmidlepolicy** command displays C-state policy. + +``` +!ppmidlepolicy +``` + +## Parameters + +None + +This command is supported on the following versions of Windows: + +- Windows 7 + +### DLL + +Kdexts.dll + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmidlepolicy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmlpscenarios.md b/windows-driver-docs-pr/debugger/-ppmlpscenarios.md new file mode 100644 index 0000000000..25dfd8cd60 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmlpscenarios.md @@ -0,0 +1,46 @@ +--- +title: ppmlpscenarios +description: The ppmlpscenarios command +ms.assetid: B4973314-1A9E-42B8-A2C9-B4069B09C956 +keywords: ["ppmlpscenarios Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmlpscenarios +api_type: +- NA +--- + +# !ppmlpscenarios + + +The **!ppmlpscenarios** command displays per-scenario policy overrides. + +``` +!ppmlpscenarios +``` + +## Parameters + +None + +This command is supported on the following versions of Windows: + +- Windows 8 + +### DLL + +Kdexts.dll + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmlpscenarios%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmperf.md b/windows-driver-docs-pr/debugger/-ppmperf.md new file mode 100644 index 0000000000..af585669fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmperf.md @@ -0,0 +1,43 @@ +--- +title: ppmperf +description: The ppmperf command +ms.assetid: B6BCB832-E7D9-44AA-9305-9A017124022B +keywords: ["ppmperf Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmperf +api_type: +- NA +--- + +# !ppmperf + +The **!ppmperf** command displays power and performance constraint information. + + +``` +!ppmperf +``` + +## Parameters + +None + +### DLL + + kedexts.dll + +**NOTE:** This command is not supported on all versions of Windows, such as Windows 10, Version 1703. +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmperf%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmperfpolicy.md b/windows-driver-docs-pr/debugger/-ppmperfpolicy.md new file mode 100644 index 0000000000..4722aa7490 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmperfpolicy.md @@ -0,0 +1,43 @@ +--- +title: ppmperfpolicy +description: The ppmperfpolicy command +ms.assetid: D81DDC0B-703D-402A-B823-AE5097CE7CDB +keywords: ["ppmperfpolicy Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmperfpolicy +api_type: +- NA +--- + +# !ppmperfpolicy + + +The **!ppmperfpolicy** command is no longer supported, use the [!ppmsettings](-ppmsettings.md) command instead. + +``` +!ppmperfpolicy +``` + +## Parameters + +None + +### DLL + +Kdexts.dll +   + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmperfpolicy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmsettings.md b/windows-driver-docs-pr/debugger/-ppmsettings.md new file mode 100644 index 0000000000..72b8e4ecf4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmsettings.md @@ -0,0 +1,48 @@ +--- +title: ppmsettings +description: The ppmsettings command +ms.assetid: 673F3F48-9328-45AF-8DB8-2CAB6E86D1B4 +keywords: ["ppmsettings Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 06/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmsettings +api_type: +- NA +--- + +# !ppmsettings + + +The **!ppmsettings** command displays currently active ppm settings for the processor. + +``` +!ppmsettings +``` + +## Parameters + +None + +This command is supported on the following versions of Windows: + +- Windows 10, Version 1511 +- Windows 10, Version 1607 +- Windows 10, Version 1703 + +### DLL + +Kdexts.dll + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmsettings%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ppmstate.md b/windows-driver-docs-pr/debugger/-ppmstate.md new file mode 100644 index 0000000000..a0e3c2fd23 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ppmstate.md @@ -0,0 +1,44 @@ +--- +title: ppmstate +description: The ppmstate command +ms.assetid: 45181F34-6753-4C5D-B573-A46B7E64870B +keywords: ["ppmstate Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ppmstate +api_type: +- NA +--- + +# !ppmstate + +The **!ppmstate** command displays power state information. + +``` +!ppmstate +``` + +## Parameters + +None + + +### DLL + +Kdexts.dll + + +**NOTE:** This command is not supported on all versions of Windows, such as Windows 10, Version 1703. +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ppmstate%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-prcb.md b/windows-driver-docs-pr/debugger/-prcb.md new file mode 100644 index 0000000000..8a9856cfe2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-prcb.md @@ -0,0 +1,84 @@ +--- +title: prcb +description: The prcb extension displays the processor control block (PRCB). +ms.assetid: 747695a1-8a5d-4d30-9315-91f4bf7f568e +keywords: ["processor control block", "prcb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- prcb +api_type: +- NA +--- + +# !prcb + + +The **!prcb** extension displays the processor control block (PRCB). + +``` +!prcb [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor to retrieve the PRCB information from. If *Processor* is omitted, processor zero will be used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about the PCR and the PRCB, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The PRCB is an extension of the processor control region (PCR). To display the PCR, use the [**!pcr**](-pcr.md) extension. + +Here is an example: + +``` +kd> !prcb +PRCB for Processor 0 at e0000000818ba000: +Threads-- Current e0000000818bbe10 Next 0000000000000000 Idle e0000000818bbe10 +Number 0 SetMember 00000001 +Interrupt Count -- 0000b81f +Times -- Dpc 00000028 Interrupt 000003ff + Kernel 00005ef4 User 00000385 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!prcb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-prefer-dml.md b/windows-driver-docs-pr/debugger/-prefer-dml.md new file mode 100644 index 0000000000..96e8b1bd08 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-prefer-dml.md @@ -0,0 +1,52 @@ +--- +title: .prefer_dml (Prefer Debugger Markup Language) +description: The .prefer_dml command sets the default behavior for commands that are capable of providing output in the Debugger Markup Language (DML) format. +ms.assetid: BBB96770-A575-4E31-AE8B-9226BB61727D +keywords: [".prefer_dml (Prefer Debugger Markup Language) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .prefer_dml (Prefer Debugger Markup Language) +api_type: +- NA +--- + +# .prefer\_dml (Prefer Debugger Markup Language) + + +The **.prefer\_dml** command sets the default behavior for commands that are capable of providing output in the Debugger Markup Language (DML) format. + +``` +.prefer_dml 0 +.prefer_dml 1 +``` + +## Parameters + + + 0 +By default, all commands will provide plain text output. + + 1 +By default, commands that are capable of providing DML output will provide DML output. + +## See also + + +[Debugger Markup Language Commands](debugger-markup-language-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.prefer_dml%20%28Prefer%20Debugger%20Markup%20Language%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-printf.md b/windows-driver-docs-pr/debugger/-printf.md new file mode 100644 index 0000000000..950d8fc050 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-printf.md @@ -0,0 +1,213 @@ +--- +title: .printf +description: The .printf token behaves like the printf statement in C. +ms.assetid: 16ad25c4-7df3-490e-80da-2beaddec3230 +keywords: [".printf Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .printf +api_type: +- NA +--- + +# .printf + + +The **.printf** token behaves like the **printf** statement in C. + +``` +.printf [/D] [Option] "FormatString" [, Argument , ...] +``` + +## Syntax Elements + + +**/D** +Specifies that the format string contains [Debugger Markup Language](debugger-markup-language-commands.md) (DML). + + *Option* +(WinDbg only) Specifies the type of text message that WinDbg should interpret the FormatString as. WinDbg assigns each type of Debugger Command window message a background and text color; choosing one of these options causes the message to be displayed in the appropriate colors. The default is to display the text as a normal-level message. For more information on message colors and how to set them, see [View | Options](view---options.md). + +The following options are available. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionType of messageTitle of colors in Options dialog box

/od

debuggee

Debuggee level command window

/oD

debuggee prompt

Debuggee prompt level command window

/oe

error

Error level command window

/on

normal

Normal level command window

/op

prompt

Prompt level command window

/oP

prompt registers

Prompt registers level command window

/os

symbols

Symbol message level command window

/ov

verbose

Verbose level command window

/ow

warning

Warning level command window

+ +  + + *FormatString* +Specifies the format string, as in **printf**. In general, conversion characters work exactly as in C. For the floating-point conversion characters, the 64-bit argument is interpreted as a 32-bit floating-point number unless the **l** modifier is used. + +The "I64" modifier can be added to indicate that a value should be interpreted as 64-bits. For instance, "%I64x" can be used to print a 64-bit hexadecimal number. + +The %p conversion character is supported, but it represents a pointer in the target's virtual address space. It must not have any modifiers and it uses the debugger's internal address formatting. In addition to the standard printf-style format specifiers, the following additional conversion characters are supported. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CharacterArgument typeArgumentText printed

%p

ULONG64

A pointer in the target's virtual address space.

The value of the pointer.

%N

DWORD_PTR (32 or 64 bits, depending on the host's architecture)

A pointer in the host's virtual address space.

The value of the pointer. (This is equivalent to the standard C %p character.)

%ma

ULONG64

The address of a NULL-terminated ASCII string in the target's virtual address space.

The specified string.

%mu

ULONG64

The address of a NULL-terminated Unicode string in the target's virtual address space.

The specified string.

%msa

ULONG64

The address of an ANSI_STRING structure in the target's virtual address space.

The specified string.

%msu

ULONG64

The address of a UNICODE_STRING structure in the target's virtual address space.

The specified string.

%y

ULONG64

The address of a debugger symbol in the target's virtual address space.

A string containing the name of the specified symbol (and displacement, if any).

%ly

ULONG64

The address of a debugger symbol in the target's virtual address space.

A string containing the name of the specified symbol (and displacement, if any), as well as any available source line information.

+ +  + + *Arguments* +Specifies arguments for the format string, as in **printf**. The number of arguments that are specified should match the number of conversion characters in *FormatString*. Each argument is an expression that will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The color settings that you can choose by using the *Options* parameter are by default all set to black text on a white background. To make best use of these options, you must first use [View | Options](view---options.md) to open the Options dialog box and change the color settings for Debugger Command window messages. + +The following example shows how to include a DML tag in the format string. + +``` +.printf /D "Click here to see extensions DLLs." +``` + +![screen shot of dml link in command browser window](images/printf01.png) + +The output shown in the preceding image has a link that you can click to execute the command specified in the `` tag. The following image shows the result of clicking the link. + +![screen shot of dml output in command browser window](images/printf02.png) + +For information about DML tags, see dml.doc in the installation folder for Debugging Tools for Windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.printf%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-process--set-process-context-.md b/windows-driver-docs-pr/debugger/-process--set-process-context-.md new file mode 100644 index 0000000000..eb8e9084b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-process--set-process-context-.md @@ -0,0 +1,165 @@ +--- +title: .process (Set Process Context) +description: The .process command specifies which process is used for the process context. +ms.assetid: f454faef-bc28-43f1-b511-bcee0c12fc24 +keywords: ["Set Process Context (.process) command", "addresses, Set Process Context (.process) command", "context, Set Process Context (.process) command", "Process, Set Process Context (.process) command", ".process (Set Process Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .process (Set Process Context) +api_type: +- NA +--- + +# .process (Set Process Context) + + +The **.process** command specifies which process is used for the process context. + +``` +.process [/i] [/p [/r]] [/P] [Process] +``` + +## Parameters + + + **/i** +(Windows XP and later; live debugging only; not during local kernel debugging) Specifies that *Process* is to be debugged *invasively*. This kind of debugging means that the operating system of the target computer actually makes the specified process active. (Without this option, the **.process** command alters the debugger's output but does not affect the target computer itself.) If you use **/i**, you must use the [**g (Go)**](g--go-.md) command to execute the target. After several seconds, the target breaks back in to the debugger, and the specified *Process* is active and used for the process context. + + **/p** +Translates all transition page table entries (PTEs) for this process to physical addresses before access, if you use **/p** and *Process* is nonzero. This translation might cause slowdowns, because the debugger must find the physical addresses for all of the memory that this process uses. Also, the debugger might have to transfer a significant amount of data across the debug cable. (This behavior is the same as [**.cache forcedecodeuser**](-cache--set-cache-size-.md).) + +If you include the **/p** option and *Process* is zero or you omit it, the translation is disabled. (This behavior is the same as [**.cache noforcedecodeptes**](-cache--set-cache-size-.md).) + + **/r** +Reloads user-mode symbols after the process context has been set, if you use the **/r** and **/p** options. (This behavior is the same as [**.reload /user**](-reload--reload-module-.md).) + + **/P** +(Live debugging and complete memory dumps only) Translates all transition page table entries (PTEs) to physical addresses before access, if you use **/P** and *Process* is nonzero. Unlike the **/p** option, the **/P** option translates the PTEs for all user-mode and kernel-mode processes, not only the specified process. This translation might cause slowdowns, because the debugger must find the physical addresses for all memory in use. Also, the debugger might have to transfer lots of data across the debug cable. (This behavior is the same as [**.cache forcedecodeptes**](-cache--set-cache-size-.md).) + + *Process* +Specifies the address of the process that you want. (More precisely, this parameter specifies the address of the EPROCESS block for this process). The process context is set to this process. If you omit *Process* or specify zero, the process context is reset to the default process for the current system state. (If you used the **/i** option to set process context, you must use the **/i** option to reset the process context.) + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the process context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +Typically, when you are doing kernel debugging, the only visible user-mode address space is the one that is associated with the current process. + +The **.process** command instructs the kernel debugger to use a specific user-mode process as the *process context*. This usage has several effects, but the most important is that the debugger has access to the virtual address space of this process. The debugger uses the page tables for this process to interpret all user-mode memory addresses, so you can read and write to this memory. + +The [**.context (Set User-Mode Address Context)**](-context--set-user-mode-address-context-.md) command has a similar effect. However, the **.context** command sets the *user-mode address context* to a specific page directory, while the **.process** command sets the process context to a specific process. On an x86-based processor, **.context** and **.process** have almost the same effect. However, on an Itanium-based processor, a single process might have more than one page directory. In this situation, the **.process** command is more powerful, because it enables access to all of the page directories that are associated with a process. For more information about the process context, see [Process Context](changing-contexts.md#process-context). + +**Note**   If you are performing live debugging, you should use the **/i** or the **/p** parameter. Without one of these parameters, you cannot correctly display user-mode or session memory. + +  + +The **/i** parameter activates the target process. When you use this option, you must execute the target once for this command to take effect. If you execute again, the process context is lost. + +The **/p** parameter enables the **forcedecodeuser** setting. (You do not have to use **/p** if the **forcedecodeuser** option is already active.) The process context and the **forcedecodeuser** state remain only until the target executes again. + +If you are performing crash dump debugging, the **/i** and **/p** options are not available. However, you cannot access any part of the user-mode process' virtual address space that were paged to disk when the crash occurred. + +If you want to use the kernel debugger to set breakpoints in user space, use the **/i** option to switch the target to the correct process context. + +The following example shows how to use the [**!process**](-process.md) extension to find the address of the EPROCESS block for the desired process. + +``` +kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +PROCESS fe5039e0 SessionId: 0 Cid: 0008 Peb: 00000000 ParentCid: 0000 + DirBase: 00030000 ObjectTable: fe529b68 TableSize: 50. + Image: System + +..... + +PROCESS fe3c0d60 SessionId: 0 Cid: 0208 Peb: 7ffdf000 ParentCid: 00d4 + DirBase: 0011f000 ObjectTable: fe3d0f48 TableSize: 30. + Image: regsvc.exe +``` + +Now the example uses the **.process** command with this process address. + +``` +kd> .process fe3c0d60 +Implicit process is now fe3c0d60 +``` + +Notice that this command makes the [**.context**](-context--set-user-mode-address-context-.md) command unnecessary. The user-mode address context already has the desired value. + +``` +kd> .context +User-mode page directory base is 11f000 +``` + +This value enables you to examine the address space in various ways. For example, the following example shows the output of the [**!peb**](-peb.md) extension. + +``` +kd> !peb +PEB at 7FFDF000 + InheritedAddressSpace: No + ReadImageFileExecOptions: No + BeingDebugged: No + ImageBaseAddress: 01000000 + Ldr.Initialized: Yes + Ldr.InInitializationOrderModuleList: 71f40 . 77f68 + Ldr.InLoadOrderModuleList: 71ec0 . 77f58 + Ldr.InMemoryOrderModuleList: 71ec8 . 77f60 + 01000000 C:\WINNT\system32\regsvc.exe + 77F80000 C:\WINNT\System32\ntdll.dll + 77DB0000 C:\WINNT\system32\ADVAPI32.dll + 77E80000 C:\WINNT\system32\KERNEL32.DLL + 77D40000 C:\WINNT\system32\RPCRT4.DLL + 77BE0000 C:\WINNT\system32\secur32.dll + SubSystemData: 0 + ProcessHeap: 70000 + ProcessParameters: 20000 + WindowTitle: 'C:\WINNT\system32\regsvc.exe' + ImageFile: 'C:\WINNT\system32\regsvc.exe' + CommandLine: 'C:\WINNT\system32\regsvc.exe' + DllPath: 'C:\WINNT\system32;.;C:\WINNT\System32;C:\WINNT\system;C:\WINNT;C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\PROGRA~1\COMMON~1\AUTODE~1' + Environment: 0x10000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.process%20%28Set%20Process%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-process.md b/windows-driver-docs-pr/debugger/-process.md new file mode 100644 index 0000000000..a05ee8b686 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-process.md @@ -0,0 +1,257 @@ +--- +title: process +description: The process extension displays information about the specified process, or about all processes, including the EPROCESS block. +ms.assetid: 57f55632-8320-47cc-8a20-5a2cf3b42b3a +keywords: ["process Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- process +api_type: +- NA +--- + +# !process + + +The !process extension displays information about the specified process, or about all processes, including the EPROCESS block. + +This extension can be used only during kernel-mode debugging. + +Syntax + +``` +!process [/s Session] [/m Module] [Process [Flags]] +!process [/s Session] [/m Module] 0 Flags ImageName +``` + +## Parameters + + +**/s** **** *Session* +Specifies the session that owns the desired process. + +**/m** **** *Module* +Specifies the module that owns the desired process. + + *Process* +Specifies the hexadecimal address or the process ID of the process on the target computer. + +The value of *Process* determines whether the !process extension displays a process address or a process ID . If *Process* is omitted in any version of Windows, the debugger displays data only about the current system process. If *Process* is 0 and *ImageName* is omitted, the debugger displays information about all active processes. + +*Flags* +Specifies the level of detail to display. *Flags* can be any combination of the following bits. If *Flags* is 0, only a minimal amount of information is displayed. The default varies according to the version of Windows and the value of *Process*. The default is 0x3 if *Process* is omitted or if *Process* is either 0 or -1; otherwise, the default is 0xF. + +Bit 0 (0x1) +Displays time and priority statistics. + +Bit 1 (0x2) +Displays a list of threads and events associated with the process, and their wait states. + +Bit 2 (0x4) +Displays a list of threads associated with the process. If this is included without Bit 1 (0x2), each thread is displayed on a single line. If this is included along with Bit 1, each thread is displayed with a stack trace. + +Bit 3 (0x8) +(Windows XP and later) Displays the return address, the stack pointer, and (on Itanium-based systems) the **bsp** register value for each function. The display of function arguments is suppressed. + +Bit 4 (0x10) +(Windows XP and later) Sets the process context equal to the specified process for the duration of this command. This results in a more accurate display of thread stacks. Because this flag is equivalent to using [**.process /p /r**](-process--set-process-context-.md) for the specified process, any existing user-mode module list will be discarded. If *Process* is zero, the debugger displays all processes, and the process context is changed for each one. If you are only displaying a single process and its user-mode state has already been refreshed (for example, with **.process /p /r**), it is not necessary to use this flag. This flag is only effective when used with Bit 0 (0x1). + +*ImageName* +Specifies the name of the process to be displayed. The debugger displays all processes whose executable image names match *ImageName*. The image name must match that in the EPROCESS block. In general, this is the executable name that was invoked to start the process, including the file extension (usually .exe), and truncated after the fifteenth character. There is no way to specify an image name that contains a space. When *ImageName* is specified, *Process* must be zero. + +## DLL + + +Kdexts.dll + +## Additional Information + + +For information about processes in kernel mode, see [Changing Contexts](changing-contexts.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +The following is an example of a **!process 0 0** display: + +``` +kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +PROCESS 80a02a60 Cid: 0002 Peb: 00000000 ParentCid: 0000 + DirBase: 00006e05 ObjectTable: 80a03788 TableSize: 150. + Image: System +PROCESS 80986f40 Cid: 0012 Peb: 7ffde000 ParentCid: 0002 + DirBase: 000bd605 ObjectTable: 8098fce8 TableSize: 38. + Image: smss.exe +PROCESS 80958020 Cid: 001a Peb: 7ffde000 ParentCid: 0012 + DirBase: 0008b205 ObjectTable: 809782a8 TableSize: 150. + Image: csrss.exe +PROCESS 80955040 Cid: 0020 Peb: 7ffde000 ParentCid: 0012 + DirBase: 00112005 ObjectTable: 80955ce8 TableSize: 54. + Image: winlogon.exe +PROCESS 8094fce0 Cid: 0026 Peb: 7ffde000 ParentCid: 0020 + DirBase: 00055005 ObjectTable: 80950cc8 TableSize: 222. + Image: services.exe +PROCESS 8094c020 Cid: 0029 Peb: 7ffde000 ParentCid: 0020 + DirBase: 000c4605 ObjectTable: 80990fe8 TableSize: 110. + Image: lsass.exe +PROCESS 809258e0 Cid: 0044 Peb: 7ffde000 ParentCid: 0026 + DirBase: 001e5405 ObjectTable: 80925c68 TableSize: 70. + Image: SPOOLSS.EXE +``` + +The following table describes some of the elements of the **!process 0 0** output. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementMeaning

Process address

The eight-character hexadecimal number after the word PROCESS is the address of the EPROCESS block. In the final entry in the preceding example, the process address is 0x809258E0.

Process ID (PID)

The hexadecimal number after the word Cid. In the final entry in the preceding example, the PID is 0x44, or decimal 68.

Process Environment Block (PEB)

The hexadecimal number after the word Peb is the address of the process environment block. In the final entry in the preceding example, the PEB is located at address 0x7FFDE000.

Parent process PID

The hexadecimal number after the word ParentCid is the PID of the parent process. In the final entry in the preceding example, the parent process PID is 0x26, or decimal 38.

Image

The name of the module that owns the process. In the final entry in the preceding example, the owner is spoolss.exe. In the first entry, the owner is the operating system itself.

Process object address

The hexadecimal number after the word ObjectTable. In the final entry in the preceding example, the address of the process object is 0x80925c68.

+ +  + +To display full details on one process, set *Flags* to 7. The process itself can be specified by setting *Process* equal to the process address, setting *Process* equal to the process ID, or setting *ImageName* equal to the executable image name. Here is an example: + +``` +kd> !process fb667a00 7 +PROCESS fb667a00 Cid: 0002 Peb: 00000000 ParentCid: 0000 + DirBase: 00030000 ObjectTable: e1000f88 TableSize: 112. + Image: System + VadRoot fb666388 Clone 0 Private 4. Modified 9850. Locked 0. + FB667BBC MutantState Signalled OwningThread 0 + Token e10008f0 + ElapsedTime 15:06:36.0338 + UserTime 0:00:00.0000 + KernelTime 0:00:54.0818 + QuotaPoolUsage[PagedPool] 1480 +Working Set Sizes (now,min,max) (3, 50, 345) + PeakWorkingSetSize 118 + VirtualSize 1 Mb + PeakVirtualSize 1 Mb + PageFaultCount 992 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 8 + + THREAD fb667780 Cid 2.1 Teb: 00000000 Win32Thread: 80144900 WAIT: (WrFreePage) KernelMode Non-Alertable + 80144fc0 SynchronizationEvent + Not impersonating + Owning Process fb667a00 + WaitTime (seconds) 32278 + Context Switch Count 787 + UserTime 0:00:00.0000 + KernelTime 0:00:21.0821 + Start Address Phase1Initialization (0x801aab44) + Initial Sp fb26f000 Current Sp fb26ed00 + Priority 0 BasePriority 0 PriorityDecrement 0 DecrementCount 0 + + ChildEBP RetAddr Args to Child + fb26ed18 80118efc c0502000 804044b0 00000000 KiSwapThread+0xb5 + fb26ed3c 801289d9 80144fc0 00000008 00000000 KeWaitForSingleObject+0x1c2 +``` + +Note that the address of the process object can be used as input to other extensions, such as [**!handle**](-handle.md), to obtain further information. + +The following table describes some of the elements in the previous example. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementMeaning
WAITThe parenthetical comment after this heading gives the reason for the wait. The command [dt nt!_KWAIT_REASON](dt--display-type-.md) will display a list of all wait reasons.

ElapsedTime

Lists the amount of time that has elapsed since the process was created. This is displayed in units of Hours:Minutes:Seconds.Milliseconds.

UserTime

Lists the amount of time the process has been running in user mode. If the value for UserTime is exceptionally high, it might identify a process that is depleting system resources. Units are the same as those of ElapsedTime.

KernelTime

Lists the amount of time the process has been running in kernel mode. If the value for KernelTime is exceptionally high, it might identify a process that is depleting system resources. Units are the same as those of ElapsedTime.

Working Set sizes

Lists the current, minimum and maximum working set size for the process, in pages. An exceptionally large working set size can be a sign of a process that is leaking memory or depleting system resources.

QuotaPoolUsage entries

Lists the paged and nonpaged pool used by the process. On a system with a memory leak, looking for excessive nonpaged pool usage on all the processes can tell you which process has the memory leak.

Clone

Indicates whether or not the process was created by the POSIX or Interix subsystems.

Private

Indicates the number of private (non-sharable) pages currently being used by the process. This includes both paged in and paged out memory.

+ +  + +In addition to the process list information, the thread information contains a list of the resources on which the thread has locks. This information is listed in the third line of output after the thread header. In this example, the thread has a lock on one resource, a SynchronizationEvent with an address of 80144fc0. By comparing this address to the list of locks shown by the [**!kdext\*.locks**](-locks---kdext--locks-.md) extension, you can determine which threads have exclusive locks on resources. + +The [**!stacks**](-stacks.md) extension gives a brief summary of the state of every thread. This can be used instead of the !process extension to get a quick overview of the system, especially when debugging multithread issues, such as resource conflicts or deadlocks. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-processfields.md b/windows-driver-docs-pr/debugger/-processfields.md new file mode 100644 index 0000000000..2648110fa7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-processfields.md @@ -0,0 +1,139 @@ +--- +title: processfields +description: The processfields extension displays the names and offsets of the fields within the executive process (EPROCESS) block. +ms.assetid: d1d4c49e-3566-4cf6-8b08-656668c92d6c +keywords: ["processfields Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- processfields +api_type: +- NA +--- + +# !processfields + + +The **!processfields** extension displays the names and offsets of the fields within the executive process (EPROCESS) block. + +``` +!processfields +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable (see the Remarks section)

+ +  + +### Additional Information + +For information about the EPROCESS block, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +This extension command is not available in Windows XP or later versions of Windows. Instead, use the [**dt (Display Type)**](dt--display-type-.md) command to show the EPROCESS structure directly: + +``` +kd> dt nt!_EPROCESS +``` + +Here is an example of **!processfields** from a Windows 2000 system: + +``` +kd> !processfields + EPROCESS structure offsets: + + Pcb: 0x0 + ExitStatus: 0x6c + LockEvent: 0x70 + LockCount: 0x80 + CreateTime: 0x88 + ExitTime: 0x90 + LockOwner: 0x98 + UniqueProcessId: 0x9c + ActiveProcessLinks: 0xa0 + QuotaPeakPoolUsage[0]: 0xa8 + QuotaPoolUsage[0]: 0xb0 + PagefileUsage: 0xb8 + CommitCharge: 0xbc + PeakPagefileUsage: 0xc0 + PeakVirtualSize: 0xc4 + VirtualSize: 0xc8 + Vm: 0xd0 + DebugPort: 0x120 + ExceptionPort: 0x124 + ObjectTable: 0x128 + Token: 0x12c + WorkingSetLock: 0x130 + WorkingSetPage: 0x150 + ProcessOutswapEnabled: 0x154 + ProcessOutswapped: 0x155 + AddressSpaceInitialized: 0x156 + AddressSpaceDeleted: 0x157 + AddressCreationLock: 0x158 + ForkInProgress: 0x17c + VmOperation: 0x180 + VmOperationEvent: 0x184 + PageDirectoryPte: 0x1f0 + LastFaultCount: 0x18c + VadRoot: 0x194 + VadHint: 0x198 + CloneRoot: 0x19c + NumberOfPrivatePages: 0x1a0 + NumberOfLockedPages: 0x1a4 + ForkWasSuccessful: 0x182 + ExitProcessCalled: 0x1aa + CreateProcessReported: 0x1ab + SectionHandle: 0x1ac + Peb: 0x1b0 + SectionBaseAddress: 0x1b4 + QuotaBlock: 0x1b8 + LastThreadExitStatus: 0x1bc + WorkingSetWatch: 0x1c0 + InheritedFromUniqueProcessId: 0x1c8 + GrantedAccess: 0x1cc + DefaultHardErrorProcessing 0x1d0 + LdtInformation: 0x1d4 + VadFreeHint: 0x1d8 + VdmObjects: 0x1dc + DeviceMap: 0x1e0 + ImageFileName[0]: 0x1fc + VmTrimFaultValue: 0x20c + Win32Process: 0x214 + Win32WindowStation: 0x1c4 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!processfields%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-processirps.md b/windows-driver-docs-pr/debugger/-processirps.md new file mode 100644 index 0000000000..633f6e8719 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-processirps.md @@ -0,0 +1,109 @@ +--- +title: processirps +description: The processirps extension displays information about I/O request packets (IRPs) associated with processes. +ms.assetid: B7CC72A5-7D3F-4DE5-878D-ABD08BAF227C +keywords: ["processirps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- processirps +api_type: +- NA +--- + +# !processirps + + +The **!processirps** extension displays information about I/O request packets (IRPs) associated with processes. + +``` +!processirps +!processirps ProcessAddress [Flags] +``` + +## Parameters + + + **** *ProcessAddress* +The address of a process. If you specify *ProcessAddress*, only IRPs associated with that process are displayed. If you do not specify *ProcessAddress*, IRPs for all processes are displayed. + + **** *Flags* +A bitwise OR of one or more of the following flags. + +Bit 0 (0x1) +Display IRPs queued to threads. + +Bit 1 (0x2) +Display IRPs queued to file objects. + +If you specify *Flags*, you must also specify *ProcessAddress*. If you do not specify *Flags*, IRPs queued to both threads and file objects are displayed. + +## + + +### DLL + +kdexts.dll + +Remarks +------- + +This command enables you to quickly identify any queued IRPs for a process, both those that are queued to threads and those that are queued to file objects. IRPs are queued to a file object when the file object has a completion port associated with it. + +Examples +-------- + +You can use [**!process**](-process.md) command to get process addresses. For example, you could get the process address for explorer.exe. + +``` +2: kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +... +PROCESS fffffa800688c940 + SessionId: 1 Cid: 0bbc Peb: 7f70da5e000 ParentCid: 0b84 + DirBase: 2db10000 ObjectTable: fffff8a0025bd440 HandleCount: 1056. + Image: explorer.exe +``` + +Now you can pass the process address for explorer.exe to the **!processirps** command. The following output shows that explorer.exe has IRPs queued to threads and IRPs queued to file objects. + +``` +2: kd> !processirps fffffa800688c940 +**** PROCESS fffffa800688c940 (Image: explorer.exe) **** + +Checking threads for IRPs. + + Thread fffffa800689f080: + + IRP fffffa80045ccc10 - Owned by \FileSystem\Ntfs for device fffffa8004f5c030 + IRP fffffa800454f650 - Owned by \FileSystem\Ntfs for device fffffa8004f5c030 + ... + IRP fffffa80068e9c10 - Owned by \FileSystem\Ntfs for device fffffa8004f5c030 + +Checking file objects for IRPs. + + FileObject fffffa80068795e0 (handle 8bc): + + IRP fffffa8006590cf0 - Owned by \Driver\DeviceApi for device DeviceApi (fffffa800363ae40) + + ... + + FileObject fffffa8005bf59c0 (handle 900): + + IRP fffffa8006659010 - Owned by \Driver\DeviceApi for device DeviceApi (fffffa800363ae40) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!processirps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-prompt-allow--control-prompt-display-.md b/windows-driver-docs-pr/debugger/-prompt-allow--control-prompt-display-.md new file mode 100644 index 0000000000..6b752ea57d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-prompt-allow--control-prompt-display-.md @@ -0,0 +1,118 @@ +--- +title: .prompt_allow (Control Prompt Display) +description: The .prompt_allow command controls what information is displayed during stepping and tracing and whenever the target's execution stops. +ms.assetid: 916114f9-0a68-4423-ba28-a5f0da8a1af9 +keywords: [".prompt_allow (Control Prompt Display) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .prompt_allow (Control Prompt Display) +api_type: +- NA +--- + +# .prompt\_allow (Control Prompt Display) + + +The **.prompt\_allow** command controls what information is displayed during stepping and tracing and whenever the target's execution stops. + +``` +.prompt_allow {+|-}Item [...] +.prompt_allow +``` + +## Parameters + + + **+** +Displays the specified item at the stepping, tracing, and execution prompt. You must add a space before the plus sign (+), but you cannot add a space after it. + + **-** +Prevents the specified item from being displayed at the stepping, tracing, and execution prompt. You must add a space before the minus sign (-), but you cannot add a space after it. + + *Item* +Specifies an item to display or not display. You can specify any number of items. Separate multiple items by spaces. You must add a plus sign (+) or minus sign (-) before each item. You can use the following items: + +**dis** +The disassembled instructions at the current location. + +**ea** +The effective address for the current instruction. + +**reg** +The current state of the most important registers. You can disable register display by using the [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg command. All three of these commands control the same setting, and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands, as described in the following Remarks section. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + +**src** +The source line that corresponds to the current instruction. You can disable source line display by using the l-ls or .prompt\_allow -src; commands. You must enable source line display through both mechanisms to be visible. + +**sym** +The symbol for the current instruction. This symbol includes the current module, function name, and offset. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about commands that affect execution, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +You can use the **.prompt\_allow** command without parameters to show which items are displayed and are not displayed. Every time that you run **.prompt\_allow**, the debugger changes the status of only the specified items. + +By default, all items are displayed. + +If you have used the l+os option, this option overrides any of the **.prompt\_allow** options other than **src**. + +You can also use a complex command such as the following example. + +``` +0:000> .prompt_allow -reg -dis +ea +Allow the following information to be displayed at the prompt: +(Other settings can affect whether the information is actually displayed) + sym - Symbol for current instruction + ea - Effective address for current instruction + src - Source info for current instruction +Do not allow the following information to be displayed at the prompt: + dis - Disassembly of current instruction + reg - Register state +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.prompt_allow%20%28Control%20Prompt%20Display%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-psp.md b/windows-driver-docs-pr/debugger/-psp.md new file mode 100644 index 0000000000..86b43b6f9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-psp.md @@ -0,0 +1,81 @@ +--- +title: psp +description: The psp extension displays the processor state parameter (PSP) register at the specified address. +ms.assetid: 5ed36051-31e0-405f-ac30-88d888f9d915 +keywords: ["processor state parameter (PSP)", "PSP register", "psp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- psp +api_type: +- NA +--- + +# !psp + + +The **!psp** extension displays the processor state parameter (PSP) register at the specified address. + +This extension is supported only on Itanium-based target computers. + +``` +!psp Address [DisplayLevel] +``` + +**Important**  This command has been deprecated in the Windows Debugger Version 10.0.14257 and later, and is no longer available. + +  + +## Parameters + + + *Address* +Specifies the hexadecimal address of the PSP register to display. + + *DisplayLevel* +Can be any one of the following options: + +**0** +Displays only the values of each PSP field. This is the default. + +**1** +Displays more in-depth information on each of the PSP fields that is not reserved or ignored. + +**2** +Displays more in-depth information on all of the PSP fields, including those that are ignored or reserved. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!psp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pte.md b/windows-driver-docs-pr/debugger/-pte.md new file mode 100644 index 0000000000..5e4cc84fb0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pte.md @@ -0,0 +1,235 @@ +--- +title: pte +description: The pte extension displays the page table entry (PTE) and page directory entry (PDE) for the specified address. +ms.assetid: e5603e58-8d9f-4693-bca2-a319080187cc +keywords: ["page table entry (PTE)", "PTE (page table entry)", "page directory entry (PDE)", "PDE (page directory entry)", "pte Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pte +api_type: +- NA +--- + +# !pte + + +The **!pte** extension displays the page table entry (PTE) and page directory entry (PDE) for the specified address. + +Syntax + +``` +!pte VirtualAddress +!pte PTE +!pte LiteralAddress 1 +``` + +## Parameters + + + *VirtualAddress* +Specifies the virtual address whose page table is desired. + + *PTE* +Specifies the address of an actual PTE. + + *LiteralAddress* **** **1** +Specifies the address of an actual PTE or PDE. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about page tables, page directories, and an explanation of the status bits, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +If one parameter is supplied and this parameter is an address in the region of memory where the page tables are stored, the debugger treats this as the *PTE* parameter. This parameter is taken as the actual address of the desired PTE, and the debugger will display this PTE and the corresponding PDE. + +If one parameter is supplied and this parameter is not an address in this region, the debugger treats this as the *VirtualAddress* parameter. The PTE and PDE that hold the mapping for this address are displayed. + +If two parameters are supplied and the second parameter is **1** (or any other small number), the debugger treats the first parameter as *LiteralAddress*. This address is interpreted as the actual address of a PTE and also as the actual address of a PDE, and the corresponding (and possibly invalid) data will be shown. + +(x86 or x64 target computer only) If two parameters are supplied and the second parameter is greater than the first, the debugger treats the two parameters as *StartAddress* and *EndAddress*. The command then displays the PTEs for each page in the specified memory range. + +For a list of all system PTEs, use the [**!sysptes**](-sysptes.md) extension. + +Here is an example from an x86 target computer: + +``` +kd> !pte 801544f4 +801544F4 - PDE at C0300800 PTE at C0200550 + contains 0003B163 contains 00154121 + pfn 3b G-DA--KWV pfn 154 G--A--KRV +``` + +The first line of this example restates the virtual address being investigated. It then gives the virtual address of the PDE and the PTE, which contain information about the virtual-physical mapping of this address. + +The second line gives the actual contents of the PDE and the PTE. + +The third line takes these contents and analyzes them, breaking them into the page frame number (PFN) and the status bits. + +See the [**!pfn**](-pfn.md) extension or the [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md) section for information about how to interpret and use the PFN. + +On an x86 or x64 target computer, the status bits for the PDE and the PTE are shown in the following table. The **!pte** display indicates these bits with capital letters or dashes, and adds additional information as well. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitDisplay when setDisplay when clearMeaning

0x200

C

-

Copy on write.

0x100

G

-

Global.

0x80

L

-

Large page. This only occurs in PDEs, never in PTEs.

0x40

D

-

Dirty.

0x20

A

-

Accessed.

0x10

N

-

Cache disabled.

0x8

T

-

Write-through.

0x4

U

K

Owner (user mode or kernel mode).

0x2

W

R

Writeable or read-only. Only on multiprocessor computers and any computer running Windows Vista or later.

0x1

V

Valid.

E

-

Executable page. For platforms that do not support a hardware execute/noexecute bit, including many x86 systems, the E is always displayed.

+ +  + +On an Itanium target computer, the status bits for the PDE and the PTE are slightly different from those of the PPE. The Itanium PPE bits are as follows: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Display when setDisplay when clearMeaning

V

Valid.

U

K

Owner (user mode or kernel mode).

D

-

Dirty.

A

-

Accessed.

W

R

Writeable or read-only. Only on multiprocessor computers and any computer running Windows Vista or later.

E

-

Execute.

C

-

Copy on write.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pte%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-pte2va.md b/windows-driver-docs-pr/debugger/-pte2va.md new file mode 100644 index 0000000000..f3681ffc24 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-pte2va.md @@ -0,0 +1,79 @@ +--- +title: pte2va +description: The pte2va extension displays the virtual address that corresponds to the specified page table entry (PTE). +ms.assetid: 9a94ce3a-dbbc-4566-9ef5-3ec76c1505eb +keywords: ["pte2va Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pte2va +api_type: +- NA +--- + +# !pte2va + + +The **!pte2va** extension displays the virtual address that corresponds to the specified page table entry (PTE). + +``` +!pte2va Address +``` + +## Parameters + + + *Address* +Specifies the PTE. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about page tables and PTEs, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +To examine the contents of a specific PTE, use the [**!pte**](-pte.md) extension. + +Here is an example of the output from the **!pte2va** extension: + +``` +kd> !pte2va 9230 +000800000248c000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!pte2va%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ptov.md b/windows-driver-docs-pr/debugger/-ptov.md new file mode 100644 index 0000000000..e9b29468f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ptov.md @@ -0,0 +1,130 @@ +--- +title: ptov +description: The ptov extension displays the entire physical-to-virtual map for a given process. +ms.assetid: 82352d12-4e81-4746-9333-b2cc98eb7a9d +keywords: ["ptov Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ptov +api_type: +- NA +--- + +# !ptov + + +The **!ptov** extension displays the entire physical-to-virtual map for a given process. + +``` +!ptov DirBase +``` + +## Parameters + + + *DirBase* +Specifies the directory base for the process. To determine the directory base, use the [**!process**](-process.md) command, and look at the value displayed for DirBase. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example. First, use [**.process**](-process--set-process-context-.md) and [**!process**](-process.md) to determine the directory base of the current process: + +``` +1: kd> .process +Implicit process is now 852b4040 +1: kd> !process 852b4040 1 +PROCESS 852b4040 SessionId: none Cid: 0004 Peb: 00000000 ParentCid: 0000 + DirBase: 00185000 ObjectTable: 83203000 HandleCount: 663. + Image: System + ... +``` + +In this case, the directory base is 0x00185000. Pass this address to **!ptov**: + +``` +1: kd> !ptov 185000 +X86PtoV: pagedir 185000, PAE enabled. +15e11000 10000 +549e6000 20000 +... +60a000 210000 +40b000 211000 +... +54ad3000 25f000 +548d3000 260000 +... +d71000 77510000 +... +``` + +The numbers in the left column are the physical addresses of each memory page that has a mapping for this process. The numbers in the right column are the virtual addresses to which they are mapped. + +The total display is very long. + +Here is a 64-bit example. + +``` +3: kd> .process +Implicit process is now fffffa80`0361eb30 +3: kd> !process fffffa80`0361eb30 1 +PROCESS fffffa800361eb30 + SessionId: none Cid: 0004 Peb: 00000000 ParentCid: 0000 + DirBase: 00187000 ObjectTable: fffff8a000002870 HandleCount: 919. + Image: System + ... +3: kd> !ptov 187000 +Amd64PtoV: pagedir 187000 +00000001`034fb000 1d0000 +a757c000 1d1000 +00000001`0103d000 1d2000 +c041e000 1d3000 +... +2ed6f000 fffff680`00001000 +00000001`13939000 fffff680`00003000 +ceefb000 fffff680`00008000 +... +``` + +The directory base is the physical address of the first table that is used in virtual address translation. This table has different names depending on the bitness of the target operating system and whether Physical Address Extension (PAE) is enabled for the target operating system. + +For 64-bit Windows, the directory base is the physical address of the Page Map Level 4 (PML4) table. For 32-bit Windows with PAE enabled, the directory base is the physical address of the Page Directory Pointers (PDP) table. For 32-bit Windows with PAE disabled, the directory bas is the physical address of the Page Directory (PD) table. + +For related topics, see [**!vtop**](-vtop.md) and [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md). For information about virtual address translation, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ptov%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-push--save-debugger-state-.md b/windows-driver-docs-pr/debugger/-push--save-debugger-state-.md new file mode 100644 index 0000000000..2314e5f298 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-push--save-debugger-state-.md @@ -0,0 +1,78 @@ +--- +title: .push (Save Debugger State) +description: The .push command saves the current state of the debugger. +ms.assetid: 2e0b45d6-35b8-4c86-9c54-df8d16b4dcc2 +keywords: [".push (Save Debugger State) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .push (Save Debugger State) +api_type: +- NA +--- + +# .push (Save Debugger State) + + +The **.push** command saves the current state of the debugger. + +``` +.push +.push /r +.push /r /q + +``` + +## Parameters + + + **/r** +Specifies that the current values in the pseudo-registers **$t0** to **$t19** should be saved. If the **/r** parameter is not used, these values are not saved by the **.push** command. + + **/q** +Specifies that the command executes quietly. That is, the command executes without displaying any output. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +This command is most useful when used with [scripts](using-script-files.md) and [debugger command programs](using-debugger-command-programs.md) so that they can work with one fixed state. To restore the debugger to a state that was previously saved using this command, use the [**.pop (Restore Debugger State)**](-pop--restore-debugger-state-.md) command. If the command is successful, no output is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.push%20%28Save%20Debugger%20State%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-qlocks.md b/windows-driver-docs-pr/debugger/-qlocks.md new file mode 100644 index 0000000000..7e9cbc026f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-qlocks.md @@ -0,0 +1,96 @@ +--- +title: qlocks +description: The qlocks extension displays the state of all queued spin locks. +ms.assetid: fdeefedb-c840-410a-94e4-ae42923e82e7 +keywords: ["qlocks Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- qlocks +api_type: +- NA +--- + +# !qlocks + + +The **!qlocks** extension displays the state of all queued spin locks. + +``` +!qlocks +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about spin locks, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +This command is useful only on a multiprocessor system. + +Here is an example: + +``` +0: kd> !qlocks +Key: O = Owner, 1-n = Wait order, blank = not owned/waiting, C = Corrupt + + Processor Number + Lock Name 0 1 2 3 + +KE - Dispatcher +KE - Unused Spare +MM - PFN +MM - System Space +CC - Vacb +CC - Master +EX - NonPagedPool +IO - Cancel +EX - WorkQueue +IO - Vpb +IO - Database +IO - Completion +NTFS - Struct +AFD - WorkQueue +CC - Bcb +MM - MM NonPagedPool +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!qlocks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-quit-lock--prevent-accidental-quit-.md b/windows-driver-docs-pr/debugger/-quit-lock--prevent-accidental-quit-.md new file mode 100644 index 0000000000..f0a6afada5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-quit-lock--prevent-accidental-quit-.md @@ -0,0 +1,87 @@ +--- +title: .quit_lock (Prevent Accidental Quit) +description: The .quit_lock command sets a password to prevent you from accidentally ending the debugging session. +ms.assetid: fd40e642-beba-4da0-a072-6493588980de +keywords: [".quit_lock (Prevent Accidental Quit) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .quit_lock (Prevent Accidental Quit) +api_type: +- NA +--- + +# .quit\_lock (Prevent Accidental Quit) + + +The **.quit\_lock** command sets a password to prevent you from accidentally ending the debugging session. + +``` +.quit_lock /s NewPassword +.quit_lock /q Password +.quit_lock +``` + +## Parameters + + + **/s** **** *NewPassword* +Prevents the debugging session from ending and stores *NewPassword*. You cannot end the debugger session until you use the **.quit\_lock /q** command together with this same password. *NewPassword* can be any string. If it contains spaces, you must enclose *NewPassword* in quotation marks. + + **/q** **** *Password* +Enables the debugging session to end. *Password* must match the password that you set with the **.quit\_lock /s** command. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +Without parameters, **.quit\_lock** displays the current lock status, including the full text of the password. + +You can repeat the **.quit\_lock /s** command to change an existing password. + +When you use **.quit\_lock /q**, the lock is removed. This command does not close the debugger. Instead, the command only enables you to exit the session in the typical manner when you want to. + +**Note**   The password is not "secret". Any remote user who is attached to the debugging session can use **.quit\_lock** to determine the password. The purpose of this command is to prevent accidental use of the [**q (Quit)**](q--qq--quit-.md) command. This command is especially useful if restarting the debugging session might be difficult (for example, during remote debugging). + +  + +You cannot use the **.quit\_lock /s** command in [Secure Mode](activating-secure-mode.md). If you use this command before Secure Mode is activated, the password protection remains, but you cannot change or remove the password. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.quit_lock%20%28Prevent%20Accidental%20Quit%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrcrashdump.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrcrashdump.md new file mode 100644 index 0000000000..60b841a9f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrcrashdump.md @@ -0,0 +1,57 @@ +--- +title: rcdrkd.rcdrcrashdump +description: The rcdrkd.rcdrcrashdump extension is used with a minidump file to display the recorder log (if the log is present in the minidump). +ms.assetid: 61DB0462-31F1-4756-87BB-60188887ACAF +keywords: ["rcdrkd.rcdrcrashdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrcrashdump +api_type: +- NA +--- + +# !rcdrkd.rcdrcrashdump + + +The [**!rcdrkd.rcdrcrashdump**](-usb3kd-device-info.md) extension is used with a minidump file to display the recorder log (if the log is present in the minidump). + +``` +!rcdrkd.rcdrcrashdump TraceProviderGuid +!rcdrkd.rcdrcrashdump DriverName +``` + +## Parameters + + + *TraceProviderGuid* +GUID of the trace provider. This parameter must include braces: {*guid*} + + *DriverName* +The name of the driver. The driver name can be used instead of the trace provider GUID for drivers that use the Inflight Trace Recorder (IFR). + +## DLL + + +Rcdrkd.dll + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrcrashdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrhelp.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrhelp.md new file mode 100644 index 0000000000..025e0f35b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrhelp.md @@ -0,0 +1,43 @@ +--- +title: rcdrkd.rcdrhelp +description: The rcdrkd.rcdrhelp command displays help for the RCDRKD debugger extension commands. +ms.assetid: E4BCAFB5-BC4F-4C7D-B011-67F86E1C9E99 +keywords: ["rcdrkd.rcdrhelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrhelp +api_type: +- NA +--- + +# !rcdrkd.rcdrhelp + + +The **!rcdrkd.rcdrhelp** command displays help for the RCDRKD debugger extension commands. + +## DLL + + +Rcdrkd.dll + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrhelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogdump.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogdump.md new file mode 100644 index 0000000000..0389a337ea --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogdump.md @@ -0,0 +1,118 @@ +--- +title: rcdrkd.rcdrlogdump +description: The rcdrkd.rcdrlogdump extension displays the trace messages from all recorder buffers of a driver or set of drivers. +ms.assetid: 18A25B5A-F22E-4A01-A130-885D5CA34D4D +keywords: ["rcdrkd.rcdrlogdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrlogdump +api_type: +- NA +--- + +# !rcdrkd.rcdrlogdump + + +The **!rcdrkd.rcdrlogdump** extension displays the trace messages from all recorder buffers of a driver or set of drivers. + +``` +!rcdrkd.rcdrlogdump DriverName [DriverName ...] +!rcdrkd.rcdrlogdump DriverName -a Address +``` + +## Parameters + + + *DriverName* +The name of a driver, not including the .sys extension. + + *Address* +If Address is specified, this command displays the trace messages from the log buffer at the specified address. + +## DLL + + +Rcdrkd.dll + +Examples +-------- + +The following example shows a portion of the output of the **!rcdrlogdump**command. + +``` +3: kd> !rcdrlogdump usbxhci.sys +Trace searchpath is: + +Trace format prefix is: %7!u!: %!FUNC! - +Log dump command Log ID Size +================ ====== ==== +!rcdrlogdump usbxhci -a fffffa8005ff2b60 03 SLT02 DCI04 1024 +!rcdrlogdump usbxhci -a fffffa8005ff2010 03 SLT02 DCI03 1024 +!rcdrlogdump usbxhci -a fffffa8005b36010 03 SLT01 DCI03 1024 +!rcdrlogdump usbxhci -a fffffa8005b379e0 03 SLT01 DCI04 1024 +!rcdrlogdump usbxhci -a fffffa8005b33350 03 SLT02 DCI01 1024 +!rcdrlogdump usbxhci -a fffffa8005b2bb60 03 SLT01 DCI01 1024 +!rcdrlogdump usbxhci -a fffffa8005a2bb60 03 CMD 1024 +!rcdrlogdump usbxhci -a fffffa8005a1ab60 03 INT00 1024 +!rcdrlogdump usbxhci -a fffffa8005085330 03 RUNDOWN 512 +!rcdrlogdump usbxhci -a fffffa8005311780 03 1033 0194 1024 +Trying to extract TMF information from - C:\ProgramData\dbg\sym\usbxhci.pdb\D4C85D5D3E2843879EDE226A334D69552\usbxhci.pdb +--- start of log --- +03 RUNDOWN 6: Controller_RetrievePciData - PCI Bus.Device.Function: 48.0.0 +03 RUNDOWN 7: Controller_RetrievePciData - PCI: VendorId 0x1033 DeviceId 0x0194 RevisionId 0x03 +03 RUNDOWN 8: Controller_QueryDeviceFlagsFromKse - Found DeviceFlags 0x101800 for USBXHCI:PCI\VEN_1033&DEV_0194 +03 RUNDOWN 9: Controller_RetrieveDeviceFlags - DeviceFlags 0x101804 +... +03 SLT01 DCI03 89911: TransferRing_DispatchEventsAndReleaseLock - 1.3.0: Mapping Complete : Path 1 TransferRingState_Idle Events 0x00000000 +03 SLT01 DCI04 89912: TransferRing_DispatchEventsAndReleaseLock - 1.4.0: Mapping Begin : Path 3 TransferRingState_Mapping Events 0x00000000 +03 SLT01 DCI04 89913: TransferRing_DispatchEventsAndReleaseLock - 1.4.0: Mapping Complete : Path 3 TransferRingState_Idle Events 0x00000000 +---- end of log ---- +``` + +The preceding output contains messages from several log buffers. To see mesages from a single log buffer, use the **-a** parameter, and specify the address of the log buffer. The following example shows how to display the messages from the log buffer at address fffffa8005ff2b60. + +``` +3: kd> !rcdrlogdump usbxhci -a fffffa8005ff2b60 +Trace searchpath is: + +Trace format prefix is: %7!u!: %!FUNC! - +Trying to extract TMF information from - C:\ProgramData\dbg\sym\usbxhci.pdb\D4C85D5D3E2843879EDE226A334D69552\usbxhci.pdb +--- start of log --- +70914: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Complete : Path 1 TransferRingState_Idle Events 0x00000000 +70916: TransferRing_TransferEventHandler - 2.4.0: TransferEventTrb 0xFFFFFA8005A3FBF0 CC_SUCCESS Length 31 EventData 1 Pointer 0xfffffa8005b96210 +70917: TransferRing_TransferEventHandler - 2.4.0: WdfRequest 0x0000057FFA469FD8 transferData 0xFFFFFA8005B961B0 +70918: TransferRing_TransferComplete - 2.4.0: WdfRequest 0x0000057FFA469FD8 completed with STATUS_SUCCESS BytesProcessed 31 +70922: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Begin : Path 3 TransferRingState_Mapping Events 0x00000000 +70923: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Complete : Path 3 TransferRingState_Idle Events 0x00000000 +81064: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Begin : Path 1 TransferRingState_Mapping Events 0x00000000 +81065: TransferRing_StageRetrieveFromRequest - 2.4.0: WdfRequest 0x0000057FFA469FD8 TransferData 0xFFFFFA8005B961B0 Function 0x9 Length 31 TransferSize 31 BytesProcessed 0 +81066: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Complete : Path 1 TransferRingState_Idle Events 0x00000000 +81068: TransferRing_TransferEventHandler - 2.4.0: TransferEventTrb 0xFFFFFA8005A40270 CC_SUCCESS Length 31 EventData 1 Pointer 0xfffffa8005b96210 +81069: TransferRing_TransferEventHandler - 2.4.0: WdfRequest 0x0000057FFA469FD8 transferData 0xFFFFFA8005B961B0 +81070: TransferRing_TransferComplete - 2.4.0: WdfRequest 0x0000057FFA469FD8 completed with STATUS_SUCCESS BytesProcessed 31 +81074: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Begin : Path 3 TransferRingState_Mapping Events 0x00000000 +81075: TransferRing_DispatchEventsAndReleaseLock - 2.4.0: Mapping Complete : Path 3 TransferRingState_Idle Events 0x00000000 +---- end of log ---- +``` + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrlogdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrloglist.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrloglist.md new file mode 100644 index 0000000000..540c5ec46e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrloglist.md @@ -0,0 +1,79 @@ +--- +title: rcdrkd.rcdrloglist +description: The rcdrkd.rcdrloglist extension displays a list of the recorder logs owned by a driver or a set of drivers. +ms.assetid: D4D3C313-EFD4-482B-B4A3-307F2407D2BA +keywords: ["rcdrkd.rcdrloglist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrloglist +api_type: +- NA +--- + +# !rcdrkd.rcdrloglist + + +The **!rcdrkd.rcdrloglist** extension displays a list of the recorder logs owned by a driver or a set of drivers. + +``` +!rcdrkd.rcdrloglist DriverName [DriverName ...] +``` + +## Parameters + + + *DriverName* +The name of a driver, not including the .sys extension. + +## DLL + + +Rcdrkd.dll + +Remarks +------- + +This command is relevant only for drivers that log messages to different logs by using the WppRecorder API. + +Examples +-------- + +The following example displays a list of all recorder logs owned by the USB 3.0 host controller driver (usbxhci.sys). + +``` +3: kd> !rcdrloglist usbxhci +Log dump command Log ID Size +================ ====== ==== +!rcdrlogdump usbxhci -a fffffa8005ff2b60 03 SLT02 DCI04 1024 +!rcdrlogdump usbxhci -a fffffa8005ff2010 03 SLT02 DCI03 1024 +!rcdrlogdump usbxhci -a fffffa8005b36010 03 SLT01 DCI03 1024 +!rcdrlogdump usbxhci -a fffffa8005b379e0 03 SLT01 DCI04 1024 +!rcdrlogdump usbxhci -a fffffa8005b33350 03 SLT02 DCI01 1024 +!rcdrlogdump usbxhci -a fffffa8005b2bb60 03 SLT01 DCI01 1024 +!rcdrlogdump usbxhci -a fffffa8005a2bb60 03 CMD 1024 +!rcdrlogdump usbxhci -a fffffa8005a1ab60 03 INT00 1024 +!rcdrlogdump usbxhci -a fffffa8005085330 03 RUNDOWN 512 +!rcdrlogdump usbxhci -a fffffa8005311780 03 1033 0194 1024 +``` + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrloglist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogsave.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogsave.md new file mode 100644 index 0000000000..e63ef317a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrlogsave.md @@ -0,0 +1,56 @@ +--- +title: rcdrkd.rcdrlogsave +description: The rcdrkd.rcdrlogsave extension saves the recorder buffers of a driver. +ms.assetid: 2A79064C-A899-4351-A8A6-D8DF31CF9A17 +keywords: ["rcdrkd.rcdrlogsave Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrlogsave +api_type: +- NA +--- + +# !rcdrkd.rcdrlogsave + + +The **!rcdrkd.rcdrlogsave** extension saves the recorder buffers of a driver. + +``` +!rcdrkd.rcdrlogsave DriverName [CaptureFilename ] +``` + +## Parameters + + + *DriverName* +The name of the driver, not including the .sys extension. + + *CaptureFileName* +The name of the file (not including the .etl extension) in which to save the recorder buffers. If *CaptureFileName* is not specified, the recorder buffers are saved in *DriverName*.etl. + +## DLL + + +Rcdrkd.dll + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrlogsave%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsearchpath.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsearchpath.md new file mode 100644 index 0000000000..eb363f1f96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsearchpath.md @@ -0,0 +1,58 @@ +--- +title: rcdrkd.rcdrsearchpath +description: The rcdrkd.rcdrsearchpath extension sets the search path for trace message format (TMF) and trace message control (TMC) files. +ms.assetid: AB19DC1B-009E-445A-B66B-5CC7EF54086F +keywords: ["rcdrkd.rcdrsearchpath Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrsearchpath +api_type: +- NA +--- + +# !rcdrkd.rcdrsearchpath + + +The **!rcdrkd.rcdrsearchpath** extension sets the search path for trace message format (TMF) and trace message control (TMC) files. + +``` +!rcdrkd.rcdrsearchpath FilePath +``` + +## Parameters + + + *FilePath* +Path to the format files. + +## DLL + + +Rcdrkd.dll + +Remarks +------- + +The search path set by this command takes precedence over the search path specified in the TRACE\_FORMAT\_SEARCH\_PATH environment variable. + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrsearchpath%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsettraceprefix.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsettraceprefix.md new file mode 100644 index 0000000000..6bd7240ecc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrsettraceprefix.md @@ -0,0 +1,89 @@ +--- +title: rcdrkd.rcdrsettraceprefix +description: The rcdrkd.rcdrsettraceprefix extension sets the trace message prefix. +ms.assetid: BFA987B8-7013-4112-A674-064ED59741C0 +keywords: ["rcdrkd.rcdrsettraceprefix Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrsettraceprefix +api_type: +- NA +--- + +# !rcdrkd.rcdrsettraceprefix + + +The **!rcdrkd.rcdrsettraceprefix** extension sets the trace message prefix. + +``` +!rcdrkd.rcdrsettraceprefix TracePrefixString +``` + +## Parameters + + + *TracePrefixString* +The trace message prefix string. + +## DLL + + +Rcdrkd.dll + +Remarks +------- + +Each message in a recorder log has a prefix that you can control by specifying a trace message prefix string. For more information, see [Trace Message Prefix](https://msdn.microsoft.com/library/windows/hardware/ff553941). + +Examples +-------- + +In the following example, the trace message prefix is originally **%7!u!: %!FUNC! -** . The parameter **%7!u!** specifies that the prefix includes the message sequence number. The parameter **%!FUNC!** specifies that the prefix includes the name of the function that generated the message. The example calls **!rcdrsettraceprefix** to change the prefix string to **%7!u!**. After that, the log display includes message sequence numbers, but does not include function names. + +``` +0: kd> !rcdrlogdump USBXHCI -a 0xfffffa8010737b60 +Trace searchpath is: + +Trace format prefix is: %7!u!: %!FUNC! - +Trying to extract TMF information from - C:\ProgramData\dbg\sym\usbxhci.pdb\D4C85D5D3E2843879EDE226A334D69552\usbxhci.pdb +--- start of log --- +405: TransferRing_DispatchEventsAndReleaseLock - 1.8.1: Mapping Begin : Path 1 TransferRingState_Mapping Events 0x00000000 +406: TransferRing_StageRetrieveFromRequest - 1.8.1: WdfRequest 0x0000057FEE117A88 TransferData 0xFFFFFA8011EE8700 Function 0x9 Length 500 TransferSize 500 BytesProcessed 0 +... +---- end of log ---- + +0: kd> !rcdrsettraceprefix %7!u!: +SetTracePrefix: "%7!u!: " +0: kd> !rcdrlogdump USBXHCI -a 0xfffffa8010737b60 +Trace searchpath is: + +Trace format prefix is: %7!u!: +Trying to extract TMF information from - C:\ProgramData\dbg\sym\usbxhci.pdb\D4C85D5D3E2843879EDE226A334D69552\usbxhci.pdb +--- start of log --- +405: 1.8.1: Mapping Begin : Path 1 TransferRingState_Mapping Events 0x00000000 +406: 1.8.1: WdfRequest 0x0000057FEE117A88 TransferData 0xFFFFFA8011EE8700 Function 0x9 Length 500 TransferSize 500 BytesProcessed 0 +... +---- end of log ---- +``` + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrsettraceprefix%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtmffile.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtmffile.md new file mode 100644 index 0000000000..6d2eca1697 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtmffile.md @@ -0,0 +1,53 @@ +--- +title: rcdrkd.rcdrtmffile +description: The rcdrkd.rcdrtmffile extension sets or clears the name of the trace message format (TMF) file. +ms.assetid: EAA1238F-8D65-4115-9B4F-22AA6A5C3B3B +keywords: ["rcdrkd.rcdrtmffile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrtmffile +api_type: +- NA +--- + +# !rcdrkd.rcdrtmffile + + +The **!rcdrkd.rcdrtmffile** extension sets or clears the name of the trace message format (TMF) file. + +``` +!rcdrkd.rcdrtmffile [Filename] +``` + +## Parameters + + + *Filename* +The name of the TMF file. If this parameter is not specified, the filename is cleared. + +## DLL + + +Rcdrkd.dll + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrtmffile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtraceprtdebug.md b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtraceprtdebug.md new file mode 100644 index 0000000000..3af0653def --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rcdrkd-rcdrtraceprtdebug.md @@ -0,0 +1,56 @@ +--- +title: rcdrkd.rcdrtraceprtdebug +description: The rcdrkd.rcdrtraceprtdebug extension turns TracePrt diagnostic mode on or off. This extension should be used under the direction of support. +ms.assetid: FD0720D6-A20D-4ECD-813E-C3AF85C98928 +keywords: ["rcdrkd.rcdrtraceprtdebug Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rcdrkd.rcdrtraceprtdebug +api_type: +- NA +--- + +# !rcdrkd.rcdrtraceprtdebug + + +The **!rcdrkd.rcdrtraceprtdebug** extension turns TracePrt diagnostic mode on or off. This extension should be used under the direction of support. + +``` +!rcdrkd.rcdrtraceprtdebug {on|off} +``` + +## Parameters + + + **on** +Turns TracePrt diagnostic mode on. + + **off** +Turns TracePrt diagnostic mode off. + +## DLL + + +Rcdrkd.dll + +## See also + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rcdrkd.rcdrtraceprtdebug%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-readmem--read-memory-from-file-.md b/windows-driver-docs-pr/debugger/-readmem--read-memory-from-file-.md new file mode 100644 index 0000000000..a1def85cd5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-readmem--read-memory-from-file-.md @@ -0,0 +1,77 @@ +--- +title: .readmem (Read Memory from File) +description: The .readmem command reads raw binary data from the specified file and copies the data to the target computer's memory. +ms.assetid: 128cbea1-5fb5-4685-8587-f814f94cc658 +keywords: [".readmem (Read Memory from File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .readmem (Read Memory from File) +api_type: +- NA +--- + +# .readmem (Read Memory from File) + + +The **.readmem** command reads raw binary data from the specified file and copies the data to the target computer's memory. + +``` +.readmem FileName Range +``` + +## Parameters + + + *FileName* +Specifies the name of the file to read. You can specify a full path or only the file name. If the file name contains spaces, enclose *FileName* in quotation marks. If you do not specify a path, the debugger uses the current directory. + + *Range* +Specifies the address range for putting the data in memory. This parameter can contain a starting and ending address or a starting address and an object count. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The memory data is copied literally to the target computer. The debugger does not parse the data in any way. For example, the **.readmem myfile 1000 10** command copies 10 bytes from the Myfile file and stores them in the target computer's memory, starting at address 1000. + +The **.readmem** command is the opposite of the [**.writemem (Write Memory to File)**](-writemem--write-memory-to-file-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.readmem%20%28Read%20Memory%20from%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ready.md b/windows-driver-docs-pr/debugger/-ready.md new file mode 100644 index 0000000000..38dbdd5832 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ready.md @@ -0,0 +1,84 @@ +--- +title: ready +description: The ready extension displays summary information about each thread in the system in a READY state. +ms.assetid: 1dc94ceb-7d06-4874-999c-059c86f51ea0 +keywords: ["thread, ready threads", "ready Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ready +api_type: +- NA +--- + +# !ready + + +The **!ready** extension displays summary information about each thread in the system in a READY state. + +``` +!ready [Flags] +``` + +## Parameters + + + *Flags* +Specifies the level of detail to display. *Flags* can be any combination of the following bits. If *Flags* is 0, only a minimal amount of information is displayed. The default is 0x6. + +Bit 1 (0x2) +Causes the display to include the thread's wait states. + +Bit 2 (0x4) +If this is included without Bit 1 (0x2), this has no effect. If this is included along with Bit 1, the thread is displayed with a stack trace. + +Bit 3 (0x8) +(Windows XP and later) Causes the display of each function to include the return address, the stack pointer, and (on Itanium systems) the **bsp** register value. The display of function arguments is suppressed. + +Bit 4 (0x10) +(Windows XP and later) Causes the display of each function to include only the return address; arguments and stack pointers are suppressed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about thread scheduling and the READY state, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The output from this extension is similar to that of [**!thread**](-thread.md), except that only ready threads are displayed, and they are sorted in order of decreasing priority. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ready%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rebase.md b/windows-driver-docs-pr/debugger/-rebase.md new file mode 100644 index 0000000000..5d99e157e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rebase.md @@ -0,0 +1,81 @@ +--- +title: rebase +description: The rebase extension searches in a rebase.log file for a specified address or symbol. +ms.assetid: 811e7ab8-301f-433a-bfc4-8a4e5f002b30 +keywords: ["rebase Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rebase +api_type: +- NA +--- + +# !rebase + + +The **!rebase** extension searches in a rebase.log file for a specified address or symbol. + +``` +!rebase [-r] Address [Path] +!rebase Symbol [Path] +!rebase -stack [Path] +!rebase -? +``` + +## Parameters + + + **-r** +Attempts to load any module found in rebase.log. + + *Address* +Specifies an address in standard hexadecimal format. The extension will search for DLLs near this address. + + *Path* +Specifies the file path to the rebase.log. If *Path* is not specified, then the extension tries to guess the path to the rebase.log or, failing that, tries to read a rebase.log file from the current working directory. + + *Symbol* +Specifies the symbol or image name. The extension will search for DLLs that contain this substring. + + **-stack** +Displays all modules in the current stack. + + **-?** +Displays a brief help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Ext.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rebase%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-reboot--reboot-target-computer-.md b/windows-driver-docs-pr/debugger/-reboot--reboot-target-computer-.md new file mode 100644 index 0000000000..1dc030b7fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-reboot--reboot-target-computer-.md @@ -0,0 +1,68 @@ +--- +title: .reboot (Reboot Target Computer) +description: The .reboot command restarts the target computer. +ms.assetid: cc311a3d-d46a-4564-97e8-fb6112d0a60d +keywords: ["Reboot Target Computer (.reboot) command", "controlling the target, Reboot Target Computer (.reboot) command", ".reboot (Reboot Target Computer) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .reboot (Reboot Target Computer) +api_type: +- NA +--- + +# .reboot (Reboot Target Computer) + + +The **.reboot** command restarts the target computer. + +``` +.reboot +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands and an explanation of how the restart process affects the debugger, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.reboot%20%28Reboot%20Target%20Computer%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-record-branches--enable-branch-recording-.md b/windows-driver-docs-pr/debugger/-record-branches--enable-branch-recording-.md new file mode 100644 index 0000000000..3eb118c465 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-record-branches--enable-branch-recording-.md @@ -0,0 +1,72 @@ +--- +title: .record_branches (Enable Branch Recording) +description: The .record_branches command enables the recording of branches that the target's code executed. +ms.assetid: 522eeba5-b6c5-473c-9c8e-8ef4c941079f +keywords: ["Enable Branch Recording (.record_branches) command", ".record_branches (Enable Branch Recording) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .record_branches (Enable Branch Recording) +api_type: +- NA +--- + +# .record\_branches (Enable Branch Recording) + + +The **.record\_branches** command enables the recording of branches that the target's code executed. + +``` +.record_branches {1|0} +.record_branches +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

x64-based only

+ +  + +Remarks +------- + +The **.record\_branches 1** command enables the recording of branches in the target's code. The **.record\_branches 0** command disables this recording. + +Without parameters, **.record\_branches** displays the current status of this setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.record_branches%20%28Enable%20Branch%20Recording%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-reg.md b/windows-driver-docs-pr/debugger/-reg.md new file mode 100644 index 0000000000..ab11dbd4e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-reg.md @@ -0,0 +1,273 @@ +--- +title: reg +description: The reg extension displays and searches through registry data. +ms.assetid: 97944c84-da2e-4859-bf99-75d05413314d +keywords: ["reg Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- reg +api_type: +- NA +--- + +# !reg + + +The **!reg** extension displays and searches through registry data. + +``` +!reg {querykey|q} FullKeyPath +!reg keyinfo HiveAddress KeyNodeAddress +!reg kcb Address +!reg knode Address +!reg kbody Address +!reg kvalue Address +!reg valuelist HiveAddress KeyNodeAddress +!reg subkeylist HiveAddress KeyNodeAddress +!reg baseblock HiveAddress +!reg seccache HiveAddress +!reg hashindex [HiveAddress]HashKey +!reg openkeys {HiveAddress|0} +!reg openhandles {HiveAddress|0} +!reg findkcb FullKeyPath +!reg hivelist +!reg viewlist HiveAddress +!reg freebins HiveAddress +!reg freecells BinAddress +!reg dirtyvector HiveAddress +!reg cellindex HiveAddress Index +!reg freehints HiveAddress Storage Display +!reg translist {RmAddress|0} +!reg uowlist TransactionAddress +!reg locktable KcbAddress ThreadAddress +!reg convkey KeyPath +!reg postblocklist +!reg notifylist +!reg ixlock LockAddress +!reg dumppool [s|r] +``` + +## Parameters + + + {**querykey**|**q**} **** *FullKeyPath* +Displays subkeys and values of a key if the key is cached. *FullKeyPath* specifies the full key path. + + **keyinfo** *HiveAddress* **** *KeyNodeAddress* +Displays subkeys and values of a key node. *HiveAddress* specifies the address of the hive. *KeyNodeAddress* specifies the address of the key node. + + **kcb** **** *Address* +Displays a registry key control block. *Address* specifies the address of the key control block. + + **knode** **** *Address* +Displays a registry key node structure. *Address* specifies the address of the key node. + + **kbody** **** *Address* +Displays a registry key body structure. *Address* specifies the address of the key body. (Registry key bodies are the actual objects associated with handles.) + + **kvalue** **** *Address* +Displays a registry key value structure. *Address* specifies the address of the value. + + **valuelist** **** *HiveAddress* **** *KeyNodeAddress* +Displays a list of the values in the specified key node. *HiveAddress* specifies the address of the hive. *KeyNodeAddress* specifies the address of the key node. + +**subkeylist** **** *HiveAddress* **** *KeyNodeAddress* +Displays a list of the subkeys of the specified key node. *HiveAddress* specifies the address of the hive. *KeyNodeAddress* specifies the address of the key node. + + **baseblock** **** *HiveAddress* +Displays the base block for a hive (also known as the *hive header*). *HiveAddress* specifies the address of the hive. + + **seccache** **** *HiveAddress* +Displays the security cache for a hive. *HiveAddress* specifies the address of the hive. + + **hashindex** **** \[*HiveAddress*\] **** *HashKey* +Computes the hash index entry for a hash key. *HiveAddress* specifies the address of the hive. *HashKey* specifies the key. + +**Note**  *HiveAddress* is required if the target computer is running Windows 7 or later. + +  + + **openkeys** {*HiveAddress*|**0**} +Displays all open keys in a hive. *HiveAddress* specifies the address of the hive. If zero is used instead, the entire registry hash table is displayed; this table contains all open keys in the registry. + + **findkcb** **** *FullKeyPath* +Displays the registry key control block corresponding to a registry path. *FullKeyPath* specifies the full key path; this path must be present in the hash table. + + **hivelist** +Displays a list of all hives in the system, along with detailed information about each hive. + + **viewlist** **** *HiveAddress* +Displays all pinned and mapped views for a hive, with detailed information for each view. *HiveAddress* specifies the address of the hive. + + **freebins** **** *HiveAddress* +Displays all free bins for a hive, with detailed information for each bin. *HiveAddress* specifies the address of the hive. + + **freecells** **** *BinAddress* +Iterates through a bin and displays all free cells inside it. *BinAddress* specifies the address of the bin. + + **dirtyvector** **** *HiveAddress* +Displays the dirty vector for a hive. *HiveAddress* specifies the address of the hive. + + **cellindex** **** *HiveAddress* **** *Index* +Displays the virtual address for a cell in a hive. *HiveAddress* specifies the address of the hive. *Index* specifies the cell index. + + **freehints** *HiveAddress* **** *Storage* **** *Display* +Displays free hint information. + + **translist** {*RmAddress*|**0**} +Displays the list of active transactions in an RM. *RmAddress* specifies the address of the RM. + + **uowlist** *TransactionAddress* +Displays the list of UoWs attached to a transaction. *TransactionAddress* specifies the address of the transaction. + + **locktable** *KcbAddress* *ThreadAddress* +Displays relevant lock table content. + + **convkey** *KeyPath* +Displays hash keys for a key path. + + **postblocklist** +Displays the list of threads that have postblocks posted. + + **notifylist** +Displays the list of notify blocks in the system. + + **ixlock** *LockAddress* +Displays ownership of an intent lock. *LockAddress* specifies the address of the lock. + + **dumppool** \[**s**|**r**\] +Displays registry-allocated paged pool. If **s** is specified, the list of registry pages is saved to a temporary file. If **r** is specified, the registry page list is restored from the previously saved temporary file. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about the registry and its components, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +Here is an example. First use **!reg hivelist** to get a list of hive addresses. + +``` +00: kd> !reg hivelist +## + +## | HiveAddr |Stable Length| Stable Map |Volatile Length| Volatile Map |MappedViews|PinnedViews|U(Cnt)| BaseBlock | FileName + +| fffff8a000014010 | 1000 | fffff8a0000140b0 | 1000 | fffff8a000014328 | 0| fffff8a00001e000 | +| fffff8a000028010 | a15000 | fffff8a00002e000 | 1a000 | fffff8a000028328 | 0| fffff8a000029000 | SYSTEM +| fffff8a00004f010 | 14000 | fffff8a00004f0b0 | c000 | fffff8a00004f328 | 0| fffff8a000050000 | +| fffff8a000329010 | 6000 | fffff8a0003290b0 | 0 | 0000000000000000 | 0| fffff8a00032f000 | Device\HarddiskVolume1\Boot\BCD +| fffff8a0002f2010 | 4255000 | fffff8a0006fa000 | 6000 | fffff8a0002f2328 | 0| fffff8a00036c000 | emRoot\System32\Config\SOFTWARE +| fffff8a000df0010 | f7000 | fffff8a000df00b0 | 1000 | fffff8a000df0328 | 0| fffff8a000df1000 | temRoot\System32\Config\DEFAULT +| fffff8a0010f8010 | 9000 | fffff8a0010f80b0 | 1000 | fffff8a0010f8328 | 0| fffff8a0010f9000 | emRoot\System32\Config\SECURITY +| fffff8a001158010 | 7000 | fffff8a0011580b0 | 0 | 0000000000000000 | 0| fffff8a001159000 | \SystemRoot\System32\Config\SAM +| fffff8a00124b010 | 24000 | fffff8a00124b0b0 | 0 | 0000000000000000 | 0| fffff8a00124c000 | files\NetworkService\NTUSER.DAT +| fffff8a0012df220 | b7000 | fffff8a0012df2c0 | 0 | 0000000000000000 | 0| fffff8a0012e6000 | \SystemRoot\System32\Config\BBI +| fffff8a001312220 | 26000 | fffff8a0013122c0 | 0 | 0000000000000000 | 0| fffff8a00117e000 | rofiles\LocalService\NTUSER.DAT +| fffff8a001928010 | 64000 | fffff8a0019280b0 | 3000 | fffff8a001928328 | 0| fffff8a00192b000 | User.MYTESTCOMPUTER2\ntuser.dat +| fffff8a001b9b010 | 203000 | fffff8a001bc4000 | 0 | 0000000000000000 | 0| fffff8a001b9c000 | \Microsoft\Windows\UsrClass.dat +| fffff8a001dc0010 | 30000 | fffff8a001dc00b0 | 0 | 0000000000000000 | 0| fffff8a001dc2000 | Volume Information\Syscache.hve +## | fffff8a0022dc010 | 175000 | fffff8a0022dc0b0 | 0 | 0000000000000000 | 0| fffff8a0022dd000 | \AppCompat\Programs\Amcache.hve + +``` + +Use the third hive address in the preceding output (fffff8a00004f010) as an argument to **!reg openkeys**. + +``` +0: kd> !reg openkeys fffff8a00004f010 + +# Hive: \REGISTRY\MACHINE\HARDWARE + +Index e9: 3069276d kcb=fffff8a00007eb98 cell=00000220 f=00200000 \REGISTRY\MACHINE\HARDWARE\DESCRIPTION\SYSTEM +Index 101: 292eea1f kcb=fffff8a00007ecc0 cell=000003b8 f=00200000 \REGISTRY\MACHINE\HARDWARE\DESCRIPTION\SYSTEM\MULTIFUNCTIONADAPTER +Index 140: d927b0d4 kcb=fffff8a00007ea70 cell=000001a8 f=00200000 \REGISTRY\MACHINE\HARDWARE\DESCRIPTION +Index 160: 96d26a30 kcb=fffff8a00007e6f8 cell=00000020 f=002c0000 \REGISTRY\MACHINE\HARDWARE + +# 0x4 keys found + +``` + +Use the first full key path in the preceding output (\\REGISTRY\\MACHINE\\HARDWARE\\DESCRIPTION\\SYSTEM) as an argument to **!reg querykey**. + +``` +0: kd> !reg querykey \REGISTRY\MACHINE\HARDWARE\DESCRIPTION\SYSTEM + +Found KCB = fffff8a00007eb98 :: \REGISTRY\MACHINE\HARDWARE\DESCRIPTION\SYSTEM + +Hive fffff8a00004f010 +KeyNode fffff8a000054224 + +[SubKeyAddr] [SubKeyName] +fffff8a000060244 CentralProcessor +fffff8a00006042c FloatingPointProcessor +fffff8a0000543bc MultifunctionAdapter + +[SubKeyAddr] [VolatileSubKeyName] +fffff8a000338d8c BIOS +fffff8a0002a2e4c VideoAdapterBusses + + Use '!reg keyinfo fffff8a00004f010 ' to dump the subkey details + +[ValueType] [ValueName] [ValueData] +REG_BINARY Component Information 0x542AC - 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 +REG_SZ Identifier AT/AT COMPATIBLE +REG_FULL_RESOURCE_DESCRIPTORConfiguration Data ff ff ff ff ff ff ff ff 00 00 00 00 02 00 00 00 05 00 00 00 18 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 80 00 ff 03 00 00 3f 00 fe 00 02 00 81 00 fe 03 00 00 3f 00 fe 00 02 00 05 00 00 00 08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0c 00 00 00 04 00 +REG_SZ SystemBiosDate 07/18/07 +REG_MULTI_SZ SystemBiosVersion HPQOEM - 20070718\0\0 +REG_SZ VideoBiosDate 03/23/20 +REG_MULTI_SZ VideoBiosVersion Hardware Version 0.0\0\0 +``` + +Here is another example: + +``` +kd> !reg hivelist +## + +## | HiveAddr |Stable Length|Stable Map|Volatile Length|Volatile Map|MappedViews|PinnedViews|U(Cnt)| BaseBlock | FileName + +| e16e7428 | 2000 | e16e7484 | 0 | 00000000 | 1 | 0 | 0| e101f000 | \Microsoft\Windows\UsrClass.dat +| e1705a78 | 77000 | e1705ad4 | 1000 | e1705bb0 | 30 | 0 | 0| e101c000 | ttings\Administrator\ntuser.dat +| e13d4b88 | 814000 | e146a000 | 1000 | e13d4cc0 | 255 | 0 | 0| e1460000 | emRoot\System32\Config\SOFTWARE +| e13ad008 | 23000 | e13ad064 | 1000 | e13ad140 | 9 | 0 | 0| e145e000 | temRoot\System32\Config\DEFAULT +| e13b3b88 | a000 | e13b3be4 | 1000 | e13b3cc0 | 3 | 0 | 0| e145d000 | emRoot\System32\Config\SECURITY +| e142d008 | 5000 | e142d064 | 0 | 00000000 | 2 | 0 | 0| e145f000 | +| e11e3628 | 4000 | e11e3684 | 3000 | e11e3760 | 0 | 0 | 0| e11e4000 | +| e10168a8 | 1c1000 | e1016904 | 15000 | e10169e0 | 66 | 0 | 0| e1017000 | SYSTEM +## | e10072c8 | 1000 | e1007324 | 0 | 00000000 | 0 | 0 | 0| e1010000 | + + +kd> !reg hashindex e16e7428 + +CmpCacheTable = e100a000 + +Hash Index[e16e7428] : 5ac +Hash Entry[e16e7428] : e100b6b0 + +kd> !reg openkeys e16e7428 + +Index 68: 7bab7683 kcb=e13314f8 cell=00000740 f=00200004 \REGISTRY\USER\S-1-5-21-1715567821-413027322-527237240-500_Classes\CLSID +Index 7a1: 48a30288 kcb=e13a3738 cell=00000020 f=002c0004 \REGISTRY\USER\S-1-5-21-1715567821-413027322-527237240-500_Classes +``` + +To display formatted registry key information, use the [**!dreg**](-dreg.md) extension instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!reg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-regkcb.md b/windows-driver-docs-pr/debugger/-regkcb.md new file mode 100644 index 0000000000..3aecade50f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-regkcb.md @@ -0,0 +1,76 @@ +--- +title: regkcb +description: The regkcb extension displays a registry key control block. +ms.assetid: d6898025-9ba2-4b3b-819b-d7b23d8ee525 +keywords: ["regkcb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- regkcb +api_type: +- NA +--- + +# !regkcb + + +The **!regkcb** extension displays a registry key control block. + +``` +!regkcb Address +``` + +## Parameters + + + *Address* +Specifies the address of the key control block. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +For information about the registry and its components, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +In Windows 2000, **!regkcb** displays a specific registry key control block. + +In Windows XP and later versions of Windows, the [**!reg**](-reg.md) extension command should be used instead. + +Every registry key has a control block that contains properties, such as its permissions. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!regkcb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rellist.md b/windows-driver-docs-pr/debugger/-rellist.md new file mode 100644 index 0000000000..b8f2bc3fbd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rellist.md @@ -0,0 +1,79 @@ +--- +title: rellist +description: The rellist extension displays a Plug and Play relation list. +ms.assetid: ecbf7e35-91c0-4ff4-82a4-53a935920915 +keywords: ["rellist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rellist +api_type: +- NA +--- + +# !rellist + + +The **!rellist** extension displays a Plug and Play relation list. + +``` +!rellist Address [Flags] +``` + +## Parameters + + + *Address* +Specifies the address of the relation list. + + *Flags* +Specifies additional information to include in the display. This can be any combination of the following bits (the default is zero): + +Bit 1 (0x2) +Causes the display to include the CM\_RESOURCE\_LIST. The display also includes the boot resources list, if it is available. + +Bit 2 (0x4) +Causes the display to include the resource requirements list (IO\_RESOURCE\_LIST). + +Bit 3 (0x8) +Causes the display to include the translated CM\_RESOURCE\_LIST. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +See [Plug and Play Debugging](plug-and-play-debugging.md) for applications of this extension command. For information about these list structures, see the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rellist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-reload--reload-module-.md b/windows-driver-docs-pr/debugger/-reload--reload-module-.md new file mode 100644 index 0000000000..7842783ec2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-reload--reload-module-.md @@ -0,0 +1,159 @@ +--- +title: .reload (Reload Module) +description: The .reload command deletes all symbol information for the specified module and reloads these symbols as needed. In some cases, this command also reloads or unloads the module itself. +ms.assetid: 750eb1a2-7af9-4f2d-81ca-9ea0fb157961 +keywords: ["Reload Module (.reload) command", "symbols, Reload Module (.reload) command", ".reload (Reload Module) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .reload (Reload Module) +api_type: +- NA +--- + +# .reload (Reload Module) + + +The **.reload** command deletes all symbol information for the specified module and reloads these symbols as needed. In some cases, this command also reloads or unloads the module itself. + +``` +.reload [Options] [Module[=Address[,Size[,Timestamp]]]] +.reload -? +``` + +## Parameters + + + *Options* +Any of the following options: + +**/d** +Reload all modules in the debugger's module list. (When you omit all parameters, this situation is the default during user-mode debugging.) + +**/f** +Forces the debugger to immediately load the symbols. This parameter overrides *lazy symbol loading*. For more information, see the following Remarks section. + +**/i** +Ignores a mismatch in the .pdb file versions. (If you do not include this parameter, the debugger does not load mismatched symbol files.) When you use **/i**, **/f** is used also, even if you do not explicitly specify it. + +**/l** +Lists the modules but does not reload their symbols. (In kernel mode, this parameter gives the same output as the [**!drivers**](-drivers.md) extension.) + +**/n** +Reloads kernel symbols only. This parameter does not reload any user symbols. (You can use this option only during kernel-mode debugging.) + +**/o** +Forces the cached files in a symbol server's downstream store to be overwritten. When you use this flag, you should also include **/f**. By default, the downstream store files are never overwritten. + +Because the symbol server uses distinct file names for the symbols of every different build of a binary, you do not have to use this option unless you believe your downstream store has become corrupted. + +**/s** +Reloads all modules in the system's module image list. (When you omit all parameters, this situation is the default during kernel-mode debugging.) + +If you are loading an individual system module by name while you perform user-mode debugging, you must include **/s**. + +**/u** +Unloads the specified module and all its symbols. The debugger unloads any loaded module whose name matches *Module*, regardless of the full path. Image names are also searched. For more information, see the note in the following Remarks section. + +**/unl** +Reloads symbols based on the image information in the unloaded module list. + +**/user** +Reloads user symbols only. (You can use this option only during kernel-mode debugging.) + +**/v** +Turns on verbose mode. + +**/w** +Treats *Module* as a literal string. This treatment prevents the debugger from expanding wildcard characters. + + *Module* +Specifies the name of an image on the target system for which to reload symbols on the host computer. *Module* should include the name and file name extension of the file. Unless you use the **/w** option, *Module* might contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). If you omit *Module*, the behavior of the **.reload** command depends on which *Options* you use. + + *Address* +Specifies the base address of the module. Typically, you have to have this address only if the image header has been corrupted or is paged out. + + *Size* +Specifies the size of the module image. In many situations, the debugger knows the correct size of the module. When the debugger does not know the correct size, you should specify *Size*. This size can be the actual module size or a larger number, but the size should not be a smaller number. Typically, you have to have this size only if the image header has been corrupted or is paged out. + + *Timestamp* +Specifies the timestamp of the module image. In many situations, the debugger knows the correct timestamp of the module. When the debugger does not know the timestamps, you should specify *Timestamp*. Typically, you have to have this timestamp only if the image header has been corrupted or is paged out. + +**Note**   There must be no blank space between the *Address*, *Size*, and *Timestamp* parameters. + +  + + **-?** +Displays a short help text for this command. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about deferred (lazy) symbol loading, see [Deferred Symbol Loading](deferred-symbol-loading.md). For more information about other symbol options, see [Setting Symbol Options](symbol-options.md). + +Remarks +------- + +The **.reload** command does not cause symbol information to be read. Instead, this command lets the debugger know that the symbol files might have changed or that a new module should be added to the module list. This command causes the debugger to revise its module list and delete its symbol information for the specified modules. The actual symbol information is not read from the individual .pdb files until the information is needed. (This kind of loading is known as *lazy symbol loading* or *deferred symbol loading*.) + +You can force symbol loading to occur by using the **/f** option or by issuing an [**ld (Load Symbols)**](ld--load-symbols-.md) command. + +The **.reload** command is useful if the system stops responding (that is, crashes), which might cause you to lose symbols for the target computer that is being debugged. The command can also be useful if you have updated the symbol tree. + +If the image header is incorrect for some reason, such as the module being unloaded, or is paged out, you can load symbols correctly by using the **/unl** argument, or specifying both *Address* and *Size*. + +The **.reload /u** command performs a broad search. The debugger first tries to match *Module* with an exact module name, regardless of path. If the debugger cannot find this match, *Module* is treated as the name of the loaded image. For example, if the HAL that resides in memory has the module name of halacpi.dll, both of the following commands unload its symbols. + +``` +kd> .reload /u halacpi.dll + +kd> .reload /u hal +``` + +If you are performing user-mode debugging and want to load a module that is not part of the target application's module list, you must include the **/s** option, as the following example shows. + +``` +0:000> .reload /u ntdll.dll +Unloaded ntdll.dll + +0:000> .reload /s /f ntdll.dll +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.reload%20%28Reload%20Module%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-remote--create-remote-exe-server-.md b/windows-driver-docs-pr/debugger/-remote--create-remote-exe-server-.md new file mode 100644 index 0000000000..cb0642377e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-remote--create-remote-exe-server-.md @@ -0,0 +1,78 @@ +--- +title: .remote (Create Remote.exe Server) +description: The .remote command starts a Remote.exe Server, enabling a remote connection to the current debugging session. +ms.assetid: fa3de33c-ba8c-4e9c-9899-b9a43f3195bf +keywords: ["Create Remote.exe Server (.remote) command", "remote debugging through remote.exe, Create Remote.exe Server (.remote) command", ".remote (Create Remote.exe Server) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .remote (Create Remote.exe Server) +api_type: +- NA +--- + +# .remote (Create Remote.exe Server) + + +The **.remote** command starts a [Remote.exe Server](starting-a-remote-exe-session.md), enabling a remote connection to the current debugging session. + +``` +.remote session +``` + +## Parameters + + + *session* +Specifies a name that you give to the debugging session. + +### Environment + +You can use the **.remote** command in KD and CDB, but you cannot use it in WinDbg. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to use Remote.exe Servers and Remote.exe Clients, see [Remote Debugging Through Remote.exe](remote-debugging-through-remote-exe.md). + +Remarks +------- + +The **.remote** command creates a Remote.exe process and turns the current debugger into a Remote.exe Server. This server enables a Remote.exe Client to connect to the current debugging session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.remote%20%28Create%20Remote.exe%20Server%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-remote-exit--exit-debugging-client-.md b/windows-driver-docs-pr/debugger/-remote-exit--exit-debugging-client-.md new file mode 100644 index 0000000000..654b673751 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-remote-exit--exit-debugging-client-.md @@ -0,0 +1,80 @@ +--- +title: .remote_exit (Exit Debugging Client) +description: The .remote_exit command exits the debugging client but does not end the debugging session. +ms.assetid: 9e15a842-6864-4ff9-97bc-f6cc8549a422 +keywords: ["Exit Debugging Client (.remote_exit) command", "remote debugging through the debugger, Exit Debugging Client (.remote_exit) command", ".remote_exit (Exit Debugging Client) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .remote_exit (Exit Debugging Client) +api_type: +- NA +--- + +# .remote\_exit (Exit Debugging Client) + + +The **.remote\_exit** command exits the debugging client but does not end the debugging session. + +``` +.remote_exit [FinalCommands] +``` + +## Parameters + + + *FinalCommands* +Specifies a command string to pass to the debugging server. You should separate multiple commands by using semicolons. These commands are passed to the debugging server and the connection is then broken. + +### Environment + +You can use the **.remote\_exit** command only in a script file. You can use it in KD and CDB, but you cannot use it in WinDbg. + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about script files, see [Using Script Files](using-script-files.md). For more information about debugging clients and debugging servers, see [Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md). + +Remarks +------- + +If you are using KD or CDB directly, instead of using a script, you can exit from the debugging client by using the [**CTRL+B**](ctrl-b--quit-local-debugger-.md) key. + +You cannot exit from a debugging client through a script that is executed in WinDbg. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.remote_exit%20%28Exit%20Debugging%20Client%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-restart--restart-kernel-connection-.md b/windows-driver-docs-pr/debugger/-restart--restart-kernel-connection-.md new file mode 100644 index 0000000000..3f0b95bbfa --- /dev/null +++ b/windows-driver-docs-pr/debugger/-restart--restart-kernel-connection-.md @@ -0,0 +1,79 @@ +--- +title: .restart (Restart Kernel Connection) +description: The .restart command restarts the kernel connection.Do not confuse this command with the .restart (Restart Target Application) command, which works only in user mode. +ms.assetid: 2c81625b-d75f-4c5f-9437-9619bf33b500 +keywords: [".restart (Restart Kernel Connection) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .restart (Restart Kernel Connection) +api_type: +- NA +--- + +# .restart (Restart Kernel Connection) + + +The **.restart** command restarts the kernel connection. + +Do not confuse this command with the [**.restart (Restart Target Application)**](-restart--restart-target-application-.md) command, which works only in user mode. + +``` +.restart +``` + +## + + +### Environment + +You can use the **.restart** command only in KD. + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about reestablishing contact with the target, see [Synchronizing with the Target Computer](synchronizing-with-the-target-computer.md). + +Remarks +------- + +The **.restart** command is similar to the [**CTRL+R (Re-synchronize)**](ctrl-r--re-synchronize-.md) command, except that **.restart** is even more extensive in its effect. This command is equivalent to ending the debugger and then attaching a new debugger to the target computer. + +The **.restart** command is most useful when you are performing [remote debugging through remote.exe](remote-debugging-through-remote-exe.md) and ending and restarting the debugger might be difficult. However, you cannot use **.restart** from a debugging client if you are performing remote debugging through the debugger. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.restart%20%28Restart%20Kernel%20Connection%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-restart--restart-target-application-.md b/windows-driver-docs-pr/debugger/-restart--restart-target-application-.md new file mode 100644 index 0000000000..cb2f9122e3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-restart--restart-target-application-.md @@ -0,0 +1,81 @@ +--- +title: .restart (Restart Target Application) +description: The .restart command restarts the target application.Do not confuse this command with the .restart (Restart Kernel Connection) command, which works only in kernel mode. +ms.assetid: abfa1817-41d8-4bb2-a6d2-e9c9027b50df +keywords: [".restart (Restart Target Application) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .restart (Restart Target Application) +api_type: +- NA +--- + +# .restart (Restart Target Application) + + +The **.restart** command restarts the target application. + +Do not confuse this command with the [**.restart (Restart Kernel Connection)**](-restart--restart-kernel-connection-.md) command, which works only in kernel mode. + +``` +.restart +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to issue this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +CDB and WinDbg can restart a target application if the debugger originally created the application. You can use the **.restart** command even if the target application has already closed. + +However, if the application is running and the debugger is later attached to the process, the **.restart** command has no effect. + +After the process is restarted, it immediately breaks into the debugger. + +In WinDbg, use the [View | WinDbg Command Line](view---windbg-command-line.md) command if you started your target from the WinDbg command prompt and you want to review this command line before you decide whether to use **.restart**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.restart%20%28Restart%20Target%20Application%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-checkrpcsym.md b/windows-driver-docs-pr/debugger/-rpcexts-checkrpcsym.md new file mode 100644 index 0000000000..325964239b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-checkrpcsym.md @@ -0,0 +1,20 @@ +--- +title: rpcexts.checkrpcsym +description: rpcexts.checkrpcsym +ms.assetid: db757ff3-c108-4811-9bdd-fb95a769ae75 +--- + +# !rpcexts.checkrpcsym + + +The **!rpcexts.checkrpcsym** extension command is obsolete; the output from the debugger should be sufficient to diagnose any RPC symbol problems. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.checkrpcsym%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-eeinfo.md b/windows-driver-docs-pr/debugger/-rpcexts-eeinfo.md new file mode 100644 index 0000000000..e198d966d0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-eeinfo.md @@ -0,0 +1,91 @@ +--- +title: rpcexts.eeinfo +description: The rpcexts.eeinfo extension displays the extended error information chain. +ms.assetid: dc842236-bdbf-42aa-911d-6eb5eb1798ee +keywords: ["rpcexts.eeinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.eeinfo +api_type: +- NA +--- + +# !rpcexts.eeinfo + + +The **!rpcexts.eeinfo** extension displays the extended error information chain. + +``` +!rpcexts.eeinfo EEInfoAddress +``` + +## Parameters + + + *EEInfoAddress* +Specifies the address of the extended error information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension displays the contents of all records in the extended error information chain. + +The records are displayed in order, with the most recent records first. The records are separated by a line of dashes. + +Here is an example (in which there is only one record): + +``` +0:001> !rpcexts.eeinfo 0xb015f0 +Computer Name: (null) +ProcessID: 708 (0x2C4) +System Time is: 3/21/2000 4:3:0:264 +Generating component: 8 +Status: 14 +Detection Location: 311 +Flags: +Parameter 0:(Long value) : -30976 (0xFFFF8700) +Parameter 1:(Long value) : 16777343 (0x100007F) +``` + +If the chain is very long and you wish to see only one record, use [**!rpcexts.eerecord**](-rpcexts-eerecord.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.eeinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-eerecord.md b/windows-driver-docs-pr/debugger/-rpcexts-eerecord.md new file mode 100644 index 0000000000..9d9cb49db3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-eerecord.md @@ -0,0 +1,87 @@ +--- +title: rpcexts.eerecord +description: The rpcexts.eerecord extension displays the contents of an extended error information record. +ms.assetid: 3c861842-d3ac-4c7d-88e3-d00233189b74 +keywords: ["rpcexts.eerecord Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.eerecord +api_type: +- NA +--- + +# !rpcexts.eerecord + + +The **!rpcexts.eerecord** extension displays the contents of an extended error information record. + +``` +!rpcexts.eerecord EERecordAddress +``` + +## Parameters + + + *EERecordAddress* +Specifies the address of the extended error record. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension displays the contents of one extended error information record in the debugger. In most cases, it is easier to use [**!rpcexts.eeinfo**](-rpcexts-eeinfo.md), which displays the whole chain. If the chain is very long and you wish to see only one record, use **!eerecord** instead. + +Here is an example: + +``` +0:001> !rpcexts.eerecord 0xb015f0 +Computer Name: (null) +ProcessID: 708 (0x2C4) +System Time is: 3/21/2000 4:3:0:264 +Generating component: 8 +Status: 14 +Detection Location: 311 +Flags: +Parameter 0:(Long value) : -30976 (0xFFFF8700) +Parameter 1:(Long value) : 16777343 (0x100007F) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.eerecord%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-getcallinfo.md b/windows-driver-docs-pr/debugger/-rpcexts-getcallinfo.md new file mode 100644 index 0000000000..4f2b7d0e96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-getcallinfo.md @@ -0,0 +1,144 @@ +--- +title: rpcexts.getcallinfo +description: The rpcexts.getcallinfo extension searches the system's RPC state information for server-side call (SCALL) information. +ms.assetid: 85957afe-f73e-4533-af5c-5ee55b35ac84 +keywords: ["rpcexts.getcallinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.getcallinfo +api_type: +- NA +--- + +# !rpcexts.getcallinfo + + +The **!rpcexts.getcallinfo** extension searches the system's RPC state information for server-side call (SCALL) information. + +``` +!rpcexts.getcallinfo [ CallID | 0 [ IfStart | 0 [ ProcNum | 0xFFFF [ProcessID|0] ] ] ] +!rpcexts.getcallinfo -? +``` + +## Parameters + + + *CallID* +Specifies the call ID. This parameter is optional; include it if you only want to display calls matching a specific *CallID* value. + + *IfStart* +Specifies the first DWORD of the interface UUID on which the call was made. This parameter is optional; include it if you only want to display calls matching a specific *IfStart* value. + + *ProcNum* +Specifies the procedure number of this call. (The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file -- the first routine in the interface is 0, the second 1, and so on.) + + *ProcessID* +Specifies the process ID (PID) of the server process that owns the calls you want to display. This parameter is optional; omit it if you want to display calls owned by multiple processes. + + **-?** +Displays some brief Help text for this extension in the Command Prompt window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. + +The parameters are parsed from left to right. To skip a parameter, supply the value 0. There is one exception to this rule: the *ProcNum* parameter is skipped by supplying the value 0xFFFF. + +Here is an example: + +``` +0:002> !rpcexts.getcallinfo +Searching for call info ... +## PID CELL ID ST PNO IFSTART TIDNUMBER CALLFLAG CALLID LASTTIME CONN/CLN +---------------------------------------------------------------------------- +00c4 0000.0006 00 009 367abb81 0000.0007 00000001 0000004a 00018b41 0000.0005 +00c4 0000.000a 00 007 367abb81 0000.002d 00000001 0000009f 000134ff 0000.0009 +00c4 0000.000d 00 00f 82273fdc 0000.002d 00000001 00000002 00036cd8 0000.0042 +00c4 0000.0010 00 00f 367abb81 0000.002d 00000001 00000078 00011636 0000.000f +00c4 0000.0012 00 00d 8d9f4e40 0000.0007 00000001 0000004f 000097bd 0000.0011 +00c4 0000.0015 00 000 367abb81 0000.0004 00000001 0000004c 0002cccf 0000.0014 +00c4 0000.0017 00 007 367abb81 0000.0004 00000001 00000006 0000cf5e 0000.0016 +00c4 0000.0018 00 000 367abb81 0000.002d 00000001 0000000b 0001236f 0000.002a +00c4 0000.0019 01 00b 82273fdc 0000.0002 00000009 00000000 00018b19 00d0.0104 +00c4 0000.001b 00 009 65a93890 0000.0007 00000001 000000ea 0003cd14 0000.001a +00c4 0000.0021 00 03b 8d9f4e40 0000.0013 00000001 0000000b 0001162c 0000.0020 +00c4 0000.0022 01 008 82273fdc 0000.001f 00000009 00000000 00013405 00c4.02e8 +00c4 0000.0024 00 007 367abb81 0000.0004 00000001 00000006 0000f198 0000.0023 +00c4 0000.0026 00 000 367abb81 0000.0036 00000001 000000ab 00038049 0000.0025 +00c4 0000.0027 01 00b 82273fdc 0000.001f 00000009 00000000 00020b7c 00a8.0228 +00c4 0000.0028 01 008 82273fdc 0000.003e 00000009 00000000 0003a949 0294.02f0 +00c4 0000.0029 00 00d 8d9f4e40 0000.002d 00000001 0000033f 0003831a 0000.0031 +00c4 0000.0030 00 03b 8d9f4e40 0000.0013 00000001 00000002 00024e43 0000.002f +00c4 0000.0032 01 008 82273fdc 0000.001f 00000009 00000000 000118f3 022c.019c +00c4 0000.0035 00 007 367abb81 0000.0033 00000001 00000074 0001042d 0000.0034 +00c4 0000.0038 00 007 367abb81 0000.002d 00000001 0000000a 0002a3e4 0000.0037 +00c4 0000.003a 00 007 367abb81 0000.0036 00000001 00000063 0003b7b8 0000.0039 +00c4 0000.003b 00 004 3ba0ffc0 0000.002d 00000001 00000005 0002dd79 0000.002e +00c4 0000.003f 01 008 82273fdc 0000.0002 00000009 00000000 000245c6 01c0.037c +00c4 0000.0043 01 008 82273fdc 0000.0002 00000009 00000000 00037d50 020c.0394 +00c4 0000.0049 00 008 8d9f4e40 0000.0007 00000001 000002b1 0004e900 0000.0048 +0170 0000.0009 01 002 e60c73e6 0000.0002 00000009 baadf00d 0004ad30 020c.03a4 +0170 0000.000a 01 002 0b0a6584 0000.0008 00000009 baadf00d 0001187b 00c4.012c +0170 0000.000c 01 002 0b0a6584 0000.0008 00000009 baadf00d 00011cdc 022c.019c +0170 0000.000d 01 003 00000136 0000.0011 00000009 baadf00d 00034845 020c.02b4 +0170 0000.000e 01 000 412f241e 0000.0002 00000009 baadf00d 00012491 0294.02b8 +0170 0000.000f 01 002 0b0a6584 0000.0011 00000009 baadf00d 000492e7 026c.0118 +0170 0000.0010 01 002 e60c73e6 0000.0013 00000009 baadf00d 0004ab78 0378.038c +0170 0000.0014 01 004 e60c73e6 0000.0011 00000001 baadf00d 0002bc25 0378.024c +0170 0000.0015 01 003 00000136 0000.0013 00000009 00000003 00031d8d 0378.00b8 +0170 0000.0018 01 004 00000136 0000.0002 00000001 baadf00d 00032e05 020c.026c +020c 0000.0004 01 003 00000132 0000.000b 00000009 00000000 00034953 0170.0240 +020c 0000.000e 01 001 2f5f6520 0000.001e 00000009 00120006 00035bac 020c.03b4 +020c 0000.0010 01 000 629b9f66 0000.000f 00000009 00000000 000279ff 00a8.0194 +020c 0000.0011 01 004 faedcf59 0000.0003 00000009 00000012 0003836b 0378.024c +020c 0000.0012 01 001 629b9f66 0000.000f 00000009 00000000 0003657e 020c.02ec +020c 0000.0017 01 005 00000134 0000.0002 00000001 00000016 0003836b 0378.024c +020c 0000.001d 01 001 2f5f6520 0000.0014 00000001 0020007d 000351b2 020c.0258 +0294 0000.0004 01 004 00000132 0000.0002 00000009 00000000 0003b786 0170.01ac +0378 0000.0004 01 003 00000134 0000.0003 0000000b 00300038 0002d896 020c.021c +026c 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 0004caa5 0000.0003 +``` + +For a similar example using the DbgRpc tool, see [Get RPC Call Information](get-rpc-call-information.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.getcallinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-getclientcallinfo.md b/windows-driver-docs-pr/debugger/-rpcexts-getclientcallinfo.md new file mode 100644 index 0000000000..7cfa99954c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-getclientcallinfo.md @@ -0,0 +1,97 @@ +--- +title: rpcexts.getclientcallinfo +description: The rpcexts.getclientcallinfo extension searches the system's RPC state information for client call (CCALL) information. +ms.assetid: 1b838238-63b3-4618-bc59-6b4d74274b9c +keywords: ["rpcexts.getclientcallinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.getclientcallinfo +api_type: +- NA +--- + +# !rpcexts.getclientcallinfo + + +The **!rpcexts.getclientcallinfo** extension searches the system's RPC state information for client call (CCALL) information. + +``` +!rpcexts.getclientcallinfo [ CallID | 0 [ IfStart | 0 [ ProcNum | 0xFFFF [ProcessID|0] ] ] ] +!rpcexts.getclientcallinfo -? +``` + +## Parameters + + + *CallID* +Specifies the call ID. This parameter is optional; include it if you only want to display calls matching a specific *CallID* value. + + *IfStart* +Specifies the first DWORD of the interface UUID on which the call was made. This parameter is optional; include it if you only want to display calls matching a specific *IfStart* value. + + *ProcNum* +Specifies the procedure number of this call. (The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file -- the first routine in the interface is 0, the second 1, and so on.) This parameter is optional; include it if you only want to display calls matching a specific *ProcNum* value. + + *ProcessID* +Specifies the process ID (PID) of the client process that owns the calls you want to display. This parameter is optional; omit it if you want to display calls owned by multiple processes. + + **-?** +Displays some brief Help text for this extension in the Command Prompt window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. It is only available if full RPC state information is being gathered. + +Here is an example: + +``` +0:002> !rpcexts.getclientcallinfo +Searching for call info ... +## PID CELL ID PNO IFSTART TIDNUMBER CALLID LASTTIME PS CLTNUMBER ENDPOINT +------------------------------------------------------------------------------ +03d4 0000.0001 0000 19bb5061 0000.0000 00000001 0004ca9b 07 0000.0002 1118 +``` + +For a similar example using the DbgRpc tool, see [Get RPC Client Call Information](get-rpc-client-call-information.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.getclientcallinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-getdbgcell.md b/windows-driver-docs-pr/debugger/-rpcexts-getdbgcell.md new file mode 100644 index 0000000000..f01875c9cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-getdbgcell.md @@ -0,0 +1,97 @@ +--- +title: rpcexts.getdbgcell +description: The rpcexts.getdbgcell extension displays RPC state information for the specified cell. +ms.assetid: 28be074f-6756-4610-aa86-1162b83fd0a7 +keywords: ["rpcexts.getdbgcell Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.getdbgcell +api_type: +- NA +--- + +# !rpcexts.getdbgcell + + +The **!rpcexts.getdbgcell** extension displays RPC state information for the specified cell. + +``` +!rpcexts.getdbgcell ProcessID CellID1.CellID2 +!rpcexts.getdbgcell -? +``` + +## Parameters + + + *ProcessID* +Specifies the process ID (PID) of the process whose server contains the desired cell. + + *CellID1*.*CellID2* +Specifies the number of the cell to be displayed. + + **-?** +Displays some brief Help text for this extension in the Command Prompt window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. + +Here is an example: + +``` +0:002> !rpcexts.getdbgcell c4 0.19 +Getting cell info ... +Call +Status: Active +Procedure Number: 11 +Interface UUID start (first DWORD only): 82273FDC +Call ID: 0x0 (0) +Servicing thread identifier: 0x0.3E +Call Flags: cached, LRPC +Last update time (in seconds since boot):1453.459 (0x5AD.1CB) +Caller (PID/TID) is: d0.1ac (208.428) +``` + +For a similar example using the DbgRpc tool, see [Get RPC Cell Information](get-rpc-cell-information.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.getdbgcell%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-getendpointinfo.md b/windows-driver-docs-pr/debugger/-rpcexts-getendpointinfo.md new file mode 100644 index 0000000000..fb0cc83bab --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-getendpointinfo.md @@ -0,0 +1,123 @@ +--- +title: rpcexts.getendpointinfo +description: The rpcexts.getendpointinfo extension searches the system's RPC state information for endpoint information. +ms.assetid: 3efd0cd1-bcdd-4785-aa00-a32a7578219c +keywords: ["rpcexts.getendpointinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.getendpointinfo +api_type: +- NA +--- + +# !rpcexts.getendpointinfo + + +The **!rpcexts.getendpointinfo** extension searches the system's RPC state information for endpoint information. + +``` + !rpcexts.getendpointinfo [EndpointName] +!rpcexts.getendpointinfo -? +``` + +## Parameters + + + *EndpointName* +Specifies the number of the endpoint to be displayed. If omitted, the endpoints for all processes on the system are displayed. + + **-?** +Displays some brief Help text for this extension in the Command Prompt window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. + +Here is an example: + +``` +0:002> !rpcexts.getendpointinfo +Searching for endpoint info ... +## PID CELL ID ST PROTSEQ ENDPOINT +------------------------------------------------------------- +00a8 0000.0001 01 NMP \PIPE\InitShutdown +00a8 0000.0003 01 NMP \PIPE\SfcApi +00a8 0000.0004 01 NMP \PIPE\ProfMapApi +00a8 0000.0005 01 LRPC OLE5 +00a8 0000.0007 01 NMP \pipe\winlogonrpc +00c4 0000.0001 01 LRPC ntsvcs +00c4 0000.0003 01 NMP \PIPE\ntsvcs +00c4 0000.0008 01 NMP \PIPE\scerpc +00d0 0000.0001 01 NMP \PIPE\lsass +00d0 0000.0003 01 NMP \pipe\WMIEP_d0 +00d0 0000.0006 01 LRPC policyagent +00d0 0000.0007 01 NMP \PIPE\POLICYAGENT +0170 0000.0001 01 LRPC epmapper +0170 0000.0003 01 TCP 135 +0170 0000.0005 01 SPX 34280 +0170 0000.0006 01 NB 135 +0170 0000.0007 01 NB 135 +0170 0000.000b 01 NMP \pipe\epmapper +01c0 0000.0001 01 NMP \pipe\spoolss +01c0 0000.0003 01 LRPC spoolss +01c0 0000.0007 01 LRPC OLE7 +020c 0000.0001 01 LRPC OLE2 +020c 0000.0005 01 LRPC senssvc +020c 0000.0007 01 NMP \pipe\tapsrv +020c 0000.0009 01 LRPC tapsrvlpc +020c 0000.000c 01 NMP \PIPE\ROUTER +020c 0000.0016 01 NMP \pipe\WMIEP_20c +0218 0000.0001 01 NMP \PIPE\winreg +022c 0000.0001 01 LRPC LRPC0000022c.00000001 +022c 0000.0003 01 TCP 1041 +022c 0000.0005 01 SPX 24576 +022c 0000.0006 01 NMP \PIPE\atsvc +0294 0000.0001 01 LRPC OLE3 +0378 0000.0001 01 LRPC OLE9 +026c 0000.0001 01 TCP 1118 +0344 0000.0001 01 LRPC OLE12 +``` + +For a similar example using the DbgRpc tool, see [Get RPC Endpoint Information](get-rpc-endpoint-information.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.getendpointinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-getthreadinfo.md b/windows-driver-docs-pr/debugger/-rpcexts-getthreadinfo.md new file mode 100644 index 0000000000..9def62145f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-getthreadinfo.md @@ -0,0 +1,92 @@ +--- +title: rpcexts.getthreadinfo +description: The rpcexts.getthreadinfo extension searches the system's RPC state information for thread information. +ms.assetid: 904605e7-c53b-4e29-874f-7a055fc7a02b +keywords: ["rpcexts.getthreadinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.getthreadinfo +api_type: +- NA +--- + +# !rpcexts.getthreadinfo + + +The **!rpcexts.getthreadinfo** extension searches the system's RPC state information for thread information. + +``` +!rpcexts.getthreadinfo ProcessID [ThreadID] +!rpcexts.getthreadinfo -? +``` + +## Parameters + + + *ProcessID* +Specifies the process ID (PID) of the process containing the desired thread. + + *ThreadID* +Specifies the thread ID of the thread to be displayed. If omitted, all threads in the specified process will be displayed. + + **-?** +Displays some brief Help text for this extension in the Command Prompt window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. + +Here is an example: + +``` +0:002> !rpcexts.getthreadinfo 26c +Searching for thread info ... +## PID CELL ID ST TID LASTTIME +----------------------------------- +026c 0000.0002 01 000003c4 0004caa5 +026c 0000.0005 03 00000254 0004ca9b +``` + +For a similar example using the DbgRpc tool, see [Get RPC Thread Information](get-rpc-thread-information.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.getthreadinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-help.md b/windows-driver-docs-pr/debugger/-rpcexts-help.md new file mode 100644 index 0000000000..5babde6962 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-help.md @@ -0,0 +1,60 @@ +--- +title: rpcexts.help +description: The rpcexts.help extension displays a Help text in the Command Prompt window showing all Rpcexts.dll extension commands. +ms.assetid: 1d7c238b-9f08-461b-ba7b-7ce1eb1b7b9f +keywords: ["rpcexts.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.help +api_type: +- NA +--- + +# !rpcexts.help + + +The **!rpcexts.help** extension displays a Help text in the Command Prompt window showing all Rpcexts.dll extension commands. + +``` +!rpcexts.help +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Rpcexts.dll

Windows XP and later

Rpcexts.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-rpcreadstack.md b/windows-driver-docs-pr/debugger/-rpcexts-rpcreadstack.md new file mode 100644 index 0000000000..5fb8da8b05 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-rpcreadstack.md @@ -0,0 +1,84 @@ +--- +title: rpcexts.rpcreadstack +description: The rpcexts.rpcreadstack extension reads an RPC client-side stack and retrieves the call information. +ms.assetid: e0988ac9-dc6e-4a4f-9096-6af2e70dcd42 +keywords: ["rpcexts.rpcreadstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.rpcreadstack +api_type: +- NA +--- + +# !rpcexts.rpcreadstack + + +The **!rpcexts.rpcreadstack** extension reads an RPC client-side stack and retrieves the call information. + +``` +!rpcexts.rpcreadstack ThreadStackPointer +``` + +## Parameters + + + *ThreadStackPointer* +Specifies the pointer to the thread stack. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +For a common use of this extension, see [Analyzing a Stuck Call Problem](analyzing-a-stuck-call-problem.md). + +Here is an example: + +``` +0:001> !rpcexts.rpcreadstack 68fba4 +CallID: 1 +IfStart: 19bb5061 +ProcNum: 0 + Protocol Sequence: "ncacn_ip_tcp" (Address: 00692ED8) + NetworkAddress: "" (Address: 00692F38) + Endpoint: "1120" (Address: 00693988) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.rpcreadstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-rpctime.md b/windows-driver-docs-pr/debugger/-rpcexts-rpctime.md new file mode 100644 index 0000000000..26ad66a24a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-rpctime.md @@ -0,0 +1,72 @@ +--- +title: rpcexts.rpctime +description: The rpcexts.rpctime extension displays the current system time. +ms.assetid: 72d54357-6b16-4d53-9909-ba201bb33519 +keywords: ["rpcexts.rpctime Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.rpctime +api_type: +- NA +--- + +# !rpcexts.rpctime + + +The **!rpcexts.rpctime** extension displays the current system time. + +``` +!rpcexts.rpctime +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Rpcexts.dll

Windows XP and later

Rpcexts.dll

+ +  + +Remarks +------- + +This extension can only be used with CDB or with user-mode WinDbg. + +Here is an example: + +``` +0:001> !rpcexts.rpctime +Current time is: 059931.126 (0x00ea1b.07e) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.rpctime%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rpcexts-thread.md b/windows-driver-docs-pr/debugger/-rpcexts-thread.md new file mode 100644 index 0000000000..7fe2eb2f5b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rpcexts-thread.md @@ -0,0 +1,95 @@ +--- +title: rpcexts.thread +description: The rpcexts.thread extension displays the per-thread RPC information.This extension command should not be confused with the .thread command. +ms.assetid: eecc4eb6-7789-47ed-8b3f-5ec21cc6117c +keywords: ["rpcexts.thread Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rpcexts.thread +api_type: +- NA +--- + +# !rpcexts.thread + + +The **!rpcexts.thread** extension displays the per-thread RPC information. + +This extension command should not be confused with the [**.thread (Set Register Context)**](-thread--set-register-context-.md) command or the [**!thread**](-thread.md) (!kdextx86.thread and !kdexts.thread) extension. + +``` +!rpcexts.thread TEB +``` + +## Parameters + + + *TEB* +Specifies the address of the thread environment block (TEB). + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Rpcexts.dll

Windows XP and later

Rpcexts.dll

+ +  + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +Remarks +------- + +This extension displays the per-thread RPC information. A field in the per-thread RPC information is the extended error information for this thread. + +Here is an example: + +``` +0:001> !rpcexts.thread 7ffdd000 +RPC TLS at 692e70 + +HandleToThread - 0x6c +SavedProcedure - 0x0 +SavedParameter - 0x0 +ActiveCall - 0x0 +Context - 0x0 +CancelTimeout - 0xffffffff +SecurityContext - 0x0 +ExtendedStatus - 0x0 +ThreadEEInfo - 0xb015f0 +ThreadEvent at - 0x00692E78 +fCallCancelled - 0x0 +buffer cache array at - 0x00692E84 +fAsync - 0x0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rpcexts.thread%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rrestart--register-for-restart-.md b/windows-driver-docs-pr/debugger/-rrestart--register-for-restart-.md new file mode 100644 index 0000000000..15a406fc51 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rrestart--register-for-restart-.md @@ -0,0 +1,47 @@ +--- +title: .rrestart (Register for Restart) +description: The .rrestart command registers the debugging session for restart in case of a reboot or an application failure. +ms.assetid: 8984DBD8-380D-4EB2-95B1-16764153FCF7 +keywords: [".rrestart (Register for Restart) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .rrestart (Register for Restart) +api_type: +- NA +--- + +# .rrestart (Register for Restart) + + +The **.rrestart** command registers the debugging session for restart in case of a reboot or an application failure. + +``` +.rrestart +``` + +Remarks +------- + +This command does not work for elevated debugger sessions. + +## See also + + +[**.urestart**](-urestart--unregister-for-restart-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.rrestart%20%28Register%20for%20Restart%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-rsdt.md b/windows-driver-docs-pr/debugger/-rsdt.md new file mode 100644 index 0000000000..b64c5d45b3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rsdt.md @@ -0,0 +1,49 @@ +--- +title: rsdt +description: The rsdt extension displays the ACPI Root System Description Table. +ms.assetid: e6576028-0982-4021-a0c9-4baecd6533e4 +keywords: ["rsdt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rsdt +api_type: +- NA +--- + +# !rsdt + + +The **!rsdt** extension displays the ACPI Root System Description Table. + +Syntax + +``` +!rsdt +``` + +## + + +### DLL + +Kdexts.dll + +### Additional Information + +For more information, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rsdt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-rtlavl.md b/windows-driver-docs-pr/debugger/-rtlavl.md new file mode 100644 index 0000000000..7353a0d402 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-rtlavl.md @@ -0,0 +1,84 @@ +--- +title: rtlavl +description: The rtlavl extension displays the entries of an RTL_AVL_TABLE structure. +ms.assetid: b1e19b13-8bb6-4f40-8d51-368fafc38ebc +keywords: ["avl tables", "rtlavl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rtlavl +api_type: +- NA +--- + +# !rtlavl + + +The **!rtlavl** extension displays the entries of an RTL\_AVL\_TABLE structure. + +``` +!rtlavl Address [Module!Type] +!rtlavl -? +``` + +## Parameters + + + *Address* +Specifies the address of the RTL\_AVL\_TABLE to display. + + *Module* +Specifies the module in which the data structure is defined. + + *Type* +Specifies the name of a data structure. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +Use the [**!gentable**](-gentable.md) extension to display AVL tables. + +Remarks +------- + +Including the *Module***!***Type* option causes each entry in the table to be interpreted as having the given type. + +The display can be interrupted at any time by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD or CDB). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!rtlavl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ruleinfo.md b/windows-driver-docs-pr/debugger/-ruleinfo.md new file mode 100644 index 0000000000..ac34beb377 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ruleinfo.md @@ -0,0 +1,117 @@ +--- +title: ruleinfo +description: The ruleinfo command displays information about a Driver Verifier rule. +ms.assetid: 025FAAFA-7A5C-462C-9CC2-AA55530CD371 +keywords: ["ruleinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ruleinfo +api_type: +- NA +--- + +# !ruleinfo + + +The **!ruleinfo** command displays information about a Driver Verifier rule. + +``` +!ruleinfo RuleId [RuleState [SubState]] +``` + +## Parameters + + + *RuleId* +The ID of the verifier rule. This is the first argument of the [**DRIVER\_VERIFIER\_DETECTED\_VIOLATION**](bug-check-0xc4--driver-verifier-detected-violation.md) bug check. + + *RuleState* +Additional state information about the violation. This is the third argument of the **DRIVER\_VERIFIER\_DETECTED\_VIOLATION** bug check. + + *SubState* +Sub-state information about the violation. This is the fourth argument of the **DRIVER\_VERIFIER\_DETECTED\_VIOLATION** bug check. + +### DLL + +ext.dll + +Remarks +------- + +This command applies only to rules in the Driver Verifier extension; that is, rules that have an ID greater than or equal to 0x10000. + +The following example shows the four arguments of a [**DRIVER\_VERIFIER\_DETECTED\_VIOLATION**](bug-check-0xc4--driver-verifier-detected-violation.md) bug check. + +``` +DRIVER_VERIFIER_DETECTED_VIOLATION (c4) +... +Arguments: +Arg1: 0000000000091001, ID of the 'NdisOidComplete' rule that was violated. +Arg2: fffff800002d49d0, A pointer to the string describing the violated rule condition. +Arg3: ffffe000027b8370, Address of internal rule state (second argument to !ruleinfo). +Arg4: ffffe000027b83f8, Address of supplemental states (third argument to !ruleinfo). + +## Debugging Details: + + +DV_VIOLATED_CONDITION: This OID should only be completed with NDIS_STATUS_NOT_ACCEPTED, + NDIS_STATUS_SUCCESS, or NDIS_STATUS_PENDING. + +DV_MSDN_LINK: http://go.microsoft.com/fwlink/p/?linkid=278802 + +DRIVER_OBJECT: ffffe0000277a2b0 +... + +STACK_TEXT: +ffffd000`2118ff58 fffff803`4c83afa2 : 00000000`000000c4 00000000`00000001 ... +ffffd000`2118ff60 fffff803`4c83a8c0 : 00000000`00000003 00000000`00091001 ... +... + +STACK_COMMAND: kb + +FOLLOWUP_NAME: Xxxx + +FAILURE_BUCKET_ID: Xxxx +... +``` + +In the preceding output, the rule ID (0x91001) is shown as Arg1. Arg3 and Arg4 are the addresses of rule state and substate information. You can pass the rule ID, the rule state, and the substate to **!ruleinfo** to get a description of the rule and a link to detailed documentation of the rule. + +``` +3: kd> !ruleinfo 0x91001 0xffffe000027b8370 0xffffe000027b83f8 + +RULE_ID: 0x91001 + +RULE_NAME: NdisOidComplete + +RULE_DESCRIPTION: +This rule verifies if an NDIS miniport driver completes an OID correctly. +Check RULE_STATE for Oid ( use !ndiskd.oid ), which can be one of the following: +1) NULL, +2) Pending OID, or +3) Previous OID if no OID is pending. + +MSDN_LINK: http://go.microsoft.com/fwlink/p/?linkid=278802 + +CONTEXT: Miniport 0xFFFFE0000283F1A0 + +CURRENT_TIME (Timed Rules): 142 seconds + +RULE_STATE: 0xFFFFE000027B83F8 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ruleinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-runaway.md b/windows-driver-docs-pr/debugger/-runaway.md new file mode 100644 index 0000000000..88a3137cce --- /dev/null +++ b/windows-driver-docs-pr/debugger/-runaway.md @@ -0,0 +1,110 @@ +--- +title: runaway +description: The runaway extension displays information about the time consumed by each thread. +ms.assetid: ea318d5b-60c6-4d1c-80c7-6bc418ad01ab +keywords: ["runaway Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- runaway +api_type: +- NA +--- + +# !runaway + + +The **!runaway** extension displays information about the time consumed by each thread. + +``` +!runaway [Flags] +``` + +## Parameters + + + *Flags* +Specifies the kind of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x1. + +Bit 0 (0x1) +Causes the debugger to show the amount of user time consumed by each thread. + +Bit 1 (0x2) +Causes the debugger to show the amount of kernel time consumed by each thread. + +Bit 2 (0x4) +Causes the debugger to show the amount of time that has elapsed since each thread was created. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Uext.dll +Ntsdexts.dll

Windows XP and later

+Uext.dll +Ntsdexts.dll
+ +  + +The **!runaway** extension can only be used during live debugging or when debugging crash dump files created by [**.dump /mt**](-dump--create-dump-file-.md) or **.dump /ma**. + +### Additional Information + +For information about threads in user mode, see [Controlling Processes and Threads](controlling-processes-and-threads.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +This extension is a quick way to find out which threads are spinning out of control or consuming too much CPU time. + +The display identifies each thread by the debugger's internal thread numbering and by the thread ID in hexadecimal. The debugger IDs are also shown. + +Here is an example: + +``` +0:001> !runaway 7 + + User Mode Time + Thread Time + 0:55c 0:00:00.0093 + 1:1a4 0:00:00.0000 + + Kernel Mode Time + Thread Time + 0:55c 0:00:00.0140 + 1:1a4 0:00:00.0000 + + Elapsed Time + Thread Time + 0:55c 0:00:43.0533 + 1:1a4 0:00:25.0876 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!runaway%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-running.md b/windows-driver-docs-pr/debugger/-running.md new file mode 100644 index 0000000000..62029ca848 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-running.md @@ -0,0 +1,123 @@ +--- +title: running +description: The running extension displays a list of running threads on all processors of the target computer. +ms.assetid: 08fd9806-36e9-4589-bf92-87dc02efebac +keywords: ["running Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- running +api_type: +- NA +--- + +# !running + + +The **!running** extension displays a list of running threads on all processors of the target computer. + +``` +!running [-i] [-t] +``` + +## Parameters + + + **-i** +Causes the display to include idle processors as well. + + **-t** +Causes a stack trace to be displayed for each processor. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For more information about debugging multiprocessor computers, see [Multiprocessor Syntax](multiprocessor-syntax.md). + +Remarks +------- + +With no options, **!running** will display the affinity of all active processors and all idle processors. For all active processors, it will also display the current and next thread fields from the process control block (PRCB) and the state of the 16 built-in queued spin locks. + +Here is an example from a multiprocessor Itanium system: + +``` +0: kd> !running + +System Processors 3 (affinity mask) + Idle Processors 0 + + Prcb Current Next + 0 e0000000818f8000 e0000000818f9e50 e0000000866f12f0 ................ + 1 e000000086f16010 e00000008620ebe0 e000000086eddbc0 .O.............. +``` + +The 16 characters at the end of each line indicate the built-in queued spin locks (the LockQueue entries in the PRCB). A period ( . ) indicates that the lock is not in use, **O** means the lock is owned by this processor, and **W** means the processor is queued for the lock. To see more information about the spin lock queue, use [**!qlocks**](-qlocks.md). + +Here is an example that shows active and idle processors, along with their stack traces: + +``` +0: kd> !running -it + +System Processors f (affinity mask) + Idle Processors f +All processors idle. + + Prcb Current Next + 0 ffdff120 805495a0 ................ + +ChildEBP RetAddr +8053e3f0 805329c2 nt!RtlpBreakWithStatusInstruction +8053e3f0 80533464 nt!_KeUpdateSystemTime+0x126 +ffdff980 ffdff980 nt!KiIdleLoop+0x14 + + 1 f87e0120 f87e2e60 ................ + +ChildEBP RetAddr +f87e0980 f87e0980 nt!KiIdleLoop+0x14 + + 2 f87f0120 f87f2e60 ................ + +ChildEBP RetAddr +f87f0980 f87f0980 nt!KiIdleLoop+0x14 + + 3 f8800120 f8802e60 ................ + +ChildEBP RetAddr +f8800980 f8800980 nt!KiIdleLoop+0x14 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!running%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-s--change-current-processor-.md b/windows-driver-docs-pr/debugger/-s--change-current-processor-.md new file mode 100644 index 0000000000..701746ea0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-s--change-current-processor-.md @@ -0,0 +1,95 @@ +--- +title: ~s (Change Current Processor) +description: The ~s command sets which processor is debugged on a multiprocessor system.In kernel mode, ~s changes the current processor. +ms.assetid: bd036a25-1e3c-4b57-9c7c-5f1730008cd7 +keywords: ["Change Current Processor (~s) command", "multiprocessor computer, Change Current Processor (~s) command", "processors", "~s (Change Current Processor) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~s (Change Current Processor) +api_type: +- NA +--- + +# ~s (Change Current Processor) + + +The **~s** command sets which processor is debugged on a multiprocessor system. + +In kernel mode, **~s** changes the current processor. Do not confuse this command with the [**~s (Set Current Thread)**](-s--set-current-thread-.md) command (which works only in user mode), the [**|s (Set Current Process)**](-s--set-current-process-.md) command, the [**||s (Set Current System)**](--s--set-current-system-.md) command, or the [**s (Search Memory)**](s--search-memory-.md) command. + +``` +~Processor s +``` + +## Parameters + + + *Processor* +Specifies the number of the processor to debug. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +You can specify processors only in kernel mode. In user mode, the tilde (~) refers to a thread. + +You can immediately tell when you are working on a multiple processor system by the shape of the kernel debugging prompt. In the following example, 0: means that you are debugging the first processor in the computer. + +``` +0: kd> +``` + +Use the following command to switch between processors: + +``` +0: kd> ~1s +1: kd> +``` + +Now the second processor in the computer that is being debugged. + +## See also + + +[Multiprocessor Syntax](multiprocessor-syntax.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~s%20%28Change%20Current%20Processor%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-s--set-current-process-.md b/windows-driver-docs-pr/debugger/-s--set-current-process-.md new file mode 100644 index 0000000000..1c2662191a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-s--set-current-process-.md @@ -0,0 +1,83 @@ +--- +title: s (Set Current Process) +description: The s command sets or displays the current process number. +ms.assetid: 6b4d8e00-426c-496b-9c52-c60faeb0c975 +keywords: ["s (Set Current Process) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- s (Set Current Process) +api_type: +- NA +--- + +# |s (Set Current Process) + + +The **|s** command sets or displays the current process number. + +Do not confuse this command with the [**s (Search Memory)**](s--search-memory-.md), [**~s (Change Current Processor)**](-s--change-current-processor-.md), [**~s (Set Current Thread)**](-s--set-current-thread-.md), or [**||s (Set Current System)**](--s--set-current-system-.md) command. + +``` +|Process s +| s +``` + +## Parameters + + + *Process* +Specifies the process to set or display. For more information about the syntax, see [Process Syntax](process-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about other methods of displaying or controlling processes and threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify processes only in user mode. + +If you use the **|s** syntax, the debugger displays information about the current process. + +This command also disassembles the current instruction for the current system, process, and thread. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20|s%20%28Set%20Current%20Process%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-s--set-current-thread-.md b/windows-driver-docs-pr/debugger/-s--set-current-thread-.md new file mode 100644 index 0000000000..3fff6809f2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-s--set-current-thread-.md @@ -0,0 +1,83 @@ +--- +title: ~s (Set Current Thread) +description: The ~s command sets or displays the current thread number. +ms.assetid: 689d578b-8d31-4049-a374-19ae94d452a9 +keywords: ["~s (Set Current Thread) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~s (Set Current Thread) +api_type: +- NA +--- + +# ~s (Set Current Thread) + + +The **~s** command sets or displays the current thread number. + +In user mode, **~s** sets the current thread. Do not confuse this command confused with the [**~s (Change Current Processor)**](-s--change-current-processor-.md) command (which works only in kernel mode), the [**|s (Set Current Process)**](-s--set-current-process-.md) command, the [**||s (Set Current System)**](--s--set-current-system-.md) command, or the [**s (Search Memory)**](s--search-memory-.md) command. + +``` +~Thread s +~ s +``` + +## Parameters + + + *Thread* +Specifies the thread to set or display. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information and other methods of displaying or controlling processes and threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +If you use the **~s** syntax, the debugger displays information about the current thread. + +This command also disassembles the current instruction for the current system, process, and thread. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~s%20%28Set%20Current%20Thread%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scm.md b/windows-driver-docs-pr/debugger/-scm.md new file mode 100644 index 0000000000..71cacac6f2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scm.md @@ -0,0 +1,74 @@ +--- +title: scm +description: The scm extension displays the specified shared cache map. +ms.assetid: 4333ee14-ca28-43af-b132-210996328af2 +keywords: ["shared cache map", "cache manager", "scm Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- scm +api_type: +- NA +--- + +# !scm + + +The **!scm** extension displays the specified shared cache map. + +``` +!scm Address +``` + +## Parameters + + + *Address* +Specifies the address of the shared cache map. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +For information about cache management, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +For information about other cache management extensions, see the [**!cchelp**](-cchelp.md) extension. + +Remarks +------- + +In Windows XP and later versions of Windows, use the [**dt nt!\_SHARED\_CACHE\_MAP Address**](dt--display-type-.md) command instead of **!scm**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!scm%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scriptlist--list-loaded-scripts-.md b/windows-driver-docs-pr/debugger/-scriptlist--list-loaded-scripts-.md new file mode 100644 index 0000000000..c2b4618609 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scriptlist--list-loaded-scripts-.md @@ -0,0 +1,95 @@ +--- +title: .scriptlist (List Loaded Scripts) +description: The .scriptlist command lists the loaded scripts. +ms.assetid: 98F24BE6-3F34-44E7-9546-3D5AB6D521DD +keywords: [".scriptlist (List Loaded Scripts) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scriptlist (List Loaded Scripts) +api_type: +- NA +--- + +# .scriptlist (List Loaded Scripts) + + +The **.scriptlist** command lists the loaded scripts. + +``` +.scriptlist +``` + +## Parameters + + + +None + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The .scriptlist command will list any scripts which have been loaded via the .scriptload command. + +If the TestScript was successfully loaded using .scriptload, the .scriptlist command would display the name of the loaded script. + +``` +0:000> .scriptlist +Command Loaded Scripts: + JavaScript script from 'C:\WinDbg\Scripts\TestScript.js' +``` + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +## See also + + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +[**.scriptload (Load Script)**](-scriptload--load-script-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scriptlist%20%28List%20Loaded%20Scripts%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-scriptload--load-script-.md b/windows-driver-docs-pr/debugger/-scriptload--load-script-.md new file mode 100644 index 0000000000..233f27bb33 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scriptload--load-script-.md @@ -0,0 +1,111 @@ +--- +title: .scriptload (Load Script) +description: The .scriptload command will load and execute the specified script file. +ms.assetid: 1D4C9587-1491-4D34-9D09-45587B272641 +keywords: [".scriptload (Load Script) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scriptload (Load Script) +api_type: +- NA +--- + +# .scriptload (Load Script) + + +The **.scriptload** command will load and execute the specified script file. + +``` +.scriptload ScriptFile +``` + +## Parameters + + + *ScriptFile* +Specifies the name of the script file to load. *ScriptFile* should include the .js file name extension. Absolute or relative paths can be used. Relative paths are relative to the directory that you started the debugger in. File paths containing spaces are not supported. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The .scriptload command will load a script and execute a script. The following command shows the successful load of TestScript.js. + +``` +0:000> .scriptload C:\WinDbg\Scripts\TestScript.js +JavaScript script successfully loaded from 'C:\WinDbg\Scripts\TestScript.js' +``` + +If there are any errors in the initial load and execution of the script, the errors will be displayed to console, including the line number and error message. + +``` +0:000:x86> .scriptload C:\WinDbg\Scripts\TestScript.js +0:000> "C:\WinDbg\Scripts\TestScript.js" (line 11 (@ 1)): Error (0x80004005): Syntax error +Error: Unable to execute JavaScript script 'C:\WinDbg\Scripts\TestScript.js' +``` + +The .scriptload command will execute the following in a JavaScript. + +- root code +- intializeScript function (if present in the script) + +When a script is loaded using the .scriptload command, the intializeScript function and the root code of the script is executed, the names which are present in the script are bridged into the root namespace of the debugger (dx Debugger) and the script stays resident in memory until it is unloaded and all references to its objects are released. + +The script can provide new functions to the debugger's expression evaluator, modify the object model of the debugger, or can act as a visualizers in much the same way that a NatVis visualizer does. For more information about NavVis and the debugger, see [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md). + +For more information about working with JavaScript, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). For more information about the debugger objects, see [Native Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md). + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +## See also + + +[**.scriptunload (Unload Script)**](-scriptunload--unload-script-.md) + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scriptload%20%28Load%20Script%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-scriptproviders--list-script-providers-.md b/windows-driver-docs-pr/debugger/-scriptproviders--list-script-providers-.md new file mode 100644 index 0000000000..ce1aec37b7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scriptproviders--list-script-providers-.md @@ -0,0 +1,96 @@ +--- +title: .scriptproviders (List Script Providers) +description: The .scriptproviders command lists the active script providers. +ms.assetid: DF2FAA60-422F-4600-9E31-0F8EF127E5A9 +keywords: [".scriptproviders (List Script Providers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scriptproviders (List Script Providers) +api_type: +- NA +--- + +# .scriptproviders (List Script Providers) + + +The **.scriptproviders** command lists the active script providers. + +``` +.scriptproviders +``` + +## Parameters + + + +None + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The .scriptproviders command will list all the script languages which are presently understood by the debugger and the extension under which they are registered. Any file ending in ".NatVis" is understood as a NatVis script and any file ending in ".js" is understood as a JavaScript script. Either type of script can be loaded with the .scriptload command. + +In the example below, the JavaScript and NatVis providers are loaded. + +``` +0:000> .scriptproviders +Available Script Providers: + NatVis (extension '.NatVis') + JavaScript (extension '.js') +``` + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +## See also + + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +[**.scriptload (Load Script)**](-scriptload--load-script-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scriptproviders%20%28List%20Script%20Providers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-scriptrun--run-script-.md b/windows-driver-docs-pr/debugger/-scriptrun--run-script-.md new file mode 100644 index 0000000000..8c922c9e55 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scriptrun--run-script-.md @@ -0,0 +1,166 @@ +--- +title: .scriptrun (Run Script) +description: The .scriptrun command will load and run a JavaScript. +ms.assetid: 6481B852-F0B4-4B02-BF7F-81DA21457A40 +keywords: [".scriptrun (Run Script) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scriptrun (Run Script) +api_type: +- NA +--- + +# .scriptrun (Run Script) + + +The .scriptrun command will load and run a JavaScript. + +``` +.scriptrun ScriptFile +``` + +## Parameters + + + *ScriptFile* +Specifies the name of the script file to load and execute. *ScriptFile* should include the .js file name extension. Absolute or relative paths can be used. Relative paths are relative to the directory that you started the debugger in. File paths containing spaces are not supported. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The .scriptrun command will load a script and, execute the following code. + +- root +- intializeScript +- invokeScript + +A confirmation message is displayed when the code is loaded and executed. + +``` +0:000> .scriptrun C:\WinDbg\Scripts\helloWorld.js +JavaScript script successfully loaded from 'C:\WinDbg\Scripts\helloWorld.js' +Hello World! We are in JavaScript! +``` + +Any object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content. + +This table summarizes which functions are executed by .scriptload and .scriptrun. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[.scriptload](-scriptload--load-script-.md).scriptrun
rootyesyes
initializeScriptyesyes
invokeScriptyes
uninitializeScript
+ +  + +You can use this code to see which functions are called with the .script run command. + +``` +// Root of Script +host.diagnostics.debugLog("***>; Code at the very top (root) of the script is always run \n"); + + +function initializeScript() +{ + // Add code here that you want to run everytime the script is loaded. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***>; initializeScript was called \n"); +} + +function invokeScript() +{ + // Add code here that you want to run everytime the script is executed. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***>; invokeScript was called \n"); +} + + +``` + +For more information about working with JavaScript, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). For more information about the debugger objects, see [Native Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md). + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider dll. + +``` +0:000> .load C:\ScriptProviders\jsprovider.dll +``` + +## See also + + +[**.scriptload (Load Script)**](-scriptload--load-script-.md) + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scriptrun%20%28Run%20Script%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-scriptunload--unload-script-.md b/windows-driver-docs-pr/debugger/-scriptunload--unload-script-.md new file mode 100644 index 0000000000..fc2ef5132c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scriptunload--unload-script-.md @@ -0,0 +1,96 @@ +--- +title: .scriptunload (Unload Script) +description: The .scriptunload command unloads the specified script. +ms.assetid: 015703C2-31E2-46B4-8F89-1EA52DB7E6FC +keywords: [".scriptunload (Unload Script) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scriptunload (Unload Script) +api_type: +- NA +--- + +# .scriptunload (Unload Script) + + +The **.scriptunload** command unloads the specified script. + +``` +.scriptunload ScriptFile +``` + +## Parameters + + + *ScriptFile* +Specifies the name of the script file to unload. *ScriptFile* should include the .js file name extension. Absolute or relative paths can be used. Relative paths are relative to the directory that you started the debugger in. File paths containing spaces are not supported. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The .scriptunload command unloads a loaded script. Use the following command syntax to unload a script + +``` +0:000:x86> .scriptunload C:\WinDbg\Scripts\TestScript.js +JavaScript script unloaded from 'C:\WinDbg\Scripts\TestScript.js' +``` + +If there are outstanding references to objects in a script, the contents of the script will be unlinked but the script may remain in memory until all such references are released. + +For more information about working with JavaScript, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). For more information about the debugger objects, see [Native Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md). + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider dll. + +``` +0:000> .load C:\ScriptProviders\jsprovider.dll +``` + +## See also + + +[**.scriptload (Load Script)**](-scriptload--load-script-.md) + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scriptunload%20%28Unload%20Script%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-scroll-prefs--control-source-scrolling-preferences-.md b/windows-driver-docs-pr/debugger/-scroll-prefs--control-source-scrolling-preferences-.md new file mode 100644 index 0000000000..0385f7c51b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scroll-prefs--control-source-scrolling-preferences-.md @@ -0,0 +1,78 @@ +--- +title: .scroll_prefs (Control Source Scrolling Preferences) +description: The .scroll_prefs command controls the positioning of the source in a Source window when scrolling to a line. +ms.assetid: 08978751-c4b7-491a-9e1f-de21d74a10a8 +keywords: [".scroll_prefs (Control Source Scrolling Preferences) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .scroll_prefs (Control Source Scrolling Preferences) +api_type: +- NA +--- + +# .scroll\_prefs (Control Source Scrolling Preferences) + + +The **.scroll\_prefs** command controls the positioning of the source in a Source window when scrolling to a line. + +``` +.scroll_prefs Before After +.scroll_prefs +``` + +## Parameters + + + *Before* +Specifies how many source lines before the line you are scrolling to should be visible in the Source window. + + *After* +Specifies how many source lines after the line you are scrolling to should be visible in the Source window. + +### Environment + +This command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +When this command is used with no parameters, the current source scrolling preferences are displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.scroll_prefs%20%28Control%20Source%20Scrolling%20Preferences%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scsikd-classext.md b/windows-driver-docs-pr/debugger/-scsikd-classext.md new file mode 100644 index 0000000000..9f555a579f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scsikd-classext.md @@ -0,0 +1,85 @@ +--- +title: scsikd.classext +description: The scsikd.classext extension displays the specified class Plug and Play (PnP) device. +ms.assetid: 2b56966c-7ae1-4d44-ad60-19f31e47efff +keywords: ["scsikd.classext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- scsikd.classext +api_type: +- NA +--- + +# !scsikd.classext + + +The **!scsikd.classext** extension displays the specified class Plug and Play (PnP) device. + +``` +!scsikd.classext [Device [Level]] +``` + +## Parameters + + + *Device* +Specifies the device object or device extension of a class PnP device. If *Device* is omitted, a list of all class PnP extensions is displayed. + + *Level* +Specifies the amount of detail to display. This parameter can take 0, 1, or 2 as values, with 2 giving the most detail. The default is 0. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Scsikd.dll

Windows XP and later

Scsikd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +Here is an example of the **!scsikd.classext** display: + +``` +0: kd> !scsikd.classext + ' !scsikd.classext 8633e3f0 ' ( ) "IBM " / "DDYS-T09170M " / "S93E" / " XBY45906" + ' !scsikd.classext 86347b48 ' (paging device) "IBM " / "DDYS-T09170M " / "S80D" / " VDA60491" + ' !scsikd.classext 86347360 ' ( ) "UNISYS " / "003451ST34573WC " / "5786" / "HN0220750000181300L6" + ' !scsikd.classext 861d1898 ' ( ) "" / "MATSHITA CD-ROM CR-177" / "7T03" / "" + + usage: !classext +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!scsikd.classext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scsikd-help.md b/windows-driver-docs-pr/debugger/-scsikd-help.md new file mode 100644 index 0000000000..4465439c73 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scsikd-help.md @@ -0,0 +1,61 @@ +--- +title: scsikd.help +description: The scsikd.help extension displays help text for Scsikd.dll extension commands. +ms.assetid: bae1a20c-7e85-4878-af4c-9840b64aec7b +keywords: ["scsikd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- scsikd.help +api_type: +- NA +--- + +# !scsikd.help + + +The **!scsikd.help** extension displays help text for Scsikd.dll extension commands. + +``` +!scsikd.help +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Scsikd.dll

Windows XP and later

Scsikd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!scsikd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scsikd-scsiext.md b/windows-driver-docs-pr/debugger/-scsikd-scsiext.md new file mode 100644 index 0000000000..79623f9ef5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scsikd-scsiext.md @@ -0,0 +1,134 @@ +--- +title: scsikd.scsiext +description: The scsikd.scsiext extension displays detailed information about the specified SCSI port extension. +ms.assetid: 0fcb0545-eb5a-4500-8e14-a5296624c80b +keywords: ["scsikd.scsiext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- scsikd.scsiext +api_type: +- NA +--- + +# !scsikd.scsiext + + +The **!scsikd.scsiext** extension displays detailed information about the specified SCSI port extension. + +``` +!scsikd.scsiext Device +``` + +## Parameters + + + *Device* +Specifies the device object or device extension of a SCSI port extension. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Scsikd.dll

Windows XP and later

Scsikd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +Remarks +------- + +Here is an example of the **!scsikd.scsiext** display, where the SCSI port extension has been specified by a functional device object (FDO); this can be obtained from the **DO** field or **DevExt** field in the [**!minipkd.adapters**](-minipkd-adapters.md) display: + +``` +kd> !scsikd.scsiext 816f9a40 +Scsiport functional device extension at address 816f9af8 +Common Extension: + Initialized + DO 0x816f9a40 LowerObject 0x816e8030 SRB Flags 00000000 + Current Power (D0,S0) Desired Power D-1 Idle 00000000 + Current PnP state 0x0 Previous state 0xff + DispatchTable f9aee200 UsePathCounts (P0, H0, C0) +Adapter Extension: + Port 2 IsPnp VirtualSlot HasInterrupt + LowerPdo 0x816e8030 HwDevExt 0x8170a004 Active Requests 0xffffffff + MaxBus 0x01 MaxTarget 0x10 MaxLun 0x08 + Port Flags (0x00001000): PD_DISCONNECT_RUNNING + NonCacheExt 0x81702000 IoBase 0x00002000 Int 0x1a + RealBus# 0x0 RealSlot# 0x2 + Timeout 0xffffffff DpcFlags 0x00000000 Sequence 0x00000003 + Srb Ext Header 0x817061a0 No. Requests 0x00000012 + QueueTag BitMap 0x00000000 Hint 0x00000000 + MaxQueueTag 0xfe (@0x816f9c58) + LuExt Size 0x00000038 SrbExt Size 0x00000188 + SG List Size - Small 17 Large 0 + Emergency - SrbData 0x816f9830 Blocked List @0x816f9e94 + CommonBuff - Size: 0x00006000 PA: 0x0000000001702000 VA: 0x81702000 + Ke Objects - Int1: 0x8175ba50 Int2: 0x00000000 Dma: 0x816f9340 + Lookaside - SrbData @ 0x816f9e40 SgList @0x00000000 Remove: @0x00000000 + Resources - Raw: 0x817ba190 Translated: 0x81709678 + Port Config 8177fde8 + DeviceMap Handles: Port 0000009c Busses e12d7b38 + Interrupt Data @0x816f9ce4: + Flags (0x00000000): + Ready LUN 0x00000000 Wmi Events 0x00000000 + Completed Request List (@0x816f9ce8): 0 entries + LUN 816ea0e8 @ ( 0, 1, 0) c ev pnp(00/ff) pow(0 ,0) DevObj 816ea030 +``` + +Here is an example of the **!scsikd.scsiext** display, where the SCSI port extension has been specified by a physical device object (PDO); this can be obtained from the **DevObj** field or **LUN** field in the [**!minipkd.adapters**](-minipkd-adapters.md) display: + +``` +kd> !scsikd.scsiext 816ea030 +Scsiport physical device extension at address 816ea0e8 +Common Extension: + Initialized + DO 0x816ea030 LowerObject 0x816f9a40 SRB Flags 00000000 + Current Power (D0,S0) Desired Power D-1 Idle 0x8176c780 + Current PnP state 0x0 Previous state 0xff + DispatchTable f9aee180 UsePathCounts (P0, H0, C0) +Logical Unit Extension: + Address (2, 0, 1, 0) Claimed Enumerated Visible + LuFlags (0x00000000): + Retry 0x00 Key 0x00000000 + Lock 0x00000000 Pause 0x00000000 CurrentLock: 0x00000000 + HwLuExt 0x8177ce10 Adapter 0x816f9af8 Timeout 0xffffffff + NextLun 0x00000000 ReadyLun 0x00000000 + Pending 0x00000000 Busy 0x00000000 Untagged 0x00000000 + Q Depth 000 (1628450047) InquiryData 0x816ea206 + DeviceMap Keys: Target 0x0000d0 Lun 00000000 + Bypass SRB_DATA blocks 4 @ 816ea270 List 816ea810 + RS Irp 8177dd80 Srb @ 816eaa0c MDL @ 816eaa4c + Request List @0x816ea1f0 is empty +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!scsikd.scsiext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-scsikd-srbdata.md b/windows-driver-docs-pr/debugger/-scsikd-srbdata.md new file mode 100644 index 0000000000..a0d45e146f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-scsikd-srbdata.md @@ -0,0 +1,67 @@ +--- +title: scsikd.srbdata +description: The scsikd.srbdata extension displays the specified SRB_DATA tracking block. +ms.assetid: 9c0ba4d9-124f-4e86-a0e1-7f8796b6571a +keywords: ["scsikd.srbdata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- scsikd.srbdata +api_type: +- NA +--- + +# !scsikd.srbdata + + +The **!scsikd.srbdata** extension displays the specified SRB\_DATA tracking block. + +``` +!scsikd.srbdata Address +``` + +## Parameters + + + *Address* +Specifies the address of an SRB\_DATA tracking block. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Scsikd.dll

Windows XP and later

Scsikd.dll

+ +  + +### Additional Information + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!scsikd.srbdata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sd.md b/windows-driver-docs-pr/debugger/-sd.md new file mode 100644 index 0000000000..74306109e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sd.md @@ -0,0 +1,90 @@ +--- +title: sd +description: The sd extension displays the security descriptor at the specified address. +ms.assetid: 67c72bdb-7bfc-42d6-9b65-31a07dc67729 +keywords: ["sd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sd +api_type: +- NA +--- + +# !sd + + +The **!sd** extension displays the security descriptor at the specified address. + +Syntax + +``` +!sd Address [Flags] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the SECURITY\_DESCRIPTOR structure. + + *Flags* +If this is set to 1, the friendly name is displayed. This includes the security identifier (SID) type, as well as the domain and user name for the SID. + +### DLL + +Exts.dll + +### Additional Information + +For an application and an example of this command, see [Determining the ACL of an Object](determining-the-acl-of-an-object.md). For information about security descriptors, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. Also see [**!sid**](-sid.md) and [**!acl**](-acl.md). + +Remarks +------- + +Here is an example: + +``` +kd> !sd e1a96a80 1 +->Revision: 0x1 +->Sbz1 : 0x0 +->Control : 0x8004 + SE_DACL_PRESENT + SE_SELF_RELATIVE +->Owner : S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser) +->Group : S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users) +->Dacl : +->Dacl : ->AclRevision: 0x2 +->Dacl : ->Sbz1 : 0x0 +->Dacl : ->AclSize : 0x40 +->Dacl : ->AceCount : 0x2 +->Dacl : ->Sbz2 : 0x0 +->Dacl : ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +->Dacl : ->Ace[0]: ->AceFlags: 0x0 +->Dacl : ->Ace[0]: ->AceSize: 0x24 +->Dacl : ->Ace[0]: ->Mask : 0x001f0003 +->Dacl : ->Ace[0]: ->SID: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser) + +->Dacl : ->Ace[1]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +->Dacl : ->Ace[1]: ->AceFlags: 0x0 +->Dacl : ->Ace[1]: ->AceSize: 0x14 +->Dacl : ->Ace[1]: ->Mask : 0x001f0003 +->Dacl : ->Ace[1]: ->SID: S-1-5-18 (Well Known Group: NT AUTHORITY\SYSTEM) + +->Sacl : is NULL +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-search.md b/windows-driver-docs-pr/debugger/-search.md new file mode 100644 index 0000000000..345cd6c32c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-search.md @@ -0,0 +1,120 @@ +--- +title: search +description: The search extension searches pages in physical memory for pointer-sized data that matches the specified criteria. +ms.assetid: 5f9d4e50-c389-4309-8851-0f5069b1b66e +keywords: ["search Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- search +api_type: +- NA +--- + +# !search + + +The **!search** extension searches pages in physical memory for pointer-sized data that matches the specified criteria. + +Syntax + +``` +!search [-s] [-p] Data [ Delta [ StartPFN [ EndPFN ]]] +!search -? +``` + +## Parameters + + + **-s** +Causes symbol check errors to be ignored during the search. This is useful if you are getting too many "incorrect symbols for kernel" errors. + + **-p** +Causes the value of *Data* to be interpreted as a 32-bit value, preventing any sign extension. + + *Data* +Specifies the data to search for. *Data* must be the size of a pointer on the target system (32 bits or 64 bits). An exact match for the value of *Data* is always displayed. Other matches are displayed as well, depending on the value of *Delta*; see the Remarks section below for details. + + *Delta* +Specifies the allowable difference between a value in memory and the value of *Data*. See the Remarks section below for details. + + *StartPFN* +Specifies the page frame number (PFN) of the beginning of the range to be searched. If this is omitted, the search begins at the lowest physical page. + + *EndPFN* +Specifies the page frame number (PFN) of the end of the range to be searched. If this is omitted, the search ends at the highest physical page. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + +Kdexts.dll + +### Additional Information + +For more ways to display and search physical memory, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +If *StartPFN* and *EndPFN* are specified, these are taken as the page frame numbers of the beginning and end of the range in physical memory to be searched. For an explanation of page frame numbers, see [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md). If *StartPFN* and *EndPFN* are omitted, all physical memory is searched. + +All hits are displayed. + +The **!search** extension will search through all memory for in the specified page range and examine each ULONG\_PTR-aligned value. Values that satisfy at least one of the following criteria are displayed: + +- The value matches *Data* exactly. + +- If Delta is 0 or omitted: The value differs from *Data* by a single bit. + +- If Delta is nonzero: The value differs from *Data* by at most *Delta*. In other words, the value lies in the range \[Data - Delta, Data + Delta\]. + +- If Delta is nonzero: The value differs from the lowest number in the range (Data - Delta) by a single bit. + +In most cases, *Data* will specify an address you are interested in, but any ULONG\_PTR sized data can be specified. + +Because the debugger's search engine structures reside in memory on the target computer, if you search all of memory (or any range containing these structures) you will see matches in the area where the structures themselves are located. If you need to eliminate these matches, do a search for a random value; this will indicate where the debugger's search structures are located. + +Here are some examples. The following will search the memory page with PFN 0x237D for values between 0x80001230 and 0x80001238, inclusive: + +``` +kd> !search 80001234 4 237d 237d +``` + +The following will search the memory pages ranging from PFN 0x2370 to 0x237F for values that are within one bit of 0x0F100F0F. The exact matches are indicated in bold; the others are off by one bit: + +``` +kd> !search 0f100f0f 0 2370 237f +Searching PFNs in range 00002370 - 0000237F for [0F100F0F - 0F100F0F] + +Pfn Offset Hit Va Pte +- - - - - - - - - - - - - - - - - - - +0000237B 00000368 0F000F0F 01003368 C0004014 +0000237C 00000100 0F100F0F 01004100 C0004014 +0000237D 000003A8 0F100F0F 010053A8 C0004014 +0000237D 000003C8 0F100F8F 010053C8 C0004014 +0000237D 000003E8 0F100F0F 010053E8 C0004014 +0000237D 00000408 0F100F0F 01005408 C0004014 +0000237D 00000428 0F100F8F 01005428 C0004014 +Search done. +``` + +The columns in the display are as follows: **Pfn** is the page frame number (PFN) of the page; **Offset** is the offset on that page; **Hit** is the value at that address; **Va** is the virtual address mapped to this physical address (if this exists and can be determined); **Pte** is the page table entry (PTE). + +To calculate the physical address, shift the PFN left three hexadecimal digits (12 bits) and add the offset. For example, the last line in the table is virtual address 0x0237D000 + 0x428 = 0x02347D428. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!search%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-searchpte.md b/windows-driver-docs-pr/debugger/-searchpte.md new file mode 100644 index 0000000000..60f7701797 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-searchpte.md @@ -0,0 +1,76 @@ +--- +title: searchpte +description: The searchpte extension searches physical memory for the specified page frame number (PFN). +ms.assetid: b9bac11e-605b-4064-b078-d3171b59da3b +keywords: ["searchpte Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- searchpte +api_type: +- NA +--- + +# !searchpte + + +The **!searchpte** extension searches physical memory for the specified page frame number (PFN). + +``` +!searchpte PFN +!searchpte -? +``` + +## Parameters + + + *PFN* +Specifies the PFN in hexadecimal format. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about page tables and page directories, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +To stop execution at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!searchpte%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-secure--activate-secure-mode-.md b/windows-driver-docs-pr/debugger/-secure--activate-secure-mode-.md new file mode 100644 index 0000000000..e7eb972d42 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-secure--activate-secure-mode-.md @@ -0,0 +1,78 @@ +--- +title: .secure (Activate Secure Mode) +description: The .secure command activates or displays the status of Secure Mode. +ms.assetid: 58a8936e-898f-4608-b1b0-399d5152f410 +keywords: [".secure (Activate Secure Mode) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .secure (Activate Secure Mode) +api_type: +- NA +--- + +# .secure (Activate Secure Mode) + + +The **.secure** command activates or displays the status of Secure Mode. + +``` +.secure 1 +.secure +``` + +## + + +### Environment + +Secure Mode can only be enabled while the debugger is dormant. Secure Mode applies only to kernel-mode sessions because, by definition, Secure Mode prevents user-mode debugging operations. + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details, see [Secure Mode](secure-mode.md). + +Remarks +------- + +To activate Secure Mode, use the command **.secure 1** (or **.secure** followed by any nonzero value). + +The command **.secure** will show whether Secure Mode is currently active. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.secure%20%28Activate%20Secure%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sel.md b/windows-driver-docs-pr/debugger/-sel.md new file mode 100644 index 0000000000..600767a237 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sel.md @@ -0,0 +1,29 @@ +--- +title: sel +description: sel +ms.assetid: 0bacc298-c44d-4ab1-a0a4-7bf26b0cf2a6 +keywords: ["sel extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !sel + + +## + + +The **!sel** extension command is obsolete. Use the [**dg (Display Selector)**](dg--display-selector-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sel%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-send-file--send-file-.md b/windows-driver-docs-pr/debugger/-send-file--send-file-.md new file mode 100644 index 0000000000..faf79743f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-send-file--send-file-.md @@ -0,0 +1,82 @@ +--- +title: .send_file (Send File) +description: The .send_file command copies files. If you are performing remote debugging through a process server, it sends a file from the smart client's computer to the process server's computer. +ms.assetid: ad12ec46-79a3-458a-acdc-c2ccb06f8c96 +keywords: [".send_file (Send File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .send_file (Send File) +api_type: +- NA +--- + +# .send\_file (Send File) + + +The **.send\_file** command copies files. If you are performing remote debugging through a process server, it sends a file from the smart client's computer to the process server's computer. + +``` +.send_file [-f] Source Destination +.send_file [-f] -s Destination +``` + +## Parameters + + + **-f** +Forces file creation. By default, **.send\_file** will not overwrite any existing files. If the -f switch is used, the destination file will always be created, and any existing file with the same name will be overwritten. + + *Source* +Specifies the full path and filename of the file to be sent. If you are debugging through a process server, this file must be located on the computer where the smart client is running. + + *Destination* +Specifies the directory where the file is to be written. If you are debugging through a process server, this directory name is evaluated on the computer where the process server is running. + + **-s** +Causes the debugger to copy all loaded symbol files. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +This command is particularly useful when you have been performing remote debugging through a process server, but wish to begin debugging locally instead. In this case you can use the .send\_file -s command to copy all the symbol files that the debugger has been using to the process server. These symbol files can then be used by a debugger running on the local computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.send_file%20%28Send%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-server--create-debugging-server-.md b/windows-driver-docs-pr/debugger/-server--create-debugging-server-.md new file mode 100644 index 0000000000..f2d34f7b99 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-server--create-debugging-server-.md @@ -0,0 +1,121 @@ +--- +title: .server (Create Debugging Server) +description: The .server command starts a debugging server, allowing a remote connection to the current debugging session. +ms.assetid: 39979a53-d6e7-4660-8884-3044da0b60de +keywords: ["Create Debugging Server (.server) command", "remote debugging through the debugger, Create Debugging Server (.server) command", ".server (Create Debugging Server) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .server (Create Debugging Server) +api_type: +- NA +--- + +# .server (Create Debugging Server) + + +The **.server** command starts a debugging server, allowing a remote connection to the current debugging session. + +``` +.server npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] +.server tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] +.server tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] +.server com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] +.server spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] +.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] +.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] +``` + +## Parameters + + + *PipeName* +When NPIPE or SPIPE protocol is used, *PipeName* is a string that will serve as the name of the pipe. Each pipe name should identify a unique debugging server. If you attempt to reuse a pipe name, you will receive an error message. *PipeName* must not contain spaces or quotation marks. *PipeName* can include a numerical **printf**-style format code, such as %x or %d. The debugger will replace this with the process ID of the debugger. A second such code will be replaced with the thread ID of the debugger. + + *Socket* +When TCP or SSL protocol is used, *Socket* is the socket port number. + +It is also possible to specify a range of ports separated by a colon. The debugger will check each port in this range to see if it is free. If it finds a free port and no error occurs, the debugging server will be created. The debugging client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the methods described in [**Searching for Debugging Servers**](searching-for-debugging-servers.md); when this debugging server is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the search results will show "port=53:60". (If you are using the **clicon** parameter to establish a reverse connection, the debugging client can specify a range of ports in this manner, while the server must specify the actual port used.) + +**clicon=***Client* +When TCP or SSL protocol is used and the **clicon** parameter is specified, a *reverse connection* will be opened. This means that the debugging server will try to connect to the debugging client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. *Client* specifies the network name of the machine on which the debugging client exists or will be created. The two initial backslashes (\\\) are optional. + +When **clicon** is used, it is best to start the debugging client before the debugging server is created, although the usual order (server before client) is also permitted. A reverse-connection server will not appear when another debugger displays all active servers. + + *COMPort* +When COM protocol is used, *COMPort* specifies the COM port to be used. The prefix COM is optional (for example, both "com2" and "2" are acceptable). + + *BaudRate* +When COM protocol is used, *BaudRate* specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. + + *COMChannel* +If COM protocol is used, *COMChannel* specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254, inclusive. + + *Protocol* +If SSL or SPIPE protocol is used, *Protocol* specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3. + + *Cert* +If SSL or SPIPE protocol is used, *Cert* specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits given by the certificate's snapin). If the syntax **certuser=***Cert* is used, the debugger will look up the certificate in the system store (the default store). If the syntax **machuser=***Cert* is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication. + + **hidden** +Prevents the server from appearing when another debugger displays all active servers. + +**password=***Password* +Requires a debugging client to supply the specified password in order to connect to the debugging session. *Password* can be any alphanumeric string, up to twelve characters in length. + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + + **IcfEnable** +(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When **IcfEnable** is used with a TCP connection, the debugger causes Windows to open the port specified by the Socket parameter. When **IcfEnable** is used with a named pipe connection, the debugger causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For full details on how to start a debugging server, see [**Activating a Debugging Server**](activating-a-debugging-server.md). For examples, see [Client and Server Examples](client-and-server-examples.md). + +Remarks +------- + +This command turns the current debugger into a debugging server. This allows you to start the server after the debugger is already running, whereas the -server [command-line option](command-line-options.md) can only be issued when the debugger is started. + +This permits a debugging client to connect to the current debugging session. Note that it is possible to start multiple servers using different options, allowing different kinds of debugging clients to join the session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.server%20%28Create%20Debugging%20Server%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-servers--list-debugging-servers-.md b/windows-driver-docs-pr/debugger/-servers--list-debugging-servers-.md new file mode 100644 index 0000000000..6bbaec65d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-servers--list-debugging-servers-.md @@ -0,0 +1,77 @@ +--- +title: .servers (List Debugging Servers) +description: The .servers command lists all debugging servers that have been established by this debugger. +ms.assetid: bf65c6f7-9c59-4756-a667-8b896bd7ea2a +keywords: ["List Debugging Servers (.servers) command", "remote debugging through the debugger, List Debugging Servers (.servers) command", ".servers (List Debugging Servers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .servers (List Debugging Servers) +api_type: +- NA +--- + +# .servers (List Debugging Servers) + + +The **.servers** command lists all debugging servers that have been established by this debugger. + +``` +.servers +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For full details on debugging servers, see [Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md). + +Remarks +------- + +The output of the **.servers** command lists all the debugging servers started by the debugger on which this command is issued. The output is formatted so that it can be used literally as the argument for the -remote command-line option or pasted into the WinDbg dialog box. + +Each debugging server is identified by a unique ID. This ID can be used as the argument for the [**.endsrv (End Debugging Server)**](-endsrv--end-debugging-server-.md) command, if you wish to terminate the debugging server. + +The **.servers** command does not list debugging servers started on this computer by different instances of the debugger, nor does it list process servers or KD connection servers. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.servers%20%28List%20Debugging%20Servers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-session.md b/windows-driver-docs-pr/debugger/-session.md new file mode 100644 index 0000000000..0f30bfd57a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-session.md @@ -0,0 +1,66 @@ +--- +title: session +description: The session extension controls the session context. It can also display a list of all user sessions. +ms.assetid: c5f32bf0-59b5-4274-9271-1ad4913ffa1a +keywords: ["session Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- session +api_type: +- NA +--- + +# !session + + +The **!session** extension controls the session context. It can also display a list of all user sessions. + +Syntax + +``` +!session +!session -s DefaultSession +!session -? +``` + +## Parameters + + + **-s** **** *DefaultSession* +Sets the [session context](changing-contexts.md#session-context) to the specified value. If *DefaultSession* is -1, the session context is set to the current session. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about user sessions and the Session Manager (smss.exe), see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +The **!session** extension is used to control the session context. Using **!session** with no parameters will display a list of active sessions on the target computer. Using **!session /s** *DefaultSession* will change the session context to the new default value. + +When you set the session context, the process context is automatically changed to the active process for that session, and the [**.cache forcedecodeptes**](-cache--set-cache-size-.md) option is enabled so that session addresses are translated properly. + +For more details and a list of all the session-related extensions that are affected by the session context, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-setdll--set-default-extension-dll-.md b/windows-driver-docs-pr/debugger/-setdll--set-default-extension-dll-.md new file mode 100644 index 0000000000..562494ac1e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-setdll--set-default-extension-dll-.md @@ -0,0 +1,79 @@ +--- +title: .setdll (Set Default Extension DLL) +description: The .setdll command changes the default extension DLL for the debugger. +ms.assetid: 9dc5cd9e-d4f2-4112-bf3d-f7061c786ddf +keywords: ["Set Default Extension DLL (.setdll) command", "extension commands ( commands), Set Default Extension DLL (.setdll) command", ".setdll (Set Default Extension DLL) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .setdll (Set Default Extension DLL) +api_type: +- NA +--- + +# .setdll (Set Default Extension DLL) + + +The **.setdll** command changes the default extension DLL for the debugger. + +``` +.setdll DLLName +!DLLName.setdll +``` + +## Parameters + + + *DLLName* +The name and path of the extension DLL. If the full path was specified when the DLL was loaded, it needs to be given in full here as well. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details on loading, unloading, and controlling extensions, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). For details on executing extension commands, see [Using Debugger Extension Commands](using-debugger-extension-commands.md). + +Remarks +------- + +The debugger maintains a default extension DLL that is implicitly loaded when the debugger is started. This allows the user to specify an extension command without first having to load an extension DLL. This command allows modification of which DLL is loaded as the default DLL. + +When a command is issued, the debugger looks for it in the default extension first. If a match is not found, all other loaded extension DLLs are searched in the order they were loaded. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.setdll%20%28Set%20Default%20Extension%20DLL%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-settings--set-debug-settings-.md b/windows-driver-docs-pr/debugger/-settings--set-debug-settings-.md new file mode 100644 index 0000000000..1f9c5e7aae --- /dev/null +++ b/windows-driver-docs-pr/debugger/-settings--set-debug-settings-.md @@ -0,0 +1,131 @@ +--- +title: .settings (Set Debug Settings) +description: The .settings command sets, modifies, displays, loads and saves settings in the Debugger.Settings namespace. +ms.assetid: DAD68FA5-21EF-4A5C-8E5E-0C763CD28C44 +keywords: [".settings (Set Debug Settings) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .settings (Set Debug Settings) +api_type: +- NA +--- + +# .settings (Set Debug Settings) + + +The **.settings** command sets, modifies, displays, loads and saves settings in the Debugger.Settings namespace. + +``` +.settings set namespace.setting=value +.settings set namespace.setting+=value +.settings save [file path] +.settings load file path +.settings list [namespace][-v] +.settings help +``` + +## Parameters + + +**.settings set parameters** + + **namespace.setting=value** +Sets or modifies a setting. When specifying file paths use slash escaping, for example C:\\\\Symbols\\\\. + +Examples: + +`.settings set Display.PreferDMLOutput=false` + +`.settings set Sources.DisplaySourceLines=true` + +`.settings set Symbols.Sympath="C:\\Symbols\\"` + + **namespace.setting+=value** +Specifies that the new value will be appended to (rather than replace) the previous value. + +Example: + +`.settings set Extensions.ExtensionSearchPath+=";C:\\MyExtension\\"` + +**.setting save parameters** + + **file path** +Saves all of the values in the Debugger.Settings namespace to the specified XML file. + + **none** +If a file path is not provided, the settings will be saved to the last file that was loaded or saved to. If a previous file does not exist, a file named config.xml will be created in the directory that the debugger executable was loaded from. + +**.setting load parameters** + + **file path** +Loads all the settings from an XML settings file. Loading settings will change only the settings that are defined in that file. Any previously loaded or changed settings that do not appear in that file will not be modified. This file will be treated as your default save path until the next save or load operation. + +**.setting list parameters** + + **namespace** +List all settings in the given namespace and their values. + + **-v** +The –v flag causes a description of the setting to be displayed. + +**.setting help parameters** + + **None** +Lists all of the settings in the Debugger namespace and their description. + + **Namespace** +Lists all settings in the given namespace and their description. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +On launch, the debugger will load all the settings from config.xml in the directory the debugger executable is in. Throughout your debugging session you can modify settings using the previous settings command (like .sympath or .prefer\_dml) or the new .settings commands. You can use ‘.settings save’ to save your settings to your settings configuration file. You can use the following command to enable AutoSave. + +`.settings set AutoSaveSettings=true` + +When auto save is enabled, the settings in the Debugger.Settings namespace will be automatically saved when exiting the debugger. + +Remarks +------- + +You can exchange debug xml settings files with others to duplicate their debug settings. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.settings%20%28Set%20Debug%20Settings%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-shell--command-shell-.md b/windows-driver-docs-pr/debugger/-shell--command-shell-.md new file mode 100644 index 0000000000..844271c88d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-shell--command-shell-.md @@ -0,0 +1,111 @@ +--- +title: .shell (Command Shell) +description: The .shell command launches a shell process and redirects its output to the debugger, or to a specified file. +ms.assetid: 351cbd54-6e1a-4dc1-b0d8-8e61294b0e86 +keywords: ["Command Shell (.shell) command", "MS-DOS Shell (.shell) command", "DOS Shell (.shell) command", "shell commands, Command Shell (.shell) command", ".shell (Command Shell) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .shell (Command Shell) +api_type: +- NA +--- + +# .shell (Command Shell) + + +The **.shell** command launches a shell process and redirects its output to the debugger, or to a specified file. + +``` +.shell [Options] [ShellCommand] +.shell -i InFile [-o OutFile [-e ErrFile]] [Options] ShellCommand +``` + +## Parameters + + + *InFile* +Specifies the path and file name of a file to be used for input. If you intend to offer no input after the initial command, you can specify a single hyphen (-) instead of *InFile*, with no space before the hyphen. + + *OutFile* +Specifies the path and file name of a file to be used for standard output. If **-o** **** *OutFile* is omitted, output is sent to the Debugger Command window. If you do not want this output displayed or saved in a file, you can specify a single hyphen (-) instead of *OutFile*, with no space before the hyphen. + + *ErrFile* +Specifies the path and file name of a file to be used for error output. If -e ErrFile is omitted, error output is sent to the same place as standard output. If you do not want this output displayed or saved in a file, you can specify a single hyphen (-) instead of *ErrFile*, with no space before the hyphen. + + *Options* +Can be any number of the following options: + +**-ci "***Commands***"** +Processes the specified debugger commands, and then passes their output as an input file to the process being launched. *Commands* can be any number of debugger commands, separated by semicolons, and enclosed in quotation marks. + +**-x** +Causes any process being spawned to be completely detached from the debugger. This allows you to create processes which will continue running even after the debugging session ends. + + *ShellCommand* +Specifies the application command line or Microsoft MS-DOS command to be executed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For other ways of accessing the command shell, see [Using Shell Commands](using-shell-commands.md). + +Remarks +------- + +The **.shell** command is not supported when the output of a user-mode debugger is redirected to the kernel debugger. For more information about redirecting output to the kernel debugger (sometimes called NTSD over KD), see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +The entire line after the **.shell** command will be interpreted as a Windows command (even if it contains a semicolon). This line should not be enclosed in quotation marks. There must be a space between **.shell** and the *ShellCommand* (additional leading spaces are ignored). + +The output from the command will appear in the Debugger Command window, unless the **-o** **** *OutFile* parameter is used. + +Issuing a **.shell** command with no parameters will activate the shell and leave it open. All subsequent commands will be interpreted as Windows commands. During this time, the debugger will display messages reading **<.shell process may need input>**, and the WinDbg prompt will be replaced with an **Input>** prompt. Sometimes, a separate Command Prompt window will appear when the debugger leaves the shell open. This window should be ignored; all input and output will be done through the Debugger Command window. + +To close this shell and return to the debugger itself, type **exit** or **.shell\_quit**. (The **.shell\_quit** command is more powerful, because it works even if the shell is frozen.) + +This command cannot be used while debugging CSRSS, because new processes cannot be created without CSRSS being active. + +You can use the -ci flag to run one or more debugger commands and then pass their output to a shell process. For example, you could pass the output from the [**!process 0 7**](-process.md) command to a Perl script by using the following command: + +``` +0:000> .shell -ci "!process 0 7" perl.exe parsemyoutput.pl +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.shell%20%28Command%20Shell%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-show-read-failures.md b/windows-driver-docs-pr/debugger/-show-read-failures.md new file mode 100644 index 0000000000..6fe06eec57 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-show-read-failures.md @@ -0,0 +1,72 @@ +--- +title: .show_read_failures +description: The .show_read_failures command enables or disables the display of read failures. +ms.assetid: e01c6578-ebf6-4ec1-85dd-de353ae8a781 +keywords: [".show_read_failures Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .show_read_failures +api_type: +- NA +--- + +# .show\_read\_failures + + +The **.show\_read\_failures** command enables or disables the display of read failures. + +``` +.show_read_failures /v +.show_sym_failures /V +``` + +## Parameters + + + **/v** +Enables the display of read failures. + + **/V** +Disables the display of read failures. + +## Environment + + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.show_read_failures%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-show-sym-failures.md b/windows-driver-docs-pr/debugger/-show-sym-failures.md new file mode 100644 index 0000000000..52560f8a87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-show-sym-failures.md @@ -0,0 +1,80 @@ +--- +title: .show_sym_failures +description: The .show_sym_failures command enables or disables the display of symbol lookup failures and type lookup failures. +ms.assetid: cf0b6cfd-aad2-482f-a382-a3909f5f3cd4 +keywords: [".show_sym_failures Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .show_sym_failures +api_type: +- NA +--- + +# .show\_sym\_failures + + +The **.show\_sym\_failures** command enables or disables the display of symbol lookup failures and type lookup failures. + +``` +.show_sym_failures /s +.show_sym_failures /S +.show_sym_failures /t +.show_sym_failures /T +``` + +## Parameters + + + **/s** +Enables the display of symbol lookup failures. + + **/S** +Disables the display of symbol lookup failures. + + **/t** +Enables the display of type lookup failures. + + **/T** +Disables the display of type lookup failures. + +## Environment + + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.show_sym_failures%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sid.md b/windows-driver-docs-pr/debugger/-sid.md new file mode 100644 index 0000000000..ae30a84eb2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sid.md @@ -0,0 +1,70 @@ +--- +title: sid +description: The sid extension displays the security identifier (SID) at the specified address. +ms.assetid: 7b93eb0e-7c0f-4c30-851b-6f40c7df8e1b +keywords: ["sid Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sid +api_type: +- NA +--- + +# !sid + + +The **!sid** extension displays the security identifier (SID) at the specified address. + +Syntax + +``` +!sid Address [Flags] +``` + +## Parameters + + + *Address* +Specifies the address of the SID structure. + + *Flags* +If this is set to 1, the SID type, domain, and user name for the SID is displayed. + +If this is set to 1, the friendly name is displayed. This includes the SID type, as well as the domain and user name for the SID. + +### DLL + +Exts.dll + +### Additional Information + +For information about SIDs, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, or *Microsoft Windows Internals* by Mark Russinovich and David Solomon. Also see [**!sd**](-sd.md) and [**!acl**](-acl.md). + +Remarks +------- + +Here are two examples, one without the friendly name shown, and one with: + +``` +kd> !sid 0xe1bf35b8 +SID is: S-1-5-21-518066528-515770016-299552555-513 + +kd> !sid 0xe1bf35b8 1 +SID is: S-1-5-21-518066528-515770016-299552555-513 (Group: MYGROUP\Domain Users) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sid%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sleep--pause-debugger-.md b/windows-driver-docs-pr/debugger/-sleep--pause-debugger-.md new file mode 100644 index 0000000000..329712faa9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sleep--pause-debugger-.md @@ -0,0 +1,84 @@ +--- +title: .sleep (Pause Debugger) +description: The .sleep command causes the user-mode debugger to pause and the target computer to become active. This command is only used when you are controlling the user-mode debugger from the kernel debugger. +ms.assetid: bc3ee17f-e3b8-4bdb-8c80-6b1fef29000e +keywords: ["Pause Debugger (.sleep) command", "controlling the user-mode debugger from the kernel debugger, Pause Debugger (.sleep) command", ".sleep (Pause Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .sleep (Pause Debugger) +api_type: +- NA +--- + +# .sleep (Pause Debugger) + + +The **.sleep** command causes the user-mode debugger to pause and the target computer to become active. This command is only used when you are controlling the user-mode debugger from the kernel debugger. + +``` +.sleep milliseconds +``` + +## Parameters + + + *milliseconds* +Specifies the length of the pause, in milliseconds. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

controlling the user-mode debugger from the kernel debugger

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For details and information about how to wake up a debugger in sleep mode, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +Remarks +------- + +When you are controlling the user-mode debugger from the kernel debugger, and the user-mode debugger prompt is visible in the kernel debugger, this command will activate sleep mode. The kernel debugger, the user-mode debugger, and the target application will all freeze, but the rest of the target computer will become active. + +If you use this command in any other scenario, it will simply freeze the debugger for a period of time. + +The sleep time is in milliseconds and interpreted according to the default radix, unless a prefix such as **0n** is used. Thus, if the default radix is 16, the following command will cause about 65 seconds of sleep: + +``` +0:000> .sleep 10000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.sleep%20%28Pause%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-slist.md b/windows-driver-docs-pr/debugger/-slist.md new file mode 100644 index 0000000000..39e682fe19 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-slist.md @@ -0,0 +1,150 @@ +--- +title: slist +description: The slist extension displays a singly-linked list (SList). +ms.assetid: 2ce6e941-eaa7-4850-9dd9-f4546659dbca +keywords: ["SList (singly-linked list)", "slist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- slist +api_type: +- NA +--- + +# !slist + + +The **!slist** extension displays a singly-linked list (SList). + +``` +!slist Address [ Symbol [Offset] ] +!slist -? +``` + +## Parameters + + + *Address* +Specifies the address of the SLIST\_HEADER. + + *Symbol* +Specifies the data type to use for display. If *Symbol* is specified, the debugger will assume that each node of the SList is an instance of this data type when displaying it. + + *Offset* +Specifies the byte offset of the SList pointer within the structure. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +Remarks +------- + +If you know the nature of the linked structures, the *Symbol* and *Offset* parameters are very useful. To see the difference, here are two examples; the first omits the *Symbol* and *Offset* parameters, while the second includes them. + +``` +0:000> !slist ListHead +SLIST HEADER: + +0x000 Alignment : a000a002643e8 + +0x000 Next : 2643e8 + +0x004 Depth : a + +0x006 Sequence : a + +SLIST CONTENTS: +002643e8 002642c0 0000000a 6e676953 72757461 +002642c0 00264198 00000009 6e676953 72757461 +00264198 00264070 00000008 6e676953 72757461 +00264070 00263f48 00000007 6e676953 72757461 +00263f48 00261420 00000006 6e676953 72757461 +00261420 002612f8 00000005 6e676953 72757461 +002612f8 002611d0 00000004 6e676953 72757461 +002611d0 002610a8 00000003 6e676953 72757461 +002610a8 00260f80 00000002 6e676953 72757461 +00260f80 00000000 00000001 6e676953 72757461 +``` + +``` +0:000> !slist ListHead _PROGRAM_ITEM 0 +SLIST HEADER: + +0x000 Alignment : a000a002643e8 + +0x000 Next : 2643e8 + +0x004 Depth : a + +0x006 Sequence : a + +SLIST CONTENTS: +002643e8 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 0xa + +0x008 Description : [260] "Signature is: 10" +002642c0 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 9 + +0x008 Description : [260] "Signature is: 9" +00264198 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 8 + +0x008 Description : [260] "Signature is: 8" +00264070 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 7 + +0x008 Description : [260] "Signature is: 7" +00263f48 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 6 + +0x008 Description : [260] "Signature is: 6" +00261420 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 5 + +0x008 Description : [260] "Signature is: 5" +002612f8 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 4 + +0x008 Description : [260] "Signature is: 4" +002611d0 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 3 + +0x008 Description : [260] "Signature is: 3" +002610a8 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 2 + +0x008 Description : [260] "Signature is: 2" +00260f80 + +0x000 ItemEntry : _SINGLE_LIST_ENTRY + +0x004 Signature : 1 + +0x008 Description : [260] "Signature is: 1" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!slist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-smt.md b/windows-driver-docs-pr/debugger/-smt.md new file mode 100644 index 0000000000..f6c28b8ab7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-smt.md @@ -0,0 +1,86 @@ +--- +title: smt +description: The smt extension displays a summary of the simultaneous multithreaded processor information. +ms.assetid: 28c07f89-6208-4b04-b7b9-825dda4f5f5a +keywords: ["smt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- smt +api_type: +- NA +--- + +# !smt + + +The **!smt** extension displays a summary of the simultaneous multithreaded processor information. + +``` +!smt +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example: + +``` +lkd> !smt +SMT Summary: +------------ + KeActiveProcessors: **------------------------------ (00000003) + KiIdleSummary: -------------------------------- (00000000) + No PRCB Set Master SMT Set IAID + 0 820f4820 Master **------------------------------ (00000003) 00 + 1 87a4d120 820f4820 **------------------------------ (00000003) 01 + +Maximum cores per physical processor: 2 +Maximum logical processors per core: 1 +``` + +The **No** column indicates the number of the processor. + +The **PRCB** column indicates the address of the processor control block for the processor. Each logical processor is listed separately. + +Each physical processor has exactly one logical processor listed as the **Master** under the **Set Master** column. + +The **SMT Set** column lists the processor's simultaneous multithreaded processor set information. + +The **IAID** column lists the initial Advanced Programmable Interrupt Controller identifier (APIC ID). On a true x64 computer, each processor starts with a hard-coded initial APIC ID. This ID value can be retrieved through the CPUID instruction. On certain other computers, the initial APIC ID is not necessarily unique across all processors, so the APIC ID that is accessible through the APIC's memory-mapped input/output (MMIO) space can be modified. This technique enables software to allocate unique APIC IDs for all processors within the computer. Depending on the target computer's processors, the **IAID** column may show this ID or may be blank. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!smt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sound-notify--use-notification-sound-.md b/windows-driver-docs-pr/debugger/-sound-notify--use-notification-sound-.md new file mode 100644 index 0000000000..7ff22e84df --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sound-notify--use-notification-sound-.md @@ -0,0 +1,77 @@ +--- +title: .sound_notify (Use Notification Sound) +description: The .sound_notify command causes a sound to be played when WinDbg enters the wait-for-command state. +ms.assetid: 72ef33ea-1c75-4add-80eb-a0d824571948 +keywords: [".sound_notify (Use Notification Sound) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .sound_notify (Use Notification Sound) +api_type: +- NA +--- + +# .sound\_notify (Use Notification Sound) + + +The **.sound\_notify** command causes a sound to be played when WinDbg enters the wait-for-command state. + +``` +.sound_notify /ed +.sound_notify /ef File +.sound_notify /d +``` + +## Parameters + + + **/ed** +Causes the default Windows alert sound to be played when WinDbg enters the wait-for-command state. + + **/ef** **** *File* +Causes the sound contained in the specified file to be played when WinDbg enters the wait-for-command state. + + **/d** +Disables the playing of sounds. + +### Environment + +This command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Targets

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.sound_notify%20%28Use%20Notification%20Sound%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sprocess.md b/windows-driver-docs-pr/debugger/-sprocess.md new file mode 100644 index 0000000000..dc6f12a61f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sprocess.md @@ -0,0 +1,142 @@ +--- +title: sprocess +description: The sprocess extension displays information about the specified session process, or about all processes in the specified session. +ms.assetid: 03c69f3c-501a-44e4-98e0-bf851ca6d24e +keywords: ["sprocess Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sprocess +api_type: +- NA +--- + +# !sprocess + + +The **!sprocess** extension displays information about the specified session process, or about all processes in the specified session. + +``` +!sprocess Session [Flags [ImageName]] +!sprocess -? +``` + +## Parameters + + + *Session* +Specifies the session that owns the desired process. *Session* is always interpreted as a decimal number. + +*Session* can have the following values: + + ++++ + + + + + + + + + + + + + + +

-1

Use current session. This is the default.

-2

Use [session context](changing-contexts.md#session-context).

-4

Display all processes by session.

+ +  + + *Flags* +Specifies the level of detail in the display. *Flags* can be any combination of the following bits. The default is 0. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

0x0

Display minimal information.

Bit 0 (0x1)

Display time and priority statistics.

Bit 1 (0x2)

Adds to the display a list of threads and events associated with the process and the wait states of the threads.

Bit 2 (0x4)

Adds to the display a list of threads associated with the process. If this bit is used without Bit 1 (0x2), each thread is displayed on a single line. If this is included with Bit 1, each thread is displayed with a stack trace.

Bit 3 (0x8)

Adds to the display of each function the return address, the stack pointer and, on Itanium-based systems, the bsp register value. It suppresses the display of function arguments.

Bit 4 (0x10)

Display only the return address of each function. Suppress the arguments and stack pointers.

+ +  + + *ImageName* +Specifies the name of the process to be displayed. All processes whose executable image names match *ImageName* are displayed. The image name must match that in the EPROCESS block. In general, this is the executable name that was invoked to start the process, including the file extension (usually .exe), and truncated after the fifteenth character. There is no way to specify an image name that contains a space. + + **-?** +Displays help for this extension in the Debugger Command window. This help text has some omissions. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about sessions and processes in kernel mode, see [Changing Contexts](changing-contexts.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The output of this extension is similar to that of [**!process**](-process.md), except that the addresses of \_MM\_SESSION\_SPACE and \_MMSESSION are displayed as well. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sprocess%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-srb.md b/windows-driver-docs-pr/debugger/-srb.md new file mode 100644 index 0000000000..104096a0f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-srb.md @@ -0,0 +1,72 @@ +--- +title: srb +description: The srb extension displays information about a SCSI Request Block (SRB). +ms.assetid: 38f40a78-c991-465e-9203-a8171d1a86f6 +keywords: ["srb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- srb +api_type: +- NA +--- + +# !srb + + +The **!srb** extension displays information about a SCSI Request Block (SRB). + +``` +!srb Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the SRB on the target computer. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about SRBs, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +An SRB is a system-defined structure used to communicate I/O requests from a SCSI class driver to a SCSI port driver. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!srb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-srcfix---lsrcfix--use-source-server-.md b/windows-driver-docs-pr/debugger/-srcfix---lsrcfix--use-source-server-.md new file mode 100644 index 0000000000..05e86aaa33 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-srcfix---lsrcfix--use-source-server-.md @@ -0,0 +1,98 @@ +--- +title: .srcfix, .lsrcfix (Use Source Server) +description: The .srcfix and .lsrcfix commands automatically set the source path to indicate that a source server will be used. +ms.assetid: e4cc3031-7990-4339-9dc2-f2c5a219a771 +keywords: [".srcfix, .lsrcfix (Use Source Server) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .srcfix, .lsrcfix (Use Source Server) +api_type: +- NA +--- + +# .srcfix, .lsrcfix (Use Source Server) + + +The **.srcfix** and **.lsrcfix** commands automatically set the source path to indicate that a source server will be used. + +``` +.srcfix[+] [Paths] +.lsrcfix[+] [Paths] +``` + +## Parameters + + + **+** +Causes the existing source path to be preserved, and **; srv\*** to be appended to the end. If the **+** is not used, the existing source path is replaced. + + *Paths* +Specifies one or more additional paths to append to the end of the new source path. + +### Environment + +The **.srcfix** command is available on all debuggers. The **.lsrcfix** command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information on setting the local source path for a remote client, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). For details about [SrcSrv](srcsrv.md), see [Using a Source Server](using-a-source-server.md). For details on the source path and the local source path, see [Source Path](source-path.md). For more information about commands that can be used while performing remote debugging through the debugger, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +Remarks +------- + +When you add `srv*` to the source path, the debugger uses [SrcSrv](srcsrv.md) to retrieve source files from locations specified in the target modules' symbol files. Using `srv*` in the source path is fundamentally different from using `srv*` in the symbol path. In the symbol path, you can specify a symbol server location along with the `srv*` (for example, `.sympath SRV*https://msdl.microsoft.com/download/symbols`). In the source path, srv\* stands alone, separated from all other elements by semicolons. + +When this command is issued from a debugging client, **.srcfix** sets the source path to use a source server on the debugging server, while **.lsrcfix** does the same on the local machine. + +These commands are the same as the [**.srcpath (Set Source Path)**](-srcpath---lsrcpath--set-source-path-.md) and **.lsrcpath (Set Local Source Path)** commands followed by the **srv\*** source path element. Thus, the following two commands are equivalent: + +``` +.srcfix[+] [Paths] +.srcpath[+] srv*[;Paths] +``` + +Similarly, the following two commands are equivalent: + +``` +.lsrcfix[+] [Paths] +.lsrcpath[+] srv*[;Paths] +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.srcfix,%20.lsrcfix%20%28Use%20Source%20Server%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-srcnoisy--noisy-source-loading-.md b/windows-driver-docs-pr/debugger/-srcnoisy--noisy-source-loading-.md new file mode 100644 index 0000000000..95bf6ac35f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-srcnoisy--noisy-source-loading-.md @@ -0,0 +1,86 @@ +--- +title: .srcnoisy (Noisy Source Loading) +description: The .srcnoisy command controls the verbosity level for source file loading. +ms.assetid: c57e0d0a-7903-455a-9a92-fab75f10ca80 +keywords: [".srcnoisy (Noisy Source Loading) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .srcnoisy (Noisy Source Loading) +api_type: +- NA +--- + +# .srcnoisy (Noisy Source Loading) + + +The **.srcnoisy** command controls the verbosity level for source file loading. + +``` +.srcnoisy [Options] +``` + +## Parameters + + + *Options* +Can be any one of the following options: + +0 +Disables the display of extra messages. + +1 +Displays information about the progress of source file loading and unloading. + +2 +Displays information about the progress of symbol file loading and unloading. + +3 +Displays all information displayed by options 1 and 2. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +With no parameters, **.srcnoisy** will display the current status of noisy source loading. + +Noisy source loading should not be confused with noisy symbol loading -- that is controlled by the [**!sym noisy**](-sym.md) extension and by other means of controlling the [SYMOPT\_DEBUG](symbol-options.md#symopt-debug) setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.srcnoisy%20%28Noisy%20Source%20Loading%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-srcpath---lsrcpath--set-source-path-.md b/windows-driver-docs-pr/debugger/-srcpath---lsrcpath--set-source-path-.md new file mode 100644 index 0000000000..608feff0d9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-srcpath---lsrcpath--set-source-path-.md @@ -0,0 +1,84 @@ +--- +title: .srcpath, .lsrcpath (Set Source Path) +description: The .srcpath and .lsrcpath commands set or display the source file search path. +ms.assetid: 416c062f-cbf9-4134-aa2c-306147a466b5 +keywords: [".srcpath, .lsrcpath (Set Source Path) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .srcpath, .lsrcpath (Set Source Path) +api_type: +- NA +--- + +# .srcpath, .lsrcpath (Set Source Path) + + +The **.srcpath** and **.lsrcpath** commands set or display the source file search path. + +``` +.srcpath[+] [Directory [; ...]] +.lsrcpath[+] [Directory [; ...]] +``` + +## Parameters + + + **+** +Specifies that the new directories will be appended to (rather than replacing) the previous source file search path. + + *Directory* +Specifies one or more directories to put in the search path. If *Directory* is not specified, the current path is displayed. Separate multiple directories with semicolons. + +### Environment + +The **.srcpath** command is available on all debuggers. The **.lsrcpath** command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details and other ways to change this path, see [Source Path](source-path.md). For more information about commands that can be used while performing remote debugging through the debugger, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +Remarks +------- + +If you include `srv*` in your source path, the debugger uses [SrcSrv](srcsrv.md) to retrieve source files from locations specified in the target modules' symbol files. For more information about using srv\* in a source path, see [Using a Source Server](using-a-source-server.md) and [**.srcfix**](-srcfix---lsrcfix--use-source-server-.md). + +When this command is issued from a debugging client, **.srcpath** sets the source path on the debugging server, while **.lsrcpath** sets the source path on the local machine. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.srcpath,%20.lsrcpath%20%28Set%20Source%20Path%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-stacks.md b/windows-driver-docs-pr/debugger/-stacks.md new file mode 100644 index 0000000000..ccfdef990e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-stacks.md @@ -0,0 +1,148 @@ +--- +title: stacks +description: The stacks extension displays information about the kernel stacks. +ms.assetid: f0777609-4785-4a6b-a6f5-9efaeb608df7 +keywords: ["stacks Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- stacks +api_type: +- NA +--- + +# !stacks + + +The **!stacks** extension displays information about the kernel stacks. + +Syntax + +``` +!stacks [Detail [FilterString]] +``` + +## Parameters + + + *Detail* +Specifies the level of detail to use in the display. The following table lists the valid values for *Detail*. + + ++++ + + + + + + + + + + + + + + +

0

Displays a summary of the current kernel stacks. This is the default value.

1

Displays stacks that are currently paged out, as well as the current kernel stacks.

2

Displays the full parameters for all stacks, as well as stacks that are currently paged out and the current kernel stacks.

+ +  + + *FilterString* +Displays only threads that contain the specified substring in a symbol. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about kernel stacks, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The **!stacks** extension gives a brief summary of the state of every thread. You can use this extension instead of the [**!process**](-process.md) extension to get a quick overview of the system, especially when debugging multithread issues such as resource conflicts or deadlocks. + +The [**!findstack**](-findstack.md) user-mode extension also displays information about particular stacks. + +Here is an example of the simplest **!stacks** display: + +``` +kd> !stacks 0 +Proc.Thread .Thread ThreadState Blocker + [System] + 4.000050 827eea10 Blocked +0xfe0343a5 + + [smss.exe] + + [csrss.exe] + b0.0000a8 82723b70 Blocked ntoskrnl!_KiSystemService+0xc4 + b0.0000c8 82719620 Blocked ntoskrnl!_KiSystemService+0xc4 + b0.0000d0 827d5d50 Blocked ntoskrnl!_KiSystemService+0xc4 +..... +``` + +The first column shows the process ID and the thread ID (separated by a period). + +The second column is the current address of the thread's ETHREAD block. + +The third column shows the state of the thread (initialized, ready, running, standby, terminated, transition, or blocked). + +The fourth column shows the top address on the thread's stack. + +Here are examples of more detailed **!stacks** output: + +``` +kd> !stacks 1 +Proc.Thread .Thread ThreadState Blocker + [System] + 4.000008 827d0030 Blocked ntoskrnl!MmZeroPageThread+0x66 + 4.000010 827d0430 Blocked ntoskrnl!ExpWorkerThread+0x189 + 4.000014 827cf030 Blocked Stack paged out + 4.000018 827cfda0 Blocked Stack paged out + 4.00001c 827cfb10 Blocked ntoskrnl!ExpWorkerThread+0x189 +..... + [smss.exe] + 9c.000098 82738310 Blocked Stack paged out + 9c.0000a0 826a5190 Blocked Stack paged out + 9c.0000a4 82739d30 Blocked Stack paged out + + [csrss.exe] + b0.0000bc 826d0030 Blocked Stack paged out + b0.0000b4 826c9030 Blocked Stack paged out + b0.0000a8 82723b70 Blocked ntoskrnl!_KiSystemService+0xc4 +..... + +kd> !stacks 2 +Proc.Thread .Thread ThreadState Blocker + [System] + 4.000008 827d0030 Blocked ntoskrnl!KiSwapThread+0xc5 + ntoskrnl!KeWaitForMultipleObjects+0x2b4 + ntoskrnl!MmZeroPageThread+0x66 + ntoskrnl!Phase1Initialization+0xd82 + ntoskrnl!PspSystemThreadStartup+0x4d + ntoskrnl!CreateSystemRootLink+0x3d8 + +0x3f3f3f3f + 4.000010 827d0430 Blocked ntoskrnl!KiSwapThread+0xc5 + ntoskrnl!KeRemoveQueue+0x191 +..... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!stacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-std-map.md b/windows-driver-docs-pr/debugger/-std-map.md new file mode 100644 index 0000000000..ced4932dd0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-std-map.md @@ -0,0 +1,87 @@ +--- +title: std_map +description: The std_map extension displays the entries of a std map tree. +ms.assetid: 7a921226-e7b1-4c3f-9732-c53c66710ccb +keywords: ["std_map Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- std_map +api_type: +- NA +--- + +# !std\_map + + +The **!std\_map** extension displays the entries of a std::map tree. + +``` +!std_map Address [Module!Type [TypeSize]] +!std_map -? +``` + +## Parameters + + + *Address* +Specifies the address of the std::map tree to display. + + *Module* +Specifies the module in which the data structure is defined. + + *Type* +Specifies the name of a data structure. This must be expressed in *Module***!std::pair<***Type1***,***Type2***>** form. If the *TypeSize* parameter is used, this parameter must be enclosed in quotation marks. + + *TypeSize* +Specifies the size of the data structure to make the symbols unambiguous. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +To display other Standard Template Library (STL) defined templates, see [**!stl**](-stl.md). + +Remarks +------- + +Including the *Module***!***Type* option causes each entry in the table to be interpreted as having the given type. + +Use [**dt -ve (Module!std::pair<Type1,Type2>)**](dt--display-type-.md) to display possible sizes. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!std_map%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-step-filter--set-step-filter-.md b/windows-driver-docs-pr/debugger/-step-filter--set-step-filter-.md new file mode 100644 index 0000000000..13ec863f66 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-step-filter--set-step-filter-.md @@ -0,0 +1,101 @@ +--- +title: .step_filter (Set Step Filter) +description: The .step_filter command creates a list of functions that are skipped (stepped over) when tracing. +ms.assetid: 9ce2bed4-fac0-4537-a129-7cb9f1e8725e +keywords: [".step_filter (Set Step Filter) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .step_filter (Set Step Filter) +api_type: +- NA +--- + +# .step\_filter (Set Step Filter) + + +The **.step\_filter** command creates a list of functions that are skipped (stepped over) when tracing. This allows you to trace through code and skip only certain functions. It can also be used in source mode to control stepping when there are multiple function calls on one line. + +``` +.step_filter "FilterList" +.step_filter /c +.step_filter +``` + +## Parameters + + +**"***FilterList***"** +Specifies the symbols associated with functions to be stepped over. *FilterList* can contain any number of text patterns separated by semicolons. Each of these patterns may contain a variety of wildcards and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details. A function whose symbol matches at least one of these patterns will be stepped over during tracing. Each time **"***FilterList***"** is used, any previous filter list is discarded and completely replaced with the new list. + + **/c** +Clears the filter list. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +Without any parameters, **.step\_filter** displays the current filter list. + +Typically, a trace command (for example, [**t**](t--trace-.md) or the windbg [debug | step into](debug---step-into.md) button ![screen shot of the step into button](images/tbinto.png)) traces into a function call. However, if the symbol associated with the function being called matches a pattern specified by *FilterList*, the function will be stepped over -- as if a step command (for example, [**p**](p--step-.md)) had been used. + +If the instruction pointer is located within code that is listed in the filter list, any trace or step commands will step out of this function, like the [**gu**](gu--go-up-.md) command or the WinDbg **Step Out** button. Of course, this filter would prevent such code from having been traced into in the first place, so this will only happen if you have changed the filter or hit a breakpoint. + +For example, the following command will cause trace commands to skip over all CRT calls: + +``` +.step_filter "msvcrt!*" +``` + +The **.step\_filter** command is most useful when you are debugging in source mode, because there can be multiple function calls on a single source line. The [**p**](p--step-.md) and [**t**](t--trace-.md) commands cannot be used to separate these function calls. + +For example, in the following line, the [**t**](t--trace-.md) command will step into both GetTickCount and printf, while the [**p**](p--step-.md) command will step over both function calls: + +``` +printf( "%x\n", GetTickCount() ); +``` + +The **.step\_filter** command allows you to filter out one of these calls while still tracing into the other. + +Because the functions are identified by symbol, a single filter can include an entire module. This lets you filter out framework functions -- for example, Microsoft Foundation Classes (MFC) or Active Template Library (ATL) calls. + +When debugging in assembly mode, each call is on a different line, so you can choose whether to step or trace line-by-line. So **.step\_filter** is not very useful in assembly mode. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.step_filter%20%28Set%20Step%20Filter%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-stl.md b/windows-driver-docs-pr/debugger/-stl.md new file mode 100644 index 0000000000..9c46630e17 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-stl.md @@ -0,0 +1,83 @@ +--- +title: stl +description: The stl extension displays some of the known Standard Template Library (STL) templates. +ms.assetid: a1f1f923-64bd-44c9-941f-9a648888c7e0 +keywords: ["stl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- stl +api_type: +- NA +--- + +# !stl + + +The **!stl** extension displays some of the known Standard Template Library (STL) templates. + +``` +!stl [Options] Template +!stl -? +``` + +## Parameters + + + *Options* +May include any of the following possibilities: + +**-v** +Causes detailed output to be displayed. + +**-V** +Causes more detailed output to be displayed, such as information on the progress of the extension, including when certain functions are called and returned. + + *Template* +Specifies the name of the template to be displayed. + + **-?** +Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +Remarks +------- + +The verbose options will only take effect if the debugger's verbose mode is enabled. + +This extension currently supports STL templates of the following types: string, wstring, vector<*string*>, vector<*wstring*>, list<*string*>, list<*wstring*>, and pointers to any of the preceding types. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!stl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storadapter.md b/windows-driver-docs-pr/debugger/-storagekd-storadapter.md new file mode 100644 index 0000000000..e83a01eeaf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storadapter.md @@ -0,0 +1,101 @@ +--- +title: storagekd.storadapter +description: The storagekd.storadapter extension displays information about the specified Storport adapter. +ms.assetid: E7EBC2F7-676A-4DD9-ADAA-5C240299013C +keywords: ["storagekd.storadapter Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storadapter +api_type: +- NA +--- + +# !storagekd.storadapter + + +The **!storagekd.storadapter** extension displays information about the specified Storport adapter. + +``` +!storagekd.storadapter [Address] +``` + +## Parameters + + + *Address* +Specifies the address of a Storport adapter device object. If *Address* is omitted, a list of all Storport adapters is displayed. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of the **!storagekd.storadapter** display: + +**1: kd> ! storagekd.storadapter** + +``` +# STORPORT adapters: +================== +## Driver Object Extension State +----------------------------------------------------------------- +\Driver\vhdmp fffffa800649a050 fffffa800649a1a0 Working +``` + +**1: kd> ! storagekd.storadapter fffffa800649a050** + +``` +ADAPTER + DeviceObj : fffffa800649a050 AdapterExt: fffffa800649a1a0 DriverObj : fffffa800507fcb0 +DeviceState : Working + LowerDO fffffa8005f71e10 PhysicalDO fffffa8005f71e10 + SlowLock Free RemLock -666 + SystemPowerState: Working AdapterPowerState D0 Full Duplex + Bus 0 Slot 0 DMA 0000000000000000 Interrupt 0000000000000000 + Allocated ResourceList 0000000000000000 +Translated ResourceList 0000000000000000 + Gateway: Outstanding 0 Lower 256 High 256 + PortConfigInfo fffffa800649a2d0 + HwInit fffffa80062e8840 HwDeviceExt fffffa8004b84d70 (112 bytes) + SrbExt 2256 bytes LUExt 24 bytes + +Normal Logical Units: + Product SCSI ID Object Extension Pnd Out Ct State + ---------------------------------------------------------------------------------------- + Msft Virtual Di 0 0 1 fffffa800658a060 fffffa800658a1b0 0 0 0 Working + + Zombie Logical Units: + Product SCSI ID Object Extension Pnd Out Ct State + -------------------------------------------------------------------------------------- +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storadapter%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storclass.md b/windows-driver-docs-pr/debugger/-storagekd-storclass.md new file mode 100644 index 0000000000..6cc0763553 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storclass.md @@ -0,0 +1,113 @@ +--- +title: storagekd.storclass +description: The storagekd.storclass extension displays information about the specified classpnp device. +ms.assetid: EC5B44F5-540E-4F25-80AA-09BE4F78BF72 +keywords: ["storagekd.storclass Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storclass +api_type: +- NA +--- + +# !storagekd.storclass + + +The **!storagekd.storclass** extension displays information about the specified *classpnp* device. + +``` +!storagekd.storclass [Address [Level]] +``` + +## Parameters + + + *Address* +Specifies the address to the device object or device extension of a classpnp device. If *Address* is omitted, a list of all classpnp extensions is displayed. + + *Level* +Specifies the amount of detail to display. This parameter can be set to 0, 1, or 2, with 2 giving the most detail and 0 the least. The default is 0. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of the **!storagekd.storclass** display: + +**1: kd> !storagekd.storclass** + +``` +Storage class devices: + +* !storclass fffffa80043dc060 [1,2] ST3160812AS Paging Disk + !storclass fffffa8006581740 [1,2] Msft Virtual Disk Disk + +Usage: !storclass +``` + +**1: kd> !storagekd.storclass fffffa80043dc060 1** + +``` +Storage class device fffffa80043dc060 with extension at fffffa80043dc1b0 + +Classpnp Internal Information at fffffa8003bec360 + + Transfer Packet Engine: + + Packet Status DL Irp Opcode Sector/ListId UL Irp + -------- ------ -------- ------ --------------- -------- + + Pending Idle Requests: 0x0 + + + -- dt classpnp!_CLASS_PRIVATE_FDO_DATA fffffa8003bec360 -- + +Classpnp External Information at fffffa80043dc1b0 + + ST3160812AS 3.ADH 9LS20QRL + + Minidriver information at fffffa80043dc670 + Attached device object at fffffa800410a060 + Physical device object at fffffa800410a060 + + Media Geometry: + + Bytes in a Sector = 512 + Sectors per Track = 63 + Tracks / Cylinder = 255 + Media Length = 160000000000 bytes = ~149 GB + + -- dt classpnp!_FUNCTIONAL_DEVICE_EXTENSION fffffa80043dc1b0 -- +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storclass%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storhelp.md b/windows-driver-docs-pr/debugger/-storagekd-storhelp.md new file mode 100644 index 0000000000..903801d414 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storhelp.md @@ -0,0 +1,81 @@ +--- +title: storagekd.storhelp +description: The storagekd.storhelp extension displays help text for Storagekd.dll extension commands. +ms.assetid: 17FFB5CC-1FA3-4D13-AA30-6D48D2435CDC +keywords: ["storagekd.storhelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storhelp +api_type: +- NA +--- + +# !storagekd.storhelp + + +The **!storagekd.storhelp** extension displays help text for Storagekd.dll extension commands. + +``` +!storagekd.storhelp +``` + +## DLL + + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of the **!storagekd.storhelp** display: + +**0: kd> !storagekd.storhelp** + +``` +# Storage Debugger Extension +=============================================== +## General Commands +---------------- +!storhelp - Displays complete help of the commands provided in this KD extension +!storclass - Dumps all class devices managed by classpnp +!storadapter - Dumps all adapters managed by Storport +!storunit - Dumps all disks managed by Storport + +## STORPORT specific commands +-------------------------- +!storlogirp - displays internal log entries that reference the specified IRP. + See '!storhelp storlogirp' for details. +!storloglist - displays internal log entries. See '!storhelp storloglist' for details. +!storlogsrb - displays internal log entries that reference the specified SRB. + See '!storhelp storlogsrb' for details. +!storsrb
- display details for the specified SCSI or STORAGE request block +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storhelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storlogirp.md b/windows-driver-docs-pr/debugger/-storagekd-storlogirp.md new file mode 100644 index 0000000000..367a3e0ba4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storlogirp.md @@ -0,0 +1,71 @@ +--- +title: storagekd.storlogirp +description: The storagekd.storlogirp extension displays the Storport’s internal log entries for the adapter filtered for the IRP provided. +ms.assetid: EE2325CC-CDC0-4963-A0E8-B8EAB9A633BE +keywords: ["storagekd.storlogirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storlogirp +api_type: +- NA +--- + +# !storagekd.storlogirp + + +The **!storagekd.storlogirp** extension displays the Storport’s internal log entries for the adapter filtered for the IRP provided. + +``` +!storagekd.storlogirp
[ []] [L ] +``` + +## Parameters + + + *Address* +Specifies the address of a Storport adapter device extension or device object. + + *irp* +The IRP to locate. + + *starting\_entry* +The beginning entry in the range to display. If not specified, the last *count* entries will be displayed. + + *ending\_entry* +The ending entry in the range to display. If not specified, *count* entries will be displayed, beginning with the item specified by *starting\_entry*. + + *count* +Count of entries to be displayed. If not specified, a value of 50 is used. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storlogirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storloglist.md b/windows-driver-docs-pr/debugger/-storagekd-storloglist.md new file mode 100644 index 0000000000..3c2717b0ee --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storloglist.md @@ -0,0 +1,91 @@ +--- +title: storagekd.storloglist +description: The storagekd.storloglist extension displays the Storport adapter’s internal log entries. +ms.assetid: 6308DDEF-8AB0-4D16-9245-3046114D5173 +keywords: ["storagekd.storloglist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storloglist +api_type: +- NA +--- + +# !storagekd.storloglist + + +The **!storagekd.storloglist** extension displays the Storport adapter’s internal log entries. + +``` +!storagekd.storloglist
[ []] [L ] +``` + +## Parameters + + + *Address* +Specifies the address of a Storport adapter device extension or device object. + + *starting\_entry* +The beginning entry in the range to display. If not specified, the last *count* entries will be displayed. + + *ending\_entry* +The ending entry in the range to display. If not specified, *count* entries will be displayed, beginning with the item specified by *starting\_entry*. + + *count* +Count of entries to be displayed. If not specified, a value of 50 is used. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of **!storagekd.storloglist** display: + +**0: kd> !storagekd.storloglist ffffe0010f5e01a0** + +``` +Storport RaidLogList + Circular buffer location: 0xffffe0010f5e1720 + Total logs written: 8 + Displaying entries 0 through 7 + --------------------------------------------------------------------- + [0]_[23:04:20.521] ResumeDevice.......... Caller: storport!RaidUnitPauseTimerDpcRoutine+0x28 (fffff800`fb4d0b28), P/P/T/L: 0/0/0/0, Pause count: 0, Resumed: True + [1]_[23:04:20.646] ResumeDevice.......... Caller: storport!RaidUnitPauseTimerDpcRoutine+0x28 (fffff800`fb4d0b28), P/P/T/L: 0/0/0/0, Pause count: 0, Resumed: True + [2]_[23:04:20.646] SpPauseDevice......... Caller: iaStorAV!RpiPauseDevice+0x67 (fffff800`fb70554f), P/T/L: 3/0/0, Timeout: 180, Adapter: 0xffffe0010f5e01a0 + [3]_[23:04:20.646] PauseDevice........... Caller: storport!StorPortPauseDevice+0x2f6 (fffff800`fb4b52d6), P/P/T/L: 0/3/0/0, Pause count: 1 + [4]_[23:04:20.646] SpResumeDevice........ Caller: iaStorAV!RpiResumeDevice+0x5f (fffff800`fb7055fb), P/T/L: 3/0/0, Adapter: 0xffffe0010f5e01a0 + [5]_[23:04:20.646] ResumeDevice.......... Caller: storport!StorPortResumeDevice+0x19 (fffff800`fb4aa23f), P/P/T/L: 0/3/0/0, Pause count: 0, Resumed: True + [6]_[23:04:20.646] SpPauseDevice......... Caller: iaStorAV!RpiPauseDevice+0x67 (fffff800`fb70554f), P/T/L: 3/0/0, Timeout: 180, Adapter: 0xffffe0010f5e01a0 + [7]_[23:04:20.646] PauseDevice........... Caller: storport!StorPortPauseDevice+0x2f6 (fffff800`fb4b52d6), P/P/T/L: 0/3/0/0, Pause count: 1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storloglist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storlogsrb.md b/windows-driver-docs-pr/debugger/-storagekd-storlogsrb.md new file mode 100644 index 0000000000..dd8f925802 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storlogsrb.md @@ -0,0 +1,71 @@ +--- +title: storagekd.storlogsrb +description: The storagekd.storlogsrb extension displays the Storport’s internal log entries for the adapter filtered for the Storage (or SCSI) Request Block (SRB) provided. +ms.assetid: 9E742636-DD19-4D8D-BDA1-C9BB8C293D8C +keywords: ["storagekd.storlogsrb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storlogsrb +api_type: +- NA +--- + +# !storagekd.storlogsrb + + +The **!storagekd.storlogsrb** extension displays the Storport’s internal log entries for the adapter filtered for the Storage (or SCSI) Request Block (SRB) provided. + +``` +!storagekd.storlogsrb
[ []] [L ] +``` + +## Parameters + + + *Address* +Specifies the address of a Storport adapter device extension or device object. + + *SRB* +The SRB to locate. + + *starting\_entry* +The beginning entry in the range to display. If not specified, the last *count* entries will be displayed. + + *ending\_entry* +The ending entry in the range to display. If not specified, *count* entries will be displayed, beginning with the item specified by *starting\_entry*. + + *count* +Count of entries to be displayed. If not specified, a value of 50 is used. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storlogsrb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storsrb.md b/windows-driver-docs-pr/debugger/-storagekd-storsrb.md new file mode 100644 index 0000000000..6a5bbaad4f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storsrb.md @@ -0,0 +1,76 @@ +--- +title: storagekd.storsrb +description: The storagekd.storsrb extension displays information about the specified Storage (or SCSI) Request Block (SRB). +ms.assetid: E2AB3BE2-0EE1-4FB5-9F62-02169B22B00B +keywords: ["storagekd.storsrb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storsrb +api_type: +- NA +--- + +# !storagekd.storsrb + + +The **!storagekd.storsrb** extension displays information about the specified Storage (or SCSI) Request Block (SRB). + +``` +!storagekd.storsrb Address +``` + +## Parameters + + + *Address* +Specifies the address of the SRB. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of the **!storagekd.storsrb** display: + +**0: kd> !storagekd.storsrb ffffe00111fe25b0** + +``` + SRB is a STORAGE request block (SRB_EX) + SRB EX 0xffffe00111fe25b0 Function 28 Version 1, Signature 53524258, SrbStatus: 0x02[Aborted], SrbFunction 0x00 [EXECUTE SCSI] + Address Type is BTL8 + + SRB_EX Data Type [SrbExDataTypeScsiCdb16] + [EXECUTE SCSI] SRB_EX: 0xffffe00111fe2648 OriginalRequest: 0xffffe001125a9010 DataBuffer/Length: 0xffffe00112944000 / 0x00000200 + PTL: (0, 1, 1) CDB: 28 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 OpCode: SCSI/READ (10) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storsrb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-storagekd-storunit.md b/windows-driver-docs-pr/debugger/-storagekd-storunit.md new file mode 100644 index 0000000000..6b411960a4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-storagekd-storunit.md @@ -0,0 +1,111 @@ +--- +title: storagekd.storunit +description: The storagekd.storunit extension displays information about the specified Storport logical unit. +ms.assetid: 73A2632C-962E-4075-97B9-5D7D843E9D0F +keywords: ["storagekd.storunit Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- storagekd.storunit +api_type: +- NA +--- + +# !storagekd.storunit + + +The **!storagekd.storunit** extension displays information about the specified Storport logical unit. + +``` +!storagekd.storunit [Address] +``` + +## Parameters + + + *Address* +Specifies the address of a Storport unit device object. If *Address* is omitted, a list of all Storport units are displayed. + +### DLL + + ++++ + + + + + + +

Windows 8 and later

Storagekd.dll

+ +  + +Remarks +------- + +Here is an example of the **!storagekd.storunit** display: + +**0: kd> !storagekd.storunit** + +``` +# STORPORT Units: +================== +## Product SCSI ID Object Extension Pnd Out Ct State +-------------------------------------------------------------------------------------- +Msft Virtual Di 0 0 1 fffffa800658a060 fffffa800658a1b0 0 0 0 Working +``` + +**0: kd> !storagekd.storunit fffffa800658a060** + +``` + DO fffffa800658a060 Ext fffffa800658a1b0 Adapter fffffa800649a1a0 Working + Vendor: Msft Product: Virtual Disk SCSI ID: (0, 0, 1) + Claimed Enumerated + SlowLock Free RemLock 1 PageCount 0 + QueueTagList: fffffa800658a270 Outstanding: Head fffffa800658a398 Tail fffffa800658a398 Timeout -1 + DeviceQueue fffffa800658a2a0 Depth: 250 Status: Not Frozen PauseCount: 0 BusyCount: 0 + IO Gateway: Busy Count 0 Pause Count 0 + Requests: Outstanding 0 Device 0 ByPass 0 + + +[Device-Queued Requests] + +## IRP SRB Type SRB XRB Command MDL SGList Timeout +----------------------------------------------------------------------------------------------------------------------------------- + + +[Bypass-Queued Requests] + +## IRP SRB Type SRB XRB Command MDL SGList Timeout +----------------------------------------------------------------------------------------------------------------------------------- + + +[Outstanding Requests] + +## IRP SRB Type SRB XRB Command MDL SGList Timeout +----------------------------------------------------------------------------------------------------------------------------------- + + +[Completed Requests] + +IRP SRB Type SRB XRB Command MDL SGList Timeout +----------------------------------------------------------------------------------------------------------------------------------- +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!storagekd.storunit%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-str.md b/windows-driver-docs-pr/debugger/-str.md new file mode 100644 index 0000000000..ecd4a0e7f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-str.md @@ -0,0 +1,84 @@ +--- +title: str +description: The str extension displays an ANSI_STRING or OEM_STRING structure. +ms.assetid: 5ebb29d4-5d77-475b-ace5-8bc8a4299320 +keywords: ["strings", "ANSI_STRING structure", "str Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- str +api_type: +- NA +--- + +# !str + + +The **!str** extension displays an ANSI\_STRING or OEM\_STRING structure. + +``` +!str Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the ANSI\_STRING or OEM\_STRING structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about ANSI\_STRING structures, see the Microsoft Windows SDK documentation. + +Remarks +------- + +ANSI strings are counted 8-bit character strings, as defined in the following structure: + +``` +typedef struct _STRING { + USHORT Length; + USHORT MaximumLength; + PCHAR Buffer; +} STRING; +typedef STRING ANSI_STRING; +typedef STRING OEM_STRING; +``` + +If the string is null-terminated, **Length** does not include the trailing null. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!str%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-suspend-ui--suspend-windbg-interface-.md b/windows-driver-docs-pr/debugger/-suspend-ui--suspend-windbg-interface-.md new file mode 100644 index 0000000000..4329cabd9a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-suspend-ui--suspend-windbg-interface-.md @@ -0,0 +1,87 @@ +--- +title: .suspend_ui (Suspend WinDbg Interface) +description: The .suspend_ui command suspends the refresh of WinDbg debugging information windows. +ms.assetid: 7fa6ca5c-f960-49eb-b6f0-a6f2d454984f +keywords: [".suspend_ui (Suspend WinDbg Interface) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .suspend_ui (Suspend WinDbg Interface) +api_type: +- NA +--- + +# .suspend\_ui (Suspend WinDbg Interface) + + +The **.suspend\_ui** command suspends the refresh of WinDbg debugging information windows. + +``` +.suspend_ui 0 +.suspend_ui 1 +.suspend_ui +``` + +## Parameters + + + **0** +Suspends the refresh of WinDbg debugging information windows. + + **1** +Enables the refresh of WinDbg debugging information windows. + +### Environment + +This command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For information about debugging information windows, see [Using Debugging Information Windows](using-debugging-information-windows.md). + +Remarks +------- + +Without any parameters, **.suspend\_ui** displays whether debugging information windows are currently suspended. + +By default, debugging information windows are refreshed every time the information they display changes. + +Suspending the refresh of these windows can speed up WinDbg during a sequence of quick operations -- for example, when tracing or stepping many times in quick succession. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.suspend_ui%20%28Suspend%20WinDbg%20Interface%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-swd.md b/windows-driver-docs-pr/debugger/-swd.md new file mode 100644 index 0000000000..5e7f5148ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/-swd.md @@ -0,0 +1,68 @@ +--- +title: swd +description: The swd extension displays the software watchdog timer states for the specified processor, including the deferred procedure call (DPC) and the watchdog timer states for threads. +ms.assetid: 03532c7e-3bfc-4e37-8a0a-0a7c5a9963a8 +keywords: ["watchdog timer", "swd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- swd +api_type: +- NA +--- + +# !swd + + +The **!swd** extension displays the software watchdog timer states for the specified processor, including the deferred procedure call (DPC) and the watchdog timer states for threads. + +``` +!swd [Processor] +``` + +## Parameters + + + *Processor* +Specifies the processor. If *Processor* is omitted, information is displayed for all processors on the target computer. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The watchdog timer shuts down or restarts Windows if Windows stops responding. The times are displayed in seconds. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!swd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sym.md b/windows-driver-docs-pr/debugger/-sym.md new file mode 100644 index 0000000000..7e67bf42fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sym.md @@ -0,0 +1,89 @@ +--- +title: sym +description: The sym extension controls noisy symbol loading and symbol prompts. +ms.assetid: 84551b24-740c-4289-acc4-8a0053f80b41 +keywords: ["symbols, noisy symbol loading", "symbols, prompts", "sym Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sym +api_type: +- NA +--- + +# !sym + + +The **!sym** extension controls noisy symbol loading and symbol prompts. + +``` +!sym +!sym noisy +!sym quiet +!sym prompts +!sym prompts off +``` + +## Parameters + + + **noisy** +Activates noisy symbol loading. + + **quiet** +Deactivates noisy symbol loading. + + **prompts** +Allows authentication dialog boxes to appear when SymSrv receives an authentication request. + + **prompts off** +Suppresses all authentication dialog boxes when SymSrv receives an authentication request. This may result in SymSrv being unable to access symbols over the internet. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Dbghelp.dll

Windows XP and later

Dbghelp.dll

+ +  + +Remarks +------- + +If the **!sym** extension is used with no arguments, the current state of noisy symbol loading and symbol prompting is displayed. + +The **!sym noisy** and **!sym quiet** extensions control noisy symbol loading. For details and for other methods of displaying and changing this option, see [SYMOPT\_DEBUG](symbol-options.md#symopt-debug). + +The **!sym prompts** and **!sym prompts off** extensions control whether authentication dialogs are displayed when SymSrv encounters an authentication request. These commands must be followed by [**.reload (Reload Module)**](-reload--reload-module-.md) for them to take effect. Authentication requests may be sent by proxy servers, internet firewalls, smart card readers, and secure websites. For details and for other methods of changing this option, see [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md). + +**Note**   Noisy symbol loading should not be confused with noisy source loading -- that is controlled by the [**.srcnoisy (Noisy Source Loading)**](-srcnoisy--noisy-source-loading-.md) command. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sym%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-symfix--set-symbol-store-path-.md b/windows-driver-docs-pr/debugger/-symfix--set-symbol-store-path-.md new file mode 100644 index 0000000000..1908c17b25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-symfix--set-symbol-store-path-.md @@ -0,0 +1,98 @@ +--- +title: .symfix (Set Symbol Store Path) +description: The .symfix command automatically sets the symbol path to point to the Microsoft symbol store. +ms.assetid: 9ad80217-e2d1-4776-a620-f2735b2c8f84 +keywords: ["Set Symbol Store Path (.symfix) command", "SymSrv, Set Symbol Store Path (.symfix) command", ".symfix (Set Symbol Store Path) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .symfix (Set Symbol Store Path) +api_type: +- NA +--- + +# .symfix (Set Symbol Store Path) + + +The **.symfix** command automatically sets the symbol path to point to the Microsoft symbol store. + +``` +.symfix[+] [LocalSymbolCache] +``` + +## Parameters + + + **+** +Causes the Microsoft symbol store path to be appended to the existing symbol path. If this is not included, the existing symbol path is replaced. + + *LocalSymbolCache* +Specifies the directory to be used as a local symbol cache. If this directory does not exist, it will be created when the symbol server begins copying files. If *LocalSymbolCache* is omitted, the sym subdirectory of the debugger installation directory will be used. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details, see [Using Symbol Servers and Symbol Stores](symbol-stores-and-symbol-servers.md). + +Remarks +------- + +The following example shows how to use **.symfix** to set a new symbol path that points to the Microsoft symbol store. + +``` +3: kd> .symfix c:\myCache +3: kd> .sympath +Symbol search path is: srv* +Expanded Symbol search path is: cache*c:\myCache;SRV*https://msdl.microsoft.com/download/symbols +``` + +The following example shows how to use **.symfix+** to append the existing symbol path with a path that points to the Microsoft symbol store. + +``` +3: kd> .sympath +Symbol search path is: c:\someSymbols +Expanded Symbol search path is: c:\somesymbols +3: kd> .symfix+ c:\myCache +3: kd> .sympath +Symbol search path is: c:\someSymbols;srv* +Expanded Symbol search path is: c:\somesymbols;cache*c:\myCache;SRV*https://msdl.microsoft.com/download/symbols +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.symfix%20%28Set%20Symbol%20Store%20Path%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-symopt--set-symbol-options-.md b/windows-driver-docs-pr/debugger/-symopt--set-symbol-options-.md new file mode 100644 index 0000000000..789ca28b24 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-symopt--set-symbol-options-.md @@ -0,0 +1,84 @@ +--- +title: .symopt (Set Symbol Options) +description: The .symopt command sets or displays the symbol options. +ms.assetid: 0793baa3-14f7-48df-8773-736b6a5470e6 +keywords: [".symopt (Set Symbol Options) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .symopt (Set Symbol Options) +api_type: +- NA +--- + +# .symopt (Set Symbol Options) + + +The **.symopt** command sets or displays the symbol options. + +``` +.symopt+ Flags +.symopt- Flags +.symopt +``` + +## Parameters + + + **+** +Causes the symbol options specified by *Flags* to be set. If **.symopt** is used with *Flags* but no plus or minus sign, a plus sign is assumed. + + **-** +Causes the symbol options specified by *Flags* to be cleared. + + *Flags* +Specifies the symbol options to be changed. *Flags* must be the sum of the bit flags of these symbol options. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For a list and description of each symbol option, its bit flag, and other methods of setting and clearing these options, see [Setting Symbol Options](symbol-options.md). + +Remarks +------- + +Without any arguments, **.symopt** displays the current symbol options. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.symopt%20%28Set%20Symbol%20Options%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sympath--set-symbol-path-.md b/windows-driver-docs-pr/debugger/-sympath--set-symbol-path-.md new file mode 100644 index 0000000000..c85b766031 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sympath--set-symbol-path-.md @@ -0,0 +1,79 @@ +--- +title: .sympath (Set Symbol Path) +description: The .sympath command sets or alters the symbol path. The symbol path specifies locations where the debugger looks for symbol files. +ms.assetid: 32146871-a59f-4c93-b886-137c5ecf5c99 +keywords: ["Set Symbol Path (.sympath) command", "symbol files and paths, Set Symbol Path (.sympath) command", ".sympath (Set Symbol Path) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .sympath (Set Symbol Path) +api_type: +- NA +--- + +# .sympath (Set Symbol Path) + + +The **.sympath** command sets or alters the symbol path. The symbol path specifies locations where the debugger looks for symbol files. + +``` +.sympath[+] [Path [; ...]] +``` + +## Parameters + + + **+** +Specifies that the new locations will be appended to (rather than replace) the previous symbol search path. + + *Path* +A fully qualified path or a list of fully qualified paths. Multiple paths are separated by semicolons. If *Path* is omitted, the current symbol path is displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details and other ways to change this path, see [Symbol Path](symbol-path.md). + +Remarks +------- + +New symbol information will not be loaded when the symbol path is changed. You can use the [**.reload (Reload Module)**](-reload--reload-module-.md) command to reload symbols. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.sympath%20%28Set%20Symbol%20Path%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-symsrv.md b/windows-driver-docs-pr/debugger/-symsrv.md new file mode 100644 index 0000000000..a2b30dc296 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-symsrv.md @@ -0,0 +1,69 @@ +--- +title: symsrv extension command +description: The symsrv extension closes the symbol server client. +ms.assetid: 666fa9d7-f723-4745-95fc-17aa20993b42 +keywords: ["symsrv Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- symsrv +api_type: +- NA +--- + +# !symsrv + + +The **!symsrv** extension closes the symbol server client. + +``` +!symsrv close +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Dbghelp.dll

Windows XP and later

Dbghelp.dll

+ +  + +Remarks +------- + +The **!symsrv close** extension will close any active symbol server client. + +This can be useful if you need to re-synchronize your connection. + +If you have previously refused an internet authentication request, you will need to use **!symsrv close** to reconnect to the symbol store. See [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md) for details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!symsrv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sysinfo.md b/windows-driver-docs-pr/debugger/-sysinfo.md new file mode 100644 index 0000000000..d120daaec1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sysinfo.md @@ -0,0 +1,143 @@ +--- +title: sysinfo +description: The sysinfo extension reads and displays specified SMBIOS, Advanced Configuration and Power Interface (ACPI), and CPU information from a dump file or live system. +ms.assetid: 1637fcc8-54ff-46a4-94f4-0b2df38507d1 +keywords: ["sysinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sysinfo +api_type: +- NA +--- + +# !sysinfo + + +The **!sysinfo** extension reads and displays specified SMBIOS, Advanced Configuration and Power Interface (ACPI), and CPU information from a dump file or live system. + +``` +!sysinfo cpuinfo [-csv [-noheaders]] +!sysinfo cpumicrocode [-csv [-noheaders]] +!sysinfo cpuspeed [-csv [-noheaders]] +!sysinfo gbl [-csv [-noheaders]] +!sysinfo machineid [-csv [-noheaders]] +!sysinfo registers +!sysinfo smbios [-csv [-noheaders]] {-debug | -devices | -memory | -power | -processor | -system | -v} +!sysinfo -? +``` + +## Parameters + + + **cpuinfo** +Displays information about the processor. + + **cpumicrocode** +(GenuineIntel processors only) Displays the initial and cached microcode processor versions. + + **cpuspeed** +Displays the maximum and current processor speeds. + + **gbl** +Displays the BIOS list of ACPI tables. + + **machineid** +Displays machine ID information for the SMBIOS, BIOS, firmware, system, and baseboard. + + **registers** +Displays machine-specific registers (MSRs). + + **smbios** +Displays the SMBIOS table. + + **-csv** +Displays all data in comma-separated, variable-length (CSV) format. + + **-noheaders** +Suppresses the header for the CSV format. + + **-debug** +Displays output in standard format and CSV format. + + **-devices** +Displays the device entries in the SMBIOS table. + + **-memory** +Displays the memory entries in the SMBIOS table. + + **-power** +Displays the power entries in the SMBIOS table. + + **-processor** +Displays the processor entries in the SMBIOS table. + + **-system** +Displays the system entries in the SMBIOS table. + + **-v** +Verbose. Displays the details of entries in the SMBIOS table. + + **-?** +Displays help for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP base system

+

Windows 2003 base system

Unavailable

Windows XP, Service Pack 2 and later

+

Windows 2003, Service Pack 1 and later

Kdexts.dll

+ +  + +Remarks +------- + +This extension is useful only when the dump file is a System Crash File (.dmp) that has not been converted to a minidump file from a kernel or full dump file, or the live system has finished starting and is online (for example, at the log-in prompt). + +You can use any combination of the **-debug**, **-devices**, **-memory**, **-power**, **-processor**, **-system**, and **-v** parameters in a single extension command. + +The following parameters are supported only on particular systems: + +- The **gbl** parameter works only when the target computer supports ACPI. + +- The **smbios** parameter works only when the target computer supports SMBIOS. + +- The **registers** parameter does not work on Itanium-based target computers, because they do not collect MSRs. + +Microsoft makes every effort to remove personally identifiable information (PII) from these records. All PII is removed from dump files. However, on a live system, some PII may not yet be removed. As a result, PII fields will be reported as 0 or blank, even if they actually contain information. + +To stop execution of commands that include the **cpuinfo**, **gbl**, **registers**, or **smbios** parameters at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sysinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-sysptes.md b/windows-driver-docs-pr/debugger/-sysptes.md new file mode 100644 index 0000000000..07fb8e440f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-sysptes.md @@ -0,0 +1,143 @@ +--- +title: sysptes +description: The sysptes extension displays a formatted view of the system page table entries (PTEs). +ms.assetid: cfb40732-6658-43aa-8b83-0ad4b55194ba +keywords: ["sysptes Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sysptes +api_type: +- NA +--- + +# !sysptes + + +The **!sysptes** extension displays a formatted view of the system page table entries (PTEs). + +``` +!sysptes [Flags] +``` + +## Parameters + + + *Flags* +Specifies the level of detail to display. *Flags* can be any combination of the following bits. The default is zero: + +Bit 0 (0x1) +Displays information about free PTEs. + +Bit 1 (0x2) +(Windows 2000 only) Displays unused pages in the page usage statistics. + +(Windows XP and later) Displays information about free PTEs in the global special pool. + +Bit 2 (0x4) +Displays detailed information about any system PTEs that are allocated to mapping locked pages. + +Bit 3 (0x8) +(Windows 2000 and Windows XP only) Displays nonpaged pool expansion free PTE information. If this bit is set, the other lists are not displayed. If both 0x1 and 0x8 are set, all nonpaged pool expansion free PTEs are displayed. If only 0x8 is set, only the total is displayed. + +Bit 4 (0x10) +(Windows Vista and later) Displays special pool free PTE information for the session. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about page tables and PTEs, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +To examine a specific PTE, use the [**!pte**](-pte.md) extension. + +Here is an example from a Windows 2000 system: + +``` +kd> !sysptes 1 + +System PTE Information + Total System Ptes 50962 + SysPtes list of size 1 has 389 free + SysPtes list of size 2 has 95 free + SysPtes list of size 4 has 55 free + SysPtes list of size 8 has 35 free + SysPtes list of size 16 has 27 free + + starting PTE: c03c7000 + ending PTE: c03f8c44 + +loading (99% complete) + + free ptes: c03c8d60 number free: 45134. + + free blocks: 1 total free: 45134 largest free block: 45134 + + Page Count + a0 2. + a1 2. + a2 2. + a3 2. +...... +``` + +In Windows XP and later versions of Windows, the display is similar, except that the page count statistics at the end are not included. Here is an example from a Windows XP system: + +``` +kd> !sysptes 1 + +System PTE Information + Total System Ptes 571224 + SysPtes list of size 1 has 361 free + SysPtes list of size 2 has 91 free + SysPtes list of size 4 has 48 free + SysPtes list of size 8 has 36 free + SysPtes list of size 9 has 29 free + SysPtes list of size 23 has 29 free + + starting PTE: fffffe0059388000 + ending PTE: fffffe00597e3ab8 + + free ptes: fffffe0059388000 number free: 551557. + free ptes: fffffe00597be558 number free: 104. + free ptes: fffffe00597d2828 number free: 676. + + free blocks: 3 total free: 552337 largest free block: 551557 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!sysptes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-teb.md b/windows-driver-docs-pr/debugger/-teb.md new file mode 100644 index 0000000000..192fdd8e37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-teb.md @@ -0,0 +1,87 @@ +--- +title: teb +description: The teb extension displays a formatted view of the information in the thread environment block (TEB). +ms.assetid: 4137b54b-f784-412d-bffd-e8a71a54155e +keywords: ["teb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- teb +api_type: +- NA +--- + +# !teb + + +The **!teb** extension displays a formatted view of the information in the thread environment block (TEB). + +``` +!teb [TEB-Address] +``` + +## Parameters + + + *TEB-Address* +The hexadecimal address of the thread whose TEB you want to examine. (This is not the address of the TEB as derived from the kernel thread block for the thread.) If *TEB-Address* is omitted in user mode, the TEB for the current thread is used. If it is omitted in kernel mode, the TEB corresponding to the current [register context](changing-contexts.md#register-context) is displayed. + +### DLL + +Exts.dll + +### Additional Information + +For information about thread environment blocks, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +The TEB is the user-mode portion of Microsoft Windows thread control structures. + +If the **!teb** extension with no argument gives you an error in kernel mode, you should use the [**!process**](-process.md) extension to determine the TEB address for the desired thread. Make sure your [register context](changing-contexts.md#register-context) is set to the desired thread, and then use the TEB address as the argument for **!teb**. + +Here is an example of this command's output in user mode: + +``` +0:001> ~ + 0 id: 324.458 Suspend: 1 Teb 7ffde000 Unfrozen +. 1 id: 324.48c Suspend: 1 Teb 7ffdd000 Unfrozen + +0:001> !teb +TEB at 7FFDD000 + ExceptionList: 76ffdc + Stack Base: 770000 + Stack Limit: 76f000 + SubSystemTib: 0 + FiberData: 1e00 + ArbitraryUser: 0 + Self: 7ffdd000 + EnvironmentPtr: 0 + ClientId: 324.48c + Real ClientId: 324.48c + RpcHandle: 0 + Tls Storage: 0 + PEB Address: 7ffdf000 + LastErrorValue: 0 + LastStatusValue: 0 + Count Owned Locks:0 + HardErrorsMode: 0 +``` + +The similar [**!peb**](-peb.md) extension displays the process environment block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!teb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-thread--set-register-context-.md b/windows-driver-docs-pr/debugger/-thread--set-register-context-.md new file mode 100644 index 0000000000..51f5ca6c06 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-thread--set-register-context-.md @@ -0,0 +1,151 @@ +--- +title: .thread (Set Register Context) +description: The .thread command specifies which thread will be used for the register context. +ms.assetid: 577276b7-a6c4-427e-ada1-10dbb62ebd5c +keywords: ["Set Register Context (.thread) command", "context, Set Register Context (.thread) command", "registers, Set Register Context (.thread) command", "call stack, Set Register Context (.thread) command", ".thread (Set Register Context) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .thread (Set Register Context) +api_type: +- NA +--- + +# .thread (Set Register Context) + + +The **.thread** command specifies which thread will be used for the register context. + +``` +.thread [/p [/r] ] [/P] [/w] [Thread] +``` + +## Parameters + + + **/p** +(Live debugging only) If this option is included and *Thread* is nonzero, all transition page table entries (PTEs) for the process owning this thread will be automatically translated into physical addresses before access. This may cause slowdowns, because the debugger will have to look up the physical addresses for all the memory used by this process, and a significant amount of data may need to be transferred across the debug cable. (This behavior is the same as that of [**.cache forcedecodeuser**](-cache--set-cache-size-.md).) + +If the **/p** option is included and *Thread* is zero or omitted, this translation will be disabled. (This behavior is the same as that of [**.cache noforcedecodeuser**](-cache--set-cache-size-.md).) + + **/r** +(Live debugging only) If the **/r** option is included along with the **/p** option, user-mode symbols for the process owning this thread will be reloaded after the process and register contexts have been set. (This behavior is the same as that of [**.reload /user**](-reload--reload-module-.md).) + + **/P** +(Live debugging only) If this option is included and *Thread* is nonzero, all transition page table entries (PTEs) will be automatically translated into physical addresses before access. Unlike the **/p** option, this translates the PTEs for all user-mode and kernel-mode processes, not only the process owning this thread. This may cause slowdowns, because the debugger will have to look up the physical addresses for all memory in use, and a huge amount of data may need to be transferred across the debug cable. (This behavior is the same as that of [**.cache forcedecodeptes**](-cache--set-cache-size-.md).) + + **/w** +(64-bit kernel debugging only) Changes the active context for the thread to the WOW64 32-bit context. The thread specified must be running in a process that has a WOW64 state. + + *Thread* +The address of the thread. If this is omitted or zero, the thread context is reset to the current thread. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +Generally, when you are doing kernel debugging, the only visible registers are the ones associated with the current thread. + +The **.thread** command instructs the kernel debugger to use the specified thread as the register context. After this command is executed, the debugger will have access to the most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command (**.thread**, [**.cxr**](-cxr--display-context-record-.md), or [**.trap**](-trap--display-trap-frame-.md)). See [Register Context](changing-contexts.md#register-context) for full details. + +The **/w** option can only be used in 64-bit kernel debugging sessions on a thread running in a process that has a WOW64 state. The context retrieved will be the last context remembered by WOW64; this is usually the last user-mode code executed by *Thread*. This option can only be used if the target is in native machine mode. For example, if the target is running on a 64-bit machine that is emulating an x86-based processor using WOW64, this option cannot be used. Using the **/w** option will cause the machine mode to switch automatically to an x86-based processor. + +This command does not actually change the current thread. In other words, extensions such as [**!thread**](-thread.md) and [**!teb**](-teb.md) will still default to the current thread if no arguments are used with them. + +Here is an example. Use the [**!process**](-process.md) extension to find the address of the desired thread. (In this case, **!process 0 0** is used to list all processes, then **!process** is used a second time to list all the threads for the desired process.) + +``` +kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +PROCESS fe5039e0 SessionId: 0 Cid: 0008 Peb: 00000000 ParentCid: 0000 + DirBase: 00030000 ObjectTable: fe529a88 TableSize: 145. + Image: System + +..... + +PROCESS ffaa5280 SessionId: 0 Cid: 0120 Peb: 7ffdf000 ParentCid: 01e0 + DirBase: 03b70000 ObjectTable: ffaa4e48 TableSize: 23. + Image: winmine.exe + +kd> !process ffaa5280 +PROCESS ffaa5280 SessionId: 0 Cid: 0120 Peb: 7ffdf000 ParentCid: 01e0 + DirBase: 03b70000 ObjectTable: ffaa4e48 TableSize: 23. + Image: winmine.exe + VadRoot ffaf6e48 Clone 0 Private 50. Modified 0. Locked 0. + DeviceMap fe502e88 + Token e1b55d70 + +..... + + THREAD ffaa43a0 Cid 120.3a4 Teb: 7ffde000 Win32Thread: e1b4fea8 WAIT: (WrUserRequest) UserMode Non-Alertable + ffadc6a0 SynchronizationEvent + Not impersonating + Owning Process ffaa5280 + WaitTime (seconds) 24323 + Context Switch Count 494 LargeStack + +..... +``` + +Now use the **.thread** command with the address of the desired thread. This sets the register context and enables you to examine the important registers and the call stack for this thread. + +``` +kd> .thread ffaa43a0 +Using context of thread ffaa43a0 + +kd> r +Last set context: +eax=00000000 ebx=00000000 ecx=00000000 edx=00000000 esi=00000000 edi=00000000 +eip=80403a0d esp=fd581c2c ebp=fd581c60 iopl=0 nv up di pl nz na pe nc +cs=0000 ss=0000 ds=0000 es=0000 fs=0000 gs=0000 efl=00000000 +0000:3a0d ?? ??? + +kd> k + *** Stack trace for last set context - .thread resets it +ChildEBP RetAddr +fd581c38 8042d61c ntoskrnl!KiSwapThread+0xc5 +00001c60 00000000 ntoskrnl!KeWaitForSingleObject+0x1a1 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.thread%20%28Set%20Register%20Context%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-thread.md b/windows-driver-docs-pr/debugger/-thread.md new file mode 100644 index 0000000000..a633ebb23e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-thread.md @@ -0,0 +1,162 @@ +--- +title: thread +description: The thread extension displays summary information about a thread on the target system, including the ETHREAD block. This command can be used only during kernel-mode debugging. +ms.assetid: 5d3cf2f7-02bf-4a94-b542-826ad2b66a6f +keywords: ["thread Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- thread +api_type: +- NA +--- + +# !thread + + +The **!thread** extension displays summary information about a thread on the target system, including the ETHREAD block. This command can be used only during kernel-mode debugging. + +This extension command is not the same as the [**.thread (Set Register Context)**](-thread--set-register-context-.md) command. + +Syntax + +``` +!thread [-p] [-t] [Address [Flags]] +``` + +## Parameters + + + **-p** +Displays summary information about the process that owns the thread. + + **-t** +When this option is included, *Address* is the thread ID, not the thread address. + + *Address* +Specifies the hexadecimal address of the thread on the target computer. If *Address* is -1 or omitted, it indicates the current thread. + + *Flags* +Specifies the level of detail to display. *Flags* can be any combination of the following bits. If *Flags* is 0, only a minimal amount of information is displayed. The default is 0x6: + +Bit 1 (0x2) +Displays the thread's wait states. + +Bit 2 (0x4) +If this bit is used without Bit 1 (0x2), it has no effect. If this bit is used with Bit 1, the thread is displayed with a stack trace. + +Bit 3 (0x8) +Adds the return address, the stack pointer, and (on Itanium systems) the **bsp** register value to the information displayed for each function and suppresses the display of function arguments. + +Bit 4 (0x10) +Sets the process context equal to the process that owns the specified thread for the duration of this command. This results in more accurate display of thread stacks. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about threads in kernel mode, see [Changing Contexts](changing-contexts.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +Here is an example using Windows 10: + +``` +0: kd> !thread 0xffffcb088f0a4480 +THREAD ffffcb088f0a4480 Cid 0e34.3814 Teb: 0000001a27ca6000 Win32Thread: 0000000000000000 RUNNING on processor 0 +Not impersonating +DeviceMap ffffb80842016c20 +Owning Process ffffcb08905397c0 Image: MsMpEng.exe +Attached Process N/A Image: N/A +Wait Start TickCount 182835891 Ticks: 0 +Context Switch Count 5989 IdealProcessor: 3 +UserTime 00:00:01.046 +KernelTime 00:00:00.296 +Win32 Start Address 0x00007ffb3b2fd1b0 +Stack Init ffff95818476add0 Current ffff958184769d30 +Base ffff95818476b000 Limit ffff958184765000 Call 0000000000000000 +Priority 8 BasePriority 8 PriorityDecrement 0 IoPriority 2 PagePriority 5 +Child-SP RetAddr : Args to Child : Call Site +fffff802`59858c68 fffff801`b56d24aa : ffffcb08`8fd68010 00000000`00000000 fffff802`58259600 00000000`00000008 : nt!DbgBreakPointWithStatus [d:\rs2\minkernel\ntos\rtl\amd64\debugstb.asm @ 130] +fffff802`59858c70 ffffcb08`8fd68010 : 00000000`00000000 fffff802`58259600 00000000`00000008 ffffcb08`8f0a4400 : 0xfffff801`b56d24aa +fffff802`59858c78 00000000`00000000 : fffff802`58259600 00000000`00000008 ffffcb08`8f0a4400 00000000`00000019 : 0xffffcb08`8fd68010 +``` + +Use commands like [**!process**](-process.md) to locate the address or thread ID of the thread you are interested in. + +The useful information in the **!thread** display is explained in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterMeaning

Thread address

The hexadecimal number after the word THREAD is the address of the ETHREAD block. In the preceding example, the thread address is 0xffffcb088f0a4480 .

Thread ID

The two hexadecimal numbers after the word Cid are the process ID and the thread ID: process ID.thread ID. In the preceding example, the process ID is 0x0e34, and the thread ID is 0x3814.

Thread Environment Block (TEB)

The hexadecimal number after the word Teb is the address of the thread environment block (TEB).

System Service Dispatch Table

The hexadecimal number after the word Win32Thread is the address of the system service dispatch table.

Thread State

The thread state is displayed at the end of the line that begins with the word RUNNING.

Owning Process

The hexadecimal number after the words Owning Process is the address of the EPROCESS for the process that owns this thread.

Start Address

The hexadecimal number after the words Start Address is the thread start address. This might appear in symbolic form.

User Thread Function

The hexadecimal number after the words Win32 Start Address is the address of the user thread function.

Priority

The priority information for the thread follows the word Priority.

Stack trace

A stack trace for the thread appears at the end of this display.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!thread%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-threadfields.md b/windows-driver-docs-pr/debugger/-threadfields.md new file mode 100644 index 0000000000..e7d2892001 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-threadfields.md @@ -0,0 +1,107 @@ +--- +title: threadfields +description: The threadfields extension displays the names and offsets of the fields within the executive thread (ETHREAD) block. +ms.assetid: 1b36e922-9079-4dc5-911a-f635ec026084 +keywords: ["threadfields Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- threadfields +api_type: +- NA +--- + +# !threadfields + + +The **!threadfields** extension displays the names and offsets of the fields within the executive thread (ETHREAD) block. + +``` +!threadfields +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable (see the Remarks section)

+ +  + +### Additional Information + +For information about the ETHREAD block, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +This extension command is not available in Windows XP or later versions of Windows. Instead, use the [**dt (Display Type)**](dt--display-type-.md) command to show the ETHREAD structure directly: + +``` +kd> dt nt!_ETHREAD +``` + +Here is an example of **!threadfields** from a Windows 2000 system: + +``` +kd> !threadfields + ETHREAD structure offsets: + + Tcb: 0x0 + CreateTime: 0x1b0 + ExitTime: 0x1b8 + ExitStatus: 0x1c0 + PostBlockList: 0x1c4 + TerminationPortList: 0x1cc + ActiveTimerListLock: 0x1d4 + ActiveTimerListHead: 0x1d8 + Cid: 0x1e0 + LpcReplySemaphore: 0x1e8 + LpcReplyMessage: 0x1fc + LpcReplyMessageId: 0x200 + ImpersonationInfo: 0x208 + IrpList: 0x20c + TopLevelIrp: 0x214 + ReadClusterSize: 0x21c + ForwardClusterOnly: 0x220 + DisablePageFaultClustering: 0x221 + DeadThread: 0x222 + HasTerminated: 0x224 + GrantedAccess: 0x228 + ThreadsProcess: 0x22c + StartAddress: 0x230 + Win32StartAddress: 0x234 + LpcExitThreadCalled: 0x238 + HardErrorsAreDisabled: 0x239 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!threadfields%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-threadtoken.md b/windows-driver-docs-pr/debugger/-threadtoken.md new file mode 100644 index 0000000000..dbb6ccf253 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-threadtoken.md @@ -0,0 +1,142 @@ +--- +title: threadtoken +description: The threadtoken extension displays the impersonation state of the current thread. +ms.assetid: df16bdb5-0834-4e07-ad5f-a712f9282bb0 +keywords: ["threadtoken Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- threadtoken +api_type: +- NA +--- + +# !threadtoken + + +The **!threadtoken** extension displays the impersonation state of the current thread. + +``` +!threadtoken +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ntsdexts.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +For information about threads and impersonation, see the Microsoft Windows SDK documentation and *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +The **!threadtoken** extension is obsolete in Windows XP and later versions of Windows. Use [**!token**](-token.md) instead. + +If the current thread is impersonating, the token that this thread is using will be displayed. + +Otherwise, a message reading "Thread is not impersonating" will appear. The process token will then be displayed. + +Tokens will be displayed in the same format that [**!handle**](-handle.md) uses when displaying token handles. + +Here is an example: + +``` +0:000> ~ +. 0 id: 1d0.55c Suspend: 1 Teb 7ffde000 Unfrozen +# 1 id: 1d0.1a4 Suspend: 1 Teb 7ffdd000 Unfrozen + +0:000> !threadtoken + +***Thread is not impersonating, using process token*** + Auth Id 0 : 0x1c93d + Type Primary + Imp Level Anonymous + Token Id 0 : 0x5e8c19 + Mod Id 0 : 0x5e8c12 + Dyn Chg 0x1f4 + Dyn Avail 0x1a4 + Groups 26 + Privs 17 + User S-1-5-21-2127521184-1604012920-1887927527-74790 + Groups 26 + S-1-5-21-2127521184-1604012920-1887927527-513 + S-1-1-0 + S-1-5-32-544 + S-1-5-32-545 + S-1-5-21-2127521184-1604012920-1887927527-277551 + S-1-5-21-2127521184-1604012920-1887927527-211604 + S-1-5-21-2127521184-1604012920-1887927527-10546 + S-1-5-21-2127521184-1604012920-1887927527-246657 + S-1-5-21-2127521184-1604012920-1887927527-277552 + S-1-5-21-2127521184-1604012920-1887927527-416040 + S-1-5-21-2127521184-1604012920-1887927527-96548 + S-1-5-21-2127521184-1604012920-1887927527-262644 + S-1-5-21-2127521184-1604012920-1887927527-155802 + S-1-5-21-2127521184-1604012920-1887927527-158763 + S-1-5-21-2127521184-1604012920-1887927527-279132 + S-1-5-21-2127521184-1604012920-1887927527-443952 + S-1-5-21-2127521184-1604012920-1887927527-175772 + S-1-5-21-2127521184-1604012920-1887927527-388472 + S-1-5-21-2127521184-1604012920-1887927527-443950 + S-1-5-21-2127521184-1604012920-1887927527-266975 + S-1-5-21-2127521184-1604012920-1887927527-158181 + S-1-5-21-2127521184-1604012920-1887927527-279435 + S-1-5-5-0-116804 + S-1-2-0 + S-1-5-4 + S-1-5-11 + Privileges 17 + SeUndockPrivilege ( Enabled Default ) + SeTakeOwnershipPrivilege ( ) + SeShutdownPrivilege ( ) + SeDebugPrivilege ( ) + SeIncreaseBasePriorityPrivilege ( ) + SeAuditPrivilege ( ) + SeSyncAgentPrivilege ( ) + SeLoadDriverPrivilege ( ) + SeSystemEnvironmentPrivilege ( Enabled ) + SeRemoteShutdownPrivilege ( ) + SeProfileSingleProcessPrivilege ( ) + SeCreatePagefilePrivilege ( ) + SeCreatePermanentPrivilege ( ) + SeSystemProfilePrivilege ( Enabled ) + SeBackupPrivilege ( ) + SeMachineAccountPrivilege ( ) + SeEnableDelegationPrivilege ( Enabled ) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!threadtoken%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-time--display-system-time-.md b/windows-driver-docs-pr/debugger/-time--display-system-time-.md new file mode 100644 index 0000000000..02c82b3193 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-time--display-system-time-.md @@ -0,0 +1,93 @@ +--- +title: .time (Display System Time) +description: The .time command displays information about the system time variables. +ms.assetid: d8024f84-98ff-4017-81c5-8a08973f9e4b +keywords: ["Display System Time (.time) command", ".time (Display System Time) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .time (Display System Time) +api_type: +- NA +--- + +# .time (Display System Time) + + +The **.time** command displays information about the system time variables. + +``` +.time [-h Hours] +``` + +## Parameters + + + **-h** **** *Hours* +Specifies the offset from Greenwich Mean Time, in hours. A negative value of *Hours* must be enclosed in parentheses. + + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +The system time variables control performance counter behavior. + +Here is an example in kernel mode: + +``` +kd> .time +Debug session time: Wed Jan 31 14:47:08 2001 +System Uptime: 0 days 2:53:56 +``` + +Here is an example in user mode: + +``` +0:000> .time +Debug session time: Mon Apr 07 19:10:50 2003 +System Uptime: 4 days 4:53:56.461 +Process Uptime: 0 days 0:00:08.750 + Kernel time: 0 days 0:00:00.015 + User time: 0 days 0:00:00.015 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.time%20%28Display%20System%20Time%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-time.md b/windows-driver-docs-pr/debugger/-time.md new file mode 100644 index 0000000000..196d9c5594 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-time.md @@ -0,0 +1,29 @@ +--- +title: time +description: time +ms.assetid: 63d19145-0f18-472c-a3ba-280de346b200 +keywords: ["time extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !time + + +## + + +The **!time** extension command is obsolete. Use the [**.time (Display System Time)**](-time--display-system-time-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!time%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-timer.md b/windows-driver-docs-pr/debugger/-timer.md new file mode 100644 index 0000000000..88e8c856fc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-timer.md @@ -0,0 +1,103 @@ +--- +title: timer +description: The timer extension displays a detailed listing of all system timer use. +ms.assetid: 795bdfe1-1ee4-4bf2-9fcd-80415fe84754 +keywords: ["timer Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- timer +api_type: +- NA +--- + +# !timer + + +The **!timer** extension displays a detailed listing of all system timer use. + +``` +!timer +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about timer objects, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The **!timer** extension displays the timer tree, which stores all timer objects in the system. + +Here is an example: + +``` +kd> !timer +Dump system timers + +Interrupt time: 9f760774 00000000 [12/ 8/2000 10:59:22.685 (Pacific Standard Time)] + +List Timer Interrupt Low/High Fire Time DPC/thread + 0 8016aea0 P 9fbd8e00 00000000 [12/ 8/2000 10:59:23.154] ntoskrnl!PopScanIdleList + 1 8257f118 e4e4225a 00000000 [12/ 8/2000 11:01:19.170] thread 8257f030 + 3 80165fc0 286be1c9 0000594a [ 4/ 1/2001 01:59:59.215] ntoskrnl!ExpTimeZoneDpcRoutine + 80165f40 2a7bf8d9 006f105e [12/31/2099 23:59:59.216] ntoskrnl!ExpCenturyDpcRoutine + 5 825a0bf8 a952e1c2 00000000 [12/ 8/2000 10:59:39.232] thread 825a0b10 + 10 8251c7a8 41f54d84 00000001 [12/ 8/2000 11:03:55.310] thread 8251c6c0 + 8249fe88 41f54d84 00000001 [12/ 8/2000 11:03:55.310] thread 8249fda0 + 11 8250e7e8 bc73ffde 00000000 [12/ 8/2000 11:00:11.326] thread 8250e700 + +..... + +237 82757070 9f904152 00000000 [12/ 8/2000 10:59:22.857] +f7a56f2e + 82676348 9f904152 00000000 [12/ 8/2000 10:59:22.857] +fe516352 + 82728b78 9f904152 00000000 [12/ 8/2000 10:59:22.857] +fe516352 +238 fe4b5d78 9f92a3ac 00000000 [12/ 8/2000 10:59:22.873] thread 827ceb10 + 801658f0 9f92a3ac 00000000 [12/ 8/2000 10:59:22.873] ntoskrnl!CcScanDpc +239 8259ad40 765a6f19 00000bba [12/23/2000 09:07:22.900] thread 825d3670 +250 826d42f0 1486bed8 80000000 [ NEVER ] thread 825fa030 + +Total Timers: 193, Maximum List: 7 +Current Hand: 226, Maximum Search: 0 + +Wakeable timers: +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!timer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tlist--list-process-ids-.md b/windows-driver-docs-pr/debugger/-tlist--list-process-ids-.md new file mode 100644 index 0000000000..0820463751 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tlist--list-process-ids-.md @@ -0,0 +1,85 @@ +--- +title: .tlist (List Process IDs) +description: The .tlist command lists all processes running on the system. +ms.assetid: 44d46b74-5cf1-4384-b468-baec5a87eaed +keywords: ["List Process IDs (.tlist) command", "process, List Process IDs (.tlist) command", ".tlist (List Process IDs) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .tlist (List Process IDs) +api_type: +- NA +--- + +# .tlist (List Process IDs) + + +The **.tlist** command lists all processes running on the system. + +``` +.tlist [Options][FileNamePattern] +``` + +## Parameters + + + *Options* +Can be any number of the following options: + +**-v** +Causes the display to be verbose. This includes the session number, the process user name, and the command-line used to start the process. + +**-c** +Limits the display to just the current process. + + *FileNamePattern* +Specifies the file name to be displayed, or a pattern that the file name of the process must match. Only those processes whose file names match this pattern will be displayed. *FileNamePattern* may contain a variety of wildcards and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details. This match is made only against the actual file name, not the path. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of displaying processes, see [Finding the Process ID](finding-the-process-id.md). + +Remarks +------- + +Each process ID is displayed with an **0n** prefix, to emphasize that the PID is a decimal number. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.tlist%20%28List%20Process%20IDs%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tls.md b/windows-driver-docs-pr/debugger/-tls.md new file mode 100644 index 0000000000..a63269ca1d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tls.md @@ -0,0 +1,80 @@ +--- +title: tls +description: The tls extension displays a thread local storage (TLS) slot. +ms.assetid: 43325322-8e6e-47fc-b1ec-8b1c304bb1e9 +keywords: ["TLS (thread local storage)", "thread local storage (TLS)", "tls Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tls +api_type: +- NA +--- + +# !tls + + +The **!tls** extension displays a thread local storage (TLS) slot. + +``` +!tls Slot [TEB] +``` + +## Parameters + + + *Slot* +Specifies the TLS slot. This can be any value between 0 and 1088 (decimal). If *Slot* is -1, all slots are displayed. + + *TEB* +Specifies the thread environment block (TEB). If this is 0 or omitted, the current thread is used. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +Remarks +------- + +Here is an example: + +``` +0:000> !tls -1 +TLS slots on thread: c08.f54 +0x0000 : 00000000 +0x0001 : 003967b8 +0:000> !tls 0 +c08.f54: 00000000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tls%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-token.md b/windows-driver-docs-pr/debugger/-token.md new file mode 100644 index 0000000000..7c1655f2d1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-token.md @@ -0,0 +1,183 @@ +--- +title: token +description: The token extension displays a formatted view of a security token object. +ms.assetid: 3df89255-5e8c-4a09-9fe9-6977b26f5631 +keywords: ["token", "security token", "token Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- token +api_type: +- NA +--- + +# !token + + +The **!token** extension displays a formatted view of a security token object. + +Kernel-Mode Syntax: + +``` +!token [-n] [Address] +!token -? +``` + +User-Mode Syntax: + +``` +!token [-n] [Handle] +!token -? +``` + +## Parameters + + + *Address* +(Kernel mode only) Specifies the address of the token to be displayed. If this is 0 or omitted, the token for the active thread is displayed. + + *Handle* +(User mode only) Specifies the handle of the token to be displayed. If this is 0 or omitted, the token associated with the target thread is displayed. + + **-n** +(User mode only) Causes the display to include the friendly name. This includes the security identifier (SID) type, as well as the domain and user name for the SID. This option cannot be used when you are debugging LSASS. + + **-?** +Displays help text for this extension. + +### DLL + +Exts.dll + +The **!token** command is available in kernel-mode and live user-mode debugging. It cannot be used on user-mode dump files. + +### Additional Information + +For information about the kernel-mode TOKEN structure, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. For information about the user-mode TOKEN structure, see the Microsoft Windows SDK documentation. + +Remarks +------- + +The TOKEN structure is a security object type that represents an authenticated user process. Every process has an assigned token, which becomes the default token for each thread of that process. However, an individual thread can be assigned a token that overrides this default. + +You can get the token address from the output of [**!process**](-process.md). To display a list of the individual fields of the TOKEN structure, use the **dt nt!\_TOKEN** command. + +Here is an example: + +``` +kd> !process 81464da8 1 +PROCESS 81464da8 SessionId: 0 Cid: 03bc Peb: 7ffdf000 ParentCid: 0124 + DirBase: 0dec2000 ObjectTable: e1a31198 TableSize: 275. + Image: MSMSGS.EXE + VadRoot 81468cc0 Vads 170 Clone 0 Private 455. Modified 413. Locked 0. + DeviceMap e1958438 + Token e1bed030 + ElapsedTime 0:44:15.0142 + UserTime 0:00:00.0290 + KernelTime 0:00:00.0300 + QuotaPoolUsage[PagedPool] 49552 + QuotaPoolUsage[NonPagedPool] 10872 + Working Set Sizes (now,min,max) (781, 50, 345) (3124KB, 200KB, 1380KB) + PeakWorkingSetSize 1550 + VirtualSize 57 Mb + PeakVirtualSize 57 Mb + PageFaultCount 2481 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 2497 +kd> !exts.token -n e1bed030 +_TOKEN e1bed030 +TS Session ID: 0 +User: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser) +Groups: + 00 S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users) + Attributes - Mandatory Default Enabled + 01 S-1-1-0 (Well Known Group: localhost\Everyone) + Attributes - Mandatory Default Enabled + 02 S-1-5-32-544 (Alias: BUILTIN\Administrators) + Attributes - Mandatory Default Enabled Owner + 03 S-1-5-32-545 (Alias: BUILTIN\Users) + Attributes - Mandatory Default Enabled + 04 S-1-5-21-518066528-515770016-299552555-2999049 (Group: MYDOMAIN\AllUsers) + Attributes - Mandatory Default Enabled + 05 S-1-5-21-518066528-515770016-299552555-2931095 (Group: MYDOMAIN\SomeGroup1) + Attributes - Mandatory Default Enabled + 06 S-1-5-21-518066528-515770016-299552555-2931096 (Group: MYDOMAIN\SomeGroup2) + Attributes - Mandatory Default Enabled + 07 S-1-5-21-518066528-515770016-299552555-3014318 (Group: MYDOMAIN\SomeGroup3) + Attributes - Mandatory Default Enabled + 08 S-1-5-21-518066528-515770016-299552555-3053352 (Group: MYDOMAIN\Another Group) + Attributes - Mandatory Default Enabled + 09 S-1-5-21-518066528-515770016-299552555-2966661 (Group: MYDOMAIN\TestGroup) + Attributes - Mandatory Default Enabled + 10 S-1-5-21-2117033040-537160606-1609722162-17637 (Group: MYOTHERDOMAIN\someusers) + Attributes - Mandatory Default Enabled + 11 S-1-5-21-518066528-515770016-299552555-3018354 (Group: MYDOMAIN\TestGroup2) + Attributes - Mandatory Default Enabled + 12 S-1-5-21-518066528-515770016-299552555-3026602 (Group: MYDOMAIN\SomeGroup4) + Attributes - Mandatory Default Enabled + 13 S-1-5-21-518066528-515770016-299552555-2926570 (Group: MYDOMAIN\YetAnotherGroup) + Attributes - Mandatory Default Enabled + 14 S-1-5-21-661411660-2927047998-133698966-513 (Group: MYDOMAIN\Domain Users) + Attributes - Mandatory Default Enabled + 15 S-1-5-21-518066528-515770016-299552555-2986081 (Alias: MYDOMAIN\an_alias) + Attributes - Mandatory Default Enabled GroupResource + 16 S-1-5-21-518066528-515770016-299552555-3037986 (Alias: MYDOMAIN\AReallyLongGroupName1) + Attributes - Mandatory Default Enabled GroupResource + 17 S-1-5-21-518066528-515770016-299552555-3038991 (Alias: MYDOMAIN\AReallyLongGroupName2) + Attributes - Mandatory Default Enabled GroupResource + 18 S-1-5-21-518066528-515770016-299552555-3037999 (Alias: MYDOMAIN\AReallyLongGroupName3) + Attributes - Mandatory Default Enabled GroupResource + 19 S-1-5-21-518066528-515770016-299552555-3038983 (Alias: MYDOMAIN\AReallyReallyLongGroupName) + Attributes - Mandatory Default Enabled GroupResource + 20 S-1-5-5-0-71188 (no name mapped) + Attributes - Mandatory Default Enabled LogonId + 21 S-1-2-0 (Well Known Group: localhost\LOCAL) + Attributes - Mandatory Default Enabled + 22 S-1-5-4 (Well Known Group: NT AUTHORITY\INTERACTIVE) + Attributes - Mandatory Default Enabled + 23 S-1-5-11 (Well Known Group: NT AUTHORITY\Authenticated Users) + Attributes - Mandatory Default Enabled +Primary Group: S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users) +Privs: + 00 0x000000017 SeChangeNotifyPrivilege Attributes - Enabled Default + 01 0x000000008 SeSecurityPrivilege Attributes - + 02 0x000000011 SeBackupPrivilege Attributes - + 03 0x000000012 SeRestorePrivilege Attributes - + 04 0x00000000c SeSystemtimePrivilege Attributes - + 05 0x000000013 SeShutdownPrivilege Attributes - + 06 0x000000018 SeRemoteShutdownPrivilege Attributes - + 07 0x000000009 SeTakeOwnershipPrivilege Attributes - + 08 0x000000014 SeDebugPrivilege Attributes - + 09 0x000000016 SeSystemEnvironmentPrivilege Attributes - + 10 0x00000000b SeSystemProfilePrivilege Attributes - + 11 0x00000000d SeProfileSingleProcessPrivilege Attributes - + 12 0x00000000e SeIncreaseBasePriorityPrivilege Attributes - + 13 0x00000000a SeLoadDriverPrivilege Attributes - Enabled + 14 0x00000000f SeCreatePagefilePrivilege Attributes - + 15 0x000000005 SeIncreaseQuotaPrivilege Attributes - + 16 0x000000019 SeUndockPrivilege Attributes - Enabled + 17 0x00000001c SeManageVolumePrivilege Attributes - +Authentication ID: (0,11691) +Impersonation Level: Anonymous +TokenType: Primary +Source: User32 TokenFlags: 0x9 ( Token in use ) +Token ID: 18296 ParentToken ID: 0 +Modified ID: (0, 18298) +RestrictedSidCount: 0 RestrictedSids: 00000000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!token%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tokenfields.md b/windows-driver-docs-pr/debugger/-tokenfields.md new file mode 100644 index 0000000000..d5c313bb1b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tokenfields.md @@ -0,0 +1,100 @@ +--- +title: tokenfields +description: The tokenfields extension displays the names and offsets of the fields within the access token object (the TOKEN structure). +ms.assetid: dfadfdb0-1ed8-4c21-9207-dc02d7435475 +keywords: ["token", "tokenfields Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tokenfields +api_type: +- NA +--- + +# !tokenfields + + +The **!tokenfields** extension displays the names and offsets of the fields within the access token object (the TOKEN structure). + +``` +!tokenfields +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable (see the Remarks section)

+ +  + +### Additional Information + +For information about the TOKEN structure, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. This book may not be available in some languages and countries.(The user-mode token structures described in the Microsoft Windows SDK documentation are slightly different.) + +Remarks +------- + +This extension command is not available in Windows XP or later versions of Windows. Instead, use the [**dt (Display Type)**](dt--display-type-.md) command to show the TOKEN structure directly: + +``` +kd> dt nt!_TOKEN +``` + +To see a specific instance of the TOKEN structure, use the [**!token**](-token.md) extension. + +Here is an example of **!tokenfields** from a Windows 2000 system: + +``` +kd> !tokenfields + TOKEN structure offsets: + TokenSource: 0x0 + AuthenticationId: 0x18 + ExpirationTime: 0x28 + ModifiedId: 0x30 + UserAndGroupCount: 0x3c + PrivilegeCount: 0x44 + VariableLength: 0x48 + DynamicCharged: 0x4c + DynamicAvailable: 0x50 + DefaultOwnerIndex: 0x54 + DefaultDacl: 0x6c + TokenType: 0x70 + ImpersonationLevel: 0x74 + TokenFlags: 0x78 + TokenInUse: 0x79 + ProxyData: 0x7c + AuditData: 0x80 + VariablePart: 0x84 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tokenfields%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tp.md b/windows-driver-docs-pr/debugger/-tp.md new file mode 100644 index 0000000000..8b97cf3dd7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tp.md @@ -0,0 +1,143 @@ +--- +title: tp +description: The tp extension displays thread pool information. +ms.assetid: 33b22e04-b781-4890-8142-c2624fdc4055 +keywords: ["thread pool", "tp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tp +api_type: +- NA +--- + +# !tp + + +The **!tp** extension displays thread pool information. + +``` +!tp pool Address [Flags] +!tp tqueue Address [Flags] +!tp ItemType Address [Flags] +!tp ThreadType [Address] +!tp stats Address [Flags] +!tp wfac Address +!tp wqueue Address Priority Node +!tp -? +``` + +## Parameters + + + **pool** **** *Address* +Causes the entire thread pool at *Address* to be displayed. If *Address* is 0, then all thread pools will be displayed. + + **tqueue** **** *Address* +Causes the active timer queue at *Address* to be displayed. + + *ItemType Address* +Causes the specified thread pool item to be displayed. *Address* specifies the address of the item. *ItemType* specifies the type of the item; this can include any of the following possibilities: + +**obj** +A generic pool item (such as an IO item) will be displayed. + +**timer** +A timer item will be displayed. + +**wait** +A wait item will be displayed. + +**work** +A work item will be displayed. + + *ThreadType* \[*Address*\] +Causes threads of the specified type to be displayed. If *Address* is included and nonzero, then only the thread at this address is displayed. If *Address* is 0, all threads matching *ThreadType* are displayed. If *Address* is omitted, only the threads matching *ThreadType* associated with the current thread are displayed. *ThreadType* specifies the type of the thread to be displayed; this can include any of the following possibilities: + +**waiter** +A thread pool waiter thread will be displayed. + +**worker** +A thread pool worker thread will be displayed. + +**stats** **\[***Address***\]** +Causes the debug statistics of the current thread to be displayed. *Address* may be omitted, but if it is specified, it must equal -1 (negative one), to represent the current thread. + + **wfac** **** *Address* +(Windows 7 and later only) Causes the worker factory at *Address* to be displayed. The specified *Address* must be a valid nonzero address. + + **wqueue** **** *Address* +(Windows 7 and later only) Causes display of a work queue and NUMA node that matche the following: a specified priority, a specified NUMA node, and the pool, at a specified address, to which the NUMA node belongs. *Address* specifies the address of the pool. When the **wqueue** parameter is used, it must be followed by *Address*, *Priority*, and *Node*. + + *Priority* +(Windows 7 and later only) Specifies the priority levels of the work queues to be displayed. *Priority* can be any of the following values: + +**0** +Work queues with high priority are displayed. + +**1** +Work queues with normal priority are displayed. + +**2** +Work queues with low priority are displayed. + +**-1** +All work queues are displayed. + + *Node* +(Windows 7 and later only) Specifies a NUMA node belonging to the pool specified by *Address*. If *Node* is -1 (negative one), all NUMA nodes are displayed. + + *Flags* +Specifies what the display should contain. This can be a sum of any of the following bit values (the default is 0x0): + +Bit 0 (0x1) +Causes the display to be single-line output. This bit value has no effect on the output when an *ItemType* is displayed. + +Bit 1 (0x2) +Causes the display to include member information. + +Bit 2 (0x4) +This flag is relevant only when the **pool** option is used. In Windows XP, Windows Server 2003, Windows Vista, and Windows Server 2008, this flag causes the display to include the pool work queue. In Windows 7 and later, this flag causes the display to include all the pool's work queues that are at normal priority, and all NUMA nodes. + + **-?** +Displays a brief help text for this extension in the Debugger Command window. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Exts.dll

+ +  + +### Additional Information + +For information about thread pooling, see the Microsoft Windows SDK documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-trap--display-trap-frame-.md b/windows-driver-docs-pr/debugger/-trap--display-trap-frame-.md new file mode 100644 index 0000000000..d9050cafa7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-trap--display-trap-frame-.md @@ -0,0 +1,80 @@ +--- +title: .trap (Display Trap Frame) +description: The .trap command displays the trap frame register state and also sets the register context. +ms.assetid: c53177ad-243c-4276-8602-2edc14b44251 +keywords: ["Display Trap Frame (.trap) command", "trap frame", ".trap (Display Trap Frame) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .trap (Display Trap Frame) +api_type: +- NA +--- + +# .trap (Display Trap Frame) + + +The **.trap** command displays the trap frame register state and also sets the register context. + +``` +.trap [Address] +``` + +## Parameters + + + *Address* +Hexadecimal address of the trap frame on the target system. Omitting the address does not display any trap frame information, but it does reset the register context. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +The **.trap** command displays the important registers for the specified trap frame. + +This command also instructs the kernel debugger to use the specified context record as the register context. After this command is executed, the debugger will have access to the most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command ([**.thread**](-thread--set-register-context-.md), [**.cxr**](-cxr--display-context-record-.md), or **.trap**). See [Register Context](changing-contexts.md#register-context) for full details. + +This extension is commonly used when debugging bug check 0xA and 0x7F. For details and an example, see [**Bug Check 0xA**](bug-check-0xa--irql-not-less-or-equal.md) (IRQL\_NOT\_LESS\_OR\_EQUAL). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.trap%20%28Display%20Trap%20Frame%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-trap.md b/windows-driver-docs-pr/debugger/-trap.md new file mode 100644 index 0000000000..9137ae26b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-trap.md @@ -0,0 +1,29 @@ +--- +title: trap +description: trap +ms.assetid: 09f2d3e7-22a7-491c-a7ba-89fc934a6826 +keywords: ["trap extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !trap + + +## + + +The **!trap** extension command is obsolete. Use the [**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!trap%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-triage.md b/windows-driver-docs-pr/debugger/-triage.md new file mode 100644 index 0000000000..f693c350a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-triage.md @@ -0,0 +1,29 @@ +--- +title: triage +description: triage +ms.assetid: 5b52c470-0955-4ea6-859e-ac57447f6a2e +keywords: ["triage extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !triage + + +## + + +The **!triage** extension command is obsolete. Use [**!analyze**](-analyze.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!triage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tss--display-task-state-segment-.md b/windows-driver-docs-pr/debugger/-tss--display-task-state-segment-.md new file mode 100644 index 0000000000..2f5ac5389d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tss--display-task-state-segment-.md @@ -0,0 +1,72 @@ +--- +title: .tss (Display Task State Segment) +description: The .tss command displays a formatted view of the saved Task State Segment (TSS) information for the current processor. +ms.assetid: 3f73b7cf-56a8-434a-bc4d-2e8ab3af9f94 +keywords: ["Display Task State Segment (.tss) command", "task state segment (TSS)", "TSS (task state segment)", ".tss (Display Task State Segment) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .tss (Display Task State Segment) +api_type: +- NA +--- + +# .tss (Display Task State Segment) + + +The **.tss** command displays a formatted view of the saved Task State Segment (TSS) information for the current processor. + +``` +.tss [Address] +``` + +## Parameters + + + *Address* +Address of the TSS. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

kernel mode only

Targets

live, crash dump

Platforms

x86 only

+ +  + +Remarks +------- + +The address of the TSS can be found by examining the output of the [**!pcr**](-pcr.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.tss%20%28Display%20Task%20State%20Segment%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tss.md b/windows-driver-docs-pr/debugger/-tss.md new file mode 100644 index 0000000000..5fbb9b9988 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tss.md @@ -0,0 +1,29 @@ +--- +title: tss +description: tss +ms.assetid: 6b6109bf-8438-4cf5-963a-f2d1a5317c4e +keywords: ["tss extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !tss + + +## + + +The **!tss** extension command is obsolete. Use the [**.tss (Display Task State Segment)**](-tss--display-task-state-segment-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tss%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ttime--display-thread-times-.md b/windows-driver-docs-pr/debugger/-ttime--display-thread-times-.md new file mode 100644 index 0000000000..65419afa27 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ttime--display-thread-times-.md @@ -0,0 +1,80 @@ +--- +title: .ttime (Display Thread Times) +description: The .ttime command displays the running times for a thread. +ms.assetid: ff48310f-3eb9-4112-b5ab-b7c16878ac8f +keywords: [".ttime (Display Thread Times) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .ttime (Display Thread Times) +api_type: +- NA +--- + +# .ttime (Display Thread Times) + + +The **.ttime** command displays the running times for a thread. + +``` +.ttime +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode only

Targets

live, crash dump

Platforms

x86 only

+ +  + +Remarks +------- + +This command only works in user mode. In kernel mode you should use [**!thread**](-thread.md) instead. This command works with user-mode minidumps as long as they were created with the **/mt** or **/ma** options; see [Minidumps](minidumps.md) for details. + +The **.ttime** command shows the creation time of the thread, as well as the amount of time it has been running in kernel mode and in user mode. + +Here is an example: + +``` +0:000> .ttime +Created: Sat Jun 28 17:58:42 2003 +Kernel: 0 days 0:00:00.131 +User: 0 days 0:00:02.109 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.ttime%20%28Display%20Thread%20Times%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-typeopt--set-type-options-.md b/windows-driver-docs-pr/debugger/-typeopt--set-type-options-.md new file mode 100644 index 0000000000..19010f44e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-typeopt--set-type-options-.md @@ -0,0 +1,109 @@ +--- +title: .typeopt (Set Type Options) +description: The .typeopt command sets or displays the type options. +ms.assetid: 17842897-26e3-4b61-aa65-e5cfe8576324 +keywords: [".typeopt (Set Type Options) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .typeopt (Set Type Options) +api_type: +- NA +--- + +# .typeopt (Set Type Options) + + +The **.typeopt** command sets or displays the type options. + +``` +.typeopt +Flags +.typeopt -Flags +.typeopt +FlagName +.typeopt -FlagName +.typeopt +``` + +## Parameters + + + **+** +Causes the type options specified by *FlagName* to be set. + + **-** +Causes the type options specified by *FlagName* to be cleared. + + *Flags* +Specifies the type options to be changed. *FlagName* can be a sum of any of the following values (there is no default): + +**0x1** +Displays values in all Watch windows and the Locals window as having UNICODE data type. + +**0x2** +Displays values in all Watch windows and the Locals window as having LONG data type. + +**0x4** +Displays integers in all Watch windows and the Locals window in the default radix. + +**0x8** +Causes the debugger to choose the matching symbol with the largest size when the Locals window or Watch window references a symbol by name but there is more than one symbol that matches this name. The size of a symbol is defined as follows: if the symbol is the name of a function, its size is the size of the function in memory. Otherwise, the size of the symbol is the size of the data type that it represents. + + *FlagName* +Specifies the type options to be changed. *FlagName* can be any one of the following strings (there is no default): + +**uni** +Displays values in all Watch windows and the Locals window as having UNICODE data type. (This has the same effect as **0x1**.) + +**longst** +Displays values in all Watch windows and the Locals window as having LONG data type. (This has the same effect as **0x2**.) + +**radix** +Displays integers in all Watch windows and the Locals window in the default radix. (This has the same effect as **0x4**.) + +**size** +Causes the debugger to choose the matching symbol with the largest size when the Locals window or Watch window references a symbol by name but there is more than one symbol that matches this name. The size of a symbol is defined as follows: if the symbol is the name of a function, its size is the size of the function in memory. Otherwise, the size of the symbol is the size of the data type that it represents. (This has the same effect as **0x8**.) + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +Without any arguments, **.typeopt** displays the current symbol options. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.typeopt%20%28Set%20Type%20Options%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tz.md b/windows-driver-docs-pr/debugger/-tz.md new file mode 100644 index 0000000000..6b1dc64f9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tz.md @@ -0,0 +1,72 @@ +--- +title: tz +description: The tz extension displays the specified power thermal zone structure. +ms.assetid: f3cc9e54-a0db-4095-b707-380ec1dacf59 +keywords: ["thermal zone", "tz Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tz +api_type: +- NA +--- + +# !tz + + +The **!tz** extension displays the specified power thermal zone structure. + +``` +!tz [Address] +``` + +## Parameters + + + *Address* +The address of a power thermal zone that you want to display. If this parameter is omitted, the display includes all thermal zones on the target computer. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +To view the system's power capabilities, use the [**!pocaps**](-pocaps.md) extension command. To view the system's power policy, use the [**!popolicy**](-popolicy.md) extension command. For information about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +To stop execution at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tz%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-tzinfo.md b/windows-driver-docs-pr/debugger/-tzinfo.md new file mode 100644 index 0000000000..311a660b49 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-tzinfo.md @@ -0,0 +1,67 @@ +--- +title: tzinfo +description: The tzinfo extension displays the contents of the specified thermal zone information structure. +ms.assetid: a30826d8-b7c5-4fbc-a3c3-b7a994eaf7fe +keywords: ["thermal zone information", "tzinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tzinfo +api_type: +- NA +--- + +# !tzinfo + + +The **!tzinfo** extension displays the contents of the specified thermal zone information structure. + +``` +!tzinfo Address +``` + +## Parameters + + + *Address* +The address of a thermal zone information structure that you want to display. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +To view the system's power capabilities, use the [**!pocaps**](-pocaps.md) extension command. To view the system's power policy, use the [**!popolicy**](-popolicy.md) extension command. For information about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!tzinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-u--unfreeze-thread-.md b/windows-driver-docs-pr/debugger/-u--unfreeze-thread-.md new file mode 100644 index 0000000000..0352842506 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-u--unfreeze-thread-.md @@ -0,0 +1,104 @@ +--- +title: ~u (Unfreeze Thread) +description: The ~u command unfreezes the specified thread.Do not confuse this command with the U (Unassemble) command. +ms.assetid: 6ac3c84a-3734-4b16-a239-4233e186c2df +keywords: ["~u (Unfreeze Thread) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ~u (Unfreeze Thread) +api_type: +- NA +--- + +# ~u (Unfreeze Thread) + + +The **~u** command unfreezes the specified thread. + +Do not confuse this command with the [**U (Unassemble)**](u--unassemble-.md) command. + +``` +~Thread u +``` + +## Parameters + + + *Thread* +Specifies the thread or threads to unfreeze. For more information about the syntax, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how frozen threads behave and a list of other commands that control the freezing and suspending of threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +Remarks +------- + +You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor. + +The following examples show you how to use the ~ commands. + +The following command displays the current status of all threads. + +``` +0:000> ~* k +``` + +The following command freeze the thread that caused the current exception. + +``` +0:000> ~# f +``` + +The following command checks that the status of this thread is suspended. + +``` +0:000> ~* k +``` + +The following command unfreezes thread number 123. + +``` +0:000> ~123 u +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20~u%20%28Unfreeze%20Thread%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-ubc.md b/windows-driver-docs-pr/debugger/-ubc.md new file mode 100644 index 0000000000..9ac9481df2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ubc.md @@ -0,0 +1,82 @@ +--- +title: ubc +description: The ubc extension clears a user-space breakpoint. +ms.assetid: 4BF2C589-A1C4-4714-B712-DD52D04704D1 +keywords: ["ubc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ubc +api_type: +- NA +--- + +# !ubc + + +The **!ubc** extension clears a user-space breakpoint. + +``` +!ubc BreakpointNumber +``` + +## Parameters + + + *BreakpointNumber* +Specifies the number of the breakpoint to be cleared. An asterisk (\*) indicates all breakpoints. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +This will permanently delete a breakpoint set with [**!ubp**](-ubp.md). + +## See also + + +[**!ubd**](-ubd.md) + +[**!ube**](-ube.md) + +[**!ubl**](-ubl.md) + +[**!ubp**](-ubp.md) + +[User Space and System Space](user-space-and-system-space.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ubc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ubd.md b/windows-driver-docs-pr/debugger/-ubd.md new file mode 100644 index 0000000000..3c8eed6e65 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ubd.md @@ -0,0 +1,82 @@ +--- +title: ubd +description: The ubd extension temporarily disables a user-space breakpoint. +ms.assetid: a639c5e0-111c-45c7-ac7d-6b7e70c1de4f +keywords: ["ubd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ubd +api_type: +- NA +--- + +# !ubd + + +The **!ubd** extension temporarily disables a user-space breakpoint. + +``` +!ubd BreakpointNumber +``` + +## Parameters + + + *BreakpointNumber* +Specifies the number of the breakpoint to be disabled. An asterisk (\*) indicates all breakpoints. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Disabled breakpoints will be ignored. Use [**!ube**](-ube.md) to re-enable the breakpoint. + +## See also + + +[**!ubc**](-ubc.md) + +[**!ube**](-ube.md) + +[**!ubl**](-ubl.md) + +[**!ubp**](-ubp.md) + +[User Space and System Space](user-space-and-system-space.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ubd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ube.md b/windows-driver-docs-pr/debugger/-ube.md new file mode 100644 index 0000000000..c59ad1c637 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ube.md @@ -0,0 +1,82 @@ +--- +title: ube +description: The ube extension re-enables a user-space breakpoint. +ms.assetid: caa13c30-e03a-44fd-9221-66e44eec88af +keywords: ["ube Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ube +api_type: +- NA +--- + +# !ube + + +The **!ube** extension re-enables a user-space breakpoint. + +``` +!ube BreakpointNumber +``` + +## Parameters + + + *BreakpointNumber* +Specifies the number of the breakpoint to be enabled. An asterisk (\*) indicates all breakpoints. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +This is used to re-enable a breakpoint that was disabled by [**!ubd**](-ubd.md). + +## See also + + +[**!ubc**](-ubc.md) + +[**!ubd**](-ubd.md) + +[**!ubl**](-ubl.md) + +[**!ubp**](-ubp.md) + +[User Space and System Space](user-space-and-system-space.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ube%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ubl.md b/windows-driver-docs-pr/debugger/-ubl.md new file mode 100644 index 0000000000..21df201996 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ubl.md @@ -0,0 +1,95 @@ +--- +title: ubl +description: The ubl extension lists all user-space breakpoints and their current status. +ms.assetid: c2c40fa5-888f-49bb-a616-a139d7d2874d +keywords: ["breakpoints, user-space breakpoints", "ubl Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ubl +api_type: +- NA +--- + +# !ubl + + +The **!ubl** extension lists all user-space breakpoints and their current status. + +``` +!ubl +``` + +## + + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +Here is an example of the use and display of user-space breakpoints: + +``` +kd> !ubp 8014a131 +This command is VERY DANGEROUS, and may crash your system! +If you don't know what you are doing, enter "!ubc *" now! + +kd> !ubp 801544f4 + +kd> !ubd 1 + +kd> !ubl + 0: e ffffffff`8014a131 (ffffffff`82deb000) 1 ffffffff + 1: d ffffffff`801544f4 (ffffffff`82dff000) 0 ffffffff +``` + +Each line in this listing contains the breakpoint number, the status (**e** for enabled or **d** for disabled), the virtual address used to set the breakpoint, the physical address of the actual breakpoint, the byte position, and the contents of this memory location at the time the breakpoint was set. + +## See also + + +[**!ubc**](-ubc.md) + +[**!ubd**](-ubd.md) + +[**!ube**](-ube.md) + +[**!ubp**](-ubp.md) + +[User Space and System Space](user-space-and-system-space.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ubl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ubp.md b/windows-driver-docs-pr/debugger/-ubp.md new file mode 100644 index 0000000000..472b1bd762 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ubp.md @@ -0,0 +1,90 @@ +--- +title: ubp +description: The ubp extension sets a breakpoint in user space. +ms.assetid: 1aaa6bec-59d3-4e37-a1c6-af3554da809f +keywords: ["ubp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ubp +api_type: +- NA +--- + +# !ubp + + +The **!ubp** extension sets a breakpoint in user space. + +``` +!ubp Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal virtual address of the location in user space where the breakpoint is to be set. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The **!ubp** extension sets a breakpoint in user space. The breakpoint is set on the actual physical page, not just the virtual page. + +Setting a physical breakpoint will simultaneously modify every virtual copy of a page, with unpredictable results. One possible consequence is corruption of the system state, possibly followed by a bug check or other system crash. Therefore, these breakpoints should be used cautiously, if at all. + +This extension cannot be used to set breakpoints on pages that have been swapped out of memory. If a page is swapped out of memory after a breakpoint is set, the breakpoint ceases to exist. + +It is not possible to set a breakpoint inside a page table or a page directory. + +Each breakpoint is assigned a *breakpoint number*. To find out the breakpoint number assigned, use [**!ubl**](-ubl.md). Breakpoints are enabled upon creation. To step over a breakpoint, you must first disable it by using [**!ubd**](-ubd.md). To clear a breakpoint, use [**!ubc**](-ubc.md). + +## See also + + +[**!ubc**](-ubc.md) + +[**!ubd**](-ubd.md) + +[**!ube**](-ube.md) + +[**!ubl**](-ubl.md) + +[User Space and System Space](user-space-and-system-space.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ubp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-uniqstack.md b/windows-driver-docs-pr/debugger/-uniqstack.md new file mode 100644 index 0000000000..dbfd596f36 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-uniqstack.md @@ -0,0 +1,123 @@ +--- +title: uniqstack +description: The uniqstack extension displays all of the stacks for all of the threads in the current process, excluding stacks that appear to have duplicates. +ms.assetid: c7502106-90b7-4fec-aa6b-394967ed2cfb +keywords: ["uniqstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- uniqstack +api_type: +- NA +--- + +# !uniqstack + + +The **!uniqstack** extension displays all of the stacks for all of the threads in the current process, excluding stacks that appear to have duplicates. + +``` +!uniqstack [ -b | -v | -p ] [ -n ] +``` + +## Parameters + + + **-b** +Causes the display to include the first three parameters passed to each function. + + **-v** +Causes the display to include frame pointer omission (FPO) information. On x86-based processors, the calling convention information is also displayed. + + **-p** +Causes the display to include the full parameters for each function that is called in the stack trace. This listing will include each parameter's data type, name, and value. *This requires full symbol information.* + + **-n** +Causes frame numbers to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Uext.dll

Windows XP and later

Uext.dll

+ +  + +Remarks +------- + +This extension is similar to the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command, except that it does not display duplicate stacks. + +For example: + +``` +0:000> !uniqstack +Processing 14 threads, please wait + +. 0 Id: f0f0f0f0.15c Suspend: 1 Teb: 00000000`7fff8000 Unfrozen + Priority: 0 +Child-SP Child-BSP RetAddr +00000000`0006e5e0 00000000`00070420 00000000`6b009840 +00000000`0006e600 00000000`000703d0 00000000`6b03db00 +00000000`0006e950 00000000`000703b0 00000000`6b008520 +00000000`0006e950 00000000`00070368 00000000`6b1845e0 +00000000`0006e9b0 00000000`00070310 00000000`6b009980 +00000000`0006e9d0 00000000`000702d0 00000000`6b009ff0 +00000000`0006e9e0 00000000`00070248 00000000`77ea4a10 +00000000`0006f290 00000000`000700e0 00000000`77ea5d60 +00000000`0006f4c0 00000000`00070028 00000000`77ed6000 +00000000`0006f550 00000000`00070000 00000000`77ed9000 +00000000`0006f550 00000000`00070000 00000000`77ca78a0 +00000000`0006fff0 00000000`00070000 00000000`00000000 + +. 1 Id: f0f0f0f0.718 Suspend: 1 Teb: 00000000`7fff4000 Unfrozen + Priority: 0 +Child-SP Child-BSP RetAddr +00000000`0043eb50 00000000`00440250 00000000`6b008520 +00000000`0043eb80 00000000`00440208 00000000`6b1845e0 +00000000`0043ebe0 00000000`004401a8 00000000`6b009980 +00000000`0043ec00 00000000`00440168 00000000`6b009ff0 +00000000`0043ec10 00000000`004400e0 00000000`77ea5f50 +00000000`0043f4c0 00000000`00440028 00000000`77ed6000 +00000000`0043f550 00000000`00440000 00000000`77ed9000 +00000000`0043f550 00000000`00440000 00000000`7de05690 +00000000`0043fff0 00000000`00440000 00000000`00000000 + +. 13 Id: f0f0f0f0.494 Suspend: 1 Teb: 00000000`7ef98000 Unfrozen + Priority: 0 +Child-SP Child-BSP RetAddr +00000000`00feffe0 00000000`00ff0040 00000000`77e94f30 +00000000`00feffe0 00000000`00ff0040 00000000`00000000 + +Total threads: 14 +Duplicate callstacks: 11 (windbg thread #s follow): +2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!uniqstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-unload--unload-extension-dll-.md b/windows-driver-docs-pr/debugger/-unload--unload-extension-dll-.md new file mode 100644 index 0000000000..3550c7c197 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-unload--unload-extension-dll-.md @@ -0,0 +1,77 @@ +--- +title: .unload (Unload Extension DLL) +description: The .unload command unloads an extension DLL from the debugger. +ms.assetid: 8399e4a8-0265-4690-b35f-973b69fe2764 +keywords: ["Unload Extension DLL (.unload) command", "extension commands ( commands), Unload Extension DLL (.unload) command", ".unload (Unload Extension DLL) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .unload (Unload Extension DLL) +api_type: +- NA +--- + +# .unload (Unload Extension DLL) + + +The **.unload** command unloads an extension DLL from the debugger. + +``` +.unload DLLName +!DLLName.unload +``` + +## Parameters + + + *DLLName* +Specifies the file name of the debugger extension DLL to be unloaded. If the full path was specified when the DLL was loaded, it needs to be given in full here as well. If *DLLName* is omitted, the current extension DLL is unloaded. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more details on loading, unloading, and controlling extensions, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +Remarks +------- + +This command is useful when testing an extension you are creating. When the extension is recompiled, you must unload and then load the new DLL. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.unload%20%28Unload%20Extension%20DLL%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-unloadall--unload-all-extension-dlls-.md b/windows-driver-docs-pr/debugger/-unloadall--unload-all-extension-dlls-.md new file mode 100644 index 0000000000..6470387321 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-unloadall--unload-all-extension-dlls-.md @@ -0,0 +1,68 @@ +--- +title: .unloadall (Unload All Extension DLLs) +description: The .unloadall command unloads all extension DLLs from the debugger on the host system. +ms.assetid: 0d0c98bd-af53-4755-ae3b-35d79b37dea0 +keywords: ["Unload All Extension DLLs (.unloadall) command", "extension commands ( commands), Unload All Extension DLLs (.unloadall) command", ".unloadall (Unload All Extension DLLs) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .unloadall (Unload All Extension DLLs) +api_type: +- NA +--- + +# .unloadall (Unload All Extension DLLs) + + +The **.unloadall** command unloads all extension DLLs from the debugger on the host system. + +``` +.unloadall +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For more details on loading, unloading, and controlling extensions, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.unloadall%20%28Unload%20All%20Extension%20DLLs%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-urb.md b/windows-driver-docs-pr/debugger/-urb.md new file mode 100644 index 0000000000..845de5c7ca --- /dev/null +++ b/windows-driver-docs-pr/debugger/-urb.md @@ -0,0 +1,26 @@ +--- +title: urb +description: urb +ms.assetid: 5eb68a56-af44-4a99-81cf-fb556fec0e2e +keywords: ["urb extension (obsolete)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# !urb + + +The **!urb** extension command is obsolete. Use the [**dt URB**](dt--display-type-.md) command instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!urb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-urestart--unregister-for-restart-.md b/windows-driver-docs-pr/debugger/-urestart--unregister-for-restart-.md new file mode 100644 index 0000000000..9ad71e9015 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-urestart--unregister-for-restart-.md @@ -0,0 +1,47 @@ +--- +title: .urestart (Unregister for Restart) +description: The .urestart command unregisters the debugging session for restart in case of a reboot or an application failure. +ms.assetid: B3881CD6-F5F4-40E2-B0E1-BAC7D19E8724 +keywords: [".urestart (Unregister for Restart) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .urestart (Unregister for Restart) +api_type: +- NA +--- + +# .urestart (Unregister for Restart) + + +The **.urestart** command unregisters the debugging session for restart in case of a reboot or an application failure. + +``` +.urestart +``` + +Remarks +------- + +This command does not work for elevated debugger sessions. + +## See also + + +[**.rrestart**](-rrestart--register-for-restart-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.urestart%20%28Unregister%20for%20Restart%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-device-info-from-pdo.md b/windows-driver-docs-pr/debugger/-usb3kd-device-info-from-pdo.md new file mode 100644 index 0000000000..d142d99fe5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-device-info-from-pdo.md @@ -0,0 +1,155 @@ +--- +title: usb3kd.device_info_from_pdo +description: The usb3kd.device_info_from_pdo command displays information about a USB device in the USB 3.0 tree. +ms.assetid: 74FD68E6-78DF-452F-80C2-91A37877DE52 +keywords: ["usb3kd.device_info_from_pdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.device_info_from_pdo +api_type: +- NA +--- + +# !usb3kd.device\_info\_from\_pdo + + +The **!usb3kd.device\_info\_from\_pdo** command displays information about a USB device in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). + +``` +!usb3kd.device_info_from_pdo DeviceObject +``` + +## Parameters + + + *DeviceObject* +Address of the physical device object (PDO) of a USB device or hub. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +**!device\_info\_from\_pdo** and [**!ucx\_device**](-usb3kd-ucx-device.md) both display information about a device, but the information displayed is different. The output of **!device\_info\_from\_pdo** is from the point of view of the USB 3.0 hub driver, and the output of **!ucx\_device** is from the point of view of the USB host controller extension driver. For example, the **!device\_info\_from\_pdo** output includes information about configuration and interface descriptors, and **!ucx\_device** output includes information about endpoints. + +Examples +-------- + +You can get the address of the PDO from the output of [**!usb\_tree**](-usb3kd-usb-tree.md) or from a variety of other debugger commands. For example, the [**!devnode**](-devnode.md) command displays the addresses of PDOs. In the following example, the USBSTOR device node is the direct child of the USBHUB3 node. The address of the PDO for the USBSTOR node is 0xfffffa80059c3800. + +``` +3: kd> !devnode 0 1 usbhub3 + +Dumping IopRootDeviceNode (= 0xfffffa8003609cc0) +DevNode 0xfffffa8005981730 for PDO 0xfffffa8004ffc550 + InstancePath is "USB\ROOT_HUB30\5&11db9684&0&0" + ServiceName is "USBHUB3" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + + DevNode 0xfffffa8005a546a0 for PDO 0xfffffa80059c3800 + InstancePath is "USB\VID_125F&PID_312A\09021000000000000342192873" + ServiceName is "USBSTOR" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + + DevNode 0xfffffa8005a09730 for PDO 0xfffffa8005b3a650 + InstancePath is "USBSTOR\Disk&Ven ... + ServiceName is "disk" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) +``` + +Now you can pass the address of the PDO to the **!usb3kd.device\_info\_from\_pdo** command. + +``` +3: kd> !device_info_from_pdo 0xfffffa80059c3800 + +## Dumping Device Information fffffa80059c3800 +------------------------------------------- +!devobj 0xfffffa8004ffc550 (Root HUB) +!device_info 0xfffffa8005abd0c0 (dt usbhub3!_DEVICE_CONTEXT 0xfffffa8005abd0c0) +dt USBHUB3!_DEVICE_CONTEXT 0xfffffa8005abd0c0 +dt USBHUB3!_HUB_PDO_CONTEXT 0xfffffa8005b118d0 +!idle_info 0xfffffa8005b11920 (dt USBHUB3!_ISM_CONTEXT 0xfffffa8005b11920) +Parent !hub_info 0xfffffa8005ad92d0 (dt USBHUB3!_HUB_FDO_CONTEXT 0xfffffa8005ad92d0) +!port_info 0xfffffa8005abe0c0 (dt USBHUB3!_PORT_CONTEXT 0xfffffa8005abe0c0) +!ucx_device 0xfffffa8005992840 !xhci_deviceslots 0xfffffa80051d1940 1 + +LPMState: U1IsEnabledForUpStreamPort U2IsEnabledForUpStreamPort U1Timeout: 38, U2Timeout: 3 +DeviceFlags: HasContainerId NoBOSContainerId Removable HasSerialNumber MsOsDescriptorNotSupported NoWakeUpSupport DeviceIsSuperSpeedCapable +DeviceHackFlags: WillDisableOnSoftRemove SkipSetIsochDelay WillResetOnResumeS0 DisableOnSoftRemove + +Descriptors: +dt _USB_CONFIGURATION_DESCRIPTOR 0xfffffa80053f9250 +dt _USB_INTERFACE_DESCRIPTOR 0xfffffa80053f9259 +ProductId: ... +DeviceDescriptor: VID ... + +UcxRequest: !wdfrequest 0x57ffa662948, +ControlRequest: !wdfrequest 0x57ffa667798, !irp 0xfffffa8005997650 !urb 0xfffffa8005abd1c0, NumberOfBytes 0 +Device working at SuperSpeed +Current Device State: ConfiguredInD0 + +Device State History: NewState ((),..) : + + [16] ConfiguredInD0 + ... +Device Event History: + [10] TransferSuccess + ... +``` + +The following example shows some of the output of the [**!usb\_tree**](-usb3kd-usb-tree.md) command. You can see the address of the PDO of one of the child device nodes as the argument to the [**!devstack**](-devstack.md) command. (**!devstack fffffa80059c3800**) + +``` +3: kd> !usb_tree + +## Dumping HUB Tree - !drvObj 0xfffffa800597f770 +-------------------------------------------- + +Topology +-------- +1) !xhci_info 0xfffffa80051d1940 ... - PCI: VendorId ... + !hub_info 0xfffffa8005ad92d0 (ROOT) + !port_info 0xfffffa8005a5ca80 !device_info 0xfffffa8005b410c0 Desc: Speed: High + ... +## Enumerated Device List +---------------------- +... + +2) !device_info 0xfffffa8005abd0c0, !devstack fffffa80059c3800 + Current Device State: ConfiguredInD0 + Desc: ... Flash Drive + USB\VID_... + !ucx_device 0xfffffa8005992840 !xhci_deviceslots 0xfffffa80051d1940 1 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.device\_info**](-usb3kd-device-info.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.device_info_from_pdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-device-info.md b/windows-driver-docs-pr/debugger/-usb3kd-device-info.md new file mode 100644 index 0000000000..6b73689a98 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-device-info.md @@ -0,0 +1,126 @@ +--- +title: usb3kd.device_info +description: The usb3kd.device_info command displays information about a USB device in the USB 3.0 tree. +ms.assetid: BD6D1562-2606-42C1-9EE6-D38D93D685DE +keywords: ["usb3kd.device_info Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.device_info +api_type: +- NA +--- + +# !usb3kd.device\_info + + +The **!usb3kd.device\_info** command displays information about a USB device in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). + +``` +!usb3kd.device_info DeviceContext +``` + +## Parameters + + + *DeviceContext* +Address of the \_DEVICE\_CONTEXT structure that represents the device. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +**!device\_info** and [**!ucx\_device**](-usb3kd-ucx-device.md) both display information about a device, but the information displayed is different. The output of **!device\_info** is from the point of view of the USB 3.0 hub driver, and the output of **!ucx\_device** is from the point of view of the USB host controller extension driver. For example, the **!device\_info** output includes information about configuration and interface descriptors, and **!ucx\_device** output includes information about endpoints. + +Examples +-------- + +You can obtain the address of the device context structure by looking at the output of the [**!usb\_tree**](-usb3kd-usb-tree.md) command. In the following example, the address of the device context structure is 0xfffffa8005abd0c0. + +``` +3: kd> !usb_tree + +## Dumping HUB Tree - !drvObj 0xfffffa800597f770 +-------------------------------------------- + +Topology +-------- +1) !xhci_info 0xfffffa80051d1940 ... - PCI: VendorId ... + !hub_info 0xfffffa8005ad92d0 (ROOT) + ... +## Enumerated Device List +---------------------- +... + +2) !device_info 0xfffffa8005abd0c0, !devstack fffffa80059c3800 + Current Device State: ConfiguredInD0 + Desc: ... USB Flash Drive + ... +``` + +Now you can pass the address of the device context to the **!device\_info** command. + +``` +3: kd> !device_info 0xfffffa8005abd0c0 + +## Dumping Device Information fffffa8005abd0c0 +------------------------------------------- +dt USBHUB3!_DEVICE_CONTEXT 0xfffffa8005abd0c0 +dt USBHUB3!_HUB_PDO_CONTEXT 0xfffffa8005b118d0 +!idle_info 0xfffffa8005b11920 (dt USBHUB3!_ISM_CONTEXT 0xfffffa8005b11920) +Parent !hub_info 0xfffffa8005ad92d0 (dt USBHUB3!_HUB_FDO_CONTEXT 0xfffffa8005ad92d0) +!port_info 0xfffffa8005abe0c0 (dt USBHUB3!_PORT_CONTEXT 0xfffffa8005abe0c0) +!ucx_device 0xfffffa8005992840 !xhci_deviceslots 0xfffffa80051d1940 1 + +LPMState: U1IsEnabledForUpStreamPort U2IsEnabledForUpStreamPort U1Timeout: 38, U2Timeout: 3 +DeviceFlags: HasContainerId NoBOSContainerId Removable HasSerialNumber MsOsDescriptorNotSupported NoWakeUpSupport DeviceIsSuperSpeedCapable +DeviceHackFlags: WillDisableOnSoftRemove SkipSetIsochDelay WillResetOnResumeS0 DisableOnSoftRemove + +Descriptors: +dt _USB_CONFIGURATION_DESCRIPTOR 0xfffffa80053f9250 +dt _USB_INTERFACE_DESCRIPTOR 0xfffffa80053f9259 +ProductId: ... Flash Drive +DeviceDescriptor: VID ... PID ... REV 0a00, Class: (0)(0) BcdUsb: 0300 + +UcxRequest: !wdfrequest 0x57ffa662948, +ControlRequest: !wdfrequest 0x57ffa667798, !irp 0xfffffa8005997650 !urb 0xfffffa8005abd1c0, NumberOfBytes 0 +Device working at SuperSpeed +Current Device State: ConfiguredInD0 + +Device State History: NewState ((),..) : + + [16] ConfiguredInD0 + ... +Device Event History: + [10] TransferSuccess + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.device\_info\_from\_pdo**](-usb3kd-device-info-from-pdo.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.device_info%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-dsf.md b/windows-driver-docs-pr/debugger/-usb3kd-dsf.md new file mode 100644 index 0000000000..486320c198 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-dsf.md @@ -0,0 +1,49 @@ +--- +title: usb3kd.dsf +description: The usb3kd.dsf extension is a toggle command that sets the debugger context to debug the DSF host driver. +ms.assetid: 1A1A7B9A-B05C-4AE8-8C26-A340DFC9613E +keywords: ["usb3kd.dsf Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.dsf +api_type: +- NA +--- + +# !usb3kd.dsf + + +The [**!usb3kd.dsf**](-usb3kd-device-info.md) extension is a toggle command that sets the debugger context to debug the DSF host driver. + +``` +!usb3kd.dsf +``` + +## DLL + + +Usb3kd.dll + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.dsf%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-help.md b/windows-driver-docs-pr/debugger/-usb3kd-help.md new file mode 100644 index 0000000000..79ca556f38 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-help.md @@ -0,0 +1,43 @@ +--- +title: usb3kd.help +description: The usb3kd.help command displays help for the USB 3 debugger extension commands. +ms.assetid: 55A40718-1178-4E7B-8210-BDEB6386AE8D +keywords: ["usb3kd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.help +api_type: +- NA +--- + +# !usb3kd.help + + +The **!usb3kd.help** command displays help for the USB 3 debugger extension commands. + +## DLL + + +Usb3kd.dll + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-hub-info-from-fdo.md b/windows-driver-docs-pr/debugger/-usb3kd-hub-info-from-fdo.md new file mode 100644 index 0000000000..74755bf469 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-hub-info-from-fdo.md @@ -0,0 +1,115 @@ +--- +title: usb3kd.hub_info_from_fdo +description: The usb3kd.hub_info_from_fdo command displays information about a hub in the USB 3.0 tree. +ms.assetid: 07A1C3EC-76A9-49A5-8467-53FCE3667203 +keywords: ["usb3kd.hub_info_from_fdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.hub_info_from_fdo +api_type: +- NA +--- + +# !usb3kd.hub\_info\_from\_fdo + + +The **!usb3kd.hub\_info\_from\_fdo** command displays information about a hub in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). + +``` +!usb3kd.hub_info_from_fdo DeviceObject +``` + +## Parameters + + + *DeviceObject* +Address of the functional device object (FDO) that represents the hub. + +## DLL + + +Usb3kd.dll + +Examples +-------- + +You can get the address of the FDO from the output of [**!usb\_tree**](-usb3kd-usb-tree.md) or from a variety of other debugger commands. For example, the [**!devstack**](-devstack.md) command displays the address of the FDO. In the following example, the address of the FDO is fffffa800597a660. + +``` +3: kd> !devnode 0 1 usbhub3 +Dumping IopRootDeviceNode (= 0xfffffa8003609cc0) +DevNode 0xfffffa8005981730 for PDO 0xfffffa8004ffc550 +... +3: kd> !devstack 0xfffffa8004ffc550 + !DevObj !DrvObj !DevExt ObjectName + fffffa800597a660 \Driver\USBHUB3 fffffa8005ad92d0 +> fffffa8004ffc550 \Driver\USBXHCI fffffa8005251d00 USBPDO-0 +... +``` + +Now you can pass the address of the FDO to the **!usb3kd.hub\_info\_from\_fdo** command. + +``` + 3: kd> !hub_info_from_fdo fffffa800597a660 + +## Dumping HUB Information fffffa800597a660 +---------------------------------------- +dt USBHUB3!_HUB_FDO_CONTEXT 0xfffffa8005ad92d0 +!rcdrlogdump usbhub3 -a 0xfffffa8005ad8010 +Capabilities: Initialized, Configured, HasOverCurrentProtection, SelectiveSuspendSupportedByParentStack, CannotWakeOnConnect, NotArmedForWake + +Total number of ports: 4, HUB depth is 0 +Number of 3.0 ports: 2 (Range 1 - 2) +Number of 2.0 ports: 2 (Range 3 - 4) + +Descriptors: + dt _USB_HUB_DESCRIPTOR 0xfffffa8005ad9728 + dt _USB_30_HUB_DESCRIPTOR 0xfffffa8005ad9728 + dt _USB_DEVICE_DESCRIPTOR 0xfffffa8005ad92d0 + dt _USB_CONFIGURATION_DESCRIPTOR 0xfffffa8005ad9770 + +List of PortContext: 4 + [1] !port_info 0xfffffa8005a5ca80 !device_info 0xfffffa8005b410c0 + Last Port Status(2.0): Connected Enabled Powered HighSpeedDeviceAttached + Last Port Change: + Current Port(2.0) State: ConnectedEnabled.WaitingForPortChangeEvent + Current Device State: ConfiguredInD0 + ... + +Current Hub State: ConfiguredWithIntTransfer + +Hub State History: NewState ((),..) : + + [43] ConfiguredWithIntTransfer + ... + +Hub Event History: + [ 0] PortEnableInterruptTransfer + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.hub\_info**](-usb3kd-hub-info.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.hub_info_from_fdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-hub-info.md b/windows-driver-docs-pr/debugger/-usb3kd-hub-info.md new file mode 100644 index 0000000000..5258a44a5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-hub-info.md @@ -0,0 +1,115 @@ +--- +title: usb3kd.hub_info +description: The usb3kd.device_info command displays information about a hub in the USB 3.0 tree. +ms.assetid: B46B48C1-C14A-410D-9C34-F8AB1640682C +keywords: ["usb3kd.hub_info Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.hub_info +api_type: +- NA +--- + +# !usb3kd.hub\_info + + +The [**!usb3kd.device\_info**](-usb3kd-device-info.md) command displays information about a hub in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). + +``` +!usb3kd.hub_info DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the hub's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!usb\_tree**](-usb3kd-usb-tree.md) command. In the following example, the address of the device extension for the root hub is 0xfffffa8005ad92d0. + +``` +3: kd> !usb_tree + +## Dumping HUB Tree - !drvObj 0xfffffa800597f770 +-------------------------------------------- +Topology +-------- +1) !xhci_info 0xfffffa80051d1940 ... - PCI: VendorId 0x1033 ... + !hub_info 0xfffffa8005ad92d0 (ROOT) + !port_info 0xfffffa8005a5ca80 !device_info 0xfffffa8005b410c0 Desc: Speed: High + ... +``` + +Now you can pass the address of the device extension to the **!hub\_info** command. + +``` +3: kd> !hub_info fffffa8005ad92d0 + +## Dumping HUB Information fffffa8005ad92d0 +---------------------------------------- +dt USBHUB3!_HUB_FDO_CONTEXT 0xfffffa8005ad92d0 +!rcdrlogdump usbhub3 -a 0xfffffa8005ad8010 +Capabilities: Initialized, Configured, HasOverCurrentProtection, ... + +Total number of ports: 4, HUB depth is 0 +Number of 3.0 ports: 2 (Range 1 - 2) +Number of 2.0 ports: 2 (Range 3 - 4) + +Descriptors: + dt _USB_HUB_DESCRIPTOR 0xfffffa8005ad9728 + dt _USB_30_HUB_DESCRIPTOR 0xfffffa8005ad9728 + dt _USB_DEVICE_DESCRIPTOR 0xfffffa8005ad92d0 + dt _USB_CONFIGURATION_DESCRIPTOR 0xfffffa8005ad9770 + +List of PortContext: 4 + [1] !port_info 0xfffffa8005a5ca80 !device_info 0xfffffa8005b410c0 + Last Port Status(2.0): Connected Enabled Powered HighSpeedDeviceAttached + Last Port Change: + Current Port(2.0) State: ConnectedEnabled.WaitingForPortChangeEvent + Current Device State: ConfiguredInD0 + ... + +Current Hub State: ConfiguredWithIntTransfer + +Hub State History: NewState ((),..) : + + [43] ConfiguredWithIntTransfer + ... +Hub Event History: + [ 0] PortEnableInterruptTransfer + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.hub\_info\_from\_fdo**](-usb3kd-hub-info-from-fdo.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.hub_info%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-port-info.md b/windows-driver-docs-pr/debugger/-usb3kd-port-info.md new file mode 100644 index 0000000000..4fc6a3f114 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-port-info.md @@ -0,0 +1,102 @@ +--- +title: usb3kd.port_info +description: The usb3kd.port_info command displays information about a USB port in the USB 3.0 tree. +ms.assetid: 78233FE5-981E-42C4-A100-198CAAA840A0 +keywords: ["usb3kd.port_info Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.port_info +api_type: +- NA +--- + +# !usb3kd.port\_info + + +The [**!usb3kd.port\_info**](-usb3kd-device-info.md) command displays information about a USB port in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). + +``` +!usb3kd.port_info PortContext +``` + +## Parameters + + + *PortContext* +Address of a \_PORT\_CONTEXT structure. + +## DLL + + +Usb3kd.dll + +Examples +-------- + +To obtain the address of the port context, look at the output of the [**!usb\_tree**](-usb3kd-usb-tree.md) command. In the following example, the address of a port context is 0xfffffa8005abe0c0. + +``` +3: kd> !usb_tree + +## Dumping HUB Tree - !drvObj 0xfffffa800597f770 +-------------------------------------------- + +Topology +-------- +1) !xhci_info 0xfffffa80051d1940 ... - PCI: VendorId ... + !hub_info 0xfffffa8005ad92d0 (ROOT) + ... + !port_info 0xfffffa8005abe0c0 !device_info 0xfffffa8005abd0c0 Desc: ... USB Flash Drive Speed: Super +``` + +Now you can pass the address of the port context to the **!port\_info** command. + +``` +3: kd> !port_info 0xfffffa8005abe0c0 + +## Dumping Port Context 0xfffffa8005abe0c0 +--------------------------------------- +dt USBHUB3!_PORT_CONTEXT 0xfffffa8005abe0c0 +!hub_info 0xfffffa8005ad92d0 (dt _HUB_FDO_CONTEXT 0xfffffa8005ad92d0) +!device_info 0xfffffa8005abd0c0 (dt _DEVICE_CONTEXT 0xfffffa8005abd0c0) +!rcdrlogdump usbhub3 -a 0xfffffa8005abf6b0 + +PortNumber: 2 +Last Port Status(3.0): Connected Enabled Powered +Last Port Change: + +CurrentPortEvent: PsmEventPortConnectChange +Current Port(3.0) State: ConnectedEnabled.WaitingForPortChangeEvent + +Port(3.0) State History: NewState ((),..) : + + [34] WaitingForPortChangeEvent + ... +Port Event History: + [ 8] TransferSuccess + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.port_info%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller-list.md b/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller-list.md new file mode 100644 index 0000000000..763a3048e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller-list.md @@ -0,0 +1,75 @@ +--- +title: usb3kd.ucx_controller_list +description: The usb3kd.ucx_controller_list command displays information about all USB 3.0 host controllers on the computer. The display is based on data structures maintained by UcxVersion.sys. +ms.assetid: 57565A2A-A409-46CE-B7F9-F1CD521960E5 +keywords: ["usb3kd.ucx_controller_list Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.ucx_controller_list +api_type: +- NA +--- + +# !usb3kd.ucx\_controller\_list + + +The [**!usb3kd.ucx\_controller\_list**](-usb3kd-device-info.md) command displays information about all USB 3.0 host controllers on the computer. The display is based on data structures maintained by the USB host controller extension driver (Ucx*Version*.sys). + +``` +!usb3kd.ucx_controller_list +``` + +## Examples + + +The following screen shot show the output of the [**!ucx\_controller\_list**](-usb3kd-device-info.md) command. + +![output of the !ucx\-controller\-list command showing ucx controllers devices and endpoints](images/ucxcontrollerlist01.png) + +The output shows that there is one USB 3.0 host controller, which is represented by the line that begins with [**!ucx\_controller**](-usb3kd-ucx-controller.md). You can see that two devices are connected to the controller and that each device has four endpoints. + +The output uses [Using Debugger Markup Language (DML)](debugger-markup-language-commands.md) to provide links. The links execute commands that give detailed information about individual devices or endpoints. For example, you could get detailed information about an endpoint by clicking one of the [**!ucx\_endpoint**](-usb3kd-ucx-endpoint.md) links. As an alternative to clicking a link, you can enter a command. For example, to see information about the first endpoint of the second device, you could enter the command **!ucx\_endpoint 0xfffffa8003694860**. + +**Note**  The DML feature is available in WinDbg, but not in Visual Studio or KD. + +  + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The [**!ucx\_controller\_list**](-usb3kd-device-info.md) command is the parent command for this set of commands. + +- [**!ucx\_controller**](-usb3kd-ucx-controller.md) +- [**!ucx\_device**](-usb3kd-ucx-device.md) +- [**!ucx\_endpoint**](-usb3kd-ucx-endpoint.md) + +The USB host controller extension driver (Ucx*Version*.sys) provides a layer of abstraction between the USB 3.0 hub driver and the USB 3.0 host controller driver. The extension driver has its own representation of host controllers, devices, and endpoints. The outputs of the commands in the [**!ucx\_controller\_list**](-usb3kd-device-info.md) family are based on the data structures maintained by the extension driver. For more information about the USB host controller extension driver and the USB 3.0 host controller driver, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). For an explanation of the data structures used by the drivers in the USB 3.0 stack, see Part 2 of the [USB Debugging Innovations in Windows 8](http://go.microsoft.com/fwlink/p/?LinkID=249153) video. + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.ucx_controller_list%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller.md b/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller.md new file mode 100644 index 0000000000..f18cdd66c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-ucx-controller.md @@ -0,0 +1,126 @@ +--- +title: usb3kd.ucx_controller +description: The usb3kd.ucx_controller command displays information about a USB 3.0 host controller. The display is based on data structures maintained by UcxVersion.sys. +ms.assetid: A2768E47-C8D7-4A01-80AC-98FB5AAA17BD +keywords: ["usb3kd.ucx_controller Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.ucx_controller +api_type: +- NA +--- + +# !usb3kd.ucx\_controller + + +The [**!usb3kd.ucx\_controller**](-usb3kd-device-info.md) command displays information about a USB 3.0 host controller. The display is based on data structures maintained by the USB host controller extension driver (Ucx*Version*.sys). + +``` +!usb3kd.ucx_controller UcxControllerPrivContext +``` + +## Parameters + + + *UcxControllerPrivContext* +Address of the \_UCXCONTROLLER\_PRIVCONTEXT structure that represents the controller. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The USB host controller extension driver (Ucx*Version*.sys) provides a layer of abstraction between the USB 3.0 hub driver and the USB 3.0 host controller driver. The extension driver has its own representation of host controllers, devices, and endpoints. The output the [**!ucx\_controller**](-usb3kd-device-info.md) command is based on the data structures maintained by the extension driver. For more information about the USB host controller extension driver and the USB 3.0 host controller driver, see [USB Driver Stack Architecture](https://msdn.microsoft.com/library/windows/hardware/hh406256). + +Examples +-------- + +To obtain the address of the UCX controller private context, look at the output of the [**!ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) command. In the following example, the address of the private context is 0xfffffa80052da050. + +``` +3: kd> !ucx_controller_list + +## Dumping List of UCX controller objects +-------------------------------------- +[1] !ucx_controller 0xfffffa80052da050 (dt ucx01000!_UCXCONTROLLER_PRIVCONTEXT fffffa80052da050) + !ucx_device 0xfffffa8005a41840 + .!ucx_endpoint 0xfffffa800533f3d0 [Blk In ], UcxEndpointStateEnabled + ... + !ucx_device 0xfffffa8005bd9680 + .!ucx_endpoint 0xfffffa8003694860 [Blk Out], UcxEndpointStateEnabled + ... +``` + +Now you can pass the address of the UCX controller private context to the [**!ucx\_controller**](-usb3kd-device-info.md) command. + +``` +3: kd> !ucx_controller 0xfffffa80052da050 + +## Dumping Ucx Controller Information fffffa80052da050 +--------------------------------------------------- +dt ucx01000!_UCXCONTROLLER_PRIVCONTEXT 0xfffffa80052da050 +Parent Device: !wdfdevice 0x57ffac91fd8 +Controller Queues: + Default : !wdfqueue 0x57ffacc5fd8 + Address'0'Ownership : !wdfqueue 0x57ffad5ad88 + DeviceManagement : !wdfqueue 0x57ffacd6fd8 + ... pend on Ctrl Reset: !wdfqueue 0x57ffad48fd8 + +Controller Reset State History: NewState + [ 2] ControllerResetStateRHPdoInD0 + [ 1] ControllerResetStateStopBlockingResetComplete1 + [ 0] ControllerResetStateRhPdoInDx + +Controller Reset Event History: + [ 1] ControllerResetEventRHPdoEnteredD0 + [ 0] SmEngineEventStart + +Root Hub PDO: !wdfdevice 0x57ffaf4daa8 +Number of 2.0 Ports: 2 +Number of 3.0 Ports: 2 +RootHub Control !wdfqueue 0x57ffacb4798 +RootHub Interrupt !wdfqueue 0x57ffad033f8, pending !wdfequest 0x57ffa5fe998 + +Device Tree: + !ucx_device 0xfffffa8005a41840 + .!ucx_endpoint 0xfffffa800533f3d0 [Blk In ], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa80053405d0 [Blk Out], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005a3f710 [Control], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005bbe4e0 [Blk Out], UcxEndpointStateStale + .!ucx_endpoint 0xfffffa8005ac4810 [Blk In ], UcxEndpointStateStale + !ucx_device 0xfffffa8005bd9680 + .!ucx_endpoint 0xfffffa8003694860 [Blk Out], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003686820 [Blk In ], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005be0550 [Control], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003695580 [Blk In ], UcxEndpointStateStale + .!ucx_endpoint 0xfffffa80036a20c0 [Blk Out], UcxEndpointStateStale +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.ucx_controller%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-ucx-device.md b/windows-driver-docs-pr/debugger/-usb3kd-ucx-device.md new file mode 100644 index 0000000000..1bb6fb056a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-ucx-device.md @@ -0,0 +1,112 @@ +--- +title: usb3kd.ucx_device +description: The usb3kd.ucx_device extension displays information about a USB device in the USB 3.0 tree. The display is based on data structures maintained by UcxVersion.sys. +ms.assetid: 7AC3DBBF-1D62-492E-B46E-C193579DE1E3 +keywords: ["usb3kd.ucx_device Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.ucx_device +api_type: +- NA +--- + +# !usb3kd.ucx\_device + + +The [**!usb3kd.ucx\_device**](-usb3kd-device-info.md) extension displays information about a USB device in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). The display is based on data structures maintained by the USB host controller extension driver (Ucx*Version*.sys). + +``` +!usb3kd.ucx_device UcxUsbDevicePrivContext +``` + +## Parameters + + + *UcxUsbDevicePrivContext* +Address of the \_UCXUSBDEVICE\_PRIVCONTEXT structure that represents the device. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The USB host controller extension driver (Ucx*Version*.sys) provides a layer of abstraction between the USB 3.0 hub driver and the USB 3.0 host controller driver. The extension driver has its own representation of host controllers, devices, and endpoints. The output the [**!ucx\_device**](-usb3kd-device-info.md) command is based on the data structures maintained by the extension driver. For more information about the USB host controller extension driver and the USB 3.0 host controller driver, see [USB Driver Stack Architecture](https://msdn.microsoft.com/library/windows/hardware/hh406256). + +**!ucx\_device** and [**!device\_info**](-usb3kd-device-info.md) both display information about a device, but the information displayed is different. The output of **!ucx\_device** is from the point of view of the USB host controller extension driver, and the output of **!device\_info** is from the point of view of the USB 3.0 hub driver. For example, the **!ucx\_device** output includes information about endpoints, and the **!device\_info** output includes information about configuration and interface descriptors. + +Examples +-------- + +To obtain the address of the UCX USB device private context, look at the output of the [**!ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) command. In the following example, the address of the private context for the second device is 0xfffffa8005bd9680. + +``` +3: 3: kd> !ucx_controller_list + +## Dumping List of UCX controller objects +-------------------------------------- +[1] !ucx_controller 0xfffffa80052da050 (dt ucx01000!_UCXCONTROLLER_PRIVCONTEXT fffffa80052da050) + !ucx_device 0xfffffa8005a41840 + .!ucx_endpoint 0xfffffa800533f3d0 [Blk In ], UcxEndpointStateEnabled + ... + !ucx_device 0xfffffa8005bd9680 + .!ucx_endpoint 0xfffffa8003694860 [Blk Out], UcxEndpointStateEnabled + ... +``` + +Now you can pass the address of the UCX USB private context to the **!ucx\_device** command. + +``` +3: kd> !ucx_device 0xfffffa8005bd9680 + +## Dumping Ucx USB Device Information fffffa8005bd9680 +--------------------------------------------------- +dt ucx01000!_UCXUSBDEVICE_PRIVCONTEXT 0xfffffa8005bd9680 +!ucx_controller 0xfffffa80052da050 +ParentHub: !wdfhandle 0x57ffacbce78 +DefaultEndpoint: !ucx_endpoint 0xfffffa8005be0550 +ListOfEndpionts: + .!ucx_endpoint 0xfffffa8003694860 [Blk Out], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003686820 [Blk In ], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005be0550 [Control], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003695580 [Blk In ], UcxEndpointStateStale + .!ucx_endpoint 0xfffffa80036a20c0 [Blk Out], UcxEndpointStateStale + +EventCallbacks: + EvtUsbDeviceEndpointsConfigure: (0xfffff880044d1164) USBXHCI!UsbDevice_UcxEvtEndpointsConfigure + EvtUsbDeviceEnable: (0xfffff880044cffac) USBXHCI!UsbDevice_UcxEvtEnable + EvtUsbDeviceDisable: (0xfffff880044d1cbc) USBXHCI!UsbDevice_UcxEvtDisable + EvtUsbDeviceReset: (0xfffff880044d2178) USBXHCI!UsbDevice_UcxEvtReset + EvtUsbDeviceAddress: (0xfffff880044d0934) USBXHCI!UsbDevice_UcxEvtAddress + EvtUsbDeviceUpdate: (0xfffff880044d0c80) USBXHCI!UsbDevice_UcxEvtUpdate + EvtUsbDeviceDefaultEndpointAdd: (0xfffff880044ede1c) USBXHCI!Endpoint_UcxEvtUsbDeviceDefaultEndpointAdd + EvtUsbDeviceEndpointAdd: (0xfffff880044edfc8) USBXHCI!Endpoint_UcxEvtUsbDeviceEndpointAdd +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.ucx_device%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-ucx-endpoint.md b/windows-driver-docs-pr/debugger/-usb3kd-ucx-endpoint.md new file mode 100644 index 0000000000..1770b8323e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-ucx-endpoint.md @@ -0,0 +1,115 @@ +--- +title: usb3kd.ucx_endpoint +description: The usb3kd.ucx_endpoint command displays information about an endpoint on a USB device in the USB 3.0 tree. The display is based on data maintained by UcxVersion.sys. +ms.assetid: 37667665-ACA1-48D3-B79E-5B9BBD689034 +keywords: ["usb3kd.ucx_endpoint Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.ucx_endpoint +api_type: +- NA +--- + +# !usb3kd.ucx\_endpoint + + +The [**!usb3kd.ucx\_endpoint**](-usb3kd-device-info.md) command displays information about an endpoint on a USB device in the [USB 3.0 tree](usb-3-extensions.md#usb-3-tree). The display is based on data structures maintained by the USB host controller extension driver (Ucx*Version*.sys). + +``` +!usb3kd.ucx_endpoint UcxEndpointPrivContext +``` + +## Parameters + + + *UcxEndpointPrivContext* +Address of the \_UCXENDPOINT\_PRIVCONTEXT structure that represents the endpoint. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The USB host controller extension driver (Ucx*Version*.sys) provides a layer of abstraction between the USB 3.0 hub driver and the USB 3.0 host controller driver. The extension driver has its own representation of host controllers, devices, and endpoints. The output the **!ucx\_endpoint** command is based on the data structures maintained by the extension driver. For more information about the USB host controller extension driver and the USB 3.0 host controller driver, see [USB Driver Stack Architecture](https://msdn.microsoft.com/library/windows/hardware/hh406256). + +Examples +-------- + +To obtain the address of the UCX endpoint private context, look at the output of the [**!ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) command. In the following example, the address of the private context for the first endpoint on the second device is 0xfffffa8003694860. + +``` +3: kd> !ucx_controller_list + +## Dumping List of UCX controller objects +-------------------------------------- +[1] !ucx_controller 0xfffffa80052da050 (dt ucx01000!_UCXCONTROLLER_PRIVCONTEXT fffffa80052da050) + !ucx_device 0xfffffa8005a41840 + .!ucx_endpoint 0xfffffa800533f3d0 [Blk In ], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa80053405d0 [Blk Out], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005a3f710 [Control], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005bbe4e0 [Blk Out], UcxEndpointStateStale + .!ucx_endpoint 0xfffffa8005ac4810 [Blk In ], UcxEndpointStateStale + !ucx_device 0xfffffa8005bd9680 + .!ucx_endpoint 0xfffffa8003694860 [Blk Out], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003686820 [Blk In ], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8005be0550 [Control], UcxEndpointStateEnabled + .!ucx_endpoint 0xfffffa8003695580 [Blk In ], UcxEndpointStateStale + .!ucx_endpoint 0xfffffa80036a20c0 [Blk Out], UcxEndpointStateStale +``` + +Now you can pass the address of the UCX endpoint private context to the **!ucx\_endpoint** command. + +``` +3: kd> !ucx_endpoint 0xfffffa8003694860 + +## Dumping Ucx USB Endpoint Information fffffa8003694860 +----------------------------------------------------- +dt ucx01000!_UCXENDPOINT_PRIVCONTEXT 0xfffffa8003694860 +[Blk Out], UcxEndpointStateEnabled, MaxTransferSize: 4194304 +Endpoint Address: 0x02 +Endpoint Queue: !wdfqueue 0x57ffc969888 + +UcxEndpoint State History: NewState + [ 3] UcxEndpointStateEnabled + [ 2] UcxEndpointStateCompletingPendingOperation1 + [ 1] UcxEndpointStateIsAbleToStart2 + [ 0] UcxEndpointStateCreated + +UcxEndpoint Event History: + [ 1] UcxEndpointEventEnableComplete + [ 0] SmEngineEventStart + +EventCallbacks: + EvtEndpointPurge: (0xfffff880044ba6e8) USBXHCI!Endpoint_UcxEvtEndpointPurge + EvtEndpointAbort: (0xfffff880044ba94c) USBXHCI!Endpoint_UcxEvtEndpointAbort + EvtEndpointReset: (0xfffff880044bb854) USBXHCI!Endpoint_UcxEvtEndpointReset +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!usb3kd.ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.ucx_endpoint%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-urb.md b/windows-driver-docs-pr/debugger/-usb3kd-urb.md new file mode 100644 index 0000000000..b540caaa82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-urb.md @@ -0,0 +1,99 @@ +--- +title: usb3kd.urb +description: The usb3kd.urb extension displays information about a USB request block (URB). +ms.assetid: B4583F32-BBC9-4182-A403-9C43BBD9BA4F +keywords: ["usb3kd.urb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.urb +api_type: +- NA +--- + +# !usb3kd.urb + + +The [**!usb3kd.urb**](-usb3kd-device-info.md) extension displays information about a USB request block (URB). + +``` +!usb3kd.urb UrbAddress +``` + +## Parameters + + + *UrbAddress* +Address of the URB. + +## DLL + + +Usb3kd.dll + +Examples +-------- + +The following example shows the address of a URB (0xfffffa8005a2cbe8) in the output of the [**!xhci\_deviceslots**](-usb3kd-xhci-deviceslots.md) command. + +``` +3: kd> !xhci_deviceslots 0xfffffa800520d2d0 + +## Dumping dt _DEVICESLOT_DATA 0xfffffa8003612e80 +---------------------------------------------- +DeviceContextBase: VA 0xfffffa8005a64000 LA 0x116864000 !wdfcommonbuffer 0x57ffa7ca758 Size 4096 + +## [1] SlotID : dt USBXHCI!_USBDEVICE_DATA 0xfffffa80059027d0 dt _SLOT_CONTEXT32 0xfffffa8005a65000 +------------------------------------------------------------------------------------------------ + USB\VID_... + SlotEnabled IsDevice NumberOfTTs 0 TTThinkTime 0 + ... + PendingTransferList: + [0] dt _TRANSFER_DATA 0xfffffa80059727f0 !urb 0xfffffa8005a2cbe8 !wdfrequest 0x57ffa68d998 TransferState_Pending + ... +``` + +The following example passes the address of the URB to the **!usb3kd.urb** command. + +``` +3: kd> !urb 0xfffffa8005a2cbe8 + +## Dumping URB 0xfffffa8005a2cbe8 +------------------------------ +Function: URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER (0x9) +UsbdDeviceHandle: + !ucx_device 0xfffffa8005901840 + !xhci_deviceslots 0xfffffa800520d2d0 1 + +Status: USBD_STATUS_PENDING (0x40000000) +UsbdFlags: (0x0) +dt _URB_BULK_OR_INTERRUPT_TRANSFER 0xfffffa8005a2cbe8 +PipeHandle: 0xfffffa800596f720 +TransferFlags: (0x1) USBD_TRANSFER_DIRECTION_IN +TransferBufferLength: 0x0 +TransferBuffer: 0xfffffa8005a2cc88 +TransferBufferMDL: 0xfffffa8005848930 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.urb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-usb-tree.md b/windows-driver-docs-pr/debugger/-usb3kd-usb-tree.md new file mode 100644 index 0000000000..0e8a6895ea --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-usb-tree.md @@ -0,0 +1,83 @@ +--- +title: usb3kd.usb_tree +description: The usb3kd.usb_tree extension displays information, in tree format, about all USB 3.0 controllers, hubs, and devices on the computer. +ms.assetid: 8E24AD44-7B32-4299-8428-D8E9B36F5848 +keywords: ["usb3kd.usb_tree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.usb_tree +api_type: +- NA +--- + +# !usb3kd.usb\_tree + + +The [**!usb3kd.usb\_tree**](-usb3kd-device-info.md) extension displays information, in tree format, about all USB 3.0 controllers, hubs, and devices on the computer. + +``` +!usb3kd.usb_tree [1] +``` + +## Parameters + + + **1** +The display includes status information for hubs and ports. + +## Examples + + +The following screen shot shows the output of the [**!usb\_tree**](-usb3kd-device-info.md) command. + +![output of the !usb\-tree command showing topology enumerated device and hub list](images/usbtree01.png) + +The output shows that there is one USB 3.0 host controller, which is represented by the line that begins with [**!xhci\_info**](-usb3kd-xhci-info.md). The next line represents the root hub for the host controller. The next four lines represent ports associated with the root hub. You can see that two ports have devices connected. + +The output uses [Using Debugger Markup Language (DML)](debugger-markup-language-commands.md) to provide links. The links execute commands that give detailed information about individual objects in the tree. For example, you could get information about one of the connected devices by clicking one of the [**!device\_info**](-usb3kd-device-info.md) links. As an alternative to clicking a link, you can enter a command. For example, to see information about the first connected device, you could enter the command **!device\_info 0xfffffa8004630690**. + +**Note**  The DML feature is available in WinDbg, but not in Visual Studio or KD. + +  + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The [**!usb\_tree**](-usb3kd-device-info.md) command is the parent command for this set of commands. + +- [**!hub\_info**](-usb3kd-hub-info.md) +- [**!hub\_info\_from\_fdo**](-usb3kd-hub-info-from-fdo.md) +- [**!device\_info**](-usb3kd-device-info.md) +- [**!device\_info\_from\_pdo**](-usb3kd-device-info-from-pdo.md) +- [**!port\_info**](-usb3kd-port-info.md) + +The information displayed by the [**!usb\_tree**](-usb3kd-device-info.md) family of commands is based on data structures maintained by the USB 3.0 hub driver. For information about the USB 3.0 hub driver and other drivers in the USB 3.0 stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). For an explanation of the data structures used by the drivers in the USB 3.0 stack, see Part 2 of the [USB Debugging Innovations in Windows 8](http://go.microsoft.com/fwlink/p/?LinkID=249153) video. + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.usb_tree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-usbanalyze.md b/windows-driver-docs-pr/debugger/-usb3kd-usbanalyze.md new file mode 100644 index 0000000000..6eb2f3ddf9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-usbanalyze.md @@ -0,0 +1,57 @@ +--- +title: usb3kd.usbanalyze +description: The usb3kd.usbanalyze extension analyzes a USB 3.0 bug check. +ms.assetid: 4BC5687B-D8C8-4E5E-B9AD-ECDC63858345 +keywords: ["usb3kd.usbanalyze Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.usbanalyze +api_type: +- NA +--- + +# !usb3kd.usbanalyze + + +The [**!usb3kd.usbanalyze**](-usb3kd-device-info.md) extension analyzes a USB 3.0 bug check. + +``` +!usb3kd.usbanalyze [-v] +``` + +## Parameters + + + **-v** +The display is verbose. + +## DLL + + +Usb3kd.dll + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +[**BUGCODE\_USB3\_DRIVER**](bug-check-0x144--bugcode-usb3-driver.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.usbanalyze%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-usbdstatus.md b/windows-driver-docs-pr/debugger/-usb3kd-usbdstatus.md new file mode 100644 index 0000000000..e125148ff9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-usbdstatus.md @@ -0,0 +1,70 @@ +--- +title: usb3kd.usbdstatus +description: The usb3kd.usbdstatus extension displays the name of a USBD status code. +ms.assetid: B79B4E6E-7281-4BB0-9708-23F1462171BB +keywords: ["usb3kd.usbdstatus Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.usbdstatus +api_type: +- NA +--- + +# !usb3kd.usbdstatus + + +The [**!usb3kd.usbdstatus**](-usb3kd-device-info.md) extension displays the name of a USBD status code. + +``` +!usb3kd.ucx_usbdstatus UrbStatus +``` + +## Parameters + + + *UsbdStatus* +The numeric value of a USBD status code. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +USBD status codes are defined in Usb.h. + +Examples +-------- + +The following example passes the numeric value 0x80000200 to the **!usbdstatus** command. The command returns the name of the status code, USBD\_STATUS\_INVALID\_URB\_FUNCTION. + +``` +3: kd> !usbdstatus 0x80000200 +USBD_STATUS_INVALID_URB_FUNCTION (0x80000200) +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.usbdstatus%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-capability.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-capability.md new file mode 100644 index 0000000000..fe705673db --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-capability.md @@ -0,0 +1,130 @@ +--- +title: usb3kd.xhci_capability +description: The usb3kd.xhci_capability extension displays the capabilities of a USB 3.0 host controller. +ms.assetid: 72D3919A-C111-4B16-8A52-B439429DFFCC +keywords: ["usb3kd.xhci_capability Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_capability +api_type: +- NA +--- + +# !usb3kd.xhci\_capability + + +The [**!usb3kd.xhci\_capability**](-usb3kd-device-info.md) extension displays the capabilities of a USB 3.0 host controller. + +``` +!usb3kd.xhci_capability DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the [**!xhci\_capability**](-usb3kd-device-info.md) command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](https://msdn.microsoft.com/library/windows/hardware/hh406256). + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + ... +``` + +Now you can pass the address of the device extension to the **!xhci\_capability** command. + +``` +3: kd> !xhci_capability 0xfffffa800536e2d0 + +## Controller Capabilities +----------------------- + dt USBXHCI!_REGISTER_DATA 0xfffffa8005362c00 + dt USBXHCI!_CAPABILITY_REGISTERS 0xfffff880046a8000 + MajorRevision.MinorRevision = 0.96 + Device Slots: 32 + Interrupters: 8 + Ports: 4 + IsochSchedulingThreshold: 1 + EventRingSegmentTableMax: 1 (2^ERST = 2) + ScratchpadRestore: OFF + MaxScratchpadBuffers: 0 + U1DeviceExitLatency: 0 + U2DeviceExitLatency: 0 + AddressingCapability: 64 bit + BwNegotiationCapability: ON + ContextSize: 32 bytes + PortPowerControl: ON + PortIndicators: OFF + LightHCResetCapability: OFF + LatencyToleranceMessagingCapability: ON + NoSecondarySidSupport: TRUE + MaximumPrimaryStreamArraySize = 4 ( 2^(MaxPSASize+1) = 32 ) + XhciExtendedCapabilities: + [1] USB_LEGACY_SUPPORT: dt _USBLEGSUP 0xfffff880046a8500 + [2] Supported Protocol 0xfffff880046a8510, Version 3.0, Offset 1, Count 2, HighSpeedOnly OFF, IntegratedHub OFF, HardwareLPM OFF + [3] Supported Protocol 0xfffff880046a8520, Version 2.0, Offset 3, Count 2, HighSpeedOnly OFF, IntegratedHub OFF, HardwareLPM OFF + +## Software Supported Capabilities +------------------------------- + DeviceSlots: 32 + Interrupters: 1 + Ports: 4 + MaxEventRingSegments: 2 + U1DeviceExitLatency: 0 + U2DeviceExitLatency: 0 + DeviceFlags: + IgnoreBiosHandoffFailure + SetLinkTrbChainBit + UseSingleInterrupter + DisableIdlePowerManagement +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_capability%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-commandring.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-commandring.md new file mode 100644 index 0000000000..bfdac5b2c1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-commandring.md @@ -0,0 +1,111 @@ +--- +title: usb3kd.xhci_commandring +description: The usb3kd.xhci_commandring extension displays information about the command ring data structure associated with a USB 3.0 host controller. +ms.assetid: 3099F3F1-B881-4BBD-90F5-59DC2DFECF3B +keywords: ["usb3kd.xhci_commandring Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_commandring +api_type: +- NA +--- + +# !usb3kd.xhci\_commandring + + +The [**!usb3kd.xhci\_commandring**](-usb3kd-device-info.md) extension displays information about the command ring data structure associated with a USB 3.0 host controller. + +``` +!usb3kd.xhci_commandring DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +AAddress of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the **!xhci\_commandring** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +The command ring is a data structure used by the USB 3.0 host controller driver to pass commands to the host controller. + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + !xhci_commandring 0xfffffa800536e2d0 (No commands are pending) + ... +``` + +Now you can pass the address of the device extension to the **!xhci\_commandring** command. + +``` +3: kd> !xhci_commandring 0xfffffa800536e2d0 + +## Dumping dt _COMMAND_DATA 0xfffffa8005362f70 !rcdrlogdump USBXHCI -a 0xfffffa8005a8f010 +------------------------------------------------------------------------------------- +Stop: OFF Abort: OFF Running: ON +CommandRingBufferData: VA 0xfffffa8005aeb200 LA 0x1168eb200 !wdfcommonbuffer 0x57ffa65d988 Size 512 +DequeueIndex: 24 EnqueueIndex: 24 CycleState: 0 + + Command Ring TRBs: + [ 0] Unknown TRB Type 49 0xfffffa8005aeb200 + + [ 1] ENABLE_SLOT 0xfffffa8005aeb210 CycleBit 1 + [ 2] ADDRESS_DEVICE 0xfffffa8005aeb220 CycleBit 1 SlotId 1 BlockSetAddressRequest 1 + ... + + PendingList: + Empty List + + WaitingList: + Empty List +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_commandring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-deviceslots.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-deviceslots.md new file mode 100644 index 0000000000..8ba41fe6fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-deviceslots.md @@ -0,0 +1,140 @@ +--- +title: usb3kd.xhci_deviceslots +description: The usb3kd.xhci_deviceslots extension displays information about the devices connected to a USB 3.0 host controller. +ms.assetid: 471167EA-F7F8-470D-B09C-8627C5BE9566 +keywords: ["usb3kd.xhci_deviceslots Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_deviceslots +api_type: +- NA +--- + +# !usb3kd.xhci\_deviceslots + + +The [**!usb3kd.xhci\_deviceslots**](-usb3kd-device-info.md) extension displays information about the devices connected to a USB 3.0 host controller. + +``` +!usb3kd.xhci_deviceslots DeviceExtension [SlotNumber] [verbose] +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + + *SlotNumber* +Slot number of the device to be displayed. If this parameter is omitted, all devices are displayed. + + **verbose** +The display is verbose. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the **!xhci\_deviceslots** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +The USB 3.0 host controller driver maintains a list of data structures that represent the devices connected to the controller. Each of these data structures is identified by a slot number. + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + !xhci_commandring 0xfffffa800536e2d0 (No commands are pending) + !xhci_deviceslots 0xfffffa800536e2d0 + ... +``` + +Now you can pass the address of the device extension to the **!usb3kd.xhci\_deviceslots** command. + +``` +3: kd> !xhci_deviceslots 0xfffffa800536e2d0 + +## Dumping dt _DEVICESLOT_DATA 0xfffffa8005226220 +---------------------------------------------- +DeviceContextBase: VA 0xfffffa8005ab9000 LA 0x1168b9000 !wdfcommonbuffer 0x57ffa65c9b8 Size 4096 + +## [1] SlotID : dt USBXHCI!_USBDEVICE_DATA 0xfffffa8005a427d0 dt _SLOT_CONTEXT32 0xfffffa8005aba000 +------------------------------------------------------------------------------------------------ + USB\VID_125F&PID_312A ADATA Technology Co., Ltd. + SlotEnabled IsDevice NumberOfTTs 0 TTThinkTime 0 + Speed: Super PortPathDepth: 1 PortPath: [ 2 ] DeviceAddress: 1 + !device_info_from_pdo 0xfffffa8005a36800 + DeviceContextBuffer: VA 0xfffffa8005aba000 LA 0x1168ba000 !wdfcommonbuffer 0x57ffa656948 Size 4096 + InputDeviceContextBuffer: VA 0xfffffa8005b65000 LA 0x116965000 !wdfcommonbuffer 0x57ffa5be958 Size 4096 + + [1] DeviceContextIndex : dt USBXHCI!_ENDPOINT_DATA 0xfffffa8005a126f0 dt _ENDPOINT_CONTEXT32 0xfffffa8005aba020 ES_RUNNING + -------------------------------------------------------------------------------------------------------------- + EndpointType_Control Address: 0x0 PacketSize: 512 Interval: 0 + !ucx_endpoint 0xfffffa8005a3f710 + RecorderLog: !rcdrlogdump USBXHCI -a 0xfffffa8005b60010 + + [0] dt _TRANSFERRING_DATA 0xfffffa8005b64ec0 Events: 0x0 TransferRingState_Idle + ... + +## [2] SlotID : dt USBXHCI!_USBDEVICE_DATA 0xfffffa80052de320 dt _SLOT_CONTEXT32 0xfffffa8005b8b000 +------------------------------------------------------------------------------------------------ + USB\VID_18A5&PID_0304 Verbatim Americas LLC + SlotEnabled IsDevice NumberOfTTs 0 TTThinkTime 0 + Speed: High PortPathDepth: 1 PortPath: [ 3 ] DeviceAddress: 2 + !device_info_from_pdo 0xfffffa80058fb800 + DeviceContextBuffer: VA 0xfffffa8005b8b000 LA 0x11698b000 !wdfcommonbuffer 0x57ffa426b18 Size 4096 + InputDeviceContextBuffer: VA 0xfffffa8005b8c000 LA 0x11698c000 !wdfcommonbuffer 0x57ffadbe3c8 Size 4096 + + [1] DeviceContextIndex : dt USBXHCI!_ENDPOINT_DATA 0xfffffa800714b050 dt _ENDPOINT_CONTEXT32 0xfffffa8005b8b020 ES_RUNNING + -------------------------------------------------------------------------------------------------------------- + EndpointType_Control Address: 0x0 PacketSize: 64 Interval: 0 + !ucx_endpoint 0xfffffa80036a20c0 + RecorderLog: !rcdrlogdump USBXHCI -a 0xfffffa8005bd0b60 + + [0] dt _TRANSFERRING_DATA 0xfffffa8004ed8df0 Events: 0x0 TransferRingState_Idle + ------------------------------------------------------------------------------ + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_deviceslots%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-dumpall.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-dumpall.md new file mode 100644 index 0000000000..7946a43218 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-dumpall.md @@ -0,0 +1,87 @@ +--- +title: usb3kd.xhci_dumpall +description: The usb3kd.xhci_dumpall command displays information about all USB 3.0 host controllers on the computer. The display is based on the data structures maintained by UsbXhci.sys. +ms.assetid: D1087DC6-B065-48E3-93B2-EF53AE9DA8C7 +keywords: ["usb3kd.xhci_dumpall Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_dumpall +api_type: +- NA +--- + +# !usb3kd.xhci\_dumpall + + +The [**!usb3kd.xhci\_dumpall**](-usb3kd-device-info.md) command displays information about all USB 3.0 host controllers on the computer. The display is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). + +``` +!usb3kd.xhci_dumpall [1] +``` + +## Parameters + + + **1** +Runs all of the XHCI commands and displays the output of each command. + +## Examples + + +The following screen shot show the output of the **!xhci\_dumpall**l command. + +![output of the !xhci\-dumpall command showing xhci controller information](images/xhcidumpall01.png) + +The output shows that there is one USB 3.0 host controller. + +The output uses [Using Debugger Markup Language (DML)](debugger-markup-language-commands.md) to provide links. The links execute commands that give detailed information about the state of the host controller as it is maintained by the USB 3.0 host controller driver. For example, you could get detailed information about the host controller capabilities by clicking the [**!xhci\_capability**](-usb3kd-xhci-capability.md) link. As an alternative to clicking a link, you can enter a command. For example, to see information about the host controller's resource usage, you could enter the command **!xhci\_resourceusage 0xfffffa800536e2d0**. + +**Note**  The DML feature is available in WinDbg, but not in Visual Studio or KD. + +  + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The **!xhci\_dumpall** command is the parent command for this set of commands. + +- [**!xhci\_capability**](-usb3kd-xhci-capability.md) +- [**!xhci\_info**](-usb3kd-xhci-info.md) +- [**!xhci\_deviceslots**](-usb3kd-xhci-deviceslots.md) +- [**!xhci\_commandring**](-usb3kd-xhci-commandring.md) +- [**!xhci\_eventring**](-usb3kd-xhci-eventring.md) +- [**!xhci\_transferring**](-usb3kd-xhci-transferring.md) +- [**!xhci\_trb**](-usb3kd-xhci-trb.md) +- [**!xhci\_registers**](-usb3kd-xhci-registers.md) +- [**!xhci\_resourceusage**](-usb3kd-xhci-resourceusage.md) + +The information displayed by the **!xhci\_dumpall** family of commands is based on data structures maintained by the USB 3.0 host controller driver. For information about the USB 3.0 host controller driver and other drivers in the USB 3.0 stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). For an explanation of the data structures used by the drivers in the USB 3.0 stack, see Part 2 of the [USB Debugging Innovations in Windows 8](http://go.microsoft.com/fwlink/p/?LinkID=249153) video. + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_dumpall%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-eventring.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-eventring.md new file mode 100644 index 0000000000..7ec28181a9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-eventring.md @@ -0,0 +1,118 @@ +--- +title: usb3kd.xhci_eventring +description: The usb3kd.xhci_eventring extension displays information about the event ring data structure associated with a USB 3.0 host controller. +ms.assetid: D3A40372-5473-48B0-94C7-5D3B80801F16 +keywords: ["usb3kd.xhci_eventring Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_eventring +api_type: +- NA +--- + +# !usb3kd.xhci\_eventring + + +The [**!usb3kd.xhci\_eventring**](-usb3kd-device-info.md) extension displays information about the event ring data structure associated with a USB 3.0 host controller. + +``` +!usb3kd.xhci_eventring DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output **!xhci\_eventring** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +The event ring is a structure used by the USB 3.0 host controller to inform drivers that an action has completed. + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + !xhci_commandring 0xfffffa800536e2d0 (No commands are pending) + !xhci_deviceslots 0xfffffa800536e2d0 + !xhci_eventring 0xfffffa800536e2d0 + ... +``` + +Now you can pass the address of the device extension to the **!xhci\_eventring** command. + +``` +3: kd> !xhci_eventring 0xfffffa800536e2d0 + +## Dumping dt _PRIMARY_INTERRUPTER_DATA fffffa800536b5b0 +----------------------------------------------------- + +## [0] Interrupter : dt _INTERRUPTER_DATA 0xfffffa800536b7d0 !rcdrlogdump USBXHCI -a 0xfffffa8005aeab60 +------------------------------------------------------------------------------------------------------ + DequeueSegment: 1 DequeueIndex: 217 TotalEventRingSegments: 2 TRBsPerSegment: 256 + CurrentBufferData : VA 0xfffffa8005373000 LA 0x117173000 !wdfcommonbuffer 0x57ffa65b9b8 Size 4096 + EventRingTableBufferData : VA 0xfffffa8005aeb000 LA 0x1168eb000 !wdfcommonbuffer 0x57ffa65d988 Size 512 + + [0] VA 0xfffffa8005370000 LA 0x117170000 !wdfcommonbuffer 0x57ffa6599b8 Size 4096 + [1] VA 0xfffffa8005373000 LA 0x117173000 !wdfcommonbuffer 0x57ffa65b9b8 Size 4096 + + Event Ring TRBs: + [207] TRANSFER_EVENT 0xfffffa8005373cf0 CycleBit 0 SlotId 2 EndpointID 4 EventData 1 Pointer 0xfffffa8005366700 CC_SUCCESS + [208] TRANSFER_EVENT 0xfffffa8005373d00 CycleBit 0 SlotId 2 EndpointID 3 EventData 1 Pointer 0xfffffa8005a3d850 CC_SHORT_PACKET + [209] TRANSFER_EVENT 0xfffffa8005373d10 CycleBit 0 SlotId 1 EndpointID 4 EventData 1 Pointer 0xfffffa8005a3d850 CC_SUCCESS + [210] TRANSFER_EVENT 0xfffffa8005373d20 CycleBit 0 SlotId 1 EndpointID 3 EventData 1 Pointer 0xfffffa8005366700 CC_SUCCESS + [211] TRANSFER_EVENT 0xfffffa8005373d30 CycleBit 0 SlotId 2 EndpointID 4 EventData 1 Pointer 0xfffffa8005366700 CC_SUCCESS + [212] TRANSFER_EVENT 0xfffffa8005373d40 CycleBit 0 SlotId 2 EndpointID 3 EventData 1 Pointer 0xfffffa8005a3d850 CC_SHORT_PACKET + [213] TRANSFER_EVENT 0xfffffa8005373d50 CycleBit 0 SlotId 1 EndpointID 4 EventData 1 Pointer 0xfffffa8005a3d850 CC_SUCCESS + [214] TRANSFER_EVENT 0xfffffa8005373d60 CycleBit 0 SlotId 1 EndpointID 3 EventData 1 Pointer 0xfffffa8005366700 CC_SUCCESS + [215] TRANSFER_EVENT 0xfffffa8005373d70 CycleBit 0 SlotId 2 EndpointID 4 EventData 1 Pointer 0xfffffa8005366700 CC_SUCCESS + [216] TRANSFER_EVENT 0xfffffa8005373d80 CycleBit 0 SlotId 2 EndpointID 3 EventData 1 Pointer 0xfffffa8005a3d850 CC_SHORT_PACKET +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_eventring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-info.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-info.md new file mode 100644 index 0000000000..6a8d7bdff1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-info.md @@ -0,0 +1,105 @@ +--- +title: usb3kd.xhci_info +description: The usb3kd.xhci_info extension displays all the XHCI commands for an individual USB 3.0 host controller. +ms.assetid: C3C3B379-4871-4293-9C35-B64F3A5E1348 +keywords: ["usb3kd.xhci_info Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_info +api_type: +- NA +--- + +# !usb3kd.xhci\_info + + +The [**!usb3kd.xhci\_info**](-usb3kd-device-info.md) extension displays all the XHCI commands for an individual USB 3.0 host controller. + +``` +!usb3kd.xhci_info DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the **!usb3kd.xhci\_info** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +Examples +-------- + +You can get address of the device extension from the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command or from a variety of other debugger commands. For example, the [**!devstack**](-devstack.md) command displays the address of the device extension. In the following example, the address of the device extension for the host controller's FDO is fffffa800536e2d0. + +``` +3: kd> !devnode 0 1 usbxhci +Dumping IopRootDeviceNode (= 0xfffffa8003609cc0) +DevNode 0xfffffa8003df3010 for PDO 0xfffffa8003dd5870 + InstancePath is "PCI\VEN_... + ServiceName is "USBXHCI" + ... + +3: kd> !devstack 0xfffffa8003dd5870 + !DevObj !DrvObj !DevExt ObjectName + fffffa800534b060 \Driver\USBXHCI fffffa800536e2d0 USBFDO-3 + fffffa8003db5790 \Driver\ACPI fffffa8003701cb0 +> fffffa8003dd5870 \Driver\pci fffffa8003dd59c0 NTPNP_PCI0020 +... +``` + +Now you can pass the address of the device extension to the **!xhci\_info** command. + +``` +3: kd> !xhci_info 0xfffffa80`0536e2d0 + +## Dumping XHCI controller commands - DeviceExtension 0xfffffa800536e2d0 +------------------------------------------------------------ + ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + !xhci_commandring 0xfffffa800536e2d0 (No commands are pending) + !xhci_deviceslots 0xfffffa800536e2d0 + !xhci_eventring 0xfffffa800536e2d0 + !xhci_resourceusage 0xfffffa800536e2d0 + !pci 100 0x30 0x0 0x0 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_info%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-registers.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-registers.md new file mode 100644 index 0000000000..2eabfd2f5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-registers.md @@ -0,0 +1,124 @@ +--- +title: usb3kd.xhci_registers +description: The usb3kd.xhci_registers extension displays the registers of a USB 3.0 host controller. +ms.assetid: C695C23D-B617-4D1E-87F8-62CF99426CA3 +keywords: ["usb3kd.xhci_registers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_registers +api_type: +- NA +--- + +# !usb3kd.xhci\_registers + + +The [**!usb3kd.xhci\_registers**](-usb3kd-device-info.md) extension displays the registers of a USB 3.0 host controller. + +``` +!usb3kd.xhci_registers DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the **!xhci\_registers** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + ... +``` + +Now you can pass the address of the device extension to the **!xhci\_registers** command. + +``` +3: kd> !xhci_registers 0xfffffa800536e2d0 + +## Dumping controller registers +---------------------------- + + dt USBXHCI!_OPERATIONAL_REGISTERS 0xfffff880046a8020 + + DeviceContextBaseAddressArrayPointer: 00000001168b9000 + + Command Registers + ----------------- + RunStopBit: 1 + HostControllerReset: 0 + ... + + Status Registers + ---------------- + HcHalted: 0 + HostSystemError: 0 + ... + + commandRingControl Registers + ---------------------------- + RingCycleState: 0 + CommandStop: 0 + ... + Runtime Registers + ----------------- + dt USBXHCI!_RUNTIME_REGISTERS 0xfffff880046a8600 + MicroFrameIndex: 0x3f7a + + dt -ba8 USBXHCI!_INTERRUPTER_REGISTER_SET 0xfffff880046a8620 + + RootPort Registers + ------------------ + dt -a4 -r2 USBXHCI!_PORT_REGISTER_SET 0xfffff880046a8420 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_registers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-resourceusage.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-resourceusage.md new file mode 100644 index 0000000000..03866bc6dc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-resourceusage.md @@ -0,0 +1,107 @@ +--- +title: usb3kd.xhci_resourceusage +description: The usb3kd.xhci_resourceusage extension displays the resources used by a USB 3.0 host controller. +ms.assetid: 6AAB64D6-3CDA-4BA2-BBA8-F2F5AD1DBB6F +keywords: ["usb3kd.xhci_resourceusage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_resourceusage +api_type: +- NA +--- + +# !usb3kd.xhci\_resourceusage + + +The [**!usb3kd.xhci\_resourceusage**](-usb3kd-device-info.md) extension displays the resources used by a USB 3.0 host controller. + +``` +!usb3kd.xhci_resourceusage DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the host controller's functional device object (FDO). + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the **!xhci\_resourceusage** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +Examples +-------- + +To obtain the address of the device extension, look at the output of the [**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) command. In the following example, the address of the device extension is 0xfffffa800536e2d0. + +``` +3: kd> !xhci_dumpall + +## Dumping all the XHCI controllers - DrvObj 0xfffffa80053072f0 +------------------------------------------------------------ +1) ... - PCI: VendorId ... DeviceId ... RevisionId ... Firmware ... + + dt USBXHCI!_CONTROLLER_DATA 0xfffffa80052f20c0 + !rcdrlogdump USBXHCI -a 0xfffffa8005068520 + !rcdrlogdump USBXHCI -a 0xfffffa8004e8b9a0 (rundown) + !wdfdevice 0x57ffac91fd8 + !xhci_capability 0xfffffa800536e2d0 + !xhci_registers 0xfffffa800536e2d0 + !xhci_commandring 0xfffffa800536e2d0 (No commands are pending) + !xhci_deviceslots 0xfffffa800536e2d0 + !xhci_eventring 0xfffffa800536e2d0 + !xhci_resourceusage 0xfffffa800536e2d0 + ... +``` + +Now you can pass the address of the device extension to the **!xhci\_resourceusage** command. + +``` + 3: kd> !xhci_resourceusage 0xfffffa800536e2d0 + +## Dumping CommonBuffer Resources +------------------------------ + dt USBXHCI!_COMMON_BUFFER_DATA 0xfffffa80059a5920 + DmaEnabler:!wdfdmaenabler 0x57ffa65a9c8 + + CommonBuffers Large: Total 9 Available 2 Used 7 TotalBytes 36864 + [ 1] dt _TRACKING_DATA 0xfffffa80059a6768 VA 0xfffffa8005370000 LA 0x117170000 ... + [ 2] dt _TRACKING_DATA 0xfffffa80059a4768 VA 0xfffffa8005373000 LA 0x117173000 ... + ... + CommonBuffers Small: Total 32 Available 8 Used 24 TotalBytes 16384 + [ 1] dt _TRACKING_DATA 0xfffffa80059a2798 VA 0xfffffa8005aeb000 LA 0x1168eb000 ... + [ 2] dt _TRACKING_DATA 0xfffffa80059a27e8 VA 0xfffffa8005aeb200 LA 0x1168eb200 ... + ... +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_resourceusage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-transferring.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-transferring.md new file mode 100644 index 0000000000..9857b3afc8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-transferring.md @@ -0,0 +1,115 @@ +--- +title: usb3kd.xhci_transferring +description: The usb3kd.xhci_transferring extension displays a transfer ring (used by a USB 3.0 host controller) until it detects a cycle bit change. +ms.assetid: BCF6DEF0-FB58-4FE6-88AD-BF778E00F052 +keywords: ["usb3kd.xhci_transferring Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_transferring +api_type: +- NA +--- + +# !usb3kd.xhci\_transferring + + +The [**!usb3kd.xhci\_transferring**](-usb3kd-device-info.md) extension displays a transfer ring (used by a USB 3.0 host controller) until it detects a cycle bit change. + +``` +!usb3kd.xhci_transferring VirtualAddress +!usb3kd.xhci_transferring PhysicalAddress 1 +``` + +## Parameters + + + *VirtualAddress* +Virtual address of the transfer ring. + + *PhysicalAddress* +Physical address of the transfer ring. + + 1 +Specifies that the address is a physical address. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output of the **!xhci\_transferring** command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +The transfer ring is a structure used by the USB 3.0 host controller driver to maintain a list of transfer request blocks (TRBs). This command takes the virtual or physical address of a transfer ring, but displays the physical address of the TRBs. This is done so the command can correctly traverse LINK TRBs. + +Examples +-------- + +To obtain the address of the transfer ring, look at the output of the [**!xhci\_deviceslots**](-usb3kd-xhci-deviceslots.md) command. In the following example, the virtual address of the transfer ring is 0xfffffa8005b2fe00. + +``` +3: kd> !usb3kd.xhci_deviceslots 0xfffffa800523a2d0 + +## Dumping dt _DEVICESLOT_DATA 0xfffffa80051a3300 +---------------------------------------------- +DeviceContextBase: VA 0xfffffa8005a41000 LA 0x116841000 !wdfcommonbuffer 0x57ffa6ff9b8 Size 4096 + +## [1] SlotID : dt USBXHCI!_USBDEVICE_DATA 0xfffffa800598c7d0 dt _SLOT_CONTEXT32 0xfffffa8005a42000 +------------------------------------------------------------------------------------------------ + USB\VID_125F&PID_312A ADATA Technology Co., Ltd. + SlotEnabled IsDevice NumberOfTTs 0 TTThinkTime 0 + Speed: Super PortPathDepth: 1 PortPath: [ 2 ] DeviceAddress: 1 + !device_info_from_pdo 0xfffffa800597d720 + DeviceContextBuffer: VA 0xfffffa8005a42000 LA 0x116842000 !wdfcommonbuffer 0x57ffa7009b8 Size 4096 + InputDeviceContextBuffer: VA 0xfffffa8005b2d000 LA 0x11692d000 !wdfcommonbuffer 0x57ffa674958 Size 4096 + ... + + [3] DeviceContextIndex : dt USBXHCI!_ENDPOINT_DATA 0xfffffa8005b394e0 dt _ENDPOINT_CONTEXT32 0xfffffa8005a42060 ES_RUNNING + -------------------------------------------------------------------------------------------------------------- + ... + CurrentRingBufferData: VA 0xfffffa8005b2fe00 LA 0x11692fe00 !wdfcommonbuffer 0x57ffa67c988 Size 512 + Current: !xhci_transferring 0xfffffa8005b2fe00 + PendingTransferList: + [0] dt _TRANSFER_DATA 0xfffffa8005b961b0 !urb 0xfffffa8005b52be8 !wdfrequest 0x57ffa469fd8 TransferState_Pending +``` + +Now you can pass the address of the transfer ring to the **!xhci\_transferring** command. + +``` +kd> !xhci_transferring 0xfffffa8005b2fe00 + + [ 0] NORMAL 0x000000011692fe00 CycleBit 1 IOC 0 BEI 0 InterrupterTarget 0 TransferLength 13 TDSize 0 + [ 1] EVENT_DATA 0x000000011692fe10 CycleBit 1 IOC 1 BEI 0 InterrupterTarget 0 Data 0 0xfffffa8005986850 TotalBytes 13 + [ 2] NORMAL 0x000000011692fe20 CycleBit 1 IOC 0 BEI 0 InterrupterTarget 0 TransferLength 13 TDSize 0 + [ 3] EVENT_DATA 0x000000011692fe30 CycleBit 1 IOC 1 BEI 0 InterrupterTarget 0 Data 0 0xfffffa8005b96210 TotalBytes 13 + [ 4] NORMAL 0x000000011692fe40 CycleBit 1 IOC 0 BEI 0 InterrupterTarget 0 TransferLength 13 TDSize 0 + [ 5] EVENT_DATA 0x000000011692fe50 CycleBit 1 IOC 1 BEI 0 InterrupterTarget 0 Data 0 0xfffffa8005b96210 TotalBytes 13 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_transferring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usb3kd-xhci-trb.md b/windows-driver-docs-pr/debugger/-usb3kd-xhci-trb.md new file mode 100644 index 0000000000..df318396c3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usb3kd-xhci-trb.md @@ -0,0 +1,94 @@ +--- +title: usb3kd.xhci_trb +description: The usb3kd.xhci_trb extension displays one or more transfer request blocks (TRBs) used by a USB 3.0 host controller +ms.assetid: 6EC90908-320E-4908-BE53-1AD01A81B140 +keywords: ["usb3kd.xhci_trb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usb3kd.xhci_trb +api_type: +- NA +--- + +# !usb3kd.xhci\_trb + + +The [**!usb3kd.xhci\_trb**](-usb3kd-device-info.md) extension displays one or more transfer request blocks (TRBs) used by a USB 3.0 host controller + +``` +!usb3kd.xhci_trb VirtualAddress Count +!usb3kd.xhci_trb PhysicalAddress Count 1 +``` + +## Parameters + + + *VirtualAddress* +Virtual address of a TRB. + + *PhysicalAddress* +Physical address of a TRB. + + *Count* +The number of consecutive TRBs to display, starting at *VirtualAddress* or *PhysicalAddress*. + + 1 +Specifies that the address is a physical address. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The output the [**!xhci\_trb**](-usb3kd-device-info.md) command is based on the data structures maintained by the USB 3.0 host controller driver (UsbXhci.sys). For more information about the USB 3.0 host controller driver and other drivers in the USB stack, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +Examples +-------- + +In the following example, **0x844d7c00** is the virtual address of a TRB. The **1** is the count, which specifies how many consecutive TRBs to display. + +``` +0: kd> !xhci_trb 0x844d7c00 1 + + [ 0] ISOCH 0x844d7c00 CycleBit 1 IOC 0 CH 1 BEI 0 InterrupterTarget 1 TransferLength 2688 TDSize 0 TBC 0 TLBPC 2 Frame 0x3D2 +``` + +In the following example, **0x0dced7c00** is the physical address of a TRB. The **4** is the count, which specifies how many consecutive TRBs to display. The **1** specifies that the address is a physical address. + +``` +0: kd> !xhci_trb 0x0dced7c00 4 1 + + [ 0] ISOCH 0xdced7c00 CycleBit 1 IOC 0 CH 1 BEI 0 InterrupterTarget 1 TransferLength 2688 TDSize 0 TBC 0 TLBPC 2 Frame 0x3D2 + [ 1] EVENT_DATA 0xdced7c10 CycleBit 1 IOC 1 CH 0 BEI 1 InterrupterTarget 1 Data 0x194c9bcf001b0001 PacketId 27 Frame 0x194c9bcf TotalBytes 2688 + [ 2] ISOCH 0xdced7c20 CycleBit 1 IOC 0 CH 1 BEI 0 InterrupterTarget 1 TransferLength 1352 TDSize 2 TBC 0 TLBPC 2 Frame 0x3D2 + [ 3] NORMAL 0xdced7c30 CycleBit 1 IOC 0 CH 1 BEI 0 InterrupterTarget 1 TransferLength 1336 TDSize 0 +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usb3kd.xhci_trb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehcidd.md b/windows-driver-docs-pr/debugger/-usbkd--ehcidd.md new file mode 100644 index 0000000000..65647cd37b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehcidd.md @@ -0,0 +1,96 @@ +--- +title: usbkd._ehcidd +description: The usbkd._ehcidd command displays information from a usbehci _DEVICE_DATA structure. +ms.assetid: 8D594564-6506-44A8-A109-A76DA5AE7D89 +keywords: ["usbkd._ehcidd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehcidd +api_type: +- NA +--- + +# !usbkd.\_ehcidd + + +The **!usbkd.\_ehcidd** command displays information from a **usbehci!\_DEVICE\_DATA** structure. + +``` +!usbkd._ehcidd StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_DEVICE\_DATA** structure. To find addresses of **usbehci!\_DEVICE\_DATA** structures, use [**!usbhcdext**](-usbkd-usbhcdext.md) or [**!usbhcdlist**](-usbkd-usbhcdlist.md). + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to get the address of a **usbehci!\_DEVICE\_DATA** structure. First enter [**!usbkd.usbhcdlist**](-usbkd-usbhcdlist.md). + +``` +0: kd> !usbkd.usbhcdlist + +MINIPORT List @ fffff80001e5bbd0 + +## List of EHCI controllers + +!drvobj ffffe00001fd33a0 dt USBPORT!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 Registration Packet ffffe00001f48c08 + +01. Xxxx Corporation PCI: VendorID Xxxx DeviceID Xxxx RevisionId 0002 + !devobj ffffe0000781a050 + !ehci_info ffffe0000781a1a0 + Operational Registers ffffd00021fb8420 + Device Data ffffe0000781bda0 + ... +``` + +In the preceding output, `ffffe0000781bda0` is the address of a **\_DEVICE\_DATA** structure. + +Now pass the structure address to **!\_ehcidd** + +``` +0: kd> !usbkd._ehcidd ffffe0000781bda0 + +*USBEHCI DEVICE DATA ffffe0000781bda0 +** dt usbehci!_DEVICE_DATA ffffe0000781bda0 + +get_field_ulong ffffe0000781bda0 usbehci!_DEVICE_DATA Flags +*All Enpoints list: +head @ ffffe0000781bdb0 f_link ffffe0000781bdb0 b_link ffffe0000781bdb0 +AsyncQueueHead ffffd00021cf5000 !_ehciqh ffffd00021cf5000 + PhysicalAddress: 0xde79a000 + NextQh: ffffd00021cf5000 Hlink de79a002 + PrevQh: ffffd00021cf5000 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehcidd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehciep.md b/windows-driver-docs-pr/debugger/-usbkd--ehciep.md new file mode 100644 index 0000000000..149fd309ff --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehciep.md @@ -0,0 +1,133 @@ +--- +title: usbkd._ehciep +description: The usbkd._ehciep command displays information from a usbehci _ENDPOINT_DATA structure. Use this command to display information about asynchronous endpoints (that is, control and bulk endpoints). +ms.assetid: 0DA42FDD-41D6-4234-9D9C-36872F0CE0C1 +keywords: ["usbkd._ehciep Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehciep +api_type: +- NA +--- + +# !usbkd.\_ehciep + + +The **!usbkd.\_ehciep** command displays information from a **usbehci!\_ENDPOINT\_DATA** structure. Use this command to display information about asynchronous endpoints (that is, control and bulk endpoints). + +``` +!usbkd._ehciep StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_ENDPOINT\_DATA** structure. To find addresses of **usbehci!\_ENDPOINT\_DATA** structures, use [**!usbhcdext**](-usbkd-usbhcdext.md) and [**!usblist**](-usbkd-usblist.md). + +## DLL + + +Usbkd.dll + +Examples +-------- + +This example shows one way to get the address of a **usbehci!\_ENDPOINT\_DATA** structure. Start with the [**!usb2tree**](-usbkd-usb2tree.md) command. + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe0000206e1a0 !devobj ffffe0000206e050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000024a61a0 !devstack ffffe000024a6050 + Port 1: !port2_info ffffe000026dd000 + Port 2: !port2_info ffffe000026ddb40 + Port 3: !port2_info ffffe000026de680 !devstack ffffe00001ec3060 + !device2_info ffffe00001ec31b0 (USB Mass Storage Device: Xxx Corporation) + Port 4: !port2_info ffffe000026df1c0 +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe0000206e1a0**. Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072). + +``` +0: kd> !usbkd.usbhcdext ffffe0000206e1a0 +... +DeviceHandleList: !usblist ffffe0000206f3b8, DL +DeviceHandleDeletedList: !usblist ffffe0000206f3c8, DL [Empty] +GlobalEndpointList: !usblist ffffe0000206f388, EP +... +``` + +The preceding output displays the command **!usblist ffffe0000206f388, EP**. Use this command to display a list of endpoints. + +``` +0: kd> !usblist ffffe0000206f388, EP +list: ffffe0000206f388 EP +... +dt usbport!_HCD_ENDPOINT ffffe000026dc970 !usbep ffffe000026dc970 +common buffer bytes 0x00003000 (12288) @ va 0000000021e6e000 pa 00000000d83c9000 +Device Address: 0x01, ep 0x81 Bulk In Flags: 00000041 dt _USB_ENDPOINT_FLAGS ffffe000026dc990 +... usbehci!_ENDPOINT_DATA ffffe000026dcc38 +... +``` + +In the preceding output, `ffffe000026dcc38` is the address of a **usbehci!\_ENDPOINT\_DATA** structure. Pass this address to **!\_ehciep**. + +``` +0: kd> !usbkd._ehciep ffffe000026dcc38 +*USBEHCI +dt usbehci!_ENDPOINT_DATA ffffe000026dcc38 +Flags: 0x00000000 +dt usbehci!_HCD_QUEUEHEAD_DESCRIPTOR ffffd00021e6e080 +*HwQH ffffd00021e6e080 +HwQH + HwQH.HLink dea2e002 + HwQH.EpChars 02002101 + DeviceAddress: 0x1 + IBit: 0x0 + EndpointNumber: 0x1 + EndpointSpeed: 0x2 HcEPCHAR_HighSpeed + DataToggleControl: 0x0 + HeadOfReclimationList: 0x0 + MaximumPacketLength: 0x200 - 512 + ... +current slot 0000000000000000 +slot[0] dt usbehci!_ENDPOINT_SLOT ffffe000026dcdb8 - slot_NotBusy +---- + ffffd00021e6e100 + dt usbehci!_HCD_TRANSFER_DESCRIPTOR ffffd00021e6e100 + tdphys: d83c9100'200 txlen 00000000 tx ffffd00000000041 flags 6d4e695d _BUSY _SLOT_RESET + Next_qTD: d83c9200'd83c9180 AltNext_qTD 77423c00'41 + NextTD: ffffd00021e6e200 AltNextTD ffffd00021e6e180 SlotNextTd ffffd00021e6e200 tok 00000c00 Xbytes x0 (0) +. + ffffd00021e6e200 + dt usbehci!_HCD_TRANSFER_DESCRIPTOR ffffd00021e6e200 + tdphys: d83c9200'5000 txlen 00000000 tx ffffd00000000041 flags 6d4e695d _BUSY _SLOT_RESET + Next_qTD: d83c9280'd83c9180 AltNext_qTD 77423c00'41 + NextTD: ffffd00021e6e280 AltNextTD ffffd00021e6e180 SlotNextTd ffffd00021e6e280 tok 00000c00 Xbytes x0 (0) +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehciep%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehciframe.md b/windows-driver-docs-pr/debugger/-usbkd--ehciframe.md new file mode 100644 index 0000000000..d713806813 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehciframe.md @@ -0,0 +1,58 @@ +--- +title: usbkd._ehciframe +description: The usbkd._ehciframe command displays an EHCI miniport FrameListBaseAddress periodic list entry chain indexed by a frame number. +ms.assetid: 6359FC98-F070-410E-AFE7-C2C67A4F7C98 +keywords: ["usbkd._ehciframe Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehciframe +api_type: +- NA +--- + +# !usbkd.\_ehciframe + + +The **!usbkd.\_ehciframe** command displays an EHCI miniport FrameListBaseAddress periodic list entry chain indexed by a frame number. + +``` +!usbkd._ehciframe StructAddr, FrameNumber +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_DEVICE\_DATA** structure. + + *FrameNumber* +Frame number in the range 0 through 1023. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehciframe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehciitd.md b/windows-driver-docs-pr/debugger/-usbkd--ehciitd.md new file mode 100644 index 0000000000..ce55d45ad9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehciitd.md @@ -0,0 +1,55 @@ +--- +title: usbkd._ehciitd +description: The usbkd._ehciitd command displays information from a usbehci _HCD_HSISO_TRANSFER_DESCRIPTOR structure. +ms.assetid: 0878695D-E7ED-498D-AD37-994371C319C4 +keywords: ["usbkd._ehciitd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehciitd +api_type: +- NA +--- + +# !usbkd.\_ehciitd + + +The **!usbkd.\_ehciitd** command displays information from a **usbehci!\_HCD\_HSISO\_TRANSFER\_DESCRIPTOR** structure. + +``` +!usbkd._ehciitd StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HCD\_HSISO\_TRANSFER\_DESCRIPTOR** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehciitd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehciqh.md b/windows-driver-docs-pr/debugger/-usbkd--ehciqh.md new file mode 100644 index 0000000000..0067078df0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehciqh.md @@ -0,0 +1,55 @@ +--- +title: usbkd._ehciqh +description: The usbkd._ehciqh command displays information from a usbehci _HCD_QUEUEHEAD_DESCRIPTOR structure. +ms.assetid: 52A1CF03-3B1D-4CC6-A4DD-3E73A7AB2F00 +keywords: ["usbkd._ehciqh Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehciqh +api_type: +- NA +--- + +# !usbkd.\_ehciqh + + +The **!usbkd.\_ehciqh** command displays information from a **usbehci!\_HCD\_QUEUEHEAD\_DESCRIPTOR** structure. Use this command to display information about asynchronous endpoints (that is, control and bulk endpoints). + +``` +!usbkd._ehciqh StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HCD\_QUEUEHEAD\_DESCRIPTOR** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehciqh%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehciregs.md b/windows-driver-docs-pr/debugger/-usbkd--ehciregs.md new file mode 100644 index 0000000000..c6f5e4c91b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehciregs.md @@ -0,0 +1,157 @@ +--- +title: usbkd._ehciregs +description: The usbkd._ehciregs command displays the operational and root hub port status registers of a USB EHCI host controller. +ms.assetid: BFD58E6B-BC51-4F2F-B597-8C815826F931 +keywords: ["usbkd._ehciregs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehciregs +api_type: +- NA +--- + +# !usbkd.\_ehciregs + + +The **!usbkd.\_ehciregs** command displays the operational and root hub port status registers of a USB EHCI host controller. + +``` +!usbkd._ehciregs StructAddr[, NumPorts] +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HC\_OPERATIONAL\_REGISTER** structure. To find the address of a **usbehci!\_HC\_OPERATIONAL\_REGISTER** structure, use [**!usbkd.usbhcdlist**](-usbkd-usbhcdlist.md). + + *NumPorts* +The number of root hub port status registers to display. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to get the address of a **usbehci!\_HC\_OPERATIONAL\_REGISTER** structure. First enter [**!usbkd.usbhcdlist**](-usbkd-usbhcdlist.md). + +``` +0: kd> !usbkd.usbhcdlist +MINIPORT List @ fffff80001e5bbd0 + +## List of EHCI controllers + +!drvobj ffffe00001fd33a0 dt USBPORT!_USBPORT_MINIPORT_DRIVER ... +... +02. Xxxx Corporation PCI: VendorID Xxxx DeviceID Xxxx RevisionId 0002 + !devobj ffffe00001ca1050 + !ehci_info ffffe00001ca11a0 + Operational Registers ffffd000228bf020 +``` + +In the preceding output,` ffffd000228bf020` is the address of a **\_HC\_OPERATIONAL\_REGISTER** structure. + +Now pass the structure address to **!\_ehciregs**. In this example, the second argument limits the display to two root hub port status registers. + +``` +0: kd> !usbkd._ehciregs ffffd000228bf020, 2 +*(ehci)HC_OPERATIONAL_REGISTER ffffd000228bf020 + USBCMD 00010001 + .HostControllerRun: 1 + .HostControllerReset: 0 + .FrameListSize: 0 + .PeriodicScheduleEnable: 0 + .AsyncScheduleEnable: 0 + .IntOnAsyncAdvanceDoorbell: 0 + .HostControllerLightReset: 0 + .InterruptThreshold: 1 + .ParkModeEnable: 0 + .ParkModeCount: 0 + + USBSTS 00002008 + .UsbInterrupt: 0 + .UsbError: 0 + .PortChangeDetect: 0 + .FrameListRollover: 1 + .HostSystemError: 0 + .IntOnAsyncAdvance: 0 + ---- + .HcHalted: 0 + .Reclimation: 1 + .PeriodicScheduleStatus: 0 + .AsyncScheduleStatus: 0 + + USBINTR 0000003f + .UsbInterrupt: 1 + .UsbError: 1 + .PortChangeDetect: 1 + .FrameListRollover: 1 + .HostSystemError: 1 + .IntOnAsyncAdvance: 1 + PeriodicListBase dec8e000 + AsyncListAddr dec91000 + PortSC[0] 00001000 + PortConnect x0 + PortConnectChange x0 + PortEnable x0 + PortEnableChange x0 + OvercurrentActive x0 + OvercurrentChange x0 + ForcePortResume x0 + PortSuspend x0 + PortReset x0 + HighSpeedDevice x0 + LineStatus x0 + PortPower x1 + PortOwnedByCC x0 + PortIndicator x0 + PortTestControl x0 + WakeOnConnect x0 + WakeOnDisconnect x0 + WakeOnOvercurrent x0 + PortSC[1] 00001000 + PortConnect x0 + PortConnectChange x0 + PortEnable x0 + PortEnableChange x0 + OvercurrentActive x0 + OvercurrentChange x0 + ForcePortResume x0 + PortSuspend x0 + PortReset x0 + HighSpeedDevice x0 + LineStatus x0 + PortPower x1 + PortOwnedByCC x0 + PortIndicator x0 + PortTestControl x0 + WakeOnConnect x0 + WakeOnDisconnect x0 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehciregs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehcisitd.md b/windows-driver-docs-pr/debugger/-usbkd--ehcisitd.md new file mode 100644 index 0000000000..14338eb36f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehcisitd.md @@ -0,0 +1,55 @@ +--- +title: usbkd._ehcisitd +description: The usbkd._ehcisitd command displays information from a usbehci _HCD_SI_TRANSFER_DESCRIPTOR +ms.assetid: FA1F61AE-A9D4-429E-97BC-0CCC3A9AF33E +keywords: ["usbkd._ehcisitd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehcisitd +api_type: +- NA +--- + +# !usbkd.\_ehcisitd + + +The **!usbkd.\_ehcisitd** command displays information from a **usbehci!\_HCD\_SI\_TRANSFER\_DESCRIPTOR** + +``` +!usbkd._ehcisitd StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HCD\_SI\_TRANSFER\_DESCRIPTOR** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehcisitd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehcistq.md b/windows-driver-docs-pr/debugger/-usbkd--ehcistq.md new file mode 100644 index 0000000000..8f5f1240ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehcistq.md @@ -0,0 +1,55 @@ +--- +title: usbkd._ehcistq +description: The usbkd._ehcistq command displays a usbehci _HCD_QUEUEHEAD_DESCRIPTOR structure. +ms.assetid: 282206D2-7F4A-4EBA-A874-F1744F218194 +keywords: ["usbkd._ehcistq Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehcistq +api_type: +- NA +--- + +# !usbkd.\_ehcistq + + +The **!usbkd.\_ehcistq** command displays a **usbehci!\_HCD\_QUEUEHEAD\_DESCRIPTOR** structure. + +``` +!usbkd._ehciep StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HCD\_QUEUEHEAD\_DESCRIPTOR** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehcistq%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehcitd.md b/windows-driver-docs-pr/debugger/-usbkd--ehcitd.md new file mode 100644 index 0000000000..3c9f53ba88 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehcitd.md @@ -0,0 +1,122 @@ +--- +title: usbkd._ehcitd +description: The usbkd._ehcitd command displays information from a usbehci _TRANSFER_CONTEXT structure. +ms.assetid: C0EE04CF-E059-4064-9791-3500E66B24FA +keywords: ["usbkd._ehcitd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehcitd +api_type: +- NA +--- + +# !usbkd.\_ehcitd + + +The **!usbkd.\_ehcitd** command displays information from a **usbehci!\_TRANSFER\_CONTEXT** structure. Use this command to display information about asynchronous endpoints (that is, control and bulk endpoints). + +``` +!usbkd._ehcitd StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_TRANSFER\_CONTEXT** structure. + +## DLL + + +Usbkd.dll + +Examples +-------- + +This example shows one way to get the address of a **usbehci!\_TRANSFER\_CONTEXT** structure. Use [**!\_ehciep**](-usbkd--ehciep.md) to display information about an endpoint. + +``` +0: kd> !_ehciep ffffe000001ab618 +*USBEHCI +dt usbehci!_ENDPOINT_DATA ffffe000001ab618 +Flags: 0x00000000 +dt usbehci!_HCD_QUEUEHEAD_DESCRIPTOR ffffd00021e65080 +*HwQH ffffd00021e65080 +HwQH + HwQH.HLink dea2e002 + HwQH.EpChars 02002201 + DeviceAddress: 0x1 + IBit: 0x0 + EndpointNumber: 0x2 + ... +slot[0] dt usbehci!_ENDPOINT_SLOT ffffe000001ab798 - slot_NotBusy +---- + ffffd00021e65100 + dt usbehci!_HCD_TRANSFER_DESCRIPTOR ffffd00021e65100 + .... +``` + +In the preceding output, `ffffd00021e65100` is the address of a **usbehci!\_TRANSFER\_CONTEXT** structure. Pass this address to **!\_ehcitd**. + +``` +0: kd> !_ehcitd ffffd00021e65100 +*USBEHCI TD 21e65100 +Sig 20td + qTD + Next_qTD: d83cc200 + AltNext_qTD: d83cc180 + Token: 0x00000c00 + PingState: 0x0 + SplitXstate: 0x0 + MissedMicroFrame: 0x0 + XactErr: 0x0 + BabbleDetected: 0x0 + DataBufferError: 0x0 + Halted: 0x0 + Active: 0x0 + Pid: 0x0 - HcTOK_Out + ErrorCounter: 0x3 + C_Page: 0x0 + InterruptOnComplete: 0x0 + BytesToTransfer: 0x0 + DataToggle: 0x0 + BufferPage[0]: 0x 0bad0-000 0bad0000 BufferPage64[0]: 00000000 + BufferPage[1]: 0x 0bad0-000 0bad0000 BufferPage64[1]: 00000000 + BufferPage[2]: 0x 0bad0-000 0bad0000 BufferPage64[2]: 00000000 + BufferPage[3]: 0x 0bad0-000 0bad0000 BufferPage64[3]: 00000000 + BufferPage[4]: 0x 0bad0-000 0bad0000 BufferPage64[4]: 00000000 +Packet:00 52 e6 21 00 d0 ff ff +PhysicalAddress: d83cc100 +EndpointData: 001ab618 +TransferLength : 0000001f +TransferContext: 00000000 +Flags: 00000041 + TD_FLAG_BUSY +NextHcdTD: 21e65200 +AltNextHcdTD: 21e65180 +SlotNextHcdTD: 21e65200 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehcitd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd--ehcitfer.md b/windows-driver-docs-pr/debugger/-usbkd--ehcitfer.md new file mode 100644 index 0000000000..9f79c4edc1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd--ehcitfer.md @@ -0,0 +1,55 @@ +--- +title: usbkd._ehcitfer +description: The usbkd._ehcitfer command displays information from a usbehci _HCD_TRANSFER_DESCRIPTOR structure. +ms.assetid: 745B8891-150C-4E25-8814-E8F35FB939F5 +keywords: ["usbkd._ehcitfer Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd._ehcitfer +api_type: +- NA +--- + +# !usbkd.\_ehcitfer + + +The **!usbkd.\_ehcitfer** command displays information from a **usbehci!\_HCD\_TRANSFER\_DESCRIPTOR** structure. + +``` +!usbkd._ehcitfer StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbehci!\_HCD\_TRANSFER\_DESCRIPTOR** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd._ehcitfer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-doesdumphaveusbdata.md b/windows-driver-docs-pr/debugger/-usbkd-doesdumphaveusbdata.md new file mode 100644 index 0000000000..577a48bd60 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-doesdumphaveusbdata.md @@ -0,0 +1,86 @@ +--- +title: usbkd.doesdumphaveusbdata +description: The usbkd.doesdumphaveusbdata command checks to see which types of USB data are in a crash dump file that was generated as a result of Bug Check 0xFE. +ms.assetid: 5E475E9F-BC8E-4185-9F63-5BAD49A83904 +keywords: ["usbkd.doesdumphaveusbdata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.doesdumphaveusbdata +api_type: +- NA +--- + +# !usbkd.doesdumphaveusbdata + + +The **!usbkd.doesdumphaveusbdata** command checks to see which types of USB data are in a crash dump file that was generated as a result of [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.doesdumphaveusbdata +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +Examples +-------- + +Here is an example of the output of **!doesdumphaveusbdata** + +``` +1: kd> !analyze -v +*** ... +BUGCODE_USB_DRIVER (fe) +... +1: kd> !usbkd.doesdumphaveusbdata + +Retrieving crashdump information Please Wait... + +Checking for GuidUsbHubPortArrayData information... +There is no data for this GUID in the mini dump. +No data to print + +Checking for GuidUsbHubExt information... +There is no data for this GUID in the mini dump. +No data to print + +Checking for GuidUsbPortLog information... +GuidUsbPortLog Exists with PORT Log Size = 8000 + +Checking for GuidUsbPortContextData information... +GuidUsbPortContextData Exists with Data Length = 4c8 + +Checking for GuidUsbPortExt information... +GuidUsbPortExt Exists (DEVICE_EXTENSION + DeviceDataSize ) = 2250 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.doesdumphaveusbdata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-ehci-info-from-fdo.md b/windows-driver-docs-pr/debugger/-usbkd-ehci-info-from-fdo.md new file mode 100644 index 0000000000..df25658b06 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-ehci-info-from-fdo.md @@ -0,0 +1,106 @@ +--- +title: usbkd.ehci_info_from_fdo +description: The usbkd.ehci_info_from_fdo command displays information about a USB host controller. +ms.assetid: C7026EF3-F58D-45EB-83D5-8B4A3E661759 +keywords: ["usbkd.ehci_info_from_fdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.ehci_info_from_fdo +api_type: +- NA +--- + +# !usbkd.ehci\_info\_from\_fdo + + +The [**!usbkd.ehci\_info\_from\_fdo**](https://msdn.microsoft.com/library/windows/hardware/dn367058) command displays information about a USB host controller. + +``` +!usbkd.ehci_info_from_fdo fdo +``` + +## Parameters + + + *fdo* +Address of the functional device object (FDO) of a UHCI or EHCI USB host controller. You can get the address of the FDO from the output of the [**!usb2tree**](-usbkd-usb2tree.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +First use the [**!usb2tree**](-usbkd-usb2tree.md) command to get the address of the FDO. + +``` +0: kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 + +1)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 +... +``` + +In the preceding output, you can see that the address of the FDO of the USB host controller is `ffffe00001ca1050`. Pass the address of the FDO to [**!ehci\_info\_from\_fdo**](https://msdn.microsoft.com/library/windows/hardware/dn367058). + +``` +0: kd> !usbkd.ehci_info_from_fdo ffffe00001ca1050 + +HC Flavor 1000 FDO ffffe00001ca1050 +Root Hub: FDO ffffe00002320050 !hub2_info ffffe000023201a0 +Operational Registers ffffd000228bf020 +Device Data ffffe00001ca2da0 +dt USBPORT!_FDO_EXTENSION ffffe00001ca15a0 +DM Timer Flags ffffe00001ca16d4 +FDO Flags ffffe00001ca16d0 +HCD Log ffffe00001ca11a0 + +DeviceHandleList: !usblist ffffe00001ca23b8, DL +DeviceHandleDeletedList: !usblist ffffe00001ca23c8, DL [Empty] +GlobalEndpointList: !usblist ffffe00001ca2388, EP +EpNeoStateChangeList: !usblist ffffe00001ca2370, SC [Empty] +GlobalTtListHead: !usblist ffffe00001ca23a8, TT [Empty] +BusContextHead: !usblist ffffe00001ca16b0, BC + +## Pending Requests + +[001] dt USBPORT!_USB_IOREQUEST_CONTEXT ffffe00001ca1450 Tag: AddD Obj: ffffe00001ca11a0 +... + +## XDPC List + +01) dt USBPORT!_XDPC_CONTEXT ffffe00001ca1f18 +... + +## PnP FUNC HISTORY (latest at bottom) + +[01] IRP_MN_QUERY_CAPABILITIES +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.ehci_info_from_fdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-hub2-info-from-fdo.md b/windows-driver-docs-pr/debugger/-usbkd-hub2-info-from-fdo.md new file mode 100644 index 0000000000..5f769228bb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-hub2-info-from-fdo.md @@ -0,0 +1,147 @@ +--- +title: usbkd.hub2_info_from_fdo +description: The usbkd.hub2_info_from_fdo command displays information about a USB hub. +ms.assetid: BB40AEDD-9FDF-43BE-A741-56D06BE2965C +keywords: ["usbkd.hub2_info_from_fdo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.hub2_info_from_fdo +api_type: +- NA +--- + +# !usbkd.hub2\_info\_from\_fdo + + +The **!usbkd.hub2\_info\_from\_fdo** command displays information about a USB hub. + +``` +!usbkd.hub2_info_from_fdo FDO +``` + +## Parameters + + + *FDO* +Address of the functional device object (FDO) for a USB hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the FDO for a USB hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 +``` + +In the preceding output, the address of the FDO for the hub appears as the argument of the suggested command **!devstack ffffe00002320050**. + +Now pass the address of the FDO to the **!hub2\_info\_from\_fdo** command. + +``` +0: kd> !usbkd.hub2_info_from_fdo ffffe00002320050 +usbhubext +***************************************************************************** + +FDO ffffe00002320050 PDO ffffe0000213c050 HubNumber# 3 +dt USBHUB!_DEVICE_EXTENSION_HUB ffffe000023201a0 +!usbhublog ffffe000023201a0 +RemoveLock ffffe00002320668 +FdoFlags ffffe00002320ba0 + +CurrentPowerIrp: System (0000000000000000) Device (0000000000000000) + +ObjReferenceList: !usblist ffffe00002320b70, RL +ExceptionList: !usblist ffffe00002321498, EL [Empty] +DmTimerListHead: !usblist ffffe00002321040, TL [Empty] +PdoRemovedListHead: !usblist ffffe00002321478, PL [Empty] +PdoPresentListHead: !usblist ffffe00002321468, PL +WorkItemListHead: !usblist ffffe00002320c80, WI [Empty] +SshBusyListHead: !usblist ffffe00002320dc0, BL + + +## PnP FUNC HISTORY (latest at bottom) + +01. IRP_MN_QUERY_DEVICE_RELATIONS +... + +## POWER FUNC HISTORY (latest at bottom) + +01. IRP_MN_QUERY_POWER - PowerSystemHibernate +... + +## HARD RESET STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. HRE_Pause HReset_WaitReady HReset_Paused +... + +## PNP STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. Ev_SYSTEM_POWER FDO_WaitPnpStop FDO_WaitPnpStop +... + +## POWER STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. Ev_SET_POWER_S0 FdoSx_Dx FdoWaitS0IoComplete_Dx +... + +## BUS STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. BE_BusSuspend BS_BusPause BS_BusSuspend +... + +SSH_EnabledStatus: [SSH_ENABLED_VIA_POWER_POLICY] + +## SSH STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. SSH_Event_ResumeHubComplete SSH_State_HubPendingResume SSH_State_HubActive +... + +## PORT DATA + +PortData 1: !port2_info ffffe000021bf000 Port State = PS_WAIT_CONNECT PortChangeLock: 0, Pcq_State: Pcq_Run_Idle + PDO 0000000000000000 +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.hub2_info_from_fdo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-isthisdumpasyncissue.md b/windows-driver-docs-pr/debugger/-usbkd-isthisdumpasyncissue.md new file mode 100644 index 0000000000..41d6edf020 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-isthisdumpasyncissue.md @@ -0,0 +1,68 @@ +--- +title: usbkd.isthisdumpasyncissue +description: This command checks a 0xFE crash dump file, to see whether the likely cause of the crash was an Interrupt on Async Advance issue associated with a USB EHCI host controller. +ms.assetid: 1729E52F-F943-4062-94AC-7890C2E25EBF +keywords: ["usbkd.isthisdumpasyncissue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.isthisdumpasyncissue +api_type: +- NA +--- + +# !usbkd.isthisdumpasyncissue + + +The **!usbkd.isthisdumpasyncissue** command checks a crash dump file, generated by [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md), to see whether the likely cause of the crash was an Interrupt on Async Advance issue associated with a USB EHCI host controller. + +``` +!usbkd.isthisdumpasyncissue +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +Examples +-------- + +Here is an example of the output of **!usbkd.isthisdumpasyncissue**. + +``` +1: kd> !analyze -v +*** ... +BUGCODE_USB_DRIVER (fe) +... +1: kd> !usbkd.isthisdumpasyncissue +This is *NOT* Async on Advance Issue because the EndPointData is NULL +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.isthisdumpasyncissue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-urbfunc.md b/windows-driver-docs-pr/debugger/-usbkd-urbfunc.md new file mode 100644 index 0000000000..464c25e018 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-urbfunc.md @@ -0,0 +1,66 @@ +--- +title: usbkd.urbfunc +description: The usbkd.urbfunc command displays the name of a URB function code. +ms.assetid: 111DD6CD-D7DB-4772-B6DD-8EA88587FD1F +keywords: ["usbkd.urbfunc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.urbfunc +api_type: +- NA +--- + +# !usbkd.urbfunc + + +The **!usbkd.urbfunc** command displays the name of a URB function code. + +``` +!usbkd.urbfunc FunctionCode +``` + +## Parameters + + + *FunctionCode* +The hexadecimal value of a URB function code. These codes are defined in usb.h. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is an example of the output of **!urbfunc**. + +``` +0: kd> !usbkd.urbfunc 0xA + +URB_FUNCTION_ISOCH_TRANSFER (0xA) +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.urbfunc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usb2.md b/windows-driver-docs-pr/debugger/-usbkd-usb2.md new file mode 100644 index 0000000000..5d581d7bc6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usb2.md @@ -0,0 +1,84 @@ +--- +title: usbkd.usb2 +description: The usbkd.usb2 command displays a list of USB endpoints that have USB 2.0 scheduling information. +ms.assetid: 48DC685A-3624-4DAD-8077-FB7C4BE4BE93 +keywords: ["usbkd.usb2 Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usb2 +api_type: +- NA +--- + +# !usbkd.usb2 + + +The **!usbkd.usb2** command displays a list of USB endpoints that have USB 2.0 scheduling information. + +``` +!usbkd.usb2 DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a USB host controller. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of a USB host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. Pass the address of the device extension to the **!usb2** command. + +``` +0: kd> !usbkd.usb2 ffffe00001ca11a0 + +Sig: HFDO +Hcd FDO Extension: +---------- +---------- +dt usbport!_HCD_ENDPOINT ffffe0000212d970 !usbep ffffe0000212d970 + Tt 0000000000000000 Device Address: 0x00, ep 0x81 Interrupt In + dt _USB2LIB_ENDPOINT_CONTEXT ffffe000023b60f0 dt _USB2_EP ffffe000023b6100 + Period,offset,Ordinal(32,0,0) smask,cmask(00,00 ........ , ........) maxpkt 1 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usb2%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usb2tree.md b/windows-driver-docs-pr/debugger/-usbkd-usb2tree.md new file mode 100644 index 0000000000..6f1a6f7a84 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usb2tree.md @@ -0,0 +1,76 @@ +--- +title: usbkd.usb2tree +description: The usbkd.usb2tree command displays USB 2.0 tree. +ms.assetid: 6BEFE154-C8F0-466C-AB68-71C6304D0DEA +keywords: ["usbkd.usb2tree Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usb2tree +api_type: +- NA +--- + +# !usbkd.usb2tree + + +The **!usbkd.usb2tree** command displays [USB 2.0 tree](usb-2-0-extensions.md#usb-2-tree). + +``` +!usbkd.usb2tree +``` + +## Examples + + +This screen shot shows and example of the output of the **!usb2tree** command. + +![output of the !usbkd.usb2tree command showing uhci ehci information and an enumerated hub list](images/usb2tree01.png) + +The output shows one EHCI execution unit and two UHCI execution units. The execution units shown in this example happen to be on a single USB host controller device. The output also shows the root hubs and connected devices. + +The output uses [Using Debugger Markup Language (DML)](debugger-markup-language-commands.md) to provide links. The links execute commands that give detailed information related to objects in the tree. For example, you could click one of the [**!devobj**](-devobj.md) links to get information about the functional device object associated with the EHCI execution unit. As an alternative to clicking the link, you could enter the command manually: **!devobj ffffe00001ca7050** + +**Note**  The DML feature is available in WinDbg, but not in Visual Studio or KD. + +  + +## DLL + + +Usb3kd.dll + +Remarks +------- + +The **!usb2tree** command is the parent command for many of the [USB 2.0 debugger extensions commands.](usb-2-0-extensions.md) The information displayed by these commands is based on data structures maintained by these drivers: + +- usbehci.sys (miniport driver for USB 2 host controller) +- usbuhci.sys (miniport driver for USB 2 host controller) +- usbport.sys (port driver for USB 2 host controller) +- usbhub.sys (USB 2 hub driver) + +For more information about these drivers, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p/?LinkId=251983). + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usb2tree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbchain.md b/windows-driver-docs-pr/debugger/-usbkd-usbchain.md new file mode 100644 index 0000000000..3f866d5a14 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbchain.md @@ -0,0 +1,85 @@ +--- +title: usbkd.usbchain +description: The usbkd.usbchain command displays a USB device chain starting at a specified PDO, and going back to the root hub. +ms.assetid: 0D69E29E-3886-436F-B5EE-E4F297D9CE36 +keywords: ["usbkd.usbchain Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbchain +api_type: +- NA +--- + +# !usbkd.usbchain + + +The **!usbkd.usbchain** command displays a USB device chain starting at a specified PDO, and going back to the root hub. + +``` +!usbkd.usbchain PDO +``` + +## Parameters + + + *PDO* +Address of the physical device object (PDO) of a device that is connected to a USB hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the PDO of a USB device. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` + kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + Port 1: !port2_info ffffe000021bf000 + Port 2: !port2_info ffffe000021bfb40 + Port 3: !port2_info ffffe000021c0680 !devstack ffffe00007c882a0 +... +``` + +In the preceding output, the address of the PDO is the argument of the suggested command **!devstack ffffe00007c882a0**. Pass the address of the PDO to **!usbkd.usbchain**. + +``` +0: kd> !usbkd.usbchain ffffe00007c882a0 + +usbchain +***************************************************************************** +HUB PDO ffffe00007c882a0 on port 3 !usbhubext ffffe00007c883f0 ArmedForWake = 0 +VID Xxxx PID Xxxx REV 0100 Xxxx Corporation + HUB #3 FDO ffffe00002320050 , !usbhubext ffffe000023201a0 HWC_ARM=0 + ROOT HUB PDO(ext) @ffffe0000213c1a0 + ROOT HUB FDO @ffffe00001ca1050, !usbhcdext ffffe00001ca11a0 PCI Vendor:Device:... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbchain%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbdevh.md b/windows-driver-docs-pr/debugger/-usbkd-usbdevh.md new file mode 100644 index 0000000000..f9186a0b9d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbdevh.md @@ -0,0 +1,139 @@ +--- +title: usbkd.usbdevh +description: The usbkd.usbdevh command displays information about a USB device handle. +ms.assetid: 463DAA72-F3EB-4C76-BB63-DA2EFA1EE9B1 +keywords: ["usbkd.usbdevh Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbdevh +api_type: +- NA +--- + +# !usbkd.usbdevh + + +The **!usbkd.usbdevh** command displays information about a USB device handle. + +``` +!usbkd.usbdevh StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_USBD\_DEVICE\_HANDLE** structure. To get the device handle list for a USB host controller, use the [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbport!\_USBD\_DEVICE\_HANDLE** structure. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + ... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) to get the device handle list. + +``` +0: kd> !usbkd.usbhcdext ffffe00001ca11a0 + +HC Flavor 1000 FDO ffffe00001ca1050 +Root Hub: FDO ffffe00002320050 !hub2_info ffffe000023201a0 +Operational Registers ffffd000228bf020 +Device Data ffffe00001ca2da0 +dt USBPORT!_FDO_EXTENSION ffffe00001ca15a0 +DM Timer Flags ffffe00001ca16d4 +FDO Flags ffffe00001ca16d0 +HCD Log ffffe00001ca11a0 + +DeviceHandleList: !usblist ffffe00001ca23b8, DL +DeviceHandleDeletedList: !usblist ffffe00001ca23c8, DL [Empty] +... +``` + +Now use the [**!usbkd.usblist**](-usbkd-usblist.md) command to get the addresses of **usbport!\_USBD\_DEVICE\_HANDLE** structures. + +``` +0: kd> !usblist ffffe00001ca23b8, DL +list: ffffe00001ca23b8 DL +---------- +!usbdevh ffffe000020f9590 +SSP [IdleReady] (0) +... +``` + +In the preceding output, `ffffe000020f9590` is the address of a **\_USBD\_DEVICE\_HANDLE** structure. Pass this address to **!usbdevh**. + +``` +0: kd> !usbkd.usbdevh ffffe000020f9590 + +dt USBPORT!_USBD_DEVICE_HANDLE ffffe000020f9590 +SSP [IdleReady] (0) +PCI\VEN_8086&DEV_293C Intel Corporation +Root Hub +DriverName : + +## DEVICE HANDLE HISTORY (latest at boottom) + +## EVENT STATE NEXT + +[01] Ev_CreateRoothub_Success Devh_Created Devh_Valid + +## Referene List: Head(ffffe000020f9668) + +[00] dt USBPORT!_DEVH_REF_OBJ ffffe000021944a0 Object: ffffe000020f9590 Tag: dvh+ PendingFlag(0) +[01] dt USBPORT!_DEVH_REF_OBJ ffffe000020bbcb0 Object: ffffe000020ba7e0 Tag: bsCT PendingFlag(0) +[02] dt USBPORT!_DEVH_REF_OBJ ffffe000032b91a0 Object: ffffe0000269e670 Tag: UrbT PendingFlag(1) + +## TtList: Head(ffffe000020f9658) + + +## PipeHandleList: Head(ffffe000020f9640) + +[00] dt USBPORT!_USBD_PIPE_HANDLE_I ffffe000020f95e0 !usbep ffffe000020f6970 + Device Address: 0x00, Endpoint Address 0x00 Endpoint Type: Control +[01] dt USBPORT!_USBD_PIPE_HANDLE_I ffffe000023bd278 !usbep ffffe0000212d970 + Device Address: 0x00, Endpoint Address 0x81 Endpoint Type: Interrupt In + +Config Information: dt USBPORT!_USBD_CONFIG_HANDLE ffffe000023cd0b0 + +## Interface List: + +[00] dt USBPORT!_USBD_INTERFACE_HANDLE_I ffffe000023bd250 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbdevh%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbdevobj.md b/windows-driver-docs-pr/debugger/-usbkd-usbdevobj.md new file mode 100644 index 0000000000..5149ee15b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbdevobj.md @@ -0,0 +1,55 @@ +--- +title: usbkd.usbdevobj +description: The usbkd.usbdevobj command displays information from a USB device object. +ms.assetid: 81A284DB-4830-4F7E-876A-31E7DC2F2819 +keywords: ["usbkd.usbdevobj Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbdevobj +api_type: +- NA +--- + +# !usbkd.usbdevobj + + +The **!usbkd.usbdevobj** command displays information from a USB device object. + +``` +!usbkd.usbdevobj DeviceObject +``` + +## Parameters + + + *DeviceObject* +Address of a **\_DEVICE\_OBJECT** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbdevobj%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbdpc.md b/windows-driver-docs-pr/debugger/-usbkd-usbdpc.md new file mode 100644 index 0000000000..a34f1e3b8b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbdpc.md @@ -0,0 +1,106 @@ +--- +title: usbkd.usbdpc +description: The usbkd.usbdpc command displays information stored in an _XDPC_CONTEXT structure. +ms.assetid: 51ED1BB0-416B-4B2B-9F4D-61F841224126 +keywords: ["usbkd.usbdpc Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbdpc +api_type: +- NA +--- + +# !usbkd.usbdpc + + +The **!usbkd.usbdpc** command displays information stored in an **\_XDPC\_CONTEXT** structure. + +``` +!usbkd.usbdpc StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_XDPC\_CONTEXT** structure. To get the XDPC list for a USB host controller, use the [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbport!\_XDPC\_CONTEXT** structure. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +UHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001e77010 +... +4)!uhci_info ffffe00001c7d1a0 !devobj ffffe00001c7d050 PCI: VendorId... +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!uhci\_info ffffe00001c7d1a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) to get the XDPC list. + +``` +0: kd> !usbkd.usbhcdext ffffe00001c7d1a0 +... +## XDPC List + +01) dt USBPORT!_XDPC_CONTEXT ffffe00001c7df18 +02) dt USBPORT!_XDPC_CONTEXT ffffe00001c7db88 +03) dt USBPORT!_XDPC_CONTEXT ffffe00001c7dd50 +04) dt USBPORT!_XDPC_CONTEXT ffffe00001c7e0e0 +... +``` + +In the preceding output, `ffffe00001c7df18` is the address of an **\_XDPC\_CONTEXT** structure. Pass this address to **!usbdpc**. + +``` +0: kd> !usbkd.usbdpc ffffe00001c7df18 + +dt USBPORT!_XDPC_CONTEXT ffffe00001c7df18 + +## XDPC HISTORY (latest at boottom) + +## EVENT STATE NEXT + +[01] Ev_Xdpc_End XDPC_Running XDPC_Enabled +[02] Ev_Xdpc_Signal XDPC_Enabled XDPC_DpcQueued +[03] Ev_Xdpc_Signal XDPC_DpcQueued XDPC_DpcQueued +[04] Ev_Xdpc_Worker XDPC_DpcQueued XDPC_Running +[05] Ev_Xdpc_Signal XDPC_Running XDPC_Signaled +[06] Ev_Xdpc_End XDPC_Signaled XDPC_DpcQueued +[07] Ev_Xdpc_Worker XDPC_DpcQueued XDPC_Running +[08] Ev_Xdpc_End XDPC_Running XDPC_Enabled +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbdpc%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbdstatus.md b/windows-driver-docs-pr/debugger/-usbkd-usbdstatus.md new file mode 100644 index 0000000000..cdfac31a19 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbdstatus.md @@ -0,0 +1,66 @@ +--- +title: usbkd.usbdstatus +description: The usbkd.usbdstatus command displays the name of a USBD status code. +ms.assetid: 9983433E-1D17-47C6-972B-0A02B228A6AE +keywords: ["usbkd.usbdstatus Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbdstatus +api_type: +- NA +--- + +# !usbkd.usbdstatus + + +The **!usbkd.usbdstatus** command displays the name of a USBD status code. + +``` +!usbkd.usbdstatus StatusCode +``` + +## Parameters + + + *StatusCode* +The hexadecimal value of a USBD status code. These codes are defined in usb.h. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is an example of the output of **!usbdstatus**. + +``` +1: kd> !usbkd.usbdstatus 0xC0000008 + +USBD_STATUS_DATA_OVERRUN (0xC0000008) +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbdstatus%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbep.md b/windows-driver-docs-pr/debugger/-usbkd-usbep.md new file mode 100644 index 0000000000..09fe4bec7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbep.md @@ -0,0 +1,119 @@ +--- +title: usbkd.usbep +description: The usbkd.usbep command displays information about a USB endpoint. +ms.assetid: FEF66394-0502-4F3F-ACBE-57AA1945CC74 +keywords: ["usbkd.usbep Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbep +api_type: +- NA +--- + +# !usbkd.usbep + + +The **!usbkd.usbep** command displays information about a USB endpoint. + +``` +!usbkd.usbep StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_HCD\_ENDPOINT** structure. To get the endpoint list for a USB host controller, use the [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbport!\_HCD\_ENDPOINT** structure. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + ... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) to get the global endpoint list. + +``` +0: kd> !usbkd.usbhcdext ffffe00001ca11a0 +... +DeviceHandleList: !usblist ffffe00001ca23b8, DL +DeviceHandleDeletedList: !usblist ffffe00001ca23c8, DL [Empty] +GlobalEndpointList: !usblist ffffe00001ca2388, EP +... +``` + +Now use the [**!usbkd.usblist**](-usbkd-usblist.md) command to get the addresses of **\_HCD\_ENDPOINT** structures. + +``` +0: kd> !usblist ffffe00001ca2388, EP + +list: ffffe00001ca2388 EP +---------- +dt usbport!_HCD_ENDPOINT ffffe000020f6970 !usbep ffffe000020f6970 +Device Address: 0x00, ep 0x00 Control Flags: 00000002 dt _USB_ENDPOINT_FLAGS ffffe000020f6990 +dt usbport!_ENDPOINT_PARAMETERS ffffe000020f6b18 RootHub Endpoint +... +``` + +In the preceding output, `ffffe000020f6970 `is the address of an **\_HCD\_ENDPOINT**structure. Pass this address to **!usbkd.usbep**. + +``` +0: kd> !usbep ffffe000020f6970 +Device Address: 0x00, Endpoint Address 0x00 Endpoint Type: Control +dt USBPORT!_HCD_ENDPOINT ffffe000020f6970 +dt USBPORT!_ENDPOINT_PARAMETERS ffffe000020f6b18 +RootHub Endpoint + +## Transfer(s) List: (HwPendingListHead) + + [EMPTY] + +## Endpoint Reference List: (EpRefListHead) + +[00] dt USBPORT!_USBOBJ_REF ffffe000021a64a0 Object ffffe000020f6970 Tag:EPop Endpoint:ffffe000020f6970 +[01] dt USBPORT!_USBOBJ_REF ffffe000021264a0 Object ffffe000020f95e0 Tag:EPpi Endpoint:ffffe000020f6970 + +## GEP HISTORY (latest at bottom) + +## EVENT STATE NEXT HwEpState + +[01] Ev_gEp_Open GEp_Init GEp_Paused ENDPOINT_PAUSE +[02] Ev_gEp_ReqActive GEp_Paused GEp_Active ENDPOINT_ACTIVE +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbep%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbfaildata.md b/windows-driver-docs-pr/debugger/-usbkd-usbfaildata.md new file mode 100644 index 0000000000..9926e070cf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbfaildata.md @@ -0,0 +1,75 @@ +--- +title: usbkd.usbfaildata +description: The usbkd.usbfaildata command displays the failure data (if any) stored for a USB device. +ms.assetid: 08FD3F82-73E3-4616-92EB-D562ECAB8A96 +keywords: ["usbkd.usbfaildata Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbfaildata +api_type: +- NA +--- + +# !usbkd.usbfaildata + + +The **!usbkd.usbfaildata** command displays the failure data (if any) stored for a USB device. + +``` +!usbkd.usbfaildata PDO +``` + +## Parameters + + + *PDO* +Address of the physical device object (PDO) of a device that is connected to a USB hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the PDO of a USB device. Enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` + kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + Port 1: !port2_info ffffe000021bf000 + Port 2: !port2_info ffffe000021bfb40 + Port 3: !port2_info ffffe000021c0680 !devstack ffffe00007c882a0 +... +``` + +In the preceding output, the address of the PDO appears as the argument of the suggested command **!devstack ffffe00007c882a0**. + +Now pass the address of the PDO to **!usbkd.usbfaildata**. + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbfaildata%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdext.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdext.md new file mode 100644 index 0000000000..42cfbb48ef --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdext.md @@ -0,0 +1,157 @@ +--- +title: usbkd.usbhcdext +description: The usbkd.usbhcdext command displays information from the device extension of a USB host controller or a USB root hub. +ms.assetid: 83811F9F-5899-4EC8-83D7-39EE884C0A01 +keywords: ["usbkd.usbhcdext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdext +api_type: +- NA +--- + +# !usbkd.usbhcdext + + +The [**!usbkd.usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) command displays information from the device extension of a USB host controller or a USB root hub. + +``` +!usbkd.usbhcdext DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of one of the following: + +- The device extension for the functional device object (FDO) of a USB host controller. +- The device extension for the physical device object (PDO) a USB root hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of an EHCI host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 + +1)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + ... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Now pass the address of the device extension to the [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) command. + +``` +0: kd> !usbkd.usbhcdext ffffe00001ca11a0 + +HC Flavor 1000 FDO ffffe00001ca1050 +Root Hub: FDO ffffe00002320050 !hub2_info ffffe000023201a0 +Operational Registers ffffd000228bf020 +Device Data ffffe00001ca2da0 +dt USBPORT!_FDO_EXTENSION ffffe00001ca15a0 +DM Timer Flags ffffe00001ca16d4 +FDO Flags ffffe00001ca16d0 +HCD Log ffffe00001ca11a0 + +DeviceHandleList: !usblist ffffe00001ca23b8, DL +DeviceHandleDeletedList: !usblist ffffe00001ca23c8, DL [Empty] +GlobalEndpointList: !usblist ffffe00001ca2388, EP +EpNeoStateChangeList: !usblist ffffe00001ca2370, SC [Empty] +GlobalTtListHead: !usblist ffffe00001ca23a8, TT [Empty] +BusContextHead: !usblist ffffe00001ca16b0, BC + +## Pending Requests + +[001] dt USBPORT!_USB_IOREQUEST_CONTEXT ffffe00001ca1450 Tag: AddD Obj: ffffe00001ca11a0 +... + +## XDPC List + +01) dt USBPORT!_XDPC_CONTEXT ffffe00001ca1f18 +... +``` + +Here is one way to find the address of the device extension for the PDO of a root hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 + +1)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + ... +``` + +In the preceding output, you can see the address of the FDO of the root hub displayed as the argument to the command **!devstack ffffe00002320050**. Use the [**!devstack**](-devstack.md) command to find the address of the PDO and the PDO device extension. + +``` +0: kd> !kdexts.devstack ffffe00002320050 + !DevObj !DrvObj !DevExt ObjectName +> ffffe00002320050 \Driver\usbhub ffffe000023201a0 0000002d + ffffe0000213c050 \Driver\usbehci ffffe0000213c1a0 USBPDO-3 +... +``` + +In the preceding output, you can see that the address of the device extension for the PDO of the root hub is `ffffe0000213c1a0`. + +Now pass the address of the device extension to the [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) command. + +``` +0: kd> !usbkd.usbhcdext ffffe0000213c1a0 + +Root Hub PDO Extension +Parent HC: FDO ffffe00001ca1050 !ehci_info ffffe00001ca11a0 +HUB FDO ffffe00002320050 !hub2_info ffffe000023201a0 +dt USBPORT!_PDO_EXTENSION ffffe0000213c5a0 + +## Pending Requests + +[001] dt USBPORT!_USB_IOREQUEST_CONTEXT ffffe0000213c450 Tag: RHcr Obj: ffffe0000213c1a0 +[002] dt USBPORT!_USB_IOREQUEST_CONTEXT ffffe00003ce5800 Tag: iIRP Obj: ffffe00002182210 + +## POWER FUNC HISTORY (latest at bottom) + +[00] IRP_MN_WAIT_WAKE (PowerSystemHibernate) +... + +## PnP STATE LOG (latest at bottom) + +## EVENT STATE NEXT + +[01] EvPDO_IRP_MN_START_DEVICE PnpNotStarted PnpStarted +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdhccontext.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdhccontext.md new file mode 100644 index 0000000000..32c6d92caf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdhccontext.md @@ -0,0 +1,55 @@ +--- +title: usbkd.usbhcdhccontext +description: The usbkd.usbhcdhccontext command displays the USB2LIB_HC_CONTEXT for a USB host controller. +ms.assetid: 72A4BAA1-D395-4D6A-BEFB-F217E994B4E7 +keywords: ["usbkd.usbhcdhccontext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdhccontext +api_type: +- NA +--- + +# !usbkd.usbhcdhccontext + + +The **!usbkd.usbhcdhccontext** command displays the **USB2LIB\_HC\_CONTEXT** for a USB host controller. + +``` +!usbkd.usbhcdhccontext DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a USB host controller. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdhccontext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdlist.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlist.md new file mode 100644 index 0000000000..60d2ce9cec --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlist.md @@ -0,0 +1,80 @@ +--- +title: usbkd.usbhcdlist +description: The usbkd.usbhcdlist command displays information about all USB host controllers that are represented by the USB port driver (Usbport.sys). +ms.assetid: 877A6361-0DB9-4089-AF85-BABFBED8C440 +keywords: ["usbkd.usbhcdlist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdlist +api_type: +- NA +--- + +# !usbkd.usbhcdlist + + +The [**!usbkd.usbhcdlist**](https://msdn.microsoft.com/library/windows/hardware/dn367074) command displays information about all USB host controllers that are represented by the USB port driver (Usbport.sys). For information about the USB port driver and the associated miniport drivers, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkId=251983). + +``` +!usbkd.usbhcdlist +``` + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is an example of a portion of the output of [**!usbhcdlist**](https://msdn.microsoft.com/library/windows/hardware/dn367074). + +``` +0: kd> !usbkd.usbhcdlist +MINIPORT List @ fffff80001e5bbd0 + +## List of UHCI controllers + +!drvobj ffffe00002000060 dt USBPORT!_USBPORT_MINIPORT_DRIVER ffffe00001f48010 Registration Packet ffffe00001f48048 + +01 +... + +## List of EHCI controllers + +!drvobj ffffe00001fd33a0 dt USBPORT!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 Registration Packet ffffe00001f48c08 + +01. Xxxxx Corporation PCI: VendorID Xxxx DeviceID Xxxx RevisionId 0002 + !devobj ffffe00001ca1050 + !ehci_info ffffe00001ca11a0 + Operational Registers ffffd000228bf020 + Device Data ffffe00001ca2da0 + !usbhcdlog ffffe00001ca11a0 + nt!_KINTERRUPT ffffe000020abe78 + Device Capabilities ffffe00001ca135c + Pending IRP's: 0, Transfers: 0 (Periodic(0), Async(0)) +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdlist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdlistlogs.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlistlogs.md new file mode 100644 index 0000000000..8889775efa --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlistlogs.md @@ -0,0 +1,87 @@ +--- +title: usbkd.usbhcdlistlogs +description: The usbkd.usbhcdlistlogs command displays a list of all functional device objects (FDOs) associated with the USB port driver (Usbport.sys) and debug logs. +ms.assetid: C86646D3-7B39-4C8C-9FDA-FD07AA7A880A +keywords: ["usbkd.usbhcdlistlogs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdlistlogs +api_type: +- NA +--- + +# !usbkd.usbhcdlistlogs + + +The **!usbkd.usbhcdlistlogs** command displays a list of all functional device objects (FDOs) associated with the USB port driver (Usbport.sys). The command also displays the complete debug logs for all EHCI Host Controllers. + +``` +!usbkd.usbhcdlistlogs +``` + +## DLL + + +Usbkd.dll + +Examples +-------- + +This example shows a portion of the output of the **!usbhcdlistlogs** command. + +``` +0: kd> !usbkd.usbhcdlistlogs + +MINIPORT List @ fffff80001e5bbd0 +*flink, blink ffffe00001f48018,ffffe00001f48bd8 + +[0] entry @: ffffe00001f48010 dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48010 +UHCI MINIPORT @ ffffe00001f48010 !drvobj ffffe00002000060 regpkt ffffe00001f48048 +02. !devobj ffffe00001ca4050 !usbhcdext ffffe00001ca41a0 HFDO 8086 2938 RHPDO ffffe0000213a050 +03. !devobj ffffe00001ca7050 !usbhcdext ffffe00001ca71a0 HFDO 8086 2937 RHPDO ffffe00002140050 + +[1] entry @: ffffe00001f48bd0 dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 +EHCI MINIPORT @ ffffe00001f48bd0 !drvobj ffffe00001fd33a0 regpkt ffffe00001f48c08 +01. !devobj ffffe00001ca1050 !usbhcdext ffffe00001ca11a0 HFDO 8086 293c RHPDO ffffe0000213c050 + +LOG@: ffffe00001ca11b8 +>LOG mask = 3ff idx = fff69e8d (28d) +*LOG: ffffe000020191a0 LOGSTART: ffffe00002014000 *LOGEND: ffffe0000201bfe0 # -1 +[ 000] ffffe000020191a0 Tmt0 0000000000000000 0000000000000000 0000000000000000 +[ 001] ffffe000020191c0 _Pop 0000000000000003 0000000000003000 0000000000000000 +... +[ 005] ffffe00002019240 chgZ 0000000000000000 0000000000b7228f 0000000000000000 +[ 006] ffffe00002019260 nes- 0000000000000000 0000000000000000 0000000000000000 +[ 007] ffffe00002019280 nes+ ffffe00001ca2370 ffffe00001ca2370 00000000000ced39 +... +[1014] ffffe00002019060 tmo4 0000000000000000 0000000000000040 ffffe00001ca1c20 +... +[1022] ffffe00002019160 xdw2 ffffe00001ca1b88 ffffe00001ca1050 0000000000000002 +[1023] ffffe00002019180 xdB0 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +``` + +The command output shows two FDOs that represent UHCI host controlers and one FDO that represents an EHCI host controller. Then the output shows the debug log for the one EHCI host controller. + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdlistlogs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdlog.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlog.md new file mode 100644 index 0000000000..2fc3ad844b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlog.md @@ -0,0 +1,89 @@ +--- +title: usbkd.usbhcdlog +description: The usbkd.usbhcdlog command displays a portion of the debug log for a USB host controller. +ms.assetid: 78FDC557-7791-422A-AB7B-5C9B6A1DF481 +keywords: ["usbkd.usbhcdlog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdlog +api_type: +- NA +--- + +# !usbkd.usbhcdlog + + +The [**!usbkd.usbhcdlog**](https://msdn.microsoft.com/library/windows/hardware/dn367076) command displays a portion of the debug log for a USB host controller. + +``` +!usbkd.usbhcdlog DeviceExtension[, NumberOfEntries] +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a UHCI or EHCI USB host controller. + + *NumberOfEntries* +The number of log entries to display. To display the entire log, set this parameter to -1. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of a USB host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0 kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 +... + +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Now pass the address of the device extension to the **!usbhcdlog** command. In this example, the second argument limits the display to four log entries. + +``` +0: kd> !usbkd.usbhcdlog ffffe00001ca11a0, 4 + +LOG@: ffffe00001ca11b8 +>LOG mask = 3ff idx = fff68e95 (295) +*LOG: ffffe000020192a0 LOGSTART: ffffe00002014000 *LOGEND: ffffe0000201bfe0 # 4 +[ 000] ffffe000020192a0 xSt0 ffffe00001ca1b88 0000000000000006 0000000000000001 +[ 001] ffffe000020192c0 xnd8 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +[ 002] ffffe000020192e0 xnd0 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +[ 003] ffffe00002019300 gNX0 0000000000000000 0000000000000000 ffffe00001ca1b88 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdlog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdlogex.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlogex.md new file mode 100644 index 0000000000..7eceec3f11 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdlogex.md @@ -0,0 +1,119 @@ +--- +title: usbkd.usbhcdlogex +description: The usbkd.usbhcdlogex command displays an annotated debug log for a USB host controller. +ms.assetid: 47274AEE-0BDB-4C25-9158-6213366434E0 +keywords: ["usbkd.usbhcdlogex Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdlogex +api_type: +- NA +--- + +# !usbkd.usbhcdlogex + + +The **!usbkd.usbhcdlogex** command displays an annotated debug log for a USB host controller. + +``` +!usbkd.usbhcdlogex DeviceExtension[, NumberOfEntries] +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a UHCI or EHCI USB host controller. + + *NumberOfEntries* +The number of log entries to display. To display the entire log, set this parameter to -1. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of a USB host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0 kd> !usbkd.usb2tree + +EHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe00001f48bd0 +... + +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Now pass the address of the device extension to the **!usbhcdlogex** command. In this example, the second argument limits the display to 20 log entries. + +``` +0: kd> !usbkd.usbhcdlogex ffffe00001ca11a0, 20 +LOG@: ffffe00001ca11b8 +>LOG mask = 3ff idx = fff68e95 (295) +*LOG: ffffe000020192a0 LOGSTART: ffffe00002014000 *LOGEND: ffffe0000201bfe0 # 20 +[ 000] ffffe000020192a0 xSt0 ffffe00001ca1b88 0000000000000006 0000000000000001 +[ 001] ffffe000020192c0 xnd8 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +[ 002] ffffe000020192e0 xnd0 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +// +// USBPORT_Xdpc_End() - USBPORT_Core_UsbHcIntDpc_Worker() DPC/XDPC: 2 of 4 + +[ 003] ffffe00002019300 gNX0 0000000000000000 0000000000000000 ffffe00001ca1b88 +[ 004] ffffe00002019320 xbg1 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +[ 005] ffffe00002019340 xbg0 ffffe00001ca1b88 ffffe00001ca1050 ffffe00001ca22e8 +// +// USBPORT_Xdpc_iBegin() - USBPORT_Core_UsbHcIntDpc_Worker() DPC/XDPC: 2 of 4 + +[ 006] ffffe00002019360 tmo4 0000000000000000 0000000000000040 ffffe00001ca1c20 +[ 007] ffffe00002019380 tmo3 0000000000000000 0000000000989680 ffffe00001ca1c20 +[ 008] ffffe000020193a0 tmo2 0000000000000000 00000000000003e8 ffffe00001ca1c20 +[ 009] ffffe000020193c0 tmo1 0000000000000000 000000000002625a ffffe00001ca1c20 +[ 010] ffffe000020193e0 tmo0 00000000000003e8 ffffe00001ca1b88 ffffe00001ca1c20 +[ 011] ffffe00002019400 hci0 0000000000000000 0000000000000000 0000000000000000 +[ 012] ffffe00002019420 xSt0 ffffe00001ca1b88 0000000000000008 0000000000000003 +[ 013] ffffe00002019440 xdw4 ffffe00001ca1b88 0000000000000000 0000000000000000 +[ 014] ffffe00002019460 xdw2 ffffe00001ca1b88 ffffe00001ca1050 0000000000000002 +[ 015] ffffe00002019480 xdB0 ffffe00001ca1b88 ffffe00001ca1050 0000000000000000 +// +// USBPORT_Xdpc_Worker_HcIntDpc() DPC/XDPC: 2 of 4 + +[ 016] ffffe000020194a0 iDP- 0000000000000000 0000000000b73e26 0000000000000000 +// +// USBPORT_IsrDpc() - Exit() + +[ 017] ffffe000020194c0 xSt0 ffffe00001ca1b88 0000000000000007 0000000000000002 +[ 018] ffffe000020194e0 Xsi1 ffffe00001ca1b88 0000000000000000 0000000000000000 +// +// USBPORT_Xdpc_iSignal()- USBPORT_Core_UsbHcIntDpc_Worker() DPC/XDPC: 2 of 4 + +[ 019] ffffe00002019500 chgZ 0000000000000000 0000000000b73e26 0000000000000000 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdlogex%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdpnp.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdpnp.md new file mode 100644 index 0000000000..9853c0dd14 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdpnp.md @@ -0,0 +1,117 @@ +--- +title: usbkd.usbhcdpnp +description: The usbkd.usbhcdpnp command displays the Plug and Play (PnP) state history for a USB host controller or root hub. +ms.assetid: 1153F3C2-5878-4223-AA18-5AE6FA056851 +keywords: ["usbkd.usbhcdpnp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdpnp +api_type: +- NA +--- + +# !usbkd.usbhcdpnp + + +The **!usbkd.usbhcdpnp** command displays the Plug and Play (PnP) state history for a USB host controller or root hub. + +``` +!usbkd.usbhcdpnp DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of one of the following: + +- The device extension for the functional device object (FDO) of a USB host controller. +- The device extension for the physical device object (PDO) a USB root hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of USB host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree + +UHCI MINIPORT(s) dt usbport!_USBPORT_MINIPORT_DRIVER ffffe0000090c3d0 +... +4)!uhci_info ffffe00001c8f1a0 !devobj ffffe00001c8f050 PCI: VendorId 8086 DeviceId 2938 RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!uhci\_info ffffe00001c8f1a0**. + +Now pass the address of the device extension to the **!usbhcdpnp** command. + +``` +0: kd> !usbkd.usbhcdpnp ffffe00001c8f1a0 + +## PNP STATE LOG (latest at bottom) + +## EVENT STATE NEXT + +[01] EvFDO_IRP_MN_START_DEVICE PnpNotStarted PnpStarted +[02] EvFDO_IRP_MN_QBR_RH PnpStarted PnpStarted +``` + +Here is one way to find the address of the device extension for the PDO of a root hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +4)!uhci_info ffffe00001c8f1a0 !devobj ffffe00001c8f050 PCI: VendorId 8086 DeviceId 2938 RevisionId 0002 + RootHub !hub2_info ffffe00000d941a0 !devstack ffffe00000d94050 +``` + +In the preceding output, you can see the address of the FDO of the root hub displayed as the argument to the command **!devstack ffffe00000d94050**. Use the [**!devstack**](-devstack.md) command to find the address of the PDO and the PDO device extension. + +``` +0: kd> !kdexts.devstack ffffe00000d94050 + !DevObj !DrvObj !DevExt ObjectName +> ffffe00000d94050 \Driver\usbhub ffffe00000d941a0 0000006b + ffffe00000ed4050 \Driver\usbuhci ffffe00000ed41a0 USBPDO-2 +``` + +In the preceding output, you can see that the address of the device extension for the PDO of the root hub is `ffffe00000ed41a0`. + +Now pass the address of the device extension to the **!usbhcdpnp** command. + +``` +0: kd> !usbkd.usbhcdpnp ffffe00000ed41a0 + +## PNP STATE LOG (latest at bottom) + +## EVENT STATE NEXT + +[01] EvPDO_IRP_MN_START_DEVICE PnpNotStarted PnpStarted +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdpnp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhcdpow.md b/windows-driver-docs-pr/debugger/-usbkd-usbhcdpow.md new file mode 100644 index 0000000000..02d6e1b8b4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhcdpow.md @@ -0,0 +1,131 @@ +--- +title: usbkd.usbhcdpow +description: The usbkd.usbhcdpow command displays the power state history for a USB host controller or root hub. +ms.assetid: 49D803E3-0D65-48D4-98C5-BFE4DB2C2985 +keywords: ["usbkd.usbhcdpow Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhcdpow +api_type: +- NA +--- + +# !usbkd.usbhcdpow + + +The **!usbkd.usbhcdpow** command displays the power state history for a USB host controller or root hub. + +``` +!usbkd.usbhcdpow DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of one of the following: + +- The device extension for the functional device object (FDO) of a USB host controller. +- The device extension for the physical device object (PDO) a USB root hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of an EHCI host controller. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... + +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + ... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Now pass the address of the device extension to the **!usbhcdpow** command. + +``` +0: kd> !usbkd.usbhcdpow ffffe00001ca11a0 + +dt USBPORT!_FDO_EXTENSION ffffe00001ca15a0 + +## State History (latest at bottom) + +## EVENT STATE NEXT + +[00] FdoPwrEv_D0_DoSetD0_2 FdoPwr_D0_WaitWorker2 FdoPwr_D0_WaitSyncUsb2 dt:0 ms +[01] FdoPwrEv_SyncUsb2_DoChirp FdoPwr_D0_WaitSyncUsb2 FdoPwr_D0_WaitSyncUsb2 dt:0 ms +[02] FdoPwrEv_Rh_SetPowerSys FdoPwr_D0_WaitSyncUsb2 FdoPwr_D0_WaitSyncUsb2 dt:0 ms +[03] FdoPwrEv_Rh_SetD0 FdoPwr_D0_WaitSyncUsb2 FdoPwr_D0_WaitSyncUsb2 dt:0 ms +[04] FdoPwrEv_SyncUsb2_Complete FdoPwr_D0_WaitSyncUsb2 FdoPwr_WaitSx dt:50 ms +[05] FdoPwrEv_Rh_Wake FdoPwr_WaitSx FdoPwr_WaitSx dt:3412 ms +[06] FdoPwrEv_Rh_Wake FdoPwr_WaitSx FdoPwr_WaitSx dt:283872 ms +[07] FdoPwrEv_Rh_Wake FdoPwr_WaitSx FdoPwr_WaitSx dt:25481267 ms +``` + +Here is one way to find the address of the device extension for the PDO of a root hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... + +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + ... +``` + +In the preceding output, you can see the address of the FDO of the root hub displayed as the argument to the command **!devstack ffffe00002320050**. Use the [**!devstack**](-devstack.md) command to find the address of the PDO and the PDO device extension. + +``` +0: kd> !kdexts.devstack ffffe00002320050 + !DevObj !DrvObj !DevExt ObjectName +> ffffe00002320050 \Driver\usbhub ffffe000023201a0 0000002d + ffffe0000213c050 \Driver\usbehci ffffe0000213c1a0 USBPDO-3 +... +``` + +In the preceding output, you can see that the address of the device extension for the PDO of the root hub is `ffffe0000213c1a0`. + +Now pass the address of the device extension to the **!usbhcdpow** command. + +``` +0: kd> !usbkd.usbhcdpow ffffe0000213c1a0 + +dt USBPORT!_FDO_EXTENSION ffffe0000213c5a0 + +## State History (latest at bottom) + +## EVENT STATE NEXT + +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhcdpow%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhelp.md b/windows-driver-docs-pr/debugger/-usbkd-usbhelp.md new file mode 100644 index 0000000000..9c55b335ea --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhelp.md @@ -0,0 +1,45 @@ +--- +title: usbkd.usbhelp +description: The usbkd.usbhelp command displays help for the USB 2.0 debugger extension commands. +ms.assetid: 3551CAC5-EFC4-4CD8-B4C9-07CB5818B507 +keywords: ["usbkd.usbhelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhelp +api_type: +- NA +--- + +# !usbkd.usbhelp + + +The **!usbkd.usbhelp** command displays help for the USB 2.0 debugger extension commands. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhuberr.md b/windows-driver-docs-pr/debugger/-usbkd-usbhuberr.md new file mode 100644 index 0000000000..678a8ae501 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhuberr.md @@ -0,0 +1,102 @@ +--- +title: usbkd.usbhuberr +description: The usbkd.usbhuberr command displays a USB hub error record. +ms.assetid: 5BB87FA2-0531-400C-95B3-325EE4DDB649 +keywords: ["usbkd.usbhuberr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhuberr +api_type: +- NA +--- + +# !usbkd.usbhuberr + + +The **!usbkd.usbhuberr** command displays a USB hub error record. + +``` +!usbkd.usbhuberr StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbhub!\_HUB\_EXCEPTION\_RECORD** structure. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbhub!\_HUB\_EXCEPTION\_RECORD**. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + ... +``` + +In the preceding output, you can see the suggested command **!devstack ffffe00002320050**. Enter this command. + +``` +0: kd> !kdexts.devstack ffffe000011f7050 + + !DevObj !DrvObj !DevExt ObjectName +> ffffe000011f7050 \Driver\usbhub ffffe000011f71a0 0000006f + ffffe00000a21050 \Driver\usbehci ffffe00000a211a0 USBPDO-8 +... +``` + +In the preceding output, `ffffe000011f71a0` is the address of the device extension for the functional device object (FDO) of the hub. Pass the address of the device extension to [**!usbkd.usbhubext**](-usbkd-usbhubext.md). + +``` +0: kd> !usbkd.usbhubext ffffe000011f71a0 + +FDO ffffe000011f7050 PDO ffffe00000a21050 HubNumber# 7 +dt USBHUB!_DEVICE_EXTENSION_HUB ffffe000011f71a0 +!usbhublog ffffe000011f71a0 +RemoveLock ffffe000011f7668 +FdoFlags ffffe000011f7ba0 + +CurrentPowerIrp: System (0000000000000000) Device (0000000000000000) + +ObjReferenceList: !usblist ffffe000011f7b70, RL +ExceptionList: !usblist ffffe000011f8498, EL [Empty] +... +``` + +In the preceding output, `ffffe000011f8498` is the address of the exception list. If the exception list is not empty, it will contain addresses of **\_HUB\_EXCEPTION\_RECORD** structures. + +``` +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhuberr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubext.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubext.md new file mode 100644 index 0000000000..b8b9da3214 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubext.md @@ -0,0 +1,240 @@ +--- +title: usbkd.usbhubext +description: The usbkd.usbhubext command displays information about a USB hub.. +ms.assetid: 1EC75753-3743-4384-8068-E796083D8239 +keywords: ["usbkd.usbhubext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubext +api_type: +- NA +--- + +# !usbkd.usbhubext + + +The **!usbkd.usbhubext** command displays information about a USB hub.. + +``` +!usbkd.usbhubext DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of one of the following: + +- The device extension for the functional device object (FDO) of a USB hub. +- The device extension for the physical device object (PDO) of a device that is connected to a USB hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of USB hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 +``` + +In the preceding output, you can see the suggested command **!devstack ffffe00002320050**. Enter this command. + +``` +0: kd> !kdexts.devstack ffffe00002320050 + + !DevObj !DrvObj !DevExt ObjectName +> ffffe00002320050 \Driver\usbhub ffffe000023201a0 0000002d + ffffe0000213c050 \Driver\usbehci ffffe0000213c1a0 USBPDO-3 +... +``` + +In the preceding output, you can see that the address of the device extension for the FDO of the hub is `ffffe000023201a0`. + +Now pass the address of the device extension to the **!usbkd.usbhubext** command. + +``` +0: kd> !usbkd.usbhubext ffffe000023201a0 + +FDO ffffe00002320050 PDO ffffe0000213c050 HubNumber# 3 +dt USBHUB!_DEVICE_EXTENSION_HUB ffffe000023201a0 +!usbhublog ffffe000023201a0 +RemoveLock ffffe00002320668 +FdoFlags ffffe00002320ba0 + +CurrentPowerIrp: System (0000000000000000) Device (0000000000000000) + +ObjReferenceList: !usblist ffffe00002320b70, RL +ExceptionList: !usblist ffffe00002321498, EL [Empty] +DmTimerListHead: !usblist ffffe00002321040, TL [Empty] +PdoRemovedListHead: !usblist ffffe00002321478, PL [Empty] +PdoPresentListHead: !usblist ffffe00002321468, PL +WorkItemListHead: !usblist ffffe00002320c80, WI [Empty] +SshBusyListHead: !usblist ffffe00002320dc0, BL + + +## PnP FUNC HISTORY (latest at bottom) + +01. IRP_MN_QUERY_DEVICE_RELATIONS +... +## POWER FUNC HISTORY (latest at bottom) + +01. IRP_MN_QUERY_POWER - PowerSystemHibernate +... + +## HARD RESET STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. HRE_Pause HReset_WaitReady HReset_Paused +... + +## PNP STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. Ev_SYSTEM_POWER FDO_WaitPnpStop FDO_WaitPnpStop +... + +## POWER STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. Ev_SET_POWER_S0 FdoSx_Dx FdoWaitS0IoComplete_Dx +... + +## BUS STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. BE_BusSuspend BS_BusPause BS_BusSuspend +... + +SSH_EnabledStatus: [SSH_ENABLED_VIA_POWER_POLICY] + +## SSH STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. SSH_Event_ResumeHubComplete SSH_State_HubPendingResume SSH_State_HubActive +... + +## PORT DATA + +PortData 1: !port2_info ffffe000021bf000 Port State = PS_WAIT_CONNECT PortChangeLock: 0, Pcq_State: Pcq_Run_Idle + PDO 0000000000000000 +... +``` + +Here is one way to find the address of the device extension for the PDO of a device that is connected to a USB hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + Port 1: !port2_info ffffe000021bf000 + Port 2: !port2_info ffffe000021bfb40 + Port 3: !port2_info ffffe000021c0680 !devstack ffffe00007c882a0 +``` + +In the preceding output, you can see suggested command **!devstack ffffe00007c882a0**. Enter this command. + +``` +0: kd> !kdexts.devstack ffffe00007c882a0 + + !DevObj !DrvObj !DevExt ObjectName + ffffe00006ce2260 \Driver\USBSTOR ffffe00006ce23b0 00000070 +> ffffe00007c882a0 \Driver\usbhub ffffe00007c883f0 USBPDO-4 +... +``` + +In the preceding output, you can see that the address of the device extension for the PDO of the device is `ffffe00007c883f0`. + +Now pass the address of the device extension to the [**!usbhcdpnp**](-usbkd-usbhcdpnp.md) command. + +``` +0: kd> !usbkd.usbhubext ffffe00007c883f0 + +dt USBHUB!_DEVICE_EXTENSION_PDO ffffe00007c883f0 +PARENT HUB: FDO ffffe00002320050 !hub2_info ffffe000023201a0 +!usbhubinfo ffffe00002320050 +PORT NUMBER : 3 +IoList: !usblist ffffe00007c888b0, IO +LatchList: !usblist ffffe00007c888e0, LA + +## PnP ID's + +DeviceId:USB\VID_0781&PID_5530 +HardwareId:USB\VID_0781&PID_5530&REV_0100USB\VID_0781&PID_5530 +CompatibleId:USB\Class_08&SubClass_06&Prot_50USB\Class_08&SubClass_06USB\Class_08 +SerialNumberId:20052444100A47F319CB +UniqueId:3 +ProductId:Cruzer + +## Pnp Func History (latest at bottom) + +01. IRP_MN_QUERY_BUS_INFORMATION +... + +## Power Func History (latest at bottom) + + +## PNP STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. (6) (0) PDO_WaitPnpStart +02. Ev_PDO_IRP_MN_START PDO_WaitPnpStart PDO_WaitPnpStop + +## POWER STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + + [EMPTY] + +## HARDWARE STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + +01. PdoEv_CreatePdo (0) Pdo_Created +02. PdoEv_RegisterPdo Pdo_Created Pdo_HwPresent +03. PdoEv_QBR Pdo_HwPresent Pdo_PnpRefHwPresent + +## IDLE STATE HISTORY (latest at bottom) + +## EVENT STATE NEXT + + [EMPTY] +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubinfo.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubinfo.md new file mode 100644 index 0000000000..0fcd88079a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubinfo.md @@ -0,0 +1,110 @@ +--- +title: usbkd.usbhubinfo +description: The usbkd.hubinfo command displays information about a USB hub. +ms.assetid: 01FF5822-0FCF-420F-AFF7-C91448DCBB98 +keywords: ["usbkd.usbhubinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubinfo +api_type: +- NA +--- + +# !usbkd.usbhubinfo + + +The **!usbkd.hubinfo** command displays information about a USB hub. + +``` +!usbkd.hubinfo FDO +``` + +## Parameters + + + *FDO* +Address of the functional device object (FDO) for a USB hub. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the FDO for a USB hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 +``` + +In the preceding output, the address of the FDO for the hub appears as the argument of the suggested command **!devstack ffffe00002320050**. + +Now pass the address of the FDO to the **!usbhubinfo** command. + +``` +0: kd> !usbkd.usbhubinfo ffffe00002320050 + + !DevObj ffffe00002320050 !usbhubext ffffe000023201a0 +On Host Controller (0x8086, 0x293c) + Stat_AsyncResumeStartAt: 2437ee39d29bd528 + Stat_AsyncResumeCompleteAt: 24413c77d29bd528 + Stat_AsyncResume: 0x3c(60) ms + Stat_SyncResumeStartAt: 2437ee39d29bd528 + Stat_SyncResumeCompleteAt: 2437ee39d29bd528 + Stat_SyncResume: 0x0(0) ms +Trap Regs: Event, Port, Event (ffffe000023204d0) + Enable: 0 Port: 0 Event 00000000 +Hub Number: # 3 +Number Of Ports: 4 +dt usbhub!_USBHUB_FDO_FLAGS ffffe00002320ba0 +>Is Root +>Power Switching: + No Power Switching +>Overcurrent: + Global Overcurrent +>PortIndicators: + No PortIndicators present +>AllowWakeOnConnect: + DO NOT WakeOnConnect +>CURRENT Hub Wake on Connectstate: + HWC_DISARM:- do not wake system on connect/disconnect event +>CURRENT Bus Wake state: + BUS_DISARM:- bus not armed for wake by this hub +>CURRENT Wake Detect state (WW Irp): + HUB_DISARM:- no ww irp pending (HUB_WAKESTATE_DISARMED) +Milliamps/Port : 500ma +Power caps (0 = not reported) + PortPower_Registry : 0 + PortPower_DeviceStatus : 500 + PortPower_CfgDescriptor : 500 + PortPower_HubStatus : 500 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhublog.md b/windows-driver-docs-pr/debugger/-usbkd-usbhublog.md new file mode 100644 index 0000000000..75586f778a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhublog.md @@ -0,0 +1,104 @@ +--- +title: usbkd.usbhublog +description: The usbkd.usbhublog command displays the debug log for a USB hub. +ms.assetid: DFDF595E-3452-40C2-A6C7-94FB8954002C +keywords: ["usbkd.usbhublog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhublog +api_type: +- NA +--- + +# !usbkd.usbhublog + + +The **!usbkd.usbhublog** command displays the debug log for a USB hub. + +``` +!usbkd.usbhublog DeviceExtension[, NumberOfEntries] +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a USB hub. + + *NumberOfEntries* +The number of log entries to display. To display the entire log, set this parameter to -1. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of the device extension for the FDO of a USB hub. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + ... +``` + +In the preceding output, you can see the suggested command **!devstack ffffe00002320050**. Enter this command. + +``` +0: kd> !kdexts.devstack ffffe00002320050 + + !DevObj !DrvObj !DevExt ObjectName +> ffffe00002320050 \Driver\usbhub ffffe000023201a0 0000002d + ffffe0000213c050 \Driver\usbehci ffffe0000213c1a0 USBPDO-3 +... +``` + +In the preceding output, `ffffe000023201a0` is the address of the device extension for the FDO of the hub. + +Now pass the address of the device extension to **!usbhublog**. In this example, the second argument limits the display to 10 log entries. + +``` +0: kd> !usbkd.usbhublog ffffe000023201a0, 10 + +LOG@: ffffe000023201a0 (usbhub!_DEVICE_EXTENSION_HUB) +>LOG mask = ff idx = ffffa333 (33) +*LOG: ffffe00002321ca0 LOGSTART: ffffe00002321640 *LOGEND: ffffe00002323620 # 20 +[ 000] ffffe00002321ca0 HDec 0000000000000000 ffffe000002904d0 0000000000000001 +[ 001] ffffe00002321cc0 HPCd 0000000000000000 0000000000000002 0000000000000004 +[ 002] ffffe00002321ce0 qwk- 0000000000000000 ffffe000021c11c0 0000000000000000 +[ 003] ffffe00002321d00 pq-- 0000000000000000 0000000000000002 0000000000000004 +[ 004] ffffe00002321d20 _6p4 0000000000000000 0000000000000000 0000000000000004 +[ 005] ffffe00002321d40 _6p1 0000000000000000 0000000000000003 0000000000000004 +[ 006] ffffe00002321d60 pq++ 0000000000000000 0000000000000003 0000000000000004 +[ 007] ffffe00002321d80 pq++ 0000000000000000 0000000000000006 0000000000000004 +[ 008] ffffe00002321da0 _6p0 0000000000000000 ffffe000021c11c0 0000000000000004 +[ 009] ffffe00002321dc0 pqDP 0000000000000000 ffffe000021c11d8 0000000000000006 +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhublog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubmddevext.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubmddevext.md new file mode 100644 index 0000000000..1da31b2780 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubmddevext.md @@ -0,0 +1,54 @@ +--- +title: usbkd.usbhubmddevext +description: The usbkd.usbhubmddevext command displays a usbhub _DEVICE_EXTENSION_HUB structure if one is present in a crash dump that was generated as a result of a Bug Check 0xFE. +ms.assetid: 2A3C1AD4-0537-43B1-BD87-734047D242B9 +keywords: ["usbkd.usbhubmddevext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubmddevext +api_type: +- NA +--- + +# !usbkd.usbhubmddevext + + +The **!usbkd.usbhubmddevext** command displays a **usbhub!\_DEVICE\_EXTENSION\_HUB** structure if one is present in a crash dump that was generated as a result of a [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.usbhubmddevext +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubmddevext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubmdpd.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubmdpd.md new file mode 100644 index 0000000000..ea4eb22f38 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubmdpd.md @@ -0,0 +1,60 @@ +--- +title: usbkd.usbhubmdpd +description: The usbkd.usbhubmdpd command displays a usbhub _HUB_PORT_DATA structure if one is present in a crash dump that was generated as a result of Bug Check 0xFE. +ms.assetid: 128D45A2-A891-42BC-9E3E-FCDC5B4504A2 +keywords: ["usbkd.usbhubmdpd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubmdpd +api_type: +- NA +--- + +# !usbkd.usbhubmdpd + + +The **!usbkd.usbhubmdpd** command displays a **usbhub!\_HUB\_PORT\_DATA** structure if one is present in a crash dump that was generated as a result of [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.usbhubmdpd [PortNum] +``` + +## Parameters + + + *PortNum* +A USB port number. If you specify a port number, this command displays the structure (if one is present) that represents the specified port. If you do not specify a port number, this command displays the structure (if one is present) on which [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md) was initiated. + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubmdpd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubpd.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubpd.md new file mode 100644 index 0000000000..4aaf4e1a6d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubpd.md @@ -0,0 +1,134 @@ +--- +title: usbkd.usbhubpd +description: The usbkd.usbhubpd command displays information about a USB port. +ms.assetid: 41D5E65D-76C2-45E0-9AC7-C2B50D806935 +keywords: ["usbkd.usbhubpd Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubpd +api_type: +- NA +--- + +# !usbkd.usbhubpd + + +The **!usbkd.usbhubpd** command displays information about a USB port. + +``` +!usbkd.usbhubpd StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbhub!\_HUB\_PORT\_DATA** structure. To get the addresses of these structures, use [**!usbhubext**](-usbkd-usbhubext.md). + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbhub!\_HUB\_PORT\_DATA**. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 + RootHub !hub2_info ffffe000023201a0 !devstack ffffe00002320050 + ... +``` + +In the preceding output, you can see the suggested command **!devstack ffffe00002320050**. Enter this command. + +``` +0: kd> !kdexts.devstack ffffe00002320050 + + !DevObj !DrvObj !DevExt ObjectName +> ffffe00002320050 \Driver\usbhub ffffe000023201a0 0000002d + ffffe0000213c050 \Driver\usbehci ffffe0000213c1a0 USBPDO-3 +... +``` + +In the preceding output, you can see that the address of the device extension for the FDO of the hub is `ffffe000023201a0`. + +Pass the address of the device extension to the [**!usbhubext**](-usbkd-usbhubext.md) command. + +``` +0: kd> !usbkd.usbhubext ffffe000023201a0 + +FDO ffffe00002320050 PDO ffffe0000213c050 HubNumber# 3 +dt USBHUB!_DEVICE_EXTENSION_HUB ffffe000023201a0 +!usbhublog ffffe000023201a0 +RemoveLock ffffe00002320668 +FdoFlags ffffe00002320ba0 + +CurrentPowerIrp: System (0000000000000000) Device (0000000000000000) +... +## PORT DATA + +PortData 1: !port2_info ffffe000021bf000 Port State = PS_WAIT_CONNECT PortChangeLock: 0, Pcq_State: Pcq_Run_Idle + PDO 0000000000000000 +.... +``` + +In the preceding output, `ffffe000021bf000` is the address of a **\_HUB\_PORT\_DATA** structure. Pass this address to **!usbhubpd**. + +``` +0: kd> !usbkd.usbhubpd ffffe000021bf000 +PortNumber: 1 +Parent Hub FDO ffffe00002320050 +Device PDO +dt USBHUB!_HUB_PORT_DATA ffffe000021bf000 +dt USBHUB!_PORTDATA_FLAGS ffffe000021bf968 + +PortChangelist: !usblist ffffe000021bf1c8, CL [Empty] + +## Port Indicators Log (latest at bottom) + +## Event State Next + + [EMPTY] + +## Port Change Queue History (latest at bottom) + +## Event State Next PcqEv_Suspend PcqEv_Resume PcqEv_ChDone Tag + +01. PCE_Resume Pcq_Stop Pcq_Pause PcqEv_Reset PcqEv_Reset REQUEST_RESUME +... Pcq_Run_wBusy Pcq_Run_Idle + +## Port Status History (latest at bottom) + +## Current State Change Eve nt PDO CEOSP H/W Port REG Frame Inserted + +01. PS_WAIT_CONNECT REQUEST_PAUSE 0000000000000000 00000 100 Age:000 512498 +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubpd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbhubs.md b/windows-driver-docs-pr/debugger/-usbkd-usbhubs.md new file mode 100644 index 0000000000..9b16a28dc0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbhubs.md @@ -0,0 +1,125 @@ +--- +title: usbkd.usbhubs +description: The usbkd.usbhubs command displays information about USB hubs. +ms.assetid: 88642A67-5105-45A4-8374-7E4D01FFAEB6 +keywords: ["usbkd.usbhubs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbhubs +api_type: +- NA +--- + +# !usbkd.usbhubs + + +The **!usbkd.usbhubs** command displays information about USB hubs. + +``` +!usbkd.usbhubs a[v] +!usbkd.usbhubs x[v] +!usbkd.usbhubs r[v] +``` + +## Parameters + + + **a** +Display all hubs. + + **r** +Display root hubs. + + **x** +Display external hubs. + + **v** +The output is verbose. For example, **!usbhubs rv** displays verbose output about all root hubs. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is an example of verbose output from the **!usbhubs** command. + +``` +0: kd> !usbkd.usbhubs rv + +args 'rv' +level: r v +ROOT HUBS +*LIST -- Root Hub List @ fffff8000217f440 +*flink, blink ffffe000023215c0,ffffe000011f85c0 +---------- + +[0] entry @: ffffe000023201a0 + !DevObj ffffe00002320050 !usbhubext ffffe000023201a0 +On Host Controller (0x8086, 0x293c) + Stat_AsyncResumeStartAt: 2437ee39d29bd498 + Stat_AsyncResumeCompleteAt: 24413c77d29bd498 + Stat_AsyncResume: 0x3c(60) ms + Stat_SyncResumeStartAt: 2437ee39d29bd498 + Stat_SyncResumeCompleteAt: 2437ee39d29bd498 + Stat_SyncResume: 0x0(0) ms +Trap Regs: Event, Port, Event (ffffe000023204d0) + Enable: 0 Port: 0 Event 00000000 +Hub Number: # 3 +Number Of Ports: 4 +dt usbhub!_USBHUB_FDO_FLAGS ffffe00002320ba0 +>Is Root +>Power Switching: + No Power Switching +>Overcurrent: + Global Overcurrent +>PortIndicators: + No PortIndicators present +>AllowWakeOnConnect: + DO NOT WakeOnConnect +>CURRENT Hub Wake on Connectstate: + HWC_DISARM:- do not wake system on connect/disconnect event +>CURRENT Bus Wake state: + BUS_DISARM:- bus not armed for wake by this hub +>CURRENT Wake Detect state (WW Irp): + HUB_DISARM:- no ww irp pending (HUB_WAKESTATE_DISARMED) +Milliamps/Port : 500ma +Power caps (0 = not reported) + PortPower_Registry : 0 + PortPower_DeviceStatus : 500 + PortPower_CfgDescriptor : 500 +## PortPower_HubStatus : 500 + +---------- + +[1] entry @: ffffe000008b91a0 + !DevObj ffffe000008b9050 !usbhubext ffffe000008b91a0 +On Host Controller (0x8086, 0x2937) +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbhubs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usblist.md b/windows-driver-docs-pr/debugger/-usbkd-usblist.md new file mode 100644 index 0000000000..ef25611b96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usblist.md @@ -0,0 +1,124 @@ +--- +title: usbkd.usblist +description: The usbkd.usblist command displays a linked list of structures of a specified type. +ms.assetid: 503466EE-2246-4CE3-BCE7-6DC7D42DB86A +keywords: ["usbkd.usblist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usblist +api_type: +- NA +--- + +# !usbkd.usblist + + +The **!usbkd.usblist** command displays a linked list of structures of a specified type. + +``` +!usbkd.usblist ListAddr, ListType +``` + +## Parameters + + + *ListAddr* +Address of a linked list of structures. To find addresses of linked lists maintained by the USB port driver, use [**!usbhcdext**](-usbkd-usbhcdext.md). To find addresses of linked list maintained by the USB hub driver, use [**!usbhubext**](-usbkd-usbhubext.md). + + *ListType* +One of the following list types. + +| List type | Structure | +|-----------|------------------------------------------| +| **BC** | **usbport!\_BUS\_CONTEXT** | +| **EP** | **usbport!\_HCD\_ENDPOINT** | +| **TT** | **usbport!\_TRANSACTION\_TRANSLATOR** | +| **DL** | **usbport!\_USBD\_DEVICE\_HANDLE** | +| **PL** | **usbhub!\_DEVICE\_EXTENSION\_PDO** | +| **EL** | **usbhub!\_HUB\_EXCEPTION\_RECORD** | +| **RL** | **usbhub!\_HUB\_REFERENCE\_LIST\_ENTRY** | +| **TL** | **usbhub!\_HUB\_TIMER\_OBJECT** | +| **WI** | **usbhub!\_HUB\_WORKITEM** | +| **IO** | **usbhub!\_IO\_LIST\_ENTRY** | +| **LA** | **usbhub!\_LATCH\_LIST\_ENTRY** | +| **CL** | **usbhub!\_PORT\_CHANGE\_CONTEXT** | +| **BL** | **usbhub!\_SSP\_BUSY\_HANDLE** | + +  + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a linked list. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 ... + ... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072). + +``` +0: kd> !usbkd.usbhcdext ffffe00001ca11a0 + +HC Flavor 1000 FDO ffffe00001ca1050 +Root Hub: FDO ffffe00002320050 !hub2_info ffffe000023201a0 +... +DeviceHandleList: !usblist ffffe00001ca23b8, DL +... +``` + +In the preceding output, ffffe00001ca23b8 is the address of a linked list of **usbport!\_USBD\_DEVICE\_HANDLE** structures. + +Now pass the address of the linked list to **!usblist**. + +``` +0: kd> !usblist ffffe00001ca23b8, DL +list: ffffe00001ca23b8 DL +---------- +!usbdevh ffffe000020f9590 +SSP [IdleReady] (0) +PCI\VEN_Xxxx Xxxx Corporation +Root Hub +DriverName : +---------- +!usbdevh ffffe00001bce250 +SSP [IdleReady] (0) +USB\Xxxx Xxxx Corporation +Speed: HIGH, Address: 1, PortPathDepth: 1, PortPath: [3 0 0 0 0 0] +DriverName :\Driver\USBSTOR !devstack ffffe000053ef2a0 +---------- +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usblist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbpdos.md b/windows-driver-docs-pr/debugger/-usbkd-usbpdos.md new file mode 100644 index 0000000000..2a81bef61d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbpdos.md @@ -0,0 +1,101 @@ +--- +title: usbkd.usbpdos +description: The usbkd.usbpdos command displays information about all physical device objects (PDOs) created by the USB hub driver. +ms.assetid: 2EFAC774-C400-4218-BF48-2D5DC557A83B +keywords: ["usbkd.usbpdos Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbpdos +api_type: +- NA +--- + +# !usbkd.usbpdos + + +The **!usbkd.usbpdos** command displays information about all physical device objects (PDOs) created by the USB hub driver. + +``` +!usbkd.usbpdos +``` + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here's an example of the output of the **!usbpdos** command. + +``` +0: kd> !usbkd.usbpdos + +ext ffffe00006c513f0 +VID 0a12 PID 0001 REV 0309 + dt USBHUB!_USB_DEVICE_DESCRIPTOR ffffe00006c51960 +Vendor: Xxxx + Xxxx Corporation + dd Class: (224)(e0) + (224)(e0) +HubFdo: ffffe00000d94050, port: 2 + +SystemWake 5 SystemHibernate(S4) +wake_irp_list_head = ffffe00006c51cb0 +wake_irp = ffffe00006c51cb0 +PDO Times: + Stat_PdoCreatedAt: 0d29bbd58 + Stat_PdoEnumeratedAt: b65ace75d29bbd58 + Stat: Enumeration Time: 0xa7d3842a(-1479310294) ms + Stat_Pdo_SetD0_StartAt: 0d29bbd58 + Stat_Pdo_SetD0_CompleteAt: 0d29bbd58 + Stat: PDO Set_D0 time: 0x0(0) ms + +## + +ext ffffe00007c883f0 +VID 0781 PID 5530 REV 0100 + dt USBHUB!_USB_DEVICE_DESCRIPTOR ffffe00007c88960 +Vendor: Xxxx + Xxxx Corporation + dd Class: (0)(0) + (8)Class_UsbStorage +HubFdo: ffffe00002320050, port: 3 +:Xxxx +SystemWake 5 SystemHibernate(S4) +wake_irp_list_head = ffffe00007c88cb0 +wake_irp = ffffe00007c88cb0 +PDO Times: + Stat_PdoCreatedAt: 0d29bbd58 + Stat_PdoEnumeratedAt: 2380af52d29bbd58 + Stat: Enumeration Time: 0x9a24226c(-1708907924) ms + Stat_Pdo_SetD0_StartAt: 0d29bbd58 + Stat_Pdo_SetD0_CompleteAt: 0d29bbd58 +## Stat: PDO Set_D0 time: 0x0(0) ms + +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbpdos%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbpdoxls.md b/windows-driver-docs-pr/debugger/-usbkd-usbpdoxls.md new file mode 100644 index 0000000000..5ea0894b34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbpdoxls.md @@ -0,0 +1,49 @@ +--- +title: usbkd.usbpdoxls +description: The usbkd.usbpdoxls command displays information about all physical device objects (PDOs) created by the USB hub driver. For each PDO, this command displays a row of comma-separated values. +ms.assetid: 10A2F582-3E4F-4248-BB49-40A4C23E5C55 +keywords: ["usbkd.usbpdoxls Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbpdoxls +api_type: +- NA +--- + +# !usbkd.usbpdoxls + + +The **!usbkd.usbpdoxls** command displays information about all physical device objects (PDOs) created by the USB hub driver. For each PDO, this command displays a row of comma-separated values. + +``` +!usbkd.usbpdoxls +``` + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbpdoxls%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbpnp.md b/windows-driver-docs-pr/debugger/-usbkd-usbpnp.md new file mode 100644 index 0000000000..3e65339e24 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbpnp.md @@ -0,0 +1,55 @@ +--- +title: usbkd.usbpnp +description: The usbkd.usbpnp command displays state context information about a USB hub. +ms.assetid: 2FF7F6A5-E9E5-4E4F-8323-3328ED00BCB9 +keywords: ["usbkd.usbpnp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbpnp +api_type: +- NA +--- + +# !usbkd.usbpnp + + +The **!usbkd.usbpnp** command displays state context information about a USB hub. + +``` +!usbkd.usbpnp DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +Address of the device extension for the functional device object (FDO) of a USB hub. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbpnp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbpo.md b/windows-driver-docs-pr/debugger/-usbkd-usbpo.md new file mode 100644 index 0000000000..7b396cc9f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbpo.md @@ -0,0 +1,49 @@ +--- +title: usbkd.usbpo +description: The usbkd.usbpo command displays the internal list of outstanding USB power requests. +ms.assetid: DB8AD37B-EB60-47E5-BBA5-C17DB0B9ADF5 +keywords: ["usbkd.usbpo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbpo +api_type: +- NA +--- + +# !usbkd.usbpo + + +The **!usbkd.usbpo** command displays the internal list of outstanding USB power requests. + +``` +!usbkd.usbpo +``` + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbpo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbportisasyncadv.md b/windows-driver-docs-pr/debugger/-usbkd-usbportisasyncadv.md new file mode 100644 index 0000000000..04b068ff59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbportisasyncadv.md @@ -0,0 +1,49 @@ +--- +title: usbkd.usbportisasyncadv +description: The usbkd.usbportisasyncadv command checks all EHCI miniport drivers for an EHCI Interrupt on Async Advance issue. +ms.assetid: F633FA76-1919-4929-9B95-C803D34F3C34 +keywords: ["usbkd.usbportisasyncadv Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbportisasyncadv +api_type: +- NA +--- + +# !usbkd.usbportisasyncadv + + +The **!usbkd.usbportisasyncadv** command checks all EHCI miniport drivers for an EHCI Interrupt on Async Advance issue. + +``` +!usbkd.usbportisasyncadv +``` + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbportisasyncadv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbportmddcontext.md b/windows-driver-docs-pr/debugger/-usbkd-usbportmddcontext.md new file mode 100644 index 0000000000..6efe083125 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbportmddcontext.md @@ -0,0 +1,54 @@ +--- +title: usbkd.usbportmddcontext +description: The usbkd.usbportmddcontext command displays USBPORT context data if it is present in a crash dump that was generated as a result of Bug Check 0xFE. +ms.assetid: 774C7EAE-A33E-49A6-956F-C0791134C221 +keywords: ["usbkd.usbportmddcontext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbportmddcontext +api_type: +- NA +--- + +# !usbkd.usbportmddcontext + + +The **!usbkd.usbportmddcontext** command displays USBPORT context data if it is present in a crash dump that was generated as a result of [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.usbportmddcontext +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbportmddcontext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbportmddevext.md b/windows-driver-docs-pr/debugger/-usbkd-usbportmddevext.md new file mode 100644 index 0000000000..afbdb84796 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbportmddevext.md @@ -0,0 +1,124 @@ +--- +title: usbkd.usbportmddevext +description: The usbkd.usbportmddevext command displays a usbport _DEVICE_EXTENSION structure if one is present in a crash dump that was generated as a result Bug Check 0xFE. +ms.assetid: 07DE5D4A-E909-4D9B-B906-B74C9CC8AE49 +keywords: ["usbkd.usbportmddevext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbportmddevext +api_type: +- NA +--- + +# !usbkd.usbportmddevext + + +The **!usbkd.usbportmddevext** command displays a **usbport!\_DEVICE\_EXTENSION** structure if one is present in a crash dump that was generated as a result [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.usbportmddevext +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +Examples +-------- + +Here is an example of the output of **!usbportmddevext**. + +``` +1: kd> !analyze -v +*** ... +BUGCODE_USB_DRIVER (fe) +... +1: kd> !usbkd.usbportmddevext +USBPORT.SYS DEVICE_EXTENSION DATA: +Hcd FDO Extension: +Sig:4f444648 HFDO +CurrentPnpFunc: 0x00000008 +PnpFuncHistoryIdx: 0x0000000d +CurrentPowerFunc: 0x00000000 +PowerFuncHistoryIdx: 0x00000000 +PnpLogIdx: 0x00000002 +IoRequestCount: 0x00000007 +IoRequestAsyncCallbackCount: 0xffffffff +IoRequestAllow: 0x00000000 +Pnp Func History (idx 13) +... +[02] pnp 13 (0d) IRP_MN_FILTER_RESOURCE_REQUIREMENTS +[... +Power Func History (idx 0) +[01] pnp 255 (ff) ??? (x0) PowerDeviceUnspecified +... + **Power and Wake ----------------------------------------------- + selective suspend:on (1) + PowerFlags (00000080): +*---FDO---* +PMDebug: 0x00000000 +MinAllocedBw: 0x00000000 +MaxAllocedBw: 0x00000000 +## ... + +## XDPC HISTORY_UsbHcIntDpc + +State History (idx 2) +EVENT, STATE, NEXT +Log[3] @ 000000d9e7c615cc +Ev_Xdpc_Worker XDPC_DpcQueued XDPC_Running +## ... + +## XDPC HISTORY_UsbDoneDpc + +State History (idx 0) +EVENT, STATE, NEXT +Log[1] @ 000000d9e7c61774 +Ev_Xdpc_Worker XDPC_DpcQueued XDPC_Running +## ... + +## XDPC HISTORY_UsbMapDpc + +State History (idx 3) +EVENT, STATE, NEXT +Log[4] @ 000000d9e7c6196c +## ... + +## XDPC HISTORY_UsbIocDpc + +State History (idx 0) +EVENT, STATE, NEXT +Log[1] @ 000000d9e7c61b04 +Ev_Xdpc_Worker XDPC_DpcQueued XDPC_Running +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbportmddevext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbportmdportlog.md b/windows-driver-docs-pr/debugger/-usbkd-usbportmdportlog.md new file mode 100644 index 0000000000..9c38734fdd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbportmdportlog.md @@ -0,0 +1,123 @@ +--- +title: usbkd.usbportmdportlog +description: The usbkd.usbportmdportlog command displays the USBPORT debug log if it is present in a crash dump that was generated as a result of Bug Check 0xFE. +ms.assetid: C0E32BDE-8186-4477-AB57-530B0AF6F27F +keywords: ["usbkd.usbportmdportlog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbportmdportlog +api_type: +- NA +--- + +# !usbkd.usbportmdportlog + + +The **!usbkd.usbportmdportlog** command displays the USBPORT debug log if it is present in a crash dump that was generated as a result of [**Bug Check 0xFE**](bug-check-0xfe--bugcode-usb-driver.md). + +``` +!usbkd.usbportmdportlog +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +Use this command only when you are debugging a crash dump file that was generated as a result of [**Bug Check 0xFE: BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md). + +Examples +-------- + +Here is an example of a portion of the output of **!usbportmdportlog**. + +``` +1: kd> !analyze -v +*** ... +BUGCODE_USB_DRIVER (fe) +... +1: kd> !usbkd.usbportmdportlog +Minidump USBPORT DEBUG_LOG buffer size 32768, entries 1024, index 400 +*LOG: 0000000113be9600 LOGSTART: 0000000113be6400 *LOGEND: 0000000113bee3e0 # 1024 +[ 000] 0000000113be9600 Bfe2 ffffe0001416802c ffffe000020a44f0 ffffe0001416801c +[ 001] 0000000113be9620 Bfe0 0000000000000000 ffffe000039f4720 ffffe00000b76cb0 +[ 002] 0000000113be9640 epr+ ffffe000043ee010 ffffe000008f5b80 ffffe00002820a0c +[ 003] 0000000113be9660 alTR ffffe00002820a0c ffffe000039f4720 ffffe00000b76cb0 +// +// USBPORT_Core_AllocTransferEx() +// transfer: ffffe00002820a0c +// Urb: ffffe000039f4720 +// Irp: ffffe00000b76cb0 + +[ 004] 0000000113be9680 TRcs 0000000000000060 0000000000000468 0000000000000001 +[ 005] 0000000113be96a0 urbi ffffe0001422c4cc 0000000000000012 000000000000000b +[ 006] 0000000113be96c0 dURB ffffe000039f4720 ffffe00000b76cb0 000000000000000b +// +// USBPORT_ProcessURB() - Device Handle valid and has been referenced +// Urb: ffffe000039f4720 +// Irp: ffffe00000b76cb0 +// function: URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE + +[ 007] 0000000113be96e0 vld> ffffe0001421ddd0 0000000000000004 ffffe000039f4720 +// +// USBPORT_NeoValidDeviceHandle() +// DeviceHandle: ffffe0001421ddd0 +// ReferenceObj: ffffe000039f4720 + +[ 008] 0000000113be9700 devH ffffe0001421ddd0 ffffe000039f4720 0000000000000000 +[ 009] 0000000113be9720 pURB ffffe000039f4720 ffffe00000b76cb0 000000000000000b +// +// USBPORT_ProcessURB() +// Urb: ffffe000039f4720 +// Irp: ffffe00000b76cb0 +// function: URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE + +[ 010] 0000000113be9740 PURB ffffe000039f4720 ffffe000020a44f0 000000000000000b +// +// USBPORT_ProcessURB() - Exit STATUS_PENDING +// Urb: ffffe000039f4720 +// Irp: ffffe000020a44f0 +// function: URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE + +[ 011] 0000000113be9760 Urb< 0000000000000103 000000000000000b 0000000000000000 +[ 012] 0000000113be9780 xSt0 ffffe000012bbf18 0000000000000006 0000000000000001 +[ 013] 0000000113be97a0 xnd8 ffffe000012bbf18 ffffe000012bb050 0000000000000000 +[ 014] 0000000113be97c0 xnd0 ffffe000012bbf18 ffffe000012bb050 0000000000000000 +// +// USBPORT_Xdpc_End() + +[ 015] 0000000113be97e0 mapF 0000000000000000 0000000000000000 0000000000000000 +[ 016] 0000000113be9800 map5 0000000000000000 0000000000000000 0000000000000000 +[ 017] 0000000113be9820 DMAx 0000000000000000 0000000000000000 0000000000000000 +[ 018] 0000000113be9840 subx 0000000000000000 0000000000000000 ffffe0001416801c +[ 019] 0000000113be9860 tmoZ 0000000000000000 ffffe0001416801c ffffe000141680a4 +... +... +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbportmdportlog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbtriage.md b/windows-driver-docs-pr/debugger/-usbkd-usbtriage.md new file mode 100644 index 0000000000..af365befd0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbtriage.md @@ -0,0 +1,49 @@ +--- +title: usbkd.usbtriage +description: The usbkd.usbtriage command displays a list of USB drivers and device objects. +ms.assetid: F71F0913-00E1-4647-8AAA-121C6BD6FD36 +keywords: ["usbkd.usbtriage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbtriage +api_type: +- NA +--- + +# !usbkd.usbtriage + + +The **!usbkd.usbtriage** command displays a list of USB drivers and device objects. + +``` +!usbkd.usbtriage +``` + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbtriage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbtt.md b/windows-driver-docs-pr/debugger/-usbkd-usbtt.md new file mode 100644 index 0000000000..f0bc498487 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbtt.md @@ -0,0 +1,71 @@ +--- +title: usbkd.usbtt +description: The usbkd.usbtt command displays information from a USBPORT _TRANSACTION_TRANSLATOR structure. +ms.assetid: 4D599BCE-C6C3-42B3-BDCE-EE9E47FA6AB7 +keywords: ["usbkd.usbtt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbtt +api_type: +- NA +--- + +# !usbkd.usbtt + + +The **!usbkd.usbtt** command displays information from a **USBPORT!\_TRANSACTION\_TRANSLATOR** structure. + +``` +!usbkd.usbtt StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_TRANSACTION\_TRANSLATOR** structure. To get the transaction translator list for a USB host controller, use the [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbport!\_TRANSACTION\_TRANSLATOR** structure. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +2)!ehci_info ffffe00001ca11a0 !devobj ffffe00001ca1050 PCI: VendorId 8086 DeviceId 293c RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!ehci\_info ffffe00001ca11a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) to get the address of `GlobalTtListHead`. Pass that address to [**!usbkd.usblist**](-usbkd-usblist.md), which will display addresses of **\_TRANSACTION\_TRANSLATOR** structures. + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbtt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbtx.md b/windows-driver-docs-pr/debugger/-usbkd-usbtx.md new file mode 100644 index 0000000000..541e8828c2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbtx.md @@ -0,0 +1,113 @@ +--- +title: usbkd.usbtx +description: The usbkd.usbtx command displays information from a usbport _HCD_TRANSFER_CONTEXT structure. +ms.assetid: 603AD207-69D5-4DED-80B5-ADA21E191D47 +keywords: ["usbkd.usbtx Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbtx +api_type: +- NA +--- + +# !usbkd.usbtx + + +The **!usbkd.usbtx** command displays information from a **usbport!\_HCD\_TRANSFER\_CONTEXT** structure. + +``` +!usbkd.usbtx StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_HCD\_TRANSFER\_CONTEXT** structure. To get the transfer list for a USB host controller, use the [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) command. + +## DLL + + +Usbkd.dll + +Examples +-------- + +Here is one way to find the address of a **usbport!\_HCD\_TRANSFER\_CONTEXT** structure. First enter [**!usbkd.usb2tree**](-usbkd-usb2tree.md). + +``` +0: kd> !usbkd.usb2tree +... +4)!uhci_info ffffe00001c8f1a0 !devobj ffffe00001c8f050 PCI: VendorId 8086 DeviceId 2938 RevisionId 0002 +... +``` + +In the preceding output, the address of the device extension of the FDO is displayed as the argument of the [DML](debugger-markup-language-commands.md) command **!uhci\_info ffffe00001c8f1a0**. + +Either click the DML command or pass the address of the device extension to [**!usbhcdext**](https://msdn.microsoft.com/library/windows/hardware/dn367072) to get the transfer list. + +``` +0: kd> !usbkd.usbhcdext ffffe00001c8f1a0 +... +## I/O TRANSFER LIST(s) + +1.) Transfer Request Priority List: (TxQueued) Type: 0-NotSplit, 1-Parent, 2-Child + -------------------------------------------------------------------------------- + [000]!usbtx ffffe0000653401c !usbep ffffe00004730c60 !irp ffffe00004221220 State: (7)TX_Mapped_inMp + Priority: 0, Type: 0, Flags= 0000000a, SequenceNum: 10, SplitIdx: 0 + InLen: 4096, OutLen: 0 Status: USBD_STATUS_PENDING (0x40000000) + ... +``` + +In the preceding output, `ffffe0000653401c` is the address of an **\_HCD\_TRANSFER\_CONTEXT**structure. Pass this address to **!usbtx**. + +``` +0: kd> !usbkd.usbtx ffffe0000653401c + +dt usbport!_HCD_TRANSFER_CONTEXT ffffe0000653401c +dt usbport!_TRANSFER_PARAMETERS ffffe0000653417c + +## TX HISTORY + +## EVENT, STATE, NEXT (latest at bottom) + +[01] (23)Ev_TX_Icsq, (0)TX_Undefined, (1)TX_InQueue +[02] (5)Ev_TX_MapTransfer, (1)TX_InQueue, (2)TX_MapPending +[03] (7)Ev_TX_MpSubmitSuccess, (2)TX_MapPending, (7)TX_Mapped_inMp + +**DMA** +dt usbport!_TRANSFER_SG_LIST ffffe0000653439c +SgCount: 1 MdlVirtualAddress: ffffe00000437000 MdlSystemAddress: ffffe00000437000 + [0] dt usbport!_TRANSFER_SG_ENTRY ffffe000065343bc + : sysaddr: 0000000000000000 len 0x00001000(4096) offset 0x00000000(0) phys 00000000'ded90000 +--- +dt usbport!_SCATTER_GATHER_ENTRY ffffe000065343ec +dt _SCATTER_GATHER_LIST ffffe00001bc231c +NumberOfElements = 1 + [0] dt _SCATTER_GATHER_ELEMENT ffffe00001bc232c + :phys 00000000'ded90000 len 0x00001000(4096) +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbtx%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbusb2ep.md b/windows-driver-docs-pr/debugger/-usbkd-usbusb2ep.md new file mode 100644 index 0000000000..902f41a5d4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbusb2ep.md @@ -0,0 +1,55 @@ +--- +title: usbkd.usbusb2ep +description: The usbkd.usbusb2ep command displays information from a usbport _USB2_EP structure. +ms.assetid: 0298D7A2-C121-4B09-8542-CCD10323D573 +keywords: ["usbkd.usbusb2ep Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbusb2ep +api_type: +- NA +--- + +# !usbkd.usbusb2ep + + +The **!usbkd.usbusb2ep** command displays information from a **usbport!\_USB2\_EP** structure. + +``` +!usbkd.usbusb2ep StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_USB2\_EP** structure. To get the address of **usbport!\_USB2\_EP** structure, use [**!usbkd.usb2**](-usbkd-usb2.md). + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbusb2ep%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbusb2tt.md b/windows-driver-docs-pr/debugger/-usbkd-usbusb2tt.md new file mode 100644 index 0000000000..4e2ca56afd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbusb2tt.md @@ -0,0 +1,55 @@ +--- +title: usbkd.usbusb2tt +description: The usbkd.usbusb2tt command displays information from a usbport _TT structure. +ms.assetid: 0020C59D-EC86-4820-8882-F801C0C7936E +keywords: ["usbkd.usbusb2tt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbusb2tt +api_type: +- NA +--- + +# !usbkd.usbusb2tt + + +The **!usbkd.usbusb2tt** command displays information from a **usbport!\_TT** structure. + +``` +!usbkd.usbusb2tt StructAddr +``` + +## Parameters + + + *StructAddr* +Address of a **usbport!\_TT** structure. + +## DLL + + +Usbkd.dll + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbusb2tt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-usbkd-usbver.md b/windows-driver-docs-pr/debugger/-usbkd-usbver.md new file mode 100644 index 0000000000..21d39dfc47 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-usbkd-usbver.md @@ -0,0 +1,66 @@ +--- +title: usbkd.usbver +description: The usbkd.usbver command displays the USBD interface version of the USB driver stack. +ms.assetid: E3F5A971-64FB-4826-8DC0-59F3615C106A +keywords: ["usbkd.usbver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- usbkd.usbver +api_type: +- NA +--- + +# !usbkd.usbver + + +The **!usbkd.usbver** command displays the USBD interface version of the USB driver stack. + +``` +!usbkd.usbver +``` + +## DLL + + +Usbkd.dll + +Remarks +------- + +The value of the USBD interface version is stored in the variable `usbport!usbd_version`. + +Examples +-------- + +Here is an example of the output of **!usbkd.usbver**. + +``` +1: kd> !usbkd.usbver + +USBD VER 600 USB stack is VISTA +``` + +## See also + + +[USB 2.0 Debugger Extensions](usb-2-0-extensions.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +**USBD\_IsInterfaceVersionSupported** +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!usbkd.usbver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-ustr.md b/windows-driver-docs-pr/debugger/-ustr.md new file mode 100644 index 0000000000..13aaea3032 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-ustr.md @@ -0,0 +1,84 @@ +--- +title: ustr +description: The ustr extension displays a UNICODE_STRING structure. +ms.assetid: 17b84bf0-5a5b-47a5-893b-fdc58ca2afc3 +keywords: ["strings", "UNICODE_STRING structure", "ustr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ustr +api_type: +- NA +--- + +# !ustr + + +The **!ustr** extension displays a UNICODE\_STRING structure. + +``` +!ustr Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the UNICODE\_STRING structure. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Ext.dll

Windows XP and later

Ext.dll

+ +  + +### Additional Information + +For more information about UNICODE\_STRING structures, see the Microsoft Windows SDK documentation. + +Remarks +------- + +Unicode strings are counted 16-bit character strings, as defined in the following structure: + +``` +typedef struct _UNICODE_STRING { + USHORT Length; + USHORT MaximumLength; + PWSTR Buffer; +} UNICODE_STRING; +``` + +If the string is null-terminated, **Length** does not include the trailing null. + +Most Win32 character string arguments are converted to Unicode strings before any real work is done. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!ustr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vad-reload.md b/windows-driver-docs-pr/debugger/-vad-reload.md new file mode 100644 index 0000000000..e49e6159ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vad-reload.md @@ -0,0 +1,99 @@ +--- +title: vad_reload +description: The vad_reload extension reloads the user-mode modules for a specified process by using the virtual address descriptors (VADs) of that process. +ms.assetid: B5500227-DDC5-43aa-987B-EB02C59B3AC6 +keywords: ["vad_reload Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vad_reload +api_location: +- Kdextx86.dll +- Kdexts.dll +api_type: +- DllExport +--- + +# !vad\_reload + + +The **!vad\_reload** extension reloads the user-mode modules for a specified process by using the virtual address descriptors (VADs) of that process. + +``` +!vad_reload Process +``` + +## Parameters + + + *Process* +Specifies the hexadecimal address of the process for which the modules will be loaded. + +### Additional Information + +For information about VADs, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +You can use the [**!process**](-process.md) extension to find the address of a process. + +Here is an example of how to find an address and use it in the **!vad\_reload** command. + +``` +3: kd> !process 0 0 +. . . +PROCESS fffffa8007d54450 + SessionId: 1 Cid: 115c Peb: 7ffffef6000 ParentCid: 0c58 + DirBase: 111bc3000 ObjectTable: fffff8a006ae0960 HandleCount: 229. + Image: SearchProtocolHost.exe +. . . +3: kd> !vad_reload fffffa8007d54450 +fffffa80`04f5e8b0: VAD maps 00000000`6c230000 - 00000000`6c26bfff, file cscobj.dll +fffffa80`04e8f890: VAD maps 00000000`6ef90000 - 00000000`6f04afff, file mssvp.dll +fffffa80`07cbb010: VAD maps 00000000`6f910000 - 00000000`6faf5fff, file tquery.dll +fffffa80`08c1f2a0: VAD maps 00000000`6fb80000 - 00000000`6fb9bfff, file mssprxy.dll +fffffa80`07dce8b0: VAD maps 00000000`6fba0000 - 00000000`6fba7fff, file msshooks.dll +fffffa80`04fd2e70: VAD maps 00000000`72a50000 - 00000000`72a6cfff, file userenv.dll +. . . +``` + +Requirements +------------ + + ++++ + + + + + + +

DLL

Kdextx86.dll (Windows 2000); +Kdexts.dll (Windows XP and later)
+ +## See also + + +[**!process**](-process.md) + +[**!vad**](-vad.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vad_reload%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-vad.md b/windows-driver-docs-pr/debugger/-vad.md new file mode 100644 index 0000000000..405fb7d329 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vad.md @@ -0,0 +1,115 @@ +--- +title: vad +description: The vad extension displays details of a virtual address descriptor (VAD) or a tree of VADs. +ms.assetid: 96bd5a38-016d-4ce9-b128-cc730577be45 +keywords: ["virtual address descriptor (VAD)", "VAD (virtual address descriptor)", "addresses, virtual address descriptor (VAD)", "vad Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vad +api_type: +- NA +--- + +# !vad + + +The **!vad** extension displays details of a virtual address descriptor (VAD) or a tree of VADs. + +- Displays details of one virtual addres descriptor (VAD) +- Displays details of a tree of VADs. +- Displays information about the VADs for a particular user-mode module and provides a string that you can use to load the symbols for that module. + +``` +!vad VAD-Root [Flag] +!vad Address 1 +``` + +## Parameters + + + *VAD-Root* +Address of the root of the VAD tree to be displayed. + + *Flag* +Specifies the form the display will take. Possible values include: + +0 +The entire VAD tree based at *VAD-Root* is displayed. (This is the default.) + +1 +Only the VAD specified by *VAD-Root* is displayed. The display will include a more detailed analysis. + + *Address* +Address in the virtual address range of a user-mode module. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about virtual address descriptors, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The address of the root of the VAD for any process can be found by using the [**!process**](-process.md) command. + +The **!vad** command can be helpful when you need to load symbols for a user-mode module that has been paged out of memory. For details, see [Mapping Symbols When the PEB is Paged Out](mapping-symbols-when-the-peb-is-paged-out.md). + +Here is an example of the **!vad** extension: + +``` +kd> !vad 824bc2f8 +VAD level start end commit +82741bf8 ( 1) 78000 78045 8 Mapped Exe EXECUTE_WRITECOPY +824ef368 ( 2) 7f6f0 7f7ef 0 Mapped EXECUTE_READ +824bc2f8 ( 0) 7ffb0 7ffd3 0 Mapped READONLY +8273e508 ( 2) 7ffde 7ffde 1 Private EXECUTE_READWRITE +82643fc8 ( 1) 7ffdf 7ffdf 1 Private EXECUTE_READWRITE + +Total VADs: 5 average level: 2 maximum depth: 2 + +kd> !vad 824bc2f8 1 + +VAD @ 824bc2f8 + Start VPN: 7ffb0 End VPN: 7ffd3 Control Area: 827f1208 + First ProtoPte: e1008500 Last PTE e100858c Commit Charge 0 (0.) + Secured.Flink 0 Blink 0 Banked/Extend: 0 Offset 0 + ViewShare NoChange READONLY + +SecNoChange +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vad%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vadump.md b/windows-driver-docs-pr/debugger/-vadump.md new file mode 100644 index 0000000000..4de9ed4535 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vadump.md @@ -0,0 +1,115 @@ +--- +title: vadump +description: The vadump extension displays all virtual memory ranges and their corresponding protection information. +ms.assetid: b13aa852-7333-41fc-ad66-4386040522d8 +keywords: ["vadump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vadump +api_type: +- NA +--- + +# !vadump + + +The **!vadump** extension displays all virtual memory ranges and their corresponding protection information. + +``` + !vadump [-v] +``` + +## Parameters + + + **-v** +Causes the display to include information about each original allocation region as well. Because individual addresses within a region can have their protection altered after memory is allocated (by **VirtualProtect**, for example), the original protection status for this larger region may not be the same as that of each range within the region. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Uext.dll

Windows XP and later

Uext.dll

+ +  + +### Additional Information + +To view memory protection information for a single virtual address, use [**!vprot**](-vprot.md). For information about memory protection, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. + +Remarks +------- + +Here is an example: + +``` +0:000> !vadump +BaseAddress: 00000000 +RegionSize: 00010000 +State: 00010000 MEM_FREE +Protect: 00000001 PAGE_NOACCESS + +BaseAddress: 00010000 +RegionSize: 00001000 +State: 00001000 MEM_COMMIT +Protect: 00000004 PAGE_READWRITE +Type: 00020000 MEM_PRIVATE +......... +``` + +In this display, the State line shows the state of the memory range beginning at the specified BaseAddress. The possible state values are MEM\_COMMIT, MEM\_FREE, and MEM\_RESERVE. + +The Protect line shows the protection status of this memory range. The possible protection values are PAGE\_NOACCESS, PAGE\_READONLY, PAGE\_READWRITE, PAGE\_EXECUTE, PAGE\_EXECUTE\_READ, PAGE\_EXECUTE\_READWRITE, PAGE\_WRITECOPY, PAGE\_EXECUTE\_WRITECOPY, and PAGE\_GUARD. + +The Type line shows the memory type. The possible values are MEM\_IMAGE, MEM\_MAPPED, and MEM\_PRIVATE. + +Here is an example using the **-v** parameter: + +``` +0:000> !vadump -v +BaseAddress: 00000000 +AllocationBase: 00000000 +RegionSize: 00010000 +State: 00010000 MEM_FREE +Protect: 00000001 PAGE_NOACCESS + +BaseAddress: 00010000 +AllocationBase: 00010000 +AllocationProtect: 00000004 PAGE_READWRITE +RegionSize: 00001000 +State: 00001000 MEM_COMMIT +Protect: 00000004 PAGE_READWRITE +Type: 00020000 MEM_PRIVATE +......... +``` + +When **-v** is used, the AllocationProtect line shows the default protection that the entire region was created with. The Protect line shows the actual protection for this specific address. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vadump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-validatelist.md b/windows-driver-docs-pr/debugger/-validatelist.md new file mode 100644 index 0000000000..8a62b6bdb2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-validatelist.md @@ -0,0 +1,68 @@ +--- +title: validatelist +description: The validatelist extension verifies that the backward and forward links in a doubly-linked list are valid. +ms.assetid: 3d90d21a-8f86-4047-9313-7205ec1b53a3 +keywords: ["doubly-linked list", "validatelist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- validatelist +api_type: +- NA +--- + +# !validatelist + + +The **!validatelist** extension verifies that the backward and forward links in a doubly-linked list are valid. + +``` +!validatelist Address +``` + +## Parameters + + + *Address* +The address of the doubly-linked list. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +To stop execution, press Ctrl+Break (in WinDbg) or Ctrl+C (in KD). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!validatelist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-verifier.md b/windows-driver-docs-pr/debugger/-verifier.md new file mode 100644 index 0000000000..848b86edaf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-verifier.md @@ -0,0 +1,331 @@ +--- +title: verifier +description: The verifier extension displays the status of Driver Verifier and its actions. +ms.assetid: e84993e1-da10-4041-8fc7-7f40806ee454 +keywords: ["Driver Verifier", "verifier Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- verifier +api_type: +- NA +--- + +# !verifier + + +The **!verifier** extension displays the status of Driver Verifier and its actions. + +Driver Verifier is included in Windows. It works on both checked and free builds. For information about Driver Verifier, see the [Driver Verifier](http://go.microsoft.com/fwlink/p/?linkid=120480) topic in the Windows Driver Kit (WDK) documentation. + +Syntax + +``` +!verifier [Flags [Image]] +!verifier 4 [Quantity] +!verifier 8 [Quantity] +!verifier 0x40 [Quantity] +!verifier 0x80 [Quantity] +!verifier 0x80 Address +!verifier 0x100 [Quantity] +!verifier 0x100 Address +!verifier 0x200 [Address] +!verifier 0x400 [Address] +!verifier -disable +!verifier ? +``` + +## Parameters + + + *Flags* +Specifies what information is displayed in the output from this command. If *Flags* is equal to the value 4, 8, 0x20, 0x40, 0x80, or 0x100, then the remaining arguments to **!verifier** are interpreted based on the specific arguments associated with those values. If *Flags* is equal to any other value, even if one or more of these bits are set, only the *Flags* and *Image* arguments are permitted. *Flags* can be any sum of the following bits; the default is 0: + +Bit 0 (0x1) +Displays the names of all drivers being verified. The number of bytes currently allocated to each driver from the nonpaged pool and the paged pool is also displayed. + +Bit 1 (0x2) +Displays information about pools (pool size, headers, and pool tags) and outstanding memory allocations left by unloaded drivers. This flag has no effect unless bit 0 (0x1) is also set. + +Bit 2 (0x4) +(Windows XP and later) Displays fault injection information. The return address, symbol name, and displacement of the code requesting each allocation are displayed. If *Flags* is exactly 0x4 and the *Quantity* parameter is included, the number of these records displayed can be chosen. Otherwise, four records are displayed. + +Bit 3 (0x8) +(Windows XP and later) Displays the most recent IRQL changes made by the drivers being verified. The old IRQL, new IRQL, processor, and time stamp are displayed. If *Flags* is exactly 0x8 and the *Quantity* parameter is included, the number of these records displayed can be chosen. Otherwise, four records are displayed. + +**Warning**  In 64-bit versions of Windows, some of the kernel functions that raise or lower the IRQL are implemented as inline code rather than as exported functions. Driver Verifier does not report IRQL changes made by inline code, so it is possible for the IRQL transition log produced by Driver Verifier to be incomplete. See Remarks for an example of a missing IRQL transition entry. + +  + +Bit 6 (0x40) +(Windows Vista and later) Displays information from the **Force Pending I/O Requests** option of Driver Verifier, including traces from the log of forced pending IRPs. + +The *Quantity* parameter specifies the number of traces to be displayed. By default, the entire log is displayed. + +Bit 7 (0x80) +(Windows Vista and later) Displays information from the kernel pool Allocate/Free log. + +The *Quantity* parameter specifies the number of traces to be displayed. By default, the entire log is displayed. + +If *Address* is specified, only traces associated with the specified address within the kernel pool Allocate/Free log are displayed. + +Bit 8 (0x100) +(Windows Vista and later) Displays information from the log of IoAllocateIrp, IoCompleteRequest and IoCancelIrp calls. + +The Quantity parameter specifies the number of traces to be displayed. By default, the entire log is displayed. + +If *Address* is specified, only traces associated with the specified IRP address are displayed. + +Bit 9 (0x200) +(Windows Vista and later) Displays entries in the Critical Region log. + +If *Address* is specified, only entries associated with the specified thread address are displayed. + +Bit 10 (0x400) +(Windows Vista and later) Displays cancelled IRPs that are currently being watched by Driver Verifier. + +If *Address* is specified, only the IRP with the specified address is displayed. + +Bit 11 (0x800) +(Windows 8.1 and later) Display entries from the fault injection log that is created when you select the [Systematic low resource simulation](https://msdn.microsoft.com/library/windows/hardware/dn312130) option. + + *Image* +If *Flags* is used and is not equal to 4, 8, or 0x10, *Image* specifies the name of a driver. *Image* is used to filter the information displayed by *Flags* values of 0x1 and 0x2: only the specified driver is considered. This driver must be currently verified. + + *Quantity* +(Windows XP and later) If *Flags* is exactly equal to 0x4, *Quantity* specifies the number of fault injection records to display. If *Flags* is exactly equal to 0x8, *Quantity* specifies the number of IRQL log entries to display. If *Flags* is exactly equal to 0x40, *Quantity* specifies the number of traces displayed from the log of forced pending IRPs. If Flags is exactly equal to 0x80, Quantity specifies the number of traces displayed from the kernel pool Allocate/Free log. If Flags is exactly equal to 0x100, Quantity specifies the number of traces displayed from the log of IoAllocateIrp, IoCompleteRequest and IoCancelIrp calls. + + **-disable** +(Windows XP and later) Clears the current Driver Verifier settings on the debug target. The clearing of these settings does not persist through a reboot. If you need to disable the Driver Verifier settings to successfully boot, set a breakpoint at nt!VerifierInitSystem and use the **!verifier -disable** command at that point. + + **?** +(Windows XP and later) Displays some brief Help text for this extension in the Debugger Command window. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about [Driver Verifier](http://go.microsoft.com/fwlink/p/?linkid=120480), see the Windows Driver Kit (WDK) documentation. + +For more information and downloads, see the [Driver Verifier](http://go.microsoft.com/fwlink/p/?linkid=8753) on the Windows Hardware Developer Central (WHDC). + +Remarks +------- + +The following example illustrates that on 64-bit versions of Windows, the IRQL transition log is not always complete. The two entries shown are consecutive entries in the log for Processor 2. The first entry shows the IRQL going from 2 to 0. The second entry shows the IRQL going from 2 to 2. Information about how the IRQL got raised from 0 to 2 is missing. + +``` +Thread: fffffa80068c9400 +Old irql: 0000000000000002 +New irql: 0000000000000000 +Processor: 0000000000000002 +Time stamp: 0000000000000857 + + fffff8800140f12a ndis!ndisNsiGetInterfaceInformation+0x20a + fffff88001509478 NETIO!NsiGetParameterEx+0x178 + fffff88005f062f2 nsiproxy!NsippGetParameter+0x24a + fffff88005f086db nsiproxy!NsippDispatchDeviceControl+0xa3 + fffff88005f087a0 nsiproxy!NsippDispatch+0x48 + +Thread: fffffa80068c9400 +Old irql: 0000000000000002 +New irql: 0000000000000002 +Processor: 0000000000000002 +Time stamp: 0000000000000857 + + fffff8800140d48d ndis!ndisReferenceTopMiniportByNameForNsi+0x1ce + fffff8800140f072 ndis!ndisNsiGetInterfaceInformation+0x152 + fffff88001509478 NETIO!NsiGetParameterEx+0x178 + fffff88005f062f2 nsiproxy!NsippGetParameter+0x24a + fffff88005f086db nsiproxy!NsippDispatchDeviceControl+0xa3 +``` + +When using Driver Verifier to test graphics drivers, use the [**!gdikdx.verifier**](-gdikdx-verifier.md) extension instead of **!verifier**. + +The values of 4, 8, and 0x20, 0x40, 0x80, and 0x100 are special values for *Flags*. If these values are used, the special arguments listed in the **Parameters** section can be used, and the display will include only the information associated with that flag value. + +If any other value for *Flags* is used, even if one or more of these bits are set, only the *Flags* and *Image* arguments are permitted. In this situation, in addition to all the other information displayed, **!verifier** will display the Driver Verifier options that are active, along with statistics on pool allocations, IRQL raises, spin locks, and trims. + +If *Flags* equals 0x20, the values specified for *CompletionTime*, *CancelTime*, and *ForceCancellation* are used by the Driver Hang Verification option of Driver Verifier. These new values take effect immediately and last until the next boot. When you reboot, they revert to their default values. + +Also, if *Flags* equals 0x20 (with or without additional parameters), the Driver Hang Verification log is printed. For information on interpreting the log, see the Driver Hang Verification section of the Driver Verifier documentation in the Windows Driver Kit (WDK) documentation. + +Here is an example of the **!verifier** extension on a Windows 7 computer. + +``` +2: kd> !verifier 0xf + +Verify Level 9bb ... enabled options are: + Special pool + Special irql + All pool allocations checked on unload + Io subsystem checking enabled + Deadlock detection enabled + DMA checking enabled + Security checks enabled + Miscellaneous checks enabled + +Summary of All Verifier Statistics + +RaiseIrqls 0x0 +AcquireSpinLocks 0x362 +Synch Executions 0x0 +Trims 0xa34a + +Pool Allocations Attempted 0x7b058 +Pool Allocations Succeeded 0x7b058 +Pool Allocations Succeeded SpecialPool 0x7b058 +Pool Allocations With NO TAG 0x0 +Pool Allocations Failed 0x0 +Resource Allocations Failed Deliberately 0x0 + +Current paged pool allocations 0x1a for 00000950 bytes +Peak paged pool allocations 0x1b for 00000AC4 bytes +Current nonpaged pool allocations 0xe3 for 00046110 bytes +Peak nonpaged pool allocations 0x10f for 00048E40 bytes + +Driver Verification List + +Entry State NonPagedPool PagedPool Module + +fffffa8003b6f670 Loaded 000000a0 00000854 videoprt.sys + +Current Pool Allocations 00000002 00000013 +Current Pool Bytes 000000a0 00000854 +Peak Pool Allocations 00000006 00000014 +Peak Pool Bytes 000008c0 000009c8 + +PoolAddress SizeInBytes Tag CallersAddress +fffff9800157efc0 0x0000003c Vprt fffff88002c62963 +fffff9800146afc0 0x00000034 Vprt fffff88002c62963 +fffff980015bafe0 0x00000018 Vprt fffff88002c628f7 +... + +fffffa8003b6f620 Loaded 00046070 000000fc usbport.sys + +Current Pool Allocations 000000e1 00000007 +Current Pool Bytes 00046070 000000fc +Peak Pool Allocations 0000010d 0000000a +Peak Pool Bytes 00048da0 00000254 + +PoolAddress SizeInBytes Tag CallersAddress +fffff98003a38fc0 0x00000038 usbp fffff88004215e34 +fffff98003a2cfc0 0x00000038 usbp fffff88004215e34 +fffff9800415efc0 0x00000038 usbp fffff88004215e34 +... + +----------------------------------------------- +Fault injection trace log +----------------------------------------------- + +Driver Verifier didn't inject any faults. + +----------------------------------------------- +Track irql trace log +----------------------------------------------- + +Displaying most recent 0x0000000000000004 entries from the IRQL transition log. +There are up to 0x100 entries in the log. + +Thread: fffff80002bf8c40 +Old irql: 0000000000000002 +New irql: 0000000000000002 +Processor: 0000000000000000 +Time stamp: 000000000000495e + + fffff8800420f2ca USBPORT!USBPORT_DM_IoTimerDpc+0x9a + fffff80002a5b5bf nt!IopTimerDispatch+0x132 + fffff80002a7c29e nt!KiProcessTimerDpcTable+0x66 + fffff80002a7bdd6 nt!KiProcessExpiredTimerList+0xc6 + fffff80002a7c4be nt!KiTimerExpiration+0x1be + +Thread: fffff80002bf8c40 +Old irql: 0000000000000002 +New irql: 0000000000000002 +Processor: 0000000000000000 +Time stamp: 000000000000495e + + fffff88004205f3a USBPORT!USBPORT_AcquireEpListLock+0x2e + fffff880042172df USBPORT!USBPORT_Core_TimeoutAllTransfers+0x1f + fffff8800420f2ca USBPORT!USBPORT_DM_IoTimerDpc+0x9a + fffff80002a5b5bf nt!IopTimerDispatch+0x132 + fffff80002a7c29e nt!KiProcessTimerDpcTable+0x66 + +Thread: fffff80002bf8c40 +Old irql: 0000000000000002 +New irql: 0000000000000002 +Processor: 0000000000000000 +Time stamp: 000000000000495e + + fffff88004201694 USBPORT!MPf_CheckController+0x4c + fffff8800420f26a USBPORT!USBPORT_DM_IoTimerDpc+0x3a + fffff80002a5b5bf nt!IopTimerDispatch+0x132 + fffff80002a7c29e nt!KiProcessTimerDpcTable+0x66 + fffff80002a7bdd6 nt!KiProcessExpiredTimerList+0xc6 + +Thread: fffff80002bf8c40 +Old irql: 0000000000000002 +New irql: 0000000000000002 +Processor: 0000000000000000 +Time stamp: 000000000000495e + + fffff8800420167c USBPORT!MPf_CheckController+0x34 + fffff8800420f26a USBPORT!USBPORT_DM_IoTimerDpc+0x3a + fffff80002a5b5bf nt!IopTimerDispatch+0x132 + fffff80002a7c29e nt!KiProcessTimerDpcTable+0x66 + fffff80002a7bdd6 nt!KiProcessExpiredTimerList+0xc6 +``` + +Here is an example of the **!verifier** extension on a Windows Vista computer with bit 7 turned on and *Address* specified. + +``` +0: kd> !verifier 80 a2b1cf20 +# Parsing 00004000 array entries, searching for address a2b1cf20. + +Pool block a2b1ce98, Size 00000168, Thread a2b1ce98 +808f1be6 ndis!ndisFreeToNPagedPool+0x39 +808f11c1 ndis!ndisPplFree+0x47 +808f100f ndis!NdisFreeNetBufferList+0x3b +8088db41 NETIO!NetioFreeNetBufferAndNetBufferList+0xe +8c588d68 tcpip!UdpEndSendMessages+0xdf +8c588cb5 tcpip!UdpSendMessagesDatagramsComplete+0x22 +8088d622 NETIO!NetioDereferenceNetBufferListChain+0xcf +8c5954ea tcpip!FlSendNetBufferListChainComplete+0x1c +809b2370 ndis!ndisMSendCompleteNetBufferListsInternal+0x67 +808f1781 ndis!NdisFSendNetBufferListsComplete+0x1a +8c04c68e pacer!PcFilterSendNetBufferListsComplete+0xb2 +809b230c ndis!NdisMSendNetBufferListsComplete+0x70 +# 8ac4a8ba test1!HandleCompletedTxPacket+0xea + +Pool block a2b1ce98, Size 00000164, Thread a2b1ce98 +822af87f nt!VerifierExAllocatePoolWithTagPriority+0x5d +808f1c88 ndis!ndisAllocateFromNPagedPool+0x1d +808f11f3 ndis!ndisPplAllocate+0x60 +808f1257 ndis!NdisAllocateNetBufferList+0x26 +80890933 NETIO!NetioAllocateAndReferenceNetBufferListNetBufferMdlAndData+0x14 +8c5889c2 tcpip!UdpSendMessages+0x503 +8c05c565 afd!AfdTLSendMessages+0x27 +8c07a087 afd!AfdTLFastDgramSend+0x7d +8c079f82 afd!AfdFastDatagramSend+0x5ae +8c06f3ea afd!AfdFastIoDeviceControl+0x3c1 +8217474f nt!IopXxxControlFile+0x268 +821797a1 nt!NtDeviceIoControlFile+0x2a +8204d16a nt!KiFastCallEntry+0x127 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!verifier%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-version.md b/windows-driver-docs-pr/debugger/-version.md new file mode 100644 index 0000000000..0608a12ecb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-version.md @@ -0,0 +1,57 @@ +--- +title: version +description: The version extension displays the version information for the extension DLL.This extension command should not be confused with the version (Show Debugger Version) command. +ms.assetid: b6ca4b8c-d673-40c5-890f-3b92fbb99fae +keywords: ["version Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- version +api_type: +- NA +--- + +# !version + + +The **!version** extension displays the version information for the extension DLL. + +This extension command should not be confused with the [**version (Show Debugger Version)**](version--show-debugger-version-.md) command. + +``` +![ExtensionDLL.]version +``` + +## Parameters + + + *ExtensionDLL* +Specifies the extension DLL whose version number is to be displayed. + +### DLL + +This extension is available in most extension DLLs. + +Remarks +------- + +If the extension DLL version does not match the debugger version, error messages will be displayed. + +This extension command will not work on Windows XP and later versions of Windows. To display version information, use the [**version (Show Debugger Version)**](version--show-debugger-version-.md) command. + +The original purpose of this extension was to ensure that the DLL version matched the target version, since a mismatch would result in inaccurate results for many extensions. Newer DLLs are no longer restricted to working with only one version of Windows, so this extension is obsolete. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!version%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vm.md b/windows-driver-docs-pr/debugger/-vm.md new file mode 100644 index 0000000000..006f237f09 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vm.md @@ -0,0 +1,160 @@ +--- +title: vm +description: The vm extension displays summary information about virtual memory use statistics on the target system. +ms.assetid: 25e4f80c-d4ca-407c-991d-e8ee5dfbb309 +keywords: ["vm Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vm +api_type: +- NA +--- + +# !vm + + +The **!vm** extension displays summary information about virtual memory use statistics on the target system. + +``` +!vm [Flags] +``` + +## Parameters + + + *Flags* +Specifies what information will be displayed in the output from this command. This can be any sum of the following bits. The default is 0, which causes the display to include system-wide virtual memory statistics as well as memory statistics for each process. + +Bit 0 (0x1) +Causes the display to omit process-specific statistics. + +Bit 1 (0x2) +Causes the display to include memory management thread stacks. + +Bit 2 (0x4) +(Windows XP and later) Causes the display to include terminal server memory usage. + +Bit 3 (0x8) +(Windows XP and later) Causes the display to include the page file write log. + +Bit 4 (0x10) +(Windows XP and later) Causes the display to include working set owner thread stacks. + +Bit 5 (0x20) +(Windows Vista and later) Causes the display to include kernel virtual address usage. + +### Environment + +| | | +|-------|------------------| +| Modes | kernel mode only | + +  + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +The [**!memusage**](-memusage.md) extension command can be used to analyze physical memory usage. For more information about memory management, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Here is an example of the short output produced when *Flags* is 1: + +``` +kd> !vm 1 + +*** Virtual Memory Usage *** + Physical Memory: 16270 ( 65080 Kb) + Page File: \??\E:\pagefile.sys + Current: 98304Kb Free Space: 61044Kb + Minimum: 98304Kb Maximum: 196608Kb + Available Pages: 5543 ( 22172 Kb) + ResAvail Pages: 6759 ( 27036 Kb) + Locked IO Pages: 112 ( 448 Kb) + Free System PTEs: 45089 ( 180356 Kb) + Free NP PTEs: 5145 ( 20580 Kb) + Free Special NP: 336 ( 1344 Kb) + Modified Pages: 714 ( 2856 Kb) + NonPagedPool Usage: 877 ( 3508 Kb) + NonPagedPool Max: 6252 ( 25008 Kb) + PagedPool 0 Usage: 729 ( 2916 Kb) + PagedPool 1 Usage: 432 ( 1728 Kb) + PagedPool 2 Usage: 436 ( 1744 Kb) + PagedPool Usage: 1597 ( 6388 Kb) + PagedPool Maximum: 13312 ( 53248 Kb) + Shared Commit: 1097 ( 4388 Kb) + Special Pool: 229 ( 916 Kb) + Shared Process: 1956 ( 7824 Kb) + PagedPool Commit: 1597 ( 6388 Kb) + Driver Commit: 828 ( 3312 Kb) + Committed pages: 21949 ( 87796 Kb) + Commit limit: 36256 ( 145024 Kb) +``` + +All memory use is listed in pages and in kilobytes. The most useful information in this display is the following: + + ++++ + + + + + + + + + + + + + + + + + + + + +
ParameterMeaning

physical memory

Total physical memory in the system.

available pages

Number of pages of memory available on the system, both virtual and physical.

nonpaged pool usage

The amount of pages allocated to the nonpaged pool. The nonpaged pool is memory that cannot be swapped out to the paging file, so it must always occupy physical memory. If this number is too large, this is usually an indication that there is a memory leak somewhere in the system.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vm%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vpb.md b/windows-driver-docs-pr/debugger/-vpb.md new file mode 100644 index 0000000000..f971606d3a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vpb.md @@ -0,0 +1,123 @@ +--- +title: vpb +description: The vpb extension displays a volume parameter block (VPB). +ms.assetid: 978d4ec8-6141-4656-9e5c-266de91c9440 +keywords: ["vpb Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vpb +api_type: +- NA +--- + +# !vpb + + +The **!vpb** extension displays a volume parameter block (VPB). + +``` +!vpb Address +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address of the VPB. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Kdexts.dll

+ +  + +### Additional Information + +For information about VPBs, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +Here is an example. First, the device tree is displayed with the [**!devnode**](-devnode.md) extension: + +``` +kd> !devnode 0 1 +Dumping IopRootDeviceNode (= 0x80e203b8) +DevNode 0x80e203b8 for PDO 0x80e204f8 + InstancePath is "HTREE\ROOT\0" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0x80e56dc8 for PDO 0x80e56f18 + InstancePath is "Root\dmio\0000" + ServiceName is "dmio" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0x80e56ae8 for PDO 0x80e56c38 + InstancePath is "Root\ftdisk\0000" + ServiceName is "ftdisk" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0x80e152a0 for PDO 0x80e15cb8 + InstancePath is "STORAGE\Volume\1&30a96598&0&Signature5C34D70COffset7E00Length60170A00" + ServiceName is "VolSnap" + TargetDeviceNotify List - f 0xe1250938 b 0xe14b9198 + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + ..... +``` + +The last device node listed is a volume. Examine its physical device object (PDO) with the [**!devobj**](-devobj.md) extension: + +``` +kd> !devobj 80e15cb8 +Device object (80e15cb8) is for: + HarddiskVolume1 \Driver\Ftdisk DriverObject 80e4e248 +Current Irp 00000000 RefCount 14 Type 00000007 Flags 00001050 +Vpb 80e15c30 DevExt 80e15d70 DevObjExt 80e15e40 Dope 80e15bd8 DevNode 80e152a0 +ExtensionFlags (0000000000) +AttachedDevice (Upper) 80e14c60 \Driver\VolSnap +Device queue is not busy. +``` + +The address of this device's VPB is included in this listing. Use this address with the **!vpb** extension: + +``` +kd> !vpb 80e15c30 +Vpb at 0x80e15c30 +Flags: 0x1 mounted +DeviceObject: 0x80de5020 +RealDevice: 0x80e15cb8 +RefCount: 14 +Volume Label: MY-DISK-C +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vpb%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vpdd.md b/windows-driver-docs-pr/debugger/-vpdd.md new file mode 100644 index 0000000000..d212b57d5e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vpdd.md @@ -0,0 +1,20 @@ +--- +title: vpdd +description: vpdd +ms.assetid: 9edd884a-f969-4479-8e08-2ddb205fedb4 +--- + +# !vpdd + + +The **!vpdd** extension is obsolete. Use [**!vtop**](-vtop.md) or [**!ptov**](-ptov.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vpdd%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vprot.md b/windows-driver-docs-pr/debugger/-vprot.md new file mode 100644 index 0000000000..8d06f948bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vprot.md @@ -0,0 +1,93 @@ +--- +title: vprot +description: The vprot extension displays virtual memory protection information. +ms.assetid: 7ee863ef-abfd-4ee7-9bac-34472e60f3fa +keywords: ["memory, memory protection", "vprot Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vprot +api_type: +- NA +--- + +# !vprot + + +The **!vprot** extension displays virtual memory protection information. + +``` +!vprot [Address] +``` + +## Parameters + + + *Address* +Specifies the hexadecimal address whose memory protection status is to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

+Uext.dll +Ntsdexts.dll

Windows XP and later

Uext.dll

+ +  + +### Additional Information + +To view memory protection information for all memory ranges owned by the target process, use [**!vadump**](-vadump.md). For information about memory protection, see *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +The **!vprot** extension command can be used for both live debugging and dump file debugging. + +Here is an example: + +``` +0:000> !vprot 30c191c +BaseAddress: 030c1000 +AllocationBase: 030c0000 +AllocationProtect: 00000080 PAGE_EXECUTE_WRITECOPY +RegionSize: 00011000 +State: 00001000 MEM_COMMIT +Protect: 00000010 PAGE_EXECUTE +Type: 01000000 MEM_IMAGE +``` + +In this display, the AllocationProtect line shows the default protection that the entire region was created with. Note that individual addresses within this region can have their protection altered after memory is allocated (for example, if **VirtualProtect** is called). The Protect line shows the actual protection for this specific address. The possible protection values are PAGE\_NOACCESS, PAGE\_READONLY, PAGE\_READWRITE, PAGE\_EXECUTE, PAGE\_EXECUTE\_READ, PAGE\_EXECUTE\_READWRITE, PAGE\_WRITECOPY, PAGE\_EXECUTE\_WRITECOPY, and PAGE\_GUARD. + +The State line also applies to the specific virtual address passed to **!vprot**. The possible state values are MEM\_COMMIT, MEM\_FREE, and MEM\_RESERVE. + +The Type line shows the memory type. The possible values are MEM\_IMAGE, MEM\_MAPPED, and MEM\_PRIVATE. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vprot%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-vtop.md b/windows-driver-docs-pr/debugger/-vtop.md new file mode 100644 index 0000000000..5549d1c17d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-vtop.md @@ -0,0 +1,104 @@ +--- +title: vtop +description: The vtop extension converts a virtual address to the corresponding physical address, and displays other page table and page directory information. +ms.assetid: 41f4accc-3eb9-4406-a6cc-a05022166e14 +keywords: ["vtop Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vtop +api_type: +- NA +--- + +# !vtop + + +The **!vtop** extension converts a virtual address to the corresponding physical address, and displays other page table and page directory information. + +Syntax + +``` +!vtop PFN VirtualAddress +!vtop 0 VirtualAddress +``` + +## Parameters + + + *DirBase* +Specifies the directory base for the process. Each process has its own virtual address space. Use the [**!process**](-process.md) extension to determine the directory base for a process. + + *PFN* +Specifies the page frame number (PFN) of the directory base for the process. + + **0** +Causes **!vtop** to use the current [process context](changing-contexts.md#process-context) for address translation. + + *VirtualAddress* +Specifies the virtual address whose page is desired. + +### DLL + +Kdexts.dll + +### Additional Information + +For other methods of achieving these results, see [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md). Also see [**!ptov**](-ptov.md). For information about page tables and page directories, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. + +Remarks +------- + +To use this command, first use the [**!process**](-process.md) extension to determine the directory base of the process. The page frame number (PFN) of this directory base can be found by removing the three trailing hexadecimal zeros (in other words, by right-shifting the number 12 bits). + +Here is an example: + +``` +kd> !process 0 0 +**** NT ACTIVE PROCESS DUMP **** +.... +PROCESS ff779190 SessionId: 0 Cid: 04fc Peb: 7ffdf000 ParentCid: 0394 + DirBase: 098fd000 ObjectTable: e1646b30 TableSize: 8. + Image: MyApp.exe +``` + +Since the directory base is 0x098FD000, its PFN is 0x098FD. + +``` +kd> !vtop 98fd 12f980 +Pdi 0 Pti 12f +0012f980 09de9000 pfn(09de9) +``` + +Notice how the trailing three zeros are optional. The **!vtop** extension displays the page directory index (PDI), the page table index (PTI), the virtual address that you had originally input, the physical address of the beginning of the physical page, and the page frame number (PFN) of the page table entry (PTE). + +If you want to convert the virtual address 0x0012F980 to a physical address, you simply have to take the last three hexadecimal digits (0x980) and add them to the physical address of the beginning of the page (0x09DE9000). This gives the physical address 0x09DE9980. + +If you forget to remove the three zeros, and pass the full directory base to **!vtop** instead of the PFN, the results will usually be correct. This is because when **!vtop** receives a number too large to be a PFN, it right-shifts it twelve bits and uses that number instead: + +``` +kd> !vtop 98fd 12f980 +Pdi 0 Pti 12f +0012f980 09de9000 pfn(09de9) + +kd> !vtop 98fd000 12f980 +Pdi 0 Pti 12f +0012f980 09de9000 pfn(09de9) +``` + +However, it is better to always use the PFN, because some directory base values will not be converted in this manner. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!vtop%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wake--wake-debugger-.md b/windows-driver-docs-pr/debugger/-wake--wake-debugger-.md new file mode 100644 index 0000000000..6ae5b747da --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wake--wake-debugger-.md @@ -0,0 +1,80 @@ +--- +title: .wake (Wake Debugger) +description: The .wake command causes sleep mode to end. This command is used only when you are controlling the user-mode debugger from the kernel debugger. +ms.assetid: 01aead7e-1f46-46cf-a697-ab5ff6329ac7 +keywords: ["Wake Debugger (.wake) command", "controlling the user-mode debugger from the kernel debugger, Wake Debugger (.wake) command", ".wake (Wake Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .wake (Wake Debugger) +api_type: +- NA +--- + +# .wake (Wake Debugger) + + +The **.wake** command causes sleep mode to end. This command is used only when you are controlling the user-mode debugger from the kernel debugger. + +``` +.wake PID +``` + +## Parameters + + + *PID* +The process ID of the user-mode debugger. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

controlling the user-mode debugger from the kernel debugger

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For more details, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). For information about how to find the process ID of the debugger, see [Finding the Process ID](finding-the-process-id.md). + +Remarks +------- + +When you are controlling the user-mode debugger from the kernel debugger and the system is in sleep mode, this command can be used to wake up the debugger before the sleep timer runs out. + +This command is not issued in the user-mode debugger on the target machine, nor in the kernel debugger on the host machine. It must be issued from a third debugger (KD, CDB, or NTSD) running on the target machine. + +This debugger can be started expressly for this purpose, or can be another debugger that happens to be running. However, if there is no other debugger already running, it is easier just to use CDB with the **-wake** [**command-line option**](cdb-command-line-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.wake%20%28Wake%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-help.md b/windows-driver-docs-pr/debugger/-wdfkd-help.md new file mode 100644 index 0000000000..10df646174 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-help.md @@ -0,0 +1,46 @@ +--- +title: wdfkd.help +description: The wdfkd.help extension displays help information about all Wdfkd.dll extension commands. +ms.assetid: 5b1e0398-8924-4be6-b6ac-97fb0ce43f0b +keywords: ["wdfkd.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.help +api_type: +- NA +--- + +# !wdfkd.help + + +The **!wdfkd.help** extension displays help information about all Wdfkd.dll extension commands. + +``` +!wdfkd.help +``` + +### DLL + +Wdfkd.dll + +### Additional Information + +The **!wdfkd.help** extension is equivalent to the [**!wdfkd.wdfhelp**](-wdfkd-wdfhelp.md) extension. + +For more information about debugging framework-based drivers, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfchildlist.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfchildlist.md new file mode 100644 index 0000000000..8bf86d14e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfchildlist.md @@ -0,0 +1,85 @@ +--- +title: wdfkd.wdfchildlist +description: The wdfkd.wdfchildlist extension displays a child list's state and information about all of the device identification descriptions that are in the child list. +ms.assetid: b224e898-0e49-431e-a748-ea12ff3b3513 +keywords: ["wdfkd.wdfchildlist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfchildlist +api_type: +- NA +--- + +# !wdfkd.wdfchildlist + + +The **!wdfkd.wdfchildlist** extension displays a child list's state and information about all of the device identification descriptions that are in the child list. + +``` +!wdfkd.wdfchildlist Handle +``` + +## Parameters + + + *Handle* +A WDFCHILDLIST-typed handle to the child list. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example shows a **!wdfkd.wdfchildlist** display. + +``` +kd> !wdfchildlist 0x7cc090c8 + +## Dumping WDFCHILDLIST 0x7cc090c8 +--------------------------------------- +owning !WDFDEVICE 0x7ca7b1c0 +ID description size 0x8 + +State: +----- +List is unlocked, changes will be applied immediately +No scans or enumerations are active on the list + +Descriptions: +------------ + PDO !WDFDEVICE 0x7cad31c8, ID description 0x83ac4ff4 + +Device WDM !devobj 0x81fb00e8, WDF pnp state WdfDevStatePnpStarted (0x119) + +Device found in last scan + +No pending insertions are in the list. + +Callbacks: +--------- + EvtChildListCreateDevice: wdfrawbusenumtest!RawBus_RawPdo_Create (f22263b0) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfchildlist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfcollection.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfcollection.md new file mode 100644 index 0000000000..28a148cf00 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfcollection.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfcollection +description: The wdfkd.wdfcollection extension displays all of the objects that are stored in a WDFCOLLECTION structure. +ms.assetid: 095bc37d-214a-4f00-9e44-5ce6009d6636 +keywords: ["wdfkd.wdfcollection Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfcollection +api_type: +- NA +--- + +# !wdfkd.wdfcollection + + +The **!wdfkd.wdfcollection** extension displays all of the objects that are stored in a WDFCOLLECTION structure. + +``` +!wdfkd.wdfcollection Handle +``` + +## Parameters + + + *Handle* +A WDFCOLLECTION-typed handle to the structure. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfcollection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfcommonbuffer.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfcommonbuffer.md new file mode 100644 index 0000000000..a51e878dd9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfcommonbuffer.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfcommonbuffer +description: The wdfkd.wdfcommonbuffer extension displays information about a WDF common buffer object. +ms.assetid: 961c2802-1a32-4fbf-bd64-12a7f1557a62 +keywords: ["wdfkd.wdfcommonbuffer Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfcommonbuffer +api_type: +- NA +--- + +# !wdfkd.wdfcommonbuffer + + +The **!wdfkd.wdfcommonbuffer** extension displays information about a WDF common buffer object. + +``` +!wdfkd.wdfcommonbuffer Handle +``` + +## Parameters + + + *Handle* +A handle to a framework common buffer object (WDFCOMMONBUFFER). + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfcommonbuffer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfcrashdump.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfcrashdump.md new file mode 100644 index 0000000000..84b8de389a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfcrashdump.md @@ -0,0 +1,145 @@ +--- +title: wdfkd.wdfcrashdump +description: The wdfkd.wdfcrashdump extension displays error log information and other crash dump information from a minidump file, if the data is present. +ms.assetid: 419c76b1-e291-4503-8c59-aa46140e40b3 +keywords: ["wdfkd.wdfcrashdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfcrashdump +api_type: +- NA +--- + +# !wdfkd.wdfcrashdump + + +The **!wdfkd.wdfcrashdump** extension displays error log information and other crash dump information from a minidump file, if the data is present. + +KMDF + +``` +!wdfkd.wdfcrashdump [InfoType] +``` + +UMDF + +``` +!wdfkd.wdfcrashdump [DriverName.dll][-d | -f | -m] +``` + +## Parameters + + + *InfoType* +Specifies the kind of information to display. *InfoType* is optional and can be any one of the following values: + +**log** +Displays error log information, if available in the crash dump file. This is the default value. + +**loader** +Displays the minidump's dynamic-bound drivers. + +*DriverName*.dll +Specifies the name of a UMDF driver. You must include the .dll file suffix. If this optional parameter is omitted, output includes metadata, the loaded module list, and available logs. + +**-d** +Displays only the driver logs. + +**-f** +Displays only the framework logs. + +**-m** +Merges framework and driver logs in their recorded order. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF + +UMDF 2.15 + +Remarks +------- + +This example shows how to use **!wdfkd.wdfcrashdump** to view information about KMDF drivers. If you specify **loader** for *InfoType*, the output includes dynamic-bound drivers in the minidump file. + +``` +0: kd> !wdfcrashdump loader +Retrieving crashdump loader information... +## Local buffer 0x002B4D00, bufferSize 720 +---------------------------------------------- + ImageName Version FxGlobals + + Wdf01000 v1.9(6902) + msisadrv v1.9(6913) 0x84deb260 + vdrvroot v1.9(6913) 0x860e8260 + storflt v1.5(6000) 0x861dfe90 + cdrom v1.9(6913) 0x84dca008 + intelppm v1.9(6913) 0x864704a8 + HDAudBus v1.7(6001) 0x86101c98 + 1394ohci v1.7(6001) 0x8610d2e8 + CompositeBus v1.9(6913) 0x86505b98 + ObjTestClassExt v1.9(6902) 0x865b7f00 + mqfilter v1.9(6902) 0x865b8008 + mqueue v1.9(6902) 0x865b6910 + umbus v1.9(6913) 0x8618aea0 + monitor v1.9(6913) 0x86aac1d8 + PEAUTH v1.5(6000) 0x854e5350 +---------------------------------------------- +``` + +This example shows how to use **!wdfkd.wdfcrashdump** to view information about UMDF drivers. If you issue **!wdfkd.wdfcrashdump** with no parameters, the output includes the driver that caused the crash and a list of all loaded drivers in the host process that failed. You can click on drivers in this list that have associated logs. + +``` +0:001> !wdfkd.wdfcrashdump +Opening minidump at location C:\temp\WudfHost_ext__1312.dmp + +Faulting driver: wpptest.dll +Failure type: Unhandled Exception (WUDFUnhandledException) +Faulting thread ID: 2840 + +Listing all drivers loaded in this host process at the time of the failure: + + ServiceName + wpptest + CoverageCx0102 + coverage + WUDFVhidmini + ToastMon + WUDFOsrUsbFilter +``` + +In the example above, output includes failure type, which is the event type in the WER report. Here, it can be **WUDFVerifierFailure** or **WUDFUnhandledException**. For more information, see [Accessing UMDF Metadata in WER Reports](https://msdn.microsoft.com/library/windows/hardware/ff542975). The output for UMDF includes an error code, if event type is **WUDFVerifierFailure**. + +To display the framework's error log records from a [complete memory dump](complete-memory-dump.md), a [kernel memory dump](kernel-memory-dump.md), or a [live kernel-mode target](live-kernel-mode-targets.md), you can also try the [**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) extension. + +**Additional Information** + +For information about enabling the inflight trace recorder for your driver, see [Using Inflight Trace Recorder (IFR) in KMDF and UMDF 2 Drivers](https://msdn.microsoft.com/library/windows/hardware/dn940485). For more information about debugging WDF drivers, see [Debugging WDF Drivers](https://msdn.microsoft.com/library/windows/hardware/ff540790). For information about KMDF debugging, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +## See also + + +[**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) + +[**!wdfkd.wdfsettraceprefix**](-wdfkd-wdfsettraceprefix.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfcrashdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdevext.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevext.md new file mode 100644 index 0000000000..349085d13f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevext.md @@ -0,0 +1,111 @@ +--- +title: wdfkd.wdfdevext +description: The wdfkd.wdfdevext extension displays information that is associated with the DeviceExtension member of a Microsoft Windows Driver Model (WDM) DEVICE_OBJECT structure. +ms.assetid: 89559cae-7323-4c91-b20a-7d42069cdb93 +keywords: ["wdfkd.wdfdevext Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdevext +api_type: +- NA +--- + +# !wdfkd.wdfdevext + + +The **!wdfkd.wdfdevext** extension displays information that is associated with the **DeviceExtension** member of a Microsoft Windows Driver Model (WDM) DEVICE\_OBJECT structure. + +``` +!wdfkd.wdfdevext DeviceExtension +``` + +## Parameters + + + *DeviceExtension* +A pointer to a device extension. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +Here is an example for HdAudBus.sys, which is a KMDF driver. Use [**!devnode**](-devnode.md) to find a device node that has HdAudBus as its function driver. Take the physical device object (PDO) from the output and pass it to [**!devstack**](-devstack.md). Take the device extension address from the output of **!devstack** and pass it to **!wdfdevext**. + +``` +0: kd> !devnode 0 1 hdaudbus +Dumping IopRootDeviceNode (= 0xffffe000002cfd30) +DevNode 0xffffe000009b7a50 for PDO 0xffffe00000226880 + InstancePath is "PCI\VEN_8086&DEV_293E&SUBSYS_2819103C&REV_02\3&33fd14ca&0&D8" + ServiceName is "HDAudBus" + ... +0: kd> !devstack 0xffffe00000226880 + !DevObj !DrvObj !DevExt ObjectName + ffffe00001351e20 \Driver\HDAudBus ffffe000009a3c00 +> ffffe00000226880 \Driver\pci ffffe000002269d0 NTPNP_PCI0009 +!DevNode ffffe000009b7a50 : + DeviceInst is "PCI\VEN_8086&DEV_293E&SUBSYS_2819103C&REV_02\3&33fd14ca&0&D8" + ServiceName is "HDAudBus" +0: kd> * +0: kd> !wdfdevext ffffe000009a3c00 +Device context is 0xffffe000009a3c00 + context: dt 0xffffe000009a3c00 HDAudBus!HDAudioDeviceExtension (size is 0xa8 bytes) + EvtCleanupCallback fffff80001f35950 HDAudBus!HdAudBusEvtDeviceCleanupCallback + +!wdfdevice 0x00001fffff65c6e8 +!wdfobject 0xffffe000009a3910 +``` + +Here is an example for Wudfrd.sys, which is the function driver for the kernel-mode portion of a UMDF 2 driver stack. Use [**!devnode**](-devnode.md) to find a device node that has Wudfrd as its function driver. Take the physical device object (PDO) from the output and pass it to [**!devstack**](-devstack.md). Take the device extension address from the output of **!devstack** and pass it to **!wdfdevext**. + +``` +0: kd> !devnode 0 1 wudfrd +Dumping IopRootDeviceNode (= 0xffffe000002cfd30) +DevNode 0xffffe00000a1e530 for PDO 0xffffe00000b15b00 + InstancePath is "ROOT\SAMPLE\0001" + ServiceName is "WUDFRd" + ... +0: kd> !devstack 0xffffe00000b15b00 + !DevObj !DrvObj !DevExt ObjectName + ffffe00000c11040 \Driver\WUDFRd ffffe00000c11190 +> ffffe00000b15b00 \Driver\PnpManager 00000000 00000052 +!DevNode ffffe00000a1e530 : + DeviceInst is "ROOT\SAMPLE\0001" + ServiceName is "WUDFRd" +0: kd> * +0: kd> !wdfdevext ffffe00000c11190 +## Device context is 0xffffe00000c11190 + +## UMDF Device Instances for this Redirector extension + + DriverManagerProcess: 0xffffe00003470500 + + ImageName Ver DevStack HostProcess DeviceID + MyUmdf2Driver.dll v2.0 0x000000a5a3ab5f70 0xffffe00000c32900 \Device\00000052 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdevext%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdevice.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevice.md new file mode 100644 index 0000000000..e149346df6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevice.md @@ -0,0 +1,157 @@ +--- +title: wdfkd.wdfdevice +description: The wdfkd.wdfdevice extension displays information that is associated with a WDFDEVICE-typed object handle. +ms.assetid: c6dd98e5-a0ed-437d-a313-5d8a416105dd +keywords: ["wdfkd.wdfdevice Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdevice +api_type: +- NA +--- + +# !wdfkd.wdfdevice + + +The **!wdfkd.wdfdevice** extension displays information that is associated with a WDFDEVICE-typed object handle. + +``` +!wdfkd.wdfdevice Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a WDFDEVICE-typed object. + + *Flags* +Optional. The kind of information to display. *Flags* can be any combination of the following bits: + +Bit 0 (0x1) +The display will include verbose information about the device, such as the associated WDFCHILDLIST-typed handles, synchronization scope, and execution level. + +Bit 1 (0x2) +The display will include detailed power state information. + +Bit 2 (0x4) +The display will include detailed power policy state information. + +Bit 3 (0x8) +The display will include detailed Plug and Play (PnP) state information. + +Bit 4 (0x10) +The display will include the device object's callback functions. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example uses the **!wdfkd.wdfdevice** extension on a WDFDEVICE handle that represents a physical device object (PDO), without specifying any flags. + +``` +kd> !wdfdevice 0x7cad31c8 + +# Dumping WDFDEVICE 0x7cad31c8 +================================= + +WDM PDEVICE_OBJECTs: self 81fb00e8 + +Pnp state: 119 ( WdfDevStatePnpStarted ) +Power state: 31f ( WdfDevStatePowerDx ) +Power Pol state: 508 ( WdfDevStatePwrPolWaitingUnarmed ) + +Parent WDFDEVICE 7ca7b1c0 +Parent states: + Pnp state: 119 ( WdfDevStatePnpStarted ) + Power state: 307 ( WdfDevStatePowerD0 ) + Power Pol state: 565 ( WdfDevStatePwrPolStarted ) + +No pended pnp or power irps +Device is the power policy owner for the stack +``` + +The following example displays the same device object as the preceding example, but this time with a flag value of 0xF. This flag value, a combination of the bits 0x1, 0x2, 0x4, and 0x8, causes the display to include verbose device information, power state information, power policy state information, and PnP state information. + +``` +kd> !wdfdevice 0x7cad31c8 f + +# Dumping WDFDEVICE 0x7cad31c8 +================================= + +WDM PDEVICE_OBJECTs: self 81fb00e8 + +Pnp state: 119 ( WdfDevStatePnpStarted ) +Power state: 31f ( WdfDevStatePowerDx ) +Power Pol state: 508 ( WdfDevStatePwrPolWaitingUnarmed ) + +Parent WDFDEVICE 7ca7b1c0 +Parent states: + Pnp state: 119 ( WdfDevStatePnpStarted ) + Power state: 307 ( WdfDevStatePowerD0 ) + Power Pol state: 565 ( WdfDevStatePwrPolStarted ) + +No pended pnp or power irps +Device is the power policy owner for the stack + +Pnp state history: +[0] WdfDevStatePnpObjectCreated (0x100) +[1] WdfDevStatePnpInit (0x105) +[2] WdfDevStatePnpInitStarting (0x106) +[3] WdfDevStatePnpHardwareAvailable (0x108) +[4] WdfDevStatePnpEnableInterfaces (0x109) +[5] WdfDevStatePnpStarted (0x119) + +Power state history: +[0] WdfDevStatePowerD0StartingConnectInterrupt (0x310) +[1] WdfDevStatePowerD0StartingDmaEnable (0x311) +[2] WdfDevStatePowerD0StartingStartSelfManagedIo (0x312) +[3] WdfDevStatePowerDecideD0State (0x313) +[4] WdfDevStatePowerD0BusWakeOwner (0x309) +[5] WdfDevStatePowerGotoDx (0x31a) +[6] WdfDevStatePowerGotoDxIoStopped (0x31c) +[7] WdfDevStatePowerDx (0x31f) + +Power policy state history: +[0] WdfDevStatePwrPolStarting (0x501) +[1] WdfDevStatePwrPolStartingSucceeded (0x502) +[2] WdfDevStatePwrPolStartingDecideS0Wake (0x504) +[3] WdfDevStatePwrPolStartedIdleCapable (0x505) +[4] WdfDevStatePwrPolTimerExpiredNoWake (0x506) +[5] WdfDevStatePwrPolTimerExpiredNoWakeCompletePowerDown (0x507) +[6] WdfDevStatePwrPolWaitingUnarmedQueryIdle (0x509) +[7] WdfDevStatePwrPolWaitingUnarmed (0x508) + +WDFCHILDLIST Handles: + !WDFCHILDLIST 0x7ce710c8 + +SyncronizationScope is WdfSynchronizationScopeNone +ExecutionLevel is WdfExecutionLevelDispatch +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdevice%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdeviceinterrupts.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdeviceinterrupts.md new file mode 100644 index 0000000000..5f9e5beb91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdeviceinterrupts.md @@ -0,0 +1,57 @@ +--- +title: wdfkd.wdfdeviceinterrupts +description: The wdfkd.wdfdeviceinterrupts extension displays all the interrupt objects for a specified device handle. +ms.assetid: 4B545593-B34F-4139-819B-2BA609C1824E +keywords: ["wdfkd.wdfdeviceinterrupts Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdeviceinterrupts +api_type: +- NA +--- + +# !wdfkd.wdfdeviceinterrupts + + +The **!wdfkd.wdfdeviceinterrupts** extension displays all the interrupt objects for a specified device handle. + +``` +!wdfkd.wdfdeviceinterrupts Handle +``` + +## Parameters + + + *Handle* +A handle to a WDFDEVICE-typed object. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +KMDF 1, UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdeviceinterrupts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdevicequeues.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevicequeues.md new file mode 100644 index 0000000000..17fdd7c067 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdevicequeues.md @@ -0,0 +1,91 @@ +--- +title: wdfkd.wdfdevicequeues +description: The wdfkd.wdfdevicequeues extension displays information about all of the framework queue objects that belong to a specified device. +ms.assetid: bd0e7fcc-b561-48fb-901a-605e9d647b61 +keywords: ["wdfkd.wdfdevicequeues Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdevicequeues +api_type: +- NA +--- + +# !wdfkd.wdfdevicequeues + + +The **!wdfkd.wdfdevicequeues** extension displays information about all of the framework queue objects that belong to a specified device. + +``` +!wdfkd.wdfdevicequeues Handle +``` + +## Parameters + + + *Handle* +A handle to a WDFDEVICE-typed object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md) and [**!wdfkd.wdfqueue**](-wdfkd-wdfqueue.md). + +Remarks +------- + +The following example shows the display from the **!wdfkd.wdfdevicequeues** extension. + +``` +kd> !wdfdevicequeues 0x7cad31c8 + +# Dumping queues of WDFDEVICE 0x7cad31c8 +===================================== +## Number of queues: 3 +---------------------------------- +Queue: 1 (!wdfqueue 0x7d67d1e8) + Manual, Not power-managed, PowerOn, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone + Number of driver owned requests: 0 + Number of waiting requests: 0 + + +## This is WDF internal queue for create requests. +---------------------------------- +Queue: 2 (!wdfqueue 0x7ce7d1e8) + Parallel, Power-managed, PowerOff, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone + Number of driver owned requests: 0 + Number of waiting requests: 0 + + +## EvtIoDefault: (0xf221fad0) wdfrawbusenumtest!EvtIoQueueDefault +---------------------------------- +Queue: 3 (!wdfqueue 0x7cd671e8) + Parallel, Power-managed, PowerOff, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone + Number of driver owned requests: 0 + Number of waiting requests: 0 + + + EvtIoDeviceControl: (0xf2226ac0) wdfrawbusenumtest!RawBus_RawPdo_EvtDeviceControl +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdevicequeues%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenabler.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenabler.md new file mode 100644 index 0000000000..d4522f4bb8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenabler.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfdmaenabler +description: The wdfkd.wdfdmaenabler extension displays information about a WDF direct memory access (DMA) object, and its transaction and common buffer objects. +ms.assetid: fb1d9106-2a5d-4262-b76f-8bf0c6c611a8 +keywords: ["wdfkd.wdfdmaenabler Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdmaenabler +api_type: +- NA +--- + +# !wdfkd.wdfdmaenabler + + +The **!wdfkd.wdfdmaenabler** extension displays information about a WDF direct memory access (DMA) object, and its transaction and common buffer objects. + +``` +!wdfkd.wdfdmaenabler Handle +``` + +## Parameters + + + *Handle* +A handle to a framework DMA enabler object (WDFDMAENABLER). + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdmaenabler%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenablers.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenablers.md new file mode 100644 index 0000000000..b730fad2b0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmaenablers.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfdmaenablers +description: The wdfkd.wdfdmaenablers extension displays all WDF direct memory access (DMA) objects associated with a specified device object. +ms.assetid: 31b185e7-74d3-4329-b389-37279e5aa75c +keywords: ["wdfkd.wdfdmaenablers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdmaenablers +api_type: +- NA +--- + +# !wdfkd.wdfdmaenablers + + +The **!wdfkd.wdfdmaenablers** extension displays all WDF direct memory access (DMA) objects associated with a specified device object. It also displays their associated transaction and common buffer objects. + +``` +!wdfkd.wdfdmaenablers Handle +``` + +## Parameters + + + *Handle* +A handle to a framework device object (WDFDEVICE). + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdmaenablers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdmatransaction.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmatransaction.md new file mode 100644 index 0000000000..782f1ec61d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdmatransaction.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfdmatransaction +description: The wdfkd.wdfdmatransaction extension displays information about a WDF direct memory access (DMA) transaction object. +ms.assetid: 6d80152b-6e64-4fef-b57e-3ed3f486ae9a +keywords: ["wdfkd.wdfdmatransaction Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdmatransaction +api_type: +- NA +--- + +# !wdfkd.wdfdmatransaction + + +The **!wdfkd.wdfdmatransaction** extension displays information about a WDF direct memory access (DMA) transaction object. + +``` +!wdfkd.wdfdmatransaction Handle +``` + +## Parameters + + + *Handle* +A handle to a framework DMA transaction object (WDFDMATRANSACTION). + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdmatransaction%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfdriverinfo.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfdriverinfo.md new file mode 100644 index 0000000000..cbcfeed303 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfdriverinfo.md @@ -0,0 +1,108 @@ +--- +title: wdfkd.wdfdriverinfo +description: The wdfkd.wdfdriverinfo extension displays information about the specified driver, including its device tree, and version information. +ms.assetid: dc758fd3-1226-46e3-b249-2cf37ef3e539 +keywords: ["wdfkd.wdfdriverinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfdriverinfo +api_type: +- NA +--- + +# !wdfkd.wdfdriverinfo + + +The **!wdfkd.wdfdriverinfo** extension displays information about the specified driver, including its device tree, the version of the Kernel-Mode Driver Framework (KMDF) library that the driver was compiled with, and a list of the framework device objects that the driver created. + +``` +!wdfkd.wdfdriverinfo [DriverName [Flags]] +``` + +## Parameters + + + *DriverName* +Optional. The name of the driver. *DriverName* must not include the .sys file name extension. + + *Flags* +Optional. Flags that specify the kind of information to display. *Flags* can be any combination of the following bits: + +Bit 0 (0x1) +The display will include verifier settings for the driver, and will also include a count of WDF objects. This flag can be combined with bit 6 (0x40) to display internal objects. + +Bit 4 (0x10) +The display will include the KMDF handle hierarchy for the driver. + +Bit 5 (0x20) +The display will include context and callback function information for each handle. This flag is valid only when bit 4 (0x10) is set. + +Bit 6 (0x40) +The display will include additional information for each handle. This flag is valid only when bit 4 (0x10) is set. This flag can be combined with bit 0 (0x1) to display internal objects. + +Bit 7 (0x80) +The handle information will be displayed in a more compact format. + +Bit 8 (0x100) +The display will left align internal type information. This flag is valid only when bit 4 (0x10) is set. + +Bit 9 (0x200) +The display will include handles that the driver potentially leaked. KMDF version 1.1 and later support this flag. This flag is valid only when bit 4 (0x10) is set. + +Bit 10 (0x400) +The display will include the device tree in verbose form. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +If you omit the *DriverName* parameter, the default driver is used. You can display the default driver by using the [**!wdfkd.wdfgetdriver**](-wdfkd-wdfgetdriver.md) extension; you can set the default driver by using the [**!wdfkd.wdfsetdriver**](-wdfkd-wdfsetdriver.md) extension. + +The following example shows the display from the **!wdfkd.wdfdriverinfo** extension. + +``` +## kd> !wdfdriverinfo wdfrawbusenumtest +---------------------------------- +Default driver image name: wdfrawbusenumtest +WDF library image name: Wdf01000 + FxDriverGlobals 0x83b7af18 + WdfBindInfo 0xf22250ec +## Version v1.5 build(1234) +---------------------------------- +WDFDRIVER: 0x7cbc90d0 + + !WDFDEVICE 0x7ca7b1c0 + context: dt 0x83584ff8 ROOT_CONTEXT (size is 0x1 bytes) + + + !WDFDEVICE 0x7cad31c8 + context: dt 0x8352cff0 RAW_PDO_CONTEXT (size is 0xc bytes) + +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfdriverinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfextendwatchdog.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfextendwatchdog.md new file mode 100644 index 0000000000..62dd8be44b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfextendwatchdog.md @@ -0,0 +1,64 @@ +--- +title: wdfkd.wdfextendwatchdog +description: The wdfkd.wdfextendwatchdog extension extends the time-out period (from 10 minutes to 24 hours) of the framework's watchdog timer during power transitions. +ms.assetid: 6feb922f-0016-468c-8dd2-963db6874977 +keywords: ["wdfkd.wdfextendwatchdog Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfextendwatchdog +api_type: +- NA +--- + +# !wdfkd.wdfextendwatchdog + + +The **!wdfkd.wdfextendwatchdog** extension extends the time-out period (from 10 minutes to 24 hours) of the framework's watchdog timer during power transitions. + +``` +!wdfkd.wdfextendwatchdog Handle [Extend] +``` + +## Parameters + + + *Handle* +A handle to a WDFDEVICE-typed object. + + *Extend* +Optional. A value that indicates whether to enable or disable extension of the time-out period. If *Extend* is 0, extension is disabled, and the time-out period is 10 minutes. If *Extend* is 1, extension is enabled and the time-out period is 24 hours. The default value is 1. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The framework starts an internal watchdog timer every time it calls a power policy or power event callback function for a driver that is not power pageable (that is, the DO\_POWER\_PAGABLE bit is clear). If the callback function causes paging I/O and therefore blocks, the operating system hangs because no paging device is available to service the request. + +If the time-out period elapses, the framework issues bug check 0x10D (WDF\_VIOLATION). For details, see [**Bug Check 0x10D**](bug-check-0x10d---wdf-violation.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfextendwatchdog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdffindobjects.md b/windows-driver-docs-pr/debugger/-wdfkd-wdffindobjects.md new file mode 100644 index 0000000000..5769c2c95f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdffindobjects.md @@ -0,0 +1,110 @@ +--- +title: wdfkd.wdffindobjects +description: The wdfkd.wdffindobjects extension searches memory for WDF objects. +ms.assetid: 8c0a4881-9417-481b-82f8-f3510af768a1 +keywords: ["wdfkd.wdffindobjects Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdffindobjects +api_type: +- NA +--- + +# !wdfkd.wdffindobjects + + +The **!wdfkd.wdffindobjects** extension searches memory for WDF objects. + +``` +!wdfkd.wdffindobjects [StartAddress [Flags]] +``` + +## Parameters + + + *StartAddress* +Optional. Specifies the address at which the search must begin. If this is omitted, the search will begin from where the most recent **!wdfkd.wdffindobjects** search ended. + + *Flags* +Optional. Specifies the kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. *Flags* cannot be used unless *StartAddress* is specified. + +Bit 0 (0x1) +Displays verbose output. + +Bit 1 (0x2) +Displays internal type information for each handle. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following examples show the output of the **!wdfkd.wdffindobjects** extension. The 0x1 flag is set in the second example. + +``` +1: kd> !wdffindobjects 0xfffffa600211b668 + Address Value Object + ------------------ ------------------ ------------------ + 0xfffffa600211b668 0x0000000000000008 + 0xfffffa600211b670 0xfffffa8002e7b1f0 !WDFREQUEST 0x0000057ffd184e08 + 0xfffffa600211b678 0x0000000000000004 + 0xfffffa600211b680 0x0000000000000001 + 0xfffffa600211b688 0xfffffa8006aa3640 !WDFUSBPIPE 0x0000057ff955c9b8 + 0xfffffa600211b690 0x0000000000000000 + 0xfffffa600211b698 0xfffff80001e61f78 + 0xfffffa600211b6a0 0x0000000000000010 + 0xfffffa600211b6a8 0x0000000000010286 + 0xfffffa600211b6b0 0xfffffa600211b6c0 + 0xfffffa600211b6b8 0x0000000000000000 + 0xfffffa600211b6c0 0xfffffa8006aa3640 !WDFUSBPIPE 0x0000057ff955c9b8 + 0xfffffa600211b6c8 0x0000057ffd184e08 !WDFREQUEST 0x0000057ffd184e08 + 0xfffffa600211b6d0 0x0000000000000000 + 0xfffffa600211b6d8 0x0000057ffc51ea18 !WDFMEMORY 0x0000057ffc51ea18 + 0xfffffa600211b6e0 0x0000000000000000 + +1: kd> !wdffindobjects 0xfffffa600211b668 1 + Address Value Type Object + ------------------ ------------------ ------ ------------------ + 0xfffffa600211b668 0x0000000000000008 + 0xfffffa600211b670 0xfffffa8002e7b1f0 Object !WDFREQUEST 0x0000057ffd184e08 + 0xfffffa600211b678 0x0000000000000004 + 0xfffffa600211b680 0x0000000000000001 + 0xfffffa600211b688 0xfffffa8006aa3640 Object !WDFUSBPIPE 0x0000057ff955c9b8 + 0xfffffa600211b690 0x0000000000000000 + 0xfffffa600211b698 0xfffff80001e61f78 + 0xfffffa600211b6a0 0x0000000000000010 + 0xfffffa600211b6a8 0x0000000000010286 + 0xfffffa600211b6b0 0xfffffa600211b6c0 + 0xfffffa600211b6b8 0x0000000000000000 + 0xfffffa600211b6c0 0xfffffa8006aa3640 Object !WDFUSBPIPE 0x0000057ff955c9b8 + 0xfffffa600211b6c8 0x0000057ffd184e08 Handle !WDFREQUEST 0x0000057ffd184e08 + 0xfffffa600211b6d0 0x0000000000000000 + 0xfffffa600211b6d8 0x0000057ffc51ea18 Handle !WDFMEMORY 0x0000057ffc51ea18 + 0xfffffa600211b6e0 0x0000000000000000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdffindobjects%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfforwardprogress.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfforwardprogress.md new file mode 100644 index 0000000000..d4333cbf3a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfforwardprogress.md @@ -0,0 +1,124 @@ +--- +title: wdfkd.wdfforwardprogress +description: The wdfkd.wdfforwardprogress extension displays information about the forward progress of a specified framework queue object. +ms.assetid: 3062d914-4fd4-4e33-8cf0-562484380184 +keywords: ["wdfkd.wdfforwardprogress Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfforwardprogress +api_type: +- NA +--- + +# !wdfkd.wdfforwardprogress + + +The **!wdfkd.wdfforwardprogress** extension displays information about the forward progress of a specified framework queue object. + +``` +!wdfkd.wdfforwardprogress Handle +``` + +## Parameters + + + *Handle* +A handle to a framework queue object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information about how to debug Kernel-Mode Driver Framework (KMDF) drivers, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +This extension will succeed only if the specified framework queue object is configured to support forward progress. If this extension is used with other objects, an error message will be displayed. + +The following example shows the display from a **!wdfkd.wdfforwardprogress** extension. + +``` +kd> !wdfkd.wdfforwardprogress 0x79af3250 + +# Dumping forward progress fields for WDFQUEUE 0x79af3250 +================================================= + ForwardProgressReservedPolicy: UseExamine (0x2) + + Total reserved requests: 44 + + Number of available reserved requests in list: 41 + !WDFREQUEST 0x7bcaf4c0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc67eb0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bccf678 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bb6ce40 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7be30a58 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x79af37d0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc7f428 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bbd40f0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd333a8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd241d8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd594e0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd80d10 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x78ea2d50 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x792020f0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc37258 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bbc1fb0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bbc4fb0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7be0cb80 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc84890 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x78acbd18 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bcf1ad8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bead540 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7922c0f0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7a34a0f0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x625195d0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc33640 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bba9f28 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bba44c8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bb77cd8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7a2b89a8 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7a41ab88 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bc7cc88 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd37180 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bca40f0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x64b4af20 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd01a40 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7a25cfb0 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bba9330 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bd14a40 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7bcc0210 (Reserved) !IRP 0x00000000 + !WDFREQUEST 0x7a54eb00 (Reserved) !IRP 0x00000000 + + Number of reserved requests in use: 3 + !WDFREQUEST 0x7bf0ab80 (Reserved) !IRP 0x8438f008 + !WDFREQUEST 0x7bc53ca8 (Reserved) !IRP 0x875f59f0 + !WDFREQUEST 0x7bced8b8 (Reserved) !IRP 0x85c25348 + + Number of undispatched IRP's in list: 0 + + EvtIoReservedResourcesAllocate: (0x9a3f1b70) mqueue!EvtIoAllocateResourcesForReservedRequest + EvtIoExamineIrp: (0x9a3f19d0) mqueue!EvtIoWdmIrpForForwardProgress +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfforwardprogress%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfgetdriver.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfgetdriver.md new file mode 100644 index 0000000000..335b5fc56b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfgetdriver.md @@ -0,0 +1,48 @@ +--- +title: wdfkd.wdfgetdriver +description: The wdfkd.wdfgetdriver extension displays the name of the current default driver. +ms.assetid: 64e5dc37-8fc9-466c-b602-cb85ed8f6ee7 +keywords: ["wdfkd.wdfgetdriver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfgetdriver +api_type: +- NA +--- + +# !wdfkd.wdfgetdriver + + +The **!wdfkd.wdfgetdriver** extension displays the name of the current default driver. + +``` +!wdfkd.wdfgetdriver +``` + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfgetdriver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfhandle.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfhandle.md new file mode 100644 index 0000000000..8470810dfc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfhandle.md @@ -0,0 +1,99 @@ +--- +title: wdfkd.wdfhandle +description: The wdfkd.wdfhandle extension displays information about a specified framework object handle, such as the handle type, object context pointers, and the underlying framework object pointer. +ms.assetid: 9365218e-2647-4e54-baba-8774d4ab3ae1 +keywords: ["wdfkd.wdfhandle Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfhandle +api_type: +- NA +--- + +# !wdfkd.wdfhandle + + +The **!wdfkd.wdfhandle** extension displays information about a specified framework object handle, such as the handle type, object context pointers, and the underlying framework object pointer. + +``` +!wdfkd.wdfhandle Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a framework object. + + *Flags* +Optional. Flags that specify the kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 4 (0x10) +The display will include the subtree of child objects for the specified handle. + +Bit 5 (0x20) +The display will include context and callback function information for the specified handle. This flag is valid only when bit 4 (0x10) is set. + +Bit 6 (0x40) +The display will include additional information for the specified handle. This flag is valid only when bit 4 (0x10) is set. + +Bit 7 (0x80) +The handle information will be displayed in a more compact format. + +Bit 8 (0x100) +The display will left align internal type information. This flag is valid only when bit 4 (0x10) is set. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example shows the output of the **!wdfhandle** extension with bit 4 set in the *Flags* parameter (so the output displays information about the child objects). + +``` +kd> !wdfhandle 0x7ca7b1c0 10 + +handle 0x7ca7b1c0, type is WDFDEVICE + +Contexts: + context: dt 0x83584ff8 ROOT_CONTEXT (size is 0x1 bytes) + + +Child WDFHANDLEs of 0x7ca7b1c0: + WDFDEVICE 0x7ca7b1c0 + WDFCMRESLIST 0x7ccfb058 + WDFCMRESLIST 0x7cadb058 + WDFCHILDLIST 0x7c72f0c8 + WDFCHILDLIST 0x7cc090c8 + WDFIOTARGET 0x7c9630b8 + +!wdfobject 0x83584e38 +``` + +In the preceding example, the input handle refers to a WDFDEVICE object. This particular device object has five child objects--two WDFCMRESLIST objects, two WDFCHILDLIST objects, and one WDFIOTARGET object. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfhandle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfhelp.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfhelp.md new file mode 100644 index 0000000000..78821bd7a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfhelp.md @@ -0,0 +1,49 @@ +--- +title: wdfkd.wdfhelp +description: The wdfkd.wdfhelp extension displays help information about all Wdfkd.dll extension commands. +ms.assetid: fdc47919-7207-4552-93e7-00633f3bfe12 +keywords: ["wdfkd.wdfhelp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfhelp +api_type: +- NA +--- + +# !wdfkd.wdfhelp + + +The **!wdfkd.wdfhelp** extension displays help information about all Wdfkd.dll extension commands. + +``` +!wdfkd.wdfhelp +``` + +### DLL + +Wdfkd.dll + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The **!wdfkd.wdfhelp** extension is equivalent to the [**!wdfkd.help**](-wdfkd-help.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfhelp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfinterrupt.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfinterrupt.md new file mode 100644 index 0000000000..2192ce8c9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfinterrupt.md @@ -0,0 +1,99 @@ +--- +title: wdfkd.wdfinterrupt +description: The wdfkd.wdfinterrupt extension displays information about a WDFINTERRUPT object. +ms.assetid: 3e032095-94fe-41d5-aeed-645d6b544105 +keywords: ["wdfkd.wdfinterrupt Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfinterrupt +api_type: +- NA +--- + +# !wdfkd.wdfinterrupt + + +The **!wdfkd.wdfinterrupt** extension displays information about a WDFINTERRUPT object. + +``` +!wdfkd.wdfinterrupt Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a WDFINTERRUPT object. + + *Flags* +Optional. Specifies the kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 0 (0x1) +Displays the interrupt service routines (ISRs) for the interrupt dispatch table (IDT) associated with this WDFINTERRUPT object. Setting this flag is equivalent to following the **!wdfinterrupt** extension with the [**!idt**](-idt.md) extension. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example shows the output of the **!wdfinterrupt** extension with bit 0 set in the *Flags* parameter (so the output displays information about the IDT). + +``` +kd> !wdfkd.wdfinterrupt 0x7a988698 1 + +# Dumping WDFINTERRUPT 0x7a988698 +========================= + Interrupt Type: Line-based, Connected, Enabled + Vector: 0xa1 (!idt 0xa1) + Irql: 0x9 + Mode: LevelSensitive + Polarity: WdfInterruptPolarityUnknown + ShareDisposition: CmResourceShareShared + FloatingSave: FALSE + Interrupt Priority Policy: WdfIrqPriorityUndefined + Processor Affinity Policy: WdfIrqPolicyOneCloseProcessor + Processor Group: 0 + Processor Affinity: 0x3 + + dt nt!KINTERRUPT 0x8594eb28 + + EvtInterruptIsr: 1394ohci!Interrupt::WdfEvtInterruptIsr (0x8d580552) + EvtInterruptDpc: 1394ohci!Interrupt::WdfEvtInterruptDpc (0x8d580682) + +Dumping IDT: + +a1: 85167a58 ndis!ndisMiniportIsr (KINTERRUPT 85167a00) + Wdf01000!FxInterrupt::_InterruptThunk (KINTERRUPT 85987500) + +To get ISR from KINTERRUPT: + dt nt!KINTERRUPT ServiceContext + dt wdf01000!FxInterrupt m_EvtInterruptIsr +``` + +In the preceding example, the display concludes with two suggested [**dt (Display Type)**](dt--display-type-.md) commands that can be used to display additional data. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfinterrupt%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfiotarget.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfiotarget.md new file mode 100644 index 0000000000..a147e9404f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfiotarget.md @@ -0,0 +1,86 @@ +--- +title: wdfkd.wdfiotarget +description: The wdfkd.wdfiotarget extension displays information about a specified I/O target object. +ms.assetid: 60a864cc-5099-4d8c-8712-1ba48bce1e0f +keywords: ["wdfkd.wdfiotarget Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfiotarget +api_type: +- NA +--- + +# !wdfkd.wdfiotarget + + +The **!wdfkd.wdfiotarget** extension displays information about a specified I/O target object. + +``` +!wdfkd.wdfiotarget Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to an I/O target object. + + *Flags* +Optional. Flags that specify the kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 0 (0x1) +The display will include details for each of the I/O target's pending request objects. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example shows a display from the **!wdfkd.wdfiotarget** extension. + +``` +kd> !wdfiotarget 0x7c9630b8 + +# WDFIOTARGET 8369cf40 +========================= +WDFDEVICE: 0x7ca7b1c0 +Target Device: !devobj 0x81ede5d8 +Target PDO: !devobj 0x822b8a90 + +Type: Instack target +State: WdfIoTargetStarted + +Requests waiting: 0 + +Requests sent: 0 + +Requests sent with ignore-target-state: 0 +``` + +The output in the preceding example includes the address of the I/O target's parent framework device object, along with the addresses of the WDM DEVICE\_OBJECT structures that represent the target driver's device object and the target device's physical device object (PDO). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfiotarget%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfldr.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfldr.md new file mode 100644 index 0000000000..ddb1dc738f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfldr.md @@ -0,0 +1,108 @@ +--- +title: wdfkd.wdfldr +description: The wdfkd.wdfldr extension displays information about the KMDF and UMDF drivers that are currently dynamically bound to the Windows Driver Frameworks. +ms.assetid: 0965632d-922b-4812-9cfb-7663af0e3847 +keywords: ["wdfkd.wdfldr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfldr +api_type: +- NA +--- + +# !wdfkd.wdfldr + + +The **!wdfkd.wdfldr** extension displays information about the drivers that are currently dynamically bound to the Windows Driver Frameworks. This includes both the Kernel-Mode Driver Framework (KMDF) and the User-Mode Driver Framework (UMDF). + +``` +!wdfkd.wdfldr [DriverName] +``` + +## Parameters + + + *DriverName* +The name of a driver, including the filename extension. If you supply a driver name, this command displays detailed information about the one driver. If you do not supply a drive name, this command displays information about all drivers that are bound to the Windows Driver Frameworks. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +Here is an example of the output of **!wdfldr**. + +``` +## 0: kd> !wdfkd.wdfldr + +## KMDF Drivers + +## LoadedModuleList 0xfffff800003b61f8 + +LIBRARY_MODULE 0xffffe0000039f7c0 + Version v1.13 + Service \Registry\Machine\System\CurrentControlSet\Services\Wdf01000 + ImageName Wdf01000.sys + ImageAddress 0xfffff800002e7000 + ImageSize 0xc5000 + Associated Clients: 16 + + ImageName Ver WdfGlobals FxGlobals ImageAddress ImageSize + peauth.sys v1.7 0xffffe00003a95880 0xffffe00003a956e0 0xfffff80002678000 0x000ab000 + monitor.sys v1.11 0xffffe000001abc70 0xffffe000001abad0 0xfffff800022e7000 0x0000e000 + UsbHub3.sys v1.11 0xffffe000028a47b0 0xffffe000028a4610 0xfffff8000220b000 0x00077000 +## ... + +## Total: 1 library loaded + +## UMDF Drivers + + DriverManagerProcess: 0xffffe00003470500 + + ImageName Ver + MyUmdfDriver.dll v1.11 + SomeUmdf2Driver.dll v2.0 + MyUmdf2Driver.dll v2.0 +``` + +Here is another example that supplies a driver name. + +``` +0: kd> !wdfldr MyUmdf2Driver.dll + +Version v2.0 +Service \Registry\Machine\System\CurrentControlSet\Services\MyUmdf2Driver + +## !wdflogdump MyUmdf2Driver.dll + +## UMDF Device Instances using MyUmdf2Driver.dll + +Process DevStack DeviceId +0xffffe00000c32900 a5a3ab5f70 \Device\00000052 !wdfdriverinfo +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfldr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdflogdump.md b/windows-driver-docs-pr/debugger/-wdfkd-wdflogdump.md new file mode 100644 index 0000000000..247ae99b05 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdflogdump.md @@ -0,0 +1,105 @@ +--- +title: wdfkd.wdflogdump +description: The wdfkd.wdflogdump extension displays the WDF In-flight Recorder log records, if available, for a KMDF driver or a UMDF 2 driver. +ms.assetid: da03fafe-4cc8-4da6-9795-828e69e0df20 +keywords: ["wdfkd.wdflogdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdflogdump +api_type: +- NA +--- + +# !wdfkd.wdflogdump + + +The **!wdfkd.wdflogdump** extension displays the WDF In-flight Recorder log records, if available, for a KMDF driver or a UMDF 2 driver. You can use this command with a [complete memory dump](complete-memory-dump.md), a [kernel memory dump](kernel-memory-dump.md), or a [live kernel-mode target](live-kernel-mode-targets.md). + +KMDF + +``` +!wdfkd.wdflogdump [DriverName][WdfDriverGlobals][-d | -f | -a LogAddress] +``` + +UMDF + +``` +!wdfkd.wdflogdump [DriverName.dll][HostProcessId][-d | -f | -m] +``` + +## Parameters + + + *DriverName* +- KMDF: The name of a KMDF driver. The name must not include the .sys filename extension. +- UMDF: The name of a UMDF 2 driver. The name must include the .dll filename extension. + + *Parameter2* +- KMDF: *WdfDriverGlobals* - The address of the *WdfDriverGlobals* structure. You can determine this address by running [**!wdfkd.wdfldr**](-wdfkd-wdfldr.md) and looking for the field labeled "WdfGlobals". Or, you can supply @@(Driver!WdfDriverGlobals) as the address value, where *Driver* is the name of the driver. If any *WdfDriverGlobals* address is supplied, *DriverName* is ignored (although it must nevertheless be supplied). +- UMDF: *HostProcessId* - The process ID of an instance of wudfhost.exe. If you supply the process ID, this command displays the log records for that process. If you do not supply the process ID, this command displays a list of commands in this form: + + **!wdflogdump** *DriverName* **** *ProcessID* + + If a single process can be determined it will automatically be chosen. + + *Options* +KMDF: + +**-d** Displays only the driver logs. + +**-f** Displays only the framework logs. + +**-a** *LogAddress*Displays a specific driver log. If this option is used, the LogAddress must be provided. + +UMDF: + +**-d** Displays only the driver logs. + +**-f** Displays only the framework logs. + +**-m** Merges framework and driver logs in their recorded order. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +Remarks +------- + +If you omit the *DriverName* parameter, the default driver name is used. Use the [**!wdfkd.wdfgetdriver**](-wdfkd-wdfgetdriver.md) extension to display the default driver name, and use the [**!wdfkd.wdfsetdriver**](-wdfkd-wdfsetdriver.md) extension to set the default driver name. + +To display the framework's error log records from a [small memory dump](small-memory-dump.md), use the [**!wdfkd.wdfcrashdump**](-wdfkd-wdfcrashdump.md) extension. + +For information about setting information that the debugger needs to format WPP tracing messages, see [**!wdfkd.wdftmffile**](-wdfkd-wdftmffile.md) and [**!wdfkd.wdfsettraceprefix**](-wdfkd-wdfsettraceprefix.md). + +**Additional Information** + +For information about enabling the inflight trace recorder for your driver, see [Using Inflight Trace Recorder (IFR) in KMDF and UMDF 2 Drivers](https://msdn.microsoft.com/library/windows/hardware/dn940485). For more information about debugging WDF drivers, see [Debugging WDF Drivers](https://msdn.microsoft.com/library/windows/hardware/ff540790). For information about KMDF debugging, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +## See also + + +[**!wdfkd.wdfcrashdump**](-wdfkd-wdfcrashdump.md) + +[**!wdfkd.wdfsettraceprefix**](-wdfkd-wdfsettraceprefix.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdflogdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdflogsave.md b/windows-driver-docs-pr/debugger/-wdfkd-wdflogsave.md new file mode 100644 index 0000000000..9aafa08979 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdflogsave.md @@ -0,0 +1,62 @@ +--- +title: wdfkd.wdflogsave +description: The wdfkd.wdflogsave extension saves the Kernel-Mode Driver Framework (KMDF) error log records for a specified driver to an event trace log (.etl) file that you can view by using TraceView. +ms.assetid: e072d522-a418-4afb-8434-c6355d026770 +keywords: ["wdfkd.wdflogsave Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdflogsave +api_type: +- NA +--- + +# !wdfkd.wdflogsave + + +The **!wdfkd.wdflogsave** extension saves the Kernel-Mode Driver Framework (KMDF) error log records for a specified driver to an event trace log (.etl) file that you can view by using TraceView. + +``` +!wdfkd.wdflogsave [DriverName [FileName]] +``` + +## Parameters + + + *DriverName* +Optional. The name of a driver. *DriverName* must not include the .sys file name extension. + + *FileName* +Optional. The name of the file to which the KMDF error log records should be saved. *FileName* should not include the .etl file name extension. If you omit *FileName*, the KMDF error log records are saved to the DriverName.etl file. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +If you omit the *DriverName* parameter, the default driver name is used. Use the [**!wdfkd.wdfgetdriver**](-wdfkd-wdfgetdriver.md) extension to display the default driver name, and use the [**!wdfkd.wdfsetdriver**](-wdfkd-wdfsetdriver.md) extension to set the default driver name. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdflogsave%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfmemory.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfmemory.md new file mode 100644 index 0000000000..a324e21f87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfmemory.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfmemory +description: The wdfkd.wdfmemory extension displays the address and size of the buffer that is associated with a framework memory object. +ms.assetid: c0f8cc6c-03bf-4b00-8b0b-89d1b5357765 +keywords: ["wdfkd.wdfmemory Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfmemory +api_type: +- NA +--- + +# !wdfkd.wdfmemory + + +The **!wdfkd.wdfmemory** extension displays the address and size of the buffer that is associated with a framework memory object. + +``` +!wdfkd.wdfmemory Handle +``` + +## Parameters + + + *Handle* +A handle to a framework memory object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfmemory%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfobject.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfobject.md new file mode 100644 index 0000000000..29dc1b2c7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfobject.md @@ -0,0 +1,80 @@ +--- +title: wdfkd.wdfobject +description: The wdfkd.wdfobject extension displays information about a specified framework object. +ms.assetid: fee1b924-5437-4d15-b39c-4d0f6eba0a90 +keywords: ["wdfkd.wdfobject Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfobject +api_type: +- NA +--- + +# !wdfkd.wdfobject + + +The **!wdfkd.wdfobject** extension displays information about a specified framework object. + +``` +!wdfkd.wdfobject FrameworkObject +``` + +## Parameters + + + *FrameworkObject* +A pointer to a framework object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +If the Kernel-Mode Driver Framework (KMDF) verifier is enabled for a driver and the public handle type was marked for tracking, the display from the **!wdfkd.wdfobject** extension includes the tag tracker (that is, the tracking object), as in the following example. + +``` +kd> !wdfobject 0x83584e38 + +The type for object 0x83584e38 is FxDevice +State: FxObjectStateCreated (0x1) + +!wdfhandle 0x7ca7b1c0 + +dt FxDevice 0x83584e38 + + context: dt 0x83584ff8 ROOT_CONTEXT (size is 0x1 bytes) + + +Object debug extension 83584e20 + !wdftagtracker 0x83722d80 + Verifier lock 0x831cefa8 + + State history: + [0] FxObjectStateCreated (0x1) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfobject%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfopenhandles.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfopenhandles.md new file mode 100644 index 0000000000..dc57906482 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfopenhandles.md @@ -0,0 +1,60 @@ +--- +title: wdfkd.wdfopenhandles +description: The wdfkd.wdfopenhandles extension displays information about all the handles that are open on the specified WDF device. +ms.assetid: 9b62a80a-6f53-4581-98b7-8eb5f9f146c2 +keywords: ["wdfkd.wdfopenhandles Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfopenhandles +api_type: +- NA +--- + +# !wdfkd.wdfopenhandles + + +The **!wdfkd.wdfopenhandles** extension displays information about all the handles that are open on the specified WDF device. + +``` +!wdfkd.wdfopenhandles Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a framework device object (WDFDEVICE). + + *Flags* +Optional. Specifies the kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 0 (0x1) +Displays file object context information. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfopenhandles%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfpool.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfpool.md new file mode 100644 index 0000000000..aba0a9b97b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfpool.md @@ -0,0 +1,20 @@ +--- +title: wdfkd.wdfpool +description: wdfkd.wdfpool +ms.assetid: 84b59a52-7c7d-4b61-a6e0-79017c11e95c +--- + +# !wdfkd.wdfpool + + +The **!wdfkd.wdfpool** extension is obsolete. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfpool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfpooltracker.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfpooltracker.md new file mode 100644 index 0000000000..04376e378b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfpooltracker.md @@ -0,0 +1,20 @@ +--- +title: wdfkd.wdfpooltracker +description: wdfkd.wdfpooltracker +ms.assetid: 8688bb0d-3315-46a7-a8f5-0ef6ba7cabb5 +--- + +# !wdfkd.wdfpooltracker + + +The **!wdfkd.wdfpooltracker** extension is obsolete. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfpooltracker%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfpoolusage.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfpoolusage.md new file mode 100644 index 0000000000..bebdab77a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfpoolusage.md @@ -0,0 +1,103 @@ +--- +title: wdfkd.wdfpoolusage +description: The wdfkd.wdfpoolusage extension displays pool usage information for a specified driver, if the Kernel-Mode Driver Framework (KMDF) verifier is enabled for the driver. +ms.assetid: 6a77b76b-c970-447c-a8dd-e1ceb7add611 +keywords: ["wdfkd.wdfpoolusage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfpoolusage +api_type: +- NA +--- + +# !wdfkd.wdfpoolusage + + +The **!wdfkd.wdfpoolusage** extension displays pool usage information for a specified driver, if the Kernel-Mode Driver Framework (KMDF) verifier is enabled for the driver. + +``` +!wdfkd.wdfpoolusage [DriverName [SearchAddress] [Flags]]] +``` + +## Parameters + + + *DriverName* +Optional. The name of a driver. *DriverName* must not include the .sys file name extension. + + *SearchAddress* +Optional. A string that represents a memory address. The pool entry that contains *SearchAddress* is displayed. If *SearchAddress* is 0 or omitted, all of the driver's pool entries are displayed. + + *Flags* +Optional. The kind of information to display. This parameter is valid only if *SearchAddress* is nonzero. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 0 (0x1) +Displays verbose output. Multiple lines are displayed for each. If this flag is not set, the information about an allocation is displayed on one line. + +Bit 1 (0x2) +Displays internal type information for each handle. + +Bit 2 (0x4) +Displays the caller of each pool entry. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +If you omit the *DriverName* parameter, the default driver is used. You can display the default driver by using the [**!wdfkd.wdfgetdriver**](-wdfkd-wdfgetdriver.md) extension; you can set the default driver by using the [**!wdfkd.wdfsetdriver**](-wdfkd-wdfsetdriver.md) extension. + +The following example shows the output from the **!wdfpoolusage** extension when no pool allocation is marked and the *Flags* value is set to 0. + +``` +## kd> !wdfpoolusage wdfrawbusenumtest 0 0 +----------------------------------- +## FxDriverGlobals 83b7af18 pool stats +----------------------------------- +Driver Tag: 'RawB' +15126 NonPaged Bytes, 548 Paged Bytes +94 NonPaged Allocations, 10 Paged Allocations +15610 PeakNonPaged Bytes, 752 PeakPaged Bytes +100 PeakNonPaged Allocations, 14 PeakPaged Allocations + +pool 82dbae00, Size 512 Tag 'RawB', NonPaged, Caller: Wdf01000!FxVerifierLock::AllocateThreadTable+5d +``` + +The following example shows the output from **!wdfpoolusage** that appears when the value of *Flags* is 1. (Note that the ellipsis (...) on the second line indicates the omission of some output that is the same as that shown in the preceding example.) + +``` +kd> !wdfpoolusage wdfrawbusenumtest 0 1 +. . . +100 PeakNonPaged Allocations, 14 PeakPaged Allocations + +Client alloc starts at 82dbae00 +Size 512 Tag 'RawB' +NonPaged (0x0) +Caller: Wdf01000!FxVerifierLock::AllocateThreadTable+5d +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfpoolusage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfqueue.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfqueue.md new file mode 100644 index 0000000000..6edc3ba131 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfqueue.md @@ -0,0 +1,74 @@ +--- +title: wdfkd.wdfqueue +description: The wdfkd.wdfqueue extension displays information about a specified framework queue object and the framework request objects that are in the queue. +ms.assetid: 100917dc-9ce9-48d6-a285-58ea78a4c2f4 +keywords: ["wdfkd.wdfqueue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfqueue +api_type: +- NA +--- + +# !wdfkd.wdfqueue + + +The **!wdfkd.wdfqueue** extension displays information about a specified framework queue object and the framework request objects that are in the queue. + +``` +!wdfkd.wdfqueue Handle +``` + +## Parameters + + + *Handle* +A handle to a framework queue object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The following example shows the display from a **!wdfkd.wdfqueue** extension. + +``` +kd> !wdfqueue 0x7ce7d1e8 + +# Dumping WDFQUEUE 0x7ce7d1e8 +========================= +Parallel, Power-managed, PowerOff, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone + Number of driver owned requests: 0 + Number of waiting requests: 0 + + + EvtIoDefault: (0xf221fad0) wdfrawbusenumtest!EvtIoQueueDefault +``` + +The queue in the preceding example is configured for parallel dispatching, is power-managed but is currently in the Off state, and can both accept and dispatch requests. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfqueue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfrequest.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfrequest.md new file mode 100644 index 0000000000..9623b3ac74 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfrequest.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfrequest +description: The wdfkd.wdfrequest extension displays information about a specified framework request object and the WDM I/O request packet (IRP) that is associated with the request object. +ms.assetid: 8b99ec30-ac2b-421d-8b20-bfbd09d41dfb +keywords: ["wdfkd.wdfrequest Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfrequest +api_type: +- NA +--- + +# !wdfkd.wdfrequest + + +The **!wdfkd.wdfrequest** extension displays information about a specified framework request object and the WDM I/O request packet (IRP) that is associated with the request object. + +``` +!wdfkd.wdfrequest Handle +``` + +## Parameters + + + *Handle* +A handle to a framework request object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfrequest%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfsearchpath.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfsearchpath.md new file mode 100644 index 0000000000..cb20c35043 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfsearchpath.md @@ -0,0 +1,86 @@ +--- +title: wdfkd.wdfsearchpath +description: The wdfkd.wdfsearchpath extension sets the search path to formatting files for Kernel-Mode Driver Framework (KMDF) error log records. +ms.assetid: cb52dc07-00b3-47d3-8636-4a6cd5ff3e29 +keywords: ["wdfkd.wdfsearchpath Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfsearchpath +api_location: +- Wdfkd.dll +api_type: +- DllExport +--- + +# !wdfkd.wdfsearchpath + + +The **!wdfkd.wdfsearchpath** extension sets the search path to formatting files for Kernel-Mode Driver Framework (KMDF) error log records. + +``` +!wdfkd.wdfsearchpath Path +``` + +## Parameters + + + *Path* +The path of a directory that contains KMDF formatting files. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +KMDF 1, UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The KMDF formatting files are included in the Windows Driver Kit (WDK). The path to the formatting files depends on the installation directory of your WDK and on the version of the WDK that you have installed. The KMDF formatting files have extension tmf (trace message formatting). To determine the search path, browse or search your WDK installation for file names of the form Wdf*VersionNumber*.tmf. The following example shows how to use the **!wdfkd.wdfsearchpath** extension. + +``` +kd> !wdfsearchpath C:\WinDDK\7600\tools\tracing\amd64 +``` + +The TRACE\_FORMAT\_SEARCH\_PATH environment variable also controls the search path, but the **!wdfkd.wdfsearchpath** extension takes precedence over the search path that TRACE\_FORMAT\_SEARCH\_PATH specifies. + +Requirements +------------ + + ++++ + + + + + + +

DLL

Wdfkd.dll
+ +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfsearchpath%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfsetdriver.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfsetdriver.md new file mode 100644 index 0000000000..ca47f4d787 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfsetdriver.md @@ -0,0 +1,61 @@ +--- +title: wdfkd.wdfsetdriver +description: The wdfkd.wdfsetdriver extension sets the name of the default Kernel-Mode Driver Framework (KMDF) driver to which debugger extension commands apply. +ms.assetid: 90fc99a0-1e78-44bb-ba91-191f116160e7 +keywords: ["wdfkd.wdfsetdriver Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfsetdriver +api_type: +- NA +--- + +# !wdfkd.wdfsetdriver + + +The **!wdfkd.wdfsetdriver** extension sets the name of the default Kernel-Mode Driver Framework (KMDF) driver to which debugger extension commands apply. + +``` +!wdfkd.wdfsetdriver DriverName +``` + +## Parameters + + + *DriverName* +The name of a driver. *DriverName* must not include the .sys file name extension. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The **!wdfkd.wdfsetdriver** extension sets the default driver name. You can use this name with other **wdfkd** extensions that would otherwise require you to specify a driver name. + +To obtain the name of the current default KMDF driver, use the [**!wdfkd.wdfgetdriver**](-wdfkd-wdfgetdriver.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfsetdriver%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfsettraceprefix.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfsettraceprefix.md new file mode 100644 index 0000000000..3ca1ed1a8c --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfsettraceprefix.md @@ -0,0 +1,61 @@ +--- +title: wdfkd.wdfsettraceprefix +description: The wdfkd.wdfsettraceprefix extension sets the trace prefix format string. +ms.assetid: dec47b55-4b6a-4ff5-8622-4a377a1903b8 +keywords: ["wdfkd.wdfsettraceprefix Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfsettraceprefix +api_type: +- NA +--- + +# !wdfkd.wdfsettraceprefix + + +The **!wdfkd.wdfsettraceprefix** extension sets the trace prefix format string. + +``` +!wdfkd.wdfsettraceprefix String +``` + +## Parameters + + + *String* +A trace prefix string. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The trace prefix string is prepended to each trace message in the Kernel-Mode Driver Framework (KMDF) error log. The TRACE\_FORMAT\_PREFIX environment variable also controls the trace prefix string. + +The format of the trace prefix string is defined by the Microsoft Windows tracing tools. For more information about the format of this string and how to customize it, see the "Trace Message Prefix" topic in the Driver Development Tools section of the Windows Driver Kit (WDK). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfsettraceprefix%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfspinlock.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfspinlock.md new file mode 100644 index 0000000000..568ec274b7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfspinlock.md @@ -0,0 +1,54 @@ +--- +title: wdfkd.wdfspinlock +description: The wdfkd.wdfspinlock extension displays information about a framework spin-lock object. This information includes the spin lock's acquisition history and the length of time that the lock was held. +ms.assetid: 73e74703-ed9b-460b-a798-41bb56942aa3 +keywords: ["wdfkd.wdfspinlock Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfspinlock +api_type: +- NA +--- + +# !wdfkd.wdfspinlock + + +The **!wdfkd.wdfspinlock** extension displays information about a framework spin-lock object. This information includes the spin lock's acquisition history and the length of time that the lock was held. + +``` +!wdfkd.wdfspinlock Handle +``` + +## Parameters + + + *Handle* +A handle to a WDFSPINLOCK-typed object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfspinlock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdftagtracker.md b/windows-driver-docs-pr/debugger/-wdfkd-wdftagtracker.md new file mode 100644 index 0000000000..d999591d0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdftagtracker.md @@ -0,0 +1,80 @@ +--- +title: wdfkd.wdftagtracker +description: The wdfkd.wdftagtracker extension displays all available tag information (including tag value, line, file, and time) for a specified tag tracker. +ms.assetid: d8720446-58c1-4792-9e16-0facfe8fa39f +keywords: ["wdfkd.wdftagtracker Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdftagtracker +api_type: +- NA +--- + +# !wdfkd.wdftagtracker + + +The **!wdfkd.wdftagtracker** extension displays all available tag information (including tag value, line, file, and time) for a specified tag tracker. + +``` +!wdfkd.wdftagtracker TagObjectPointer [Flags] +``` + +## Parameters + + + *TagObjectPointer* +A pointer to a tag tracker. + + *Flags* +Optional. The kind of information to display. *Flags* can be any combination of the following bits. The default value is 0x0. + +Bit 0 (0x1) +Displays the history of acquire operations and release operations on the object. + +Bit 1 (0x2) +Displays the line number of the object in hexadecimal instead of decimal. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +To retrieve a pointer to a tag tracker, use the [**!wdfkd.wdfobject**](-wdfkd-wdfobject.md) extension on an internal framework object pointer. + +To use tag tracking, you must enable both the Kernel-Mode Driver Framework (KMDF) verifier and handle tracking in the registry. Both of these settings are stored in the driver's **Parameters\\Wdf** subkey of the **HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Services** key. + +To enable the KMDF verifier, set a nonzero value for **VerifierOn**. + +To enable handle tracking, set the value of **TrackHandles** to the name of one or more object types, or specify an asterisk (\*) to track all object types. For example, the following example specifies the tracking of references to all WDFDEVICE and WDFQUEUE objects. + +``` +TrackHandles: MULTI_SZ: WDFDEVICE WDFQUEUE +``` + +When you enable handle tracking for an object type, the framework tracks the references that are taken on any object of that type. This setting is useful in finding driver memory leaks that unreleased references cause. **TrackHandles** works only if the KMDF verifier is enabled. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdftagtracker%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdftmffile.md b/windows-driver-docs-pr/debugger/-wdfkd-wdftmffile.md new file mode 100644 index 0000000000..ed2bd0e4ca --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdftmffile.md @@ -0,0 +1,71 @@ +--- +title: wdfkd.wdftmffile +description: The wdfkd.wdftmffile extension sets the trace message format (.tmf) file to use when the debugger is formatting KMDF error logs for the wdfkd.wdflogdump or wdfkd.wdfcrashdump. +ms.assetid: 7099440c-bfea-472f-b9ee-943026afdb81 +keywords: ["wdfkd.wdftmffile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdftmffile +api_type: +- NA +--- + +# !wdfkd.wdftmffile + + +The **!wdfkd.wdftmffile** extension sets the trace message format (.tmf) file to use when the debugger is formatting Kernel-Mode Driver Framework (KMDF) error log records for the [**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) or [**!wdfkd.wdfcrashdump**](-wdfkd-wdfcrashdump.md) extensions. + +``` +!wdfkd.wdftmffile TMFpath +``` + +## Parameters + + + *TMFpath* +A path that contains the .tmf file. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +If your driver uses a KMDF version earlier than 1.11, you must use the **!wdfkd.wdftmffile** extension before you can use the [**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) or [**!wdfkd.wdfcrashdump**](-wdfkd-wdfcrashdump.md) extensions. + +Starting in KMDF version 1.11, the framework library's symbol file (for example wdf01000.pdb) contains the trace message format (TMF) entries. Starting in the Windows 8 version of the kernel debugger, the [Kernel-Mode Driver Framework Extensions (Wdfkd.dll)](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) read the entries from the .pdb file. As a result, if your driver uses KMDF version 1.11 or later, and you are using the kernel debugger from Windows 8 or later, you do not need to use **!wdfkd.wdftmffile**. You do need to include the directory that contains the symbol file in the debugger's [symbol path](symbol-path.md). The debugging target machine can be running any operating system that supports KMDF. + +The following example shows how to use the **!wdfkd.wdftmffile** extension from the root WDK directory, for KMDF version 1.5. + +``` +kd> !wdftmffile tools\tracing\\wdf1005.tmf +``` + +Note that the path might be different for the version of the Windows Driver Kit (WDK) that you are using. Also note that the .tmf file's name represents the version of KMDF that you are using. For example, Wdf1005.tmf is the .tmf file for KMDF version 1.5. + +For information about how to view the KMDF log during a debugging session, see [Using the Framework's Event Logger](https://msdn.microsoft.com/library/windows/hardware/ff545531). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdftmffile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdftraceprtdebug.md b/windows-driver-docs-pr/debugger/-wdfkd-wdftraceprtdebug.md new file mode 100644 index 0000000000..163379d20a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdftraceprtdebug.md @@ -0,0 +1,62 @@ +--- +title: wdfkd.wdftraceprtdebug +description: The wdfkd.wdftraceprtdebug extension enables and disables the Traceprt.dll diagnostic mode, which generates verbose debugging information. +ms.assetid: e12e0ff1-fc27-4d95-b48a-73cab8f1e363 +keywords: ["wdfkd.wdftraceprtdebug Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdftraceprtdebug +api_type: +- NA +--- + +# !wdfkd.wdftraceprtdebug + + +The **!wdfkd.wdftraceprtdebug** extension enables and disables the Traceprt.dll diagnostic mode, which generates verbose debugging information. + +``` +!wdfkd.wdftraceprtdebug {on | off} +``` + +## Parameters + + + **on** +Enables the Traceprt.dll diagnostic mode. + + **off** +Disables the Traceprt.dll diagnostic mode. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You should use the !wdfkd.wdftraceprtdebug extension only at the direction of technical support. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdftraceprtdebug%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstack.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstack.md new file mode 100644 index 0000000000..decc81f0bb --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstack.md @@ -0,0 +1,119 @@ +--- +title: wdfkd.wdfumdevstack +description: The wdfkd.wdfumdevstack extension displays detailed information about a UMDF device stack in the implicit process. +ms.assetid: AB7F2585-B69B-4854-B8BC-438DDA735149 +keywords: ["wdfkd.wdfumdevstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumdevstack +api_type: +- NA +--- + +# !wdfkd.wdfumdevstack + + +The **!wdfkd.wdfumdevstack** extension displays detailed information about a UMDF device stack in the [implicit process](controlling-threads-and-processes.md). + +``` +!wdfkd.wdfumdevstack DevstackAddress [Flags] +``` + +## Parameters + + + *DevstackAddress* +Specifies the address of the device stack to display information about. You can use [**!wdfkd.wdfumdevstacks**](-wdfkd-wdfumdevstacks.md) to get the addresses of UMDF device stacks in the implicit process. + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays detailed information about the device stack. + +Bit 7 (0x80) +Displays information about the internal framework. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +This command displays the same information as the user-mode command [**!wudfext.umdevstack**](-wudfext-umdevstack.md). + +Here is an example of how to use **!wdfumdevstack**. First use [**!wdfumdevstacks**](-wdfkd-wdfumdevstacks.md) to display the UMDF device stacks in the implicit process. + +``` +0: kd> !wdfkd.wdfumdevstacks +Number of device stacks: 1 + Device Stack: 0x000000a5a3ab5f70 Pdo Name: \Device\00000052 + Active: Yes + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: MyUmdf2Driver + UMDriver Image Path: C:\WINDOWS\System32\drivers\UMDF\MyUmdf2Driver.dll + FxDriver: 0xa5a3acaaa0 + FxDevice: 0xa5a3ac4fc0 + Open UM files (use !wdfumfile for details): + Device XFerMode: Deferred RW: Buffered CTL: Buffered + DevStack XFerMode: Deferred RW: Buffered CTL: Buffered +``` + +The preceding output shows that there is one UMDF device stack in the implicit process. You can also see that the device stack has one device object (Number of UM devices: 1). + +The preceding output displays the address of a device stack (0x000000a5a3ab5f70). To get detailed information about the device stack, pass its address to **!wdfumdevstack**. In this example, we set the *Flags* parameter to 0x80 to include information about the framework. + +``` +0: kd> !wdfkd.wdfumdevstack 0x000000a5a3ab5f70 0x80 + Device Stack: 0x000000a5a3ab5f70 Pdo Name: \Device\00000052 + Active: Yes + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: MyUmdf2Driver + UMDriver Image Path: C:\WINDOWS\System32\drivers\UMDF\MyUmdf2Driver.dll + FxDriver: 0xa5a3acaaa0 + FxDevice: 0xa5a3ac4fc0 + Open UM files (use !wdfumfile for details): + Device XFerMode: Deferred RW: Buffered CTL: Buffered + Internal Values: + wudfhost!WudfDriverAndFxInfo 0x000000a5a3ac21b8 + IUMDFramework: 0x0000000000000000 + IFxMessageDispatch: 0x000000a5a3aba630 + FxDevice 0x000000a5a3ac4fc0 + Modules: + Driver: wudfhost!CWudfModuleInfo 0x000000a5a3ac18f0 + Fx: wudfhost!CWudfModuleInfo 0x000000a5a3aca7a0 + wudfx02000!FxDriver: 0x000000a5a3acaaa0 + DevStack XFerMode: Deferred RW: Buffered CTL: Buffered +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumdevstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstacks.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstacks.md new file mode 100644 index 0000000000..cad5194d5e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdevstacks.md @@ -0,0 +1,110 @@ +--- +title: wdfkd.wdfumdevstacks +description: The wdfkd.wdfumdevstacks extension displays information about all UMDF device stacks in the implicit process. +ms.assetid: 05D09B0D-4ED8-4333-B4BC-5BE28C63312C +keywords: ["wdfkd.wdfumdevstacks Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumdevstacks +api_type: +- NA +--- + +# !wdfkd.wdfumdevstacks + + +The **!wdfkd.wdfumdevstacks** extension displays information about all UMDF device stacks in the [implicit process](controlling-threads-and-processes.md). + +``` +!wdfkd.wdfumdevstacks [Flags] +``` + +## Parameters + + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays detailed information about each device stack. + +Bit 7 (0x80) +Displays information about the internal framework. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +This command displays the same information as the user-mode command [**!wudfext.umdevstacks**](-wudfext-umdevstacks.md). + +Before you use this command, use [**!process**](-process.md) to get a list of all UMDF host processes. + +``` +0: kd> !process 0 0 wudfhost.exe +PROCESS ffffe00000c32900 + SessionId: 0 Cid: 079c Peb: 7ff782537000 ParentCid: 037c + DirBase: 607af000 ObjectTable: ffffc00009807940 HandleCount: + Image: WUDFHost.exe +``` + +The preceding output shows that there is one UMDF host process; that is, there is one instance of wudfhost.exe. + +Next use [**.process**](-process--set-process-context-.md) to set the implicit process to wudfhost.exe. + +``` +0: kd> .process /P ffffe00000c32900 +Implicit process is now ffffe000`00c32900 +.cache forcedecodeptes done +``` + +Now use **!wdfkd.wdfumdevstacks** to display the UMDF device stacks in the implicit process (wudfhost.exe). + +``` +0: kd> !wdfkd.wdfumdevstacks +Number of device stacks: 1 + Device Stack: 0x000000a5a3ab5f70 Pdo Name: \Device\00000052 + Active: Yes + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: MyUmdf2Driver + UMDriver Image Path: C:\WINDOWS\System32\drivers\UMDF\MyUmdf2Driver.dll + FxDriver: 0xa5a3acaaa0 + FxDevice: 0xa5a3ac4fc0 + Open UM files (use !wdfumfile for details): + Device XFerMode: Deferred RW: Buffered CTL: Buffered + DevStack XFerMode: Deferred RW: Buffered CTL: Buffered +``` + +The preceding output shows that there is one UMDF device stack in the implicit process. You can also see that the device stack has one device object (Number of UM devices: 1). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumdevstacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumdownirp.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdownirp.md new file mode 100644 index 0000000000..1a0935c314 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumdownirp.md @@ -0,0 +1,71 @@ +--- +title: wdfkd.wdfumdownirp +description: The wdfkd.wdfumdownirp extension displays the kernel-mode I/O request packet (IRP) that is associated with a specified user-mode IRP. +ms.assetid: 98DFF193-950A-46CF-875E-B2907743F5D4 +keywords: ["wdfkd.wdfumdownirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumdownirp +api_type: +- NA +--- + +# !wdfkd.wdfumdownirp + + +The **!wdfkd.wdfumdownirp** extension displays the kernel-mode I/O request packet (IRP) that is associated with a specified user-mode IRP. This command is used in two steps. See Remarks. + +``` +!wdfkd.wdfumdownirp UmIrp [FileObject] +``` + +## Parameters + + + *UmIrp* +Specifies the address of a user mode IRP. You can use [**!wdfkd.wdfumirps**](-wdfkd-wdfumirps.md) to get the addresses of UM IRPs in the [implicit process](controlling-threads-and-processes.md). + + *FileObject* +Specifies the address of a **\_FILE\_OBJECT** structure. For information about how to get this address, see Remarks. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +To use this command, follow these steps: + +1. Enter this command, passing only the address a user-mode IRP. The command displays a handle. +2. Pass the displayed handle to the [**!handle**](-handle.md) command. In the output of **!handle**, find the address of a **\_FILE\_OBJECT** structure. +3. Enter this command again, passing both the address of the user-mode IRP and the address of the **\_FILE\_OBJECT** structure. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumdownirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumfile.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumfile.md new file mode 100644 index 0000000000..2820aa3408 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumfile.md @@ -0,0 +1,64 @@ +--- +title: wdfkd.wdfumfile +description: The wdfkd.wdfumfile extension displays information about a UMDF intra-stack file. +ms.assetid: AAE9E003-829D-4A52-8F67-58DFE15D5D3C +keywords: ["wdfkd.wdfumfile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumfile +api_type: +- NA +--- + +# !wdfkd.wdfumfile + + +The **!wdfkd.wdfumfile** extension displays information about a UMDF intra-stack file. + +``` +!wdfkd.wdfumfile Address +``` + +## Parameters + + + *Address* +Specifies the address of the UMDF intra-stack file to display information about. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +This command displays the same information as the user-mode command [**!wudfext.umfile**](-wudfext-umfile.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumfile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumirp.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumirp.md new file mode 100644 index 0000000000..b1b00a9c5b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumirp.md @@ -0,0 +1,95 @@ +--- +title: wdfkd.wdfumirp +description: The wdfkd.wdfumirp extension displays information about a user-mode I/O request packet (UM IRP). +ms.assetid: 8706E8F6-A387-48A9-AF14-ED2C0F94AD98 +keywords: ["wdfkd.wdfumirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumirp +api_type: +- NA +--- + +# !wdfkd.wdfumirp + + +The **!wdfkd.wdfumirp** extension displays information about a user-mode I/O request packet (UM IRP). + +``` +!wdfkd.wdfumirp Address +``` + +## Parameters + + + *Address* +Specifies the address of the UM IRP to display information about. You can use [**!wdfkd.wdfumirps**](-wdfkd-wdfumirps.md) to get the addresses of UM IRPs in the [implicit process](controlling-threads-and-processes.md). + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +This command displays the same information as the user-mode command [**!wudfext.umirp**](-wudfext-umirp.md). + +You can use [**!process**](-process.md) to get a list of all UMDF host processes, and you can use [**.process**](-process--set-process-context-.md) to set the implicit process to one of the UMDF host processes. For a detailed example, see [**!wdfkd.wdfumdevstacks**](-wdfkd-wdfumdevstacks.md). + +The following shows how to use [**!wdfkd.wdfumirps**](-wdfkd-wdfumirps.md) and **!wdfkd.wdfumirp** to display information about an individual UM IRP. + +``` +0: kd> !wdfkd.wdfumirps +Number of pending IRPS: 0x4 +#### CWudfIrp Current Type UniqueId KernelIrp Device Stack +---- ---------------- -------------------------------------------------- ---- +... +0003 1ab9eae370 Power (WAIT_WAKE) 0 ffffe00000c53010 1ab9eaa6d0 + +0: kd> !wdfkd.wdfumirp 1ab9eae370 +UM IRP: 0x0000001ab9eae370 UniqueId: 0x0 Kernel Irp: 0xffffe00000c53010 + Type: Power (WAIT_WAKE) + ClientProcessId: 0x0 + Device Stack: 0x0000001ab9eaa6d0 + IoStatus + hrStatus: 0x0 + Information: 0x0 + Total number of stack locations: 2 + CurrentStackLocation: StackLocation[ 0 ] + > StackLocation[ 0 ] + FxDevice: (None) + Completion: + Callback: 0x0000000000000000 + Context: 0x0000001ab9ebc750 + StackLocation[ 1 ] + ... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumirps.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumirps.md new file mode 100644 index 0000000000..377790ca9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumirps.md @@ -0,0 +1,85 @@ +--- +title: wdfkd.wdfumirps +description: The wdfkd.wdfumirps extension displays the list of pending user-mode I/O request packets (UM IRPs) in the implicit process. +ms.assetid: 1BFFDAC0-AA1F-434A-BB05-6864810F9B98 +keywords: ["wdfkd.wdfumirps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfumirps +api_type: +- NA +--- + +# !wdfkd.wdfumirps + + +The **!wdfkd.wdfumirps** extension displays the list of pending user-mode I/O request packets (UM IRPs) in the [implicit process](controlling-threads-and-processes.md). + +``` +!wdfkd.wdfumirps NumberOfIrps Flags +``` + +## Parameters + + + *NumberOfIrps* +Optional. Specifies the number of pending UM IRPs to display information about. If *NumberOfIrps* is an asterisk (\*) or is omitted, all UM IRPs will be displayed. + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays details about the pending IRPs. + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session or in a user-mode debugging session that is attached to the UMDF host process (wudfhost.exe). + +This command displays the same information as the user-mode command [**!wudfext.umirps**](-wudfext-umirps.md). + +You can use [**!process**](-process.md) to get a list of all UMDF host processes, and you can use [**.process**](-process--set-process-context-.md) to set the implicit process to one of the UMDF host processes. For a detailed example, see [**!wdfkd.wdfumdevstacks**](-wdfkd-wdfumdevstacks.md). + +Here is an example of the output of **!wdfkd.wdfumirps**. + +``` +0: kd> !wdfkd.wdfumirps +Number of pending IRPS: 0x4 +#### CWudfIrp Current Type UniqueId KernelIrp Device Stack +---- ---------------- -------------------------------------------------- ---- +0000 1ab9e90c40 WdfRequestUndefined 0 0 1ab9eaa6d0 +0001 1ab9ebfa90 WdfRequestInternalIoctl 0 0 1ab9eaa6d0 +0002 1ab9ebfd10 WdfRequestInternalIoctl 0 0 1ab9eaa6d0 +0003 1ab9eae370 Power (WAIT_WAKE) 0 ffffe00000c53010 1ab9eaa6d0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfumirps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfumtriage.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfumtriage.md new file mode 100644 index 0000000000..aa6bb15395 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfumtriage.md @@ -0,0 +1,60 @@ +--- +title: wdfkd_wdfumtriage +description: The wdfkd_wdfumtriage extension displays information UMDF devices on the system, including device objects, loaded drivers and class extensions, PnP device stack, dispatched IRPs. +ms.assetid: E25DAE56-E42A-4A56-B36F-8B0B1D826524 +keywords: ["wdfkd_wdfumtriage Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd_wdfumtriage +api_type: +- NA +--- + +# !wdfkd\_wdfumtriage + + +The **!wdfkd\_wdfumtriage** extension displays information about all UMDF devices on the system, including device objects, corresponding host process, loaded drivers and class extensions, PnP device stack, PnP device nodes, dispatched IRPs, and problem state if relevant. + +``` +!wdfkd.wdfumtriage +``` + +## DLL + + +Wdfkd.dll + +## Frameworks + + +UMDF 2 + +## Additional Information + + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use this command in a kernel-mode debugging session. + +Here is an example of the output of **!wdfkd\_wdfumtriage**. + +![driver object list output from !wdfkd.wdfumtriage](images/wdfumtriage2.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd_wdfumtriage%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfusbdevice.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbdevice.md new file mode 100644 index 0000000000..ad9b9c8fe9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbdevice.md @@ -0,0 +1,63 @@ +--- +title: wdfkd.wdfusbdevice +description: The wdfkd.wdfusbdevice extension displays information about a specified KMDF USB device object, incuding all USB interfaces and the pipes that are configured. +ms.assetid: 94e0a4ef-36a6-4a37-ac4a-5a2ee2678b9a +keywords: ["wdfkd.wdfusbdevice Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfusbdevice +api_type: +- NA +--- + +# !wdfkd.wdfusbdevice + + +The !wdfkd.wdfusbdevice extension displays information about a specified Kernel-Mode Driver Framework (KMDF) USB device object. This information includes all USB interfaces and the pipes that are configured for each interface. + +``` +!wdfkd.wdfusbdevice Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a WDFUSBDEVICE-typed USB device object. + + *Flags* +Optional. A hexadecimal value that modifies the kind of information to return. The default value is 0x0. Flags can be any combination of the following bits: + +Bit 0 (0x1) +The display will include the properties of the I/O target. + +Bit 1 (0x2) +The display will include the properties of the I/O target for each USB pipe object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfusbdevice%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfusbinterface.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbinterface.md new file mode 100644 index 0000000000..895d3da5c2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbinterface.md @@ -0,0 +1,60 @@ +--- +title: wdfkd.wdfusbinterface +description: The wdfkd.wdfusbinterface extension displays information about a specified Kernel-Mode Driver Framework (KMDF) USB interface object, including its possible and current settings. +ms.assetid: 2c0788aa-adb0-4a51-9937-32c8d9e0c240 +keywords: ["wdfkd.wdfusbinterface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfusbinterface +api_type: +- NA +--- + +# !wdfkd.wdfusbinterface + + +The **!wdfkd.wdfusbinterface** extension displays information about a specified Kernel-Mode Driver Framework (KMDF) USB interface object, including its possible and current settings. + +``` +!wdfkd.wdfusbinterface Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a WDFUSBINTERFACE-typed USB interface object. + + *Flags* +Optional. A hexadecimal value that modifies the kind of information to return. The default value is 0x0. Flags can be any combination of the following bits: + +Bit 0 (0x1) +The display will include the properties of the I/O target for each KMDF USB pipe object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfusbinterface%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfusbpipe.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbpipe.md new file mode 100644 index 0000000000..bcf1cee477 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfusbpipe.md @@ -0,0 +1,60 @@ +--- +title: wdfkd.wdfusbpipe +description: The wdfkd.wdfusbpipe extension displays information about a Kernel-Mode Driver Framework (KMDF) USB pipe object's I/O target. +ms.assetid: 6ae335c4-ac86-4f8c-b22d-cedad72e9cab +keywords: ["wdfkd.wdfusbpipe Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfusbpipe +api_type: +- NA +--- + +# !wdfkd.wdfusbpipe + + +The **!wdfkd.wdfusbpipe** extension displays information about a Kernel-Mode Driver Framework (KMDF) USB pipe object's I/O target. + +``` +!wdfkd.wdfusbpipe Handle [Flags] +``` + +## Parameters + + + *Handle* +A handle to a WDFUSBPIPE-typed USB pipe object. + + *Flags* +Optional. A hexadecimal value that modifies the kind of information to return. The default value is 0x0. Flags can be any combination of the following bits: + +Bit 0 (0x1) +The display will include the properties of the I/O target. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1, UMDF 2 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfusbpipe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdfkd-wdfwmi.md b/windows-driver-docs-pr/debugger/-wdfkd-wdfwmi.md new file mode 100644 index 0000000000..8a212505b1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdfkd-wdfwmi.md @@ -0,0 +1,59 @@ +--- +title: wdfkd.wdfwmi +description: The wdfkd.wdfwmi extension displays the Microsoft Windows Management Instrumentation (WMI) information for a specified framework device object. +ms.assetid: fd521be8-3c7a-415b-8044-c9fb25188cbc +keywords: ["wdfkd.wdfwmi Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdfkd.wdfwmi +api_type: +- NA +--- + +# !wdfkd.wdfwmi + + +The **!wdfkd.wdfwmi** extension displays the Microsoft Windows Management Instrumentation (WMI) information for a specified framework device object. This information includes all WMI provider objects and their associated WMI instance objects. + +``` +!wdfkd.wdfwmi Handle +``` + +## Parameters + + + *Handle* +A handle to a framework device object. + +### DLL + +Wdfkd.dll + +### Frameworks + +KMDF 1 + +### Additional Information + +For more information, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +Remarks +------- + +The output of the **!wdfkd.wdfwmi** extension includes information about the WMI registration, provider, and instances. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdfkd.wdfwmi%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wdmaud.md b/windows-driver-docs-pr/debugger/-wdmaud.md new file mode 100644 index 0000000000..0016d45c66 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wdmaud.md @@ -0,0 +1,90 @@ +--- +title: wdmaud +description: Displays a variety of WDM Audio (WDMAud) structures. +ms.assetid: fa41e3e2-a767-4c8c-9604-e3ea924ac571 +keywords: ["wdmaud Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wdmaud +api_type: +- NA +--- + +# !wdmaud + + +Displays a variety of WDM Audio (WDMAud) structures. + +``` +!wdmaud Address Flags +``` + +## Parameters + + + *Address* +Specifies the address of the structure to be displayed. + + *Flags* +Specifies the information to display. This must include exactly one of the bits 0x1, 0x2, 0x4, and 0x8. The 0x100 bit can be added to any of these. + +Bit 0 (0x1) +Displays a list of all IOCTLs that have been sent to wdmaud.sys. When this is used, *Address* should specify the address of the **WdmaIoctlHistoryListHead**. If the 0x100 bit is set, the display also includes the **pContext** that each IOCTL was sent with. + +Bit 1 (0x2) +Displays a list of all IRPs that WDMAud has marked as pending. When this is used, *Address* should specify the address of the **WdmaPendingIrpListHead**. If the 0x100 bit is set, the display also includes the context on which each IRP was allocated. + +Bit 2 (0x4) +Displays a list of all MDLs that WDMAud has allocated. When this is used, *Address* should specify the address of the **WdmaAllocatedMdlListHead**. If the 0x100 bit is set, the display also includes the context on which each MDL was allocated. + +Bit 3 (0x8) +Displays a list of all active contexts attached to wdmaud.sys. When this is used, *Address* should specify the address of the **WdmaContextListHead**. If the 0x100 bit is set, the display also includes the data members of each context structure. + +Bit 8 (0x100) +Causes the display to include verbose information. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +For information about WDM audio architecture and audio drivers, see the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The contexts attached to wdmaud.sys (**pContext**) contain most of the state data for each device. Whenever wdmaud.drv is loaded into a new process, wdmaud.sys is notified of its arrival. Whenever wdmaud.drv is unloaded, wdmaud.sys cleans up any allocations made in that context. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wdmaud%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-whatperftime.md b/windows-driver-docs-pr/debugger/-whatperftime.md new file mode 100644 index 0000000000..1e5d1f24db --- /dev/null +++ b/windows-driver-docs-pr/debugger/-whatperftime.md @@ -0,0 +1,75 @@ +--- +title: whatperftime +description: The whatperftime extension converts a high-resolution performance counter value into a standard time value. +ms.assetid: ff11a51f-4e25-4cf3-be19-d38361c441e9 +keywords: ["performance count", "whatperftime Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- whatperftime +api_type: +- NA +--- + +# !whatperftime + + +The **!whatperftime** extension converts a high-resolution performance counter value into a standard time value. + +``` +!whatperftime Count +``` + +## Parameters + + + *Count* +The performance counter clock value. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +You can use **!whatperftime** to convert values retrieved by calling **QueryPerformanceCounter**. Performance counter time values are also found in software traces. + +The output is displayed as *HH:MM:SS.mmm*. Here is an example: + +``` +kd> !whatperftime 304589 +3163529 Performance Counter in Standard Time: .004.313s +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!whatperftime%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-whattime.md b/windows-driver-docs-pr/debugger/-whattime.md new file mode 100644 index 0000000000..d78cc26e15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-whattime.md @@ -0,0 +1,73 @@ +--- +title: whattime +description: The whattime extension converts a tick count into a standard time value. +ms.assetid: c63e8bad-3a87-4209-b9f0-b6c433c294b2 +keywords: ["tick count", "whattime Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- whattime +api_type: +- NA +--- + +# !whattime + + +The **!whattime** extension converts a tick count into a standard time value. + +``` +!whattime Ticks +``` + +## Parameters + + + *Ticks* +The number of ticks. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Kdexts.dll

+ +  + +Remarks +------- + +The output is displayed as *HH:MM:SS.mmm*. Here is an example: + +``` +kd> !whattime 29857ae4 +696613604 Ticks in Standard Time: 15:02:16.040s +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!whattime%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-whea.md b/windows-driver-docs-pr/debugger/-whea.md new file mode 100644 index 0000000000..6c50a8a869 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-whea.md @@ -0,0 +1,173 @@ +--- +title: whea +description: The whea extension displays top-level Windows Hardware Error Architecture (WHEA) information. +ms.assetid: 5d621507-74e7-4a43-8600-88dca29e461d +keywords: ["whea Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- whea +api_type: +- NA +--- + +# !whea + + +The **!whea** extension displays top-level Windows Hardware Error Architecture (WHEA) information. + +``` +!whea +``` + +## + + +### DLL + + ++++ + + + + + + + + + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP

Unavailable

Windows Server 2003

Unavailable

Windows Vista and later

Kdexts.dll

+ +  + +This extension can be used only in Windows Vista and later versions of Windows. + +### Additional Information + +The [**!errrec**](-errrec.md) and [**!errpkt**](-errpkt.md) extensions can be used to display additional WHEA information. For general information about WHEA, see [Windows Hardware Error Architecture (WHEA)](http://go.microsoft.com/fwlink/p/?linkid=153571) in the Windows Driver Kit (WDK) documentation. + +Remarks +------- + +The following example shows the (truncated) output of the **!whea** extension: + +``` +3: kd> !whea +Error Source Table @ fffff800019ca250 +13 Error Sources +Error Source 0 @ fffffa80064132c0 + Notify Type : Machine Check Exception + Type : 0x0 (MCE) + Error Count : 8 + Record Count : 10 + Record Length : c3e + Error Records : wrapper @ fffffa8007cf4000 record @ fffffa8007cf4030 + : wrapper @ fffffa8007cf4c3e record @ fffffa8007cf4c6e + : wrapper @ fffffa8007cf587c record @ fffffa8007cf58ac + : wrapper @ fffffa8007cf64ba record @ fffffa8007cf64ea + : wrapper @ fffffa8007cf70f8 record @ fffffa8007cf7128 + : wrapper @ fffffa8007cf7d36 record @ fffffa8007cf7d66 + : wrapper @ fffffa8007cf8974 record @ fffffa8007cf89a4 + : wrapper @ fffffa8007cf95b2 record @ fffffa8007cf95e2 + : wrapper @ fffffa8007cfa1f0 record @ fffffa8007cfa220 + : wrapper @ fffffa8007cfae2e record @ fffffa8007cfae5e + : wrapper @ fffffa8007cfba6c record @ fffffa8007cfba9c + : wrapper @ fffffa8007cfc6aa record @ fffffa8007cfc6da + : wrapper @ fffffa8007cfd2e8 record @ fffffa8007cfd318 + : wrapper @ fffffa8007cfdf26 record @ fffffa8007cfdf56 + : wrapper @ fffffa8007cfeb64 record @ fffffa8007cfeb94 + : wrapper @ fffffa8007cff7a2 record @ fffffa8007cff7d2 + Descriptor : @ fffffa8006413328 + Length : 3cc + Max Raw Data Length : 392 + Num Records To Preallocate : 10 + Max Sections Per Record : 3 + Error Source ID : 0 + Flags : 00000000 +Error Source 1 @ fffffa8007d00bc0 + Notify Type : Corrected Machine Check + Type : 0x1 (CMC) + Error Count : 0 + Record Count : 10 + Record Length : c3e + Error Records : wrapper @ fffffa8007d01000 record @ fffffa8007d01030 + : wrapper @ fffffa8007d01c3e record @ fffffa8007d01c6e + : wrapper @ fffffa8007d0287c record @ fffffa8007d028ac + : wrapper @ fffffa8007d034ba record @ fffffa8007d034ea + : wrapper @ fffffa8007d040f8 record @ fffffa8007d04128 + : wrapper @ fffffa8007d04d36 record @ fffffa8007d04d66 + : wrapper @ fffffa8007d05974 record @ fffffa8007d059a4 + : wrapper @ fffffa8007d065b2 record @ fffffa8007d065e2 + : wrapper @ fffffa8007d071f0 record @ fffffa8007d07220 + : wrapper @ fffffa8007d07e2e record @ fffffa8007d07e5e + : wrapper @ fffffa8007d08a6c record @ fffffa8007d08a9c + : wrapper @ fffffa8007d096aa record @ fffffa8007d096da + : wrapper @ fffffa8007d0a2e8 record @ fffffa8007d0a318 + : wrapper @ fffffa8007d0af26 record @ fffffa8007d0af56 + : wrapper @ fffffa8007d0bb64 record @ fffffa8007d0bb94 + : wrapper @ fffffa8007d0c7a2 record @ fffffa8007d0c7d2 + Descriptor : @ fffffa8007d00c28 + Length : 3cc + Max Raw Data Length : 392 + Num Records To Preallocate : 10 + Max Sections Per Record : 3 + Error Source ID : 1 + Flags : 00000000 +Error Source 2 @ fffffa8007d00770 + Notify Type : Non-Maskable Interrupt + Type : 0x3 (NMI) + Error Count : 1 + Record Count : 1 + Record Length : 1f8 + Error Records : wrapper @ fffffa800631b2c0 record @ fffffa800631b2f0 + Descriptor : @ fffffa8007d007d8 + Length : 3cc + Max Raw Data Length : 100 + Num Records To Preallocate : 1 + Max Sections Per Record : 1 + Error Source ID : 2 + Flags : 00000000 +Error Source 3 @ fffffa8007d0dbc0 + Notify Type : BOOT Error Record + Type : 0x7 (BOOT) + Error Count : 0 + Record Count : 1 + Record Length : 4f8 + Error Records : wrapper @ 0000000000000000 record @ 0000000000000030 + Descriptor : @ fffffa8007d0dc28 + Length : 3cc + Max Raw Data Length : 400 + Num Records To Preallocate : 1 + Max Sections Per Record : 1 + Error Source ID : 3 + Flags : 00000000 + +. . . . +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!whea%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-while.md b/windows-driver-docs-pr/debugger/-while.md new file mode 100644 index 0000000000..5ad324e265 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-while.md @@ -0,0 +1,54 @@ +--- +title: .while +description: The .while token behaves like the while keyword in C. +ms.assetid: bc38357d-b17a-4a26-840e-1b4b90986154 +keywords: [".while Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .while +api_type: +- NA +--- + +# .while + + +The **.while** token behaves like the **while** keyword in C. + +``` +.while (Condition) { Commands } +``` + +## Syntax Elements + + + *Condition* +Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing *Condition* in parentheses is optional. *Condition* must be an expression, not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Commands* +Specifies one or more commands that will be executed repeatedly as long as the condition is true. This block of commands needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon. + +### Additional Information + +For information about other control flow tokens and their use in debugger command programs, see [Using Debugger Command Programs](using-debugger-command-programs.md). + +Remarks +------- + +The [**.break**](https://msdn.microsoft.com/library/windows/hardware/ff556242) and [**.continue**](-continue.md) tokens can be used to exit or restart the *Commands* block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.while%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-winrterr.md b/windows-driver-docs-pr/debugger/-winrterr.md new file mode 100644 index 0000000000..82ed4a5de6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-winrterr.md @@ -0,0 +1,84 @@ +--- +title: winrterr +description: The winrterr sets the debugger reporting mode for Windows Runtime errors. +ms.assetid: 72E3EF7A-6055-405F-9E24-C9B81C07B8A7 +keywords: ["winrterr Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- winrterr +api_type: +- NA +--- + +# !winrterr + + +The **!winrterr** sets the debugger reporting mode for Windows Runtime errors. + +``` +!winrterr Mode +!winrterr +``` + +## Parameters + + +*Mode* +The following table describes the possible values for *Mode*. + + ++++ + + + + + + + + + + + + + + + + + + + + +
ValueDescription

report

When a Windows Runtime error occurs, the error and related text are displayed in the debugger, but execution contunues. This is the default mode.

break

When a Windows Runtime error occurs, the error and related text are displayed in the debugger, and execution stops.

quiet

When a Windows Runtime error occurs, nothing is displayed in the debugger, and execution continues.

+ +  + +If *Mode* is omitted, **!winrterr** displays the current reporting mode. If the debugger has broken in as a result of a Windows Runtime error, the error and related text are also displayed. + +## See also + + +[Windows Runtime Debugger Commands](windows-runtime-debugger-commands.md) + +[**!hstring**](-hstring.md) + +[**!hstring2**](-hstring2.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!winrterr%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-disable.md b/windows-driver-docs-pr/debugger/-wmitrace-disable.md new file mode 100644 index 0000000000..7fc6d1692f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-disable.md @@ -0,0 +1,65 @@ +--- +title: wmitrace.disable +description: The wmitrace.disable extension disables a provider for the specified Event Tracing for Windows (ETW) trace session. +ms.assetid: b993bfa4-2d3d-4739-9d5e-0cb714369742 +keywords: ["wmitrace.disable Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.disable +api_type: +- NA +--- + +# !wmitrace.disable + + +The **!wmitrace.disable** extension disables a provider for the specified Event Tracing for Windows (ETW) trace session. + +``` +!wmitrace.disable { LoggerID | LoggerName } GUID +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + + *GUID* +Specifies the GUID of the provider to be disabled. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 7 and later versions of Windows. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +After using this extension, you must resume program execution (for example, by using the [**g (Go)**](g--go-.md) command) in order for it to take effect. After a brief time, the target computer automatically breaks into the debugger again. + +To enable a provider, use [**!wmitrace.enable**](-wmitrace-enable.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.disable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-dumpmini.md b/windows-driver-docs-pr/debugger/-wmitrace-dumpmini.md new file mode 100644 index 0000000000..745df7d91f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-dumpmini.md @@ -0,0 +1,56 @@ +--- +title: wmitrace.dumpmini +description: The wmitrace.dumpmini extension displays the system trace fragment, which is stored in a dump file. +ms.assetid: c6b4c09f-3a73-4467-849b-8570477bc9af +keywords: ["wmitrace.dumpmini Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.dumpmini +api_type: +- NA +--- + +# !wmitrace.dumpmini + + +The **!wmitrace.dumpmini** extension displays the system trace fragment, which is stored in a dump file. + +``` +!wmitrace.dumpmini +``` + +## + + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows Vista and later versions of Windows. + +This extension is useful only when debugging a minidump file or a full dump file. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +The *system trace fragment* is a copy of the contents of the last buffer of the System Context Log. Under normal conditions, this is the trace session whose logger ID is 2. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.dumpmini%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-dumpminievent.md b/windows-driver-docs-pr/debugger/-wmitrace-dumpminievent.md new file mode 100644 index 0000000000..488cc61380 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-dumpminievent.md @@ -0,0 +1,56 @@ +--- +title: wmitrace.dumpminievent +description: The wmitrace.dumpminievent extension displays the system event log trace fragment, which is stored in a dump file. +ms.assetid: 94debe5f-d125-44d0-99c4-90d8794525df +keywords: ["wmitrace.dumpminievent Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.dumpminievent +api_type: +- NA +--- + +# !wmitrace.dumpminievent + + +The **!wmitrace.dumpminievent** extension displays the system event log trace fragment, which is stored in a dump file. + +``` +!wmitrace.dumpminievent +``` + +## + + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows Vista Service Pack 1 (SP1) and later versions of Windows. + +This extension is useful only when debugging a minidump file or a full dump file. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +The *system event log trace fragment* is a copy of the contents of the last buffer of the System Event Log. The **!wmitrace.dumpminievent** extension displays its contents in event log format. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.dumpminievent%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-dynamicprint.md b/windows-driver-docs-pr/debugger/-wmitrace-dynamicprint.md new file mode 100644 index 0000000000..661d4ae67a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-dynamicprint.md @@ -0,0 +1,76 @@ +--- +title: wmitrace.dynamicprint +description: The wmitrace.dynamicprint extension controls whether the debugger displays the trace messages generated by a session running in KD_FILTER_MODE. +ms.assetid: 458a9dfa-e3cc-4652-a9e5-5098a962f1c7 +keywords: ["wmitrace.dynamicprint Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.dynamicprint +api_type: +- NA +--- + +# !wmitrace.dynamicprint + + +The **!wmitrace.dynamicprint** extension controls whether the debugger displays the trace messages generated by a session running in KD\_FILTER\_MODE. + +``` +!wmitrace.dynamicprint {0 | 1} +``` + +## Parameters + + + **0** +Turns the trace message display off. + + **1** +Turns the trace message display on. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For help in starting a trace session, see "Tracelog" in the Windows Driver Kit (WDK). + +Remarks +------- + +Before you use this extension, start a trace session, and specify that the trace messages should be sent to the debugger. For example, if you use [**!wmitrace.start**](-wmitrace-start.md) to start the session, use the **-kd** parameter. If you use Tracelog to start the trace session, use its **-kd** parameter. Tracelog (tracelog.exe) is a trace controller included in the Windows Driver Kit. + +Trace messages are held in a buffers on the target computer. Those buffers are flushed and sent to the debugger on the host computer at regular intervals. You can specify the flush timer interval by using the **-kd** parameter of the [**!wmitrace.start**](-wmitrace-start.md) command or the **-kd** parameter of the Tracelog tool. Starting in Windows 8, you can specify the flush timer value in milliseconds by appending **ms** to the flush timer value. + +By default, ETW maintains per-processor trace buffers on the target computer. When the trace buffers are flushed and sent to the debugger on the host computer, there is no mechanism for merging the buffers into a chronological sequence of events. So the events might be displayed out of order. Starting in Windows 7, you can solve this problem by setting the **-lowcapacity** parameter when you use the Tracelog tool to start a trace session. + +**Tracelog** *MySession* **-kd -lowcapacity** + +When you start a session with **-lowcapacity** set, all events go to a single buffer on the target computer, and the events are displayed in the correct order in the debugger on the host computer. + +Also, before using this extension, use [**!wmitrace.searchpath**](-wmitrace-searchpath.md) or [**!wmitrace.tmffile**](-wmitrace-tmffile.md) to specify the trace message format files. The system uses the trace message format files to format the binary trace messages so that they can be displayed as human-readable text. + +## See also + + +[**!wmitrace.start**](-wmitrace-start.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.dynamicprint%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-enable.md b/windows-driver-docs-pr/debugger/-wmitrace-enable.md new file mode 100644 index 0000000000..476cdd0bc7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-enable.md @@ -0,0 +1,80 @@ +--- +title: wmitrace.enable +description: The wmitrace.enable extension enables a provider for the specified Event Tracing for Windows (ETW) trace session. +ms.assetid: 5a27fa00-7d52-43f7-84f4-82c5b5af1c06 +keywords: ["wmitrace.enable Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.enable +api_type: +- NA +--- + +# !wmitrace.enable + + +The **!wmitrace.enable** extension enables a provider for the specified Event Tracing for Windows (ETW) trace session. + +``` +!wmitrace.enable { LoggerID | LoggerName } GUID [-level Num] [-matchallkw Num] [-matchanykw Num] [-enableproperty Num] [-flag Num] +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + + *GUID* +Specifies the GUID of the provider to be enabled. + + **-level** *Num* +Specifies the level. *Num* can be any integer. + + **-matchallkw** *Num* +Specifies one or more keywords. If multiple keywords are specified, the provider will be enabled only if all keywords are matched. *Num* can be any integer. + + **-matchanykw** *Num* +Specifies one or more keywords. If multiple keywords are specified, the provider will be enabled if at least one keyword is matched. *Num* can be any integer. The effects of this parameter overlap with the effects of the -flag parameter. + + **-enableproperty** *Num* +Specifies the enable property. *Num* can be any integer. + + **-flag** *Num* +Specifies one or more flags. *Num* can be any integer. The effects of this parameter overlap with the effects of the -matchanykw parameter. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 7 and later versions of Windows. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +After using this extension, you must resume program execution (for example, by using the [**g (Go)**](g--go-.md) command) in order for it to take effect. After a brief time, the target computer automatically breaks into the debugger again. + +To disable a provider, use [**!wmitrace.disable**](-wmitrace-disable.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.enable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-eventlogdump.md b/windows-driver-docs-pr/debugger/-wmitrace-eventlogdump.md new file mode 100644 index 0000000000..3bb16778a0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-eventlogdump.md @@ -0,0 +1,62 @@ +--- +title: wmitrace.eventlogdump +description: The wmitrace.eventlogdump extension displays the contents of the specified logger. The display is formatted like an event log. +ms.assetid: 27254b36-b413-45f0-9834-ff55fbb787c7 +keywords: ["wmitrace.eventlogdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.eventlogdump +api_type: +- NA +--- + +# !wmitrace.eventlogdump + + +The **!wmitrace.eventlogdump** extension displays the contents of the specified logger. The display is formatted like an event log. + +``` +!wmitrace.eventlogdump { LoggerID | LoggerName } +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +This extension is similar to the [**!wmitrace.logdump**](-wmitrace-logdump.md) extension, except that the output of **!wmitrace.eventlogdump** is formatted in event log style, and the output of **!wmitrace.logdump** is formatted in Windows software trace preprocessor (WPP) style. You should choose the extension whose format is appropriate for the data you wish to display. + +To find the logger ID of a trace session, use the [**!wmitrace.strdump**](-wmitrace-strdump.md) extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and their basic properties, including the logger ID. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.eventlogdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-help.md b/windows-driver-docs-pr/debugger/-wmitrace-help.md new file mode 100644 index 0000000000..ec6a6e2b8a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-help.md @@ -0,0 +1,49 @@ +--- +title: wmitrace.help +description: The wmitrace.help extension displays the extension commands in Wmitrace.dll. +ms.assetid: b0839c68-a53e-4f80-bad3-7545b5c78b7a +keywords: ["wmitrace.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.help +api_type: +- NA +--- + +# !wmitrace.help + + +The **!wmitrace.help** extension displays the extension commands in Wmitrace.dll. + +``` +!wmitrace.help +``` + +## + + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-logdump.md b/windows-driver-docs-pr/debugger/-wmitrace-logdump.md new file mode 100644 index 0000000000..eacdce1679 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-logdump.md @@ -0,0 +1,84 @@ +--- +title: wmitrace.logdump +description: The wmitrace.logdump extension displays the contents of the trace buffers for a trace session. You can limit the display to trace messages from specified providers. +ms.assetid: 073338c6-68c4-4ae0-b69e-392256277236 +keywords: ["wmitrace.logdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.logdump +api_type: +- NA +--- + +# !wmitrace.logdump + + +The **!wmitrace.logdump** extension displays the contents of the trace buffers for a trace session. You can limit the display to trace messages from specified providers. + +``` +!wmitrace.logdump [-t Count] [{LoggerID|LoggerName} [GUIDFile]] +``` + +## Parameters + + + **-t** *Count* +Limits the output to the most recent messages. *Count* specifies the number of messages to display. + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. If no parameter is specified, the trace session with ID equal to 1 is used. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + + *GUIDFile* +Displays only trace messages from providers specified in the *GUIDFile* file. *GUIDFile* represents the path (optional) and file name of a text file that contains the control GUIDs of one or more trace providers, such as a .guid or .ctl file. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about Tracelog, see "Tracelog" in the Windows Driver Kit (WDK). + +Remarks +------- + +During Windows software trace preprocessor (WPP) software tracing, trace session buffers are used to store trace messages until they are flushed to a log file or to a trace consumer for a real-time display. The **!wmitrace.logdump** extension displays the contents of the buffers that are in physical memory. The display appears in the Debugger Command window. + +This extension is especially useful to recover the most recent traces when a crash occurs, and to display the traces stored in a crash dump file. + +Before you use this extension, use [**!wmitrace.searchpath**](-wmitrace-searchpath.md) or [**!wmitrace.tmffile**](-wmitrace-tmffile.md) to specify the trace message format files. The system uses the trace message format files to format the binary trace messages in the buffers so that they can be displayed as human-readable text. + +**Note**  If your driver uses UMDF version 1.11 or later, you do not need to use [**!wmitrace.searchpath**](-wmitrace-searchpath.md) or [**!wmitrace.tmffile**](-wmitrace-tmffile.md). + +  + +When you use Tracelog to start a trace session with circular buffering (-buffering), use this extension to display the buffer contents. + +To find the logger ID of a trace session, use the [**!wmitrace.strdump**](-wmitrace-strdump.md) extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and their basic properties, including the logger ID. + +This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested providers do not use trace message format (TMF) files, and therefore this extension does not display their contents. + +This extension is similar to the [**!wmitrace.eventlogdump**](-wmitrace-eventlogdump.md) extension, except that the output of **!wmitrace.logdump** is formatted in WPP style, and the output of **!wmitrace.eventlogdump** is formatted in event log style. You should choose the extension whose format is appropriate for the data you want to display. + +For information about how to view the UMDF trace log, see [Using WPP Software Tracing in UMDF-based Drivers](https://msdn.microsoft.com/library/windows/hardware/ff561391#viewing-the-umdf-trace-log). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.logdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-logger.md b/windows-driver-docs-pr/debugger/-wmitrace-logger.md new file mode 100644 index 0000000000..392fc1f5cc --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-logger.md @@ -0,0 +1,62 @@ +--- +title: wmitrace.logger +description: The wmitrace.logger extension displays data about the trace session, including the session configuration data. This extension does not display trace messages generated during the session. +ms.assetid: 2bc456db-3e97-49f8-9c57-75ee5fee0f9d +keywords: ["wmitrace.logger Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.logger +api_type: +- NA +--- + +# !wmitrace.logger + + +The **!wmitrace.logger** extension displays data about the trace session, including the session configuration data. This extension does not display trace messages generated during the session. + +``` +!wmitrace.logger [ LoggerID | LoggerName ] +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. If no parameter is specified, the trace session with ID equal to 1 is used. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. + +Remarks +------- + +This extension is designed for performance logs and events, which cannot be formatted for human-readable display. To display the trace messages in a trace session buffer, along with header data, use [**!wmitrace.logdump**](-wmitrace-logdump.md). + +To find the logger ID of a trace session, use the [**!wmitrace.strdump**](-wmitrace-strdump.md) extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and their basic properties, including the logger ID. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.logger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-logsave.md b/windows-driver-docs-pr/debugger/-wmitrace-logsave.md new file mode 100644 index 0000000000..7a78de411e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-logsave.md @@ -0,0 +1,71 @@ +--- +title: wmitrace.logsave +description: The wmitrace.logsave extension writes the current contents of the trace buffers for a trace session to a file. +ms.assetid: 713fea09-d405-4142-b2e8-29c813a4c3b6 +keywords: ["wmitrace.logsave Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.logsave +api_type: +- NA +--- + +# !wmitrace.logsave + + +The **!wmitrace.logsave** extension writes the current contents of the trace buffers for a trace session to a file. + +``` +!wmitrace.logsave {LoggerID|LoggerName} Filename +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + + *Filename* +Specifies a path (optional) and file name for the output file. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about Tracelog, see "Tracelog" in the Windows Driver Kit (WDK). + +Remarks +------- + +This extension displays only the traces that are in memory at the time. It does not display trace messages that have been flushed from the buffers and delivered to an event trace log file or to a trace consumer. + +Trace session buffers store trace messages until they are flushed to a log file or to a trace consumer for a real-time display. This extension saves the contents of the buffers that are in physical memory to the specified file. + +The output is written in binary format. Typically, these files use the .etl (event trace log) filename extension. + +When you use Tracelog to start a trace session with circular buffering (-buffering), you can use this extension to save the current buffer contents. + +To find the logger ID of a trace session, use the [**!wmitrace.strdump**](-wmitrace-strdump.md) extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and their basic properties, including the logger ID. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.logsave%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-searchpath.md b/windows-driver-docs-pr/debugger/-wmitrace-searchpath.md new file mode 100644 index 0000000000..111a840d82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-searchpath.md @@ -0,0 +1,71 @@ +--- +title: wmitrace.searchpath +description: The wmitrace.searchpath extension specifies the location of the trace message format files for messages in the trace buffers. +ms.assetid: 528c997c-007c-4046-92cc-169c7720b3fe +keywords: ["wmitrace.searchpath Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.searchpath +api_type: +- NA +--- + +# !wmitrace.searchpath + + +The **!wmitrace.searchpath** extension specifies the location of the trace message format files for messages in the trace buffers. + +``` +!wmitrace.searchpath [+] TMFPath +!wmitrace.searchpath +``` + +## Parameters + + + **+** +Causes *TMFPath* to be appended to the existing search path. If the plus (+) token is not used, *TMFPath* replaces the existing search path. + + *TMFPath* +The path to the directory where the debugger should look for the trace message format files. Paths that contain spaces are not supported. If multiple paths are included, they should be separated by semicolons, and the entire string should be enclosed in quotation marks. If the path is in quotation marks, the backslash character must be preceded by an escape character ( `"c:\\debuggers;c:\\debuggers2"` ). When the **+** token is used, *TMFPath* will be appended to the existing path, with a semicolon automatically inserted between the existing path and the new path; however, if the **+** token is used, quotation marks cannot be used. + + + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about trace message format files, see the "Trace Message Format Files" topic in the Windows Driver Kit (WDK). + +Remarks +------- + +When used with no parameters, **!wmitrace.searchpath** displays the current search path. + +The trace message format files (\*.tmf) contain instructions for formatting the binary trace messages that a trace provider generates. + +The *TMFPath* parameter must contain only a path to a directory; it cannot include a file name. The name of a TMF file is a message GUID followed by the .tmf extension. When the system formats a message, it reads the message GUID on the message and searches recursively for a TMF file whose name matches the message GUID, beginning in the specified directory. + +Windows needs a TMF file in order to format the binary trace messages in a buffer. Use **!wmitrace.searchpath** or [**!wmitrace.tmffile**](-wmitrace-tmffile.md) to specify the TMF file before using [**!wmitrace.dynamicprint**](-wmitrace-dynamicprint.md) or [**!wmitrace.logdump**](-wmitrace-logdump.md) to display trace buffer contents. + +If you do not use either **!wmitrace.searchpath** or [**!wmitrace.tmffile**](-wmitrace-tmffile.md), the system uses the value of the TRACE\_FORMAT\_SEARCH\_PATH environment variable. If that variable is not present, it uses the default.tmf file, which is included in Windows. If the system cannot find any formatting information for a trace message, it writes a "No format information found" error message in place of the trace message content. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.searchpath%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-setprefix.md b/windows-driver-docs-pr/debugger/-wmitrace-setprefix.md new file mode 100644 index 0000000000..d8fdbbc279 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-setprefix.md @@ -0,0 +1,202 @@ +--- +title: wmitrace.setprefix +description: The wmitrace.setprefix extension specifies the trace message prefix that is prepended to the trace messages from this session. +ms.assetid: 8712af44-f231-48f6-97ac-56a1d737cd6b +keywords: ["wmitrace.setprefix Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.setprefix +api_type: +- NA +--- + +# !wmitrace.setprefix + + +The **!wmitrace.setprefix** extension specifies the trace message prefix that is prepended to the trace messages from this session. This extension allows you to change the prefix during the debugging session. + +``` +!wmitrace.setprefix [+] PrefixVariables +!wmitrace.setprefix +``` + +## Parameters + + + **+** +Causes *PrefixVariables* to be apended to the trace message prefix. If the **+** token is not used, *PrefixVariables* replaces the existing trace message prefix. + + *PrefixVariables* +A set of variables that specifies the format and data in the trace message prefix. + +The variables have the format %n!x!, where %n represents a data field and !x! represents the data type. You can also include separation characters, such as colons (:), semicolons (;), parentheses ( ( ) ), braces ( { } ), and brackets ( \[ \] ) to separate the fields. + +Each %n variable represents a parameter that is described in the following table. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Prefix variable identifierVariable typeDescription

%1

string

The friendly name of the message GUID of the trace message. By default, the friendly name of a message GUID is the name of the directory in which the trace provider was built.

%2

string

Source file and line number.

+

This variable represents the friendly name of the trace message. By default, the friendly name of a trace message is the name of the source file and the line number of the code that generated the trace message.

%3

ULONG

Thread ID.

+

Identifies the thread that generated the trace message.

%4

string

Time stamp of the time that the trace message was generated.

%5

string

Kernel time.

+

Displays the elapsed execution time for kernel-mode instruction, in CPU ticks, at the time that the trace message was generated.

%6

string

User time.

+

Displays the elapsed execution time for user-mode instruction, in CPU ticks, at the time that the trace message was generated.

%7

LONG

Sequence number.

+

Displays the local or global sequence number of the trace message. Local sequence numbers, which are unique only to this trace session, are the default.

%8

ULONG

Process ID.

+

Identifies the process that generated the trace message.

%9

ULONG

CPU number.

+

Identifies the CPU on which the trace message was generated.

%!FUNC!

string

Function name.

+

Displays the name of the function that generated the trace message.

%!FLAGS%

string

Displays the name of the trace flags that enable the trace message.

%!LEVEL!

string

Displays the value of the trace level that enables the trace message.

%!COMPNAME!

string

Component name.

+

Displays the name of the component of the provider that generated the trace message. The component name appears only if it is specified in the tracing code.

%!SUBCOMP!

string

Subcomponent name.

+

Displays the name of the subcomponent of the provider that generated the trace message. The subcomponent name appears only if it is specified in the tracing code.

+ +  + +The symbol within exclamation marks is a conversion character that specifies the format and precision of the variable. For example, %8!04X! specifies the process ID formatted as a four-digit, unsigned, hexadecimal number. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Example + +The following command changes the trace message prefix in the debugger output to the following format: + +**!wmitrace.setprefix %2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:** + +This extension command sets the trace message prefix to the following format: + +*SourceFile\_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime:* + +As a result, the trace messages are prepended with the specified information in the specified format. The following code example is taken from a trace of the Tracedrv sample driver in the WDK. + +``` +tracedrv_c258: TracedrvDispatchDeviceControl: 0af4.0c64: 07/25/2003-13:55:39.998: IOCTL = 1 +``` + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK documentation. For information about trace message format files, see the "Trace Message Prefix" topic in the WDK documentation. + +Remarks +------- + +When used with no parameters, **!wmitrace.setprefix** displays the current value of the trace message prefix. + +The *trace message prefix* consists of data about the trace message that is prepended to each trace message during Windows software trace preprocessor (WPP) software tracing. This data originates in the trace log (.etl) file and the trace message format (.tmf) file. You can customize the format and data in trace message prefix. + +The default trace message prefix is as follows: + +``` +[%9!d!]%8!04X!.%3!04X!::%4!s! [%1!s!] +``` + +and produces the following prefix: + +``` +[CPUNumber]ProcessID.ThreadID::SystemTime [ProviderDirectory] +``` + +You can change the format and data in the trace message prefix outside of the debugger by setting the %TRACE\_FORMAT\_PREFIX% environment variable. For an example that illustrates how to set the trace message prefix outside of the debugger, see "Example 7: Customizing the Trace Message Prefix" in the Windows Driver Kit (WDK) documentation. If the trace message prefix of your messages varies from the default, this environment variable might be set on your computer. + +The prefix that you set by using this extension command affects only the debugger output. The trace message prefix that appears in the trace log is determined by the default value and the value of the %TRACE\_FORMAT\_PREFIX% environment variable. + +This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested providers do not use trace message format (TMF) files, and therefore this extension does not affect them. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.setprefix%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-start.md b/windows-driver-docs-pr/debugger/-wmitrace-start.md new file mode 100644 index 0000000000..b99cf1a91f --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-start.md @@ -0,0 +1,89 @@ +--- +title: wmitrace.start +description: The wmitrace.start extension starts the Event Tracing for Windows (ETW) logger on the target computer. +ms.assetid: 52ed0c5a-6ca9-4890-bae5-54394bc43d51 +keywords: ["wmitrace.start Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.start +api_type: +- NA +--- + +# !wmitrace.start + + +The **!wmitrace.start** extension starts the Event Tracing for Windows (ETW) logger on the target computer. + +``` +!wmitrace.start LoggerName [-cir Size | -seq Size] [-f File] [-b Size] [-max Num] [-min Num] [-kd] [-ft Time] +``` + +## Parameters + + + *LoggerName* +Supplies a name to be used for the trace session. *LoggerName* cannot contain spaces or quotation marks. + + **-cir** *Size* +Causes the log file to be written in a circular manner. *Size* specifies the maximum file size, in bytes. When the file reaches this length, new data will be written to the file in a circular manner, overwriting the file from beginning to end. This cannot be combined with the **-seq** parameter. If neither **-cir** nor **-seq** is specified, the file is written in buffered mode. + + **-seq** *Num* +Causes the log file to be written in a sequential manner. *Size* specifies the maximum file size, in bytes. When the file reaches this length, the oldest data will be deleted from the beginning of the file whenever new data is appended to the end. This cannot be combined with the **-cir** parameter. If neither **-cir** nor **-seq** is specified, the file is written in buffered mode. + + **-f** *File* +Specifies the name of the log file to be created on the target computer. *File* must include an absolute directory path, and cannot contain spaces or quotation marks. + + **-b** *Size* +Specifies the size of each buffer, in kilobytes. The permissible range of *Size* is between 1 and 2048, inclusive. + + **-max** *Num* +Specifies the maximum number of buffers to use. *Num* can be any positive integer. + + **-min** *Num* +Specifies the minimum number of buffers to use. *Num* can be any positive integer. + + **-kd** +Enables KD filter mode. Messages will be sent to the kernel debugger and displayed on the screen. + + **-ft** *Time* +Specifies the duration of the flush timer, in seconds. Starting in Windows 8, you can specify the flush timer duration in milliseconds by appending **ms** to the *Time* value. For example, **-ft 100ms**. + +**Note**  If you start a tracing session in KD filter mode (**-kd**), trace buffers on the target computer are sent to the debugger on the host computer for display. This parameter specifies how often the buffers on the target computer are flushed and sent to the host computer. + +  + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 7 and later versions of Windows. + +### Additional Information + +For more details on the parameters of this extension, see [StartTrace Function](http://go.microsoft.com/fwlink/p/?linkid=139652) and [EVENT\_TRACE\_PROPERTIES](http://go.microsoft.com/fwlink/p/?linkid=139653) on MSDN. For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +After using this extension, you must resume program execution (for example, by using the [**g (Go)**](g--go-.md) command) in order for it to take effect. After a brief time, the target computer automatically breaks into the debugger again. + +When the trace session is started, the system assigns it an ordinal number (the *logger ID*). The session can then be referred to either by the logger name or the logger ID. + +To stop the ETW logger, use [**!wmitrace.stop**](-wmitrace-stop.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.start%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-stop.md b/windows-driver-docs-pr/debugger/-wmitrace-stop.md new file mode 100644 index 0000000000..30d25baf0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-stop.md @@ -0,0 +1,62 @@ +--- +title: wmitrace.stop +description: The wmitrace.stop extension stops the Event Tracing for Windows (ETW) logger on the target computer. +ms.assetid: 38be65ae-efef-400f-bb10-315d1f6b11d8 +keywords: ["wmitrace.stop Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.stop +api_type: +- NA +--- + +# !wmitrace.stop + + +The **!wmitrace.stop** extension stops the Event Tracing for Windows (ETW) logger on the target computer. + +``` +!wmitrace.stop { LoggerID | LoggerName } +``` + +## Parameters + + + *LoggerID* +Specifies the trace session. *LoggerID* is an ordinal number that the system assigns to each trace session on the computer. + + *LoggerName* +Specifies the trace session. *LoggerName* is the text name that was specified when the trace session was started. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 7 and later versions of Windows. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK). + +Remarks +------- + +After using this extension, you must resume program execution (for example, by using the [**g (Go)**](g--go-.md) command) in order for it to take effect. After a brief time, the target computer automatically breaks into the debugger again. + +To start the ETW logger, use [**!wmitrace.start**](-wmitrace-start.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.stop%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-strdump.md b/windows-driver-docs-pr/debugger/-wmitrace-strdump.md new file mode 100644 index 0000000000..00ef9fe0bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-strdump.md @@ -0,0 +1,60 @@ +--- +title: wmitrace.strdump +description: The wmitrace.strdump extension displays the WMI event trace structures. You can limit the display to the structures for a particular trace session. +ms.assetid: 3fd1c4d5-c3c6-40b5-90f4-e5453bb56b19 +keywords: ["wmitrace.strdump Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.strdump +api_type: +- NA +--- + +# !wmitrace.strdump + + +The **!wmitrace.strdump** extension displays the WMI event trace structures. You can limit the display to the structures for a particular trace session. + +``` +!wmitrace.strdump [ LoggerID | LoggerName ] +``` + +## Parameters + + + *LoggerID* +Limits the display to the event trace structures for the specified trace session. *LoggerID* specifies the trace session. It is an ordinal number that the system assigns to each trace session on the computer. If no parameter is specified, all trace sessions are displayed. + + *LoggerName* +Limits the display to the event trace structures for the specified trace session. *LoggerName* is the text name that was specified when the trace session was started. If no parameter is specified, all trace sessions are displayed. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about Tracelog, see the "Tracelog" topic in the Windows Driver Kit (WDK). + +Remarks +------- + +To find the logger ID of a trace session, use the **!wmitrace.strdump** extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and their basic properties, including the logger ID. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.strdump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-tfp.md b/windows-driver-docs-pr/debugger/-wmitrace-tfp.md new file mode 100644 index 0000000000..f23804ea72 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-tfp.md @@ -0,0 +1,23 @@ +--- +title: wmitrace.tfp +description: wmitrace.tfp +ms.assetid: c81f0794-a622-4400-8966-f49e031ae279 +--- + +# !wmitrace.tfp + + +## + + +The **!wmitrace.tfp** extension command is obsolete. Use [**!wmitrace.setprefix**](-wmitrace-setprefix.md) instead. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.tfp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-tmffile.md b/windows-driver-docs-pr/debugger/-wmitrace-tmffile.md new file mode 100644 index 0000000000..4404964251 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-tmffile.md @@ -0,0 +1,71 @@ +--- +title: wmitrace.tmffile +description: The wmitrace.tmffile extension specifies a trace message format (TMF) file. The file specified by this extension is used to format trace messages displayed or written by other WMI tracing extensions. +ms.assetid: 37ad335b-7604-466b-b328-7aebbc2fb5c1 +keywords: ["wmitrace.tmffile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.tmffile +api_type: +- NA +--- + +# !wmitrace.tmffile + + +The **!wmitrace.tmffile** extension specifies a trace message format (TMF) file. The file specified by this extension is used to format trace messages displayed or written by other WMI tracing extensions. + +``` +!wmitrace.tmffile TMFFile +``` + +## Parameters + + + *TMFFile* +Specifies a trace message format file. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about trace message format files, see the "Trace Message Format File" topic in the Windows Driver Kit (WDK). + +Remarks +------- + +*Trace message format files* (.tmf) are structured text files that are created during Windows software trace preprocessor (WPP) software tracing. These files contain instructions for formatting trace binary trace messages so that they can be displayed in human-readable form. + +In order to display the trace message in a trace buffer ([**!wmitrace.logdump**](-wmitrace-logdump.md)) or write them to a file [**(!wmitrace.logsave**](-wmitrace-logsave.md)), you must first identify the TMF files for the trace messages. + +You can use [**!wmitrace.searchpath**](-wmitrace-searchpath.md) to specify a directory in which TMF files are stored. The system then searches the directory for a TMF file that contains instructions for the messages that it is formatting. (It uses the message GUID to associate the message with the correct TMF file.) + +However, you can use **!wmitrace.tmffile** to specify a particular TMF file. You must use **!wmitrace.tmffile** if the TMF file name is not a message GUID followed by the .tmf extension. Otherwise, the system will not find it. + +If you do not use either [**!wmitrace.searchpath**](-wmitrace-searchpath.md) or **!wmitrace.tmffile**, the system uses the value of the TRACE\_FORMAT\_SEARCH\_PATH environment variable. If that variable is not present, it uses the default.tmf file. If the system cannot find formatting information for a trace message, it writes a "No format information found" error message, instead of the trace message content. + +**Note**  If your driver uses UMDF version 1.11 or later, you do not need to use [**!wmitrace.searchpath**](-wmitrace-searchpath.md) or **!wmitrace.tmffile**. + +  + +This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested providers do not use trace message format (TMF) files, and therefore this extension cannot be used with them. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.tmffile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wmitrace-traceoperation.md b/windows-driver-docs-pr/debugger/-wmitrace-traceoperation.md new file mode 100644 index 0000000000..1512dfeb97 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wmitrace-traceoperation.md @@ -0,0 +1,63 @@ +--- +title: wmitrace.traceoperation +description: The wmitrace.traceoperation extension displays the progress messages from the tracing components in Windows. +ms.assetid: 92d189fe-fb3b-40a6-81a8-9e66868c4d1d +keywords: ["wmitrace.traceoperation Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wmitrace.traceoperation +api_type: +- NA +--- + +# !wmitrace.traceoperation + + +The **!wmitrace.traceoperation** extension displays the progress messages from the tracing components in Windows. + +``` +!wmitrace.traceoperation {0 | 1 | 2} +``` + +## Parameters + + + **0** +Disables the display of tracing progress messages. + + **1** +Enables the display of tracing progress messages. All messages generated by the WMI tracing debugger extensions are displayed. + + **2** +Enables the display of tracing progress messages. All messages generated by the WMI tracing debugger extensions or by Tracefmt are displayed. + +### DLL + +This extension is exported by Wmitrace.dll. + +This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory. + +### Additional Information + +For a conceptual overview of event tracing, see the Microsoft Windows SDK. + +Remarks +------- + +This extension causes the tracing components to display verbose output. This feature is useful to troubleshoot software tracing. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wmitrace.traceoperation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-write-cmd-hist--write-command-history-.md b/windows-driver-docs-pr/debugger/-write-cmd-hist--write-command-history-.md new file mode 100644 index 0000000000..697ed61952 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-write-cmd-hist--write-command-history-.md @@ -0,0 +1,69 @@ +--- +title: .write_cmd_hist (Write Command History) +description: The .write_cmd_hist command writes the entire history of the Debugger Command window to a file. +ms.assetid: 7d512f0c-56cd-48e5-b618-d5615113f065 +keywords: [".write_cmd_hist (Write Command History) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .write_cmd_hist (Write Command History) +api_type: +- NA +--- + +# .write\_cmd\_hist (Write Command History) + + +The **.write\_cmd\_hist** command writes the entire history of the Debugger Command window to a file. + +``` +.write_cmd_hist Filename +``` + +## Parameters + + + *Filename* +Specifies the path and filename of the file that will be created. + +### Environment + +This command is available only in WinDbg and cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.write_cmd_hist%20%28Write%20Command%20History%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-writemem--write-memory-to-file-.md b/windows-driver-docs-pr/debugger/-writemem--write-memory-to-file-.md new file mode 100644 index 0000000000..fd8a15b06e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-writemem--write-memory-to-file-.md @@ -0,0 +1,77 @@ +--- +title: .writemem (Write Memory to File) +description: The .writemem command writes a section of memory to a file. +ms.assetid: 928e9452-d9b4-49fa-a5fa-cdc3832d7349 +keywords: [".writemem (Write Memory to File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .writemem (Write Memory to File) +api_type: +- NA +--- + +# .writemem (Write Memory to File) + + +The **.writemem** command writes a section of memory to a file. + +``` +.writemem FileName Range +``` + +## Parameters + + + *FileName* +Specifies the name of the file to be created. You can specify a full path and file name, or just the file name. If the file name contains spaces, *FileName* should be enclosed in quotation marks. If no path is specified, the current directory is used. + + *Range* +Specifies the memory range to be written to the file. For syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +The memory is copied literally to the file. It is not parsed in any way. + +The **.writemem** command is the opposite of the [**.readmem (Read Memory from File)**](-readmem--read-memory-from-file-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.writemem%20%28Write%20Memory%20to%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wsle.md b/windows-driver-docs-pr/debugger/-wsle.md new file mode 100644 index 0000000000..835b329ef8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wsle.md @@ -0,0 +1,100 @@ +--- +title: wsle +description: The wsle extension displays all working set list entries (WSLEs). +ms.assetid: 9540ac44-a44b-4af6-acdd-baa275e8d004 +keywords: ["wsle Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wsle +api_type: +- NA +--- + +# !wsle + + +The **!wsle** extension displays all working set list entries (WSLEs). + +Syntax + +``` +!wsle [Flags [Address]] +``` + +## Parameters + + + *Flags* +Specifies the information to include in the display. This can be any combination of the following bits. The default is zero. If this is used, only basic information about the working set is displayed. + +Bit 0 (0x1) +Causes the display to include information about each WSLE's address, age, lock status, and reference count. If a WSLE has an invalid page table entry (PTE) or page directory entry (PDE) associated with it, this is also displayed. + +Bit 1 (0x2) +Causes the display to include the total number of valid WSLEs, the index of the last WSLE, and the index of the first free WSLE. + +Bit 2 (0x4) +Causes the display to include the total number of free WSLEs, as well as the index of each free WSLE. If bit 1 is also set, then a check is done to make sure that the number of free WSLEs plus the number of valid WSLEs is actually equal to the total number of WSLEs. + + *Address* +Specifies the address of the working set list. If this is omitted, the default working set list is used. Specifying zero for *Address* is the same as omitting it. + +### DLL + +Kdexts.dll + +### Additional Information + +For information about working sets, see the Windows Driver Kit (WDK) documentation and *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +Remarks +------- + +This extension can take a significant amount of time to execute. + +Here is an example from an x86 target computer running Windows Server 2003: + +``` +kd> !wsle 3 + +Working Set @ c0503000 + FirstFree: a7 FirstDynamic: 4 + LastEntry 23d NextSlot: 4 LastInitialized 259 + NonDirect 65 HashTable: 0 HashTableSize: 0 + +Reading the WSLE data... + +Virtual Address Age Locked ReferenceCount + c0300203 0 1 1 + c0301203 0 1 1 + c0502203 0 1 1 + c0503203 0 1 1 + c01ff201 0 0 1 + 77f74d19 3 0 1 + 7ffdfa01 2 0 1 + c0001201 0 0 1 + +..... + +Reading the WSLE data... +Valid WSLE entries = 0xa7 +found end @ wsle index 0x259 + +..... +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wsle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wtitle--set-window-title-.md b/windows-driver-docs-pr/debugger/-wtitle--set-window-title-.md new file mode 100644 index 0000000000..af61ed44ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wtitle--set-window-title-.md @@ -0,0 +1,80 @@ +--- +title: .wtitle (Set Window Title) +description: The .wtitle command sets the title in the main WinDbg window or in the NTSD, CDB, or KD window. +ms.assetid: 9ff74a70-22fd-4bb7-b124-f262a37cfd1f +keywords: [".wtitle (Set Window Title) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- .wtitle (Set Window Title) +api_type: +- NA +--- + +# .wtitle (Set Window Title) + + +The **.wtitle** command sets the title in the main WinDbg window or in the NTSD, CDB, or KD window. + +``` +.wtitle Title +``` + +## Parameters + + + *Title* +The title to use for the window. + +### Environment + +This command cannot be used in script files. + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +For CDB, NTSD, or KD, if the **.wtitle** command has not been used, the window title matches the command line used to launch the debugger. + +For WinDbg, if **.wtitle** has not been used, the main window title includes the name of the target. If a debugging server is active, its connection string is displayed as well. If multiple debugging servers are active, only the most recent one is displayed. + +When **.wtitle** is used, *Title* replaces all this information. Even if a debugging server is started later, *Title* will not change. + +The WinDbg version number is always displayed in the window title bar, regardless of whether this command is used. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20.wtitle%20%28Set%20Window%20Title%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-help.md b/windows-driver-docs-pr/debugger/-wudfext-help.md new file mode 100644 index 0000000000..50b51494ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-help.md @@ -0,0 +1,61 @@ +--- +title: wudfext.help +description: The wudfext.help extension displays all Wudfext.dll extension commands. +ms.assetid: b81ffdae-8178-4e98-b8d8-50fee7b511c9 +keywords: ["wudfext.help Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.help +api_type: +- NA +--- + +# !wudfext.help + + +The **!wudfext.help** extension displays all Wudfext.dll extension commands. + +``` +!wudfext.help +``` + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.help%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-umdevstack.md b/windows-driver-docs-pr/debugger/-wudfext-umdevstack.md new file mode 100644 index 0000000000..d095c214ef --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-umdevstack.md @@ -0,0 +1,93 @@ +--- +title: wudfext.umdevstack +description: The wudfext.umdevstack extension displays detailed information about a device stack in the host process. +ms.assetid: 3cce0e30-ea04-4587-9208-b6a7d51fd44a +keywords: ["wudfext.umdevstack Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.umdevstack +api_type: +- NA +--- + +# !wudfext.umdevstack + + +The **!wudfext.umdevstack** extension displays detailed information about a device stack in the host process. + +``` +!wudfext.umdevstack DevstackAddress [Flags] +``` + +## Parameters + + + *DevstackAddress* +Specifies the address of the device stack to display information about. + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays detailed information about the device stack. + +Bit 8 (0x80) +Displays information about the internal framework. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The following is an example of the **!wudfext.umdevstack** display: + +``` +kd> !umdevstack 0x0034e4e0 +Device Stack: 0x0034e4e0 Pdo Name: \Device\00000057 + Number of UM drivers: 0x1 + Driver 00: + Driver Config Registry Path: WUDFEchoDriver + UMDriver Image Path: C:\Windows\system32\DRIVERS\UMDF\WUDFEchoDriver.dll + Fx Driver: IWDFDriver 0xf2db8 + Fx Device: IWDFDevice 0xf2f80 + IDriverEntry: WUDFEchoDriver!CMyDriver 0x000f2c70 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.umdevstack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-umdevstacks.md b/windows-driver-docs-pr/debugger/-wudfext-umdevstacks.md new file mode 100644 index 0000000000..35e30a9c93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-umdevstacks.md @@ -0,0 +1,102 @@ +--- +title: wudfext.umdevstacks +description: The wudfext.umdevstacks extension displays information about all device stacks in the current host process. +ms.assetid: e69420fc-97b8-420f-b635-bee41fbf4586 +keywords: ["wudfext.umdevstacks Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.umdevstacks +api_type: +- NA +--- + +# !wudfext.umdevstacks + + +The **!wudfext.umdevstacks** extension displays information about all device stacks in the current host process. + +``` +!wudfext.umdevstacks [Flags] +``` + +## Parameters + + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays detailed information about each device stack. + +Bit 8 (0x80) +Displays information about the internal framework. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The **!wudfext.umdevstacks** extension displays the framework interface objects that are associated with each device stack. For more information about using the output from **!wudfext.umdevstacks**, see [**!wudfext.umdevstack**](-wudfext-umdevstack.md). + +The **!wudfext.umdevstacks** output includes two fields entitled "Object Tracking" and "Refcount Tracking". These indicate whether the object tracking option (**TrackObjects**) and the reference count tracking option (**TrackRefCounts**) have been enabled in WDF Verifier, respectively. If the object tracking option has been enabled, the display includes the object tracker address; this address can be passed to [**!wudfext.wudfdumpobjects**](-wudfext-wudfdumpobjects.md) to display tracking information. + +Here is an example of the **!wudfext.umdevstacks** display: + +``` +0: kd> !umdevstacks +Number of device stacks: 1 + Device Stack: 0x038c6f08 Pdo Name: \Device\USBPDO-11 + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: WUDFOsrUsbFx2 + UMDriver Image Path: D:\Windows\system32\DRIVERS\UMDF\WUDFOsrUsbFx2.dll + Fx Driver: IWDFDriver 0x3076ff0 + Fx Device: IWDFDevice 0x3082e70 + IDriverEntry: WUDFOsrUsbFx2!CMyDriver 0x0306eff8 + Open UM files (use !umfile for details): + 0x04a8ef84 + Device XFerMode: CopyImmediately RW: Buffered CTL: Buffered + Object Tracker Address: 0x03074fd8 + Object Tracking ON + Refcount Tracking OFF + DevStack XFerMode: CopyImmediately RW: Buffered CTL: Buffered +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.umdevstacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-umfile.md b/windows-driver-docs-pr/debugger/-wudfext-umfile.md new file mode 100644 index 0000000000..c7327af239 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-umfile.md @@ -0,0 +1,67 @@ +--- +title: wudfext.umfile +description: The wudfext.umfile extension displays information about a UMDF intra-stack file. +ms.assetid: cd796f73-702e-488d-929d-ac77801c74f4 +keywords: ["wudfext.umfile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.umfile +api_type: +- NA +--- + +# !wudfext.umfile + + +The **!wudfext.umfile** extension displays information about a UMDF intra-stack file. + +``` +!wudfext.umfile Address +``` + +## Parameters + + + *Address* +Specifies the address of the UMDF intra-stack file to display information about. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.umfile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-umirp.md b/windows-driver-docs-pr/debugger/-wudfext-umirp.md new file mode 100644 index 0000000000..fe0f31511a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-umirp.md @@ -0,0 +1,109 @@ +--- +title: wudfext.umirp +description: The wudfext.umirp extension displays information about a host user-mode I/O request packet (UM IRP). +ms.assetid: b31b864d-0c94-48b8-9ffd-f14639b9a551 +keywords: ["wudfext.umirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.umirp +api_type: +- NA +--- + +# !wudfext.umirp + + +The **!wudfext.umirp** extension displays information about a host user-mode I/O request packet (UM IRP). + +``` +!wudfext.umirp Address +``` + +## Parameters + + + *Address* +Specifies the address of the UM IRP to display information about. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use the [**!wudfext.umirps**](-wudfext-umirps.md) extension command to display a list of all outstanding UM IRPs in the host process. + +Each UM IRP has one or more stack locations. Each stack location corresponds to the parameters that a single driver in the device stack will receive when it is called to handle a request. + +**!wudfext.umirp** dumps all of the stack locations and marks the current location with a right angle bracket (>). The current location corresponds to the driver that currently owns the request. The current location changes when a driver forwards a request to the next lower driver in the stack, or when the driver completes a request that the driver owns. + +The following is an example of the **!wudfext.umirp** display: + +``` +kd> !umirp 3dd480 +UM IRP: 0x003dd480 UniqueId: 0xde Kernel Irp: 0x0x85377850 + Type: WudfMsg_READ + ClientProcessId: 0x338 + Device Stack: 0x0034e4e0 + IoStatus + hrStatus: 0x0 + Information: 0x0 + Driver/Framework created IRP: No + Data Buffer: 0x00000000 / 0 + IsFrom32BitProcess: Yes + CancelFlagSet: No + Cancel callback: 0x01102224 + Total number of stack locations: 2 + CurrentStackLocation: 2 (StackLocation[ 1 ]) + StackLocation[ 0 ] + UNINITIALIZED + > StackLocation[ 1 ] + IWDFRequest: ???? + IWDFDevice: 0x000f2f80 + IWDFFile: 0x003a7648 + Completion: + Callback: 0x00000000 + Context: 0x00000000 + Parameters: (RequestType: WdfRequestRead) + Buffer length: 0x400 + Key: 0x00000000 + Offset: 0x0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.umirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-umirps.md b/windows-driver-docs-pr/debugger/-wudfext-umirps.md new file mode 100644 index 0000000000..f8c411706a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-umirps.md @@ -0,0 +1,101 @@ +--- +title: wudfext.umirps +description: The wudfext.umirps extension displays the list of pending user-mode I/O request packets (UM IRPs) in the host process. +ms.assetid: bba78784-f4f5-432c-ad5e-837770de79d9 +keywords: ["wudfext.umirps Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.umirps +api_type: +- NA +--- + +# !wudfext.umirps + + +The **!wudfext.umirps** extension displays the list of pending user-mode I/O request packets (UM IRPs) in the host process. + +``` +!wudfext.umirps NumberOfIrps Flags +``` + +## Parameters + + + *NumberOfIrps* +Optional. Specifies the number of pending UM IRPs to display information about. If *NumberOfIrps* is an asterisk (\*) or is omitted, all UM all UM IRPs will be displayed. + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Displays details about the pending IRPs. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The list of pending UM IRPs that are displayed have either been presented to the driver or are waiting to be presented to the driver. + +By default, **!wudfext.umirps** shows all UM IRPs. However, you can use the *NumberOfIrps* parameter to limit this display. + +The following is an example of the **!wudfext.umirps** display: + +``` +kd> !umirps 0xa +Number of pending IRPS: 0xc8 +#### CWudfIrp Type UniqueId KernelIrp +---- ---------------- ---------- ---------------- --------- +0000 3dd280 READ dc 856f02f0 +0001 3dd380 WRITE dd 85b869e0 +0002 3dd480 READ de 85377850 +0003 3dd580 READ df 93bba4e8 +0004 3dd680 WRITE e0 84cb9d70 +0005 3dd780 READ e1 85bec150 +0006 3dd880 WRITE e2 86651db0 +0007 3dd980 READ e3 85c22818 +0008 3dda80 READ e4 9961d150 +0009 3ddb80 WRITE e5 85c15148 +``` + +To determine the corresponding kernel-mode IRP, use the [**!wudfext.wudfdownkmirp**](-wudfext-wudfdownkmirp.md) extension. Alternatively, you can use the values in the **UniqueId** and **KernelIrp** columns to match a UMDF IRP (or UM IRP) to a corresponding kernel IRP. You can pass the values in the **CWudfIrp** column to the [**!wudfext.umirp**](-wudfext-umirp.md) extension to determine the framework **IWDFRequest** objects that each layer in the device stack can access. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.umirps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfdevice.md b/windows-driver-docs-pr/debugger/-wudfext-wudfdevice.md new file mode 100644 index 0000000000..2c9e001e11 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfdevice.md @@ -0,0 +1,130 @@ +--- +title: wudfext.wudfdevice +description: The wudfext.wudfdevice extension displays the Plug and Play (PnP) and power-management state systems for a device. +ms.assetid: d070f5ba-97c0-47f8-869f-54a3d3395476 +keywords: ["wudfext.wudfdevice Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfdevice +api_type: +- NA +--- + +# !wudfext.wudfdevice + + +The **!wudfext.wudfdevice** extension displays the Plug and Play (PnP) and power-management state systems for a device. + +``` +!wudfext.wudfdevice pWDFDevice +``` + +## Parameters + + + *pWDFDevice* +Specifies the address of the **IWDFDevice** interface to display PnP or power-management state about. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use the **!wudfext.wudfdevice** extension to determine the current PnP or power-management state of the device that the *pWDFDevice* parameter specifies. + +The following is an example of the **!wudfext.wudfdevice** display: + +``` +kd> !wudfdevice 0xf2f80 +Pnp Driver Callbacks: + IPnpCallback: 0x0 + IPnpCallbackHardware: 0x0 + IPnpSelfManagedIo: 0x0 +Pnp State Machine: + CurrentState: WdfDevStatePnpStarted + Pending UMIrp: 0x00000000 + Could not read event queue depth, assuming 8 + Event queue: + Processed/in-process events: + PnpEventAddDevice + PnpEventStartDevice + PnpEventPwrPolStarted + Pending events: + State History: + WdfDevStatePnpInit + WdfDevStatePnpInitStarting + WdfDevStatePnpHardwareAvailable + WdfDevStatePnpEnableInterfaces + WdfDevStatePnpStarted +Power State Machine: + CurrentState: WdfDevStatePowerD0 + Pending UMIrp: 0x00000000 + IoCallbackFailure: false + Could not read event queue depth, assuming 8 + Event queue: + Processed/in-process events: + PowerImplicitD0 + Pending events: + State History: + WdfDevStatePowerStartingCheckDeviceType + WdfDevStatePowerD0Starting + WdfDevStatePowerD0StartingConnectInterrupt + WdfDevStatePowerD0StartingDmaEnable + WdfDevStatePowerD0StartingStartSelfManagedIo + WdfDevStatePowerDecideD0State + WdfDevStatePowerD0 +Power Policy State Machine: + CurrentState : WdfDevStatePwrPolStartingSucceeded + PowerPolicyOwner : false + PendingSystemPower UMIrp : 0x00000000 + PowerFailed : false + Could not read event queue depth, assuming 8 + Event queue: + Processed/in-process events: + PwrPolStart + PwrPolPowerUp + Pending events: + State History: + WdfDevStatePwrPolStarting + WdfDevStatePwrPolStarted + WdfDevStatePwrPolStartingSucceeded +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfdevice%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfdevicequeues.md b/windows-driver-docs-pr/debugger/-wudfext-wudfdevicequeues.md new file mode 100644 index 0000000000..412b211233 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfdevicequeues.md @@ -0,0 +1,90 @@ +--- +title: wudfext.wudfdevicequeues +description: The wudfext.wudfdevicequeues extension displays information about all the I/O queues for a device. +ms.assetid: 985e6d93-018f-436a-a75c-088251398539 +keywords: ["wudfext.wudfdevicequeues Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfdevicequeues +api_type: +- NA +--- + +# !wudfext.wudfdevicequeues + + +The **!wudfext.wudfdevicequeues** extension displays information about all the I/O queues for a device. + +``` +!wudfext.wudfdevicequeues pWDFDevice +``` + +## Parameters + + + *pWDFDevice* +Specifies the address of the **IWDFDevice** interface for which to display information about all of its associated I/O queues. The [**!wudfext.wudfdriverinfo**](-wudfext-wudfdriverinfo.md) extension command determines the address of **IWDFDevice**. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The following is an example of the **!wudfext.wudfdevicequeues** display: + +``` +## kd> !wudfdevicequeues 0xf2f80 +-------------------------------------------------- +Queue: 1 (!wudfqueue 0x000f3500) + WdfIoQueueDispatchSequential, POWER MANAGED, WdfIoQueuePowerOn, CAN ACCEPT, CAN DISPATCH + Number of driver owned requests: 1 + IWDFIoRequest 0x000fa7c0 CWdfIoRequest 0x000fa748 + Number of waiting requests: 199 + IWDFIoRequest 0x000fa908 CWdfIoRequest 0x000fa890 + IWDFIoRequest 0x000faa50 CWdfIoRequest 0x000fa9d8 +... + IWDFIoRequest 0x000fa678 CWdfIoRequest 0x000fa600 + Driver's callback interfaces. + IQueueCallbackRead 0x000f343c + IQueueCallbackDeviceIoControl 0x000f3438 + IQueueCallbackWrite 0x000f3440 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfdevicequeues%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfdownkmirp.md b/windows-driver-docs-pr/debugger/-wudfext-wudfdownkmirp.md new file mode 100644 index 0000000000..c13e6506e3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfdownkmirp.md @@ -0,0 +1,72 @@ +--- +title: wudfext.wudfdownkmirp +description: The wudfext.downkmmirp extension displays the kernel-mode I/O request packet (IRP) that corresponds to the specified user-mode I/O request packet (UM IRP). +ms.assetid: f5c42040-2349-4469-a398-12a238ff170e +keywords: ["wudfext.wudfdownkmirp Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfdownkmirp +api_type: +- NA +--- + +# !wudfext.wudfdownkmirp + + +The **!wudfext.downkmmirp** extension displays the kernel-mode I/O request packet (IRP) that corresponds to the specified user-mode I/O request packet (UM IRP). + +``` +!wudfext.wudfdownkmirp Address +``` + +## Parameters + + + *Address* +Specifies the address of the UM IRP whose corresponding kernel-mode IRP is to be displayed. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use the [**!wudfext.umirps**](-wudfext-umirps.md) extension command to display a list of all outstanding UM IRPs in the host process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfdownkmirp%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfdriverinfo.md b/windows-driver-docs-pr/debugger/-wudfext-wudfdriverinfo.md new file mode 100644 index 0000000000..11755703e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfdriverinfo.md @@ -0,0 +1,83 @@ +--- +title: wudfext.wudfdriverinfo +description: The wudfext.wudfdriverinfo extension displays information about a UMDF driver within the current host process. +ms.assetid: 6204df00-2de5-41b6-80c1-ba576699fb20 +keywords: ["wudfext.wudfdriverinfo Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfdriverinfo +api_type: +- NA +--- + +# !wudfext.wudfdriverinfo + + +The **!wudfext.wudfdriverinfo** extension displays information about a UMDF driver within the current host process. + +``` +!wudfext.wudfdriverinfo Name +``` + +## Parameters + + + *Name* +Specifies the name of the UMDF driver to display information about. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The **!wudfext.wudfdriverinfo** extension iterates through each level in each device stack and displays the driver and device information for each entry that matches the driver whose name is specified in the *Name* parameter. + +You can use **!wudfext.wudfdriverinfo** to quickly find the device object for your driver. + +The following is an example of the **!wudfext.wudfdriverinfo** display: + +``` +kd> !wudfdriverinfo wudfechodriver +IWDFDriver: 0xf2db8 + !WDFDEVICE 0xf2f80 + !devstack 0x34e4e0 @ level 0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfdriverinfo%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfdumpobjects.md b/windows-driver-docs-pr/debugger/-wudfext-wudfdumpobjects.md new file mode 100644 index 0000000000..40a0da9f14 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfdumpobjects.md @@ -0,0 +1,123 @@ +--- +title: wudfext.wudfdumpobjects +description: The wudfext.wudfdumpobjects extension displays outstanding UMDF objects. +ms.assetid: 2ede7f2e-124c-494d-9188-5a28617a0bdb +keywords: ["wudfext.wudfdumpobjects Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfdumpobjects +api_type: +- NA +--- + +# !wudfext.wudfdumpobjects + + +The **!wudfext.wudfdumpobjects** extension displays outstanding UMDF objects. + +``` +!wudfext.wudfdumpobjects ObjTrackerAddress +``` + +## Parameters + + + *ObjTrackerAddress* +Specifies the address to track leaked objects. This address is displayed in the driver-stop message in the debugger when a leak occurs. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +If the UMDF object tracking option (**TrackObjects**) has been enabled in WDF Verifier, you can use **!wudfext.wudfdumpobjects** to see any leaked objects that remain after the driver unloads. + +If the **TrackObjects** option has been enabled, the address of the object tracker is automatically displayed when a leak is detected. Use this address as *ObjTrackerAddress* when executing **!wudfext.wudfdumpobjects**. + +This extension can be used at any time, even if UMDF has not broken in to the debugger. + +If UMDF is version 1.9 or above, you can use either [**!wudfext.umdevstack**](-wudfext-umdevstack.md) or [**!wudfext.umdevstacks**](-wudfext-umdevstacks.md) to determine the address of the object tracker. This address can then be passed to **!wudfext.wudfdumpobjects**. Here is an example: + +``` +0: kd> !umdevstacks +Number of device stacks: 1 + Device Stack: 0x038c6f08 Pdo Name: \Device\USBPDO-11 + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: WUDFOsrUsbFx2 + UMDriver Image Path: D:\Windows\system32\DRIVERS\UMDF\WUDFOsrUsbFx2.dll + Fx Driver: IWDFDriver 0x3076ff0 + Fx Device: IWDFDevice 0x3082e70 + IDriverEntry: WUDFOsrUsbFx2!CMyDriver 0x0306eff8 + Open UM files (use !umfile for details): + 0x04a8ef84 + Device XFerMode: CopyImmediately RW: Buffered CTL: Buffered + Object Tracker Address: 0x03074fd8 + Object Tracking ON + Refcount Tracking OFF + DevStack XFerMode: CopyImmediately RW: Buffered CTL: Buffered + +0: kd> !wudfdumpobjects 0x03074fd8 +WdfTypeDriver Object: 0x03076fb0, Interface: 0x03076ff0 +WdfTypeDevice Object: 0x03082e30, Interface: 0x03082e70 +WdfTypeIoTarget Object: 0x03088f50, Interface: 0x03088f90 +WdfTypeIoQueue Object: 0x0308ce58, Interface: 0x0308ce98 +WdfTypeIoQueue Object: 0x03090e58, Interface: 0x03090e98 +WdfTypeIoQueue Object: 0x03092e58, Interface: 0x03092e98 +WdfTypeIoTarget Object: 0x03098f40, Interface: 0x03098f80 +WdfTypeFile Object: 0x0309cfa0, Interface: 0x0309cfe0 +WdfTypeUsbInterface Object: 0x030a0f98, Interface: 0x030a0fd8 +WdfTypeRequest Object: 0x030a2ef8, Interface: 0x030a2f38 +WdfTypeIoTarget Object: 0x030a6f30, Interface: 0x030a6f70 +WdfTypeIoTarget Object: 0x030aaf30, Interface: 0x030aaf70 +WdfTypeIoTarget Object: 0x030aef30, Interface: 0x030aef70 +WdfTypeRequest Object: 0x030c6ef8, Interface: 0x030c6f38 +WdfTypeRequest Object: 0x030ceef8, Interface: 0x030cef38 +WdfTypeMemoryObject Object: 0x030d6fb0, Interface: 0x030d6ff0 +WdfTypeMemoryObject Object: 0x030dcfb0, Interface: 0x030dcff0 +WdfTypeFile Object: 0x030e4fa8, Interface: 0x030e4fe8 +WdfTypeFile Object: 0x030e6fa8, Interface: 0x030e6fe8 +WdfTypeFile Object: 0x030e8fa8, Interface: 0x030e8fe8 +WdfTypeRequest Object: 0x030eaef8, Interface: 0x030eaf38 +WdfTypeMemoryObject Object: 0x030ecfb0, Interface: 0x030ecff0 +WdfTypeMemoryObject Object: 0x030eefb0, Interface: 0x030eeff0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfdumpobjects%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudffile.md b/windows-driver-docs-pr/debugger/-wudfext-wudffile.md new file mode 100644 index 0000000000..7b4c16b15e --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudffile.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudffile +description: The wudfext.wudffile extension displays information about a framework file. +ms.assetid: f655703d-0e61-4e9c-a033-834a89ef6d05 +keywords: ["wudfext.wudffile Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudffile +api_type: +- NA +--- + +# !wudfext.wudffile + + +The **!wudfext.wudffile** extension displays information about a framework file. + +``` +!wudfext.wudffile pWDFFile [TypeName] +``` + +## Parameters + + + *pWDFFile* +Specifies the address of the **IWDFFile** interface to display information about. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudffile%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudffilehandletarget.md b/windows-driver-docs-pr/debugger/-wudfext-wudffilehandletarget.md new file mode 100644 index 0000000000..1b692f487a --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudffilehandletarget.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudffilehandletarget +description: The wudfext.wudffilehandletarget extension displays information about a file-handle-based I/O target. +ms.assetid: 14adf5ea-57d1-4ae5-8944-a643edd6ff39 +keywords: ["wudfext.wudffilehandletarget Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudffilehandletarget +api_type: +- NA +--- + +# !wudfext.wudffilehandletarget + + +The **!wudfext.wudffilehandletarget** extension displays information about a file-handle-based I/O target. + +``` +!wudfext.wudffilehandletarget pWDFFileHandleTarget TypeName +``` + +## Parameters + + + *pWDFFileHandleTarget* +Specifies the address of the **IWDFIoTarget** interface to display information about. The [**!wudfext.wudfobject**](-wudfext-wudfobject.md) extension command determines the address of **IWDFIoTarget**. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudffilehandletarget%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfiotarget.md b/windows-driver-docs-pr/debugger/-wudfext-wudfiotarget.md new file mode 100644 index 0000000000..4b473e0fca --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfiotarget.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudfiotarget +description: The wudfext.wudfiotarget extension displays information about an I/O target including the target's state and list of sent requests. +ms.assetid: ccd241d6-c9c8-4518-902c-f119cf5b73fe +keywords: ["wudfext.wudfiotarget Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfiotarget +api_type: +- NA +--- + +# !wudfext.wudfiotarget + + +The **!wudfext.wudfiotarget** extension displays information about an I/O target including the target's state and list of sent requests. + +``` +!wudfext.wudfiotarget pWDFTarget TypeName +``` + +## Parameters + + + *pWDFTarget* +Specifies the address of the **IWDFIoTarget** interface to display information about. The [**!wudfext.wudfobject**](-wudfext-wudfobject.md) extension command determines the address of **IWDFIoTarget**. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfiotarget%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfobject.md b/windows-driver-docs-pr/debugger/-wudfext-wudfobject.md new file mode 100644 index 0000000000..4278e9ddae --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfobject.md @@ -0,0 +1,177 @@ +--- +title: wudfext.wudfobject +description: The wudfext.wudfobject extension displays information about a WDF object, as well as its parent and child relationships. +ms.assetid: cb9398fb-24f5-4692-9a08-543bf1317b19 +keywords: ["wudfext.wudfobject Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfobject +api_type: +- NA +--- + +# !wudfext.wudfobject + + +The **!wudfext.wudfobject** extension displays information about a WDF object, as well as its parent and child relationships. + +``` +!wudfext.wudfobject pWDFObject Flags TypeName +``` + +## Parameters + + + *pWDFObject* +Specifies the address of the WDF interface to display information about. + + *Flags* +Optional. Specifies the type of information to be displayed. *Flags* can be any combination of the following bits. The default value is 0x01. + +Bit 0 (0x01) +Steps recursively through the object hierarchy to obtain the parent and child relationships, which are displayed. + +Bit 1 (0x02) +Displays only summary information about the object. + +Bit 8 (0x80) +Steps recursively through the object hierarchy, and displays details about the internal framework. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +You can use **!wudfext.wudfobject** to list, for example, the child objects of an **IWDFDevice** object, which generally include the device's queues. + +You can also use **!wudfext.wudfobject** to find WDF objects that are associated with a particular device, to check the state of a WDF object (for example, whether the WDF object is in the process of deletion), or to determine the WDF object's current reference count. + +The **!wudfext.wudfobject** extension also displays the callback functions and context objects that the driver associated with each framework object and attempts to determine the framework object's type. This last feature might not work with certain compilers. + +The following are some examples. In the first example, [**!wudfext.umdevstacks**](-wudfext-umdevstack.md) gives 0x03050E70 as the address of a device object, and this address is then passed to **!wudfext.wudfobject**. The 0x1 flag is included to display all the children of this object. + +``` +0: kd> !umdevstacks +Number of device stacks: 1 + Device Stack: 0x038f6f08 Pdo Name: \Device\USBPDO-11 + Number of UM devices: 1 + Device 0 + Driver Config Registry Path: WUDFOsrUsbFx2 + UMDriver Image Path: D:\Windows\system32\DRIVERS\UMDF\WUDFOsrUsbFx2.dll + Fx Driver: IWDFDriver 0x3044ff0 + Fx Device: IWDFDevice 0x3050e70 + IDriverEntry: WUDFOsrUsbFx2!CMyDriver 0x0303eff8 + Open UM files (use !umfile for details): + 0x049baf84 + Device XFerMode: CopyImmediately RW: Buffered CTL: Buffered + Object Tracker Address: 0x00000000 + Object Tracking OFF + Refcount Tracking OFF + DevStack XFerMode: CopyImmediately RW: Buffered CTL: Buffered + +0: kd> !wudfobject 0x3050e70 1 +IWDFDevice 0x3050e70 Fx: 0x3050e30 [Ref 2] + 15 Children + 00: IWDFIoTarget 0x3056f90 Fx: 0x3056f50 [Ref 3] + No Children + 01: + 02: + 03: + 04: IWDFIoQueue 0x305ae98 Fx: 0x305ae58 [Ref 8] + No Children + 05: IWDFIoQueue 0x305ee98 Fx: 0x305ee58 [Ref 2] + No Children + 06: IWDFIoQueue 0x3060e98 Fx: 0x3060e58 [Ref 2] + No Children + 07: IWDFIoTarget 0x3066f80 Fx: 0x3066f40 [Ref 2] + 1 Children + 00: IWDFUsbInterface 0x306efd8 Fx: 0x306ef98 [Ref 1] + 3 Children + 00: IWDFIoTarget 0x3074f70 Fx: 0x3074f30 [Ref 2] + 2 Children + 00: IWDFMemory 0x30a4ff0 Fx: 0x30a4fb0 [Ref 2] + No Children + 01: IWDFMemory 0x30aaff0 Fx: 0x30aafb0 [Ref 2] + No Children + 01: IWDFIoTarget 0x3078f70 Fx: 0x3078f30 [Ref 1] + No Children +``` + +Here is an example of **!wudfext.wudfobject** displaying a file object: + +``` +kd> !wudfobject 0xf5060 +IWDFFile 0xf5060 Fx: 0xf4fe8 [Ref 1] + State: Created Parent: 0xf2f80 + No Children +``` + +Here is an example of **!wudfext.wudfobject** displaying a driver object: + +``` +kd> !wudfobject 0xf2db8 0x01 +IWDFDriver 0xf2db8 Fx: 0xf2d40 [Ref 2] + Callback: (WUDFEchoDriver!CMyDriver, 0xf2c68) + State: Created Parent: 0 + 1 Children: + 00: IWDFDevice 0xf2f80 Fx: 0xf2f08 [Ref 2] + State: Created Parent: 0xf2db8 + 5 Children: + 00: IWDFIoTarget 0xf33c0 Fx: 0xf3348 [Ref 3] + State: Created Parent: 0xf2f80 + No Children + 01: IWDFIoQueue 0xf3500 Fx: 0xf3488 [Ref 3] + State: Created Parent: 0xf2f80 + No Children + 02: IWDFFile 0xf5060 Fx: 0xf4fe8 [Ref 1] + State: Created Parent: 0xf2f80 + No Children + 03: IWDFFile 0xf5100 Fx: 0xf5088 [Ref 101] + State: Created Parent: 0xf2f80 + No Children + 04: IWDFFile 0xf51a0 Fx: 0xf5128 [Ref 101] + State: Created Parent: 0xf2f80 + No Children +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfobject%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfqueue.md b/windows-driver-docs-pr/debugger/-wudfext-wudfqueue.md new file mode 100644 index 0000000000..5632db7056 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfqueue.md @@ -0,0 +1,90 @@ +--- +title: wudfext.wudfqueue +description: The wudfext.wudfqueue extension displays information about an I/O queue. +ms.assetid: b3ede1af-c85a-42d6-a8e5-e4094dd80d1c +keywords: ["wudfext.wudfqueue Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfqueue +api_type: +- NA +--- + +# !wudfext.wudfqueue + + +The **!wudfext.wudfqueue** extension displays information about an I/O queue. + +``` +!wudfext.wudfqueue pWDFQueue +``` + +## Parameters + + + *pWDFQueue* +Specifies the address of the **IWDFIoQueue** interface to display information about. The [**!wudfext.wudfdevicequeues**](-wudfext-wudfdevicequeues.md) extension command determines the address of **IWDFIoQueue**. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The following is an example of the **!wudfext.wudfqueue** display: + +``` +kd> !wudfqueue 0x000f3500 + WdfIoQueueDispatchSequential, POWER MANAGED, WdfIoQueuePowerOn, CAN ACCEPT, CAN DISPATCH + Number of driver owned requests: 1 + IWDFIoRequest 0x000fa7c0 CWdfIoRequest 0x000fa748 + Number of waiting requests: 199 + IWDFIoRequest 0x000fa908 CWdfIoRequest 0x000fa890 + IWDFIoRequest 0x000faa50 CWdfIoRequest 0x000fa9d8 + IWDFIoRequest 0x000fab98 CWdfIoRequest 0x000fab20 + ... + IWDFIoRequest 0x000fa530 CWdfIoRequest 0x000fa4b8 + IWDFIoRequest 0x000fa678 CWdfIoRequest 0x000fa600 + Driver's callback interfaces. + IQueueCallbackRead 0x000f343c + IQueueCallbackDeviceIoControl 0x000f3438 + IQueueCallbackWrite 0x000f3440 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfqueue%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfrefhist.md b/windows-driver-docs-pr/debugger/-wudfext-wudfrefhist.md new file mode 100644 index 0000000000..58ccb55732 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfrefhist.md @@ -0,0 +1,114 @@ +--- +title: wudfext.wudfrefhist +description: The wudfext.wudfrefhist extension displays the reference count stack history for a UMDF object. +ms.assetid: 8999f525-c6ed-4341-be2c-b0debef23a4b +keywords: ["wudfext.wudfrefhist Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfrefhist +api_type: +- NA +--- + +# !wudfext.wudfrefhist + + +The **!wudfext.wudfrefhist** extension displays the reference count stack history for a UMDF object. + +``` +!wudfext.wudfrefhist ObjectAddress +``` + +## Parameters + + + *ObjectAddress* +Specifies the address of the UMDF object whose reference count stack history is to be displayed. Note that this is the address of the object itself, not of the interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The **!wudfext.wudfrefhist** command is not supported by UMDF 1.11. + +The *ObjectAddress* parameter must be the address of the UMDF object, not the address of the interface (which is used by many other UMDF extension commands). To determine the address of the UMDF object, use the [**!wudfext.wudfdumpobjects**](-wudfext-wudfdumpobjects.md) command, which displays both the UMDF object address and the interface address. Alternatively, if you know the address of the interface, you can use it as the argument of the [**!wudfext.wudfobject**](-wudfext-wudfobject.md) command, which displays the object address (displayed after the symbol "Fx:"). + +If the reference count tracking option (**TrackRefCounts**) has been enabled in WDF Verifier, you can use **!wudfext.wudfrefhist** to display each call stack that increments or decrements an object's reference count. You can determine whether a call stack is causing a memory leak by examining its **AddRef** and **Release** calls for references that are being added and not released. + +This command can be used at any time, even if UMDF has not broken in to the debugger. + +If this command does not display the desired information, make sure that the relevant data is paged in and then try again. + +Here is an example of using the **!wudfext.wudfrefhist** command: + +``` +0:007> !wudfext.umdevstacks +... + UMDriver Image Path: C:\Windows\System32\drivers\UMDF\WUDFOsrUsbFilter.dll + Object Tracker Address: 0x0000003792ee9fc0 + Object Tracking ON + Refcount Tracking ON + +0:007> !wudfext.wudfdumpobjects 0x0000003792ee9fc0 +... +WdfTypeIoQueue Object: 0x0000003792f05ce0, Interface: 0x0000003792f05d58 + +## 0:007> !wudfext.wudfrefhist 0x0000003792f05ce0 +----------------------------------------------------------------------- +## 2 (++) +----------------------------------------------------------------------- +WUDFx!UfxObject::TrackRefCounts+0xb2 +WUDFx!CWdfIoQueue::AddRef+0x17adc +WUDFx!CWdfIoQueue::CreateAndInitialize+0xeb +WUDFx!CWdfDevice::CreateIoQueue+0x1e7 +WUDFOsrUsbFilter!CMyQueue::Initialize+0x48 +WUDFOsrUsbFilter!CMyDevice::Configure+0x7d +WUDFOsrUsbFilter!CMyDriver::OnDeviceAdd+0xca +WUDFx!CWdfDriver::OnAddDevice+0x486 +WUDFx!CWUDF::AddDevice+0x43 +WUDFHost!CWudfDeviceStack::LoadDrivers+0x320 +WUDFHost!CLpcNotification::Message+0x1340 +WUDFPlatform!WdfLpcPort::ProcessMessage+0x140 +WUDFPlatform!WdfLpcCommPort::ProcessMessage+0x92 +WUDFPlatform!WdfLpc::RetrieveMessage+0x20c +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfrefhist%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfrequest.md b/windows-driver-docs-pr/debugger/-wudfext-wudfrequest.md new file mode 100644 index 0000000000..00d655bc91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfrequest.md @@ -0,0 +1,108 @@ +--- +title: wudfext.wudfrequest +description: The wudfext.wudfrequest extension displays information about an I/O request. +ms.assetid: 4812c7bb-0fce-43e1-8f07-e4da9dd0c3bb +keywords: ["wudfext.wudfrequest Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfrequest +api_type: +- NA +--- + +# !wudfext.wudfrequest + + +The **!wudfext.wudfrequest** extension displays information about an I/O request. + +``` +!wudfext.wudfrequest pWDFRequest +``` + +## Parameters + + + *pWDFRequest* +Specifies the address of the **WDFIoRequest** interface to display information about. The [**!wudfext.wudfqueue**](-wudfext-wudfqueue.md) extension command determines the address of **WDFIoRequest**. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +Remarks +------- + +The following is an example of the **!wudfext.wudfrequest** display: + +``` +kd> !wudfrequest 0x000fa530 +CWdfIoRequest 0x000fa4b8 +Type: WdfRequestRead + IWDFIoQueue: 0x000f3500 +Completed: No +Canceled: No +UM IRP: 0x00429108 UniqueId: 0xf4 Kernel Irp: 0x0x936ef160 + Type: WudfMsg_READ + ClientProcessId: 0x1248 + Device Stack: 0x003be4e0 + IoStatus + hrStatus: 0x0 + Information: 0x0 + Driver/Framework created IRP: No + Data Buffer: 0x00000000 / 0 + IsFrom32BitProcess: Yes + CancelFlagSet: No + Cancel callback: 0x000fa534 + Total number of stack locations: 2 + CurrentStackLocation: 2 (StackLocation[ 1 ]) + StackLocation[ 0 ] + UNINITIALIZED + > StackLocation[ 1 ] + IWDFRequest: ???? + IWDFDevice: 0x000f2f80 + IWDFFile: 0x00418cf0 + Completion: + Callback: 0x00000000 + Context: 0x00000000 + Parameters: (RequestType: WdfRequestRead) + Buffer length: 0x400 + Key: 0x00000000 + Offset: 0x0 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfrequest%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfusbinterface.md b/windows-driver-docs-pr/debugger/-wudfext-wudfusbinterface.md new file mode 100644 index 0000000000..ad97e534d6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfusbinterface.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudfusbinterface +description: The wudfext.wudfusbinterface extension displays information about a USB interface object. +ms.assetid: 4c93919a-781d-4bd8-9be2-eecdb75781b1 +keywords: ["wudfext.wudfusbinterface Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfusbinterface +api_type: +- NA +--- + +# !wudfext.wudfusbinterface + + +The **!wudfext.wudfusbinterface** extension displays information about a USB interface object. + +``` +!wudfext.wudfusbinterface pWDFUSBInterface TypeName +``` + +## Parameters + + + *pWDFUSBInterface* +Specifies the address of the **IWDFUsbInterface** interface to display information about. The [**!wudfext.wudfobject**](-wudfext-wudfobject.md) extension command determines the address of **IWDFUsbInterface**. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfusbinterface%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfusbpipe.md b/windows-driver-docs-pr/debugger/-wudfext-wudfusbpipe.md new file mode 100644 index 0000000000..56a25eccdf --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfusbpipe.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudfusbpipe +description: The wudfext.wudfusbpipe extension displays information about a USB pipe object. +ms.assetid: a80f01e1-9c2c-4674-a067-0ff7e006713a +keywords: ["wudfext.wudfusbpipe Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfusbpipe +api_type: +- NA +--- + +# !wudfext.wudfusbpipe + + +The **!wudfext.wudfusbpipe** extension displays information about a USB pipe object. + +``` +!wudfext.wudfusbpipe pWDFUSBPipe TypeName +``` + +## Parameters + + + *pWDFUSBPipe* +Specifies the address of the **IWDFUsbTargetPipe** interface to display information about. The [**!wudfext.wudfobject**](-wudfext-wudfobject.md) extension command determines the address of **IWDFUsbTargetPipe**. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfusbpipe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-wudfext-wudfusbtarget.md b/windows-driver-docs-pr/debugger/-wudfext-wudfusbtarget.md new file mode 100644 index 0000000000..c72038de76 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-wudfext-wudfusbtarget.md @@ -0,0 +1,70 @@ +--- +title: wudfext.wudfusbtarget +description: The wudfext.wudfusbtarget extension displays information about a USB I/O target. +ms.assetid: 2e01830f-56dc-435a-81e9-14e2b4d093d2 +keywords: ["wudfext.wudfusbtarget Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wudfext.wudfusbtarget +api_type: +- NA +--- + +# !wudfext.wudfusbtarget + + +The **!wudfext.wudfusbtarget** extension displays information about a USB I/O target. + +``` +!wudfext.wudfusbtarget pWDFUSBTarget TypeName +``` + +## Parameters + + + *pWDFUSBTarget* +Specifies the address of the **IWDFUsbTargetDevice** interface to display information about. The [**!wudfext.wudfobject**](-wudfext-wudfobject.md) extension command determines the address of **IWDFUsbTargetDevice**. + + *TypeName* +Optional. Specifies the type of the interface (for example, **IWDFDevice**). If a value for *TypeName* is supplied, the extension uses the value as the type of the interface. If an asterisk (\*) is supplied as *TypeName*, or if *TypeName* is omitted, the extension attempts to automatically determine the type of the supplied interface. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Unavailable

Windows XP with UMDF version 1.7 and later

Wudfext.dll

+ +  + +### Additional Information + +For more information, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!wudfext.wudfusbtarget%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/-xhci-findowner.md b/windows-driver-docs-pr/debugger/-xhci-findowner.md new file mode 100644 index 0000000000..09f7137f41 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-xhci-findowner.md @@ -0,0 +1,140 @@ +--- +title: xhci_findowner +description: The usb3kd.xhci_findowner command finds the owner a common buffer. +ms.assetid: 6AA3E41C-5838-4425-B1CE-37A13E8F755E +keywords: ["xhci_findowner Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- xhci_findowner +api_type: +- NA +--- + +# !xhci\_findowner + + +The **!usb3kd.xhci\_findowner** command finds the owner a common buffer. + +``` +!usb3kd.xhci_findowner Address +``` + +## Parameters + + + *Address* +Virtual or physical address of a common buffer. + +## DLL + + +Usb3kd.dll + +Remarks +------- + +A common buffer is a block of physically contiguous memory that’s addressable by hardware. The USB 3.0 driver stack uses common buffers to communicate with USB 3.0 host controllers. Suppose the system crashes, and you come across an address that you suspect might be common buffer memory. If the address is common buffer memory, this command tells you which USB 3.0 host controller the memory belongs to (in case you that you have more than one USB 3.0 controller) and what the memory is used for. + +Examples +-------- + +The following example calls [**!xhci\_resourceusage**](-usb3kd-xhci-resourceusage.md) to list the addresses of some common buffers. + +``` +0: kd> !usb3kd.xhci_resourceusage 0x867fbff0 + +## Dumping CommonBuffer Resources +------------------------------ + dt USBXHCI!_COMMON_BUFFER_DATA 0x868d61c0 + DmaEnabler:!wdfdmaenabler 0x79729fe8 + + CommonBuffers Large: Total 8 Available 2 Used 6 TotalBytes 32768 + [ 1] dt _TRACKING_DATA 0x868d73a4 VA 0x868e0000 LA 0xdb2e0000 -- Owner 0x86801690 Tag: Int2 Size 4096 + [ 2] dt _TRACKING_DATA 0x868d6d1c VA 0x868e1000 LA 0xdb2e1000 -- Owner 0x86801690 Tag: Int2 Size 4096 + [ 3] dt _TRACKING_DATA 0x868d6c54 VA 0x868e2000 LA 0xdb2e2000 -- Owner 0x86801690 Tag: Int2 Size 4096 + [ 4] dt _TRACKING_DATA 0x868d6b8c VA 0x868e3000 LA 0xdb2e3000 -- Owner 0x86801690 Tag: Int2 Size 4096 + [ 5] dt _TRACKING_DATA 0x868d67b4 VA 0x868e5000 LA 0xdb2e5000 -- Owner 0x86801548 Tag: Slt1 Size 4096 + [ 6] dt _TRACKING_DATA 0x868d50b4 VA 0x868e6000 LA 0xdb2e6000 -- Owner 0x86801548 Tag: Slt3 Size 4096 + + CommonBuffers Small: Total 16 Available 13 Used 3 TotalBytes 8192 + [ 1] dt _TRACKING_DATA 0x868d6974 VA 0x868e4000 LA 0xdb2e4000 -- Owner 0x86801690 Tag: Int1 Size 512 + [ 2] dt _TRACKING_DATA 0x868d69a4 VA 0x868e4200 LA 0xdb2e4200 -- Owner 0x86801548 Tag: Slt2 Size 512 + [ 3] dt _TRACKING_DATA 0x868d69d4 VA 0x868e4400 LA 0xdb2e4400 -- Owner 0x86801488 Tag: Cmd1 Size 512 +``` + +One of the virtual addresses listed in the preceding output is 0x868e2000. The following example passes that address to **!xhci\_findowner**. One of the physical addresses listed in the preceding output is 0xdb2e4400. The following example passes 0xdb2e4440 (offset 0x40 bytes from 0xdb2e4400) to **!xhci\_findowner**. + +``` +0: kd> !xhci_findowner 0x868e2000 + +!xhci_info 0x867fbff0 Texas Instruments - PCI: VendorId 0x104c DeviceId 0x8241 RevisionId 0x02 + + dt _TRACKING_DATA 0x868d6c54 VA 0x868e2000 LA 0xdb2e2000 -- Owner 0x86801690 Tag: Int2 Size 4096 + + dt _INTERRUPTER_DATA 0x86801690 + !xhci_eventring 0x867fbff0 <-- This memory is used for event ring. + + +0: kd> !xhci_findowner 0xdb2e4440 <-- Note the offset difference. + +!xhci_info 0x867fbff0 Texas Instruments - PCI: VendorId 0x104c DeviceId 0x8241 RevisionId 0x02 + + dt _TRACKING_DATA 0x868d69d4 VA 0x868e4400 LA 0xdb2e4400 -- Owner 0x86801488 Tag: Cmd1 Size 512 + + dt _COMMAND_DATA 0x86801488 + !xhci_commandring 0x867fbff0 <-- This memory is used for command ring. +``` + +The **!xhci\_findowner** command is especially useful when you have an address in a transfer request block (TRB), and you want to track it back to the device slot that it belongs to. In the following example, one of the addresses listed in the output of [**!xhci\_transferring**](-usb3kd-xhci-transferring.md) is 0xda452230, which is the physical address of a TRB. The example passes that address to **!xhci\_findowner**. The output shows that the TRB belongs to device slot 8 (**!xhci\_deviceslots 0x8551d370 8**). + +``` +0: kd> !usb3kd.xhci_transferring 0x87652200 + + [ 0] NORMAL 0xda452200 CycleBit 1 IOC 0 BEI 0 InterrupterTarget 2 TransferLength 6 TDSize 0 + [ 1] EVENT_DATA 0xda452210 CycleBit 1 IOC 1 BEI 0 InterrupterTarget 2 Data 0x8511375c TotalBytes 6 + [ 2] NORMAL 0xda452220 CycleBit 1 IOC 0 BEI 0 InterrupterTarget 2 TransferLength 6 TDSize 0 + [ 3] EVENT_DATA 0xda452230 CycleBit 1 IOC 1 BEI 0 InterrupterTarget 2 Data 0x857d076c TotalBytes 6 + +0: kd> !xhci_findowner 0xda452230 + +!xhci_info 0x8551d370 Renesas - PCI: VendorId 0x1912 DeviceId 0x0015 RevisionId 0x02 Firmware 0x0020.0006 + + dt _TRACKING_DATA 0x8585fd5c VA 0x87652200 LA 0xda452200 -- Owner 0x85894548 Tag: Rng1 Size 512 + + !xhci_deviceslots 0x8551d370 8 + + [0] dt _TRANSFERRING_DATA 0x85894548 Events: 0x0 TransferRingState_Idle + ------------------------------------------------------------------------------ + WdfQueue: !wdfqueue 0x7a76bcb0 (0 waiting) + CurrentRingBufferData: VA 0x87652200 LA 0xda452200 !wdfcommonbuffer 0x7a7a0370 Size 512 + Current: !xhci_transferring 0x87652200 + PendingTransferList: + [0] dt _TRANSFER_DATA 0x851136f0 !urb 0x84e55468 !wdfrequest 0x7aeec9e8 TransferState_Pending + [1] dt _TRANSFER_DATA 0x857d0700 !urb 0x85733be8 !wdfrequest 0x7a82f9d8 TransferState_Pending +``` + +## See also + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[**!xhci\_dumpall**](-usb3kd-xhci-dumpall.md) + +[Universal Serial Bus (USB) Drivers](http://go.microsoft.com/fwlink/p?LinkID=227351) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!xhci_findowner%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/-zombies.md b/windows-driver-docs-pr/debugger/-zombies.md new file mode 100644 index 0000000000..6be3e52fe7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/-zombies.md @@ -0,0 +1,85 @@ +--- +title: zombies +description: The zombies extension displays all dead ("zombie") processes or threads. +ms.assetid: f7fbce79-456a-4643-ad31-8cb2e6449ecf +keywords: ["zombies Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- zombies +api_type: +- NA +--- + +# !zombies + + +The **!zombies** extension displays all dead ("zombie") processes or threads. + +``` +!zombies [Flags [RestartAddress]] +``` + +## Parameters + + + *Flags* +Specifies what will be displayed. Possible values include: + +1 +Displays all zombie processes. (This is the default.) + +2 +Displays all zombie threads. + + *RestartAddress* +Specifies the hexadecimal address at which to begin the search. This is useful if the previous search was terminated prematurely. The default is zero. + +### DLL + + ++++ + + + + + + + + + + +

Windows 2000

Kdextx86.dll

Windows XP and later

Unavailable

+ +  + +### Additional Information + +To see a list of all processes and threads, use the [**!process**](-process.md) extension. + +For general information about processes and threads in kernel mode, see [Changing Contexts](changing-contexts.md). For more information about analyzing processes and threads, see *Microsoft Windows Internals*, by Mark Russinovich and David Solomon. (This book may not be available in some languages and countries.) + +Remarks +------- + +Zombie processes are dead processes that have not yet been removed from the process list. Zombie threads are analogous. + +This extension is available only for Windows 2000. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20!zombies%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/32-bit-pointers-and-64-bit-pointers.md b/windows-driver-docs-pr/debugger/32-bit-pointers-and-64-bit-pointers.md new file mode 100644 index 0000000000..8dee54e6e8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/32-bit-pointers-and-64-bit-pointers.md @@ -0,0 +1,42 @@ +--- +title: 32-Bit Pointers and 64-Bit Pointers +description: 32-Bit Pointers and 64-Bit Pointers +ms.assetid: 641443b9-465f-4c7e-a13d-47a991304b46 +keywords: ["WdbgExts extensions, 32-bit pointers", "WdbgExts extensions, 64-bit pointers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# 32-Bit Pointers and 64-Bit Pointers + + +## + + +The WdbgExts.h header file supports both 32-bit and 64-bit pointers. To use 64-bit pointers, simply include the following two lines in your code, in the following order: + +``` +#define KDEXT_64BIT +#include wdbgexts.h +``` + +It is recommended that you always use 64-bit pointers in your code. This allows your extension to work on any platform, because the debugger will automatically cast 64-bit pointers to 32 bits when the target is 32-bit. + +If you intend to use your extension only on 32-bit platforms, you can write a 32-bit extension instead. In that case, you only need to include the following line in your code: + +``` +#include wdbgexts.h +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%2032-Bit%20Pointers%20and%2064-Bit%20Pointers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/TOC.md b/windows-driver-docs-pr/debugger/TOC.md new file mode 100644 index 0000000000..197c0020e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/TOC.md @@ -0,0 +1,2126 @@ +# [Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](index.md) +# [Getting Started with Windows Debugging](getting-started-with-windows-debugging.md) +## [Getting Started with WinDbg (User-Mode)](getting-started-with-windbg.md) +## [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md) +## [Choosing the 32-Bit or 64-Bit Debugging Tools](choosing-a-32-bit-or-64-bit-debugger-package.md) +## [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md) +## [Setting Up Debugging (Kernel-Mode and User-Mode)](getting-set-up-for-debugging.md) +### [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) +#### [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) +#### [Setting Up Kernel-Mode Debugging over a 1394 Cable Manually](setting-up-a-1394-cable-connection.md) +#### [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually](setting-up-a-usb-3-0-debug-cable-connection.md) +#### [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually](setting-up-a-usb-2-0-debug-cable-connection.md) +#### [Setting Up Kernel-Mode Debugging over a Serial Cable Manually](setting-up-a-null-modem-cable-connection.md) +#### [Setting Up Kernel-Mode Debugging using Serial over USB Manually](setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md) +#### [Setting Up Kernel-Mode Debugging of a Virtual Machine Manually](attaching-to-a-virtual-machine--kernel-mode-.md) +#### [Setting Up Local Kernel Debugging of a Single Computer Manually](setting-up-local-kernel-debugging-of-a-single-computer-manually.md) +### [Supported Ethernet NICs for Network Kernel Debugging in Windows 10](supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md) +### [Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) +### [Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) +### [Setting Up User-Mode Debugging in Visual Studio](setting-up-user-mode-debugging-in-visual-studio.md) +### [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md) +### [Configuring tools.ini](configuring-tools-ini.md) +### [Using KDbgCtrl](using-kdbgctrl.md) +## [Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md) +## [Debug Drivers - Step by Step Lab (Sysvad Kernel-Mode)](debug-universal-drivers--kernel-mode-.md) +# [Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +## [WinDbg Preview - What's New](windbg-what-is-new-preview.md) +## [WinDbg Preview - Installation](windbg-install-preview.md) +## [WinDbg Preview - Command line startup options](windbg-command-line-preview.md) +## [WinDbg Preview – Settings and workspaces](windbg-setup-preview.md) +## [WinDbg Preview – Keyboard shortcuts](windbg-keyboard-shortcuts-preview.md) +## [WinDbg Preview - Start a user-mode session](windbg-user-mode-preview.md) +## [WinDbg Preview - Start a kernel mode session](windbg-kernel-mode-preview.md) +## [WinDbg Preview – File menu](windbg-file-preview.md) +## [WinDbg Preview – Home menu](windbg-home-preview.md) +## [WinDbg Preview – View menu](windbg-view-preview.md) +## [WinDbg Preview – Breakpoints](windbg-breakpoints-preview.md) +## [WinDbg Preview – Data Model](windbg-data-model-preview.md) +## [WinDbg Preview – Scripting](windbg-scripting-preview.md) +# [Debugging Resources](debugging-resources.md) +## [Debugging Tools for Windows: New for Windows 10](debugging-tools-for-windows--new-for-windows-10.md) +## [Tools Included in Debugging Tools for Windows](extra-tools.md) +### [ADPlus](adplus.md) +### [DumpChk](dumpchk.md) +### [GFlags](gflags.md) +#### [GFlags Overview](gflags-overview.md) +#### [GFlags Details](gflags-details.md) +#### [GFlags Commands](gflags-commands.md) +#### [GFlags Flag Table](gflags-flag-table.md) +#### [GFlags and PageHeap](gflags-and-pageheap.md) +#### [Monitoring Silent Process Exit](registry-entries-for-silent-process-exit.md) +#### [Global Flags Dialog Box](global-flags-dialog-box.md) +##### [Opening the Dialog Box](opening-the-dialog-box.md) +##### [Setting and Clearing System-wide Flags](setting-and-clearing-system-wide-flags.md) +##### [Setting and Clearing Kernel Flags](setting-and-clearing-kernel-flags.md) +##### [Setting and Clearing Image File Flags](setting-and-clearing-image-file-flags.md) +##### [Configuring Silent Process Exit Monitoring](setting-and-clearing-flags-for-silent-process-exit.md) +##### [Launching a Program with Flags](launching-a-program-with-flags.md) +##### [Running a Program in a Debugger](running-a-program-in-a-debugger.md) +##### [Configuring Special Pool](configuring-special-pool.md) +###### [Requesting Special Pool by Pool Tag](requesting-special-pool-by-pool-tag.md) +###### [Requesting Special Pool by Allocation Size](requesting-special-pool-by-allocation-size.md) +###### [Canceling Requests for Special Pool](canceling-requests-for-special-pool.md) +###### [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md) +##### [Configuring Object Reference Tracing](configuring-object-reference-tracing.md) +#### [Global Flag Reference](global-flag-reference.md) +##### [Buffer DbgPrint Output](buffer-dbgprint-output.md) +##### [Create kernel mode stack trace database](create-kernel-mode-stack-trace-database.md) +##### [Create user mode stack trace database](create-user-mode-stack-trace-database.md) +##### [Debug initial command](debug-initial-command.md) +##### [Debug WinLogon](debug-winlogon.md) +##### [Disable heap coalesce on free](disable-heap-coalesce-on-free.md) +##### [Disable paging of kernel stacks](disable-paging-of-kernel-stacks.md) +##### [Disable protected DLL verification](disable-protected-dll-verification.md) +##### [Disable stack extension](disable-stack-extension.md) +##### [Early critical section event creation](early-critical-section-event-creation.md) +##### [Enable application verifier](enable-application-verifier.md) +##### [Enable bad handles detection](enable-bad-handles-detection.md) +##### [Enable close exception](enable-close-exception.md) +##### [Enable debugging of Win32 subsystem](enable-debugging-of-win32-subsystem.md) +##### [Enable exception logging](enable-exception-logging.md) +##### [Enable heap free checking](enable-heap-free-checking.md) +##### [Enable heap parameter checking](enable-heap-parameter-checking.md) +##### [Enable heap tagging](enable-heap-tagging.md) +##### [Enable heap tagging by DLL](enable-heap-tagging-by-dll.md) +##### [Enable heap tail checking](enable-heap-tail-checking.md) +##### [Enable heap validation on call](enable-heap-validation-on-call.md) +##### [Enable loading of kernel debugger symbols](enable-loading-of-kernel-debugger-symbols.md) +##### [Enable object handle type tagging](enable-object-handle-type-tagging.md) +##### [Enable page heap](enable-page-heap.md) +##### [Enable pool tagging](enable-pool-tagging.md) +##### [Enable silent process exit monitoring](enable-silent-process-exit-monitoring.md) +##### [Enable system critical breaks](enable-system-critical-breaks.md) +##### [Load image using large pages if possible](load-image-using-large-pages-if-possible.md) +##### [Maintain a list of objects for each type](maintain-a-list-of-objects-for-each-type.md) +##### [Object Reference Tracing](object-reference-tracing.md) +##### [Show loader snaps](show-loader-snaps.md) +##### [Special Pool](special-pool.md) +##### [Stop on exception](stop-on-exception.md) +##### [Stop on hung GUI](stop-on-hung-gui.md) +##### [Stop on unhandled user-mode exception](stop-on-unhandled-user-mode-exception.md) +#### [GFlags Examples](gflags-examples.md) +##### [Example 1: Displaying Global Flags](example-1---displaying-global-flags.md) +##### [Example 2: Setting a Flag by Using a Flag Abbreviation](example-2---setting-a-flag-by-using-a-flag-abbreviation.md) +##### [Example 3: Setting a Flag by Using Its Hexadecimal Value](example-3---setting-a-flag-by-using-its-hexadecimal-value.md) +##### [Example 4: Setting Multiple Flags](example-4---setting-multiple-flags.md) +##### [Example 5: Clearing a Flag](example-5---clearing-a-flag.md) +##### [Example 6: Clearing All Flags](example-6---clearing-all-flags.md) +##### [Example 7: Clearing All Flags for an Image File](example-7---clearing-all-flags-for-an-image-file.md) +##### [Example 8: Enlarging the User-Mode Stack Trace Database](example-8---enlarging-the-user-mode-stack-trace-database.md) +##### [Example 9: Detecting a Pool Memory Leak](example-9---detecting-a-pool-memory-leak.md) +##### [Example 10: Detecting a Heap Memory Leak in a Process](example-10---detecting-a-heap-memory-leak-in-a-process.md) +##### [Example 11: Enabling Page Heap Verification](example-11---enabling-page-heap-verification.md) +##### [Example 12: Using Page Heap Verification to Find a Bug](example-12---using-page-heap-verification-to-find-a-bug.md) +##### [Example 13: Listing Image Files with Global Flags](example-13---listing-image-files-with-global-flags.md) +##### [Example 14: Configuring Special Pool](example-14---configuring-special-pool.md) +##### [Example 15: Using Object Reference Tracing](example-15--using-object-reference-tracing.md) +### [Kill Tool](kill-tool.md) +### [Logger and LogViewer](logger-and-logviewer.md) +#### [Logger](logger.md) +##### [Using the Debugger and Logexts.dll](using-the-debugger-and-logexts-dll.md) +##### [Using Logger.exe](using-logger-exe.md) +##### [Logger Restrictions and Limitations](logger-restrictions-and-limitations.md) +#### [LogViewer](logviewer.md) +##### [Reading the LogViewer Display](reading-the-logviewer-display.md) +##### [Filtering the LogViewer Function List](filtering-the-logviewer-function-list.md) +##### [Exporting LogViewer Files to Text](exporting-logviewer-files-to-text.md) +#### [The Logger Manifest](the-logger-manifest.md) +##### [Overview of the Logging Manifest](overview-of-the-logging-manifest.md) +##### [Manifest File Placement](manifest-file-placement.md) +##### [Manifest File Format](manifest-file-format.md) +### [PLMDebug](plmdebug.md) +### [Remote Tool](remote-tool.md) +#### [Remote Tool Concepts](remote-tool-concepts.md) +#### [Remote Tool Commands](remote-tool-commands.md) +##### [Remote Server Syntax](remote-server-syntax.md) +##### [Remote Client Syntax](remote-client-syntax.md) +##### [Remote Server Query Command](remote-server-query-command.md) +##### [Remote Session Commands](remote-session-commands.md) +#### [Remote Tool Examples](remote-tool-examples.md) +### [TList](tlist.md) +#### [TList Commands](tlist-commands.md) +#### [TList Examples](tlist-examples.md) +### [UMDH](umdh.md) +#### [Preparing to Use UMDH](preparing-to-use-umdh.md) +#### [UMDH Commands](umdh-commands.md) +##### [Analyze a Running Process](analyze-a-running-process.md) +##### [Analyze UMDH Logs](analyze-umdh-logs.md) +#### [Interpreting a UMDH Log](interpreting-a-umdh-log.md) +#### [Interpreting a Log Comparison](interpreting-a-log-comparison.md) +### [USBView](usbview.md) +## [Tools Related to Debugging Tools for Windows](tools-related-to-debugging-tools-for-windows.md) +### [Application Verifier](application-verifier.md) +### [Windows Error Reporting](windows-error-reporting.md) +## [Source Code](source-code.md) +### [Source Path](source-path.md) +### [Using a Source Server](using-a-source-server.md) +### [SrcSrv](srcsrv.md) +#### [Using SrcSrv](using-srcsrv.md) +#### [Source Indexing](source-indexing.md) +##### [The Srcsrv.ini File](the-srcsrv-ini-file.md) +##### [The Ssindex.cmd Script](the-ssindex-cmd-script.md) +##### [The SrcTool Utility](the-srctool-utility.md) +##### [The PDBStr Tool](the-pdbstr-tool.md) +##### [The VSSDump Tool](the-vssdump-tool.md) +#### [Source Control Systems](source-control-systems.md) +##### [Using Visual SourceSafe](using-visual-sourcesafe.md) +##### [Debugging with Visual SourceSafe](debugging-with-visual-sourcesafe.md) +##### [Using CVS](using-cvs.md) +##### [Using Other Source Control Systems](using-other-source-control-systems.md) +###### [Creating Your Own Provider Module](creating-your-own-provider-module.md) +###### [Creating Your Own Source Control System](creating-your-own-source-control-system.md) +###### [Language Specification 1](language-specification-1.md) +###### [Language Specification 2](language-specification-2.md) +#### [HTTP Sites and UNC Shares](http-sites-and-unc-shares.md) +##### [Setting Up the Web Site](setting-up-the-web-site.md) +##### [Extracting Source Files](extracting-source-files.md) +##### [Modifying the Source Indexing Streams in a .pdb File](modifying-the-source-indexing-streams-in-a--pdb-file.md) +##### [Using UNC Shares](using-unc-shares.md) +##### [Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control](using-http-sites-and-unc-shares-in-conjuction-with-regular-version-con.md) +## [Security Considerations](security-considerations.md) +### [Debug Privilege](debug-privilege.md) +### [Security Vulnerabilities](security-vulnerabilities.md) +#### [Security During Kernel-Mode Debugging](security-during-kernel-mode-debugging.md) +#### [Security During User-Mode Debugging](security-during-user-mode-debugging.md) +#### [Security During Postmortem Debugging](security-during-postmortem-debugging.md) +#### [Security During Remote Debugging](security-during-remote-debugging.md) +### [Secure Mode](secure-mode.md) +#### [Features of Secure Mode](features-of-secure-mode.md) +#### [Activating Secure Mode](activating-secure-mode.md) +## [Processor Architecture](processor-architecture.md) +### [The x86 Processor](the-x86-processor.md) +#### [x86 Architecture](x86-architecture.md) +#### [x86 Instructions](x86-instructions.md) +#### [Annotated x86 Disassembly](annotated-x86-disassembly.md) +### [The x64 Processor](the-x64-processor.md) +#### [x64 Architecture](x64-architecture.md) +#### [x64 Instructions](x64-instructions.md) +#### [Annotated x64 Disassembly](annotated-x64-disassembly.md) +## [Debugger Engine and Extension APIs](debugger-engine-and-extension-apis.md) +### [Debugger Engine Introduction](introduction.md) +### [Debugger Engine Overview](debugger-engine-overview.md) +#### [Debugging Session and Execution Model](debugging-session-and-execution-model.md) +#### [Client Objects](client-objects.md) +#### [Input and Output](input-and-output.md) +#### [Remote Debugging](remote-debugging5.md) +#### [Targets](targets.md) +#### [Events](events.md) +#### [Breakpoints](breakpoints3.md) +#### [Symbols](symbols4.md) +#### [Memory](memory.md) +#### [Threads and Processes](threads-and-processes.md) +### [Using the Debugger Engine API](using-the-debugger-engine-api.md) +#### [Debugger Engine API Overview](debugger-engine-api-overview.md) +##### [Interacting with the Engine](interacting-with-the-engine.md) +###### [Using Client Objects](using-client-objects.md) +###### [Using Callback Objects](using-callback-objects.md) +##### [Using Input and Output](using-input-and-output.md) +##### [Monitoring Events](monitoring-events.md) +###### [Event Filters](event-filters.md) +###### [Event Information](event-information.md) +##### [Using Breakpoints](using-breakpoints2.md) +###### [Setting Breakpoints](setting-breakpoints.md) +###### [Controlling Breakpoint Flags and Parameters](controlling-breakpoint-flags-and-parameters.md) +##### [Memory Access](memory-access.md) +###### [Virtual and Physical Memory](virtual-and-physical-memory.md) +###### [Registers](registers.md) +###### [Other Data Spaces](other-data-spaces.md) +##### [Examining the Stack Trace](examining-the-stack-trace.md) +##### [Controlling Threads and Processes](controlling-threads-and-processes.md) +##### [Using Symbols](using-symbols.md) +###### [Modules](modules.md) +###### [Types](types.md) +###### [Scopes and Symbol Groups](scopes-and-symbol-groups.md) +##### [Using Source Files](using-source-files.md) +##### [Connecting to Targets](connecting-to-targets.md) +###### [Live User-Mode Targets](live-user-mode-targets.md) +###### [Live Kernel-Mode Targets](live-kernel-mode-targets.md) +###### [Dump-File Targets](dump-file-targets.md) +###### [Remote Targets](remote-targets.md) +##### [Target Information](target-information.md) +##### [Target State](target-state.md) +##### [Calling Extensions and Extension Functions](calling-extensions-and-extension-functions.md) +##### [Assembling and Disassembling Instructions](assembling-and-disassembling-instructions.md) +### [Writing DbgEng Extensions](writing-dbgeng-extensions.md) +#### [DbgEng Extension Design Guide](dbgeng-extension-design-guide.md) +##### [Anatomy of a DbgEng Extension DLL](anatomy-of-a-dbgeng-extension-dll.md) +##### [Using Clients and the Engine](using-clients-and-the-engine.md) +##### [Writing DbgEng Extension Code](writing-dbgeng-extension-code.md) +##### [Building DbgEng Extensions](building-dbgeng-extensions.md) +### [EngExtCpp Extensions](engextcpp-extensions.md) +#### [EngExtCpp Extension Design Guide](engextcpp-extension-design-guide.md) +##### [EngExtCpp Extension Libraries](engextcpp-extension-libraries.md) +##### [Client Objects and the Engine](client-objects-and-the-engine.md) +##### [Writing EngExtCpp Extensions](writing-engextcpp-extensions.md) +##### [Building EngExtCpp Extensions](building-extengcpp-extensions.md) +##### [Parsing Extension Arguments](parsing-extension-arguments.md) +##### [Typed Data](typed-data.md) +### [Writing WdbgExts Extensions](writing-wdbgexts-extensions.md) +#### [WdbgExts Extension Design Guide](wdbgexts-extension-design-guide.md) +##### [WdbgExts Extension API Overview](wdbgexts-extension-api-overview.md) +##### [32-Bit Pointers and 64-Bit Pointers](32-bit-pointers-and-64-bit-pointers.md) +##### [Using WdbgExts Extension Callbacks](using-wdbgexts-extension-callbacks.md) +##### [Using the DECLARE_API Macro](using-the-declare-api-macro.md) +##### [Writing WdbgExts Extension Code](writing-wdbgexts-extension-code.md) +###### [WdbgExts Input and Output](wdbgexts-input-and-output.md) +###### [WdbgExts Memory Access](wdbgexts-memory-access.md) +###### [WdbgExts Threads and Processes](wdbgexts-threads-and-processes.md) +###### [WdbgExts Symbols](wdbgexts-symbols.md) +###### [WdbgExts Target Information](wdbgexts-target-information.md) +##### [Building WdbgExts Extensions](building-wdbgexts-extensions.md) +### [Writing Custom Analysis Debugger Extensions](writing-custom-analysis-debugger-extensions.md) +#### [Writing an Analysis Extension Plug-in to Extend !analyze](writing-an-analysis-extension-to-extend--analyze.md) +#### [Metadata Files for Analysis Extension Plug-ins](metadata-files-for-analysis-extensions.md) +#### [Failure Analysis Entries](failure-analysis-entries.md) +## [Customizing Debugger Output Using DML](customizing-debugger-output-using-dml.md) +## [JavaScript Debugger Scripting](javascript-debugger-scripting.md) +### [JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md) +### [Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md) +## [Native Debugger Objects in NatVis](native-debugger-objects-in-natvis.md) +## [Using LINQ With the debugger objects](using-linq-with-the-debugger-objects.md) +## [Glossary](glossary.md) +### [A](a.md) +### [B](b.md) +### [C](c.md) +### [D](d.md) +### [E](e.md) +### [F](f.md) +### [H](h.md) +### [I](i.md) +### [K](k.md) +### [L](l.md) +### [M](m.md) +### [N](n.md) +### [O](o.md) +### [P](p.md) +### [R](r.md) +### [S](s.md) +### [T](t.md) +### [U](u.md) +### [V](v.md) +### [W](w.md) +# [Debugger Operation](debugger-operation-win8.md) +## [Debugging Using WinDbg](debugging-using-windbg.md) +### [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md) +### [Debugging a UWP app using WinDbg](debugging-a-uwp-app-using-windbg.md) +### [Opening a Dump File Using WinDbg](opening-a-crash-dump-file-using-windbg.md) +### [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md) +### [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) +### [Setting Symbol and Executable Image Paths in WinDbg](setting-symbol-and-source-paths-in-windbg.md) +### [Remote Debugging Using WinDbg](remode-debugging-using-windbg.md) +### [Entering Debugger Commands in WinDbg](debugger-command-window.md) +### [Using the Command Browser Window in WinDbg](command-browser-window.md) +### [Setting Breakpoints in WinDbg](setting-breakpoints-in-windbg.md) +### [Viewing the Call Stack in WinDbg](calls-window.md) +### [Assembly Code Debugging in WinDbg](disassembly-window.md) +### [Source Code Debugging in WinDbg](source-window.md) +### [Viewing and Editing Memory in WinDbg](memory-window.md) +### [Viewing and Editing Global Variables in WinDbg](viewing-and-editing-global-variables-in-windbg.md) +### [Viewing and Editing Local Variables in WinDbg](locals-window.md) +### [Viewing and Editing Registers in WinDbg](registers-window.md) +### [Controlling Processes and Threads in WinDbg](processes-and-threads-window.md) +### [Configuring Exceptions and Events in WinDbg](configuring-exceptions-and-events-in-windbg.md) +### [Keeping a Log File in WinDbg](keeping-a-log-file-in-windbg.md) +### [Using the Watch Window](watch-window.md) +### [Using the Scratch Pad](scratch-pad.md) +## [Debugging Using KD and NTKD](debugging-using-kd-and-ntkd.md) +### [Opening a Dump File Using KD](opening-a-crash-dump-file-using-kd.md) +### [Live Kernel-Mode Debugging Using KD](performing-kernel-mode-debugging-using-kd.md) +### [Ending a Debugging Session in KD](ending-a-debugging-session-in-kd.md) +### [Setting Symbol and Executable Image Paths in KD](setting-symbol-and-source-paths-in-kd.md) +### [Setting Breakpoints in KD](setting-breakpoints-in-kd.md) +### [Viewing the Call Stack in KD](viewing-the-call-stack-in-kd.md) +### [Viewing and Editing Memory in KD](viewing-memory--variables--and-registers-in-kd.md) +### [Viewing and Editing Registers in KD](viewing-and-editing-registers-in-kd.md) +### [Remote Debugging Using KD](remote-debugging-using-kd.md) +### [Configuring Exceptions and Events in KD](configuring-exceptions-and-events-in-kd.md) +### [Keeping a Log File in KD](keeping-a-log-file-in-kd.md) +## [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md) +### [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md) +### [Opening a Dump File Using CDB](opening-a-crash-dump-file-using-cdb.md) +### [Ending a Debugging Session in CDB](ending-a-debugging-session-in-cdb.md) +### [Setting Symbol and Executable Image Paths in CDB](setting-symbol-and-source-paths-in-cdb.md) +### [Setting Breakpoints in CDB](setting-breakpoints-in-cdb.md) +### [Viewing the Call Stack in CDB](viewing-the-call-stack-in-cdb.md) +### [Viewing and Editing Memory in CDB](viewing-memory--variables--and-registers-in-cdb.md) +### [Viewing and Editing Registers in CDB](viewing-and-editing-registers-in-cdb.md) +### [Configuring Exceptions and Events in CDB](configuring-exceptions-and-events-in-cdb.md) +### [Keeping a Log File in CDB](keeping-a-log-file-in-cdb.md) +## [Local Kernel-Mode Debugging](performing-local-kernel-debugging.md) +## [Controlling the Target](controlling-the-target.md) +## [Enabling Postmortem Debugging](enabling-postmortem-debugging.md) +## [Using the Debugger Command Window](the-debugger-command-window.md) +### [Using Debugger Commands](using-debugger-commands.md) +### [Evaluating Expressions](evaluating-expressions.md) +### [Using Shell Commands](using-shell-commands.md) +### [Using Aliases](using-aliases.md) +### [Using Script Files](using-script-files.md) +### [Using Debugger Command Programs](using-debugger-command-programs.md) +#### [Elements of a Debugger Command Program](elements-of-a-debugger-command-program.md) +#### [Control Flow Tokens](control-flow-tokens.md) +#### [Executing a Debugger Command Program](executing-a-debugger-command-program.md) +#### [Debugger Command Program Examples](debugger-command-program-examples.md) +## [Using the WinDbg Graphical Interface](windbg-graphical-interface.md) +### [Using Debugging Information Windows](using-debugging-information-windows.md) +#### [Opening a Window](opening-a-window.md) +#### [Closing a Window](closing-a-window.md) +#### [Configuring a Window](configuring-a-window.md) +#### [Moving Through a Window](moving-through-a-window.md) +#### [Cutting and Pasting Text](cutting-and-pasting-text.md) +#### [Changing Text Properties](changing-text-properties.md) +#### [Positioning the Windows](positioning-the-windows.md) +##### [Debugging with Floating and Docked Windows](debugging-with-floating-and-docked-windows.md) +##### [Docking a Window](docking-a-window.md) +##### [Tabbing a Window](tabbing-a-window.md) +##### [Undocking a Window](undocking-a-window.md) +##### [Creating a New Dock](creating-a-new-dock.md) +##### [Resizing and Moving a Window](resizing-and-moving-a-window.md) +##### [Arranging Windows](arranging-windows.md) +### [Using Workspaces](using-workspaces.md) +#### [Creating and Opening a Workspace](creating-and-opening-a-workspace.md) +#### [Workspace Contents](workspace-contents.md) +#### [Using and Customizing WinDbg Themes](using-and-customizing-windbg-themes.md) +##### [Loading a Theme](loading-a-theme.md) +##### [Customizing a Theme](customizing-a-theme.md) +##### [Using Themes Provided in Debugging Tools for Windows](using-themes-provided-in-debugging-tools-for-windows.md) +### [Using the Toolbar and Status Bar](using-the-toolbar-and-status-bar.md) +### [Using the Help Documentation](using-the-help-documentation.md) +## [Using Debugger Extensions](debugger-extensions.md) +### [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) +### [Using Debugger Extension Commands](using-debugger-extension-commands.md) +### [Writing New Debugger Extensions](writing-new-debugger-extensions.md) +## [Remote Debugging](remote-debugging.md) +### [Choosing the Best Remote Debugging Method](choosing-the-best-remote-debugging-method.md) +### [Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md) +#### [Activating a Debugging Server](activating-a-debugging-server.md) +#### [Searching for Debugging Servers](searching-for-debugging-servers.md) +#### [Activating a Debugging Client](activating-a-debugging-client.md) +#### [Client and Server Examples](client-and-server-examples.md) +#### [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md) +### [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) +#### [Starting the Debugging Session](starting-the-debugging-session.md) +#### [Switching Modes](switching-modes.md) +#### [When to Use This Technique](when-to-use-this-technique.md) +#### [Combining This Method with Remote Debugging](combining-this-method-with-remote-debugging.md) +### [Remote Debugging Through Remote.exe](remote-debugging-through-remote-exe.md) +#### [The Remote.exe Utility](the-remote-exe-utility.md) +#### [Starting a Remote.exe Session](starting-a-remote-exe-session.md) +#### [Remote.exe Batch Files](remote-exe-batch-files.md) +### [Process Servers (User Mode)](process-servers--user-mode-.md) +#### [Activating a Process Server](activating-a-process-server.md) +#### [Searching for Process Servers](searching-for-process-servers.md) +#### [Activating a Smart Client](activating-a-smart-client.md) +#### [Process Server Examples](process-server-examples.md) +#### [Controlling a Process Server Session](controlling-a-process-server-session.md) +### [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md) +#### [Activating a KD Connection Server](activating-a-kd-connection-server.md) +#### [Searching for KD Connection Servers](searching-for-kd-connection-servers.md) +#### [Activating a Smart Client (Kernel Mode)](activating-a-smart-client--kernel-mode-.md) +#### [KD Connection Server Examples](kd-connection-server-examples.md) +#### [Controlling a KD Connection Server Session](controlling-a-kd-connection-server-session.md) +### [Repeaters](repeaters.md) +#### [Activating a Repeater](activating-a-repeater.md) +#### [Using a Repeater](using-a-repeater.md) +#### [Repeater Examples](repeater-examples.md) +### [Advanced Remote Debugging Scenarios](advanced-remote-debugging-scenarios.md) +#### [Debugging Targets on Multiple Computers](debugging-targets-on-multiple-computers.md) +#### [Symbols in the Middle](symbols-in-the-middle.md) +#### [Two Firewalls](two-firewalls.md) +### [Remote Debugging on Workgroup Computers](remote-debugging-on-workgroup-computers.md) +## [Debugging Previous Versions of Windows](debugging-previous-versions-of-windows.md) +### [Debugging Tools For Windows: What's New](debugging-tools-for-windows--what-s-new.md) +#### [Debugging Tools for Windows: New for Windows 8.1](debugging-tools-for-windows--new-for-windows-8-1.md) +#### [Debugging Tools for Windows: New for Windows 8](debugging-tools-for-windows--new-for-windows-8.md) +### [Debugging Tools For Windows8 Release Notes](debugging-tools-for-windows8-release-notes.md) +### [Debugging Windows XP and Windows Vista](debugging-windows-xp-and-windows-vista.md) +### [Debugging Using Visual Studio](debugging-using-visual-studio.md) +#### [Debugging a User-Mode Process Using Visual Studio](debugging-a-user-mode-process-using-visual-studio.md) +#### [Opening a Dump File Using Visual Studio](opening-a-crash-dump-file-using-visual-studio.md) +#### [Kernel-Mode Debugging in Visual Studio](performing-kernel-mode-debugging-using-visual-studio.md) +#### [Ending a Debugging Session in Visual Studio](ending-a-debugging-session-in-visual-studio.md) +#### [Setting Symbol and Executable Image Paths in Visual Studio](setting-symbol-and-source-paths-in-visual-studio.md) +#### [Remote Debugging Using Visual Studio](remote-debugging-using-visual-studio.md) +#### [Entering Debugger Commands in Visual Studio](entering-debugger-commands-in-visual-studio.md) +#### [Setting Breakpoints in Visual Studio](setting-breakpoints-in-visual-studio.md) +#### [Viewing the Call Stack in Visual Studio](viewing-the-call-stack-in-visual-studio.md) +#### [Source Code Debugging in Visual Studio](viewing-source-and-assembly-code-in-visual-studio.md) +#### [Viewing and Editing Memory and Registers in Visual Studio](viewing-memory--variables--and-registers-in-visual-studio.md) +#### [Controlling Threads and Processes in Visual Studio](viewing-threads-and-processes-in-visual-studio.md) +#### [Configuring Exceptions and Events in Visual Studio](configuring-exceptions-and-events-in-visual-studio.md) +#### [Keeping a Log File in Visual Studio](keeping-a-log-file-in-visual-studio.md) +### [Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging over a 1394 Cable in Visual Studio](setting-up-a-1394-cable-connection-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable in Visual Studio](setting-up-a-usb-3-0-cable-connection-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio](setting-up-a-usb-2-0-cable-connection-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging over a Serial Cable in Visual Studio](setting-up-a-null-modem-cable-connection-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio](setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md) +#### [Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio](setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md) +# [Debugging Techniques](debugging-techniques.md) +## [Standard Debugging Techniques](standard-debugging-techniques.md) +### [Using Breakpoints](using-breakpoints.md) +#### [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md) +#### [Breakpoint Syntax](breakpoint-syntax.md) +#### [Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md) +#### [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md) +#### [Initial Breakpoint](initial-breakpoint.md) +#### [User Space and System Space](user-space-and-system-space.md) +#### [Risks Entailed When Setting Breakpoints](risks-entailed-when-setting-breakpoints.md) +#### [Conditional breakpoints in WinDbg and other Windows debuggers](setting-a-conditional-breakpoint.md) +#### [Executing Until a Specified State is Reached](executing-until-a-specified-state-is-reached.md) +### [Reading and Writing Memory](reading-and-writing-memory.md) +#### [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) +#### [Accessing Memory by Physical Address](accessing-memory-by-physical-address.md) +#### [Accessing Global Variables](accessing-global-variables.md) +#### [Accessing Local Variables](accessing-local-variables.md) +#### [Controlling Variables Through the Watch Window](controlling-variables-through-the-watch-window.md) +#### [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md) +### [Using the !analyze Extension](using-the--analyze-extension.md) +### [Handling a Bug Check When Driver Verifier is Enabled](handling-a-bug-check-when-driver-verifier-is-enabled.md) +### [Noninvasive Debugging (User Mode)](noninvasive-debugging--user-mode-.md) +### [Debugging in Assembly Mode](debugging-in-assembly-mode.md) +### [Debugging in Source Mode](debugging-in-source-mode.md) +### [Debugging Optimized Code and Inline Functions](debugging-optimized-code-and-inline-functions-external.md) +### [Debugging Managed Code Using the Windows Debugger](debugging-managed-code.md) +### [Debugging Windows Apps Using the Windows Debugger](debugging-windows-store-apps-using-the-windows-debugger.md) +### [Changing Contexts](changing-contexts.md) +### [Controlling Processes and Threads](controlling-processes-and-threads.md) +### [Using Debugger Markup Language](debugger-markup-language-commands.md) +### [Controlling Exceptions and Events](controlling-exceptions-and-events.md) +### [Finding the Process ID](finding-the-process-id.md) +### [Debugging a Stack Overflow](debugging-a-stack-overflow.md) +### [Manually Walking a Stack](manually-walking-a-stack.md) +### [Debugging a Stack Trace that has JScript Frames](debugging-a-stack-trace-that-has-jscript-frames.md) +### [Debugging an Application Failure](debugging-an-application-failure.md) +### [Reattaching to the Target Application](reattaching-to-the-target-application.md) +### [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) +### [Synchronizing with the Target Computer](synchronizing-with-the-target-computer.md) +### [Finding a Memory Leak](finding-a-memory-leak.md) +#### [Determining Whether a Leak Exists](determining-whether-a-leak-exists.md) +#### [Finding a Kernel-Mode Memory Leak](finding-a-kernel-mode-memory-leak.md) +##### [Using PoolMon to Find a Kernel-Mode Memory Leak](using-poolmon-to-find-a-kernel-mode-memory-leak.md) +##### [Using the Kernel Debugger to Find a Kernel-Mode Memory Leak](using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md) +##### [Using Driver Verifier to Find a Kernel-Mode Memory Leak](using-driver-verifier-to-find-a-kernel-mode-memory-leak.md) +#### [Finding a User-Mode Memory Leak](finding-a-user-mode-memory-leak.md) +##### [Using Performance Monitor to Find a User-Mode Memory Leak](using-performance-monitor-to-find-a-user-mode-memory-leak.md) +##### [Using UMDH to Find a User-Mode Memory Leak](using-umdh-to-find-a-user-mode-memory-leak.md) +### [Debugging a Time Out](debugging-a-time-out.md) +#### [Resource Time Outs](resource-time-outs.md) +#### [Critical Section Time Outs](critical-section-time-outs.md) +### [Debugging a Stalled System](debugging-a-stalled-system.md) +#### [Finding the Failed Process](finding-the-failed-process.md) +#### [Debugging an Interrupt Storm](debugging-an-interrupt-storm.md) +### [Debugging Multiple Targets](debugging-multiple-targets.md) +### [Tracking Down a Processor Hog](tracking-down-a-processor-hog.md) +### [Determining the ACL of an Object](determining-the-acl-of-an-object.md) +### [Displaying a Critical Section](displaying-a-critical-section.md) +### [Debugging a Deadlock](debugging-a-deadlock.md) +### [Debugging a Failed Driver Unload](debugging-a-failed-driver-unload.md) +### [Reading Bug Check Callback Data](reading-bug-check-callback-data.md) +### [Debugging a User-Mode Failure with KD](debugging-a-user-mode-failure-with-kd.md) +### [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) +### [Mapping Driver Files](mapping-driver-files.md) +### [Messages from the Target](messages-from-the-target.md) +#### [Breaking Into the Debugger](breaking-into-the-debugger.md) +#### [Sending Output to the Debugger](sending-output-to-the-debugger.md) +#### [Reading and Filtering Debugging Messages](reading-and-filtering-debugging-messages.md) +#### [Determining if a Debugger is Attached](determining-if-a-debugger-is-attached.md) +## [Specialized Debugging Techniques](specialized-debugging-techniques.md) +### [Windows Runtime Debugging](windows-runtime-debugger-commands.md) +### [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md) +### [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md) +### [Debugging Device Nodes and Device Stacks](device-node-and-stack-debugger-commands.md) +### [Debugging Plug and Play and Power Issues](plug-and-play-and-power-debugger-commands.md) +### [Debugging a User-Mode Failure with KD](debugging-a-user-mode-failure-with-kd.md) +### [Debugging a Device Installation Co-Installer](debugging-a-device-installation-co-installer.md) +### [Debugging a Dual-Boot Machine](debugging-a-dual-boot-machine.md) +### [Debugging Windows Setup and the OS Loader](debugging-windows-setup-and-the-os-loader.md) +### [Debugging CSRSS](debugging-csrss.md) +### [Debugging WinLogon](debugging-winlogon.md) +### [Debugging BIOS Code](debugging-bios-code.md) +### [Specifying Module and Function Owners](specifying-module-and-function-owners.md) +### [RPC Debugging](rpc-debugging.md) +#### [Overview of RPC Debugging](overview-of-rpc-debugging.md) +#### [Enabling RPC State Information](enabling-rpc-state-information.md) +#### [Displaying RPC State Information](displaying-rpc-state-information.md) +##### [Using the RPC Debugger Extensions](using-the-rpc-debugger-extensions.md) +##### [Using the DbgRpc Tool](using-the-dbgrpc-tool.md) +##### [Get RPC Cell Information](get-rpc-cell-information.md) +##### [Get RPC Endpoint Information](get-rpc-endpoint-information.md) +##### [Get RPC Thread Information](get-rpc-thread-information.md) +##### [Get RPC Call Information](get-rpc-call-information.md) +##### [Get RPC Client Call Information](get-rpc-client-call-information.md) +#### [Common RPC Debugging Techniques](common-rpc-debugging-techniques.md) +##### [Analyzing a Stuck Call Problem](analyzing-a-stuck-call-problem.md) +##### [Tracking Contention in the Server Process](tracking-contention-in-the-server-process.md) +##### [Checking for Stuck Threads](checking-for-stuck-threads.md) +##### [Identifying the Caller From the Server Thread](identifying-the-caller-from-the-server-thread.md) +#### [RPC State Information Internals](rpc-state-information-internals.md) +### [ACPI Debugging](acpi-debugging.md) +#### [The AMLI Debugger](the-amli-debugger.md) +##### [Introduction to the AMLI Debugger](introduction-to-the-amli-debugger.md) +##### [Setting Up an AML Debugging Session](setting-up-an-aml-debugging-session.md) +##### [Basic AML Debugging](basic-aml-debugging.md) +##### [Using AMLI Debugger Extensions](using-amli-debugger-extensions.md) +##### [Using AMLI Debugger Commands](using-amli-debugger-commands.md) +##### [AML Debugging Examples](aml-debugging-examples.md) +#### [Other ACPI Debugging Extensions](other-acpi-debugging-extensions.md) +### [NDIS Debugging](ndis-debugging.md) +#### [Overview of NDIS Debugging](overview-of-ndis-debugging.md) +#### [Preparing for NDIS Debugging](preparing-for-ndis-debugging.md) +#### [Enabling NDIS Debug Tracing](enabling-ndis-debug-tracing.md) +##### [Enabling NDIS Debug Tracing By Setting Registry Values](enabling-ndis-debug-tracing-by-setting-registry-values.md) +### [Kernel Streaming Debugging](kernel-streaming-debugging.md) +#### [Overview of Kernel Streaming Debugging](overview-of-kernel-streaming-debugging.md) +#### [Analyzing a Video Stream Stall](analyzing-a-video-stream-stall.md) +##### [Determining the Cause of a Video Stream Stall](determining-the-cause-of-a-video-stream-stall.md) +##### [Debugging a Processing Stall](debugging-a-processing-stall.md) +##### [Using Logging to Track Important Events](using-logging-to-track-important-events.md) +##### [Interpreting Bug Check 0xCB](interpreting-bug-check-0xcb.md) +#### [Analyzing a Capture Stall](analyzing-a-capture-stall.md) +#### [Live Local Debugging](live-local-debugging.md) +#### [Graph Analysis with Unloadable Modules](graph-analysis-with-unloadable-modules.md) +#### [Using !ks.graph](using--ks-graph.md) +### [SCSI Miniport Debugging](scsi-miniport-debugging.md) +#### [Overview of SCSI Miniport Debugging](overview-of-scsi-miniport-debugging.md) +#### [Extensions for Debugging SCSI Miniport Drivers](extensions-for-debugging-scsi-miniport-drivers.md) +#### [Bug Checks for SCSI Miniport Debugging](bug-checks-for-scsi-miniport-debugging.md) +#### [Analyzing Stalled Drivers and Time-Outs](analyzing-stalled-drivers-and-time-outs.md) +#### [Important Breakpoints for Analyzing Reproducible Problems](important-breakpoints-for-analyzing-reproducible-problems.md) +### [Plug and Play Debugging](plug-and-play-debugging.md) +#### [Extensions for Debugging Plug and Play Drivers](extensions-for-debugging-plug-and-play-drivers.md) +#### [Determining the Status of a Device](determining-the-status-of-a-device.md) +#### [Device Node Status Flags](device-node-status-flags.md) +#### [Device Manager Problem Codes](device-manager-problem-codes.md) +#### [Checking for Resource Conflicts](checking-for-resource-conflicts.md) +### [Debugging a Service Application](debugging-a-service-application.md) +#### [Choosing the Best Method](choosing-the-best-method.md) +#### [Preparing to Debug the Service Application](preparing-to-debug-the-service-application.md) +#### [Debugging the Service Application Automatically](debugging-the-service-application-automatically.md) +#### [Debugging the Service Application Manually](debugging-the-service-application-manually.md) +### [Attaching to a Target Computer Running Hyper-V](attaching-to-a-target-computer-running-hyper-v.md) +#### [Debugging Hyper-V via a Null-modem Cable Connection](debugging-hyper-v-via-a-null-modem-cable-connection.md) +#### [Debugging Hyper-V via a 1394 Cable Connection](debugging-hyper-v-via-a-1394-cable-connection.md) +#### [Troubleshooting Hyper-V Debugging](troubleshooting-hyper-v-debugging.md) +# [Symbols for Windows Debugging (WinDbg, KD, CDB, NTSD)](symbols.md) +## [Introduction to Symbols](introduction-to-symbols.md) +### [Symbol path for Windows debuggers](symbol-path.md) +### [Symbols and Symbol Files](symbols-and-symbol-files.md) +### [Public and Private Symbols](public-and-private-symbols.md) +## [Accessing Symbols for Debugging](accessing-symbols-for-debugging.md) +### [Installing Windows Symbol Files](installing-windows-symbol-files.md) +### [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md) +#### [Using a Symbol Server](using-a-symbol-server.md) +#### [SymSrv](symsrv.md) +##### [Microsoft public symbol server](microsoft-public-symbols.md) +##### [Advanced SymSrv Use](advanced-symsrv-use.md) +##### [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md) +#### [HTTP Symbol Stores](http-symbol-stores.md) +#### [File Share (SMB) Symbol Server](file-share--smb--symbol-server.md) +#### [Symbol Store Folder Tree](symbol-store-folder-tree.md) +#### [SymProxy](symproxy.md) +##### [Installing SymProxy](installing-symproxy.md) +##### [Configuring the Registry](configuring-the-registry.md) +##### [Choosing Network Security Credentials](choosing-network-security-credentials.md) +##### [Configuring IIS for SymProxy](configuring-iis-for-symproxy.md) +##### [Setting Up Exclusion Lists](setting-up-exclusion-lists.md) +##### [Dealing with Unavailable Symbol Stores](dealing-with-unavailable-symbol-stores.md) +##### [Checking and Updating Status](checking-and-updating-status.md) +##### [Handling File Pointers](handling-file-pointers.md) +##### [Caching Acquired Symbol Files](caching-acquired-symbol-files.md) +##### [SymProxy Automated Installation](symproxy-automated-installation.md) +#### [Other Symbol Stores](other-symbol-stores.md) +#### [Other Symbol Servers](other-symbol-servers.md) +### [Deferred Symbol Loading](deferred-symbol-loading.md) +### [Avoiding debugger searches for unneeded symbols](avoiding-debugger-searches-for-unneeded-symbols.md) +## [SymStore](symstore.md) +### [SymStore Transactions](symstore-transactions.md) +### [File System References and Symbol Files](file-system-references-and-symbol-files.md) +### [SymStore Compressed Files](symstore-compressed-files.md) +### [Symbol Storage Format](symbol-storage-format.md) +## [How the Debugger Recognizes Symbols](how-the-debugger-recognizes-symbols.md) +### [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md) +### [Symbol Options](symbol-options.md) +### [Symbol Status Abbreviations](symbol-status-abbreviations.md) +## [Symbol Problems While Debugging](symbol-problems-while-debugging.md) +### [Verifying Symbols](verifying-symbols.md) +### [Matching Symbol Names](matching-symbol-names.md) +### [Reading Symbols from Paged-Out Headers](reading-symbols-from-paged-out-headers.md) +### [Mapping Symbols When the PEB is Paged Out](mapping-symbols-when-the-peb-is-paged-out.md) +### [Debugging User-Mode Processes Without Symbols](debugging-user-mode-processes-without-symbols.md) +### [Debugging Performance-Optimized Code](debugging-performance-optimized-code.md) +## [AgeStore](agestore.md) +### [Using AgeStore](using-agestore.md) +### [AgeStore Command-Line Options](agestore-command-line-options.md) +## [DBH](dbh.md) +### [Using DBH](using-dbh.md) +### [Additional DBH Examples](additional-dbh-examples.md) +### [DBH Command-Line Options](dbh-command-line-options.md) +### [DBH Commands](dbh-commands.md) +## [PDBCopy](pdbcopy.md) +### [Using PDBCopy](using-pdbcopy.md) +### [Choosing Which Public Symbols to Remove](choosing-which-public-symbols-to-remove.md) +### [PDBCopy Command-Line Options](pdbcopy-command-line-options.md) +## [SymChk](symchk.md) +### [Using SymChk](using-symchk.md) +### [Using a Manifest File with SymChk](using-a-manifest-file-with-symchk.md) +### [SymChk Command-Line Options](symchk-command-line-options.md) +# [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) +## [Kernel-Mode Dump Files](kernel-mode-dump-files.md) +### [Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) +#### [Complete Memory Dump](complete-memory-dump.md) +#### [Kernel Memory Dump](kernel-memory-dump.md) +#### [Small Memory Dump](small-memory-dump.md) +#### [Automatic Memory Dump](automatic-memory-dump.md) +#### [Active Memory Dump](active-memory-dump.md) +### [Creating a Kernel-Mode Dump File](creating-a-kernel-mode-dump-file.md) +#### [Enabling a Kernel-Mode Dump File](enabling-a-kernel-mode-dump-file.md) +#### [Forcing a System Crash](forcing-a-system-crash.md) +##### [Forcing a System Crash from the Debugger](forcing-a-system-crash-from-the-debugger.md) +##### [Forcing a System Crash from the Keyboard](forcing-a-system-crash-from-the-keyboard.md) +#### [Creating a Dump File Without a System Crash](creating-a-dump-file-without-a-system-crash.md) +#### [Verifying the Creation of a Kernel-Mode Dump File](verifying-the-creation-of-a-kernel-mode-dump-file.md) +### [Analyzing a Kernel-Mode Dump File](analyzing-a-kernel-mode-dump-file.md) +#### [Analyzing a Kernel-Mode Dump File with KD](analyzing-a-kernel-mode-dump-file-with-kd.md) +#### [Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) +#### [Analyzing a Kernel-Mode Dump File with KAnalyze](analyzing-a-kernel-mode-dump-file-with-kanalyze.md) +## [User-Mode Dump Files](user-mode-dump-files.md) +### [Varieties of User-Mode Dump Files](varieties-of-user-mode-dump-files.md) +#### [Full User-Mode Dumps](full-user-mode-dumps.md) +#### [Minidumps](minidumps.md) +### [Creating a User-Mode Dump File](creating-a-user-mode-dump-file.md) +#### [Choosing the Best Tool](choosing-the-best-tool.md) +#### [CDB and WinDbg](cdb-and-windbg.md) +#### [UserDump](userdump.md) +### [Analyzing a User-Mode Dump File](analyzing-a-user-mode-dump-file.md) +#### [Analyzing a User-Mode Dump File with CDB](analyzing-a-user-mode-dump-file-with-cdb.md) +#### [Analyzing a User-Mode Dump File with WinDbg](analyzing-a-user-mode-dump-file-with-windbg.md) +## [Extracting Information from a Dump File](extracting-information-from-a-dump-file.md) +## [CAB Files that Contain Paging Files Along with a Memory Dump](cab-files-that-contain-paging-files-along-with-a-memory-dump.md) +## [Debugging OCA minidump files](debugging-oca-minidump-files.md) +# [Bug Checks (Blue Screens)](bug-checks--blue-screens-.md) +## [General Tips for Blue Screens](general-troubleshooting-tips.md) +## [Blue Screen Data](blue-screen-data.md) +## [Bug Check Code Reference](bug-check-code-reference2.md) +### [Bug Check 0x1: APC_INDEX_MISMATCH](bug-check-0x1--apc-index-mismatch.md) +### [Bug Check 0x2: DEVICE_QUEUE_NOT_BUSY](bug-check-0x2--device-queue-not-busy.md) +### [Bug Check 0x3: INVALID_AFFINITY_SET](bug-check-0x3--invalid-affinity-set.md) +### [Bug Check 0x4: INVALID_DATA_ACCESS_TRAP](bug-check-0x4--invalid-data-access-trap.md) +### [Bug Check 0x5: INVALID_PROCESS_ATTACH_ATTEMPT](bug-check-0x5--invalid-process-attach-attempt.md) +### [Bug Check 0x6: INVALID_PROCESS_DETACH_ATTEMPT](bug-check-0x6--invalid-process-detach-attempt.md) +### [Bug Check 0x7: INVALID_SOFTWARE_INTERRUPT](bug-check-0x7--invalid-software-interrupt.md) +### [Bug Check 0x8: IRQL_NOT_DISPATCH_LEVEL](bug-check-0x8--irql-not-dispatch-level.md) +### [Bug Check 0x9: IRQL_NOT_GREATER_OR_EQUAL](bug-check-0x9--irql-not-greater-or-equal.md) +### [Bug Check 0xA: IRQL_NOT_LESS_OR_EQUAL](bug-check-0xa--irql-not-less-or-equal.md) +### [Bug Check 0xB: NO_EXCEPTION_HANDLING_SUPPORT](bug-check-0xb--no-exception-handling-support.md) +### [Bug Check 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED](bug-check-0xc--maximum-wait-objects-exceeded.md) +### [Bug Check 0xD: MUTEX_LEVEL_NUMBER_VIOLATION](bug-check-0xd--mutex-level-number-violation.md) +### [Bug Check 0xE: NO_USER_MODE_CONTEXT](bug-check-0xe--no-user-mode-context.md) +### [Bug Check 0xF: SPIN_LOCK_ALREADY_OWNED](bug-check-0xf--spin-lock-already-owned.md) +### [Bug Check 0x10: SPIN_LOCK_NOT_OWNED](bug-check-0x10--spin-lock-not-owned.md) +### [Bug Check 0x11: THREAD_NOT_MUTEX_OWNER](bug-check-0x11--thread-not-mutex-owner.md) +### [Bug Check 0x12: TRAP_CAUSE_UNKNOWN](bug-check-0x12--trap-cause-unknown.md) +### [Bug Check 0x13: EMPTY_THREAD_REAPER_LIST](bug-check-0x13--empty-thread-reaper-list.md) +### [Bug Check 0x14: CREATE_DELETE_LOCK_NOT_LOCKED](bug-check-0x14--create-delete-lock-not-locked.md) +### [Bug Check 0x15: LAST_CHANCE_CALLED_FROM_KMODE](bug-check-0x15--last-chance-called-from-kmode.md) +### [Bug Check 0x16: CID_HANDLE_CREATION](bug-check-0x16--cid-handle-creation.md) +### [Bug Check 0x17: CID_HANDLE_DELETION](bug-check-0x17--cid-handle-deletion.md) +### [Bug Check 0x18: REFERENCE_BY_POINTER](bug-check-0x18--reference-by-pointer.md) +### [(Developer Content) Bug Check 0x19: BAD_POOL_HEADER](bug-check-0x19--bad-pool-header.md) +### [Bug Check 0x1A: MEMORY_MANAGEMENT](bug-check-0x1a--memory-management.md) +### [Bug Check 0x1B: PFN_SHARE_COUNT](bug-check-0x1b--pfn-share-count.md) +### [Bug Check 0x1C: PFN_REFERENCE_COUNT](bug-check-0x1c--pfn-reference-count.md) +### [Bug Check 0x1D: NO_SPIN_LOCK_AVAILABLE](bug-check-0x1d--no-spin-lock-available.md) +### [Bug Check 0x1E: KMODE_EXCEPTION_NOT_HANDLED](bug-check-0x1e--kmode-exception-not-handled.md) +### [Bug Check 0x1F: SHARED_RESOURCE_CONV_ERROR](bug-check-0x1f--shared-resource-conv-error.md) +### [Bug Check 0x20: KERNEL_APC_PENDING_DURING_EXIT](bug-check-0x20--kernel-apc-pending-during-exit.md) +### [Bug Check 0x21: QUOTA_UNDERFLOW](bug-check-0x21--quota-underflow.md) +### [Bug Check 0x22: FILE_SYSTEM](bug-check-0x22--file-system.md) +### [Bug Check 0x23: FAT_FILE_SYSTEM](bug-check-0x23--fat-file-system.md) +### [Bug Check 0x24: NTFS_FILE_SYSTEM](bug-check-0x24--ntfs-file-system.md) +### [Bug Check 0x25: NPFS_FILE_SYSTEM](bug-check-0x25--npfs-file-system.md) +### [Bug Check 0x26: CDFS_FILE_SYSTEM](bug-check-0x26--cdfs-file-system.md) +### [Bug Check 0x27: RDR_FILE_SYSTEM](bug-check-0x27--rdr-file-system.md) +### [Bug Check 0x28: CORRUPT_ACCESS_TOKEN](bug-check-0x28--corrupt-access-token.md) +### [Bug Check 0x29: SECURITY_SYSTEM](bug-check-0x29--security-system.md) +### [Bug Check 0x2A: INCONSISTENT_IRP](bug-check-0x2a--inconsistent-irp.md) +### [Bug Check 0x2B: PANIC_STACK_SWITCH](bug-check-0x2b--panic-stack-switch.md) +### [Bug Check 0x2C: PORT_DRIVER_INTERNAL](bug-check-0x2c--port-driver-internal.md) +### [Bug Check 0x2D: SCSI_DISK_DRIVER_INTERNAL](bug-check-0x2d--scsi-disk-driver-internal.md) +### [Bug Check 0x2E: DATA_BUS_ERROR](bug-check-0x2e--data-bus-error.md) +### [Bug Check 0x2F: INSTRUCTION_BUS_ERROR](bug-check-0x2f--instruction-bus-error.md) +### [Bug Check 0x30: SET_OF_INVALID_CONTEXT](bug-check-0x30--set-of-invalid-context.md) +### [Bug Check 0x31: PHASE0_INITIALIZATION_FAILED](bug-check-0x31--phase0-initialization-failed.md) +### [Bug Check 0x32: PHASE1_INITIALIZATION_FAILED](bug-check-0x32--phase1-initialization-failed.md) +### [Bug Check 0x33: UNEXPECTED_INITIALIZATION_CALL](bug-check-0x33--unexpected-initialization-call.md) +### [Bug Check 0x34: CACHE_MANAGER](bug-check-0x34--cache-manager.md) +### [Bug Check 0x35: NO_MORE_IRP_STACK_LOCATIONS](bug-check-0x35--no-more-irp-stack-locations.md) +### [Bug Check 0x36: DEVICE_REFERENCE_COUNT_NOT_ZERO](bug-check-0x36--device-reference-count-not-zero.md) +### [Bug Check 0x37: FLOPPY_INTERNAL_ERROR](bug-check-0x37--floppy-internal-error.md) +### [Bug Check 0x38: SERIAL_DRIVER_INTERNAL](bug-check-0x38--serial-driver-internal.md) +### [Bug Check 0x39: SYSTEM_EXIT_OWNED_MUTEX](bug-check-0x39--system-exit-owned-mutex.md) +### [Bug Check 0x3A: SYSTEM_UNWIND_PREVIOUS_USER](bug-check-0x3a--system-unwind-previous-user.md) +### [Bug Check 0x3B: SYSTEM_SERVICE_EXCEPTION](bug-check-0x3b--system-service-exception.md) +### [Bug Check 0x3C: INTERRUPT_UNWIND_ATTEMPTED](bug-check-0x3c--interrupt-unwind-attempted.md) +### [Bug Check 0x3D: INTERRUPT_EXCEPTION_NOT_HANDLED](bug-check-0x3d--interrupt-exception-not-handled.md) +### [Bug Check 0x3E: MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED](bug-check-0x3e--multiprocessor-configuration-not-supported.md) +### [Bug Check 0x3F: NO_MORE_SYSTEM_PTES](bug-check-0x3f--no-more-system-ptes.md) +### [Bug Check 0x40: TARGET_MDL_TOO_SMALL](bug-check-0x40--target-mdl-too-small.md) +### [Bug Check 0x41: MUST_SUCCEED_POOL_EMPTY](bug-check-0x41--must-succeed-pool-empty.md) +### [Bug Check 0x42: ATDISK_DRIVER_INTERNAL](bug-check-0x42--atdisk-driver-internal.md) +### [Bug Check 0x43: NO_SUCH_PARTITION](bug-check-0x43--no-such-partition.md) +### [Bug Check 0x44: MULTIPLE_IRP_COMPLETE_REQUESTS](bug-check-0x44--multiple-irp-complete-requests.md) +### [Bug Check 0x45: INSUFFICIENT_SYSTEM_MAP_REGS](bug-check-0x45--insufficient-system-map-regs.md) +### [Bug Check 0x46: DEREF_UNKNOWN_LOGON_SESSION](bug-check-0x46--deref-unknown-logon-session.md) +### [Bug Check 0x47: REF_UNKNOWN_LOGON_SESSION](bug-check-0x47--ref-unknown-logon-session.md) +### [Bug Check 0x48: CANCEL_STATE_IN_COMPLETED_IRP](bug-check-0x48--cancel-state-in-completed-irp.md) +### [Bug Check 0x49: PAGE_FAULT_WITH_INTERRUPTS_OFF](bug-check-0x49--page-fault-with-interrupts-off.md) +### [Bug Check 0x4A: IRQL_GT_ZERO_AT_SYSTEM_SERVICE](bug-check-0x4a--irql-gt-zero-at-system-service.md) +### [Bug Check 0x4B: STREAMS_INTERNAL_ERROR](bug-check-0x4b--streams-internal-error.md) +### [Bug Check 0x4C: FATAL_UNHANDLED_HARD_ERROR](bug-check-0x4c--fatal-unhandled-hard-error.md) +### [Bug Check 0x4D: NO_PAGES_AVAILABLE](bug-check-0x4d--no-pages-available.md) +### [Bug Check 0x4E: PFN_LIST_CORRUPT](bug-check-0x4e--pfn-list-corrupt.md) +### [Bug Check 0x4F: NDIS_INTERNAL_ERROR](bug-check-0x4f--ndis-internal-error.md) +### [Bug Check 0x50: PAGE_FAULT_IN_NONPAGED_AREA](bug-check-0x50--page-fault-in-nonpaged-area.md) +### [Bug Check 0x51: REGISTRY_ERROR](bug-check-0x51--registry-error.md) +### [Bug Check 0x52: MAILSLOT_FILE_SYSTEM](bug-check-0x52--mailslot-file-system.md) +### [Bug Check 0x53: NO_BOOT_DEVICE](bug-check-0x53--no-boot-device.md) +### [Bug Check 0x54: LM_SERVER_INTERNAL_ERROR](bug-check-0x54--lm-server-internal-error.md) +### [Bug Check 0x55: DATA_COHERENCY_EXCEPTION](bug-check-0x55--data-coherency-exception.md) +### [Bug Check 0x56: INSTRUCTION_COHERENCY_EXCEPTION](bug-check-0x56--instruction-coherency-exception.md) +### [Bug Check 0x57: XNS_INTERNAL_ERROR](bug-check-0x57--xns-internal-error.md) +### [Bug Check 0x58: FTDISK_INTERNAL_ERROR](bug-check-0x58--ftdisk-internal-error.md) +### [Bug Check 0x59: PINBALL_FILE_SYSTEM](bug-check-0x59--pinball-file-system.md) +### [Bug Check 0x5A: CRITICAL_SERVICE_FAILED](bug-check-0x5a--critical-service-failed.md) +### [Bug Check 0x5B: SET_ENV_VAR_FAILED](bug-check-0x5b--set-env-var-failed.md) +### [Bug Check 0x5C: HAL_INITIALIZATION_FAILED](bug-check-0x5c--hal-initialization-failed.md) +### [Bug Check 0x5D: UNSUPPORTED_PROCESSOR](bug-check-0x5d--unsupported-processor.md) +### [Bug Check 0x5E: OBJECT_INITIALIZATION_FAILED](bug-check-0x5e--object-initialization-failed.md) +### [Bug Check 0x5F: SECURITY_INITIALIZATION_FAILED](bug-check-0x5f--security-initialization-failed.md) +### [Bug Check 0x60: PROCESS_INITIALIZATION_FAILED](bug-check-0x60--process-initialization-failed.md) +### [Bug Check 0x61: HAL1_INITIALIZATION_FAILED](bug-check-0x61--hal1-initialization-failed.md) +### [Bug Check 0x62: OBJECT1_INITIALIZATION_FAILED](bug-check-0x62--object1-initialization-failed.md) +### [Bug Check 0x63: SECURITY1_INITIALIZATION_FAILED](bug-check-0x63--security1-initialization-failed.md) +### [Bug Check 0x64: SYMBOLIC_INITIALIZATION_FAILED](bug-check-0x64--symbolic-initialization-failed.md) +### [Bug Check 0x65: MEMORY1_INITIALIZATION_FAILED](bug-check-0x65--memory1-initialization-failed.md) +### [Bug Check 0x66: CACHE_INITIALIZATION_FAILED](bug-check-0x66--cache-initialization-failed.md) +### [Bug Check 0x67: CONFIG_INITIALIZATION_FAILED](bug-check-0x67--config-initialization-failed.md) +### [Bug Check 0x68: FILE_INITIALIZATION_FAILED](bug-check-0x68--file-initialization-failed.md) +### [Bug Check 0x69: IO1_INITIALIZATION_FAILED](bug-check-0x69--io1-initialization-failed.md) +### [Bug Check 0x6A: LPC_INITIALIZATION_FAILED](bug-check-0x6a--lpc-initialization-failed.md) +### [Bug Check 0x6B: PROCESS1_INITIALIZATION_FAILED](bug-check-0x6b--process1-initialization-failed.md) +### [Bug Check 0x6C: REFMON_INITIALIZATION_FAILED](bug-check-0x6c--refmon-initialization-failed.md) +### [Bug Check 0x6D: SESSION1_INITIALIZATION_FAILED](bug-check-0x6d--session1-initialization-failed.md) +### [Bug Check 0x6E: SESSION2_INITIALIZATION_FAILED](bug-check-0x6e--session2-initialization-failed.md) +### [Bug Check 0x6F: SESSION3_INITIALIZATION_FAILED](bug-check-0x6f--session3-initialization-failed.md) +### [Bug Check 0x70: SESSION4_INITIALIZATION_FAILED](bug-check-0x70--session4-initialization-failed.md) +### [Bug Check 0x71: SESSION5_INITIALIZATION_FAILED](bug-check-0x71--session5-initialization-failed.md) +### [Bug Check 0x72: ASSIGN_DRIVE_LETTERS_FAILED](bug-check-0x72--assign-drive-letters-failed.md) +### [Bug Check 0x73: CONFIG_LIST_FAILED](bug-check-0x73--config-list-failed.md) +### [Bug Check 0x74: BAD_SYSTEM_CONFIG_INFO](bug-check-0x74--bad-system-config-info.md) +### [Bug Check 0x75: CANNOT_WRITE_CONFIGURATION](bug-check-0x75--cannot-write-configuration.md) +### [Bug Check 0x76: PROCESS_HAS_LOCKED_PAGES](bug-check-0x76--process-has-locked-pages.md) +### [Bug Check 0x77: KERNEL_STACK_INPAGE_ERROR](bug-check-0x77--kernel-stack-inpage-error.md) +### [Bug Check 0x78: PHASE0_EXCEPTION](bug-check-0x78--phase0-exception.md) +### [Bug Check 0x79: MISMATCHED_HAL](bug-check-0x79--mismatched-hal.md) +### [Bug Check 0x7A: KERNEL_DATA_INPAGE_ERROR](bug-check-0x7a--kernel-data-inpage-error.md) +### [Bug Check 0x7B: INACCESSIBLE_BOOT_DEVICE](bug-check-0x7b--inaccessible-boot-device.md) +### [Bug Check 0x7C: BUGCODE_NDIS_DRIVER](bug-check-0x7c--bugcode-ndis-driver.md) +### [Bug Check 0x7D: INSTALL_MORE_MEMORY](bug-check-0x7d--install-more-memory.md) +### [(Developer Content) Bug Check 0x7E: SYSTEM_THREAD_EXCEPTION_NOT_HANDLED](bug-check-0x7e--system-thread-exception-not-handled.md) +### [Bug Check 0x7F: UNEXPECTED_KERNEL_MODE_TRAP](bug-check-0x7f--unexpected-kernel-mode-trap.md) +### [Bug Check 0x80: NMI_HARDWARE_FAILURE](bug-check-0x80--nmi-hardware-failure.md) +### [Bug Check 0x81: SPIN_LOCK_INIT_FAILURE](bug-check-0x81--spin-lock-init-failure.md) +### [Bug Check 0x82: DFS_FILE_SYSTEM](bug-check-0x82--dfs-file-system.md) +### [Bug Check 0x85: SETUP_FAILURE](bug-check-0x85--setup-failure.md) +### [Bug Check 0x8B: MBR_CHECKSUM_MISMATCH](bug-check-0x8b--mbr-checksum-mismatch.md) +### [Bug Check 0x8E: KERNEL_MODE_EXCEPTION_NOT_HANDLED](bug-check-0x8e--kernel-mode-exception-not-handled.md) +### [Bug Check 0x8F: PP0_INITIALIZATION_FAILED](bug-check-0x8f--pp0-initialization-failed.md) +### [Bug Check 0x90: PP1_INITIALIZATION_FAILED](bug-check-0x90--pp1-initialization-failed.md) +### [Bug Check 0x92: UP_DRIVER_ON_MP_SYSTEM](bug-check-0x92--up-driver-on-mp-system.md) +### [Bug Check 0x93: INVALID_KERNEL_HANDLE](bug-check-0x93--invalid-kernel-handle.md) +### [Bug Check 0x94: KERNEL_STACK_LOCKED_AT_EXIT](bug-check-0x94--kernel-stack-locked-at-exit.md) +### [Bug Check 0x96: INVALID_WORK_QUEUE_ITEM](bug-check-0x96--invalid-work-queue-item.md) +### [Bug Check 0x97: BOUND_IMAGE_UNSUPPORTED](bug-check-0x97--bound-image-unsupported.md) +### [Bug Check 0x98: END_OF_NT_EVALUATION_PERIOD](bug-check-0x98--end-of-nt-evaluation-period.md) +### [Bug Check 0x99: INVALID_REGION_OR_SEGMENT](bug-check-0x99--invalid-region-or-segment.md) +### [Bug Check 0x9A: SYSTEM_LICENSE_VIOLATION](bug-check-0x9a--system-license-violation.md) +### [Bug Check 0x9B: UDFS_FILE_SYSTEM](bug-check-0x9b--udfs-file-system.md) +### [Bug Check 0x9C: MACHINE_CHECK_EXCEPTION](bug-check-0x9c--machine-check-exception.md) +### [Bug Check 0x9E: USER_MODE_HEALTH_MONITOR](bug-check-0x9e--user-mode-health-monitor.md) +### [(Developer Content) Bug Check 0x9F: DRIVER_POWER_STATE_FAILURE](bug-check-0x9f--driver-power-state-failure.md) +### [Bug Check 0xA0: INTERNAL_POWER_ERROR](bug-check-0xa0--internal-power-error.md) +### [Bug Check 0xA1: PCI_BUS_DRIVER_INTERNAL](bug-check-0xa1--pci-bus-driver-internal.md) +### [Bug Check 0xA2: MEMORY_IMAGE_CORRUPT](bug-check-0xa2--memory-image-corrupt.md) +### [Bug Check 0xA3: ACPI_DRIVER_INTERNAL](bug-check-0xa3--acpi-driver-internal.md) +### [Bug Check 0xA4: CNSS_FILE_SYSTEM_FILTER](bug-check-0xa4--cnss-file-system-filter.md) +### [Bug Check 0xA5: ACPI_BIOS_ERROR](bug-check-0xa5--acpi-bios-error.md) +### [Bug Check 0xA7: BAD_EXHANDLE](bug-check-0xa7--bad-exhandle.md) +### [Bug Check 0xAB: SESSION_HAS_VALID_POOL_ON_EXIT](bug-check-0xab--session-has-valid-pool-on-exit.md) +### [Bug Check 0xAC: HAL_MEMORY_ALLOCATION](bug-check-0xac--hal-memory-allocation.md) +### [Bug Check 0xAD: VIDEO_DRIVER_DEBUG_REPORT_REQUEST](bug-check-0xad--video-driver-debug-report-request.md) +### [Bug Check 0xB1: BGI_DETECTED_VIOLATION](bug-check-0xb1--bgi-detected-violation.md) +### [Bug Check 0xB4: VIDEO_DRIVER_INIT_FAILURE](bug-check-0xb4--video-driver-init-failure.md) +### [Bug Check 0xB8: ATTEMPTED_SWITCH_FROM_DPC](bug-check-0xb8--attempted-switch-from-dpc.md) +### [Bug Check 0xB9: CHIPSET_DETECTED_ERROR](bug-check-0xb9--chipset-detected-error.md) +### [Bug Check 0xBA: SESSION_HAS_VALID_VIEWS_ON_EXIT](bug-check-0xba--session-has-valid-views-on-exit.md) +### [Bug Check 0xBB: NETWORK_BOOT_INITIALIZATION_FAILED](bug-check-0xbb--network-boot-initialization-failed.md) +### [Bug Check 0xBC: NETWORK_BOOT_DUPLICATE_ADDRESS](bug-check-0xbc--network-boot-duplicate-address.md) +### [Bug Check 0xBD: INVALID_HIBERNATED_STATE](bug-check-0xbd--invalid-hibernated-state.md) +### [Bug Check 0xBE: ATTEMPTED_WRITE_TO_READONLY_MEMORY](bug-check-0xbe--attempted-write-to-readonly-memory.md) +### [Bug Check 0xBF: MUTEX_ALREADY_OWNED](bug-check-0xbf--mutex-already-owned.md) +### [Bug Check 0xC1: SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION](bug-check-0xc1--special-pool-detected-memory-corruption.md) +### [(Developer Content) Bug Check 0xC2: BAD_POOL_CALLER](bug-check-0xc2--bad-pool-caller.md) +### [Bug Check 0xC4: DRIVER_VERIFIER_DETECTED_VIOLATION](bug-check-0xc4--driver-verifier-detected-violation.md) +### [Bug Check 0xC5: DRIVER_CORRUPTED_EXPOOL](bug-check-0xc5--driver-corrupted-expool.md) +### [Bug Check 0xC6: DRIVER_CAUGHT_MODIFYING_FREED_POOL](bug-check-0xc6--driver-caught-modifying-freed-pool.md) +### [Bug Check 0xC7: TIMER_OR_DPC_INVALID](bug-check-0xc7--timer-or-dpc-invalid.md) +### [Bug Check 0xC8: IRQL_UNEXPECTED_VALUE](bug-check-0xc8--irql-unexpected-value.md) +### [Bug Check 0xC9: DRIVER_VERIFIER_IOMANAGER_VIOLATION ](bug-check-0xc9--driver-verifier-iomanager-violation.md) +### [Bug Check 0xCA: PNP_DETECTED_FATAL_ERROR](bug-check-0xca--pnp-detected-fatal-error.md) +### [Bug Check 0xCB: DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS](bug-check-0xcb--driver-left-locked-pages-in-process.md) +### [Bug Check 0xCC: PAGE_FAULT_IN_FREED_SPECIAL_POOL](bug-check-0xcc--page-fault-in-freed-special-pool.md) +### [Bug Check 0xCD: PAGE_FAULT_BEYOND_END_OF_ALLOCATION](bug-check-0xcd--page-fault-beyond-end-of-allocation.md) +### [Bug Check 0xCE: DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS](bug-check-0xce--driver-unloaded-without-cancelling-pending-operations.md) +### [Bug Check 0xCF: TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE](bug-check-0xcf--terminal-server-driver-made-incorrect-memory-reference.md) +### [Bug Check 0xD0: DRIVER_CORRUPTED_MMPOOL](bug-check-0xd0--driver-corrupted-mmpool.md) +### [Bug Check 0xD1: DRIVER_IRQL_NOT_LESS_OR_EQUAL](bug-check-0xd1--driver-irql-not-less-or-equal.md) +### [Bug Check 0xD2: BUGCODE_ID_DRIVER](bug-check-0xd2--bugcode-id-driver.md) +### [Bug Check 0xD3: DRIVER_PORTION_MUST_BE_NONPAGED](bug-check-0xd3--driver-portion-must-be-nonpaged.md) +### [Bug Check 0xD4: SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD](bug-check-0xd4--system-scan-at-raised-irql-caught-improper-driver-unlo.md) +### [Bug Check 0xD5: DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL](bug-check-0xd5--driver-page-fault-in-freed-special-pool.md) +### [Bug Check 0xD6: DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION](bug-check-0xd6--driver-page-fault-beyond-end-of-allocation.md) +### [Bug Check 0xD7: DRIVER_UNMAPPING_INVALID_VIEW](bug-check-0xd7--driver-unmapping-invalid-view.md) +### [Bug Check 0xD8: DRIVER_USED_EXCESSIVE_PTES](bug-check-0xd8--driver-used-excessive-ptes.md) +### [Bug Check 0xD9: LOCKED_PAGES_TRACKER_CORRUPTION](bug-check-0xd9--locked-pages-tracker-corruption.md) +### [Bug Check 0xDA: SYSTEM_PTE_MISUSE](bug-check-0xda--system-pte-misuse.md) +### [Bug Check 0xDB: DRIVER_CORRUPTED_SYSPTES](bug-check-0xdb--driver-corrupted-sysptes.md) +### [Bug Check 0xDC: DRIVER_INVALID_STACK_ACCESS](bug-check-0xdc--driver-invalid-stack-access.md) +### [Bug Check 0xDE: POOL_CORRUPTION_IN_FILE_AREA](bug-check-0xde--pool-corruption-in-file-area.md) +### [Bug Check 0xDF: IMPERSONATING_WORKER_THREAD](bug-check-0xdf--impersonating-worker-thread.md) +### [Bug Check 0xE0: ACPI_BIOS_FATAL_ERROR](bug-check-0xe0--acpi-bios-fatal-error.md) +### [Bug Check 0xE1: WORKER_THREAD_RETURNED_AT_BAD_IRQL](bug-check-0xe1--worker-thread-returned-at-bad-irql.md) +### [Bug Check 0xE2: MANUALLY_INITIATED_CRASH](bug-check-0xe2--manually-initiated-crash.md) +### [Bug Check 0xE3: RESOURCE_NOT_OWNED](bug-check-0xe3--resource-not-owned.md) +### [Bug Check 0xE4: WORKER_INVALID](bug-check-0xe4--worker-invalid.md) +### [Bug Check 0xE6: DRIVER_VERIFIER_DMA_VIOLATION](bug-check-0xe6--driver-verifier-dma-violation.md) +### [Bug Check 0xE7: INVALID_FLOATING_POINT_STATE](bug-check-0xe7--invalid-floating-point-state.md) +### [Bug Check 0xE8: INVALID_CANCEL_OF_FILE_OPEN](bug-check-0xe8--invalid-cancel-of-file-open.md) +### [Bug Check 0xE9: ACTIVE_EX_WORKER_THREAD_TERMINATION](bug-check-0xe9--active-ex-worker-thread-termination.md) +### [Bug Check 0xEA: THREAD_STUCK_IN_DEVICE_DRIVER](bug-check-0xea--thread-stuck-in-device-driver.md) +### [Bug Check 0xEB: DIRTY_MAPPED_PAGES_CONGESTION](bug-check-0xeb--dirty-mapped-pages-congestion.md) +### [Bug Check 0xEC: SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT](bug-check-0xec--session-has-valid-special-pool-on-exit.md) +### [Bug Check 0xED: UNMOUNTABLE_BOOT_VOLUME](bug-check-0xed--unmountable-boot-volume.md) +### [(Developer Content) Bug Check 0xEF: CRITICAL_PROCESS_DIED](bug-check-0xef--critical-process-died.md) +### [Bug Check 0xF1: SCSI_VERIFIER_DETECTED_VIOLATION](bug-check-0xf1--scsi-verifier-detected-violation.md) +### [Bug Check 0xF2: HARDWARE_INTERRUPT_STORM](bug-check-0xf2--hardware-interrupt-storm.md) +### [Bug Check 0xF3: DISORDERLY_SHUTDOWN](bug-check-0xf3--disorderly-shutdown.md) +### [Bug Check 0xF4: CRITICAL_OBJECT_TERMINATION](bug-check-0xf4--critical-object-termination.md) +### [Bug Check 0xF5: FLTMGR_FILE_SYSTEM](bug-check-0xf5--fltmgr-file-system.md) +### [Bug Check 0xF6: PCI_VERIFIER_DETECTED_VIOLATION](bug-check-0xf6--pci-verifier-detected-violation.md) +### [Bug Check 0xF7: DRIVER_OVERRAN_STACK_BUFFER](bug-check-0xf7--driver-overran-stack-buffer.md) +### [Bug Check 0xF8: RAMDISK_BOOT_INITIALIZATION_FAILED](bug-check-0xf8--ramdisk-boot-initialization-failed.md) +### [Bug Check 0xF9: DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN](bug-check-0xf9--driver-returned-status-reparse-for-volume-open.md) +### [Bug Check 0xFA: HTTP_DRIVER_CORRUPTED](bug-check-0xfa---http-driver-corrupted.md) +### [Bug Check 0xFC: ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY](bug-check-0xfc---attempted-execute-of-noexecute-memory.md) +### [Bug Check 0xFD: DIRTY_NOWRITE_PAGES_CONGESTION](bug-check-0xfd---dirty-nowrite-pages-congestion.md) +### [Bug Check 0xFE: BUGCODE_USB_DRIVER](bug-check-0xfe--bugcode-usb-driver.md) +### [Bug Check 0xFF: RESERVE_QUEUE_OVERFLOW](bug-check-0xff---reserve-queue-overflow.md) +### [Bug Check 0x100: LOADER_BLOCK_MISMATCH](bug-check-0x100---loader-block-mismatch.md) +### [Bug Check 0x101: CLOCK_WATCHDOG_TIMEOUT](bug-check-0x101---clock-watchdog-timeout.md) +### [Bug Check 0x102: DPC_WATCHDOG_TIMEOUT](bug-check-0x102--dpc-watchdog-timeout.md) +### [Bug Check 0x103: MUP_FILE_SYSTEM](bug-check-0x103---mup-file-system.md) +### [Bug Check 0x104: AGP_INVALID_ACCESS](bug-check-0x104---agp-invalid-access.md) +### [Bug Check 0x105: AGP_GART_CORRUPTION](bug-check-0x105---agp-gart-corruption.md) +### [Bug Check 0x106: AGP_ILLEGALLY_REPROGRAMMED](bug-check-0x106---agp-illegally-reprogrammed.md) +### [Bug Check 0x108: THIRD_PARTY_FILE_SYSTEM_FAILURE](bug-check-0x108--third-party-file-system-failure.md) +### [Bug Check 0x109: CRITICAL_STRUCTURE_CORRUPTION](bug-check-0x109---critical-structure-corruption.md) +### [Bug Check 0x10A: APP_TAGGING_INITIALIZATION_FAILED](bug-check-0x10a---app-tagging-initialization-failed.md) +### [Bug Check 0x10C: FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION](bug-check-0x10c---fsrtl-extra-create-parameter-violation.md) +### [Bug Check 0x10D: WDF_VIOLATION](bug-check-0x10d---wdf-violation.md) +### [Bug Check 0x10E: VIDEO_MEMORY_MANAGEMENT_INTERNAL](bug-check-0x10e---video-memory-management-internal.md) +### [Bug Check 0x10F: RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED](bug-check-0x10f---resource-manager-exception-not-handled.md) +### [Bug Check 0x111: RECURSIVE_NMI](bug-check-0x111---recursive-nmi.md) +### [Bug Check 0x112: MSRPC_STATE_VIOLATION](bug-check-0x112---msrpc-state-violation.md) +### [Bug Check 0x113: VIDEO_DXGKRNL_FATAL_ERROR](bug-check-0x113---video-dxgkrnl-fatal-error.md) +### [Bug Check 0x114: VIDEO_SHADOW_DRIVER_FATAL_ERROR](bug-check-0x114---video-shadow-driver-fatal-error.md) +### [Bug Check 0x115: AGP_INTERNAL](bug-check-0x115---agp-internal.md) +### [Bug Check 0x116: VIDEO_TDR_ERROR](bug-check-0x116---video-tdr-error.md) +### [Bug Check 0x117: VIDEO_TDR_TIMEOUT_DETECTED](bug-check-0x117---video-tdr-timeout-detected.md) +### [Bug Check 0x119: VIDEO_SCHEDULER_INTERNAL_ERROR](bug-check-0x119---video-scheduler-internal-error.md) +### [Bug Check 0x11A: EM_INITIALIZATION_FAILURE](bug-check-0x11a---em-initialization-failure.md) +### [Bug Check 0x11B: DRIVER_RETURNED_HOLDING_CANCEL_LOCK](bug-check-0x11b---driver-returned-holding-cancel-lock.md) +### [Bug Check 0x11C: ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE](bug-check-0x11c--attempted-write-to-cm-protected-storage.md) +### [Bug Check 0x11D: EVENT_TRACING_FATAL_ERROR](bug-check-0x11d---event-tracing-fatal-error.md) +### [Bug Check 0x11E: TOO_MANY_RECURSIVE_FAULTS](bug-check--0x11e--too-many-recursive-faults.md) +### [Bug Check 0x11F: INVALID_DRIVER_HANDLE](bug-check--0x11f--invalid-driver-handle.md) +### [Bug Check 0x120: BITLOCKER_FATAL_ERROR](bug-check--0x120--bitlocker-fatal-error-.md) +### [Bug Check 0x121: DRIVER_VIOLATION](bug-check-0x121---driver-violation.md) +### [Bug Check 0x122: WHEA_INTERNAL_ERROR](bug-check-0x122---whea-internal-error.md) +### [Bug Check 0x123: CRYPTO_SELF_TEST_FAILURE](bug-check--0x123--crypto-self-test-failure-.md) +### [Bug Check 0x124: WHEA_UNCORRECTABLE_ERROR](bug-check-0x124---whea-uncorrectable-error.md) +### [Bug Check 0x125: NMR_INVALID_STATE](bug-check--0x125--nmr-invalid-state.md) +### [Bug Check 0x126: NETIO_INVALID_POOL_CALLER](bug-check--0x126--netio-invalid-pool-caller.md) +### [Bug Check 0x127: PAGE_NOT_ZERO](bug-check-0x127---page-not-zero.md) +### [Bug Check 0x128: WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY](bug-check-0x128--worker-thread-returned-with-bad-io-priority.md) +### [Bug Check 0x129: WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY](bug-check-0x129--worker-thread-returned-with-bad-paging-io-priority.md) +### [Bug Check 0x12A: MUI_NO_VALID_SYSTEM_LANGUAGE](bug-check-0x12a--mui-no-valid-system-language.md) +### [Bug Check 0x12B: FAULTY_HARDWARE_CORRUPTED_PAGE](bug-check-0x12b---faulty-hardware-corrupted-page.md) +### [Bug Check 0x12C: EXFAT_FILE_SYSTEM](bug-check-0x12c---exfat-file-system.md) +### [Bug Check 0x12D: VOLSNAP_OVERLAPPED_TABLE_ACCESS](bug-check-0x12d--volsnap-overlapped-table-access.md) +### [Bug Check 0x12E: INVALID_MDL_RANGE](bug-check-0x12e--invalid-mdl-range.md) +### [Bug Check 0x12F: VHD_BOOT_INITIALIZATION_FAILED](bug-check-0x12f--vhd-boot-initialization-failed.md) +### [Bug Check 0x130: DYNAMIC_ADD_PROCESSOR_MISMATCH](bug-check-0x130--dynamic-add-processor-mismatch.md) +### [Bug Check 0x131: INVALID_EXTENDED_PROCESSOR_STATE](bug-check-0x131--invalid-extended-processor-state.md) +### [Bug Check 0x132: RESOURCE_OWNER_POINTER_INVALID](bug-check-0x132--resource-owner-pointer-invalid.md) +### [Bug Check 0x133 DPC_WATCHDOG_VIOLATION](bug-check-0x133-dpc-watchdog-violation.md) +### [Bug Check 0x134: DRIVE_EXTENDER](bug-check-0x134--drive-extender.md) +### [Bug Check 0x135: REGISTRY_FILTER_DRIVER_EXCEPTION](bug-check-0x135--registry-filter-driver-exception.md) +### [Bug Check 0x136: VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE](bug-check-0x136--vhd-boot-host-volume-not-enough-space.md) +### [Bug Check 0x137: WIN32K_HANDLE_MANAGER](bug-check-0x137--win32k-handle-manager.md) +### [Bug Check 0x138: GPIO_CONTROLLER_DRIVER_ERROR](bug-check-0x138-gpio-controller-driver-error.md) +### [Bug Check 0x139: KERNEL_SECURITY_CHECK_FAILURE](bug-check---bug-check-0x139-kernel-security-check-failure.md) +### [Bug Check 0x13A: KERNEL_MODE_HEAP_CORRUPTION](bug-check-0x13a--kernel-mode-heap-corruption.md) +### [Bug Check 0x13B: PASSIVE_INTERRUPT_ERROR](bug-check-0x13b--passive-interrupt-error.md) +### [Bug Check 0x13C: INVALID_IO_BOOST_STATE](bug-check-0x13c--invalid-io-boost-state.md) +### [Bug Check 0x13D: CRITICAL_INITIALIZATION_FAILURE](bug-check-0x13d--critical-initialization-failure.md) +### [Bug Check 0x140: STORAGE_DEVICE_ABNORMALITY_DETECTED](bug-check-0x140--storage-device-abnormality-detected.md) +### [Bug Check 0x141: VIDEO_ENGINE_TIMEOUT_DETECTED](bug-check-0x141---video-engine-timeout-detected.md) +### [Bug Check 0x142: VIDEO_TDR_APPLICATION_BLOCKED](bug-check-0x142--video-tdr-application-blocked.md) +### [Bug Check 0x143: PROCESSOR_DRIVER_INTERNAL](bug-check-0x143--processor-driver-internal.md) +### [Bug Check 0x144: BUGCODE_USB3_DRIVER](bug-check-0x144--bugcode-usb3-driver.md) +### [Bug Check 0x145: SECURE_BOOT_VIOLATION](bug-check-0x145--secure-boot-violation-.md) +### [Bug Check 0x147: ABNORMAL_RESET_DETECTED](bug-check-0x147--abnormal-reset-detected.md) +### [Bug Check 0x14B: SOC_SUBSYSTEM_FAILURE](bug-check-0x14b--soc-subsystem-failure.md) +### [Bug Check 0x149: REFS_FILE_SYSTEM](bug-check-0x149--refs-file-system.md) +### [Bug Check 0x14A: KERNEL_WMI_INTERNAL](bug-check-0x14a--kernel-wmi-internal.md) +### [Bug Check 0x14C: FATAL_ABNORMAL_RESET_ERROR](bug-check-0x14c--fatal-abnormal-reset-error.md) +### [Bug Check 0x14D: EXCEPTION_SCOPE_INVALID](bug-check-0x14d--exception-scope-invalid.md) +### [Bug Check 0x14E: SOC_CRITICAL_DEVICE_REMOVED](bug-check-0x14e--soc-critical-device-removed.md) +### [Bug Check 0x14F: PDC_WATCHDOG_TIMEOUT](bug-check-0x14f--pdc-watchdog-timeout.md) +### [Bug Check 0x150: TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK](bug-check-0x150--tcpip-aoac-nic-active-reference-leak.md) +### [Bug Check 0x151: UNSUPPORTED_INSTRUCTION_MODE](bug-check-0x151--unsupported-instruction-mode.md) +### [Bug Check 0x152: INVALID_PUSH_LOCK_FLAGS](bug-check-0x152--invalid-push-lock-flags.md) +### [Bug Check 0x153: KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION](bug-check-0x153--kernel-lock-entry-leaked-on-thread-termination.md) +### [Bug Check 0x154: UNEXPECTED_STORE_EXCEPTION](bug-check-0x154--unexpected-store-exception.md) +### [Bug Check 0x155: OS_DATA_TAMPERING](bug-check-0x155--os-data-tampering.md) +### [Bug Check 0x156: WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP](bug-check-0x156--winsock-detected-hung-closesocket-livedump.md) +### [Bug Check 0x157: KERNEL_THREAD_PRIORITY_FLOOR_VIOLATION](bug-check-0x157--kernel-thread-priority-floor-violation.md) +### [Bug Check 0x158: ILLEGAL_IOMMU_PAGE_FAULT](bug-check-0x158--illegal-iommu-page-fault.md) +### [Bug Check 0x159: HAL_ILLEGAL_IOMMU_PAGE_FAULT](bug-check-0x159--hal-illegal-iommu-page-fault.md) +### [Bug Check 0x15A: SDBUS_INTERNAL_ERROR](bug-check-0x15a--sdbus-internal-error.md) +### [Bug Check 0x15B: WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE](bug-check-0x15b--worker-thread-returned-with-system-page-priority-active.md) +### [Bug Check 0x15C: PDC_WATCHDOG_TIMEOUT_LIVEDUMP](bug-check-0x15c--pdc-watchdog-timeout-livedump.md) +### [Bug Check 0x15D: SOC_SUBSYSTEM_FAILURE_LIVEDUMP](bug-check-0x15d-soc-subsystem-failure-livedump.md) +### [Bug Check 0x15E: BUGCODE_NDIS_DRIVER_LIVE_DUMP](bug-check-0x15e-bugcode-ndis-driver-live-dump.md) +### [Bug Check 0x15F: CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP](bug-check-0x15f--connected-standby-watchdog-timeout-livedump.md) +### [Bug Check 0x160: WIN32K_ATOMIC_CHECK_FAILURE](bug-check-0x160--win32k-atomic-check-failure.md) +### [Bug Check 0x161: LIVE_SYSTEM_DUMP](bug-check-0x161--live-system-dump.md) +### [Bug Check 0x162: KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE](bug-check-0x162--kernel-auto-boost-invalid-lock-release.md) +### [Bug Check 0x163: WORKER_THREAD_TEST_CONDITION](bug-check-0x162--worker-thread-test-condition.md) +### [Bug Check 0x164: WIN32K_CRITICAL_FAILURE](bug-check-0x164--win32k-critical-failure.md) +### [Bug Check 0x16C: INVALID_RUNDOWN_PROTECTION_FLAGS](bug-check-0x16c--invalid-rundown-protection-flags.md) +### [Bug Check 0x16D: INVALID_SLOT_ALLOCATOR_FLAGS](bug-check-0x16d--invalid-slot-allocator-flags.md) +### [Bug Check 0x16E: ERESOURCE_INVALID_RELEASE](bug-check-0x16e--eresource-invalid-release.md) +### [Bug Check 0x175: PREVIOUS_FATAL_ABNORMAL_RESET_ERROR](bug-check-0x175--previous-fatal-abnormal-reset-error.md) +### [Bug Check 0x178: ELAM_DRIVER_DETECTED_FATAL_ERROR](bug-check-0x175--elam-driver-detected-fatal-error.md) +### [Bug Check 0x187: VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD](bug-check-0x187--video-dwminit-timeout-fallback-bdd.md) +### [Bug Check 0x188: CLUSTER_CSVFS_LIVEDUMP](bug-check-0x188--cluster-csvfs-livedump.md) +### [Bug Check 0x189: BAD_OBJECT_HEADER](bug-check-0x189--bad-object-header.md) +### [Bug Check 0x18B: SECURE_KERNEL_ERROR](bug-check-0x18b--secure-kernel-error.md) +### [Bug Check 0x190: WIN32K_CRITICAL_FAILURE_LIVEDUMP](bug-check-0x190--win32k-critical-failure-livedump.md) +### [Bug Check 0x191: PF_DETECTED_CORRUPTION](bug-check-0x191--pf-detected-corruption.md) +### [Bug Check 0x192: KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL](bug-check-0x192--kernel-auto-boost-lock-acquisition-with-raised-irql.md) +### [Bug Check 0x193: VIDEO_DXGKRNL_LIVEDUMP](bug-check-0x192--video-dxgkrnl-livedump.md) +### [Bug Check 0x195: SMB_SERVER_LIVEDUMP](bug-check-0x195--smb-server-livedump.md) +### [Bug Check 0x196: LOADER_ROLLBACK_DETECTED](bug-check-0x196--loader-rollback-detected.md) +### [Bug Check 0x197: WIN32K_SECURITY_FAILURE](bug-check-0x197--win32k-security-failure.md) +### [Bug Check 0x198: UFX_LIVEDUMP](bug-check-0x198--ufx-livedump.md) +### [Bug Check 0x199: KERNEL_STORAGE_SLOT_IN_USE](bug-check-0x199--kernel-storage-slot-in-use.md) +### [Bug Check 0x19A: WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO](bug-check-0x19a--worker-thread-returned-while-attached-to-silo.md) +### [Bug Check 0x19B: TTM_FATAL_ERROR](bug-check-0x19b--ttm-fatal-error.md) +### [Bug Check 0x19C: WIN32K_POWER_WATCHDOG_TIMEOUT](bug-check-0x19c--win32k-power-watchdog-timeout.md) +### [Bug Check 0x19D: CLUSTER_SVHDX_LIVEDUMP](bug-check-0x19d--cluster-svhdx-livedump.md) +### [Bug Check 0x1C4: DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP](bug-check-0x1c4--driver-verifier-detected-violation-livedump.md) +### [Bug Check 0x1C5: IO_THREADPOOL_DEADLOCK_LIVEDUMP](bug-check-0x1c5--io-threadpool-deadlock-livedump.md) +### [Bug Check 0xBFE: BC_BLUETOOTH_VERIFIER_FAULT](bug-check-0xbfe--bc-bluetooth-verifier-fault.md) +### [Bug Check 0xBFF: BC_BTHMINI_VERIFIER_FAULT](bug-check-0xbff--bc-bthmini-verifier-fault.md) +### [Bug Check 0x20001: HYPERVISOR_ERROR](bug-check--0x20001--hypervisor-error.md) +### [Bug Check 0x1000007E: SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M](bug-check-0x1000007e--system-thread-exception-not-handled-m.md) +### [Bug Check 0x1000007F: UNEXPECTED_KERNEL_MODE_TRAP_M](bug-check-0x1000007f--unexpected-kernel-mode-trap-m.md) +### [Bug Check 0x1000008E: KERNEL_MODE_EXCEPTION_NOT_HANDLED_M](bug-check-0x1000008e--kernel-mode-exception-not-handled-m.md) +### [Bug Check 0x100000EA: THREAD_STUCK_IN_DEVICE_DRIVER_M](bug-check-0x100000ea--thread-stuck-in-device-driver-m.md) +### [Bug Check 0x4000008A: THREAD_TERMINATE_HELD_MUTEX](bug-check-0x4000008a--thread-terminate-held-mutex.md) +### [Bug Check 0xC0000218: STATUS_CANNOT_LOAD_REGISTRY_FILE](bug-check-0xc0000218--status-cannot-load-registry-file.md) +### [Bug Check 0xC000021A: STATUS_SYSTEM_PROCESS_TERMINATED](bug-check-0xc000021a--status-system-process-terminated.md) +### [Bug Check 0xC0000221: STATUS_IMAGE_CHECKSUM_MISMATCH](bug-check-0xc0000221--status-image-checksum-mismatch.md) +### [Bug Check 0xDEADDEAD: MANUALLY_INITIATED_CRASH1](bug-check-0xdeaddead--manually-initiated-crash1.md) +# [Debugger Reference](debugger-reference.md) +## [Command-Line Options](command-line-options.md) +### [CDB Command-Line Options](cdb-command-line-options.md) +### [KD Command-Line Options](kd-command-line-options.md) +### [WinDbg Command-Line Options](windbg-command-line-options.md) +### [DbgSrv Command-Line Options](dbgsrv-command-line-options.md) +### [KdSrv Command-Line Options](kdsrv-command-line-options.md) +### [DbEngPrx Command-Line Options](dbengprx-command-line-options.md) +### [KDbgCtrl Command-Line Options](kdbgctrl-command-line-options.md) +### [DbgRpc Command-Line Options](dbgrpc-command-line-options.md) +### [SymStore Command-Line Options](symstore-command-line-options.md) +## [Environment Variables](environment-variables.md) +### [General Environment Variables](general-environment-variables.md) +### [Kernel-Mode Environment Variables](kernel-mode-environment-variables.md) +## [Debugger Commands](debugger-commands.md) +### [Syntax Rules](syntax-rules.md) +#### [Numerical Expression Syntax](numerical-expression-syntax.md) +##### [MASM Numbers and Operators](masm-numbers-and-operators.md) +##### [C++ Numbers and Operators](c---numbers-and-operators.md) +##### [MASM Expressions vs. C++ Expressions](masm-expressions-vs--c---expressions.md) +##### [Expression Examples](expression-examples.md) +##### [Sign Extension](sign-extension.md) +#### [String Wildcard Syntax](string-wildcard-syntax.md) +#### [Register Syntax](register-syntax.md) +#### [Pseudo-Register Syntax](pseudo-register-syntax.md) +#### [Source Line Syntax](source-line-syntax.md) +#### [Address and Address Range Syntax](address-and-address-range-syntax.md) +#### [Thread Syntax](thread-syntax.md) +#### [Process Syntax](process-syntax.md) +#### [System Syntax](system-syntax.md) +#### [Multiprocessor Syntax](multiprocessor-syntax.md) +### [Command Tokens](command-tokens.md) +#### [; (Command Separator)](----command-separator-.md) +#### [{ } (Block Delimiter)](------block-delimiter-.md) +#### [${ } (Alias Interpreter)](-------alias-interpreter-.md) +#### [$$ (Comment Specifier)](-----comment-specifier-.md) +#### [* (Comment Line Specifier)](----comment-line-specifier-.md) +#### [.block](-block.md) +#### [.break](-break3.md) +#### [.catch](-catch.md) +#### [.continue](-continue.md) +#### [.do](-do.md) +#### [.else](-else.md) +#### [.elsif](-elsif.md) +#### [.for](-for.md) +#### [.foreach](-foreach.md) +#### [.if](-if.md) +#### [.leave](-leave.md) +#### [.printf](-printf.md) +#### [.while](-while.md) +### [Commands](commands.md) +#### [ENTER (Repeat Last Command)](enter--repeat-last-command-.md) +#### [$<, $><, $$<, $$><, $$ >a< (Run Script File)](-----------------------a---run-script-file-.md) +#### [? (Command Help)](---command-help-.md) +#### [? (Evaluate Expression)](---evaluate-expression-.md) +#### [?? (Evaluate C++ Expression)](----evaluate-c---expression-.md) +#### [# (Search for Disassembly Pattern)](---search-for-disassembly-pattern-.md) +#### [|| (System Status)](----system-status-.md) +#### [||s (Set Current System)](--s--set-current-system-.md) +#### [| (Process Status)](---process-status-.md) +#### [|s (Set Current Process)](-s--set-current-process-.md) +#### [~ (Thread Status)](---thread-status-.md) +#### [~e (Thread-Specific Command)](-e--thread-specific-command-.md) +#### [~f (Freeze Thread)](-f--freeze-thread-.md) +#### [~u (Unfreeze Thread)](-u--unfreeze-thread-.md) +#### [~n (Suspend Thread)](-n--suspend-thread-.md) +#### [~m (Resume Thread)](-m--resume-thread-.md) +#### [~s (Set Current Thread)](-s--set-current-thread-.md) +#### [~s (Change Current Processor)](-s--change-current-processor-.md) +#### [a (Assemble)](a--assemble-.md) +#### [ad (Delete Alias)](ad--delete-alias-.md) +#### [ah (Assertion Handling)](ah--assertion-handling-.md) +#### [al (List Aliases)](al--list-aliases-.md) +#### [as, aS (Set Alias)](as--as--set-alias-.md) +#### [ba (Break on Access)](ba--break-on-access-.md) +#### [bc (Breakpoint Clear)](bc--breakpoint-clear-.md) +#### [bd (Breakpoint Disable)](bd--breakpoint-disable-.md) +#### [be (Breakpoint Enable)](be--breakpoint-enable-.md) +#### [bl (Breakpoint List)](bl--breakpoint-list-.md) +#### [bp, bu, bm (Set Breakpoint)](bp--bu--bm--set-breakpoint-.md) +#### [br (Breakpoint Renumber)](br--breakpoint-renumber-.md) +#### [bs (Update Breakpoint Command)](bs--update-breakpoint-command-.md) +#### [bsc (Update Conditional Breakpoint)](bsc--update-conditional-breakpoint-.md) +#### [c (Compare Memory)](c--compare-memory-.md) +#### [d, da, db, dc, dd, dD, df, dp, dq, du, dw, dW, dyb, dyd (Display Memory)](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) +#### [dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory)](dda--ddp--ddu--dpa--dpp--dpu--dqa--dqp--dqu--display-referenced-memory.md) +#### [dds, dps, dqs (Display Words and Symbols)](dds--dps--dqs--display-words-and-symbols-.md) +#### [dg (Display Selector)](dg--display-selector-.md) +#### [dl (Display Linked List)](dl--display-linked-list-.md) +#### [ds, dS (Display String)](ds--ds--display-string-.md) +#### [dt (Display Type)](dt--display-type-.md) +#### [dtx (Display Type - Extended Debugger Object Model Information)](dtx--display-type---extended-debugger-object-model-information-.md) +#### [dv (Display Local Variables)](dv--display-local-variables-.md) +#### [dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md) +#### [e, ea, eb, ed, eD, ef, ep, eq, eu, ew, eza, ezu (Enter Values)](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) +#### [f, fp (Fill Memory)](f--fp--fill-memory-.md) +#### [g (Go)](g--go-.md) +#### [gc (Go from Conditional Breakpoint)](gc--go-from-conditional-breakpoint-.md) +#### [gh (Go with Exception Handled)](gh--go-with-exception-handled-.md) +#### [gn, gN (Go with Exception Not Handled)](gn--gn--go-with-exception-not-handled-.md) +#### [gu (Go Up)](gu--go-up-.md) +#### [ib, iw, id (Input from Port)](ib--iw--id--input-from-port-.md) +#### [j (Execute If - Else)](j--execute-if---else-.md) +#### [k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) +#### [l+, l- (Set Source Options)](l---l---set-source-options-.md) +#### [ld (Load Symbols)](ld--load-symbols-.md) +#### [lm (List Loaded Modules)](lm--list-loaded-modules-.md) +#### [ln (List Nearest Symbols)](ln--list-nearest-symbols-.md) +#### [ls, lsa (List Source Lines)](ls--lsa--list-source-lines-.md) +#### [lsc (List Current Source)](lsc--list-current-source-.md) +#### [lse (Launch Source Editor)](lse--launch-source-editor-.md) +#### [lsf, lsf- (Load or Unload Source File)](lsf--lsf---load-or-unload-source-file-.md) +#### [lsp (Set Number of Source Lines)](lsp--set-number-of-source-lines-.md) +#### [m (Move Memory)](m--move-memory-.md) +#### [n (Set Number Base)](n--set-number-base-.md) +#### [ob, ow, od (Output to Port)](ob--ow--od--output-to-port-.md) +#### [p (Step)](p--step-.md) +#### [pa (Step to Address)](pa--step-to-address-.md) +#### [pc (Step to Next Call)](pc--step-to-next-call-.md) +#### [pct (Step to Next Call or Return)](pct--step-to-next-call-or-return-.md) +#### [ph (Step to Next Branching Instruction)](ph--step-to-next-branching-instruction-.md) +#### [pt (Step to Next Return)](pt--step-to-next-return-.md) +#### [q, qq (Quit)](q--qq--quit-.md) +#### [qd (Quit and Detach)](qd--quit-and-detach-.md) +#### [r (Registers)](r--registers-.md) +#### [rdmsr (Read MSR)](rdmsr--read-msr-.md) +#### [rm (Register Mask)](rm--register-mask-.md) +#### [s (Search Memory)](s--search-memory-.md) +#### [so (Set Kernel Debugging Options)](so--set-kernel-debugging-options-.md) +#### [sq (Set Quiet Mode)](sq--set-quiet-mode-.md) +#### [ss (Set Symbol Suffix)](ss--set-symbol-suffix-.md) +#### [sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions)](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) +#### [t (Trace)](t--trace-.md) +#### [ta (Trace to Address)](ta--trace-to-address-.md) +#### [tb (Trace to Next Branch)](tb--trace-to-next-branch-.md) +#### [tc (Trace to Next Call)](tc--trace-to-next-call-.md) +#### [tct (Trace to Next Call or Return)](tct--trace-to-next-call-or-return-.md) +#### [th (Trace to Next Branching Instruction)](th--trace-to-next-branching-instruction-.md) +#### [tt (Trace to Next Return)](tt--trace-to-next-return-.md) +#### [u (Unassemble)](u--unassemble-.md) +#### [uf (Unassemble Function)](uf--unassemble-function-.md) +#### [up (Unassemble from Physical Memory)](up--unassemble-from-physical-memory-.md) +#### [ur (Unassemble Real Mode BIOS)](ur--unassemble-real-mode-bios-.md) +#### [ux (Unassemble x86 BIOS)](ux--unassemble-x86-bios-.md) +#### [vercommand (Show Debugger Command Line)](vercommand--show-debugger-command-line-.md) +#### [version (Show Debugger Version)](version--show-debugger-version-.md) +#### [vertarget (Show Target Computer Version)](vertarget--show-target-computer-version-.md) +#### [wrmsr (Write MSR)](wrmsr--write-msr-.md) +#### [wt (Trace and Watch Data)](wt--trace-and-watch-data-.md) +#### [x (Examine Symbols)](x--examine-symbols-.md) +#### [z (Execute While)](z--execute-while-.md) +### [Meta-Commands](meta-commands.md) +#### [.abandon (Abandon Process)](-abandon--abandon-process-.md) +#### [.allow_exec_cmds (Allow Execution Commands)](-allow-exec-cmds--allow-execution-commands-.md) +#### [.allow_image_mapping (Allow Image Mapping)](-allow-image-mapping--allow-image-mapping-.md) +#### [.apply_dbp (Apply Data Breakpoint to Context)](-apply-dbp--apply-data-breakpoint-to-context-.md) +#### [.asm (Change Disassembly Options)](-asm--change-disassembly-options-.md) +#### [.attach (Attach to Process)](-attach--attach-to-process-.md) +#### [.beep (Speaker Beep)](-beep--speaker-beep-.md) +#### [.bpcmds (Display Breakpoint Commands)](-bpcmds--display-breakpoint-commands-.md) +#### [.bpsync (Synchronize Threads at Breakpoint)](-bpsync--synchronize-threads-at-breakpoint-.md) +#### [.breakin (Break to the Kernel Debugger)](-breakin--break-to-the-kernel-debugger-.md) +#### [.browse (Display Command in Browser)](-browse--display-command-in-browser-.md) +#### [.bugcheck (Display Bug Check Data)](-bugcheck--display-bug-check-data-.md) +#### [.cache (Set Cache Size)](-cache--set-cache-size-.md) +#### [.call (Call Function)](-call--call-function-.md) +#### [.chain (List Debugger Extensions)](-chain--list-debugger-extensions-.md) +#### [.childdbg (Debug Child Processes)](-childdbg--debug-child-processes-.md) +#### [.clients (List Debugging Clients)](-clients--list-debugging-clients-.md) +#### [.closehandle (Close Handle)](-closehandle--close-handle-.md) +#### [.cls (Clear Screen)](-cls--clear-screen-.md) +#### [.context (Set User-Mode Address Context)](-context--set-user-mode-address-context-.md) +#### [.copysym (Copy Symbol Files)](-copysym--copy-symbol-files-.md) +#### [.cordll (Control CLR Debugging)](-cordll--control-clr-debugging-.md) +#### [.crash (Force System Crash)](-crash--force-system-crash-.md) +#### [.create (Create Process)](-create--create-process-.md) +#### [.createdir (Set Created Process Directory)](-createdir--set-created-process-directory-.md) +#### [.cxr (Display Context Record)](-cxr--display-context-record-.md) +#### [.dbgdbg (Debug Current Debugger)](-dbgdbg--debug-current-debugger-.md) +#### [.detach (Detach from Process)](-detach--detach-from-process-.md) +#### [.dml_flow (Unassemble with Links)](-dml-flow.md) +#### [.dml_start (Display DML Starting Point)](-dml-start.md) +#### [.dump (Create Dump File)](-dump--create-dump-file-.md) +#### [.dumpcab (Create Dump File CAB)](-dumpcab--create-dump-file-cab-.md) +#### [.dvalloc (Allocate Memory)](-dvalloc--allocate-memory-.md) +#### [.dvfree (Free Memory)](-dvfree--free-memory-.md) +#### [.echo (Echo Comment)](-echo--echo-comment-.md) +#### [.echocpunum (Show CPU Number)](-echocpunum--show-cpu-number-.md) +#### [.echotime (Show Current Time)](-echotime--show-current-time-.md) +#### [.echotimestamps (Show Time Stamps)](-echotimestamps--show-time-stamps-.md) +#### [.ecxr (Display Exception Context Record)](-ecxr--display-exception-context-record-.md) +#### [.effmach (Effective Machine)](-effmach--effective-machine-.md) +#### [.enable_long_status (Enable Long Integer Display)](-enable-long-status--enable-long-integer-display-.md) +#### [.enable_unicode (Enable Unicode Display)](-enable-unicode--enable-unicode-display-.md) +#### [.endpsrv (End Process Server)](-endpsrv--end-process-server-.md) +#### [.endsrv (End Debugging Server)](-endsrv--end-debugging-server-.md) +#### [.enumtag (Enumerate Secondary Callback Data)](-enumtag--enumerate-secondary-callback-data-.md) +#### [.event_code (Display Event Code)](-event-code--display-event-code-.md) +#### [.eventlog (Display Recent Events)](-eventlog--display-recent-events-.md) +#### [.exepath (Set Executable Path)](-exepath--set-executable-path-.md) +#### [.expr (Choose Expression Evaluator)](-expr--choose-expression-evaluator-.md) +#### [.exptr (Display Exception Pointers)](-exptr--display-exception-pointers-.md) +#### [.exr (Display Exception Record)](-exr--display-exception-record-.md) +#### [.excr (Display Exception Context Record)](-excr--display-exception-context-record-.md) +#### [.extmatch (Display All Matching Extensions)](-extmatch--display-all-matching-extensions-.md) +#### [.extpath (Set Extension Path)](-extpath--set-extension-path-.md) +#### [.f+, .f- (Shift Local Context)](-f----f---shift-local-context-.md) +#### [.fiber (Set Fiber Context)](-fiber--set-fiber-context-.md) +#### [.fiximports (Fix Target Module Imports)](-fiximports--fix-target-module-imports-.md) +#### [.flash_on_break (Flash on Break)](-flash-on-break--flash-on-break-.md) +#### [.fnent (Display Function Data)](-fnent--display-function-data-.md) +#### [.fnret (Display Function Return Value)](-fnret--display-function-return-value-.md) +#### [.force_radix_output (Use Radix for Integers)](-force-radix-output--use-radix-for-integers-.md) +#### [.force_tb (Forcibly Allow Branch Tracing)](-force-tb--forcibly-allow-branch-tracing-.md) +#### [.formats (Show Number Formats)](-formats--show-number-formats-.md) +#### [.fpo (Control FPO Overrides)](-fpo--control-fpo-overrides-.md) +#### [.frame (Set Local Context)](-frame--set-local-context-.md) +#### [.help (Meta-Command Help)](-help--meta-command-help-.md) +#### [.hh (Open HTML Help File)](-hh--open-html-help-file-.md) +#### [.hideinjectedcode (Hide Injected Code)](-hideinjectedcode.md) +#### [.holdmem (Hold and Compare Memory)](-holdmem--hold-and-compare-memory-.md) +#### [.idle_cmd (Set Idle Command)](-idle-cmd--set-idle-command-.md) +#### [.ignore_missing_pages (Suppress Missing Page Errors)](-ignore-missing-pages--suppress-missing-page-errors-.md) +#### [.inline (Toggle Inline Function Debugging)](-inline--toggle-inline-debugging-.md) +#### [.imgscan (Find Image Headers)](-imgscan--find-image-headers-.md) +#### [.jdinfo (Use JIT_DEBUG_INFO)](-jdinfo--use-jit-debug-info-.md) +#### [.kdfiles (Set Driver Replacement Map)](-kdfiles--set-driver-replacement-map-.md) +#### [.kdtargetmac (Display Target MAC Address)](-kdtargetmac--display-target-mac-address-.md) +#### [.kframes (Set Stack Length)](-kframes--set-stack-length-.md) +#### [.kill (Kill Process)](-kill--kill-process-.md) +#### [.lastevent (Display Last Event)](-lastevent--display-last-event-.md) +#### [.lines (Toggle Source Line Support)](-lines--toggle-source-line-support-.md) +#### [.load, .loadby (Load Extension DLL)](-load---loadby--load-extension-dll-.md) +#### [.locale (Set Locale)](-locale--set-locale-.md) +#### [.logappend (Append Log File)](-logappend--append-log-file-.md) +#### [.logclose (Close Log File)](-logclose--close-log-file-.md) +#### [.logfile (Display Log File Status)](-logfile--display-log-file-status-.md) +#### [.logopen (Open Log File)](-logopen--open-log-file-.md) +#### [.netsyms (Disable Network Symbol Loading)](-netsyms.md) +#### [.netuse (Control Network Connections)](-netuse--control-network-connections-.md) +#### [.noshell (Prohibit Shell Commands)](-noshell--prohibit-shell-commands-.md) +#### [.noversion (Disable Version Checking)](-noversion--disable-version-checking-.md) +#### [.ocommand (Expect Commands from Target)](-ocommand--expect-commands-from-target-.md) +#### [.nvload (NatVis Load)](-nvload--natvis-load-.md) +#### [.nvlist (NatVis List)](-nvlist--natvis-list-.md) +#### [.nvunload (NatVis Unload)](-nvunload--natvis-unload-.md) +#### [.nvunloadall (NatVis Unload All)](-nvunloadall--natvis-unload-all-.md) +#### [.ofilter (Filter Target Output)](-ofilter--filter-target-output-.md) +#### [.open (Open Source File)](-open--open-source-file-.md) +#### [.opendump (Open Dump File)](-opendump--open-dump-file-.md) +#### [.outmask (Control Output Mask)](-outmask--control-output-mask-.md) +#### [.pagein (Page In Memory)](-pagein--page-in-memory-.md) +#### [.pcmd (Set Prompt Command)](-pcmd--set-prompt-command-.md) +#### [.pop (Restore Debugger State)](-pop--restore-debugger-state-.md) +#### [.prefer_dml (Prefer Debugger Markup Language)](-prefer-dml.md) +#### [.process (Set Process Context)](-process--set-process-context-.md) +#### [.prompt_allow (Control Prompt Display)](-prompt-allow--control-prompt-display-.md) +#### [.push (Save Debugger State)](-push--save-debugger-state-.md) +#### [.quit_lock (Prevent Accidental Quit)](-quit-lock--prevent-accidental-quit-.md) +#### [.readmem (Read Memory from File)](-readmem--read-memory-from-file-.md) +#### [.reboot (Reboot Target Computer)](-reboot--reboot-target-computer-.md) +#### [.record_branches (Enable Branch Recording)](-record-branches--enable-branch-recording-.md) +#### [.reload (Reload Module)](-reload--reload-module-.md) +#### [.remote (Create Remote.exe Server)](-remote--create-remote-exe-server-.md) +#### [.remote_exit (Exit Debugging Client)](-remote-exit--exit-debugging-client-.md) +#### [.restart (Restart Target Application)](-restart--restart-target-application-.md) +#### [.restart (Restart Kernel Connection)](-restart--restart-kernel-connection-.md) +#### [.rrestart (Register for Restart)](-rrestart--register-for-restart-.md) +#### [.scroll_prefs (Control Source Scrolling Preferences)](-scroll-prefs--control-source-scrolling-preferences-.md) +#### [.scriptlist (List Loaded Scripts)](-scriptlist--list-loaded-scripts-.md) +#### [.scriptload (Load Script)](-scriptload--load-script-.md) +#### [.scriptproviders (List Script Providers)](-scriptproviders--list-script-providers-.md) +#### [.scriptrun (Run Script)](-scriptrun--run-script-.md) +#### [.scriptunload (Unload Script)](-scriptunload--unload-script-.md) +#### [.secure (Activate Secure Mode)](-secure--activate-secure-mode-.md) +#### [.send_file (Send File)](-send-file--send-file-.md) +#### [.server (Create Debugging Server)](-server--create-debugging-server-.md) +#### [.servers (List Debugging Servers)](-servers--list-debugging-servers-.md) +#### [.setdll (Set Default Extension DLL)](-setdll--set-default-extension-dll-.md) +#### [.shell (Command Shell)](-shell--command-shell-.md) +#### [.settings (Set Debug Settings)](-settings--set-debug-settings-.md) +#### [.show_read_failures](-show-read-failures.md) +#### [.show_sym_failures](-show-sym-failures.md) +#### [.sleep (Pause Debugger)](-sleep--pause-debugger-.md) +#### [.sound_notify (Use Notification Sound)](-sound-notify--use-notification-sound-.md) +#### [.srcfix, .lsrcfix (Use Source Server)](-srcfix---lsrcfix--use-source-server-.md) +#### [.srcnoisy (Noisy Source Loading)](-srcnoisy--noisy-source-loading-.md) +#### [.srcpath, .lsrcpath (Set Source Path)](-srcpath---lsrcpath--set-source-path-.md) +#### [.step_filter (Set Step Filter)](-step-filter--set-step-filter-.md) +#### [.suspend_ui (Suspend WinDbg Interface)](-suspend-ui--suspend-windbg-interface-.md) +#### [.symfix (Set Symbol Store Path)](-symfix--set-symbol-store-path-.md) +#### [.symopt (Set Symbol Options)](-symopt--set-symbol-options-.md) +#### [.sympath (Set Symbol Path)](-sympath--set-symbol-path-.md) +#### [.thread (Set Register Context)](-thread--set-register-context-.md) +#### [.time (Display System Time)](-time--display-system-time-.md) +#### [.tlist (List Process IDs)](-tlist--list-process-ids-.md) +#### [.trap (Display Trap Frame)](-trap--display-trap-frame-.md) +#### [.tss (Display Task State Segment)](-tss--display-task-state-segment-.md) +#### [.ttime (Display Thread Times)](-ttime--display-thread-times-.md) +#### [.typeopt (Set Type Options)](-typeopt--set-type-options-.md) +#### [.unload (Unload Extension DLL)](-unload--unload-extension-dll-.md) +#### [.unloadall (Unload All Extension DLLs)](-unloadall--unload-all-extension-dlls-.md) +#### [.urestart (Unregister for Restart)](-urestart--unregister-for-restart-.md) +#### [.wake (Wake Debugger)](-wake--wake-debugger-.md) +#### [.write_cmd_hist (Write Command History)](-write-cmd-hist--write-command-history-.md) +#### [.writemem (Write Memory to File)](-writemem--write-memory-to-file-.md) +#### [.wtitle (Set Window Title)](-wtitle--set-window-title-.md) +### [Control Keys](control-keys.md) +#### [CTRL+\ (Debug Current Debugger)](ctrl--.md) +#### [CTRL+ALT+\ (Debug Current Debugger)](ctrl-alt--.md) +#### [CTRL+A (Toggle Baud Rate)](ctrl-a--toggle-baud-rate-.md) +#### [CTRL+B (Quit Local Debugger)](ctrl-b--quit-local-debugger-.md) +#### [CTRL+C (Break)](ctrl-c--break-.md) +#### [CTRL+D (Toggle Debug Info)](ctrl-d--toggle-debug-info-.md) +#### [CTRL+F (Break to KD)](ctrl-f--break-to-kd-.md) +#### [CTRL+K (Change Post-Reboot Break State)](ctrl-k--change-post-reboot-break-state-.md) +#### [CTRL+P (Debug Current Debugger)](ctrl-p--debug-current-debugger-.md) +#### [CTRL+R (Re-synchronize)](ctrl-r--re-synchronize-.md) +#### [CTRL+V (Toggle Verbose Mode)](ctrl-v--toggle-verbose-mode-.md) +#### [CTRL+W (Show Debugger Version)](ctrl-w--show-debugger-version-.md) +### [General Extension Commands](general-extensions.md) +#### [!acl](-acl.md) +#### [!address](-address.md) +#### [!analyze](-analyze.md) +#### [!asd](-asd.md) +#### [!atom](-atom.md) +#### [!bitcount](-bitcount.md) +#### [!chksym](-chksym.md) +#### [!chkimg](-chkimg.md) +#### [!cppexr](-cppexr.md) +#### [!cpuid](-cpuid.md) +#### [!cs](-cs.md) +#### [!cxr](-cxr.md) +#### [!dh](-dh.md) +#### [!dlls](-dlls.md) +#### [!dml_proc](-dml-proc.md) +#### [!dumpfa](-dumpfa.md) +#### [!elog_str](-elog-str.md) +#### [!envvar](-envvar.md) +#### [!error](-error.md) +#### [!exchain](-exchain.md) +#### [!exr](-exr.md) +#### [!findxmldata](-findxmldata.md) +#### [!for_each_frame](-for-each-frame.md) +#### [!for_each_function](-for-each-function.md) +#### [!for_each_local](-for-each-local.md) +#### [!for_each_module](-for-each-module.md) +#### [!for_each_register](-for-each-register.md) +#### [!gflag](-gflag.md) +#### [!gle](-gle.md) +#### [!gs](-gs.md) +#### [!handle](-handle.md) +#### [!heap](-heap.md) +#### [!help](-help.md) +#### [!homedir](-homedir.md) +#### [!hstring](-hstring.md) +#### [!hstring2](-hstring2.md) +#### [!htrace](-htrace.md) +#### [!imggp](-imggp.md) +#### [!imgreloc](-imgreloc.md) +#### [!kuser](-kuser.md) +#### [!list](-list.md) +#### [!lmi](-lmi.md) +#### [!mui](-mui.md) +#### [!net_send](-net-send.md) +#### [!obja](-obja.md) +#### [!owner](-owner.md) +#### [!peb](-peb.md) +#### [!rebase](-rebase.md) +#### [!rtlavl](-rtlavl.md) +#### [!sd](-sd.md) +#### [!sid](-sid.md) +#### [!slist](-slist.md) +#### [!std_map](-std-map.md) +#### [!stl](-stl.md) +#### [!str](-str.md) +#### [!sym](-sym.md) +#### [!symsrv](-symsrv.md) +#### [!teb](-teb.md) +#### [!tls](-tls.md) +#### [!token](-token.md) +#### [!tp](-tp.md) +#### [!triage](-triage.md) +#### [!ustr](-ustr.md) +#### [!version](-version.md) +#### [!winrterr](-winrterr.md) +### [Kernel-Mode Extension Commands](kernel-mode-extensions.md) +#### [!ahcache](-ahcache.md) +#### [!alignmentfaults](-alignmentfaults.md) +#### [!analyzebugcheck](-analyzebugcheck.md) +#### [!apc](-apc.md) +#### [!apicerr](-apicerr.md) +#### [!arbinst](-arbinst.md) +#### [!arbiter](-arbiter.md) +#### [!ate](-ate.md) +#### [!bcb](-bcb.md) +#### [!blockeddrv](-blockeddrv.md) +#### [!bpid](-bpid.md) +#### [!btb](-btb.md) +#### [!bth](-bth.md) +#### [!bugdump](-bugdump.md) +#### [!bushnd](-bushnd.md) +#### [!ca](-ca.md) +#### [!callback](-callback.md) +#### [!calldata](-calldata.md) +#### [!can_write_kdump](-can-write-kdump.md) +#### [!cbreg](-cbreg.md) +#### [!cchelp](-cchelp.md) +#### [!chklowmem](-chklowmem.md) +#### [!cmreslist](-cmreslist.md) +#### [!cpuinfo](-cpuinfo.md) +#### [!db, !dc, !dd, !dp, !dq, !du, !dw](-db---dc---dd---dp---dq---du---dw.md) +#### [!dbgprint](-dbgprint.md) +#### [!dblink](-dblink.md) +#### [!dcr](-dcr.md) +#### [!dcs](-dcs.md) +#### [!deadlock](-deadlock.md) +#### [!defwrites](-defwrites.md) +#### [!devext](-devext.md) +#### [!devhandles](-devhandles.md) +#### [!devnode](-devnode.md) +#### [!devobj](-devobj.md) +#### [!devstack](-devstack.md) +#### [!dflink](-dflink.md) +#### [!diskspace](-diskspace.md) +#### [!dma](-dma.md) +#### [!dpa](-dpa.md) +#### [!dpcs](-dpcs.md) +#### [!driveinfo](-driveinfo.md) +#### [!drivers](-drivers.md) +#### [!drvobj](-drvobj.md) +#### [!dskheap](-dskheap.md) +#### [!eb, !ed](-eb---ed.md) +#### [!ecb, !ecd, !ecw](-ecb---ecd---ecw.md) +#### [!ecs](-ecs.md) +#### [!errlog](-errlog.md) +#### [!errpkt](-errpkt.md) +#### [!errrec](-errrec.md) +#### [!exca](-exca.md) +#### [!filecache](-filecache.md) +#### [!filelock](-filelock.md) +#### [!fileobj](-fileobj.md) +#### [!filetime](-filetime.md) +#### [!finddata](-finddata.md) +#### [!findfilelockowner](-findfilelockowner.md) +#### [!findthreads](-findthreads.md) +#### [!for_each_process](-for-each-process.md) +#### [!for_each_thread](-for-each-thread.md) +#### [!fpsearch](-fpsearch.md) +#### [!frozen](-frozen.md) +#### [!fwver](-fwver.md) +#### [!fxdevice](-fxdevice.md) +#### [!gbl](-gbl.md) +#### [!gentable](-gentable.md) +#### [!hidppd](-hidppd.md) +#### [!ib, !id, !iw](-ib---id---iw.md) +#### [!icpleak](-icpleak.md) +#### [!idt](-idt.md) +#### [!ih](-ih.md) +#### [!ihs](-ihs.md) +#### [!ioresdes](-ioresdes.md) +#### [!ioctldecode](-ioctldecode.md) +#### [!ioreslist](-ioreslist.md) +#### [!iovirp](-iovirp.md) +#### [!ipi](-ipi.md) +#### [!irp](-irp.md) +#### [!irpfind](-irpfind.md) +#### [!irpzone](-irpzone.md) +#### [!irql](-irql.md) +#### [!isainfo](-isainfo.md) +#### [!isr](-isr.md) +#### [!ivt](-ivt.md) +#### [!job](-job.md) +#### [!kb, !kv](-kb---kv.md) +#### [!loadermemorylist](-loadermemorylist.md) +#### [!lockedpages](-lockedpages.md) +#### [!locks (!kdext*.locks)](-locks---kdext--locks-.md) +#### [!logonsession](-logonsession.md) +#### [!lookaside](-lookaside.md) +#### [!lpc](-lpc.md) +#### [!mca](-mca.md) +#### [!memlist](-memlist.md) +#### [!memusage](-memusage.md) +#### [!mps](-mps.md) +#### [!mtrr](-mtrr.md) +#### [!npx](-npx.md) +#### [!ob, !od, !ow](-ob---od---ow.md) +#### [!object](-object.md) +#### [!obtrace](-obtrace.md) +#### [!openmaps](-openmaps.md) +#### [!pars](-pars.md) +#### [!pat](-pat.md) +#### [!pci](-pci.md) +#### [!pciir](-pciir.md) +#### [!pcitree](-pcitree.md) +#### [!pcm](-pcm.md) +#### [!pcr](-pcr.md) +#### [!pcrs](-pcrs.md) +#### [!pfn](-pfn.md) +#### [!pmc](-pmc.md) +#### [!pmssa](-pmssa.md) +#### [!powertriage](-powertriage.md) +#### [!pnpevent](-pnpevent.md) +#### [!pocaps](-pocaps.md) +#### [!pool](-pool.md) +#### [!poolfind](-poolfind.md) +#### [!poolused](-poolused.md) +#### [!poolval](-poolval.md) +#### [!popolicy](-popolicy.md) +#### [!pplookaside](-pplookaside.md) +#### [!ppmidle](-ppmidle.md) +#### [!ppmidleaccounting](-ppmidleaccounting.md) +#### [!ppmidlepolicy](-ppmidlepolicy.md) +#### [!ppmlpscenarios](-ppmlpscenarios.md) +#### [!ppmperf](-ppmperf.md) +#### [!ppmperfpolicy](-ppmperfpolicy.md) +#### [!ppmsettings](-ppmstate.md) +#### [!ppmstate](-ppmstate.md) +#### [!prcb](-prcb.md) +#### [!process](-process.md) +#### [!processfields](-processfields.md) +#### [!processirps](-processirps.md) +#### [!psp](-psp.md) +#### [!pte](-pte.md) +#### [!pte2va](-pte2va.md) +#### [!ptov](-ptov.md) +#### [!qlocks](-qlocks.md) +#### [!ready](-ready.md) +#### [!reg](-reg.md) +#### [!regkcb](-regkcb.md) +#### [!rellist](-rellist.md) +#### [!ruleinfo](-ruleinfo.md) +#### [!running](-running.md) +#### [!scm](-scm.md) +#### [!search](-search.md) +#### [!searchpte](-searchpte.md) +#### [!sel](-sel.md) +#### [!session](-session.md) +#### [!smt](-smt.md) +#### [!sprocess](-sprocess.md) +#### [!srb](-srb.md) +#### [!stacks](-stacks.md) +#### [!swd](-swd.md) +#### [!sysinfo](-sysinfo.md) +#### [!sysptes](-sysptes.md) +#### [!thread](-thread.md) +#### [!threadfields](-threadfields.md) +#### [!time](-time.md) +#### [!timer](-timer.md) +#### [!tokenfields](-tokenfields.md) +#### [!trap](-trap.md) +#### [!tss](-tss.md) +#### [!tz](-tz.md) +#### [!tzinfo](-tzinfo.md) +#### [!ubc](-ubc.md) +#### [!ubd](-ubd.md) +#### [!ube](-ube.md) +#### [!ubl](-ubl.md) +#### [!ubp](-ubp.md) +#### [!urb](-urb.md) +#### [!vad](-vad.md) +#### [!vad_reload](-vad-reload.md) +#### [!validatelist](-validatelist.md) +#### [!verifier](-verifier.md) +#### [!vm](-vm.md) +#### [!vpb](-vpb.md) +#### [!vpdd](-vpdd.md) +#### [!vtop](-vtop.md) +#### [!wdmaud](-wdmaud.md) +#### [!whattime](-whattime.md) +#### [!whatperftime](-whatperftime.md) +#### [!whea](-whea.md) +#### [!wsle](-wsle.md) +#### [!zombies](-zombies.md) +### [User-Mode Extension Commands](user-mode-extensions.md) +#### [!avrf](-avrf.md) +#### [!critsec](-critsec.md) +#### [!dp (!ntsdexts.dp)](-dp---ntsdexts-dp-.md) +#### [!dreg](-dreg.md) +#### [!dt](-dt.md) +#### [!evlog](-evlog.md) +#### [!findstack](-findstack.md) +#### [!gatom](-gatom.md) +#### [!igrep](-igrep.md) +#### [!locks (!ntsdexts.locks)](-locks---ntsdexts-locks-.md) +#### [!mapped_file](-mapped-file.md) +#### [!runaway](-runaway.md) +#### [!threadtoken](-threadtoken.md) +#### [!uniqstack](-uniqstack.md) +#### [!vadump](-vadump.md) +#### [!vprot](-vprot.md) +### [Specialized Extension Commands](specialized-extensions.md) +#### [Storage Kernel Debugger Extensions](storage-kernel-debugger-extensions.md) +##### [!storagekd.storadapter](-storagekd-storadapter.md) +##### [!storagekd.storclass](-storagekd-storclass.md) +##### [!storagekd.storhelp](-storagekd-storhelp.md) +##### [!storagekd.storlogirp](-storagekd-storlogirp.md) +##### [!storagekd.storloglist](-storagekd-storloglist.md) +##### [!storagekd.storlogsrb](-storagekd-storlogsrb.md) +##### [!storagekd.storsrb](-storagekd-storsrb.md) +##### [!storagekd.storunit](-storagekd-storunit.md) +#### [Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) +##### [!bthkd.bthdevinfo](-bthkd-bthdevinfo.md) +##### [!bthkd.bthenuminfo](-bthkd-bthenuminfo.md) +##### [!bthkd.bthinfo](-bthkd-bthinfo-.md) +##### [!bthkd.bthhelp](-bthkd-bthhelp.md) +##### [!bthkd.bthtree](-bthkd-bthtree.md) +##### [!bthkd.bthusbtransfer](-bthkd-bthusbtransfer.md) +##### [!bthkd.dibflags](-bthkd-dibflags.md) +##### [!bthkd.hcicmd](-bthkd-hcicmd.md) +##### [!bthkd.hciinterface](-bthkd-hciinterface.md) +##### [!bthkd.l2capinterface](-bthkd-l2capinterface-.md) +##### [!bthkd.rfcomminfo](-bthkd-rfcomminfo.md) +##### [!bthkd.rfcommconnection](-bthkd-rfcommconnection.md) +##### [!bthkd.rfcommchannel](-bthkd-rfcommchannel.md) +##### [!bthkd.sdpinterface](-bthkd-sdpinterface.md) +##### [!bthkd.scointerface](-bthkd-scointerface-.md) +##### [!bthkd.sdpnode](-bthkd-sdpnode.md) +##### [!bthkd.sdpstream](-bthkd-sdpstream.md) +#### [GPIO Extensions](gpio-extensions.md) +##### [!gpiokd.help](-gpiokd-help.md) +##### [!gpiokd.bankinfo](-gpiokd-bankinfo.md) +##### [!gpiokd.clientlist](-gpiokd-clientlist.md) +##### [!gpiokd.gpioext](-gpiokd-gpioext.md) +##### [!gpiokd.pininfo](-gpiokd-pininfo.md) +##### [!gpiokd.pinisrvec](-gpiokd-pinisrvec.md) +##### [!gpiokd.pintable](-gpiokd-pintable.md) +#### [USB 3.0 Extensions](usb-3-extensions.md) +##### [USB 3.0 Data Structures](usb-3-0-data-structures.md) +##### [!usb3kd.help](-usb3kd-help.md) +##### [!usb3kd.device_info](-usb3kd-device-info.md) +##### [!usb3kd.device_info_from_pdo](-usb3kd-device-info-from-pdo.md) +##### [!usb3kd.dsf](-usb3kd-dsf.md) +##### [!usb3kd.hub_info](-usb3kd-hub-info.md) +##### [!usb3kd.hub_info_from_fdo](-usb3kd-hub-info-from-fdo.md) +##### [!usb3kd.port_info](-usb3kd-port-info.md) +##### [!usb3kd.ucx_device](-usb3kd-ucx-device.md) +##### [!usb3kd.ucx_endpoint](-usb3kd-ucx-endpoint.md) +##### [!usb3kd.ucx_controller](-usb3kd-ucx-controller.md) +##### [!usb3kd.ucx_controller_list](-usb3kd-ucx-controller-list.md) +##### [!usb3kd.usbanalyze](-usb3kd-usbanalyze.md) +##### [!usb3kd.usbdstatus](-usb3kd-usbdstatus.md) +##### [!usb3kd.usb_tree](-usb3kd-usb-tree.md) +##### [!usb3kd.urb](-usb3kd-urb.md) +##### [!usb3kd.xhci_capability](-usb3kd-xhci-capability.md) +##### [!usb3kd.xhci_commandring](-usb3kd-xhci-commandring.md) +##### [!usb3kd.xhci_deviceslots](-usb3kd-xhci-deviceslots.md) +##### [!usb3kd.xhci_dumpall](-usb3kd-xhci-dumpall.md) +##### [!usb3kd.xhci_eventring](-usb3kd-xhci-eventring.md) +##### [!xhci_findowner](-xhci-findowner.md) +##### [!usb3kd.xhci_info](-usb3kd-xhci-info.md) +##### [!usb3kd.xhci_registers](-usb3kd-xhci-registers.md) +##### [!usb3kd.xhci_resourceusage](-usb3kd-xhci-resourceusage.md) +##### [!usb3kd.xhci_trb](-usb3kd-xhci-trb.md) +##### [!usb3kd.xhci_transferring](-usb3kd-xhci-transferring.md) +#### [USB 2.0 Debugger Extensions](usb-2-0-extensions.md) +##### [!usbkd.usbhelp](-usbkd-usbhelp.md) +##### [!usbkd._ehcidd](-usbkd--ehcidd.md) +##### [!usbkd._ehciep](-usbkd--ehciep.md) +##### [!usbkd._ehciframe](-usbkd--ehciframe.md) +##### [!usbkd._ehciqh](-usbkd--ehciqh.md) +##### [!usbkd._ehciregs](-usbkd--ehciregs.md) +##### [!usbkd._ehcisitd](-usbkd--ehcisitd.md) +##### [!usbkd._ehcistq](-usbkd--ehcistq.md) +##### [!usbkd._ehcitd](-usbkd--ehcitd.md) +##### [!usbkd._ehcitfer](-usbkd--ehcitfer.md) +##### [!usbkd._ehciitd](-usbkd--ehciitd.md) +##### [!usbkd.doesdumphaveusbdata](-usbkd-doesdumphaveusbdata.md) +##### [!usbkd.isthisdumpasyncissue](-usbkd-isthisdumpasyncissue.md) +##### [!usbkd.urbfunc](-usbkd-urbfunc.md) +##### [!usbkd.usb2](-usbkd-usb2.md) +##### [!usbkd.usb2tree](-usbkd-usb2tree.md) +##### [!usbkd.usbchain](-usbkd-usbchain.md) +##### [!usbkd.usbdevobj](-usbkd-usbdevobj.md) +##### [!usbkd.usbdpc](-usbkd-usbdpc.md) +##### [!usbkd.ehci_info_from_fdo](-usbkd-ehci-info-from-fdo.md) +##### [!usbkd.usbdevh](-usbkd-usbdevh.md) +##### [!usbkd.usbep](-usbkd-usbep.md) +##### [!usbkd.usbfaildata](-usbkd-usbfaildata.md) +##### [!usbkd.usbhcdext](-usbkd-usbhcdext.md) +##### [!usbkd.usbdstatus](-usbkd-usbdstatus.md) +##### [!usbkd.usbhcdhccontext](-usbkd-usbhcdhccontext.md) +##### [!usbkd.usbhcdlist](-usbkd-usbhcdlist.md) +##### [!usbkd.usbhcdlistlogs](-usbkd-usbhcdlistlogs.md) +##### [!usbkd.usbhcdlog](-usbkd-usbhcdlog.md) +##### [!usbkd.usbhcdlogex](-usbkd-usbhcdlogex.md) +##### [!usbkd.usbhcdpnp](-usbkd-usbhcdpnp.md) +##### [!usbkd.usbhcdpow](-usbkd-usbhcdpow.md) +##### [!usbkd.hub2_info_from_fdo](-usbkd-hub2-info-from-fdo.md) +##### [!usbkd.usbhuberr](-usbkd-usbhuberr.md) +##### [!usbkd.usbhubext](-usbkd-usbhubext.md) +##### [!usbkd.usbhubinfo](-usbkd-usbhubinfo.md) +##### [!usbkd.usbhublog](-usbkd-usbhublog.md) +##### [!usbkd.usbhubmddevext](-usbkd-usbhubmddevext.md) +##### [!usbkd.usbhubmdpd](-usbkd-usbhubmdpd.md) +##### [!usbkd.usbhubpd](-usbkd-usbhubpd.md) +##### [!usbkd.usbhubs](-usbkd-usbhubs.md) +##### [!usbkd.usblist](-usbkd-usblist.md) +##### [!usbkd.usbpo](-usbkd-usbpo.md) +##### [!usbkd.usbpdos](-usbkd-usbpdos.md) +##### [!usbkd.usbpdoxls](-usbkd-usbpdoxls.md) +##### [!usbkd.usbpnp](-usbkd-usbpnp.md) +##### [!usbkd.usbportisasyncadv](-usbkd-usbportisasyncadv.md) +##### [!usbkd.usbportmdportlog](-usbkd-usbportmdportlog.md) +##### [!usbkd.usbportmddcontext](-usbkd-usbportmddcontext.md) +##### [!usbkd.usbportmddevext](-usbkd-usbportmddevext.md) +##### [!usbkd.usbtriage](-usbkd-usbtriage.md) +##### [!usbkd.usbtt](-usbkd-usbtt.md) +##### [!usbkd.usbtx](-usbkd-usbtx.md) +##### [!usbkd.usbusb2ep](-usbkd-usbusb2ep.md) +##### [!usbkd.usbusb2tt](-usbkd-usbusb2tt.md) +##### [!usbkd.usbver](-usbkd-usbver.md) +#### [RCDRKD Extensions](rcdrkd-extensions.md) +##### [!rcdrkd.rcdrhelp](-rcdrkd-rcdrhelp.md) +##### [!rcdrkd.rcdrcrashdump](-rcdrkd-rcdrcrashdump.md) +##### [!rcdrkd.rcdrlogdump](-rcdrkd-rcdrlogdump.md) +##### [!rcdrkd.rcdrloglist](-rcdrkd-rcdrloglist.md) +##### [!rcdrkd.rcdrlogsave](-rcdrkd-rcdrlogsave.md) +##### [!rcdrkd.rcdrsearchpath](-rcdrkd-rcdrsearchpath.md) +##### [!rcdrkd.rcdrsettraceprefix](-rcdrkd-rcdrsettraceprefix.md) +##### [!rcdrkd.rcdrtmffile](-rcdrkd-rcdrtmffile.md) +##### [!rcdrkd.rcdrtraceprtdebug](-rcdrkd-rcdrtraceprtdebug.md) +#### [HID Extensions](hid-extensions.md) +##### [!hidkd.help](-hidkd-help.md) +##### [!hidkd.hidfdo](-hidkd-hidfdo.md) +##### [!hidkd.hidpdo](-hidkd-hidpdo.md) +##### [!hidkd.hidtree](-hidkd-hidtree.md) +##### [!hidkd.hidppd](-hidkd-hidppd.md) +##### [!hidkd.hidrd](-hidkd-hidrd.md) +#### [Logger Extensions (Logexts.dll)](logger-extensions--logexts-dll-.md) +##### [!logexts.help](-logexts-help.md) +##### [!logexts.logb](-logexts-logb.md) +##### [!logexts.logc](-logexts-logc.md) +##### [!logexts.logd](-logexts-logd.md) +##### [!logexts.loge](-logexts-loge.md) +##### [!logexts.logi](-logexts-logi.md) +##### [!logexts.logm](-logexts-logm.md) +##### [!logexts.logo](-logexts-logo.md) +#### [NDIS Extensions (Ndiskd.dll)](ndis-extensions--ndiskd-dll-.md) +##### [!ndiskd.help](-ndiskd-help.md) +##### [!ndiskd.netadapter](-ndiskd-netadapter.md) +##### [!ndiskd.minidriver](-ndiskd-minidriver.md) +##### [!ndiskd.rcvqueue](-ndiskd-rcvqueue.md) +##### [!ndiskd.protocol](-ndiskd-protocol.md) +##### [!ndiskd.mopen](-ndiskd-mopen.md) +##### [!ndiskd.filter](-ndiskd-filter.md) +##### [!ndiskd.filterdriver](-ndiskd-filterdriver.md) +##### [!ndiskd.nbl](-ndiskd-nbl.md) +##### [!ndiskd.nb](-ndiskd-nb.md) +##### [!ndiskd.nblpool](-ndiskd-nblpool.md) +##### [!ndiskd.nbpool](-ndiskd-nbpool.md) +##### [!ndiskd.pendingnbls](-ndiskd-pendingnbls.md) +##### [!ndiskd.nbllog](-ndiskd-nbllog.md) +##### [!ndiskd.cxadapter](-ndiskd-cxadapter.md) +##### [!ndiskd.netqueue](-ndiskd-netqueue.md) +##### [!ndiskd.netrb](-ndiskd-netrb.md) +##### [!ndiskd.netpacket](-ndiskd-netpacket.md) +##### [!ndiskd.netpacketfragment](-ndiskd-netpacketfragment.md) +##### [!ndiskd.oid](-ndiskd-oid.md) +##### [!ndiskd.interfaces](-ndiskd-interfaces.md) +##### [!ndiskd.ifprovider](-ndiskd-ifprovider.md) +##### [!ndiskd.ifstacktable](-ndiskd-ifstacktable.md) +##### [!ndiskd.compartments](-ndiskd-compartments.md) +##### [!ndiskd.pkt](-ndiskd-pkt.md) +##### [!ndiskd.pktpools](-ndiskd-pktpools.md) +##### [!ndiskd.findpacket](-ndiskd-findpacket.md) +##### [!ndiskd.vc](-ndiskd-vc.md) +##### [!ndiskd.af](-ndiskd-af.md) +##### [!ndiskd.ndisref](-ndiskd-ndisref.md) +##### [!ndiskd.ndisevent](-ndiskd-ndisevent.md) +##### [!ndiskd.ndisstack](-ndiskd-ndisstack.md) +##### [!ndiskd.wdiadapter](-ndiskd-wdiadapter.md) +##### [!ndiskd.wdiminidriver](-ndiskd-wdiminidriver.md) +##### [!ndiskd.nwadapter](-ndiskd-nwadapter.md) +##### [!ndiskd.ndisrwlock](-ndiskd-ndisrwlock.md) +##### [!ndiskd.ndisslot](-ndiskd-ndisslot.md) +##### [!ndiskd.ndis](-ndiskd-ndis.md) +##### [!ndiskd.dbglevel](-ndiskd-dbglevel.md) +##### [!ndiskd.dbgsystems](-ndiskd-dbgsystems.md) +##### [!ndiskd.ndiskdversion](-ndiskd-ndiskdversion.md) +##### [!ndiskd.netreport](-ndiskd-netreport.md) +#### [RPC Extensions (Rpcexts.dll)](rpc-extensions--rpcexts-dll-.md) +##### [!rpcexts.checkrpcsym](-rpcexts-checkrpcsym.md) +##### [!rpcexts.eeinfo](-rpcexts-eeinfo.md) +##### [!rpcexts.eerecord](-rpcexts-eerecord.md) +##### [!rpcexts.getcallinfo](-rpcexts-getcallinfo.md) +##### [!rpcexts.getclientcallinfo](-rpcexts-getclientcallinfo.md) +##### [!rpcexts.getdbgcell](-rpcexts-getdbgcell.md) +##### [!rpcexts.getendpointinfo](-rpcexts-getendpointinfo.md) +##### [!rpcexts.getthreadinfo](-rpcexts-getthreadinfo.md) +##### [!rpcexts.help](-rpcexts-help.md) +##### [!rpcexts.rpcreadstack](-rpcexts-rpcreadstack.md) +##### [!rpcexts.rpctime](-rpcexts-rpctime.md) +##### [!rpcexts.thread](-rpcexts-thread.md) +#### [ACPI Extensions (Acpikd.dll and Kdexts.dll)](acpi-extensions--acpikd-dll-and-kdexts-dll-.md) +##### [!acpicache](-acpicache.md) +##### [!acpiinf](-acpiinf.md) +##### [!acpiirqarb](-acpiirqarb.md) +##### [!acpikd.help](-acpikd-help.md) +##### [!amli ?](-amli--.md) +##### [!amli bc](-amli-bc.md) +##### [!amli bd](-amli-bd.md) +##### [!amli be](-amli-be.md) +##### [!amli bl](-amli-bl.md) +##### [!amli bp](-amli-bp.md) +##### [!amli cl](-amli-cl.md) +##### [!amli debugger](-amli-debugger.md) +##### [!amli dh](-amli-dh.md) +##### [!amli dl](-amli-dl.md) +##### [!amli dns](-amli-dns.md) +##### [!amli do](-amli-do.md) +##### [!amli ds](-amli-ds.md) +##### [!amli find](-amli-find.md) +##### [!amli lc](-amli-lc.md) +##### [!amli ln](-amli-ln.md) +##### [!amli r](-amli-r.md) +##### [!amli set](-amli-set.md) +##### [!amli u](-amli-u.md) +##### [!facs](-facs.md) +##### [!fadt](-fadt.md) +##### [!mapic](-mapic.md) +##### [!nsobj](-nsobj.md) +##### [!nstree](-nstree.md) +##### [!rsdt](-rsdt.md) +#### [Graphics Driver Extensions (Gdikdx.dll)](graphics-driver-extensions--gdikdx-dll-.md) +##### [!gdikdx.verifier](-gdikdx-verifier.md) +#### [Kernel Streaming Extensions (Ks.dll)](kernel-streaming-extensions--ks-dll-.md) +##### [!ks.help](-ks-help.md) +##### [!ks.kshelp](-ks-kshelp.md) +##### [!ks.pchelp](-ks-pchelp.md) +##### [!ks.allstreams](-ks-allstreams.md) +##### [!ks.automation](-ks-automation.md) +##### [!ks.devhdr](-ks-devhdr.md) +##### [!ks.dhdr](-ks-dhdr.md) +##### [!ks.dump](-ks-dump.md) +##### [!ks.dumpbag](-ks-dumpbag.md) +##### [!ks.dumpcircuit](-ks-dumpcircuit.md) +##### [!ks.dumplog](-ks-dumplog.md) +##### [!ks.dumpqueue](-ks-dumpqueue.md) +##### [!ks.enumdevobj](-ks-enumdevobj.md) +##### [!ks.enumdrvobj](-ks-enumdrvobj.md) +##### [!ks.eval](-ks-eval.md) +##### [!ks.findlive](-ks-findlive.md) +##### [!ks.forcedump](-ks-forcedump.md) +##### [!ks.graph](-ks-graph.md) +##### [!ks.libexts](-ks-libexts.md) +##### [!ks.objhdr](-ks-objhdr.md) +##### [!ks.ohdr](-ks-ohdr.md) +##### [!ks.pciaudio](-ks-pciaudio.md) +##### [!ks.pciks](-ks-pciks.md) +##### [!ks.shdr](-ks-shdr.md) +##### [!ks.topology](-ks-topology.md) +#### [SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll)](scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md) +##### [!scsikd.help](-scsikd-help.md) +##### [!scsikd.classext](-scsikd-classext.md) +##### [!scsikd.scsiext](-scsikd-scsiext.md) +##### [!scsikd.srbdata](-scsikd-srbdata.md) +##### [!minipkd.help](-minipkd-help.md) +##### [!minipkd.adapter](-minipkd-adapter.md) +##### [!minipkd.adapters](-minipkd-adapters.md) +##### [!minipkd.exports](-minipkd-exports.md) +##### [!minipkd.lun](-minipkd-lun.md) +##### [!minipkd.portconfig](-minipkd-portconfig.md) +##### [!minipkd.req](-minipkd-req.md) +##### [!minipkd.srb](-minipkd-srb.md) +#### [Windows Driver Framework Extensions (Wdfkd.dll)](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) +##### [!wdfkd.help](-wdfkd-help.md) +##### [!wdfkd.wdfchildlist](-wdfkd-wdfchildlist.md) +##### [!wdfkd.wdfcollection](-wdfkd-wdfcollection.md) +##### [!wdfkd.wdfcommonbuffer](-wdfkd-wdfcommonbuffer.md) +##### [!wdfkd.wdfcrashdump](-wdfkd-wdfcrashdump.md) +##### [!wdfkd.wdfdevext](-wdfkd-wdfdevext.md) +##### [!wdfkd.wdfdevice](-wdfkd-wdfdevice.md) +##### [!wdfkd.wdfdeviceinterrupts](-wdfkd-wdfdeviceinterrupts.md) +##### [!wdfkd.wdfdevicequeues](-wdfkd-wdfdevicequeues.md) +##### [!wdfkd.wdfdmaenabler](-wdfkd-wdfdmaenabler.md) +##### [!wdfkd.wdfdmaenablers](-wdfkd-wdfdmaenablers.md) +##### [!wdfkd.wdfdmatransaction](-wdfkd-wdfdmatransaction.md) +##### [!wdfkd.wdfdriverinfo](-wdfkd-wdfdriverinfo.md) +##### [!wdfkd.wdfextendwatchdog](-wdfkd-wdfextendwatchdog.md) +##### [!wdfkd.wdffindobjects](-wdfkd-wdffindobjects.md) +##### [!wdfkd.wdfforwardprogress](-wdfkd-wdfforwardprogress.md) +##### [!wdfkd.wdfgetdriver](-wdfkd-wdfgetdriver.md) +##### [!wdfkd.wdfhandle](-wdfkd-wdfhandle.md) +##### [!wdfkd.wdfhelp](-wdfkd-wdfhelp.md) +##### [!wdfkd.wdfinterrupt](-wdfkd-wdfinterrupt.md) +##### [!wdfkd.wdfiotarget](-wdfkd-wdfiotarget.md) +##### [!wdfkd.wdfldr](-wdfkd-wdfldr.md) +##### [!wdfkd.wdflogdump](-wdfkd-wdflogdump.md) +##### [!wdfkd.wdflogsave](-wdfkd-wdflogsave.md) +##### [!wdfkd.wdfmemory](-wdfkd-wdfmemory.md) +##### [!wdfkd.wdfobject](-wdfkd-wdfobject.md) +##### [!wdfkd.wdfopenhandles](-wdfkd-wdfopenhandles.md) +##### [!wdfkd.wdfpool](-wdfkd-wdfpool.md) +##### [!wdfkd.wdfpooltracker](-wdfkd-wdfpooltracker.md) +##### [!wdfkd.wdfpoolusage](-wdfkd-wdfpoolusage.md) +##### [!wdfkd.wdfqueue](-wdfkd-wdfqueue.md) +##### [!wdfkd.wdfrequest](-wdfkd-wdfrequest.md) +##### [!wdfkd.wdfsearchpath](-wdfkd-wdfsearchpath.md) +##### [!wdfkd.wdfsettraceprefix](-wdfkd-wdfsettraceprefix.md) +##### [!wdfkd.wdfsetdriver](-wdfkd-wdfsetdriver.md) +##### [!wdfkd.wdfspinlock](-wdfkd-wdfspinlock.md) +##### [!wdfkd.wdftagtracker](-wdfkd-wdftagtracker.md) +##### [!wdfkd.wdftmffile](-wdfkd-wdftmffile.md) +##### [!wdfkd.wdftraceprtdebug](-wdfkd-wdftraceprtdebug.md) +##### [!wdfkd.wdfumdevstack](-wdfkd-wdfumdevstack.md) +##### [!wdfkd.wdfumdevstacks](-wdfkd-wdfumdevstacks.md) +##### [!wdfkd.wdfumdownirp](-wdfkd-wdfumdownirp.md) +##### [!wdfkd.wdfumfile](-wdfkd-wdfumfile.md) +##### [!wdfkd.wdfumirp](-wdfkd-wdfumirp.md) +##### [!wdfkd.wdfumirps](-wdfkd-wdfumirps.md) +##### [!wdfkd_wdfumtriage](-wdfkd-wdfumtriage.md) +##### [!wdfkd.wdfusbdevice](-wdfkd-wdfusbdevice.md) +##### [!wdfkd.wdfusbinterface](-wdfkd-wdfusbinterface.md) +##### [!wdfkd.wdfusbpipe](-wdfkd-wdfusbpipe.md) +##### [!wdfkd.wdfwmi](-wdfkd-wdfwmi.md) +#### [User-Mode Driver Framework Extensions (Wudfext.dll)](user-mode-driver-framework-extensions--wudfext-dll-.md) +##### [!wudfext.help](-wudfext-help.md) +##### [!wudfext.umdevstack](-wudfext-umdevstack.md) +##### [!wudfext.umdevstacks](-wudfext-umdevstacks.md) +##### [!wudfext.umfile](-wudfext-umfile.md) +##### [!wudfext.umirp](-wudfext-umirp.md) +##### [!wudfext.umirps](-wudfext-umirps.md) +##### [!wudfext.wudfdevice](-wudfext-wudfdevice.md) +##### [!wudfext.wudfdevicequeues](-wudfext-wudfdevicequeues.md) +##### [!wudfext.wudfdownkmirp](-wudfext-wudfdownkmirp.md) +##### [!wudfext.wudfdriverinfo](-wudfext-wudfdriverinfo.md) +##### [!wudfext.wudfdumpobjects](-wudfext-wudfdumpobjects.md) +##### [!wudfext.wudffile](-wudfext-wudffile.md) +##### [!wudfext.wudffilehandletarget](-wudfext-wudffilehandletarget.md) +##### [!wudfext.wudfiotarget](-wudfext-wudfiotarget.md) +##### [!wudfext.wudfobject](-wudfext-wudfobject.md) +##### [!wudfext.wudfqueue](-wudfext-wudfqueue.md) +##### [!wudfext.wudfrefhist](-wudfext-wudfrefhist.md) +##### [!wudfext.wudfrequest](-wudfext-wudfrequest.md) +##### [!wudfext.wudfusbinterface](-wudfext-wudfusbinterface.md) +##### [!wudfext.wudfusbpipe](-wudfext-wudfusbpipe.md) +##### [!wudfext.wudfusbtarget](-wudfext-wudfusbtarget.md) +#### [WMI Tracing Extensions (Wmitrace.dll)](wmi-tracing-extensions--wmitrace-dll-.md) +##### [!wmitrace.disable](-wmitrace-disable.md) +##### [!wmitrace.dumpmini](-wmitrace-dumpmini.md) +##### [!wmitrace.dumpminievent](-wmitrace-dumpminievent.md) +##### [!wmitrace.dynamicprint](-wmitrace-dynamicprint.md) +##### [!wmitrace.enable](-wmitrace-enable.md) +##### [!wmitrace.eventlogdump](-wmitrace-eventlogdump.md) +##### [!wmitrace.help](-wmitrace-help.md) +##### [!wmitrace.logdump](-wmitrace-logdump.md) +##### [!wmitrace.logger](-wmitrace-logger.md) +##### [!wmitrace.logsave](-wmitrace-logsave.md) +##### [!wmitrace.searchpath](-wmitrace-searchpath.md) +##### [!wmitrace.setprefix](-wmitrace-setprefix.md) +##### [!wmitrace.start](-wmitrace-start.md) +##### [!wmitrace.stop](-wmitrace-stop.md) +##### [!wmitrace.strdump](-wmitrace-strdump.md) +##### [!wmitrace.tfp](-wmitrace-tfp.md) +##### [!wmitrace.tmffile](-wmitrace-tmffile.md) +##### [!wmitrace.traceoperation](-wmitrace-traceoperation.md) +#### [OEM Support Extensions (kdex2x86.dll)](oem-support-extensions--kdex2x86-dll-.md) +#### [SieExtPub.dll](sieextpub-dll.md) +## [Debugger-Related APIs](debugger-related-apis.md) +### [Symbol Server API](symbol-server-api.md) +### [The dbgeng.h Header File](the-dbgeng-h-header-file.md) +### [The wdbgexts.h Header File](the-wdbgexts-h-header-file.md) +## [Debugger Error and Warning Messages](debugger-error-and-warning-messages.md) +### [dbgerr001: PEB is Paged Out](dbgerr001--peb-is-paged-out.md) +### [dbgerr002: Bad Pointer](dbgerr002--bad-pointer.md) +### [dbgerr003: Mismatched Symbols](dbgerr003--mismatched-symbols.md) +### [dbgerr004: Page Not Present in Dump File](dbgerr004--page-not-present-in-dump-file.md) +### [dbgerr005: Private Symbols Required](dbgerr005--private-symbols-required.md) +### [Stack Unwind Information Not Available](stack-unwind-information-not-available.md) +### [No Header Information Available](no-header-information-available.md) +## [WinDbg Graphical Interface Features](windbg-graphical-interface-features.md) +### [File Menu](file-menu.md) +#### [File | Open Source File](file---open-source-file.md) +#### [File | Close Current Window](file---close-current-window.md) +#### [File | Open Executable](file---open-executable.md) +#### [File | Attach to a Process](file---attach-to-a-process.md) +#### [File | Open Crash Dump](file---open-crash-dump.md) +#### [File | Connect to Remote Session](file---connect-to-remote-session.md) +#### [File | Connect to Remote Stub](file---connect-to-remote-stub.md) +#### [File | Kernel Debug](file---kernel-debug.md) +#### [File | Symbol File Path](file---symbol-file-path.md) +#### [File | Source File Path](file---source-file-path.md) +#### [File | Image File Path](file---image-file-path.md) +#### [File | Open Workspace](file---open-workspace.md) +#### [File | Save Workspace](file---save-workspace.md) +#### [File | Save Workspace As](file---save-workspace-as.md) +#### [File | Clear Workspace](file---clear-workspace.md) +#### [File | Delete Workspaces](file---delete-workspaces.md) +#### [File | Open Workspace in File](file---open-workspace-in-file.md) +#### [File | Save Workspace to File](file---save-workspace-to-file.md) +#### [File | Map Network Drive](file---map-network-drive.md) +#### [File | Disconnect Network Drive](file---disconnect-network-drive.md) +#### [File | Recent Files](file---recent-files.md) +#### [File | Exit](file---exit.md) +### [Edit Menu](edit-menu.md) +#### [Edit | Cut](edit---cut.md) +#### [Edit | Copy](edit---copy.md) +#### [Edit | Paste](edit---paste.md) +#### [Edit | Select All](edit---select-all.md) +#### [Edit | Write Window Text to File](edit---write-window-text-to-file.md) +#### [Edit | Add to Command Output](edit---add-to-command-output.md) +#### [Edit | Clear Command Output](edit---clear-command-output.md) +#### [Edit | Evaluate Selection](edit---evaluate-selection.md) +#### [Edit | Display Selected Type](edit---display-selected-type.md) +#### [Edit | Find](edit---find.md) +#### [Edit | Find Next](edit---find-next.md) +#### [Edit | Go to Address](edit---go-to-address.md) +#### [Edit | Go to Line](edit---go-to-line.md) +#### [Edit | Go to Current Instruction](edit---go-to-current-instruction.md) +#### [Edit | Set Current Instruction](edit---set-current-instruction.md) +#### [Edit | Breakpoints](edit---breakpoints.md) +#### [Edit | Open/Close Log File](edit---open-close-log-file.md) +### [View Menu](view-menu.md) +#### [View | Command](view---command.md) +#### [View | Watch](view---watch.md) +#### [View | Locals](view---locals.md) +#### [View | Registers](view---registers.md) +#### [View | Memory](view---memory.md) +#### [View | Call Stack](view---call-stack.md) +#### [View | Disassembly](view---disassembly.md) +#### [View | Scratch Pad](view---scratch-pad.md) +#### [View | Processes and Threads](view---processes-and-threads.md) +#### [View | Command Browser](view---command-browser.md) +#### [View | Verbose Output](view---verbose-output.md) +#### [View | Show Version](view---show-version.md) +#### [View | Toolbar](view---toolbar.md) +#### [View | Status Bar](view---status-bar.md) +#### [View | Font](view---font.md) +#### [View | Options](view---options.md) +#### [View | Source language file extensions](view---source-language-file-extensions.md) +#### [View | WinDbg Command Line](view---windbg-command-line.md) +### [Debug Menu](debug-menu.md) +#### [Debug | Go](debug---go.md) +#### [Debug | Go Unhandled Exception](debug---go-unhandled-exception.md) +#### [Debug | Go Handled Exception](debug---go-handled-exception.md) +#### [Debug | Restart](debug---restart.md) +#### [Debug | Stop Debugging](debug---stop-debugging.md) +#### [Debug | Detach Debuggee](debug---detach-debuggee.md) +#### [Debug | Break](debug---break.md) +#### [Debug | Step Into](debug---step-into.md) +#### [Debug | Step Over](debug---step-over.md) +#### [Debug | Step Out](debug---step-out.md) +#### [Debug | Run to Cursor](debug---run-to-cursor.md) +#### [Debug | Source Mode](debug---source-mode.md) +#### [Debug | Resolve Unqualified Symbols](debug---resolve-unqualified-symbols.md) +#### [Debug | Event Filters](debug---event-filters.md) +#### [Debug | Modules](debug---modules.md) +#### [Debug | Kernel Connection | Cycle Baud Rate](debug---kernel-connection---cycle-baud-rate.md) +#### [Debug | Kernel Connection | Cycle Initial Break](debug---kernel-connection---cycle-initial-break.md) +#### [Debug | Kernel Connection | Resynchronize](debug---kernel-connection---resynchronize.md) +### [Window Menu](window-menu.md) +#### [Window | Close All Source Windows](window---close-all-source-windows.md) +#### [Window | Close All Error Windows](window---close-all-error-windows.md) +#### [Window | Open Dock](window---open-dock.md) +#### [Window | Dock All](window---dock-all.md) +#### [Window | Undock All](window---undock-all.md) +#### [Window | MDI Emulation](window---mdi-emulation.md) +#### [Window | Automatically Open Disassembly](window---automatically-open-disassembly.md) +#### [List of Open Windows](list-of-open-windows.md) +### [Help Menu](help-menu.md) +#### [Help | Contents](help---contents.md) +#### [Help | Index](help---index.md) +#### [Help | Search](help---search.md) +#### [Help | About](help---about.md) +### [Toolbar Buttons](toolbar-buttons.md) +### [Keyboard Shortcuts](keyboard-shortcuts.md) + diff --git a/windows-driver-docs-pr/debugger/a--assemble-.md b/windows-driver-docs-pr/debugger/a--assemble-.md new file mode 100644 index 0000000000..3252626ca4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/a--assemble-.md @@ -0,0 +1,80 @@ +--- +title: a (Assemble) +description: The a command assembles 32-bit x86 instruction mnemonics and puts the resulting instruction codes into memory. +ms.assetid: 6736a5fd-5a33-4698-9510-8a95f6a1caf7 +keywords: ["Assemble (a) command", "assembly debugging, Assemble (a) command", "a (Assemble) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- a (Assemble) +api_type: +- NA +--- + +# a (Assemble) + + +The **a** command assembles 32-bit x86 instruction mnemonics and puts the resulting instruction codes into memory. + +``` +a [Address] +``` + +## Parameters + + + *Address* +Specifies the beginning of the block in memory where the resulting codes are put. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +The **a** command does not support 64-bit instruction mnemonics. However, the **a** command is enabled regardless of whether you are debugging a 32-bit target or a 64-bit target. Because of the similarities between x86 and x64 instructions, you can sometimes use the **a** command successfully when debugging a 64-bit target. + +If you do not specify an address, the assembly starts at the address that the current value of the instruction pointer specifies. To assemble a new instruction, type the desired mnemonic and press ENTER. To end assembly, press only ENTER. + +Because the assembler searches for all of the symbols that are referred to in the code, this command might take time to complete. During this time, you cannot press [**CTRL+C**](ctrl-c--break-.md)to end the **a** command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20a%20%28Assemble%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/a.md b/windows-driver-docs-pr/debugger/a.md new file mode 100644 index 0000000000..378356dafa --- /dev/null +++ b/windows-driver-docs-pr/debugger/a.md @@ -0,0 +1,36 @@ +--- +title: A (Windows Debugger Glossary) +description: Glossary page - A +Robots: noindex, nofollow +ms.assetid: ef7fa08b-0eed-4ef9-8b2f-79247e2ad988 +--- + +# A + + +**accessible** +A debugging session is *accessible* if the current target is suspended. + +**actual processor type** +The type of the physical processor in the target computer. + +See also effective processor type, executing processor type. + +For more information, see [Target Information](target-information.md). + +**arbitrary exception filter** +An exception filter that has been manually added to the engine's list of event filters. + +See also [specific exception filter](https://msdn.microsoft.com/library/windows/hardware/ff558784). + +For more information, see [Event Filters](event-filters.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20A%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/accessing-global-variables.md b/windows-driver-docs-pr/debugger/accessing-global-variables.md new file mode 100644 index 0000000000..43a601f53a --- /dev/null +++ b/windows-driver-docs-pr/debugger/accessing-global-variables.md @@ -0,0 +1,65 @@ +--- +title: Accessing Global Variables +description: Accessing Global Variables +ms.assetid: 81daf418-d3cf-413a-8ee0-790b0c0f86c0 +keywords: ["global variables", "global variables, accessing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Global Variables + + +## + + +The names of global variables are stored in the symbol files that are created when an application is compiled. The debugger interprets the name of a global variable as a virtual address. Any command that accepts an address as a parameter also accepts the name of a variable. Therefore, you can use all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) to read or write global variables. + +In addition, you can use the [**? (Evaluate Expression)**](---evaluate-expression-.md) command to display the address that is associated with any symbol. + +Visual Studio and WinDbg provide user interface elements that you can use (in addition to commands) to view and edit global variables. See [Viewing and Editing Memory and Registers in Visual Studio](viewing-memory--variables--and-registers-in-visual-studio.md) and [Viewing and Editing Global Variables in WinDbg](viewing-and-editing-global-variables-in-windbg.md). + +Consider the following example. Suppose that you want to examine the `MyCounter` global variable, which is a 32-bit integer. Also suppose that the default radix is 10. + +You can obtain this variable's address and then display it as follows. + +``` +0:000> ? MyCounter +Evaluate expression: 1244892 = 0012fedc +0:000> dd 0x0012fedc L1 +0012fedc 00000052 +``` + +The first command output tells you that the address of `MyCounter` is 0x0012FEDC. You can then use the [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command to display one double-word at this address. (You could also use 1244892, which is the decimal version of this address. However, most C programmers prefer to use 0x0012FEDC.) The second command tells you that the value of MyCounter is 0x52 (decimal 82). + +You could also perform these steps in the following command. + +``` +0:000> dd MyCounter L1 +0012fedc 00000052 +``` + +To change the value of `MyCounter` to decimal 83, use the following command. + +``` +0:000> ed MyCounter 83 +``` + +This example uses decimal input, because that format seems more natural for an integer. However, the output of the [**d\***](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command is still in hexadecimal format. + +``` +0:000> dd MyCounter L1 0012fedc 00000053 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Accessing%20Global%20Variables%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/accessing-local-variables.md b/windows-driver-docs-pr/debugger/accessing-local-variables.md new file mode 100644 index 0000000000..448f7fadd4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/accessing-local-variables.md @@ -0,0 +1,43 @@ +--- +title: Accessing Local Variables +description: Accessing Local Variables +ms.assetid: 0aab3fdf-fe0c-46ad-aa2f-90992811b001 +keywords: ["local variables, accessing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Local Variables + + +## + + +Local variables, like global variables, are stored in the symbol files. And as with global variables, the debugger interprets their names as addresses. They can be read and written in the same manner as global variables. However, if you need to indicate to a command that a symbol is local, precede the symbol with a dollar sign ( $ ) and an exclamation point ( ! ), as in `$!var`. + +Visual Studio and WinDbg provide user interface elements that you can use (in addition to commands) to view and edit local variables. For more information, see [Viewing and Editing Memory and Registers in Visual Studio](viewing-memory--variables--and-registers-in-visual-studio.md) and [Viewing and Editing Local Variables in WinDbg](locals-window.md). + +You can also use the following methods to display, change, and use local variables: + +- The [**dv (Display Local Variables)**](dv--display-local-variables-.md) command displays the names and values of all local variables. + +- The [**!for\_each\_local**](-for-each-local.md) extension enables you to execute a single command repeatedly, once for each local variable. + +However, there is one primary difference between local and global variables. When an application is executing, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the function in which they are defined. + +The debugger interprets local variables according to the [local context](changing-contexts.md#local-context). By default, this context matches the location of the program counter. But the debugger can change the context. For more information about the local context, see Local Context. + +When the local context is changed, the Locals window is immediately updated to reflect the new collection of local variables. The [**dv**](dv--display-local-variables-.md) command also shows the new variables. All of these variable names are then interpreted correctly by the memory commands that are described earlier. You can then read or write to these variables. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Accessing%20Local%20Variables%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/accessing-memory-by-physical-address.md b/windows-driver-docs-pr/debugger/accessing-memory-by-physical-address.md new file mode 100644 index 0000000000..db66ca47e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/accessing-memory-by-physical-address.md @@ -0,0 +1,39 @@ +--- +title: Accessing Memory by Physical Address +description: Accessing Memory by Physical Address +ms.assetid: 248871dc-dac0-413e-8971-2ee2c2fe5290 +keywords: ["physical address, accessing memory"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Memory by Physical Address + + +## + + +To read from a physical address, use the [**!db**](-db---dc---dd---dp---dq---du---dw.md), **!dc**, **!dd**, **!dp**, **!du**, and **!dw** extension commands. + +To write to a physical address, use the [**!eb**](-eb---ed.md) and **!ed** extension commands. + +The [**fp (Fill Physical Memory)**](f--fp--fill-memory-.md) command writes a pattern to a physical memory range, repeating it until the range is full. + +When you are using WinDbg in kernel mode, you can also read or write to physical memory directly from the [Memory window](memory-window.md). + +To search physical memory for a piece of data or a range of data, use the [**!search**](-search.md) extension command. + +Also, for more information about physical addresses, see [Converting Virtual Addresses to Physical Addresses](converting-virtual-addresses-to-physical-addresses.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Accessing%20Memory%20by%20Physical%20Address%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/accessing-memory-by-virtual-address.md b/windows-driver-docs-pr/debugger/accessing-memory-by-virtual-address.md new file mode 100644 index 0000000000..46091f2324 --- /dev/null +++ b/windows-driver-docs-pr/debugger/accessing-memory-by-virtual-address.md @@ -0,0 +1,65 @@ +--- +title: Accessing Memory by Virtual Address +description: Accessing Memory by Virtual Address +ms.assetid: 13e97cba-c4a4-4240-99b3-88a7537b0ca8 +keywords: ["virtual address, accessing memory"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Memory by Virtual Address + + +## + + +To access memory addresses or address ranges, you can use several commands. Visual Studio and WinDbg provide user interface elements (as well as commands) that you can use to view and edit memory. For more information, see [Viewing and Editing Memory and Registers in Visual Studio](viewing-memory--variables--and-registers-in-visual-studio.md) and [Viewing and Editing Memory in WinDbg](memory-window.md). + +The following commands can read or write memory in a variety of formats. These formats include hexadecimal bytes, words (words, double words, and quad-words), integers (short, long, and quad integers and unsigned integers), floating-point numbers (10-byte, 16-byte, 32-byte, and 64-byte real numbers), and ASCII characters. + +- The [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command displays the contents of a specified memory address or range. + +- The [**e\* (Enter Values)**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) command writes a value to the specified memory address. + +You can use the following commands to handle more specialized data types: + +- The [**dt (Display Type)**](dt--display-type-.md) command finds a variety of data types and displays data structures that have been created by the application that is being debugged. This command is highly versatile and has many variations and options. + +- The [**ds, dS (Display String)**](ds--ds--display-string-.md) command displays a STRING, ANSI\_STRING, or UNICODE\_STRING data structure. + +- The [**dl (Display Linked List)**](dl--display-linked-list-.md) command traces and displays a linked list. + +- The [**d\*s (Display Words and Symbols)**](dds--dps--dqs--display-words-and-symbols-.md) command finds double-words or quad-words that might contain symbol information and then displays the data and the symbol information. + +- The [**!address**](-address.md) extension command displays information about the properties of the memory that is located at a specific address. + +You can use the following commands to manipulate memory ranges: + +- The [**m (Move Memory)**](m--move-memory-.md) command moves the contents of one memory range to another. + +- The [**f (Fill Memory)**](f--fp--fill-memory-.md) command writes a pattern to a memory range, repeating it until the range is full. + +- The [**c (Compare Memory)**](c--compare-memory-.md) command compares the contents of two memory ranges. + +- The [**s (Search Memory)**](s--search-memory-.md) command searches for a specified pattern within a memory range or searches for any ASCII or Unicode characters that exist in a memory range. + +- The [**.holdmem (Hold and Compare Memory)**](-holdmem--hold-and-compare-memory-.md) command compares one memory range to another. + +In most situations, these commands interpret their parameters in the current radix. Therefore, you should add **0x** before hexadecimal addresses if the current radix is not 16. However, the display output of these commands is typically in hexadecimal format, regardless of the current radix. (For more information about the output, see the individual command topics.) The [Memory window](memory-window.md) displays integers and real numbers in decimal format and displays other formats in hexadecimal format. + +To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. To quickly convert numbers from one base to another, use the [**? (Evaluate Expression)**](---evaluate-expression-.md) command or the [**.formats (Show Number Formats)**](-formats--show-number-formats-.md) command. + +When you are performing user-mode debugging, the meaning of virtual addresses is determined by the current process. When you are performing kernel-mode debugging, the meaning of virtual addresses can be controlled by the debugger. For more information, see [Process Context](changing-contexts.md#process-context). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Accessing%20Memory%20by%20Virtual%20Address%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/accessing-symbols-for-debugging.md b/windows-driver-docs-pr/debugger/accessing-symbols-for-debugging.md new file mode 100644 index 0000000000..ce4a33f812 --- /dev/null +++ b/windows-driver-docs-pr/debugger/accessing-symbols-for-debugging.md @@ -0,0 +1,43 @@ +--- +title: Accessing Symbols for Debugging +description: Accessing Symbols for Debugging +ms.assetid: a0f52dc3-6903-4d63-b74c-5c16960a7cb6 +--- + +# Accessing Symbols for Debugging + + +## + + +Setting up symbols correctly for debugging can be a challenging task, particularly for kernel debugging. It often requires that you know the names and releases of all products on your computer. The debugger must be able to locate each of the symbol files corresponding to the product releases and service packs. + +This can result in an extremely long symbol path consisting of a long list of directories. + +To simplify these difficulties in coordinating symbol files, the symbol files can be gathered into a *symbol store*, which is then accessed by a *symbol server*. + +A symbol store is a collection of symbol files, an index, and a tool that can be used by an administrator to add and delete files. The files are indexed according to unique parameters such as the time stamp and image size. A symbol store can also hold executable image files which can be extracted using a symbol server. Debugging Tools for Windows contains a symbol store creation tool called [SymStore](symstore.md). + +A symbol server enables the debuggers to automatically retrieve the correct symbol files from a symbol store without the user needing to know product names, releases, or build numbers. Debugging Tools for Windows contains a symbol server called [SymSrv](symsrv.md). The symbol server is activated by including a certain text string in the symbol path. Each time the debugger needs to load symbols for a newly loaded module, it calls the symbol server to locate the appropriate symbol files. + +If you wish to use a different method for your symbol search than that provided by SymSrv, you can create your own symbol server DLL. For details on implementing such a symbol server, see [Other Symbol Servers](other-symbol-servers.md). + +If you are performing user-mode debugging, you will need symbols for the target application. If you are performing kernel-mode debugging, you will need symbols for the driver you are debugging, as well as the Windows public symbols. Microsoft has created a symbol store with public symbols for Microsoft products; this symbol store is available on the internet. These symbols can be loaded using the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command, as long as you have access to the internet while your debugger is running. For more information or to determine how to manually install these symbols, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +This section includes: + +[Installing Windows Symbol Files](installing-windows-symbol-files.md) + +[Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md) + +[Deferred Symbol Loading](deferred-symbol-loading.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Accessing%20Symbols%20for%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/acpi-debugging.md b/windows-driver-docs-pr/debugger/acpi-debugging.md new file mode 100644 index 0000000000..d801d7071c --- /dev/null +++ b/windows-driver-docs-pr/debugger/acpi-debugging.md @@ -0,0 +1,33 @@ +--- +title: ACPI Debugging +description: ACPI Debugging +ms.assetid: c3d5e404-c2d9-4f38-8473-66e76ea97ea9 +keywords: ["ACPI debugging", "BIOS debugging, ACPI BIOS debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI Debugging + + +## + + +This section includes: + +[The AMLI Debugger](the-amli-debugger.md) + +[Other ACPI Debugging Extensions](other-acpi-debugging-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ACPI%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/acpi-extensions--acpikd-dll-and-kdexts-dll-.md b/windows-driver-docs-pr/debugger/acpi-extensions--acpikd-dll-and-kdexts-dll-.md new file mode 100644 index 0000000000..d3d35daef0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/acpi-extensions--acpikd-dll-and-kdexts-dll-.md @@ -0,0 +1,33 @@ +--- +title: ACPI Extensions (Acpikd.dll and Kdexts.dll) +description: ACPI Extensions (Acpikd.dll and Kdexts.dll) +ms.assetid: 1b1df290-b65b-4066-baf5-0f283990467f +keywords: ["ACPI debugging, extensions (acpikd.dll and kdexts.dll)", "acpikd.dll (ACPI extensions)", "extensions, ACPI"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI Extensions (Acpikd.dll and Kdexts.dll) + + +## + + +Extension commands that are useful for debugging ACPI (Advanced Configuration and Power Interface) BIOS code can be found in Acpikd.dll and Kdexts.dll. + +The Windows 2000 versions of these extension commands appear in the Acpikd.dll module located in the W2kfre and W2kchk directories. Note that this extension module has an internal build number of 2179, while Windows 2000 has a build number of 2195. You should ignore the resulting version mismatch errors. + +For Windows XP and later versions of Windows, some of the ACPI debugging extensions can be found in Winxp\\Acpikd.dll, while others can be found in Winxp\\Kdexts.dll. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ACPI%20Extensions%20%28Acpikd.dll%20and%20Kdexts.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-debugging-client.md b/windows-driver-docs-pr/debugger/activating-a-debugging-client.md new file mode 100644 index 0000000000..e1734a9568 --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-debugging-client.md @@ -0,0 +1,129 @@ +--- +title: Activating a Debugging Client +description: Once the debugging server has been activated, you can start a debugging client on another computer and connect to the debugging session. +ms.assetid: 45a7baa7-08dc-47ae-a137-874aaa4ec8aa +keywords: ["Activating a Debugging Client Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Debugging Client +api_type: +- NA +--- + +# Activating a Debugging Client + + +Once the debugging server has been activated, you can start a debugging client on another computer and connect to the debugging session. + +There are two ways to start a debugging client: by using the -remote [command-line option](command-line-options.md), or by using the WinDbg graphical interface. + +The protocol of the client must match the protocol of the server. The general syntax for starting a debugging client depends on the protocol used. The following options exist: + +``` +Debugger -remote npipe:server=Server,pipe=PipeName[,password=Password] + +Debugger -remote tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +Debugger -remote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +Debugger -remote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +Debugger -remote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +To use the graphical interface to connect to a remote debugging session, WinDbg must be in dormant mode -- it must either have been started with no command-line parameters, or it must have ended the previous debugging session. Select the **File | Connect to Remote Session** menu command, or press the CTRL+R shortcut key. When the **Connect to Remote Debugger Session** dialog box appears, enter one of the following strings into the **Connection string** text box: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] + +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +Alternatively, you can use the **Browse** button to locate active debugging servers. See [File | Connect to Remote Session](file---connect-to-remote-session.md) for details. + +## + + +The parameters in the preceding commands have the following possible values: + + *Debugger* +This does not have to be the same debugger as the one used by the debugging client -- WinDbg, KD, and CDB are all interchangeable for purposes of remote debugging through the debugger. + + *Server* +This is the network name or IP address of the computer on which the debugging server was created. The two initial backslashes (\\\) are optional on the command line, but are not permitted in the WinDbg dialog box. + + **pipe=** *PipeName* +If NPIPE or SPIPE protocol is used, *PipeName* is the name that was given to the pipe when the server was created. + +If you are not logged on to the client computer with an account that has access to the server computer, you must provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* + +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can activate a debugging client by using the **-remote** command-line option or by using the WinDbg graphical interface. + +**Note**  You might need to enable file and printer sharing on the server computer. In Control Panel, navigate to **Network and Internet > Network and Sharing Center> Advanced sharing settings**. Select **Turn on file and printer sharing**. + +  + + **port=** *Socket* +If TCP or SSL protocol is used, *Socket* is the same socket port number that was used when the server was created. + +**clicon** +Specifies that the debugging server will try to connect to the client through a reverse connection. The client must use **clicon** if and only if the server is using **clicon**. In most cases, the debugging client is started before the debugging server when a reverse connection is used. + + **port=** *COMPort* +If COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +If COM protocol is used, *BaudRate* should match the baud rate chosen when the server was created. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* should match the channel number chosen when the server was created. + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* should match the secure protocol used when the server was created. + + *Cert* +If SSL or SPIPE protocol is used, you should use the identical **certuser=***Cert* or **machuser=** *Cert* parameter that was used when the server was created. + + **password=** *Password* +If a password was used when the server was created, *Password* must be supplied in order to create the debugging client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005." Passwords must be twelve characters or less in length. + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +Command-line options used to start new debugging sessions (like **-p**) cannot be used by the debugging client, but only by the server. Configuration options (like **-n**) will work from either the client or the server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Debugging%20Client%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-debugging-server.md b/windows-driver-docs-pr/debugger/activating-a-debugging-server.md new file mode 100644 index 0000000000..7dbcafeb5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-debugging-server.md @@ -0,0 +1,142 @@ +--- +title: Activating a Debugging Server +description: There are two ways to activate the debugging server. +ms.assetid: aba75d2d-4077-415f-b847-023e47239e2e +keywords: ["Activating a Debugging Server Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Debugging Server +api_type: +- NA +--- + +# Activating a Debugging Server + + +There are two ways to activate the debugging server. It can be activated when the debugger is started by using the **-server** command-line option in a elevated Command Prompt window (Run as Administrator). It can also be activated after the debugger is running. Start the debugger with elevated privileges (Run as Administrator), and enter the [**.server**](-server--create-debugging-server-.md) command. + +**Note**  You can activate a debugging server without having elevated privileges, and debugging clients will be able to connect to the server. However, clients will not be able to discover a debugging server unless it was activated with elevated privileges. For information about how to discover debugging servers, see [Searching for Debugging Servers](searching-for-debugging-servers.md). + +  + +The debuggers support several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL). + +The general syntax for activating a debugging server depends on the protocol used. + +``` +Debugger -server npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] [-noio] [Options] + +Debugger -server tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] [-noio] [Options] + +Debugger -server tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] [-noio] [Options] + +Debugger -server com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] [-noio] [Options] + +Debugger -server spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] [-noio] [Options] + +Debugger -server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] [-noio] [Options] + +Debugger -server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] [-noio] [Options] +``` + +Another method of activating a debugging server is to use the [**.server (Create Debugging Server)**](-server--create-debugging-server-.md) command after the debugger has already been started. + +``` +.server npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] + +.server tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] + +.server tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] + +.server com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] + +.server spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] + +.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] + +.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] +``` + +## + + +The parameters in the previous commands have the following possible values: + + *Debugger* +Can be KD, CDB, NTSD, or WinDbg. + + **pipe=** *PipeName* +When NPIPE or SPIPE protocol is used, *PipeName* is a string that will serve as the name of the pipe. Each pipe name should identify a unique debugging server. If you attempt to reuse a pipe name, you will receive an error message. *PipeName* must not contain spaces or quotation marks. *PipeName* can include a numerical **printf**-style format code, such as **%x** or **%d**. The debugger will replace this with the process ID of the debugger. A second such code will be replaced with the thread ID of the debugger. + +**Note**  You might need to enable file and printer sharing on the computer that is running the debugging server. In Control Panel, navigate to **Network and Internet > Network and Sharing Center> Advanced sharing settings**. Select **Turn on file and printer sharing**. + +  + + **port=** *Socket* +When TCP or SSL protocol is used, *Socket* is the socket port number. + +It is also possible to specify a range of ports separated by a colon. The debugger will check each port in this range to see if it is free. If it finds a free port and no error occurs, the debugging server will be created. The debugging client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the methods described in [**Searching for Debugging Servers**](searching-for-debugging-servers.md); when this debugging server is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as **port=51:60**, and port 53 was actually used, the search results will show "port=53:60". (If you are using the **clicon** parameter to establish a reverse connection, the debugging client can specify a range of ports in this manner, while the server must specify the actual port used.) + + **clicon=** *Client* +When TCP or SSL protocol is used and the **clicon** parameter is specified, a *reverse connection* will be opened. This means that the debugging server will try to connect to the debugging client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. *Client* specifies the network name or IP address of the computer on which the debugging client exists or will be created. The two initial backslashes (\\\) are optional. + +Since the server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or is broken you will have to restart the server connection. A reverse-connection server will not appear when another debugger displays all active servers. + +**Note**   When **clicon** is used, it is best to start the debugging client before the debugging server is created, although the usual order (server before client) is also permitted. + +  + +**port=** *COMPort* +When COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +When COM protocol is used, *BaudRate* specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254, inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable -- in that situation you cannot use channels within a COM port.) + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3. + +*Cert* +If SSL or SPIPE protocol is used, *Cert* specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits given by the certificate's snapin). If the syntax **certuser=***Cert* is used, the debugger will look up the certificate in the system store (the default store). If the syntax **machuser=***Cert* is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication. + + **hidden** +Prevents the server from appearing when another debugger displays all active servers. + + **password=** *Password* +Requires a client to supply the specified password in order to connect to the debugging session. *Password* can be any alphanumeric string, up to twelve characters in length. + +**Warning**   Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol. + +  + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +**-noio** +If the debugging server is created with the **-noio** option, no input or output can be done through the server itself. The debugger will only accept input from the debugging client (plus any initial command or command script specified by the **-c** command-line option). All output will be directed to the debugging client. The **-noio** option is only available with KD, CDB, and NTSD. If NTSD is used for the server, no console window will be created at all. + + **IcfEnable** +(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When **IcfEnable** is used with a TCP connection, the debugger causes Windows to open the port specified by the *Socket* parameter. When **IcfEnable** is used with a named pipe connection, the debugger causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates. + +*Options* +Any additional command-line parameters can be placed here. See [Command-Line Options](command-line-options.md) for a full list. + +You can use the [**.server**](-server--create-debugging-server-.md) command to start multiple servers using different protocol options. This allows different kinds of debugging clients to join the session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Debugging%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-kd-connection-server.md b/windows-driver-docs-pr/debugger/activating-a-kd-connection-server.md new file mode 100644 index 0000000000..fd8493ecbf --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-kd-connection-server.md @@ -0,0 +1,109 @@ +--- +title: Activating a KD Connection Server +description: To activate a KD connection server, open an elevated Command Prompt window (Run as Adminstrator), and enter the kdsrv command. +ms.assetid: 1b6f6f72-2679-45c7-bf1b-9607bf7e7d89 +keywords: ["Activating a KD Connection Server Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a KD Connection Server +api_type: +- NA +--- + +# Activating a KD Connection Server + + +The KD connection server that is included in Debugging Tools for Windows is called KdSrv (kdsrv.exe). To activate a KD connection server, open an elevated Command Prompt window (Run as Adminstrator), and enter the **kdsrv** command. + +**Note**  You can activate a KD connection server without having elevated privileges, and debugging clients will be able to connect to the server. However, clients will not be able to discover a KD connection server unless it was activated with elevated privileges. For information about how to discover debugging servers, see [**Searching for KD Connection Servers**](searching-for-kd-connection-servers.md). + +  + +KdSrv supports several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL). + +The syntax for the KdSrv command line depends on the protocol used. The following options exist: + +``` +kdsrv -t npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] + +kdsrv -t tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] + +kdsrv -t tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] + +kdsrv -t com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] + +kdsrv -t spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] + +kdsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] + +kdsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] +``` + +## + + +The parameters in the previous commands have the following possible values: + + **pipe=** *PipeName* +When NPIPE or SPIPE protocol is used, *PipeName* is a string that will serve as the name of the pipe. Each pipe name should identify a unique process server. If you attempt to reuse a pipe name, you will receive an error message. *PipeName* must not contain spaces or quotation marks. *PipeName* can include a numerical **printf**-style format code, such as **%x** or **%d**. This will be replaced by the process ID of KdSrv. A second such code will be replaced by the thread ID of KdSrv. + + **port=** *Socket* +When TCP or SSL protocol is used, *Socket* is the socket port number. + +It is also possible to specify a range of ports separated by a colon. KdSrv will check each port in this range to see if it is free. If it finds a free port and no error occurs, the KD connection server will be created. The smart client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the methods described in [**Searching for KD Connection Servers**](searching-for-kd-connection-servers.md); when this KD connection server is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as **port=51:60**, and port 53 was actually used, the search results will show "port=53:60". (If you are using the **clicon** parameter to establish a reverse connection, the smart client can specify a range of ports in this manner, while the KD connection server must specify the actual port used.) + + **clicon=** *Client* +When TCP or SSL protocol is used and the **clicon** parameter is specified, a *reverse connection* will be opened. This means that the KD connection server will try to connect to the smart client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. *Client* specifies the network name or IP address of the computer on which the smart client exists or will be created. The two initial backslashes (\\\) are optional. + +Since the KD connection server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or is broken you will have to restart the process server. A reverse-connection KD connection server will not appear when someone uses the **-QR** command-line option to display all active servers. + +**Note**   When **clicon** is used, it is best to start the smart client before the KD connection server is created, although the usual order (server before client) is also permitted. + +  + +**port=** *COMPort* +When COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +When COM protocol is used, *BaudRate* specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254, inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable -- in that situation you cannot use channels within a COM port.) + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3. + + *Cert* +If SSL or SPIPE protocol is used, *Cert* specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits given by the certificate's snapin). If the syntax **certuser=***Cert* is used, the debugger will look up the certificate in the system store (the default store). If the syntax **machuser=***Cert* is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication. + + **hidden** +Prevents the KD connection server from appearing when someone uses the **-QR** command-line option to display all active servers. + + **password=** *Password* +Requires a smart client to supply the specified password in order to connect to the KD connection server. *Password* can be any alphanumeric string, up to twelve characters in length. + +**Warning**   Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol. + +  + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + + **IcfEnable** +(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When **IcfEnable** is used with a TCP connection, the debugger causes Windows to open the port specified by the *Socket* parameter. When **IcfEnable** is used with a named pipe connection, the debugger causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20KD%20Connection%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-process-server.md b/windows-driver-docs-pr/debugger/activating-a-process-server.md new file mode 100644 index 0000000000..d13fabd8e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-process-server.md @@ -0,0 +1,131 @@ +--- +title: Activating a Process Server +description: To activate a process server, open an elevated Command Prompt window (Run as Administrator), and enter the dbgsrv command. +ms.assetid: 566a4f64-8a14-469b-b50c-20e3c00aa2f8 +keywords: ["Activating a Process Server Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Process Server +api_type: +- NA +--- + +# Activating a Process Server + + +The process server that is included in Debugging Tools for Windows is called DbgSrv (dbgsrv.exe). To activate a process server, open an elevated Command Prompt window (Run as Administrator), and enter the **dbgsrv** command. + +**Note**  You can activate a process server without having elevated privileges, and debugging clients will be able to connect to the server. However, clients will not be able to discover a process server unless it was activated with elevated privileges. For information about how to discover debugging servers, see [Searching for Process Servers](searching-for-process-servers.md). + +  + +DbgSrv supports several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL). + +``` +dbgsrv -t npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] + +dbgsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] [[-sifeo Executable] -c[s] AppCmdLine] [-x | -pc] +``` + +## + + +The parameters in the previous commands have the following possible values: + + **pipe=** *PipeName* +When NPIPE or SPIPE protocol is used, *PipeName* is a string that will serve as the name of the pipe. Each pipe name should identify a unique process server. If you attempt to reuse a pipe name, you will receive an error message. *PipeName* must not contain spaces or quotation marks. *PipeName* can include a numerical **printf**-style format code, such as **%x** or **%d**. The process server will replace this with the process ID of DbgSrv. A second such code will be replaced with the thread ID of DbgSrv. + +**Note**  You might need to enable file and printer sharing on the computer that is running the process server. In Control Panel, navigate to **Network and Internet > Network and Sharing Center> Advanced sharing settings**. Select **Turn on file and printer sharing**. + +  + + **port=** *Socket* +When TCP or SSL protocol is used, *Socket* is the socket port number. + +It is also possible to specify a range of ports separated by a colon. DbgSrv will check each port in this range to see if it is free. If it finds a free port and no error occurs, the process server will be created. The smart client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the methods described in [**Searching for Process Servers**](searching-for-process-servers.md); when this process server is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as **port=51:60**, and port 53 was actually used, the search results will show "port=53:60". (If you are using the **clicon** parameter to establish a reverse connection, the smart client can specify a range of ports in this manner, while the process server must specify the actual port used.) + + **clicon=** *Client* +When TCP or SSL protocol is used and the **clicon** parameter is specified, a *reverse connection* will be opened. This means that the process server will try to connect to the smart client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. *Client* specifies the network name or IP address of the computer on which the smart client exists or will be created. The two initial backslashes (\\\) are optional. + +Since the process server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or is broken you will have to restart the process server. A reverse-connection process server will not appear when someone uses the **-QR** command-line option to display all active servers. + +**Note**   When **clicon** is used, it is best to start the smart client before the process server is created, although the usual order (server before client) is also permitted. + +  + +**port=** *COMPort* +When COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +When COM protocol is used, *BaudRate* specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254, inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable -- in that situation you cannot use channels within a COM port.) + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3. + +*Cert* +If SSL or SPIPE protocol is used, *Cert* specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits given by the certificate's snapin). If the syntax **certuser=***Cert* is used, the debugger will look up the certificate in the system store (the default store). If the syntax **machuser=***Cert* is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication. + + **hidden** +Prevents the process server from appearing when someone uses the **-QR** command-line option to display all active servers. + + **password=** *Password* +Requires a smart client to supply the specified password in order to connect to the process server. *Password* can be any alphanumeric string, up to twelve characters in length. + +**Warning**   Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol. + +  + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + + **IcfEnable** +(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When **IcfEnable** is used with a TCP connection, the debugger causes Windows to open the port specified by the *Socket* parameter. When **IcfEnable** is used with a named pipe connection, the debugger causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates. + +**-sifeo** *Executable* +Suspends the Image File Execution Option (IFEO) value for the given image. *Executable* should include the file name of the executable image, including the file name extensions. The **-sifeo** option allows DbgSrv to be set as the IFEO debugger for an image created by the **-c** option, without causing recursive invocation due to the IFEO setting. This option can be used only if **-c** is used. + + **-c** +Causes DbgSrv to create a new process. You can use this to create a process that you intend to debug. This is similar to spawning a new process from the debugger, except that this process will not be debugged when it is created. To debug this process, determine its PID and use the **-p** option when starting the smart client to debug this process. + +**s** +Causes the newly-created process to be immediately suspended. If you are using this option, it is recommended that you use CDB as your smart client, and that you start the smart client with the **-pb** command-line option, in conjunction with **-p PID**. If you include the **-pb** option on the command line, the process will resume when the debugger attaches to it; otherwise you can resume the process with the [**~\*m**](-m--resume-thread-.md) command. + +*AppCmdLine* +Specifies the full command line of the process to be created. *AppCmdLine* can be either a Unicode or ASCII string, and can include any printable character. All text that appears after the **-c\[s\]** parameter will be taken to form the string *AppCmdLine*. + +**-x** +Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its command line. + + **-pc** +Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its command line. A syntax error results if **-pc** is the final element on the DbgSrv command line. Aside from this restriction, **-pc** is identical to **-x**. + +You can start any number of process servers on one computer. However, this is generally unnecessary, since one process server can be used by any number of smart clients (each engaged in a different debugging session). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Process%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-repeater.md b/windows-driver-docs-pr/debugger/activating-a-repeater.md new file mode 100644 index 0000000000..5bf90a8150 --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-repeater.md @@ -0,0 +1,154 @@ +--- +title: Activating a Repeater +description: To activate the repeater connection, you will usually first start the server, then start the repeater, then start the client.It is also possible to start the repeater first and then the server. +ms.assetid: a2409b3d-48eb-46eb-8a53-7c4d505bb6ea +keywords: ["Activating a Repeater Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Repeater +api_type: +- NA +--- + +# Activating a Repeater + + +To activate the repeater connection, you will usually first start the server, then start the repeater, then start the client. + +It is also possible to start the repeater first and then the server. But unless you are using the **clicon** parameter to establish a reverse connection, the client must always be started last. + +## Step One: Starting the Server + + +The server can be a debugging server, a process server, or a KD connection server. You start this as you normally would, except that the transport protocol settings will be used to connect to the repeater, not the client. For details, see [**Activating a Debugging Server**](activating-a-debugging-server.md), [**Activating a Process Server**](activating-a-process-server.md), or [**Activating a KD Connection Server**](activating-a-kd-connection-server.md). + +If you use a password when creating the server, this password will be required when the client attaches, but not when the repeater is created. + +If you use the **hidden** parameter, the server will be hidden as usual. The repeater itself is always hidden. + +## Step Two: Starting the Repeater + + +The repeater that is included in Debugging Tools for Windows is called DbEngPrx (dbengprx.exe). + +DbEngPrx understands the following transport protocols: named pipe (NPIPE), TCP, and COM port. + +If your client and server are using secure sockets layer (SSL) protocol, you should use TCP protocol for the repeater. If your client and server are using secure pipe (SPIPE) protocol, you should use NPIPE protocol for the repeater. The repeater will pass on whatever data it receives -- it does not interpret, encrypt, or decrypt any information. All encryption and decryption will be done by the client and the server. + +The syntax for the DbEnPrx command line is as follows: + +## + + +**dbengprx \[-p\] -c** *ClientTransport* **-s** *ServerTransport* + +The parameters in the previous commands have the following possible values: + + **-p** +Causes DbEngPrx to continue existing even after all connections to it are dropped. + +*ClientTransport* +Specifies the protocol settings to be used in connecting to the server. The protocol should match that used when the server was created. The protocol syntaxes are as follows: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] +``` + +The protocol parameters have the following meanings: + +*Server* +This is the network name or IP address of the computer on which the server was created. The two initial backslashes (\\\) are optional. + + **pipe=** *PipeName* +If NPIPE or SPIPE protocol is used, *PipeName* is the name that was given to the pipe when the server was created. + + **port=** *Socket* +If TCP or SSL protocol is used, *Socket* is the same socket port number that was used when the server was created. + +**clicon** +Specifies that the server will try to connect to the repeater through a reverse connection. *ClientTransport* must use **clicon** if and only if the server is using **clicon**. In most cases, the repeater is started before the server when a reverse connection is used. + +**port=** *COMPort* +If COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +If COM protocol is used, *BaudRate* should match the baud rate chosen when the server was created. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* should match the channel number chosen when the server was created. + + **password=** *Password* +If a password was used when the server was created, *Password* must be supplied in order to create the debugging client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005." + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +ServerTransport +Specifies the protocol settings that will be used when the client connects to the repeater. The possible protocol syntaxes are: + +``` +npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] +tcp:port=Socket[,hidden][,password=Password][,IcfEnable] +tcp:port=Socket,clicon=Client[,password=Password] +com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] +``` + +The protocol parameters have the following meanings: + + **pipe=** *PipeName* +When NPIPE or SPIPE protocol is used, *PipeName* is a string that will serve as the name of the pipe. Each pipe name should identify a unique repeater. If you attempt to reuse a pipe name, you will receive an error message. *PipeName* must not contain spaces or quotation marks. *PipeName* can include a numerical **printf**-style format code, such as **%x** or **%d**. The repeater will replace this with the process ID of DbEngPrx. A second such code will be replaced with the thread ID of DbEngPrx. + + **port=** *Socket* +When TCP or SSL protocol is used, *Socket* is the socket port number. + +It is also possible to specify a range of ports separated by a colon. DbEngPrx will check each port in this range to see if it is free. If it finds a free port and no error occurs, the repeater will be created. The client will have to specify the actual port being used to connect to the repeater. To determine the actual port, search for the repeater; when this repeater is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as **port=51:60**, and port 53 was actually used, the search results will show "port=53:60". (If you are using the **clicon** parameter to establish a reverse connection, the client can specify a range of ports in this manner, while the repeater must specify the actual port used.) + +**clicon=***Client* +When TCP or SSL protocol is used and the **clicon** parameter is specified, a *reverse connection* will be opened. This means that the repeater will try to connect to the client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. *Client* specifies the network name or IP address of the computer on which the client exists or will be created. The two initial backslashes (\\\) are optional. + +Since the repeater is looking for one specific client, you cannot connect multiple clients to the repeater if you use this method. If the connection is refused or is broken you will have to restart the repeater. + +When **clicon** is used, it is best to start the client before the repeater is created, although the usual order (repeater before client) is also permitted. + +**port=** *COMPort* +When COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. You cannot use the same COM port in the *ClientTransport* and the *ServerTransport*. + +**baud=** *BaudRate* +When COM protocol is used, *BaudRate* specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. If you are using COM protocol in both the *ClientTransport* and the *ServerTransport* you may specify different baud rates, but naturally the slower rate will be the limit on how fast the client and server can communicate with each other. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* specifies the COM channel to be used in communicating with the client. This can be any value between 0 and 254, inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable -- in that situation you cannot use channels within a COM port.) + +**hidden** +Prevents the server from appearing when another debugger displays all active servers. + + **password=** *Password* +Requires a client to supply the specified password in order to connect to the debugging session. *Password* can be any alphanumeric string. + +**IcfEnable** +(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When **IcfEnable** is used with a TCP connection, the debugger causes Windows to open the port specified by the *Socket* parameter. When **IcfEnable** is used with a named pipe connection, the debugger causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates. + +### Step Three: Starting the Client + +The client should be a debugging client or a smart client -- whichever corresponds to your server type. For details, see [**Activating a Debugging Client**](activating-a-debugging-client.md), [**Activating a Smart Client**](activating-a-smart-client.md), or [**Activating a Smart Client (Kernel Mode)**](activating-a-smart-client--kernel-mode-.md). + +If the server rejects the connection (for example, if you supply an incorrect password), both the repeater and the client will be shut down. You will have to restart both of them to reestablish contact with the server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Repeater%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-smart-client--kernel-mode-.md b/windows-driver-docs-pr/debugger/activating-a-smart-client--kernel-mode-.md new file mode 100644 index 0000000000..ecce131364 --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-smart-client--kernel-mode-.md @@ -0,0 +1,143 @@ +--- +title: Activating a Smart Client (Kernel Mode) +description: Once the KD connection server has been activated, you can create a smart client on another computer and begin a debugging session. +ms.assetid: bf0f1dd5-e6dc-4168-8476-cf21e77bd335 +keywords: ["Activating a Smart Client (Kernel Mode) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Smart Client (Kernel Mode) +api_type: +- NA +--- + +# Activating a Smart Client (Kernel Mode) + + +Once the KD connection server has been activated, you can create a smart client on another computer and begin a debugging session. + +There are two ways to start a smart client: by starting KD or WinDbg with the kernel protocol **kdsrv**, or by using the WinDbg graphical interface. + +You need to specify the remote transfer protocol used by the KD connection server. You can also specify the protocol for the actual kernel connection between the KD connection server and the target computer, or you can use the default. + +The general syntax for starting a smart client depends on the protocol used. The following options exist: + +``` +Debugger -k kdsrv:server=@{npipe:server=Server,pipe=PipeName[,password=Password]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{tcp:server=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]},trans=@{ConnectType} [Options] + +Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]},trans=@{ConnectType} [Options] +``` + +To use the graphical interface to connect to a KD connection server, WinDbg must be in dormant mode -- it must either have been started with no command-line parameters, or it must have ended the previous debugging session. Select the **File | Connect to Remote Stub** menu command. When the **Connect to Remote Stub Server** dialog box appears, enter one of the following strings into the **Connection string** text box: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] + +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +Alternatively, you can use the **Browse** button to locate active KD connection servers. See [File | Connect to Remote Stub](file---connect-to-remote-stub.md) for details. + +## + + +The parameters in the preceding commands have the following possible values: + + *Debugger* +This can be KD or WinDbg. + +*Server* +This is the network name or IP address of the computer on which the KD connection server was created.The two initial backslashes (\\\) are optional on the command line, but are not permitted in the WinDbg dialog box. + + **pipe=** *PipeName* +If NPIPE or SPIPE protocol is used, *PipeName* is the name that was given to the pipe when the KD connection server was created. + +If you are not logged on to the client computer with an account that has access to the server computer, you must provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* + +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can activate a smart client by using **-k kdsrv** or by using the WinDbg graphical interface. + + **port=** *Socket* +If TCP or SSL protocol is used, *Socket* is the same socket port number that was used when the KD connection server was created. + +**clicon** +Specifies that the KD connection server will try to connect to the smart client through a reverse connection. The client must use **clicon** if and only if the server is using **clicon**. In most cases, the smart client is started before the KD connection server when a reverse connection is used. + +**port=** *COMPort* +If COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +If COM protocol is used, *BaudRate* should match the baud rate chosen when the KD connection server was created. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* should match the channel number chosen when the KD connection server was created. + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* should match the secure protocol used when the KD connection server was created. + + *Cert* +If SSL or SPIPE protocol is used, you should use the identical **certuser=***Cert* or **machuser=***Cert* parameter that was used when the KD connection server was created. + + **password=** *Password* +If a password was used when the KD connection server was created, *Password* must be supplied in order to create the smart client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005." + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + + **trans=@{** *ConnectType* **}** +Tells the debugger how to connect to the target. The following kernel connection protocols are permitted: + +``` +com:port=ComPort,baud=BaudRate +1394:channel=1394Channel[,symlink=1394Protocol] +usb2:targetname=String +com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect] +com:modem +``` + +For information about these protocols, see [Getting Set Up for Debugging](getting-set-up-for-debugging.md). You can omit any of the parameters for these protocols -- for example, you can say **trans=@{com:}** -- and the debugger will default to the values specified by the environment variables on the computer where KdSrv is running. + +*Options* +Any additional command-line parameters can be placed here. See [Command-Line Options](command-line-options.md) for a full list. + +Since the KD connection server simply acts as a gateway for the smart client, the additional *Options* will be the same as those you would use if you were starting a kernel debugger on computer where KdSrv is running. The exception to this is any option that specifies a path or filename will be taken as a path on the computer where the smart client is running. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Smart%20Client%20%28Kernel%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-a-smart-client.md b/windows-driver-docs-pr/debugger/activating-a-smart-client.md new file mode 100644 index 0000000000..08468df67e --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-a-smart-client.md @@ -0,0 +1,134 @@ +--- +title: Activating a Smart Client +description: Once the DbgSrv process server has been activated, you can create a smart client on another computer and begin a debugging session. +ms.assetid: 7199dc95-e8fc-4f58-ab6e-c0141681113e +keywords: ["Activating a Smart Client Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Activating a Smart Client +api_type: +- NA +--- + +# Activating a Smart Client + + +Once the DbgSrv process server has been activated, you can create a smart client on another computer and begin a debugging session. + +There are two ways to start a smart client: by starting CDB or WinDbg with the -premote [command-line option](command-line-options.md), or by using the WinDbg graphical interface. + +The protocol of the smart client must match the protocol of the process server. The general syntax for starting a smart client depends on the protocol used. The following options exist: + +``` +Debugger -premote npipe:server=Server,pipe=PipeName[,password=Password] [Options] + +Debugger -premote tcp:server=Server,port=Socket[,password=Password][,ipversion=6] [Options] + +Debugger -premote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] [Options] + +Debugger -premote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] [Options] + +Debugger -premote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] [Options] + +Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] [Options] + +Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] [Options] +``` + +To use the graphical interface to connect to a process server, WinDbg must be in dormant mode -- it must either have been started with no command-line parameters, or it must have ended the previous debugging session. Select the **File | Connect to Remote Stub** menu command. When the **Connect to Remote Stub Server** dialog box appears, enter one of the following strings into the **Connection string** text box: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] + +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +Alternatively, you can use the **Browse** button to locate active process servers. See [File | Connect to Remote Stub](file---connect-to-remote-stub.md) for details. + +## + + +The parameters in the preceding commands have the following possible values: + + *Debugger* +This can be CDB or WinDbg. + + *Server* +This is the network name or IP address of the computer on which the process server was created. The two initial backslashes (\\\) are optional on the command line, but are not permitted in the WinDbg dialog box. + + **pipe=** *PipeName* +If NPIPE or SPIPE protocol is used, *PipeName* is the name that was given to the pipe when the process server was created. + +If you are not logged on to the client computer with an account that has access to the server computer, you must provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* + +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can activate a smart client by using the **-premote** command-line option or by using the WinDbg graphical interface. + +**Note**  You might need to enable file and printer sharing on the server computer. In Control Panel, navigate to **Network and Internet > Network and Sharing Center> Advanced sharing settings**. Select **Turn on file and printer sharing**. + +  + + **port=** *Socket* +If TCP or SSL protocol is used, *Socket* is the same socket port number that was used when the process server was created. + + **clicon** +Specifies that the process server will try to connect to the smart client through a reverse connection. The client must use **clicon** if and only if the server is using **clicon**. In most cases, the smart client is started before the process server when a reverse connection is used. + +**port=** *COMPort* +If COM protocol is used, *COMPort* specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable. + +**baud=** *BaudRate* +If COM protocol is used, *BaudRate* should match the baud rate chosen when the process server was created. + +**channel=** *COMChannel* +If COM protocol is used, *COMChannel* should match the channel number chosen when the process server was created. + + **proto=** *Protocol* +If SSL or SPIPE protocol is used, *Protocol* should match the secure protocol used when the process server was created. + +*Cert* +If SSL or SPIPE protocol is used, you should use the identical **certuser=***Cert* or **machuser=***Cert* parameter that was used when the process server was created. + + **password=** *Password* +If a password was used when the process server was created, *Password* must be supplied in order to create the smart client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005." + + **ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +*Options* +Any additional command-line parameters can be placed here. See [Command-Line Options](command-line-options.md) for a full list. If you are using CDB, this must specify the process you wish to debug. If you are using WinDbg, you can specify the process on the command line or through the graphical interface. + +Since the process server simply acts as a gateway for the smart client, the additional *Options* will be the same as those you would use if you were starting a user-mode debugger on the same machine as the target application. + +If you are using the **-premote** option with [**.attach (Attach to Process)**](-attach--attach-to-process-.md) or [**.create (Create Process)**](-create--create-process-.md), the parameters are the same as those listed above. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20a%20Smart%20Client%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/activating-secure-mode.md b/windows-driver-docs-pr/debugger/activating-secure-mode.md new file mode 100644 index 0000000000..7874af26ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/activating-secure-mode.md @@ -0,0 +1,41 @@ +--- +title: Activating Secure Mode +description: Activating Secure Mode +ms.assetid: bb7cd081-f032-4af4-bb4d-efa96917088b +keywords: ["Secure Mode, how to activate"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Activating Secure Mode + + +## + + +Secure Mode is only available for kernel-mode debugging. It must be activated before the debugging session has begun -- either on the debugger's command line, or when the debugger is completely dormant and is not yet being used as a server. + +To activate Secure Mode, use one of the following methods: + +- The **-secure** [command-line option](command-line-options.md) + +- The [**.secure 1**](-secure--activate-secure-mode-.md) command + +- The [**.symopt+0x40000**](-symopt--set-symbol-options-.md) command + +If you have an existing kernel debugging session and need to discover whether you are already in Secure Mode, use the [**.secure**](-secure--activate-secure-mode-.md) command with no arguments. This will tell you the current status of Secure Mode. + +After Secure Mode has been activated, it cannot be turned off. Even ending the debugging session will not turn it off. Secure Mode persists as long as the debugger itself is running. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Activating%20Secure%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/active-memory-dump.md b/windows-driver-docs-pr/debugger/active-memory-dump.md new file mode 100644 index 0000000000..33ffe704bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/active-memory-dump.md @@ -0,0 +1,41 @@ +--- +title: Active Memory Dump +description: Active Memory Dump +ms.assetid: b40979b6-cd9a-4655-8030-8bde25d75113 +--- + +# Active Memory Dump + + +## + + +An *Active Memory Dump* is similar to a [Complete Memory Dump](complete-memory-dump.md), but it filters out pages that are not likely to be relevant to troubleshooting problems on the host machine. Because of this filtering, it is typically significantly smaller than a complete memory dump. + +This dump file does include any memory allocated to user-mode applications. It also includes memory allocated to the Windows kernel and hardware abstraction level (HAL), as well as memory allocated to kernel-mode drivers and other kernel-mode programs. The dump includes active pages mapped into the kernel or user space that are useful for debugging, as well as selected Pagefile-backed Transition, Standby, and Modified pages such as the memory allocated with VirtualAlloc or page-file backed sections. Active dumps do not include pages on the free and zeroed lists, the file cache, guest VM pages and various other types of memory that are not likely to be useful during debugging. + +An Active Memory Dump is particularly useful when Windows is hosting virtual machines (VMs). When taking a complete memory dump, the contents of each VM is included. When there are multiple VMs running, this can account for a large amount of memory in use on the host system. Many times, the code activities of interest are in the parent host OS, not the child VMs. An active memory dump filters out the memory associated with all of the child VMs. + +The Active Memory Dump file is written to %SystemRoot%\\Memory.dmp by default. + +The Active Memory Dump is available in Windows 10 and later. + +**Note**  To suppress missing page error messages when debugging an Active Memory Dump, use the [**.ignore\_missing\_pages**](-ignore-missing-pages--suppress-missing-page-errors-.md) command. + +  + +## Related topics + + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Active%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/ad--delete-alias-.md b/windows-driver-docs-pr/debugger/ad--delete-alias-.md new file mode 100644 index 0000000000..74f0050000 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ad--delete-alias-.md @@ -0,0 +1,80 @@ +--- +title: ad (Delete Alias) +description: The ad command deletes an alias from the alias list. +ms.assetid: 8ff223b6-5cfb-4d87-b45f-ad9bd51faf7f +keywords: ["ad (Delete Alias) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ad (Delete Alias) +api_type: +- NA +--- + +# ad (Delete Alias) + + +The **ad** command deletes an alias from the alias list. + +``` +ad [/q] Name +ad * +``` + +## Parameters + + + **/q** +Specifies quiet mode. This mode hides the error message if the alias that *Name* specifies does not exist. + + *Name* +Specifies the name of the alias to delete. If you specify an asterisk (\*), all aliases are deleted (even if there is an alias whose name is "\*"). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to use aliases, see [Using Aliases](using-aliases.md). + +Remarks +------- + +You can use the **ad** command to delete any user-named alias. But you cannot use this command to delete a fixed-name alias ($u0 to $u9). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ad%20%28Delete%20Alias%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/additional-dbh-examples.md b/windows-driver-docs-pr/debugger/additional-dbh-examples.md new file mode 100644 index 0000000000..116597abbb --- /dev/null +++ b/windows-driver-docs-pr/debugger/additional-dbh-examples.md @@ -0,0 +1,350 @@ +--- +title: Additional DBH Examples +description: Additional DBH Examples +ms.assetid: 6db23b6b-e5da-4ea3-9f0a-ab42c0e712d7 +keywords: ["DBH, displaying symbols", "DBH, symbol decorations", "DBH, data types", "DBH, imaginary symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Additional DBH Examples + + +Here are additional examples of commands that can be issued at the DBH prompt. + +### Displaying Private Symbols and Public Symbols + +If the target is a full symbol file, then each public symbol appears twice in the file: in the public symbol table, and in the private symbol data. The copy in the public symbol table often contains various decorations (prefixes and suffixes). For details, see [Public and Private Symbols](public-and-private-symbols.md). + +DBH can display information about this symbol from the private symbol data, from the public symbol table without decorations, and from the public symbol table with decorations. Here is an example in which all three of these are displayed, using the command **addr 414fe0** each time. + +The first time this command appears in this example, DBH uses the default symbol options, so the resulting information comes from the private symbol data. Note that this information includes the address, size, and data type of the function **fgets**. Then, the command symopt +4000 is used, which turns on the SYMOPT\_PUBLICS\_ONLY option. This causes DBH to ignore the private symbol data, and therefore when the **addr 414fe0** command is run the second time, DBH uses the public symbol table, and no size or data type information is shown for the function **fgets**. Finally, the command symopt -2 is used, turning off the SYMOPT\_UNDNAME option and causing DBH to include decorations. When the **addr 414fe0** runs this final time, it shows the decorated version of the function name, **\_fgets**. + +``` +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +fgets + name : fgets + addr : 414fe0 + size : 113 + flags : 0 + type : 7e +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagFunction (5) + index : 7d + +pid:4308 mod:TimeTest[400000]: symopt +4000 + +Symbol Options: 0x10c13 +Symbol Options: 0x14c13 + +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +fgets + name : fgets + addr : 414fe0 + size : 0 + flags : 0 + type : 0 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagPublicSymbol (a) + index : 7f + +pid:4308 mod:TimeTest[400000]: symopt -2 + +Symbol Options: 0x14c13 +Symbol Options: 0x14c11 + +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +_fgets + name : _fgets + addr : 414fe0 + size : 0 + flags : 0 + type : 0 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagPublicSymbol (a) + index : 7f +``` + +If the -d command-line option had been used, the results would have shown the decorated public name from the beginning. + +### Determining the Decorations of a Specific Symbol + +DBH can determine the decorations on a specific symbol. This can be useful when used in conjunction with a program that requires symbols to be specified with their decorations, such as [PDBCopy](pdbcopy.md). + +For example, suppose you know that the symbol file mysymbols.pdb contains a symbol whose undecorated name is **MyFunction1**. To find the decorated name, use the following procedure. + +First, start DBH without the -d command-line option, and then use the symopt +4000 command so that all information comes from the public symbol table: + +``` +C:\> dbh c:\mydir\mysymbols.pdb + +mysymbols [1000000]: symopt +4000 + +Symbol Options: 0x10c13 +Symbol Options: 0x14c13 +``` + +Next, use the **name** command or the **enum** command to display the address of the desired symbol: + +``` +mysymbols [1000000]: enum myfunction1 + + index address name + 2ab 102cb4e : MyFunction1 + + +``` + +Now use symopt -2 to make symbol decorations visible, and then use the **addr** command with the address of this symbol: + +``` +mysymbols [1000000]: symopt -2 + +Symbol Options: 0x14c13 +Symbol Options: 0x14c11 + +mysymbols [1000000]: addr 102cb4e + +_MyFunction1@4 + name : _InterlockedIncrement@4 + addr : 102cb4e + size : 0 + flags : 0 + type : 0 +modbase : 1000000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagPublicSymbol (a) + index : 2ab +``` + +This reveals that the decorated name of the symbol is **\_MyFunction1@4**. + +### Decoding Symbol Decorations + +The **undec** command can be used to reveal the meaning of C++ symbol decorations. In the following example, the decorations attached to ??\_C@\_03GGCAPAJC@Sep?$AA@ are decoded to indicate that it is a string: + +``` +dbh: undec ??_C@_03GGCAPAJC@Sep?$AA@ + +??_C@_03GGCAPAJC@Sep?$AA@ = +`string' +``` + +The following examples decode the decorations attached to three function names, revealing their prototypes: + +``` +dbh: undec ?gcontext@@3_KA + +?gcontext@@3_KA = +unsigned __int64 gcontext + + +dbh: undec ?pathcpy@@YGXPAGPBG1K@Z + +?pathcpy@@YGXPAGPBG1K@Z = +void __stdcall pathcpy(unsigned short *,unsigned short const *,unsigned short const *,unsigned long) + + +dbh: undec ?_set_new_handler@@YAP6AHI@ZP6AHI@Z@Z + +?_set_new_handler@@YAP6AHI@ZP6AHI@Z@Z = +int (__cdecl*__cdecl _set_new_handler(int (__cdecl*)(unsigned int)))(unsigned int) +``` + +The **undec** command does not display information about initial underscores, the prefix **\_\_imp\_**, or trailing "**@***address*" decorations, which are commonly found attached to function names. + +You can use the **undec** command with any string, not just the name of a symbol in the currently loaded module. + +### Sorting a List of Symbols by Address + +If you simply want a list of symbols, sorted in address order, you can run DBH in batch mode and pipe the results to a **sort** command. The address values typically begin in the 18th column of each line, so the following command sorts the results by address: + +``` +dbh -p:4672 enum mymodule!* | sort /+18 +``` + +### Displaying Source Line Information + +When you use a full symbol file, DBH can display source line information. This does not require access to any source files, since this information is stored in the symbol files themselves. + +Here, the **line** command displays the hexadecimal address of the binary instructions corresponding to the specified source line, and it displays the symbols associated with that line. (In this example, there are no symbols associated with the line.) + +``` +dbh [1000000]: line myprogram.cpp#767 + + file : e:\mydirectory\src\myprogram.cpp + line : 767 + addr : 1006191 + key : 0000000000000000 +disp : 0 +``` + +Here, the **srclines** command displays the object files associated with the specified source line: + +``` +dbh [1000000]: srclines myprogram.cpp 767 + +0x1006191: e:\mydirectory\objchk\amd64\myprogram.obj +line 767 e:\mydirectory\src\myprogram.cpp +``` + +Note that the output of **srclines** is similar to that of the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) debugger command. + +### Displaying a Data Type + +The **type** command can be used to display information about a data type. Here it displays data about the CMDPROC type: + +``` +dbh [1000000]: type CMDPROC + + name : CMDPROC + addr : 0 + size : 8 + flags : 0 + type : c +modbase : 1000000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagTypedef (11) + index : c +``` + +The value listed after "tag" specifies the nature of this data type. In this case, **SymTagTypedef** indicates that this type was defined using a **typedef** statement. + +### Using Imaginary Symbols + +The **add** command can add an imaginary symbol to the loaded module. The actual symbol file is not altered; only the image of that file in DBH's memory is changed. + +The **add** command can be useful if you wish to temporarily override which symbols are associated with a given address range. In the following example, a portion of the address range associated with **MyModule!main** is overridden by the imaginary symbol **MyModule!magic**. + +Here is how the module appears before the imaginary symbol is added. Note that the **main** function begins at 0x0042CC56, and has size 0x42B. So when the **addr** command is used with the address 0x0042CD10, it recognizes this address as lying within the boundaries of the **main** function: + +``` +pid:6040 mod:MyModule[400000]: enum timetest!ma* + + index address name + 1 42cc56 : main + 3 415810 : malloc + 5 415450 : mainCRTStartup + +pid:6040 mod:MyModule[400000]: addr 42cc56 + +main + name : main + addr : 42cc56 + size : 42b + flags : 0 + type : 2 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagFunction (5) + index : 1 + +pid:6040 mod:MyModule[400000]: addr 42cd10 + +main+ba + name : main + addr : 42cc56 + size : 42b + flags : 0 + type : 2 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagFunction (5) + index : 1 +``` + +Now the symbol **magic** is added at the address 0x0042CD00, with size 0x10 bytes. When the **enum** command is used, the high bit in the index is set, showing that this is an imaginary symbol: + +``` +pid:6040 mod:MyModule[400000]: add magic 42cd00 10 + + +pid:6040 mod:MyModule[400000]: enum timetest!ma* + + index address name + 1 42cc56 : main + 3 415810 : malloc + 5 415450 : mainCRTStartup + 80000001 42cd00 : magic +``` + +When the **addr** command is used, it looks for any symbols whose ranges include the specified address. Since this search begins with the specified address and runs backward, the address 0x004CD10 is now associated with **magic**. On the other hand, the address 0x004CD40 is still associated with **main**, because it lies outside the range of the **magic** symbol. Note also that the tag **SymTagCustom** indicates an imaginary symbol: + +``` +pid:6040 mod:MyModule[400000]: addr 42cd10 + +magic+10 + name : magic + addr : 42cd00 + size : 10 + flags : 1000 + type : 0 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagCustom (1a) + index : 80000001 + +pid:6040 mod:MyModule[400000]: addr 42cd40 + +main+ea + name : main + addr : 42cc56 + size : 42b + flags : 0 + type : 2 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagFunction (5) + index : 1 +``` + +Finally, the **del** command can delete the symbol **magic**, returning all the symbols to their original ranges: + +``` +pid:6040 mod:MyModule[400000]: del magic + + +pid:6040 mod:MyModule[400000]: enum timetest!ma* + + index address name + 1 42cc56 : main + 3 415810 : malloc + 5 415450 : mainCRTStartup +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Additional%20DBH%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/address-and-address-range-syntax.md b/windows-driver-docs-pr/debugger/address-and-address-range-syntax.md new file mode 100644 index 0000000000..9b3b7faf37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/address-and-address-range-syntax.md @@ -0,0 +1,158 @@ +--- +title: Address and Address Range Syntax +description: Address and Address Range Syntax +ms.assetid: 3d4f41f1-07ec-484d-a748-27fbbb9bd0b2 +--- + +# Address and Address Range Syntax + + +## + + +There are several ways to specify addresses in the debugger. + +Addresses are always *virtual addresses*, except when the documentation specifically indicates another kind of address. In user mode, the debugger interprets virtual addresses according to the page directory of the [current process](controlling-processes-and-threads.md). In kernel mode, the debugger interprets virtual addresses according to the page directory of the process that the [process context](changing-contexts.md#process-context) specifies. You can also directly set the *user-mode address context*. For more information about the user-mode address context, see [**.context (Set User-Mode Address Context)**](-context--set-user-mode-address-context-.md). + +### Address Modes and Segment Support + +On x86-based platforms, CDB and KD support the following addressing modes. These modes are distinguished by their prefixes. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixNameAddress types

%

flat

32-bit addresses (also 16-bit selectors that point to 32-bit segments) and 64-bit addresses on 64-bit systems.

&

virtual 86

Real-mode addresses. x86-based only.

#

plain

Real-mode addresses. x86-based only.

+ +  + +The difference between the plain and virtual 86 modes is that a plain 16-bit address uses the segment value as a selector and looks up the segment descriptor. But a virtual 86 address does not use selectors and instead maps directly into the lower 1 MB. + +If you access memory through an addressing mode that is not the current default mode, you can use the address mode prefixes to override the current address mode. + +### Address Arguments + +Address arguments specify the location of variables and functions. The following table explains the syntax and meaning of the various addresses that you can use in CDB and KD. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SyntaxMeaning

offset

The absolute address in virtual memory space, with a type that corresponds to the current execution mode. For example, if the current execution mode is 16 bit, the offset is 16 bit. If the execution mode is 32-bit segmented, the offset is 32-bit segmented.

&[[ segment:]] offset

The real address. x86-based and x64-based.

%segment:[[ offset]]

A segmented 32-bit or 64-bit address. x86-based and x64-based.

%[[ offset]]

An absolute address (32-bit or 64-bit) in virtual memory space. x86-based and x64-based.

name[[ +| ]] offset

A flat 32-bit or 64-bit address. name can be any symbol. offset specifies the offset. This offset can be whatever address mode its prefix indicates. No prefix specifies a default mode address. You can specify the offset as a positive (+) or negative (−) value.

+ +  + +Use the [**dg (Display Selector)**](dg--display-selector-.md) command to view segment descriptor information. + +In MASM expressions, you can also use the **poi** operator to dereference any pointer. For example, if the pointer at address 0x00123456 points to address location 0x00420000, the following two commands are equivalent. + +``` +0:000> dd 420000 +0:000> dd poi(123456) +``` + +In C++ expressions, pointers behave like pointers in C++. However, numbers are interpreted as integers. If you have to deference an actual number, you must cast it first, as the following example shows. + +``` +0:000> dd *( (long*) 0x123456 ) +``` + +Some [pseudo-registers](pseudo-register-syntax.md) also hold common addresses, such as the current program counter location. + +You can also indicate an address in an application by specifying the original source file name and line number. For more information about how to specify this information, see [Source Line Syntax](source-line-syntax.md). + +### Address Ranges + +You can specify an address range by a pair of addresses or by an address and object count. + +To specify a range by a pair of addresses, specify the starting address and the ending address. For example, the following example is a range of 8 bytes, beginning at the address 0x00001000. + +``` +0x00001000 0x00001007 +``` + +To specify an address range by an address and object count, specify an address argument, the letter L (uppercase or lowercase), and a value argument. The address specifies the starting address. The value specifies the number of objects to be examined or displayed. The size of the object depends on the command. For example, if the object size is 1 byte, the following example is a range of 8 bytes, beginning at the address 0x00001000. + +``` +0x00001000 L8 +``` + +However, if the object size is a double word (32 bits or 4 bytes), the following two ranges each give an 8-byte range. + +``` +0x00001000 0x00001007 +0x00001000 L2 +``` + +There are two other ways to specify the value (the **L***Size* range specifier): + +- **L?** *Size* (with a question mark) means the same as **L***Size*, except that **L?** *Size* removes the debugger's automatic range limit. Typically, there is a range limit of 256 MB, because larger ranges are typographic errors. If you want to specify a range that is larger than 256 MB, you must use the **L?** *Size* syntax. + +- **L-** *Size* (with a hyphen) specifies a range of length *Size* that ends at the given address. For example, **80000000 L20** specifies the range from 0x80000000 through 0x8000001F, and **80000000 L-20** specifies the range from 0x7FFFFFE0 through 0x7FFFFFFF. + +Some commands that ask for address ranges accept a single address as the argument. In this situation, the command uses some default object count to compute the size of the range. Typically, commands for which the address range is the final parameter permit this syntax. For the exact syntax and the default range size for each command, see the reference topics for each command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Address%20and%20Address%20Range%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/adplus.md b/windows-driver-docs-pr/debugger/adplus.md new file mode 100644 index 0000000000..600598fe4d --- /dev/null +++ b/windows-driver-docs-pr/debugger/adplus.md @@ -0,0 +1,42 @@ +--- +title: ADPlus +description: This topic covers ADPlus +ms.assetid: f0ac9322-3728-42ef-87a4-5b6d25a282d1 +keywords: ADPlus, dump file, adplus.vbs, Autodump+ +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ADPlus + + +## + + +ADPlus V7.0 is a total rewrite of ADPlus. ADPlus V7.0 is written in managed code, which allows us to easily add new features. ADPlus.exe keeps the basic functionality of ADPlus.vbs and adds some additional features. Also, there is a new companion called ADPlusManager, which extends ADPlus to a distributed environment like an HPC computer cluster. + +## Where to get ADPlus + + +ADPlus is included in [Debugging Tools for Windows](index.md). + +For ADPlus V7.0 documentation, see adplus.doc in the installation folder for Debugging Tools for Windows. + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ADPlus%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/advanced-remote-debugging-scenarios.md b/windows-driver-docs-pr/debugger/advanced-remote-debugging-scenarios.md new file mode 100644 index 0000000000..1838774a6c --- /dev/null +++ b/windows-driver-docs-pr/debugger/advanced-remote-debugging-scenarios.md @@ -0,0 +1,35 @@ +--- +title: Advanced Remote Debugging Scenarios +description: Advanced Remote Debugging Scenarios +ms.assetid: 9f0e3b01-9ec2-44aa-a6bf-0216ed5aaaa8 +keywords: ["remote debugging, advanced"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Advanced Remote Debugging Scenarios + + +## + + +This section includes: + +[Debugging Targets on Multiple Computers](debugging-targets-on-multiple-computers.md) + +[Symbols in the Middle](symbols-in-the-middle.md) + +[Two Firewalls](two-firewalls.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Advanced%20Remote%20Debugging%20Scenarios%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/advanced-symsrv-use.md b/windows-driver-docs-pr/debugger/advanced-symsrv-use.md new file mode 100644 index 0000000000..13df494f8c --- /dev/null +++ b/windows-driver-docs-pr/debugger/advanced-symsrv-use.md @@ -0,0 +1,212 @@ +--- +title: Advanced SymSrv Use +description: Advanced SymSrv Use +ms.assetid: 16d4dda0-4bcf-4450-9972-e20d71efc845 +keywords: ["SymSrv, features", "caching symbols", "symbol servers, caching", "symbols, caching", "symbol servers, downstream store", "downstream store (symbol server)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Advanced SymSrv Use + + +SymSrv can deliver symbol files from a centralized symbol store. This store can contain any number of symbol files, corresponding to any number of programs or operating systems. The store can also contain binary files (this is useful when debugging minidumps). + +The store can contain the actual symbol and binary files, or it can simply contain pointers to symbol files. If the store contains pointers, SymSrv will retrieve the actual files directly from their sources. + +SymSrv can also be used to separate a large symbol store into a smaller subset that is appropriate for a specialized debugging task. + +Finally, SymSrv can obtain symbol files from an HTTP or HTTPS source using the logon information provided by the operating system. SymSrv supports HTTPS sites protected by smartcards, certificates, and regular logins and passwords. For more information, see [HTTP Symbol Stores](http-symbol-stores.md). + +### Setting the Symbol Path + +To use this symbol server, symsrv.dll must be installed in the same directory as the debugger. The symbol path can be set as shown here: + +``` +set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share + +set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share + +set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share + +set _NT_SYMBOL_PATH = srv*\\Server\Share +``` + +The parts of this syntax are explained as follows: + + **symsrv** +This keyword must always appear first. It indicates to the debugger that this item is a symbol server, not just a normal symbol directory. + +*ServerDLL* +Specifies the name of the symbol server DLL. If you are using the SymSrv symbol server, this will always be symsrv.dll. + +**srv** +This is shorthand for **symsrv\*symsrv.dll**. + +*DownstreamStore* +Specifies the downstream store. This is a local directory or network share that will be used to cache individual symbol files. + +You can specify more than one downstream store, separated by asterisks. Multiple downstream stores are explained in **Cascading Downstream Stores** further down on this page. + +If you include two asterisks in a row where a downstream store would normally be specified, then the default downstream store is used. This store will be located in the sym subdirectory of the home directory. The home directory defaults to the debugger installation directory; this can be changed by using the [**!homedir**](-homedir.md) extension or by setting the DBGHELP\_HOMEDIR environment variable. + +If *DownstreamStore* specifies a directory that does not exist, SymStore will attempt to create it. + +If the *DownstreamStore* parameter is omitted and no extra asterisk is included -- in other words, if you use **srv** with exactly one asterisk or **symsrv** with exactly two asterisks -- then no downstream store will be created. The debugger will load all symbol files directly from the server, without caching them locally. + +**Note**   If you are accessing symbols from an HTTP or HTTPS site, or if the symbol store uses compressed files, a downstream store is always used. If no downstream store is specified, one will be created in the sym subdirectory of the home directory. + +  + +*\\\\Server\\Share* +Specifies the server and share of the remote symbol store. + +If a downstream store is used, the debugger will first look for a symbol file in this store. If the symbol file is not found, the debugger will locate the symbol file from the specified *Server* and *Share*, and then cache a copy of this file in the downstream store. The file will be copied to a subdirectory in the tree under *DownstreamStore* which corresponds to its location in the tree under *\\\\Server\\Share*. + +The symbol server does not have to be the only entry in the symbol path. If the symbol path consists of multiple entries, the debugger checks each entry for the needed symbol files, in order (from left to right), regardless of whether a symbol server or an actual directory is named. + +Here are some examples. To use SymSrv as the symbol server with a symbol store on \\\\mybuilds\\mysymbols, set the following symbol path: + +``` +set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\mybuilds\mysymbols +``` + +To set the symbol path so that the debugger will copy symbol files from a symbol store on \\\\mybuilds\\mysymbols to your local directory c:\\localsymbols, use: + +``` +set _NT_SYMBOL_PATH=symsrv*symsrv.dll*c:\localsymbols*\\mybuilds\mysymbols +``` + +To set the symbol path so that the debugger will copy symbol files from the HTTP site www.company.com/manysymbols to a local network directory \\\\localserver\\myshare\\mycache, use: + +``` +set _NT_SYMBOL_PATH=symsrv*symsrv.dll*\\localserver\myshare\mycache*http://www.company.com/manysymbols +``` + +This last example can also be shortened as such: + +``` +set _NT_SYMBOL_PATH=srv*\\localserver\myshare\mycache*http://www.company.com/manysymbols +``` + +In addition, the symbol path can contain several directories or symbol servers, separated by semicolons. This allows you to locate symbols from multiple locations (or even multiple symbol servers). If a binary has a mismatched symbol file, the debugger cannot locate it using the symbol server because it checks only for the exact parameters. However, the debugger may find a mismatched symbol file with the correct name, using the traditional symbol path, and successfully load it. Even though the file is technically not the correct symbol file, it might provide useful information. + +### Compressed Files + +SymSrv is compatible with symbol stores that contain compressed files, as long as this compression has been done with the compress.exe tool, which is available [here](http://go.microsoft.com/fwlink/p/?linkid=239917). Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd\_ or module2.db\_). For details, see [SymStore](symstore.md). + +If the files on the store are compressed, you must use a downstream store. SymSrv will uncompress all files before caching them on the downstream store. + +### Deleting the Cache + +If you are using a *DownstreamStore* as a cache, you can delete this directory at any time to save disk space. + +It is possible to have a vast symbol store that includes symbol files for many different programs or Windows versions. If you upgrade the version of Windows used on your target computer, the cached symbol files will all match the earlier version. These cached files will not be of any further use, and therefore this might be a good time to delete the cache. + +### Cascading Downstream Stores + +You can specify any number of downstream stores, separated by asterisks. These stores are known as *cascading symbol stores*. + +After the initial **srv\*** or **symsrv\****ServerDLL***\***, each subsequent token represents a symbol location. The token furthest left is checked first. An empty token -- indicated by two asterisks in a row, or by an asterisk at the end of the string -- represents the default downstream store. + +Here is an example of a symbol path that uses two downstream stores to hold information from the main symbol store being accessed. These could be called the master store, the mid-level store, and the local cache: + +``` +srv*c:\localcache*\\interim\store*https://msdl.microsoft.com/download/symbols +``` + +In this scenario, SymSrv will first look in c:\\localcache for a symbol file. If it is found there, it will return a path to it. If it is not found there, it will look in \\\\interim\\store. If the symbol file is found there, SymSrv will copy it to c:\\localcache and return the path. If it is not found there, SymSrv will look in the [Microsoft public symbol store](microsoft-public-symbols.md) at https://msdl.microsoft.com/download/symbols; if the file is found there, SymSrv will copy it to both \\\\interim\\store and c:\\localcache. + +A similar behavior would be obtained by using the following path: + +``` +srv**\\interim\store*http://internetsite +``` + +In this case, the local cache is the default downstream store and the master store is an internet site. A mid-level store of \\\\interim\\store has been specified for use in between the other two. + +When SymSrv processes a path that contains cascading stores, it will skip any store that it cannot read or write to. So if a share goes down, it will copy the file to the store downstream from the missing store without any error. A nice side effect of this error is that the user can specify more than one master store that feeds a single stream of downstream stores as long as the master stores are not writable. + +When a compressed symbol file is retrieved from the master store, it will be stored in compressed form in any mid-level store. The file will be uncompressed in the bottom-most store in the path. + +### Working With HTTP and SMB Symbol Server Paths + +As previously discussed, chaining (or cascading) refers to the copy that occurs between each “\*” separator in the symbol path. The symbols are searched for in a left-to-right order. On each miss, the next (upstream) symbol server is queried, until the file is found. + +If found, the file is copied from the (upstream) symbol server to the previous (downstream) symbol server. This is repeated for each (downstream) symbol server. In this way, the (shared) downstream symbol servers are populated with the collective efforts of all clients using the symbol servers. + +Even though chained UNC paths can be used without the SRV\* prefix, we recommend that SRV\* be specified so that the advanced error handling of symsrv.dll be used. + +When including a HTTP symbol server in the path, only one can be specified (per chain), and it must be at the end of the path (as it can’t be written to serve as a cache). If an HTTP-based symbol store was located in the middle or the left of the store list, it would not be possible to copy any found files to it and the chain would be broken. Furthermore, because the symbol handler cannot open a file from a web site, an HTTP-based store should not be the leftmost or only store on the list. If SymSrv is ever presented with this symbol path, it will attempt to recover by copying the file to the default downstream store and open it from there, regardless of whether the default downstream store is indicated in the symbol path or not. + +HTTP is only supported when using the SRV\* prefix (implemented by the symsrv.dll symbol handler). + +**Example HTTP and SMB Share Symbol Server Scenarios** + +A common UNC-only deployment involves a central office hosting all of the files (\\\\MainOffice\\Symbols), branch offices caching a subset (\\\\BranchOfficeA\\Symbols), and desktops (C:\\Symbols) caching the files that they reference. + +``` +srv*C:\Symbols*\\BranchOfficeA\Symbols*\\MainOffice\Symbols +``` + +When the SMB share is the primary (upstream) symbol store, Read is required. + +``` +srv*C:\Symbols*\\MachineName\Symbols +``` + +When the SMB share is an intermediate (downstream) symbol store, Read/Change is required. The client will copy the file from the primary symbol store to the SMB share, and then from the SMB share to the local folder. + +``` +srv*C:\Symbols*\\MachineName\Symbols*https://msdl.microsoft.com/download/symbols +srv*C:\Symbols*\\MachineName\Symbols*\\MainOffice\Symbols +``` + +When the SMB share is an intermediate (downstream) symbol store in a SymProxy deployment, only Read is required. The SymProxy ISAPI Filter will perform the writes, not the client. + +``` +srv*C:\Symbols*\\MachineName\Symbols*https://SymProxyName/Symbols +``` + +**Multiple HTTP and SMB Share Symbol Server Cache Scenarios** + +It is possible to specify multiple chains of symbol servers and cache locations, separated by a semi colon “;”. If the symbols are located in the first chain, the second chain is not traversed. If the symbols are not located in the first chain, the second chain will be traversed and if the symbols are located in the second chain, they will be cached in the specified location. This approach will allow a primary symbol server to normally be used, with a secondary server only being used, if the symbols are not available on the primary symbol server specified in the first chain. + +``` +srv*C:\Symbols*\\Machine1\Symbols*http://SymProxyName/Symbols;srv*C:\WebSymbols* https://msdl.microsoft.com/download/symbols +``` + +### cache\**localsymbolcache* + +Another way to create a local cache of symbols is by using the **cache\****localsymbolcache* string in your symbol path. This is not part of the symbol server element, but a separate element in your symbol path. The debugger will use the specified directory *localsymbolcache* to store any symbols loaded from any element that appears in your symbol path to the right of this string. This allows you to use a local cache for symbols downloaded from any location, not just those downloaded by a symbol server. + +For example, the following symbol path will not cache symbols taken from *\\\\someshare*. It will use c:\\mysymbols to cache symbols taken from *\\\\anothershare*, because the element beginning with *\\\\anothershare* appears to the right of the **cache\*c:\\mysymbols** element. It will also use c:\\mysymbols to cache symbols taken from the Microsoft public symbol store, because of the usual syntax used by the symbol server (**srv** with two or more asterisks). Moreover, if you subsequently use the [**.sympath+**](-sympath--set-symbol-path-.md) command to add additional locations to this path, these new elements will also be cached, since they will be appended to the right side of the path. + +``` +_NT_SYMBOL_PATH=\\someshare\that\cachestar\ignores;srv*c:\mysymbols*https://msdl.microsoft.com/download/symbols;cache*c:\mysymbols;\\anothershare\that\gets\cached +``` + +### How SymSrv Locates Files + +SymSrv creates a fully qualified UNC path to the desired symbol file. This path begins with the path to the symbol store recorded in the \_NT\_SYMBOL\_PATH environment variable. The **SymbolServer** routine is then used to identify the name of the desired file; this name is appended to the path as a directory name. Another directory name, consisting of the concatenation of the *id*, *two*, and *three* parameters passed to **SymbolServer**, is then appended. If any of these values is zero, they are omitted. + +The resulting directory is searched for the symbol file, or a symbol store pointer file. + +If this search is successful, **SymbolServer** passes the path to the caller and returns **TRUE**. If the file is not found, **SymbolServer** returns **FALSE**. + +### Using AgeStore to Reduce the Cache Size + +The AgeStore tool can be used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. This can be useful if your downstream store is too large. For details, see [AgeStore](agestore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Advanced%20SymSrv%20Use%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/agestore-command-line-options.md b/windows-driver-docs-pr/debugger/agestore-command-line-options.md new file mode 100644 index 0000000000..3c0772d328 --- /dev/null +++ b/windows-driver-docs-pr/debugger/agestore-command-line-options.md @@ -0,0 +1,87 @@ +--- +title: AgeStore Command-Line Options +description: The AgeStore command line uses the following syntax. The parameters can be included in any order. +ms.assetid: ae6ad504-a582-45ac-89a1-7e90952948b4 +keywords: ["AgeStore Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- AgeStore Command-Line Options +api_type: +- NA +--- + +# AgeStore Command-Line Options + + +The AgeStore command line uses the following syntax. The parameters can be included in any order. + +``` +agestore [PathSpec] -date=Month-Day-Year Options + +agestore [PathSpec] -days=NumberOfDays Options + +agestore [PathSpec] -size=SizeRemaining Options + +agestore [PathSpec] -size Options + +agestore -? +``` + +## Parameters + + + *PathSpec* +Specifies the target directory in which files are to be deleted. If the -s option is used, *PathSpec* specifies the root directory of the target tree in which files are to be deleted. *PathSpec* may be the absolute or relative path of a directory on the local computer, or a UNC path. If *PathSpec* contains spaces, it must be enclosed in quotation marks. If *PathSpec* is omitted, AgeStore uses the current working directory. + +**-date=***Month-Day-Year* +Specifies the cutoff date for deleting files. All files that were last accessed prior to the specified date will be deleted. The date must be specified in the format Month-Day-Year, with hyphens between the month and day and between the day and the year. Leading zeros in *Month* and *Day* are optional. The year can be specified with two digits or four. Thus you can indicate the date of January 5, 2008 as 01-05-2008 or 1-5-08. + + **-days=***NumberOfDays* +Specifies the cutoff date and time for deleting files. All files that were last accessed prior to the specified number of days ago will be deleted. *NumberOfDays* specifies an integer number of 24-hour days. For example, if the specifier -days=3 is used at 6:00 PM on February 17, 2008, all files last accessed prior to 6:00 PM on February 14, 2008 will be deleted. + + **-size=***SizeRemaining* +Specifies the total size of the files that should remain after the deletion, in bytes. When this switch is used, AgeStore deletes files in the target directory or target tree, beginning with the files accessed least recently, until the total size of the remaining files is less than or equal to *SizeRemaining*. When the **-s** option is used, AgeStore targets an entire directory tree, and *SizeRemaining* specifies the total size of files that should remain in this entire directory tree after deletion. + + **-size** +Causes AgeStore to list the total size of all files in the target directory or target tree. No files are deleted. + + *Options* +Any combination of the following options. + +**-l** +Causes AgeStore not to delete any files, but merely to list all the files that would be deleted if this same command were run without the **-l** option. + +**-s** +Causes AgeStore to treat the entire directory tree subordinate to *PathSpec* as the target. When the **-s** option is not used, the directory specified by *PathSpec* becomes the target directory in which files will be deleted. When the **-s** option is used, the directory specified by *PathSpec* and all subdirectories under it become the target tree in which files will be deleted. + +**-k** +Causes AgeStore to keep any empty subdirectories. If this option is not used, AgeStore deletes the target directory if it is completely empty after the command runs. If the **-s** option is used without the **-k** option, all empty directories in the target directory tree will be deleted after AgeStore has completed its file deletion -- even the root directory itself, if it becomes empty. If there are directories in this tree that happen to be already empty before AgeStore runs, AgeStore deletes these directories as well. However, if the AgeStore command results in no file deletion (for example, if the **-size=***SizeRemaining* parameter specifies a size larger than the total size of all files in the target tree), empty directories are not deleted. If the **-s** option is not used, empty directories are never deleted, and the **-k** option is ignored. + +**-q** +Quiet mode. If this option is not included, AgeStore lists all files as they are deleted. + +**-y** +Suppresses the **(y/n)** prompt. If this option is not used, AgeStore prompts you with an "Are you sure?" prompt before deleting any files. + + **-?** +Displays help text for the AgeStore command line. + +### Additional Information + +For more information about the AgeStore tool, see [Using AgeStore](using-agestore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20AgeStore%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/agestore.md b/windows-driver-docs-pr/debugger/agestore.md new file mode 100644 index 0000000000..d63cf6311e --- /dev/null +++ b/windows-driver-docs-pr/debugger/agestore.md @@ -0,0 +1,32 @@ +--- +title: AgeStore +description: AgeStore +ms.assetid: 000b0f14-04e9-49fd-825c-8e1fd499494f +keywords: ["AgeStore", "AgeStore, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# AgeStore + + +The AgeStore tool (agestore.exe) deletes files in a directory or directory tree, based on their last access dates. This program is particularly useful for removing old files from the downstream store used by a symbol server, in order to conserve disk space. + +This section includes: + +[Using AgeStore](using-agestore.md) + +[**AgeStore Command-Line Options**](agestore-command-line-options.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20AgeStore%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ah--assertion-handling-.md b/windows-driver-docs-pr/debugger/ah--assertion-handling-.md new file mode 100644 index 0000000000..6e2a4d0aa8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ah--assertion-handling-.md @@ -0,0 +1,101 @@ +--- +title: ah (Assertion Handling) +description: The ah command controls the assertion handling status for specific addresses. +ms.assetid: a55aa34f-c861-45de-bacf-92549ab98fdc +keywords: ["ah (Assertion Handling) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ah (Assertion Handling) +api_type: +- NA +--- + +# ah (Assertion Handling) + + +The **ah** command controls the assertion handling status for specific addresses. + +``` +ahb [Address] +ahi [Address] +ahd [Address] +ahc +ah +``` + +## Parameters + + + **ahb** +Breaks into the debugger if an assertion fails at the specified address. + + **ahi** +Ignores an assertion failure at the specified address. + + **ahd** +Deletes any assertion-handling information at the specified address. This deletion causes the debugger to return to its default state for that address. + + *Address* +Specifies the address of the instruction whose assertion-handling status is being set. If you omit this parameter, the debugger uses the current program counter. + + **ahc** +Deletes all assertion-handling information for the current process. + + **ah** +Displays the current assertion-handling settings. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about break status and handling status, descriptions of all event codes, a list of the default status for all events, and details about other methods of controlling this status, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +Remarks +------- + +The **ah\*** command controls the assertion handling status for a specific address. The [**sx\* asrt**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) command controls the global assertion handling status. If you use **ah\*** for a certain address and then an assert occurs there, the debugger responds based on the **ah\*** settings and ignores the **sx\* asrt** settings. + +When the debugger encounters an assertion, the debugger first checks whether handling has been configured for that specific address. If you have not configured the handling, the debugger uses the global setting. + +The **ah\*** command affects only the current process. When the current process ends, all status settings are lost. + +Assertion handling status affects only STATUS\_ASSERTION\_EXCEPTION exceptions. This handling does not affect the kernel-mode ASSERT routine. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ah%20%28Assertion%20Handling%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/al--list-aliases-.md b/windows-driver-docs-pr/debugger/al--list-aliases-.md new file mode 100644 index 0000000000..d2304319c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/al--list-aliases-.md @@ -0,0 +1,73 @@ +--- +title: al (List Aliases) +description: The al command displays a list of all currently defined user-named aliases. +ms.assetid: 40e20edb-4545-4c5a-bb56-61e00b064efc +keywords: ["al (List Aliases) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- al (List Aliases) +api_type: +- NA +--- + +# al (List Aliases) + + +The **al** command displays a list of all currently defined user-named aliases. + +``` +al +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to use aliases, see [Using Aliases](using-aliases.md). + +Remarks +------- + +The **al** command lists all user-named aliases. But this command does not list fixed-name aliases ($u0 to $u9). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20al%20%28List%20Aliases%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/aml-debugging-examples.md b/windows-driver-docs-pr/debugger/aml-debugging-examples.md new file mode 100644 index 0000000000..a746437ac9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/aml-debugging-examples.md @@ -0,0 +1,217 @@ +--- +title: AML Debugging Examples +description: AML Debugging Examples +ms.assetid: 3a9f760f-f511-412f-aca0-3c415b3e5dc2 +keywords: ["AMLI Debugger, debugging examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# AML Debugging Examples + + +## + + +Here are examples that illustrate how to get started with AML debugging. + +### Investigating a Frozen Computer + +If the target computer has frozen and you suspect it may be an ACPI problem, begin by using the [**!amli lc**](-amli-lc.md) extension to display all the active contexts: + +``` +kd> !amli lc +*Ctxt=ffffffff8128d000, ThID=ffffffff81277880, Flgs=----R----, pbOp=ffffffff8124206c, Obj=\_SB.PCI0.ISA0.FDC0._CRS +``` + +If no contexts are displayed, the error is probably not ACPI-related. + +If there are contexts shown, look for the one marked with an asterisk. This is the *current context* (the one that is being executed by the interpreter at the present moment). + +In this example, the target computer is running Windows XP or Windows Server 2003 on a 32-bit processor. Therefore all addresses are cast to 64 bits, producing a gratuitous FFFFFFFF in the high 32 bits. The abbreviation **pbOp** indicates the instruction pointer ("pointer to binary op codes"). The **Obj** field gives the full path and name of the method as it appears in the ACPI tables. For a description of the flags, see [**!amli lc**](-amli-lc.md). + +You can use the [**!amli u**](-amli-u.md) command to disassemble the \_CRS method as follows: + +``` +kd> !amli u \_SB.PCI0.ISA0.FDC0._CRS + +ffffffff80e4a535 : CreateDWordFieldCRES, 0x76, RAMT) +ffffffff80e4a540 : CreateDWordField(CRES, 0x82, PCIT) +ffffffff80e4a54b : Add(MLEN(), 0x100000, RAMT) +ffffffff80e4a559 : Subtract(0xffe00000, RAMT, PCIT) +ffffffff80e4a567 : Return(CRES) +``` + +### Breaking Into the AMLI Debugger + +The [**!amli debugger**](-amli-debugger.md) command causes the AML interpreter to break into the AMLI Debugger the next time any AML code is executed. + +After the AMLI Debugger prompt appears, you can use any of the AMLI Debugger commands. You can also use **!amli** extension commands without prefixing them with "!amli": + +``` +kd> !amli debugger +kd> g + +AMLI(? for help)-> find _crs +\_SB.LNKA._CRS +\_SB.LNKB._CRS +\_SB.LNKC._CRS +\_SB.LNKD._CRS +\_SB.PCI0._CRS +\_SB.PCI0.LPC.NCP._CRS +\_SB.PCI0.LPC.PIC._CRS +\_SB.PCI0.LPC.TIME._CRS +\_SB.PCI0.LPC.IDMA._CRS +\_SB.PCI0.LPC.RTC._CRS +\_SB.PCI0.LPC.SPKR._CRS +\_SB.PCI0.LPC.FHUB._CRS +\_SB.PCI0.SBD1._CRS +\_SB.PCI0.SBD2._CRS +\_SB.MBRD._CRS + +AMLI(? for help)-> u \_SB.PCI0._CRS + +ffffffff80e4a535 : CreateDWordFieldCRES, 0x76, RAMT) +ffffffff80e4a540 : CreateDWordField(CRES, 0x82, PCIT) +ffffffff80e4a54b : Add(MLEN(), 0x100000, RAMT) +ffffffff80e4a559 : Subtract(0xffe00000, RAMT, PCIT) +ffffffff80e4a567 : Return(CRES) +``` + +### Using Breakpoints + +In the following example, you will break into the AMLI Debugger before the method \_BST is executed. + +Even if you have located a \_BST object, you should verify that it is indeed a method. You can use the [**!amli dns**](-amli-dns.md) extension to do this. + +``` +kd> !amli dns /s \_sb.pci0.isa.bat1._bst + +ACPI Name Space: \_SB.PCI0.ISA.BAT1._BST (c29c2044) +Method(_BST:Flags=0x0,CodeBuff=c29c20a5,Len=103) +``` + +Now you can use the [**!amli bp**](-amli-bp.md) command to place the breakpoint: + +``` +kd> !amli bp \_sb.pci0.isa.bat1._bst +``` + +You may also want to place breakpoints within the method. You could use the [**!amli u**](-amli-u.md) command to disassemble \_BST and then place a breakpoint on one of its steps: + +``` +kd> !amli u _sb.pci0.isa.bat1._bst + +ffffffffc29c20a5: Acquire(\_SB_.PCI0.ISA_.EC0_.MUT1, 0xffff) +ffffffffc29c20c0: Store("CMBatt - _BST.BAT1", Debug) +ffffffffc29c20d7: \_SB_.PCI0.ISA_.EC0_.CPOL() +ffffffffc29c20ee: Release(\_SB_.PCI0.ISA_.EC0_.MUT1) +ffffffffc29c2107: Return(PBST) + +kd> !amli bp c29c20ee +``` + +### Responding to a Triggered Breakpoint + +In the following example, the method \_WAK is running and then encounters a breakpoint: + +``` +Running \_WAK method +Hit Breakpoint 0. +``` + +Use the [**!amli ln**](-amli-ln.md) extension to see the nearest method to the current program counter. The following example is taken from a Windows 2000 system, so the addresses are shown in 32-bit form: + +``` +kd> !amli ln +c29accf5: \_WAK +``` + +The [**!amli lc**](-amli-lc.md) extension displays all the active contexts: + +``` +kd> !amli lc + Ctxt=c18b6000, ThID=00000000, Flgs=A-QC-W----, pbOp=c29bf8fe, Obj=\_SB.PCI0.ISA.EC0._Q09 +*Ctxt=c18b4000, ThID=c15a6618, Flgs=----R-----, pbOp=c29accf5, Obj=\_WAK +``` + +This shows that the active contexts are associated with the methods \_Q09 and \_WAK. The current context is \_WAK. + +Now you can use the [**!amli r**](-amli-r.md) command to display more details about the current context. From this you can see useful thread and stack information, as well as arguments passed to \_WAK and the local data objects. + +``` +kd> !amli r +Context=c18b4000*, Queue=00000000, ResList=00000000 +ThreadID=c15a6618, Flags=00000010 +StackTop=c18b5eec, UsedStackSize=276 bytes, FreeStackSize=7636 bytes +LocalHeap=c18b40c0, CurrentHeap=c18b40c0, UsedHeapSize=88 bytes +Object=\_WAK, Scope=\_WAK, ObjectOwner=c18b4108, SyncLevel=0 +AsyncCallBack=ff06b5d0, CallBackData=0, CallBackContext=c99efddc + +MethodObject=\_WAK +c18b40e4: Arg0=Integer(:Value=0x00000001[1]) +c18b5f3c: Local0=Unknown() +c18b5f54: Local1=Unknown() +c18b5f6c: Local2=Unknown() +c18b5f84: Local3=Unknown() +c18b5f9c: Local4=Unknown() +c18b5fb4: Local5=Unknown() +c18b5fcc: Local6=Unknown() +c18b5fe4: Local7=Unknown() +c18b4040: RetObj=Unknown() +``` + +### Tracing, Stepping, and Running AML Code + +If you want to trace through the code, you can turn on full tracing information by using the [**!amli set**](-amli-set.md) extension as follows: + +``` +kd> !amli set spewon verboseon traceon +``` + +Now you can step through the AML code, watching the code execute line by line. The **p** command steps over any function calls. The **t** command will step into function calls. + +``` +AMLI(? for help)-> p + +c29bfcb7: Store(\_SB_.PCI0.ISA_.ACAD.CHAC(SEL0=0x10e1) +c29c17b1: { +c29c17b1: | Store(LGreater(And(Arg0=0x10e1,0xf0,)=0xe0,0x80)=0xffffffff,Local0)=0xffffffff + +AMLI(? for help)-> p + +c29c17bb: | If(LNot(LEqual(Local0=0xffffffff,ACP_=0xffffffff)=0xffffffff)=0x0) +c29c17ce: | { +c29c17ce: | | Return(Zero) +c29c17d0: | } +c29c17d0: },Local1)=0x0 + +AMLI(? for help)-> t + +c29bfcd4: Store(\_SB_.PCI0.ISA_.BAT1.CHBP(SEL0=0x10e1) +c29c293d: { +c29c293d: | Store("CMBatt - CHBP.BAT1",Debug)String(:Str="CMBatt - CHBP.BAT1")="CMBatt - CHBP.BAT1" +``` + +You may also run methods from within the AMLI Debugger if you choose. For example, you might evaluate the status of the LNKA device by running its control method \_STA: + +``` +AMLI(? for help)-> run \_sb.lnka._sta +PCI OpRegion Access on region c29b2268 device c29b2120 + +\_SB.LNKA._STA completed successfully with object data: +Integer(:Value=0x0000000b[11]) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20AML%20Debugging%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyze-a-running-process.md b/windows-driver-docs-pr/debugger/analyze-a-running-process.md new file mode 100644 index 0000000000..a139322042 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyze-a-running-process.md @@ -0,0 +1,78 @@ +--- +title: Analyze a Running Process +description: Use the following commands to record and analyze the heap memory allocations in a running process. This analysis focuses on stack traces. +ms.assetid: 65a8b510-f5f1-4622-87ff-b44d5855787d +keywords: ["Analyze a Running Process Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Analyze a Running Process +api_type: +- NA +--- + +# Analyze a Running Process + + +Use the following commands to record and analyze the heap memory allocations in a running process. This analysis focuses on stack traces. + +``` +umdh -p:PID [-f:LogFile] [-v[:MsgFile]] | [-g] | [-h] +``` + +## Parameters + + + **-p:***PID* +Specifies the process to analyze. *PID* is the process ID of the process. This parameter is required. + +To find the PID of a running process, use Task Manager, Tasklist (Windows XP and later operating systems), or [TList](tlist.md). + + **-f:***LogFile* +Saves the log contents in a text file. By default, UMDH writes the log to stdout (command window). + +*LogFile* specifies the path (optional) and name of the file. If you specify an existing file, UMDH overwrites the file. + +**Note**   If UMDH was not started in Administrator mode, or attempts to write to "protected" paths, it will be denied access. + +  + + **-v\[:***MsgFile***\]** +Verbose mode. Generates detailed informational and error messages. By default, UMDH writes these messages to stderr. + +*MsgFile* specifies the path (optional) and name of a text file. When you use this variable, UMDH writes the verbose messages to the specified file, instead of to stderr. If you specify an existing file, UMDH overwrites the file. + + **-g** +Logs the heap blocks that are not referenced by the process ("garbage collection"). + + **-h** +Displays help. + +### Comments + +On Windows 2000, if UMDH is reporting errors finding the stack trace database, and you have enabled the **Create user mode stack trace database** option in [GFlags](gflags.md), you might have a symbol file conflict. To resolve it, copy the DBG and PDB symbol files for the application to the same directory, and try again. + +### Sample Usage + +``` +umdh -? +umdh -p:2230 +umdh -p:2230 -f:dump_allocations.txt +umdh -p:2230 -f:c:\Log1.txt -v:c:\Msg1.txt +umdh -p:2230 -g -f:garbage.txt +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyze%20a%20Running%20Process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyze-umdh-logs.md b/windows-driver-docs-pr/debugger/analyze-umdh-logs.md new file mode 100644 index 0000000000..35041f06fe --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyze-umdh-logs.md @@ -0,0 +1,75 @@ +--- +title: Analyze UMDH Logs +description: Use the following commands to analyze User-Mode Dump Heap (UMDH) logs that were created by running UMDH with the syntax described in Analyze a Running Process. +ms.assetid: 66e559b2-0335-4a1d-ba6c-dde6b826dc5f +keywords: ["Analyze UMDH Logs Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Analyze UMDH Logs +api_type: +- NA +--- + +# Analyze UMDH Logs + + +Use the following commands to analyze User-Mode Dump Heap (UMDH) logs that were created by running UMDH with the syntax described in [**Analyze a Running Process**](analyze-a-running-process.md). This analysis focuses on allocations, instead of stack traces. + +You can analyze a single log file or compare logs from different runs to detect the changes in the program or driver's memory dump allocations over time. + +``` +umdh [-d] [-v] [-l] File1 [File2] [-h | ?] +``` + +## Parameters + + + **-d** +Displays numeric data in decimal numbers. The default is hexadecimal. + + **-v** +Verbose mode. Includes the traces, as well as summary information. The traces are most helpful when analyzing a single log file. + + **-l** +Includes file names and line numbers in the log. (Please note that the parameter is the lowercased letter "L," not the number one.) + + *File1* \[*File2*\] +Specifies the UMDH log files to analyze. + +UMDH creates log files when you run it in the [**analyze a running process**](analyze-a-running-process.md) mode and save the log content in a text file (**-f**). + +When you specify one log file, UMDH analyzes the file and displays the function calls in each trace in descending order of bytes allocated. + +When you specify two log files, UMDH compares the files and displays in descending order the function calls whose allocations have grown the most between the two trials. + + **-h | ?** +Displays help. + +### Sample Usage + +``` +umdh dump.txt +umdh -d -v dump.txt +umdh dump1.txt dump2.txt +``` + +Remarks +------- + +Suppose you have two computers: a *logging computer* where you create a UMDH log and an *analysis computer* where you analyze the UMDH log. The symbol path on your analysis computer must point to the symbols for the version of Windows that was loaded on the logging computer at the time the log was made. Do not point the symbol path on the analysis computer to a symbol server. If you do, UMDH will retrieve symbols for the version of Windows that is running on the analysis computer, and UMDH will not display meaningful results. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyze%20UMDH%20Logs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-capture-stall.md b/windows-driver-docs-pr/debugger/analyzing-a-capture-stall.md new file mode 100644 index 0000000000..56b047c0ff --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-capture-stall.md @@ -0,0 +1,86 @@ +--- +title: Analyzing a Capture Stall +description: Analyzing a Capture Stall +ms.assetid: 9a88deba-374c-4ccc-8bb8-18e3b4124158 +keywords: ["kernel streaming debugging, blah"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Capture Stall + + +The following is an artificially created scenario that simulates a capture stall. This is a particularly valuable scenario since similar situations frequently occur in stress testing. The scenario is as follows: + +The Windows recording component Sndrec32 is recording from the primary capture device, in this case a Creative SBLive wave device. For a period of time, it records normally; however, the graph stalls at 8.50 seconds because we have explicitly caused portcls not to complete capture IRPs for purposes of this test. + +The application shows running, but the stream position is not advancing. Position is halted at 8.50 seconds. + +Since the primary capture device on this machine is a PCI sound card, first use the [**!ks.pciaudio**](-ks-pciaudio.md) command to try and determine a starting point. Use a flag value of 1 to request a display of all running streams: + +``` +kd> !pciaudio 1 + +1 Audio FDOs found: + Functional Device 8121c030 [\Driver\emu10k] + Wave Cyclic Streams: + Pin 812567c0 RUN [emu10k1m!CMiniportWaveCyclicStreamSBLive ff9ec7f8] +``` + +In this case, there is only one PCI audio device and it is serviced by the Intel emu10k driver (\\Driver\\emu10k). This driver currently has a single running stream (0x812567C0). Now you can use [**!ks.graph**](-ks-graph.md) to view the kernel graph. Set *Level* and *Flags* both to 7 to obtain maximum detail on the stall: + +``` +kd> !graph 812567c0 7 7 +Attempting a graph build on 812567c0... Please be patient... +Graph With Starting Point 812567c0: +"emu10k" Filter ff9ebb98, Child Factories 5 + Output Factory 0: + Pin 812567c0 (File 811c6630, -> "splitter" 811df960) Irps(q/p) = 8, 0 + Queued: 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98 +``` + +The above shows the details for factory 0. The emu10k output pin 0x812567C0 is connected to the splitter input pin 0x811DF960. There are eight IRPs queued to emu10k's output pin. The output from [**!ks.graph**](-ks-graph.md) continues as follows: + +``` +"splitter" Filter ffb18890, Child Factories 2 + Output Factory 0: + Pin 811df430 (File ffa55f90) Irps(q/p) = 10, 0 + Queued: ffadd008 ffa73b00 ffa1e998 811de310 ffa54370 ffaaf008 811dee70 81250e70 811de580 811de8c0 +``` + +There are ten IRPs queued to splitter's output pin. + +``` + Input Factory 1: + Pin 811df960 (File 81187820, <- "emu10k" 812567c0) Irps(q/p) = 0, 8 + Pending: 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98 +``` + +Splitter's input pin has no queued IRPs; however, it is waiting for the eight from emu10k to enter the queue. + +``` +Analyzing a Hung Graph From 812567c0: + +Suspect Filters (For a Hung Graph): + "emu10k" Filter ff9ebb98 or class "PortCls Wave Cyclic" is suspect. + Reasons For This Analysis: + - No critical pin has less than 8 queued Irps + - Downstream "splitter" pin 811df960 is starved + Irps to check: + 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98 +``` + +From this information, the analyzer suggests that either emu10k or WaveCyclic may be at fault. It also provides a list of the suspect IRPs; these are the IRPs that are queued to emu10k's input pin. If any of those IRPs were to complete, splitter would copy data and complete an IRP and the graph would progress. For some reason, emu10k is not completing those capture Irps. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Capture%20Stall%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kanalyze.md b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kanalyze.md new file mode 100644 index 0000000000..5ccd216265 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kanalyze.md @@ -0,0 +1,33 @@ +--- +title: Analyzing a Kernel-Mode Dump File with KAnalyze +description: Analyzing a Kernel-Mode Dump File with KAnalyze +ms.assetid: 647edb27-e9dc-4e6f-afa5-ea11c1c24e57 +keywords: ["dump file, KAnalyze", "KAnalyze", "OEM Support Tools, KAnalyze"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Kernel-Mode Dump File with KAnalyze + + +## + + +Kernel Memory Space Analyzer (KAnalyze, Kanalyze.exe) is another tool that can examine kernel-mode dump files. + +KAnalyze and its documentation are part of the OEM Support Tools package. + +To download these tools, go to [Microsoft Support Article 253066](http://go.microsoft.com/fwlink/p/?linkid=241339) and follow the instructions on that page. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Kernel-Mode%20Dump%20File%20with%20KAnalyze%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kd.md b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kd.md new file mode 100644 index 0000000000..023ecb32ad --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-kd.md @@ -0,0 +1,73 @@ +--- +title: Analyzing a Kernel-Mode Dump File with KD +description: Analyzing a Kernel-Mode Dump File with KD +ms.assetid: 7e8fbf6e-0adc-434c-ba93-f83f49a4af92 +keywords: ["KD, analyzing a dump file", "CAB file containing a dump file, analyzing kernel-mode dump file with KD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Kernel-Mode Dump File with KD + + +## + + +Kernel-mode memory dump files can be analyzed by KD. The processor or Windows version that the dump file was created on does not need to match the platform on which KD is being run. + +### Starting KD + +To analyze a dump file, start KD with the **-z** command-line option: + +**kd -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For a full list of options, see [**KD Command-Line Options**](kd-command-line-options.md). + +You can also open a dump file after the debugger is running by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed with [**g (Go)**](g--go-.md). + +It is possible to debug multiple dump files at the same time. This can be done by including multiple **-z** switches on the command line (each followed by a different file name), or by using [**.opendump**](-opendump--open-dump-file-.md) to add additional dump files as debugger targets. For information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file. + +It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the **-z** option or as the argument to an [**.opendump**](-opendump--open-dump-file-.md) command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will only be able to read one of them. The debugger will not read any additional files from the CAB, even if they were symbol files or other files associated with the dump file. + +### Analyzing the Dump File + +If you are analyzing a Kernel Memory Dump or a Small Memory Dump, you may need to set the executable image path to point to any executable files which may have been loaded in memory at the time of the crash. + +Analysis of a dump file is similar to analysis of a live debugging session. See the [Debugger Commands](debugger-commands.md) reference section for details on which commands are available for debugging dump files in kernel mode. + +In most cases, you should begin by using [**!analyze**](-analyze.md). This extension command performs automatic analysis of the dump file and can often result in a lot of useful information. + +The [**.bugcheck (Display Bug Check Data)**](-bugcheck--display-bug-check-data-.md) shows the bug check code and its parameters. Look up this bug check in the [Bug Check Code Reference](bug-check-code-reference2.md) for information about the specific error. + +The following debugger extensions are especially useful for analyzing a kernel-mode crash dump: + +[**!drivers**](-drivers.md) + +[**!kdext\*.locks**](-locks---kdext--locks-.md) + +[**!memusage**](-memusage.md) + +[**!vm**](-vm.md) + +[**!errlog**](-errlog.md) + +[**!process 0 0**](-process.md) + +[**!process 0 7**](-process.md) + +For techniques that can be used to read specific kinds of information from a dump file, see [Extracting Information from a Dump File](extracting-information-from-a-dump-file.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Kernel-Mode%20Dump%20File%20with%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-windbg.md b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-windbg.md new file mode 100644 index 0000000000..5327e36c5a --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file-with-windbg.md @@ -0,0 +1,75 @@ +--- +title: Analyzing a Kernel-Mode Dump File with WinDbg +description: Analyzing a Kernel-Mode Dump File with WinDbg +ms.assetid: a1493740-5bb5-4335-b177-ee94b93f716b +keywords: ["WinDbg, analyzing a kernel-mode dump file", "CAB file containing a dump file, analyzing kernel-mode dump file with WinDbg"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Kernel-Mode Dump File with WinDbg + + +## + + +Kernel-mode memory dump files can be analyzed by WinDbg. The processor or Windows version that the dump file was created on does not need to match the platform on which KD is being run. + +### Starting WinDbg + +To analyze a dump file, start WinDbg with the **-z** command-line option: + +**windbg -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For a full list of options, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +If WinDbg is already running and is in dormant mode, you can open a crash dump by selecting the **File | Open Crash Dump** menu command or pressing the CTRL+D shortcut key. When the **Open Crash Dump** dialog box appears, enter the full path and name of the crash dump file in the **File name** text box, or use the dialog box to select the proper path and file name. When the proper file has been chosen, click **Open**. + +You can also open a dump file after the debugger is running by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed with [**g (Go)**](g--go-.md). + +It is possible to debug multiple dump files at the same time. This can be done by including multiple **-z** switches on the command line (each followed by a different file name), or by using [**.opendump**](-opendump--open-dump-file-.md) to add additional dump files as debugger targets. For information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file. + +It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the **-z** option or as the argument to an [**.opendump**](-opendump--open-dump-file-.md) command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will only be able to read one of them. The debugger will not read any additional files from the CAB, even if they were symbol files or other files associated with the dump file. + +### Analyzing the Dump File + +If you are analyzing a Kernel Memory Dump or a Small Memory Dump, you may need to set the executable image path to point to any executable files that may have been loaded in memory at the time of the crash. + +Analysis of a dump file is similar to analysis of a live debugging session. See the [Debugger Commands](debugger-commands.md) reference section for details on which commands are available for debugging dump files in kernel mode. + +In most cases, you should begin by using [**!analyze**](-analyze.md). This extension command performs automatic analysis of the dump file and can often result in a lot of useful information. + +The [**.bugcheck (Display Bug Check Data)**](-bugcheck--display-bug-check-data-.md) shows the bug check code and its parameters. Look up this bug check in the [Bug Check Code Reference](bug-check-code-reference2.md) for information about the specific error. + +The following debugger extensions are especially useful for analyzing a kernel-mode crash dump: + +[**!drivers**](-drivers.md) + +[**!kdext\*.locks**](-locks---kdext--locks-.md) + +[**!memusage**](-memusage.md) + +[**!vm**](-vm.md) + +[**!errlog**](-errlog.md) + +[**!process 0 0**](-process.md) + +[**!process 0 7**](-process.md) + +For techniques that can be used to read specific kinds of information from a dump file, see [Extracting Information from a Dump File](extracting-information-from-a-dump-file.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Kernel-Mode%20Dump%20File%20with%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file.md b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file.md new file mode 100644 index 0000000000..5e73c070c1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-kernel-mode-dump-file.md @@ -0,0 +1,43 @@ +--- +title: Analyzing a Kernel-Mode Dump File +description: Analyzing a Kernel-Mode Dump File +ms.assetid: 2bda51c2-b022-4740-8df9-5a2cf2382e3e +keywords: ["dump file, analyzing a kernel-mode dump file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Kernel-Mode Dump File + + +## + + +This section includes: + +[Analyzing a Kernel-Mode Dump File with KD](analyzing-a-kernel-mode-dump-file-with-kd.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Analyzing a Kernel-Mode Dump File with KAnalyze](analyzing-a-kernel-mode-dump-file-with-kanalyze.md) + +### Installing Symbol Files + +Regardless of which tool you use, you need to install the symbol files for the version of Windows that generated the dump file. These files will be used by the debugger you choose to use to analyze the dump file. For more information about the proper installation of symbol files, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +### DumpExam + +The DumpExam tool is obsolete. It is no longer needed in the analysis of a crash dump file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Kernel-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-stuck-call-problem.md b/windows-driver-docs-pr/debugger/analyzing-a-stuck-call-problem.md new file mode 100644 index 0000000000..14d84748f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-stuck-call-problem.md @@ -0,0 +1,138 @@ +--- +title: Analyzing a Stuck Call Problem +description: Analyzing a Stuck Call Problem +ms.assetid: e1a80cde-cf83-4a16-ae4b-5ddd5eb77b6d +keywords: ["RPC debugging, stuck call"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Stuck Call Problem + + +## + + +A common problem occurs when a process makes an RPC call, directly or indirectly, while holding a critical section or a resource. In this case, the RPC call goes to another process or machine and dispatches to the manager routine (server routine), which then hangs or takes too long. This causes the original caller to encounter a critical section time-out. + +When examined through the debugger, RPC is on top of the stack of the thread owning the critical section, but it is not clear what it is waiting for. + +Here is one example of such a stack. Many variations are possible. + +``` +0:002> ~1k +ChildEBP RetAddr +0068fba0 77e9e8eb ntdll!ZwWaitForSingleObject+0xb +0068fbc8 4efeff73 KERNEL32!WaitForSingleObjectEx+0x5a +0068fbe8 4eff0012 RPCRT4!UTIL_WaitForSyncIO+0x21 +0068fc0c 4efe6e2b RPCRT4!UTIL_GetOverlappedResultEx+0x44 +0068fc44 4ef973bf RPCRT4!WS_SyncRecv+0x12a +0068fc68 4ef98d5a RPCRT4!OSF_CCONNECTION__TransSendReceive+0xcb +0068fce4 4ef9b682 RPCRT4!OSF_CCONNECTION__SendFragment+0x297 +0068fd38 4ef9a5a8 RPCRT4!OSF_CCALL__SendNextFragment+0x272 +0068fd88 4ef9a9cb RPCRT4!OSF_CCALL__FastSendReceive+0x165 +0068fda8 4ef9a7f8 RPCRT4!OSF_CCALL__SendReceiveHelper+0xed +0068fdd4 4ef946a7 RPCRT4!OSF_CCALL__SendReceive+0x37 +0068fdf0 4efd56b3 RPCRT4!I_RpcSendReceive+0xc4 +0068fe08 01002850 RPCRT4!NdrSendReceive+0x4f +0068ff40 01001f32 rtclnt+0x2850 +0068ffb4 77e92ca8 rtclnt+0x1f32 +0068ffec 00000000 KERNEL32!CreateFileA+0x11b +``` + +Here's how to troubleshoot this problem. + + **Troubleshooting a stuck call problem** + +1. Make sure the debugger is debugging the process that owns the stuck cell. (This is the process containing the client thread that is suspected of hanging in RPC.) + +2. Get the stack pointer of this thread. The stack will look like the one shown in the preceding example. In this example, the stack pointer is 0x0068FBA0. + +3. Get the call information for this thread. In order to do that, use the [**!rpcexts.rpcreadstack**](-rpcexts-rpcreadstack.md) extension with the thread stack pointer as its parameter, as follows: + + ``` + 0:001> !rpcexts.rpcreadstack 68fba0 + CallID: 1 + IfStart: 19bb5061 + ProcNum: 0 + Protocol Sequence: "ncacn_ip_tcp" (Address: 00692ED8) + NetworkAddress: "" (Address: 00692F38) + Endpoint: "1120" (Address: 00693988) + ``` + + The information displayed here will allow you to trace the call. + +4. The network address is empty, which indicates the local machine. The endpoint is 1120. You need to determine which process hosts this endpoint. This can be done by passing this endpoint number to the [**!rpcexts.getendpointinfo**](-rpcexts-getendpointinfo.md) extension, as follows: + ``` + 0:001> !rpcexts.getendpointinfo 1120 + Searching for endpoint info ... + PID CELL ID ST PROTSEQ ENDPOINT + -------------------------------------------- + 0278 0000.0001 01 TCP 1120 + ``` + +5. From the preceding information, you can see that process 0x278 contains this endpoint. You can determine if this process knows anything about this call by using the [**!rpcexts.getcallinfo**](-rpcexts-getcallinfo.md) extension. This extension needs four parameters: *CallID*, *IfStart*, and *ProcNum* (which were found in step 3), and the *ProcessID* of 0x278: + ``` + 0:001> !rpcexts.getcallinfo 1 19bb5061 0 278 + Searching for call info ... + PID CELL ID ST PNO IFSTART TIDNUMBER CALLFLAG CALLID LASTTIME CONN/CLN + ---------------------------------------------------------------------------- + 0278 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 00072c09 0000.0003 + ``` + +6. The information in step 5 is useful, but somewhat abbreviated. The cell ID is given in the second column as 0000.0004. If you pass the process ID and this cell number to the [**!rpcexts.getdbgcell**](-rpcexts-getdbgcell.md) extension, you will see a more readable display of this cell: + + ``` + 0:001> !rpcexts.getdbgcell 278 0.4 + Getting cell info ... + Call + Status: Dispatched + Procedure Number: 0 + Interface UUID start (first DWORD only): 19BB5061 + Call ID: 0x1 (1) + Servicing thread identifier: 0x0.2 + Call Flags: cached + Last update time (in seconds since boot):470.25 (0x1D6.19) + Owning connection identifier: 0x0.3 + ``` + + This shows that the call is in state "dispatched", which means is has left the RPC Run-Time. The last update time is 470.25. You can learn the current time by using the [**!rpcexts.rpctime**](-rpcexts-rpctime.md) extension: + + ``` + 0:001> !rpcexts.rpctime + Current time is: 6003, 422 + ``` + + This shows that the last contact with this call was approximately 5533 seconds ago, which is about 92 minutes. Thus, this must be a stuck call. + +7. As a last step before you attach a debugger to the server process, you can isolate the thread that should currently service the call by using the Servicing thread identifier. This is another cell number; it appeared in step 6 as "0x0.2". You can use it as follows: + + ``` + 0:001> !rpcexts.getdbgcell 278 0.2 + Getting cell info ... + Thread + Status: Dispatched + Thread ID: 0x1A4 (420) + Last update time (in seconds since boot):470.25 (0x1D6.19) + ``` + + Now you know that you are looking for thread 0x1A4 in process 0x278. + +It is possible that the thread was making another RPC call. If necessary, you can trace this call by repeating this procedure. + +**Note**   This procedure shows how to find the server thread if you know the client thread. For an example of the reverse technique, see [Identifying the Caller From the Server Thread](identifying-the-caller-from-the-server-thread.md). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Stuck%20Call%20Problem%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-cdb.md b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-cdb.md new file mode 100644 index 0000000000..a4031309e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-cdb.md @@ -0,0 +1,63 @@ +--- +title: Analyzing a User-Mode Dump File with CDB +description: Analyzing a User-Mode Dump File with CDB +ms.assetid: 992e9e5b-a2de-4644-b1bb-1569a18081df +keywords: ["CDB, analyzing a dump file", "CAB file containing a dump file, analyzing user-mode dump file with CDB"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a User-Mode Dump File with CDB + + +## + + +User-mode memory dump files can be analyzed by CDB. The processor or Windows version that the dump file was created on does not need to match the platform on which CDB is being run. + +### Installing Symbol Files + +Before analyzing the memory dump file, you will need to install the symbol files for the version of Windows that generated the dump file. These files will be used by the debugger you choose to use to analyze the dump file. For more information about the proper installation of symbol files, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +You will also need to install all the symbol files for the user-mode process, either an application or system service, that caused the system to generate the dump file. If this code was written by you, the symbol files should have been generated when the code was compiled and linked. If this is commercial code, check on the product CD-ROM or contact the software manufacturer for these particular symbol files. + +### Starting CDB + +To analyze a dump file, start CDB with the **-z** command-line option: + +**cdb -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For a full list of options, see [**CDB Command-Line Options**](cdb-command-line-options.md). + +You can also open a dump file after the debugger is running by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed with [**g (Go)**](g--go-.md). This allows you to debug multiple dump files at the same time. + +It is possible to debug multiple dump files at the same time. This can be done by including multiple **-z** switches on the command line (each followed by a different file name), or by using [**.opendump**](-opendump--open-dump-file-.md) to add additional dump files as debugger targets. For information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file. + +It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the **-z** option or as the argument to an [**.opendump**](-opendump--open-dump-file-.md) command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will only be able to read one of them. The debugger will not read any additional files from the CAB, even if they are symbol files or executables associated with the dump file. + +### Analyzing a Full User Dump File + +Analysis of a full user dump file is similar to analysis of a live debugging session. See the [Debugger Commands](debugger-commands.md) reference section for details on which commands are available for debugging dump files in user mode. + +### Analyzing Minidump Files + +Analysis of a user-mode minidump file is done in the same way as a full user dump. However, since much less memory has been preserved, you are much more limited in the actions you can perform. Commands that attempt to access memory beyond what is preserved in the minidump file will not function properly. + +### Additional Techniques + +For techniques that can be used to read specific kinds of information from a dump file, see [Extracting Information from a Dump File](extracting-information-from-a-dump-file.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20User-Mode%20Dump%20File%20with%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-windbg.md b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-windbg.md new file mode 100644 index 0000000000..431e47e62b --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file-with-windbg.md @@ -0,0 +1,65 @@ +--- +title: Analyzing a User-Mode Dump File with WinDbg +description: Analyzing a User-Mode Dump File with WinDbg +ms.assetid: 46b6a170-e8dd-4d89-bcb9-ea65d74d2a54 +keywords: ["WinDbg, analyzing a user-mode dump file", "CAB file containing a dump file, analyzing user-mode dump file with WinDbg"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a User-Mode Dump File with WinDbg + + +## + + +User-mode memory dump files can be analyzed by WinDbg. The processor or Windows version that the dump file was created on does not need to match the platform on which WinDbg is being run. + +### Installing Symbol Files + +Before analyzing the memory dump file, you will need to install the symbol files for the version of Windows that generated the dump file. These files will be used by the debugger you choose to use to analyze the dump file. For more information about the proper installation of symbol files, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +You will also need to install all the symbol files for the user-mode process, either an application or system service, that caused the system to generate the dump file. If this code was written by you, the symbol files should have been generated when the code was compiled and linked. If this is commercial code, check on the product CD-ROM or contact the software manufacturer for these particular symbol files. + +### Starting WinDbg + +To analyze a dump file, start WinDbg with the **-z** command-line option: + +**windbg -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For a full list of options, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +If WinDbg is already running and is in dormant mode, you can open a crash dump by selecting the **File | Open Crash Dump** menu command or pressing the CTRL+D shortcut key. When the **Open Crash Dump** dialog box appears, enter the full path and name of the crash dump file in the **File name** text box, or use the dialog box to select the proper path and file name. When the proper file has been chosen, click **Open**. + +You can also open a dump file after the debugger is running by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed with [**g (Go)**](g--go-.md). + +It is possible to debug multiple dump files at the same time. This can be done by including multiple **-z** switches on the command line (each followed by a different file name), or by using [**.opendump**](-opendump--open-dump-file-.md) to add additional dump files as debugger targets. For information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file. + +It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the **-z** option or as the argument to an [**.opendump**](-opendump--open-dump-file-.md) command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will only be able to read one of them. The debugger will not read any additional files from the CAB, even if they were symbol files or executables associated with the dump file. + +### Analyzing a Full User Dump File + +Analysis of a full user dump file is similar to analysis of a live debugging session. See the [Debugger Commands](debugger-commands.md) reference section for details on which commands are available for debugging dump files in user mode. + +### Analyzing Minidump Files + +Analysis of a user-mode minidump file is done in the same way as a full user dump. However, since much less memory has been preserved, you are much more limited in the actions you can perform. Commands that attempt to access memory beyond what is preserved in the minidump file will not function properly. + +### Additional Techniques + +For techniques that can be used to read specific kinds of information from a dump file, see [Extracting Information from a Dump File](extracting-information-from-a-dump-file.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20User-Mode%20Dump%20File%20with%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file.md b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file.md new file mode 100644 index 0000000000..ade88acbe8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-user-mode-dump-file.md @@ -0,0 +1,33 @@ +--- +title: Analyzing a User-Mode Dump File +description: Analyzing a User-Mode Dump File +ms.assetid: b7f3dff8-cd2d-41c9-83ff-f0e5fb2312c0 +keywords: ["dump file, analyzing a user-mode dump file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a User-Mode Dump File + + +## + + +This section includes: + +[Analyzing a User-Mode Dump File with CDB](analyzing-a-user-mode-dump-file-with-cdb.md) + +[Analyzing a User-Mode Dump File with WinDbg](analyzing-a-user-mode-dump-file-with-windbg.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20User-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-a-video-stream-stall.md b/windows-driver-docs-pr/debugger/analyzing-a-video-stream-stall.md new file mode 100644 index 0000000000..acf35267c3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-a-video-stream-stall.md @@ -0,0 +1,34 @@ +--- +title: Analyzing a Video Stream Stall +description: Analyzing a Video Stream Stall +ms.assetid: b53b7f4b-c82f-4dba-933c-ec72177e6990 +keywords: ["kernel streaming debugging, video stream stall"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing a Video Stream Stall + + +This section shows how to analyze a video stream stall. All sample output is generated from an AVStream minidriver after an independent hardware vendor (IHV) driver bug has been introduced. + +[Determining the Cause](determining-the-cause-of-a-video-stream-stall.md) + +[Debugging a Processing Stall](debugging-a-processing-stall.md) + +[Using Logging to Track Important Events](using-logging-to-track-important-events.md) + +[Interpreting Bug Check 0xCB](interpreting-bug-check-0xcb.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20a%20Video%20Stream%20Stall%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/analyzing-stalled-drivers-and-time-outs.md b/windows-driver-docs-pr/debugger/analyzing-stalled-drivers-and-time-outs.md new file mode 100644 index 0000000000..ee9ef5adea --- /dev/null +++ b/windows-driver-docs-pr/debugger/analyzing-stalled-drivers-and-time-outs.md @@ -0,0 +1,61 @@ +--- +title: Analyzing Stalled Drivers and Time-Outs +description: Analyzing Stalled Drivers and Time-Outs +ms.assetid: c305acba-48b9-4597-925a-8b1ded4f0048 +keywords: ["SCSI Miniport Debugging, hangs and time-outs"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Analyzing Stalled Drivers and Time-Outs + + +When debugging a SCSI miniport driver, the three most common causes for hangs and time-outs are: + +- The SCSI miniport DPC is not running + +- The SCSI miniport fails to ask for the next request + +- A request is not being completed by the SCSI miniport, usually because it is waiting for map registers. + +If you suspect that the SCSI miniport DPC is not running, use [**!pcr**](-pcr.md) to display the DPC queue for the current processor. If the SCSI port DPC routine is in the DPC queue, place a breakpoint on this routine to determine whether this routine is ever called. Otherwise, use [**!scsikd.scsiext**](-scsikd-scsiext.md) on each device. Consider the following sample output from the **!scsikd.scsiext** extension: + +``` +0: kd> !scsikd.scsiext 86353040 +Common Extension: + < ..omitted.. > +Logical Unit Extension: + Address (3, 0, 1, 0) Claimed Enumerated Visible + LuFlags (0x00000000): + Retry 0x00 Key 0x008889ff + Lock 0x00000000 Pause 0x00000000 CurrentLock: 0x00000000 + HwLuExt 0x862e6f00 Adapter 0x8633db28 Timeout 0x0000000a + NextLun 0x00000000 ReadyLun 0x00000000 + Pending 0x00000000 Busy 0x00000000 Untagged 0x00000000 + + . . . + +Request list @0x86353200: + Tick count is 2526 + SrbData 8615d700 Srb 8611f4fc Irp 8611f2b8 Key 60197 <1s + SrbData 85e72868 Srb 86100c3c Irp 861009f8 Key e29dc7 <1s +``` + +If the timeout slot is -1 and the untagged slot is nonzero, or the time-out slot is nonzero and there are requests shown, the miniport has failed to ask for the next request. + +Alternatively, if the retry slot and the busy slot are nonzero, a request may not be completed by the SCSI miniport because it is waiting for map registers. Similarly, if the untagged and pending slots are nonzero, the SCSI miniport might be waiting for map registers. In either case, the address of the SCSI request block (SRB) is the address in the busy slot and the address of the request that is not being completed. For more information about the SRB, use the [**!minipkd.srb**](-minipkd-srb.md) extension with this address as input. + +The [**!devobj**](-devobj.md) extension determines whether the SCSI miniport is waiting for map registers. Use the device object address of the device that is issuing the request as input to **!devobj**. If the current IRQ is nonzero, it is highly probable that the SCSI miniport is waiting for map registers. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Analyzing%20Stalled%20Drivers%20and%20Time-Outs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/anatomy-of-a-dbgeng-extension-dll.md b/windows-driver-docs-pr/debugger/anatomy-of-a-dbgeng-extension-dll.md new file mode 100644 index 0000000000..d5f2b342ef --- /dev/null +++ b/windows-driver-docs-pr/debugger/anatomy-of-a-dbgeng-extension-dll.md @@ -0,0 +1,67 @@ +--- +title: Anatomy of a DbgEng Extension DLL +description: Anatomy of a DbgEng Extension DLL +ms.assetid: 5131115b-b9a0-479b-9391-7ab384633d92 +keywords: ["DbgEng Extensions, DLL anatomy"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Anatomy of a DbgEng Extension DLL + + +## + + +A DbgEng extension DLL exports a number of callback functions, some of which may be implementations of extension commands. + +These extension DLLs are loaded by the [debugger engine](introduction.md#debugger-engine) and can provide extra functionality or automation of tasks while performing user-mode or kernel-mode debugging on Microsoft Windows. + +If you performed a full install of Debugging Tools for Windows, a sample DbgEng extension called "exts" can be found in the sdk\\samples\\exts subdirectory of the installation directory. + +### Extension Commands + +An extension DLL may export any number of functions that are used to execute extension commands. Each function is explicitly declared as an export in the .def file, and its name must consist entirely of lowercase letters. + +Functions used to implement extension commands must match the prototype [**PDEBUG\_EXTENSION\_CALL**](https://msdn.microsoft.com/library/windows/hardware/ff553378). + +These functions are named according to the standard C++ convention, except that uppercase letters are not permitted. The exported function name and the extension command name are identical, except that the extension command begins with an exclamation point (!). For example, when you load myextension.dll into the debugger and then type **!stack** into the Debugger Command window, the debugger looks for an exported function named **stack** in myextension.dll. + +If myextension.dll is not already loaded, or if there may be other extension commands with the same name in other extension DLLs, you can type **!myextension.stack** into the Debugger Command window to indicate the extension DLL and the extension command in that DLL. + +### Other Exported Functions + +A DbgEng extension DLL must export [*DebugExtensionInitialize*](https://msdn.microsoft.com/library/windows/hardware/ff540476). This will be called when the DLL is loaded, to initialize the DLL. It may be used by the DLL to initialize global variables. + +An extension DLL may export [*DebugExtensionUninitialize*](https://msdn.microsoft.com/library/windows/hardware/ff540495). If this is exported, it will be called before the extension DLL is unloaded. It may be used by the DLL to clean up before it is unloaded. + +An extension DLL may export [*DebugExtensionNotify*](https://msdn.microsoft.com/library/windows/hardware/ff540478). If this is exported, it will be called when a session begins or ends, and when a target starts or stops executing. These notifications are also provided to [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550) objects registered with a client. + +An extension DLL may export [*KnownStructOutput*](https://msdn.microsoft.com/library/windows/hardware/ff551934). If this is exported, it will be called when the DLL is loaded. This function returns a list of structures that the DLL knows how to print on a single line. It may be called later to format instances of these structures for printing. + +### Engine Procedure for Loading a DbgEng Extension DLL + +When an extension DLL is loaded, the callback functions are called by the engine in the following order: + +1. **DebugExtensionInitialize** is called so the extension DLL can initialize. + +2. If exported, **DebugExtensionNotify** is called if the engine has an active session, and called again if the session is suspended and accessible. + +3. If exported, **KnownStructOutput** is called to request a list of structures the DLL knows how to print on a single line. + +See [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) for information about how to use the debugger to load and unload an extension DLL, and see [Using Debugger Extension Commands](using-debugger-extension-commands.md) for information about executing an extension command. + +The debugger engine will place a **try / except** block around a call to an extension DLL. This protects the engine from some types of bugs in the extension code; but, since the extension calls are executed in the same thread as the engine, they can still cause it to crash. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Anatomy%20of%20a%20DbgEng%20Extension%20DLL%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/annotated-x64-disassembly.md b/windows-driver-docs-pr/debugger/annotated-x64-disassembly.md new file mode 100644 index 0000000000..390fbf914c --- /dev/null +++ b/windows-driver-docs-pr/debugger/annotated-x64-disassembly.md @@ -0,0 +1,338 @@ +--- +title: Annotated x64 Disassembly +description: Annotated x64 Disassembly +ms.assetid: 67930062-8a3a-460f-ae56-248d2a8e131e +keywords: ["x64 processor, annotated disassembly"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Annotated x64 Disassembly + + +## + + +The following very simple function illustrates the x64 calling convention. + +``` +int Simple(int i, int j) +{ + return i*5 + j + 3; +} +``` + +This compiles to code like this: + +``` +01001080 lea eax,[rdx+rcx*4] ; eax = rdx+rcx*4 +01001083 lea eax,[rcx+rax+0x3] ; eax = rcx+rax+3 +01001087 ret +``` + +The *i* and *j* parameters are passed in the **ecx** and **edx** registers, respectively. Since there are only two parameters, the routine does not use the stack at all. + +The particular code generated exploits three tricks, one of which is specific to the x64: + +1. The **lea** operation can be used to perform a series of simple arithmetic operations as a single operation. The first instruction stores *j+i*\*4 in **eax**, and the second instruction adds *i*+3 to the result, for a total of *j*+*i*\*5+3. + +2. Many operations, such as addition and multiplication, can be done with extra precision, and then truncated to the correct precision. In this instance, the code uses 64-bit addition and multiplication. We can safely truncate the result to 32 bits. + +3. On the x64, any operation that outputs to a 32-bit register automatically zero-extends the result. In this case, outputting to **eax** has the effect of truncating the result to 32 bits. + +Return values are passed in the **rax** register. In this case, the result is already in the **rax** register, so the function returns. + +Next we consider a more complicated function to demonstrate typical x64 disassembly: + +``` +HRESULT Meaningless(IDispatch *pdisp, DISPID dispid, BOOL fUnique, LPCWSTR pszExe) +{ + IQueryAssociations *pqa; + HRESULT hr = AssocCreate(CLSID_QueryAssociations, IID_IQueryAssociations, (void**)&pqa); + if (SUCCEEDED(hr)) { + hr = pqa->Init(ASSOCF_INIT_BYEXENAME, pszExe, NULL, NULL); + if (SUCCEEDED(hr)) { + WCHAR wszName[MAX_PATH]; + DWORD cchName = MAX_PATH; + hr = pqa->GetString(0, ASSOCSTR_FRIENDLYAPPNAME, NULL, wszName, &cchName); + if (SUCCEEDED(hr)) { + VARIANTARG rgvarg[2] = { 0 }; + V_VT(&rgvarg[0]) = VT_BSTR; + V_BSTR(&rgvarg[0]) = SysAllocString(wszName); + if (V_BSTR(&rgvarg[0])) { + DISPPARAMS dp; + LONG lUnique = InterlockedIncrement(&lCounter); + V_VT(&rgvarg[1]) = VT_I4; + V_I4(&rgvarg[1]) = fUnique ? lUnique : 0; + dp.rgvarg = rgvarg; + dp.cArgs = 2; + dp.rgdispidNamedArgs = NULL; + dp.cNamedArgs = 0; + hr = pdisp->Invoke(dispid, IID_NULL, 0, DISPATCH_METHOD, &dp, NULL, NULL, NULL); + VariantClear(&rgvarg[0]); + VariantClear(&rgvarg[1]); + } else { + hr = E_OUTOFMEMORY; + } + } + } + pqa->Release(); + } + return hr; +} +``` + +We'll go through this function and the equivalent assembly line by line. + +When entered, the function's parameters are stored as follows: + +- **rcx** = *pdisp*. + +- **rdx** = *dispid*. + +- **r8** = *fUnique*. + +- **r9** = *pszExe*. + +Recall that the first four parameters are passed in registers. Since this function has only four registers, none are passed on the stack. + +The assembly begins as follows: + +``` +Meaningless: +010010e0 push rbx ; save +010010e1 push rsi ; save +010010e2 push rdi ; save +010010e3 push r12d ; save +010010e5 push r13d ; save +010010e7 push r14d ; save +010010e9 push r15d ; save +010010eb sub rsp,0x2c0 ; reserve stack +010010f2 mov rbx,r9 ; rbx = pszExe +010010f5 mov r12d,r8d ; r12 = fUnique (zero-extend) +010010f8 mov r13d,edx ; r13 = dispid (zero-extend) +010010fb mov rsi,rcx ; rsi = pdisp +``` + +The function begins by saving nonvolatile registers, and then reserving stack space for local variables. It then saves parameters in nonvolatile registers. Note that the destination of the middle two **mov** instructions is a 32-bit register, so they are implicitly zero-extended to 64 bits. + +``` + IQueryAssociations *pqa; + HRESULT hr = AssocCreate(CLSID_QueryAssociations, IID_IQueryAssociations, (void**)&pqa); +``` + +The first parameter to **AssocCreate** is a 128-bit CLSID passed by value. Since this doesn't fit in a 64-bit register, the CLSID is copied to the stack, and a pointer to the stack location is passed instead. + +``` +010010fe movdqu xmm0,oword ptr [CLSID_QueryAssociations (01001060)] +01001106 movdqu oword ptr [rsp+0x60],xmm0 ; temp buffer for first parameter +0100110c lea r8,[rsp+0x58] ; arg3 = &pqa +01001111 lea rdx,[IID_IQueryAssociations (01001070)] ; arg2 = &IID_IQueryAssociations +01001118 lea rcx,[rsp+0x60] ; arg1 = &temporary +0100111d call qword ptr [_imp_AssocCreate (01001028)] ; call +``` + +The **movdqu** instruction transfers 128-bits values to and from **xmm***n* registers. In this instance, the assembly code uses it to copy the CLSID to the stack. The pointer to the CLSID is passed in **r8**. The other two arguments are passed in **rcx** and **rdx**. + +``` + if (SUCCEEDED(hr)) { + +01001123 test eax,eax +01001125 jl ReturnEAX (01001281) +``` + +The code checks to see if the return value is a success. + +``` + hr = pqa->Init(ASSOCF_INIT_BYEXENAME, pszExe, NULL, NULL); + +0100112b mov rcx,[rsp+0x58] ; arg1 = pqa +01001130 mov rax,[rcx] ; rax = pqa.vtbl +01001133 xor r14d,r14d ; r14 = 0 +01001136 mov [rsp+0x20],r14 ; arg5 = 0 +0100113b xor r9d,r9d ; arg4 = 0 +0100113e mov r8,rbx ; arg3 = pszExe +01001141 mov r15d,0x2 ; r15 = 2 (for later) +01001147 mov edx,r15d ; arg2 = 2 (ASSOCF_INIT_BY_EXENAME) +0100114a call qword ptr [rax+0x18] ; call Init method +``` + +This is an indirect function call using a C++ vtable. The **this** pointer is passed in **rcx** as the first parameter. The first three parameters are passed in registers, while the final parameter is passed on the stack. The function reserves 16 bytes for the parameters passed in registers, so the fifth parameter begins at **rsp**+0x20. + +``` + if (SUCCEEDED(hr)) { + +0100114d mov ebx,eax ; ebx = hr +0100114f test ebx,ebx ; FAILED? +01001151 jl ReleasePQA (01001274) ; jump if so +``` + +The assembly-language code saves the result in **ebx**, and checks to see if it's a success code. + +``` + WCHAR wszName[MAX_PATH]; + DWORD cchName = MAX_PATH; + hr = pqa->GetString(0, ASSOCSTR_FRIENDLYAPPNAME, NULL, wszName, &cchName); + if (SUCCEEDED(hr)) { + +01001157 mov dword ptr [rsp+0x50],0x104 ; cchName = MAX_PATH +0100115f mov rcx,[rsp+0x58] ; arg1 = pqa +01001164 mov rax,[rcx] ; rax = pqa.vtbl +01001167 lea rdx,[rsp+0x50] ; rdx = &cchName +0100116c mov [rsp+0x28],rdx ; arg6 = cchName +01001171 lea rdx,[rsp+0xb0] ; rdx = &wszName[0] +01001179 mov [rsp+0x20],rdx ; arg5 = &wszName[0] +0100117e xor r9d,r9d ; arg4 = 0 +01001181 mov r8d,0x4 ; arg3 = 4 (ASSOCSTR_FRIENDLYNAME) +01001187 xor edx,edx ; arg2 = 0 +01001189 call qword ptr [rax+0x20] ; call GetString method +0100118c mov ebx,eax ; ebx = hr +0100118e test ebx,ebx ; FAILED? +01001190 jl ReleasePQA (01001274) ; jump if so +``` + +Once again, we set up the parameters and call a function, then test the return value for success. + +``` + VARIANTARG rgvarg[2] = { 0 }; + +01001196 lea rdi,[rsp+0x82] ; rdi = &rgvarg +0100119e xor eax,eax ; rax = 0 +010011a0 mov ecx,0x2e ; rcx = sizeof(rgvarg) +010011a5 rep stosb ; Zero it out +``` + +The idiomatic method for zeroing out a buffer on x64 is the same as x86. + +``` + V_VT(&rgvarg[0]) = VT_BSTR; + V_BSTR(&rgvarg[0]) = SysAllocString(wszName); + if (V_BSTR(&rgvarg[0])) { + +010011a7 mov word ptr [rsp+0x80],0x8 ; V_VT(&rgvarg[0]) = VT_BSTR +010011b1 lea rcx,[rsp+0xb0] ; arg1 = &wszName[0] +010011b9 call qword ptr [_imp_SysAllocString (01001010)] ; call +010011bf mov [rsp+0x88],rax ; V_BSTR(&rgvarg[0]) = result +010011c7 test rax,rax ; anything allocated? +010011ca je OutOfMemory (0100126f) ; jump if failed + + DISPPARAMS dp; + LONG lUnique = InterlockedIncrement(&lCounter); + +010011d0 lea rax,[lCounter (01002000)] +010011d7 mov ecx,0x1 +010011dc lock xadd [rax],ecx ; interlocked exchange and add +010011e0 add ecx,0x1 +``` + +**InterlockedIncrement** compiles directly to machine code. The **lock xadd** instruction performs an atomic exchange and add. The final result is stored in **ecx**. + +``` + V_VT(&rgvarg[1]) = VT_I4; + V_I4(&rgvarg[1]) = fUnique ? lUnique : 0; + +010011e3 mov word ptr [rsp+0x98],0x3 ; V_VT(&rgvarg[1]) = VT_I4; +010011ed mov eax,r14d ; rax = 0 (r14d is still zero) +010011f0 test r12d,r12d ; fUnique set? +010011f3 cmovne eax,ecx ; if so, then set rax=lCounter +010011f6 mov [rsp+0xa0],eax ; V_I4(&rgvarg[1]) = ... +``` + +Since x64 supports the **cmov** instruction, the **?:** construct can be compiled without using a jump. + +``` + dp.rgvarg = rgvarg; + dp.cArgs = 2; + dp.rgdispidNamedArgs = NULL; + dp.cNamedArgs = 0; + +010011fd lea rax,[rsp+0x80] ; rax = &rgvarg[0] +01001205 mov [rsp+0x60],rax ; dp.rgvarg = rgvarg +0100120a mov [rsp+0x70],r15d ; dp.cArgs = 2 (r15 is still 2) +0100120f mov [rsp+0x68],r14 ; dp.rgdispidNamedArgs = NULL +01001214 mov [rsp+0x74],r14d ; dp.cNamedArgs = 0 +``` + +This code initializes the rest of the members of DISPPARAMS. Note that the compiler reuses the space on the stack previously used by the CLSID. + +``` + hr = pdisp->Invoke(dispid, IID_NULL, 0, DISPATCH_METHOD, &dp, NULL, NULL, NULL); + +01001219 mov rax,[rsi] ; rax = pdisp.vtbl +0100121c mov [rsp+0x40],r14 ; arg9 = 0 +01001221 mov [rsp+0x38],r14 ; arg8 = 0 +01001226 mov [rsp+0x30],r14 ; arg7 = 0 +0100122b lea rcx,[rsp+0x60] ; rcx = &dp +01001230 mov [rsp+0x28],rcx ; arg6 = &dp +01001235 mov word ptr [rsp+0x20],0x1 ; arg5 = 1 (DISPATCH_METHOD) +0100123c xor r9d,r9d ; arg4 = 0 +0100123f lea r8,[GUID_NULL (01001080)] ; arg3 = &IID_NULL +01001246 mov edx,r13d ; arg2 = dispid +01001249 mov rcx,rsi ; arg1 = pdisp +0100124c call qword ptr [rax+0x30] ; call Invoke method +0100124f mov ebx,eax ; hr = result +``` + +The code then sets up the parameters and calls the **Invoke** method. + +``` + VariantClear(&rgvarg[0]); + VariantClear(&rgvarg[1]); + +01001251 lea rcx,[rsp+0x80] ; arg1 = &rgvarg[0] +01001259 call qword ptr [_imp_VariantClear (01001018)] +0100125f lea rcx,[rsp+0x98] ; arg1 = &rgvarg[1] +01001267 call qword ptr [_imp_VariantClear (01001018)] +0100126d jmp ReleasePQA (01001274) +``` + +The code finishes up the current branch of the conditional, and skips over the **else** branch. + +``` + } else { + hr = E_OUTOFMEMORY; + } + } + +OutOfMemory: +0100126f mov ebx,0x8007000e ; hr = E_OUTOFMEMORY + pqa->Release(); +ReleasePQA: +01001274 mov rcx,[rsp+0x58] ; arg1 = pqa +01001279 mov rax,[rcx] ; rax = pqa.vtbl +0100127c call qword ptr [rax+0x10] ; release +``` + +The **else** branch. + +``` + return hr; +} + +0100127f mov eax,ebx ; rax = hr (for return value) +ReturnEAX: +01001281 add rsp,0x2c0 ; clean up the stack +01001288 pop r15d ; restore +0100128a pop r14d ; restore +0100128c pop r13d ; restore +0100128e pop r12d ; restore +01001290 pop rdi ; restore +01001291 pop rsi ; restore +01001292 pop rbx ; restore +01001293 ret ; return (do not pop arguments) +``` + +The return value is stored in **rax**, and then the non-volatile registers are restored before returning. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Annotated%20x64%20Disassembly%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/annotated-x86-disassembly.md b/windows-driver-docs-pr/debugger/annotated-x86-disassembly.md new file mode 100644 index 0000000000..667e9ae50a --- /dev/null +++ b/windows-driver-docs-pr/debugger/annotated-x86-disassembly.md @@ -0,0 +1,537 @@ +--- +title: Annotated x86 Disassembly +description: Annotated x86 Disassembly +ms.assetid: ea1e67c8-d752-42d8-92db-a0c105ceddd6 +keywords: ["x86 processor, annotated disassembly", "x86 processor, assembly code", "x86 processor, source code"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Annotated x86 Disassembly + + +## + + +The following section will walk you through a disassembly example. + +### Source Code + +The following is the code for the function that will be analyzed. + +``` +HRESULT CUserView::CloseView(void) +{ + if (m_fDestroyed) return S_OK; + + BOOL fViewObjectChanged = FALSE; + ReleaseAndNull(&m_pdtgt); + + if (m_psv) { + m_psb->EnableModelessSB(FALSE); + if(m_pws) m_pws->ViewReleased(); + + IShellView* psv; + + HWND hwndCapture = GetCapture(); + if (hwndCapture && hwndCapture == m_hwnd) { + SendMessage(m_hwnd, WM_CANCELMODE, 0, 0); + } + + m_fHandsOff = TRUE; + m_fRecursing = TRUE; + NotifyClients(m_psv, NOTIFY_CLOSING); + m_fRecursing = FALSE; + + m_psv->UIActivate(SVUIA_DEACTIVATE); + + psv = m_psv; + m_psv = NULL; + + ReleaseAndNull(&_pctView); + + if (m_pvo) { + IAdviseSink *pSink; + if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) && pSink) { + if (pSink == (IAdviseSink *)this) + m_pvo->SetAdvise(0, 0, NULL); + pSink->Release(); + } + + fViewObjectChanged = TRUE; + ReleaseAndNull(&m_pvo); + } + + if (psv) { + psv->SaveViewState(); + psv->DestroyViewWindow(); + psv->Release(); + } + + m_hwndView = NULL; + m_fHandsOff = FALSE; + + if (m_pcache) { + GlobalFree(m_pcache); + m_pcache = NULL; + } + + m_psb->EnableModelessSB(TRUE); + + CancelPendingActions(); + } + + ReleaseAndNull(&_psf); + + if (fViewObjectChanged) + NotifyViewClients(DVASPECT_CONTENT, -1); + + if (m_pszTitle) { + LocalFree(m_pszTitle); + m_pszTitle = NULL; + } + + SetRect(&m_rcBounds, 0, 0, 0, 0); + return S_OK; +} +``` + +### Assembly Code + +This section contains the annotated disassembly example. + +Functions which use the **ebp** register as a frame pointer start out as follows: + +``` +HRESULT CUserView::CloseView(void) +SAMPLE!CUserView__CloseView: +71517134 55 push ebp +71517135 8bec mov ebp,esp +``` + +This sets up the frame so the function can access its parameters as positive offsets from **ebp**, and local variables as negative offsets. + +This is a method on a private COM interface, so the calling convention is **\_\_stdcall**. This means that parameters are pushed right to left (in this case, there are none), the "this" pointer is pushed, and then the function is called. Thus, upon entry into the function, the stack looks like this: + +``` +[esp+0] = return address +[esp+4] = this +``` + +After the two preceding instructions, the parameters are accessible as: + +``` +[ebp+0] = previous ebp pushed on stack +[ebp+4] = return address +[ebp+8] = this +``` + +For a function that uses **ebp** as a frame pointer, the first pushed parameter is accessible at \[**ebp**+8\]; subsequent parameters are accessible at consecutive higher DWORD addresses. + +``` +71517137 51 push ecx +71517138 51 push ecx +``` + +This function requires only two local stack variables, so a **sub esp**, 8 instruction. The pushed values are then available as \[**ebp**-4\] and \[**ebp**-8\]. + +For a function that uses **ebp** as a frame pointer, stack local variables are accessible at negative offsets from the **ebp** register. + +``` +71517139 56 push esi +``` + +Now the compiler saves the registers that are required to be preserved across function calls. Actually, it saves them in bits and pieces, interleaved with the first line of actual code. + +``` +7151713a 8b7508 mov esi,[ebp+0x8] ; esi = this +7151713d 57 push edi ; save another registers +``` + +It so happens that CloseView is a method on ViewState, which is at offset 12 in the underlying object. Consequently, **this** is a pointer to a ViewState class, although when there is possible confusion with another base class, it will be more carefully specified as (ViewState\*)**this**. + +``` + if (m_fDestroyed) +7151713e 33ff xor edi,edi ; edi = 0 +``` + +XORing a register with itself is a standard way of zeroing it out. + +``` +71517140 39beac000000 cmp [esi+0xac],edi ; this->m_fDestroyed == 0? +71517146 7407 jz NotDestroyed (7151714f) ; jump if equal +``` + +The **cmp** instruction compares two values (by subtracting them). The **jz** instruction checks if the result is zero, indicating that the two compared values are equal. + +The cmp instruction compares two values; a subsequent j instruction jumps based on the result of the comparison. + +``` + return S_OK; +71517148 33c0 xor eax,eax ; eax = 0 = S_OK +7151714a e972010000 jmp ReturnNoEBX (715172c1) ; return, do not pop EBX +``` + +The compiler delayed saving the EBX register until later in the function, so if the program is going to "early-out" on this test, then the exit path needs to be the one that does not restore EBX. + +``` + BOOL fViewObjectChanged = FALSE; + ReleaseAndNull(&m_pdtgt); +``` + +The execution of these two lines of code is interleaved, so pay attention. + +``` +NotDestroyed: +7151714f 8d86c0000000 lea eax,[esi+0xc0] ; eax = &m_pdtgt +``` + +The **lea** instruction computes the effect address of a memory access and stores it in the destination. The actual memory address is not dereferenced. + +The lea instruction takes the address of a variable. + +``` +71517155 53 push ebx +``` + +You should save that EBX register before it is damaged. + +``` +71517156 8b1d10195071 mov ebx,[_imp__ReleaseAndNull] +``` + +Because you will be calling **ReleaseAndNull** frequently, it is a good idea to cache its address in EBX. + +``` +7151715c 50 push eax ; parameter to ReleaseAndNull +7151715d 897dfc mov [ebp-0x4],edi ; fViewObjectChanged = FALSE +71517160 ffd3 call ebx ; call ReleaseAndNull + if (m_psv) { +71517162 397e74 cmp [esi+0x74],edi ; this->m_psv == 0? +71517165 0f8411010000 je No_Psv (7151727c) ; jump if zero +``` + +Remember that you zeroed out the EDI register a while back and that EDI is a register preserved across function calls (so the call to **ReleaseAndNull** did not change it). Therefore, it still holds the value zero and you can use it to quickly test for zero. + +``` + m_psb->EnableModelessSB(FALSE); +7151716b 8b4638 mov eax,[esi+0x38] ; eax = this->m_psb +7151716e 57 push edi ; FALSE +7151716f 50 push eax ; "this" for callee +71517170 8b08 mov ecx,[eax] ; ecx = m_psb->lpVtbl +71517172 ff5124 call [ecx+0x24] ; __stdcall EnableModelessSB +``` + +The above pattern is a telltale sign of a COM method call. + +COM method calls are pretty popular, so it is a good idea to learn to recognize them. In particular, you should be able to recognize the three IUnknown methods directly from their Vtable offsets: QueryInterface=0, AddRef=4, and Release=8. + +``` + if(m_pws) m_pws->ViewReleased(); +71517175 8b8614010000 mov eax,[esi+0x114] ; eax = this->m_pws +7151717b 3bc7 cmp eax,edi ; eax == 0? +7151717d 7406 jz NoWS (71517185) ; if so, then jump +7151717f 8b08 mov ecx,[eax] ; ecx = m_pws->lpVtbl +71517181 50 push eax ; "this" for callee +71517182 ff510c call [ecx+0xc] ; __stdcall ViewReleased +NoWS: + HWND hwndCapture = GetCapture(); +71517185 ff15e01a5071 call [_imp__GetCapture] ; call GetCapture +``` + +Indirect calls through globals is how function imports are implemented in Microsoft Win32. The loader fixes up the globals to point to the actual address of the target. This is a handy way to get your bearings when you are investigating a crashed machine. Look for the calls to imported functions and in the target. You will usually have the name of some imported function, which you can use to determine where you are in the source code. + +``` + if (hwndCapture && hwndCapture == m_hwnd) { + SendMessage(m_hwnd, WM_CANCELMODE, 0, 0); + } +7151718b 3bc7 cmp eax,edi ; hwndCapture == 0? +7151718d 7412 jz No_Capture (715171a1) ; jump if zero +``` + +The function return value is placed in the EAX register. + +``` +7151718f 8b4e44 mov ecx,[esi+0x44] ; ecx = this->m_hwnd +71517192 3bc1 cmp eax,ecx ; hwndCapture = ecx? +71517194 750b jnz No_Capture (715171a1) ; jump if not + +71517196 57 push edi ; 0 +71517197 57 push edi ; 0 +71517198 6a1f push 0x1f ; WM_CANCELMODE +7151719a 51 push ecx ; hwndCapture +7151719b ff1518195071 call [_imp__SendMessageW] ; SendMessage +No_Capture: + m_fHandsOff = TRUE; + m_fRecursing = TRUE; +715171a1 66818e0c0100000180 or word ptr [esi+0x10c],0x8001 ; set both flags at once + + NotifyClients(m_psv, NOTIFY_CLOSING); +715171aa 8b4e20 mov ecx,[esi+0x20] ; ecx = (CNotifySource*)this.vtbl +715171ad 6a04 push 0x4 ; NOTIFY_CLOSING +715171af 8d4620 lea eax,[esi+0x20] ; eax = (CNotifySource*)this +715171b2 ff7674 push [esi+0x74] ; m_psv +715171b5 50 push eax ; "this" for callee +715171b6 ff510c call [ecx+0xc] ; __stdcall NotifyClients +``` + +Notice how you had to change your "this" pointer when calling a method on a different base class from your own. + +``` + m_fRecursing = FALSE; +715171b9 80a60d0100007f and byte ptr [esi+0x10d],0x7f + m_psv->UIActivate(SVUIA_DEACTIVATE); +715171c0 8b4674 mov eax,[esi+0x74] ; eax = m_psv +715171c3 57 push edi ; SVUIA_DEACTIVATE = 0 +715171c4 50 push eax ; "this" for callee +715171c5 8b08 mov ecx,[eax] ; ecx = vtbl +715171c7 ff511c call [ecx+0x1c] ; __stdcall UIActivate + psv = m_psv; + m_psv = NULL; +715171ca 8b4674 mov eax,[esi+0x74] ; eax = m_psv +715171cd 897e74 mov [esi+0x74],edi ; m_psv = NULL +715171d0 8945f8 mov [ebp-0x8],eax ; psv = eax +``` + +The first local variable is **psv**. + +``` + ReleaseAndNull(&_pctView); +715171d3 8d466c lea eax,[esi+0x6c] ; eax = &_pctView +715171d6 50 push eax ; parameter +715171d7 ffd3 call ebx ; call ReleaseAndNull + if (m_pvo) { +715171d9 8b86a8000000 mov eax,[esi+0xa8] ; eax = m_pvo +715171df 8dbea8000000 lea edi,[esi+0xa8] ; edi = &m_pvo +715171e5 85c0 test eax,eax ; eax == 0? +715171e7 7448 jz No_Pvo (71517231) ; jump if zero +``` + +Note that the compiler speculatively prepared the address of the **m\_pvo** member, because you are going to use it frequently for a while. Thus, having the address handy will result in smaller code. + +``` + if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) && pSink) { +715171e9 8b08 mov ecx,[eax] ; ecx = m_pvo->lpVtbl +715171eb 8d5508 lea edx,[ebp+0x8] ; edx = &pSink +715171ee 52 push edx ; parameter +715171ef 6a00 push 0x0 ; NULL +715171f1 6a00 push 0x0 ; NULL +715171f3 50 push eax ; "this" for callee +715171f4 ff5120 call [ecx+0x20] ; __stdcall GetAdvise +715171f7 85c0 test eax,eax ; test bits of eax +715171f9 7c2c jl No_Advise (71517227) ; jump if less than zero +715171fb 33c9 xor ecx,ecx ; ecx = 0 +715171fd 394d08 cmp [ebp+0x8],ecx ; _pSink == ecx? +71517200 7425 jz No_Advise (71517227) +``` + +Notice that the compiler concluded that the incoming "this" parameter was not required (because it long ago stashed that into the ESI register). Thus, it reused the memory as the local variable pSink. + +If the function uses an EBP frame, then incoming parameters arrive at positive offsets from EBP and local variables are placed at negative offsets. But, as in this case, the compiler is free to reuse that memory for any purpose. + +If you are paying close attention, you will see that the compiler could have optimized this code a little better. It could have delayed the **lea edi, \[esi+0xa8\]** instruction until after the two **push 0x0** instructions, replacing them with **push edi**. This would have saved 2 bytes. + +``` + if (pSink == (IAdviseSink *)this) +``` + +These next several lines are to compensate for the fact that in C++, (IAdviseSink \*)**NULL** must still be **NULL**. So if your "this" is really "(ViewState\*)NULL", then the result of the cast should be **NULL** and not the distance between IAdviseSink and IBrowserService. + +``` +71517202 8d46ec lea eax,[esi-0x14] ; eax = -(IAdviseSink*)this +71517205 8d5614 lea edx,[esi+0x14] ; edx = (IAdviseSink*)this +71517208 f7d8 neg eax ; eax = -eax (sets carry if != 0) +7151720a 1bc0 sbb eax,eax ; eax = eax - eax - carry +7151720c 23c2 and eax,edx ; eax = NULL or edx +``` + +Although the Pentium has a conditional move instruction, the base i386 architecture does not, so the compiler uses specific techniques to simulate a conditional move instruction without taking any jumps. + +The general pattern for a conditional evaluation is the following: + +``` + neg r + sbb r, r + and r, (val1 - val2) + add r, val2 +``` + +The **neg r** sets the carry flag if **r** is nonzero, because **neg** negates the value by subtracting from zero. And, subtracting from zero will generate a borrow (set the carry) if you subtract a nonzero value. It also damages the value in the **r** register, but that is acceptable because you are about to overwrite it anyway. + +Next, the **sbb r, r** instruction subtracts a value from itself, which always results in zero. However, it also subtracts the carry (borrow) bit, so the net result is to set **r** to zero or -1, depending on whether the carry was clear or set, respectively. + +Therefore, **sbb r, r** sets **r** to zero if the original value of **r** was zero, or to -1 if the original value was nonzero. + +The third instruction performs a mask. Because the **r** register is zero or -1, "this" serves either to leave **r** zero or to change **r** from -1 to **(val1 - val1)**, in that ANDing any value with -1 leaves the original value. + +Therefore, the result of "and r, (val1 - val1)" is to set r to zero if the original value of r was zero, or to "(val1 - val2)" if the original value of r was nonzero. + +Finally, you add **val2** to **r**, resulting in **val2** or **(val1 - val2) + val2 = val1**. + +Thus, the ultimate result of this series of instructions is to set **r** to **val2** if it was originally zero or to **val1** if it was nonzero. This is the assembly equivalent of **r = r ? val1 : val2**. + +In this particular instance, you can see that **val2 = 0** and **val1 = (IAdviseSink\*)this**. (Notice that the compiler elided the final **add eax, 0** instruction because it has no effect.) + +``` +7151720e 394508 cmp [ebp+0x8],eax ; pSink == (IAdviseSink*)this? +71517211 750b jnz No_SetAdvise (7151721e) ; jump if not equal +``` + +Earlier in this section, you set EDI to the address of the **m\_pvo** member. You are going to be using it now. You also zeroed out the ECX register earlier. + +``` + m_pvo->SetAdvise(0, 0, NULL); +71517213 8b07 mov eax,[edi] ; eax = m_pvo +71517215 51 push ecx ; NULL +71517216 51 push ecx ; 0 +71517217 51 push ecx ; 0 +71517218 8b10 mov edx,[eax] ; edx = m_pvo->lpVtbl +7151721a 50 push eax ; "this" for callee +7151721b ff521c call [edx+0x1c] ; __stdcall SetAdvise +No_SetAdvise: + pSink->Release(); +7151721e 8b4508 mov eax,[ebp+0x8] ; eax = pSink +71517221 50 push eax ; "this" for callee +71517222 8b08 mov ecx,[eax] ; ecx = pSink->lpVtbl +71517224 ff5108 call [ecx+0x8] ; __stdcall Release +No_Advise: +``` + +All these COM method calls should look very familiar. + +The evaluation of the next two statements is interleaved. Do not forget that EBX contains the address of **ReleaseAndNull**. + +``` + fViewObjectChanged = TRUE; + ReleaseAndNull(&m_pvo); +71517227 57 push edi ; &m_pvo +71517228 c745fc01000000 mov dword ptr [ebp-0x4],0x1 ; fViewObjectChanged = TRUE +7151722f ffd3 call ebx ; call ReleaseAndNull +No_Pvo: + if (psv) { +71517231 8b7df8 mov edi,[ebp-0x8] ; edi = psv +71517234 85ff test edi,edi ; edi == 0? +71517236 7412 jz No_Psv2 (7151724a) ; jump if zero + psv->SaveViewState(); +71517238 8b07 mov eax,[edi] ; eax = psv->lpVtbl +7151723a 57 push edi ; "this" for callee +7151723b ff5034 call [eax+0x34] ; __stdcall SaveViewState +``` + +Here are more COM method calls. + +``` + psv->DestroyViewWindow(); +7151723e 8b07 mov eax,[edi] ; eax = psv->lpVtbl +71517240 57 push edi ; "this" for callee +71517241 ff5028 call [eax+0x28] ; __stdcall DestroyViewWindow + psv->Release(); +71517244 8b07 mov eax,[edi] ; eax = psv->lpVtbl +71517246 57 push edi ; "this" for callee +71517247 ff5008 call [eax+0x8] ; __stdcall Release +No_Psv2: + m_hwndView = NULL; +7151724a 83667c00 and dword ptr [esi+0x7c],0x0 ; m_hwndView = 0 +``` + +ANDing a memory location with zero is the same as setting it to zero, because anything AND zero is zero. The compiler uses this form because, even though it is slower, it is much shorter than the equivalent **mov** instruction. (This code was optimized for size, not speed.) + +``` + m_fHandsOff = FALSE; +7151724e 83a60c010000fe and dword ptr [esi+0x10c],0xfe + if (m_pcache) { +71517255 8b4670 mov eax,[esi+0x70] ; eax = m_pcache +71517258 85c0 test eax,eax ; eax == 0? +7151725a 740b jz No_Cache (71517267) ; jump if zero + GlobalFree(m_pcache); +7151725c 50 push eax ; m_pcache +7151725d ff15b4135071 call [_imp__GlobalFree] ; call GlobalFree + m_pcache = NULL; +71517263 83667000 and dword ptr [esi+0x70],0x0 ; m_pcache = 0 +No_Cache: + m_psb->EnableModelessSB(TRUE); +71517267 8b4638 mov eax,[esi+0x38] ; eax = this->m_psb +7151726a 6a01 push 0x1 ; TRUE +7151726c 50 push eax ; "this" for callee +7151726d 8b08 mov ecx,[eax] ; ecx = m_psb->lpVtbl +7151726f ff5124 call [ecx+0x24] ; __stdcall EnableModelessSB + CancelPendingActions(); +``` + +In order to call **CancelPendingActions**, you have to move from (ViewState\*)this to (CUserView\*)this. Note also that **CancelPendingActions** uses the \_\_thiscall calling convention instead of \_\_stdcall. According to \_\_thiscall, the "this" pointer is passed in the ECX register instead of being passed on the stack. + +``` +71517272 8d4eec lea ecx,[esi-0x14] ; ecx = (CUserView*)this +71517275 e832fbffff call CUserView::CancelPendingActions (71516dac) ; __thiscall + ReleaseAndNull(&_psf); +7151727a 33ff xor edi,edi ; edi = 0 (for later) +No_Psv: +7151727c 8d4678 lea eax,[esi+0x78] ; eax = &_psf +7151727f 50 push eax ; parameter +71517280 ffd3 call ebx ; call ReleaseAndNull + if (fViewObjectChanged) +71517282 397dfc cmp [ebp-0x4],edi ; fViewObjectChanged == 0? +71517285 740d jz NoNotifyViewClients (71517294) ; jump if zero + NotifyViewClients(DVASPECT_CONTENT, -1); +71517287 8b46ec mov eax,[esi-0x14] ; eax = ((CUserView*)this)->lpVtbl +7151728a 8d4eec lea ecx,[esi-0x14] ; ecx = (CUserView*)this +7151728d 6aff push 0xff ; -1 +7151728f 6a01 push 0x1 ; DVASPECT_CONTENT = 1 +71517291 ff5024 call [eax+0x24] ; __thiscall NotifyViewClients +NoNotifyViewClients: + if (m_pszTitle) +71517294 8b8680000000 mov eax,[esi+0x80] ; eax = m_pszTitle +7151729a 8d9e80000000 lea ebx,[esi+0x80] ; ebx = &m_pszTitle (for later) +715172a0 3bc7 cmp eax,edi ; eax == 0? +715172a2 7409 jz No_Title (715172ad) ; jump if zero + LocalFree(m_pszTitle); +715172a4 50 push eax ; m_pszTitle +715172a5 ff1538125071 call [_imp__LocalFree] + m_pszTitle = NULL; +``` + +Remember that EDI is still zero and EBX is still &m\_pszTitle, because those registers are preserved by function calls. + +``` +715172ab 893b mov [ebx],edi ; m_pszTitle = 0 +No_Title: + SetRect(&m_rcBounds, 0, 0, 0, 0); +715172ad 57 push edi ; 0 +715172ae 57 push edi ; 0 +715172af 57 push edi ; 0 +715172b0 81c6fc000000 add esi,0xfc ; esi = &this->m_rcBounds +715172b6 57 push edi ; 0 +715172b7 56 push esi ; &m_rcBounds +715172b8 ff15e41a5071 call [_imp__SetRect] +``` + +Notice that you do not need the value of "this" any more, so the compiler uses the **add** instruction to modify it in place instead of using up another register to hold the address. This is actually a performance win due to the Pentium u/v pipelining, because the v pipe can do arithmetic, but not address computations. + +``` + return S_OK; +715172be 33c0 xor eax,eax ; eax = S_OK +``` + +Finally, you restore the registers you are required to preserve, clean up the stack, and return to your caller, removing the incoming parameters. + +``` +715172c0 5b pop ebx ; restore +ReturnNoEBX: +715172c1 5f pop edi ; restore +715172c2 5e pop esi ; restore +715172c3 c9 leave ; restores EBP and ESP simultaneously +715172c4 c20400 ret 0x4 ; return and clear parameters +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Annotated%20x86%20Disassembly%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/application-verifier.md b/windows-driver-docs-pr/debugger/application-verifier.md new file mode 100644 index 0000000000..edf63cf0be --- /dev/null +++ b/windows-driver-docs-pr/debugger/application-verifier.md @@ -0,0 +1,42 @@ +--- +title: Application Verifier +description: Application Verifier +ms.assetid: d3040254-aa9b-4aae-b850-966078df7988 +keywords: ["verifying drivers (Application Verifier)", "driver verification (Application Verifier)", "Application Verifier", "AppVerif.exe", "user-mode application testing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Application Verifier + + +Application Verifier (AppVerif.exe) is a *dynamic verification* tool for user-mode applications. This tool monitors application actions while the application runs, subjects the application to a variety of stresses and tests, and generates a report about potential errors in application execution or design. + +Application Verifier can detect errors in any user-mode applications that are not based on managed code, including user-mode drivers. It finds subtle programming errors that might be difficult to detect during standard application testing or driver testing. + +You can use Application Verifier alone or in conjunction with a user-mode debugger. This tool runs on Microsoft Windows XP and later versions of Windows. The current user must be a member of the Administrators group on the computer. + +Application Verifier is not included in Debugging Tools for Windows. Application Verifier is included in the Windows Software Development Kit (SDK). You can find information about downloading and installing the Windows SDK [here](http://go.microsoft.com/fwlink/p?LinkID=271979). After you install the Windows SDK, Appverif.exe and Appverif.chm will be in Windows\\System32. To start Application Verifier, open a Command Prompt window and enter **appverif**. + +The Application Verifier tool comes with its own documentation. To read the documentation, start Application Verifier, and from the **Help** menu, click **Help**, or press **F1**. + +## Related topics + + +[Tools Related to Debugging Tools for Windows](tools-related-to-debugging-tools-for-windows.md) + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Application%20Verifier%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/arranging-windows.md b/windows-driver-docs-pr/debugger/arranging-windows.md new file mode 100644 index 0000000000..2b4d4e4431 --- /dev/null +++ b/windows-driver-docs-pr/debugger/arranging-windows.md @@ -0,0 +1,41 @@ +--- +title: Arranging Windows +description: Arranging Windows +ms.assetid: f6c0b778-42a8-4073-8cdb-c4b801e59274 +keywords: ["debugging information windows, suggestions for docking"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Arranging Windows + + +## + + +One useful window arrangement is to combine all of your [Source windows](source-window.md) into a single tabbed collection. The easiest way to do this is by marking your first source window as the tab-dock target for all Source windows by selecting the **Set as tab-dock target for window type** option in the Source window's short-cut menu. Once this is done, all future Source windows that are opened will automatically be included in a tabbed collection with this first Source window. The Source window marked as the tab-dock target will not be closed when the **Window | Close All Source Windows** menu command is selected. Thus you can set up a placeholder window for the Source windows that will only be closed when you want it to be. + +This collection can occupy half of the WinDbg window or you can put it in a separate dock. + +If you want each debugging information window to be completely separate, you can create one dock for each window. This arrangement enables you to minimize or maximize each window separately. + +If you want all of your windows to be floating, you should select **Always floating** on each window's shortcut menu so that you can drag each window independently to any location. + +Alternatively, you can use the [MDI Emulation](window---mdi-emulation.md) command on the **Window** menu. This command makes all of the windows floating windows and constrains them within the frame window. This behavior emulates the behavior of WinDbg before the introduction of docking mode. + +If you are using dual monitors, you can put the WinDbg window in one monitor and an extra dock in the other. + +Some standard window arrangements for various debugging scenarios are included in the Debugging Tools for Windows package. For details on these arrangements, see [Using and Customizing WinDbg Themes](using-and-customizing-windbg-themes.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Arranging%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/as--as--set-alias-.md b/windows-driver-docs-pr/debugger/as--as--set-alias-.md new file mode 100644 index 0000000000..0b1672d1d6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/as--as--set-alias-.md @@ -0,0 +1,157 @@ +--- +title: as, aS (Set Alias) +description: The as and aS commands define a new alias or redefine an existing one. +ms.assetid: 6e42122b-5a18-403b-a19a-1346bea8da12 +keywords: ["as, aS (Set Alias) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- as, aS (Set Alias) +api_type: +- NA +--- + +# as, aS (Set Alias) + + +The **as** and **aS** commands define a new alias or redefine an existing one. + +``` +as Name EquivalentLine +aS Name EquivalentPhrase +aS Name "EquivalentPhrase" +as /e Name EnvironmentVariable +as /ma Name Address +as /mu Name Address +as /msa Name Address +as /msu Name Address +as /x Name Expression +aS /f Name File +as /c Name CommandString +``` + +## Parameters + + + *Name* +Specifies the alias name. This name can be any text string that does not contain a space or the ENTER keystroke and does not begin with "al", "as", "aS", or "ad". *Name* is case sensitive. + + *EquivalentLine* +Specifies the alias equivalent. *EquivalentLine* is case sensitive. You must add at least one space between *Name* and *EquivalentLine*. The number of spaces between these two parameters is not important. The alias equivalent never contains leading spaces. After these spaces, *EquivalentLine* includes the rest of the line. Semicolons, quotation marks, and spaces are treated as literal characters, and trailing spaces are included. + + *EquivalentPhrase* +Specifies the alias equivalent. *EquivalentPhrase* is case sensitive. You must add at least one space between *Name* and *EquivalentPhrase*. The number of spaces between these two parameters is not important. The alias equivalent never contains leading spaces. + +You can enclose *EquivalentPhrase* in quotation marks ("). Regardless of whether you use quotation marks, *EquivalentPhrase* can contain spaces, commas, and single quotation marks ('). If you enclose *EquivalentPhrase* in quotation marks, it can include semicolons, but not additional quotation marks. If you do not enclose *EquivalentPhrase* in quotation marks, it can include quotation marks in any location other than the first character, but it cannot include semicolons. Trailing spaces are included regardless of whether you use quotation marks. + + **/e** +Sets the alias equivalent equal to the environment variable that *EnvironmentVariable* specifies. + + *EnvironmentVariable* +Specifies the environment variable that is used to determine the alias equivalent. The debugger's environment is used, not the target's. If you started the debugger at a Command Prompt window, the environment variables in that window are used. + + **/ma** +Sets the alias equivalent equal to the null-terminated ASCII string that begins at *Address*. + + **/mu** +Sets the alias equivalent equal to the null-terminated Unicode string that begins at *Address*. + + **/msa** +Sets the alias equivalent equal to the ANSI\_STRING structure that is located at *Address*. + + **/msu** +Sets the alias equivalent equal to the UNICODE\_STRING structure that is located at *Address*. + + *Address* +Specifies the location of the virtual memory that is used to determine the alias equivalent. + + **/x** +Sets the alias equivalent equal to the 64-bit value of *Expression*. + + *Expression* +Specifies the expression to evaluate. This value becomes the alias equivalent. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + **/f** +Sets the alias equivalent equal to the contents of the *File* file. You should always use the **/f** switch together with **aS**, not with **as**. + + *File* +Specifies the file whose contents become the alias equivalent. *File* can contain spaces, but you should never enclose *File* in quotation marks. If you specify an invalid file, you receive an "Out of memory" error message. + + **/c** +Sets the alias equivalent equal to the output of the commands that *CommandString* specifies. The alias equivalent includes carriage returns if they are present within the command display and a carriage return at the end of the display of each command (even if you specify only one command). + + *CommandString* +Specifies the commands whose outputs become the alias equivalent. This string can include any number of commands that are separated by semicolons. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to use aliases, see [Using Aliases](using-aliases.md). + +Remarks +------- + +If you do not use any switches, the **as** command uses the rest of the line as the alias equivalent. + +You can end the **aS** command by a semicolon. This technique is useful in a script when you have to put all commands on a single line. Note that if the portion of the line after the semicolon requires expansion of the alias, you must enclose that second portion of the line in a new block. The following example produces the expected output, 0x6. + +``` +0:001> aS /x myAlias 5 + 1; .block{.echo myAlias} +0x6 +``` + +If you omit the new block, you do not get the expected output. That is because the expansion of a newly set alias does not happen until a new code block is entered. In the following example, the new block is omitted, and the output is the text "myAlias" instead of the expected value 0x6. + +``` +0:001> aS /x myAlias 5 + 1; .echo myAlias +myAlias +``` + +For more information about using aliases in scripts, see [Using Aliases](using-aliases.md). + +If you use a **/e**, **/ma**, **/mu**, **/msa**, **/msu**, or **/x** switch, the **as** and **aS** commands work the same and the command ends if a semicolon is encountered. + +If *Name* is already the name of an existing alias, that alias is redefined. + +You can use the **as** or **aS** command to create or change any user-named alias. But you cannot use the command to control a fixed-name alias ($u0 to $u9). + +You can use the **/ma**, **/mu**, **/msa**, **/msu**, **/f**, and **/c** switches to create an alias that contains carriage returns. However, you cannot use an alias that contains carriage returns to execute multiple commands in sequence. Instead, you must use semicolons. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20as,%20aS%20%28Set%20Alias%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/assembling-and-disassembling-instructions.md b/windows-driver-docs-pr/debugger/assembling-and-disassembling-instructions.md new file mode 100644 index 0000000000..36ceec0e5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/assembling-and-disassembling-instructions.md @@ -0,0 +1,40 @@ +--- +title: Assembling and Disassembling Instructions +description: Assembling and Disassembling Instructions +ms.assetid: 7681bea1-4d4e-4260-950d-69cb8feb3807 +keywords: ["Debugger Engine API, assembling and disassembling"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Assembling and Disassembling Instructions + + +The debugger engine supports the use of assembly language for displaying and changing code in the target. For an overview of the use of assembly language in the debugger, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +**Note**   Assembly language is not supported for all architectures. And on some architectures not all instructions are supported. + +  + +To assemble a single assembly-language instruction and place the resulting processor instruction in the target's memory, use [**Assemble**](https://msdn.microsoft.com/library/windows/hardware/ff538121). + +To disassemble a single instruction by taking a processor instruction from the target and producing a string that represents the assembly instruction, use [**Disassemble**](https://msdn.microsoft.com/library/windows/hardware/ff541948). + +The method [**GetDisassembleEffectiveOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546581) returns the first effective address of the last instruction to be disassembled. For example, if the last instruction to be disassembled is `move ax, [ebp+4]`, the effective address is the value of `ebp+4`. This corresponds to the **$ea** pseudo-register. + +To send disassembled instructions to the output callbacks, use the methods [*OutputDisassembly*](https://msdn.microsoft.com/library/windows/hardware/ff553211) and [*OutputDisassemblyLines*](https://msdn.microsoft.com/library/windows/hardware/ff553216). + +The debugger engine has some options that control the assembly and disassembly. These options are returned by [**GetAssemblyOptions**](https://msdn.microsoft.com/library/windows/hardware/ff545605). They can be set using [**SetAssemblyOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556626) and some options can be turned on with [**AddAssemblyOptions**](https://msdn.microsoft.com/library/windows/hardware/ff537852) or turned off with [**RemoveAssemblyOptions**](https://msdn.microsoft.com/library/windows/hardware/ff554483). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Assembling%20and%20Disassembling%20Instructions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/attaching-to-a-target-computer-running-hyper-v.md b/windows-driver-docs-pr/debugger/attaching-to-a-target-computer-running-hyper-v.md new file mode 100644 index 0000000000..b7e1572bad --- /dev/null +++ b/windows-driver-docs-pr/debugger/attaching-to-a-target-computer-running-hyper-v.md @@ -0,0 +1,39 @@ +--- +title: Attaching to a Target Computer Running Hyper-V +description: Attaching to a Target Computer Running Hyper-V +ms.assetid: 379ebaf6-0599-41df-a57a-03a133ea0b02 +keywords: ["Hyper-V debugging", "Windows hypervisor debugging", "hypervisor debugging", "root partition", "parent partition", "guest partition", "child partition"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Attaching to a Target Computer Running Hyper-V + + +## + + +Windows Server 2008 Hyper-V is a virtualization platform that enables multiple operating systems to run on a single computer. Each operating system runs in an isolated virtual space known as a *partition*. The first partition, known as the *root partition* or *parent partition*, must run Windows Server 2008 or a later version of Windows. The other partitions, known as *guest partitions* or *child partitions*, may run other operating systems. Windows hypervisor, a component of Hyper-V, runs as a thin layer between these partitions and the hardware. + +Debugging Tools for Windows supports kernel debugging of the root partition, as well as kernel debugging of Windows hypervisor itself. This debugging can be done across a null-modem cable or a 1394 connection. + +The procedures used to perform this debugging are described in the following sections: + +[Debugging Hyper-V via a Null-modem Cable Connection](debugging-hyper-v-via-a-null-modem-cable-connection.md) + +[Debugging Hyper-V via a 1394 Cable Connection](debugging-hyper-v-via-a-1394-cable-connection.md) + +[Troubleshooting Hyper-V Debugging](troubleshooting-hyper-v-debugging.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Attaching%20to%20a%20Target%20Computer%20Running%20Hyper-V%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/attaching-to-a-virtual-machine--kernel-mode-.md b/windows-driver-docs-pr/debugger/attaching-to-a-virtual-machine--kernel-mode-.md new file mode 100644 index 0000000000..6b9090ed31 --- /dev/null +++ b/windows-driver-docs-pr/debugger/attaching-to-a-virtual-machine--kernel-mode-.md @@ -0,0 +1,136 @@ +--- +title: Setting Up Kernel-Mode Debugging of a Virtual Machine Manually +description: Debugging Tools for Windows supports kernel debugging of a virtual machine. +ms.assetid: e863e664-8338-4bbe-953b-e000a6843db9 +keywords: ["virtual machine debugging", "Virtual PC debugging", "VMware debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging of a Virtual Machine Manually + + +Debugging Tools for Windows supports kernel debugging of a virtual machine. The virtual machine can be located on the same physical computer as the debugger or on a different computer that is connected to the same network. This topic describes how to set up debugging of a virtual machine manually. + +As an alternative to setting up debugging of a virtual machine manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio](setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the virtual machine being debugged is called the *target virtual machine*. + +## Setting Up the Target Virtual Machine + + +1. In the virtual machine, in an elevated Command Prompt window, enter the following commands. + + **bcdedit /debug on** + + **bcdedit /dbgsettings serial debugport:***n* **baudrate:115200** + + where *n* is the number of a COM port on the virtual machine. + +2. Reboot the virtual machine. +3. In the virtual machine, configure the COM port to map to a named pipe. The debugger will connect through this pipe. For more information about how to create this pipe, see your virtual machine's documentation. + +## Starting the Debugging Session Using WinDbg + + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **COM** tab. Check the **Pipe** box, and check the **Reconnect** box. For **Baud Rate**, enter 115200. For **Resets**, enter 0. + +If the debugger is running on the same computer as the virtual machine, enter the following for **Port**. + +**\\\\.\\pipe\\***PipeName*. + +If the debugger is running on a different computer from the virtual machine, enter the following for **Port**. + +**\\\\***VMHost***\\pipe\\***PipeName* + +Click **OK**. + +You can also start WinDbg at the command line. If the debugger is running on the same physical computer as the virtual machine, enter the following command in a Command Prompt window. + +**windbg -k com:pipe,port=\\\\.\\pipe\\***PipeName***,resets=0,reconnect** + +If the debugger is running on a different physical computer from the virtual machine, enter the following command in a Command Prompt window. + +**windbg -k com:pipe,port=\\\\***VMHost***\\pipe\\***PipeName***,resets=0,reconnect** + +## Starting the Debugging Session Using KD + + +To debug a virtual machine that is running on the same physical computer as the debugger, enter the following command in a Command Prompt window. + +**kd -k com:pipe,port=\\\\.\\pipe\\***PipeName***,resets=0,reconnect** + +To debug a virtual machine that is running on a different physical computer from the debugger, enter the following command in a Command Prompt window. + +**kd -k com:pipe,port=\\\\***VMHost***\\pipe\\***PipeName***,resets=0,reconnect** + +## Parameters + + + *VMHost* +Specifies the name of the computer that the virtual machine is running on. + +*PipeName* +Specifies the name of the pipe that you created on the virtual machine. + +**resets=0** +Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. Use the **resets=0** parameter for Microsoft Virtual PC and other virtual machines whose pipes drop excess bytes. Do not use this parameter for VMware or other virtual machines whose pipes do not drop all excess bytes. + + *reconnect* +Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the debugger does not find the named pipe when the debugger is started, the *reconnect* parameter causes the debugger to wait for a pipe that is named *PipeName* to appear. Use *reconnect* for Virtual PC and other virtual machines that destroy and re-create their pipes during a computer restart. Do not use this parameter for VMware or other virtual machines that preserve their pipes during a computer restart. + +For more information about additional command-line options, see [**KD Command-Line Options**](kd-command-line-options.md) or [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +## Generation 2 Virtual Machines + + +By default, COM ports are not presented in generation 2 virtual machines. You can add COM ports through PowerShell or WMI. For the COM ports to be displayed in the Hyper-V Manager console, they must be created with a path. + +To enable kernel debugging using a COM port on a generation 2 virtual machine, follow these steps: + +1. Disable Secure Boot by entering this PowerShell command: + + **Set-VMFirmware –Vmname** *VmName* **–EnableSecureBoot Off** + + where *VmName* is the name of your virtual machine. + +2. Add a COM port to the virtual machine by entering this PowerShell command: + + **Set-VMComPort –VMName** *VmName* **1 \\\\.\\pipe\\***PipeName* + + For example, the following command configures the first COM port on virtual machine TestVM to connect to named pipe TestPipe on the local computer. + + **Set-VMComPort –VMName TestVM 1 \\\\.\\pipe\\TestPipe** + +For more information, see [Generation 2 Virtual Machine Overview](http://go.microsoft.com/fwlink/p/?Linkid=331326). + +## Remarks + + +If the target computer has stopped responding, the target computer is still stopped because of an earlier kernel debugging action, or you used the **-b** [command-line option](command-line-options.md), the debugger breaks into the target computer immediately. + +Otherwise, the target computer continues running until the debugger orders it to break. + +**Note**  If you restart the virtual machine by using the VMWare facilities (for example, the reset button), exit WinDbg, and then restart WinDbg to continue debugging. +During virtual machine debugging, VMWare often consumes 100% of the CPU. + +  + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20of%20a%20Virtual%20Machine%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/automatic-memory-dump.md b/windows-driver-docs-pr/debugger/automatic-memory-dump.md new file mode 100644 index 0000000000..54bf5959d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/automatic-memory-dump.md @@ -0,0 +1,49 @@ +--- +title: Automatic Memory Dump +description: Automatic Memory Dump +ms.assetid: A2C71497-7865-4DC8-B760-6121B224737A +--- + +# Automatic Memory Dump + + +## + + +An *Automatic Memory Dump* contains the same information as a [Kernel Memory Dump](kernel-memory-dump.md). The difference between the two is not in the dump file itself, but in the way that Windows sets the size of the system paging file. + +If the system paging file size is set to **System managed size**, and the kernel-mode crash dump is set to **Automatic Memory Dump**, then Windows can set the size of the paging file to less than the size of RAM. In this case, Windows sets the size of the paging file large enough to ensure that a kernel memory dump can be captured most of the time. + +If the computer crashes and the paging file is not large enough to capture a kernel memory dump, Windows increases the size of the paging file to at least the size of RAM. The time of this event is recorded here in the Registry: + +**HKLM**\\**SYSTEM**\\**CurrentControlSet**\\**Control**\\**CrashControl**\\**LastCrashTime** + +The increased paging file size stays in place for 4 weeks and then returns to the smaller size. If you want to return to the smaller paging file before 4 weeks, you can delete the Registry entry. + +To see the paging file settings, go to **Control Panel > System and Security > System > Advanced system settings**. Under **Performance**, click **Settings**. On the **Advanced** tab, under **Virtual memory**, click **Change**. In the Virtual Memory dialog box, you can see the paging file settings. + +![screen shot of the virtual memory dialog box.](images/virtualmemorydialog.png) + +The Automatic Memory Dump file is written to %SystemRoot%\\Memory.dmp by default. + +The Automatic Memory Dump is available in Windows 8 and later. + +**Note**  To suppress missing page error messages when debugging an Automatic Memory Dump, use the [**.ignore\_missing\_pages**](-ignore-missing-pages--suppress-missing-page-errors-.md) command. + +  + +## Related topics + + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Automatic%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/avoiding-debugger-searches-for-unneeded-symbols.md b/windows-driver-docs-pr/debugger/avoiding-debugger-searches-for-unneeded-symbols.md new file mode 100644 index 0000000000..b796d138de --- /dev/null +++ b/windows-driver-docs-pr/debugger/avoiding-debugger-searches-for-unneeded-symbols.md @@ -0,0 +1,65 @@ +--- +title: Avoiding debugger searches for unneeded symbols +description: Why does symbol loading sometimes take so long? That depends on whether the symbol name is qualified or unqualified. +ms.assetid: 710BAEAF-BC45-416E-8359-69E9DFCA2570 +--- + +# Avoiding debugger searches for unneeded symbols + + +**Last updated:** + +- May 27, 2007 + +You arrive at an interesting breakpoint while debugging your driver, only to have the debugger pause for a very long time while it attempts to load symbols for drivers that you don't own and that don't even matter for the debugging task at hand. What's going on? + +By default, symbols are loaded by the debugger as they are needed. (This is called deferred symbol loading or lazy symbol loading.) The debugger looks for symbols whenever it executes a command that calls for the display of symbols. This can happen at a breakpoint if you have set a watch variable that is not valid in the current context, such as a function parameter or local variable that doesn't exist in the current stack frame, because they become invalid when the context changes. It can also happen if you simply mistype a symbol name or execute an invalid debugger command-the debugger starts looking for a matching symbol. + +Why does this sometimes take so long? That depends on whether the symbol name is qualified or unqualified. A qualified symbol name is preceded with the name of the module that contains the symbol-for example, myModule!myVar. An unqualified symbol name does not specify a module name-for example, myOtherVar. + +In the case of the qualified name, the debugger looks for the symbol in the specified module and, if the module is not already loaded, loads the module (assuming the module exists and contains the symbol). This happens fairly quickly. + +In the case of an unqualified name, the debugger doesn't "know" which module contains the symbol, so it must look in all of them. The debugger first checks all loaded modules for the symbol and then, if it cannot match the symbol in any loaded module, the debugger continues its search by loading all unloaded modules, starting with the downstream store and ending with the symbol server, if you're using one. Obviously, this can take a lot of time. + +## How to prevent automatic loading for unqualified symbols + + +The **SYMOPT\_NO\_UNQUALIFIED\_LOADS** option disables or enables the debugger's automatic loading of modules when it searches for an unqualified symbol. When **SYMOPT\_NO\_UNQUALIFIED\_LOADS** is set and the debugger attempts to match an unqualified symbol, it searches only modules that have already been loaded, and stops searching when it cannot match the symbol, instead of loading unloaded modules to continue its search. This option does not affect searching for qualified names. + +**SYMOPT\_NO\_UNQUALIFIED\_LOADS** is off by default. To activate this option, use the **-snul** command-line option or, while the debugger is running, use **.symopt+0x100** or **.symopt-0x100** to turn the option on or off, respectively. + +To see the effect of **SYMOPT\_NO\_UNQUALIFIED\_LOADS**, try this experiment: + +1. Activate noisy symbol loading (**SYMOPT\_DEBUG**) by using the **-n** command-line option or, if the debugger is already running, use **.symopt+0x80000000** or the **!sym noisy** debugger extension command. **SYMOPT\_DEBUG** instructs the debugger to display information about its search for symbols, such as the name of each module as it is loaded or an error message if the debugger cannot find a file. +2. Instruct the debugger to evaluate a nonexistent symbol (for example, type **?asdasdasd**). The debugger should report numerous errors while it searches for the nonexistent symbol. +3. Activate **SYMOPT\_NO\_UNQUALIFIED\_LOADS** by using **.symopt+0x100**. +4. Repeat step 2. The debugger should search only loaded modules for the nonexistent symbol, and it should finish the task much faster. +5. To disable **SYMOPT\_DEBUG**, use **.symopt-0x80000000** or the **!sym quiet** debugger extension command. + +A number of options are available to control how the debugger loads and uses symbols. For a complete list of symbol options and how to use them, see "Setting Symbol Options" in the online documentation provided with Debugging Tools for Windows. The latest release of the Debugging Tools for Windows package is available as a free download from the web, or you can install the package from the Windows DDK, Platform SDK, or Customer Support Diagnostics CD. + +## What should you do? + + +- To speed up symbol searching, use qualified names in breakpoints and debugger commands whenever possible. If you want to see a symbol from a known module, qualify it with the module name; if you don't know where the symbol is, use an unqualified name. For local variables and function arguments, use **$** as the module name (for example, *$!MyVar*). +- To diagnose the causes of slow symbol loading, activate noisy symbol loading (**SYMOPT\_DEBUG**) by using the **-n** command-line option or, if the debugger is already running, by using **.symopt+0x80000000** or the **!sym noisy** debugger extension command. +- To prevent the debugger from searching for symbols in unloaded modules, activate **SYMOPT\_NO\_UNQUALIFIED\_LOADS** by using the **-snul** command-line option or, if the debugger is already running, by using **.symopt+0x100**. +- To explicitly load the modules you need for your debugging session, use debugger commands such as **.reload** or **ld**. + +## Related topics + + +[WDK and WinDbg downloads](https://go.microsoft.com/fwlink/p/?LinkId=733614) + +[Windows Debugging](http://msdn.microsoft.com/library/windows/hardware/ff551063.aspx) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Avoiding%20debugger%20searches%20for%20unneeded%20symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/b.md b/windows-driver-docs-pr/debugger/b.md new file mode 100644 index 0000000000..e3247cca3a --- /dev/null +++ b/windows-driver-docs-pr/debugger/b.md @@ -0,0 +1,54 @@ +--- +title: B (Windows Debugger Glossary) +description: Glossary page - B +Robots: noindex, nofollow +ms.assetid: 5ba110fc-1a12-4cbd-adc9-ef9441e257cb +--- + +# B + + +**blue screen** +The blue character-mode screen displayed after a bug check occurs. + +**breakpoint** +A location in the target or a target operation which will cause an event when triggered. + +For more information, see [Using Breakpoints](using-breakpoints.md). + +**breakpoint ID** +The unique identifier for a breakpoint. + +For more information, see [Using Breakpoints](using-breakpoints.md). + +**breakpoint type** +The method used to implement the breakpoint. There are two types of breakpoints: processor breakpoints and software breakpoints. + +**break status** +A setting that influences how the debugger engine proceeds after an event. The break status indicates whether the event should break into the debugger, have a notification printed to the debugger console, or be ignored. The break status is part of an event filter. + +See also [*handling status*](h.md#handling-status). + +For more information, see the topics [Controlling Exceptions and Events](controlling-exceptions-and-events.md) and [Event Filters](event-filters.md). + +**bug check** +When Windows encounters hardware problems, inconsistencies within data necessary for its operation, or other severe errors, it shuts down and displays error information on a blue character-mode screen. + +This shutdown is known variously as a bug check, kernel error, system crash, stop error, or, occasionally, trap. The screen display itself is referred to as a blue screen or stop screen. The most important information shown on the screen is a message code which gives information about the crash; this is known as a bug check code or stop code. + +WinDbg or KD can configure the system so that a debugger is automatically contacted when such an error occurs. Alternatively, the system can be instructed to automatically reboot in case of such an error. + +For more information, see [Bug Checks (Blue Screens)](bug-checks--blue-screens-.md). + +**bug check code** +The hexadecimal code indicating a specific type of bug check . + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20B%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ba--break-on-access-.md b/windows-driver-docs-pr/debugger/ba--break-on-access-.md new file mode 100644 index 0000000000..c33d0f4684 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ba--break-on-access-.md @@ -0,0 +1,191 @@ +--- +title: ba (Break on Access) +description: The ba command sets a processor breakpoint (often called, less accurately, a data breakpoint). This breakpoint is triggered when the specified memory is accessed. +ms.assetid: 0d39d883-363e-421b-a1b8-08bf2d216724 +keywords: ["ba (Break on Access) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ba (Break on Access) +api_type: +- NA +--- + +# ba (Break on Access) + + +The **ba** command sets a processor breakpoint (often called, less accurately, a *data breakpoint*). This breakpoint is triggered when the specified memory is accessed. + +User-Mode + +``` +[~Thread] ba[ID] Access Size [Options] [Address [Passes]] ["CommandString"] +``` + +Kernel-Mode + +``` +ba[ID] Access Size [Options] [Address [Passes]] ["CommandString"] +``` + +## Parameters + + + *Thread* +Specifies the thread that the breakpoint applies to. For more information about syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + *ID* +Specifies an optional number that identifies the breakpoint. If you do not specify *ID*, the first available breakpoint number is used. You cannot add space between **ba** and the ID number. Each processor supports only a limited number of processor breakpoints, but there is no restriction on the value of the *ID* number. If you enclose *ID* in square brackets (\[\]), *ID* can include any expression. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Access* +Specifies the type of access that satisfies the breakpoint. This parameter can be one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OptionAction

e (execute)

Breaks into the debugger when the CPU retrieves an instruction from the specified address.

r (read/write)

Breaks into the debugger when the CPU reads or writes at the specified address.

w (write)

Breaks into the debugger when the CPU writes at the specified address.

i (i/o)

(Microsoft Windows XP and later versions, kernel mode only, x86-based systems only) Breaks into the debugger when the I/O port at the specified Address is accessed.

+ +  + + *Size* +Specifies the size of the location, in bytes, to monitor for access. On an x86-based processor, this parameter can be 1, 2, or 4. However, if *Access* equals **e**, *Size* must be 1. + +On an x64-based processor, this parameter can be 1, 2, 4, or 8. However, if *Access* equals **e**, *Size* must be 1. + + *Options* +Specifies breakpoint options. You can use any number of the following options, except as indicated: + +**/1** +Creates a "one-shot" breakpoint. After this breakpoint is triggered, the breakpoint is permanently removed from the breakpoint list. + +**/p** *EProcess* +(Kernel mode only) Specifies a process that is associated with this breakpoint. *EProcess* should be the actual address of the EPROCESS structure, not the PID. The breakpoint is triggered only if it is encountered in the context of this process. + +**/t** *EThread* +(Kernel mode only) Specifies a thread that is associated with this breakpoint. *EThread* should be the actual address of the ETHREAD structure, not the thread ID. The breakpoint is triggered only if it is encountered in the context of this thread. If you use **/p** *EProcess* and **/t** *EThread* , you can enter them in either order. + +**/c** *MaxCallStackDepth* +Causes the breakpoint to be active only when the call stack depth is less than *MaxCallStackDepth*. You cannot combine this option together with **/C**. + +**/C** *MinCallStackDepth* +Causes the breakpoint to be active only when the call stack depth is larger than *MinCallStackDepth*. You cannot combine this option together with **/c**. + + *Address* +Specifies any valid address. If the application accesses memory at this address, the debugger stops execution and displays the current values of all registers and flags. This address must be an offset and suitably aligned to match the *Size* parameter. (For example, if *Size* is 4, *Address* must be a multiple of 4.) If you omit *Address*, the current instruction pointer is used. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Passes* +Specifies the number of times the breakpoint is passed by until it activates. This number can be any 16-bit value. The number of times the program counter passes through this point without breaking is one less than the value of this number. Therefore, omitting this number is the same as setting it equal to 1. Note also that this number counts only the times that the application *executes* past this point. Stepping or tracing past this point does not count. After the full count is reached, you can reset this number only by clearing and resetting the breakpoint. + + *CommandString* +Specifies a list of commands to execute every time that the breakpoint is encountered the specified number of times. These commands are executed only if the breakpoint is hit after you issue a [**g (Go)**](g--go-.md) command, instead of after a [**t (Trace)**](t--trace-.md) or [**p (Step)**](p--step-.md) command. Debugger commands in *CommandString* can include parameters. + +You must enclose this command string in quotation marks, and you should separate multiple commands by semicolons. You can use standard C control characters (such as **\\n** and **\\"**). Semicolons that are contained in second-level quotation marks (**\\"**) are interpreted as part of the embedded quoted string. + +This parameter is optional. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information on processor breakpoints, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). For more information about and examples of using breakpoints, other breakpoint commands and methods of controlling breakpoints, and information about how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +The debugger uses the *ID* number to refer to the breakpoint in later [**bc (Breakpoint Clear)**](bc--breakpoint-clear-.md), [**bd (Breakpoint Disable)**](bd--breakpoint-disable-.md), and [**be (Breakpoint Enable)**](be--breakpoint-enable-.md) commands. + +Use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command to list all existing breakpoints, their ID numbers, and their status. + +Use the [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them. + +Each processor breakpoint has a size associated with it. For example, a **w** (write) processor breakpoint could be set at the address 0x70001008 with a size of four bytes. This would monitor the block of addresses from 0x70001008 to 0x7000100B, inclusive. If this block of memory is written to, the breakpoint will be triggered. + +It can happen that the processor performs an operation on a memory region that *overlaps* with, but is not identical to, the specified region. In this example, a single write operation that includes the range 0x70001000 to 0x7000100F, or a write operation that includes only the byte at 0x70001009, would be an overlapping operation. In such a situation, whether the breakpoint is triggered is processor-dependent. You should consult the processor manual for specific details. To take one specific instance, on an x86 processor, a read or write breakpoint is triggered whenever the accessed range overlaps the breakpoint range. + +Similarly, if an **e** (execute) breakpoint is set on the address 0x00401003, and then a two-byte instruction spanning the addresses 0x00401002 and 0x00401003 is executed, the result is processor-dependent. Again, consult the processor architecture manual for details. + +The processor distinguishes between breakpoints set by a user-mode debugger and breakpoints set by a kernel-mode debugger. A user-mode processor breakpoint does not affect any kernel-mode processes. A kernel-mode processor breakpoint might or might not affect a user-mode process, depending on whether the user-mode code is using the debug register state and whether there is a user-mode debugger that is attached. + +To apply the current process' existing data breakpoints to a different register context, use the [**.apply\_dbp (Apply Data Breakpoint to Context)**](-apply-dbp--apply-data-breakpoint-to-context-.md) command. + +On a multiprocessor computer, each processor breakpoint applies to all processors. For example, if the current processor is 3 and you use the command `ba e1 MyAddress` to put a breakpoint at MyAddress, any processor -- not only processor 3 -- that executes at that address triggers the breakpoint. (This holds for software breakpoints as well.) + +You cannot create multiple processor breakpoints at the same address that differ only in their *CommandString* values. However, you can create multiple breakpoints at the same address that have different restrictions (for example, different values of the **/p**, **/t**, **/c**, and **/C** options). + +For more details on processor breakpoints, and additional restrictions that apply to them, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). + +The following examples show the **ba** command. The following command sets a breakpoint for read access on 4 bytes of the variable myVar. + +``` +0:000> ba r4 myVar +``` + +The following command adds a breakpoint on all serial ports with addresses from 0x3F8 through 0x3FB. This breakpoint is triggered if anything is read or written to these ports. + +``` +kd> ba i4 3f8 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ba%20%28Break%20on%20Access%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/basic-aml-debugging.md b/windows-driver-docs-pr/debugger/basic-aml-debugging.md new file mode 100644 index 0000000000..9ef79d8712 --- /dev/null +++ b/windows-driver-docs-pr/debugger/basic-aml-debugging.md @@ -0,0 +1,69 @@ +--- +title: Basic AML Debugging +description: Basic AML Debugging +ms.assetid: 2897abd4-7fef-4f9e-a4d8-10302d555fe4 +keywords: ["AMLI Debugger, basic use"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Basic AML Debugging + + +## + + +The AMLI Debugger supports two types of specialized commands: *AMLI Debugger extensions* and *AMLI Debugger commands*. + +When you are performing AML debugging, you should carefully distinguish between two different kinds of prompts that will appear in the Debugger Command window: + +- When you see the **kd>** prompt, you are controlling the kernel debugger. All the standard kernel debugger commands and extensions are available. In addition, the AMLI Debugger extensions are also available. In Windows 2000, these extensions have a syntax of **!acpikd.amli** *command*. In Windows XP and later versions of Windows, these extensions have a syntax of **!amli** *command*. The AMLI Debugger commands are not available in this mode. + +- When you see the **AMLI(? for help)->** prompt, you are controlling the AMLI Debugger. (When you are using WinDbg, this prompt will appear in the top pane of the Debugger Command window, and an **Input>** prompt will appear in the bottom pane.) From this prompt, you can enter any AMLI Debugger command. You can also enter any AMLI Debugger extension; these extensions should not be prefixed with **!amli**. The standard kernel debugging commands are not available in this mode. + +- When you see no prompt at all, the target computer is running. + +At the beginning of any debugging session, you should set your AMLI Debugger options with the [**!amli set**](-amli-set.md) extension. The **verboseon**, **traceon**, and **errbrkon** options are also very useful. When your target computer is running Windows XP or later, you should always activate the **spewon** option. See the extension reference page for details. + +There are several ways for the AMLI Debugger to become active: + +- If a breakpoint in AML code is encountered, ACPI will break into the AMLI Debugger. + +- If a serious error or exception occurs within AML code (such as an **int 3**), ACPI will break into the AMLI Debugger. + +- If the **errbrkon** option has been set, any AML error will cause ACPI to break into the AMLI Debugger. + +- If you want to deliberately break into the AMLI Debugger, use the [**!amli debugger**](-amli-debugger.md) extension and then the [**g (Go)**](g--go-.md) command. The next time any AML code is executed by the interpreter, the AMLI Debugger will take over. + +When you are at the AMLI Debugger prompt, you can type **q** to return to the kernel debugger, or type **g** to resume normal execution. + +The following extensions are especially useful for AML debugging: + +- The [**!amli dns**](-amli-dns.md) extension displays the ACPI namespace for a particular object, the namespace tree subordinate to that object, or even the entire namespace tree. This command is especially useful in determining what a particular namespace object is -- whether it is a method, a fieldunit, a device, or another type of object. + +- The [**!amli find**](-amli-find.md) extension takes the name of any namespace object and returns its full path. + +- The [**!amli u**](-amli-u.md) extension unassembles AML code. + +- The [**!amli lc**](-amli-lc.md) extension displays brief information about all active ACPI contexts. + +- The [**!amli r**](-amli-r.md) extension displays detailed information about the current context of the interpreter. This is useful when the AMLI Debugger prompt appears after an error is detected. + +- Breakpoints can be set and controlled within AML code. Use [**!amli bp**](-amli-bp.md) to set a breakpoint, [**!amli bc**](-amli-bc.md) to clear a breakpoint, [**!amli bd**](-amli-bd.md) to disable a breakpoint, [**!amli be**](-amli-be.md) to re-enable a breakpoint, and [**!amli bl**](-amli-bl.md) to list all breakpoints. + +- The AMLI Debugger is able to run, step, and trace through AML code. Use the **run**, **p**, and **t** commands to perform these actions. + +For a full list of extensions and commands, see [Using AMLI Debugger Extensions](using-amli-debugger-extensions.md) and [Using AMLI Debugger Commands](using-amli-debugger-commands.md) . + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Basic%20AML%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bc--breakpoint-clear-.md b/windows-driver-docs-pr/debugger/bc--breakpoint-clear-.md new file mode 100644 index 0000000000..87eadab295 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bc--breakpoint-clear-.md @@ -0,0 +1,78 @@ +--- +title: bc (Breakpoint Clear) +description: The bc command permanently removes previously set breakpoints from the system. +ms.assetid: 7bff5261-179f-4fd6-b427-de74e830a8c7 +keywords: ["bc (Breakpoint Clear) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bc (Breakpoint Clear) +api_type: +- NA +--- + +# bc (Breakpoint Clear) + + +The **bc** command permanently removes previously set breakpoints from the system. + +``` +bc Breakpoints +``` + +## Parameters + + + *Breakpoints* +Specifies the ID numbers of the breakpoints to remove. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (\*) to indicate all breakpoints. If you want to use a [numeric expression](numerical-expression-syntax.md) for an ID, enclose it in brackets (\[\]). If you want to use a [string with wildcard characters](string-wildcard-syntax.md) to match a breakpoint's symbolic name, enclose it in quotation marks ( " " ). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +Use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command to list all existing breakpoints, their ID numbers, and their status. + +Use the [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bc%20%28Breakpoint%20Clear%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bd--breakpoint-disable-.md b/windows-driver-docs-pr/debugger/bd--breakpoint-disable-.md new file mode 100644 index 0000000000..e27c8f0bae --- /dev/null +++ b/windows-driver-docs-pr/debugger/bd--breakpoint-disable-.md @@ -0,0 +1,82 @@ +--- +title: bd (Breakpoint Disable) +description: The bd command disables, but does not delete, previously set breakpoints. +ms.assetid: 9b408f4a-6036-41d7-b89a-3e7841c50a90 +keywords: ["bd (Breakpoint Disable) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bd (Breakpoint Disable) +api_type: +- NA +--- + +# bd (Breakpoint Disable) + + +The **bd** command disables, but does not delete, previously set breakpoints. + +``` +bd Breakpoints +``` + +## Parameters + + + *Breakpoints* +Specifies the ID numbers of the breakpoints to disable. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (\*) to indicate all breakpoints. If you want to use a [numeric expression](numerical-expression-syntax.md) for an ID, enclose it in brackets (\[\]). If you want to use a [string with wildcard characters](string-wildcard-syntax.md) to match a breakpoint's symbolic name, enclose it in quotation marks (" " ). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +When a breakpoint is disabled, the system does not check whether the conditions that are specified in the breakpoint are valid. + +Use the [**be (Breakpoint Enable)**](be--breakpoint-enable-.md) command to re-enable a disabled breakpoint. + +Use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command to list all existing breakpoints, their ID numbers, and their status. + +Use the [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bd%20%28Breakpoint%20Disable%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/be--breakpoint-enable-.md b/windows-driver-docs-pr/debugger/be--breakpoint-enable-.md new file mode 100644 index 0000000000..b13ded5b74 --- /dev/null +++ b/windows-driver-docs-pr/debugger/be--breakpoint-enable-.md @@ -0,0 +1,78 @@ +--- +title: be (Breakpoint Enable) +description: The be command restores one or more breakpoints that were previously disabled. +ms.assetid: 110fe8b0-0bc7-49ce-9c66-326d5897c0ca +keywords: ["be (Breakpoint Enable) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- be (Breakpoint Enable) +api_type: +- NA +--- + +# be (Breakpoint Enable) + + +The **be** command restores one or more breakpoints that were previously disabled. + +``` +be Breakpoints +``` + +## Parameters + + + *Breakpoints* +Specifies the ID numbers of the breakpoints to enable. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (**\***) to indicate all breakpoints. If you want to use a [numeric expression](numerical-expression-syntax.md) for an ID, enclose it in brackets (**\[\]**). If you want to use a [string with wildcard characters](string-wildcard-syntax.md) to match a breakpoint's symbolic name, enclose it in quotation marks ( **" "** ). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +Use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command to list all existing breakpoints, their ID numbers, and their status. + +Use the [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20be%20%28Breakpoint%20Enable%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bl--breakpoint-list-.md b/windows-driver-docs-pr/debugger/bl--breakpoint-list-.md new file mode 100644 index 0000000000..d10d8aecb4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bl--breakpoint-list-.md @@ -0,0 +1,124 @@ +--- +title: bl (Breakpoint List) +description: The bl command lists information about existing breakpoints. +ms.assetid: 3e7c31d4-5c76-4609-91be-c6b0fc1cb292 +keywords: ["bl (Breakpoint List) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bl (Breakpoint List) +api_type: +- NA +--- + +# bl (Breakpoint List) + + +The **bl** command lists information about existing breakpoints. + +``` +bl [/L] [Breakpoints] +``` + +## Parameters + + + **/L** +Forces **bl** to always display breakpoint addresses instead of showing source file and line numbers. + + *Breakpoints* +Specifies the ID numbers of the breakpoints to list. If you omit *Breakpoints*, the debugger lists all breakpoints. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (**\***) to indicate all breakpoints. If you want to use a [numeric expression](numerical-expression-syntax.md) for an ID, enclose it in brackets (**\[\]**). If you want to use a [string with wildcard characters](string-wildcard-syntax.md) to match a breakpoint's symbolic name, enclose it in quotation marks ( **" "** ). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +For each breakpoint, the command displays the following information: + +- The breakpoint ID. This ID is a decimal number that you can use to refer to the breakpoint in later commands. + +- The breakpoint status. The status can be **e** (enabled) or **d** (disabled). + +- (Unresolved breakpoints only) The letter "u" appears if the breakpoint is unresolved. That is, the breakpoint does not match a symbolic reference in any currently loaded module. For information about these breakpoints, see [Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md). + +- The virtual address or symbolic expression that makes up the breakpoint location. If you enabled source line number loading, the **bl** command displays file and line number information instead of address offsets. If the breakpoint is unresolved, the address is omitted here and appears at the end of the listing instead. + +- (Data breakpoints only) Type and size information are displayed for data breakpoints. The types can be **e** (execute), **r** (read/write), **w** (write), or **i** (input/output). These types are followed with the size of the block, in bytes. For information about these breakpoints, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). + +- The number of passes that remain until the breakpoint is activated, followed by the initial number of passes in parentheses. For more information about this kind of breakpoint, see the description of the *Passes* parameter in [**bp, bu, bm (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md). + +- The associated process and thread. If thread is given as three asterisks ("**\*\*\***"), this breakpoint is not a thread-specific breakpoint. + +- The module and function, with offset, that correspond to the breakpoint address. If the breakpoint is unresolved, the breakpoint address appears here instead, in parentheses. If the breakpoint is set on a valid address but symbol information is missing, this field is blank. + +- The command that is automatically executed when this breakpoint is hit. This command is displayed in quotation marks. + +If you are not sure what command was used to set an existing breakpoint, use [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) to list all breakpoints along with the commands that were used to create them. + +The following example shows the output of a **bl** command. + +Example + +``` +0:000> bl + 0 e 010049e0 0001 (0001) 0:**** stst!main +``` + +This output contains the following information: + +- The breakpoint ID is **0**. + +- The breakpoint status is **e** (enabled). + +- The breakpoint is not unresolved (there is no **u** in the output). + +- The virtual address of the breakpoint is **010049e0**. + +- The breakpoint is active on the first pass through the code and the code has not yet been executed under the debugger. This information is indicated by a value of 1 (**0001**) in the "passes remaining" counter and a value of 1 (**(0001)**) in the initial passes counter. + +- This breakpoint is not a thread-specific breakpoint (**\*\*\*\***). + +- The breakpoint is set on **main** in the **stst** module. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bl%20%28Breakpoint%20List%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/blue-screen-data.md b/windows-driver-docs-pr/debugger/blue-screen-data.md new file mode 100644 index 0000000000..283b0f54a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/blue-screen-data.md @@ -0,0 +1,179 @@ +--- +title: Blue Screen Data +description: When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a bug check or stop error. +ms.assetid: 8cc42643-e231-49dd-96b0-6cb528d5d7a9 +keywords: ["Blue Screen Data Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Blue Screen Data +api_type: +- NA +--- + +# Blue Screen Data + + +**Note**  This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://go.microsoft.com/fwlink/p/?linkid=183646). + +  + +**Note**   If you are an IT professional or support agent, see this article for additional information, [Troubleshoot "blue screen" or Stop error problems before you contact Microsoft Support](https://support.microsoft.com/help/3106831/troubleshoot-blue-screen-or-stop-error-problems-before-you-contact-microsoft-support). + +  + +When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a *bug check*. It is also commonly referred to as a *system crash*, a *kernel error*, or a *stop error*. + +If the OS were allowed to continue to run after the operating system integrity is compromised, it could corrupt data or compromise the security of the system. + +If crash dumps are enabled on the system, a crash dump file is created. + +If a kernel debugger is attached and active, the system causes a break so that the debugger can be used to investigate the crash. + +If no debugger is attached, a blue text screen appears with information about the error. This screen is called a *blue screen*, a *bug check screen*, or a *stop screen*. + +If you are using an insider build of Windows, the text will be displayed on a green background. + +The exact appearance of the blue screen depends on the cause of the error. + +The following is an example of one possible blue screen: + +![bug check example windows 10 blue screen with qr code](images/bug-check-example-blue-screen-page-fault.png) + +The stop code is displayed such as [**PAGE\_FAULT\_IN\_NONPAGED\_AREA**](bug-check-0x50--page-fault-in-nonpaged-area.md). When it is available, the module name of the code that was being executed is also displayed, such as AcmeVideo.sys. + +If a [kernel-mode dump file](kernel-mode-dump-files.md) has been written, this will be indicated as well with a percentage complete count down as the dump is being written. + +There is a stop code hex value associated with each stop code as listed in [Bug Check Code Reference](bug-check-code-reference2.md). + +## + + +### Gathering the Stop Code Parameters + +Each bug check code has four associated parameters that provide additional information. The parameters are described in [Bug Check Code Reference](bug-check-code-reference2.md) for each stop code. + +There are multiple ways to gather the four stop code parameters. + +- Examine the Windows system log in the event viewer. The event properties for the BugCheck will list the four stop code parameters. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). + +- Load the generated dump file and use the [**!analyze**](-analyze.md) command with the debugger attached. For more information, see [Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md). + +- Attach a kernel debugger to the faulting PC. When the stop code occurs, the debugger output will include the four parameters after the stop code hex value. + + ``` + ******************************************************************************* + * * + * Bugcheck Analysis * + * * + ******************************************************************************* + + Use !analyze -v to get detailed debugging information. + + BugCheck 9F, {3, ffffe000f38c06a0, fffff803c596cad0, ffffe000f46a1010} + + Implicit thread is now ffffe000`f4ca3040 + Probably caused by : hidusb.sys + ``` + +### Bug Check Symbolic Names + +[**DRIVER\_POWER\_STATE\_FAILURE**](bug-check-0x9f--driver-power-state-failure.md) is the Bug Check Symbolic Name, with an associated bug check code of 9F. The stop code hex value associated with the Bug Check Symbolic Name is listed in the [Bug Check Code Reference](bug-check-code-reference2.md). + +### Reading Bug Check Information from the Debugger + +If a debugger is attached, a bug check will cause the target computer to break into the debugger. In this case, the blue screen may not appear immediately, the full details on this crash will be sent to the debugger and appear in the debugger window. To see this information a second time, use the [**.bugcheck (Display Bug Check Data)**](-bugcheck--display-bug-check-data-.md) command or the [**!analyze**](-analyze.md) extension command. + +**Kernel Debugging and Crash Dump Analysis** + +Kernel debugging is especially useful when other troubleshooting techniques fail, or for a recurring problem. Remember to capture the exact text in the bug check information section of the error message. To isolate a complex problem and develop a viable workaround, it is useful to record the exact actions that lead to the failure. + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md) + +The Defrag Tools show on Channel 9 - + +### Using Driver Verifier to Gather Information + +It is estimated that about three quarters of blue screens are caused by faulting drivers. Driver Verifier is a tool that runs in real time to examine the behavior of drivers. For example, Driver Verifier checks the use of memory resources, such as memory pools. If it see errors in the execution of driver code, it proactively creates an exception to allow that part of the driver code to be further scrutinized. The driver verifier manager is built into Windows and is available on all Windows PCs. To start the driver verifier manager, type *Verifier* at a command prompt. You can configure which drivers you would like to verify. The code that verifies drivers adds overhead as it runs, so try and verify the smallest number of drivers as possible. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +## Tips for Software Engineers + + +When a bug check occurs as a result of code you have written, you should use the kernel debugger to analyze the problem, and then fix the bugs in your code. For full details, see the individual bug check code in the [Bug Check Code Reference](bug-check-code-reference2.md) section. + +However, you might also encounter bug checks that are not caused by your own code. In this case, you probably will not be able to fix the actual cause of the problem, so your goal should be to work around the problem, and if possible isolate and remove the hardware or software component that is at fault. + +Many problems can be resolved through basic troubleshooting procedures, such as verifying instructions, reinstalling key components, and verifying file dates. Also, the Event Viewer, the Sysinternals diagnostic tools and network monitoring tools might isolate and resolve these issues. + +For general troubleshooting of Windows bug check codes, follow these suggestions: + +- If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available. + +- If new device drivers or system services have been added recently, try removing or updating them. Try to determine what changed in the system that caused the new bug check code to appear. + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- Run the Windows Memory Diagnostics tool, to test the memory. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes. Make sure the virus detection program checks the Master Boot Record for infections. + +- Use the scan disk utility to confirm that there are no file system errors. Right click on the drive you want to scan and select **Properties**. Click on **Tools**. Click the **Check now** button. +- Use the System File Checker tool to repair missing or corrupted system files. The System File Checker is a utility in Windows that allows users to scan for corruptions in Windows system files and restore corrupted files. Use the following command to run the System File Checker tool (SFC.exe). + + ``` + SFC /scannow + ``` + + For more information, see [Use the System File Checker tool to repair missing or corrupted system files](https://support.microsoft.com/kb/929833). + +- Confirm that there is sufficient free space on the hard drive. The operating system and some applications require sufficient free space to create swap files and for other functions. Based on the system configuration, the exact requirement varies, but it is normally a good idea to have 10% to 15% free space available. + +- Verify that the system has the latest Service Pack installed. To detect which Service Pack, if any, is installed on your system, click **Start**, click **Run**, type **winver**, and then press ENTER. The **About Windows** dialog box displays the Windows version number and the version number of the Service Pack, if one has been installed. + +- Check with the manufacturer to see if an updated system BIOS or firmware is available. + +- Disable BIOS memory options such as caching or shadowing. + +- For PCs, make sure that all expansion boards are is properly seated and all cables are completely connected. + +**Using Safe Mode** + +Consider using Safe Mode when removing or disabling components. Using Safe Mode loads only the minimum required drivers and system services during the Windows startup. To enter Safe Mode, use **Update and Security** in Settings. Select **Recovery**->**Advanced startup** to boot to maintenance mode. At the resulting menu, choose **Troubleshoot**-> **Advanced Options** -> **Startup Settings** -> **Restart**. After Windows restarts to the **Startup Settings** screen, select option, 4, 5 or 6 to boot to Safe Mode. + +Safe Mode may be available by pressing a function key on boot, for example F8. Refer to information from the manufacturer for specific startup options. + +## Forced KeBugCheck + + +To deliberately cause a bug check from a kernel-mode driver, you need to pass the bug check's symbolic name to the **KeBugCheck** or **KeBugCheckEx** function. This should only be done in circumstances where no other option is available. For more details on these functions, see the Windows Driver Kit. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Blue%20Screen%20Data%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bluetooh-extensions--bthkd-dll-.md b/windows-driver-docs-pr/debugger/bluetooh-extensions--bthkd-dll-.md new file mode 100644 index 0000000000..f20fbaf5e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bluetooh-extensions--bthkd-dll-.md @@ -0,0 +1,112 @@ +--- +title: Bluetooth Extensions (Bthkd.dll) +description: The Bluetooth debugger extensions display information about the current Bluetooth environment on the target system. +ms.assetid: F6C5295D-F1F9-4180-BE57-A7D47AC8690C +--- + +# Bluetooth Extensions (Bthkd.dll) + + +The Bluetooth debugger extensions display information about the current Bluetooth environment on the target system. + +**Note**  As you work with the Bluetooth debugging extensions, you may come across undocumented behavior or APIs. We strongly recommend against taking dependencies on undocumented behavior or APIs as it's subject to change in future releases. + +  + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[!bthkd.bthdevinfo](-bthkd-bthdevinfo.md)

The [!bthkd.bthdevinfo](-bthkd-bthdevinfo.md) command displays the information about a given BTHENUM created device PDO.

[!bthkd.bthenuminfo](-bthkd-bthenuminfo.md)

The [!bthkd.bthenuminfo](-bthkd-bthenuminfo.md) command displays information about the BTHENUM FDO.

[!bthkd.bthinfo](-bthkd-bthinfo-.md)

The [!bthkd.bthinfo](-bthkd-bthinfo-.md) command displays details about the BTHPORT FDO. This command is a good starting point for Bluetooth investigations as it displays address information that can be used to access many of the other Bluetooth debug extension commands.

[!bthkd.bthhelp](-bthkd-bthhelp.md)

The [!bthkd.bthhelp](-bthkd-bthhelp.md) command displays help for the Bluetooth debug extension commands.

[!bthkd.bthtree](-bthkd-bthtree.md)

The [!bthkd.bthtree](-bthkd-bthtree.md) command displays the complete Bluetooth device tree.

[!bthkd.bthusbtransfer](-bthkd-bthusbtransfer.md)

The [!bthkd.bthusbtransfer](-bthkd-bthusbtransfer.md) command displays the Bluetooth usb transfer context including Irp, Bip and transfer buffer information.

[!bthkd.dibflags](-bthkd-dibflags.md)

The [!bthkd.dibflags](-bthkd-dibflags.md) command displays DEVICE_INFO_BLOCK.DibFlags dumps flags set in _DEVICE_INFO_BLOCK.DibFlags.

[!bthkd.hcicmd](-bthkd-hcicmd.md)

The [!bthkd.hcicmd](-bthkd-hcicmd.md) command displays a list of the currently pending commands.

[!bthkd.hciinterface](-bthkd-hciinterface.md)

The [!bthkd.hciinterface](-bthkd-hciinterface.md) command displays the bthport!_HCI_INTERFACE structure.

[!bthkd.l2capinterface](-bthkd-l2capinterface-.md)

The [!bthkd.l2capinterface](-bthkd-l2capinterface-.md) command displays information about the L2CAP interface.

[!bthkd.rfcomminfo](-bthkd-rfcomminfo.md)

The [!bthkd.rfcomminfo](-bthkd-rfcomminfo.md) command displays information about the RFCOMM FDO and the TDI Device Object.

[!bthkd.rfcommconnection](-bthkd-rfcommconnection.md)

The [!bthkd.rfcommconnection](-bthkd-rfcommconnection.md) command displays information about a given RFCOMM connection object.

[!bthkd.rfcommchannel](-bthkd-rfcommchannel.md)

The [!bthkd.rfcommchannel](-bthkd-rfcommchannel.md) command displays information about a given RFCOMM channel CB.

[!bthkd.sdpinterface](-bthkd-sdpinterface.md)

The [!bthkd.sdpinterface](-bthkd-sdpinterface.md) command displays information about the SDP interface.

[!bthkd.scointerface](-bthkd-scointerface-.md)

The [!bthkd.scointerface](-bthkd-scointerface-.md) command displays information about the SCO interface.

[!bthkd.sdpnode](-bthkd-sdpnode.md)

The [!bthkd.sdpnode](-bthkd-sdpnode.md) command displays information about a node in an sdp tree.

[!bthkd.sdpstream](-bthkd-sdpstream.md)

The [!bthkd.sdpstream](-bthkd-sdpstream.md) command displays the contents of a SDP stream.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Bluetooth%20Extensions%20%28Bthkd.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bp--bu--bm--set-breakpoint-.md b/windows-driver-docs-pr/debugger/bp--bu--bm--set-breakpoint-.md new file mode 100644 index 0000000000..c4bc35c430 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bp--bu--bm--set-breakpoint-.md @@ -0,0 +1,222 @@ +--- +title: bp, bu, bm (Set Breakpoint) +description: The bp, bu, and bm commands set one or more software breakpoints. You can combine locations, conditions, and options to set different kinds of software breakpoints. +ms.assetid: 77d095fe-06d1-4842-ad49-8420ab4d5d72 +keywords: ["bp, bu, bm (Set Breakpoint) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bp, bu, bm (Set Breakpoint) +api_type: +- NA +--- + +# bp, bu, bm (Set Breakpoint) + + +The **bp**, **bu**, and **bm** commands set one or more software breakpoints. You can combine locations, conditions, and options to set different kinds of software breakpoints. + +User-Mode + +``` +[~Thread] bp[ID] [Options] [Address [Passes]] ["CommandString"] +[~Thread] bu[ID] [Options] [Address [Passes]] ["CommandString"] +[~Thread] bm [Options] SymbolPattern [Passes] ["CommandString"] +``` + +Kernel-Mode + +``` +bp[ID] [Options] [Address [Passes]] ["CommandString"] +bu[ID] [Options] [Address [Passes]] ["CommandString"] +bm [Options] SymbolPattern [Passes] ["CommandString"] +``` + +## Parameters + + + *Thread* +Specifies the thread that the breakpoint applies to. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. If you do not specify a thread, the breakpoint applies to all threads. + + *ID* +Specifies a decimal number that identifies a breakpoint. + +The debugger assigns the *ID* when it creates the breakpoint, but you can change it by using the [**br (Breakpoint Renumber)**](br--breakpoint-renumber-.md) command. You can use the *ID* to refer to the breakpoint in later debugger commands. To display the *ID* of a breakpoint, use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command. + +When you use *ID* in a command, do not type a space between the command (**bp** or **bu**) and the ID number. + +The *ID* parameter is always optional. If you do not specify *ID*, the debugger uses the first available breakpoint number. In kernel mode, you can set only 32 breakpoints. In user mode, you can set any number of breakpoints. In either case, there is no restriction on the value of the *ID* number. If you enclose *ID* in square brackets (**\[\]**), *ID* can include any expression. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Options* +Specifies breakpoint options. You can specify any number of the following options, except as indicated: + +**/1** +Creates a "one-shot" breakpoint. After this breakpoint is triggered, it is deleted from the breakpoint list. + +**/f** *PredNum* +(Itanium-based only, user mode only) Specifies a predicate number. The breakpoint is predicated with the corresponding predicate register. (For example, **bp /f 4** *address* sets a breakpoint that is predicated with the **p4** predicate register.) + +**/p** *EProcess* +(Kernel-mode only) Specifies a process that is associated with this breakpoint. *EProcess* should be the actual address of the EPROCESS structure, not the PID. The breakpoint is triggered only if it is encountered in the context of this process. + +**/t** *EThread* +(Kernel-mode only) Specifies a thread that is associated with this breakpoint. *EThread* should be the actual address of the ETHREAD structure, not the thread ID. The breakpoint is triggered only if it is encountered in the context of this thread. If you use **/p** *EProcess* and **/t** *EThread*, you can enter them in any order. + +**/c** *MaxCallStackDepth* +Activates the breakpoint only when the call stack depth is less than *MaxCallStackDepth*. You cannot use this option together with **/C**. + +**/C** *MinCallStackDepth* +Activates the breakpoint only when the call stack depth is larger than *MinCallStackDepth*. You cannot use this option together with **/c**. + +**/a** +(For **bm** only) Sets breakpoints on all of the specified locations, whether they are in data space or code space. Because breakpoints on data can cause program failures, use this option only on locations that are known to be safe. + +**/d** +(For **bm** only) Converts the breakpoint locations to addresses. Therefore, if the code is moved, the breakpoints remain at the same address, instead of being set according to *SymbolPattern*. Use **/d** to avoid reevaluating changes to breakpoints when modules are loaded or unloaded. + +**/(** +(For **bm** only) Includes parameter list information in the symbol string that *SymbolString* defines. + +This feature enables you to set breakpoints on overloaded functions that have the same name but different parameter lists. For example, bm /( myFunc sets breakpoints on both **myFunc(int a)** and **myFunc(char a)**. Without "/(", a breakpoint that is set on **myFunc** fails because it does not indicate which **myFunc** function the breakpoint is intended for. + + *Address* +Specifies the first byte of the instruction where the breakpoint is set. If you omit *Address*, the current instruction pointer is used. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Passes* +Specifies the number of the execution pass that the breakpoint is activated on. The debugger skips the breakpoint location until it reaches the specified pass. The value of *Passes* can be any 16-bit or 32-bit value. + +By default, the breakpoint is active the first time that the application executes the code that contains the breakpoint location. This default situation is equivalent to a value of **1** for *Passes*. To activate the breakpoint only after the application executes the code at least one time, enter a value of **2** or more. For example, a value of **2** activates the breakpoint the second time that the code is executed. + +This parameter creates a counter that is decremented on each pass through the code. To see the initial and current values of the *Passes* counter, use [**bl (Breakpoint List)**](bl--breakpoint-list-.md). + +The *Passes* counter is decremented only when the application *executes* past the breakpoint in response to a [**g (Go)**](g--go-.md) command. The counter is not decremented if you are stepping through the code or tracing past it. When the *Passes* counter reaches **1**, you can reset it only by clearing and resetting the breakpoint. + + *CommandString* +Specifies a list of commands that are executed every time that the breakpoint is encountered the specified number of times. You must enclose the *CommandString* parameter in quotation marks. Use semicolons to separate multiple commands. + +Debugger commands in *CommandString* can include parameters. You can use standard C-control characters (such as **\\n** and **\\"**). Semicolons that are contained in second-level quotation marks (**\\"**) are interpreted as part of the embedded quoted string. + +The *CommandString* commands are executed only if the breakpoint is reached while the application is *executing* in response to a [**g (Go)**](g--go-.md) command. The commands are not executed if you are stepping through the code or tracing past this point. + +Any command that resumes program execution after a breakpoint (such as **g** or **t**) ends the execution of the command list. + + *SymbolPattern* +Specifies a pattern. The debugger tries to match this pattern to existing symbols and to set breakpoints on all pattern matches. *SymbolPattern* can contain a variety of wildcard characters and specifiers. For more information about this syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). Because these characters are being matched to symbols, the match is not case sensitive, and a single leading underscore (\_) represents any quantity of leading underscores. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +The **bp**, **bu**, and **bm** commands set new breakpoints, but they have different characteristics: + +- The **bp (Set Breakpoint)** command sets a new breakpoint at the *address* of the breakpoint location that is specified in the command. If the debugger cannot resolve the address expression of the breakpoint location when the breakpoint is set, the **bp** breakpoint is automatically converted to a **bu** breakpoint. Use a **bp** command to create a breakpoint that is no longer active if the module is unloaded. + +- The **bu (Set Unresolved Breakpoint)** command sets a *deferred* or *unresolved* breakpoint. A **bu** breakpoint is set on a symbolic reference to the breakpoint location that is specified in the command (not on an address) and is activated whenever the module with the reference is resolved. For more information about these breakpoints, see [Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md). + +- The **bm (Set Symbol Breakpoint)** command sets a new breakpoint on symbols that match a specified pattern. This command can create more than one breakpoint. By default, after the pattern is matched, **bm** breakpoints are the same as **bu** breakpoints. That is, **bm** breakpoints are deferred breakpoints that are set on a symbolic reference. However, a bm /d command creates one or more **bp** breakpoints. Each breakpoint is set on the address of a matched location and does not track module state. + +If you are not sure what command was used to set an existing breakpoint, use [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) to list all breakpoints along with the commands that were used to create them. + +There are three primary differences between **bp** breakpoints and **bu** breakpoints: + +- A **bp** breakpoint location is always converted to an address. If a module change moves the code at which a **bp** breakpoint was set, the breakpoint remains at the same address. On the other hand, a **bu** breakpoint remains associated with the symbolic value (typically a symbol plus an offset) that was used, and it tracks this symbolic location even if its address changes. + +- If a **bp** breakpoint address is found in a loaded module, and if that module is later unloaded, the breakpoint is removed from the breakpoint list. On the other hand, **bu** breakpoints persist after repeated unloads and loads. + +- Breakpoints that you set with **bp** are not saved in WinDbg [workspaces](using-workspaces.md). Breakpoints that are set with **bu** are saved in workspaces. + +The **bm** command is useful when you want to use wildcard characters in the symbol pattern for a breakpoint. The **bm** *SymbolPattern* syntax is equivalent to using [**x SymbolPattern**](x--examine-symbols-.md) and then using **bu** on each result. For example, to set breakpoints on all of the symbols in the *Myprogram* module that begin with the string "mem," use the following command. + +Example + +``` +0:000> bm myprogram!mem* + 4: 0040d070 MyProgram!memcpy + 5: 0040c560 MyProgram!memmove + 6: 00408960 MyProgram!memset +``` + +Because the **bm** command sets software breakpoints (not processor breakpoints), it automatically excludes data location when it sets breakpoints to avoid corrupting the data. + +It is possible to specify a data address rather than a program address when using the **bp** or bm /a commands. However, even if a data location is specified, these commands create software breakpoints, not processor breakpoints. If a software breakpoint is placed in program data instead of executable code, it can lead to data corruption. Therefore you should use these commands in a data location only if you are certain that the memory stored in that location will be used as executable code and not as program data. Otherwise, you should use the [**ba (Break on Access)**](ba--break-on-access-.md) command instead. For more details, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). + +For details on how to set a breakpoint on a location specified by a more complicated syntax, such as a member of a C++ public class, or an arbitrary text string containing otherwise restricted characters, see [Breakpoint Syntax](breakpoint-syntax.md). + +If a single logical source line spans multiple physical lines, the breakpoint is set on the last physical line of the statement or call. If the debugger cannot set a breakpoint at the requested position, it puts the breakpoint in the next allowed position. + +If you specify *Thread*, breakpoints are set on the specified threads. For example, the **~\*bp** command sets breakpoints on all threads, **~\#bp** sets a breakpoint on the thread that causes the current exception, and **~123bp** sets a breakpoint on thread 123. The **~bp** and **~.bp** commands both set a breakpoint on the current thread. + +When you are debugging a multiprocessor system in kernel mode, breakpoints that you set by using **bp** or [**ba (Break on Access)**](ba--break-on-access-.md) apply to all processors. For example, if the current processor is 3 and you type **bp MemoryAddress** to put a breakpoint at **MemoryAddress**. Any processor that is executing at that address (not only processor 3) causes a breakpoint trap. + +The **bp**, **bu**, and **bm** commands set software breakpoints by replacing the processor instruction with a break instruction. To debug read-only code or code that cannot be changed, use a ba e command, where **e** represents execute-only access. + +The following command sets a breakpoint 12 bytes past the beginning of the function **MyTest**. This breakpoint is ignored for the first six passes through the code, but execution stops on the seventh pass through the code. + +``` +0:000> bp MyTest+0xb 7 +``` + +The following command sets a breakpoint at **RtlRaiseException**, displays the **eax** register, displays the value of the symbol **MyVar**, and continues. + +``` +kd> bp ntdll!RtlRaiseException "r eax; dt MyVar; g" +``` + +The following two **bm** commands set three breakpoints. When the commands are executed, the displayed result does not distinguish between breakpoints created with the **/d** switch and those created without it. The [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) can be used to distinguish between these two types. If the breakpoint was created by **bm** without the **/d** switch, the **.bpcmds** display indicates the breakpoint type as **bu**, followed by the evaluated symbol enclosed in the **@!""** token (which indicates it is a literal symbol and not a numeric expression or register). If the breakpoint was created by **bm** with the **/d** switch, the **.bpcmds** display indicates the breakpoint type as **bp**. + +``` +0:000> bm myprog!openf* + 0: 00421200 @!"myprog!openFile" + 1: 00427800 @!"myprog!openFilter" + +0:000> bm /d myprog!closef* + 2: 00421600 @!"myprog!closeFile" + +0:000> .bpcmds +bu0 @!"myprog!openFile"; +bu1 @!"myprog!openFilter"; +bp2 0x00421600 ; +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bp,%20bu,%20bm%20%28Set%20Breakpoint%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/br--breakpoint-renumber-.md b/windows-driver-docs-pr/debugger/br--breakpoint-renumber-.md new file mode 100644 index 0000000000..956f0cade6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/br--breakpoint-renumber-.md @@ -0,0 +1,81 @@ +--- +title: br (Breakpoint Renumber) +description: The br command renumbers one or more breakpoints. +ms.assetid: 1b41eb37-3375-4203-bbf5-f55869383db8 +keywords: ["br (Breakpoint Renumber) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- br (Breakpoint Renumber) +api_type: +- NA +--- + +# br (Breakpoint Renumber) + + +The **br** command renumbers one or more breakpoints. + +``` +br OldID NewID [OldID2 NewID2 ...] +``` + +## Parameters + + + *OldID* +Specifies the current ID number of the breakpoint. + + *NewID* +Specifies a new number that becomes the ID of the breakpoint. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +You can use the **br** command to renumber any number of breakpoints at the same time. For each breakpoint, list the old ID and the new ID, in that order, as parameters to **br**. + +If there is already a breakpoint with an ID equal to *NewID*, the command fails and an error message is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20br%20%28Breakpoint%20Renumber%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/breaking-into-the-debugger.md b/windows-driver-docs-pr/debugger/breaking-into-the-debugger.md new file mode 100644 index 0000000000..38f0d6489d --- /dev/null +++ b/windows-driver-docs-pr/debugger/breaking-into-the-debugger.md @@ -0,0 +1,65 @@ +--- +title: Breaking Into the Debugger +description: Breaking Into the Debugger +ms.assetid: 4fec7170-7480-4a8a-b060-1c8a8c3fb9dc +keywords: ["breaking into the debugger", "DebugBreak function", "DbgBreakPoint function", "KdBreakPoint function", "DbgBreakPointWithStatus function", "KdBreakPointWithStatus function", "ASSERT macro", "ASSERTMSG macro"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Breaking Into the Debugger + + +## + + +User-mode and kernel-mode code use different routines to break into the debugger. + +### User-Mode Break Routines + +A break routine causes an exception to occur in the current process, so that the calling thread can signal the debugger associated with the calling process. + +To break into a debugger from a user-mode program, use the **DebugBreak** routine. For complete documentation of this routine, see the Microsoft Windows SDK. + +When a user-mode program calls **DebugBreak**, the following possible actions will occur: + +1. If a user-mode debugger is attached, the program will break into the debugger. This means that the program will pause and the debugger will become active. + +2. If no user-mode debugger is attached, but kernel-mode debugging was enabled at boot time, the entire computer will break into the kernel debugger. If no kernel debugger is attached, the computer will freeze and await a kernel debugger. + +3. If no user-mode debugger is attached, and kernel-mode debugging is not enabled, the program will terminate with an unhandled exception, and the post-mortem (just-in-time) debugger will be activated. For more information, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +### Kernel-Mode Break Routines + +When a kernel-mode program breaks into the debugger, the entire operating system freezes until the kernel debugger allows execution to resume. If no kernel debugger is present, this is treated as a bug check. + +The **DbgBreakPoint** routine works in kernel-mode code, but is otherwise similar to the **DebugBreak** user-mode routine. + +**DbgBreakPointWithStatus** also causes a break, but it additionally sends a 32-bit status code to the debugger. + +**KdBreakPoint** and **KdBreakPointWithStatus** are identical to **DbgBreakPoint** and **DbgBreakPointWithStatus**, respectively, when compiled in the checked build environment. When compiled in the free build environment, they have no effect. + +For complete documentation of these routines, as well as the build environment, see the Windows Driver Kit. + +### Kernel-Mode Conditional Break Routines + +Two conditional break routines are available for kernel-mode code. These routines test a logical expression. If the expression is false, execution halts and the debugger becomes active. + +The **ASSERT** macro causes the debugger to display the failed expression and its location in the program. The **ASSERTMSG** macro is similar, but allows an additional message to be sent to the debugger. + +**ASSERT** and **ASSERTMSG** are only active when compiled in the checked build environment. When compiled in the free build environment, they have no effect. + +For complete documentation of these routines, as well as the build environment, see the Windows Driver Kit. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Breaking%20Into%20the%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/breakpoint-syntax.md b/windows-driver-docs-pr/debugger/breakpoint-syntax.md new file mode 100644 index 0000000000..117edf1bed --- /dev/null +++ b/windows-driver-docs-pr/debugger/breakpoint-syntax.md @@ -0,0 +1,96 @@ +--- +title: Breakpoint Syntax +description: This topic covers breakpoint syntax +ms.assetid: 86228b87-9ca3-4d0c-be9e-63446ac6ce31 +keywords: debugger, breakpoints on methods, breakpoints, syntax rules for commands, b (breakpoint identifier), literal MASM identifier, templated functions +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Breakpoint Syntax + + +## + + +The following syntax elements can be used when creating a [breakpoint](using-breakpoints.md), either through the Debugger Command window or through the WinDbg graphical interface. + +### Addresses in Breakpoints + +Breakpoints support many kinds of address syntax, including virtual addresses, function offsets, and source line numbers. For example, you can use any of the following commands to set breakpoints: + +``` +0:000> bp 0040108c +0:000> bp main+5c +0:000> bp `source.c:31` +``` + +For more information about this syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md), [Source Line Syntax](source-line-syntax.md), and the individual command topics. + +### Breakpoints on Methods + +If you want to put a breakpoint on the *MyMethod* method in the *MyClass* class, you can use two different syntaxes: + +- In MASM expression syntax, you can indicate a method by a double colon or by a double underscore. + + ``` + 0:000> bp MyClass::MyMethod + 0:000> bp MyClass__MyMethod + ``` + +- In C++ expression syntax, you must indicate a method by a double colon. + + ``` + 0:000> bp @@( MyClass::MyMethod ) + ``` + +If you want to use a more complex breakpoint command, you should use MASM expression syntax. For more information about expression syntax, see [Evaluating Expressions](evaluating-expressions.md). + +### Breakpoints Using Complicated Text + +To set a breakpoint on complicated functions, including functions that contain spaces, as well as a member of a C++ public class, enclose the expression in parentheses. For example, use **bp (??MyPublic)** or **bp (operator new)**. + +A more versatile technique is to use the @!"chars" syntax. This is a special escape in the MASM evaluator that enables you to provide arbitrary text for symbol resolution. You must start with the three symbols @!" and end with a quotation mark ("). Without this syntax, you cannot use spaces, angle brackets (<, >), or other special characters in symbol names in the MASM evaluator. This syntax is exclusively for names, and not parameters. Templates and overloads are the primary sources of symbols that require this quote notation. You can also set the **bu** command by using the @!"chars" syntax, as the following code example shows. + +``` +0:000> bu @!"ExecutableName!std::pair,std::allocator > >::operator=" +``` + +In this example, *ExecutableName* is the name of an executable file. + +This escape syntax is more useful for C++ (for example, overloaded operators) instead of C because there are no spaces (or special characters) in C function names. However, this syntax is also important for a lot of managed code because of the considerable use of overloads in the .NET Framework. + +To set a breakpoint on arbitrary text in C++ syntax, use **bu @@c++(***text***)** for C++-compatible symbols. + +### Breakpoints in Scripts + +Breakpoint IDs do not have to be referred to explicitly. Instead, you can use a numerical expression that resolves to an integer that corresponds to a breakpoint ID. To indicate that the expression should be interpreted as a breakpoint, use the following syntax. + +``` +b?[Expression] +``` + +In this syntax, the square brackets are required, and *Expression* stands for any numerical expression that resolves to an integer that corresponds to a breakpoint ID. + +This syntax allows debugger scripts to programmatically select a breakpoint. In the following example, the breakpoint changes depending on the value of a user-defined pseudo-register. + +``` +b?[@$t0] +``` + +### Breakpoint Pseudo-Registers + +If you want to refer to a breakpoint address in an expression, you can use a [pseudo-register](pseudo-register-syntax.md) with the **$bp***Number* syntax, where *Number* is the breakpoint ID. For more information about this syntax, see Pseudo-Register Syntax. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Breakpoint%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/breakpoints3.md b/windows-driver-docs-pr/debugger/breakpoints3.md new file mode 100644 index 0000000000..5db66f8d71 --- /dev/null +++ b/windows-driver-docs-pr/debugger/breakpoints3.md @@ -0,0 +1,48 @@ +--- +title: Breakpoints +description: Breakpoints +ms.assetid: f805667c-7ee1-4f66-bfc5-7e3b90b35b86 +keywords: ["Debugger Engine, breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Breakpoints + + +The [debugger engine](introduction.md#debugger-engine) can create and monitor breakpoints in the target. + +There are two types of breakpoints that the engine can insert into a target: software breakpoints and processor breakpoints. + +- *Software breakpoints* are inserted into the target's code by modifying the processor instruction at the breakpoint's location. The debugger engine keeps track of such breakpoints; they are invisible to the clients reading and writing memory at that location. A software breakpoint is triggered when the target executes the modified instruction. + +- *Processor breakpoints* are inserted into the target's processor by the debugger engine. A processor breakpoint can be triggered by different actions, for example, executing an instruction at the location (like software breakpoints), or reading or writing memory at the breakpoint's location. Support for processor breakpoints is dependent on the processor in the target's computer. + +A breakpoint's address can be specified by an explicit address, by an expression that evaluates to an address, or by an expression that might evaluate to an address at a future time. In the last case, each time a module is loaded or unloaded in the target, the engine will attempt to reevaluate the expression and insert the breakpoint if it can determine the address; this makes it possible to set breakpoints in modules before they are loaded. + +A number of parameters can be associated with a breakpoint to control its behavior: + +- A breakpoint can be associated with a particular thread in the target and will only be triggered by that thread. + +- A breakpoint can have debugger commands associated with it; these commands will automatically be executed when the breakpoint is triggered. + +- A breakpoint can be flagged as inactive until the target has passed it a specified number of times. + +- A breakpoint can be automatically removed the first time it is triggered. + +### Additional Information + +For details about using breakpoints, see [Using Breakpoints](setting-breakpoints.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bs--update-breakpoint-command-.md b/windows-driver-docs-pr/debugger/bs--update-breakpoint-command-.md new file mode 100644 index 0000000000..4c78fd9be0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bs--update-breakpoint-command-.md @@ -0,0 +1,85 @@ +--- +title: bs (Update Breakpoint Command) +description: The bs command changes the command executed when the specified breakpoint is encountered. +ms.assetid: 624c9a30-a0d8-49bd-aba6-a46250022677 +keywords: ["bs (Update Breakpoint Command) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bs (Update Breakpoint Command) +api_type: +- NA +--- + +# bs (Update Breakpoint Command) + + +The **bs** command changes the command executed when the specified breakpoint is encountered. + +``` +bs ID ["CommandString"] +``` + +## Parameters + + + *ID* +Specifies the ID number of the breakpoint. + + *CommandString* +Specifies the new list of commands to be executed every time that the breakpoint is encountered. You must enclose the *CommandString* parameter in quotation marks. Use semicolons to separate multiple commands. + +Debugger commands in *CommandString* can include parameters. You can use standard C-control characters (such as **\\n** and **\\"**). Semicolons that are contained in second-level quotation marks (**\\"**) are interpreted as part of the embedded quoted string. + +The *CommandString* commands are executed only if the breakpoint is reached while the application is executing in response to a **g (Go)** command. The commands are not executed if you are stepping through the code or tracing past this point. + +Any command that resumes program execution after a breakpoint (such as **g** or **t**) ends the execution of the command list. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +If the *CommandString* is not specified, any commands already set on the breakpoint are removed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bs%20%28Update%20Breakpoint%20Command%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bsc--update-conditional-breakpoint-.md b/windows-driver-docs-pr/debugger/bsc--update-conditional-breakpoint-.md new file mode 100644 index 0000000000..e413668697 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bsc--update-conditional-breakpoint-.md @@ -0,0 +1,94 @@ +--- +title: bsc (Update Conditional Breakpoint) +description: The bsc command changes the condition under which a breakpoint occurs or changes the command executed when the specified conditional breakpoint is encountered. +ms.assetid: 4d491797-3ba2-4a63-a575-67df39484bcf +keywords: ["bsc (Update Conditional Breakpoint) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- bsc (Update Conditional Breakpoint) +api_type: +- NA +--- + +# bsc (Update Conditional Breakpoint) + + +The **bsc** command changes the condition under which a breakpoint occurs or changes the command executed when the specified conditional breakpoint is encountered. + +``` +bsc ID Condition ["CommandString"] +``` + +## Parameters + + + *ID* +Specifies the ID number of the breakpoint. + + *Condition* +Specifies the condition under which the breakpoint should be triggered. + + *CommandString* +Specifies the new list of commands to be executed every time that the breakpoint is encountered. You must enclose the *CommandString* parameter in quotation marks. Use semicolons to separate multiple commands. + +Debugger commands in *CommandString* can include parameters. You can use standard C-control characters (such as **\\n** and **\\"**). Semicolons that are contained in second-level quotation marks (**\\"**) are interpreted as part of the embedded quoted string. + +The CommandString commands are executed only if the breakpoint is reached while the application is executing in response to a **g (Go)** command. The commands are not executed if you are stepping through the code or tracing past this point. + +Any command that resumes program execution after a breakpoint (such as **g** or **t**) ends the execution of the command list. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +Remarks +------- + +If the *CommandString* is not specified, any commands already set on the breakpoint are removed. + +The same effect can be achieved by using the [**bs (Update Breakpoint Command)**](bs--update-breakpoint-command-.md) command with the following syntax: + +``` +bs ID "j Condition 'CommandString'; 'gc'" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20bsc%20%28Update%20Conditional%20Breakpoint%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/buffer-dbgprint-output.md b/windows-driver-docs-pr/debugger/buffer-dbgprint-output.md new file mode 100644 index 0000000000..b2a11872b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/buffer-dbgprint-output.md @@ -0,0 +1,62 @@ +--- +title: Buffer DbgPrint Output +description: Buffer DbgPrint Output +ms.assetid: af97c484-3a37-4c86-8828-12a0ea1c8c0e +keywords: ["Buffer DbgPrint Output (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Buffer DbgPrint Output + + +## + + +The **Buffer DbgPrint Output** flag suppresses debugger output from **DbgPrint**, **DbgPrintEx**, **KdPrint**, and **KdPrintEx** calls. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

ddp

Hexadecimal value

0x08000000

Symbolic Name

FLG_DISABLE_DBGPRINT

Destination

System-wide registry entry, kernel flag

+ +  + +### Comments + +When debugger output is suppressed, it does not automatically appear in the kernel debugger. However, the message is always sent to the DbgPrint buffer, where it can be accessed by using the [**!dbgprint**](-dbgprint.md) debugger extension. + +For information about the functions that communicate with the debugger, see [Sending Output to the Debugger](sending-output-to-the-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Buffer%20DbgPrint%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check---bug-check-0x139-kernel-security-check-failure.md b/windows-driver-docs-pr/debugger/bug-check---bug-check-0x139-kernel-security-check-failure.md new file mode 100644 index 0000000000..43f2e0b57e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check---bug-check-0x139-kernel-security-check-failure.md @@ -0,0 +1,110 @@ +--- +title: Bug Check 0x139 KERNEL_SECURITY_CHECK_FAILURE +description: The KERNEL_SECURITY_CHECK_FAILURE bug check has a value of 0x00000139. This bug check indicates that the kernel has detected the corruption of a critical data structure. +ms.assetid: C0E5C625-13DB-4B3A-8080-69CEB963A299 +keywords: ["Bug Check 0x139 KERNEL_SECURITY_CHECK_FAILURE", "Bug Check 0x139 KERNEL_SECURITY_CHECK_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Bug Check 0x139 KERNEL_SECURITY_CHECK_FAILURE +api_type: +- NA +--- + +# Bug Check 0x139: KERNEL\_SECURITY\_CHECK\_FAILURE + + +The KERNEL\_SECURITY\_CHECK\_FAILURE bug check has a value of 0x00000139. This bug check indicates that the kernel has detected the corruption of a critical data structure. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## Bug Check 0x139 KERNEL\_SECURITY\_CHECK\_FAILURE Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------------------------------------------| +| 1 | The type of corruption. For more information, see the following table. | +| 2 | Address of the trap frame for the exception that caused the bug check | +| 3 | Address of the exception record for the exception that caused the bug check | +| 4 | Reserved | + +  + +The following table describes possible values for Parameter 1. + +| Parameter 1 | Description | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | A stack-based buffer has been overrun (legacy /GS violation). | +| 1 | VTGuard instrumentation code detected an attempt to use an illegal virtual function table. Typically, a C++ object was corrupted, and then a virtual method call was attempted using the corrupted object's **this** pointer. | +| 2 | Stack cookie instrumentation code detected a stack-based buffer overrun (/GS violation). | +| 3 | A LIST\_ENTRY was corrupted (for example, a double remove). For more information, see the following Cause section. | +| 4 | Reserved | +| 5 | An invalid parameter was passed to a function that considers invalid parameters fatal. | +| 6 | The stack cookie security cookie was not properly initialized by the loader. This may be caused by building a driver to run only on Windows 8 and attempting to load the driver image on an earlier version of Windows. To avoid this problem, you must build the driver to run on an earlier version of Windows. | +| 7 | A fatal program exit was requested. | +| 8 | A array bounds check inserted by the compiler detected an illegal array indexing operation. | +| 9 | A call to **RtlQueryRegistryValues** was made specifying RTL\_QUERY\_REGISTRY\_DIRECT without RTL\_QUERY\_REGISTRY\_TYPECHECK, and the target value was not in a trusted system hive. | + +  + +Cause +----- + +Using the parameter 1 table, and a dump file, it is possible to narrow down the cause for many bug checks of this type. + +LIST\_ENTRY corruption can be difficult to track down and this bug check, indicates that an inconsistency has been introduced into a doubly-linked list (detected when an individual list entry element is added to or removed from the list). Unfortunately, the inconsistency is not necessarily detected at the time when the corruption occurred, so some detective work may be necessary to identify the root cause. + +Common causes of list entry corruption include: + +- A driver has corrupted a kernel synchronization object, such as a KEVENT (for example double initializing a KEVENT while a thread was still waiting on that same KEVENT, or allowing a stack-based KEVENT to go out of scope while another thread was using that KEVENT). This type of bug check typically occurs in nt!Ke\* or nt!Ki\* code. It can happen when a thread finishes waiting on a synchronization object or when code attempts to put a synchronization object in the signaled state. Usually, the synchronization object being signaled is the one that has been corrupted. Sometimes, Driver Verifier with special pool can help track down the culprit (if the corrupted synchronization object is in a pool block that has already been freed). +- A driver has corrupted a periodic KTIMER. This type of bug check typically occurs in nt!Ke\* or nt!Ki\* code and involves signaling a timer, or inserting or removing a timer from a timer table. The timer being manipulated may be the corrupted one, but it might be necessary to inspect the timer table with [**!timer**](-timer.md) (or manually walking the timer list links) to identify which timer has been corrupted. Sometimes, Driver Verifier with special pool can help track down the culprit (if the corrupted KTIMER is in a pool block that has already been freed). +- A driver has mismanaged an internal LIST\_ENTRY-style linked list. A typical example would be calling **RemoveEntryList** twice on the same list entry without reinserting the list entry between the two **RemoveEntryList** calls. Other variations are possible, such as double inserting an entry into the same list. +- A driver has freed a data structure that contains a LIST\_ENTRY without removing the data structure from its corresponding list, causing corruption to be detected later when the list is examined after the old pool block has been reused. +- A driver has used a LIST\_ENTRY-style list in a concurrent fashion without proper synchronization, resulting in a torn update to the list. + +In most cases, you can identify the corrupted data structure by walking the linked list both forward and backwards (the [**dl**](dl--display-linked-list-.md) and **dlb** commands are useful for this purpose) and comparing the results. Where the list is inconsistent between a forward and backward walk is typically the location of the corruption. Since a linked list update operation can modify the list links of a neighboring element, you should look at the neighbors of a corrupted list entry closely, as they may be the underlying culprit. + +Because many system components internally utilize LIST\_ENTRY lists, various types of resource mismanagement by a driver using system APIs might cause linked list corruption in a system-managed linked list. + +Resolution +---------- + +Determining the cause of this issues typically requires the use of the debugger to gather additional information. Multiple dump files should be examined to see if this stop code has similar characteristics, such as the code that is running when the stop code appears. + +For more information, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md), [Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md). + +Use the event log to see if there are higher level events that occur leading up to this stop code. + +These general troubleshooting tips may be helpful. + +- If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available. + +- If new device drivers or system services have been added recently, try removing or updating them. Try to determine what changed in the system that caused the new bug check code to appear. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +- Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes. Make sure the virus detection program checks the Master Boot Record for infections. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +## See also + + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x11e--too-many-recursive-faults.md b/windows-driver-docs-pr/debugger/bug-check--0x11e--too-many-recursive-faults.md new file mode 100644 index 0000000000..7adfb81e35 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x11e--too-many-recursive-faults.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x11E TOO_MANY_RECURSIVE_FAULTS +description: The TOO_MANY_RECURSIVE_FAULTS bug check has a value of 0x0000011E. This indicates that a file system has caused too many recursive faults under low resource conditions to be handled. +ms.assetid: E945719A-ACFA-4DDF-8176-7ABEF41E1C47 +keywords: ["Bug Check 0x11E TOO_MANY_RECURSIVE_FAULTS", "TOO_MANY_RECURSIVE_FAULTS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TOO_MANY_RECURSIVE_FAULTS +api_type: +- NA +--- + +# Bug Check 0x11E: TOO\_MANY\_RECURSIVE\_FAULTS + + +The TOO\_MANY\_RECURSIVE\_FAULTS bug check has a value of 0x0000011E. This indicates that a file system has caused too many recursive faults under low resource conditions to be handled. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TOO\_MANY\_RECURSIVE\_FAULTS Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x11f--invalid-driver-handle.md b/windows-driver-docs-pr/debugger/bug-check--0x11f--invalid-driver-handle.md new file mode 100644 index 0000000000..e9b6798040 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x11f--invalid-driver-handle.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x11F INVALID_DRIVER_HANDLE +description: The INVALID_DRIVER_HANDLE bug check has a value of 0x0000011F. This indicates that someone has closed the initial handle for a driver between inserting the driver object and referencing the handle. +ms.assetid: A669256B-737D-4215-8E0E-5500D7704F4E +keywords: ["Bug Check 0x11F INVALID_DRIVER_HANDLE", "INVALID_DRIVER_HANDLE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_DRIVER_HANDLE +api_type: +- NA +--- + +# Bug Check 0x11F: INVALID\_DRIVER\_HANDLE + + +The INVALID\_DRIVER\_HANDLE bug check has a value of 0x0000011F. This indicates that someone has closed the initial handle for a driver between inserting the driver object and referencing the handle. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_DRIVER\_HANDLE Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------------------| +| 1 | The handle value for the driver object. | +| 2 | The status returned trying to reference the object. | +| 3 | The address of the PDRIVER\_OBJECT. | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x120--bitlocker-fatal-error-.md b/windows-driver-docs-pr/debugger/bug-check--0x120--bitlocker-fatal-error-.md new file mode 100644 index 0000000000..e8a4790bb5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x120--bitlocker-fatal-error-.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x120 BITLOCKER_FATAL_ERROR +description: The BITLOCKER_FATAL_ERROR bug check has a value of 0x00000120. This indicates that BitLocker drive encryption encountered a problem that it cannot recover from. +ms.assetid: 24AF3FB3-2F4A-499D-8E55-0761FC350AE5 +keywords: ["Bug Check 0x120 BITLOCKER_FATAL_ERROR", "BITLOCKER_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BITLOCKER_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x120: BITLOCKER\_FATAL\_ERROR + + +The BITLOCKER\_FATAL\_ERROR bug check has a value of 0x00000120. This indicates that BitLocker drive encryption encountered a problem that it cannot recover from. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BITLOCKER\_FATAL\_ERROR Parameters + + +| Parameter | Description | +|-----------|-----------------| +| 1 | Type of problem | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x123--crypto-self-test-failure-.md b/windows-driver-docs-pr/debugger/bug-check--0x123--crypto-self-test-failure-.md new file mode 100644 index 0000000000..33c1710055 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x123--crypto-self-test-failure-.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x123 CRYPTO_SELF_TEST_FAILURE +description: The CRYPTO_SELF_TEST_FAILURE bug check has a value of 0x00000123. This indicates that the cryptographic subsystem failed a mandatory algorithm self-test during bootstrap. +ms.assetid: 003FFB3D-1DAF-4A09-B70D-5B1242B4FAD8 +keywords: ["Bug Check 0x123 CRYPTO_SELF_TEST_FAILURE", "CRYPTO_SELF_TEST_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRYPTO_SELF_TEST_FAILURE +api_type: +- NA +--- + +# Bug Check 0x123: CRYPTO\_SELF\_TEST\_FAILURE + + +The CRYPTO\_SELF\_TEST\_FAILURE bug check has a value of 0x00000123. This indicates that the cryptographic subsystem failed a mandatory algorithm self-test during bootstrap. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CRYPTO\_SELF\_TEST\_FAILURE Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x125--nmr-invalid-state.md b/windows-driver-docs-pr/debugger/bug-check--0x125--nmr-invalid-state.md new file mode 100644 index 0000000000..1886497c7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x125--nmr-invalid-state.md @@ -0,0 +1,96 @@ +--- +title: Bug Check 0x125 NMR_INVALID_STATE +description: The NMR_INVALID_STATE bug check has a value of 0x00000125. This indicates that NMR (network module registrar) has detected an invalid state. See parameter 1 for the state type. +ms.assetid: DD80FC61-8211-46A0-9D44-CF1E729B12D4 +keywords: ["Bug Check 0x125 NMR_INVALID_STATE", "NMR_INVALID_STATE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NMR_INVALID_STATE +api_type: +- NA +--- + +# Bug Check 0x125: NMR\_INVALID\_STATE + + +The NMR\_INVALID\_STATE bug check has a value of 0x00000125. This indicates that NMR (network module registrar) has detected an invalid state. See parameter 1 for the state type. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NMR\_INVALID\_STATE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

The subtype of the bugcheck.

+

0x0 : Machine Check Exception

+

Parameter 2 - Address of the WHEA_ERROR_RECORD structure.

+

Parameter 3 - High order 32-bits of the MCi_STATUS value.

+

Parameter 4 - Low order 32-bits of the MCi_STATUS value.

+

0x1 : Corrected Machine Check

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x2 : Corrected Platform Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x3 : Non-maskable Interrupt

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x4 : PCI Express Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x5 : Generic Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x6 : INIT Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x7 : BOOT Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x8 : SCI Generic Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0x9 : Itanium Machine Check Abort

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +Parameter 3 - Length in bytes of the SAL log. +Parameter 4 - Address of the SAL log. +

0xa : Itanium Corrected Machine Check

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure. +

0xb : Itanium Corrected Platform Error

+Parameter 2 - Address of the WHEA_ERROR_RECORD structure.
2Pointer to the NMI Handle
3Pointer to the expected type, when available
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x126--netio-invalid-pool-caller.md b/windows-driver-docs-pr/debugger/bug-check--0x126--netio-invalid-pool-caller.md new file mode 100644 index 0000000000..560cf518aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x126--netio-invalid-pool-caller.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0x126 NETIO_INVALID_POOL_CALLER +description: The NETIO_INVALID_POOL_CALLER bug check has a value of 0x00000126. This indicates that an invalid pool request has been made to netio managed memory pool, e.g. FSB and MDL. +ms.assetid: D155D39D-0E8B-4BA5-91B4-AF8F291F7F1F +keywords: ["Bug Check 0x126 NETIO_INVALID_POOL_CALLER", "NETIO_INVALID_POOL_CALLER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NETIO_INVALID_POOL_CALLER +api_type: +- NA +--- + +# Bug Check 0x126: NETIO\_INVALID\_POOL\_CALLER + + +The NETIO\_INVALID\_POOL\_CALLER bug check has a value of 0x00000126. This indicates that an invalid pool request has been made to netio managed memory pool, e.g. FSB and MDL. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NETIO\_INVALID\_POOL\_CALLER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

The subtype of the bugcheck.

+

0x1 : Invalid pool. Pool is at an invalid state.

+Parameter 2 - Pointer to memory block or MDL. +Parameter 3 - Pointer to page. +Parameter 4 - Pointer to CPU pool. +

0x2 : Invalid MDL. MDL is at an invalid state.

+Parameter 2 - Pointer to MDL. +Parameter 3 - Pointer to CPU pool. +Parameter 4 - Pointer to pool header.
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check--0x20001--hypervisor-error.md b/windows-driver-docs-pr/debugger/bug-check--0x20001--hypervisor-error.md new file mode 100644 index 0000000000..22287d0a1c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check--0x20001--hypervisor-error.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x20001 HYPERVISOR_ERROR +description: The HYPERVISOR_ERROR bug check has a value of 0x00020001. This indicates that the hypervisor has encountered a fatal error. +ms.assetid: 5F62DEEA-D192-46ED-827C-021A749D7091 +keywords: ["Bug Check 0x20001 HYPERVISOR_ERROR", "HYPERVISOR_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HYPERVISOR_ERROR +api_type: +- NA +--- + +# Bug Check 0x20001: HYPERVISOR\_ERROR + + +The HYPERVISOR\_ERROR bug check has a value of 0x00020001. This indicates that the hypervisor has encountered a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## HYPERVISOR\_ERROR Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1--apc-index-mismatch.md b/windows-driver-docs-pr/debugger/bug-check-0x1--apc-index-mismatch.md new file mode 100644 index 0000000000..9c8f41108a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1--apc-index-mismatch.md @@ -0,0 +1,101 @@ +--- +title: Bug Check 0x1 APC_INDEX_MISMATCH +description: 0x00000001. +ms.assetid: 01e64516-809c-49ce-9aaa-b4e439ac575b +keywords: ["Bug Check 0x1 APC_INDEX_MISMATCH", "APC_INDEX_MISMATCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- APC_INDEX_MISMATCH +api_type: +- NA +--- + +# Bug Check 0x1: APC\_INDEX\_MISMATCH + + +The APC\_INDEX\_MISMATCH bug check has a value of 0x00000001. This indicates that there has been a mismatch in the APC (asynchronous procedure calls) state index. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## APC\_INDEX\_MISMATCH Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the system function (system call) or worker routine.

2

The value of the current thread's ApcStateIndex field.

3

The value of current thread's CombinedApcDisable field. This field consists of two separate 16-bit fields: (Thread->SpecialApcDisable << 16) | Thread->KernelApcDisable.

4

Call type (0 - system call, 1 - worker routine).

+ +  + +Cause +----- + +The most common cause of this bug check is when a file system or driver has a mismatched sequence of calls to disable and re-enable APCs. The key data item is the *Thread*->**CombinedApcDisable** field. The **CombinedApcDisable** field consists of two separate 16-bit fields: **SpecialApcDisable** and **KernelApcDisable**. A negative value of either field indicates that a driver has disabled special or normal APCs (respectively) without re-enabling them. A positive value indicates that a driver has enabled special or normal APCs too many times. + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +You can use the [**!apc**](-apc.md) extension to displays the contents of one or more asynchronous procedure calls (APCs). + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Remarks +------- + +This is a kernel internal error. This error occurs on exit from a system call. A possible cause for this bug check is when a file system or driver has a mismatched sequence of system calls to enter or leave guarded or critical regions. For example, each call to [**KeEnterCriticalRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552021) must have a matching call to [**KeLeaveCriticalRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552964). If you are developing a driver, you can use [Static Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff552808), a static analysis tool available in the Windows Driver Kit, to detect problems in your code before you ship your driver. Run Static Driver Verifier with the [CriticalRegions](https://msdn.microsoft.com/library/windows/hardware/ff543603) rule to verify that your source code uses these system calls in correct sequence. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10--spin-lock-not-owned.md b/windows-driver-docs-pr/debugger/bug-check-0x10--spin-lock-not-owned.md new file mode 100644 index 0000000000..dc8bed0546 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10--spin-lock-not-owned.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x10 SPIN_LOCK_NOT_OWNED +description: The SPIN_LOCK_NOT_OWNED bug check has a value of 0x00000010.This bug check appears very infrequently. +ms.assetid: ffef2d3d-43e9-48aa-a905-8656207da6a8 +keywords: ["Bug Check 0x10 SPIN_LOCK_NOT_OWNED", "SPIN_LOCK_NOT_OWNED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SPIN_LOCK_NOT_OWNED +api_type: +- NA +--- + +# Bug Check 0x10: SPIN\_LOCK\_NOT\_OWNED + + +The SPIN\_LOCK\_NOT\_OWNED bug check has a value of 0x00000010. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x100---loader-block-mismatch.md b/windows-driver-docs-pr/debugger/bug-check-0x100---loader-block-mismatch.md new file mode 100644 index 0000000000..31583c0094 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x100---loader-block-mismatch.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x100 LOADER_BLOCK_MISMATCH +description: The LOADER_BLOCK_MISMATCH bug check has a value of 0x00000100. This indicates that either the loader block is invalid, or it does not match the system that is being loaded. +ms.assetid: 4f025141-ab81-4acd-9114-a6701e1000d3 +keywords: ["Bug Check 0x100 LOADER_BLOCK_MISMATCH", "LOADER_BLOCK_MISMATCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LOADER_BLOCK_MISMATCH +api_type: +- NA +--- + +# Bug Check 0x100: LOADER\_BLOCK\_MISMATCH + + +The LOADER\_BLOCK\_MISMATCH bug check has a value of 0x00000100. This indicates that either the loader block is invalid, or it does not match the system that is being loaded. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## LOADER\_BLOCK\_MISMATCH Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

3

2

The size of the loader black extension

3

The major version of the loader block

4

The minor version of the loader block

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1000007e--system-thread-exception-not-handled-m.md b/windows-driver-docs-pr/debugger/bug-check-0x1000007e--system-thread-exception-not-handled-m.md new file mode 100644 index 0000000000..9d91f183ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1000007e--system-thread-exception-not-handled-m.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1000007E SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M +description: The SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M bug check has a value of 0x1000007E. +ms.assetid: 830c44e7-c801-4545-8154-c980329720a8 +keywords: ["Bug Check 0x1000007E SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M", "SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M +api_type: +- NA +--- + +# Bug Check 0x1000007E: SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED\_M + + +The SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED\_M bug check has a value of 0x1000007E. This indicates that a system thread generated an exception which the error handler did not catch. + +Bug check 0x1000007E has the same meaning and parameters as [**bug check 0x7E**](bug-check-0x7e--system-thread-exception-not-handled.md) (SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1000007f--unexpected-kernel-mode-trap-m.md b/windows-driver-docs-pr/debugger/bug-check-0x1000007f--unexpected-kernel-mode-trap-m.md new file mode 100644 index 0000000000..fbac051a18 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1000007f--unexpected-kernel-mode-trap-m.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1000007F UNEXPECTED_KERNEL_MODE_TRAP_M +description: The UNEXPECTED_KERNEL_MODE_TRAP_M bug check has a value of 0x1000007F. +ms.assetid: 913355b6-f569-4535-a6cc-bdc6071b76ff +keywords: ["Bug Check 0x1000007F UNEXPECTED_KERNEL_MODE_TRAP_M", "UNEXPECTED_KERNEL_MODE_TRAP_M"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNEXPECTED_KERNEL_MODE_TRAP_M +api_type: +- NA +--- + +# Bug Check 0x1000007F: UNEXPECTED\_KERNEL\_MODE\_TRAP\_M + + +The UNEXPECTED\_KERNEL\_MODE\_TRAP\_M bug check has a value of 0x1000007F. This indicates that a trap was generated by the Intel CPU and the kernel failed to catch this trap. + +Bug check 0x1000007F has the same meaning and parameters as [**bug check 0x7F**](bug-check-0x7f--unexpected-kernel-mode-trap.md) (UNEXPECTED\_KERNEL\_MODE\_TRAP). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1000008e--kernel-mode-exception-not-handled-m.md b/windows-driver-docs-pr/debugger/bug-check-0x1000008e--kernel-mode-exception-not-handled-m.md new file mode 100644 index 0000000000..70fe02323c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1000008e--kernel-mode-exception-not-handled-m.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1000008E KERNEL_MODE_EXCEPTION_NOT_HANDLED_M +description: The KERNEL_MODE_EXCEPTION_NOT_HANDLED_M bug check has a value of 0x1000008E. +ms.assetid: 1ed1d625-685a-40d3-b97b-37480190801d +keywords: ["Bug Check 0x1000008E KERNEL_MODE_EXCEPTION_NOT_HANDLED_M", "KERNEL_MODE_EXCEPTION_NOT_HANDLED_M"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_MODE_EXCEPTION_NOT_HANDLED_M +api_type: +- NA +--- + +# Bug Check 0x1000008E: KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED\_M + + +The KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED\_M bug check has a value of 0x1000008E. This indicates that a kernel-mode program generated an exception which the error handler did not catch. + +Bug check 0x1000008E has the same meaning and parameters as [**bug check 0x8E**](bug-check-0x8e--kernel-mode-exception-not-handled.md) (KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x100000ea--thread-stuck-in-device-driver-m.md b/windows-driver-docs-pr/debugger/bug-check-0x100000ea--thread-stuck-in-device-driver-m.md new file mode 100644 index 0000000000..ac9a178454 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x100000ea--thread-stuck-in-device-driver-m.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x100000EA THREAD_STUCK_IN_DEVICE_DRIVER_M +description: The THREAD_STUCK_IN_DEVICE_DRIVER_M bug check has a value of 0x100000EA. This indicates that a device driver thread is endlessly spinning.This has the same meaning/parameters as bug check 0xEA. +ms.assetid: 0b46e836-0563-4fa9-be96-125caeab08d8 +keywords: ["Bug Check 0x100000EA THREAD_STUCK_IN_DEVICE_DRIVER_M", "THREAD_STUCK_IN_DEVICE_DRIVER_M"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- THREAD_STUCK_IN_DEVICE_DRIVER_M +api_type: +- NA +--- + +# Bug Check 0x100000EA: THREAD\_STUCK\_IN\_DEVICE\_DRIVER\_M + + +The THREAD\_STUCK\_IN\_DEVICE\_DRIVER\_M bug check has a value of 0x100000EA. This indicates that a thread in a device driver is endlessly spinning. + +Bug check 0x100000EA has the same meaning and parameters as [**bug check 0xEA**](bug-check-0xea--thread-stuck-in-device-driver.md) (THREAD\_STUCK\_IN\_DEVICE\_DRIVER). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x101---clock-watchdog-timeout.md b/windows-driver-docs-pr/debugger/bug-check-0x101---clock-watchdog-timeout.md new file mode 100644 index 0000000000..7ae9151d30 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x101---clock-watchdog-timeout.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x101 CLOCK_WATCHDOG_TIMEOUT +description: The CLOCK_WATCHDOG_TIMEOUT bug check has a value of 0x00000101 that indicates that an expected clock interrupt on a secondary processor, was not received within the allocated interval. +ms.assetid: 2e35d8c5-00b3-4722-b596-a76f38eb5179 +keywords: ["Bug Check 0x101 CLOCK_WATCHDOG_TIMEOUT", "CLOCK_WATCHDOG_TIMEOUT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CLOCK_WATCHDOG_TIMEOUT +api_type: +- NA +--- + +# Bug Check 0x101: CLOCK\_WATCHDOG\_TIMEOUT + + +The CLOCK\_WATCHDOG\_TIMEOUT bug check has a value of 0x00000101. This indicates that an expected clock interrupt on a secondary processor, in a multi-processor system, was not received within the allocated interval. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CLOCK\_WATCHDOG\_TIMEOUT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Clock interrupt time-out interval, in nominal clock ticks

2

0

3

The address of the processor control block (PRCB) for the unresponsive processor

4

0

+ +  + +Cause +----- + +The specified processor is not processing interrupts. Typically, this occurs when the processor is nonresponsive or is deadlocked. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x102--dpc-watchdog-timeout.md b/windows-driver-docs-pr/debugger/bug-check-0x102--dpc-watchdog-timeout.md new file mode 100644 index 0000000000..fdd77d098f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x102--dpc-watchdog-timeout.md @@ -0,0 +1,56 @@ +--- +title: Bug Check 0x102 DPC_WATCHDOG_TIMEOUT +description: The DPC_WATCHDOG_TIMEOUT bug check has a value of 0x00000102. This indicates that The DPC watchdog routine was not executed within the allocated time interval. +ms.assetid: 1BEC2701-3127-4FB9-AD0F-DD54A9F2C2C3 +keywords: ["Bug Check 0x102 DPC_WATCHDOG_TIMEOUT", "DPC_WATCHDOG_TIMEOUT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DPC_WATCHDOG_TIMEOUT +api_type: +- NA +--- + +# Bug Check 0x102: DPC\_WATCHDOG\_TIMEOUT + + +The DPC\_WATCHDOG\_TIMEOUT bug check has a value of 0x00000102. This indicates that The DPC watchdog routine was not executed within the allocated time interval. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DPC\_WATCHDOG\_TIMEOUT Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------------| +| 1 | DPC watchdog time out interval in nominal clock ticks. | +| 2 | The PRCB address of the hung processor. | +| 3 | Reserved | +| 4 | Reserved | + +  + +Cause +----- + +This bug check typically means that either an ISR is hung at an IRQL that is below clock level and above dispatch level, or a DPC routine is hung on the specified processor. + +For example for StorPort Miniport drivers, StorPort.sys handles I/O completions in a routine that runs at DISPATCH\_LEVEL and that serially calls the I/O completion routines of all IRPs that have just completed. If I/O completion routines singly or together take too much time, the keyboard and/or mouse may stop responding. It is also possible that the Windows DPC Watchdog timer routine will decide that the StorPort routine has taken excessive time to finish. + +Resolution +---------- + +A kernel driver in the storage stack can reduce the problem's likelihood by efficient coding of the driver's I/O completion routine. If it is still not possible to do all necessary processing in the completion routine in enough time, the routine can create a work element for the I/O work, queue up the element to a work queue and return STATUS\_MORE\_PROCESSING\_REQUIRED; a worker thread of the driver should then find the work element, do the work and do IoCallerDriver for the IRP to ensure the IRP's further I/O processing. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x103---mup-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x103---mup-file-system.md new file mode 100644 index 0000000000..fbaa8e36a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x103---mup-file-system.md @@ -0,0 +1,94 @@ +--- +title: Bug Check 0x103 MUP_FILE_SYSTEM +description: The MUP_FILE_SYSTEM bug check has a value of 0x00000103. +ms.assetid: 2756bdcc-5b10-481e-99ec-17b00c4f459d +keywords: ["Bug Check 0x103 MUP_FILE_SYSTEM", "MUP_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MUP_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x103: MUP\_FILE\_SYSTEM + + +The MUP\_FILE\_SYSTEM bug check has a value of 0x00000103. This bug check indicates that the multiple UNC provider (MUP) has encountered invalid or unexpected data. As a result, the MUP cannot channel a remote file system request to a network redirector, the Universal Naming Convention (UNC) provider. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MUP\_FILE\_SYSTEM Parameters + + +Parameter 1 identifies the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x1

The address of the pending IRP.

The address of the file object whose file context could not be found.

The address of the device object.

The MUP could not locate the file context that corresponds to a file object. This typically indicates that the MUP is seeing an I/O request for a file object for which MUP did not see a corresponding IRP_MJ_CREATE request. The likely cause of this bug check is a filter driver error.

0x2

The address of the expected file context.

The address that was actually retrieved from the file object.

Reserved

A file context is known to exist for the file object, but was not what was expected (for example, it might be NULL).

0x3

The address of the IRP context.

The IRP completion status code.

The driver object of the UNC provider that completed the IRP (might be NULL).

The IRP completion status was unexpected or invalid.

+

This bug check occurs only when you are using a Checked Build of Windows and should only be caused by file system filter drivers that are attached to legacy network redirectors. Legacy redirectors use FsRtlRegisterUncProvider to register with MUP. This bug check detects filter drivers that return an NTSTATUS that is not STATUS_SUCCESS in IRP_MJ_CLEANUP or IRP_MJ_CLOSE requests.

0x4

Address of the IRP

Address of the file object

The file context for the file object

An I/O operation was started on a file object before the create request for the file object was completed.

+ +  + +Remarks +------- + +The MUP maintains context information on a per-file object basis for all file objects it handles. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x104---agp-invalid-access.md b/windows-driver-docs-pr/debugger/bug-check-0x104---agp-invalid-access.md new file mode 100644 index 0000000000..6f7a5bf3e8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x104---agp-invalid-access.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x104 AGP_INVALID_ACCESS +description: The AGP_INVALID_ACCESS bug check has a value of 0x00000104. This indicates that the GPU wrote to a range of Accelerated Graphics Port (AGP) memory that had not previously been committed. +ms.assetid: c1f5322e-847a-424f-b117-1714b8572a4f +keywords: ["Bug Check 0x104 AGP_INVALID_ACCESS", "AGP_INVALID_ACCESS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- AGP_INVALID_ACCESS +api_type: +- NA +--- + +# Bug Check 0x104: AGP\_INVALID\_ACCESS + + +The AGP\_INVALID\_ACCESS bug check has a value of 0x00000104. This indicates that the GPU wrote to a range of Accelerated Graphics Port (AGP) memory that had not previously been committed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## AGP\_INVALID\_ACCESS Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Offset (in ULONG) within the AGP verifier page to the first ULONG data that is corrupted

2

0

3

0

4

0

+ +  + +Cause +----- + +Typically, this bug check is caused by an unsigned or improperly tested video driver. It can also be caused by an old BIOS. + +Resolution +---------- + +Check for display driver and computer BIOS updates. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x105---agp-gart-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0x105---agp-gart-corruption.md new file mode 100644 index 0000000000..04c2b0ed29 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x105---agp-gart-corruption.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x105 AGP_GART_CORRUPTION +description: The AGP_GART_CORRUPTION bug check has a value of 0x00000105. This indicates that the Graphics Aperture Remapping Table (GART) is corrupt. +ms.assetid: efc39d1f-666d-4377-a262-ed5164357b52 +keywords: ["Bug Check 0x105 AGP_GART_CORRUPTION", "AGP_GART_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- AGP_GART_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0x105: AGP\_GART\_CORRUPTION + + +The AGP\_GART\_CORRUPTION bug check has a value of 0x00000105. This indicates that the Graphics Aperture Remapping Table (GART) is corrupt. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## AGP\_GART\_CORRUPTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The base address (virtual) of the GART

2

The offset into the GART where the corruption occurred

3

The base address (virtual) of the GART cache (a copy of the GART)

4

0

+ +  + +Cause +----- + +This bug check is typically caused by improper direct memory access (DMA) by a driver. + +Resolution +---------- + +Enable Driver Verifier for any unsigned drivers. Remove them or disable them one by one until the erring driver is identified. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x106---agp-illegally-reprogrammed.md b/windows-driver-docs-pr/debugger/bug-check-0x106---agp-illegally-reprogrammed.md new file mode 100644 index 0000000000..89c7bef6a9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x106---agp-illegally-reprogrammed.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x106 AGP_ILLEGALLY_REPROGRAMMED +description: The AGP_ILLEGALLY_REPROGRAMMED bug check has a value of 0x00000106. This indicates that the Accelerated Graphics Port (AGP) hardware has been reprogrammed by an unauthorized agent. +ms.assetid: 7acccf9b-bc4f-4842-a332-1023ab26f03d +keywords: ["Bug Check 0x106 AGP_ILLEGALLY_REPROGRAMMED", "AGP_ILLEGALLY_REPROGRAMMED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- AGP_ILLEGALLY_REPROGRAMMED +api_type: +- NA +--- + +# Bug Check 0x106: AGP\_ILLEGALLY\_REPROGRAMMED + + +The AGP\_ILLEGALLY\_REPROGRAMMED bug check has a value of 0x00000106. This indicates that the Accelerated Graphics Port (AGP) hardware has been reprogrammed by an unauthorized agent. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## AGP\_ILLEGALLY\_REPROGRAMMED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The originally programmed AGP command register value

2

The current command register value

3

0

4

0

+ +  + +Cause +----- + +This bug check is typically caused by an unsigned, or improperly tested, video driver. + +Resolution +---------- + +Check the video manufacturer's Web site for updated display drivers or use VGA mode. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x108--third-party-file-system-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x108--third-party-file-system-failure.md new file mode 100644 index 0000000000..3706716e53 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x108--third-party-file-system-failure.md @@ -0,0 +1,85 @@ +--- +title: Bug Check 0x108 THIRD_PARTY_FILE_SYSTEM_FAILURE +description: The THIRD_PARTY_FILE_SYSTEM_FAILURE bug check has a value of 0x00000108. This indicates that an unrecoverable problem has occurred in a third-party file system or file system filter. +ms.assetid: 1ed82617-b0f0-4b41-9af9-b309b6b75dfd +keywords: ["Bug Check 0x108 THIRD_PARTY_FILE_SYSTEM_FAILURE", "THIRD_PARTY_FILE_SYSTEM_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- THIRD_PARTY_FILE_SYSTEM_FAILURE +api_type: +- NA +--- + +# Bug Check 0x108: THIRD\_PARTY\_FILE\_SYSTEM\_FAILURE + + +The THIRD\_PARTY\_FILE\_SYSTEM\_FAILURE bug check has a value of 0x00000108. This indicates that an unrecoverable problem has occurred in a third-party file system or file system filter. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## THIRD\_PARTY\_FILE\_SYSTEM\_FAILURE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Identifies the file system that failed. Possible values include:

+

1: Polyserve (Psfs.sys)

2

The address of the exception record.

3

The address of the context record.

4

Reserved.

+ +  + +Cause +----- + +One possible cause of this bug check is disk corruption. Corruption in the third-party file system or bad blocks (sectors) on the hard disk can induce this error. Corrupted SCSI and IDE drivers can also adversely affect the Windows operating system's ability to read and write to disk, thus causing the error. + +Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool is completely depleted, this error can stop the system. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a disk corruption problem:** Check Event Viewer for error messages from SCSI, IDE, or other disk controllers in the system that might help pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You should also run hardware diagnostics supplied by the file system or the file system filter manufacturer. + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x109---critical-structure-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0x109---critical-structure-corruption.md new file mode 100644 index 0000000000..ffe610a7cc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x109---critical-structure-corruption.md @@ -0,0 +1,301 @@ +--- +title: Bug Check 0x109 CRITICAL_STRUCTURE_CORRUPTION +description: The CRITICAL_STRUCTURE_CORRUPTION bug check has a value of 0x00000109. This indicates that the kernel has detected critical kernel code or data corruption. +ms.assetid: 38d4d722-a915-4f17-899b-2a0b4aa69d95 +keywords: ["Bug Check 0x109 CRITICAL_STRUCTURE_CORRUPTION", "CRITICAL_STRUCTURE_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRITICAL_STRUCTURE_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0x109: CRITICAL\_STRUCTURE\_CORRUPTION + + +The CRITICAL\_STRUCTURE\_CORRUPTION bug check has a value of 0x00000109. This indicates that the kernel has detected critical kernel code or data corruption. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CRITICAL\_STRUCTURE\_CORRUPTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Reserved

2

Reserved

3

Reserved

4

The type of the corrupted region. (See the following table later on this page.)

+ +  + +The value of Parameter 4 indicates the type of corrupted region. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 4Type of Corrupted Region, Type of Corruption, or Type of Action Taken That Caused the Corruption

0x0

A generic data region

0x1

A function modification or the Itanium-based function location

0x2

A processor interrupt dispatch table (IDT)

0x3

A processor global descriptor table (GDT)

0x4

A type-1 process list corruption

0x5

A type-2 process list corruption

0x6

A debug routine modification

0x7

A critical MSR modification

0x8

Object type

0x9

A processor IVT

0xA

Modification of a system service function

0xB

A generic session data region

0xC

Modification of a session function or .pdata

0xD

Modification of an import table

0xE

Modification of a session import table

0xF

Ps Win32 callout modification

0x10

Debug switch routine modification

0x11

IRP allocator modification

0x12

Driver call dispatcher modification

0x13

IRP completion dispatcher modification

0x14

IRP deallocator modification

0x15

A processor control register

0x16

Critical floating point control register modification

0x17

Local APIC modification

0x18

Kernel notification callout modification

0x19

Loaded module list modification

0x1A

Type 3 process list corruption

0x1B

Type 4 process list corruption

0x1C

Driver object corruption

0x1D

Executive callback object modification

0x1E

Modification of module padding

0x1F

Modification of a protected process

0x20

A generic data region

0x21

A page hash mismatch

0x22

A session page hash mismatch

0x23

Load config directory modification

0x24

Inverted function table modification

0x25

Session configuration modification

0x26

An extended processor control register

0x27

Type 1 pool corruption

0x28

Type 2 pool corruption

0x29

Type 3 pool corruption

0x101

General pool corruption

0x102

Modification of win32k.sys

+ +  + +Cause +----- + +There are generally three different causes for this bug check: + +1. A driver has inadvertently, or deliberately, modified critical kernel code or data. Microsoft Windows Server 2003 with Service Pack 1 (SP1) and later versions of Windows for x64-based computers do not allow the kernel to be patched except through authorized Microsoft-originated hot patches. For more information, see [Patching Policy for x64-based Systems](http://go.microsoft.com/fwlink/p/?linkid=50719). + +2. A developer attempted to set a normal kernel breakpoint using a kernel debugger that was not attached when the system was started. Normal breakpoints ([**bp**](bp--bu--bm--set-breakpoint-.md)) can only be set if the debugger is attached at start time. Processor breakpoints ([**ba**](ba--break-on-access-.md)) can be set at any time. + +3. A hardware corruption occurred. For example, the kernel code or data could have been stored in memory that failed. + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +To start, examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. You can specify the processor number to examine the stacks on all processors. + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Run the Windows Memory Diagnostics tool, to test the memory. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10a---app-tagging-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x10a---app-tagging-initialization-failed.md new file mode 100644 index 0000000000..df2fec0b51 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10a---app-tagging-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x10A APP_TAGGING_INITIALIZATION_FAILED +description: The APP_TAGGING_INITIALIZATION_FAILED bug check has a value of 0x0000010A.This bug check appears very infrequently. +ms.assetid: 4ec74094-8b9a-4c04-9e40-6e9c1a45ae60 +keywords: ["Bug Check 0x10A APP_TAGGING_INITIALIZATION_FAILED", "APP_TAGGING_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- APP_TAGGING_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x10A: APP\_TAGGING\_INITIALIZATION\_FAILED + + +The APP\_TAGGING\_INITIALIZATION\_FAILED bug check has a value of 0x0000010A. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10c---fsrtl-extra-create-parameter-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x10c---fsrtl-extra-create-parameter-violation.md new file mode 100644 index 0000000000..ed348243a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10c---fsrtl-extra-create-parameter-violation.md @@ -0,0 +1,131 @@ +--- +title: Bug Check 0x10C FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION +description: The FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION bug check has a value of 0x0000010C that indicates that a violation was detected in the FsRtl ECP package. +ms.assetid: b702b182-696a-4233-8bd0-23a52ab2ddc4 +keywords: ["Bug Check 0x10C FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION", "FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x10C: FSRTL\_EXTRA\_CREATE\_PARAMETER\_VIOLATION + + +The FSRTL\_EXTRA\_CREATE\_PARAMETER\_VIOLATION bug check has a value of 0x0000010C. This indicates that a violation was detected in the File system Run-time library (FsRtl) Extra Create Parameter (ECP) package. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FSRTL\_EXTRA\_CREATE\_PARAMETER\_VIOLATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The type of violation. (See the following table later on this page for more details).

2

0

3

The address of the ECP.

4

The starting address of the ECP list.

+ +  + +The value of Parameter 1 indicates the type of violation. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Type of Violation

0x1

The ECP signature is invalid, due to either a bad pointer or memory corruption.

0x2

The ECP has undefined flags set.

0x3

The ECP was not allocated by the FsRtl.

0x4

The ECP has flags set that are illegal for a parameter passed by a create caller.

0x5

The ECP is corrupted; its size is smaller than the header size.

0x6

The ECP that is being freed has non-empty list pointers; it might still be part of an ECP list.

0x11

The ECP list signature is invalid, due to either a bad pointer or memory corruption.

0x12

The ECP list has undefined flags set.

0x13

The ECP list was not allocated by the FsRtl.

0x14

The ECP list has flags set that are illegal for a parameter list passed by a create caller.

0x15

The ECP list passed by the create caller is empty.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10d---wdf-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x10d---wdf-violation.md new file mode 100644 index 0000000000..717e76d556 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10d---wdf-violation.md @@ -0,0 +1,250 @@ +--- +title: Bug Check 0x10D WDF_VIOLATION +description: The WDF_VIOLATION bug check has a value of 0x0000010D. This indicates that Kernel-Mode Driver Framework (KMDF) detected that Windows found an error in a framework-based driver. +ms.assetid: 2d8c9730-cd24-4f8c-8f8b-252644737847 +keywords: ["Bug Check 0x10D WDF_VIOLATION", "WDF_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WDF_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x10D: WDF\_VIOLATION + + +The WDF\_VIOLATION bug check has a value of 0x0000010D. This indicates that Kernel-Mode Driver Framework (KMDF) detected that Windows found an error in a framework-based driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WDF\_VIOLATION Parameters + + +Parameter 1 indicates the specific error code of the bug check. Parameter 4 is reserved. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Cause of Error

0x1

Pointer to a WDF_POWER_ROUTINE_TIMED_OUT_DATA structure

Reserved

A framework-based driver has timed out during a power operation. This typically means that the device stack did not set the DO_POWER_PAGABLE bit and a driver attempted a pageable operation after the paging device stack was powered down.

0x2

Reserved

Reserved

An attempt is being made to acquire a lock that is currently being held.

0x3

WDFREQUEST handle

The number of outstanding references that remain on both buffers

Windows Driver Framework Verifier has encountered a fatal error. In particular, an I/O request was completed, but a framework request object cannot be deleted because there are outstanding references to the input buffer, the output buffer, or both.

0x4

Reserved

The caller's address

A NULL parameter was passed to a function that required a non-NULL value.

0x5

The handle value passed in

Reserved

A framework object handle of the incorrect type was passed to a framework object method.

0x6

See table below.

0x7

The handle of the framework object

Reserved

A driver attempted to delete a framework object incorrectly by calling WdfObjectDereference to delete a handle instead of calling WdfObjectDelete.

0x8

The handle of the DMA transaction object

Reserved

An operation occurred on a DMA transaction object while it was not in the correct state.

0x9

Currently unused.

0xA

A pointer to a WDF_QUEUE_FATAL_ERROR_DATA structure

Reserved

A fatal error has occurred while processing a request that is currently in the queue.

0xB

See table below.

0xC

WDFDEVICE handle

Pointer to new PnP IRP

A new state-changing PnP IRP arrived while the driver was processing another state-changing PnP IRP.

0xD

WDFDEVICE handle

Pointer to power IRP

A device's power policy owner received a power IRP that it did not request. There might be multiple power policy owners, but only one is allowed. A KMDF driver can change power policy ownership by calling WdfDeviceInitSetPowerPolicyOwnership.

0xE

IRQL at which the event callback function was called.

IRQL at which the event callback function returned.

An event callback function did not return at the same IRQL at which it was called. The callback function changed the IRQL directly or indirectly (for example, by acquiring a spinlock, which raises IRQL to DISPATCH_LEVEL, but not releasing the spinlock).

0xF

Address of an event callback function.

Reserved

An event callback function entered a critical region, but it did not leave the critical region before returning.

+ +  + +**Parameter 1 is equal to 0x6** + +If Parameter 1 is equal to 0x6, then a fatal error was made in handling a WDF request. In this case, Parameter 2 further specifies the type of fatal error that has been made, as defined by the enumeration WDF\_REQUEST\_FATAL\_ERROR. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 2Parameter 3Cause of Error

0x1

The address of the IRP

No more I/O stack locations are available to format the underlying IRP.

0x2

The WDF request handle value

An attempt was made to format a framework request object that did not contain an IRP.

0x3

The WDF request handle value

The driver attempted to send a framework request that has already been sent to an I/O target.

0x4

A pointer to a WDR_REQUEST_FATAL_ERROR_INFORMATION_LENGTH_MISMATCH_DATA structure that contains a pointer to the IRP, a WDF request handle value, an IRP major function, and the number of bytes attempted to be written

The driver has completed a framework request, but has written more bytes to the output buffer than are specified in the IRP.

+ +  + +**Parameter 1 is equal to 0xB** + +If Parameter 1 is equal to 0xB, then an attempt to acquire or release a lock was invalid. In this case, Parameter 3 further specifies the error that has been made. + + +++++ + + + + + + + + + + + + + + + + + + + +
Parameter 2Parameter 3Cause of Error

The handle value

0x0

A handle passed to WdfObjectAcquireLock or WdfObjectReleaseLock represents an object that does not support synchronization locks.

A WDF spin lock handle

0x1

The spin lock is being released by a thread that did not acquire it.

+ +  + +Cause +----- + +See the description of each code in the Parameters section for an explanation of the cause. + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in gathering information, such as the faulting code module. + +Typically, the WDF dump file will yield further information on the driver that caused this bug check. Use this command to look at the log file. + +``` +kd> !wdfkd.wdflogdump +``` + +If Parameter 1 is equal to **0x2**, examine the caller's stack to determine the lock in question. + +If Parameter 1 is equal to **0x3**, the driver's Kernel-Mode Driver Framework error log will include details about the outstanding references. + +If Parameter 1 is equal to **0x4**, use the [**ln debugger**](ln--list-nearest-symbols-.md) command with the value of *Parameter 3* as its argument to determine which function requires a non-**NULL** parameter. + +If Parameter 1 is equal to **0x7**, use the **!wdfkd.wdfhandle***Parameter 2* extension command to determine the handle type. + +If Parameter 1 is equal to **0xA**, then the WDF\_QUEUE\_FATAL\_ERROR\_DATA structure will indicate either the problematic request or the queue handle. It will also indicate the NTSTATUS, if not STATUS\_SUCCESS, when available. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10e---video-memory-management-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x10e---video-memory-management-internal.md new file mode 100644 index 0000000000..85694f9d04 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10e---video-memory-management-internal.md @@ -0,0 +1,176 @@ +--- +title: Bug Check 0x10E VIDEO_MEMORY_MANAGEMENT_INTERNAL +description: The VIDEO_MEMORY_MANAGEMENT_INTERNAL bug check has a value of 0x0000010E. This indicates that the video memory manager has encountered a condition that it is unable to recover from. +ms.assetid: 2fb29098-084c-462a-bb06-789e73924d16 +keywords: ["Bug Check 0x10E VIDEO_MEMORY_MANAGEMENT_INTERNAL", "VIDEO_MEMORY_MANAGEMENT_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_MEMORY_MANAGEMENT_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x10E: VIDEO\_MEMORY\_MANAGEMENT\_INTERNAL + + +The VIDEO\_MEMORY\_MANAGEMENT\_INTERNAL bug check has a value of 0x0000010E. This indicates that the video memory manager has encountered a condition that it is unable to recover from. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_MEMORY\_MANAGEMENT\_INTERNAL Parameters + + +Parameter 1 is the only parameter of interest; this identifies the exact violation. Values for Parameter 1 that do not appear in this table must be individually examined. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Cause of Error

0x1

An attempt was made to rotate a non-rotate range.

0x2

An attempt was made to destroy a non-empty process heap.

0x3

An attempt to unmap from an aperture segment failed.

0x4

A rotation in a must-succeed path failed.

0x5

A deferred command failed.

0x6

An attempt was made to reallocate resources for an allocation that was having its eviction canceled.

0x7

An invalid attempt was made to defer free usage.

0x8

The split direct memory access (DMA) buffer contains an invalid reference.

0x9

An attempt to evict an allocation failed.

0xA

An invalid attempt to use a pinned allocation was made.

0xB

A driver returned an invalid error code from BuildPagingBuffer.

0xC

A resource leak was detected in a segment.

0xD

A segment is being used improperly.

0xE

An attempt to map an allocation into an aperture segment failed.

0xF

A driver returned an invalid error code from AcquireSwizzlingRange.

0x10

A driver returned an invalid error code from ReleaseSwizzlingRange.

0x11

An invalid attempt to use an aperture segment was made.

0x12

A driver overflowed the provided DMA buffer.

0x13

A driver overflowed the provided private data buffer.

0x14

An attempt to purge all segments failed.

0x15

An attempt was made to free a virtual address descriptor (VAD) that was still in the rotated state

0x16

A driver broke the guaranteed DMA buffer model contract.

0x17

An unexpected system command failure occurred.

0x18

An attempt to release a pinned allocation's resource failed.

0x19

A driver failed to patch a DMA buffer.

0x1A

The owner of a shared allocation was freed.

0x1B

An attempt was made to release an aperture range that is still in use.

0x25

The GPU attempted to write over an undefined area of the aperture.

+ +  + +Cause +----- + +This bug check is usually caused by a video driver behaving improperly. + +Resolution +---------- + +If the problem persists, check Windows Update for an updated video driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x10f---resource-manager-exception-not-handled.md b/windows-driver-docs-pr/debugger/bug-check-0x10f---resource-manager-exception-not-handled.md new file mode 100644 index 0000000000..9950ec2c10 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x10f---resource-manager-exception-not-handled.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x10F RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED +description: The RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000010F. +ms.assetid: d2589163-8c82-4416-a378-a0c72360a9fb +keywords: ["Bug Check 0x10F RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED", "RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED +api_type: +- NA +--- + +# Bug Check 0x10F: RESOURCE\_MANAGER\_EXCEPTION\_NOT\_HANDLED + + +The RESOURCE\_MANAGER\_EXCEPTION\_NOT\_HANDLED bug check has a value of 0x0000010F. This indicates that the kernel transaction manager detected that a kernel-mode resource manager has raised an exception in response to a direct call-back. The resource manager is in an unexpected and unrecoverable state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RESOURCE\_MANAGER\_EXCEPTION\_NOT\_HANDLED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the exception record

2

The address of the context record

3

The address of the exception code

4

The address of the resource manager

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x11--thread-not-mutex-owner.md b/windows-driver-docs-pr/debugger/bug-check-0x11--thread-not-mutex-owner.md new file mode 100644 index 0000000000..8ec8c7a21f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x11--thread-not-mutex-owner.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x11 THREAD_NOT_MUTEX_OWNER +description: The THREAD_NOT_MUTEX_OWNER bug check has a value of 0x00000011.This bug check appears very infrequently. +ms.assetid: 9f6fe1db-535f-4983-866a-8a5ea035ac80 +keywords: ["Bug Check 0x11 THREAD_NOT_MUTEX_OWNER", "THREAD_NOT_MUTEX_OWNER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- THREAD_NOT_MUTEX_OWNER +api_type: +- NA +--- + +# Bug Check 0x11: THREAD\_NOT\_MUTEX\_OWNER + + +The THREAD\_NOT\_MUTEX\_OWNER bug check has a value of 0x00000011. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x111---recursive-nmi.md b/windows-driver-docs-pr/debugger/bug-check-0x111---recursive-nmi.md new file mode 100644 index 0000000000..3a5f0c87ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x111---recursive-nmi.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x111 RECURSIVE_NMI +description: The RECURSIVE_NMI bug check has a value of 0x00000111. This bug check indicates that a non-maskable-interrupt (NMI) occurred while a previous NMI was in progress. +ms.assetid: 1f275db1-ac79-4bd2-85c5-cb64342911d1 +keywords: ["Bug Check 0x111 RECURSIVE_NMI", "RECURSIVE_NMI"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RECURSIVE_NMI +api_type: +- NA +--- + +# Bug Check 0x111: RECURSIVE\_NMI + + +The RECURSIVE\_NMI bug check has a value of 0x00000111. This bug check indicates that a non-maskable-interrupt (NMI) occurred while a previous NMI was in progress. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +Remarks +------- + +This bug check occurs when there is an error in the system management interrupt (SMI) code, and an SMI interrupts an NMI and enables interrupts. Execution then continues with NMIs enabled, and another NMI interrupts the NMI in progress. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x112---msrpc-state-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x112---msrpc-state-violation.md new file mode 100644 index 0000000000..b1d5883014 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x112---msrpc-state-violation.md @@ -0,0 +1,143 @@ +--- +title: Bug Check 0x112 MSRPC_STATE_VIOLATION +description: The MSRPC_STATE_VIOLATION bug check has a value of 0x00000112. This indicates that the Msrpc.sys driver has initiated a bug check. +ms.assetid: b7cd531d-518e-4d11-8edb-d52dbbe51043 +keywords: ["Bug Check 0x112 MSRPC_STATE_VIOLATION", "MSRPC_STATE_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MSRPC_STATE_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x112: MSRPC\_STATE\_VIOLATION + + +The MSRPC\_STATE\_VIOLATION bug check has a value of 0x00000112. This indicates that the Msrpc.sys driver has initiated a bug check. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MSRPC\_STATE\_VIOLATION Parameters + + +Parameters 1 and 2 are the only parameters of interest. Parameter 1 indicates the state violation type; the value for Parameter 2 is determined by the value of Parameter 1. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Cause of Error

0x01

The exception code

A non-continuable exception was continued by the caller.

0x02

The error

The advanced local procedure call (ALPC) returned an invalid error.

0x03

The session to the server

The caller unloaded the Microsoft remote procedure call (MSRPC) driver while it was still in use. It is likely that open binding handles remain.

0x04 and

+

0x05

The session to the server

An invalid close command was received from the ALPC.

0x06

The binding handle

An attempt was made to bind a remote procedure call (RPC) handle a second time.

0x07

The binding handle

An attempt was made to perform an operation on a binding handle that was not bound.

0x08

The binding handle

An attempt was made to set security information on a binding handle that was already bound.

0x09

The binding handle

An attempt was made to set an option on a binding handle that was already bound.

0x0A

The call object

An attempt was made to cancel an invalid asynchronous remote procedure call.

0x0B

The call object

An attempt was made to push on an asynchronous pipe call when it was not expected.

0x0C and

+

0x0E

The pipe object

An attempt was made to push on an asynchronous pipe without waiting for notification.

0x0F

The pipe object

An attempt was made to synchronously terminate a pipe a second time.

0x15

The object closest to the error

An RPC internal error occurred.

0x16

Reserved

Two causally ordered calls were issued in an order that cannot be enforced by the RPC.

0x17

The call object

A server manager routine did not unsubscribe from notifications prior to completing the call.

0x18

The async handle

An invalid operation on the asynchronous handle occurred.

+ +  + +Cause +----- + +The most common cause of this bug check is that the caller of the Msrpc.sys driver violated the state semantics for such a call. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x113---video-dxgkrnl-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x113---video-dxgkrnl-fatal-error.md new file mode 100644 index 0000000000..f317a352c7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x113---video-dxgkrnl-fatal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x113 VIDEO_DXGKRNL_FATAL_ERROR +description: The VIDEO_DXGKRNL_FATAL_ERROR bug check has a value of 0x00000113 that indicates that the Microsoft DirectX graphics kernel subsystem has detected a violation. +ms.assetid: 916b78de-3030-4a9c-b7a7-fa1c20c5c739 +keywords: ["Bug Check 0x113 VIDEO_DXGKRNL_FATAL_ERROR", "VIDEO_DXGKRNL_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_DXGKRNL_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x113: VIDEO\_DXGKRNL\_FATAL\_ERROR + + +The VIDEO\_DXGKRNL\_FATAL\_ERROR bug check has a value of 0x00000113. This indicates that the Microsoft DirectX graphics kernel subsystem has detected a violation. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x114---video-shadow-driver-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x114---video-shadow-driver-fatal-error.md new file mode 100644 index 0000000000..f9a2bc2154 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x114---video-shadow-driver-fatal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x114 VIDEO_SHADOW_DRIVER_FATAL_ERROR +description: The VIDEO_SHADOW_DRIVER_FATAL_ERROR bug check has a value of 0x00000114. This indicates that the shadow driver has detected a violation.This bug check appears very infrequently. +ms.assetid: 5250947b-bae0-4981-8e52-b8337a72a4ee +keywords: ["Bug Check 0x114 VIDEO_SHADOW_DRIVER_FATAL_ERROR", "VIDEO_SHADOW_DRIVER_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_SHADOW_DRIVER_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x114: VIDEO\_SHADOW\_DRIVER\_FATAL\_ERROR + + +The VIDEO\_SHADOW\_DRIVER\_FATAL\_ERROR bug check has a value of 0x00000114. This indicates that the shadow driver has detected a violation. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x115---agp-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x115---agp-internal.md new file mode 100644 index 0000000000..44f8001c93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x115---agp-internal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x115 AGP_INTERNAL +description: The AGP_INTERNAL bug check has a value of 0x00000115. This indicates that the accelerated graphics port (AGP) driver has detected a violation.This bug check appears very infrequently. +ms.assetid: 5fc7e627-ca37-4fb3-a80b-24a9ef265cc5 +keywords: ["Bug Check 0x115 AGP_INTERNAL", "AGP_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- AGP_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x115: AGP\_INTERNAL + + +The AGP\_INTERNAL bug check has a value of 0x00000115. This indicates that the accelerated graphics port (AGP) driver has detected a violation. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x116---video-tdr-error.md b/windows-driver-docs-pr/debugger/bug-check-0x116---video-tdr-error.md new file mode 100644 index 0000000000..f7e4a37526 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x116---video-tdr-error.md @@ -0,0 +1,234 @@ +--- +title: Bug Check 0x116 VIDEO_TDR_ERROR +description: The VIDEO_TDR_ ERROR bug check has a value of 0x00000116. This indicates that an attempt to reset the display driver and recover from a timeout failed. +ms.assetid: 06fe312a-e2d3-479f-b0fb-06c0ac79be32 +keywords: ["Bug Check 0x116 VIDEO_TDR_ERROR", "VIDEO_TDR_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_TDR_ERROR +api_type: +- NA +--- + +# Bug Check 0x116: VIDEO\_TDR\_ERROR + + +The VIDEO\_TDR\_ ERROR bug check has a value of 0x00000116. This indicates that an attempt to reset the display driver and recover from a timeout failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_TDR\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The pointer to the internal TDR recovery context, if available.

2

A pointer into the responsible device driver module (for example, the owner tag).

3

The error code of the last failed operation, if available.

4

Internal context dependent data, if available.

+ +  + +Cause +----- + +A common stability problem in graphics occurs when the system appears completely frozen or hung while processing an end-user command or operation. Usually the GPU is busy processing intensive graphics operations, typically during game-play. No screen updates occur, and users assume that their system is frozen. Users usually wait a few seconds and then reboot the system by pressing the power button. Windows tries to detect these problematic hang situations and dynamically recover a responsive desktop. + +This process of detection and recovery is known as Timeout Detection and Recovery (TDR). The default timeout is 2 seconds. In the TDR process for video cards, the operating system's GPU scheduler calls the display miniport driver's [*DxgkDdiResetFromTimeout*](https://msdn.microsoft.com/library/windows/hardware/ff559815) function to reinitialize the driver and reset the GPU. + +During this process, the operating system tells the driver not to access the hardware or memory and gives it a short time for currently running threads to complete. If the threads do not complete within the timeout, then the system bug checks with 0x116 VIDEO\_TDR\_FAILURE. For more information, see [Thread Synchronization and TDR](https://msdn.microsoft.com/library/windows/hardware/ff570082). + +The system can also bug check with VIDEO\_TDR\_FAILURE if a number of TDR events occur in a short period of time, by default more than five TDRs in one minute. + +If the recovery process is successful, a message will be displayed, indicating that the "Display driver stopped responding and has recovered." + +For more information, see Timeout Detection and Recovery (TDR), [TDR Registry Keys](https://msdn.microsoft.com/library/windows/hardware/ff569918) and [TDR changes in Windows 8](https://msdn.microsoft.com/library/windows/hardware/jj676805) which are located in [Debugging Tips for the Windows Display Driver Model (WDDM)](https://msdn.microsoft.com/library/windows/hardware/ff551790). + +Resolution +---------- + +The GPU is taking more time than permitted to display graphics to your monitor. This behavior can occur for one or more of the following reasons: + +- You may need to install the latest updates for your display driver, so that it properly supports the TDR process. +- Hardware issues that impact the ability of the video card to operate properly, including: + - Over-clocked components, such as the motherboard + - Incorrect component compatibility and settings (especially memory configuration and timings) + - Insufficient system cooling + - Insufficient system power + - Defective parts (memory modules, motherboards, etc.) +- Visual effects, or too many programs running in the background may be slowing your PC down so that the video card can not respond as necessary. + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +``` +1: kd> !analyze -v +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +VIDEO_TDR_FAILURE (116) +Attempt to reset the display driver and recover from timeout failed. +Arguments: +Arg1: ffffe000c2c404c0, Optional pointer to internal TDR recovery context (TDR_RECOVERY_CONTEXT). +Arg2: fffff8016470c14c, The pointer into responsible device driver module (e.g. owner tag). +Arg3: ffffffffc000009a, Optional error code (NTSTATUS) of the last failed operation. +Arg4: 0000000000000004, Optional internal context dependent data. + +... +``` + +Also displayed will be the faulting module name + +``` +MODULE_NAME: nvlddmkm + +IMAGE_NAME: nvlddmkm.sys +``` + +You can use the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md)command to display information about the faulting driver, including the timestamp. + +``` +1: kd> lmvm nvlddmkm +Browse full module list +start end module name +fffff801`63ec0000 fffff801`649a7000 nvlddmkm T (no symbols) + Loaded symbol image file: nvlddmkm.sys + Image path: \SystemRoot\system32\DRIVERS\nvlddmkm.sys + Image name: nvlddmkm.sys + Browse all global symbols functions data + Timestamp: Wed Jul 8 15:43:44 2015 (559DA7A0) + CheckSum: 00AA7491 + ImageSize: 00AE7000 + Translations: 0000.04b0 0000.04e4 0409.04b0 0409.04e4 + +``` + +Parameter 1 contains a pointer to the TDR\_RECOVERY\_CONTEXT. As shown in the !analyze output, you can use the dt command to display this data. + +``` +1: kd> dt dxgkrnl!_TDR_RECOVERY_CONTEXT ffffe000c2c404c0 + +0x000 Signature : 0x52445476 + +0x008 pState : 0xffffe000`c2b12a40 ?? + +0x010 TimeoutReason : 9 ( TdrEngineTimeoutPromotedToAdapterReset ) + +0x018 Tick : _ULARGE_INTEGER 0xb2 + +0x020 pAdapter : 0xffffe000`c2a89010 DXGADAPTER + +0x028 pVidSchContext : (null) + +0x030 GPUTimeoutData : _TDR_RECOVERY_GPU_DATA + +0x048 CrtcTimeoutData : _TDR_RECOVERY_CONTEXT:: + +0x050 pProcessName : (null) + +0x058 DbgOwnerTag : 0xfffff801`6470c14c + +0x060 PrivateDbgInfo : _TDR_DEBUG_REPORT_PRIVATE_INFO + +0xb00 pDbgReport : 0xffffe000`c2c3f750 _WD_DEBUG_REPORT + +0xb08 pDbgBuffer : 0xffffc000`bd000000 Void + +0xb10 DbgBufferSize : 0x37515 + +0xb18 pDumpBufferHelper : (null) + +0xb20 pDbgInfoExtension : 0xffffc000`ba7e47a0 _DXGKARG_COLLECTDBGINFO_EXT + +0xb28 pDbgBufferUpdatePrivateInfo : 0xffffc000`bd000140 Void + +0xb30 ReferenceCount : 0n1 + +0xb38 pResetCompletedEvent : (null) +``` + +Parameter 2 contains a pointer into the responsible device driver module (for example, the owner tag). + +``` +1: kd> ub fffff8016470c14c +nvlddmkm+0x84c132: +fffff801`6470c132 cc int 3 +fffff801`6470c133 cc int 3 +fffff801`6470c134 48ff254d2deaff jmp qword ptr [nvlddmkm+0x6eee88 (fffff801`645aee88)] +fffff801`6470c13b cc int 3 +fffff801`6470c13c 48ff252d2eeaff jmp qword ptr [nvlddmkm+0x6eef70 (fffff801`645aef70)] +fffff801`6470c143 cc int 3 +fffff801`6470c144 48ff257d2deaff jmp qword ptr [nvlddmkm+0x6eeec8 (fffff801`645aeec8)] +fffff801`6470c14b cc int 3 +``` + +You may wish to examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. + +``` +1: kd> k + # Child-SP RetAddr Call Site +00 ffffd001`7d53d918 fffff801`61ba2b4c nt!KeBugCheckEx [d:\th\minkernel\ntos\ke\amd64\procstat.asm @ 122] +01 ffffd001`7d53d920 fffff801`61b8da0e dxgkrnl!TdrBugcheckOnTimeout+0xec [d:\th\windows\core\dxkernel\dxgkrnl\core\dxgtdr.cxx @ 2731] +02 ffffd001`7d53d960 fffff801`61b8dd7f dxgkrnl!ADAPTER_RENDER::Reset+0x15e [d:\th\windows\core\dxkernel\dxgkrnl\core\adapter.cxx @ 19443] +03 ffffd001`7d53d990 fffff801`61ba2385 dxgkrnl!DXGADAPTER::Reset+0x177 [d:\th\windows\core\dxkernel\dxgkrnl\core\adapter.cxx @ 19316] +04 ffffd001`7d53d9e0 fffff801`63c5fba7 dxgkrnl!TdrResetFromTimeout+0x15 [d:\th\windows\core\dxkernel\dxgkrnl\core\dxgtdr.cxx @ 2554] +05 ffffd001`7d53da10 fffff801`63c47e5d dxgmms1!VidSchiRecoverFromTDR+0x11b [d:\th\windows\core\dxkernel\dxgkrnl\dxgmms1\vidsch\vidscher.cxx @ 1055] +06 ffffd001`7d53dbc0 fffff801`aa55c698 dxgmms1!VidSchiWorkerThread+0x8d [d:\th\windows\core\dxkernel\dxgkrnl\dxgmms1\vidsch\vidschi.cxx @ 426] +07 ffffd001`7d53dc00 fffff801`aa5c9306 nt!PspSystemThreadStartup+0x58 [d:\th\minkernel\ntos\ps\psexec.c @ 6845] +08 ffffd001`7d53dc60 00000000`00000000 nt!KxStartSystemThread+0x16 [d:\th\minkernel\ntos\ke\amd64\threadbg.asm @ 80] +``` + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code, if you can consistently reproduce the stop code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Verify that all graphics related software such as DirectX and OpenGL are up to date, and any graphics intensive applications (such as games) are fully patched. +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- **Using Safe Mode** + + Consider using Safe Mode to help isolate this issue. Using Safe Mode loads only the minimum required drivers and system services during the Windows startup. To enter Safe Mode, use **Update and Security** in Settings. Select **Recovery**->**Advanced startup** to boot to maintenance mode. At the resulting menu, choose **Troubleshoot**-> **Advanced Options** -> **Startup Settings** -> **Restart**. After Windows restarts to the **Startup Settings** screen, select option, 4, 5 or 6 to boot to Safe Mode. + + Safe Mode may be available by pressing a function key on boot, for example F8. Refer to information from the manufacturer for specific startup options. + +- Run the Windows Memory Diagnostics tool, to test the memory. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Remarks +------- + +**Hardware certification requirements** + +For information on requirements that hardware devices must meet when they implement TDR, refer to the WHCK documentation on *Device.Graphics…TDRResiliency*. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x117---video-tdr-timeout-detected.md b/windows-driver-docs-pr/debugger/bug-check-0x117---video-tdr-timeout-detected.md new file mode 100644 index 0000000000..593336a94a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x117---video-tdr-timeout-detected.md @@ -0,0 +1,220 @@ +--- +title: Bug Check 0x117 VIDEO_TDR_TIMEOUT_DETECTED +description: The VIDEO_TDR_TIMEOUT_DETECTED bug check has a value of 0x00000117. This indicates that the display driver failed to respond in a timely fashion. +ms.assetid: 70e24a97-f695-4d35-b52f-69dfddecd9b5 +keywords: ["Bug Check 0x117 VIDEO_TDR_TIMEOUT_DETECTED", "VIDEO_TDR_TIMEOUT_DETECTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_TDR_TIMEOUT_DETECTED +api_type: +- NA +--- + +# Bug Check 0x117: VIDEO\_TDR\_TIMEOUT\_DETECTED + + +The VIDEO\_TDR\_TIMEOUT\_DETECTED bug check has a value of 0x00000117. This indicates that the display driver failed to respond in a timely fashion. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_TDR\_TIMEOUT\_DETECTED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The pointer to the internal TDR recovery context, if available.

2

A pointer into the responsible device driver module (for example, the owner tag).

3

The secondary driver-specific bucketing key.

4

Internal context dependent data, if available.

+ +  + +Cause +----- + +A common stability problem in graphics occurs when the system appears completely frozen or hung while processing an end-user command or operation. Usually the GPU is busy processing intensive graphics operations, typically during game-play. No screen updates occur, and users assume that their system is frozen. Users usually wait a few seconds and then reboot the system by pressing the power button. Windows tries to detect these problematic hang situations and dynamically recover a responsive desktop. + +This process of detection and recovery is known as Timeout Detection and Recovery (TDR). The default timeout is 2 seconds. In the TDR process for video cards, the operating system's GPU scheduler calls the display miniport driver's [*DxgkDdiResetFromTimeout*](https://msdn.microsoft.com/library/windows/hardware/ff559815) function to reinitialize the driver and reset the GPU. + +If the recovery process is successful, a message will be displayed, indicating that the "Display driver stopped responding and has recovered." + +For more information, see Timeout Detection and Recovery (TDR), [TDR Registry Keys](https://msdn.microsoft.com/library/windows/hardware/ff569918) and [TDR changes in Windows 8](https://msdn.microsoft.com/library/windows/hardware/jj676805) which are located in [Debugging Tips for the Windows Display Driver Model (WDDM)](https://msdn.microsoft.com/library/windows/hardware/ff551790). + +Resolution +---------- + +The GPU is taking more time than permitted to display graphics to your monitor. This behavior can occur for one or more of the following reasons: + +- You may need to install the latest updates for your display driver, so that it properly supports the TDR process. +- Hardware issues that impact the ability of the video card to operate properly, including: + - Over-clocked components, such as the motherboard + - Incorrect component compatibility and settings (especially memory configuration and timings) + - Insufficient system cooling + - Insufficient system power + - Defective parts (memory modules, motherboards, etc.) +- Visual effects, or too many programs running in the background may be slowing your PC down so that the video card can not respond as necessary. + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +``` +3: kd> !analyze -v +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +VIDEO_TDR_TIMEOUT_DETECTED (117) +The display driver failed to respond in timely fashion. +(This code can never be used for a real bugcheck.) +Arguments: +Arg1: 8975d500, Optional pointer to internal TDR recovery context (TDR_RECOVERY_CONTEXT). +Arg2: 9a02381e, The pointer into responsible device driver module (e.g owner tag). +Arg3: 00000000, The secondary driver specific bucketing key. +Arg4: 00000000, Optional internal context dependent data. + +... +``` + +Also displayed will be the faulting module name + +``` +MODULE_NAME: atikmpag + +IMAGE_NAME: atikmpag.sys +``` + +You can use the lmv command to display information about the faulting driver, including the timestamp. + +``` +3: kd> lmvm atikmpag +Browse full module list +start end module name +9a01a000 9a09a000 atikmpag T (no symbols) + Loaded symbol image file: atikmpag.sys + Image path: atikmpag.sys + Image name: atikmpag.sys + Browse all global symbols functions data + Timestamp: Fri Dec 6 12:20:32 2013 (52A23190) + CheckSum: 0007E58A + ImageSize: 00080000 + Translations: 0000.04b0 0000.04e4 0409.04b0 0409.04e4 +``` + +Parameter 1 contains a pointer to the TDR\_RECOVERY\_CONTEXT. + +``` +3: kd> dt dxgkrnl!_TDR_RECOVERY_CONTEXT fffffa8010041010 + +0x000 Signature : ?? + +0x004 pState : ???? + +0x008 TimeoutReason : ?? + +0x010 Tick : _ULARGE_INTEGER + +0x018 pAdapter : ???? + +0x01c pVidSchContext : ???? + +0x020 GPUTimeoutData : _TDR_RECOVERY_GPU_DATA + +0x038 CrtcTimeoutData : _TDR_RECOVERY_CONTEXT:: + +0x040 DbgOwnerTag : ?? + +0x048 PrivateDbgInfo : _TDR_DEBUG_REPORT_PRIVATE_INFO + +0xae0 pDbgReport : ???? + +0xae4 pDbgBuffer : ???? + +0xae8 DbgBufferSize : ?? + +0xaec pDumpBufferHelper : ???? + +0xaf0 pDbgInfoExtension : ???? + +0xaf4 pDbgBufferUpdatePrivateInfo : ???? + +0xaf8 ReferenceCount : ?? +Memory read error 10041b08 +``` + +Parameter 2 contains a pointer into the responsible device driver module (for example, the owner tag). + +``` +BUGCHECK_P2: ffffffff9a02381e +``` + +You may wish to examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. + +``` +3: kd> k + # ChildEBP RetAddr +00 81d9ace0 976e605e dxgkrnl!TdrUpdateDbgReport+0x93 [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\core\dxgtdr.cxx @ 944] +01 81d9acfc 976ddead dxgkrnl!TdrCollectDbgInfoStage2+0x195 [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\core\dxgtdr.cxx @ 1759] +02 81d9ad24 976e664f dxgkrnl!DXGADAPTER::Reset+0x23f [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\core\adapter.cxx @ 14972] +03 81d9ad3c 977be9e0 dxgkrnl!TdrResetFromTimeout+0x16 [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\core\dxgtdr.cxx @ 2465] +04 81d9ad50 977b7518 dxgmms1!VidSchiRecoverFromTDR+0x13 [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\dxgmms1\vidsch\vidscher.cxx @ 1018] +05 (Inline) -------- dxgmms1!VidSchiRun_PriorityTable+0xfa71 +06 81d9ad70 812c01d4 dxgmms1!VidSchiWorkerThread+0xfaf2 [d:\blue_gdr\windows\core\dxkernel\dxgkrnl\dxgmms1\vidsch\vidschi.cxx @ 424] +07 81d9adb0 81325fb1 nt!PspSystemThreadStartup+0x58 [d:\blue_gdr\minkernel\ntos\ps\psexec.c @ 5884] +08 81d9adbc 00000000 nt!KiThreadStartup+0x15 [d:\blue_gdr\minkernel\ntos\ke\i386\threadbg.asm @ 81] +``` + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code, if you can consistently reproduce the stop code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Verify that all graphics related software such as DirectX and OpenGL are up to date, and any graphics intensive applications (such as games) are fully patched. +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- **Using Safe Mode** + + Consider using Safe Mode to help isolate this issue. Using Safe Mode loads only the minimum required drivers and system services during the Windows startup. To enter Safe Mode, use **Update and Security** in Settings. Select **Recovery**->**Advanced startup** to boot to maintenance mode. At the resulting menu, choose **Troubleshoot**-> **Advanced Options** -> **Startup Settings** -> **Restart**. After Windows restarts to the **Startup Settings** screen, select option, 4, 5 or 6 to boot to Safe Mode. + + Safe Mode may be available by pressing a function key on boot, for example F8. Refer to information from the manufacturer for specific startup options. + +- Run the Windows Memory Diagnostics tool, to test the memory. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Remarks +------- + +**Hardware certification requirements** + +For information on requirements that hardware devices must meet when they implement TDR, refer to the WHCK documentation on *Device.Graphics…TDRResiliency*. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x119---video-scheduler-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x119---video-scheduler-internal-error.md new file mode 100644 index 0000000000..ab1f07899e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x119---video-scheduler-internal-error.md @@ -0,0 +1,70 @@ +--- +title: Bug Check 0x119 VIDEO_SCHEDULER_INTERNAL_ERROR +description: The VIDEO_SCHEDULER_INTERNAL_ERROR bug check has a value of 0x00000119. This indicates that the video scheduler has detected a fatal violation. +ms.assetid: dfffdd70-c519-4e39-a604-a0ba2217093b +keywords: ["Bug Check 0x119 VIDEO_SCHEDULER_INTERNAL_ERROR", "VIDEO_SCHEDULER_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_SCHEDULER_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x119: VIDEO\_SCHEDULER\_INTERNAL\_ERROR + + +The VIDEO\_SCHEDULER\_INTERNAL\_ERROR bug check has a value of 0x00000119. This indicates that the video scheduler has detected a fatal violation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_SCHEDULER\_INTERNAL\_ERROR Parameters + + +Parameter 1 is the only parameter of interest and identifies the exact violation. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Cause of Error

0x1

The driver has reported an invalid fence ID.

0x2

The driver failed upon the submission of a command.

0x3

The driver failed upon patching the command buffer.

0x4

The driver reported an invalid flip capability.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x11a---em-initialization-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x11a---em-initialization-failure.md new file mode 100644 index 0000000000..872d46a107 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x11a---em-initialization-failure.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x11A EM_INITIALIZATION_FAILURE +description: The EM_INITIALIZATION_FAILURE bug check has a value of 0x0000011A.This bug check appears very infrequently. +ms.assetid: 322789f5-0564-4518-89a6-2c6cc9aa9020 +keywords: ["Bug Check 0x11A EM_INITIALIZATION_FAILURE", "EM_INITIALIZATION_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- EM_INITIALIZATION_FAILURE +api_type: +- NA +--- + +# Bug Check 0x11A: EM\_INITIALIZATION\_FAILURE + + +The EM\_INITIALIZATION\_FAILURE bug check has a value of 0x0000011A. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x11b---driver-returned-holding-cancel-lock.md b/windows-driver-docs-pr/debugger/bug-check-0x11b---driver-returned-holding-cancel-lock.md new file mode 100644 index 0000000000..8b64426442 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x11b---driver-returned-holding-cancel-lock.md @@ -0,0 +1,67 @@ +--- +title: Bug Check 0x11B DRIVER_RETURNED_HOLDING_CANCEL_LOCK +description: The DRIVER_RETURNED_HOLDING_CANCEL_LOCK bug check has a value of 0x0000011B. +ms.assetid: 8728dc74-cf21-490f-b3b0-1513d2310461 +keywords: ["Bug Check 0x11B DRIVER_RETURNED_HOLDING_CANCEL_LOCK", "DRIVER_RETURNED_HOLDING_CANCEL_LOCK"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_RETURNED_HOLDING_CANCEL_LOCK +api_type: +- NA +--- + +# Bug Check 0x11B: DRIVER\_RETURNED\_HOLDING\_CANCEL\_LOCK + + +The DRIVER\_RETURNED\_HOLDING\_CANCEL\_LOCK bug check has a value of 0x0000011B. This bug check indicates that a driver has returned from a *cancel* routine that holds the global cancel lock. This causes all later cancellation calls to fail, and results in either a deadlock or another bug check. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_RETURNED\_HOLDING\_CANCEL\_LOCK Parameters + + + ++++ + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the IRP that was canceled (might not be valid).

2

The address of the cancel routine.

+ +  + +Remarks +------- + +The cancel spin lock should have been released by the *cancel* routine. + +The driver calls the IoCancelIrpIoCancelIrp function to cancel an individual I/O request packet (IRP). This function acquires the cancel spin lock, sets the cancel flag in the IRP, and then calls the *cancel* routine specified by the appropriate field in the IRP, if a routine was specified. The *cancel* routine is expected to release the cancel spin lock. If there is no *cancel* routine, the cancel spin lock is released. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x11c--attempted-write-to-cm-protected-storage.md b/windows-driver-docs-pr/debugger/bug-check-0x11c--attempted-write-to-cm-protected-storage.md new file mode 100644 index 0000000000..b814ff11f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x11c--attempted-write-to-cm-protected-storage.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x11C ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE +description: The ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE bug check has a value of 0x0000011C that indicates that a write was attempted to the protected storage of the configuration manager. +ms.assetid: 5a322457-51d7-4832-8eeb-1fdc99f313e8 +keywords: ["Bug Check 0x11C ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE", "ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE +api_type: +- NA +--- + +# Bug Check 0x11C: ATTEMPTED\_WRITE\_TO\_CM\_PROTECTED\_STORAGE + + +The ATTEMPTED\_WRITE\_TO\_CM\_PROTECTED\_STORAGE bug check has a value of 0x0000011C. This bug check indicates that an attempt was made to write to the read-only protected storage of the configuration manager. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ATTEMPTED\_WRITE\_TO\_CM\_PROTECTED\_STORAGE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address for the attempted write

2

PTE contents

3

Reserved

4

Reserved

+ +  + +Remarks +------- + +When it is possible, the name of the driver that is attempting the write operation is printed as a Unicode string on the bug check screen and then saved in KiBugCheckDriver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x11d---event-tracing-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x11d---event-tracing-fatal-error.md new file mode 100644 index 0000000000..cd71de9b59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x11d---event-tracing-fatal-error.md @@ -0,0 +1,32 @@ +--- +title: Bug Check 0x11D EVENT_TRACING_FATAL_ERROR +description: The EVENT_TRACING_FATAL_ERROR bug check has a value of 0x0000011D. This bug check indicates that the Event Tracing subsystem has encountered an unexpected fatal error. +ms.assetid: 5d9dee69-d6b5-426c-9165-e2b955a9cd41 +keywords: ["Bug Check 0x11D EVENT_TRACING_FATAL_ERROR", "EVENT_TRACING_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- EVENT_TRACING_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x11D: EVENT\_TRACING\_FATAL\_ERROR + + +The EVENT\_TRACING\_FATAL\_ERROR bug check has a value of 0x0000011D. This bug check indicates that the Event Tracing subsystem has encountered an unexpected fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12--trap-cause-unknown.md b/windows-driver-docs-pr/debugger/bug-check-0x12--trap-cause-unknown.md new file mode 100644 index 0000000000..0a3d277e89 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12--trap-cause-unknown.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x12 TRAP_CAUSE_UNKNOWN +description: The TRAP_CAUSE_UNKNOWN bug check has a value of 0x00000012. This indicates that an unknown exception has occurred. +ms.assetid: 43cbcc34-9df0-4d5f-b823-1cc3cafaa811 +keywords: ["Bug Check 0x12 TRAP_CAUSE_UNKNOWN", "TRAP_CAUSE_UNKNOWN"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TRAP_CAUSE_UNKNOWN +api_type: +- NA +--- + +# Bug Check 0x12: TRAP\_CAUSE\_UNKNOWN + + +The TRAP\_CAUSE\_UNKNOWN bug check has a value of 0x00000012. This indicates that an unknown exception has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TRAP\_CAUSE\_UNKNOWN Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The unexpected interrupt

2

The unknown floating-point exception

3

The enabled and asserted status bits. See the processor definition for details.

4

Reserved

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x121---driver-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x121---driver-violation.md new file mode 100644 index 0000000000..a57d383282 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x121---driver-violation.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x121 DRIVER_VIOLATION +description: The DRIVER_VIOLATION bug check has a value of 0x00000121. This bug check indicates that a driver has caused a violation. +ms.assetid: 4a5d1d84-a958-45a6-9511-b5b4ecd4c067 +keywords: ["Bug Check 0x121 DRIVER_VIOLATION", "DRIVER_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x121: DRIVER\_VIOLATION + + +The DRIVER\_VIOLATION bug check has a value of 0x00000121. This bug check indicates that a driver has caused a violation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_VIOLATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Describes the type of violation

2

Reserved

3

Reserved

+ +  + +Remarks +------- + +Use a kernel debugger and view the call stack to determine the name of the driver that caused the violation. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x122---whea-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x122---whea-internal-error.md new file mode 100644 index 0000000000..6724e4bcbe --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x122---whea-internal-error.md @@ -0,0 +1,140 @@ +--- +title: Bug Check 0x122 WHEA_INTERNAL_ERROR +description: The WHEA_INTERNAL_ERROR bug check has a value of 0x00000122. +ms.assetid: b0bf1f27-bfdd-4d5d-aeac-f74f45c6174f +keywords: ["Bug Check 0x122 WHEA_INTERNAL_ERROR", "WHEA_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WHEA_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x122: WHEA\_INTERNAL\_ERROR + + +The WHEA\_INTERNAL\_ERROR bug check has a value of 0x00000122. This bug check indicates that an internal error in the Windows Hardware Error Architecture (WHEA) has occurred. Errors can result from a bug in the implementation of a platform-specific hardware error driver (PSHED) plug-in supplied by a vendor, the firmware implementation of error records, or the firmware implementation of error injection. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WHEA\_INTERNAL\_ERROR Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x1

Size of memory

Error source count

0

Failed to allocate enough memory for all the error sources in the hardware error source table.

0x2

Number of processors

0

0

Failed to allocate enough memory for a WHEA information block for each processor.

0x5

Status

Phase (The initialization phase for the bug check)

0

WHEA failed to allocate enough memory for the error sources, or the error source enumeration failed.

0x6

Status

Phase

Error source type

Failed to initialize the error source (Parameter 4) during the phase specified by Parameter 3.

0x7

Status

0

0

Failed to allocate enough memory.

0x8

Number of error sources

0

0

Failed to allocate enough memory for all the error source descriptors.

0x9

Error source type

Source ID

0

WHEA received an uncorrected error source from an invalid error source.

0xA

Error source type

Source ID

0

Failed to allocate an error record for an uncorrected error.

0xB

Error source type

Source ID

0

Failed to populate the error record for an uncorrected error.

+ +  + +If Parameter 1 is equal to 0x6, 0x9, 0xA, or 0xB, one of the other parameters contains the error source type. The following table gives possible values for the error source type. + +| Value | Description | +|-------|--------------------------------------| +| 0x00 | Machine check exception | +| 0x01 | Corrected machine check | +| 0x02 | Corrected platform error | +| 0x03 | Non-maskable interrupt | +| 0x04 | PCI express error | +| 0x05 | Other types of error sources/Generic | +| 0x06 | IA64 INIT error source | +| 0x07 | BOOT error source | +| 0x08 | SCI-based generic error source | +| 0x09 | Itanium machine check abort | +| 0x0A | Itanium machine check | +| 0x0B | Itanium corrected platform error | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x124---whea-uncorrectable-error.md b/windows-driver-docs-pr/debugger/bug-check-0x124---whea-uncorrectable-error.md new file mode 100644 index 0000000000..0ea6c911af --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x124---whea-uncorrectable-error.md @@ -0,0 +1,171 @@ +--- +title: Bug Check 0x124 WHEA_UNCORRECTABLE_ERROR +description: The WHEA_UNCORRECTABLE_ERROR bug check has a value of 0x00000124. This bug check indicates that a fatal hardware error has occurred. +ms.assetid: b3b7c6dd-3891-4ccb-96d1-49e8a2de34c8 +keywords: ["Bug Check 0x124 WHEA_UNCORRECTABLE_ERROR", "WHEA_UNCORRECTABLE_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WHEA_UNCORRECTABLE_ERROR +api_type: +- NA +--- + +# Bug Check 0x124: WHEA\_UNCORRECTABLE\_ERROR + + +The WHEA\_UNCORRECTABLE\_ERROR bug check has a value of 0x00000124. This bug check indicates that a fatal hardware error has occurred. This bug check uses the error data that is provided by the Windows Hardware Error Architecture (WHEA). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WHEA\_UNCORRECTABLE\_ERROR Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x0

Address of WHEA_ERROR_RECORD structure.

High 32 bits of MCi_STATUS MSR for the MCA bank that had the error.

Low 32 bits of MCi_STATUS MSR for the MCA bank that had the error.

A machine check exception occurred.

+

These parameter descriptions apply if the processor is based on the x64 architecture, or the x86 architecture that has the MCA feature available (for example, Intel Pentium Pro, Pentium IV, or Xeon).

0x1

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A corrected machine check exception occurred.

0x2

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A corrected platform error occurred.

0x3

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A nonmaskable Interrupt (NMI) error occurred.

0x4

Address of WHEA_ERROR_RECORD structure.

Reserved

Reserved.

An uncorrectable PCI Express error occurred.

0x5

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A generic hardware error occurred.

0x6

Address of WHEA_ERROR_RECORD structure

Reserved.

Reserved.

An initialization error occurred.

0x7

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A BOOT error occurred.

0x8

Address of WHEA_ERROR_RECORD structure

Reserved.

Reserved.

A Scalable Coherent Interface (SCI) generic error occurred.

0x9

Address of WHEA_ERROR_RECORD structure.

Length, in bytes, of the SAL log.

Address of the SAL log.

An uncorrectable Itanium-based machine check abort error occurred.

0xA

Address of WHEA_ERROR_RECORD structure

Reserved.

Reserved.

A corrected Itanium-based machine check error occurred.

0xB

Address of WHEA_ERROR_RECORD structure.

Reserved.

Reserved.

A corrected Itanium platform error occurred.

+ +  + +Cause +----- + +This bug check is typically related to physical hardware failures. It can be heat related, defective hardware, memory or even a processor that is beginning to fail or has failed. If over-clocking has been enabled, try disabling it. Confirm that any cooling systems such as fans are functional. Run system diagnostics to confirm that the system memory is not defective. It is less likely, but possible that a driver is causing the hardware to fail with this bug check. + +For additional general bug check troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Remarks +------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +Parameter 1 identifies the type of error source that reported the error. Parameter 2 holds the address of the WHEA\_ERROR\_RECORD structure that describes the error condition. + +When a hardware error occurs, WHEA creates an error record to store the error information associated with the hardware error condition. Each error record is described by a WHEA\_ERROR\_RECORD structure. The Windows kernel includes the error record with the Event Tracing for Windows (ETW) hardware error event that it raises in response to the error so that the error record is saved in the system event log. The format of the error records that are used by WHEA are based on the Common Platform Error Record as described in Appendix N of version 2.2 of the Unified Extensible Firmware Interface (UEFI) Specification. For more information, see [WHEA\_ERROR\_RECORD](https://msdn.microsoft.com/library/windows/hardware/ff560483) and [Windows Hardware Error Architecture (WHEA)](https://msdn.microsoft.com/library/windows/hardware/ff559509). + +You can use [**!errrec**](-errrec.md) <addr> to display the WHEA\_ERROR\_RECORD structure using the address provided in Parameter 2. The [**!whea**](-whea.md) and [**!errpkt**](-errpkt.md) extensions can be used to display additional WHEA information. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md) + +This bug check is not supported in Windows versions prior to Windows Vista. Instead, machine check exceptions are reported through [**bug check 0x9C**](bug-check-0x9c--machine-check-exception.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x127---page-not-zero.md b/windows-driver-docs-pr/debugger/bug-check-0x127---page-not-zero.md new file mode 100644 index 0000000000..9e07c835b1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x127---page-not-zero.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x127 PAGE_NOT_ZERO +description: The PAGE_NOT_ZERO bug check has a value of 0x00000127. +ms.assetid: b6485307-191d-401a-8f2e-7f4a54a630f9 +keywords: ["Bug Check 0x127 PAGE_NOT_ZERO", "PAGE_NOT_ZERO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PAGE_NOT_ZERO +api_type: +- NA +--- + +# Bug Check 0x127: PAGE\_NOT\_ZERO + + +The PAGE\_NOT\_ZERO bug check has a value of 0x00000127. This bug check indicates that a page that should have been filled with zeros was not. This bug check might occur because of a hardware error or because a privileged component of the operating system modified a page after freeing it. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PAGE\_NOT\_ZERO Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address that maps the corrupted page

2

Physical page number

3

Zero (Reserved)

4

Zero (Reserved)

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x128--worker-thread-returned-with-bad-io-priority.md b/windows-driver-docs-pr/debugger/bug-check-0x128--worker-thread-returned-with-bad-io-priority.md new file mode 100644 index 0000000000..ffc2468478 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x128--worker-thread-returned-with-bad-io-priority.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x128 WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY +description: The WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY bug check has a value of 0x00000128. This indicates that a worker threads IOPriority was wrongly modified by the called worker routine. +ms.assetid: 2659491F-2257-4553-A7A4-ECA39DD0A0F7 +keywords: ["Bug Check 0x128 WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY", "WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_RETURNED_WITH_BAD_IO_PRIORITY +api_type: +- NA +--- + +# Bug Check 0x128: WORKER\_THREAD\_RETURNED\_WITH\_BAD\_IO\_PRIORITY + + +The WORKER\_THREAD\_RETURNED\_WITH\_BAD\_IO\_PRIORITY bug check has a value of 0x00000128. This indicates that a worker threads IOPriority was wrongly modified by the called worker routine. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_RETURNED\_WITH\_BAD\_IO\_PRIORITY Parameters + + +| Parameter | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1 | Address of worker routine (Use the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) command on this address to find the offending driver) | +| 2 | Current IoPrioirity value | +| 3 | Workitem parameter | +| 4 | Workitem address | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x129--worker-thread-returned-with-bad-paging-io-priority.md b/windows-driver-docs-pr/debugger/bug-check-0x129--worker-thread-returned-with-bad-paging-io-priority.md new file mode 100644 index 0000000000..c70d1d6ea7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x129--worker-thread-returned-with-bad-paging-io-priority.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x129 WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY +description: The WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY bug check has a value of 0x00000129 that indicates that a worker threads Paging IOPriority was wrongly modified. +ms.assetid: E662D301-6B4D-4E92-BED3-4BB0731DBFD0 +keywords: ["Bug Check 0x129 WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY", "WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_RETURNED_WITH_BAD_PAGING_IO_PRIORITY +api_type: +- NA +--- + +# Bug Check 0x129: WORKER\_THREAD\_RETURNED\_WITH\_BAD\_PAGING\_IO\_PRIORITY + + +The WORKER\_THREAD\_RETURNED\_WITH\_BAD\_PAGING\_IO\_PRIORITY bug check has a value of 0x00000129. This indicates that a worker threads Paging IOPriority was wrongly modified by the called worker routine. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_RETURNED\_WITH\_BAD\_PAGING\_IO\_PRIORITY Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Address of worker routine

+

Use the [ln (List Nearest Symbols)](ln--list-nearest-symbols-.md) command on this address to find the offending driver.

2Current Paging IoPrioirity value
3Workitem parameter
4Workitem address
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12a--mui-no-valid-system-language.md b/windows-driver-docs-pr/debugger/bug-check-0x12a--mui-no-valid-system-language.md new file mode 100644 index 0000000000..0bfcfdcc76 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12a--mui-no-valid-system-language.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x12A MUI_NO_VALID_SYSTEM_LANGUAGE +description: The MUI_NO_VALID_SYSTEM_LANGUAGE bug check has a value of 0x0000012A. This indicates that Windows did not find any installed, licensed language packs for the system default UI language. +ms.assetid: 6424FC7D-BD39-4F35-9E72-E9730D27CC24 +keywords: ["Bug Check 0x12A MUI_NO_VALID_SYSTEM_LANGUAGE", "MUI_NO_VALID_SYSTEM_LANGUAGE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MUI_NO_VALID_SYSTEM_LANGUAGE +api_type: +- NA +--- + +# Bug Check 0x12A: MUI\_NO\_VALID\_SYSTEM\_LANGUAGE + + +The MUI\_NO\_VALID\_SYSTEM\_LANGUAGE bug check has a value of 0x0000012A. This indicates that Windows did not find any installed, licensed language packs for the system default UI language. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MUI\_NO\_VALID\_SYSTEM\_LANGUAGE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1The subtype of the bugcheck +

0x1 : Windows did not find any installed language packs during phase I initialization.

+Parameter 2 - NT status code that describes the reason of failure. +

0x2 : Windows did not find any installed, licensed language packs for the system default UI language during kernel cache creation.

+Parameter 2 - NT status code that describes the reason of failure. +.
2See parameter 1
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12b---faulty-hardware-corrupted-page.md b/windows-driver-docs-pr/debugger/bug-check-0x12b---faulty-hardware-corrupted-page.md new file mode 100644 index 0000000000..442602c817 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12b---faulty-hardware-corrupted-page.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x12B FAULTY_HARDWARE_CORRUPTED_PAGE +description: The FAULTY_HARDWARE_CORRUPTED_PAGE bug check has a value of 0x0000012B. This bug check indicates that a single-bit error was found in this page. This is a hardware memory error. +ms.assetid: caa57d76-946f-4394-bfcf-1dbf3813a55b +keywords: ["Bug Check 0x12B FAULTY_HARDWARE_CORRUPTED_PAGE", "FAULTY_HARDWARE_CORRUPTED_PAGE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FAULTY_HARDWARE_CORRUPTED_PAGE +api_type: +- NA +--- + +# Bug Check 0x12B: FAULTY\_HARDWARE\_CORRUPTED\_PAGE + + +The FAULTY\_HARDWARE\_CORRUPTED\_PAGE bug check has a value of 0x0000012B. This bug check indicates that a single-bit error was found in this page. This is a hardware memory error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FAULTY\_HARDWARE\_CORRUPTED\_PAGE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address maps to the corrupted page

2

Physical page number

3

Zero (Reserved)

4

Zero (Reserved)

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12c---exfat-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x12c---exfat-file-system.md new file mode 100644 index 0000000000..92a09b2a5b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12c---exfat-file-system.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x12C EXFAT_FILE_SYSTEM +description: The EXFAT_FILE_SYSTEM bug check has a value of 0x0000012C. This bug check indicates that a problem occurred in the Extended File Allocation Table (exFAT) file system. +ms.assetid: f55bbe88-d96f-494f-b84b-eda7c4e6bdfc +keywords: ["Bug Check 0x12C EXFAT_FILE_SYSTEM", "EXFAT_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- EXFAT_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x12C: EXFAT\_FILE\_SYSTEM + + +The EXFAT\_FILE\_SYSTEM bug check has a value of 0x0000012C. This bug check indicates that a problem occurred in the Extended File Allocation Table (exFAT) file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## EXFAT\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") determine the source file by its identifier number. The low 16 bits determine the source line in the file where the bug check occurred.

2

If FppExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If FppExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved.

+ +  + +Cause +----- + +This bug check is caused by the file system as a last resort when its internal accounting is in an unsupportable state and to continue poses a large risk of data loss. The file system never causes this bug check when the on disk structures are corrupted, the disk sectors go bad, or a memory allocation fails. Bad sectors could lead to a bug check, for example, when a page fault occurs in kernel code or data and the memory manager cannot read the pages. However, for this bug check, the file system is not the cause. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command together with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12d--volsnap-overlapped-table-access.md b/windows-driver-docs-pr/debugger/bug-check-0x12d--volsnap-overlapped-table-access.md new file mode 100644 index 0000000000..cdee70c1a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12d--volsnap-overlapped-table-access.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x12D VOLSNAP_OVERLAPPED_TABLE_ACCESS +description: The VOLSNAP_OVERLAPPED_TABLE_ACCESS bug check has a value of 0x0000012D that indicates that volsnap tried to access a common table from two different threads. +ms.assetid: F1D378E9-CD5D-4DA3-A200-DAED66284534 +keywords: ["Bug Check 0x12D VOLSNAP_OVERLAPPED_TABLE_ACCESS", "VOLSNAP_OVERLAPPED_TABLE_ACCESS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VOLSNAP_OVERLAPPED_TABLE_ACCESS +api_type: +- NA +--- + +# Bug Check 0x12D: VOLSNAP\_OVERLAPPED\_TABLE\_ACCESS + + +The VOLSNAP\_OVERLAPPED\_TABLE\_ACCESS bug check has a value of 0x0000012D. This indicates that volsnap tried to access a common table from two different threads which may result in table corruption and eventually corrupt the table. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VOLSNAP\_OVERLAPPED\_TABLE\_ACCESS Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12e--invalid-mdl-range.md b/windows-driver-docs-pr/debugger/bug-check-0x12e--invalid-mdl-range.md new file mode 100644 index 0000000000..bc35c0dcbf --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12e--invalid-mdl-range.md @@ -0,0 +1,54 @@ +--- +title: Bug Check 0x12E INVALID_MDL_RANGE +description: The INVALID_MDL_RANGE bug check has a value of 0x0000012E. +ms.assetid: 911192DC-17B8-4D75-A96E-2E310B30348F +keywords: ["Bug Check 0x12E INVALID_MDL_RANGE", "INVALID_MDL_RANGE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_MDL_RANGE +api_type: +- NA +--- + +# Bug Check 0x12E: INVALID\_MDL\_RANGE + + +The INVALID\_MDL\_RANGE bug check has a value of 0x0000012E. This indicates that a driver has called the IoBuildPartialMdl() function and passed it an MDL to map part of a source MDL, but the virtual address range specified is outside the range in the source MDL. This is typically a driver bug. + +The source and target MDLs, as well as the address range length to be mapped are the arguments to the IoBuildPartialMdl() function, i.e.;) . + +``` +IoBuildPartialMdl( + IN PMDL SourceMdl, + IN OUT PMDL TargetMdl, + IN PVOID VirtualAddress, + IN ULONG Length +``` + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_MDL\_RANGE Parameters + + +| Parameter | Description | +|-----------|----------------| +| 1 | SourceMdl | +| 2 | TargetMdl | +| 3 | VirtualAddress | +| 4 | Length | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x12f--vhd-boot-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x12f--vhd-boot-initialization-failed.md new file mode 100644 index 0000000000..8ac199c444 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x12f--vhd-boot-initialization-failed.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0x12F VHD_BOOT_INITIALIZATION_FAILED +description: The VHD_BOOT_INITIALIZATION_FAILED bug check has a value of 0x0000012F. This indicates that an initialization failure occurred while attempting to boot from a VHD. +ms.assetid: CC4CD97B-FCBA-4B73-AB9E-D56387D4CB07 +keywords: ["Bug Check 0x12F VHD_BOOT_INITIALIZATION_FAILED", "VHD_BOOT_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VHD_BOOT_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x12F: VHD\_BOOT\_INITIALIZATION\_FAILED + + +The VHD\_BOOT\_INITIALIZATION\_FAILED bug check has a value of 0x0000012F. This indicates that an initialization failure occurred while attempting to boot from a VHD. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VHD\_BOOT\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Action that failed

+1 : Couldn't extract VHD information from boot device. +2 : Timeout waiting for VHD parent device to surface. +3 : VHD path string memory allocation error. +4 : VHD path construction failed. +5 : VHD boot device mount failed. +6 : Disable sleep states failed. +7 : VHD information memory allocation error. +8 : VHD information construction failed.
2NT status code
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x13--empty-thread-reaper-list.md b/windows-driver-docs-pr/debugger/bug-check-0x13--empty-thread-reaper-list.md new file mode 100644 index 0000000000..ad0351b5da --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x13--empty-thread-reaper-list.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x13 EMPTY_THREAD_REAPER_LIST +description: The EMPTY_THREAD_REAPER_LIST bug check has a value of 0x00000013.This bug check appears very infrequently. +ms.assetid: 069b4d99-2bf5-4238-b80e-52eb6c732175 +keywords: ["Bug Check 0x13 EMPTY_THREAD_REAPER_LIST", "EMPTY_THREAD_REAPER_LIST"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- EMPTY_THREAD_REAPER_LIST +api_type: +- NA +--- + +# Bug Check 0x13: EMPTY\_THREAD\_REAPER\_LIST + + +The EMPTY\_THREAD\_REAPER\_LIST bug check has a value of 0x00000013. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x130--dynamic-add-processor-mismatch.md b/windows-driver-docs-pr/debugger/bug-check-0x130--dynamic-add-processor-mismatch.md new file mode 100644 index 0000000000..474ad2e115 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x130--dynamic-add-processor-mismatch.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x130 DYNAMIC_ADD_PROCESSOR_MISMATCH +description: The DYNAMIC_ADD_PROCESSOR_MISMATCH bug check has a value of 0x00000130. This bugcheck indicates that a new processor added to the system is incompatible with the current configuration. +ms.assetid: B5E7E1FF-ABF6-459B-B589-BC2CDC991B13 +keywords: ["Bug Check 0x130 DYNAMIC_ADD_PROCESSOR_MISMATCH", "DYNAMIC_ADD_PROCESSOR_MISMATCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DYNAMIC_ADD_PROCESSOR_MISMATCH +api_type: +- NA +--- + +# Bug Check 0x130: DYNAMIC\_ADD\_PROCESSOR\_MISMATCH + + +The DYNAMIC\_ADD\_PROCESSOR\_MISMATCH bug check has a value of 0x00000130. This bugcheck indicates that a new processor added to the system is incompatible with the current configuration. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DYNAMIC\_ADD\_PROCESSOR\_MISMATCH Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x131--invalid-extended-processor-state.md b/windows-driver-docs-pr/debugger/bug-check-0x131--invalid-extended-processor-state.md new file mode 100644 index 0000000000..5b39693141 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x131--invalid-extended-processor-state.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0x131 INVALID_EXTENDED_PROCESSOR_STATE +description: The INVALID_EXTENDED_PROCESSOR_STATE bug check has a value of 0x00000131. This indicates that an invalid combination of parameters was detected while saving or restoring extended processor state. +ms.assetid: 72EEA46A-1E96-4B07-A7E6-40DAE4641B20 +keywords: ["Bug Check 0x131 INVALID_EXTENDED_PROCESSOR_STATE", "INVALID_EXTENDED_PROCESSOR_STATE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_EXTENDED_PROCESSOR_STATE +api_type: +- NA +--- + +# Bug Check 0x131: INVALID\_EXTENDED\_PROCESSOR\_STATE + + +The INVALID\_EXTENDED\_PROCESSOR\_STATE bug check has a value of 0x00000131. This indicates that an invalid combination of parameters was detected while saving or restoring extended processor state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_EXTENDED\_PROCESSOR\_STATE Parameters + + +Parameter one indicates which validity check failed. + +| Parameter | Description | +|-----------|---------------------------------------------------------------------------------| +| 1 | 0 - Invalid feature mask was passed or extended processor state is not enabled. | +| 2 | Nonzero if extended state is enabled. | +| 3 | The low 32 bits of the feature mask. | +| 4 | The high 32 bits of the feature mask. | + +  + +| Parameter | Description | +|-----------|------------------------------------------------------------------------------------------------| +| 1 | 1 - An attempt to save or restore extended state was made at IRQL higher than DISPATCH\_LEVEL. | +| 2 | The IRQL | +| 3 | Reserved | +| 4 | Reserved | + +  + +| Parameter | Description | +|-----------|-----------------------------------------------------------------| +| 1 | 2 - The previously saved state is for an equal or higher level. | +| 2 | The saved level. | +| 3 | The current level. | +| 4 | Reserved | + +  + +| Parameter | Description | +|-----------|-----------------------------------------------------------| +| 1 | 3 - The previously saved state is for a different thread. | +| 2 | The saved thread. | +| 3 | The current thread. | +| 4 | Reserved | + +  + +| Parameter | Description | +|-----------|------------------------------------------------------| +| 1 | 4 - Previously saved state is for a different level. | +| 2 | The saved level. | +| 3 | The current level. | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x132--resource-owner-pointer-invalid.md b/windows-driver-docs-pr/debugger/bug-check-0x132--resource-owner-pointer-invalid.md new file mode 100644 index 0000000000..cbbd6d1ffd --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x132--resource-owner-pointer-invalid.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x132 RESOURCE_OWNER_POINTER_INVALID +description: The RESOURCE_OWNER_POINTER_INVALID bug check has a value of 0x00000132. This indicates that an invalid resource owner pointer was supplied. +ms.assetid: 0DEFEFF0-A88C-4797-BF36-0D1E532FA371 +keywords: ["Bug Check 0x132 RESOURCE_OWNER_POINTER_INVALID", "RESOURCE_OWNER_POINTER_INVALID"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RESOURCE_OWNER_POINTER_INVALID +api_type: +- NA +--- + +# Bug Check 0x132: RESOURCE\_OWNER\_POINTER\_INVALID + + +The RESOURCE\_OWNER\_POINTER\_INVALID bug check has a value of 0x00000132. This indicates that an invalid resource owner pointer was supplied. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RESOURCE\_OWNER\_POINTER\_INVALID Parameters + + +| Parameter | Description | +|-----------|-------------------------| +| 1 | Resource | +| 2 | Resource->OwnerTable | +| 3 | CurrentThread | +| 4 | OwnerPointer | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x133-dpc-watchdog-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x133-dpc-watchdog-violation.md new file mode 100644 index 0000000000..a998364c40 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x133-dpc-watchdog-violation.md @@ -0,0 +1,152 @@ +--- +title: Bug Check 0x133 DPC_WATCHDOG_VIOLATION +description: The DPC_WATCHDOG_VIOLATION bug check has a value of 0x00000133. +ms.assetid: CE9A4CBF-0016-42F7-A9EE-56DF6E61593A +keywords: ["Bug Check 0x133 DPC_WATCHDOG_VIOLATION", "DPC_WATCHDOG_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DPC_WATCHDOG_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x133 DPC\_WATCHDOG\_VIOLATION + + +The DPC\_WATCHDOG\_VIOLATION bug check has a value of 0x00000133. This bug check indicates that the DPC watchdog executed, either because it detected a single long-running deferred procedure call (DPC), or because the system spent a prolonged time at an interrupt request level (IRQL) of DISPATCH\_LEVEL or above. The value of Parameter 1 indicates whether a single DPC exceeded a timeout, or whether the system cumulatively spent an extended period of time at IRQL DISPATCH\_LEVEL or above. DPCs should not run longer than 100 microseconds and ISRs should not run longer than 25 microseconds, however the actual timeout values on the system are set much higher. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DPC\_WATCHDOG\_VIOLATION Parameters + + +*Parameter 1* indicates the type of violation. The meaning of the other parameters depends on the value of *Parameter 1*. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0

The DPC time count (in ticks)

The DPC time allotment (in ticks).

Reserved

A single DPC or ISR exceeded its time allotment. The offending component can usually be identified with a stack trace.

1

The watchdog period

Reserved

Reserved

The system cumulatively spent an extended period of time at IRQL DISPATCH_LEVEL or above. The offending component can usually be identified with a stack trace.

+ +  + +Cause +----- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +**Parameter 1 = 0** + +In this example, the tick count of 501 exceeds the DPC time allotment of 500. The image name indicates that this code was executing when the bug check occurred. + +``` +0: kd> !analyze -v +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +DPC_WATCHDOG_VIOLATION (133) +The DPC watchdog detected a prolonged run time at an IRQL of DISPATCH_LEVEL +or above. +Arguments: +Arg1: 0000000000000000, A single DPC or ISR exceeded its time allotment. The offending + component can usually be identified with a stack trace. +Arg2: 0000000000000501, The DPC time count (in ticks). +Arg3: 0000000000000500, The DPC time allotment (in ticks). +Arg4: 0000000000000000 + +... + +IMAGE_NAME: BthA2DP.sys +... +``` + +Use the following debugger commands to gather more information for failures with a parameter of 0: + +[**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) to look at what code was running when the stop code occurred. + +You may want to use the u, ub, uu (Unassemble) command to look deeper into the specifics of a the code that was running. + +The [**!pcr**](-pcr.md) extension displays the current status of the Processor Control Region (PCR) on a specific processor. In the output will be the address of the Prcb + +``` + Prcb: fffff80309974180 +``` + +You can use the [**dt (Display Type)**](dt--display-type-.md) command to display additional information about the DPCs and the DPC Watchdog. For the address use the Prcb listed in the !pcr output: + +``` +dt nt!_KPRCB fffff80309974180 Dpc* +``` + +**Parameter 1 = 1** + +For parameter of 1, the code may not stop in the offending area of code. In this case one approach is to use the event tracing to attempt to track down which driver is exceeding it's normal execution duration. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md) + +Remarks +------- + +In general this stop code is caused by faulty driver code that under certain conditions, does not complete its work within the allotted time frame. + +If you are not equipped to use the Windows debugger to this problem, you should use some basic troubleshooting techniques. + +- If a driver is identified in the bug check message, to isolate the issue, disable the driver. Check with the manufacturer for driver updates. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing bug check 0x133. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x134--drive-extender.md b/windows-driver-docs-pr/debugger/bug-check-0x134--drive-extender.md new file mode 100644 index 0000000000..9d7d0c7cb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x134--drive-extender.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x134 DRIVE_EXTENDER +description: The DRIVE_EXTENDER bug check has a value of 0x00000134. This indicates that the drive extender component has experienced a severe internal error that prevents continued system operation. +ms.assetid: 32E58C16-7754-4B7A-AE43-93FC513464E0 +keywords: ["Bug Check 0x134 DRIVE_EXTENDER", "DRIVE_EXTENDER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVE_EXTENDER +api_type: +- NA +--- + +# Bug Check 0x134: DRIVE\_EXTENDER + + +The DRIVE\_EXTENDER bug check has a value of 0x00000134. This indicates that the drive extender component has experienced a severe internal error that prevents continued system operation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVE\_EXTENDER Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x135--registry-filter-driver-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x135--registry-filter-driver-exception.md new file mode 100644 index 0000000000..bb8b853620 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x135--registry-filter-driver-exception.md @@ -0,0 +1,54 @@ +--- +title: Bug Check 0x135 REGISTRY_FILTER_DRIVER_EXCEPTION +description: The REGISTRY_FILTER_DRIVER_EXCEPTION bug check has a value of 0x00000135. This bugcheck is caused by an unhandled exception in a registry filtering driver. +ms.assetid: 99E171F4-5629-405F-993C-51287AD7D2C8 +keywords: ["Bug Check 0x135 REGISTRY_FILTER_DRIVER_EXCEPTION", "REGISTRY_FILTER_DRIVER_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REGISTRY_FILTER_DRIVER_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x135: REGISTRY\_FILTER\_DRIVER\_EXCEPTION + + +The REGISTRY\_FILTER\_DRIVER\_EXCEPTION bug check has a value of 0x00000135. This bugcheck is caused by an unhandled exception in a registry filtering driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## REGISTRY\_FILTER\_DRIVER\_EXCEPTION Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------------------------------| +| 1 | Exception Code | +| 2 | Address of the context record for the exception that caused the bugcheck | +| 3 | The driver's callback routine address | +| 4 | Reserved | + +  + +Cause +----- + +This bugcheck indicates that a registry filtering driver didn't handle an exception inside its notification routine. + +Resolution +---------- + +Identify the offending driver by using the 3rd parameter. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x136--vhd-boot-host-volume-not-enough-space.md b/windows-driver-docs-pr/debugger/bug-check-0x136--vhd-boot-host-volume-not-enough-space.md new file mode 100644 index 0000000000..8f6c7a65ad --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x136--vhd-boot-host-volume-not-enough-space.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x136 VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE +description: The VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE bug check has a value of 0x00000136 indicating an initialization failure while booting from a VHD. There is not enough free space to expand the VHD. +ms.assetid: B3CD91D0-EB8B-4793-AE4B-72AE94F6EC1B +keywords: ["Bug Check 0x136 VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE", "VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VHD_BOOT_HOST_VOLUME_NOT_ENOUGH_SPACE +api_type: +- NA +--- + +# Bug Check 0x136: VHD\_BOOT\_HOST\_VOLUME\_NOT\_ENOUGH\_SPACE + + +The VHD\_BOOT\_HOST\_VOLUME\_NOT\_ENOUGH\_SPACE bug check has a value of 0x00000136. This indicates that an initialization failure occurred while attempting to boot from a VHD. The volume that hosts the VHD does not have enough free space to expand the VHD. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VHD\_BOOT\_HOST\_VOLUME\_NOT\_ENOUGH\_SPACE Parameters + + +| Parameter | Description | +|-----------|---------------------------------------------| +| 1 | 0 : Unable to expand VHD file to full size. | +| 2 | NT Status Code | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x137--win32k-handle-manager.md b/windows-driver-docs-pr/debugger/bug-check-0x137--win32k-handle-manager.md new file mode 100644 index 0000000000..4b4b2fb554 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x137--win32k-handle-manager.md @@ -0,0 +1,46 @@ +--- +title: Bug Check 0x137 WIN32K_HANDLE_MANAGER +description: The WIN32K_HANDLE_MANAGER bug check has a value of 0x00000137. This indicates that the win32k/ntuser handle manager has detected a fatal error. +ms.assetid: 1DD53B1D-EFAA-42D3-9085-B5A76B54DF1A +keywords: ["Bug Check 0x137 WIN32K_HANDLE_MANAGER", "WIN32K_HANDLE_MANAGER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_HANDLE_MANAGER +api_type: +- NA +--- + +# Bug Check 0x137: WIN32K\_HANDLE\_MANAGER + + +The WIN32K\_HANDLE\_MANAGER bug check has a value of 0x00000137. This indicates that the win32k/ntuser handle manager has detected a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_HANDLE\_MANAGER Parameters + + +| Parameter | Description | +|-----------|--------------------------------------| +| 1 | Reserved | +| 2 | Address of the object (If available) | +| 3 | Reserved | +| 4 | Reserved | + +  + +Under some circumstances, additional parameters not listed here may be returned. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x138-gpio-controller-driver-error.md b/windows-driver-docs-pr/debugger/bug-check-0x138-gpio-controller-driver-error.md new file mode 100644 index 0000000000..a2a9a1bbd2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x138-gpio-controller-driver-error.md @@ -0,0 +1,109 @@ +--- +title: Bug Check 0x138 GPIO_CONTROLLER_DRIVER_ERROR +description: The GPIO_CONTROLLER_DRIVER_ERROR bug check has a value of 0x00000138. This bug check indicates that the GPIO class extension driver encountered a fatal error. +ms.assetid: 4025D968-10F9-4F2F-953F-914A4BE7D883 +keywords: ["Bug Check 0x138 GPIO_CONTROLLER_DRIVER_ERROR", "GPIO_CONTROLLER_DRIVER_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- GPIO_CONTROLLER_DRIVER_ERROR +api_type: +- NA +--- + +# Bug Check 0x138: GPIO\_CONTROLLER\_DRIVER\_ERROR + + +The GPIO\_CONTROLLER\_DRIVER\_ERROR bug check has a value of 0x00000138. This bug check indicates that the GPIO class extension driver encountered a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## GPIO\_CONTROLLER\_DRIVER\_ERROR Parameters + + +*Parameter 1* indicates the type of violation. The meaning of the other parameters depends on the value of *Parameter 1*. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

1

GSIV

Reserved

Reserved

The GPIO controller managing the specific GSIV is not registered.

2

Context value

Reserved

Reserved

A client driver specified an invalid context to a lock or unlock request.

3

Indicates whether a critical transition is being requested.

Indicates whether the bank is already in F1 due to a non-critical transition.

Indicates whether the bank is already in F1 due to a critical transition.

PoFx requested that the GPIO controller send a bank through an inappropriate F1 power state and/or a critical transition.

4

Indicates whether a critical transition is being requested.

Indicates whether the bank is in F1 due to a non-critical transition.

Indicates whether the bank is in F1 due to a critical transition.

PoFx requested that the GPIO controller send a bank through an inappropriate F0 power state and/or a critical transition.

5

NTSTATUS

GPIO device extension

GPIO interrupt parameters

An on-Soc GPIO interrupt operation failed.

6

NTSTATUS

GPIO device extension

GPIO IO parameters

An on-Soc GPIO IO operation failed.

7

Revision ID

Function Index

Reserved

A _DSM method returned malformed data.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x13a--kernel-mode-heap-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0x13a--kernel-mode-heap-corruption.md new file mode 100644 index 0000000000..7e322eb0ba --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x13a--kernel-mode-heap-corruption.md @@ -0,0 +1,79 @@ +--- +title: Bug Check 0x13A KERNEL_MODE_HEAP_CORRUPTION +description: The KERNEL_MODE_HEAP_CORRUPTION bug check has a value of 0x0000013A. This indicates that the kernel mode heap manager has detected corruption in a heap. +ms.assetid: 806669B3-B811-462A-A3B6-2F583BF0E19A +keywords: ["Bug Check 0x13A KERNEL_MODE_HEAP_CORRUPTION", "KERNEL_MODE_HEAP_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_MODE_HEAP_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0x13A: KERNEL\_MODE\_HEAP\_CORRUPTION + + +The KERNEL\_MODE\_HEAP\_CORRUPTION bug check has a value of 0x0000013A. This indicates that the kernel mode heap manager has detected corruption in a heap. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_MODE\_HEAP\_CORRUPTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Type of corruption detected

+0x3 : A corrupt entry header was detected. +0x4 : Multiple corrupt entry headers were detected. +0x5 : A corrupt entry header in a large allocation was detected. +0x6 : A corruption was detected with features consistent with a buffer overrun. +0x7 : A corruption was detected with features consistent with a buffer underrun. +0x8 : A free block was passed to an operation that is only valid for busy blocks. +0x9 : An invalid argument was specified for the current operation. +0xA : A corruption was detected with features consistent with a use-after-free error. +0xB : The wrong heap was specified for the current operation. +0xC : A corrupt free list was detected. +0xD : The heap detected list corruption in a list other than the free list.
2Address of the heap that reported the corruption
3Address at which the corruption was detected
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x13b--passive-interrupt-error.md b/windows-driver-docs-pr/debugger/bug-check-0x13b--passive-interrupt-error.md new file mode 100644 index 0000000000..3dcd052170 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x13b--passive-interrupt-error.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x13B PASSIVE_INTERRUPT_ERROR +description: The PASSIVE_INTERRUPT_ERROR bug check has a value of 0x0000013B. This indicates that the kernel has detected issues with the passive-level interrupt. +ms.assetid: 6C921FCB-B945-4909-BAD3-1DBD6E3CAA54 +keywords: ["Bug Check 0x13B PASSIVE_INTERRUPT_ERROR", "PASSIVE_INTERRUPT_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PASSIVE_INTERRUPT_ERROR +api_type: +- NA +--- + +# Bug Check 0x13B: PASSIVE\_INTERRUPT\_ERROR + + +The PASSIVE\_INTERRUPT\_ERROR bug check has a value of 0x0000013B. This indicates that the kernel has detected issues with the passive-level interrupt. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PASSIVE\_INTERRUPT\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Type of error detected

+0x1 : A driver tried to acquire an interrupt spinlock but passed in a passive-level interrupt object.
2Address of the KINTERRUPT object for the passive-level interrupt.
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x13c--invalid-io-boost-state.md b/windows-driver-docs-pr/debugger/bug-check-0x13c--invalid-io-boost-state.md new file mode 100644 index 0000000000..c329c70b2b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x13c--invalid-io-boost-state.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x13C INVALID_IO_BOOST_STATE +description: The INVALID_IO_BOOST_STATE bug check has a value of 0x0000013C. This indicates that a thread exited with an invalid I/O boost state. This should be zero when a thread exits. +ms.assetid: BDCD8A3A-1F26-41A4-95B0-9B2CEBD333AC +keywords: ["Bug Check 0x13C INVALID_IO_BOOST_STATE", "INVALID_IO_BOOST_STATE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_IO_BOOST_STATE +api_type: +- NA +--- + +# Bug Check 0x13C: INVALID\_IO\_BOOST\_STATE + + +The INVALID\_IO\_BOOST\_STATE bug check has a value of 0x0000013C. This indicates that a thread exited with an invalid I/O boost state. This should be zero when a thread exits. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_IO\_BOOST\_STATE Parameters + + +| Parameter | Description | +|-----------|---------------------------------------------------------| +| 1 | Pointer to the thread which had the invalid boost state | +| 2 | Current boost state or throttle count | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x13d--critical-initialization-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x13d--critical-initialization-failure.md new file mode 100644 index 0000000000..ccdc8a5991 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x13d--critical-initialization-failure.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x13D CRITICAL_INITIALIZATION_FAILURE +description: The CRITICAL_INITIALIZATION_FAILURE bug check has a value of 0x0000013D. This indicates that early kernel initialization has failed. +ms.assetid: 6983C044-223E-4C58-91A9-5C89C9C0FAC9 +keywords: ["Bug Check 0x13D CRITICAL_INITIALIZATION_FAILURE", "CRITICAL_INITIALIZATION_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRITICAL_INITIALIZATION_FAILURE +api_type: +- NA +--- + +# Bug Check 0x13D: CRITICAL\_INITIALIZATION\_FAILURE + + +The CRITICAL\_INITIALIZATION\_FAILURE bug check has a value of 0x0000013D. This indicates that early kernel initialization has failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CRITICAL\_INITIALIZATION\_FAILURE Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14--create-delete-lock-not-locked.md b/windows-driver-docs-pr/debugger/bug-check-0x14--create-delete-lock-not-locked.md new file mode 100644 index 0000000000..1492c1d3b7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14--create-delete-lock-not-locked.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x14 CREATE_DELETE_LOCK_NOT_LOCKED +description: The CREATE_DELETE_LOCK_NOT_LOCKED bug check has a value of 0x00000014.This bug check appears very infrequently. +ms.assetid: 5a0c44c8-c864-43c3-b4d8-15801c59a94b +keywords: ["Bug Check 0x14 CREATE_DELETE_LOCK_NOT_LOCKED", "CREATE_DELETE_LOCK_NOT_LOCKED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CREATE_DELETE_LOCK_NOT_LOCKED +api_type: +- NA +--- + +# Bug Check 0x14: CREATE\_DELETE\_LOCK\_NOT\_LOCKED + + +The CREATE\_DELETE\_LOCK\_NOT\_LOCKED bug check has a value of 0x00000014. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x140--storage-device-abnormality-detected.md b/windows-driver-docs-pr/debugger/bug-check-0x140--storage-device-abnormality-detected.md new file mode 100644 index 0000000000..452870505e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x140--storage-device-abnormality-detected.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x140 STORAGE_DEVICE_ABNORMALITY_DETECTED +description: The STORAGE_DEVICE_ABNORMALITY_DETECTED bug check has a value of 0x00000140 that indicates that the storage driver stack encountered a failure to respond. +ms.assetid: 7D0C8F15-EC9C-47A5-9EF4-3FB8E21CAD9A +keywords: ["Bug Check 0x140 STORAGE_DEVICE_ABNORMALITY_DETECTED", "STORAGE_DEVICE_ABNORMALITY_DETECTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- STORAGE_DEVICE_ABNORMALITY_DETECTED +api_type: +- NA +--- + +# Bug Check 0x140: STORAGE\_DEVICE\_ABNORMALITY\_DETECTED + + +The STORAGE\_DEVICE\_ABNORMALITY\_DETECTED bug check has a value of 0x00000140. This indicates that the storage driver stack encountered rate of responsiveness violations, exceeding the threshold, or other failures to respond. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## STORAGE\_DEVICE\_ABNORMALITY\_DETECTED Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x141---video-engine-timeout-detected.md b/windows-driver-docs-pr/debugger/bug-check-0x141---video-engine-timeout-detected.md new file mode 100644 index 0000000000..1a3ab625ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x141---video-engine-timeout-detected.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x141 VIDEO_ENGINE_TIMEOUT_DETECTED +description: The VIDEO_ENGINE_TIMEOUT_DETECTED bug check has a value of 0x00000141. This indicates that one of the display engines failed to respond in timely fashion. +ms.assetid: 0912495D-DE6D-4064-BD66-DA6145889821 +keywords: ["Bug Check 0x141 VIDEO_ENGINE_TIMEOUT_DETECTED", "VIDEO_ENGINE_TIMEOUT_DETECTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_ENGINE_TIMEOUT_DETECTED +api_type: +- NA +--- + +# Bug Check 0x141: VIDEO\_ENGINE\_TIMEOUT\_DETECTED + + +The VIDEO\_ENGINE\_TIMEOUT\_DETECTED bug check has a value of 0x00000141. This indicates that one of the display engines failed to respond in timely fashion. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_ENGINE\_TIMEOUT\_DETECTED Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------------------------------------------| +| 1 | Optional pointer to internal TDR recovery context (TDR\_RECOVERY\_CONTEXT). | +| 2 | The pointer into responsible device driver module (e.g owner tag). | +| 3 | The secondary driver specific bucketing key. | +| 4 | Optional internal context dependent data. | + +  + +Remarks +------- + +Secondary data of tag {270A33FD-3DA6-460D-BA89-3C1BAE21E39B} contains additional TDR related data. Use .enumtag to view the data. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x142--video-tdr-application-blocked.md b/windows-driver-docs-pr/debugger/bug-check-0x142--video-tdr-application-blocked.md new file mode 100644 index 0000000000..3d2271d54b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x142--video-tdr-application-blocked.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x142 VIDEO_TDR_APPLICATION_BLOCKED +description: The VIDEO_TDR_APPLICATION_BLOCKED bug check has a value of 0x00000142. This indicates that an application has been blocked from accessing graphics hardware. +ms.assetid: B97FCA51-C368-4144-A364-50135A8DE836 +keywords: ["Bug Check 0x142 VIDEO_TDR_APPLICATION_BLOCKED", "VIDEO_TDR_APPLICATION_BLOCKED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_TDR_APPLICATION_BLOCKED +api_type: +- NA +--- + +# Bug Check 0x142: VIDEO\_TDR\_APPLICATION\_BLOCKED + + +The VIDEO\_TDR\_APPLICATION\_BLOCKED bug check has a value of 0x00000142. This indicates that an application has been blocked from accessing graphics hardware. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_TDR\_APPLICATION\_BLOCKED Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------------------------------------------| +| 1 | Optional pointer to internal TDR recovery context (TDR\_RECOVERY\_CONTEXT). | +| 2 | The pointer into responsible device driver module (e.g owner tag). | +| 3 | The secondary driver specific bucketing key. | +| 4 | Id of the process being blocked from accessing the GPU. | + +  + +Remarks +------- + +Secondary data of tag {270A33FD-3DA6-460D-BA89-3C1BAE21E39B} contains additional TDR related data. Use [**.enumtag (Enumerate Secondary Callback Data)**](-enumtag--enumerate-secondary-callback-data-.md) to view the data. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x143--processor-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x143--processor-driver-internal.md new file mode 100644 index 0000000000..86e0e59fab --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x143--processor-driver-internal.md @@ -0,0 +1,91 @@ +--- +title: Bug Check 0x143 PROCESSOR_DRIVER_INTERNAL +description: The PROCESSOR_DRIVER_INTERNAL bug check has a value of 0x00000143. This indicates that the Processor Power Management (PPM) driver encountered a fatal error. +ms.assetid: B61A1DF1-4454-4418-866F-FD9EC96F6906 +keywords: ["Bug Check 0x143 PROCESSOR_DRIVER_INTERNAL", "PROCESSOR_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PROCESSOR_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x143: PROCESSOR\_DRIVER\_INTERNAL + + +The PROCESSOR\_DRIVER\_INTERNAL bug check has a value of 0x00000143. This indicates that the Processor Power Management (PPM) driver encountered a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PROCESSOR\_DRIVER\_INTERNAL Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------------------------------| +| 1 | 1 - Power Engine Plugin(PEP) failed to accept a required notification | +| 2 | PEP runtime Notification type | +| 3 | Pointer to notification message | +| 4 | Pointer to processor device context (FDO\_DATA) issuing the notification | + +  + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
12 - Power Engine Plugin (PEP) returned invalid processor idle state
2

Type of invalid state

+

0x0 : PEP requested too many processors for coordinated idle state

+Parameter 3 - Number of processors requested to participate in coordinated idle transitions +Parameter 4 - Pointer to processor device context (FDO_DATA) +

0x1 : PEP requested processor to be in an invalid idle state

+Parameter 3 - Idle state index requested +Parameter 4 - Pointer to processor device context (FDO_DATA) corresponding to the invalid idle state +

0x2 : PEP requested the platform to be in an invalid idle state

+Parameter 3 - Platform idle state index requested +Parameter 4 - Pointer to processor device context (FDO_DATA) corresponding to the invalid idle state
3Refer to parameter 2
4Refer to parameter 2
+ +  + +Cause +----- + +The processor driver detected an irreconcilable condition which prompted it to bugcheck. This likely happens during the processor idle and perf-state change execution, which may involve other entities such has kernel, HAL and the Power Engine Plugin (PEP). Information from bugcheck will help identify which of the assumptions made by the processor driver in dealing with other entities was violated. The root cause may lie in other entities and a dump file may reveal more information to ascertain the reason for the bugcheck. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x144--bugcode-usb3-driver.md b/windows-driver-docs-pr/debugger/bug-check-0x144--bugcode-usb3-driver.md new file mode 100644 index 0000000000..70a1f00a56 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x144--bugcode-usb3-driver.md @@ -0,0 +1,413 @@ +--- +title: Bug Check 0x144 BUGCODE_USB3_DRIVER +description: The BUGCODE_USB3_DRIVER bug check has a value of 0x00000144. This is the code used for all USB 3 bug checks. +ms.assetid: 39414287-3E20-405B-846A-B7F9F8AEE078 +keywords: ["Bug Check 0x144 BUGCODE_USB3_DRIVER", "BUGCODE_USB3_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BUGCODE_USB3_DRIVER +api_type: +- NA +--- + +# Bug Check 0x144: BUGCODE\_USB3\_DRIVER + + +The **BUGCODE\_USB3\_DRIVER** bug check has a value of 0x00000144. This is the code used for all USB 3 bug checks. Parameter 1 specifies the type of the USB 3 bug check, and the meanings of the other parameters are dependent on Parameter 1. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BUGCODE\_USB3\_DRIVER Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x1

Optional. Pointer to the IRP used to resend the URB

Pointer to the URB

Pointer to the client driver's device object

A client driver used an URB that it had previously sent to the core stack.

0x2

Pointer to the physical device object (PDO) for the boot device

Reserved

Reserved

A boot or paging device failed re-enumeration.

0x3

Optional. Pointer to the IRP used to send the URB

Pointer to the corrupted URB

Pointer to the client driver's device object

A client driver sent a corrupted URB to the core stack. This can happen because the client driver did not allocate the URB using USBD_xxxUrbAllocate or because the client driver did a buffer underrun for the URB.

0x800

IRQL at which the Open Static Streams request was sent

Pointer to the Open Static Streams IRP

Pointer to the client driver's device object

An Open Static Streams request was sent at IRQL > PASSIVE LEVEL.

0x801

Pointer to the Open Static Streams IRP

Pointer to the Open Static Streams URB

Pointer to the client driver's device object

A client driver attempted to open static streams before querying for streams capability. A client driver cannot open a static stream until after it successfully queries for the streams capability. For more information, see Remarks.

0x802

Number of static streams that the client driver tried to open

Number of static streams that were granted to the client driver

Pointer to the client driver's device object

A Client driver tried to open an invalid number of static streams. The number of streams cannot be 0 and cannot be greater than the value returned to the client driver in the query USB capability call.

0x803

Pointer to the Open Static Streams IRP

Pointer to the Open Static Streams URB

Pointer to the client driver's device object

A client driver attempted to open static streams for an endpoint that already had static streams open. Before opening static streams, the client driver must close the previously opened static streams.

0x804

The leaked handle context. Run !usbanalyze -v to get information about the leaked handle and URBs. You must enable Driver Verifier for the client driver.

Device object passed to [USBD_CreateHandle](https://msdn.microsoft.com/library/windows/hardware/hh406241).

Reserved

A client driver forgot to close a handle it created earlier using [USBD_CreateHandle](https://msdn.microsoft.com/library/windows/hardware/hh406241) or forgot to free an URB it allocated.

0x805

[WDFREQUEST](https://msdn.microsoft.com/library/windows/hardware/ff542962) handle for the Close Static Streams URB

Pointer to the Close Static Streams URB

Pointer to the client driver's device object

A client driver sent a Close Static Streams URB in an invalid state (for example, after processing D0 Exit).

0x806

Pointer to the IRP

Pointer to the URB

Pointer to the client driver's device object

A client driver attempted to send a chained [MDL](https://msdn.microsoft.com/library/windows/hardware/ff554414) before querying for chained MDL capability. A client driver cannot send a chained MDL until after it successfully queries for the chained MDL capability. For more information, see Remarks.

0x807

Pointer to the chained [MDL](https://msdn.microsoft.com/library/windows/hardware/ff554414)

Pointer to the URB

Pointer to the client driver's device object if available

A client driver sent an URB to the core stack with a transfer buffer length longer than the byte count (returned by [MmGetMdlByteCount](https://msdn.microsoft.com/library/windows/hardware/ff554530)) of the [MDL](https://msdn.microsoft.com/library/windows/hardware/ff554414) passed in. For more information, see Remarks.

0x1001

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The xHCI controller asserted the HSE bit, which indicates a host system error.

0x1002

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The xHCI controller asserted the HCE bit, which indicates a host controller error.

0x1003

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The xHCI stop endpoint command returned an unhandled completion code.

0x1004

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The xHCI endpoint state received a context state error after an xHCI endpoint stop command was issued.

0x1005

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Set dequeue pointer failed during an attempt to clear stall on control endpoint.

0x1006

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Reset EP failed during an attempt to clear stall on control endpoint.

0x1007

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The reset of the xHCI controller failed during reset recovery.

0x1008

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The restart of the xHCI controller failed during reset recovery.

0x1009

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

An xHCI controller command failed to complete after the command timeout abort.

0x100A

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Set dequeue pointer failed during an attempt to set the dequeue pointer after endpoint stop completion.

0x100B

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The stop of the xHCI controller failed during reset recovery.

0x100C

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The firmware in the xHCI controller is not supported. The xHCI driver will not load on this controller unless the firmware is updated.

0x100D

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller was detected to be physically removed.

0x100E

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The driver detect an error on a stream enabled endpoint.

0x100F

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The firmware in the xHCI controller is outdated. The xHCI driver will continue working with this controller but may run into some issues. A firmware update is recommended.

0x1010

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

A transfer event TRB completed with an unhandled completion code.

0x1011

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller reported that the event ring became full. The controller is also known to drop events when this happens.

0x1012

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller completed a command out of order.

0x1013

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

After command abort completion, the command ring dequeue pointer reported by the controller is incorrect.

0x1014

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

After enable slot completion, controller gave us a bad slot id.

0x1015

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Controller failed a SetAddress command with BSR1. That is unexpected.

0x1016

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Controller failed to enable a slot during a usbdevice reset. This is unexpected.

0x1017

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Controller failed an endpoints configure command where we were deconfiguring the endpoints. That is unexpected.

0x1018

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Controller failed a disable slot command. That is unexpected.

0x1019

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Controller failed a USB device reset command. That is unexpected.

0x101A

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

After endpoint reset, Set Dequeue Pointer command failed.

0x101B

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The xHCI reset endpoint command returned an unhandled completion code.

0x101C

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The D0Entry for xHCI failed.

0x101D

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Temporarily dropping and adding a stream endpoint (as two commands) failed, when using the Configure Endpoint command instead of Set Dequeue Pointer during request cancellation.

0x101E

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller indicated a transfer completion that was not pending on the controller. EventData == 1 (dereferencing the Transfer Event TRB's pointer would have caused a bugcheck)

0x101F

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller indicated a transfer completion that was not pending on the controller. EventData == 0 (logical address in transfer event TRB not matched)

0x1020

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

The controller indicated a transfer completion that was not pending on the controller. EventData == 0 (logical address in transfer event TRB not matched) The Transfer Event TRB may be redundant (points somewhere near a recently completed request).

0x1021

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Temporarily dropping and adding a stream endpoint (as two commands) failed, when using the Configure Endpoint command as part of resetting an endpoint that was not Halted.

0x1022

XHCI_LIVEDUMP_CONTEXT

Reserved

Reserved

Dropping and adding the same endpoint (as one command) failed.

0x3000

USBHUB3_LIVEDUMP_CONTEXT

Reserved

Reserved

A misbehaving hub was successfully reset by the hub driver.

0x3001

USBHUB3_LIVEDUMP_CONTEXT

Reserved

Reserved

A misbehaving hub failed to be reset successfully by the hub driver.

0x3002

USBHUB3_LIVEDUMP_CONTEXT

Reserved

Reserved

A non-function SuperSpeed hub was disabled by the hub driver.

0x3003

USBHUB3_LIVEDUMP_CONTEXT

Reserved

Reserved

A USB device failed enumeration.

+ +  + +Remarks +------- + +To query for a USB capability, the client driver must call [**WdfUsbTargetDeviceQueryUsbCapability**](https://msdn.microsoft.com/library/windows/hardware/hh439434) or [**USBD\_QueryUsbCapability**](https://msdn.microsoft.com/library/windows/hardware/hh406230) + +To send a chained [**MDL**](https://msdn.microsoft.com/library/windows/hardware/ff554414), the client driver must call [**USBD\_QueryUsbCapability**](https://msdn.microsoft.com/library/windows/hardware/hh406230) and use **URB\_FUNCTION\_BULK\_OR\_INTERRUPT\_TRANSFER\_USING\_CHAINED\_MDL** or **URB\_FUNCTION\_ISOCH\_TRANSFER\_USING\_CHAINED\_MDL**. + +## See also + + +[Universal Serial Bus (USB)](https://msdn.microsoft.com/library/windows/hardware/ff538930) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x145--secure-boot-violation-.md b/windows-driver-docs-pr/debugger/bug-check-0x145--secure-boot-violation-.md new file mode 100644 index 0000000000..f4506d3942 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x145--secure-boot-violation-.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x145 SECURE_BOOT_VIOLATION +description: The SECURE_BOOT_VIOLATION bug check has a value of 0x00000145. This indicates that the secure Boot policy enforcement could not be started. +ms.assetid: C877C655-D94D-45B5-82DB-1361F0B020D2 +keywords: ["Bug Check 0x145 SECURE_BOOT_VIOLATION", "SECURE_BOOT_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SECURE_BOOT_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x145: SECURE\_BOOT\_VIOLATION + + +The SECURE\_BOOT\_VIOLATION bug check has a value of 0x00000145. This indicates that the secure Boot policy enforcement could not be started due to an invalid policy or a required operation not being completed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SECURE\_BOOT\_VIOLATION Parameters + + +| Parameter | Description | +|-----------|------------------------------------| +| 1 | The status code of the failure. | +| 2 | Address of the Secure Boot policy. | +| 3 | Size of the Secure Boot policy. | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x147--abnormal-reset-detected.md b/windows-driver-docs-pr/debugger/bug-check-0x147--abnormal-reset-detected.md new file mode 100644 index 0000000000..e62667ed6b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x147--abnormal-reset-detected.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x147 ABNORMAL_RESET_DETECTED +description: The ABNORMAL_RESET_DETECTED bug check has a value of 0x00000147. This indicates that Windows underwent an abnormal reset. +ms.assetid: 83D537CD-AEDA-466F-A150-411131DE54B0 +keywords: ["Bug Check 0x147 ABNORMAL_RESET_DETECTED", "ABNORMAL_RESET_DETECTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ABNORMAL_RESET_DETECTED +api_type: +- NA +--- + +# Bug Check 0x147: ABNORMAL\_RESET\_DETECTED + + +The ABNORMAL\_RESET\_DETECTED bug check has a value of 0x00000147. This indicates that Windows underwent an abnormal reset. No context or exception records were saved, and bugcheck callbacks were not called. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ABNORMAL\_RESET\_DETECTED Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x149--refs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x149--refs-file-system.md new file mode 100644 index 0000000000..f1c763ca1f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x149--refs-file-system.md @@ -0,0 +1,58 @@ +--- +title: Bug Check 0x149 REFS_FILE_SYSTEM +description: The REFS_FILE_SYSTEM bug check has a value of 0x00000149. This indicates that a file system error has occurred. +ms.assetid: 899E89E7-46CD-4143-B1DC-7959F01643CF +keywords: ["Bug Check 0x149 REFS_FILE_SYSTEM", "REFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x149: REFS\_FILE\_SYSTEM + + +The REFS\_FILE\_SYSTEM bug check has a value of 0x00000149. This indicates that a file system error has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## REFS\_FILE\_SYSTEM Parameters + + +| Parameter | Description | +|-----------|--------------------------------------| +| 1 | \_\_LINE\_\_ | +| 2 | ExceptionRecord | +| 3 | ContextRecord | +| 4 | ExceptionRecord->ExceptionAddress | + +  + +| Parameter | Description | +|-----------|-------------| +| 1 | Message | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +Resolution +---------- + +If you see RefsExceptionFilter on the stack then the 2nd and 3rd parameters are the exception record and context record. Do a .exr on the 2nd parameter to view the exception information. Do a .cxr on the 3rd parameter and then kb to obtain a more informative stack trace. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14a--kernel-wmi-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x14a--kernel-wmi-internal.md new file mode 100644 index 0000000000..1c45446f41 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14a--kernel-wmi-internal.md @@ -0,0 +1,71 @@ +--- +title: Bug Check 0x14A KERNEL_WMI_INTERNAL +description: The KERNEL_WMI_INTERNAL bug check has a value of 0x0000014A. This indicates that the internal kernel WMI subsystem has encountered a fatal error. +ms.assetid: 2E739F6B-4618-44A5-B060-F2BCB77B82A3 +keywords: ["Bug Check 0x14A KERNEL_WMI_INTERNAL", "KERNEL_WMI_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_WMI_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x14A: KERNEL\_WMI\_INTERNAL + + +The KERNEL\_WMI\_INTERNAL bug check has a value of 0x0000014A. This indicates that the internal kernel WMI subsystem has encountered a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_WMI\_INTERNAL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

0 : A kernel WMI entry reference count was incremented from 0.

+Parameter 2: Pointer to the kernel WMI entry. +

1 : A kernel WMI datasource was removed prematurely.

+Parameter 2: Pointer to the kernel WMI datasource.
2See parameter 1
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14b--soc-subsystem-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x14b--soc-subsystem-failure.md new file mode 100644 index 0000000000..4305d69d59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14b--soc-subsystem-failure.md @@ -0,0 +1,141 @@ +--- +title: Bug Check 0x14B SOC_SUBSYSTEM_FAILURE +description: The SOC_SUBSYSTEM_FAILURE bug check has a value of 0x0000014B. This indicates that an unrecoverable error was encountered in a System on a Chip (SoC) subsystem. +ms.assetid: CC42D634-90CE-43F1-8552-E5DE711D2117 +keywords: ["Bug Check 0x14B SOC_SUBSYSTEM_FAILURE", "Bug Check 0x14B SOC_SUBSYSTEM_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Bug Check 0x14B SOC_SUBSYSTEM_FAILURE +api_type: +- NA +--- + +# Bug Check 0x14B: SOC\_SUBSYSTEM\_FAILURE + + +The SOC\_SUBSYSTEM\_FAILURE bug check has a value of 0x0000014B. This indicates that an unrecoverable error was encountered in a System on a Chip (SoC) subsystem. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## Bug Check 0x14B SOC\_SUBSYSTEM\_FAILURE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of an [SOC_SUBSYSTEM_FAILURE_DETAILS](https://msdn.microsoft.com/library/windows/hardware/dn376404) structure.

2

Reserved.

3

Reserved.

4

Optional. Address of a vendor-supplied data block.

+ +  + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +``` +2: kd> !analyze -v +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +SOC_SUBSYSTEM_FAILURE (14b) +A SOC subsystem has experienced an unrecoverable critical fault. +Arguments: +Arg1: 9aa8d630, nt!SOC_SUBSYSTEM_FAILURE_DETAILS +Arg2: 00000000, Reserved +Arg3: 00000000, Reserved +Arg4: a126c000, (Optional) address to vendor supplied general purpose data block. +``` + +Use the provided nt!SOC\_SUBSYSTEM\_FAILURE\_DETAILS structure to dump the failure data using the dt command and the address provided by Arg1. + +``` +2: kd> dt nt!SOC_SUBSYSTEM_FAILURE_DETAILS 9aa8d630 + +0x000 SubsysType : 1 ( SOC_SUBSYS_AUDIO_DSP ) + +0x008 FirmwareVersion : 0 + +0x010 HardwareVersion : 0 + +0x018 UnifiedFailureRegionSize : 0x24 + +0x01c UnifiedFailureRegion : [1] "F" +``` + +Work with SoC vendor to further parse the data, including the optional vendor supplied general purpose data block. + +You may want to examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. You can specify the processor number to examine the stacks on all processors. + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

+ +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14c--fatal-abnormal-reset-error.md b/windows-driver-docs-pr/debugger/bug-check-0x14c--fatal-abnormal-reset-error.md new file mode 100644 index 0000000000..89fbdd6c8f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14c--fatal-abnormal-reset-error.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x14C FATAL_ABNORMAL_RESET_ERROR +description: The FATAL_ABNORMAL_RESET_ERROR bug check has a value of 0x0000014C. This indicates that an unrecoverable system error occurred or the system has abnormally reset. +ms.assetid: 46E624EE-CA84-443E-95C2-E128E8D03188 +keywords: ["Bug Check 0x14C FATAL_ABNORMAL_RESET_ERROR", "FATAL_ABNORMAL_RESET_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FATAL_ABNORMAL_RESET_ERROR +api_type: +- NA +--- + +# Bug Check 0x14C: FATAL\_ABNORMAL\_RESET\_ERROR + + +The FATAL\_ABNORMAL\_RESET\_ERROR bug check has a value of 0x0000014C. This indicates that an unrecoverable system error occurred or the system has abnormally reset. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FATAL\_ABNORMAL\_RESET\_ERROR Parameters + + +None + +Cause +----- + +The system encountered an unexpected error and restarted. Issues that may cause this error include: hardware watchdog timer in application or auxiliary processors indicating a system hang, user-initiated key sequence because of a hang, a brownout, or failures in the default bugcheck path. The cache may not be flushed and the resulting full memory dump may not contain the current thread context. + +Secondary data of tag {E1D08891-D5A3-45F9-B811-AD711DFB2607} contains additional “Blackbox” data. Use [**.enumtag (Enumerate Secondary Callback Data)**](-enumtag--enumerate-secondary-callback-data-.md) to view the data. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14d--exception-scope-invalid.md b/windows-driver-docs-pr/debugger/bug-check-0x14d--exception-scope-invalid.md new file mode 100644 index 0000000000..dba22e0e0f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14d--exception-scope-invalid.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x14D EXCEPTION_SCOPE_INVALID +description: The EXCEPTION_SCOPE_INVALID bug check has a value of 0x0000014D. This indicates that an internal inconsistency in exception dispatching has been detected. +ms.assetid: 17355775-6D78-479D-839E-D73F0684E67C +keywords: ["Bug Check 0x14D EXCEPTION_SCOPE_INVALID", "EXCEPTION_SCOPE_INVALID"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- EXCEPTION_SCOPE_INVALID +api_type: +- NA +--- + +# Bug Check 0x14D: EXCEPTION\_SCOPE\_INVALID + + +The EXCEPTION\_SCOPE\_INVALID bug check has a value of 0x0000014D. This indicates that an internal inconsistency in exception dispatching has been detected. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## EXCEPTION\_SCOPE\_INVALID Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14e--soc-critical-device-removed.md b/windows-driver-docs-pr/debugger/bug-check-0x14e--soc-critical-device-removed.md new file mode 100644 index 0000000000..806a500594 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14e--soc-critical-device-removed.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x14E SOC_CRITICAL_DEVICE_REMOVED +description: The SOC_CRITICAL_DEVICE_REMOVED bug check has a value of 0x0000014E. This indicates that a critical SOC device has been unexpectedly removed or failed. +ms.assetid: FC0A9CED-F078-4651-BD3E-4246ED36E81A +keywords: ["Bug Check 0x14E SOC_CRITICAL_DEVICE_REMOVED", "SOC_CRITICAL_DEVICE_REMOVED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SOC_CRITICAL_DEVICE_REMOVED +api_type: +- NA +--- + +# Bug Check 0x14E: SOC\_CRITICAL\_DEVICE\_REMOVED + + +The SOC\_CRITICAL\_DEVICE\_REMOVED bug check has a value of 0x0000014E. This indicates that a critical SOC device has been unexpectedly removed or failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SOC\_CRITICAL\_DEVICE\_REMOVED Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------------------------------------------------| +| 1 | When available, indicates the ID of the device which was removed (4 character packed code) | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x14f--pdc-watchdog-timeout.md b/windows-driver-docs-pr/debugger/bug-check-0x14f--pdc-watchdog-timeout.md new file mode 100644 index 0000000000..4cf5ea3779 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x14f--pdc-watchdog-timeout.md @@ -0,0 +1,80 @@ +--- +title: Bug Check 0x14F PDC_WATCHDOG_TIMEOUT +description: The PDC_WATCHDOG_TIMEOUT bug check has a value of 0x0000014F. This indicates that a system component failed to respond within the allocated time period. +ms.assetid: 347D31C2-7027-44BD-A0E8-60C6EC3A2030 +keywords: ["Bug Check 0x14F PDC_WATCHDOG_TIMEOUT", "PDC_WATCHDOG_TIMEOUT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PDC_WATCHDOG_TIMEOUT +api_type: +- NA +--- + +# Bug Check 0x14F: PDC\_WATCHDOG\_TIMEOUT + + +The PDC\_WATCHDOG\_TIMEOUT bug check has a value of 0x0000014F. This indicates that a system component failed to respond within the allocated time period, preventing the system from exiting connected standby. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PDC\_WATCHDOG\_TIMEOUT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1Client ID of the hung component.
2

Client type of the hung component.

+

0x1 : A notification client failed to respond.

+Parameter 3: Pointer to the notification client (PDC_NOTIFICATION_CLIENT). +Parameter 4: Pointer to a pdc!PDC_14F_TRIAGE structure. +

0x2 : A resiliency client failed to respond.

+Parameter 3: Pointer to the resiliency client (PDC_RESILIENCY_CLIENT). +Parameter 4: Pointer to a pdc!PDC_14F_TRIAGE structure. +

0x3 : An activator client held a reference for too long.

+Parameter 3: Pointer to the activation client (pdc!_PDC_ACTIVATOR_CLIENT). +Parameter 4: Pointer to a pdc!PDC_14F_TRIAGE structure. +

0x100 : Win32k did not complete a monitor-on request in a timely manner.

+Parameter 3: The most recent POWER_MONITOR_REQUEST_REASON value for this request. +Parameter 4: A value indicating the internal path taken to initiate the request.
3See parameter 2
4See parameter 2
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15--last-chance-called-from-kmode.md b/windows-driver-docs-pr/debugger/bug-check-0x15--last-chance-called-from-kmode.md new file mode 100644 index 0000000000..5aae52a6c4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15--last-chance-called-from-kmode.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x15 LAST_CHANCE_CALLED_FROM_KMODE +description: The LAST_CHANCE_CALLED_FROM_KMODE bug check has a value of 0x00000015.This bug check appears very infrequently. +ms.assetid: e0839e78-ba14-484c-9570-012a11896ad0 +keywords: ["Bug Check 0x15 LAST_CHANCE_CALLED_FROM_KMODE", "LAST_CHANCE_CALLED_FROM_KMODE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LAST_CHANCE_CALLED_FROM_KMODE +api_type: +- NA +--- + +# Bug Check 0x15: LAST\_CHANCE\_CALLED\_FROM\_KMODE + + +The LAST\_CHANCE\_CALLED\_FROM\_KMODE bug check has a value of 0x00000015. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x150--tcpip-aoac-nic-active-reference-leak.md b/windows-driver-docs-pr/debugger/bug-check-0x150--tcpip-aoac-nic-active-reference-leak.md new file mode 100644 index 0000000000..3222fb67a7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x150--tcpip-aoac-nic-active-reference-leak.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x150 TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK +description: The TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK bug check has a value of 0x00000150. This indicates that the NIC active reference should have been released when the send queue was fully drained. +ms.assetid: D48424B0-DE50-46E5-B63C-76B653C9176B +keywords: ["Bug Check 0x150 TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK", "TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TCPIP_AOAC_NIC_ACTIVE_REFERENCE_LEAK +api_type: +- NA +--- + +# Bug Check 0x150: TCPIP\_AOAC\_NIC\_ACTIVE\_REFERENCE\_LEAK + + +The TCPIP\_AOAC\_NIC\_ACTIVE\_REFERENCE\_LEAK bug check has a value of 0x00000150. This indicates that the NIC active reference should have been released when the send queue was fully drained. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TCPIP\_AOAC\_NIC\_ACTIVE\_REFERENCE\_LEAK Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x151--unsupported-instruction-mode.md b/windows-driver-docs-pr/debugger/bug-check-0x151--unsupported-instruction-mode.md new file mode 100644 index 0000000000..806160ed30 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x151--unsupported-instruction-mode.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x151 UNSUPPORTED_INSTRUCTION_MODE +description: The UNSUPPORTED_INSTRUCTION_MODE bug check has a value of 0x00000151. +ms.assetid: 2FB679D8-9FA3-423D-BCA1-5EDE88C78FBF +keywords: ["Bug Check 0x151 UNSUPPORTED_INSTRUCTION_MODE", "UNSUPPORTED_INSTRUCTION_MODE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNSUPPORTED_INSTRUCTION_MODE +api_type: +- NA +--- + +# Bug Check 0x151: UNSUPPORTED\_INSTRUCTION\_MODE + + +The UNSUPPORTED\_INSTRUCTION\_MODE bug check has a value of 0x00000151. This indicates that an attempt was made to execute code using an unsupported processor instruction mode (for example, executing classic ARM instructions instead of ThumbV2 instructions). This is not permitted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UNSUPPORTED\_INSTRUCTION\_MODE Parameters + + +| Parameter | Description | +|-----------|------------------------------------------------| +| 1 | Program counter when the problem was detected. | +| 2 | Trap Frame | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x152--invalid-push-lock-flags.md b/windows-driver-docs-pr/debugger/bug-check-0x152--invalid-push-lock-flags.md new file mode 100644 index 0000000000..42f06d9d99 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x152--invalid-push-lock-flags.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x152 INVALID_PUSH_LOCK_FLAGS +description: The INVALID_PUSH_LOCK_FLAGS bug check has a value of 0x00000152. This indicates that the flags supplied to one of push lock APIs were invalid. +ms.assetid: E225CF12-42E8-490B-865D-E8153C388874 +keywords: ["Bug Check 0x152 INVALID_PUSH_LOCK_FLAGS", "INVALID_PUSH_LOCK_FLAGS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_PUSH_LOCK_FLAGS +api_type: +- NA +--- + +# Bug Check 0x152: INVALID\_PUSH\_LOCK\_FLAGS + + +The INVALID\_PUSH\_LOCK\_FLAGS bug check has a value of 0x00000152. This indicates that the flags supplied to one of push lock APIs were invalid. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_PUSH\_LOCK\_FLAGS Parameters + + +| Parameter | Description | +|-----------|------------------------------------------| +| 1 | The invalid flags supplied by the caller | +| 2 | The address of the push lock | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x153--kernel-lock-entry-leaked-on-thread-termination.md b/windows-driver-docs-pr/debugger/bug-check-0x153--kernel-lock-entry-leaked-on-thread-termination.md new file mode 100644 index 0000000000..b4f760c873 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x153--kernel-lock-entry-leaked-on-thread-termination.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x153 KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION +description: The KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION bug check has a value of 0x00000153. This indicates that a thread was terminated before it had freed all its AutoBoost lock entries. +ms.assetid: 0837C084-DAB8-4064-903D-10CD5CDE65E5 +keywords: ["Bug Check 0x153 KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION", "KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_LOCK_ENTRY_LEAKED_ON_THREAD_TERMINATION +api_type: +- NA +--- + +# Bug Check 0x153: KERNEL\_LOCK\_ENTRY\_LEAKED\_ON\_THREAD\_TERMINATION + + +The KERNEL\_LOCK\_ENTRY\_LEAKED\_ON\_THREAD\_TERMINATION bug check has a value of 0x00000153. This indicates that a thread was terminated before it had freed all its AutoBoost lock entries. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_LOCK\_ENTRY\_LEAKED\_ON\_THREAD\_TERMINATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1The address of the thread
2The address of the entry that was not freed
3

A status code indicating the state of the entry

+

0x1 : Lock pointer was not NULL

+

0x2 : Thread pointer reserved bits were set

+

0x3 : Thread pointer was corrupted

+

0x4 : The entry had residual IO or CPU boosts left

4Reserved
+ +  + +Cause +----- + +This is typically caused when a thread never released a lock it previously acquired (e.g. by relying on another thread to release it), or if the thread did not supply a consistent set of flags to lock package APIs. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x154--unexpected-store-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x154--unexpected-store-exception.md new file mode 100644 index 0000000000..c7f0e3373b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x154--unexpected-store-exception.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x154 UNEXPECTED_STORE_EXCEPTION +description: The UNEXPECTED_STORE_EXCEPTION bug check has a value of 0x00000154. This indicates that the store component caught an unexpected exception. +ms.assetid: 5D51212E-459C-4F58-9321-5E55FD793401 +keywords: ["Bug Check 0x154 UNEXPECTED_STORE_EXCEPTION", "UNEXPECTED_STORE_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNEXPECTED_STORE_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x154: UNEXPECTED\_STORE\_EXCEPTION + + +The UNEXPECTED\_STORE\_EXCEPTION bug check has a value of 0x00000154. This indicates that the store component caught an unexpected exception. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UNEXPECTED\_STORE\_EXCEPTION Parameters + + +| Parameter | Description | +|-----------|----------------------------------------------| +| 1 | Pointer to the store context or data manager | +| 2 | Exception information | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x155--os-data-tampering.md b/windows-driver-docs-pr/debugger/bug-check-0x155--os-data-tampering.md new file mode 100644 index 0000000000..619ce498a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x155--os-data-tampering.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x155 OS_DATA_TAMPERING +description: The OS_DATA_TAMPERING bug check has a value of 0x00000155. +ms.assetid: 14FE8B69-C260-41DE-AE01-BE127ABB6267 +keywords: ["Bug Check 0x155 OS_DATA_TAMPERING", "OS_DATA_TAMPERING"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- OS_DATA_TAMPERING +api_type: +- NA +--- + +# Bug Check 0x155: OS\_DATA\_TAMPERING + + +The OS\_DATA\_TAMPERING bug check has a value of 0x00000155. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## OS\_DATA\_TAMPERING Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x156--winsock-detected-hung-closesocket-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x156--winsock-detected-hung-closesocket-livedump.md new file mode 100644 index 0000000000..9b5708d178 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x156--winsock-detected-hung-closesocket-livedump.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x156 WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP +description: The WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP bug check has a value of 0x00000156. This indicates that Winsock detected a hung transport endpoint close request. +ms.assetid: F5B53149-3051-459C-834A-6AE17C56AEE6 +keywords: ["Bug Check 0x156 WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP", "WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WINSOCK_DETECTED_HUNG_CLOSESOCKET_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x156: WINSOCK\_DETECTED\_HUNG\_CLOSESOCKET\_LIVEDUMP + + +The WINSOCK\_DETECTED\_HUNG\_CLOSESOCKET\_LIVEDUMP bug check has a value of 0x00000156. This indicates that Winsock detected a hung transport endpoint close request. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WINSOCK\_DETECTED\_HUNG\_CLOSESOCKET\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1AFD endpoint pointer (!afdkd.endp <ptr>)
2

Transport endpoint type

+

0x1 : UDP datagram

+

0x2 : RAW datagram

+

0x3 : TCP listener

+

0x4 : TCP endpoint

3Number of buffered send bytes for datagram endpoints
4afd!NETIO_SUPER_TRIAGE_BLOCK
+ +  + +Cause +----- + +While processing a closesocket request, Winsock detected a hung transport endpoint close request. The system generated a live dump for analysis, then the closesocket request was completed without waiting for the completion of hung transport endpoint close request. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x157--kernel-thread-priority-floor-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x157--kernel-thread-priority-floor-violation.md new file mode 100644 index 0000000000..3adf63ad9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x157--kernel-thread-priority-floor-violation.md @@ -0,0 +1,71 @@ +--- +title: Bug Check 0x157 KERNEL_THREAD_PRIORITY_FLOOR_VIOLATION +description: The ATTEMPTED_SWITCH_FROM_DPC bug check has a value of 0x00000157. This indicates that an illegal operation was attempted on the priority floor of a particular thread. +ms.assetid: 93D15A0A-1413-47DB-91E8-DB61A3604BB1 +keywords: ["Bug Check 0x157 KERNEL_THREAD_PRIORITY_FLOOR_VIOLATION", "KERNEL_THREAD_PRIORITY_FLOOR_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_THREAD_PRIORITY_FLOOR_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x157: KERNEL\_THREAD\_PRIORITY\_FLOOR\_VIOLATION + + +The ATTEMPTED\_SWITCH\_FROM\_DPC bug check has a value of 0x00000157. This indicates that an illegal operation was attempted on the priority floor of a particular thread. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_THREAD\_PRIORITY\_FLOOR\_VIOLATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1The address of the thread
2The target priority value
3

A status code indicating the nature of the violation

+0x1 : The priority counter for the target priority over-flowed +0x2 : The priority counter for the target priority under-flowed +0x3 : The target priority value was illegal
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x158--illegal-iommu-page-fault.md b/windows-driver-docs-pr/debugger/bug-check-0x158--illegal-iommu-page-fault.md new file mode 100644 index 0000000000..df8a30b4d3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x158--illegal-iommu-page-fault.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x158 ILLEGAL_IOMMU_PAGE_FAULT +description: The ILLEGAL_IOMMU_PAGE_FAULT bug check has a value of 0x00000158. This indicates that the IOMMU has delivered a page fault packet for an invalid ASID. +ms.assetid: E26C9B67-A332-4AE9-9325-9A3378EC9B36 +keywords: ["Bug Check 0x158 ILLEGAL_IOMMU_PAGE_FAULT", "ILLEGAL_IOMMU_PAGE_FAULT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ILLEGAL_IOMMU_PAGE_FAULT +api_type: +- NA +--- + +# Bug Check 0x158: ILLEGAL\_IOMMU\_PAGE\_FAULT + + +The ILLEGAL\_IOMMU\_PAGE\_FAULT bug check has a value of 0x00000158. This indicates that the IOMMU has delivered a page fault packet for an invalid ASID. This is not safe since the ASID may have already been reused. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ILLEGAL\_IOMMU\_PAGE\_FAULT Parameters + + +| Parameter | Description | +|-----------|---------------------------------------| +| 1 | The invalid ASID. | +| 2 | The number of ASIDs currently in use. | +| 3 | The process using this ASID. | +| 4 | The ASID's reference count. | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x159--hal-illegal-iommu-page-fault.md b/windows-driver-docs-pr/debugger/bug-check-0x159--hal-illegal-iommu-page-fault.md new file mode 100644 index 0000000000..4070d42b7e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x159--hal-illegal-iommu-page-fault.md @@ -0,0 +1,53 @@ +--- +title: Bug Check 0x159 HAL_ILLEGAL_IOMMU_PAGE_FAULT +description: The HAL_ILLEGAL_IOMMU_PAGE_FAULT bug check has a value of 0x00000159. +ms.assetid: 2431EDC4-53B3-4E17-86D8-3B6911B21C98 +keywords: ["Bug Check 0x159 HAL_ILLEGAL_IOMMU_PAGE_FAULT", "HAL_ILLEGAL_IOMMU_PAGE_FAULT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HAL_ILLEGAL_IOMMU_PAGE_FAULT +api_type: +- NA +--- + +# Bug Check 0x159: HAL\_ILLEGAL\_IOMMU\_PAGE\_FAULT + + +The HAL\_ILLEGAL\_IOMMU\_PAGE\_FAULT bug check has a value of 0x00000159. This indicates that the IOMMU has delivered a page fault against an ASID that was in the process of being freed. The driver was responsible for completing any inflight requests before this point in time and this bugcheck indicates a driver in the system did not do so. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## HAL\_ILLEGAL\_IOMMU\_PAGE\_FAULT Parameters + + +| Parameter | Description | +|-----------|-----------------------------------| +| 1 | IOMMU Vendor disambiguation | +| 2 | Pointer to fault packet | +| 3 | Vendor specific fault packet data | +| 4 | Vendor specific fault packet data | + +  + +| Parameter | Description | +|-----------|---------------------------------------| +| 1 | IOMMU Vendor disambiguation = 0x3xxx. | +| 2 | Status | +| 3 | PASID | +| 4 | DirectoryBase | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15a--sdbus-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x15a--sdbus-internal-error.md new file mode 100644 index 0000000000..ba8916606d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15a--sdbus-internal-error.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x15A SDBUS_INTERNAL_ERROR +description: The SDBUS_INTERNAL_ERROR bug check has a value of 0x0000015A. This indicates that an unrecoverable hardware failure has occurred on an SD-attached device. +ms.assetid: C5FBE617-DADD-452C-A1BC-A0DE228FF2DE +keywords: ["Bug Check 0x15A SDBUS_INTERNAL_ERROR", "SDBUS_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SDBUS_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x15A: SDBUS\_INTERNAL\_ERROR + + +The SDBUS\_INTERNAL\_ERROR bug check has a value of 0x0000015A. This indicates that an unrecoverable hardware failure has occurred on an SD-attached device. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SDBUS\_INTERNAL\_ERROR Parameters + + +| Parameter | Description | +|-----------|----------------------------------------------------------------| +| 1 | Pointer to the internal SD work packet that caused the failure | +| 2 | Pointer the controller socket information | +| 3 | Pointer to the SD request packet sent down to the bus driver | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15b--worker-thread-returned-with-system-page-priority-active.md b/windows-driver-docs-pr/debugger/bug-check-0x15b--worker-thread-returned-with-system-page-priority-active.md new file mode 100644 index 0000000000..730d2db5b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15b--worker-thread-returned-with-system-page-priority-active.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x15B WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE +description: The WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE bug check has a value of 0x0000015B that indicates a worker thread's system page priority was leaked. +ms.assetid: F618AA35-54BC-4923-99C8-311DB1D20C71 +keywords: ["Bug Check 0x15B WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE", "WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_RETURNED_WITH_SYSTEM_PAGE_PRIORITY_ACTIVE +api_type: +- NA +--- + +# Bug Check 0x15B: WORKER\_THREAD\_RETURNED\_WITH\_SYSTEM\_PAGE\_PRIORITY\_ACTIVE + + +The WORKER\_THREAD\_RETURNED\_WITH\_SYSTEM\_PAGE\_PRIORITY\_ACTIVE bug check has a value of 0x0000015B. This indicates that a worker thread's system page priority was leaked by the called worker routine. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_RETURNED\_WITH\_SYSTEM\_PAGE\_PRIORITY\_ACTIVE Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------------------------------------| +| 1 | Address of worker routine (do ln on this address to find the offending driver) | +| 2 | Current system page priority value | +| 3 | WorkItem parameter | +| 4 | WorkItem address | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15c--pdc-watchdog-timeout-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x15c--pdc-watchdog-timeout-livedump.md new file mode 100644 index 0000000000..d60e8eeaa3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15c--pdc-watchdog-timeout-livedump.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x15C PDC_WATCHDOG_TIMEOUT_LIVEDUMP +description: The PDC_WATCHDOG_TIMEOUT_LIVEDUMP bug check has a value of 0x0000015C that indicates that a system component failed to respond, preventing entering or exiting connected standby. +ms.assetid: 4FBB884D-99B5-4564-95D5-396323651C5A +keywords: ["Bug Check 0x15C PDC_WATCHDOG_TIMEOUT_LIVEDUMP", "PDC_WATCHDOG_TIMEOUT_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PDC_WATCHDOG_TIMEOUT_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x15C: PDC\_WATCHDOG\_TIMEOUT\_LIVEDUMP + + +The PDC\_WATCHDOG\_TIMEOUT\_LIVEDUMP bug check has a value of 0x0000015C. This indicates that a system component failed to respond within the allocated time period, preventing the system from entering or exiting connected standby. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PDC\_WATCHDOG\_TIMEOUT\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1Client ID of the hung component.
2

Client type of the hung component.

+0x1 : A notification client failed to respond. +

3 - Pointer to the notification client (pdc!_PDC_NOTIFICATION_CLIENT).

+

4 - Pointer to a pdc!PDC_14F_TRIAGE structure.

+0x2 : A resiliency client failed to respond. +

3 - Pointer to the resiliency client (pdc!_PDC_RESILIENCY_CLIENT).

+

4 - Pointer to a pdc!PDC_14F_TRIAGE structure.

+0x3 : An activator client held a reference for too long +

3 - Pointer to the activation client (pdc!_PDC_ACTIVATOR_CLIENT).

+

4 - Pointer to a pdc!PDC_14F_TRIAGE structure.

3See parameter 2
4See parameter 2
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15d-soc-subsystem-failure-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x15d-soc-subsystem-failure-livedump.md new file mode 100644 index 0000000000..3bf3cf39e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15d-soc-subsystem-failure-livedump.md @@ -0,0 +1,124 @@ +--- +title: Bug Check 0x15D SOC_SUBSYSTEM_FAILURE_LIVEDUMP +description: The SOC_SUBSYSTEM_FAILURE_LIVEDUMP bug code has a value of 0x0000015D. +ms.assetid: F7903E88-1706-46E6-A5D0-6972702058A8 +keywords: ["Bug Check 0x15D SOC_SUBSYSTEM_FAILURE_LIVEDUMP", "Bug Check 0x14B SOC_SUBSYSTEM_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Bug Check 0x14B SOC_SUBSYSTEM_FAILURE +api_type: +- NA +--- + +# Bug Check 0x15D: SOC\_SUBSYSTEM\_FAILURE\_LIVEDUMP + + +The SOC\_SUBSYSTEM\_FAILURE\_LIVEDUMP bug code has a value of 0x0000015D. This indicates that a System on a Chip (SoC) subsystem has experienced a critical fault and has captured a live kernel dump. The SoC subsystem does not generate a bug check in this situation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## Bug Check 0x14B SOC\_SUBSYSTEM\_FAILURE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of an [SOC_SUBSYSTEM_FAILURE_DETAILS](https://msdn.microsoft.com/library/windows/hardware/dn376404) structure.

2

Reserved.

3

Reserved.

4

Optional. Address of a vendor-supplied data block.

+ +  + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +Use the provided nt!SOC\_SUBSYSTEM\_FAILURE\_DETAILS structure to dump the failure data using the dt command and the address provided by Arg1. + +``` +2: kd> dt nt!SOC_SUBSYSTEM_FAILURE_DETAILS 9aa8d630 + +0x000 SubsysType : 1 ( SOC_SUBSYS_AUDIO_DSP ) + +0x008 FirmwareVersion : 0 + +0x010 HardwareVersion : 0 + +0x018 UnifiedFailureRegionSize : 0x24 + +0x01c UnifiedFailureRegion : [1] "F" +``` + +Work with SoC vendor to further parse the data, including the optional vendor supplied general purpose data block. + +You may want to examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. You can specify the processor number to examine the stacks on all processors. + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

+ +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15e-bugcode-ndis-driver-live-dump.md b/windows-driver-docs-pr/debugger/bug-check-0x15e-bugcode-ndis-driver-live-dump.md new file mode 100644 index 0000000000..b1094caec1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15e-bugcode-ndis-driver-live-dump.md @@ -0,0 +1,158 @@ +--- +title: Bug Check 0x15E BUGCODE_NDIS_DRIVER_LIVE_DUMP +description: The BUGCODE_NDIS_DRIVER_LIVE_DUMP bug code has a value of 0x0000015E. This bug code indicates that NDIS has captured a live kernel dump. NDIS does not generate a bug check in this situation. +ms.assetid: 3663A955-A1D7-4880-BD83-0976012F2CB1 +keywords: ["Bug Check 0x15E BUGCODE_NDIS_DRIVER_LIVE_DUMP", "BUGCODE_NDIS_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BUGCODE_NDIS_DRIVER +api_type: +- NA +--- + +# Bug Check 0x15E: BUGCODE\_NDIS\_DRIVER\_LIVE\_DUMP + + +The BUGCODE\_NDIS\_DRIVER\_LIVE\_DUMP bug code has a value of 0x0000015E. This bug code indicates that NDIS has captured a live kernel dump. NDIS does not generate a bug check in this situation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BUGCODE\_NDIS\_DRIVER Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. If a Parameter's value is "0," that means it is not used. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 1 Value and Cause of ErrorParameter 2Parameter 3Parameter 4

0x01

NDIS_BUGCHECK_MINIPORT_FATAL_ERROR

+

A miniport driver has encountered a fatal error and requested re-enumeration.

The address of the miniport block. Run [!ndiskd.minidriver](-ndiskd-minidriver.md) with this address for more information.

The address of the miniport's Physical Device Object (PDO)

The fatal error that caused this live dump to be taken. Possible values:

+
    +
  1. 70: Caused by user mode
  2. +
  3. 71: Caused by [NdisMRemoveMiniport](https://msdn.microsoft.com/library/windows/hardware/ff563661)
  4. +
  5. 72: Caused by [NdisIMInitializeDeviceInstanceEx](https://msdn.microsoft.com/library/windows/hardware/ff562727) failing
  6. +
  7. 73: Caused by [MiniportRestart](https://msdn.microsoft.com/library/windows/hardware/ff559435) failing
  8. +
  9. 74: Caused by failing a [OID_PNP_SET_POWER (D0)](https://msdn.microsoft.com/library/windows/hardware/ff569780) request
  10. +
  11. 75: Caused by failing a [OID_PNP_SET_POWER (Dx)](https://msdn.microsoft.com/library/windows/hardware/ff569780) request
  12. +

0x25

NDIS_BUGCHECK_WATCHDOG

+

An attempt to manage the network stack has taken too long. When NDIS calls out into other drivers, NDIS starts a watchdog timer to ensure the call completes promptly. If the call takes too long, NDIS injects a bugcheck.

+

This can be caused by a simple deadlock. Look with "!stacks 2 ndis" or similar to see if any threads look suspicious. Pay special attention to the PrimaryThread from the NDIS_WATCHDOG_TRIAGE_BLOCK.

+

This can be caused by lost NBLs, in which case [!ndiskd.pendingnbls](-ndiskd-pendingnbls.md) may help. Check for OIDs that are stuck using [!ndiskd.oid](-ndiskd-oid.md).

The operation that took too long. Possible values:

+
    +
  • 0x01 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_PAUSE

    +

    There was a timeout while pausing a protocol driver.

  • +
  • 0x02 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_NETPNPEVENT

    +

    There was a timeout while delivering a NET_PNP_EVENT_NOTIFICATION to a protocol driver.

  • +
  • 0x03 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_STATUS_INDICATION

    +

    There was a timeout while delivering a status indication to a protocol driver.

  • +
  • 0x04 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_UNBIND

    +

    There was a timeout while unbinding a protocol driver.

  • +
  • 0x11 : NDIS_BUGCHECK_WATCHDOG_FILTER_PAUSE

    +

    There was a timeout while pausing a filter driver.

  • +
  • 0x12 : NDIS_BUGCHECK_WATCHDOG_FILTER_NETPNPEVENT

    +

    There was a timeout while delivering a NET_PNP_EVENT_NOTIFICATION to a filter driver.

  • +
  • 0x13 : NDIS_BUGCHECK_WATCHDOG_FILTER_STATUS_INDICATION

    +

    There was a timeout while delivering a status indication to a filter driver.

  • +
  • 0x14 : NDIS_BUGCHECK_WATCHDOG_FILTER_DETACH

    +

    There was a timeout while detaching a filter driver.

  • +
  • 0x21 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_PAUSE

    +

    There was a timeout while pausing a miniport adapter.

  • +
  • 0x22 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_HALT

    +

    There was a timeout while halting a miniport adapter.

  • +
  • 0x23 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_OID

    +

    There was a timeout while delivering an OID request to a miniport adapter.

  • +
  • 0x24 : NDIS_BUGCHECK_WATCHDOG_FILTER_OID

    +

    There was a timeout while delivering an OID request to a filter driver.

  • +
  • 0x25 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_IDLE

    +

    There was a timeout while idling a miniport adapter.

  • +
  • 0x26 : NDIS_BUGCHECK_WATCHDOG_CANCEL_IDLE

    +

    There was a timeout while canceling an idle request on a miniport adapter.

  • +

Cast to ndis!NDIS_WATCHDOG_TRIAGE_BLOCK. Useful fields:

+
    +
  • StartTime shows what time the operation started, in 100ns units, as returned by KeQueryInterruptTime.
  • +
  • TimeoutMilliseconds shows how long NDIS waited, at a minimum, before triggering this bugcheck.
  • +
  • TargetObject is a handle to the protocol, filter module, or miniport adapter that NDIS is waiting on. Run [!ndiskd.protocol](-ndiskd-protocol.md), [!ndiskd.filter](-ndiskd-filter.md), or [!ndiskd.netadapter](-ndiskd-netadapter.md) with this handle for more information.
  • +
  • PrimaryThread is the thread on which NDIS initiated the operation. Usually, this is the first place to look, although the thread may have gone elsewhere if the operation is being handled asynchronously.
  • +

The value of Parameter 4 depends on the value of Parameter 2. Each number in this list corresponds to the same number in Parameter 2.

+
    +
  • 0x01 : 0
  • +
  • 0x02 : The NET_PNP_EVENT_CODE of the stuck event. For more information about these codes, see [NET_PNP_EVENT](https://msdn.microsoft.com/library/windows/hardware/ff568751)..
  • +
  • 0x03 : The NDIS_STATUS code of the stuck indication. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x04 : 0
  • +
  • 0x11 : 0
  • +
  • 0x12 : The NET_PNP_EVENT_CODE of the stuck event. For possible values, see the previous list of values for item 2 in this list.
  • +
  • 0x13 : The NDIS_STATUS code of the stuck indication. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x14 : 0
  • +
  • 0x21 : 0
  • +
  • 0x22 : 0
  • +
  • 0x23 : The OID code of the stuck request. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x24 : The OID code of the stuck request. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x25 : 0
  • +
  • 0x26 : 0
  • +

0x30

NDIS_BUGCHECK_STUCK_NBL

+

A miniport driver has not returned a NBL back to the stack for some time.

The address of the miniport block. Run [!ndiskd.minidriver](-ndiskd-minidriver.md) with this address for more information.

0

0

+ +  + +Cause +----- + +Parameter 1 indicates the specific cause of the BUGCODE\_NDIS\_DRIVER\_LIVE\_DUMP bugcheck. + +Remarks +------- + +NDIS has detected and recovered from a serious problem in another network driver. Although the system was not halted, this problem may later cause connectivity problems or a fatal bugcheck. + +This bug code occurs only in Windows 8.1 and later versions of Windows. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x15f--connected-standby-watchdog-timeout-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x15f--connected-standby-watchdog-timeout-livedump.md new file mode 100644 index 0000000000..cc7518d1e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x15f--connected-standby-watchdog-timeout-livedump.md @@ -0,0 +1,93 @@ +--- +title: Bug Check 0x15F CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP +description: The CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP bug check has a value of 0x0000015F. This indicates that a connected standby watchdog timeout has occurred. +ms.assetid: 4C10AAC1-0B8F-4BBE-B470-55A8ED373687 +keywords: ["Bug Check 0x15F CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP", "CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CONNECTED_STANDBY_WATCHDOG_TIMEOUT_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x15F: CONNECTED\_STANDBY\_WATCHDOG\_TIMEOUT\_LIVEDUMP + + +The CONNECTED\_STANDBY\_WATCHDOG\_TIMEOUT\_LIVEDUMP bug check has a value of 0x0000015F. This indicates that a connected standby watchdog timeout has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CONNECTED\_STANDBY\_WATCHDOG\_TIMEOUT\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

CS watchdog subcode

+0x1 : DRIPS watchdog timeout. The system has been in the resiliency phase of connected standby with no activators active and no device constraints unsatisfied for too long without entering DRIPS (deepest runtime idle platform state). +

2 - A pointer to additional information (nt!POP_DRIPS_WATCHDOG_METRICS)

+

3 - Non-DRIPS duration in milliseconds

+

4 - Reserved

+0x2 : DRIPS watchdog device constraint timeout. The system has been in the resiliency phase of connected standby for too long without entering DRIPS (deepest runtime idle platform state) due to an unsatisfied device constraint with no activators active. +

2 - nt!TRIAGE_POP_FX_DEVICE Device

+

3 - Component index

+

4 - Reserved

+0x3 : DRIPS watchdog preveto timeout. The system has been in the resiliency phase of connected standby for too long without entering DRIPS (deepest runtime idle platform state) due to an active PEP pre-veto with no unsatisfied device constraint and with no activators active. +

2 - Veto code

+

3 - A pointer to the veto name string (PWSTR)

+

4 - A pointer to the PEP PPM callback

+0x4 : Deep Sleep Watchdog +

2 - Metrics

+

3 -NonDeepSleepDurationMs

+

4 - Reserved

+0x5 : Deep Sleep Power Setting Watchdog +

2 - Metrics

+

3 -NonDeepSleepDurationMs

+

4 - Reserved

2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +Cause +----- + +This machine is exhibiting behavior that reduces screen-off battery life. Typically this is caused by CPU activity, device activity, or devices being in an insufficient idle state. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x16--cid-handle-creation.md b/windows-driver-docs-pr/debugger/bug-check-0x16--cid-handle-creation.md new file mode 100644 index 0000000000..60d781b7f0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x16--cid-handle-creation.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x16 CID_HANDLE_CREATION +description: The CID_HANDLE_CREATION bug check has a value of 0x00000016.This bug check appears very infrequently. +ms.assetid: 99b4d1c7-8639-4e4c-905e-b9a351c101a1 +keywords: ["Bug Check 0x16 CID_HANDLE_CREATION", "CID_HANDLE_CREATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CID_HANDLE_CREATION +api_type: +- NA +--- + +# Bug Check 0x16: CID\_HANDLE\_CREATION + + +The CID\_HANDLE\_CREATION bug check has a value of 0x00000016. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x160--win32k-atomic-check-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x160--win32k-atomic-check-failure.md new file mode 100644 index 0000000000..972bed261f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x160--win32k-atomic-check-failure.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x160 WIN32K_ATOMIC_CHECK_FAILURE +description: The WIN32K_ATOMIC_CHECK_FAILURE bug check has a value of 0x00000160. This indicates that a Win32k function has violated an ATOMICCHECK. +ms.assetid: 81EEC1ED-367A-477D-B008-2295C7D7D1B4 +keywords: ["Bug Check 0x160 WIN32K_ATOMIC_CHECK_FAILURE", "WIN32K_ATOMIC_CHECK_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_ATOMIC_CHECK_FAILURE +api_type: +- NA +--- + +# Bug Check 0x160: WIN32K\_ATOMIC\_CHECK\_FAILURE + + +The WIN32K\_ATOMIC\_CHECK\_FAILURE bug check has a value of 0x00000160. This indicates that a Win32k function has violated an ATOMICCHECK. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_ATOMIC\_CHECK\_FAILURE Parameters + + +| Parameter | Description | +|-----------|-------------------------------------------------------------------------| +| 1 | Count of functions on the stack currently inside of an ATOMIC operation | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x161--live-system-dump.md b/windows-driver-docs-pr/debugger/bug-check-0x161--live-system-dump.md new file mode 100644 index 0000000000..c2e9751cda --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x161--live-system-dump.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x161 LIVE_SYSTEM_DUMP +description: The LIVE_SYSTEM_DUMP bug check has a value of 0x00000161. This indicates that the system administrator requested the collection of a live system memory dump. +ms.assetid: 0FD942A1-C92F-4386-850D-3C51D9E553D4 +keywords: ["Bug Check 0x161 LIVE_SYSTEM_DUMP", "LIVE_SYSTEM_DUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LIVE_SYSTEM_DUMP +api_type: +- NA +--- + +# Bug Check 0x161: LIVE\_SYSTEM\_DUMP + + +The LIVE\_SYSTEM\_DUMP bug check has a value of 0x00000161. This indicates that the system administrator requested the collection of a live system memory dump. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## LIVE\_SYSTEM\_DUMP Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x162--kernel-auto-boost-invalid-lock-release.md b/windows-driver-docs-pr/debugger/bug-check-0x162--kernel-auto-boost-invalid-lock-release.md new file mode 100644 index 0000000000..5cda2dac71 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x162--kernel-auto-boost-invalid-lock-release.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x162 KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE +description: The KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE bug check has a value of 0x00000162. This indicates that a lock tracked by AutoBoost was released by a thread that did not own the lock. +ms.assetid: 8430B461-892C-4517-B5E1-94DCDB413B21 +keywords: ["Bug Check 0x162 KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE", "KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_AUTO_BOOST_INVALID_LOCK_RELEASE +api_type: +- NA +--- + +# Bug Check 0x162: KERNEL\_AUTO\_BOOST\_INVALID\_LOCK\_RELEASE + + +The KERNEL\_AUTO\_BOOST\_INVALID\_LOCK\_RELEASE bug check has a value of 0x00000162. This indicates that a lock tracked by AutoBoost was released by a thread that did not own the lock. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_AUTO\_BOOST\_INVALID\_LOCK\_RELEASE Parameters + + +| Parameter | Description | +|-----------|------------------------------| +| 1 | The address of the thread | +| 2 | The lock address | +| 3 | The session ID of the thread | +| 4 | Reserved | + +  + +Cause +----- + +This is typically caused when some thread releases a lock on behalf of another thread (which is not legal with AutoBoost tracking enabled) or when some thread tries to release a lock it no longer owns. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x162--worker-thread-test-condition.md b/windows-driver-docs-pr/debugger/bug-check-0x162--worker-thread-test-condition.md new file mode 100644 index 0000000000..697ba52de5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x162--worker-thread-test-condition.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x163 WORKER_THREAD_TEST_CONDITION +description: The WORKER_THREAD_TEST_CONDITION bug check has a value of 0x00000163. This indicates that a test for kernel worker threads raised a failure. +ms.assetid: E0FF42E9-4C79-4C44-AD0C-64973884E9BE +keywords: ["Bug Check 0x163 WORKER_THREAD_TEST_CONDITION", "WORKER_THREAD_TEST_CONDITION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_TEST_CONDITION +api_type: +- NA +--- + +# Bug Check 0x163: WORKER\_THREAD\_TEST\_CONDITION + + +The WORKER\_THREAD\_TEST\_CONDITION bug check has a value of 0x00000163. This indicates that a test for kernel worker threads raised a failure. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_TEST\_CONDITION Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------------------------| +| 1 | Active test flags | +| 2 | Flag corresponding to the test that triggered the failure | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x164--win32k-critical-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x164--win32k-critical-failure.md new file mode 100644 index 0000000000..8170056237 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x164--win32k-critical-failure.md @@ -0,0 +1,110 @@ +--- +title: Bug Check 0x164 WIN32K_CRITICAL_FAILURE +description: The WIN32K_CRITICAL_FAILURE bug check has a value of 0x00000164. This indicates that Win32k has encountered a critical failure. +ms.assetid: 6274C852-53DA-4E01-B2A6-D7485501BE50 +keywords: ["Bug Check 0x164 WIN32K_CRITICAL_FAILURE", "WIN32K_CRITICAL_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_CRITICAL_FAILURE +api_type: +- NA +--- + +# Bug Check 0x164: WIN32K\_CRITICAL\_FAILURE + + +The WIN32K\_CRITICAL\_FAILURE bug check has a value of 0x00000164. This indicates that Win32k has encountered a critical failure. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_CRITICAL\_FAILURE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

1 - Type of the failure.

+0x1 : REGION_VALIDATION_FAILURE- Region is out of surface bounds. +

2 - Pointer to DC

+

3 - Pointer to SURFACE

+

4 - Pointer to REGION

+0x2 : OPERATOR_NEW_USED - Operator "new" is used to allocate memory. +

2 - Reserved

+

3 - Reserved

+

4 - Reserved

+

+0x3 : CRITICAL_APISET_EXTENSIONS_MISSING - Critical extension APISET API is missing. +

2 - wchar_t* to the name of the missing function

+

3 - Reserved

+

4 - Reserved

+0x4 : GDI_SPRITE_SURFACE_INVALID_DELETE - GDI sprite's shape is being deleted without deleting the sprite. +

2 - Handle to the SURFACE

+

3 - Reference count to the SURFACE

+

4 - PID of the SURFACE owner

+0x5 : POINTER_DEVICE_EXCLUSIVE_OPEN_FAILED - Failed to open Pointer device. +

+

2 - UNICODE_STRING of the device

+

3 - Reserved

+

4 - Reserved

+0x8 : PUBLIC_DC_INVALID_PRIVATE_MEMBER - A public DC has a pointer to an object owned by a specific process. +

2 - Pointer to DC

+

3 - Process id that owns the object

+

4 - Reserved

+0xA : TTFD_INVOKE_ILLEGAL_ID - Invalid function table index is being used in TTFD. +

2 - Reserved

+

3 - Reserved

+

4 - Reserved

+0xB : OTFD_INVOKE_ILLEGAL_ID - Invalid function table index is being used in ATMFD. +

2 - Reserved

+

3 - Reserved

+

4 - Reserved

+0xC : GFPE_INVOKE_ILLEGAL_ID - Invalid function table index is being used in a PALETTE. +

2 - Pointer to the PALETTE

+

3 - The invalid index

+

4 - Maximum valid index + 1

+0x10 : USER_SAS_REGISTRATION_FAILED - SAS key registration has failed. +

2 - vkey

+

3 - modifiers

+

4 - flags

2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x16c--invalid-rundown-protection-flags.md b/windows-driver-docs-pr/debugger/bug-check-0x16c--invalid-rundown-protection-flags.md new file mode 100644 index 0000000000..9130d93945 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x16c--invalid-rundown-protection-flags.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x16C INVALID_RUNDOWN_PROTECTION_FLAGS +description: The INVALID_RUNDOWN_PROTECTION_FLAGS bug check has a value of 0x0000016C. This indicates that the flags supplied to one of the rundown protection APIs were invalid. +ms.assetid: D14307A3-1D52-4B4E-85B2-2CD0B2442695 +keywords: ["Bug Check 0x16C INVALID_RUNDOWN_PROTECTION_FLAGS", "INVALID_RUNDOWN_PROTECTION_FLAGS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_RUNDOWN_PROTECTION_FLAGS +api_type: +- NA +--- + +# Bug Check 0x16C: INVALID\_RUNDOWN\_PROTECTION\_FLAGS + + +The INVALID\_RUNDOWN\_PROTECTION\_FLAGS bug check has a value of 0x0000016C. This indicates that the flags supplied to one of the rundown protection APIs were invalid. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_RUNDOWN\_PROTECTION\_FLAGS Parameters + + +| Parameter | Description | +|-----------|------------------------------------------| +| 1 | The invalid flags supplied by the caller | +| 2 | The address of the rundown ref | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x16d--invalid-slot-allocator-flags.md b/windows-driver-docs-pr/debugger/bug-check-0x16d--invalid-slot-allocator-flags.md new file mode 100644 index 0000000000..598de4c084 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x16d--invalid-slot-allocator-flags.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x16D INVALID_SLOT_ALLOCATOR_FLAGS +description: The INVALID_SLOT_ALLOCATOR_FLAGS bug check has a value of 0x0000016D. This indicates that the flags supplied to one of the slot allocator APIs were invalid. +ms.assetid: 7A26E679-405D-4ABD-9C70-AC3B63E86C4C +keywords: ["Bug Check 0x16D INVALID_SLOT_ALLOCATOR_FLAGS", "INVALID_SLOT_ALLOCATOR_FLAGS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_SLOT_ALLOCATOR_FLAGS +api_type: +- NA +--- + +# Bug Check 0x16D: INVALID\_SLOT\_ALLOCATOR\_FLAGS + + +The INVALID\_SLOT\_ALLOCATOR\_FLAGS bug check has a value of 0x0000016D. This indicates that the flags supplied to one of the slot allocator APIs were invalid. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_SLOT\_ALLOCATOR\_FLAGS Parameters + + +| Parameter | Description | +|-----------|------------------------------------------| +| 1 | The invalid flags supplied by the caller | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x16e--eresource-invalid-release.md b/windows-driver-docs-pr/debugger/bug-check-0x16e--eresource-invalid-release.md new file mode 100644 index 0000000000..893fa9ff9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x16e--eresource-invalid-release.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x16E ERESOURCE_INVALID_RELEASE +description: The ERESOURCE_INVALID_RELEASE bug check has a value of 0x0000016E. This indicates that the target thread pointer supplied to ExReleaseResourceForThreadLite was invalid. +ms.assetid: F180D28D-70B7-4E78-9E04-C5DC19A41EB9 +keywords: ["Bug Check 0x16E ERESOURCE_INVALID_RELEASE", "ERESOURCE_INVALID_RELEASE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ERESOURCE_INVALID_RELEASE +api_type: +- NA +--- + +# Bug Check 0x16E: ERESOURCE\_INVALID\_RELEASE + + +The ERESOURCE\_INVALID\_RELEASE bug check has a value of 0x0000016E. This indicates that the target thread pointer supplied to ExReleaseResourceForThreadLite was invalid. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ERESOURCE\_INVALID\_RELEASE Parameters + + +| Parameter | Description | +|-----------|------------------------------------------------| +| 1 | The resource being released | +| 2 | The current thread | +| 3 | The incorrect target thread that was passed in | +| 4 | Reserved | + +  + +Cause +----- + +This bugcheck will hit if a call to ExSetOwnerPointerEx was skipped by the API client (if a cross-thread release was intended) or if the caller accidentally passed in a value other that supplied by ExGetCurrentResourceThread. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x17--cid-handle-deletion.md b/windows-driver-docs-pr/debugger/bug-check-0x17--cid-handle-deletion.md new file mode 100644 index 0000000000..5c7008e2e9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x17--cid-handle-deletion.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x17 CID_HANDLE_DELETION +description: The CID_HANDLE_DELETION bug check has a value of 0x00000017.This bug check appears very infrequently. +ms.assetid: 84012928-655c-4b99-b940-dad4f0caf249 +keywords: ["Bug Check 0x17 CID_HANDLE_DELETION", "CID_HANDLE_DELETION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CID_HANDLE_DELETION +api_type: +- NA +--- + +# Bug Check 0x17: CID\_HANDLE\_DELETION + + +The CID\_HANDLE\_DELETION bug check has a value of 0x00000017. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x175--elam-driver-detected-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x175--elam-driver-detected-fatal-error.md new file mode 100644 index 0000000000..e01e24197e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x175--elam-driver-detected-fatal-error.md @@ -0,0 +1,74 @@ +--- +title: Bug Check 0x178 ELAM_DRIVER_DETECTED_FATAL_ERROR +description: The ELAM_DRIVER_DETECTED_FATAL_ERROR bug check has a value of 0x00000178. This indicates that ELAM driver detected a fatal error. +ms.assetid: 4D37FE16-0189-426C-8015-9F14DA3C52F6 +keywords: ["Bug Check 0x178 ELAM_DRIVER_DETECTED_FATAL_ERROR", "ELAM_DRIVER_DETECTED_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ELAM_DRIVER_DETECTED_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x178: ELAM\_DRIVER\_DETECTED\_FATAL\_ERROR + + +The ELAM\_DRIVER\_DETECTED\_FATAL\_ERROR bug check has a value of 0x00000178. This indicates that ELAM driver detected a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ELAM\_DRIVER\_DETECTED\_FATAL\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1Type of the failure. +

0x0 : TPM attestation could not be revoked

+2 - Pointer to the BDCB_IMAGE_INFORMATION structure for the driver being inspected +3 - TBS_RESULT failure code +

0x10000 : ELAM-vendor defined failure

+2 - (Optional) ELAM vendor supplied value +3 - (Optional) ELAM vendor supplied value
2See parameter 1
3See parameter 1
4(Optional) ELAM vendor supplied general purpose data block
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x175--previous-fatal-abnormal-reset-error.md b/windows-driver-docs-pr/debugger/bug-check-0x175--previous-fatal-abnormal-reset-error.md new file mode 100644 index 0000000000..4b94bb7522 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x175--previous-fatal-abnormal-reset-error.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x175 PREVIOUS_FATAL_ABNORMAL_RESET_ERROR +description: The PREVIOUS_FATAL_ABNORMAL_RESET_ERROR bug check has a value of 0x00000175. +ms.assetid: C1F74858-DAF4-466C-9696-6FE5390574C3 +keywords: ["Bug Check 0x175 PREVIOUS_FATAL_ABNORMAL_RESET_ERROR", "PREVIOUS_FATAL_ABNORMAL_RESET_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PREVIOUS_FATAL_ABNORMAL_RESET_ERROR +api_type: +- NA +--- + +# Bug Check 0x175: PREVIOUS\_FATAL\_ABNORMAL\_RESET\_ERROR + + +The PREVIOUS\_FATAL\_ABNORMAL\_RESET\_ERROR bug check has a value of 0x00000175. This indicates that an unrecoverable system error occurred or the system has abnormally reset on Windows phone devices. The system generated a live dump to collect device crash data from the previous error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PREVIOUS\_FATAL\_ABNORMAL\_RESET\_ERROR Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +Cause +----- + +The system on Windows Phone devices encountered an unexpected error and restarted. Issues that may cause this error include: hardware watchdog timer in application or auxiliary processors indicating a system hang, user-initiated key sequence because of a hang, etc. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x18--reference-by-pointer.md b/windows-driver-docs-pr/debugger/bug-check-0x18--reference-by-pointer.md new file mode 100644 index 0000000000..ccc479660c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x18--reference-by-pointer.md @@ -0,0 +1,100 @@ +--- +title: Bug Check 0x18 REFERENCE_BY_POINTER +description: The REFERENCE_BY_POINTER bug check has a value of 0x00000018. This indicates that the reference count of an object is illegal for the current state of the object. +ms.assetid: 911fa821-5e59-4f20-a31b-148064e6c113 +keywords: ["Bug Check 0x18 REFERENCE_BY_POINTER", "REFERENCE_BY_POINTER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REFERENCE_BY_POINTER +api_type: +- NA +--- + +# Bug Check 0x18: REFERENCE\_BY\_POINTER + + +The REFERENCE\_BY\_POINTER bug check has a value of 0x00000018. This indicates that the reference count of an object is illegal for the current state of the object. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## REFERENCE\_BY\_POINTER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Object type of the object whose reference count is being lowered.

2

Object whose reference count is being lowered.

3

Reserved

4

Reserved

+ +  + +Cause +----- + +The reference count of an object is illegal for the current state of the object. Each time a driver uses a pointer to an object, the driver calls a kernel routine to increase the reference count of the object by one. When the driver is done with the pointer, the driver calls another kernel routine to decrease the reference count by one. + +Drivers must match calls to the routines that increase (*reference*) and decrease (*dereference*) the reference count. This bug check is caused by an inconsistency in the object's reference count. Typically, the inconsistency is caused by a driver that decreases the reference count of an object too many times, making extra calls that dereference the object. This bug check can occur because an object's reference count goes to zero while there are still open handles to the object. It might also occur when the object's reference count drops below zero, whether or not there are open handles to the object. + +Resolution +---------- + +Make sure that the driver matches calls to the routines that increase and decrease the reference count of the object. Make sure that your driver does not make extra calls to routines that dereference the object (see Parameter 2). + +You can use a debugger to help analyze this problem. For more information, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md). The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +To find the handle and pointer count on the object, use the **!object** debugger command. + +kd> !object *address* + +Where *address* is the address of the object given in Parameter 2. + +You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x187--video-dwminit-timeout-fallback-bdd.md b/windows-driver-docs-pr/debugger/bug-check-0x187--video-dwminit-timeout-fallback-bdd.md new file mode 100644 index 0000000000..381e87b18a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x187--video-dwminit-timeout-fallback-bdd.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x187 VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD +description: The VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD bug check has a value of 0x00000187. This indicates that video fell back to BDD rather than using the IHV driver. This always generates a live dump. +ms.assetid: CF4AB5DB-2779-4E6E-BF27-AE320403A982 +keywords: ["Bug Check 0x187 VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD", "VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_DWMINIT_TIMEOUT_FALLBACK_BDD +api_type: +- NA +--- + +# Bug Check 0x187: VIDEO\_DWMINIT\_TIMEOUT\_FALLBACK\_BDD + + +The VIDEO\_DWMINIT\_TIMEOUT\_FALLBACK\_BDD bug check has a value of 0x00000187. This indicates that video fell back to BDD rather than using the IHV driver. This always generates a live dump. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_DWMINIT\_TIMEOUT\_FALLBACK\_BDD Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1Reason Code. +

0x1 : DWM failed to initialize after retries, stopping display adapters and falling back to BDD

2Reserved
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x188--cluster-csvfs-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x188--cluster-csvfs-livedump.md new file mode 100644 index 0000000000..c2505aa951 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x188--cluster-csvfs-livedump.md @@ -0,0 +1,81 @@ +--- +title: Bug Check 0x188 CLUSTER_CSVFS_LIVEDUMP +description: The CLUSTER_CSVFS_LIVEDUMP bug check has a value of 0x00000188. This indicates that CSVFS initiated this livedump to help debug an inconsistent state. +ms.assetid: 220B0CDB-6E10-4262-A07C-042E8BA21D7F +keywords: ["Bug Check 0x188 CLUSTER_CSVFS_LIVEDUMP", "CLUSTER_CSVFS_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CLUSTER_CSVFS_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x188: CLUSTER\_CSVFS\_LIVEDUMP + + +The CLUSTER\_CSVFS\_LIVEDUMP bug check has a value of 0x00000188. This indicates that CSVFS initiated this livedump to help debug an inconsistent state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CLUSTER\_CSVFS\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Reason Code

+0x1 : Cache purge on oplock downgrade to none has failed +

2- address of CSVFS!_SCB

+0x2 : Cache purge on oplock upgrade from none has failed +

2- address of CSVFS!_SCB

+0x3 : Cache purge on set purge failure mode +

2- address of CSVFS!_SCB

+0x4 : Cache flush on oplock downgrade to none failed +

2- address of CSVFS!_SCB

2See parameter 1
3Reserved
4Reserved
+ +  + +Cause +----- + +First parameter contains the reason code When CSVFS detects that current state might cause data corruption or other sort of inconsistency it would generate live dump with this status code. Parameter1 has code pointing to what scenario this live dump is created for. Other parameters should be interpreted in context of the reason code. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x189--bad-object-header.md b/windows-driver-docs-pr/debugger/bug-check-0x189--bad-object-header.md new file mode 100644 index 0000000000..49006efe0b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x189--bad-object-header.md @@ -0,0 +1,70 @@ +--- +title: Bug Check 0x189 BAD_OBJECT_HEADER +description: The BAD_OBJECT_HEADER bug check has a value of 0x00000189. This indicates that The OBJECT_HEADER has been corrupted. +ms.assetid: 1B4F586A-2DFB-421A-863B-CC706FB4795B +keywords: ["Bug Check 0x189 BAD_OBJECT_HEADER", "BAD_OBJECT_HEADER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BAD_OBJECT_HEADER +api_type: +- NA +--- + +# Bug Check 0x189: BAD\_OBJECT\_HEADER + + +The BAD\_OBJECT\_HEADER bug check has a value of 0x00000189. This indicates that The OBJECT\_HEADER has been corrupted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BAD\_OBJECT\_HEADER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1Pointer to bad OBJECT_HEADER
2Pointer to the resulting OBJECT_TYPE based on the TypeIndex in the OBJECT_HEADER
3

Type of corruption.

+0x0 : The type index is corrupt +0x1 : The object security descriptor is invalid
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x18b--secure-kernel-error.md b/windows-driver-docs-pr/debugger/bug-check-0x18b--secure-kernel-error.md new file mode 100644 index 0000000000..fea39d8b6e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x18b--secure-kernel-error.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x18B SECURE_KERNEL_ERROR +description: The SECURE_KERNEL_ERROR bug check has a value of 0x0000018B. This indicates that the secure kernel has encountered a fatal error. +ms.assetid: 333355E3-6966-4BEB-A649-DA22B973EE84 +keywords: ["Bug Check 0x18B SECURE_KERNEL_ERROR", "SECURE_KERNEL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SECURE_KERNEL_ERROR +api_type: +- NA +--- + +# Bug Check 0x18B: SECURE\_KERNEL\_ERROR + + +The SECURE\_KERNEL\_ERROR bug check has a value of 0x0000018B. This indicates that the secure kernel has encountered a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SECURE\_KERNEL\_ERROR Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x19--bad-pool-header.md b/windows-driver-docs-pr/debugger/bug-check-0x19--bad-pool-header.md new file mode 100644 index 0000000000..7db5630f40 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x19--bad-pool-header.md @@ -0,0 +1,172 @@ +--- +title: (Developer Content) Bug Check 0x19 BAD_POOL_HEADER +description: The BAD_POOL_HEADER bug check has a value of 0x00000019. This indicates that a pool header is corrupt. +ms.assetid: a3e84703-d778-426b-80e6-e143f5d8f869 +keywords: ["(Developer Content) Bug Check 0x19 BAD_POOL_HEADER", "BAD_POOL_HEADER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BAD_POOL_HEADER +api_type: +- NA +--- + +# (Developer Content) Bug Check 0x19: BAD\_POOL\_HEADER + + +The BAD\_POOL\_HEADER bug check has a value of 0x00000019. This indicates that a pool header is corrupt. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BAD\_POOL\_HEADER Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x2

The pool entry being checked

The size of the pool block

0

The special pool pattern check failed.

+

(The owner has likely corrupted the pool block.)

0x3

The pool entry being checked

The read-back flink freelist value

The read-back blink freelist value

The pool freelist is corrupt.

+

(In a healthy list, the values of Parameters 2, 3, and 4 should be identical.)

0x5

One of the pool entries

Reserved

The other pool entry

A pair of adjacent pool entries have headers that contradict each other. At least one of them is corrupt.

0x6

One incorrectly-calculated entry

Reserved

The bad entry that caused the miscalculation

The pool block header's previous size is too large.

0x7

0

Reserved

The bad pool entry

The pool block header size is corrupt.

0x8

0

Reserved

The bad pool entry

The pool block header size is zero.

0x9

One incorrectly-calculated entry

Reserved

The bad entry that caused the miscalculation

The pool block header size is corrupted (it is too large).

0xA

The pool entry that should have been found

Reserved

The virtual address of the page that should have contained the pool entry

The pool block header size is corrupt.

0xD, 0xE, 0xF, 0x23, 0x24, 0x25

Reserved

Reserved

Reserved

The pool header of a freed block has been modified after it was freed. This is not typically the fault of the prior owner of the freed block; instead it is usually (but not always) due to the block preceding the freed block being overrun.

0x20

The pool entry that should have been found

The next pool entry

Reserved

The pool block header size is corrupt.

0X21

The pool pointer being freed

The number of bytes allocated for the pool block

The corrupted value found following the pool block

The data following the pool block being freed is corrupt. Typically this means the consumer (call stack) has overrun the block.

0X22

The address being freed

Reserved

Reserved

An address being freed does not have a tracking entry. This is usually because the call stack is trying to free a pointer that either has already been freed or was never allocated to begin with.

+ +  + +Cause +----- + +The pool is already corrupted at the time of the current request. + +This may or may not be due to the caller. + +Resolution +---------- + +The internal pool links must be walked using the kernel debugger to figure out a possible cause of the problem. + +Then you can use special pool for the suspect pool tags, or use Driver Verifier "Special Pool" option on the suspect driver. The [**!analyze**](-analyze.md) extension may be of help in pinpointing the suspect driver, but this is frequently not the case with pool corrupters. + +Use the steps described in [**Blue Screen Data**](blue-screen-data.md) to gather the Stop Code Parameters. Use the stop code parameters to determine the specific type of code behavior you are working to track down. + +**Driver Verifier** + +Driver Verifier is a tool that runs in real time to examine the behavior of drivers. If it see errors in the execution of driver code, it proactively creates an exception to allow that part of the driver code to be further scrutinized. The driver verifier manager is built into Windows and is available on all Windows PCs. To start the driver verifier manager, type *Verifer* at a command prompt. You can configure which drivers you would like to verify. The code that verifies drivers adds overhead as it runs, so try and verify the smallest number of drivers as possible. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +**Windows Memory Diagnostics** + +If this Bug Check appears inconsistently, it could be related to faulty physical memory. + +Run the Windows Memory Diagnostics tool, to test the memory. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x190--win32k-critical-failure-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x190--win32k-critical-failure-livedump.md new file mode 100644 index 0000000000..6ec6bbe097 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x190--win32k-critical-failure-livedump.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0x190 WIN32K_CRITICAL_FAILURE_LIVEDUMP +description: The WIN32K_CRITICAL_FAILURE_LIVEDUMP bug check has a value of 0x00000190. This indicates that Win32k has encountered a critical failure. A live dump is captured to collect the debug information. +ms.assetid: 39C0145D-08FE-4BBC-A729-9E70198CF87F +keywords: ["Bug Check 0x190 WIN32K_CRITICAL_FAILURE_LIVEDUMP", "WIN32K_CRITICAL_FAILURE_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_CRITICAL_FAILURE_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x190: WIN32K\_CRITICAL\_FAILURE\_LIVEDUMP + + +The WIN32K\_CRITICAL\_FAILURE\_LIVEDUMP bug check has a value of 0x00000190. This indicates that Win32k has encountered a critical failure. A live dump is captured to collect the debug information. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_CRITICAL\_FAILURE\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Type of the failure

+

0x1 : REGION_VALIDATION_FAILURE - Region is out of surface bounds.

+2- Pointer to DC +3- Pointer to SURFACE +4- Pointer to REGION +

0x2 : OPERATOR_NEW_USED - Operator "new" is used to allocate memory.

+2 - Reserved +3 - Reserved +4 - Reserved
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x191--pf-detected-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0x191--pf-detected-corruption.md new file mode 100644 index 0000000000..6ba5f3e160 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x191--pf-detected-corruption.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x191 PF_DETECTED_CORRUPTION +description: The PF_DETECTED_CORRUPTION bug check has a value of 0x00000191. +ms.assetid: 570D22A7-E3EB-4A53-9188-640907FF39A5 +keywords: ["Bug Check 0x191 PF_DETECTED_CORRUPTION", "PF_DETECTED_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PF_DETECTED_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0x191: PF\_DETECTED\_CORRUPTION + + +The PF\_DETECTED\_CORRUPTION bug check has a value of 0x00000191. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PF\_DETECTED\_CORRUPTION Parameters + + +| Parameter | Description | +|-----------|-------------| +| 1 | Reserved | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x192--kernel-auto-boost-lock-acquisition-with-raised-irql.md b/windows-driver-docs-pr/debugger/bug-check-0x192--kernel-auto-boost-lock-acquisition-with-raised-irql.md new file mode 100644 index 0000000000..8c1bc0973a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x192--kernel-auto-boost-lock-acquisition-with-raised-irql.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x192 KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL +description: The KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL bug check indicates that a lock tracked by AutoBoost was acquired while executing at DISPATCH_LEVEL or above. +ms.assetid: D88EF2CC-26DC-44D8-80CB-18D058C6A413 +keywords: ["Bug Check 0x192 KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL", "KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_AUTO_BOOST_LOCK_ACQUISITION_WITH_RAISED_IRQL +api_type: +- NA +--- + +# Bug Check 0x192: KERNEL\_AUTO\_BOOST\_LOCK\_ACQUISITION\_WITH\_RAISED\_IRQL + + +The KERNEL\_AUTO\_BOOST\_LOCK\_ACQUISITION\_WITH\_RAISED\_IRQL bug check has a value of 0x00000192. This indicates that a lock tracked by AutoBoost was acquired while executing at DISPATCH\_LEVEL or above. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_AUTO\_BOOST\_LOCK\_ACQUISITION\_WITH\_RAISED\_IRQL Parameters + + +| Parameter | Description | +|-----------|-----------------------------------------| +| 1 | The address of the thread | +| 2 | The lock address | +| 3 | The IRQL at which the lock was acquired | +| 4 | Reserved | + +  + +Cause +----- + +The caller cannot be blocking on a lock above APC\_LEVEL because the lock may be held exclusively by the interrupted thread, which would cause a deadlock. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x192--video-dxgkrnl-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x192--video-dxgkrnl-livedump.md new file mode 100644 index 0000000000..6b2e8f0284 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x192--video-dxgkrnl-livedump.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x193 VIDEO_DXGKRNL_LIVEDUMP +description: The VIDEO_DXGKRNL_LIVEDUMP bug check has a value of 0x00000193. This indicates a livedump triggered by dxgkrnl occurred. +ms.assetid: 73B84617-7DBB-4161-BAB3-8BCDDBE9BE93 +keywords: ["Bug Check 0x193 VIDEO_DXGKRNL_LIVEDUMP", "VIDEO_DXGKRNL_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_DXGKRNL_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x193: VIDEO\_DXGKRNL\_LIVEDUMP + + +The VIDEO\_DXGKRNL\_LIVEDUMP bug check has a value of 0x00000193. This indicates a livedump triggered by dxgkrnl occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_DXGKRNL\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Reason Code

+0x100 Internal
2Reserved
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x195--smb-server-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x195--smb-server-livedump.md new file mode 100644 index 0000000000..12f605ee53 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x195--smb-server-livedump.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x195 SMB_SERVER_LIVEDUMP +description: The SMB_SERVER_LIVEDUMP bug check has a value of 0x00000195. This indicates the SMB server detected a problem and has captured a kernel dump to collect debug information. +ms.assetid: 302BA6E0-DC7C-4AE7-BD4D-C6F6A74D82D9 +keywords: ["Bug Check 0x195 SMB_SERVER_LIVEDUMP", "SMB_SERVER_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SMB_SERVER_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x195: SMB\_SERVER\_LIVEDUMP + + +The SMB\_SERVER\_LIVEDUMP bug check has a value of 0x00000195. This indicates the SMB server detected a problem and has captured a kernel dump to collect debug information. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SMB\_SERVER\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

0x1 : An I/O failed to complete in a reasonable amount of time.

+2 - Pointer to the I/O's SRV2_WORK_ITEM
2See parameter 1
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x196--loader-rollback-detected.md b/windows-driver-docs-pr/debugger/bug-check-0x196--loader-rollback-detected.md new file mode 100644 index 0000000000..5f5dfb5d6c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x196--loader-rollback-detected.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x196 LOADER_ROLLBACK_DETECTED +description: The LOADER_ROLLBACK_DETECTED bug check has a value of 0x00000196. This indicates that the version of the OS loader does not match the operating system. +ms.assetid: 122AAC03-999A-456D-AFD8-749B19267D41 +keywords: ["Bug Check 0x196 LOADER_ROLLBACK_DETECTED", "LOADER_ROLLBACK_DETECTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LOADER_ROLLBACK_DETECTED +api_type: +- NA +--- + +# Bug Check 0x196: LOADER\_ROLLBACK\_DETECTED + + +The LOADER\_ROLLBACK\_DETECTED bug check has a value of 0x00000196. This indicates that the version of the OS loader does not match the operating system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## LOADER\_ROLLBACK\_DETECTED Parameters + + +| Parameter | Description | +|-----------|-------------------------| +| 1 | Loader security version | +| 2 | OS security version | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x197--win32k-security-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x197--win32k-security-failure.md new file mode 100644 index 0000000000..dab316d215 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x197--win32k-security-failure.md @@ -0,0 +1,72 @@ +--- +title: Bug Check 0x197 WIN32K_SECURITY_FAILURE +description: The WIN32K_SECURITY_FAILURE bug check has a value of 0x00000197. This indicates a security failure was detected in win32k. +ms.assetid: FBF81B3B-6F72-4624-84E8-FA9ED19F8198 +keywords: ["Bug Check 0x197 WIN32K_SECURITY_FAILURE", "WIN32K_SECURITY_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_SECURITY_FAILURE +api_type: +- NA +--- + +# Bug Check 0x197: WIN32K\_SECURITY\_FAILURE + + +The WIN32K\_SECURITY\_FAILURE bug check has a value of 0x00000197. This indicates a security failure was detected in win32k. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_SECURITY\_FAILURE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Failure type

+

0x1 : An objects handle entry didn't point back to the object.

+2 - Pointer to the object type +3 - Pointer to the object handle entry +4 - Expected object
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x198--ufx-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x198--ufx-livedump.md new file mode 100644 index 0000000000..add8704ff4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x198--ufx-livedump.md @@ -0,0 +1,72 @@ +--- +title: Bug Check 0x198 UFX_LIVEDUMP +description: The UFX_LIVEDUMP bug check has a value of 0x00000198. This indicates that a UFX live dump occurred. +ms.assetid: 319F8BA5-8522-43E6-B06F-6BC021FF8411 +keywords: ["Bug Check 0x198 UFX_LIVEDUMP", "UFX_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UFX_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x198: UFX\_LIVEDUMP + + +The UFX\_LIVEDUMP bug check has a value of 0x00000198. This indicates that a UFX live dump occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UFX\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Failure type

+

0x1 : A class driver failed to activate the bus.

+2 - Mask of enumerated child PDOs +3 - Mask of activated child PDOs +4 - Reserved
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x199--kernel-storage-slot-in-use.md b/windows-driver-docs-pr/debugger/bug-check-0x199--kernel-storage-slot-in-use.md new file mode 100644 index 0000000000..4a66b66482 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x199--kernel-storage-slot-in-use.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x199 KERNEL_STORAGE_SLOT_IN_USE +description: The KERNEL_STORAGE_SLOT_IN_USE bug check has a value of 0x00000199. This indicates that the storage slot cannot be freed because there is an object using it. +ms.assetid: 5C561976-DD3C-4593-AAF0-F46618242D28 +keywords: ["Bug Check 0x199 KERNEL_STORAGE_SLOT_IN_USE", "KERNEL_STORAGE_SLOT_IN_USE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_STORAGE_SLOT_IN_USE +api_type: +- NA +--- + +# Bug Check 0x199: KERNEL\_STORAGE\_SLOT\_IN\_USE + + +The KERNEL\_STORAGE\_SLOT\_IN\_USE bug check has a value of 0x00000199. This indicates that the storage slot cannot be freed because there is an object using it. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_STORAGE\_SLOT\_IN\_USE Parameters + + +| Parameter | Description | +|-----------|----------------------------------| +| 1 | The address of the storage array | +| 2 | Reserved | +| 3 | Reserved | +| 4 | Reserved | + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x19a--worker-thread-returned-while-attached-to-silo.md b/windows-driver-docs-pr/debugger/bug-check-0x19a--worker-thread-returned-while-attached-to-silo.md new file mode 100644 index 0000000000..2e31d17d8c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x19a--worker-thread-returned-while-attached-to-silo.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x19A WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO +description: The WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO bug check has a value of 0x0000019A. This indicates that a worker thread attached to a silo and did not detach before returning. +ms.assetid: D947FF20-4C86-4879-A5CA-934A20BE61C9 +keywords: ["Bug Check 0x19A WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO", "WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_RETURNED_WHILE_ATTACHED_TO_SILO +api_type: +- NA +--- + +# Bug Check 0x19A: WORKER\_THREAD\_RETURNED\_WHILE\_ATTACHED\_TO\_SILO + + +The WORKER\_THREAD\_RETURNED\_WHILE\_ATTACHED\_TO\_SILO bug check has a value of 0x0000019A. This indicates that a worker thread attached to a silo and did not detach before returning. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_RETURNED\_WHILE\_ATTACHED\_TO\_SILO Parameters + + +| Parameter | Description | +|-----------|---------------------------| +| 1 | Address of worker routine | +| 2 | Workitem parameter | +| 3 | Workitem address | +| 4 | Reserved | + +  + +Cause +----- + +To investigate use the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md)command on parameter 1 to help identify the mis-behaving driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x19b--ttm-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x19b--ttm-fatal-error.md new file mode 100644 index 0000000000..9140cb4c53 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x19b--ttm-fatal-error.md @@ -0,0 +1,72 @@ +--- +title: Bug Check 0x19B TTM_FATAL_ERROR +description: The TTM_FATAL_ERROR bug check has a value of 0x0000019B. This indicates that the terminal topology manager experienced a fatal error. +ms.assetid: 993A3A57-A303-4FEB-98F4-68802F4151D4 +keywords: ["Bug Check 0x19B TTM_FATAL_ERROR", "TTM_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TTM_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x19B: TTM\_FATAL\_ERROR + + +The TTM\_FATAL\_ERROR bug check has a value of 0x0000019B. This indicates that the terminal topology manager experienced a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TTM\_FATAL\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Failure type

+

0x1 : An terminal object could not be generated.

+2 - The NT status code of the failure +3 - Reserved +4 - Reserved
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x19c--win32k-power-watchdog-timeout.md b/windows-driver-docs-pr/debugger/bug-check-0x19c--win32k-power-watchdog-timeout.md new file mode 100644 index 0000000000..6977e2413f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x19c--win32k-power-watchdog-timeout.md @@ -0,0 +1,93 @@ +--- +title: Bug Check 0x19C WIN32K_POWER_WATCHDOG_TIMEOUT +description: The WIN32K_POWER_WATCHDOG_TIMEOUT bug check has a value of 0x0000019C. This indicates that Win32k did not turn the monitor on in a timely manner. +ms.assetid: 55907359-C282-43F0-92FE-5DC248BF9D02 +keywords: ["Bug Check 0x19C WIN32K_POWER_WATCHDOG_TIMEOUT", "WIN32K_POWER_WATCHDOG_TIMEOUT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WIN32K_POWER_WATCHDOG_TIMEOUT +api_type: +- NA +--- + +# Bug Check 0x19C: WIN32K\_POWER\_WATCHDOG\_TIMEOUT + + +The WIN32K\_POWER\_WATCHDOG\_TIMEOUT bug check has a value of 0x0000019C. This indicates that Win32k did not turn the monitor on in a timely manner. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WIN32K\_POWER\_WATCHDOG\_TIMEOUT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Failure type (win32kbase!POWER_WATCHDOG_TYPE)

+
+``` + 0x10 : The power request queue is not making progress + 2 - Pointer to the thread processing power requests, if any + 3 - Pointer to the win32k user lock + 4 - Pointer to the power request (win32kbase!PPOWERREQUEST) being + processed, if any + 0x20 : Calling PO to set power state + 2 - Pointer to the power request worker thread + 3 - Reserved + 4 - Reserved + 0x30 : Calling GDI to power on + 2 - Pointer to the power request worker thread + 3 - Reserved + 4 - Reserved + 0x40 : Calling DWM to render + 2 - Pointer to the power request worker thread + 3 - Reserved + 4 - Reserved + 0x50 : Calling monitor driver to power on + 2 - Pointer to the power request worker thread + 3 - Reserved + 4 - Reserved +``` +
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x19d--cluster-svhdx-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x19d--cluster-svhdx-livedump.md new file mode 100644 index 0000000000..4b26dbff7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x19d--cluster-svhdx-livedump.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x19D CLUSTER_SVHDX_LIVEDUMP +description: The CLUSTER_SVHDX_LIVEDUMP bug check has a value of 0x0000019D. This indicates that SVHDX initiated this livedump to help debug an inconsistent state. +ms.assetid: E261617D-E84A-4644-8854-53A189395637 +keywords: ["Bug Check 0x19D CLUSTER_SVHDX_LIVEDUMP", "CLUSTER_SVHDX_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CLUSTER_SVHDX_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x19D: CLUSTER\_SVHDX\_LIVEDUMP + + +The CLUSTER\_SVHDX\_LIVEDUMP bug check has a value of 0x0000019D. This indicates that SVHDX initiated this livedump to help debug an inconsistent state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CLUSTER\_SVHDX\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Reason code

+

0x1 : Mounting a Shared Virtual disk has failed

+2 - Address of Svhdxflt!_SVHDX_VIRTUALDISK_CONTEXT +3 - Address of nt!_FILE_OBJECT +4 - NTSTATUS
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +Cause +----- + +When SVHDX detects that current state might cause some sort of inconsistency it will generate live dump with this status code. Parameter1 has code pointing to what scenario this live dump is created for. Other parameters should be interpreted in context of the reason code. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1a--memory-management.md b/windows-driver-docs-pr/debugger/bug-check-0x1a--memory-management.md new file mode 100644 index 0000000000..79eac9bd1c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1a--memory-management.md @@ -0,0 +1,172 @@ +--- +title: Bug Check 0x1A MEMORY_MANAGEMENT +description: The MEMORY_MANAGEMENT bug check has a value of 0x0000001A. This indicates that a severe memory management error occurred. +ms.assetid: 7d3ff54e-e61a-43fa-a378-fb8d32565586 +keywords: ["Bug Check 0x1A MEMORY_MANAGEMENT", "MEMORY_MANAGEMENT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MEMORY_MANAGEMENT +api_type: +- NA +--- + +# Bug Check 0x1A: MEMORY\_MANAGEMENT + + +The MEMORY\_MANAGEMENT bug check has a value of 0x0000001A. This indicates that a severe memory management error occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MEMORY\_MANAGEMENT Parameters + + +Parameter 1 is the only parameter of interest; this identifies the exact violation. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Cause of Error

0x1

The fork clone block reference count is corrupt. (This only occurs on checked builds of Windows.)

0x31

The image relocation fix-up table or code stream has been corrupted. This is probably a hardware error.

0x403

The page table and PFNs are out of sync . This is probably a hardware error, especially if parameters 3 & 4 differ by only a single bit.

0x411

A page table entry (PTE) has been corrupted. Parameter 2 is the address of the PTE.

0x777

The caller is unlocking a system cache address that is not currently locked. (This address was either never mapped or is being unlocked twice.)

0x778

The system is using the very last system cache view address, instead of preserving it.

0x780

+

0x781

The PTEs mapping the argument system cache view have been corrupted.

0x1000

A caller of MmGetSystemAddressForMdl* tried to map a fully-cached physical page as non-cached. This action would cause a conflicting hardware translation buffer entry, and so it was refused by the operating system. Since the caller specified "bug check on failure" in the requesting MDL, the system had no choice but to issue a bug check in this instance.

0x1010

The caller is unlocking a pageable section that is not currently locked. (This section was either never locked or is being unlocked twice.)

0x1233

A driver tried to map a physical memory page that was not locked. This is illegal because the contents or attributes of the page can change at any time. This is a bug in the code that made the mapping call. Parameter 2 is the page frame number of the physical page that the driver attempted to map.

0x1234

The caller is trying lock a nonexistent pageable section.

0x1235

The caller is trying to protect an MDL with an invalid mapping.

0x3451

The PTEs of a kernel thread stack that has been swapped out are corrupted.

0x5003

The working set free list is corrupt. This is probably a hardware error.

0x5100

The allocation bitmap is corrupt. The memory manager is about to overwrite a virtual address that was already in use.

0x8884

(Windows 7only). Two pages on the standby list that were supposed to have identical page priority values do not, in fact, have identical page priority values. The differing values are captured in parameter 4.

0x8888

+

0x8889

Internal memory management structures are corrupted.

0x888A

Internal memory management structures (likely the PTE or PFN) are corrupted.

0x41283

The working set index encoded in the PTE is corrupted.

0x41284

A PTE or the working set list is corrupted.

0x41286

The caller is trying to free an invalid pool address.

0x41785

The working set list is corrupted.

0x41287

An illegal page fault occurred while holding working set synchronization. Parameter 2 contains the referenced virtual address.

0x41790

A page table page has been corrupted. On a 64 bit version of Windows, parameter 2 contains the address of the PFN for the corrupted page table page. On a 32 bit version of Windows, parameter 2 contains a pointer to the number of used PTEs, and parameter 3 contains the number of used PTEs.

0x41792

A corrupted PTE has been detected. Parameter 2 contains the address of the PTE. Parameters 3/4 contain the low/high parts of the PTE.

0x61940

A PDE has been unexpectedly invalidated.

0x61946

The MDL being created is flawed. This almost always means the driver calling MmProbeAndLockPages is at fault. Typically the driver is attempting to create a Write MDL when it is being asked to process a paging Read.

0x03030303

The boot loader is broken. (This value applies only to Intel Itanium machines.)

Other

An unknown memory management error occurred.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1b--pfn-share-count.md b/windows-driver-docs-pr/debugger/bug-check-0x1b--pfn-share-count.md new file mode 100644 index 0000000000..a13c7da7a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1b--pfn-share-count.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1B PFN_SHARE_COUNT +description: The PFN_SHARE_COUNT bug check has a value of 0x0000001B.This bug check appears very infrequently. +ms.assetid: 7af4f639-2412-4312-84a7-66354d300ec6 +keywords: ["Bug Check 0x1B PFN_SHARE_COUNT", "PFN_SHARE_COUNT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PFN_SHARE_COUNT +api_type: +- NA +--- + +# Bug Check 0x1B: PFN\_SHARE\_COUNT + + +The PFN\_SHARE\_COUNT bug check has a value of 0x0000001B. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1c--pfn-reference-count.md b/windows-driver-docs-pr/debugger/bug-check-0x1c--pfn-reference-count.md new file mode 100644 index 0000000000..bc6da4c32c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1c--pfn-reference-count.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1C PFN_REFERENCE_COUNT +description: The PFN_REFERENCE_COUNT bug check has a value of 0x0000001C.This bug check appears very infrequently. +ms.assetid: 0fb1cb56-e542-4b9e-9b06-f4dfc7657bb8 +keywords: ["Bug Check 0x1C PFN_REFERENCE_COUNT", "PFN_REFERENCE_COUNT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PFN_REFERENCE_COUNT +api_type: +- NA +--- + +# Bug Check 0x1C: PFN\_REFERENCE\_COUNT + + +The PFN\_REFERENCE\_COUNT bug check has a value of 0x0000001C. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1c4--driver-verifier-detected-violation-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x1c4--driver-verifier-detected-violation-livedump.md new file mode 100644 index 0000000000..43f0795f34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1c4--driver-verifier-detected-violation-livedump.md @@ -0,0 +1,466 @@ +--- +title: Bug Check 0x1C4 DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP +description: The DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP bug check has a value of 0x000001C4. +ms.assetid: B5C00570-477C-4C0C-B8B9-A7796FC33D63 +keywords: ["Bug Check 0x1C4 DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP", "DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_VERIFIER_DETECTED_VIOLATION_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x1C4: DRIVER\_VERIFIER\_DETECTED\_VIOLATION\_LIVEDUMP + + +The DRIVER\_VERIFIER\_DETECTED\_VIOLATION\_LIVEDUMP bug check has a value of 0x000001C4. This indicates that a device driver attempting to corrupt the system has been detected. This is because the driver was specified in the registry as being suspect (by the administrator) and the kernel has enabled substantial checking of this driver. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_VERIFIER\_DETECTED\_VIOLATION\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

The subclass of driver violation.

+
+``` + 0x00081001: ID of the 'KsDeviceMutex' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081002: ID of the 'KsStreamPointerClone' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081003: ID of the 'KsStreamPointerLock' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00081004: ID of the 'KsStreamPointerUnlock' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081005: ID of the 'KsCallbackReturn' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00081006: ID of the 'KsIrqlDeviceCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081007: ID of the 'KsIrqlFilterCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081008: ID of the 'KsIrqlPinCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00081009: ID of the 'KsIrqlDDIs' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0008100A: ID of the 'KsFilterMutex' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0008100B: ID of the 'KsProcessingMutex' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00082001: ID of the 'KsTimedPinSetDeviceState' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00082002: ID of the 'KsTimedDeviceCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00082003: ID of the 'KsTimedFilterCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00082004: ID of the 'KsTimedPinCallbacks' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00082005: ID of the 'KsTimedProcessingMutex' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00071001: ID of the 'PcIrqlDDIs' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00071003: ID of the 'PcIrqlIport' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00071004: ID of the 'PcUnmapAllocatedPages' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00071005: ID of the 'PcAllocatedPages' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00071006: ID of the 'PcRegisterAdapterPower' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00071007: ID of the 'PcAddAdapterDevice' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00071008: ID of the 'PcPropertyRequest' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00071009: ID of the 'PcAllocateAndMapPages' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0007100A: ID of the 'PcPoRequestPowerIrp' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00072001: ID of the 'PcTimedWaveRtStreamSetState' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00020002: ID of the 'IrqlApcLte' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020003: ID of the 'IrqlDispatch' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020004: ID of the 'IrqlExAllocatePool' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020005: ID of the 'IrqlExApcLte1' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020006: ID of the 'IrqlExApcLte2' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020007: ID of the 'IrqlExApcLte3' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020008: ID of the 'IrqlExPassive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020009: ID of the 'IrqlIoApcLte' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000A: ID of the 'IrqlIoPassive1' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000B: ID of the 'IrqlIoPassive2' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000C: ID of the 'IrqlIoPassive3' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000D: ID of the 'IrqlIoPassive4' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000E: ID of the 'IrqlIoPassive5' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002000F: ID of the 'IrqlKeApcLte1' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020010: ID of the 'IrqlKeApcLte2' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020011: ID of the 'IrqlKeDispatchLte' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020015: ID of the 'IrqlKeReleaseSpinLock' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020016: ID of the 'IrqlKeSetEvent' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020019: ID of the 'IrqlMmApcLte' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002001A: ID of the 'IrqlMmDispatch' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002001B: ID of the 'IrqlObPassive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002001C: ID of the 'IrqlPsPassive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002001D: ID of the 'IrqlReturn' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0002001E: ID of the 'IrqlRtlPassive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0002001F: ID of the 'IrqlZwPassive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00020022: ID of the 'IrqlIoDispatch' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00040003: ID of the 'CriticalRegions' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00040006: ID of the 'QueuedSpinLock' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00040007: ID of the 'QueuedSpinLockRelease' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00040009: ID of the 'SpinLock' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0004000A: ID of the 'SpinlockRelease' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0004000E: ID of the 'GuardedRegions' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0004100B: ID of the 'RequestedPowerIrp' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x0004100F: ID of the 'IoSetCompletionExCompleteIrp' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00043006: ID of the 'PnpRemove' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00091001: ID of the 'NdisOidComplete' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00091002: ID of the 'NdisOidDoubleComplete' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0009100E: ID of the 'NdisOidDoubleRequest' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00092003: ID of the 'NdisTimedOidComplete' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0009200D: ID of the 'NdisTimedDataSend' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0009200F: ID of the 'NdisTimedDataHang' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00092010: ID of the 'NdisFilterTimedPauseComplete' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00092011: ID of the 'NdisFilterTimedDataSend' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00092012: ID of the 'NdisFilterTimedDataReceive' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00093004: ID of the 'WlanAssociation' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00093005: ID of the 'WlanConnectionRoaming' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00093006: ID of the 'WlanDisassociation' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00093101: ID of the 'WlanAssert' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Reserved + Parameter 4 - Reserved + + 0x00094007: ID of the 'WlanTimedAssociation' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00094008: ID of the 'WlanTimedConnectionRoaming' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x00094009: ID of the 'WlanTimedConnectRequest' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0009400B: ID of the 'WlanTimedLinkQuality' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). + + 0x0009400C: ID of the 'WlanTimedScan' rule that was violated. + Parameter 2 - A pointer to the string describing the violated rule condition. + Parameter 3 - Address of internal rule state (second argument to !ruleinfo). + Parameter 4 - Address of supplemental states (third argument to !ruleinfo). +``` +
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1c5--io-threadpool-deadlock-livedump.md b/windows-driver-docs-pr/debugger/bug-check-0x1c5--io-threadpool-deadlock-livedump.md new file mode 100644 index 0000000000..bdaf91802c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1c5--io-threadpool-deadlock-livedump.md @@ -0,0 +1,69 @@ +--- +title: Bug Check 0x1C5 IO_THREADPOOL_DEADLOCK_LIVEDUMP +description: The IO_THREADPOOL_DEADLOCK_LIVEDUMP bug check has a value of 0x000001C5. This indicates a kernel mode threadpool encountered a deadlock situation. +ms.assetid: CBAB931F-E2A9-4843-9565-DC1CA3B557E6 +keywords: ["Bug Check 0x1C5 IO_THREADPOOL_DEADLOCK_LIVEDUMP", "IO_THREADPOOL_DEADLOCK_LIVEDUMP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IO_THREADPOOL_DEADLOCK_LIVEDUMP +api_type: +- NA +--- + +# Bug Check 0x1C5: IO\_THREADPOOL\_DEADLOCK\_LIVEDUMP + + +The IO\_THREADPOOL\_DEADLOCK\_LIVEDUMP bug check has a value of 0x000001C5. This indicates a kernel mode threadpool encountered a deadlock situation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IO\_THREADPOOL\_DEADLOCK\_LIVEDUMP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Pool Number.

+

0x0 : ExPoolUntrusted

2Pointer to the PEX_WORK_QUEUE
3Reserved
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1d--no-spin-lock-available.md b/windows-driver-docs-pr/debugger/bug-check-0x1d--no-spin-lock-available.md new file mode 100644 index 0000000000..bd2edbc072 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1d--no-spin-lock-available.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1D NO_SPIN_LOCK_AVAILABLE +description: The NO_SPIN_LOCK_AVAILABLE bug check has a value of 0x0000001D.This bug check appears very infrequently. +ms.assetid: 9720538e-0e47-4e7f-89d0-aeef353d00b8 +keywords: ["Bug Check 0x1D NO_SPIN_LOCK_AVAILABLE", "NO_SPIN_LOCK_AVAILABLE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_SPIN_LOCK_AVAILABLE +api_type: +- NA +--- + +# Bug Check 0x1D: NO\_SPIN\_LOCK\_AVAILABLE + + +The NO\_SPIN\_LOCK\_AVAILABLE bug check has a value of 0x0000001D. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1e--kmode-exception-not-handled.md b/windows-driver-docs-pr/debugger/bug-check-0x1e--kmode-exception-not-handled.md new file mode 100644 index 0000000000..f7f1548910 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1e--kmode-exception-not-handled.md @@ -0,0 +1,193 @@ +--- +title: Bug Check 0x1E KMODE_EXCEPTION_NOT_HANDLED +description: The KMODE_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000001E. This indicates that a kernel-mode program generated an exception which the error handler did not catch. +ms.assetid: 4a30b770-b2c4-4fdd-b431-95f2b40ef5f7 +keywords: ["Bug Check 0x1E KMODE_EXCEPTION_NOT_HANDLED", "KMODE_EXCEPTION_NOT_HANDLED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KMODE_EXCEPTION_NOT_HANDLED +api_type: +- NA +--- + +# Bug Check 0x1E: KMODE\_EXCEPTION\_NOT\_HANDLED + + +The KMODE\_EXCEPTION\_NOT\_HANDLED bug check has a value of 0x0000001E. This indicates that a kernel-mode program generated an exception which the error handler did not catch. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KMODE\_EXCEPTION\_NOT\_HANDLED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The exception code that was not handled

2

The address at which the exception occurred

3

Parameter 0 of the exception

4

Parameter 1 of the exception

+ +  + +Cause +----- + +This is a common bug check. To interpret it, you must identify which exception was generated. + +Common exception codes include: + +- 0x80000002: STATUS\_DATATYPE\_MISALIGNMENT + + An unaligned data reference was encountered. + +- 0x80000003: STATUS\_BREAKPOINT + + A breakpoint or ASSERT was encountered when no kernel debugger was attached to the system. + +- 0xC0000005: STATUS\_ACCESS\_VIOLATION + + A memory access violation occurred. (Parameter 4 of the bug check is the address that the driver attempted to access.) + +For a complete list of exception codes, see the ntstatus.h file located in the inc directory of the Windows Driver Kit. + +Resolution +---------- + +**If you are not equipped to debug this problem**, you can use some basic troubleshooting techniques described in [**Blue Screen Data**](blue-screen-data.md). If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +**If you plan to debug this problem**, you may find it difficult to obtain a stack trace. Parameter 2 (the exception address) should pinpoint the driver or function that caused this problem. + +If exception code 0x80000003 occurs, this indicates that a hard-coded breakpoint or assertion was hit, but the system was started with the **/NODEBUG** switch. This problem should rarely occur. If it occurs repeatedly, make sure a kernel debugger is connected and the system is started with the **/DEBUG** switch. + +If exception code 0x80000002 occurs, the trap frame will supply additional information. + +If the specific cause of the exception is unknown, the following should be considered: + +**Hardware incompatibility** + +Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +**Faulty device driver or system service** + +In addition, a faulty device driver or system service might be responsible for this error. Hardware issues, such as BIOS incompatibilities, memory conflicts, and IRQ conflicts can also generate this error. + +If a driver is listed by name within the bug check message, disable or remove that driver. Disable or remove any drivers or services that were recently added. If the error occurs during the startup sequence and the system partition is formatted with NTFS file system, you might be able to use Safe Mode to disable the driver in Device Manager. + +Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing bug check 0x1E. You should also run hardware diagnostics, especially the memory scanner, supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. + +The error that generates this message can occur after the first restart during Windows Setup, or after Setup is finished. A possible cause of the error is a system BIOS incompatibility. BIOS problems can be resolved by upgrading the system BIOS version. + +**To get a stack trace if the normal stack tracing procedures fail** + +1. Use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command to display parameters in the stack trace. Look for the call to **NT!PspUnhandledExceptionInSystemThread**. (If this function is not listed, see the note below.) + +2. The first parameter to **NT!PspUnhandledExceptionInSystemThread** is a pointer to a structure, which contains pointers to an **except** statement: + + ``` + typedef struct _EXCEPTION_POINTERS { + PEXCEPTION_RECORD ExceptionRecord; + PCONTEXT ContextRecord; + } EXCEPTION_POINTERS, *PEXCEPTION_POINTERS; + + ULONG PspUnhandledExceptionInSystemThread( + IN PEXCEPTION_POINTERS ExceptionPointers + ) + ``` + + Use the [**dd (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command on that address to display the necessary data. + +3. The first retrieved value is an exception record and the second is a context record. Use the [**.exr (Display Exception Record)**](-exr--display-exception-record-.md) command and the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with these two values as their arguments, respectively. + +4. After the **.cxr** command executes, use the **kb** command to display a stack trace that is based on the context record information. This stack trace indicates the calling stack where the unhandled exception occurred. + +**Note**  This procedure assumes that you can locate **NT!PspUnhandledExceptionInSystemThread**. However, in some cases (such as an access violation crash) you will not be able to do this. In that case, look for **ntoskrnl!KiDispatchException**. The third parameter passed to this function is a trap frame address. Use the [**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) command with this address to set the Register Context to the proper value. You can then perform stack traces and issue other commands. + +  + +Here is an example of bug check 0x1E on an x86 processor: + +``` +kd> .bugcheck get the bug check data +Bugcheck code 0000001e +Arguments c0000005 8013cd0a 00000000 0362cffff + +kd> kb start with a stack trace +FramePtr RetAddr Param1 Param2 Param3 Function Name +8013ed5c 801263ba 00000000 00000000 fe40cb00 NT!_DbgBreakPoint +8013eecc 8013313c 0000001e c0000005 8013cd0a NT!_KeBugCheckEx+0x194 +fe40cad0 8013318e fe40caf8 801359ff fe40cb00 NT!PspUnhandledExceptionInSystemThread+0x18 +fe40cad8 801359ff fe40cb00 00000000 fe40cb00 NT!PspSystemThreadStartup+0x4a +fe40cf7c 8013cb8e fe43a44c ff6ce388 00000000 NT!_except_handler3+0x47 +00000000 00000000 00000000 00000000 00000000 NT!KiThreadStartup+0xe + +kd> dd fe40caf8 L2 dump EXCEPTION_POINTERS structure +0xFE40CAF8 fe40cd88 fe40cbc4 ..@...@. + +kd> .exr fe40cd88 first DWORD is the exception record +Exception Record @ FE40CD88: + ExceptionCode: c0000005 + ExceptionFlags: 00000000 + Chained Record: 00000000 +ExceptionAddress: 8013cd0a +NumberParameters: 00000002 + Parameter[0]: 00000000 + Parameter[1]: 0362cfff + +kd> .cxr fe40cbc4 second DWORD is the context record +CtxFlags: 00010017 +eax=00087000 ebx=00000000 ecx=03ff0000 edx=ff63d000 esi=0362cfff edi=036b3fff +eip=8013cd0a esp=fe40ce50 ebp=fe40cef8 iopl=0 nv dn ei pl nz ac po cy +vip=0 vif=0 +cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000 efl=00010617 +0x8013cd0a f3a4 rep movsb + +kd> kb kb gives stack for context record +ChildEBP RetAddr Args to Child +fe40ce54 80402e09 ff6c4000 ff63d000 03ff0000 NT!_RtlMoveMemory@12+0x3e +fe40ce68 80403c18 ffbc0c28 ff6ce008 ff6c4000 HAL!_HalpCopyBufferMap@20+0x49 +fe40ce9c fe43b1e4 ff6cef90 ffbc0c28 ff6ce009 HAL!_IoFlushAdapterBuffers@24+0x148 +fe40ceb8 fe4385b4 ff6ce388 6cd00800 ffbc0c28 QIC117!_kdi_FlushDMABuffers@20+0x28 +fe40cef8 fe439894 ff6cd008 ffb6c820 fe40cf4c QIC117!_cqd_CmdReadWrite@8+0x26e +fe40cf18 fe437d92 ff6cd008 ffb6c820 ff6e4e50 QIC117!_cqd_DispatchFRB@8+0x210 +fe40cf30 fe43a4f5 ff6cd008 ffb6c820 00000000 QIC117!_cqd_ProcessFRB@8+0x134 +fe40cf4c 80133184 ff6ce388 00000000 00000000 QIC117!_kdi_ThreadRun@4+0xa9 +fe40cf7c 8013cb8e fe43a44c ff6ce388 00000000 NT!_PspSystemThreadStartup@8+0x40 +``` + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x1f--shared-resource-conv-error.md b/windows-driver-docs-pr/debugger/bug-check-0x1f--shared-resource-conv-error.md new file mode 100644 index 0000000000..08a8dea874 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x1f--shared-resource-conv-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x1F SHARED_RESOURCE_CONV_ERROR +description: The SHARED_RESOURCE_CONV_ERROR bug check has a value of 0x0000001F.This bug check appears very infrequently. +ms.assetid: 36262cbf-29e1-4e75-bb25-ca71bf819272 +keywords: ["Bug Check 0x1F SHARED_RESOURCE_CONV_ERROR", "SHARED_RESOURCE_CONV_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SHARED_RESOURCE_CONV_ERROR +api_type: +- NA +--- + +# Bug Check 0x1F: SHARED\_RESOURCE\_CONV\_ERROR + + +The SHARED\_RESOURCE\_CONV\_ERROR bug check has a value of 0x0000001F. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2--device-queue-not-busy.md b/windows-driver-docs-pr/debugger/bug-check-0x2--device-queue-not-busy.md new file mode 100644 index 0000000000..cab1527a81 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2--device-queue-not-busy.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x2 DEVICE_QUEUE_NOT_BUSY +description: The DEVICE_QUEUE_NOT_BUSY bug check has a value of 0x00000002.This bug check appears very infrequently. +ms.assetid: 04db7272-0c9c-4fb7-a680-efa4c97603b1 +keywords: ["Bug Check 0x2 DEVICE_QUEUE_NOT_BUSY", "DEVICE_QUEUE_NOT_BUSY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DEVICE_QUEUE_NOT_BUSY +api_type: +- NA +--- + +# Bug Check 0x2: DEVICE\_QUEUE\_NOT\_BUSY + + +The DEVICE\_QUEUE\_NOT\_BUSY bug check has a value of 0x00000002. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x20--kernel-apc-pending-during-exit.md b/windows-driver-docs-pr/debugger/bug-check-0x20--kernel-apc-pending-during-exit.md new file mode 100644 index 0000000000..1941857f14 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x20--kernel-apc-pending-during-exit.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0x20 KERNEL_APC_PENDING_DURING_EXIT +description: The KERNEL_APC_PENDING_DURING_EXIT bug check has a value of 0x00000020. This indicates that an asynchronous procedure call (APC) was still pending when a thread exited. +ms.assetid: 0ef7c2b2-0864-4206-b786-bac9df9cedc7 +keywords: ["Bug Check 0x20 KERNEL_APC_PENDING_DURING_EXIT", "KERNEL_APC_PENDING_DURING_EXIT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_APC_PENDING_DURING_EXIT +api_type: +- NA +--- + +# Bug Check 0x20: KERNEL\_APC\_PENDING\_DURING\_EXIT + + +The KERNEL\_APC\_PENDING\_DURING\_EXIT bug check has a value of 0x00000020. This indicates that an asynchronous procedure call (APC) was still pending when a thread exited. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_APC\_PENDING\_DURING\_EXIT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the APC found pending during exit

2

The thread's APC disable count

3

The current IRQL

4

Reserved

+ +  + +Cause +----- + +The key data item is the APC disable count (Parameter 2) for the thread. If the count is nonzero, it will indicate the source of the problem. + +The APC disable count is decremented each time a driver calls **KeEnterCriticalRegion**, **FsRtlEnterFileSystem**, or acquires a mutex. + +The APC disable count is incremented each time a driver calls **KeLeaveCriticalRegion**, **KeReleaseMutex**, or **FsRtlExitFileSystem**. + +Because these calls should always be in pairs, the APC disable count should be zero when a thread exits. A negative value indicates that a driver has disabled APC calls without re-enabling them. A positive value indicates that the reverse is true. + +If you ever see this error, be very suspicious of all drivers installed on the machine -- especially unusual or non-standard drivers. + +This current IRQL (Parameter 3) should be zero. If it is not, the driver's cancellation routine may have caused this bug check by returning at an elevated IRQL. In this case, carefully note what was running (and what was closing) at the time of the crash, and note all of the installed drivers at the time of the crash. The cause in this case is usually a severe bug in a driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x21--quota-underflow.md b/windows-driver-docs-pr/debugger/bug-check-0x21--quota-underflow.md new file mode 100644 index 0000000000..3329f1156c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x21--quota-underflow.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x21 QUOTA_UNDERFLOW +description: The QUOTA_UNDERFLOW bug check has a value of 0x00000021. This indicates that quota charges have been mishandled by returning more quota to a particular block than was previously charged. +ms.assetid: 41b1c93b-77e0-4baa-8eed-7a956e45d144 +keywords: ["Bug Check 0x21 QUOTA_UNDERFLOW", "QUOTA_UNDERFLOW"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- QUOTA_UNDERFLOW +api_type: +- NA +--- + +# Bug Check 0x21: QUOTA\_UNDERFLOW + + +The QUOTA\_UNDERFLOW bug check has a value of 0x00000021. This indicates that quota charges have been mishandled by returning more quota to a particular block than was previously charged. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## QUOTA\_UNDERFLOW Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The process that was initially charged, if available.

2

The quota type. For the list of all possible quota type values, see the header file Ps.h in the Windows Driver Kit (WDK).

3

The initial charged amount of quota to return.

4

The remaining amount of quota that was not returned.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x22--file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x22--file-system.md new file mode 100644 index 0000000000..dcaa78f2fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x22--file-system.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x22 FILE_SYSTEM +description: The FILE_SYSTEM bug check has a value of 0x00000022.This bug check appears very infrequently. +ms.assetid: 89230b9a-f538-4892-b36e-3410c7adcc81 +keywords: ["Bug Check 0x22 FILE_SYSTEM", "FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x22: FILE\_SYSTEM + + +The FILE\_SYSTEM bug check has a value of 0x00000022. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x23--fat-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x23--fat-file-system.md new file mode 100644 index 0000000000..58201a1277 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x23--fat-file-system.md @@ -0,0 +1,84 @@ +--- +title: Bug Check 0x23 FAT_FILE_SYSTEM +description: The FAT_FILE_SYSTEM bug check has a value of 0x00000023. This indicates that a problem occurred in the FAT file system. +ms.assetid: 5a10e650-2fca-4836-b407-ded8b41c43a1 +keywords: ["Bug Check 0x23 FAT_FILE_SYSTEM", "FAT_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FAT_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x23: FAT\_FILE\_SYSTEM + + +The FAT\_FILE\_SYSTEM bug check has a value of 0x00000023. This indicates that a problem occurred in the FAT file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FAT\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

If FatExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If FatExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted SCSI and IDE drivers can also adversely affect the system's ability to read and write to the disk, thus causing the error. + +Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a disk corruption problem:** Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You should also run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. Run **Chkdsk /f /r** to detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition. + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x24--ntfs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x24--ntfs-file-system.md new file mode 100644 index 0000000000..e034d9b15d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x24--ntfs-file-system.md @@ -0,0 +1,103 @@ +--- +title: Bug Check 0x24 NTFS_FILE_SYSTEM +description: The NTFS_FILE_SYSTEM bug check has a value of 0x00000024. This indicates a problem occurred in ntfs.sys, the driver file that allows the system to read and write to NTFS drives. +ms.assetid: 9d2dd8a8-b550-4392-b663-6902a015ef7b +keywords: ["Bug Check 0x24 NTFS_FILE_SYSTEM", "NTFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NTFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x24: NTFS\_FILE\_SYSTEM + + +The NTFS\_FILE\_SYSTEM bug check has a value of 0x00000024. This indicates a problem occurred in ntfs.sys, the driver file that allows the system to read and write to NTFS drives. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NTFS\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

If NtfsExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If NtfsExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is disk corruption. Corruption in the NTFS file system or bad blocks (sectors) on the hard disk can induce this error. Corrupted hard drive (SATA/IDE) drivers can also adversely affect the system's ability to read and write to disk, thus causing the error. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a disk corruption problem:** + +- Check Event Viewer for error messages related to the hard drive appearing in the System Log that might help pinpoint the device or driver that is causing the error. + +- Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. + +- You should also run hardware diagnostics supplied by the system manufacturer related to the storage sub system. + +- Use the scan disk utility to confirm that there are no file system errors. Right click on the drive you want to scan and select **Properties**. Click on **Tools**. Click the **Check now** button. +- Confirm that there is sufficient free space on the hard drive. The operating system and some applications require sufficient free space to create swap files and for other functions. Based on the system configuration, the exact requirement varies, but it is normally a good idea to have 10% to 15% free space available. + +- Use the System File Checker tool to repair missing or corrupted system files. The System File Checker is a utility in Windows that allows users to scan for corruptions in Windows system files and restore corrupted files. Use the following command to run the System File Checker tool (SFC.exe). + + ``` + SFC /scannow + ``` + + For more information, see [Use the System File Checker tool to repair missing or corrupted system files](https://support.microsoft.com/kb/929833). + +- **Driver Verifier** + + Driver Verifier is a tool that runs in real time to examine the behavior of drivers. If it see errors in the execution of driver code, it proactively creates an exception to allow that part of the driver code to be further scrutinized. The driver verifier manager is built into Windows and is available on all Windows PCs. To start the driver verifier manager, type *Verifer* at a command prompt. You can configure which drivers you would like to verify. The code that verifies drivers adds overhead as it runs, so try and verify the smallest number of drivers as possible. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +In the past, another possible cause of this stop code is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x25--npfs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x25--npfs-file-system.md new file mode 100644 index 0000000000..33f98f83f8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x25--npfs-file-system.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x25 NPFS_FILE_SYSTEM +description: The NPFS_FILE_SYSTEM bug check has a value of 0x00000025. This indicates that a problem occurred in the NPFS file system. +ms.assetid: 099c93ec-78c0-4bb9-827d-712cfdfec0bb +keywords: ["Bug Check 0x25 NPFS_FILE_SYSTEM", "NPFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NPFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x25: NPFS\_FILE\_SYSTEM + + +The NPFS\_FILE\_SYSTEM bug check has a value of 0x00000025. This indicates that a problem occurred in the NPFS file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NPFS\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x26--cdfs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x26--cdfs-file-system.md new file mode 100644 index 0000000000..ed9caf5bee --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x26--cdfs-file-system.md @@ -0,0 +1,84 @@ +--- +title: Bug Check 0x26 CDFS_FILE_SYSTEM +description: The CDFS_FILE_SYSTEM bug check has a value of 0x00000026. This indicates that a problem occurred in the CD file system. +ms.assetid: f427c262-f750-4719-a52b-2f00094d2a4e +keywords: ["Bug Check 0x26 CDFS_FILE_SYSTEM", "CDFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CDFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x26: CDFS\_FILE\_SYSTEM + + +The CDFS\_FILE\_SYSTEM bug check has a value of 0x00000026. This indicates that a problem occurred in the CD file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CDFS\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

If CdExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If CdExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted SCSI and IDE drivers can also adversely affect the system's ability to read and write to the disk, thus causing the error. + +Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a disk corruption problem:** Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You should also run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. Run **Chkdsk /f /r** to detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition. + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x27--rdr-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x27--rdr-file-system.md new file mode 100644 index 0000000000..edd1c951d6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x27--rdr-file-system.md @@ -0,0 +1,85 @@ +--- +title: Bug Check 0x27 RDR_FILE_SYSTEM +description: The RDR_FILE_SYSTEM bug check has a value of 0x00000027. This indicates that a problem occurred in the SMB redirector file system. +ms.assetid: 1294022d-7281-45d2-89c8-40d11ce202f0 +keywords: ["Bug Check 0x27 RDR_FILE_SYSTEM", "RDR_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RDR_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x27: RDR\_FILE\_SYSTEM + + +The RDR\_FILE\_SYSTEM bug check has a value of 0x00000027. This indicates that a problem occurred in the SMB redirector file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RDR\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The high 16 bits (the first four hexadecimal digits after the "0x") identify the type of problem. Possible values include:

+

0xCA550000 RDBSS_BUG_CHECK_CACHESUP

+

0xC1EE0000 RDBSS_BUG_CHECK_CLEANUP

+

0xC10E0000 RDBSS_BUG_CHECK_CLOSE

+

0xBAAD0000 RDBSS_BUG_CHECK_NTEXCEPT

+

2

If RxExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If RxExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x28--corrupt-access-token.md b/windows-driver-docs-pr/debugger/bug-check-0x28--corrupt-access-token.md new file mode 100644 index 0000000000..87b43232b6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x28--corrupt-access-token.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x28 CORRUPT_ACCESS_TOKEN +description: The CORRUPT_ACCESS_TOKEN bug check has a value of 0x00000028.This bug check appears very infrequently. +ms.assetid: 33f275b8-1f7a-49ed-af4b-8686b73d64f9 +keywords: ["Bug Check 0x28 CORRUPT_ACCESS_TOKEN", "CORRUPT_ACCESS_TOKEN"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CORRUPT_ACCESS_TOKEN +api_type: +- NA +--- + +# Bug Check 0x28: CORRUPT\_ACCESS\_TOKEN + + +The CORRUPT\_ACCESS\_TOKEN bug check has a value of 0x00000028. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x29--security-system.md b/windows-driver-docs-pr/debugger/bug-check-0x29--security-system.md new file mode 100644 index 0000000000..28b5720131 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x29--security-system.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x29 SECURITY_SYSTEM +description: The SECURITY_SYSTEM bug check has a value of 0x00000029.This bug check appears very infrequently. +ms.assetid: 9a027a41-71f4-4b5e-a9f0-c626c77248cf +keywords: ["Bug Check 0x29 SECURITY_SYSTEM", "SECURITY_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SECURITY_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x29: SECURITY\_SYSTEM + + +The SECURITY\_SYSTEM bug check has a value of 0x00000029. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2a--inconsistent-irp.md b/windows-driver-docs-pr/debugger/bug-check-0x2a--inconsistent-irp.md new file mode 100644 index 0000000000..618047fd10 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2a--inconsistent-irp.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x2A INCONSISTENT_IRP +description: The INCONSISTENT_IRP bug check has a value of 0x0000002A. This indicates that an IRP was found to contain inconsistent information. +ms.assetid: e8dcfba1-94ed-499c-ae00-e0dfaf7f5094 +keywords: ["Bug Check 0x2A INCONSISTENT_IRP", "INCONSISTENT_IRP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INCONSISTENT_IRP +api_type: +- NA +--- + +# Bug Check 0x2A: INCONSISTENT\_IRP + + +The INCONSISTENT\_IRP bug check has a value of 0x0000002A. This indicates that an IRP was found to contain inconsistent information. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INCONSISTENT\_IRP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the IRP that was found to be inconsistent

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +An IRP was discovered to be in an inconsistent state. Usually this means some field of the IRP was inconsistent with the remaining state of the IRP. An example would be an IRP that was being completed, but was still marked as being queued to a driver's device queue. + +Remarks +------- + +This bug check code is not currently being used in the system, but exists for debugging purposes. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2b--panic-stack-switch.md b/windows-driver-docs-pr/debugger/bug-check-0x2b--panic-stack-switch.md new file mode 100644 index 0000000000..e839c9ba51 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2b--panic-stack-switch.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x2B PANIC_STACK_SWITCH +description: The PANIC_STACK_SWITCH bug check has a value of 0x0000002B. This indicates that the kernel mode stack was overrun. +ms.assetid: 0ab28a16-979d-4b40-812a-a31fac3f6be8 +keywords: ["Bug Check 0x2B PANIC_STACK_SWITCH", "PANIC_STACK_SWITCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PANIC_STACK_SWITCH +api_type: +- NA +--- + +# Bug Check 0x2B: PANIC\_STACK\_SWITCH + + +The PANIC\_STACK\_SWITCH bug check has a value of 0x0000002B. This indicates that the kernel mode stack was overrun. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PANIC\_STACK\_SWITCH Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The trap frame

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +This error normally appears when a kernel-mode driver uses too much stack space. It can also appear when serious data corruption occurs in the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2c--port-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x2c--port-driver-internal.md new file mode 100644 index 0000000000..93f4b5f6bf --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2c--port-driver-internal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x2C PORT_DRIVER_INTERNAL +description: The PORT_DRIVER_INTERNAL bug check has a value of 0x0000002C.This bug check appears very infrequently. +ms.assetid: c7caf68e-e7b7-493f-90ad-14cd45b66cba +keywords: ["Bug Check 0x2C PORT_DRIVER_INTERNAL", "PORT_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PORT_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x2C: PORT\_DRIVER\_INTERNAL + + +The PORT\_DRIVER\_INTERNAL bug check has a value of 0x0000002C. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2d--scsi-disk-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x2d--scsi-disk-driver-internal.md new file mode 100644 index 0000000000..5c9dbad9c7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2d--scsi-disk-driver-internal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x2D SCSI_DISK_DRIVER_INTERNAL +description: The SCSI_DISK_DRIVER_INTERNAL bug check has a value of 0x0000002D.This bug check appears very infrequently. +ms.assetid: 36956b1b-94e9-42c1-a8e2-09324ea15eca +keywords: ["Bug Check 0x2D SCSI_DISK_DRIVER_INTERNAL", "SCSI_DISK_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SCSI_DISK_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x2D: SCSI\_DISK\_DRIVER\_INTERNAL + + +The SCSI\_DISK\_DRIVER\_INTERNAL bug check has a value of 0x0000002D. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2e--data-bus-error.md b/windows-driver-docs-pr/debugger/bug-check-0x2e--data-bus-error.md new file mode 100644 index 0000000000..19c241ae91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2e--data-bus-error.md @@ -0,0 +1,98 @@ +--- +title: Bug Check 0x2E DATA_BUS_ERROR +description: The DATA_BUS_ERROR bug check has a value of 0x0000002E. This typically indicates that a parity error in system memory has been detected. +ms.assetid: 117adb1b-49aa-4c4e-ae01-730d1d653c02 +keywords: ["Bug Check 0x2E DATA_BUS_ERROR", "DATA_BUS_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DATA_BUS_ERROR +api_type: +- NA +--- + +# Bug Check 0x2E: DATA\_BUS\_ERROR + + +The DATA\_BUS\_ERROR bug check has a value of 0x0000002E. This typically indicates that a parity error in system memory has been detected. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DATA\_BUS\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address that caused the fault

2

Physical address that caused the fault

3

Processor status register (PSR)

4

Faulting instruction register (FIR)

+ +  + +Cause +----- + +This error is almost always caused by a hardware problem -- a configuration issue, defective hardware, or incompatible hardware. + +The most common hardware problems that can cause this error are defective RAM, Level 2 (L2) RAM cache errors, or video RAM errors. Hard disk corruption can also cause this error. + +This bug check can also be caused when a device driver attempts to access an address in the 0x8*xxxxxxx* range that does not exist (in other words, that does not have a physical address mapping). + +Resolution +---------- + +**Resolving a hardware problem:** If hardware has recently been added to the system, remove it to see if the error recurs. + +If existing hardware has failed, remove or replace the faulty component. You should run hardware diagnostics supplied by the system manufacturer to determine which hardware component has failed. For details on these procedures, see the owner's manual for your computer. Check that all adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure that adapter card contacts are clean. + +If the problem occurs on a newly installed system, check the availability of updates for the BIOS, the SCSI controller or network cards. Updates of this kind are typically available on the Web site or the bulletin board system (BBS) of the hardware manufacturer. + +If the error occurs after installing a new or updated device driver, the driver should be removed or replaced. If, under this circumstance, the error occurs during startup and the system partition is formatted with NTFS, you might be able to use Safe Mode to rename or delete the faulty driver. + +If the driver is used as part of the system startup process in Safe Mode, you need to start the computer using the Recovery Console in order to access the file. + +For additional error messages that might help pinpoint the device or driver that is causing the error, check the System Log in Event Viewer. Disabling memory caching or shadowing in the BIOS might also resolve this error. In addition, check the system for viruses, using any up-to-date commercial virus scanning software that examines the Master Boot Record of the hard disk. All Windows file systems can be infected by viruses. + +**Resolving a hard disk corruption problem:** Run **Chkdsk /f /r** on the system partition. You must restart the system before the disk scan begins. If you cannot start the system due to the error, use the Recovery Console and run **Chkdsk /r**. + +**Warning**   If your system partition is formatted with the file allocation table (FAT) file system, the long filenames used by Windows can be damaged if Scandisk or another Microsoft MS-DOS-based hard disk tool is used to verify the integrity of your hard disk from MS-DOS. Always use the version of Chkdsk that matches your Windows version. + +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x2f--instruction-bus-error.md b/windows-driver-docs-pr/debugger/bug-check-0x2f--instruction-bus-error.md new file mode 100644 index 0000000000..c2b90b438b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x2f--instruction-bus-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x2F INSTRUCTION_BUS_ERROR +description: The INSTRUCTION_BUS_ERROR bug check has a value of 0x0000002F.This bug check appears very infrequently. +ms.assetid: ff2d54ad-924b-420c-b2f9-716c30cb1ef8 +keywords: ["Bug Check 0x2F INSTRUCTION_BUS_ERROR", "INSTRUCTION_BUS_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INSTRUCTION_BUS_ERROR +api_type: +- NA +--- + +# Bug Check 0x2F: INSTRUCTION\_BUS\_ERROR + + +The INSTRUCTION\_BUS\_ERROR bug check has a value of 0x0000002F. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3--invalid-affinity-set.md b/windows-driver-docs-pr/debugger/bug-check-0x3--invalid-affinity-set.md new file mode 100644 index 0000000000..995dde6912 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3--invalid-affinity-set.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x3 INVALID_AFFINITY_SET +description: The INVALID_AFFINITY_SET bug check has a value of 0x00000003.This bug check appears very infrequently. +ms.assetid: e58a872e-8cf8-4d3c-ae54-fe19fadcd57e +keywords: ["Bug Check 0x3 INVALID_AFFINITY_SET", "INVALID_AFFINITY_SET"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_AFFINITY_SET +api_type: +- NA +--- + +# Bug Check 0x3: INVALID\_AFFINITY\_SET + + +The INVALID\_AFFINITY\_SET bug check has a value of 0x00000003. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x30--set-of-invalid-context.md b/windows-driver-docs-pr/debugger/bug-check-0x30--set-of-invalid-context.md new file mode 100644 index 0000000000..b528bd5c46 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x30--set-of-invalid-context.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0x30 SET_OF_INVALID_CONTEXT +description: The SET_OF_INVALID_CONTEXT bug check has a value of 0x00000030. This indicates that the stack pointer in a trap frame had an invalid value. +ms.assetid: 77e86390-e387-4ffd-96dd-c32a98939c3a +keywords: ["Bug Check 0x30 SET_OF_INVALID_CONTEXT", "SET_OF_INVALID_CONTEXT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SET_OF_INVALID_CONTEXT +api_type: +- NA +--- + +# Bug Check 0x30: SET\_OF\_INVALID\_CONTEXT + + +The SET\_OF\_INVALID\_CONTEXT bug check has a value of 0x00000030. This indicates that the stack pointer in a trap frame had an invalid value. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SET\_OF\_INVALID\_CONTEXT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The new stack pointer

2

The old stack pointer

3

The trap frame address

4

0

+ +  + +Cause +----- + +This bug check occurs when some routine attempts to set the stack pointer in the trap frame to a lower value than the current stack pointer value. + +If this error were not caught, it would cause the kernel to run with a stack pointer pointing to stack which is no longer valid. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x31--phase0-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x31--phase0-initialization-failed.md new file mode 100644 index 0000000000..71b3462948 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x31--phase0-initialization-failed.md @@ -0,0 +1,47 @@ +--- +title: Bug Check 0x31 PHASE0_INITIALIZATION_FAILED +description: The PHASE0_INITIALIZATION_FAILED bug check has a value of 0x00000031. This indicates that system initialization failed. +ms.assetid: 7341a012-dc7d-4e41-a417-c5f5dfc8decc +keywords: ["Bug Check 0x31 PHASE0_INITIALIZATION_FAILED", "PHASE0_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PHASE0_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x31: PHASE0\_INITIALIZATION\_FAILED + + +The PHASE0\_INITIALIZATION\_FAILED bug check has a value of 0x00000031. This indicates that system initialization failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PHASE0\_INITIALIZATION\_FAILED Parameters + + +None + +Cause +----- + +System initialization failed at a very early stage. + +Resolution +---------- + +A debugger is required to analyze this. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x32--phase1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x32--phase1-initialization-failed.md new file mode 100644 index 0000000000..fb84782dea --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x32--phase1-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x32 PHASE1_INITIALIZATION_FAILED +description: The PHASE1_INITIALIZATION_FAILED bug check has a value of 0x00000032. This indicates that system initialization failed. +ms.assetid: 91437523-35f4-4715-bced-01961aefadce +keywords: ["Bug Check 0x32 PHASE1_INITIALIZATION_FAILED", "PHASE1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PHASE1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x32: PHASE1\_INITIALIZATION\_FAILED + + +The PHASE1\_INITIALIZATION\_FAILED bug check has a value of 0x00000032. This indicates that system initialization failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PHASE1\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that describes why the system initialization failed

2

Reserved

3

Reserved

4

Reserved

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x33--unexpected-initialization-call.md b/windows-driver-docs-pr/debugger/bug-check-0x33--unexpected-initialization-call.md new file mode 100644 index 0000000000..f36b4d9e07 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x33--unexpected-initialization-call.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x33 UNEXPECTED_INITIALIZATION_CALL +description: The UNEXPECTED_INITIALIZATION_CALL bug check has a value of 0x00000033.This bug check appears very infrequently. +ms.assetid: f925e167-1a89-4728-829d-2fdc4dea2908 +keywords: ["Bug Check 0x33 UNEXPECTED_INITIALIZATION_CALL", "UNEXPECTED_INITIALIZATION_CALL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNEXPECTED_INITIALIZATION_CALL +api_type: +- NA +--- + +# Bug Check 0x33: UNEXPECTED\_INITIALIZATION\_CALL + + +The UNEXPECTED\_INITIALIZATION\_CALL bug check has a value of 0x00000033. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x34--cache-manager.md b/windows-driver-docs-pr/debugger/bug-check-0x34--cache-manager.md new file mode 100644 index 0000000000..0b8ff2a661 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x34--cache-manager.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x34 CACHE_MANAGER +description: The CACHE_MANAGER bug check has a value of 0x00000034. This indicates that a problem occurred in the file system's cache manager. +ms.assetid: a943e5ce-0be7-4b30-94e7-3e29ce8aa38c +keywords: ["Bug Check 0x34 CACHE_MANAGER", "CACHE_MANAGER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CACHE_MANAGER +api_type: +- NA +--- + +# Bug Check 0x34: CACHE\_MANAGER + + +The CACHE\_MANAGER bug check has a value of 0x00000034. This indicates that a problem occurred in the file system's cache manager. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CACHE\_MANAGER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x35--no-more-irp-stack-locations.md b/windows-driver-docs-pr/debugger/bug-check-0x35--no-more-irp-stack-locations.md new file mode 100644 index 0000000000..cb19f68110 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x35--no-more-irp-stack-locations.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0x35 NO_MORE_IRP_STACK_LOCATIONS +description: The NO_MORE_IRP_STACK_LOCATIONS bug check has a value of 0x00000035. This bug check occurs when the IoCallDriver packet has no more stack locations remaining. +ms.assetid: 1a8d5a1b-70aa-4846-bafe-0fef041570c1 +keywords: ["Bug Check 0x35 NO_MORE_IRP_STACK_LOCATIONS", "NO_MORE_IRP_STACK_LOCATIONS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_MORE_IRP_STACK_LOCATIONS +api_type: +- NA +--- + +# Bug Check 0x35: NO\_MORE\_IRP\_STACK\_LOCATIONS + + +The NO\_MORE\_IRP\_STACK\_LOCATIONS bug check has a value of 0x00000035. This bug check occurs when the **IoCallDriver** packet has no more stack locations remaining. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NO\_MORE\_IRP\_STACK\_LOCATIONS Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of the IRP

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +A higher-level driver has attempted to call a lower-level driver through the **IoCallDriver** interface, but there are no more stack locations in the packet. This will prevent the lower-level driver from accessing its parameters. + +This is a disastrous situation, since the higher level driver is proceeding as if it has filled in the parameters for the lower level driver (as required). But since there is no stack location for the latter driver, the former has actually written off the end of the packet. This means that some other memory has been corrupted as well. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x36--device-reference-count-not-zero.md b/windows-driver-docs-pr/debugger/bug-check-0x36--device-reference-count-not-zero.md new file mode 100644 index 0000000000..0c890702a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x36--device-reference-count-not-zero.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x36 DEVICE_REFERENCE_COUNT_NOT_ZERO +description: The DEVICE_REFERENCE_COUNT_NOT_ZERO bug check has a value of 0x00000036. This indicates that a driver attempted to delete a device object that still had a positive reference count. +ms.assetid: 8379d034-44fd-412a-8a2d-d234d41227ac +keywords: ["Bug Check 0x36 DEVICE_REFERENCE_COUNT_NOT_ZERO", "DEVICE_REFERENCE_COUNT_NOT_ZERO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DEVICE_REFERENCE_COUNT_NOT_ZERO +api_type: +- NA +--- + +# Bug Check 0x36: DEVICE\_REFERENCE\_COUNT\_NOT\_ZERO + + +The DEVICE\_REFERENCE\_COUNT\_NOT\_ZERO bug check has a value of 0x00000036. This indicates that a driver attempted to delete a device object that still had a positive reference count. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DEVICE\_REFERENCE\_COUNT\_NOT\_ZERO Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the device object

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +A device driver has attempted to delete one of its device objects from the system, but the reference count for that object was non-zero. + +This means there are still outstanding references to the device. (The reference count indicates the number of reasons why this device object cannot be deleted.) + +This is a bug in the calling device driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x37--floppy-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x37--floppy-internal-error.md new file mode 100644 index 0000000000..80857e4daf --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x37--floppy-internal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x37 FLOPPY_INTERNAL_ERROR +description: The FLOPPY_INTERNAL_ERROR bug check has a value of 0x00000037.This bug check appears very infrequently. +ms.assetid: a5707c3c-2d11-4f37-8b0e-f9ca8937fef1 +keywords: ["Bug Check 0x37 FLOPPY_INTERNAL_ERROR", "FLOPPY_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FLOPPY_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x37: FLOPPY\_INTERNAL\_ERROR + + +The FLOPPY\_INTERNAL\_ERROR bug check has a value of 0x00000037. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x38--serial-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x38--serial-driver-internal.md new file mode 100644 index 0000000000..7179471eda --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x38--serial-driver-internal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x38 SERIAL_DRIVER_INTERNAL +description: The SERIAL_DRIVER_INTERNAL bug check has a value of 0x00000038.This bug check appears very infrequently. +ms.assetid: 27a11ade-0938-4153-b5b5-4b1a3edbb5b7 +keywords: ["Bug Check 0x38 SERIAL_DRIVER_INTERNAL", "SERIAL_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SERIAL_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x38: SERIAL\_DRIVER\_INTERNAL + + +The SERIAL\_DRIVER\_INTERNAL bug check has a value of 0x00000038. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x39--system-exit-owned-mutex.md b/windows-driver-docs-pr/debugger/bug-check-0x39--system-exit-owned-mutex.md new file mode 100644 index 0000000000..571617e1ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x39--system-exit-owned-mutex.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0x39 SYSTEM_EXIT_OWNED_MUTEX +description: The SYSTEM_EXIT_OWNED_MUTEX bug check has a value of 0x00000039. This indicates that the worker routine returned without releasing the mutex object that it owned. +ms.assetid: 79257486-f65e-4d02-acf0-b7f0607a21cc +keywords: ["Bug Check 0x39 SYSTEM_EXIT_OWNED_MUTEX", "SYSTEM_EXIT_OWNED_MUTEX"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_EXIT_OWNED_MUTEX +api_type: +- NA +--- + +# Bug Check 0x39: SYSTEM\_EXIT\_OWNED\_MUTEX + + +The SYSTEM\_EXIT\_OWNED\_MUTEX bug check has a value of 0x00000039. This indicates that the worker routine returned without releasing the mutex object that it owned. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_EXIT\_OWNED\_MUTEX Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the worker routine that caused the error.

2

The parameter passed to the worker routine.

3

The address of the work item.

4

Reserved.

+ +  + +Cause +----- + +The worker routine returned while it still owned a mutex object. The current worker thread will proceed to run other unrelated work items, and the mutex will never be released. + +Resolution +---------- + +A debugger is required to analyze this problem. To find the driver that caused the error, use the **ln** (List Nearest Symbols) debugger command: + +kd> ln address + +Where address is the worker routine given in Parameter 1. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3a--system-unwind-previous-user.md b/windows-driver-docs-pr/debugger/bug-check-0x3a--system-unwind-previous-user.md new file mode 100644 index 0000000000..71848575d5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3a--system-unwind-previous-user.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x3A SYSTEM_UNWIND_PREVIOUS_USER +description: The SYSTEM_UNWIND_PREVIOUS_USER bug check has a value of 0x0000003A.This bug check appears very infrequently. +ms.assetid: 13fb651f-f2a2-4591-9316-37bd9616c829 +keywords: ["Bug Check 0x3A SYSTEM_UNWIND_PREVIOUS_USER", "SYSTEM_UNWIND_PREVIOUS_USER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_UNWIND_PREVIOUS_USER +api_type: +- NA +--- + +# Bug Check 0x3A: SYSTEM\_UNWIND\_PREVIOUS\_USER + + +The SYSTEM\_UNWIND\_PREVIOUS\_USER bug check has a value of 0x0000003A. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3b--system-service-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x3b--system-service-exception.md new file mode 100644 index 0000000000..86a3ede84c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3b--system-service-exception.md @@ -0,0 +1,102 @@ +--- +title: Bug Check 0x3B SYSTEM_SERVICE_EXCEPTION +description: The SYSTEM_SERVICE_EXCEPTION bug check has a value of 0x0000003B. This indicates that an exception happened while executing a routine that transitions from non-privileged code to privileged code. +ms.assetid: 0e2c230e-d942-4f32-ae8e-7a54aceb4c19 +keywords: ["Bug Check 0x3B SYSTEM_SERVICE_EXCEPTION", "SYSTEM_SERVICE_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_SERVICE_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x3B: SYSTEM\_SERVICE\_EXCEPTION + + +The SYSTEM\_SERVICE\_EXCEPTION bug check has a value of 0x0000003B. This indicates that an exception happened while executing a routine that transitions from non-privileged code to privileged code. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_SERVICE\_EXCEPTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The exception that caused the bug check

2

The address of the instruction that caused the bug check

3

The address of the context record for the exception that caused the bug check

4

0

+ +  + +Cause +----- + +The stop code indicates that executing code had an exception and the thread that was below it, is a system thread. + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md) + +In the past, this error has been linked to excessive paged pool usage and may occur due to user-mode graphics drivers crossing over and passing bad data to the kernel code. If you suspect this is the case, use the pool options in driver verifier to gather additional information. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). You can also set a breakpoint in the code leading up to this stop code and attempt to single step forward into the faulting code. + +For general troubleshooting of Windows bug check codes, follow these suggestions: + +- If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available. + +- If new device drivers or system services have been added recently, try removing or updating them. Try to determine what changed in the system that caused the new bug check code to appear. + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3c--interrupt-unwind-attempted.md b/windows-driver-docs-pr/debugger/bug-check-0x3c--interrupt-unwind-attempted.md new file mode 100644 index 0000000000..ab93719161 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3c--interrupt-unwind-attempted.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x3C INTERRUPT_UNWIND_ATTEMPTED +description: The INTERRUPT_UNWIND_ATTEMPTED bug check has a value of 0x0000003C.This bug check appears very infrequently. +ms.assetid: 000fbbf0-e70e-4d78-a637-0a466bf5c69c +keywords: ["Bug Check 0x3C INTERRUPT_UNWIND_ATTEMPTED", "INTERRUPT_UNWIND_ATTEMPTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INTERRUPT_UNWIND_ATTEMPTED +api_type: +- NA +--- + +# Bug Check 0x3C: INTERRUPT\_UNWIND\_ATTEMPTED + + +The INTERRUPT\_UNWIND\_ATTEMPTED bug check has a value of 0x0000003C. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3d--interrupt-exception-not-handled.md b/windows-driver-docs-pr/debugger/bug-check-0x3d--interrupt-exception-not-handled.md new file mode 100644 index 0000000000..304e70b8d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3d--interrupt-exception-not-handled.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x3D INTERRUPT_EXCEPTION_NOT_HANDLED +description: The INTERRUPT_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000003D.This bug check appears very infrequently. +ms.assetid: 4fcdd7b9-c9be-46b1-aa10-3a31e61e4a6d +keywords: ["Bug Check 0x3D INTERRUPT_EXCEPTION_NOT_HANDLED", "INTERRUPT_EXCEPTION_NOT_HANDLED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INTERRUPT_EXCEPTION_NOT_HANDLED +api_type: +- NA +--- + +# Bug Check 0x3D: INTERRUPT\_EXCEPTION\_NOT\_HANDLED + + +The INTERRUPT\_EXCEPTION\_NOT\_HANDLED bug check has a value of 0x0000003D. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3e--multiprocessor-configuration-not-supported.md b/windows-driver-docs-pr/debugger/bug-check-0x3e--multiprocessor-configuration-not-supported.md new file mode 100644 index 0000000000..f0fba0fb73 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3e--multiprocessor-configuration-not-supported.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0x3E MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED +description: The MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED bug check has a value of 0x0000003E. This indicates that the system has multiple processors, but they are asymmetric in relation to one another. +ms.assetid: 187da73d-0d8a-4e25-9668-229539758f9c +keywords: ["Bug Check 0x3E MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED", "MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED +api_type: +- NA +--- + +# Bug Check 0x3E: MULTIPROCESSOR\_CONFIGURATION\_NOT\_SUPPORTED + + +The MULTIPROCESSOR\_CONFIGURATION\_NOT\_SUPPORTED bug check has a value of 0x0000003E. This indicates that the system has multiple processors, but they are asymmetric in relation to one another. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MULTIPROCESSOR\_CONFIGURATION\_NOT\_SUPPORTED Parameters + + +None + +Cause +----- + +In order to be symmetric, all processors must be of the same type and level. This system contains processors of different types (for example, a Pentium processor and an 80486 processor). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x3f--no-more-system-ptes.md b/windows-driver-docs-pr/debugger/bug-check-0x3f--no-more-system-ptes.md new file mode 100644 index 0000000000..d6d4193390 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x3f--no-more-system-ptes.md @@ -0,0 +1,114 @@ +--- +title: Bug Check 0x3F NO_MORE_SYSTEM_PTES +description: The NO_MORE_SYSTEM_PTES bug check has a value of 0x0000003F. This is the result of a system which has performed too many I/O actions. +ms.assetid: b8164ec3-87c3-4629-ab70-6addbf368b76 +keywords: ["Bug Check 0x3F NO_MORE_SYSTEM_PTES", "NO_MORE_SYSTEM_PTES"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_MORE_SYSTEM_PTES +api_type: +- NA +--- + +# Bug Check 0x3F: NO\_MORE\_SYSTEM\_PTES + + +The NO\_MORE\_SYSTEM\_PTES bug check has a value of 0x0000003F. This is the result of a system which has performed too many I/O actions. This has resulted in fragmented system page table entries (PTE). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NO\_MORE\_SYSTEM\_PTES Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

0: system expansion PTE type

+

1: nonpaged pool expansion PTE type

2

Size of memory request

3

Total free system PTEs

4

Total system PTEs

+ +  + +Cause +----- + +In almost all cases, the system is not actually out of PTEs. Rather, a driver has requested a large block of memory, but there is no contiguous block of sufficient size to satisfy this request. + +Often video drivers will allocate large amounts of kernel memory that must succeed. Some backup programs do the same. + +Resolution +---------- + +**A possible work-around:** Modify the registry to increase the total number of system PTEs. If this does not help, remove any recently-installed software, especially backup utilities or disk-intensive applications. + +**Debugging the problem:** The following method can be used to debug bug check 0x3F. + +First, get a stack trace, and use the [**!sysptes 3**](-sysptes.md) extension command. + +Then set **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management\\TrackPtes** equal to DWORD 1, and reboot. This will cause the system to save stack traces. + +This allows you to display more detailed information about the PTE owners. For example: + +``` +0: kd> !sysptes 4 + +0x2c47 System PTEs allocated to mapping locked pages + +VA MDL PageCount Caller/CallersCaller +f0e5db48 eb6ceef0 1 ntkrpamp!MmMapLockedPages+0x15/ntkrpamp!IopfCallDriver+0x35 +f0c3fe48 eb634bf0 1 netbt!NbtTdiAssociateConnection+0x1f/netbt!DelayedNbtProcessConnect+0x17c +f0db38e8 eb65b880 1 mrxsmb!SmbMmAllocateSessionEntry+0x89/mrxsmb!SmbCepInitializeExchange+0xda +f8312568 eb6df880 1 rdbss!RxCreateFromNetRoot+0x3d7/rdbss!RxCreateFromNetRoot+0x93 +f8363908 eb685880 1 mrxsmb!SmbMmAllocateSessionEntry+0x89/mrxsmb!SmbCepInitializeExchange+0xda +f0c54248 eb640880 1 rdbss!RxCreateFromNetRoot+0x3d7/rdbss!RxCreateFromNetRoot+0x93 +f0ddf448 eb5f3160 1 mrxsmb!MrxSmbUnalignedDirEntryCopyTail+0x387/mrxsmb!MRxSmbCoreInformation+0x36 +f150bc08 eb6367b0 1 mrxsmb!MrxSmbUnalignedDirEntryCopyTail+0x387/mrxsmb!MRxSmbCoreInformation+0x36 +f1392308 eb6fba70 1 netbt!NbtTdiOpenAddress+0x1fb/netbt!DelayedNbtProcessConnect+0x17c +eb1bee64 edac5000 200 VIDEOPRT!pVideoPortGetDeviceBase+0x118/VIDEOPRT!VideoPortMapMemory+0x45 +f139b5a8 edd4b000 12 rdbss!FsRtlCopyWrite2+0x34/rdbss!RxDriverEntry+0x149 +eb41f400 ede92000 20 VIDEOPRT!pVideoPortGetDeviceBase+0x139/VIDEOPRT!VideoPortGetDeviceBase+0x1b +eb41f198 edf2a000 20 NDIS!NdisReadNetworkAddress+0x3a/NDIS!NdisFreeSharedMemory+0x58 +eb41f1e4 eb110000 10 VIDEOPRT!pVideoPortGetDeviceBase+0x139/VIDEOPRT!VideoPortGetDeviceBase+0x1b +...... +``` + +If the system runs out of PTEs again after the **TrackPtes** registry value has been set, [**bug check 0xD8**](bug-check-0xd8--driver-used-excessive-ptes.md) (DRIVER\_USED\_EXCESSIVE\_PTES) will be issued instead of 0x3F. The name of the driver causing this error will be displayed as well. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4--invalid-data-access-trap.md b/windows-driver-docs-pr/debugger/bug-check-0x4--invalid-data-access-trap.md new file mode 100644 index 0000000000..cf1e9069aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4--invalid-data-access-trap.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x4 INVALID_DATA_ACCESS_TRAP +description: The INVALID_DATA_ACCESS_TRAP bug check has a value of 0x00000004.This bug check appears very infrequently. +ms.assetid: 98c7052d-37ff-4ad8-b9c4-afa4226ed1b0 +keywords: ["Bug Check 0x4 INVALID_DATA_ACCESS_TRAP", "INVALID_DATA_ACCESS_TRAP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_DATA_ACCESS_TRAP +api_type: +- NA +--- + +# Bug Check 0x4: INVALID\_DATA\_ACCESS\_TRAP + + +The INVALID\_DATA\_ACCESS\_TRAP bug check has a value of 0x00000004. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x40--target-mdl-too-small.md b/windows-driver-docs-pr/debugger/bug-check-0x40--target-mdl-too-small.md new file mode 100644 index 0000000000..a99c999458 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x40--target-mdl-too-small.md @@ -0,0 +1,47 @@ +--- +title: Bug Check 0x40 TARGET_MDL_TOO_SMALL +description: The TARGET_MDL_TOO_SMALL bug check has a value of 0x00000040. This indicates that a driver has improperly used IoBuildPartialMdl. +ms.assetid: bd154c1f-6c74-424e-bc32-22c9a93efae5 +keywords: ["Bug Check 0x40 TARGET_MDL_TOO_SMALL", "TARGET_MDL_TOO_SMALL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TARGET_MDL_TOO_SMALL +api_type: +- NA +--- + +# Bug Check 0x40: TARGET\_MDL\_TOO\_SMALL + + +The TARGET\_MDL\_TOO\_SMALL bug check has a value of 0x00000040. This indicates that a driver has improperly used **IoBuildPartialMdl**. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TARGET\_MDL\_TOO\_SMALL Parameters + + +None + +Cause +----- + +This is a driver bug. A driver has called the **IoBuildPartialMdl** function and passed it an MDL to map part of a source MDL, but the target MDL is not large enough to map the entire range of addresses requested. + +Resolution +---------- + +The source and target MDLs, as well as the address range length to be mapped, are the first, second, and fourth arguments to the **IoBuildPartialMdl** function. Therefore, doing a stack trace on this particular function might help during the debugging process. Ensure that your code is correctly calculating the necessary size for the target MDL for the address range length that you are passing to this function. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4000008a--thread-terminate-held-mutex.md b/windows-driver-docs-pr/debugger/bug-check-0x4000008a--thread-terminate-held-mutex.md new file mode 100644 index 0000000000..3a21fa9593 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4000008a--thread-terminate-held-mutex.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x4000008A THREAD_TERMINATE_HELD_MUTEX +description: The THREAD_TERMINATE_HELD_MUTEX bug check has a value of 0x4000008A. +ms.assetid: 30A796F0-D622-43F2-8050-C9B62941FBE9 +keywords: ["Bug Check 0x4000008A THREAD_TERMINATE_HELD_MUTEX", "THREAD_TERMINATE_HELD_MUTEX"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- THREAD_TERMINATE_HELD_MUTEX +api_type: +- NA +--- + +# Bug Check 0x4000008A: THREAD\_TERMINATE\_HELD\_MUTEX + + +The THREAD\_TERMINATE\_HELD\_MUTEX bug check has a value of 0x4000008A. This indicates that a driver acquired a mutex on a thread that exited before the mutex could be released. This can be caused by a driver returning to user mode without releasing a mutex or by a driver acquiring a mutex and then causing an exception that results in the thread it is running on, being terminated. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## THREAD\_TERMINATE\_HELD\_MUTEX Parameters + + +| Parameter | Description | +|-----------|--------------------------------------------------| +| 1 | The address of the KTHREAD that owns the KMUTEX. | +| 2 | The address of the KMUTEX that is owned. | +| 3 | Reserved | +| 4 | Reserved | + +  + +Cause +----- + +To investigate, look at the callstack. If there is a driver on the stack that is directly followed by system exception handling routines and then thread termination routines, this driver is at fault and needs to be fixed so that it does not cause an unhandled exception while holding a kernel mutex. If the stack just shows normal thread termination code and no driver is implicated, run [**!pool**](-pool.md) or use [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) on the address of the mutex (parameter 2) and see if you can discover who owns the it. This bug will almost certainly be in the code of the owner of that mutex. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x41--must-succeed-pool-empty.md b/windows-driver-docs-pr/debugger/bug-check-0x41--must-succeed-pool-empty.md new file mode 100644 index 0000000000..9a3cbb0ba1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x41--must-succeed-pool-empty.md @@ -0,0 +1,84 @@ +--- +title: Bug Check 0x41 MUST_SUCCEED_POOL_EMPTY +description: The MUST_SUCCEED_POOL_EMPTY bug check has a value of 0x00000041. This indicates that a kernel-mode thread has requested too much must-succeed pool. +ms.assetid: 10aafcf4-6af0-41b5-803c-578369bdd810 +keywords: ["Bug Check 0x41 MUST_SUCCEED_POOL_EMPTY", "MUST_SUCCEED_POOL_EMPTY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MUST_SUCCEED_POOL_EMPTY +api_type: +- NA +--- + +# Bug Check 0x41: MUST\_SUCCEED\_POOL\_EMPTY + + +The MUST\_SUCCEED\_POOL\_EMPTY bug check has a value of 0x00000041. This indicates that a kernel-mode thread has requested too much must-succeed pool. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MUST\_SUCCEED\_POOL\_EMPTY Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The size of the request that could not be satisfied

2

The number of pages used from nonpaged pool

3

The number of requests from nonpaged pool larger than PAGE_SIZE

4

The number of pages available

+ +  + +Cause +----- + +In Microsoft Windows 2000, only a small amount of must-succeed pool is permitted. In Windows XP and later, no driver is permitted to request must-succeed pool. + +If a must-succeed request cannot be filled, this bug check is issued. + +Resolution +---------- + +Replace or rewrite the driver which is making the request. A driver should not request must-succeed pool. Instead, it should ask for normal pool and gracefully handle the scenario where the pool is temporarily empty. + +The [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command will show the driver that caused the error. + +Additionally, it is possible that a second component has depleted the must-succeed pool. To determine if this is the case, first use the **kb** command. Then use [**!vm 1**](-vm.md) to display total pool usage, [**!poolused 2**](-poolused.md) to display per-tag nonpaged pool usage, and **!poolused 4** to display per-tag paged pool usage. The component associated with the tag using the most pool is probably the source of the problem. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x42--atdisk-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0x42--atdisk-driver-internal.md new file mode 100644 index 0000000000..320f12ffa6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x42--atdisk-driver-internal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x42 ATDISK_DRIVER_INTERNAL +description: The ATDISK_DRIVER_INTERNAL bug check has a value of 0x00000042.This bug check appears very infrequently. +ms.assetid: 422c8fc9-e980-4879-abf7-d30c69086069 +keywords: ["Bug Check 0x42 ATDISK_DRIVER_INTERNAL", "ATDISK_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ATDISK_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0x42: ATDISK\_DRIVER\_INTERNAL + + +The ATDISK\_DRIVER\_INTERNAL bug check has a value of 0x00000042. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x43--no-such-partition.md b/windows-driver-docs-pr/debugger/bug-check-0x43--no-such-partition.md new file mode 100644 index 0000000000..92464265bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x43--no-such-partition.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x43 NO_SUCH_PARTITION +description: The NO_SUCH_PARTITION bug check has a value of 0x00000043.This bug check appears very infrequently. +ms.assetid: cf0888c7-633a-4df4-afce-bec6a0205fac +keywords: ["Bug Check 0x43 NO_SUCH_PARTITION", "NO_SUCH_PARTITION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_SUCH_PARTITION +api_type: +- NA +--- + +# Bug Check 0x43: NO\_SUCH\_PARTITION + + +The NO\_SUCH\_PARTITION bug check has a value of 0x00000043. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x44--multiple-irp-complete-requests.md b/windows-driver-docs-pr/debugger/bug-check-0x44--multiple-irp-complete-requests.md new file mode 100644 index 0000000000..4f892941d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x44--multiple-irp-complete-requests.md @@ -0,0 +1,80 @@ +--- +title: Bug Check 0x44 MULTIPLE_IRP_COMPLETE_REQUESTS +description: The MULTIPLE_IRP_COMPLETE_REQUESTS bug check has a value of 0x00000044. This indicates that a driver has tried to request an IRP be completed that is already complete. +ms.assetid: bc60b4b3-aded-4c67-bbaa-aad1b6b38d30 +keywords: ["Bug Check 0x44 MULTIPLE_IRP_COMPLETE_REQUESTS", "MULTIPLE_IRP_COMPLETE_REQUESTS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MULTIPLE_IRP_COMPLETE_REQUESTS +api_type: +- NA +--- + +# Bug Check 0x44: MULTIPLE\_IRP\_COMPLETE\_REQUESTS + + +The MULTIPLE\_IRP\_COMPLETE\_REQUESTS bug check has a value of 0x00000044. This indicates that a driver has tried to request an IRP be completed that is already complete. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MULTIPLE\_IRP\_COMPLETE\_REQUESTS Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the IRP

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +A driver has called **IoCompleteRequest** to ask that an IRP be completed, but the packet has already been completed. + +Resolution +---------- + +This is a tough bug to find because the simplest case -- a driver that attempted to complete its own packet twice -- is usually not the source of the problem. More likely, two separate drivers each believe that they own the packet, and each has attempted to complete it. The first request succeeds, and the second fails, resulting in this bug check. + +Tracking down which drivers in the system caused the error is difficult, because the trail of the first driver has been covered by the second. However, the driver stack for the current request can be found by examining the device object fields in each of the stack locations. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x45--insufficient-system-map-regs.md b/windows-driver-docs-pr/debugger/bug-check-0x45--insufficient-system-map-regs.md new file mode 100644 index 0000000000..9b9c1671f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x45--insufficient-system-map-regs.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x45 INSUFFICIENT_SYSTEM_MAP_REGS +description: The INSUFFICIENT_SYSTEM_MAP_REGS bug check has a value of 0x00000045.This bug check appears very infrequently. +ms.assetid: fc01b455-a0b5-4d25-a115-076c227ed303 +keywords: ["Bug Check 0x45 INSUFFICIENT_SYSTEM_MAP_REGS", "INSUFFICIENT_SYSTEM_MAP_REGS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INSUFFICIENT_SYSTEM_MAP_REGS +api_type: +- NA +--- + +# Bug Check 0x45: INSUFFICIENT\_SYSTEM\_MAP\_REGS + + +The INSUFFICIENT\_SYSTEM\_MAP\_REGS bug check has a value of 0x00000045. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x46--deref-unknown-logon-session.md b/windows-driver-docs-pr/debugger/bug-check-0x46--deref-unknown-logon-session.md new file mode 100644 index 0000000000..bb91def0cc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x46--deref-unknown-logon-session.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x46 DEREF_UNKNOWN_LOGON_SESSION +description: The DEREF_UNKNOWN_LOGON_SESSION bug check has a value of 0x00000046.This bug check appears very infrequently. +ms.assetid: 17c7995f-051e-43b7-99f2-69aa2d968cef +keywords: ["Bug Check 0x46 DEREF_UNKNOWN_LOGON_SESSION", "DEREF_UNKNOWN_LOGON_SESSION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DEREF_UNKNOWN_LOGON_SESSION +api_type: +- NA +--- + +# Bug Check 0x46: DEREF\_UNKNOWN\_LOGON\_SESSION + + +The DEREF\_UNKNOWN\_LOGON\_SESSION bug check has a value of 0x00000046. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x47--ref-unknown-logon-session.md b/windows-driver-docs-pr/debugger/bug-check-0x47--ref-unknown-logon-session.md new file mode 100644 index 0000000000..3e0b680fea --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x47--ref-unknown-logon-session.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x47 REF_UNKNOWN_LOGON_SESSION +description: The REF_UNKNOWN_LOGON_SESSION bug check has a value of 0x00000047.This bug check appears very infrequently. +ms.assetid: 9d3ddc84-f17d-4760-b1e1-7153048a77ea +keywords: ["Bug Check 0x47 REF_UNKNOWN_LOGON_SESSION", "REF_UNKNOWN_LOGON_SESSION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REF_UNKNOWN_LOGON_SESSION +api_type: +- NA +--- + +# Bug Check 0x47: REF\_UNKNOWN\_LOGON\_SESSION + + +The REF\_UNKNOWN\_LOGON\_SESSION bug check has a value of 0x00000047. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x48--cancel-state-in-completed-irp.md b/windows-driver-docs-pr/debugger/bug-check-0x48--cancel-state-in-completed-irp.md new file mode 100644 index 0000000000..32daefe7d9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x48--cancel-state-in-completed-irp.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0x48 CANCEL_STATE_IN_COMPLETED_IRP +description: The CANCEL_STATE_IN_COMPLETED_IRP bug check has a value of 0x00000048. This indicates that an I/O request packet (IRP) was completed, and then was subsequently canceled. +ms.assetid: e706cf9b-8800-41ce-9bad-e4b9a8503051 +keywords: ["Bug Check 0x48 CANCEL_STATE_IN_COMPLETED_IRP", "CANCEL_STATE_IN_COMPLETED_IRP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CANCEL_STATE_IN_COMPLETED_IRP +api_type: +- NA +--- + +# Bug Check 0x48: CANCEL\_STATE\_IN\_COMPLETED\_IRP + + +The CANCEL\_STATE\_IN\_COMPLETED\_IRP bug check has a value of 0x00000048. This indicates that an I/O request packet (IRP) was completed, and then was subsequently canceled. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CANCEL\_STATE\_IN\_COMPLETED\_IRP Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

A pointer to the IRP

2

The cancel routine set by the driver

3

Reserved

4

Reserved

+ +  + +Cause +----- + +An IRP that had a *Cancel* routine set was completed normally, without cancellation. But after it was complete, a driver called the IRP's *Cancel* routine. + +This could be caused by a driver that completed the IRP and then attempted to cancel it. + +It could also be caused by two drivers each trying to access the same IRP in an improper way. + +Resolution +---------- + +The cancel routine parameter can be used to determine which driver or stack caused the bug check. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x49--page-fault-with-interrupts-off.md b/windows-driver-docs-pr/debugger/bug-check-0x49--page-fault-with-interrupts-off.md new file mode 100644 index 0000000000..50b515e939 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x49--page-fault-with-interrupts-off.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x49 PAGE_FAULT_WITH_INTERRUPTS_OFF +description: The PAGE_FAULT_WITH_INTERRUPTS_OFF bug check has a value of 0x00000049.This bug check appears very infrequently. +ms.assetid: c7fa7d00-7702-4f2b-9c71-886861259092 +keywords: ["Bug Check 0x49 PAGE_FAULT_WITH_INTERRUPTS_OFF", "PAGE_FAULT_WITH_INTERRUPTS_OFF"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PAGE_FAULT_WITH_INTERRUPTS_OFF +api_type: +- NA +--- + +# Bug Check 0x49: PAGE\_FAULT\_WITH\_INTERRUPTS\_OFF + + +The PAGE\_FAULT\_WITH\_INTERRUPTS\_OFF bug check has a value of 0x00000049. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4a--irql-gt-zero-at-system-service.md b/windows-driver-docs-pr/debugger/bug-check-0x4a--irql-gt-zero-at-system-service.md new file mode 100644 index 0000000000..5644914da6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4a--irql-gt-zero-at-system-service.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x4A IRQL_GT_ZERO_AT_SYSTEM_SERVICE +description: The IRQL_GT_ZERO_AT_SYSTEM_SERVICE bug check has a value of 0x0000004A. This indicates that a thread is returning to user mode from a system call when its IRQL is still above PASSIVE_LEVEL. +ms.assetid: 0da64630-d446-426a-a51f-34117fe9daa7 +keywords: ["Bug Check 0x4A IRQL_GT_ZERO_AT_SYSTEM_SERVICE", "IRQL_GT_ZERO_AT_SYSTEM_SERVICE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IRQL_GT_ZERO_AT_SYSTEM_SERVICE +api_type: +- NA +--- + +# Bug Check 0x4A: IRQL\_GT\_ZERO\_AT\_SYSTEM\_SERVICE + + +The IRQL\_GT\_ZERO\_AT\_SYSTEM\_SERVICE bug check has a value of 0x0000004A. This indicates that a thread is returning to user mode from a system call when its IRQL is still above PASSIVE\_LEVEL. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IRQL\_GT\_ZERO\_AT\_SYSTEM\_SERVICE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the system function (system call routine)

2

The current IRQL

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4b--streams-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x4b--streams-internal-error.md new file mode 100644 index 0000000000..5affd9577d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4b--streams-internal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x4B STREAMS_INTERNAL_ERROR +description: The STREAMS_INTERNAL_ERROR bug check has a value of 0x0000004B.This bug check appears very infrequently. +ms.assetid: 6c1222c7-448c-4a99-be30-cf2c43c41cb9 +keywords: ["Bug Check 0x4B STREAMS_INTERNAL_ERROR", "STREAMS_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- STREAMS_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x4B: STREAMS\_INTERNAL\_ERROR + + +The STREAMS\_INTERNAL\_ERROR bug check has a value of 0x0000004B. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4c--fatal-unhandled-hard-error.md b/windows-driver-docs-pr/debugger/bug-check-0x4c--fatal-unhandled-hard-error.md new file mode 100644 index 0000000000..e23ececf4b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4c--fatal-unhandled-hard-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x4C FATAL_UNHANDLED_HARD_ERROR +description: The FATAL_UNHANDLED_HARD_ERROR bug check has a value of 0x0000004C.This bug check appears very infrequently. +ms.assetid: 39ecd06b-1522-4b87-bfd8-a0022e3a6861 +keywords: ["Bug Check 0x4C FATAL_UNHANDLED_HARD_ERROR", "FATAL_UNHANDLED_HARD_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FATAL_UNHANDLED_HARD_ERROR +api_type: +- NA +--- + +# Bug Check 0x4C: FATAL\_UNHANDLED\_HARD\_ERROR + + +The FATAL\_UNHANDLED\_HARD\_ERROR bug check has a value of 0x0000004C. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4d--no-pages-available.md b/windows-driver-docs-pr/debugger/bug-check-0x4d--no-pages-available.md new file mode 100644 index 0000000000..d32b71dbad --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4d--no-pages-available.md @@ -0,0 +1,101 @@ +--- +title: Bug Check 0x4D NO_PAGES_AVAILABLE +description: The NO_PAGES_AVAILABLE bug check has a value of 0x0000004D. This indicates that no free pages are available to continue operations. +ms.assetid: c1f8fb33-a01c-4455-87a7-59aa6ba7cb37 +keywords: ["Bug Check 0x4D NO_PAGES_AVAILABLE", "NO_PAGES_AVAILABLE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_PAGES_AVAILABLE +api_type: +- NA +--- + +# Bug Check 0x4D: NO\_PAGES\_AVAILABLE + + +The NO\_PAGES\_AVAILABLE bug check has a value of 0x0000004D. This indicates that no free pages are available to continue operations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NO\_PAGES\_AVAILABLE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The total number of dirty pages

2

The number of dirty pages destined for the page file

3

Windows XP and Windows 2000: The size of the nonpaged pool available at the time the bug check occurred

+

Windows Server 2003 and later: Reserved

4

Windows 2000: The number of transition pages that are currently stranded

+

Windows XP and later: The most recent modified write error status.

+ +  + +Cause +----- + +To see general memory statistics, use the [**!vm 3**](-vm.md) extension. + +This bug check can occur for any of the following reasons: + +- A driver has blocked, deadlocking the modified or mapped page writers. Examples of this include mutex deadlocks or accesses to paged out memory in file system drivers or filter drivers. This indicates a driver bug. + + If Parameter 1 or Parameter 2 is large, then this is a possibility. Use [**!vm 3**](-vm.md). + +- A storage driver is not processing requests. Examples of this are stranded queues and non-responding drives. This indicates a driver bug. + + If Parameter 1 or Parameter 2 is large, then this is a possibility. Use [**!vm 8**](-vm.md), followed by [**!process 0 7**](-process.md). + +- A high-priority realtime thread has starved the balance set manager from trimming pages from the working set, or starved the modified page writer from writing them out. This indicates a bug in the component that created this thread. + + This situation is difficult to analyze. Try using [**!ready**](-ready.md). Try also [**!process 0 7**](-process.md) to list all threads and see if any have accumulated excessive kernel time as well as what their current priorities are. Such processes may have blocked out the memory management threads from making pages available. + +- **Windows XP and Windows 2000:** Not enough pool is available for the storage stack to write out modified pages. This indicates a driver bug. + + If Parameter 3 is small, then this is a possibility. Use [**!vm**](-vm.md) and [**!poolused 2**](-poolused.md). + +- **Windows 2000:** All the processes have been trimmed to their minimums and all modified pages written, but still no memory is available. The freed memory must be stuck in transition pages with non-zero reference counts -- thus they cannot be put on the freelist. + + A driver is neglecting to unlock the pages preventing the reference counts from going to zero which would free the pages. This may be due to transfers that never finish, causing the driver routines to run endlessly, or to other driver bugs. + + If Parameter 4 is large, then this is a possibility. But it is very hard to find the driver. Try the [**!process 0 1**](-process.md) extension and look for any drivers that have a lot of locked pages. + +If the problem cannot be found, then try booting with a kernel debugger attached from the beginning, and monitor the situation. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4e--pfn-list-corrupt.md b/windows-driver-docs-pr/debugger/bug-check-0x4e--pfn-list-corrupt.md new file mode 100644 index 0000000000..cc5361fc66 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4e--pfn-list-corrupt.md @@ -0,0 +1,116 @@ +--- +title: Bug Check 0x4E PFN_LIST_CORRUPT +description: The PFN_LIST_CORRUPT bug check has a value of 0x0000004E. This indicates that the page frame number (PFN) list is corrupted. +ms.assetid: cf78aecb-80d3-4637-a2b5-a2511999c5e3 +keywords: ["Bug Check 0x4E PFN_LIST_CORRUPT", "PFN_LIST_CORRUPT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PFN_LIST_CORRUPT +api_type: +- NA +--- + +# Bug Check 0x4E: PFN\_LIST\_CORRUPT + + +The PFN\_LIST\_CORRUPT bug check has a value of 0x0000004E. This indicates that the page frame number (PFN) list is corrupted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PFN\_LIST\_CORRUPT Parameters + + +*Parameter 1* indicates the type of violation. The meaning of the other parameters depends on the value of *Parameter 1*. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x01

The ListHead value that was corrupted

The number of pages available

0

The list head was corrupted.

0x02

The entry in the list that is being removed

The highest physical page number

The reference count of the entry being removed

A list entry was corrupted.

0x07

The page frame number

The current share count

0

A driver has unlocked a certain page more times than it locked it.

0x8D

The page frame number whose state is inconsistent

0

0

The page-free list is corrupted. This error code most likely indicates a hardware issue.

0x8F

New page number

Old page number

0

The free or zeroed page listhead is corrupted.

0x99

Page frame number

Current page state

0

A page table entry (PTE) or PFN is corrupted.

0x9A

Page frame number

Current page state

The reference count of the entry that is being removed

A driver attempted to free a page that is still locked for IO.

+ +  + +Cause +----- + +This error is typically caused by a driver passing a bad memory descriptor list. For example, the driver might have called **MmUnlockPages** twice with the same list. + +If a kernel debugger is available, examine the stack trace. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x4f--ndis-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x4f--ndis-internal-error.md new file mode 100644 index 0000000000..0f76417f18 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x4f--ndis-internal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x4F NDIS_INTERNAL_ERROR +description: The NDIS_INTERNAL_ERROR bug check has a value of 0x0000004F.This bug check appears very infrequently. +ms.assetid: e71916b3-3bb5-4595-a333-81ed2785b495 +keywords: ["Bug Check 0x4F NDIS_INTERNAL_ERROR", "NDIS_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NDIS_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x4F: NDIS\_INTERNAL\_ERROR + + +The NDIS\_INTERNAL\_ERROR bug check has a value of 0x0000004F. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5--invalid-process-attach-attempt.md b/windows-driver-docs-pr/debugger/bug-check-0x5--invalid-process-attach-attempt.md new file mode 100644 index 0000000000..36ce6a6da7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5--invalid-process-attach-attempt.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0x5 INVALID_PROCESS_ATTACH_ATTEMPT +description: The INVALID_PROCESS_ATTACH_ATTEMPT bug check has a value of 0x00000005. +ms.assetid: 72efb88f-1bf7-4552-b44e-4ecb04754b7d +keywords: ["Bug Check 0x5 INVALID_PROCESS_ATTACH_ATTEMPT", "INVALID_PROCESS_ATTACH_ATTEMPT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_PROCESS_ATTACH_ATTEMPT +api_type: +- NA +--- + +# Bug Check 0x5: INVALID\_PROCESS\_ATTACH\_ATTEMPT + + +The INVALID\_PROCESS\_ATTACH\_ATTEMPT bug check has a value of 0x00000005. This generally indicates that the thread was attached to a process in a situation where that is not allowed. For example, this bug check could occur if **KeAttachProcess** was called when the thread was already attached to a process (which is illegal), or if the thread returned from certain function calls in an attached state (which is invalid), + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_PROCESS\_ATTACH\_ATTEMPT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The pointer to the dispatcher object for the target process, or if the thread is already attached, the pointer to the object for the original process.

2

The pointer to the dispatcher object of the process that the current thread is currently attached to.

3

The value of the thread's APC state index.

4

A non-zero value indicates that a DPC is running on the current processor.

+ +  + +Remarks +------- + +This bug check can occur if the driver calls the **KeAttachProcess** function and the thread is already attached to another process. It is better to use the **KeStackAttachProcess** function. If the current thread was already attached to another process, the **KeStackAttachProcess** function saves the current APC state before it attaches the current thread to the new process. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x50--page-fault-in-nonpaged-area.md b/windows-driver-docs-pr/debugger/bug-check-0x50--page-fault-in-nonpaged-area.md new file mode 100644 index 0000000000..9202dfcd5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x50--page-fault-in-nonpaged-area.md @@ -0,0 +1,110 @@ +--- +title: Bug Check 0x50 PAGE_FAULT_IN_NONPAGED_AREA +description: The PAGE_FAULT_IN_NONPAGED_AREA bug check has a value of 0x00000050. This indicates that invalid system memory has been referenced. +ms.assetid: 63b4ab82-f7a9-4e14-bf7c-707a22d7e251 +keywords: ["Bug Check 0x50 PAGE_FAULT_IN_NONPAGED_AREA", "PAGE_FAULT_IN_NONPAGED_AREA"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PAGE_FAULT_IN_NONPAGED_AREA +api_type: +- NA +--- + +# Bug Check 0x50: PAGE\_FAULT\_IN\_NONPAGED\_AREA + + +The PAGE\_FAULT\_IN\_NONPAGED\_AREA bug check has a value of 0x00000050. This indicates that invalid system memory has been referenced. Typically the memory address is wrong or the memory address is pointing at freed memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PAGE\_FAULT\_IN\_NONPAGED\_AREA Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read operation

+

1: Write operation

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +Bug check 0x50 can occur after the installation of faulty hardware or in the event of failure of installed hardware (usually related to defective RAM, be it main memory, L2 RAM cache, or video RAM). + +Another possible cause is the installation of a faulty system service or faulty driver code. + +Antivirus software can also trigger this error, as can a corrupted NTFS volume. + +Resolution +---------- + +**Gather Information** + +Examine the name of the driver if that was listed on the blue screen. + +Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +**Windows Memory Diagnostics** + +Run the Windows Memory Diagnostics tool, to test the memory. Click the Start button, and then clicking Control Panel. In the search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +**Resolving a faulty hardware problem:** If hardware has been added to the system recently, remove it to see if the error recurs. If existing hardware has failed, remove or replace the faulty component. You should run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. + +**Resolving a faulty system service problem:** Disable the service and confirm that this resolves the error. If so, contact the manufacturer of the system service about a possible update. If the error occurs during system startup, investigate the Windows repair options. For more information, see [Recovery options in Windows 10](http://windows.microsoft.com/windows-10/windows-10-recovery-options). + +**Resolving an antivirus software problem:** Disable the program and confirm that this resolves the error. If it does, contact the manufacturer of the program about a possible update. + +**Resolving a corrupted NTFS volume problem:** Run **Chkdsk /f /r** to detect and repair disk errors. You must restart the system before the disk scan begins on a system partition. Contact the manufacture of the hard driver system to locate any diagnostic tools that they provide for the hard drive sub system. + +For general blue screen troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +Remarks +------- + +Typically, this address is in freed memory or is simply invalid. + +This cannot be protected by a **try - except** handler -- it can only be protected by a probe. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x51--registry-error.md b/windows-driver-docs-pr/debugger/bug-check-0x51--registry-error.md new file mode 100644 index 0000000000..6367d22733 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x51--registry-error.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x51 REGISTRY_ERROR +description: The REGISTRY_ERROR bug check has a value of 0x00000051. This indicates that a severe registry error has occurred. +ms.assetid: 286e462f-e4d4-408f-91ad-3e20336e2025 +keywords: ["Bug Check 0x51 REGISTRY_ERROR", "REGISTRY_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REGISTRY_ERROR +api_type: +- NA +--- + +# Bug Check 0x51: REGISTRY\_ERROR + + +The REGISTRY\_ERROR bug check has a value of 0x00000051. This indicates that a severe registry error has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## REGISTRY\_ERROR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Reserved

2

Reserved

3

The pointer to the hive (if available)

4

If the hive is corrupt, the return code of HvCheckHive (if available)

+ +  + +Cause +----- + +Something has gone wrong with the registry. If a kernel debugger is available, get a stack trace. + +This error may indicate that the registry encountered an I/O error while trying to read one of its files. This can be caused by hardware problems or file system corruption. + +It may also occur due to a failure in a refresh operation, which is used only in by the security system, and then only when resource limits are encountered. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x52--mailslot-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x52--mailslot-file-system.md new file mode 100644 index 0000000000..d8f78c65b5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x52--mailslot-file-system.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x52 MAILSLOT_FILE_SYSTEM +description: The MAILSLOT_FILE_SYSTEM bug check has a value of 0x00000052.This bug check appears very infrequently. +ms.assetid: 9596eea9-d19e-4e67-b7a3-0d6b7fd34f17 +keywords: ["Bug Check 0x52 MAILSLOT_FILE_SYSTEM", "MAILSLOT_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MAILSLOT_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x52: MAILSLOT\_FILE\_SYSTEM + + +The MAILSLOT\_FILE\_SYSTEM bug check has a value of 0x00000052. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x53--no-boot-device.md b/windows-driver-docs-pr/debugger/bug-check-0x53--no-boot-device.md new file mode 100644 index 0000000000..adaf93f76c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x53--no-boot-device.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x53 NO_BOOT_DEVICE +description: The NO_BOOT_DEVICE bug check has a value of 0x00000053.This bug check appears very infrequently. +ms.assetid: 4713be6e-fcf4-4fcc-8a50-76af9fd1d5af +keywords: ["Bug Check 0x53 NO_BOOT_DEVICE", "NO_BOOT_DEVICE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_BOOT_DEVICE +api_type: +- NA +--- + +# Bug Check 0x53: NO\_BOOT\_DEVICE + + +The NO\_BOOT\_DEVICE bug check has a value of 0x00000053. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x54--lm-server-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x54--lm-server-internal-error.md new file mode 100644 index 0000000000..045be02e40 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x54--lm-server-internal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x54 LM_SERVER_INTERNAL_ERROR +description: The LM_SERVER_INTERNAL_ERROR bug check has a value of 0x00000054.This bug check appears very infrequently. +ms.assetid: fb39413d-50ba-441a-ab60-4708e59b5e03 +keywords: ["Bug Check 0x54 LM_SERVER_INTERNAL_ERROR", "LM_SERVER_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LM_SERVER_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x54: LM\_SERVER\_INTERNAL\_ERROR + + +The LM\_SERVER\_INTERNAL\_ERROR bug check has a value of 0x00000054. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x55--data-coherency-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x55--data-coherency-exception.md new file mode 100644 index 0000000000..b8eebcf6be --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x55--data-coherency-exception.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x55 DATA_COHERENCY_EXCEPTION +description: The DATA_COHERENCY_EXCEPTION bug check has a value of 0x00000055.This bug check appears very infrequently. +ms.assetid: f7b585ec-5b76-44eb-b3fa-17684152156d +keywords: ["Bug Check 0x55 DATA_COHERENCY_EXCEPTION", "DATA_COHERENCY_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DATA_COHERENCY_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x55: DATA\_COHERENCY\_EXCEPTION + + +The DATA\_COHERENCY\_EXCEPTION bug check has a value of 0x00000055. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x56--instruction-coherency-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x56--instruction-coherency-exception.md new file mode 100644 index 0000000000..76414473db --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x56--instruction-coherency-exception.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x56 INSTRUCTION_COHERENCY_EXCEPTION +description: The INSTRUCTION_COHERENCY_EXCEPTION bug check has a value of 0x00000056.This bug check appears very infrequently. +ms.assetid: 70fea630-9fb2-47e8-a099-9eee8c41b334 +keywords: ["Bug Check 0x56 INSTRUCTION_COHERENCY_EXCEPTION", "INSTRUCTION_COHERENCY_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INSTRUCTION_COHERENCY_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x56: INSTRUCTION\_COHERENCY\_EXCEPTION + + +The INSTRUCTION\_COHERENCY\_EXCEPTION bug check has a value of 0x00000056. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x57--xns-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x57--xns-internal-error.md new file mode 100644 index 0000000000..0e0295f8c4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x57--xns-internal-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x57 XNS_INTERNAL_ERROR +description: The XNS_INTERNAL_ERROR bug check has a value of 0x00000057.This bug check appears very infrequently. +ms.assetid: cb39b78a-69c8-4505-b537-c1d0a986685b +keywords: ["Bug Check 0x57 XNS_INTERNAL_ERROR", "XNS_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- XNS_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x57: XNS\_INTERNAL\_ERROR + + +The XNS\_INTERNAL\_ERROR bug check has a value of 0x00000057. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x58--ftdisk-internal-error.md b/windows-driver-docs-pr/debugger/bug-check-0x58--ftdisk-internal-error.md new file mode 100644 index 0000000000..8527cb7be4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x58--ftdisk-internal-error.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0x58 FTDISK_INTERNAL_ERROR +description: The FTDISK_INTERNAL_ERROR bug check has a value of 0x00000058. This is issued if the system is booted from the wrong copy of a mirrored partition. +ms.assetid: c8de6a04-740d-415e-bf23-b28da066a225 +keywords: ["Bug Check 0x58 FTDISK_INTERNAL_ERROR", "FTDISK_INTERNAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FTDISK_INTERNAL_ERROR +api_type: +- NA +--- + +# Bug Check 0x58: FTDISK\_INTERNAL\_ERROR + + +The FTDISK\_INTERNAL\_ERROR bug check has a value of 0x00000058. This is issued if the system is booted from the wrong copy of a mirrored partition. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FTDISK\_INTERNAL\_ERROR Parameters + + +None + +Cause +----- + +The hives are indicating that the mirror is valid, but it is not. The hives should actually be pointing to the shadow partition. + +This is almost always caused by the primary partition being revived. + +Resolution +---------- + +Reboot the system from the shadow partition. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x59--pinball-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x59--pinball-file-system.md new file mode 100644 index 0000000000..eeee67bb95 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x59--pinball-file-system.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x59 PINBALL_FILE_SYSTEM +description: The PINBALL_FILE_SYSTEM bug check has a value of 0x00000059. This indicates that a problem occurred in the Pinball file system. +ms.assetid: b6b9f2e9-261d-4d4d-b282-41fadd0bf8b3 +keywords: ["Bug Check 0x59 PINBALL_FILE_SYSTEM", "PINBALL_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PINBALL_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x59: PINBALL\_FILE\_SYSTEM + + +The PINBALL\_FILE\_SYSTEM bug check has a value of 0x00000059. This indicates that a problem occurred in the Pinball file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PINBALL\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5a--critical-service-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x5a--critical-service-failed.md new file mode 100644 index 0000000000..851a4a8af2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5a--critical-service-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x5A CRITICAL_SERVICE_FAILED +description: The CRITICAL_SERVICE_FAILED bug check has a value of 0x0000005A.This bug check appears very infrequently. +ms.assetid: 9a0657b0-943b-4c25-bb30-f04377fdaee9 +keywords: ["Bug Check 0x5A CRITICAL_SERVICE_FAILED", "CRITICAL_SERVICE_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRITICAL_SERVICE_FAILED +api_type: +- NA +--- + +# Bug Check 0x5A: CRITICAL\_SERVICE\_FAILED + + +The CRITICAL\_SERVICE\_FAILED bug check has a value of 0x0000005A. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5b--set-env-var-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x5b--set-env-var-failed.md new file mode 100644 index 0000000000..814ce3e23d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5b--set-env-var-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x5B SET_ENV_VAR_FAILED +description: The SET_ENV_VAR_FAILED bug check has a value of 0x0000005B.This bug check appears very infrequently. +ms.assetid: 0161bfca-48d2-4991-b6e0-15c96c167295 +keywords: ["Bug Check 0x5B SET_ENV_VAR_FAILED", "SET_ENV_VAR_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SET_ENV_VAR_FAILED +api_type: +- NA +--- + +# Bug Check 0x5B: SET\_ENV\_VAR\_FAILED + + +The SET\_ENV\_VAR\_FAILED bug check has a value of 0x0000005B. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5c--hal-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x5c--hal-initialization-failed.md new file mode 100644 index 0000000000..959475e1c3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5c--hal-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x5C HAL_INITIALIZATION_FAILED +description: The HAL_INITIALIZATION_FAILED bug check has a value of 0x0000005C.This indicates that the HAL initialization failed. +ms.assetid: 0a62e3d4-40a3-4886-9696-7fa7f50d2c21 +keywords: ["Bug Check 0x5C HAL_INITIALIZATION_FAILED", "HAL_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HAL_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x5C: HAL\_INITIALIZATION\_FAILED + + +The HAL\_INITIALIZATION\_FAILED bug check has a value of 0x0000005C. + +This indicates that the HAL initialization failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5d--unsupported-processor.md b/windows-driver-docs-pr/debugger/bug-check-0x5d--unsupported-processor.md new file mode 100644 index 0000000000..42fab2b83f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5d--unsupported-processor.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0x5D UNSUPPORTED_PROCESSOR +description: The UNSUPPORTED_PROCESSOR bug check has a value of 0x0000005D. This indicates that the computer is attempting to run Windows on an unsupported processor. +ms.assetid: 6d483759-7d02-4635-9622-437862165683 +keywords: ["Bug Check 0x5D UNSUPPORTED_PROCESSOR", "UNSUPPORTED_PROCESSOR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNSUPPORTED_PROCESSOR +api_type: +- NA +--- + +# Bug Check 0x5D: UNSUPPORTED\_PROCESSOR + + +The UNSUPPORTED\_PROCESSOR bug check has a value of 0x0000005D. This indicates that the computer is attempting to run Windows on an unsupported processor. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UNSUPPORTED\_PROCESSOR Parameters + + +None + +Cause +----- + +Windows requires a higher-grade processor than the one you are using. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5e--object-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x5e--object-initialization-failed.md new file mode 100644 index 0000000000..20a2e6c97a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5e--object-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x5E OBJECT_INITIALIZATION_FAILED +description: The OBJECT_INITIALIZATION_FAILED bug check has a value of 0x0000005E.This bug check appears very infrequently. +ms.assetid: 01775d91-ec60-4c0c-bba9-7c8940fcc58a +keywords: ["Bug Check 0x5E OBJECT_INITIALIZATION_FAILED", "OBJECT_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- OBJECT_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x5E: OBJECT\_INITIALIZATION\_FAILED + + +The OBJECT\_INITIALIZATION\_FAILED bug check has a value of 0x0000005E. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x5f--security-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x5f--security-initialization-failed.md new file mode 100644 index 0000000000..2237a9186b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x5f--security-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x5F SECURITY_INITIALIZATION_FAILED +description: The SECURITY_INITIALIZATION_FAILED bug check has a value of 0x0000005F.This bug check appears very infrequently. +ms.assetid: af0eea86-a88c-4ee2-8e03-776cd63b7adf +keywords: ["Bug Check 0x5F SECURITY_INITIALIZATION_FAILED", "SECURITY_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SECURITY_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x5F: SECURITY\_INITIALIZATION\_FAILED + + +The SECURITY\_INITIALIZATION\_FAILED bug check has a value of 0x0000005F. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6--invalid-process-detach-attempt.md b/windows-driver-docs-pr/debugger/bug-check-0x6--invalid-process-detach-attempt.md new file mode 100644 index 0000000000..f808fb8849 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6--invalid-process-detach-attempt.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x6 INVALID_PROCESS_DETACH_ATTEMPT +description: The INVALID_PROCESS_DETACH_ATTEMPT bug check has a value of 0x00000006. This bug check appears very infrequently. +ms.assetid: f468b348-6576-4430-aa8f-b6100a689fee +keywords: ["Bug Check 0x6 INVALID_PROCESS_DETACH_ATTEMPT", "INVALID_PROCESS_DETACH_ATTEMPT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_PROCESS_DETACH_ATTEMPT +api_type: +- NA +--- + +# Bug Check 0x6: INVALID\_PROCESS\_DETACH\_ATTEMPT + + +The INVALID\_PROCESS\_DETACH\_ATTEMPT bug check has a value of 0x00000006. + +This bug check appears very infrequently. This bug check can be caused by calling [**KeStackAttachProcess**](https://msdn.microsoft.com/library/windows/hardware/ff549659) routine and subsequently calling [**KeUnstackDetachProcess**](https://msdn.microsoft.com/en-us/library/windows/hardware/ff549677) in the driver's implementation of the [**PLOAD_IMAGE_NOTIFY_ROUTINE**](https://msdn.microsoft.com/en-us/library/windows/hardware/mt764088(v=vs.85).aspx) callback function. The callback runs in a thread of the process in which the image loaded. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x60--process-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x60--process-initialization-failed.md new file mode 100644 index 0000000000..d57aaa0c8b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x60--process-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x60 PROCESS_INITIALIZATION_FAILED +description: The PROCESS_INITIALIZATION_FAILED bug check has a value of 0x00000060.This bug check appears very infrequently. +ms.assetid: 781190a6-a50f-4b7a-9dea-ac31d2dee325 +keywords: ["Bug Check 0x60 PROCESS_INITIALIZATION_FAILED", "PROCESS_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PROCESS_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x60: PROCESS\_INITIALIZATION\_FAILED + + +The PROCESS\_INITIALIZATION\_FAILED bug check has a value of 0x00000060. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x61--hal1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x61--hal1-initialization-failed.md new file mode 100644 index 0000000000..97ccc42748 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x61--hal1-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x61 HAL1_INITIALIZATION_FAILED +description: The HAL1_INITIALIZATION_FAILED bug check has a value of 0x00000061.This bug check appears very infrequently. +ms.assetid: bf91dce3-072b-427e-9ef1-c6dfc2e37a4f +keywords: ["Bug Check 0x61 HAL1_INITIALIZATION_FAILED", "HAL1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HAL1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x61: HAL1\_INITIALIZATION\_FAILED + + +The HAL1\_INITIALIZATION\_FAILED bug check has a value of 0x00000061. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x62--object1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x62--object1-initialization-failed.md new file mode 100644 index 0000000000..9c65b147b2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x62--object1-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x62 OBJECT1_INITIALIZATION_FAILED +description: The OBJECT1_INITIALIZATION_FAILED bug check has a value of 0x00000062.This bug check appears very infrequently. +ms.assetid: 4039e240-2660-42a8-97bd-4a4907eb5773 +keywords: ["Bug Check 0x62 OBJECT1_INITIALIZATION_FAILED", "OBJECT1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- OBJECT1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x62: OBJECT1\_INITIALIZATION\_FAILED + + +The OBJECT1\_INITIALIZATION\_FAILED bug check has a value of 0x00000062. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x63--security1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x63--security1-initialization-failed.md new file mode 100644 index 0000000000..f153b68e15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x63--security1-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x63 SECURITY1_INITIALIZATION_FAILED +description: The SECURITY1_INITIALIZATION_FAILED bug check has a value of 0x00000063.This bug check appears very infrequently. +ms.assetid: 907be187-8703-46f3-bf17-01cd048f8ab6 +keywords: ["Bug Check 0x63 SECURITY1_INITIALIZATION_FAILED", "SECURITY1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SECURITY1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x63: SECURITY1\_INITIALIZATION\_FAILED + + +The SECURITY1\_INITIALIZATION\_FAILED bug check has a value of 0x00000063. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x64--symbolic-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x64--symbolic-initialization-failed.md new file mode 100644 index 0000000000..fa931422a0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x64--symbolic-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x64 SYMBOLIC_INITIALIZATION_FAILED +description: The SYMBOLIC_INITIALIZATION_FAILED bug check has a value of 0x00000064.This bug check appears very infrequently. +ms.assetid: 0f4fa80b-a04b-4482-952d-8f124d185b41 +keywords: ["Bug Check 0x64 SYMBOLIC_INITIALIZATION_FAILED", "SYMBOLIC_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYMBOLIC_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x64: SYMBOLIC\_INITIALIZATION\_FAILED + + +The SYMBOLIC\_INITIALIZATION\_FAILED bug check has a value of 0x00000064. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x65--memory1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x65--memory1-initialization-failed.md new file mode 100644 index 0000000000..8c6ca1abab --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x65--memory1-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x65 MEMORY1_INITIALIZATION_FAILED +description: The MEMORY1_INITIALIZATION_FAILED bug check has a value of 0x00000065.This bug check appears very infrequently. +ms.assetid: 9bd07824-f3bd-455a-8287-0cc9dd21dbe5 +keywords: ["Bug Check 0x65 MEMORY1_INITIALIZATION_FAILED", "MEMORY1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MEMORY1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x65: MEMORY1\_INITIALIZATION\_FAILED + + +The MEMORY1\_INITIALIZATION\_FAILED bug check has a value of 0x00000065. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x66--cache-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x66--cache-initialization-failed.md new file mode 100644 index 0000000000..10537a525e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x66--cache-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x66 CACHE_INITIALIZATION_FAILED +description: The CACHE_INITIALIZATION_FAILED bug check has a value of 0x00000066.This bug check appears very infrequently. +ms.assetid: 60e948ae-71c7-43b2-a16f-605141158929 +keywords: ["Bug Check 0x66 CACHE_INITIALIZATION_FAILED", "CACHE_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CACHE_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x66: CACHE\_INITIALIZATION\_FAILED + + +The CACHE\_INITIALIZATION\_FAILED bug check has a value of 0x00000066. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x67--config-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x67--config-initialization-failed.md new file mode 100644 index 0000000000..8f79b18b16 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x67--config-initialization-failed.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x67 CONFIG_INITIALIZATION_FAILED +description: The CONFIG_INITIALIZATION_FAILED bug check has a value of 0x00000067. This bug check indicates that the registry configuration failed. +ms.assetid: 3bc4d6d9-785e-4283-b4c5-2c868c03f084 +keywords: ["Bug Check 0x67 CONFIG_INITIALIZATION_FAILED", "CONFIG_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CONFIG_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x67: CONFIG\_INITIALIZATION\_FAILED + + +The CONFIG\_INITIALIZATION\_FAILED bug check has a value of 0x00000067. This bug check indicates that the registry configuration failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CONFIG\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Reserved

2

The location selector

3

The NT status code

4

Reserved

+ +  + +Cause +----- + +The registry could not allocate the pool that it needed to contain the registry files. This situation should never occur, because the register allocates this pool early enough in system initialization so that plenty of paged pool should be available. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x68--file-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x68--file-initialization-failed.md new file mode 100644 index 0000000000..49b4813dbf --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x68--file-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x68 FILE_INITIALIZATION_FAILED +description: The FILE_INITIALIZATION_FAILED bug check has a value of 0x00000068.This bug check appears very infrequently. +ms.assetid: 1f39dca6-77db-4f45-a06d-198e42f2bb6c +keywords: ["Bug Check 0x68 FILE_INITIALIZATION_FAILED", "FILE_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FILE_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x68: FILE\_INITIALIZATION\_FAILED + + +The FILE\_INITIALIZATION\_FAILED bug check has a value of 0x00000068. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x69--io1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x69--io1-initialization-failed.md new file mode 100644 index 0000000000..823db001c5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x69--io1-initialization-failed.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x69 IO1_INITIALIZATION_FAILED +description: The IO1_INITIALIZATION_FAILED bug check has a value of 0x00000069. This bug check indicates that the initialization of the I/O system failed for some reason. +ms.assetid: 1f150598-d008-41d0-8b2a-ef59bc5e5e6c +keywords: ["Bug Check 0x69 IO1_INITIALIZATION_FAILED", "IO1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IO1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x69: IO1\_INITIALIZATION\_FAILED + + +The IO1\_INITIALIZATION\_FAILED bug check has a value of 0x00000069. This bug check indicates that the initialization of the I/O system failed for some reason. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IO1\_INITIALIZATION\_FAILED Parameters + + +None + +Cause +----- + +There is very little information available to analyze this error. + +Most likely, the setup routine has improperly installed the system, or a user has reconfigured the system. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6a--lpc-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6a--lpc-initialization-failed.md new file mode 100644 index 0000000000..857c8fc8cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6a--lpc-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x6A LPC_INITIALIZATION_FAILED +description: The LPC_INITIALIZATION_FAILED bug check has a value of 0x0000006A.This bug check appears very infrequently. +ms.assetid: a8ffc4ec-0873-4226-800b-f305a85eaf24 +keywords: ["Bug Check 0x6A LPC_INITIALIZATION_FAILED", "LPC_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LPC_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6A: LPC\_INITIALIZATION\_FAILED + + +The LPC\_INITIALIZATION\_FAILED bug check has a value of 0x0000006A. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6b--process1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6b--process1-initialization-failed.md new file mode 100644 index 0000000000..48c76576f8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6b--process1-initialization-failed.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x6B PROCESS1_INITIALIZATION_FAILED +description: The PROCESS1_INITIALIZATION_FAILED bug check has a value of 0x0000006B. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: 8680d924-3041-4927-a228-52b281bbc267 +keywords: ["Bug Check 0x6B PROCESS1_INITIALIZATION_FAILED", "PROCESS1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PROCESS1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6B: PROCESS1\_INITIALIZATION\_FAILED + + +The PROCESS1\_INITIALIZATION\_FAILED bug check has a value of 0x0000006B. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PROCESS1\_INITIALIZATION\_FAILED Parameters + + +The following parameters appear on the blue screen. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the failure

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +Any part of the disk subsystem can cause the PROCESS1\_INITIALIZATION\_FAILED bug check, including bad disks, bad or incorrect cables, mixing different ATA-type devices on the same chain, or drives that are not available becuase of hardware regeneration. + +This bug check can also be caused by a missing file from the boot partition or by a driver file that a user accidentally disabled in the **Drivers** tab. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6c--refmon-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6c--refmon-initialization-failed.md new file mode 100644 index 0000000000..9935573e25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6c--refmon-initialization-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x6C REFMON_INITIALIZATION_FAILED +description: The REFMON_INITIALIZATION_FAILED bug check has a value of 0x0000006C.This bug check appears very infrequently. +ms.assetid: a312eb27-56dd-45e5-97d1-8ab4846fd31a +keywords: ["Bug Check 0x6C REFMON_INITIALIZATION_FAILED", "REFMON_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- REFMON_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6C: REFMON\_INITIALIZATION\_FAILED + + +The REFMON\_INITIALIZATION\_FAILED bug check has a value of 0x0000006C. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6d--session1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6d--session1-initialization-failed.md new file mode 100644 index 0000000000..b618bf0d5c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6d--session1-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x6D SESSION1_INITIALIZATION_FAILED +description: The SESSION1_INITIALIZATION_FAILED bug check has a value of 0x0000006D. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: e4f9280b-1cdd-4536-88bf-b216cc70129f +keywords: ["Bug Check 0x6D SESSION1_INITIALIZATION_FAILED", "SESSION1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6D: SESSION1\_INITIALIZATION\_FAILED + + +The SESSION1\_INITIALIZATION\_FAILED bug check has a value of 0x0000006D. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION1\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the initialization failure

2

0

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6e--session2-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6e--session2-initialization-failed.md new file mode 100644 index 0000000000..dfe1249973 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6e--session2-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x6E SESSION2_INITIALIZATION_FAILED +description: The SESSION2_INITIALIZATION_FAILED bug check has a value of 0x0000006E. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: 4c6abce5-e2a3-4033-897b-ddecb00d4cdf +keywords: ["Bug Check 0x6E SESSION2_INITIALIZATION_FAILED", "SESSION2_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION2_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6E: SESSION2\_INITIALIZATION\_FAILED + + +The SESSION2\_INITIALIZATION\_FAILED bug check has a value of 0x0000006E. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION2\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the Windows operating system to conclude that initialization failed

2

0

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x6f--session3-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x6f--session3-initialization-failed.md new file mode 100644 index 0000000000..fd4b1f51c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x6f--session3-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x6F SESSION3_INITIALIZATION_FAILED +description: The SESSION3_INITIALIZATION_FAILED bug check has a value of 0x0000006F. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: 5ee76f2c-026f-4b38-a7ee-ad5d45b132f7 +keywords: ["Bug Check 0x6F SESSION3_INITIALIZATION_FAILED", "SESSION3_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION3_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x6F: SESSION3\_INITIALIZATION\_FAILED + + +The SESSION3\_INITIALIZATION\_FAILED bug check has a value of 0x0000006F. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION3\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the Windows operating system to conclude that initialization failed

2

0

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7--invalid-software-interrupt.md b/windows-driver-docs-pr/debugger/bug-check-0x7--invalid-software-interrupt.md new file mode 100644 index 0000000000..43caf3b844 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7--invalid-software-interrupt.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x7 INVALID_SOFTWARE_INTERRUPT +description: The INVALID_SOFTWARE_INTERRUPT bug check has a value of 0x00000007.This bug check appears very infrequently. +ms.assetid: ceba1694-ed12-4e7a-85c9-9ad73a046bf3 +keywords: ["Bug Check 0x7 INVALID_SOFTWARE_INTERRUPT", "INVALID_SOFTWARE_INTERRUPT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_SOFTWARE_INTERRUPT +api_type: +- NA +--- + +# Bug Check 0x7: INVALID\_SOFTWARE\_INTERRUPT + + +The INVALID\_SOFTWARE\_INTERRUPT bug check has a value of 0x00000007. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x70--session4-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x70--session4-initialization-failed.md new file mode 100644 index 0000000000..40d3200b48 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x70--session4-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x70 SESSION4_INITIALIZATION_FAILED +description: The SESSION4_INITIALIZATION_FAILED bug check has a value of 0x00000070. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: 05de773c-19eb-44dd-b6ef-3efa43d703ef +keywords: ["Bug Check 0x70 SESSION4_INITIALIZATION_FAILED", "SESSION4_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION4_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x70: SESSION4\_INITIALIZATION\_FAILED + + +The SESSION4\_INITIALIZATION\_FAILED bug check has a value of 0x00000070. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION4\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the Windows operating system to conclude that initialization failed

2

0

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x71--session5-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x71--session5-initialization-failed.md new file mode 100644 index 0000000000..e15fac4628 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x71--session5-initialization-failed.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0x71 SESSION5_INITIALIZATION_FAILED +description: The SESSION5_INITIALIZATION_FAILED bug check has a value of 0x00000071. This bug check indicates that the initialization of the Microsoft Windows operating system failed. +ms.assetid: 5a79d766-c795-4d0c-94d4-417016701f6d +keywords: ["Bug Check 0x71 SESSION5_INITIALIZATION_FAILED", "SESSION5_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION5_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x71: SESSION5\_INITIALIZATION\_FAILED + + +The SESSION5\_INITIALIZATION\_FAILED bug check has a value of 0x00000071. This bug check indicates that the initialization of the Microsoft Windows operating system failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION5\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The NT status code that caused the Windows operating system to conclude that initialization failed

2

0

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x72--assign-drive-letters-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x72--assign-drive-letters-failed.md new file mode 100644 index 0000000000..940b1704df --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x72--assign-drive-letters-failed.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x72 ASSIGN_DRIVE_LETTERS_FAILED +description: The ASSIGN_DRIVE_LETTERS_FAILED bug check has a value of 0x00000072.This bug check appears very infrequently. +ms.assetid: 36437a0e-d56f-4454-9b1c-c57d98e1450a +keywords: ["Bug Check 0x72 ASSIGN_DRIVE_LETTERS_FAILED", "ASSIGN_DRIVE_LETTERS_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ASSIGN_DRIVE_LETTERS_FAILED +api_type: +- NA +--- + +# Bug Check 0x72: ASSIGN\_DRIVE\_LETTERS\_FAILED + + +The ASSIGN\_DRIVE\_LETTERS\_FAILED bug check has a value of 0x00000072. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x73--config-list-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x73--config-list-failed.md new file mode 100644 index 0000000000..67655bb32d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x73--config-list-failed.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0x73 CONFIG_LIST_FAILED +description: The CONFIG_LIST_FAILED bug check has a value of 0x00000073. This bug check indicates that one of the top-level registry keys, also known as core system hives, cannot be linked in the registry tree. +ms.assetid: fec1f3ee-5405-49c2-8082-75adfdabd6b8 +keywords: ["Bug Check 0x73 CONFIG_LIST_FAILED", "CONFIG_LIST_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CONFIG_LIST_FAILED +api_type: +- NA +--- + +# Bug Check 0x73: CONFIG\_LIST\_FAILED + + +The CONFIG\_LIST\_FAILED bug check has a value of 0x00000073. This bug check indicates that one of the top-level registry keys, also known as core system hives, cannot be linked in the registry tree. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CONFIG\_LIST\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

1

2

The NT status code that led the Windows operating system to assume that it failed to load the hive

3

The index of the hive in the hive list

4

A pointer to a UNICODE_STRING structure that contains the file name of the hive

+ +  + +Cause +----- + +The registry hive that cannot be linked might be SAM, SECURITY, SOFTWARE, or DEFAULT. The hive is valid, because it was loaded successfully. + +Examine Parameter 2 to see why the hive could not be linked in the registry tree. One common cause of this error is that the Windows operating system is out of disk space on the system drive. (In this situation, this parameter is 0xC000017D, STATUS\_NO\_LOG\_SPACE.) Another common problem is that an attempt to allocate pool has failed. (In this situation, Parameter 2 is 0xC000009A, STATUS\_INSUFFICIENT\_RESOURCES.) You must investigate other status codes. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x74--bad-system-config-info.md b/windows-driver-docs-pr/debugger/bug-check-0x74--bad-system-config-info.md new file mode 100644 index 0000000000..bd66d2e15b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x74--bad-system-config-info.md @@ -0,0 +1,87 @@ +--- +title: Bug Check 0x74 BAD_SYSTEM_CONFIG_INFO +description: The BAD_SYSTEM_CONFIG_INFO bug check has a value of 0x00000074. This bug check indicates that there is an error in the registry. +ms.assetid: c59ddc44-d860-4fbb-a975-ae7226fdce86 +keywords: ["Bug Check 0x74 BAD_SYSTEM_CONFIG_INFO", "BAD_SYSTEM_CONFIG_INFO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BAD_SYSTEM_CONFIG_INFO +api_type: +- NA +--- + +# Bug Check 0x74: BAD\_SYSTEM\_CONFIG\_INFO + + +The BAD\_SYSTEM\_CONFIG\_INFO bug check has a value of 0x00000074. This bug check indicates that there is an error in the registry. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BAD\_SYSTEM\_CONFIG\_INFO Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Reserved

2

Reserved

3

Reserved

4

The NT status code (if it is available)

+ +  + +Cause +----- + +The BAD\_SYSTEM\_CONFIG\_INFO bug check occurs if the SYSTEM hive is corrupt. However, this corruption is unlikely, because the boot loader, checks a hive for corruption when it loads the hive. + +This bug check can also occur if some critical registry keys and values are missing. The keys and values might be missing if a user manually edited the registry or if an application or service corrupted the registry. + +Resolution +---------- + +Try booting into safe mode and then restart the OS normally. If the restart does not fix the problem, the registry damage is too extensive. Try the following steps. + +- If you have a system restore point, try restoring to an earlier restore point. +- Reset your PC. +- Use installation media to restore or reset your PC. +- Use installation media to reinstall Windows. + +For more information, see [Recovery options in Windows 10](http://windows.microsoft.com/windows-10/windows-10-recovery-options#). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x75--cannot-write-configuration.md b/windows-driver-docs-pr/debugger/bug-check-0x75--cannot-write-configuration.md new file mode 100644 index 0000000000..bb6815dcc0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x75--cannot-write-configuration.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0x75 CANNOT_WRITE_CONFIGURATION +description: The CANNOT_WRITE_CONFIGURATION bug check has a value of 0x00000075. This bug check indicates that the SYSTEM registry hive file cannot be converted to a mapped file. +ms.assetid: 0190de02-8bd1-4c20-839d-bf9fb517567d +keywords: ["Bug Check 0x75 CANNOT_WRITE_CONFIGURATION", "CANNOT_WRITE_CONFIGURATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CANNOT_WRITE_CONFIGURATION +api_type: +- NA +--- + +# Bug Check 0x75: CANNOT\_WRITE\_CONFIGURATION + + +The CANNOT\_WRITE\_CONFIGURATION bug check has a value of 0x00000075. This bug check indicates that the SYSTEM registry hive file cannot be converted to a mapped file. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CANNOT\_WRITE\_CONFIGURATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

1

2

The NT status code that led the Windows operating system to assume that it had failed to convert the hive

3

Reserved

4

Reserved

+ +  + +Cause +----- + +The CANNOT\_WRITE\_CONFIGURATION bug check typically occurs if the system is out of pool and the Windows operating system cannot reopen the hive. + +This bug check should almost never occur, because the conversion of the hive file occurs early enough during system initialization so that enough pool should be available. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x76--process-has-locked-pages.md b/windows-driver-docs-pr/debugger/bug-check-0x76--process-has-locked-pages.md new file mode 100644 index 0000000000..ec9888f7a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x76--process-has-locked-pages.md @@ -0,0 +1,96 @@ +--- +title: Bug Check 0x76 PROCESS_HAS_LOCKED_PAGES +description: The PROCESS_HAS_LOCKED_PAGES bug check has a value of 0x00000076. This bug check indicates that a driver failed to release locked pages after an I/O operation. +ms.assetid: 25c63e2e-6d2a-401a-b523-ffa70e9f75df +keywords: ["Bug Check 0x76 PROCESS_HAS_LOCKED_PAGES", "PROCESS_HAS_LOCKED_PAGES"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PROCESS_HAS_LOCKED_PAGES +api_type: +- NA +--- + +# Bug Check 0x76: PROCESS\_HAS\_LOCKED\_PAGES + + +The PROCESS\_HAS\_LOCKED\_PAGES bug check has a value of 0x00000076. This bug check indicates that a driver failed to release locked pages after an I/O operation, or that it attempted to unlock pages that were already unlocked. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PROCESS\_HAS\_LOCKED\_PAGES Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x00

The pointer to the process object

The number of locked pages

The pointer to driver stacks (if they are enabled). Otherwise, this parameter is zero.

The process being terminated has locked memory pages. The driver must unlock any memory that it might have locked in a process, before the process terminates.

0x01

MDL specified by the driver

Current number of locked memory pages in that process

A pointer to driver stacks for that process (if they are enabled). Otherwise, this parameter is zero.

The driver is attempting to unlock process memory pages that are not locked.

+ +  + +Cause +----- + +The driver either failed to unlock pages that it locked (parameter 1 value is 0x0), or the driver is attempting to unlock pages that have not been locked or that have already been unlocked (parameter 1 value is 0x1). + +Resolution +---------- + +**If the parameter 1 value is 0x0** + +First use the [**!search**](-search.md) extension on the current process pointer throughout all of physical memory. This extension might find at least one memory descriptor list (MDL) that points to the current process. Next, use **!search** on each MDL that you find to obtain the I/O request packet (IRP) that points to the current process. From this IRP, you can identify which driver is leaking the pages. + +Otherwise, you can detect which driver caused the error by editing the registry: + +1. In the **\\\\HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management** registry key, create or edit the **TrackLockedPages** value, and then set it equal to DWORD 1. + +2. Restart the computer. + +The system then saves stack traces, so you can easily identify the driver that caused the problem. If the driver causes the same error again, [**bug check 0xCB**](bug-check-0xcb--driver-left-locked-pages-in-process.md) (DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS) is issued, and the name of the driver that causes this error is displayed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +**If the parameter 1 value is 0x1** + +Examine the driver source code that locks and unlocks memory, and try to locate an instance where memory is unlocked without first being locked. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x77--kernel-stack-inpage-error.md b/windows-driver-docs-pr/debugger/bug-check-0x77--kernel-stack-inpage-error.md new file mode 100644 index 0000000000..b99a3ac1df --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x77--kernel-stack-inpage-error.md @@ -0,0 +1,162 @@ +--- +title: Bug Check 0x77 KERNEL_STACK_INPAGE_ERROR +description: The KERNEL_STACK_INPAGE_ERROR bug check has a value of 0x00000077. This bug check indicates that the requested page of kernel data from the paging file could not be read into memory. +ms.assetid: 203a6d0f-0caa-46ed-9bab-61bbde1c8016 +keywords: ["Bug Check 0x77 KERNEL_STACK_INPAGE_ERROR", "KERNEL_STACK_INPAGE_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_STACK_INPAGE_ERROR +api_type: +- NA +--- + +# Bug Check 0x77: KERNEL\_STACK\_INPAGE\_ERROR + + +The KERNEL\_STACK\_INPAGE\_ERROR bug check has a value of 0x00000077. This bug check indicates that the requested page of kernel data from the paging file could not be read into memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_STACK\_INPAGE\_ERROR Parameters + + +The four parameters that listed in the message have two possible meanings. + +If the first parameter is 0, 1, or 2, the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

0: The page of kernel data was retrieved from page cache.

+

1: The page was retrieved from a disk.

+

2: The page was retrieved from a disk, the storage stack returned SUCCESS, but Status.Information is not equal to PAGE_SIZE.

2

The value that appears in the stack where the signature should be.

3

0

4

The address of the signature on the kernel stack

+ +  + +If the first parameter is any value other than 0, 1, or 2, the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The status code

2

The I/O status code

3

The page file number

4

The offset into page file

+ +  + +Cause +----- + +If the first parameter is 0 or 1, the stack signature in the kernel stack was not found. This error is probably caused by defective hardware, such as a RAM error. + +If the first parameter is 2, the driver stack returned an inconsistent status for the read of the page. For example, the driver stack returned a success status even though it did not read the whole page. + +If the first parameter is any value other than 0, 1, or 2, the value of the first parameter is an NTSTATUS error code that the driver stack returns after it tries to retrieve the page of kernel data. You can determine the exact cause of this error from the I/O status code (the second parameter). Some common status codes include the following: + +- 0xC000009A, or STATUS\_INSUFFICIENT\_RESOURCES, indicates a lack of nonpaged pool resources. This status code indicates a driver error in the storage stack. (The storage stack should always be able to retrieve this data, regardless of software resource availability.) + +- 0xC000009C, or STATUS\_DEVICE\_DATA\_ERROR, indicates bad blocks (sectors) on the hard disk. + +- 0xC000009D, or STATUS\_DEVICE\_NOT\_CONNECTED, indicates defective or loose cabling, termination, or that the controller does not see the hard disk drive. + +- 0xC000016A, or STATUS\_DISK\_OPERATION\_FAILED, indicates bad blocks (sectors) on the hard disk. + +- 0xC0000185, or STATUS\_IO\_DEVICE\_ERROR, indicates improper termination or defective cabling on SCSI devices or that two devices are trying to use the same IRQ. + +These status codes are the most common ones that have specific causes. For more information about other possible status codes that might be returned, see the Ntstatus.h file in the Microsoft Windows Driver Kit (WDK). + +A virus infection can also cause this bug check. + +Resolution +---------- + +**Resolving a bad block problem:** If you can restart the computer after the error, Autochk runs automatically and attempts to map the bad sector to prevent it from being used anymore. + +If Autochk does not scan the hard disk for errors, you can manually start the disk scanner. Run **Chkdsk /f /r** on the system partition. You must restart the computer before the disk scan begins. If you cannot start the system because the error, use the Recovery Console and run **Chkdsk /r**. + +**Warning**   If your system partition is formatted with the FAT file system, the long file names that the Windows operating system uses might be damaged if you use Scandisk or another MS-DOS-based hard disk tool to verify the integrity of your hard disk drive from MS-DOS. Always use the version of Chkdsk that matches your version of the Windows operating system. + +  + +**Resolving a defective hardware problem:** If the I/O status is 0xC0000185 and the paging file is on an SCSI disk, check the disk cabling and SCSI termination for problems. + +**Resolving a failing RAM problem:** Run the hardware diagnostics that the system manufacturer supplies, especially the memory scanner. For more information about these procedures, see the owner's manual for your computer. + +Check that all the adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure adapter card contacts are clean. + +Check the System Log in Event Viewer for additional error messages that might help identify the device that is causing the error. You can also disable memory caching of the BIOS to try to resolve this error. + +Make sure that the latest Windows Service Pack is installed. + +If the preceding steps fail to resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective component on the motherboard can cause this error. + +**Resolving a virus infection:** Check your computer for viruses by using any up-to-date, commercial virus scanning software that examines the Master Boot Record of the hard disk. All Windows file systems can be infected by viruses. + +## See also + + +[**Bug Check 0x7A (KERNEL\_DATA\_INPAGE\_ERROR)**](bug-check-0x7a--kernel-data-inpage-error.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x78--phase0-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x78--phase0-exception.md new file mode 100644 index 0000000000..23a1f3f88f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x78--phase0-exception.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x78 PHASE0_EXCEPTION +description: The PHASE0_EXCEPTION bug check has a value of 0x00000078.This bug check occurs when an unexpected break is encountered during HAL initialization. +ms.assetid: 2f306296-a7f4-47f8-b077-7acc623a538f +keywords: ["Bug Check 0x78 PHASE0_EXCEPTION", "PHASE0_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PHASE0_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x78: PHASE0\_EXCEPTION + + +The PHASE0\_EXCEPTION bug check has a value of 0x00000078. + +This bug check occurs when an unexpected break is encountered during HAL initialization. This break can occur if you have set the **/break** parameter in your boot settings but have not enabled kernel debugging. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x79--mismatched-hal.md b/windows-driver-docs-pr/debugger/bug-check-0x79--mismatched-hal.md new file mode 100644 index 0000000000..1b3d35a2e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x79--mismatched-hal.md @@ -0,0 +1,105 @@ +--- +title: Bug Check 0x79 MISMATCHED_HAL +description: The MISMATCHED_HAL bug check has a value of 0x00000079 that indicates that the HAL revision level or configuration does not match that of the kernel or the computer. +ms.assetid: 2d063c2a-c647-4436-b005-04f71a4d2b66 +keywords: ["Bug Check 0x79 MISMATCHED_HAL", "MISMATCHED_HAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MISMATCHED_HAL +api_type: +- NA +--- + +# Bug Check 0x79: MISMATCHED\_HAL + + +The MISMATCHED\_HAL bug check has a value of 0x00000079. This bug check indicates that the Hardware Abstraction Layer (HAL) revision level or configuration does not match that of the kernel or the computer. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MISMATCHED\_HAL Parameters + + +Parameter 1 indicates the type of mismatch. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause.

0x1

The major processor control block (PRCB) level of Ntoskrnl.exe.

The major PRCB level of Hal.dll.

Reserved

The PRCB release levels are mismatched. (Something is out of date.)

0x2

The build type of Ntoskrnl.exe.

The build type of Hal.dll.

Reserved

The build types are mismatched.

0x3

The size of the loader parameter extension.

The major version of the loader parameter extension.

The minor version of the loader parameter extension.

The loader (ntldr) and HAL versions are mismatched.

+ +  + +When Parameter 1 equals 0x2, the following build type codes are used: + +- 0: Multiprocessor-enabled free build + +- 1: Multiprocessor-enabled checked build + +- 2: Single-processor free build + +- 3: Single-processor checked build + +Cause +----- + +The MISMATCHED\_HAL bug check often occurs when a user manually updates Ntoskrnl.exe or Hal.dll. + +The error can also indicate that one of those two files is out of date. For example, the HAL might be designed for Microsoft Windows 2000 and the kernel is designed for Windows XP. Or the computer might erroneously have a multiprocessor HAL and a single-processor kernel installed, or vice versa. + +The Ntoskrnl.exe kernel file is for single-processor systems and Ntkrnlmp.exe is for multiprocessor systems. However, these file names correspond to the files on the installation media.After you have installed the Windows operating system, the file is renamed to Ntoskrnl.exe, regardless of the source file that is used. The HAL file also uses the name Hal.dll after installation, but there are several possible HAL files on the installation media. For more information, see "Installing the Checked Build" in the Windows Driver Kit (WDK). + +Resolution +---------- + +Restart the computer by using the product CD or the Windows Setup disks. At the Welcome screen, press F10 to start the Recovery Console. Use the **Copy** command to copy the correct HAL or kernel file from the original CD into the appropriate folder on the hard disk. The **Copy** command detects whether the file that you are copying is in the Microsoft compressed file format. If so, it automatically expands the file that is copied on the target drive. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7a--kernel-data-inpage-error.md b/windows-driver-docs-pr/debugger/bug-check-0x7a--kernel-data-inpage-error.md new file mode 100644 index 0000000000..2a3c1b0e96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7a--kernel-data-inpage-error.md @@ -0,0 +1,194 @@ +--- +title: Bug Check 0x7A KERNEL_DATA_INPAGE_ERROR +description: The KERNEL_DATA_INPAGE_ERROR bug check has a value of 0x0000007A. This bug check indicates that the requested page of kernel data from the paging file could not be read into memory. +ms.assetid: 466d4864-8840-47b2-9a9a-302a125bf095 +keywords: ["Bug Check 0x7A KERNEL_DATA_INPAGE_ERROR", "KERNEL_DATA_INPAGE_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_DATA_INPAGE_ERROR +api_type: +- NA +--- + +# Bug Check 0x7A: KERNEL\_DATA\_INPAGE\_ERROR + + +The KERNEL\_DATA\_INPAGE\_ERROR bug check has a value of 0x0000007A. This bug check indicates that the requested page of kernel data from the paging file could not be read into memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_DATA\_INPAGE\_ERROR Parameters + + +The four parameters that are listed in the message can have three possible meanings. If the first parameter is 1 or 2, or 3 and the third parameter is 0, the parameters have the following definitions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The lock type that was held (1, 2, or 3)

2

The error status (usually an I/O status code)

3

If Lock Type is 1: the current process

+

If Lock Type is 2 or 3: 0

4

The virtual address that could not be paged into memory

+ +  + +If the first parameter is 3 (and the third parameter is nonzero) or 4, the parameters have the following definitions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The lock type that was held (3 or 4)

2

The error status (typically an I/O status code)

3

The address of the InPageSupport structure

4

The faulting address

+ +  + +Otherwise, the parameters have the following definitions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the page table entry (PTE)

2

The error status (usually an I/O status code)

3

The PTE contents

4

The faulting address

+ +  + +Cause +----- + +Frequently, you can determine the cause of the KERNEL\_DATA\_INPAGE\_ERROR bug check from the error status (Parameter 2). Some common status codes include the following: + +- 0xC000009A, or STATUS\_INSUFFICIENT\_RESOURCES, indicates a lack of nonpaged pool resources. + +- 0xC000009C, or STATUS\_DEVICE\_DATA\_ERROR, typically indicates bad blocks (sectors) on the hard disk. + +- 0xC000009D, or STATUS\_DEVICE\_NOT\_CONNECTED, indicates defective or loose cabling, termination, or that the controller does not see the hard disk. + +- 0xC000016A, or STATUS\_DISK\_OPERATION\_FAILED, indicates bad blocks (sectors) on the hard disk. + +- 0xC0000185, or STATUS\_IO\_DEVICE\_ERROR, indicates improper termination or defective cabling on SCSI devices or that two devices are trying to use the same IRQ. + +- 0xC000000E, or STATUS\_NO\_SUCH\_DEVICE, indicates a hardware failure or an incorrect drive configuration. Check your cables and check the drive with the diagnostic utility available from your drive manufacturer. If you are using older PATA (IDE) drives, this status code can indicate an incorrect master/subordinate drive configuration. + +These status codes are the most common ones that have specific causes. For more information about other possible status codes that can be returned, see the Ntstatus.h file in the Microsoft Windows Driver Kit (WDK). + +Another common cause of this error message is defective hardware or failing RAM. + +A virus infection can also cause this bug check. + +Resolution +---------- + +**Resolving a bad block problem:** An I/O status code of 0xC000009C or 0xC000016A typically indicates that the data could not be read from the disk because of a bad block (sector). If you can restart the computer after the error, Autochk runs automatically and attempts to map the bad sector to prevent it from being used anymore. + +If Autochk does not scan the hard disk for errors, you can manually start the disk scanner. Run **Chkdsk /f /r** on the system partition. You must restart the computer before the disk scan begins. If you cannot start the computer because of the error, use the Recovery Console and run **Chkdsk /r**. + +**Warning**   If your system partition is formatted with the FAT file system, the long file names that the Windows operating system uses might be damaged if you use Scandisk or another MS-DOS-based hard disk tool to verify the integrity of your hard disk from MS-DOS. Always use the version of Chkdsk that matches your version of Windows. + +  + +**Resolving a defective hardware problem:** If the I/O status is C0000185 and the paging file is on an SCSI disk, check the disk cabling and SCSI termination for problems. + +**Resolving a failing RAM problem:** Run the hardware diagnostics that the system manufacturer supplies, especially the memory scanner. For more information about these procedures, see the owner's manual for your computer. + +Check that all the adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure adapter card contacts are clean. + +Check the System Log in Event Viewer for additional error messages that might help identify the device that is causing the error. You can also disable memory caching of the BIOS to try to resolve this error. + +Make sure that the latest Windows Service Pack is installed. + +If the preceding steps do not resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective component on the motherboard can cause this error. + +**Resolving a virus infection:** Check your computer for viruses by using any up-to-date, commercial virus scanning software that examines the Master Boot Record of the hard disk. All Windows file systems can be infected by viruses. + +## See also + + +[**Bug Check 0x77 (KERNEL\_STACK\_INPAGE\_ERROR)**](bug-check-0x77--kernel-stack-inpage-error.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7b--inaccessible-boot-device.md b/windows-driver-docs-pr/debugger/bug-check-0x7b--inaccessible-boot-device.md new file mode 100644 index 0000000000..ad2b148171 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7b--inaccessible-boot-device.md @@ -0,0 +1,293 @@ +--- +title: Bug Check 0x7B INACCESSIBLE_BOOT_DEVICE +description: The INACCESSIBLE_BOOT_DEVICE bug check has a value of 0x0000007B. This bug check indicates that the Microsoft Windows operating system has lost access to the system partition during startup. +ms.assetid: 0dfcb519-4ea3-4419-a1c3-60fdff96404d +keywords: ["Bug Check 0x7B INACCESSIBLE_BOOT_DEVICE", "INACCESSIBLE_BOOT_DEVICE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INACCESSIBLE_BOOT_DEVICE +api_type: +- NA +--- + +# Bug Check 0x7B: INACCESSIBLE\_BOOT\_DEVICE + + +The INACCESSIBLE\_BOOT\_DEVICE bug check has a value of 0x0000007B. This bug check indicates that the Microsoft Windows operating system has lost access to the system partition during startup. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INACCESSIBLE\_BOOT\_DEVICE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of a UNICODE_STRING structure, or the address of the device object that could not be mounted

2

0

3

0

4

0

+ +  + +To determine the meaning of Parameter 1, look at the data that it points to. If the first word (USHORT) at this address is even, Parameter 1 is the beginning of a Unicode string. If the first word (USHORT) at this address is 0x3, Parameter 1 is the first field (Type) of a device object. + +- If this parameter points to a device object, the file system that was supposed to read the boot device failed to initialize or simply did not recognize the data on the boot device as a file system structure. In this situation, the specified device object is the object that could not be mounted. + +- If this parameter points to a Unicode string, you must read the first 8 bytes at this address. These bytes form the UNICODE\_STRING structure, which is defined as follows: + + ``` + USHORT Length; + USHORT MaximumLength; + PWSTR Buffer; + ``` + + The **Length** field gives the actual length of the string. The **Buffer** field points to the beginning of the string (**Buffer** is always be at least 0x80000000.) + + The actual string contains the Advanced RISC Computing (ARC) specification name of the device that the boot was being attempted from. ARC names are a generic way to identify devices in the ARC environment. + +Cause +----- + +The INACCESSIBLE\_BOOT\_DEVICE bug check frequently occurs because of a boot device failure. During I/O system initialization, the boot device driver might have failed to initialize the boot device (typically a hard disk). + +File system initialization might have failed because it did not recognize the data on the boot device. Also, repartitioning the system partition, changing the BIOS configuration, or installing a disk controller might induce this error. + +This error can also occur because of incompatible disk hardware. If the error occurred at the initial setup of the system, the system might have been installed on an unsupported disk controller. Some disk controllers require additional drivers to be present when Windows starts. + +Resolution +---------- + +This error always occurs while the system is starting. This error frequently occurs before the debugger connection is established, so debugging can be difficult. In addition, the OS may not be accessible and the error logs may be empty as the OS has not booted far enough to start those sub-systems. + +**\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*** + +**If you are unable to boot Windows** + +**\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*** + +If you receive this stop code and Windows doesn't boot forward into the OS, try the following: + +**Revert any recent hardware changes** + +Remove any recently added hardware, especially hard disk drives or controllers, to see if the error is resolved. If the problematic hardware is a hard disk drive, the disk firmware version might be incompatible with your version of the Windows operating system. Contact the manufacturer for updates. If you removed another piece of hardware and the error is resolved, IRQ or I/O port conflicts may exist. Reconfigure the new device according to the manufacturer's instructions. + +If you have recently made changes to BIOS settings, such as changing the controller mode from legacy to AHCI in the BIOS, revert those changes. For more information, see + +**Check for storage device compatibility** + +Confirm that all hard disk drivers, hard disk controllers, and any other storage adapters are compatible with the installed version of Windows. For example, you can get information about compatibility at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +**Update BIOS and Firmware** + +Check the availability of updates for the system BIOS and storage controller firmware. + +**Use the Media Creation Tool to create a bootable USB thumb drive or DVD** + +Use Media Creation Tool, using another computer to create a bootable USB thumb drive or DVD. Use it to perform a clean install, by clicking on the setup file or booting from the USB. + +For more information, see [Get Windows 10](https://www.microsoft.com/software-download/windows10). + +Be aware that you may need to disable features, such as quick BIOS boot, or you may not be able to reach the boot device priority menu. Change your boot sequence priority in the BIOS menu to boot from FDD (FlashDiskDrive) or DVD instead of HDD. + +**Common Boot Menu Keys** + +The boot menu key varies per manufacturer, these keys are commonly used. Check the system documentation to determine what boot key is used. + +F12 +ESC +F9 +F10 +F8 +**Common BIOS Setup Keys** + +The BIOS setup key varies per manufacturer, these keys are commonly used. Check the system documentation to determine what setup key is used. + +ESC +DEL +F2 +**\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*** + +**If you can boot Windows** + +**\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*** + +- **Boot to Safe Mode and then Boot Normally** + + Complete the following steps to boot into Safe Mode. Booting into safe mode loads a core set of storage drivers that may allow for the storage system to be accessed once again. + + To enter Safe Mode, use **Update and Security** in Settings. Select **Recovery**->**Advanced startup** to boot to maintenance mode. At the resulting menu, choose **Troubleshoot**-> **Advanced Options** -> **Startup Settings** -> **Restart**. After Windows restarts to the **Startup Settings** screen, select option, 4, 5 or 6 to boot to Safe Mode. + + Once Windows is loaded in Safe Mode, restart your PC to see if the proper storage drivers will be loaded and that the storage device is recognized. + + Safe Mode may also be available by pressing a function key on boot, for example F8. Refer to information from the system manufacturer for specific startup options. + +- Use the scan disk utility to confirm that there are no file system errors. Right click on the drive you want to scan and select **Properties**. Click on **Tools**. Click the **Check now** button. +- Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes. Make sure the virus detection program checks the Master Boot Record for infections. + +- For IDE devices, define the onboard IDE port as Primary only. Also check each IDE device for the proper **master/subordinate/stand alone** setting. Try removing all IDE devices except for hard disks. Finally, check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing the error. + +- Confirm that there is sufficient free space on the hard drive. The operating system and some applications require sufficient free space to create swap files and for other functions. Based on the system configuration, the exact requirement varies, but it is normally a good idea to have 10% to 15% free space available. + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- Use the System File Checker tool to repair missing or corrupted system files. The System File Checker is a utility in Windows that allows users to scan for corruptions in Windows system files and restore corrupted files. Use the following command to run the System File Checker tool (SFC.exe). + + ``` + SFC /scannow + ``` + + For more information, see [Use the System File Checker tool to repair missing or corrupted system files](https://support.microsoft.com/kb/929833). + +- After automatic repair, on the Choose an option screen, select **Troubleshoot > Advanced options > System Restore**. This option takes your PC back to an earlier point in time, called a system restore point. Restore points are generated when you install a new app, driver, update, or when you create a restore point manually. Choose a restore point before you experienced the error. + +- Use the kernel debugger to attach to the system and further analyze the failure as described in remarks. + +Remarks +------- + +**Investigating the storage system configuration** + +It is helpful to know as much as possible about the boot device that Windows is installed on. For example, you can investigate the following items: + +- Find out what type of controller the boot device is connected to (SATA, IDE, etc). If you can boot the system, you can use device manager to examine the controller and disk driver properties and see the associated driver file as well as error events. + +- Indicate if other devices are attached to the same controller that the boot device is on (SSD, DVD, and so on). + +- Note the file system that is used on the drive, typically NTFS. + +**To analyze this error using the kernel debugger:** Run an [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command in the debugger to see which modules are loaded to attempt to isolate the specific driver. Verify that the following drivers were loaded. + +*disk* + +``` + +0: kd> lm m disk +Browse full module list +start end module name +fffff806`bd0b0000 fffff806`bd0cd000 disk (deferred) +``` + +*partmgr* + +``` +0: kd> lm m partmgr +Browse full module list +start end module name +fffff806`bc5a0000 fffff806`bc5c1000 partmgr (deferred) +``` + +*NTFS* + +``` +0: kd> lm m ntfs +Browse full module list +start end module name +fffff806`bd3f0000 fffff806`bd607000 NTFS (deferred) +``` + +*classpnp* + +``` + 0: kd> lm m classpnp +Browse full module list +start end module name +fffff806`bd0d0000 fffff806`bd131000 CLASSPNP (deferred) +``` + +*pci* + +``` +0: kd> lm m pci +Browse full module list +start end module name +fffff806`bc440000 fffff806`bc494000 pci (deferred) +``` + +Also make sure your controller drivers are loaded. For example for a SATA RAID Controller, this might be the *iaStorA.Sys* driver, or it could be the *EhStorClass* driver. + +``` +0: kd> lm m EhStorClass +Browse full module list +start end module name +fffff806`bcbb0000 fffff806`bcbcb000 EhStorClass (deferred) +``` + +List the drivers that contain "stor", storahci, may be present. + +``` +0: kd> lm m stor* +Browse full module list +start end module name +fffff806`bcb00000 fffff806`bcb23000 storahci (deferred) +fffff806`bcb30000 fffff806`bcbaa000 storport (deferred) +fffff806`c0770000 fffff806`c0788000 storqosflt (deferred) +``` + +**Booting with a debugger attached** + +If you can boot the target system with a debugger connected, issue [**!devnode 0 1**](-devnode.md) when the bugcheck occurs. You'll see which device lacks a driver or could not start, and the reason for not starting may be apparent. + +One cause, might be that Plug and Play cannot assign resources to the boot device. You can verify this restriction by finding an entry for the service. If the status flags include DNF\_INSUFFICIENT\_RESOURCES or do not include DNF\_STARTED or DNF\_ENUMERATED, you may have located the problem. Try **!devnode 0 1 storahci** to save some time, instead of dumping the whole device tree. + +``` +0: kd> !devnode 0 1 storahci +Dumping IopRootDeviceNode (= 0xffffb9053d94d850) +DevNode 0xffffb9053e8dea50 for PDO 0xffffb9053e8da060 + InstancePath is "PCI\VEN_8086&DEV_3B22&SUBSYS_304A103C&REV_05\3&21436425&0&FA" + ServiceName is "storahci" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffb9053e88db30 for PDO 0xffffb9053e890060 + InstancePath is "SCSI\Disk&Ven_&Prod_ST3500418AS\4&23d99fa2&0&000000" + ServiceName is "disk" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffb9053e88d850 for PDO 0xffffb9053e88e060 + InstancePath is "SCSI\CdRom&Ven_hp&Prod_DVD-RAM_GH60L\4&23d99fa2&0&010000" + ServiceName is "cdrom" + TargetDeviceNotify List - f 0xffffdf0ae9bbb0e0 b 0xffffdf0aea874710 + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) +``` + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7c--bugcode-ndis-driver.md b/windows-driver-docs-pr/debugger/bug-check-0x7c--bugcode-ndis-driver.md new file mode 100644 index 0000000000..ef943fee1d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7c--bugcode-ndis-driver.md @@ -0,0 +1,469 @@ +--- +title: Bug Check 0x7C BUGCODE_NDIS_DRIVER +description: The BUGCODE_NDIS_DRIVER bug check has a value of 0x0000007C. This bug check indicates that the operating system detected an error in a networking driver. +ms.assetid: 0f2c2e9c-2889-4d99-b653-0ee1d4c2be0e +keywords: ["Bug Check 0x7C BUGCODE_NDIS_DRIVER", "BUGCODE_NDIS_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BUGCODE_NDIS_DRIVER +api_type: +- NA +--- + +# Bug Check 0x7C: BUGCODE\_NDIS\_DRIVER + + +The BUGCODE\_NDIS\_DRIVER bug check has a value of 0x0000007C. This bug check indicates that the operating system detected an error in a networking driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BUGCODE\_NDIS\_DRIVER Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. If a Parameter's value is "0," that means it is not used. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 1 Value and Cause of ErrorParameter 2Parameter 3Parameter 4

0x01

NDIS_BUGCHECK_ALLOCATE_SHARED_MEM_HIGH_IRQL

+

A driver called [NdisMAllocateSharedMemory](https://msdn.microsoft.com/library/windows/hardware/ff562782) at a raised IRQL.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The length of the requested shared memory

The current IRQL

0x02

NDIS_BUGCHECK_SHARED_MEM_CORRUPTION

+

During a call to [NdisMAllocateSharedMemory](https://msdn.microsoft.com/library/windows/hardware/ff562782), NDIS detected that a previously-allocated shared memory page had been corrupted.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The shared memory page that was corrupted

The address of a NDIS_WRAPPER_CONTEXTE that keeps track of shared memory allocations by the driver

0x03

NDIS_BUGCHECK_FREE_INVALID_SHARED_MEM

+

A miniport driver called [NdisMFreeSharedMemory](https://msdn.microsoft.com/library/windows/hardware/ff563589) (Async) with a shared memory address that had already been freed.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The page from which this shared memory was allocated

The virtual address of the shared memory

0x04

NDIS_BUGCHECK_UNLOAD_DRIVER_INVALID_PARAMETER

+

[AddDevice](https://msdn.microsoft.com/library/windows/hardware/ff540521) was called with a driver that is not on the list of drivers that are registered with NDIS.

+

Enabled only on special instrumented NDIS.

The address of the NDIS_M_DRIVER_BLOCK

The address of the DRIVER_OBJECT

0

0x05

NDIS_BUGCHECK_RECVD_PACKET_IN_USE_BAD_STACK_LOCATION

+

An Ethernet driver indicated that it received a packet using a packet descriptor that was currently in use by the protocol stack.

+

Caught by checking stack packet location.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the packet descriptor used by the driver. Run [!ndiskd.pkt](-ndiskd-pkt.md) with this address for more information.

The address of the packet array that contained this packet descriptor

0x06

NDIS_BUGCHECK_RECVD_PACKET_IN_USE_BAD_REF_COUNT

+

An Ethernet driver indicated that it received a packet using a packet descriptor that was currently in use by the protocol stack.

+

Caught by checking packet reference count.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the packet descriptor used by the driver. Run [!ndiskd.pkt](-ndiskd-pkt.md) with this address for more information.

The address of the packet array that contained this packet descriptor

0x07

An FDDI driver indicated that it received a packet by using a packet descriptor that was currently in use by the protocol stack.

+

Caught by checking reference count.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the packet descriptor used by the driver. Run [!ndiskd.pkt](-ndiskd-pkt.md) with this address for more information.

The address of the packet array that contained this packet descriptor

0x08

NDIS_BUGCHECK_HALT_WITHOUT_INTERRUPT_DEREGISTER

+

A miniport driver did not deregister its interrupt during the halt process.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the NDIS_MINIPORT_INTERRUPT

0

0x09

NDIS_BUGCHECK_HALT_WITHOUT_CANCEL_TIMER

+

A miniport driver stopped without successfully canceling all its timers.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the miniport driver's timer queue (NDIS_MINIPORT_TIMER)

0

0x0A

NDIS_BUGCHECK_DRIVER_UNLOAD_UNEXPECTED

+

A miniport driver is getting unloaded prematurely.

The address of the NDIS_M_DRIVER_BLOCK

The address of the DRIVER_OBJECT

The reference count for the miniport driver

0x0B

NDIS_BUGCHECK_INIT_FAILED_WITHOUT_INTERRUPT_DEREGISTER

+

A miniport driver failed its initialization without deregistering its interrupt.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the NDIS_MINIPORT_INTERRUPT

0

0x0C

NDIS_BUGCHECK_INIT_FAILED_WITHOUT_CANCEL_TIMER

+

A miniport driver failed its initialization without successfully canceling all its timers.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the miniport driver's timer queue (NDIS_MINIPORT_TIMER)

0

0x0D

NDIS_BUGCHECK_HALT_INIT_WITHOUT_INTERRUPT_DEREGISTER

+

A miniport driver did not deregister its interrupt during the halt process.

+

The halt was called from the initialize routine after the miniport driver returned success from its initialize handler.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the NDIS_MINIPORT_INTERRUPT

0

0x0E

NDIS_BUGCHECK_HALT_INIT_WITHOUT_CANCEL_TIMER

+

A miniport driver stopped without successfully canceling all its timers.

+

The halt was called from the initialize routine after the miniport driver returned success from its initialize handler.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the miniport driver's timer queue (NDIS_MINIPORT_TIMER)

0

0x0F

NDIS_BUGCHECK_RESET_COMPLETE_UNEXPECTED

+

A miniport driver called [NdisMResetComplete](https://msdn.microsoft.com/library/windows/hardware/ff563663) without any pending reset request.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The reset status

AddressingReset (BOOLEAN)

0x10

NDIS_BUGCHECK_PM_INIT_FAILED_NO_INT_DEREGISTER

+

After resuming from a low-power state, a miniport driver failed its initialization without deregistering its interrupt.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the NDIS_MINIPORT_INTERRUPT

0

0x11

NDIS_BUGCHECK_PM_INIT_FAILED_NO_CANCEL_TIMER

+

After resuming from a low-power state, a miniport driver failed its initialization without successfully canceling all its timers.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the miniport driver's timer queue (NDIS_MINIPORT_TIMER)

0

0x12

NDIS_BUGCHECK_NFILTER_RECVD_PACKET_BAD_REF_COUNT

+

A miniport driver indicated that it received a packet using a packet descriptor that was currently in use by the protocol stack.

+

Caught by checking packet reference count.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the packet descriptor used by the driver. Run [!ndiskd.pkt](-ndiskd-pkt.md) with this address for more information.

The address of the packet array that contained this packet descriptor

0x13

NDIS_BUGCHECK_TFILTER_RECVD_PACKET_BAD_REF_COUNT

+

A Token-Ring miniport driver indicated that it received a packet using a packet descriptor that was currently in use by the protocol stack.

+

Caught by checking packet reference count.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The address of the packet descriptor used by the driver. Run [!ndiskd.pkt](-ndiskd-pkt.md) with this address for more information.

The address of the packet array that contained this packet descriptor

0x14

NDIS_BUGCHECK_WAIT_EVENT_HIGH_IRQL

+

An NDIS driver called [NdisWaitEvent](https://msdn.microsoft.com/library/windows/hardware/ff564651) at an illegal IRQL

The actual IRQL

0

0

0x15

NDIS_BUGCHECK_INVALID_NDIS5_CALL

+

A miniport driver called an API that is reserved for older drivers. The driver should only call NDIS 6.x APIs.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

0

0

0x16

NDIS_BUGCHECK_INVALID_OPEN_IN_BIND_CONTEXT

+

A protocol driver improperly opened an adapter during binding.

The address of the specific protocol. Run [!ndiskd.protocol](-ndiskd-protocol.md) with this address for more information.

The address of the context area that is allocated by the protocol driver.

+

Cast to ndis!NDIS_BIND_CONTEXT.

The address of the open handle. Run [!ndiskd.mopen](-ndiskd-mopen.md) with this address for more information.

0x17

NDIS_BUGCHECK_IFPROVIDER_DEREGISTER_UNEXPECTED

+

An Interface Provider called [NdisIfDeregisterProvider](https://msdn.microsoft.com/library/windows/hardware/ff562703) without first removing all its Interfaces.

The address of the interface provider handle. Run [!ndiskd.ifprovider](-ndiskd-ifprovider.md) with this address for more information.

0

0

0x1B

NDIS_BUGCHECK_IF_STACK_TABLE_LOOP

+

A driver attempted to add an Interface to the ifStackTable, but doing so would cause a cycle. The ifStackTable must not have cycles. Run [!ndiskd.ifstacktable](-ndiskd-ifstacktable.md) to see the current table (prior to this call to [NdisIfAddIfStackEntry](https://msdn.microsoft.com/library/windows/hardware/ff562693)).

The HigherLayerIfIndex being added to the table

The LowerLayerIfIndex being added to the table

0

0x1C

NDIS_BUGCHECK_MINIPORT_FAILED_OID_WHICH_MUST_SUCCEED

+

A miniport driver failed an OID request that must not fail. Doing so would leak memory or other resources.

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

The OID that was failed. Use [!ndiskd.help](-ndiskd-help.md) to find the name of this OID.

The failure status code (NDIS_STATUS_XXX) with which the OID request was completed

0x1D

NDIS_BUGCHECK_OID_REQUEST_INVALID_BUFFER

+

A miniport driver or filter driver has completed an OID request illegally. Check that BytesWritten is not greater than the entire length of the buffer.

The address of the specific miniport adapter or filter module block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) or [!ndiskd.filter](-ndiskd-filter.md) with this address for more information.

The address to the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) that was completed illegally. Inspect it with [!ndiskd.oid](-ndiskd-oid.md).

0

0x1E

NDIS_BUGCHECK_REFCOUNT_IMBALANCE

+

NDIS has detected an error in an internal refcount. This can be caused by a refcount underflow (more dereferences than references), or by a tag mismatch.

0

Internal handle. Use [!ndiskd.ndisref](-ndiskd-ndisref.md) or cast to ndis!NDIS_REFCOUNT_BLOCK.

The current reftag value

0x1F

NDIS_BUGCHECK_ILLEGAL_MINIPORT_STATE_TRANSITION

+

A miniport driver completed a state transition illegally.

What failed. Possible values:

+
    +
  1. NDIS_BUGCHECK_ILLEGAL_MINIPORT_STATE_TRANSITION_PAUSE_COMPLETE

    +

    The miniport called NdisMPauseComplete but there was no pending Pause operation.

  2. +
  3. NDIS_BUGCHECK_ILLEGAL_MINIPORT_STATE_TRANSITION_RESTART_COMPLETE

    +

    The miniport called NdisMRestartComplete but there was no pending Restart operation.

  4. +

The address of the specific miniport adapter block. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this address for more information.

0

0x20

NDIS_BUGCHECK_STATUS_INDICATION_INVALID_BUFFER

+

A miniport driver or filter driver indicated an illegal [NDIS_STATUS_INDICATION](https://msdn.microsoft.com/library/windows/hardware/ff567373).

The type of the status indication. Run [!ndiskd.help](-ndiskd-help.md) with this code for more information.

The handle of the driver instance that indicated this illegal status indication. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) or [!ndiskd.filter](-ndiskd-filter.md) with this handle for more information.

The address of the status indication payload. Its interpretation depends on the type of status indication.

0x21

NDIS_BUGCHECK_INVALID_OBJECT_HEADER

+

A driver created an invalid [NDIS_OBJECT_HEADER](https://msdn.microsoft.com/library/windows/hardware/ff566588).

The handle of the driver that indicated the illegal status indication. Run [!ndiskd.minidriver](-ndiskd-minidriver.md) or [!ndiskd.filterdriver](-ndiskd-filterdriver.md) with this handle for more information.

The object with the malformed header. Its interpretation depends on the API being called. For example, if the driver called NdisAllocateCloneOidRequest, then cast the object to ndis!NDIS_OID_REQUEST.

0

0x22

NDIS_BUGCHECK_ILLEGAL_NET_PNP_EVENT

+

A miniport driver or filter driver indicated an illegal [NET_PNP_EVENT_NOTIFICATION](https://msdn.microsoft.com/library/windows/hardware/ff568752).

The handle of the driver that indicated the illegal status indication. Run [!ndiskd.minidriver](-ndiskd-minidriver.md) or [!ndiskd.filterdriver](-ndiskd-filterdriver.md) with this handle for more information.

Cast to NET_PNP_EVENT_NOTIFICATION

0

0x23

NDIS_BUGCHECK_PD_ERROR

+

An error was detected in the Packet Direct datapath.

The subtype of the bugcheck. Possible values:

+
    +
  1. NDIS_BUGCHECK_PD_ERROR_EC_THREAD_MISMATCH

    +

    An API was called on the wrong thread.

  2. +
  3. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_ARM_BY_CLIENT

    +

    A PD client attempted to arm the provider while in an illegal state.

  4. +
  5. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_ARM_NOTIFICATION

    +

    A PD provider illegally triggered a drain notification while it was not armed.

  6. +
  7. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_ARM_NOTIFICATION_VIA_ISR

    +

    A PD provider illegally triggered an ISR drain notification while it was not armed.

  8. +
  9. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_THUNK_BY_LWF

    +

    A filter driver attempted to interfere with the Packet Direct datapath.

  10. +
  11. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_BM_GROUP_REQUEST

    +

    A PD provider illegally attempted to remove itself from a buffer manager group.

  12. +
  13. NDIS_BUGCHECK_PD_ERROR_ILLEGAL_PD_BUFFER_SETUP

    +

    A PD buffer setup request was malformed.

  14. +

The value of Parameter 3 depends on the value of Parameter 2. Each number in this list corresponds to the same number in Parameter 2.

+
    +
  1. Cast to NDIS_PD_EC
  2. +
  3. Cast to NDIS_PD_QUEUE_TRACKER
  4. +
  5. Cast to NDIS_PD_QUEUE_TRACKER
  6. +
  7. Cast to NDIS_PD_QUEUE_TRACKER
  8. +
  9. The handle of the specific filter module. Run [!ndiskd.filter](-ndiskd-filter.md) with this handle for more information.
  10. +
  11. The buffer manager group, if known
  12. +
  13. The source PD_MEMORY_HANDLE or PD_BUFFER
  14. +

The value of Parameter 4 depends on the value of Parameter 2. Each number in this list corresponds to the same number in Parameter 2.

+
    +
  1. The ETHREAD that was expected
  2. +
  3. The handle to the PD client
  4. +
  5. The handle to the PD provider. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this handle for more information.
  6. +
  7. The handle to the PD provider. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this handle for more information.
  8. +
  9. The handle to the PD provider. Run [!ndiskd.netadapter](-ndiskd-netadapter.md) with this handle for more information.
  10. +
  11. If Parameter 3 is 0, this is the provider handle.

    +

    If Parameter 3 is non-zero, the PD client has not freed all allocations yet, and this is the PD client handle.

  12. +
  13. The target PD_BUFFER
  14. +

0x24

NDIS_BUGCHECK_UNEXPECTED_FAILURE

+

An internal operation failed unexpectedly. This is likely to be a bug in NDIS.SYS itself.

The operation that failed. Possible values:

+

0x01 : NDIS_BUGCHECK_UNEXPECTED_FAILURE_KEWAITFORSINGLEOBJECT

+

A call to KeWaitForSingleObject failed.

The failure status code

0

0x25

NDIS_BUGCHECK_WATCHDOG

+

An attempt to manage the network stack has taken too long. When NDIS calls out into other drivers, NDIS starts a watchdog timer to ensure the call completes promptly. If the call takes too long, NDIS injects a bugcheck.

+

This can be caused by a simple deadlock. Look with "!stacks 2 ndis" or similar to see if any threads look suspicious. Pay special attention to the PrimaryThread from the NDIS_WATCHDOG_TRIAGE_BLOCK.

+

This can be caused by lost NBLs, in which case [!ndiskd.pendingnbls](-ndiskd-pendingnbls.md) may help. Check for OIDs that are stuck using [!ndiskd.oid](-ndiskd-oid.md).

The operation that took too long. Possible values:

+
    +
  • 0x01 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_PAUSE

    +

    There was a timeout while pausing a protocol driver.

  • +
  • 0x02 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_NETPNPEVENT

    +

    There was a timeout while delivering a NET_PNP_EVENT_NOTIFICATION to a protocol driver.

  • +
  • 0x03 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_STATUS_INDICATION

    +

    There was a timeout while delivering a status indication to a protocol driver.

  • +
  • 0x04 : NDIS_BUGCHECK_WATCHDOG_PROTOCOL_UNBIND

    +

    There was a timeout while unbinding a protocol driver.

  • +
  • 0x11 : NDIS_BUGCHECK_WATCHDOG_FILTER_PAUSE

    +

    There was a timeout while pausing a filter driver.

  • +
  • 0x12 : NDIS_BUGCHECK_WATCHDOG_FILTER_NETPNPEVENT

    +

    There was a timeout while delivering a NET_PNP_EVENT_NOTIFICATION to a filter driver.

  • +
  • 0x13 : NDIS_BUGCHECK_WATCHDOG_FILTER_STATUS_INDICATION

    +

    There was a timeout while delivering a status indication to a filter driver.

  • +
  • 0x14 : NDIS_BUGCHECK_WATCHDOG_FILTER_DETACH

    +

    There was a timeout while detaching a filter driver.

  • +
  • 0x21 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_PAUSE

    +

    There was a timeout while pausing a miniport adapter.

  • +
  • 0x22 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_HALT

    +

    There was a timeout while halting a miniport adapter.

  • +
  • 0x23 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_OID

    +

    There was a timeout while delivering an OID request to a miniport adapter.

  • +
  • 0x24 : NDIS_BUGCHECK_WATCHDOG_FILTER_OID

    +

    There was a timeout while delivering an OID request to a filter driver.

  • +
  • 0x25 : NDIS_BUGCHECK_WATCHDOG_MINIPORT_IDLE

    +

    There was a timeout while idling a miniport adapter.

  • +
  • 0x26 : NDIS_BUGCHECK_WATCHDOG_CANCEL_IDLE

    +

    There was a timeout while canceling an idle request on a miniport adapter.

  • +

Cast to ndis!NDIS_WATCHDOG_TRIAGE_BLOCK. Useful fields:

+
    +
  • StartTime shows what time the operation started, in 100ns units, as returned by KeQueryInterruptTime.
  • +
  • TimeoutMilliseconds shows how long NDIS waited, at a minimum, before triggering this bugcheck.
  • +
  • TargetObject is a handle to the protocol, filter module, or miniport adapter that NDIS is waiting on. Run [!ndiskd.protocol](-ndiskd-protocol.md), [!ndiskd.filter](-ndiskd-filter.md), or [!ndiskd.netadapter](-ndiskd-netadapter.md) with this handle for more information.
  • +
  • PrimaryThread is the thread on which NDIS initiated the operation. Usually, this is the first place to look, although the thread may have gone elsewhere if the operation is being handled asynchronously.
  • +

The value of Parameter 4 depends on the value of Parameter 2. Each number in this list corresponds to the same hexadecimal value in Parameter 2.

+
    +
  • 0x01 : 0
  • +
  • 0x02 : The NET_PNP_EVENT_CODE of the stuck event. For more information about these codes, see [NET_PNP_EVENT](https://msdn.microsoft.com/library/windows/hardware/ff568751)..
  • +
  • 0x03 : The NDIS_STATUS code of the stuck indication. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x04 : 0
  • +
  • 0x11 : 0
  • +
  • 0x12 : The NET_PNP_EVENT_CODE of the stuck event. For possible values, see the previous list of values for item 2 in this list.
  • +
  • 0x13 : The NDIS_STATUS code of the stuck indication. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x14 : 0
  • +
  • 0x21 : 0
  • +
  • 0x22 : 0
  • +
  • 0x23 : The OID code of the stuck request. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x24 : The OID code of the stuck request. Use [!ndiskd.help](-ndiskd-help.md) to decode it.
  • +
  • 0x25 : 0
  • +
  • 0x26 : 0
  • +

0x26

NDIS_BUGCHECK_INVALID_OID_COMPLETION

+

A miniport driver attempted to complete an OID request that is not currently pending on that miniport driver. This can be caused by the driver trying to complete the same request more than one time.

The miniport driver handle that caused the bugcheck. Run [!ndiskd.minidriver](-ndiskd-minidriver.md) with this handle for more information.

The NDIS OID request the miniport driver was trying to complete. You can try to run [!ndiskd.oid](-ndiskd-oid.md) with this request but the memory might not be valid at this point.

0

0x27

NDIS_BUGCHECK_LEAKED_NBL

+

A driver has leaked a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. Check with [!ndiskd.pendingnbls](-ndiskd-pendingnbls.md) to see any NBLs that are still pending on this driver.

Where the leak was detected. Possible values:

+
    +
  • 0x01 : The leak was detected by the NBL tracker. The driver that is currently deregistering or unbinding is the most likely cause. Look at the callstack of the bugchecking thread. Drivers must not unbind or deregister while they still hold active NBLs.

  • +

0

0

+ +  + +Cause +----- + +Parameter 1 indicates the specific cause of the BUGCODE\_NDIS\_DRIVER bug check. + +Remarks +------- + +The BUGCODE\_NDIS\_DRIVER bugcheck indendifies problems in network drivers. Often, the problem is caused by a NDIS miniport driver. You can get a complete list of NDIS miniport drivers by using [**!ndiskd.netadapter**](-ndiskd-netadapter.md). You can get a bigger picture overview of the network stack with [**!ndiskd.netreport**](-ndiskd-netreport.md). + +This bug check code occurs only on Microsoft Windows Server 2003 and later versions of Windows. In Windows 2000 and Windows XP, the corresponding code is [**bug check 0xD2**](bug-check-0xd2--bugcode-id-driver.md) (BUGCODE\_ID\_DRIVER). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7d--install-more-memory.md b/windows-driver-docs-pr/debugger/bug-check-0x7d--install-more-memory.md new file mode 100644 index 0000000000..082f59b2f1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7d--install-more-memory.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0x7D INSTALL_MORE_MEMORY +description: The INSTALL_MORE_MEMORY bug check has a value of 0x0000007D. This bug check indicates that there is not enough memory to start up the Microsoft Windows operating system. +ms.assetid: 560cfa2b-f000-4dc9-8505-f539f3f56fd6 +keywords: ["Bug Check 0x7D INSTALL_MORE_MEMORY", "INSTALL_MORE_MEMORY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INSTALL_MORE_MEMORY +api_type: +- NA +--- + +# Bug Check 0x7D: INSTALL\_MORE\_MEMORY + + +The INSTALL\_MORE\_MEMORY bug check has a value of 0x0000007D. This bug check indicates that there is not enough memory to start up the Microsoft Windows operating system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INSTALL\_MORE\_MEMORY Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The number of physical pages that are found

2

The lowest physical page

3

The highest physical page

4

0

+ +  + +Cause +----- + +The Windows operating system does not have sufficient memory to complete the startup process. + +Resolution +---------- + +Install more memory. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7e--system-thread-exception-not-handled.md b/windows-driver-docs-pr/debugger/bug-check-0x7e--system-thread-exception-not-handled.md new file mode 100644 index 0000000000..f155788cee --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7e--system-thread-exception-not-handled.md @@ -0,0 +1,118 @@ +--- +title: Bug Check 0x7E SYSTEM_THREAD_EXCEPTION_NOT_HANDLED +description: The SYSTEM_THREAD_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000007E. This bug check indicates that a system thread generated an exception that the error handler did not catch. +ms.assetid: 2ecea74f-21d6-4436-beed-d8cf8ef6b169 +keywords: ["Bug Check 0x7E SYSTEM_THREAD_EXCEPTION_NOT_HANDLED", "SYSTEM_THREAD_EXCEPTION_NOT_HANDLED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_THREAD_EXCEPTION_NOT_HANDLED +api_type: +- NA +--- + +# Bug Check 0x7E: SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED + + +The SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED bug check has a value of 0x0000007E. This bug check indicates that a system thread generated an exception that the error handler did not catch. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The exception code that was not handled

2

The address where the exception occurred

3

The address of the exception record

4

The address of the context record

+ +  + +Cause +----- + +The SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED bug check is a common bug check. To interpret it, you must identify which exception was generated. + +Common exception codes include the following: + +- 0x80000002: STATUS\_DATATYPE\_MISALIGNMENT indicates an unaligned data reference was encountered. + +- 0x80000003: STATUS\_BREAKPOINT indicates a breakpoint or ASSERT was encountered when no kernel debugger was attached to the system. + +- 0xC0000005: STATUS\_ACCESS\_VIOLATION indicates a memory access violation occurred. + +For a complete list of exception codes, see the Ntstatus.h file that is located in the inc directory of the Microsoft Windows Driver Kit (WDK). + +Resolution +---------- + +If you are not equipped to use the Windows debugger to work on this problem, you should use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing bug check 0x7E. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Check with your hardware vendor for any BIOS updates. Hardware issues, such as BIOS incompatibilities, memory conflicts, and IRQ conflicts can also generate this error. + +- You can also disable memory caching/shadowing of the BIOS might to try to resolve the error. You should also run hardware diagnostics, that the system manufacturer supplies. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +**If you plan to debug this problem,** Parameter 2 (the exception address) should identify the driver or function that caused this problem. + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +If exception code 0x80000003 occurs, a hard-coded breakpoint or assertion was hit, but the system was started with the **/NODEBUG** switch. This problem should not occur frequently. If it occurs repeatedly, make sure that a kernel debugger is connected and the system is started with the **/DEBUG** switch. + +If exception code 0x80000002 occurs, the trap frame supplies additional information. + +If a driver is listed by name within the bug check message, disable or remove that driver. If the issue is narrowed down to a single driver, set breakpoints and single step in code to work to locate the failure and gain insight into events leading up to the crash. + +For more information see the following topics: + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +[Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x7f--unexpected-kernel-mode-trap.md b/windows-driver-docs-pr/debugger/bug-check-0x7f--unexpected-kernel-mode-trap.md new file mode 100644 index 0000000000..4f09ee14de --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x7f--unexpected-kernel-mode-trap.md @@ -0,0 +1,113 @@ +--- +title: Bug Check 0x7F UNEXPECTED_KERNEL_MODE_TRAP +description: The UNEXPECTED_KERNEL_MODE_TRAP bug check has a value of 0x0000007F. +ms.assetid: f4fcc2a1-891b-44e9-94bf-e712019f538f +keywords: ["Bug Check 0x7F UNEXPECTED_KERNEL_MODE_TRAP", "UNEXPECTED_KERNEL_MODE_TRAP"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNEXPECTED_KERNEL_MODE_TRAP +api_type: +- NA +--- + +# Bug Check 0x7F: UNEXPECTED\_KERNEL\_MODE\_TRAP + + +The UNEXPECTED\_KERNEL\_MODE\_TRAP bug check has a value of 0x0000007F. This bug check indicates that the Intel CPU generated a trap and the kernel failed to catch this trap. + +This trap could be a *bound trap* (a trap the kernel is not permitted to catch) or a *double fault* (a fault that occurred while processing an earlier fault, which always results in a system failure). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UNEXPECTED\_KERNEL\_MODE\_TRAP Parameters + + +The first parameter that appears on the blue screen specifies the trap number. + +The most common trap codes include the following: + +- 0x00000000, or Divide by Zero Error, indicates that a DIV instruction is executed and the divisor is zero. Memory corruption, other hardware problems, or software failures can cause this error. + +- 0x00000004, or Overflow, occurs when the processor executes a call to an interrupt handler when the overflow (OF) flag is set. + +- 0x00000005, or Bounds Check Fault, indicates that the processor, while executing a BOUND instruction, finds that the operand exceeds the specified limits. A BOUND instruction ensures that a signed array index is within a certain range. + +- 0x00000006, or Invalid Opcode, indicates that the processor tries to execute an invalid instruction. This error typically occurs when the instruction pointer has become corrupted and is pointing to the wrong location. The most common cause of this error is hardware memory corruption. + +- 0x00000008, or Double Fault, indicates that an exception occurs during a call to the handler for a prior exception. Typically, the two exceptions are handled serially. However, there are several exceptions that cannot be handled serially, and in this situation the processor signals a double fault. There are two common causes of a double fault: + - A kernel stack overflow. This overflow occurs when a guard page is hit, and the kernel tries to push a trap frame. Because there is no stack left, a stack overflow results, causing the double fault. If you think this overview has occurred, use [**!thread**](-thread.md) to determine the stack limits, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) with a large parameter (for example, **kb 100**) to display the full stack. + - A hardware problem. + +The less-common trap codes include the following: + +- 0x00000001 -- A system-debugger call + +- 0x00000003 -- A debugger breakpoint + +- 0x00000007 -- A hardware coprocessor instruction with no coprocessor present + +- 0x0000000A -- A corrupted Task State Segment + +- 0x0000000B -- An access to a memory segment that was not present + +- 0x0000000C -- An access to memory beyond the limits of a stack + +- 0x0000000D -- An exception not covered by some other exception; a protection fault that pertains to access violations for applications + +For other trap numbers, see an Intel architecture manual. + +Cause +----- + +Bug check 0x7F typically occurs after you install a faulty or mismatched hardware (especially memory) or if installed hardware fails. + +A double fault can occur when the kernel stack overflows. This overflow occurs if multiple drivers are attached to the same stack. For example, if two file system filter drivers are attached to the same stack and then the file system recurses back in, the stack overflows. + +Resolution +---------- + +**Debugging:** Always begin with the [**!analyze**](-analyze.md) extension. + +If this extension is not sufficient, use the [**kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) debugger command. + +- If **kv** shows a **taskGate**, use the [**.tss (Display Task State Segment)**](-tss--display-task-state-segment-.md) command on the part before the colon. + +- If **kv** shows a trap frame, use the [**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) command to format the frame. + +- Otherwise, use the [**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) command on the appropriate frame. (On x86-based platforms, this frame is associated with the procedure **NT!KiTrap**.) + +After using one of these commands, use **kv** again to display the new stack. + +**Troubleshooting:** If you recently added hardware to the computer, remove it to see if the error recurs. If existing hardware has failed, remove or replace the faulty component. Run hardware diagnostics that the system manufacturer supplies to determine which hardware component failed. + +The memory scanner is especially important. Faulty or mismatched memory can cause this bug check. For more information about these procedures, see the owner's manual for your computer. Check that all adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure adapter card contacts are clean. + +If the error appears on a newly installed system, check the availability of updates for the BIOS, the SCSI controller, or network cards. These kind of updates are typically available on the Web site or BBS of the hardware manufacturer. + +Confirm that all hard disk drives, hard disk controllers, and SCSI adapters are compatible with the installed version of Windows. For example, you can get information about compatibility with Windows 7 at the [Windows 7 Compatibility Center](http://go.microsoft.com/fwlink/p/?LinkID=246806). + +If the error occurred after the installation of a new or updated device driver, you should remove or replace the driver. If, under this circumstance, the error occurs during the startup sequence and the system partition is formatted with NTFS, you might be able to use Safe Mode to rename or delete the faulty driver. If the driver is used as part of the system startup process in Safe Mode, you have to start the computer by using the Recovery Console in order to access the file. + +Also restart your computer, and then press F8 at the character-based menu that displays the operating system choices. At the **Advanced Options** menu, select the **Last Known Good Configuration** option. This option is most effective when you add only one driver or service at a time. + +Overclocking (setting the CPU to run at speeds above the rated specification) can cause this error. If you have overclocked the computer that is experiencing the error, return the CPU to the default clock speed setting. + +Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing the error. You can also disable memory caching of the BIOS to try to resolve the problem. + +If you encountered this error while upgrading to a new version of the Windows operating system, the error might be caused by a device driver, a system service, a virus scanner, or a backup tool that is incompatible with the new version. If possible, remove all third-party device drivers and system services and disable any virus scanners before you upgrade. Contact the software manufacturer to obtain updates of these tools. Also make sure that you have installed the latest Windows Service Pack. + +Finally, if all the above steps do not resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective component on the motherboard can also cause this error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x8--irql-not-dispatch-level.md b/windows-driver-docs-pr/debugger/bug-check-0x8--irql-not-dispatch-level.md new file mode 100644 index 0000000000..46678e84f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x8--irql-not-dispatch-level.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x8 IRQL_NOT_DISPATCH_LEVEL +description: The IRQL_NOT_DISPATCH_LEVEL bug check has a value of 0x00000008.This bug check appears very infrequently. +ms.assetid: e37a2fa2-2a0c-4259-91cc-bb8ccd411189 +keywords: ["Bug Check 0x8 IRQL_NOT_DISPATCH_LEVEL", "IRQL_NOT_DISPATCH_LEVEL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IRQL_NOT_DISPATCH_LEVEL +api_type: +- NA +--- + +# Bug Check 0x8: IRQL\_NOT\_DISPATCH\_LEVEL + + +The IRQL\_NOT\_DISPATCH\_LEVEL bug check has a value of 0x00000008. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x80--nmi-hardware-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x80--nmi-hardware-failure.md new file mode 100644 index 0000000000..a30deb2d72 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x80--nmi-hardware-failure.md @@ -0,0 +1,47 @@ +--- +title: Bug Check 0x80 NMI_HARDWARE_FAILURE +description: The NMI_HARDWARE_FAILURE bug check has a value of 0x00000080. This bug check indicates that a hardware malfunction has occurred. +ms.assetid: 1b376540-d101-44af-8295-d8078a920c67 +keywords: ["Bug Check 0x80 NMI_HARDWARE_FAILURE", "NMI_HARDWARE_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NMI_HARDWARE_FAILURE +api_type: +- NA +--- + +# Bug Check 0x80: NMI\_HARDWARE\_FAILURE + + +The NMI\_HARDWARE\_FAILURE bug check has a value of 0x00000080. This bug check indicates that a hardware malfunction has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NMI\_HARDWARE\_FAILURE Parameters + + +None + +Cause +----- + +A variety of hardware malfunctions can cause the NMI\_HARDWARE\_FAILURE bug check. The exact cause is difficult to determine. + +Resolution +---------- + +Remove any hardware or drivers that have been recently installed. Make sure that all memory modules are of the same type. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x81--spin-lock-init-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x81--spin-lock-init-failure.md new file mode 100644 index 0000000000..02c4464f1c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x81--spin-lock-init-failure.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x81 SPIN_LOCK_INIT_FAILURE +description: The SPIN_LOCK_INIT_FAILURE bug check has a value of 0x00000081.This bug check appears very infrequently. +ms.assetid: 0af215f5-e7f6-47bd-86e7-9cb3dd1524be +keywords: ["Bug Check 0x81 SPIN_LOCK_INIT_FAILURE", "SPIN_LOCK_INIT_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SPIN_LOCK_INIT_FAILURE +api_type: +- NA +--- + +# Bug Check 0x81: SPIN\_LOCK\_INIT\_FAILURE + + +The SPIN\_LOCK\_INIT\_FAILURE bug check has a value of 0x00000081. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x82--dfs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x82--dfs-file-system.md new file mode 100644 index 0000000000..e1431bc56b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x82--dfs-file-system.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x82 DFS_FILE_SYSTEM +description: The DFS_FILE_SYSTEM bug check has a value of 0x00000082.This bug check appears very infrequently. +ms.assetid: 70e19e56-4fad-40fe-a1fe-8bc638e094e3 +keywords: ["Bug Check 0x82 DFS_FILE_SYSTEM", "DFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x82: DFS\_FILE\_SYSTEM + + +The DFS\_FILE\_SYSTEM bug check has a value of 0x00000082. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x85--setup-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x85--setup-failure.md new file mode 100644 index 0000000000..5087aadfeb --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x85--setup-failure.md @@ -0,0 +1,112 @@ +--- +title: Bug Check 0x85 SETUP_FAILURE +description: The SETUP_FAILURE bug check has a value of 0x00000085. This bug check indicates that a fatal error occurred during setup. +ms.assetid: 52c93485-7c20-4a7e-8fc7-d520753973ed +keywords: ["Bug Check 0x85 SETUP_FAILURE", "SETUP_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SETUP_FAILURE +api_type: +- NA +--- + +# Bug Check 0x85: SETUP\_FAILURE + + +The SETUP\_FAILURE bug check has a value of 0x00000085. This bug check indicates that a fatal error occurred during setup. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SETUP\_FAILURE Parameters + + +Parameter 1 indicates the type of violation. Parameter 4 is not used. The meaning of the other parameters depends on the value of Parameter 1. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Cause

0x0

0

0

The OEM HAL font is not a valid .fon format file, so setup cannot display text.

+

This cause indicates that Vgaxxx.fon on the boot floppy or CD is damaged.

0x1

The precise video initialization failure:

+

0:NtCreateFile of \device\video0

+

1: IOCTL_VIDEO_QUERY_NUM_AVAIL_MODES

+

2: IOCTL_VIDEO_QUERY_AVAIL_MODES

+

3: The desired video mode is not supported. This value indicates an internal setup error.

+

4: IOCTL_VIDEO_SET_CURRENT_MODE (unable to set video mode)

+

5: IOCTL_VIDEO_MAP_VIDEO_MEMORY

+

6: IOCTL_VIDEO_LOAD_AND_SET_FONT

The status code from the NT API call, if appropriate

Video initialization failed.

+

This failure might indicate that the disk that contains Vga.sys (or another video driver that is appropriate to the computer) is damaged or that the computer has video hardware that the Microsoft Windows operating system cannot communicate with.

+

0x2

0

0

Out of memory.

+

0x3

The precise keyboard initialization failure:

+

0:NtCreateFile of \device\KeyboardClass0 failed. (Setup did not find a keyboard connected to the computer.)

+

1: Unable to load keyboard layout DLL. (Setup could not load the keyboard layout file. This failure indicates that the CD or floppy disk is missing a file, such as Kbdus.dll for the U.S. release or another layout DLL for localized releases.)

0

Keyboard initialization failed.

+

This failure might indicate that the disk that contains the keyboard driver (I8042prt.sys or Kbdclass.sys) is damaged or that the computer has keyboard hardware that Windows cannot communicate with. This failure might also mean that the keyboard layout DLL could not be loaded.

+

0x4

0

0

Setup could not resolve the ARC device path name of the device that setup was started from.

+

This error is an internal setup error.

0x5

Reserved

Reserved

Partitioning sanity check failed.

+

This error indicates a bug in a disk driver.

+

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x8b--mbr-checksum-mismatch.md b/windows-driver-docs-pr/debugger/bug-check-0x8b--mbr-checksum-mismatch.md new file mode 100644 index 0000000000..899a62bd69 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x8b--mbr-checksum-mismatch.md @@ -0,0 +1,80 @@ +--- +title: Bug Check 0x8B MBR_CHECKSUM_MISMATCH +description: The MBR_CHECKSUM_MISMATCH bug check has a value of 0x0000008B. This bug check indicates that a mismatch has occurred in the MBR checksum. +ms.assetid: 7db57605-b6ff-49b9-8a79-3325512825b9 +keywords: ["Bug Check 0x8B MBR_CHECKSUM_MISMATCH", "MBR_CHECKSUM_MISMATCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MBR_CHECKSUM_MISMATCH +api_type: +- NA +--- + +# Bug Check 0x8B: MBR\_CHECKSUM\_MISMATCH + + +The MBR\_CHECKSUM\_MISMATCH bug check has a value of 0x0000008B. This bug check indicates that a mismatch has occurred in the MBR checksum. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MBR\_CHECKSUM\_MISMATCH Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The disk signature from MBR

2

The MBR checksum that the OS Loader calculates

3

The MBR checksum that the system calculates

4

Reserved

+ +  + +Cause +----- + +The MBR\_CHECKSUM\_MISMATCH bug check occurs during the boot process when the MBR checksum that the Microsoft Windows operating system calculates does not match the checksum that the loader passes in. + +This error typically indicates a virus. + +Resolution +---------- + +There are many forms of viruses and not all can be detected. Typically, the newer viruses usually can be detected only by a virus scanner that has recently been upgraded. You should boot with a write-protected disk that contains a virus scanner and try to clean out the infection. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x8e--kernel-mode-exception-not-handled.md b/windows-driver-docs-pr/debugger/bug-check-0x8e--kernel-mode-exception-not-handled.md new file mode 100644 index 0000000000..6855cabb81 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x8e--kernel-mode-exception-not-handled.md @@ -0,0 +1,120 @@ +--- +title: Bug Check 0x8E KERNEL_MODE_EXCEPTION_NOT_HANDLED +description: The KERNEL_MODE_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000008E. This bug check indicates that a kernel-mode application generated an exception that the error handler did not catch. +ms.assetid: 987ee868-5622-44e4-979c-3ae93a98b5b1 +keywords: ["Bug Check 0x8E KERNEL_MODE_EXCEPTION_NOT_HANDLED", "KERNEL_MODE_EXCEPTION_NOT_HANDLED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_MODE_EXCEPTION_NOT_HANDLED +api_type: +- NA +--- + +# Bug Check 0x8E: KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED + + +The KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED bug check has a value of 0x0000008E. This bug check indicates that a kernel-mode application generated an exception that the error handler did not catch. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The exception code that was not handled

2

The address where the exception occurred

3

The trap frame

4

Reserved

+ +  + +Cause +----- + +The KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED bug check is a very common bug check. To interpret it, you must identify which exception was generated. + +Common exception codes include the following: + +- 0x80000002: STATUS\_DATATYPE\_MISALIGNMENT indicates that an unaligned data reference was encountered. + +- 0x80000003: STATUS\_BREAKPOINT indicates that a breakpoint or ASSERT was encountered when no kernel debugger was attached to the system. + +- 0xC0000005: STATUS\_ACCESS\_VIOLATION indicates that a memory access violation occurred. + +For a complete list of exception codes, see the Ntstatus.h file that is located in the inc directory of the Microsoft Windows Driver Kit (WDK). + +Resolution +---------- + +If you are not equipped to debug this problem, you should use some basic troubleshooting techniques: + +- Make sure you have enough disk space. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Try changing video adapters. + +- Check with your hardware vendor for any BIOS updates. + +- Disable BIOS memory options such as caching or shadowing. + +If you plan to debug this problem, you might find it difficult to obtain a stack trace. Parameter 2 (the exception address) should identify the driver or function that caused this problem. + +If exception code 0x80000003 occurs, a hard-coded breakpoint or assertion was hit, but the computer was started with the **/NODEBUG** switch. This problem should rarely occur. If it occurs repeatedly, make sure that a kernel debugger is connected and that the computer is started with the **/DEBUG** switch. + +If exception code 0x80000002 occurs, the trap frame supplies additional information. + +If you do not know the specific cause of the exception, consider the following items: + +- Hardware incompatibility. Make sure that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about compatibility with Windows 7 at the [Windows 7 Compatibility Center](http://go.microsoft.com/fwlink/p/?LinkID=246806). + +- Faulty device driver or system service. A faulty device driver or system service might be responsible for this error. Hardware issues, such as BIOS incompatibilities, memory conflicts, and IRQ conflicts can also generate this error. + +If the bug check message lists a driver by name , disable or remove that driver. Also, disable or remove any drivers or services that were recently added. If the error occurs during the startup sequence and the system partition is formatted with NTFS file system, you might be able to use Safe Mode to rename or delete the faulty driver. If the driver is used as part of the system startup process in Safe Mode, you have to start the computer by using the Recovery Console to access the file. + +If the problem is associated with Win32k.sys, the source of the error might be a third-party remote control program. If such software is installed, you can remove the service by starting the system by using the Recovery Console and then deleting the offending system service file. + +Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing bug check 0x8E. You can disable memory caching of the BIOS to try to resolve the error. You should also run hardware diagnostics, especially the memory scanner, that the system manufacturer supplies. For more information about these procedures, see the owner's manual for your computer. + +The error that generates this message can occur after the first restart during Windows Setup, or after Setup is finished. A possible cause of the error is lack of disk space for installation and system BIOS incompatibilities. For problems during Windows installation that are associated with lack of disk space, reduce the number of files on the target hard disk drive. Check for and delete any temporary files that you do not have to have, Internet cache files, application backup files, and .chk files that contain saved file fragments from disk scans. You can also use another hard disk drive with more free space for the installation. + +You can resolve BIOS problems by upgrading the system BIOS version. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x8f--pp0-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x8f--pp0-initialization-failed.md new file mode 100644 index 0000000000..1a32248680 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x8f--pp0-initialization-failed.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0x8F PP0_INITIALIZATION_FAILED +description: The PP0_INITIALIZATION_FAILED bug check has a value of 0x0000008F. This bug check indicates that the Plug and Play (PnP) manager could not be initialized. +ms.assetid: 2e369d1a-51b1-4f65-8afb-b362ad48b703 +keywords: ["Bug Check 0x8F PP0_INITIALIZATION_FAILED", "PP0_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PP0_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x8F: PP0\_INITIALIZATION\_FAILED + + +The PP0\_INITIALIZATION\_FAILED bug check has a value of 0x0000008F. This bug check indicates that the Plug and Play (PnP) manager could not be initialized. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PP0\_INITIALIZATION\_FAILED Parameters + + +None + +Cause +----- + +An error occurred during Phase 0 initialization of the kernel-mode PnP manager. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9--irql-not-greater-or-equal.md b/windows-driver-docs-pr/debugger/bug-check-0x9--irql-not-greater-or-equal.md new file mode 100644 index 0000000000..65cbacafe6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9--irql-not-greater-or-equal.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x9 IRQL_NOT_GREATER_OR_EQUAL +description: The IRQL_NOT_GREATER_OR_EQUAL bug check has a value of 0x00000009.This bug check appears very infrequently. +ms.assetid: d48f1681-df49-4cc3-a22d-84e090e7d774 +keywords: ["Bug Check 0x9 IRQL_NOT_GREATER_OR_EQUAL", "IRQL_NOT_GREATER_OR_EQUAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IRQL_NOT_GREATER_OR_EQUAL +api_type: +- NA +--- + +# Bug Check 0x9: IRQL\_NOT\_GREATER\_OR\_EQUAL + + +The IRQL\_NOT\_GREATER\_OR\_EQUAL bug check has a value of 0x00000009. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x90--pp1-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0x90--pp1-initialization-failed.md new file mode 100644 index 0000000000..f058e4a10d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x90--pp1-initialization-failed.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0x90 PP1_INITIALIZATION_FAILED +description: The PP1_INITIALIZATION_FAILED bug check has a value of 0x00000090. This bug check indicates that the Plug and Play (PnP) manager could not be initialized. +ms.assetid: 8dd46d24-0174-4310-953e-7b451ae34c71 +keywords: ["Bug Check 0x90 PP1_INITIALIZATION_FAILED", "PP1_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PP1_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0x90: PP1\_INITIALIZATION\_FAILED + + +The PP1\_INITIALIZATION\_FAILED bug check has a value of 0x00000090. This bug check indicates that the Plug and Play (PnP) manager could not be initialized. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PP1\_INITIALIZATION\_FAILED Parameters + + +None + +Cause +----- + +An error occurred during Phase 1 initialization of the kernel-mode PnP manager. + +Phase 1 is where most of the initialization is done, including setting up the registry files and other environment settings for drivers to call during the subsequent I/O initialization. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x92--up-driver-on-mp-system.md b/windows-driver-docs-pr/debugger/bug-check-0x92--up-driver-on-mp-system.md new file mode 100644 index 0000000000..6b19828134 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x92--up-driver-on-mp-system.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x92 UP_DRIVER_ON_MP_SYSTEM +description: The UP_DRIVER_ON_MP_SYSTEM bug check has a value of 0x00000092. This bug check indicates that a uniprocessor-only driver has been loaded on a multiprocessor system. +ms.assetid: 1e26c7b1-bfa5-4a32-a483-5ce8179ac6b7 +keywords: ["Bug Check 0x92 UP_DRIVER_ON_MP_SYSTEM", "UP_DRIVER_ON_MP_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UP_DRIVER_ON_MP_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x92: UP\_DRIVER\_ON\_MP\_SYSTEM + + +The UP\_DRIVER\_ON\_MP\_SYSTEM bug check has a value of 0x00000092. This bug check indicates that a uniprocessor-only driver has been loaded on a multiprocessor system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UP\_DRIVER\_ON\_MP\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The base address of the driver

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +A driver that is compiled to work only on uniprocessor machines has been loaded, but the Microsoft Windows operating system is running on a multiprocessor system with more than one active processor. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x93--invalid-kernel-handle.md b/windows-driver-docs-pr/debugger/bug-check-0x93--invalid-kernel-handle.md new file mode 100644 index 0000000000..35cac61814 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x93--invalid-kernel-handle.md @@ -0,0 +1,74 @@ +--- +title: Bug Check 0x93 INVALID_KERNEL_HANDLE +description: The INVALID_KERNEL_HANDLE bug check has a value of 0x00000093. This bug check indicates that an invalid or protected handle was passed to NtClose. +ms.assetid: c8564da7-cdbf-40f5-94f4-b1fac23b8b42 +keywords: ["Bug Check 0x93 INVALID_KERNEL_HANDLE", "INVALID_KERNEL_HANDLE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_KERNEL_HANDLE +api_type: +- NA +--- + +# Bug Check 0x93: INVALID\_KERNEL\_HANDLE + + +The INVALID\_KERNEL\_HANDLE bug check has a value of 0x00000093. This bug check indicates that an invalid or protected handle was passed to **NtClose**. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_KERNEL\_HANDLE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The handle that is passed to NtClose

2

0: The caller tried to close a protected handle

+

1: The caller tried to close an invalid handle

3

Reserved

4

Reserved

+ +  + +Cause +----- + +The INVALID\_KERNEL\_HANDLE bug check indicates that some kernel code (for example, a server, redirector, or another driver) tried to close an invalid handle or a protected handle. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x94--kernel-stack-locked-at-exit.md b/windows-driver-docs-pr/debugger/bug-check-0x94--kernel-stack-locked-at-exit.md new file mode 100644 index 0000000000..0206473e0f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x94--kernel-stack-locked-at-exit.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x94 KERNEL_STACK_LOCKED_AT_EXIT +description: The KERNEL_STACK_LOCKED_AT_EXIT bug check has a value of 0x00000094. This bug check indicates that a thread exited while its kernel stack was marked as not swappable. +ms.assetid: cc0962f0-4d2b-4092-821c-a47a59bedbf0 +keywords: ["Bug Check 0x94 KERNEL_STACK_LOCKED_AT_EXIT", "KERNEL_STACK_LOCKED_AT_EXIT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KERNEL_STACK_LOCKED_AT_EXIT +api_type: +- NA +--- + +# Bug Check 0x94: KERNEL\_STACK\_LOCKED\_AT\_EXIT + + +The KERNEL\_STACK\_LOCKED\_AT\_EXIT bug check has a value of 0x00000094. This bug check indicates that a thread exited while its kernel stack was marked as not swappable + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## KERNEL\_STACK\_LOCKED\_AT\_EXIT Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x96--invalid-work-queue-item.md b/windows-driver-docs-pr/debugger/bug-check-0x96--invalid-work-queue-item.md new file mode 100644 index 0000000000..7816de9204 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x96--invalid-work-queue-item.md @@ -0,0 +1,79 @@ +--- +title: Bug Check 0x96 INVALID_WORK_QUEUE_ITEM +description: The INVALID_WORK_QUEUE_ITEM bug check has a value of 0x00000096. This bug check indicates that a queue entry was removed that contained a NULL pointer. +ms.assetid: 18d7d8b2-814c-4207-aac9-e3affc2ccebd +keywords: ["Bug Check 0x96 INVALID_WORK_QUEUE_ITEM", "INVALID_WORK_QUEUE_ITEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_WORK_QUEUE_ITEM +api_type: +- NA +--- + +# Bug Check 0x96: INVALID\_WORK\_QUEUE\_ITEM + + +The INVALID\_WORK\_QUEUE\_ITEM bug check has a value of 0x00000096. This bug check indicates that a queue entry was removed that contained a **NULL** pointer. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_WORK\_QUEUE\_ITEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the queue entry whose flink or blink field is NULL.

2

The address of the queue that is being referenced. Typically, this queue is an ExWorkerQueue.

3

The base address of the ExWorkerQueue array. (This address helps you determine if the queue in question is indeed an ExWorkerQueue. If the queue is an ExWorkerQueue, the offset from this parameter will isolate the queue.)

4

Assuming the queue is an ExWorkerQueue, this value is the address of the worker routine that would have been called if the work item had been valid. (You can use this address to isolate the driver that is misusing the work queue.)

+ +  + +Cause +----- + +The INVALID\_WORK\_QUEUE\_ITEM bug check occurs when **KeRemoveQueue** removes a queue entry whose **flink** or **blink** field is **NULL**. + +Any queue misuse can cause this error. But typically this error occurs because worker thread work items are misused. + +An entry on a queue can be inserted on the list only one time. When an item is removed from a queue, its **flink** field is set to **NULL**. Then, when this item is removed the second time, this bug check occurs. + +In most situations, the queue that is being referenced is an **ExWorkerQueue** (executive worker queue). To help identify the driver that caused the error, Parameter 4 displays the address of the worker routine that would have been called if this work item had been valid. However, if the queue that is being referenced is not an **ExWorkerQueue**, this parameter is not useful. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x97--bound-image-unsupported.md b/windows-driver-docs-pr/debugger/bug-check-0x97--bound-image-unsupported.md new file mode 100644 index 0000000000..77142003ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x97--bound-image-unsupported.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0x97 BOUND_IMAGE_UNSUPPORTED +description: The BOUND_IMAGE_UNSUPPORTED bug check has a value of 0x00000097.This bug check appears very infrequently. +ms.assetid: 51d96612-d7a4-4e0f-b83b-208311cf1e1a +keywords: ["Bug Check 0x97 BOUND_IMAGE_UNSUPPORTED", "BOUND_IMAGE_UNSUPPORTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BOUND_IMAGE_UNSUPPORTED +api_type: +- NA +--- + +# Bug Check 0x97: BOUND\_IMAGE\_UNSUPPORTED + + +The BOUND\_IMAGE\_UNSUPPORTED bug check has a value of 0x00000097. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x98--end-of-nt-evaluation-period.md b/windows-driver-docs-pr/debugger/bug-check-0x98--end-of-nt-evaluation-period.md new file mode 100644 index 0000000000..096b3b6a60 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x98--end-of-nt-evaluation-period.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0x98 END_OF_NT_EVALUATION_PERIOD +description: The END_OF_NT_EVALUATION_PERIOD bug check has a value of 0x00000098. This bug check indicates that the trial period for the Microsoft Windows operating system has ended. +ms.assetid: e49ea686-27b9-4743-9339-766b4748e29b +keywords: ["Bug Check 0x98 END_OF_NT_EVALUATION_PERIOD", "END_OF_NT_EVALUATION_PERIOD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- END_OF_NT_EVALUATION_PERIOD +api_type: +- NA +--- + +# Bug Check 0x98: END\_OF\_NT\_EVALUATION\_PERIOD + + +The END\_OF\_NT\_EVALUATION\_PERIOD bug check has a value of 0x00000098. This bug check indicates that the trial period for the Microsoft Windows operating system has ended. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## END\_OF\_NT\_EVALUATION\_PERIOD Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The low-order 32 bits of the product expiration date

2

The high-order 32 bits of the product expiration date

3

Reserved

4

Reserved

+ +  + +Cause +----- + +Your installation of the Windows operating system is an evaluation unit with an expiration date. The trial period is over. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x99--invalid-region-or-segment.md b/windows-driver-docs-pr/debugger/bug-check-0x99--invalid-region-or-segment.md new file mode 100644 index 0000000000..31e44c0299 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x99--invalid-region-or-segment.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0x99 INVALID_REGION_OR_SEGMENT +description: The INVALID_REGION_OR_SEGMENT bug check has a value of 0x00000099. This bug check indicates that ExInitializeRegion or ExInterlockedExtendRegion was called with an invalid set of parameters. +ms.assetid: 353b9028-7ba4-405e-9ac9-f3c12fd595ab +keywords: ["Bug Check 0x99 INVALID_REGION_OR_SEGMENT", "INVALID_REGION_OR_SEGMENT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_REGION_OR_SEGMENT +api_type: +- NA +--- + +# Bug Check 0x99: INVALID\_REGION\_OR\_SEGMENT + + +The INVALID\_REGION\_OR\_SEGMENT bug check has a value of 0x00000099. This bug check indicates that **ExInitializeRegion** or **ExInterlockedExtendRegion** was called with an invalid set of parameters. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_REGION\_OR\_SEGMENT Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9a--system-license-violation.md b/windows-driver-docs-pr/debugger/bug-check-0x9a--system-license-violation.md new file mode 100644 index 0000000000..d5c82e4619 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9a--system-license-violation.md @@ -0,0 +1,259 @@ +--- +title: Bug Check 0x9A SYSTEM_LICENSE_VIOLATION +description: The SYSTEM_LICENSE_VIOLATION bug check has a value of 0x0000009A. This bug check indicates that the software license agreement has been violated. +ms.assetid: 742d864c-46f8-4d7f-8617-061c75fe833a +keywords: ["Bug Check 0x9A SYSTEM_LICENSE_VIOLATION", "SYSTEM_LICENSE_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_LICENSE_VIOLATION +api_type: +- NA +--- + +# Bug Check 0x9A: SYSTEM\_LICENSE\_VIOLATION + + +The SYSTEM\_LICENSE\_VIOLATION bug check has a value of 0x0000009A. This bug check indicates that the software license agreement has been violated. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_LICENSE\_VIOLATION Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x00

0: The product should be WinNT

+

1: The product should be LanmanNT or ServerNT

A partial serial number

The first two characters of the product type from the product options

Offline product type changes have been attempted.

0x01

The registered evaluation time from source 1

A partial serial number

The registered evaluation time from an alternate source

Offline changes to the Microsoft Windows evaluation unit time period have been attempted.

0x02

The status code that is associated with the open failure

0

0

The setup key could not be opened.

0x03

The status code that is associated with the key lookup failure

0

0

The SetupType or SetupInProgress value from the setup key is missing, so setup mode could not be detected.

0x04

The status code that is associated with the key lookup failure

0

0

The SystemPrefix value from the setup key is missing.

0x05

(See the setup code)

An invalid value was found in licensed processors

The officially licensed number of processors

Offline changes to the number of licensed processors have been attempted.

0x06

The status code that is associated with the open failure

0

0

The ProductOptions key could not be opened.

0x07

The status code that is associated with the read failure

0

0

The ProductType value could not be read.

0x08

The status code that is associated with the Change Notify failure

0

0

Change Notify on ProductOptions failed.

0x09

The status code that is associated with the Change Notify failure

0

0

Change Notify on SystemPrefix failed.

0x0A

0

0

0

An NTW system was converted to an NTS system.

0x0B

The status code that is associated with the change failure

0

0

The reference of the setup key failed.

0x0C

The status code that is associated with the change failure

0

0

The reference of the product options key failed.

0x0D

The status code that is associated with the failure

0

0

The attempt to open ProductOptions in the worker thread failed.

0x0F

The status code that is associated with the failure

0

0

The attempt to open the setup key failed.

0x10

The status code that is associated with the failure

0: set value failed

+

1: Change Notify failed

0

A failure occurred in the setup key worker thread.

0x11

The status code that is associated with the failure

0: set value failed

+

1: Change Notify failed

0

A failure occurred in the product options key worker thread.

0x12

The status code that is associated with the failure

0

0

Unable to open the LicenseInfoSuites key for the suite.

0x13

The status code that is associated with the failure

0

0

Unable to query the LicenseInfoSuites key for the suite.

0x14

The size of the memory allocation

0

0

Unable to allocate memory.

0x15

The status code that is associated with the failure

Reserved

0

Unable to reset the ConcurrentLimit value for the suite key.

0x16

The status code that is associated with the failure

0

0

Unable to open the license key for a suite product.

0x17

The status code that is associated with the failure

0

0

Unable to reset the ConcurrentLimit value for a suite product.

0x18

The status code that is associated with the open failure

Reserved

0

Unable to start the Change Notify for the LicenseInfoSuites.

0x19

0

0

0

A suite is running on a system that must be PDC.

0x1A

The status code that is associated with the failure

0

0

A failure occurred when enumerating the suites.

0x1B

0

0

0

Changes to the policy cache were attempted.

+ +  + +Cause +----- + +The Microsoft Windows operating system detects a violation of the software license agreement. + +A user might have tried to change the product type of an offline system or change the trial period of an evaluation unit of Windows. For more information about the specific violation, see the parameter list. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9b--udfs-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0x9b--udfs-file-system.md new file mode 100644 index 0000000000..336163c1f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9b--udfs-file-system.md @@ -0,0 +1,84 @@ +--- +title: Bug Check 0x9B UDFS_FILE_SYSTEM +description: The UDFS_FILE_SYSTEM bug check has a value of 0x0000009B. This bug check indicates that a problem occurred in the UDF file system. +ms.assetid: cf20429d-6007-47e7-9faa-db7e1489e96b +keywords: ["Bug Check 0x9B UDFS_FILE_SYSTEM", "UDFS_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UDFS_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0x9B: UDFS\_FILE\_SYSTEM + + +The UDFS\_FILE\_SYSTEM bug check has a value of 0x0000009B. This bug check indicates that a problem occurred in the UDF file system. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UDFS\_FILE\_SYSTEM Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

If UdfExceptionFilter is on the stack, this parameter specifies the address of the exception record.

3

If UdfExceptionFilter is on the stack, this parameter specifies the address of the context record.

4

Reserved.

+ +  + +Cause +----- + +The UDFS\_FILE\_SYSTEM bug check might be caused disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted SCSI and IDE drivers can also adversely affect the system's ability to read and write to the disk and cause the error. + +This bug check might also occur if nonpaged pool memory is full. If the nonpaged pool memory is full, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver that requires nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To debug this problem:** Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command with Parameter 3, and then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md). + +**To resolve a disk corruption problem:** Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help identify the device or driver that is causing the error. Disable any virus scanners, backup application, or disk defragmenter tools that continually monitor the system. You should also run hardware diagnostics that the system manufacturer supplies. For more information about these procedures, see the owner's manual for your computer. Run **Chkdsk /f /r** to detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition. + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This memory increases the quantity of nonpaged pool memory that is available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9c--machine-check-exception.md b/windows-driver-docs-pr/debugger/bug-check-0x9c--machine-check-exception.md new file mode 100644 index 0000000000..c932209f0a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9c--machine-check-exception.md @@ -0,0 +1,215 @@ +--- +title: Bug Check 0x9C MACHINE_CHECK_EXCEPTION +description: The MACHINE_CHECK_EXCEPTION bug check has a value of 0x0000009C. This bug check indicates that a fatal machine check exception has occurred. +ms.assetid: b8945dba-c515-4a30-a36c-ef4feaadabbe +keywords: ["Bug Check 0x9C MACHINE_CHECK_EXCEPTION", "MACHINE_CHECK_EXCEPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MACHINE_CHECK_EXCEPTION +api_type: +- NA +--- + +# Bug Check 0x9C: MACHINE\_CHECK\_EXCEPTION + + +The MACHINE\_CHECK\_EXCEPTION bug check has a value of 0x0000009C. This bug check indicates that a fatal machine check exception has occurred. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MACHINE\_CHECK\_EXCEPTION Parameters + + +The four parameters that are listed in the message have different meanings, depending on the processor type. + +If the processor is based on an older x86-based architecture and has the Machine Check Exception (MCE) feature but not the Machine Check Architecture (MCA) feature (for example, the Intel Pentium processor), the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The low 32 bits of P5_MC_TYPE Machine Service Report (MSR)

2

The address of the MCA_EXCEPTION structure

3

The high 32 bits of P5_MC_ADDR MSR

4

The low 32 bits of P5_MC_ADDR MSR

+ +  + +If the processor is based on a newer x86-based architecture and has the MCA feature and the MCE feature (for example, any Intel Processor of family 6 or higher, such as Pentium Pro, Pentium IV, or Xeon), or if the processor is an x64-based processor, the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The bank number

2

The address of the MCA_EXCEPTION structure

3

The high 32 bits of MCi_STATUS MSR for the MCA bank that had the error

4

The low 32 bits of MCi_STATUS MSR for the MCA bank that had the error

+ +  + +On an Itanium-based processor, the parameters have the following meaning. + +**Note**  Parameter 1 indicates the type of violation. + +  + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x1

The address of the log

The size of the log

0

0x2

The address of the log

The size of the log

The error code

The system abstraction layer (SAL) returned an error for SAL_GET_STATEINFO while processing MCA.

0x3

The address of the log

The size of the log

The error code

SAL returned an error for SAL_CLEAR_STATEINFO while it processed MCA.

0x4

The address of the log

The size of the log

0

Firmware (FW) reported a fatal MCA.

0x5

The address of the log

The size of the log

0

There are two possible causes:

+
    +
  • SAL reported a recoverable MCA, but this recovery is not currently supported.

  • +
  • SAL generated an MCA but could not produce an error record.

  • +

0xB

The address of the log

The size of the log

0

0xC

The address of the log

The size of the log

The error code

SAL returned an error for SAL_GET_STATEINFO while processing an INIT event.

0xD

The address of the log

The size of the log

The error code

SAL returned an error for SAL_CLEAR_STATEINFO while it processed an INIT event.

0xE

The address of the log

The size of the log

0

+ +  + +Remarks +------- + +In Windows Vista and later operating systems, this bug check occurs only in the following circumstances. + +- WHEA is not fully initialized. +- All processors that rendezvous have no errors in their registers. + +For other circumstances, this bug check has been replaced with [**bug Check 0x124: WHEA\_UNCORRECTABLE\_ERROR**](bug-check-0x124---whea-uncorrectable-error.md) in Windows Vista and later operating systems. + +For more information about Machine Check Architecture (MCA), see the Intel or AMD Web sites. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9e--user-mode-health-monitor.md b/windows-driver-docs-pr/debugger/bug-check-0x9e--user-mode-health-monitor.md new file mode 100644 index 0000000000..42a359c40a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9e--user-mode-health-monitor.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0x9E USER_MODE_HEALTH_MONITOR +description: The USER_MODE_HEALTH_MONITOR bug check has a value of 0x0000009E. This bug check indicates that one or more critical user-mode components failed to satisfy a health check. +ms.assetid: 5ad56234-5150-4acb-828d-198c2e5fb9b6 +keywords: ["Bug Check 0x9E USER_MODE_HEALTH_MONITOR", "USER_MODE_HEALTH_MONITOR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- USER_MODE_HEALTH_MONITOR +api_type: +- NA +--- + +# Bug Check 0x9E: USER\_MODE\_HEALTH\_MONITOR + + +The USER\_MODE\_HEALTH\_MONITOR bug check has a value of 0x0000009E. This bug check indicates that one or more critical user-mode components failed to satisfy a health check. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## USER\_MODE\_HEALTH\_MONITOR Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The process that failed to satisfy a health check in the configured time-out

2

The health monitoring time-out, in seconds

3

Reserved

4

Reserved

+ +  + +Cause +----- + +Hardware mechanisms, such as watchdog timers, can detect that basic kernel services are not executing. However, resource starvation issues (including memory leaks, lock contention, and scheduling priority misconfiguration) can block critical user-mode components without blocking deferred procedure calls (DPCs) or draining the non-paged pool. + +Kernel components can extend watchdog timer functionality to user mode by periodically monitoring critical applications. This bug check indicates that a user-mode health check failed in a way that prevents graceful shutdown. This bug check restores critical services by restarting or enabling application failover to other servers. + +On the Microsoft Windows Server 2003, Enterprise Edition, Windows Server 2003, Datacenter Edition, and Windows 2000 with Service Pack 4 (SP4) operating systems, a user-mode hang can also cause this bug check. The bug check occurs in this situation only if the user has set **HangRecoveryAction** to a value of 3. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0x9f--driver-power-state-failure.md b/windows-driver-docs-pr/debugger/bug-check-0x9f--driver-power-state-failure.md new file mode 100644 index 0000000000..19af747d21 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0x9f--driver-power-state-failure.md @@ -0,0 +1,319 @@ +--- +title: (Developer Content) Bug Check 0x9F DRIVER_POWER_STATE_FAILURE +description: This bug check has a value of 0x0000009F. This bug check indicates that the driver is in an inconsistent or invalid power state. +ms.assetid: f767fe80-0ec0-45e4-9949-467f50ac601c +keywords: ["(Developer Content) Bug Check 0x9F DRIVER_POWER_STATE_FAILURE", "DRIVER_POWER_STATE_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_POWER_STATE_FAILURE +api_type: +- NA +--- + +# (Developer Content) Bug Check 0x9F: DRIVER\_POWER\_STATE\_FAILURE + + +This bug check has a value of 0x0000009F. This bug check indicates that the driver is in an inconsistent or invalid power state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_POWER\_STATE\_FAILURE Parameters + + +Parameter 1 indicates the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x1

The device object

Reserved

Reserved

The device object that is being freed still has an outstanding power request that it has not completed.

0x2

The target device's device object, if it is available

The device object

The driver object, if it is available

The device object completed the I/O request packet (IRP) for the system power state request, but it did not call PoStartNextPowerIrp.

0x3

The physical device object (PDO) of the stack

The functional device object (FDO) of the stack. In Windows 7 and later, nt!TRIAGE_9F_POWER.

The blocked IRP

A device object has been blocking an IRP for too long a time.

0x4

Time-out value, in seconds.

The thread currently holding onto the Plug-and-Play (PnP) lock.

In Windows 7 and later, nt!TRIAGE_9F_POWER.

The power state transition timed out waiting to synchronize with the PnP subsystem.

0x500

Reserved

The target device's device object, if available

Device object

The device object completed the IRP for the system power state request, but it did not call PoStartNextPowerIrp.

+ +  + +Cause +----- + +For a description of the possible causes, see the description of each code in the Parameters section. + +**Debugging bug check 0x9F when Parameter 1 equals 0x3** + +- In a kernel debugger, use the [**!analyze -v**](-analyze.md) command to perform the initial bug check analysis. The verbose analysis displays the address of the **nt!TRIAGE\_9F\_POWER** structure, which is in Arg3. + + ``` + kd>!analyze -v + ******************************************************************************* + * * + * Bugcheck Analysis * + * * + ******************************************************************************* + + DRIVER_POWER_STATE_FAILURE (9f) + A driver has failed to complete a power IRP within a specific time. + Arguments: + Arg1: 0000000000000003, A device object has been blocking an Irp for too long a time + Arg2: fffffa8007b13440, Physical Device Object of the stack + Arg3: fffff8000386c3d8, nt!TRIAGE_9F_POWER on Win7 and higher, otherwise the Functional Device Object of the stack + Arg4: fffffa800ab61bd0, The blocked IRP + ``` + + The nt!TRIAGE\_9F\_POWER structure provides additional bug check information that might help you determine the cause of this bug check. The structure can provide a list of all outstanding power IRPs, a list of all power IRP worker threads, and a pointer to the delayed system worker queue. + +- Use the [**dt (Display Type)**](dt--display-type-.md) command and specify the nt!TRIAGE\_9F\_POWER structure using the address from Arg3. + + ``` + 0: kd> dt nt!TRIAGE_9F_POWER fffff8000386c3d8 + +0x000 Signature : 0x8000 + +0x002 Revision : 1 + +0x008 IrpList : 0xfffff800`01c78bd0 _LIST_ENTRY [ 0xfffffa80`09f43620 - 0xfffffa80`0ad00170 ] + +0x010 ThreadList : 0xfffff800`01c78520 _LIST_ENTRY [ 0xfffff880`009cdb98 - 0xfffff880`181f2b98 ] + +0x018 DelayedWorkQueue : 0xfffff800`01c6d2d8 _TRIAGE_EX_WORK_QUEUE + ``` + + The [**dt (Display Type)**](dt--display-type-.md) command displays the structure. You can use various debugger commands to follow the LIST\_ENTRY fields to examine the list of outstanding IRPs and the power IRP worker threads. + +- Use the [**!irp**](-irp.md) command to examine the IRP that was blocked. The address of this IRP is in Arg4. + + ``` + 0: kd> !irp fffffa800ab61bd0 + Irp is active with 7 stacks 6 is current (= 0xfffffa800ab61e08) + No Mdl: No System Buffer: Thread 00000000: Irp stack trace. + cmd flg cl Device File Completion-Context + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-00000000 + + Args: 00000000 00000000 00000000 00000000 + >[IRP_MJ_POWER(16), IRP_MN_SET_POWER(2)] + 0 e1 fffffa800783f060 00000000 00000000-00000000 pending + \Driver\HidUsb + Args: 00016600 00000001 00000004 00000006 + [N/A(0), N/A(0)] + 0 0 00000000 00000000 00000000-fffffa800ad00170 + + Args: 00000000 00000000 00000000 00000000 + + + ``` + +- Use the [**!devstack**](-devstack.md) command with the PDO address in Arg2, to display information associated with the faulting driver. + + ``` + 0: kd> !devstack fffffa8007b13440 + !DevObj !DrvObj !DevExt ObjectName + fffffa800783f060 \Driver\HidUsb fffffa800783f1b0 InfoMask field not found for _OBJECT_HEADER at fffffa800783f030 + + > fffffa8007b13440 \Driver\usbhub fffffa8007b13590 Cannot read info offset from nt!ObpInfoMaskToOffset + + !DevNode fffffa8007ac8a00 : + DeviceInst is "USB\VID_04D8&PID_0033\5&46fa7b7&0&1" + ServiceName is "HidUsb" + ``` + +- Use the !poaction command to display the threads that handle the power operations and any allocated power IRPs. + + ``` + 3: kd> !poaction + PopAction: fffff801332f3fe0 + State..........: 0 - Idle + Updates........: 0 + Action.........: None + Lightest State.: Unspecified + Flags..........: 10000003 QueryApps|UIAllowed + Irp minor......: ?? + System State...: Unspecified + Hiber Context..: 0000000000000000 + + Allocated power irps (PopIrpList - fffff801332f44f0) + IRP: ffffe0001d53d8f0 (wait-wake/S0), PDO: ffffe00013cae060 + IRP: ffffe0001049a5d0 (wait-wake/S0), PDO: ffffe00012d42050 + IRP: ffffe00013d07420 (set/D3,), PDO: ffffe00012daf840, CURRENT: ffffe00012dd5040 + IRP: ffffe0001e5ac5d0 (wait-wake/S0), PDO: ffffe00013d33060 + IRP: ffffe0001ed3e420 (wait-wake/S0), PDO: ffffe00013c96060 + IRP: ffffe000195fe010 (wait-wake/S0), PDO: ffffe00012d32050 + + Irp worker threads (PopIrpThreadList - fffff801332f3100) + THREAD: ffffe0000ef5d040 (static) + THREAD: ffffe0000ef5e040 (static), IRP: ffffe00013d07420, DEVICE: ffffe00012dd5040 + + PopAction: fffff801332f3fe0 + State..........: 0 - Idle + Updates........: 0 + Action.........: None + Lightest State.: Unspecified + Flags..........: 10000003 QueryApps|UIAllowed + Irp minor......: ?? + System State...: Unspecified + Hiber Context..: 0000000000000000 + + Allocated power irps (PopIrpList - fffff801332f44f0) + IRP: ffffe0001d53d8f0 (wait-wake/S0), PDO: ffffe00013cae060 + IRP: ffffe0001049a5d0 (wait-wake/S0), PDO: ffffe00012d42050 + IRP: ffffe00013d07420 (set/D3,), PDO: ffffe00012daf840, CURRENT: ffffe00012dd5040 + IRP: ffffe0001e5ac5d0 (wait-wake/S0), PDO: ffffe00013d33060 + IRP: ffffe0001ed3e420 (wait-wake/S0), PDO: ffffe00013c96060 + IRP: ffffe000195fe010 (wait-wake/S0), PDO: ffffe00012d32050 + + Irp worker threads (PopIrpThreadList - fffff801332f3100) + THREAD: ffffe0000ef5d040 (static) + THREAD: ffffe0000ef5e040 (static), IRP: ffffe00013d07420, DEVICE: ffffe00012dd5040 + ``` + +- If you are working with a KMDF driver, use the [Windows Driver Framework Extensions](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) (!wdfkd) to gather additional information. + + Use [**!wdfkd.wdflogdump**](-wdfkd-wdflogdump.md) <your driver name>, to see if KMDF is waiting for you to ACK any pending requests. + + Use [**!wdfkd.wdfdevicequeues**](-wdfkd-wdfdevicequeues.md) <your WDFDEVICE> to examine all outstanding requests and what state they are in. + +- Use the [**!stacks**](-stacks.md) extension to examine the state of every thread and look for a thread that might be holding up the power state transition. + +- To help you determine the cause of the error, consider the following questions: + + - What are the characteristics of the physical device object (PDO) driver (Arg2)? + - Can you find the blocked thread? When you examine the thread with the [**!thread**](-thread.md) debugger command, what does the thread consist of? + - Is there IO associated with the thread that is blocking it? What symbols are on the stack? + - When you examine the blocked power IRP, what do you notice? + - What is the PnP minor function code of the power IRP? + +**Debugging bug check 0x9F when Parameter 1 equals 0x4** + +- In a kernel debugger, use the [**!analyze -v**](-analyze.md) command to perform the initial bug check analysis. The verbose analysis displays the address of the **nt!TRIAGE\_9F\_PNP** structure, which is in Parameter 4 (arg4). + + ``` + kd> !analyze -v + ******************************************************************************* + * * + * Bugcheck Analysis * + * * + ******************************************************************************* + + DRIVER_POWER_STATE_FAILURE (9f) + A driver has failed to complete a power IRP within a specific time (usually 10 minutes). + Arguments: + Arg1: 00000004, The power transition timed out waiting to synchronize with the Pnp + subsystem. + Arg2: 00000258, Timeout in seconds. + Arg3: 84e01a70, The thread currently holding on to the Pnp lock. + Arg4: 82931b24, nt!TRIAGE_9F_PNP on Win7 + + + ``` + + The nt!TRIAGE\_9F\_PNP structure provides additional bug check information that might help you determine the cause of the error. The nt!TRIAGE\_9F\_PNP structure provides a pointer to a structure that contains the list of dispatched (but not completed) PnP IRPs and provides a pointer to the delayed system worker queue. + +- Use the [**dt (Display Type)**](dt--display-type-.md) command and specify the **nt!TRIAGE\_9F\_PNP** structure and the address that you found in Arg4. + + ``` + kd> dt nt!TRIAGE_9F_PNP 82931b24 + +0x000 Signature : 0x8001 + +0x002 Revision : 1 + +0x004 CompletionQueue : 0x82970e20 _TRIAGE_PNP_DEVICE_COMPLETION_QUEUE + +0x008 DelayedWorkQueue : 0x829455bc _TRIAGE_EX_WORK_QUEUE + + ``` + + The [**dt (Display Type)**](dt--display-type-.md) command displays the structure. You can use debugger commands to follow the LIST\_ENTRY fields to examine the list of outstanding PnP IRPs. + + To help you determine the cause of the error, consider the following questions: + + - Is there an IRP associated with the thread? + - Is there any IO in the CompletionQueue? + - What symbols are on the stack? +- Refer to the additional techniques described above under parameter 0x3. + +Resolution +---------- + +If you are not equipped to debug this problem using the techniques described above, you can use some basic troubleshooting techniques. + +- If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available. + +- If new device drivers or system services have been added recently, try removing or updating them. Try to determine what changed in the system that caused the new bug check code to appear. + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- To try and isolate the cause, temporally disable power save using control panel, power options. Some driver issues are related to the various states of system hibernation and the suspending and resumption of power. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- Check with the manufacturer to see if an updated system BIOS or firmware is available. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa--irql-not-less-or-equal.md b/windows-driver-docs-pr/debugger/bug-check-0xa--irql-not-less-or-equal.md new file mode 100644 index 0000000000..c8faa9373d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa--irql-not-less-or-equal.md @@ -0,0 +1,170 @@ +--- +title: Bug Check 0xA IRQL_NOT_LESS_OR_EQUAL +description: The IRQL_NOT_LESS_OR_EQUAL bug check has a value of 0x0000000A. +ms.assetid: a32b80f5-9822-41af-8668-836a70b05c0f +keywords: ["Bug Check 0xA IRQL_NOT_LESS_OR_EQUAL", "IRQL_NOT_LESS_OR_EQUAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IRQL_NOT_LESS_OR_EQUAL +api_type: +- NA +--- + +# Bug Check 0xA: IRQL\_NOT\_LESS\_OR\_EQUAL + + +The IRQL\_NOT\_LESS\_OR\_EQUAL bug check has a value of 0x0000000A. This indicates that Microsoft Windows or a kernel-mode driver accessed paged memory at an invalid address while at a raised interrupt request level (IRQL). This is typically either a bad pointer or a pageability problem. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IRQL\_NOT\_LESS\_OR\_EQUAL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The virtual memory address that could not be accessed.

+

Use [!pool](-pool.md) on this address to see whether it's Paged pool. These commands, may also be useful in gathering information about the failure: [!pte](-pte.md), [!address](-address.md), and [ln (List Nearest Symbols)](ln--list-nearest-symbols-.md).

2

IRQL at time of the fault.

+

VALUES:

+

2 : The IRQL was DISPATCH_LEVEL at the time of the fault. END_VALUES

3

Bitfield describing the operation that caused the fault.

+

Bit 0:

+

VALUES:

+

0: Read operation

+

1: Write operation

+

Bit 3: (Only available on chipsets that support this level of reporting.)

+

VALUES:

+

0: Not an execute operation

+

1: Execute operation

+Bit 0 and Bit 3 combined values: +

0x0 : Fault trying to READ from the address in parameter 1.

+

0x1 : Fault trying to WRITE to the address in parameter 1.

+

0x8 : Fault trying to EXECUTE code from the address in parameter 1.

+

This value is usually caused by:

+
    +
  • Calling a function that cannot be called at DISPATCH_LEVEL while at DISPATCH_LEVEL
  • +
  • Forgetting to release a spinlock
  • +
  • Marking code as pageable when it must be non-pageable (e.g., because the code acquires a spinlock, or is called in a DPC)
  • +

4

The instruction pointer at the time of the fault.

+

Use the [ln (List Nearest Symbols)](ln--list-nearest-symbols-.md) command on this address to see the name of the function.

+ +  + +Cause +----- + +Bug check 0xA is usually caused by kernel mode device drivers using improper addresses. + +This bug check indicates that an attempt was made to access an invalid address while at a raised interrupt request level (IRQL). This is either a bad memory pointer or a pageability problem with the device driver code. + +1. If parameter 1 is less than 0x1000, then this is likely a NULL pointer dereference. +2. If !pool reports that parameter 1 is Paged pool, then the IRQL is too high to access this data. Run at a lower IRQL or allocate the data in NonPagedPool. +3. If parameter 3 indicates that this was an attempt to execute pageable code, then the IRQL is too high to call this function. Run at a lower IRQL or do not mark the code as pageable. +4. Otherwise, this may be a bad pointer, possibly caused by use-after-free or bit-flipping. Investigate the validity of parameter 1 with [**!pte**](-pte.md), [**!address**](-address.md), and [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md). + +Resolution +---------- + +If a kernel debugger is available, obtain a stack trace. + +**Gather Information** + +Examine the name of the driver if that was listed on the blue screen. + +Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +**Driver Verifier** + +Driver Verifier is a tool that runs in real time to examine the behavior of drivers. For example, Driver Verifier checks the use of memory resources, such as memory pools. If it sees errors in the execution of driver code, it proactively creates an exception to allow that part of the driver code to be further scrutinized. The driver verifier manager is built into Windows and is available on all Windows PCs. To start the driver verifier manager, type *Verifer* at a command prompt. You can configure which drivers you would like to verify. The code that verifies drivers adds overhead as it runs, so try and verify the smallest number of drivers as possible. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +Here is a debugging example: + +``` +kd> .bugcheck [Lists bug check data.] +Bugcheck code 0000000a +Arguments 00000000 0000001c 00000000 00000000 + +kd> kb [Lists the stack trace.] +ChildEBP RetAddr Args to Child +8013ed5c 801263ba 00000000 00000000 e12ab000 NT!_DbgBreakPoint +8013eecc 801389ee 0000000a 00000000 0000001c NT!_KeBugCheckEx+0x194 +8013eecc 00000000 0000000a 00000000 0000001c NT!_KiTrap0E+0x256 +8013ed5c 801263ba 00000000 00000000 e12ab000 +8013ef64 00000246 fe551aa1 ff690268 00000002 NT!_KeBugCheckEx+0x194 + +kd> kv [Lists the trap frames.] +ChildEBP RetAddr Args to Child +8013ed5c 801263ba 00000000 00000000 e12ab000 NT!_DbgBreakPoint (FPO: [0,0,0]) +8013eecc 801389ee 0000000a 00000000 0000001c NT!_KeBugCheckEx+0x194 +8013eecc 00000000 0000000a 00000000 0000001c NT!_KiTrap0E+0x256 (FPO: [0,0] TrapFrame @ 8013eee8) +8013ed5c 801263ba 00000000 00000000 e12ab000 +8013ef64 00000246 fe551aa1 ff690268 00000002 NT!_KeBugCheckEx+0x194 + +kd> .trap 8013eee8 [Gets the registers for the trap frame at the time of the fault.] +eax=dec80201 ebx=ffdff420 ecx=8013c71c edx=000003f8 esi=00000000 edi=87038e10 +eip=00000000 esp=8013ef5c ebp=8013ef64 iopl=0 nv up ei pl nz na pe nc +cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000 efl=00010202 +ErrCode = 00000000 +00000000 ??????????????? [The current instruction pointer is NULL.] + +kd> kb [Gives the stack trace before the fault.] +ChildEBP RetAddr Args to Child +8013ef68 fe551aa1 ff690268 00000002 fe5620d2 NT!_DbgBreakPoint +8013ef74 fe5620d2 fe5620da ff690268 80404690 +NDIS!_EthFilterIndicateReceiveComplete+0x31 +8013ef64 00000246 fe551aa1 ff690268 00000002 elnkii!_ElnkiiRcvInterruptDpc+0x1d0 +``` + +Remarks +------- + +The error that generates this bug check usually occurs after the installation of a faulty device driver, system service, or BIOS. + +If you encounter bug check 0xA while upgrading to a later version of Windows, this error might be caused by a device driver, a system service, a virus scanner, or a backup tool that is incompatible with the new version. + +**Resolving a faulty hardware problem:** If hardware has been added to the system recently, remove it to see if the error recurs. If existing hardware has failed, remove or replace the faulty component. You should run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. + +**Resolving a faulty system service problem:** Disable the service and confirm that this resolves the error. If so, contact the manufacturer of the system service about a possible update. If the error occurs during system startup, investigate the Windows repair options. For more information, see [Recovery options in Windows 10](http://windows.microsoft.com/windows-10/windows-10-recovery-options). + +**Resolving an antivirus software problem:** Disable the program and confirm that this resolves the error. If it does, contact the manufacturer of the program about a possible update. + +For general blue screen troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa0--internal-power-error.md b/windows-driver-docs-pr/debugger/bug-check-0xa0--internal-power-error.md new file mode 100644 index 0000000000..18fb2d62f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa0--internal-power-error.md @@ -0,0 +1,584 @@ +--- +title: Bug Check 0xA0 INTERNAL_POWER_ERROR +description: The INTERNAL_POWER_ERROR bug check has a value of 0x000000A0. This bug check indicates that the power policy manager experienced a fatal error. +ms.assetid: a763e865-8591-4ed3-b3cd-1cdaecad6e97 +keywords: ["Bug Check 0xA0 INTERNAL_POWER_ERROR", "INTERNAL_POWER_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INTERNAL_POWER_ERROR +api_type: +- NA +--- + +# Bug Check 0xA0: INTERNAL\_POWER\_ERROR + + +The INTERNAL\_POWER\_ERROR bug check has a value of 0x000000A0. This bug check indicates that the power policy manager experienced a fatal error. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INTERNAL\_POWER\_ERROR Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x1

1: A device has overrun its maximum number of reference counts.

+

2, 3, or 4: (Windows Server 2003, Windows XP, and Windows 2000 only) Too many inrush power IRPs have been queued.

+

5: (Windows Server 2003, Windows XP, and Windows 2000 only) The power IRP has been sent to a passive level device object.

+

6: The system has failed to allocate a necessary power IRP.

If Parameter 2 has a value of 1, the maximum number of references allowed.

+

If Parameter 2 has a value of 2, 3, or 4, the maximum number of pending IRPs allowed.

+

If Parameter 2 has a value of 6, the target device object.

If Parameter 2 has value of 6, indicates whether this is a system (0x0) or device (0x1) power IRP.

An error occurred during the handling of the power I/O request packet (IRP).

0x2

Reserved

Reserved

Reserved

An internal failure has occurred while attempting to process a power event. For more information, see [Debugging bug check 0xA0 when parameter 1 equals 0x2](#parameter-1-equals-0x2).

0x3

The expected checksum

The actual checksum

The line number of the failure

The checksum for a hibernation context page does not match its expected checksum.

0x4

The expected checksum

The actual checksum

The line number of the failure

The checksum for a page about to be written to the hibernation file does not match its expected checksum.

0x5

Reserved

Reserved

Reserved

An unknown shutdown code has been sent to the system shutdown handler.

0x7

Reserved

Reserved

Reserved

An unhandled exception has occurred. For more information, see [Debugging bug check 0xA0 when parameter 1 equals 0x7](#parameter-1-equals-0x7).

0x8

This parameter is always set to 0x100.

The device object

POWER_CHANNEL_SUMMARY

+

A fatal error occurred while processing a system power event.

0x9

Status code

Mirroring phase

Reserved

A fatal error occured while preparing the hibernate file.

0xA

0: A bug check was requested immediately upon resuming.

+

1: A bug check was requested during resume after all non-pageable devices had been powered on.

+

2: A bug check was requested during resume after all devices had been powered on.

Reserved

Reserved

A bug check was requested when waking for debugging purposes.

0xB

Size of the hibernation file.

Hibernation progress before running out of space

+

0: HIBERFILE_PROGRESS_FREE_MAP

+

1: HIBERFILE_PROGRESS_RESUME_CONTEXT

+

2: HIBERFILE_PROGRESS_PROCESSOR_STATEE

+

3: HIBERFILE_PROGRESS_MEMORY_RANGES

+

4: HIBERFILE_PROGRESS_TABLE_PAGES

+

5: HIBERFILE_PROGRESS_MEMORY_IMAGE

Size of the remaining memory ranges.

The hibernation file is too small.

0xC

Status code

Dump stack context

Reserved

The dump stack failed to initialize.

0x101

Reserved

Exception pointer.

Reserved

An unhandled exception occured while processing a system power event. For more information, see [Debugging bug check 0xA0 when parameter 1 equals 0x101](#parameter-1-equals-0x101).

0x102

Reserved

DUMP_INITIALIZATION_CONTEXT

POP_HIBER_CONTEXT

The hibernation working buffer size is not page aligned.

0x103

Reserved

POP_HIBER_CONTEXT

Reserved

All working pages have failed to be accounted for during the hibernation process.

0x104

Reserved

POP_HIBER_CONTEXT

Reserved

An attempt was made to map internal hibernation memory while the internal memory structures were locked.

0x105

Reserved

POP_HIBER_CONTEXT

Reserved

An attempt was made to map internal hibernation memory with an unsupported memory type flag.

0x106

Reserved

The memory descriptor list (MDL)

Reserved

A memory descriptor list was created during the hibernation process which describes memory that is not paged-aligned.

0x107

Reserved

POP_HIBER_CONTEXT

PO_MEMORY_RANGE_ARRAY

A data mismatch has occurred in the internal hibernation data structures.

0x108

Reserved

POP_HIBER_CONTEXT

Reserved

The disk subsystem failed to properly write part of the hibernation file.

0x109

Reserved

Expected checksum

Actual checksum

The checksum for the processor state data does not match its expected checksum.

0x10A

Reserved

POP_HIBER_CONTEXT

NTSTATUS

The disk subsystem failed to properly read or write part of the hibernation file.

0x10B

Reserved

Current hibernation progress

Reserved

An attempt was made to mark pages for the boot phase of hibernation at the wrong time using the PoSetHiberRange API.

0x10C

Reserved

Flags provided to the API

Length to mark

The PoSetHiberRange API was called with invalid parameters.

0x200

Reserved

DEVICE_OBJECT

DEVICE_OBJECT_POWER_EXTENSION

An unknown device type is being checked for an idle state.

0x300

Reserved

DEVICE_OBJECT

IRP

An unknown status was returned from a battery power IRP.

0x301

Reserved

DEVICE_OBJECT

IRP

The battery has entered an unknown state.

0x400

Reserved

IO_STACK_LOCATION

DEVICE_OBJECT

A device has overrun its maximum number of reference counts.

0x401

Reserved

Pending IRP list

DEVICE_OBJECT

Too many inrush power IRPs have been queued.

0x402

Reserved

Pending IRP list

DEVICE_OBJECT

Too many inrush power IRPs have been queued.

0x403

Reserved

Pending IRP list

DEVICE_OBJECT

Too many inrush power IRPs have been queued.

0x404

Reserved

IO_STACK_LOCATION

DEVICE_OBJECT

A power IRP has been sent to a passive-level device object.

0x500

Reserved

IRP

DEVICE_OBJECT

An unknown status was returned from a thermal power IRP.

0x600

DEVICE_OBJECT PDO

Reserved

Reserved

A driver has attempted a duplicate registration with the Power Runtime Framework.

0x601

POP_FX_DEVICE device

PEP_DEVICE_REGISTER PEP

Reserved

No Power Engine Plugins accepted device registration.

0x602

DEVICE_NODE device node

Sleep count

Reserved

Device node sleep count does not match its activation count.

0x603

POP_FX_PLUGIN

Work request type

Reserved

A Power Engine Plugin made an invalid work request.

0x605

Notification ID

POP_FX_PLUGIN

Reserved

A Power Engine Plugin failed to accept mandatory device power management notification.

0x606

POP_FX_COMPONENT

POP_FX_COMPONENT_FLAGS

New condition for the component

A Power Engine Plugin attempted to transition a critical system resource component to an Active (or Idle) condition when the resource was already Active (or Idle).

0x607

POP_FX_DEVICE

NTSTATUS

Reserved

The acquisition of a runtime power management framework device-removal lock failed when it was required to succeed.

0x608

POP_FX_COMPONENT

POP_FX_COMPONENT_FLAGS

Reserved

A driver has attempted to transition a component to idle without a preceding active request.

0x609

POP_FX_PLUGIN

POP_FX_DEVICE

Duplicate Request Type

+

0: DevicePowerRequired

+

1: DevicePowerNotRequired

A Power Engine Plugin has requested either device power required or device power not required without an intervening request of the opposite type.

0x610

POP_FX_PLUGIN

POP_FX_DEVICE

Reserved

A Power Engine Plugin has requested device power not required while a previous device power required request is outstanding.

0x611

POP_FX_PLUGIN

POP_FX_DEVICE

Invalid component index

A Power Engine Plugin has requested an operation on an invalid component.

0x612

POP_FX_PLUGIN PowerEnginePlugin

Reserved

Reserved

A Power Engine Plugin has requested additional work to be done in the context of a device notification where no buffer was supplied by PO for the request.

0x613

POP_FX_DEVICE

Component index

Operation

+

0: Complete device power not required

+

1: Report device powered on

+

2: Complete idle condition

A driver has attempted to complete a request when no such outstanding request is pending.

0x614

POP_FX_DEVICE

Component index

Illegal parameter

+

0: PO_FX_FLAG_BLOCKING used at IRQL >= DISPATCH_LEVEL

+

1: PO_FX_FLAG_BLOCKING and PO_FX_FLAG_ASYNC_ONLY both specified

+

2: Invalid component index

A driver has requested an active/idle transition on a component with an illegal parameter.

0x615

POP_FX_PLUGIN

POP_FX_COMPONENT

Illegal Action

+

0: Component not in idle state 0

+

1:Component is already active

+

2: No outstanding activation request

+

3: Outstanding idle state transition

A Power Engine Plugin has illegally indicated the completion of a component activation.

0x616

POP_FX_PLUGIN

POP_FX_COMPONENT

Illegal Action

+

0: Invalid idle state

+

1: Component is already in the requested state

+

2: Requested a non-zero idle state without passing through idle state 0

A Power Engine Plugin has illegally requested a component idle state transition.

0x666

PPOP_PEP_ACTIVITY

New activity type

+

0: DevicePowerOn

+

1: ComponentIdleStateChange

+

2: ComponentActivating

+

3: ComponentActive

+

4: DevicePowerOff

+

5: DeviceSuspend

Conflicting activity type

+

0: DevicePowerOn

+

1: ComponentIdleStateChange

+

2: ComponentActivating

+

3: ComponentActive

+

4: DevicePowerOff

+

5: DeviceSuspend

The default Power Engine Plugin has attempted to trigger a new activity that conflicts with another activity.

0x667

POP_PEP_ACTIVITY

Activity type

+

0: DevicePowerOn

+

1: ComponentIdleStateChange

+

2: ComponentActivating

+

3: ComponentActive

+

4: DevicePowerOff

+

5: DeviceSuspend

POP_PEP_ACTIVITY_STATUS

Default Power Engine Plugin has attempted to complete an activity that is not running.

0x700

PEPHANDLE

PEP_PPM_IDLE_SELECT

Reserved

A Power Engine Plugin has specified invalid processor idle dependencies.

0x701

The index of the selected idle state of the hung processor

The PRCB address of the hung processor

The index of the hung processor

A processor was not able to complete an idle transition within the allocated interval. This indicates the specified processor is hung.

0x702

The index of the selected idle state of the processor

The idle synchronization state of the processor

The PRCB address of the hung processor

A processor woke up from a non-interruptible state without the the OS initiating an explicit wake through the PEP (using the necessary PPM idle synchronization).

+ +  + +Resolution +---------- + +**General Notes** + +In the preceding table, several of the parameters are pointers to structures. For example, if Parameter 2 is listed as DEVICE\_OBJECT, then Parameter 2 is a pointer to a DEVICE\_OBJECT structure. Some of the structures are defined in wdm.h, which is included in the Windows Driver Kit. For example, the following structures are defined in wdm.h. + +- EXCEPTION\_POINTERS +- DEVICE\_OBJECT +- IO\_STACK\_LOCATION +- PEP\_DEVICE\_REGISTER + +Some of the structures that appear in the preceding table are not defined in any public header file. You can see the definitions of those structures by using the [**dt**](dt--display-type-.md) debugger command. The following example shows how to use the **dt** command to see the **DEVICE\_OBJECT\_POWER\_EXTENSION** structure. + +``` +3: kd> dt nt!DEVICE_OBJECT_POWER_EXTENSION + +0x000 IdleCount : Uint4B + +0x004 BusyCount : Uint4B + +0x008 BusyReference : Uint4B + +0x00c TotalBusyCount : Uint4B + +0x010 ConservationIdleTime : Uint4B + +0x014 PerformanceIdleTime : Uint4B + +0x018 DeviceObject : Ptr64 _DEVICE_OBJECT + +0x020 IdleList : _LIST_ENTRY + +0x030 IdleType : _POP_DEVICE_IDLE_TYPE + +0x034 IdleState : _DEVICE_POWER_STATE + +0x038 CurrentState : _DEVICE_POWER_STATE + +0x040 Volume : _LIST_ENTRY + +0x050 Specific : +``` + +The following procedures will help you debug certain instances of this bug check. + + +**Debugging bug check 0xA0 when Parameter 1 equals 0x2** + +1. Examine the stack. Look for the **ntoskrnl!PopExceptionFilter** function. This function contains the following code as its first argument. + + ``` + (error_code << 16) | _LINE_ + ``` + + If the caller is **PopExceptionFilter**, the first argument to this function is of type PEXCEPTION\_POINTERS. Note the value of this argument. + +2. Use the [**dt (Display Type)**](dt--display-type-.md) command and specify the value that you found in the previous step as *argument*. + + ``` + dt nt!_EXCEPTION_POINTERS argument + ``` + + This command displays the structure. Note the address of the context record. + +3. Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command and specify the context record that you found in the previous step as *record*. + + ``` + .cxr record + ``` + + This command sets the register context to the proper value. + +4. Use a variety of commands to analyze the source of the error. Start with [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) . + + +**Debugging bug check 0xA0 when Parameter 1 equals 0x7** + +1. Examine the stack. Look for the **ntoskrnl!PopExceptionFilter** function. The first argument to this function is of type PEXCEPTION\_POINTERS. Note the value of this argument. + +2. Use the [**dt (Display Type)**](dt--display-type-.md) command and specify the value that you found in the previous step as *argument*. + + ``` + dt nt!_EXCEPTION_POINTERS argument + ``` + + This command displays the structure. Note the address of the context record. + +3. Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command and specify the context record that you found in the previous step as *record*. + + ``` + .cxr record + ``` + + This command sets the register context to the proper value. + +4. Use a variety of commands to analyze the source of the error. Start with [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) . + + +**Debugging bug check 0xA0 when Parameter 1 equals 0x101** + +1. Use the [**dt (Display Type)**](dt--display-type-.md) command and specify the value of Parameter 3 as *argument*. + + ``` + dt nt!_EXCEPTION_POINTERS argument + ``` + + This command displays the structure. Note the address of the context record. + +2. Use the [**.cxr (Display Context Record)**](-cxr--display-context-record-.md) command and specify the context record that you found the previous step as *record*. + + ``` + .cxr record + ``` + + This command sets the register context to the proper value. + +3. Use a variety of commands to analyze the source of the error. Start with [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) . + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa1--pci-bus-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0xa1--pci-bus-driver-internal.md new file mode 100644 index 0000000000..272baa4d70 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa1--pci-bus-driver-internal.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0xA1 PCI_BUS_DRIVER_INTERNAL +description: The PCI_BUS_DRIVER_INTERNAL bug check has a value of 0x000000A1. This bug check indicates that the PCI Bus driver detected inconsistency problems in its internal structures and could not continue. +ms.assetid: ec1981a7-eb26-4d17-97d6-55a33abb0e98 +keywords: ["Bug Check 0xA1 PCI_BUS_DRIVER_INTERNAL", "PCI_BUS_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PCI_BUS_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0xA1: PCI\_BUS\_DRIVER\_INTERNAL + + +The PCI\_BUS\_DRIVER\_INTERNAL bug check has a value of 0x000000A1. This bug check indicates that the PCI Bus driver detected inconsistency problems in its internal structures and could not continue. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PCI\_BUS\_DRIVER\_INTERNAL Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa2--memory-image-corrupt.md b/windows-driver-docs-pr/debugger/bug-check-0xa2--memory-image-corrupt.md new file mode 100644 index 0000000000..0860a15f9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa2--memory-image-corrupt.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0xA2 MEMORY_IMAGE_CORRUPT +description: The MEMORY_IMAGE_CORRUPT bug check has a value of 0x000000A2. This bug check indicates that corruption has been detected in the image of an executable file in memory. +ms.assetid: 73990217-4af2-478c-aa5e-39e6bc5811cf +keywords: ["Bug Check 0xA2 MEMORY_IMAGE_CORRUPT", "MEMORY_IMAGE_CORRUPT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MEMORY_IMAGE_CORRUPT +api_type: +- NA +--- + +# Bug Check 0xA2: MEMORY\_IMAGE\_CORRUPT + + +The MEMORY\_IMAGE\_CORRUPT bug check has a value of 0x000000A2. This bug check indicates that corruption has been detected in the image of an executable file in memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MEMORY\_IMAGE\_CORRUPT Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x02

If Parameter 3 is zero: The page number in the table page that failed

+

If Parameter 3 is nonzero: The page number with the failing page run index

Zero, or the index that failed to match the run

0

A table page check failure occurred.

0x03

The starting physical page number of the range

The length (in pages) of the range

The page number of the table page that contains this run

The checksum for the range of memory listed is incorrect.

+ +  + +Cause +----- + +A cyclic redundancy check (CRC) check on the memory range has failed. + +On a system wake operation, various regions of memory might be checked to guard against memory failures. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa3--acpi-driver-internal.md b/windows-driver-docs-pr/debugger/bug-check-0xa3--acpi-driver-internal.md new file mode 100644 index 0000000000..ba3011337d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa3--acpi-driver-internal.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xA3 ACPI_DRIVER_INTERNAL +description: The ACPI_DRIVER_INTERNAL bug check has a value of 0x000000A3. This bug check indicates that the ACPI driver detected an internal inconsistency. +ms.assetid: 599c09a9-5c13-404e-b68f-5fa68bd801ed +keywords: ["Bug Check 0xA3 ACPI_DRIVER_INTERNAL", "ACPI_DRIVER_INTERNAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ACPI_DRIVER_INTERNAL +api_type: +- NA +--- + +# Bug Check 0xA3: ACPI\_DRIVER\_INTERNAL + + +The ACPI\_DRIVER\_INTERNAL bug check has a value of 0x000000A3. This bug check indicates that the ACPI driver detected an internal inconsistency. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ACPI\_DRIVER\_INTERNAL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Reserved

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +An inconsistency in the ACPI driver is so severe that continuing to run would cause serious problems. + +One possible source of this problem is a BIOS error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa4--cnss-file-system-filter.md b/windows-driver-docs-pr/debugger/bug-check-0xa4--cnss-file-system-filter.md new file mode 100644 index 0000000000..65f267aa75 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa4--cnss-file-system-filter.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0xA4 CNSS_FILE_SYSTEM_FILTER +description: The CNSS_FILE_SYSTEM_FILTER bug check has a value of 0x000000A4. This bug check indicates that a problem occurred in the CNSS file system filter. +ms.assetid: fbf04b17-424c-4b9b-beae-5327d20bf0b9 +keywords: ["Bug Check 0xA4 CNSS_FILE_SYSTEM_FILTER", "CNSS_FILE_SYSTEM_FILTER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CNSS_FILE_SYSTEM_FILTER +api_type: +- NA +--- + +# Bug Check 0xA4: CNSS\_FILE\_SYSTEM\_FILTER + + +The CNSS\_FILE\_SYSTEM\_FILTER bug check has a value of 0x000000A4. This bug check indicates that a problem occurred in the CNSS file system filter. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CNSS\_FILE\_SYSTEM\_FILTER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number. The low 16 bits identify the source line in the file where the bug check occurred.

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +The CNSS\_FILE\_SYSTEM\_FILTER bug check might occur because nonpaged pool memory is full. If the nonpaged pool memory is completely full, this error can stop the system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver that requires nonpaged pool memory can also trigger this error. + +Resolution +---------- + +**To resolve a nonpaged pool memory depletion problem:** Add new physical memory to the computer. This memory sincrease the quantity of nonpaged pool memory available to the kernel. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa5--acpi-bios-error.md b/windows-driver-docs-pr/debugger/bug-check-0xa5--acpi-bios-error.md new file mode 100644 index 0000000000..eb7a40f93e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa5--acpi-bios-error.md @@ -0,0 +1,571 @@ +--- +title: Bug Check 0xA5 ACPI_BIOS_ERROR +description: The ACPI_BIOS_ERROR bug check has a value of 0x000000A5 that indicates that the ACPI BIOS of the computer is not fully compliant with the ACPI specification. +ms.assetid: f0366a3c-a2c4-4fc8-a722-52fdda59eb2b +keywords: ["Bug Check 0xA5 ACPI_BIOS_ERROR", "ACPI_BIOS_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ACPI_BIOS_ERROR +api_type: +- NA +--- + +# Bug Check 0xA5: ACPI\_BIOS\_ERROR + + +The ACPI\_BIOS\_ERROR bug check has a value of 0x000000A5. This bug check indicates that the Advanced Configuration and Power Interface (ACPI) BIOS of the computer is not fully compliant with the ACPI specification. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ACPI\_BIOS\_ERROR Parameters + + +Parameter 1 indicates the kind of the incompatibility. The meaning of the other parameters depends on the value of Parameter 1. + +If the BIOS incompatibility is related to Plug and Play (PnP) or power management, the following parameters are used. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x01

ACPI's deviceExtension

ACPI's ResourceList

0: No resource list is found

+

1: No IRQ resource is found in list

ACPI cannot find the System Control Interrupt (SCI) vector in the resources that are handed to it when ACPI is started.

0x02

(See the table later on this page)

0x03

The ACPI object that was being run

The return value from the interpreter

The name of the control method (in ULONG format)

ACPI tried to run a control method while creating device extensions to represent the ACPI namespace, but this control method failed.

0x04

The ACPI extension that _PRW belongs to

A pointer to the method

The DataType returned (see Amli.h)

ACPI evaluated a _PRW and expected to find an integer as a package element.

0x05

The ACPI extension that _PRW belongs to

Aointer to the _PRW

The number of elements in the _PRW

ACPI evaluated a _PRW, and the package that came back failed to contain at least two elements. The ACPI specification requires that two elements always be present in a _PRW.

0x06

The ACPI extension that _PRx belongs to

A pointer to the _PRx

A pointer to the name of the object to look for

ACPI tried to find a named object, but it could not find the object.

0x07

The ACPI extension that the method belongs to

A pointer to the method

The DataType returned (see Amli.h)

ACPI evaluated a method and expected to receive a buffer in return. However, the method returned some other data type.

0x08

The ACPI extension that the method belongs to

A pointer to the method

The DataType returned (see Amli.h)

ACPI evaluated a method and expected to receive an integer in return. However, the method returned some other data type.

0x09

The ACPI extension that the method belongs to

A pointer to the method

The DataType returned (see Amli.h)

ACPI evaluated a method and expected to receive a package in return. However, the method returned some other data type.

0x0A

The ACPI extension that the method belongs to

A pointer to the method

The DataType returned (see Amli.h)

ACPI evaluated a method and expected to receive a string in return. However, the method returned some other data type.

0x0B

The ACPI extension that _EJD belongs to

The status that the interpreter returns

The name of the object that ACPI is trying to find

ACPI cannot find the object that an _EJD string references.

0x0C

The ACPI extension that ACPI found a dock device for

A pointer to the _EJD method

0: BIOS does not claim system is dockage

+

1: Duplicate device extensions for dock device

ACPI provides faulty or insufficient information for dock support.

0x0D

The ACPI extension that ACPI needs the object for

The (ULONG) name of the method that ACPI looked for

0: Base case

+

1: Conflict

ACPI could not find a required method or object in the namespace This bug check code is used if there is no _HID or _ADR present.

0x0E

The NS PowerResource that ACPI needs the object for

The (ULONG) name of the method that ACPI looked for

0: Base case

ACPI could not find a required method or object in the namespace for a power resource (or entity other than a "device"). This bug check code is used if there is no _ON, _OFF, or _STA present for a power resource.

0x0F

The current buffer that ACPI was parsing

The buffer's tag

The specified length of the buffer

ACPI could not parse the resource descriptor.

0x10

(See the table later on this page)

0x11

(See the table later on this page)

0x14

The current buffer that ACPI was parsing

The buffer's tag

A pointer to a variable that contains the ULONGLONG length of the buffer

ACPI could not parse the resource descriptor. The length exceeds MAXULONG.

0x15

The ACPI Machine Language (AML) context

1: Failed to load table

+

2: The Parameter Path String Object was not found

+

3: Failed to insert Parameter Data into the ParameterPath String Object

+

4: Out of system memory

The NT status code

ACPI had a fatal error when attempting to load a table.

0x16

A pointer to the parent NSOBJ

A pointer to the illegal child ACPI namespace object

Reserved

ACPI had a fatal error when processing an xSDT. An object was declared as a child of a parent that cannot have children.

+ +  + +If an interrupt routing failure or incompatibility has occurred, the following parameters are used. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x2001

InterruptModel (integer)

The return value from the interpreter

A pointer to the PIC control method

ACPI tried to evaluate the PIC control method but failed.

0x10001

A pointer to the device object

A pointer to the parent of the device object

A pointer to the _PRT object

+

(See the following Comments section)

ACPI tried to do interrupt routing, but failed.

0x10002

A pointer to the device object

A pointer to the string name that ACPI was looking for but could not find

A pointer to the _PRT object

+

(See the following Comments section)

ACPI could not find the link node referenced in a _PRT.

0x10003

A pointer to the device object

The device ID or function number.

+

This DWORD is encoded as follows: bits 5:0 are the PCI device number, and bits 8:6 are the PCI function number

A pointer to the _PRT object

+

(See the following Comments section)

ACPI could not find a mapping in the _PRT package for a device.

0x10005

A pointer to the _PRT object

+

(See the following Comments section)

A pointer to the current _PRT element.

+

(This pointer is an index into the _PRT.)

The device ID or function number.

+

This DWORD is encoded as follows: bits 15:0 are the PCI function number, and bits 31:16 are the PCI device number

ACPI found an entry in the _PRT that the function ID is not all F's for.

+

(The generic format for a _PRT entry is that the device number is specified, but the function number is not.)

0x10006

A pointer to the link node.

+

(This device is missing the _DIS method.)

0

0

ACPI found a link node, but it cannot disable the node.

+

(Link nodes must be disabled to allow for reprogramming.)

0x10007

The vector that could not be found

0

0

The _PRT contained a reference to a vector that is not described in the I/O APIC entry's MAPIC table.

0x10008

The invalid interrupt level.

0

0

The ACPI SCI interrupt level is invalid.

+

0x10009

0

0

0

The Fixed ACPI Description Table (FADT) could not be located.

0x1000A

0

0

0

The Root System Description Pointer (RSDP) or Extended System Description Table (XSDT) could not be located

+

0x1000B

The ACPI table signature

A pointer to the ACPI table

0

The length of the ACPI table is not consistent with the table revision.

0x20000

The I/O port in the Fixed Table

0

0

The PM_TMR_BLK entry in the Fixed ACPI Description Table doesn't point to a working ACPI timer block.

+ +  + +If a miscellaneous failure or incompatibility has occurred, the following parameters are used. + + +++++++ + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause

0x20000

The I/O port in the Fixed Table

0

0

The PM_TMR_BLK entry in the Fixed ACPI Description Table does not point to a working ACPI timer block.

+ +  + +If Parameter 1 equals **0x02**, the ACPI BIOS could not process the resource list for the PCI root buses. In this case, Parameter 3 specifies the exact problem, and the remaining parameters have the following definitions. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 2Parameter 3Parameter 4Cause

The ACPI extension for the PCI bus

0x0

A pointer to the QUERY_RESOURCES IRP

ACPI cannot convert the BIOS' resource list into the proper format. This probably represents an error in the BIOS' list encoding procedure.

The ACPI extension for the PCI bus

0x1

A pointer to the QUERY_RESOURCE_REQUIREMENTS IRP

ACPI cannot convert the BIOS' resource list into the proper format. This probably represents an error in the BIOS' list encoding procedure.

The ACPI extension for the PCI bus

0x2

0

ACPI found an empty resource list.

The ACPI extension for the PCI bus

0x3

A pointer to the PNP CRS descriptor

ACPI could not find the current bus number in the CRS.

The ACPI extension for the PCI bus

A pointer to the resource list for PCI

A pointer to the E820 memory table

The list of resources that PCI claims to decode overlaps with the list of memory regions that the E820 BIOS interface reports. (This kind of conflict is never permitted.)

+ +  + +If Parameter 1 equals **0x10**, the ACPI BIOS could not determine the system-to-device-state mapping correctly. In this situation, Parameter 3 specifies the exact problem, and the remaining parameters have the following definitions. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 2Parameter 3Parameter 4Cause

The ACPI extension whose mapping is needed

0x0

The DEVICE_POWER_STATE (this is "x+1")

_PRx was mapped back to a non-supported S-state.

The ACPI extension whose mapping is needed

0x1

The SYSTEM_POWER_STATE that cannot be mapped

ACPI cannot find a D-state to associate with the S-state.

The ACPI extension whose mapping is needed

0x2

The SYSTEM_POWER_STATE that cannot be mapped

The device claims to be able to wake the system when the system is in this S-state, but the system does not actually support this S-state.

+ +  + +If Parameter 1 equals **0x11**, the system could not enter ACPI mode. In this situation, Parameter 2 specifies the exact problem, and the remaining parameters have the following definitions. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 2Parameter 3Parameter 4Cause

0x0

0

0

The system could not initialize the AML interpreter.

0x1

0

0

The system could not find RSDT.

0x2

0

0

The system could not allocate critical driver structures.

0x3

0

0

The system could not load RSDT.

0x4

0

0

The system could not load DDBs.

0x5

0

0

The system cannot connect the Interrupt vector.

0x6

0

0

SCI_EN never becomes set in PM1 Control Register.

0x7

A pointer to the table that had a bad checksum

Creator revision

The table checksum is incorrect.

0x8

A pointer to the table that ACPI failed to load

Creator revision

ACPI failed to load DDB.

0x9

FADT version

0

Unsupported firmware version.

0xA

0

0

The system could not find MADT.

0xB

0

0

The system could not find any valid Local SAPIC structures in the MADT.

+ +  + +Cause +----- + +The value of Parameter 1 indicates the error. + +Resolution +---------- + +If you are debugging this error, use the [**!analyze -v**](-analyze.md) extension. This extension displays all the relevant data (device extensions, nsobjects, or whatever is appropriate to the specific error). + +If you are not performing debugging, this error indicates that you have to obtain a new BIOS. Contact your vendor or visit the internet to get a new BIOS. + +If you cannot obtain an updated BIOS, or the latest BIOS is still not ACPI compliant, you can turn off ACPI mode during text-mode setup. To turn off ACPI mode, press the F7 key when you are prompted to install storage drivers. The system does not notify you that the F7 key was pressed, but it silently disables ACPI and enables you to continue your installation. + +Remarks +------- + +A PCI routing table (\_PRT) is the ACPI BIOS object that specifies how all the PCI devices are connected to the interrupt controllers. A computer with multiple PCI buses might have multiple \_PRTs. + +You can display a \_PRT in the debugger by using the **!acpikd.nsobj** extension together with the address of the \_PRT object as its argument. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xa7--bad-exhandle.md b/windows-driver-docs-pr/debugger/bug-check-0xa7--bad-exhandle.md new file mode 100644 index 0000000000..27a902ae55 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xa7--bad-exhandle.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0xA7 BAD_EXHANDLE +description: The BAD_EXHANDLE bug check has a value of 0x000000A7. This bug check indicates that the kernel-mode handle table detected an inconsistent handle table entry state. +ms.assetid: 9f485894-2653-40d2-b5fe-56e46ba26c1b +keywords: ["Bug Check 0xA7 BAD_EXHANDLE", "BAD_EXHANDLE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BAD_EXHANDLE +api_type: +- NA +--- + +# Bug Check 0xA7: BAD\_EXHANDLE + + +The BAD\_EXHANDLE bug check has a value of 0x000000A7. This bug check indicates that the kernel-mode handle table detected an inconsistent handle table entry state. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BAD\_EXHANDLE Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xab--session-has-valid-pool-on-exit.md b/windows-driver-docs-pr/debugger/bug-check-0xab--session-has-valid-pool-on-exit.md new file mode 100644 index 0000000000..e1c38bd053 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xab--session-has-valid-pool-on-exit.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xAB SESSION_HAS_VALID_POOL_ON_EXIT +description: The SESSION_HAS_VALID_POOL_ON_EXIT bug check has a value of 0x000000AB. This bug check indicates that a session unload occurred while a session driver still held memory. +ms.assetid: fe4587cc-2567-4452-a3e7-22a53def76b2 +keywords: ["Bug Check 0xAB SESSION_HAS_VALID_POOL_ON_EXIT", "SESSION_HAS_VALID_POOL_ON_EXIT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION_HAS_VALID_POOL_ON_EXIT +api_type: +- NA +--- + +# Bug Check 0xAB: SESSION\_HAS\_VALID\_POOL\_ON\_EXIT + + +The SESSION\_HAS\_VALID\_POOL\_ON\_EXIT bug check has a value of 0x000000AB. This bug check indicates that a session unload occurred while a session driver still held memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION\_HAS\_VALID\_POOL\_ON\_EXIT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The session ID.

2

The number of paged pool bytes that are leaking.

3

The number of nonpaged pool bytes that are leaking.

4

The total number of paged and nonpaged allocations that are leaking. (The number of nonpaged allocations are in the upper half of this word, and paged allocations are in the lower half of this word.)

+ +  + +Cause +----- + +The SESSION\_HAS\_VALID\_POOL\_ON\_EXIT bug check occurs because a session driver does not free its pool allocations before a session unload. This bug check can indicate a bug in Win32k.sys, Atmfd.dll, Rdpdd.dll, or a video or other driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xac--hal-memory-allocation.md b/windows-driver-docs-pr/debugger/bug-check-0xac--hal-memory-allocation.md new file mode 100644 index 0000000000..cb21cdef23 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xac--hal-memory-allocation.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xAC HAL_MEMORY_ALLOCATION +description: The HAL_MEMORY_ALLOCATION bug check has a value of 0x000000AC. This bug check indicates that the hardware abstraction layer (HAL) could not obtain sufficient memory. +ms.assetid: 816e6ab5-ccec-47fb-8618-865cb5bb6cb2 +keywords: ["Bug Check 0xAC HAL_MEMORY_ALLOCATION", "HAL_MEMORY_ALLOCATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HAL_MEMORY_ALLOCATION +api_type: +- NA +--- + +# Bug Check 0xAC: HAL\_MEMORY\_ALLOCATION + + +The HAL\_MEMORY\_ALLOCATION bug check has a value of 0x000000AC. This bug check indicates that the hardware abstraction layer (HAL) could not obtain sufficient memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## HAL\_MEMORY\_ALLOCATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The allocation size

2

0

3

A pointer to a string that contains the file name

4

Reserved

+ +  + +Cause +----- + +The HAL could not obtain non-paged memory pool for a system critical requirement. + +These critical memory allocations are made early in system initialization, and the HAL\_MEMORY\_ALLOCATION bug check is not expected. This bug check probably indicates some other critical error such as pool corruption or massive consumption. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xad--video-driver-debug-report-request.md b/windows-driver-docs-pr/debugger/bug-check-0xad--video-driver-debug-report-request.md new file mode 100644 index 0000000000..76f5a14f9d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xad--video-driver-debug-report-request.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xAD VIDEO_DRIVER_DEBUG_REPORT_REQUEST +description: The VIDEO_DRIVER_DEBUG_REPORT_REQUEST bug check has a value of 0x000000AD. This bug check indicates that the video port created a non-fatal minidump on behalf of the video driver during run time. +ms.assetid: eedde484-584b-478b-9429-a9c78bb62c1e +keywords: ["Bug Check 0xAD VIDEO_DRIVER_DEBUG_REPORT_REQUEST", "VIDEO_DRIVER_DEBUG_REPORT_REQUEST"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_DRIVER_DEBUG_REPORT_REQUEST +api_type: +- NA +--- + +# Bug Check 0xAD: VIDEO\_DRIVER\_DEBUG\_REPORT\_REQUEST + + +The VIDEO\_DRIVER\_DEBUG\_REPORT\_REQUEST bug check has a value of 0x000000AD. This bug check indicates that the video port created a non-fatal minidump on behalf of the video driver during run time. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_DRIVER\_DEBUG\_REPORT\_REQUEST Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Driver-specific

2

Driver-specific

3

Driver-specific

4

The number of all reports that have been requested since boot time

+ +  + +Remarks +------- + +The video port created a non-fatal minidump on behalf of the video driver during run time because the video driver requested a debug report. + +The VIDEO\_DRIVER\_DEBUG\_REPORT\_REQUEST bug check can be caused only by minidump creation, not by the creation of a full dump or kernel dump. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xb--no-exception-handling-support.md b/windows-driver-docs-pr/debugger/bug-check-0xb--no-exception-handling-support.md new file mode 100644 index 0000000000..531c97ad4a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xb--no-exception-handling-support.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0xB NO_EXCEPTION_HANDLING_SUPPORT +description: The NO_EXCEPTION_HANDLING_SUPPORT bug check has a value of 0x0000000B.This bug check appears very infrequently. +ms.assetid: 0f48aef9-b2e4-421e-bb78-dca74033d3c3 +keywords: ["Bug Check 0xB NO_EXCEPTION_HANDLING_SUPPORT", "NO_EXCEPTION_HANDLING_SUPPORT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_EXCEPTION_HANDLING_SUPPORT +api_type: +- NA +--- + +# Bug Check 0xB: NO\_EXCEPTION\_HANDLING\_SUPPORT + + +The NO\_EXCEPTION\_HANDLING\_SUPPORT bug check has a value of 0x0000000B. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xb1--bgi-detected-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xb1--bgi-detected-violation.md new file mode 100644 index 0000000000..8afbcc6387 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xb1--bgi-detected-violation.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0xB1 BGI_DETECTED_VIOLATION +description: The BGI_DETECTED_VIOLATION bug check has a value of 0x000000B1. +ms.assetid: B1DE8C2B-FBE3-4EFC-8DD8-4222AD5E1E36 +keywords: ["Bug Check 0xB1 BGI_DETECTED_VIOLATION", "BGI_DETECTED_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BGI_DETECTED_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xB1: BGI\_DETECTED\_VIOLATION + + +The BGI\_DETECTED\_VIOLATION bug check has a value of 0x000000B1. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BGI\_DETECTED\_VIOLATION Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xb4--video-driver-init-failure.md b/windows-driver-docs-pr/debugger/bug-check-0xb4--video-driver-init-failure.md new file mode 100644 index 0000000000..dfa022b2f5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xb4--video-driver-init-failure.md @@ -0,0 +1,44 @@ +--- +title: Bug Check 0xB4 VIDEO_DRIVER_INIT_FAILURE +description: The VIDEO_DRIVER_INIT_FAILURE bug check has a value of 0x000000B4. This indicates that Windows was unable to enter graphics mode. +ms.assetid: 37c2d07d-f351-42d0-ba88-9b9a2a3d19f8 +keywords: ["Bug Check 0xB4 VIDEO_DRIVER_INIT_FAILURE", "VIDEO_DRIVER_INIT_FAILURE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- VIDEO_DRIVER_INIT_FAILURE +api_type: +- NA +--- + +# Bug Check 0xB4: VIDEO\_DRIVER\_INIT\_FAILURE + + +The VIDEO\_DRIVER\_INIT\_FAILURE bug check has a value of 0x000000B4. This indicates that Windows was unable to enter graphics mode. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## VIDEO\_DRIVER\_INIT\_FAILURE Parameters + + +None + +Cause +----- + +The system was not able to go into graphics mode because no display drivers were able to start. + +This usually occurs when no video miniport drivers are able to load successfully. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xb8--attempted-switch-from-dpc.md b/windows-driver-docs-pr/debugger/bug-check-0xb8--attempted-switch-from-dpc.md new file mode 100644 index 0000000000..5572e1650d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xb8--attempted-switch-from-dpc.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0xB8 ATTEMPTED_SWITCH_FROM_DPC +description: The ATTEMPTED_SWITCH_FROM_DPC bug check has a value of 0x000000B8. This indicates that an illegal operation was attempted by a delayed procedure call (DPC) routine. +ms.assetid: 614b7be8-cec9-4dd9-b183-66db1790c31f +keywords: ["Bug Check 0xB8 ATTEMPTED_SWITCH_FROM_DPC", "ATTEMPTED_SWITCH_FROM_DPC"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ATTEMPTED_SWITCH_FROM_DPC +api_type: +- NA +--- + +# Bug Check 0xB8: ATTEMPTED\_SWITCH\_FROM\_DPC + + +The ATTEMPTED\_SWITCH\_FROM\_DPC bug check has a value of 0x000000B8. This indicates that an illegal operation was attempted by a delayed procedure call (DPC) routine. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ATTEMPTED\_SWITCH\_FROM\_DPC Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The original thread causing the failure

2

The new thread

3

The stack address of the original thread

4

Reserved

+ +  + +Cause +----- + +A wait operation, attach process, or yield was attempted from a DPC routine. This is an illegal operation. + +Resolution +---------- + +The stack trace will lead to the code in the original DPC routine that caused the error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xb9--chipset-detected-error.md b/windows-driver-docs-pr/debugger/bug-check-0xb9--chipset-detected-error.md new file mode 100644 index 0000000000..8b98db1d12 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xb9--chipset-detected-error.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0xB9 CHIPSET_DETECTED_ERROR +description: The CHIPSET_DETECTED_ERROR bug check has a value of 0x000000B9.This bug check appears very infrequently. +ms.assetid: 21d92ea9-dae3-41f1-b0e7-3701c420f7ca +keywords: ["Bug Check 0xB9 CHIPSET_DETECTED_ERROR", "CHIPSET_DETECTED_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CHIPSET_DETECTED_ERROR +api_type: +- NA +--- + +# Bug Check 0xB9: CHIPSET\_DETECTED\_ERROR + + +The CHIPSET\_DETECTED\_ERROR bug check has a value of 0x000000B9. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xba--session-has-valid-views-on-exit.md b/windows-driver-docs-pr/debugger/bug-check-0xba--session-has-valid-views-on-exit.md new file mode 100644 index 0000000000..e8de9ea64d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xba--session-has-valid-views-on-exit.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xBA SESSION_HAS_VALID_VIEWS_ON_EXIT +description: The SESSION_HAS_VALID_VIEWS_ON_EXIT bug check has a value of 0x000000BA. This indicates that a session driver still had mapped views when the session unloaded. +ms.assetid: e0ef7d0e-8a3e-41ca-b0c1-c0f0bb298ef1 +keywords: ["Bug Check 0xBA SESSION_HAS_VALID_VIEWS_ON_EXIT", "SESSION_HAS_VALID_VIEWS_ON_EXIT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION_HAS_VALID_VIEWS_ON_EXIT +api_type: +- NA +--- + +# Bug Check 0xBA: SESSION\_HAS\_VALID\_VIEWS\_ON\_EXIT + + +The SESSION\_HAS\_VALID\_VIEWS\_ON\_EXIT bug check has a value of 0x000000BA. This indicates that a session driver still had mapped views when the session unloaded. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION\_HAS\_VALID\_VIEWS\_ON\_EXIT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The session ID

2

The number of mapped views that are leaking

3

The address of this session's mapped views table

4

The size of this session's mapped views table

+ +  + +Cause +----- + +This error is caused by a session driver not unmapping its mapped views prior to a session unload. This indicates a bug in win32k.sys, atmfd.dll, rdpdd.dll, or a video driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbb--network-boot-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0xbb--network-boot-initialization-failed.md new file mode 100644 index 0000000000..c2faf82a9a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbb--network-boot-initialization-failed.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0xBB NETWORK_BOOT_INITIALIZATION_FAILED +description: The NETWORK_BOOT_INITIALIZATION_FAILED bug check has a value of 0x000000BB. This indicates that Windows failed to successfully boot off a network. +ms.assetid: 1cc86ca0-437d-4a26-90ed-76f122c522ef +keywords: ["Bug Check 0xBB NETWORK_BOOT_INITIALIZATION_FAILED", "NETWORK_BOOT_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NETWORK_BOOT_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0xBB: NETWORK\_BOOT\_INITIALIZATION\_FAILED + + +The NETWORK\_BOOT\_INITIALIZATION\_FAILED bug check has a value of 0x000000BB. This indicates that Windows failed to successfully boot off a network. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NETWORK\_BOOT\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The part of network initialization that failed. Possible values are:

+

1: Failure while updating the registry.

+

2: Failure while starting the network stack. Windows sends IOCTLs to the redirector and datagram receiver, then waits for the redirector to be ready. If it is not ready within a certain period of time, this error is issued.

+

3: Failure while sending the DHCP IOCTL to TCP. This is how Windows informs the transport of its IP address.

2

The failure status

3

Reserved

4

Reserved

+ +  + +Cause +----- + +This error is caused when Windows is booting off a network, and a critical function fails during I/O initialization. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbc--network-boot-duplicate-address.md b/windows-driver-docs-pr/debugger/bug-check-0xbc--network-boot-duplicate-address.md new file mode 100644 index 0000000000..63c52f88bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbc--network-boot-duplicate-address.md @@ -0,0 +1,79 @@ +--- +title: Bug Check 0xBC NETWORK_BOOT_DUPLICATE_ADDRESS +description: The NETWORK_BOOT_DUPLICATE_ADDRESS bug check has a value of 0x000000BC. This indicates that a duplicate IP address was assigned to this machine while booting off a network. +ms.assetid: 54c45e73-7054-4dba-abe4-91f5f5a064a4 +keywords: ["Bug Check 0xBC NETWORK_BOOT_DUPLICATE_ADDRESS", "NETWORK_BOOT_DUPLICATE_ADDRESS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NETWORK_BOOT_DUPLICATE_ADDRESS +api_type: +- NA +--- + +# Bug Check 0xBC: NETWORK\_BOOT\_DUPLICATE\_ADDRESS + + +The NETWORK\_BOOT\_DUPLICATE\_ADDRESS bug check has a value of 0x000000BC. This indicates that a duplicate IP address was assigned to this machine while booting off a network. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## NETWORK\_BOOT\_DUPLICATE\_ADDRESS Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The IP address, shown as a DWORD. An address of the form aa.bb.cc.dd will appear as 0xDDCCBBAA.

2

The hardware address of the other machine. (For an Ethernet connection, see the following note.)

3

The hardware address of the other machine. (For an Ethernet connection, see the following note.)

4

The hardware address of the other machine. (For an Ethernet connection, this will be zero.)

+ +  + +**Note**   When Parameter 4 equals zero, this indicates an Ethernet connection. In that case, the MAC address will be stored in Parameter 2 and Parameter 3. An Ethernet MAC address of the form *aa-bb-cc-dd-ee-ff* will cause Parameter 2 to equal 0xAABBCCDD, and Parameter 3 to equal 0xEEFF0000. + +  + +Cause +----- + +This error indicates that when TCP/IP sent out an ARP for its IP address, it got a response from another machine indicating a duplicate IP address. + +When Windows is booting off a network, this is a fatal error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbd--invalid-hibernated-state.md b/windows-driver-docs-pr/debugger/bug-check-0xbd--invalid-hibernated-state.md new file mode 100644 index 0000000000..7ac85ae73f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbd--invalid-hibernated-state.md @@ -0,0 +1,71 @@ +--- +title: Bug Check 0xBD INVALID_HIBERNATED_STATE +description: The INVALID_HIBERNATED_STATE bug check has a value of 0x000000BD. +ms.assetid: DB386A20-EE6F-4E2B-8FFD-51CCE0A8AEAC +keywords: ["Bug Check 0xBD INVALID_HIBERNATED_STATE", "INVALID_HIBERNATED_STATE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_HIBERNATED_STATE +api_type: +- NA +--- + +# Bug Check 0xBD: INVALID\_HIBERNATED\_STATE + + +The INVALID\_HIBERNATED\_STATE bug check has a value of 0x000000BD. This indicates that the hibernated memory image does not match the current hardware configuration. This bugcheck occurs when a system resumes from hibernate and discovers that the hardware has been changed while the system was hibernated. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_HIBERNATED\_STATE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

Hardware that was invalid.

+

1 : Number of installed processors is less than before the hibernation

+

Value in Param 2: Number of processors before hibernation

+

Value in Param 3: Number of processors after hibernation

2Per Parameter 1
3Per Parameter 1
4Reserved
+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbe--attempted-write-to-readonly-memory.md b/windows-driver-docs-pr/debugger/bug-check-0xbe--attempted-write-to-readonly-memory.md new file mode 100644 index 0000000000..81aab2c7b4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbe--attempted-write-to-readonly-memory.md @@ -0,0 +1,70 @@ +--- +title: Bug Check 0xBE ATTEMPTED_WRITE_TO_READONLY_MEMORY +description: The ATTEMPTED_WRITE_TO_READONLY_MEMORY bug check has a value of 0x000000BE. This is issued if a driver attempts to write to a read-only memory segment. +ms.assetid: d6247828-09ae-4071-9b4f-917af29265bc +keywords: ["Bug Check 0xBE ATTEMPTED_WRITE_TO_READONLY_MEMORY", "ATTEMPTED_WRITE_TO_READONLY_MEMORY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ATTEMPTED_WRITE_TO_READONLY_MEMORY +api_type: +- NA +--- + +# Bug Check 0xBE: ATTEMPTED\_WRITE\_TO\_READONLY\_MEMORY + + +The ATTEMPTED\_WRITE\_TO\_READONLY\_MEMORY bug check has a value of 0x000000BE. This is issued if a driver attempts to write to a read-only memory segment. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ATTEMPTED\_WRITE\_TO\_READONLY\_MEMORY Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address of attempted write

2

PTE contents

3

Reserved

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbf--mutex-already-owned.md b/windows-driver-docs-pr/debugger/bug-check-0xbf--mutex-already-owned.md new file mode 100644 index 0000000000..84c26f6774 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbf--mutex-already-owned.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0xBF MUTEX_ALREADY_OWNED +description: The MUTEX_ALREADY_OWNED bug check has a value of 0x000000BF. This indicates that a thread attempted to acquire ownership of a mutex it already owned. +ms.assetid: 0008c6eb-3add-4169-b29a-6fe4d77c5c9e +keywords: ["Bug Check 0xBF MUTEX_ALREADY_OWNED", "MUTEX_ALREADY_OWNED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MUTEX_ALREADY_OWNED +api_type: +- NA +--- + +# Bug Check 0xBF: MUTEX\_ALREADY\_OWNED + + +The MUTEX\_ALREADY\_OWNED bug check has a value of 0x000000BF. This indicates that a thread attempted to acquire ownership of a mutex it already owned. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MUTEX\_ALREADY\_OWNED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the mutex

2

The thread that caused the error

3

0

4

Reserved

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbfe--bc-bluetooth-verifier-fault.md b/windows-driver-docs-pr/debugger/bug-check-0xbfe--bc-bluetooth-verifier-fault.md new file mode 100644 index 0000000000..a2c9b04789 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbfe--bc-bluetooth-verifier-fault.md @@ -0,0 +1,113 @@ +--- +title: Bug Check 0xBFE BC_BLUETOOTH_VERIFIER_FAULT +description: The BC_BLUETOOTH_VERIFIER_FAULT bug check has a value of 0x00000BFE. This indicates that a driver has caused a violation. +ms.assetid: EC1368CE-46A2-4B69-8405-3118503D35C2 +keywords: ["Bug Check 0xBFE BC_BLUETOOTH_VERIFIER_FAULT", "BC_BLUETOOTH_VERIFIER_FAULT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BC_BLUETOOTH_VERIFIER_FAULT +api_type: +- NA +--- + +# Bug Check 0xBFE: BC\_BLUETOOTH\_VERIFIER\_FAULT + + +The BC\_BLUETOOTH\_VERIFIER\_FAULT bug check has a value of 0x00000BFE. This indicates that a driver has caused a violation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BC\_BLUETOOTH\_VERIFIER\_FAULT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

The subtype of the Bluetooth verifier fault.

+
+``` + 0x1 : An attempt was made to submit a Bluetooth Request Block that is already in use + 2 - Brb pointer + 3 - Reserved + 4 - Reserved + 0x2 : An attempt was made to free a Bluetooth Request Block that is in use + 2 - Brb pointer + 3 - Reserved + 4 - Reserved + 0x3 : An attempt was made to allocate or initialize an invalid BRB type + 2 - Brb pointer + 3 - pdo extension (if available) + 4 - Reserved + 0x4 : Invalid Bluetooth Request Block pointer was submitted + 2 - Brb pointer + 3 - Reserved + 4 - Reserved + 0x5 : A Bluetooth Request Block with an invalid size was submitted + 2 - Brb pointer + 3 - Actual Size + 4 - Expected Size + 0x6 : The IOCTL_BTH_GET_DEVICE_INFO was called with invalid parameters + 2 - Reserved + 3 - Reserved + 4 - Reserved + 0x7 : BRB_L2CA_UNREGISTER_SERVER was submitted with an invalid server handle + 2 - Server handle + 3 - Reserved + 4 - Reserved + 0x8 : BRB_L2CA_CLOSE_CHANNEL was submitted with an invalid channel handle + 2 - Brb pointer + 3 - Channel handle + 4 - Reserved + 0x9 : BRB_SCO_UNREGISTER_SERVER was submitted with an invalid server handle + 2 - Server handle + 3 - Reserved + 4 - Reserved +``` +
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +Resolution +---------- + +Parameter 1 describes the type of violation. Look at the call stack to determine the misbehaving driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xbff--bc-bthmini-verifier-fault.md b/windows-driver-docs-pr/debugger/bug-check-0xbff--bc-bthmini-verifier-fault.md new file mode 100644 index 0000000000..e8d7e83fee --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xbff--bc-bthmini-verifier-fault.md @@ -0,0 +1,89 @@ +--- +title: Bug Check 0xBFF BC_BTHMINI_VERIFIER_FAULT +description: The BC_BTHMINI_VERIFIER_FAULT bug check has a value of 0x00000BFF. This indicates that The Bluetooth miniport extensible driver verifier has caught a violation. +ms.assetid: 4BB54209-89EA-455D-B850-CC2A96A43C87 +keywords: ["Bug Check 0xBFF BC_BTHMINI_VERIFIER_FAULT", "BC_BTHMINI_VERIFIER_FAULT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BC_BTHMINI_VERIFIER_FAULT +api_type: +- NA +--- + +# Bug Check 0xBFF: BC\_BTHMINI\_VERIFIER\_FAULT + + +The BC\_BTHMINI\_VERIFIER\_FAULT bug check has a value of 0x00000BFF. This indicates that The Bluetooth miniport extensible driver verifier has caught a violation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BC\_BTHMINI\_VERIFIER\_FAULT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
1

The subtype of the Bluetooth verifier fault.

+
+``` + 0x1 : An attempt was made to return a packet with type that mis-matched its original request. + 2 - Returned packet type + 3 - Expected packet type + 4 - Reserved + 0x2 : An attempt was made to return an unexpected status code and caused the packet to be discarded. + 2 - Unexpected return status + 3 - Reserved + 4 - Reserved + 0x3 : Incorrect output buffer size was returned to indicate number of bytes written by the lower transport driver. + 2 - Unexpected buffer size + 3 - Expected buffer size + 4 - Reserved +``` +
2See parameter 1
3See parameter 1
4See parameter 1
+ +  + +Resolution +---------- + +Parameter 1 describes the type of violation. Look at the call stack to determine the misbehaving driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc--maximum-wait-objects-exceeded.md b/windows-driver-docs-pr/debugger/bug-check-0xc--maximum-wait-objects-exceeded.md new file mode 100644 index 0000000000..c07fcc03a3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc--maximum-wait-objects-exceeded.md @@ -0,0 +1,48 @@ +--- +title: Bug Check 0xC MAXIMUM_WAIT_OBJECTS_EXCEEDED +description: The MAXIMUM_WAIT_OBJECTS_EXCEEDED bug check has a value of 0x0000000C. This indicates that the current thread exceeded the permitted number of wait objects. +ms.assetid: 99d2eb8f-f331-45b8-a96b-68696802c269 +keywords: ["Bug Check 0xC MAXIMUM_WAIT_OBJECTS_EXCEEDED", "MAXIMUM_WAIT_OBJECTS_EXCEEDED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MAXIMUM_WAIT_OBJECTS_EXCEEDED +api_type: +- NA +--- + +# Bug Check 0xC: MAXIMUM\_WAIT\_OBJECTS\_EXCEEDED + + +The MAXIMUM\_WAIT\_OBJECTS\_EXCEEDED bug check has a value of 0x0000000C. This indicates that the current thread exceeded the permitted number of wait objects. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MAXIMUM\_WAIT\_OBJECTS\_EXCEEDED Parameters + + +None + +Cause +----- + +This bug check results from the improper use of **KeWaitForMultipleObjects** or **FsRtlCancellableWaitForMultipleObjects**. + +The caller may pass a pointer to a buffer in this routine's *WaitBlockArray* parameter. The system will use this buffer to keep track of wait objects. + +If a buffer is supplied, the *Count* parameter may not exceed MAXIMUM\_WAIT\_OBJECTS. If no buffer is supplied, the *Count* parameter may not exceed THREAD\_WAIT\_OBJECTS. + +If the value of *Count* exceeds the allowable value, this bug check is issued. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc0000218--status-cannot-load-registry-file.md b/windows-driver-docs-pr/debugger/bug-check-0xc0000218--status-cannot-load-registry-file.md new file mode 100644 index 0000000000..7e30deda06 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc0000218--status-cannot-load-registry-file.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0xC0000218 STATUS_CANNOT_LOAD_REGISTRY_FILE +description: The STATUS_CANNOT_LOAD_REGISTRY_FILE bug check has a value of 0xC0000218. This indicates that a registry file could not be loaded. +ms.assetid: cdcf68fa-8beb-4e21-bc6b-7a9f4c6e9e80 +keywords: ["Bug Check 0xC0000218 STATUS_CANNOT_LOAD_REGISTRY_FILE", "STATUS_CANNOT_LOAD_REGISTRY_FILE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- STATUS_CANNOT_LOAD_REGISTRY_FILE +api_type: +- NA +--- + +# Bug Check 0xC0000218: STATUS\_CANNOT\_LOAD\_REGISTRY\_FILE + + +The STATUS\_CANNOT\_LOAD\_REGISTRY\_FILE bug check has a value of 0xC0000218. This indicates that a registry file could not be loaded. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## STATUS\_CANNOT\_LOAD\_REGISTRY\_FILE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of the name of the registry hive that could not be loaded.

2

Zero (Reserved)

3

Zero (Reserved)

4

Zero (Reserved)

+ +  + +This bug check displays a descriptive text message. The name of the damaged file is displayed as part of the message. + +Cause +----- + +This error occurs if a necessary registry hive file cannot be loaded. Usually this means the file is corrupt or is missing. + +In rare instances, this error can be caused by a driver that has corrupted the registry image in memory, or by a memory error in this region. + +Resolution +---------- + +Try using the the startup recovery mechanism (for example Startup Repair, Recovery Console, or Emergency Recovery Disk) provided by the operating system. If the problem is a missing or corrupt registry file, that usually fixes the problem. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc000021a--status-system-process-terminated.md b/windows-driver-docs-pr/debugger/bug-check-0xc000021a--status-system-process-terminated.md new file mode 100644 index 0000000000..6f52e8e0c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc000021a--status-system-process-terminated.md @@ -0,0 +1,110 @@ +--- +title: Bug Check 0xC000021A STATUS_SYSTEM_PROCESS_TERMINATED +description: The STATUS_SYSTEM_PROCESS_TERMINATED bug check has a value of 0xC000021A. This means that an error has occurred in a crucial user-mode subsystem. +ms.assetid: d46e2948-ff18-49e0-a738-7b90ab54d333 +keywords: ["Bug Check 0xC000021A STATUS_SYSTEM_PROCESS_TERMINATED", "STATUS_SYSTEM_PROCESS_TERMINATED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- STATUS_SYSTEM_PROCESS_TERMINATED +api_type: +- NA +--- + +# Bug Check 0xC000021A: STATUS\_SYSTEM\_PROCESS\_TERMINATED + + +The STATUS\_SYSTEM\_PROCESS\_TERMINATED bug check has a value of 0xC000021A. This means that an error has occurred in a crucial user-mode subsystem. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## STATUS\_SYSTEM\_PROCESS\_TERMINATED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

A string that identifies the problem

2

The error code

3

Reserved

4

Reserved

+ +  + +Cause +----- + +This error occurs when a user-mode subsystem, such as WinLogon or the Client Server Run-Time Subsystem (CSRSS), has been fatally compromised and security can no longer be guaranteed. In response, the operating system switches to kernel mode. Microsoft Windows cannot run without WinLogon or CSRSS. Therefore, this is one of the few cases where the failure of a user-mode service can shut down the system. + +Mismatched system files can also cause this error. This can occur if you have restored your hard disk from a backup. Some backup programs might skip restoring system files that they determine are in use. + +Resolution +---------- + +Running the kernel debugger is not useful in this situation because the actual error occurred in a user-mode process. + +**Resolving an error in a user-mode device driver, system service, or third-party application:** Because bug check 0xC000021A occurs in a user-mode process, the most common culprits are third-party applications. If the error occurred after the installation of a new or updated device driver, system service, or third-party application, the new software should be removed or disabled to isolate the cause. Contact the manufacturer of the software about a possible update. + +**Resolving a mismatched system file problem:** If you have recently restored your hard disk from a backup, check if there is an updated version of the Backup/Restore program available from the manufacturer. + +These steps may be helpful in gathering additional information. + +- Look at the most recently installed applications. To do this navigate to "Uninstall or change a program" in control panel and sort the installed applications by install date. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +These steps may be helpful in resolving this issue. + +- Use the System File Checker tool to repair missing or corrupted system files. The System File Checker is a utility in Windows that allows users to scan for corruptions in Windows system files and restore corrupted files. Use the following command to run the System File Checker tool (SFC.exe). + + ``` + SFC /scannow + ``` + + For more information, see [Use the System File Checker tool to repair missing or corrupted system files](https://support.microsoft.com/kb/929833). + +- Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes. Make sure the virus detection program checks the Master Boot Record for infections. + +- Verify that the system has the latest Service Pack installed. To detect which Service Pack, if any, is installed on your system, click **Start**, click **Run**, type **winver**, and then press ENTER. The **About Windows** dialog box displays the Windows version number and the version number of the Service Pack, if one has been installed. + +**Using Safe Mode** + +Consider using Safe Mode to isolate elements for troubleshooting and if necessary to use Windows. Using Safe Mode loads only the minimum required drivers and system services during the Windows startup. To enter Safe Mode, use **Update and Security** in Settings. Select **Recovery**->**Advanced startup** to boot to maintenance mode. At the resulting menu, choose **Troubleshoot**-> **Advanced Options** -> **Startup Settings** -> **Restart**. After Windows restarts to the **Startup Settings** screen, select option, 4, 5 or 6 to boot to Safe Mode. + +Safe Mode may be available by pressing a function key on boot, for example F8. Refer to information from the manufacturer for specific startup options. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc0000221--status-image-checksum-mismatch.md b/windows-driver-docs-pr/debugger/bug-check-0xc0000221--status-image-checksum-mismatch.md new file mode 100644 index 0000000000..11cd45329a --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc0000221--status-image-checksum-mismatch.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xC0000221 STATUS_IMAGE_CHECKSUM_MISMATCH +description: The STATUS_IMAGE_CHECKSUM_MISMATCH bug check has a value of 0xC0000221. This indicates that a driver or a system DLL has been corrupted. +ms.assetid: d0baccb0-51a2-45c7-ae08-507217d0ac96 +keywords: ["Bug Check 0xC0000221 STATUS_IMAGE_CHECKSUM_MISMATCH", "STATUS_IMAGE_CHECKSUM_MISMATCH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- STATUS_IMAGE_CHECKSUM_MISMATCH +api_type: +- NA +--- + +# Bug Check 0xC0000221: STATUS\_IMAGE\_CHECKSUM\_MISMATCH + + +The STATUS\_IMAGE\_CHECKSUM\_MISMATCH bug check has a value of 0xC0000221. This indicates that a driver or a system DLL has been corrupted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## STATUS\_IMAGE\_CHECKSUM\_MISMATCH Parameters + + +Cause +----- + +This bug check results from a serious error in a driver or other system file. The file header checksum does not match the expected checksum. + +This can also be caused by faulty hardware in the I/O path to the file (a disk error, faulty RAM, or a corrupted page file). + +Resolution +---------- + +To remedy this error, run the Emergency Recovery Disk (ERD) and allow the system to repair or replace the missing or damaged driver file on the system partition. + +You can also run an in-place upgrade over the existing copy of Windows. This preserves all registry settings and configuration information, but replaces all system files. If any Service Packs and/or hotfixes had previously been applied, you need to reinstall them afterward in the appropriate order (latest Service Pack, then any post-Service Pack hotfixes in the order in which they were originally installed, if applicable). + +If a specific file was identified in the bug check message as being corrupted, you can try replacing that individual file manually. If the system partition is formatted with FAT, you can start from an MS-DOS startup disk and copy the file from the original source onto the hard disk. If you have a dual-boot machine, you can boot to your other operating system and replace the file. + +If you want to replace the file on a single-boot system with an NTFS partition, you need to restart the system, press F8 at the operating system **Loader** menu, and choose **Safe Mode with Command Prompt**. From there, copy a fresh version of the file from the original source onto the hard disk. If the file is used as part of the system startup process in Safe Mode, you need to start the computer using the Recovery Console in order to access the file. If these methods fail, try reinstalling Windows and then restoring the system from a backup. + +**Note**   If the original file from the product CD has a filename extension ending in an \_ (underscore), the file needs to be uncompressed before it can be used. The Recovery Console's **Copy** command automatically detects compressed files and expands them as they are copied to the target location. If you are using Safe Mode to access a drive, use the **Expand** command to uncompress and copy the file to the target folder. You can use the **Expand** command in the command line environment of Safe Mode. + +  + +**Resolving a disk error problem:** Disk errors can be a source of file corruption. Run **Chkdsk /f /r** to detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition. + +**Resolving a RAM problem:** If the error occurred immediately after RAM was added to the system, the paging file might be corrupted or the new RAM itself might be either faulty or incompatible. + +**To determine if newly added RAM is causing a bug check** + +1. Return the system to the original RAM configuration. + +2. Use the Recovery Console to access the partition containing the paging file and delete the file pagefile.sys. + +3. While still in the Recovery Console, run **Chkdsk /r** on the partition that contained the paging file. + +4. Restart the system. + +5. Set the paging file to an optimal level for the amount of RAM added. + +6. Shutdown the system and add your RAM. + + The new RAM must meet the system manufacturer's specifications for speed, parity, and type (that is, fast page-mode (FPM) versus extended data out (EDO) versus synchronous dynamic random access memory (SDRAM)). Try to match the new RAM to the existing installed RAM as closely as possible. RAM can come in many different capacities, and more importantly, in different formats (single inline memory modules -- SIMM -- or dual inline memory modules -- DIMM). The electrical contacts can be either gold or tin and it is not wise to mix these contact types. + +If you experience the same error message after reinstalling the new RAM, run hardware diagnostics supplied by the system manufacturer, especially the memory scanner. For details on these procedures, see the owner's manual for your computer. + +When you can log on to the system again, check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. + +Disabling memory caching of the BIOS might also resolve this error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc1--special-pool-detected-memory-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0xc1--special-pool-detected-memory-corruption.md new file mode 100644 index 0000000000..6c83dff818 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc1--special-pool-detected-memory-corruption.md @@ -0,0 +1,124 @@ +--- +title: Bug Check 0xC1 SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION +description: The SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION bug check has a value of 0x000000C1. This indicates that the driver wrote to an invalid section of the special pool. +ms.assetid: 4d5a3d95-de39-4e15-aba8-33257a6f0677 +keywords: ["Bug Check 0xC1 SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION", "SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0xC1: SPECIAL\_POOL\_DETECTED\_MEMORY\_CORRUPTION + + +The SPECIAL\_POOL\_DETECTED\_MEMORY\_CORRUPTION bug check has a value of 0x000000C1. This indicates that the driver wrote to an invalid section of the special pool. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SPECIAL\_POOL\_DETECTED\_MEMORY\_CORRUPTION Parameters + + +Parameter 4 indicates the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

Address that the driver tried to free

Reserved

0

0x20

A driver attempted to free pool which was not allocated.

Address that the driver tried to free

Bytes requested

Bytes calculated (actually given to the caller)

0x21,

+

0x22

A driver attempted to free a bad address.

Address that the driver tried to free

Address where bits are corrupted

Reserved

0x23

A driver freed an address, but nearby bytes within the same page have been corrupted.

Address that the driver tried to free

Address where bits are corrupted

Reserved

0x24

A driver freed an address, but bytes occurring after the end of the allocation have been overwritten.

Current IRQL

Pool type

Number of bytes

0x30

A driver attempted to allocate pool at an incorrect IRQL.

Current IRQL

Pool type

Address that the driver tried to free

0x31

A driver attempted to free pool at an incorrect IRQL.

Address that the driver tried to free

Address where one bit is corrupted

Reserved

0x32

A driver freed an address, but nearby bytes within the same page have a single bit error.

+ +  + +The \_POOL\_TYPE codes are enumerated in ntddk.h. In particular, zero indicates nonpaged pool and one indicates paged pool. + +Cause +----- + +A driver has written to an invalid section of the special pool. + +Resolution +---------- + +Obtain a backtrace of the current thread. This backtrace will usually reveal the source of the error. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc2--bad-pool-caller.md b/windows-driver-docs-pr/debugger/bug-check-0xc2--bad-pool-caller.md new file mode 100644 index 0000000000..8bd4e8ad1d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc2--bad-pool-caller.md @@ -0,0 +1,252 @@ +--- +title: (Developer Content) Bug Check 0xC2 BAD_POOL_CALLER +description: The BAD_POOL_CALLER bug check has a value of 0x000000C2. This indicates that the current thread is making a bad pool request. +ms.assetid: 64803335-ab93-4c4d-9b30-2ec15a13303f +keywords: ["(Developer Content) Bug Check 0xC2 BAD_POOL_CALLER", "BAD_POOL_CALLER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BAD_POOL_CALLER +api_type: +- NA +--- + +# (Developer Content) Bug Check 0xC2: BAD\_POOL\_CALLER + + +The BAD\_POOL\_CALLER bug check has a value of 0x000000C2. This indicates that the current thread is making a bad pool request. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BAD\_POOL\_CALLER Parameters + + +**Parameter 1** indicates the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x00

0

Pool type

Pool tag

The current thread requested a zero-byte pool allocation.

0x01,

+

0x02,

+

0x04

Pointer to pool header

First part of pool header contents

0

The pool header has been corrupted.

0x06

Reserved

Pointer to pool header

Pool header contents

The current thread attempted to free the pool, which was already freed.

0x07

Reserved

Pool header contents

Address of the block of pool being freed

The current thread attempted to free the pool, which was already freed.

0x08

Current IRQL

Pool type

Size of allocation, in bytes

The current thread attempted to allocate the pool at an invalid IRQL.

0x09

Current IRQL

Pool type

Address of pool

The current thread attempted to free the pool at an invalid IRQL.

0x0A

Address of pool

Allocator's tag

Tag being used in the attempted free

The current thread attempted to free pool memory by using the wrong tag.

+

(The memory might belong to another component.)

0x0B,

+

0x0C,

+

or 0x0D

Address of pool

Pool allocation's tag

Bad quota process pointer

The current thread attempted to release a quota on a corrupted pool allocation.

0x40

Starting address

Start of system address space

0

The current thread attempted to free the kernel pool at a user-mode address.

0x41

Starting address

Physical page frame

Highest physical page frame

The current thread attempted to free a non-allocated nonpaged pool address.

0x42

+

or 0x43

Address being freed

0

0

The current thread attempted to free a virtual address that was never in any pool.

0x44

Starting address

Reserved

0

The current thread attempted to free a non-allocated nonpaged pool address.

0x46

Starting address

0

0

The current thread attempted to free an invalid pool address.

0x47

Starting address

Physical page frame

Highest physical page frame

The current thread attempted to free a non-allocated nonpaged pool address.

0x48

Starting address

Reserved

Reserved

The current thread attempted to free a non-allocated paged pool address.

0x50

Starting address

Start offset, in pages, from beginning of paged pool

Size of paged pool, in bytes

The current thread attempted to free a non-allocated paged pool address.

0x60

Starting address

0

0

The current thread attempted to free an invalid contiguous memory address.

+

(The caller of MmFreeContiguousMemory is passing a bad pointer.)

0x99

Address that is being freed

0

0

The current thread attempted to free pool with an invalid address.

+

(This code can also indicate corruption in the pool header.)

0x9A

Pool type

Number of bytes requested

Pool tag

The current thread marked an allocation request MUST_SUCCEED.

+

(This pool type is no longer supported.)

0x9B

Pool type

Number of bytes requested

Caller's address

The current thread attempted to allocate a pool with a tag of 0

+

(This would be untrackable, and possibly corrupt the existing tag tables.)

0x9C

Pool type

Number of bytes requested

Caller's address

The current thread attempted to allocate a pool with a tag of "BIG".

+

(This would be untrackable and could possibly corrupt the existing tag tables.)

0x9D

Incorrect pool tag used

Pool type

Caller's address

The current thread attempted to allocate a pool with a tag that does not contain any letters or digits. Using such tags makes tracking pool issues difficult.

0x41286

Reserved

Reserved

Start offset from the beginning of the paged pool, in pages

The current thread attempted to free a paged pool address in the middle of an allocation.

+ +  + +The \_POOL\_TYPE codes are enumerated in Ntddk.h. In particular, 0 indicates nonpaged pool and 1 indicates paged pool. + +Cause +----- + +An invalid pool request has been made by the current thread. Typically this is at a bad IRQL level or double freeing the same memory allocation, etc. + +Resolution +---------- + +Activate Driver Verifier with memory pool options enabled, to obtain more information about these errors and to locate the faulting driver. + +**Driver Verifier** + +Driver Verifier is a tool that runs in real time to examine the behavior of drivers. If it see errors in the execution of driver code, it proactively creates an exception to allow that part of the driver code to be further scrutinized. The driver verifier manager is built into Windows and is available on all Windows PCs. To start the driver verifier manager, type *Verifer* at a command prompt. You can configure which drivers you would like to verify. The code that verifies drivers adds overhead as it runs, so try and verify the smallest number of drivers as possible. For more information, see [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448). + +**Windows Memory Diagnostics** + +In particular, for situations with memory pool corruption, run the Windows Memory Diagnostics tool, to try and isolate the physical memory as a cause. In the control panel search box, type Memory, and then click **Diagnose your computer's memory problems**.‌ After the test is run, use Event viewer to view the results under the System log. Look for the *MemoryDiagnostics-Results* entry to view the results. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc4--driver-verifier-detected-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xc4--driver-verifier-detected-violation.md new file mode 100644 index 0000000000..7e6865fea0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc4--driver-verifier-detected-violation.md @@ -0,0 +1,1578 @@ +--- +title: Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION +description: The DRIVER_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000C4. This is the general bug check code for fatal errors found by Driver Verifier. +ms.assetid: 7814f827-05fc-419b-b428-4565978bbb52 +keywords: ["Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION", "DRIVER_VERIFIER_DETECTED_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_VERIFIER_DETECTED_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xC4: DRIVER\_VERIFIER\_DETECTED\_VIOLATION + + +The DRIVER\_VERIFIER\_DETECTED\_VIOLATION bug check has a value of 0x000000C4. This is the general bug check code for fatal errors found by Driver Verifier. For more information, see [Handling a Bug Check When Driver Verifier is Enabled](handling-a-bug-check-when-driver-verifier-is-enabled.md). + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_VERIFIER\_DETECTED\_VIOLATION Parameters + + +Parameter 1 identifies the type of violation. The meaning of the remaining parameters varies with the value of Parameter 1. The parameter values are described in the following table. + +**Note**  If you have trouble viewing all 5 columns in this table, try the following: +- Expand your browser window to full size. +- Place the cursor in the table and use the arrow keys to scroll left and right. +- Or use the [MSDN Library version](http://msdn.microsoft.com/library/ff560187.aspx) of this page. + +  + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x00

Current IRQL

Pool type

0

The driver requested a zero-byte pool allocation.

0x01

Current IRQL

Pool type

Size of allocation, in bytes

The driver attempted to allocate paged memory with IRQL > APC_LEVEL.

0x02

Current IRQL

Pool type

Size of allocation, in bytes

The driver attempted to allocate nonpaged memory with IRQL > DISPATCH_LEVEL.

0x10

Bad Address

0

0

The driver attempted to free an address that was not returned from an allocate call.

0x11

Current IRQL

Pool type

Address of pool

The driver attempted to free paged pool with IRQL > APC_LEVEL.

0x12

Current IRQL

Pool type

Address of pool

The driver attempted to free nonpaged pool with IRQL > DISPATCH_LEVEL.

0x13 or

+

0x14

Reserved

Pointer to pool header

Pool header contents

The driver attempted to free memory pool which was already freed.

0x16

Reserved

Pool address

0

The driver attempted to free pool at a bad address, or the driver passed invalid parameters to a memory routine.

0x30

Current IRQL

Requested IRQL

0

The driver passed an invalid parameter to [KeRaiseIrql](https://msdn.microsoft.com/library/windows/hardware/ff553079).

+

(The parameter was either a value lower than the current IRQL, or a value higher than HIGH_LEVEL. This may be the result of using an uninitialized parameter.)

0x31

Current IRQL

Requested IRQL

0: New IRQL is bad

+

1: New IRQL is invalid inside a DPC routine

The driver passed an invalid parameter to [KeLowerIrql](https://msdn.microsoft.com/library/windows/hardware/ff552968).

+

(The parameter was either a value higher than the current IRQL, or a value higher than HIGH_LEVEL. This may be the result of using an uninitialized parameter.)

0x32

Current IRQL

Spin lock address

0

The driver called [KeReleaseSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff553145) at an IRQL other than DISPATCH_LEVEL.

+

(This may be due to a double-release of a spin lock.)

0x33

Current IRQL

Fast mutex address

0

The driver attempted to acquire fast mutex with IRQL > APC_LEVEL.

0x34

Current IRQL

Fast mutex address

0

The driver attempted to release fast mutex at an IRQL other than APC_LEVEL.

0x35

Current IRQL

Spin lock address

Old IRQL

The kernel released a spin lock with IRQL not equal to DISPATCH_LEVEL.

0x36

Current IRQL

Spin lock number

Old IRQL

The kernel released a queued spin lock with IRQL not equal to DISPATCH_LEVEL.

0x37

Current IRQL

Thread APC disable count

Resource

The driver tried to acquire a resource, but APCs are not disabled.

0x38

Current IRQL

Thread APC disable count

Resource

The driver tried to release a resource, but APCs are not disabled.

0x39

Current IRQL

Thread APC disable count

Mutex

The driver tried to acquire a mutex "unsafe" with IRQL not equal to APC_LEVEL on entry.

0x3A

Current IRQL

Thread APC disable count

Mutex

The driver tried to release a mutex "unsafe" with IRQL not equal to APC_LEVEL on entry.

0x3C

Handle passed to routine

Object type

0

The driver called [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679) with a bad handle.

0x3D

0

0

Address of the bad resource

The driver passed a bad (unaligned) resource to [ExAcquireResourceExclusive](https://msdn.microsoft.com/library/windows/hardware/ff544345).

0x3E

0

0

0

The driver called [KeLeaveCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552964) for a thread that is not currently in a critical region.

0x3F

Object address

New object reference count.

+

-1: dereference case

+

1: reference case

0

The driver applied [ObReferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff558678) to an object that has a reference count of zero, or the driver applied [ObDereferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff557724) to an object that has a reference count of zero.

0x40

Current IRQL

Spin lock address

0

The driver called [KeAcquireSpinLockAtDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff551921) with IRQL < DISPATCH_LEVEL.

0x41

Current IRQL

Spin lock address

0

The driver called [KeReleaseSpinLockFromDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff553150) with IRQL < DISPATCH_LEVEL.

0x42

Current IRQL

Spin lock address

0

The driver called [KeAcquireSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff551917) with IRQL > DISPATCH_LEVEL.

0x51

Base address of allocation

Address of the reference beyond the allocation

Number of charged bytes

The driver attempted to free memory after having written past the end of the allocation. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x52

Base address of allocation

Reserved

Number of charged bytes

The driver attempted to free memory after having written past the end of the allocation. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x53,

+

0x54,

+

or 0x59

Base address of allocation

Reserved

Reserved

The driver attempted to free memory after having written past the end of the allocation. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x60

Bytes allocated from paged pool

Bytes allocated from nonpaged pool

Total number of allocations that were not freed

The driver is unloading without first freeing its pool allocations. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x61

Bytes allocated from paged pool

Bytes allocated from nonpaged pool

Total number of allocations that were not freed

A driver thread is attempting to allocate pool memory while the driver is unloading. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x62

Name of the driver

Reserved

Total number of allocations that were not freed, including both paged and nonpaged pool

The driver is unloading without first freeing its pool allocations. A bug check with this parameter occurs only when the Pool Tracking option of Driver Verifier is active.

0x70

Current IRQL

MDL address

Access mode

The driver called [MmProbeAndLockPages](https://msdn.microsoft.com/library/windows/hardware/ff554664) with IRQL > DISPATCH_LEVEL.

0x71

Current IRQL

MDL address

Process address

The driver called MmProbeAndLockProcessPages with IRQL > DISPATCH_LEVEL.

0x72

Current IRQL

MDL address

Process address

The driver called MmProbeAndLockSelectedPages with IRQL > DISPATCH_LEVEL.

0x73

Current IRQL

In 32-bit Windows: Low 32 bits of the physical address

+

In 64-bit Windows: the 64-bit physical address

Number of bytes

The driver called [MmMapIoSpace](https://msdn.microsoft.com/library/windows/hardware/ff554618) with IRQL > DISPATCH_LEVEL.

0x74

Current IRQL

MDL address

Access mode

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622) in kernel mode with IRQL > DISPATCH_LEVEL.

0x75

Current IRQL

MDL address

Access mode

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622) in user mode with IRQL > APC_LEVEL.

0x76

Current IRQL

MDL address

Access mode

The driver called [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629) in kernel mode with IRQL > DISPATCH_LEVEL.

0x77

Current IRQL

MDL address

Access mode

The driver called [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629) in user mode with IRQL > APC_LEVEL.

0x78

Current IRQL

MDL address

0

The driver called [MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381) with IRQL > DISPATCH_LEVEL.

0x79

Current IRQL

Virtual address being unmapped

MDL address

The driver called [MmUnmapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff556391) in kernel mode with IRQL > DISPATCH_LEVEL.

0x7A

Current IRQL

Virtual address being unmapped

MDL address

The driver called [MmUnmapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff556391) in user mode with IRQL > APC_LEVEL.

0x7B

Current IRQL

Virtual address being unmapped

Number of bytes

The driver called [MmUnmapIoSpace](https://msdn.microsoft.com/library/windows/hardware/ff556387) with IRQL > APC_LEVEL.

0x7C

MDL address

MDL flags

0

The driver called [MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381), and passed an MDL whose pages were never successfully locked.

0x7D

MDL address

MDL flags

0

The driver called [MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381), and passed an MDL whose pages are from nonpaged pool.

+

(These should never be unlocked.)

0x7E

Current IRQL

DISPATCH_LEVEL

0

The driver called [MmAllocatePagesForMdl](https://msdn.microsoft.com/library/windows/hardware/ff554482), [MmAllocatePagesForMdlEx](https://msdn.microsoft.com/library/windows/hardware/ff554489), or [MmFreePagesFromMdl](https://msdn.microsoft.com/library/windows/hardware/ff554521) with IRQL > DISPATCH_LEVEL.

0x7F

Current IRQL

MDL address

MDL flags

The driver called [BuildMdlForNonPagedPool](https://msdn.microsoft.com/library/windows/hardware/ff554498) and passed an MDL whose pages are from paged pool.

0x80

Current IRQL

Event address

0

The driver called [KeSetEvent](https://msdn.microsoft.com/library/windows/hardware/ff553253) with IRQL > DISPATCH_LEVEL.

0x81

MDL address

MDL flags

0

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622).

+

(You should use [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629) instead, with the BugCheckOnFailure parameter set to FALSE.)

0x82

MDL address

MDL flags

0

The driver called [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629) with the BugCheckOnFailure parameter equal to TRUE.

+

(This parameter should be set to FALSE.)

0x83

Start of physical address range to map

Number of bytes to map

First page frame number that isn't locked down

The driver called [MmMapIoSpace](https://msdn.microsoft.com/library/windows/hardware/ff554618) without having locked down the MDL pages. The physical pages represented by the physical address range being mapped must have been locked down prior to making this call.

0x85

MDL address

Number of pages to map

First page frame number that isn't locked down

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622) without having locked down the MDL pages.

0x89

MDL address

Pointer to the non-memory page in the MDL

The non-memory page number in the MDL

An MDL is not marked as "I/O", but it contains non-memory page addresses.

0x91

Reserved

Reserved

Reserved

The driver switched stacks using a method that is not supported by the operating system. The only supported way to extend a kernel mode stack is by using [KeExpandKernelStackAndCallout](https://msdn.microsoft.com/library/windows/hardware/ff552030).

0xA0 (Windows Server 2003 and later operating systems only)

Pointer to the IRP making the read or write request

Device object of the lower device

Number of the sector in which the error was detected

A cyclic redundancy check (CRC) error was detected on a hard disk. A bug check with this parameter occurs only when the Disk Integrity Checking option of Driver Verifier is active.

0xA1 (Windows Server 2003 and later operating systems only)

Copy of the IRP making the read or write request. (The actual IRP has been completed.)

Device object of the lower device

Number of the sector in which the error was detected

A CRC error was detected on a sector (asynchronously). A bug check with this parameter occurs only when the Disk Integrity Checking option of Driver Verifier is active.

0xA2 (Windows Server 2003 and later operating systems only)

IRP making the read or write request, or a copy of this IRP

Device object of the lower device

Number of the sector in which the error was detected

The CRCDISK checksum copies don't match. This could be a paging error. A bug check with this parameter occurs only when the Disk Integrity Checking option of Driver Verifier is active.

0xB0 (Windows Vista and later operating systems only)

MDL address

MDL flags

Incorrect MDL flags

The driver called [MmProbeAndLockPages](https://msdn.microsoft.com/library/windows/hardware/ff554664) for an MDL with incorrect flags. For example, the driver passed an MDL created by [MmBuildMdlForNonPagedPool](https://msdn.microsoft.com/library/windows/hardware/ff554498) to MmProbeAndLockPages.

0xB1 (Windows Vista and later operating systems only)

MDL address

MDL flags

Incorrect MDL flags

The driver called MmProbeAndLockProcessPages for an MDL with incorrect flags. For example, the driver passed an MDL created by [MmBuildMdlForNonPagedPool](https://msdn.microsoft.com/library/windows/hardware/ff554498) to MmProbeAndLockProcessPages.

0xB2 (Windows Vista and later operating systems only)

MDL address

MDL flags

Incorrect MDL flags

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622) for an MDL with incorrect flags. For example, the driver passed an MDL that is already mapped to a system address or that was not locked to MmMapLockedPages.

0xB3 (Windows Vista and later operating systems only)

MDL address

MDL flags

Missing MDL flags (at least one was expected)

The driver called [MmMapLockedPages](https://msdn.microsoft.com/library/windows/hardware/ff554622) for an MDL with incorrect flags. For example, the driver passed an MDL that is not locked to MmMapLockedPages.

0xB4 (Windows Vista and later operating systems only)

MDL address

MDL flags

Unexpected partial MDL flag

The driver called [MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381) for a partial MDL. A partial MDL is one that was created by [IoBuildPartialMdl](https://msdn.microsoft.com/library/windows/hardware/ff548324).

0xB8 (Windows Vista and later operating systems only)

MDL address

MDL flags

Reserved

The pages that are described by the MDL are still mapped. The driver must unmap the pages before calling IoFreeMdl. +

0xC0 (Windows Vista and later operating systems only)

Address of the IRP

Reserved

Reserved

The driver called [IoCallDriver](https://msdn.microsoft.com/library/windows/hardware/ff548336) with interrupts disabled.

0xC1 (Windows Vista and later operating systems only)

Address of the driver dispatch routine

Reserved

Reserved

A driver dispatch routine was returned with interrupts disabled.

0xC2 (Windows Vista and later operating systems only)

Reserved

Reserved

Reserved

The driver called a Fast I/O dispatch routine after interrupts were disabled.

0xC3 (Windows Vista and later operating systems only)

Address of the driver Fast I/O dispatch routine

Reserved

Reserved

A driver Fast I/O dispatch routine was returned with interrupts disabled.

0xC5 (Windows Vista and later operating systems only)

Address of the driver dispatch routine

The current thread's APC disable count

The thread's APC disable count prior to calling the driver dispatch routine

A driver dispatch routine has changed the thread's APC disable count.

+

The APC disable count is decremented each time a driver calls [KeEnterCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552021), [FsRtlEnterFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545900), or acquires a mutex.

+

The APC disable count is incremented each time a driver calls [KeLeaveCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552964), [KeReleaseMutex](https://msdn.microsoft.com/library/windows/hardware/ff553140), or [FsRtlExitFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545908).

+

Because these calls should always be in pairs, the APC disable count should be zero whenever a thread is exited. A negative value indicates that a driver has disabled APC calls without re-enabling them. A positive value indicates that the reverse is true.

0xC6 (Windows Vista and later operating systems only)

Address of the driver Fast I/O dispatch routine

Current thread's APC disable count

The thread's APC disable count prior to calling the Fast I/O driver dispatch routine

A driver Fast I/O dispatch routine has changed the thread's APC disable count.

+

The APC disable count is decremented each time a driver calls [KeEnterCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552021), [FsRtlEnterFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545900), or acquires a mutex.

+

The APC disable count is incremented each time a driver calls [KeLeaveCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552964), [KeReleaseMutex](https://msdn.microsoft.com/library/windows/hardware/ff553140), or [FsRtlExitFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545908).

+

Because these calls should always be in pairs, the APC disable count should be zero whenever a thread is exited. A negative value indicates that a driver has disabled APC calls without re-enabling them. A positive value indicates that the reverse is true.

0xCA (Windows Vista and later operating systems only)

Address of the lookaside list

Reserved

Reserved

The driver has attempted to re-initialize a lookaside list.

0xCB (Windows Vista and later operating systems only)

Address of the lookaside list

Reserved

Reserved

The driver has attempted to delete an uninitialized lookaside list.

0xCC (Windows Vista and later operating systems only)

Address of the lookaside list

Starting address of the pool allocation

Size of the pool allocation

The driver has attempted to free a pool allocation that contains an active lookaside list.

0xCD (Windows Vista and later operating systems only)

Address of the lookaside list

Block size specified by the caller

Minimum supported block size

The driver has attempted to create a lookaside list with an allocation block size that is too small.

0xD0 (Windows Vista and later operating systems only)

Address of the ERESOURCE structure

Reserved

Reserved

The driver has attempted to re-initialize an ERESOURCE structure.

0xD1 (Windows Vista and later operating systems only)

Address of the ERESOURCE structure

Reserved

Reserved

The driver has attempted to delete an uninitialized ERESOURCE structure.

0xD2 (Windows Vista and later operating systems only)

Address of the ERESOURCE structure

Starting address of the pool allocation

Size of the pool allocation

The driver has attempted to free a pool allocation that contains an active ERESOURCE structure.

0xD5 (Windows Vista and later operating systems only)

Address of the IO_REMOVE_LOCK structure created by the checked build version of the driver

Current [IoReleaseRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff549560) tag

Reserved

The current [IoReleaseRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff549560) tag does not match the previous [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204) tag. If the driver calling IoReleaseRemoveLock is not in a checked build, Parameter 2 is the address of the shadow IO_REMOVE_LOCK structure created by Driver Verifier on behalf of the driver. In this case, the address of the IO_REMOVE_LOCK structure used by the driver is not used at all, because Driver Verifier is replacing the lock address for all the remove lock APIs. A bug check with this parameter occurs only when the I/O Verification option of Driver Verifier is active.

0xD6 (Windows Vista and later operating systems only)

Address of the IO_REMOVE_LOCK structure created by the checked build version of the driver

Tag that does not match previous [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204) tag

Previous [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204) tag

The current [IoReleaseRemoveLockAndWait](https://msdn.microsoft.com/library/windows/hardware/ff549567) tag does not match the previous [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204) tag. If the driver calling [IoReleaseRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff549560) is not a checked build, Parameter 2 is the address of the shadow IO_REMOVE_LOCK structure created by Driver Verifier on behalf of the driver. In this case, the address of the IO_REMOVE_LOCK structure used by the driver is not used at all, because Driver Verifier is replacing the lock address for all the remove lock APIs. A bug check with this parameter occurs only when the I/O Verification option of Driver Verifier is active.

0xD7 (Windows 7 operating systems and later only)

Address of the checked build Remove Lock structure that is used internally by Driver Verifier

Address of the Remove Lock structure that is specified by the driver

Reserved

A Remove Lock cannot be re-initialized, even after it calls [IoReleaseRemoveLockAndWait](https://msdn.microsoft.com/library/windows/hardware/ff549567), because other threads might still be using that lock (by calling [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204)). The driver should allocate the Remove Lock inside its device extension, and initialize it a single time. The lock will be deleted together with the device extension.

0xDA (Windows Vista and later operating systems only)

Starting address of the driver

WMI callback address inside the driver

Reserved

An attempt was made to unload a driver that has not deregistered its WMI callback function.

0xDB (Windows Vista and later operating systems only)

Address of the device object

Reserved

Reserved

An attempt was made to delete a device object that was not deregistered from WMI.

0xDC (Windows Vista and later operating systems only)

Reserved

Reserved

Reserved

An invalid RegHandle value was specified as a parameter of the function [EtwUnregister](https://msdn.microsoft.com/library/windows/hardware/ff545613).

0xDD (Windows Vista and later operating systems only)

Address of the call to EtwRegister

Starting address of the unloading driver

For Windows 8Windows 8 and later versions, this parameter is the ETW RegHandle value.

An attempt was made to unload a driver without calling [EtwUnregister](https://msdn.microsoft.com/library/windows/hardware/ff545613).

0xDF (Windows 7 operating systems and later only)

Synchronization object address

The synchronization object is in session address space. Synchronization objects are not allowed in session address space because they can be manipulated from another session or from system threads that have no session virtual address space.

0xE0 (Windows Vista and later operating systems only)

User-mode address that is used as a parameter

Size ,in bytes, of the address range that is used as a parameter

Reserved

A call was made to an operating system kernel function that specified a user-mode address as a parameter.

0xE1 (Windows Vista and later operating systems only)

Address of the synchronization object

Reserved

Reserved

A synchronization object was found to have an address that was either invalid or pageable.

0xE2 (Windows Vista and later operating systems only)

Address of the IRP

User-mode address present in the IRP

Reserved

An IRP with Irp->RequestorMode set to KernelMode was found to have a user-mode address as one of its members.

0xE3 (Windows Vista and later operating systems only)

Address of the call to the API

User-mode address used as a parameter in the API

Reserved

A driver has made a call to a kernel-mode ZwXxx routine with a user-mode address as a parameter.

0xE4 (Windows Vista and later operating systems only)

Address of the call to the API

Address of the malformed UNICODE_STRING structure

Reserved

A driver has made a call to a kernel-mode ZwXxx routine with a malformed UNICODE_STRING structure as a parameter.

0xE5 (Windows Vista and later operating systems only)

Current IRQL

Reserved

Reserved

A call was made to a Kernel API at the incorrect IRQL.

0xE6 (Windows Vista and later operating systems only)

Address inside the driver making the Zw API call

Current IRQL

Special kernel APCs.

Kernel Zw API was not called at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

0xEA (Windows Vista and later operating systems only)

Current IRQL

The thread's APC disable count

Address of the pushlock

A driver has attempted to acquire a pushlock while APCs are enabled.

0xEB (Windows Vista and later operating systems only)

Current IRQL

The thread's APC disable count

Address of the pushlock

A driver has attempted to release a pushlock while APCs are enabled.

0xF0 (Windows Vista and later operating systems only)

Address of the destination buffer

Address of the source buffer

Number of bytes to copy

A driver called the memcpy function with overlapping source and destination buffers.

0xF5 (Windows Vista and later operating systems only)

Address of the NULL handle

Object type

Reserved

A driver passed a NULL handle to [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679).

0xF6 (Windows 7 operating systems and later)

Handle value being referenced

Address of the current process

Address inside the driver that performs the incorrect reference

A driver references a user-mode handle as kernel mode.

0xF7 (Windows 7 operating systems and later)

Handle value specified by the caller

Object type specified by the caller

AccessMode specified by the caller

A driver is attempting a user-mode reference for a kernel handle in the context of the system process.

0xFA (Windows 7 operating systems and later)

Completion routine address.

IRQL value before it calls the completion routine

Current IRQL value, after it calls the completion routine

The IRP completion routine returned at an IRQL that was different from the IRQL the routine was called at.

0xFB (Windows 7 operating systems and later)

Completion routine address

Current thread's APC disable count

The thread's APC disable count before it calls the IRP completion routine

The thread's APC disable count was changed by the driver's IRP completion routine.

+

The APC disable count is decremented each time a driver calls [KeEnterCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552021), [FsRtlEnterFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545900), or acquires a mutex.

+

The APC disable count is incremented each time a driver calls [KeLeaveCriticalRegion](https://msdn.microsoft.com/library/windows/hardware/ff552964), [KeReleaseMutex](https://msdn.microsoft.com/library/windows/hardware/ff553140), or [FsRtlExitFileSystem](https://msdn.microsoft.com/library/windows/hardware/ff545908).

+

Because these calls should always be in pairs, the APC disable count should be zero whenever a thread is exited. A negative value indicates that a driver has disabled APC calls without re-enabling them. A positive value indicates that the reverse is true.

0x105

+

(Windows 7 operating systems and later)

Address of the IRP

The driver uses ExFreePool instead of IoFreeIrp to release the IRP.

0x10A

+

(Windows 7 operating systems and later)

The driver attempts to charge pool quota to the Idle process.

0x10B

+

(Windows 7 operating systems and later)

The driver attempts to charge pool quota from a DPC routine. This is incorrect because the current process context is undefined.

0x110

+

(Windows 7 operating systems and later)

Address of the Interrupt Service Routine

Address of the extended context that was saved before it executed the ISR

Address of the extended context was saved after it executed the ISR

The interrupt service routine (ISR) for the driver has corrupted the extended thread context.

0x111

+

(Windows 7 operating systems and later)

Address of the Interrupt Service Routine

IRQL before executing ISR

IRQL after executing ISR

The interrupt Service Routine returned a changed IRQL.

0x115

+

(Windows 7 operating systems and later)

The address of the thread that is responsible for the shutdown, which might be deadlocked

Driver Verifier detected that the system has taken longer than 20 minutes and shutdown is not complete.

0x11A

+

(Windows 7 operating systems and later)

Current IRQL

The driver calls KeEnterCriticalRegion at IRQL > APC_LEVEL.

0x11B

+

(Windows 7 operating systems and later)

Current IRQL

The driver calls KeLeaveCriticalRegion at IRQL > APC_LEVEL.

0x120

+

(Windows 7 operating systems and later)

Address of the IRQL value

Address of the Object to wait on

Address of Timeout value

The thread waits at IRQL > DISPATCH_LEVEL. Callers of KeWaitForSingleObject or KeWaitForMultipleObjects must run at IRQL <= DISPATCH_LEVEL.

0x121

+

(Windows 7 operating systems and later)

Address of the IRQL value

Address of the Object to wait on

Address of Timeout value

The thread waits at IRQL equals DISPATCH_LEVEL and the Timeout is NULL. Callers of KeWaitForSingleObject or KeWaitForMultipleObjects can run at IRQL <= DISPATCH_LEVEL. If a NULL pointer is supplied for Timeout, the calling thread remains in a wait state until the Object is signaled.

0x122

+

(Windows 7 operating systems and later)

Address of the IRQL value

Address of the Object to wait on

Address of the Timeout value

The thread waits at DISPATCH_LEVEL and Timeout value is not equal to zero (0). If the Timeout != 0, the callers of KeWaitForSingleObject or KeWaitForMultipleObjects must run at IRQL <= APC_LEVEL.

0x123

+

(Windows 7 operating systems and later)

Address of the Object to wait on

The caller of KeWaitForSingleObject or KeWaitForMultipleObjects specified the wait as UserMode, but the Object is on the kernel stack.

0x130

+

(Windows 7 operating systems and later)

Address of work item

The work item is in session address space. Work items are not allowed in session address space because they can be manipulated from another session or from system threads that have no session virtual address space.

0x131

+

(Windows 7 operating systems and later)

Address of work item

The work item is in pageable memory. Work items have to be in nonpageable memory because the kernel uses them at DISPATCH_LEVEL.

0x135

Address of IRP

Number of milliseconds allowed between the [IoCancelIrp](https://msdn.microsoft.com/library/windows/hardware/ff548338) call and the completion for this IRP

The canceled IRP did not completed in the expected time The driver took longer than expected to complete the canceled IRP.

0x13A

Address of the pool block being freed

Incorrect value

Address of the incorrect value

The driver has called [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) and Driver Verifier detects an error in one of the internal values that is used to track pool usage.

0x13B

Address of the pool block being freed

Address of the incorrect value

Address of a pointer to the incorrect memory page

The driver has called [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) and Driver Verifier detects an error in one of the internal values that is used to track pool usage.

0x13C

Address of the pool block being freed

Incorrect value

Address of the incorrect value

The driver has called [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) and Driver Verifier detects an error in one of the internal values that is used to track pool usage.

0x13D

Address of the pool block being freed

Address of the incorrect value

Correct value that was expected

The driver has called [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) and Driver Verifier detects an error in one of the internal values that is used to track pool usage.

0x13E

Pool block address specified by the caller

Pool block address tracked by Driver Verifier

Pointer to the pool block address that is tracked by Driver Verifier

The pool block address specified by the caller of [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) is different from the address tracked by Driver Verifier.

0x13F

Address of the pool block being freed

Number of bytes being freed

Pointer to the number of bytes tracked by Driver Verifier

The number of bytes of memory being freed in the call to [ExFreePool](https://msdn.microsoft.com/library/windows/hardware/ff544590) is different from the number of bytes tracked by Driver Verifier.

0x140

Current IRQL

MDL address

Associated virtual address with this MDL

A non-locked MDL was constructed from either pageable or tradable memory.

0x1000 (Windows XP and later operating systems only)

Address of the resource

Reserved

Reserved

Self-deadlock: The current thread has tried to recursively acquire a resource. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1001 (Windows XP and later operating systems only)

Address of the resource that was the final cause of the deadlock

Reserved

Reserved

Deadlock: A lock hierarchy violation has been found. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

+

(Use the [!deadlock](-deadlock.md) extension for further information.)

0x1002 (Windows XP and later operating systems only)

Address of the resource

Reserved

Reserved

Uninitialized resource: A resource has been acquired without having been initialized first. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1003 (Windows XP and later operating systems only)

Address of the resource that is being released deadlocked

Address of the resource that should have been released first

Reserved

Unexpected release: A resource has been released in an incorrect order. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1004 (Windows XP and later operating systems only)

Address of the resource

Address of the thread that acquired the resource

Address of the current thread

Unexpected thread: The wrong thread releases a resource. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1005 (Windows XP and later operating systems only)

Address of the resource

Reserved

Reserved

Multiple initialization: A resource is initialized more than one time. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1007 (Windows XP and later operating systems only)

Address of the resource

Reserved

Reserved

Unacquired resource: A resource is released before it has been acquired. A bug check with this parameter occurs only when the Deadlock Detection option of Driver Verifier is active.

0x1008

+

(Windows 7 operating systems and later)

Lock address

Driver Verifier internal data

Driver Verifier internal data

The driver tried to acquire a lock by using an API that is mismatched for this lock type.

0x1009

+

(Windows 7 operating systems and later)

Lock address

Driver Verifier internal data

Driver Verifier internal data

The driver tried to release a lock by using an API that is mismatched for this lock type.

0x100A

+

(Windows 7 operating systems and later)

Owner thread address

Driver Verifier internal data

The terminated thread owns the lock.

0x100B

+

(Windows 7 operating systems and later)

Lock address

Owner thread address

Driver Verifier internal address

The deleted lock is still owned by a thread.

0xA001

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch object (if NON-NULL)

Reserved (unused)

VM Switch: The SourceHandle for the caller-supplied NetBufferList must be set. See the [AllocateNetBufferListForwardingContext](https://msdn.microsoft.com/library/windows/hardware/hh598134) routine.

0xA002

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch object (if NON-NULL).

Reserved (unused)

VM Switch: The caller supplied NetBufferList's forwarding detail is not zero. See the [AllocateNetBufferListForwardingContext](https://msdn.microsoft.com/library/windows/hardware/hh598134) routine.

0xA003

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch object (if NON-NULL).

Reserved (unused)

VM Switch: The caller supplied a NetBufferList with packet header or routing context that is NULL. See [Packet Management Guidelines for the Extensible Switch Data Path](https://msdn.microsoft.com/library/windows/hardware/hh582270).

0xA004

+

(Windows 8.1 operating systems and later)

ID of invalid port

NIC Index

A pointer to the virtual switch object (if NON-NULL).

VM Switch: The caller specified an invalid Port and NIC index combination. See [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182).

0xA005

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the Destination list.

A pointer to the virtual switch object (if NON-NULL).

VM Switch: The caller supplied an invalid destination. See [AddNetBufferListDestination](https://msdn.microsoft.com/library/windows/hardware/hh598133) and [UpdateNetBufferListDestinations](https://msdn.microsoft.com/library/windows/hardware/hh598303).

0xA006

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch object (if NON-NULL).

Reserved (unused)

VM Switch: The caller supplied an invalid source NIC or Port object. See [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182).

0xA007

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch object (if NON-NULL).

Reserved (unused)

VM Switch: The caller supplied an invalid destination list. See [AddNetBufferListDestination](https://msdn.microsoft.com/library/windows/hardware/hh598133) and [UpdateNetBufferListDestinations](https://msdn.microsoft.com/library/windows/hardware/hh598303).

0xA008

+

(Windows 8.1 operating systems and later)

Parent NIC object

NIC index

A pointer to the virtual switch object (if NON-NULL).

VM Switch: Attempting to reference a NIC when not allowed. See [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182).

0xA009

+

(Windows 8.1 operating systems and later)

Port being referenced

A pointer to the virtual switch object (if NON-NULL)

Reserved (unused)

VM Switch: Attempt to reference a port when not allowed. See [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182).

0xA00A

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

ContextTypeInfo object

Reserved (unused)

VM Switch: Failure context is already set. See [SetNetBufferListSwitchContext](https://msdn.microsoft.com/library/windows/hardware/hh846223).

0xA00B

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

NDIS_SWITCH_REPORT_FILTERED_NBL_FLAGS_*

A pointer to the virtual switch object (if NON-NULL)

VM Switch: Invalid direction provided for dropped NetBufferList. See [ReportFilteredNetBufferLists](https://msdn.microsoft.com/library/windows/hardware/hh598297).

0xA00C

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

Send Flags value

A pointer to the virtual switch object (if NON-NULL)

VM Switch: NetBufferList chain has multiple source ports when NDIS_SEND_FLAGS_SWITCH_SINGLE_SOURCE flag is set. See [Hyper-V Extensible Switch Send and Receive Flags](https://msdn.microsoft.com/library/windows/hardware/hh598186).

0xA00D

+

(Windows 8.1 operating systems and later)

A pointer to the NetBufferList object

A pointer to the virtual switch context

A pointer to the virtual switch object (if NON-NULL)

VM Switch: One or more NetBufferLists in chain have invalid destination when NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP flag is set. See [Hyper-V Extensible Switch Send and Receive Flags](https://msdn.microsoft.com/library/windows/hardware/hh598186).

0x2000

+

(Windows 7 operating systems and later)

The first argument passed to the [StorPortInitialize](https://msdn.microsoft.com/library/windows/hardware/ff567108) routine. This parameter is a pointer to the driver object that the operating system passed to the miniport driver in the first argument of the miniport driver's [DriverEntry](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine.

The second argument passed to the [StorPortInitialize](https://msdn.microsoft.com/library/windows/hardware/ff567108) routine. This parameter is a pointer to context information that the operating system passed to the miniport driver in the second argument of the miniport driver's [DriverEntry](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine.

Reserved

The Storport miniport driver passed a bad argument (a NULL pointer) to the [StorPortInitialize](https://msdn.microsoft.com/library/windows/hardware/ff567108) routine.

+

0x00020002

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlApcLte](https://msdn.microsoft.com/library/windows/hardware/ff547740). The rule specifies that the driver must call [ObGetObjectSecurity](https://msdn.microsoft.com/library/windows/hardware/ff557738) and [ObReleaseObjectSecurity](https://msdn.microsoft.com/library/windows/hardware/ff558695) only when IRQL <= APC_LEVEL.

0x00020003

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlDispatch](https://msdn.microsoft.com/library/windows/hardware/ff547743). The IrqlDispatch rule specifies that the driver must call certain routines only when IRQL = DISPATCH_LEVEL

0x00020004

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlExAllocatePool](https://msdn.microsoft.com/library/windows/hardware/ff547747). The IrqlExAllocatePool rule specifies that the driver calls [ExAllocatePoolWithTag](https://msdn.microsoft.com/library/windows/hardware/ff544520) and [ExAllocatePoolWithTagPriority](https://msdn.microsoft.com/library/windows/hardware/ff544523) only when at IRQL<=DISPATCH_LEVEL.

0x00020005

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlExApcLte1](https://msdn.microsoft.com/library/windows/hardware/ff547748). The IrqlExApcLte1 rule specifies that the driver calls ExAcquireFastMutex and ExTryToAcquireFastMutex only at IRQL <= APC_LEVEL.

0x00020006

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlExApcLte2](https://msdn.microsoft.com/library/windows/hardware/ff547751). The IrqlExApcLte2 rule specifies that the driver calls certain routines only when IRQL <= APC_LEVEL.

0x00020007

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlExApcLte3](https://msdn.microsoft.com/library/windows/hardware/ff547753). The IrqlExApcLte3 rule specifies that the driver must call certain executive support routines only when IRQL <= APC_LEVEL.

0x00020008

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlExPassive](https://msdn.microsoft.com/library/windows/hardware/ff547756). The IrqlExPassive rule specifies that the driver must call certain executive support routines only when IRQL = PASSIVE_LEVEL.

0x00020009

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoApcLte](https://msdn.microsoft.com/library/windows/hardware/ff547759). The IrqlIoApcLte rule specifies that the driver must call certain I/O manager routines only when IRQL <= APC_LEVEL.

0x0002000A

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoPassive1](https://msdn.microsoft.com/library/windows/hardware/ff547763). The IrqlIoPassive1 rule specifies that the driver must call certain I/O manager routines only when IRQL = PASSIVE_LEVEL.

0x0002000B

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoPassive2](https://msdn.microsoft.com/library/windows/hardware/ff547766). The IrqlIoPassive2 rule specifies that the driver must call certain I/O manager routines only when IRQL = PASSIVE_LEVEL.

0x0002000C

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoPassive3](https://msdn.microsoft.com/library/windows/hardware/ff547780). The IrqlIoPassive3 rule specifies that the driver must call certain I/O manager routines only when IRQL = PASSIVE_LEVEL.

0x0002000D

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoPassive4](https://msdn.microsoft.com/library/windows/hardware/ff547787). The IrqlIoPassive4 rule specifies that the driver must call certain I/O manager routines only when IRQL = PASSIVE_LEVEL.

0x0002000E

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlIoPassive5](https://msdn.microsoft.com/library/windows/hardware/ff547796). The IrqlIoPassive5 rule specifies that the driver must call certain I/O manager routines only when IRQL = PASSIVE_LEVEL.

0x0002000F

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlKeApcLte1](https://msdn.microsoft.com/library/windows/hardware/ff547803). The IrqlKeApcLte1 rule specifies that the driver must call certain kernel routines only when IRQL <= APC_LEVEL.

0x00020010

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlKeApcLte2](https://msdn.microsoft.com/library/windows/hardware/ff547806). The IrqlKeApcLte2 rule specifies that the driver must call certain kernel routines only when IRQL <= APC_LEVEL.

0x00020011

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlKeDispatchLte](https://msdn.microsoft.com/library/windows/hardware/ff547812). The IrqlKeDispatchLte rule specifies that the driver must call certain kernel routines only when IRQL <= DISPATCH_LEVEL.

0x00020015

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlKeReleaseSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff547830). The IrqlKeReleaseSpinLock rule specifies that the driver must call KeReleaseSpinLock only when IRQL = DISPATCH_LEVEL.

0x00020016

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlKeSetEvent](https://msdn.microsoft.com/library/windows/hardware/ff547835). The IrqlKeSetEvent rule specifies that the [KeSetEvent](https://msdn.microsoft.com/library/windows/hardware/ff553253) routine is only called at IRQL <= DISPATCH_LEVEL when Wait is set to FALSE, and at IRQL <= APC_LEVEL when Wait is set to TRUE.

0x00020019

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlMmApcLte](https://msdn.microsoft.com/library/windows/hardware/ff547855). The IrqlMmApcLte rule specifies that the driver must call certain memory manager routines only when IRQL <= APC_LEVEL.

0x0002001A

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlMmDispatch](https://msdn.microsoft.com/library/windows/hardware/hh975186). The IrqlMmDispatch rule specifies that the driver must call [MmFreeContiguousMemory](https://msdn.microsoft.com/library/windows/hardware/ff554503) only when IRQL = DISPATCH_LEVEL.

0x0002001B

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlObPassive](https://msdn.microsoft.com/library/windows/hardware/ff547873). The IrqlObPassive rule specifies that the driver must call [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679) only when IRQL = PASSIVE_LEVEL.

0x0002001C

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlPsPassive](https://msdn.microsoft.com/library/windows/hardware/ff547882). The IrqlPsPassive rule specifies that the driver must call certain process and thread manager routines only when IRQL = PASSIVE_LEVEL.

0x0002001D

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [IrqlReturn](https://msdn.microsoft.com/library/windows/hardware/ff547886).

0x0002001E

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlRtlPassive](https://msdn.microsoft.com/library/windows/hardware/ff547893). The IrqlRtlPassive rule specifies that the driver must call [RtlDeleteRegistryValue](https://msdn.microsoft.com/library/windows/hardware/ff561829) only when IRQL = PASSIVE_LEVEL.

0x0002001F

+

(Windows 8 operating systems and later)

Pointer to the string that describes the violated rule condition.

Optional pointer to the rule state variable(s).

Reserved

The driver violated the DDI compliance rule [IrqlZwPassive](https://msdn.microsoft.com/library/windows/hardware/ff547897). The IrqlZwPassive rule specifies that the driver must call [ZwClose](https://msdn.microsoft.com/library/windows/hardware/ff566417) only when IRQL = PASSIVE_LEVEL.

0x00020022

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Reserved (unused)

Reserved (unused)

The driver violated the DDI compliance rule [IrqlIoDispatch](https://msdn.microsoft.com/library/windows/hardware/jj157234).

0x00040003

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [CriticalRegions](https://msdn.microsoft.com/library/windows/hardware/ff543603).

0x00040006

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [QueuedSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff551494).

0x00040007

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [QueuedSpinLockRelease](https://msdn.microsoft.com/library/windows/hardware/ff551496).

0x00040009

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [SpinLock](https://msdn.microsoft.com/library/windows/hardware/ff551861).

0x0004000B

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [SpinlockRelease](https://msdn.microsoft.com/library/windows/hardware/ff552780).

0x0004000E

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [GuardedRegions](https://msdn.microsoft.com/library/windows/hardware/hh975150).

0x0004100B

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Reserved

Reserved

The driver violated the DDI compliance rule [RequestedPowerIrp](https://msdn.microsoft.com/library/windows/hardware/ff551613).

0x0004100F

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [IoSetCompletionExCompleteIrp](https://msdn.microsoft.com/library/windows/hardware/hh975178).

0x00043006

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Reserved

Reserved

The driver violated the DDI compliance rule [PnpRemove](https://msdn.microsoft.com/library/windows/hardware/dn322052).

0x00091001

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [NdisOidComplete](https://msdn.microsoft.com/library/windows/hardware/dn305115).

0x00091002

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [NdisOidDoubleComplete](https://msdn.microsoft.com/library/windows/hardware/dn305116).

0x0009100E

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the DDI compliance rule [NdisOidDoubleRequest](https://msdn.microsoft.com/library/windows/hardware/dn305117).

0x00092003

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [NdisTimedOidComplete](https://msdn.microsoft.com/library/windows/hardware/dn305120).

0x0009200D

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [NdisTimedDataSend](https://msdn.microsoft.com/library/windows/hardware/dn305119).

0x0009200F

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [NdisTimedDataHang](https://msdn.microsoft.com/library/windows/hardware/dn305118).

0x00093004

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanAssociation](https://msdn.microsoft.com/library/windows/hardware/dn305122).

0x00093005

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanConnectionRoaming](https://msdn.microsoft.com/library/windows/hardware/dn305123).

0x00093006

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanDisassociation](https://msdn.microsoft.com/library/windows/hardware/dn305124).

0x00094007

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanTimedAssociation](https://msdn.microsoft.com/library/windows/hardware/dn305125).

0x00094008

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanTimedConnectionRoaming](https://msdn.microsoft.com/library/windows/hardware/dn305126).

0x00094009

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanTimedConnectRequest](https://msdn.microsoft.com/library/windows/hardware/dn305127).

0x0009400B

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanTimedLinkQuality](https://msdn.microsoft.com/library/windows/hardware/dn305128).

0x0009400C

+

(Windows 8.1 operating systems and later)

Pointer to the string that describes the violated rule condition.

Address of internal rule state (second argument to !ruleinfo).

Address of supplemental states (third argument to !ruleinfo).

The driver violated the NDIS/WIFI verification rule [WlanTimedScan](https://msdn.microsoft.com/library/windows/hardware/dn305129).

+ +  + +Cause +----- + +See the description of each code in the Parameters section for a description of the cause. Further information can be obtained by using the [**!analyze -v**](-analyze.md) extension. + +Resolution +---------- + +This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it. You might also consider removing the driver that caused this problem. + +If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code. + +For full details on Driver Verifier, see the [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) section of the Windows Driver Kit (WDK). + +Remarks +------- + +The \_POOL\_TYPE codes are enumerated in Ntddk.h. In particular, **0** (zero) indicates nonpaged pool and **1** (one) indicates paged pool. + +*(Windows 8 and later versions of Windows)* If [DDI compliance checking](https://msdn.microsoft.com/library/windows/hardware/hh454208) causes a bug check, run [Static Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff552808) on the driver source code and specify the DDI compliance rule (identified by the parameter 1 value) that caused the bug check. Static Driver Verifier can help you locate the cause of the problem in your source code. + +## See also + + +[Handling a Bug Check When Driver Verifier is Enabled](handling-a-bug-check-when-driver-verifier-is-enabled.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc5--driver-corrupted-expool.md b/windows-driver-docs-pr/debugger/bug-check-0xc5--driver-corrupted-expool.md new file mode 100644 index 0000000000..2940fd8b5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc5--driver-corrupted-expool.md @@ -0,0 +1,85 @@ +--- +title: Bug Check 0xC5 DRIVER_CORRUPTED_EXPOOL +description: The DRIVER_CORRUPTED_EXPOOL bug check has a value of 0x000000C5. This indicates that the system attempted to access invalid memory at a process IRQL that was too high. +ms.assetid: e375e7d3-9cb1-474f-ade2-1bc65dd79864 +keywords: ["Bug Check 0xC5 DRIVER_CORRUPTED_EXPOOL", "DRIVER_CORRUPTED_EXPOOL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_CORRUPTED_EXPOOL +api_type: +- NA +--- + +# Bug Check 0xC5: DRIVER\_CORRUPTED\_EXPOOL + + +The DRIVER\_CORRUPTED\_EXPOOL bug check has a value of 0x000000C5. This indicates that the system attempted to access invalid memory at a process IRQL that was too high. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_CORRUPTED\_EXPOOL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL at time of reference

3

0: Read

+

1: Write

4

Address that referenced memory

+ +  + +Cause +----- + +The kernel attempted to access pageable memory (or perhaps completely invalid memory) when the IRQL was too high. The ultimate cause of this problem is almost certainly a driver that has corrupted the system pool. + +In most cases, this bug check results if a driver corrupts a small allocation (less than PAGE\_SIZE). Larger allocations result in [**bug check 0xD0**](bug-check-0xd0--driver-corrupted-mmpool.md) (DRIVER\_CORRUPTED\_MMPOOL). + +Resolution +---------- + +If you have recently installed any new software, check to see if it is properly installed. Check for updated drivers on the manufacturer's website. + +To debug this error, use the special pool option of Driver Verifier. If this fails to reveal the driver that caused the error, use the Global Flags utility to enable the special pool by pool tag. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc6--driver-caught-modifying-freed-pool.md b/windows-driver-docs-pr/debugger/bug-check-0xc6--driver-caught-modifying-freed-pool.md new file mode 100644 index 0000000000..6a1fa4639e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc6--driver-caught-modifying-freed-pool.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xC6 DRIVER_CAUGHT_MODIFYING_FREED_POOL +description: The DRIVER_CAUGHT_MODIFYING_FREED_POOL bug check has a value of 0x000000C6. This indicates that the driver attempted to access a freed memory pool. +ms.assetid: a5df3612-549d-4cf1-b3e1-4e5efad8ce88 +keywords: ["Bug Check 0xC6 DRIVER_CAUGHT_MODIFYING_FREED_POOL", "DRIVER_CAUGHT_MODIFYING_FREED_POOL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_CAUGHT_MODIFYING_FREED_POOL +api_type: +- NA +--- + +# Bug Check 0xC6: DRIVER\_CAUGHT\_MODIFYING\_FREED\_POOL + + +The DRIVER\_CAUGHT\_MODIFYING\_FREED\_POOL bug check has a value of 0x000000C6. This indicates that the driver attempted to access a freed memory pool. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_CAUGHT\_MODIFYING\_FREED\_POOL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

0: Read

+

1: Write

3

0: Kernel mode

+

1: User mode

4

Reserved

+ +  + +Remarks +------- + +The faulty component will be displayed in the current kernel stack. This driver should be either replaced or debugged. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc7--timer-or-dpc-invalid.md b/windows-driver-docs-pr/debugger/bug-check-0xc7--timer-or-dpc-invalid.md new file mode 100644 index 0000000000..217fc26bdc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc7--timer-or-dpc-invalid.md @@ -0,0 +1,116 @@ +--- +title: Bug Check 0xC7 TIMER_OR_DPC_INVALID +description: The TIMER_OR_DPC_INVALID bug check has a value of 0x000000C7. This is issued if a kernel timer or delayed procedure call (DPC) is found somewhere in memory where it is not permitted. +ms.assetid: 25a85b38-c299-4bf8-a7ed-f516adb5fcb1 +keywords: ["Bug Check 0xC7 TIMER_OR_DPC_INVALID", "TIMER_OR_DPC_INVALID"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TIMER_OR_DPC_INVALID +api_type: +- NA +--- + +# Bug Check 0xC7: TIMER\_OR\_DPC\_INVALID + + +The TIMER\_OR\_DPC\_INVALID bug check has a value of 0x000000C7. This is issued if a kernel timer or delayed procedure call (DPC) is found somewhere in memory where it is not permitted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TIMER\_OR\_DPC\_INVALID Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x0

Address of the timer object

Start of memory range being checked

End of memory range being checked

The timer object was found in a block of memory where a timer object is not permitted. .

0x1

Address of the DPC object

Start of memory range being checked

End of memory range being checked

The DPC object was found in a block of memory where a DPC object is not permitted.

0x2

Address of the DPC routine

Start of memory range being checked

End of memory range being checked

The DPC routine was found in a block of memory where a DPC object is not permitted.

0x3

Address of the DPC object

Processor number

Number of processors in the system

The processor number for the DPC object is not correct.

0x4

Address of the DPC routine

The thread's APC disable count before the kernel calls the DPC routine

The thread's APC disable count after the DPC routine is called

The thread's APC disable count was changed during DPC routine execution.

+

The APC disable count is decremented each time a driver calls KeEnterCriticalRegion, FsRtlEnterFileSystem, or acquires a mutex.

+

The APC disable count is incremented each time a driver calls KeLeaveCriticalRegion, KeReleaseMutex, or FsRtlExitFileSystem.

0x5

Address of the DPC routine

The thread's APC disable count before the kernel calls the DPC routine

The thread's APC disable count after the DPC routine is called

The thread's APC disable count was changed during the execution of timer DPC routine.

+

The APC disable count is decremented each time a driver calls KeEnterCriticalRegion, FsRtlEnterFileSystem, or acquires a mutex.

+

The APC disable count is incremented each time a driver calls KeLeaveCriticalRegion, KeReleaseMutex, or FsRtlExitFileSystem.

+ +  + +Cause +----- + +This condition is usually caused by a driver failing to cancel a timer or DPC before freeing the memory where it resides. + +Resolution +---------- + +If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code. + +If you are a system administrator, you should unload the driver if the problem persists. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc8--irql-unexpected-value.md b/windows-driver-docs-pr/debugger/bug-check-0xc8--irql-unexpected-value.md new file mode 100644 index 0000000000..96ded0c5bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc8--irql-unexpected-value.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0xC8 IRQL_UNEXPECTED_VALUE +description: The IRQL_UNEXPECTED_VALUE bug check has a value of 0x000000C8. This indicates that the processor's IRQL is not what it should be at this time. +ms.assetid: eff166ab-e245-48ea-ab9e-9bb722814acf +keywords: ["Bug Check 0xC8 IRQL_UNEXPECTED_VALUE", "IRQL_UNEXPECTED_VALUE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IRQL_UNEXPECTED_VALUE +api_type: +- NA +--- + +# Bug Check 0xC8: IRQL\_UNEXPECTED\_VALUE + + +The IRQL\_UNEXPECTED\_VALUE bug check has a value of 0x000000C8. This indicates that the processor's IRQL is not what it should be at this time. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IRQL\_UNEXPECTED\_VALUE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The value of the following bit computation:

+

(Current IRQL << 16) | (Expected IRQL << 8) | UniqueValue

2

Zero, or APC->KernelRoutine

3

Zero, or APC

4

Zero, or APC->NormalRoutine

+ +  + +You can determine "UniqueValue" by computing (Parameter 1 AND 0xFF). If "UniqueValue" is either zero or one, Parameter 2, Parameter 3, and Parameter 4 will equal the indicated APC pointers. Otherwise, these parameters will equal zero. + +Cause +----- + +This error is usually caused by a device driver or another lower-level program that changed the IRQL for some period and did not restore the original IRQL at the end of that period. For example, the routine may have acquired a spin lock and failed to release it. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xc9--driver-verifier-iomanager-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xc9--driver-verifier-iomanager-violation.md new file mode 100644 index 0000000000..85124f5379 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xc9--driver-verifier-iomanager-violation.md @@ -0,0 +1,710 @@ +--- +title: Bug Check 0xC9 DRIVER_VERIFIER_IOMANAGER_VIOLATION +description: The DRIVER_VERIFIER_IOMANAGER_VIOLATION bug check has a value of 0x000000C9. This is the bug check code for all Driver Verifier I/O Verification violations. +ms.assetid: dcafb0df-cbc1-44f4-8ec4-976df0842f0c +keywords: ["Bug Check 0xC9 DRIVER_VERIFIER_IOMANAGER_VIOLATION", "DRIVER_VERIFIER_IOMANAGER_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_VERIFIER_IOMANAGER_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xC9: DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION + + +The DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION bug check has a value of 0x000000C9. This is the bug check code for all Driver Verifier **I/O Verification** violations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION Parameters + + +When Driver Verifier is active and **I/O Verification** is selected, various I/O violations will cause this bug check to be issued. Parameter 1 identifies the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x01

Address of IRP being freed

0

0

The driver attempted to free an object whose type is not IO_TYPE_IRP.

0x02

Address of IRP being freed

0

0

The driver attempted to free an IRP that is still associated with a thread.

0x03

Address of IRP being sent

0

0

The driver passed IoCallDriver an IRP Type not equal to IRP_TYPE.

0x04

Address of device object

0

0

The driver passed IoCallDriver an invalid device object.

0x05

Address of device object associated with offending driver

IRQL before IoCallDriver

IRQL after IoCallDriver

The IRQL changed during a call to the driver dispatch routine.

0x06

IRP status

Address of IRP being completed

0

The driver called IoCompleteRequest with a status marked as pending (or equal to -1).

0x07

Address of cancel routine

Address of IRP being completed

0

The driver called IoCompleteRequest while its cancel routine was still set.

0x08

Address of device object

IRP major function code

Exception status code

The driver passed IoBuildAsynchronousFsdRequest an invalid buffer.

0x09

Address of device object

I/O control code

Exception status code

The driver passed IoBuildDeviceIoControlRequest an invalid buffer.

0x10

Current IRQL

Reserved

Reserved

IoCallDriver was called above DISPATCH_LEVEL.

0x11

Driver fast I/O dispatch routine address

IRQL before calling driver dispatch routine

Current IRQL

IoCallDriver was called above DISPATCH_LEVEL.

0x12

Driver dispatch routine address

IRQL before calling driver dispatch routine

Current IRQL

IoCallDriver was called above DISPATCH_LEVEL.

0x0A

Address of device object

0

0

The driver passed IoInitializeTimer a device object with an already-initialized timer.

0x0C

Address of I/O status block

0

0

The driver passed an I/O status block to an IRP, but this block is allocated on a stack which has already unwound past that point.

0x0D

Address of user event object

0

0

The driver passed a user event to an IRP, but this event is allocated on a stack which has already unwound past that point.

0x0E

Current IRQL

Address of IRP

0

The driver called IoCompleteRequest with IRQL > DISPATCH_LEVEL.

0x0F

Address of the device object to which the IRP is being sent

Pointer to the IRP

Pointer to file object

The driver sent a create request with a file object that has been closed, or that had its open canceled.

+ +  + +In addition to the errors mentioned in the previous table, there are a number of **I/O Verification** errors that will cause Driver Verifier to halt the system, but which are not actually bug checks. + +These errors cause messages to be displayed on the blue screen, in a crash dump file, and in a kernel debugger. These messages will appear differently in each of these locations. When these errors occur, the hexadecimal bug check code 0xC9 and the bug check string DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION do not appear on the blue screen or in the debugger, although they will appear in a crash dump file. + +On the blue screen, the following data will be displayed: + +- The message **IO SYSTEM VERIFICATION ERROR**. + +- The message **WDM DRIVER ERROR** *XXX*, where *XXX* is a hexadecimal code representing the specific error. (See the table below for a list of the I/O error codes and their meanings.) + +- The name of the driver which caused the error. + +- The address in the driver's code where the error was detected (Parameter 2). + +- A pointer to the IRP (Parameter 3). + +- A pointer to the device object (Parameter 4). + +If a kernel-mode crash dump has been enabled, the following information will appear in the crash dump file: + +- The message **BugCheck 0xC9 (DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION)**. + +- The hexadecimal I/O error code. (See the table below for a list of the I/O error codes and their meanings.) + +- The address in the driver's code where the error was detected. + +- A pointer to the IRP. + +- A pointer to the device object. + +If a kernel debugger is attached to the system which has caused this violation, the following information will be sent to the debugger: + +- The message **WDM DRIVER ERROR**, along with an assessment of the severity of the error. + +- The name of the driver which caused the error. + +- A descriptive string which explains the cause of this error. Often additional information is passed along, such as a pointer to the IRP. (See the table below for a list of these descriptive strings and what additional information is specified.) + +- A query for further action. Possible responses are **b** (break), **i** (ignore), **z** (zap), **r** (remove), or **d** (disable). Instructing the operating system to continue allows you to see what would happen "down the line" if this error had not occurred. Of course, this often will lead to additional bug checks. The "zap" option will actually remove the breakpoint that caused this error to be discovered. + +**Note**   No other bug checks can be ignored in this manner. Only this kind of **I/O Verification** errors can be ignored, and even these errors can only be ignored if a kernel debugger is attached. + +  + +The following table lists those **I/O Verification** errors that can appear. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I/O Error CodeSeverityCause of Error

0x200

Unknown

This code covers all unknown I/O Verification errors.

0x201

Fatal error

A device is deleting itself while there is another device beneath it in the driver stack. This may be because the caller has forgotten to call IoDetachDevice first, or the lower driver may have incorrectly deleted itself.

0x202

Fatal error

A driver has attempted to detach from a device object that is not attached to anything. This may occur if detach was called twice on the same device object. (Device object specified.)

0x203

Fatal error

A driver has called IoCallDriver without setting the cancel routine in the IRP to NULL. (IRP specified.)

0x204

Fatal error

The caller has passed in NULL as a device object. This is fatal. (IRP specified.)

0x205

Fatal error

The caller is forwarding an IRP that is currently queued beneath it. The code handling IRPs returning STATUS_PENDING in this driver appears to be broken. (IRP specified.)

0x206

Fatal error

The caller has incorrectly forwarded an IRP (control field not zeroed). The driver should use IoCopyCurrentIrpStackLocationToNext or IoSkipCurrentIrpStackLocation. (IRP specified.)

0x207

Fatal error

The caller has manually copied the stack and has inadvertently copied the upper layer's completion routine. The driver should use IoCopyCurrentIrpStackLocationToNext. (IRP specified.)

0x208

Fatal error

This IRP is about to run out of stack locations. Someone may have forwarded this IRP from another stack. (IRP specified.)

0x209

Fatal error

The caller is completing an IRP that is currently queued beneath it. The code handling IRPs returning STATUS_PENDING in this driver appears to be broken. (IRP specified.)

0x20A

Fatal error

The caller of IoFreeIrp is freeing an IRP that is still in use. (Original IRP and IRP in use specified.)

0x20B

Fatal error

The caller of IoFreeIrp is freeing an IRP that is still in use. (IRP specified.)

0x20C

Fatal error

The caller of IoFreeIrp is freeing an IRP that is still queued against a thread. (IRP specified.)

0x20D

Fatal error

The caller of IoInitializeIrp has passed an IRP that was allocated with IoAllocateIrp. This is illegal and unnecessary, and has caused a quota leak. Check the documentation for IoReuseIrp if this IRP is being recycled.

0x20E

Non-fatal error

A PNP IRP has an invalid status. (Any PNP IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)

0x20F

Non-fatal error

A Power IRP has an invalid status. (Any Power IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)

0x210

Non-fatal error

A WMI IRP has an invalid status. (Any WMI IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)

0x211

Non-fatal error

The caller has forwarded an IRP while skipping a device object in the stack. The caller is probably sending IRPs to the PDO instead of to the device returned by IoAttachDeviceToDeviceStack. (IRP specified.)

0x212

Non-fatal error

The caller has trashed or has not properly copied the IRP's stack. (IRP specified.)

0x213

Non-fatal error

The caller has changed the status field of an IRP it does not understand. (IRP specified.)

0x214

Non-fatal error

The caller has changed the information field of an IRP it does not understand. (IRP specified.)

0x215

Non-fatal error

A non-successful non-STATUS_NOT_SUPPORTED IRP status for IRP_MJ_PNP is being passed down stack. (IRP specified.) Failed PNP IRPs must be completed.

0x216

Non-fatal error

The previously-set IRP_MJ_PNP status has been converted to STATUS_NOT_SUPPORTED. (IRP specified.) This failure status is reserved for use by the operating system. Drivers cannot fail a PnP IRP with this value.

0x217

Non-fatal error

The driver has not handled a required IRP. The driver must update the status of the IRP to indicate whether or not it has been handled. (IRP specified.)

0x218

Non-fatal error

The driver has responded to an IRP that is reserved for other device objects elsewhere in the stack. (IRP specified.)

0x219

Non-fatal error

A non-successful non-STATUS_NOT_SUPPORTED IRP status for IRP_MJ_POWER is being passed down stack. (IRP specified.) Failed POWER IRPs must be completed.

0x21A

Non-fatal error

The previously-set IRP_MJ_POWER status has been converted to STATUS_NOT_SUPPORTED. (IRP specified.)

0x21B

Non-fatal error

A driver has returned a suspicious status. This is probably due to an uninitialized variable bug in the driver. (IRP specified.)

0x21C

Warning

The caller has copied the IRP stack but not set a completion routine. This is inefficient -- use IoSkipCurrentIrpStackLocation instead. (IRP specified.)

0x21D

Fatal error

An IRP dispatch handler has not properly detached from the stack below it upon receiving a remove IRP. (Device object, dispatch routine, and IRP specified.)

0x21E

Fatal error

An IRP dispatch handler has not properly deleted its device object upon receiving a remove IRP. (Device object, dispatch routine, and IRP specified.)

0x21F

Non-fatal error

A driver has not filled out a dispatch routine for a required IRP major function. (IRP specified.)

0x220

Non-fatal error

IRP_MJ_SYSTEM_CONTROL has been completed by someone other than the ProviderId. This IRP should either have been completed earlier or should have been passed down. (IRP specified, along with the device object where it was targeted.)

0x221

Fatal error

An IRP dispatch handler for a PDO has deleted its device object, but the hardware has not been reported as missing in a bus relations query. (Device object, dispatch routine, and IRP specified.)

0x222

Fatal error

A Bus Filter's IRP dispatch handler has detached upon receiving a remove IRP when the PDO is still alive. Bus Filters must clean up in FastIoDetach callbacks. (Device object, dispatch routine, and IRP specified.)

0x223

Fatal error

An IRP dispatch handler for a bus filter has deleted its device object, but the PDO is still present. Bus filters must clean up in FastIoDetach callbacks. (Device object, dispatch routine, and IRP specified.)

0x224

Fatal error

An IRP dispatch handler has returned a status that is inconsistent with the IRP's IoStatus.Status field. (Dispatch handler routine, IRP, IRP's IoStatus.Status, and returned Status specified.)

0x225

Non-fatal error

An IRP dispatch handler has returned a status that is illegal (0xFFFFFFFF). This is probably due to an uninitialized stack variable. To debug this error, use the [ln (List Nearest Symbols)](ln--list-nearest-symbols-.md) command with the specified address.

0x226

Fatal error

An IRP dispatch handler has returned without passing down or completing this IRP, or someone forgot to return STATUS_PENDING. (IRP specified.)

0x227

Fatal error

An IRP completion routine is in pageable code. (This is never permitted.) (Routine and IRP specified.)

0x228

Non-fatal error

A driver's completion routine has not marked the IRP pending if the PendingReturned field was set in the IRP passed to it. This may cause Windows to hang, especially if an error is returned by the stack. (Routine and IRP specified.)

0x229

Fatal error

A cancel routine has been set for an IRP that is currently being processed by drivers lower in the stack, possibly stomping their cancel routine. (Routine and IRP specified.)

0x22A

Non-fatal error

The physical device object (PDO) has not responded to a required IRP. (IRP specified.)

0x22B

Non-fatal error

The physical device object (PDO) has forgotten to fill out the device relation list with the PDO for the TargetDeviceRelation query. (IRP specified.)

0x22C

Fatal error

The code implementing the TargetDeviceRelation query has not called ObReferenceObject on the PDO. (IRP specified.)

0x22D

Non-fatal error

The caller has completed a IRP_MJ_PNP it didn't understand instead of passing it down. (IRP specified.)

0x22E

Non-fatal error

The caller has completed a successful IRP_MJ_PNP instead of passing it down. (IRP specified.)

0x22F

Non-fatal error

The caller has completed an untouched IRP_MJ_PNP (instead of passing the IRP down), or non-PDO has failed the IRP using illegal value of STATUS_NOT_SUPPORTED. (IRP specified.)

0x230

Non-fatal error

The caller has completed an IRP_MJ_POWER it didn't understand instead of passing it down. (IRP specified.)

0x231

Fatal error

The caller has completed a successful IRP_MJ_POWER instead of passing it down. (IRP specified.)

0x232

Non-fatal error

The caller has completed an untouched IRP_MJ_POWER (instead of passing the IRP down), or non-PDO has failed the IRP using illegal value of STATUS_NOT_SUPPORTED. (IRP specified.)

0x233

Non-fatal error

The version field of the query capabilities structure in a query capabilities IRP was not properly initialized. (IRP specified.)

0x234

Non-fatal error

The size field of the query capabilities structure in a query capabilities IRP was not properly initialized. (IRP specified.)

0x235

Non-fatal error

The address field of the query capabilities structure in a query capabilities IRP was not properly initialized to -1. (IRP specified.)

0x236

Non-fatal error

The UI Number field of the query capabilities structure in a query capabilities IRP was not properly initialized to -1. (IRP specified.)

0x237

Fatal error

A driver has sent an IRP that is restricted for system use only. (IRP specified.)

0x238

Warning

The caller of IoInitializeIrp has passed an IRP that was allocated with IoAllocateIrp. This is illegal, unnecessary, and negatively impacts performance in normal use. If this IRP is being recycled, see IoReuseIrp in the Windows Driver Kit.

0x239

Warning

The caller of IoCompleteRequest is completing an IRP that has never been forwarded via a call to IoCallDriver or PoCallDriver. This may be a bug. (IRP specified.)

0x23A

Fatal error

A driver has forwarded an IRP at an IRQL that is illegal for this major code. (IRP specified.)

0x23B

Non-fatal error

The caller has changed the status field of an IRP it does not understand. (IRP specified.)

+ +  + +The following table lists additional **I/O Verification** errors that can appear in Windows XP and later. Some of these errors will only be revealed if **Enhanced I/O Verification** is activated. In Windows Vista and later, the **Enhanced I/O Verification** settings are included as part of **I/O Verification**. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I/O Error CodeSeverityCause of Error

0x23C

Fatal error

A driver has completed an IRP without setting the cancel routine in the IRP to NULL. (IRP specified.)

0x23D

Non-fatal error

A driver has returned STATUS_PENDING but did not mark the IRP pending via a call to IoMarkIrpPending. (IRP specified.)

0x23E

Non-fatal error

A driver has marked an IRP pending but didn't return STATUS_PENDING. (IRP specified.)

0x23F

Fatal error

A driver has not inherited the DO_POWER_PAGABLE bit from the stack it has attached to. (Device object specified.)

0x240

Fatal error

A driver is attempting to delete a device object that has already been deleted via a prior call to IoDeleteDevice.

0x241

Fatal error

A driver has detached its device object during a surprise remove IRP. (IRP and device object specified.)

0x242

Fatal error

A driver has deleted its device object during a surprise remove IRP. (IRP and device object specified.)

0x243

Fatal error

A driver has failed to clear the DO_DEVICE_INITIALIZING flag at the end of AddDevice. (Device object specified.)

0x244

Fatal error

A driver has not copied either the DO_BUFFERED_IO or the DO_DIRECT_IO flag from the device object it is attaching to. (Device object specified.)

0x245

Fatal error

A driver has set both the DO_BUFFERED_IO and the DO_DIRECT_IO flags. These flags are mutually exclusive. (Device object specified.)

0x246

Fatal error

A driver has failed to copy the DeviceType field from the device object it is attaching to. (Device object specified.)

0x247

Fatal error

A driver has failed an IRP that cannot legally be failed. (IRP specified.)

0x248

Fatal error

A driver has added a device object that is not a PDO to a device relations query. (IRP and device object specified.)

0x249

Non-fatal error

A driver has enumerated two child PDOs that returned identical Device IDs. (Both device objects specified.)

0x24A

Fatal error

A driver has mistakenly called a file I/O function with IRQL not equal to PASSIVE_LEVEL.

0x24B

Fatal error

A driver has completed an IRP_MN_QUERY_DEVICE_RELATIONS request of type TargetDeviceRelation as successful, but did not properly fill out the request or forward the IRP to the underlying hardware stack. (Device object specified.)

0x24C

Non-fatal error

A driver has returned STATUS_PENDING but did not mark the IRP pending by a call to IoMarkIrpPending. (IRP specified.)

0x24D

Fatal error

A driver has passed an invalid device object to a function that requires a PDO. (Device object specified.)

0x300

Non-fatal error

A driver has returned a suspicious status. This is probably due to an uninitialized variable bug in the driver.

0x301

Non-fatal error

A driver has forwarded an IRP at IRQL > DISPATCH_LEVEL. (IRQL value specified)

0x302

Non-fatal error

A driver has forwarded an IRP at IRQL >= APC_LEVEL.

+

The I/O Manager will need to queue an APC to complete this request. The APC will not be able to run because the caller is already at APC level, so the caller is likely to deadlock. (IRQL value specified)

0x306

Non-fatal error

The driver is completing an IRP_MJ_PNP (major) and IRP_MN_REMOVE_DEVICE (minor) request with a failure status code.

0x307

Non-fatal error

The driver issued an I/O request with an event that was already signaled and received a STATUS_PENDING response. This can result in unwinding before the I/O is complete.

0x310

Non-fatal error

The driver is reinitializing an IRP that is still in use.

0x311

Non-fatal error

The driver is reinitializing an IRP that was created with IoMakeAssociatedIrp, IoBuildAsynchronousFsdRequest, IoBuildSynchronousFsdRequest, IoBuildDeviceIoControlRequest.

0x312

Non-fatal error

The caller provided the IRP Status Information field with a value that is greater than the output section of the system buffer.

+ +  + +Cause +----- + +See the description of each code in the Parameters section for a description of the cause. + +Resolution +---------- + +This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it. You might consider removing the driver which caused this problem as well. + +If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code. + +For full details on Driver Verifier, see the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xca--pnp-detected-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0xca--pnp-detected-fatal-error.md new file mode 100644 index 0000000000..f1b363ebc2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xca--pnp-detected-fatal-error.md @@ -0,0 +1,127 @@ +--- +title: Bug Check 0xCA PNP_DETECTED_FATAL_ERROR +description: The PNP_DETECTED_FATAL_ERROR bug check has a value of 0x000000CA. This indicates that the Plug and Play Manager encountered a severe error. +ms.assetid: 2092c4a7-e068-461f-b28e-8063faf5a031 +keywords: ["Bug Check 0xCA PNP_DETECTED_FATAL_ERROR", "PNP_DETECTED_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PNP_DETECTED_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0xCA: PNP\_DETECTED\_FATAL\_ERROR + + +The PNP\_DETECTED\_FATAL\_ERROR bug check has a value of 0x000000CA. This indicates that the Plug and Play Manager encountered a severe error, probably as a result of a problematic Plug and Play driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PNP\_DETECTED\_FATAL\_ERROR Parameters + + +Parameter 1 identifies the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x1

Address of newly-reported PDO

Address of older PDO which has been duplicated

Reserved

Duplicate PDO: A specific instance of a driver has enumerated multiple PDOs with identical device ID and unique IDs.

0x2

Address of purported PDO

Address of driver object

Reserved

Invalid PDO: An API which requires a PDO has been called with random memory, or with an FDO, or with a PDO which hasn't been initialized.

+

(An uninitialized PDO is one that has not been returned to Plug and Play by QueryDeviceRelation or QueryBusRelations.)

0x3

Address of PDO whose IDs were queried

Address of ID buffer

1: DeviceID

+

2: UniqueID

+

3: HardwareIDs

+

4: CompatibleIDs

Invalid ID: An enumerator has returned an ID which contains illegal characters or isn't properly terminated. (IDs must contain only characters in the ranges 0x20 - 0x2B and 0x2D - 0x7F.)

0x4

Address of PDO with DOE_DELETE_PENDING set

Reserved

Reserved

Invalid enumeration of deleted PDO: An enumerator has returned a PDO which it had previously deleted using IoDeleteDevice.

0x5

Address of PDO

Reserved

Reserved

PDO freed while linked in devnode tree: The object manager reference count on a PDO dropped to zero while the devnode was still linked in the tree. (This usually indicates that the driver is not adding a reference when returning the PDO in a query IRP.)

0x8

Address of PDO whose stack returned the invalid bus relation

Total number of PDOs returned as bus relations

The index (zero-based) at which the first NULL PDO was found

NULL pointer returned as a bus relation: One or more of the devices present on the bus is a NULL PDO.

0x9

Connection type that was passed

Reserved

Reserved

Invalid connection type passed to IoDisconnectInterruptEx: A driver has passed an invalid connection type to IoDisconnectInterruptEx. The connection type passed to this routine must match the one returned by a corresponding successful call to IoConnectInterruptEx.

0xA

Driver object

IRQL after returning from driver callback

Combined APC disable count after returning from driver callback

Incorrect notify callback behavior: A driver failed to preserve IRQL or combined APC disable count across a Plug 'n' Play notification.

0xB

Related PDO

Removal relations

Reserved

Deleted PDO reported as relation: One of the removal relations for the device being removed has already been deleted.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xcb--driver-left-locked-pages-in-process.md b/windows-driver-docs-pr/debugger/bug-check-0xcb--driver-left-locked-pages-in-process.md new file mode 100644 index 0000000000..f343a6b11c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xcb--driver-left-locked-pages-in-process.md @@ -0,0 +1,116 @@ +--- +title: Bug Check 0xCB DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS +description: The DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS bug check has a value of 0x000000CB. This indicates that a driver or the I/O manager failed to release locked pages after an I/O operation. +ms.assetid: e97d114e-c6f1-44f1-a2ad-bfa8d03dc3c7 +keywords: ["Bug Check 0xCB DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS", "DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS +api_type: +- NA +--- + +# Bug Check 0xCB: DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS + + +The DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS bug check has a value of 0x000000CB. This indicates that a driver or the I/O manager failed to release locked pages after an I/O operation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS Parameters + + +The four parameters listed in the message can have two possible meanings. + +If a driver locked these pages, the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Calling address in the driver that locked the pages

2

Caller of the calling address in driver that locked the pages

3

Address of the MDL containing the locked pages

4

Number of locked pages

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +If the I/O manager locked these pages, the parameters have the following meaning. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of the dispatch routine of the top driver on the stack to which the IRP was sent

2

Address of the device object of the top driver on the stack to which the IRP was sent

3

Address of the MDL containing the locked pages

4

Number of locked pages

+ +  + +Remarks +------- + +This bug check is issued only if the registry value **\\\\HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management\\TrackLockedPages** is equal to DWORD 1. If this value is not set, the system will issue the less-informative [**bug check 0x76**](bug-check-0x76--process-has-locked-pages.md) (PROCESS\_HAS\_LOCKED\_PAGES). + +Starting with Windows Vista, this bug check can also be issued by Driver Verifier when the Pool Tracking option is enabled. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xcc--page-fault-in-freed-special-pool.md b/windows-driver-docs-pr/debugger/bug-check-0xcc--page-fault-in-freed-special-pool.md new file mode 100644 index 0000000000..b42f6acecb --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xcc--page-fault-in-freed-special-pool.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xCC PAGE_FAULT_IN_FREED_SPECIAL_POOL +description: The PAGE_FAULT_IN_FREED_SPECIAL_POOL bug check has a value of 0x000000CC. This indicates that the system has referenced memory which was earlier freed. +ms.assetid: 77823c38-76eb-49ca-aaf4-3cf5994a0525 +keywords: ["Bug Check 0xCC PAGE_FAULT_IN_FREED_SPECIAL_POOL", "PAGE_FAULT_IN_FREED_SPECIAL_POOL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PAGE_FAULT_IN_FREED_SPECIAL_POOL +api_type: +- NA +--- + +# Bug Check 0xCC: PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL + + +The PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL bug check has a value of 0x000000CC. This indicates that the system has referenced memory which was earlier freed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +The Driver Verifier Special Pool option has caught the system accessing memory which was earlier freed. This usually indicates a system-driver synchronization problem. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +Remarks +------- + +This cannot be protected by a **try - except** handler -- it can only be protected by a probe. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xcd--page-fault-beyond-end-of-allocation.md b/windows-driver-docs-pr/debugger/bug-check-0xcd--page-fault-beyond-end-of-allocation.md new file mode 100644 index 0000000000..6eae1efd39 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xcd--page-fault-beyond-end-of-allocation.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xCD PAGE_FAULT_BEYOND_END_OF_ALLOCATION +description: The PAGE_FAULT_BEYOND_END_OF_ALLOCATION bug check has a value of 0x000000CD. This indicates that the system accessed memory beyond the end of some driver's pool allocation. +ms.assetid: ce506f92-94a9-4ef5-974b-32013410468a +keywords: ["Bug Check 0xCD PAGE_FAULT_BEYOND_END_OF_ALLOCATION", "PAGE_FAULT_BEYOND_END_OF_ALLOCATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PAGE_FAULT_BEYOND_END_OF_ALLOCATION +api_type: +- NA +--- + +# Bug Check 0xCD: PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION + + +The PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION bug check has a value of 0x000000CD. This indicates that the system accessed memory beyond the end of some driver's pool allocation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +The driver allocated *n* bytes of memory from the special pool. Subsequently, the system referenced more than *n* bytes from this pool. This usually indicates a system-driver synchronization problem. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +Remarks +------- + +This cannot be protected by a **try - except** handler -- it can only be protected by a probe. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xce--driver-unloaded-without-cancelling-pending-operations.md b/windows-driver-docs-pr/debugger/bug-check-0xce--driver-unloaded-without-cancelling-pending-operations.md new file mode 100644 index 0000000000..9ac450f1fc --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xce--driver-unloaded-without-cancelling-pending-operations.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0xCE DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS +description: The DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS bug check has a value of 0x000000CE. This indicates that a driver failed to cancel pending operations before unloading. +ms.assetid: ade0d20d-25f0-45ad-a099-31f3521b91cd +keywords: ["Bug Check 0xCE DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS", "DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS +api_type: +- NA +--- + +# Bug Check 0xCE: DRIVER\_UNLOADED\_WITHOUT\_CANCELLING\_PENDING\_OPERATIONS + + +The DRIVER\_UNLOADED\_WITHOUT\_CANCELLING\_PENDING\_OPERATIONS bug check has a value of 0x000000CE. This indicates that a driver failed to cancel pending operations before unloading. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_UNLOADED\_WITHOUT\_CANCELLING\_PENDING\_OPERATIONS Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +This driver failed to cancel lookaside lists, DPCs, worker threads, or other such items before unload. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xcf--terminal-server-driver-made-incorrect-memory-reference.md b/windows-driver-docs-pr/debugger/bug-check-0xcf--terminal-server-driver-made-incorrect-memory-reference.md new file mode 100644 index 0000000000..bd9c484bd1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xcf--terminal-server-driver-made-incorrect-memory-reference.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0xCF TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE +description: The TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE bug check has a value of 0x000000CF. This indicates that a driver has been incorrectly ported to the terminal server. +ms.assetid: 1c3351d8-95df-4a12-a9c5-36aa6a5cf236 +keywords: ["Bug Check 0xCF TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE", "TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE +api_type: +- NA +--- + +# Bug Check 0xCF: TERMINAL\_SERVER\_DRIVER\_MADE\_INCORRECT\_MEMORY\_REFERENCE + + +The TERMINAL\_SERVER\_DRIVER\_MADE\_INCORRECT\_MEMORY\_REFERENCE bug check has a value of 0x000000CF. This indicates that a driver has been incorrectly ported to the terminal server. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## TERMINAL\_SERVER\_DRIVER\_MADE\_INCORRECT\_MEMORY\_REFERENCE Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +The driver is referencing session space addresses from the system process context. This probably results from the driver queuing an item to a system worker thread. + +This driver needs to comply with Terminal Server's memory management rules. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd--mutex-level-number-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xd--mutex-level-number-violation.md new file mode 100644 index 0000000000..35343ade44 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd--mutex-level-number-violation.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0xD MUTEX_LEVEL_NUMBER_VIOLATION +description: The MUTEX_LEVEL_NUMBER_VIOLATION bug check has a value of 0x0000000D.This bug check appears very infrequently. +ms.assetid: beffa1ef-7499-44b9-90fb-0c8af7f0f2be +keywords: ["Bug Check 0xD MUTEX_LEVEL_NUMBER_VIOLATION", "MUTEX_LEVEL_NUMBER_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MUTEX_LEVEL_NUMBER_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xD: MUTEX\_LEVEL\_NUMBER\_VIOLATION + + +The MUTEX\_LEVEL\_NUMBER\_VIOLATION bug check has a value of 0x0000000D. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd0--driver-corrupted-mmpool.md b/windows-driver-docs-pr/debugger/bug-check-0xd0--driver-corrupted-mmpool.md new file mode 100644 index 0000000000..0076dee486 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd0--driver-corrupted-mmpool.md @@ -0,0 +1,87 @@ +--- +title: Bug Check 0xD0 DRIVER_CORRUPTED_MMPOOL +description: The DRIVER_CORRUPTED_MMPOOL bug check has a value of 0x000000D0. This indicates that the system attempted to access invalid memory at a process IRQL that was too high. +ms.assetid: fad53a11-d4db-4f2c-b03e-19c5db47975b +keywords: ["Bug Check 0xD0 DRIVER_CORRUPTED_MMPOOL", "DRIVER_CORRUPTED_MMPOOL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_CORRUPTED_MMPOOL +api_type: +- NA +--- + +# Bug Check 0xD0: DRIVER\_CORRUPTED\_MMPOOL + + +The DRIVER\_CORRUPTED\_MMPOOL bug check has a value of 0x000000D0. This indicates that the system attempted to access invalid memory at a process IRQL that was too high. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_CORRUPTED\_MMPOOL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL at time of reference

3

0: Read

+

1: Write

4

Address that referenced memory

+ +  + +Cause +----- + +The kernel attempted to access pageable memory (or perhaps completely invalid memory) when the IRQL was too high. The ultimate cause of this problem is almost certainly a driver that has corrupted the system pool. + +In most cases, this bug check results if a driver corrupts a large allocation (PAGE\_SIZE or larger). Smaller allocations result in [**bug check 0xC5**](bug-check-0xc5--driver-corrupted-expool.md) (DRIVER\_CORRUPTED\_EXPOOL). + +Resolution +---------- + +If you have recently installed any new software, check to see if it is properly installed. Check for updated drivers on the manufacturer's website. + +To debug this error, use the special pool option of Driver Verifier. If this fails to reveal the driver that caused the error, use the Global Flags utility to enable the special pool by pool tag. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +An alternate method is to open the **\\\\HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management** registry key. In this key, create or edit the **ProtectNonPagedPool** value, and set it equal to DWORD 1. Then reboot. Then the system will unmap all freed nonpaged pool. This will prevent drivers from corrupting the pool. (This does not protect the pool from DMA hardware, however.) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd1--driver-irql-not-less-or-equal.md b/windows-driver-docs-pr/debugger/bug-check-0xd1--driver-irql-not-less-or-equal.md new file mode 100644 index 0000000000..34b9c4c609 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd1--driver-irql-not-less-or-equal.md @@ -0,0 +1,106 @@ +--- +title: Bug Check 0xD1 DRIVER_IRQL_NOT_LESS_OR_EQUAL +description: The DRIVER_IRQL_NOT_LESS_OR_EQUAL bug check has a value of 0x000000D1. This indicates that a kernel-mode driver attempted to access pageable memory at a process IRQL that was too high. +ms.assetid: 26cfd881-cc6e-4cc3-b464-e67d75700b96 +keywords: ["Bug Check 0xD1 DRIVER_IRQL_NOT_LESS_OR_EQUAL", "DRIVER_IRQL_NOT_LESS_OR_EQUAL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_IRQL_NOT_LESS_OR_EQUAL +api_type: +- NA +--- + +# Bug Check 0xD1: DRIVER\_IRQL\_NOT\_LESS\_OR\_EQUAL + + +The DRIVER\_IRQL\_NOT\_LESS\_OR\_EQUAL bug check has a value of 0x000000D1. This indicates that a kernel-mode driver attempted to access pageable memory at a process IRQL that was too high. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_IRQL\_NOT\_LESS\_OR\_EQUAL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL at time of reference

3

0: Read

+

1: Write

+

8: Execute

4

Address that referenced memory

+ +  + +Cause +----- + +A driver tried to access an address that is pageable (or that is completely invalid) while the IRQL was too high. + +This bug check is usually caused by drivers that have used improper addresses. + +If the first parameter has the same value as the fourth parameter, and the third parameter indicates an execute operation, this bug check was likely caused by a driver that was trying to execute code when the code itself was paged out. Possible causes for the page fault include the following: + +- The function was marked as pageable and was running at an elevated IRQL (which includes obtaining a lock). + +- The function call was made to a function in another driver, and that driver was unloaded. + +- The function was called by using a function pointer that was an invalid pointer. + +Resolution +---------- + +The [**!analyze**](-analyze.md) debug extension displays information about the bug check and can be very helpful in determining the root cause. + +For more information, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +To start, examine the stack trace using the [**k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command. + +If the problem is caused by the driver that you are developing, make sure that the function that was executing at the time of the bug check is not marked as pageable or does not call any other inline functions that could be paged out. + +If you are not equipped to use the Windows debugger to work on this problem, you can use some basic troubleshooting techniques. + +- Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing this bug check. + +- If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- For additional general troubleshooting information, see [**Blue Screen Data**](blue-screen-data.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd2--bugcode-id-driver.md b/windows-driver-docs-pr/debugger/bug-check-0xd2--bugcode-id-driver.md new file mode 100644 index 0000000000..b8c1aee44b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd2--bugcode-id-driver.md @@ -0,0 +1,167 @@ +--- +title: Bug Check 0xD2 BUGCODE_ID_DRIVER +description: The BUGCODE_ID_DRIVER bug check has a value of 0x000000D2. This indicates that a problem occurred with an NDIS driver. +ms.assetid: 697d128c-c79d-454a-a3e7-e9b85e3ab4bc +keywords: ["Bug Check 0xD2 BUGCODE_ID_DRIVER", "BUGCODE_ID_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BUGCODE_ID_DRIVER +api_type: +- NA +--- + +# Bug Check 0xD2: BUGCODE\_ID\_DRIVER + + +The BUGCODE\_ID\_DRIVER bug check has a value of 0x000000D2. This indicates that a problem occurred with an NDIS driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BUGCODE\_ID\_DRIVER Parameters + + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Message and Cause

Address of the miniport block

Number of bytes requested

0

1

Allocating shared memory at raised IRQL. A driver called NdisMAllocateSharedMemory with IRQL >= DISPATCH_LEVEL.

Address of the miniport block

The Status value submitted to NdisMResetComplete

The AddressingReset value submitted to NdisMResetComplete

0

Completing reset when one is not pending. A driver called NdisMResetComplete, but no reset was pending.

Address of the miniport block

Memory page containing address being freed

Address of shared memory signature

Virtual address being freed

Freeing shared memory not allocated. A driver called NdisMFreeSharedMemory or NdisMFreeSharedMemoryAsync with an address that is not located in NDIS shared memory.

Address of the miniport block

Address of the packet that is incorrectly included in the packet array

Address of the packet array

Number of packets in the array

Indicating packet not owned by it. The miniport's packet array is corrupt.

Address of the MiniBlock

Address of the driver object

0

0

NdisAddDevice: AddDevice called with a MiniBlock that is not on the NdisMiniDriverList.

Address of the MiniBlock

The MiniBlock's reference count

0

0

NdisMUnload: MiniBlock is getting unloaded but it is still on NdisMiniDriverList.

Address of the miniport block

Memory page

Wrapper context

Address of shared memory signature

Overwrote past allocated shared memory. The address being written to is not located in NDIS shared memory.

+ +  + +In the following instances of this bug check, the meaning of the parameters depends on the message and on the value of Parameter 4. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Message and Cause

Address of the miniport block

Address of the miniport interrupt

Address of the miniport timer queue

1

Unloading without deregistering interrupt. A miniport driver failed its initialization without deregistering its interrupt.

Address of the miniport block

Address of the miniport timer queue

Address of the miniport interrupt

2

Unloading without deregistering interrupt. A miniport driver did not deregister its interrupt during the halt process.

Address of the miniport block

Address of the miniport interrupt

Address of the miniport timer queue

1

Unloading without deregistering timer. A miniport driver failed its initialization without successfully canceling all its timers.

Address of the miniport block

Address of the miniport timer queue

Address of the miniport interrupt

2

Unloading without deregistering timer. A miniport driver halted without successfully canceling all its timers.

+ +  + +Remarks +------- + +This bug check code only occurs on Windows 2000 and Windows XP. In Windows Server 2003 and later, the corresponding code is [**bug check 0x7C**](bug-check-0x7c--bugcode-ndis-driver.md) (BUGCODE\_NDIS\_DRIVER). + +On the checked build of Windows, only the **Allocating Shared Memory at Raised IRQL** and **Completing Reset When One is Not Pending** instances of this bug check can occur. All the other instances of bug check 0xD2 are replaced with ASSERTs. See [Breaking Into the Debugger](breaking-into-the-debugger.md) for details. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd3--driver-portion-must-be-nonpaged.md b/windows-driver-docs-pr/debugger/bug-check-0xd3--driver-portion-must-be-nonpaged.md new file mode 100644 index 0000000000..c9b16699fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd3--driver-portion-must-be-nonpaged.md @@ -0,0 +1,81 @@ +--- +title: Bug Check 0xD3 DRIVER_PORTION_MUST_BE_NONPAGED +description: The DRIVER_PORTION_MUST_BE_NONPAGED bug check has a value of 0x000000D3. This indicates that the system attempted to access pageable memory at a process IRQL that was too high. +ms.assetid: 8b33dd20-9faa-4c02-96b7-89f55e69aeec +keywords: ["Bug Check 0xD3 DRIVER_PORTION_MUST_BE_NONPAGED", "DRIVER_PORTION_MUST_BE_NONPAGED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_PORTION_MUST_BE_NONPAGED +api_type: +- NA +--- + +# Bug Check 0xD3: DRIVER\_PORTION\_MUST\_BE\_NONPAGED + + +The DRIVER\_PORTION\_MUST\_BE\_NONPAGED bug check has a value of 0x000000D3. This indicates that the system attempted to access pageable memory at a process IRQL that was too high. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_PORTION\_MUST\_BE\_NONPAGED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL at time of reference

3

0: Read

+

1: Write

4

Address that referenced memory

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +This bug check is usually caused by drivers that have incorrectly marked their own code or data as pageable. + +Resolution +---------- + +To begin debugging, use a kernel debugger to get a stack trace. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd4--system-scan-at-raised-irql-caught-improper-driver-unlo.md b/windows-driver-docs-pr/debugger/bug-check-0xd4--system-scan-at-raised-irql-caught-improper-driver-unlo.md new file mode 100644 index 0000000000..8a44b798b3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd4--system-scan-at-raised-irql-caught-improper-driver-unlo.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xD4 SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD +description: The SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD bug check has a value of 0x000000D4. This indicates that a driver did not cancel pending operations before unloading. +ms.assetid: 4c0e69d1-737c-4dd7-b52a-4cd5eeadcbb9 +keywords: ["Bug Check 0xD4 SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD", "SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD +api_type: +- NA +--- + +# Bug Check 0xD4: SYSTEM\_SCAN\_AT\_RAISED\_IRQL\_CAUGHT\_IMPROPER\_DRIVER\_UNLOAD + + +The SYSTEM\_SCAN\_AT\_RAISED\_IRQL\_CAUGHT\_IMPROPER\_DRIVER\_UNLOAD bug check has a value of 0x000000D4. This indicates that a driver did not cancel pending operations before unloading. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_SCAN\_AT\_RAISED\_IRQL\_CAUGHT\_IMPROPER\_DRIVER\_UNLOAD Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL at time of reference

3

0: Read

+

1: Write

4

Address that referenced memory

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +This driver failed to cancel lookaside lists, DPCs, worker threads, or other such items before unload. Subsequently, the system attempted to access the driver's former location at a raised IRQL. + +Resolution +---------- + +To begin debugging, use a kernel debugger to get a stack trace. If the driver that caused the error has been identified, activate Driver Verifier and attempt to replicate this bug. + +For full details on Driver Verifier, see the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd5--driver-page-fault-in-freed-special-pool.md b/windows-driver-docs-pr/debugger/bug-check-0xd5--driver-page-fault-in-freed-special-pool.md new file mode 100644 index 0000000000..06bbaed179 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd5--driver-page-fault-in-freed-special-pool.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xD5 DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL +description: The DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL bug check has a value of 0x000000D5. This indicates that a driver has referenced memory which was earlier freed. +ms.assetid: b86e55d2-122f-40ac-adb3-092511d3274e +keywords: ["Bug Check 0xD5 DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL", "DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL +api_type: +- NA +--- + +# Bug Check 0xD5: DRIVER\_PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL + + +The DRIVER\_PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL bug check has a value of 0x000000D5. This indicates that a driver has referenced memory which was earlier freed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +The Driver Verifier **Special Pool** option has caught the driver accessing memory which was earlier freed. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +Remarks +------- + +This cannot be protected by a **try - except** handler -- it can only be protected by a probe. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd6--driver-page-fault-beyond-end-of-allocation.md b/windows-driver-docs-pr/debugger/bug-check-0xd6--driver-page-fault-beyond-end-of-allocation.md new file mode 100644 index 0000000000..a45c55c8ca --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd6--driver-page-fault-beyond-end-of-allocation.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xD6 DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION +description: The DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION bug check has a value of 0x000000D6. This indicates the driver accessed memory beyond the end of its pool allocation. +ms.assetid: 939165dc-3052-4de7-88fd-25d4a7e82945 +keywords: ["Bug Check 0xD6 DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION", "DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION +api_type: +- NA +--- + +# Bug Check 0xD6: DRIVER\_PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION + + +The DRIVER\_PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION bug check has a value of 0x000000D6. This indicates the driver accessed memory beyond the end of its pool allocation. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory address referenced

2

0: Read

+

1: Write

3

Address that referenced memory (if known)

4

Reserved

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) *KiBugCheckDriver*. + +Cause +----- + +The driver allocated *n* bytes of memory and then referenced more than *n* bytes. The Driver Verifier **Special Pool** option detected this violation. + +For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit. + +Remarks +------- + +This cannot be protected by a **try - except** handler -- it can only be protected by a probe. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd7--driver-unmapping-invalid-view.md b/windows-driver-docs-pr/debugger/bug-check-0xd7--driver-unmapping-invalid-view.md new file mode 100644 index 0000000000..d70338d850 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd7--driver-unmapping-invalid-view.md @@ -0,0 +1,74 @@ +--- +title: Bug Check 0xD7 DRIVER_UNMAPPING_INVALID_VIEW +description: The DRIVER_UNMAPPING_INVALID_VIEW bug check has a value of 0x000000D7. This indicates a driver is trying to unmap an address that was not mapped. +ms.assetid: 68075aa7-f579-49c7-a30a-a21312625ff9 +keywords: ["Bug Check 0xD7 DRIVER_UNMAPPING_INVALID_VIEW", "DRIVER_UNMAPPING_INVALID_VIEW"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_UNMAPPING_INVALID_VIEW +api_type: +- NA +--- + +# Bug Check 0xD7: DRIVER\_UNMAPPING\_INVALID\_VIEW + + +The DRIVER\_UNMAPPING\_INVALID\_VIEW bug check has a value of 0x000000D7. This indicates a driver is trying to unmap an address that was not mapped. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_UNMAPPING\_INVALID\_VIEW Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Virtual address to unmap

2

1: The view is being unmapped

+

2: The view is being committed

3

0

4

0

+ +  + +Remarks +------- + +The driver that caused the error can be determined from the stack trace. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd8--driver-used-excessive-ptes.md b/windows-driver-docs-pr/debugger/bug-check-0xd8--driver-used-excessive-ptes.md new file mode 100644 index 0000000000..e506a57244 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd8--driver-used-excessive-ptes.md @@ -0,0 +1,80 @@ +--- +title: Bug Check 0xD8 DRIVER_USED_EXCESSIVE_PTES +description: The DRIVER_USED_EXCESSIVE_PTES bug check has a value of 0x000000D8. This indicates that there are no more system page table entries (PTE) remaining. +ms.assetid: a11212eb-8dd7-49f3-9b23-237ed88b9cff +keywords: ["Bug Check 0xD8 DRIVER_USED_EXCESSIVE_PTES", "DRIVER_USED_EXCESSIVE_PTES"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_USED_EXCESSIVE_PTES +api_type: +- NA +--- + +# Bug Check 0xD8: DRIVER\_USED\_EXCESSIVE\_PTES + + +The DRIVER\_USED\_EXCESSIVE\_PTES bug check has a value of 0x000000D8. This indicates that there are no more system page table entries (PTE) remaining. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_USED\_EXCESSIVE\_PTES Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Pointer to the name of the driver that caused the error (Unicode string), or zero

2

Number of PTEs used by the driver that caused the error (if Parameter 1 is nonzero)

3

Total free system PTEs

4

Total system PTEs

+ +  + +If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE\_STRING) **KiBugCheckDriver**. + +Cause +----- + +This is usually caused by a driver not cleaning up its memory use properly. Parameter 1 shows the driver which has consumed the most PTEs. The call stack will reveal which driver actually caused the bug check. + +Resolution +---------- + +Both drivers may need to be fixed. The total number of system PTEs may also need to be increased. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xd9--locked-pages-tracker-corruption.md b/windows-driver-docs-pr/debugger/bug-check-0xd9--locked-pages-tracker-corruption.md new file mode 100644 index 0000000000..e064bcd26f --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xd9--locked-pages-tracker-corruption.md @@ -0,0 +1,93 @@ +--- +title: Bug Check 0xD9 LOCKED_PAGES_TRACKER_CORRUPTION +description: The LOCKED_PAGES_TRACKER_CORRUPTION bug check has a value of 0x000000D9. This indicates that the internal locked-page tracking structures have been corrupted. +ms.assetid: 81011ce6-159c-448f-9f68-7b1eb949ff68 +keywords: ["Bug Check 0xD9 LOCKED_PAGES_TRACKER_CORRUPTION", "LOCKED_PAGES_TRACKER_CORRUPTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- LOCKED_PAGES_TRACKER_CORRUPTION +api_type: +- NA +--- + +# Bug Check 0xD9: LOCKED\_PAGES\_TRACKER\_CORRUPTION + + +The LOCKED\_PAGES\_TRACKER\_CORRUPTION bug check has a value of 0x000000D9. This indicates that the internal locked-page tracking structures have been corrupted. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## LOCKED\_PAGES\_TRACKER\_CORRUPTION Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x01

The address of the internal lock tracking structure

The address of the memory descriptor list

The number of pages locked for the current process

The MDL is being inserted twice on the same process list.

0x02

The address of the internal lock tracking structure

The address of the memory descriptor list

The number of pages locked for the current process

The MDL is being inserted twice on the systemwide list.

0x03

The address of the first internal tracking structure found

The address of the internal lock tracking structure

The address of the memory descriptor list

The MDL was found twice in the process list when being freed.

0x04

The address of the internal lock tracking structure

The address of the memory descriptor list

0

The MDL was found in the systemwide list on free after it was removed.

+ +  + +Cause +----- + +The error is indicated by the value of Parameter 1. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xda--system-pte-misuse.md b/windows-driver-docs-pr/debugger/bug-check-0xda--system-pte-misuse.md new file mode 100644 index 0000000000..fcd00b7892 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xda--system-pte-misuse.md @@ -0,0 +1,343 @@ +--- +title: Bug Check 0xDA SYSTEM_PTE_MISUSE +description: The SYSTEM_PTE_MISUSE bug check has a value of 0x000000DA. This indicates that a page table entry (PTE) routine has been used in an improper way. +ms.assetid: a9a9f3e9-39b7-4e4a-a326-2f510e0aaa99 +keywords: ["Bug Check 0xDA SYSTEM_PTE_MISUSE", "SYSTEM_PTE_MISUSE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SYSTEM_PTE_MISUSE +api_type: +- NA +--- + +# Bug Check 0xDA: SYSTEM\_PTE\_MISUSE + + +The SYSTEM\_PTE\_MISUSE bug check has a value of 0x000000DA. This indicates that a page table entry (PTE) routine has been used in an improper way. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SYSTEM\_PTE\_MISUSE Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x01

The address of the internal lock tracking structure

The address of the memory descriptor list

The address of the duplicate internal lock tracking structure

The mapping being freed is a duplicate.

0x02

The address of the internal lock tracking structure

The number of mappings that the system expects to free

The number of mappings that the driver is requesting to free

The number of mappings being freed is incorrect.

0x03

The address of the first internal tracking structure found

The mapping address that the system expects to free

The mapping address that the driver is requesting to free

The mapping address being freed is incorrect.

0x04

The address of the internal lock tracking structure

The page frame number that the system expects should be first in the MDL

The page frame number that is currently first in the MDL

The first page of the mapped MDL has changed since the MDL was mapped.

0x05

The address of the first internal tracking structure found

The virtual address that the system expects to free

The virtual address that the driver is requesting to free

The start virtual address in the MDL being freed has changed since the MDL was mapped.

0x06

The MDL specified by the driver

The virtual address specified by the driver

The number of mappings to free (specified by the driver)

The MDL being freed was never (or is currently not) mapped.

0x07

The initial mapping

The number of mappings

Reserved

(Windows 2000 only) The mapping range is being double-allocated.

0x08

The initial mapping

The number of mappings the caller is freeing

The number of mappings the system thinks should be freed

(Windows 2000 only) The caller is asking to free an incorrect number of mappings.

0x09

The initial mapping

The number of mappings that the caller is freeing

The mapping index that the system thinks is already free

(Windows 2000 only) The caller is asking to free several mappings, but at least one of them is not allocated.

0x0A

1: The driver requested "bug check on failure" in the MDL.

+

0: The driver did not request "bug check on failure" in the MDL.

The number of mappings that the caller is allocating

The type of mapping pool requested

(Windows 2000 only) The caller is asking to allocate zero mappings.

0x0B

The corrupt mapping

The number of mappings that the caller is allocating

The type of mapping pool requested

(Windows 2000 only) The mapping list was already corrupt at the time of this allocation. The corrupt mapping is located below the lowest possible mapping address.

0x0C

The corrupt mapping

The number of mappings that the caller is allocating

The type of mapping pool requested

(Windows 2000 only) The mapping list was already corrupt at the time of this allocation. The corrupt mapping is located above the lowest possible mapping address.

0x0D

The initial mapping

The number of mappings that the caller is freeing

The type of mapping pool

(Windows 2000 only) The caller is trying to free zero mappings.

0x0E

The initial mapping

The number of mappings that the caller is freeing

The type of mapping pool

(Windows 2000 only) The caller is trying to free mappings, but the guard mapping has been overwritten.

0x0F

The non-existent mapping

The number of mappings that the caller is trying to free

The type of mapping pool being freed

(Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent mapping is located below the lowest possible mapping address.

0x10

The non-existent mapping

The number of mappings the caller is trying to free

The type of mapping pool being freed

(Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent mapping is located above the highest possible mapping address.

0x11

The non-existent mapping

The number of mappings that the caller is trying to free

The type of mapping pool being freed

(Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent mapping is at the base of the mapping address space.

0x100

The number of mappings being requested

The caller's identifying tag

The address of the routine that called the caller of this routine

(Windows XP and later only) The caller requested 0 mappings.

0x101

The first mapping address

The caller's identifying tag

The owner's identifying tag

(Windows XP and later only) A caller is trying to free a mapping address range that it does not own.

0x102

The first mapping address

The caller's identifying tag

Reserved

(Windows XP and later only) The mapping address space that the caller is trying to free is apparently empty.

0x103

The address of the invalid mapping

The caller's identifying tag

The number of mappings in the mapping address space

(Windows XP and later only) The mapping address space that the caller is trying to free is still reserved. [MmUnmapReservedMapping](https://msdn.microsoft.com/library/windows/hardware/ff556392)

+

must be called before [MmFreeMappingAddress](https://msdn.microsoft.com/library/windows/hardware/ff554512).

0x104

The first mapping address

The caller's identifying tag

The owner's identifying tag

(Windows XP and later only) The caller is attempting to map an MDL to a mapping address space that it does not own.

0x105

The first mapping address

The caller's identifying tag

Reserved

(Windows XP and later only) The caller is attempting to map an MDL to an invalid mapping address space. The caller has mostly likely specified an invalid address.

0x107

The first mapping address

The address of the non-empty mapping

The last mapping address

(Windows XP and later only) The caller is attempting to map an MDL to a mapping address space that has not been properly reserved. The caller should have called [MmUnmapReservedMapping](https://msdn.microsoft.com/library/windows/hardware/ff556392) prior to calling [MmMapLockedPagesWithReservedMapping](https://msdn.microsoft.com/library/windows/hardware/ff554640)

0x108

The first mapping address

The caller's identifying tag

The owner's identifying tag

(Windows XP and later only) The caller is attempting to unmap a locked mapping address space that it does not own.

0x109

The first mapping address

The caller's identifying tag

Reserved

(Windows XP and later only) The caller is attempting to unmap a locked virtual address space that is apparently empty.

0x10A

The first mapping address

The number of mappings in the locked mapping address space

The number of mappings to unmap

(Windows XP and later only) The caller is attempting to unmap more mappings than actually exist in the locked mapping address space.

0x10B

The first mapping address

The caller's identifying tag

The number of mappings to unmap

(Windows XP and later only) The caller is attempting to unmap a portion of a locked virtual address space that is not currently mapped.

0x10C

The first mapping address

The caller's identifying tag

The number of mappings to unmap

(Windows XP and later only) The caller is not unmapping the entirety of the locked mapping address space.

0x200

The first mapping address

0

0

(Windows XP and later only) The caller is attempting to reserve a mapping address space that contains no mappings.

0x201

+

0x202

The first mapping address to reserve

The address of the mapping that has already been reserved

The number of mappings to reserve

(Windows XP and later only) One of the mappings that the caller is attempting to reserve has already been reserved.

0x300

The first mapping address to release

0

0

(Windows XP and later only) The caller is attempting to release a mapping address space that contains no mappings.

0x301

The address of the mapping

0

0

(Windows XP and later only) The caller is attempting to release a mapping that it is not permitted to release.

0x302

The address that the caller is trying to release.

Reserved

Reserved

The caller is attempting to release a system address that is not currently mapped.

0x303

The first mapping address

The number of mappings to release

0

(Windows XP and later only) The caller is attempting to release a mapping address range that was not reserved.

0x304

The first mapping address

The number of mappings to release

0

(Windows XP and later only) The caller is attempting to release a mapping address range that begins in the middle of a different allocation.

0x305

The first mapping address

The number of mappings that the caller is trying to release

The number of mappings that should be released

(Windows XP and later only) The caller is attempting to release the wrong number of mappings.

0x306

The first mapping address

The free mapping address

The number of mappings to release

(Windows XP and later only) One of the mappings that the caller is attempting to release is already free.

0x400

The base address of the I/O space mapping

The number of pages to be freed

0

(Windows XP and later only) The caller is trying to free an I/O space mapping that the system is unaware of.

+ +  + +Cause +----- + +The error is indicated by the value of Parameter 1. + +A stack trace will identify the driver that caused the error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xdb--driver-corrupted-sysptes.md b/windows-driver-docs-pr/debugger/bug-check-0xdb--driver-corrupted-sysptes.md new file mode 100644 index 0000000000..f140dde96d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xdb--driver-corrupted-sysptes.md @@ -0,0 +1,79 @@ +--- +title: Bug Check 0xDB DRIVER_CORRUPTED_SYSPTES +description: The DRIVER_CORRUPTED_SYSPTES bug check has a value of 0x000000DB. This indicates that an attempt was made to touch memory at an invalid IRQL, probably due to corruption of system PTEs. +ms.assetid: f21a7582-c665-4677-851b-702888d9fe13 +keywords: ["Bug Check 0xDB DRIVER_CORRUPTED_SYSPTES", "DRIVER_CORRUPTED_SYSPTES"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_CORRUPTED_SYSPTES +api_type: +- NA +--- + +# Bug Check 0xDB: DRIVER\_CORRUPTED\_SYSPTES + + +The DRIVER\_CORRUPTED\_SYSPTES bug check has a value of 0x000000DB. This indicates that an attempt was made to touch memory at an invalid IRQL, probably due to corruption of system PTEs. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_CORRUPTED\_SYSPTES Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Memory referenced

2

IRQL

3

0: Read

+

1: Write

4

Address in code which referenced memory

+ +  + +Cause +----- + +A driver tried to access pageable (or completely invalid) memory at too high of an IRQL. This bug check is almost always caused by drivers that have corrupted system PTEs. + +Resolution +---------- + +If this bug check occurs, the culprit can be detected by editing the registry. In the **\\\\HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management** registry key, create or edit the **TrackPtes** value, and set it equal to DWORD 3. Then reboot. The system will then save stack traces, and if the driver commits the same error, the system will issue [**bug check 0xDA**](bug-check-0xda--system-pte-misuse.md) (SYSTEM\_PTE\_MISUSE). Then the stack trace will identify the driver that caused the error. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xdc--driver-invalid-stack-access.md b/windows-driver-docs-pr/debugger/bug-check-0xdc--driver-invalid-stack-access.md new file mode 100644 index 0000000000..06d1221dd7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xdc--driver-invalid-stack-access.md @@ -0,0 +1,37 @@ +--- +title: Bug Check 0xDC DRIVER_INVALID_STACK_ACCESS +description: The DRIVER_INVALID_STACK_ACCESS bug check has a value of 0x000000DC. This indicates that a driver accessed a stack address that lies below the stack pointer of the stack's thread. +ms.assetid: efc2201f-b2e5-458b-a2b0-26abaa46f1a4 +keywords: ["Bug Check 0xDC DRIVER_INVALID_STACK_ACCESS", "DRIVER_INVALID_STACK_ACCESS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_INVALID_STACK_ACCESS +api_type: +- NA +--- + +# Bug Check 0xDC: DRIVER\_INVALID\_STACK\_ACCESS + + +The DRIVER\_INVALID\_STACK\_ACCESS bug check has a value of 0x000000DC. This indicates that a driver accessed a stack address that lies below the stack pointer of the stack's thread. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_INVALID\_STACK\_ACCESS Parameters + + +None + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xde--pool-corruption-in-file-area.md b/windows-driver-docs-pr/debugger/bug-check-0xde--pool-corruption-in-file-area.md new file mode 100644 index 0000000000..5cc357c094 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xde--pool-corruption-in-file-area.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0xDE POOL_CORRUPTION_IN_FILE_AREA +description: The POOL_CORRUPTION_IN_FILE_AREA bug check has a value of 0x000000DE. This indicates that a driver has corrupted pool memory that is used for holding pages destined for disk. +ms.assetid: 6394e0fa-76ee-4924-8aa3-d10a4d57c6e8 +keywords: ["Bug Check 0xDE POOL_CORRUPTION_IN_FILE_AREA", "POOL_CORRUPTION_IN_FILE_AREA"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- POOL_CORRUPTION_IN_FILE_AREA +api_type: +- NA +--- + +# Bug Check 0xDE: POOL\_CORRUPTION\_IN\_FILE\_AREA + + +The POOL\_CORRUPTION\_IN\_FILE\_AREA bug check has a value of 0x000000DE. This indicates that a driver has corrupted pool memory that is used for holding pages destined for disk. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## POOL\_CORRUPTION\_IN\_FILE\_AREA Parameters + + +None + +Cause +----- + +When the Memory Manager dereferenced the file, it discovered this corruption in pool memory. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xdeaddead--manually-initiated-crash1.md b/windows-driver-docs-pr/debugger/bug-check-0xdeaddead--manually-initiated-crash1.md new file mode 100644 index 0000000000..bef784dc52 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xdeaddead--manually-initiated-crash1.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0xDEADDEAD MANUALLY_INITIATED_CRASH1 +description: The MANUALLY_INITIATED_CRASH1 bug check has a value of 0xDEADDEAD. This indicates that the user deliberately initiated a crash dump from either the kernel debugger or the keyboard. +ms.assetid: b7439fc7-3146-48c9-b44e-dddea2d84769 +keywords: ["Bug Check 0xDEADDEAD MANUALLY_INITIATED_CRASH1", "MANUALLY_INITIATED_CRASH1"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MANUALLY_INITIATED_CRASH1 +api_type: +- NA +--- + +# Bug Check 0xDEADDEAD: MANUALLY\_INITIATED\_CRASH1 + + +The MANUALLY\_INITIATED\_CRASH1 bug check has a value of 0xDEADDEAD. This indicates that the user deliberately initiated a crash dump from either the kernel debugger or the keyboard. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MANUALLY\_INITIATED\_CRASH1 Parameters + + +None + +Remarks +------- + +For details on manually-initiated crash dumps, see [Forcing a System Crash](forcing-a-system-crash.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xdf--impersonating-worker-thread.md b/windows-driver-docs-pr/debugger/bug-check-0xdf--impersonating-worker-thread.md new file mode 100644 index 0000000000..2628551c3e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xdf--impersonating-worker-thread.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xDF IMPERSONATING_WORKER_THREAD +description: The IMPERSONATING_WORKER_THREAD bug check has a value of 0x000000DF. This indicates that a workitem did not disable impersonation before it completed. +ms.assetid: d8a68b5b-3aa8-4d02-8063-420834a47f1b +keywords: ["Bug Check 0xDF IMPERSONATING_WORKER_THREAD", "IMPERSONATING_WORKER_THREAD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- IMPERSONATING_WORKER_THREAD +api_type: +- NA +--- + +# Bug Check 0xDF: IMPERSONATING\_WORKER\_THREAD + + +The IMPERSONATING\_WORKER\_THREAD bug check has a value of 0x000000DF. This indicates that a workitem did not disable impersonation before it completed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## IMPERSONATING\_WORKER\_THREAD Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The worker routine that caused this error

2

The parameter passed to this worker routine

3

A pointer to the work item

4

Reserved

+ +  + +Cause +----- + +A worker thread was impersonating another process, and failed to disable impersonation before it returned. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe--no-user-mode-context.md b/windows-driver-docs-pr/debugger/bug-check-0xe--no-user-mode-context.md new file mode 100644 index 0000000000..dbd6648ae1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe--no-user-mode-context.md @@ -0,0 +1,34 @@ +--- +title: Bug Check 0xE NO_USER_MODE_CONTEXT +description: The NO_USER_MODE_CONTEXT bug check has a value of 0x0000000E.This bug check appears very infrequently. +ms.assetid: 0c3b3da9-c9e6-443d-9087-9bee9aa1e41a +keywords: ["Bug Check 0xE NO_USER_MODE_CONTEXT", "NO_USER_MODE_CONTEXT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- NO_USER_MODE_CONTEXT +api_type: +- NA +--- + +# Bug Check 0xE: NO\_USER\_MODE\_CONTEXT + + +The NO\_USER\_MODE\_CONTEXT bug check has a value of 0x0000000E. + +This bug check appears very infrequently. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe0--acpi-bios-fatal-error.md b/windows-driver-docs-pr/debugger/bug-check-0xe0--acpi-bios-fatal-error.md new file mode 100644 index 0000000000..cbd79d4b37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe0--acpi-bios-fatal-error.md @@ -0,0 +1,51 @@ +--- +title: Bug Check 0xE0 ACPI_BIOS_FATAL_ERROR +description: The ACPI_BIOS_FATAL_ERROR bug check has a value of 0x000000E0. This indicates that one of your computer components is faulty. +ms.assetid: 4cc4c96e-6e0e-4bf1-8e72-4e6f39848914 +keywords: ["Bug Check 0xE0 ACPI_BIOS_FATAL_ERROR", "ACPI_BIOS_FATAL_ERROR"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ACPI_BIOS_FATAL_ERROR +api_type: +- NA +--- + +# Bug Check 0xE0: ACPI\_BIOS\_FATAL\_ERROR + + +The ACPI\_BIOS\_FATAL\_ERROR bug check has a value of 0x000000E0. This indicates that one of your computer components is faulty. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ACPI\_BIOS\_FATAL\_ERROR Parameters + + +The parameters for this bug check are issued by the BIOS, not by Windows. They can only be interpreted by the hardware vendor. + +Cause +----- + +Your computer's BIOS has reported that a component in the system is so faulty that there is no way for Windows to operate. The BIOS is indicating that there is no alternative but to issue a bug check. + +Resolution +---------- + +You can determine which component is faulty by running the diagnostic disk or tool that was included with your computer. + +If you do not have this tool, you must contact the system vendor and report this error message to them. They will be able to help you correct this hardware problem. This enables Windows to operate. + +Microsoft cannot address this error. Only the hardware vendor is qualified to analyze it. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe1--worker-thread-returned-at-bad-irql.md b/windows-driver-docs-pr/debugger/bug-check-0xe1--worker-thread-returned-at-bad-irql.md new file mode 100644 index 0000000000..515efc2f6d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe1--worker-thread-returned-at-bad-irql.md @@ -0,0 +1,84 @@ +--- +title: Bug Check 0xE1 WORKER_THREAD_RETURNED_AT_BAD_IRQL +description: The WORKER_THREAD_RETURNED_AT_BAD_IRQL bug check has a value of 0x000000E1. This indicates that a worker thread completed and returned with IRQL DISPATCH_LEVEL. +ms.assetid: c02b98e9-e3a4-473a-bd9f-3130b7e58c1d +keywords: ["Bug Check 0xE1 WORKER_THREAD_RETURNED_AT_BAD_IRQL", "WORKER_THREAD_RETURNED_AT_BAD_IRQL"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_THREAD_RETURNED_AT_BAD_IRQL +api_type: +- NA +--- + +# Bug Check 0xE1: WORKER\_THREAD\_RETURNED\_AT\_BAD\_IRQL + + +The WORKER\_THREAD\_RETURNED\_AT\_BAD\_IRQL bug check has a value of 0x000000E1. This indicates that a worker thread completed and returned with IRQL >= DISPATCH\_LEVEL. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_THREAD\_RETURNED\_AT\_BAD\_IRQL Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of the worker routine

2

IRQL that the worker thread returned at

3

Work item parameter

4

Work item address

+ +  + +Cause +----- + +A worker thread completed and returned with IRQL >= DISPATCH\_LEVEL. + +Resolution +---------- + +To find the driver that caused the error, use the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) debugger command: + +``` +kd> ln address +``` + +where *address* is the worker routine address given in Parameter 1. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe2--manually-initiated-crash.md b/windows-driver-docs-pr/debugger/bug-check-0xe2--manually-initiated-crash.md new file mode 100644 index 0000000000..09b04d26c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe2--manually-initiated-crash.md @@ -0,0 +1,42 @@ +--- +title: Bug Check 0xE2 MANUALLY_INITIATED_CRASH +description: The MANUALLY_INITIATED_CRASH bug check has a value of 0x000000E2. This indicates that the user deliberately initiated a crash dump from either the kernel debugger or the keyboard. +ms.assetid: 6248355f-6b27-44ac-8772-8599630a8245 +keywords: ["Bug Check 0xE2 MANUALLY_INITIATED_CRASH", "MANUALLY_INITIATED_CRASH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- MANUALLY_INITIATED_CRASH +api_type: +- NA +--- + +# Bug Check 0xE2: MANUALLY\_INITIATED\_CRASH + + +The MANUALLY\_INITIATED\_CRASH bug check has a value of 0x000000E2. This indicates that the user deliberately initiated a crash dump from either the kernel debugger or the keyboard. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## MANUALLY\_INITIATED\_CRASH Parameters + + +None + +Remarks +------- + +For more information about manually-initiated crash dumps, see Forcing a System Crash. . + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe3--resource-not-owned.md b/windows-driver-docs-pr/debugger/bug-check-0xe3--resource-not-owned.md new file mode 100644 index 0000000000..a3009f5f7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe3--resource-not-owned.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0xE3 RESOURCE_NOT_OWNED +description: The RESOURCE_NOT_OWNED bug check has a value of 0x000000E3. This indicates that a thread tried to release a resource it did not own. +ms.assetid: f0f47af6-cba0-42a0-912b-562f069d5b3e +keywords: ["Bug Check 0xE3 RESOURCE_NOT_OWNED", "RESOURCE_NOT_OWNED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RESOURCE_NOT_OWNED +api_type: +- NA +--- + +# Bug Check 0xE3: RESOURCE\_NOT\_OWNED + + +The RESOURCE\_NOT\_OWNED bug check has a value of 0x000000E3. This indicates that a thread tried to release a resource it did not own. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RESOURCE\_NOT\_OWNED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Address of resource

2

Address of thread

3

Address of owner table (if it exists)

4

Reserved

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe4--worker-invalid.md b/windows-driver-docs-pr/debugger/bug-check-0xe4--worker-invalid.md new file mode 100644 index 0000000000..5bb86e59f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe4--worker-invalid.md @@ -0,0 +1,114 @@ +--- +title: Bug Check 0xE4 WORKER_INVALID +description: The WORKER_INVALID bug check has a value of 0x000000E4. This typically indicates that memory that should not contain an executive work item does contain such an item. +ms.assetid: 93951b77-bedf-4781-9c2b-e8df2aa8cb1c +keywords: ["Bug Check 0xE4 WORKER_INVALID", "WORKER_INVALID"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WORKER_INVALID +api_type: +- NA +--- + +# Bug Check 0xE4: WORKER\_INVALID + + +The WORKER\_INVALID bug check has a value of 0x000000E4. This indicates that memory that should not contain an executive work item does contain such an item, or that a currently active work item was queued. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## WORKER\_INVALID Parameters + + +Parameter 1 indicates the code position. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x0

Address of work item

Start of pool block

End of pool block

An active worker item was freed.

0x1

Address of work item

Queue number

0

An active worker item was queued.

0x2

Address of work item

Address of I/O worker routine

0

A queued I/O worker item was freed.

0x3

Address of work item

Address of invalid object

0

An attempt was made to initialize an I/O worker item with an invalid object.

0x5

Address of work item

Queue number

NUMA Node targeted or -1 if all NODES were searched for.

An attempt was made to queue a work item before Worker Queued was initialized.

0x6

Address of work item

Queue number

0

Invalid queue type was provided.

0x7

Address of work item

Queue number

0

An attempt was made to queue a work item with an invalid worker routine address.

+ +  + +Cause +----- + +This is usually caused by a driver freeing memory which still contains an executive work item. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe6--driver-verifier-dma-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xe6--driver-verifier-dma-violation.md new file mode 100644 index 0000000000..dceea90fc5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe6--driver-verifier-dma-violation.md @@ -0,0 +1,190 @@ +--- +title: Bug Check 0xE6 DRIVER_VERIFIER_DMA_VIOLATION +description: The DRIVER_VERIFIER_DMA_VIOLATION bug check has a value of 0x000000E6. This is the bug check code for all Driver Verifier DMA Verification violations. +ms.assetid: badf8948-356c-4728-b34e-02f1638630a6 +keywords: ["Bug Check 0xE6 DRIVER_VERIFIER_DMA_VIOLATION", "DRIVER_VERIFIER_DMA_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_VERIFIER_DMA_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xE6: DRIVER\_VERIFIER\_DMA\_VIOLATION + + +The DRIVER\_VERIFIER\_DMA\_VIOLATION bug check has a value of 0x000000E6. This is the bug check code for all Driver Verifier **DMA Verification** violations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_VERIFIER\_DMA\_VIOLATION Parameters + + +Parameter 1 is the only parameter of interest. This parameter identifies the exact violation. If a debugger is attached, an informative message is displayed in the debugger. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Cause of Error and Debugger Message

0x00

This code can represent two kinds of errors:

+

1. The driver tried to flush too many bytes to the end of the map register file. The number of bytes permitted and the number of bytes attempted are displayed.

+

2. Windows has run out of contiguous map registers. The number of map registers needed and the largest block of contiguous map registers is displayed.

0x01

The performance counter has decreased. The old and new values of the counter are displayed.

0x02

The performance counter has increased too fast. The counter value is displayed in the debugger.

0x03

The driver freed too many DMA common buffers. Usually this means it freed the same buffer two times.

0x04

The driver freed too many DMA adapter channels. Usually this means it freed the same adapter channel two times.

0x05

The driver freed too many DMA map registers. Usually this means it freed the same map register two times. The number of active map registers is displayed.

0x06

The driver freed too many DMA scatter/gather lists. Usually this means it freed the same scatter/gather list two times. The number of lists allocated and the number of lists freed is displayed.

0x07

The driver tried to release the adapter without first freeing all its common buffers. The adapter address and the number of remaining buffers is displayed.

0x08

The driver tried to release the adapter without first freeing all adapter channels, common buffers, or scatter/gather lists. The adapter address and the number of remaining items is displayed.

0x09

The driver tried to release the adapter without first freeing all map registers. The adapter address and the number of remaining map registers is displayed.

0x0A

The driver tried to release the adapter without first freeing all its scatter/gather lists. The adapter address and the number of remaining scatter/gather lists is displayed.

0x0B

HV_TOO_MANY_ADAPTER_CHANNELSThe driver has allocated too many adapter channels at the same time. . (Only one adapter channel is permitted per adapter.)

0x0C

The driver tried to allocate too many map registers at the same time. The number requested and the number allowed are displayed.

0x0D

The driver did not flush its adapter buffers. The number of bytes that the driver tried to map and the maximum number of bytes allowed are displayed.

0x0E

The driver tried a DMA transfer without locking the buffer. The buffer in question was in paged memory. The address of the MDL is displayed.

0x0F

The driver or the hardware wrote outside its allocated DMA buffer. The nature of the error (overrun or underrun) is displayed, as well as the relevant addresses.

0x10

The driver tried to free its map registers while some were still mapped. The number of map registers still mapped is displayed.

0x11

The driver has too many outstanding reference counts for the adapter. The number of reference counts and the adapter address are displayed.

0x13

The driver called a DMA routine at an improper IRQL. The required IRQL and the actual IRQL are displayed.

0x14

The driver called a DMA routine at an improper IRQL. The required IRQL and the actual IRQL are displayed.

0x15

The driver tried to allocate too many map registers. The number requested and the number allowed are displayed.

0x16

The driver tried to flush a buffer that is not mapped. The address of the buffer is displayed.

0x18

The driver tried a DMA operation by using an adapter that was already released and no longer exists. The adapter address is displayed.

0x19

The driver passed a null DMA_ADAPTER value to a HAL routine.

0x1B

The driver passed an address and MDL to a HAL routine. However, this address is not within the bounds of this MDL. The address passed and the address of the MDL are displayed.

0x1D

The driver tried to map an address range that was already mapped. The address range and the current mapping for that range are displayed.

0x1E

The driver called HalGetAdapter. This function is obsolete -- you must use IoGetDmaAdapter instead.

0x1F

HV_BAD_MDLThe driver referenced an invalid system address -- either before the first MDL, or after the end of the first MDL, or by using a transfer length that is longer than the MDL buffer and crosses a page boundary within the MDL. . Either the invalid address and the first MDL address, or the MDL address and the extra transfer length are displayed.

0x20

The driver tried to flush a map register that hasn't been mapped. The map register base, flushing address, and MDL are displayed.

0x21

The driver tried to map a zero-length buffer for transfer.

+ +  + +Cause +----- + +See the description of each code in the Parameters section for a description of the cause. + +Resolution +---------- + +This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it. You might also consider removing the driver that caused this problem. + +If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code. + +The Driver Verifier **DMA Verification** option is only available in Windows XP and later versions. For full details on Driver Verifier, see the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe7--invalid-floating-point-state.md b/windows-driver-docs-pr/debugger/bug-check-0xe7--invalid-floating-point-state.md new file mode 100644 index 0000000000..b6144c2738 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe7--invalid-floating-point-state.md @@ -0,0 +1,83 @@ +--- +title: Bug Check 0xE7 INVALID_FLOATING_POINT_STATE +description: The INVALID_FLOATING_POINT_STATE bug check has a value of 0x000000E7. This indicates that a thread's saved floating-point state is invalid. +ms.assetid: 71a61132-cb7f-4618-b3d5-95602e52c098 +keywords: ["Bug Check 0xE7 INVALID_FLOATING_POINT_STATE", "INVALID_FLOATING_POINT_STATE"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_FLOATING_POINT_STATE +api_type: +- NA +--- + +# Bug Check 0xE7: INVALID\_FLOATING\_POINT\_STATE + + +The INVALID\_FLOATING\_POINT\_STATE bug check has a value of 0x000000E7. This indicates that a thread's saved floating-point state is invalid. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_FLOATING\_POINT\_STATE Parameters + + +Parameter 1 indicates which validity check failed. Parameter 4 is not used. The meaning of the other parameters depends on the value of Parameter 1. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Cause of Error

0x0

The flags field

0

The saved context flags field is invalid. Either FLOAT_SAVE_VALID is not set, or some reserved bits are nonzero.

0x1

The saved IRQL

The current IRQL

The current processor's IRQL is not the same as when the floating-point context was saved.

0x2

The saved address of the thread that owns this floating-point context

The current thread

The saved context does not belong to the current thread.

+ +  + +Cause +----- + +While restoring the previously-saved floating-point state for a thread, the state was found to be invalid. + +Parameter 1 indicates which validity check failed. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe8--invalid-cancel-of-file-open.md b/windows-driver-docs-pr/debugger/bug-check-0xe8--invalid-cancel-of-file-open.md new file mode 100644 index 0000000000..9e0c136136 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe8--invalid-cancel-of-file-open.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xE8 INVALID_CANCEL_OF_FILE_OPEN +description: The INVALID_CANCEL_OF_FILE_OPEN bug check has a value of 0x000000E8. This indicates that an invalid file object was passed to IoCancelFileOpen. +ms.assetid: 168d8b3a-62a0-4436-9e97-812ddfb8b7f7 +keywords: ["Bug Check 0xE8 INVALID_CANCEL_OF_FILE_OPEN", "INVALID_CANCEL_OF_FILE_OPEN"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- INVALID_CANCEL_OF_FILE_OPEN +api_type: +- NA +--- + +# Bug Check 0xE8: INVALID\_CANCEL\_OF\_FILE\_OPEN + + +The INVALID\_CANCEL\_OF\_FILE\_OPEN bug check has a value of 0x000000E8. This indicates that an invalid file object was passed to **IoCancelFileOpen**. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## INVALID\_CANCEL\_OF\_FILE\_OPEN Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The file object passed to IoCancelFileOpen

2

The device object passed to IoCancelFileOpen

3

Reserved

4

Reserved

+ +  + +Cause +----- + +The file object passed to **IoCancelFileOpen** is invalid. It should have reference of one. The driver that called **IoCancelFileOpen** is at fault. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xe9--active-ex-worker-thread-termination.md b/windows-driver-docs-pr/debugger/bug-check-0xe9--active-ex-worker-thread-termination.md new file mode 100644 index 0000000000..025610889b --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xe9--active-ex-worker-thread-termination.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xE9 ACTIVE_EX_WORKER_THREAD_TERMINATION +description: The ACTIVE_EX_WORKER_THREAD_TERMINATION bug check has a value of 0x000000E9. This indicates that an active executive worker thread is being terminated. +ms.assetid: dd68f07f-fab1-402c-9a81-f43722f91b69 +keywords: ["Bug Check 0xE9 ACTIVE_EX_WORKER_THREAD_TERMINATION", "ACTIVE_EX_WORKER_THREAD_TERMINATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ACTIVE_EX_WORKER_THREAD_TERMINATION +api_type: +- NA +--- + +# Bug Check 0xE9: ACTIVE\_EX\_WORKER\_THREAD\_TERMINATION + + +The ACTIVE\_EX\_WORKER\_THREAD\_TERMINATION bug check has a value of 0x000000E9. This indicates that an active executive worker thread is being terminated. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ACTIVE\_EX\_WORKER\_THREAD\_TERMINATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The exiting ETHREAD

2

Reserved

3

Reserved

4

Reserved

+ +  + +Cause +----- + +An executive worker thread is being terminated without having gone through the worker thread rundown code. This is forbidden; work items queued to the **ExWorkerQueue** must not terminate their threads. + +A stack trace should indicate the cause. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xea--thread-stuck-in-device-driver.md b/windows-driver-docs-pr/debugger/bug-check-0xea--thread-stuck-in-device-driver.md new file mode 100644 index 0000000000..d83f0f0dee --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xea--thread-stuck-in-device-driver.md @@ -0,0 +1,89 @@ +--- +title: Bug Check 0xEA THREAD_STUCK_IN_DEVICE_DRIVER +description: The THREAD_STUCK_IN_DEVICE_DRIVER bug check has a value of 0x000000EA. This indicates that a thread in a device driver is endlessly spinning. +ms.assetid: f3d6acaf-3445-4fc3-b4ed-b72a74a32b57 +keywords: ["Bug Check 0xEA THREAD_STUCK_IN_DEVICE_DRIVER", "THREAD_STUCK_IN_DEVICE_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- THREAD_STUCK_IN_DEVICE_DRIVER +api_type: +- NA +--- + +# Bug Check 0xEA: THREAD\_STUCK\_IN\_DEVICE\_DRIVER + + +The THREAD\_STUCK\_IN\_DEVICE\_DRIVER bug check has a value of 0x000000EA. This indicates that a thread in a device driver is endlessly spinning. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## THREAD\_STUCK\_IN\_DEVICE\_DRIVER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

A pointer to the stuck thread object

2

A pointer to the DEFERRED_WATCHDOG object

3

A pointer to the offending driver name

4

In the kernel debugger: The number of times the "intercepted" bug check 0xEA was hit

+

On the blue screen: 1

+ +  + +Cause +----- + +A device driver is spinning in an infinite loop, most likely waiting for hardware to become idle. + +This usually indicates problem with the hardware itself, or with the device driver programming the hardware incorrectly. Frequently, this is the result of a bad video card or a bad display driver. + +Resolution +---------- + +Use the [**.thread (Set Register Context)**](-thread--set-register-context-.md) command together with Parameter 1. Then use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) to find the location where the thread is stuck. + +If the kernel debugger is already connected and running when Windows detects a time-out condition. Then **DbgBreakPoint** will be called instead of **KeBugCheckEx**. A detailed message will be printed to the debugger. See [Sending Output to the Debugge](sending-output-to-the-debugger.md)for more information. + +This message will include what would have been the bug check parameters. Because no actual bug check was issued, the [**.bugcheck (Display Bug Check Data)**](-bugcheck--display-bug-check-data-.md) command will not be useful. The four parameters can also be retrieved from Watchdog's global variables by using **dd watchdog!g\_WdBugCheckData L5**" on a 32-bit system, or **dq watchdog!g\_WdBugCheckData L5**" on a 64-bit system. + +Debugging this error in an interactive manner such as this will enable you to find an offending thread, set breakpoints in it, and then use [**g (Go)**](g--go-.md) to return to the spinning code to debug it further. + +On multiprocessor machines (OS build 3790 or earlier), you can hit a time out if the spinning thread is interrupted by a hardware interrupt and an ISR or DPC routine is running at the time of the bug check. This is because the time out's work item can be delivered and handled on the second CPU and the same time. If this occurs, you must look deeper at the offending thread's stack to determine the spinning code which caused the time out to occur. Use the [**dds (Display Words and Symbols)**](dds--dps--dqs--display-words-and-symbols-.md) command to do this. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xeb--dirty-mapped-pages-congestion.md b/windows-driver-docs-pr/debugger/bug-check-0xeb--dirty-mapped-pages-congestion.md new file mode 100644 index 0000000000..91e941c70c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xeb--dirty-mapped-pages-congestion.md @@ -0,0 +1,91 @@ +--- +title: Bug Check 0xEB DIRTY_MAPPED_PAGES_CONGESTION +description: The DIRTY_MAPPED_PAGES_CONGESTION bug check has a value of 0x000000EB. This indicates that no free pages are available to continue operations. +ms.assetid: 7a73dc74-fe40-4c0c-9c33-b0af3709bf43 +keywords: ["Bug Check 0xEB DIRTY_MAPPED_PAGES_CONGESTION", "DIRTY_MAPPED_PAGES_CONGESTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DIRTY_MAPPED_PAGES_CONGESTION +api_type: +- NA +--- + +# Bug Check 0xEB: DIRTY\_MAPPED\_PAGES\_CONGESTION + + +The DIRTY\_MAPPED\_PAGES\_CONGESTION bug check has a value of 0x000000EB. This indicates that no free pages are available to continue operations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DIRTY\_MAPPED\_PAGES\_CONGESTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The total number of dirty pages

2

The number of dirty pages destined for the page file

3

Windows Server 2003 only: The size of the nonpaged pool available at the time of the bug check (in pages)

+

Windows Vista and later versions: Reserved

4

Windows Server 2003 only: The number of transition pages that are currently stranded

+

Windows Vista and later versions: The most recent modified write error status

+ +  + +Cause +----- + +The file system driver stack has deadlocked and most of the modified pages are destined for the file system. Because the file system is non-operational, the system has crashed because none of the modified pages can be reused without losing data. Any file system or filter driver in the stack may be at fault. + +To see general memory statistics, use the [**!vm 3**](-vm.md) extension. + +This bug check can occur for any of the following reasons: + +- A driver has blocked, deadlocking the modified or mapped page writers. Examples of this include mutex deadlocks or accesses to paged out memory in file system drivers or filter drivers. This indicates a driver bug. + + If Parameter 1 or Parameter 2 is large, this is a possibility. Use [**!vm 3**](-vm.md). + +- A storage driver is not processing requests. Examples of this are stranded queues and unresponsive drives. This indicates a driver bug. + + If Parameter 1 or Parameter 2 is large, this is a possibility. Use [**!process 0 7**](-process.md). + +- Windows Server 2003 only: Not enough pool is available for the storage stack to write out modified pages. This indicates a driver bug. + + If Parameter 3 is small, this is a possibility. Use [**!vm**](-vm.md) and [**!poolused 2**](-poolused.md). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xec--session-has-valid-special-pool-on-exit.md b/windows-driver-docs-pr/debugger/bug-check-0xec--session-has-valid-special-pool-on-exit.md new file mode 100644 index 0000000000..11999e10be --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xec--session-has-valid-special-pool-on-exit.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xEC SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT +description: The SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT bug check has a value of 0x000000EC. This indicates that a session unload occurred while a session driver still held memory. +ms.assetid: 0100684b-cde6-4f15-93da-78d200fa2f80 +keywords: ["Bug Check 0xEC SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT", "SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT +api_type: +- NA +--- + +# Bug Check 0xEC: SESSION\_HAS\_VALID\_SPECIAL\_POOL\_ON\_EXIT + + +The SESSION\_HAS\_VALID\_SPECIAL\_POOL\_ON\_EXIT bug check has a value of 0x000000EC. This indicates that a session unload occurred while a session driver still held memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SESSION\_HAS\_VALID\_SPECIAL\_POOL\_ON\_EXIT Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The session ID

2

The number of special pool pages that are leaking

3

Reserved

4

Reserved

+ +  + +Cause +----- + +This error is caused by a session driver not freeing its special pool allocations prior to a session unload. This indicates a bug in win32k.sys, atmfd.dll, rdpdd.dll, or a video driver. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xed--unmountable-boot-volume.md b/windows-driver-docs-pr/debugger/bug-check-0xed--unmountable-boot-volume.md new file mode 100644 index 0000000000..79343c8c88 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xed--unmountable-boot-volume.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0xED UNMOUNTABLE_BOOT_VOLUME +description: The UNMOUNTABLE_BOOT_VOLUME bug check has a value of 0x000000ED. This indicates that the I/O subsystem attempted to mount the boot volume and it failed. +ms.assetid: 7c4ab301-f110-4fc8-9ff8-242e0d2155fd +keywords: ["Bug Check 0xED UNMOUNTABLE_BOOT_VOLUME", "UNMOUNTABLE_BOOT_VOLUME"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- UNMOUNTABLE_BOOT_VOLUME +api_type: +- NA +--- + +# Bug Check 0xED: UNMOUNTABLE\_BOOT\_VOLUME + + +The UNMOUNTABLE\_BOOT\_VOLUME bug check has a value of 0x000000ED. This indicates that the I/O subsystem attempted to mount the boot volume and it failed. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## UNMOUNTABLE\_BOOT\_VOLUME Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The device object of the boot volume

2

The status code from the file system that describes why it failed to mount the volume

3

Reserved

4

Reserved

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xef--critical-process-died.md b/windows-driver-docs-pr/debugger/bug-check-0xef--critical-process-died.md new file mode 100644 index 0000000000..5f1aab796d --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xef--critical-process-died.md @@ -0,0 +1,110 @@ +--- +title: (Developer Content) Bug Check 0xEF CRITICAL_PROCESS_DIED +description: The CRITICAL_PROCESS_DIED bug check has a value of 0x000000EF. This indicates that a critical system process died. +ms.assetid: caa18221-6128-4d77-ab61-ef3c28cfba38 +keywords: ["(Developer Content) Bug Check 0xEF CRITICAL_PROCESS_DIED", "CRITICAL_PROCESS_DIED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRITICAL_PROCESS_DIED +api_type: +- NA +--- + +# (Developer Content) Bug Check 0xEF: CRITICAL\_PROCESS\_DIED + + +The CRITICAL\_PROCESS\_DIED bug check has a value of 0x000000EF. This indicates that a critical system process died. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CRITICAL\_PROCESS\_DIED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The process object

2

Reserved

3

Reserved

4

Reserved

+ +  + +Resolution +---------- + +Determining the cause of this issues typically requires the use of the debugger to gather additional information. Multiple dump files should be examined to see if this stop code has similar characteristics, such as the code that is running when the stop code appears. + +For more information, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md), [Using the !analyze Extension](using-the--analyze-extension.md) and [!analyze](-analyze.md). + +Use the event log to see if there are higher level events that occur leading up to this stop code. + +These general troubleshooting tips may be helpful. + +- If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available. + +- If new device drivers or system services have been added recently, try removing or updating them. Try to determine what changed in the system that caused the new bug check code to appear. + +- Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. For more information, see [Open Event Viewer](http://windows.microsoft.com/windows/what-information-event-logs-event-viewer#1TC=windows-7). Look for critical errors in the system log that occurred in the same time window as the blue screen. + +- Check with the manufacturer to see if an updated system BIOS or firmware is available. + +- You can try running the hardware diagnostics supplied by the system manufacturer. + +- Confirm that any new hardware that is installed is compatible with the installed version of Windows. For example, you can get information about required hardware at [Windows 10 Specifications](https://www.microsoft.com/windows/windows-10-specifications). + +- Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes. Make sure the virus detection program checks the Master Boot Record for infections. + +- Use the System File Checker tool to repair missing or corrupted system files. The System File Checker is a utility in Windows that allows users to scan for corruptions in Windows system files and restore corrupted files. Use the following command to run the System File Checker tool (SFC.exe). + + ``` + SFC /scannow + ``` + + For more information, see [Use the System File Checker tool to repair missing or corrupted system files](https://support.microsoft.com/kb/929833). + +- Look in **Device Manager** to see if any devices are marked with the exclamation point (!). Review the events log displayed in driver properties for any faulting driver. Try updating the related driver. + +## See also + + +[Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) + +[Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md) + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf--spin-lock-already-owned.md b/windows-driver-docs-pr/debugger/bug-check-0xf--spin-lock-already-owned.md new file mode 100644 index 0000000000..4861e753a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf--spin-lock-already-owned.md @@ -0,0 +1,49 @@ +--- +title: Bug Check 0xF SPIN_LOCK_ALREADY_OWNED +description: The SPIN_LOCK_ALREADY_OWNED bug check has a value of 0x0000000F. This indicates that a request for a spin lock has been initiated when the spin lock was already owned. +ms.assetid: 8347a78a-528e-4767-a13d-ad2fd8f71818 +keywords: ["Bug Check 0xF SPIN_LOCK_ALREADY_OWNED", "SPIN_LOCK_ALREADY_OWNED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SPIN_LOCK_ALREADY_OWNED +api_type: +- NA +--- + +# Bug Check 0xF: SPIN\_LOCK\_ALREADY\_OWNED + + +The SPIN\_LOCK\_ALREADY\_OWNED bug check has a value of 0x0000000F. This indicates that a request for a spin lock has been initiated when the spin lock was already owned. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SPIN\_LOCK\_ALREADY\_OWNED Parameters + + +None + +Cause +----- + +Typically, this error is caused by a recursive request for a spin lock. It can also occur if something similar to a recursive request for a spin lock has been initiated--for example, when a spin lock has been acquired by a thread, and then that same thread calls a function, which also tries to acquire a spin lock. The second attempt to acquire a spin lock is not blocked in this case because doing so would result in an unrecoverable deadlock. If the calls are made on more than one processor, then one processor will be blocked until the other processor releases the lock. + +This error can also occur, without explicit recursion, when all threads and all spin locks are assigned an IRQL. Spin lock IRQLs are always greater than or equal to DPC level, but this is not true for threads. However, a thread that is holding a spin lock must maintain an IRQL greater than or equal to that of the spin lock. Decreasing the thread IRQL below the IRQL level of the spin lock that it is holding allows another thread to be scheduled on the processor. This new thread could then attempt to acquire the same spin lock. + +Resolution +---------- + +Ensure that you are not recursively acquiring the lock. And, for threads that hold a spin lock, ensure that you are not decreasing the thread IRQL to a level below the IRQL of the spin lock that it is holding. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf1--scsi-verifier-detected-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xf1--scsi-verifier-detected-violation.md new file mode 100644 index 0000000000..e23ea00fb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf1--scsi-verifier-detected-violation.md @@ -0,0 +1,167 @@ +--- +title: Bug Check 0xF1 SCSI_VERIFIER_DETECTED_VIOLATION +description: The SCSI_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000F1. This is the bug check code for all Driver Verifier SCSI Verification violations. +ms.assetid: babc33f9-a467-4b19-b1a2-1898d0224d4d +keywords: ["Bug Check 0xF1 SCSI_VERIFIER_DETECTED_VIOLATION", "SCSI_VERIFIER_DETECTED_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SCSI_VERIFIER_DETECTED_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xF1: SCSI\_VERIFIER\_DETECTED\_VIOLATION + + +The SCSI\_VERIFIER\_DETECTED\_VIOLATION bug check has a value of 0x000000F1. This is the bug check code for all Driver Verifier **SCSI Verification** violations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## SCSI\_VERIFIER\_DETECTED\_VIOLATION Parameters + + +Parameter 1 identifies the type of violation. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x1000

First argument passed

Second argument passed

Reserved

The miniport driver passed bad arguments to ScsiPortInitialize.

0x1001

Delay, in microseconds

Reserved

Reserved

The miniport driver called ScsiPortStallExecution and specified a delay greater than 0.1 second, stalling the processor too long.

0x1002

Address of routine that took too long

Address of miniport's HW_DEVICE_EXTENSION

Duration of the routine, in microseconds

A miniport routine called by the port driver took longer than 0.5 second to execute.

+

(0.5 seconds is the limit for most routines. However, the HwInitialize routine is allowed 5 seconds, and the FindAdapter routine is exempt.)

0x1003

Address of miniport's HW_DEVICE_EXTENSION

Address of the SRB

Reserved

The miniport driver completed a request more than once.

0x1004

Address of the SRB

Address of miniport's HW_DEVICE_EXTENSION

Reserved

The miniport driver completed a request with an invalid SRB status.

0x1005

Address of miniport's HW_DEVICE_EXTENSION

Address of LOGICAL_UNIT_EXTENSION

Reserved

The miniport driver called ScsiPortNotification to ask for NextLuRequest, but an untagged request is still active.

0x1006

Address of miniport's HW_DEVICE_EXTENSION

Invalid virtual address

Reserved

The miniport driver passed an invalid virtual address to ScsiPortGetPhysicalAddress.

+

(This usually means the address supplied doesn't map to the common buffer area.)

0x1007

Address of ADAPTER_EXTENSION

Address of miniport's HW_DEVICE_EXTENSION

Reserved

The reset hold period for the bus ended, but the miniport driver still has outstanding requests.

0x2001

Delay, in microseconds

Reserved

Reserved

The Storport miniport driver called [StorPortStallExecution](https://msdn.microsoft.com/library/windows/hardware/ff567508) and specified a delay longer than 0.1 second, stalling the processor for an excessive length of time.

0x2002

Reserved

Reserved

Reserved

[StorPortGetUncachedExtension](https://msdn.microsoft.com/library/windows/hardware/ff567103) was not called from the miniport driver's [HwStorFindAdapter](https://msdn.microsoft.com/library/windows/hardware/ff557390) routine. The StorPortGetUncachedExtension routine can only be called from the miniport driver's HwStorFindAdapter routine and only for a bus-master adapter. A Storport miniport driver must set the SrbExtensionSize of the [HW_INITIALIZATION_DATA](https://msdn.microsoft.com/library/windows/hardware/ff557459) (Storport) structure before calling StorPortGetUncachedExtension.

0x2003

Reserved

Reserved

Reserved

An invalid address was passed to the [StorPortGetDeviceBase](https://msdn.microsoft.com/library/windows/hardware/ff567080) routine. The StorPortGetDeviceBase routine supports only those addresses that were assigned to the driver by the system Plug and Play (PnP) manager.

0x2004

Reserved

Reserved

Reserved

The Storport miniport driver completed the same I/O request more than once.

0x2005

Reserved

Reserved

Reserved

The Storport miniport driver passed an invalid virtual address to one of the StorPortReadxxx or StorPortWritexxx routines. This usually means the address supplied doesn't map to the common buffer area. The specified Register or Port must be in mapped memory-space range returned by [StorPortGetDeviceBase](https://msdn.microsoft.com/library/windows/hardware/ff567080) routine.

+ +  + +Cause +----- + +See the description of each code in the Parameters section for an explanation of the cause. + +Resolution +---------- + +This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it. You might consider removing the driver which caused this problem as well. + +If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code. + +The Driver Verifier **SCSI Verification** option is available only in Windows XP and later. The Driver Verifier **Storport Verification** option is available only in Windows 7 and later. For full details on Driver Verifier, see the Windows Driver Kit. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf2--hardware-interrupt-storm.md b/windows-driver-docs-pr/debugger/bug-check-0xf2--hardware-interrupt-storm.md new file mode 100644 index 0000000000..ff8d1708bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf2--hardware-interrupt-storm.md @@ -0,0 +1,76 @@ +--- +title: Bug Check 0xF2 HARDWARE_INTERRUPT_STORM +description: The HARDWARE_INTERRUPT_STORM bug check has a value of 0x000000F2. This indicates that the kernel detected an interrupt storm. +ms.assetid: 04751AB2-E9B3-40AD-A872-8DDA9B96C6CA +keywords: ["Bug Check 0xF2 HARDWARE_INTERRUPT_STORM", "HARDWARE_INTERRUPT_STORM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HARDWARE_INTERRUPT_STORM +api_type: +- NA +--- + +# Bug Check 0xF2: HARDWARE\_INTERRUPT\_STORM + + +The HARDWARE\_INTERRUPT\_STORM bug check has a value of 0x000000F2. This indicates that the kernel detected an interrupt storm. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## HARDWARE\_INTERRUPT\_STORM Parameters + + +| Parameter | Description | +|-----------|-------------------------------------------------------------------------------------------| +| 1 | Address of the ISR (or first ISR in the chain) connected to the storming interrupt vector | +| 2 | ISR context value | +| 3 | Address of the interrupt object for the storming interrupt vector | +| 4 | 0x1 if the ISR is not chained, 0x2 if the ISR is chained | + +  + +Cause +----- + +This bugcheck indicates that the kernel has detected an interrupt storm. An interrupt storm is defined as a level triggered interrupt signal staying in the asserted state. This is fatal to the system in the manner that the system will hard hang, or "bus lock". + +This can happen because of the following: + +- A piece of hardware does not release its interrupt signal after being told to do so by the device driver. +- A device driver does not instruct its hardware to release the interrupt signal because it does not believe the interrupt was initiated from its hardware. +- A device driver claims the interrupt even though the interrupt was not initiated from its hardware. Note that this can only occur when multiple devices are sharing the same IRQ. +- The ELCR (edge level control register) is set incorrectly. +- Edge and Level interrupt triggered devices share an IRQ (e.g. COM port and PCI SCSI controller). + +All of these cases will instantly hard hang your system. Instead of hard hanging the system, this bugcheck is initiated since in many cases it can identify the culprit. + +When the bugcheck occurs, the module containing the ISR (interrupt service routine) of the storming IRQ is displayed on the screen. This is an example of what you would see: + +``` +*** STOP: 0x000000F2 (0xFCA7C55C, 0x817B9B28, 0x817D2AA0, 0x00000002) +An interrupt storm has caused the system to hang. +*** Address FCA7C55C base at FCA72000, Datestamp 3A72BDEF - ACPI.sys +``` + +In the event the fourth parameter is a 0x00000001, the module pointed to is very likely the culprit. Either the driver is broken, or the hardware is malfunctioning. + +In the event the fourth parameter is a 0x00000002, the module pointed to is the first ISR in the chain, and is never guaranteed to be the culprit. + +Resolution +---------- + +A user experiencing this bugcheck repeatedly should try to isolate the problem by looking for devices that are on the same IRQ as the one for which the module is a driver for (in this case, the same IRQ that ACPI is using). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf3--disorderly-shutdown.md b/windows-driver-docs-pr/debugger/bug-check-0xf3--disorderly-shutdown.md new file mode 100644 index 0000000000..ea30a60450 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf3--disorderly-shutdown.md @@ -0,0 +1,77 @@ +--- +title: Bug Check 0xF3 DISORDERLY_SHUTDOWN +description: The DISORDERLY_SHUTDOWN bug check has a value of 0x000000F3. This indicates that Windows was unable to shut down due to lack of memory. +ms.assetid: e113cd2f-96b2-43b8-a67e-a851cc5c0da8 +keywords: ["Bug Check 0xF3 DISORDERLY_SHUTDOWN", "DISORDERLY_SHUTDOWN"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DISORDERLY_SHUTDOWN +api_type: +- NA +--- + +# Bug Check 0xF3: DISORDERLY\_SHUTDOWN + + +The DISORDERLY\_SHUTDOWN bug check has a value of 0x000000F3. This indicates that Windows was unable to shut down due to lack of memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DISORDERLY\_SHUTDOWN Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The total number of dirty pages

2

The number of dirty pages destined for the page file

3

Windows Server 2003 only: The size of the nonpaged pool available at the time of the bug check (in pages)

+

Windows Vista and later: Reserved

4

Windows Server 2003 only: The current shut down stage

+

Windows Vista and later: The most recent modified write error status

+ +  + +Cause +----- + +Windows attempted to shut down, but there were no free pages available to continue operations. + +Because applications were not terminated and drivers were not unloaded, they continued to access pages even after the modified writer had terminated. This causes the system to run out of pages, since the page files could be used. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf4--critical-object-termination.md b/windows-driver-docs-pr/debugger/bug-check-0xf4--critical-object-termination.md new file mode 100644 index 0000000000..0992f345ad --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf4--critical-object-termination.md @@ -0,0 +1,75 @@ +--- +title: Bug Check 0xF4 CRITICAL_OBJECT_TERMINATION +description: The CRITICAL_OBJECT_TERMINATION bug check has a value of 0x000000F4. This indicates that a process or thread crucial to system operation has unexpectedly exited or been terminated. +ms.assetid: 51a73ada-5e82-45a2-ad2a-8ef53f96318c +keywords: ["Bug Check 0xF4 CRITICAL_OBJECT_TERMINATION", "CRITICAL_OBJECT_TERMINATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CRITICAL_OBJECT_TERMINATION +api_type: +- NA +--- + +# Bug Check 0xF4: CRITICAL\_OBJECT\_TERMINATION + + +The CRITICAL\_OBJECT\_TERMINATION bug check has a value of 0x000000F4. This indicates that a process or thread crucial to system operation has unexpectedly exited or been terminated. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## CRITICAL\_OBJECT\_TERMINATION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The terminating object type:

+

0x3: Process

+

0x6: Thread

2

The terminating object

3

The process image file name

4

Pointer to an ASCII string containing an explanatory message

+ +  + +Cause +----- + +Several processes and threads are necessary for the operation of the system. When they are terminated for any reason, the system can no longer function. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf5--fltmgr-file-system.md b/windows-driver-docs-pr/debugger/bug-check-0xf5--fltmgr-file-system.md new file mode 100644 index 0000000000..2c7ba03008 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf5--fltmgr-file-system.md @@ -0,0 +1,136 @@ +--- +title: Bug Check 0xF5 FLTMGR_FILE_SYSTEM +description: The FLTMGR_FILE_SYSTEM bug check has a value of 0x000000F5. This indicates that an unrecoverable failure occurred in the Filter Manager. +ms.assetid: 9b008c76-65c8-4de4-b7a0-96d8732c7b7e +keywords: ["Bug Check 0xF5 FLTMGR_FILE_SYSTEM", "FLTMGR_FILE_SYSTEM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- FLTMGR_FILE_SYSTEM +api_type: +- NA +--- + +# Bug Check 0xF5: FLTMGR\_FILE\_SYSTEM + + +The FLTMGR\_FILE\_SYSTEM bug check has a value of 0x000000F5. This indicates that an unrecoverable failure occurred in the Filter Manager. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## FLTMGR\_FILE\_SYSTEM Parameters + + +Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of error

0x66

Pointer to the callback data structure for the operation.

0

0

The minifilter returned FLT_PREOP_SUCCESS_WITH_CALLBACK or FLT_PREOP_SYNCHRONIZE from a preoperation callback, but did not register a corresponding postoperation callback.

0x67

Pointer to the callback data structure for the operation.

0

Error NTSTATUS code for the operation

An internal object ran out of space, and the system is unable to allocate new space.

0x68

Reserved

Address of the FLT_FILE_NAME_INFORMATIONN structure

Reserved

A FLT_FILE_NAME_INFORMATION structure was dereferenced too many times.

0x6A

File object pointer for the file.

0

0

The file-open or file-create request could not be canceled, because one or more handles have been created for the file.

0x6B

Frame ID

0

Thread

Invalid BACKPOCKET IRPCTRL state.

0x6C

Frame ID

BackPocket List

Thread

Too many nested PageFaults for BACKPOCKETED IRPCTR.

0x6D

Address of the minifilter's context structure

Address of the CONTEXT_NODE structure

0

The context structure was dereferenced too many times. This means that the reference count on the Filter Manager's CONTEXT_NODE structure went to zero while it was still attached to its associated object.

0x6E

Address of the minifilter's context structure

Address of the CONTEXT_NODE structure

0

The context structure was referenced after being freed.

+ +  + +Cause +----- + +The cause of the problem is indicated by the value of Parameter 1. See the table in the Parameters section. + +Resolution +---------- + +If Parameter 1 equals **0x66**, you can debug this problem by verifying that your minifilter driver has registered a post-operation callback for this operation. The current operation can be found in the callback data structure. (See Parameter 2.) Use the **!fltkd.cbd** debugger extension. + +If Parameter 1 equals **0x67**, you should verify that you do not have a nonpaged pool leak somewhere in the system. + +If Parameter 1 equals **0x6A**, make sure that your minifilter driver does not reference this file object (see Parameter 2) to get a handle at any point during your minifilter's processing of this operation. + +If Parameter 1 equals **0x6B** or **0x6C**, then a non-recoverable internal state error has occurred which will cause the operating system to bug check. + +If Parameter 1 equals **0x6D**, make sure that your minifilter driver does not call **FltReleaseContext** too many times for the given context (see Parameter 2). + +If Parameter 1 equals 0x6E, make sure that your minifilter driver does not call **FltReferenceContext** after the given context has been deleted (see Parameter 2). + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf6--pci-verifier-detected-violation.md b/windows-driver-docs-pr/debugger/bug-check-0xf6--pci-verifier-detected-violation.md new file mode 100644 index 0000000000..80a82b5b36 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf6--pci-verifier-detected-violation.md @@ -0,0 +1,71 @@ +--- +title: Bug Check 0xF6 PCI_VERIFIER_DETECTED_VIOLATION +description: The PCI_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000F6. This indicates that an error occurred in the BIOS or another device being verified by the PCI driver. +ms.assetid: 8d2be46d-52fd-41dc-b33c-67fea7e0e501 +keywords: ["Bug Check 0xF6 PCI_VERIFIER_DETECTED_VIOLATION", "PCI_VERIFIER_DETECTED_VIOLATION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PCI_VERIFIER_DETECTED_VIOLATION +api_type: +- NA +--- + +# Bug Check 0xF6: PCI\_VERIFIER\_DETECTED\_VIOLATION + + +The PCI\_VERIFIER\_DETECTED\_VIOLATION bug check has a value of 0x000000F6. This indicates that an error occurred in the BIOS or another device being verified by the PCI driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## PCI\_VERIFIER\_DETECTED\_VIOLATION Parameters + + +Parameter 1 is the only parameter of interest; this identifies the nature of the failure detected. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Parameter 1Cause of Error

0x01

An active bridge was reprogrammed by the BIOS during a docking event.

0x02

The PMCSR register was not updated within the spec-mandated time.

0x03

A driver has written to Windows-controlled portions of a PCI device's configuration space.

+ +  + +Cause +----- + +The PCI driver detected an error in a device or BIOS being verified. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf7--driver-overran-stack-buffer.md b/windows-driver-docs-pr/debugger/bug-check-0xf7--driver-overran-stack-buffer.md new file mode 100644 index 0000000000..b7a08cceec --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf7--driver-overran-stack-buffer.md @@ -0,0 +1,82 @@ +--- +title: Bug Check 0xF7 DRIVER_OVERRAN_STACK_BUFFER +description: The DRIVER_OVERRAN_STACK_BUFFER bug check has a value of 0x000000F7. This indicates that a driver has overrun a stack-based buffer. +ms.assetid: 5981b5e0-90c1-486e-8bbf-2778f2595f6b +keywords: ["Bug Check 0xF7 DRIVER_OVERRAN_STACK_BUFFER", "DRIVER_OVERRAN_STACK_BUFFER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_OVERRAN_STACK_BUFFER +api_type: +- NA +--- + +# Bug Check 0xF7: DRIVER\_OVERRAN\_STACK\_BUFFER + + +The DRIVER\_OVERRAN\_STACK\_BUFFER bug check has a value of 0x000000F7. This indicates that a driver has overrun a stack-based buffer. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_OVERRAN\_STACK\_BUFFER Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The actual security check cookie from the stack

2

The expected security check cookie

3

The bit-complement of the expected security check cookie

4

0

+ +  + +Cause +----- + +A driver overran a stack-based buffer (or local variable) in a way that would have overwritten the function's return address and jumped back to an arbitrary address when the function returned. + +This is the classic "buffer overrun" hacking attack. The system has been brought down to prevent a malicious user from gaining complete control of it. + +Resolution +---------- + +Use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command to get a stack trace. + +The last routine on the stack before the buffer overrun handlers and bug check call is the one that overran its local variable. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf8--ramdisk-boot-initialization-failed.md b/windows-driver-docs-pr/debugger/bug-check-0xf8--ramdisk-boot-initialization-failed.md new file mode 100644 index 0000000000..6c0162b338 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf8--ramdisk-boot-initialization-failed.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xF8 RAMDISK_BOOT_INITIALIZATION_FAILED +description: The RAMDISK_BOOT_INITIALIZATION_FAILED bug check has a value of 0x000000F8. This indicates that an initialization failure occurred while attempting to boot from the RAM disk. +ms.assetid: 73b053af-6ecb-48a3-b09d-e28d39390d11 +keywords: ["Bug Check 0xF8 RAMDISK_BOOT_INITIALIZATION_FAILED", "RAMDISK_BOOT_INITIALIZATION_FAILED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RAMDISK_BOOT_INITIALIZATION_FAILED +api_type: +- NA +--- + +# Bug Check 0xF8: RAMDISK\_BOOT\_INITIALIZATION\_FAILED + + +The RAMDISK\_BOOT\_INITIALIZATION\_FAILED bug check has a value of 0x000000F8. This indicates that an initialization failure occurred while attempting to boot from the RAM disk. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RAMDISK\_BOOT\_INITIALIZATION\_FAILED Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Indicates the cause of the failure.

+

1: No LoaderXIPRom descriptor was found in the loader memory list.

+

2: Unable to open the RAM disk driver (ramdisk.sys or \Device\Ramdisk).

+

3: FSCTL_CREATE_RAM_DISK failed.

+

4: Unable to create GUID string from binary GUID.

+

5: Unable to create symbolic link pointing to the RAM disk device.

2

NTSTATUS code

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xf9--driver-returned-status-reparse-for-volume-open.md b/windows-driver-docs-pr/debugger/bug-check-0xf9--driver-returned-status-reparse-for-volume-open.md new file mode 100644 index 0000000000..db3b38d93c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xf9--driver-returned-status-reparse-for-volume-open.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xF9 DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN +description: The DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN bug check that indicates that a driver returned STATUS_REPARSE to an IRP_MJ_CREATE request with no trailing names. +ms.assetid: 60eeb24a-accf-4db8-ba5b-1738a9aa4b46 +keywords: ["Bug Check 0xF9 DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN", "DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN +api_type: +- NA +--- + +# Bug Check 0xF9: DRIVER\_RETURNED\_STATUS\_REPARSE\_FOR\_VOLUME\_OPEN + + +The DRIVER\_RETURNED\_STATUS\_REPARSE\_FOR\_VOLUME\_OPEN bug check has a value of 0x000000F9. This indicates that a driver returned STATUS\_REPARSE to an IRP\_MJ\_CREATE request with no trailing names. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DRIVER\_RETURNED\_STATUS\_REPARSE\_FOR\_VOLUME\_OPEN Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The device object that was opened

2

The device object to which the IRP_MJ_CREATE request was issued

3

Address of the Unicode string containing the new name of the file (to be reparsed)

4

Information returned by the driver for the IRP_MJ_CREATE request

+ +  + +Remarks +------- + +STATUS\_REPARSE should be returned only for IRP\_MJ\_CREATE requests with trailing names, as that indicates the driver is supporting name spaces. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xfa---http-driver-corrupted.md b/windows-driver-docs-pr/debugger/bug-check-0xfa---http-driver-corrupted.md new file mode 100644 index 0000000000..53d0fbbeeb --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xfa---http-driver-corrupted.md @@ -0,0 +1,67 @@ +--- +title: Bug Check 0xFA HTTP_DRIVER_CORRUPTED +description: The HTTP_DRIVER_CORRUPTED bug check has a value of 0x000000FA. This indicates that the HTTP kernel driver (Http.sys) has reached a corrupted state and cannot recover. +ms.assetid: f7e3c1bf-2259-4aa6-af19-267b537dedfe +keywords: ["Bug Check 0xFA HTTP_DRIVER_CORRUPTED", "HTTP_DRIVER_CORRUPTED"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- HTTP_DRIVER_CORRUPTED +api_type: +- NA +--- + +# Bug Check 0xFA: HTTP\_DRIVER\_CORRUPTED + + +The HTTP\_DRIVER\_CORRUPTED bug check has a value of 0x000000FA. This indicates that the HTTP kernel driver (Http.sys) has reached a corrupted state and cannot recover. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## HTTP\_DRIVER\_CORRUPTED Parameters + + +Parameter 1 identifies the exact state of the HTTP kernel driver. + + +++++++ + + + + + + + + + + + + + + + + + + +
Parameter 1Parameter 2Parameter 3Parameter 4Cause of Error

0x1

Address of work item

Name of the file that contains the work item check

Line number of the work item check within the file

A work item is invalid. This will eventually result in thread pool corruption and an access violation.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xfc---attempted-execute-of-noexecute-memory.md b/windows-driver-docs-pr/debugger/bug-check-0xfc---attempted-execute-of-noexecute-memory.md new file mode 100644 index 0000000000..3b7f52e1a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xfc---attempted-execute-of-noexecute-memory.md @@ -0,0 +1,73 @@ +--- +title: Bug Check 0xFC ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY +description: The ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY bug check has a value of 0x000000FC. This indicates that an attempt was made to execute non-executable memory. +ms.assetid: bece76bd-03ca-40fd-a69b-f6cc05d09806 +keywords: ["Bug Check 0xFC ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY", "ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY +api_type: +- NA +--- + +# Bug Check 0xFC: ATTEMPTED\_EXECUTE\_OF\_NOEXECUTE\_MEMORY + + +The ATTEMPTED\_EXECUTE\_OF\_NOEXECUTE\_MEMORY bug check has a value of 0x000000FC. This indicates that an attempt was made to execute non-executable memory. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## ATTEMPTED\_EXECUTE\_OF\_NOEXECUTE\_MEMORY Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The virtual address whose execution was attempted

2

The contents of the page table entry (PTE)

3

Reserved

4

Reserved

+ +  + +Resolution +---------- + +When possible, the Unicode string of the driver name that attempted to execute non-executable memory is printed on the bug check screen and is also saved in **KiBugCheckDriver**. Otherwise, the driver in question can often be found by running a stack trace and then reviewing the current instruction pointer. + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xfd---dirty-nowrite-pages-congestion.md b/windows-driver-docs-pr/debugger/bug-check-0xfd---dirty-nowrite-pages-congestion.md new file mode 100644 index 0000000000..72a007a75c --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xfd---dirty-nowrite-pages-congestion.md @@ -0,0 +1,78 @@ +--- +title: Bug Check 0xFD DIRTY_NOWRITE_PAGES_CONGESTION +description: The DIRTY_NOWRITE_PAGES_CONGESTION bug check has a value of 0x000000FD. This indicates that there are no free pages available to continue basic system operations. +ms.assetid: b657fffe-8331-4b4f-9d29-fea8ee1e1682 +keywords: ["Bug Check 0xFD DIRTY_NOWRITE_PAGES_CONGESTION", "DIRTY_NOWRITE_PAGES_CONGESTION"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DIRTY_NOWRITE_PAGES_CONGESTION +api_type: +- NA +--- + +# Bug Check 0xFD: DIRTY\_NOWRITE\_PAGES\_CONGESTION + + +The DIRTY\_NOWRITE\_PAGES\_CONGESTION bug check has a value of 0x000000FD. This indicates that there are no free pages available to continue basic system operations. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## DIRTY\_NOWRITE\_PAGES\_CONGESTION Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

Total number of dirty pages

2

Number of non-writeable dirty pages

3

Reserved

4

Most recently modified write-error status

+ +  + +Cause +----- + +This bug check usually occurs because the component that owns the modified non-writeable pages failed to write out these pages after marking the relevant files as "do not write" to memory management. This indicates a driver bug. + +Resolution +---------- + +For more information about which driver is causing the problem, use the [**!vm 3**](-vm.md) extension, followed by [**!memusage 1**](-memusage.md) . + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xfe--bugcode-usb-driver.md b/windows-driver-docs-pr/debugger/bug-check-0xfe--bugcode-usb-driver.md new file mode 100644 index 0000000000..5b35e87ed7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xfe--bugcode-usb-driver.md @@ -0,0 +1,227 @@ +--- +title: Bug Check 0xFE BUGCODE_USB_DRIVER +description: The BUGCODE_USB_DRIVER bug check has a value of 0x000000FE. This indicates that an error has occurred in a universal serial bus (USB) driver. +ms.assetid: 830f9d11-4b16-41a9-a804-6d689a779278 +keywords: ["Bug Check 0xFE BUGCODE_USB_DRIVER", "BUGCODE_USB_DRIVER"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- BUGCODE_USB_DRIVER +api_type: +- NA +--- + +# Bug Check 0xFE: BUGCODE\_USB\_DRIVER + + +The BUGCODE\_USB\_DRIVER bug check has a value of 0x000000FE. This indicates that an error has occurred in a universal serial bus (USB) driver. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## BUGCODE\_USB\_DRIVER Parameters + + +Parameter 1 identifies the type of violation. + +Parameter 1 +Parameter 2 +Parameter 3 +Parameter 4 +Cause of Error +0x1 + +Reserved + +Reserved + +Reserved + +An internal error has occurred in the USB stack. + +0x2 + +Address of the pending IRP + +Address of the IRP that was passed in + +Address of the USB request block (URB) that caused the error + +The USB client driver has submitted a URB that is still attached to another IRP pending in the bus driver. + +0x3 + +Reserved + +Reserved + +Reserved + +The USB miniport driver has generated a bug check. This usually happens in response to a hardware failure. + +0x4 + +Address of the IRP + +Address of the URB + +Reserved + +The caller has submitted an IRP that is already pending in the USB bus driver. + +0x5 + +Device extension pointer of the host controller + +PCI vendor, product id for the controller + +Pointer to endpoint data structure + +A hardware failure has occurred because of a bad physical address found in a hardware data structure. + +0x6 + +Object address + +Signature that was expected + +Reserved + +An internal data structure (object) is corrupted. + +0x7 + +Pointer to usbport.sys debug log + +Message string + +File name + +Please see the provided message string for detailed information. + +0x8 + +1 + +Reserved + +Reserved + +Reserved + +2 + +Device object + +IRP + +An IRP was received by the hub driver that it does not expect or has not registered for. + +3 + +Reserved + +Reserved + +Reserved + +4 + +PDO if Parameter 3 is not NULL. Context if Parameter 3 is NULL. + +Context or NULL + +Fatal PDO trap + +5 + +Reserved + +Reserved + +Reserved + +6 + +Time-out code. See the following table. + +Time-out code context: port data + +Fatal time-out + +  + +If Parameter 1 has a value of 8 and Parameter 2 has a value of 6, then Parameter 3 is a time-out code. Possible values for the time-out code are given in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Time-out codeMeaning

0

Non-fatal time-out

1

Failed resuming a suspended port.

2

Timed out waiting for a reset, initiated by a client driver, to complete before suspending the port.

3

Timed out waiting for the port to complete resume before suspending it.

4

Timed out waiting for the port-change state machine to be disabled prior to suspending the port.

5

Timed out waiting for a suspend-port request to complete.

6

Timed out waiting for the port-change state machine to be disabled.

7

Timed out waiting for the port-change state machine to be closed.

8

Timed out waiting for the hub to resume from selective suspend.

9

Timed out waiting for the hub to resume from selective suspend prior to system suspend.

10

Timed out waiting for port-change state machine to become idle.

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-0xff---reserve-queue-overflow.md b/windows-driver-docs-pr/debugger/bug-check-0xff---reserve-queue-overflow.md new file mode 100644 index 0000000000..6f895f1e77 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-0xff---reserve-queue-overflow.md @@ -0,0 +1,68 @@ +--- +title: Bug Check 0xFF RESERVE_QUEUE_OVERFLOW +description: The RESERVE_QUEUE_OVERFLOW bug check has a value of 0x000000FF. This indicates that an attempt was made to insert a new item into a reserve queue, causing the queue to overflow. +ms.assetid: d327ea41-c568-49f6-8b37-183533fd6261 +keywords: ["Bug Check 0xFF RESERVE_QUEUE_OVERFLOW", "RESERVE_QUEUE_OVERFLOW"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- RESERVE_QUEUE_OVERFLOW +api_type: +- NA +--- + +# Bug Check 0xFF: RESERVE\_QUEUE\_OVERFLOW + + +The RESERVE\_QUEUE\_OVERFLOW bug check has a value of 0x000000FF. This indicates that an attempt was made to insert a new item into a reserve queue, causing the queue to overflow. + +**Important** This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://windows.microsoft.com/windows-10/troubleshoot-blue-screen-errors). + +## RESERVE\_QUEUE\_OVERFLOW Parameters + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

1

The address of the reserve queue

2

The size of the reserve queue

3

0

4

0

+ +  + +  + +  + + + + diff --git a/windows-driver-docs-pr/debugger/bug-check-code-reference2.md b/windows-driver-docs-pr/debugger/bug-check-code-reference2.md new file mode 100644 index 0000000000..cf9c60692e --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-check-code-reference2.md @@ -0,0 +1,388 @@ +--- +title: Bug Check Code Reference +description: This section contains descriptions of the common bug checks, including the parameters passed to the blue screen. +ms.assetid: DBA85578-97CF-4BD7-A67D-1C7AD2E9B2BB +--- + +# Bug Check Code Reference + + +This section contains descriptions of the common bug checks, including the parameters passed to the blue screen. It also describes how you can diagnose the fault which led to the bug check, and possible ways to deal with the error. + +**Note**  This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://go.microsoft.com/fwlink/p/?linkid=183646). + +  + +If a specific bug check code does not appear in this reference, use the [**!analyze**](-analyze.md) extension command (in kernel mode) with the following syntax: + +**!analyze -show** *Code*. + +This will display information about the specified bug check. If your default radix is not 16, you should prefix *Code* with "0x". + +The following table shows the code and name of each bug check. + +| Code | Name | +|------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| 0x00000001 | [**APC\_INDEX\_MISMATCH**](bug-check-0x1--apc-index-mismatch.md) | +| 0x00000002 | [**DEVICE\_QUEUE\_NOT\_BUSY**](bug-check-0x2--device-queue-not-busy.md) | +| 0x00000003 | [**INVALID\_AFFINITY\_SET**](bug-check-0x3--invalid-affinity-set.md) | +| 0x00000004 | [**INVALID\_DATA\_ACCESS\_TRAP**](bug-check-0x4--invalid-data-access-trap.md) | +| 0x00000005 | [**INVALID\_PROCESS\_ATTACH\_ATTEMPT**](bug-check-0x5--invalid-process-attach-attempt.md) | +| 0x00000006 | [**INVALID\_PROCESS\_DETACH\_ATTEMPT**](bug-check-0x6--invalid-process-detach-attempt.md) | +| 0x00000007 | [**INVALID\_SOFTWARE\_INTERRUPT**](bug-check-0x7--invalid-software-interrupt.md) | +| 0x00000008 | [**IRQL\_NOT\_DISPATCH\_LEVEL**](bug-check-0x8--irql-not-dispatch-level.md) | +| 0x00000009 | [**IRQL\_NOT\_GREATER\_OR\_EQUAL**](bug-check-0x9--irql-not-greater-or-equal.md) | +| 0x0000000A | [**IRQL\_NOT\_LESS\_OR\_EQUAL**](bug-check-0xa--irql-not-less-or-equal.md) | +| 0x0000000B | [**NO\_EXCEPTION\_HANDLING\_SUPPORT**](bug-check-0xb--no-exception-handling-support.md) | +| 0x0000000C | [**MAXIMUM\_WAIT\_OBJECTS\_EXCEEDED**](bug-check-0xc--maximum-wait-objects-exceeded.md) | +| 0x0000000D | [**MUTEX\_LEVEL\_NUMBER\_VIOLATION**](bug-check-0xd--mutex-level-number-violation.md) | +| 0x0000000E | [**NO\_USER\_MODE\_CONTEXT**](bug-check-0xe--no-user-mode-context.md) | +| 0x0000000F | [**SPIN\_LOCK\_ALREADY\_OWNED**](bug-check-0xf--spin-lock-already-owned.md) | +| 0x00000010 | [**SPIN\_LOCK\_NOT\_OWNED**](bug-check-0x10--spin-lock-not-owned.md) | +| 0x00000011 | [**THREAD\_NOT\_MUTEX\_OWNER**](bug-check-0x11--thread-not-mutex-owner.md) | +| 0x00000012 | [**TRAP\_CAUSE\_UNKNOWN**](bug-check-0x12--trap-cause-unknown.md) | +| 0x00000013 | [**EMPTY\_THREAD\_REAPER\_LIST**](bug-check-0x13--empty-thread-reaper-list.md) | +| 0x00000014 | [**CREATE\_DELETE\_LOCK\_NOT\_LOCKED**](bug-check-0x14--create-delete-lock-not-locked.md) | +| 0x00000015 | [**LAST\_CHANCE\_CALLED\_FROM\_KMODE**](bug-check-0x15--last-chance-called-from-kmode.md) | +| 0x00000016 | [**CID\_HANDLE\_CREATION**](bug-check-0x16--cid-handle-creation.md) | +| 0x00000017 | [**CID\_HANDLE\_DELETION**](bug-check-0x17--cid-handle-deletion.md) | +| 0x00000018 | [**REFERENCE\_BY\_POINTER**](bug-check-0x18--reference-by-pointer.md) | +| 0x00000019 | [**BAD\_POOL\_HEADER**](bug-check-0x19--bad-pool-header.md) | +| 0x0000001A | [**MEMORY\_MANAGEMENT**](bug-check-0x1a--memory-management.md) | +| 0x0000001B | [**PFN\_SHARE\_COUNT**](bug-check-0x1b--pfn-share-count.md) | +| 0x0000001C | [**PFN\_REFERENCE\_COUNT**](bug-check-0x1c--pfn-reference-count.md) | +| 0x0000001D | [**NO\_SPIN\_LOCK\_AVAILABLE**](bug-check-0x1d--no-spin-lock-available.md) | +| 0x0000001E | [**KMODE\_EXCEPTION\_NOT\_HANDLED**](bug-check-0x1e--kmode-exception-not-handled.md) | +| 0x0000001F | [**SHARED\_RESOURCE\_CONV\_ERROR**](bug-check-0x1f--shared-resource-conv-error.md) | +| 0x00000020 | [**KERNEL\_APC\_PENDING\_DURING\_EXIT**](bug-check-0x20--kernel-apc-pending-during-exit.md) | +| 0x00000021 | [**QUOTA\_UNDERFLOW**](bug-check-0x21--quota-underflow.md) | +| 0x00000022 | [**FILE\_SYSTEM**](bug-check-0x22--file-system.md) | +| 0x00000023 | [**FAT\_FILE\_SYSTEM**](bug-check-0x23--fat-file-system.md) | +| 0x00000024 | [**NTFS\_FILE\_SYSTEM**](bug-check-0x24--ntfs-file-system.md) | +| 0x00000025 | [**NPFS\_FILE\_SYSTEM**](bug-check-0x25--npfs-file-system.md) | +| 0x00000026 | [**CDFS\_FILE\_SYSTEM**](bug-check-0x26--cdfs-file-system.md) | +| 0x00000027 | [**RDR\_FILE\_SYSTEM**](bug-check-0x27--rdr-file-system.md) | +| 0x00000028 | [**CORRUPT\_ACCESS\_TOKEN**](bug-check-0x28--corrupt-access-token.md) | +| 0x00000029 | [**SECURITY\_SYSTEM**](bug-check-0x29--security-system.md) | +| 0x0000002A | [**INCONSISTENT\_IRP**](bug-check-0x2a--inconsistent-irp.md) | +| 0x0000002B | [**PANIC\_STACK\_SWITCH**](bug-check-0x2b--panic-stack-switch.md) | +| 0x0000002C | [**PORT\_DRIVER\_INTERNAL**](bug-check-0x2c--port-driver-internal.md) | +| 0x0000002D | [**SCSI\_DISK\_DRIVER\_INTERNAL**](bug-check-0x2d--scsi-disk-driver-internal.md) | +| 0x0000002E | [**DATA\_BUS\_ERROR**](bug-check-0x2e--data-bus-error.md) | +| 0x0000002F | I[**NSTRUCTION\_BUS\_ERROR**](bug-check-0x2f--instruction-bus-error.md) | +| 0x00000030 | [**SET\_OF\_INVALID\_CONTEXT**](bug-check-0x30--set-of-invalid-context.md) | +| 0x00000031 | [**PHASE0\_INITIALIZATION\_FAILED**](bug-check-0x31--phase0-initialization-failed.md) | +| 0x00000032 | [**PHASE1\_INITIALIZATION\_FAILED**](bug-check-0x32--phase1-initialization-failed.md) | +| 0x00000033 | [**UNEXPECTED\_INITIALIZATION\_CALL**](bug-check-0x33--unexpected-initialization-call.md) | +| 0x00000034 | [**CACHE\_MANAGER**](bug-check-0x34--cache-manager.md) | +| 0x00000035 | [**NO\_MORE\_IRP\_STACK\_LOCATIONS**](bug-check-0x35--no-more-irp-stack-locations.md) | +| 0x00000036 | [**DEVICE\_REFERENCE\_COUNT\_NOT\_ZERO**](bug-check-0x36--device-reference-count-not-zero.md) | +| 0x00000037 | [**FLOPPY\_INTERNAL\_ERROR**](bug-check-0x37--floppy-internal-error.md) | +| 0x00000038 | [**SERIAL\_DRIVER\_INTERNAL**](bug-check-0x38--serial-driver-internal.md) | +| 0x00000039 | [**SYSTEM\_EXIT\_OWNED\_MUTEX**](bug-check-0x39--system-exit-owned-mutex.md) | +| 0x0000003A | [**SYSTEM\_UNWIND\_PREVIOUS\_USER**](bug-check-0x3a--system-unwind-previous-user.md) | +| 0x0000003B | [**SYSTEM\_SERVICE\_EXCEPTION**](bug-check-0x3b--system-service-exception.md) | +| 0x0000003C | [**INTERRUPT\_UNWIND\_ATTEMPTED**](bug-check-0x3c--interrupt-unwind-attempted.md) | +| 0x0000003D | [**INTERRUPT\_EXCEPTION\_NOT\_HANDLED**](bug-check-0x3d--interrupt-exception-not-handled.md) | +| 0x0000003E | [**MULTIPROCESSOR\_CONFIGURATION\_NOT\_SUPPORTED**](bug-check-0x3e--multiprocessor-configuration-not-supported.md) | +| 0x0000003F | [**NO\_MORE\_SYSTEM\_PTES**](bug-check-0x3f--no-more-system-ptes.md) | +| 0x00000040 | [**TARGET\_MDL\_TOO\_SMALL**](bug-check-0x40--target-mdl-too-small.md) | +| 0x00000041 | [**MUST\_SUCCEED\_POOL\_EMPTY**](bug-check-0x41--must-succeed-pool-empty.md) | +| 0x00000042 | [**ATDISK\_DRIVER\_INTERNAL**](bug-check-0x42--atdisk-driver-internal.md) | +| 0x00000043 | [**NO\_SUCH\_PARTITION**](bug-check-0x43--no-such-partition.md) | +| 0x00000044 | [**MULTIPLE\_IRP\_COMPLETE\_REQUESTS**](bug-check-0x44--multiple-irp-complete-requests.md) | +| 0x00000045 | [**INSUFFICIENT\_SYSTEM\_MAP\_REGS**](bug-check-0x45--insufficient-system-map-regs.md) | +| 0x00000046 | [**DEREF\_UNKNOWN\_LOGON\_SESSION**](bug-check-0x46--deref-unknown-logon-session.md) | +| 0x00000047 | [**REF\_UNKNOWN\_LOGON\_SESSION**](bug-check-0x47--ref-unknown-logon-session.md) | +| 0x00000048 | [**CANCEL\_STATE\_IN\_COMPLETED\_IRP**](bug-check-0x48--cancel-state-in-completed-irp.md) | +| 0x00000049 | [**PAGE\_FAULT\_WITH\_INTERRUPTS\_OFF**](bug-check-0x49--page-fault-with-interrupts-off.md) | +| 0x0000004A | [**IRQL\_GT\_ZERO\_AT\_SYSTEM\_SERVICE**](bug-check-0x4a--irql-gt-zero-at-system-service.md) | +| 0x0000004B | [**STREAMS\_INTERNAL\_ERROR**](bug-check-0x4b--streams-internal-error.md) | +| 0x0000004C | [**FATAL\_UNHANDLED\_HARD\_ERROR**](bug-check-0x4c--fatal-unhandled-hard-error.md) | +| 0x0000004D | [**NO\_PAGES\_AVAILABLE**](bug-check-0x4d--no-pages-available.md) | +| 0x0000004E | [**PFN\_LIST\_CORRUPT**](bug-check-0x4e--pfn-list-corrupt.md) | +| 0x0000004F | [**NDIS\_INTERNAL\_ERROR**](bug-check-0x4f--ndis-internal-error.md) | +| 0x00000050 | [**PAGE\_FAULT\_IN\_NONPAGED\_AREA**](bug-check-0x50--page-fault-in-nonpaged-area.md) | +| 0x00000051 | [**REGISTRY\_ERROR**](bug-check-0x51--registry-error.md) | +| 0x00000052 | [**MAILSLOT\_FILE\_SYSTEM**](bug-check-0x52--mailslot-file-system.md) | +| 0x00000053 | [**NO\_BOOT\_DEVICE**](bug-check-0x53--no-boot-device.md) | +| 0x00000054 | [**LM\_SERVER\_INTERNAL\_ERROR**](bug-check-0x54--lm-server-internal-error.md) | +| 0x00000055 | [**DATA\_COHERENCY\_EXCEPTION**](bug-check-0x55--data-coherency-exception.md) | +| 0x00000056 | [**INSTRUCTION\_COHERENCY\_EXCEPTION**](bug-check-0x56--instruction-coherency-exception.md) | +| 0x00000057 | [**XNS\_INTERNAL\_ERROR**](bug-check-0x57--xns-internal-error.md) | +| 0x00000058 | [**FTDISK\_INTERNAL\_ERROR**](bug-check-0x58--ftdisk-internal-error.md) | +| 0x00000059 | [**PINBALL\_FILE\_SYSTEM**](bug-check-0x59--pinball-file-system.md) | +| 0x0000005A | [**CRITICAL\_SERVICE\_FAILED**](bug-check-0x5a--critical-service-failed.md) | +| 0x0000005B | [**SET\_ENV\_VAR\_FAILED**](bug-check-0x5b--set-env-var-failed.md) | +| 0x0000005C | [**HAL\_INITIALIZATION\_FAILED**](bug-check-0x5c--hal-initialization-failed.md) | +| 0x0000005D | [**UNSUPPORTED\_PROCESSOR**](bug-check-0x5d--unsupported-processor.md) | +| 0x0000005E | [**OBJECT\_INITIALIZATION\_FAILED**](bug-check-0x5e--object-initialization-failed.md) | +| 0x0000005F | [**SECURITY\_INITIALIZATION\_FAILED**](bug-check-0x5f--security-initialization-failed.md) | +| 0x00000060 | [**PROCESS\_INITIALIZATION\_FAILED**](bug-check-0x60--process-initialization-failed.md) | +| 0x00000061 | [**HAL1\_INITIALIZATION\_FAILED**](bug-check-0x61--hal1-initialization-failed.md) | +| 0x00000062 | [**OBJECT1\_INITIALIZATION\_FAILED**](bug-check-0x62--object1-initialization-failed.md) | +| 0x00000063 | [**SECURITY1\_INITIALIZATION\_FAILED**](bug-check-0x63--security1-initialization-failed.md) | +| 0x00000064 | [**SYMBOLIC\_INITIALIZATION\_FAILED**](bug-check-0x64--symbolic-initialization-failed.md) | +| 0x00000065 | [**MEMORY1\_INITIALIZATION\_FAILED**](bug-check-0x65--memory1-initialization-failed.md) | +| 0x00000066 | [**CACHE\_INITIALIZATION\_FAILED**](bug-check-0x66--cache-initialization-failed.md) | +| 0x00000067 | [**CONFIG\_INITIALIZATION\_FAILED**](bug-check-0x67--config-initialization-failed.md) | +| 0x00000068 | [**FILE\_INITIALIZATION\_FAILED**](bug-check-0x68--file-initialization-failed.md) | +| 0x00000069 | [**IO1\_INITIALIZATION\_FAILED**](bug-check-0x69--io1-initialization-failed.md) | +| 0x0000006A | [**LPC\_INITIALIZATION\_FAILED**](bug-check-0x6a--lpc-initialization-failed.md) | +| 0x0000006B | [**PROCESS1\_INITIALIZATION\_FAILE**](bug-check-0x6b--process1-initialization-failed.md)D | +| 0x0000006C | [**REFMON\_INITIALIZATION\_FAILED**](bug-check-0x6c--refmon-initialization-failed.md) | +| 0x0000006D | [**SESSION1\_INITIALIZATION\_FAILED**](bug-check-0x6d--session1-initialization-failed.md) | +| 0x0000006E | [**SESSION2\_INITIALIZATION\_FAILED**](bug-check-0x6e--session2-initialization-failed.md) | +| 0x0000006F | [**SESSION3\_INITIALIZATION\_FAILED**](bug-check-0x6f--session3-initialization-failed.md) | +| 0x00000070 | [**SESSION4\_INITIALIZATION\_FAILED**](bug-check-0x70--session4-initialization-failed.md) | +| 0x00000071 | [**SESSION5\_INITIALIZATION\_FAILED**](bug-check-0x71--session5-initialization-failed.md) | +| 0x00000072 | [**ASSIGN\_DRIVE\_LETTERS\_FAILED**](bug-check-0x72--assign-drive-letters-failed.md) | +| 0x00000073 | [**CONFIG\_LIST\_FAILED**](bug-check-0x73--config-list-failed.md) | +| 0x00000074 | [**BAD\_SYSTEM\_CONFIG\_INFO**](bug-check-0x74--bad-system-config-info.md) | +| 0x00000075 | [**CANNOT\_WRITE\_CONFIGURATION**](bug-check-0x75--cannot-write-configuration.md) | +| 0x00000076 | [**PROCESS\_HAS\_LOCKED\_PAGES**](bug-check-0x76--process-has-locked-pages.md) | +| 0x00000077 | [**KERNEL\_STACK\_INPAGE\_ERROR**](bug-check-0x77--kernel-stack-inpage-error.md) | +| 0x00000078 | [**PHASE0\_EXCEPTION**](bug-check-0x78--phase0-exception.md) | +| 0x00000079 | [**MISMATCHED\_HAL**](bug-check-0x79--mismatched-hal.md) | +| 0x0000007A | [**KERNEL\_DATA\_INPAGE\_ERROR**](bug-check-0x7a--kernel-data-inpage-error.md) | +| 0x0000007B | [**INACCESSIBLE\_BOOT\_DEVICE**](bug-check-0x7b--inaccessible-boot-device.md) | +| 0x0000007C | [**BUGCODE\_NDIS\_DRIVER**](bug-check-0x7c--bugcode-ndis-driver.md) | +| 0x0000007D | [**INSTALL\_MORE\_MEMORY**](bug-check-0x7d--install-more-memory.md) | +| 0x0000007E | [**SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED**](bug-check-0x7e--system-thread-exception-not-handled.md) | +| 0x0000007F | [**UNEXPECTED\_KERNEL\_MODE\_TRAP**](bug-check-0x7f--unexpected-kernel-mode-trap.md) | +| 0x00000080 | [**NMI\_HARDWARE\_FAILURE**](bug-check-0x80--nmi-hardware-failure.md) | +| 0x00000081 | [**SPIN\_LOCK\_INIT\_FAILURE**](bug-check-0x81--spin-lock-init-failure.md) | +| 0x00000082 | [**DFS\_FILE\_SYSTEM**](bug-check-0x82--dfs-file-system.md) | +| 0x00000085 | [**SETUP\_FAILURE**](bug-check-0x85--setup-failure.md) | +| 0x0000008B | [**MBR\_CHECKSUM\_MISMATCH**](bug-check-0x8b--mbr-checksum-mismatch.md) | +| 0x0000008E | [**KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED**](bug-check-0x8e--kernel-mode-exception-not-handled.md) | +| 0x0000008F | [**PP0\_INITIALIZATION\_FAILED**](bug-check-0x8f--pp0-initialization-failed.md) | +| 0x00000090 | [**PP1\_INITIALIZATION\_FAILED**](bug-check-0x90--pp1-initialization-failed.md) | +| 0x00000092 | [**UP\_DRIVER\_ON\_MP\_SYSTEM**](bug-check-0x92--up-driver-on-mp-system.md) | +| 0x00000093 | [**INVALID\_KERNEL\_HANDLE**](bug-check-0x93--invalid-kernel-handle.md) | +| 0x00000094 | [**KERNEL\_STACK\_LOCKED\_AT\_EXIT**](bug-check-0x94--kernel-stack-locked-at-exit.md) | +| 0x00000096 | [**INVALID\_WORK\_QUEUE\_ITEM**](bug-check-0x96--invalid-work-queue-item.md) | +| 0x00000097 | [**BOUND\_IMAGE\_UNSUPPORTED**](bug-check-0x97--bound-image-unsupported.md) | +| 0x00000098 | [**END\_OF\_NT\_EVALUATION\_PERIOD**](bug-check-0x98--end-of-nt-evaluation-period.md) | +| 0x00000099 | [**INVALID\_REGION\_OR\_SEGMENT**](bug-check-0x99--invalid-region-or-segment.md) | +| 0x0000009A | [**SYSTEM\_LICENSE\_VIOLATION**](bug-check-0x9a--system-license-violation.md) | +| 0x0000009B | [**UDFS\_FILE\_SYSTEM**](bug-check-0x9b--udfs-file-system.md) | +| 0x0000009C | [**MACHINE\_CHECK\_EXCEPTION**](bug-check-0x9c--machine-check-exception.md) | +| 0x0000009E | [**USER\_MODE\_HEALTH\_MONITOR**](bug-check-0x9e--user-mode-health-monitor.md) | +| 0x0000009F | [**DRIVER\_POWER\_STATE\_FAILURE**](bug-check-0x9f--driver-power-state-failure.md) | +| 0x000000A0 | [**INTERNAL\_POWER\_ERROR**](bug-check-0xa0--internal-power-error.md) | +| 0x000000A1 | [**PCI\_BUS\_DRIVER\_INTERNAL**](bug-check-0xa1--pci-bus-driver-internal.md) | +| 0x000000A2 | [**MEMORY\_IMAGE\_CORRUPT**](bug-check-0xa2--memory-image-corrupt.md) | +| 0x000000A3 | [**ACPI\_DRIVER\_INTERNAL**](bug-check-0xa3--acpi-driver-internal.md) | +| 0x000000A4 | [**CNSS\_FILE\_SYSTEM\_FILTER**](bug-check-0xa4--cnss-file-system-filter.md) | +| 0x000000A5 | [**ACPI\_BIOS\_ERROR**](bug-check-0xa5--acpi-bios-error.md) | +| 0x000000A7 | [**BAD\_EXHANDLE**](bug-check-0xa7--bad-exhandle.md) | +| 0x000000AB | [**SESSION\_HAS\_VALID\_POOL\_ON\_EXIT**](bug-check-0xab--session-has-valid-pool-on-exit.md) | +| 0x000000AC | [**HAL\_MEMORY\_ALLOCATION**](bug-check-0xac--hal-memory-allocation.md) | +| 0x000000AD | [**VIDEO\_DRIVER\_DEBUG\_REPORT\_REQUEST**](bug-check-0xad--video-driver-debug-report-request.md) | +| 0x000000B1 | [**BGI\_DETECTED\_VIOLATION**](bug-check-0xb1--bgi-detected-violation.md) | +| 0x000000B4 | [**VIDEO\_DRIVER\_INIT\_FAILURE**](bug-check-0xb4--video-driver-init-failure.md) | +| 0x000000B8 | [**ATTEMPTED\_SWITCH\_FROM\_DPC**](bug-check-0xb8--attempted-switch-from-dpc.md) | +| 0x000000B9 | [**CHIPSET\_DETECTED\_ERROR**](bug-check-0xb9--chipset-detected-error.md) | +| 0x000000BA | [**SESSION\_HAS\_VALID\_VIEWS\_ON\_EXIT**](bug-check-0xba--session-has-valid-views-on-exit.md) | +| 0x000000BB | [**NETWORK\_BOOT\_INITIALIZATION\_FAILED**](bug-check-0xbb--network-boot-initialization-failed.md) | +| 0x000000BC | [**NETWORK\_BOOT\_DUPLICATE\_ADDRESS**](bug-check-0xbc--network-boot-duplicate-address.md) | +| 0x000000BD | [**INVALID\_HIBERNATED\_STATE**](bug-check-0xbd--invalid-hibernated-state.md) | +| 0x000000BE | [**ATTEMPTED\_WRITE\_TO\_READONLY\_MEMORY**](bug-check-0xbe--attempted-write-to-readonly-memory.md) | +| 0x000000BF | [**MUTEX\_ALREADY\_OWNED**](bug-check-0xbf--mutex-already-owned.md) | +| 0x000000C1 | [**SPECIAL\_POOL\_DETECTED\_MEMORY\_CORRUPTION**](bug-check-0xc1--special-pool-detected-memory-corruption.md) | +| 0x000000C2 | [**BAD\_POOL\_CALLER**](bug-check-0xc2--bad-pool-caller.md) | +| 0x000000C4 | [**DRIVER\_VERIFIER\_DETECTED\_VIOLATION**](bug-check-0xc4--driver-verifier-detected-violation.md) | +| 0x000000C5 | [**DRIVER\_CORRUPTED\_EXPOOL**](bug-check-0xc5--driver-corrupted-expool.md) | +| 0x000000C6 | [**DRIVER\_CAUGHT\_MODIFYING\_FREED\_POO**](bug-check-0xc6--driver-caught-modifying-freed-pool.md)L | +| 0x000000C7 | [**TIMER\_OR\_DPC\_INVALID**](bug-check-0xc7--timer-or-dpc-invalid.md) | +| 0x000000C8 | [**IRQL\_UNEXPECTED\_VALUE**](bug-check-0xc8--irql-unexpected-value.md) | +| 0x000000C9 | [**DRIVER\_VERIFIER\_IOMANAGER\_VIOLATION**](bug-check-0xc9--driver-verifier-iomanager-violation.md) | +| 0x000000CA | [**PNP\_DETECTED\_FATAL\_ERROR**](bug-check-0xca--pnp-detected-fatal-error.md) | +| 0x000000CB | [**DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS**](bug-check-0xcb--driver-left-locked-pages-in-process.md) | +| 0x000000CC | [**PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL**](bug-check-0xcc--page-fault-in-freed-special-pool.md) | +| 0x000000CD | [**PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION**](bug-check-0xcd--page-fault-beyond-end-of-allocation.md) | +| 0x000000CE | [**DRIVER\_UNLOADED\_WITHOUT\_CANCELLING\_PENDING\_OPERATIONS**](bug-check-0xce--driver-unloaded-without-cancelling-pending-operations.md) | +| 0x000000CF | [**TERMINAL\_SERVER\_DRIVER\_MADE\_INCORRECT\_MEMORY\_REFERENCE**](bug-check-0xcf--terminal-server-driver-made-incorrect-memory-reference.md) | +| 0x000000D0 | [**DRIVER\_CORRUPTED\_MMPOOL**](bug-check-0xd0--driver-corrupted-mmpool.md) | +| 0x000000D1 | [**DRIVER\_IRQL\_NOT\_LESS\_OR\_EQUAL**](bug-check-0xd1--driver-irql-not-less-or-equal.md) | +| 0x000000D2 | [**BUGCODE\_ID\_DRIVER**](bug-check-0xd2--bugcode-id-driver.md) | +| 0x000000D3 | [**DRIVER\_PORTION\_MUST\_BE\_NONPAGED**](bug-check-0xd3--driver-portion-must-be-nonpaged.md) | +| 0x000000D4 | [**SYSTEM\_SCAN\_AT\_RAISED\_IRQL\_CAUGHT\_IMPROPER\_DRIVER\_UNLOAD**](bug-check-0xd4--system-scan-at-raised-irql-caught-improper-driver-unlo.md) | +| 0x000000D5 | [**DRIVER\_PAGE\_FAULT\_IN\_FREED\_SPECIAL\_POOL**](bug-check-0xd5--driver-page-fault-in-freed-special-pool.md) | +| 0x000000D6 | [**DRIVER\_PAGE\_FAULT\_BEYOND\_END\_OF\_ALLOCATION**](bug-check-0xd6--driver-page-fault-beyond-end-of-allocation.md) | +| 0x000000D7 | [**DRIVER\_UNMAPPING\_INVALID\_VIEW**](bug-check-0xd7--driver-unmapping-invalid-view.md) | +| 0x000000D8 | [**DRIVER\_USED\_EXCESSIVE\_PTES**](bug-check-0xd8--driver-used-excessive-ptes.md) | +| 0x000000D9 | [**LOCKED\_PAGES\_TRACKER\_CORRUPTION**](bug-check-0xd9--locked-pages-tracker-corruption.md) | +| 0x000000DA | [**SYSTEM\_PTE\_MISUSE**](bug-check-0xda--system-pte-misuse.md) | +| 0x000000DB | [**DRIVER\_CORRUPTED\_SYSPTES**](bug-check-0xdb--driver-corrupted-sysptes.md) | +| 0x000000DC | [**DRIVER\_INVALID\_STACK\_ACCESS**](bug-check-0xdc--driver-invalid-stack-access.md) | +| 0x000000DE | [**POOL\_CORRUPTION\_IN\_FILE\_AREA**](bug-check-0xde--pool-corruption-in-file-area.md) | +| 0x000000DF | I[**MPERSONATING\_WORKER\_THREAD**](bug-check-0xdf--impersonating-worker-thread.md) | +| 0x000000E0 | [**ACPI\_BIOS\_FATAL\_ERROR**](bug-check-0xe0--acpi-bios-fatal-error.md) | +| 0x000000E1 | [**WORKER\_THREAD\_RETURNED\_AT\_BAD\_IRQL**](bug-check-0xe1--worker-thread-returned-at-bad-irql.md) | +| 0x000000E2 | [**MANUALLY\_INITIATED\_CRASH**](bug-check-0xe2--manually-initiated-crash.md) | +| 0x000000E3 | [**RESOURCE\_NOT\_OWNED**](bug-check-0xe3--resource-not-owned.md) | +| 0x000000E4 | [**WORKER\_INVALID**](bug-check-0xe4--worker-invalid.md) | +| 0x000000E6 | [**DRIVER\_VERIFIER\_DMA\_VIOLATION**](bug-check-0xe6--driver-verifier-dma-violation.md) | +| 0x000000E7 | [**INVALID\_FLOATING\_POINT\_STATE**](bug-check-0xe7--invalid-floating-point-state.md) | +| 0x000000E8 | [**INVALID\_CANCEL\_OF\_FILE\_OPEN**](bug-check-0xe8--invalid-cancel-of-file-open.md) | +| 0x000000E9 | [**ACTIVE\_EX\_WORKER\_THREAD\_TERMINATION**](bug-check-0xe9--active-ex-worker-thread-termination.md) | +| 0x000000EA | [**THREAD\_STUCK\_IN\_DEVICE\_DRIVER**](bug-check-0xea--thread-stuck-in-device-driver.md) | +| 0x000000EB | [**DIRTY\_MAPPED\_PAGES\_CONGESTION**](bug-check-0xeb--dirty-mapped-pages-congestion.md) | +| 0x000000EC | [**SESSION\_HAS\_VALID\_SPECIAL\_POOL\_ON\_EXIT**](bug-check-0xec--session-has-valid-special-pool-on-exit.md) | +| 0x000000ED | [**UNMOUNTABLE\_BOOT\_VOLUME**](bug-check-0xed--unmountable-boot-volume.md) | +| 0x000000EF | [**CRITICAL\_PROCESS\_DIED**](bug-check-0xef--critical-process-died.md) | +| 0x000000F1 | [**SCSI\_VERIFIER\_DETECTED\_VIOLATION**](bug-check-0xf1--scsi-verifier-detected-violation.md) | +| 0x000000F2 | [**HARDWARE\_INTERRUPT\_STORM**](bug-check-0xf2--hardware-interrupt-storm.md) | +| 0x000000F3 | [**DISORDERLY\_SHUTDOWN**](bug-check-0xf3--disorderly-shutdown.md) | +| 0x000000F4 | [**CRITICAL\_OBJECT\_TERMINATION**](bug-check-0xf4--critical-object-termination.md) | +| 0x000000F5 | [**FLTMGR\_FILE\_SYSTEM**](bug-check-0xf5--fltmgr-file-system.md) | +| 0x000000F6 | [**PCI\_VERIFIER\_DETECTED\_VIOLATION**](bug-check-0xf6--pci-verifier-detected-violation.md) | +| 0x000000F7 | [**DRIVER\_OVERRAN\_STACK\_BUFFER**](bug-check-0xf7--driver-overran-stack-buffer.md) | +| 0x000000F8 | [**RAMDISK\_BOOT\_INITIALIZATION\_FAILED**](bug-check-0xf8--ramdisk-boot-initialization-failed.md) | +| 0x000000F9 | [**DRIVER\_RETURNED\_STATUS\_REPARSE\_FOR\_VOLUME\_OPEN**](bug-check-0xf9--driver-returned-status-reparse-for-volume-open.md) | +| 0x000000FA | [**HTTP\_DRIVER\_CORRUPTED**](bug-check-0xfa---http-driver-corrupted.md) | +| 0x000000FC | [**ATTEMPTED\_EXECUTE\_OF\_NOEXECUTE\_MEMORY**](bug-check-0xfc---attempted-execute-of-noexecute-memory.md) | +| 0x000000FD | [**DIRTY\_NOWRITE\_PAGES\_CONGESTION**](bug-check-0xfd---dirty-nowrite-pages-congestion.md) | +| 0x000000FE | [**BUGCODE\_USB\_DRIVER**](bug-check-0xfe--bugcode-usb-driver.md) | +| 0x000000FF | [**RESERVE\_QUEUE\_OVERFLOW**](bug-check-0xff---reserve-queue-overflow.md) | +| 0x00000100 | [**LOADER\_BLOCK\_MISMATCH**](bug-check-0x100---loader-block-mismatch.md) | +| 0x00000101 | [**CLOCK\_WATCHDOG\_TIMEOUT**](bug-check-0x101---clock-watchdog-timeout.md) | +| 0x00000102 | [**DPC\_WATCHDOG\_TIMEOUT**](bug-check-0x102--dpc-watchdog-timeout.md) | +| 0x00000103 | [**MUP\_FILE\_SYSTEM**](bug-check-0x103---mup-file-system.md) | +| 0x00000104 | [**AGP\_INVALID\_ACCESS**](bug-check-0x104---agp-invalid-access.md) | +| 0x00000105 | [**AGP\_GART\_CORRUPTION**](bug-check-0x105---agp-gart-corruption.md) | +| 0x00000106 | [**AGP\_ILLEGALLY\_REPROGRAMMED**](bug-check-0x106---agp-illegally-reprogrammed.md) | +| 0x00000108 | [**THIRD\_PARTY\_FILE\_SYSTEM\_FAILURE**](bug-check-0x108--third-party-file-system-failure.md) | +| 0x00000109 | [**CRITICAL\_STRUCTURE\_CORRUPTION**](bug-check-0x109---critical-structure-corruption.md) | +| 0x0000010A | [**APP\_TAGGING\_INITIALIZATION\_FAILED**](bug-check-0x10a---app-tagging-initialization-failed.md) | +| 0x0000010C | [**FSRTL\_EXTRA\_CREATE\_PARAMETER\_VIOLATION**](bug-check-0x10c---fsrtl-extra-create-parameter-violation.md) | +| 0x0000010D | [**WDF\_VIOLATION**](bug-check-0x10d---wdf-violation.md) | +| 0x0000010E | [**VIDEO\_MEMORY\_MANAGEMENT\_INTERNAL**](bug-check-0x10e---video-memory-management-internal.md) | +| 0x0000010F | [**RESOURCE\_MANAGER\_EXCEPTION\_NOT\_HANDLED**](bug-check-0x10f---resource-manager-exception-not-handled.md) | +| 0x00000111 | [**RECURSIVE\_NMI**](bug-check-0x111---recursive-nmi.md) | +| 0x00000112 | [**MSRPC\_STATE\_VIOLATION**](bug-check-0x112---msrpc-state-violation.md) | +| 0x00000113 | [**VIDEO\_DXGKRNL\_FATAL\_ERROR**](bug-check-0x113---video-dxgkrnl-fatal-error.md) | +| 0x00000114 | [**VIDEO\_SHADOW\_DRIVER\_FATAL\_ERROR**](bug-check-0x114---video-shadow-driver-fatal-error.md) | +| 0x00000115 | [**AGP\_INTERNAL**](bug-check-0x115---agp-internal.md) | +| 0x00000116 | [**VIDEO\_TDR\_ERROR**](bug-check-0x116---video-tdr-error.md) | +| 0x00000117 | [**VIDEO\_TDR\_TIMEOUT\_DETECTED**](bug-check-0x117---video-tdr-timeout-detected.md) | +| 0x00000119 | [**VIDEO\_SCHEDULER\_INTERNAL\_ERROR**](bug-check-0x119---video-scheduler-internal-error.md) | +| 0x0000011A | [**EM\_INITIALIZATION\_FAILURE**](bug-check-0x11a---em-initialization-failure.md) | +| 0x0000011B | [**DRIVER\_RETURNED\_HOLDING\_CANCEL\_LOCK**](bug-check-0x11b---driver-returned-holding-cancel-lock.md) | +| 0x0000011C | [**ATTEMPTED\_WRITE\_TO\_CM\_PROTECTED\_STORAGE**](bug-check-0x11c--attempted-write-to-cm-protected-storage.md) | +| 0x0000011D | [**EVENT\_TRACING\_FATAL\_ERROR**](bug-check-0x11d---event-tracing-fatal-error.md) | +| 0x0000011E | [**TOO\_MANY\_RECURSIVE\_FAULTS**](bug-check--0x11e--too-many-recursive-faults.md) | +| 0x0000011F | [**INVALID\_DRIVER\_HANDLE**](bug-check--0x11f--invalid-driver-handle.md) | +| 0x00000120 | [**BITLOCKER\_FATAL\_ERROR**](bug-check--0x120--bitlocker-fatal-error-.md) | +| 0x00000121 | [**DRIVER\_VIOLATION**](bug-check-0x121---driver-violation.md) | +| 0x00000122 | [**WHEA\_INTERNAL\_ERROR**](bug-check-0x122---whea-internal-error.md) | +| 0x00000123 | [**CRYPTO\_SELF\_TEST\_FAILURE**](bug-check--0x123--crypto-self-test-failure-.md) | +| 0x00000124 | [**WHEA\_UNCORRECTABLE\_ERROR**](bug-check-0x124---whea-uncorrectable-error.md) | +| 0x00000125 | [**NMR\_INVALID\_STATE**](bug-check--0x125--nmr-invalid-state.md) | +| 0x00000126 | [**NETIO\_INVALID\_POOL\_CALLER**](bug-check--0x126--netio-invalid-pool-caller.md) | +| 0x00000127 | [**PAGE\_NOT\_ZERO**](bug-check-0x127---page-not-zero.md) | +| 0x00000128 | [**WORKER\_THREAD\_RETURNED\_WITH\_BAD\_IO\_PRIORITY**](bug-check-0x128--worker-thread-returned-with-bad-io-priority.md) | +| 0x00000129 | [**WORKER\_THREAD\_RETURNED\_WITH\_BAD\_PAGING\_IO\_PRIORITY**](bug-check-0x129--worker-thread-returned-with-bad-paging-io-priority.md) | +| 0x0000012A | [**MUI\_NO\_VALID\_SYSTEM\_LANGUAGE**](bug-check-0x12a--mui-no-valid-system-language.md) | +| 0x0000012B | [**FAULTY\_HARDWARE\_CORRUPTED\_PAGE**](bug-check-0x12b---faulty-hardware-corrupted-page.md) | +| 0x0000012C | [**EXFAT\_FILE\_SYSTEM**](bug-check-0x12c---exfat-file-system.md) | +| 0x0000012D | [**VOLSNAP\_OVERLAPPED\_TABLE\_ACCESS**](bug-check-0x12d--volsnap-overlapped-table-access.md) | +| 0x0000012E | [**INVALID\_MDL\_RANGE**](bug-check-0x12e--invalid-mdl-range.md) | +| 0x0000012F | [**VHD\_BOOT\_INITIALIZATION\_FAILED**](bug-check-0x12f--vhd-boot-initialization-failed.md) | +| 0x00000130 | [**DYNAMIC\_ADD\_PROCESSOR\_MISMATCH**](bug-check-0x130--dynamic-add-processor-mismatch.md) | +| 0x00000131 | [**INVALID\_EXTENDED\_PROCESSOR\_STATE**](bug-check-0x131--invalid-extended-processor-state.md) | +| 0x00000132 | [**RESOURCE\_OWNER\_POINTER\_INVALID**](bug-check-0x132--resource-owner-pointer-invalid.md) | +| 0x00000133 | [**DPC\_WATCHDOG\_VIOLATION**](bug-check-0x133-dpc-watchdog-violation.md) | +| 0x00000134 | [**DRIVE\_EXTENDER**](bug-check-0x134--drive-extender.md) | +| 0x00000135 | [**REGISTRY\_FILTER\_DRIVER\_EXCEPTION**](bug-check-0x135--registry-filter-driver-exception.md) | +| 0x00000136 | [**VHD\_BOOT\_HOST\_VOLUME\_NOT\_ENOUGH\_SPACE**](bug-check-0x136--vhd-boot-host-volume-not-enough-space.md) | +| 0x00000137 | [**WIN32K\_HANDLE\_MANAGER**](bug-check-0x137--win32k-handle-manager.md) | +| 0x00000138 | [**GPIO\_CONTROLLER\_DRIVER\_ERROR**](bug-check-0x138-gpio-controller-driver-error.md) | +| 0x00000139 | [**KERNEL\_SECURITY\_CHECK\_FAILURE**](bug-check---bug-check-0x139-kernel-security-check-failure.md) | +| 0x0000013A | [**KERNEL\_MODE\_HEAP\_CORRUPTION**](bug-check-0x13a--kernel-mode-heap-corruption.md) | +| 0x0000013B | [**PASSIVE\_INTERRUPT\_ERROR**](bug-check-0x13b--passive-interrupt-error.md) | +| 0x0000013C | [**INVALID\_IO\_BOOST\_STATE**](bug-check-0x13c--invalid-io-boost-state.md) | +| 0x0000013D | [**CRITICAL\_INITIALIZATION\_FAILURE**](bug-check-0x13d--critical-initialization-failure.md) | +| 0x00000140 | [**STORAGE\_DEVICE\_ABNORMALITY\_DETECTED**](bug-check-0x140--storage-device-abnormality-detected.md) | +| 0x00000141 | [**VIDEO\_ENGINE\_TIMEOUT\_DETECTED**](bug-check-0x141---video-engine-timeout-detected.md) | +| 0x00000142 | [**VIDEO\_TDR\_APPLICATION\_BLOCKED**](bug-check-0x142--video-tdr-application-blocked.md) | +| 0x00000143 | [**PROCESSOR\_DRIVER\_INTERNAL**](bug-check-0x143--processor-driver-internal.md) | +| 0x00000144 | [**BUGCODE\_USB3\_DRIVER**](bug-check-0x144--bugcode-usb3-driver.md) | +| 0x00000145 | [**SECURE\_BOOT\_VIOLATION**](bug-check-0x145--secure-boot-violation-.md) | +| 0x00000147 | [**ABNORMAL\_RESET\_DETECTED**](bug-check-0x147--abnormal-reset-detected.md) | +| 0x00000149 | [**REFS\_FILE\_SYSTEM**](bug-check-0x149--refs-file-system.md) | +| 0x0000014A | [**KERNEL\_WMI\_INTERNAL**](bug-check-0x14a--kernel-wmi-internal.md) | +| 0x0000014B | [**SOC\_SUBSYSTEM\_FAILURE**](bug-check-0x14b--soc-subsystem-failure.md) | +| 0x0000014C | [**FATAL\_ABNORMAL\_RESET\_ERROR**](bug-check-0x14c--fatal-abnormal-reset-error.md) | +| 0x0000014D | [**EXCEPTION\_SCOPE\_INVALID**](bug-check-0x14d--exception-scope-invalid.md) | +| 0x0000014E | [**SOC\_CRITICAL\_DEVICE\_REMOVED**](bug-check-0x14e--soc-critical-device-removed.md) | +| 0x0000014F | [**PDC\_WATCHDOG\_TIMEOUT**](bug-check-0x14f--pdc-watchdog-timeout.md) | +| 0x00000150 | [**TCPIP\_AOAC\_NIC\_ACTIVE\_REFERENCE\_LEAK**](bug-check-0x150--tcpip-aoac-nic-active-reference-leak.md) | +| 0x00000151 | [**UNSUPPORTED\_INSTRUCTION\_MODE**](bug-check-0x151--unsupported-instruction-mode.md) | +| 0x00000152 | [**INVALID\_PUSH\_LOCK\_FLAGS**](bug-check-0x152--invalid-push-lock-flags.md) | +| 0x00000153 | [**KERNEL\_LOCK\_ENTRY\_LEAKED\_ON\_THREAD\_TERMINATION**](bug-check-0x153--kernel-lock-entry-leaked-on-thread-termination.md) | +| 0x00000154 | [**UNEXPECTED\_STORE\_EXCEPTION**](bug-check-0x154--unexpected-store-exception.md) | +| 0x00000155 | [**OS\_DATA\_TAMPERING**](bug-check-0x155--os-data-tampering.md) | +| 0x00000156 | [**WINSOCK\_DETECTED\_HUNG\_CLOSESOCKET\_LIVEDUMP**](bug-check-0x156--winsock-detected-hung-closesocket-livedump.md) | +| 0x00000157 | [**KERNEL\_THREAD\_PRIORITY\_FLOOR\_VIOLATION**](bug-check-0x157--kernel-thread-priority-floor-violation.md) | +| 0x00000158 | [**ILLEGAL\_IOMMU\_PAGE\_FAULT**](bug-check-0x158--illegal-iommu-page-fault.md) | +| 0x00000159 | [**HAL\_ILLEGAL\_IOMMU\_PAGE\_FAULT**](bug-check-0x159--hal-illegal-iommu-page-fault.md) | +| 0x0000015A | [**SDBUS\_INTERNAL\_ERROR**](bug-check-0x15a--sdbus-internal-error.md) | +| 0x0000015B | [**WORKER\_THREAD\_RETURNED\_WITH\_SYSTEM\_PAGE\_PRIORITY\_ACTIVE**](bug-check-0x15b--worker-thread-returned-with-system-page-priority-active.md) | +| 0x0000015C | [**PDC\_WATCHDOG\_TIMEOUT\_LIVEDUMP**](bug-check-0x15c--pdc-watchdog-timeout-livedump.md) | +| 0x0000015F | [**CONNECTED\_STANDBY\_WATCHDOG\_TIMEOUT\_LIVEDUMP**](bug-check-0x15f--connected-standby-watchdog-timeout-livedump.md) | +| 0x00000160 | [**WIN32K\_ATOMIC\_CHECK\_FAILURE**](bug-check-0x160--win32k-atomic-check-failure.md) | +| 0x00000161 | [**LIVE\_SYSTEM\_DUMP**](bug-check-0x161--live-system-dump.md) | +| 0x00000162 | [**KERNEL\_AUTO\_BOOST\_INVALID\_LOCK\_RELEASE**](bug-check-0x162--kernel-auto-boost-invalid-lock-release.md) | +| 0x00000163 | [**WORKER\_THREAD\_TEST\_CONDITION**](bug-check-0x162--worker-thread-test-condition.md) | +| 0x00000164 | [**WIN32K\_CRITICAL\_FAILURE**](bug-check-0x164--win32k-critical-failure.md) | +| 0x0000016C | [**INVALID\_RUNDOWN\_PROTECTION\_FLAGS**](bug-check-0x16c--invalid-rundown-protection-flags.md) | +| 0x0000016D | [**INVALID\_SLOT\_ALLOCATOR\_FLAGS**](bug-check-0x16d--invalid-slot-allocator-flags.md) | +| 0x0000016E | [**ERESOURCE\_INVALID\_RELEASE**](bug-check-0x16e--eresource-invalid-release.md) | +| 0x00000175 | [**PREVIOUS\_FATAL\_ABNORMAL\_RESET\_ERROR**](bug-check-0x175--previous-fatal-abnormal-reset-error.md) | +| 0x00000178 | [**ELAM\_DRIVER\_DETECTED\_FATAL\_ERROR**](bug-check-0x175--elam-driver-detected-fatal-error.md) | +| 0x00000187 | [**VIDEO\_DWMINIT\_TIMEOUT\_FALLBACK\_BDD**](bug-check-0x187--video-dwminit-timeout-fallback-bdd.md) | +| 0x00000188 | [**CLUSTER\_CSVFS\_LIVEDUMP**](bug-check-0x188--cluster-csvfs-livedump.md) | +| 0x00000189 | [**BAD\_OBJECT\_HEADER**](bug-check-0x189--bad-object-header.md) | +| 0x0000018B | [**SECURE\_KERNEL\_ERROR**](bug-check-0x18b--secure-kernel-error.md) | +| 0x00000190 | [**WIN32K\_CRITICAL\_FAILURE\_LIVEDUMP**](bug-check-0x190--win32k-critical-failure-livedump.md) | +| 0x00000191 | [**PF\_DETECTED\_CORRUPTION**](bug-check-0x191--pf-detected-corruption.md) | +| 0x00000192 | [**KERNEL\_AUTO\_BOOST\_LOCK\_ACQUISITION\_WITH\_RAISED\_IRQL**](bug-check-0x192--kernel-auto-boost-lock-acquisition-with-raised-irql.md) | +| 0x00000193 | [**VIDEO\_DXGKRNL\_LIVEDUMP**](bug-check-0x192--video-dxgkrnl-livedump.md) | +| 0x00000195 | [**SMB\_SERVER\_LIVEDUMP**](bug-check-0x195--smb-server-livedump.md) | +| 0x00000196 | [**LOADER\_ROLLBACK\_DETECTED**](bug-check-0x196--loader-rollback-detected.md) | +| 0x00000197 | [**WIN32K\_SECURITY\_FAILURE**](bug-check-0x197--win32k-security-failure.md) | +| 0x00000198 | [**UFX\_LIVEDUMP**](bug-check-0x198--ufx-livedump.md) | +| 0x00000199 | [**KERNEL\_STORAGE\_SLOT\_IN\_USE**](bug-check-0x199--kernel-storage-slot-in-use.md) | +| 0x0000019A | [**WORKER\_THREAD\_RETURNED\_WHILE\_ATTACHED\_TO\_SILO**](bug-check-0x19a--worker-thread-returned-while-attached-to-silo.md) | +| 0x0000019B | [**TTM\_FATAL\_ERROR**](bug-check-0x19b--ttm-fatal-error.md) | +| 0x0000019C | [**WIN32K\_POWER\_WATCHDOG\_TIMEOUT**](bug-check-0x19c--win32k-power-watchdog-timeout.md) | +| 0x0000019D | [**CLUSTER\_SVHDX\_LIVEDUMP**](bug-check-0x19d--cluster-svhdx-livedump.md) | +| 0x000001C4 | [**DRIVER\_VERIFIER\_DETECTED\_VIOLATION\_LIVEDUMP**](bug-check-0x1c4--driver-verifier-detected-violation-livedump.md) | +| 0x000001C5 | [**IO\_THREADPOOL\_DEADLOCK\_LIVEDUMP**](bug-check-0x1c5--io-threadpool-deadlock-livedump.md) | +| 0x00000BFE | [**BC\_BLUETOOTH\_VERIFIER\_FAULT**](bug-check-0xbfe--bc-bluetooth-verifier-fault.md) | +| 0x00000BFF | [**BC\_BTHMINI\_VERIFIER\_FAULT**](bug-check-0xbff--bc-bthmini-verifier-fault.md) | +| 0x00020001 | [**HYPERVISOR\_ERROR**](bug-check--0x20001--hypervisor-error.md) | +| 0x1000007E | [**SYSTEM\_THREAD\_EXCEPTION\_NOT\_HANDLED\_M**](bug-check-0x1000007e--system-thread-exception-not-handled-m.md) | +| 0x1000007F | [**UNEXPECTED\_KERNEL\_MODE\_TRAP\_M**](bug-check-0x1000007f--unexpected-kernel-mode-trap-m.md) | +| 0x1000008E | [**KERNEL\_MODE\_EXCEPTION\_NOT\_HANDLED\_M**](bug-check-0x1000008e--kernel-mode-exception-not-handled-m.md) | +| 0x100000EA | [**THREAD\_STUCK\_IN\_DEVICE\_DRIVER\_M**](bug-check-0x100000ea--thread-stuck-in-device-driver-m.md) | +| 0x4000008A | [**THREAD\_TERMINATE\_HELD\_MUTEX**](bug-check-0x4000008a--thread-terminate-held-mutex.md) | +| 0xC0000218 | [**STATUS\_CANNOT\_LOAD\_REGISTRY\_FILE**](bug-check-0xc0000218--status-cannot-load-registry-file.md) | +| 0xC000021A | [**STATUS\_SYSTEM\_PROCESS\_TERMINATED**](bug-check-0xc000021a--status-system-process-terminated.md) | +| 0xC0000221 | [**STATUS\_IMAGE\_CHECKSUM\_MISMATCH**](bug-check-0xc0000221--status-image-checksum-mismatch.md) | +| 0xDEADDEAD | [**MANUALLY\_INITIATED\_CRASH1**](bug-check-0xdeaddead--manually-initiated-crash1.md) | + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Bug%20Check%20Code%20Reference%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bug-checks--blue-screens-.md b/windows-driver-docs-pr/debugger/bug-checks--blue-screens-.md new file mode 100644 index 0000000000..c325af0538 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-checks--blue-screens-.md @@ -0,0 +1,39 @@ +--- +title: Bug Checks (Blue Screens) +description: This topic covers bug checks (Blue Screens) +ms.assetid: 6ACE4AD9-5318-4c96-A560-D247033CB500 +keywords: bug check, blue screen, kernel error, stop error, stop code +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Bug Checks (Blue Screens) + + +## + + +This section includes: + +[General Tips for Blue Screens](general-troubleshooting-tips.md) + +[Blue Screen Data](blue-screen-data.md) + +[Bug Check Code Reference](bug-check-code-reference2.md) + +**Note**  These topic are for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://go.microsoft.com/fwlink/p/?linkid=183646). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Bug%20Checks%20%28Blue%20Screens%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/bug-checks-for-scsi-miniport-debugging.md b/windows-driver-docs-pr/debugger/bug-checks-for-scsi-miniport-debugging.md new file mode 100644 index 0000000000..51a2d2d4e8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/bug-checks-for-scsi-miniport-debugging.md @@ -0,0 +1,59 @@ +--- +title: Bug Checks for SCSI Miniport Debugging +description: Bug Checks for SCSI Miniport Debugging +ms.assetid: 9a517096-f708-452b-83f6-e7d4f0d41ac3 +keywords: ["SCSI Miniport debugging, bug checks"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Bug Checks for SCSI Miniport Debugging + + +There are primarily two bug checks that arise in the course of debugging a SCSI miniport driver: bug check 0x77 (KERNEL\_STACK\_INPAGE\_ERROR) and bug check 0x7A (KERNEL\_DATA\_INPAGE\_ERROR). For full details of their parameters, see [**Bug Check 0x77**](bug-check-0x77--kernel-stack-inpage-error.md) and [**Bug Check 0x7A**](bug-check-0x7a--kernel-data-inpage-error.md). + +Each of these bug checks indicates that a paging error has occurred. There are three main causes for these bug checks: + +- Full bus reset due to a timeout on a particular device or no activity on an adapter + +- Selection time-out + +- Controller errors + +To determine the precise cause of the failure, begin by using the [**!scsikd.classext**](-scsikd-classext.md) extension, which displays information about recently failed requests, including the SRB status, SCSI status, and sense data of the request. + +``` +kd> !scsikd.classext 816e96b0 +Storage class device 816e96b0 with extension at 816e9768 + +Classpnp Internal Information at 817b4008 + + Failed requests: + + Srb Scsi + Opcode Status Status Sense Code Sector Time Stamp + ------ ------ ------ ---------- -------- ------------ + 2a 0a 02 03 0c 00 0000abcd 23:01:07.453 Retried + 28 0a 02 03 04 00 0000abcd 23:01:07.984 Retried + +dt classpnp!_CLASS_PRIVATE_FDO_DATA 817b4008 - + +... +``` + +In the previous example, opcode 0x2A indicates a write operation, and 0x28 indicates a read operation. The SCSI status in the example is 02, which indicates a check condition. The sense codes provide more error information. + +As always, miniport driver developers are responsible for associating error codes from their hardware to the SRB status codes. Typically, timeouts are associated with SRB 0x0A, the code for a selection timeout. SRB 0x0e is typically associated with a full bus reset, but it can also be associated with controller errors. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Bug%20Checks%20for%20SCSI%20Miniport%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/building-dbgeng-extensions.md b/windows-driver-docs-pr/debugger/building-dbgeng-extensions.md new file mode 100644 index 0000000000..ea98b810fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/building-dbgeng-extensions.md @@ -0,0 +1,50 @@ +--- +title: Building DbgEng Extensions +description: Building DbgEng Extensions +ms.assetid: e2cf8a01-2099-4ad7-98ac-1a20c76a2e0a +keywords: ["DbgEng Extensions, building", "Build utility (build.exe), building DbgEng extensions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Building DbgEng Extensions + + +## + + +All debugger extensions should be compiled and built by using Visual Studio. The Build utility is no longer used with debugger extensions. + +For documentation on the Building projects in Visual Studio refer to [Building C++ Projects in Visual Studio.](https://msdn.microsoft.com/library/7s88b19e.aspx) + +To build an extension, use the following procedure: + +**To build a debugger extension** + +1. Open the **dbgsdk.sln** sample project in Visual Studio. + +2. Check the include and lib file project settings. If *%debuggers%* represents the root of your Debugging Tools for Windows installation, they should be set as follows: + + ``` + Include Path + %debuggers%\sdk\inc + Library Path + %debuggers%\sdk\lib + ``` + + If you have moved these headers and libraries to a different location, specify that location instead. + +3. Select **Build** and then **Build Solution** from the menu in Visual Studio. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Building%20DbgEng%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/building-extengcpp-extensions.md b/windows-driver-docs-pr/debugger/building-extengcpp-extensions.md new file mode 100644 index 0000000000..a3c17d4b92 --- /dev/null +++ b/windows-driver-docs-pr/debugger/building-extengcpp-extensions.md @@ -0,0 +1,51 @@ +--- +title: Building EngExtCpp Extensions +description: Building EngExtCpp Extensions +ms.assetid: 63d73c4e-03b8-4bbe-9c2e-96cda3ad544c +keywords: ["EngExtCpp extensions, building"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Building EngExtCpp Extensions + + +## + + +The EngExtCpp extension libraries are built almost the same way as the DbgEng extension libraries. For more information, see [Building DbgEng Extensions](building-dbgeng-extensions.md). + +The EngExtCpp implementation code (engextcpp.cpp) is used instead of linking with a static library. + +Because the EngExtCpp extension framework is built on top of the DbgEng extension framework, an EngExtCpp extension DLL should export the same functions as a DbgEng extension DLL. + +Each extension should be exported. When you use the [**EXT\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/ff544514) macro to define an extension function, this macro also creates a C function with the same name as the extension. This function should be exported from the DLL. + +The following functions are provided by engextcpp should be exported from the EngExtCpp DLL. + +- **DebugExtensionInitialize** -- so that the [**Initialize**](https://msdn.microsoft.com/library/windows/hardware/ff548226) method can be called to initialize the library. + +- **DebugExtensionUnitialize** -- so that the [**Uninitialize**](https://msdn.microsoft.com/library/windows/hardware/ff548226) method can be called to uninitialize the library. + +- **KnownStructOutputEx** -- so that the engine can call the [*ExtKnownStructMethod*](https://msdn.microsoft.com/library/windows/hardware/ff543989) methods to format known structures for output. + +- **DebugExtensionNotify** -- so that the engine can call the [**OnSessionActive**](https://msdn.microsoft.com/library/windows/hardware/ff548226), **OnSessionInactive**, **OnSessionAccessible**, and **OnSessionInaccessible** methods to notify the extension library of changes to the debugging session's state. + +- **help** -- so that the EngExtCpp extension framework can automatically provide a **!help** extension. + +These functions can be exported even if the functionality they provide is not needed. Moreover, if they are not exported, the functionality they provide will be lost. + +**DebugExtensionInitialize** must be exported in order for the debugger engine to recognize the DLL as a valid DbgEng extension DLL. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Building%20EngExtCpp%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/building-wdbgexts-extensions.md b/windows-driver-docs-pr/debugger/building-wdbgexts-extensions.md new file mode 100644 index 0000000000..95475dedeb --- /dev/null +++ b/windows-driver-docs-pr/debugger/building-wdbgexts-extensions.md @@ -0,0 +1,100 @@ +--- +title: Building WdbgExts Extensions +description: Building WdbgExts Extensions +ms.assetid: a3923de6-bed5-40e0-a9cb-99e0f4354448 +keywords: ["Build utility (build.exe), building WdbgExts extensions", "WdbgExts extensions, building", "WdbgExts extensions, compiling"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Building WdbgExts Extensions + + +## + + +All debugger extensions should be compiled and built with the Build utility. The Build utility is included in the Windows Driver Kit (WDK) and in earlier versions of the Windows DDK. + +For more information on the Build utility, see the WDK documentation. + +Note the following points: + +- The WDK has several different build environment windows. Each of these has a corresponding shortcut placed in the **Start** menu when the WDK is installed. To build a debugger extension, you must use the latest Windows build environment, regardless of what platform you will be running the extension on. + +- The Build utility is usually not able to compile code that is located in a directory path that contains spaces. Your extension code should be located in a directory whose full path contains no spaces. (In particular, this means that if you install Debugging Tools for Windows to the default location -- Program Files\\Debugging Tools for Windows -- you will not be able to build the sample extensions.) + +**To build a debugger extension** + +1. Open the window for the latest Windows build environment. (You can choose either the "free" version or the "checked" version -- they will give identical results unless you have put **\#ifdef DBG** statements in your code.) + +2. Set the variable \_NT\_TARGET\_VERSION to indicate the oldest version of Windows on which you want to run the extension. \_NT\_TARGET\_VERSION can be set to the following values. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueVersions of Windows

_NT_TARGET_VERSION_WIN2K

Windows 2000 and later.

_NT_TARGET_VERSION_WINXP

Windows XP and later.

_NT_TARGET_VERSION_WS03

Windows Server 2003 and later.

_NT_TARGET_VERSION_LONGHORN

Windows Vista and later.

+ +   + + If \_NT\_TARGET\_VERSION is not set, the extension will only run on the version of Windows for which the build window was opened (and later versions). For example, putting the following line in your Sources file will build an extension that will run on Windows XP and later versions of Windows: + + ``` + _NT_TARGET_VERSION = $(_NT_TARGET_VERSION_WINXP) + ``` + +3. 3.Set the DBGSDK\_INC\_PATH and DBGSDK\_LIB\_PATH environment variables to specify the paths to the debugger SDK headers and the debugger SDK libraries, respectively. If *%debuggers%* represents the root of your Debugging Tools for Windows installation, these variables should be set as follows: + + ``` + set DBGSDK_INC_PATH=%debuggers%\sdk\inc + set DBGSDK_LIB_PATH=%debuggers%\sdk\lib + ``` + + If you have moved these headers and libraries to a different location, specify that location instead. + +4. 4.Change the current directory to the directory that contains your extension's Dirs file or Sources file. + +5. 5.Run the Build utility: + ``` + build -cZMg + ``` + +For a full explanation of these steps, and for a description of how to create a Dirs file and a Sources file, see the Build utility documentation in the WDK. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Building%20WdbgExts%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/c---numbers-and-operators.md b/windows-driver-docs-pr/debugger/c---numbers-and-operators.md new file mode 100644 index 0000000000..8c7dae3bea --- /dev/null +++ b/windows-driver-docs-pr/debugger/c---numbers-and-operators.md @@ -0,0 +1,297 @@ +--- +title: C++ Numbers and Operators +description: C++ Numbers and Operators +ms.assetid: e5d3ac7f-fd79-48bb-b927-9ad72570dcbe +keywords: ["expressions, C++ expression syntax", "C++ expressions, numbers", "C++ expressions, operators", "numerical expressions, C++", "operators, C++", "precedence rules (C++)", "methods", "methods, syntax", "members of classes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# C++ Numbers and Operators + + +## + + +The C++ expression parser supports all forms of C++ expression syntax. The syntax includes all data types (including pointers, floating-point numbers, and arrays) and all C++ unary and binary operators. + +### Numbers in C++ Expressions + +Numbers in C++ expressions are interpreted as decimal numbers, unless you specify them in another manner. To specify a hexadecimal integer, add **0x** before the number. To specify an octal integer, add **0** (zero) before the number. + +The default debugger radix does not affect how you enter C++ expressions. You cannot directly enter a binary number (except by nesting a MASM expression within the C++ expression). + +You can enter a hexadecimal 64-bit value in the *xxxxxxxx***\`***xxxxxxxx* format. (You can also omit the grave accent ( **\`** ).) Both formats produce the same value. + +You can use the **L**, **U**, and **I64** suffixes with integer values. The actual size of the number that is created depends on the suffix and the number that you enter. For more information about this interpretation, see a C++ language reference. + +The *output* of the C++ expression evaluator keeps the data type that the C++ expression rules specify. However, if you use this expression as an argument for a command, a cast is always made. For example, you do not have to cast integer values to pointers when they are used as addresses in command arguments. If the expression's value cannot be validly cast to an integer or a pointer, a syntax error occurs. + +You can use the **0n** (decimal) prefix for some *output*, but you cannot use it for C++ expression input. + +### Characters and Strings in C++ Expressions + +You can enter a character by surrounding it with single quotation marks ( ' ). The standard C++ escape characters are permitted. + +You can enter string literals by surrounding them with double quotation marks ( " ). You can use **\\"** as an escape sequence within such a string. However, strings have no meaning to the [expression evaluator](evaluating-expressions.md). + +### Symbols in C++ Expressions + +In a C++ expression, each symbol is interpreted according to its type. Depending on what the symbol refers to, it might be interpreted as an integer, a data structure, a function pointer, or any other data type. If you use a symbol that does not correspond to a C++ data type (such as an unmodified module name) within a C++ expression, a syntax error occurs. + +If the symbol might be ambiguous, you can add a module name and an exclamation point ( **!** ) or only an exclamation point before the symbol. For more information about symbol recognition, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +You can use a grave accent ( **\`** ) or an apostrophe ( **'** ) in a symbol name only if you add a module name and exclamation point before the symbol name. + +When you add the **<** and **>** delimiters after a template name, you can add spaces between these delimiters. + +### Operators in C++ Expressions + +You can always use parentheses to override precedence rules. + +If you enclose part of a C++ expression in parentheses and add two at signs (**@@**) before the expression, the expression is interpreted according to MASM expression rules. You cannot add a space between the two at signs and the opening parenthesis. The final value of this expression is passed to the C++ expression evaluator as a ULONG64 value. You can also specify the expression evaluator by using **@@c++( ... )** or **@@masm( ... )**. + +Data types are indicated as usual in the C++ language. The symbols that indicate arrays ( **\[ \]** ), pointer members ( **->** ), UDT members ( **.** ), and members of classes ( **::** ) are all recognized. All arithmetic operators are supported, including assignment and side-effect operators. However, you cannot use the **new**, **delete**, and **throw** operators, and you cannot actually call a function. + +Pointer arithmetic is supported and offsets are scaled correctly. Note that you cannot add an offset to a function pointer. (If you have to add an offset to a function pointer, cast the offset to a character pointer first.) + +As in C++, if you use operators with invalid data types, a syntax error occurs. The debugger's C++ expression parser uses slightly more relaxed rules than most C++ compilers, but all major rules are enforced. For example, you cannot shift a non-integer value. + +You can use the following operators. The operators in each cell take precedence over those in lower cells. Operators in the same cell are of the same precedence and are parsed from left to right. As with C++, expression evaluation ends when its value is known. This ending enables you to effectively use expressions such as **?? myPtr && \*myPtr**. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning

Expression // Comment

Ignore all subsequent text

Class :: Member

+

Class ::~Member

+

:: Name

Member of class

+

Member of class (destructor)

+

Global

Structure . Field

+

Pointer -> Field

+

Name [integer]

+

LValue ++

+

LValue --

+

dynamic_cast <type>(Value)

+

static_cast <type>(Value)

+

reinterpret_cast <type>(Value)

+

const_cast <type>(Value)

Field in a structure

+

Field in referenced structure

+

Array subscript

+

Increment (after evaluation)

+

Decrement (after evaluation)

+

Typecast (always performed)

+

Typecast (always performed)

+

Typecast (always performed)

+

Typecast (always performed)

(type) Value

+

sizeof value

+

sizeof( type )

+

++ LValue

+

-- LValue

+

~ Value

+

! Value

+

Value

+

+ Value

+

& LValue

+

* Value

Typecast (always performed)

+

Size of expression

+

Size of data type

+

Increment (before evaluation)

+

Decrement (before evaluation)

+

Bit complement

+

Not (Boolean)

+

Unary minus

+

Unary plus

+

Address of data type

+

Dereference

Structure . * Pointer

+

Pointer -> * Pointer

Pointer to member of structure

+

Pointer to member of referenced structure

Value * Value

+

Value / Value

+

Value % Value

Multiplication

+

Division

+

Modulus

Value + Value

+

Value - Value

Addition

+

Subtraction

Value << Value

+

Value >> Value

Bitwise shift left

+

Bitwise shift right

Value < Value

+

Value <= Value

+

Value > Value

+

Value >= Value

Less than (comparison)

+

Less than or equal (comparison)

+

Greater than (comparison)

+

Greater than or equal (comparison)

Value == Value

+

Value != Value

Equal (comparison)

+

Not equal (comparison)

Value & Value

Bitwise AND

Value ^ Value

Bitwise XOR (exclusive OR)

Value | Value

Bitwise OR

Value && Value

Logical AND

Value || Value

Logical OR

LValue =Value

+

LValue *= Value

+

LValue /= Value

+

LValue %=Value

+

LValue +=Value

+

LValue -= Value

+

LValue <<= Value

+

LValue >>= Value

+

LValue &= Value

+

LValue |= Value

+

LValue ^= Value

Assign

+

Multiply and assign

+

Divide and assign

+

Modulo and assign

+

Add and assign

+

Subtract and assign

+

Shift left and assign

+

Shift right and assign

+

AND and assign

+

OR and assign

+

XOR and assign

Value ? Value : Value

Conditional evaluation

Value , Value

Evaluate all values, and then discard all except the rightmost value

+ +  + +### Registers and Pseudo-Registers in C++ Expressions + +You can use registers and pseudo-registers within C++ expressions. You must add an at sign ( **@** ) before the register or pseudo-register. + +The expression evaluator automatically performs the proper cast. Actual registers and integer-value pseudo-registers are cast to ULONG64. All addresses are cast to PUCHAR, **$thread** is cast to ETHREAD\*, **$proc** is cast to EPROCESS\*, **$teb** is cast to TEB\*, and **$peb** is cast to PEB\*. + +You cannot change a register or pseudo-register by an assignment or side-effect operator. You must use the [**r (Registers)**](r--registers-.md) command to change these values. + +For more information about registers and pseudo-registers, see [Register Syntax](register-syntax.md) and [Pseudo-Register Syntax](pseudo-register-syntax.md). + +### Macros in C++ Expressions + +You can use macros within C++ expressions. You must add a number sign (\#) before the macros. + +You can use the following macros. These macros have the same definitions as the Microsoft Windows macros with the same name. (The Windows macros are defined in Winnt.h.) + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MacroReturn Value

#CONTAINING_RECORD(Address, Type, Field)

Returns the base address of an instance of a structure, given the type of the structure and the address of a field within the structure.

#FIELD_OFFSET(Type, Field)

Returns the byte offset of a named field in a known structure type.

#RTL_CONTAINS_FIELD (Struct, Size, Field)

Indicates whether the given byte size includes the desired field.

#RTL_FIELD_SIZE(Type, Field)

Returns the size of a field in a structure of known type, without requiring the type of the field.

#RTL_NUMBER_OF(Array)

Returns the number of elements in a statically sized array.

#RTL_SIZEOF_THROUGH_FIELD(Type, Field)

Returns the size of a structure of known type, up through and including a specified field.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20C++%20Numbers%20and%20Operators%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/c--compare-memory-.md b/windows-driver-docs-pr/debugger/c--compare-memory-.md new file mode 100644 index 0000000000..d0e45a0e82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/c--compare-memory-.md @@ -0,0 +1,102 @@ +--- +title: c (Compare Memory) +description: The c command compares the values held in two memory areas. +ms.assetid: caa02ec3-35d6-4d41-a777-daa264b0dd18 +keywords: ["c (Compare Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- c (Compare Memory) +api_type: +- NA +--- + +# c (Compare Memory) + + +The **c** command compares the values held in two memory areas. + +``` +c Range Address +``` + +## Parameters + + + *Range* +The first of the two memory ranges to be compared. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Address* +The starting address of the second memory range to be compared. The size of this range will be the same as that specified for the first range. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +If the two areas are not identical, the debugger will display all memory addresses in the first range where they do not agree. + +As an example, consider the following code: + +``` +void main() +{ + char rgBuf1[100]; + char rgBuf2[100]; + + memset(rgBuf1, 0xCC, sizeof(rgBuf1)); + memset(rgBuf2, 0xCC, sizeof(rgBuf2)); + + rgBuf1[42] = 0xFF; +} +``` + +To compare **rgBuf1** and **rgBuf2**, use either of the following commands: + +``` +0:000> c rgBuf1 (rgBuf1+0n100) rgBuf2 + +0:000> c rgBuf1 L 0n100 rgBuf2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20c%20%28Compare%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/c.md b/windows-driver-docs-pr/debugger/c.md new file mode 100644 index 0000000000..eda529743a --- /dev/null +++ b/windows-driver-docs-pr/debugger/c.md @@ -0,0 +1,72 @@ +--- +title: C (Windows Debugger Glossary) +description: Glossary page - C +Robots: noindex, nofollow +ms.assetid: 295b05a3-e27f-4761-a562-7e87e25bfd3b +--- + +# C + + +**C++ expression** +An expression that can be evaluated by the C++ expression evaluator. + +**C call stack** +See call stack. + +**call stack** +The set of stack frames for each thread containing representing the function calls made by the thread. Each time a function call is made a new stack frame is pushed onto the top of the stack. When that function returns, the stack frame is popped off the stack. + +Sometimes referred to as the or simply the . + +**callback object** +See event callbacks, input callbacks, and output callbacks. + +**checked build** +Two different builds of each NT-based operating system exist: + +- The (or ) of Windows is the end-user version of the operating system. For details, see free build. +- The (or ) of Windows serves as a testing and debugging aid in the developing of the operating system and kernel-mode drivers. The checked build contains extra error checking, argument verification, and debugging information that is not available in the free build. , making it easier to trace the cause of problems in system software. A checked system or driver can help isolate and track down driver problems that can cause unpredictable behavior, result in memory leaks, or result in improper device configuration. + +Although the checked build provides extra protection, it consumes more memory and disk space than the free build. System and driver performance is slower, because additional code paths are executed due to parameter checking and output of diagnostic messages, and some alternate implementations of kernel functions are used. + +The checked build of Windows should not be confused with a driver that has been built in one of the Checked Build Environments of the Windows Driver Kit (WDK). + +**child symbol** +A symbol that is contained in another symbol. For example, the symbol for a member in a structure is a child of the symbol for that structure. + +**client** +See client object. + +**client object** +A client object is used for interaction with the debugger engine. It holds per-client state, and provides implementations for the top-level interfaces in the debugger engine API. + +**client thread** +The thread in which the client object was created. In general, a client's methods may be called only from this thread. The debugger engine uses this thread to make all calls to the callback object registered with the client. + +**code breakpoint** +See software breakpoint. + +**crash dump file** +A file that contains a snapshot of certain memory regions and other data related to an application or operating system. A crash dump file can be stored and then used to debug the application or operating system at a later time. + +A user-mode crash dump file can be created by Windows when an application crashes, and a kernel-mode crash dump file can be created by special Windows routines when Windows itself crashes. There are several different types of crash dump files. + +**current process** +The process that the debugger engine is currently controlling. When an event occurs, the current process is set to the event process. + +**current target** +The target that the debugger engine is currently controlling. When an event occurs, the current target is set to the event target. + +**current thread** +The thread that the debugger engine is currently controlling. When an event occurs, the current thread is set to the event thread. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20C%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/cab-files-that-contain-paging-files-along-with-a-memory-dump.md b/windows-driver-docs-pr/debugger/cab-files-that-contain-paging-files-along-with-a-memory-dump.md new file mode 100644 index 0000000000..a1bdd4d9cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/cab-files-that-contain-paging-files-along-with-a-memory-dump.md @@ -0,0 +1,68 @@ +--- +title: CAB Files that Contain Paging Files Along with a Memory Dump +description: A memory dump file can be placed in a cabinet (CAB) file along with paging files. +ms.assetid: 89B54522-1B21-4E4E-9AF3-1F637E3BA50F +--- + +# CAB Files that Contain Paging Files Along with a Memory Dump + + +A memory dump file can be placed in a cabinet (CAB) file along with paging files. When a Windows debugger analyzes the memory dump file, it can use the paging files to present a full view memory, including memory that was paged out when the dump file was created. + +Suppose a CAB file named MyCab.cab contains these files: + +Memory.dmp +Cabmanifest.xml +Pagefile.sys +Also suppose Cabmanifest.xml looks like this: + +```XML + + + + + + +``` + +You can open the CAB file by entering one of these commands: + +- **windbg /z MyCab.cab** +- **kd /z MyCab.cab** + +The debugger reads Cabmanifest.xml for a list of paging files that are to be included in the debugging session. In this example, there is only one paging file. The debugger converts the paging file to a Target Information File (TIF) file that it can use during the debugging session. Because the debugger has access to the TIF, it can display memory that was paged out at the time the dump file was created. + +Regardless of how many paging files are in the CAB file, the debugger uses only the paging files that are listed in Cabmanifest.xml. Here's an example of a CAB manifest file that lists three paging files. + +```XML + + + + + + + + +``` + +In Cabmanifest.xml, the paging files must be listed in the same order that Windows uses them. That is, they must be listed in the order that they appear in the Registry. + +The memory dump file that you put in the CAB file must be a complete memory dump. You can use Control Panel to configure Windows to create a complete memory dump when there is a crash. For example, in Windows 8 you can go to **Control Panel > System and Security > System > Advanced System Settings > Startup and Recovery**. As an alternative to using Control Panel, you can set the value of this registry entry to 1. + +**HKLM**\\**SYSTEM**\\**CurrentControlSet**\\**Control**\\**CrashControl**\\**CrashDumpEnabled** + +Starting in Windows 8.1, you can configure Windows to preserve the contents of paging files when Windows restarts. + +To specify that you want paging files to be saved when Windows restarts, set the value of this registry entry to 1. + +**HKLM**\\**SYSTEM**\\**CurrentControlSet**\\**Control**\\**CrashControl**\\**SavePageFileContents** + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CAB%20Files%20that%20Contain%20Paging%20Files%20Along%20with%20a%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/caching-acquired-symbol-files.md b/windows-driver-docs-pr/debugger/caching-acquired-symbol-files.md new file mode 100644 index 0000000000..0332dcb41f --- /dev/null +++ b/windows-driver-docs-pr/debugger/caching-acquired-symbol-files.md @@ -0,0 +1,66 @@ +--- +title: Caching Acquired Symbol Files +description: Caching Acquired Symbol Files +ms.assetid: 2aedc67f-27f3-46f4-8369-504e525b8c18 +keywords: ["SymProxy, caching"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Caching Acquired Symbol Files + + +Typically, SymProxy caches the files that it acquires in the directory designated within Internet Information Services (IIS) as the virtual root for the associated Web site. Then IIS makes the file available to the client debugger. Because the debugger cannot open a file directly from HTTP, it copies the file to a local cache, specified by the symbol path: + +``` +srv*c:\localcache*http://server/symbols +``` + +In this example, the client debugger copies the file to c:\\localcache. In a situation such as this, the file is copied twice - once by SymProxy to the virtual root of the Web site, and again by the debugger to its local cache. + +It is possible to avoid the second copy operation and speed up processing. To do this, you must first share the virtual root of the Web site as a UNC path that can be accessed by the debuggers. For sake of example, this path is named \\\\server\\symbols. You must then remove the IIS configuration for MIME types: + +**To remove the IIS configuration for MIME types** + +1. From **Administrative Tools** open **Internet Information Services (IIS) Manager**. + +2. Expand **Web Sites**. + +3. Right-click **Default Web Site**. + +4. Right-click the **Symbols** virtual directory and select **Properties**. + +5. Click the **HTTP Headers** tab. + +6. Click **MIME Types** . + +7. Select all types in the list box labeled **Registered MIME Types**. + +8. Click **Remove** . + +9. To exit the **MIME Types** dialog, click **OK**. + +10. To exit **Symbols Properties**, click **OK**. + +This causes IIS to return **file not found** to the debugging client for all transactions on the Web site. However, it does not prevent SymProxy from populating the virtual root with the file. + +After you remove the IIS configuration for MIME types, configure the debugger clients to look for symbols first in the HTTP store and in the share that maps to the virtual root of the store with the command: + +``` +srv**http://server/symbols;srv*\\server\symbols +``` + +In the preceding example, the first element of the symbol path (srv\*\*http://server/symbols) says to get files from the HTTP store and copy them to the default symbol store as a local cache. The specified cache is of no importance because no file is ever received from the HTTP store. After this failure, it attempts to obtain the file from the actual location of the virtual root of the store (srv\*\\\\server\\symbols). This attempt succeeds because the file is copied to that location as a side effect of the previous path processing. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Caching%20Acquired%20Symbol%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/calling-extensions-and-extension-functions.md b/windows-driver-docs-pr/debugger/calling-extensions-and-extension-functions.md new file mode 100644 index 0000000000..611315588a --- /dev/null +++ b/windows-driver-docs-pr/debugger/calling-extensions-and-extension-functions.md @@ -0,0 +1,68 @@ +--- +title: Calling Extensions and Extension Functions +description: Calling Extensions and Extension Functions +ms.assetid: 0582cdc2-7059-42db-878b-28767a6fe850 +keywords: ["Debugger Engine API, calling extensions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling Extensions and Extension Functions + + +To load an extension library (or to obtain a handle for an already loaded extension library), use [**AddExtension**](https://msdn.microsoft.com/library/windows/hardware/ff537892). An extension library can be unloaded with [**RemoveExtension**](https://msdn.microsoft.com/library/windows/hardware/ff554497). + +Extension commands can be called using [**CallExtension**](https://msdn.microsoft.com/library/windows/hardware/ff539023). + +### Extension Functions + +*Extension functions* are functions that are exported by extension libraries. They can use any function prototype and are called directly using C function pointers. + +They are not extension commands and are not available via debugger commands. Extension functions cannot be called remotely; they must be called directly. Hence they cannot be used from debugging clients. They can only be called when the client object is inside the host engine - when not remotely debugging or when using a smart client. + +Extension functions are identified within extension libraries by the "\_EFN\_" prepended to their names. + +To obtain a pointer to an extension function, use [**GetExtensionFunction**](https://msdn.microsoft.com/library/windows/hardware/ff546733). The type of this function pointer should match the prototype of the extension function. The extension function can now be called just like any other function pointer in C. + +### Example + +If the following extension function was included in an extension library and loaded into the debugger engine: + +``` +HRESULT CALLBACK +_EFN_GetObject(IDebugClient * client, SomeObject * obj); +``` + +It could be called using: + +``` +typedef ULONG (CALLBACK * GET_OBJECT)(IDebugClient * client, SomeObject * obj); + + + +HRESULT status = S_OK; +GET_OBJECT extFn = NULL; +SomeObject myObj; + +if (g_DebugControl-> + GetExtensionFunction(0, + "GetObject", + (FARPROC *) &extFn ) == S_OK && + extFn) +{ + status = (*extFn)(client, &myObj); +} +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Calling%20Extensions%20and%20Extension%20Functions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/calls-window.md b/windows-driver-docs-pr/debugger/calls-window.md new file mode 100644 index 0000000000..d1e7da1838 --- /dev/null +++ b/windows-driver-docs-pr/debugger/calls-window.md @@ -0,0 +1,75 @@ +--- +title: Viewing the Call Stack in WinDbg +description: In WinDbg, you can view the call stack by entering commands or by using the Calls window. +ms.assetid: 0e5b5611-d43c-40ba-8340-ea49fe18cc3f +keywords: ["debugging information windows, Calls window", "Calls window", "call stack, Calls window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Viewing the Call Stack in WinDbg + + +The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, the next function is the function that called the current function, and so on. The call stack that is displayed is based on the current program counter, unless you change the register context. For more information about how to change the register context, see [Changing Contexts](changing-contexts.md). + +In WinDbg, you can view the call stack by entering commands or by using the Calls window. + +## Debugger Command Window + + +You can view the call stack by entering one of the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands in the Debugger Command window. + +## Calls Window + + +As an alternative to the [**k**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command, you can view the call stack in the Calls window. To open the Calls window, choose **Call Stack** from the **View** menu. + +The following screen shot shows an example of a Calls window. + +![screen shot of the calls window](images/window-calls.png) + +## + + +Buttons in the Calls window enable you to customize the view of the call stack. To move to the corresponding call location in the [Source window](source-window.md) or [Disassembly window](disassembly-window.md), double-click a line of the call stack, or select a line and press ENTER. This action also changes the [local context](changing-contexts.md#local-context) to the selected stack frame. For more information about running to or from this point, see [Controlling the Target](controlling-the-target.md). + +In user mode, the stack trace is based on the stack of the current thread. For more information about the stack of the current thread, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +In kernel mode, the stack trace is based on the current register context. You can set the register context to match a specific thread, context record, or trap frame. For more information about setting the register context, see [Register Context](changing-contexts.md#register-context). + +The Calls window has a toolbar that contains several buttons and has a shortcut menu with additional commands. To access this menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button that displays the calls window toolbar shortcut menu](images/tbcall.png)). The toolbar and menu contain the following buttons and commands: + +- **Raw args** displays the first three parameters that are passed to the function. On an x86-based processor, this display includes the first three parameters that are passed to the function ("Args to Child"). + +- **Func info** displays Frame Pointer Omission (FPO) data and other internal information about the function. This command is available only on an x86-based processor. + +- **Source** displays source module names and line numbers after the function names (if the debugger has this information). + +- **Addrs** displays various frame-related addresses. On an x86-based processor, this display includes the base pointer for the stack frame ("ChildEBP") and the return address ("RetAddr"). + +- **Nonvolatile regs** displays the nonvolatile portion of the register context. This command is available only on an Itanium-based processor. + +- **Frame nums** displays frame numbers. Frames are always numbered consecutively, beginning with zero. + +- **Arg types** displays detailed information about the arguments that are expected and received by the functions in the stack. + +- **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +### Additional Information + +For more information about the register context and the local context, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20the%20Call%20Stack%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/canceling-requests-for-special-pool.md b/windows-driver-docs-pr/debugger/canceling-requests-for-special-pool.md new file mode 100644 index 0000000000..68b889224f --- /dev/null +++ b/windows-driver-docs-pr/debugger/canceling-requests-for-special-pool.md @@ -0,0 +1,35 @@ +--- +title: Canceling Requests for Special Pool +description: Canceling Requests for Special Pool +ms.assetid: fb18cb15-33ee-4e6d-856e-70c4ffbf8383 +--- + +# Canceling Requests for Special Pool + + +## + + +You can use GFlags to cancel a request for allocation from the special pool if the request was made by using GFlags. You cannot use GFlags to cancel a request for special pool that was made by using Driver Verifier. + +In Windows Vista and later versions of Windows, you can also use the command line to cancel special pool requests. For information, see [**GFlags Commands**](gflags-commands.md). + +**To cancel requests for special pool** + +1. Select the System Registry tab or the Kernel Flags tab. + + On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the **System Registry** tab. + +2. Delete the text or hexadecimal value from the **Kernel Special Pool Tag** box. + +3. Click **Apply**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Canceling%20Requests%20for%20Special%20Pool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/cdb-and-windbg.md b/windows-driver-docs-pr/debugger/cdb-and-windbg.md new file mode 100644 index 0000000000..44f8e5ccfd --- /dev/null +++ b/windows-driver-docs-pr/debugger/cdb-and-windbg.md @@ -0,0 +1,43 @@ +--- +title: CDB and WinDbg +description: CDB and WinDbg +ms.assetid: 840dbe3c-510c-4064-ae6c-bb7525841621 +keywords: ["dump file, CDB", "dump file, WinDbg"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CDB and WinDbg + + +## + + +CDB and WinDbg can create user-mode dump files in a variety of ways. + +### Creating a Dump File Automatically + +When an application error occurs, Windows can respond in several different ways, depending on the postmortem debugging settings. If these settings instruct a debugging tool to create a dump file, a user-mode memory dump file will be created. For more information, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +### Creating Dump Files While Debugging + +When CDB or WinDbg is debugging a user-mode application, you can also the [**.dump (Create Dump File)**](-dump--create-dump-file-.md) command to create a dump file. + +This command does not cause the target application to terminate. By selecting the proper command options, you can create a minidump file that contains exactly the amount of information you wish. + +### Shrinking an Existing Dump File + +CDB and WinDbg can also be used to *shrink* a dump file. To do this, begin debugging an existing dump file, and then use the **.dump** command to create a dump file of smaller size. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CDB%20and%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/cdb-command-line-options.md b/windows-driver-docs-pr/debugger/cdb-command-line-options.md new file mode 100644 index 0000000000..76197f6cac --- /dev/null +++ b/windows-driver-docs-pr/debugger/cdb-command-line-options.md @@ -0,0 +1,435 @@ +--- +title: CDB Command-Line Options +description: First-time users of CDB or NTSD should begin with the Debugging Using CDB and NTSD section. +ms.assetid: 34dbb695-19e4-4efc-83c7-3a94e5fcf269 +keywords: ["CDB Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CDB Command-Line Options +api_type: +- NA +--- + +# CDB Command-Line Options + + +First-time users of CDB or NTSD should begin with the [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md) section. + +The CDB command line uses the following syntax: + +``` +cdb [ -server ServerTransport | -remote ClientTransport ] +[ -premote SmartClientTransport ] [-log{a|au|o|ou} LogFile] +[-2] [-d] [-ddefer] [-g] [-G] [-hd] [-lines] [-myob] [-bonc] +[-n] [-o] [-s] [-v] [-w] [-cf "filename"] [-cfr "filename"] [-c "command"] +[-robp] [-r BreakErrorLevel] [-t PrintErrorLevel] +[ -x{e|d|n|i} Exception ] [-x] [-clines lines] +[-i ImagePath] [-y SymbolPath] [-srcpath SourcePath] +[-aExtension] [-failinc] [-noio] [-noinh] [-noshell] [-nosqm] +[-sdce] [-ses] [-sicv] [-sins] [-snc] [-snul] [-zp PageFile] +[-sup] [-sflags 0xNumber] [-ee {masm|c++}] +[-e Event] [-pb] [-pd] [-pe] [-pr] [-pt Seconds] [-pv] +[ -- | -p PID | -pn Name | -psn ServiceName | -z DumpFile | executable ] +[-cimp] [-isd] [-kqm] [-pvr] [-version] [-vf] [-vf:] [-netsyms:{yes|no}] + +cdb -iae + +cdb -iaec KeyString + +cdb -iu KeyString + +cdb -QR Server + +cdb -wake pid + +cdb -? +``` + +The NTSD command-line syntax is identical to that of CDB: + +``` +ntsd [ -server ServerTransport | -remote ClientTransport ] +[ -premote SmartClientTransport ] [-log{a|au|o|ou} LogFile] +[-2] [-d] [-ddefer] [-g] [-G] [-hd] [-lines] [-myob] [-bonc] +[-n] [-o] [-s] [-v] [-w] [-cf "filename"] [-cfr "filename"] [-c "command"] +[-robp] [-r BreakErrorLevel] [-t PrintErrorLevel] +[ -x{e|d|n|i} Exception ] [-x] [-clines lines] +[-i ImagePath] [-y SymbolPath] [-srcpath SourcePath] +[-aExtension] [-failinc] [-noio] [-noinh] [-noshell] [-nosqm] +[-sdce] [-ses] [-sicv] [-sins] [-snc] [-snul] [-zp PageFile] +[-sup] [-sflags 0xNumber] [-ee {masm|c++}] +[-e Event] [-pb] [-pd] [-pe] [-pr] [-pt Seconds] [-pv] +[ -- | -p PID | -pn Name | -psn ServiceName | -z DumpFile | executable ] +[-cimp] [-isd] [-kqm] [-pvr] [-version] [-vf] [-vf:] [-netsyms:{yes|no}] + +ntsd -iae + +ntsd -iaec KeyString + +ntsd -iu KeyString + +ntsd -QR Server + +ntsd -wake PID + +ntsd -? +``` + +The only difference between NTSD and CDB is that NTSD spawns a new console window while CDB inherits the window from which it was invoked. Since the **start** command can also be used to spawn a new console window, the following two constructions will give the same results: + +``` +start cdb [parameters] +ntsd [parameters] +``` + +Descriptions of the CDB and NTSD command-line options follow. Only the **-remote**, **-server**, **-g** and **-G** options are case-sensitive. The initial hyphen can be replaced with a forward-slash (/). Options that do not take any additional parameters can be concatenated -- so **cdb -o -d -G -g winmine** can be written as **cdb -odGg winmine**. + +If the **-remote** or **-server** option is used, it must appear before any other options on the command line. If an *executable* is specified, it must appear last on the command line; any text after the *executable* name is passed to the executable program as its own command-line parameters. + +## Parameters + + + **-server** *ServerTransport* +Creates a debugging server that can be accessed by other debuggers. For an explanation of the possible *ServerTransport* values, see [**Activating a Debugging Server**](activating-a-debugging-server.md). When this parameter is used, it must be the first parameters on the command line. + + **-remote** *ClientTransport* +Creates a debugging client, and connects to a debugging server that is already running. For an explanation of the possible *ClientTransport* values, see [**Activating a Debugging Client**](activating-a-debugging-client.md). When this parameter is used, it must be the first parameters on the command line. + + **-premote** *SmartClientTransport* +Creates a smart client, and connects to a process server that is already running. For an explanation of the possible *SmartClientTransport* values, see [**Activating a Smart Client**](activating-a-smart-client.md). + + **-2** +If the target application is a *console application*, this option causes it to live in a new console window. (The default is for a target console application to share the window with CDB or NTSD.) + + **--** +Debugs the Client Server Run-Time Subsystem (CSRSS). For details, see [Debugging CSRSS](debugging-csrss.md). + + **-a** *Extension* +Sets the default extension DLL. The default is *userexts*. There must be no space after the "a", and the .dll extension must not be included. For details, and other methods of setting this default, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + + **-bonc** +If this option is specified, the debugger will break into the target as soon as the session begins. This is especially useful when connecting to a debugging server that might not be currently broken into the target. + + **-c "** *command* **"** +Specifies the initial debugger command to run at start-up. This command must be surrounded with quotation marks. Multiple commands can be separated with semicolons. (If you have a long command list, it may be easier to put them in a script and then use the **-c** option with the [**$<, $><, $><, $$>< (Run Script File)**](-----------------------a---run-script-file-.md) command.) + +If you are starting a debugging client, this command must be intended for the debugging server. Client-specific commands such as **.lsrcpath** are not allowed. + + **-cf "** *filename* **"** +Specifies the path and name of a script file. This script file is executed as soon as the debugger is started. If *filename* contains spaces it must be enclosed in quotation marks. If the path is omitted, the current directory is assumed. If the **-cf** option is not used, the file ntsd.ini in the current directory is used as the script file. If the file does not exist, no error occurs. For details, see [Using Script Files](using-script-files.md). + + **-cfr "** *filename* **"** +Specifies the path and name of a script file. This script file is executed as soon as the debugger is started, and any time the target is restarted. If *filename* contains spaces it must be enclosed in quotation marks. If the path is omitted, the current directory is assumed. If the file does not exist, no error occurs. For details, see [Using Script Files](using-script-files.md). + + **-cimp** +Directs CDB/NTSD to start with a DbgSrv implicit command line instead of an explicit process to run. This option is the client side of dbgsrv -pc. + + **-clines** *lines* +Sets the approximate number of commands in the command history which can be accessed during remote debugging. For details, and for other ways to change this number, see [Using Debugger Commands](using-debugger-commands.md). + + **-d** +Passes control of this debugger to the kernel debugger. If you are debugging CSRSS, this control redirection always is active, even if **-d** is not specified. (This option cannot be used during remote debugging -- use **-ddefer** instead.) See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. This option cannot be used in conjunction with either the **-ddefer** option or the **-noio** option. + +**Note**  If you use WinDbg as the kernel debugger, many of the familiar features of WinDbg are not available in this scenario. For example, you cannot use the Locals window, the Disassembly window, or the Call Stack window, and you cannot step through source code. This is because WinDbg is only acting as a viewer for the debugger (NTSD or CDB) running on the target computer. + +  + + **-ddefer** +Passes control of this debugger to the kernel debugger, unless a debugging client is connected. (This is a variation of **-d** that can be used from a debugging server.) See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. This option cannot be used in conjunction with either the **-d** option or the **-noio** option. + + **-e** *Event* +Signals the debugger that the specified event has occurred. This option is only used when starting the debugger programmatically. + + **-ee** {**masm**|**c++**} +Sets the default expression evaluator. If **masm** is specified, MASM expression syntax will be used. If **c++** is specified, C++ expression syntax will be used. If the **-ee** option is omitted, MASM expression syntax is used as the default. See [Evaluating Expressions](evaluating-expressions.md) for details. + + **-failinc** +Causes the debugger to ignore any questionable symbols. When debugging a user-mode or kernel-mode minidump file, this option will also prevent the debugger from loading any modules whose images can't be mapped. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-g** +Ignores the initial breakpoint in target application. This option will cause the target application to continue running after it is started or CDB attaches to it, unless another breakpoint has been set. See [Initial Breakpoint](initial-breakpoint.md) for details. + + **-G** +Ignores the final breakpoint at process termination. By default, CDB stops during the image run-down process. This option will cause CDB to exit immediately when the child terminates. This has the same effect as entering the command **sxd epr**. For more information, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + + **-hd** +(Microsoft Windows XP and later) Specifies that the debug heap should not be used. See [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md) for details. + + **-i** *ImagePath* +Specifies the location of the executables that generated the fault. If the path contains spaces, it should be enclosed in quotation marks. + + **-iae** +Installs CDB as the postmortem debugger. For details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +If this action succeeds, no message is displayed; if it fails, an error message is displayed. + +The **-iae** parameter must not be used with any other parameters. This command will not actually start CDB. + + **-iaec** *KeyString* +Installs CDB as the postmortem debugger. The contents of *KeyString* will be appended to the end of the **AeDebug** registry key. If *KeyString* contains spaces, it must be enclosed in quotation marks. For details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +If this action succeeds, no message is displayed; if it fails, an error message is displayed. + +The **-iaec** parameter must not be used with any other parameters. This command will not actually start CDB. + + **-isd** +Turns on the CREATE\_IGNORE\_SYSTEM\_DEFAULT flag for any process creations. + + **-iu** *KeyString* +Registers debugger remoting as an URL type so that users can auto-launch a debugger remote client with an URL. *KeyString* has the format `remdbgeng://RemotingOption`. *RemotingOption* is a string that defines the transport protocol as defined in the topic [**Activating a Debugging Client**](activating-a-debugging-client.md). If this action succeeds, no message is displayed; if it fails, an error message is displayed. + +The **-iu** parameter must not be used with any other parameters. This command will not actually start CDB. + + **-kqm** +Starts CDB/NTSD in quiet mode. + + **-lines** +Enables source line debugging. If this option is omitted, the [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command will have to be used before source debugging will be allowed. For other methods of controlling this, see [SYMOPT\_LOAD\_LINES](symbol-options.md#symopt-load-lines). + + **-log**{**a|au|o|ou**} *LogFile* +Begins logging information to a log file. If the specified file already exists, it will be overwritten if **-logo** is used, or output will be appended to the file if -loga is used. The **-logau** and **-logou** options operate similar to **-loga** and **-logo** respectively, except that the log file is a Unicode file. For more details, see [Keeping a Log File in CDB](keeping-a-log-file-in-cdb.md). + + **-myob** +If there is a version mismatch with dbghelp.dll, the debugger will continue to run. (Without the **-myob** switch, this is considered a fatal error.) + + **-n** +*Noisy symbol load*: Enables verbose output from the symbol handler. For details and for other methods of controlling this, see [SYMOPT\_DEBUG](symbol-options.md#symopt-debug). + + **-netsyms {yes|no}** +Allow or disallow loading symbols from a network path. + + **-noinh** +Prevents processes created by the debugger from inheriting handles from the debugger. For other methods of controlling this, see [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md). + + **-noio** +Prevents the debugging server from being used for input or output. Input will only be accepted from the debugging client (plus any initial command or command script specified by the **-c** command-line option). + +All output will be directed to the debugging client. If NTSD is used for the server, no console window will be created at all. For more details, see [**Activating a Debugging Server**](activating-a-debugging-server.md). This option cannot be used in conjunction with either the **-d** option or the **-ddefer** option. + + **-noshell** +Prohibits all **.shell** commands. This prohibition will last as long as the debugger is running, even if a new debugging session is begun. For details, and for other ways to disable **.shell** commands, see [Using Shell Commands](using-shell-commands.md). + + **-nosqm** +Disables telemetry data collection and upload. + + **-o** +Debugs all processes launched by the target application (child processes). By default, processes created by the one you are debugging will run as they normally do. For other methods of controlling this, see [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md). + + **-p** *PID* +Specifies the decimal process ID to be debugged. This is used to debug a process that is already running. For details, see [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md). + + **-pb** +(Windows XP and later) Prevents the debugger from requesting an initial break-in when attaching to a target process. This can be useful if the application is already suspended, or if you wish to avoid creating a break-in thread in the target. + + **-pd** +(Windows XP and later) Causes the target application not to be terminated at the end of the debugging session. See [Ending a Debugging Session in CDB](ending-a-debugging-session-in-cdb.md) for details. + + **-pe** +(Windows XP and later) Indicates that the target application is already being debugged. See [Re-attaching to the Target Application](reattaching-to-the-target-application.md) for details. + + **-pn** *Name* +Specifies the name of the process to be debugged. (This name must be unique.) This is used to debug a process that is already running. + + **-pr** +(Windows XP and later) Causes the debugger to start the target process running when it attaches to it. This can be useful if the application is already suspended and you wish it to resume execution. + + **-psn** *ServiceName* +Specifies the name of a service contained in the process to be debugged. This is used to debug a process that is already running. + + **-pt** *Seconds* +Specifies the break time-out, in seconds. The default is 30. See [Controlling the Target](controlling-the-target.md) for details. + + **-pv** +Specifies that the debugger should attach to the target process noninvasively. For details, see [Noninvasive Debugging (User Mode)](noninvasive-debugging--user-mode-.md). + + **-pvr** +Works like **-pv** except that the target process is not suspended. + + **-QR** *Server* +Lists all debugging servers running on the specified network server. The double backslash (\\\) preceding *Server* is optional. See [**Searching for Debugging Servers**](searching-for-debugging-servers.md) for details. + +The **-QR** parameter cannot be used with any other parameters. This command will not actually start CDB. + + **-r** *BreakErrorLevel* +Specifies the error level that will cause the target to break into the debugger. This is a decimal number equal to 0, 1, 2, or 3. Possible values are as follows: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueConstantMeaning

0

NONE

Do not break on any errors.

1

ERROR

Break on ERROR level debugging events.

2

MINORERROR

Break on MINORERROR and ERROR level debugging events.

3

WARNING

Break on WARNING, MINORERROR, and ERROR level debugging events.

+ +  + +This error level only has meaning in checked builds of Microsoft Windows. The default value is 1. + + **-robp** +This allows CDB to set a breakpoint on a read-only memory page. (The default is for such an operation to fail.) + + **-s** +Disables lazy symbol loading. This will slow down process startup. For details and for other methods of controlling this, see [SYMOPT\_DEFERRED\_LOADS](symbol-options.md#symopt-deferred-loads). + + **-sdce** +Causes the debugger to display **File access error** dialog boxes during symbol load. For details and for other methods of controlling this, see [SYMOPT\_FAIL\_CRITICAL\_ERRORS](symbol-options.md#symopt-fail-critical-errors). + + **-ses** +Causes the debugger to perform a strict evaluation of all symbol files and ignore any questionable symbols. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-sflags 0x** *Number* +Sets all the symbol handler options at once. *Number* should be a hexadecimal number prefixed with **0x** -- a decimal without the **0x** is permitted, but the symbol options are binary flags and therefore hexadecimal is recommended. This option should be used with care, since it will override all the symbol handler defaults. For details, see [Setting Symbol Options](symbol-options.md). + + **-sicv** +Causes the symbol handler to ignore the CV record. For details and for other methods of controlling this, see [SYMOPT\_IGNORE\_CVREC](symbol-options.md#symopt-ignore-cvrec). + + **-sins** +Causes the debugger to ignore the symbol path and executable image path environment variables. For details, see [SYMOPT\_IGNORE\_NT\_SYMPATH](symbol-options.md#symopt-ignore-nt-sympath). + + **-snc** +Causes the debugger to turn off C++ translation. For details and for other methods of controlling this, see [SYMOPT\_NO\_CPP](symbol-options.md#symopt-no-cpp). + + **-snul** +Disables automatic symbol loading for unqualified names. For details and for other methods of controlling this, see [SYMOPT\_NO\_UNQUALIFIED\_LOADS](symbol-options.md#symopt-no-unqualified-loads). + + **-srcpath** *SourcePath* +Specifies the source file search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Source Path](source-path.md). + + **-sup** +Causes the symbol handler to search the public symbol table during every symbol search. For details and for other methods of controlling this, see [SYMOPT\_AUTO\_PUBLICS](symbol-options.md#symopt-auto-publics). + + **-t** *PrintErrorLevel* +Specifies the error level that will cause the debugger to display an error message. This is a decimal number equal to 0, 1, 2, or 3. Possible values are as follows: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueConstantMeaning

0

NONE

Do not display any errors.

1

ERROR

Display ERROR level debugging events.

2

MINORERROR

Display MINORERROR and ERROR level debugging events.

3

WARNING

Display WARNING, MINORERROR, and ERROR level debugging events.

+ +  + +This error level only has meaning in checked builds of Microsoft Windows. The default value is 1. + + **-v** +Enables verbose output from the debugger. + + **-version** +Prints the debugger version string. + + **-vf** +Enables default ApplicationVerifier settings. + + **-vf:** *<opts>* +Enables given ApplicationVerifier settings. + + **-w** +Specifies to debug 16-bit applications in a separate VDM. + + **-wake** *PID* +Causes sleep mode to end for the user-mode debugger whose process ID is specified by *PID*. This command must be issued on the target machine during sleep mode. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +The **-wake** parameter should not be used with any other parameters. This command will not actually start CDB. + + **-x**{**e**|**d**|**n**|**i**} *Exception* +Controls the debugger's behavior when the specified event occurs. The *Exception* can be either an exception number or an event code. You can specify this option multiple times to control different events. See [Controlling Exceptions and Events](controlling-exceptions-and-events.md) for details and for other methods of controlling these settings. + + **-x** +Disables first-chance break on access violation exceptions. The second occurrence of an access violation will break into the debugger. This is the same as **-xd av**. + + **-y** *SymbolPath* +Specifies the symbol search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Symbol Path](symbol-path.md). + + **-z** *DumpFile* +Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several dump files at once by including multiple **-z** options, each followed by a different *DumpFile* value. For details, see [Analyzing a User-Mode Dump File with CDB](analyzing-a-user-mode-dump-file-with-cdb.md). + + **-zp** *PageFile* +Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the [**.pagein (Page In Memory)**](-pagein--page-in-memory-.md) command. You cannot use **-zp** with a standard Windows page file -- only specially-modified page files can be used. + + *executable* +Specifies the command line of an executable process. This is used to launch a new process and debug it. This has to be the final item on the command line. All text after the executable name is passed to the executable as its argument string. + + **-?** +Displays command-line help text. + +When you are starting the debugger from **Start | Run** or from a Command Prompt window, specify arguments for the target application after the application's file name. For instance: + +``` +cdb myexe arg1arg2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CDB%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/changing-contexts.md b/windows-driver-docs-pr/debugger/changing-contexts.md new file mode 100644 index 0000000000..642b05b870 --- /dev/null +++ b/windows-driver-docs-pr/debugger/changing-contexts.md @@ -0,0 +1,121 @@ +--- +title: Changing Contexts +description: Changing Contexts +ms.assetid: 3690903c-4281-4c65-98b0-00ca22206168 +keywords: ["context", "logon session, context", "context, session context", "session, context", "user sessions", "session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Changing Contexts + + +## + + +In kernel-mode debugging, there are many processes, threads, and sometimes user sessions that are executing at the same time. Therfore, phrases such as "virtual address 0x80002000" or "the **eax** register" are ambiguous. You must specify the *context* in which such phrases can be understood. + +The debugger has five different contexts that you can set while you are debugging: + +1. The session context indicates the default user session. (This context applies to only Microsoft Windows XP and later versions of Windows. These operating systems allow multiple logon sessions to coexist.) + +2. The process context determines how the debugger interprets virtual addresses. + +3. The *user-mode address context* is almost never set directly. This context is automatically set when you change the process context. + +4. The register context determines how the debugger interprets registers and also controls the results of a stack trace. This context is also known as the *thread context*, although that term is not completely accurate. An *explicit context* is also a type of register context. If you specify an explicit context, that context is used instead of the current register context. + +5. The local context determines how the debugger interprets local variables. This context is also known as the *scope*. + +### Session Context + +In Windows XP and later versions of Windows, multiple logon sessions can run at the same time. Each logon session has its own processes. + +The [**!session**](-session.md) extension displays all logon sessions or changes the current session context. + +The session context is used by the [**!sprocess**](-sprocess.md) and [**!spoolused**](https://msdn.microsoft.com/library/windows/hardware/ff565361) extensions when the session number is entered as "-2". + +When the session context is changed, the process context is automatically changed to the active process for that session. + +### Process Context + +Each process has its own page directory that records how virtual addresses are mapped to physical addresses. When any thread within a process is executing, the Windows operating system uses this page directory to interpret virtual addresses. + +During user-mode debugging, the current process determines the process context. Virtual addresses that are used in debugger commands, extensions, and debugging information windows are interpreted by using the page directory of the current process. + +During kernel-mode debugging, you can set the process context by using the [**.process (Set Process Context)**](-process--set-process-context-.md) command. Use this command to select which process's page directory is used to interpret virtual addresses. After you set the process context, you can use this context in any command that takes addresses. You can even set breakpoints at this address. By including a **/i** option in the **.process** command to specify invasive debugging, you can also use the kernel debugger to set breakpoints in user space. + +You can also set user-mode breakpoints from the kernel debugger by using a process-specific breakpoint on a kernel-space function. Set strategic breakpoints and wait for the appropriate context to come up. + +The *user-mode address context* is part of the process context. Typically, you do not have to set the user-mode address context directly. If you set the process context, the user-mode address context automatically changes to the directory base of the relevant page table for the process. However, on an Itanium-based processor, a single process might have more than one page directory. In this situation, you can use the [**.context (Set User-Mode Address Context)**](-context--set-user-mode-address-context-.md) command to change the user-mode address context. + +When you set the process context during kernel-mode debugging, that process context is retained until another **.process** command changes the context. The user-mode address context is also retained until a **.process** or **.context** command changes it. These contexts are not changed when the target computer executes, and they are not affected by changes to the register context or the local context. + +### Register Context + +Each thread has its own register values. These values are stored in the CPU registers when the thread is executing and are stored in memory when another thread is executing. + +During user-mode debugging, the current thread typically determines the register context. Any reference to registers in debugger commands, extensions, and debugging information windows is interpreted according to the current thread's registers. + +You can change the register context to a value other than the current thread while you are performing user-mode debugging by using one of the following commands: + +[**.cxr (Display Context Record)**](-cxr--display-context-record-.md) + +[**.ecxr (Display Exception Context Record)**](-ecxr--display-exception-context-record-.md) + +During kernel-mode debugging, you can control the register context by using a variety of debugger commands, including the following commands: + +[**.thread (Set Register Context)**](-thread--set-register-context-.md) + +[**.cxr (Display Context Record)**](-cxr--display-context-record-.md) + +[**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) + +These commands do not change the values of the CPU registers. Instead, the debugger retrieves the specified register context from its location in memory. Actually, the debugger can retrieve only the *saved* register values. (Other values are set dynamically and are not saved. The saved values are sufficient to re-create a stack trace. + +After the register context is set, the new register context is used for any commands that use register values, such as [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) and [**r (Registers)**](r--registers-.md). + +However, when you are debugging multiprocessor computers, some commands enable you to specify a processor. (For more information about such commands, see [Multiprocessor Syntax](multiprocessor-syntax.md).) If you specify a processor for a command, the command uses the register context of the active thread on the specified processor instead of the current register context, even if the specified processor is the currently-active processor. + +Also, if the register context does not match the current processor mode setting, these commands produce incorrect or meaningless output. To avoid the output errors, commands that depend on the register state fail until you change the processor mode to match the register context. To change the processor mode, use the [**.effmach (Effective Machine)**](-effmach--effective-machine-.md) command, + +Changing the register context can also change the local context. In this manner, the register context can affect the display of local variables. + +If any application execution, stepping, or tracing occurs, the register context is immediately reset to match the program counter's position. In user mode, the register context is also reset if the current process or thread is changed. + +The register context affects stack traces, because the stack trace begins at the location that the stack pointer register (**esp** on an x86-based processor or **sp** on an Itanium-based processor) points to. If the register context is set to an invalid or inaccessible value, stack traces cannot be obtained. + +You can apply a processor breakpoint (data breakpoint) to a specific register context by using the [**.apply\_dbp (Apply Data Breakpoint to Context)**](-apply-dbp--apply-data-breakpoint-to-context-.md) command. + +### Local Context + +When a program is executing, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the function that they are defined in. + +When you are performing user-mode or kernel-mode debugging, the debugger uses the scope of the current function (the current frame on the stack) as the local context. To change this context, use the [**.frame (Set Local Context)**](-frame--set-local-context-.md) command, or double-click the desired frame in the [Calls window](calls-window.md). + +In user-mode debugging, the local context is always a frame within the stack trace of the current thread. In kernel-mode debugging, the local context is always a frame within the stack trace of the current register context's thread. + +You can use only one stack frame at a time for the local context. Local variables in other frames cannot be accessed. + +The local context is reset if any of the following events occur: + +- Any program execution, stepping or tracing + +- Any use of the thread delimiter (~) in any command + +- Any change to the register context + +The [**!for\_each\_frame**](-for-each-frame.md) extension enables you to execute a single command repeatedly, once for each frame in the stack. This command changes the local context for each frame, executes the specified command, and then returns the local context to its original value. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Changing%20Contexts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/changing-text-properties.md b/windows-driver-docs-pr/debugger/changing-text-properties.md new file mode 100644 index 0000000000..6ad4d9694d --- /dev/null +++ b/windows-driver-docs-pr/debugger/changing-text-properties.md @@ -0,0 +1,43 @@ +--- +title: Changing Text Properties +description: Changing Text Properties +ms.assetid: 90f514da-064e-4d14-a4f3-856ccb534e76 +keywords: ["debugging information windows, text properties", "text properties of debugging information windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Changing Text Properties + + +## + + +You can customize the font that is used in all of the debugging information windows. You can also change the tab width that is used in the [Source windows](source-window.md). + +### Setting the Font, Font Style, and Font Size + +All debugging information windows share the same font. To change this font, click **Font** on the **View** menu, or click the **Font** button (![screen shot of the font button](images/tbfont.png)) on the toolbar. + +In the **Font** dialog box, select the font, style, and size from the appropriate lists, and then click **OK**. All of the available fonts are fixed-pitch, because these kinds of fonts are the most useful for viewing code. + +### Setting the Tab Width + +To change the tab width settings, click **Options** on the **View** menu or click the **Options** button (![screen shot of the options button](images/tbopt.png)) on the toolbar. + +The **Options** dialog box then appears. In the **Tab width** box, enter the number of spaces that the tab width should be equivalent to, and then click **OK**. + +The tab settings affect the display of the code in any Source window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Changing%20Text%20Properties%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/checking-and-updating-status.md b/windows-driver-docs-pr/debugger/checking-and-updating-status.md new file mode 100644 index 0000000000..e053518e96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/checking-and-updating-status.md @@ -0,0 +1,26 @@ +--- +title: Checking and Updating Status +description: Checking and Updating Status +ms.assetid: 60b81369-e81b-4795-a729-a535c38a0999 +keywords: ["SymProxy, status", "SymProxy, checking status", "SymProxy, updating status"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Checking and Updating Status + + +It is possible to see where SymProxy is configured to acquire symbols by using a web browser. Add *\\status* to the server URL get the status information. For example, if the symbols Web site is http://symbols.contoso.com, go to http://symbols.contoso.com/status. You can also use this to cause symproxy to re-read its configuration information after making a change to the registry. This changes the paths without having to restart the IIS service. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Checking%20and%20Updating%20Status%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/checking-for-resource-conflicts.md b/windows-driver-docs-pr/debugger/checking-for-resource-conflicts.md new file mode 100644 index 0000000000..1fdecb4491 --- /dev/null +++ b/windows-driver-docs-pr/debugger/checking-for-resource-conflicts.md @@ -0,0 +1,422 @@ +--- +title: Checking for Resource Conflicts +description: Checking for Resource Conflicts +ms.assetid: c994085c-8610-487f-88a5-f11b4a68ec4a +keywords: ["Plug and Play (PnP), resource conflicts", "resource conflicts"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Checking for Resource Conflicts + + +## + + +This section discusses techniques that can be used to detect resource conflicts. + +The first technique involves dumping the arbiter data. The following example examines the arbiter data for the I/O ranges: + +``` +kd> !arbiter 1 + +DEVNODE ff0daf48 + Port Arbiter "RootPort" at 8045b920 + Allocated ranges: + 10 - 1f S Owner ff0d6b30 + 22 - 3f S Owner ff0d6b30 + 44 - 47 S Owner ff0d6b30 + 4c - 6f S Owner ff0d6b30 + 72 - 7f S Owner ff0d6b30 + 90 - 91 S Owner ff0d6b30 + 93 - 9f S Owner ff0d6b30 + a2 - bf S Owner ff0d6b30 + d0 - ef S Owner ff0d6b30 + 100 - 2f7 S Owner ff0d6b30 + 300 - cf7 S Owner ff0d6b30 + d00 - ffff S Owner ff0d6b30 + Possible allocation: + < none > + + DEVNODE ff0d2e28 (PCI_HAL\PNP0A03\0) + Port Arbiter "PCI I/O Port (b=00)" at e122c2c8 + Allocated ranges: + 0 - f Owner 00000000 + 20 - 21 Owner 00000000 + 40 - 43 Owner 00000000 + 48 - 4b Owner 00000000 + 60 - 60 Owner ff0d4030 + 64 - 64 Owner ff0d4030 + 70 - 71 Owner 00000000 + 80 - 8f Owner 00000000 + 92 - 92 Owner 00000000 + a0 - a1 Owner 00000000 + c0 - cf Owner 00000000 + f0 - ff Owner 00000000 + 170 - 177 Owner ff0cf030 + 1ce - 1cf S Owner ff040040 + 2f8 - 2ff Owner 00000000 + 376 - 376 Owner ff0cf030 + 378 - 37f Owner ff0d4e70 + 3b0 - 3bb S Owner ff040040 + 3c0 - 3cf S Owner ff0bb900 + 3c0 - 3df S Owner ff040040 + 3d4 - 3db S Owner ff0bb900 + 3de - 3df S Owner ff0bb900 + 3ec - 3ef Owner ff0d0b50 (This device conflicts with another device, see below) + 3f2 - 3f5 Owner ff0d4770 + 3f7 - 3f7 S Owner ff0d4770 + 3f8 - 3ff Owner ff0d4af0 + 778 - 77b Owner ff0d4e70 + cf8 - cff Owner 00000000 + 1000 - 10ff Owner ff0d1030 + 1400 - 140f Owner ff0d1d30 + 1410 - 141f Owner ff0d1890 + 10000 - ffffffffffffffff Owner 00000000 + Possible allocation: + < none > +``` + +Note that there are two arbiters: one located in the root of the device tree, and one in PCI\_HAL. Also note that the PCI arbiter claims and preallocates ranges for the devices it arbitrates (0xD000-0xFFFF, which is later suballocated by the PCI arbiter for its devices). The Owner field indicates the device object that owns the range. A value of zero for Owner indicates that the range is not on the bus. In the case of a PCI bridge, for example, all the ranges it does not pass will be assigned to **NULL**. + +In the following example, the PCI bridge passes I/O 0xD000-0xDFFFF so its arbiter will contain the following two ranges: + +``` +0-CFFFF Owner 00000000 +E0000-FFFFFFFFFFFFFFFF Owner 00000000 +``` + +The FFFFFFFFFFFFFFFF is because all arbitrated resources are treated as 64-bit ranges. + +**Examples:** + +``` +kd> !devobj ff0bb900 + +Device object (ff0bb900) is for: + Video0 \Driver\mga_mil DriverObject ff0bbc10 +Current Irp 00000000 RefCount 1 Type 00000023 Flags 0000204c +DevExt ff0bb9b8 DevNode ff0bb808 +Device queue is not busy. +kd> !devnode ff0bb808 + +DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff + Parent 0xff0daf48 Sibling 0000000000 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c + Flags (0x00000400) DNF_RESOURCE_REPORTED +kd> !devnode ff0bb808 6 + +DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff + Parent 0xff0daf48 Sibling 0000000000 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c + Flags (0x00000400) DNF_RESOURCE_REPORTED + CmResourceList at 0xe12474e8 Version 0.0 Interface 0x5 Bus #0 + Entry 0 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3c0 for 0x10 bytes + Entry 1 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3d4 for 0x8 bytes + Entry 2 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3de for 0x2 bytes + Entry 3 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + Range starts at 0x0000000040000000 for 0x4000 bytes + Entry 4 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + Range starts at 0x0000000040800000 for 0x800000 bytes +``` + +As shown in the example, this operation retrieved the legacy video card that owns the range 3c0-3cf. The same device object is listed near the other ranges it owns (3de-3df and 3d4-3dc). Using the same tracking technique, the range of 3f8-3ff is determined to be that used by the serial port. + +A similar technique is required to translate the interrupts: + +``` +kd> !arbiter 4 + +DEVNODE ff0daf48 + Interrupt Arbiter "RootIRQ" at 8045bae0 + Allocated ranges: + 31 - 31 Owner ff0d4030 + 34 - 34 S Owner ff0d4af0 + 36 - 36 Owner ff0d4770 + 3b - 3b S Owner ff0d1030 + 3b - 3b S Owner ff0d1d30 + 3c - 3c Owner ff0d3c70 + 3f - 3f Owner ff0cf030 + Possible allocation: + < none > +``` + +Note that there is a single arbiter for interrupts: the root arbiter. + +For example, translate the interrupt 3F to an IRQ. First dump the device object, then the devnode: + +``` +kd> !devobj ff0cf030 + +Device object (ff0cf030) is for: + IdeFdoff0d0398Channel1 \Driver\IntelIde DriverObject ff0d0530 +Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040AttachedDev ff0cd030 + +DevExt ff0cf0e8 DevNode ff0cfe88 +Device queue is not busy. +kd> !devnode ff0cfe88 6 + +DevNode 0xff0cfe88 for PDO 0xff0cf030 at level 0x3 + Parent 0xff0d1348 Sibling 0000000000 Child 0xff0c84a8 + InterfaceType 0xffffffff Bus Number 0xfffffff0 + InstancePath is "PCIIDE\IDEChannel\1&1" + ServiceName is "atapi" + TargetDeviceNotify List - f 0xff0cfeec b 0xff0cfeec + Flags (0x6000120b) DNF_PROCESSED, DNF_STARTED, + DNF_ENUMERATED, DNF_RESOURCE_ASSIGNED, + DNF_ADDED, DNF_HAS_BOOT_CONFIG + Unknown flags 0x40000000 + CmResourceList at 0xe12321c8 Version 0.0 Interface 0x1 Bus #0 + Entry 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x170 for 0x8 bytes + Entry 1 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x376 for 0x1 bytes + Entry 2 - Interrupt (0x2) Device Exclusive (0x1) + Flags (0x01) - LATCHED + Level 0xf, Vector 0xf, Affinity 0xffffffff + + IoResList at 0xe12363c8 : Interface 0x1 Bus 0 Slot 0 + Reserved Values = {0x0002e0d0, 0x00920092, 0xe1235508} + Alternative 0 (Version 1.1) + Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Shared (0x3) + Flags (0000) - + Data: : 0x1 0x61004d 0x680063 + Preferred Descriptor 1 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000008 byte range with alignment 0x000001 + 170 - 0x177 + Preferred Descriptor 2 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000001 byte range with alignment 0x000001 + 376 - 0x376 + Preferred Descriptor 3 - Interrupt (0x2) Device Exclusive (0x1) + Flags (0x01) - LATCHED + 0xf - 0xf + Alternative 1 (Version 1.1) + Preferred Descriptor 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000008 byte range with alignment 0x000001 + 170 - 0x177 + Preferred Descriptor 1 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000001 byte range with alignment 0x000001 + 376 - 0x376 + Preferred Descriptor 2 - Interrupt (0x2) Device Exclusive (0x1) + Flags (0x01) - LATCHED + 0xf - 0xf +``` + +For example, try to determine if there is a resource conflict that caused this device not to start, starting with a **devnode**: + +``` +kd> !devnode 0xff0d4bc8 6 + +DevNode 0xff0d4bc8 for PDO 0xff0d4cb0 at level 0 + Parent 0xff0daf48 Sibling 0xff0d4a08 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + InstancePath is "Root\*PNP0501\1_0_17_2_0_0" + ServiceName is "Serial" + TargetDeviceNotify List - f 0xff0d4c2c b 0xff0d4c2c + Flags (0x60001129) DNF_PROCESSED, DNF_ENUMERATED, + DNF_MADEUP, DNF_INSUFFICIENT_RESOURCES, + DNF_ADDED, DNF_HAS_BOOT_CONFIG + Unknown flags 0x40000000 + + IoResList at 0xe1251e28 : Interface 0x1 Bus 0 Slot 0 + Reserved Values = {0x0043005c, 0x006e006f, 0x00720074} + Alternative 0 (Version 1.1) + Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Undetermined Shar +ing (0) + Flags (0000) - + Data: : 0xc000 0x0 0x0 + Preferred Descriptor 1 - Port (0x1) Undetermined Sharing (0) + Flags (0x05) - PORT_IO 10_BIT_DECODE + 0x000008 byte range with alignment 0x000001 + 3e8 - 0x3ef + Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3) + Flags (0x01) - LATCHED + 0x5 - 0x5 + Alternative 1 (Version 1.1) + Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Undetermined Shar +ing (0) + Flags (0000) - + Data: : 0xc000 0x0 0x0 + Preferred Descriptor 1 - Port (0x1) Undetermined Sharing (0) + Flags (0x05) - PORT_IO 10_BIT_DECODE + 0x000008 byte range with alignment 0x000008 + 3e8 - 0x3ef + Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3) + Flags (0x01) - LATCHED + 0x5 - 0x5 +``` + +First, make the assumption that this is an I/O conflict and dump the arbiters (see the preceding example). The result shows that the range 0x3EC-0x3EF is owned by 0xFF0D0B50, which overlaps the serial device's resources request. Next, dump the device object for the owner of this range, and then dump the devnode for the owner: + +``` +kd> !devobj ff0d0b50 + +Device object (ff0d0b50) is for: + Resource00413e \Driver\isapnp DriverObject ff0d0e10 +Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040 +DevExt ff0d0c08 DevNode ff0d0a68 +Device queue is not busy. +kd> !devnode ff0d0a68 6 + +DevNode 0xff0d0a68 for PDO 0xff0d0b50 at level 0xffffffff + Parent 0xff0daf48 Sibling 0000000000 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff +Duplicate PDO 0xff0d0e10 TargetDeviceNotify List - f 0xff0d0acc b 0xff0d0acc + Flags (0x00000421) DNF_PROCESSED, DNF_MADEUP, + DNF_RESOURCE_REPORTED + CmResourceList at 0xe1233628 Version 0.0 Interface 0x1 Bus #0 + Entry 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3ec for 0x4 bytes +``` + +This is a "pseudo-devnode" that corresponds to the range allocated by the ISAPNP driver for its read data port. + +To determine the resources that the PnP Manager assigned to a particular device when it attempted to start the device: + +1. Place a breakpoint on the routine that is called when the IRP\_MN\_START\_DEVICE request is received by the driver. You can also place a breakpoint on the driver's dispatch routine (if you know its name). In both cases, the driver and its symbols should be loaded. This may require you to set an initial breakpoint. + + For example, for PCMCIA you can set a breakpoint on **pcmcia!pcmciastartpccard**. The advantage of using this particular routine is that its second parameter is a CM Resource List that you can dump using **!cmreslist** (eliminating step 3). See the following PCMCIA example. + +2. When you have determined which device is of interest, dump the device object (if you have not done so already), and then dump the devnode with the CM Resource List. Check which resources were assigned to the device. You may also check whether the resources are a subset of the I/O Resource List. Then type **g** or single step through the procedure, and determine whether the device was started and which resources were assigned. If a device was offered a set of resources to start but failed to do so, the driver might not be behaving properly (for example, if it incorrectly declared that it can use a set of resources it cannot actually use). + +**Example:** + +``` +ntoskrnl!IopStartDevice: +80420212 55 push ebp +kd> kb +ChildEBP RetAddr Args to Child +f64138c0 8048b640 ff0ce870 ff0d7c08 ff0cde88 ntoskrnl!IopStartDevice (!devobj ff0ce870) +f64138f0 8048d8e7 ff0cde88 f6413978 ff0cddc8 ntoskrnl!IopStartAndEnumerateDevice ++0x1a +f6413900 8048de7f ff0cde88 f6413978 ff0cf448 ntoskrnl!IopProcessStartDevicesWork +er+0x43 +f6413910 8048d8d5 ff0cf448 8048d8a4 f6413978 ntoskrnl!IopForAllChildDeviceNodes+ +0x1f +f6413924 8048de7f ff0cf448 f6413978 ff0d3f48 ntoskrnl!IopProcessStartDevicesWork +er+0x31 +f6413934 8048d8d5 ff0d3f48 8048d8a4 f6413978 ntoskrnl!IopForAllChildDeviceNodes+ +0x1f +f6413948 8048d893 ff0d3f48 f6413978 e12052e8 ntoskrnl!IopProcessStartDevicesWork +er+0x31 +f641395c 804f6f1b ff0d7c08 f6413978 8045c520 ntoskrnl!IopProcessStartDevices+0x1 +f +f64139d0 804f5cc1 80088000 f6413aec 8045bba0 ntoskrnl!IopInitializeBootDrivers+0 +x2f9 +f6413b24 804f4db3 80088000 00000001 00000000 ntoskrnl!IoInitSystem+0x3a6 +f6413da8 80447610 80088000 00000000 00000000 ntoskrnl!Phase1Initialization+0x6a3 + +f6413ddc 8045375a 804f4710 80088000 00000000 ntoskrnl!PspSystemThreadStartup+0x5 +4 +00000000 00000000 00000000 00000000 00000000 ntoskrnl!KiThreadStartup+0x16 +kd> !devobj ff0ce870 + +Device object (ff0ce870) is for: + NTPNP_PCI0002 \Driver\PCI DriverObject ff0ceef0 +Current Irp 00000000 RefCount 0 Type 00000022 Flags 00001040AttachedDev ff0cb9e0 + +DevExt ff0ce928 DevNode ff0cde88 +Device queue is not busy. +kd> !devnode ff0cde88 6 + +DevNode 0xff0cde88 for PDO 0xff0ce870 at level 0x2 + Parent 0xff0cf448 Sibling 0xff0cddc8 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + InstancePath is "PCI\VEN_8086&DEV_7010\0&69" + ServiceName is "intelide" + TargetDeviceNotify List - f 0xff0cdeec b 0xff0cdeec + Flags (0x00001209) DNF_PROCESSED, DNF_ENUMERATED, + DNF_RESOURCE_ASSIGNED, DNF_ADDED + (note that the device is not yet started) + CmResourceList at 0xe120fce8 Version 0.0 Interface 0x5 Bus #0 + Entry 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0xfff0 for 0x10 bytes (these are the resources used: 0xfff0-0xffff) + Entry 1 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data - {0x00000001, 0x00000004, 0000000000} + + IoResList at 0xe120df88 : Interface 0x5 Bus 0 Slot 0x2d + Alternative 0 (Version 1.1) + Descriptor 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_IO + 0x000010 byte range with alignment 0x000010 + 0 - 0xffff (it could have used any 16 bytes that are 16-byte aligned between 0 and 0xffff) + Descriptor 1 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data: : 0x1 0x4 0x0 +``` + +Example for PCMCIA: + +``` +kd> bp pcmcia!pcmciastartpccard +Loading symbols for 0x8039d000 pcmcia.sys -> pcmcia.sys +kd> kb +Loading symbols for 0x80241000 ndis.sys -> ndis.sys +ChildEBP RetAddr Args to Child +f6413814 803a7cbd ff0d0c30 e11d8808 ff0d0c30 pcmcia!PcmciaStartPcCard +f6413838 803a3798 ff0d0c30 ff0d1500 ff0d1588 pcmcia!PcmciaPdoPnpDispatch+0x169 +f6413848 80418641 ff0d0c30 ff0d1588 00000000 pcmcia!PcmciaDispatch+0x3a +f641385c 802455cf ff0d1614 ff0d1638 00040000 ntoskrnl!IofCallDriver+0x35 +f641387c 802497cf ff0d1588 ff0d0c30 ff0c8210 NDIS!ndisPassIrpDownTheStack+0x3b +f64138ac 80418641 ff0c8210 ff0d161c ff0d1640 NDIS!ndisPnPDispatch+0x1f9 +f64138c0 8048de68 ff0c3508 ff0d16a8 00000000 ntoskrnl!IofCallDriver+0x35 +f64138d4 8041ff5e ff0c8210 f64138f8 ff0c3508 ntoskrnl!IopAsynchronousCall+0x90 +f6413920 8048b4ae ff0d0c30 ff0e0a68 ff0d16a8 ntoskrnl!IopStartDevice+0x76 +f6413950 8048d707 ff0d16a8 f64139fc 00000000 ntoskrnl!IopStartAndEnumerateDevice+0x1a +f6413960 8048dc9f ff0d16a8 f64139fc ff0d1e88 ntoskrnl!IopProcessStartDevicesWorker+0x43 +f6413970 8048d6f5 ff0d1e88 8048d6c4 f64139fc ntoskrnl!IopForAllChildDeviceNodes+0x1f +f6413984 8048dc9f ff0d1e88 f64139fc ff0d3268 ntoskrnl!IopProcessStartDevicesWorker+0x31 +f6413994 8048d6f5 ff0d3268 8048d6c4 f64139fc ntoskrnl!IopForAllChildDeviceNodes+0x1f +f64139a8 8048dc9f ff0d3268 f64139fc ff0d7b28 ntoskrnl!IopProcessStartDevicesWorker+0x31 +f64139b8 8048d6f5 ff0d7b28 8048d6c4 f64139fc ntoskrnl!IopForAllChildDeviceNodes+0x1f +f64139cc 8048d6b3 ff0d7b28 f64139fc 80087000 ntoskrnl!IopProcessStartDevicesWorker+0x31 +f64139e0 804f6c97 ff0e0a68 f64139fc 8045c140 ntoskrnl!IopProcessStartDevices+0x1f +f6413a30 804f5601 000001e0 80087000 00000000 ntoskrnl!IopInitializeSystemDrivers+0x5b +f6413b7c 804f4820 80087000 00000001 00000000 ntoskrnl!IoInitSystem+0x3fe +kd> !cmreslist e11d8808 + +CmResourceList at 0xe11d8808 Version 0.0 Interface 0x1 Bus #0 + Entry 0 - Interrupt (0x2) Device Exclusive (0x1) + Flags (0x01) - LATCHED + Level 0x9, Vector 0x9, Affinity 0xffffffff + Entry 1 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0xdfe0 for 0x20 bytes (started with IRQ 9, IO dfe0-dfff) + Entry 2 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data - {0x00010120, 0000000000, 0000000000} + +kd> g +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Checking%20for%20Resource%20Conflicts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/checking-for-stuck-threads.md b/windows-driver-docs-pr/debugger/checking-for-stuck-threads.md new file mode 100644 index 0000000000..de25ecab3a --- /dev/null +++ b/windows-driver-docs-pr/debugger/checking-for-stuck-threads.md @@ -0,0 +1,53 @@ +--- +title: Checking for Stuck Threads +description: Checking for Stuck Threads +ms.assetid: ffb1ff13-fc4c-4aaf-a8fe-b473b51b9db0 +keywords: ["RPC debugging, stuck threads"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Checking for Stuck Threads + + +## + + +RPC needs its worker threads available in order to perform normally. A common problem is that some component in the same process will deadlock while holding one of the global critical sections (for example, loader lock or heap lock). This will cause many threads to hang -- very possibly including some RPC worker threads. + +If this occurs, the RPC server will not respond to the outside world. RPC calls to it will return RPC\_S\_SERVER\_UNAVAILABLE or RPC\_S\_SERVER\_TOO\_BUSY. + +A similar problem can result if a faulty driver prevents IRPs from completing and reaching the RPC server. + +If you suspect that one of these problems may be occurring, use DbgRpc with the **-t** switch (or use the [**!rpcexts.getthreadinfo**](-rpcexts-getthreadinfo.md) extension). The process ID should be used as a parameter. In the following example, assume the process ID is 0xC4: + +``` +D:\wmsg>dbgrpc -t -P c4 +Searching for thread info ... +## PID CELL ID ST TID LASTTIME +----------------------------------- +00c4 0000.0004 03 0000011c 000f164f +00c4 0000.0007 03 00000120 008a6290 +00c4 0000.0015 03 0000018c 008a6236 +00c4 0000.0026 03 00000264 0005c443 +00c4 0000.002d 03 00000268 000265bb +00c4 0000.0030 03 0000026c 000f1d32 +00c4 0000.0034 03 00000388 007251e9 +``` + +The TID column gives the thread ID for each thread. The LASTTIME column contains the time stamp of the last change in state for each thread. + +Whenever the server receives a request, at least one thread will change state, and its time stamp will be updated. Therefore, if an RPC request is made to the server and the request fails but none of the time stamps change, this indicates that the request is not actually reaching the RPC Run-Time. You should investigate the cause of this. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Checking%20for%20Stuck%20Threads%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-a-32-bit-or-64-bit-debugger-package.md b/windows-driver-docs-pr/debugger/choosing-a-32-bit-or-64-bit-debugger-package.md new file mode 100644 index 0000000000..6368ca2a06 --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-a-32-bit-or-64-bit-debugger-package.md @@ -0,0 +1,52 @@ +--- +title: Choosing the 32-Bit or 64-Bit Debugging Tools +description: When you install Debugging Tools for Windows, you get both a 32-bit set of tools and a 64-bit set of tools. +ms.assetid: 26aaaf11-1005-4ae7-8f27-4ae0812faa81 +keywords: ["32-bit debugger package", "32-bit debugging tools", "64-bit debugger package", "64-bit debugging tools", "installation, choosing between 32-bit and 64-bit packages"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Choosing the 32-Bit or 64-Bit Debugging Tools + + +When you install Debugging Tools for Windows, you get both a 32-bit set of tools and a 64-bit set of tools. If you use the Microsoft Visual Studio [debugging environment](debuggers-in-the-debugging-tools-for-windows-package.md), you don't have to be concerned about whether to use the 32- or 64-bit set because Visual Studio automatically chooses the correct debugging tools. + +If you are using one of the other debugging environments (WinDbg, KD, CDB, or NTSD), you have to make the choice yourself. To determine which set of debugging tools to use, you need to know the type of processor that is running on your host computer and whether the host computer is running a 32- or 64-bit version of Windows. + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. + +### Host computer running a 32-bit version of Windows + +If your host computer is running a 32-bit version of Windows, use the 32-bit debugging tools. (This situation applies to both x86-based and x64-based targets.) + +### x64-based host computer running a 64-bit version of Windows + +If your host computer uses an x64-based processor and is running a 64-bit version of Windows, the following rules apply: + +- If you are analyzing a dump file, you can use either the 32-bit debugging tools or the 64-bit debugging tools. (It is not important whether the dump file is a user-mode dump file or a kernel-mode dump file, and it is not important whether the dump file was made on an x86-based or an x64-based platform.) + +- If you are performing live kernel-mode debugging, you can use either the 32-bit debugging tools or the x64 debugging tools. (This situation applies to both x86-based and x64-based targets.) + +- If you are debugging live user-mode code that is running on the same computer as the debugger, use the 64-bit tools for debugging 64-bit code and 32-bit code running on WOW64. To set the debugger for 32-bit or 64-bit mode, use the [**.effmach**](-effmach--effective-machine-.md) command. + +- If you are debugging live 32-bit user-mode code that is running on a separate target computer, use the 32-bit debugging tools. + +## Related topics + + +[Windows Debugging](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20the%2032-Bit%20or%2064-Bit%20Debugging%20Tools%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-network-security-credentials.md b/windows-driver-docs-pr/debugger/choosing-network-security-credentials.md new file mode 100644 index 0000000000..f8125d6d4d --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-network-security-credentials.md @@ -0,0 +1,114 @@ +--- +title: Choosing Network Security Credentials +description: Choosing Network Security Credentials +ms.assetid: f53bda2b-a5e7-4a8e-ac31-44c92f306b7a +keywords: ["SymProxy, network security"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Choosing Network Security Credentials + + +The symbol proxy server must run from a security context with the appropriate privileges for access to the symbol stores that you plan to use. If you obtain symbols from an external Web store such as https://msdl.microsoft.com/download/symbols, the symbol proxy server must access the Web from outside of any firewalls. If you obtain files from other computers on your network, the symbol proxy server must have appropriate privileges to read files from those locations. Two possible choices are to set the symbol proxy server to authenticate as the **Network Service** account or to create a user account that is managed within Active Directory Domain Services along with other user accounts. + +**Note**   It is a good practice to limit privileges of this account to only those necessary to read files and copy them to c:\\symstore. This restriction prevents clients that access your HTTP store from corrupting the system. + +  + +**Note**  Make sure the options presented here make sense in your environment. Different organizations have different security needs and requirements. Modify the process outlined here to support the security requirements of your organization. + +  + +### Authenticate as a Network Service + +The **Network Service** account is built in to Windows, so there is no extra step of creating a new account. For this example, we name the computer where the symbol proxy server is being configured *SymMachineName* on a domain named *corp*. + +External symbol stores or Internet proxies must be configured to allow this computer's **Network Service** account (Machine Account) to authenticate successfully. There are two ways to achieve this: + +- Allow access to the **Authenticated Users** group on the external store or Internet proxy. + +- Allow access to the Machine Account *corp\\SymMachineName$*. This option is more secure because it limits access to just the symbol proxy server's "Network Service" account. + +### Authenticate as a Domain User + +For this example, we will presume the user account is named *SymProxyUser* on a domain called *corp*. + +**To add the user account to the IIS\_USRS group** + +1. From **Administrative Tools** open **Computer Management**. + +2. Expand **Local Users and Groups**. + +3. Click **Groups**. + +4. Double-click **IIS\_USRS** in the center pane and select **Properties**. + +5. Under the **Members** section, click **Add**. + +6. Type *corp\\SymProxyUser* in the pane labeled **Enter the object name to select**. + +7. To exit the **Select Users, Computer, or Groups** dialog box, click **OK**. + +8. To exit **IIS\_USRS Properties**, click **OK**. + +9. Close the **Computer Management** console. + +**Set up IIS to use the account** + +1. From **Administrative Tools** open **Internet Information Services (IIS) Manager**. + +2. Expand **Web Sites**. + +3. Right click **Default Web Site** and choose **Properties**. + +4. Click the **Directory Security** tab. + +5. In the **Authentication and access control** section, click **Edit…**. + +6. Make sure that *Enable anonymous access* is checked. + +7. Enter the credentials of the account that has permissions to access the remote symbol server store(s) (“corp\\SymProxyUser”) , then click **OK**. + +8. Re-enter the password when asked and click **OK**. + +9. To exit **Default Web Site Properties**, click **OK**. + +10. You may be presented with the *Inheritance Overrides* dialog. If so, select which virtual directories you want to have this apply to. + +### Authenticate as a Domain User Using the IIS\_WPG group + +For this example, the user account is named *SymProxyUser* on a domain named *corp*. To authenticate this user account, it must be added to the **IIS\_WPG** group. + +**To add the user account to the IIS\_WPG group** + +1. From **Administrative Tools** open **Computer Management**. + +2. Expand **Local Users and Groups**. + +3. Click **Groups**. + +4. Double-click **IIS\_WPG** in the right pane. + +5. Click **Add**. + +6. Type *corp\\SymProxyUser* in the pane labeled **Enter the object name to select**. + +7. To exit the **Select Users, Computer, or Groups** dialog box, click **OK**. + +8. To exit **IIS\_WPG Properties**, click **OK**. + +9. Close the **Computer Management** console. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20Network%20Security%20Credentials%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-the-best-method.md b/windows-driver-docs-pr/debugger/choosing-the-best-method.md new file mode 100644 index 0000000000..c2fa74e7e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-the-best-method.md @@ -0,0 +1,42 @@ +--- +title: Choosing the Best Method +description: Choosing the Best Method +ms.assetid: d6069c8c-1da1-4930-b75d-efcee9691e6b +--- + +# Choosing the Best Method + + +There are several different ways to debug a service application. In order to choose the correct method, you must first make two choices: the time at which the debugger is attached to the service application and what debugging configuration to use. + +There are three stages at which the debugger can be attached to the service application: + +- The very beginning of the service startup. The debugger is automatically launched when the service begins. Choose this option if you want to debug the service's initialization code. + +- The first time that the service encounters an exception. The debugger is automatically launched when an exception or crash occurs or if the service application calls the **DebugBreak** function. Choose this option if you want the debugger to appear when a problem is encountered but not before. + +- After the service is running normally. You can manually attach a debugger to a service that is already running at any time. Choose this option if you do not want to make advance preparations for debugging. + +There are three debugging configurations you can choose: + +- Local debugging. A single debugger, running on the same computer as the service. + +- Remote debugging. A debugging server running on the same computer as the service, being controlled from a debugging client running on a second computer. + +- Kernel-controlled user-mode debugging. A user-mode debugger running on the same computer as the service, being controlled from a kernel debugger on a second computer. + +If your service is running on Windows 2000, Windows XP, or Windows Server 2003, you can combine any of these three attach options with any of these three debugging configuration options. + +If your service is running on Windows Vista or a later version of Windows, there is one restriction on how these choices can be combined. If you want to debug from the beginning of the service startup, or from the time that an exception is encountered, you must use either remote debugging or kernel-controlled user-mode debugging. + +In other words, on Windows Vista and later, you cannot use local debugging unless you plan to attach the debugger manually after the service is already running. This restriction results from the fact that in these versions of Windows, services run in session 0, and any debugger that is automatically launched and attached to the service is also in session 0, and does not have a user interface on the computer that the service is running on. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20the%20Best%20Method%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-the-best-remote-debugging-method.md b/windows-driver-docs-pr/debugger/choosing-the-best-remote-debugging-method.md new file mode 100644 index 0000000000..cb0d1be018 --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-the-best-remote-debugging-method.md @@ -0,0 +1,63 @@ +--- +title: Choosing the Best Remote Debugging Method +description: Choosing the Best Remote Debugging Method +ms.assetid: af048b78-cb80-44d2-854f-11e0991e3353 +keywords: ["remote debugging, choosing the best method"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Choosing the Best Remote Debugging Method + + +## + + +There are two primary methods of performing remote debugging, as well as several additional methods and a huge number of combination methods. + +Here are some tips to help you choose the best technique. + +- [Remote debugging through the debugger](remote-debugging-through-the-debugger.md) is usually the best method. If you simply have one server and one client and they can freely connect to each other, the same debugger binaries are installed on both the client and the server, and the debugging technician who will be operating the client will be able to talk to someone in the room with the server, this is the recommended method. + + The client and the server can be running any version of Windows. They do not have to be running the same version as each other. + + If the client is unable to send a connection request to the server, but the server is able to send a request to the client, you can use remote debugging through the debugger with a *reverse connection* by using the **clicon** parameter. + +- [Remote debugging through remote.exe](remote-debugging-through-remote-exe.md) is used to remotely control a Command Prompt window. It can be used to remotely control KD, CDB, or NTSD. It cannot be used with WinDbg. + + If your client does not have copies of the debugger binaries, you must use the remote.exe method. + +- **A process server** or a **KD connection server** can be used if the debugging technician will not be able to talk to someone in the room with the server. All the actual debugging work is done by the client (called the *smart client*); this removes the need to have a second person present at the server itself. + + Process servers are used for user-mode debugging; KD connection servers are used for kernel-mode debugging. Other than this distinction, they behave in similar ways. + + This method is also useful if the computer where the server will be running cannot handle heavy process loads, or if the technician running the client has access to symbol files or source files that are confidential and cannot be accessed by the server. However, this method is not as fast or efficient as remote debugging through the debugger. This method cannot be used for dump-file debugging. + + See [Process Servers (User Mode)](process-servers--user-mode-.md) and [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md) for details. + +- **A repeater** is a lightweight proxy server that relays data between two computers. You can add a repeater between the client and the server if you are performing remote debugging through the debugger or if you are using a process server. + + Using a repeater may be necessary if your client and your server are unable to talk directly to each other, but can each access an outside computer. You can use reverse-connections with repeaters as well. It is even possible to use two repeaters in a row, but this is rarely necessary. + + See [Repeaters](repeaters.md) for details. + +- It is also possible to control CDB (or NTSD) from the kernel debugger. This is yet another form of remote debugging. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +Variations on all of these methods are possible. + +It is possible to chain several computers together to take advantage of more than one transport method. You can create complicated transport sequences that take into account where the technician is, where the symbols are located, and whether there are firewalls preventing connections in certain directions. See [Advanced Remote Debugging Scenarios](advanced-remote-debugging-scenarios.md) for some examples. + +You can even perform remote debugging on a single computer. For example, it might be useful to start a low-privilege process server and then connect to it with a high-privilege smart client. And on a Windows 2000 terminal server computer you can debug one session from another. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20the%20Best%20Remote%20Debugging%20Method%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-the-best-tool.md b/windows-driver-docs-pr/debugger/choosing-the-best-tool.md new file mode 100644 index 0000000000..b7378f7ce6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-the-best-tool.md @@ -0,0 +1,96 @@ +--- +title: Choosing the Best Tool +description: Choosing the Best Tool +ms.assetid: 08021932-930b-4998-b651-9581df9345b3 +keywords: ["dump file, user-mode creation tools"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Choosing the Best Tool + + +## + + +There are severa; different tools that can create user-mode dump files. In most cases, ADPlus is the best tool to use. + +The following table shows the features of each tool. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature[ADPlus](adplus.md)[Windows Error Reporting](windows-error-reporting.md)[CDB and WinDbg](cdb-and-windbg.md)[UserDump](userdump.md)

Creating a dump file when an application crashes (postmortem debugging)

Yes

Yes

Yes

Yes

Creating a dump file when an application "hangs" (stops responding but does not actually crash)

Yes

No

Yes

Yes

Creating a dump file when an application encounters an exception

Yes

Yes

Yes

Yes

Creating a dump file while an application is running normally

No

No

Yes

No

Creating a dump file from an application that fails during startup

No

No

Yes

Yes

Shrinking an existing dump file

No

No

Yes

No

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20the%20Best%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/choosing-which-public-symbols-to-remove.md b/windows-driver-docs-pr/debugger/choosing-which-public-symbols-to-remove.md new file mode 100644 index 0000000000..858114204f --- /dev/null +++ b/windows-driver-docs-pr/debugger/choosing-which-public-symbols-to-remove.md @@ -0,0 +1,136 @@ +--- +title: Choosing Which Public Symbols to Remove +description: Choosing Which Public Symbols to Remove +ms.assetid: 0de89f65-ebb5-4186-a6f9-6676f86a75f1 +keywords: ["PDBCopy, removing public symbols", "symbols, AgeStore"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Choosing Which Public Symbols to Remove + + +PDBCopy supplies the -f and -F options so that you can remove an arbitrary set of public symbols from a stripped symbol file, leaving only those symbols that your audience needs to access in order to perform their debugging. + +A common use of PDBCopy is to create a special version of your symbol file for use by Microsoft in its Online Crash Analysis (OCA) program. OCA can designate certain functions as *inert*, which means that if the function is found on the stack trace it is ignored. A function would typically be declared inert if it is simply a wrapper or "pass-through" function that performs no significant computations. If such a function is found on the stack in a failure analysis, it can be assumed that this function itself was not at fault, and at most it passed on invalid or corrupt data that it received from routines earlier on the stack. By ignoring such functions, OCA can better determine the actual cause of the error or corruption. + +Naturally, any function that you wish to declare "inert" needs to be included in the public symbol table of the symbol file used by OCA. However, these are not the only functions that need to be included, as the following example shows. + +Suppose that you write a Windows driver and you use PDBCopy to remove all public symbols from its symbol file, except for **FunctionOne** and **FunctionSix**, two inert functions. Your expectation is that if either **FunctionOne** or **FunctionSix** are found on the stack after a crash, they will be ignored by OCA. If any other part of your driver is on the stack, Microsoft will supply you with the corresponding memory address and you can use the address to debug your driver. + +However, let us suppose that your driver occupies memory in the following layout: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AddressContents of memory

0x1000

Base address of the module

0x2000

Beginning of FunctionOne

0x203F

End of FunctionOne

0x3000

Beginning of FunctionSix

0x305F

End of FunctionSix

0x7FFF

End of the module in memory

+ +  + +If the debugger finds an address on the stack, it selects the symbol with the next lower address. Since the public symbol table contains the address of each symbol but no size information, there is no way for the debugger to know if an address actually falls within the boundaries of any specific symbol. + +Therefore, if a fault occurs at address 0x2031, the debugger run by Microsoft OCA correctly identifies the fault as lying within **FunctionOne**. Since this is an inert function, the debugger continues walking the stack to find the cause of the crash. + +However, if a fault occurs at 0x2052, the debugger still matches this address to **FunctionOne**, even though it lies beyond the actual end of this function (0x203F). + +Consequently, you must include in your stripped symbol file not only the functions you wish to expose, but also the symbols immediately following these functions. In this example, you would wish to expose **FunctionOne**, **FunctionTwo**, **FunctionSix**, and **FunctionSeven**: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AddressContents of memory

0x1000

Base address of the module

0x2000

Beginning of FunctionOne

0x203F

End of FunctionOne

0x2040

Beginning of FunctionTwo

0x3000

Beginning of FunctionSix

0x305F

End of FunctionSix

0x3060

Beginning of FunctionSeven

0x7FFF

End of the module in memory

+ +  + +If you include all four of these functions in the stripped symbol file, then the Microsoft OCA analysis will not mistakenly treat the address 0x2052 as part of **FunctionOne**. In this example it will assume that this address is part of **FunctionTwo**, but that is not important because you have not registered **FunctionTwo** with OCA as an inert function. The important thing is that the address 0x2052 is recognized as not falling within an inert function, and therefore OCA will recognize this as a meaningful fault within your driver and can inform you of the fault. + +If you do not wish to publicize the names of the functions following each inert function, you can insert unimportant functions into your code following each inert function so that the names of these functions can be included in your public symbol file. Be sure to verify that these added functions do indeed follow your inert functions in your binary's address space, since some optimization routines may alter this, or even remove some functions entirely. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Choosing%20Which%20Public%20Symbols%20to%20Remove%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/client-and-server-examples.md b/windows-driver-docs-pr/debugger/client-and-server-examples.md new file mode 100644 index 0000000000..11d150540e --- /dev/null +++ b/windows-driver-docs-pr/debugger/client-and-server-examples.md @@ -0,0 +1,78 @@ +--- +title: Client and Server Examples +description: Client and Server Examples +ms.assetid: 78dea1c0-6e94-4980-8042-375f11386d53 +keywords: ["remote debugging through the debugger, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Client and Server Examples + + +## + + +Suppose one person is running an application on a computer named *\\\\BOX17*. This application has problems, but the debugging technician is at a different site. + +The first person sets up a debugging server using CDB on *\\\\BOX17*. The target application has a process ID of 122. TCP protocol is chosen, with a socket port number of 1025. The server is started by entering the following command in an elevated Command Prompt window (Run as Administrator): + +``` +E:\Debugging Tools for Windows> cdb -server tcp:port=1025 -p 122 +``` + +On the other computer, the technician decides to use WinDbg as the debugging client. It can be started with this command: + +``` +G:\Debugging Tools> windbg -remote tcp:server=BOX17,port=1025 +``` + +Here is another example. In this case, NPIPE protocol is chosen, and CDB is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric string -- in this example, "MainPipe". The first user opens an elevated Command Prompt window (Run as Administrator) and starts a debugging server by entering this command: + +``` +E:\Debugging Tools for Windows> cdb -server npipe:pipe=MainPipe -v winmine.exe +``` + +The technician is logged on to the client computer with an account that does not have access to the server computer. But the technician knows the username and password for an account that does have access to the server computer. The username for that account is Contoso. The technician enters the following command: + +``` +net use \\BOX17\ipc$ /user:Contoso +``` + +When prompted, the technician enters the password for the Contoso account. + +The technician is not sure what name was used for the named pipe, so she queries BOX17 for available debugging servers. + +``` +G:\Debugging Tools> cdb -QR \\BOX17 +Servers on \\BOX17: +Debugger Server - npipe:Pipe=MainPipe +Remote Process Server - npipe:Pipe=AnotherPipe +``` + +Two pipes are shown. However, only one is a debugging server -- the other is a process server, and we are not interested in that. So **MainPipe** must be the correct name. The technician uses the following command to start the debugging client: + +``` +G:\Debugging Tools> cdb -remote npipe:server=BOX17,pipe=MyPipe +``` + +### Using a Secure Server + +Here is an example of a secure server. This server uses secure sockets layer with an S-Channel protocol of TLS1. The debugger will look for the certificate in the machine store. The certificate is specified by its hexadecimal thumbprint. + +``` +D:\> cdb -server "ssl:proto=tls1,machuser=ab 38 f7 ae 13 20 ac da 05 14 65 60 30 83 7b 83 09 2c d2 34,port=1234" notepad.exe +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Client%20and%20Server%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/client-objects-and-the-engine.md b/windows-driver-docs-pr/debugger/client-objects-and-the-engine.md new file mode 100644 index 0000000000..a0d502b70e --- /dev/null +++ b/windows-driver-docs-pr/debugger/client-objects-and-the-engine.md @@ -0,0 +1,171 @@ +--- +title: Client Objects and the Engine +description: Client Objects and the Engine +ms.assetid: 959912c0-bce9-4d5b-9119-1ac07a8ea1ad +keywords: ["EngExtCpp extensions, client objects"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Client Objects and the Engine + + +## + + +An EngExtCpp extension interacts with the [debugger engine](introduction.md#debugger-engine) through a client object. Interface pointers to the client object are available to the extension through members of the [**ExtExtension**](https://msdn.microsoft.com/library/windows/hardware/ff543981) base class. The following members provide access to the first version of the engine API interfaces. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Engine API interfaceExtExtension member

[IDebugAdvanced](https://msdn.microsoft.com/library/windows/hardware/ff549798)

m_Advanced

[IDebugClient](https://msdn.microsoft.com/library/windows/hardware/ff549827)

m_Client

[IDebugControl](https://msdn.microsoft.com/library/windows/hardware/ff550508)

m_Control

[IDebugDataSpaces](https://msdn.microsoft.com/library/windows/hardware/ff550528)

m_Data

[IDebugRegisters](https://msdn.microsoft.com/library/windows/hardware/ff550825)

m_Registers

[IDebugSymbols](https://msdn.microsoft.com/library/windows/hardware/ff550856)

m_Symbols

[IDebugSystemObjects](https://msdn.microsoft.com/library/windows/hardware/ff550875)

m_System

+ +  + +The following members provide access to later versions of the engine API interfaces. These interfaces may not be available in all versions of the debugger engine. If they are not available, any attempt to use them will result in a exception being thrown. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Engine API interfaceExtExtension member

IDebugAdvanced2

m_Advanced2

IDebugAdvanced3

m_Advanced3

IDebugClient2

m_Client2

IDebugClient3

m_Client3

IDebugClient4

m_Client4

IDebugClient5

m_Client5

IDebugControl2

m_Control2

IDebugControl3

m_Control3

IDebugControl4

m_Control4

IDebugData2

m_Data2

IDebugData3

m_Data3

IDebugData4

m_Data4

IDebugRegisters2

m_Registers2

IDebugSymbols2

m_Symbols2

IDebugSymbols3

m_Symbols3

IDebugSystemObjects2

m_System2

IDebugSystemObjects3

m_System3

IDebugSystemObjects4

m_System4

+ +  + +The members in these tables are initialized each time the extension library is used to execute an extension command or format a structure for output. Once a task is completed, these members are uninitialized. Consequently, extensions should not cache the values of these members and should use the **ExtExtension** members directly. + +An extension library can also create its own client objects using the method [**IDebugClient::CreateClient**](https://msdn.microsoft.com/library/windows/hardware/ff539320) or the functions [**DebugCreate**](https://msdn.microsoft.com/library/windows/hardware/ff540469) or [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465). + +For an overview of client objects, see [Client Objects](client-objects.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Client%20Objects%20and%20the%20Engine%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/client-objects.md b/windows-driver-docs-pr/debugger/client-objects.md new file mode 100644 index 0000000000..c4776c8900 --- /dev/null +++ b/windows-driver-docs-pr/debugger/client-objects.md @@ -0,0 +1,51 @@ +--- +title: Client Objects +description: Client Objects +ms.assetid: 173a67f1-093e-4462-8e2c-41d0f10106d0 +keywords: ["Debugger Engine, client objects", "client objects"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Client Objects + + +## + + +Almost all interaction with the [debugger engine](introduction.md#debugger-engine) is through *client objects*, often simply referred to as *clients*. Each client provides an implementation of the top-level engine interfaces. Each interface provides a different set of methods, which can be used to interact with the engine and, through the engine, the targets. An instance of the engine can have many clients, each with its own state. + +### Primary Clients + +A *primary client* is a client that has joined the current debugging session. Initially, when a new client object is created, it is not a primary client. A client becomes a primary client when it is used to acquire a target (for example, by calling [**CreateProcess2**](https://msdn.microsoft.com/library/windows/hardware/ff539323)) or is connected to the debugging session using [**ConnectSession**](https://msdn.microsoft.com/library/windows/hardware/ff539245). The debugger command [**.clients**](-clients--list-debugging-clients-.md) lists only the primary clients. + +### Callback Objects + +Callback objects can be registered with each client. There are three types of callback objects: + +1. **Input Callback Objects** (or *input callbacks*): the engine calls input callbacks to request input. For example, a debugger with a console window could register an input callback to provide the engine with input from the user, or a debugger might register an input callback to provide the engine with input from a file. + +2. **Output Callback Objects** (or *output callbacks*): the engine calls output callbacks to display output. For example, a debugger with a console window could register an output callback to present the debugger's output to the user, or a debugger might register an output callback to send the output to a log file. + +3. **Event Callback Objects** (or *event callbacks*): the engine calls event callbacks whenever an event occurs in a target (or there is a change in the engine's state). For example, a debugger extension library could register an event callback to monitor certain events or perform automated actions when an particular event occurs. + +### Remote Debugging + +Client objects facilitate communication to remote instances of the host engine. The [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465) function creates a client object that is connected to a remote engine instance; methods called on this client are executed by the remote engine and callback objects registered locally with the client will be called when the remote engine makes callback calls. + +### Additional Information + +For details about creating and using client objects, see [Using Callback Objects](using-callback-objects.md). For details about registering callback objects, see Using Callback Objects. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Client%20Objects%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/closing-a-window.md b/windows-driver-docs-pr/debugger/closing-a-window.md new file mode 100644 index 0000000000..ae94c0ea30 --- /dev/null +++ b/windows-driver-docs-pr/debugger/closing-a-window.md @@ -0,0 +1,35 @@ +--- +title: Closing a Window +description: Closing a Window +ms.assetid: efa37441-460a-4023-8d8a-7ac19ddf6f16 +keywords: ["debugging information windows, closing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Closing a Window + + +## + + +To close a debugging information window, click the **Close** button in the upper-right corner of the window. + +If you want to close the active window, you can also click **Close Current Window** on the **File** menu or press CTRL+F4. + +You can close one of the debugging information windows by pressing ALT+SHIFT+*number*, where ALT+*number* are the shortcut keys that open this window. (For a list of the possible shortcut keys, see [Opening a Window](opening-a-window.md).) + +To close all [Source windows](source-window.md) at the same time, click [Close All Source Windows](window---close-all-source-windows.md) on the **Window** menu. This command will not close a Source window that has been designated as a tab-dock target. For more information on this setting, see the Source Window topic. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Closing%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/combining-this-method-with-remote-debugging.md b/windows-driver-docs-pr/debugger/combining-this-method-with-remote-debugging.md new file mode 100644 index 0000000000..ad4b5a7516 --- /dev/null +++ b/windows-driver-docs-pr/debugger/combining-this-method-with-remote-debugging.md @@ -0,0 +1,89 @@ +--- +title: Combining This Method with Remote Debugging +description: Combining This Method with Remote Debugging +ms.assetid: 4f9a60ab-b221-4a60-b3d5-cd907e33ec19 +--- + +# Combining This Method with Remote Debugging + + +## + + +It is sometimes useful to [control the user-mode debugger from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md)and use the user-mode debugger as a [debugging server](remote-debugging-through-the-debugger.md) at the same time. + +For example, this configuration is useful when your user-mode symbols are located on a symbol server. In the standard configuration for controlling the user-mode debugger from a kernel debugger, the interaction of the two debuggers can lead to tiny lapses in synchronization, and these lapses can prevent symbol server authentication. The more complex configuration described here can avoid this problem. + +**Note**   In describing this scenario, *target application* refers to the user-mode application that is being debugged, *target computer* refers to the computer that contains the target application and the CDB or NTSD process, and *host computer* refers to the computer that contains the kernel debugger. + +  + +To use this technique, you must do the following: + +1. Start NTSD or CDB on the target computer, with the -ddefer and -server command-line options, specifying the desired transport options. The -server option must be the first parameter on the command line. + + For example, you can attach to a running process by using the following syntax. + + ``` + ntsd -server ServerTransport -ddefer [-y UserSymbolPath] -p PID + ``` + + Or, you can start a new process as the target by using the following syntax. + + ``` + ntsd -server ServerTransport -ddefer [-y UserSymbolPath] ApplicationName + ``` + + If you are installing this as a postmortem debugger, you would use the following syntax. Note that you must manually edit the registry to install a postmortem debugger that includes the -server parameter; for details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + + ``` + ntsd -server ServerTransport -ddefer [-y UserSymbolPath] + ``` + + For information about the available transport options, see [**Activating a Debugging Server**](activating-a-debugging-server.md). + +2. Start WinDbg or KD on the host computer, as if you were going to debug the target computer, but do not actually break in to the target computer. To use WinDbg, use the following syntax. + + ``` + windbg [-y KernelSymbolPath] [-k ConnectionOptions] + ``` + + For more information about this step, see [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md) + + . + +3. Start WinDbg or CDB as a debugging client, with the same transport options used to start the server. This debugging client can be run on either the host computer or on a third computer. + + ``` + cdb -remote ClientTransport + ``` + + For more information about this step, see [**Activating a Debugging Client**](activating-a-debugging-client.md). + +4. Once the debuggers are running and the `Input>` prompt appears in the kernel debugger, use the [**.sleep (Pause Debugger)**](-sleep--pause-debugger-.md) command to pause the debuggers and let the target computer run for a few seconds. This gives the target computer time to process the remote transport protocol, establishing the connection between the user-mode remote server and the remote client. + +If you use CDB as the user-mode debugger, the Command Prompt window that is associated with CDB remains locked and unavailable while debugging continues. If you use NTSD, no additional window is created, even though NTSD has a process ID associated with it on the target computer. + +The four modes and the methods of switching between them described in the topic [Switching Modes](switching-modes.md) apply in this combination scenario, with the following differences: + +- There are two different user-mode debugging modes. When the target computer is running, the debugging server is controlled by the debugging client as in any other remote debugging session; this is called *remote-controlled user-mode debugging*. When the kernel-mode debugger is broken in to the target computer and the `Input>` prompt is showing, the user-mode debugger is controlled by the kernel debugger; this is called *kernel-controlled user-mode debugging*. + +- These two modes are never available at the same time. When the kernel debugger is broken in to the target computer, even though the user-mode debugger may be active, the target computer is unable to process the remote transport protocol, and therefore the user-mode debugger will not be able to receive remote input across this connection. + +- If your user-mode symbols are located on a symbol server, any debugger commands that require symbol access should be issued while in remote-controlled user-mode debugging mode. + +- To switch from kernel-controlled user-mode debugging to remote-controlled user-mode debugging, use the [**.sleep (Pause Debugger)**](-sleep--pause-debugger-.md) command. When the user-mode debugger wakes from the sleep command, it will be in remote-controlled user-mode debugging mode. + +- To switch from remote-controlled user-mode debugging to kernel-mode debugging, enter any command from the `Input>` prompt. If this prompt is not visible, switch to kernel-mode debugging, and then use the [**g (Go)**](g--go-.md) command at the `kd>` prompt. + +Internally, a user-mode debugger started with -ddefer gives first priority to input from the debugging client, and second priority to input from the kernel debugger. However, there can never be a conflict between simultaneous inputs, because when the kernel debugger has broken in to the target computer, the remote connection is unavailable. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Combining%20This%20Method%20with%20Remote%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/command-browser-window.md b/windows-driver-docs-pr/debugger/command-browser-window.md new file mode 100644 index 0000000000..729d44771f --- /dev/null +++ b/windows-driver-docs-pr/debugger/command-browser-window.md @@ -0,0 +1,64 @@ +--- +title: Using the Command Browser Window in WinDbg +description: Using the Command Browser Window in WinDbg +ms.assetid: b895f463-38ec-451a-8c0a-0deb8650a904 +keywords: ["debugging information windows, command browser window", "command browser window", "Debugger Command window, command browser window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Command Browser Window in WinDbg + + +A Command Browser window displays and stores the text results of a debugger command. This window creates a command reference that enables you to view the results of a specific command without re-entering the command. A Command Browser window also provides navigation through the stored commands, so you can more quickly access commands than with the [Debugger Command window](debugger-command-window.md). + +### Opening the Command Browser Window + +You can open multiple Command Browser windows at one time. To open a Command Browser window, choose **Command Browser** from the **View** menu. (You can also press CTRL+N or click the **Command Browser** button (![screen shot of the command browser button](images/window-command-browser-icon.png)) on the toolbar. ALT+SHIFT+N closes the Command Browser window.) + +You can also open a Command Browser window by entering [**.browse (Display Command in Browser)**](-browse--display-command-in-browser-.md) in the regular Debugger Command window. + +The following screen shot shows an example of a Command Browser window. + +![screen shot of the command browser window](images/window-commandbrowser.png) + +### Using the Command Browser Window + +In the Command Browser window, you can do the following: + +- To enter a command, type it in the **Command** box. + +- To view the results of a previously entered command, use the **Start**, **Prev**, and **Next** buttons to scroll through the command list, or select one of the preceding 20 commands from the **Command** menu. To find a command that is not one of the preceding 20 commands, use the **Next** button. + +The Command Browser window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button that displays the command browser window toolbar shortcut menu](images/window-command-browser-icon.png)). The following list describes some of the menu commands: + +- **Start**, **Prev**, and **Next** move the cursor to the start of the command history or to the previous or next command, respectively. + +- **Add to Recent Commands** puts the current command into the **Recent Commands** menu of the **View** menu in the WinDbg window. Recent commands are saved in the workspace. + +- **Toolbar** turns the toolbar on and off. + +- **Move to new dock** closes the Command Browser window and opens it in a new dock. + +- **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +Commands that you enter in a Command Browser window are executed by the debugger engine, not by the WinDbg user interface. This means that you cannot enter user interface commands like [**.cls**](-cls--clear-screen-.md) in a Command Browser window. If the user interface is a remote client, the server (not the client) executes the command. + +A command that you enter in a Command Browser window executes synchronously, so it does not display output until it has completed. + +Command Browser windows are saved in the WinDbg workspace, but the command histories are not saved. Only the current command for each Command Browser window is saved in the workspace. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Command%20Browser%20Window%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/command-line-options.md b/windows-driver-docs-pr/debugger/command-line-options.md new file mode 100644 index 0000000000..9dfa3e43f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/command-line-options.md @@ -0,0 +1,40 @@ +--- +title: Command-Line Options +description: Command-Line Options +ms.assetid: 080060a1-b1dd-4096-bb9c-8825f4f71b86 +keywords: ["command-line options", "starting the debugger, command-line options"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Command-Line Options + + +## + + +## In this section + + +- [**CDB Command-Line Options**](cdb-command-line-options.md) +- [**KD Command-Line Options**](kd-command-line-options.md) +- [**WinDbg Command-Line Options**](windbg-command-line-options.md) +- [**DbgSrv Command-Line Options**](dbgsrv-command-line-options.md) +- [**KdSrv Command-Line Options**](kdsrv-command-line-options.md) +- [**DbEngPrx Command-Line Options**](dbengprx-command-line-options.md) +- [**KDbgCtrl Command-Line Options**](kdbgctrl-command-line-options.md) +- [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md) +- [**SymStore Command-Line Options**](symstore-command-line-options.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/command-tokens.md b/windows-driver-docs-pr/debugger/command-tokens.md new file mode 100644 index 0000000000..67bc6cefce --- /dev/null +++ b/windows-driver-docs-pr/debugger/command-tokens.md @@ -0,0 +1,67 @@ +--- +title: Command Tokens +description: Command Tokens +ms.assetid: 164ffe42-93d9-405e-8ad3-965c476e9204 +keywords: ["commands, tokens used in commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Command Tokens + + +## + + +This section of the reference discusses the various tokens used within debugger commands and meta-commands. + +These tokens include: + +[**; (Command Separator)**](----command-separator-.md) + +[**{ } (Block Delimiter)**](------block-delimiter-.md) + +[**${ } (Alias Interpreter)**](-------alias-interpreter-.md) + +[**$$ (Comment Specifier)**](-----comment-specifier-.md) + +[**\* (Comment Line Specifier)**](----comment-line-specifier-.md) + +[**.block**](-block.md) + +[**.break**](https://msdn.microsoft.com/library/windows/hardware/ff556242) + +[**.catch**](-catch.md) + +[**.continue**](-continue.md) + +[**.do**](-do.md) + +[**.else**](-else.md) + +[**.elsif**](-elsif.md) + +[**.for**](-for.md) + +[**.foreach**](-foreach.md) + +[**.if**](-if.md) + +[**.leave**](-leave.md) + +[**.printf**](-printf.md) + +[**.while**](-while.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Command%20Tokens%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/commands.md b/windows-driver-docs-pr/debugger/commands.md new file mode 100644 index 0000000000..281ba803bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/commands.md @@ -0,0 +1,29 @@ +--- +title: Commands +description: Commands +ms.assetid: be2ff9ca-48d2-4050-8390-2ead1d53f8d9 +keywords: ["commands, reference"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Commands + + +## + + +This section of the reference discusses the various debugger commands that you can use in CDB, KD, and WinDbg. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/common-rpc-debugging-techniques.md b/windows-driver-docs-pr/debugger/common-rpc-debugging-techniques.md new file mode 100644 index 0000000000..fd82e6370f --- /dev/null +++ b/windows-driver-docs-pr/debugger/common-rpc-debugging-techniques.md @@ -0,0 +1,39 @@ +--- +title: Common RPC Debugging Techniques +description: Common RPC Debugging Techniques +ms.assetid: 4439ba40-909d-4fa8-a96d-8ffaf90e22d9 +keywords: ["RPC debugging, common techniques"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Common RPC Debugging Techniques + + +## + + +This section describes four common RPC-related problems. RPC state information can be used to troubleshoot these problems. + +Either the DbgRpc tool or the RPC debugger extensions can be used in any of these four situations. + +[Analyzing a Stuck Call Problem](analyzing-a-stuck-call-problem.md) + +[Tracking Contention in the Server Process](tracking-contention-in-the-server-process.md) + +[Checking for Stuck Threads](checking-for-stuck-threads.md) + +[Identifying the Caller From the Server Thread](identifying-the-caller-from-the-server-thread.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Common%20RPC%20Debugging%20Techniques%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/complete-memory-dump.md b/windows-driver-docs-pr/debugger/complete-memory-dump.md new file mode 100644 index 0000000000..de30081177 --- /dev/null +++ b/windows-driver-docs-pr/debugger/complete-memory-dump.md @@ -0,0 +1,43 @@ +--- +title: Complete Memory Dump +description: Complete Memory Dump +ms.assetid: ccc4d22a-89af-4c7d-a982-f77c682cd001 +keywords: ["dump file, Complete Memory Dump", "Complete Memory Dump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Complete Memory Dump + + +## + + +A *Complete Memory Dump* is the largest kernel-mode dump file. This file includes all of the physical memory that is used by Windows. A complete memory dump does not, by default, include physical memory that is used by the platform firmware. + +Starting with Windows 8, you can register a [*BugCheckAddPagesCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540669) routine that is called during a complete memory dump. Your *BugCheckAddPagesCallback* routine can specify driver-specific data to add to the dump file. For example, this additional data can include physical pages that are not mapped to the system address range in virtual memory but that contain information that can help you to debug your driver. The *BugCheckAddPagesCallback* routine might add to the dump file any driver-owned physical pages that are unmapped or that are mapped to user-mode addresses in virtual memory. + +This dump file requires a pagefile on your boot drive that is at least as large as your main system memory; it should be able to hold a file whose size equals your entire RAM plus one megabyte. + +The Complete Memory Dump file is written to %SystemRoot%\\Memory.dmp by default. + +If a second bug check occurs and another Complete Memory Dump (or Kernel Memory Dump) is created, the previous file will be overwritten. + +## Related topics + + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Complete%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-a-window.md b/windows-driver-docs-pr/debugger/configuring-a-window.md new file mode 100644 index 0000000000..3fb1b375fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-a-window.md @@ -0,0 +1,31 @@ +--- +title: Configuring a Window +description: Configuring a Window +ms.assetid: d801b181-d1d5-419b-811d-38df538e36ef +keywords: ["debugging information windows, configuring"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring a Window + + +## + + +Each debugging information window has a shortcut menu that you can access by right-clicking the title bar of the window or by clicking the icon near the upper-right corner of the title bar. You can use the commands on this shortcut menu to configure the window. + +Many debugging information windows also have toolbars that contain buttons. Most of these buttons have features that are the same as commands on the shortcut menu. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-cdb.md b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-cdb.md new file mode 100644 index 0000000000..a54e39ac8a --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-cdb.md @@ -0,0 +1,29 @@ +--- +title: Configuring Exceptions and Events in CDB +description: You can configure CDB to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. +ms.assetid: EA23057E-3241-43F2-84D3-CA5E56721583 +--- + +# Configuring Exceptions and Events in CDB + + +You can configure CDB to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. For each event, you can set the break status. + +You can configure the break status or handling status by doing one of the following: + +- Use the [**SXE**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md), **SXD**, **SXN**, or **SXI** command. + +- Use the **-x**, **-xe**, **-xd**, **-xn**, or **-xi** option on the [**CDB command line**](cdb-command-line-options.md). +- Use the **sxe** or **sxd** keyword in the Tools.ini file. + +For a detailed discussion of exceptions and events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Exceptions%20and%20Events%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-kd.md b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-kd.md new file mode 100644 index 0000000000..4b1ed208bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-kd.md @@ -0,0 +1,24 @@ +--- +title: Configuring Exceptions and Events in KD +description: You can configure KD to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. +ms.assetid: 0F96E152-CA18-4945-A89D-5155F4B4F65F +--- + +# Configuring Exceptions and Events in KD + + +You can configure KD to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. For each event, you can set the break status. + +You can configure the break status or the handling status by using the [**SXE**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md), **SXD**, **SXN**, or **SXI** command. + +For a detailed discussion of exceptions and events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Exceptions%20and%20Events%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-visual-studio.md b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-visual-studio.md new file mode 100644 index 0000000000..f39b82b9ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-visual-studio.md @@ -0,0 +1,31 @@ +--- +title: Configuring Exceptions and Events in Visual Studio +description: You can configure the Windows Debugger to react to specified exceptions and events in a pre-determined way. For each exception, you can set the break status and the handling status. +ms.assetid: 531CFE28-B0DA-4B6D-896F-C8F678C7FE00 +--- + +# Configuring Exceptions and Events in Visual Studio + + +You can configure the Windows Debugger to react to specified exceptions and events in a pre-determined way. For each exception, you can set the break status and the handling status. For each event, you can set the break status. + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +You can configure the break status or the handling status by entering the following commands in the Debugger Immediate Window. If the Debugger Immediate Window is not already open, from the **Debug** menu, choose **Windows>Immediate**. + +- [**sxe**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) +- [**sxd**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) +- [**sxn**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) +- [**sxi**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) + +For a detailed discussion of exceptions and events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Exceptions%20and%20Events%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-windbg.md b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-windbg.md new file mode 100644 index 0000000000..51f7ac6483 --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-exceptions-and-events-in-windbg.md @@ -0,0 +1,34 @@ +--- +title: Configuring Exceptions and Events in WinDbg +description: You can configure WinDbg to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. +ms.assetid: B91DD7B6-5206-4BA6-8B49-8ECCA2FA730B +--- + +# Configuring Exceptions and Events in WinDbg + + +You can configure WinDbg to react to specified exceptions and events in a specific way. For each exception, you can set the break status and the handling status. For each event, you can set the break status. + +You can configure the break status by doing one of the following: + +- Choose **Event Filters** from the **Debug** menu, click the event that you want from the list in the **Event Filters** dialog box, and then select **Enabled**, **Disabled**, **Output**, or **Ignore**. + +- Use the [**SXE**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md), **SXD**, **SXN**, or **SXI** command. + +You can configure the handling status by doing one of the following: + +- Choose **Event Filters** from the **Debug** menu, click the event that you want from the list in the **Event Filters** dialog box, and then select **Handled** or **Not Handled**. + +- Use the [**SXE**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md), **SXD**, **SXN**, or **SXI** command. + +For a detailed discussion of exceptions and events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Exceptions%20and%20Events%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-iis-for-symproxy.md b/windows-driver-docs-pr/debugger/configuring-iis-for-symproxy.md new file mode 100644 index 0000000000..7d6bd43ae7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-iis-for-symproxy.md @@ -0,0 +1,82 @@ +--- +title: Configuring IIS for SymProxy +description: Configuring IIS for SymProxy +ms.assetid: 66f1d05c-2572-4dda-a9d9-766561ebd491 +keywords: ["SymProxy, IIS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring IIS for SymProxy + + +Internet Information Services (IIS) must be configured to use SymProxy as an Internet Server Application Programming Interface (ISAPI) filter. Furthermore, permissions must be set so that IIS can obtain symbols. + +**To configure the application pool** + +1. From **Administrative Tools** open **Internet Information Services (IIS) Manager**. + +2. Expand the entry with the computer name on the left and locate **Application Pools**. + +3. Right-click **Application Pools** and choose **Add Application Pool**. + +4. For the **Name** type *SymProxy App Pool*. + +5. Under **.Net Framework version** select *None* + +6. Click **OK** to create the application pool. + +7. Next, right click the entry for the new application pool and select **Advanced Settings…**. + +8. Under **Process Model**, you will see **Identity**. Click the button at the right labeled "**…**". + + 1. If you are authenticating as a network service, select **Predefined** for the **Application Pool Identity** and then select **Network Service**. + + 2. If you are authenticating as a domain user, select **Custom account** and then click the **Set** button. Type the credentials of the account that has permissions to access the remote symbol server store (for example, *corp\\SymProxyUser*), and click **OK**. + +9. Click **OK** to exit the **Application Pool Identity** dialog. + +10. Click **OK** to exit the **Advanced Settings** dialog. + +**To set up the Virtual Directory** + +1. Expand **Web Sites**. + +2. Select **Default Web Site**. + +3. Right-click the **Symbols** virtual directory and choose **Properties**. + +4. In the **Virtual Directory** tab, click **Create**. + +5. From the **Application Pool** drop-down menu, choose **SymProxy App Pool**. + +6. To exit **Symbols Properties**, click **OK**. + +**Configure the ISAPI Filter** + +1. Right-click the **Default Web Site** and select **Properties**. + +2. Double-click **ISAPI Filters**. + +3. Right click the center pane under the column **Name** and select Click **Add**. + +4. For **Filter Name** type **SymProxy** or some other meaningful name. + +5. For **Executable** type *c:\\windows\\system32\\inetsrv\\symproxy.dll*. + +6. To exit the **Filter Properties** dialog, click **OK**. + +7. To exit **Default Web Site Properties,** click **OK**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20IIS%20for%20SymProxy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-object-reference-tracing.md b/windows-driver-docs-pr/debugger/configuring-object-reference-tracing.md new file mode 100644 index 0000000000..0b9474f32b --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-object-reference-tracing.md @@ -0,0 +1,60 @@ +--- +title: Configuring Object Reference Tracing +description: Configuring Object Reference Tracing +ms.assetid: 9dbf979d-5fc0-4359-bbed-6175f3191c52 +keywords: ["Object Reference Tracing, configuration"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring Object Reference Tracing + + +You can use Gflags to enable, disable, and configure the Object Reference Tracing feature of Windows. Object Reference Tracing records sequential stack traces whenever an object reference counter is incremented or decremented. The traces can help you to detect object reference errors, including double-dereferencing, failure to reference, and failure to dereference objects. This feature is supported only in Windows Vista and later versions of Windows. For detailed information about this feature, see [Object Reference Tracing](object-reference-tracing.md). + +**To enable Object Reference Tracing** + +1. In the Gflags dialog box, select the **System Registry** tab or the **Kernel Flags** tab. + +2. In the Object Reference Tracing section, select **Enable**. + + You must limit the trace to objects with specified pool tags, to objects created by a specified process, or both. + +3. To limit the trace to objects with a particular pool tag, type the pool tag name. To list multiple pool tags, use semicolons (;) to separate the pool tags. When you list multiple pool tags, the trace includes objects with any of the specified pool tags. Pool tags are case sensitive. + + For example, Fred;Tag1. + +4. To limit the trace to objects that are created by a particular process, type the image name of the process. You can specify only one image file name. + + When you specify both pool tags and a process, the trace includes objects that are created by the process that have any of the specified pool tags. + +5. To retain the trace after the trace object is destroyed, select **Permanent**. + + When you select **Permanent**, the trace is retained until you disable object reference tracing, or shut down or restart Windows. + +6. Click **Apply** or **OK**. + +The following screen shot shows Object Reference Tracing enabled on the **Kernel Flags** tab. + +![screen shot that shows object reference tracing enabled on the kernel flags tab](images/gflags-obj.png) + +This trace will include only objects that were created by the notepad.exe process that have the pool tag **Fred** or **Tag1**. Because this is a run time (kernel flags) setting, the trace starts immediately. If it were a registry setting, you would have to restart Windows to start the trace. + +**To disable Object Reference Tracing** + +1. In the Gflags dialog box, select the **System Registry** tab or the **Kernel Flags** tab. Object Reference Tracing will appear on the latter tab only in Windows Vista and later versions of Windows. + +2. In the Object Reference Tracing section, clear the **Enable** check box. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Object%20Reference%20Tracing%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-special-pool.md b/windows-driver-docs-pr/debugger/configuring-special-pool.md new file mode 100644 index 0000000000..721d92b4f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-special-pool.md @@ -0,0 +1,49 @@ +--- +title: Configuring Special Pool +description: Configuring Special Pool +ms.assetid: a6c90e88-8d67-47e8-8862-b7585a5d8bec +keywords: ["GFlags, configuring kernel special pool", "kernel special pool", "special pool", "pool tags and special pool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring Special Pool + + +## + + +The Gflags *Special Pool* feature directs Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is within a specified size range. + +For detailed information about this feature, see [Special Pool](special-pool.md). + +In Windows Vista and later versions of Windows, you can configure the Special Pool feature as a system-wide registry setting or as a kernel flags setting that does not require a reboot. In earlier versions of Windows, Special Pool is available only as a registry setting. + +In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see [**GFlags Commands**](gflags-commands.md). + +This section includes the following topics. + +[Requesting Special Pool by Pool Tag](requesting-special-pool-by-pool-tag.md) + +[Requesting Special Pool by Allocation Size](requesting-special-pool-by-allocation-size.md) + +[Canceling Requests for Special Pool](canceling-requests-for-special-pool.md) + +[Detecting Overruns and Underruns](detecting-overruns-and-underruns.md) + +**Note**   Use *Driver Verifier* to request special pool for allocations by a particular driver. For more information, see the "Special Pool" topic in the "Driver Verifier" section of the Windows Driver Kit (WDK). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Special%20Pool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-the-registry.md b/windows-driver-docs-pr/debugger/configuring-the-registry.md new file mode 100644 index 0000000000..68c3b0ed4c --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-the-registry.md @@ -0,0 +1,313 @@ +--- +title: Configuring the Registry +description: Configuring the Registry +ms.assetid: 69a1dd39-c4aa-491d-9e28-fd1661ec9a7a +keywords: ["SymProxy, registry", "ProxyCfg and SymProxy", "Netsh and SymProxy"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring the Registry + + +SymProxy stores its settings in this registry key. + +``` +HKLM/Software/Microsoft/Symbol Server Proxy +``` + +This registry key controls the location from which to find symbols to store in the Web site, the logging level, and whether or not SymProxy operates with a direct connection to the network. You can create this key by running the SymProxy registration tool (Symproxy.reg) provided with Debugging Tools for Windows. Type **symproxy.reg** at the command prompt or double-click it from Windows Explorer. + +This will add entries for the settings that will be prefixed with an "x" so that they are disabled. To enable a setting, remove the "x" from in front of the desired setting. + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy] +"Available Settings"="Remove the 'x' prefix to use the setting" +"xLogLevel"=dword:0000000f +"xNoInternetProxy"=dword:00000001 +"xNoFilePointers"=dword:00000001 +"xNoUncompress"=dword:00000001 +"xNoCache"=dword:00000001 +"xMissTimeout"=dword:00000e10 +"xMissAgeTimeout"=dword:00015180 +"xMissAgeCheck"=dword:00000e10 +"xMissFileCache"=dword:00000001 +"xMissFileThreads"=dword:00000010 +"xFailureCount"=dword:00000004 +"xFailurePeriod"=dword:00000078 +"xFailureTimeout"=dword:00002d +"xFailureBlackout"=dword:0000384 + +``` + +The symproxy.reg registry file assumes a virtual directory name of Symbols and configures the Symbol Path to use the Microsoft Public Symbol Server. + +``` +[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories] + +[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories\Symbols] +"SymbolPath"="https://msdl.microsoft.com/download/symbols" +``` + +The event logging entries in symproxy.reg are covered latter in the Event Log section of this topic. + +``` +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy] +"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}" +"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\ + 00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\ + 5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\ + 00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00 +"TypesSupported"=dword:00000007 +``` + +The web directory entries in symproxy.reg are discussed in this topic. + +### Web Directories + +For each virtual directory generated in IIS that you are using as a symbol store, you must setup a registry key below the **Web Directories** subkey of the following registry key. + +``` +HKLM/Software/Microsoft/Symbol Server Proxy +``` + +**To edit the registry key for a symbol store virtual directory** + +- Edit the contents of **SymbolPath** to contain all of the symbol stores used by the SymProxy symbol store. If there is more than one symbol store being used, separate them with semicolons. A maximum of 10 stores is supported for each value. HTTP paths must include the **http:// prefix**, and UNC paths must include the **\\\\** prefix. + +For example, if one of the virtual directories is called Symbols, and the symbols stores that it accesses are located at the UNC store \\\\symbols\\symbols and the HTTP store https://msdl.microsoft.com/download/symbols, create the following registry key. + +``` +HKLM/Software/Microsoft/Symbol Server Proxy/Web Directories/Symbols +``` + +After this key is created, edit its **SymbolPath** to be \\\\symbols\\symbols;https://msdl.microsoft.com/download/symbols. This can be seen in the following screenshot of the Registry Editor. + +![screen shot of the registry editor showing a revised symbolpath](images/symproxy-registry.png) + +In this example, SymProxy first searches for symbols in \\\\symbols\\symbols. If the files are not found there, the Microsoft Symbol Store will be used. + +- In each of the keys under Web Directories that match the Virtual Directory names, a REG\_SZ called SymbolPath needs to be created. The value contains all the upstream symbol stores that will be used to populate the SymProxy symbol store. + +- A maximum of 10 entries are supported. + +- Separate entries with semicolons. + +- UNC paths need to include the “\\\\” prefix + +- HTTP paths need to include the “http://” prefix + +- Order the values from least expensive to most expensive. + + - You will need to balance usage performance goals vs. server and data communications costs in the calculation. + + - In general, put local SMB/HTTP servers before internet HTTP servers. + +### SymProxy Performance Counters + +SymProxy can emit performance counters via a provider called SymProxy. + +To enable the performance counters support, register the symproxy manifest file in an administrator command window: + +``` +C:\> lodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man +``` + +To disable the performance counters support, unregister the manifest: + +``` +C:\> unlodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man +``` + +### SymProxy Event Tracing for Windows + +SymProxy can create ETW events via a provider called Microsoft-Windows-SymProxy. + +``` +C:\> logman query providers | findstr SymProxy +Microsoft-Windows-SymProxy {0876099C-A903-47FF-AF14-52035BB479EF} +``` + +To enable the ETW support, register the manifest file: + +``` +C:\> wevtutil.exe install-manifest %WINDIR%\system32\inetsrv\symproxy.man +``` + +To disable the ETW support, unregister the manifest file: + +``` +C:\> wevtutil.exe uninstall-manifest %WINDIR%\system32\inetsrv\symproxy.man +``` + +### Event Log + +If ETW is configured, the events are recorded as events in the *Operational and Analytic* channels under *Applications and Services Logs\\Microsoft\\Windows\\SymProxy* in the Event Log. + +To correctly view the message of the Event Log entries, the Event Log area of the symproxy.reg file needs to be added to the registry: + +``` +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy] +"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}" +"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\ + 00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\ + 5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\ + 00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00 +"TypesSupported"=dword:00000007 +``` + +### SymProxy Events + +SymProxy logs the following events: + +| | | | +|--------------|-----------------------------------|-------------| +| **Event ID** | **Description** | **Channel** | +| 1 | Start of the ISAPI filter | Admin | +| 2 | Stop of the ISAPI filter | Admin | +| 3 | Configuration of the ISAPI filter | Admin | +| 4 | Miss Cache Statistics | Admin | +| 10 | URL Request - Local Cache Hit | Operational | +| 11 | URL Request - Local Cache Miss | Operational | +| 20 | Symbol Download via SymSrv | Operational | +| 30 | Critical Symbol Missing | Admin | +| 31 | Critical Image Missing | Admin | +| 40 | SymSrv – Path Not Found | Admin | +| 41 | SymSrv – File Not Found | Admin | +| 42 | SymSrv – Access Denied | Admin | +| 43 | SymSrv – Path Too Long | Admin | +| 49 | SymSrv – Error Code | Admin | +| 90 | Lock Contention | Operational | +| 100 | General Critical Message | Analytic | +| 101 | General Error Message | Analytic | +| 102 | General Warning Message | Analytic | +| 103 | General Informational Message | Analytic | +| 104 | General Analytic Message | Analytic | +| 105 | General Debug Message | Debug | + +  + +### Symbol Server Proxy Configuration + +SymProxy stores its configuration settings in the following registry key area: + +``` +HKLM/Software/Microsoft/Symbol Server Proxy +``` + +From this location, SymProxy acquires its global settings and the symbol paths of upstream symbol stores. + +You can create this key by merging in the symproxy.reg file you customized as discussed earlier. + +### Symbol Server Proxy’ key + +The Symbol Server Proxy registry key supports the following global settings (all REG\_DWORD). Settings can be applied live by recycling the application pool. A new w3wp.exe process will be created and it will read the new values. Once all pending requests to the old w3wp.exe process have completed, the old w3wp.exe process will end. IIS by default recycles w3wp.exe processes every 1,740 minutes (29 hours). + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
REG_DWORDlDescription
LogLevel

By default, SymProxy doesn’t log an extensive amount of information about its use of SymSrv.dll. Creating REG_DWORD:"LogLevel " with a value of 5 (Analytic) or 6 (Debug), enables the additional logging.

NoInternetProxy

When running as a service, SymSrv.dll uses WinHTTP instead of WinInet to make HTTP requests. Consequently, you may need to set up HTTP proxy settings so that the service can access outside network resources. You can do this using the netsh program. Type “netsh.exe winhttp -?” for instructions.

+

By default, SymProxy uses the designated HTTP proxy. If no HTTP proxy is configured, SymProxy will use a dummy proxy. This allows secure access to HTTP sites within your intranet. As a side effect, this prevents SymProxy from directly connecting to non-secure sites.

+

Creating the REG_DWORD:"NoInternetProxy" value configures SymProxy to operate without a proxy, allowing a direct connection.

NoFilePointers

By default, for symbols that don’t exist, SymProxy will look for a file.ptr file next to the requested file (in the local cache). If found, it will return the location specified by the file.ptr file. This ability is only required when the local cache is being populated by SymStore.exe.

+

Create the REG_DWORD:"NoFilePointers" value to skip the lookup.

NoUncompress

By default, SymProxy will decompress downloaded symbols before returning the file to the caller. This reduces CPU at the client, but increases I/O.

+

Create the REG_DWORD:"NoUncompress" value to skip the decompression.

NoCache

By default, SymProxy will cache downloaded symbols to the local file system, defined by the virtual directory’s path.

+

Create the REG_DWORD:"NoCache" value to skip the download and to provide the remote path of the file to the client instead.

MissTimeout

Timeout period, in seconds, for which missing symbols are reported as missing without re-querying the upstream symbol servers.

+

A miss is associated with a UTC based time. Subsequent requests for the file are immediately rejected for N seconds.

+

The first request for the file after N seconds causes the upstream symbol stores to be re-queried.

+

On success, the symbol file is returned and the miss is deleted.

+

On failure, the miss is moved forward to the current time (in UTC) to start a new timeout period.

+

Use the “Miss Cache *” counters to monitor the misses.

+

• Unspecified - (default) 300 seconds/5 minutes

+

• 0 – Feature disabled

+

• N – Timeout lasts N seconds

MissAgeCheck

Period between Miss Age checks. The Miss cache is scanned and records older than MissAgeTimeout seconds are removed.

+

The current statistics are saved to the Event Log using Event ID 4.

+

• Unspecified - (default) 3600 seconds / 1 hour

+

• 0 – Feature disabled

+

• N – Period between checks in N seconds

MissFileCache

By default, SymProxy does not save miss information to disk. Create the REG_DWORD:"MissFileCache" value to cache miss information in the symbol folder tree. Create the REG_DWORD:"MissFileCache" value to cache miss information in the symbol folder tree.

+

Enable MissFileCache when miss informarion needs to be shared across an IIS farm. Enabling MissFileCache also makes worker process recycling more efficient.

+

MissFileCache causes an I/O operation on the first request for a missing symbol (Miss File Read), the download of a symbol (Miss File Delete), and a failed symbol lookup (Miss File Write).

+

Use the “Miss File XXX/sec” counters to monitor the operations.

+

It is safe to delete .miss files while the SymProxy is running:

+

C:\> del C:\SymStore\Symbols\*.miss /s

MissFileThreads

By default, SymProxy performs up to 16 concurrent asynchronous file I/O operations for the Miss File feature. Creating the REG_DWORD:" MissFileThreads" value overrides the default limit. Values can be between 1 and 64.

+

Use the “Miss File Queue Depth” counter to monitor the load.

FailureTimeout

+

FailureCount

+

FailurePeriod

+

FailureBlackout

The Blackout feature is used to termporarly disable upstream symbol stores that are unresponsive. The Blackout feature uses 4 REG_DWORD values to define the behaviour. By default, the feature is disabled.

+

For each upstream symbol store defined in a Symbol Path, failures are individually recorded. If a request takes longer than FailureTimeout (msec), the failure count is incremented.

+

The Symbol Path is marked as dead after FailureCount failures in FailurePeriod seconds. At this time, all requests are ignored until FailureBlackout seconds have elapsed. The first caller after the timeout tests the upstream symbol store. On success, the timeout is removed and requests are allowed. On failure, the time is set to Now+FailureBlackout seconds. After that time, the upstream symbol store is tested again.

+ +  + +### Accessing Outside Network Resources + +When SymSrv is used in conjunction with SymProxy, it runs as a service and uses the WinHTTP API to access symbols over an HTTP connection. This differs from its usual behavior of using WinInet for this purpose. + +Consequently, you may need to set up HTTP proxy settings so that this service can access outside network resources. Use one of the following methods to configure these settings: + +- In Windows Vista, Windows Server 2008, and later versions of Windows, use the Netsh tool (netsh.exe). For instructions, type the following in a Command Prompt window: + ``` + netsh winhttp -? + ``` + +The default behavior of SymProxy is to use whatever HTTP proxy is designated by either ProxyCfg or Netsh. If no HTTP proxy is configured, SymProxy uses a dummy proxy to allow access to secure HTTP sites within your intranet. As a side effect, this technique prevents SymProxy from working with direct connections to the external Internet. If you wish to permit SymProxy to operate with a direct connection to the Internet, create a REG\_DWORD value named **NoInternetProxy** in the **Symbol Server Proxy** key of your registry. Set the value of **NoInternetProxy** to 1 and verify that there is no HTTP proxy indicated by ProxyCfg. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20the%20Registry%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/configuring-tools-ini.md b/windows-driver-docs-pr/debugger/configuring-tools-ini.md new file mode 100644 index 0000000000..a92397e433 --- /dev/null +++ b/windows-driver-docs-pr/debugger/configuring-tools-ini.md @@ -0,0 +1,145 @@ +--- +title: Configuring tools.ini +description: Configuring tools.ini +ms.assetid: 4f0d9f48-99d5-4180-b25d-70fd8de6f20e +keywords: ["tools.ini file", "ntsd.ini file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configuring tools.ini + + +## + + +The file tools.ini contains information to initialize the command-line debuggers. On startup, the debugger searches for the appropriate section header in the tools.ini file and extracts initialization information from the entries under the header. Each command-line debugger has its own section header - \[CDB\], \[NTSD\], and \[KD\]. The environment variable INIT must point to the directory containing the tools.ini file. + +WinDbg does not use the tools.ini file. Instead, WinDbg saves initialization settings in [workspaces](using-workspaces.md). + +The tools.ini entries are shown in the following table. + +Keywords must be separated from the values by white space or a colon. Keywords are not case-sensitive. + +For **TRUE** or **FALSE** values, "FALSE" is the only false value. Anything else is **TRUE**. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EntryDescription

$u0: value ... $u9: value

Assign values to fixed-name aliases. You can specify numeric values n or 0xn or any other string. See [Using Aliases](using-aliases.md) for details. No command-line equivalent.

DebugChildren: flag

TRUE or FALSE. If TRUE, CDB debugs the specified application as well as any child processes that it might spawn. Command-line equivalent is -o.

DebugOutput: flag

TRUE or FALSE. If TRUE, CDB sends output and receives input through a terminal. If FALSE, output goes to the user screen. The command-line option -d is similar but not identical.

IniFile: file

Specifies the name of the script file that CDB or KD takes commands from at startup. The default is the ntsd.ini file in the current directory. Command-line equivalent is -cf. For details, see [Using Script Files](using-script-files.md).

LazyLoad: flag

TRUE or FALSE. If TRUE, CDB performs lazy symbol loading; that is, symbols are not loaded until required. Command-line equivalent is -s.

+

For details, and other methods of setting this option, see [Deferred Symbol Loading](deferred-symbol-loading.md).

SetDll: filename

Set extension DLL. The .dll filename extension should be omitted. Default is userexts.dll. Command-line equivalent is -a.

+

For details, and other methods of setting this default, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md).

StopFirst: flag

TRUE or FALSE. If true, CDB stops on the breakpoint at the end of the image-loading process. Command-line equivalent is -g.

StopOnProcessExit: flag

TRUE or FALSE. If TRUE, CDB stops when it receives a process termination notification. Command-line equivalent is -G.

+sxd: event +sxe: event

Sets the debugger response and the handling status for the specified exception or event.

+

Exceptions and events may be specified in the following ways:

+

+*: Default exception +n: Exception n (decimal) +0xn: Exception 0xn (hexadecimal) +(other): Event code +

See [Controlling Exceptions and Events](controlling-exceptions-and-events.md) for details of this process and for other methods of controlling these settings.

VerboseOutput: flag

TRUE or FALSE. If TRUE, CDB will display detailed information about symbol handling, event notification, and other run-time occurrences. Command-line equivalent is -v.

lines: flag

TRUE or FALSE. The lines flag enables or disables support for source-line information.

srcopt: options

Sets the source line options that control source display and program stepping options. For more information see [l+, l- (Set Source Options)](l---l---set-source-options-.md).

srcpath: directory

Sets the source file search path. For more information see [.srcpath, .lsrcpath (Set Source Path)](-srcpath---lsrcpath--set-source-path-.md).

enable_unicode: flag

TRUE or FALSE. The enable_unicode flag specifies whether the debugger displays USHORT pointers and arrays as Unicode strings.

force_radix_output: flag

TRUE or FALSE. The force_radix_output flag specifies whether integers are displayed in decimal format or in the default radix.

col_mode: flag

TRUE or FALSE. The col_mode flag controls the color mode setting. When color mode is enabled the debugger can produce colored output. By default, most colors are not set and instead default to the current console colors.

col: name colspec

The name indicates the element that you are coloring. The colspec is a three-letter RGB indicator of the form [rR-][gG-][bB-]. A lower-case letter indicates darker, an upper-case letter indicates brighter and a dash indicates no color component contribution. Due to console color limitations, bright is not actually per-component, but applies to all components if any request bright. In other words, rgB is the same as RGB. For this reason, it is recommended that all caps be used if any caps are going to be used.

+

Example usage:

+

col: emphfg R--

+ +  + +A sample \[NTSD\] section in the tools.ini file follows: + +``` +[NTSD] +sxe: 3c +sxe: cc +$u0: VeryLongName +VerboseOutput:true +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20tools.ini%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/connecting-to-targets.md b/windows-driver-docs-pr/debugger/connecting-to-targets.md new file mode 100644 index 0000000000..dbd05b7fe9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/connecting-to-targets.md @@ -0,0 +1,37 @@ +--- +title: Connecting to Targets +description: Connecting to Targets +ms.assetid: d85169d8-a226-4bc4-a4f3-6eb88d1fad2c +keywords: ["Debugger Engine, connecting to targets", "targets", "targets, connecting to"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Connecting to Targets + + +## + + +This section includes: + +[Live User-Mode Targets](live-user-mode-targets.md) + +[Live Kernel-Mode Targets](live-kernel-mode-targets.md) + +[Dump-File Targets](dump-file-targets.md) + +[Remote Targets](remote-targets.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Connecting%20to%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/control-flow-tokens.md b/windows-driver-docs-pr/debugger/control-flow-tokens.md new file mode 100644 index 0000000000..56bf8d6cef --- /dev/null +++ b/windows-driver-docs-pr/debugger/control-flow-tokens.md @@ -0,0 +1,73 @@ +--- +title: Control Flow Tokens +description: Control Flow Tokens +ms.assetid: c38852aa-3dfe-4f70-9ef4-8c86e4a8334d +keywords: ["script file, control flow tokens", "control flow tokens", "debugger command program, control flow tokens"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Control Flow Tokens + + +## + + +You can use *control flow tokens* to create conditional execution and execution loops within debugger command programs. + +Control flow tokens behave like their counterparts in C and C++, with the following general exceptions: + +- You must enclose each block of commands that is executed conditionally or repeatedly in braces, even if there is only one such command. For example, you cannot omit the braces in the following command. + ``` + 0:000> .if (ebx>0) { r ebx } + ``` + +- Each condition must be a expression. Commands are not permitted. For example, the following example produces a syntax error. + ``` + 0:000> .while (r ebx) { .... } + ``` + +- The final command before a closing brace does not have to be followed by a semicolon. + +The following control flow tokens are supported within a debugger command program. For more information about the syntax of each token, see the individual reference topics. + +- The [**.if**](-if.md) token behaves like the **if** keyword in C. + +- The [**.else**](-else.md) token behaves like the **else** keyword in C. + +- The [**.elsif**](-elsif.md) token behaves like the **else if** keyword combination in C. + +- The [**.foreach**](-foreach.md) token parses the output of debugger commands, a string, or a text file. This token then takes each item that it finds and uses them as the input to a specified list of debugger commands. + +- The [**.for**](-for.md) token behaves like the **for** keyword in C, except that you must separate multiple increment commands by semicolons, not by commas. + +- The [**.while**](-while.md) token behaves like the **while** keyword in C. + +- The [**.do**](-do.md) token behaves like the **do** keyword in C, except that you cannot use the word "while" before the condition. + +- The [**.break**](https://msdn.microsoft.com/library/windows/hardware/ff556242) token behaves like the **break** keyword in C. You can use this token within any **.for**, **.while**, or **.do** loop. + +- The [**.continue**](-continue.md) token behaves like the **continue** keyword in C. You can use this token within any **.for**, **.while**, or **.do** loop. + +- The [**.catch**](-catch.md) token prevents a program from ending if an error occurs. The **.catch** token is followed by braces that enclose one or more commands. If one of these commands generates an error, the error message is displayed, all remaining commands within the braces are ignored, and execution resumes with the first command after the closing brace. + +- The [**.leave**](-leave.md) token is used to exit from a **.catch** block. + +- The [**.printf**](-printf.md) token behaves like the **printf** statement in C. + +- The [**.block**](-block.md) token performs no action. You should use this token only to introduce a block, because you cannot create a block by only using a pair of braces. You must add a control flow token before the opening brace. + +The [**!for\_each\_module**](-for-each-module.md), [**!for\_each\_frame**](-for-each-frame.md), and [**!for\_each\_local**](-for-each-local.md) extensions are also useful with a debugger command program. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Control%20Flow%20Tokens%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/control-keys.md b/windows-driver-docs-pr/debugger/control-keys.md new file mode 100644 index 0000000000..0378102a37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/control-keys.md @@ -0,0 +1,33 @@ +--- +title: Control Keys +description: Control Keys +ms.assetid: 48a0b379-1911-4f43-9288-db9c4d55e0bd +keywords: ["control keys", "control keys, complete listing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Control Keys + + +## + + +This section of the reference discusses the various control keys that can be used in the debuggers. + +These control keys work in KD and, in some cases, CDB. Many of these also work in WinDbg (using the CTRL+ALT keys instead of just CTRL). + +WinDbg also uses the CTRL key, the ALT key, and the F keys as shortcut keys to toggle the menu options. See [Shortcut Keys](keyboard-shortcuts.md) for a list of their meanings. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Control%20Keys%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-a-kd-connection-server-session.md b/windows-driver-docs-pr/debugger/controlling-a-kd-connection-server-session.md new file mode 100644 index 0000000000..24c66cb996 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-a-kd-connection-server-session.md @@ -0,0 +1,41 @@ +--- +title: Controlling a KD Connection Server Session +description: Controlling a KD Connection Server Session +ms.assetid: d927575f-f408-48d0-81f4-0711a09b0015 +keywords: ["KD connection server, controlling a session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling a KD Connection Server Session + + +## + + +Once the remote session has been started, the smart client can be used as if it were debugging the target computer from the computer where the KD connection server is running. All commands will behave as they would in this situation, except that paths are relative to the smart client's computer. + +### Using WinDbg as a Smart Client + +After WinDbg is started as a smart client for a KD connection server, you can use the [Debug | Stop Debugging](debug---stop-debugging.md) command to end the debugging session. At that point, WinDbg will enter dormant mode and will no longer be connected to the KD connection server. All subsequent debugging will be done on the computer where WinDbg is running. You cannot reattach to the KD connection serve by using [File | Kernel Debug](file---kernel-debug.md) -- this can only be done from the command line. + +### Ending the Session + +KD or WinDbg can exit or end the debugging session in the normal fashion. See [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) + +for details. The KD connection server will remain in operation and can be re-used as many times as desired. (It can also be used by for any number of simultaneous debugging sessions.) + +The KD connection server can be terminated from either computer. To terminate it from the smart client, use the [**.endpsrv (End Process Server)**](-endpsrv--end-process-server-.md) command. To terminate the KD connection server from the computer it is running on, use Task Manager to end the kdsrv.exe process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20a%20KD%20Connection%20Server%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-a-process-server-session.md b/windows-driver-docs-pr/debugger/controlling-a-process-server-session.md new file mode 100644 index 0000000000..1fc455778f --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-a-process-server-session.md @@ -0,0 +1,43 @@ +--- +title: Controlling a Process Server Session +description: Controlling a Process Server Session +ms.assetid: 4219b08a-d353-43dc-8640-96c504b8075b +keywords: ["process server, controlling a session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling a Process Server Session + + +## + + +Once the remote session has been started, the smart client can be used as if it were debugging a target application on a single machine. All commands will behave as they would in this situation, except that paths are relative to the smart client's computer. + +### Using WinDbg as a Smart Client + +After WinDbg is started as a smart client for a user-mode process server, it will remain attached to the process server permanently. If the debugging session is ended, the [File | Attach to a Process](file---attach-to-a-process.md) menu command or the [**.tlist (List Process IDs)**](-tlist--list-process-ids-.md) command will display all processes running on the computer running the process server. WinDbg can attach to any of these processes. + +The [File | Open Executable](file---open-executable.md) command cannot be used. A new process can only be spawned if it is included on the WinDbg command line. + +In this situation, WinDbg will not be able to debug processes on the computer where it is running, nor will it be able to start a kernel debugging session. + +### Ending the Session + +CDB or WinDbg can exit or end the debugging session in the normal fashion. See [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) for details. The process server will remain in operation and can be re-used as many times as desired. (It can also be used by for any number of simultaneous debugging sessions.) + +The process server can be terminated from either computer. To terminate it from the smart client, use the [**.endpsrv (End Process Server)**](-endpsrv--end-process-server-.md) command. To terminate the process server from the computer it is running on, use Task Manager to end the dbgsrv.exe process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20a%20Process%20Server%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-a-remote-debugging-session.md b/windows-driver-docs-pr/debugger/controlling-a-remote-debugging-session.md new file mode 100644 index 0000000000..a2c2021c34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-a-remote-debugging-session.md @@ -0,0 +1,67 @@ +--- +title: Controlling a Remote Debugging Session +description: Controlling a Remote Debugging Session +ms.assetid: dedd277d-1aa0-468c-919c-29b25b0b5c0d +keywords: ["remote debugging through the debugger, controlling a session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling a Remote Debugging Session + + +## + + +Once the remote session has been started, commands can be entered into either the debugging server or the debugging client. If there are multiple clients, any of them can enter commands. Once ENTER is pressed, the command is transmitted to the debugging server and executed. + +Whenever one user enters a command, all users will see the command itself and its output. If this command was issued from a debugging client, all other users will see an identification, preceding the command, of which user issued the command. Commands issued from the debugging server do not have this prefix. + +After a command is executed by one user, other users who are connected through KD or CDB will not see a new command prompt. On the other hand, users of WinDbg will see the prompt in the bottom panel of the Debugger Command window continuously, even when the debugger engine is running. Neither of these should be a cause for alarm; any user can enter a command at any time, and the engine will execute these commands in the order they were received. + +Actions made through the WinDbg interface will also be executed by the debugging server. + +### Communication Between Users + +Whenever a new debugging client connects to the session, all other users will see a message that this client has connected. No message is displayed when a client disconnects. + +The [**.clients (List Debugging Clients)**](-clients--list-debugging-clients-.md) command will list all clients currently connected to the debugging session. + +The [**.echo (Echo Comment)**](-echo--echo-comment-.md) command is useful for sending messages from one user to another. + +### WinDbg Workspaces + +When WinDbg is being used as a debugging client, its workspace will only save values set through the graphical interface. Changes made through the Debugger Command window will not be saved. (This guarantees that only changes made by the local client will be reflected, since the Debugger Command window will accept input from all clients as well as the debugging server.) + +### File Paths + +The symbol path, executable image path, and extension DLL path are all interpreted as file paths relative to the Debugging Tools for Windows installation folder on the debugging server. + +When WinDbg is used as a debugging client, it has its own *local source path* as well. All source-related commands will access the source files on the local computer. Therefore, the proper paths have to be set on any client or server that will use source commands. + +This multiple-path system allows a debugging client to use source-related commands without actually sharing the source files with other clients or with the server. This is useful if there are private or confidential source files which one of the users has access to. + +### Canceling the Debugging Server + +The [**.endsrv (End Debugging Server)**](-endsrv--end-debugging-server-.md) command can be used to terminate a debugging server. If the debugger has established multiple debugging servers, you can cancel some of them while leaving others running. + +Terminating a server will prevent any future clients from attaching to it. It will not cut off any clients that are currently attached through the server. + +### Exiting the Debugger and Terminating the Session + +To exit from one debugging client without terminating the server, you must issue a command from that specific client. If this client is KD or CDB, use the [**CTRL+B**](ctrl-b--quit-local-debugger-.md) key to exit. If you are using a script to run KD or CDB, use [**.remote\_exit (Exit Debugging Client)**](-remote-exit--exit-debugging-client-.md). If this client is WinDbg, choose **Exit** from the **File** menu to exit. + +To terminate the entire session and exit the debugging server, use the [**q (Quit)**](q--qq--quit-.md) command. This command can be entered from any server or client, and it will terminate the entire session for all users. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20a%20Remote%20Debugging%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-breakpoint-flags-and-parameters.md b/windows-driver-docs-pr/debugger/controlling-breakpoint-flags-and-parameters.md new file mode 100644 index 0000000000..81bc7ee939 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-breakpoint-flags-and-parameters.md @@ -0,0 +1,142 @@ +--- +title: Controlling Breakpoint Flags and Parameters +description: Controlling Breakpoint Flags and Parameters +ms.assetid: ed702f01-2a30-4ffb-a804-167cf3b19936 +keywords: ["breakpoints, flags and parameters", "DEBUG_BREAK_READ", "DEBUG_BREAK_WRITE", "DEBUG_BREAK_EXECUTE", "DEBUG_BREAK_IO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Breakpoint Flags and Parameters + + +## + + +There are a number of methods that can be used to determine basic information about breakpoints: + +- [**GetId**](https://msdn.microsoft.com/library/windows/hardware/ff546827) returns the breakpoint ID. + +- [**GetType**](https://msdn.microsoft.com/library/windows/hardware/ff549370) returns the breakpoint type (software or processor) and the type of the effective processor on which the breakpoint is set. + +- [**GetAdder**](https://msdn.microsoft.com/library/windows/hardware/ff545576) returns the client that added the breakpoint. + +- [**GetOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548008) returns the address of a breakpoint. + +- [**GetOffsetExpression**](https://msdn.microsoft.com/library/windows/hardware/ff548048) returns the expression string that specifies the location of the breakpoint. + +In addition to its location and breakpoint type, a breakpoint has several parameters controlling its behavior. + +Breakpoint parameters can be controlled through a variety of specific methods. In addition, most of the parameters may be queried together using [**GetParameters**](https://msdn.microsoft.com/library/windows/hardware/ff548095). + +### Breakpoint Flags + +Breakpoint flags are one kind of breakpoint parameters. + +Breakpoint flags can be queried using [**GetFlags**](https://msdn.microsoft.com/library/windows/hardware/ff546791). They can be changed by using [**AddFlags**](https://msdn.microsoft.com/library/windows/hardware/ff537903), [**RemoveFlags**](https://msdn.microsoft.com/library/windows/hardware/ff554504), or [**SetFlags**](https://msdn.microsoft.com/library/windows/hardware/ff556703). + +Breakpoint flags form a bit field. The possible flags that can be used in this bit field, and their meanings, are as follows: + +DEBUG\_BREAKPOINT\_ENABLED +When this flag is set, the breakpoint is *enabled* and will have its normal effect. When this flag is not set, the breakpoint is *disabled* and will not have any effect. If you wish to temporarily deactivate a breakpoint, you can remove this flag; it is then easy to add this flag back when you want to re-enable this breakpoint. + +DEBUG\_BREAKPOINT\_ADDER\_ONLY +When this flag is set, the breakpoint is a *private breakpoint*. This breakpoint is visible only to the client that added it. In this case, other clients will not be able to query the engine for the breakpoint, and the engine will not send events generated by the breakpoint to other clients. All callbacks (event and [output](using-input-and-output.md#output)) related to this breakpoint will be sent only to this client. See [**GetAdder**](https://msdn.microsoft.com/library/windows/hardware/ff545576). + +DEBUG\_BREAKPOINT\_GO\_ONLY +When this flag is set, the breakpoint will only be triggered if the target is in unrestricted execution. It will not be triggered if the engine is stepping through instructions in the target. + +DEBUG\_BREAKPOINT\_ONE\_SHOT +When this flag is set, the breakpoint will automatically remove itself the first time it is triggered. + +DEBUG\_BREAKPOINT\_DEFERRED +When this flag is set, the breakpoint is *deferred*. This flag is set by the engine when the offset of the breakpoint is specified using a symbolic expression, and the engine cannot evaluate the expression. Every time a module is loaded or unleaded in the target, the engine will attempt reevaluate the expression for all breakpoints whose location is specified using an expression. Those that cannot be evaluated are flagged as deferred. This flag cannot be modified by any client. + +### Other Breakpoint Parameters + +Breakpoint parameters also include: + +*Pass count* +If the breakpoint has a pass count associated with it, it will not be activated until the target has passed the breakpoint the specified number of times. The pass count that was originally set can be found by using [**GetPassCount**](https://msdn.microsoft.com/library/windows/hardware/ff548104). The number of times remaining that the engine will pass the breakpoint before it is activated can be found using [**GetCurrentPassCount**](https://msdn.microsoft.com/library/windows/hardware/ff545769). The pass count can be reset to a new value by using [**SetPassCount**](https://msdn.microsoft.com/library/windows/hardware/ff556759). + +*Match thread* +If the breakpoint has a thread associated with it, it will be ignored by the engine when it is encountered by any other thread. The thread can be found by using [**GetMatchThreadId**](https://msdn.microsoft.com/library/windows/hardware/ff547074), and can be changed by using [**SetMatchThreadId**](https://msdn.microsoft.com/library/windows/hardware/ff556735). + +*Command* +The breakpoint may have a command associated with it. The command is executed when the breakpoint is activated. This command can be found by using [**GetCommand**](https://msdn.microsoft.com/library/windows/hardware/ff545677), and can be changed by using [**SetCommand**](https://msdn.microsoft.com/library/windows/hardware/ff556632). + +*Size* +If the breakpoint is a processor breakpoint, it must have a specified size. This determines the size of the block of memory whose access will activate the breakpoint -- the beginning of the block is the breakpoint's location. The size can be found by using [**GetDataParameters**](https://msdn.microsoft.com/library/windows/hardware/ff546557), and can be changed by using [**SetDataParameters**](https://msdn.microsoft.com/library/windows/hardware/ff556655). + +*Access type* +If the breakpoint is a processor breakpoint, it must have an access type. This determines the type of access that will activate the breakpoint. For example, the breakpoint may be activated if the target reads from, writes to, or executes the memory specified by the breakpoint. The access type can be found by using [**GetDataParameters**](https://msdn.microsoft.com/library/windows/hardware/ff546557), and can be changed by using [**SetDataParameters**](https://msdn.microsoft.com/library/windows/hardware/ff556655). + +### Valid Parameters for Processor Breakpoints + +The following access types are available for processor breakpoints: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription

DEBUG_BREAK_READ

The breakpoint will be triggered when the CPU reads memory in the breakpoint's memory block.

DEBUG_BREAK_WRITE

The breakpoint will be triggered when the CPU writes memory in the breakpoint's memory block.

+DEBUG_BREAK_READ +| DEBUG_BREAK_WRITE

The breakpoint will be triggered when the CPU reads or writes memory in the breakpoint's memory block.

DEBUG_BREAK_EXECUTE

The breakpoint will be triggered when the CPU fetches the instruction in the breakpoint's memory block.

DEBUG_BREAK_IO

The breakpoint will be triggered when the I/O port in the breakpoints memory block is accessed. (Windows XP and Microsoft Windows Server 2003 only, kernel mode only, x86 only)

+ +  + +Not all access types and sizes are supported on all processors. The following access types and sizes are supported: + +x86 +All access types are supported. DEBUG\_BREAK\_READ behaves like DEBUG\_BREAK\_READ | DEBUG\_BREAK\_WRITE. The size must be 1, 2, or 4. The breakpoint's address must be a multiple of the size. + +x64 +All access types are supported. DEBUG\_BREAK\_READ behaves like DEBUG\_BREAK\_READ | DEBUG\_BREAK\_WRITE. The size must be 1, 2, 4, or 8. The breakpoint's address must be a multiple of the size. + +Itanium +All access types except DEBUG\_BREAK\_IO are supported. The size must be a power of two; for DEBUG\_BREAK\_EXECUTE, the size must be 16. The breakpoint's address must be a multiple of the size. + +Itanium running in x86 mode +The is the same as for x86, except that DEBUG\_BREAK\_IO is not supported. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Breakpoint%20Flags%20and%20Parameters%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-exceptions-and-events.md b/windows-driver-docs-pr/debugger/controlling-exceptions-and-events.md new file mode 100644 index 0000000000..ea6a6546e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-exceptions-and-events.md @@ -0,0 +1,505 @@ +--- +title: Controlling Exceptions and Events +description: Controlling Exceptions and Events +ms.assetid: cc8067f3-07de-4ee2-b028-94f9ac088891 +keywords: ["exceptions", "exceptions, overview", "exceptions, handling", "events", "events, overview", "events, handling"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Exceptions and Events + + +## + + +You can catch and handle exceptions in user-mode and kernel-mode applications by a variety of methods. An active debugger, a postmortem debugger, or an internal error handling routine are all common ways to handle exceptions. + +For more information about the precedence order of these various exception handlers, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +When the Microsoft Windows operating system allows a debugger to handle an exception, the application that generated the exception *breaks into* the debugger. That is, the application stops and the debugger becomes active. The debugger can then handle the exception in some way or analyze the situation. The debugger can then end the process or let it resume running. + +If the debugger ignores the exception and lets the application continue running, the operating system looks for other exception handlers as if no debugger was present. If the exception is handled, the application continues running. However, if the exception remains unhandled, the debugger is then given a second opportunity to deal with the situation. + +### Using the Debugger to Analyze an Exception + +When an exception or event breaks into the debugger, you can use the debugger to examine the code that is being executed and the memory that the application is using. By altering certain quantities or jumping to a different point in the application, you might be able to remove the cause of the exception. + +You can resume execution by issuing a [**gh (Go with Exception Handled)**](gh--go-with-exception-handled-.md) or [**gn (Go with Exception Not Handled)**](gn--gn--go-with-exception-not-handled-.md) command. + +If you issue the **gn** command in the debugger's second opportunity to handle the exception, the application ends. + +### Kernel-Mode Exceptions + +Exceptions that occur in kernel-mode code are more serious than user-mode exceptions. If kernel-mode exceptions are not handled, a [bug check](bug-checks--blue-screens-.md) is issued and the system stops. + +As with user-mode exceptions, if a kernel-mode debugger is attached to the system, the debugger is notified before the *bug check screen* (also known as a *blue screen*) appears. If no debugger is attached, the bug check screen appears. In this case, the operating system might create a [crash dump file](crash-dump-files.md). + +### Controlling Exceptions and Events from the Debugger + +You can configure the debugger to react to specified exceptions and events in a specific way. + +The debugger can set the break status for each exception or event: + +- The event can cause a break into the debugger as soon as it occurs (the "first chance"). + +- The event can break in after other error handlers have been given an opportunity to respond (the "second chance"). + +- The event can also send the debugger a message but continue executing. + +- The debugger can ignore the event. + +The debugger can also set the handling status for each exception and event. The debugger can treat the event like a handled exception or an unhandled exception. (Of course, events that are not actually errors do not require any handling.) + +You can control the break status and handling status by doing one of the following: + +- Use the [**SXE**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md), **SXD**, **SXN**, or **SXI** command in the [Debugger Command window](debugger-command-window.md). + +- (CDB and NTSD) Use the **-x**, **-xe**, **-xd**, **-xn**, or **-xi** option on the [**command line**](cdb-command-line-options.md). + +- (CDB, NTSD, and KD) Use the **sxe** or **sxd** keyword in the [Tools.ini](configuring-tools-ini.md) file. + +- (WinDbg only) Click [Event Filters](debug---event-filters.md) on the **Debug** menu to open the **Event Filters** dialog box, and then choose the options that you want. + +The **SX\*** command, the **-x\*** command-line option, and the **sx\*** Tools.ini keyword typically set the break status of the specified event. You can add the **-h** option to cause the handling status to be set instead. + +There are four special event codes (**cc**, **hc**, **bpec**, and **ssec**) that always specify handling status instead of break status. + +You can display the most recent exception or event by using the [**.lastevent (Display Last Event)**](-lastevent--display-last-event-.md) command. + +### Controlling Break Status + +When you set the break status of an exception or event, you can use the following options. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandStatus nameDescription

+SXE +or +-xe

Break

+

(Enabled)

When this exception occurs, the target immediately breaks into the debugger. This break in occurs before any other error handlers are activated. This method is called first-chance handling.

+SXD +or +-xd

Second chance break

+

(Disabled)

The debugger does not break in for this kind of first-chance exception (although a message is displayed). If other error handlers cannot address this exception, execution stops and the target breaks into the debugger. This method is called second-chance handling.

+SXN +or +-xn

Output

+

(Notify)

When this exception occurs, the target application does not break into the debugger at all. However, a message is displayed that informs the user of this exception.

+SXI +or +-xi

Ignore

When this exception occurs, the target application does not break into the debugger, and no message is displayed.

+ +  + +If an exception is not anticipated by an **SX**\* setting, the target application breaks into the debugger on the second chance. The default status for events is listed in the following "Event Definitions and Defaults" section of this topic. + +To set break status by using the WinDbg graphical interface, [Event Filters](debug---event-filters.md) on the **Debug** menu, click the event that you want from the list in the **Event Filters** dialog box, and then select **Enabled**, **Disabled**, **Output**, or **Ignore**. + +### Controlling Handling Status + +All events are considered unhandled, unless you use the [**gh (Go with Exception Handled)**](gh--go-with-exception-handled-.md) command. + +All exceptions are considered unhandled, unless you use the [**sx\***](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) command together with the **-h** option. + +Additionally, **SX**\* options can configure the handling status for invalid handles, STATUS\_BREAKPOINT break instructions, and single-step exceptions. (This configuration is separate from their break configuration.) When you configure their break status, these events are named **ch**, **bpe**, and **sse**, respectively. When you configure their handling status, these events are named **hc**, **bpec**, and **ssec**, respectively. (For the full listing of events, see the following "Event Definitions and Defaults" section.) + +You can configure the handling status for the CTRL+C event (**cc**), but not its break status. If an application receives a CTRL+C event, the application always breaks into the debugger. + +When you use the **SX**\* command on **cc**, **hc**, **bpec**, and **ssec** events, or when you use the **SX**\* command together with the **-h** option on an exception, the following actions occur. + + +++++ + + + + + + + + + + + + + + + + + + + +
CommandStatus nameDescription

SXE

Handled

The event is considered handled when execution resumes.

SXD,SXN,SXI

Not Handled

The event is considered not handled when execution resumes.

+ +  + +To set handling status by using the WinDbg graphical interface, click [Event Filters](debug---event-filters.md) on the **Debug** menu, click the event that you want from the list in the **Event Filters** dialog box, and then select **Handled** or **Not Handled**. + +### Automatic Commands + +The debugger also enables you to set commands that are automatically executed if the event or exception causes a break into the debugger. You can set a command string for the first-chance break and a command string for the second-chance break. You can set these strings with the [**SX\***](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) command or the [Debug | Event Filters](debug---event-filters.md) command. Each command string can contain multiple commands that are separated with semicolons. + +These commands are executed regardless of the break status. That is, if the break status is "Ignore," the command is still executed. If the break status is "Second-chance break," the first-chance command is executed when the exception first occurs, before any other exception handlers are involved. The command string can end with an execution command such as [**g (Go)**](g--go-.md), [**gh (Go with Exception Handled)**](gh--go-with-exception-handled-.md), or [**gn (Go with Exception Not Handled)**](gn--gn--go-with-exception-not-handled-.md). + +### Event Definitions and Defaults + +You can change the break status or handling status of the following exceptions. Their default break status is indicated. + +The following exceptions' default handling status is always "Not Handled". Be careful about changing this status. If you change this status to "Handled", all first-chance and second-chance exceptions of this type are considered handled, and this configuration bypasses all of the exception-handling routines. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event codeMeaningDefault break status

asrt

Assertion failure

Break

av

Access violation

Break

dm

Data misaligned

Break

dz

Integer division by zero

Break

c000008e

Floating point division by zero

Break

eh

C++ EH exception

Second-chance break

gp

Guard page violation

Break

ii

Illegal instruction

Second-chance break

iov

Integer overflow

Break

ip

In-page I/O error

Break

isc

Invalid system call

Break

lsq

Invalid lock sequence

Break

sbo

Stack buffer overflow

Break

sov

Stack overflow

Break

wkd

Wake debugger

Break

aph

Application hang

+

This exception is triggered if the Windows operating system concludes that a process has stopped responding (that is, is hung).

Break

3c

Child application termination

Second-chance break

chhc

Invalid handle

Break

Number

Any numbered exception

Second-chance break

+ +  + +**Note**   You can override the **asrt** break status for a specific address by using the [**ah (Assertion Handling)**](ah--assertion-handling-.md) command. The **ch** and **hc** event codes refer to the same exception. When you are controlling its break status, use **sx\* ch**. When you are controlling its handling status, use **sx\* hc**. + +  + +You can change the break status or handling status of the following exceptions. Their default break status is indicated. + +The following exceptions' default handling status is always "Handled". Because these exceptions are used to communicate with the debugger, you should not typically change their status to "Not Handled". This status causes other exception handlers to catch the exceptions if the debugger ignores them. + +An application can use DBG\_COMMAND\_EXCEPTION (**dbce**) to communicate with the debugger. This exception is similar to a breakpoint, but you can use the **SX**\* command to react in a specific way when this exception occurs. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event codeMeaningDefault break status

dbce

Special debugger command exception

Ignore

vcpp

Special Visual C++ exception

Ignore

wos

WOW64 single-step exception

Break

wob

WOW64 breakpoint exception-

Break

ssessec

Single-step exception

Break

bpebpec

Breakpoint exception

Break

ccecc

CTRL+C or CTRL+BREAK

+

This exception is triggered if the target is a console application and CTRL+C or CTRL+BREAK is passed to it.

Break

+ +  + +**Note**   The final three exceptions in the preceding table have two different event codes. When you are controlling their break status, use **sse**, **bpe**, and **cce**. When you are controlling their handling status, use **ssec**, **bpec**, and **cc**. + +  + +### The following exceptions are useful when you are debugging managed code. + + +++++ + + + + + + + + + + + + + + + + + + + +
Event codeMeaningDefault status

clr

Common Language Runtime exception

Second-chance break

+

Not handled

clrn

Common Language Runtime notification exception

Second-chance break

+

Handled

+ +  + +You can change the break status of the following events. Because these events are not exceptions, their handling status is irrelevant. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event codeMeaningDefault break status

ser

System error

Ignore

cpr[:Process]

Process creation

+

Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel mode.

+

You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either through the -o[command-line option](cdb-command-line-options.md) or through the [.childdbg (Debug Child Processes)](-childdbg--debug-child-processes-.md) command.

+

The process name can include an optional file name extension and an asterisk (*) or question mark (?) as wildcard characters. The debugger remembers only the most recent cpr setting. Separate settings for separate processes are not supported. Include a colon or a space between cpr and Process.

+

If Process is omitted, the setting applies to any child process creation.

Ignore

epr[:Process]

Process exit

+

Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel mode.

+

You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either through the -o[command-line option](cdb-command-line-options.md) or through the [.childdbg (Debug Child Processes)](-childdbg--debug-child-processes-.md) command.

+

The process name can include an optional file name extension and an asterisk (*) or question mark (?) as wildcard characters. The debugger remembers only the most recent epr setting. Separate settings for separate processes are not supported. Include a colon or a space between epr and Process.

+

If Process is omitted, the setting applies to any child process exit.

Ignore

ct

Thread creation

Ignore

et

Thread exit

Ignore

ld[:Module]

Load module

+

If you specify Module, the break occurs when the module with this name is loaded. Module can specify the name or the address of the module. If the name is used, Module might contain a variety of wildcard characters and specifiers. (For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md).)

+

The debugger remembers only the most recent ld setting. Separate settings for separate modules are not supported. Include a colon or a space between ld and Module.

+

If Module is omitted, the event is triggered when any module is loaded.

Output

ud[:Module]

Unload module

+

If you specify Module, the break occurs when the module with this name, or at this base address, is unloaded. Module can specify the name or the address of the module. If the name is used, Module can be an exact name or include wildcard characters. If Module is an exact name, it is immediately resolved to a base address by using the current debugger module list and it is stored as an address. If Module contains wildcard characters, the pattern string is kept for later matching when unload events occur.

+

Rarely, the debugger does not have name information for unload events and matches only by the base address. Therefore, if Module contains wildcard characters, the debugger cannot perform a name match in this particular unload case and breaks when any module is unloaded.

+

The debugger remembers only the most recent ud setting. Separate settings for separate modules are not supported. Include a colon or a space between ld and Module.

+

If Module is omitted, the event is triggered when any module is loaded.

Output

out[:Output]

Target application output

+

If you specify Output, the break occurs only when output that matches the specified pattern is received. Output can contain a variety of wildcard characters and specifiers. (For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md).) However, Output cannot contain a colon or spaces. The match is not case sensitive. Include a colon or space between out and Output.

Ignore

ibp

Initial break point

+

(This event occurs at the beginning of the debug session and after you restart the target computer.)

In user mode: Break. You can change this status to "Ignore" by using the -g[command-line option](command-line-options.md).

+

In kernel mode: Ignore. You can change this status to "Enabled" by a variety of methods. For more information about how to change this status, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md).

iml

Initial module load

+

(Kernel mode only)

Ignore. You can change this status to "Break" by a variety of methods. For more information about how to change this status, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md).

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Exceptions%20and%20Events%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-processes-and-threads.md b/windows-driver-docs-pr/debugger/controlling-processes-and-threads.md new file mode 100644 index 0000000000..b603b4f70a --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-processes-and-threads.md @@ -0,0 +1,99 @@ +--- +title: Controlling Processes and Threads +description: Controlling Processes and Threads +ms.assetid: f5a50b54-443e-425e-98cb-cff8d31ac897 +keywords: ["process", "process, choosing", "thread", "thread, choosing", "thread, freezing", "thread, unfreezing (thawing)", "thread, suspending", "suspend count of threads", "freezing threads"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Processes and Threads + + +## + + +When you are performing user-mode debugging, you activate, display, freeze, unfreeze, suspend, and unsuspend processes and threads. + +The *current* or *active* process is the process that is currently being debugged. Similarly, the *current* or *active* thread is the thread that the debugger is currently controlling. The actions of many debugger commands are determined by the identity of the current process and thread. The current process also determines the virtual address mappings that the debugger uses. + +When debugging begins, the current process is the one that the debugger is attached to or that caused the exception that broke into the debugger. Similarly, the current thread is the one that was active when the debugger attached to the process or that caused the exception. However, you can use the debugger to change the current process and thread and to freeze or unfreeze individual threads. + +In kernel-mode debugging, processes and threads are not controlled by the methods that are described in this section. For more information about how processes and threads are manipulated in kernel mode, see [Changing Contexts](changing-contexts.md). + +### Displaying Processes and Threads + +To display process and thread information, you can use the following methods: + +- The [**| (Process Status)**](---process-status-.md) command + +- The [**~ (Thread Status)**](---thread-status-.md) command + +- (WinDbg only) The [Processes and Threads window](processes-and-threads-window.md) + +### Setting the Current Process and Thread + +To change the current process or thread, you can use the following methods: + +- The [**|s (Set Current Process)**](-s--set-current-process-.md) command + +- The [**~s (Set Current Thread)**](-s--set-current-thread-.md) command + +- (WinDbg only) The [Processes and Threads window](processes-and-threads-window.md) + +### Freezing and Suspending Threads + +The debugger can change the execution of a thread by *suspending* the thread or by *freezing* the thread. These two actions have somewhat different effects. + +Each thread has a *suspend count* that is associated with it. If this count is one or larger, the system does not run the thread. If the count is zero or lower, the system runs the thread when appropriate. + +Typically, each thread has a suspend count of zero. When the debugger attaches to a process, it increments the suspend counts of all threads in that process by one. If the debugger detaches from the process, it decrements all suspend counts by one. When the debugger executes the process, it temporarily decrements all suspend counts by one. + +You can control the suspend count of any thread from the debugger by using the following methods: + +- The [**~n (Suspend Thread)**](-n--suspend-thread-.md) command increments the specified thread's suspend count by one. + +- The [**~m (Resume Thread)**](-m--resume-thread-.md) command decrements the specified thread's suspend count by one. + +The most common use for these commands is to raise a specific thread's suspend count from one to two. When the debugger executes or detaches from the process, the thread then has a suspend count of one and remains suspended, even if other threads in the process are executing. + +You can suspend threads even when you are performing [noninvasive debugging](noninvasive-debugging--user-mode-.md). + +The debugger can also *freeze* a thread. This action is similar to suspending the thread in some ways. However, "frozen" is only a debugger setting. Nothing in the Windows operating system recognizes that anything is different about this thread. + +By default, all threads are unfrozen. When the debugger causes a process to execute, threads that are frozen do not execute. However, if the debugger detaches from the process, all threads unfreeze. + +To freeze and unfreeze individual threads, you can use the following methods: + +- The [**~f (Freeze Thread)**](-f--freeze-thread-.md) command freezes the specified thread. + +- The [**~u (Unfreeze Thread)**](-u--unfreeze-thread-.md) command unfreezes the specified thread. + +In any event, threads that belong to the target process never execute when the debugger has broken into the target. The suspend count of a thread affects the thread's behavior only when the debugger executes the process or detaches. The frozen status affects the thread's behavior only when the debugger executes the process. + +### Threads and Processes in Other Commands + +You can add thread specifiers or process specifiers before many other commands. For more information, see the individual command topics. + +You can add the [**~e (Thread-Specific Command)**](-e--thread-specific-command-.md) qualifier before many commands and extension commands. This qualifier causes the command to be executed with respect to the specified thread. This qualifier is especially useful if you want to apply a command to more than one thread. For example, the following command repeats the [**!gle**](-gle.md) extension command for every thread that is being debugged. + +``` +~*e !gle +``` + +### Multiple Systems + +The debugger can attach to multiple targets at the same time. When these processes include dump files or include live targets on more than one computer, the debugger references a system, process, and thread for each action. For more information about this kind of debugging, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Processes%20and%20Threads%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-the-target.md b/windows-driver-docs-pr/debugger/controlling-the-target.md new file mode 100644 index 0000000000..d3e227e186 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-the-target.md @@ -0,0 +1,271 @@ +--- +title: Controlling the Target +description: Controlling the Target +ms.assetid: bc08b925-2a55-4af6-a5e2-949637a4c7ee +keywords: ["controlling the target", "controlling the target, overview", "starting and stopping the target", "execution of the target"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling the Target + + +## + + +While you are debugging a target application in user mode or a target computer in kernel mode, the target can be *running* or *stopped*. + +When the debugger connects to a kernel-mode target, the debugger leaves the target running, unless you use the **-b** [command-line option](command-line-options.md), the target system has stopped responding (that is, *crashed*), or the target system is still stopped because of an earlier kernel debugging action. + +When the debugger starts or connects to a user-mode target, the debugger immediately stops the target, unless you use the **-g** command-line option. For more information, see [Initial Breakpoint](initial-breakpoint.md). + +### When the Target is Running + +When the target is running, most debugger actions are unavailable. + +If you want to stop a running target, you can issue a **Break** command. This command causes the debugger to *break into the target*. That is, the debugger stops the target and all control is given to the debugger. The application might not break immediately. For example, if all threads are currently executing system code, or are in a wait operation, the application breaks only after control has returned to the application's code. + +If a running target encounters an exception, if certain [events](controlling-exceptions-and-events.md) occur, if a [breakpoint](using-breakpoints.md) is hit, or if the application closes normally, the target *breaks into the debugger*. This action stops the target and gives all control to the debugger. A message appears in the [Debugger Command window](debugger-command-window.md) and describes the error, event, or breakpoint. + +### When the Target is Stopped + +To start or control the target's execution, you can do the following: + +- To cause the application to begin running, issue the **Go** command. + +- To step through the application one instruction at a time, use the **Step Into** or **Step Over** commands. If a function call occurs, **Step Into** enters the function and continues stepping through each instruction. **Step Over** treats the function call as a single step. When the debugger is in [Assembly Mode](debugging-in-assembly-mode.md), stepping occurs one machine instruction at a time. When the debugger is in [Source Mode](debugging-in-source-mode.md), stepping occurs one source line at a time. + +- To finish the current function and stop when the return occurs, use the **Step Out** or **Trace and Watch** commands. The **Step Out** command continues until the current function ends. **Trace and Watch** continues until the current function ends and also displays a summary of the function's calls. However, you must issue the **Trace and Watch** command on the first instruction of the function in question. + +- If an exception occurs, you can use the **Go with Exception Handled** and **Go with Exception Not Handled** commands to resume execution and control the status of the exception. (For more information about exceptions, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md).) + +- (WinDbg only) If you select a line in the [Disassembly window](disassembly-window.md) or a [Source window](source-window.md) and then use the **Run to Cursor** command, the program runs until it encounters the selected line. + +- (User Mode only) To close the target application and restart it from the beginning, use the **Restart** command. You can use this command only with a process that the debugger created. After the process is restarted, it immediately breaks into the debugger. + +- (WinDbg only) To close the target application and clear the debugger, use the **Stop Debugging** command. This command enables you to start debugging a different target. + +### Command Forms + +Most commands for starting or controlling the target's execution exist as text commands, menu commands, toolbar buttons, and shortcut keys. As basic text commands, you can use these commands in CDB, KD, or WinDbg. (The text form of the commands frequently supports additional options, such as changing the location of the program counter or executing a fixed number of instructions.) You can use the menu commands, toolbar buttons, and shortcut keys in WinDbg. + +You can use the commands in the following forms. + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandWinDbg buttonWinDbg commandWinDbg shortcut keysEffect
Screen shot of the Run to Cursor button

[Debug | Run to Cursor](debug---run-to-cursor.md)

F7

+

CTRL + F10

(WinDbg only) Executes until it reaches the line that the cursor marks.

Screen shot of the Stop Debugging button

[Debug | Stop Debugging](debug---stop-debugging.md)

SHIFT + F5

Stops all debugging and closes the target.

(CDB/KD only) [CTRL+C](ctrl-c--break-.md)

Screen shot of the Break button

[Debug | Break](debug---break.md)

CTRL + BREAK

Execution stops, and the debugger breaks into the target.

[.restart (Restart Target Application)](-restart--restart-target-application-.md)

Screen shot of the Restart button

[Debug | Restart](debug---restart.md)

CTRL + SHIFT + F5

(User mode only) Restarts the target application.

[g (Go)](g--go-.md)

Screen shot of the Go button

[Debug | Go](debug---go.md)

F5

Target executes freely.

[gc (Go from Conditional Breakpoint)](gc--go-from-conditional-breakpoint-.md)

Resumes execution after a [conditional breakpoint](setting-a-conditional-breakpoint.md).

[gh (Go with Exception Handled)](gh--go-with-exception-handled-.md)

[Debug | Go Handled Exception](debug---go-handled-exception.md)

Same as g (Go), except that the current exception is treated as handled.

[gn (Go with Exception Not Handled)](gn--gn--go-with-exception-not-handled-.md)

[Debug | Go Unhandled Exception](debug---go-unhandled-exception.md)

Same as g (Go), except that the current exception is treated as unhandled.

[gu (Go Up)](gu--go-up-.md)

Screen shot of the Step Out button

[Debug | Step Out](debug---step-out.md)

SHIFT + F11

Target executes until the current function is complete.

[p (Step)](p--step-.md)

Screen shot of the Step Over button

[Debug | Step Over](debug---step-over.md)

F10

Target executes one instruction. If this instruction is a function call, that function is executed as a single step.

[pa (Step to Address)](pa--step-to-address-.md)

Target executes until it reaches the specified address. All steps in this function are displayed (but steps in called functions are not).

[pc (Step to Next Call)](pc--step-to-next-call-.md)

Target executes until the next call instruction. If the current instruction is a call instruction, this call is executed completely and execution continues until the next call.

[pct (Step to Next Call or Return)](pct--step-to-next-call-or-return-.md)

Target executes until it reaches a call instruction or a return instruction.

[ph (Step to Next Branching Instruction)](ph--step-to-next-branching-instruction-.md)

Target executes until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls.

[pt (Step to Next Return)](pt--step-to-next-return-.md)

Target executes until it reaches a return instruction.

[t (Trace)](t--trace-.md)

Screen shot of the Step Into button

[Debug | Step Into](debug---step-into.md)

F11

+

F8

Target executes one instruction. If this instruction is a function call, debugger traces into that call.

[ta (Trace to Address)](ta--trace-to-address-.md)

Target executes until it reaches the specified address. All steps in this function and called functions are displayed.

[tb (Trace to Next Branch)](tb--trace-to-next-branch-.md)

(All modes, except kernel mode, only on x86-based systems) Target executes until it reaches the next branch instruction.

[tc (Trace to Next Call)](tc--trace-to-next-call-.md)

Target executes until the next call instruction. If the current instruction is a call instruction, the instruction is traced into until a new call is reached.

[tct (Trace to Next Call or Return)](tct--trace-to-next-call-or-return-.md)

Target executes until it reaches a call instruction or return instruction. If the current instruction is a call instruction or return instruction, the instruction is traced into until a new call or return is reached.

[th (Trace to Next Branching Instruction)](th--trace-to-next-branching-instruction-.md)

Target executes until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls. If the current instruction is a branching instruction, the instruction is traced into until a new branching instruction is reached.

[tt (Trace to Next Return)](tt--trace-to-next-return-.md)

Target executes until it reaches a return instruction. If the current instruction is a return instruction, the instruction is traced into until a new return is reached.

[wt (Trace and Watch Data)](wt--trace-and-watch-data-.md)

Target executes until the completion of the whole specified function. Statistics are then displayed.

+ +  + +For more information about how to restart the target computer, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +### Command-Line Options + +If you do not want the application to stop immediately when it starts or loads, use CDB or WinDbg together with the **-g** command-line option. For more information about this situation, see [Initial Breakpoint](initial-breakpoint.md). + +CDB and WinDbg also support the **-G** [command-line option](command-line-options.md). This option causes the debugging session to end if the application completes properly. + +The following command tries to run the application from start to finish, and the debugger prompt appears only if an error occurs. + +``` +cdb -g -G ApplicationName +``` + +You can use the **-pt** [command-line option](command-line-options.md) to set the break time-out. There are certain problems that can make the target unable to communicate with the debugger. If a break command is issued and the debugger cannot break into the target after this time, the debugger displays a "Break-in timed out" message. + +At this point, the debugger stops trying to break into the target. Instead, the debugger pauses the target and enables you to examine (but not control) the target application. + +The default time-out is 30 seconds. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20the%20Target%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-the-user-mode-debugger-from-the-kernel-debugger.md b/windows-driver-docs-pr/debugger/controlling-the-user-mode-debugger-from-the-kernel-debugger.md new file mode 100644 index 0000000000..0c80cb97f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-the-user-mode-debugger-from-the-kernel-debugger.md @@ -0,0 +1,47 @@ +--- +title: Controlling the User-Mode Debugger from the Kernel Debugger +description: Controlling the User-Mode Debugger from the Kernel Debugger +ms.assetid: 8fba2187-cf22-41ad-9b06-228a5b082822 +keywords: ["KD, controlling CDB or NTSD", "WinDbg, controlling CDB or NTSD", "CDB, redirecting control to the kernel debugger", "NTSD, redirecting control to the kernel debugger", "redirecting user-mode output to the kernel debugger", "controlling the user-mode debugger from the kernel debugger", "controlling the user-mode debugger from the kernel debugger, overview", "controlling the user-mode debugger from the kernel debugger, sleep mode", "sleep mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling the User-Mode Debugger from the Kernel Debugger + + +## + + +You can redirect the input and output from a user-mode debugger to a kernel debugger. This redirection enables the kernel debugger to control a specific user-mode debugging session that is occurring on the target computer. + +You can use either KD or WinDbg as the kernel debugger. Note that many of the familiar features of WinDbg are not available in this scenario. For example, you cannot use the Locals window, the Disassembly window, or the Call Stack window, and you cannot step through source code. This is because WinDbg is only acting as a viewer for the debugger (NTSD or CDB) running on the target computer. + +You can use either CDB or NTSD as the user-mode debugger. NTSD is the better choice, because it requires minimal resources from the processor and operating system of the computer whose application is being debugged. In fact, when NTSD is started under the control of the kernel debugger, no NTSD window is created. With NTSD, you can perform user-mode debugging through the serial port early in the boot phase and late into shutdown. + +**Note**  The [**.shell**](-shell--command-shell-.md) command is not supported when the output of a user-mode debugger is redirected to the kernel debugger. + +  + +This section includes the following: + +- [Starting the Debugging Session](starting-the-debugging-session.md) describes how to begin a session where the user-mode debugger is controlled from the kernel debugger. + +- [Switching Modes](switching-modes.md) describes the four different modes that are involved, and how to alternate between them. + +- [When to Use This Technique](when-to-use-this-technique.md) describes scenarios where this technique is particularly useful. + +- [Combining This Method with Remote Debugging](combining-this-method-with-remote-debugging.md) describes how to control the user-mode debugger from a kernel debugger, and use it as a debugging server at the same time. This combination can be useful if your user-mode symbols are located on a symbol server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20the%20User-Mode%20Debugger%20from%20the%20Kernel%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-threads-and-processes.md b/windows-driver-docs-pr/debugger/controlling-threads-and-processes.md new file mode 100644 index 0000000000..63eacd272a --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-threads-and-processes.md @@ -0,0 +1,107 @@ +--- +title: Controlling Threads and Processes +description: Controlling Threads and Processes +ms.assetid: 6182ca34-ee5e-47e9-82fe-29266397e3a8 +keywords: ["Debugger Engine API, threads and processes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Threads and Processes + + +## + + +For an overview of threads and processes in the debugger engine, see [Threads and Processes](threads-and-processes.md). + +When an event occurs, the event thread and event process are set to the thread and process (operating system or virtual) in which the event occurred. They can be found using [**GetEventThread**](https://msdn.microsoft.com/library/windows/hardware/ff546646) and [**GetEventProcess**](https://msdn.microsoft.com/library/windows/hardware/ff546640), respectively. + +### Implicit Threads and Processes + +In kernel-mode debugging the debugger engine will use the *implicit process* to determine which virtual address space to use when performing virtual to physical address translation -- for example, in the methods [**VirtualToPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff560335) and [**ReadVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554359). When an event occurs, the implicit process is set to the current process. + +The implicit process may be changed by using [**SetImplicitProcessDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff556713). To determine the implicit process use [**GetImplicitProcessDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546865). + +**Note**   When setting [breakpoints](multiprocessor-syntax.md#breakpoints) during a live kernel debugging session, the debugger engine will pass the virtual address of the breakpoint to the target, and the target will set the breakpoint. In this case, only the process context of the target is used when handling the breakpoint; the value of the implicit process is irrelevant. + +  + +In kernel-mode debugging, the debugger engine will use the *implicit thread* to determine some of the target's [registers](x86-architecture.md#registers). This includes the processor stack (see [**GetStackOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548403)), the frame offset (see [**GetFrameOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546806)), and the instruction offset (see [**GetInstructionOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546916)). When an event occurs, the implicit thread is set to the current thread. + +The implicit thread may be changed by using [**SetImplicitThreadDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff556716). To determine the implicit thread, use [**GetImplicitThreadDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546871). + +Not all registers are determined by the implicit thread. Some registers will remain the same when the implicit thread is changed. + +**Warning**   The implicit process and implicit thread are independent. If the implicit thread does not belong to the implicit process, then user and session state for the implicit thread will be in the wrong virtual address space and attempts to access this information will cause errors or provide incorrect results. This problem does not occur when accessing kernel memory, since kernel memory addresses are constant across all virtual address spaces. Thus information for the implicit thread located in kernel memory may be accessed independent of the implicit process. + +  + +### Threads + +The *engine thread ID* is used by the debugger engine to identify each operating system thread and each virtual thread for a target. + +While a target is stopped, each thread also has an index relative to the process to which it belongs. For any process, the index of the first thread in the process is zero, and the index of the last thread is the number of threads in the process minus one. The number of threads in the current process can be found by using [**GetNumberThreads**](https://msdn.microsoft.com/library/windows/hardware/ff547992). The total number of threads in all processes in the current target can be found by using [**GetTotalNumberThreads**](https://msdn.microsoft.com/library/windows/hardware/ff549356). + +The engine thread ID and system thread ID for one or more threads in the current process can be found from their index by using [**GetThreadIdsByIndex**](https://msdn.microsoft.com/library/windows/hardware/ff549339). + +The engine maintains several pieces of information about each thread. This information may be queried for the current thread, and may be used to find the engine thread ID for a thread. + +system thread ID (user-mode debugging only) +The system thread ID of the current thread can be found by using [**GetCurrentThreadSystemId**](https://msdn.microsoft.com/library/windows/hardware/ff546544). For a given system thread ID, the corresponding engine thread ID may be found by using [**GetThreadIdBySystemId**](https://msdn.microsoft.com/library/windows/hardware/ff549329). + +thread environment block (TEB) +The address of the TEB for the current thread can be found by using [**GetCurrentThreadTeb**](https://msdn.microsoft.com/library/windows/hardware/ff546549). For a given TEB address, the corresponding engine thread ID may be found by using [**GetThreadIdByTeb**](https://msdn.microsoft.com/library/windows/hardware/ff549336). In kernel-mode debugging, the TEB of a (virtual) thread is the TEB of the system thread that was running on the corresponding processor when the last event occurred. + +data offset +In user-mode debugging, the data offset of a (system) thread is the location of the TEB for that thread. In kernel-mode debugging the data offset of a (virtual) thread is the KTHREAD structure for the system thread that was running on the corresponding processor when the last event occurred. The data offset of the current thread can be found by using [**GetCurrentThreadDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff545894). For a given data offset, the corresponding engine thread ID may be found by using [**GetThreadIdByDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff549302). + +system handle +The system handle of the current thread can be found by using [**GetCurrentThreadHandle**](https://msdn.microsoft.com/library/windows/hardware/ff545904). For a given system handle, the corresponding engine thread ID may be found by using [**GetThreadIdByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff549312). In kernel-mode debugging, an artificial handle is created for each (virtual) process. This handle can only be used with debugger engine API queries. + +### Processes + +The *engine process ID* is used by the debugger engine to identify each operating system process and each virtual process for a target. + +While a target is stopped, each process has an index relative to the target. The index of the first process in the target is zero, and the index of the last process is the number of processes in the target minus one. The number of processes in the current target can be found by using [**GetNumberProcesses**](https://msdn.microsoft.com/library/windows/hardware/ff547946). + +The engine process ID and system process ID for one or more threads in the current target can be found from their index by using [**GetProcessIdsByIndex**](https://msdn.microsoft.com/library/windows/hardware/ff548160). + +The engine maintains several pieces of information about each process. This information may be queried for the current process, and may be used to find the engine process ID for a process. + +system process ID (user-mode debugging only) +The system process ID of the current process can be found by using [**GetCurrentProcessSystemId**](https://msdn.microsoft.com/library/windows/hardware/ff545850). For a given system process ID, the corresponding engine process ID may be found by using [**GetProcessIdBySystemId**](https://msdn.microsoft.com/library/windows/hardware/ff548155). + +process environment block (PEB) +The address of the PEB for the current process can be found by using [**GetCurrentProcessPeb**](https://msdn.microsoft.com/library/windows/hardware/ff545839). For a given PEB address, the corresponding engine process ID may be found by using [**GetProcessIdByPeb**](https://msdn.microsoft.com/library/windows/hardware/ff548150). In kernel-mode debugging, the PEB of the (virtual) process is the PEB of the system process that was running when the last event occurred. + +data offset +In user-mode debugging, the data offset of a (system) process is the location of the PEB of that process. In kernel-mode debugging, the data offset of the (virtual) process is the KPROCESS structure for the system process that was running when the last event occurred. The data offset of the current process can be found by using [**GetCurrentProcessDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff545787). For a given data offset, the corresponding engine process ID may be found by using [**GetProcessIdByDataOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548140). + +system handle +The system handle of the current process can be found by using [**GetCurrentProcessHandle**](https://msdn.microsoft.com/library/windows/hardware/ff545829). For a given system handle, the corresponding engine process ID may be found by using [**GetProcessIdByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff548147). In kernel-mode debugging, an artificial handle is created for the (virtual) process. This handle can only be used with debugger engine queries. + +### Events + +In live user-mode debugging, whenever a thread is created or exits in a target, the create-thread and exit-thread debugging events are generated. These events result in calls to the [**IDebugEventCallbacks::CreateThread**](https://msdn.microsoft.com/library/windows/hardware/ff550713) and [**IDebugEventCallbacks::ExitThread**](https://msdn.microsoft.com/library/windows/hardware/ff550730) callback methods. + +In live user-mode debugging, whenever a process is created or exits in a target, the create-process and exit-process debugging events are generated. These events result in calls to the [**IDebugEventCallbacks::CreateProcess**](https://msdn.microsoft.com/library/windows/hardware/ff550697) and [**IDebugEventCallbacks::ExitProcess**](https://msdn.microsoft.com/library/windows/hardware/ff550728) callback methods. + +For more information about events, see [Monitoring Events](monitoring-events.md). + +### Additional Information + +For more information about threads and processes, including the TEB, KTHREAD, PEB, and KPROCESS structures, see *Microsoft Windows Internals* by David Solomon and Mark Russinovich. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Threads%20and%20Processes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/controlling-variables-through-the-watch-window.md b/windows-driver-docs-pr/debugger/controlling-variables-through-the-watch-window.md new file mode 100644 index 0000000000..a83e088610 --- /dev/null +++ b/windows-driver-docs-pr/debugger/controlling-variables-through-the-watch-window.md @@ -0,0 +1,33 @@ +--- +title: Controlling Variables Through the Watch Window +description: Controlling Variables Through the Watch Window +ms.assetid: bd857442-fbd7-4c00-9743-6077d38ee38e +keywords: ["Watch window, global variables", "Watch window, local variables"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Variables Through the Watch Window + + +## + + +In WinDbg, you can also use the Watch window to display and change global and local variables. + +The Watch window can display any list of variables that you want. These variables can include global variables and local variables from any function. At any time, the Watch window displays the values of those variables that match the current function's scope. You can also change the values of these variables through the Watch window. + +Unlike the Locals window, the Watch window is not affected by changes to the local context. Only those variables that are defined in the scope of the current program counter can have their values displayed or modified. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Variables%20Through%20the%20Watch%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/converting-virtual-addresses-to-physical-addresses.md b/windows-driver-docs-pr/debugger/converting-virtual-addresses-to-physical-addresses.md new file mode 100644 index 0000000000..07b0e41069 --- /dev/null +++ b/windows-driver-docs-pr/debugger/converting-virtual-addresses-to-physical-addresses.md @@ -0,0 +1,199 @@ +--- +title: Converting Virtual Addresses to Physical Addresses +description: Converting Virtual Addresses to Physical Addresses +ms.assetid: 5b3d19df-09cc-4131-ae64-5ce64d986df3 +keywords: ["virtual address", "virtual address, converting to physical address", "physical address", "physical address, converting from virtual address", "addresses", "addresses, converting virtual to physical", "memory, virtual addresses", "memory, physical addresses"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Converting Virtual Addresses to Physical Addresses + + +## + + +Most debugger commands use virtual addresses, not physical addresses, as their input and output. However, there are times that having the physical address can be useful. + +There are two ways to convert a virtual address to a physical address: by using the **!vtop** extension, and by using the **!pte** extension. + +### Address Conversion Using !vtop + +Suppose you are debugging a target computer on which the MyApp.exe process is running and you want to investigate the virtual address 0x0012F980. Here is the procedure you would use with the **!vtop** extension to determine the corresponding physical address. + +**Converting a virtual address to a physical address using !vtop** + +1. Make sure that you are working in hexadecimal. If necessary, set the current base with the [**N 16**](n--set-number-base-.md) command. + +2. Determine the *byte index* of the address. This number is equal to the lowest 12 bits of the virtual address. Thus, the virtual address 0x0012F980 has a byte index of 0x980. + +3. Determine the *directory base* of the address by using the [**!process**](-process.md) extension: + + ``` + kd> !process 0 0 + **** NT ACTIVE PROCESS DUMP **** + .... + PROCESS ff779190 SessionId: 0 Cid: 04fc Peb: 7ffdf000 ParentCid: 0394 + DirBase: 098fd000 ObjectTable: e1646b30 TableSize: 8. + Image: MyApp.exe + ``` + +4. Determine the *page frame number* of the directory base. This is simply the directory base without the three trailing hexadecimal zeros. In this example, the directory base is 0x098FD000, so the page frame number is 0x098FD. + +5. Use the [**!vtop**](-vtop.md) extension. The first parameter of this extension should be the page frame number. The second parameter of **!vtop** should be the virtual address in question: + + ``` + kd> !vtop 98fd 12f980 + Pdi 0 Pti 12f + 0012f980 09de9000 pfn(09de9) + ``` + + The second number shown on the final line is the physical address of the beginning of the physical page. + +6. Add the byte index to the address of the beginning of the page: 0x09DE9000 + 0x980 = 0x09DE9980. This is the desired physical address. + +You can verify that this computation was done correctly by displaying the memory at each address. The [**!d\***](-db---dc---dd---dp---dq---du---dw.md) extension displays memory at a specified physical address: + +``` +kd> !dc 9de9980 +# 9de9980 6d206e49 726f6d65 00120079 0012f9f4 In memory....... +# 9de9990 0012f9f8 77e57119 77e8e618 ffffffff .....q.w...w.... +# 9de99a0 77e727e0 77f6f13e 77f747e0 ffffffff .'.w>..w.G.w.... +# 9de99b0 ..... +``` + +The [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command uses a virtual address as its argument: + +``` +kd> dc 12f980 +0012f980 6d206e49 726f6d65 00120079 0012f9f4 In memory....... +0012f990 0012f9f8 77e57119 77e8e618 ffffffff .....q.w...w.... +0012f9a0 77e727e0 77f6f13e 77f747e0 ffffffff .'.w>..w.G.w.... +0012f9b0 ..... +``` + +Because the results are the same, this indicates that the physical address 0x09DE9980 does indeed correspond to the virtual address 0x0012F980. + +### Address Conversion Using !pte + +Again, assume you are investigating the virtual address 0x0012F980 belonging to the MyApp.exe process. Here is the procedure you would use with the **!pte** extension to determine the corresponding physical address: + +**Converting a virtual address to a physical address using !pte** + +1. Make sure that you are working in hexadecimal. If necessary, set the current base with the [**N 16**](n--set-number-base-.md) command. + +2. Determine the *byte index* of the address. This number is equal to the lowest 12 bits of the virtual address. Thus, the virtual address 0x0012F980 has a byte index of 0x980. + +3. Set the [process context](changing-contexts.md#process-context) to the desired process: + + ``` + kd> !process 0 0 + **** NT ACTIVE PROCESS DUMP **** + .... + PROCESS ff779190 SessionId: 0 Cid: 04fc Peb: 7ffdf000 ParentCid: 0394 + DirBase: 098fd000 ObjectTable: e1646b30 TableSize: 8. + Image: MyApp.exe + + kd> .process /p ff779190 + Implicit process is now ff779190 + .cache forcedecodeuser done + ``` + +4. Use the [**!pte**](-pte.md) extension with the virtual address as its argument. This displays information in two columns. The left column describes the page directory entry (PDE) for this address; the right column describes its page table entry (PTE): + + ``` + kd> !pte 12f980 + VA 0012f980 + PDE at C0300000 PTE at C00004BC + contains 0BA58067 contains 09DE9067 + pfn ba58 ---DA--UWV pfn 9de9 ---DA--UWV + ``` + +5. Look in the last row of the right column. The notation "pfn 9de9" appears. The number 0x9DE9 is the *page frame number* (PFN) of this PTE. Multiply the page frame number by 0x1000 (for example, shift it left 12 bits). The result, 0x09DE9000, is the physical address of the beginning of the page. + +6. Add the byte index to the address of the beginning of the page: 0x09DE9000 + 0x980 = 0x09DE9980. This is the desired physical address. + +This is the same result obtained by the earlier method. + +### Converting Addresses By Hand + +Although the **!ptov** and **pte** extensions supply the fastest way to convert virtual addresses to physical addresses, this conversion can be done manually as well. A description of this process will shed light on some of the details of the virtual memory architecture. + +Memory structures vary in size, depending on the processor and the hardware configuration. This example is taken from an x86 system that does not have Physical Address Extension (PAE) enabled. + +Using 0x0012F980 again as the virtual address, you first need to convert it to binary, either by hand or by using the [**.formats (Show Number Formats)**](-formats--show-number-formats-.md) command: + +``` +kd> .formats 12f980 +Evaluate expression: + Hex: 0012f980 + Decimal: 1243520 + Octal: 00004574600 + Binary: 00000000 00010010 11111001 10000000 + Chars: .... + Time: Thu Jan 15 01:25:20 1970 + Float: low 1.74254e-039 high 0 + Double: 6.14381e-318 +``` + +This virtual address is a combination of three fields. Bits 0 to 11 are the byte index. Bits 12 to 21 are the page table index. Bits 22 to 31 are the page directory index. Separating the fields, you have: + +``` +0x0012F980 = 0y 00000000 00 010010 1111 1001 10000000 +``` + +This exposes the three parts of the virtual address: + +- Page directory index = 0y0000000000 = 0x0 + +- Page table index = 0y0100101111 = 0x12F + +- Byte index = 0y100110000000 = 0x980 + +You then need three additional pieces of information for your system. + +- The size of each PTE. This is 4 bytes on non-PAE x86 systems. + +- The size of a page. This is 0x1000 bytes. + +- The PTE\_BASE virtual address. On a non-PAE system, this is 0xC0000000. + +Using this data, you can compute the address of the PTE itself: + +``` +PTE address = PTE_BASE + + (page directory index) * PAGE_SIZE + + (page table index) * sizeof(MMPTE) + = 0xc0000000 + + 0x0 * 0x1000 + + 0x12F * 4 + = 0xC00004BC +``` + +This is the address of the PTE. The PTE is a 32-bit DWORD. Examine its contents: + +``` +kd> dd 0xc00004bc L1 +c00004bc 09de9067 +``` + +This PTE has value 0x09DE9067. It is made of two fields: + +- The low 12 bits of the PTE are the *status flags*. In this case, these flags equal 0x067 -- or in binary, 0y000001100111. For an explanation of the status flags, see the [**!pte**](-pte.md) reference page. + +- The high 20 bits of the PTE are equal to the *page frame number* (PFN) of the PTE. In this case, the PFN is 0x09DE9. + +The first physical address on the physical page is the PFN multiplied by 0x1000 (shifted left 12 bits). The byte index is the offset on this page. Thus,the physical address you are looking for is 0x09DE9000 + 0x980 = 0x09DE9980. This is the same result obtained by the earlier methods. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Converting%20Virtual%20Addresses%20to%20Physical%20Addresses%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/crash-dump-files.md b/windows-driver-docs-pr/debugger/crash-dump-files.md new file mode 100644 index 0000000000..13a821a8fe --- /dev/null +++ b/windows-driver-docs-pr/debugger/crash-dump-files.md @@ -0,0 +1,40 @@ +--- +title: Crash dump analysis using the Windows debuggers (WinDbg) +description: You analyze crash dump files by using WinDbg and other Windows debuggers. +ms.assetid: e7b4883c-6551-4a94-80d2-635f79348a48 +keywords: dump file, crash dump file +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Crash dump analysis using the Windows debuggers (WinDbg) + + +You analyze crash dump files by using WinDbg and other Windows debuggers. + +## + + +This section includes: + +[Kernel-Mode Dump Files](kernel-mode-dump-files.md) + +[User-Mode Dump Files](user-mode-dump-files.md) + +[Extracting Information from a Dump File](extracting-information-from-a-dump-file.md) +**Note**  This topic is for programmers. If you are a customer who has received a blue screen error code while using your computer, see [Troubleshoot blue screen errors](http://go.microsoft.com/fwlink/p/?linkid=183646). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Crash%20dump%20analysis%20using%20the%20Windows%20debuggers%20%28WinDbg%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/crashing-and-rebooting-the-target-computer.md b/windows-driver-docs-pr/debugger/crashing-and-rebooting-the-target-computer.md new file mode 100644 index 0000000000..e21b2647d5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/crashing-and-rebooting-the-target-computer.md @@ -0,0 +1,55 @@ +--- +title: Crashing and Rebooting the Target Computer +description: This topic covers crashing and rebooting the Target Computer +ms.assetid: 7480e572-05ca-40c6-aa91-b1ab35e4496b +keywords: debugging, debug, controlling the target, crashing the target computer, rebooting the target computer, reboot, boot process, system crash, bug check +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Crashing and Rebooting the Target Computer + + +## + + +When you perform kernel debugging, you can cause the target computer to stop responding (that is, *crash* or *bug check*) by issuing the [**.crash (Force System Crash)**](-crash--force-system-crash-.md) command. This command immediately causes the target computer to stop responding. The debugger writes a kernel-mode dump file if you have enabled crash dumps. (For more information about these files, see [Creating a Kernel-Mode Dump File](creating-a-kernel-mode-dump-file.md).) + +To restart the target computer, use the [**.reboot (Reboot Target Computer)**](-reboot--reboot-target-computer-.md) command. + +If you want the target computer to create a crash dump file and then restart, you should issue the **.crash** command, followed by the **.reboot** command. If you want only to restart, the **.crash** command is not required. + +In the early stages of the boot process, the connection between the host computer and the target computer is lost. No information about the target computer is available to the debugger. + +After the connection is broken, the debugger closes all symbol files and unloads all debugger extensions. At this point, all breakpoints are lost if you are running KD or CDB. In WinDbg, you can save the current workspace. This action saves all breakpoints. + +If you want to end the debugging session at this point, use the [**CTRL+B**](ctrl-b--quit-local-debugger-.md) command (in KD) or click **Exit** on the **File** menu (in WinDbg). + +If you do not exit the debugger, the connection is reestablished after enough of the boot process has completed. Symbols and extensions are reloaded at this point. If you are running WinDbg, the kernel-mode workspace is reloaded. + +You can tell the debugger to automatically break into the target computer during the restart process at two possible times: + +- When the first kernel module is loaded into memory + +- When the kernel initializes + +To set an automatic breakpoint when the first kernel module loads, use the **-d** [command-line option](command-line-options.md). + +You can also change the break state after the debugger is running: + +- Control the initial module load and kernel initialization breakpoints like all exceptions and events. You can break into the debugger when these events occur, or ignore them. You can also have a specified command automatically execute when these breakpoints are hit. For more information, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +- Use the [**CTRL+K**](ctrl-k--change-post-reboot-break-state-.md) shortcut keys in KD, the [CTRL+ALT+K](debug---kernel-connection---cycle-initial-break.md) shortcut keys in WinDbg, and the Debug | Kernel Connection | Cycle Initial Break command in WinDbg to change the break state. Every time that you use these commands, the debugger switches between three states: no automatic break, break upon kernel initialization, and break on first kernel module load. This method cannot activate both automatic breakpoints at the same time. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Crashing%20and%20Rebooting%20the%20Target%20Computer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/create-kernel-mode-stack-trace-database.md b/windows-driver-docs-pr/debugger/create-kernel-mode-stack-trace-database.md new file mode 100644 index 0000000000..fd4008d60e --- /dev/null +++ b/windows-driver-docs-pr/debugger/create-kernel-mode-stack-trace-database.md @@ -0,0 +1,60 @@ +--- +title: Create kernel mode stack trace database +description: Create kernel mode stack trace database +ms.assetid: 0c1f94c0-ebc7-4e3c-8101-ba3cf830e7f8 +keywords: ["Create kernel mode stack trace database (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Create kernel mode stack trace database + + +## + + +The **Create kernel mode stack trace database** flag creates a run-time stack trace database of kernel operations, such as resource objects and object management operations, and works only when using the checked build of Windows. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

kst

Hexadecimal value

0x2000

Symbolic Name

FLG_KERNEL_STACK_TRACE_DB

Destination

System-wide registry entry

+ +  + +### Comments + +GFlags displays this flag as a kernel flag setting, but it is not effective at run time, because the kernel is already started. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Create%20kernel%20mode%20stack%20trace%20database%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/create-user-mode-stack-trace-database.md b/windows-driver-docs-pr/debugger/create-user-mode-stack-trace-database.md new file mode 100644 index 0000000000..000cb17cb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/create-user-mode-stack-trace-database.md @@ -0,0 +1,56 @@ +--- +title: Create user mode stack trace database +description: Create user mode stack trace database +ms.assetid: c24a42d3-cb06-4ce5-bf90-c8a224bf7d01 +keywords: ["Create user mode stack trace database (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Create user mode stack trace database + + +## + + +The **Create user mode stack trace database** flag creates a run-time stack trace database in the address space of a particular process (image file mode) or all processes (system-wide). + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

ust

Hexadecimal value

0x1000

Symbolic Name

FLG_USER_STACK_TRACE_DB

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Create%20user%20mode%20stack%20trace%20database%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-a-dump-file-without-a-system-crash.md b/windows-driver-docs-pr/debugger/creating-a-dump-file-without-a-system-crash.md new file mode 100644 index 0000000000..26ba2ea0a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-a-dump-file-without-a-system-crash.md @@ -0,0 +1,35 @@ +--- +title: Creating a Dump File Without a System Crash +description: Creating a Dump File Without a System Crash +ms.assetid: 747194d0-0aac-487a-acdc-ff27721606d4 +keywords: ["dump file, creating without a system crash"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Dump File Without a System Crash + + +## + + +If KD or WinDbg is performing kernel-mode debugging, it can cause a kernel-mode dump file to be written without crashing the target computer. + +This dump file can be either a Complete Memory Dump or a Small Memory Dump. The Control Panel settings are not relevant to this action. + +Whereas dump files caused by a system crash are written to the computer that has crashed, this dump file will be written to the host computer. + +For details, see the [**.dump (Create Dump File)**](-dump--create-dump-file-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20a%20Dump%20File%20Without%20a%20System%20Crash%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-a-kernel-mode-dump-file.md b/windows-driver-docs-pr/debugger/creating-a-kernel-mode-dump-file.md new file mode 100644 index 0000000000..3fbdb94713 --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-a-kernel-mode-dump-file.md @@ -0,0 +1,51 @@ +--- +title: Creating a Kernel-Mode Dump File +description: Creating a Kernel-Mode Dump File +ms.assetid: d3eb86b2-eba7-4ddb-90e9-0e26414436fb +keywords: ["dump file, creating kernel-mode dump file", "dump file, NMI switch", "NMI switch"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Kernel-Mode Dump File + + +## + + +There are three ways in which a kernel-mode dump file can be created: + +1. You can enable the dump file from the Control Panel, and then the system can crash on its own. + +2. You can enable the dump file from the Control Panel, and then force the system to crash. + +3. You can use the debugger to create a dump file without crashing the system. + +This section includes: + +[Enabling a Kernel-Mode Dump File](enabling-a-kernel-mode-dump-file.md) + +[Forcing a System Crash](forcing-a-system-crash.md) + +[Creating a Dump File Without a System Crash](creating-a-dump-file-without-a-system-crash.md) + +[Verifying the Creation of a Kernel-Mode Dump File](verifying-the-creation-of-a-kernel-mode-dump-file.md) + +### Using an NMI Switch + +It is also possible to use an NMI switch to create a crash dump file. Contact your hardware vendor to determine whether your machine has this switch. + +The usage of NMI switches is not covered in this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20a%20Kernel-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-a-new-dock.md b/windows-driver-docs-pr/debugger/creating-a-new-dock.md new file mode 100644 index 0000000000..1fefaab973 --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-a-new-dock.md @@ -0,0 +1,37 @@ +--- +title: Creating a New Dock +description: Creating a New Dock +ms.assetid: 99cba4f9-4025-4684-920b-43c7147b5385 +keywords: ["docking windows, creating a new dock", "window docking, creating a new dock"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a New Dock + + +## + + +When WinDbg is started, the WinDbg window is the only possible docking location. + +To create a new dock, on the **Window** menu, click **Open Dock**. This dock is an independent window that you can maximize, minimize, or drag like any other window on the desktop. + +A new dock can also be created by using the **Move to new dock** option on the shortcut menu for any already open window. This selection will close the window and open it in a new dock. + +You can create as many docks as you want. + +To close a dock and any debugging information windows that are currently docked there, click the **Close** button in the upper-right corner of the dock. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20a%20New%20Dock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-a-user-mode-dump-file.md b/windows-driver-docs-pr/debugger/creating-a-user-mode-dump-file.md new file mode 100644 index 0000000000..39265a0dbe --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-a-user-mode-dump-file.md @@ -0,0 +1,41 @@ +--- +title: Creating a User-Mode Dump File +description: Creating a User-Mode Dump File +ms.assetid: 7fa6735f-e845-4a09-b637-8e9d1b024578 +keywords: ["dump file, creating user-mode dump file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a User-Mode Dump File + + +## + + +There are several different tools that can be used to create a user-mode dump file: CDB, WinDbg, Windows Error Reporting (WER), UserDump, and ADPlus. + +This section includes: + +[Choosing the Best Tool](choosing-the-best-tool.md) + +[CDB and WinDbg](cdb-and-windbg.md) + +[UserDump](userdump.md) + +For information about creating a user-mode dump file through ADPlus, see [ADPlus](adplus.md). + +For information about creating a user-mode dump file through WER, see [Windows Error Reporting](windows-error-reporting.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20a%20User-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-and-opening-a-workspace.md b/windows-driver-docs-pr/debugger/creating-and-opening-a-workspace.md new file mode 100644 index 0000000000..a8ab81eb24 --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-and-opening-a-workspace.md @@ -0,0 +1,89 @@ +--- +title: Creating and Opening a Workspace +description: Creating and Opening a Workspace +ms.assetid: 0163f380-f982-4635-a450-ed83f0b52e03 +keywords: ["workspaces, creating", "workspaces, opening", "workspaces, named workspaces", "workspaces, default workspaces", "workspaces, types of workspaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating and Opening a Workspace + + +## + + +WinDbg has two kinds of workspaces: *default workspaces* and *named workspaces*. + +### Default Workspaces + +WinDbg has several different kinds of default workspaces: + +- The *base workspace* is used when WinDbg is in a dormant state. + +- The *default user-mode workspace* is used when you are attaching to a user-mode process (by using the **-p**[**command-line option**](windbg-command-line-options.md) or by using the [File | Attach to a Process](file---attach-to-a-process.md) command). + +- The *remote default workspace* is used when you are connecting to a debugging server. + +- The *default kernel-mode workspace* is used when WinDbg begins a kernel-mode debugging session. + +- The *processor-specific workspace* is used during kernel-mode debugging after WinDbg attaches to the target computer. There are separate processor-specific workspaces for x86-based and x64-based processors. + +When WinDbg creates a user-mode process for debugging, a workspace is created for that executable file. Each created executable file has its own workspace. + +When WinDbg analyzes a dump file, a workspace is created for that dump file analysis session. Each dump file has its own workspace. + +When you begin a debugging session, the appropriate workspace is loaded. When you end a debugging session or exit WinDbg, a dialog box is displayed and asks you if you want to save the changes that you have made to the current workspace. If you start WinDbg with the **-QY**[**command-line option**](windbg-command-line-options.md), this dialog box does not appear, and workspaces are automatically saved. Also, if you start WinDbg by the **-Q** command-line option, this dialog box does not appear, and no changes are saved. + +Workspaces load in a cumulative manner. The base workspace is always loaded first. When you begin a particular debugging action, the appropriate workspace is loaded. So most debugging is completed after two workspaces have been loaded. Kernel-mode debugging is completed after three workspaces have been loaded (the base workspace, the default kernel-mode workspace, and the processor-specific workspace). + +For greatest efficiency, you should save settings in lower-level workspaces if you want them to apply to all of your WinDbg work. + +**Note**   The layout of the debugging information windows is one exception to the cumulative behavior of workspaces. The position, docking status, and size of each window are determined by only the most recent workspace that you opened. This behavior includes the contents of the Watch window and the locations that you viewed in each [Memory window](memory-window.md). The command history in the [Debugger Command window](debugger-command-window.md) is not cleared when a new workspace is opened, but all other window states are reset. + +  + +To access the base workspace, start WinDbg with no target, or click [Stop Debugging](debug---stop-debugging.md) on the **Debug** menu after your session is complete. You can then make any edits that are allowed in the base workspace. + +### Named Workspaces + +You can also give workspaces names and then save or load them individually. After you load a named workspace, all automatic loading and saving of default workspaces is disabled. + +Named workspaces contain some additional information that default workspaces do not. For more information about this additional information, see [Workspace Contents](workspace-contents.md). + +### Opening, Saving, and Clearing Workspaces + +To control workspaces, you can do the following: + +- Open and load a named workspace by using the **-W** [**command-line option**](windbg-command-line-options.md). + +- Open and load a workspace from a file by using the **-WF** [**command-line option**](windbg-command-line-options.md). + +- Disable all automatic workspace loading by using the **-WX** [**command-line option**](windbg-command-line-options.md). Only explicit workspace commands cause workspaces to be saved or loaded. + +- Open and load a named workspace by clicking [Open Workspace](file---open-workspace.md) on the **File** menu or pressing CTRL+W. + +- Save the current default workspace or the current named workspace by clicking [Save Workspace](file---save-workspace.md) on the **File** menu. + +- Assign a name to the current workspace and save it by clicking [Save Workspace As](file---save-workspace-as.md) on the **File** menu. + +- Delete specific items and settings from the current workspace by clicking [Clear Workspace](file---clear-workspace.md) on the **File** menu. + +- Delete workspaces by clicking [Delete Workspaces](file---delete-workspaces.md) on the **File** menu. + +- Open and load a workspace from a file by clicking [Open Workspace in File](file---open-workspace-in-file.md) on the **File** menu. + +- Save a workspace to a file by clicking [Save Workspace to File](file---save-workspace-to-file.md) on the **File** menu. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20and%20Opening%20a%20Workspace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-your-own-provider-module.md b/windows-driver-docs-pr/debugger/creating-your-own-provider-module.md new file mode 100644 index 0000000000..e420538cbe --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-your-own-provider-module.md @@ -0,0 +1,121 @@ +--- +title: Creating Your Own Provider Module +description: Creating Your Own Provider Module +ms.assetid: 4282d375-bcf0-478f-bb2f-a43dc50b09e3 +keywords: ["version control systems, provider modules"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating Your Own Provider Module + + +In general, to create your own provider module, you must implement the following set of interfaces. + +**$module::SimpleUsage()** + +**Purpose** +Displays simple module usage information to STDOUT. + +**Parameters** +None + +**Return Value** +None + +**$module::VerboseUsage()** + +**Purpose** +Displays in-depth module usage information to STDOUT. + +**Parameters** +None + +**Return Value** +None + +**$objref = $module::new(***@CommandArguments***)** + +**Purpose** +Initializes an instance of the provider module. + +**Parameters** + +*@CommandArguments* +All @ARGV arguments that are not recognized by ssindex.cmd as being general arguments. + +**Return Value** +A reference that can be used in later operations. + +**$objref->GatherFileInformation(***$SourcePath***,***$ServerHashReference***)** + +**Purpose** +Enables the module to gather the required source-indexing information for the directory specified by the *$SourcePath* parameter. The module should not assume that this entry is called only once for each object instancebecause SSIndex may call it multiple times for different paths. + +**Parameters** + +*$SourcePath* +The local directory containing the source to be indexed. + +*$ServerHashReference* +A reference to a hash containing all of the entries from the specified Srcsrv.ini file. + +**Return Value** +None + +**(***$VariableHashReference***,***$FileEntry***) = $objref**->**GetFileInfo(***$LocalFile***)** + +**Purpose** +Provides the necessary information to extract a single, specific file from the source control system. + +**Parameters** + +*$LocalFile* +A fully qualified file name. + +**Return Values** + +*$VariableHashReference* +A hash reference of the variables necessary to interpret the returned *$FileEntry*. Ssindex.cmd caches these variables for every source file used by a single debug file to reduce the amount of information written to the source index stream. + +*$FileEntry* +The file entry to be written to the source index stream to allow SrcSrv to extract this file from source control. The exact format of this line is specific to the source control system. + +*$TextString***= $objref->LongName()** + +**Purpose** +Provides a descriptive string to identify the source control system to the end user. + +**Parameters** +None + +**Return Value** + +*$TextString* +The descriptive name of the source control system. + +**@StreamVariableLines=$objref->SourceStreamVariables()** + +**Purpose** +Enables the source control system to add source-control-specific variables to the source stream for each debug file. The sample modules use this method for writing the required EXTRACT\_CMD and EXTRACT\_TARGET variables. + +**Parameters** +None + +**Return Value** + +*@StreamVariableLines* +The list of entries for the source stream variables. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20Your%20Own%20Provider%20Module%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/creating-your-own-source-control-system.md b/windows-driver-docs-pr/debugger/creating-your-own-source-control-system.md new file mode 100644 index 0000000000..e936a7eb58 --- /dev/null +++ b/windows-driver-docs-pr/debugger/creating-your-own-source-control-system.md @@ -0,0 +1,34 @@ +--- +title: Creating Your Own Source Control System +description: Creating Your Own Source Control System +ms.assetid: 86492545-fc94-40ee-b22d-26fa2b0fbcc8 +keywords: ["source servers, HTTP sites", "source servers, UNC shares", "SrcSrv, HTTP sites", "SrcSrv, UNC shares"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating Your Own Source Control System + + +This section enables you to understand how to prepare instrumentation scripts so that SrcSrv can be integrated into your build or version control system. The implementation is dependent on the language specification version that ships with SrcSrv. + +Many of the specifics of how Srcsrv.dll is called by symbol handler code are discussed. However, this information is not static and will not become so in the future. No one should attempt to write code that calls Srcsrv.dll directly. This is reserved for DbgHelp or the Visual Studio products. Third-party vendors wanting to integrate such functionality into their products should use the **SymGetSourceFile** function. This function, along with others in the DbgHelp API, is described in the DbgHelp documentation, which can be found in the sdk/help subdirectory of the Debugging Tools for Windows installation directory. + +This section includes: + +[Language Specification 1](language-specification-1.md) + +[Language Specification 2](language-specification-2.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Creating%20Your%20Own%20Source%20Control%20System%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/critical-section-time-outs.md b/windows-driver-docs-pr/debugger/critical-section-time-outs.md new file mode 100644 index 0000000000..8a2a92d5a5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/critical-section-time-outs.md @@ -0,0 +1,145 @@ +--- +title: Critical Section Time Outs +description: Critical Section Time Outs +ms.assetid: 736ec6e9-e822-49aa-8f1c-7e5e43779dbd +keywords: ["critical section, debugging critical section time outs"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Critical Section Time Outs + + +## + + +Critical section time outs can be identified by the stack trace that shows the routine **RtlpWaitForCriticalSection** near the top of the stack. Another variety of critical section time out is a possible deadlock application error. To debug critical section time outs properly, CDB or WinDbg is necessary. + +As with resource time outs, the **!ntsdexts.locks** extension will give a list of locks currently held and the threads that own them. Unlike resource time outs, the thread IDs given are not immediately useful. These are system IDs that do not map directly to the thread numbers used by CDB. + +Just as with **ExpWaitForResource*Xxx***, the lock identifier is the first parameter to **RtlpWaitForCriticalSection**. Continue tracing the chain of waits until either a loop is found or the final thread is not waiting for a critical section time out. + +### Example of Debugging a Critical Time Out + +Start by displaying the stack: + +``` +0:024> kb + +ChildEBP RetAddr Args to Child +0569fca4 77f79c78 77f71000 002a6b88 7fffffff ntdll!_DbgBreakPoint +0569fd04 77f71048 5ffa9f9c 5fef0b4b 5ffa9f9c ntdll!_RtlpWaitForCriticalSection+0x89 +0569fd0c 5fef0b4b 5ffa9f9c 002a6b88 002a0019 ntdll!_RtlEnterCriticalSection+0x48 +0569fd70 5fedf83f 002a6b88 0569fdc0 0000003e winsrv!_StreamScrollRegion+0x1f0 +0569fd8c 5fedfa5b 002a6b88 00190000 00000000 winsrv!_AdjustCursorPosition+0x8e +0569fdc0 5fedf678 0569ff18 0031c200 0335ee88 winsrv!_DoWriteConsole+0x104 + +0569fefc 5fe6311b 0569ff18 0569ffd0 00000005 winsrv!_SrvWriteConsole+0x96 +0569fff4 00000000 00000000 00000024 00000024 csrsrv!_CsrApiRequestThread+0x4ff +``` + +Now use the [**!ntsdexts.locks**](-locks---ntsdexts-locks-.md) extension to find the critical section: + +``` +0:024> !locks +CritSec winsrv!_ScrollBufferLock at 5ffa9f9c 5ffa9f9c is the first one +LockCount 5 +RecursionCount 1 +OwningThread 88 // here's the owning thread ID +EntryCount 11c +ContentionCount 135 +*** Locked + +CritSec winsrv!_gcsUserSrv+0 at 5ffa91b4 //second critical section found below + +LockCount 8 +RecursionCount 1 +OwningThread 6d // second owning thread +EntryCount 1d6c +ContentionCount 1d47 +*** Locked +``` + +Now search for the thread that has the ID number 0x6D: + +``` +0:024> ~ + 0 id: 16.15 Teb 7ffdd000 Unfrozen + 1 id: 16.13 Teb 7ffdb000 Unfrozen + 2 id: 16.30 Teb 7ffda000 Unfrozen + 3 id: 16.2f Teb 7ffd9000 Unfrozen + 4 id: 16.2e Teb 7ffd8000 Unfrozen + 5 id: 16.6c Teb 7ff6c000 Unfrozen + 6 id: 16.6d Teb 7ff68000 Unfrozen // this thread owns the second critical section + 7 id: 16.2d Teb 7ffd7000 Unfrozen + 8 id: 16.33 Teb 7ffd6000 Unfrozen + 9 id: 16.42 Teb 7ff6f000 Unfrozen + 10 id: 16.6f Teb 7ff6e000 Unfrozen + 11 id: 16.6e Teb 7ffd5000 Unfrozen + 12 id: 16.52 Teb 7ff6b000 Unfrozen + 13 id: 16.61 Teb 7ff6a000 Unfrozen + 14 id: 16.7e Teb 7ff69000 Unfrozen + 15 id: 16.43 Teb 7ff67000 Unfrozen + 16 id: 16.89 Teb 7ff50000 Unfrozen + 17 id: 16.95 Teb 7ff65000 Unfrozen + 18 id: 16.90 Teb 7ff64000 Unfrozen + 19 id: 16.71 Teb 7ff63000 Unfrozen + 20 id: 16.bb Teb 7ff62000 Unfrozen + 21 id: 16.88 Teb 7ff61000 Unfrozen // this thread owns the first critical section + 22 id: 16.cd Teb 7ff5e000 Unfrozen + 23 id: 16.c1 Teb 7ff5f000 Unfrozen + 24 id: 16.bd Teb 7ff5d000 Unfrozen +``` + +Thread 21 owns the first critical section. Make that the active thread and get a stack trace: + +``` +0:024> ~21s +ntdll!_ZwWaitForSingleObject+0xb: +77f71bfb c20c00 ret 0xc + +0:021> kb + +ChildEBP RetAddr Args to Child +0556fc44 77f79c20 00000110 00000000 77fa4700 ntdll!_ZwWaitForSingleObject+0xb +0556fcb0 77f71048 5ffa91b4 5feb4f7e 5ffa91b4 ntdll!_RtlpWaitForCriticalSection+0x31 +0556fcb8 5feb4f7e 5ffa91b4 0556fd70 77f71000 ntdll!_RtlEnterCriticalSection+0x48 +0556fcf4 5fef0b76 01302005 00000000 fffffff4 winsrv!__ScrollDC+0x14 +0556fd70 5fedf83f 002bd880 0556fdc0 00000025 winsrv!_StreamScrollRegion+0x21b +0556fd8c 5fedfa5b 002bd880 00190000 00000000 winsrv!_AdjustCursorPosition+0x8e + +0556fdc0 5fedf678 0556ff18 002bdf70 002a4d58 winsrv!_DoWriteConsole+0x104 +0556fefc 5fe6311b 0556ff18 0556ffd0 00000005 winsrv!_SrvWriteConsole+0x96 +0556fff4 00000000 00000000 00000024 00000024 csrsrv!_CsrApiRequestThread+0x4ff +``` + +Thread 6 owns the second critical section. Examine its stack as well: + +``` +0:021> ~6s +winsrv!_PtiFromThreadId+0xd: +5fe8429a 394858 cmp [eax+0x58],ecx ds:0023:7f504da8=000000f8 + +0:006> kb + +ChildEBP RetAddr Args to Child +01ecfeb4 5fecd0d7 00000086 00000000 7f5738e0 winsrv!_PtiFromThreadId+0xd +01ecfed0 5feccf62 00000086 01ecfff4 00000113 winsrv!__GetThreadDesktop+0x12 +01ecfefc 5fe6311b 01ecff18 01ecffd0 00000005 winsrv!___GetThreadDesktop+0x8b +01ecfff4 00000000 00000000 00000024 00000024 csrsrv!_CsrApiRequestThread+0x4ff +``` + +Thread 21 has **RtlpWaitForCriticalSection** near the top of its stack. Thread 6 does not. So thread 21 is the culprit. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Critical%20Section%20Time%20Outs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl--.md b/windows-driver-docs-pr/debugger/ctrl--.md new file mode 100644 index 0000000000..0c59c23590 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl--.md @@ -0,0 +1,75 @@ +--- +title: CTRL+\ (Debug Current Debugger) +description: The CTRL+\ key combination launches a new instance of CDB; this new debugger takes the current debugger as its target. +ms.assetid: c0c63af5-712c-47b6-8811-81e441ddb3df +keywords: ["CTRL+\ (Debug Current Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+\ (Debug Current Debugger) +api_type: +- NA +--- + +# CTRL+\\ (Debug Current Debugger) + + +The **CTRL+\\** key launches a new instance of CDB; this new debugger takes the current debugger as its target. + +``` +CTRL+\ ENTER +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +
Debuggers

CDB, NTSD, KD

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +This is equivalent to launching a new CDB through the [**remote.exe**](the-remote-exe-utility.md) utility, and using it to debug the debugger that you are already running. + +[**CTRL+\\**](ctrl-alt--.md) is similar to the [**.dbgdbg (Debug Current Debugger)**](-dbgdbg--debug-current-debugger-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+\%20%28Debug%20Current%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-a--toggle-baud-rate-.md b/windows-driver-docs-pr/debugger/ctrl-a--toggle-baud-rate-.md new file mode 100644 index 0000000000..93e4151fb8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-a--toggle-baud-rate-.md @@ -0,0 +1,87 @@ +--- +title: CTRL+A (Toggle Baud Rate) +description: The CTRL+A key toggles the baud rate used in the kernel debugging connection. +ms.assetid: 77a95ca1-073c-480a-abda-f484adbc1d23 +keywords: ["CTRL+A (Toggle Baud Rate) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+A (Toggle Baud Rate) +api_type: +- NA +--- + +# CTRL+A (Toggle Baud Rate) + + +The CTRL+A key toggles the baud rate used in the kernel debugging connection. + +KD Syntax + +``` +CTRL+A ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+A +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

KD and WinDbg only

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +This will cycle through all available baud rates for the kernel debugging connection. + +Supported baud rates are 19200, 38400, 57600, and 115200. Each time this control key is used, the next baud rate will be selected. If the baud rate is already at 115200, it will be reduced to 19200. + +In WinDbg, this can also be accomplished by selecting [Debug | Kernel Connection | Cycle Baud Rate](debug---kernel-connection---cycle-baud-rate.md). + +You cannot actually use this control key to change the baud rate at which you are debugging. The baud rate of the host computer and the target computer must match, and the baud rate of the target computer cannot be changed without rebooting. Therefore, you only need to toggle through the baud rates if the two computers are attempting to communicate at different rates. In this case, you must change the host computer's baud rate to match that of the target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+A%20%28Toggle%20Baud%20Rate%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-alt--.md b/windows-driver-docs-pr/debugger/ctrl-alt--.md new file mode 100644 index 0000000000..cc4ee82a96 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-alt--.md @@ -0,0 +1,75 @@ +--- +title: CTRL+ALT+\ (Debug Current Debugger) +description: The CTRL+ALT+\ key combination launches a new instance of CDB; this new debugger takes the current debugger as its target. +ms.assetid: 0a36baa4-fe40-4498-9cf8-ae81497f1dda +keywords: ["CTRL+ALT+\ (Debug Current Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+ALT+\ (Debug Current Debugger) +api_type: +- NA +--- + +# CTRL+ALT+\\ (Debug Current Debugger) + + +The **CTRL+ALT+\\** key launches a new instance of CDB; this new debugger takes the current debugger as its target. + +``` +CTRL+ALT+\ +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +
Debuggers

WinDbg

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +This is equivalent to launching a new CDB through the [**remote.exe**](the-remote-exe-utility.md) utility, and using it to debug the debugger that you are already running. + +**CTRL+ALT+\\** is similar to the [**.dbgdbg (Debug Current Debugger)**](-dbgdbg--debug-current-debugger-.md) command, however **CTRL+ALT+\\** has the advantage that it can be used when no debugger command line is available. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+ALT+\%20%28Debug%20Current%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-b--quit-local-debugger-.md b/windows-driver-docs-pr/debugger/ctrl-b--quit-local-debugger-.md new file mode 100644 index 0000000000..3978198a04 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-b--quit-local-debugger-.md @@ -0,0 +1,77 @@ +--- +title: CTRL+B (Quit Local Debugger) +description: The CTRL+B key causes the debugger to terminate abruptly. This does not end a remote debugging session. +ms.assetid: f70f4c40-244f-4abf-982f-d738800ac621 +keywords: ["CTRL+B (Quit Local Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+B (Quit Local Debugger) +api_type: +- NA +--- + +# CTRL+B (Quit Local Debugger) + + +The CTRL+B key causes the debugger to terminate abruptly. This does not end a remote debugging session. + +``` +CTRL+B ENTER +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

CDB and KD only

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +In CDB, the [**q (Quit)**](q--qq--quit-.md) command should be used to exit. CTRL+B should only be used if the debugger is not responding. + +In KD, the **q** command will end the debugging session and leave the target computer locked. If you need to preserve the debugging session (so a new debugger can connect to it), or if you need to leave the target computer running, you should use CTRL+B. + +In WinDbg, the equivalent command is [File | Exit](file---exit.md) or ALT+F4. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+B%20%28Quit%20Local%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-c--break-.md b/windows-driver-docs-pr/debugger/ctrl-c--break-.md new file mode 100644 index 0000000000..22aec2b2fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-c--break-.md @@ -0,0 +1,129 @@ +--- +title: CTRL+C (Break) +description: The CTRL+C key breaks into the debugger, stopping the target application or target computer, and cancels debugger commands. +ms.assetid: ee9df6d7-4a40-4006-90df-478e06899e3a +keywords: ["CTRL+C (Break) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+C (Break) +api_type: +- NA +--- + +# CTRL+C (Break) + + +The CTRL+C key breaks into the debugger, stopping the target application or target computer, and cancels debugger commands. + +CDB Syntax + +``` +CTRL+C +``` + +KD Syntax + +``` +CTRL+C +``` + +Target Computer Syntax + +``` +SYSRQ +ALT+SYSRQ +F12 +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

CDB and KD only

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For other methods of issuing this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +**When Using CDB:** + +In user mode, the CTRL+C key causes the target application to break into the debugger. The target application freezes, the debugger becomes active, and debugger commands can be entered. + +If the debugger is already active, CTRL+C does not affect the target application. It can be, however, used to terminate a debugger command. For instance, if you have requested a long display and no longer want to see it, CTRL+C will end the display and return you to the debugger command prompt. + +When performing remote debugging with CDB, CTRL+C can be pressed on the host computer's keyboard. If you want to issue a break from the target computer's keyboard, use CTRL+C on an x86 machine. + +The F12 key can be used to get a command prompt when the application being debugged is busy. Set the focus on one of the target application's windows and press the F12 key on the target computer. + +**When Using KD:** + +In kernel mode, the CTRL+C key causes the target computer to break into the debugger. This locks the target computer and wakes up the debugger. + +When debugging a system that is still running, CTRL+C must be pressed on the host keyboard to get the initial command prompt. + +If the debugger is already active, CTRL+C does not affect the target computer. It can be used, however, to terminate a debugger command. For instance, if you have requested a long display and no longer want to see it, CTRL+C will end the display and return you to the debugger command prompt. + +CTRL+C can also be used to get a command prompt when a debugger command is generating a long display or when the target computer is busy. When debugging an x86 machine, it can be pressed on either the host or target keyboard. + +SYSRQ (or ALT+SYSRQ on an enhanced keyboard) is similar. It works from the host or target keyboard on any processor. However, it only works if the prompt has been acquired by pressing CTRL+C at least once before. + +The SYSRQ key can be disabled by editing the registry. In the registry key + +``` +HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters +``` + +create a value named **BreakOnSysRq**, and set it equal to DWORD 0x0. Then reboot. After this is done, pressing the SYSRQ key on the target computer's keyboard will not break into the kernel debugger. + +**When Debugging KD with CDB:** + +If you are debugging KD with CDB, then CTRL+C will be intercepted by the host debugger (CDB). To break into the target debugger (KD), you should use [**CTRL+F**](ctrl-f--break-to-kd-.md) instead. + +**Note**   Note that in WinDbg, CTRL+C is a [shortcut key](keyboard-shortcuts.md) that is used to copy text from a window. To issue a break command in WinDbg, use [CTRL+BREAK](debug---break.md) or select Debug | Break from the menu. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+C%20%28Break%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-d--toggle-debug-info-.md b/windows-driver-docs-pr/debugger/ctrl-d--toggle-debug-info-.md new file mode 100644 index 0000000000..69f03eb099 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-d--toggle-debug-info-.md @@ -0,0 +1,87 @@ +--- +title: CTRL+D (Toggle Debug Info) +description: The CTRL+D key toggles debugger internal information flow on and off. This is used to restart communication in cases where the debugger is not communicating properly. +ms.assetid: fcc5d597-6a3f-4d6c-82f9-3624efb4f434 +keywords: ["CTRL+D (Toggle Debug Info) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+D (Toggle Debug Info) +api_type: +- NA +--- + +# CTRL+D (Toggle Debug Info) + + +The CTRL+D key toggles debugger internal information flow on and off. This is used to restart communication between the target computer and the host computer in cases where the debugger is not communicating properly. + +KD Syntax + +``` +CTRL+D ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+D +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

KD and WinDbg only

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +Remarks +------- + +When this is toggled on, the debugger outputs information about the communication between the host computer and the target computer. + +This key can be used to test whether the debugger has crashed. If you suspect that either the debugger or the target is frozen, use this key. If you see packets being sent, the target is still working. If you see time-out messages, then the target is not responding. If there are no messages at all, the debugger has crashed. + +If the target is not responding, use CTRL+R ENTER CTRL+C. If time-out messages continue to appear, the target has crashed (or the debugger was misconfigured). + +This is also useful for debugging the KD debugger itself. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+D%20%28Toggle%20Debug%20Info%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-f--break-to-kd-.md b/windows-driver-docs-pr/debugger/ctrl-f--break-to-kd-.md new file mode 100644 index 0000000000..01161ad7d8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-f--break-to-kd-.md @@ -0,0 +1,81 @@ +--- +title: CTRL+F (Break to KD) +description: The CTRL+F key cancels commands or breaks into the debugger. +ms.assetid: 45bb7eaf-cb79-4fb4-a01d-373bfb1957c3 +keywords: ["CTRL+F (Break to KD) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+F (Break to KD) +api_type: +- NA +--- + +# CTRL+F (Break to KD) + + +The CTRL+F key cancels commands or breaks into the debugger. (This control key is particularly useful when you are using CDB to debug KD itself.) + +``` +CTRL+F ENTER +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

CDB, KD

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +Under typical conditions, CTRL+F is identical to the standard break commands ([**CTRL+C**](ctrl-c--break-.md) in KD and CDB, and [Debug | Break](debug---break.md) or CTRL+BREAK in WinDbg.) + +However, if you are debugging KD with CDB, these two keys will work differently. CTRL+C will be intercepted by the host debugger (CDB), while CTRL+F will be intercepted by the target debugger (KD). + +## See also + + +[**.breakin (Break to the Kernel Debugger)**](-breakin--break-to-the-kernel-debugger-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+F%20%28Break%20to%20KD%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-k--change-post-reboot-break-state-.md b/windows-driver-docs-pr/debugger/ctrl-k--change-post-reboot-break-state-.md new file mode 100644 index 0000000000..65c5f8effe --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-k--change-post-reboot-break-state-.md @@ -0,0 +1,98 @@ +--- +title: CTRL+K (Change Post-Reboot Break State) +description: The CTRL+K key changes the conditions on which the debugger will automatically break into the target computer. +ms.assetid: 74f57775-63ad-4a96-9ba5-bfedd4c8c826 +keywords: ["CTRL+K (Change Post-Reboot Break State) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+K (Change Post-Reboot Break State) +api_type: +- NA +--- + +# CTRL+K (Change Post-Reboot Break State) + + +The CTRL+K key changes the conditions on which the debugger will automatically break into the target computer. + +KD Syntax + +``` +CTRL+K ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+K +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

KD and WinDbg only

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For an overview of related commands and an explanation of how the reboot process affects the debugger, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +Remarks +------- + +This control key causes the kernel debugger to cycle through the following three states: + +**No break** +In this state, the debugger will not break into the target computer unless you press [**CTRL+C**](ctrl-c--break-.md). + +**Break on reboot** +In this state, the debugger will break into a rebooted target computer after the kernel initializes. This is equivalent to starting KD or WinDbg with the **-b**[command-line option](command-line-options.md). + +**Break on first module load** +In this state, the debugger will break into a rebooted target computer after the first kernel module is loaded. (This will cause the break to occur earlier than in the **Break on reboot** option.) This is equivalent to starting KD or WinDbg with the **-d**[command-line option](command-line-options.md). + +When CTRL+K is used, the new break state is displayed. + +In WinDbg, this can also be accomplished by selecting [Debug | Kernel Connection | Cycle Initial Break](debug---kernel-connection---cycle-initial-break.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+K%20%28Change%20Post-Reboot%20Break%20State%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-p--debug-current-debugger-.md b/windows-driver-docs-pr/debugger/ctrl-p--debug-current-debugger-.md new file mode 100644 index 0000000000..0273bbc936 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-p--debug-current-debugger-.md @@ -0,0 +1,32 @@ +--- +title: CTRL+P (Debug Current Debugger) +description: The CTRL+P command is obsolete and has been replaced by the CTRL+\ and CTRL+ALT+\ key combinations. +ms.assetid: c6e72631-ffd7-413b-966f-63e6be1643d9 +keywords: ["CTRL+P (Debug Current Debugger) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+P (Debug Current Debugger) +api_type: +- NA +--- + +# CTRL+P (Debug Current Debugger) + + +The **CTRL+P** command is obsolete and has been replaced by [**CTRL+\\**](ctrl--.md) and [**CTRL+ALT+\\**](ctrl-alt--.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+P%20%28Debug%20Current%20Debugger%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-r--re-synchronize-.md b/windows-driver-docs-pr/debugger/ctrl-r--re-synchronize-.md new file mode 100644 index 0000000000..c4446b57c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-r--re-synchronize-.md @@ -0,0 +1,87 @@ +--- +title: CTRL+R (Re-synchronize) +description: The CTRL+R key synchronizes with the target computer. +ms.assetid: 95ffa380-af90-4d56-b973-038e7ccc6760 +keywords: ["CTRL+R (Re-synchronize) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+R (Re-synchronize) +api_type: +- NA +--- + +# CTRL+R (Re-synchronize) + + +The CTRL+R key synchronizes with the target computer. + +KD Syntax + +``` +CTRL+R ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+R +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

KD and WinDbg only

Modes

kernel mode only

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of re-establishing contact with the target, see [Synchronizing with the Target Computer](synchronizing-with-the-target-computer.md). + +Remarks +------- + +This attempts to synchronize the host computer with the target computer. Use this key if the target is not responding. + +If you are using a 1394 kernel connection, resynchronization may not always be successful. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+R%20%28Re-synchronize%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-v--toggle-verbose-mode-.md b/windows-driver-docs-pr/debugger/ctrl-v--toggle-verbose-mode-.md new file mode 100644 index 0000000000..e279851062 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-v--toggle-verbose-mode-.md @@ -0,0 +1,83 @@ +--- +title: CTRL+V (Toggle Verbose Mode) +description: The CTRL+V key toggles verbose mode on and off. +ms.assetid: 1aca1452-86dd-4573-8ad0-e46aa474a324 +keywords: ["CTRL+V (Toggle Verbose Mode) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+V (Toggle Verbose Mode) +api_type: +- NA +--- + +# CTRL+V (Toggle Verbose Mode) + + +The CTRL+V key toggles verbose mode on and off. + +CDB / KD Syntax + +``` +CTRL+V ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+V +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

CDB, KD, WinDbg

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +When verbose mode is turned on, some display commands (such as register dumping) produce more detailed output. Every MODULE LOAD operation that is sent to the debugger will be displayed. And every time a driver or DLL is loaded by the operating system, the debugger will be notified. + +In WinDbg, this can also be accomplished by selecting [View | Verbose Output](view---verbose-output.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+V%20%28Toggle%20Verbose%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ctrl-w--show-debugger-version-.md b/windows-driver-docs-pr/debugger/ctrl-w--show-debugger-version-.md new file mode 100644 index 0000000000..5fe6cee4e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ctrl-w--show-debugger-version-.md @@ -0,0 +1,91 @@ +--- +title: CTRL+W (Show Debugger Version) +description: The CTRL+W key displays version information for the debugger and all loaded extension DLLs. +ms.assetid: 9651965e-fbf5-4084-adcd-63de60998b8b +keywords: ["CTRL+W (Show Debugger Version) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- CTRL+W (Show Debugger Version) +api_type: +- NA +--- + +# CTRL+W (Show Debugger Version) + + +The CTRL+W key displays version information for the debugger and all loaded extension DLLs. + +CDB / KD Syntax + +``` +CTRL+W ENTER +``` + +WinDbg Syntax + +``` +CTRL+ALT+W +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + + + + + +

Debuggers

CDB, KD, WinDbg

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +Remarks +------- + +This has the same effect as the [**version (Show Debugger Version)**](version--show-debugger-version-.md) command, except that the latter command displays the Windows operating system version as well. + +In WinDbg, this can also be accomplished by selecting [View | Show Version](view---show-version.md). + +## See also + + +[**version (Show Debugger Version)**](version--show-debugger-version-.md) + +[**vertarget (Show Target Computer Version)**](vertarget--show-target-computer-version-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20CTRL+W%20%28Show%20Debugger%20Version%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/customizing-a-theme.md b/windows-driver-docs-pr/debugger/customizing-a-theme.md new file mode 100644 index 0000000000..002a5a7a25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/customizing-a-theme.md @@ -0,0 +1,67 @@ +--- +title: Customizing a Theme +description: Customizing a Theme +ms.assetid: 3dddbf19-34ec-4cb0-b427-854ae7622fa1 +keywords: ["themes, customizing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Customizing a Theme + + +## + + +Before customizing a theme, it must first be loaded. See [Loading a Theme](loading-a-theme.md) for details. + +After the theme is loaded, start WinDbg with no command-line parameters. This opens the base workspace. There are two common areas of focus for customizing a theme: setting paths and adjusting window position. + +After you have completed any wanted adjustments, exit WinDbg and save your workspace by selecting **Save Workspace** from the **File** menu. If you want to save your new settings to a .reg file, open Regedit and export the registry key under **HKCU\\Software\\Microsoft\\Windbg\\Workspaces** to a .reg file. + +### Setting Paths + +By setting the appropriate paths, you can ensure that WinDbg can locate all of the files that it needs to debug effectively. There are three main paths to set: the symbol path, the source path, and the executable image path. + +Here are examples of how to set the symbol and source path. The executable image path is typically the same as your symbol path. + +To set your symbol path: + +``` +SRV*c:\MySymCache*\\CompanySymbolServer\Symbols;SRV*c:\WinSymCache*https://msdl.microsoft.com/download/symbols +``` + +To set your source path: + +``` +SRV*;d:\MySourceRoot +``` + +### Adjusting Window Position + +Before using your theme, you should adjust the window positioning so that WinDbg handles your source files correctly. This ensures that Source windows knows where to dock. + +Begin by opening a Source window in WinDbg. Tab-dock this window with the placeholder set aside for your Source windows. In order for the proper relationship to be made, the placeholder window must be the uppermost window in the dock before you perform this tab-docking operation. Now close the source window but not the placeholder window. + +Because debugging information windows "remember" their last docking operation, each source window's last docking operation is associated with one of the placeholder windows after you have performed this procedure. Because of this memory attribute, you should not close any of your placeholder windows. Further, if you choose to change the theme's configuration, any window you reposition in a dock should always be tab-docked with a placeholder file. + +The sample themes included with the Debugging Tools for Windows were created using the following actions: + +Place and position the placeholder\*.c files into the dock. + +Tab-dock every window type above the wanted placeholder window. + +For further information about adjusting window position in WinDbg, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Customizing%20a%20Theme%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/customizing-debugger-output-using-dml.md b/windows-driver-docs-pr/debugger/customizing-debugger-output-using-dml.md new file mode 100644 index 0000000000..89c8eb2d6b --- /dev/null +++ b/windows-driver-docs-pr/debugger/customizing-debugger-output-using-dml.md @@ -0,0 +1,640 @@ +--- +title: Customizing Debugger Output Using DML +description: The debugger markup language (DML) provides a mechanism for enhancing output from the debugger and extensions. +ms.assetid: 04984510-B95F-405F-81DF-E9D0673210B4 +--- + +# Customizing Debugger Output Using DML + + +The debugger markup language (DML) provides a mechanism for enhancing output from the debugger and extensions. Similar to HTML, the debugger’s markup support allows output to include display directives and extra non-display information in the form of tags. The debugger user interfaces, such as WinDbg parse out the extra information provided in DML to enhance the display of information and provide new behaviors, such as grid displays and sorting. This topic describes how you can customize your debug output using DML. For general information on enabling and using DML in the debuggers, see [Using Debugger Markup Language](debugger-markup-language-commands.md). + +DML is available in Windows 10 and later. + +## DML Overview + + +On of DML's primary benefits it to provide the ability to link to related information in debugger output. One of the primary DML tags is the <link> tag which lets an output producer indicate that information related to a piece of output can be accessed via the link’s stated action. As with HTML links in a web browser, this allows the user to navigate hyperlinked information. + +A benefit of providing hyperlinked content is that it can be used to enhance the discoverability of debugger and debugger extension functionality. The debugger and its extensions contain a large amount of functionality but it can be difficult to determine the appropriate command to use in different scenarios. Users must simply know what commands are available to use in specific scenarios. Differences between user and kernel debugging add further complexity. This often means that many users are unaware of debug commands which could help them. DML links provides the ability for arbitrary debug commands to be wrapped in alternate presentations, such as descriptive text, clickable menu systems or linked help. Using DML, the command output can be enhanced to guide the user to additional related commands relevant for the task at hand. + +**Debugger DML Support** + +- The command window in WinDbg supports all DML behavior and will show colors, font styles and links. +- The console debuggers – ntsd, cdb and kd – only support the color attributes of DML, and the only when running in a true console with color mode enabled. +- Debuggers with redirected I/O, ntsd –d or remote.exe sessions will not display any colors. + +## DML Content Specification + + +DML is not intended to be a full presentation language such as HTML. DML is deliberately very simple and has only a handful of tags. + +Because not all debugger tools support rich text, DML is designed to allow simple translation between DML and plain text. This allows DML to function in all existing debugger tools. Effects such as colors can easily be supported since removing them does not remove the text carrying the actual information. + +DML is not XML. DML does not attempt to carry semantic nor structured information. As mentioned above, there must be a simple mapping between DML and plain text, for this reason, DML tags are all discardable. + +DML is not extensible; all tags are pre-defined and validated to work across all of the existing debugger tools. + +**Tag Structure** + +Similar to XML, DML tags are given as a starting <tagname \[args\]> and a following </tagname>. + +**Special Characters** + +DML content roughly follows the XML/HTML rules for special characters. The characters &, <, > and “ are special and cannot be used in plain text. The equivalent escaped versions are &, <, > and ". For example this text: + +"Alice & Bob think 3 < 4" + +would be converted to the following DML. + +``` +"Alice & Bob think 3 < 4" +``` + +**C programming language formatting characters** + +A significant departure from XML/HTML rules is that DML text can include C programming language stream-style formatting characters such as \\b, \\t, \\r and \\n. This is to support compatibility with existing debugger text production and consumption. + +## Example DML + + +Suppose the file C:\\Dml\_Experiment.txt contains the following lines. + +``` +My DML Experiment +List modules that begin with usb. +``` + +The following command displays the text and link in the Command Browser window. + +``` +.browse .dml_start c:\Dml_Experiment.txt +``` + +![screen shot of dml file output](images/dmlcommands03.png) + +If you click the **List modules that begin with usb** link, you see output similar to the following image. + +![screen shot of module list](images/dmlcommands04.png) + +## Right-Click Behavior in DML + + +Right-click behavior is available in DML. This sample shows how to define right click behavior using <altlink> to send a breakpoint [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command and send the [**u (Unassemble)**](u--unassemble-.md) with a regular click. + +``` + + +u MyProgram!memcpy + +``` + +## DML Tag Reference + + +### <link> + +*<link \[name=”text”\] \[cmd=”debugger\_command”\]\[alt="Hover text to display"\] \[section=”name”\]>link text</link>* + +The link tag is the basic hyper linking mechanism in DML. It directs user interfaces which support DML presentation to display the link text as a clickable link. When a link with a cmd specification is clicked the debugger command is executed and its output should replace the current output. + +The name and section arguments allow for navigation between named links, similar to HTML’s <a name> and \#name support. When a link that has a section argument is clicked on the UI will scan for a link named with a matching name and will scroll that into view. This allows links to point to different sections of the same page (or a particular section of a new page). DML’s section name is separate to avoid having to define a new syntax which would allow a section name at the end of the command string. + +Conversion to plain text drops the tags. + +**Example** + +``` + Handy Links +Display process information with DML rendering. +Display stack information with DML rendering. +``` + +**Example** + +This example shows the use of the alt attribute to create text that will appear when you hover over the DML link. + +``` +Hover Example +LmD +``` + +### <altlink> + +*<altlink \[name=”text”\] \[cmd=”debugger\_command”\] \[section=”name”\]>alt link text</altlink>* + +The <altlink> tag provides right-click behavior is available in DML. When a link with a cmd specification is clicked the debugger command is executed and its output should replace the current output. The <altlink> tab is normally paired with the <link> tag to support regular and right click behavior. + +Conversion to plain text drops the tags. + +**Example** + +This example shows how to define right click behavior using <altlink> to send a breakpoint [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command and send the [**u (Unassemble)**](u--unassemble-.md) with a regular click. + +``` + + +u MyProgram!memcpy + +``` + +### <exec> + +*<exec cmd=”debugger\_command”>descriptive text</exec>* + +An exec tag is similar to a link tag in that the descriptive text should be presented as a clickable item. However, when the exec tag is used in a command browser window, the given command is executed without replacing the current output, this tag provides a way to have commands executed with a click, from a menu. + +Conversion to plain text drops the tags. + +**Example** + +This example shows how to define two commands with a regular click. + +``` +Exec Sample +Display process information with DML rendering. +Display stack information with DML rendering. +``` + +### <b> + +*<b>bold text</b>* + +This tag requests bold. The <b>, <i> and <u> can be nested to have a mix of the properties. + +Conversion to plain text drops the tags. + +**Example** + +This example shows how to bold text. + +``` +This is bold Text +``` + +### <i> + +*<i>italicized text</i>* + +This tag requests italics. The <b>, <i> and <u> can be nested to have a mix of the properties. + +Conversion to plain text drops the tags. + +**Example** + +This example shows how to italicize text. + +``` +This is italicized Text +``` + +### <u> + +*<i>underlined text</i>* + +This tag requests underlined text. The <b>, <i> and <u> can be nested to have a mix of the properties. + +Conversion to plain text drops the tags. + +**Example** + +This example shows how to underlined text. + +``` +This is underlined Text +``` + +**Example** + +This example shows how to combine tags to bold, underline and italicize text. + +``` +This is bold, underlined and italizized text. +``` + +### <col> + +<col fg="name" bg="name">text</col> + +Request foreground and background colors for the text. The colors are given as names of known colors instead of absolute values as that allows customers to control what kind of color they see. Current color names (defaults only apply to WinDbg). + +**Foreground and Background Element Tags** + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingDescription / Example

wbg - Windows background

+

wfg - Windows foreground

Default window background and foreground colors. Default to system colors for window and window text. +

<col fg="wfg" bg="wbg"> This is standard foreground / background text </col>

clbg - Current line foreground

+

clfg - Current line background

Current line background and foreground colors. Default to system colors for highlight and highlight text. +

<col fg="clfg" bg="clbg"> Test Text - Current Line</col>

empbg - Emphasized background

+

emphfg - Emphasized foreground

Emphasized text. Defaults to light blue. +

<col fg="empfg" bg="empbg"> This is emphasis foreground / background text </col>

subbg - Subdued background

+

subfg- Subdued foreground

Subdued text. Default to system color for inactive caption text and inactive captions. +

<col fg="subfg" bg="subbg"> This is subdued foreground / background text </col>

normbg - Normal background

+

normfg - Normal foreground

Normal +

<col fg="normfg" bg="normbg"> Test Text - Normal (normfg / normbg) </col>

warnbg - Warning background

+

warnfg - Warning foreground

Warning +

<col fg="warnfg" bg="warnbg"> Test Text - Warning (warnfg / warnbg) </col>

errbg - Error background

+

errfg - Error foreground

Error +

<col fg="errfg" bg="errbg"> Test Text - Error (errfg / errbg) </col>

verbbg - Verbose background

+

verbfg - Verbose foreground

Verbose +

<col fg="verbfg" bg="verbbg"> Test Text - Verbose (verbfg / verbbg) </col>

+ +  + +**Source Code Single Element Tags** + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

srcnum - Source numeric constant

Source element colors. +

<col fg="srcnum" bg="wbg"> Test Text - srcnum </col>

srcchar - Source character constant

<col fg="srcchar" bg="wbg"> Test Text - srcchar </col>

srcstr - Source string constant

<col fg="srcstr" bg="wbg"> Test Text - srcstr </col>

srcid -Source identifier

<col fg="srcid " bg="wbg"> Test Text - srcid </col>

srckw- Keyword

<col fg="srckw" bg="wbg"> Test Text - srckw </col>

srcpair - Source brace or matching symbol pair

<col fg="srcpair" bg="empbbg"> Test Text - srcpair </col>

srccmnt - Source comment

<col fg="srccmnt" bg="wbg"> Test Text - srccmnt </col>

srcdrct - Source directive

<col fg="srcdrct" bg="wbg"> Test Text - srcdrct </col>

srcspid - Source special identifier

<col fg="srcspid" bg="wbg"> Test Text - srcspid </col>

srcannot - Source annotation

<col fg="srcannot" bg="wbg"> Test Text - srcannot </col>

changed - Changed data

Used for data that has changed since a previous stop point, such as changed registers in WinDbg. Defaults to red. +

<col fg="changed" bg="wbg"> Test Text - Changed</col>

+ +  + +## DML Example Code + + +This example code illustrates the following. + +- Calling debug commands +- Implementing right click commands +- Implementing hover over text +- Using color and rich text + +```XML + +******************************************************* +*** Example debug commands for crash dump analysis **** +******************************************************* + + +**** Hover over commands for additional information **** + **** Right-click for command help **** + + +*** Common First Steps for Crash Dump Analysis *** +.symfix - Set standard symbol path +.sympath+ C:\Symbols - Add any additional symbol directories, for example C:\Symbols +.reload /f - Reloads symbols to make sure they are in good shape +!analyze -v - Run !analyze with the verbose option +vertarget - Check the target version +version - Display the versions in use +.chain /D - Use the .chain /D command to list debugger extensions +kD - Display the stack backtrace using DML rendering +LmD - List modules command and display the output in DML format +.help /D - Display help for commands in WinDbg +.hh - Start help + +*** Registers and Context *** +r - Display registers +dt nt!_CONTEXT - Display information about nt_CONTEXT +dt nt!_PEB - Display information about the nt!_PEB +ub - Unassemble Backwards + + +**** Note: Not all of the following commands will work with all crash dump data **** + +*** Device Drivers *** +!devnode 0 1 - Display devnodes +.load wdfkd.dll;!wdfkd.help - Load wdfkd extensions and display help +!wdfkd.wdfldr - Display WDF framework driver loader information +!wdfkd.umtriage - Display WDF umtriage driver information + +*** IRPs and IRQL *** +!processirps - Display process IRPs +!irql - Run !irql + +*** Variables and Symbols *** +dv - Display the names and values of all local variables in the current scope + +*** Threads, Processes, and Stacks *** +!threads - Display threads +!ready 0xF - Display threads in the ready state +!process 0 F - Run !process 0 F +!stacks 2 - Display stack information using !stacks 2 +tlist - Display a process list using tlist +!process - Display process information +!dml_proc - Display process information with DML rendering + +``` + +This example code illustrates the use of color and formatting tags. + +```XML +*** Text Tag Examples **** + +This is bold text +This is underlined text +This is italizized text +This is bold, underlined and italizized text + +Color Tag Examples + This is standard foreground / background text + This is emphasis foreground / background text + This is subdued foreground / background text + Test Text - Current Line + +Other Tags Sets + Test Text - Normal (normfg / normbg) + Test Text - Warning (warnfg / warnbg) + Test Text - Error (errfg / errbg) + Test Text - Verbose (verbfg / verbbg) + +Changed Text Tag Examples + Test Text - Changed + +Source Tags - using wbg background + Test Text - srcnum + Test Text - srcchar + Test Text - srcstr + Test Text - srcid + Test Text - srckw + Test Text - srcpair + Test Text - srccmnt + Test Text - srcdrct + Test Text - srcspid + Test Text - srcannot + +Source Tags - using empbg background + Test Text - srcnum + Test Text - srcchar + Test Text - srcstr + Test Text - srcid + Test Text - srckw + Test Text - srcpair + Test Text - srccmnt + Test Text - srcdrct + Test Text - srcspid + Test Text - srcannot + +Source Tags - using subbg background + Test Text - srcnum + Test Text - srcchar + Test Text - srcstr + Test Text - srcid + Test Text - srckw + Test Text - srcpair + Test Text - srccmnt + Test Text - srcdrct + Test Text - srcspid + Test Text - srcannot +``` + +## DML Additions to the dbgeng Interface + + +The [Debugger Engine and Extension APIs](debugger-engine-and-extension-apis.md) provide an interface to use the debugger engine to create custom applications. You can also write custom extensions that will run in WinDbg, KD, CDB, and NTSD. For more information see [Writing DbgEng Extensions](writing-dbgeng-extensions.md). This section describes the available DML enhancements to the debugger engine interfaces. + +The dbgeng already has a set of text handling input methods and output interfaces, the use of DML only requires specification of the type of content carried in input and output text. + +**Providing DML Content to dbgeng** + +The output control flag DEBUG\_OUTCTL\_DML indicates that the text generated by a dbgeng method should be handled as DML content. If this flag is not given the text is treated as plain text context. DEBUG\_OUTCTL\_DML can be used with the following methods. + +- [**IDebugControl4::ControlledOutput**](https://msdn.microsoft.com/library/windows/hardware/ff539248) +- [**IDebugControl4::ControlledOutputVaList**](https://msdn.microsoft.com/library/windows/hardware/ff539252) +- [**IDebugControl4::ControlledOutputWide**](https://msdn.microsoft.com/library/windows/hardware/ff539266) +- [**IDebugControl4::ControlledOutputVaListWide**](https://msdn.microsoft.com/library/windows/hardware/ff539259) + +Text given must follow the DML rules for valid characters. + +All output routines have been enhanced to allow a new format specifier %\[h|w\]Y{t}. This format specifier has a string pointer as an argument and indicates that the given text is plain text and should be converted to DML format during output processing. This gives callers a simple way of including plain text in DML content without having to pre-convert to DML format themselves. The h and w qualifiers indicate ANSI or Unicode text, as with %s. + +The following table summarizes the use of the %Y format specifier. + +| | | +|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| %Y{t} | Quoted string. Will convert text to DML if the output format (first arg) is DML. | +| %Y{T} | Quoted string. Will always convert text to DML regardless of the output format. | +| %Y{s} | Unquoted string. Will convert text to DML if the output format (first arg) is DML. | +| %Y{S} | Unquoted string. Will always convert text to DML regardless of the output format. | +| %Y{as} | ULONG64. Adds either an empty string or 9 characters of spacing for padding the high 32-bit portion of debugger formatted pointer fields. The extra space outputs 9 spaces which includes the upper 8 zeros plus the \` character. | +| %Y{ps} | ULONG64. Extra space for padding debugger formatted pointer fields (includes the upper 8 zeros plus the \` character). | +| %Y{l} | ULONG64. Address as source line information. | + +  + +This code snippet illustrates the use of the %Y format specifier. + +``` +HRESULT CALLBACK testout(_In_ PDEBUG_CLIENT pClient, _In_ PCWSTR /*pwszArgs*/) +{ + HRESULT hr = S_OK; + + ComPtr spControl; + IfFailedReturn(pClient->QueryInterface(IID_PPV_ARGS(&spControl))); + + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{t}: %Y{t}\n", L"Hello "); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{T}: %Y{T}\n", L"Hello "); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{s}: %Y{s}\n", L"Hello "); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{S}: %Y{S}\n", L"Hello "); + + spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{t}: %Y{t}\n", L"Hello "); + spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{T}: %Y{T}\n", L"Hello "); + spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{s}: %Y{s}\n", L"Hello "); + spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{S}: %Y{S}\n", L"Hello "); + + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{a}: %Y{a}\n", (ULONG64)0x00007ffa7da163c0); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 64bit : '%Y{as}'\n", (ULONG64)0x00007ffa7da163c0); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 32value : '%Y{as}'\n", (ULONG64)0x1); + + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 64bit : '%Y{ps}'\n", (ULONG64)0x00007ffa7da163c0); + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 32value : '%Y{ps}'\n", (ULONG64)0x1); + + spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{l}: %Y{l}\n", (ULONG64)0x00007ffa7da163c0); + + return hr; + +} +``` + +This sample code would generate the following output. + +``` +0:004> !testout +DML/NORMAL Y{t}: "Hello " +DML/NORMAL Y{T}: "Hello " +DML/NORMAL Y{s}: Hello +DML/NORMAL Y{S}: Hello +TEXT/NORMAL Y{t}: "Hello " +TEXT/NORMAL Y{T}: "Hello <World>" +TEXT/NORMAL Y{s}: Hello +TEXT/NORMAL Y{S}: Hello <World> +DML/NORMAL Y{a}: 00007ffa`7da163c0 +DML/NORMAL Y{as} 64bit : ' ' +DML/NORMAL Y{as} 32value : ' ' +DML/NORMAL Y{ps} 64bit : ' ' +DML/NORMAL Y{ps} 32value : ' ' +DML/NORMAL Y{l}: [d:\th\minkernel\kernelbase\debug.c @ 443] +``` + +An additional control flag, DEBUG\_OUTCTL\_AMBIENT\_DML, allows specification of DML context text without modifying any out output control attributes. DEBUG\_OUTCTL\_AMBIENT\_TEXT has been added also as a more-descriptive alias for the previously-existing DEBUG\_OUTCTL\_AMBIENT. The output control flags are defined in dbgeng.h. + +``` +#define DEBUG_OUTCTL_DML 0x00000020 + +// Special values which mean leave the output settings +// unchanged. +#define DEBUG_OUTCTL_AMBIENT_DML 0xfffffffe +#define DEBUG_OUTCTL_AMBIENT_TEXT 0xffffffff + +// Old ambient flag which maps to text. +#define DEBUG_OUTCTL_AMBIENT DEBUG_OUTCTL_AMBIENT_TEXT +``` + +**Providing DML Content From a Debuggee** + +The dbgeng has been enhanced to scan debuggee output for a special marker – – that indicates the remaining text in a piece of debuggee output should be treated as DML. The mode change only applies to a single piece of debuggee output, such as a single OutputDebugString string, and is not a global mode switch. + +This example shows a mix of plain and DML output. + +``` +OutputDebugString(“This is plain text\nThis is DML text\n”); +``` + +The output produced, will have a line of plain text followed by a line of DML where the acronym DML is displayed in a different color. + +**IDebugOutputCallbacks2** + +IDebugOutputCallbacks2 allows dbgeng interface clients to receive full DML content for presentation. IDebugOutputCallbacks2 is an extension of IDebugOutputCallbacks (not IDebugOutputCallbacksWide) so that it can be passed in to the existing SetOutputCallbacks method. The engine will do a QueryInterface for IDebugOutputCallbacks2 to see which interface the incoming output callback object supports. If the object supports IDebugOutputCallbacks2 all output will be sent through the extended IDebugOutputCallbacks2 methods; the basic IDebugOutputCallbacks::Output method will not be used. + +The new methods are: + +- IDebugOutputCallbacks2::GetInterestMask – Allows the callback object to describe which kinds of output notifications it wants to receive. The basic choice is between plain text content (DEBUG\_OUTCBI\_TEXT) and DML content (DEBUG\_OUTCBI\_DML). In addition, the callback object can also request notification of explicit flushes (DEBUG\_OUTCBI\_EXPLICIT\_FLUSH). +- IDebugOutputCallbacks2::Output2 – All IDebugOutputCallbacks2 notifications come through Output2. The Which parameter indicates what kind of notification is coming in while the Flags, Arg and Text parameters carry the notification payload. Notifications include: + + - DEBUG\_OUTCB\_TEXT – Plain text output. Flags are from DEBUG\_OUTCBF\_\*, Arg is the output mask and Text is the plain text. This will only be received if DEBUG\_OUTCBI\_TEXT was given in the interest mask. + - DEBUG\_OUTCB\_DML – DML content output. Flags are from DEBUG\_OUTCBF\_\*, Arg is the output mask and Text is the DML content. This will only be received if DEBUG\_OUTCBI\_DML was given in the interest mask. + - DEBUG\_OUTCB\_EXPLICIT\_FLUSH – A caller has called FlushCallbacks with no buffered text. Normally when buffered text is flushed the DEBUG\_OUTCBF\_COMBINED\_EXPLICIT\_FLUSH flag will be set, folding the two notifications into one. If no text is buffered a flush-only notification is sent. + + The flags are defined in dbgeng.h as shown here. + + ``` + // IDebugOutputCallbacks2 interest mask flags. + // + + // Indicates that the callback wants notifications + // of all explicit flushes. + #define DEBUG_OUTCBI_EXPLICIT_FLUSH 0x00000001 + // Indicates that the callback wants + // content in text form. + #define DEBUG_OUTCBI_TEXT 0x00000002 + // Indicates that the callback wants + // content in markup form. + #define DEBUG_OUTCBI_DML 0x00000004 + + #define DEBUG_OUTCBI_ANY_FORMAT 0x00000006 + ``` + +Note that an output object can register for both text and DML content if it can handle them both. During output processing of the callback the engine will pick the format that reduces conversions, thus supporting both may reduce conversions in the engine. It is not necessary, though, and supporting only one format is the expected mode of operation. + +**Automatic Conversions** + +The dbgeng will automatically convert between plain text and DML as necessary. For example, if a caller sends DML content to the engine the engine will convert it to plain text for all output clients which only accept plain text. Alternately, the engine will convert plain text to DML for all output callbacks which only accept DML. + +## Related topics + + +[Using Debugger Markup Language](debugger-markup-language-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Customizing%20Debugger%20Output%20Using%20DML%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/cutting-and-pasting-text.md b/windows-driver-docs-pr/debugger/cutting-and-pasting-text.md new file mode 100644 index 0000000000..27c1f797e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/cutting-and-pasting-text.md @@ -0,0 +1,93 @@ +--- +title: Cutting and Pasting Text +description: Cutting and Pasting Text +ms.assetid: efc62bee-ba35-4bff-b88b-3b287ededc38 +keywords: ["cutting text", "pasting text", "copying text", "debugging information windows, cutting and pasting text", "text", "text, editing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Cutting and Pasting Text + + +## + + +WinDbg uses many common methods of manipulating text and several methods that are less familiar. + +### Selecting Text + +To select text in a [Source window](source-window.md), in the [Disassembly window](disassembly-window.md), in either pane of the [Debugger Command window](debugger-command-window.md), or in a dialog box, point to one end of the text, press and hold the left mouse button, and drag the pointer to the other end of the text. + +To select all of the text in a window, you can also click [Select All](edit---select-all.md) on the **Edit** menu or press CTRL+A. + +In the [Calls window](calls-window.md), Watch window, [Locals window](locals-window.md), [Registers window](registers-window.md), and [Memory window](memory-window.md), you cannot select an arbitrary span of text, but you can select a whole line or cell. Click in the desired line or cell to select its text. + +While you are entering text, press the DELETE and BACKSPACE keys to delete the text to the right or left of the cursor, respectively. If you select text, you can press these keys to delete the selection. If you select text and then type any characters, the new characters replace what you selected. + +### Copying Text + +To copy text, select that text and then do one of the following: + +- Press the right mouse button. (This method works only in some locations. For more information about how to use the right mouse button, see The Right Mouse Button.) + +- Press CTRL+C. + +- Press CTRL+INSERT. + +- (Docked and tabbed windows only) Click **Copy** on the **Edit** menu. + +- Click the **Copy (Ctrl+C)** button (![screen shot of the copy button](images/tbcopy.png)) on the toolbar. + +### Cutting Text + +To cut text and move it to the clipboard, select the text and then do one of the following: + +- Press CTRL+X. + +- Press SHIFT+DELETE. + +- (Docked and tabbed windows only) Click **Cut** on the **Edit** menu. + +- Click the **Cut (Ctrl+X)** button (![screen shot of the cut button](images/tbcut.png)) on the toolbar. + +You can cut text from the bottom pane of the Debugger Command window, from the left column of the Watch window, and from any dialog box (that is, from any location that supports text entry). + +### Pasting Text + +To paste text from the clipboard, put the cursor where you want to insert the text (or select the text that you want to replace) and then do one of the following: + +- Press the right mouse button. (This method works only in some locations, and you cannot use this method to replace text. For more inormation about how to use this method, see The Right Mouse Button.) + +- Press CTRL+V. + +- Press SHIFT+INSERT. + +- (Docked and tabbed windows only) Click **Paste** on the **Edit** menu. + +- Click the **Paste (Ctrl+V)** button (![screen shot of the paste button](images/tbpaste.png)) on the tooblar. + +You can paste text into the bottom pane of the Debugger Command window, into the left column of the Watch window, and into any dialog box (that is, into any location that supports text entry). + +### Right Mouse Button + +The right mouse button has several effects that can make copying and pasting much quicker: + +- If you select text in either pane of the Debugger Command window, in the Scratch Pad, in the Disassembly window, or in any Source window, and then you press the right mouse button, the text is copied to the clipboard. However, if **QuickEdit Mode** has been deselected in [View | Options](view---options.md), right-clicking in these locations will pop up the menu most relevant to the current location. + +- If you put the cursor (without selecting any text) in either pane of the Debugger Command window, in the Scratch Pad, or in the text entry space of the Watch window, and then you press the right mouse button, the contents of the clipboard are pasted into the window. However, if **QuickEdit Mode** has been deselected in [View | Options](view---options.md), right-clicking in these locations will pop up the menu most relevant to the current location. + +- If you put the cursor in any box and then press the right mouse button, a menu with **Undo**, **Cut**, **Copy**, **Paste**, and **Select All** options appears. You can choose any of these options. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Cutting%20and%20Pasting%20Text%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md b/windows-driver-docs-pr/debugger/d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md new file mode 100644 index 0000000000..cda9766b89 --- /dev/null +++ b/windows-driver-docs-pr/debugger/d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md @@ -0,0 +1,193 @@ +--- +title: d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory) +description: The d* commands display the contents of memory in the given range. +ms.assetid: deb58b77-6648-466d-be00-e2e0a92895b5 +keywords: ["d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory) +api_type: +- NA +--- + +# d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory) + + +The **d\*** commands display the contents of memory in the given range. + +``` +d{a|b|c|d|D|f|p|q|u|w|W} [Options] [Range] +dy{b|d} [Options] [Range] +d [Options] [Range] +``` + +## Parameters + + + *Options* +Specifies one or more display options. Any of the following options can be included, except that no more than one **/p**\* option can be indicated: + +**/c***Width* +Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type. + +**/p** +(Kernel-mode only) Uses physical memory addresses for the display. The range specified by *Range* will be taken from physical memory rather than virtual memory. + +**/p\[c\]** +(Kernel-mode only) Same as **/p**, except that cached memory will be read. The brackets around **c** must be included. + +**/p\[uc\]** +(Kernel-mode only) Same as **/p**, except that uncached memory will be read. The brackets around **uc** must be included. + +**/p\[wc\]** +(Kernel-mode only) Same as **/p**, except that write-combined memory will be read. The brackets around **wc** must be included. + + *Range* +Specifies the memory area to display. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If you omit *Range*, the command will display memory starting at the ending location of the last display command. If *Range* is omitted and no previous display command has been used, the display begins at the current instruction pointer. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +Each line displayed will include the address of the first byte in the line followed by the contents of memory at that and following locations. + +If you omit *Range*, the command will display memory starting at the ending location of the last display command. This allows you to continuously scan through memory. + +This command exists in the following forms. The second characters of the **dd**, **dD**, **dw**, and **dW** commands are case-sensitive, as are the third characters of the **dyb** and **dyd** commands. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDisplay

d

This displays data in the same format as the most recent d* command. If no previous d* command has been issued, d has the same effect as db.

+

Notice that d repeats the most recent command that began with d. This includes dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu, dds, dps, dqs, ds, dS, dg, dl, dt, and dv, as well as the display commands on this page. If the parameters given after d are not appropriate, errors may result.

da

ASCII characters.

+

Each line displays up to 48 characters. The display continues until the first null byte or until all characters in range have been displayed. All nonprintable characters, such as carriage returns and line feeds, are displayed as periods (.).

db

Byte values and ASCII characters.

+

Each display line shows the address of the first byte in the line, followed by up to 16 hexadecimal byte values. The byte values are immediately followed by the corresponding ASCII values. The eighth and ninth hexadecimal values are separated by a hyphen (-). All nonprintable characters, such as carriage returns and line feeds, are displayed as periods (.).

+

The default count is 128 bytes.

dc

Double-word values (4 bytes) and ASCII characters.

+

Each display line shows the address of the first word in the line and up to eight hexadecimal word values, as well as their ASCII equivalent.

+

The default count is 32 DWORDs (128 bytes).

dd

Double-word values (4 bytes).

+

The default count is 32 DWORDs (128 bytes).

dD

Double-precision floating-point numbers (8 bytes).

+

The default count is 15 numbers (120 bytes).

df

Single-precision floating-point numbers (4 bytes).

+

The default count is 16 numbers (64 bytes).

dp

Pointer-sized values. This command is equivalent to dd or dq, depending on whether the target computer's processor architecture is 32-bit or 64-bit, respectively.

+

The default count is 32 DWORDs or 16 quad-words (128 bytes).

dq

Quad-word values (8 bytes).

+

The default count is 16 quad-words (128 bytes).

du

Unicode characters.

+

Each line displays up to 48 characters. The display continues until the first null byte or until all characters in range have been displayed. All nonprintable characters, such as carriage returns and line feeds, are displayed as periods (.).

dw

Word values (2 bytes).

+

Each display line shows the address of the first word in the line and up to eight hexadecimal word values.

+

The default count is 64 words (128 bytes).

dW

Word values (2 bytes) and ASCII characters.

+

Each display line shows the address of the first word in the line and up to eight hexadecimal word values.

+

The default count is 64 words (128 bytes).

dyb

Binary values and byte values.

+

The default count is 32 bytes.

dyd

Binary values and double-word values (4 bytes).

+

The default count is 8 DWORDs (32 bytes).

+ +  + +If you attempt to display an invalid address, its contents are shown as question marks (**?**). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20d,%20da,%20db,%20dc,%20dd,%20dD,%20df,%20dp,%20dq,%20du,%20dw%20%28Display%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/d.md b/windows-driver-docs-pr/debugger/d.md new file mode 100644 index 0000000000..7eeb0f705f --- /dev/null +++ b/windows-driver-docs-pr/debugger/d.md @@ -0,0 +1,85 @@ +--- +title: D (Windows Debugger Glossary) +description: Glossary page - D +Robots: noindex, nofollow +ms.assetid: e4d53375-c82e-493b-9ccb-444c211fbc79 +--- + +# D + + +**data breakpoint** +See processor breakpoint. + +**DbgEng extension** +A debugger extension based on the prototypes in the dbgeng.h header file. These extensions use the debugger engine API to communicate with the debugger engine. + +**debug build** +See Checked Build. + +**debuggee** +See target. + +**debugger** +A debugger engine application that uses the full functionality of the debugger engine. For example, WinDbg, CDB, NTSD, and KD are debuggers. + +**debugger console** +A fictional entity representing the source of the debugger engine input and the destination of its output. In reality, the debugger engine only uses input and output callbacks and has no notion of what is being used to implement them. + +Typically, input is received from the Debugger Command window and output is sent to the same window. However, the input and output callbacks can provide many other sources of input and destinations for output, for example, remote connections, script files, and log files. + +**debugger engine** +A library for manipulating debugging targets. Its interface is based on the prototypes in the dbgeng.h file. It is used by debuggers, extensions, and debugger engine applications. + +**debugger engine API** +A powerful interface to control the behavior of the debugger engine. It may be used by debuggers, DbgEng extensions, and debugger engine applications. The prototypes for this interface are found in the dbgeng.h header file. + +**debugger engine application** +A stand-alone application that uses the debugger engine API to control the debugger engine. + +**debugger extension** +An external function that can run inside the debugger. Each extension is exported from a module known as an debugger extension DLL. The debugger engine invokes the debugger extension by calling its code within the DLL. Some debugger extensions ship with Debugging Tools for Windows. You can write your own extensions to automate any number of debugger features or to customize the output of the information accessible to the debugger. + +Also referred to as an , or simply . + +**debugger extension DLL** +A DLL containing debugger extensions. When the debugger engine loads the DLL these extensions become available for use within the debugger. + +**debugger extension library** +See debugger extension DLL. + +**debugging client** +An instance of the debugger engine acting as a proxy, sending debugger commands and I/O to the debugging server. + +**debugging server** +An instance of the debugger engine acting as a host, listening for connections from debugging clients. + +**debugging session** +The debugging session is the actual act of running a software debugging program, such as WinDbg, KD, or CDB, to debug a software component, system service, application, or operating system. The debugging session can also be run against a memory dump file for analysis. + +A debugging session starts when a acquires a and lasts until all targets have been discarded. + +**default exception filter** +The event filter which applies to exception events that do not match any other exception filters. The default exception filter is a specific exception filter. + +**dormant mode** +A state in which a debugger program is running, but without a target or active session. + +**downstream store** +A cache of symbols created by a symbol server. Typically this cache is on your local machine, while the symbol store is located remotely. If you have a chain of symbol servers, the downstream store can be located on any computer downstream from the symbol store. + +**dump file** +See crash dump file. + +**dump target** +A crash dump file that is being debugged. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20D%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbengprx-command-line-options.md b/windows-driver-docs-pr/debugger/dbengprx-command-line-options.md new file mode 100644 index 0000000000..c360092644 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbengprx-command-line-options.md @@ -0,0 +1,55 @@ +--- +title: DbEngPrx Command-Line Options +description: The DbEngPrx command line uses the following syntax. +ms.assetid: 3c0675a4-93f0-4aaa-9f33-9a45c48c1ff4 +keywords: ["DbEngPrx Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DbEngPrx Command-Line Options +api_type: +- NA +--- + +# DbEngPrx Command-Line Options + + +The DbEngPrx command line uses the following syntax. + +``` +dbengprx [-p] -c ClientTransport -s ServerTransport + +dbengprx -? +``` + +## Parameters + + + **-p** +Causes DbEngPrx to continue existing even after all connections to it are dropped. + + **-c** *ClientTransport* +Specifies the protocol settings to be used in connecting to the server. The protocol should match that used when the server was created. For details, see [**Activating a Repeater**](activating-a-repeater.md). + + **-s** *ServerTransport* +Specifies the protocol settings that will be used when the client connects to the repeater. For details, see [**Activating a Repeater**](activating-a-repeater.md). + + **-?** +Displays a message box with help text for the DbEngPrx command line. + +For information about using DbEngPrx, see [Repeaters](repeaters.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DbEngPrx%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgeng-extension-design-guide.md b/windows-driver-docs-pr/debugger/dbgeng-extension-design-guide.md new file mode 100644 index 0000000000..085b1c57e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgeng-extension-design-guide.md @@ -0,0 +1,37 @@ +--- +title: DbgEng Extension Design Guide +description: DbgEng Extension Design Guide +ms.assetid: c7046c2a-9cda-4cae-b47a-f36cca44e82d +keywords: ["DbgEng Extensions, Design Guide"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DbgEng Extension Design Guide + + +## + + +This section includes: + +[Anatomy of a DbgEng Extension DLL](anatomy-of-a-dbgeng-extension-dll.md) + +[Using Clients and the Engine](using-clients-and-the-engine.md) + +[Writing DbgEng Extension Code](writing-dbgeng-extension-code.md) + +[Building DbgEng Extensions](building-dbgeng-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DbgEng%20Extension%20Design%20Guide%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgerr001--peb-is-paged-out.md b/windows-driver-docs-pr/debugger/dbgerr001--peb-is-paged-out.md new file mode 100644 index 0000000000..c91a6cdbb6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgerr001--peb-is-paged-out.md @@ -0,0 +1,41 @@ +--- +title: dbgerr001 PEB is Paged Out +description: dbgerr001 PEB is Paged Out +ms.assetid: 60b20242-e458-4c36-b78d-17703c02b8b9 +keywords: ["dbgerr001", "PEB is paged out (dbgerr001)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# dbgerr001: PEB is Paged Out + + +## + + +Debugger error **dbgerr001** displays the message "PEB is paged out." This error indicates that the process environment block (PEB) is not accessible. + +To load symbols, the debugger looks at the list of modules loaded by the operating system. The pointer to the user-mode module list is one of the items stored in the PEB. + +In order to reclaim memory, the Memory Manager may page out user-mode data to make space for other process or kernel mode components. + +When this error occurs, it means that the debugger has detected that the PEB data structure for this process is no longer readable. Most likely, is has been paged out to disk. + +Without this data structure, the debugger cannot determine what images the symbols should be loaded for. + +**Note**   This only affects symbol files for the user-mode modules. Kernel-mode modules and symbols are not affected, as they are tracked in a different list. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dbgerr001:%20PEB%20is%20Paged%20Out%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgerr002--bad-pointer.md b/windows-driver-docs-pr/debugger/dbgerr002--bad-pointer.md new file mode 100644 index 0000000000..2e016cb1ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgerr002--bad-pointer.md @@ -0,0 +1,39 @@ +--- +title: dbgerr002 Bad Pointer +description: dbgerr002 Bad Pointer +ms.assetid: d5f2404e-3e7d-4de2-a772-0d42169eb9ad +keywords: ["dbgerr002", "Bad pointer (dbgerr002)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# dbgerr002: Bad Pointer + + +## + + +Debugger error **dbgerr002** displays the message "Bad pointer." This error indicates a problem retrieving a symbol file. + +The symbol server has the file indexed, but is being redirected to another location to find the file. No file is accessible at this other location. + +Two common causes of this problem are: + +- The path is a UNC path, and the computer containing this server is not available. + +- The path indicates a directory or file that has been deleted. + +If your symbol store was created by using SymStore, you can find the full path to this file by examining file.ptr. For details, see [Using SymStore](symstore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dbgerr002:%20Bad%20Pointer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgerr003--mismatched-symbols.md b/windows-driver-docs-pr/debugger/dbgerr003--mismatched-symbols.md new file mode 100644 index 0000000000..5080b41f87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgerr003--mismatched-symbols.md @@ -0,0 +1,31 @@ +--- +title: dbgerr003 Mismatched Symbols +description: dbgerr003 Mismatched Symbols +ms.assetid: 95251f5a-5479-4dc8-b3bb-4eb6096bdb6e +keywords: ["dbgerr003", "Mismatched symbols (dbgerr003)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# dbgerr003: Mismatched Symbols + + +## + + +Debugger error **dbgerr003** displays the message "*File* has mismatched symbols." This error indicates that DbgHelp found the symbol file represented by File, but that the symbol file is not the correct version, or that DbgHelp cannot confirm that the symbol file is the correct version. + +The debugger might load the specified symbol file despite this error, depending on other requirements in the path. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dbgerr003:%20Mismatched%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgerr004--page-not-present-in-dump-file.md b/windows-driver-docs-pr/debugger/dbgerr004--page-not-present-in-dump-file.md new file mode 100644 index 0000000000..a8f7c0840d --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgerr004--page-not-present-in-dump-file.md @@ -0,0 +1,37 @@ +--- +title: dbgerr004 Page Not Present in Dump File +description: dbgerr004 Page Not Present in Dump File +ms.assetid: e76d11fc-857b-4a40-8f41-f34f3bcade57 +keywords: ["dbgerr004", "Page not present in dump file (dbgerr004)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# dbgerr004: Page Not Present in Dump File + + +## + + +Debugger error **dbgerr004** displays the message "Page *number* not present in dump file." This error indicates that the debugger needed a memory page that was not included in the dump file being debugged. + +The specified *number* is the page frame number (PFN) corresponding to the location in the physical memory of the original page. + +To suppress this error message, use the [**.ignore\_missing\_pages 1**](-ignore-missing-pages--suppress-missing-page-errors-.md) command. This command allows debugging to proceed, but does not display this error message. + +Kernel-mode memory dumps come in three sizes, and the smaller sizes do not include all the memory pages. For details, see [Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md). + +User-mode memory dumps also come in various sizes. See [User-Mode Dump Files](user-mode-dump-files.md) for details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dbgerr004:%20Page%20Not%20Present%20in%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgerr005--private-symbols-required.md b/windows-driver-docs-pr/debugger/dbgerr005--private-symbols-required.md new file mode 100644 index 0000000000..819d289298 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgerr005--private-symbols-required.md @@ -0,0 +1,39 @@ +--- +title: dbgerr005 Private Symbols Required +description: dbgerr005 Private Symbols Required +ms.assetid: 0e3b9c98-1f02-4fff-9a91-d3a7470df882 +keywords: ["dbgerr005", "Private symbols required (dbgerr005)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# dbgerr005: Private Symbols Required + + +## + + +Debugger error **dbgerr005** displays the message "Private symbols (symbols.pri) are required for locals." This error indicates that the debugger is unable to perform an action because private symbols are not present. + +During kernel-mode debugging, the debugger needs symbols for Microsoft Windows. During user-mode debugging, the debugger needs symbols for the target application, and often needs symbols for Windows as well. + +Some basic symbols, such as function names and global variables, are needed for even the most rudimentary debugging. These are called *public symbols*. Symbols such as data structure names, global variables visible in only one object file, local variables, and line number information are not always required for debugging, although they are useful for a more in-depth debugging session. These are called *private symbols*. + +Many software manufacturers, including Microsoft, produce two versions of their symbol files. The version released to their customers contains only public symbols. The version used internally contains both public and private symbols. + +Most debugging actions can be performed with public symbols alone. But certain actions -- such as displaying local variables -- require private symbols. When an action of this sort is attempted and private symbols are not available, this error message is displayed. + +When you see this message, it is usually best to simply continue debugging. The information you were unable to obtain is probably not essential to properly debugging the target. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dbgerr005:%20Private%20Symbols%20Required%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgrpc-command-line-options.md b/windows-driver-docs-pr/debugger/dbgrpc-command-line-options.md new file mode 100644 index 0000000000..159c943d99 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgrpc-command-line-options.md @@ -0,0 +1,96 @@ +--- +title: DbgRpc Command-Line Options +description: The DbgRpc command line must always contain exactly one of the -l, -e, -t, -c, or -a switches. The options following these switches depend on the switch used. +ms.assetid: 1c90f97c-f054-402d-a559-2459528029b9 +keywords: ["DbgRpc Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DbgRpc Command-Line Options +api_type: +- NA +--- + +# DbgRpc Command-Line Options + + +The DbgRpc command line must always contain exactly one of the -l, -e, -t, -c, or -a switches. The options following these switches depend on the switch used. The -s, -p, and -r options can be used with any other options. + +``` + dbgrpc [-s Server -p ProtSeq] [-r Radix] -l -P ProcessID -L CellID1.CellID2 + +dbgrpc [-s Server -p ProtSeq] [-r Radix] -e [-E EndpointName] + +dbgrpc [-s Server -p ProtSeq] [-r Radix] -t -P ProcessID [-T ThreadID] + +dbgrpc [-s Server -p ProtSeq] [-r Radix] [-c|-a] [-C CallID] [-I IfStart] [-N ProcNum] [-P ProcessID] + +dbgrpc -? +``` + +## Parameters + + + **-s** *Server* +Allows DbgRpc to view information from a remote machine. The server name should not be preceded by slash marks. For more information about using DbgRpc remotely, see [Using the DbgRpc Tool](using-the-dbgrpc-tool.md). + + **-p** *ProtSeq* +Specifies the remote transport to be used. The possible values of *ProtSeq* are **ncacn\_ip\_tcp** (TCP protocol) and **ncacn\_np** (named pipe protocol). TCP protocol is recommended. For more information about using DbgRpc remotely, see [Using the DbgRpc Tool](using-the-dbgrpc-tool.md). + + **-r** *Radix* +Specifies the radix to be used for the command parameters. The default is base 16. If the **-r** parameter is used, it should be placed first on the line, since it only affects parameters listed after itself. It does not affect the output of the DbgRpc tool. + + **-l** +Displays RPC state information for the specified cell. For an example, see [Get RPC Cell Information](get-rpc-cell-information.md). + + *ProcessID* +Specifies the process ID (PID) of a process. When the **-l** option is being used, this should be the process whose server contains the desired cell. When the **-t** option is being used, this should be the process containing the desired thread. When the **-c** or **-a** options are being used, this parameter is optional; it should be the server process that owns the calls you wish to display. + +*CellID1*.*CellID2* +Specifies the number of the cell to be displayed. + + **-e** +Searches the system's RPC state information for endpoint information. For an example, see [Get RPC Endpoint Information](get-rpc-endpoint-information.md). + + *EndpointName* +Specifies the number of the endpoint to be displayed. If omitted, the endpoints for all processes on the system are displayed. + + **-t** +Searches the system's RPC state information for thread information. For an example, see [Get RPC Thread Information](get-rpc-thread-information.md). + + *ThreadID* +Specifies the thread ID of the thread to be displayed. If omitted, all threads in the specified process will be displayed. + + **-c** +Searches the system's RPC state information for server-side call (SCALL) information. For an example, see [Get RPC Call Information](get-rpc-call-information.md). + + **-a** +Searches the system's RPC state information for client call (CCALL) information. For an example, see [Get RPC Client Call Information](get-rpc-client-call-information.md). This option requires full RPC state information. + + *CallID* +Specifies the call ID. This parameter is optional; include it only if you want to display calls matching a specific *CallID* value. + + *IfStart* +Specifies the first DWORD of the interface's universally unique identifier (UUID) on which the call was made. This parameter is optional; include it only if you want to display calls matching a specific *IfStart* value. + + *ProcNum* +Specifies the procedure number of this call. (The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file -- the first routine in the interface is 0, the second 1, and so on.) This parameter is optional; include it only if you want to display calls matching a specific *ProcNum* value. + +### Additional Information + +For more information about debugging Microsoft Remote Procedure Call (RPC), see [RPC Debugging](rpc-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DbgRpc%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbgsrv-command-line-options.md b/windows-driver-docs-pr/debugger/dbgsrv-command-line-options.md new file mode 100644 index 0000000000..17b02d91c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbgsrv-command-line-options.md @@ -0,0 +1,69 @@ +--- +title: DbgSrv Command-Line Options +description: The DbgSrv command line uses the following syntax. +ms.assetid: 817f7ede-bdaf-4d4e-a1bd-579c67ea1ab9 +keywords: ["DbgSrv Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DbgSrv Command-Line Options +api_type: +- NA +--- + +# DbgSrv Command-Line Options + + +The DbgSrv command line uses the following syntax. + +``` +dbgsrv -t ServerTransport [-sifeo image.ext] -c[s] AppCmdLine [-x | -pc] + +dbgsrv -? +``` + +All options are case-sensitive. + +## Parameters + + + **-t** *ServerTransport* +Specifies the transport protocol. For a list of the possible protocols and the syntax for *ServerTransport* in each case, see [**Activating a Process Server**](activating-a-process-server.md). + + **-sifeo** *Executable* +Suspends the Image File Execution Option (IFEO) value for the given image. *Executable* should include the file name of the executable image, including the file name extensions. The -sifeo option allows DbgSrv to be set as the IFEO debugger for an image created by the -c option, without causing recursive invocation due to the IFEO setting. This option can be used only if -c is used. + + **-c** +Causes DbgSrv to create a new process. You can use this to create a process that you intend to debug. This is similar to spawning a new process from the debugger, except that this process will *not* be debugged when it is created. To debug this process, determine its PID and use the **-p** option when starting the smart client to debug this process. + + **s** +Causes the newly-created process to be immediately suspended. If you are using this option, it is recommended that you use CDB as your smart client, and that you start the smart client with the -pb command-line option, in conjunction with -p PID. If you include the -pb option on the command line, the process will resume when the debugger attaches to it; otherwise you can resume the process with the [**~\*m**](-m--resume-thread-.md) command. + + *AppCmdLine* +Specifies the full command line of the process to be created. *AppCmdLine* can be either a Unicode or ASCII string, and can include any printable character. All text that appears after the **-c**\[**s**\] parameter will be taken to form the string *AppCmdLine*. + + **-x** +Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its command line. + + **-pc** +Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its command line. A syntax error results if -pc is the final element on the DbgSrv command line. Aside from this restriction, -pc is identical to -x. + + **-?** +Displays a message box with help text for the DbgSrv command line. + +For information about using DbgSrv, see [Process Servers (User Mode)](process-servers--user-mode-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DbgSrv%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbh-command-line-options.md b/windows-driver-docs-pr/debugger/dbh-command-line-options.md new file mode 100644 index 0000000000..e4bdcc15d0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbh-command-line-options.md @@ -0,0 +1,81 @@ +--- +title: DBH Command-Line Options +description: The DBH command line uses the following syntax. +ms.assetid: fd333c2d-1f07-4a47-8653-e10cf58417a5 +keywords: ["DBH Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- DBH Command-Line Options +api_type: +- NA +--- + +# DBH Command-Line Options + + +The DBH command line uses the following syntax. + +``` +dbh [Options] -p:PID [Command] + +dbh [Options] ExecutableName [Command] + +dbh [Options] SymbolFileName [Command] + +dbh -? + +dbh -?? +``` + +## Parameters + + +**-p:***PID* +Specifies the process ID of the process whose symbols are to be loaded. + + *ExecutableName* +Specifies the executable file whose symbols are to be loaded, including the file name extension (usually .exe or .sys). You should include a relative or absolute directory path; if no path is included, the current working directory is assumed. If the specified file is not found in this location, DBH searches for it using **SymLoadModuleEx**. + + *SymbolFileName* +Specifies the symbol file whose symbols are to be loaded, including the file name extension (.pdb or .dbg). You should include a relative or absolute directory path; if no path is included, the current working directory is assumed. + + *Options* +Any combination of the following options. + +**-d** +Causes decorated names to be used when displaying symbols and searching for symbols. When this option is used, [SYMOPT\_PUBLICS\_ONLY](symbol-options.md#symopt-publics-only) is turned on, and both SYMOPT\_UNDNAME and SYMOPT\_AUTO\_PUBLICS are turned off. This is equivalent to issuing the command symopt +4000 followed by symopt -10002 after DBH is running. + +**-s:***Path* +Sets the symbol path to the specified *Path* value. + +**-n** +Turns on *noisy symbol loading*. Additional information is displayed about the search for symbols. The name of each symbol file is displayed as it is loaded. If the debugger cannot load a symbol file, it displays an error message. Error messages for .pdb files are displayed in text. Error messages for .dbg files are in the form of an error code, explained in the winerror.h file. Not all of these messages are useful, but some of them may be helpful to analyze why a symbol file cannot be found or matched. If an image file is loaded solely to recover symbolic header information, this is displayed as well. + + *Command* +Causes DBH to run, execute the specified *Command*, and then exit. For a list of possible commands, see [DBH Commands](dbh-commands.md). + + **-?** +Displays help text for the DBH command line. + + **-??** +Displays help text for the DBH command line, and displays a list of all DBH commands. + +### Additional Information + +For more information about the DBH tool, see [Using DBH](using-dbh.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DBH%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbh-commands.md b/windows-driver-docs-pr/debugger/dbh-commands.md new file mode 100644 index 0000000000..ceb2d58ac3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbh-commands.md @@ -0,0 +1,374 @@ +--- +title: DBH Commands +description: DBH Commands +ms.assetid: 124e8be9-1b1a-4498-84a4-5dbb6b5b9026 +keywords: ["DBH, commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DBH Commands + + +From the DBH command line, you can use a variety of commands to analyze symbols and symbol files. + +The following table lists the commands that control the DBH options and perform other basic tasks. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEffect

verbose [on|off]

Turns verbose mode on or off. With no parameter, displays the current verbose mode setting.

sympath [Path]

Sets the symbol search path. With no parameter, displays the current symbol search path.

symopt Options

+

symopt +Options

+

symopt -Options

+

symopt

Sets the symbol options. With no + or -, the value of Options replaces the current symbol options. If + or - is used, Options specifies the options to be added or removed; there must be a space before the + or - but no space after it. With no parameter, the current symbol options are displayed. When DBH is launched, the default value of all the symbol options is 0x10C13. For a list of available options, see [Setting Symbol Options](symbol-options.md).

help

Displays help text for the DBH commands.

quit

Quits the DBH program.

+ +  + +The following table lists the commands that load, unload, and rebase the target module. These commands cannot be used if DBH was started by specifying a process ID on the command line. + + ++++ + + + + + + + + + + + + + + + + + + + + +
CommandEffect

load File

Loads the specified module. File should specify the path, file name, and file name extension of either the executable file or the symbol file.

unload

Unloads the current module.

base Address

Sets the default base address to the specified value. All symbol addresses will be determined relative to this base address.

+ +  + +The following table lists the commands that search for files and display directory information. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEffect

findexe File Path

Locates the specified executable file in the specified path, using the FindExecutableImage routine.

finddbg File Path

Locates the specified .dbg file in the specified path. Including the .dbg extension is optional.

dir File Path

Locates the specified file in the specified path or in any subdirectory under this path, using the EnumDirTree routine.

srchtree Path File

Locates the specified file in the specified path or in any subdirectory under this path, using the SearchTreeForFile routine. This command is the same as dir, except that the parameters are reversed.

ffpath File

Finds the specified file in the current symbol path.

+ +  + +The following table lists the commands that parse the module list and control the default module. The default module and its base address are displayed on the DBH prompt. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEffect

mod Address

Changes the default module to the module with the specified base address.

refresh

Refreshes the module list.

omap

Displays the module OMAP structures.

epmod PID

Enumerates all the modules loaded for the specified process. PID specifies the process ID of the desired process.

info

Displays information about the currently loaded module.

obj Mask

Lists all object files associated with the default module that match the specified pattern. Mask may contain a variety of wildcard characters and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details.

src Mask

Lists all source files associated with the default module that match the specified pattern. Mask may contain a variety of wildcard characters and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details.

enummod

Enumerates all loaded modules. There is always at least one module, unless DBH is running without a target, in which case there are none.

+ +  + +The following table lists the commands that display and search for symbols. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEffect

enum Module!Symbol

Enumerates all symbols matching the specified module and symbol. Module specifies the module to search (without the file name extension). Symbol specifies a pattern that the symbol must contain. Both Module and Symbol may contain a variety of wildcard characters and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details.

enumaddr Address

Enumerates all symbols associated with the specified address.

addr Address

Displays detailed information about the symbols associated with the specified address.

name [Module!]Symbol

Displays detailed information about the specified symbol. An optional Module specifier may be included. Wildcards should not be used, because if multiple symbols match the pattern, name only displays the first of them.

next [Module!]Symbol

+

next Address

Displays detailed information about the next symbol after the specified symbol or address. If a symbol is specified by name, an optional Module specifier may be included, but wildcards should not be used.

prev [Module!]Symbol

+

prev Address

Displays detailed information about the first symbol previous to the specified symbol or address. If a symbol is specified by name, an optional Module specifier may be included, but wildcards should not be used.

line File#LineNum

Displays the hexadecimal address of the binary instruction associated with the specified source line, and any symbols associated with this line. Also sets the current line number equal to the specified line number. File specifies the name of the source file, and LineNum specifies the line number within that file; these should be separated with a number sign ( # ).

srclines File LineNum

Displays the object files associated with the specified source line, and the hexadecimal address of the binary instruction associated with this line. Does not change the current line number. File specifies the name of the source file, and LineNum specifies the line number within that file; these should be separated with a space.

laddr Address

Displays the source file and line number corresponding to the symbol located at the specified address.

linenext

Increments the current line number, and displays information about the new line number.

lineprev

Decrements the current line number, and displays information about the new line number.

locals Function [Mask]

Displays all local variables contained within the specified function. If Mask is included, only those locals matching the specified pattern are displayed; see [String Wildcard Syntax](string-wildcard-syntax.md) for details.

type TypeName

Displays detailed information about the specified data type. TypeName specifies the name of the data type (for example, WSTRING). If no type name matches this value, any matching symbol will be displayed. Unlike most DBH command parameters, TypeName is case-sensitive.

elines [Source [Obj]]

Enumerates all source lines matching the specified source mask and object mask. Source specifies the name of the source file, including the absolute path and file name extension. Obj specifies the name of the object file, including the relative path and file name extension. Both Source and Obj may contain a variety of wildcard characters and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details. If a parameter is omitted this is equivalent to using the asterisk (*) wildcard. If you do not wish to specify path information, prefix the file name with *\ to indicate a wildcard path.

index Value

Displays detailed information about the symbol with the specified index value.

scope Address

+

scope [Module!]Symbol

Displays detailed information about the parent of the specified symbol. The symbol may be specified by address or by name.

srch [mask=Symbol] [index=Index] [tag=Tag] [addr=Address] [globals]

Searches for all symbols that match the specified masks. Symbol specifies the symbol name. It should not include the module name, but it may contain wildcard characters and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details. Index specifies the hexadecimal address of a symbol to be used as the parent for the search. Tag specifies the hexadecimal symbol type classifier (SymTagXxx) value that must match the symbol. Address specifies the address of the symbol. If globals is included, only global symbols will be displayed.

uw Address

Displays the unwind information for the function at the specified address.

dtag

Displays all the symbol type classifier (SymTagXxx) values.

etypes

Enumerates all data types.

dump

Displays a complete list of all symbol information in the target file.

+ +  + +The following table lists the commands that relate to symbol servers and symbol stores. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEffect

home [Path]

Sets the home directory used by SymSrv and SrcSrv for the default downstream store. If the symbol path contains a reference to a symbol server that uses a default downstream store, then the sym subdirectory of the home directory will be used for the downstream store. With no parameter, home displays the current home directory.

srvpath Path

Tests whether the specified path is the path of a symbol store.

srvind File

Finds the symbol server index that corresponds to the specified file. The symbol server index is a unique value based on the contents of the file, regardless of whether it actually has been added to any symbol store. File should specify the file name and absolute path of the desired file.

fii File

Displays the symbol server indexes for the specified binary file and its associated files.

getfile File Index

Displays the file with the specified name and symbol server index. File specifies the name of the desired file; this should not include its path. Index specifies the symbol server index of the desired file. DBH uses the SymFindFileInPath routine to search the tree under the current symbol path for a file with this name and this index.

sup Path File1 File2

Stores a file in a symbol store, based on the values of the parameters. Path specifies the directory path of the symbol store. File1 and File2 are used to create a delta value, which is in turn used to determine the file being stored.

storeadd File Store

Adds the specified file to the specified symbol store. Store should be the root path of the symbol store.

+ +  + +The following table lists the DBH commands that apply to real and imaginary symbols. + + ++++ + + + + + + + + + + + + + + + + + + + + +
CommandEffect

undec Name

Reveals the meaning of the decorations attached to the specified symbol name. Name can be any string; it need not correspond to a currently loaded symbol. If Name contains C++ decorations, the meaning of these decorations is displayed.

add Name Address Size

Adds the specified imaginary symbol to the list of symbols loaded in DBH. Name specifies the name of the symbol to be added, Address specifies its hexadecimal address, and Size its hexadecimal size in bytes. This is treated like any other symbol in later DBH commands, until the DBH session is ended with quit or unload, or until the imaginary symbol is deleted with del. The actual target symbol file is not altered.

del Name

+

del Address

Deletes an imaginary symbol previously added with the add command. The symbol can be specified either by name or by address. This cannot be used to delete real symbols.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DBH%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dbh.md b/windows-driver-docs-pr/debugger/dbh.md new file mode 100644 index 0000000000..b846eaf3e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dbh.md @@ -0,0 +1,40 @@ +--- +title: DBH +description: DBH +ms.assetid: b5cdc9ef-eca8-4b23-8fbe-06532ffcc12c +keywords: ["DBH", "DBH, overview", "symbols, DBH"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DBH + + +The DBH tool (dbh.exe) is a command-line tool that displays information about the contents of a symbol file. + +DBH exposes the functionality of the DbgHelp API (dbghelp.dll) through a convienient command-line interface. Therefore, its behavior may change as DbgHelp is updated. The source code for one version of DBH is available in the Windows Software Development Kit (SDK) for Windows 8. + +This section includes: + +[Using DBH](using-dbh.md) + +[Additional DBH Examples](additional-dbh-examples.md) + +[**DBH Command-Line Options**](dbh-command-line-options.md) + +[DBH Commands](dbh-commands.md) + +For more information about the DbgHelp API, see the Debug Help Library documentation, which is installed as part of Debugging Tools for Windows if you perform a custom install and select the **SDK** feature and its subfeatures. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DBH%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dda--ddp--ddu--dpa--dpp--dpu--dqa--dqp--dqu--display-referenced-memory.md b/windows-driver-docs-pr/debugger/dda--ddp--ddu--dpa--dpp--dpu--dqa--dqp--dqu--display-referenced-memory.md new file mode 100644 index 0000000000..9ac23e2250 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dda--ddp--ddu--dpa--dpp--dpu--dqa--dqp--dqu--display-referenced-memory.md @@ -0,0 +1,166 @@ +--- +title: dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory) +description: The dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, and dqu commands display the pointer at the specified location, dereference that pointer, and display the associated memory. +ms.assetid: af3db4e2-e3fc-4c4d-9432-13b87e699716 +keywords: ["dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory) +api_type: +- NA +--- + +# dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory) + + +The **dda**, **ddp**, **ddu**, **dpa**, **dpp**, **dpu**, **dqa**, **dqp**, and **dqu** commands display the pointer at the specified location, dereference that pointer, and then display the memory at the resulting location in a variety of formats. + +``` +ddp [Options] [Range] +dqp [Options] [Range] +dpp [Options] [Range] +dda [Options] [Range] +dqa [Options] [Range] +dpa [Options] [Range] +ddu [Options] [Range] +dqu [Options] [Range] +dpu [Options] [Range] +``` + +## Parameters + + + *Options* +Specifies one or more display options. Any of the following options can be included, except that no more than one **/p**\* option can be indicated: + +**/c***Width* +Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type. Because of the way pointers are displayed by these commands, it is usually best to use the default of only one data column. + +**/p** +(Kernel-mode only) Uses physical memory addresses for the display. The range specified by *Range* will be taken from physical memory rather than virtual memory. + +**/p\[c\]** +(Kernel-mode only) Same as **/p**, except that cached memory will be read. The brackets around **c** must be included. + +**/p\[uc\]** +(Kernel-mode only) Same as **/p**, except that uncached memory will be read. The brackets around **uc** must be included. + +**/p\[wc\]** +(Kernel-mode only) Same as **/p**, except that write-combined memory will be read. The brackets around **wc** must be included. + + *Range* +Specifies the memory area to display. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If you omit *Range*, the command will display memory starting at the ending location of the last display command. If *Range* is omitted and no previous display command has been used, the display begins at the current instruction pointer. If a simple address is given, the default range length is 128 bytes. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The second and third characters of this command are case-sensitive. + +The second character of this command determines the pointer size used: + + ++++ + + + + + + + + + + + + + + + + + + + + +
CommandDisplay

dd*

32-bit pointers used

dq*

64-bit pointers used

dp*

Standard pointer sizes used: 32-bit or 64-bit, depending on the target's processor architecture

+ +  + +The third character of this command determines how the dereferenced memory is displayed: + + ++++ + + + + + + + + + + + + + + + + + + + + +
CommandDisplay

d*p

Displays the contents of the memory referenced by the pointer in DWORD or QWORD format, depending on the pointer size of the target's processor architecture. If this value matches any known symbol, this symbol is displayed as well.

d*a

Displays the contents of the memory referenced by the pointer in ASCII character format.

d*u

Displays the contents of the memory referenced by the pointer in Unicode character format.

+ +  + +If line number information has been enabled, source file names and line numbers will be displayed when available. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dda,%20ddp,%20ddu,%20dpa,%20dpp,%20dpu,%20dqa,%20dqp,%20dqu%20%28Display%20Referenced%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dds--dps--dqs--display-words-and-symbols-.md b/windows-driver-docs-pr/debugger/dds--dps--dqs--display-words-and-symbols-.md new file mode 100644 index 0000000000..7de6993200 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dds--dps--dqs--display-words-and-symbols-.md @@ -0,0 +1,102 @@ +--- +title: dds, dps, dqs (Display Words and Symbols) +description: The dds, dps, and dqs commands display the contents of memory in the given range. This memory is assumed to be a series of addresses in the symbol table. +ms.assetid: 5a3ed1c4-723a-4902-bfbf-d4a44d2cd0b5 +keywords: ["dds, dps, dqs (Display Words and Symbols) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dds, dps, dqs (Display Words and Symbols) +api_type: +- NA +--- + +# dds, dps, dqs (Display Words and Symbols) + + +The **dds**, **dps**, and **dqs** commands display the contents of memory in the given range. This memory is assumed to be a series of addresses in the symbol table. The corresponding symbols are displayed as well. + +``` +dds [Options] [Range] +dqs [Options] [Range] +dps [Options] [Range] +``` + +## Parameters + + + *Options* +Specifies one or more display options. Any of the following options can be included, except that no more than one **/p**\* option can be indicated: + +**/c** *Width* +Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type. Because of the way symbols are displayed by these commands, it is usually best to use the default of only one data column. + +**/p** +(Kernel-mode only) Uses physical memory addresses for the display. The range specified by *Range* will be taken from physical memory rather than virtual memory. + +**/p\[c\]** +(Kernel-mode only) Same as **/p**, except that cached memory will be read. The brackets around **c** must be included. + +**/p\[uc\]** +(Kernel-mode only) Same as **/p**, except that uncached memory will be read. The brackets around **uc** must be included. + +**/p\[wc\]** +(Kernel-mode only) Same as **/p**, except that write-combined memory will be read. The brackets around **wc** must be included. + + *Range* +Specifies the memory area to display. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If you omit *Range*, the command will display memory starting at the ending location of the last display command. If *Range* is omitted and no previous display command has been used, the display begins at the current instruction pointer. If a simple address is given, the default range length is 128 bytes. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The second character of **dds** is case-sensitive. The third character of all these commands is case-sensitive. + +The **dds** command displays double-word (4 byte) values like the [**dd**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command. The **dqs** command displays quad-word (8 byte) values like the **dq** command. The **dps** command displays pointer-sized values (4 byte or 8 byte, depending on the target computer's architecture) like the **dp** command. + +Each of these words is treated as an address in the symbol table. The corresponding symbol information is displayed for each word. + +If line number information has been enabled, source file names and line numbers will be displayed when available. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dds,%20dps,%20dqs%20%28Display%20Words%20and%20Symbols%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dealing-with-unavailable-symbol-stores.md b/windows-driver-docs-pr/debugger/dealing-with-unavailable-symbol-stores.md new file mode 100644 index 0000000000..5ec34ec038 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dealing-with-unavailable-symbol-stores.md @@ -0,0 +1,58 @@ +--- +title: Dealing with Unavailable Symbol Stores +description: Dealing with Unavailable Symbol Stores +ms.assetid: 42e3518b-b139-49cd-96cc-ea31f6df7964 +keywords: ["SymProxy, unavailable stores"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dealing with Unavailable Symbol Stores + + +If one of the symbol stores that SymSrv is configured to obtain files from is down or otherwise unavailable, the result can be long waits from the client for every file request. When SymSrv is called from SymProxy, you can avoid most of these waits by setting up SymSrv to stop trying to access the store in question. When this feature is engaged, SymSrv stops trying to use the store for a set period of time after it experiences a specified number of timeouts from the same store during a set interval. The values of these variables can be controlled either by an .ini file or from the registry. + +**To control symbol store access using a .ini file** + +1. In %WINDIR%\\system32\\inetsrv\\Symsrv.ini, create a section called **timeouts**. + +2. Add the values **trigger**, **count**, and **blackout** to this section. + +**Trigger** indicates the amount of time in minutes to watch for timeouts. **Count** indicates the number of timeouts to look for during the **trigger** period. **Blackout** indicates the length of time in minutes to disable the store after the threshhold is reached. + +For example, we recommend the following settings: + +``` +[timeouts] +trigger=10 +count=5 +blackout=15 +``` + +In this example, the store access is turned off if five timeouts are experienced in a 10-minute period. At the completion of a 15-minute blackout, the store is reactivated. + +**To control symbol store access using the registry** + +1. Create a key named + ``` + HKLM\ Software\Microsoft\Symbol Server\Timeouts + ``` + +2. Add three REG\_DWORD values **trigger**, **count**, and **blackout** to this key. Set these values as you would in the .ini file. + +Whether using the registry or an .ini file, if any of the trigger, count, or blackout values are set to 0 or if any of the keys or values do not exist, this functionality is disabled. + +This feature of SymSrv is currently available only when running as a service. This means that the only practical application of this feature is when it is called from SymProxy. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Dealing%20with%20Unavailable%20Symbol%20Stores%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---break.md b/windows-driver-docs-pr/debugger/debug---break.md new file mode 100644 index 0000000000..7d550d12d4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---break.md @@ -0,0 +1,67 @@ +--- +title: Debug Break +description: Debug Break +ms.assetid: fc17d0b2-3ef5-4e10-a6a3-51f7011fddcf +keywords: ["Debug Break", "controlling the target, Debug Break"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Break + + +## + + +Click **Break** on the **Debug** menu to stop the target's execution and return control to the debugger. + +In user mode, this command stops the process and its threads, enabling you to regain control of the debugger. In kernel mode, this command breaks into the target computer. + +You can also use this command while the debugger is active. In this situation, the command will truncate long [Debugger Command window](debugger-command-window.md) displays. + +The **Break** command is equivalent to pressing CTRL+BREAK or clicking the **Break (Ctrl+Break)** button (![screen shot of the break button](images/tbbreak.png)) on the toolbar. + +### ALT+DEL + +You can use **ALT+DEL** to send a **Break**. **ALT+DEL** works the same as **Break (Ctrl+Break).** + +### User-Mode Effects + +In user mode, the **Break** command causes the target application to break into the debugger. The target application stops, the debugger becomes active, and you can enter debugger commands. + +If the debugger is already active, **Break** does not affect the target application. However, you can use this command to terminate a debugger command. For example, if you have requested a long display and do not want to see any more of it, **Break** will end the display and return you to the debugger command prompt. + +When you are performing remote debugging with WinDbg, you can press the Break key on the host computer's keyboard. If you want to issue a break from the target computer's keyboard, use CTRL+C on an x86-based computer. + +You can press the F12 key to open a command prompt when the application that is being debugged is busy. Click one of the target application's windows and press F12 on the target computer. + +### Kernel-Mode Effects + +In kernel mode, the **Break** command causes the target computer to break into the debugger. This command locks the target computer and wakes up the debugger. + +When you are debugging a system that is still running, you must press the Break key on the host keyboard to open an initial command prompt. + +If the debugger is already active, **Break** does not affect the target computer. However, you can use this command to terminate a debugger command. For example, if you have requested a long display and do not want to see any more of it, **Break** will end the display and return you to the debugger command prompt. + +You can also use **Break** to open a command prompt when a debugger command is generating a long display or when the target computer is busy. When you are debugging an x86-based computer, you can also press CTRL+C on the target keyboard to have the same effect. + +The SYSRQ key (or pressing ALT+SYSRQ on an enhanced keyboard) is similar. This key works from the host or target keyboard on any processor. However, this key works only if you have opened the prompt by pressing CTRL+C at least one time before. + +You can disable the SYSRQ key by editing the registry. In the HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Services\\i8042prt\\Parameters registry key, create a value named **BreakOnSysRq** and set it equal to DWORD 0x0. Then, restart the computer. After you have restarted the computer, you can press the SYSRQ key on the target computer's keyboard and it will not break into the kernel debugger. + +### Additional Information + +The corresponding key in KD and CDB is [**CTRL+C**](ctrl-c--break-.md). For more information about other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Break%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---detach-debuggee.md b/windows-driver-docs-pr/debugger/debug---detach-debuggee.md new file mode 100644 index 0000000000..dcc082c5b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---detach-debuggee.md @@ -0,0 +1,39 @@ +--- +title: Debug Detach Debuggee +description: Debug Detach Debuggee +ms.assetid: 9b1c20ff-e675-4d28-bafc-9880ae7c21e3 +keywords: ["Debug Detach Debuggee"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Detach Debuggee + + +## + + +Click **Detach Debuggee** on the **Debug** menu to detach from the target application and leave it running. + +Detaching from the target is supported under one of the following conditions: + +- (Microsoft Windows XP and later versions of Windows) You are debugging a running user-mode target. + +- You are noninvasively debugging a user-mode target. + +If you are debugging a live target on Windows 2000, the **Detach Debuggee** command is not available, because this version of Windows does not support detaching from a target process. + +For more information about how to exit the debugger or detach from the target, see [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Detach%20Debuggee%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---event-filters.md b/windows-driver-docs-pr/debugger/debug---event-filters.md new file mode 100644 index 0000000000..3f07ffb104 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---event-filters.md @@ -0,0 +1,51 @@ +--- +title: Debug Event Filters +description: Debug Event Filters +ms.assetid: ffa1241a-8a75-44ac-94b7-608393cf4138 +keywords: ["Debug Event Filters", "exceptions, Debug Event Filters", "events, Debug Event Filters"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Event Filters + + +## + + +Click **Event Filters** on the **Debug** menu to open the **Event Filters** dialog box. In this dialog box, you can configure the break status and handling status of exceptions and events. + +### Dialog Box + +The **Event Filters** dialog box lists all events that the debugger recognizes. You may add numbered exceptions to the list that will then be displayed. + +To change the break status for an event, select the event and then click one of the **Execution** option buttons (**Enabled**, **Disabled**, **Output**, or **Ignore**). + +To change the handling status for an event, select the event and then click one of the **Continue** option buttons (**Handled** or **Not Handled**). + +To add a new numbered exception, click **Add**. When the **Exception Filter** dialog box appears, enter the exception code, click the appropriate button for the break status and handling status, and then click **OK**. + +To remove a numbered exception, select the exception and then click **Remove**. You cannot remove the standard events. + +When you set the status for the **Load module** or **Unload module** events, you can limit this status to a specific module. Click **Argument**, enter the name of the module or the base address of the module in the **Filter Argument** dialog box, and then click **OK**. You can use [wildcards](string-wildcard-syntax.md) when you specify the base address. If you do not specify a module, the break occurs when any module is loaded or unloaded. + +When you set the status for the **Debuggee output** event, you can limit this status to a specific output pattern. Click **Argument**, enter the output pattern in the **Filter Argument** dialog box, and then click **OK**. If you do not specify an output pattern, the break occurs for any output. + +If you want to set automatic commands that are executed if the event breaks into the debugger, select the event and then click **Commands**. The **Filter Command** dialog box will appear. Enter any commands that you want into the **Command** or **Second-chance Command** box. Separate multiple commands by using semicolons and do not enclose these commands in quotation marks. + +### Additional Information + +For more information about break status and handling status, all event codes, the default status for all events, and other methods of controlling this status, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Event%20Filters%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---go-handled-exception.md b/windows-driver-docs-pr/debugger/debug---go-handled-exception.md new file mode 100644 index 0000000000..6b1e33313b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---go-handled-exception.md @@ -0,0 +1,33 @@ +--- +title: Debug Go Handled Exception +description: Debug Go Handled Exception +ms.assetid: f6288286-b57d-484e-b08a-79b2b84b6ea9 +keywords: ["Debug Go Handled Exception", "controlling the target, Debug Go Handled Exception", "exceptions, Debug Go Handled Exception"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Go Handled Exception + + +## + + +Click **Go Handled Exception** on the **Debug** menu to resume execution on the target and to treat the current exception as handled. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). For more information about exceptions and other events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Go%20Handled%20Exception%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---go-unhandled-exception.md b/windows-driver-docs-pr/debugger/debug---go-unhandled-exception.md new file mode 100644 index 0000000000..6b8f7bdfcc --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---go-unhandled-exception.md @@ -0,0 +1,33 @@ +--- +title: Debug Go Unhandled Exception +description: Debug Go Unhandled Exception +ms.assetid: b9263b79-c8cb-4a3e-bf4e-f2e6673a8498 +keywords: ["Debug Go Unhandled Exception", "controlling the target, Debug Go Unhandled Exception", "exceptions, Debug Go Unhandled Exception"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Go Unhandled Exception + + +## + + +Click **Go Unhandled Exception** on the **Debug** menu to resume execution on the target and to treat the current exception as unhandled. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). For more information about exceptions and other events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Go%20Unhandled%20Exception%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---go.md b/windows-driver-docs-pr/debugger/debug---go.md new file mode 100644 index 0000000000..0a2fc34f27 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---go.md @@ -0,0 +1,35 @@ +--- +title: Debug Go +description: Debug Go +ms.assetid: d6b4bcb2-60f1-42ed-a125-8f754f2fd235 +keywords: ["Debug Go", "controlling the target, Debug Go"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Go + + +## + + +Click **Go** on the **Debug** menu to resume (or begin) execution on the target. This execution will continue until a breakpoint is reached, an exception or event occurs, the process ends, or the debugger breaks into the target. + +This command is equivalent to pressing F5 or clicking the **Go (F5)** button (![screen shot of the go button](images/tbgo.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Go%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-baud-rate.md b/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-baud-rate.md new file mode 100644 index 0000000000..4394a9ea15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-baud-rate.md @@ -0,0 +1,35 @@ +--- +title: Debug Kernel Connection Cycle Baud Rate +description: Debug Kernel Connection Cycle Baud Rate +ms.assetid: 5d7f13ff-738d-498c-88cb-ad2d6fe596ac +keywords: ["Debug Kernel Connection Cycle Baud Rate"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Kernel Connection | Cycle Baud Rate + + +## + + +Point to **Kernel Connection** and then click **Cycle Baud Rate** on the **Debug** menu to change the baud rate that is used in the kernel debugging connection. + +This command is equivalent to pressing CTRL+ALT+A. (You can also press CTRL+A in KD.) + +This command cycles through all available baud rates for the kernel debugging connection. Supported baud rates are 19200, 38400, 57600, and 115200. Every time that you use this command, the next baud rate is selected. If the baud rate is already at 115200, it is reduced to 19200. + +You cannot use this command to change the baud rate at which you are debugging. The baud rate of the host computer and the target computer must match, and you cannot change the baud rate of the target computer without restarting the computer. Therefore, you must change the baud rate only if the two computers are trying to communicate at different rates. In this case, you must change the host computer's baud rate to match that of the target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Kernel%20Connection%20|%20Cycle%20Baud%20Rate%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-initial-break.md b/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-initial-break.md new file mode 100644 index 0000000000..48798855a3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---kernel-connection---cycle-initial-break.md @@ -0,0 +1,48 @@ +--- +title: Debug Kernel Connection Cycle Initial Break +description: Debug Kernel Connection Cycle Initial Break +ms.assetid: e4dbb810-d9b3-4721-89ec-af4b5e244cc0 +keywords: ["Debug Kernel Connection Cycle Initial Break"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Kernel Connection | Cycle Initial Break + + +## + + +Point to **Kernel Conection** and then click **Cycle Initial Break** on the **Debug** menu to change the conditions on which the debugger automatically breaks into the target computer. + +This command is equivalent to pressing CTRL+ALT+K. (You can also press CTRL+K in KD.) + +This command causes the kernel debugger to cycle through the following three states: + +**No break** +The debugger does not break into the target computer unless you press [CTRL+BREAK](debug---break.md) or Debug | Break. + +**Break on reboot** +The debugger breaks into a restarted target computer after the kernel initializes. This command is equivalent to starting WinDbg with the -b [**command-line option**](windbg-command-line-options.md). + +**Break on first module load** +The debugger breaks into a restarted target computer after the first kernel module is loaded. (This action causes the break to occur earlier than in the **Break on reboot** state.) This command is equivalent to starting WinDbg with the -d [**command-line option**](windbg-command-line-options.md). + +When you use the **Cycle Initial Break** command, the new break state is displayed. + +### Additional Information + +For more information about related commands and an explanation of how the restart process affects the debugger, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Kernel%20Connection%20|%20Cycle%20Initial%20Break%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---kernel-connection---resynchronize.md b/windows-driver-docs-pr/debugger/debug---kernel-connection---resynchronize.md new file mode 100644 index 0000000000..3e0a64fc04 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---kernel-connection---resynchronize.md @@ -0,0 +1,37 @@ +--- +title: Debug Kernel Connection Resynchronize +description: Debug Kernel Connection Resynchronize +ms.assetid: b388dd9e-8d5c-4e29-8e81-a2be7c95437c +keywords: ["Debug Kernel Connection Resynchronize", "synchronizing with the target computer, Debug Kernel Connection Resynchronize"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Kernel Connection | Resynchronize + + +## + + +Point to **Kernel Connection** and then click **Resynchronize** on the **Debug** menu to cause the debugger to try to reestablish a kernel debugging connection with the target computer. + +This command is equivalent to pressing CTRL+ALT+R. (You can also press CTRL+R in KD.) + +Use this command if the target is not responding. + +### Additional Information + +For more information about reestablishing contact with the target, see [Synchronizing with the Target Computer](synchronizing-with-the-target-computer.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Kernel%20Connection%20|%20Resynchronize%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---modules.md b/windows-driver-docs-pr/debugger/debug---modules.md new file mode 100644 index 0000000000..66b2a50dc3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---modules.md @@ -0,0 +1,55 @@ +--- +title: Debug Modules +description: Debug Modules +ms.assetid: 4107ff36-31c4-45a6-95f6-b647543f01be +keywords: ["Debug Modules", "executable files and paths, Debug Modules"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Modules + + +## + + +Click **Modules** on the **Debug** menu to display the current list of loaded modules. + +### Dialog Box + +When you click **Modules**, the **Module List** dialog box appears. This dialog box lists all modules that are currently loaded into memory. + +**Module List** is divided into the following columns: + +- The **Name** column specifies the module name. + +- The **Start** and **End** columns specify the first and last address of the module's memory image. + +- The **Timestamp** column specifies the build date and time for the module. + +- The **Checksum** column specifies the checksum value. + +- The **Symbols** column displays information about the symbols that this module uses. For more information about the values that appear in this column, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). + +- The **Symbol file** column specifies the path and file name of the associated symbol file. If the debugger is unaware of any symbol file, the name of the executable file is given instead. + +If you click the title bar of a column, the display is sorted by the data in that column. If you click the title bar again, the sort order reverses. + +If you select a line and then click **Reload**, that module's symbol information is reloaded. + +If you select a line and press CTRL+C, the whole line is copied to the clipboard. + +Click **Close** to close this dialog box. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Modules%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---resolve-unqualified-symbols.md b/windows-driver-docs-pr/debugger/debug---resolve-unqualified-symbols.md new file mode 100644 index 0000000000..cce9adae72 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---resolve-unqualified-symbols.md @@ -0,0 +1,34 @@ +--- +title: Debug Resolve Unqualified Symbols +description: Debug Resolve Unqualified Symbols +ms.assetid: 8b935640-a01d-46e8-a9e4-08f20e293196 +keywords: ["Debug Resolve Unqualified Symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Resolve Unqualified Symbols + + +Select **Resolve Unqualified Symbols** on the **Debug** menu to resolve symbols that have no module prefix. + +If you clear **Resolve Unqualified Symbols**, the debugger cannot resolve symbols that have no module prefix. If you do not select **Resolve Unqualified Symbols** and a variable that has no prefix is not already loaded, the debugger does not load any additional symbols to resolve it. You can still use unqualified symbols when this option is clear, but only if they have been previously loaded. + +Although we always recommend that you use module qualifiers, you can clear the **Resolve Unqualified Symbols** option to avoid loading symbols that resolve incorrect or misspelled symbols when module qualifiers are not used. + +### Additional Information + +For more information about symbols, loading symbols, and verifying symbols, see [Symbols](symbols.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Resolve%20Unqualified%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---restart.md b/windows-driver-docs-pr/debugger/debug---restart.md new file mode 100644 index 0000000000..250f649966 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---restart.md @@ -0,0 +1,35 @@ +--- +title: Debug Restart +description: Debug Restart +ms.assetid: e529171a-0dd4-4528-a527-f8b430cd9321 +keywords: ["Debug Restart", "controlling the target, Debug Restart"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Restart + + +## + + +Click **Restart** on the **Debug** menu to stop the target's execution and end the target process and all its threads. This command then restarts the target execution at the beginning of the process. + +This command is equivalent to pressing CTRL+SHIFT+F5 or clicking the **Restart (Ctrl+Shift+F5)** button (![screen shot of the restart button](images/tbrestart.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). For more information about how to exit WinDbg or end the debugging session, see [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Restart%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---run-to-cursor.md b/windows-driver-docs-pr/debugger/debug---run-to-cursor.md new file mode 100644 index 0000000000..48f3611f97 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---run-to-cursor.md @@ -0,0 +1,35 @@ +--- +title: Debug Run to Cursor +description: Debug Run to Cursor +ms.assetid: 3d3d017b-e106-4eec-be0a-46c0db658744 +keywords: ["Debug Run to Cursor", "controlling the target, Debug Run to Cursor"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Run to Cursor + + +## + + +Click **Run to Cursor** on the **Debug** menu to resume running on the target. If you insert the cursor on an instruction in the [Disassembly window](disassembly-window.md) or a [Source window](source-window.md) and then execute this action, WinDbg executes all instructions from the current instruction up to the instruction you have selected. + +This command is equivalent to pressing F7 or CTRL+F10 or clicking the **Run to cursor (Ctrl+F10 or F7)** button (![screen shot of the run to cursor button](images/tbcursor.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Run%20to%20Cursor%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---source-mode.md b/windows-driver-docs-pr/debugger/debug---source-mode.md new file mode 100644 index 0000000000..45418e3c21 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---source-mode.md @@ -0,0 +1,39 @@ +--- +title: Debug Source Mode +description: Debug Source Mode +ms.assetid: 51fd8b6c-9bd9-42ed-a5fa-0098b3f0fea2 +keywords: ["Debug Source Mode", "source debugging, Debug Source Mode", "assembly debugging, Debug Source Mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Source Mode + + +## + + +Select **Source Mode** on the **Debug** menu to switch the debugger to source mode. Clear **Source Mode** to switch the debugger to assembly mode. + +You can click the **Source mode on** button (shown on the left in the following figure) to change the debugger to source mode or click the **Source mode off** button (shown on the right in the following figure) to change the debugger to assembly mode. + +![screen shot of the source mode buttons](images/tbsrcasm.png) + +When source mode is active, ASM is unavailable on the status bar. When assembly mode is active, ASM is displayed on the status bar. + +### Additional Information + +For more information about source-mode debugging, see [Debugging in Source Mode](debugging-in-source-mode.md). For more information about assembly-mode debugging, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Source%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---step-into.md b/windows-driver-docs-pr/debugger/debug---step-into.md new file mode 100644 index 0000000000..35d496592b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---step-into.md @@ -0,0 +1,35 @@ +--- +title: Debug Step Into +description: Debug Step Into +ms.assetid: 809a14f8-7280-46d3-b113-7b1808c13d0f +keywords: ["Debug Step Into", "controlling the target, Debug Step Into"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Step Into + + +## + + +Click **Step Into** on the **Debug** menu to execute a single instruction on the target. If the instruction is a function call, the debugger steps into the function. + +This command is equivalent to pressing F11 or F8 or clicking the **Step into (F11 or F8)** button (![screen shot of the step into button](images/tbinto.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Step%20Into%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---step-out.md b/windows-driver-docs-pr/debugger/debug---step-out.md new file mode 100644 index 0000000000..fa75b06520 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---step-out.md @@ -0,0 +1,35 @@ +--- +title: Debug Step Out +description: Debug Step Out +ms.assetid: 628a9f15-745a-4502-9999-a9139d4a91de +keywords: ["Debug Step Out", "controlling the target, Debug Step Out"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Step Out + + +## + + +Click **Step Out** on the **Debug** menu to resume running on the target. This command executes the rest of the current function and breaks when the function return is completed. + +This command is equivalent to pressing SHIFT+F11 or clicking the **Step out (Shift+F11)** button (![screen shot of the step out button](images/tbout.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Step%20Out%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---step-over.md b/windows-driver-docs-pr/debugger/debug---step-over.md new file mode 100644 index 0000000000..482613c43c --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---step-over.md @@ -0,0 +1,35 @@ +--- +title: Debug Step Over +description: Debug Step Over +ms.assetid: e4ae98bc-ffa4-4126-9914-7aa53dba2856 +keywords: ["Debug Step Over", "controlling the target, Debug Step Over"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Step Over + + +## + + +Click **Step Over** on the **Debug** menu to execute a single instruction on the target. If the instruction is a function call, the whole function is executed. + +This command is equivalent to pressing F10 or clicking the **Step over (F10)** button (![screen shot of the step over button](images/tbover.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Step%20Over%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug---stop-debugging.md b/windows-driver-docs-pr/debugger/debug---stop-debugging.md new file mode 100644 index 0000000000..c9520f8504 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug---stop-debugging.md @@ -0,0 +1,35 @@ +--- +title: Debug Stop Debugging +description: Debug Stop Debugging +ms.assetid: 40c8a266-ffea-488e-ac10-89e61c5c9781 +keywords: ["Debug Stop Debugging", "controlling the target, Debug Stop Debugging", "exiting the debugger, Debug Stop Debugging", "quitting the debugger, Debug Stop Debugging", "ending the debugging session, Debug Stop Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug | Stop Debugging + + +## + + +Click **Stop Debugging** on the **Debug** menu to stop the target's execution and end the target process and all its threads. This action enables you to start to debug a different target application. + +This command is equivalent to pressing SHIFT+F5 or clicking the **Stop debugging (Shift+F5)** button (![screen shot of the stop debugging button](images/tbstop.png)) on the toolbar. + +### Additional Information + +For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see [Controlling the Target](controlling-the-target.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20|%20Stop%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug-initial-command.md b/windows-driver-docs-pr/debugger/debug-initial-command.md new file mode 100644 index 0000000000..c5e92ffbf4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-initial-command.md @@ -0,0 +1,66 @@ +--- +title: Debug initial command +description: Debug initial command +ms.assetid: 0af0b53d-455f-4cdb-b956-9d7e49601733 +keywords: ["Debug initial command (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug initial command + + +## + + +The **Debug initial command** flag debugs the Client Server Run-time Subsystem (CSRSS) and the WinLogon process. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dic

Hexadecimal value

0x4

Symbolic Name

FLG_DEBUG_INITIAL_COMMAND

Destination

System-wide registry entry, kernel flag

+ +  + +### Comments + +NTSD debugs the processes (using the command **ntsd -d**), but control is redirected to the kernel debugger. + +For details on NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + +### See Also + +[Enable debugging of Win32 subsystem](enable-debugging-of-win32-subsystem.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20initial%20command%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug-menu.md b/windows-driver-docs-pr/debugger/debug-menu.md new file mode 100644 index 0000000000..ca8ac6ecf9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-menu.md @@ -0,0 +1,65 @@ +--- +title: Debug Menu +description: Debug Menu +ms.assetid: 52bad9c4-91e8-48e8-a6b6-41208ca0aa6b +keywords: ["Debug Menu (complete listing)", "graphical interface, debug menu"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug Menu + + +## + + +This section describes the following commands on the **Debug** menu of WinDbg: + +[Debug | Go](debug---go.md) + +[Debug | Go Unhandled Exception](debug---go-unhandled-exception.md) + +[Debug | Go Handled Exception](debug---go-handled-exception.md) + +[Debug | Restart](debug---restart.md) + +[Debug | Stop Debugging](debug---stop-debugging.md) + +[Debug | Detach Debuggee](debug---detach-debuggee.md) + +[Debug | Break](debug---break.md) + +[Debug | Step Into](debug---step-into.md) + +[Debug | Step Over](debug---step-over.md) + +[Debug | Step Out](debug---step-out.md) + +[Debug | Run to Cursor](debug---run-to-cursor.md) + +[Debug | Source Mode](debug---source-mode.md) + +[Debug | Resolve Unqualified Symbols](debug---resolve-unqualified-symbols.md) + +[Debug | Event Filters](debug---event-filters.md) + +[Debug | Modules](debug---modules.md) + +[Debug | Kernel Connection | Cycle Baud Rate](debug---kernel-connection---cycle-baud-rate.md) + +[Debug | Kernel Connection | Cycle Initial Break](debug---kernel-connection---cycle-initial-break.md) + +[Debug | Kernel Connection | Resynchronize](debug---kernel-connection---resynchronize.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug-privilege.md b/windows-driver-docs-pr/debugger/debug-privilege.md new file mode 100644 index 0000000000..b4b33ed818 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-privilege.md @@ -0,0 +1,80 @@ +--- +title: Debug Privilege +description: The debug privilege allows someone to debug a process that they wouldn’t otherwise have access to. +ms.assetid: f3ea9065-6d04-4629-88ed-85428f7915ca +keywords: ["debug privilege", "debug privilege, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug Privilege + + +The debug privilege allows someone to debug a process that they wouldn’t otherwise have access to. For example, a process running as a user with the debug privilege enabled on its token can debug a service running as local system. + +## + + +Debug privilege is a security policy setting that allows users to attach a debugger to a process or to the kernel. An administrator can modify a security policy for a user group to include or to remove this functionality. Developers who are debugging their own applications do not need this user privilege. Developers who are debugging system components or who are debugging remote components will need this user privilege. This user privilege provides complete access to sensitive and critical operating system components. By default, this property is enabled for users with Administrator rights. A user with Administrator privileges can enable this property for other user groups. + +### Modifying Debug Privilege for a Process + +The following code example shows how to enable the debug privilege in your process. This enables you to debug other processes that you wouldn't have access to otherwise. + +``` +// +// SetPrivilege enables/disables process token privilege. +// +BOOL SetPrivilege(HANDLE hToken, LPCTSTR lpszPrivilege, BOOL bEnablePrivilege) +{ + LUID luid; + BOOL bRet=FALSE; + + if (LookupPrivilegeValue(NULL, lpszPrivilege, &luid)) + { + TOKEN_PRIVILEGE tp; + + tp.PrivilegeCount=1; + tp.Privileges[0].Luid=luid; + tp.Privileges[0].Attributes=(bEnablePrivilege) ? SE_PRIVILEGE_ENABLED: 0; + // + // Enable the privilege or disable all privileges. + // + if (AdjustTokenPrivileges(hToken, FALSE, &tp, NULL, (PTOKEN_PRIVILEGES)NULL, (PDWORD)NULL)) + { + // + // Check to see if you have proper access. + // You may get "ERROR_NOT_ALL_ASSIGNED". + // + bRet=(GetLastError() == ERROR_SUCCESS); + } + } + return bRet; +} +``` + +The following example shows how to use this function: + +``` +HANDLE hProcess=GetCurrentProcess(); +HANDLE hToken; + +if (OpenProcessToken(hProcess, TOKEN_ADJUST_PRIVILEGES, &hToken)) +{ + SetPrivilege(hToken, SE_DEBUG_NAME, TRUE); + CloseHandle(hToken); +} +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20Privilege%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md b/windows-driver-docs-pr/debugger/debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md new file mode 100644 index 0000000000..1d81c81ef8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md @@ -0,0 +1,1472 @@ +--- +title: Debug Universal Drivers - Step-by-Step Lab (Echo Kernel Mode) +description: This lab introduces the WinDbg kernel debugger. WinDbg is used to debug the echo kernel mode sample driver code. +ms.assetid: 3FBC3693-4288-42BA-B1E8-84DC2A9AFFD9 +keywords: ["debug lab", "step-by-step", "ECHO"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode) + + +This lab introduces the WinDbg kernel debugger. WinDbg is used to debug the echo kernel mode sample driver code. + +## Lab objectives + + +This lab includes exercises that introduce the debugging tools, teach common debugging commands, illustrate the use of break points, and show the use of the debugging extensions. + +In this lab, a live kernel debug connection is used to explore the following: + +- Use the Windows debugger commands +- Use standard commands (Call stacks, variables, threads, IRQL) +- Use advanced driver debugging commands (!commands) +- Use symbols +- Set breakpoints in live debugging +- View call stacks +- Display the Plug and Play device tree +- Work with thread and process context + +**Note**  When working with the Windows debugger, there are two types of debugging that can be performed - user or kernel mode debugging. +*User mode* - Applications and subsystems run on the computer in user mode. Processes that run in user mode do so within their own virtual address spaces. They are restricted from gaining direct access to many parts of the system, including system hardware, memory that was not allocated for their use, and other portions of the system that might compromise system integrity. Because processes that run in user mode are effectively isolated from the system and other user mode processes, they cannot interfere with these resources. + +*Kernel mode* - Kernel mode is the processor access mode in which the operating system and privileged programs run. Kernel mode code has permission to access any part of the system, and is not restricted like user mode code. It can gain access to any part of any other process running in either user mode or kernel mode. Much of the core OS functionality and many hardware device drivers run in kernel mode. + +This lab will focus on kernel mode debugging, as that is the method used to debug many device drivers. + +  + +This exercise covers debug commands that are frequently used during both user-mode and kernel-mode debugging. The exercise also covers debug extensions (sometimes called "!commands") that are used for kernel-mode debugging. + +## Lab setup + + +You will need the following hardware to be able to complete the lab. + +- A laptop or desktop computer (host) running Windows 10 +- A laptop or desktop computer (target) running Windows 10 +- A network cross over cable or a network hub and network cables to connect the two PCs +- Access to the internet to download symbol files + +You will need the following software to be able to complete the lab. + +- Visual Studio 2015 +- Windows Software Development Kit (SDK) for Windows 10 +- Windows Driver Kit (WDK) for Windows 10 +- The sample echo driver for Windows 10 + +The lab has the following eleven sections. + +- [Section 1: Connect to a kernel mode WinDbg session](#connectto) +- [Section 2: Kernel mode debugging commands and techniques](#kernelmodedebuggingcommandsandtechniques) +- [Section 3: Download and build the KMDF Universal Echo Driver](#download) +- [Section 4: Install the KMDF Echo driver sample on the target system](#install) +- [Section 5: Use WinDbg to display information about the driver](#usewindbgtodisplayinformation) +- [Section 6: Display Plug and Play device tree information](#displayingtheplugandplaydevicetree) +- [Section 7: Work with breakpoints and source code](#workingwithbreakpoints) +- [Section 8: View variables and call stacks](#viewingvariables) +- [Section 9: Display processes and threads](#displayingprocessesandthreads) +- [Section 10: IRQL, Registers and Ending the WinDbg session](#irqlregistersmemory) +- [Section 11: Windows debugging resources](#windowsdebuggingresources) + +## Section 1: Connect to a kernel mode WinDbg session + + +*In Section 1, you will configure network debugging on the host and target system.* + +The PCs in this lab need to be configured to use an Ethernet network connection for kernel debugging. + +This lab uses two PCs. Windows debugger runs on the *host* system and the KMDF Echo driver runs on the *target* system. + +The "<-Host" on the left is connected using a cross over ethernet cable to the "->Target" on the right. + +The steps in the lab assume that you are using a cross over network cable, but the lab should also work if you can plug both the host and the target directly into a network hub. + +![two pcs connected with a double arrow](images/debuglab-image-targethostdrawing1.png) + +To work with kernel mode applications and use WinDbg, we recommend that you use the KDNET over Ethernet transport. For information about how to use the Ethernet transport protocol, see [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md). For more information about setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](https://msdn.microsoft.com/windows-drivers/develop/preparing_a_computer_for_manual_driver_deployment) and [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md). + +### Configure kernel–mode debugging using a crossover ethernet cable + +To enable kernel mode debugging on the target system, perform the following steps. + +**<- On the host system** + +1. Open a command prompt on the host system and type **ipconfig** to determine its IP address. +``` +C:\>ipconfig +Windows IP Configuration +Ethernet adapter Ethernet: + Connection-specific DNS Suffix . : + Link-local IPv6 Address . . . . . : fe80::c8b6:db13:d1e8:b13b%3 + Autoconfiguration IPv4 Address. . : 169.182.1.1 + Subnet Mask . . . . . . . . . . . : 255.255.0.0 + Default Gateway . . . . . . . . . : +``` + +2. Record the IP address of the host system: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +**-> On the target system** + +3. Open a command prompt on the target system and use the **ping** command to confirm network connectivity between the two systems. Use the IP address of the host system you recorded instead of the one shown in the sample output. + +``` +C:\> ping 169.182.1.1 + +Pinging 169.182.1.1 with 32 bytes of data: +Reply from 169.182.1.1: bytes=32 time=1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 + +Ping statistics for 169.182.1.1: + Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), +Approximate round trip times in milli-seconds: + Minimum = 0ms, Maximum = 1ms, Average = 0ms +``` + +Enable kernel mode debugging on the target system by completing the following steps. + +1. On the target computer, open a Command Prompt window as Administrator. Enter this command to enable debugging. +``` +C:\> bcdedit /set {default} DEBUG YES +``` + +2. Type this command to enable test signing. +``` +C:\> bcdedit /set TESTSIGNING ON +``` + +3. Type this command to set the IP address of the host system. Use the IP address of the host system that you recorded earlier, not the one shown. +``` +C:\> bcdedit /dbgsettings net hostip:192.168.1.1 port:50000 key:1.2.3.4 +``` + +**Warning**  To increase the security of the connection and decrease the risk of the random client debugger connection requests, consider using an auto generated random key. For more information, see [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md). + +4. Type this command to confirm that the dbgsettings they are set properly. + +``` +C:\> bcdedit /dbgsettings +key 1.2.3.4 +debugtype NET +hostip 169.168.1.1 +port 50000 +dhcp Yes +The operation completed successfully. +``` + +**Note**   +**Firewalls and debuggers** + +If you receive a pop-up message from the firewall, and you wish to use the debugger, unblock the types of networks that you desire. + +![windows security alert - windows firewall has blocked some features of this app ](images/debuglab-image-firewall-dialog-box.png) + +  + +**<- On the host system** + +1. On the host computer, open a Command Prompt window as Administrator. Change to the WinDbg.exe directory. We will use the x64version of WinDbg.exe from the Windows Driver Kit (WDK) that was installed as part of the Windows kit installation. +``` +C:\> Cd C:\Program Files(x86)\Windows Kits\10\Debuggers\x64 +``` + +2. Launch WinDbg with remote user debug using the following command. The value for the key and port match what we set earlier using BCDEdit on the target. +``` +WinDbg –k net:port=50000,key=1.2.3.4 +``` + +**->On the target system** + +Reboot the target system. + +**<-On the host system** + +In a minute or two, debug output should be displayed on the host system. + +![windows debugger showing command window output from a live kernel connection](images/debuglab-image-winddbg-hh.png) + +The Debugger Command window is the primary debugging information window in WinDbg. You can enter debugger commands and view the command output in this window. + +The Debugger Command window is split into two panes. You type commands in the smaller pane (the command entry pane) at the bottom of the window and view the command output in the larger pane at the top of the window. + +In the command entry pane, use the up arrow and down arrow keys to scroll through the command history. When a command appears, you can edit it or press **ENTER** to run the command. + +### Section 2: Kernel mode debugging commands and techniques + + +*In Section 2, you will use debug commands to display information about the target system.* + +**<- On the host system** + +**Enable Debugger Markup Language (DML) with .prefer\_dml** + +Some debug commands display text using Debugger Markup Language that you can click on to quickly gather more information. + +1. Use Ctrl+Break (Scroll Lock) in WinDBg to break into the code running on the target system. It may take a bit of time for the target system to respond. + +2. Type the following command to enable DML in the Debugger Command window. + +``` +0: kd> .prefer_dml 1 +DML versions of commands on by default +``` + +**Use .hh to get help** + +You can access reference command help using the **.hh** command. + +3. Type the following command to view the command reference help for **.prefer\_dml**. + +``` +0: kd> .hh .prefer_dml +``` + +The Debugger help file will display help for the **.prefer\_dml** command. + +![debugger help application showing help for the .prefer\-dml command](images/debuglab-image-prefer-dml-help.png) + +**Display the version of Windows on the target system** + +5. Display detailed version information on the target system by typing the [**vertarget (Show Target Computer Version)**](vertarget--show-target-computer-version-.md) command in the WinDbg window. + +``` +0: kd> vertarget +Windows 10 Kernel Version 9926 MP (4 procs) Free x64 +Product: WinNt, suite: TerminalServer SingleUserTS +Built by: 9926.0.amd64fre.fbl_awesome1501.150119-1648 +Machine Name: "" +Kernel base = 0xfffff801`8d283000 PsLoadedModuleList = 0xfffff801`8d58aef0 +Debug session time: Fri Feb 20 10:15:17.807 2015 (UTC - 8:00) +System Uptime: 0 days 01:31:58.931 +``` + +**List the loaded modules** + +6. You can verify that you are working with the right kernel mode process by displaying the loaded modules by typing the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command in the WinDbg window. + +``` +0: Kd> lm +start end module name +fffff801`09200000 fffff801`0925f000 volmgrx (no symbols) +fffff801`09261000 fffff801`092de000 mcupdate_GenuineIntel (no symbols) +fffff801`092de000 fffff801`092ec000 werkernel (export symbols) werkernel.sys +fffff801`092ec000 fffff801`0934d000 CLFS (export symbols) CLFS.SYS +fffff801`0934d000 fffff801`0936f000 tm (export symbols) tm.sys +fffff801`0936f000 fffff801`09384000 PSHED (export symbols) PSHED.dll +fffff801`09384000 fffff801`0938e000 BOOTVID (export symbols) BOOTVID.dll +fffff801`0938e000 fffff801`093f7000 spaceport (no symbols) +fffff801`09400000 fffff801`094cf000 Wdf01000 (no symbols) +fffff801`094d9000 fffff801`09561000 CI (export symbols) CI.dll +... +``` + +**Note**  Output that has been omitted is indicated with "… " in this lab. + +  + +7. To request detailed information about a specific module, use the v (verbose) option as shown. + +``` +0: Kd> lm v m tcpip +Browse full module list +start end module name +fffff801`09eeb000 fffff801`0a157000 tcpip (no symbols) + Loaded symbol image file: tcpip.sys + Image path: \SystemRoot\System32\drivers\tcpip.sys + Image name: tcpip.sys + Browse all global symbols functions data + Timestamp: Sun Nov 09 18:59:03 2014 (546029F7) + CheckSum: 00263DB1 + ImageSize: 0026C000 + Translations: 0000.04b0 0000.04e4 0409.04b0 0409.04e4 + +Unable to enumerate user-mode unloaded modules, Win32 error 0n30 +``` + +8. Because we have yet to set the symbol path and loaded symbols, limited information is available in the debugger. + +### Section 3: Download and build the KMDF universal echo driver + +*In Section 3, you will download and build the KMDF universal echo driver.* + +Typically, you would be working with your own driver code when you use WinDbg. To become familiar with WinDbg operation, the KMDF Template "Echo" sample driver is used. With the source code available, it will also be easier to understand the information that is displayed in WinDbg. In addition, this sample is used to illustrate how you can single step through native kernel mode code. This technique can be very valuable for debugging complex kernel mode code issues. + +To download and build the Echo sample audio driver, perform the following steps. + +1. **Download and extract the KMDF Echo sample from GitHub** + + You can use a browser to view the echo sample in GitHub here: + + [https://github.com/Microsoft/Windows-driver-samples/tree/97cf5197cf5b882b2c689d8dc2b555f2edf8f418/general/echo/kmdf](https://github.com/Microsoft/Windows-driver-samples/blob/97cf5197cf5b882b2c689d8dc2b555f2edf8f418/general/echo/kmdf/ReadMe.md) + + You can read about the sample here: + + + + You can browse all of the universal driver samples here: + + + + The KMDF Echo sample is located in the general folder. + + ![github windows-driver-samples highlighting the general folder and the download zip button](images/debuglab-image-github.png) + + a. This lab, shows how to download the universal driver samples in one zip file. + + + + b. Download the master.zip file to your local hard drive. + + c. Right-click *Windows-driver-samples-master.zip*, and choose **Extract All**. Specify a new folder, or browse to an existing one that will store the extracted files. For example, you could specify *C:\\DriverSamples\\* as the new folder into which the files are extracted. + + d. After the files are extracted, navigate to the following subfolder. + + *C:\\DriverSamples\\general\\echo\\kmdf* + +2. **Open the driver solution in Visual Studio** + + In Microsoft Visual Studio, click **File** > **Open** > **Project/Solution...** and navigate to the folder that contains the extracted files (for example, *C:\\DriverSamples\\general\\echo\\kmdf*). Double-click the *kmdfecho* solution file to open it. + + In Visual Studio, locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has three projects. + + ![visual studio with the device.c file loaded from the kmdfecho project](images/debuglab-image-echo-visual-studio.png) + +3. **Set the sample's configuration and platform** + + In Solution Explorer, right-click **Solution 'kmdfecho' (3 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the three projects. By default, the configuration is set to "Win10 Debug", and the platform is set to "Win64" for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for the remaining three projects. + +4. **Set the runtime library** + + Set the runtime library - Change Runtime Library from DLL version to non DLL version. Without this setting, you have to install the MSVC runtime to the target computer separately. + + ![echo property page highlighting the runtime library setting](images/debuglab-image-echoapp-properties.png) + +5. **Check driver signing** + + Open the echo driver’s property page and make sure **Driver Signing** > **Sign Mode** is set to “Test Sign”. This is required because Windows requires that drivers are signed. + + ![echo property page highlighting the sign mode setting](images/debuglab-image-echoapp-driver-signing.png) + +6. **Build the sample using Visual Studio** + + In Visual Studio, click **Build** > **Build Solution**. + + If all goes well, the build windows should display a message indicating that the build for all three projects succeeded. + +7. **Locate the built driver files** + + In File Explorer, navigate to the folder that contains the extracted files for the sample. For example, you would navigate to *C:\\DriverSamples\\general\\echo\\kmdf*, if that's the folder you specified earlier. Within that folder, the location of the compiled driver files varies depending on the configuration and platform settings that you selected in the **Configuration Manager**. For example, if you left the default settings unchanged, then the compiled driver files will be saved to a folder named *\\x64\\Debug* for a 64 bit, debug build. + + Navigate to the folder that contains the built files for the Autosync driver: + + *C:\\DriverSamples\\general\\echo\\kmdf\\driver\\AutoSync\\x64\\Debug*. The folder should contain these files: + + | File | Description | + |----------|-----------------------------------------------------------------------------------| + | Echo.sys | The driver file. | + | Echo.inf | An information (INF) file that contains information needed to install the driver. | + +   + + In addition, the echoapp.exe file was built and it should be located here: *C:\\DriverSamples\\general\\echo\\kmdf\\exe\\x64\\Debug* + + | File | Description | + |-------------|-----------------------------------------------------------------------------------| + | EchoApp.exe | A command prompt executable test file that communicates with the echo.sys driver. | + +   + +8. Locate a USB thumb drive or set up a network share to copy the built driver files and the test EchoApp from the host to the target system. + +In the next section, you will copy the code to the target system, and install and test the driver. + +### Section 4: Install the KMDF echo driver sample on the target system + +*In Section 4, you will use devcon to install the echo sample driver.* + +**-> On the target system** + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically, this is a separate computer from the computer on which you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the sample echo driver, automatically or manually. + +Before you manually deploy a driver, you must prepare the target computer by turning on test signing. You also need to locate the DevCon tool in your WDK installation. After that you’re ready to run the built driver sample. + +To install the driver on the target system, perform the following steps. + +**Enable test signed drivers** + +Enable the ability to run test signed drivers: + +a. Open Windows Settings. +b. In Update and Security, select **Recovery**. +c. Under Advanced startup, click **Restart Now**. +d. When the PC reboots, select **Startup options**. +e. Select Disable driver signature enforcement by pressing the **F7** key. +f. Reboot the target computer. +**<- On the host system** + +Navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder: + +*C:\\Program Files (x86)\\Windows Kits\\10.0\\Tools\\x64\\devcon.exe* +Create a folder on the target for the built driver package (for example, *C:\\EchoDriver*). Copy all the files from the built driver described earlier on the host computer and save them to the folder that you created on the target computer. + +Locate the .cer certificate on the host system, it is in the same folder on the host computer in the folder that contains the built driver files. On the target computer, right-click the certificate file, and click **Install**, then follow the prompts to install the test certificate. + +If you need more detailed instructions for setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](https://msdn.microsoft.com/windows-drivers/develop/preparing_a_computer_for_manual_driver_deployment). + +**-> On the target system** + +**Install the driver** + +The following instructions show you how to install and test the sample driver. Here's the general syntax for the devcon tool that you will use to install the driver: + +*devcon install <INF file> <hardware ID>* + +The INF file required for installing this driver is *echo.inf*. The inf file contains the hardware ID for installing the *echo.sys*. For the echo sample the hardware ID is **root\\ECHO**. + +On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: + +**devcon install echo.inf root\\ECHO** +If you get an error message about *devcon* not being recognized, try adding the path to the *devcon* tool. For example, if you copied it to a folder called *C:\\Tools*, then try using the following command: + +**c:\\tools\\devcon install echo.inf root\\ECHO** +A dialog box will appear indicating that the test driver is an unsigned driver. Click **Install this driver anyway** to proceed. + +![windows security warning - windows can't verify the publisher of this driver software](images/debuglab-image-install-security-warning.png) + +For more detailed instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/library/windows/hardware/hh698272.aspx). + +After successfully installing the sample driver, you're now ready to test it. + +**Examine the driver in Device Manager** + +On the target computer, in a Command Prompt window, enter **devmgmt** open Device Manager. In Device Manager, on the View menu, choose Devices by type. In the device tree, locate *Sample WDF Echo Driver* in the Sample Device node. + +![device manager tree with the sample wdf echo driver highlighted](images/debuglab-image-device-manager-echo.png) + +**Test the driver** + +Type **echoapp** to start the test echo app to confirm that the driver is functional. + +``` +C:\Samples\KMDF_Echo_Sample> echoapp +DevicePath: \\?\root#sample#0005#{cdc35b6e-0be4-4936-bf5f-5537380a7c1a} +Opened device successfully +512 Pattern Bytes Written successfully +512 Pattern Bytes Read successfully +Pattern Verified successfully +30720 Pattern Bytes Written successfully +30720 Pattern Bytes Read successfully +Pattern Verified successfully +``` + +### Section 5: Use WinDbg to display information about the driver + +*In Section 5, you will set the symbol path and use kernel debugger commands to display information about the KMDF echo sample driver.* + +View information about the driver by performing the following steps. + +**<-On the host system** + +1. If you closed the debugger, open it again using the following command in the administrator command prompt window. + + ``` + WinDbg -k net:port=50000,key=1.2.3.4 + ``` + +2. Use Ctrl+Break (Scroll Lock) to break into the code running on the target system. + +**Setting the symbol path** + +1. To set the symbols path to the Microsoft symbol server in the WinDbg environment, use the **.symfix** command. + + ``` + 0: kd> .symfix + ``` + +2. To add your local symbol location to use your local symbols, add the path using **.sympath+** and then **.reload /f**. + + ``` + 0: kd> .sympath+ C:\DriverSamples\general\echo\kmdf + 0: kd> .reload /f + ``` + + **Note**  The **.reload** command with the **/f** force option deletes all symbol information for the specified module and reloads the symbols. In some cases, this command also reloads or unloads the module itself. + +   + +**Note**  You must load the proper symbols to use advanced functionality that WinDbg provides. If you do not have symbols properly configured, you will receive messages indicating that symbols are not available when you attempt to use functionality that is dependent on symbols. +``` +0:000> dv +Unable to enumerate locals, HRESULT 0x80004005 +Private symbols (symbols.pri) are required for locals. +Type “.hh dbgerr005” for details. +``` + +  + +**Note**   +**Symbol servers** + +There are a number of approaches that can be used to work with symbols. In many situations, you can configure the PC to access symbols from a symbol server that Microsoft provides when they are needed. This walkthrough assumes that this approach will be used. If the symbols in your environment are in a different location, modify the steps to use that location. For additional information, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +  + +**Note**   +**Understand source code symbol requirements** + +To perform source debugging, you must build a checked (debug) version of your binaries. The compiler will create symbol files (.pdb files). These symbol files will show the debugger how the binary instructions correspond to the source lines. The actual source files themselves must also be accessible to the debugger. + +The symbol files do not contain the text of the source code. For debugging, it is best if the linker does not optimize your code. Source debugging and access to local variables are more difficult, and sometimes nearly impossible, if the code has been optimized. If you are having problems viewing local variables or source lines, set the following build options: + +``` +set COMPILE_DEBUG=1 +set ENABLE_OPTIMIZER=0 +``` + +  + +1. Type the following in the command area of the debugger to display information about the echo driver : + + ``` + 0: kd> lm m echo* v + Browse full module list + start end module name + fffff801`4ae80000 fffff801`4ae89000 ECHO (private pdb symbols) C:\Samples\KMDF_ECHO_SAMPLE\echo.pdb + Loaded symbol image file: ECHO.sys + Image path: \SystemRoot\system32\DRIVERS\ECHO.sys + Image name: ECHO.sys + ... + ``` + + For information, see [**lm**](lm--list-loaded-modules-.md). + +2. Because we set prefer\_dml =1 earlier, some elements of the output are hot links that you can click on. Click on the *Browse all global symbols link* in the debug output to display information about items symbols that start with the letter “a”. + + ``` + 0: kd> x /D Echo!a* + ``` + +3. As it turns out, the echo sample doesn’t contain any symbols that start with the letter “a”, so to display information about all of the symbols associated with echo driver that start with Echo, type **x ECHO!Echo\***. + + ``` + 0: kd> x ECHO!Echo* + fffff801`0bf95690 ECHO!EchoEvtIoQueueContextDestroy (void *) + fffff801`0bf95000 ECHO!EchoEvtDeviceSelfManagedIoStart (struct WDFDEVICE__ *) + fffff801`0bf95ac0 ECHO!EchoEvtTimerFunc (struct WDFTIMER__ *) + fffff801`0bf9b120 ECHO!EchoEvtDeviceSelfManagedIoSuspend (struct WDFDEVICE__ *) + ... + ``` + + For information, see [**x (Examine Symbols)**](x--examine-symbols-.md). + +4. The **!lmi** extension displays detailed information about a module. Type **!lmi echo**. Your output should be similar to the text shown below. + + ``` + 0: kd> !lmi echo + Loaded Module Info: [echo] + Module: ECHO + Base Address: fffff8010bf94000 + Image Name: ECHO.sys + … + ``` + +5. Use the **!dh** extension to display header information as shown below. + + ``` + 0: kd> !dh echo + + File Type: EXECUTABLE IMAGE + FILE HEADER VALUES + 14C machine (i386) + 6 number of sections + 54AD8A42 time date stamp Wed Jan 07 11:34:26 2015 + ... + ``` + +6. **Setting the debug mask** + + Type the following to change the default debug bit mask so that all debug messages from the target system will be displayed in the debugger. + + ``` + 0: kd> !ed nt!Kd_DEFAULT_MASK 0xFFFFFFFF + ``` + + Some drivers will display additional information when the mask of 0xFFFFFFFF is used. Set the mask to 0x00000000 if you would like to reduce the amount of information that is displayed. + + ``` + 0: kd> !ed nt!Kd_DEFAULT_MASK 0x00000000 + ``` + +### Section 6: Displaying Plug and Play device tree information + +*In Section 6, you will display information about the echo sample device driver and where it lives in the Plug and Play device tree.* + +Information about the device driver in the Plug and Play device tree can be useful for troubleshooting. For example, if a device driver is not resident in the device tree, there may an issue with the installation of the device driver. + +For more information about the device node debug extension, see [**!devnode**](-devnode.md). + +**<-On the host system** + +1. To see all the device nodes in the Plug and Play device tree, enter the **!devnode 0 1** command. + + ``` + 0: kd> !devnode 0 1 + Dumping IopRootDeviceNode (= 0xffffe0005a3a8d30) + DevNode 0xffffe0005a3a8d30 for PDO 0xffffe0005a3a9e50 + InstancePath is "HTREE\ROOT\0" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe0005a3a3d30 for PDO 0xffffe0005a3a4e50 + InstancePath is "ROOT\volmgr\0000" + ServiceName is "volmgr" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe0005a324560 for PDO 0xffffe0005bd95ca0… + … + ``` + +2. Use Ctrl+F to search in the output that is generated to look for the name of the device driver, *echo*. + + ![find dialog box showing the term echo being searched for](images/debuglab-image-find-dialog.png) + +3. The echo device driver should be loaded. Use the **!devnode 0 1 echo** command to display Plug and Play information associated with our echo device driver as shown below. + + ``` + 0: Kd> !devnode 0 1 echo + Dumping IopRootDeviceNode (= 0xffffe0007b725d30) + DevNode 0xffffe0007b71a630 for PDO 0xffffe0007b71a960 + InstancePath is "ROOT\SAMPLE\0000" + ServiceName is "ECHO" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + … + ``` + +4. The output displayed in the previous command includes the PDO associated with the running instance of our driver, in this example it is *0xffffe0007b71a960*. Enter the **!devobj***<PDO address>* command to display Plug and Play information associated with the echo device driver. Use the PDO address that **!devnode** displays on your PC, not the one shown here. + + ``` + 0: kd> !devobj 0xffffe0007b71a960 + Device object (ffffe0007b71a960) is for: + 0000000e \Driver\PnpManager DriverObject ffffe0007b727e60 + Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040 + Dacl ffffc102c9b36031 DevExt 00000000 DevObjExt ffffe0007b71aab0 DevNode ffffe0007b71a630 + ExtensionFlags (0x00000800) DOE_DEFAULT_SD_PRESENT + Characteristics (0x00000180) FILE_AUTOGENERATED_DEVICE_NAME, FILE_DEVICE_SECURE_OPEN + AttachedDevice (Upper) ffffe000801fee20 \Driver\ECHO + Device queue is not busy. + ``` + +5. The output displayed in the **!devnode 0 1** command includes the PDO address associated with the running instance of our driver, in this example it is *0xffffe0007b71a960*. Enter the **!devstack***<PDO address>* command to display Plug and Play information associated with the device driver. Use the PDO address that **!devnode** displays on your PC, not the one shown below. + + ``` + 0: kd> !devstack 0xffffe0007b71a960 + !DevObj !DrvObj !DevExt ObjectName + ffffe000801fee20 \Driver\ECHO ffffe0007f72eff0 + > ffffe0007b71a960 \Driver\PnpManager 00000000 0000000e + !DevNode ffffe0007b71a630 : + DeviceInst is "ROOT\SAMPLE\0000" + ServiceName is "ECHO" + ``` + +The output shows that we have a fairly simple device driver stack. The echo driver is a child of the PnPManager node. The PnPManager is a root node. + +``` +\Driver\ECHO +\Driver\PnpManager +``` + +This diagram shows a more complex device node tree. + +![device node tree with about 20 nodes](images/debuglab-image-device-node-tree.png) + +**Note**  For more information about more complex driver stacks, see [Driver stacks](https://msdn.microsoft.com/library/windows/hardware/hh439632) and [Device nodes and device stacks](https://msdn.microsoft.com/library/windows/hardware/ff554721) on MSDN. + +  + +### Section 7: Working with breakpoints and source code + +*In Section 7, you will set breakpoints and single step through kernel mode source code.* + +**Note**   +**Setting breakpoints using commands** + +To be able to step through code and check the values of variables in real time, we need to enable breakpoints and set a path to the source code. + +Breakpoints are used to stop code execution at a particular line of code. You can then step forward in the code from that point, to debug that specific section of code. + +To set a breakpoint using a debug command, use one of the following **b** commands. + + ++++ + + + + + + + + + + + + + + +

bp

Sets a breakpoint that will be active until the module it is in is unloaded.

bu

Sets a breakpoint that is unresolved when the module is unloaded and re-enables when the module reloads.

bm

Sets a breakpoint for a symbol. This command will use bu or bp appropriately and allows wildcards * to be used to set breakpoints on every symbols that matches (like all methods in a class).

+ +  + +  + +For more information, see [Source Code Debugging in WinDbg](source-window.md) in the debugging reference documentation. + +**<-On the host system** + +1. Use the WinDbg UI to confirm that **Debug** > **Source Mode** is enabled in the current WinDbg session. + +2. Add your local code location to the source path by typing the following command. + + ``` + .srcpath+ C:\DriverSamples\KMDF_Echo_Sample\driver\AutoSync + ``` + +3. Add your local symbol location to the symbol path by typing the following command. + + ``` + .sympath+ C:\DriverSamples\KMDF_Echo_Sample\driver\AutoSync + ``` + +4. We will use the **x** command to examine the symbols associated with the echo driver to determine the function name to use for the breakpoint. We can use a wild card or Ctrl+F to locate the **DeviceAdd** function name. + + ``` + 0: kd> x ECHO!EchoEvt* + 8b4c7490 ECHO!EchoEvtIoQueueContextDestroy (void *) + 8b4c7000 ECHO!EchoEvtDeviceSelfManagedIoStart (struct WDFDEVICE__ *) + 8b4c7820 ECHO!EchoEvtTimerFunc (struct WDFTIMER__ *) + 8b4cb0e0 ECHO!EchoEvtDeviceSelfManagedIoSuspend (struct WDFDEVICE__ *) + 8b4c75d0 ECHO!EchoEvtIoWrite (struct WDFQUEUE__ *, struct WDFREQUEST__ *, unsigned int) + 8b4cb170 ECHO!EchoEvtDeviceAdd (struct WDFDRIVER__ *, struct + … + ``` + + The output above shows that **DeviceAdd** method for our echo driver is *ECHO!EchoEvtDeviceAdd*. + + Alternatively, we could review the source code to locate the desired function name for our breakpoint. + +5. Set the breakpoint with the **bm** command using the name of the driver, followed by the function name (for example **AddDevice**) where you want to set the breakpoint, separated by an exclamation mark. We will use **AddDevice** to watch the driver being loaded. + + ``` + 0: kd> bm ECHO!EchoEvtDeviceAdd + 1: fffff801`0bf9b1c0 @!"ECHO!EchoEvtDeviceAdd" + ``` + + **Note**   + You can use different syntax in conjunction with setting variables like <module>!<symbol>, <class>::<method>,‘<file.cpp>:<line number>’, or skip a number of times <condition> <\#>. For more information, see [Conditional breakpoints in WinDbg and other Windows debuggers](setting-a-conditional-breakpoint.md). + +   + +6. List the current breakpoints to confirm that the breakpoint was set by typing the **bl** command. + + ``` + 0: kd> bl + 1 e fffff801`0bf9b1c0 0001 (0001) ECHO!EchoEvtDeviceAdd + ``` + + The "e" in the output shown above indicates that the breakpoint number 1 is enabled to fire. + +7. Restart code execution on the target system by typing the **go** command **g**. + +8. **-> On the target system** + + In Windows, open **Device Manager** using the icon or by entering **mmc devmgmt.msc**. In Device Manager, expand the **Samples** node. + +9. Right-click the KMDF Echo driver entry and select **Disable** from the menu. + +10. Right-click the KMDF Echo driver entry again and select **Enable** from the menu. + +11. **<- On the host system** + + When the driver is enabled, the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) debug breakpoint should fire, and the execution of the driver code on the target system should halt. When the breakpoint is hit, the execution should be stopped at the start of the *AddDevice* routine. The debug command output will display "Breakpoint 1 hit". + + ![windbg showing sample code locals and command windows](images/debuglab-image-breakpoint-echo-deviceadd.png) + +12. Step through the code line-by-line by typing the **p** command or pressing F10 until you reach the following end of the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. The Brace character “}” will be highlighted as shown. + + ![code window showing brace character highlighted at start of adddevice routine](images/debuglab-image-breakpoint-end-deviceadd.png) + +13. In the next section, we will examine the state of the variables after the DeviceAdd code has executed. + +**Note**   +**Modifying breakpoint state** + +You can modify existing breakpoints by using the following commands: + + ++++ + + + + + + + + + + + + + + + + + + +

bl

Lists breakpoints.

bc

Clears a breakpoint from the list. Use bc * to clear all breakpoints.

bd

Disables a breakpoint. Use bd * to disable all breakpoints.

be

Enables a breakpoint. Use be * to enable all breakpoints.

+ +  + +Alternatively, you can also modify breakpoints by clicking **edit** > **breakpoints** in WinDbg. Note that the breakpoint dialog box only works with existing breakpoints. New breakpoints must be set from the command line. + +  + +**Note**   +**Setting memory access breakpoints** + +You can also set breakpoints that fire when a memory location is accessed. Use the **ba** (break on access) command, with the following syntax. + +``` +ba
{options} +``` + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionDescription

e

execute (when CPU fetches an instruction from the address)

r

read/write (when CPU reads or writes to the address)

w

write (when the CPU writes to the address)

+ +  + +Note that you can only set four data breakpoints at any given time and it is up to you to make sure that you are aligning your data correctly or you won’t trigger the breakpoint (words must end in addresses divisible by 2, dwords must be divisible by 4, and quadwords by 0 or 8). + +For example, to set a read/write breakpoint on a specific memory address, you could use a command like this. + +``` +ba r 4 0x0003f7bf0 +``` + +  + +**Note**   +**Stepping through code from the Debugger Command window** + +The following are the commands that you can use to step through your code (with the associated keyboard short cuts shown in parentheses). + +- Break in (Ctrl+Break) - This command will interrupt a system as long as the system is running and is in communication with WinDbg (the sequence in the Kernel Debugger is Ctrl+C). + +- Run to cursor (F7 or Ctrl+F10) – Place the cursor in a source or disassembly window where you want the execution to break, then press F7; code execution will run to that point. Note that if the flow of code execution does not reach the point indicated by the cursor (an IF statement isn't executed), WinDbg would not break, because the code execution did not reach the indicated point. + +- Run (F5) – Run until a breakpoint is encountered or an event like a bug check occurs. + +- Step over (F10) – This command causes code execution to proceed one statement or one instruction at a time. If a call is encountered, code execution passes over the call without entering the called routine. (If the programming language is C or C++ and WinDbg is in source mode, source mode can be turned on or off using **Debug**>**Source Mode**). + +- Step in (F11) – This command is like step-over, except that the execution of a call does go into the called routine. + +- Step out (Shift+F11) – This command causes execution to run to and exit from the current routine (current place in the call stack). This is useful if you've seen enough of the routine. + +  + +For more information, see [Source Code Debugging in WinDbg](source-window.md) in the debugging reference documentation. + +### Section 8: Viewing variables and call stacks + +*In Section 8, you will display information about variables and call stacks.* + +This lab assumes that you are stopped at the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine using the process described earlier. To view the output show here, repeat the steps described previously, if necessary. + +**<- On the host system** + +**Display variables** + +Use the **view**> **local** menu item to display local variables. + +![windbg local variables window](images/debuglab-image-display-variables.png) + +**Global variables** + +You can find the location of a global variable address by typing *? <variable name>*. + +**Local variables** + +You can display the names and values of all local variables for a given frame by typing the **dv** command. + +``` +0: kd> dv + Driver = 0x00001fff`7ff9c838 + DeviceInit = 0xffffd001`51978190 + status = 0n0 +``` + +**Callstacks** + +**Note**   +The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, and the next function is the function that called the current function, and so on. + +To display the call stack, use the k\* commands. + + ++++ + + + + + + + + + + + + + + +

kb

Displays the stack and first three parameters.

kp

Displays the stacks and the full list of parameters.

kn

Allows you to see the stack with the frame information next to it.

+ +  + +  + +**<-On the host system** + +1. If you want to keep the call stack available, you can click **view** > **call stack** to view it. Click on the columns at the top of the window to toggle the display of additional information. + +![windbg display call stacks window](images/debuglab-image-display-callstacks.png) + +2. Use the **kn** command to show the call stack while debugging the sample adapter code in a break state. + +``` +3: kd> kn +# Child-SP RetAddr Call Site +00 ffffd001`51978110 fffff801`0942f55b ECHO!EchoEvtDeviceAdd+0x66 [c:\Samples\kmdf echo sample\c++\driver\autosync\driver.c @ 138] +01 (Inline Function) --------`-------- Wdf01000!FxDriverDeviceAdd::Invoke+0x30 [d:\wbrtm\minkernel\wdf\framework\shared\inc\private\common\fxdrivercallbacks.hpp @ 61] +02 ffffd001`51978150 fffff801`eed8097d Wdf01000!FxDriver::AddDevice+0xab [d:\wbrtm\minkernel\wdf\framework\shared\core\km\fxdriverkm.cpp @ 72] +03 ffffd001`51978570 fffff801`ef129423 nt!PpvUtilCallAddDevice+0x35 [d:\9142\minkernel\ntos\io\pnpmgr\verifier.c @ 104] +04 ffffd001`519785b0 fffff801`ef0c4112 nt!PnpCallAddDevice+0x63 [d:\9142\minkernel\ntos\io\pnpmgr\enum.c @ 7397] +05 ffffd001`51978630 fffff801`ef0c344f nt!PipCallDriverAddDevice+0x6e2 [d:\9142\minkernel\ntos\io\pnpmgr\enum.c @ 3390] +... +``` + +The call stack shows that the kernel (nt) called into Plug and Play code (PnP), that called driver framework code (WDF) that subsequently called the echo driver **DeviceAdd** function. + +### Section 9: Displaying processes and threads + +### Processes + +*In Section 9, you will display information about the process and threads running in kernel mode.* + +**Note**   +You can display or set process information by using the [**!process**](-process.md) debugger extension. We will set a breakpoint to examine the process that are used when a sound is played. + +  + +1. **<- On the host system** + + Type the **dv** command to examine the locale variables associated with the **EchoEvtIo** routine as shown. + + ``` + 0: kd> dv ECHO!EchoEvtIo* + ECHO!EchoEvtIoQueueContextDestroy + ECHO!EchoEvtIoWrite + ECHO!EchoEvtIoRead + ``` + +2. Clear the previous breakpoints using **bc \***. + + ``` + 0: kd> bc * + ``` + +3. 3. Set a symbol breakpoint on the **EchoEvtIo** routines using the following command. + + ``` + 0: kd> bm ECHO!EchoEvtIo* + 2: aade5490 @!”ECHO!EchoEvtIoQueueContextDestroy” + 3: aade55d0 @!”ECHO!EchoEvtIoWrite” + 4: aade54c0 @!”ECHO!EchoEvtIoRead” + ``` + +4. List the breakpoints to confirm that the breakpoint is set properly. + + ``` + 0: kd> bl + 1 e aabf0490 [c:\Samples\kmdf echo sample\c++\driver\autosync\queue.c @ 197] 0001 (0001) ECHO!EchoEvtIoQueueContextDestroy + ... + ``` + +5. Type **g** to restart code execution. + + ``` + 0: kd> g + ``` + +6. **-> On the target system** + + Run the EchoApp.exe driver test program on the target system. + +7. **<- On the host system** + + When the test app runs, the I/O routine in the driver will be called. This will cause the breakpoint to fire, and execution of the driver code on the target system will halt. + + ``` + Breakpoint 2 hit + ECHO!EchoEvtIoWrite: + fffff801`0bf95810 4c89442418 mov qword ptr [rsp+18h],r8 + ``` + +8. Use the **!process** command to display the current process that is involved in running echoapp.exe. + + ``` + 0: kd> !process + PROCESS ffffe0007e6a7780 + SessionId: 1 Cid: 03c4 Peb: 7ff7cfec4000 ParentCid: 0f34 + DirBase: 1efd1b000 ObjectTable: ffffc001d77978c0 HandleCount: 34. + Image: echoapp.exe + VadRoot ffffe000802c79f0 Vads 30 Clone 0 Private 135. Modified 5. Locked 0. + DeviceMap ffffc001d83c6e80 + Token ffffc001cf270050 + ElapsedTime 00:00:00.052 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + QuotaPoolUsage[PagedPool] 33824 + QuotaPoolUsage[NonPagedPool] 4464 + Working Set Sizes (now,min,max) (682, 50, 345) (2728KB, 200KB, 1380KB) + PeakWorkingSetSize 652 + VirtualSize 16 Mb + PeakVirtualSize 16 Mb + PageFaultCount 688 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 138 + + THREAD ffffe00080e32080 Cid 03c4.0ec0 Teb: 00007ff7cfece000 Win32Thread: 0000000000000000 RUNNING on processor 1 + ``` + + The output shows that the process is associated with the echoapp.exe which was running when our breakpoint on the driver write event was hit. For more information, see [**!process**](-process.md). + +9. Use the **!process 0 0** to display summary information for all processes. In the output, use CTRL+F to locate the same process address for the process associated with the echoapp.exe image. In the example shown below, the process address is ffffe0007e6a7780. + + ``` + ... + + PROCESS ffffe0007e6a7780 + SessionId: 1 Cid: 0f68 Peb: 7ff7cfe7a000 ParentCid: 0f34 + DirBase: 1f7fb9000 ObjectTable: ffffc001cec82780 HandleCount: 34. + Image: echoapp.exe + + ... + ``` + +10. Record the process ID associated with echoapp.exe to use later in this lab. You can also use CTRL+C, to copy the address to the copy buffer for later use. + + \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_(echoapp.exe process address) + +11. Enter **g** as required into the debugger to run the code forward until the echoapp.exe finishes running. It will hit the breakpoint in the read and write event a number of times. When echoapp.exe finishes, break in to the debugger, by pressing CTRL+ScrLk (Ctrl+Break). + +12. Use the **!process** command to confirm that you are now running a different process. In the output shown below, the process with the Image value of *System* is different from the *Echo* Image value. + + ``` + 1: kd> !process + PROCESS ffffe0007b65d900 + SessionId: none Cid: 0004 Peb: 00000000 ParentCid: 0000 + DirBase: 001ab000 ObjectTable: ffffc001c9a03000 HandleCount: 786. + Image: System + VadRoot ffffe0007ce45930 Vads 14 Clone 0 Private 22. Modified 131605. Locked 64. + DeviceMap ffffc001c9a0c220 + Token ffffc001c9a05530 + ElapsedTime 21:31:02.516 + ... + ``` + + The output above shows that a system process ffffe0007b65d900 was running, when we stopped the OS. + +13. Now, use the **!process** command to try to look at the process ID that had been associated with echoapp.exe that you recorded earlier. Provide your echoapp.exe process address that you recorded earlier, instead of the example process address shown below. + + ``` + 0: kd> !process ffffe0007e6a7780 + TYPE mismatch for process object at 82a9acc0 + ``` + + The process object is now longer available, as the echoapp.exe process is no longer running. + +### Threads + +**Note**   +The commands to view and set threads are very similar to those of processes. Use the [**!thread**](-thread.md) command to view threads. Use [**.thread**](-thread--set-register-context-.md) to set the current threads. + +  + +1. **<- On the host system** + + Enter **g** into the debugger to restart code execution on the target system. + +2. **-> On the target system** + + Run the EchoApp.exe driver test program on the target system. + +3. **<- On the host system** + + The breakpoint will be hit and code execution will halt. + + ``` + Breakpoint 4 hit + ECHO!EchoEvtIoRead: + aade54c0 55 push ebp + ``` + +4. To view the threads that are running, type [**!thread**](-thread.md). Information similar to the following should be displayed: + + ``` + 0: kd> !thread + THREAD ffffe000809a0880 Cid 0b28.1158 Teb: 00007ff7d00dd000 Win32Thread: 0000000000000000 RUNNING on processor 0 + IRP List: + ffffe0007bc5be10: (0006,01f0) Flags: 00060a30 Mdl: 00000000 + Not impersonating + DeviceMap ffffc001d83c6e80 + Owning Process ffffe0008096c900 Image: echoapp.exe + ... + ``` + + Note the image name of *echoapp.exe*, indicating that we are looking at the thread associated with the test app. + +5. 4. Use the **!process** command to determine if this is the only thread running in the process associated with echoapp.exe. Note that the thread number of the running thread in the process is the same thread running that the !thread command displayed. + + ``` + 0: kd> !process + PROCESS ffffe0008096c900 + SessionId: 1 Cid: 0b28 Peb: 7ff7d00df000 ParentCid: 0f34 + DirBase: 1fb746000 ObjectTable: ffffc001db6b52c0 HandleCount: 34. + Image: echoapp.exe + VadRoot ffffe000800cf920 Vads 30 Clone 0 Private 135. Modified 8. Locked 0. + DeviceMap ffffc001d83c6e80 + Token ffffc001cf5dc050 + ElapsedTime 00:00:00.048 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + QuotaPoolUsage[PagedPool] 33824 + QuotaPoolUsage[NonPagedPool] 4464 + Working Set Sizes (now,min,max) (681, 50, 345) (2724KB, 200KB, 1380KB) + PeakWorkingSetSize 651 + VirtualSize 16 Mb + PeakVirtualSize 16 Mb + PageFaultCount 686 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 138 + + THREAD ffffe000809a0880 Cid 0b28.1158 Teb: 00007ff7d00dd000 Win32Thread: 0000000000000000 RUNNING on processor 0 + ``` + +6. Use the **!process 0 0 command** to locate the process address of two related processes and record those process address here. + + Cmd.exe: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + + EchoApp.exe: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + + ``` + 0: kd> !process 0 0 + + … + + PROCESS ffffe0007bbde900 + SessionId: 1 Cid: 0f34 Peb: 7ff72dfa7000 ParentCid: 0c64 + DirBase: 19c5fa000 ObjectTable: ffffc001d8c2f300 HandleCount: 31. + Image: cmd.exe + … + PROCESS ffffe0008096c900 + SessionId: 1 Cid: 0b28 Peb: 7ff7d00df000 ParentCid: 0f34 + DirBase: 1fb746000 ObjectTable: ffffc001db6b52c0 HandleCount: 34. + Image: echoapp.exe + … + ``` + + **Note**  You can alternatively use **!process 0 17** to display detailed information about every process. The output from this command can be lengthy. The output can be searched using Ctrl+F. + +   + +7. Use the **!process** command to list process information for both processes running your PC. Provide the process address from your **!process 0 0** output, not the address shown below. + + This example output is for the cmd.exe process ID that was recorded earlier. Note that the image name for this process ID is cmd.exe. + + ``` + 0: kd> !process ffffe0007bbde900 + PROCESS ffffe0007bbde900 + SessionId: 1 Cid: 0f34 Peb: 7ff72dfa7000 ParentCid: 0c64 + DirBase: 19c5fa000 ObjectTable: ffffc001d8c2f300 HandleCount: 31. + Image: cmd.exe + VadRoot ffffe0007bb8e7b0 Vads 25 Clone 0 Private 117. Modified 20. Locked 0. + DeviceMap ffffc001d83c6e80 + Token ffffc001d8c48050 + ElapsedTime 21:33:05.840 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + QuotaPoolUsage[PagedPool] 24656 + QuotaPoolUsage[NonPagedPool] 3184 + Working Set Sizes (now,min,max) (261, 50, 345) (1044KB, 200KB, 1380KB) + PeakWorkingSetSize 616 + VirtualSize 2097164 Mb + PeakVirtualSize 2097165 Mb + PageFaultCount 823 + MemoryPriority FOREGROUND + BasePriority 8 + CommitCharge 381 + + THREAD ffffe0007cf34880 Cid 0f34.0f1c Teb: 00007ff72dfae000 Win32Thread: 0000000000000000 WAIT: (UserRequest) UserMode Non-Alertable + ffffe0008096c900 ProcessObject + Not impersonating + ... + ``` + + This example output is for the echoapp.exe process ID that was recorded earlier. + + ``` + 0: kd> !process ffffe0008096c900 + PROCESS ffffe0008096c900 + SessionId: 1 Cid: 0b28 Peb: 7ff7d00df000 ParentCid: 0f34 + DirBase: 1fb746000 ObjectTable: ffffc001db6b52c0 HandleCount: 34. + Image: echoapp.exe + VadRoot ffffe000800cf920 Vads 30 Clone 0 Private 135. Modified 8. Locked 0. + DeviceMap ffffc001d83c6e80 + Token ffffc001cf5dc050 + ElapsedTime 00:00:00.048 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + QuotaPoolUsage[PagedPool] 33824 + QuotaPoolUsage[NonPagedPool] 4464 + Working Set Sizes (now,min,max) (681, 50, 345) (2724KB, 200KB, 1380KB) + PeakWorkingSetSize 651 + VirtualSize 16 Mb + PeakVirtualSize 16 Mb + PageFaultCount 686 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 138 + + THREAD ffffe000809a0880 Cid 0b28.1158 Teb: 00007ff7d00dd000 Win32Thread: 0000000000000000 RUNNING on processor 0 + IRP List: + ffffe0007bc5be10: (0006,01f0) Flags: 00060a30 Mdl: 00000000 + Not impersonating + ... + ``` + +8. Record the first thread address associated with the two processes here. + + Cmd.exe: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + + EchoApp.exe: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +9. Use the **!Thread** command to display information about the current thread. + + ``` + 0: kd> !Thread + THREAD ffffe000809a0880 Cid 0b28.1158 Teb: 00007ff7d00dd000 Win32Thread: 0000000000000000 RUNNING on processor 0 + IRP List: + ffffe0007bc5be10: (0006,01f0) Flags: 00060a30 Mdl: 00000000 + Not impersonating + DeviceMap ffffc001d83c6e80 + Owning Process ffffe0008096c900 Image: echoapp.exe + Attached Process N/A Image: N/A + ... + ``` + + As expected, the current thread is the thread associated with echoapp.exe and it is in a running state. + +10. Use the **!Thread** command to display information about the thread associated with cmd.exe process. Provide the thread address you recorded earlier. + + ``` + 0: kd> !Thread ffffe0007cf34880 + THREAD ffffe0007cf34880 Cid 0f34.0f1c Teb: 00007ff72dfae000 Win32Thread: 0000000000000000 WAIT: (UserRequest) UserMode Non-Alertable + ffffe0008096c900 ProcessObject + Not impersonating + DeviceMap ffffc001d83c6e80 + Owning Process ffffe0007bbde900 Image: cmd.exe + Attached Process N/A Image: N/A + Wait Start TickCount 4134621 Ticks: 0 + Context Switch Count 4056 IdealProcessor: 0 + UserTime 00:00:00.000 + KernelTime 00:00:01.421 + Win32 Start Address 0x00007ff72e9d6e20 + Stack Init ffffd0015551dc90 Current ffffd0015551d760 + Base ffffd0015551e000 Limit ffffd00155518000 Call 0 + Priority 14 BasePriority 8 UnusualBoost 3 ForegroundBoost 2 IoPriority 2 PagePriority 5 + Child-SP RetAddr : Args to Child : Call Site + ffffd001`5551d7a0 fffff801`eed184fe : fffff801`eef81180 ffffe000`7cf34880 00000000`fffffffe 00000000`fffffffe : nt!KiSwapContext+0x76 [d:\9142\minkernel\ntos\ke\amd64\ctxswap.asm @ 109] + ffffd001`5551d8e0 fffff801`eed17f79 : ffff03a5`ca56a3c8 000000de`b6a6e990 000000de`b6a6e990 00007ff7`d00df000 : nt!KiSwapThread+0x14e [d:\9142\minkernel\ntos\ke\thredsup.c @ 6347] + ffffd001`5551d980 fffff801`eecea340 : ffffd001`5551da18 00000000`00000000 00000000`00000000 00000000`00000388 : nt!KiCommitThreadWait+0x129 [d:\9142\minkernel\ntos\ke\waitsup.c @ 619] + ... + ``` + + This thread is associated with cmd.exe and is in a wait state. + +11. Provide the thread address of the waiting CMD.exe thread to change the context to that waiting thread. + + ``` + 0: kd> .Thread ffffe0007cf34880 + Implicit thread is now ffffe000`7cf34880 + ``` + +12. Use the **k** command to view the call stack associated with the waiting thread. + + ``` + 0: kd> k + *** Stack trace for last set context - .thread/.cxr resets it +# Child-SP RetAddr Call Site + 00 ffffd001`5551d7a0 fffff801`eed184fe nt!KiSwapContext+0x76 [d:\9142\minkernel\ntos\ke\amd64\ctxswap.asm @ 109] + 01 ffffd001`5551d8e0 fffff801`eed17f79 nt!KiSwapThread+0x14e [d:\9142\minkernel\ntos\ke\thredsup.c @ 6347] + 02 ffffd001`5551d980 fffff801`eecea340 nt!KiCommitThreadWait+0x129 [d:\9142\minkernel\ntos\ke\waitsup.c @ 619] + 03 ffffd001`5551da00 fffff801`ef02e642 nt!KeWaitForSingleObject+0x2c0 [d:\9142\minkernel\ntos\ke\wait.c @ 683] + ... + ``` + + Call stack elements such as **KiCommitThreadWait** indicate that this thread is not running as is expected. + +**Note**   +For more information about threads and processes, see the following references on MSDN: + +[Threads and Processes](threads-and-processes.md) + +[Changing Contexts](changing-contexts.md) + +  + +### Section 10: IRQL, Registers and Ending the WinDbg session + +### Viewing the saved IRQL + +*In Section 10, you will display the IRQL, and the contents of the regsisters.* + +**<- On the host system** + +The interrupt request level (IRQL) is used to manage the priority of interrupt servicing. Each processor has an IRQL setting that threads can raise or lower. Interrupts that occur at or below the processor's IRQL setting are masked and will not interfere with the current operation. Interrupts that occur above the processor's IRQL setting take precedence over the current operation. The [**!irql**](-irql.md) extension displays the interrupt request level (IRQL) on the current processor of the target computer before the debugger break occurred. When the target computer breaks into the debugger, the IRQL changes, but the IRQL that was effective just before the debugger break is saved and is displayed by **!irql**. + +``` +0: kd> !irql +Debugger saved IRQL for processor 0x0 -- 2 (DISPATCH_LEVEL) +``` + +### Viewing the registers + +**<-On the host system** + +Display the contents of the registers for the current thread on the current processor by using the [**r (Registers)**](r--registers-.md) command. + +``` +0: kd> r +rax=000000000000c301 rbx=ffffe00173eed880 rcx=0000000000000001 +rdx=000000d800000000 rsi=ffffe00173eed8e0 rdi=ffffe00173eed8f0 +rip=fffff803bb757020 rsp=ffffd001f01f8988 rbp=ffffe00173f0b620 + r8=000000000000003e r9=ffffe00167a4a000 r10=000000000000001e +r11=ffffd001f01f88f8 r12=0000000000000000 r13=ffffd001f01efdc0 +r14=0000000000000001 r15=0000000000000000 +iopl=0 nv up ei pl nz na pe nc +cs=0010 ss=0018 ds=002b es=002b fs=0053 gs=002b efl=00000202 +nt!DbgBreakPointWithStatus: +fffff803`bb757020 cc int 3 +``` + +Alternatively, you can display the contents of the registers by clicking **view** > **registers**. For more information see [**r (Registers)**](r--registers-.md). + +Viewing the contents of the registers can be helpful when stepping through assembly language code execution and in other scenarios. For more information about assembly language disassembly, see [Annotated x86 Disassembly](annotated-x86-disassembly.md) and [Annotated x64 Disassembly](annotated-x64-disassembly.md). + +For information about contents of the register, see [x86 Architecture](x86-architecture.md) and [x64 Architecture](x64-architecture.md). + +### Ending the WinDbg session + +**<-On the host system** + +To end a user-mode debugging session, return the debugger to dormant mode, and set the target application to run again, enter the **qd** (Quit and Detach) command. + +Be sure and use the **g** command to let the target computer run code, so that it can be used. It also a good idea to clear any break points using **bc \***, so that the target computer won't break and try to connect to the host computer debugger. + +``` +0: kd> qd +``` + +For more information, see [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) in the debugging reference documentation. + +### Section 11: Windows debugging resources + + +Additional information is available on Windows debugging. Note that some of these books will use older versions of Windows such as Windows Vista in their examples, but the concepts discussed are applicable to most versions of Windows. + +**Books** + +- Advanced Windows Debugging by Mario Hewardt and Daniel Pravat + +- Inside Windows Debugging: A Practical Guide to Debugging and Tracing Strategies in Windows® by Tarik Soulami + +- Windows Internals by Mark E. Russinovich, David A. Solomon and Alex Ionescu + +**Video** + +The Defrag Tools Show WinDbg Episodes 13-29 + +**Training Vendors:** + +OSR + +### Related topics + + +[Standard Debugging Techniques](standard-debugging-techniques.md) + +[Specialized Debugging Techniques](specialized-debugging-techniques.md) + +[Getting Started with Windows Debugging](getting-started-with-windows-debugging.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20Universal%20Drivers%20-%20Step%20by%20Step%20Lab%20%28Echo%20Kernel-Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debug-universal-drivers--kernel-mode-.md b/windows-driver-docs-pr/debugger/debug-universal-drivers--kernel-mode-.md new file mode 100644 index 0000000000..1783d24922 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-universal-drivers--kernel-mode-.md @@ -0,0 +1,2129 @@ +--- +title: Debug Drivers - Step-by-Step Lab (Sysvad Kernel Mode) +description: This lab provides hands-on exercises that demonstrate how to debug the Sysvad audio kernel-mode device driver. +ms.assetid: 4A31451C-FC7E-4C5F-B4EB-FBBAC8DADF9E +keywords: ["debug lab", "step-by-step", "SYSVAD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug Drivers - Step by Step Lab (Sysvad Kernel Mode) + + +This lab provides hands-on exercises that demonstrate how to debug the Sysvad audio kernel-mode device driver. + +Microsoft Windows Debugger (WinDbg) is a powerful Windows-based debugging tool that you can use to perform user-mode and kernel-mode debugging. WinDbg provides source-level debugging for the Windows kernel, kernel-mode drivers, and system services, as well as user-mode applications and drivers. + +WinDbg can step through source code, set breakpoints, view variables (including C++ objects), stack traces, and memory. Its Debugger Command window allows the user to issue a wide variety of commands. + +## Lab setup + + +You will need the following hardware to be able to complete the lab: + +- A laptop or desktop computer (host) running Windows 10 +- A laptop or desktop computer (target) running Windows 10 +- A network cross-over cable, or a network hub and network cables to connect the two PCs +- Access to the internet to download symbol files + +You will need the following software to be able to complete the lab. + +- Microsoft Visual Studio 2015 +- Windows Software Development Kit (SDK) for Windows 10 +- Windows Driver Kit (WDK) for Windows 10 +- The sample Sysvad audio driver for Windows 10 + +For information on downloading and installing the WDK, see [Download the Windows Driver Kit (WDK)](https://developer.microsoft.com/windows/hardware/windows-driver-kit) + +## Sysvad debugging walkthrough + + +This lab walk you through the process of debugging a kernel-mode driver. The exercises use the Syvad virtual audio driver sample. Because the Syvad audio driver doesn't interact with actual audio hardware, it can be used on most devices. The lab covers the following tasks: + +- [Section 1: Connect to a kernel-mode WinDbg session](#connectto) +- [Section 2: kernel-mode debugging commands and techniques](#kernelmodedebuggingcommandsandtechniques) +- [Section 3: Download and build the Sysvad audio driver](#download) +- [Section 4: Install the Sysvad audio driver on the target system](#install) +- [Section 5: Use WinDbg to display information about the driver](#usewindbgtodisplayinformation) +- [Section 6: Display Plug and Play device tree information](#displayingtheplugandplaydevicetree) +- [Section 7: Work with breakpoints and source code](#workingwithbreakpoints) +- [Section 8: Look at variables](#lookingatvariables) +- [Section 9: View call stacks](#viewingcallstacks) +- [Section 10: Display processes and threads](#displayingprocessesandthreads) +- [Section 11: IRQL, registers and disassembly](#irqlregistersmemory) +- [Section 12: Work with memory](#workingwithmemory) +- [Section 13: Ending the WinDbg session](#endingthesession) +- [Section 14: Windows debugging resources](#windowsdebuggingresources) + +## Echo driver lab + + +The Echo driver is a simpler driver then the Sysvad audio driver. If you are new to WinDbg, you may want to consider first completing the [Debug Universal Drivers - Step-by-Step Lab (Echo kernel mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md). This lab reuses the setup directions from that lab, so if you have completed that lab you can skip sections 1 and 2 here. + +## Section 1: Connect to a kernel-mode WinDbg session + + +*In Section 1, you will configure network debugging on the host and target system.* + +The PCs in this lab need to be configured to use an Ethernet network connection for kernel debugging. + +This lab uses two computers. WinDbg runs on the *host* system and the Sysvad driver runs on the *target* system. + +The "<-Host" on the left is connected using a cross over ethernet cable to the "->Target" on the right. + +The steps in the lab assume that you are using a cross over network cable, but the lab should also work if you can plug both the host and the target directly into a network hub. + +![two pcs connected with a double arrow](images/debuglab-image-targethostdrawing1.png) + +To work with kernel-mode applications and use WinDbg, we recommend that you use the KDNET over Ethernet transport. For information about how to use the Ethernet transport protocol, see [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md). For more information about setting up the target computer, see [Preparing a Computer for Manual Driver Deployment](https://msdn.microsoft.com/windows-drivers/develop/preparing_a_computer_for_manual_driver_deployment) and [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md). + +### Configure kernel–mode debugging using a crossover ethernet cable + +To enable kernel-mode debugging on the target system, perform the following steps. + +**<- On the host system** + +1. Open a command prompt on the host system and type **ipconfig /all** to determine its IP address. + +``` +C:\>ipconfig /all +Windows IP Configuration + + Host Name . . . . . . . . . . . . : TARGETPC +... + +Ethernet adapter Ethernet: + Connection-specific DNS Suffix . : + Link-local IPv6 Address . . . . . : fe80::c8b6:db13:d1e8:b13b3 + Autoconfiguration IPv4 Address. . : 169.182.1.1 + Subnet Mask . . . . . . . . . . . : 255.255.0.0 + Default Gateway . . . . . . . . . : +``` + +2. Record the IP address of the host System: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +3. Record the Host Name of the host System: \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +**-> On the target system** + +4. Open a command prompt on the target system and use the **ping** command to confirm network connectivity between the two systems. Use the IP address of the host system you recorded instead of the one shown in the sample output. + +``` +C:\> ping 169.182.1.1 + +Pinging 169.182.1.1 with 32 bytes of data: +Reply from 169.182.1.1: bytes=32 time=1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 +Reply from 169.182.1.1: bytes=32 time<1ms TTL=255 + +Ping statistics for 169.182.1.1: + Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), +Approximate round trip times in milli-seconds: + Minimum = 0ms, Maximum = 1ms, Average = 0ms +``` + +To use the KDNET utility to enable kernel-mode debugging on the target system, peform the following steps. + +1. On the host system, locate the WDK KDNET directory. By default it is located here. + +``` +C:\Program Files (x86)\Windows Kits\10\ +``` + +2. Locate these two files and copy them to a network share or thumb drive, so that they will be available on the target computer. + +``` +kdnet.exe +VerifiedNICList.xml +``` + +3. On the target computer, open a Command Prompt window as Administrator. Enter this command to validate that the NIC on the target PC is suported. + +``` +C:\KDNET>kdnet + +Network debugging is supported on the following NICs: +busparams=0.25.0, Intel(R) 82579LM Gigabit Network Connection, KDNET is running on this NIC.kdnet.exe +``` + +4. Type this command to set the IP address of the host system. Use the IP address of the host system that you recorded earlier, not the one shown. Pick a unique port address for each target/host pair that you work with, such as 50010. + +``` +C:\>kdnet TARGETPC 50010 + +NtQuerySystemInformation cannot query SystemKernelDebuggingAllowed on this OS. +Enabling network debugging on Intel(R) 82577LM Gigabit Network Connection. +Key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p +``` + +5. Type this command to confirm that the dbgsettings are set properly. + +``` +C:\> bcdedit /dbgsettings +busparams 0.25.0 +key 2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p +debugtype NET +hostip 169.182.1.1 +port 50010 +dhcp Yes +The operation completed successfully. +``` + +Copy the auto generated unique key into a text file, to avoid having to type it in on the host PC. Copy the text file with the key over to the host system. +**Note**   +**Firewalls and debuggers** + +If you receive a pop-up message from the firewall, and you wish to use the debugger, unblock the types of networks that you desire. + +![windows security alert - windows firewall has blocked some features of this app](images/debuglab-image-firewall-dialog-box.png) + +  + +**<- On the host system** + +1. On the host computer, open a Command Prompt window as Administrator. Change to the WinDbg.exe directory. We will use the x64version of WinDbg.exe from the Windows Driver Kit (WDK) that was installed as part of the Windows kit installation. + +``` +C:\> Cd C:\Program Files (x86)\Windows Kits\10\Debuggers\x64 +``` + +2. Launch WinDbg with remote user debug using the following command. The value for the key and port match what you set earlier using BCDEdit on the target. + +``` +C:\> WinDbg –k net:port=50010,key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p +``` + +**->On the target system** + +Reboot the target system. + +**<-On the host system** + +In a minute or two, debug output should be displayed on the host system. + +![windows debugger showing command window output from a live kernel connection](images/debuglab-image-winddbg-hh.png) + +The Debugger Command window is the primary debugging information window in WinDbg. You can enter debugger commands and view the command output in this window. + +The Debugger Command window is split into two panes. You type commands in the smaller pane (the command entry pane) at the bottom of the window and view the command output in the larger pane at the top of the window. + +In the command entry pane, use the up arrow and down arrow keys to scroll through the command history. When a command appears, you can edit it or press **ENTER** to run the command. + +## Section 2: kernel-mode debugging commands and techniques + + +*In Section 2, you will use debug commands to display information about the target system.* + +**<- On the host system** + +**Enable Debugger Markup Language (DML) with .prefer\_dml** + +Some debug commands display text using Debugger Markup Language that you can click on to quickly gather more information. + +1. Use Ctrl+Break (Scroll Lock) in WinDBg to break into the code running on the target system. It may take a bit of time for the target system to respond. +2. Type the following command to enable DML in the Debugger Command window. + +``` +0: kd> .prefer_dml 1 +DML versions of commands on by default +``` + +**Use .hh to get help** + +You can access reference command help using the **.hh** command. + +3. Type the following command to view the command reference help for **.prefer\_dml**. +``` +0: kd> .hh .prefer_dml +``` + +The Debugger help file will display help for the **.prefer\_dml** command. + +![debugger help application showing help for the .prefer\-dml command](images/debuglab-image-prefer-dml-help.png) + +**Display the version of Windows on the target system** + +5. Display detailed version information on the target system by typing the [**vertarget (Show Target Computer Version)**](vertarget--show-target-computer-version-.md) command in the WinDbg window. + +``` +0: kd> vertarget +Windows 10 Kernel Version 9926 MP (4 procs) Free x64 +Product: WinNt, suite: TerminalServer SingleUserTS +Built by: 9926.0.amd64fre.fbl_awesome1501.150119-1648 +Machine Name: "" +Kernel base = 0xfffff801`8d283000 PsLoadedModuleList = 0xfffff801`8d58aef0 +Debug session time: Fri Feb 20 10:15:17.807 2015 (UTC - 8:00) +System Uptime: 0 days 01:31:58.931 +``` + +**List the loaded modules** + +6. You can verify that you are working with the right kernel-mode process by displaying the loaded modules by typing the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command in the WinDbg window. + +``` +0: Kd> lm +start end module name +fffff801`09200000 fffff801`0925f000 volmgrx (no symbols) +fffff801`09261000 fffff801`092de000 mcupdate_GenuineIntel (no symbols) +fffff801`092de000 fffff801`092ec000 werkernel (export symbols) werkernel.sys +fffff801`092ec000 fffff801`0934d000 CLFS (export symbols) CLFS.SYS +fffff801`0934d000 fffff801`0936f000 tm (export symbols) tm.sys +fffff801`0936f000 fffff801`09384000 PSHED (export symbols) PSHED.dll +fffff801`09384000 fffff801`0938e000 BOOTVID (export symbols) BOOTVID.dll +fffff801`0938e000 fffff801`093f7000 spaceport (no symbols) +fffff801`09400000 fffff801`094cf000 Wdf01000 (no symbols) +fffff801`094d9000 fffff801`09561000 CI (export symbols) CI.dll +... +``` + +**Note**  Output that has been omitted is indicated with "… " in this lab. + +  + +Because we have yet to set the symbol path and loaded symbols, limited information is available in the debugger. + +## Section 3: Download and build the Sysvad audio driver + + +*In Section 3, you will download and build the Sysvad audio driver.* + +Typically, you would be working with your own driver code when you use WinDbg. To become familiar with debugging audio drivers, the Sysvad virtual audio sample driver is used. This sample is used to illustrate how you can single step through native kernel-mode code. This technique can be very valuable for debugging complex kernel-mode code issues. + +To download and build the Sysvad sample audio driver, perform the following steps. + +1. **Download and extract the Sysvad audio sample from GitHub** + + You can use a browser to view the Sysvad sample and Readme.md file here: + + [https://github.com/Microsoft/Windows-driver-samples/tree/master/audio/sysvad](https://github.com/Microsoft/Windows-driver-samples/blob/97cf5197cf5b882b2c689d8dc2b555f2edf8f418/general/echo/kmdf/ReadMe.md) + + ![github repo showing general folder and download zip button](images/sysvad-lab-github.png) + + This lab, shows how to download the universal driver samples in one zip file. + + a. Download the master.zip file to your local hard drive. + + + + b. Right-click *Windows-driver-samples-master.zip*, and choose **Extract All**. Specify a new folder, or browse to an existing one that will store the extracted files. For example, you could specify *C:\\WDK\_Samples\\* as the new folder into which the files are extracted. + + c. After the files are extracted, navigate to the following subfolder. + + *C:\\WDK\_Samples\\Sysvad* + +2. **Open the driver solution in Visual Studio** + + In Visual Studio, click **File** > **Open** > **Project/Solution...** and navigate to the folder that contains the extracted files (for example, *C:\\WDK\_Samples\\Sysvad*). Double-click the *Syvad* solution file. + + In Visual Studio locate the Solution Explorer. (If this is not already open, choose **Solution Explorer** from the **View** menu.) In Solution Explorer, you can see one solution that has four (4) projects. Note that the project titled SwapAPO is actually a folder that contains two projects - APO and PropPageExtensions. + + ![visual studio with the device.c file loaded from the sysvad project](images/sysvad-lab-visual-studio-solution.png) + +3. **Set the sample's configuration and platform** + + In Solution Explorer, right-click **Solution 'sysvad' (6 projects)**, and choose **Configuration Manager**. Make sure that the configuration and platform settings are the same for the four projects. By default, the configuration is set to "Win10 Debug", and the platform is set to "Win64" for all the projects. If you make any configuration and/or platform changes for one project, you must make the same changes for the remaining three projects. + + **Note**  This lab assumes that 64 bit Windows is being used. If you are using 32 bit Windows, build the driver for 32 bit. + +   + +4. **Check driver signing** + + Locate the TabletAudioSample. Open the Sysvad driver’s property page and make sure **Driver Signing** > **Sign Mode** is set to *Test Sign*. + +5. **Build the sample using Visual Studio** + + In Visual Studio, click **Build** > **Build Solution**. + + The build windows should display a message indicating that the build for all six projects succeeded. + +6. **Locate the built driver files** + + In File Explorer, navigate to the folder that contains the extracted files for the sample. For example, you would navigate to *C:\\WDK\_Samples\\Sysvad*, if that's the folder you specified earlier. Within that folder, the location of the compiled driver files varies depending on the configuration and platform settings that you selected in the **Configuration Manager**. For example, if you left the default settings unchanged, then the compiled driver files will be saved to a folder named *\\x64\\Debug* for a 64-bit, debug build. + + Navigate to the folder that contains the built files for the TabletAudioSample driver: + + *C:\\WDK\_Samples\\Sysvad\\TabletAudioSample\\x64\\Debug*. The folder will contain the TabletAudioSample .SYS driver, symbol pdp file and the inf file. You will also need to locate the SwapAPO, PropPageExt and KeywordDetectorContosoAdapter dlls and symbol files. + + To install the driver, you will need the following files. + + | | | + |-----------------------------------|-----------------------------------------------------------------------------------| + | TabletAudioSample.sys | The driver file. | + | TabletAudioSample.pdb | The driver symbol file. | + | tabletaudiosample.inf | An information (INF) file that contains information needed to install the driver. | + | KeywordDetectorContosoAdapter.dl | A sample keyword detector. | + | KeywordDetectorContosoAdapter.pdb | The sample keyword detector symbol file. | + | lSwapAPO.dll | A sample driver extension for a UI to manage APOs. | + | lSwapAPO.pdb | The APO UI symbol file. | + | PropPageExt.dll | A sample driver extension for a property page. | + | PropPageExt.pdb | The property page symbol file. | + | TabletAudioSample.cer | The TabletAudioSample certificate file. | + +   + +7. Locate a USB thumb drive or set up a network share to copy the built driver files from the host to the target system. + +In the next section, you will copy the code to the target system, and install and test the driver. + +## Section 4: Install the Sysvad audio driver sample on the target system + + +*In Section 4, you will use devcon to install the Sysvad audio driver.* + +**-> On the target system** + +The computer where you install the driver is called the *target computer* or the *test computer*. Typically, this is a separate computer from the computer on which you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*. + +The process of moving the driver package to the target computer and installing the driver is called *deploying* the driver. You can deploy the sample Sysvad driver, automatically or manually. + +Before you manually deploy a driver, you must prepare the target computer by turning on test signing. You also need to locate the DevCon tool in your WDK installation. After that you’re ready to run the built driver sample on the target system. + +To install the driver on the target system, perform the following steps. + +1. **Enable test signed drivers** + + To enable the ability to run test signed drivers: + + 1. Open Windows Settings. + + 2. In **Update and Security**, select **Recovery**. + + 3. Under **Advanced startup**, click **Restart Now**. + + 4. When the PC restarts, select **Troubleshoot**. + + 5. Then select **Advanced options**, **Startup Settings** and then click **Restart**. + + 6. Select Disable driver signature enforcement by pressing the **F7** key. + + 7. The PC will start with the new values in place. + +2. **<- On the host system** + + Navigate to the Tools folder in your WDK installation and locate the DevCon tool. For example, look in the following folder: + + *C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\devcon.exe* + +3. **-> On the target system** + + **Install the driver** + + The following instructions show you how to install and test the sample driver. + + The INF file required for installing this driver is *TabletAudioSample.inf*. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, right-click the TabletAudioSample.inf file, and then select **Install**. + + A dialog box will appear indicating that the test driver is an unsigned driver. Click **Install this driver anyway** to proceed. + + ![windows security warning - windows can't verify the publisher](images/debuglab-image-install-security-warning.png) + + [!TIP] If you have any issues with the installation, check the following file for more information. + `%windir%\\inf\\setupapi.dev.log` + + For more detailed instructions, see [Configuring a Computer for Driver Deployment, Testing, and Debugging](http://msdn.microsoft.com/library/windows/hardware/hh698272.aspx). + + The INF file contains the hardware ID for installing the *tabletaudiosample.sys*. For the Syvad sample, the hardware ID is: + `root\\sysvad\_TabletAudioSample` + + On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command: `devcon status root\\sysvad\_TabletAudioSample` + + + Status information is displayed durring the devcon install. + + +4. **Examine the driver in Device Manager** + + On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the View menu, select **Devices by type**. + + In the device tree, locate *Virtual Audio Device (WDM) - Tablet Sample* in the Audio Device node. This is typically under the **Sound, video and game controllers** node. Confirm that it is installed and active. + + Highlight the driver for the actual hardware on the PC in Device Manager. Then right-click the driver and click disable to disable the driver. + + Confirm in Device Manager that audio hardware driver, displays the a down arrow, indicating that it is disabled. + + ![device manager tree with the virtual audio device tablet sample highlighted](images/sysvad-lab-audio-device-manager.png) + + After successfully installing the sample driver, you're now ready to test it. + +**Test the Sysvad audio driver** + +1. On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, select **Devices by type**. In the device tree, locate *Virtual Audio Device (WDM) - Tablet Sample*. + +2. Open Control Panel and navigate to **Hardware and Sound** > **Manage audio devices**. In the Sound dialog box, select the speaker icon labeled as *Virtual Audio Device (WDM) - Tablet Sample*, and then click **Set Default**, but do not click **OK**. This will keep the Sound dialog box open. +3. Locate an MP3 or other audio file on the target computer and double-click to play it. Then in the Sound dialog box, verify that there is activity in the volume level indicator associated with the *Virtual Audio Device (WDM) - Tablet Sample* driver. + +## Section 5: Use WinDbg to display information about the driver + + +*In Section 5, you will set the symbol path and use kernel debugger commands to display information about the Sysvad sample driver.* + +Symbols allow for WinDbg to display additional information such as variable names, that can be invaluable when debugging. WinDbg uses the Microsoft Visual Studio debug symbol formats for source-level debugging. It can access any symbol or variable from a module that has PDB symbol files. + +To load the debugger, perform the following steps. + +**<-On the host system** + +1. If you closed the debugger, open it again using the following command in the administrator command prompt window. Replace the key and port with what you previously configured. + + ``` + C:\> WinDbg –k net:port=50010,key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p + ``` + +2. Use Ctrl+Break (Scroll Lock) to break into the code running on the target system. + +**Set the symbol path** + +1. To set the symbols path to the Microsoft symbol server in the WinDbg environment, use the **.symfix** command. + + ``` + 0: kd> .symfix + ``` + +2. To add your local symbol location to use your local symbols, add the path using **.sympath+** and then **.reload /f**. + + ``` + 0: kd> .sympath+ C:\WDK_Samples\Sysvad + 0: kd> .reload /f + ``` + + **Note**  The **.reload** command with the **/f** force option deletes all symbol information for the specified module and reloads the symbols. In some cases, this command also reloads or unloads the module itself. + +   + +**Note**  You must load the proper symbols to use advanced functionality that WinDbg provides. If you do not have symbols properly configured, you will receive messages indicating that symbols are not available when you attempt to use functionality that is dependent on symbols. +``` +0:000> dv +Unable to enumerate locals, HRESULT 0x80004005 +Private symbols (symbols.pri) are required for locals. +Type “.hh dbgerr005” for details. +``` + +  + +**Note**   +**Symbol servers** + +There are a number of approaches that can be used to work with symbols. In many situations, you can configure the PC to access symbols from a symbol server that Microsoft provides when they are needed. This walkthrough assumes that this approach will be used. If the symbols in your environment are in a different location, modify the steps to use that location. For additional information, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +  + +**Note**   +**Understand source code symbol requirements** + +To perform source debugging, you must build a checked (debug) version of your binaries. The compiler will create symbol files (.pdb files). These symbol files will show the debugger how the binary instructions correspond to the source lines. The actual source files themselves must also be accessible to the debugger. + +The symbol files do not contain the text of the source code. For debugging, it is best if the linker does not optimize your code. Source debugging and access to local variables are more difficult, and sometimes nearly impossible, if the code has been optimized. If you are having problems viewing local variables or source lines, set the following build options. + +``` +set COMPILE_DEBUG=1 +set ENABLE_OPTIMIZER=0 +``` + +  + +1. Type the following in the command area of the debugger to display information about the Sysvad driver. + + ``` + 0: kd> lm m tabletaudiosample v + Browse full module list + start end module name + fffff801`14b40000 fffff801`14b86000 tabletaudiosample (private pdb symbols) C:\Debuggers\sym\TabletAudioSample.pdb\E992C4803EBE48C7B23DC1596495CE181\TabletAudioSample.pdb + Loaded symbol image file: tabletaudiosample.sys + Image path: \SystemRoot\system32\drivers\tabletaudiosample.sys + Image name: tabletaudiosample.sys + Browse all global symbols functions data + Timestamp: Thu Dec 10 12:20:26 2015 (5669DE8A) + CheckSum: 0004891E + ... + ``` + + For more information, see [**lm**](lm--list-loaded-modules-.md). + +2. Click the **Browse all global symbols** link in the debug output to display information about items symbols that start with the letter a. +3. Because DML is enabled, some elements of the output are hot links that you can click on. Click on the *data* link in the debug output to display information about items symbols that start with the letter a. + + ``` + 0: kd> x /D /f tabletaudiosample!a* + A B C D E F G H I J K L M N O P Q R S T U V W X Y Z + + fffff806`9adb1000 tabletaudiosample!AddDevice (struct _DRIVER_OBJECT *, struct _DEVICE_OBJECT *) + ``` + + For information, see [**x (Examine Symbols)**](x--examine-symbols-.md). + +4. The **!lmi** extension displays detailed information about a module. Type **!lmi tabletaudiosample**. Your output should be similar to the text shown below. + + ``` + 0: kd> !lmi tabletaudiosample + Loaded Module Info: [tabletaudiosample] + Module: tabletaudiosample + Base Address: fffff8069ad90000 + Image Name: tabletaudiosample.sys + Machine Type: 34404 (X64) + Time Stamp: 58ebe848 Mon Apr 10 13:17:12 2017 + Size: 48000 + CheckSum: 42df7 + Characteristics: 22 + Debug Data Dirs: Type Size VA Pointer + CODEVIEW a7, e5f4, d1f4 RSDS - GUID: {5395F0C5-AE50-4C56-AD31-DD5473BD318F} + Age: 1, Pdb: C:\Windows-driver-samples-master\audio\sysvad\TabletAudioSample\x64\Debug\TabletAudioSample.pdb + ?? 250, e69c, d29c [Data not mapped] + Image Type: MEMORY - Image read successfully from loaded memory. + Symbol Type: PDB - Symbols loaded successfully from image header. + C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\sym\TabletAudioSample.pdb\5395F0C5AE504C56AD31DD5473BD318F1\TabletAudioSample.pdb + Compiler: Resource - front end [0.0 bld 0] - back end [14.0 bld 24210] + Load Report: private symbols & lines, not source indexed + C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\sym\TabletAudioSample.pdb\5395F0C5AE504C56AD31DD5473BD318F1\TabletAudioSample.pdb + ``` + +5. Use the **!dh** extension to display header information as shown below. + + ``` + 0: kd> !dh tabletaudiosample + + File Type: EXECUTABLE IMAGE + FILE HEADER VALUES + 8664 machine (X64) + 9 number of sections + 5669DE8A time date stamp Thu Dec 10 12:20:26 2015 + + 0 file pointer to symbol table + 0 number of symbols + F0 size of optional header + 22 characteristics + Executable + App can handle >2gb addresses + ... + ``` + +## Section 6: Displaying Plug and Play device tree information + + +*In Section 6, you will display information about the Sysvad sample device driver and where it lives in the Plug and Play device tree.* + +Information about the device driver in the Plug and Play device tree can be useful for troubleshooting. For example, if a device driver is not resident in the device tree, there may an issue with the installation of the device driver. + +For more information about the device node debug extension, see [**!devnode**](-devnode.md). + +**<-On the host system** + +1. To see all the device nodes in the Plug and Play device tree, enter the **!devnode 0 1** command. This command can take a minute or two to run. During that time, "\*Busy" will be displayed in the status area of WinDbg. + + ``` + 0: kd> !devnode 0 1 + Dumping IopRootDeviceNode (= 0xffffe0005a3a8d30) + DevNode 0xffffe0005a3a8d30 for PDO 0xffffe0005a3a9e50 + InstancePath is "HTREE\ROOT\0" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe0005a3a3d30 for PDO 0xffffe0005a3a4e50 + InstancePath is "ROOT\volmgr\0000" + ServiceName is "volmgr" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe0005a324560 for PDO 0xffffe0005bd95ca0… + ... + ``` + +2. Use Ctrl+F to search in the output that is generated to look for the name of the device driver, *sysvad*. + + ![find dialog box showing the term sysvad being searched for](images/sysvad-lab-audio-find-dialog.png) + + A device node entry with a name of sysvad\_TabletAudioSample will be present in the !devnode output for Syvad. + + ``` + DevNode 0xffffe00086e68190 for PDO 0xffffe00089c575a0 + InstancePath is "ROOT\sysvad_TabletAudioSample\0000" + ServiceName is "sysvad_tabletaudiosample" + State = DeviceNodeStarted (0x308) + ... + ``` + + Note that the PDO address and the DevNode address are displayed. + +3. Use the **!devnode 0 1 sysvad\_TabletAudioSample** command to display Plug and Play information associated with our Sysvad device driver. + + ``` + 0: kd> !devnode 0 1 sysvad_TabletAudioSample + Dumping IopRootDeviceNode (= 0xffffe00082df8d30) + DevNode 0xffffe00086e68190 for PDO 0xffffe00089c575a0 + InstancePath is "ROOT\sysvad_TabletAudioSample\0000" + ServiceName is "sysvad_tabletaudiosample" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe000897fb650 for PDO 0xffffe00089927e30 + InstancePath is "SWD\MMDEVAPI\{0.0.0.00000000}.{64097438-cdc0-4007-a19e-62e789062e20}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe00086d2f5f0 for PDO 0xffffe00089939ae0 + InstancePath is "SWD\MMDEVAPI\{0.0.0.00000000}.{78880f4e-9571-44a4-a9df-960bde446487}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe00089759bb0 for PDO 0xffffe000875aa060 + InstancePath is "SWD\MMDEVAPI\{0.0.0.00000000}.{7cad07f2-d0a0-4b9b-8100-8dc735e9c447}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe00087735010 for PDO 0xffffe000872068c0 + InstancePath is "SWD\MMDEVAPI\{0.0.0.00000000}.{fc38551b-e69f-4b86-9661-ae6da78bc3c6}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe00088457670 for PDO 0xffffe0008562b830 + InstancePath is "SWD\MMDEVAPI\{0.0.1.00000000}.{0894b831-c9fe-4c56-86a6-092380fc5628}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe000893dbb70 for PDO 0xffffe00089d68060 + InstancePath is "SWD\MMDEVAPI\{0.0.1.00000000}.{15eb6b5c-aa54-47b8-959a-0cff2c1500db}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe00088e6f250 for PDO 0xffffe00089f6e990 + InstancePath is "SWD\MMDEVAPI\{0.0.1.00000000}.{778c07f0-af9f-43f2-8b8d-490024f87239}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + DevNode 0xffffe000862eb4b0 for PDO 0xffffe000884443a0 + InstancePath is "SWD\MMDEVAPI\{0.0.1.00000000}.{e4b72c7c-be50-45df-94f5-0f2922b85983}" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + ``` + +4. The output displayed in the previous command includes the PDO associated with the running instance of our driver, in this example it is *0xffffe00089c575a0*. Enter the **!devobj***<PDO address>* command to display Plug and Play information associated with the Sysvad device driver. Use the PDO address that **!devnode** displays on your PC, not the one shown here. + + ``` + 0: kd> !devobj 0xffffe00089c575a0 + Device object (ffffe00089c575a0) is for: + 0000004e \Driver\PnpManager DriverObject ffffe00082d47e60 + Current Irp 00000000 RefCount 65 Type 0000001d Flags 00001040 + SecurityDescriptor ffffc102b0f6d171 DevExt 00000000 DevObjExt ffffe00089c576f0 DevNode ffffe00086e68190 + ExtensionFlags (0000000000) + Characteristics (0x00000180) FILE_AUTOGENERATED_DEVICE_NAME, FILE_DEVICE_SECURE_OPEN + AttachedDevice (Upper) ffffe00088386a50 \Driver\sysvad_tabletaudiosample + Device queue is not busy. + ``` + +5. The output displayed in the **!devobj** command includes the name of the attached device: *\\Driver\\sysvad\_tabletaudiosample*. Use the **!drvobj** command with a bit mask of 2, to display information associated with the attached device. + + ``` + 0: kd> !drvobj \Driver\sysvad_tabletaudiosample 2 + Driver object (ffffe0008834f670) is for: + \Driver\sysvad_tabletaudiosample + DriverEntry: fffff80114b45310 tabletaudiosample!FxDriverEntry + DriverStartIo: 00000000 + DriverUnload: fffff80114b5fea0 tabletaudiosample!DriverUnload + AddDevice: fffff80114b5f000 tabletaudiosample!AddDevice + + Dispatch routines: + [00] IRP_MJ_CREATE fffff80117b49a20 portcls!DispatchCreate + [01] IRP_MJ_CREATE_NAMED_PIPE fffff8015a949a00 nt!IopInvalidDeviceRequest + [02] IRP_MJ_CLOSE fffff80115e26f90 ks!DispatchCleanup + [03] IRP_MJ_READ fffff80115e32710 ks!DispatchRead + [04] IRP_MJ_WRITE fffff80115e327e0 ks!DispatchWrite + [05] IRP_MJ_QUERY_INFORMATION fffff8015a949a00 nt!IopInvalidDeviceRequest + [06] IRP_MJ_SET_INFORMATION fffff8015a949a00 nt!IopInvalidDeviceRequest + [07] IRP_MJ_QUERY_EA fffff8015a949a00 nt!IopInvalidDeviceRequest + [08] IRP_MJ_SET_EA fffff8015a949a00 nt!IopInvalidDeviceRequest + [09] IRP_MJ_FLUSH_BUFFERS fffff80115e32640 ks!DispatchFlush + [0a] IRP_MJ_QUERY_VOLUME_INFORMATION fffff8015a949a00 nt!IopInvalidDeviceRequest + [0b] IRP_MJ_SET_VOLUME_INFORMATION fffff8015a949a00 nt!IopInvalidDeviceRequest + [0c] IRP_MJ_DIRECTORY_CONTROL fffff8015a949a00 nt!IopInvalidDeviceRequest + [0d] IRP_MJ_FILE_SYSTEM_CONTROL fffff8015a949a00 nt!IopInvalidDeviceRequest + [0e] IRP_MJ_DEVICE_CONTROL fffff80115e27480 ks!DispatchDeviceIoControl + [0f] IRP_MJ_INTERNAL_DEVICE_CONTROL fffff8015a949a00 nt!IopInvalidDeviceRequest + [10] IRP_MJ_SHUTDOWN fffff8015a949a00 nt!IopInvalidDeviceRequest + [11] IRP_MJ_LOCK_CONTROL fffff8015a949a00 nt!IopInvalidDeviceRequest + [12] IRP_MJ_CLEANUP fffff8015a949a00 nt!IopInvalidDeviceRequest + [13] IRP_MJ_CREATE_MAILSLOT fffff8015a949a00 nt!IopInvalidDeviceRequest + [14] IRP_MJ_QUERY_SECURITY fffff80115e326a0 ks!DispatchQuerySecurity + [15] IRP_MJ_SET_SECURITY fffff80115e32770 ks!DispatchSetSecurity + [16] IRP_MJ_POWER fffff80117b3dce0 portcls!DispatchPower + [17] IRP_MJ_SYSTEM_CONTROL fffff80117b13d30 portcls!PcWmiSystemControl + [18] IRP_MJ_DEVICE_CHANGE fffff8015a949a00 nt!IopInvalidDeviceRequest + [19] IRP_MJ_QUERY_QUOTA fffff8015a949a00 nt!IopInvalidDeviceRequest + [1a] IRP_MJ_SET_QUOTA fffff8015a949a00 nt!IopInvalidDeviceRequest + [1b] IRP_MJ_PNP fffff80114b5f7d0 tabletaudiosample!PnpHandler + ``` + +6. Enter the **!devstack***<PDO address>* command to display Plug and Play information associated with the device driver. The output displayed in the **!devnode 0 1** command includes the PDO address associated with the running instance of our driver. In this example it is *0xffffe00089c575a0*. Use the PDO address that **!devnode** displays on your PC, not the one shown below. + + ``` + 0: kd> !devstack 0xffffe00089c575a0 + !DevObj !DrvObj !DevExt ObjectName + ffffe00088d212e0 \Driver\ksthunk ffffe00088d21430 0000007b + ffffe00088386a50 \Driver\sysvad_tabletaudiosampleffffe00088386ba0 0000007a + > ffffe00089c575a0 \Driver\PnpManager 00000000 0000004e + !DevNode ffffe00086e68190 : + DeviceInst is "ROOT\sysvad_TabletAudioSample\0000" + ServiceName is "sysvad_tabletaudiosample" + ``` + +The output shows that we have a farily simple device driver stack. The sysvad\_TabletAudioSample driver is a child of the PnPManager node. The PnPManager is a root node. + +This diagram shows a more complex device node tree. + +![device node tree with about 20 nodes](images/debuglab-image-device-node-tree.png) + +**Note**  For more information about more complex driver stacks, see [Driver stacks](https://msdn.microsoft.com/library/windows/hardware/hh439632) and [Device nodes and device stacks](https://msdn.microsoft.com/library/windows/hardware/ff554721). + +  + +## Section 7: Working with breakpoints + + +*In Section 7, you will work with breakpoints to stop code execution at specific points.* + +**Setting breakpoints using commands** + +Breakpoints are used to stop code execution at a particular line of code. You can then step forward in the code from that point, to debug that specific section of code. + +To set a breakpoint using a debug command, use one of the following **b** commands. + + ++++ + + + + + + + + + + + + + + +

bp

Sets a breakpoint that will be active until the module it is in is unloaded.

bu

Sets a breakpoint that is unresolved when the module is unloaded and re-enables when the module reloads.

bm

Sets a breakpoint for a symbol. This command will use bu or bp appropriately and allows wildcards * to be used to set breakpoints on every symbols that matches (like all methods in a class).

+ +  + +1. Use the WinDbg UI to confirm that **Debug** > **Source Mode** is enabled in the current WinDbg session. + +2. Add your local code location to the source path by typing the following command. + + ``` + .sympath+ C:\WDK_Samples\Sysvad + ``` + +3. Add your local symbol location to the symbol path by typing the following command. + + ``` + .sympath+ C:\WDK_Samples\Sysvad + ``` + +4. **Set the debug mask** + + As you are working with a driver it can be handy to see all of the messages that it may display. Type the following to change the default debug bit mask so that all debug messages from the target system will be displayed in the debugger. + + ``` + 0: kd> ed nt!Kd_DEFAULT_MASK 0xFFFFFFFF + ``` + +5. Set the breakpoint with the **bm** command using the name of the driver, followed by the function name (AddDevice) where you want to set the breakpoint, separated by an exclamation mark. + + ``` + 0: kd> bm tabletaudiosample!AddDevice + breakpoint 1 redefined + 1: fffff801`14b5f000 @!"tabletaudiosample!AddDevice" + ``` + + You can use different syntax in conjunction with setting variables like <module>!<symbol>, <class>::<method>,‘<file.cpp>:<line number>’, or skip a number of times <condition> <\#>. For more information, see [Using Breakpoints](using-breakpoints.md). + +6. List the current breakpoints to confirm that the breakpoint was set by typing the **bl** command. + + ``` + 0: kd> bl + 1 e fffff801`14b5f000 0001 (0001) tabletaudiosample!AddDevice + ``` + +7. Restart code execution on the target system by typing the go command **g**. + +8. **->On the target system** + + In Windows, open Device Manager by using the icon or by entering **mmc devmgmt.msc**. In **Device Manager** expand the **Sound, video and game controllers** node. Right click the virtual audio driver entry and select **Disable** from the menu. + +9. Right click the virtual audio driver entry again and select **Enable** from the menu. +10. **<- On the host system** + + This should cause Windows to reload the driver, which calls AddDevice. This will cause the AddDevice debug breakpoint to fire and the execution of the driver code on the target system should halt. + + ``` + Breakpoint 1 hit + tabletaudiosample!AddDevice: + fffff801`14baf000 4889542410 mov qword ptr [rsp+10h],rdx + ``` + + If your source path is set properly, you should stop at the AddDevice routine in adapter.cpp + + ``` + { + PAGED_CODE(); + + NTSTATUS ntStatus; + ULONG maxObjects; + + DPF(D_TERSE, ("[AddDevice]")); + + maxObjects = g_MaxMiniports; + + #ifdef SYSVAD_BTH_BYPASS + // + // Allow three (3) Bluetooth hands-free profile devices. + // + maxObjects += g_MaxBthHfpMiniports * 3; + #endif // SYSVAD_BTH_BYPASS + + // Tell the class driver to add the device. + // + ntStatus = + PcAddAdapterDevice + ( + DriverObject, + PhysicalDeviceObject, + PCPFNSTARTDEVICE(StartDevice), + maxObjects, + 0 + ); + + + return ntStatus; + } // AddDevice + ``` + +11. Step line-by-line through the code by typing the **p** command or pressing F10. You can step forward out of the sysvad AddDevice code to PpvUtilCall, PnpCallAddDevice and then to the PipCallDriverAddDevice Windows code. You can provide a number to the **p** command to step forward multiple lines, for example *p 5*. + +12. When you are done stepping through the code, use the go command **g** to restart execution on the target system. + +**Setting memory access breakpoints** + +You can also set breakpoints that fire when a memory location is accessed. Use the **ba** (break on access) command, with the following syntax. + +``` +ba
{options} +``` + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionDescription

e

execute (when CPU fetches an instruction from the address)

r

read/write (when CPU reads or writes to the address)

w

write (when the CPU writes to the address)

+ +  + +Note that you can only set four data breakpoints at any given time and it is up to you to make sure that you are aligning your data correctly or you won’t trigger the breakpoint (words must end in addresses divisible by 2, dwords must be divisible by 4, and quadwords by 0 or 8) + +For example, to set a read/write breakpoint on a specific memory address, use a command like this. + +``` +ba r 4 fffff800`7bc9eff0 +``` + +**Modifying breakpoint state** + +You can modify existing breakpoints by using the following commands. + + ++++ + + + + + + + + + + + + + + + + + + +

bl

Lists breakpoints.

bc

Clears a breakpoint from the list. Use bc * to clear all breakpoints.

bd

Disables a breakpoint. Use bd * to disable all breakpoints.

be

Enables a breakpoint. Use be * to enable all breakpoints.

+ +  + +Alternatively, you can also modify breakpoints by clicking **edit** > **breakpoints**. Note that the breakpoint dialog box only works with existing breakpoints. New breakpoints must be set from the command line. + +**Set a breakpoint on MixerVolume** + +Different parts of the audio driver code is called to respond to various events, after the device driver is loaded. In the next section, we set a breakpoint that will fire when the user adjusts the volume control for the virtual audio driver. + +To set a breakpoint on MixerVolume, perform the following steps. + +1. **<- On the host system** + + To locate the method that changes the volume, use the x command to list the symbols in CAdapterCommon, that contain the string volume. + + ``` + kd> x tabletaudiosample!CAdapterCommon::* + ... + fffff800`7bce26a0 tabletaudiosample!CAdapterCommon::MixerVolumeWrite (unsigned long, unsigned long, long) + … + ``` + + Use CTRL+F to search upward in the output for volume and locate the MixerVolumeWrite method. + +2. Clear the previous breakpoints using bc \*. +3. Set a symbol breakpoint on the CAdapterCommon::MixerVolumeWrite routine using the following command. + + ``` + kd> bm tabletaudiosample!CAdapterCommon::MixerVolumeWrite + 1: fffff801`177b26a0 @!"tabletaudiosample!CAdapterCommon::MixerVolumeWrite" + ``` + +4. List the breakpoints to confirm that the breakpoint is set properly. + + ``` + kd> bl + 1 e fffff801`177b26a0 [c:\WDK_Samples\audio\sysvad\common.cpp @ 1668] 0001 (0001) tabletaudiosample!CAdapterCommon::MixerVolumeWrite + ``` + +5. Restart code execution on the target system by typing the go command **g**. + +6. In Control Panel select **Hardware and Sound** >**Sound**. Right click **Sink Description Sample** and select **Properties**. Select the **Levels** tab. Adjust the slider volume. + +7. This should cause the SetMixerVolume debug breakpoint to fire and execution of the driver code on the target system should halt. + + ``` + kd> g + Breakpoint 1 hit + tabletaudiosample!CAdapterCommon::MixerVolumeWrite: + fffff801`177b26a0 44894c2420 mov dword ptr [rsp+20h],r9d + ``` + + You should stop at this line in common.cpp + + ``` + { + if (m_pHW) + { + m_pHW->SetMixerVolume(Index, Channel, Value); + } + } // MixerVolumeWrite + ``` + +8. Use the dv command to display the current variables and their values. More information on variables is provided in the next section of this lab. + + ``` + 2: kd> dv + this = 0x00000000`00000010 + ulNode = 0x344 + ulChannel = 0x210a45f8 + lVolume = 0n24 + ``` + +9. Press **F10** to single step through the code. + +10. Press **F5** to finish the execution of the MixerVolumeWrite code. + +**Summary - Stepping through code from the Debugger Command window** + +The following are the commands that you can use to step through your code (with the associated keyboard short cuts shown in parentheses). + +- Break in (Ctrl+Break) - This command will interrupt a system as long as the system is running and is in communication with WinDbg (the sequence in the Kernel Debugger is Ctrl+C). + +- Step over (F10) – This command causes code execution to proceed one statement or one instruction at a time. If a call is encountered, code execution passes over the call without entering the called routine. (If the programming language is C or C++ and WinDbg is in source mode, source mode can be turned on or off using **Debug**>**Source Mode**). + +- Step in (F11) – This command is like step-over, except that the execution of a call does go into the called routine. + +- Step out (Shift+F11) – This command causes execution to run to and exit from the current routine (current place in the call stack). This is useful if you've seen enough of the routine. + +- Run to cursor (F7 or Ctrl+F10) – Place the cursor in a source or disassembly window where you want the execution to break, then press F7; code execution will run to that point. Note that if the flow of code execution does not reach the point indicated by the cursor (e.g., an IF statement isn't executed), WinDbg would not break, because the code execution did not reach the indicated point. + +- Run (F5) – Run until a breakpoint is encountered or an event like a bug check occurs. + +**Advanced options** + +- Set instruction to the current line (Ctrl+Shift+I) – In a source window, you can place your cursor on a line, enter this keyboard shortcut, and code execution will start from that point as soon as you let it proceed (for example using F5 or F10). This is handy if you want to retry a sequence, but it requires some care. For example, registers and variables are not set to what they would be if code execution had reached that line naturally. + +- Direct setting of the eip register -- You can put a value into the eip register, and as soon as you press F5 (or F10, F11, etc.), execution commences from that address. This is similar to setting instruction to the cursor-designated current line, except that you specify the address of an assembly instruction. + +It can be easier to step through UI rather than from the command line so this method is recommended. If necessary, the following commands can be used to step through a source file at the command line: + +- .lines - Enable source line information. + +- bp main - Set the initial breakpoint at the beginning of your module. + +- l+t - Stepping will be done by source line. + +- Select **Debug**>**Source Mode** to enter source mode; the `L+t` command is not sufficient. + +- l+s - Source lines will be displayed at prompt. + +- g - Run program until "main" is entered. + +- p - Execute one source line. + +For more information, see [Source Code Debugging in WinDbg](source-window.md) in the debugging reference documentation. + +**Set breakpoints in code** + +You can set a breakpoint in code by adding the `DebugBreak()` statement and rebuilding the project and re-installing the driver. This breakpoint will fire each time the driver is enabled, so it would be a techniques to be used in the early development stages, not in production code. This technique is not as flexible as dynamically setting breakpoints using the breakpoint commands. + +Tip: You may want to keep a copy of the Sysvad driver with out the breakpoint added for further lab work. + +1. Set a break to occur each time the AddDevice method is run by adding the `DebugBreak()` statement to the sample code. + + ``` + ... + // Insert the DebugBreak() statment before the PcAddAdapterDevice is called. + // + + DebugBreak() + + // Tell the class driver to add the device. + // + ntStatus = + PcAddAdapterDevice + ( + DriverObject, + PhysicalDeviceObject, + PCPFNSTARTDEVICE(StartDevice), + maxObjects, + 0 + ); + + return ntStatus; + } // AddDevice + ``` + +2. Follow all of the steps previously described to rebuild the driver in Microsoft Visual Studio and re-install it to the target machine. Be sure to uninstall the existing driver before installing the updated driver. +3. Clear any previous breakpoints and make sure that the debugger is attached to the target PC. + +4. When the code runs and reaches the `DebugBreak` statement, execution will stop and a message will be displayed. + + ``` + KERNELBASE!DebugBreak: + 77b3b770 defe     __debugbreak + ``` + +## Section 8: Display variables + + +*In Section 8, you will use debugger commands to display variables.* + +It can be useful to examine variables as the code executes to confirm that the code is working as expected. This labs examines variables as the audio driver produces sound. + +1. Use the **dv** command to examine the locale variables associated with the tabletaudiosample!CMiniportWaveRT::New\*. + + ``` + kd> dv tabletaudiosample!CMiniportWaveRT::New* + ``` + +2. Clear the previous breakpoints + + ``` + bc * + ``` + +3. Set a symbol breakpoint on the CMiniportWaveCyclicStreamMSVAD routines using the following command. + + ``` + 0: kd> bm tabletaudiosample!CMiniportWaveRT::NewStream + 1: fffff801`177dffc0 @!"tabletaudiosample!CMiniportWaveRT::NewStream" + ``` + +4. Restart code execution on the target system by typing the go command **g**. + +5. **-> On the target system** + + Locate a small media file (such as Windows notification sound file with a .wav file extension) and click the file to play it. For example you can use Ring05.wav located in the Windows\\Media directory. + +6. **<- On the host system** + + When the media file is played, the breakpoint should fire, and execution of the driver code on the target system should halt. + + ``` + Breakpoint 1 hit + tabletaudiosample!CMiniportWaveRT::NewStream: + fffff801`177dffc0 44894c2420 mov dword ptr [rsp+20h],r9d + ``` + + The source code Window should be highlighting the brace on the entrance to the NewStream function. + + ``` + /*++ + + Routine Description: + + The NewStream function creates a new instance of a logical stream + associated with a specified physical channel. Callers of NewStream should + run at IRQL PASSIVE_LEVEL. + + Arguments: + + OutStream - + + OuterUnknown - + + Pin - + + Capture - + + DataFormat - + + Return Value: + + NT status code. + + --*/ + { + + ... + ``` + +7. **Local variables** + + You can display the names and values of all local variables for a given frame by typing the **dv** command. + + ``` + 0: kd> dv + this = 0xffffe000`4436f8e0 + OutStream = 0xffffe000`49d2f130 + OuterUnknown = 0xffffe000`4436fa30 + Pin = 0 + Capture = 0x01 ' + DataFormat = 0xffffe000`44227790 + signalProcessingMode = {487E9220-E000-FFFF-30F1-D24900E0FFFF} + ntStatus = 0n1055 + stream = 0x00000000`00000200 + ``` + +8. **Use DML to Display Variables** + + To use DML to explore variables, click the underlined elements. The click action builds a [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) command that allows you to drill down on nested data structures. + + ``` + 0: kd> dx -r1 (*((tabletaudiosample!CMiniportWaveRT *)0xffffe001d10b8380)) + (*((tabletaudiosample!CMiniportWaveRT *)0xffffe001d10b8380)) : [Type: CMiniportWaveRT] + [+0x020] m_lRefCount : 0 + [+0x028] m_pUnknownOuter : 0xffffe001d1477e50 : [Type: IUnknown *] + [+0x030] m_ulLoopbackAllocated : 0x2050 + [+0x034] m_ulSystemAllocated : 0x180 + [+0x038] m_ulOffloadAllocated : 0x0 + [+0x03c] m_dwCaptureAllocatedModes : 0x0 + + 0: kd> dx -r1 (*((tabletaudiosample!_GUID *)0xffffd001c8acd348)) + (*((tabletaudiosample!_GUID *)0xffffd001c8acd348)) : {487E9220-E000-FFFF-30F1-D24900E0FFFF} [Type: _GUID] + [] + + 0: kd> dx -r1 -n (*((tabletaudiosample!_GUID *)0xffffd001c8acd348)) + (*((tabletaudiosample!_GUID *)0xffffd001c8acd348)) : [Type: _GUID] + [+0x000] Data1 : 0x487e9220 + [+0x004] Data2 : 0xe000 + [+0x006] Data3 : 0xffff + [+0x008] Data4 : [Type: unsigned char [8]] + + + 0: kd> dx -r1 -n (*((tabletaudiosample!unsigned char (*)[8])0xffffd001c8acd350)) + (*((tabletaudiosample!unsigned char (*)[8])0xffffd001c8acd350)) : [Type: unsigned char [8]] + [0] : 0x30 + [1] : 0xf1 + [2] : 0xd2 + [3] : 0x49 + [4] : 0x0 + [5] : 0xe0 + [6] : 0xff + [7] : 0xff + ``` + +9. **Global variables** + + You can find the memory location of a global variable by typing **? <variable name>**. + + ``` + 0: kd> ? signalProcessingMode + Evaluate expression: -52768896396472 = ffffd001`c8acd348 + ``` + +10. This returns the memory location of the variable, in this case *ffffd001\`c8acd348*. You can view the contents of the memory location by dumping the value of that location typing the **dd** command using the memory location returned by the previous command. + + ``` + 0: kd> dd ffffd001`c8acd348 + ffffd001`c8acd348 487e9220 ffffe000 49d2f130 ffffe000 + ffffd001`c8acd358 4837c468 ffffe000 18221570 ffffc000 + ffffd001`c8acd368 4436f8e0 ffffe000 487e9220 ffffe000 + ffffd001`c8acd378 18ab145b fffff801 4837c420 ffffe000 + ffffd001`c8acd388 4436f8e0 ffffe000 49d2f130 ffffe000 + ffffd001`c8acd398 4436fa30 ffffe000 00000000 00000000 + ffffd001`c8acd3a8 00000001 00000000 44227790 ffffe000 + ffffd001`c8acd3b8 18adc7f9 fffff801 495972a0 ffffe000 + ``` + +11. You can also use variable names with the **dd** command. + + ``` + 0: kd> dd signalProcessingMode + ffffd001`c8acd348 487e9220 ffffe000 49d2f130 ffffe000 + ffffd001`c8acd358 4837c468 ffffe000 18221570 ffffc000 + ffffd001`c8acd368 4436f8e0 ffffe000 487e9220 ffffe000 + ffffd001`c8acd378 18ab145b fffff801 4837c420 ffffe000 + ffffd001`c8acd388 4436f8e0 ffffe000 49d2f130 ffffe000 + ffffd001`c8acd398 4436fa30 ffffe000 00000000 00000000 + ffffd001`c8acd3a8 00000001 00000000 44227790 ffffe000 + ffffd001`c8acd3b8 18adc7f9 fffff801 495972a0 ffffe000 + ``` + +12. **Display variables** + + Use the **View**> **Locals** menu item to display local variables. This interface also provides this ability to drill down on more complex data structures. + + ![windbg showing sample code locals and command windows](images/sysvad-lab-display-variables.png) + +13. Use p or F10 to step forward about 10 lines in the code until you are highlighting the ntStatus = IsFormatSupported(Pin, Capture, DataFormat); line of code. + + ``` + PAGED_CODE(); + + ASSERT(OutStream); + ASSERT(DataFormat); + + DPF_ENTER(("[CMiniportWaveRT::NewStream]")); + + NTSTATUS ntStatus = STATUS_SUCCESS; + PCMiniportWaveRTStream stream = NULL; + GUID signalProcessingMode = AUDIO_SIGNALPROCESSINGMODE_DEFAULT; + + *OutStream = NULL; + + // + // If the data format attributes were specified, extract them. + // + if ( DataFormat->Flags & KSDATAFORMAT_ATTRIBUTES ) + { + // The attributes are aligned (QWORD alignment) after the data format + PKSMULTIPLE_ITEM attributes = (PKSMULTIPLE_ITEM) (((PBYTE)DataFormat) + ((DataFormat->FormatSize + FILE_QUAD_ALIGNMENT) & ~FILE_QUAD_ALIGNMENT)); + ntStatus = GetAttributesFromAttributeList(attributes, attributes->Size, &signalProcessingMode); + } + + // Check if we have enough streams. + // + if (NT_SUCCESS(ntStatus)) + { + ntStatus = ValidateStreamCreate(Pin, Capture, signalProcessingMode); + } + + // Determine if the format is valid. + // + if (NT_SUCCESS(ntStatus)) + { + ntStatus = IsFormatSupported(Pin, Capture, DataFormat); + } + + ... + ``` + +14. Use the **dv** command to display the names and values of all local variables for a given frame. Note that, as expected, the values are different from the last time we ran this command, as additional code has been run that changes the local variables and some variables are now not in the current frame or their values have changed. + + ``` + 2: kd> dv + this = 0xffffe001`d1182000 + OutStream = 0xffffe001`d4776d20 + OuterUnknown = 0xffffe001`d4776bc8 + Pin = 0 + Capture = 0x00 ' + DataFormat = 0xffffe001`cd7609b0 + signalProcessingMode = {4780004E-7133-41D8-8C74-660DADD2C0EE} + ntStatus = 0n0 + stream = 0x00000000`00000000 + ``` + +## Section 9: View call stacks + + +*In Section 9, you will view call stacks to examine caller/calle code.* + +The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, and the next function is the function that called the current function, and so on. + +To display the call stack, use the k\* commands: + + ++++ + + + + + + + + + + + + + + +

kb

Displays the stack and first three parameters.

kp

Displays the stacks and the full list of parameters.

kn

Allows you to see the stack with the frame information next to it.

+ +  + +If you want to keep the call stack available, you can click **View**> **Call stack** to view it. Click the columns at the top of the window to toggle the display of additional information. + +![windbg call stack window](images/sysvad-lab-call-stack.png) + +This output shows the call stack while debugging the sample adapter code in a break state. + +``` +0: kd> kb +# RetAddr : Args to Child : Call Site +00 fffff800`7a0fa607 : ffffe001`d1182000 ffffe001`d4776d20 ffffe001`d4776bc8 ffffe001`00000000 : tabletaudiosample!CMiniportWaveRT::NewStream+0x1dc [c:\data1\threshold\audio\endpointscommon\minwavert.cpp @ 597] +01 fffff800`7a0fb2c3 : 00000000`00000000 ffffe001`d122bb10 ffffe001`ceb81750 ffffe001`d173f058 : portcls!CPortPinWaveRT::Init+0x2e7 +02 fffff800`7a0fc7f9 : ffffe001`d4776bc0 00000000`00000000 ffffe001`d10b8380 ffffe001`d122bb10 : portcls!CPortFilterWaveRT::NewIrpTarget+0x193 +03 fffff800`7a180552 : 00000000`00000000 ffffe001`d10b8380 ffffe001`d122bb10 ffffe001`d4565600 : portcls!xDispatchCreate+0xd9 +04 fffff800`7a109a9a : ffffe001`d10b84d0 ffffe001`d10b8380 00000000`00000000 ffffe001`00000000 : ks!KsDispatchIrp+0x272 +05 fffff800`7bd314b1 : ffffe001`d122bb10 ffffd001`c3098590 ffffe001`d122bd90 ffffe001`ce80da70 : portcls!DispatchCreate+0x7a +06 fffff803`cda1bfa8 : 00000000`00000024 00000000`00000000 00000000`00000000 ffffe001`d122bb10 : ksthunk!CKernelFilterDevice::DispatchIrp+0xf9 +07 fffff803`cda7b306 : 00000000`000001f0 ffffe001`d48ce690 ffffe001`d13d6400 ffffe001`d13d64c0 : nt!IopParseDevice+0x7c8 +08 fffff803`cda12916 : 00000000`000001f0 ffffd001`c30988d0 ffffe001`d13d6490 fffff803`cda7b250 : nt!IopParseFile+0xb6 +09 fffff803`cda1131c : ffffe001`d2ccb001 ffffd001`c30989e0 00ffffe0`00000040 ffffe001`cd127dc0 : nt!ObpLookupObjectName+0x776 +0a fffff803`cd9fedb8 : ffffe001`00000001 ffffe001`d48ce690 00000000`00000000 00000000`00000000 : nt!ObOpenObjectByNameEx+0x1ec +0b fffff803`cd9fe919 : 000000ee`6d1fc8d8 000000ee`6d1fc788 000000ee`6d1fc7e0 000000ee`6d1fc7d0 : nt!IopCreateFile+0x3d8 +0c fffff803`cd752fa3 : ffffc000`1f296870 fffff803`cd9d9fbd ffffd001`c3098be8 00000000`00000000 : nt!NtCreateFile+0x79 +0d 00007fff`69805b74 : 00007fff`487484e6 0000029b`00000003 00000000`0000012e 00000000`00000000 : nt!KiSystemServiceCopyEnd+0x13 +0e 00007fff`487484e6 : 0000029b`00000003 00000000`0000012e 00000000`00000000 00000000`00000000 : 0x00007fff`69805b74 +0f 0000029b`00000003 : 00000000`0000012e 00000000`00000000 00000000`00000000 00000000`00000000 : 0x00007fff`487484e6 +10 00000000`0000012e : 00000000`00000000 00000000`00000000 00000000`00000000 00000000`00000080 : 0x0000029b`00000003 +11 00000000`00000000 : 00000000`00000000 00000000`00000000 00000000`00000080 00000000`00000000 : 0x12e +``` + +You can use DML to further explore the code. When you click on the first 00 entry, the [**.frame (Set Local Context)**](-frame--set-local-context-.md) command is used to set the context and then, the [**dv (Display Local Variables)**](dv--display-local-variables-.md) command displays the local variables. + +``` +0: kd> .frame 0n0;dv /t /v +00 ffffd001`c30981d0 fffff800`7a0fa607 tabletaudiosample!CMiniportWaveRT::NewStream+0x1dc [c:\data1\threshold\audio\endpointscommon\minwavert.cpp @ 597] +ffffd001`c30982b0 class CMiniportWaveRT * this = 0xffffe001`d1182000 +ffffd001`c30982b8 struct IMiniportWaveRTStream ** OutStream = 0xffffe001`d4776d20 +ffffd001`c30982c0 struct IPortWaveRTStream * OuterUnknown = 0xffffe001`d4776bc8 +ffffd001`c30982c8 unsigned long Pin = 0 +ffffd001`c30982d0 unsigned char Capture = 0x00 ' +ffffd001`c30982d8 union KSDATAFORMAT * DataFormat = 0xffffe001`cd7609b0 +ffffd001`c3098270 struct _GUID signalProcessingMode = {4780004E-7133-41D8-8C74-660DADD2C0EE} +ffffd001`c3098210 long ntStatus = 0n0 +ffffd001`c3098218 class CMiniportWaveRTStream * stream = 0x00000000`00000000 +``` + +## Section 10: Display processes and threads + + +*In Section 10, you will use debugger commands to display processes and threads.* + +**Process** + +To change the current process context, use the .process <process> command. The following example demonstrates how to identify a process and switch context to it. + +- Use the `!process` command to display the current process that is involved in playing the sound. + + For more information see [**!process**](-process.md) + +The output shows that the process is associated with audiodg.exe. If you are still at the breakpoint described in the previous section of this topic, the current process should be associated with the audiodg.exe image. + +**<- On the host system** + +``` +0: kd> !process +PROCESS ffffe001d147c840 + SessionId: 0 Cid: 10f0 Peb: ee6cf8a000 ParentCid: 0434 + DirBase: d2122000 ObjectTable: ffffc0001f191ac0 HandleCount: + Image: audiodg.exe + VadRoot ffffe001d4222f70 Vads 70 Clone 0 Private 504. Modified 16. Locked 0. + DeviceMap ffffc00019113080 + Token ffffc0001f1d4060 + ElapsedTime + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + QuotaPoolUsage[PagedPool] 81632 + QuotaPoolUsage[NonPagedPool] 9704 + Working Set Sizes (now,min,max) (2154, 1814, 2109) (8616KB, 7256KB, 8436KB) + PeakWorkingSetSize 2101 + VirtualSize 2097192 Mb + PeakVirtualSize 2097192 Mb + PageFaultCount 2336 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 1573 + + THREAD ffffe001d173e840 Cid 10f0.1dac Teb: 000000ee6cf8b000 Win32Thread: ffffe001d1118cf0 WAIT: (UserRequest) UserMode Non-Alertable + ffffe001d16c4dd0 NotificationEvent + ffffe001d08b0840 ProcessObject + + THREAD ffffe001ceb77080 Cid 10f0.16dc Teb: 000000ee6cf8d000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001cf2d1840 QueueObject + + THREAD ffffe001d112c840 Cid 10f0.0a4c Teb: 000000ee6cf8f000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001cf2d1840 QueueObject + + THREAD ffffe001d16c7840 Cid 10f0.13c4 Teb: 000000ee6cf91000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001cf2d1840 QueueObject + + THREAD ffffe001cec67840 Cid 10f0.0dbc Teb: 000000ee6cf93000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001d173e5c0 QueueObject + + THREAD ffffe001d1117840 Cid 10f0.1d6c Teb: 000000ee6cf95000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001d173e5c0 QueueObject + + THREAD ffffe001cdeae840 Cid 10f0.0298 Teb: 000000ee6cf97000 Win32Thread: 0000000000000000 RUNNING on processor 2 +``` + +Note that one of the threads associated with this process is in the RUNNING state. This thread was supporting the playing of the media clip when the breakpoint was hit. + +Use the **!process 0 0** command to display summary information for all processes. In the command output use CTRL+F to locate the process ID for the process associated with the audiodg.exe image. In the example shown below, the process ID is *ffffe001d147c840*. + +Record the process ID associated with audiodg.exe on your PC to use later in this lab. \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +``` +... + +PROCESS ffffe001d147c840 + SessionId: 0 Cid: 10f0 Peb: ee6cf8a000 ParentCid: 0434 + DirBase: d2122000 ObjectTable: ffffc0001f191ac0 HandleCount: + Image: audiodg.exe +... +``` + +Enter g into the debugger to run the code forward until the media clip is done playing. Then break in to the debugger, by pressing Ctrl+ScrLk (Ctrl+Break) Use the !process command to confirm that you are now running a different process. + +``` +!process +PROCESS ffffe001cd0ad040 + SessionId: none Cid: 0004 Peb: 00000000 ParentCid: 0000 + DirBase: 001aa000 ObjectTable: ffffc00017214000 HandleCount: + Image: System + VadRoot ffffe001d402b820 Vads 438 Clone 0 Private 13417. Modified 87866. Locked 64. + DeviceMap ffffc0001721a070 + Token ffffc00017216a60 + ElapsedTime 05:04:54.716 + UserTime 00:00:00.000 + KernelTime 00:00:20.531 + QuotaPoolUsage[PagedPool] 0 + QuotaPoolUsage[NonPagedPool] 0 + Working Set Sizes (now,min,max) (1720, 50, 450) (6880KB, 200KB, 1800KB) + PeakWorkingSetSize 15853 + VirtualSize 58 Mb + PeakVirtualSize 74 Mb + PageFaultCount 46128 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 66 + + THREAD ffffe001cd0295c0 Cid 0004.000c Teb: 0000000000000000 Win32Thread: 0000000000000000 WAIT: (Executive) KernelMode Non-Alertable + fffff803cd8e0120 SynchronizationEvent + + THREAD ffffe001cd02a6c0 Cid 0004.0010 Teb: 0000000000000000 Win32Thread: 0000000000000000 WAIT: (Executive) KernelMode Non-Alertable + fffff803cd8e0ba0 Semaphore Limit 0x7fffffff +... +``` + +The output above shows that a different system process of *ffffe001cd0ad040* is running. The image name shows System, not audiodg.exe. + +Now use the !process command to switch to the process that was associated with audiodg.exe. In the example, the process ID is *ffffe001d147c840*. Substitute the process ID in the example with your process ID, that you recorded earlier. + +``` +0: kd> !process ffffe001d147c840 +PROCESS ffffe001d147c840 + SessionId: 0 Cid: 10f0 Peb: ee6cf8a000 ParentCid: 0434 + DirBase: d2122000 ObjectTable: ffffc0001f191ac0 HandleCount: + Image: audiodg.exe + VadRoot ffffe001d4222f70 Vads 60 Clone 0 Private 299. Modified 152. Locked 0. + DeviceMap ffffc00019113080 + Token ffffc0001f1d4060 + ElapsedTime 1 Day 01:53:14.490 + UserTime 00:00:00.031 + KernelTime 00:00:00.031 + QuotaPoolUsage[PagedPool] 81552 + QuotaPoolUsage[NonPagedPool] 8344 + Working Set Sizes (now,min,max) (1915, 1814, 2109) (7660KB, 7256KB, 8436KB) + PeakWorkingSetSize 2116 + VirtualSize 2097189 Mb + PeakVirtualSize 2097192 Mb + PageFaultCount 2464 + MemoryPriority BACKGROUND + BasePriority 8 + CommitCharge 1418 + + THREAD ffffe001d173e840 Cid 10f0.1dac Teb: 000000ee6cf8b000 Win32Thread: ffffe001d1118cf0 WAIT: (UserRequest) UserMode Non-Alertable + ffffe001d16c4dd0 NotificationEvent + ffffe001d08b0840 ProcessObject + Not impersonating + DeviceMap ffffc00019113080 + Owning Process ffffe001d147c840 Image: audiodg.exe + Attached Process N/A Image: N/A + Wait Start TickCount 338852 Ticks: 197682 (0:00:51:28.781) + Context Switch Count 36 IdealProcessor: 0 + UserTime 00:00:00.015 + KernelTime 00:00:00.000 + Win32 Start Address 0x00007ff7fb928de0 + Stack Init ffffd001c2ec6dd0 Current ffffd001c2ec60c0 + Base ffffd001c2ec7000 Limit ffffd001c2ec1000 Call 0 + Priority 8 BasePriority 8 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 + Kernel stack not resident. + + THREAD ffffe001d115c080 Cid 10f0.15b4 Teb: 000000ee6cf9b000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001d0bf0640 QueueObject + Not impersonating + DeviceMap ffffc00019113080 + Owning Process ffffe001d147c840 Image: audiodg.exe + Attached Process N/A Image: N/A + Wait Start TickCount 338852 Ticks: 197682 (0:00:51:28.781) + Context Switch Count 1 IdealProcessor: 0 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + Win32 Start Address 0x00007fff6978b350 + Stack Init ffffd001c3143dd0 Current ffffd001c3143520 + Base ffffd001c3144000 Limit ffffd001c313e000 Call 0 + Priority 8 BasePriority 8 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 + Kernel stack not resident. + + THREAD ffffe001d3a27040 Cid 10f0.17f4 Teb: 000000ee6cf9d000 Win32Thread: 0000000000000000 WAIT: (WrQueue) UserMode Alertable + ffffe001d173e5c0 QueueObject + Not impersonating + DeviceMap ffffc00019113080 + Owning Process ffffe001d147c840 Image: audiodg.exe + Attached Process N/A Image: N/A + Wait Start TickCount 518918 Ticks: 17616 (0:00:04:35.250) + Context Switch Count 9 IdealProcessor: 1 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + Win32 Start Address 0x00007fff6978b350 + Stack Init ffffd001c70c6dd0 Current ffffd001c70c6520 + Base ffffd001c70c7000 Limit ffffd001c70c1000 Call 0 + Priority 9 BasePriority 8 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 + Kernel stack not resident. +``` + +Because this code is not active, all of the threads are in WAIT state, as expected. + +**Threads** + +The commands to view and set threads are very similar to those of processes. Use the [**!thread**](-thread.md) command to view threads. Use [**.thread**](-thread--set-register-context-.md) to set the current threads. + +To explore threads associated with the media player, play the media clip again. If the breakpoint described in the previous section is still in place, you will stop in the context of audiodg.exe. + +Use the !thread -1 0 to display brief information for the current thread. This shows the thread address, the thread and process IDs, the thread environment block (TEB) address, the address of the Win32 function (if any) the thread was created to run, and the thread’s scheduling state. + +``` +0: kd> !thread -1 0 +THREAD ffffe001d3a27040 Cid 10f0.17f4 Teb: 000000ee6cf9d000 Win32Thread: 0000000000000000 RUNNING on processor 0 +``` + +To view more information about the thread that is running, type [**!thread**](-thread.md). Information similar to the following should be displayed. + +``` +0: kd> !thread +THREAD ffffe001d3a27040 Cid 10f0.17f4 Teb: 000000ee6cf9d000 Win32Thread: 0000000000000000 RUNNING on processor 0 +IRP List: + ffffe001d429e580: (0006,02c8) Flags: 000008b4 Mdl: 00000000 +Not impersonating +DeviceMap ffffc00019113080 +Owning Process ffffe001d147c840 Image: audiodg.exe +Attached Process N/A Image: N/A +Wait Start TickCount 537630 Ticks: 0 +Context Switch Count 63 IdealProcessor: 1 +UserTime 00:00:00.000 +KernelTime 00:00:00.015 +Win32 Start Address 0x00007fff6978b350 +Stack Init ffffd001c70c6dd0 Current ffffd001c70c6520 +Base ffffd001c70c7000 Limit ffffd001c70c1000 Call 0 +Priority 8 BasePriority 8 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 +Child-SP RetAddr : Args to Child : Call Site +ffffd001`c70c62a8 fffff800`7a0fa607 : ffffe001`d4aec5c0 ffffe001`cdefd3d8 ffffe001`d4aec5c0 ffffe001`cdefd390 : tabletaudiosample!CMiniportWaveRT::NewStream [c:\data1\threshold\audio\endpointscommon\minwavert.cpp @ 562] +ffffd001`c70c62b0 fffff800`7a0fb2c3 : 00000000`00000000 ffffe001`d429e580 ffffe001`d4ea47b0 ffffe001`cdefd3d8 : portcls!CPortPinWaveRT::Init+0x2e7 +ffffd001`c70c6340 fffff800`7a0fc7f9 : ffffe001`d4aec430 00000000`00000000 ffffe001`d10b8380 ffffe001`d429e580 : portcls!CPortFilterWaveRT::NewIrpTarget+0x193 +ffffd001`c70c63c0 fffff800`7a180552 : 00000000`00000000 ffffe001`d10b8380 ffffe001`d429e580 ffffe001`d4565600 : portcls!xDispatchCreate+0xd9 +ffffd001`c70c6450 fffff800`7a109a9a : ffffe001`d10b84d0 ffffe001`d10b8380 00000000`00000000 ffffe001`00000000 : ks!KsDispatchIrp+0x272 +ffffd001`c70c6510 fffff800`7bd314b1 : ffffe001`d429e580 ffffd001`c70c6590 ffffe001`d429e800 ffffe001`ce80da70 : portcls!DispatchCreate+0x7a +ffffd001`c70c6540 fffff803`cda1bfa8 : 00000000`00000025 00000000`00000000 00000000`00000000 ffffe001`d429e580 : ksthunk!CKernelFilterDevice::DispatchIrp+0xf9 +ffffd001`c70c65a0 fffff803`cda7b306 : 00000000`000002fc ffffe001`d5e0d510 00000000`00000000 ffffe001`d3341bd0 : nt!IopParseDevice+0x7c8 +ffffd001`c70c6770 fffff803`cda12916 : 00000000`000002fc ffffd001`c70c68d0 ffffe001`d3341ba0 fffff803`cda7b250 : nt!IopParseFile+0xb6 +ffffd001`c70c67d0 fffff803`cda1131c : ffffe001`ceb6c601 ffffd001`c70c69e0 00000000`00000040 ffffe001`cd127dc0 : nt!ObpLookupObjectName+0x776 +ffffd001`c70c6970 fffff803`cd9fedb8 : ffff8ab8`00000001 ffffe001`d5e0d510 00000000`00000000 00000000`00000000 : nt!ObOpenObjectByNameEx+0x1ec +ffffd001`c70c6a90 fffff803`cd9fe919 : 000000ee`6d37c6e8 00000004`6d37c500 000000ee`6d37c5f0 000000ee`6d37c5e0 : nt!IopCreateFile+0x3d8 +ffffd001`c70c6b40 fffff803`cd752fa3 : fffff6fb`7da05360 fffff6fb`40a6c0a8 fffff681`4d815760 ffff8ab8`92895e23 : nt!NtCreateFile+0x79 +ffffd001`c70c6bd0 00007fff`69805b74 : 00007fff`487484e6 0000029b`00000003 00000000`0000012e 00000000`00000000 : nt!KiSystemServiceCopyEnd+0x13 (TrapFrame @ ffffd001`c70c6c40) +000000ee`6d37c568 00007fff`487484e6 : 0000029b`00000003 00000000`0000012e 00000000`00000000 00000000`00000000 : 0x00007fff`69805b74 +000000ee`6d37c570 0000029b`00000003 : 00000000`0000012e 00000000`00000000 00000000`00000000 00000000`00000000 : 0x00007fff`487484e6 +000000ee`6d37c578 00000000`0000012e : 00000000`00000000 00000000`00000000 00000000`00000000 00000000`00000080 : 0x0000029b`00000003 +000000ee`6d37c580 00000000`00000000 : 00000000`00000000 00000000`00000000 00000000`00000080 00000000`00000000 : 0x12e +``` + +Use the k command to view the call stack associated with the thread. + +``` +0: kd> k +# Child-SP RetAddr Call Site +00 ffffd001`c70c62a8 fffff800`7a0fa607 tabletaudiosample!CMiniportWaveRT::NewStream [c:\data1\threshold\audio\endpointscommon\minwavert.cpp @ 562] +01 ffffd001`c70c62b0 fffff800`7a0fb2c3 portcls!CPortPinWaveRT::Init+0x2e7 +02 ffffd001`c70c6340 fffff800`7a0fc7f9 portcls!CPortFilterWaveRT::NewIrpTarget+0x193 +03 ffffd001`c70c63c0 fffff800`7a180552 portcls!xDispatchCreate+0xd9 +04 ffffd001`c70c6450 fffff800`7a109a9a ks!KsDispatchIrp+0x272 +05 ffffd001`c70c6510 fffff800`7bd314b1 portcls!DispatchCreate+0x7a +06 ffffd001`c70c6540 fffff803`cda1bfa8 ksthunk!CKernelFilterDevice::DispatchIrp+0xf9 +07 ffffd001`c70c65a0 fffff803`cda7b306 nt!IopParseDevice+0x7c8 +08 ffffd001`c70c6770 fffff803`cda12916 nt!IopParseFile+0xb6 +09 ffffd001`c70c67d0 fffff803`cda1131c nt!ObpLookupObjectName+0x776 +0a ffffd001`c70c6970 fffff803`cd9fedb8 nt!ObOpenObjectByNameEx+0x1ec +0b ffffd001`c70c6a90 fffff803`cd9fe919 nt!IopCreateFile+0x3d8 +0c ffffd001`c70c6b40 fffff803`cd752fa3 nt!NtCreateFile+0x79 +0d ffffd001`c70c6bd0 00007fff`69805b74 nt!KiSystemServiceCopyEnd+0x13 +0e 000000ee`6d37c568 00007fff`487484e6 0x00007fff`69805b74 +0f 000000ee`6d37c570 0000029b`00000003 0x00007fff`487484e6 +10 000000ee`6d37c578 00000000`0000012e 0x0000029b`00000003 +11 000000ee`6d37c580 00000000`00000000 0x12e +``` + +Enter g into the debugger to run the code forward until the media clip is done playing. Then break in to the debugger, by pressing Ctrl - ScrLk (Ctrl-Break) Use the !thread command to confirm that you are now running a different thread. + +``` +0: kd> !thread +THREAD ffffe001ce80b840 Cid 17e4.01ec Teb: 00000071fa9b9000 Win32Thread: ffffe001d41690d0 RUNNING on processor 0 +Not impersonating +DeviceMap ffffc0001974e2c0 +Owning Process ffffe001d1760840 Image: rundll32.exe +Attached Process N/A Image: N/A +Wait Start TickCount 538040 Ticks: 0 +Context Switch Count 3181840 IdealProcessor: 0 +UserTime 00:00:08.250 +KernelTime 00:00:10.796 +Win32 Start Address 0x00007ff6d2f24270 +Stack Init ffffd001cd16afd0 Current ffffd001cd16a730 +Base ffffd001cd16b000 Limit ffffd001cd165000 Call 0 +Priority 8 BasePriority 8 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 + +Child-SP RetAddr : Args to Child : Call Site +fffff803`cf373d18 fffff800`7a202852 : fffff803`cf373e60 00000000`00000001 ffffe001`cf4ed330 00000000`0000ffff : nt!DbgBreakPointWithStatus +fffff803`cf373d20 fffff803`cd6742c6 : ffffe001`cf4ed2f0 fffff803`cf373e60 00000000`00000001 00000000`0004e4b8 : kdnic!TXSendCompleteDpc+0x142 +fffff803`cf373d60 fffff803`cd74d495 : 00000000`00000000 fffff803`cd923180 fffff803`cde1f4b0 fffff901`40669010 : nt!KiRetireDpcList+0x5f6 +fffff803`cf373fb0 fffff803`cd74d2a0 : 00000000`00000090 0000000e`0000006a 00000000`00000092 00000000`00000000 : nt!KxRetireDpcList+0x5 (TrapFrame @ fffff803`cf373e70) +ffffd001`cd16a6c0 fffff803`cd74bd75 : 00000000`00000000 fffff803`cd74a031 00000000`00000000 00000000`00000000 : nt!KiDispatchInterruptContinue +ffffd001`cd16a6f0 fffff803`cd74a031 : 00000000`00000000 00000000`00000000 ffffe001`cff4d2a0 fffff803`cd67738e : nt!KiDpcInterruptBypass+0x25 +ffffd001`cd16a700 fffff960`50cdb5a4 : fffff901`400006d0 00000000`00000001 fffff901`40000d60 ffffd001`cd16a9f0 : nt!KiInterruptDispatchNoLockNoEtw+0xb1 (TrapFrame @ ffffd001`cd16a700) +ffffd001`cd16a890 fffff960`50c66b2f : 00000000`00000000 fffff901`40669010 fffff901`42358580 fffff901`40000d60 : win32kfull!Win32FreePoolImpl+0x34 +ffffd001`cd16a8c0 fffff960`50c68cd6 : 00000000`00000000 ffffd001`cd16a9f0 fffff901`400006d0 fffff901`400c0460 : win32kfull!EXLATEOBJ::vAltUnlock+0x1f +ffffd001`cd16a8f0 fffff803`cd752fa3 : 00000000`00000000 00000000`00000000 ffffe001`ce80b840 00000000`00000000 : win32kfull!NtGdiAlphaBlend+0x1d16 +ffffd001`cd16add0 00007fff`674c1494 : 00007fff`674b1e97 0000a7c6`daee0559 00000000`00000001 0000020b`741f3c50 : nt!KiSystemServiceCopyEnd+0x13 (TrapFrame @ ffffd001`cd16ae40) +00000071`fa74c9a8 00007fff`674b1e97 : 0000a7c6`daee0559 00000000`00000001 0000020b`741f3c50 00000000`00ffffff : 0x00007fff`674c1494 +00000071`fa74c9b0 0000a7c6`daee0559 : 00000000`00000001 0000020b`741f3c50 00000000`00ffffff 00000000`00000030 : 0x00007fff`674b1e97 +00000071`fa74c9b8 00000000`00000001 : 0000020b`741f3c50 00000000`00ffffff 00000000`00000030 00000000`01010bff : 0x0000a7c6`daee0559 +00000071`fa74c9c0 0000020b`741f3c50 : 00000000`00ffffff 00000000`00000030 00000000`01010bff 00000000`00000000 : 0x1 +00000071`fa74c9c8 00000000`00ffffff : 00000000`00000030 00000000`01010bff 00000000`00000000 00000000`000000c0 : 0x0000020b`741f3c50 +00000071`fa74c9d0 00000000`00000030 : 00000000`01010bff 00000000`00000000 00000000`000000c0 00000000`00000030 : 0xffffff +00000071`fa74c9d8 00000000`01010bff : 00000000`00000000 00000000`000000c0 00000000`00000030 00000071`00000030 : 0x30 +00000071`fa74c9e0 00000000`00000000 : 00000000`000000c0 00000000`00000030 00000071`00000030 00000071`01ff8000 : 0x1010bff +``` + +The image name is rundll32.exe, which is indeed not the image name associated with playing the media clip. + +**Note**   +To set the current thread, type .thread <thread number>. + +For more information about threads and processes, see the following references on MSDN: + +[Threads and Processes](threads-and-processes.md) + +[Changing Contexts](changing-contexts.md) + +  + +## Section 11: IRQL, registers, and disassembly + + +### View the saved IRQL + +*In Section 11, you will display the IRQL, and the contents of the regsisters.* + +**<- On the host system** + +The interrupt request level (IRQL) is used to manage the priority of interrupt servicing. Each processor has an IRQL setting that threads can raise or lower. Interrupts that occur at or below the processor's IRQL setting are masked and will not interfere with the current operation. Interrupts that occur above the processor's IRQL setting take precedence over the current operation. The [**!irql**](-irql.md) extension displays the interrupt request level (IRQL) on the current processor of the target computer before the debugger break occurred. When the target computer breaks into the debugger, the IRQL changes, but the IRQL that was effective just before the debugger break is saved and is displayed by !irql. + +``` +0: kd> !irql +Debugger saved IRQL for processor 0x0 -- 2 (DISPATCH_LEVEL) +``` + +### <View the registers and disassembly + +**View the registers** + +Display the contents of the registers for the current thread on the current processor by using the [**r (Registers)**](r--registers-.md) command. + +``` +0: kd> r +rax=000000000000c301 rbx=ffffe00173eed880 rcx=0000000000000001 +rdx=000000d800000000 rsi=ffffe00173eed8e0 rdi=ffffe00173eed8f0 +rip=fffff803bb757020 rsp=ffffd001f01f8988 rbp=ffffe00173f0b620 + r8=000000000000003e r9=ffffe00167a4a000 r10=000000000000001e +r11=ffffd001f01f88f8 r12=0000000000000000 r13=ffffd001f01efdc0 +r14=0000000000000001 r15=0000000000000000 +iopl=0 nv up ei pl nz na pe nc +cs=0010 ss=0018 ds=002b es=002b fs=0053 gs=002b efl=00000202 +nt!DbgBreakPointWithStatus: +fffff803`bb757020 cc int 3 +``` + +Alternatively, you can display the contents of the registers by clicking **View** > **Registers**. + +![windbg registers window showing about 12 registers](images/sysvad-lab-audio-display-registers.png) + +Viewing the contents of the registers can be helpful when stepping through assembly language code execution and in other scenarios. For more information see [**r (Registers)**](r--registers-.md). + +For information about contents of the register, see [x86 Architecture](x86-architecture.md) and [x64 Architecture](x64-architecture.md). + +**Disassembly** + +You can disassemble the code that is under execution to view the assembly language code that is being run by clicking **View** > **Disassembly**. + +![windbg disassembly window](images/sysvad-lab-audio-disassembly-window.png) + +For more information about assembly language disassembly, see [Annotated x86 Disassembly](annotated-x86-disassembly.md) and [Annotated x64 Disassembly](annotated-x64-disassembly.md). + +## Section 12: Work with memory + + +*In Section 12, you will use debugger commands to display the contents of memory.* + +**View memory** + +You may need to examine memory to identify an issue or to inspect variables, pointers, and so on. You can display memory by typing one of the following **d\* <address>** commands. + + ++++ + + + + + + + + + + + + + + + + + + +

db

Displays data in byte values and ASCII characters.

dd

Displays data as double wide words (4 bytes).

du

Displays data as Unicode characters.

dw

Displays data as word values (2 bytes) and ASCII characters.

+ +  + +**Note**   +If you attempt to display an invalid address, its contents are shown as question marks (?). + +  + +Alternatively, you can view the memory by clicking **View** > **Memory**. Use the **Display format** pull down to change how the memory is displayed. + +![windbg view memory window](images/sysvad-lab-audio-memory-display.png) + +1. To view data associated with the volume control, set a breakpoint to fire on the PropertyHandlerAudioEngineVolumeLevel routine using the bm command. Before we set the new breakpoint, we will clear all of the previous breakpoints using bc \*. + + ``` + kd> bc * + ``` + +2. Set a breakpoint to fire on the PropertyHandlerAudioEngineVolumeLevel routine using the bm command. + + ``` + kd> bm tabletaudiosample!CMiniportWaveRT::SetDeviceChannelVolume + 1: fffff80f`02c3a4b0 @!"tabletaudiosample!CMiniportWaveRT::SetDeviceChannelVolume" + ``` + +3. List the breakpoints to confirm that the breakpoint is set properly. + + ``` + kd> bl + 1: fffff80f`02c3a4b0 @!"tabletaudiosample!CMiniportWaveRT::SetDeviceChannelVolume" + ``` + +4. Use the **g** command to restart code execution. + + On the target system adjust the volume in the system tray. This will cause the breakpoint to fire. + + ``` + Breakpoint 1 hit + tabletaudiosample!CMiniportWaveRT::SetDeviceChannelVolume: + fffff80f`02c3a4b0 44894c2420 mov dword ptr [rsp+20h],r9d + ``` + +5. Use the **View**> **Local** menu item to display local variables. Note the current value of the IVolume variable. + +6. You can display the data type and the current value for the IVolume variable in the sample code by typing the **dt** command and the name of the variable. + + ``` + kd> dt lVolume + Local var @ 0xa011ea50 Type long + 0n-6291456 + ``` + +7. The breakpoint is hit on entering SetDeviceChannelVolume. + + ``` + STDMETHODIMP_(NTSTATUS) CMiniportWaveRT::SetDeviceChannelVolume(_In_ ULONG _ulNodeId, _In_ UINT32 _uiChannel, _In_ LONG _Volume) + { + NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST; + + PAGED_CODE (); + + DPF_ENTER(("[CMiniportWaveRT::SetEndpointChannelVolume]")); + IF_TRUE_ACTION_JUMP(_ulNodeId != KSNODE_WAVE_AUDIO_ENGINE, ntStatus = STATUS_INVALID_DEVICE_REQUEST, Exit); + + // Snap the volume level to our range of steppings. + LONG lVolume = VOLUME_NORMALIZE_IN_RANGE(_Volume); + + ntStatus = SetChannelVolume(_uiChannel, lVolume); + + Exit: + return ntStatus; + } + ``` + +8. Attempt to display the value at the memory location of IVolume by using the [**dt (Display Type)**](dt--display-type-.md) command. + + ``` + kd> dt dt lVolume + Local var @ 0xffffb780b7eee664 Type long + 0n0 + ``` + + Because the variable is yet to be defined, it does not contain information. + +9. Press F10 to run forward to the last line of code in SetDeviceChannelVolume. + + ``` + return ntStatus; + ``` + +10. Display the value at the memory location of IVolume by using the [**dt (Display Type)**](dt--display-type-.md) command. + + ``` + kd> dt lVolume + Local var @ 0xffffb780b7eee664 Type long + 0n-6291456 + ``` + + Now that the variable is active, a value of 6291456 is displayed in this example. + +11. You can also display the memory location of IVolume by using the [**? (Evaluate Expression)**](---evaluate-expression-.md) command. + + ``` + kd> ? lVolume + Evaluate expression: -79711507126684 = ffffb780`b7eee664 + ``` + +12. The address shown, *ffffb780\`b7eee664* is the address of the lVolume variable. Use the dd command to display the contents of memory at that location. + + ``` + kd> dd ffffb780`b7eee664 + ffffb780`b7eee664 ffa00000 00000018 00000000 c52d7008 + ffffb780`b7eee674 ffffc98e e0495756 fffff80e c52d7008 + ffffb780`b7eee684 ffffc98e 00000000 fffff80e 00000000 + ffffb780`b7eee694 ffffc98e ffa00000 ffffb780 b7eee710 + ffffb780`b7eee6a4 ffffb780 00000000 00000000 c7477260 + ffffb780`b7eee6b4 ffffc98e b7eee7a0 ffffb780 b7eee6f0 + ffffb780`b7eee6c4 ffffb780 e04959ca fffff80e 00000000 + ffffb780`b7eee6d4 00000000 00000028 00000000 00000002 + ``` + +13. You can display the first four bytes of an address by specifying the range parameter L4. + + ``` + kd> dd ffffb780`b7eee664 l4 + ffffb780`b7eee664 ffa00000 00000018 00000000 c52d7008 + ``` + +14. To see the different types of memory output displayed, type the **du**, **da** and **db** commands. + + ``` + kd> du ffffb780`b7eee664 + ffffb780`b7eee664 "" + + kd> a ffffb780`b7eee664 + ffffb780`b7eee664 "" + + kd> db 0xffffae015ff97664 + ffffae01`5ff97664 00 80 bc ff 18 00 00 00-00 00 00 00 08 50 e0 51 .............P.Q + ffffae01`5ff97674 00 c0 ff ff 56 57 da 56-0e f8 ff ff 08 50 e0 51 ....VW.V.....P.Q + ffffae01`5ff97684 00 c0 ff ff 00 00 00 00-0e f8 ff ff 00 00 00 00 ................ + ffffae01`5ff97694 00 c0 ff ff aa 80 bc ff-01 ae ff ff 10 77 f9 5f .............w._ + ffffae01`5ff976a4 01 ae ff ff 40 00 00 00-00 e6 ff ff 10 dc 30 55 ....@.........0U + ffffae01`5ff976b4 00 c0 ff ff a0 77 f9 5f-01 ae ff ff f0 76 f9 5f .....w._.....v._ + ffffae01`5ff976c4 01 ae ff ff ca 59 da 56-0e f8 ff ff 00 00 00 00 .....Y.V........ + ffffae01`5ff976d4 00 00 00 00 28 00 00 00-00 00 00 00 02 00 00 00 ....(........... + ``` + + Use the df float option to display data as single-precision floating-point numbers (4 bytes). + + ``` + df ffffb780`b7eee664 + ffffb780`b7eee664 -1.#QNAN 3.3631163e-044 0 -2775.002 + ffffb780`b7eee674 -1.#QNAN -5.8032637e+019 -1.#QNAN -2775.002 + ffffb780`b7eee684 -1.#QNAN 0 -1.#QNAN 0 + ffffb780`b7eee694 -1.#QNAN -1.#QNAN -1.#QNAN -2.8479408e-005 + ``` + +**Write to memory** + +Similar to the commands that are used for reading memory, you can use the e\* commands to change memory contents. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription

ea

ASCII string (not NULL-terminated)

eu

Unicode string (not NULL-terminated

ew

Word values (2 bytes)

eza

NULL-terminated ASCII string

ezu

NULL-terminated Unicode string

eb

Byte values

ed

Double-word values (4 bytes)

+ +  + +The following example shows how to overwrite memory. + +1. First, locate the address of the lVolume that is used in the sample code. + + ``` + kd> ? lVolume + Evaluate expression: -79711507126684 = ffffb780`b7eee664 + ``` + +2. Overwrite that memory address with new characters using the **eb** command. + + ``` + kd> eb 0xffffb780`b7eee664 11 11 11 11 11 + ``` + +3. Display the memory location to confirm that the characters have been overwritten by typing the **db** command. + + ``` + kd> db 0xffffb780`b7eee664 + ffffb780`b7eee664 11 11 11 11 11 00 00 00-00 00 00 00 08 70 2d c5 .............p-. + ffffb780`b7eee674 8e c9 ff ff 56 57 49 e0-0e f8 ff ff 08 70 2d c5 ....VWI......p-. + ffffb780`b7eee684 8e c9 ff ff 00 00 00 00-0e f8 ff ff 00 00 00 00 ................ + ffffb780`b7eee694 8e c9 ff ff 00 00 a0 ff-80 b7 ff ff 10 e7 ee b7 ................ + ffffb780`b7eee6a4 80 b7 ff ff 00 00 00 00-00 00 00 00 60 72 47 c7 ............`rG. + ffffb780`b7eee6b4 8e c9 ff ff a0 e7 ee b7-80 b7 ff ff f0 e6 ee b7 ................ + ffffb780`b7eee6c4 80 b7 ff ff ca 59 49 e0-0e f8 ff ff 00 00 00 00 .....YI......... + ffffb780`b7eee6d4 00 00 00 00 28 00 00 00-00 00 00 00 02 00 00 00 ....(........... + ``` + +Alternatively, you can modify the contents of the memory in a watch or locals window. For the watch window, you may see variables that are out of context of the current frame. Modifying them is not relevant if they are not in context. + +## Section 13: End the WinDbg session + + +**<-On the host system** + +To end a user-mode debugging session, return the debugger to dormant mode, and set the target application to run again, enter the **qd** (Quit and Detach) command. + +Be sure and use the **g** command to let the target computer run code, so that it can be used. It also a good idea to clear any break points using **bc \***, so that the target computer won't break and try to connect to the host computer debugger. + +``` +0: kd> qd +``` + +For more information, see [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) in the debugging reference documentation. + +## Section 14: Windows debugging resources + + +Additional information is available on Windows debugging. Note that some of these books will use older versions of Windows such as Windows Vista in their examples, but the concepts discussed are applicable to most versions of Windows. + +**Books** + +- *Advanced Windows Debugging* by Mario Hewardt and Daniel Pravat + +- *Inside Windows Debugging: A Practical Guide to Debugging and Tracing Strategies in Windows®* by Tarik Soulami + +- *Windows Internals* by Mark E. Russinovich, David A. Solomon and Alex Ionescu + +**Video** + +The Defrag Tools Show WinDbg Episodes 13-29 + +**Training Vendors:** + +OSR + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20Drivers%20-%20Step%20by%20Step%20Lab%20%28Sysvad%20Kernel-Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debug-winlogon.md b/windows-driver-docs-pr/debugger/debug-winlogon.md new file mode 100644 index 0000000000..5041a39b1b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debug-winlogon.md @@ -0,0 +1,66 @@ +--- +title: Debug WinLogon +description: Debug WinLogon +ms.assetid: c30e6b83-685a-4e4e-88bf-1e05776ac87a +keywords: ["Debug WinLogon (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debug WinLogon + + +## + + +The **Debug WinLogon** flag debugs the WinLogon service. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dwl

Hexadecimal value

0x04000000

Symbolic Name

FLG_DEBUG_INITIAL_COMMAND_EX

Destination

System-wide registry entry

+ +  + +### Comments + +NTSD debugs Winlogon (by using the command **ntsd -d -g -x**), but control is redirected to the kernel debugger. + +For details on NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + +### See Also + +[Debug initial command](debug-initial-command.md), [Enable debugging of Win32 subsystem](enable-debugging-of-win32-subsystem.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debug%20WinLogon%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-command-program-examples.md b/windows-driver-docs-pr/debugger/debugger-command-program-examples.md new file mode 100644 index 0000000000..2f8927f6ac --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-command-program-examples.md @@ -0,0 +1,145 @@ +--- +title: Debugger Command Program Examples +description: Debugger Command Program Examples +ms.assetid: da756906-6243-4cb9-b4e5-5b0b4540533d +keywords: ["debugger command program, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Command Program Examples + + +## + + +The following sections describe debugger command programs. + +### Using the .foreach Token + +The following example uses the [**.foreach**](-foreach.md) token to search for WORD values of 5a4d. For each 5a4d value that is found, the debugger displays 8 DWORD values, starting at the address of where the 5a4d DWORD was found. + +``` +0:000> .foreach (place { s-[1]w 77000000 L?4000000 5a4d }) { dc place L8 } +``` + +The following example uses the [**.foreach**](-foreach.md) token to search for WORD values of 5a4d. For each 5a4d value that is found, the debugger displays 8 DWORD values, starting 4 bytes prior to the address where the 5a4d DWORD was found. + +``` +0:000> .foreach (place { s-[1]w 77000000 L?4000000 5a4d }) { dc place -0x4 L8 } +``` + +The following example displays the same values. + +``` +0:000> .foreach (place { s-[1]w 77000000 L?4000000 5a4d }) { dc ( place -0x4 ) L8 } +``` + +**Note**  If you want to operate on the variable name in the *OutCommands* portion of the command, you must add a space after the variable name. For example, in the preceeding example, there is a space between the variable *place* and the subtraction operator. + +  + +The **-\[1\]** option together with the [**s (Search Memory)**](s--search-memory-.md) command causes its output to include only the addresses it finds, not the values that are found at those addresses. + +The following command displays verbose module information for all modules that are located in the memory range from 0x77000000 through 0x7F000000. + +``` +0:000> .foreach (place { lm1m }) { .if ((${place} >= 0x77000000) & (${place} <= 0x7f000000)) { lmva place } } +``` + +The **1m** option together with the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command causes its output to include only the addresses of the modules, not the full description of the modules. + +The preceding example uses the [**${ } (Alias Interpreter)**](-------alias-interpreter-.md) token to make sure aliases are replaced even if they are next to other text. If the command did not include this token, the opening parenthesis that is next to **place** prevents alias replacement. Note that the **${}** token works on the variables that are used in **.foreach** and on true aliases. + +### Walking the Process List + +The following example walks through the kernel-mode process list and displays the executable name for each entry in the list. + +This example should be stored as a text file and executed with the [**$$>< (Run Script File)**](-----------------------a---run-script-file-.md) command. This command loads the whole file, replaces all carriage returns with semicolons, and executes the resulting block. This command enables you to write readable programs by using multiple lines and indentation, instead of having to squeeze the whole program onto a single line. + +This example illustrates the following features: + +- The **$t0**, **$t1**, and **$t2** pseudo-registers are used as variables in this program. The program also uses aliases named **Procc** and **$ImageName**. + +- This program uses the MASM expression evaluator. However, the **@@c++( )** token appears one time. This token causes the program to use the C++ expression evaluator to parse the expression within the parentheses. This usage enables the program to use the C++ structure tokens directly. + +- The **?** flag is used with the [**r (Registers)**](r--registers-.md) command. This flag assigns typed values to the pseudo-register **$t2**. + +``` +$$ Get process list LIST_ENTRY in $t0. +r $t0 = nt!PsActiveProcessHead + +$$ Iterate over all processes in list. +.for (r $t1 = poi(@$t0); + (@$t1 != 0) & (@$t1 != @$t0); + r $t1 = poi(@$t1)) +{ + r? $t2 = #CONTAINING_RECORD(@$t1, nt!_EPROCESS, ActiveProcessLinks); + as /x Procc @$t2 + + $$ Get image name into $ImageName. + as /ma $ImageName @@c++(&@$t2->ImageFileName[0]) + + .block + { + .echo ${$ImageName} at ${Procc} + } + + ad $ImageName + ad Procc +} +``` + +### Walking the LDR\_DATA\_TABLE\_ENTRY List + +The following example walks through the user-mode LDR\_DATA\_TABLE\_ENTRY list and displays the base address and full path of each list entry. + +Like the preceding example, this program should be saved in a file and executed with the [**$$>< (Run Script File)**](-----------------------a---run-script-file-.md) command. + +This example illustrates the following features: + +- This program uses the MASM expression evaluator. However, in two places, the **@@c++( )** token appears. This token causes the program to use the C++ expression evaluator to parse the expression within the parentheses. This usage enables the program to use C++ structure tokens directly. + +- The **?** flag is used with the [**r (Registers)**](r--registers-.md) command. This flag assigns typed values to the pseudo-registers **$t0** and **$t1**. In the body of the loop, **$t1** has the type **ntdll!\_LDR\_DATA\_TABLE\_ENTRY\***, so the program can make direct member references. + +- The user-named aliases **$Base** and **$Mod** are used in this program. The dollar signs reduce the possibility that these aliases have been used previously in the current debugger session. The dollar signs are not necessary. The [**${/v: }**](-------alias-interpreter-.md) token interprets the alias literally, preventing it from being replaced if it was defined before the script is run. You can also use this token together with any block to prevent alias definitions before the block from being used. + +- The [**.block**](-block.md) token is used to add an extra alias replacement step. Alias replacement occurs one time for the whole script when it is loaded and one time when each block is entered. Without the **.block** token and its braces, the **.echo** command does not receive the values of the **$Mod** and **$Base** aliases that are assigned in the previous lines. + +``` +$$ Get module list LIST_ENTRY in $t0. +r? $t0 = &@$peb->Ldr->InLoadOrderModuleList + +$$ Iterate over all modules in list. +.for (r? $t1 = *(ntdll!_LDR_DATA_TABLE_ENTRY**)@$t0; + (@$t1 != 0) & (@$t1 != @$t0); + r? $t1 = (ntdll!_LDR_DATA_TABLE_ENTRY*)@$t1->InLoadOrderLinks.Flink) +{ + $$ Get base address in $Base. + as /x ${/v:$Base} @@c++(@$t1->DllBase) + + $$ Get full name into $Mod. + as /msu ${/v:$Mod} @@c++(&@$t1->FullDllName) + + .block + { + .echo ${$Mod} at ${$Base} + } + + ad ${/v:$Base} + ad ${/v:$Mod} +} +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Command%20Program%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-command-window.md b/windows-driver-docs-pr/debugger/debugger-command-window.md new file mode 100644 index 0000000000..c41759329b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-command-window.md @@ -0,0 +1,65 @@ +--- +title: Entering Debugger Commands in WinDbg +description: Entering Debugger Commands in WinDbg using the Debugger Command window +ms.assetid: 4d839170-efaf-43d5-a81c-ac3b9c33586c +keywords: debugging information windows, command window, WinDbg +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Entering Debugger Commands in WinDbg + + +## + + +The Debugger Command window is the primary debugging information window in WinDbg. You can enter debugger commands and view the command output in this window. + +**Note**   This window displays "Command" in the title bar. However, this documentation always refers to this window as "the Debugger Command window" to avoid confusing it with the Command Prompt windows that are used to issue Microsoft MS-DOS commands. + +  + +### Opening the Debugger Command Window + +To open the Debugger Command window, choose **Command** from the **View** menu. (You can also press ALT+1 or click the **Command** button (![screen shot of the debugger command window button](images/tbcmd.png)) on the toolbar. ALT+SHIFT+1 closes the Debugger Command window.) + +The following screen shot shows an example of a Debugger Command window. + +![screen shot of an example of a debugger command window](images/window-command.png) + +### Using the Debugger Command Window + +The Debugger Command window is split into two panes. You type commands in the smaller pane (the command entry pane) at the bottom of the window and view the output in the larger pane at the top of the window. + +In the command entry pane, use the UP ARROW and DOWN ARROW keys to scroll through the command history. When a command appears, you can edit it or press ENTER to run the command. + +The Debugger Command window contains a shortcut menu with additional commands. To access this menu, right-click the title bar of the window or click the icon near the upper-right corner of the window (![screen shot of the button for accessing the debugger command window toolbar shortcut menu ](images/tbcmd.png)). The following list describes some of the menu commands: + +- **Add to command output** adds a comment to the command output, similar to the [Edit | Add to Command Output](edit---add-to-command-output.md) command. + +- **Clear command output** deletes all of the text in the window. + +- **Choose text color and recolor selection...** opens a dialog box that enables you to choose the text color in which to display the text that is selected in the Debugger Command window. + +- **Word wrap** turns the word wrap status on and off. This command affects the whole window, not only commands that you use after this state is selected. Because many commands and extensions produce formatted displays, it is not recommended that you use word wrap. + +- **Mark current location** sets a marker at the current cursor location in the command window. The name of the mark is the contents of the line to the right of the cursor. + +- **Go to mark** causes the window to scroll so that the line that contains the chosen mark is positioned at the top of the window. + +- **Always floating** causes the window to remain undocked, even if it is dragged to a docking location. + +- **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Entering%20Debugger%20Commands%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-commands.md b/windows-driver-docs-pr/debugger/debugger-commands.md new file mode 100644 index 0000000000..8667d953d9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-commands.md @@ -0,0 +1,39 @@ +--- +title: Debugger Commands +description: Debugger Commands +ms.assetid: b38ba11d-27a5-462f-a2fb-df56576ec377 +keywords: ["debugger commands, reference", "debugger commands, complete listing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Commands + + +## + + +This section includes the following topics: + +[Syntax Rules](syntax-rules.md) + +[Command Tokens](command-tokens.md) + +[Commands](commands.md) + +[Meta-Commands](meta-commands.md) + +[Control Keys](control-keys.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-engine-and-extension-apis.md b/windows-driver-docs-pr/debugger/debugger-engine-and-extension-apis.md new file mode 100644 index 0000000000..a2b4aed6d0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-engine-and-extension-apis.md @@ -0,0 +1,90 @@ +--- +title: Debugger Engine and Extension APIs +description: Debugger Engine and Extension APIs +ms.assetid: 2d651c4b-e123-4285-b69c-d7fd5e1f9a81 +--- + +# Debugger Engine and Extension APIs + + +This section includes: + +[Debugger Engine Overview](debugger-engine-overview.md) + +[Using the Debugger Engine API](using-the-debugger-engine-api.md) + +[Writing DbgEng Extensions](writing-dbgeng-extensions.md) + +[EngExtCpp Extensions](engextcpp-extensions.md) + +[Writing WdbgExts Extensions](writing-wdbgexts-extensions.md) + +[Customizing Debugger Output Using DML](#dml) + +[Using JavaScript to Extend the Capabilities of the Debugger](#javascript) + +## + + +This documentation describes how to use the debugger engine and how to write extensions that will run in WinDbg, KD, CDB, and NTSD. These debugger extensions can be used when performing user-mode or kernel-mode debugging on Microsoft Windows. + +### Debugger Engine + +The debugger engine provides an interface for examining and manipulating debugging targets in user-mode and kernel-mode on Microsoft Windows. + +The debugger engine can acquire targets, set breakpoints, monitor events, query symbols, read and write memory, and control threads and processes in a target. + +You can use the debugger engine to write both debugger extension libraries and stand-alone applications. Such applications are *debugger engine applications*. A debugger engine application that uses the full functionality of the debugger engine is a *debugger*. For example, WinDbg, CDB, NTSD, and KD are debuggers; the debugger engine provides the core of their functionality. + +The debugger engine API is specified by the prototypes in the header file dbgeng.h. + +For more information, see [Debugger Engine Overview](debugger-engine-overview.md) and [Using the Debugger Engine API](using-the-debugger-engine-api.md). + +. + +### Extensions + +You can create your own debugging commands by writing and building an extension DLL. For example, you might want to write an extension command to display a complex data structure. + +There are three different types of debugger extension DLLs: + +- *DbgEng extension DLLs*. These are based on the prototypes in the dbgeng.h header file. Each DLL of this type may export DbgEng extension commands. These extension commands use the Debugger Engine API and may also use the WdbgExts API. + + For more information, see [Writing DbgEng Extensions](writing-dbgeng-extensions.md). + +- *EngExtCpp extension DLLs*. These are based on the prototypes in the engextcpp.h and dbgeng.h header files. Each DLL of this type may export DbgEng extension commands. These extension commands use both the Debugger Engine API and the EngExtCpp extension framework, and may also use the WdbgExts API. + +- *WdbgExts extension DLLs*. These are based on the prototypes in the wdbgexts.h header file. Each DLL of this type exports one or more WdbgExts extension commands. These extension commands use the WdbgExts API exclusively. For more information see [Writing WdbgExts Extensions](writing-wdbgexts-extensions.md). + +The DbgEng API can be used to create extensions or stand-alone applications. The WdbgExts API contains a subset of the functionality of the debugger engine API and can be used only by extensions. + +All debugger extensions should be compiled and built using Visual Studio. + +Extension code samples are installed as part of the Debugging Tools for Windows package if you perform a custom installation and select the **SDK** component and all its subcomponents. They can be found in the sdk\\samples subdirectory of the Debugging Tools for Windows installation directory. + +The easiest way to write new debugger extensions is to study the sample extensions. Each sample extension includes makefile and sources files for use with the Build utility. Both types of extensions are represented in the samples. + +## Writing Custom Analysis Debugger Extensions + + +You can extend the capabilities of the [**!analyze**](-analyze.md) debugger command by writing an analysis extension plugin. By providing an analysis extension plugin, you can participate in the analysis of a bug check or an exception in a way that is specific to your own component or application. When you write an analysis extension plugin, you also write a metadata file that describes the situations for which you want your plugin to be called. When **!analyze** runs, it locates, loads, and runs the appropriate analysis extension plugins. For more information, see [Writing Custom Analysis Debugger Extensions](writing-custom-analysis-debugger-extensions.md) + +## Customizing Debugger Output Using DML + + +You can customize debugger output using DML. For more information see [Customizing Debugger Output Using DML](customizing-debugger-output-using-dml.md). + +## Using JavaScript to Extend the Capabilities of the Debugger + + +Use JavaScript to create scripts that understand debugger objects and extend and customize the capabilities of the debugger. JavaScript providers bridge a scripting language to the debugger's internal object model. The JavaScript debugger scripting provider, allows the for use of JavaScript with the debugger. For more information, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Engine%20and%20Extension%20APIs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-engine-api-overview.md b/windows-driver-docs-pr/debugger/debugger-engine-api-overview.md new file mode 100644 index 0000000000..e80abe351c --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-engine-api-overview.md @@ -0,0 +1,61 @@ +--- +title: Debugger Engine API Overview +description: Debugger Engine API Overview +ms.assetid: ea8beca6-93b7-4537-af89-78d599b8b982 +keywords: ["Debugger Engine API, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Engine API Overview + + +## + + +This section includes: + +[Interacting with the Engine](interacting-with-the-engine.md) + +[Using Input and Output](using-input-and-output.md) + +[Monitoring Events](monitoring-events.md) + +[Using Breakpoints](using-breakpoints2.md) + +[Memory Access](memory-access.md) + +[Examining the Stack Trace](examining-the-stack-trace.md) + +[Controlling Threads and Processes](controlling-threads-and-processes.md) + +[Using Symbols](using-symbols.md) + +[Using Source Files](using-source-files.md) + +[Connecting to Targets](connecting-to-targets.md) + +[Target Information](target-information.md) + +[Target State](target-state.md) + +[Calling Extensions and Extension Functions](calling-extensions-and-extension-functions.md) + +[Assembling and Disassembling Instructions](assembling-and-disassembling-instructions.md) + +**Important**  The IDebug\* interfaces such as [**IDebugEventCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff550550) interface, although COM like, are not proper COM APIs. Calling these interfaces from managed code is an unsupported scenario. Issues such as garbage collection and thread ownership, lead to system instability when the interfaces are called with managed code. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Engine%20API%20Overview%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-engine-overview.md b/windows-driver-docs-pr/debugger/debugger-engine-overview.md new file mode 100644 index 0000000000..f066679198 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-engine-overview.md @@ -0,0 +1,60 @@ +--- +title: Debugger Engine Overview +description: Debugger Engine Overview +ms.assetid: e3cd8a1d-dd07-480b-bc3b-4f6acc647167 +keywords: ["Debugger Engine", "Debugger Engine, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Engine Overview + + +The *debugger engine* (DbgEng.dll), typically referred to as the *engine*, provides an interface for examining and manipulating debugging targets in [*user mode*](https://msdn.microsoft.com/library/windows/hardware/ff556343#wdkgloss-user-mode) and [*kernel mode*](https://msdn.microsoft.com/library/windows/hardware/ff556299#wdkgloss-kernel-mode) on Microsoft Windows. + +The debugger engine can acquire targets, set [breakpoints](multiprocessor-syntax.md#breakpoints), monitor [events](events.md#events), query [symbols](symbols.md#symbols), read and write to memory, and control [threads](controlling-threads-and-processes.md#threads) and [processes](controlling-threads-and-processes.md#processes) in a target. + +You can use the debugger engine to write both debugger extension libraries and stand-alone applications. Such applications are referred to as *debugger engine applications*. A debugger engine application that uses the full functionality of the debugger engine is called a *debugger*. For example, WinDbg, CDB, NTSD, and KD are debuggers; the debugger engine provides the core of their functionality. + +**Engine Concepts:** + +[Debugging Session and Execution Model](debugging-session-and-execution-model.md) + +[Client Objects](client-objects.md) + +[Input and Output](input-and-output.md) + +**Examining and Manipulating Targets:** + +[Targets](targets.md) + +[Events](events.md) + +[Breakpoints](breakpoints3.md) + +[Symbols](symbols.md) + +[Memory](memory.md) + +[Threads and Processes](threads-and-processes.md) + +### Incomplete Documentation + +This is a preliminary document and is currently incomplete. + +For many concepts relating to the debuggers and the debugger engine that are not yet documented here, look in the [Debugging Techniques](debugging-techniques.md) section of this documentation. + +To obtain some of the currently undocumented functionality of the debugger engine API, use the [**Execute**](https://msdn.microsoft.com/library/windows/hardware/ff543208) method to execute individual debugger commands. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Engine%20Overview%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-error-and-warning-messages.md b/windows-driver-docs-pr/debugger/debugger-error-and-warning-messages.md new file mode 100644 index 0000000000..83c8e51050 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-error-and-warning-messages.md @@ -0,0 +1,29 @@ +--- +title: Debugger Error and Warning Messages +description: Debugger Error and Warning Messages +ms.assetid: 8025d1f7-aa70-4023-b744-b8ed7cce32a4 +keywords: ["error messages", "warning messages"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Error and Warning Messages + + +## + + +This reference section describes some of the error and warning messages that the debugger can display. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Error%20and%20Warning%20Messages%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-extensions.md b/windows-driver-docs-pr/debugger/debugger-extensions.md new file mode 100644 index 0000000000..827fcfc5f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-extensions.md @@ -0,0 +1,41 @@ +--- +title: Using Debugger Extensions +description: This topic describes using debugger extensions +ms.assetid: 55de0cbd-c6ba-40af-a932-2f9e57f1e8ec +keywords: extension commands, debugger extensions +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugger Extensions + + +## + + +Visual Studio, WinDbg, KD, and CDB all allow the use of debugger extension commands. These extensions give these three Microsoft debuggers a great degree of power and flexibility. + +Debugger extension commands are used much like the standard debugger commands. However, while the built-in debugger commands are part of the debugger binaries themselves, debugger extension commands are exposed by DLLs distinct from the debugger. + +This allows you to write new debugger commands which are tailored to your specific need. In addition, a number of debugger extension DLLs are shipped with the debugging tools themselves. + +This section includes: + +[Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) + +[Using Debugger Extension Commands](using-debugger-extension-commands.md) + +[Writing New Debugger Extensions](writing-new-debugger-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-markup-language-commands.md b/windows-driver-docs-pr/debugger/debugger-markup-language-commands.md new file mode 100644 index 0000000000..f926b43d98 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-markup-language-commands.md @@ -0,0 +1,113 @@ +--- +title: Using Debugger Markup Language +description: Debugger commands can provide output in plain text or in an enhanced format that uses Debugger Markup Language (DML). Output that is enhanced with DML includes links. +ms.assetid: 70DDC56F-614F-43B7-B325-91984B74AECF +keywords: ["Debugger Markup Language", "DML", "Enhanced debugger commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugger Markup Language + + +Debugger commands can provide output in plain text or in an enhanced format that uses Debugger Markup Language (DML). Output that is enhanced with DML includes links that you can click to execute related commands. + +DML is available in Windows 10 and later. + +**DML Capable Commands** + +The following commands are capable of generating DML output: + +- [**.dml\_start**](-dml-start.md) +- [**.dml\_flow**](-dml-flow.md) +- [**!dml\_proc**](-dml-proc.md) +- [**lmD**](lm--list-loaded-modules-.md) +- [**kM**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) +- [**.chain /D**](-chain--list-debugger-extensions-.md) +- [**.help /D**](-help--meta-command-help-.md) +- [**.printf /D**](-printf.md) + +The [**lmD**](lm--list-loaded-modules-.md) command is an example of a command that is capable of providing DML output. The **lmD** command displays a list of loaded modules. As the following image shows, each module name is a link that you can click to get more detailed information about the module. + +![screen shot of lmd output](images/dmlcommands01.png) + +The following image shows the result of clicking the **usbuhci** link. The output includes additional links that enable you to explore further details of the usbuhci module. + +![screen shot of module details](images/dmlcommands02.png) + +**Turning DML On and Off** + +The [**.prefer\_dml**](-prefer-dml.md) command turns DML on or off. When DML is turned on (.prefer\_dml 1), commands that are capable of generating DML output will generate DML output by default. + +### Console Enhancements + +All of the Windows debuggers now have command output areas which support DML parsing. In windbg the command window supports all DML behavior and will show colors, font styles and links. The console debuggers, ntsd, cdb and kd, only support the color attributes of DML, and the only when running in a true console with color mode enabled. Debuggers with redirected I/O, ntsd –d or remote.exe sessions will not display any colors. + +### Console Debugger Color Mode + +The console debuggers, ntsd, cdb and kd now have the ability to display colored output when running in a true console. This is not the default, it requires color mode to be explicitly enabled via tools.ini. The new col\_mode <true|false> token in tools.ini controls the color mode setting. For more information about working with the tools.ini file, see [Configuring tools.ini](configuring-tools-ini.md) + +When color mode is enabled the debugger can produce colored output. By default most colors are not set and instead default to the current console colors. + +### Windbg Command Browser Window + +In Windows 10 and later Windbg the command browser window parses and displays DML. All tags such as <link>, <exec> and appearance modifications, are fully supported. + +To start a command browser session using the menu in WinDbg, select **View**, **Command Browser**. The .browse <command> in the command window will open a new command browser window and execute the given command. For more information see [Using the Command Browser Window in WinDbg](command-browser-window.md). A new command browser window can also be opened with Ctrl+N. + +The command browser window deliberately mimics the behavior of a web browser, with a drop-down history and previous/next buttons. The history drop-down only displays the last twenty commands but full history is kept so by going back in the commands you can get the drop-down to display older history. + +You can have as many command windows open at once as you like. Command windows persist in workspaces but only save the current command; the history is not kept. + +The WinDbg **View** menu has a **Set Browser Start Command** option which allows a user to set a preferred command for new browser windows to start with, such as .dml\_start. This command is saved in workspaces. + +A **Recent Commands** sub-window is available on the **View** menu to hold commands of interest. Selecting a recent command opens a new browser with the given command. There is a menu item on the browser window’s context menu that adds the window’s current command to the list of recent commands. The list of recent commands is persisted in workspaces. + +The command browser window executes the command synchronously and so does not display output until the command has completed. Long-running commands will not show anything until they have finished. + +Links have a right-click context menu similar to the right-click context menu in a web browser. Links can be opened in a new browser window. A link’s command can be copied to the clipboard for use. + +Clicking the icon near the upper-right corner of the title bar to set the command browser windows to either auto-refresh or manual-refresh. Auto-refresh browsers will automatically re-run their command on debugger state changes. This keeps the output live but at the cost of executing the command on all changes. Auto-refresh is on by default. If the browser does not need to be live the window’s context menu can be used to disable auto-refresh. + +Because commands are executed by the engine, not by the user interface, user-interface specific commands, such as [**.cls (Clear Screen)**](-cls--clear-screen-.md), will return a syntax error in when used in command browser windows. It also means that when the user interface is a remote client, the command will be executed by the server, not by the client, and the command output will show server state. + +Command browser windows can run any debugger command, it does not have to be a command that produces DML. You can use browser windows to have an arbitrary set of commands active for use. + +## Customizing DML + + +DML defines a small set of tags that can be included in command output. One example is the <link> tag. You can experiment with the <link> tag (and other DML tags) by using the [**.dml\_start**](-dml-start.md) and [**.browse**](-browse--display-command-in-browser-.md) commands. The command **.browse .dml\_start** *filepath* executes the commands stored in a DML file. The output is displayed in the [Command Browser window](command-browser-window.md) instead of the regular command window. + +Suppose the file c:\\DmlExperiment.txt contains the following lines. + +``` +My DML Experiment +List modules that begin with usb. +``` + +The following command displays the text and link in the Command Browser window. + +``` +.browse .dml_start c:\Dml_Experiment.txt +``` + +![screen shot of dml file output](images/dmlcommands03.png) + +If you click the **List modules that begin with usb** link, you see output similar to the following image. + +![screen shot of module list](images/dmlcommands04.png) + +For a thorough discussion of DML customization and a complete list of DML tags, see [Customizing Debugger Output Using DML](customizing-debugger-output-using-dml.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugger%20Markup%20Language%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-operation-win8.md b/windows-driver-docs-pr/debugger/debugger-operation-win8.md new file mode 100644 index 0000000000..b2c4756584 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-operation-win8.md @@ -0,0 +1,31 @@ +--- +title: Debugger Operation +description: This section covers debugger operation +ms.assetid: 110551C5-DB1D-420E-BC26-F4CA7555C9CF +--- + +# Debugger Operation + + +In this section: + +- [Debugging Using Visual Studio](debugging-using-visual-studio.md) +- [Debugging Using WinDbg](debugging-using-windbg.md) +- [Debugging Using KD and NTKD](debugging-using-kd-and-ntkd.md) +- [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md) +- [Controlling the Target](controlling-the-target.md) +- [Enabling Postmortem Debugging](enabling-postmortem-debugging.md) +- [Using the Debugger Command Window](the-debugger-command-window.md) +- [Using the WinDbg Graphical Interface](windbg-graphical-interface.md) +- [Using Debugger Extensions](debugger-extensions.md) +- [Performing Remote Debugging](remote-debugging.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Operation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-reference.md b/windows-driver-docs-pr/debugger/debugger-reference.md new file mode 100644 index 0000000000..0a22c82bf1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-reference.md @@ -0,0 +1,41 @@ +--- +title: Debugger Reference +description: Debugger Reference +ms.assetid: 72337c77-422f-4dfa-af21-464298975401 +keywords: ["Debugger Reference"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger Reference + + +## + + +This reference section includes: + +[Command-Line Options](command-line-options.md) + +[Environment Variables](environment-variables.md) + +[Debugger Commands](debugger-commands.md) + +[Debugger-Related APIs](debugger-related-apis.md) + +[Debugger Error and Warning Messages](debugger-error-and-warning-messages.md) + +[WinDbg Graphical Interface Features](windbg-graphical-interface-features.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Reference%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugger-related-apis.md b/windows-driver-docs-pr/debugger/debugger-related-apis.md new file mode 100644 index 0000000000..0cdc4eb24a --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugger-related-apis.md @@ -0,0 +1,35 @@ +--- +title: Debugger-Related APIs +description: Debugger-Related APIs +ms.assetid: 46a14b0d-8fad-4ab1-9661-d19fa5ed3817 +keywords: ["debugger-related apis", "apis"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugger-Related APIs + + +## + + +This reference section includes: + +[Symbol Server API](symbol-server-api.md) + +[The dbgeng.h Header File](the-dbgeng-h-header-file.md) + +[The wdbgexts.h Header File](the-wdbgexts-h-header-file.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger-Related%20APIs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debuggers-in-the-debugging-tools-for-windows-package.md b/windows-driver-docs-pr/debugger/debuggers-in-the-debugging-tools-for-windows-package.md new file mode 100644 index 0000000000..33404b685e --- /dev/null +++ b/windows-driver-docs-pr/debugger/debuggers-in-the-debugging-tools-for-windows-package.md @@ -0,0 +1,117 @@ +--- +title: Debugging Environments +description: Starting with Windows Driver Kit (WDK) 8.0, the driver development environment and the Windows debugger are integrated into Microsoft Visual Studio. +ms.assetid: 13F9D82A-4C04-425A-A063-B349DB5C8E08 +keywords: ["WinDbg", "KD", "CDB", "NTSD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Environments + + +Starting with Windows Driver Kit (WDK) 8.0, the driver development environment and the Windows debugger are integrated into Microsoft Visual Studio. + +After you install Visual Studio and the WDK, you have six available debugging environments: + +- Visual Studio with integrated Windows debugger +- Microsoft Windows Debugger (WinDbg) +- Microsoft Kernel Debugger (KD) +- NTKD +- Microsoft Console Debugger (CDB) +- Microsoft NT Symbolic Debugger (NTSD) + +The following sections describe the debugging environments. + +### Visual Studio with integrated Windows debugger + +Starting with WDK 8.0, the driver development environment and the Windows debugger are integrated into Visual Studio. In this integrated environment, most of the tools you need for coding, building, packaging, testing, debugging, and deploying a driver are available in the Visual Studio user interface. + +Typically kernel-mode debugging requires two computers. The debugger runs on the *host computer* and the code being debugged runs on the *target computer*. With the the Windows debugger integrated into Visual Studio, you can perform a wide variety of debugging tasks, including those shown in the following list, from the host computer. + +- Configure a set of target computers for debugging. +- Configure the debugging connections to a set of target computers. +- Launch a kernel-mode debugging session between the host computer and a target computer. +- Debug a user-mode process on the host computer. +- Debug a user-mode process on a target computer. +- Connect to remote debugging sessions. +- View assembly code and source code. +- View and manipulate local variables, parameters, and other symbols. +- View and manipulate memory. +- Navigate call stacks. +- Set breakpoints. +- Execute debugger commands. + +You can also build drivers, deploy drivers, and run driver tests from within the Visual Studio user interface. If you make use of the Visual Studio integration provided by both the WDK and Debugging Tools for Windows, you can perform almost all of the driver development, packaging, deployment, testing, and debugging tasks from within Visual Studio on the host computer. Here are some of the WDK capabilities that have been integrated into Visual Studio. + +- Configure a set of target computers for driver testing. +- Create and sign a driver package. +- Deploy a driver package to a target computer. +- Install and load a driver on a target computer. +- Test a driver on a target computer. + +### WinDbg + +Microsoft Windows Debugger (WinDbg) is a powerful Windows-based debugger that is capable of both user-mode and kernel-mode debugging. WinDbg provides debugging for the Windows kernel, kernel-mode drivers, and system services, as well as user-mode applications and drivers. + +WinDbg uses the Visual Studio debug symbol formats for source-level debugging. It can access any symbol or variable from a module that has PDB symbol files, and can access any public function's name that is exposed by modules that were compiled with COFF symbol files (such as Windows .dbg files). + +WinDbg can view source code, set breakpoints, view variables (including C++ objects), stack traces, and memory. Its Debugger Command window allows the user to issue a wide variety of commands. + +For kernel-mode debugging, WinDbg typically requires two computers (the host computer and the target computer). WinDbg also supports various remote debugging options for both user-mode and kernel-mode targets. + +WinDbg is a graphical-interface counterpart to CDB/NTSD and to KD/NTKD. + +### KD + +Microsoft Kernel Debugger (KD) is a character-based console program that enables in-depth analysis of kernel-mode activity on all NT-based operating systems. You can use KD can to debug kernel-mode components and drivers, or to monitor the behavior of the operating system itself. KD also supports multiprocessor debugging. + +Typically, KD does not run on the computer being debugged. You need two computers (the *host computer* and the *target computer*) for kernel-mode debugging. + +### NTKD + +There is a variation of the KD debugger named NTKD. It is identical to KD in every way, except that it spawns a new text window when it is started, whereas KD inherits the Command Prompt window from which it was invoked. + +### CDB + +Microsoft Console Debugger (CDB) is a character-based console program that enables low-level analysis of Windows user-mode memory and constructs. CDB is extremely powerful for debugging a program that is currently running or has recently crashed (live analysis), yet simple to set up. It can be used to investigate the behavior of a working application. In the case of a failing application, CDB can be used to obtain a stack trace or to look at the guilty parameters. It works well across a network (using a remote access server), as it is character-based. + +With CDB, you can display and execute program code, set breakpoints, and examine and change values in memory. CDB can analyze binary code by disassembling it and displaying assembly instructions. It can also analyze source code directly. + +Because CDB can access memory locations through addresses or global symbols, you can refer to data and instructions by name rather than by address, making it easy to locate and debug specific sections of code. CDB supports debugging multiple threads and processes. It is extensible, and can read and write both paged and non-paged memory. + +If the target application is itself a console application, the target will share the console window with CDB. To spawn a separate console window for a target console application, use the *-2* command-line option. + +### NTSD + +There is a variation of the CDB debugger named Microsoft NT Symbolic Debugger (NTSD). It is identical to CDB in every way, except that it spawns a new text window when it is started, whereas CDB inherits the Command Prompt window from which it was invoked. + +Like CDB, NTSD is fully capable of debugging both console applications and graphical Windows programs. (The name *Console Debugger* is used to indicate the fact that CDB is classified as a console application; it does not imply that the target application must be a console application.) + +Since the **start** command can also be used to spawn a new console window, the following two constructions will give the same results: + +``` +start cdb parameters +ntsd parameters +``` + +It is possible to redirect the input and output from NTSD (or CDB) so that it can be controlled from a kernel debugger (either Visual Studio, WinDbg, or KD). If this technique is used with NTSD, no console window will appear at all. Controlling NTSD from the kernel debugger is therefore especially useful, since it results in an extremely light-weight debugger that places almost no burden on the computer containing the target application. This combination can be used to debug system processes, shutdown, and the later stages of boot up. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +## Related topics + + +[Windows Debugging](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Environments%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-deadlock.md b/windows-driver-docs-pr/debugger/debugging-a-deadlock.md new file mode 100644 index 0000000000..fad5490eb8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-deadlock.md @@ -0,0 +1,161 @@ +--- +title: Debugging a Deadlock +description: Debugging a Deadlock +ms.assetid: ee7990d9-2d4e-4e48-9214-539eebd1d8db +keywords: ["deadlocks", "thread, no ready threads"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Deadlock + + +## + + +When a thread needs exclusive access to code or some other resource, it requests a *lock*. If it can, Windows responds by giving this lock to the thread. At this point, nothing else in the system can access the locked code. This happens all the time and is a normal part of any well-written multithreaded application. Although a particular code segment can only have one lock on it at a time, multiple code segments can each have their own lock. + +A *deadlock* arises when two or more threads have requested locks on two or more resources, in an incompatible sequence. For instance, suppose that Thread One has acquired a lock on Resource A and then requests access to Resource B. Meanwhile, Thread Two has acquired a lock on Resource B and then requests access to Resource A. Neither thread can proceed until the other thread's lock is relinquished, and, therefore, neither thread can proceed. + +User-mode deadlocks arise when multiple threads of one application have blocked each others' access to the same resources. Kernel-mode deadlocks arise when multiple threads (from the same process or from distinct processes) have blocked each others' access to the same kernel resource. The procedure used to debug a deadlock depends on whether the deadlock occurs in user mode or in kernel mode. + +### Debugging a User-Mode Deadlock + +When a deadlock occurs in user mode, use the following procedure to debug it: + +1. Issue the [**!ntsdexts.locks**](-locks---ntsdexts-locks-.md) extension. In user mode, you can just type **!locks** at the debugger prompt; the **ntsdexts** prefix is assumed. + +2. This extension displays all the critical sections associated with the current process, along with the ID for the owning thread and the lock count for each critical section. If a critical section has a lock count of zero, it is not locked. Use the [**~ (Thread Status)**](---thread-status-.md) command to see information about the threads that own the other critical sections. + +3. Use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command for each of these threads to determine whether they are waiting on other critical sections. + +4. Using the output of these **kb** commands, you can find the deadlock: two threads that are each waiting on a lock held by the other thread. In rare cases, a deadlock could be caused by more than two threads holding locks in a circular pattern, but most deadlocks involve only two threads. + +Here is an illustration of this procedure. You begin with the **!ntdexts.locks** extension: + +``` +0:006> !locks +CritSec ftpsvc2!g_csServiceEntryLock+0 at 6833dd68 +LockCount 0 +RecursionCount 1 +OwningThread a7 +EntryCount 0 +ContentionCount 0 +*** Locked + +CritSec isatq!AtqActiveContextList+a8 at 68629100 +LockCount 2 +RecursionCount 1 +OwningThread a3 +EntryCount 2 +ContentionCount 2 +*** Locked + +CritSec +24e750 at 24e750 +LockCount 6 +RecursionCount 1 +OwningThread a9 +EntryCount 6 +ContentionCount 6 +*** Locked +``` + +The first critical section displayed has no locks and, therefore, can be ignored. + +The second critical section displayed has a lock count of 2 and is, therefore, a possible cause of a deadlock. The owning thread has a thread ID of 0xA3. + +You can find this thread by listing all threads with the [**~ (Thread Status)**](---thread-status-.md) command, and looking for the thread with this ID: + +``` +0:006> ~ + 0 Id: 1364.1330 Suspend: 1 Teb: 7ffdf000 Unfrozen + 1 Id: 1364.17e0 Suspend: 1 Teb: 7ffde000 Unfrozen + 2 Id: 1364.135c Suspend: 1 Teb: 7ffdd000 Unfrozen + 3 Id: 1364.1790 Suspend: 1 Teb: 7ffdc000 Unfrozen + 4 Id: 1364.a3 Suspend: 1 Teb: 7ffdb000 Unfrozen + 5 Id: 1364.1278 Suspend: 1 Teb: 7ffda000 Unfrozen +. 6 Id: 1364.a9 Suspend: 1 Teb: 7ffd9000 Unfrozen + 7 Id: 1364.111c Suspend: 1 Teb: 7ffd8000 Unfrozen + 8 Id: 1364.1588 Suspend: 1 Teb: 7ffd7000 Unfrozen +``` + +In this display, the first item is the debugger's internal thread number. The second item (the `Id` field) contains two hexadecimal numbers separated by a decimal point. The number before the decimal point is the process ID; the number after the decimal point is the thread ID. In this example, you see that thread ID 0xA3 corresponds to thread number 4. + +You then use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command to display the stack that corresponds to thread number 4: + +``` +0:006> ~4 kb + 4 id: 97.a3 Suspend: 0 Teb 7ffd9000 Unfrozen +ChildEBP RetAddr Args to Child +014cfe64 77f6cc7b 00000460 00000000 00000000 ntdll!NtWaitForSingleObject+0xb +014cfed8 77f67456 0024e750 6833adb8 0024e750 ntdll!RtlpWaitForCriticalSection+0xaa +014cfee0 6833adb8 0024e750 80000000 01f21cb8 ntdll!RtlEnterCriticalSection+0x46 +014cfef4 6833ad8f 01f21cb8 000a41f0 014cff20 ftpsvc2!DereferenceUserDataAndKill+0x24 +014cff04 6833324a 01f21cb8 00000000 00000079 ftpsvc2!ProcessUserAsyncIoCompletion+0x2a +014cff20 68627260 01f21e0c 00000000 00000079 ftpsvc2!ProcessAtqCompletion+0x32 +014cff40 686249a5 000a41f0 00000001 686290e8 isatq!I_TimeOutContext+0x87 +014cff5c 68621ea7 00000000 00000001 0000001e isatq!AtqProcessTimeoutOfRequests_33+0x4f +014cff70 68621e66 68629148 000ad1b8 686230c0 isatq!I_AtqTimeOutWorker+0x30 +014cff7c 686230c0 00000000 00000001 000c000a isatq!I_AtqTimeoutCompletion+0x38 +014cffb8 77f04f2c 00000000 00000001 000c000a isatq!SchedulerThread_297+0x2f +00000001 000003e6 00000000 00000001 000c000a kernel32!BaseThreadStart+0x51 +``` + +Notice that this thread has a call to the **WaitForCriticalSection** function, which means that not only does it have a lock, it is waiting for code that is locked by something else. We can find out which critical section we are waiting on by looking at the first parameter of the call to **WaitForCriticalSection**. This is the first address under **Args to Child**: "24e750". So this thread is waiting on the critical section at address 0x24E750. This was the third critical section listed by the **!locks** extension that you used earlier. + +In other words, thread 4, which owns the second critical section, is waiting on the third critical section. Now turn your attention to the third critical section, which is also locked. The owning thread has thread ID 0xA9. Returning to the output of the **~** command that you saw previously, note that the thread with this ID is thread number 6. Display the stack backtrace for this thread: + +``` +0:006> ~6 kb +ChildEBP RetAddr Args to Child +0155fe38 77f6cc7b 00000414 00000000 00000000 ntdll!NtWaitForSingleObject+0xb +0155feac 77f67456 68629100 6862142e 68629100 ntdll!RtlpWaitForCriticalSection+0xaa +0155feb4 6862142e 68629100 0009f238 686222e1 ntdll!RtlEnterCriticalSection+0x46 +0155fec0 686222e1 0009f25c 00000001 0009f238 isatq!ATQ_CONTEXT_LISTHEAD__RemoveFromList +0155fed0 68621412 0009f238 686213d1 0009f238 isatq!ATQ_CONTEXT__CleanupAndRelease+0x30 +0155fed8 686213d1 0009f238 00000001 01f26bcc isatq!AtqpReuseOrFreeContext+0x3f +0155fee8 683331f7 0009f238 00000001 01f26bf0 isatq!AtqFreeContext+0x36 +0155fefc 6833984b ffffffff 00000000 00000000 ftpsvc2!ASYNC_IO_CONNECTION__SetNewSocket +0155ff18 6833adcd 77f05154 01f26a58 00000000 ftpsvc2!USER_DATA__Cleanup+0x47 +0155ff28 6833ad8f 01f26a58 000a3410 0155ff54 ftpsvc2!DereferenceUserDataAndKill+0x39 +0155ff38 6833324a 01f26a58 00000000 00000040 ftpsvc2!ProcessUserAsyncIoCompletion+0x2a +0155ff54 686211eb 01f26bac 00000000 00000040 ftpsvc2!ProcessAtqCompletion+0x32 +0155ff88 68622676 000a3464 00000000 000a3414 isatq!AtqpProcessContext+0xa7 +0155ffb8 77f04f2c abcdef01 ffffffff 000ad1b0 isatq!AtqPoolThread+0x32 +0155ffec 00000000 68622644 abcdef01 00000000 kernel32!BaseThreadStart+0x51 +``` + +This thread, too, is waiting for a critical section to be freed. In this case, it is waiting on the critical section at 0x68629100. This was the second critical section in the list generated earlier by the **!locks** extension. + +This is the deadlock. Thread 4, which owns the second critical section, is waiting on the third critical section. Thread 6, which owns the third critical section, is waiting on the second critical section. + +Having confirmed the nature of this deadlock, you can use the usual debugging techniques to analyze threads 4 and 6. + +### Debugging a Kernel-Mode Deadlock + +There are several debugger extensions that are useful for debugging deadocks in kernel mode: + +- The [**!kdexts.locks**](-locks---kdext--locks-.md) extension displays information about all locks held on kernel resources and the threads holding these locks. (In kernel mode, you can just type **!locks** at the debugger prompt; the **kdexts** prefix is assumed.) + +- The [**!qlocks**](-qlocks.md) extension displays the state of all queued spin locks. + +- The [**!wdfkd.wdfspinlock**](-deadlock.md) extension displays information about a Kernel-Mode Driver Framework (KMDF) spin-lock object. + +- The [**!deadlock**](-deadlock.md) extension is used in conjunction with Driver Verifier to detect inconsistent use of locks in your code that have the potential to cause deadlocks. + +When a deadlock occurs in kernel mode, use the **!kdexts.locks** extension to list all the locks currently acquired by threads. + +You can usually pinpoint the deadlock by finding one non-executing thread that holds an exclusive lock on a resource that is required by an executing thread. Most of the locks are shared. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Deadlock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-device-installation-co-installer.md b/windows-driver-docs-pr/debugger/debugging-a-device-installation-co-installer.md new file mode 100644 index 0000000000..436bcd5e4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-device-installation-co-installer.md @@ -0,0 +1,75 @@ +--- +title: Debugging a Device Installation Co-Installer +description: Debugging a Device Installation Co-Installer +ms.assetid: a5cf3cec-bd61-49a6-b836-6759cd8c7d82 +keywords: ["device installation co-installer debugging", "installation co-installer debugging", "co-installer debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Device Installation Co-Installer + + +## + + +Some hardware device installation packages include DLL files known as *co-installers*, which assist with installing the device. + +You cannot debug a co-installer in the same fashion as other modules. This is because of the unique way in which a co-installer is loaded, and because many installation scenarios occur automatically without providing the developer an opportunity to break into the running process. + +You can resolve this issue by programmatically installing the device. Attaching a debugger to the application which installs the device allows access to the co-installer itself. The simplest way to accomplish this is to install or reinstall the device using the [DevCon](http://go.microsoft.com/fwlink/p/?linkid=152915) tool that is included in the Windows Driver Kit (WDK). You can then debug the co-installer with WinDbg. + +Use the following procedure to accomplish this task. This procedure assumes you have developed a working driver installation package for your device which uses a co-installer. It also assumes that you have the latest copy of the WDK. For information on developing drivers, driver installation packages, and driver installation co-installers, see the WDK documentation. + +**Debugging a Co-installer Using DevCon and WinDbg** + +1. Plug in the hardware device. + +2. Cancel the **New Hardware Found** wizard. + +3. Start WinDbg. + +4. Select **Open Executable** from WinDbg's **File** menu. + +5. In the **Open Executable** dialog box, do the following: + 1. In the file selection text box, select the DevCon tool (Devcon.exe). For this, browse to the WDK installation folder, then open the subdirectory tools, then open the subdirectory devcon, then open the subdirectory that matches the processor architecture of your machine, and then select Devcon.exe. Click only once on Devcon.exe and do not yet press **Open**. + 2. In the **Arguments** text box, enter the following text, where *INFFile* is the filename of your Device Installation Information (INF) file, and *HardwareID* is the hardware ID of your device: + ``` + update INFFile HardwareID + ``` + + 3. In the **Start directory** text box, enter the path to your device installation package. + 4. Click **Open**. + +6. The debugging process will begin, and WinDbg will break into the DevCon process before DevCon installs your driver. + +7. Configure the debugger to break into the co-installer process when it is loaded. You can do this by either of the following methods: + - In the Debugger Command window, use the [**sxe (Set Exceptions)**](sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md) command followed by **ld:** and then the filename of the co-installer, excluding the file extension. There should be no space after the colon For example, if the name of the co-installer is mycoinst.dll, you would use the following command: + ``` + sxe ld:mycoinst + ``` + + - Select **Event Filters** from WinDbg's **Debug** menu. In the **Event Filters** dialog box, select **Load module**. Under **Execution**, select **Enabled.** Under **Continue**, select **Not Handled.** Click the **Argument** button, and then in the text box enter the filename of the co-installer, excluding the file extension (for example, enter "mycoinst" for mycoinst.dll). Click **OK** and then click **Close**. + +8. Resume execution by pressing F5 or entering the **g (Go)** command in the Debugger Command window. + +9. When the co-installer is loaded, execution will break back into the debugger. At this point, you can set any additional breakpoints that you need. + +### Limitations of This Procedure + +In certain cases, running a device installation package under DevCon may result in slightly different behavior than that of a PnP installation, because of different security tokens and the like. If you are trying to debug a specific problem in your co-installer, it is possible that this problem will not replicate if DevCon is involved. Therefore, before using this technique, you should use DevCon to install your driver without a debugger attached to verify that this problem exists in both the PnP and the DevCon scenarios. + +If the problem vanishes whenever DevCon initiates the installation, then you will have to debug your co-installer without using DevCon. One way of doing this is to use the [TList](tlist.md) tool with the **/m** option to determine which process is loading the co-installer module, and then attaching the debugger to that process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Device%20Installation%20Co-Installer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-dual-boot-machine.md b/windows-driver-docs-pr/debugger/debugging-a-dual-boot-machine.md new file mode 100644 index 0000000000..e4d1c490a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-dual-boot-machine.md @@ -0,0 +1,33 @@ +--- +title: Debugging a Dual-Boot Machine +description: Debugging a Dual-Boot Machine +ms.assetid: 46ed532e-5ef3-4893-b2eb-da8eb52121f0 +keywords: ["dual-boot machines"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Dual-Boot Machine + + +## + + +How should you respond when the alternate operating system does not start on a dual-boot machine? + +First, check that the boot options point to the correct path for the other operating system. See [Getting Set Up for Debugging](getting-set-up-for-debugging.md) for details. + +On an x86 computer, you should also verify that boosect.ini exists. This file contains the boot record for the other operating system. To unhide this file, use the **attrib -r -s -h boosect.ini** command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Dual-Boot%20Machine%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-failed-driver-unload.md b/windows-driver-docs-pr/debugger/debugging-a-failed-driver-unload.md new file mode 100644 index 0000000000..aac0ebae36 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-failed-driver-unload.md @@ -0,0 +1,59 @@ +--- +title: Debugging a Failed Driver Unload +description: Debugging a Failed Driver Unload +ms.assetid: df4b6082-8236-4a7f-80f4-6c33dc8e887a +keywords: ["failed driver unload", "driver unload debugging", "unload failures"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Failed Driver Unload + + +## + + +A driver will not unload if there is a leaked reference to **DeviceObject** or **DriverObject**. This is a common cause of failed driver unloads. + +Apart from **IoCreateDevice**, there are several functions that take reference to **DriverObject** and **DeviceObject**. If you do not follow the guidelines for using the functions, you will end up leaking the reference. + +Here is an example of how to debug this problem. Although **DeviceObject** is used in this example, this technique works for all objects. + +**Fixing a driver that fails to unload** + +1. Put a breakpoint right after the driver calls **IoCreateDevice**. Get the **DeviceObject** address. + +2. Find the object header by using the [**!object**](-object.md) extension on this object address: + + ``` + kd> !object 81a578c0 + Object: 81a578c0 Type: (81bd0e70) Device + ObjectHeader: 81a578a8 + HandleCount: 0 PointerCount: 3 + Directory Object: e1001208 Name: Serial0 + ``` + + The first variable in the **ObjectHeader** is the *pointer count* or *reference count*. + +3. Put a write breakpoint on the pointer count, using the **ObjectHeader**'s address: + + ``` + kd> ba w4 81a578a8 "k;g" + ``` + +4. Use [**g (Go)**](g--go-.md). The debugger will produce a log. + +5. Look for the mismatched reference/dereference pair -- specifically, a missing dereference. (Note that **ObReferenceObject** is implemented as a macro inside the kernel.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Failed%20Driver%20Unload%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-processing-stall.md b/windows-driver-docs-pr/debugger/debugging-a-processing-stall.md new file mode 100644 index 0000000000..ba88f12a80 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-processing-stall.md @@ -0,0 +1,93 @@ +--- +title: Debugging a Processing Stall +description: Debugging a Processing Stall +ms.assetid: 9dff37ed-4843-4e85-8ab3-6a0a37a58c23 +keywords: ["kernel streaming debugging, video stream stall, processing stall"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Processing Stall + + +Begin by finding the relevant pin. In a hypothetical case, the relevant video capture pin has address **8160DDE0**, so we use the [**!ks.dump**](-ks-dump.md) extension command on this address to get more details: + +``` +kd> !ks.dump 8160DDE0 7 +Pin object 8160DDE0 [CKsPin = 8160DD50] + DeviceState KSSTATE_RUN + ClientState KSSTATE_RUN + CKsPin object 8160DD50 [KSPIN = 8160DDE0] + State KSSTATE_RUN + Processing Mutex 8160DFD0 is not held + And Gate & 8160DF88 + And Gate Count 1 +``` + +First, determine if the pin is in the appropriate state and whether the processing mutex is being held by another thread. In this case, the pin state is **KSSTATE\_RUN**, as it should be, and the processing mutex is not being held, so we next use the [**!ks.dumpqueue**](-ks-dumpqueue.md) extension to determine if there are frames available: + +``` +kd> !ks.dumpqueue 8160DDE0 7 +Queue 8172D5D8: + Frames Received : 763 + Frames Waiting : 5 +...... +Queue 8172D5D8: + Frame Header 81B77E60: + Irp = 816EE008 + Refcount = 1 + Frame Header 81A568D0: + Irp = 816DE008 + Refcount = 0 + Frame Header 81844ED8: + Irp = FFA0F650 + Refcount = 0 + Frame Header 8174B0B0: + Irp = FFABB460 + Refcount = 0 + Leading Edge: + Stream Pointer 8183EA58 [Public 8183EA90]: + Frame Header = 81B77E60 +...... +``` + +In the above partial display of the **!ks.dumpqueue** output, we see that there are five frames waiting, or available. Are these frames ahead of or behind the leading edge? In the **!ks.dumpqueue** display, the frames are always listed from oldest to newest. The frame header of the leading edge matches that of the first frame listed, the oldest frame. Thus all of the available frames are ahead of the leading edge. + +If this were not the case, and instead all of the frames were behind the leading edge, and they had a reference count due to clone pointers, the problems most likely originate with either the hardware or the driver's programming of hardware. Make sure that the hardware is signaling buffer completions (check interrupts and DPCs) and determine that the driver is responding appropriately to those notifications (by deleting clones upon buffer completion, for example). + +If, as in our example, all of the frames are ahead of the leading edge, the problem is almost certainly a software issue. Further information can be obtained by looking at the pin's And gate. + +### Interpreting the And Gate + +The pin's And gate controls processing. If the gate count is one, processing can occur. Obtain the current status of the And gate by using the **!ks.dump** extension: + +``` +kd> !ks.dump 8160DDE0 7 +Pin object 8160DDE0 [CKsPin = 8160DD50] + DeviceState KSSTATE_RUN + ClientState KSSTATE_RUN + CKsPin object 8160DD50 [KSPIN = 8160DDE0] + State KSSTATE_RUN + Processing Mutex 8160DFD0 is not held + And Gate & 8160DF88 + And Gate Count 1 +``` + +Because the gate count is one, the And gate is open. In this case, investigate the following potential causes for the processing stall: + +- The process dispatch incorrectly returned STATUS\_PENDING. + +- The data availability case is missing a [KsPinAttemptProcessing](http://go.microsoft.com/fwlink/p/?linkid=56545) call. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Processing%20Stall%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-service-application.md b/windows-driver-docs-pr/debugger/debugging-a-service-application.md new file mode 100644 index 0000000000..94be9847c4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-service-application.md @@ -0,0 +1,40 @@ +--- +title: Debugging a Service Application +description: Debugging a Service Application +ms.assetid: 1d1e24d5-8b6b-4ed5-84ad-b73356168b10 +keywords: ["service application debugging", "postmortem debugging, debugging service applications", "services"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Service Application + + +A *service*, also known as a *Windows service*, is a user-mode process designed to be started by Windows without human interaction. It is started automatically at system boot, or by an application that uses the service functions included in the Win32 API. A service can also be started by a human user through the Services control panel utility. Every service must conform to the interface rules of the service control manager (SCM). + +Each service is composed of three elements: a *service application*, a *service control program*, and the service control manager itself. Although a service application is sometimes (incorrectly) referred to as a "service," it is actually one of the three components that make up a service. The service application can contain almost any kind of user-mode code. The service control program controls when the service application starts and stops. The service control manager is part of Windows. + +The following sections describe how to debug a service application: + +[Choosing the Best Method](choosing-the-best-method.md) + +[Preparing to Debug the Service Application](preparing-to-debug-the-service-application.md) + +[Debugging the Service Application Automatically](debugging-the-service-application-automatically.md) + +[Debugging the Service Application Manually](debugging-the-service-application-manually.md) + +For an overview of services, service applications, and the service control manager, see *Microsoft Windows Internals: Microsoft Windows Server 2003, Windows XP, and Windows 2000* by David A. Solomon and Mark E. Russinovich (4th edition, Microsoft Press, 2005). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Service%20Application%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-stack-overflow.md b/windows-driver-docs-pr/debugger/debugging-a-stack-overflow.md new file mode 100644 index 0000000000..ec3c82b395 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-stack-overflow.md @@ -0,0 +1,234 @@ +--- +title: Debugging a Stack Overflow +description: Debugging a Stack Overflow +ms.assetid: fc67effa-88c9-4915-a5a8-8c094595c6c5 +keywords: ["stack overflow", "call stack, debugging a stack overflow"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Stack Overflow + + +## + + +A stack overflow is an error that user-mode threads can encounter. There are three possible causes for this error: + +- A thread uses the entire stack reserved for it. This is often caused by infinite recursion. + +- A thread cannot extend the stack because the page file is maxed out, and therefore no additional pages can be committed to extend the stack. + +- A thread cannot extend the stack because the system is within the brief period used to extend the page file. + +When a function running on a thread allocates local variables, the variables are put on the thread's call stack. The amount of stack space required by the function could be as large as the sum of the sizes of all the local variables. However, the compiler usually performs optimizations that reduce the stack space required by a function. For example, if two variables are in different scopes, the compiler can use the same stack memory for both of those variables. The compiler might also be able to eliminate some local variables entirely by optimizing calculations. + +The amount of optimization is influenced by compiler settings applied at build time. For example, a Debug build and a Release build have different levels of optimization. The amount of stack space required by a function in a Debug build might be larger than the amount of stack space required by that same function in a Release build. + +Here is an example of how to debug a stack overflow. In this example, NTSD is running on the same computer as the target application and is redirecting its output to KD on the host computer. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +The first step is see what event caused the debugger to break in: + +``` +0:002> .lastevent +Last event: Exception C00000FD, second chance +``` + +You can look up exception code 0xC00000FD in ntstatus.h, which can be found in the Microsoft Windows SDK and the Windows Driver Kit (WDK). This exception code is STATUS\_STACK\_OVERFLOW. + +To double-check that the stack overflowed, you can use the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command: + +``` +0:002> k +ChildEBP RetAddr +009fdd0c 71a32520 COMCTL32!_chkstk+0x25 +009fde78 77cf8290 COMCTL32!ListView_WndProc+0x4c4 +009fde98 77cfd634 USER32!_InternalCallWinProc+0x18 +009fdf00 77cd55e9 USER32!UserCallWinProcCheckWow+0x17f +009fdf3c 77cd63b2 USER32!SendMessageWorker+0x4a3 +009fdf5c 71a45b30 USER32!SendMessageW+0x44 +009fdfec 71a45bb0 COMCTL32!CCSendNotify+0xc0e +009fdffc 71a1d688 COMCTL32!CICustomDrawNotify+0x2a +009fe074 71a1db30 COMCTL32!Header_Draw+0x63 +009fe0d0 71a1f196 COMCTL32!Header_OnPaint+0x3f +009fe128 77cf8290 COMCTL32!Header_WndProc+0x4e2 +009fe148 77cfd634 USER32!_InternalCallWinProc+0x18 +009fe1b0 77cd4490 USER32!UserCallWinProcCheckWow+0x17f +009fe1d8 77cd46c8 USER32!DispatchClientMessage+0x31 +009fe200 77f7bb3f USER32!__fnDWORD+0x22 +009fe220 77cd445e ntdll!_KiUserCallbackDispatcher+0x13 +009fe27c 77cfd634 USER32!DispatchMessageWorker+0x3bc +009fe2e4 009fe4a8 USER32!UserCallWinProcCheckWow+0x17f +00000000 00000000 0x9fe4a8 +``` + +The target thread has broken into COMCTL32!\_chkstk, which indicates a stack problem. Now you should investigate the stack usage of the target process. The process has multiple threads, but the important one is the one that caused the overflow, so identify this thread first: + +``` +0:002> ~*k + + 0 id: 570.574 Suspend: 1 Teb 7ffde000 Unfrozen + ..... + + 1 id: 570.590 Suspend: 1 Teb 7ffdd000 Unfrozen + ..... + +. 2 id: 570.598 Suspend: 1 Teb 7ffdc000 Unfrozen +ChildEBP RetAddr + 009fdd0c 71a32520 COMCTL32!_chkstk+0x25 +..... + + 3 id: 570.760 Suspend: 1 Teb 7ffdb000 Unfrozen +``` + +Now you need to investigate thread 2. The period at the left of this line indicates that this is the current thread. + +The stack information is contained in the TEB (Thread Environment Block) at 0x7FFDC000. The easiest way to list it is using [**!teb**](-teb.md). However, this requires you to have the proper symbols. For maximum versatility, assume you have no symbols: + +``` +0:002> dd 7ffdc000 L4 +7ffdc000 009fdef0 00a00000 009fc000 00000000 +``` + +To interpret this, you need to look up the definition of the TEB data structure. If you had complete symbols, you could use [**dt TEB**](dt--display-type-.md) to do this. But in this case, you will need to look at the ntpsapi.h file in the Microsoft Windows SDK. For Windows XP and later versions of Windows, this file contains the following information: + +``` +typedef struct _TEB { + NT_TIB NtTib; + PVOID EnvironmentPointer; + CLIENT_ID ClientId; + PVOID ActiveRpcHandle; + PVOID ThreadLocalStoragePointer; + PPEB ProcessEnvironmentBlock; + ULONG LastErrorValue; + ..... + PVOID DeallocationStack; + ..... +} TEB; + +typedef struct _NT_TIB { + struct _EXCEPTION_REGISTRATION_RECORD *ExceptionList; + PVOID StackBase; + PVOID StackLimit; + ..... +} NT_TIB; +``` + +This indicates that the second and third DWORDs in the TEB structure point to the bottom and top of the stack, respectively. In this case, these addresses are 0x00A00000 and 0x009FC000. (The stack grows downward in memory.) You can calculate the stack size using the [**? (Evaluate Expression)**](---evaluate-expression-.md) command: + +``` +0:002> ? a00000-9fc000 +Evaluate expression: 16384 = 00004000 +``` + +This shows that the stack size is 16 K. The maximum stack size is stored in the field **DeallocationStack**. After some calculation, you can determine that this field's offset is 0xE0C. + +``` +0:002> dd 7ffdc000+e0c L1 +7ffdce0c 009c0000 + +0:002> ? a00000-9c0000 +Evaluate expression: 262144 = 00040000 +``` + +This shows that the maximum stack size is 256 K, which means more than adequate stack space is left. + +Furthermore, this process looks clean -- it is not in an infinite recursion or exceeding its stack space by using excessively large stack-based data structures. + +Now break into KD and look at the overall system memory usage with the [**!vm**](-vm.md) extension command: + +``` +0:002> .breakin +Break instruction exception - code 80000003 (first chance) +ntoskrnl!_DbgBreakPointWithStatus+4: +80148f9c cc int 3 + +kd> !vm + +*** Virtual Memory Usage *** + Physical Memory: 16268 ( 65072 Kb) + Page File: \??\C:\pagefile.sys + Current: 147456Kb Free Space: 65988Kb + Minimum: 98304Kb Maximum: 196608Kb + Available Pages: 2299 ( 9196 Kb) + ResAvail Pages: 4579 ( 18316 Kb) + Locked IO Pages: 93 ( 372 Kb) + Free System PTEs: 42754 ( 171016 Kb) + Free NP PTEs: 5402 ( 21608 Kb) + Free Special NP: 348 ( 1392 Kb) + Modified Pages: 757 ( 3028 Kb) + NonPagedPool Usage: 811 ( 3244 Kb) + NonPagedPool Max: 6252 ( 25008 Kb) + PagedPool 0 Usage: 1337 ( 5348 Kb) + PagedPool 1 Usage: 893 ( 3572 Kb) + PagedPool 2 Usage: 362 ( 1448 Kb) + PagedPool Usage: 2592 ( 10368 Kb) + PagedPool Maximum: 13312 ( 53248 Kb) + Shared Commit: 3928 ( 15712 Kb) + Special Pool: 1040 ( 4160 Kb) + Shared Process: 3641 ( 14564 Kb) + PagedPool Commit: 2592 ( 10368 Kb) + Driver Commit: 887 ( 3548 Kb) + Committed pages: 45882 ( 183528 Kb) + Commit limit: 50570 ( 202280 Kb) + + Total Private: 33309 ( 133236 Kb) + ..... +``` + +First, look at nonpaged and paged pool usage. Both are well within limits, so these are not the cause of the problem. + +Next, look at the number of committed pages: 183528 out of 202280. This is very close to the limit. Although this display does not show this number to be completely at the limit, you should keep in mind that while you are performing user-mode debugging, other processes are running on the system. Each time an NTSD command is executed, these other processes are also allocating and freeing memory. That means you do not know exactly what the memory state was like at the time the stack overflow occurred. Given how close the committed page number is to the limit, it is reasonable to conclude that the page file was used up at some point and this caused the stack overflow. + +This is not an uncommon occurrence, and the target application cannot really be faulted for this. If it happens frequently, you may want to consider raising the initial stack commitment for the failing application. + +### Analyzing a Single Function Call + +It can also be useful to find out exactly how much stack space a certain function call is allocating. + +To do this, disassemble the first few instructions and look for the instruction `sub esp`*number*. This moves the stack pointer, effectively reserving *number* bytes for local data. + +Here is an example: + +``` +0:002> k +ChildEBP RetAddr +009fdd0c 71a32520 COMCTL32!_chkstk+0x25 +009fde78 77cf8290 COMCTL32!ListView_WndProc+0x4c4 +009fde98 77cfd634 USER32!_InternalCallWinProc+0x18 +009fdf00 77cd55e9 USER32!UserCallWinProcCheckWow+0x17f +009fdf3c 77cd63b2 USER32!SendMessageWorker+0x4a3 +009fdf5c 71a45b30 USER32!SendMessageW+0x44 +009fdfec 71a45bb0 COMCTL32!CCSendNotify+0xc0e +009fdffc 71a1d688 COMCTL32!CICustomDrawNotify+0x2a +009fe074 71a1db30 COMCTL32!Header_Draw+0x63 +009fe0d0 71a1f196 COMCTL32!Header_OnPaint+0x3f +009fe128 77cf8290 COMCTL32!Header_WndProc+0x4e2 +009fe148 77cfd634 USER32!_InternalCallWinProc+0x18 + +0:002> u COMCTL32!Header_Draw + COMCTL32!Header_Draw : +71a1d625 55 push ebp +71a1d626 8bec mov ebp,esp +71a1d628 83ec58 sub esp,0x58 +71a1d62b 53 push ebx +71a1d62c 8b5d08 mov ebx,[ebp+0x8] +71a1d62f 56 push esi +71a1d630 57 push edi +71a1d631 33f6 xor esi,esi +``` + +This shows that **Header\_Draw** allocated 0x58 bytes of stack space. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Stack%20Overflow%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-stack-trace-that-has-jscript-frames.md b/windows-driver-docs-pr/debugger/debugging-a-stack-trace-that-has-jscript-frames.md new file mode 100644 index 0000000000..f359858e7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-stack-trace-that-has-jscript-frames.md @@ -0,0 +1,30 @@ +--- +title: Debugging a Stack Trace that has JScript Frames +description: The JScript Stack Dump Creation and Consumption feature works by collecting JScript frames and stitching them against debugger physical frames. +ms.assetid: A470809F-55AA-4A49-B181-EC8D22C84F31 +keywords: ["JScript", "jscript9diagdump.dll"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Stack Trace that has JScript Frames + + +The JScript Stack Dump Creation and Consumption feature works by collecting JScript frames and stitching them against debugger physical frames. Sometimes on x86 platforms, the debugger constructs the stack trace incorrectly. + +If your stack includes JScript frames that you think might be incorrect, enter the following command in the debugger. + +**.stkwalk\_force\_frame\_pointer 1** + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Stack%20Trace%20that%20has%20JScript%20Frames%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-stalled-system.md b/windows-driver-docs-pr/debugger/debugging-a-stalled-system.md new file mode 100644 index 0000000000..2e7e7eb797 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-stalled-system.md @@ -0,0 +1,51 @@ +--- +title: Debugging a Stalled System +description: Debugging a Stalled System +ms.assetid: 83679dca-2477-4d03-9a89-5a5aebc7b9d9 +keywords: ["stalled system debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Stalled System + + +## + + +There are times when the computer can stop responding without actually initiating a bug check. This "freeze" can appear in a variety of forms: + +- The mouse pointer can be moved, but does not affect any windows on the screen. + +- The entire screen is still and the mouse pointer does not move, but paging continues between the memory and the disk. + +- The screen is still and the disk is silent. + +If the mouse pointer moves or there is paging to the disk, this is usually due to a problem within the Client Server Run-Time Subsystem (CSRSS). + +If NTSD is running on CSRSS, press F12 and dump out each thread to see if there is anything out of the ordinary. (See [Debugging CSRSS](debugging-csrss.md) for more details.) + +If an examination of CSRSS reveals nothing, then the problem may be with the kernel after all. + +If there is no mouse movement or paging, then it is almost certainly a kernel problem. + +Analyzing a kernel crash of this sort is generally a difficult task. To begin, break into KD (with [**CTRL+C**](ctrl-c--break-.md)) or WinDbg (with **CTRL+BREAK**). You can now use the debugger commands to examine the situation. + +Some useful techniques in this case include: + +[Finding the Failed Process](finding-the-failed-process.md) + +[Debugging an Interrupt Storm](debugging-an-interrupt-storm.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Stalled%20System%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-time-out.md b/windows-driver-docs-pr/debugger/debugging-a-time-out.md new file mode 100644 index 0000000000..74ddd1f0e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-time-out.md @@ -0,0 +1,37 @@ +--- +title: Debugging a Time Out +description: Debugging a Time Out +ms.assetid: 795774da-10fb-4431-908d-94c3baa01132 +keywords: ["time outs"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a Time Out + + +## + + +There are two main time outs that occur on Windows systems: + +[Resource Time Outs](resource-time-outs.md) (kernel mode) + +[Critical Section Time Outs](critical-section-time-outs.md) (user mode) + +In many cases, these problems are simply a matter of a thread taking too long to release a resource or exit a section of code. + +On a retail system, the time-out value is set high enough that you would not see the break (a true deadlock would simply hang). The time-out values are set in the registry under **HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Control\\SessionManager**. The integer values specify the number of seconds in each time out. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20Time%20Out%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-user-mode-failure-with-kd.md b/windows-driver-docs-pr/debugger/debugging-a-user-mode-failure-with-kd.md new file mode 100644 index 0000000000..3c88f388b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-user-mode-failure-with-kd.md @@ -0,0 +1,39 @@ +--- +title: Debugging a User-Mode Failure with KD +description: Debugging a User-Mode Failure with KD +ms.assetid: c7ef3c04-45bf-4e7b-bcc6-35fe2ffa43d1 +keywords: ["KD, user-mode debugging with KD"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging a User-Mode Failure with KD + + +## + + +To properly debug user-mode failures, you need CDB or WinDbg. However, sometimes a user-mode exception will break into KD because no user-mode debugger is present. There are also times when it is helpful to monitor what specific user-mode processes are doing while debugging a kernel-mode problem. + +By default, the kernel debugger attempts to load the first user-mode symbol that matches the address specified (for a **k**, **u**, or **ln** command). + +Unfortunately, user-mode symbols are often not specified in the symbol path or the first symbol is not the correct one. If the symbols are not there, either copy them into the symbol path or use a [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command to point to the full symbol tree, and then use the [**.reload (Reload Module)**](-reload--reload-module-.md) command. If the wrong symbol is loaded, you can explicitly load a symbol by doing a **.reload <binary.ext>**. + +Most of the Windows DLLs are rebased so they load at different addresses, but there are exceptions. Video adapters are the most common exceptions. There are dozens of video adapters that all load at the same base address, so KD will almost always find ati.dll (the first video symbol, alphabetically). For video, there is also a .sys file loaded that can be identified by using a [**!drivers**](-drivers.md) extension. With that information, you can issue a **.reload** to get the correct video DLLs. There are also times when the debugger gets confused and reloading specific symbols will help give the correct stack. Unassemble the functions to see if the symbols look correct. + +Similar to the video DLLs, almost all executables load at the same address, so KD will report access. If you see a stack trace in access, do a [**!process**](-process.md) and then a **.reload** of the executable name given. If the executable does not have symbols in the symbol path, copy them there and do the **.reload** again. + +Sometimes KD or WinDbg has trouble loading the correct user-mode symbols even when the full symbol tree is in the symbol path. In this case, ntdll.dll and kernel32.dll are two of the most common symbols that would be required. In the case of debugging CSRSS from KD, winsrv.dll and csrsrv.dll are also common DLLs to load. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20User-Mode%20Failure%20with%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-cdb.md b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-cdb.md new file mode 100644 index 0000000000..673e8d6ecc --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-cdb.md @@ -0,0 +1,99 @@ +--- +title: Debugging a User-Mode Process Using CDB +description: You can use CDB to attach to a running process or to spawn and attach to new process. +ms.assetid: 0C56F6B5-0FBC-45C9-8AB7-218C00F90521 +--- + +# Debugging a User-Mode Process Using CDB + + +You can use CDB to attach to a running process or to spawn and attach to new process. + +## Attaching to a Running Process + + +### Command Prompt + +In a Command Prompt window, you can attach to a running process when you launch CDB. Use one of the following commands: + +- **cdb -p** *ProcessID* +- **cdb -pn** *ProcessName* + +where *ProcessID* is the Process ID of a running process or *ProcessName* is the name of a running process. + +For more information about the command-line syntax, see [**CDB Command-Line Options**](cdb-command-line-options.md). + +### CDB Command Window + +If the debugger is already debugging one or more processes, you can attach to a running process by using the [**.attach (Attach to Process)**](-attach--attach-to-process-.md) command. + +The debugger always starts multiple target processes simultaneously, unless some of their threads are frozen or suspended. + +If the [**.attach**](-attach--attach-to-process-.md) command is successful, the debugger attaches to the specified process the next time that the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command. + +## Attaching to a Running Process Noninvasively + + +If you want to debug a running process and interfere only minimally in its execution, you should debug the process [noninvasively](noninvasive-debugging--user-mode-.md). + +### Command Prompt + +To noninvasively debug a running process from the CDB command line, specify the **-pv** option, the **-p** option, and the process ID, in the following syntax. + +**cdb -pv -p** *ProcessID* + +Or, to noninvasively debug a running process by specifying the process name, use the following syntax instead. + +**cdb -pv -pn** *ProcessName* + +There are several other useful command-line options. For more information about the command-line syntax, see [**CDB Command-Line Options**](cdb-command-line-options.md). + +### CDB Command Window + +If the debugger is already active, you can noninvasively debug a running process by entering the [**.attach -v (Attach to Process)**](-attach--attach-to-process-.md) command. + +You can use the **.attach** command if the debugger is already debugging one or more processes invasively. + +If the **.attach -v** command is successful, the debugger debugs the specified process the next time that the debugger issues an execution command. Because execution is not permitted during noninvasive debugging, the debugger cannot noninvasively debug more than one process at a time. This restriction also means that using the **.attach -v** command might make an existing invasive debugging session less useful. + +## Spawning a New Process + + +CDB can start a user-mode application and then debug the application. The application is specified by name. The debugger can also automatically attach to child processes (additional processes that the original target process started). + +Processes that the debugger creates (also known as spawned processes) behave slightly differently than processes that the debugger does not create. + +Instead of using the standard heap API, processes that the debugger creates use a special debug heap. You can force a spawned process to use the standard heap instead of the debug heap by using the \_NO\_DEBUG\_HEAP [environment variable](general-environment-variables.md) or the **-hd** command-line option. + +Also, because the target application is a child process of the debugger, it inherits the debugger's permissions. This permission might enable the target application to perform certain actions that it could not perform otherwise. For example, the target application might be able to affect protected processes. + +In a Command Prompt window, you can spawn a new process when you launch CDB. Enter the following command. + +**cdb \[-o\]** *ProgramName* **\[***Arguments***\]** + +The **-o** option causes the debugger to attach to child processes. There are several other useful command-line options. For more information about the command-line syntax, see [**CDB Command-Line Options**](cdb-command-line-options.md). + +If the debugger is already debugging one or more processes, you can create a new process by entering the [**.create (Create Process)**](-create--create-process-.md) command. + +The debugger will always start multiple target processes simultaneously, unless some of their threads are frozen or suspended. + +If the [**.create**](-create--create-process-.md) command is successful, the debugger creates the specified process the next time that the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command. + +You can control the application's starting directory by using the [**.createdir (Set Created Process Directory)**](-createdir--set-created-process-directory-.md) command before [**.create**](-create--create-process-.md). You can use the **.createdir -I** command or the **-noinh** command-line option to control whether the target application inherits the debugger's handles. + +You can activate or deactivate the debugging of child processes by using the [**.childdbg (Debug Child Processes)**](-childdbg--debug-child-processes-.md) command. + +## Reattaching to a Process + + +If the debugger stops responding or freezes, you can attach a new debugger to the target process. For more information about how to attach a debugger in this situation, see [Reattaching to the Target Application](reattaching-to-the-target-application.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20User-Mode%20Process%20Using%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-visual-studio.md b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-visual-studio.md new file mode 100644 index 0000000000..2f577d3ab3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-visual-studio.md @@ -0,0 +1,64 @@ +--- +title: Debugging a User-Mode Process Using Visual Studio +description: In Microsoft Visual Studio, you can use the Windows User Mode Debugger to attach to a running process or to spawn and attach to a new process. +ms.assetid: C19D1B6F-B97B-4C1B-AD84-AC974C5F5C8C +--- + +# Debugging a User-Mode Process Using Visual Studio + + +In Microsoft Visual Studio, you can use the Windows User Mode Debugger to attach to a running process or to spawn and attach to a new process. The process can run on the same computer that is running the debugger, or it can run on a separate computer. + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=391063). + +## Attaching to a running process on the same computer + + +1. In Visual Studio, from the **Tools** menu, choose **Attach to Process**. +2. In the **Attach to Process** dialog box, set **Transport** to **Windows User Mode Debugger**, and set **Qualifier** to **Localhost**. +3. In the **Available Processes** list, select the process that you want to attach to. +4. Click **Attach**. + +### Noninvasive debugging + +If you want to debug a running process and interfere only minimally in its execution, you should debug the process [noninvasively](noninvasive-debugging--user-mode-.md). + +## Spawning a new process on the same computer + + +1. In Visual Studio, from the **Tools** menu, choose **Launch Under Debugger**. +2. In the **Launch Under Debugger** dialog box, enter the path to the executable file. You can also enter arguments and a working directory. +3. Click **Launch.** + +Processes that the debugger creates (also known as spawned processes) behave a little differently than processes that the debugger does not create. + +Instead of using the standard heap API, processes that the debugger creates use a special debug heap. You can force a spawned process to use the standard heap instead of the debug heap by using the \_NO\_DEBUG\_HEAP environment variable. + +Also, because the target application is a child process of the debugger, it inherits the debugger's permissions. This permission might enable the target application to perform certain actions that it could not perform otherwise. For example, the target application might be able to affect protected processes. + +## Attaching to a running process on a separate computer + + +Sometimes the debugger and the code being debugged run on separate computers. The computer that runs the debugger is called the *host computer*, and the computer that runs the code being debugged is called the *target computer*. You can configure a target computer from Visual Studio on the host computer. Configuring the target computer is also called *provisioning* the target computer. For more information, see [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). + +After you have provisioned a target computer, you can use Visual Studio on the host computer to attach to a process running on the target computer. + +1. On the host computer, in Visual Studio, from the **Tools** menu, choose **Attach to Process**. +2. In the **Attach to Process** dialog box, set **Transport** to **Windows User Mode Debugger**, and set **Qualifier** to the name of the target computer. +3. In the **Available Processes** list, select the process that you want to attach to. +4. Click **Attach**. + +**Note**   +If you are using separate host and target computers, do not install Visual Studio and the WDK on the target computer. Debugging is not supported if Visual Studio and the WDK are installed on the target computer. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20User-Mode%20Process%20Using%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-windbg.md b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-windbg.md new file mode 100644 index 0000000000..812e811118 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-user-mode-process-using-windbg.md @@ -0,0 +1,123 @@ +--- +title: Debugging a User-Mode Process Using WinDbg +description: You can use WinDbg to attach to a running process or to spawn and attach to a new process. +ms.assetid: 65677DE4-4C91-4E24-B9BC-0924619C7307 +--- + +# Debugging a User-Mode Process Using WinDbg + + +You can use WinDbg to attach to a running process or to spawn and attach to a new process. + +## Attaching to a Running Process + + +There are several ways you can use WinDbg to attach to a running process. Regardless of the method you choose, you will need the process ID or the process name. The process ID is a number assigned by the operating system. For more information about how to determine the process ID and the process name, see [Finding the Process ID](finding-the-process-id.md). + +### WinDbg Menu + +When WinDbg is in dormant mode, you can attach to a running process by choosing **Attach to a Process** from the **File** menu or by pressing **F6**. + +In the **Attach to Process** dialog box, select the process you want to debug, and click **OK**. + +### Command Prompt + +In a Command Prompt window, you can attach to a running process when you launch WinDbg. Use one of the following commands: + +- **windbg -p** *ProcessID* +- **windbg -pn** *ProcessName* + +where *ProcessID* is the Process ID of a running process or *ProcessName* is the name of a running process. + +For more information about the command-line syntax, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +### Debugger Command Window + +If WinDbg is already debugging one or more processes, you can attach to a running process by using the [**.attach (Attach to Process)**](-attach--attach-to-process-.md) command in the [Debugger Command window](the-debugger-command-window.md). + +The debugger always starts multiple target processes simultaneously, unless some of their threads are frozen or suspended. + +If the [**.attach**](-attach--attach-to-process-.md) command is successful, the debugger attaches to the specified process the next time the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command. + +## Attaching to a Running Process Noninvasively + + +If you want to debug a running process and interfere only minimally in its execution, you should debug the process [noninvasively](noninvasive-debugging--user-mode-.md). + +### WinDbg Menu + +When WinDbg is in dormant mode, you can noninvasively debug a running process by choosing **Attach to a Process** from the **File** menu or by pressing **F6**. + +When the **Attach to Process** dialog box appears, select the **Noninvasive** check box. Then, select the line that contains the process ID and name that you want. (You can also enter the process ID in the **Process ID** box.) Finally, click **OK**. + +### Command Prompt + +In a Command Prompt window, you can attach to a running process noninvasively when you launch WinDbg. Use one of the following commands: + +**windbg -pv -p** *ProcessID* +**windbg -pv -pn** *ProcessName* +There are several other useful command-line options. For more information about the command-line syntax, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +### Debugger Command Window + +If the debugger is already active, you can noninvasively debug a running process by using the [**.attach -v (Attach to Process)**](-attach--attach-to-process-.md) command in the [Debugger Command window](the-debugger-command-window.md). + +You can use the **.attach** command if the debugger is already debugging one or more processes invasively. You cannot use this command if WinDbg is dormant. + +If the **.attach -v** command is successful, the debugger debugs the specified process the next time that the debugger issues an execution command. Because execution is not permitted during noninvasive debugging, the debugger cannot noninvasively debug more than one process at a time. This restriction also means that using the **.attach -v** command might make an existing invasive debugging session less useful. + +## Spawning a New Process + + +WinDbg can start a user-mode application and then debug the application. The application is specified by name. The debugger can also automatically attach to child processes (additional processes that the original target process started). + +Processes that the debugger creates (also known as spawned processes) behave slightly differently than processes that the debugger does not create. + +Instead of using the standard heap API, processes that the debugger creates use a special debug heap. You can force a spawned process to use the standard heap instead of the debug heap by using the \_NO\_DEBUG\_HEAP [environment variable](general-environment-variables.md) or the **-hd** command-line option. + +Also, because the target application is a child process of the debugger, it inherits the debugger's permissions. This permission might enable the target application to perform certain actions that it could not perform otherwise. For example, the target application might be able to affect protected processes. + +### WinDbg Menu + +When WinDbg is in dormant mode, you can spawn a new process by choosing **Open Executable** from the **File** menu or by pressing CTRL+E. + +When the Open Executable dialog box appears, enter the full path of the executable file in the **File name** box, or use the **Look in** list to select the path and file name that you want. + +If you want to use any command-line parameters with the user-mode application, enter them in the **Arguments** box. If you want to change the starting directory from the default directory, enter the directory path in the **Start** directory box. If you want WinDbg to attach to child processes, select the **Debug child processes also** check box. + +After you make your selections, click **Open**. + +### Command Prompt + +In a Command Prompt window, you can spawn a new process when you launch WinDbg. Use the following command: + +**windbg \[-o\]** *ProgramName* **\[***Arguments***\]** + +The **-o** option causes the debugger to attach to child processes. There are several other useful command-line options. For more information about the command-line syntax, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +### Debugger Command Window + +If WinDbg is already debugging one or more processes, you can create a new process by using the [**.create (Create Process)**](-create--create-process-.md) command in the [Debugger Command window](the-debugger-command-window.md). + +The debugger will always start multiple target processes simultaneously, unless some of their threads are frozen or suspended. + +If the [**.create**](-create--create-process-.md) command is successful, the debugger creates the specified process the next time that the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command. + +You can control the application's starting directory by using the [**.createdir (Set Created Process Directory)**](-createdir--set-created-process-directory-.md) command before [**.create**](-create--create-process-.md). You can use the **.createdir -I** command or the **-noinh** command-line option to control whether the target application inherits the debugger's handles. + +You can activate or deactivate the debugging of child processes by using the [**.childdbg (Debug Child Processes)**](-childdbg--debug-child-processes-.md) command. + +## Reattaching to a Process + + +If the debugger stops responding or freezes, you can attach a new debugger to the target process. For more information about how to attach a debugger in this situation, see [Reattaching to the Target Application](reattaching-to-the-target-application.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20User-Mode%20Process%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-a-uwp-app-using-windbg.md b/windows-driver-docs-pr/debugger/debugging-a-uwp-app-using-windbg.md new file mode 100644 index 0000000000..024c7d4ef4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-a-uwp-app-using-windbg.md @@ -0,0 +1,514 @@ +--- +title: Debugging a UWP app using WinDbg +description: You can debug Universal Windows Platform (UWP) app using WinDbg. +ms.assetid: 1CE337AC-54C0-4EF5-A374-3ECF1D72BA60 +--- + +# Debugging a UWP app using WinDbg + + +You can debug Universal Windows Platform (UWP) app using WinDbg. This approach would typically be used for advanced scenarios, where it is not possible to complete the debugging task using the built in Visual Studio debugger. For more information about debugging in Visual Studio, see [Debugging in Visual Studio](https://msdn.microsoft.com/library/sc65sadd.aspx). + +## Attaching to a UWP app + + +Attaching to UWP process is the same as attaching to a user mode process. For example, in WinDbg you can attach to a running process by choosing **Attach to a Process from the File** menu or by pressing F6. For more information, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md). + +A UWP app will not be suspended in the same ways that it does when not being debugged. To explicitly suspend/resume a UWP app, you can use the .suspendpackage and .resumepackage commands (details below). For general information on Process Lifecycle Management (PLM) used by UWP apps, see [App lifecycle](https://msdn.microsoft.com/library/windows/apps/mt243287) and [Launching, resuming, and background tasks](https://msdn.microsoft.com/library/windows/apps/mt227652). + +## Launching and debugging a UWP app + + +The -plmPackage and -plmApp command line parameters instruct the debugger to launch an app under the debugger. + +``` +windbg.exe -plmPackage -plmApp [] +``` + +Since multiple apps can be contained within a single package, both <PLMPackage> and <ApplicationId> parameters are required. This is a summary of the parameters. + + ++++ + + + + + + + + + + + + + + + + + + +
ParameterDescription
<PLMPackageName>The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.
<ApplicationId>

The ApplicationId is located in the application manifest file and can be viewed using the .querypackage or .querypackages command as discussed in this topic.

+

For more information about the application manifest file, see [App package manifest](https://msdn.microsoft.com/library/windows/apps/br211474).

[<parameters>]

Optional parameters passed to the App. Not all apps use or require parameters.

+ +  + +**HelloWorld Sample** + +To demonstrate UWP debugging, this topic uses the HelloWorld example described in [Create a "Hello, world" app (XAML)](https://msdn.microsoft.com/windows/uwp/get-started/create-a-hello-world-app-xaml-universal). + +To create a workable test app, it is only necessary to complete up to step three of the lab. + +**Locating the Full Package Name and AppId** + +Use the .querypackages command to locate the full package name and the AppId. Type .querypackages and then user CRTL+F to search up in the output for the application name, such as HelloWorld. When the entry is located using CTRL+F, it will show the package full name, for example *e24caf14-8483-4743-b80c-ca46c28c75df\_1.0.0.0\_x86\_\_97ghe447vaan8* and the AppId of *App*. + +Example: + +``` +0:000> .querypackages +... +Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +Package Display Name: HelloWorld +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=domars +Publisher Display Name: domars +Install Folder: c:\users\domars\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX +Package State: Unknown +AppId: App +... +``` + +**Viewing the Base Package Name in the in the Manifest** + +For troubleshooting, you may want to view the base package name in Visual Studio. + +To locate the base package name in Visual Studio, click on the ApplicationManifest.xml file in project explorer. The base package name will be displayed under the packaging tab as "Package name". By default, the package name will be a GUID, for example *e24caf14-8483-4743-b80c-ca46c28c75df*. + +To use notepad to locate the base package name, open the ApplicationManifest.xml file and locate the **Identity Name** tag. + +``` + +``` + +**Locating the Application Id in the Manifest** + +To locate the Application Id in the manifest file for an installed UWP app, look for the *Application Id* entry. + +For example, for the hello world app the Application ID is *App*. + +``` + +``` + +**Example WinDbg Command Line** + +This is an example command line loading the HelloWorld app under the debugger using the full package name and AppId. + +``` +windbg.exe -plmPackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 -plmApp App +``` + +## Launching a background task under the debugger + + +A background task can be explicitly launched under the debugger from the command line using the TaskId. To do this, use the -plmPackage and -plmBgTaskId command line parameters: + +``` +windbg.exe -plmPackage -plmBgTaskId +``` + + ++++ + + + + + + + + + + + + + + +
ParameterDescription
<PLMPackageName>

The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.

<BackgroundTaskId>

The BackgroundTaskId can be located using the .querypackages command as described below.

+

For more information about the application manifest file, see [App package manifest](https://msdn.microsoft.com/library/windows/apps/br211474).

+ +  + +This is an example of loading the SDKSamples.BackgroundTask code under the debugger. + +``` +windbg.exe -plmPackage Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe -plmBgTaskId {ee4438ee-22db-4cdd-85e4-8ad8a1063523} +``` + +You can experiment with the Background task sample code to become familiar with UWP debugging. It can be downloaded at [Background task sample](https://code.msdn.microsoft.com/windowsapps/Background-Task-Sample-9209ade9). + +Use the .querypackages command to locate the BackgroundTaskId. Use CTRL-F to locate the app and then locate the *Background Task Id* field. The background task must be running to display the associated background task name and task Id. + +``` +0:000> .querypackages +... +Package Full Name: Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x86__8wekyb3d8bbwe +Package Display Name: BackgroundTask C++ sample +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US +Publisher Display Name: Microsoft Corporation +Install Folder: C:\Users\DOMARS\Documents\Visual Studio 2015\Projects\Background_task_sample\C++\Debug\BackgroundTask.Windows\AppX +Package State: Running +AppId: BackgroundTask.App +Background Task Name: SampleBackgroundTask +Background Task Id: {ee4438ee-22db-4cdd-85e4-8ad8a1063523} +... +``` + +If you know the full package name you can use .querypackage to display the *Background Task Id* field. + +You can also locate the BackgroundTaskId by using the enumerateBgTasks option of the PLMDebug. For more information about the PMLDebug utiltity, see [**PLMDebug**](plmdebug.md). + +``` +C:\Program Files\Debugging Tools for Windows (x64)>PLMDebug /enumerateBgTasks Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe +Package full name is Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe. +Background Tasks: +SampleBackgroundTask : {C05806B1-9647-4765-9A0F-97182CEA5AAD} + +SUCCEEDED +``` + +## Debugging a UWP process remotely using a Process Server (DbgSrv) + + +All of the -plm\* commands work correctly with dbgsrv. To debug using dbgsrv, use the -premote switch with the connection string for dbgsrv: + +``` +windbg.exe -premote npipe:pipe=fdsa,server=localhost -plmPackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 -plmApp App +``` + +For more information about the -premote options, see [Process Servers (User Mode)](process-servers--user-mode-.md) and [Process Server Examples](process-server-examples.md). + +## Summary of UWP app commands + + +This section provides a summary of UWP app debugger commands + +**Gathering Package Information** + +**.querypackage** + +The .querypackage displays the state of a UWP application. For example, if the app is running, it can be in the *Active* state. + +``` +.querypackage +``` + +Example: + +``` +0:000> .querypackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +Package Display Name: HelloWorld +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=domars +Publisher Display Name: domars +Install Folder: c:\users\domars\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX +Package State: Running +AppId: App +Executable: HelloWorld.exe +``` + +**.querypackages** + +The .querypackages command lists all the installed UWP applications and their current state. + +``` +.querypackages +``` + +Example: + +``` +0:000> .querypackages +... +Package Full Name: Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe +Package Display Name: Microsoft Solitaire Collection +Version: 3.9.5250.0 +Processor Architecture: x64 +Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US +Publisher Display Name: Microsoft Studios +Install Folder: C:\Program Files\WindowsApps\Microsoft.MicrosoftSolitaireCollection_3.9.5250.0_x64__8wekyb3d8bbwe +Package State: Unknown +AppId: App + +Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +Package Display Name: HelloWorld +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=domars +Publisher Display Name: domars +Install Folder: c:\users\domars\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX +Package State: Running +AppId: App +Executable: HelloWorld.exe + +Package Full Name: Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x86__8wekyb3d8bbwe +Package Display Name: BackgroundTask C++ sample +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US +Publisher Display Name: Microsoft Corporation +Install Folder: C:\Users\DOMARS\Documents\Visual Studio 2015\Projects\Background_task_sample\C++\Debug\BackgroundTask.Windows\AppX +Package State: Unknown +AppId: BackgroundTask.App + +... +``` + +**Launching an app for Debugging** + +**.createpackageapp** + +The .createpackageapp command enables debugging and launches a UWP application. + +``` +.createpackageapp [] +``` + +This table lists the parameters for .createpackageapp. + + ++++ + + + + + + + + + + + + + + + + + + +
ParameterDescription
<PLMPackageName>The name of the application package. Use the .querypackages command to lists all UWP applications. Do not provide a path to the location of the package, provide just the package name.
<ApplicationId>

The ApplicationId can be located using .querypackage or .querypackages as discussed earlier in this topic.

+

For more information about the application manifest file, see [App package manifest](https://msdn.microsoft.com/library/windows/apps/br211474).

[<parameters>]Optional parameters that are passed to the application. Not all applications require or use these optional parameters.
+ +  + +Example: + +``` +.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App +``` + +**Enabling and Disabling Use of Debug Commands** + +**.enablepackagedebug** + +The .enablepackagedebug command enables debugging for UWP application. You must use .enablepackagedebug before you call any of the suspend, resume, or terminate functions. + +Note that the .createpackageapp command also enables debugging of the app. + +``` +.enablepackagedebug +``` + +Example: + +``` +.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**.disablepackagedebug** + +The .disablepackagedebug command disables debugging for UWP application. + +``` +.disablepackagedebug +``` + +Example: + +``` +.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**Starting and Stopping apps** + +Note that suspend, resume, and terminate affect all currently running apps in the package. + +**.suspendpackage** + +The .suspendpackage command, suspends a UWP application. + +``` +.suspendpackage +``` + +Example: + +``` +0:024> .suspendpackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**.resumepackage** + +The .resumepackage command resumes a UWP application. + +``` +.resumepackage +``` + +Example: + +``` +.resumepackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**.terminatepackageapp** + +The .terminatepackageapp command terminates the all of the UWP applications in the package. + +``` +.terminatepackageapp +``` + +Example: + +``` +.terminatepackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**Background Tasks** + +**.activatepackagebgtask** + +The .activatepackagebgtask command enables debugging and launches a UWP background task. + +``` + .activatepackagebgtask +``` + +Example: + +``` +.activatepackagebgtask Microsoft.SDKSamples.BackgroundTask.CPP_1.0.0.0_x64__8wekyb3d8bbwe {C05806B1-9647-4765-9A0F-97182CEA5AAD} +``` + +## Usage Examples + + +**Attach a debugger when your app is launched** + +Suppose you have an app named HelloWorld that is in a package named e24caf14-8483-4743-b80c-ca46c28c75df\_1.0.0.0\_x86\_\_97ghe447vaan8. Verify that your package is installed by displaying the full names and running states all installed packages. In a Command Prompt window, enter the following command. You can use CTRL+F to search the command output for the app name of HelloWorld. + +``` +.querypackages +... + +Package Full Name: e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +Package Display Name: HelloWorld +Version: 1.0.0.0 +Processor Architecture: x86 +Publisher: CN=domars +Publisher Display Name: user1 +Install Folder: c:\users\user1\documents\visual studio 2015\Projects\HelloWorld\HelloWorld\bin\x86\Release\AppX +Package State: Unknown +AppId: App + +... +``` + +Use .createpackageapp to launch and attach to the app. The .createpackageapp command also enables debugging of the app. + +``` +.createpackageapp e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 App +``` + +When you have finished debugging, decrement the debug reference count for the package using the .disablepackagedebug command. + +``` +.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**Attach a debugger to an app that is already running** + +Suppose you want to attach WinDbg to MyApp, which is already running. In WinDbg, on the **File** menu, choose **Attach to a Process**. Note the process ID for MyApp. Let's say the process ID is 4816. Increment the debug reference count for the package that contains MyApp. + +``` +.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +In WinDbg, in the **Attach to Process** dialog box, select process 4816, and click OK. WinDbg will attach to MyApp. + +When you have finished debugging, decrement the debug reference count for the package using the .disablepackagedebug command. + +``` +.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +**Manually suspend and resume your app** + +Follow these steps to manually suspend and resume your app. First, increment the debug reference count for the package that contains your app. + +``` +.enablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +Suspend the package. Your app's suspend handler is called, which can be helpful for debugging. + +``` +.suspendpackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +When you have finished debugging, resume the package. + +``` +.resumepackage e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +Finally, decrement the debug reference count for the package. + +``` +.disablepackagedebug e24caf14-8483-4743-b80c-ca46c28c75df_1.0.0.0_x86__97ghe447vaan8 +``` + +## Related topics + + +[Debugging Using WinDbg](debugging-using-windbg.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20a%20UWP%20app%20using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-an-application-failure.md b/windows-driver-docs-pr/debugger/debugging-an-application-failure.md new file mode 100644 index 0000000000..e7ba07c434 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-an-application-failure.md @@ -0,0 +1,39 @@ +--- +title: Debugging an Application Failure +description: Debugging an Application Failure +ms.assetid: c4118acb-2566-441a-8481-dee4bfdb03ba +keywords: ["application failures"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging an Application Failure + + +## + + +There are a variety of errors possible in user-mode applications. + +The most common kinds of failures include access violations, alignment faults, exceptions, critical section time-outs (deadlocks), and in-page I/O errors. + +Access violations and data type misalignments are among the most common. They usually occur when an invalid pointer is dereferenced. The blame could lie with the function that caused the fault, or with an earlier function that passed an invalid parameter to the faulting function. + +User-mode exceptions have many possible causes. If an unknown exception occurs, locate it in ntstatus.h or winerror.h if possible. + +Critical section timeouts (or possible deadlocks) occur when one thread is waiting for a critical section for a long time. These are difficult to debug and require an in-depth analysis of the stack trace. + +In-page I/O errors are almost always hardware failures. You can double-check the status code in ntstatus.h to verify. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20an%20Application%20Failure%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-an-interrupt-storm.md b/windows-driver-docs-pr/debugger/debugging-an-interrupt-storm.md new file mode 100644 index 0000000000..127fb25e62 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-an-interrupt-storm.md @@ -0,0 +1,225 @@ +--- +title: Debugging an Interrupt Storm +description: Debugging an Interrupt Storm +ms.assetid: b863cb9c-dce0-4572-b0ed-6f7d3a6ba472 +keywords: ["pending IRPs", "I/O Request Packet (IRP), pending"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging an Interrupt Storm + + +## + + +One of the most common examples of a stalled system is an interrupt storm. An *interrupt storm* is a level-triggered interrupt signal that remains in the asserted state. + +The following events can cause an interrupt storm: + +- A hardware device does not release its interrupt signal after being directed to do so by the device driver. + +- A device driver does not instruct its hardware to release the interrupt signal, because it does not detect that the interrupt was initiated from its hardware. + +- A device driver claims the interrupt even though the interrupt was not initiated from its hardware. This situation can only occur when multiple devices are sharing the same IRQ. + +- The edge level control register (ELCR) is not set correctly. + +- Edge and level interrupt-triggered devices share an IRQ (for example, a COM port and a PCI SCSI controller). + +This example demonstrates one method for detecting and debugging an interrupt storm. + +When the machine hangs, use a kernel debugger to break in. Use the **!irpfind** extension command to look for pending IRPs. Then, use the **!irp** extension to obtain details about any pending IRPs. For example: + +``` +kd> !irp 81183468 +Irp is active with 2 stacks 2 is current (= 0x811834fc) + No Mdl Thread 00000000: Irp stack trace. + cmd flg cl Device File Completion-Context + [ 0, 0] 0 0 8145f470 00000000 00000000-00000000 + \Driver\E100B + Args: 00000000 00000000 00000000 00000000 +>[ 16, 2] 0 e1 8145f470 00000000 8047f744-814187a8 Success Error Cancel pending + \Driver\E100B ntoskrnl!PopCompleteSystemPowerIrp + Args: 00000000 00000000 00000002 00000002 +``` + +This example shows that \\driver\\e100b has not returned the IRP for **ntoskrnl!PopCompleteSystemPowerIrp**. It appears to be stuck and might be experiencing an interrupt storm. + +To investigate, use the **kb** command to request a stack trace. For example: + +``` +kd> kb +ChildEBP RetAddr Args to Child +f714ee68 8046355a 00000001 80068c10 00000030 ntoskrnl!RtlpBreakWithStatusInstruction +f714ee68 80067a4f 00000001 80068c10 00000030 ntoskrnl!KeUpdateSystemTime+0x13e +f714eeec 8046380b 01001010 0000003b f714ef00 halacpi!HalBeginSystemInterrupt+0x83 +f714eeec 80463c50 01001010 0000003b f714ef00 ntoskrnl!KiChainedDispatch+0x1b +f714ef78 80067cc2 00000000 00000240 8000017c ntoskrnl!KiDispatchInterrupt +f714ef78 80501cb5 00000000 00000240 8000017c halacpi!HalpDispatchInterrupt2ndEnt +``` + +Notice that the section in bold is an interrupt dispatch. If you use the **g** command and break in again, you will very likely see a different stack trace, but you will still see an interrupt dispatch. To determine which interrupt is responsible for the system stall, look at the second parameter passed into **HalBeginSystemInterrupt** (in this case, 0x3B). The standard rule is that the interrupt vector displayed (0x3B) is the IRQ line plus 0x30, so the interrupt is number 0xB. Running another stack trace may provide more information about which device issued the interrupt service request (ISR). In this case, a second stack trace has the following result: + +``` +kd> kb +ChildEBP RetAddr Args to Child +f714ee24 8046355a 00000001 00000010 00000030 ntoskrnl!RtlpBreakWithStatusInstruction +f714ee24 bfe854b9 00000001 00000010 00000030 ntoskrnl!KeUpdateSystemTime+0x13e +f714eed8 f7051796 00000000 80463850 8143ec88 atimpab!AtiInterrupt+0x109 +f714eee0 80463850 8143ec88 81444038 8046380b VIDEOPRT!pVideoPortInterrupt+0x16 +f714eef8 80463818 00000202 0000003b 80450bb8 ntoskrnl!KiChainedDispatch2ndLvl+0x28 +f714eef8 80463c50 00000202 0000003b 80450bb8 ntoskrnl!KiChainedDispatch+0x28 +f714ef78 80067cc2 00000000 00000240 8000017c ntoskrnl!KiDispatchInterrupt +f714ef78 80501cb5 00000000 00000240 8000017c halacpi!HalpDispatchInterrupt2ndEntry+0x1b +f714f084 8045f744 f714f16c 00020019 f714f148 ntoskrnl!NtCreateKey+0x113 +f714f084 8042e487 f714f16c 00020019 f714f148 ntoskrnl!KiSystemService+0xc4 +f714f118 804ab556 f714f16c 00020019 f714f148 ntoskrnl!ZwCreateKey+0xb +f714f184 8041f75b f714f1e8 8000017c f714f1d0 ntoskrnl!IopCreateRegistryKeyEx+0x4e +f714f204 804965cd 8145f630 00000000 00000001 ntoskrnl!IopProcessSetInterfaceState+0x93 +f714f220 bfee1eb9 8145f630 00000000 8145f5a0 ntoskrnl!IoSetDeviceInterfaceState+0x2b +f714f254 bfedb416 00000004 00000800 0045f570 NDIS!ndisMCommonHaltMiniport+0x1f +f714f268 bfed4ddb bfed0660 811a2708 811a2708 NDIS!ndisPmHaltMiniport+0x9a +f714f288 bfed5146 811a2708 00000004 8145f570 NDIS!ndisSetPower+0x1d1 +f714f2a8 8041c60f 81453a30 811a2708 80475b18 NDIS!ndisPowerDispatch+0x84 +f714f2bc 8044cc52 80475b18 811a2708 811a279c ntoskrnl!IopfCallDriver+0x35 +f714f2d4 8044cb89 811a279c 811a2708 811a27c0 ntoskrnl!PopPresentIrp+0x62 +``` + +The system is currently running the ISR for the video card. The system will run the ISR for each of the devices sharing IRQ 0xB. If no process claims the interrupt, the operating system will wait infinitely, requesting the driver ISRs to handle the interrupt. It is also possible that a process might handle the interrupt and stop it, but if the hardware is broken the interrupt may simply be re-asserted. + +Use the **!arbiter 4** extension to determine which devices are on IRQ 0xB. If there is only one device on IRQ 0xB, you have found the cause of the problem.. If there is more than one device sharing the interrupt (99% of the cases), you will need to isolate the device either by manually programming LNK nodes (which is destructive to the system state), or by removing or disabling hardware. + +``` +kd> !arbiter 4 +DEVNODE 8149a008 (HTREE\ROOT\0) + Interrupt Arbiter "RootIRQ" at 80472a20 + Allocated ranges: + 0000000000000000 - 0000000000000000 B 8149acd0 + 0000000000000001 - 0000000000000001 B 8149acd0 + 0000000000000002 - 0000000000000002 B 8149acd0 + 0000000000000003 - 0000000000000003 B 8149acd0 + 0000000000000004 - 0000000000000004 B 8149acd0 + 0000000000000005 - 0000000000000005 B 8149acd0 + 0000000000000006 - 0000000000000006 B 8149acd0 + 0000000000000007 - 0000000000000007 B 8149acd0 + 0000000000000008 - 0000000000000008 B 8149acd0 + 0000000000000009 - 0000000000000009 B 8149acd0 + 000000000000000a - 000000000000000a B 8149acd0 + 000000000000000b - 000000000000000b B 8149acd0 + 000000000000000c - 000000000000000c B 8149acd0 + 000000000000000d - 000000000000000d B 8149acd0 + 000000000000000e - 000000000000000e B 8149acd0 + 000000000000000f - 000000000000000f B 8149acd0 + 0000000000000010 - 0000000000000010 B 8149acd0 + 0000000000000011 - 0000000000000011 B 8149acd0 + 0000000000000012 - 0000000000000012 B 8149acd0 + 0000000000000013 - 0000000000000013 B 8149acd0 + 0000000000000014 - 0000000000000014 B 8149acd0 + 0000000000000015 - 0000000000000015 B 8149acd0 + 0000000000000016 - 0000000000000016 B 8149acd0 + 0000000000000017 - 0000000000000017 B 8149acd0 + 0000000000000018 - 0000000000000018 B 8149acd0 + 0000000000000019 - 0000000000000019 B 8149acd0 + 000000000000001a - 000000000000001a B 8149acd0 + 000000000000001b - 000000000000001b B 8149acd0 + 000000000000001c - 000000000000001c B 8149acd0 + 000000000000001d - 000000000000001d B 8149acd0 + 000000000000001e - 000000000000001e B 8149acd0 + 000000000000001f - 000000000000001f B 8149acd0 + 0000000000000020 - 0000000000000020 B 8149acd0 + 0000000000000021 - 0000000000000021 B 8149acd0 + 0000000000000022 - 0000000000000022 B 8149acd0 + 0000000000000023 - 0000000000000023 B 8149acd0 + 0000000000000024 - 0000000000000024 B 8149acd0 + 0000000000000025 - 0000000000000025 B 8149acd0 + 0000000000000026 - 0000000000000026 B 8149acd0 + 0000000000000027 - 0000000000000027 B 8149acd0 + 0000000000000028 - 0000000000000028 B 8149acd0 + 0000000000000029 - 0000000000000029 B 8149acd0 + 000000000000002a - 000000000000002a B 8149acd0 + 000000000000002b - 000000000000002b B 8149acd0 + 000000000000002c - 000000000000002c B 8149acd0 + 000000000000002d - 000000000000002d B 8149acd0 + 000000000000002e - 000000000000002e B 8149acd0 + 000000000000002f - 000000000000002f B 8149acd0 + 0000000000000032 - 0000000000000032 B 8149acd0 + 0000000000000039 - 0000000000000039 S 814776d0 (ACPI) + Possible allocation: + < none > + + DEVNODE 81476f28 (ACPI_HAL\PNP0C08\0) + Interrupt Arbiter "ACPI_IRQ" at bfff10e0 + Allocated ranges: + 0000000000000000 - 0000000000000000 B 81495bb0 + 0000000000000001 - 0000000000000001 814952b0 (i8042prt) + 0000000000000003 - 0000000000000003 S 81495610 (Serial) + 0000000000000004 - 0000000000000004 B 8149acd0 + 0000000000000006 - 0000000000000006 81495730 (fdc) + 0000000000000008 - 0000000000000008 81495a90 + 0000000000000009 - 0000000000000009 S 814776d0 (ACPI) + 000000000000000b - 000000000000000b S + 000000000000000b - 000000000000000b S 81453c30 (ds1) + 000000000000000b - 000000000000000b S 81453a30 (E100B) + 000000000000000b - 000000000000000b S 81493c30 (uhcd) + 000000000000000b - 000000000000000b S 8145c390 (atirage3) + 000000000000000c - 000000000000000c 814953d0 (i8042prt) + 000000000000000d - 000000000000000d B 81495850 + 000000000000000e - 000000000000000e 8145bb50 (atapi) + 000000000000000f - 000000000000000f 8145b970 (atapi) + Possible allocation: + < none > +``` + +In this case, the audio, Universal Serial Bus (USB), network interface card (NIC), and video are all using the same IRQ. + +To find out which ISR claims ownership of the interrupt, examine the return value from the ISR. Simply disassemble the ISR using the **U** command with address given in the **!arbiter** display, and set a breakpoint on the last instruction of the ISR (which will be a 'ret' instruction). Note that using the command **g <address>** is the equivalent of setting a breakpoint on that address: + +``` +kd> g bfe33e7b +ds1wdm!AdapterIsr+ad: +bfe33e7b c20800 ret 0x8 +``` + +Use the **r** command to examine the registers. In particular, look at the EAX register. If the portion of the register contents in bold (in the following code example) is anything other then zero, this ISR claimed the interrupt. Otherwise, the interrupt was not claimed, and the operating system will call the next ISR. This example shows that the video card is not claiming the interrupt: + +``` +kd> r +eax=00000000 ebx=813f4ff0 ecx=00000010 edx=ffdff848 esi=8145d168 edi=813f4fc8 +eip=bfe33e7b esp=f714eec4 ebp=f714eee0 iopl=0 nv up ei pl zr na po nc +cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000 efl=00000246 +ds1wdm!AdapterIsr+ad: +bfe33e7b c20800 ret 0x8 +``` + +In fact, in this case, the interrupt is not claimed by any of the devices on IRQ 0xb. When you encounter this problem, you should also check to see if each piece of hardware associated with the interrupt is actually enabled. For PCI, this is easy -- look at the CMD register displayed by the **!pci** extension output: + +``` +kd> !pci 0 0 +PCI Bus 0 +00:0 8086:7190.03 Cmd[0006:.mb...] Sts[2210:c....] Device Host bridge +01:0 8086:7191.03 Cmd[0107:imb..s] Sts[0220:.6...] PciBridge 0->1-1 PCI-PCI bridge +03:0 1073:000c.03 Cmd[0000:......] Sts[0210:c....] Device SubID:1073:000c Audio device +04:0 8086:1229.05 Cmd[0007:imb...] Sts[0290:c....] Device SubID:8086:0008 Ethernet +07:0 8086:7110.02 Cmd[000f:imb...] Sts[0280:.....] Device ISA bridge +07:1 8086:7111.01 Cmd[0005:i.b...] Sts[0280:.....] Device IDE controller +07:2 8086:7112.01 Cmd[0005:i.b...] Sts[0280:.....] Device USB host controller +07:3 8086:7113.02 Cmd[0003:im....] Sts[0280:.....] Device Class:6:80:0 +``` + +Note that the audio chip's CMD register is zero. This means the audio chip is effectively disabled at this time. This also means that the audio chip will not be capable of responding to accesses by the driver. + +In this case, the audio chip needs to be manually re-enabled. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20an%20Interrupt%20Storm%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-bios-code.md b/windows-driver-docs-pr/debugger/debugging-bios-code.md new file mode 100644 index 0000000000..f3b3da0a7d --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-bios-code.md @@ -0,0 +1,33 @@ +--- +title: Debugging BIOS Code +description: Debugging BIOS Code +ms.assetid: 98f0381b-4f9d-4cf2-9860-8da20f6fbd38 +keywords: ["BIOS debugging", "BIOS debugging, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging BIOS Code + + +## + + +BIOS code is not built from standard assembly code, so it requires different debugging techniques. + +On an x86-based processor, the BIOS uses 16-bit code. To disassemble this code, use the [**ux (Unassemble x86 BIOS)**](ux--unassemble-x86-bios-.md) command. To display information about the Intel Multiprocessor Specification (MPS), use the [**!mps**](-mps.md) extension. + +If you are debugging ACPI BIOS code, the preceding commands do not work, because ACPI BIOS is written in ACPI Machine Language (AML). To disassemble this code, you should use [**!amli u**](-amli-u.md). For more information about this kind of debugging, see [ACPI Debugging](acpi-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20BIOS%20Code%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-csrss.md b/windows-driver-docs-pr/debugger/debugging-csrss.md new file mode 100644 index 0000000000..761523c424 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-csrss.md @@ -0,0 +1,73 @@ +--- +title: Debugging CSRSS +description: Debugging CSRSS +ms.assetid: 9c3a8498-d9e4-4070-aee8-c038fa1666a4 +keywords: ["CSRSS debugging", "NTSD, debugging CSRSS", "controlling the user-mode debugger from the kernel debugger, debugging CSRSS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging CSRSS + + +## + + +The Client Server Run-Time Subsystem (CSRSS) is the user-mode process that controls the underlying layer for the Windows environment. There are a number of problems that make it necessary to debug CSRSS itself. + +Debugging CSRSS is also useful when the Windows subsystem terminates unexpectedly with a [**Bug Check 0xC000021A**](bug-check-0xc000021a--status-system-process-terminated.md) (STATUS\_SYSTEM\_PROCESS\_TERMINATED). In this case, debugging CSRSS will catch the failure before it gets to an "unexpected" point. + +### Controlling NTSD from the Kernel Debugger + +The easiest way to debug CSRSS is to use NTSD and [control it from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +### Enabling CSRSS Debugging + +CSRSS debugging must be enabled before you can proceed. If the target computer is running a [*checked build*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-checked-build) of Windows, CSRSS debugging is always enabled. If the target computer is running a [*free build*](https://msdn.microsoft.com/library/windows/hardware/ff556280#wdkgloss-free-build) of Windows, you will have to enable CSRSS debugging through the Global Flags Utility (GFlags). + +To do this, start the GFlags utility, select the **System Registry** radio button, and select **Enable debugging of Win32 subsystem**. + +Alternatively, you can use the following GFlags command-line: + +``` +gflags /r +20000 +``` + +Or, if you prefer, you can edit the registry key manually instead of using GFlags. Open the following registry key: + +``` +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager +``` + +Edit the **GlobalFlag** value entry (of type REG\_DWORD) and set the bit 0x00020000. + +After using GFlags or manually editing the registry, you must reboot for the changes to take effect. + +### Starting NTSD + +Because you will be controlling the user-mode debugger from the kernel debugger, you will need to set up a kernel debugging connection. See [Getting Set Up for Debugging](getting-set-up-for-debugging.md) for details. + +After the registry has been properly configured, it is a simple matter of starting NTSD as follows: + +**ntsd --** + +See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for an explanation of how to proceed. + +You will have to set your symbol path to a location on your host computer or to some other location on your network. When CSRSS is being debugged, network authentication on the target computer will not work properly. + +Note that you may see an "in page io error" message. This is another manifestation of a hardware failure. + +In Windows XP and later versions of Windows, when the debugging session ends, the debugger will detach from CSRSS while the CSRSS process is still running. This avoids termination of the CSRSS process itself. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20CSRSS%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-1394-cable-connection.md b/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-1394-cable-connection.md new file mode 100644 index 0000000000..65caf092fe --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-1394-cable-connection.md @@ -0,0 +1,65 @@ +--- +title: Debugging Hyper-V via a 1394 Cable Connection +description: Debugging Hyper-V via a 1394 Cable Connection +ms.assetid: da183635-8dc9-4092-b4c3-104304ee45f7 +--- + +# Debugging Hyper-V via a 1394 Cable Connection + + +## + + +To debug the root partition or Windows hypervisor across a 1394 cable connection, use the following procedure. + +1. Verify that you have the proper version of Debugging Tools for Windows installed on the host computer. If you are unsure of which version to use, see [Choosing a 32-Bit or 64-Bit Debugger Package](choosing-a-32-bit-or-64-bit-debugger-package.md). + +2. On the target computer, use the BCDEdit tool to set the boot configuration settings to allow the debugging that you want. If you intend to debug the root partition, use the following commands: + + ``` + bcdedit /set dbgtransport kd1394.dll + bcdedit /dbgsettings 1394 CHANNEL:ChannelNumber + bcdedit /debug on + ``` + + If you intend to debug Windows hypervisor, use the following commands: + + ``` + bcdedit /hypervisorsettings 1394 CHANNEL:ChannelNumber + bcdedit /set hypervisordebug on + bcdedit /set hypervisorlaunchtype auto + ``` + + In these commands, *ChannelNumber* represents the number of the 1394 channel that you are using. For details on the use of BCDEdit, see [Editing Boot Options](https://msdn.microsoft.com/library/windows/hardware/ff542279). + + If you want to enable debugging of both the root partition and Window hypervisor, use both sets of BCDEdit commands described in this step, with two different 1394 channel numbers. + + After issuing these BCDEdit commands, restart the target computer. + +3. Connect the host computer and the target computer by connecting a null-modem cable between their COM ports. This is done exactly as in standard kernel debugging; for details, see [Setting Up a 1394 Cable Connection](setting-up-a-1394-cable-connection.md). + +4. The actual debugging session is started by using the Remote tool (Remote.exe) to launch KD. To begin debugging, use the following command: + + ``` + remote.exe /s "DbgPath\kd -k 1394:channel=ChannelNumber -y SymPath" RemoteID + ``` + + In this command, *ChannelNumber* represents the 1394 channel number you used in the BCDEdit command. To debug the root partition, use the channel number you specified for it; to debug Windows hypervisor, use the channel number you specified for it. *RemoteID* represents an identifying string that is used by the Remote tool (for example, **HyperV\_ROOT** or **HyperV\_HV**). *DbgPath* represents the root directory of the Debugging Tools for Windows installation, and *SymPath* represents the symbol path. You may include other KD options as well. If you want to connect remotely to KD from another computer, (using WinDbg or a second instance of KD), include the **-server** parameter followed by any permissible transport options. If you include the **-server** parameter, it must be the first parameter used. + + For example, the command to debug the root partition is similar to this: + + ``` + remote.exe /s "\debuggers\kd -k 1394:channel=50 -y srv*c:\localstore*https://msdl.microsoft.com/download/symbols" HyperV_ROOT + ``` + +At this point, you can debug the target normally. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Hyper-V%20via%20a%201394%20Cable%20Connection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-null-modem-cable-connection.md b/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-null-modem-cable-connection.md new file mode 100644 index 0000000000..4b98f478bb --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-hyper-v-via-a-null-modem-cable-connection.md @@ -0,0 +1,89 @@ +--- +title: Debugging Hyper-V via a Null-modem Cable Connection +description: Debugging Hyper-V via a Null-modem Cable Connection +ms.assetid: 93d78696-11fa-443b-9fbe-60d208aa91d5 +--- + +# Debugging Hyper-V via a Null-modem Cable Connection + + +## + + +To debug either the root partition or Windows hypervisor across a null-modem cable connection, use the following procedure. + +1. Verify that you have the proper version of Debugging Tools for Windows installed on the host computer. If you are unsure of which version to use, see [Choosing a 32-Bit or 64-Bit Debugger Package](choosing-a-32-bit-or-64-bit-debugger-package.md). To debug Hyper-V across a null-modem cable, the x64 package must be used. If a different version of the package is required for your target, use a 1394 cable to debug Hyper-V, + +2. Copy the file Kdhvcom.dll from the Debugging Tools for Windows package to the Windows\\system32 directory on the root partition of the target computer. + +3. On the target computer, use the BCDEdit tool to set the boot configuration settings to allow the debugging that you want. If you intend to debug the root partition, use the following commands: + + ``` + bcdedit /set dbgtransport kdhvcom.dll + bcdedit /dbgsettings serial DEBUGPORT:Port BAUDRATE:Baud + bcdedit /debug on + ``` + + If you intend to debug Windows hypervisor, use the following commands: + + ``` + bcdedit /hypervisorsettings serial DEBUGPORT:Port BAUDRATE:Baud + bcdedit /set hypervisordebug on + bcdedit /set hypervisorlaunchtype auto + ``` + + In these commands, *Port* represents the number of the COM port that you are using, and *Baud* represents the rate of the connection. For example, if you are using COM1 with a baud of 115,200, *Port* is **1** and *Baud* is **115200**. For details on the use of BCDEdit, see [Editing Boot Options](https://msdn.microsoft.com/library/windows/hardware/ff542279). + + If you want to enable debugging of both the root partition and Window hypervisor, use both sets of BCDEdit commands described in this step. + + After issuing these BCDEdit commands, restart the target computer. + +4. Connect the host computer and the target computer by connecting a null-modem cable between their COM ports. This is done exactly as in standard kernel debugging; for details, see [Setting Up a Null-Modem Cable Connection](setting-up-a-null-modem-cable-connection.md). + +5. Open a Command Prompt window on the host computer, and change the current directory to the root directory of the Debugging Tools for Windows installation. Run the vmdemux (virtual machine demultiplexer) tool, using the following command line: + + ``` + vmdemux -src com:port=Port,baud=Baud + ``` + + In this command, *Port* represents the number of the COM port you are using (including the "com" prefix), and *Baud* represents the rate of the connection. For example, if you are using COM1 with a baud of 115,200, *Port* is **com1** and *Baud* is **115200**. If you have already begun debugging Windows hypervisor and are restarting vmdemux, include the -channel 0 parameter as well. + + Vmdemux creates multiple named-pipe sessions across the COM connection: one channel for debugging Windows hypervisor and one channel for debugging the root partition. For each channel, vmdemux displays a connection string that can be used to connect a kernel debugger across that channel. + +6. The actual debugging session is started by using the Remote tool (Remote.exe) to launch KD. To begin debugging the root partition, use the following command: + + ``` + remote.exe /s "DbgPath\kd -k RPConnectionString -y SymPath" HyperV_ROOT + ``` + + To begin debugging Windows hypervisor, use the following command: + + ``` + remote.exe /s "DbgPath\kd -k HVConnectionString -y SymPath" HyperV_HV + ``` + + In these commands, *RPConnectionString* and *HVConnectionString* represent the connection strings for the root partition and Windows hypervisor, respectively, which were displayed in the output of vmdemux in the previous step. *DbgPath* represents the root directory of the Debugging Tools for Windows installation, and *SymPath* represents the symbol path. You may include other KD options as well. If you want to connect remotely to KD from another computer (using WinDbg or a second instance of KD), include the **-server** parameter followed by any permissible transport options. If you include the **-server** parameter, it must be the first parameter used. + + For example, the command to debug the root partition is similar to this: + + ``` + remote.exe /s "\debuggers\kd -k com:port=\\.\pipe\Vm1,pipe,resets=0,reconnect -y srv*c:\localstore*https://msdl.microsoft.com/download/symbols" HyperV_ROOT + ``` + + And the command to debug Windows hypervisor is similar to this: + + ``` + remote.exe /s "c:\debuggers\kd -k com:port=\\.\pipe\Vm0,pipe,resets=0,reconnect -y srv*c:\localstore*https://msdl.microsoft.com/download/symbols" HyperV_HV + ``` + +At this point, you can debug the target normally. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Hyper-V%20via%20a%20Null-modem%20Cable%20Connection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-in-assembly-mode.md b/windows-driver-docs-pr/debugger/debugging-in-assembly-mode.md new file mode 100644 index 0000000000..d5bbdcdbdb --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-in-assembly-mode.md @@ -0,0 +1,97 @@ +--- +title: Debugging in Assembly Mode +description: Debugging in Assembly Mode +ms.assetid: 048c43ff-7f9e-4a20-a524-44f66d92eefe +keywords: ["assembly debugging", "assembly mode", "assembly debugging, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging in Assembly Mode + + +## + + +If you have C or C++ source files for your application, you can use the debugger much more powerfully if you [debug in source mode](debugging-in-source-mode.md). + +However, there are many times you cannot perform source debugging. You might not have the source files for your application. You might be debugging someone else's code. You might not have built your executable files with full .pdb symbols. And even if you can do source debugging on your application, you might have to trace Microsoft Windows routines that your application calls or that are used to load your application. + +In these situations, you have to debug in assembly mode. Moreover, assembly mode has many useful features that are not present in source debugging. The debugger automatically displays the contents of memory locations and registers as they are accessed and displays the address of the program counter. This display makes assembly debugging a valuable tool that you can use together with source debugging. + +### Disassembly Code + +The debugger primarily analyzes binary executable code. Instead of displaying this code in raw format, the debugger *disassembles* this code. That is, the debugger converts the code from machine language to assembly language. + +You can display the resulting code (known as *disassembly code*) in several different ways: + +- The [**u (Unassemble)**](u--unassemble-.md) command disassembles and displays a specified section of machine language. + +- The [**uf (Unassemble Function)**](uf--unassemble-function-.md) command disassembles and displays a function. + +- The [**up (Unassemble from Physical Memory)**](up--unassemble-from-physical-memory-.md) command disassembles and displays a specified section of machine language that has been stored in physical memory. + +- The [**ur (Unassemble Real Mode BIOS)**](ur--unassemble-real-mode-bios-.md) command disassembles and displays a specified 16-bit real-mode code. + +- The [**ux (Unassemble x86 BIOS)**](ux--unassemble-x86-bios-.md) command disassembles and displays the x86-based BIOS code instruction set at a specified address. + +- (WinDbg only) The [disassembly window](view---disassembly.md) disassembles and displays a specified section of machine language. this window is automatically active if you select the **automatically open disassembly** command on the **window** menu. you can also open this window by clicking **disassembly** on the **view** menu, pressing alt+7, or pressing the **disassembly (alt+7)** button (![screen shot of the disassembly button](images/tbdisasm2.png)) on the WinDbg toolbar. + +The disassembly display appears in four columns: address offset, binary code, assembly language mnemonic, and assembly language details. The following example shows this display. + +``` +0040116b 45 inc ebp +0040116c fc cld +0040116d 8945b0 mov eax,[ebp-0x1c] +``` + +To the right of the line that represents the current program counter, the display shows the values of any memory locations or registers that are being accessed. If this line contains a branch instruction, the notation **\[br=1\]** or **\[br=0\]** appears. This notation indicates a branch that is or is not taken, respectively. + +You can use the [**.asm (Change Disassembly Options)**](-asm--change-disassembly-options-.md) command to change how the disassembled instructions are displayed. + +In WinDbg's Disassembly window, the line that represents the current program counter is highlighted. Lines where breakpoints are set are also highlighted. + +You can also use the following commands to manipulate assembly code: + +- The [**\# (Search for Disassembly Pattern)**](---search-for-disassembly-pattern-.md) command searches a region of memory for a specific pattern. This command is equivalent to searching the four columns of the disassembly display. + +- The [**a (Assemble)**](a--assemble-.md) command can take assembly instructions and translate them into binary machine code. + +### Assembly Mode and Source Mode + +The debugger has two different operating modes: *assembly mode* and *source mode*. + +When you are single-stepping through an application, the size of a single step is one line of assembly code or one line of source code, depending on the mode. + +Several commands create different data displays depending on the mode. + +In WinDbg, the [Disassembly window](disassembly-window.md) automatically moves to the foreground when you run or step through an application in assembly mode. In source mode, the [Source window](source-window.md) moves to the foreground. + +To set the mode, you can do one of the following: + +- Use the [**l+, l- (Set Source Options)**](l---l---set-source-options-.md) command to control the mode. The **l-t** command activates assembly mode. + +- (WinDbg only) Clear the **Source Mode** command on the **Debug** menu to cause the debugger to enter assembly mode.You can also click the **Source mode off** button (![screen shot of the source mode off button](images/tbasm.png)) on the toolbar. + +In WinDbg, when you are in assembly mode, **ASM** appears visible on the status bar. + +The shortcut menu in WinDbg's Disassembly window includes the **Highlight instructions from the current source line** command. This command highlights all of the instructions that correspond to the current source line. Frequently, a single source line corresponds to multiple assembly instructions. If code has been optimized, these assembly instructions might not be consecutive. The **Highlight instructions from the current source line** command enables you to find all of the instructions that were assembled from the current source line. + +### Assembly Language Source Files + +If your application was written in assembly language, the disassembly that the debugger produces might not exactly match your original code. In particular, NO-OPs and comments will not be present. + +If you want to debug your code by referencing the original .asm files, you must use source mode debugging. You can load the assembly file like a C or C++ source file. For more information about this kind of debugging, see [Debugging in Source Mode](debugging-in-source-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20in%20Assembly%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-in-source-mode.md b/windows-driver-docs-pr/debugger/debugging-in-source-mode.md new file mode 100644 index 0000000000..96c6c37b6b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-in-source-mode.md @@ -0,0 +1,154 @@ +--- +title: Debugging in Source Mode +description: Debugging in Source Mode +ms.assetid: b236f53b-2429-4085-b008-6648d1474ec2 +keywords: ["source debugging", "source mode", "source debugging, overview", "Build utility (build.exe), avoiding optimization"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging in Source Mode + + +## + + +Debugging an application is easier if you can analyze the source of the code, instead of the disassembled binaries. + +WinDbg, CDB, and KD can use source code in debugging, if the source language is C, C++, or assembly. + +### Compilation Requirements + +To use source debugging, you must have your compiler or linker create symbol files (.pdb files) when the binaries are built. These symbol files show the debugger how the binary instructions correspond to the source lines. + +Also, the debugger must be able to access the actual source files , because symbol files do not contain the actual source text. + +If it is possible, the compiler and linker should not optimize your code. Source debugging and access to local variables are more difficult, and sometimes almost impossible, if the code has been optimized. If you are using the Build utility as your compiler and linker, set the MSC\_OPTIMIZATION macro to **/Od /Oi** to avoid optimization. + +### Locating the Symbol Files and Source Files + +To debug in source mode, the debugger must be able to find the source files and the symbol files. For more information, see [Source Code](source-code.md). + +### Beginning Source Debugging + +The debugger can display source information whenever it has proper symbols and source files for the thread that is currently being debugged. + +If you start a new user-mode application by using the debugger, the initial break occurs when Ntdll.dll loads the application. Because the debugger does not have access to the Ntdll.dll source files, you cannot access source information for your application at this point. + +To move the program counter to the beginning of the application, add a breakpoint at the entry point to your binary. In the [Debugger Command window](debugger-command-window.md), type the following command. + +``` +bp main +g +``` + +The application is then loaded and stops when the **main** function is entered. (Of course, you can use any entry point, not only **main**.) + +If the application throws an exception, it breaks into the debugger. Source information is available at this point. However, if you issue a break by using the [**CTRL+C**](ctrl-c--break-.md), [CTRL+BREAK](debug---break.md), or Debug | Break command, the debugger creates a new thread, so you cannot see your source code. + +After you have reached a thread that you have source files for, you can use the Debugger Command window to execute source debugging commands. If you are using WinDbg, the [Source window](source-window.md) appears. If you have already opened a Source window by clicking **Open Source File** on the **File** menu, WinDbg typically create a new window for the source. You can close the previous window without affecting the debugging process. + +### Source Debugging in the WinDbg GUI + +If you are using WinDbg, a Source window appears as soon as the program counter is in code that the debugger has source information for. + +WinDbg displays one Source window for each source file that you or WinDbg opened. For more information about the text properties of this window, see [Source Windows](source-window.md). + +You can then step through your application or execute to a breakpoint or to the cursor. For more information about stepping and tracing commands, see [Controlling the Target](controlling-the-target.md). + +If you are in source mode, the appropriate Source window moves to the foreground as you step through your application. Because there are also Microsoft Windows routines that are called during the application's execution, the debugger might move a [Disassembly window](disassembly-window.md) to the foreground when this kind of call occurs (because the debugger does not have access to the source for these functions). When the program counter returns to known source files, the appropriate Source window becomes active. + +As you move through the application, WinDbg highlights your location in the Source window and the Disassembly window. Lines at which breakpoints are set are also highlighted. The source code is colored according to the parsing of the language. If the Source window has been selected, you can hover over a symbol with the mouse to evaluate it. For more information about these features and how to control them, see [Source Windows](source-window.md). + +To activate source mode in WinDbg, use the [**l+t**](l---l---set-source-options-.md) command, click **source mode** on the **debug** menu, or click the **source mode on** button (![screen shot of the source mode on button](images/tbsrc.png)) on the toolbar. + +When source mode is active, the **ASM** indicator appears unavailable on the status bar. + +You can view or alter the values of any local variables as you step through a function in source mode. For more information, see [Reading and Writing Memory](reading-and-writing-memory.md). + +### Source Debugging in the Debugger Command Window + +If you are using CDB, you do not have a separate Source window. However, you can still view your progress as you step through the source. + +Before you can do source debugging in CDB, you have to load source line symbols by issuing the [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command or by starting the debugger with the [**-lines command-line option**](cdb-command-line-options.md). + +If you execute an [**l+t**](l---l---set-source-options-.md) command, all program stepping is performed one source line at a time. Use **l-t** to step one assembly instruction at a time. If you are using WinDbg, this command has the same effect as selecting or clearing **Source Mode** on the **Debug** menu or using the toolbar buttons. + +The [**l+s**](l---l---set-source-options-.md) command displays the current source line and line number at the prompt. If you want to see only the line number, use **l+l** instead. + +If you use [**l+o**](l---l---set-source-options-.md) and **l+s**, only the source line is displayed while you step through the program. The program counter, disassembly code, and register information are hidden. This kind of display enables you to quickly step through the code and view nothing but the source. + +You can use the [**lsp (Set Number of Source Lines)**](lsp--set-number-of-source-lines-.md) command to specify exactly how many source lines are displayed when you step through or execute the application. + +The following sequence of commands is an effective way to step through a source file. + +``` +.lines enable source line information +bp main set initial breakpoint +l+t stepping will be done by source line +l+s source lines will be displayed at prompt +g run program until "main" is entered +pr execute one source line, and toggle register display off +p execute one source line +``` + +Because [**ENTER**](enter--repeat-last-command-.md) repeats the last command, you can now step through the application by using the ENTER key. Each step causes the source line, memory offset, and assembly code to appear. + +For more information about how to interpret the disassembly display, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +When the assembly code is displayed, any memory location that is being accessed is displayed at the right end of the line. You can use the [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) and [**e\* (Enter Values)**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) commands to view or change the values in these locations. + +If you have to view each assembly instruction to determine offsets or memory information, use [**l-t**](l---l---set-source-options-.md) to step by assembly instructions instead of source lines. The source line information can still be displayed. Each source line corresponds to one or more assembly instructions. + +All of these commands are available in WinDbg and in CDB. You can use the commands to view source line information from WinDbg's [Debugger Command window](debugger-command-window.md) instead of from the Source window. + +### Source Lines and Offsets + +You can also perform source debugging by using the expression evaluator to determine the offset that corresponds to a specific source line. + +The following command displays a memory offset. + +``` +? `[[module!]filename][:linenumber]` +``` + +If you omit *filename*, the debugger searches for the source file that corresponds to the current program counter. + +The debugger reads *linenumber* as a decimal number unless you add **0x** before it, regardless of the current default radix. If you omit *linenumber*, the expression evaluates to the initial address of the executable file that corresponds to the source file. + +This syntax is understood in CDB only if the **.lines** command or the **-lines** command-line option has loaded source line symbols. + +This technique is very versatile, because you can use it regardless of where the program counter is pointing. For example, this technique enables you to set breakpoints in advance, by using commands such as the following. + +``` +bp `source.c:31` +``` + +For more information, see [Source Line Syntax](source-line-syntax.md) and [Using Breakpoints](using-breakpoints.md). + +### Stepping and Tracing in Source Mode + +When you are debugging in source mode, there can be multiple function calls on a single source line. You cannot use the **p** and **t** commands to separate these function calls. + +For example, in the following command, the **t** command steps into both **GetTickCount** and **printf**, while the **p** command steps over both function calls. + +``` +printf( "%x\n", GetTickCount() ); +``` + +If you want to step over certain calls while tracing into other calls, use [**.step\_filter (Set Step Filter)**](-step-filter--set-step-filter-.md) to indicate which calls to step over. + +You can use **\_step\_filter** to filter out framework functions (for example, Microsoft Foundation Classes (MFC) or Active Template Library (ATL) calls). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20in%20Source%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-managed-code.md b/windows-driver-docs-pr/debugger/debugging-managed-code.md new file mode 100644 index 0000000000..899aeaa95c --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-managed-code.md @@ -0,0 +1,205 @@ +--- +title: Debugging Managed Code Using the Windows Debugger +description: You can use the windows debuggers (WinDbg, CDB, and NTSD) to debug target applications that contain managed code. +ms.assetid: eb4cc883-71ac-4a57-8654-07c3120310c0 +keywords: debugging, debug, Windbg, managed code debugging, .NET common language runtime, common language runtime, CLR , JIT compiler, JITted code +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Managed Code Using the Windows Debugger + + +You can use the windows debuggers (WinDbg, CDB, and NTSD) to debug target applications that contain managed code. To debug managed code, you must load the [SOS debugging extension (sos.dll)](http://go.microsoft.com/fwlink/p/?linkid=223345) and a data access component (mscordacwks.dll). + +The windows debuggers are separate from the Visual Studio debugger. For information about the distinction between the windows debuggers and the Visual Studio debugger, see [Windows Debugging](index.md). + +## Introduction to Managed Code + + +Managed code is executed together with the Microsoft .NET common language runtime (CLR). In a managed-code application, the binary code that the compiler produces is in Microsoft intermediate language (MSIL), which is platform-independent. + +When managed code is run, the runtime produces native code that is platform-specific. The process of generating native code from MSIL is called *just-in-time (JIT) compiling*. After the JIT compiler has compiled the MSIL for a specific method, the method's native code remains in memory. Whenever this method is later called, the native code executes and the JIT compiler does not have to be involved. + +You can build managed code by using several compilers that are manufactured by a variety of software producers. In particular, Microsoft Visual Studio can build managed code from several different languages including C#, Visual Basic, JScript, and C++ with managed extensions. + +The CLR is not updated every time the .NET Framework is updated. For example, versions 2.0, 3.0, and 3.5 of the .NET Framework all use version 2.0 of the CLR. The following table shows the version and filename of the CLR used by each version of the .NET Framework. + +| .NET Framework version | CLR version | CLR filename | +|------------------------|-------------|--------------| +| 1.1 | 1.1 | mscorwks.dll | +| 2.0 | 2.0 | mscorwks.dll | +| 3.0 | 2.0 | mscorwks.dll | +| 3.5 | 2.0 | mscorwks.dll | +| 4.0 | 4.0 | clr.dll | +| 4.5 | 4.0 | clr.dll | + +  + +## Debugging Managed Code + + +To debug managed code, the debugger must load these two components. + +- Data access component (DAC) (mscordacwks.dll) +- [SOS debugging extension (sos.dll)](http://go.microsoft.com/fwlink/p/?linkid=223345) + +**Note**  For all versions of the .NET Framework, the filename of the DAC is mscordacwks.dll, and the filename of the SOS debugging extension is sos.dll. + +  + +### Getting the SOS Debugging Extension (sos.dll) + +The SOS debugging extension (sos.dll) files are not included in the current version of Debugging Tools for Windows. + +For .NET Framework versions 2.0 and later, sos.dll is included in the .NET Framework installation. + +For version 1.*x* of the .NET Framework, sos.dll is not included in the .NET Framework installation. To get sos.dll for .NET Framework 1.*x*, download the 32-bit version of Windows 7 Debugging Tools for Windows. + +Windows 7 Debugging Tools for Windows is included in the Windows SDK for Windows 7, which is available at these two places: + +- [Windows SDK for Windows 7 and .NET Framework 4.0](http://go.microsoft.com/fwlink/p?LinkId=320327) +- [Windows SDK for Windows 7 and .NET Framework 4.0 (ISO)](http://go.microsoft.com/fwlink/p?LinkId=320328) + +If you are running an x64 version of Windows, use the [ISO](http://go.microsoft.com/fwlink/p?LinkID=320328) site, so that you can specify that you want the 32-bit version of the SDK. Sos.dll is included only in the 32-bit version of Windows 7 Debugging Tools for Windows. + +### Loading mscordacwks.dll and sos.dll (live debugging) + +Assume that the debugger and the application being debugged are running on the same computer. Then the .NET Framework being used by the application is installed on the computer and is available to the debugger. + +The debugger must load a version of the DAC that is the same as the version of the CLR that the managed-code application is using. The bitness (32-bit or 64-bit) must also match. The DAC (mscordacwks.dll) comes with the .NET Framework. To load the correct version of the DAC, attach the debugger to the managed-code application, and enter this command. + +**.cordll -ve -u -l** + +The output should be similar to this. + +``` +CLRDLL: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscordacwks.dll +CLR DLL status: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscordacwks.dll +``` + +To verify that the version of mscordacwks.dll matches the version of the CLR that the application is using, enter one of the following commands to display information about the loaded CLR module. + +**lmv mclr** (for version 4.0 of the CLR) + +**lmv mscorwks** (for version 1.0 or 2.0 of the CLR) + +The output should be similar to this. + +``` +start end module name +000007ff`26710000 000007ff`2706e000 clr (deferred) + Image path: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\clr.dll +... +``` + +In the preceding example, notice that the version of the CLR (clr.dll) matches the version of the DAC (mscordacwks.dll): v4.0.30319. Also notice that both components are 64-bit. + +When you use [**.cordll**](-cordll--control-clr-debugging-.md) to load the DAC, the SOS debugging extension (sos.dll) might get loaded automatically. If sos.dll doesn't get loaded automatically, you can use one of these commands to load it. + +**.loadby sos clr** (for version 4.0 of the CLR) + +**.loadby sos mscorwks** (for version 1.0 or 2.0 of the CLR) + +As an alternative to using [**.loadby**](-load---loadby--load-extension-dll-.md), you can use **.load**. For example, to load version 4.0 of the 64-bit CLR, you could enter a command similar to this. + +**.load C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\sos.dll** + +In the preceding output, notice that the version of the SOS debugging extension (sos.dll) matches the version of the CLR and the DAC: v4.0.30319. Also notice that all three components are 64-bit. + +### Loading mscordacwks.dll and sos.dll (dump file) + +Suppose you use the debugger to open a dump file (of a managed-code application) that was created on another computer. + +The debugger must load a version of the DAC that is the same as the version of the CLR that the managed-code application was using on the other computer. The bitness (32-bit or 64-bit) must also match. + +The DAC (mscordacwks.dll) comes with the .NET Framework, but let's assume that you do not have the correct version of the .NET Framework installed on the computer that is running the debugger. You have three options. + +- Load the DAC from a symbol server. For example, you could include Microsoft's public symbol server in your symbol path. +- Install the correct version of the .NET Framework on the computer that is running the debugger. +- Get the correct version of mscordacwks.dll from the person who created the dump file (on another computer) and manually copy it to the computer that is running the debugger. + +Here we illustrate using Microsoft's public symbol server. + +Enter these commands. + +**.sympath+ srv\*** (Add symbol server to symbol path.) + +**!sym noisy** + +**.cordll -ve -u -l** + +The output will be similar to this. + +``` +CLRDLL: Unable to get version info for 'C:\Windows\Microsoft.NET + \Framework64\v4.0.30319\mscordacwks.dll', Win32 error 0n87 + +SYMSRV: C:\ProgramData\dbg\sym\mscordacwks_AMD64_AMD64_4.0.30319.18010.dll + \5038768C95e000\mscordacwks_AMD64_AMD64_4.0.30319.18010.dll not found + +SYMSRV: mscordacwks_AMD64_AMD64_4.0.30319.18010.dll from + http://msdl.microsoft.com/download/symbols: 570542 bytes - copied +... +SYMSRV: C:\ProgramData\dbg\sym\SOS_AMD64_AMD64_4.0.30319.18010.dll + \5038768C95e000\SOS_AMD64_AMD64_4.0.30319.18010.dll not found + +SYMSRV: SOS_AMD64_AMD64_4.0.30319.18010.dll from + http://msdl.microsoft.com/download/symbols: 297048 bytes - copied +... +Automatically loaded SOS Extension +... +``` + +In the preceding output, you can see that the debugger first looked for mscordacwks.dll and sos.dll on the local computer in C:\\Windows\\Microsoft.NET and in the symbol cache (C:\\ProgramData\\dbg\\sym). When the debugger did not find the correct versions of the files on the local computer, it retrieved them from the public symbol server. + +To verify that the version of mscordacwks.dll matches the version of the CLR that the application was using, enter one of the following commands to display information about the loaded CLR module. + +**lmv -mclr** (for version 4.0 of the CLR) + +**lmv -mscorwks** (for version 1.0 or 2.0 of the CLR) + +The output should be similar to this. + +``` +start end module name +000007ff`26710000 000007ff`2706e000 clr (deferred) + Image path: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\clr.dll +... +``` + +In the preceding example, notice that the version of the CLR (clr.dll) matches the version of the DAC (mscordacwks.dll): v4.0.30319. Also notice that both components are 64-bit. + +### Using the SOS Debugging Extension + +To verify that the SOS debugging extension loaded correctly, enter the [**.chain**](-chain--list-debugger-extensions-.md) command. + +``` +0:000> .chain +Extension DLL search Path: +... +Extension DLL chain: + C:\ProgramData\dbg\sym\SOS_AMD64_AMD64_4.0.30319.18010.dll\... + ... + dbghelp: image 6.13.0014.1665, API 6.2.6, built Wed Dec 12 03:02:43 2012 +... +``` + +To test the SOS debugging extension, enter **!sos.help**. Then try one of the command provided by the SOS debugging extension. For example, you could try **!sos.DumpDomain** or the **!sos.Threads** command. + +### Notes + +Sometimes a managed-code application loads more than one version of the CLR. In that case, you must specify which version of the DAC to load. For more information, see [**.cordll**](-cordll--control-clr-debugging-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Managed%20Code%20Using%20the%20Windows%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-multiple-targets.md b/windows-driver-docs-pr/debugger/debugging-multiple-targets.md new file mode 100644 index 0000000000..c99f3c198f --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-multiple-targets.md @@ -0,0 +1,155 @@ +--- +title: Debugging Multiple Targets +description: Debugging Multiple Targets +ms.assetid: 93eb6b49-e7a0-4f30-ade8-94019a1adf43 +keywords: ["multiple targets", "system", "system, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Multiple Targets + + +## + + +You can debug multiple dump files or live user-mode applications at the same time. Each target contains one or more processes, and each process contains one or more threads. + +These targets are also grouped into *systems*. Systems are sets of targets that are grouped together for easy identification and manipulation. Systems are defined as follows: + +- Each kernel-mode or user-mode dump file is a separate system. + +- When you are debugging live user-mode applications on different computers (by using a [process server](process-servers--user-mode-.md), such as Dbgsrv), each application is a separate system. + +- When you are debugging live user-mode applications on the local computer, the applications are combined into a single system. + +The *current* or *active* system is the system that you are currently debugging. + +### Acquiring Multiple Targets + +The first target is acquired in the usual manner. + +You can debug additional live user-mode applications by using the [**.attach (Attach to Process)**](-attach--attach-to-process-.md) or [**.create (Create Process)**](-create--create-process-.md) command, followed by the **g (Go)** command. + +You can debug additional dump files by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed by the **g (Go)** command. You can also open multiple dump files when the debugger is started. To open multiple dump files, include multiple **-z** switches in the command, each followed by a different file name. + +You can use the preceding commands even if the processes are on different systems. You must start a process server on each system and then use the -premote parameter with **.attach** or **.create** to identify the proper process server. If you use the **.attach** or **.create** command again without specifying the -premote parameter, the debugger attaches to, or creates, a process on the current system. + +### Manipulating Systems and Targets + +When debugging begins, the current system is the one that the debugger most recently attached to. If an exception occurs, the current system switches to the system that this exception occurred on. + +To close one target and continue to debug the other targets, use the [**.kill (Kill Process)**](-kill--kill-process-.md) command. You can use the [**.detach (Detach from Process)**](-detach--detach-from-process-.md) command or WinDbg's [Debug | Detach Debuggee](debug---detach-debuggee.md) menu command instead. These commands detach the debugger from the target but leave the target running. + +To control the debugging of multiple systems, you can use the following methods: + +- The [**|| (System Status)**](----system-status-.md) command displays information about one or more systems + +- The [**||s (Set Current System)**](--s--set-current-system-.md) command enables you to select the current system + +- (WinDbg only) The [Processes and Threads window](processes-and-threads-window.md) enables you display or select systems, processes, and threads + +By using these commands to select the current system, and by using the standard commands to [select the current process and thread](controlling-processes-and-threads.md), you can determine the context of commands that display memory and registers. + +However, you cannot separate execution of these processes. The [**g (Go)**](g--go-.md) command always causes all targets to execute together. + +**Note**   There are complications, when you debug live targets and dump targets together, because commands behave differently for each type of debugging. For example, if you use the **g (Go)** command when the current system is a dump file, the debugger begins executing, but you cannot break back into the debugger, because the break command is not recognized as valid for dump file debugging. + +  +Example +------- + +To work with three dump files at the same time, you can use the -z option to load them when WinDbg is started. + +``` +windbg -z c:\notepad.dmp -z c:\paint.dmp -z c:\calc.dmp +``` + +For more infomation see [WinDbg Command-Line Options](windbg-command-line-options.md). You can also use the [.opendump](-opendump--open-dump-file-.md) and the [**g (Go)**](g--go-.md) commands to load additional dump files in the debugger. + +Use the [|| (System Status)](----system-status-.md) command to confirm that all three systems are present. + +``` +||0:0:007> || +. 0 User mini dump: c:\notepad.dmp + 1 User mini dump: C:\paint.dmp + 2 User mini dump: c:\calc.dmp +``` + +Use the The [**g (Go)**](g--go-.md) command to complete loading of the dump files. +``` +||0:0:007> g + +************* Path validation summary ************** +Response Time (ms) Location +Deferred srv* +Symbol search path is: srv* +Executable search path is: +Windows 10 Version 15063 MP (4 procs) Free x64 +Product: WinNt, suite: SingleUserTS +15063.0.amd64fre.rs2_release.170317-1834 +Machine Name: +Debug session time: Fri Jun 9 15:52:04.000 2017 (UTC - 7:00) +System Uptime: not available +Process Uptime: 0 days 0:03:44.000 +............................................................... +This dump file has a breakpoint exception stored in it. +The stored exception information can be accessed via .ecxr. +ntdll!DbgBreakPoint: +00007ff8`aada8d70 cc int 3 + +``` + +Then use the [||s (Set Current System)](--s--set-current-system-.md) command to set the current system to system 1 and then display the current system. + +``` +||1:1:017> ||1s +||1:1:017> || + 0 User mini dump: c:\notepad.dmp +. 1 User mini dump: c:\paint.dmp + 2 User mini dump: c:\calc.dmp + +``` + +You can use the [.detach](-detach--detach-from-process-.md) command when you are done looking at the current dump file. + +``` +||1:1:017> .detach +ntdll!DbgBreakPoint: +00007ff8`aada8d70 cc int 3 +Detached +||0:0:007> || +. 0 User mini dump: c:\notepad.dmp + 2 User mini dump: c:\calc.dmp +``` + +Resources +--------- + +For addtional information on debugging see the following resources. + +**Books** + +- Advanced Windows Debugging by Mario Hewardt and Daniel Pravat + +- Inside Windows Debugging: A Practical Guide to Debugging and Tracing Strategies in Windows by Tarik Soulami + +- Windows Internals by Pavel Yosifovich, Alex Ionescu, Mark E. Russinovich and David A. Solomon + +**Video** + +The Defrag Tools Show WinDbg Episodes 13-29 [http://channel9.msdn.com/Shows/Defrag-Tools](http://channel9.msdn.com/Shows/Defrag-Tools) + + + + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Multiple%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-oca-minidump-files.md b/windows-driver-docs-pr/debugger/debugging-oca-minidump-files.md new file mode 100644 index 0000000000..186394faa0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-oca-minidump-files.md @@ -0,0 +1,77 @@ +--- +title: Debugging OCA minidump files +description: Online Crash Analysis (OCA) is the reporting facility for Windows Error Reporting (WER) information. Your company can use OCA crash dumps to analyze customer problems. +ms.assetid: 56F4202D-6A5F-4177-BBFD-70DA717FF24A +--- + +# Debugging OCA minidump files + + +Online Crash Analysis (OCA) is the reporting facility for [Windows Error Reporting (WER)](http://msdn.microsoft.com/en-US/library/windows/hardware/gg487440) information. Your company can use OCA crash dumps to analyze customer problems. + +## Analyze dump files + + +Dump files are a snapshot of the state of the computer (or process) at the time of the crash. + +To analyze this data, a developer must use a debugger that can read user minidump files. The debugger must also have access to both the images and symbols that match the contents of the dump file. Most developers are aware of the need to use matching symbols when debugging a live crash. However, when debugging a minidump, matching images must also be available for the debugger. + +Matching images must be available because minidump files store very little information; they store only some of the volatile information at the time of the crash. They do not store the basic code streams that the computer loaded into memory. Instead, to save space, the minidump file stores only the name and time stamp of the images loaded on the crashing computer. + +To examine the code that was running on the crashing computer, the debugger must be given access to the same binaries that the crashing computer was running. The debugger uses the name and time stamp stored in the minidump file to uniquely match and load the binaries when the developer wants to debug the crash. + +After the images and symbols are loaded in the debugger, you can analyze the state of the system at the time of the crash, including data that was saved after the crash occurred. The minidump does not, however, reproduce the steps that led to the specific failure. Finding the root cause requires analyzing the driver's source code to determine what code path may have led to the failure. Experience has shown that a large percentage of failures can be understood and addressed by analyzing dump files and source code. + +## Use symbols to match executable code with source code + + +The best way to access matching images and symbols is to use the Microsoft symbol server. Symbols are data that enable the debugger to map the executable code back to the source code. When you build a program, the program's symbols are usually stored in symbol files. When a debugger analyzes a program, it needs to access the program's symbols. + +Symbol files can include any or all of the following: + +- The names and addresses of all functions. +- All data type, structure, and class definitions. +- The names, data types, and addresses of global variables. +- The names, data types, addresses, and scopes of local variables. +- The line number in the source code that corresponds to each binary instruction. + +The [Windows Driver Kit (WDK)](http://msdn.microsoft.com/en-US/library/windows/hardware/gg487463) includes tools that can be used to reduce the number of symbols in a symbol file. The symbol files that contain all of the source-level information are called full symbol files. The symbol files with reduced information are called stripped symbol files. + +Because symbol data is crucial for getting meaningful crash information from Windows Error Report (WER) data, we encourage you to submit your symbols when you submit drivers to be signed. When symbols are submitted, they are stored on a server that synchronizes symbol data with the associated WER processes. With this storage process, you can easily categorize the crashes reported in the minidump files and ultimately receive better data back from Microsoft. + +Microsoft provides a symbol server on the Internet that you can use to analyze the Windows modules that are present in minidump files. The server includes stripped symbol files for Windows and a few other products. Microsoft has added the binaries for Windows XP and Windows Server 2003. You can use the Internet symbol server and the Debugging Tools for Windows to analyze minidump files. + +## Integrate WER into applications + + +Information on integrating WER into applications can be found on MSDN at [Using WER](http://msdn.microsoft.com/library/bb513616.aspx). + +## Related topics + + +[Advanced Driver Debugging \[336 KB\] \[PPT\]](http://download.microsoft.com/download/f/0/5/f05a42ce-575b-4c60-82d6-208d3754b2d6/adv-drv_debug.ppt) + +[WDK and WinDbg downloads](https://go.microsoft.com/fwlink/p/?LinkId=733614) + +[Driver Debugging Basics \[WinHEC 2007; 633 KB\] \[PPT\]](http://download.microsoft.com/download/a/f/d/afdfd50d-6eb9-425e-84e1-b4085a80e34e/dvr-t410_wh07.pptx) + +[How to read the small memory dump file that is created by Windows if a crash occurs](http://support.microsoft.com/kb/315263) + +[Resource-Definition Statements](http://msdn.microsoft.com/library/aa381043.aspx) + +[Windows Error Reporting](http://msdn.microsoft.com/library/bb513641(vs.85).aspx) + +[MSDN Webcast: Windows Error Reporting (Level 200)](https://msevents.microsoft.com/CUI/EventDetail.aspx?EventId=1032314332) + +[VERSIONINFO resource](http://msdn.microsoft.com/library/aa381058.aspx) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20OCA%20minidump%20files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-optimized-code-and-inline-functions-external.md b/windows-driver-docs-pr/debugger/debugging-optimized-code-and-inline-functions-external.md new file mode 100644 index 0000000000..1095a6f79c --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-optimized-code-and-inline-functions-external.md @@ -0,0 +1,189 @@ +--- +title: Debugging Optimized Code and Inline Functions +description: For Windows 8, the debugger and the Windows compiler have been enhanced so that you can debug optimized code and debug inline functions. +ms.assetid: C7BE6B8E-9CF2-471C-A4F9-931C71CCC0FE +keywords: ["debug optimized code", "debug inline functions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Optimized Code and Inline Functions + + +For Windows 8, the debugger and the Windows compiler have been enhanced so that you can debug optimized code and debug inline functions. The debugger displays parameters and local variables regardless of whether they are stored in registers or on the stack. The debugger also displays inline functions in the call stack. For inline functions, the debugger displays local variables, but not parameters. + +When code gets optimized, it is transformed to run faster and use less memory. Sometimes functions are removed as a result of dead code removal, code being merged, or functions being placed inline. Local variables and parameters can also be removed. Many code optimizations remove local variables that are not needed or used; other optimizations remove induction variables in loops. Common sub-expression elimination merges local variables together. + +Retail builds of Windows are optimized. So if you are running a retail build of Windows, it is especially helpful to have a debugger that is designed to work well with optimized code. To make debugging of optimized code effective, two primary features are required: 1) accurate display of local variables, and 2) display of inline functions on the call stack. + +## Accurate display of local variables and parameters + + +To facilitate the accurate display of local variables and parameters, the compiler records information about the locations of local variables and parameters in symbol (PDB) files. These location records track the variables’ storage locations and the specific code ranges where these locations are valid. These records not only help track the locations (in registers or in stack slots) of the variables, but also the movement of the variables. For example, a parameter might first be in register RCX, but is moved to a stack slot to free up RCX, then moved to register R8 when it is heavily used in a loop, and then moved to different stack slot when the code is out of the loop. The Windows debugger consumes the rich location records in the PDB files and uses the current instruction pointer to select the appropriate location records for the local variables and parameters. + +This screen shot of the Locals window in Visual Studio shows the parameters and local variables for a function in an optimized 64-bit application. The function is not inline, so we see both parameters and local variables. + +![screen shot of the locals window](images/optimizedcode01.png) + +You can use the [**dv -v**](dv--display-local-variables-.md) command to see the locations of the parameters and local variables. + +![screen shot that shows the locations of parameters and local variables](images/optimizedcode02.png) + +Notice that the Locals window displays the parameters correctly even though they are stored in registers. + +In addition to tracking variables with primitive types, the location records track data members of local structures and classes. The following debugger output displays local structures. + +``` +0:000> dt My1 +Local var Type _LocalStruct + +0x000 i1 : 0n0 (edi) + +0x004 i2 : 0n1 (rsp+0x94) + +0x008 i3 : 0n2 (rsp+0x90) + +0x00c i4 : 0n3 (rsp+0x208) + +0x010 i5 : 0n4 (r10d) + +0x014 i6 : 0n7 (rsp+0x200) + +0:000> dt My2 +Local var @ 0xefa60 Type _IntSum + +0x000 sum1 : 0n4760 (edx) + +0x004 sum2 : 0n30772 (ecx) + +0x008 sum3 : 0n2 (r12d) + +0x00c sum4 : 0n0 +``` + +Here are some observations about the preceding debugger output. + +- The local structure **My1** illustrates that the compiler can spread local structure data members to registers and non-contiguous stack slots. +- The output of the command **dt My2** will be different from the output of the command **dt \_IntSum 0xefa60**. You cannot assume that the local structure will occupy a contiguous block of stack memory. In the case of **My2**, only `sum4` stays in the original stack block; the other three data members are moved to registers. +- Some data members can have multiple locations. For example, **My2.sum2** has two locations: one is register ECX (which the Windows debugger chooses) and the other is 0xefa60+0x4 (the original stack slot). This could happen for primitive-type local variables also, and the Windows debugger imposes precedent heuristics to determine which location to use. For example, register locations always trump stack locations. + +## Display of inline functions on the call stack + + +During code optimization, some functions are placed in line. That is, the body of the function is placed directly in the code like a macro expansion. There is no function call and no return to the caller. To facilitate the display of inline functions, the compiler stores data in the PDB files that helps decode the code chunks for the inline functions (that is, sequences of code blocks in caller functions that belong to the callee functions that are being placed inline) as well as the local variables (scoped local variables in those code blocks). This data helps the debugger include inline functions as part of the stack unwind. + +Suppose you compile an application and force a function named `func1` to be inline. + +``` +__forceinline int func1(int p1, int p2, int p3) +{ + int num1 = 0; + int num2 = 0; + int num3 = 0; + ... +} +``` + +You can use the [**bm**](bp--bu--bm--set-breakpoint-.md) command to set a breakpoint at `func1`. + +``` +0:000> bm MyApp!func1 + 1: 000007f6`8d621088 @!"MyApp!func1" (MyApp!func1 inlined in MyApp!main+0x88) +0:000> g + +Breakpoint 1 hit +MyApp!main+0x88: +000007f6`8d621088 488d0d21110000 lea rcx,[MyApp!`string' (000007f6`8d6221b0)] +``` + +After you take one step into `func1`, you can use the [**k**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command to see `func1` on the call stack. You can use the [**dv**](dv--display-local-variables-.md) command to see the local variables for `func1`. Notice that the local variable `num3` is shown as unavailable. A local variable can be unavailable in optimized code for a number of reasons. It might be that the variable doesn't exist in the optimized code. It might be that the variable has not been initialized yet or that the variable is no longer being used. + +``` +0:000> p +MyApp!func1+0x7: +000007f6`8d62108f 8d3c33 lea edi,[rbx+rsi] + +0:000> knL +# Child-SP RetAddr Call Site +00 (Inline Function) --------`-------- MyApp!func1+0x7 +01 00000000`0050fc90 000007f6`8d6213f3 MyApp!main+0x8f +02 00000000`0050fcf0 000007ff`c6af0f7d MyApp!__tmainCRTStartup+0x10f +03 00000000`0050fd20 000007ff`c7063d6d KERNEL32!BaseThreadInitThunk+0xd +04 00000000`0050fd50 00000000`00000000 ntdll!RtlUserThreadStart+0x1d + +0:000> dv -v +00000000`0050fcb0 num1 = 0n0 +00000000`0050fcb4 num2 = 0n0 + num3 = +``` + +If you look at frame 1 in the stack trace, you can see the local variables for the `main` function. Notice that two of the variables are stored in registers. + +``` +0:000> .frame 1 +01 00000000`0050fc90 000007f6`8d6213f3 MyApp!main+0x8f + +0:000> dv -v +00000000`0050fd08 c = 0n7 +@ebx b = 0n13 +@esi a = 0n6 +``` + +The Windows debugger aggregates data from PDB files to find all the places where a specific function has been placed inline. You can use the [**x**](x--examine-symbols-.md) command to list all the caller sites of the an inline function. + +``` +0:000> x simple!MoreCalculate +00000000`ff6e1455 simple!MoreCalculate = (inline caller) simple!wmain+8d +00000000`ff6e1528 simple!MoreCalculate = (inline caller) simple!wmain+160 + +0:000> x simple!Calculate +00000000`ff6e141b simple!Calculate = (inline caller) simple!wmain+53 +``` + +Because the Windows debugger can enumerate all the caller sites of an inline function, it can set a breakpoints inside the inline function by calculating the offsets from the caller sites. You can use the [**bm**](bp--bu--bm--set-breakpoint-.md) command (which is used to set breakpoints that match regular expression patterns) to set breakpoints for inline functions. + +The Windows debugger groups all breakpoints that are set for a specific inline function into a breakpoint container. You can manipulate the breakpoint container as a whole by using commands like [**be**](be--breakpoint-enable-.md), [**bd**](bd--breakpoint-disable-.md), [**bc**](bc--breakpoint-clear-.md). See the following **bd 3** and **bc 3** command examples. You can also manipulate individual breakpoints. See the following **be 2** command example. + +``` +0:000> bm simple!MoreCalculate + 2: 00000000`ff6e1455 @!"simple!MoreCalculate" (simple!MoreCalculate inlined in simple!wmain+0x8d) + 4: 00000000`ff6e1528 @!"simple!MoreCalculate" (simple!MoreCalculate inlined in simple!wmain+0x160) + +0:000> bl + 0 e 00000000`ff6e13c8 [n:\win7\simple\simple.cpp @ 52] 0001 (0001) 0:**** simple!wmain + 3 e 0001 (0001) 0:**** {simple!MoreCalculate} + 2 e 00000000`ff6e1455 [n:\win7\simple\simple.cpp @ 58] 0001 (0001) 0:**** simple!wmain+0x8d (inline function simple!MoreCalculate) + 4 e 00000000`ff6e1528 [n:\win7\simple\simple.cpp @ 72] 0001 (0001) 0:**** simple!wmain+0x160 (inline function simple!MoreCalculate) + +0:000> bd 3 +0:000> be 2 + +0:000> bl + 0 e 00000000`ff6e13c8 [n:\win7\simple\simple.cpp @ 52] 0001 (0001) 0:**** simple!wmain + 3 d 0001 (0001) 0:**** {simple!MoreCalculate} + 2 e 00000000`ff6e1455 [n:\win7\simple\simple.cpp @ 58] 0001 (0001) 0:**** simple!wmain+0x8d (inline function simple!MoreCalculate) + 4 d 00000000`ff6e1528 [n:\win7\simple\simple.cpp @ 72] 0001 (0001) 0:**** simple!wmain+0x160 (inline function simple!MoreCalculate) + +0:000> bc 3 + +0:000> bl + 0 e 00000000`ff6e13c8 [n:\win7\simple\simple.cpp @ 52] 0001 (0001) 0:**** simple!wmain +``` + +Because there are no explicit call or return instructions for inline functions, source-level stepping is especially challenging for a debugger. For example, you could unintentionally step in to an inline function (if the next instruction is part of an inline function), or you could step in and step out of the same inline function multiple times (because the code blocks for the inline function have been split and moved by the compiler). To preserve the familiar stepping experience, the Windows debugger maintains a small conceptual call stack for every code instruction address and builds an internal state machine to execute step-in, step-over, and step-out operations. This gives a reasonably accurate approximation to the stepping experience for non-inline functions. + +## Additional Information + + +**Note**  You can use the **.inline 0** command to disable inline function debugging. The **.inline 1** command enables inline function debugging. [Standard Debugging Techniques](standard-debugging-techniques.md) + +  + +## Related topics + + +[Standard Debugging Techniques](standard-debugging-techniques.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Optimized%20Code%20and%20Inline%20Functions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-performance-optimized-code.md b/windows-driver-docs-pr/debugger/debugging-performance-optimized-code.md new file mode 100644 index 0000000000..a4fcc0e176 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-performance-optimized-code.md @@ -0,0 +1,107 @@ +--- +title: Debugging Performance-Optimized Code +description: Debugging Performance-Optimized Code +ms.assetid: 9dbae9e7-c181-491e-9566-6f5e8182aae0 +keywords: ["performance-optimized code"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Performance-Optimized Code + + +## + + +Microsoft has certain techniques that it uses to re-arrange compiled and linked code so that it executes with more efficiency. These techniques optimize the component for memory hierarchies, and are based on training scenarios. + +The resulting optimization reduces paging (and page faults), and increases spatial locality between code and data. It addresses a key performance bottleneck that would be introduced by poor positioning of the original code. A component that has gone through this optimization may have its code or data block within a function moved to different locations of the binary. + +In modules that have been optimized by these techniques, the locations of code and data blocks will often be found at memory addresses different than the locations where they would reside after normal compilation and linking. Furthermore, functions may have been split into many non-contiguous blocks, in order that the most commonly-used code paths can be located close to each other on the same pages. + +Therefore, a function (or any symbol) plus an offset will not necessarily have the same meaning it would have in non-optimized code. + +### Debugging Performance-Optimized Code + +When debugging, you can see if a module has been performance-optimized by using the [**!lmi**](-lmi.md) extension command on any module for which symbols have been loaded: + +``` +0:000> !lmi ntdll +Loaded Module Info: [ntdll] + Module: ntdll + Base Address: 77f80000 + Image Name: ntdll.dll + Machine Type: 332 (I386) + Time Stamp: 394193d2 Fri Jun 09 18:03:14 2000 + CheckSum: 861b1 +Characteristics: 230e stripped perf +Debug Data Dirs: Type Size VA Pointer + MISC 110, 0, 76c00 [Data not mapped] + Image Type: DBG - Image read successfully from symbol server. + c:\symbols\dll\ntdll.dbg + Symbol Type: DIA PDB - Symbols loaded successfully from symbol server. + c:\symbols\dll\ntdll.pdb +``` + +In this output, notice the term **perf** on the "Characteristics" line. This indicates that this performance optimization has been applied to ntdll.dll. + +The debugger is able to understand a function or other symbol without an offset; this allows you to set breakpoints on functions or other labels without any problem. However, the output of a dissassembly operation may be confusing, because this disassembly will reflect the changes made by the optimizer. + +Since the debugger will try to stay close to the original code, you might see some amusing results. The rule of thumb when working with performance-optimized codes is simply that you cannot perform reliable address arithmetic on optimized code. + +Here is an example: + +``` +kd> bl + 0 e f8640ca6 0001 (0001) tcpip!IPTransmit + 1 e f8672660 0001 (0001) tcpip!IPFragment + +kd> u f864b4cb +tcpip!IPTransmit+e48: +f864b4cb f3a4 rep movsb +f864b4cd 8b75cc mov esi,[ebp-0x34] +f864b4d0 8b4d10 mov ecx,[ebp+0x10] +f864b4d3 8b7da4 mov edi,[ebp-0x5c] +f864b4d6 8bc6 mov eax,esi +f864b4d8 6a10 push 0x10 +f864b4da 034114 add eax,[ecx+0x14] +f864b4dd 57 push edi +``` + +You can see from the breakpoint list that the address of **IPTransmit** is 0xF8640CA6. + +When you unassemble a section of code within this function at 0xF864B4CB, the output indicates that this is 0xE48 bytes past the beginning of the function. However, if you subtract the base of the function from this address, the actual offset appears to be 0xA825. + +What is happening is this: The debugger is indeed showing a disassembly of the binary instructions beginning at 0xF864B4CB. But instead of computing the offset by simple subtraction, the debugger displays -- as best it can -- the offset to the function entry as it existed in the original code before the optimizations were performed. That value is 0xE48. + +On the other hand, if you try to look at **IPTransmit**+0xE48, you will see this: + +``` +kd> u tcpip!iptransmit+e48 +tcpip!ARPTransmit+d8: +f8641aee 0856ff or [esi-0x1],dl +f8641af1 75fc jnz tcpip!ARPTransmit+0xd9 (f8641aef) +f8641af3 57 push edi +f8641af4 e828eeffff call tcpip!ARPSendData (f8640921) +f8641af9 5f pop edi +f8641afa 5e pop esi +f8641afb 5b pop ebx +f8641afc c9 leave +``` + +What is happening here is that the debugger recognizes the symbol **IPTransmit** as equivalent to the address 0xF8640CA6, and the command parser performs a simple addition to find that 0xF8640CA6 + 0xE48 = 0xF8641AEE. This address is then used as the argument for the [**u (Unassemble)**](u--unassemble-.md) command. But once this location is analyzed, the debugger discovers that this is not **IPTransmit** plus an offset of 0xE48. Indeed, it is not part of this function at all. Rather, it corresponds to the function **ARPTransmit** plus an offset of 0xD8. + +The reason this happens is that performance optimization is not reversible through address arithmetic. While the debugger can take an address and deduce its original symbol and offset, it does not have enough information to take a symbol and offset and translate it to the correct address. Consequently, disassembly is not useful in these cases. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Performance-Optimized%20Code%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-previous-versions-of-windows.md b/windows-driver-docs-pr/debugger/debugging-previous-versions-of-windows.md new file mode 100644 index 0000000000..e7148ace3d --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-previous-versions-of-windows.md @@ -0,0 +1,37 @@ +--- +title: Debugging Previous Versions of Windows +description: . +ms.assetid: 4751D53D-A7CD-4645-B6E9-A8E06ABF4C6D +--- + +# Debugging Previous Versions of Windows + + +For more information about debugging with previous versions of Windows, see these topics: + +- [Debugging Tools For Windows: What's New](debugging-tools-for-windows--what-s-new.md) +- [Debugging Tools For Windows8 Release Notes](debugging-tools-for-windows8-release-notes.md) +- [Debugging Windows XP and Windows Vista](debugging-windows-xp-and-windows-vista.md) +- [Debugging Using Visual Studio](debugging-using-visual-studio.md) +- [Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +## Windows 7 Debugging Tools for Windows + + +To debug code running on Windows Vistaor Windows Server 2008, get the Windows 7 Debugging Tools for Windows package, which is included in the [Microsoft Windows Software Development Kit (SDK) for Windows 7 and .NET Framework 4.0](http://go.microsoft.com/fwlink/p/?LinkId=320327). If you want to download only Debugging Tools for Windows, install the SDK, and, during the installation, select the **Debugging Tools for Windows** box and clear all the other boxes. + +## Related topics + + +[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Previous%20Versions%20of%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-resources.md b/windows-driver-docs-pr/debugger/debugging-resources.md new file mode 100644 index 0000000000..ea6b391a73 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-resources.md @@ -0,0 +1,80 @@ +--- +title: Debugging Resources +description: Use Debugging Tools for Windows to debug drivers, applications, and services on Windows systems. +ms.assetid: F2111416-EC6C-4967-B123-9A6101040561 +--- + +# Debugging Resources + + +Use Debugging Tools for Windows to debug drivers, applications, and services on Windows systems. The core debugging engine in the tool set is called the Windows debugger. Starting with Windows 8, you can use Visual Studio as your interface to the Windows debugger. You can also use the traditional interfaces (WinDbg, CDB, and NTSD), which are included in Debugging Tools for Windows. + +## Getting Started with Debugging Tools for Windows + + +- [Windows Debugging](index.md) + +## Installing Debugging Tools for Windows + + +- [Download and Install Debugging Tools for Windows](http://msdn.microsoft.com/en-US/windows/hardware/gg463009) + +## Debugger How-Tos + + +- [Advanced Driver Debugging: Part 1 \[media file\]](http://download.microsoft.com/download/B/1/6/B161948D-EDE1-4AEF-8776-AD485CDDCD9E/TDDR05003.wvx) +- [Advanced Driver Debugging: Part 2 \[media file\]](http://download.microsoft.com/download/B/1/6/B161948D-EDE1-4AEF-8776-AD485CDDCD9E/TDDR05004.wvx) +- [Avoiding debugger searches for unneeded symbols](http://msdn.microsoft.com/en-US/library/windows/hardware/gg463239) +- [Debugging Kernel-Mode Driver Framework Drivers](http://msdn.microsoft.com/en-US/library/windows/hardware/gg463020) +- [Debugging WDF Drivers](https://msdn.microsoft.com/library/windows/hardware/ff540790) +- [How to Enable Verbose Debug Tracing in Various Drivers and Subsystems](http://support.microsoft.com/default.aspx?scid=kb;en-us;q314743) +- [Debugging a Driver](https://msdn.microsoft.com/windows-drivers/develop/debugging_a_driver) +- [**BCDEdit /dbgsettings**](https://msdn.microsoft.com/library/windows/hardware/ff542187) +- [Tools for Debugging Drivers](https://msdn.microsoft.com/library/windows/hardware/ff552951) (WDK Documentation) + +## Knowledge base articles for debugging + + +A number of [Knowledge Base articles](https://support.microsoft.com) are available for debugging related topics. This page provides a few examples of Product Support links that are relevant for debugging. + +- [2816225: Enabling Debug mode causes Windows to hang if no Debugger is connected](https://support.microsoft.com/kb/2816225/) +- [311503: Use the Microsoft Symbol Server to obtain debug symbol files](http://support.microsoft.com/kb/311503) +- [Q248413: INFO: NDIS Kernel Debugger Extensions](http://support.microsoft.com/kb/248413) +- [Q121366: INFO: PDB and DBG Files - What They Are and How They Work](http://support.microsoft.com/kb/121366) +- [Q121543: Setting Up for Remote Debugging](http://support.microsoft.com/kb/121543) +- [Q129845: Blue Screen Preparation Before Calling Microsoft](http://support.microsoft.com/kb/129845) +- [Q128372: How to Remove Symbols from Device Drivers](http://support.microsoft.com/kb/128372) +- [Q97858: CTRL+C Exception Handling Under WinDbg](http://support.microsoft.com/kb/97858) +- [Q102351: Debugging Console Apps Using Redirection](http://support.microsoft.com/kb/102351) +- [Q117559: INF: How to Correlate Spid, Kpid, and Thread Instance](http://support.microsoft.com/kb/117559) +- [Q121434: Specifying the Debugger for Unhandled User Mode Exceptions](http://support.microsoft.com/kb/121434) +- [Q133722: HOWTO: Debug Flat Thunks](http://support.microsoft.com/kb/133722) +- [Q148220: PRB: Debugger Reports "WARNING: symbols checksum is wrong"](http://support.microsoft.com/kb/148220) +- [Q137199: PRB: Debuggers Cannot Reliably Use Debug Register Breakpoints](http://support.microsoft.com/kb/137199) +- [Q100957: PRB: Debugging an Application Driven by MS-TEST](http://support.microsoft.com/kb/100957) +- [Q130667: PRB: F12 Causes Hard-Coded Breakpoint Exception When Debugging](http://support.microsoft.com/kb/130667) +- [Q173260: PRB: Synchronization Failure When Debugging](http://support.microsoft.com/kb/173260) +- [Q168609: How to Use Display Heap (DH.EXE) Utility](http://support.microsoft.com/kb/168609) +- [Q103861: INFO: Choosing the Debugger That the System Will Spawn](http://support.microsoft.com/kb/103861) + +## Related topics + + +[DebugView Monitoring Tool](http://technet.microsoft.com/sysinternals/bb896647.aspx) + +[Driver Developer Community Resources](http://msdn.microsoft.com/en-US/windows/hardware/gg454517) + +[Driver Signing Requirements for Windows](http://msdn.microsoft.com/en-US/library/windows/hardware/gg487317) + +[Support for Developer Kits and Tools](http://msdn.microsoft.com/en-US/windows/hardware/gg454528) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Resources%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-session-and-execution-model.md b/windows-driver-docs-pr/debugger/debugging-session-and-execution-model.md new file mode 100644 index 0000000000..b298c7508f --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-session-and-execution-model.md @@ -0,0 +1,46 @@ +--- +title: Debugging Session and Execution Model +description: Debugging Session and Execution Model +ms.assetid: 1cc2c055-447c-44cd-94d4-ae3dfa8243fb +keywords: ["Debugger Engine, execution model", "execution model", "Debugger Engine, debugging session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Session and Execution Model + + +The debugger engine can debug multiple targets, simultaneously. A *debugging session* begins when the engine acquires a target and continues until all of the targets have been discarded. A debugging session is *inaccessible* while the targets are executing and *accessible* when the current target is suspended. The engine can only be used to examine and manipulate targets while the session is accessible. + +The main loop of a debugger typically consists of setting the execution status, calling the method [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) and handling the generated [events](events.md#events). When **WaitForEvent** is called, the session becomes inaccessible. + +When an event occurs in a target, the engine suspends all targets and the session becomes accessible. The engine then notifies the event callbacks of the event and follows the event filter rules. The event callbacks and event filters determine how execution in the target should proceed. If they determine that the engine should break into the debugger, the **WaitForEvent** method returns and the session remains accessible; otherwise, the engine will resume execution of the target in the manner determined by the event callbacks and event filters, and the session becomes inaccessible again. + +For the duration of the **WaitForEvent** call--in particular, while notifying the event callbacks and processing the filter rules--the engine is in a state referred to as "inside a wait". While in this state, **WaitForEvent** cannot be called (it is not reentrant). + +There are two steps involved in initiating execution in a target: setting the execution status, and then calling **WaitForEvent**. The execution status can be set using the method [**SetExecutionStatus**](https://msdn.microsoft.com/library/windows/hardware/ff556693) or by executing a debugger command that sets the execution status--for example, **g(Go)** and **p (Step)**. + +If a sequence of debugger commands are executed together--for example, "**g ; ? @$ip**"--an *implicit wait* will occur after any command that requires execution in the target if that command is not the last command in the sequence. An implicit wait cannot occur when the debugger engine is in the state "inside a wait"; in this case, the execution of the commands will stop and the current command--the one that attempted to cause the implicit wait--will be interpreted as an indication of how execution in the target should proceed. The rest of the commands will be discarded. + +**Note**   When determining whether the session is accessible or inaccessible, limited execution of a target (for example, stepping) is considered execution by the engine. When the limited execution is complete, the session becomes accessible. + +  + +### Host Engine + +When debugging remotely, you can use multiple instances of the debugger engine. Exactly one of these instances maintains the debugging session; this instance is called the *host engine*. + +All debugger operations are relative to the host engine, for example, symbol loading and extension loading. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Session%20and%20Execution%20Model%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-targets-on-multiple-computers.md b/windows-driver-docs-pr/debugger/debugging-targets-on-multiple-computers.md new file mode 100644 index 0000000000..c6b984e63f --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-targets-on-multiple-computers.md @@ -0,0 +1,35 @@ +--- +title: Debugging Targets on Multiple Computers +description: Debugging Targets on Multiple Computers +ms.assetid: 3c4fa2d9-1443-4460-b570-9415a3600393 +keywords: ["multiple computer debugging", "system, targets on multiple computers", "remote debugging, multiple computers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Targets on Multiple Computers + + +## + + +The debugger can debug multiple dump files or live user-mode applications at the same time. See [Debugging Multiple Targets](debugging-multiple-targets.md) for details. + +You can debug multiple live targets even if the processes are on different systems. Simply start a process server on each system, and then use the **-premote** parameter with [**.attach (Attach to Process)**](-attach--attach-to-process-.md) or [**.create (Create Process)**](-create--create-process-.md) to identify the proper process server. + +The *current* or *active* system is the system currently being debugged. If you use the **.attach** or **.create** command again without specifying the **-premote** parameter, the debugger will attach to, or create, a process on the current system. + +For details on how to control such a debugging session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Targets%20on%20Multiple%20Computers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-techniques.md b/windows-driver-docs-pr/debugger/debugging-techniques.md new file mode 100644 index 0000000000..524f21487e --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-techniques.md @@ -0,0 +1,35 @@ +--- +title: Debugging Techniques +description: This section discusses two types of debugging techniques standard and specialized. +ms.assetid: 7de0283e-82fe-4443-bb11-e6378d2bb533 +keywords: ["debugging techniques"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Techniques + + +This section discusses two types of debugging techniques: standard and specialized. Standard techniques apply to most debugging scenarios, and examples include setting breakpoints, inspecting the call stack, and finding a memory leak. Specialized techniques apply to particular technologies or types of code, and examples are Plug and Play debugging, Kernel Mode Driver Framework debugging, and RPC debugging. + +## + + +You can learn more the following sections. + +[Standard Debugging Techniques](standard-debugging-techniques.md) + +[Specialized Debugging Techniques](specialized-debugging-techniques.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Techniques%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-the-service-application-automatically.md b/windows-driver-docs-pr/debugger/debugging-the-service-application-automatically.md new file mode 100644 index 0000000000..de522ca9fb --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-the-service-application-automatically.md @@ -0,0 +1,53 @@ +--- +title: Debugging the Service Application Automatically +description: Debugging the Service Application Automatically +ms.assetid: 3168b5c1-30fa-4ff5-b871-736dcdeb8f31 +--- + +# Debugging the Service Application Automatically + + +A debugger can be launched automatically when the service application starts up. Alternatively, it can be launched automatically when the service application encounters an exception or executes a **DebugBreak** command. If you have chosen one of these methods, this topic explains how to proceed. If you are not sure which method to choose, see [Choosing the Best Method](choosing-the-best-method.md). + +Then use the following procedure: + +1. Do one of the following preparatory steps: + - If you plan to debug the service application from the very beginning, including its initialization code, follow the procedure described in Enabling the Debugging of the Initialization Code. Alternatively, if you want the service application to break into the debugger when it crashes or encounters an exception, follow the procedure described in Enabling the Service Application to Break Into the Debugger. + - To assure that the service application will allow the debugger to run properly, perform the procedure described in [Adjusting the Service Application Timeout](preparing-to-debug-the-service-application.md#adjusting-the-service-application-timeout). + - If the service is combined with other services in a single SvcHost process, perform the procedure described in Isolating the Service. + +2. If the service is already running, you must restart it for these changes to take effect. We recommend that you restart Windows itself, in order to remove any effects of the running service. If you do not want to restart Windows, use the following commands, where *ServiceName* is the name of the service: + ``` + net stop ServiceName + net start ServiceName + ``` + +3. If you have chosen to debug the service application's initialization code, when the service starts, the debugger is launched and attaches to the service application. + + If you have chosen to let the debugger be triggered by an exception, the service application executes normally until it encounters an exception or executes a **DebugBreak** function. At this point, the debugger is launched and attaches to the service application. + +4. The next step depends on the debugger command line you specified during step 1: + - If you specified a debugger without any remoting options, this debugger is launched and its window becomes visible. + - If you specified NTSD with the -server and -noio options, NTSD is launched without a console window. You can then connect to the debugging session from another computer by starting any user-mode debugger with the -remote parameter. For instructions, see [**Activating a Debugging Client**](activating-a-debugging-client.md). + - If you specified NTSD with the -d option, NTSD is launched without a console window. You can then connect to the debugging session by using kernel debugger running on another computer. For instructions, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + - If you specified NTSD with the -ddefer and -server options, NTSD is launched without a console window. You can then connect to the debugging session by using both a kernel debugger and a user-mode remote debugger, running on a different computer than the service (but possibly the same computer as each other). For instructions, see [Combining This Method with Remote Debugging](combining-this-method-with-remote-debugging.md). + +5. When the debugger starts, the service pauses at the initial process breakpoint, the exception, or the **DebugBreak** command. This enables you to examine the current state of the service application, set breakpoints, and make any other desired configuration choices. + +6. Use [**g (Go)**](g--go-.md) or another execution command to resume the execution of the service application. + +## Related topics + + +[DebugBreak function](http://go.microsoft.com/fwlink/p/?linkid=124229) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20the%20Service%20Application%20Automatically%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-the-service-application-manually.md b/windows-driver-docs-pr/debugger/debugging-the-service-application-manually.md new file mode 100644 index 0000000000..910923addc --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-the-service-application-manually.md @@ -0,0 +1,42 @@ +--- +title: Debugging the Service Application Manually +description: Debugging the Service Application Manually +ms.assetid: 9be3976f-dd56-42f2-ac85-1c5a1f87a4ee +--- + +# Debugging the Service Application Manually + + +Manually attaching to a service application after it has been started is much like debugging any running user-mode process. + +Use [the TList tool](tlist.md) with the **/s** option to display the process ID (PID) of each running process and the services active in each process. + +If the service application you want to debug is combined with other services in a single process, you must isolate it before debugging it. To do this, perform the procedure described in Isolating the Service. At the end of this procedure, restart the service. + +To determine the new PID of the service, issue the following Service Configuration tool (Sc.exe) command, where *ServiceName* is the name of the service: + +``` +sc queryex ServiceName +``` + +Now start WinDbg or CDB with this service application as the target. There are three ways to do this: by specifying the PID with the -p option, by specifying the executable name with the -pn option (if the executable name is unique), or by specifying the service name with the -psn option. + +For example, if the process SpoolSv.exe has a PID of 651 and contains the service named *Spooler*, the following three commands are equivalent: + +``` +windbg -p 651 [AdditionalOptions] +windbg -pn spoolsv.exe [AdditionalOptions] +windbg -psn spooler [AdditionalOptions] +``` + +After the debugger starts, proceed as you would in any other user-mode debugging session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20the%20Service%20Application%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-10.md b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-10.md new file mode 100644 index 0000000000..7d04d120e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-10.md @@ -0,0 +1,68 @@ +--- +title: Debugging Tools for Windows New for Windows 10 +description: For Windows 10, Debugging Tools for Windows includes these new features. +ms.assetid: DCF1222F-6A67-463E-8C31-B7753CAFFC20 +--- + +# Debugging Tools for Windows: New for Windows 10 + + +For Windows 10, Debugging Tools for Windows includes these new features. + +## Windows 10, version 1703 + + +This section describes new debugging tools in Windows 10, version 1703. + +- Eight new JavaScript topics including [JavaScript Debugger Scripting](javascript-debugger-scripting.md) +- Updates to the [**dx (Display Debugger Object Model Expression)**](dx--display-visualizer-variables-.md) command, to include new command capabilities. +- New [**dtx (Display Type - Extended Debugger Object Model Information)**](dtx--display-type---extended-debugger-object-model-information-.md) command. +- New [**!ioctldecode**](-ioctldecode.md) command. +- Updated [Debugger Engine Reference](https://msdn.microsoft.com/library/windows/hardware/ff540540) to include additional interfaces and structures. +- Updates to [Configuring tools.ini](configuring-tools-ini.md) to document additional options for the command line debuggers. +- Published 75 previously undocumented stop codes in [Bug Check Code Reference](bug-check-code-reference2.md). +- New [Supported Ethernet NICs for Network Kernel Debugging in Windows 10](supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md) topic. + +## Windows 10, version 1607 + + +This section describes new debugging tools in Windows 10, version 1607. + +- New topic about [Debugging a UWP app using WinDbg](debugging-a-uwp-app-using-windbg.md). +- Updates to the 30 most-viewed developer bug check topics in [Bug Check Code Reference](bug-check-code-reference2.md). + +## Windows 10 + + +- [**.settings (Set Debug Settings)**](-settings--set-debug-settings-.md) - New command that allows you to set, modify, display, load and save settings in the Debugger.Settings namespace. +- [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) - Describes the new dx debugger command, which displays object information using the NatVis extension model and LINQ support. +- New commands that work with the NatVis visualization files in the debugger environment. + - [**.nvlist (NatVis List)**](-nvlist--natvis-list-.md) + - [**.nvload (NatVis Load)**](-nvload--natvis-load-.md) + - [**.nvunload (NatVis Unload)**](-nvunload--natvis-unload-.md) + - [**.nvunloadall (NatVis Unload All)**](-nvunloadall--natvis-unload-all-.md) +- [Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) +- [Storage Kernel Debugger Extensions](storage-kernel-debugger-extensions.md) +- New Symproxy information including [SymProxy Automated Installation](symproxy-automated-installation.md). In addition the following topics are updated to cover new SymProxy functionality: + - [HTTP Symbol Stores](http-symbol-stores.md) + - [SymProxy](symproxy.md) + - [Installing SymProxy](installing-symproxy.md) + - [Configuring the Registry](configuring-the-registry.md) + - [Configuring IIS for SymProxy](configuring-iis-for-symproxy.md) +- [**CDB Command-Line Options**](cdb-command-line-options.md) - Updated to include new command line options. +- [**!analyze**](-analyze.md) - Updated to include information about using this extension with UMDF 2.15. +- [**!wdfkd.wdfcrashdump**](-wdfkd-wdfcrashdump.md)- Updated to include information about using this extension with UMDF 2.15 +- [**!irp**](-irp.md) - Updated. Starting with Windows 10 the IRP major and minor code text is displayed in command output. +- [Using Debugger Markup Language](debugger-markup-language-commands.md) - Updated to describe new right click behavior available in the Debugger Markup Language (DML). +- [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md) - Performance has increased in taking a memory dump over KDNET. +- [Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md)- New step by step lab that shows how to use WinDbg to debug the sample KMDF echo driver. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20for%20Windows:%20New%20for%20Windows%2010%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8-1.md b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8-1.md new file mode 100644 index 0000000000..1d13c1734d --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8-1.md @@ -0,0 +1,31 @@ +--- +title: Debugging Tools for Windows New for Windows 8.1 +description: For Windows 8.1, Debugging Tools for Windows includes these new features. +ms.assetid: F2424842-88A7-4520-9C52-9574D049FB5F +--- + +# Debugging Tools for Windows: New for Windows 8.1 + + +For Windows 8.1, Debugging Tools for Windows includes these new features. + +- [GPIO Extensions](gpio-extensions.md) +- [HID Extensions](hid-extensions.md) +- Most of the [Kernel-Mode Driver Framework extension commands](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) now work with UMDF 2 as well as KMDF. Some commands (for example [**!wdfkd.wdfumdevstacks**](-wdfkd-wdfumdevstacks.md)) that specifically support UMDF 2 have been added to this set. +- Paging file can now be included in a CAB file along with a memory dump file. See [CAB Files that Contain Paging Files Along with a Memory Dump](cab-files-that-contain-paging-files-along-with-a-memory-dump.md) + +## Related topics + + +[Windows Debugging](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20for%20Windows:%20New%20for%20Windows%208.1%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8.md b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8.md new file mode 100644 index 0000000000..211b10796e --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--new-for-windows-8.md @@ -0,0 +1,40 @@ +--- +title: Debugging Tools for Windows New for Windows 8 +description: Debugging Tools for Windows New for Windows 8 +ms.assetid: 1AC2595A-800F-4F40-9C9D-61DE5398CBEB +--- + +# Debugging Tools for Windows: New for Windows 8 + + +Beginning with Windows 8, you can develop, build, and debug both kernel-mode and user-mode components all from Microsoft Visual Studio. There is added support for debugging over a network connection or a USB 3.0 connection and improved support for debugging optimized code and inline functions. For more information, see these topics: + +- [Debugging Using Visual Studio](debugging-using-visual-studio.md) +- [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md) +- [Setting Up a USB 3.0 Connection Manually](setting-up-a-usb-3-0-debug-cable-connection.md) +- [Debugging Optimized Code and Inline Functions](debugging-optimized-code-and-inline-functions-external.md) + +Two new sets of debugger extension commands are included: + +- [USB 3.0 Extensions](usb-3-extensions.md) +- [RCDRKD Extensions](rcdrkd-extensions.md) + +In addition to Visual Studio, you can sse the Windows debugger to debug Windows apps. The Debugging Tools for Windows package includes, [**PLMDebug.exe**](plmdebug.md), that enables you to take manual control of suspending, resuming, debugging, and terminating Windows app. + +Sos.dll is a component that is used for debugging managed code. The Windows 8 Debugging Tools for Windows package does not include sos.dll. For information about how to get sos.dll, see [Getting the SOS Debugging Extension (sos.dll)](debugging-managed-code.md#getting-the-sos-debugging-extension). + +## Related topics + + +[Windows Debugging](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20for%20Windows:%20New%20for%20Windows%208%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-tools-for-windows--what-s-new.md b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--what-s-new.md new file mode 100644 index 0000000000..d26a094c0a --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-tools-for-windows--what-s-new.md @@ -0,0 +1,30 @@ +--- +title: Debugging Tools For Windows What's New +description: Debugging Tools For Windows What's New +ms.assetid: 7F85412E-7A5D-4B1E-83B9-C32EDA7C6B49 +--- + +# Debugging Tools For Windows: What's New + + +## In this section + + +- [Debugging Tools for Windows: New for Windows 8.1](debugging-tools-for-windows--new-for-windows-8-1.md) +- [Debugging Tools for Windows: New for Windows 8](debugging-tools-for-windows--new-for-windows-8.md) + +## Related topics + + +[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20For%20Windows:%20What's%20New%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-tools-for-windows8-release-notes.md b/windows-driver-docs-pr/debugger/debugging-tools-for-windows8-release-notes.md new file mode 100644 index 0000000000..97b9f0e8fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-tools-for-windows8-release-notes.md @@ -0,0 +1,55 @@ +--- +title: Debugging Tools For Windows8 Release Notes +description: Debugging Tools For Windows8 Release Notes +ms.assetid: 15776778-691F-4F76-92CE-2DB266AD31E8 +--- + +# Debugging Tools For Windows8 Release Notes + + +## Channel number for 1394 debugging in Visual Studio + + +If you use Microsoft Visual Studio to perform kernel-mode debugging over a 1394 cable, set the channel to a decimal integer between 1 and 62 inclusive. Do not set the channel to 0 when you first set up debugging. Because the default channel value is 0, the software assumes there is no change and does not update the settings. If you must use channel 0, first use an alternate channel (1 through 62) and then switch to channel 0. + +## Inline function debugging is on by default + + +In Windows 8, debugging of inline functions is turned on by default. The command **.inline 0** turns off inline function debugging, and the command **.inline 1** turns on inline function debugging. + +## Invalid port number in configuration page for network debugging + + +**Issue:** If an invalid port number is entered in the configuration page for kernel-mode network debugging, the configuration succeeds but the debugger on the host computer cannot connect to the target computer. + +**Workaround:** Make sure the port number is valid. Valid port numbers range from 49152–65535. Also, your company might have restrictions on which ports can be used for network debugging. To ensure that a valid port number is entered, please check your internal IP Security Policy. + +## Use of .remote tool in command line + + +**Issue:** The use of **.remote** tool in the command line crashes the interface as it creates old style remote.exe using npipe. + +**Workaround:** Use the **.server** command instead. + +## Design features for Visual Studio + + +- Automatic provisioning of a machine includes both user mode and kernel mode bootstrapping, regardless of which one is chosen. This requires two restarts for provisioning and takes between 8–20 minutes. +- Support for attaching only one process at a time. +- During a debugging session in Windows Debugger Extension for Visual Studio, exceptions are managed using the command line. + +## Global design features + + +- User must run in an elevated context in order to install the USB 3.0 XHCI filter driver. If the user is not running elevated, the PnP manager returns an error message that does not inform the user that elevation is the problem. +- If kernel debugging is enabled, the device used for kernel debugging should not be removed from the system while the device is still turned on. If the device is removed, the system will hang and will need to be restarted. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20For%20Windows8%20Release%20Notes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-user-mode-processes-without-symbols.md b/windows-driver-docs-pr/debugger/debugging-user-mode-processes-without-symbols.md new file mode 100644 index 0000000000..1489b5b479 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-user-mode-processes-without-symbols.md @@ -0,0 +1,43 @@ +--- +title: Debugging User-Mode Processes Without Symbols +description: Debugging User-Mode Processes Without Symbols +ms.assetid: ac742239-ed6b-4813-80d6-7b8eb84a0cb4 +keywords: ["symbols, debugging without symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging User-Mode Processes Without Symbols + + +## + + +It is important to have symbols on the faulting machine before starting the debugger for a user-mode failure. However, sometimes the debugger is started without symbols. If the problem is easily reproducible, you can just copy symbols and rerun. If, however, the problem may not occur again, some information can still be gleaned from the failure: + +1. To figure out what the addresses mean, you'll need a computer which matches the one with the error. It should have the same platform (x86 or x64) and be loaded with the same version of Windows. + +2. When you have the computer configured, copy the user-mode symbols and the binaries you want to debug onto the new machine. + +3. Start CDB or WinDbg on the symbol-less machine. + +4. If you don't know which application failed on the symbol-less machine, issue an [**| (Process Status)**](---process-status-.md) command. If that doesn't give you a name, break into KD on the symbol-less machine and do a [**!process 0 0**](-process.md), looking for the process ID given by the CDB command. + +5. When you have the two debuggers set up -- one with symbols which hasn't hit the error, and one which has hit the error but is without symbols -- issue a [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command on the symbol-less machine. + +6. On the machine with symbols, issue a [**u (Unassemble)**](u--unassemble-.md) command for each address given on the symbol-less stack. This will give you the stack trace for the error on the symbol-less machine. + +7. By looking at a stack trace you can see the module and function names involved in the call. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20User-Mode%20Processes%20Without%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-using-cdb-and-ntsd.md b/windows-driver-docs-pr/debugger/debugging-using-cdb-and-ntsd.md new file mode 100644 index 0000000000..bd1e5789e9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-using-cdb-and-ntsd.md @@ -0,0 +1,44 @@ +--- +title: Debugging Using CDB and NTSD +description: This section describes how to perform basic debugging tasks using the Microsoft Console Debugger (CDB) and Microsoft NT Symbolic Debugger (NTSD). +ms.assetid: 770D8A69-9B0C-4745-B7E8-D461760C851B +--- + +# Debugging Using CDB and NTSD + + +This section describes how to perform basic debugging tasks using the Microsoft Console Debugger (CDB) and Microsoft NT Symbolic Debugger (NTSD). + +CDB and NTSD are identical in every way, except that NTSD spawns a new text window when it is started, whereas CDB inherits the Command Prompt window from which it was invoked. The instructions in this section are given for CDB, but they work equally well for NTSD. For a discussion of when to use CDB or NTSD, see [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md). + +Details are given in the following topics: + +- [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md) + +- [Opening a Dump File Using CDB](opening-a-crash-dump-file-using-cdb.md) + +- [Ending a Debugging Session in CDB](ending-a-debugging-session-in-cdb.md) + +- [Setting Symbol and Executable Image Paths in CDB](setting-symbol-and-source-paths-in-cdb.md) + +- [Setting Breakpoints in CDB](setting-breakpoints-in-cdb.md) + +- [Viewing the Call Stack in CDB](viewing-the-call-stack-in-cdb.md) + +- [Viewing and Editing Memory in CDB](viewing-memory--variables--and-registers-in-cdb.md) + +- [Viewing and Editing Registers in CDB](viewing-and-editing-registers-in-cdb.md) + +- [Configuring Exceptions and Events in CDB](configuring-exceptions-and-events-in-cdb.md) + +- [Keeping a Log File in CDB](keeping-a-log-file-in-cdb.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20CDB%20and%20NTSD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-using-kd-and-ntkd.md b/windows-driver-docs-pr/debugger/debugging-using-kd-and-ntkd.md new file mode 100644 index 0000000000..1b5249bfd8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-using-kd-and-ntkd.md @@ -0,0 +1,46 @@ +--- +title: Debugging Using KD and NTKD +description: This section describes how to perform basic debugging tasks using the KD and NTKD debuggers. +ms.assetid: 625BE34B-5A3C-4E22-BC2F-5375601E629A +--- + +# Debugging Using KD and NTKD + + +This section describes how to perform basic debugging tasks using the KD and NTKD debuggers. + +KD and NTKD are identical in every way, except that NTKD spawns a new text window when it is started, whereas KD inherits the Command Prompt window from which it was invoked. The instructions in this section are given for KD, but they work equally well for NTKD. For a discussion of when to use KD or NTKD, see [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md). + +Details are given in the following topics: + +- [Opening a Dump File Using KD](opening-a-crash-dump-file-using-kd.md) + +- [Live Kernel-Mode Debugging Using KD](performing-kernel-mode-debugging-using-kd.md) + +- [Ending a Debugging Session in KD](ending-a-debugging-session-in-kd.md) + +- [Setting Symbol and Executable Image Paths in KD](setting-symbol-and-source-paths-in-kd.md) + +- [Setting Breakpoints in KD](setting-breakpoints-in-kd.md) + +- [Viewing the Call Stack in KD](viewing-the-call-stack-in-kd.md) + +- [Viewing and Editing Memory in KD](viewing-memory--variables--and-registers-in-kd.md) + +- [Viewing and Editing Registers in KD](viewing-and-editing-registers-in-kd.md) + +- [Remote Debugging Using KD](remote-debugging-using-kd.md) + +- [Configuring Exceptions and Events in KD](configuring-exceptions-and-events-in-kd.md) + +- [Keeping a Log File in KD](keeping-a-log-file-in-kd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20KD%20and%20NTKD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-using-visual-studio.md b/windows-driver-docs-pr/debugger/debugging-using-visual-studio.md new file mode 100644 index 0000000000..e304bd78d7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-using-visual-studio.md @@ -0,0 +1,50 @@ +--- +title: Debugging Using Visual Studio +description: Starting with Windows Driver Kit (WDK) 8, the driver development environment and the Windows debuggers are integrated into Microsoft Visual Studio. +ms.assetid: B961B0C9-FF6C-4F6B-AC15-CA1B405A4C4C +--- + +# Debugging Using Visual Studio + + +Starting with Windows Driver Kit (WDK) 8, the driver development environment and the Windows debuggers are integrated into Microsoft Visual Studio. In this integrated environment, most of the tools you need for coding, building, packaging, testing, debugging, and deploying a driver are available in the Visual Studio user interface. + +To get the integrated envrionment, first install Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=391063). + +**Important**  This feature is not available in Windows 10, version 1507 and later versions of the WDK. + +  + +Typically kernel-mode debugging requires two computers. The debugger runs on the *host computer*, and the code being debugged runs on the *target computer*. The target computer is also called the *test computer*. You can do user-mode debugging on a single computer, but in some cases you might want to debug a user-mode process that is running on a separate target computer. + +In the Visual Studio environment, you can configure target computers for kernel-mode and user-mode debugging. You can establish a kernel-mode debugging session. You can attach to a user-mode process or launch and debug a user mode process on the host computer or a target computer. You can analyze dump files. In Visual Studio you can sign, deploy, install, and load a driver on a target computer. + +These topics show you how to use Visual Studio to perform several of the tasks involved in debugging a driver. + +## In this section + + +- [Debugging a User-Mode Process Using Visual Studio](debugging-a-user-mode-process-using-visual-studio.md) +- [Opening a Dump File Using Visual Studio](opening-a-crash-dump-file-using-visual-studio.md) +- [Kernel-Mode Debugging in Visual Studio](performing-kernel-mode-debugging-using-visual-studio.md) +- [Ending a Debugging Session in Visual Studio](ending-a-debugging-session-in-visual-studio.md) +- [Setting Symbol and Executable Image Paths in Visual Studio](setting-symbol-and-source-paths-in-visual-studio.md) +- [Remote Debugging Using Visual Studio](remote-debugging-using-visual-studio.md) +- [Entering Debugger Commands in Visual Studio](entering-debugger-commands-in-visual-studio.md) +- [Setting Breakpoints in Visual Studio](setting-breakpoints-in-visual-studio.md) +- [Viewing the Call Stack in Visual Studio](viewing-the-call-stack-in-visual-studio.md) +- [Source Code Debugging in Visual Studio](viewing-source-and-assembly-code-in-visual-studio.md) +- [Viewing and Editing Memory and Registers in Visual Studio](viewing-memory--variables--and-registers-in-visual-studio.md) +- [Controlling Threads and Processes in Visual Studio](viewing-threads-and-processes-in-visual-studio.md) +- [Configuring Exceptions and Events in Visual Studio](configuring-exceptions-and-events-in-visual-studio.md) +- [Keeping a Log File in Visual Studio](keeping-a-log-file-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-using-windbg-preview.md b/windows-driver-docs-pr/debugger/debugging-using-windbg-preview.md new file mode 100644 index 0000000000..b5aea3ed0b --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-using-windbg-preview.md @@ -0,0 +1,126 @@ +--- +title: Debugging Using WinDbg Preview +description: This section describes how to perform basic debugging tasks using the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/17/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + + +# ![Small logo on windbg preview](images/windbgx-preview-logo.png) Debugging Using WinDbg Preview + +WinDbg Preview is a brand-new version of WinDbg with more modern visuals, faster windows, a full-fledged scripting experience, built with the extensible debugger data model front and center. WinDbg Preview is using the same underlying engine as WinDbg today, so all the commands, extensions, and workflows you're used to will still work as they did before. + +For information on what's new in the most recent release, see [WinDbg Preview - What's New](windbg-what-is-new-preview.md). + +For the latest news, tips, and tricks from the debugger dev team, refer to the debugger tools team blog. +[https://blogs.msdn.microsoft.com/windbg/](https://blogs.msdn.microsoft.com/windbg/) + + +Review these topics to install and configure WinDbg Preview. + +- [WinDbg Preview – Installation](windbg-install-preview.md) +- [WinDbg Preview – Command line startup options](windbg-command-line-preview.md) +- [WinDbg Preview – Settings and workspaces](windbg-setup-preview.md) +- [WinDbg Preview – Keyboard shortcuts](windbg-keyboard-shortcuts-preview.md) + +These topics describe how to get connected to the environment that you want to debug. + +- [WinDbg Preview – Start a user-mode session](windbg-user-mode-preview.md) +- [WinDbg Preview – Start a kernel mode session](windbg-kernel-mode-preview.md) + +These topics describe some common tasks, organized by the menu tabs. + +- [WinDbg Preview – File menu](windbg-file-preview.md) +- [WinDbg Preview – Home menu](windbg-home-preview.md) +- [WinDbg Preview – View menu](windbg-view-preview.md) +- [WinDbg Preview – Breakpoints](windbg-breakpoints-preview.md) +- [WinDbg Preview – Data model](windbg-data-model-preview.md) +- [WinDbg Preview – Scripting](windbg-scripting-preview.md) + + +## Providing feedback + +Your feedback will help guide WinDbg's development going forward. + +- If you have feedback such as a feature that you really want to see or a bug that makes something difficult, use the Feedback Hub. + +![Screen shot of feedback hub showing feedback options including the add new feedback button](images/windbgx-feedback.png) + + +## Major Features of WinDbg Preview + +Here's some of the most notable things that have changed or are new. + +![Main screen in debugger](images/windbgx-main-menu.png) + + +### General features +- **Easier Connection Setup and Recall** - The WinDbg Preview includes the ability to recall previous session configuration information. + +![Screen shot of main screen in debugger](images/windbgx-start-debugging-menu.png) + +- **Easy feedback channel** - Your feedback will guide the development effort going forward. For more information, see [Providing Feedback](#providing-feedback) +- **Dump file processor detection** -Auto-detects processor architecture for easier managed debugging. +- **Performance Improvements** Windows now load asynchronously and can be canceled - When you run another command, WinDbg Preview will stop the loading of your locals, watch, or other windows. + + +### Windowing improvements + +- **Disassembly Window Improvements** - The disassembly window is also improved, the highlight of the current instruction remains where it is when you scroll. +- **Memory window improvements** - The memory window has highlighting and improved scrolling. +- **Locals and watch data model visualization** - The locals and watch windows are both based off of the data model that is used by the dx command. This means the locals and watch windows will benefit from any NatVis or JavaScript extensions you have loaded, and can even support full LINQ queries, just like the dx command. +- **Logs** - This is a under the covers log of the WinDbg Preview internals. It can be viewed for troubleshooting or to monitor long running processes. + +For more information, see [WinDbg Preview - View menu](windbg-view-preview.md). + +![View menu in debugger](images/windbgx-view-menu.png) + +- **Command window** - Use the command window provides easy access to toggle DML and clear the debugger command window. All current debugger commands are compatible with and continue to work in WinDbg Preview. +- **Source window** - Use the source windows to work with source code files, the new source windows should look more similar to the source windows you're used to seeing in every other modern editor. + +### Enhanced breakpoint tracking + +- **Enable/Disable breakpoints** - The breakpoints window shows all your current breakpoints and provides easy access to enabling and disabling them. +- **Hit count** - The breakpoint window keeps a running total of each time the breakpoint is hit. + +For more information, see [Breakpoints](windbg-breakpoints-preview.md). + + +### Enhanced data model support + +- **Built in data model support** - WinDbg Preview is written with built in data model support and the data model is available through out the debugger. +- **Model window** - The model window gives you an expandable and browsable version of ‘dx’ and ‘dx -g’, letting you create powerful tables on-top of your NatVis, JavaScript, and LINQ queries. + +For more information, see [WinDbg Preview - Data model](windbg-data-model-preview.md). + +![Screen shot of data model menu in debugger](images/windbgx-data-model-menu.png) + + +### New Scripting development UI + +- **Script development UI** - There is now a purpose built scripting window to make developing JavaScript and NatVis scripts easier, with error highlighting and IntelliSense. + +For more information, see [WinDbg Preview - Scripting](windbg-scripting-preview.md). + +![Screen shot of scripting menu in debugger](images/windbgx-scripting-menu.png) + + +### Backwards compatibility + +Because the underling debugger engine is the same, all of the previous debugger commands and debugger extensions continue to work. + + +---  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-using-windbg.md b/windows-driver-docs-pr/debugger/debugging-using-windbg.md new file mode 100644 index 0000000000..aedeac5945 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-using-windbg.md @@ -0,0 +1,62 @@ +--- +title: Debugging Using WinDbg +description: This section describes how to perform basic debugging tasks using the WinDbg debugger. +ms.assetid: 6738E3B9-FD79-4720-A8A8-8FA8EE1BA256 +--- + +# Debugging Using WinDbg + + +This section describes how to perform basic debugging tasks using the WinDbg debugger. + +Details are given in the following topics: + +- [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md) + +- [Debugging a UWP app using WinDbg](debugging-a-uwp-app-using-windbg.md) + +- [Opening a Dump File Using WinDbg](opening-a-crash-dump-file-using-windbg.md) + +- [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md) + +- [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) + +- [Setting Symbol and Executable Image Paths in WinDbg](setting-symbol-and-source-paths-in-windbg.md) + +- [Remote Debugging Using WinDbg](remode-debugging-using-windbg.md) + +- [Entering Debugger Commands in WinDbg](debugger-command-window.md) + +- [Using the Command Browser Window in WinDbg](command-browser-window.md) + +- [Setting Breakpoints in WinDbg](setting-breakpoints-in-windbg.md) + +- [Viewing the Call Stack in WinDbg](calls-window.md) + +- [Assembly Code Debugging in WinDbg](disassembly-window.md) + +- [Source Code Debugging in WinDbg](source-window.md) + +- [Viewing and Editing Memory in WinDbg](memory-window.md) + +- [Viewing and Editing Global Variables in WinDbg](viewing-and-editing-global-variables-in-windbg.md) + +- [Viewing and Editing Local Variables in WinDbg](locals-window.md) + +- [Viewing and Editing Registers in WinDbg](registers-window.md) + +- [Controlling Processes and Threads in WinDbg](processes-and-threads-window.md) + +- [Configuring Exceptions and Events in WinDbg](configuring-exceptions-and-events-in-windbg.md) + +- [Keeping a Log File in WinDbg](keeping-a-log-file-in-windbg.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-windows-setup-and-the-os-loader.md b/windows-driver-docs-pr/debugger/debugging-windows-setup-and-the-os-loader.md new file mode 100644 index 0000000000..9a232684e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-windows-setup-and-the-os-loader.md @@ -0,0 +1,32 @@ +--- +title: Debugging Windows Setup and the OS Loader +description: Debugging Windows Setup and the OS Loader +ms.assetid: 5195b1c5-2478-4faf-8f1e-ed5341d39ac4 +keywords: ["Windows setup debugging", "OS Loader debugging", "setup debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Windows Setup and the OS Loader + + +## Debugging During the Boot Sequence + + +For information about debugging a computer as it boots, see the following topics. + +- [**BCDEdit /bootdebug**](https://msdn.microsoft.com/library/windows/hardware/ff542183) +- [BCD Boot Options Reference](https://msdn.microsoft.com/library/windows/hardware/ff542205) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Windows%20Setup%20and%20the%20OS%20Loader%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-windows-store-apps-using-the-windows-debugger.md b/windows-driver-docs-pr/debugger/debugging-windows-store-apps-using-the-windows-debugger.md new file mode 100644 index 0000000000..6b9b3f30dc --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-windows-store-apps-using-the-windows-debugger.md @@ -0,0 +1,24 @@ +--- +title: Debugging Windows Apps Using the Windows Debugger +description: You can use the Windows debuggers (WinDbg, CDB, and NTSD) to debug Windows apps. Use the PLMDebug tool to take control of suspending, resuming, and terminating a Windows app while you are debugging. +ms.assetid: 87AA23A1-AB70-48CC-8F96-350C121F250E +--- + +# Debugging Windows Apps Using the Windows Debugger + + +You can use the Windows debuggers (WinDbg, CDB, and NTSD) to debug Windows apps. Use the [**PLMDebug**](plmdebug.md) tool to take control of suspending, resuming, and terminating a Windows app while you are debugging. + +To debug a managed-code Windows app, load the [SOS debugging extension (sos.dll)](http://go.microsoft.com/fwlink/p/?linkid=223345) and a data access component (mscordacwks.dll). For more information, see [Debugging Managed Code Using the Windows Debugger](debugging-managed-code.md). + +The windows debuggers are separate from the Visual Studio debugger. For information about the distinction between the windows debuggers and the Visual Studio debugger, see [Windows Debugging](index.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Windows%20Apps%20Using%20the%20Windows%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-windows-xp-and-windows-vista.md b/windows-driver-docs-pr/debugger/debugging-windows-xp-and-windows-vista.md new file mode 100644 index 0000000000..3e673ab388 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-windows-xp-and-windows-vista.md @@ -0,0 +1,40 @@ +--- +title: Debugging Windows XP and Windows Vista +description: To use WinDbg to debug Windows XP or Windows Vista, get the Windows 7 Debugging Tools for Windows package, which is included in the SDK for Windows 7. +ms.assetid: 1E4FC9D9-7F84-4F67-8FBC-4283C69AB0AC +--- + +# Debugging Windows XP and Windows Vista + + +To use WinDbg to debug Windows XP or Windows Vista, get the Windows 7 Debugging Tools for Windows package, which is included in the [Microsoft Windows Software Development Kit (SDK) for Windows 7 and .NET Framework 4.0](http://go.microsoft.com/fwlink/p/?LinkId=320327). + +If you want to download only Debugging Tools for Windows, install the SDK, and, during the installation, select the **Debugging Tools for Windows** box and clear all the other boxes. + +**Note**  You might have to uninstall Microsoft Visual C++ 2010 Redistributable components before you install the SDK. For more information, see [the Microsoft Support website](http://support.microsoft.com/kb/2717426). + +  + +## Debugging Tools (WinDbg, KD, CDB, NTSD) for Windows XP and Windows Vista + + +The Windows 7 Debugging Tools for Windows can run on x86-based or x64-based processors, and they can debug code that's running on x86-based or x64-based processors. Sometimes the debugger and the code being debugged run on the same computer, but other times the debugger and the code being debugged run on separate computers. In either case, the computer that's running the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. Use the Windows 7 Debugging Tools for Windows when the target computer is running one of these operating systems. + +| | | +|---------------|---------------------| +| Windows XP | Windows Server 2003 | +| Windows Vista | Windows Server 2008 | + +  + +If the target computer is running a more recent version of Windows, get the current [Debugging Tools for Windows](index.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Windows%20XP%20and%20Windows%20Vista%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-winlogon.md b/windows-driver-docs-pr/debugger/debugging-winlogon.md new file mode 100644 index 0000000000..2f62548106 --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-winlogon.md @@ -0,0 +1,57 @@ +--- +title: Debugging WinLogon +description: Debugging WinLogon +ms.assetid: 408727cd-fb59-44fe-b896-88317d2bc087 +keywords: ["WinLogon debugging", "NTSD, debugging CSRSS", "controlling the user-mode debugger from the kernel debugger, debugging WinLogon"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging WinLogon + + +## + + +WinLogon is the user-mode process that handles the task of interactive users logging on and logging off, and handles all instances of CTRL+ALT+DELETE. + +### Controlling NTSD from the Kernel Debugger + +The easiest way to debug WinLogon is to use NTSD and [control it from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +### Enabling WinLogon Debugging + +Because you will be redirecting the user-mode debugger output to the kernel debugger, you will need to set up a kernel debugging connection. See [Getting Set Up for Debugging](getting-set-up-for-debugging.md). + +To attach a debugger to WinLogon, you must go through the registry so the process is debugged from the time it starts up. To set up WinLogon debugging, set **HKEY\_LOCAL\_MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Image File Execution Options\\WinLogon.EXE\\Debugger** to: + +``` +ntsd -d -x -g +``` + +The **-d** option passes control to the kernel debugger. The **-x** option causes the debugger to capture access violations as second-chance exceptions. The **-g** option causes the WinLogon process to run after the attachment. Do not add the **-g** if you want to start debugging before Winlogon.exe begins (for example, if you want to set an initial breakpoint). + +In addition, you should set the GlobalFlag value under the **winlogon.exe** key to REG\_DWORD "0x000400F0". This sets heap checking and FLG\_ENABLE\_KDEBUG\_SYMBOL\_LOAD. However, since this second flag only affects the kernel debugger, symbols must also be copied to the target computer before starting the debugger. + +The registry change requires a reboot to take effect. + +### Performing the Debugging + +After the next reboot, the debugger will break into WinLogon automatically. + +See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for an explanation of how to proceed. + +You will have to set your symbol path to a location on your host computer or to some other location on your network. When WinLogon is being debugged, network authentication on the target computer will not work properly. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20WinLogon%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-with-floating-and-docked-windows.md b/windows-driver-docs-pr/debugger/debugging-with-floating-and-docked-windows.md new file mode 100644 index 0000000000..8720a1e34a --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-with-floating-and-docked-windows.md @@ -0,0 +1,49 @@ +--- +title: Debugging with Floating and Docked Windows +description: Debugging with Floating and Docked Windows +ms.assetid: 2b3e67de-576e-4cbb-bdf1-58a31cea733c +keywords: ["docking windows, debugging", "floating windows, debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging with Floating and Docked Windows + + +## + + +The features that are available in a debugging information window are not affected by whether the window is floating, docked, or docked in a tabbed collection. + +### Overview of the Window Configuration + +A floating window is not connected to the WinDbg window or any other dock. Floating windows always appear directly in front of the WinDbg window. + +A docked window occupies a fixed position within the WinDbg window or in a separate dock. + +When two or more docked windows are tabbed together, they occupy the same position within the frame. You can see only one of these tabbed windows at one time. At the bottom of each tabbed window collection is a set of tabs. The selected tab indicates which window in the collection is visible. + +### Making a Window Active + +You can make any window active, regardless of its position. When a floating window is active, it appears in the foreground. When a window that is inside an additional dock is active, that dock appears in the foreground. When a docked window within the WinDbg window is active, one or more floating windows might still obscure the docked window. + +To make a floating window or a docked window active, click its title bar. To make a docked window in a tabbed collection active, click its tab. + +You can also make a window active by using the WinDbg menu or toolbar. You can activate any window by clicking the window name at the bottom of the **Window** menu. You can also activate any window (other than a [Memory window](memory-window.md) or a [Source window](source-window.md)) by clicking its name on the **View** menu or clicking its toolbar button. + +Press CTRL+TAB to switch between debugging information windows. By pressing these keys repeatedly, you can scan through all of the windows, regardless of whether they are floating, docked by themselves, or part of a tabbed collection of docked windows. When you release the CTRL key, the window that you are currently viewing becomes active. + +The ALT+TAB shortcut keys are the standard Microsoft Windows shortcut keys to switch between the windows on the desktop. You can use these shortcut keys to switch between the WinDbg window and any additional docks that you have created. You can also make a dock active by clicking its button in the Windows taskbar. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20with%20Floating%20and%20Docked%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/debugging-with-visual-sourcesafe.md b/windows-driver-docs-pr/debugger/debugging-with-visual-sourcesafe.md new file mode 100644 index 0000000000..a64c1633aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/debugging-with-visual-sourcesafe.md @@ -0,0 +1,42 @@ +--- +title: Debugging with Visual SourceSafe +description: Debugging with Visual SourceSafe +ms.assetid: 65cc4eda-7aed-489f-a622-27a42afc0e4a +keywords: ["Visual SourceSafe, debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging with Visual SourceSafe + + +In order for source files indexed using Visual SourceSafe to work properly with the debugger, you must configure your system properly. + +If the Visual SourceSafe database requires a user and optional password for access, these values must be set using the SSUSER and SSPWD environment variables. Furthermore, the version of SrcSrv that ships with Visual Studio 2005 cannot detect whether Visual SourceSafe is prompting for credentials, which causes the application to stop responding.. Upgrade to the version of SrcSrv that ships with Debugging Tools for Windows to prevent this. + +If Visual SourceSafe is not set in the path of your debugging computer, you can get around this by adding an entry to the [Srcsrv.ini](the-srcsrv-ini-file.md) file that works with your debugger. When using a standard installation of Visual Studio, this file should be located in + +``` +%PROGRAMFILES%\Microsoft Visual Studio 8\Common7\IDE\srcsrv.ini +``` + +In the \[trusted commands\] section of Srcsrv.ini, add an entry of the form + +``` +ss.exe="Path" +``` + +where *Path* is the location of Ss.exe. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20with%20Visual%20SourceSafe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/deferred-symbol-loading.md b/windows-driver-docs-pr/debugger/deferred-symbol-loading.md new file mode 100644 index 0000000000..76831a5d1a --- /dev/null +++ b/windows-driver-docs-pr/debugger/deferred-symbol-loading.md @@ -0,0 +1,39 @@ +--- +title: Deferred Symbol Loading +description: Deferred Symbol Loading +ms.assetid: 58771089-dd0c-4ea9-8a9a-41553f290e88 +keywords: ["deferred symbol loading", "symbols, deferred symbol loading", "lazy symbol loading", "symbols, lazy symbol loading"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Deferred Symbol Loading + + +## + + +By default, symbol information is not actually loaded when the target modules are loaded. Instead, symbols are loaded by the debugger as they are needed. This is called *deferred symbol loading* or *lazy symbol loading*. When this option is enabled, the debugger loads symbols whenever it encounters an unrecognized symbol. + +When the symbol path is changed, for example by using the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command, all loaded modules with export symbols are lazily reloaded. Symbols of modules with full PDB symbols will be lazily reloaded if the new path no longer includes the original path that was used to load the PDB symbols. If the new path still includes the original path to the PDB symbol file, those symbols will not be lazily reloaded. + +When deferred symbol loading is disabled, process startup can be much slower, because all symbols are read whenever a module is loaded. + +In WinDbg, the deferred symbol loading behavior can be modified for symbols that have no module prefix by using the [Resolve Unqualified Symbols](debug---resolve-unqualified-symbols.md) option on the **Debug** menu. + +You can override deferred symbol loading by using the [**ld (Load Symbols)**](ld--load-symbols-.md) command or the [**.reload (Reload Module)**](-reload--reload-module-.md) command with the **/f** option. These force the specified symbols to be loaded immediately, although the loading of other symbols is deferred. + +By default, deferred symbol loading is enabled. In CDB and KD, the **-s** [command-line option](command-line-options.md) will turn this option off. It can also be turned off in CDB by using the *LazyLoad* variable in the [tools.ini](configuring-tools-ini.md) file. Once the debugger is running, this option can be turned on or off by using [**.symopt+0x4**](-symopt--set-symbol-options-.md) or **.symopt-0x4**, respectively. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Deferred%20Symbol%20Loading%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/detecting-overruns-and-underruns.md b/windows-driver-docs-pr/debugger/detecting-overruns-and-underruns.md new file mode 100644 index 0000000000..8fb04b2a5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/detecting-overruns-and-underruns.md @@ -0,0 +1,45 @@ +--- +title: Detecting Overruns and Underruns +description: Detecting Overruns and Underruns +ms.assetid: d7d282c8-adde-49fc-a20e-d633abd6dd3f +--- + +# Detecting Overruns and Underruns + + +## + + +You can use the **Verify Start** or **Verify End** option in GFlags to align allocations from the special pool so that they are best suited to detect overruns (accessing memory past the end of the allocation) or underruns (accessing memory that precedes the beginning of the allocation). + +- **Verify Start** enables underrun detection on allocations from the special pool. This causes a bug check when a program tries to access memory preceding its special pool memory allocation. + +- **Verify End** enables overrun detection on allocations from the special pool. This causes a bug check when a program tries to access memory beyond its special pool memory allocation. Because overruns are much more common, **Verify End** is the default. + +In Windows Vista and later versions of Windows, this option is available on the **System Registry** and **Kernel Flags** tabs. In earlier versions of Windows, it is available only on the **System Registry** tab. + +**To specify special pool alignment** + +1. Click the **System Registry** tab. + +2. Click **Verify Start** or **Verify End**. + +3. Click **Apply**. + + The following screen shot shows the Verify Start and Verify End settings on the System **Registry** tab. + + ![screen shot illustrating the verify start and verify end options on the system registry tab](images/gflags-overruns.png) + +### Comments + +The **Verify Start** and **Verify End** alignment settings apply to all allocations from the special pool, including special pool allocation requests set in Driver Verifier. If you set the alignment without specifying a pool tag or allocation size, then the settings apply only to requests set in Driver Verifier. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Detecting%20Overruns%20and%20Underruns%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/determining-if-a-debugger-is-attached.md b/windows-driver-docs-pr/debugger/determining-if-a-debugger-is-attached.md new file mode 100644 index 0000000000..9a777ee00d --- /dev/null +++ b/windows-driver-docs-pr/debugger/determining-if-a-debugger-is-attached.md @@ -0,0 +1,37 @@ +--- +title: Determining if a Debugger is Attached +description: Determining if a Debugger is Attached +ms.assetid: 78f7d90a-459c-4967-a980-3f8d6339eb77 +keywords: ["determining if a debugger is attached", "KdRefreshDebuggerNotPresent function", "KD_DEBUGGER_ENABLED global variable", "KD_DEBUGGER_NOT_PRESENT global variable"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining if a Debugger is Attached + + +## + + +Kernel-mode code can determine the status of kernel debugging by using the following variables and routines: + +- (Windows XP and later) The KD\_DEBUGGER\_ENABLED global kernel variable indicates whether kernel debugging is enabled. + +- (Windows XP and later) The KD\_DEBUGGER\_NOT\_PRESENT global kernel variable indicates whether a kernel debugger is currently attached. + +- (Windows Server 2003 and later) The **KdRefreshDebuggerNotPresent** routine refreshes the value of KD\_DEBUGGER\_NOT\_PRESENT. + +For complete documentation, see the Windows Driver Kit. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Determining%20if%20a%20Debugger%20is%20Attached%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/determining-the-acl-of-an-object.md b/windows-driver-docs-pr/debugger/determining-the-acl-of-an-object.md new file mode 100644 index 0000000000..b234c02982 --- /dev/null +++ b/windows-driver-docs-pr/debugger/determining-the-acl-of-an-object.md @@ -0,0 +1,93 @@ +--- +title: Determining the ACL of an Object +description: Determining the ACL of an Object +ms.assetid: 8dcd4f5a-1415-4a58-bfb1-fd3cbd58cc56 +keywords: ["access control list (ACL)", "ACL (access control list)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining the ACL of an Object + + +## + + +You can use the debugger to examine the access control list (ACL) of an object. + +The following method can be used if you are performing kernel debugging. To use it while you are performing user-mode debugging, you need to redirect control to a kernel debugger. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +First, use the [**!object**](-object.md) debugger extension with the name of the object in question: + +``` +kd> !object \BaseNamedObjects\AgentToWkssvcEvent +Object: ffbb8a98 Type: (80e30e70) Event + ObjectHeader: ffbb8a80 + HandleCount: 2 PointerCount: 3 + Directory Object: e14824a0 Name: AgentToWkssvcEvent +``` + +This shows that the object header has address 0xFFBB8A80. Use the [**dt (Display Type)**](dt--display-type-.md) command with this address and the **nt!\_OBJECT\_HEADER** structure name: + +``` +kd> dt nt!_OBJECT_HEADER ffbb8a80 + +0x000 PointerCount : 3 + +0x004 HandleCount : 2 + +0x004 NextToFree : 0x00000002 + +0x008 Type : 0x80e30e70 + +0x00c NameInfoOffset : 0x10 ' + +0x00d HandleInfoOffset : 0 ' + +0x00e QuotaInfoOffset : 0 ' + +0x00f Flags : 0x20 ' ' + +0x010 ObjectCreateInfo : 0x8016b460 + +0x010 QuotaBlockCharged : 0x8016b460 + +0x014 SecurityDescriptor : 0xe11f08b6 + +0x018 Body : _QUAD +``` + +The security descriptor pointer value is shown as 0xE11F08B6. The lowest 3 bits of this value represent an offset past the beginning of this structure, so you should ignore them. In other words, the SECURITY\_DESCRIPTOR structure actually begins at 0xE11F08B6 & ~0x7. Use the [**!sd**](-sd.md) extension on this address: + +``` +kd> !sd e11f08b0 +->Revision: 0x1 +->Sbz1 : 0x0 +->Control : 0x8004 + SE_DACL_PRESENT + SE_SELF_RELATIVE +->Owner : S-1-5-32-544 +->Group : S-1-5-18 +->Dacl : +->Dacl : ->AclRevision: 0x2 +->Dacl : ->Sbz1 : 0x0 +->Dacl : ->AclSize : 0x44 +->Dacl : ->AceCount : 0x2 +->Dacl : ->Sbz2 : 0x0 +->Dacl : ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +->Dacl : ->Ace[0]: ->AceFlags: 0x0 +->Dacl : ->Ace[0]: ->AceSize: 0x14 +->Dacl : ->Ace[0]: ->Mask : 0x001f0003 +->Dacl : ->Ace[0]: ->SID: S-1-5-18 + +->Dacl : ->Ace[1]: ->AceType: ACCESS_ALLOWED_ACE_TYPE +->Dacl : ->Ace[1]: ->AceFlags: 0x0 +->Dacl : ->Ace[1]: ->AceSize: 0x18 +->Dacl : ->Ace[1]: ->Mask : 0x00120001 +->Dacl : ->Ace[1]: ->SID: S-1-5-32-544 + +->Sacl : is NULL +``` + +This displays the security information for this object. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Determining%20the%20ACL%20of%20an%20Object%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/determining-the-cause-of-a-video-stream-stall.md b/windows-driver-docs-pr/debugger/determining-the-cause-of-a-video-stream-stall.md new file mode 100644 index 0000000000..398b7839f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/determining-the-cause-of-a-video-stream-stall.md @@ -0,0 +1,50 @@ +--- +title: Determining the Cause of a Video Stream Stall +description: Determining the Cause of a Video Stream Stall +ms.assetid: 959c2295-1ec3-48b0-aed9-93a81378372f +keywords: ["kernel streaming debugging, video stream stall, cause"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining the Cause of a Video Stream Stall + + +There are two basic causes for a video stream stall: + +- **A hang.** Either a user-mode thread or a kernel-mode thread is not being released by the driver. + +- **A stall.** This is the result of a problem with a component in the streaming path. Some possibilities include: + - The capture driver is not completing packets. In this case, either a driver component or the hardware might be the source of the stall. + - The capture driver has no packets to complete. In this case, the buffers might be stalled in a codec or other downstream component. + +If you can reproduce the problem, attach a debugger at this point to determine which is the actual cause. + +**To determine if the problem is a hang** + +1. Attach a user-mode debugger to the application and look for blocked user-mode threads. + +2. Determine whether the application is responsive. Can the graph be paused? Can the graph be stopped? Does streaming restart if the graph is stopped and restarted? + +3. If the application is non-responsive, attempt to end the task by using Task Manager. If this fails, there is a kernel-mode hang. + +**To determine if the problem is a stall** + +1. Determine where the samples are in the graph. This can be done locally or in a kernel-mode debugging session. + +2. Determine whether samples are flowing downstream. If you can reproduce the bug in [GraphEdit](http://go.microsoft.com/fwlink/p/?linkid=9230), place an intermediate filter in the graph to display samples. + +3. Determine if the processing routine is being called. This can be done by attaching a kernel-mode debugger and setting a breakpoint in this routine. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Determining%20the%20Cause%20of%20a%20Video%20Stream%20Stall%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/determining-the-status-of-a-device.md b/windows-driver-docs-pr/debugger/determining-the-status-of-a-device.md new file mode 100644 index 0000000000..277389a5e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/determining-the-status-of-a-device.md @@ -0,0 +1,165 @@ +--- +title: Determining the Status of a Device +description: Determining the Status of a Device +ms.assetid: d250643e-13cb-4657-9235-5fdeb1eab89a +keywords: ["Plug and Play (PnP), device status", "Plug and Play (PnP), device tree", "device status", "device tree"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining the Status of a Device + + +## + + +To display the entire device tree, starting with the root, use **!devnode 0 1**: + +``` +kd> !devnode 0 1 +``` + +Identify the devnode for which you are searching, either by examining the driver or the bus that exposed it. + +The devnode status flags describe the status of the device. For details, see [Device Node Status Flags](device-node-status-flags.md). + +In the example for the **!devnode** command in the [Extensions for Debugging Plug and Play Drivers](extensions-for-debugging-plug-and-play-drivers.md) section, the swenum device was created by the PnP Manager, so the DNF\_MADEUP (0x00000001) flag is set. + +The following example shows a device that was created by the PCI bus. This device does not have the DNF\_MADEUP flag set. + +``` +0: kd> !devnode 0xfffffa8004483490 +DevNode 0xfffffa8004483490 for PDO 0xfffffa800448d060 + Parent 0xfffffa80036766d0 Sibling 0xfffffa8004482010 Child 0xfffffa80058ad720 + InstancePath is "PCI\VEN_8086&DEV_293C&SUBSYS_2819103C&REV_02\3&21436425&0&D7" + ServiceName is "usbehci" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[09] = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[08] = DeviceNodeEnumeratePending (0x30c) + StateHistory[07] = DeviceNodeStarted (0x308) + StateHistory[06] = DeviceNodeStartPostWork (0x307) + ... + Flags (0x6c0000f0) DNF_ENUMERATED, DNF_IDS_QUERIED, + DNF_HAS_BOOT_CONFIG, DNF_BOOT_CONFIG_RESERVED, + DNF_NO_LOWER_DEVICE_FILTERS, DNF_NO_LOWER_CLASS_FILTERS, + DNF_NO_UPPER_DEVICE_FILTERS, DNF_NO_UPPER_CLASS_FILTERS + CapabilityFlags (0x00002000) WakeFromD3 +``` + +**Examples** + +1. A devnode for a device with insufficient resources: + +``` +kd> !devnode 0xff0d06e8 6 + +DevNode 0xff0d06e8 for PDO 0xff0d07d0 at level 0x3 + Parent 0xff0d1408 Sibling 0000000000 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xfffffff0 + InstancePath is "ISAPNP\SUP2171\00000067" + ServiceName is "Modem" + TargetDeviceNotify List - f 0xff0d074c b 0xff0d074c + Flags (..........) DNF_PROCESSED, DNF_ENUMERATED, + DNF_INSUFFICIENT_RESOURCES, DNF_ADDED, + DNF_HAS_BOOT_CONFIG + Unknown flags 0x40000000 + + IoResList at 0xe133e7a8 : Interface 0x1 Bus 0 Slot 0 + Alternative 0 (Version 1.1) + Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Shared (0x3) + Flags (0000) - + Data: : 0x0 0x61004d 0x680063 + Preferred Descriptor 1 - Port (0x1) Undetermined Sharing (0) + Flags (0x11) - PORT_IO 16_BIT_DECODE + 0x000008 byte range with alignment 0x000001 + 2f8 - 0x2ff + Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3) + Flags (0x01) - LATCHED + 0x3 - 0x3 +``` + +Note that the devnode has no CM Resource List, because it is not started and is not using resources, although it has requested resources. + +2. Note that there are no resources stored in this devnode for a legacy driver. + +``` +kd> !devnode 0xff0d1648 6 + +DevNode 0xff0d1648 for PDO 0xff0d22d0 at level 0x2 + Parent 0xff0d2e28 Sibling 0xff0d1588 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + InstancePath is "PCI\VEN_102B&DEV_0519\0&60" + ServiceName is "mga_mil" + TargetDeviceNotify List - f 0xff0d16ac b 0xff0d16ac + Flags (0x6000500b) DNF_PROCESSED, DNF_STARTED, + DNF_ENUMERATED, DNF_ADDED, + DNF_LEGACY_DRIVER, DNF_HAS_BOOT_CONFIG + Unknown flags 0x40000000 +``` + +You can retrieve the device object list for the driver for the following types of devices: + +``` +kd> !drvobj mga_mil + +Driver object (ff0bbc10) is for: + \Driver\mga_mil +Driver Extension List: (id , addr) + +Device Object list: +ff0bb900 +``` + +You can then dump the data for this device object: + +``` +kd> !devobj ff0bb900 + +Device object (ff0bb900) is for: + Video0 \Driver\mga_mil DriverObject ff0bbc10 +Current Irp 00000000 RefCount 1 Type 00000023 Flags 0000204c +DevExt ff0bb9b8 DevNode ff0bb808 +Device queue is not busy. +``` + +Finally, you can dump the devnode referred by the device object. This devnode is not linked in the device tree. It represents a "pseudo-devnode" used to claim resources for the legacy device. Note the DNF\_RESOURCE\_REPORTED flag that indicates the device is a reported detected device. + +``` +kd> !devnode ff0bb808 6 + +DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff + Parent 0xff0daf48 Sibling 0000000000 Child 0000000000 + InterfaceType 0xffffffff Bus Number 0xffffffff + TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c + Flags (0x00000400) DNF_RESOURCE_REPORTED + CmResourceList at 0xe12474e8 Version 0.0 Interface 0x5 Bus #0 + Entry 0 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3c0 for 0x10 bytes + Entry 1 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3d4 for 0x8 bytes + Entry 2 - Port (0x1) Shared (0x3) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3de for 0x2 bytes + Entry 3 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + Range starts at 0x0000000040000000 for 0x4000 bytes + Entry 4 - Memory (0x3) Device Exclusive (0x1) + Flags (0000) - READ_WRITE + Range starts at 0x0000000040800000 for 0x800000 bytes +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Determining%20the%20Status%20of%20a%20Device%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/determining-whether-a-leak-exists.md b/windows-driver-docs-pr/debugger/determining-whether-a-leak-exists.md new file mode 100644 index 0000000000..d11221bbc6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/determining-whether-a-leak-exists.md @@ -0,0 +1,42 @@ +--- +title: Determining Whether a Leak Exists +description: Determining Whether a Leak Exists +ms.assetid: a29db56e-6507-48f4-ad30-eb0a849f8673 +keywords: ["memory leak, detection"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining Whether a Leak Exists + + +If Windows performance is degrading over time and you suspect that a memory leak may be involved, the technique described in this section can indicate whether there is a memory leak. It will not tell you what the source of the leak is, nor whether it is user mode or kernel mode. + +Begin by launching Performance Monitor. Add the following counters: + +- **Memory**-->**Pool Nonpaged Bytes** + +- **Memory**-->**Pool Paged Bytes** + +- **Paging File**-->**% Usage** + +Change the update time to 600 seconds to capture a graph of the leak over time. You might also want to log the data to a file for later examination. + +Start the application or test that you believe is causing the leak. Allow the application or test to run undisturbed for some time; do not use the target computer during this time. Leaks are usually slow and may take hours to detect. Wait for a few hours before deciding whether a leak has occurred. + +Monitor the Performance Monitor counters. After the test has started, the counter values will change rapidly, and it may take some time for the memory pools values to reach a steady state. + +User-mode memory leaks are always located in pageable pool and cause both the **Pool Paged Bytes** counter and the page file **Usage** counter to increase steadily over time. Kernel-mode memory leaks usually deplete nonpaged pool, causing the **Pool Nonpaged Bytes** counter to increase, although pageable memory can be affected as well. Occasionally these counters may show false positives because an application is caching data. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Determining%20Whether%20a%20Leak%20Exists%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/device-manager-problem-codes.md b/windows-driver-docs-pr/debugger/device-manager-problem-codes.md new file mode 100644 index 0000000000..af82575e07 --- /dev/null +++ b/windows-driver-docs-pr/debugger/device-manager-problem-codes.md @@ -0,0 +1,53 @@ +--- +title: Device Manager Problem Codes +description: Device Manager Problem Codes +ms.assetid: d08c3dd1-ab2e-4ce6-8bf7-9634c0a5be1f +keywords: ["Plug and Play (PnP), device manager problem codes", "device manager problem codes", "CM_PROB_XXX"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Manager Problem Codes + + +The Device Manager marks a device with a yellow exclamation mark (!) when the device has a problem. The problem codes are in the form CM\_PROB\_*XXX* and are defined in the header file cfg.h. The most important are explained here, together with their mapping to the [Device Node Status Flags](device-node-status-flags.md). For a more comprehensive list, please see [Device Manager Error Messages](../install/device-manager-error-messages.md). + +**Code 1 (CM\_PROB\_NOT\_CONFIGURED)** +Indicates that the device is not installed and was not installed previously. (Corresponds to DNF\_NOT\_CONFIGURED.) + +**Code 10 (CM\_PROB\_FAILED\_START)** +Indicates that the device did not start for some reason, but the I/O Manager attempted to start it with a set of resources. (Corresponds to DNF\_START\_FAILED.) + +**Code 12 (CM\_PROB\_NORMAL\_CONFLICT)** +Indicates that there were not sufficient resources to start this device. (Corresponds to DNF\_INSUFFICIENT\_RESOURCES.) + +**Code 14 (CM\_PROB\_NEED\_RESTART)** +Indicates that user mode reconfigured the device and a reboot is required for the changes to take effect. (Corresponds to DNF\_NEED\_RESTART.) + +**Code 18 (CM\_PROB\_REINSTALL)** +Indicates that the device needs to be installed and was installed previously. (Corresponds to DNF\_REINSTALL.) + +**Code 21 (CM\_PROB\_WILL\_BE\_REMOVED)** +Indicates that the user mode uninstalled this device. (Corresponds to DNF\_WILL\_BE\_REMOVED.) + +**Code 22 (CM\_PROB\_DISABLED)** +Indicates that the device is disabled. (Corresponds to DNF\_DISABLED.) + +**Code 28 (CM\_PROB\_FAILED\_INSTALL)** +Indicates that the installation failed and there is no driver selected for this device, although the kernel did not report a problem (and there is no DNF\_XXX match for this the problem). This problem can be the result of an on-board system device (ISA timer, ISA RTC, RAM Memory, and so forth) that does not yet have an INF file. + +**Code 31 (CM\_FAILED\_ADD)** +Indicates that the device was not added. Reasons for the failure may include: a driver's **AddDevice** routine returned an error, there is no service listed for the device in the registry, there is more than one service listed, or the controlling driver could not be loaded. (Corresponds to DNF\_ADD\_FAILED.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Device%20Manager%20Problem%20Codes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/device-node-and-stack-debugger-commands.md b/windows-driver-docs-pr/debugger/device-node-and-stack-debugger-commands.md new file mode 100644 index 0000000000..15356ccd26 --- /dev/null +++ b/windows-driver-docs-pr/debugger/device-node-and-stack-debugger-commands.md @@ -0,0 +1,31 @@ +--- +title: Debugging Device Nodes and Device Stacks +description: You can use the following commands for debugging device nodes and device stacks. +ms.assetid: 5CD48647-2DDD-4592-B8AD-D5508A6C11C6 +keywords: ["device node", "device stack", "driver stack", "device object", "driver object"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Device Nodes and Device Stacks + + +You can use the following commands for debugging device nodes and device stacks. + +- [**!devnode**](-devnode.md) +- [**!devstack**](-devstack.md) +- [**!devobj**](-devobj.md) +- [**!drvobj**](-drvobj.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Device%20Nodes%20and%20Device%20Stacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/device-node-status-flags.md b/windows-driver-docs-pr/debugger/device-node-status-flags.md new file mode 100644 index 0000000000..dadb0eb8da --- /dev/null +++ b/windows-driver-docs-pr/debugger/device-node-status-flags.md @@ -0,0 +1,127 @@ +--- +title: Device Node Status Flags +description: Device Node Status Flags +ms.assetid: 64f4548f-ace3-440c-8a36-97bd46cfa986 +keywords: ["Plug and Play (PnP), Device Node Status Flags", "Device Node Status Flags", "DNF_XXX"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Node Status Flags + + +## + + +The Device Node Status flags describe the status of a device. + +The most important flags are: + +**DNF\_MADEUP (0x00000001)** +The device was created and is owned by the PnP Manager. It was not created by a bus driver. + +**DNF\_DUPLICATE (0x00000002)** +The device node is a duplicate of another enumerated device node. + +**DNF\_HAL\_NODE (0x00000004)** +The device node is the root node created by the hardware abstraction layer (HAL). + +**DNF\_REENUMERATE (0x00000008)** +The device needs to be re-enumerated. + +**DNF\_ENUMERATED (0x00000010)** +The PDO for the device was exposed by its parent. + +**DNF\_IDS\_QUERIED (0x00000020)** +The operating system should send IRP\_MN\_QUERY\_ID requests to the device driver. + +**DNF\_HAS\_BOOT\_CONFIG (0x00000040)** +The device has resources assigned by the BIOS. The device is considered pseudo-started and needs to participate in rebalancing. + +**DNF\_BOOT\_CONFIG\_RESERVED (0x00000080)** +The boot resources of the device are reserved. + +**DNF\_NO\_RESOURCE\_REQUIRED (0x00000100)** +The device does not require resources. + +**DNF\_RESOURCE\_REQUIREMENTS\_NEED\_FILTERED (0x00000200)** +The device's resource requirements list is a filtered list. + +**DNF\_RESOURCE\_REQUIREMENTS\_CHANGED (0x00000400)** +The device's resource requirements list has changed. + +**DNF\_NON\_STOPPED\_REBALANCE (0x00000800)** +The device can be restarted with new resources without being stopped. + +**DNF\_LEGACY\_DRIVER (0x00001000)** +The device's controlling driver is a non-PnP driver. + +**DNF\_HAS\_PROBLEM (0x00002000)** +The device has a problem and will be removed. + +**DNF\_HAS\_PRIVATE\_PROBLEM (0x00004000)** +The device reported PNP\_DEVICE\_FAILED without also reporting PNP\_DEVICE\_RESOURCE\_REQUIREMENTS\_CHANGED. + +**DNF\_HARDWARE\_VERIFICATION (0x00008000)** +The device node has hardware verification. + +**DNF\_DEVICE\_GONE (0x00010000)** +The device's PDO is no longer returned in an IRP\_QUERY\_RELATIONS request. + +**DNF\_LEGACY\_RESOURCE\_DEVICENODE (0x00020000)** +The device node was created for legacy resource allocation. + +**DNF\_NEEDS\_REBALANCE (0x00040000)** +The device node has triggered rebalancing. + +**DNF\_LOCKED\_FOR\_EJECT (0x00080000)** +The device is being ejected or is related to a device that is being ejected. + +**DNF\_DRIVER\_BLOCKED (0x00100000)** +One or more of the drivers for the device node have been blocked from loading. + +**DNF\_CHILD\_WITH\_INVALID\_ID (0x00200000)** +One or more children of the device node have invalid IDs. + +**DNF\_ASYNC\_START\_NOT\_SUPPORTED (0x00400000)** +The device does not support asynchronous starts. + +**DNF\_ASYNC\_ENUMERATION\_NOT\_SUPPORTED (0x00800000)** +The device does not support asynchronous enumeration. + +**DNF\_LOCKED\_FOR\_REBALANCE (0x01000000)** +The device is locked for rebalancing. + +**DNF\_UNINSTALLED (0x02000000)** +An IRP\_MN\_QUERY\_REMOVE\_DEVICE request is in progress for the device. + +**DNF\_NO\_LOWER\_DEVICE\_FILTERS (0x04000000)** +There is no Registry entry of the lower-device-filters type for the device. + +**DNF\_NO\_LOWER\_CLASS\_FILTERS (0x08000000)** +There is no Registry entry of the lower-class-filters type for the device. + +**DNF\_NO\_SERVICE (0x10000000)** +There is no Registry entry of the service the for the device. + +**DNF\_NO\_UPPER\_DEVICE\_FILTERS (0x20000000)** +There is no Registry entry of the upper-device-filters type for the device. + +**DNF\_NO\_UPPER\_CLASS\_FILTERS (0x40000000)** +There is no Registry entry of the upper-class-filters type for the device. + +**DNF\_WAITING\_FOR\_FDO (0x80000000)** +Enumeration of the device is waiting until the driver attaches its FDO. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Device%20Node%20Status%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dg--display-selector-.md b/windows-driver-docs-pr/debugger/dg--display-selector-.md new file mode 100644 index 0000000000..7388ac79fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/dg--display-selector-.md @@ -0,0 +1,156 @@ +--- +title: dg (Display Selector) +description: The dg command shows the segment descriptor for the specified selector. +ms.assetid: bf680931-f4f9-4b72-bb25-42d095514d2a +keywords: ["dg (Display Selector) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dg (Display Selector) +api_type: +- NA +--- + +# dg (Display Selector) + + +The **dg** command shows the segment descriptor for the specified selector. + +``` +dg FirstSelector [LastSelector] +``` + +## Parameters + + + *FirstSelector* +Specifies the hexadecimal selector value of the first selector to be displayed. + + *LastSelector* +Specifies the hexadecimal selector value of the last selector to be displayed. If this is omitted, only one selector will be displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

x86, Itanium

+ +  + +Remarks +------- + +No more than 256 selectors can be displayed by this command. + +Common selector values are: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Iddecimalhex

KGDT_NULL

0

0x00

KGDT_R0_CODE

8

0x08

KGDT_R0_DATA

16

0x10

KGDT_R3_CODE

24

0x18

KGDT_R3_DATA

32

0x20

KGDT_TSS

40

0x28

KGDT_R0_PCR

48

0x30

KGDT_R3_TEB

56

0x38

KGDT_VDM_TILE

64

0x40

KGDT_LDT

72

0x48

KGDT_DF_TSS

80

0x50

KGDT_NMI_TSS

88

0x58

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dg%20%28Display%20Selector%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/disable-heap-coalesce-on-free.md b/windows-driver-docs-pr/debugger/disable-heap-coalesce-on-free.md new file mode 100644 index 0000000000..cf564faf1a --- /dev/null +++ b/windows-driver-docs-pr/debugger/disable-heap-coalesce-on-free.md @@ -0,0 +1,62 @@ +--- +title: Disable heap coalesce on free +description: Disable heap coalesce on free +ms.assetid: 64a68fa2-9270-4b2d-9edc-d54370191dcb +keywords: ["Disable heap coalesce on free (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Disable heap coalesce on free + + +## + + +The **Disable heap coalesce on free** flag leaves adjacent blocks of heap memory separate when they are freed. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dhc

Hexadecimal value

0x00200000

Symbolic Name

FLG_HEAP_DISABLE_COALESCING

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +By default, Windows combines ("coalesces") newly-freed adjacent blocks into a single block. Combining the blocks takes time, but reduces fragmentation that might force the heap to allocate additional memory when it cannot find contiguous memory. + +This flag is used for maintaining compatibility with old applications. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Disable%20heap%20coalesce%20on%20free%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/disable-paging-of-kernel-stacks.md b/windows-driver-docs-pr/debugger/disable-paging-of-kernel-stacks.md new file mode 100644 index 0000000000..f91baff7cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/disable-paging-of-kernel-stacks.md @@ -0,0 +1,62 @@ +--- +title: Disable paging of kernel stacks +description: Disable paging of kernel stacks +ms.assetid: 3bf0ae20-4569-41de-9d7c-dd6a2790dac6 +keywords: ["Disable paging of kernel stacks (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Disable paging of kernel stacks + + +## + + +The **Disable paging of kernel stacks** flag prevents paging of the kernel-mode stacks of inactive threads. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dps

Hexadecimal value

0x80000

Symbolic Name

FLG_DISABLE_PAGE_KERNEL_STACKS

Destination

System-wide registry entry

+ +  + +### Comments + +Generally, the kernel-mode stack cannot be paged; it is guaranteed to be resident in memory. However, Windows occasionally pages the kernel stacks of inactive threads. This flag prevents these occurrences. + +The kernel debugger can provide information about a thread only when its stack is in physical memory. This flag is particularly important when debugging deadlocks and in other cases when every thread must be tracked. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Disable%20paging%20of%20kernel%20stacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/disable-protected-dll-verification.md b/windows-driver-docs-pr/debugger/disable-protected-dll-verification.md new file mode 100644 index 0000000000..663068030e --- /dev/null +++ b/windows-driver-docs-pr/debugger/disable-protected-dll-verification.md @@ -0,0 +1,56 @@ +--- +title: Disable protected DLL verification +description: Disable protected DLL verification +ms.assetid: 28b5c4f8-18d3-44ed-a424-92e8e04dcdbc +keywords: ["Disable protected DLL verification (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Disable protected DLL verification + + +## + + +The **Disable protected DLL verification** flag appears in GFlags, but it has no effect on Windows. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dpd

Hexadecimal value

0x80000000

Symbolic Name

FLG_DISABLE_PROTDLLS

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Disable%20protected%20DLL%20verification%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/disable-stack-extension.md b/windows-driver-docs-pr/debugger/disable-stack-extension.md new file mode 100644 index 0000000000..27e7fa3859 --- /dev/null +++ b/windows-driver-docs-pr/debugger/disable-stack-extension.md @@ -0,0 +1,60 @@ +--- +title: Disable stack extension +description: Disable stack extension +ms.assetid: e4c95103-4f98-4f79-a46c-c8040e39791b +keywords: ["Disable stack extension (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Disable stack extension + + +## + + +The **Disable stack extension** flag prevents the kernel from extending the stacks of the threads in the process beyond the initial committed memory. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

dse

Hexadecimal value

0x10000

Symbolic Name

FLG_DISABLE_STACK_EXTENSION

Destination

Image file registry entry

+ +  + +### Comments + +This feature is used to simulate low memory conditions (where stack extensions fail) and to test the strategic system processes that are expected to run well even with low memory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Disable%20stack%20extension%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/disassembly-window.md b/windows-driver-docs-pr/debugger/disassembly-window.md new file mode 100644 index 0000000000..881a49bb20 --- /dev/null +++ b/windows-driver-docs-pr/debugger/disassembly-window.md @@ -0,0 +1,64 @@ +--- +title: Assembly Code Debugging in WinDbg +description: In WinDbg, you can view assembly code by entering commands or by using the Disassembly window. +ms.assetid: e00ea29e-4153-4588-8353-de69910bfc65 +keywords: ["debugging information windows, Disassembly window", "Disassembly window", "assembly debugging, Disassembly window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Assembly Code Debugging in WinDbg + + +In WinDbg, you can view assembly code by entering commands or by using the Disassembly window. + +## Debugger Command Window + + +You can view assembly code by entering the one of the [**u, ub, uu (Unassemble)**](u--unassemble-.md) commands in the Debugger Command window. + +## Dissasembly Window + + +To open or switch to the Disassembly window, choose **Dissasembly** from the **View** menu. (You can also press ALT+7 or click the **Disassembly** button (![screen shot of the disassembly button](images/tbdisasm2.png)) on the toolbar. ALT+SHIFT+7 will close the Disassembly Window.) + +The following screen shot shows an example of a Disassembly window. + +![screen shot of the disassembly window](images/window-disassembly.png) + +The debugger takes a section of memory, interprets it as binary machine instructions, and then disassembles it to produce an assembly-language version of the machine instructions. The resulting code is displayed in the Disassembly window. + +In the Disassembly window, you can do the following: + +- To disassemble a different section of memory, in the **Offset** box, type the address of the memory you want to disassemble. (You can press ENTER after typing the address, but you do not have to.) The Disassembly window displays code before you have completed the address; you can disregard this code. + +- To see other sections of memory, click the **Previous** or **Next** buttons or press the PAGE UP or PAGE DOWN keys. These commands display disassembled code from the preceding or following sections of memory, respectively. By pressing the RIGHT ARROW, LEFT ARROW, UP ARROW, and DOWN ARROW keys, you can navigate within the window. If you use these keys to move off of the page, a new page will appear. + +The Disassembly window has a toolbar that contains two buttons and a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon that appears near the upper-right corner of the window (![screen shot of the button that displays the disassembly window toolbar shortcut menu](images/tbdisasm2.png)). The following list describes some of the menu commands: + +- **Go to current address** opens the Source window with the source file that corresponds to the selected line in the Disassembly window and highlights this line. + +- **Disassemble before current instruction** causes the current line to be placed in the middle of the Disassembly window. This command is the default option. If this command is cleared, the current line will appear at the top of the Disassembly window, which saves time because reverse-direction disassembly can be time-consuming. + +- **Highlight instructions from the current source line** causes all of the instructions that correspond to the current source line to be highlighted. Often, a single source line will correspond to multiple assembly instructions. If code has been optimized, these assembly instructions might not be consecutive. This command enables you to find all of the instructions that were assembled from the current source line. + +- **Show source line for each instruction** displays the source line number that corresponds to each assembly instruction. + +- **Show source file for each instruction** displays the source file name that corresponds to each assembly instruction. + +### Additional Information + +For more information about assembly debugging and related commands and a full explanation of the assembly display, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Assembly%20Code%20Debugging%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/displaying-a-critical-section.md b/windows-driver-docs-pr/debugger/displaying-a-critical-section.md new file mode 100644 index 0000000000..c00cb6c38c --- /dev/null +++ b/windows-driver-docs-pr/debugger/displaying-a-critical-section.md @@ -0,0 +1,218 @@ +--- +title: Displaying a Critical Section +description: Displaying a Critical Section +ms.assetid: d55971f6-9112-417d-8fb6-e299c7fc90a7 +keywords: ["critical section", "critical section, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Displaying a Critical Section + + +## + + +Critical sections can be displayed in user mode by a variety of different methods. The exact meaning of each field depends on the version of Microsoft Windows version you are using. + +### Displaying Critical Sections + +Critical sections can be displayed by the **!ntsdexts.locks** extension, the **!critsec** extension, the **!cs** extension, and the **dt (Display Type)** command. + +The [**!ntsdexts.locks**](-locks---ntsdexts-locks-.md) extension displays a list of critical sections associated with the current process. If the **-v** option is used, all critical sections are displayed. Here is an example: + +``` +0:000> !locks + +CritSec ntdll!FastPebLock+0 at 77FC49E0 +LockCount 0 +RecursionCount 1 +OwningThread c78 +EntryCount 0 +ContentionCount 0 +*** Locked + +.... +Scanned 37 critical sections +``` + +If you know the address of the critical section you wish to display, you can use the [**!critsec**](-critsec.md) extension. This displays the same collection of information as **!ntsdexts.locks**. For example: + +``` +0:000> !critsec 77fc49e0 + +CritSec ntdll!FastPebLock+0 at 77FC49E0 +LockCount 0 +RecursionCount 1 +OwningThread c78 +EntryCount 0 +ContentionCount 0 +*** Locked +``` + +The [**!cs**](-cs.md) extension is only available in Microsoft Windows XP and later versions of Windows. It can display a critical section based on its address, search an address range for critical sections, and even display the stack trace associated with each critical section. Some of these features require full Windows symbols to work properly. If Application Verifier is active, **!cs -t** can be used to display the critical section tree. See the **!cs** reference page for details and examples. + +The information displayed by **!cs** is slightly different than that shown by **!ntsdexts.locks** and **!critsec**. For example: + +``` +## 0:000> !cs 77fc49e0 + +Critical section = 0x77fc49e0 (ntdll!FastPebLock+0x0) +DebugInfo = 0x77fc3e00 +LOCKED +LockCount = 0x0 +OwningThread = 0x00000c78 +RecursionCount = 0x1 +LockSemaphore = 0x0 +SpinCount = 0x00000000 +``` + +The [**dt (Display Type)**](dt--display-type-.md) command can be used to display the literal contents of the RTL\_CRITICAL\_SECTION structure. For example: + +``` +0:000> dt RTL_CRITICAL_SECTION 77fc49e0 + +0x000 DebugInfo : 0x77fc3e00 + +0x004 LockCount : 0 + +0x008 RecursionCount : 1 + +0x00c OwningThread : 0x00000c78 + +0x010 LockSemaphore : (null) + +0x014 SpinCount : 0 +``` + +### Interpreting Critical Section Fields in Windows XP and Windows 2000 + +The most important fields of the critical section structure are as follows: + +- In Microsoft Windows 2000, and Windows XP, the **LockCount** field indicates the number of times that any thread has called the **EnterCriticalSection** routine for this critical section, minus one. This field starts at -1 for an unlocked critical section. Each call of **EnterCriticalSection** increments this value; each call of **LeaveCriticalSection** decrements it. For example, if **LockCount** is 5, this critical section is locked, one thread has acquired it, and five additional threads are waiting for this lock. + +- The **RecursionCount** field indicates the number of times that the owning thread has called **EnterCriticalSection** for this critical section. + +- The **EntryCount** field indicates the number of times that a thread other than the owning thread has called **EnterCriticalSection** for this critical section. + +A newly initialized critical section looks like this: + +``` +0:000> !critsec 433e60 +CritSec mymodule!cs+0 at 00433E60 +LockCount NOT LOCKED +RecursionCount 0 +OwningThread 0 +EntryCount 0 +ContentionCount 0 +``` + +The debugger displays "NOT LOCKED" as the value for **LockCount**. The actual value of this field for an unlocked critical section is -1. You can verify this with the **dt (Display Type)** command: + +``` +0:000> dt RTL_CRITICAL_SECTION 433e60 + +0x000 DebugInfo : 0x77fcec80 + +0x004 LockCount : -1 + +0x008 RecursionCount : 0 + +0x00c OwningThread : (null) + +0x010 LockSemaphore : (null) + +0x014 SpinCount : 0 +``` + +When the first thread calls the **EnterCriticalSection** routine, the critical section's **LockCount**, **RecursionCount**, **EntryCount** and **ContentionCount** fields are all incremented by one, and **OwningThread** becomes the thread ID of the caller. **EntryCount** and **ContentionCount** are never decremented. For example: + +``` +0:000> !critsec 433e60 +CritSec mymodule!cs+0 at 00433E60 +LockCount 0 +RecursionCount 1 +OwningThread 4d0 +EntryCount 0 +ContentionCount 0 +``` + +At this point, four different things can happen. + +1. The owning thread calls **EnterCriticalSection** again. This will increment **LockCount** and **RecursionCount**. **EntryCount** is not incremented. + + ``` + 0:000> !critsec 433e60 + CritSec mymodule!cs+0 at 00433E60 + LockCount 1 + RecursionCount 2 + OwningThread 4d0 + EntryCount 0 + ContentionCount 0 + ``` + +2. A different thread calls **EnterCriticalSection**. This will increment **LockCount** and **EntryCount**. **RecursionCount** is not incremented. + + ``` + 0:000> !critsec 433e60 + CritSec mymodule!cs+0 at 00433E60 + LockCount 1 + RecursionCount 1 + OwningThread 4d0 + EntryCount 1 + ContentionCount 1 + ``` + +3. The owning thread calls **LeaveCriticalSection**. This will decrement **LockCount** (to -1) and **RecursionCount** (to 0), and will reset **OwningThread** to 0. + + ``` + 0:000> !critsec 433e60 + CritSec mymodule!cs+0 at 00433E60 + LockCount NOT LOCKED + RecursionCount 0 + OwningThread 0 + EntryCount 0 + ContentionCount 0 + ``` + +4. Another thread calls **LeaveCriticalSection**. This produces the same results as the owning thread calling **LeaveCriticalSection** -- it will decrement **LockCount** (to -1) and **RecursionCount** (to 0), and will reset **OwningThread** to 0. + +When any thread calls **LeaveCriticalSection**, Windows decrements **LockCount** and **RecursionCount**. This feature has both good and bad aspects. It allows a device driver to enter a critical section on one thread and leave the critical section on another thread. However, it also makes it possible to accidentally call **LeaveCriticalSection** on the wrong thread, or to call **LeaveCriticalSection** too many times and cause **LockCount** to reach values lower than -1. This corrupts the critical section and causes all threads to wait indefinitely on the critical section. + +### Interpreting Critical Section Fields in Windows Server 2003 SP1 and Later + +In Microsoft Windows Server 2003 Service Pack 1 and later versions of Windows, the **LockCount** field is parsed as follows: + +- The lowest bit shows the lock status. If this bit is 0, the critical section is locked; if it is 1, the critical section is not locked. + +- The next bit shows whether a thread has been woken for this lock. If this bit is 0, then a thread has been woken for this lock; if it is 1, no thread has been woken. + +- The remaining bits are the ones-complement of the number of threads waiting for the lock. + +As an example, suppose the **LockCount** is -22. The lowest bit can be determined in this way: + +``` +0:009> ? 0x1 & (-0n22) +Evaluate expression: 0 = 00000000 +``` + +The next-lowest bit can be determined in this way: + +``` +0:009> ? (0x2 & (-0n22)) >> 1 +Evaluate expression: 1 = 00000001 +``` + +The ones-complement of the remaining bits can be determined in this way: + +``` +0:009> ? ((-1) - (-0n22)) >> 2 +Evaluate expression: 5 = 00000005 +``` + +In this example, the first bit is 0 and therefore the critical section is locked. The second bit is 1, and so no thread has been woken for this lock. The complement of the remaining bits is 5, and so there are five threads waiting for this lock. + +### Additional Information + +For information about how to debug critical section time outs, see [Critical Section Time Outs](critical-section-time-outs.md). For general information about critical sections, see the Microsoft Windows SDK, the Windows Driver Kit (WDK), or *Microsoft Windows Internals* by Mark Russinovich and David Solomon. (These resources may not be available in some languages and countries.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Displaying%20a%20Critical%20Section%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/displaying-rpc-state-information.md b/windows-driver-docs-pr/debugger/displaying-rpc-state-information.md new file mode 100644 index 0000000000..83abba753a --- /dev/null +++ b/windows-driver-docs-pr/debugger/displaying-rpc-state-information.md @@ -0,0 +1,53 @@ +--- +title: Displaying RPC State Information +description: Displaying RPC State Information +ms.assetid: 9931cf62-a7c2-4270-8664-a77a82207aa9 +keywords: ["RPC debugging, displaying RPC state information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Displaying RPC State Information + + +## + + +All RPC run-time state information is contained in cells. A cell is the smallest unit of information that can be viewed and updated individually. Both the DbgRpc tool and the RPC debugger extensions allow you to view the contents of any given cell or to run high-level queries. + +Each key object in the RPC Run-Time will maintain one or more cells of information about its state. Each cell has a cell ID. When an object refers to another object, it does so by specifying that object's cell ID. + +The key objects that the RPC Run-Time can maintain information about are endpoints, threads, connection objects, Server Call (SCALL) objects, and Client Call (CCALL) objects. Server Call objects are usually referred to simply as *call objects*. + +The RPC state information queries produce the same information whether you are using the DbgRpc tool or the RPC debugger extensions. The following sections describe how queries are used in each vehicle: + +[Using the RPC Debugger Extensions](using-the-rpc-debugger-extensions.md) + +[Using the DbgRpc Tool](using-the-dbgrpc-tool.md) + +The most basic query simply displays an individual cell: + +[Get RPC Cell Information](get-rpc-cell-information.md) + +The following high-level queries are also available: + +[Get RPC Endpoint Information](get-rpc-endpoint-information.md) + +[Get RPC Thread Information](get-rpc-thread-information.md) + +[Get RPC Call Information](get-rpc-call-information.md) + +[Get RPC Client Call Information](get-rpc-client-call-information.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Displaying%20RPC%20State%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dl--display-linked-list-.md b/windows-driver-docs-pr/debugger/dl--display-linked-list-.md new file mode 100644 index 0000000000..bd87c5849a --- /dev/null +++ b/windows-driver-docs-pr/debugger/dl--display-linked-list-.md @@ -0,0 +1,93 @@ +--- +title: dl (Display Linked List) +description: The dl command displays a LIST_ENTRY or SINGLE_LIST_ENTRY linked list. +ms.assetid: fbf03e78-d4b3-4dd9-904b-3f44a1a86cff +keywords: ["dl (Display Linked List) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dl (Display Linked List) +api_type: +- NA +--- + +# dl (Display Linked List) + + +The **dl** command displays a LIST\_ENTRY or SINGLE\_LIST\_ENTRY linked list. + +``` +dl[b] Address MaxCount Size +``` + +## Parameters + + + **b** +If this is included, the list is dumped in reverse order. (In other words, the debugger follows the **Blink**s instead of the **Flink**s.) This cannot be used with a SINGLE\_LIST\_ENTRY. + + *Address* +The starting address of the list. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *MaxCount* +Maximum number of elements to dump. + + *Size* +Size of each element. This is the number of consecutive ULONG\_PTRs that will be displayed for each element in the list. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +This list must be a LIST\_ENTRY or SINGLE\_LIST\_ENTRY structure. If this is embedded in a larger structure, be sure that *Address* points to the linked list structure and not to the beginning of the outer structure. + +The display begins with *Address*. Therefore, if you are supplying the address of a pointer that points to the beginning of the list, you should disregard the first element printed. + +The *Address*, *MaxCount*, and *Size* parameters are in the current default radix. You can use the [**n (Set Number Base)**](n--set-number-base-.md) command or the **0x** prefix to change the radix. + +If the list loops back on itself, the dump will stop. If a null pointer is encountered, the dump will stop. + +If you want to execute some command for each element of the list, use the [**!list**](-list.md) extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dl%20%28Display%20Linked%20List%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/docking-a-window.md b/windows-driver-docs-pr/debugger/docking-a-window.md new file mode 100644 index 0000000000..a9a638fb4a --- /dev/null +++ b/windows-driver-docs-pr/debugger/docking-a-window.md @@ -0,0 +1,59 @@ +--- +title: Docking a Window +description: Docking a Window +ms.assetid: e8963a3b-0e86-4f4f-a59e-27cbde6a6ff8 +keywords: ["debugging information windows, docking windows", "docking windows", "window docking"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Docking a Window + + +## + + +To dock a floating window, do one of the following: + +- Double-click the window's title bar. + +- Open the shortcut menu by right-clicking the window's title bar or clicking the window's icon in the upper-right corner, and then click **Dock**. + +- In the WinDbg window, on the **Window** menu, click **Dock All**. This command docks all of the windows except those that have the **Always floating** option selected on their individual shortcut menus. + +- Drag the window to a docking location. This action causes the window to dock unless **Always floating** is selected on the shortcut menu for that window, or unless you press and hold the ALT key as you begin dragging the window. + +When you dock a window by any method other than dragging it, WinDbg automatically positions the docked window. If the window has never been docked before, WinDbg moves the window to a new untabbed location within the WinDbg window. If the window has been docked before, WinDbg returns the window to its most recent docking location, which might be tabbed or untabbed. + +When you dock a window by dragging it, you can control its destination position. As you drag the window, you will see a semi-transparent outline of the window appear. This outline shows where the window will be docked if you release the mouse button at that point. The following rules determine where a dragged window is docked: + +- If you drag the mouse pointer over the WinDbg window when the window is empty or over an empty dock, and then you release the mouse button, the dragged window is docked in that location and completely fills the frame or dock. + +- If you drag the mouse pointer over the left, right, top, or bottom portion of an already-docked window and then you release the mouse button, the dragged window is docked to the left, right, top, or bottom of the already-docked window, respectively. + +- When you drag the mouse pointer over a floating window (including the original position of the window that you are dragging), no docking occurs. This exception means that you might have to drag other windows out of the way (or drag the current window two times) before you can move the window to where you want it. + +- If you drag the mouse pointer to a position that is not inside the WinDbg frame or any other dock and then you release the mouse button, the dragged window remains floating. + +All of the preceding rules apply to the mouse pointer location itself. They do not depend on where you originally clicked within the title bar of the window that you are dragging. + +### Re-docking + +If you let WinDbg automatically dock a floating window that was previously docked, WinDbg tries to put the window in the same docking position that it previously occupied. Also, if you load a workspace, WinDbg tries to restore all of the debugging information windows to their previous positions, whether docked or floating. + +However, multiple instances of [Memory windows](memory-window.md) and [Source windows](source-window.md) are not distinguished when the docking position is saved. For example, if you combine the [Locals window](locals-window.md) together with a Memory window in a tabbed collection, and this state is saved and later restored, the Locals window joins a Memory window in a tabbed collection, but it might not be the same Memory window as before. + +If you load a workspace that includes one or more Source windows when the source files are inaccessible, those Source windows are not reopened. When this situation occurs, other windows that were tabbed together with those windows might return to the floating state. If you want to keep all of your Source windows tabbed together, you should include at least one source file that is always present, or include an additional window in the tabbed collection. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Docking%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ds--ds--display-string-.md b/windows-driver-docs-pr/debugger/ds--ds--display-string-.md new file mode 100644 index 0000000000..9085c4f985 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ds--ds--display-string-.md @@ -0,0 +1,85 @@ +--- +title: ds, dS (Display String) +description: The ds and dS commands display a STRING, ANSI_STRING, or UNICODE_STRING structure. +ms.assetid: cb05e89c-6c83-476b-a577-a6aeefd8cdd6 +keywords: ["ds, dS (Display String) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ds, dS (Display String) +api_type: +- NA +--- + +# ds, dS (Display String) + + +The **ds** and **dS** commands display a STRING, ANSI\_STRING, or UNICODE\_STRING structure. (These commands do not display null-delimited character strings.) + +``` +d{s|S} [/c Width] [Address] +``` + +## Parameters + + + **s** +Specifies that a STRING or ANSI\_STRING structure is to be displayed. (This **s** is case-sensitive.) + + **S** +Specifies that a UNICODE\_STRING structure is to be displayed. (This **S** is case-sensitive.) + + **/c** *Width* +Specifies the number of characters to display on each line. This number includes null characters, which will not be visible. + + *Address* +The memory address where the string begins. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If omitted, the last address used in a display command is assumed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +If you want to display Unicode strings in the Locals window or Watch window of WinDbg, you need to use the [**.enable\_unicode (Enable Unicode Display)**](-enable-unicode--enable-unicode-display-.md) command first. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ds,%20dS%20%28Display%20String%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dt--display-type-.md b/windows-driver-docs-pr/debugger/dt--display-type-.md new file mode 100644 index 0000000000..b9e4f51e28 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dt--display-type-.md @@ -0,0 +1,466 @@ +--- +title: dt (Display Type) +description: The dt command displays information about a local variable, global variable or data type. This can display information about simple data types, as well as structures and unions. +ms.assetid: 82aba13e-6604-46ca-b3e5-bb865ecf3f1f +keywords: ["dt (Display Type) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dt (Display Type) +api_type: +- NA +--- + +# dt (Display Type) + + +The **dt** command displays information about a local variable, global variable or data type. This can display information about simple data types, as well as structures and unions. + +User-Mode Syntax + +``` +dt [-DisplayOpts] [-SearchOpts] [module!]Name [[-SearchOpts] Field] [Address] [-l List] +dt [-DisplayOpts] Address [-l List] +dt -h +``` + +Kernel-Mode Syntax + +``` +[Processor] dt [-DisplayOpts] [-SearchOpts] [module!]Name [[-SearchOpts] Field] [Address] [-l List] +dt [-DisplayOpts] Address [-l List] +dt -h +``` + +## Parameters + + + *Processor* +Specifies the processor that is running the process containing the information needed. For more information, see [Multiprocessor Syntax](multiprocessor-syntax.md). Processors can only be specified in kernel mode. + + *DisplayOpts* +Specifies one or more of the options given in the following table. These options are preceded by a hyphen. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription

-a[quantity]

Show each array element on a new line, with its index. A total of quantity elements will be displayed. There must be no space between the a and the quantity. If -a is not followed by a digit, all items in the array are shown. The -a[quantity] switch should appear immediately before each type name or field name that you want displayed in this manner.

-b

Display blocks recursively. If a displayed structure contains substructures, it is expanded recursively to arbitrary depths and displayed in full. Pointers are expanded only if they are in the original structure, not in substructures.

-c

Compact output. All fields are displayed on one line, if possible. (When used with the -a switch, each array element takes one line rather than being formatted as a several-line block.)

-d

When used with a Name that is ended with an asterisk, display verbose output for all types that begin with Name. If Name does not end with an asterisk, display verbose output.

-e

Forces dt to enumerate types. This option is only needed if dt is mistakenly interpreting the Name value as an instance rather than as a type.

-i

Do not indent the subtypes.

-o

Omit offset values of the structure fields.

-p

Address is a physical address, rather than a virtual address.

-r[depth]

Recursively dumps the subtype fields. If depth is given, this recursion will stop after depth levels. The depth must be a digit between 1 and 9, and there must be no space between the r and the depth. The -r[depth] switch should appear immediately before the address.

-s size

Enumerate only those types whose size in bytes equals the value of size. The -s option is only useful when types are being enumerated. When -s is specified, -e is always implied as well.

-t

Enumerate types only.

-v

Verbose output. This gives additional information such as the total size of a structure and the number of its elements. When this is used along with the -y search option, all symbols are displayed, even those with no associated type information.

+ +  + + *SearchOpts* +Specifies one or more of the options given in the following table. These options are preceded by a hyphen. + + ++++ + + + + + + + + + + + + + + + + +
OptionDescription

-n

This indicates that the next parameter is a name. This should be used if the next item consists entirely of hexadecimal characters, because it will otherwise be taken as an address.

-y

This indicates that the next parameter is the beginning of the name, not necessarily the entire name. When -y is included, all matches are listed, followed by detailed information on the first match in the list. If -y is not included, only exact matches will be displayed.

+ +  + + *module* +An optional parameter specifying the module that defines this structure. If there is a local variable or type with the same name as a global variable or type, you should include *module* to specify that you mean the global variable. Otherwise, the **dt** command will display the local variable, even if the local variable is a case-insensitive match and the global variable is a case-sensitive match. + + *Name* +Specifies the name of a type or global variable. If *Name* ends with an asterisk (**\***), a list of all matches is displayed. Thus, **dt A\*** will list all data types, globals, and statics beginning with "A", but will not display the actual instances of these types. (If the **-v** display option is used at the same time, all symbols will be displayed -- not just those with associated type information.) You can also replace *Name* with a period (**.**) to signify that you want to repeat the most recently used value of *Name*. + +If *Name* contains a space, it should be enclosed in parentheses. + + *Field* +Specifies the field(s) to be displayed. If *Field* is omitted, all fields are displayed. If *Field* is followed by a period (**.**), the first-level subfields of this field will be displayed as well. If *Field* is followed with a series of periods, the subfields will be displayed to a depth equal to the number of periods. Any field name followed by a period will be treated as a prefix match, as if the **-y** search option was used. If *Field* is followed by an asterisk (\*), it is treated as only the beginning of the field, not necessarily the entire field, and all matching fields are displayed. + + *Address* +Specifies the address of the structure to be displayed. If *Name* is omitted, *Address* must be included and must specify the address of a global variable. *Address* is taken to be a virtual address unless otherwise specified. Use the **-p** option to specify a physical address. Use an "at" sign ( **@** ) to specify a register (for example, **@eax**). + + *List* +Specifies the field name that links a linked list. The *Address* parameter must be included. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The **dt** command output will always display signed numbers in base 10, and unsigned numbers in hexadecimal. + +All parameters of **dt** that allow symbol values also allow string wildcards. See [String Wildcard Syntax](string-wildcard-syntax.md) for details. + +The **-y** and **-n** options can precede any *Name* or *Field*. The **-y** option allows you to specify the beginning of the type or structure name. For example, **dt -y ALLEN** will display data about the type **ALLENTOWN**. However, you could not display the type **ALLENTOWN** with **dt -y A**. Instead, you would have to use **dt -ny A**, because **A** is a valid hexadecimal value and would be interpreted as an address without the **-n** option. + +If *Name* indicates a structure, all fields will be displayed (for example, **dt myStruct**). If you only want one specific field, you can do **dt myStruct myField**. This displays the member that C would call **myStruct.myField**. However, note that the command **dt myStruct myField1 myField2** displays **myStruct.myField1** and **myStruct.myField2**. It does not display **myStruct.myField1.myField2**. + +If a structure name or field is followed by a subscript, this specifies a single instance of an array. For example, **dt myStruct myFieldArray\[3\]** will display the fourth element of the array in question. But if a type name is followed by a subscript, this specifies an entire array. For example, **dt CHAR\[8\] myPtr** will display an eight-character string. The subscript is always taken as decimal regardless of the current radix; an **0x** prefix will cause an error. + +Because the command uses type information from the .*pdb* file, it can freely be used to debug any CPU platform. + +The type information used by **dt** includes all type names created with **typedef**, including all the Windows-defined types. For example, **unsigned long** and **char** are not valid type names, but **ULONG** and **CHAR** are. See the Microsoft Windows SDK for a full list of all Windows type names. + +All types created by **typedefs** within your own code will be present, as long as they have actually been used in your program. However, types that are defined in your headers but never actually used will not be stored in the .pdb symbol files and will not be accessible to the debugger. To make such a type available to the debugger, use it as the *input* of a **typedef** statement. For example, if the following appears in your code, the structure MY\_DATA will be stored in the .pdb symbol file and can be displayed by the **dt** command: + +``` +typedef struct _MY_DATA { + . . . + } MY_DATA; +typedef MY_DATA *PMY_DATA; +``` + +On the other hand, the following code would not suffice because both MY\_DATA and PMY\_DATA are defined by the initial **typedef** and, therefore, MY\_DATA has not itself been used as the input of any **typedef** statement: + +``` +typedef struct _MY_DATA { + . . . + } MY_DATA, *PMY_DATA; +``` + +In any event, type information is included only in a full symbol file, not a symbol file that has been stripped of all private symbol information. For more information, see [Public and Private Symbols](public-and-private-symbols.md). + +If you want to display unicode strings, you need to use the [**.enable\_unicode (Enable Unicode Display)**](-enable-unicode--enable-unicode-display-.md) command first. You can control the display of long integers with the [**.enable\_long\_status (Enable Long Integer Display)**](-enable-long-status--enable-long-integer-display-.md) command. + +In the following example, **dt** displays a global variable: + +``` +0:000> dt mt1 + +0x000 a : 10 + +0x004 b : 98 'b' + +0x006 c : 0xdd + +0x008 d : 0xabcd + +0x00c gn : [6] 0x1 + +0x024 ex : 0x0 +``` + +In the following example, **dt** displays the array field **gn**: + +``` +0:000> dt mt1 -a gn + +0x00c gn : + [00] 0x1 + [01] 0x2 + [02] 0x3 + [03] 0x4 + [04] 0x5 + [05] 0x6 +``` + +The following command displays some subfields of a variable: + +``` +0:000> dt mcl1 m_t1 dpo + +0x010 dpo : DEEP_ONE + +0x070 m_t1 : MYTYPE1 +``` + +The following command displays the subfields of the field **m\_t1**. Because the period automatically causes prefix matching, this will also display subfields of any field that begins with "m\_t1": + +``` +0:000> dt mcl1 m_t1. + +0x070 m_t1 : + +0x000 a : 0 + +0x004 b : 0 ' + +0x006 c : 0x0 + +0x008 d : 0x0 + +0x00c gn : [6] 0x0 + +0x024 ex : 0x0 +``` + +You could repeat this to any depth. For example, the command **dt mcl1 a..c.** would display all fields to depth four, such that the first field name began with **a** and the third field name began with **c**. + +Here is a more detailed example of how subfields can be displayed. First, display the **Ldr** field: + +``` +0:000> dt nt!_PEB Ldr 7ffdf000 + +0x00c Ldr : 0x00191ea0 +``` + +Now expand the pointer type field: + +``` +0:000> dt nt!_PEB Ldr Ldr. 7ffdf000 + +0x00c Ldr : 0x00191ea0 + +0x000 Length : 0x28 + +0x004 Initialized : 0x1 ' + +0x008 SsHandle : (null) + +0x00c InLoadOrderModuleList : _LIST_ENTRY [ 0x191ee0 - 0x192848 ] + +0x014 InMemoryOrderModuleList : _LIST_ENTRY [ 0x191ee8 - 0x192850 ] + +0x01c InInitializationOrderModuleList : _LIST_ENTRY [ 0x191f58 - 0x192858 ] + +0x024 EntryInProgress : (null) +``` + +Now display the **CriticalSectionTimeout** field: + +``` +0:000> dt nt!_PEB CriticalSectionTimeout 7ffdf000 + +0x070 CriticalSectionTimeout : _LARGE_INTEGER 0xffffe86d`079b8000 +``` + +Now expand the **CriticalSectionTimeout** structure subfields one level deep: + +``` +0:000> dt nt!_PEB CriticalSectionTimeout. 7ffdf000 + +0x070 CriticalSectionTimeout : 0xffffe86d`079b8000 + +0x000 LowPart : 0x79b8000 + +0x004 HighPart : -6035 + +0x000 u : __unnamed + +0x000 QuadPart : -25920000000000 +``` + +Now expand the **CriticalSectionTimeout** structure subfields two levels deep: + +``` +0:000> dt nt!_PEB CriticalSectionTimeout.. 7ffdf000 + +0x070 CriticalSectionTimeout : 0xffffe86d`079b8000 + +0x000 LowPart : 0x79b8000 + +0x004 HighPart : -6035 + +0x000 u : + +0x000 LowPart : 0x79b8000 + +0x004 HighPart : -6035 + +0x000 QuadPart : -25920000000000 +``` + +The following command displays an instance of the data type MYTYPE1 that is located at the address 0x0100297C: + +``` +0:000> dt 0x0100297c MYTYPE1 + +0x000 a : 22 + +0x004 b : 43 '+' + +0x006 c : 0x0 + +0x008 d : 0x0 + +0x00c gn : [6] 0x0 + +0x024 ex : 0x0 +``` + +The following command displays an array of 10 ULONGs at the address 0x01002BE0: + +``` +0:000> dt -ca10 ULONG 01002be0 +[0] 0x1001098 +[1] 0x1 +[2] 0xdead +[3] 0x7d0 +[4] 0x1 +[5] 0xcd +[6] 0x0 +[7] 0x0 +[8] 0x0 +[9] 0x0 +``` + +The following command continues the previous display at a different address. Note that "ULONG" does not need to be re-entered: + +``` +0:000> dt -ca4 . 01002d00 +Using sym ULONG +[0] 0x12 +[1] 0x4ac +[2] 0xbadfeed +[3] 0x2 +``` + +Here are some examples of type display. The following command displays all types and globals beginning with the string "MY" in the module *thismodule*. Those prefixed with an address are actual instances; those without addresses are type definitions: + +``` +0:000> dt thismodule!MY* +010029b8 thismodule!myglobal1 +01002990 thismodule!myglobal2 + thismodule!MYCLASS1 + thismodule!MYCLASS2 + thismodule!MYCLASS3 + thismodule!MYTYPE3::u + thismodule!MYTYPE1 + thismodule!MYTYPE3 + thismodule!MYTYPE3 + thismodule!MYFLAGS +``` + +When performing type display, the **-v** option can be used to display the size of each item. The **-s** *size* option can be used to only enumerate items of a specific size. Again, those prefixed with an address are actual instances; those without addresses are type definitions: + +``` +0:001> dt -s 2 -v thismodule!* +Enumerating symbols matching thismodule!*, Size = 0x2 +Address Size Symbol + 002 thismodule!wchar_t + 002 thismodule!WORD + 002 thismodule!USHORT + 002 thismodule!SHORT + 002 thismodule!u_short + 002 thismodule!WCHAR +00427a34 002 thismodule!numberOfShips +00427a32 002 thismodule!numberOfPlanes +00427a30 002 thismodule!totalNumberOfItems +``` + +Here is an example of the **-b** option. The structure is expanded and the **OwnerThreads** array within the structure is expanded, but the **Flink** and **Blink** list pointers are not followed: + +``` +kd> dt nt!_ERESOURCE -b 0x8154f040 + +0x000 SystemResourcesList : [ 0x815bb388 - 0x816cd478 ] + +0x000 Flink : 0x815bb388 + +0x004 Blink : 0x816cd478 + +0x008 OwnerTable : (null) + +0x00c ActiveCount : 1 + +0x00e Flag : 8 + +0x010 SharedWaiters : (null) + +0x014 ExclusiveWaiters : (null) + +0x018 OwnerThreads : + [00] + +0x000 OwnerThread : 0 + +0x004 OwnerCount : 0 + +0x004 TableSize : 0 + [01] + +0x000 OwnerThread : 0x8167f563 + +0x004 OwnerCount : 1 + +0x004 TableSize : 1 + +0x028 ContentionCount : 0 + +0x02c NumberOfSharedWaiters : 0 + +0x02e NumberOfExclusiveWaiters : 0 + +0x030 Address : (null) + +0x030 CreatorBackTraceIndex : 0 + +0x034 SpinLock : 0 +``` + +Here is an example of **dt** in kernel mode. The following command produces results similar to [**!process 0 0**](-process.md): + +``` +kd> dt nt!_EPROCESS -l ActiveProcessLinks.Flink -y Ima -yoi Uni 814856f0 +## ActiveProcessLinks.Flink at 0x814856f0 + +UniqueProcessId : 0x00000008 +ImageFileName : [16] "System" + +## ActiveProcessLinks.Flink at 0x8138a030 + +UniqueProcessId : 0x00000084 +ImageFileName : [16] "smss.exe" + +## ActiveProcessLinks.Flink at 0x81372368 + +UniqueProcessId : 0x000000a0 +ImageFileName : [16] "csrss.exe" + +## ActiveProcessLinks.Flink at 0x81369930 + +UniqueProcessId : 0x000000b4 +ImageFileName : [16] "winlogon.exe" + +.... +``` + +If you want to execute a command for each element of the list, use the [**!list**](-list.md) extension. + +Finally, the **dt -h** command will display a short help text summarizing the **dt** syntax. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dt%20%28Display%20Type%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dtx--display-type---extended-debugger-object-model-information-.md b/windows-driver-docs-pr/debugger/dtx--display-type---extended-debugger-object-model-information-.md new file mode 100644 index 0000000000..86ff931017 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dtx--display-type---extended-debugger-object-model-information-.md @@ -0,0 +1,143 @@ +--- +title: dtx (Display Type - Extended Debugger Object Model Information) +description: The dtx command displays extended symbolic type information using the debugger object model. The dtx command is similar to the dt (Display Type) command. +ms.assetid: 758D752E-65A0-4F1D-BB56-06E4ECEC6D48 +keywords: ["dtx (Display Type - Extended Debugger Object Model Information) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dtx (Display Type - Extended Debugger Object Model Information) +api_type: +- NA +--- + +# dtx (Display Type - Extended Debugger Object Model Information) + + +The dtx command displays extended symbolic type information using the debugger object model. The dtx command is similar to the [**dt (Display Type)**](dt--display-type-.md) command. + +``` +dtx -DisplayOpts [Module!]Name Address +``` + +## Parameters + + + **DisplayOpts** +Use the following optional flags to change how the output is displayed. + +*-a* Displays array elements in a new line with its index. + +*-r \[n\]* Recursively dump the subtypes (fields) up to *n* levels. + +*-h* Displays command line help for the dtx command. + +**Module!** +An optional parameter specifying the module that defines this structure, followed by the exclamation point. If there is a local variable or type with the same name as a global variable or type, you should include *module* name to specify the global variable. + + **Name** +A type name or a global symbol. + + **Address** +Memory address containing the type. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +The following examples show how to use the dtx command. + +Use the address and the name to display extended symbolic type information. + +``` +0: kd> dtx nt!_EPROCESS ffffb607560b56c0 +(*((nt!_EPROCESS *)0xffffb607560b56c0)) [Type: _EPROCESS] + [+0x000] Pcb [Type: _KPROCESS] + [+0x2d8] ProcessLock [Type: _EX_PUSH_LOCK] + [+0x2e0] RundownProtect [Type: _EX_RUNDOWN_REF] + [+0x2e8] UniqueProcessId : 0x4 [Type: void *] + [+0x2f0] ActiveProcessLinks [Type: _LIST_ENTRY] +``` + +Display additional information using the -r recursion option. + +``` +0: kd> dtx -r2 HdAudio!CAzMixertopoMiniport fffff806`d24992b8 +(*((HdAudio!CAzMixertopoMiniport *)0xfffff806d24992b8)) [Type: CAzMixertopoMiniport] + [+0x018] m_lRefCount : -766760880 [Type: long] + [+0x020] m_pUnknownOuter : 0xfffff806d24dbc40 [Type: IUnknown *] + [+0x028] m_FilterDesc [Type: PCFILTER_DESCRIPTOR] + [+0x000] Version : 0xd24c2890 [Type: unsigned long] + [+0x008] AutomationTable : 0xfffff806d24c2780 [Type: PCAUTOMATION_TABLE *] + [+0x000] PropertyItemSize : 0x245c8948 [Type: unsigned long] + [+0x004] PropertyCount : 0x6c894808 [Type: unsigned long] + [+0x008] Properties : 0x5718247489481024 [Type: PCPROPERTY_ITEM *] + [+0x010] MethodItemSize : 0x55415441 [Type: unsigned long] + [+0x014] MethodCount : 0x57415641 [Type: unsigned long] + [+0x018] Methods : 0x4ce4334540ec8348 [Type: PCMETHOD_ITEM *] + [+0x020] EventItemSize : 0x8b41f18b [Type: unsigned long] + [+0x024] EventCount : 0xd8b48f4 [Type: unsigned long] + [+0x028] Events : 0x7d2d8d4cfffdf854 [Type: PCEVENT_ITEM *] + [+0x030] Reserved : 0x66fffd79 [Type: unsigned long] + [+0x010] PinSize : 0xd24aa9b0 [Type: unsigned long] + [+0x014] PinCount : 0xfffff806 [Type: unsigned long] + [+0x018] Pins : 0xfffff806d24aa740 [Type: PCPIN_DESCRIPTOR *] + [+0x000] MaxGlobalInstanceCount : 0x57555340 [Type: unsigned long] + [+0x004] MaxFilterInstanceCount : 0x83485741 [Type: unsigned long] + [+0x008] MinFilterInstanceCount : 0x8b4848ec [Type: unsigned long] + [+0x010] AutomationTable : 0xa5158b48ed33c000 [Type: PCAUTOMATION_TABLE *] + [+0x018] KsPinDescriptor [Type: KSPIN_DESCRIPTOR] +``` + +Tip: Use the [**x (Examine Symbols)**](x--examine-symbols-.md) command to display the address of an item of interest. + +``` +0: kd> x /d HdAudio!CazMixertopoMiniport* +... +fffff806`d24992b8 HdAudio!CAzMixertopoMiniport::`vftable' = +... +``` + +## See also + + +[**dt (Display Type)**](dt--display-type-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dtx%20%28Display%20Type%20-%20Extended%20Debugger%20Object%20Model%20Information%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/dump-file-targets.md b/windows-driver-docs-pr/debugger/dump-file-targets.md new file mode 100644 index 0000000000..801a57ede3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dump-file-targets.md @@ -0,0 +1,45 @@ +--- +title: Dump-File Targets +description: Dump-File Targets +ms.assetid: 83fb6753-a6c1-4899-9b06-a6331b3c31a8 +keywords: ["targets, dump files", "dump files"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dump-File Targets + + +## + + +For an introduction and overview of crash dump files, see [Crash Dump Files](crash-dump-files.md). + +### Opening Dump Files + +To open a crash dump file for use as a debugger target, use [**OpenDumpFile**](https://msdn.microsoft.com/library/windows/hardware/ff552322) or [**OpenDumpfileWide**](https://msdn.microsoft.com/library/windows/hardware/ff552324). These methods are similar to the [**.opendump**](-opendump--open-dump-file-.md) debugger command. + +**Note**   The engine doesn't completely attach to the dump file until the [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) method has been called. When a dump file is created from a process or kernel, information about the last event is stored in the dump file. After the dump file is opened, the next time execution is attempted, the engine will generate this event for the event callbacks. Only then does the dump file become available in the debugging session. See [Debugging Session and Execution Model](debugging-session-and-execution-model.md) for more details. + +  + +Additional files can be used to assist in debugging a crash dump file. The methods [**AddDumpInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff537865) and [**AddDumpInformationFileWide**](https://msdn.microsoft.com/library/windows/hardware/ff537874) register files containing page-file information to be used when the next dump file is opened. These methods must be called before the dump file is opened. [**GetNumberDumpFiles**](https://msdn.microsoft.com/library/windows/hardware/ff547887) will return the number of such files that were used when the current dump file was opened and [**GetDumpFile**](https://msdn.microsoft.com/library/windows/hardware/ff546586) will return a description of these files. + +User-mode minidump files contain several streams of information. These streams can be read using the [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operation [**DEBUG\_REQUEST\_READ\_USER\_MINIDUMP\_STREAM**](https://msdn.microsoft.com/library/windows/hardware/ff541575). + +### Creating Dump Files + +To create a crash dump file of the current target -- user-mode or kernel-mode -- use [**WriteDumpFile2**](https://msdn.microsoft.com/library/windows/hardware/ff561382). This method is similar to the [**.dump**](-dump--create-dump-file-.md) debugger command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Dump-File%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dumpchk.md b/windows-driver-docs-pr/debugger/dumpchk.md new file mode 100644 index 0000000000..7927cf1238 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dumpchk.md @@ -0,0 +1,218 @@ +--- +title: DumpChk +description: DumpChk +ms.assetid: f7431207-562b-451a-843e-1c2be038e306 +keywords: ["DumpChk"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DumpChk + + +DumpChk (the Microsoft Crash Dump File Checker tool) is a program that performs a quick analysis of a crash dump file. This enables you to see summary information about what the dump file contains. If the dump file is corrupt in such a way that it cannot be opened by a debugger, DumpChk reveals this fact. + +## Where to get DumpChk + + +DumpChk.exe is included in [Debugging Tools for Windows](index.md). + +## DumpChk command-line options + + +``` +DumpChk [-y SymbolPath] DumpFile +``` + +### Parameters + + **-y** *SymbolPath* +*SymbolPath* specifies where DumpChk is to search for symbols. Symbol information may be necessary for some dump files. It can also help to improve the information shown in the dump file by allowing symbol names to be resolved. + + *DumpFile* +*DumpFile* specifies the crash dump file that is to be analyzed. This may include an absolute or relative directory path or universal naming convention (UNC) path. If *DumpFile* contains spaces, it must be enclosed in quotation marks. + +## Using DumpChk + + +Here is an example in which the dump file is corrupt. The error shown at the end, `DebugClient cannot open DumpFile`, indicates that some kind of corruption must have occurred: + +``` +C:\Debuggers> dumpchk c:\mydir\dumpfile2.dmp + +Loading dump file c:\mydir\dumpfile2.dmp + +Microsoft (R) Windows Debugger Version 6.9.0003.113 X86 +Copyright (C) Microsoft. All rights reserved. + + +Loading Dump File [c:\mydir\dumpfile2.dmp] +Could not match Dump File signature - invalid file format +Could not open dump file [c:\mydir\dumpfile2.dmp], HRESULT 0x80004002 + "No such interface supported" +**** DebugClient cannot open DumpFile - error 80004002 +``` + +Because this display does not end with the words `Finished dump check`, the dump file is corrupt. The error message at the end explains that the dump file could not be opened. + +Note that other errors may be listed, some of which are actually benign. For example, the following error message does not represent a problem: + +``` +error 3 InitTypeRead( nt!_PEB at 7ffd5000) +``` + +Here is an example of DumpChk run on a healthy user-mode minidump. The display begins with an overall summary of the dump file, and then gives detailed information about what data is contained in the dump file: + +``` +C:\Debuggers> dumpchk c:\mydir\dumpfile1.dmp + +Loading dump file c:\mydir\dumpfile1.dmp + +Microsoft (R) Windows Debugger Version 6.9.0003.113 X86 +Copyright (C) Microsoft. All rights reserved. + + +Loading Dump File [c:\mydir\dumpfile1.dmp] +User Mini Dump File with Full Memory: Only application data is available + +Symbol search path is: srv*C:\CODE\LocalStore*\\symbols\symbols +Executable search path is: +Windows Vista Version 6000 MP (2 procs) Free x86 compatible +Product: WinNt, suite: SingleUserTS +Debug session time: Tue Jun 17 02:28:23.000 2008 (GMT-7) +System Uptime: 0 days 15:43:52.861 +Process Uptime: 0 days 0:00:26.000 +... +This dump file has an exception of interest stored in it. +The stored exception information can be accessed via .ecxr. + +----- User Mini Dump Analysis + +MINIDUMP_HEADER: +Version A793 (6903) +NumberOfStreams 12 +Flags 1826 + 0002 MiniDumpWithFullMemory + 0004 MiniDumpWithHandleData + 0020 MiniDumpWithUnloadedModules + 0800 MiniDumpWithFullMemoryInfo + 1000 MiniDumpWithThreadInfo + +Streams: +Stream 0: type ThreadListStream (3), size 00000064, RVA 000001BC + 2 threads + RVA 000001C0, ID 1738, Teb:000000007FFDF000 + RVA 000001F0, ID 1340, Teb:000000007FFDE000 +Stream 1: type ThreadInfoListStream (17), size 0000008C, RVA 00000220 + RVA 0000022C, ID 1738 + RVA 0000026C, ID 1340 +Stream 2: type ModuleListStream (4), size 00000148, RVA 000002AC + 3 modules + RVA 000002B0, 00400000 - 00438000: 'C:\CODE\TimeTest\Debug\TimeTest.exe' + RVA 0000031C, 779c0000 - 77ade000: 'C:\Windows\System32\ntdll.dll' + RVA 00000388, 76830000 - 76908000: 'C:\Windows\System32\kernel32.dll' +Stream 3: type Memory64ListStream (9), size 00000290, RVA 00001D89 + 40 memory ranges + RVA 0x2019 BaseRva + range# RVA Address Size + 0 00002019 00010000 00010000 + 1 00012019 00020000 00005000 + 2 00017019 0012e000 00002000 + + (additional stream data deleted) + +Stream 9: type UnusedStream (0), size 00000000, RVA 00000000 +Stream 10: type UnusedStream (0), size 00000000, RVA 00000000 +Stream 11: type UnusedStream (0), size 00000000, RVA 00000000 + + +Windows Vista Version 6000 MP (2 procs) Free x86 compatible +Product: WinNt, suite: SingleUserTS +kernel32.dll version: 6.0.6000.16386 (vista_rtm.061101-2205) +Debug session time: Tue Jun 17 02:28:23.000 2008 (GMT-7) +System Uptime: 0 days 15:43:52.861 +Process Uptime: 0 days 0:00:26.000 + Kernel time: 0 days 0:00:00.000 + User time: 0 days 0:00:00.000 +PEB at 7ffd9000 + InheritedAddressSpace: No + ReadImageFileExecOptions: No + BeingDebugged: Yes + ImageBaseAddress: 00400000 + Ldr 77a85d00 + Ldr.Initialized: Yes + Ldr.InInitializationOrderModuleList: 002c1e30 . 002c2148 + Ldr.InLoadOrderModuleList: 002c1da0 . 002c2138 + Ldr.InMemoryOrderModuleList: 002c1da8 . 002c2140 + Base TimeStamp Module + 400000 47959d85 Jan 21 23:38:45 2008 C:\CODE\TimeTest\Debug\TimeTest.exe + 779c0000 4549bdc9 Nov 02 02:43:37 2006 C:\Windows\system32\ntdll.dll + 76830000 4549bd80 Nov 02 02:42:24 2006 C:\Windows\system32\kernel32.dll + SubSystemData: 00000000 + ProcessHeap: 002c0000 + ProcessParameters: 002c14c0 + WindowTitle: 'C:\CODE\TimeTest\Debug\TimeTest.exe' + ImageFile: 'C:\CODE\TimeTest\Debug\TimeTest.exe' + CommandLine: '\CODE\TimeTest\Debug\TimeTest.exe' + DllPath: 'C:\CODE\TimeTest\Debug;C:\Windows\system32;C:\Windows\system; + Environment: 002c0808 + =C:=C:\CODE + =ExitCode=00000000 + ALLUSERSPROFILE=C:\ProgramData + AVENGINE=C:\PROGRA~1\CA\SHARED~1\SCANEN~1 + CommonProgramFiles=C:\Program Files\Common Files + COMPUTERNAME=EMNET + ComSpec=C:\Windows\system32\cmd.exe + configsetroot=C:\Windows\ConfigSetRoot + FP_NO_HOST_CHECK=NO + HOMEDRIVE=C: + NUMBER_OF_PROCESSORS=2 + OS=Windows_NT + Path=C:\DTFW\200804~2.113\winext\arcade;C:\Windows\system32 + PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC + PROCESSOR_ARCHITECTURE=x86 + PROCESSOR_IDENTIFIER=x86 Family 6 Model 15 Stepping 13, GenuineIntel + PROCESSOR_LEVEL=6 + PROCESSOR_REVISION=0f0d + ProgramData=C:\ProgramData + ProgramFiles=C:\Program Files + PROMPT=$P$G + PUBLIC=C:\Users\Public + RoxioCentral=C:\Program Files\Common Files\Roxio Shared\9.0\Roxio Central33\ + SESSIONNAME=Console + SystemDrive=C: + SystemRoot=C:\Windows + USERDNSDOMAIN=NORTHSIDE.COMPANY.COM + USERDOMAIN=NORTHSIDE + USERNAME=myname + USERPROFILE=C:\Users\myname + WINDBG_DIR=C:\DTFW\200804~2.113 + windir=C:\Windows + WINLAYTEST=200804~2.113 + _NT_SOURCE_PATH=C:\mysources + _NT_SYMBOL_PATH=C:\mysymbols +Finished dump check +``` + +The output begins by identifying the characteristics of the dump file - in this case, a user-mode minidump with full memory information, including application data but not operating-system data. This is followed by the symbol path being used by DumpChk, and then a summary of the dump file contents. + +Because this display ends with the words `Finished dump check`, the dump file is probably not corrupt, and can be opened by a debugger. However, more subtle forms of corrruption might still be present in the file. + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20DumpChk%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/dv--display-local-variables-.md b/windows-driver-docs-pr/debugger/dv--display-local-variables-.md new file mode 100644 index 0000000000..e131894543 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dv--display-local-variables-.md @@ -0,0 +1,116 @@ +--- +title: dv (Display Local Variables) +description: The dv command displays the names and values of all local variables in the current scope. +ms.assetid: 1b5260f7-f47c-481a-b93f-015ab9fa4b58 +keywords: ["dv (Display Local Variables) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dv (Display Local Variables) +api_type: +- NA +--- + +# dv (Display Local Variables) + + +The **dv** command displays the names and values of all local variables in the current scope. + +``` +dv [Flags] [Pattern] +``` + +## Parameters + + + *Flags* +Causes additional information to be displayed. Any of the following case-sensitive *Flags* can be included: + +**/f** <addr> +Lets you specify an arbitrary function address so that you can see what parameters and locals exist for any code anywhere. It turns off the value display and implies **/V**. The **/f** flag must be the last flag. A parameter filter pattern can still be specified after it if the string is quoted. + +**/i** +Causes the display to specify the kind of variable: local, global, parameter, function, or unknown. + +**/t** +Causes the display to include the data type for each local variable. + +**/v** +Causes the display to include the virtual memory address or register location of each local variable. + +**/V** +Same as **/v**, and also includes the address of the local variable relative to the relevant register. + +**/a** +Sorts the output by address, in ascending order. + +**/A** +Sorts the output by address, in descending order. + +**/n** +Sorts the output by name, in ascending order. + +**/N** +Sorts the output by name, in descending order. + +**/z** +Sorts the output by size, in ascending order. + +**/Z** +Sorts the output by size, in descending order. + + *Pattern* +Causes the command to only display local variables that match the specified *Pattern*. The pattern may contain a variety of wildcards and specifiers; see [String Wildcard Syntax](string-wildcard-syntax.md) for details. If *Pattern* contains spaces, it must be enclosed in quotation marks. If *Pattern* is omitted, all local variables will be displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For details on displaying and changing local variables and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +In verbose mode, the addresses of the variables are displayed as well. (This can also be done with the [**x (Examine Symbols)**](x--examine-symbols-.md) command.) + +Data structures and unfamiliar data types are not displayed in full; rather, their type name is displayed. To display the entire structure, or display a particular member of the structure, use the [**dt (Display Type)**](dt--display-type-.md) command. + +The *local context* determines which set of local variables will be displayed. By default, this context matches the current position of the program counter. For information about how this can be changed, see [Local Context](changing-contexts.md#local-context). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dv%20%28Display%20Local%20Variables%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/dx--display-visualizer-variables-.md b/windows-driver-docs-pr/debugger/dx--display-visualizer-variables-.md new file mode 100644 index 0000000000..f9a6b09802 --- /dev/null +++ b/windows-driver-docs-pr/debugger/dx--display-visualizer-variables-.md @@ -0,0 +1,254 @@ +--- +title: dx (Display Debugger Object Model Expression) +description: The dx command displays a C++ expression using the NatVis extension model. The dx command works with debugger objects. +ms.assetid: 93047911-5195-4FB9-A015-5349084EDC0A +keywords: ["dx (Display Debugger Object Model Expression) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 08/10/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- dx (Display Debugger Object Model Expression) +api_type: +- NA +--- + +# dx (Display Debugger Object Model Expression) + + +The **dx** command displays a C++ expression using the NatVis extension model. For more information about NatVis, see [Create custom views of native objects](http://msdn.microsoft.com/library/jj620914.aspx). + +``` +dx [-g|-gc #][-c #][-n|-v]-r[#] Expression[, ] +dx [{-?}|{-h}] +``` + +## Parameters + + + *Expression* +A C++ expression to be displayed. + + **-g** +Display as a data grid objects which are iterable. Each iterated element is a row in the grid and each display child of those elements is a column. This allows you to view something such as an array of structs, where each array element is displayed in a row and each field of the struct is displayed in a column. + +Left clicking a column name (where there is an available DML link) will sort by that column. If already sorted by that column, the sort order will be inverted. + +Any object which is iterable will have a right click context menu item added via DML called 'Display as Grid'. Right clicking an object in the output window and selecting this will display the object in the grid view instead of the standard tree view. + +A (+) displayed by a column name offers both a right click and left click behavior. + +- Left click takes that column and explodes it into its own table. You see the original rows plus the children of the expanded column. +- Right click provides "Expand Into Grid" which takes the column and adds it back to the current table as right most columns. + + **-gc \#** +Display as a grid and restrict grid cell sizes to specified number of (\#) characters. + + **-c \#** +Displays container continuation (skipping \# elements of the container).This option is typically used in custom output automation scenarios and provides a "…" continuation element at the bottom of the listing. + + **-n** +There are two ways that data can be rendered. Using the NatVis visualization (the default) or using the underlying native C/C++ structures. Specify the -n parameter to render the output using just the native C/C++ structures and not the NatVis visualizations. + + **-v** +Display verbose information that includes methods and other non-typical objects. + + **-r***\#* +Recursively display subtypes (fields) up to *\#* levels. If *\#* is not specified, a recursion level of one, is the default value. + + **\[<,FormatSpecifier>\]** +Use any of the following format specifiers to modify the default rendering. + +| | | +|-------------------------|------------------------------------------------------------------------------------------| +| ,x | Display ordinals in hexidecimal | +| ,d | Display ordinals in decimal | +| ,o | Display ordinals in octal | +| ,b | Display ordinals in binary | +| ,en | Display enums by name only (no value) | +| ,c | Display as single character (not a string) | +| .s | Display 8-bit strings as ASCII quoted | +| ,sb | Display 8-bit strings as ASCII unquoted | +| ,s8 | Display 8-bit strings as UTF-8 quoted | +| ,s8b | Display 8-bit strings as UTF-8 unquoted | +| ,su | Display 16-bit strings as UTF-16 quoted | +| ,sub | Display 16-bit strings as UTF-16 unqouted | +| ,! | Display objects in raw mode only (e.g.: no NatVis) | +| ,\# | Specify length of pointer/array/container as the literal value \# (replace with numeric) | +| ,\[<expression>\] | Specify length of pointer/array/container as the expression <expression> | +| ,nd | Do not find the derived (runtype) type of the object. Display static value only | + +  + + **dx** {**-?**} +Display command line help. + + **dx** {**-h**} +Displays help for objects available in the debugger. + +## Command line usage example + +The .dx settings command can be used to display information about the Debug Settings object. For more information about the debug settings objects, see [**.settings**](-settings--set-debug-settings-.md) . +``` +kd> dx -r1 Debugger.Settings +Debugger.Settings : + Display : + EngineInitialization : + Extensions : + Input : + Sources : + Symbols : + AutoSaveSettings : false +``` + +Use the -r1 recursion option to view the other Debugger objects - Sessions, Settings and State. + +``` +kd> dx -r1 Debugger +Debugger : + Sessions : + Settings : + State : +``` + +Specify the Debugger.Sessions object with the -r3 recursion option to travel further down the object chain. + +``` +kd> dx -r3 Debugger.Sessions +Debugger.Sessions : + [0] : Remote KD: KdSrv:Server=@{},Trans=@{1394:Channel=0} + Processes : + [0] : + [4] : + [304] : smss.exe + [388] : csrss.exe + [456] : wininit.exe + [468] : csrss.exe + [528] : services.exe + [536] : lsass.exe + [544] : winlogon.exe + [620] : svchost.exe + ... ... +``` + +Add the x format specifier to display the ordinal values in hexadecimal. + +``` +kd> dx -r3 Debugger.Sessions,x +Debugger.Sessions,x : + [0x0] : Remote KD: KdSrv:Server=@{},Trans=@{1394:Channel=0} + Processes : + [0x0] : + [0x4] : + [0x130] : smss.exe + [0x184] : csrss.exe + [0x1c8] : wininit.exe + [0x1d4] : csrss.exe + [0x210] : services.exe + [0x218] : lsass.exe + [0x220] : winlogon.exe + [0x26c] : svchost.exe + [0x298] : svchost.exe + [0x308] : dwm.exe + [0x34c] : nvvsvc.exe + [0x37c] : nvvsvc.exe + [0x384] : svchost.exe + ... ... +``` + +This example uses an active debug session to list the call stack of the first thread in the first process. + +``` +kd> dx -r1 Debugger.Sessions.First().Processes.First().Threads.First().Stack.Frames +Debugger.Sessions.First().Processes.First().Threads.First().Stack.Frames : + [0x0] : nt!RtlpBreakWithStatusInstruction + [0x1] : nt!KdCheckForDebugBreak + 0x7a006 + [0x2] : nt!KiUpdateRunTime + 0x42 + [0x3] : nt!KiUpdateTime + 0x129 + [0x4] : nt!KeClockInterruptNotify + 0x1c3 + [0x5] : hal!HalpTimerClockInterruptEpilogCommon + 0xa + [0x6] : hal!HalpTimerClockInterruptCommon + 0x3e + [0x7] : hal!HalpTimerClockInterrupt + 0x1cb + [0x8] : nt!KiIdleLoop + 0x1a +``` + +Use the -g option to display output as a data grid. Click on a column to sort. + +``` +kd> dx -g @$curprocess.Modules +``` + +![output from dx -g @$curprocess.modules showing columnar grid output](images/dx-grid-example.png) + +Use the -h option to display information about objects. +``` +kd> dx -h Debugger.State +Debugger.State [State pertaining to the current execution of the debugger (e.g.: user variables)] + DebuggerVariables [Debugger variables which are owned by the debugger and can be referenced by a pseudo-register prefix of @$] + PseudoRegisters [Categorizied debugger managed pseudo-registers which can be referenced by a pseudo-register prefix of @$] + UserVariables [User variables which are maintained by the debugger and can be referenced by a pseudo-register prefix of @$] +``` + +## Working around symbol file limitations with casting + +When displaying information about various Windows system variables, there are times where not all of the type information is available in the public symbols. This example illustrates this situation. + +``` +0: kd> dx nt!PsIdleProcess +Error: No type (or void) for object at Address 0xfffff800e1d50128 +``` + +The dx command supports the ability to reference the address of a variable which does not have type information. Such “address of” references are treated as “void \*” and can be cast as such. This means that if the data type is known, the following syntax can be used to display type information for the variable. + +``` +dx (Datatype *)&VariableName +``` + +For example for a nt!PsIdleProcess which has a data type of nt!\_EPROCESS, use this command. + +``` +dx (nt!_EPROCESS *)&nt!PsIdleProcess +(nt!_EPROCESS *)&nt!PsIdleProcess : 0xfffff800e1d50128 [Type: _EPROCESS *] + [+0x000] Pcb [Type: _KPROCESS] + [+0x2c8] ProcessLock [Type: _EX_PUSH_LOCK] + [+0x2d0] CreateTime : {4160749568} [Type: _LARGE_INTEGER] + [+0x2d8] RundownProtect [Type: _EX_RUNDOWN_REF] + [+0x2e0] UniqueProcessId : 0x1000 [Type: void *] + [+0x2e8] ActiveProcessLinks [Type: _LIST_ENTRY] + [+0x2f8] Flags2 : 0x218230 [Type: unsigned long] + [+0x2f8 ( 0: 0)] JobNotReallyActive : 0x0 [Type: unsigned long] +``` + +The dx command does not support switching expression evaluators with the @@ MASM syntax. For more information about expression evaluators, see [Evaluating Expressions](evaluating-expressions.md). + +## Using LINQ With the debugger objects + +LINQ syntax can be used with the debugger objects to search and manipulate data. LINQ is conceptually similar to the Structured Query Language (SQL) that is used to query databases. You can use a number of LINQ methods to search, filter and parse debug data. For information us using LINQ with the debugger objects, see [Using LINQ With the debugger objects](using-linq-with-the-debugger-objects.md). + +## Using debugger objects with NatVis and JavaScript + +For information about using debugger objects with NatVis, see [Native Debugger Objects in NatVis](native-debugger-objects-in-natvis.md). + +For information about using debugger objects with JavaScript, see [Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md). + + +## See also + +[Using LINQ With the debugger objects](using-linq-with-the-debugger-objects.md) + +[Native Debugger Objects in NatVis](native-debugger-objects-in-natvis.md) + +[Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md)  + +--- +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dx%20%28Display%20Debugger%20Object%20Model%20Expression%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md b/windows-driver-docs-pr/debugger/e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md new file mode 100644 index 0000000000..31fc62c3e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md @@ -0,0 +1,175 @@ +--- +title: e, ea, eb, ed, eD, ef, ep, eq, eu, ew, eza (Enter Values) +description: The e* commands enter into memory the values that you specify.This command should not be confused with the ~E (Thread-Specific Command) qualifier. +ms.assetid: d21b13ac-2268-4218-b562-4c466956b05d +keywords: ["e, ea, eb, ed, eD, ef, ep, eq, eu, ew, eza (Enter Values) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- e, ea, eb, ed, eD, ef, ep, eq, eu, ew, eza (Enter Values) +api_type: +- NA +--- + +# e, ea, eb, ed, eD, ef, ep, eq, eu, ew, eza (Enter Values) + + +The **e\*** commands enter into memory the values that you specify. + +This command should not be confused with the [**~E (Thread-Specific Command)**](-e--thread-specific-command-.md) qualifier. + +``` +e{b|d|D|f|p|q|w} Address [Values] +e{a|u|za|zu} Address "String" +e Address [Values] +``` + +## Parameters + + +### Syntax eD ef + + *Address* +Specifies the starting address where to enter values. The debugger replaces the value at *Address* and each subsequent memory location until all *Values* have been used. + + *Values* +Specifies one or more values to enter into memory. Multiple numeric values should be separated with spaces. If you do not specify any values, the current address and the value at that address will be displayed, and you will be prompted for input. + + *String* +Specifies a string to be entered into memory. The **ea** and **eza** commands will write this to memory as an ASCII string; the **eu** and **ezu** commands will write this to memory as a Unicode string. The **eza** and **ezu** commands write a terminal **NULL**; the **ea** and **eu** commands do not. *String* must be enclosed in quotation marks. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +This command exists in the following forms. The second characters of the **ed** and **eD** commands are case-sensitive. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandEnter

e

This enters data in the same format as the most recent e* command. (If the most recent e* command was ea, eza, eu, or ezu, the final parameter will be String and may not be omitted.)

ea

ASCII string (not NULL-terminated).

eb

Byte values.

ed

Double-word values (4 bytes).

eD

Double-precision floating-point numbers (8 bytes).

ef

Single-precision floating-point numbers (4 bytes).

ep

Pointer-sized values. This command is equivalent to ed or eq, depending on whether the target computer's processor architecture is 32-bit or 64-bit, respectively.

eq

Quad-word values (8 bytes).

eu

Unicode string (not NULL-terminated).

ew

Word values (2 bytes).

eza

NULL-terminated ASCII string.

ezu

NULL-terminated Unicode string.

+ +  + +Numeric values will be interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. The default radix can be overridden by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + +**Note**   The default radix behaves differently when C++ expressions are being used. See [Evaluating Expressions](evaluating-expressions.md) for details. + +  + +When entering byte values with the **eb** command, you can use single straight quotation marks to specify characters. If you want to include multiple characters, each must be surrounded with its own quotation marks. This allows you to enter a character string that is not terminated by a null character. For example: + +``` +eb 'h' 'e' 'l' 'l' 'o' +``` + +C-style escape characters (such as '\\0' or '\\n') may not be used with these commands. + +If you omit the *Values* parameter, you will be prompted for input. The address and its current contents will be displayed, and an **Input>** prompt will appear. You can then do any of the following: + +- Enter a new value, by typing the value and pressing ENTER. + +- Preserve the current value in memory by pressing SPACE followed by ENTER. + +- Exit from the command by pressing ENTER. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20e,%20ea,%20eb,%20ed,%20eD,%20ef,%20ep,%20eq,%20eu,%20ew,%20eza%20%28Enter%20Values%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/e.md b/windows-driver-docs-pr/debugger/e.md new file mode 100644 index 0000000000..469541c1bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/e.md @@ -0,0 +1,66 @@ +--- +title: E (Windows Debugger Glossary) +description: Glossary page - E +Robots: noindex, nofollow +ms.assetid: 1e32bd40-8c77-4c6b-913c-6ec26707ed36 +--- + +# E + + +**effective processor type** +The processor type the debugger uses when dealing with the target computer. The effective processor type affects how the debugger sets breakpoints, accesses registers, gets stack traces, and performs other processor-specific actions. + +**engine** +See debugger engine. + +**event** +The debugger engine monitors some of the events that occur in its targets. These include a breakpoint being triggered, an exception, thread and process creation, module loading, and internal debugger engine changes. + +**event filter** +A collection of rules that influence how the debugger engine proceeds after an event has occurred in a target. There are three types of event filters: specific event filters, specific exception filters, and arbitrary exception filters. + +**event callback objects** +Instances of the [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550) interface which have been registered with a client. The engine notifies the event callbacks whenever an event occurs. + +**event callbacks** +See event callback objects. + +**event process** +The process for which the last event occurred. + +**event target** +The target for which the last event occurred. + +**event thread** +The thread for which the last event occurred. + +**executing processor type** +The type of the processor in the current processor context. + +**exception** +An error condition resulting from the execution of a particular machine instruction or from the target indicating that it has encountered an error. Exceptions can be hardware or software-related errors. + +An exception is an and is identified by its . + +**exception code** +An identifier which determines the type of an exception event. + +**exception filter** +An event filter for an exception event specified by exception code. + +**extension** +See debugger extension. + +**extension command** +See debugger extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20E%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/early-critical-section-event-creation.md b/windows-driver-docs-pr/debugger/early-critical-section-event-creation.md new file mode 100644 index 0000000000..0414a0d057 --- /dev/null +++ b/windows-driver-docs-pr/debugger/early-critical-section-event-creation.md @@ -0,0 +1,62 @@ +--- +title: Early critical section event creation +description: Early critical section event creation +ms.assetid: a9453e6d-7566-4226-a950-d32d6192f8ac +keywords: ["Early critical section event creation (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Early critical section event creation + + +## + + +The **Early critical section event creation** flag creates event handles when a critical section is initialized, rather than waiting until the event is needed. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

cse

Hexadecimal value

0x10000000

Symbolic Name

FLG_CRITSEC_EVENT_CREATION

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +When Windows cannot create an event, it generates the exception during initialization and the calls to enter and leave the critical section do not fail. + +Because this flag uses a significant amount of nonpaged pool memory, use it only on very reliable systems that have sufficient memory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Early%20critical%20section%20event%20creation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---add-to-command-output.md b/windows-driver-docs-pr/debugger/edit---add-to-command-output.md new file mode 100644 index 0000000000..fc9c6d19e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---add-to-command-output.md @@ -0,0 +1,37 @@ +--- +title: Edit Add to Command Output +description: Edit Add to Command Output +ms.assetid: 6c71bdc8-bf3a-49e7-8cbe-0ed378b98413 +keywords: ["Edit Add to Command Output", "Debugger Command window, Edit Add to Command Output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Add to Command Output + + +## + + +Click **Add to Command Output** on the **Edit** menu to insert a comment into the [Debugger Command window](debugger-command-window.md). + +Type a comment into the **Text** box and then click **OK**. + +Your comment appears in the Debugger Command window and in any open log file. However, the comment does not appear in any Windows debuggers that are remotely connected to your session. + +### Additional Information + +For more information about other features of the Debugger Command window, see [Using Debugger Commands](using-debugger-commands.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Add%20to%20Command%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---breakpoints.md b/windows-driver-docs-pr/debugger/edit---breakpoints.md new file mode 100644 index 0000000000..8cbd6b48d0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---breakpoints.md @@ -0,0 +1,77 @@ +--- +title: Edit Breakpoints +description: Edit Breakpoints +ms.assetid: ca55ee25-aef3-42b1-b628-0a0e849103eb +keywords: ["Edit Breakpoints", "breakpoints, Edit Breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Breakpoints + + +## + + +Click **Breakpoints** on the **Edit** menu to display or control breakpoints. + +This command is equivalent to pressing ALT+F9. If a [source window](source-window.md) or the [disassembly window](disassembly-window.md) is not active, you can also press f9 or click the **insert or remove breakpoint (f9)** button (![screen shot of the insert or remove breakpoint button](images/tbbp.png)) on the toolbar. + +However, if a Source window or the Disassembly window is open, the **Insert or remove breakpoint (F9)** button and the F9 key set a breakpoint on the current line. (If there is already a breakpoint set at the current line, this button or key will remove the breakpoint.) + +If a statement or call spans multiple lines, WinDbg sets the breakpoint on the last line of the statement or call. You should insert the caret (^) on or before the statement to set a breakpoint for the whole statement. If the debugger cannot set a breakpoint at the current caret position, it will search in a downward direction for the next allowed position and insert the breakpoint there. + +### Dialog Box + +When you click **Breakpoints**, the **Breakpoints** dialog box appears. This dialog box displays all current breakpoint information and is presented in the following columns: + +- The breakpoint number. This number is a decimal number that you can use to refer to the breakpoint in future commands. + +- The breakpoint status. This status can be **e** (enabled) or **d** (disabled). + +- (Unresolved breakpoints only) The letter **u**. This letter appears if the breakpoint is unresolved (that is, it does not match any currently-loaded module address). For details, see [Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md). + +- The virtual address of the breakpoint. If you have enabled the loading of source line numbers, the display includes file and line number information instead of address offsets. If the breakpoint is unresolved, the address appears at the end of the listing instead of here. + +- (Processor breakpoints only) Type and size information. This information can be **e** (execute), **r** (read/write), **w** (write), or **i** (input/output). These types are followed with the size of the block, in bytes. For details, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). + +- The number of passes that are remaining until the breakpoint becomes active, followed by the initial number of passes in parentheses. The number of times that the program counter passes through the breakpoint without breaking is one less than the value of this number. Therefore, this number is never lower than 1. Note also that this number counts only the times the application executes through this point. In other words, stepping over this point does not count. After the full count has been reached, you can reset the count only by clearing and resetting the breakpoint. + +- The associated process and thread. If thread is given with three asterisks (\*\*\*), this breakpoint is not a thread-specific breakpoint. + +- The module and function, with offset, that correspond to the breakpoint address. If the breakpoint is unresolved, the breakpoint address appears here, in parentheses. If the breakpoint is set on a valid address but symbol information is missing, this column will be blank. + +- The command string that is automatically executed when this breakpoint is hit. This command string is displayed in quotation marks. If the breakpoint is hit, the commands in this command string are executed until application execution resumes. Any command that resumes program execution (such as **g** or **t**) will stop the execution of the command list. + +If you select any breakpoint, you can then click the **Remove**, **Disable**, or **Enable** button. The **Remove** button permanently removes the breakpoint. The **Disable** button temporarily deactivates the breakpoint. The **Enable** button re-enables a disabled breakpoint. + +The **Remove All** button permanently removes all breakpoints. + +You can also enter commands in the **Command** box in the following ways: + +- If you enter a [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md), **bu (Set Unresolved Breakpoint)**, **bm (Set Symbol Breakpoint)**, [**ba (Break on Access)**](ba--break-on-access-.md), [**bc (Breakpoint Clear)**](bc--breakpoint-clear-.md), [**bd (Breakpoint Disable)**](bd--breakpoint-disable-.md), or [**be (Breakpoint Enable)**](be--breakpoint-enable-.md) command, the **Command** box works as if you were entering the command in the [Debugger Command window](debugger-command-window.md). However, the command itself must be in lowercase letters. The command cannot begin with a thread specifier. If you want to use a thread specifier, enter it in the **Thread** box without the initial tilde (~). + +- If you enter any other text, the text will be treated as the argument string for a [**bu (Set Unresolved Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command. That is, the debugger prefixes your entry with **bu** and a space and then executes it as a command. + +When you are entering a new breakpoint, you can also do the following: + +- Create a thread-specific breakpoint by entering a thread specifier in the **Thread** box. Do not include the tilde (~) character that is typically prefixed to a thread specifier. + +- Create a conditional breakpoint by entering a condition in the **Condition** box. The condition can be any evaluable expression, and it will be evaluated according to the current expression syntax (see [Evaluating Expressions](evaluating-expressions.md)). For more information about these types of breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +### Additional Information + +For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and setting breakpoints in user space from a kernel debugger, see [Using Breakpoints](using-breakpoints.md). For more information about conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---clear-command-output.md b/windows-driver-docs-pr/debugger/edit---clear-command-output.md new file mode 100644 index 0000000000..3d78f992b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---clear-command-output.md @@ -0,0 +1,33 @@ +--- +title: Edit Clear Command Output +description: Edit Clear Command Output +ms.assetid: ded3de6c-4974-48d4-af65-9c4d09ba10cf +keywords: ["Edit Clear Command Output", "Debugger Command window, Edit Clear Command Output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Clear Command Output + + +## + + +Click **Clear Command Output** on the **Edit** menu to clear all of the text from the [Debugger Command window](debugger-command-window.md) and clear the command history. + +### Additional Information + +For more information about other features of the Debugger Command window, see [Using Debugger Commands](using-debugger-commands.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Clear%20Command%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---copy.md b/windows-driver-docs-pr/debugger/edit---copy.md new file mode 100644 index 0000000000..dac120c605 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---copy.md @@ -0,0 +1,37 @@ +--- +title: Edit Copy +description: Edit Copy +ms.assetid: 62e4ea69-8d8b-4a99-b0c9-314cda7e20bc +keywords: ["Edit Copy", "text, Edit Copy"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Copy + + +## + + +Click **Copy** on the **Edit** menu to copy to the clipboard any text that you have selected. + +This command is equivalent to pressing CTRL+C or CTRL+INSERT or clicking the **Copy (Ctrl+C)** button (![screen shot of the copy button](images/tbcopy.png)) on the toolbar. + +You can use the **Copy** command only with docked or tabbed windows. You can use the shortcut keys and the toolbar button with any window that supports this feature. + +### Additional Information + +For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see [Cutting and Pasting Text](cutting-and-pasting-text.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Copy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---cut.md b/windows-driver-docs-pr/debugger/edit---cut.md new file mode 100644 index 0000000000..d5aa51c38f --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---cut.md @@ -0,0 +1,37 @@ +--- +title: Edit Cut +description: Edit Cut +ms.assetid: e1cb2415-64a5-4c8a-902a-dbf78019243c +keywords: ["Edit Cut", "text, Edit Cut"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Cut + + +## + + +Click **Cut** on the **Edit** menu to delete any text that you have selected and to move it to the clipboard. + +This command is equivalent to pressing CTRL+X or SHIFT+DELETE or clicking the **Cut (Ctrl+X)** button (![screen shot of the cut button](images/tbcut.png)) on the toolbar. + +You can use the **Cut** command on the **Edit** menu only with docked or tabbed windows, but you can use the shortcut keys and the toolbar button with any window that supports this feature. + +### Additional Information + +For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see [Cutting and Pasting Text](cutting-and-pasting-text.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Cut%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---display-selected-type.md b/windows-driver-docs-pr/debugger/edit---display-selected-type.md new file mode 100644 index 0000000000..b590bcd8e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---display-selected-type.md @@ -0,0 +1,37 @@ +--- +title: Edit Display Selected Type +description: Edit Display Selected Type +ms.assetid: 45073276-df6c-47d4-b614-acd4437f5b73 +keywords: ["Edit Display Selected Type", "data types, Edit Display Selected Type"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Display Selected Type + + +## + + +Click **Display Selected Type** on the **Edit** menu to determine the data type of the current selection in the [Source window](source-window.md) and to display the type in the [Debugger Command window](debugger-command-window.md). + +This command is equivalent to pressing CTRL+SHIFT+Y or clicking **Display selected type** on the Source window's shortcut menu. + +If the selected text includes more than a single object, a syntax error or other irregular results might be displayed. If no text is selected in a Source window, you cannot use this command. + +### Additional Information + +For more information about other features of Source windows, see [Source Window](source-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Display%20Selected%20Type%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---evaluate-selection.md b/windows-driver-docs-pr/debugger/edit---evaluate-selection.md new file mode 100644 index 0000000000..f4a7b45ead --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---evaluate-selection.md @@ -0,0 +1,37 @@ +--- +title: Edit Evaluate Selection +description: Edit Evaluate Selection +ms.assetid: fa374669-509a-4b91-b5a0-79322c006910 +keywords: ["Edit Evaluate Selection"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Evaluate Selection + + +## + + +Click **Evaluate Selection** on the **Edit** menu to evaluate the current selection in the [Source window](source-window.md) and display the result in the [Debugger Command window](debugger-command-window.md). + +This command is equivalent to pressing CTRL+SHIFT+V, clicking **Evaluate selection** on the Source window's shortcut menu, or using the [**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) command together with the selected text as its argument. + +If the selected text includes more than one line, a syntax error results. If no text is selected in a Source window, you cannot use this command. + +### Additional Information + +For more information about other features of Source windows, see [Source Window](source-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Evaluate%20Selection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---find-next.md b/windows-driver-docs-pr/debugger/edit---find-next.md new file mode 100644 index 0000000000..4631d00ff0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---find-next.md @@ -0,0 +1,39 @@ +--- +title: Edit Find Next +description: Edit Find Next +ms.assetid: 0fa53035-555a-4f7f-9d15-dea60759121b +keywords: ["Edit Find Next"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Find Next + + +## + + +Click **Find Next** on the **Edit** menu to repeat the previous search and find the next match. + +This command is equivalent to pressing F3. + +To repeat the search in a backward direction, press SHIFT+F3. + +If you have not previously performed any searches, use the **Edit | Find Next** command, press F3, or press SHIFT+F3 to open the **Find** dialog box (similar to the [Edit | Find](edit---find.md) command). + +### Additional Information + +For more information about other ways of finding text in debugging information windows, see [Moving Through a Window](moving-through-a-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Find%20Next%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---find.md b/windows-driver-docs-pr/debugger/edit---find.md new file mode 100644 index 0000000000..61dbd00d9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---find.md @@ -0,0 +1,53 @@ +--- +title: Edit Find +description: Edit Find +ms.assetid: 9e3a0095-1bce-4262-a22c-584de54113cc +keywords: ["Edit Find"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Find + + +## + + +Click **Find** on the **Edit** menu to find text in the active debugging information window. + +**Note**  The active window must be the [Debugger Command window](debugger-command-window.md) or a [Source window](source-window.md). + +  + +This command is equivalent to pressing CTRL+F. + +### Dialog Box + +When you click **Find**, the **Find** dialog box appears. In this dialog box, in the **Find what** box, enter the text that you want to find. If there is already text selected, this text automatically appears in the **Find what** box. + +In the **Direction** area, click **Up** or **Down** to specify the direction of your search. The search begins wherever the cursor is in the window. You can put the cursor at any location by using the mouse pointer. + +Select **Match whole word only** if you want to search for a single whole word. (If you select this option when you search for multiple words, you always receive a failed search.)) + +Select **Match case** to perform a case-sensitive search. + +The **Find** command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations. + +After you close the **Find** dialog box, you can repeat the search in a forward direction by using the [Edit | Find Next](edit---find-next.md) command or pressing F3. You can repeat the search in a backward direction by pressing SHIFT+F3. + +### Additional Information + +For more information about other ways to find text in debugging information windows, see [Moving Through a Window](moving-through-a-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Find%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---go-to-address.md b/windows-driver-docs-pr/debugger/edit---go-to-address.md new file mode 100644 index 0000000000..a544de014f --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---go-to-address.md @@ -0,0 +1,49 @@ +--- +title: Edit Go to Address +description: Edit Go to Address +ms.assetid: 152bdbb1-87e5-4a73-a1b7-1c4997f4a41c +keywords: ["Edit Go to Address"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Go to Address + + +## + + +Click **Go to Address** on the **Edit** menu to go to an address in the target's virtual address space. + +This command is equivalent to pressing CTRL+G. + +### Dialog Box + +When you click **Go to Address**, the **View Code Offset** dialog box appears. In this dialog box, enter the address that you want to move to. This address can be an expression (such as a function, symbol, or integer memory address) or any valid address expression. If the address is ambiguous, the dialog box displays a list that contains all of the ambiguous items. + +**Note**   If you put the cursor on a line within the [Disassembly window](disassembly-window.md) or a [Source window](source-window.md) and then use the**Go to Address** command, the address of the line that you have selected will appear in the **View Code Offset** dialog box. You can use this address or replace it with any address of your choice. + +  + +After you click **OK**, the debugger moves the caret (^) to the beginning of the function or address in the Disassembly window or a Source window. + +You can use the **Go to Address** command in any window that is currently active. If the debugger is in disassembly mode, WinDbg finds the address in the Disassembly window. If the debugger is in source mode, WinDbg finds the address in a Source window. If the address cannot be found in a Source window, WinDbg finds it in the Disassembly window. If the appropriate window is not open, WinDbg opens it. + +The **Go to Address** command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations. + +### Additional Information + +For more information about other ways of finding text in debugging information windows, see [Moving Through a Window](moving-through-a-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Go%20to%20Address%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---go-to-current-instruction.md b/windows-driver-docs-pr/debugger/edit---go-to-current-instruction.md new file mode 100644 index 0000000000..ca272c7af2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---go-to-current-instruction.md @@ -0,0 +1,37 @@ +--- +title: Edit Go to Current Instruction +description: Edit Go to Current Instruction +ms.assetid: 7bc57ac1-1de6-4534-836b-132e3b072ae5 +keywords: ["Edit Go to Current Instruction"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Go to Current Instruction + + +## + + +Click **Go to Current Instruction** on the **Edit** menu to open the debugging information window that contains the current instruction and to highlight this instruction. + +This command is equivalent to pressing ALT+ASTERISK (using the ASTERISK key on the numeric keypad). + +If the current instruction corresponds to a known source file, WinDbg opens the [Source window](source-window.md) that contains this source file. If no such window exists, WinDbg opens one. The current line is highlighted. + +If the current instruction is not in a known source file and the [Disassembly window](disassembly-window.md) is open, WinDbg opens the Disassembly window and the current line is highlighted. However, if the Disassembly window is closed, the **Go to Current Instruction** command does not open it. + +This command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Go%20to%20Current%20Instruction%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---go-to-line.md b/windows-driver-docs-pr/debugger/edit---go-to-line.md new file mode 100644 index 0000000000..a5ad6d4107 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---go-to-line.md @@ -0,0 +1,41 @@ +--- +title: Edit Go to Line +description: Edit Go to Line +ms.assetid: af7f2afc-95cb-4dcd-9b74-1bd46713239f +keywords: ["Edit Go to Line"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Go to Line + + +## + + +Click **Go to Line** on the **Edit** menu to search for a specific line in the currently-active [Source window](source-window.md). If the active window is not a Source window, this command has no effect. + +This command is equivalent to pressing CTRL+L. + +### Dialog Box + +When you click **Go to Line**, the **Go to Line** dialog box appears. In this dialog box, enter the line number that you want to find and then click **OK**. The debugger will move the caret (^) to that line. If the line number is bigger than the last line in the file, the cursor will move to the end of the file. + +The **Go to Line** command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations. + +### Additional Information + +For more information about other ways of finding text in debugging information windows, see [Moving Through a Window](moving-through-a-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Go%20to%20Line%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---open-close-log-file.md b/windows-driver-docs-pr/debugger/edit---open-close-log-file.md new file mode 100644 index 0000000000..23c8c45cd6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---open-close-log-file.md @@ -0,0 +1,43 @@ +--- +title: Edit Open/Close Log File +description: Edit Open/Close Log File +ms.assetid: f63549f7-1516-48a0-8af8-38cca103215c +keywords: ["Edit Open/Close Log File", "log file, Edit Open/Close Log File"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Open/Close Log File + + +## + + +Click **Open/Close Log File** on the **Edit** menu to write to a new log file, append to an existing log file, or close an open log file. + +### Dialog Box + +When you click **Open/Close Log File**, the **Open/Close Log File** dialog box appears. This dialog box displays the current log file, if one is already open. + +If the **Log file name** box is blank, you can enter a log file name. If this file already exists, WinDbg overwrites the existing file, unless you select the **Append** check box. If you specify a file name but no path, WinDbg puts the file in the default directory that you started WinDbg from. + +If the **Log file name** box already displays a file name, you can click **Close Open Log File** to close the file. If you clear the **Log file name** box and enter a new log file name, the previous log file will be closed. + +Click **OK** to save changes, or click **Cancel** to discard changes. + +If you click **OK** when no log file name appears in the **Log file name** box, it has no effect. That is, WinDbg does not close a log file or open a log file. + +However, if a log file is already active and you click **OK** without clearing its name or selecting **Append**, WinDbg deletes the log file and uses a new file that has the same name. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Open/Close%20Log%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---paste.md b/windows-driver-docs-pr/debugger/edit---paste.md new file mode 100644 index 0000000000..3af0d8058f --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---paste.md @@ -0,0 +1,37 @@ +--- +title: Edit Paste +description: Edit Paste +ms.assetid: e03be533-5768-40f9-899b-16adbcb49de5 +keywords: ["Edit Paste", "text, Edit Paste"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Paste + + +## + + +Click **Paste** on the **Edit** menu to paste text from the clipboard to the current cursor location. + +This command is equivalent to pressing CTRL+V or SHIFT+INSERT or clicking the **Paste (Ctrl+V)** button (![screen shot of the paste button](images/tbpaste.png)) on the toolbar. + +You can use the **Paste** command only with docked or tabbed windows. But you can use the shortcut keys and the toolbar button with any window that supports this feature. + +### Additional Information + +For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see [Cutting and Pasting Text](cutting-and-pasting-text.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Paste%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---select-all.md b/windows-driver-docs-pr/debugger/edit---select-all.md new file mode 100644 index 0000000000..36a341c4c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---select-all.md @@ -0,0 +1,35 @@ +--- +title: Edit Select All +description: Edit Select All +ms.assetid: bcff336e-092a-4fa0-86b1-b08d69f9230f +keywords: ["Edit Select All", "text, Edit Select All"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Select All + + +## + + +Click **Select All** on the **Edit** menu to select all of the text in the active [Debugger Command window](debugger-command-window.md), [Disassembly window](disassembly-window.md), [Source window](source-window.md), or dialog box. + +This command is equivalent to pressing CTRL+A. + +### Additional Information + +For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see [Cutting and Pasting Text](cutting-and-pasting-text.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Select%20All%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---set-current-instruction.md b/windows-driver-docs-pr/debugger/edit---set-current-instruction.md new file mode 100644 index 0000000000..141a70470b --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---set-current-instruction.md @@ -0,0 +1,31 @@ +--- +title: Edit Set Current Instruction +description: Edit Set Current Instruction +ms.assetid: 9c881b6d-34c7-4c5c-bbfc-9a6d4c6f06e8 +keywords: ["Edit Set Current Instruction"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Set Current Instruction + + +## + + +Click **Set Current Instruction** on the **Edit** menu to change the value of the instruction pointer to the instruction that corresponds to the current line in the active [Source window](source-window.md). + +This command is equivalent to pressing CTRL+SHIFT+I or clicking **Set instruction pointer to current line** on the Source window's shortcut menu. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Set%20Current%20Instruction%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit---write-window-text-to-file.md b/windows-driver-docs-pr/debugger/edit---write-window-text-to-file.md new file mode 100644 index 0000000000..8a27efc8ba --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit---write-window-text-to-file.md @@ -0,0 +1,41 @@ +--- +title: Edit Write Window Text to File +description: Edit Write Window Text to File +ms.assetid: 7a86a8e4-7ab8-46ba-9bd5-4aef81cd1f29 +keywords: ["Edit Write Window Text to File"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit | Write Window Text to File + + +## + + +Click **Write Window Text to File** on the **Edit** menu to save all of the text in the active debugging information window to a file. + +This command is available only if the active window is the [Debugger Command window](debugger-command-window.md), [Calls window](calls-window.md), or Scratch Pad. + +### Dialog Box + +When you click **Write Windows Text to File**, the **Write Window Text to File** dialog box appears. In this dialog box, enter the name of the file where you want to save the window text. You can browse in the **Save in** list to the directory that you want or select a specific file that you want to overwrite. The default file name extension is .txt. + +Click **Save** to save the file or click **Cancel** to exit. + +### Additional Information + +For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see [Cutting and Pasting Text](cutting-and-pasting-text.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20|%20Write%20Window%20Text%20to%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/edit-menu.md b/windows-driver-docs-pr/debugger/edit-menu.md new file mode 100644 index 0000000000..cf67288405 --- /dev/null +++ b/windows-driver-docs-pr/debugger/edit-menu.md @@ -0,0 +1,67 @@ +--- +title: Edit Menu +description: Edit Menu +ms.assetid: fb3c8b71-93ba-4811-ba86-abc5aef81faa +keywords: ["Edit Menu (complete listing)", "graphical interface, edit menu"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Edit Menu + + +## + + +This section describes the following commands on the **Edit** menu of WinDbg: + +[Edit | Cut](edit---cut.md) + +[Edit | Copy](edit---copy.md) + +**Edit | Copy Formatted** + +[Edit | Paste](edit---paste.md) + +[Edit | Select All](edit---select-all.md) + +[Edit | Write Window Text to File](edit---write-window-text-to-file.md) + +**Edit | Copy Window Text to Clipboard** + +[Edit | Add to Command Output](edit---add-to-command-output.md) + +[Edit | Clear Command Output](edit---clear-command-output.md) + +[Edit | Evaluate Selection](edit---evaluate-selection.md) + +[Edit | Display Selected Type](edit---display-selected-type.md) + +[Edit | Find](edit---find.md) + +[Edit | Find Next](edit---find-next.md) + +[Edit | Go to Address](edit---go-to-address.md) + +[Edit | Go to Line](edit---go-to-line.md) + +[Edit | Go to Current Instruction](edit---go-to-current-instruction.md) + +[Edit | Set Current Instruction](edit---set-current-instruction.md) + +[Edit | Breakpoints](edit---breakpoints.md) + +[Edit | Open/Close Log File](edit---open-close-log-file.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Edit%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/elements-of-a-debugger-command-program.md b/windows-driver-docs-pr/debugger/elements-of-a-debugger-command-program.md new file mode 100644 index 0000000000..897fc85229 --- /dev/null +++ b/windows-driver-docs-pr/debugger/elements-of-a-debugger-command-program.md @@ -0,0 +1,47 @@ +--- +title: Elements of a Debugger Command Program +description: Elements of a Debugger Command Program +ms.assetid: f964e358-2f3f-4780-87ea-e1374ae861e6 +keywords: ["debugger command program, elements"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Elements of a Debugger Command Program + + +## + + +A *debugger command program* is a small application that consists of debugger commands and control flow tokens, such as **.if**, **.for**, and **.while**. (For a full list of control flow tokens and their syntax, see [Control Flow Tokens](control-flow-tokens.md).) + +You can use braces ( **{ }** ) to enclose a block of statements within a larger command block. When you enter each block, all aliases within the block are evaluated. If you later alter the value of an alias within a command block, commands after that point do not use the new alias value unless they are within a subordinate block. + +You cannot create a block by using a pair of braces. You must add a control flow token before the opening brace. If you want to create a block only to evaluate aliases, you should use the [**.block**](-block.md) token before the opening brace. + +A debugger command program can use [user-named aliases or fixed-name aliases](using-aliases.md) as its local variables. If you want to use numeric or typed variables, you can use the **$t***n*[pseudo-registers](pseudo-register-syntax.md). + +User-named aliases are evaluated only if they are not next to other text. If you want to evaluate an alias that is next to other text, use the [**${ } (Alias Interpreter)**](-------alias-interpreter-.md) token. This token has optional switches that enable you to evaluate the alias in a variety of ways. + +You can add comments to a debugger command program by using two dollar signs ([**$$ (Comment Specifier)**](-----comment-specifier-.md)). You should not insert a comment between a token and its elements (such as braces or conditions). + +**Note**   You should not use an asterisk ([**\* (Comment Line Specifier)**](----comment-line-specifier-.md)). Because comments that are specified with an asterisk do not end with a semicolon, the rest of the program is disregarded. + +  + +Typically, you should use MASM syntax within a debugger command program. When you have to use C++ elements (such as specifying a member of a structure or class), you can use the **@@c++( )** token to switch to C++ syntax for that clause. + +The **$scmp**, **$sicmp**, and **$spat** string operators in MASM syntax are particularly useful. For more information about these operators, see [MASM Numbers and Operators](masm-numbers-and-operators.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Elements%20of%20a%20Debugger%20Command%20Program%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-application-verifier.md b/windows-driver-docs-pr/debugger/enable-application-verifier.md new file mode 100644 index 0000000000..8c8bc5616b --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-application-verifier.md @@ -0,0 +1,60 @@ +--- +title: Enable application verifier +description: Enable application verifier +ms.assetid: a91e244e-e3b6-4975-8385-1da06cc3ae83 +keywords: ["Enable application verifier (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable application verifier + + +## + + +The **Enable application verifier** flag enables system features that are used for user-mode application testing, such as page heap verification, lock checks, and handle checks. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

vrf

Hexadecimal value

0x100

Symbolic Name

FLG_APPLICATION_VERIFIER

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +This flag enables only the most basic detection features. To test user-mode applications reliably, use Application Verifier (appverif.exe). For more information, see [Application Verifier](application-verifier.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20application%20verifier%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-bad-handles-detection.md b/windows-driver-docs-pr/debugger/enable-bad-handles-detection.md new file mode 100644 index 0000000000..fa295ffd20 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-bad-handles-detection.md @@ -0,0 +1,56 @@ +--- +title: Enable bad handles detection +description: Enable bad handles detection +ms.assetid: beeecb82-a270-416e-8a2a-dd64af3d052e +keywords: ["Enable bad handles detection (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable bad handles detection + + +## + + +The **Enable bad handles detection** flag raises a user-mode exception (STATUS\_INVALID\_HANDLE) whenever a user-mode process passes an invalid handle to the Object Manager. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

bhd

Hexadecimal value

0x40000000

Symbolic Name

FLG_ENABLE_HANDLE_EXCEPTIONS

Destination

System-wide registry entry, kernel flag

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20bad%20handles%20detection%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-close-exception.md b/windows-driver-docs-pr/debugger/enable-close-exception.md new file mode 100644 index 0000000000..766c7d3392 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-close-exception.md @@ -0,0 +1,60 @@ +--- +title: Enable close exception +description: Enable close exception +ms.assetid: 4089df14-3204-4a48-b67f-cf6bd53100a5 +keywords: ["Enable close exception (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable close exception + + +## + + +The **Enable close exception** flag raises a user-mode exception whenever an invalid handle is passed to the **CloseHandle** interface or related interfaces, such as **SetEvent**, that take handles as arguments. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

ece

Hexadecimal value

0x00400000

Symbolic Name

FLG_ENABLE_CLOSE_EXCEPTIONS

Destination

System-wide registry entry, kernel flag

+ +  + +**Note**   This flag is still supported, but the [Enable bad handles detection](enable-bad-handles-detection.md) flag (bhd), which performs a more comprehensive check of handle use, is preferred. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20close%20exception%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-debugging-of-win32-subsystem.md b/windows-driver-docs-pr/debugger/enable-debugging-of-win32-subsystem.md new file mode 100644 index 0000000000..9997ac233c --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-debugging-of-win32-subsystem.md @@ -0,0 +1,64 @@ +--- +title: Enable debugging of Win32 subsystem +description: Enable debugging of Win32 subsystem +ms.assetid: ea9d1c96-413e-42b7-a0c2-b114aa6de2a6 +keywords: ["Enable debugging of Win32 subsystem (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable debugging of Win32 subsystem + + +## + + +The **Enable debugging of Win32 subsystem** flag debugs the Client Server Run-time Subsystem (csrss.exe) in the NTSD debugger. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

d32

Hexadecimal value

0x20000

Symbolic Name

FLG_ENABLE_CSRDEBUG

Destination

System-wide registry entry

+ +  + +### Comments + +NTSD debugs the process by using the command **ntsd -d -p -1**. + +This flag is effective only when the [Debug initial command](debug-initial-command.md) flag (dic) or the [Debug WinLogon](debug-winlogon.md) flag (dwl) is also set. + +For details on NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20debugging%20of%20Win32%20subsystem%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-exception-logging.md b/windows-driver-docs-pr/debugger/enable-exception-logging.md new file mode 100644 index 0000000000..960a23b9ee --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-exception-logging.md @@ -0,0 +1,56 @@ +--- +title: Enable exception logging +description: Enable exception logging +ms.assetid: 3bb645f8-995a-4da8-abca-bb9ba93beb81 +keywords: ["Enable exception logging (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable exception logging + + +## + + +The **Enable exception logging** flag creates a log of exception records in the kernel run-time library. You can access the log from a kernel debugger. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

eel

Hexadecimal value

0x00800000

Symbolic Name

FLG_ENABLE_EXCEPTION_LOGGING

Destination

System-wide registry entry, kernel flag

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20exception%20logging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-free-checking.md b/windows-driver-docs-pr/debugger/enable-heap-free-checking.md new file mode 100644 index 0000000000..50a1f13802 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-free-checking.md @@ -0,0 +1,60 @@ +--- +title: Enable heap free checking +description: Enable heap free checking +ms.assetid: d97d6aac-608c-4c0a-8702-c078ed4820db +keywords: ["Enable heap free checking (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap free checking + + +## + + +The **Enable heap free checking** flag validates each heap allocation when it is freed. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

hfc

Hexadecimal value

0x20

Symbolic Name

FLG_HEAP_ENABLE_FREE_CHECK

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### See Also + +[Enable heap tail checking](enable-heap-tail-checking.md), [Enable heap parameter checking](enable-heap-parameter-checking.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20free%20checking%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-parameter-checking.md b/windows-driver-docs-pr/debugger/enable-heap-parameter-checking.md new file mode 100644 index 0000000000..b11d0e7957 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-parameter-checking.md @@ -0,0 +1,60 @@ +--- +title: Enable heap parameter checking +description: Enable heap parameter checking +ms.assetid: e9c7a2e3-8e43-45e3-948b-6154da1359e2 +keywords: ["Enable heap parameter checking (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap parameter checking + + +## + + +The **Enable heap parameter checking** flag verifies selected aspects of the heap whenever a heap function is called. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

hpc

Hexadecimal value

0x40

Symbolic Name

FLG_HEAP_VALIDATE_PARAMETERS

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### See Also + +[Enable heap validation on call](enable-heap-validation-on-call.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20parameter%20checking%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-tagging-by-dll.md b/windows-driver-docs-pr/debugger/enable-heap-tagging-by-dll.md new file mode 100644 index 0000000000..07a9be5573 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-tagging-by-dll.md @@ -0,0 +1,64 @@ +--- +title: Enable heap tagging by DLL +description: Enable heap tagging by DLL +ms.assetid: d8f8f6f6-7365-4208-834f-3f5ccacdb7b6 +keywords: ["Enable heap tagging by DLL (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap tagging by DLL + + +## + + +The **Enable heap tagging by DLL** flag assigns a unique tag to heap allocations created by the same DLL. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

htd

Hexadecimal value

0x8000

Symbolic Name

FLG_HEAP_ENABLE_TAG_BY_DLL

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +You can display the tag by using the [**!heap**](-heap.md) debugger extension with the -t parameter. + +### See Also + +[Enable heap tagging](enable-heap-tagging.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20tagging%20by%20DLL%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-tagging.md b/windows-driver-docs-pr/debugger/enable-heap-tagging.md new file mode 100644 index 0000000000..cde6109146 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-tagging.md @@ -0,0 +1,64 @@ +--- +title: Enable heap tagging +description: Enable heap tagging +ms.assetid: be877811-075c-4019-81dd-73a134d5fb81 +keywords: ["Enable heap tagging (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap tagging + + +## + + +The **Enable heap tagging** flag assigns unique tags to heap allocations. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

htg

Hexadecimal value

0x800

Symbolic Name

FLG_HEAP_ENABLE_TAGGING

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +You can display the tag by using the [**!heap**](-heap.md) debugger extension with the -t parameter. + +### See Also + +[Enable heap tagging by DLL](enable-heap-tagging-by-dll.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20tagging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-tail-checking.md b/windows-driver-docs-pr/debugger/enable-heap-tail-checking.md new file mode 100644 index 0000000000..bcc4a50a4c --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-tail-checking.md @@ -0,0 +1,64 @@ +--- +title: Enable heap tail checking +description: Enable heap tail checking +ms.assetid: d71b4567-55e7-49e6-a791-a292ad477c10 +keywords: ["Enable heap tail checking (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap tail checking + + +## + + +The **Enable heap tail checking** flag checks for buffer overruns when the heap is freed. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

htc

Hexadecimal value

0x10

Symbolic Name

FLG_HEAP_ENABLE_TAIL_CHECK

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +This flag adds a short pattern to the end of each allocation. The Windows heap manager detects the pattern when the block is freed and, if the block was modified, the heap manager breaks into the debugger. + +### See Also + +[Enable heap free checking](enable-heap-free-checking.md), [Enable heap parameter checking](enable-heap-parameter-checking.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20tail%20checking%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-heap-validation-on-call.md b/windows-driver-docs-pr/debugger/enable-heap-validation-on-call.md new file mode 100644 index 0000000000..dfa8ece1db --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-heap-validation-on-call.md @@ -0,0 +1,64 @@ +--- +title: Enable heap validation on call +description: Enable heap validation on call +ms.assetid: 779871e0-f8b9-4eb5-9869-8df67586ffab +keywords: ["Enable heap validation on call (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable heap validation on call + + +## + + +The **Enable heap validation on call** flag validates the entire heap each time a heap function is called. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

hvc

Hexadecimal value

0x80

Symbolic Name

FLG_HEAP_VALIDATE_ALL

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +To avoid the high overhead associated with this flag, use the **HeapValidate** function instead of setting this flag, especially at critical junctures, such as when the heap is destroyed. However, this flag is useful for detecting random corruption in a pool. + +### See Also + +[Enable heap parameter checking](enable-heap-parameter-checking.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20heap%20validation%20on%20call%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-loading-of-kernel-debugger-symbols.md b/windows-driver-docs-pr/debugger/enable-loading-of-kernel-debugger-symbols.md new file mode 100644 index 0000000000..357bc905e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-loading-of-kernel-debugger-symbols.md @@ -0,0 +1,60 @@ +--- +title: Enable loading of kernel debugger symbols +description: Enable loading of kernel debugger symbols +ms.assetid: ce047073-9cfd-4ab2-bd58-48a2acc55351 +keywords: ["Enable loading of kernel debugger symbols (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable loading of kernel debugger symbols + + +## + + +The **Enable loading of kernel debugger symbols** flag loads kernel symbols into the kernel memory space the next time Windows starts. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

ksl

Hexadecimal value

0x40000

Symbolic Name

FLG_ENABLE_KDEBUG_SYMBOL_LOAD

Destination

System-wide registry entry, kernel flag

+ +  + +### Comments + +The kernel symbols are used in kernel profiling and by advanced kernel debugging tools. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20loading%20of%20kernel%20debugger%20symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-object-handle-type-tagging.md b/windows-driver-docs-pr/debugger/enable-object-handle-type-tagging.md new file mode 100644 index 0000000000..33f483623e --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-object-handle-type-tagging.md @@ -0,0 +1,56 @@ +--- +title: Enable object handle type tagging +description: Enable object handle type tagging +ms.assetid: 7a9e96c3-7ef7-4a23-9602-a09ff9b3d02f +keywords: ["Enable object handle type tagging (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable object handle type tagging + + +## + + +The **Enable object handle type tagging** flag appears in GFlags, but it has no effect on Windows. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

eot

Hexadecimal value

0x01000000

Symbolic Name

FLG_ENABLE_HANDLE_TYPE_TAGGING

Destination

System-wide registry entry, kernel flag

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20object%20handle%20type%20tagging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-page-heap.md b/windows-driver-docs-pr/debugger/enable-page-heap.md new file mode 100644 index 0000000000..77e19d71e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-page-heap.md @@ -0,0 +1,66 @@ +--- +title: Enable page heap +description: Enable page heap +ms.assetid: b889b7b7-721c-4ecf-bf59-c1ccc0bc735d +keywords: ["Enable page heap (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable page heap + + +## + + +The **Enable page heap** flag turns on page heap verification, which monitors dynamic heap memory operations, including allocate and free operations, and causes a debugger break when the verifier detects a heap error. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

hpa

Hexadecimal value

0x02000000

Symbolic Name

FLG_HEAP_PAGE_ALLOCS

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +This option enables full page heap verification when set for image files and standard page heap verification when set in the system registry or as a kernel flag. + +- *Full page heap verification* (for **/i**) places a zone of reserved virtual memory at the end of each allocation. + +- *Standard page heap verification* (for **/r** or **/k**) places random patterns at the end of an allocation and examines the patterns when a heap block is freed. + +Setting this flag for an image file is the same as typing **gflags /p /enable** *ImageFile* **/full** for the image file at the command line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20page%20heap%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-pool-tagging.md b/windows-driver-docs-pr/debugger/enable-pool-tagging.md new file mode 100644 index 0000000000..ff2ffce2cc --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-pool-tagging.md @@ -0,0 +1,69 @@ +--- +title: Enable pool tagging +description: Enable pool tagging +ms.assetid: e88f97a0-a8c3-4162-871a-b78671b902bb +keywords: ["Enable pool tagging (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable pool tagging + + +## + + +The **Enable pool tagging** flag collects data and calculates statistics about pool memory allocations sorted by pool tag value. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

ptg

Hexadecimal value

0x400

Symbolic Name

FLG_POOL_ENABLE_TAGGING

Destination

System-wide registry entry

+ +  + +### Comments + +This flag is permanently set in Windows Server 2003 and later versions of Windows. On these systems, the **Enable pool tagging** check box in the Global Flags dialog box is dimmed and commands to enable or disable pool tagging fail. + +Use **ExAllocatePoolWithTag** or **ExAllocatePoolWithQuotaTag** to set the tag value. When no tag value is specified (**ExAllocatePool**, **ExAllocatePoolWithQuota**), Windows creates a tag with the default value of "None." Because data for all allocations with a "None" tag is combined, you cannot distinguish the data for a specific allocation. For information about these routines, see the Windows Driver Kit (WDK). + +In Windows XP and earlier systems, this flag also directs Windows to attach a pool tag even when the pool memory is allocated by using **ExAllocatePoolWithQuotaTag**. Otherwise, the tag bytes are used to store the quota values. In Windows Server 2003, tag values and quota values are stored in separate fields that are attached to every pool memory allocation. + +**Note**   To display the data that Windows collects about a tagged allocation, use PoolMon, a tool that is included in the Windows Driver Kit. +The description of the **Enable Pool Tagging** flag in the Windows XP Support Tools documentation is incomplete. This flag directs Windows to collect and process data by tag value. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20pool%20tagging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-silent-process-exit-monitoring.md b/windows-driver-docs-pr/debugger/enable-silent-process-exit-monitoring.md new file mode 100644 index 0000000000..50b00c36c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-silent-process-exit-monitoring.md @@ -0,0 +1,50 @@ +--- +title: Enable silent process exit monitoring +description: Enable silent process exit monitoring +ms.assetid: 3FEA9660-541B-42D0-B020-CECEBF14BB4D +--- + +# Enable silent process exit monitoring + + +## + + +The **Enable silent process exit monitoring** flag enables silent exit monitoring for a process. + + ++++ + + + + + + + + + + + + + + +

Hexadecimal value

0x200

Symbolic Name

FLG_MONITOR_SILENT_PROCESS_EXIT

Destination

Image file registry entry

+ +  + +### Comments + +For more information about monitoring a process for silent exit, see [Monitoring Silent Process Exit](registry-entries-for-silent-process-exit.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20silent%20process%20exit%20monitoring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enable-system-critical-breaks.md b/windows-driver-docs-pr/debugger/enable-system-critical-breaks.md new file mode 100644 index 0000000000..21e2b5fd7a --- /dev/null +++ b/windows-driver-docs-pr/debugger/enable-system-critical-breaks.md @@ -0,0 +1,62 @@ +--- +title: Enable system critical breaks +description: Enable system critical breaks +ms.assetid: f13372b9-604e-4ea5-96e2-d8b7e916c8e5 +keywords: ["Enable system critical breaks (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enable system critical breaks + + +## + + +The **Enable system critical breaks** flag forces a system break into the debugger. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

scb

Hexadecimal value

0x100000

Symbolic Name

FLG_ENABLE_SYSTEM_CRIT_BREAKS

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +When set for a process (image file), this flag forces a system break into the debugger whenever the specified process stops abnormally. This flag is effective only when the process calls the **RtlSetProcessBreakOnExit** and **RtlSetThreadBreakOnExit** interfaces. + +When set system-wide (registry or kernel flag), this flag forces a system break into the debugger whenever processes that have called the **RtlSetProcessBreakOnExit** and **RtlSetThreadBreakOnExit** interfaces stop abnormally. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enable%20system%20critical%20breaks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enabling-a-kernel-mode-dump-file.md b/windows-driver-docs-pr/debugger/enabling-a-kernel-mode-dump-file.md new file mode 100644 index 0000000000..1826520ca3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enabling-a-kernel-mode-dump-file.md @@ -0,0 +1,53 @@ +--- +title: Enabling a Kernel-Mode Dump File +description: Enabling a Kernel-Mode Dump File +ms.assetid: 4faf389f-764e-4439-9e45-fdd53890b0d1 +keywords: ["dump file, enabling kernel-mode dump file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling a Kernel-Mode Dump File + + +## + + +During a system crash, the Windows crash dump settings determine whether a dump file will be created, and if so, what size the dump file will be. + +The Windows Control Panel controls the kernel-mode crash dump settings. Only a system administrator can modify these settings. + +To change these settings, go to **Control Panel > System and Security > System**. Click **Advanced system settings**. Under **Startup and Recovery**, click **Settings**. + +You will see the following dialog box: + +![screen shot of the startup and recovery dialog box](images/crashpanel.png) + +Under **Write Debugging Information**, you can specify a kernel-mode dump file setting. Only one dump file can be created for any given crash. See [Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) for a description of different dump file settings. + +You can also select or deselect the **Write an event to the system log** and **Automatically restart** options. + +The settings that you select will apply to any kernel-mode dump file created by a system crash, regardless of whether the system crash was accidental or whether it was caused by the debugger. See [Forcing a System Crash](forcing-a-system-crash.md) for details on causing a deliberate crash. + +However, these settings do not affect dump files created by the [**.dump**](-dump--create-dump-file-.md) command. See [Creating a Dump File Without a System Crash](creating-a-dump-file-without-a-system-crash.md) for details on using this command. + +## Related topics + + +[Kernel-Mode Dump Files](kernel-mode-dump-files.md) + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enabling%20a%20Kernel-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing-by-setting-registry-values.md b/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing-by-setting-registry-values.md new file mode 100644 index 0000000000..dcbad86756 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing-by-setting-registry-values.md @@ -0,0 +1,219 @@ +--- +title: Enabling NDIS Debug Tracing By Setting Registry Values +description: Enabling NDIS Debug Tracing By Setting Registry Values +ms.assetid: ae01f546-0636-4e67-bfc7-229c3cc24b27 +keywords: ["NDIS debugging, debug tracing, setting registry values"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling NDIS Debug Tracing By Setting Registry Values + + +You can enable different levels of debug tracing in various NDIS components by editing the registry. Typically, you should add the following entries and values to the **HKLM\\SYSTEM\\CurrentControlSet\\Services\\NDIS\\Parameters** registry key: + +``` +"DebugLevel"=dword:00000000 +"DebugSystems"=dword:000030F3 +"DebugBreakPoint"=dword:00000001 +``` + +The following values are acceptable for **DebugBreakPoint**, **DebugLevel** and **DebugSystems**: + +**DebugBreakPoint** +Controls whether an NDIS driver will automatically break into the debugger. If this value is set to 1, NDIS will break into the debugger when a driver enters Ndis.sys's **DriverEntry** function. + +**DebugLevel** +Selects the level or amount of debug tracing in the NDIS components that you select with the **DebugSystems** value. The following values specify levels that you can select: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LevelDescriptionValue

DBG_LEVEL_INFO

All available debug information. This is the highest level of trace.

0x00000000

DBG_LEVEL_LOG

Log information.

0x00000800

DBG_LEVEL_WARN

Warnings.

0x00001000

DBG_LEVEL_ERR

Errors.

0x00002000

DBG_LEVEL_FATAL

Fatal errors, which can cause the operating system to crash. This is the lowest level of trace.

0x00003000

+ +  + +**DebugSystems** +Enables debug tracing for specified NDIS components. This corresponds to using the [**!ndiskd.dbgsystems**](-ndiskd-dbgsystems.md) extension. The following values specify the NDIS components that you can select: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentDescriptionValue

DBG_COMP_INIT

Handles adapter initialization.

0x00000001

DBG_COMP_CONFIG

Handles adapter configuration.

0x00000002

DBG_COMP_SEND

Handles sending data over the network.

0x00000004

DBG_COMP_RECV

Handles receiving data from the network.

0x00000008

DBG_COMP_PROTOCOL

Handles protocol operations.

0x00000010

DBG_COMP_BIND

Handles binding operations.

0x00000020

DBG_COMP_BUSINFO

Handles bus queries.

0x00000040

DBG_COMP_REG

Handles registry operations.

0x00000080

DBG_COMP_MEMORY

Handles memory management.

0x00000100

DBG_COMP_FILTER

Handles filter operations.

0x00000200

DBG_COMP_REQUEST

Handles requests.

0x00000400

DBG_COMP_WORK_ITEM

Handles work-item operations.

0x00000800

DBG_COMP_PNP

Handles Plug and Play operations.

0x00001000

DBG_COMP_PM

Handles power management operations.

0x00002000

DBG_COMP_OPENREF

Handles operations that open reference objects.

0x00004000

DBG_COMP_LOCKS

Handles locking operations.

0x00008000

DBG_COMP_RESET

Handles resetting operations.

0x00010000

DBG_COMP_WMI

Handles Windows Management Instrumentation operations.

0x00020000

DBG_COMP_CO

Handles Connection-Oriented NDIS.

0x00040000

DBG_COMP_REF

Handles reference operations.

0x00080000

DBG_COMP_ALL

Handles all NDIS components.

0xFFFFFFFF

+ +  + +You can select more than one NDIS component. If more than one component is selected, combine the data values with an OR operator. For example, to select DBG\_COMP\_PNP, DBG\_COMP\_PM, DBG\_COMP\_INIT and DBG\_COMP\_CONFIG, you would combine the corresponding values (0x1000, 0x2000, 0x1, and 0x2) to obtain the value 0x3003, and then set it in the registry thus: + +``` +"DebugSystems"=dword:00003003 +``` + +Whenever you change registry values for debug tracing, you must restart your computer for the new settings to take effect. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enabling%20NDIS%20Debug%20Tracing%20By%20Setting%20Registry%20Values%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing.md b/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing.md new file mode 100644 index 0000000000..d6c6ad8969 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enabling-ndis-debug-tracing.md @@ -0,0 +1,30 @@ +--- +title: Enabling NDIS Debug Tracing +description: Enabling NDIS Debug Tracing +ms.assetid: 4ca3c246-3e73-46fb-93a5-ea376788e330 +keywords: ["NDIS debugging, debug tracing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling NDIS Debug Tracing + + +NDIS debug tracing is the primary method for debugging NDIS drivers. When you set up NDIS debug tracing, you are actually enabling one or more levels of DbgPrint statements with NDIS. The resulting information is sufficient for debugging most network driver problems. + +You can enable debug tracing by setting appropriate registry values. For details, see [Enabling NDIS Debug Tracing By Setting Registry Values](enabling-ndis-debug-tracing-by-setting-registry-values.md). + +Setting registry values to enable debug tracing works even if the host computer does not have the checked version of the Ndis.sys symbols installed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enabling%20NDIS%20Debug%20Tracing%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enabling-postmortem-debugging.md b/windows-driver-docs-pr/debugger/enabling-postmortem-debugging.md new file mode 100644 index 0000000000..649fccf21d --- /dev/null +++ b/windows-driver-docs-pr/debugger/enabling-postmortem-debugging.md @@ -0,0 +1,335 @@ +--- +title: Enabling Postmortem Debugging +description: This topic covers how to enable postmortem debugging +ms.assetid: ae116b60-fed2-4e1d-98a8-9fe83f460c50 +keywords: debugging. debug, Windbg, postmortem debugging, just-in-time debugging, JIT debugging, AeDebug registry key +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling Postmortem Debugging + + +## User Mode Exception Handling + + +**Exceptions and Breakpoints** + +The most common application errors are called exceptions. These include access violations, division-by-zero errors, numerical overflows, CLR exceptions, and many other kinds of errors. Applications can also cause breakpoint interrupts. These occur when Windows is unable to run the application (for example, when a necessary module cannot be loaded) or when a breakpoint is encountered. Breakpoints can be inserted into the code by a debugger, or invoked through a function such as [**DebugBreak**](https://msdn.microsoft.com/library/windows/desktop/ms679297). + +**Exception Handlers Precedence** + +Based on configuration values and which debuggers are active, Windows handles user-mode errors in a variety of ways. The following sequence shows the precedence used for user mode error handling: + +1. If a user-mode debugger is currently attached to the faulting process, all errors will cause the target to break into this debugger. + + As long as the user-mode debugger is attached, no other error-handling methods will be used -- even if the [**gn (Go With Exception Not Handled)**](gn--gn--go-with-exception-not-handled-.md) command is used. + +2. If no user-mode debugger is attached and the executing code has its own exception handling routines (for example, **try - except**), this exception handling routine will attempt to deal with the error. + +3. If no user-mode debugger is attached, and Windows has an open kernel-debugging connection, and the error is a breakpoint interrupt, Windows will attempt to contact the kernel debugger. + + Kernel debugging connections must be opened during Windows' boot process. If you wish to prevent a user-mode interrupt from breaking into the kernel debugger, you can use the KDbgCtrl utility with the **-du** parameter. For details on how to configure kernel-debugging connections and how to use KDbgCtrl, see [Getting Set Up for Debugging](getting-set-up-for-debugging.md). + + In the kernel debugger, you can use [**gh (Go With Exception Handled)**](gh--go-with-exception-handled-.md) to disregard the error and continue running the target. You can use [**gn (Go With Exception Not Handled)**](gn--gn--go-with-exception-not-handled-.md) to bypass the kernel debugger and go on to step 4. + +4. If the conditions in steps 1, 2, and 3 do not apply, Windows will activate a debugging tool configured in the AeDebug registry values. Any program can be selected in advance as the tool to use in this situation. The chosen program is referred to as the *postmortem debugger*. + +5. If the conditions in steps 1, 2, and 3 do not apply, and there is no postmortem debugger registered, Windows Error Reporting (WER) displays a message and provides solutions if any are available. WER also writes a memory dump file if the appropriate values are set in the Registry. For more information, see [Using WER](http://go.microsoft.com/fwlink/p?LinkID=257799) and [Collecting User-Mode Dumps](http://go.microsoft.com/fwlink/p?LinkID=257798). + +**DebugBreak Function** + +If a postmortem debugger has been installed, you can deliberately break into the debugger from a user-mode application by calling the **DebugBreak** function. + +## Specifying a Postmortem Debugger + + +This section describes how to configure tools such as WinDbg as the postmortem debugger. Once configured, the postmortem debugger will be automatically started whenever an application crashes. + +**Post Mortem Debugger Registry Keys** + +Windows Error Reporting (WER) creates the postmortem debugger process using the values set in the AeDebug registry key. + +**HKLM**\\**Software**\\**Microsoft**\\**Windows NT**\\**CurrentVersion**\\**AeDebug** + +There are two primary registry values of interest, *Debugger* and *Auto*. The *Debugger* registry value specifies the command line for the postmortem debugger. The *Auto* registry value specifies if the postmortem debugger is automatically started, or if a confirmation message box is presented first. + +**Debugger (REG\_SZ)** +This REG\_SZ value specifies the debugger that will handle postmortem debugging. + +The full path to the debugger must be listed unless the debugger is located in a directory that is in the default path. + +The command line is generated from the Debugger string via a printf style call that includes 3 parameters. Although the order is fixed, there is no requirement to use any or all of the available parameters. + +DWORD (%ld) - Process ID of the target process. + +DWORD (%ld) - Event Handle duplicated into the postmortem debugger process. If the postmortem debugger signals the event, WER will continue the target process without waiting for the postmortem debugger to terminate. The event should only be signaled if the issue has been resolved. If the postmortem debugger terminates without signaling the event, WER continues the collection of information about the target processes. + +void\* (%p) - Address of a JIT\_DEBUG\_INFO structure allocated in the target process’s address space. The structure contains additional exception information and context. + +**Auto (REG\_SZ)** +This REG\_SZ value is always either **0** or **1**. + +If **Auto** is set to **0**, a confirmation message box is displayed prior to postmortem debugging process being started. + +If **Auto** is set to **1**, the postmortem debugger is immediately created. + +When you manually edit the registry, do so very carefully, because improper changes to the registry may not allow Windows to boot. + +**Example Command Line Usage** + +Many postmortem debuggers use a command line that includes -p and -e switches to indicate the parameters are a PID and Event (respectively). For example, installing WinDbg via windbg.exe -I creates the following values: + +``` +Debugger = "\WinDbg -p %ld -e %ld -g" +Auto = 1 +``` + +There is flexibility in how the WER %ld %ld %p parameters can be used. For example. there is no requirement to specify any switches around or between the WER parameters. For example, installing [Windows Sysinternals ProcDump](https://technet.microsoft.com/sysinternals/dd996900.aspx) using procdump.exe -i creates the following values with no switches between the WER %ld %ld %p parameters: + +``` +Debugger = "\procdump.exe" -accepteula -j "c:\Dumps" %ld %ld %p +Auto = 1 +``` + +**32 and 64 bit Debuggers** + +On a 64-bit platform, the Debugger (REG\_SZ) and Auto (REG\_SZ) registry values are defined individually for 64-bit and 32-bit applications. An additional Windows on Windows (WOW) key is used to store the 32 bit application post mortem debugging values. + +**HKLM**\\**Software**\\**Wow6432Node**\\**Microsoft**\\**Windows NT**\\**CurrentVersion**\\**AeDebug** + +On a 64-bit platform, use a 32-bit post-mortem debugger for 32-bit processes and a 64-bit debugger for 64-bit processes. This avoids a 64-bit debugger focusing on the WOW64 threads, instead of the 32-bit threads, in a 32-bit process. + +For many postmortem debuggers, including the Debugging Tools for Windows postmortem debuggers, this involves running the installation command twice; once with the x86 version and once with the x64 version. For example, to use WinDbg as the interactive postmortem debugger, the windbg.exe -I command would be run twice, once for each version. + +64-bit Installation: + +C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\windbg.exe –I + +This updates the registry key with these values. + +``` +HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug +Debugger = "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\windbg.exe" -p %ld -e %ld –g +``` + +32-bit Installation: + +C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x86\\windbg.exe –I + +This updates the registry key with these values. + +``` +HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug +Debugger = "C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\windbg.exe" -p %ld -e %ld –g +``` + +## Configuring Post Mortem Debuggers + + +### Debugging Tools for Windows + +The Debugging Tools for Windows debuggers all support being set as the postmortem debugger. The install command intends for the process to be debugged interactively. + +**WinDbg** + +To set the postmortem debugger to WinDbg, run **windbg -I**. (The **I** must be capitalized.) This command will display a success or failure message after it is used. To work with both 32 and 64 bit applications, run the command for the both the 64 and 32 debuggers. + +``` +C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\windbg.exe –I +C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\windbg.exe –I +``` + +This how the how the AeDebug registry entry will be configured when **windbg -I** is run. + +``` +Debugger = "\WinDbg -p %ld -e %ld -g" +Auto = 1 +``` + +In the examples, *<Path>* is the directory where the debugger is located. + +The -p and -e parameters pass the Process ID and Event, as discussed previously. + +The **-g** passes the g (Go) command to WinDbg and continues execution from the current instruction. + +**Note**   +There is a significant issue passing the g (Go) command. The issue with this approach, is that exceptions do not always repeat, typically, because of a transient condition that no longer exists when the code is restarted. For more information about this issue, see [**.jdinfo (Use JIT\_DEBUG\_INFO)**](-jdinfo--use-jit-debug-info-.md). + +To avoid this issue, use .jdinfo or .dump /j. This approach allows the debugger to be in the context of the code failure of interest. For more information, see [Just In Time (JIT) Debugging](#jit) later in this topic. + +  + +**CDB** + +To set the postmortem debugger to CDB, run **cdb -iae** (Install AeDebug) or **cdb -iaec** *KeyString* (Install AeDebug with Command). + +``` +C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe -iae +C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe -iae +``` + +When the **-iaec** parameter is used, *KeyString* specifies a string to be appended to the end of command line used to launch the postmortem debugger. If *KeyString* contains spaces, it must be enclosed in quotation marks. + +``` +C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe -iaec [KeyString] +C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe -iaec [KeyString] +``` + +This command display nothing if it succeeds, and an error message if it fails. + +**NTSD** + +To set the postmortem debugger to NTSD, run **ntsd -iae** (Install AeDebug) or **ntsd -iaec** *KeyString* (Install AeDebug with Command). + +``` +C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\ntsd.exe -iae +C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\ntsd.exe -iae +``` + +When the **-iaec** parameter is used, *KeyString* specifies a string to be appended to the end of command line used to launch the postmortem debugger. If *KeyString* contains spaces, it must be enclosed in quotation marks. + +``` +C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\ntsd.exe -iaec [KeyString] +C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\ntsd.exe -iaec [KeyString] +``` + +This command display nothing if it succeeds, and an error to a new console window on failure. + +**Note**  Because the -p %ld -e %ld -g parameters always appear first on the command line of the postmortem debugger, you should not use the -iaec switch to specify the -server parameter because -server will not work unless it appears first on the command line. To install a postmortem debugger that includes this parameter, you must edit the registry manually. + +  + +### Visual Studio JIT Debugger + +If Visual Studio has been installed, vsjitdebugger.exe will be registered as the post mortem debugger. The Visual Studio JIT Debugger intends for the process to be debugged interactively. + +``` +Debugger = "C:\WINDOWS\system32\vsjitdebugger.exe" -p %ld -e %ld +``` + +If Visual Studio is updated or re-installed, this entry will be re-written, overwriting any alternate values set. + +### Window Sysinternals ProcDump + +The Windows Sysinternals ProcDump utility can also be used for postmortem dump capture. For more information about using and downloading ProcDump, see [ProcDump](https://technet.microsoft.com/sysinternals/dd996900.aspx) on TechNet. + +Like the [**.dump**](-dump--create-dump-file-.md) WinDbg command, ProcDump is able to be capture a dump of the crash non-interactively. The capture may occur in any Windows system session. + +ProcDump exits when the dump file capture completes, WER then reports the failure and the faulting process is terminated. + +Use procdump -i to install procdump and -u to uninstall ProcDump for both the 32 and 64 bit post mortem debugging. + +``` +\procdump.exe -i +``` + +The install and uninstall commands output the registry values modified on success, and the errors on failure. + +The ProcDump command line options in the registry are set to: + +``` +Debugger = \ProcDump.exe -accepteula -j "" %ld %ld %p +``` + +ProcDump uses all 3 parameters - PID, Event and JIT\_DEBUG\_INFO. For more information on the JIT\_DEBUG\_INFO parameter, see [Just In Time (JIT) Debugging](#jit) below. + +The size of dump captured defaults to Mini (process/threads/handles/modules/address space) without a size option set, MiniPlus (Mini plus MEM\_PRIVATE pages) with -mp set, or Full (all memory - equivalent to ".dump /mA") with -ma set. + +For systems with sufficient drive space, a Full (-ma) capture is recommended. + +Use -ma with the -i option to specify an all memory capture. Optionally, provide a path for the dump files. + +``` +\procdump.exe -ma -i c:\Dumps +``` + +For systems with limited drive space, a MiniPlus (-mp) capture is recommended. + +``` +\procdump.exe -mp -i c:\Dumps +``` + +The folder to save the dump file to is optional. The default is the current folder. The folder should secured with an ACL that is equal or better than what is used for C:\\Windows\\Temp. For more information on managing security related to folders, see [Security During Postmortem Debugging](security-during-postmortem-debugging.md). + +To uninstall ProcDump as the postmortem debugger, and restore the previous settings, use the -u (Uninstall) option. + +``` +\procdump.exe -u +``` + +The install and uninstall commands set both the 64-bit and 32-bit values on 64-bit platforms. + +ProcDump is a "packed" executable containing both the 32-bit and 64-bit version of application - as such, the same executable is used for both 32-bit and 64-bit. When ProcDump runs, it automatically switches the version, if the version running doesn't match the target process. + +## Just In Time (JIT) Debugging + + +**Setting Context to the Faulting Application** + +As discussed previously, it is very desirable to set the context to the exception that caused the crash using the JIT\_DEBUG\_INFO parameter. For more information about this, see [**.jdinfo (Use JIT\_DEBUG\_INFO)**](-jdinfo--use-jit-debug-info-.md). + +**Debugging Tools for Windows** + +This example shows how to edit the registry to run an initial command (-c) that uses the .jdinfo <address> command to display the additional exception information, and change the context to the location of the exception (similar to how .ecxr is used set the context to the exception record). + +``` +Debugger = "\windbg.exe -p %ld -e %ld -c ".jdinfo 0x%p" +Auto = 1 +``` + +The %p parameter is the address of a JIT\_DEBUG\_INFO structure in the target process’s address space. The %p parameter is pre-appended with 0x so that it is interpreted as a hex value. For more information, see [**.jdinfo (Use JIT\_DEBUG\_INFO)**](-jdinfo--use-jit-debug-info-.md). + +To debug a mix of 32 and 64 bit apps, configure both the 32 and 64 bit registry keys (described above), setting the proper path to the location of the 64-bit and 32-bit WinDbg.exe. + +**Creating a dump file using .dump** + +To capture a dump file whenever a failure occurs that includes the JIT\_DEBUG\_INFO data, use .dump /j <address>. + +``` +\windbg.exe -p %ld -e %ld -c ".dump /j %p /u \AeDebug.dmp; qd" +``` + +Use the /u option to generate a unique filename to allow multiple dump files to be automatically created. For more information about the options see, [**.dump (Create Dump File)**](-dump--create-dump-file-.md). + +The created dump will have the JITDEBUG\_INFO data stored as the default exception context. Instead of using .jdinfo to view the exception information and set the context, use .exr -1 to display the exception record and .ecxr to set the context. For more information see [**.exr (Display Exception Record)**](-exr--display-exception-record-.md) and [**.ecxr (Display Exception Context Record)**](-ecxr--display-exception-context-record-.md). + +**Windows Error Reporting - q / qd** + +The way the debug session ends determines if Windows Error Reporting reports the failure. + +If the debug session is detached using qd prior to the closing of the debugger, WER will report the failure. + +If the debug session is quit using q (or if the debugger is closed without detaching), WER will not report the failure. + +Append *;q* or *;qd* to the end of the command string to invoke the desired behavior. + +For example, to allow WER to report the failure after CDB captures a dump, configure this command string. + +``` +\cdb.exe -p %ld -e %ld -c ".dump /j 0x%p /u c:\Dumps\AeDebug.dmp; qd" +``` + +This example would allow WER to report the failure after WinDbg captures a dump. + +``` +\windbg.exe -p %ld -e %ld -c ".dump /j %p /u \AeDebug.dmp; qd"" +``` + +## Security Vulnerabilities + + +If you are considering enabling postmortem debugging on a computer that you share with other people, see [Security During Postmortem Debugging](security-during-postmortem-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enabling%20Postmortem%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enabling-rpc-state-information.md b/windows-driver-docs-pr/debugger/enabling-rpc-state-information.md new file mode 100644 index 0000000000..c1571e61f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enabling-rpc-state-information.md @@ -0,0 +1,58 @@ +--- +title: Enabling RPC State Information +description: Enabling RPC State Information +ms.assetid: 8804d941-c241-44cb-8d91-05b94a875d94 +keywords: ["RPC debugging, enabling RPC state information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling RPC State Information + + +## + + +Two different levels of RPC run-time state information can be gathered: **Server** information and **Full** information. This information gathering must be enabled before the debugger or DbgRpc can be used to analyze state information. + +Only Windows XP and later versions of Windows support the gathering of RPC state information. + +Gathering **Server** state information is very lightweight. It costs about 100 machine instructions per RPC call, resulting in no detectable load, even during performance tests. However, gathering this information does use memory (about 4KB per RPC server), so it is not recommended on a machine that is already experiencing memory pressure. **Server** information includes data about endpoints, threads, connection objects, and Server Call (SCALL) objects. This is sufficient to debug most RPC problems. + +Gathering **Full** state information is more heavyweight. It includes all the information gathered at the **Server** level and, in addition, includes Client Call (CCALL) objects. **Full** state information is usually not needed. + +To enable state information to be gathered on an individual machine, run the Group Policy Editor (Gpedit.msc). Under the Local Computer Policy, navigate to **Computer Configuration/Administrative Templates/System/Remote Procedure Call**. Under this node you will see the **RPC Troubleshooting State Information** item. When you edit its properties, you will see five possible states: + +**None** +No state information will be maintained. Unless your machine is experiencing memory pressure, this is not recommended. + +**Server** +**Server** state information will be gathered. This is the recommended setting on a single computer. + +**Full** +**Full** state information will be gathered. + +**Auto1** +On a computer with less than 64 MB of RAM, this is the same as **None**. On a computer with at least 64 MB of RAM, this is the same as **Server**. + +**Auto2** +On a computer running Windows Server 2003 with less than 128 MB of RAM, or on any Windows XP computer, this is the same as **None**. On a Windows Server 2003 computer with at least 128 MB RAM, this is the same as **Server**. + +This is the default. + +If you want to simultaneously set these levels on a set of networked computers, use the Group Policy Editor to roll out a machine policy to the preferred set of machines. The policy engine will take care that the settings you want are propagated to the preferred set of machines. The **Auto1** and **Auto2** levels are especially useful in this case, because the operating system and amount of RAM on each computer may vary. + +If the network includes computers running versions of Windows that are earlier than Windows XP, the settings will be ignored on those machines. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Enabling%20RPC%20State%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-cdb.md b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-cdb.md new file mode 100644 index 0000000000..bb510711e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-cdb.md @@ -0,0 +1,42 @@ +--- +title: Ending a Debugging Session in CDB +description: You can exit CDB by entering the q (Quit) command. This command also closes the application that you are debugging. +ms.assetid: B32AD09D-7F88-420E-94BD-59FAE6EC1720 +--- + +# Ending a Debugging Session in CDB + + +You can exit CDB by entering the [**q (Quit)**](q--qq--quit-.md) command. This command also closes the application that you are debugging. + +The [**qd (Quit and Detach)**](qd--quit-and-detach-.md) command detaches CDB from the target application, exits the debugger, and leaves the target application running. If you used the **-pd** command-line option when you started the debugger, detaching occurs if the session is ended for any reason. (This technique makes **-pd** especially useful when you are debugging a sensitive process, such as the Client Server Run-Time Subsystem (CSRSS), that you do not want to end.) + +If the debugger is not responding, you can exit by pressing [**CTRL+B**](ctrl-b--quit-local-debugger-.md) and then ENTER. This method is a secondary exit mechanism. It abruptly ends the debugger and is similar to ending a process through Task Manager or by closing the window. + +To end a user-mode debugging session, return the debugger to dormant mode, and close the target application, you can use the following method: + +- Enter the [**.kill (Kill Process)**](-kill--kill-process-.md) command. + +To end a user-mode debugging session, return the debugger to dormant mode, and set the target application running again, you can use the following methods: + +- Enter the [**.detach (Detach from Process)**](-detach--detach-from-process-.md) command. If you are debugging multiple targets, this command detaches from the current target and continues the debugging session with the remaining targets. + +- Enter the [**qd (Quit and Detach)**](qd--quit-and-detach-.md) command. + +- Enter the [**q (Quit)**](q--qq--quit-.md) command, if you started the debugger with the **-pd** option. + +To end a user-mode debugging session, return the debugger to dormant mode, but leave the target application in the debugging state, you can use the following method: + +- Enter the [**.abandon (Abandon Process)**](-abandon--abandon-process-.md) command. + +For more information about reattaching to the target, see [Reattaching to the Target Application](reattaching-to-the-target-application.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Ending%20a%20Debugging%20Session%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-kd.md b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-kd.md new file mode 100644 index 0000000000..28739231b3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-kd.md @@ -0,0 +1,35 @@ +--- +title: Ending a Debugging Session in KD +description: Ending a Debugging Session in KD +ms.assetid: 6CD39971-424D-4F29-9A36-CCD14187DEB0 +--- + +# Ending a Debugging Session in KD + + +There are two different ways to exit KD. + +- Issue a [**q (Quit)**](q--qq--quit-.md) command in KD to save the log file, end the debugging session, and exit the debugger. The target computer remains locked. + +- Press [**CTRL+B**](ctrl-b--quit-local-debugger-.md) and then press ENTER to end the debugger abruptly. If you want the target computer to continue to run after the debugger is ended, you must use this method. Because CTRL+B does not remove breakpoints, you should use the following commands first. + + ``` + kd> bc * + kd> g + ``` + +Exiting the debugger by using CTRL+B does not clear kernel-mode breakpoints, but attaching a new kernel debugger does clear these breakpoints. + +When you are performing remote debugging, [**q**](q--qq--quit-.md) ends the debugging session. CTRL+B exits the debugger but leaves the session active. This situation enables another debugger to connect to the session. + +If the [**q (Quit)**](q--qq--quit-.md) command does not work, press [**CTRL+R**](ctrl-r--re-synchronize-.md) and then press ENTER on the host computer's keyboard, and then retry the **q** command. If this procedure does not work, you must use CTRL+B to exit the debugger. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Ending%20a%20Debugging%20Session%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-visual-studio.md b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-visual-studio.md new file mode 100644 index 0000000000..80a072fb93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-visual-studio.md @@ -0,0 +1,20 @@ +--- +title: Ending a Debugging Session in Visual Studio +description: To end a debugging session in Microsoft Visual Studio, from the Debug menu, choose Stop Debugging. +ms.assetid: D1737580-5A56-4BF6-BB4C-ECE5F017C4B1 +--- + +# Ending a Debugging Session in Visual Studio + + +To end a debugging session in Microsoft Visual Studio, from the **Debug** menu, choose **Stop Debugging**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Ending%20a%20Debugging%20Session%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-windbg.md b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-windbg.md new file mode 100644 index 0000000000..d832e4353d --- /dev/null +++ b/windows-driver-docs-pr/debugger/ending-a-debugging-session-in-windbg.md @@ -0,0 +1,71 @@ +--- +title: Ending a Debugging Session in WinDbg +description: Ending a Debugging Session in WinDbg +ms.assetid: 9C19211B-38CC-482B-B69F-B83B29963B3F +--- + +# Ending a Debugging Session in WinDbg + + +## Exiting WinDbg + + +You can exit WinDbg by choosing **Exit** from the **File** menu or by pressing ALT+F4. + +If you are performing user-mode debugging, these commands close the application that you are debugging, unless you used the **-pd** command-line option when you started the debugger. + +If you are performing kernel-mode debugging, the target computer remains in its current state. This situation enables you to leave the target running or frozen. (If you leave the target frozen, any future connection from a kernel debugger can resume debugging where you left it.) + +## Ending a User-Mode Session Without Exiting + + +To end a user-mode debugging session, return the debugger to dormant mode, and close the target application, you can use the following methods: + +- Enter the [**.kill (Kill Process)**](-kill--kill-process-.md) command. + +- Enter the [**q (Quit)**](q--qq--quit-.md) command (unless you started the debugger with the **-pd** option). + +- Choose **Stop Debugging** from the **Debug** menu. +- Press SHIFT+F5. + +- Click the **Stop Debugging** button (![screen shot of the stop debugging button ](images/tbstop.png)) on the toolbar + +To end a user-mode debugging session, return the debugger to dormant mode, and set the target application running again, you can use the following methods: + +- Enter the [**.detach (Detach from Process)**](-detach--detach-from-process-.md) command. If you are debugging multiple targets, this command detaches from the current target and continues the debugging session with the remaining targets. + +- Choose **Detach Debugee** from the **Debug** menu. If you are debugging multiple targets, this command detaches from all current targets. + +- Enter the [**qd (Quit and Detach)**](qd--quit-and-detach-.md) command. + +- Enter the [**q (Quit)**](q--qq--quit-.md) command, if you started the debugger with the **-pd** option. + +To end a user-mode debugging session, return the debugger to dormant mode, but leave the target application in the debugging state, you can use the following method: + +- Enter the [**.abandon (Abandon Process)**](-abandon--abandon-process-.md) command. + +For information about reattaching to the target, see [Reattaching to the Target Application](reattaching-to-the-target-application.md). + +## Ending a Kernel-Mode Session Without Exiting + + +To end a kernel-mode debugging session, return the debugger to dormant mode, and leave the target computer frozen, you can use the following methods: + +- Enter the [**q (Quit)**](q--qq--quit-.md) command (unless you started the debugger with the **-pd** option) + +- Choose **Stop Debugging** from the **Debug** menu. +- Press SHIFT+F5. + +- Click the **Stop debugging (Shift+F5)** button (![screen shot of the stop debugging button ](images/tbstop.png)) on the toolbar. + +When a WinDbg session ends, you are prompted to save the workspace for the current session, and then WinDbg returns to dormant mode. At this point, you can use all starting options. That is, you can start to debug a running process, spawn a new process, attach to a target computer, open a crash dump, or connect to a remote debugging session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Ending%20a%20Debugging%20Session%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/engextcpp-extension-design-guide.md b/windows-driver-docs-pr/debugger/engextcpp-extension-design-guide.md new file mode 100644 index 0000000000..7fdc6d0e8f --- /dev/null +++ b/windows-driver-docs-pr/debugger/engextcpp-extension-design-guide.md @@ -0,0 +1,41 @@ +--- +title: EngExtCpp Extension Design Guide +description: EngExtCpp Extension Design Guide +ms.assetid: 7fc21b10-9f79-4dab-90cc-5e2609414f72 +keywords: ["EngExtCpp extensions, design guide"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# EngExtCpp Extension Design Guide + + +## + + +This section includes: + +[EngExtCpp Extension Libraries](engextcpp-extension-libraries.md) + +[Client Objects and the Engine](client-objects-and-the-engine.md) + +[Writing EngExtCpp Extensions](writing-engextcpp-extensions.md) + +[Building ExtEngCpp Extensions](building-extengcpp-extensions.md) + +[Parsing Extension Arguments](parsing-extension-arguments.md) + +[Typed Data](typed-data.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20EngExtCpp%20Extension%20Design%20Guide%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/engextcpp-extension-libraries.md b/windows-driver-docs-pr/debugger/engextcpp-extension-libraries.md new file mode 100644 index 0000000000..40b4763ac8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/engextcpp-extension-libraries.md @@ -0,0 +1,53 @@ +--- +title: EngExtCpp Extension Libraries +description: EngExtCpp Extension Libraries +ms.assetid: 8c7ce3f8-46c4-408c-aab5-00d654bddfcd +keywords: ["EngExtCpp extensions, libraries"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# EngExtCpp Extension Libraries + + +## + + +An EngExtCpp extension library is a DLL that uses the EngExtCpp extension framework found in EngExtCpp.h. When this library is loaded by the debugger engine, its methods and functions can provide extra functionality or automation of tasks while performing user-mode or kernel-mode debugging on Microsoft Windows. + +The EngExtCpp extension framework is built on top of the [DbgEng extension framework](writing-dbgeng-extension-code.md). It offers the same debugger engine API for interaction with the debugger engine. but it also provides additional features to make common tasks simpler. + +If you performed a full install of Debugging Tools for Windows, a sample EngExtCpp extension called "extcpp" can be found in the sdk\\samples\\extcpp subdirectory of the installation directory. + +### EXT\_CLASS and ExtExtension + +At the core of an EngExtCpp extension library is a single instance of the [**EXT\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff544508) class. An EngExtCpp extension library will provide the implementation of this class, which contains all the extension commands and methods for formatting structures that are exported by the library. + +EXT\_CLASS is a subclass of [**ExtExtension**](https://msdn.microsoft.com/library/windows/hardware/ff543981). The single instance of this class is created using the [**EXT\_DECLARE\_GLOBALS**](https://msdn.microsoft.com/library/windows/hardware/ff544527) macro which must appear exactly once in the source files for the extension library. + +When the extension library is loaded, the [**Initialize**](https://msdn.microsoft.com/library/windows/hardware/ff550945) method of the class is called by the engine, and the [**Uninitialize**](https://msdn.microsoft.com/library/windows/hardware/ff558961) method is called before unloading the class. Additionally, the methods [**OnSessionActive**](https://msdn.microsoft.com/library/windows/hardware/ff552312), [**OnSessionInactive**](https://msdn.microsoft.com/library/windows/hardware/ff552318), [**OnSessionAccessible**](https://msdn.microsoft.com/library/windows/hardware/ff552310), and [**OnSessionInaccessible**](https://msdn.microsoft.com/library/windows/hardware/ff552315) are called by the engine to notify the extension library of the state of the debugging session. + +### Extension Commands + +The [**EXT\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff544508) class can contain a number of methods that are used to execute extension commands. Each extension command is declared in the EXT\_CLASS class by using the [**EXT\_COMMAND\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/ff544517) macro. The implementation of a command is defined by using the [**EXT\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/ff544514) macro. + +### Known Structures + +The [**EXT\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff544508) class can contain a number of methods that use the [*ExtKnownStructMethod*](https://msdn.microsoft.com/library/windows/hardware/ff543989) prototype. The methods can be used by the engine to format instances of certain structure types for output. + +### Provided Values + +The [**EXT\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff544508) class can contain a number of methods that use the **ExtProvideValueMethod** prototype. The methods can be used by the engine to evaluate some pseudo-registers provided by the extension. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20EngExtCpp%20Extension%20Libraries%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/engextcpp-extensions.md b/windows-driver-docs-pr/debugger/engextcpp-extensions.md new file mode 100644 index 0000000000..69f6d79519 --- /dev/null +++ b/windows-driver-docs-pr/debugger/engextcpp-extensions.md @@ -0,0 +1,33 @@ +--- +title: EngExtCpp Extensions +description: EngExtCpp Extensions +ms.assetid: 0eed4aa8-c70a-429e-b887-9b35352517ce +keywords: ["EngExtCpp extensions", "extensions, ExtEngCpp"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# EngExtCpp Extensions + + +## + + +This section includes: + +[EngExtCpp Extension Design Guide](engextcpp-extension-design-guide.md) + +[EngExtCpp Extension Reference](https://msdn.microsoft.com/library/windows/hardware/ff543033) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20EngExtCpp%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/enter--repeat-last-command-.md b/windows-driver-docs-pr/debugger/enter--repeat-last-command-.md new file mode 100644 index 0000000000..30e4780514 --- /dev/null +++ b/windows-driver-docs-pr/debugger/enter--repeat-last-command-.md @@ -0,0 +1,73 @@ +--- +title: ENTER (Repeat Last Command) +description: The ENTER key repeats the last command that you typed. +ms.assetid: 058e455a-8934-4b28-8cf0-2d3f09a7e7cc +keywords: ["ENTER (Repeat Last Command) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ENTER (Repeat Last Command) +api_type: +- NA +--- + +# ENTER (Repeat Last Command) + + +The ENTER key repeats the last command that you typed. + +``` +ENTER +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +In CDB and KD, pressing the ENTER key by itself at a command prompt reissues the command that you previously entered. + +In WinDbg, the ENTER key can have no effect or you can use it to repeat the previous command. You can set this option in the **Options** dialog box. (To open the **Options** dialog box, click **Options** on the **View** menu or click the **Options** button (![screen shot of the options button](images/tbopt.png)) on the toolbar.) + +If you set ENTER to repeat the last command, but you want to create white space in the [Debugger Command window](debugger-command-window.md), use the [**\* (Comment Line Specifier)**](----comment-line-specifier-.md) token and then press ENTER several times. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ENTER%20%28Repeat%20Last%20Command%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/entering-debugger-commands-in-visual-studio.md b/windows-driver-docs-pr/debugger/entering-debugger-commands-in-visual-studio.md new file mode 100644 index 0000000000..e07e5e1186 --- /dev/null +++ b/windows-driver-docs-pr/debugger/entering-debugger-commands-in-visual-studio.md @@ -0,0 +1,22 @@ +--- +title: Entering Debugger Commands in Visual Studio +description: The procedures covers Entering Debugger Commands in Visual Studio. +ms.assetid: 0590D849-3885-46D9-A6A1-55F3086B95FF +--- + +# Entering Debugger Commands in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +In Visual Studio, you can enter debugger commands in the Debugger Immediate Window. To open the Debugger Immediate Window, from the **Debug** menu, choose **Windows>Immediate**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Entering%20Debugger%20Commands%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/environment-variables.md b/windows-driver-docs-pr/debugger/environment-variables.md new file mode 100644 index 0000000000..608ab10d0a --- /dev/null +++ b/windows-driver-docs-pr/debugger/environment-variables.md @@ -0,0 +1,35 @@ +--- +title: Environment Variables +description: Environment Variables +ms.assetid: 0b1cd89f-e0c1-464e-a6d1-88a93753e570 +keywords: ["environment variables"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Environment Variables + + +## + + +This reference section includes: + +[General Environment Variables](general-environment-variables.md) + +[Kernel-Mode Environment Variables](kernel-mode-environment-variables.md) + +For information about using environment variables for debugging, see [Getting Set Up for Debugging](getting-set-up-for-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Environment%20Variables%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/evaluating-expressions.md b/windows-driver-docs-pr/debugger/evaluating-expressions.md new file mode 100644 index 0000000000..f94c1a7142 --- /dev/null +++ b/windows-driver-docs-pr/debugger/evaluating-expressions.md @@ -0,0 +1,97 @@ +--- +title: Evaluating Expressions +description: Evaluating Expressions +ms.assetid: f2fbdac1-2c20-4132-b43e-4c7a90a2f5b7 +keywords: ["expressions, overview", "expressions, different types", "MASM expressions, when to use", "C++ expressions, when to use", "MASM expressions, overview", "C++ expressions, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Evaluating Expressions + + +## + + +The debugger understands two different forms of expressions: *MASM expressions* and *C++ expressions*. + +Microsoft Macro Assembler (MASM) expressions are used in the examples in this Help documentation, except when otherwise noted. In MASM expressions, all symbols are treated as addresses. + +C++ expressions are the same as those used in actual C++ code. In these expressions, symbols are understood as the appropriate data types. + +### When Each Syntax is Used + +You can select the default expression evaluator in one of the following ways: + +- Use the \_NT\_EXPR\_EVAL [environment variable](general-environment-variables.md) before the debugger is started. + +- Use the **-ee** {**masm**|**c++**} [command-line option](command-line-options.md) when the debugger is started. + +- Use the [**.expr (Choose Expression Evaluator)**](-expr--choose-expression-evaluator-.md) command to display or change the expression evaluator after the debugger is running. + +If you do not use one of the preceding methods, the debugger uses the MASM expression evaluator. + +If you want to evaluate an expression without changing the debugger state, you can use the [**? (Evaluate Expression)**](---evaluate-expression-.md) command. + +All commands and debugging information windows interpret their arguments through the default expression evaluator, with the following exceptions: + +- The [**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) command always uses the C++ expression evaluator. + +- The Watch window always uses the C++ expression evaluator. + +- The [Locals window](locals-window.md) always uses the C++ expression evaluator. + +- Some extension commands always use the MASM expression evaluator (and other extension commands accept only numeric arguments instead of full expressions). + +- If any part of an expression is enclosed in parentheses and you insert two at signs (**@@**) before the expression, the expression is evaluated by the expression evaluator that would not typically be used in this case. + +The two at signs (**@@**) enable you to use two different evaluators for different parameters of a single command. It also enables you to evaluate different pieces of a long expression by different methods. You can nest the two at signs. Each appearance of the two at signs switches to the other expression evaluator. + +**Warning**   C++ expression syntax is useful for manipulating structures and variables, but it is not well-suited as a parser for the parameters of debugger commands. When you are using debugger commands for general purposes or you are using debugger extensions, you should set MASM expression syntax as the default expression evaluator. If you must have a specific parameter use C++ expression syntax, use the two at sign (**@@**) syntax. + +  + +For more information about the two different expression types, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +### Numbers in Expressions + +Numbers in MASM expressions are interpreted according to the current radix. The [**n (Set Number Base)**](n--set-number-base-.md) command can be used to set the default radix to 16, 10, or 8. All un-prefixed numbers will be interpreted in this base. The default radix can be overridden by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + +Numbers in C++ expressions are interpreted as decimal numbers unless you specify differently. To specify a hexadecimal integer, add **0x** before the number. To specify an octal integer, add **0** (zero) before the number. (However, in the debugger's *output*, the **0n** decimal prefix is sometimes used.) + +If you want to display a number in several bases at the same time, use the [**.formats (Show Number Formats)**](-formats--show-number-formats-.md) command. + +### Symbols in Expressions + +The two types of expressions interpret symbols differently: + +- In MASM expressions, each symbol is interpreted as an address. Depending on what the symbol refers to, this address is the address of a global variable, local variable, function, segment, module, or any other recognized label. + +- In C++ expressions, each symbol is interpreted according to its type. Depending on what the symbol refers to, it might be interpreted as an integer, a data structure, a function pointer, or any other data type. A symbol that does not correspond to a C++ data type (such as an unmodified module name) creates a syntax error. + +If a symbol might be ambiguous, precede it with the module name and an exclamation point ( **!** ). If the symbol name could be interpreted as a hexadecimal number, precede it with the module name and an exclamation point ( **!** ) or only an exclamation point. In order to specify that a symbol is meant to be local, omit the module name, and include a dollar sign and an exclamation point ( **$!** ) before the symbol name. For more information about interpreting symbols, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +### Operators in Expressions + +Each expression type uses a different collection of operators. + +For more information about the operators that you can use in MASM expressions and their precedence rules, see [MASM Numbers and Operators](masm-numbers-and-operators.md). + +For more information about the operators that you can use in C++ expressions and their precedence rules, see [C++ Numbers and Operators](c---numbers-and-operators.md). + +Remember that MASM operations are always byte-based, and C++ operations follow C++ type rules (including the scaling of pointer arithmetic). + +For some examples of the different syntaxes, see [Expression Examples](expression-examples.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Evaluating%20Expressions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/event-filters.md b/windows-driver-docs-pr/debugger/event-filters.md new file mode 100644 index 0000000000..6ccf46f53c --- /dev/null +++ b/windows-driver-docs-pr/debugger/event-filters.md @@ -0,0 +1,148 @@ +--- +title: Event Filters +description: Event Filters +ms.assetid: 91f2a483-8971-42de-a6c5-cc25409279a5 +keywords: ["Debugger Engine API, event filters"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Event Filters + + +*Event filters* provide simple event filtering; they influence how the debugger engine proceeds after an event occurs in a target. When an event occurs, the engine determines whether that event matches an event filter. If it does, the break status for the event filter influences whether the debugger will break into the target. If the event is an exception event, the handling status determines whether the exception should be considered handled or not-handled in the target. + +**Note**   If more sophisticated event filtering is required, event callbacks can be used. + +  + +Event filters are divided into three categories. + +1. *Specific event filters*. These are the filters for all the non-exception events. See [**DEBUG\_FILTER\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541490) for a list of these events. + +2. *Specific exception filters*. The first specific exception filter is the *default exception filter*. The rest are filters for those exceptions for which the engine has built-in filters. See [**Specific Exceptions**](https://msdn.microsoft.com/library/windows/hardware/ff558784) for a list of the specific exception filters. + +3. *Arbitrary exception filters*. These are filters for exception events that have been added manually. + +The filters in categories 1 and 2 are collectively known as *specific filters*, and the filters in categories 2 and 3 are collectively known as *exception filters*. The number of filters in each category is returned by [**GetNumberEventFilters**](https://msdn.microsoft.com/library/windows/hardware/ff547899). + +An event matches a specific event filter if the type of the event is the same as the type of the filter. Some event filters have an additional parameter which further restricts the events they match. + +An exception event matches an exception filter if the exception code for the exception event is the same as the exception code for the exception filter. If there is no exception filter with the same exception code as the exception event, the exception event will be handled by the default exception filter. + +### Commands and Parameters + +Event filters can have a debugger command associated with them. This command is executed by the engine when an event matching the filter occurs. [**GetEventFilterCommand**](https://msdn.microsoft.com/library/windows/hardware/ff546611) and [**SetEventFilterCommand**](https://msdn.microsoft.com/library/windows/hardware/ff556678) can be used to get and set this command. For exception filters, this command is executed on the first-chance of the exception. A separate second-chance command can be executed upon the second-chance exception event. To get and set the second-chance command, use [**GetExceptionFilterSecondCommand**](https://msdn.microsoft.com/library/windows/hardware/ff546653) and [**SetExceptionSecondChanceCommand**](https://msdn.microsoft.com/library/windows/hardware/ff556687). + +The parameters for specific event filters and exception filters are returned by [**GetSpecificFilterParameters**](https://msdn.microsoft.com/library/windows/hardware/ff548398) and [**GetExceptionFilterParameters**](https://msdn.microsoft.com/library/windows/hardware/ff556683). The break status and handling status for event filters can be set using [**SetSpecificFilterParameters**](https://msdn.microsoft.com/library/windows/hardware/ff556795) and **SetExceptionFilterParameters**. + +**SetExceptionFilterParameters** can also be used to add and remove arbitrary exception filters. + +A short description of specific filters is returned by [**GetEventFilterText**](https://msdn.microsoft.com/library/windows/hardware/ff546618). + +Some specific filters take arguments that restrict which events the filter matches. [**GetSpecificFilterArgument**](https://msdn.microsoft.com/library/windows/hardware/ff548386) and [**SetSpecificFilterArgument**](https://msdn.microsoft.com/library/windows/hardware/ff556791) will get and set arguments for those specific filters which support arguments. If a specific filter has no argument, there is no restriction on which events it matches. The following table lists the event filters that take arguments and how they restrict the events which match them: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventMatch criteria

Create Process

The name of the created process must match the argument.1

Exit Process

The name of the exited process must match the argument.1

Load Module

The name of the loaded module must match the argument.1

Unload Module

The base address of the unloaded module must be the same as the argument.2

Target Output

The debug output from the target must match the argument.3

+ +  + +**Note**   +1. The argument uses the [string wildcard syntax](string-wildcard-syntax.md) and is compared with the image name (ignoring path) when the event occurs. If the name of the module or process is not available, it is considered a match. + +2. The argument is an expression that is evaluated by the engine when the argument is set. + +3. The argument uses the string wildcard syntax and is compared with the debug output from the target. If the output is not known, it is considered a match. + +  + +### Index and Exception Code + +Each event filter has an index. The index is a number between zero and one less than the total number of filters (inclusive). The index range for each category of filters can be found from the *SpecificEvents*, *SpecificExceptions*, and *ArbitraryExceptions* values returned by [**GetNumberEventFilters**](https://msdn.microsoft.com/library/windows/hardware/ff547899), as described in the following table: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Event FiltersIndex of first filterNumber of filters

Specific event filters

0

SpecificEvents

specific exception filters

SpecificEvents

SpecificExceptions

arbitrary exception filters

SpecificEvents + SpecificExceptions

ArbitraryExceptions

+ +  + +The indices for the specific event filters are found in the first table located in the topic [**DEBUG\_FILTER\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541490). The index of the default exception filter (the first specific exception filter) is *SpecificEvents*. When an arbitrary exception filter is removed, the indices of the other arbitrary exception filters can change. + +The exception filters are usually specified by exception code. However, some methods require the index of the exception. To find the index of an exception filter for a given exception, use [**GetExceptionFilterParameters**](https://msdn.microsoft.com/library/windows/hardware/ff546650) to iterate over all the exception filters until you find the one with the same exception code as the exception. The exception codes for the specific exception filters can be found in the topic [**Specific Exceptions**](https://msdn.microsoft.com/library/windows/hardware/ff558784). + +### System Errors + +When a system error occurs, the engine will break into the debugger or print the error to the output stream, if the error occurs at or below specified levels. These levels are returned by [**GetSystemErrorControl**](https://msdn.microsoft.com/library/windows/hardware/ff549215) and can be changed using [**SetSystemErrorControl**](https://msdn.microsoft.com/library/windows/hardware/ff556806). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Event%20Filters%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/event-information.md b/windows-driver-docs-pr/debugger/event-information.md new file mode 100644 index 0000000000..c7c732d3c5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/event-information.md @@ -0,0 +1,34 @@ +--- +title: Event Information +description: Event Information +ms.assetid: e6621b5d-f1af-4021-8832-43f79835a6c1 +keywords: ["targets, events"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Event Information + + +Whenever a debugging session is accessible, there is a *last event*. This is the event that caused the session to become accessible. The *event target* is the target which generated the last event. When the session becomes accessible, the current target is set to the event target. The details of the last event are returned by [**GetLastEventInformation**](https://msdn.microsoft.com/library/windows/hardware/ff546982). The instruction pointer for the last event and the memory at the instruction pointer when the event occurred are returned by the [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operations [**DEBUG\_REQUEST\_GET\_CAPTURED\_EVENT\_CODE\_OFFSET**](https://msdn.microsoft.com/library/windows/hardware/ff541561) and [**DEBUG\_REQUEST\_READ\_CAPTURED\_EVENT\_CODE\_STREAM**](https://msdn.microsoft.com/library/windows/hardware/ff541572). + +If the target is a crash dump file, the *last event* is the last event that occurred before the dump file was created. This event is stored in the dump file and the engine generates it for the event callbacks when the dump file is acquired as a debugging target. + +If the target is a kernel-mode target and a [*bug check*](https://msdn.microsoft.com/library/windows/hardware/ff556272#wdkgloss-bug-check) occurred, the bug check code and related parameters can be found using [**ReadBugCheckData**](https://msdn.microsoft.com/library/windows/hardware/ff553517). + +If the target is a user-mode Minidump, the dump file generator may store an additional event. Typically, this is the event that provoked the generator to save the dump file. Details of this event are returned by [**GetStoredEventInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548431) and the [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operations [**DEBUG\_REQUEST\_TARGET\_EXCEPTION\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff541606), [**DEBUG\_REQUEST\_TARGET\_EXCEPTION\_THREAD**](https://msdn.microsoft.com/library/windows/hardware/ff541623), and [**DEBUG\_REQUEST\_TARGET\_EXCEPTION\_RECORD**](https://msdn.microsoft.com/library/windows/hardware/ff541616). + +Dump files may contain a static list of events. Each event represents a snapshot of the target at a particular point in time. The number of events in this list is returned by [**GetNumberEvents**](https://msdn.microsoft.com/library/windows/hardware/ff547906). For a description of each event in the list, use [**GetEventIndexDescription**](https://msdn.microsoft.com/library/windows/hardware/ff546630). To set an event from this list as the current event, use the method [**SetNextEventIndex**](https://msdn.microsoft.com/library/windows/hardware/ff556737); after calling [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229), the event becomes the current event. To determine which event in the list is the current event, use [**GetCurrentEventIndex**](https://msdn.microsoft.com/library/windows/hardware/ff545755). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Event%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/events.md b/windows-driver-docs-pr/debugger/events.md new file mode 100644 index 0000000000..20ace75dd3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/events.md @@ -0,0 +1,43 @@ +--- +title: Events +description: Events +ms.assetid: 2b086e78-ac4d-4f9c-a006-65f6f50b33f1 +keywords: ["Debugger Engine, events"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Events + + +## + + +The debugger engine provides facilities for monitoring and responding to events in the target. When an event occurs, the engine suspends the target (often only briefly), it then notifies all of the clients of the event, who in turn instruct the engine on how execution should proceed in the target. + +To notify a client of an event, the engine calls the event callback object that is registered with the client. The engine provides each event callback with details of the event, and the event callback instructs the engine on how execution should proceed in the target. When different event callbacks provide conflicting instructions, the engine acts on the instruction with the highest precedence (see [**DEBUG\_STATUS\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541651)), which typically means choosing the instruction that involves the least execution of the target. + +**Note**   While the event callback is handling the event, the target is suspended and the debugging session is accessible; however, because the engine was waiting for an event--either explicitly during a [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) call or implicitly by executing a command such as [**g (Go)**](g--go-.md) or [**p (Step)**](p--step-.md)--the event callback cannot call **WaitForEvent**, and if it attempts to execute any commands that would cause the debugger to execute, for example **g (Go)** or **p (Step)**, the engine will interpret these commands as an instruction on how to proceed. + +  + +### Event Filters + +The debugger engine also provides *event filters*, which are a simpler alternative for basic event monitoring. The event filters provide a few simple rules that specify whether an event should be printed to the debugger's output stream or break into the debugger. They can also be used to execute debugger commands when an event occurs. + +### Additional Information + +For details about monitoring events, see [Monitoring Events](monitoring-events.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Events%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/examining-the-stack-trace.md b/windows-driver-docs-pr/debugger/examining-the-stack-trace.md new file mode 100644 index 0000000000..f2ab0c2b97 --- /dev/null +++ b/windows-driver-docs-pr/debugger/examining-the-stack-trace.md @@ -0,0 +1,30 @@ +--- +title: Examining the Stack Trace +description: Examining the Stack Trace +ms.assetid: ca203f29-841f-411e-915a-81abaa96a8e6 +keywords: ["Debugger Engine API, stack trace"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Examining the Stack Trace + + +A *call stack* contains the data for the functions calls made by a thread. The data for each function call is called a *stack frame* and includes the return address, parameters passed to the function, and the function's local variables. Each time a function call is made a new stack frame is pushed onto the top of the stack. When that function returns, the stack frame is popped off the stack. + +Each thread has its own call stack, representing the calls made in that thread. + +To get a stack trace, use the methods [**GetStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff548425) and [**GetContextStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff545748). A stack trace can be printed using [**OutputStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff553252) and [**OutputContextStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff553203). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Examining%20the%20Stack%20Trace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-1---displaying-global-flags.md b/windows-driver-docs-pr/debugger/example-1---displaying-global-flags.md new file mode 100644 index 0000000000..0e811faca8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-1---displaying-global-flags.md @@ -0,0 +1,60 @@ +--- +title: Example 1 Displaying Global Flags +description: Example 1 Displaying Global Flags +ms.assetid: c1a1eafd-d70a-43f9-af90-33ddc33758fe +--- + +# Example 1: Displaying Global Flags + + +## + + +The commands demonstrated in this example display the system-wide flags set in the registry, the system flags set for the session (kernel mode), and the flags set for an image file. + +The following GFlags command displays the current value of the system-wide flags set in the registry. It uses the **/r** parameter to specify the system-wide registry entry. + +``` +gflags /r +``` + +In response, GFlags displays a single hexadecimal value representing the sum of all flags set and a list of the flags set. + +``` +Current Boot Registry Settings are: 40001400 + ptg - Enable pool tagging + ust - Create user mode stack trace database + bhd - Enable bad handles detection +``` + +In this example, the results show that there are three tags set, with a combined value of 0x40001400. + +- [Enable pool tagging](enable-pool-tagging.md) (ptg) = 0x400 + +- [Create user mode stack trace database](create-user-mode-stack-trace-database.md) (ust) = 0x1000 + +- [Enable bad handles detection](enable-bad-handles-detection.md) (bhd) = 0x40000000 + +The following command displays the flags set for the current session. It uses the **/k** parameter to indicate kernel mode. + +``` +gflags /k +``` + +The following command displays flags set in the registry for the image file notepad.exe. It uses the **/i** parameter to indicate image file mode and specifies the image file. + +``` +gflags /i notepad.exe +``` + +Remember that the flag value displayed might not be the current, effective flag value. Changes to the system-wide flags are not effective until you restart Windows. Changes to image file flag settings are not effective until you restart the program. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%201:%20%20Displaying%20Global%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-10---detecting-a-heap-memory-leak-in-a-process.md b/windows-driver-docs-pr/debugger/example-10---detecting-a-heap-memory-leak-in-a-process.md new file mode 100644 index 0000000000..8bf08564a4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-10---detecting-a-heap-memory-leak-in-a-process.md @@ -0,0 +1,59 @@ +--- +title: Example 10 Detecting a Heap Memory Leak in a Process +description: Example 10 Detecting a Heap Memory Leak in a Process +ms.assetid: ec98dd96-b12b-4f83-85e8-2c5ee32fc17e +--- + +# Example 10: Detecting a Heap Memory Leak in a Process + + +## + + +This example uses GFlags and User Mode Dump Heap (UMDH, umdh.exe), a tool included in Microsoft Debugging Tools for Windows. + +**To detect a leak in heap memory in notepad.exe** + +1. Set the [Create user mode stack trace database](create-user-mode-stack-trace-database.md) (**ust**) flag for the notepad.exe image file. + + The following command uses GFlags to set the **Create user mode stack trace database** flag. It uses the **/i** parameter to identify the image file and the **ust** abbreviation for the flag. + + ``` + gflags /i Notepad.exe +ust + ``` + + As a result of this command, a user-mode stack trace is created for all new instances of the Notepad process. + +2. Set the symbol file path. + + The following command creates an environment variable that stores the path to the directory of symbol files: + + ``` + set _NT_SYMBOL_PATH=C:\Windows\symbols + ``` + +3. Start Notepad. + +4. Find the process identifier (PID) of the Notepad process. + + You can find the PID of any running process from Task Manager or Tasklist (tasklist.exe), a tool included in Windows XP Professional and Windows Server 2003 operating systems. In this example, the Notepad PID is 1228. + +5. Run UMDH. + + The following command runs UMDH (umdh.exe). It uses the **-p:** parameter to specify the PID that, in this example, is 1228. It uses the **/f:** parameter to specify the name and location of the output file for the heap dump, notepad.dmp. + + ``` + umdh -p:1228 -f:notepad.dmp + ``` + + In response, UMDH writes a complete dump of all active heaps to the notepad.dmp file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2010:%20%20Detecting%20a%20Heap%20Memory%20Leak%20in%20a%20Process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-11---enabling-page-heap-verification.md b/windows-driver-docs-pr/debugger/example-11---enabling-page-heap-verification.md new file mode 100644 index 0000000000..292de6b2e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-11---enabling-page-heap-verification.md @@ -0,0 +1,49 @@ +--- +title: Example 11 Enabling Page Heap Verification +description: Example 11 Enabling Page Heap Verification +ms.assetid: 5d0303a9-29f7-4759-ae7b-ad670eaee0ee +--- + +# Example 11: Enabling Page Heap Verification + + +## + + +The following commands enable full and standard page heap verification for myapp.exe, a fictitious program. + +The first command enables *standard* page heap verification for myapp.exe. It uses the **/p** parameter to enable page heap for a process. By default, **/p** enables standard page heap. + +``` +gflags /p /enable myapp.exe +``` + +The following commands enable *full* page heap verification for the myapp.exe program. Although these commands create different settings in the registry, they are all functionally equivalent to selecting the **Enable page heap** check box for the myapp.exe image file in the **Global Flags** dialog box. These methods can be used interchangeably. + +``` +gflags /p /enable myapp.exe /full +gflags /i myapp.exe +hpa +gflags /i myapp.exe +02000000 +``` + +The following commands disable full or standard page heap verification for the myapp.exe program, regardless of the command or dialog box method used to enable page heap verification. + +``` +gflags /p /disable myapp.exe +gflags /i myapp.exe -hpa +gflags /i myapp.exe -02000000 +``` + +**Note**   When using the **/debug** or **/kdebug** parameters, use the **/p /disable** parameters to turn off the page heap verification (not the **/i -hpa** parameters). The **/p /disable** parameters disable page heap verification and delete registry entries that the debugger reads. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2011:%20%20Enabling%20Page%20Heap%20Verification%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-12---using-page-heap-verification-to-find-a-bug.md b/windows-driver-docs-pr/debugger/example-12---using-page-heap-verification-to-find-a-bug.md new file mode 100644 index 0000000000..5cda31dc73 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-12---using-page-heap-verification-to-find-a-bug.md @@ -0,0 +1,179 @@ +--- +title: Example 12 Using Page Heap Verification to Find a Bug +description: Example 12 Using Page Heap Verification to Find a Bug +ms.assetid: aa3f5c53-8522-48be-a3cd-49b740803fe3 +--- + +# Example 12: Using Page Heap Verification to Find a Bug + + +## + + +The following series of commands demonstrates how to use the page heap verification features of GFlags and the NTSD debugger to detect an error in heap memory use. In this example, the programmer suspects that a fictitious application, pheap-buggy.exe, has a heap error, and proceeds through a series of tests to identify the error. + +For details on NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + +### Step 1: Enable standard page heap verification + +The following command enables standard page heap verification for pheap-buggy.exe: + +``` +gflags /p /enable pheap-buggy.exe +``` + +### Step 2: Verify that page heap is enabled + +The following command lists the image files for which page heap verification is enabled: + +``` +gflags /p +``` + +In response, GFlags displays the following list of programs. In this display, **traces** indicates standard page heap verification, and **full traces** indicates full page heap verification. In this case, pheap-buggy.exe is listed with **traces**, indicating that standard page heap verification is enabled, as intended. + +``` +pheap-buggy.exe: page heap enabled with flags (traces ) +``` + +### Step 3: Run the debugger + +The following command runs the **CorruptAfterEnd** function of pheap-buggy.exe in NTSD with the **-g** (ignore initial breakpoint) and **-x** (set second-chance break on access violation exceptions) parameters: + +``` +ntsd -g -x pheap-buggy /CorruptAfterEnd +``` + +When the application fails, NTSD generates the following display, which indicates that it detected an error in pheap-buggy.exe: + +``` +=========================================================== +VERIFIER STOP 00000008: pid 0xAA0: corrupted suffix pattern + + 00C81000 : Heap handle + 00D81EB0 : Heap block + 00000100 : Block size +# 00000000 : +=========================================================== + +Break instruction exception - code 80000003 (first chance) +eax=00000000 ebx=00d81eb0 ecx=77f7e257 edx=0006fa18 esi=00000008 edi=00c81000 +eip=77f7e098 esp=0006fc48 ebp=0006fc5c iopl=0 nv up ei pl zr na po nc +cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00000246 +ntdll!DbgBreakPoint: +77f7e098 cc int 3 +``` + +The header information includes the address of the heap with the corrupted block (00C81000 : Heap handle), the address of the corrupted block (00D81EB0 : Heap block), and the size of the allocation (00000100 : Block size). + +The "corrupted suffix pattern" message indicates that the application violated the data integrity pattern that GFlags inserted after the end of the pheap-buggy.exe heap allocation. + +### Step 4: Display the call stack + +In the next step, use the addresses that NTSD reported to locate the function that caused the error. The next two commands turn on line number dumping in the debugger and display the call stack with line numbers. + +``` +C:\>.lines + +Line number information will be loaded + +C:\>kb + +ChildEBP RetAddr Args to Child +WARNING: Stack unwind information not available. Following frames may be wrong. +0006fc5c 77f9e6dd 00000008 77f9e3e8 00c81000 ntdll!DbgBreakPoint +0006fcd8 77f9f3c8 00c81000 00000004 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x2879 +0006fcfc 77f9f5bb 00c81000 01001002 00000010 ntdll!RtlpNtEnumerateSubKey+0x3564 +0006fd4c 77fa261e 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x3757 +0006fdc0 77fc0dc2 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x67ba +0006fe78 77fbd87b 00c80000 01001002 00d81eb0 ntdll!RtlSizeHeap+0x16a8 +0006ff24 010013a4 00c80000 01001002 00d81eb0 ntdll!RtlFreeHeap+0x69 +0006ff3c 01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x2b [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 185] +0006ff4c 0100157f 00000002 00c65a68 00c631d8 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 69] +0006ffc0 77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349] +0006fff0 00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204 +``` + +As a result, the debugger displays the call stack for pheap-buggy.exe with line numbers. The call stack display shows that the error occurred when the **TestCorruptAfterEnd** function in pheap-buggy.exe tried to free an allocation at 0x00c80000 by calling **HeapFree**, a redirect to **RtlFreeHeap**. + +The most likely cause of this error is that the program wrote past the end of the buffer that it allocated in this function. + +### Step 5: Enable full page heap verification + +Unlike standard page heap verification, full page heap verification can catch the misuse of this heap buffer as soon as it occurs. The following command enables full page heap verification for pheap-buggy.exe: + +``` +gflags /p /enable pheap-buggy.exe /full +``` + +### Step 6: Verify that full page heap is enabled + +The following command lists the programs for which page heap verification is enabled: + +``` +gflags /p +``` + +In response, GFlags displays the following list of programs. In this display, **traces** indicates standard page heap verification, and **full traces** indicates full page heap verification. In this case, pheap-buggy.exe is listed with **full traces**, indicating that full page heap verification is enabled, as intended. + +``` +pheap-buggy.exe: page heap enabled with flags (full traces ) +``` + +### Step 7: Run the debugger again + +The following command runs the **CorruptAfterEnd** function of pheap-buggy.exe in the NTSD debugger with the **-g** (ignore initial breakpoint) and **-x** (set second-chance break on access violation exceptions) parameters: + +``` +ntsd -g -x pheap-buggy /CorruptAfterEnd +``` + +When the application fails, NTSD generates the following display, which indicates that it detected an error in pheap-buggy.exe: + +``` +Page heap: process 0x5BC created heap @ 00880000 (00980000, flags 0x3) +ModLoad: 77db0000 77e8c000 kernel32.dll +ModLoad: 78000000 78046000 MSVCRT.dll +Page heap: process 0x5BC created heap @ 00B60000 (00C60000, flags 0x3) +Page heap: process 0x5BC created heap @ 00C80000 (00D80000, flags 0x3) +Access violation - code c0000005 (first chance) +Access violation - code c0000005 (!!! second chance !!!) +eax=00c86f00 ebx=00000000 ecx=77fbd80f edx=00c85000 esi=00c80000 edi=00c16fd0 +eip=01001398 esp=0006ff2c ebp=0006ff4c iopl=0 nv up ei pl nz na po nc +cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00000206 +pheap-buggy!TestCorruptAfterEnd+1f: +01001398 889801010000 mov [eax+0x101],bl ds:0023:00c87001=?? +``` + +With full page heap verification enabled, the debugger breaks at an access violation. To find the precise location of the access violation, turn on line number dumping and display the call stack trace. + +The numbered call stack trace appears as follows: The line displaying the problem appears in bold text. + +``` +ChildEBP RetAddr Args to Child +0006ff3c 01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x1f [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 184] +0006ff4c 0100157f 00000002 00c16fd0 00b70eb0 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap-buggy.cxx @ 69] +0006ffc0 77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349] +WARNING: Stack unwind information not available. Following frames may be wrong. +0006fff0 00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204 +``` + +The stack trace shows that the problem occurs in line 184 of pheap-buggy.exe. Because full page heap verification is enabled, the call stack starts in the program code, not in a system DLL. As a result, the violation was caught where it happened, instead of when the heap block was freed. + +### Step 8: Locate the error in the code + +A quick inspection reveals the cause of the problem: The program tries to write to the 257th byte (0x101) of a 256-byte (0x100) buffer, a common off-by-one error. + +``` +*((PCHAR)Block + 0x100) = 0; +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2012:%20%20Using%20Page%20Heap%20Verification%20to%20Find%20a%20Bug%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-13---listing-image-files-with-global-flags.md b/windows-driver-docs-pr/debugger/example-13---listing-image-files-with-global-flags.md new file mode 100644 index 0000000000..04c4ac7099 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-13---listing-image-files-with-global-flags.md @@ -0,0 +1,50 @@ +--- +title: Example 13 Listing Image Files with Global Flags +description: Example 13 Listing Image Files with Global Flags +ms.assetid: 1b1285d5-ed73-49c4-a123-de9cbdb3090c +--- + +# Example 13: Listing Image Files with Global Flags + + +## + + +GFlags displays the flags set for a particular image file, but it does not display all image files that have flags set. + +Windows stores flags for an image file that the **GlobalFlag** registry entry in a registry subkey named for the image file in the following registry path, **HKEY\_LOCAL\_MACHINE\\ SOFTWARE\\ Microsoft\\ Windows NT\\ CurrentVersion\\ Image File Execution Options\\*ImageFileName*\\GlobalFlag**. + +To determine which image files have flags set, use Reg (reg.exe), a tool included in Windows Server 2003. + +The following Reg **Query** command searches for the **GlobalFlag** registry entry in the specified registry path. The **-v** parameter specifies the **GlobalFlag** registry entry. The **/s** parameter makes the search recursive. + +``` +reg query "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options" /v GlobalFlag /s +``` + +In response, Reg displays all instances of the **GlobalFlag** registry entry in the path and the value of the entry. + +``` +HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\notepad.exe + GlobalFlag REG_SZ 0x00001000 + +HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\photohse.EXE + GlobalFlag REG_SZ 0x00200000 + +HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\printhse.EXE + GlobalFlag REG_SZ 0x00200000 +``` + +**Tip**   Type the **Reg** command into Notepad, then save the file as imageflags.bat. Thereafter, to find image files for which flags have been set, just type **ImageFlags**. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2013:%20%20Listing%20Image%20Files%20with%20Global%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-14---configuring-special-pool.md b/windows-driver-docs-pr/debugger/example-14---configuring-special-pool.md new file mode 100644 index 0000000000..9d63ebca0f --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-14---configuring-special-pool.md @@ -0,0 +1,156 @@ +--- +title: Example 14 Configuring Special Pool +description: Example 14 Configuring Special Pool +ms.assetid: a89f8a08-30e4-4d04-9689-c665b2175780 +--- + +# Example 14: Configuring Special Pool + + +Beginning in Windows Vista, you can configure the [Special Pool](special-pool.md) feature as a kernel flag setting or as a registry setting. If you configure it as a kernel flag (run time) setting, you do not need to restart the computer to make the change effective. In earlier versions of Windows, Special Pool is available only as a registry setting. + +Also, beginning in Windows Vista, you can set and configure the Special Pool feature from the command line. In earlier versions of Windows, you can set and configure the Special Pool feature only in the Global Flags dialog box. + +### Request Special Pool by pool tag without rebooting + +The following command requests special pool for all allocations with the **Tag1** pool tag. This setting becomes effective immediately, but it is lost if you shut down or restart Windows. + +This command uses the **/k** parameter to specify a kernel flag (run time) setting and the +spp abbreviation to set a special pool request. + +``` +gflags /k +spp Tag1 +``` + +Gflags responds by printing: + +``` +Special Pool set to 0x31676154 +PoolTagOverruns set to 0x1 +Current Running Kernel Settings are: 00000000 +``` + +Notice that the special pool allocation request is not a kernel flag setting and is not reflected in the kernel settings value. + +Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to underruns, use the Gflags Dialog Box. For information, see [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md). + +You cannot display the pool tag at the command line. To verify that the pool tag is a kernel setting, use the Gflags Dialog Box. + +### Request Special Pool by pool tag in the registry + +The following command requests special pool for all allocations with the **Tag1** pool tag. Because this setting is stored in the registry, you must restart the computer to make it effective, but it remains effective until you change it. + +This command uses the **/r** parameter to specify a registry setting and the +spp abbreviation to set a special pool request. + +``` +gflags /r +spp Tag1 +``` + +Gflags responds by printing: + +``` +Special Pool set to 0x31676154 +PoolTagOverruns set to 0x1 +Current Boot Registry Settings are: 00000000 +``` + +Notice that the special pool allocation request is not a registry flag setting and is not reflected in the registry settings value. + +Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to underruns, use the Gflags Dialog Box. For information, see [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md). + +To verify that the value has been added to the registry, use Reg or Regedit to display the value of the **PoolTag** entry in the **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management** key. + +For example: + +``` +c:>reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" -v PoolTag +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management + PoolTag REG_DWORD 0x31676154 +``` + +### Request Special Pool by size without rebooting + +The following command requests special pool for allocations of 1 to 8 bytes on an x86 computer with a PAGE\_SIZE of 0x1000 and allocation granularity of 8 bytes. + +This command uses the **/k** parameter to specify a kernel flag (run time) setting and the +spp abbreviation to set a special pool request. The size value is preceded by 0x to indicate that it is a size and not a pool tag. + +The value, 0x10, is calculated by adding the allocation granularity (8 bytes) to the largest size in the range (8 bytes) for a total of 16 bytes (0x10). For help in determining the correct value to enter, see "Selecting an Allocation Size" in [Special Pool](special-pool.md). + +``` +gflags /k +spp 0x10 +``` + +Gflags responds by printing: + +``` +Special Pool set to 0x10 +PoolTagOverruns set to 0x1 +Current Running Kernel Settings are: 00000000 +``` + +Again, the special pool allocation request is not a kernel flag setting and is not reflected in the kernel settings value. + +Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to underruns, use the Gflags Dialog Box. For information, see [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md). + +### Request Special Pool by size in the registry + +The following command requests special pool for allocations of 1024 to 1040 bytes on an x64 computer with a PAGE\_SIZE of 0x1000 and allocation granularity of 16 bytes. + +This command uses the **/r** parameter to specify a system-wide registry setting and the +spp abbreviation to set a special pool request. The size value is preceded by 0x to indicate that it is a size and not a pool tag. + +The value, 0x420, is calculated by adding the allocation granularity (16 bytes) to the largest size in the range (1040 bytes) for a total of 1056 bytes (0x420). For help in determining the correct value to enter, see "Selecting an Allocation Size" in [Special Pool](special-pool.md). + +``` +gflags /r +spp 0x420 +``` + +Gflags responds by printing: + +``` +Special Pool set to 0x420 +PoolTagOverruns set to 0x1 +Current Boot Registry Settings are: 00000000 +``` + +Again, the special pool allocation request is not a registry flag setting and is not reflected in the registry settings value. + +Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to underruns, use the Gflags Dialog Box. For information, see [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md). + +To verify that the value has been added to the registry, use Reg or Regedit to display the value of the **PoolTag** entry in the **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Memory Management** key. + +For example: + +``` +c:>reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" -v PoolTag +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management + PoolTag REG_DWORD 0x420 +``` + +### Cancel a Special Pool Request + +The following command cancels a request for Special Pool as a kernel flag (run time) setting. The command is the same for a request by pool tag or by size. + +``` +gflags /k -spp +``` + +The following command cancels a request for Special Pool as a registry setting. The command is the same for a request by pool tag or by size. + +``` +gflags /r -spp +``` + +When the command is successful, Gflags responds by printing: + +``` +Special Pool value has been deleted. +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2014:%20%20Configuring%20Special%20Pool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-15--using-object-reference-tracing.md b/windows-driver-docs-pr/debugger/example-15--using-object-reference-tracing.md new file mode 100644 index 0000000000..648273614f --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-15--using-object-reference-tracing.md @@ -0,0 +1,152 @@ +--- +title: Example 15 Using Object Reference Tracing +description: Example 15 Using Object Reference Tracing +ms.assetid: 3c6102e6-4dac-4d90-ab8f-162dd6d8adf9 +--- + +# Example 15: Using Object Reference Tracing + + +Object Reference Tracing is a Windows feature that records a sequential stack trace when an object is referenced or dereferenced. It is designed to detect errors in object handling that can lead to crashes or memory leaks. Some of these errors are difficult to detect because they do not appear consistently. For detailed information, see [Object Reference Tracing](object-reference-tracing.md). + +You can configure Object Reference Tracing by using the **Global Flags** dialog box or at a command prompt. The following examples use the command prompt. For information about using the **Global Flags** dialog box to configure Object Reference Tracing, see [Configuring Object Reference Tracing](configuring-object-reference-tracing.md). + +You can use Gflags to enable, disable, and configure Object Reference Tracing. The process is as follows: + +- **Use Gflags to enable Object Reference Tracing** in the registry or as a kernel flag (run time) setting. If you add the setting to the registry, you must restart the computer to start tracing. If you enable the run time version of the settings, the trace starts immediately, but the trace settings revert to those in the registry key when you shut down or restart the computer. + +- **Start the process that creates the suspect object**. The trace includes only objects created by processes that are started after the trace begins. If the process starts during or soon after restarting, add the trace settings to the registry, and then restart the system. + +- **Use the** [**!obtrace**](-obtrace.md) **debugger extension** to view the trace. By default, the trace is maintained until the object is destroyed, but you can use the **/p** parameter to maintain the trace until tracing is disabled. + +- **Use Gflags to disable Object Reference Tracing**.in the registry or as a kernel flag (run time) setting. If you delete the setting from the registry, you must restart the computer to end tracing. If you disable the run time version of the settings, the trace ends immediately, but the trace settings revert to those in the registry when you shut down or restart the computer. + +These examples show how to use Gflags to enable and disable object reference tracing. \\ + +### Enable Run-time Tracing + +The following command enables Object Reference Tracing at the command prompt. The command uses the **/ko** parameter to enable Object Reference Tracing as a kernel flag (run time) setting. The command uses the **/t** parameter to specify the pool tags **Tag1** and **Fred**. As a result, all objects that are created with **Tag1** or **Fred** are traced. + +``` +gflags /ko /t Tag1;Fred +``` + +Because the command changes the kernel flag (run-time) settings, object reference tracing starts immediately. The trace will include all objects with the pool tags **Tag1** or **Fred** that are created by processes that start after the command is submitted. + +Gflags responds by printing the following message: + +``` +Running Kernel Settings : +Object Ref Tracing Enabled + Temporary Traces + Pool Tags: Tag1;Fred + Process Name: All Processes +``` + +This message indicates that Object Reference Tracing is enabled. "Temporary Traces" indicates that all records of the trace are deleted when the object is destroyed. To make the trace "permanent," use the **/p** parameter, which directs Windows to retain the trace data until Object Reference Tracing is disabled, or the computer is shut down or restarted. + +### Enable Tracing in the Registry + +The following command adds an Object Reference Tracing configuration to the registry. The trace that you configure begins when you restart the computer. + +The command uses the **/ro** parameter to enable Object Reference Tracing as a registry setting. The command uses the **/i** to specify the process for notepad.exe and the **/t** parameter to specify the pool tags **Tag1** and **Fred**. As a result, all objects that are created by the Notepad process with the **Tag1** or **Fred** pool tags are traced. The command also uses the **/p** parameter, which retains the trace data until the tracing is disabled. + +``` +gflags /ro /t Tag1;Fred /i Notepad.exe /p +``` + +When you submit the command, Gflags stores the information in the registry. However, because registry settings are not effective until you restart the computer, this object reference tracing is configured, but is not yet started. + +Gflags responds by printing the following message: + +``` +Boot Registry Settings : +Object Ref Tracing Enabled + Permanent Traces + Pool Tags: Tag1;Fred + Process Name: Notepad.exe +``` + +The message indicates that Object Reference Tracing is enabled in the registry. "Permanent Traces" indicates that the trace data will be retained until you shut down or restart the computer. The message also lists the pool tags and image file names that will be traced. + +### Display the Object Reference Tracing Configuration + +You can display the Object Reference Tracing configuration that is currently effective or is stored in the registry to be used when the computer is restarted. + +In this example, there is one Object Reference Tracing configuration stored in the registry and a different one configured for run time. The run-time trace begins immediately (and overrides any registry settings). However, if you restart the system, the run-time settings are lost, and the Object Reference Tracing session registry settings become effective. + +The following command displays the run time Object Reference Tracing configuration. It uses the **/ko** parameter with no other parameters. + +``` +gflags /ko +``` + +``` +Running Kernel Settings : +Object Ref Tracing Enabled + Temporary Traces + Pool Tags: Tag1;Fred + Process Name: All Processes +``` + +If Object Reference Tracing is enabled, as it is in this example, the settings that are displayed describe a trace that is in progress. + +The following command displays the Object Reference Tracing configuration data stored in the registry. It uses the **/ro** parameter with no other parameters. + +``` +gflags /ro +``` + +In response, Gflags displays the data stored in the registry: + +``` +Boot Registry Settings : +Object Ref Tracing Enabled + Permanent Traces + Pool Tags: Tag1;Fred + Process Name: Notepad.exe +``` + +If you have restarted the computer since you added the Object Reference Tracing configuration to the registry, the settings that are displayed in response to a gflags /ro command describe the trace that is in progress. However, if you have not yet restarted, or you have restarted, but then started a run-time object reference trace (**/ko**), the settings that are stored in the registry are not currently effective, but they will become effective again when you reboot the system. + +### Disable Object Reference Tracing + +When you disable run-time (kernel flag) Object Reference Tracing settings, the trace stops immediately. When you disable Object Reference Tracing settings in the registry, the trace stops when you restart the computer. + +The following command disables run-time Object Reference Tracing. It uses the **/d** parameter to disable all settings. You cannot disable settings selectively. + +``` +gflags /ko -d +``` + +When the command succeeds, Gflags responds with the following message: + +``` +Running Kernel Settings : +Object Ref Tracing Disabled +``` + +The following command disables run-time Object Reference Tracing. + +The following command disables Object Reference Tracing settings in the registry. It uses the **/d** parameter to disable all settings. You cannot disable settings selectively. This command is effective when you restart the computer. + +``` +gflags /ro -d +``` + +When the command succeeds, Gflags responds with the following message: + +``` +Boot Registry Settings : +Object Ref Tracing Disabled +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%2015:%20Using%20Object%20Reference%20Tracing%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-2---setting-a-flag-by-using-a-flag-abbreviation.md b/windows-driver-docs-pr/debugger/example-2---setting-a-flag-by-using-a-flag-abbreviation.md new file mode 100644 index 0000000000..a6e09d544c --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-2---setting-a-flag-by-using-a-flag-abbreviation.md @@ -0,0 +1,36 @@ +--- +title: Example 2 Setting a Flag by Using a Flag Abbreviation +description: Example 2 Setting a Flag by Using a Flag Abbreviation +ms.assetid: 3c011ca5-8901-4bf2-b95d-364d644cb476 +--- + +# Example 2: Setting a Flag by Using a Flag Abbreviation + + +## + + +The following command sets the [Show loader snaps](show-loader-snaps.md) flag for the notepad.exe image file. **Show Loader Snaps** takes snapshots of the load process, capturing in detail the loading and unloading of executable images and their supporting library modules. + +The command uses the **/i** parameter to indicate image file mode and specifies the name of the image file notepad.exe. To identify the flag, the command uses **sls**, the abbreviation for **Show Loader Snaps**, and it precedes the abbreviation with a plus sign (+) to indicate that the flag is set. Without the plus sign, the command has no effect. + +``` +gflags /i notepad.exe +sls +``` + +In response, GFlags displays the flags set for notepad.exe. The display indicates that the command is successful. The **Show Loader Snaps** feature is enabled for all new sessions of the Notepad program. + +``` +Current Registry Settings for notepad.exe executable are: 00000002 + sls - Show Loader Snaps +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%202:%20%20Setting%20a%20Flag%20by%20Using%20a%20Flag%20Abbreviation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-3---setting-a-flag-by-using-its-hexadecimal-value.md b/windows-driver-docs-pr/debugger/example-3---setting-a-flag-by-using-its-hexadecimal-value.md new file mode 100644 index 0000000000..af177ff40c --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-3---setting-a-flag-by-using-its-hexadecimal-value.md @@ -0,0 +1,38 @@ +--- +title: Example 3 Setting a Flag by Using Its Hexadecimal Value +description: Example 3 Setting a Flag by Using Its Hexadecimal Value +ms.assetid: 64fa0b2e-9fe7-47d0-bf83-8ae7c06252b6 +--- + +# Example 3: Setting a Flag by Using Its Hexadecimal Value + + +## + + +The following command sets the system-wide [Enable page heap](enable-page-heap.md) flag. **Enable Page Heap** adds a guard page and other tracking features to each heap allocation. + +The command uses the **/r** parameter to indicate system-wide registry mode. To identify the flag, the command uses **2000000**, which represents 0x2000000, the hexadecimal value for **Enable page heap**. + +Although the command sets a flag, it omits the plus (+) sign. When using hexadecimal values, the sign is optional and add (+) is the default. + +``` +gflags /r 2000000 +``` + +In response, GFlags displays the system-wide flags set in the registry. The display indicates that the command is successful. The **Enable page heap** feature will be enabled for all processes when Windows restarts. + +``` +Current Boot Registry Settings are: 02000000 + hpa - Enable page heap +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%203:%20%20Setting%20a%20Flag%20by%20Using%20Its%20Hexadecimal%20Value%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-4---setting-multiple-flags.md b/windows-driver-docs-pr/debugger/example-4---setting-multiple-flags.md new file mode 100644 index 0000000000..bc25bed376 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-4---setting-multiple-flags.md @@ -0,0 +1,54 @@ +--- +title: Example 4 Setting Multiple Flags +description: Example 4 Setting Multiple Flags +ms.assetid: b8c7301b-4a34-4f03-8c5e-ba43a1fb3681 +--- + +# Example 4: Setting Multiple Flags + + +## + + +The following command sets these three flags for the current session: + +- [Enable heap free checking](enable-heap-free-checking.md) (hfc, 0x20) + +- [Enable heap parameter checking](enable-heap-parameter-checking.md) (hpc, 0x40) + +- [Enable heap validation on call](enable-heap-validation-on-call.md) (hvc, 0x80) + +This command uses the **/k** parameter to specify kernel mode (session only). It sets the value for kernel mode to **E0** (0xE0), the sum of the hexadecimal values of the selected flags (0x20 + 0x40 + 0x80). + +``` +gflags /k e0 +``` + +In response, GFlags displays the revised value of flags set for the session. The display indicates that the command is successful and that the three flags specified in the command are set. + +``` +Current Running Kernel Settings are: 000000e0 + hfc - Enable heap free checking + hpc - Enable heap parameter checking + hvc - Enable heap validation on call +``` + +You can use several different GFlags commands to set flags. Each of the following commands has the same effect as the command used in this example and the methods can be used interchangeably: + +``` +gflags /k +20 +40 +80 +gflags /k +E0 +gflags /k +hfc +hpc +hvc +``` + +Kernel (run time) flags are effective immediately and remain effective until Windows shuts down. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%204:%20%20Setting%20Multiple%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-5---clearing-a-flag.md b/windows-driver-docs-pr/debugger/example-5---clearing-a-flag.md new file mode 100644 index 0000000000..315d29b468 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-5---clearing-a-flag.md @@ -0,0 +1,39 @@ +--- +title: Example 5 Clearing a Flag +description: Example 5 Clearing a Flag +ms.assetid: 63c8bae9-ae6e-4d82-9389-ec36554635ab +--- + +# Example 5: Clearing a Flag + + +## + + +The following command clears the system-wide [Enable page heap](enable-page-heap.md) flag set in the registry. The command uses the **/r** parameter to indicate the system-wide registry mode and **hpa**, the abbreviation for the **Enable page heap** flag. The minus sign (-) indicates that the flag is to be cleared. + +``` +gflags /r -hpa +``` + +In response, GFlags displays the current value of the system-wide registry entry. The display indicates that the command is successful and that there are no longer any flags set. + +``` +Current Boot Registry Settings are: 00000000 +``` + +Note that the following command, which uses the hexadecimal value of the **Enable Page Heap** flag, has the same effect as the command used in this example. These commands can be used interchangeably: + +``` +gflags /r -02000000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%205:%20%20Clearing%20a%20Flag%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-6---clearing-all-flags.md b/windows-driver-docs-pr/debugger/example-6---clearing-all-flags.md new file mode 100644 index 0000000000..bb692c7cfa --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-6---clearing-all-flags.md @@ -0,0 +1,89 @@ +--- +title: Example 6 Clearing All Flags +description: Example 6 Clearing All Flags +ms.assetid: 07a6af3d-3ef7-429d-9afa-439b20915ab1 +--- + +# Example 6: Clearing All Flags + + +## + + +This example demonstrates two different ways to clear all flags set in the registry and for the session: + +- Subtract the current flag value. + +- Subtract high values. + +**Note**   The methods demonstrated by this example clear flags only. They do not reset the maximum stack trace size or kernel special pool tag to the default values. + +  + +### Subtract the Current Flag Value + +The following command clears all flags set in the system-wide flag entry in the registry by subtracting the current value of the entry. In this example, the current value is 0xE0. The command uses the **/r** parameter to indicate the system-wide registry mode and the E0 value with a minus sign (-) to subtract E0 from the flag value. + +``` +gflags /r -E0 +``` + +In response, GFlags displays the revised value of system-wide flag registry entry. A value of zero indicates that the command is successful and that there are no longer any system-wide flags set in the registry. + +``` +Current Boot Registry Settings are: 00000000 +``` + +Note that the following commands have the same effect as the command used in this example and can be used interchangeably: + +``` +gflags /r -20 -40 -80 +gflags /r -hfc -hpc -hvc +``` + +### Subtract High Values + +The following command clears all system-wide flags by subtracting high values (0xFFFFFFFF) from the system-wide flag setting. + +``` +gflags /r -ffffffff +``` + +In response, GFlags displays the revised value of the system-wide flag entry. A value of zero indicates that the command is successful and that there are no longer any system-wide flags set in the registry. + +``` +Current Boot Registry Settings are: 00000000 +``` + +**Tip**   Type this command into Notepad, then save the file as clearflag.bat. Thereafter, to clear all flags, just type **ClearFlag**. + +  + +Finally, the following example demonstrates that the intuitive method of clearing all flags does not work. + +The following command appears to set the value of the system-wide flag entry to 0. However, it actually adds zero to the system-wide flag value. In this example, the current value of the system-wide flag entry is 0xE0. + +``` +gflags /r 0 +``` + +In response, GFlags displays the system-wide flag value after the command completes: + +``` +Current Boot Registry Settings are: 000000e0 + hfc - Enable heap free checking + hpc - Enable heap parameter checking + hvc - Enable heap validation on call +``` + +The command has no effect because it adds the value 0 to system-wide flag entry. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%206:%20%20Clearing%20All%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-7---clearing-all-flags-for-an-image-file.md b/windows-driver-docs-pr/debugger/example-7---clearing-all-flags-for-an-image-file.md new file mode 100644 index 0000000000..e49ed9002c --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-7---clearing-all-flags-for-an-image-file.md @@ -0,0 +1,35 @@ +--- +title: Example 7 Clearing All Flags for an Image File +description: Example 7 Clearing All Flags for an Image File +ms.assetid: 832c79de-07ca-4212-b3b3-ace396986ebb +--- + +# Example 7: Clearing All Flags for an Image File + + +## + + +The following command clears all flags and image debugger options for an image file. The command adds high-values (0xFFFFFFFF) to the current flag value. GFlags responds by deleting the **GlobalFlag** registry entry for the image file, thereby deleting all of the values it stores. + +This command does not affect flags set in the system-wide **GlobalFlag** registry entry or flags set for the session (kernel mode). + +``` +gflags /i notepad.exe ffffffff +``` + +In response, GFlags displays a message indicating that there are no flags set for the image file: + +``` +No Registry Settings for notepad.exe executable +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%207:%20%20Clearing%20All%20Flags%20for%20an%20Image%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-8---enlarging-the-user-mode-stack-trace-database.md b/windows-driver-docs-pr/debugger/example-8---enlarging-the-user-mode-stack-trace-database.md new file mode 100644 index 0000000000..d6767de017 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-8---enlarging-the-user-mode-stack-trace-database.md @@ -0,0 +1,71 @@ +--- +title: Example 8 Enlarging the User-Mode Stack Trace Database +description: Example 8 Enlarging the User-Mode Stack Trace Database +ms.assetid: b04f6b86-a210-4941-a4eb-a9059d9890d9 +--- + +# Example 8: Enlarging the User-Mode Stack Trace Database + + +## + + +The following GFlags command increases the maximum size of the user-mode stack trace database for myapp.exe, a fictitious program, from 8 MB to 24 MB. + +The command uses the **/i** parameter to specify the image file. It uses the **/tracedb** parameter to set the maximum stack trace database size and the value 24 to indicate the size in megabytes. The command uses decimal units. (Hexadecimal units are not valid.) + +``` +gflags /i MyApp.exe /tracedb 24 +``` + +As the following error message indicates, this command fails because the [Create user mode stack trace database](create-user-mode-stack-trace-database.md) (+ust) flag is not set for the MyApp image file. You cannot set the size of a trace database until you create one. + +``` +Failed to set the trace database size for `MyApp.exe' +``` + +The following commands fix the error. The first command creates a trace database for myapp.exe and the second command sets the maximum size of the trace database to 24 MB. These commands cannot be combined into a single command. The following display shows the commands and the success message from GFlags. + +``` +gflags /i MyApp.exe +ust + +Current Registry Settings for MyApp.exe executable are: 00001000 + ust - Create user mode stack trace database + +gflags /i MyApp.exe /tracedb 24 + +Trace database size for `MyApp.exe' set to 24 Mb. +``` + +GFlags can change the size of the user-mode stack trace database, but it does not display it. To display the trace database size, use registry APIs, Regedit, or Reg (reg.exe), a tool included in Windows XP and Windows Server 2003, to check the value of the **StackTraceDatabaseSizeInMB** registry entry (HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Image File Execution Options\\*ImageFileName*\\**StackTraceDatabaseSizeInMB**). + +(A version of Reg is included in Windows XP, but that version does not permit the **/v** and **/s** switches in the same command.) + +The following command uses Reg to query the value of **StackTraceDatabaseSizeInMB**: + +``` +reg query "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\MyApp.exe" /v StackTraceDatabaseSizeInMB +``` + +In response, Reg displays the value of **StackTraceDatabaseSizeInMB**, which confirms that the new value, 24 (0x18), was set. This value becomes effective when you restart myapp.exe. + +``` +! REG.EXE VERSION 3.0 + +HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\MyApp.exe + StackTraceDatabaseSizeInMB REG_DWORD 0x18 +``` + +**Tip**   Type the **reg query** command into Notepad, then save the file as tracedb.bat. Thereafter, to display the value of **StackTraceDatabaseSizeInMB**, just type **TraceDb**. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%208:%20%20Enlarging%20the%20User-Mode%20Stack%20Trace%20Database%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/example-9---detecting-a-pool-memory-leak.md b/windows-driver-docs-pr/debugger/example-9---detecting-a-pool-memory-leak.md new file mode 100644 index 0000000000..1c765de9e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/example-9---detecting-a-pool-memory-leak.md @@ -0,0 +1,86 @@ +--- +title: Example 9 Detecting a Pool Memory Leak +description: Example 9 Detecting a Pool Memory Leak +ms.assetid: 3f634593-a024-46d1-9f3d-9d39b28bab03 +keywords: ["PoolMon, PoolMon and GFlags"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Example 9: Detecting a Pool Memory Leak + + +## + + +The following example uses GFlags to set the system-wide [Enable pool tagging](enable-pool-tagging.md) flag in the registry. Then, it uses PoolMon (poolmon.exe), a tool in the Windows Driver Kit, to display the size of the memory pools. + +PoolMon monitors the bytes in the paged and nonpaged memory pools and sorts them by pool tag. By running PoolMon periodically, you can identify pools that expand continuously over time. This pattern often indicates a memory leak. + +**Note**   Pool tagging is permanently enabled in Windows Server 2003 and later versions of Windows. On these systems, the **Enable pool tagging** check box on the **Global Flags** dialog box is dimmed, and commands to enable or disable pool tagging fail. +If pool tagging is not enabled, PoolMon fails and displays the following message: "Query pooltags Failed c0000002." + +  + +**To detect a pool memory leak** + +1. To enable pool tagging for all processes in versions of Windows earlier than Windows Server 2003, set the system-wide [Enable pool tagging](enable-pool-tagging.md) flag in the registry. The following command line uses the flag abbreviation method, but you can identify the flag by its hexadecimal value or use the **Global Flags** dialog box: + ``` + gflags /r +ptg + ``` + +2. Restart the computer to make the registry change effective. + +3. Run PoolMon periodically by using the following command. In this command, the **/b** parameter sorts the pools in descending size order. + + ``` + poolmon /b + ``` + + In response, PoolMon displays allocations from the memory pools in descending size order , including the number of allocate operations and free operations, and the amount of memory remaining in the pool (in the Bytes column). + + ``` + Memory: 16224K Avail: 4564K PageFlts: 31 InRam Krnl: 684K P: 680K + Commit: 24140K Limit: 24952K Peak: 24932K Pool N: 744K P: 2180K + + Tag Type Allocs Frees Diff Bytes Per Alloc + ----------------------------------------------------------------------- + + CM Paged 1283 ( 0) 1002 ( 0) 281 1377312 ( 0) 4901 + Strg Paged 10385 ( 10) 6658 ( 4) 3727 317952 ( 512) 85 + Fat Paged 6662 ( 8) 4971 ( 6) 1691 174560 ( 128) 103 + MmSt Paged 614 ( 0) 441 ( 0) 173 83456 ( 0) 482 + ``` + + If the value in the **Bytes** column for an allocation expands continuously for no obvious reason, there might be a memory leak in that pool. + +4. Clear the **Enable pool tagging** flag. + + The following command line uses the flag abbreviation method, but you can identify the flag by its hexadecimal value or use the **Global Flags** dialog box: + + ``` + gflags /r -ptg + ``` + +5. Restart Windows to make the registry change effective. + +**Note**   Use the append symbol (**>>**) to redirect the PoolMon output to a log file. Later, you can examine the log file for pool size trends. For example: + +  + +``` +poolmon.exe /b >> poolmon.log +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Example%209:%20%20Detecting%20a%20Pool%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/executing-a-debugger-command-program.md b/windows-driver-docs-pr/debugger/executing-a-debugger-command-program.md new file mode 100644 index 0000000000..905123fc0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/executing-a-debugger-command-program.md @@ -0,0 +1,35 @@ +--- +title: Executing a Debugger Command Program +description: Executing a Debugger Command Program +ms.assetid: ad28a5d6-0d6a-42c0-82f3-6760a8c773ab +keywords: ["debugger command program, execution"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Executing a Debugger Command Program + + +## + + +You can execute a debugger command program in one of the following ways: + +- Enter all of the statements in the [Debugger Command window](debugger-command-window.md) as a single string, with individual statements and commands separated by semicolons. + +- Add all of the statements in a script file on a single line, with individual statements and commands separated by semicolons. Then, run this script file by using one of the methods described in [Using Script Files](using-script-files.md). + +- Add all of the statements in a script file, with each statement on a separate line. (Alternatively, separate statements by any combination of carriage returns and semicolons.) Then, run this script file by using the [**$>< (Run Script File)**](-----------------------a---run-script-file-.md) or **$$>< (Run Script File)** command. These commands open the specified script file, replace all carriage returns with semicolons, and execute the resulting text as a single command block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Executing%20a%20Debugger%20Command%20Program%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/executing-until-a-specified-state-is-reached.md b/windows-driver-docs-pr/debugger/executing-until-a-specified-state-is-reached.md new file mode 100644 index 0000000000..dddf344352 --- /dev/null +++ b/windows-driver-docs-pr/debugger/executing-until-a-specified-state-is-reached.md @@ -0,0 +1,81 @@ +--- +title: Executing Until a Specified State is Reached +description: Executing Until a Specified State is Reached +ms.assetid: 0657a7bf-4d72-4248-9e45-d79d51b91139 +keywords: ["executing until a specified state is reached", "breakpoints, used to control execution", "breakpoints, and pseudo-registers", "script file, used to control execution"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Executing Until a Specified State is Reached + + +## + + +There are several ways to cause the target to execute until a specified state is reached. + +### Using a Breakpoint to Control Execution + +One method is to use a breakpoint. The simplest breakpoint halts execution when the program counter reaches a specified address. A more complex breakpoint can: + +- be triggered only when this address is executed by a specific thread, + +- allow a specified number of passes through this address before being triggered, + +- automatically issue a specified command when it is triggered, or + +- watch a specified address in non-executable memory, being triggered when that memory is read or written to. + +For details on how to set and control breakpoints, see [Using Breakpoints](using-breakpoints.md). + +A more complicated way to execute until a specified state is reached is to use a *conditional breakpoint*. This kind of breakpoint is set at a certain address, but is only triggered if a specified condition holds. For details, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +### Breakpoints and Pseudo-Registers + +In specifying the desired state, it is often helpful to use *automatic pseudo-registers*. These are variables controlled by the debugger which allow you to reference a variety of values related to the target state. + +For example, the following breakpoint uses the **$thread** pseudo-register, which is always equal to the value of the current thread. It resolves to the value of the current thread when it is used in a command. By using **$thread** as the argument of the **/t** parameter of the [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command, you can create a breakpoint that will be triggered every time that **NtOpenFile** is called by the thread which was active at the time you issued the **bp** command: + +``` +kd> bp /t @$thread nt!ntopenfile +``` + +This breakpoint will not be triggered when any other thread calls **NtOpenFile**. + +For a list of automatic pseudo-registers, see [Pseudo-Register Syntax](pseudo-register-syntax.md). + +### Using a Script File to Control Execution + +Another way to execute until a specified state is reached is to create a script file that calls itself recursively, testing the desired state in each iteration. + +Typically, this script file will contain the [**.if**](-if.md) and [**.else**](-else.md) tokens. You can use a command such as [**t (Trace)**](t--trace-.md) to execute a single step, and then test the condition in question. + +For example, if you wish to execute until the **eax** register contains the value 0x1234, you can create a script file called *eaxstep* that contains the following line: + +``` +.if (@eax == 1234) { .echo 1234 } .else { t "$ + + +A powerful way to manipulate log files is to export them to text. This allows you to find specific parameter values by using the Find facility of any text editor. Although it is possible for a text file to be generated by Logger directly, you will have more flexibility if you use LogViewer to filter the function calls or add aliasing, and then export this information into a text file. + +To create a text file from an .lgv file, open the file in LogViewer, and then select **File | Export to Text**. In the dialog box, choose a file name and location. + +There are several options at the bottom of the dialog box: + +**Export Diff Information** +This option will alias all pointers, handle values, and other values that change from execution to execution. Instead of outputting the actual value of a pointer (for example, "0x00123FA2"), LogViewer will output "Pointer." Similarly, handles will be aliased as "HeapHandle1" or some other value that will not register as a *diff* when the two files are compared using a differencing tool. + +**Include Non-Visible Rows** +This option disables whatever filters are currently applied to the view while exporting. + +**Create a Separate File For Each Thread** +This option splits up the text file by thread, making it easier to follow a thread of execution. This is useful if you intend to "diff" two instances of execution. + +**Export Range** +This option specifies the range of rows to export. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Exporting%20LogViewer%20Files%20to%20Text%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/expression-examples.md b/windows-driver-docs-pr/debugger/expression-examples.md new file mode 100644 index 0000000000..0f86afcbb6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/expression-examples.md @@ -0,0 +1,102 @@ +--- +title: Expression Examples +description: Expression Examples +ms.assetid: a4915678-a83f-48f1-8b29-50cf530f9246 +keywords: ["expressions, examples", "MASM expressions, examples", "C++ expressions, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Expression Examples + + +## + + +This topics contains examples of MASM and C++ expressions that are used in various commands. + +All other sections of this Help documentation use MASM expression syntax in the examples (unless otherwise noted). C++ expression syntax is very useful for manipulating structures and variables, but it does not parse the parameters of debugger commands very well. + +If you are using debugger commands for general purposes or using debugger extensions, you should set MASM expression syntax as the default syntax. If you must have a specific parameter to use C++ expression syntax, use the **@@( )** syntax. + +### Conditional Breakpoints + +You can use comparison operators to create [conditional breakpoints](setting-a-conditional-breakpoint.md). The following code example uses MASM expression syntax. Because the current default radix is 16, the example uses the **0n** prefix so that the number 20 is understood as a decimal number. + +``` +0:000> bp MyFunction+0x43 "j ( poi(MyVar)>0n20 ) ''; 'gc' " +``` + +In the previous example, **MyVar** is an integer in the C source. Because the MASM parser treats all symbols as addresses, the example must have the **poi** operator to dereference **MyVar**. + +### Conditional Expressions + +The following example prints the value of **ecx** if **eax** is greater than **ebx**, 7 if **eax** is less than **ebx**, and 3 if **eax** equals **ebx**. This example uses the MASM expression evaluator, so the equal sign (=) is a comparison operator, not an assignment operator. + +``` +0:000> ? ecx*(eax>ebx) + 7*(eax ?? @ecx*(int)(@eax>@ebx) + 7*(int)(@eax<@ebx) + 3*(int)(@eax==@ebx) +``` + +### C++ Expression Examples + +If **myInt** is a ULONG32 value and if you are using the MASM expression evaluator, the following two examples show the value of **MyInt**. + +``` +0:000> ?? myInt +0:000> dd myInt L1 +``` + +However, the following example shows the *address* of **myInt**. + +``` +0:000> ? myInt +``` + +### Mixed Expression Examples + +You cannot use source-line expressions in a C++ expression. The following example uses the **@@( )** syntax to nest an MASM expression within a C++ expression. This example sets **MyPtr** equal to the address of line 43 of the Myfile.c file. + +``` +0:000> ?? MyPtr = @@( `myfile.c:43` ) +``` + +The following examples set the default expression evaluator to MASM and then evaluate *Expression2* as a C++ expression, and evaluate *Expression1* and *Expression3* as MASM expressions. + +``` +0:000> .expr /s masm +0:000> bp Expression1 + @@( Expression2 ) + Expression3 +``` + +If **myInt** is a ULONG64 value and if you know that this value is followed in memory by another ULONG64, you can set an access breakpoint at that location by using one of the following examples. (Note the use of pointer arithmetic.) + +``` +0:000> ba r8 @@( &myInt + 1 ) +0:000> ba r8 myInt + 8 +``` + +### Structures + +The C++ expression evaluator casts pseudo-registers to their appropriate types. For example, **$teb** is cast as a TEB\*. The following example displays the process ID. + +``` +kd> ?? @$teb->ClientId.UniqueProcess +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Expression%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/extensions-for-debugging-plug-and-play-drivers.md b/windows-driver-docs-pr/debugger/extensions-for-debugging-plug-and-play-drivers.md new file mode 100644 index 0000000000..3f0653a1a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/extensions-for-debugging-plug-and-play-drivers.md @@ -0,0 +1,226 @@ +--- +title: Extensions for Debugging Plug and Play Drivers +description: Extensions for Debugging Plug and Play Drivers +ms.assetid: 0b60c4ce-5c2d-4cce-a1e6-8275186aa147 +keywords: ["Plug and Play (PnP), extensions", "extensions, plug and play"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extensions for Debugging Plug and Play Drivers + + +When you debug Plug and Play drivers, you may find the following debugger extensions useful. + +[**!arbiter**](-arbiter.md) +Displays the current system resource arbiters. An arbiter is a piece of code that is exposed by the bus driver that arbitrates requests for resources, and attempts to solve the resource conflicts among the devices connected on that bus. + +[**!cmreslist**](-cmreslist.md) +Displays the CM\_RESOURCE\_LIST for the specified device object. + +You must know the address of the CM Resource List. + +Here is an example: + +``` +kd> !cmreslist 0xe12576e8 + +CmResourceList at 0xe12576e8 Version 0.0 Interface 0x1 Bus #0 + Entry 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x01) - PORT_MEMORY PORT_IO + Range starts at 0x3f8 for 0x8 bytes + Entry 1 - Interrupt (0x2) Shared (0x3) + Flags (0x01) - LATCHED + Level 0x4, Vector 0x4, Affinity 0xffffffff +``` + +This shows that the device with this CM resource list is using I/O Range 3F8-3FF and IRQ 4. + +[**!dcs**](-dcs.md) +This extension is obsolete -- its functionality has been subsumed by [**!pci**](-pci.md). See the !pci 100 example later in this section. + +[**!devext**](-devext.md) +Displays bus-specific device extension information for a variety of devices. + +[**!devnode**](-devnode.md) +Displays information about a node in the device tree. + +Device node 0 (zero) is the root of the device tree. + +Here is an example: + +``` +0: kd> !devnode 0xfffffa8003634af0 +DevNode 0xfffffa8003634af0 for PDO 0xfffffa8003658590 + Parent 0xfffffa8003604010 Sibling 0xfffffa80036508e0 Child 0000000000 + InstancePath is "ROOT\SYSTEM\0000" + ServiceName is "swenum" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[09] = DeviceNodeEnumerateCompletion (0x30d) + StateHistory[08] = DeviceNodeEnumeratePending (0x30c) + StateHistory[07] = DeviceNodeStarted (0x308) + StateHistory[06] = DeviceNodeStartPostWork (0x307) + StateHistory[05] = DeviceNodeStartCompletion (0x306) + StateHistory[04] = DeviceNodeStartPending (0x305) + ... + Flags (0x6c000131) DNF_MADEUP, DNF_ENUMERATED, + DNF_IDS_QUERIED, DNF_NO_RESOURCE_REQUIRED, + DNF_NO_LOWER_DEVICE_FILTERS, DNF_NO_LOWER_CLASS_FILTERS, + DNF_NO_UPPER_DEVICE_FILTERS, DNF_NO_UPPER_CLASS_FILTERS + UserFlags (0x00000008) DNUF_NOT_DISABLEABLE + DisableableDepends = 1 (including self) +``` + +[**!devobj**](-devobj.md) +Displays detailed information about a DEVICE\_OBJECT. + +Here is an example: + +``` +kd> !devobj 0xff0d4af0 + +Device object (ff0d4af0) is for: + 00252d \Driver\PnpManager DriverObject ff0d9030 +Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040AttachedDev ff0b59e0 + +DevExt ff0d4ba8 DevNode ff0d4a08 +Device queue is not busy. +``` + +[**!drivers**](-drivers.md) +The [**!drivers**](-drivers.md) command is no longer supported. Please use the [**lm t n**](lm--list-loaded-modules-.md) command instead. + +[**!drvobj**](-drvobj.md) +Displays detailed information about a DRIVER\_OBJECT. + +Lists all the device objects created by the specified driver. + +Here is an example: + +``` +kd> !drvobj serial + +Driver object (ff0ba630) is for: + \Driver\Serial +Driver Extension List: (id , addr) + +Device Object list: +ffba3040 ff0b4040 ff0b59e0 ff0b5040 +``` + +[**!ecb, !ecd, !ecw**](-ecb---ecd---ecw.md) +(x86 target computers only) Writes a sequence of values into the PCI configuration space. + +[**ib, iw, id**](-ib---id---iw.md) +Reads data from an I/O port. + +These three commands are useful for determining whether a certain I/O range is claimed by a device other than the driver being debugged. A byte value of 0xFF at a port indicates that the port is not in use. + +[**!ioreslist**](-ioreslist.md) +Displays the specified IO\_RESOURCE\_REQUIREMENTS\_LIST. + +[**!irp**](-irp.md) +Displays information about an IRP. + +[**!irpfind**](-irpfind.md) +Displays information about all IRPs currently allocated in the target system, or information about those IRPs whose fields match the specified search criteria. + +[**!pci**](-pci.md) +(x86 target computers only) Displays the current status of the PCI buses and any devices attached to them. It can also display the PCI configuration space. + +The following example displays the devices on the primary bus: + +``` +kd> !pci +PCI Bus 0 +00:0 8086:1237.02 Cmd[0106:.mb..s] Sts[2280:.....] Device Host bridge +0d:0 8086:7000.01 Cmd[0007:imb...] Sts[0280:.....] Device ISA bridge +0d:1 8086:7010.00 Cmd[0005:i.b...] Sts[0280:.....] Device IDE controller +0e:0 1011:0021.01 Cmd[0107:imb..s] Sts[0280:.....] PciBridge 0->1-1 PCI-PCI + bridge +10:0 5333:8811.43 Cmd[0023:im.v..] Sts[0200:.....] Device VGA compatible controller + + + +The following example displays the devices for the secondary bus, with verbose output: + +kd> !pci 1 1 + +PCI Bus 1 +08:0 10b7:5900.00 Cmd[0107:imb..s] Sts[0200:.....] Device Ethernet + cf8:80014000 IntPin:1 IntLine:f Rom:fa000000 cis:0 cap:0 + IO[0]:fce1 + +09:0 9004:8178.00 Cmd[0117:imb..s] Sts[0280:.....] Device SCSI controller + cf8:80014800 IntPin:1 IntLine:f Rom:fa000000 cis:0 cap:0 + IO[0]:f801 MEM[1]:f9fff000 + +0b:0 9004:5800.10 Cmd[0116:.mb..s] Sts[0200:.....] Device SubID:9004:8940 +1394 host controller + cf8:80015800 IntPin:1 IntLine:e Rom:fa000000 cis:0 cap:0 + MEM[0]:f9ffec00 +``` + +The following example displays the PCI configuration space for the SCSI controller (bus 1, device 9, function 0): + +``` +kd> !pci 100 1 9 0 +00: 9004 ;VendorID=9004 +02: 8178 ;DeviceID=8178 +04: 0117 ;Command=SERREnable,MemWriteEnable,BusInitiate,MemSpaceEnable,IOSpac +eEnable +06: 0280 ;Status=FB2BCapable,DEVSELTiming:1 +08: 00 ;RevisionID=00 +09: 00 ;ProgIF=00 (SCSI bus controller) +0a: 00 ;SubClass=00 +0b: 01 ;BaseClass=01 (Mass storage controller) +0c: 08 ;CacheLineSize=Burst8DW +0d: 20 ;LatencyTimer=20 +0e: 00 ;HeaderType=00 +0f: 00 ;BIST=00 +10: 0000f801;BAR0=0000f801 +14: f9fff000;BAR1=f9fff000 +18: 00000000;BAR2=00000000 +1c: 00000000;BAR3=00000000 +20: 00000000;BAR4=00000000 +24: 00000000;BAR5=00000000 +28: 00000000;CBCISPtr=00000000 +2c: 0000 ;SubSysVenID=0000 +2e: 0000 ;SubSysID=0000 +30: fa000000;ROMBAR=fa000000 +34: 00000000;Reserved=00000000 +38: 00000000;Reserved=00000000 +3c: 0f ;IntLine=0f +3d: 01 ;IntPin=01 +3e: 08 ;MinGnt=08 +3f: 08 ;MaxLat=08 +40: 00001580,00001580,00000000,00000000,00000000,00000000,00000000,00000000 +60: 00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000 +80: 00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000 +a0: 00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000 +c0: 00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000 +e0: 00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000 +``` + +[**!pcitree**](-pcitree.md) +Displays information about PCI device objects, including child PCI buses and CardBus buses, as well as the devices attached to them. + +[**!pnpevent**](-pnpevent.md) +Displays the PnP device event queue. + +[**!rellist**](-rellist.md) +Displays a PnP relation list and any related CM\_RESOURCE\_LIST and IO\_RESOURCE\_LIST structures. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Extensions%20for%20Debugging%20Plug%20and%20Play%20Drivers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/extensions-for-debugging-scsi-miniport-drivers.md b/windows-driver-docs-pr/debugger/extensions-for-debugging-scsi-miniport-drivers.md new file mode 100644 index 0000000000..512eb2e219 --- /dev/null +++ b/windows-driver-docs-pr/debugger/extensions-for-debugging-scsi-miniport-drivers.md @@ -0,0 +1,177 @@ +--- +title: Extensions for Debugging SCSI Miniport Drivers +description: Extensions for Debugging SCSI Miniport Drivers +ms.assetid: 6e6c35e5-d9dd-430a-8fc4-86f24344c24d +keywords: ["SCSI Miniport Debugging, useful extensions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extensions for Debugging SCSI Miniport Drivers + + +When you debug SCSI miniport drivers, you may find the following debugger extensions useful. General debugger extensions are listed first, followed by those specific to SCSI miniport debugging. + +[**!devobj**](-devobj.md) +The **!devobj** extension displays detailed information about a DEVICE\_OBJECT. If the **Current Irp** field is nonnull, this could be caused by the SCSI driver waiting for map registers. + +Here is an example: + +``` +0: kd> !devobj 8633da70 +Device object (8633da70) is for: + adpu160m1 \Driver\adpu160m DriverObject 8633eeb8 +Current Irp 860ef008 RefCount 0 Type 00000004 Flags 00000050 +Dacl e129871c DevExt 8633db28 DevObjExt 8633dfd0 +ExtensionFlags (0000000000) +AttachedTo (Lower) 863b2978 \Driver\PCI +Device queue is not busy. +``` + +[**!errlog**](-errlog.md) +The **!errlog** extension displays the contents of any pending entries in the I/O system's error log. + +[**!object**](-object.md) +The **!object** extension displays information about a system object. This extension displays all SCSI devices. + +For example: + +``` +0: kd> !object \device\scsi +Object: e12a2520 Type: (863d12c8) Directory + ObjectHeader: e12a2508 + HandleCount: 0 PointerCount: 9 + Directory Object: e1001100 Name: Scsi + + Hash Address Type Name + ---- ------- ---- ---- + 04 86352040 Device adpu160m1Port3Path0Target6Lun0 + 11 86353040 Device adpu160m1Port3Path0Target1Lun0 + 13 86334a70 Device lp6nds351 + 22 862e6040 Device adpu160m1Port3Path0Target0Lun0 + 24 8633da70 Device adpu160m1 + 25 86376040 Device adpu160m2 + 34 862e5040 Device adpu160m1Port3Path0Target2Lun0 +``` + +[**!pcr**](-pcr.md) +The **!pcr** extension displays detailed information about the Processor Control Region (PCR) on a processor. The information includes the items in the DPC queue, which can be useful. when you are debugging a stalled driver or a time-out. + +[**!minipkd.help**](-minipkd-help.md) +The **!minipkd.help** extension displays a list of all of the Minipkd.dll extension commands. + +If an error message similar to the following appears, it indicates that the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols. + +``` +minipkd error (0) ... \minipkd\minipkd.c @ line 435 +``` + +The [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command can be used to display the current path and to change the path. The [**.reload (Reload Module)**](-reload--reload-module-.md) command will reload symbols from the current path. + +[**!minipkd.adapter Adapter**](-minipkd-adapter.md) +The **!minipkd.adapter** extension displays detailed information about a specified adapter. The **Adapter** can be found by looking at the **DevExt** field in the **!minipkd.adapters** display. + +[**!minipkd.adapters**](-minipkd-adapters.md) +The **!minipkd.adapters** extension displays all the adapters that work with the SCSI Port driver that have been identified by Windows, and the individual devices associated with each adapter. + +Here is an example: + +``` +0: kd> !minipkd.adapters +Adapter \Driver\lp6nds35 DO 86334a70 DevExt 86334b28 +Adapter \Driver\adpu160m DO 8633da70 DevExt 8633db28 + LUN 862e60f8 @(0,0,0) c ev pnp(00/ff) pow(0,0) DevObj 862e6040 + LUN 863530f8 @(0,1,0) c ev p d pnp(00/ff) pow(0,0) DevObj 86353040 + LUN 862e50f8 @(0,2,0) c ev pnp(00/ff) pow(0,0) DevObj 862e5040 + LUN 863520f8 @(0,6,0) ev pnp(00/ff) pow(0,0) DevObj 86352040 +Adapter \Driver\adpu160m DO 86376040 DevExt 863760f8 +``` + +An error message similar to the following indicates that either the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols, or that Windows has not identified any adapters that work with the SCSI Port driver: + +``` +minipkd error (0) ... \minipkd\minipkd.c @ line 435 +``` + +If the [**!minipkd.help**](-minipkd-help.md) extension command returns help information successfully, the SCSI Port symbols are correct. + +[**!minipkd.exports Adapter**](-minipkd-exports.md) +The **!minipkd.exports** extension displays the addresses of the miniport exports for the specified adapter. + +[**!minipkd.lun {LUN | Device}**](-minipkd-lun.md) +The **!minipkd.lun** extension displays detailed information about a specified Logical Unit Extension (LUN). The LUN can be specified either by its address (which can be found by looking at the **LUN** field in the **!minipkd.adapters** display) or by its physical device object (which can be found in the **DevObj** field of the **!minipkd.adapters** display). + +[**!minipkd.portconfig PortConfig**](-minipkd-portconfig.md) +The **!minipkd.portconfig** extension displays detailed information about a specified PORT\_CONFIGURATION\_DATA. The **PortConfig** can be found in the **Port Config Info** field of the **!minipkd.adapter** display. + +[**!minipkd.req {Adapter | Device}**](-minipkd-req.md) +The **!minipkd.req** extension displays information about all of the currently active requests on the specified adapter or LUN device. + +[**!minipkd.srb SRB**](-minipkd-srb.md) +The **!minipkd.srb** extension displays detailed information about a specified SCSI request block (SRB). The SRB is specified by address. The addresses of all currently active requests can be found in the **SRB** fields of the output from the **!minipkd.req** command. + +[**!scsikd.classext \[Device \[Level\]\]**](-scsikd-classext.md) +The **!scsikd.classext** extension displays detailed information about a specified class Plug and Play (PnP) device or a list of all such devices. The *Device* is the device object or device extension of the class PnP device. If *Device* is omitted, a list of all class PnP extensions is displayed. + +Here is an example: + +``` +0: kd> !scsikd.classext + + ' !scsikd.classext 8633e3f0 ' ( ) "IBM " / "DDYS-T09170M " / "S93E" / " XBY45906" + ' !scsikd.classext 86347b48 ' (paging device) "IBM " / "DDYS-T09170M " / "S80D" / " VDA60491" + ' !scsikd.classext 86347360 ' ( ) "UNISYS " / "003451ST34573WC " / "5786" / "HN0220750000181300L6" + ' !scsikd.classext 861d1898 ' ( ) "" / "MATSHITA CD-ROM CR-177" / "7T03" / "" + + usage: !classext +``` + +[**!scsikd.scsiext Device**](-scsikd-scsiext.md) +The **!scsikd.scsiext** extension displays detailed information about a specified SCSI port extension. The *Device* can be the device object or device extension of either the adapter or the LUN. + +Here are some examples: + +``` +0: kd> !scsikd.scsiext 86353040 +Common Extension: + < ..omitted.. > +Logical Unit Extension: + Address (3, 0, 1, 0) Claimed Enumerated Visible + LuFlags (0x00000000): + Retry 0x00 Key 0x008889ff + Lock 0x00000000 Pause 0x00000000 CurrentLock: 0x00000000 + HwLuExt 0x862e6f00 Adapter 0x8633db28 Timeout 0x0000000a + NextLun 0x00000000 ReadyLun 0x00000000 + Pending 0x00000000 Busy 0x00000000 Untagged 0x00000000 + < ..omitted.. > +Request list @0x86353200: + Tick count is 2526 + SrbData 8615d700 Srb 8611f4fc Irp 8611f2b8 Key 60197 <1s + SrbData 85e72868 Srb 86100c3c Irp 861009f8 Key e29dc7 <1s + +0: kd> !scsikd.scsiext 8633da70 +Common Extension: + < ..omitted.. > +Adapter Extension: + Port 3 IsPnp VirtualSlot HasInterrupt + LowerPdo 0x84f9fb68 HwDevExt 0x84634004 Active Requests 0x00000000 + MaxBus 0x03 MaxTarget 0x40 MaxLun 0x08 + Port Flags (0x00001000): PD_DISCONNECT_RUNNING + NonCacheExt 0x850d4000 IoBase 0xd80f0000 Int 0x23 < ..omitted.. > +``` + +[**!scsikd.srbdata Address**](-scsikd-srbdata.md) +The **!scsikd.srbdata** extension displays detailed information about a specified SRB\_DATA tracking block. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Extensions%20for%20Debugging%20SCSI%20Miniport%20Drivers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/extra-tools.md b/windows-driver-docs-pr/debugger/extra-tools.md new file mode 100644 index 0000000000..224d078746 --- /dev/null +++ b/windows-driver-docs-pr/debugger/extra-tools.md @@ -0,0 +1,112 @@ +--- +title: Tools Included in Debugging Tools for Windows +description: Debugging Tools for Windows includes several tools in addition to the debugging engine and the Debugging Environments. The tools are in the installation directory of Debugging Tools for Windows. +ms.assetid: f5d761b9-866e-4948-978e-e95f8aed8b21 +--- + +# Tools Included in Debugging Tools for Windows + + +Debugging Tools for Windows includes several tools in addition to the debugging engine and the [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md). The tools are in the [installation directory](#installation-directories) of Debugging Tools for Windows. + +## + + +[ADPlus](adplus.md) +Automatically create memory dump files and log files with debug output from one or more processes. + +[DumpChk](dumpchk.md) +Validate a memory dump file. + +[GFlags](gflags.md) +Control registry keys and other settings. + +[Kill](kill-tool.md) +Terminate a process. + +[Logger and LogViewer](logger-and-logviewer.md) +Record and display function calls and other actions of a program. + +[PLMDebug](plmdebug.md) +Use the Windows debugger to debug Windows app, which run under Process Lifecycle Management (PLM). With PLMDebug, you can take manual control of suspending, resuming, and terminating a Windows app. + +[Remote Tool](remote-tool.md) +Remotely control any console program, including KD, CDB, and NTSD. See [Remote Debugging Through Remote.exe](remote-debugging-through-remote-exe.md). + +[TList](tlist.md) +List all running processes. + +[UMDH](umdh.md) +Analyze heap allocations. + +[USBView](usbview.md) +Display USB host controllers and connected devices. + +DbgRpc (Dbgrpc.exe) +Display Microsoft Remote Procedure Call (RPC) state information. See [RPC Debugging](rpc-debugging.md) and [Using the DbgRpc Tool](using-the-dbgrpc-tool.md). + +KDbgCtrl (Kernel Debugging Control, Kdbgctrl.exe) +Control and configure the kernel debugging connection. See [Using KDbgCtrl](using-kdbgctrl.md). + +[SrcSrv](srcsrv.md) +A source server that can be used to deliver source files while debugging. + +[SymSrv](symsrv.md) +A symbol server that the debugger can use to connect to a symbol store. + +[SymProxy](symproxy.md) +Create a single HTTP symbol server on your network that all your debuggers can point to. This has the benefit of pointing to multiple symbol servers (both internal and external) with a single symbol path, handling all authentication, and increasing performance via symbol caching. Symproxy.dll is in the SymProxy folder in the [installation directory](#installation-directories). + +[SymChk](symchk.md) +Compare executable files to symbol files to verify that the correct symbols are available. + +[SymStore](symstore.md) +Create a symbol store. See [Using SymStore](symstore.md). + +[AgeStore](agestore.md) +Removes old entries in the downstream store of a symbol server or a source server. + +[DBH](dbh.md) +Display information about the contents of a symbol file. + +[PDBCopy](pdbcopy.md) +Remove private symbol information from a symbol file, and control which public symbols are included in the file. + +DbgSrv +A process server used for remote debugging. See [Process Servers (User Mode)](process-servers--user-mode-.md). + +KdSrv +A KD connection server used for remote debugging.See [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md). + +DbEngPrx +A repeater (small proxy server) used for remote debugging. See [Repeaters](repeaters.md). + +Breakin (Breakin.exe) +Causes a user-mode break to occur in a process. For help, open a Command Prompt window, navigate to the [installation directory](#installation-directories), and enter **breakin /?**. + +List (File List Utility) (List.exe) +For help, open a Command Prompt window, navigate to the [installation directory](#installation-directories), and enter **list /?**. + +RTList (Remote Task List Viewer) (Rtlist.exe) +List running processes via a DbgSrv process server. For help, open a Command Prompt window, navigate to the [installation directory](#installation-directories), and enter **rtlist /?**. + +## Installation Directory + + +The default installation directory for 64 bit OS installs for the debugging tools is C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\. If you have a 32-bit OS, you can find the Windows Kits folder under C:\\Program Files. To determine if you should use the 32 bit or 64 bit tools, see [Choosing the 32-Bit or 64-Bit Debugging Tools](choosing-a-32-bit-or-64-bit-debugger-package.md). + +## Related topics + + +[Tools Related to Debugging Tools for Windows](tools-related-to-debugging-tools-for-windows.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Tools%20Included%20in%20Debugging%20Tools%20for%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/extracting-information-from-a-dump-file.md b/windows-driver-docs-pr/debugger/extracting-information-from-a-dump-file.md new file mode 100644 index 0000000000..0859560374 --- /dev/null +++ b/windows-driver-docs-pr/debugger/extracting-information-from-a-dump-file.md @@ -0,0 +1,48 @@ +--- +title: Extracting Information from a Dump File +description: Extracting Information from a Dump File +ms.assetid: abde266e-e3ab-4e5e-ac6d-a27933f3d1a9 +keywords: ["extracting information from a dump file", "dump file, extracting various information", "machine name (determining from a dump file)", "computer name (determining from a dump file)", "IP address (determining from a dump file)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extracting Information from a Dump File + + +## + + +Certain kinds of information, such as the name of the target computer, are easily available during live debugging. When debugging a dump file it takes a little more work to determine this information. + +### Finding the Computer Name in a Kernel-Mode Dump File + +If you need to determine the name of the computer on which the crash dump was made, you can use the [**!peb**](-peb.md) extension and look for the value of COMPUTERNAME it its output. + +Or you can use the following command: + +``` +0: kd> x srv!SrvComputerName +be8ce2e8 srv!SrvComputerName = _UNICODE_STRING "AIGM-MYCOMP-PUB01" +``` + +### Finding the IP Address in a Kernel-Mode Dump File + +To determine the IP address of the computer on which the crash dump was made, find a thread stack that shows some send/receive network activity. Open one of the send packets or receive packets. The IP address will be visible in that packet. + +### Finding the Process ID in a User-Mode Dump File + +To determine the process ID of the target application from a user-mode dump file, use the [**| (Process Status)**](---process-status-.md) command. This will display all the processes being debugged at the time the dump was written. The process marked with a period (**.**) is the current process. Its process ID is given in hexadecimal after the **id:** notation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Extracting%20Information%20from%20a%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/extracting-source-files.md b/windows-driver-docs-pr/debugger/extracting-source-files.md new file mode 100644 index 0000000000..588ab5278a --- /dev/null +++ b/windows-driver-docs-pr/debugger/extracting-source-files.md @@ -0,0 +1,48 @@ +--- +title: Extracting Source Files +description: Extracting Source Files +ms.assetid: b7c859a9-5264-401c-ad96-ad044bcc140e +keywords: ["extracting source files", "source servers, extracting source files"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extracting Source Files + + +To extract all of the source files from all the modules for which you want to provide source, use the command: + +``` +srctool.exe -x +``` + +This tool must be executed on .pdb files that have already been source-indexed for your version control system on a computer that has version control access. This places all source files into a common directory tree. Copy the contents of this tree to the root of the Web site. You can do this as often as you want on any new products or modules that you want to add. There is no worry about files overwriting each other because the directory tree structure keeps dissimilar files separated and uniquely accessible. + +### Walk + +The Walk (Walk.cmd) script is included in Debugging Tools for Windows. This script searches recursively through a directory tree and executes any specified command on any file that matches a specified file mask. The syntax is: + +``` +walk.cmd FileMask Command +``` + +where *FileMask* specifies a file mask, with or without an accompanying starting directory, and *Command* specifies the command to be executed. + +Here is an example that runs the srctool.exe file extraction command on all .pdb files in c:\\symbols and its subdirectories: + +``` +walk.cmd c:\symbols\*.pdb srctool.exe -x +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Extracting%20Source%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/f--fp--fill-memory-.md b/windows-driver-docs-pr/debugger/f--fp--fill-memory-.md new file mode 100644 index 0000000000..4c64bc5c70 --- /dev/null +++ b/windows-driver-docs-pr/debugger/f--fp--fill-memory-.md @@ -0,0 +1,139 @@ +--- +title: f, fp (Fill Memory) +description: The f and fp commands fill the specified memory range with a repeating pattern.These commands should not be confused with the ~F (Freeze Thread) command. +ms.assetid: 9ef4eb88-dc6f-4f0f-ac01-a6b0bb42b33e +keywords: ["f, fp (Fill Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- f, fp (Fill Memory) +api_type: +- NA +--- + +# f, fp (Fill Memory) + + +The **f** and **fp** commands fill the specified memory range with a repeating pattern. + +These commands should not be confused with the [**~F (Freeze Thread)**](-f--freeze-thread-.md) command. + +``` +f Range Pattern +fp [MemoryType] PhysicalRange Pattern +``` + +## Parameters + + + *Range* +Specifies the range in virtual memory to fill. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *PhysicalRange* +(Kernel mode only) Specifies the range in physical memory to fill. The syntax of *PhysicalRange* is the same as that of a virtual memory range, except that no symbol names are permitted. + + *MemoryType* +(Kernel mode only) Specifies the type of physical memory, which can be one of the following: + +**\[c\]** +Cached memory. + +**\[uc\]** +Uncached memory. + +**\[wc\]** +Write-combined memory. + + *Pattern* +Specifies one or more byte values with which to fill memory. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

+f: user mode, kernel mode +fp: kernel mode only

Targets

live, crash dump

Platforms

all

+ +  + +### Additional Information + +For an overview of memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +This command fills the memory area specified by *range* with the specified *pattern*, repeated as many times as necessary. + +The *pattern* parameter must be input as a series of bytes. These can be entered as numeric or as ASCII characters. + +Numeric values will be interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. The default radix can be overridden by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + +**Note**   The default radix behaves differently when C++ expressions are being used. For more information, see the [Evaluating Expressions](evaluating-expressions.md) topic. + +  + +If ASCII characters are used, each character must be enclosed in single straight quotation marks. C-style escape characters (such as '\\0' or '\\n') may not be used. + +If multiple bytes are specified, they must be separated by spaces. + +If *pattern* has more values than the number of bytes in the range, the debugger ignores the extra values. + +Here are some examples. Assuming the current radix is 16, the following command will fill memory locations 0012FF40 through 0012FF5F with the pattern "ABC", repeated several times: + +``` +0:000> f 0012ff40 L20 'A' 'B' 'C' +``` + +The following command has the exact same effect: + +``` +0:000> f 0012ff40 L20 41 42 43 +``` + +The following examples show how you can use the physical memory types (**c**, **uc**, and **wc**) with the **fp** command in kernel mode: + +``` +kd> fp [c] 0012ff40 L20 'A' 'B' 'C' +``` + +``` +kd> fp [uc] 0012ff40 L20 'A' 'B' 'C' +``` + +``` +kd> fp [wc] 0012ff40 L20 'A' 'B' 'C' +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20f,%20fp%20%28Fill%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/f.md b/windows-driver-docs-pr/debugger/f.md new file mode 100644 index 0000000000..9b371f92c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/f.md @@ -0,0 +1,30 @@ +--- +title: F (Windows Debugger Glossary) +description: Glossary page - F +Robots: noindex, nofollow +ms.assetid: 9e5917b2-0f7d-4d6c-8e92-249b29b546ca +--- + +# F + + +**free build** +Two different builds of each NT-based operating system exist: + +- The (or ) of Windows is the end-user version of the operating system. The system and drivers are built with full optimization, debugging asserts are disabled, and debugging information is stripped from the binaries. A free system and driver are smaller and faster, and it uses less memory. +- The (or ) of Windows serves as a testing and debugging aid. For details, see checked build. + +Distribution media containing the free build of the operating system do not have any special labels -- in other words, the CD containing the free build will just be labeled with the Windows version name, and no reference to the type of build. + +**first-chance exception** +The first opportunity to handle an exception. If an exception is not handled by any handler on the first opportunity, the handlers are given a second chance. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20F%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/failure-analysis-entries.md b/windows-driver-docs-pr/debugger/failure-analysis-entries.md new file mode 100644 index 0000000000..9467a7bdff --- /dev/null +++ b/windows-driver-docs-pr/debugger/failure-analysis-entries.md @@ -0,0 +1,41 @@ +--- +title: Failure Analysis Entries +description: A DebugFailureAnalysis object has a collection of failure analysis entries. +ms.assetid: 759DE159-F2A8-4BB1-AAF5-B2B91C4F91B0 +--- + +# Failure Analysis Entries + + +A [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object has a collection of failure analysis entries. For more information, see [Failure Analysis Entries, Tags, and Data Types](writing-an-analysis-extension-to-extend--analyze.md#failure-analysis-entries-tags-and-data-types). + +A *failure analysis entry* (also called an *FA entry*) is one of the following: + +- An [**FA\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/jj991808) structure +- An [**FA\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/jj991808) structure followed by a data block + +The **DataSize** member of the [**FA\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/jj991808) structure holds the size, in bytes, of the data block. If there is no data block, **DataSize** is equal to 0. The **Tag** member of an **FA\_ENTRY** structure identifies the kind of information that is stored in the FA entry. For example, the tag **DEBUG\_FLR\_BUGCHECK\_CODE** indicates that the data block of the **FA\_ENTRY** holds a bug check code. + +In some cases, there is no need for a data block; all the information is conveyed by the tag. For example, an [**FA\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/jj991808) with tag **DEBUG\_FLR\_KERNEL\_VERIFIER\_ENABLED** has no data block. + +Each tag is associated with one of the data types in the [**FA\_ENTRY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/jj991809) enumeration. For example, the tag **DEBUG\_FLR\_BUGCHECK\_CODE** is associated with the data type **DEBUG\_FA\_ENTRY\_ULONG**. To determine the data type of a tag, call the [**GetType**](https://msdn.microsoft.com/library/windows/hardware/jj991813) method of the [IDebugFAEntryTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) interface. + +To get or set the data block of an FA entry, use the [**IDebugFailureAnalysis2**](https://msdn.microsoft.com/library/windows/hardware/jj983405) interface. + +## Related topics + + +[Writing an Analysis Extension Plug-in to Extend !analyze](writing-an-analysis-extension-to-extend--analyze.md) + +[**FA\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/jj991808) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Failure%20Analysis%20Entries%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/features-of-secure-mode.md b/windows-driver-docs-pr/debugger/features-of-secure-mode.md new file mode 100644 index 0000000000..8ca3a92c03 --- /dev/null +++ b/windows-driver-docs-pr/debugger/features-of-secure-mode.md @@ -0,0 +1,45 @@ +--- +title: Features of Secure Mode +description: Features of Secure Mode +ms.assetid: bf40d018-7804-47df-9064-fb6f86da4b33 +keywords: ["Secure Mode, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Features of Secure Mode + + +## + + +When Secure Mode is active, all commands that could be used to affect the *host* computer are deactivated, and there are some restrictions on symbol servers and debugger extensions. + +The specific effects of Secure Mode are as follows: + +- The [**.attach (Attach to Process)**](-attach--attach-to-process-.md), [**.create (Create Process)**](-create--create-process-.md), [**.detach (Detach from Process)**](-detach--detach-from-process-.md), [**.abandon (Abandon Process)**](-abandon--abandon-process-.md), [**.kill (Kill Process)**](-kill--kill-process-.md), [**.tlist (List Process IDs)**](-tlist--list-process-ids-.md), [**.dump (Create Dump File)**](-dump--create-dump-file-.md), [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md), [**.writemem (Write Memory to File)**](-writemem--write-memory-to-file-.md), [**.netuse (Control Network Connections)**](-netuse--control-network-connections-.md), and [**.quit\_lock (Prevent Accidental Quit)**](-quit-lock--prevent-accidental-quit-.md) commands are not available. + +- The [File | Attach to a Process](file---attach-to-a-process.md), [File | Open Executable](file---open-executable.md), [Debug | Detach Debuggee](debug---detach-debuggee.md), [Debug | Stop Debugging](debug---stop-debugging.md), [File | Open Crash Dump](file---open-crash-dump.md) WinDbg menu commands are not available. + +- The [**.shell (Command Shell)**](-shell--command-shell-.md) command is not available. + +- Extension DLLs must be loaded from a local disk; they cannot be loaded from UNC paths. + +- Only the two standard types of extension DLLs (wdbgexts.h and dbgeng.h) are permitted. Other types of DLLs cannot be loaded as extensions. + +- If you are using a symbol server, there are several restrictions. Only SymSrv (symsrv.dll) is permitted; other symbol server DLLs will not be accepted. You may not use a downstream store for your symbols, and any existing downstream store will be ignored. HTTP and HTTPS connections are not permitted. + +After it has been activated, Secure Mode cannot be turned off. For more information see, [Activating Secure Mode](activating-secure-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Features%20of%20Secure%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---attach-to-a-process.md b/windows-driver-docs-pr/debugger/file---attach-to-a-process.md new file mode 100644 index 0000000000..458f240f63 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---attach-to-a-process.md @@ -0,0 +1,52 @@ +--- +title: File Attach to a Process +description: File Attach to a Process +ms.assetid: 6bd438a3-e9fb-444d-baf6-fffdee0487f2 +keywords: ["File Attach to a Process", "starting the debugger, File Attach to a Process"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Attach to a Process + + +## + + +Click **Attach to a Process** on the **File** menu to debug a user-mode application that is currently running. + +This command is equivalent to pressing F6. You can use this command only when WinDbg is in dormant mode. + +### Dialog Box + +When you click **Attach to a Process**, the **Attach to Process** dialog box appears,and you can do the following: + +- Select the line that contains the proper process ID and name (or enter the process ID in the **Process ID** box). + **Note**  Each listed process has an associated plus sign (**+**). You can click the plus sign to display information about that process' command line, services, and child processes. + +   + + **Note**   If WinDbg is connected to a process server, the **Attach to Process** dialog box will display processes that are running on the remote computer. For more information about process servers, see [**Activating a Smart Client**](activating-a-smart-client.md). + +   + +- If you want to attach noninvasively to a process, select the **Noninvasive** check box. + +After you make your selections, click **OK**. + +### Additional Information + +For more information and other methods of attaching to a process, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md) and [Noninvasive Debugging (User Mode)](noninvasive-debugging--user-mode-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Attach%20to%20a%20Process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---clear-workspace.md b/windows-driver-docs-pr/debugger/file---clear-workspace.md new file mode 100644 index 0000000000..ede4a25c8a --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---clear-workspace.md @@ -0,0 +1,41 @@ +--- +title: File Clear Workspace +description: File Clear Workspace +ms.assetid: 21d60ff7-0c62-4018-9dc6-51036816780b +keywords: ["File Clear Workspace", "workspaces, File Clear Workspace"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Clear Workspace + + +## + + +Click **Clear Workspace** on the **File** menu to erase items in the current workspace. + +### Dialog Box + +When you click **Clear Workspace**, the **Clear Workspace** dialog box appears. This dialog box contains a list of all of the items that are contained in the current workspace in the **Items in Workspace** area. + +Use the **Clear** and **Clear All** buttons to remove items from the **Items in Workspace** area. If you make an error, use the **Save** and **Save All** buttons to return items to this list. + +Click **OK** to make these changes, or click **Cancel** to discard these changes. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Clear%20Workspace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---close-current-window.md b/windows-driver-docs-pr/debugger/file---close-current-window.md new file mode 100644 index 0000000000..5f034d051e --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---close-current-window.md @@ -0,0 +1,33 @@ +--- +title: File Close Current Window +description: File Close Current Window +ms.assetid: b0cdb6da-66f7-40fd-8a93-8890affc6104 +keywords: ["File Close Current Window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Close Current Window + + +## + + +Click **Close Current Window** on the **File** menu to close the active debugging information window. + +This command is equivalent to pressing CTRL+F4. + +You can also close a debugging information window by clicking the **Close** button in the upper-right corner of the information window inside the WinDbg window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Close%20Current%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---connect-to-remote-session.md b/windows-driver-docs-pr/debugger/file---connect-to-remote-session.md new file mode 100644 index 0000000000..d74128ecf9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---connect-to-remote-session.md @@ -0,0 +1,110 @@ +--- +title: File Connect to Remote Session +description: File Connect to Remote Session +ms.assetid: 82c4900f-846b-41fb-afdc-3c73b524af9c +keywords: ["File Connect to Remote Session", "remote debugging through the debugger, File Connect to Remote Session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Connect to Remote Session + + +## + + +Click **Connect to Remote Session** on the **File** menu to make WinDbg a debugging client and to connect to an active debugging server. + +This command is equivalent to pressing CTRL+R. You can use this command only when WinDbg is in dormant mode. + +You cannot use this command to connect to a process server or a KD connection server; for that purpose, use [File | Connect to Remote Stub](file---connect-to-remote-stub.md) instead. + +### Connect to Remote Debugger Session Dialog Box + +When you click **Connect to Remote Session**, the **Connect to Remote Debugger Session** dialog box appears. You can use this dialog box to enter the remote connection parameters or to browse a list of debugging servers. + +To manually specify the remote connection parameters, enter one of the following strings in the **Connection string** box: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] + +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +The various parameters in the preceding options have the following possible values: + +*Server* +The network name of the computer on which the debugging server was created. Do not precede this name with backslashes (**\\\\**). + +*PipeName* +If you use the NPIPE or SPIPE protocol, *PipeName* is the name that was given to the pipe when the server was created. + +*Socket* +If you use the TCP or SSL protocol, *Socket* is the same socket port number that was used when the server was created. + +*COMPort* +If you use the COM protocol, *COMPort* specifies the COM port to use. The "COM" prefix is optional (for example, both "com2" and "2" are correct). + +*BaudRate* +If you use the COM protocol, *BaudRate* should match the baud rate that you chose when the server was created. + +*COMChannel* +If you use the COM protocol, *COMChannel* should match the channel number that you chose when the server was created. + +*Protocol* +(Windows 2000 and later) If you use the SSL or SPIPE protocol, *Protocol* should match the secure protocol that you used when the server was created. + +*Cert* +(Windows 2000 and later) If you use the SSL or SPIPE protocol, you should use the identical **certuser=***Cert* or **machuser=***Cert* parameter that was used when the server was created. + +**clicon** +Specifies that the debugging server will try to connect to the client through a reverse connection. The client must use **clicon** if and only if the server is using **clicon**. In most cases, the debugging client is started before the debugging server when a reverse connection is used. + +*Password* +If you used a password when the server was created, you must supply *Password* to create the debugging client. This value must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005". + +**ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when you are using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +Instead of manually specifying the remote connection parameters, you can press the **Browse** button in the **Connect to Remote Debugger Session** dialog box and use the **Browse Remote Servers** dialog box. + +### Browse Remote Servers Dialog Box + +In the **Browse Remote Servers** dialog box, in the **Machine** text box, enter the name of the computer that the debugging server is running on. (The two initial backslashes are optional: "MyBox" and "\\\\MyBox" are both correct.) Then, press the **Refresh** button. + +The **Servers** area lists all of the debugging servers that are running on that computer. Select any of the listed servers and then press ENTER or click **OK**. (You can also double-click one of the listed servers.) The proper connection string for the debugging server that you selected will now appear in the **Connection string** box in the **Connect to Remote Debugger Session** dialog box. + +If the server is password-protected, the connection string includes **Password=\***. You must replace the asterisk (**\***) with the actual password. + +After you specify the server and password, click **OK** to open the connection. + +This list of servers in the **Browse Remote Servers** dialog box can also include servers that no longer exist but were shut down improperly. If you connect to one of these nonexistent servers, you will receive an error message. + +The list of servers does not include process servers and KD connection servers; you can list those servers only by using the [File | Connect to Remote Stub](file---connect-to-remote-stub.md) command or by running **cdb -QR** *Server* from a Command Prompt window. + +### Additional Information + +For more information and for other methods of joining a remote debugging session, see [**Activating a Debugging Client**](activating-a-debugging-client.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Connect%20to%20Remote%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---connect-to-remote-stub.md b/windows-driver-docs-pr/debugger/file---connect-to-remote-stub.md new file mode 100644 index 0000000000..8a27df5a72 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---connect-to-remote-stub.md @@ -0,0 +1,107 @@ +--- +title: File Connect to Remote Stub +description: File Connect to Remote Stub +ms.assetid: 7357db85-babe-4729-9a20-76ba284f5bf3 +keywords: ["File Connect to Remote Stub"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Connect to Remote Stub + + +Click **Connect to Remote Stub** on the **File** menu to make WinDbg a smart client and connect to a process server or a KD connection server. + +This command is equivalent to using the -premote command line option in user mode, or the -k kdsrv transport protocol command-line option in kernel mode. You can use this command only when WinDbg is in dormant mode. + +You cannot use this command to connect to a debugging server; for that purpose, use [File | Connect to Remote Session](file---connect-to-remote-session.md) instead. + +### Connect to Remote Stub Server Dialog Box + +When you click **Connect to Remote Stub**, the **Connect to Remote Stub Server** dialog box appears. You can use this dialog box to enter the remote connection parameters or to browse a list of process servers and KD connection servers. + +To manually specify the remote connection parameters, enter one of the following strings in the **Connection string** box: + +``` +npipe:server=Server,pipe=PipeName[,password=Password] + +tcp:server=Server,port=Socket[,password=Password][,ipversion=6] + +tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] + +com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] + +spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] + +ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] +``` + +The various parameters in the preceding options have the following possible values: + +*Server* +The network name of the computer on which the process server or KD connection server was created. Do not precede this name with backslashes (**\\\\**). + +*PipeName* +If you use the NPIPE or SPIPE protocol, *PipeName* is the name that was given to the pipe when the server was created. + +*Socket* +If you use the TCP or SSL protocol, *Socket* is the same socket port number that was used when the server was created. + +*COMPort* +If you use the COM protocol, *COMPort* specifies the COM port to use. The "COM" prefix is optional (for example, both "com2" and "2" are correct). + +*BaudRate* +If you use the COM protocol, *BaudRate* should match the baud rate that you chose when the server was created. + +*COMChannel* +If you use the COM protocol, *COMChannel* should match the channel number that you chose when the server was created. + +*Protocol* +(Windows 2000 and later) If you use the SSL or SPIPE protocol, *Protocol* should match the secure protocol that you used when the server was created. + +*Cert* +(Windows 2000 and later) If you use the SSL or SPIPE protocol, you should use the identical **certuser=***Cert* or **machuser=***Cert* parameter that was used when the server was created. + +**clicon** +Specifies that the process server or KD connection server will try to connect to the client through a reverse connection. The client must use **clicon** if and only if the server is using **clicon**. In most cases, the smart client is started before the server when a reverse connection is used. + +*Password* +If you used a password when the server was created, you must supply *Password* to create the smart client. This value must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005". + +**ipversion=6** +(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when you are using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary. + +Instead of manually specifying the remote connection parameters, you can press the **Browse** button in the **Connect to Remote Stub Server** dialog box and use the **Browse Remote Servers** dialog box. + +### Browse Remote Servers Dialog Box + +In the **Browse Remote Servers** dialog box, in the **Machine** text box, enter the name of the computer that the process server or KD connection server is running on. (The two initial backslashes are optional: "MyBox" and "\\\\MyBox" are both correct.) Then, press the **Refresh** button. + +The **Servers** area lists all of the process servers and KD connection servers that are running on that computer. Select any of the listed servers and then press ENTER or click **OK**. (You can also double-click one of the listed servers.) The proper connection string for the process server that you selected will now appear in the **Connection string** box in the **Connect to Remote Stub Server** dialog box. + +If the server is password-protected, the connection string includes **Password=\***. You must replace the asterisk (**\***) with the actual password. + +After you specify the server and password, click **OK** to open the connection. + +The list of servers in the **Browse Remote Servers** dialog box can also include servers that no longer exist but were shut down improperly. If you connect to one of these nonexistent servers, you will receive an error message. + +The list of servers does not include debugging servers. To view those servers, use the [File | Connect to Remote Session](file---connect-to-remote-session.md) command. + +### Additional Information + +For more information and for other methods of joining a remote stub session, see [**Activating a Smart Client**](activating-a-smart-client.md) and [**Activating a Smart Client (Kernel Mode)**](activating-a-smart-client--kernel-mode-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Connect%20to%20Remote%20Stub%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---delete-workspaces.md b/windows-driver-docs-pr/debugger/file---delete-workspaces.md new file mode 100644 index 0000000000..98f44885f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---delete-workspaces.md @@ -0,0 +1,39 @@ +--- +title: File Delete Workspaces +description: File Delete Workspaces +ms.assetid: 1c86fa56-4e8d-44c9-8d31-92868bbe781a +keywords: ["File Delete Workspaces", "workspaces, File Delete Workspaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Delete Workspaces + + +## + + +Click **Delete Workspaces** on the **File** menu to delete one or more existing workspaces. + +### Dialog Box + +When you click **Delete Workspaces**, the **Delete Workspaces** dialog box appears. In this dialog box, select the workspace that you want to delete and click **Delete**. + +Click **Close** to close the dialog box. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Delete%20Workspaces%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---disconnect-network-drive.md b/windows-driver-docs-pr/debugger/file---disconnect-network-drive.md new file mode 100644 index 0000000000..fc809ea1cf --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---disconnect-network-drive.md @@ -0,0 +1,41 @@ +--- +title: File Disconnect Network Drive +description: File Disconnect Network Drive +ms.assetid: 65d78f9b-0c3c-4ec8-906d-afdfa64beebb +keywords: ["File Disconnect Network Drive", "shell commands, File Disconnect Network Drive"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Disconnect Network Drive + + +## + + +Click **Disconnect Network Drive** on the **File** menu to remove network connections. + +### Dialog Box + +When you click **Disconnect Network Drive**, the **Disconnect Network Drives** dialog box appears. In the **Network Drives** box, select the connection you want to remove and click **OK**. + +This dialog box works exactly like the corresponding feature of Windows Explorer. + +The **File | Disconnect Network Drive** command affects only the network connections of the computer on which WinDbg is running. If you are using WinDbg as a client in a remote debugging session and you want to change the network connections of the server, you must use a **.shell net use** command. + +### Additional Information + +For more information about accessing the command shell, see [Using Shell Commands](using-shell-commands.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Disconnect%20Network%20Drive%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---exit.md b/windows-driver-docs-pr/debugger/file---exit.md new file mode 100644 index 0000000000..9f9181af17 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---exit.md @@ -0,0 +1,35 @@ +--- +title: File Exit +description: File Exit +ms.assetid: 2b35a887-7574-413e-bc93-c406eddb110d +keywords: ["File Exit", "exiting the debugger, File Exit", "quitting the debugger, File Exit", "ending the debugging session, File Exit"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Exit + + +## + + +Click **Exit** on the **File** menu to end the debugging session and exit WinDbg. + +This command is equivalent to pressing ALT+F4. + +### Additional Information + +For more information about exiting WinDbg or ending the debugging session, see [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Exit%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---image-file-path.md b/windows-driver-docs-pr/debugger/file---image-file-path.md new file mode 100644 index 0000000000..6a31b726fe --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---image-file-path.md @@ -0,0 +1,49 @@ +--- +title: File Image File Path +description: File Image File Path +ms.assetid: d2a827b5-bba0-4840-8e74-5b24c9eb6a22 +keywords: ["File Image File Path", "executable files and paths, File Image File Path"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Image File Path + + +## + + +Click **Image File Path** on the **File** menu to display, set, or append to the executable image path. + +This command is equivalent to pressing CTRL+I. + +### Executable Image Search Path Dialog Box + +When you click **Image File Path**, the **Executable Image Search Path** dialog box appears. This dialog box displays the current executable image path. If the **Image path** box is blank, there is no current executable image path. + +You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons. + +Click **OK** to save changes, or click **Cancel** to discard changes. + +If you select the **Reload** check box, the debugger will reload all loaded image and symbol files after you click **OK**. This command is equivalent to using the [**.reload (Reload Module)**](-reload--reload-module-.md) command. + +You can also click **Browse** to open the **Browse For Folder** dialog box. + +### Browse For Folder Dialog Box + +In the **Browse For Folder** dialog box, you can browse through the folders on your computer or your network. You can also use the **Make New Folder** button to create a new folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears. + +Click **OK** to append the selected folder to the executable image path and return to the **Executable Image Search Path** dialog box. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Image%20File%20Path%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---kernel-debug.md b/windows-driver-docs-pr/debugger/file---kernel-debug.md new file mode 100644 index 0000000000..a72972293a --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---kernel-debug.md @@ -0,0 +1,49 @@ +--- +title: File Kernel Debug +description: File Kernel Debug +ms.assetid: a80b3572-87a0-4a9d-9b62-67e1ca65fff4 +keywords: ["File Kernel Debug", "starting the debugger, File Kernel Debug"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Kernel Debug + + +## + + +Click **Kernel Debug** on the **File** menu to debug a target computer in kernel mode. + +This command is equivalent to pressing CTRL+K. You can use this command only when WinDbg is in dormant mode. + +### Dialog Box + +When you click **Kernel Debug**, the **Kernel Debugging** dialog box appears with these tabs: + +- The **COM** tab indicates that the connection will use a COM port. In the **Baud Rate** box, enter the baud rate. In the **Port** box, enter the name of the COM port. For more information, see [Setting Up a Serial Connection Manually](setting-up-a-null-modem-cable-connection.md). + + You can also use the COM tab to connect to virtual machine through a named pipe. In the **Port** box, enter **\\\\***VMHost***\\pipe\\***PipeName*. *VMHost* specifies the name of the physical computer on which the virtual machine is running. If the virtual machine is running on the same computer as the kernel debugger itself, use a single period (.) for *VMHost*. For more information, see [Setting Up a Connection to a Virtual Machine](attaching-to-a-virtual-machine--kernel-mode-.md). + +- The **1394** tab indicates that the connection will use 1394. In the **Channel** box, enter the 1394 channel number. 1394 debugging is supported only if both the host computer and target computer are running Windows XP or later versions of the Windows operating system. For more information, see [Setting Up a 1394 Connection Manually](setting-up-a-1394-cable-connection.md). + +- The **USB** tab indicates that the connection will use USB 2.0 or USB 3.0. In the **Target Name** box, enter the target name that you created when you configured the target computer. For more information, see [Setting Up a USB 2.0 Connection Manually](setting-up-a-usb-2-0-debug-cable-connection.md) and [Setting Up a USB 3.0 Connection Manually](setting-up-a-usb-3-0-debug-cable-connection.md). + +- The **NET** tab indicates that the connection will use Ethernet. In the **Port Number** box, enter the port number that you specified when you configured the target computer. In the **Key** box, enter the key that was generated for you (or that you created) when you configured the target computer. For more information, see [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md). + +- The **Local** tab indicates that WinDbg will perform local kernel debugging. Local kernel debugging is supported only on Windows XP and later. + +For more information and for other methods of beginning a kernel debugging session, see [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Kernel%20Debug%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---map-network-drive.md b/windows-driver-docs-pr/debugger/file---map-network-drive.md new file mode 100644 index 0000000000..bd1786a582 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---map-network-drive.md @@ -0,0 +1,41 @@ +--- +title: File Map Network Drive +description: File Map Network Drive +ms.assetid: 55a5523f-5735-4b44-8d98-ded9932e630a +keywords: ["File Map Network Drive", "shell commands, File Map Network Drive"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Map Network Drive + + +## + + +Click **Map Network Drive** on the **File** menu to add network connections and assign drive letters to these connections. + +### Dialog Box + +When you click **Map Network Drive**, the **Map Network Drive** dialog box appears. Use the **Drive** and **Folder** menus to choose a server and share and assign a drive letter to it. + +This dialog box works exactly like the corresponding feature of Windows Explorer. + +The **File | Map Network Drive** command affects only the network connections of the computer on which WinDbg is running. If you are using WinDbg as a client in a remote debugging session and you want to change the network connections of the server, you must use a **.shell net use** command. + +### Additional Information + +For more information about accessing the command shell, see [Using Shell Commands](using-shell-commands.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Map%20Network%20Drive%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---open-crash-dump.md b/windows-driver-docs-pr/debugger/file---open-crash-dump.md new file mode 100644 index 0000000000..167da4850f --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---open-crash-dump.md @@ -0,0 +1,41 @@ +--- +title: File Open Crash Dump +description: File Open Crash Dump +ms.assetid: 0a398f9a-776b-4438-bde4-7654e1f813b7 +keywords: ["File Open Crash Dump", "starting the debugger, File Open Crash Dump", "dump file, File Open Crash Dump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Open Crash Dump + + +## + + +Click **Open Crash Dump** on the **File** menu to open a user-mode or kernel-mode crash dump file and to analyze it. + +This command is equivalent to pressing CTRL+D. You can use this command only when WinDbg is in dormant mode. + +### Dialog Box + +When you click **Open Crash Dump**, the **Open Crash Dump** dialog box appears. Enter the full path of the crash dump file in the **File name** box, or use the **Look in** list to find and select the proper path and file name. (Dump files typically end with the .dmp or .mdmp extension.) + +After you choose the proper file, click **Open**. + +### Additional Information + +For more information about analyzing crash dump files, see [Analyzing a User-Mode Dump File with WinDbg](analyzing-a-user-mode-dump-file-with-windbg.md) or [Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Open%20Crash%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---open-executable.md b/windows-driver-docs-pr/debugger/file---open-executable.md new file mode 100644 index 0000000000..ab17df2638 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---open-executable.md @@ -0,0 +1,55 @@ +--- +title: File Open Executable +description: File Open Executable +ms.assetid: dee75298-903d-438f-a66e-fddcfcd74ec7 +keywords: ["File Open Executable", "starting the debugger, File Open Executable"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Open Executable + + +## + + +Click **Open Executable** on the **File** menu to start a new user-mode process and debug it. + +This command is equivalent to pressing CTRL+E. You can use this command only when WinDbg is in dormant mode. + +### Dialog Box + +When you click **Open Executable**, the **Open Executable** dialog box appears, and you can do the following: + +- Enter the full path of the executable file in the **File name** box. Alternatively, you can use the dialog box to locate and select the proper file. You must specify the exact path to the executable file. Unlike the Microsoft Windows **Run** dialog box and a Command Prompt window, the **Open Executable** dialog box does not search the current path for an executable name. + +- If you want to use command-line arguments with the executable file, enter them in the **Arguments** box. + +- If you want to change the starting directory from the default directory enter the directory path in the **Start directory** box. + +- If you want WinDbg to attach to any *child processes* (additional processes that the original target process started), select **Debug child processes also**. + +After you make your selections, click **Open**. + +**Note**   When you use this command to open a source file, the path to that file is automatically appended to the [source path](source-path.md). + +  + +If WinDbg is connected to a process server, you cannot use the **Open Executable** command. + +### Additional Information + +For more information and other methods of starting new processes for debugging, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Open%20Executable%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---open-source-file.md b/windows-driver-docs-pr/debugger/file---open-source-file.md new file mode 100644 index 0000000000..3345deebc3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---open-source-file.md @@ -0,0 +1,54 @@ +--- +title: File Open Source File +description: File Open Source File +ms.assetid: 27007865-7517-40df-a30a-26ecf3cec9f5 +keywords: ["File Open Source File", "source debugging, File Open Source File"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Open Source File + + +## + + +Click **Open Source File** on the **File** menu to load a specific source file. + +This command is equivalent to pressing CTRL+O or clicking the **Open source file (Ctrl+O)** button (![screen shot of the open source file button](images/tbopen.png)). + +### Dialog Box + +When you click **Open Source File**, the **Open Source File** dialog box appears. To open a file, do the following: + +1. In the **Look in** list, select the directory where the file is located. The directory last opened is selected by default. + +2. In the **Files of type** list, select the type of file that you want to open. Only files with the chosen extensions are displayed in the **Open Source File** dialog box. + **Note**  You can also use wildcard patterns in the **File name** box to display only files with a certain extension. The new wildcard pattern is retained in a session until you change it. You can use any combination of wildcard patterns, separated by semicolons. For example, entering **\*.INC; \*.H; \*.CPP** displays all files with these extensions. The maximum number of characters in a line is 251. + +   + +3. If you find the file you want, double-click the file name, or click the file name and click **Open**. + + -OR- + + To discard changes and close the dialog box, click **Cancel**. + +The names of the four files that you opened most recently in WinDbg are displayed when you point to **Recent files** on the **File** menu. To open one of these files, click its name. + +### Additional Information + +For more information about source files and source paths and for other ways to load source files, see [Source Path](source-path.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Open%20Source%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---open-workspace-in-file.md b/windows-driver-docs-pr/debugger/file---open-workspace-in-file.md new file mode 100644 index 0000000000..55cd04c3c1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---open-workspace-in-file.md @@ -0,0 +1,39 @@ +--- +title: File Open Workspace in File +description: File Open Workspace in File +ms.assetid: 902be727-a418-4d84-b20b-39af8e7dd417 +keywords: ["File Open Workspace in File", "workspaces, File Open Workspace in File"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Open Workspace in File + + +## + + +Click **Open Workspace in File** on the **File** menu to load a workspace that was previously saved to a file. + +### Dialog Box + +When you click **Open Workspace in File**, the **Open Workspace in File** dialog box appears. In this dialog box, enter the name of the file that you want to load, or use the **Look in** list to navigate to the file and select it. (Workspace files should use the .wew extension.) + +Click **OK** to load the workspace, or click **Cancel** to close the dialog box. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Open%20Workspace%20in%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---open-workspace.md b/windows-driver-docs-pr/debugger/file---open-workspace.md new file mode 100644 index 0000000000..4c174f0490 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---open-workspace.md @@ -0,0 +1,41 @@ +--- +title: File Open Workspace +description: File Open Workspace +ms.assetid: 589d782c-c6b4-4b5a-a533-1ed02129fb9c +keywords: ["File Open Workspace", "workspaces, File Open Workspace"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Open Workspace + + +## + + +Click **Open Workspace** on the **File** menu to open a saved workspace. + +This command is equivalent to pressing CTRL+W. + +### Dialog Box + +When you click **Open Workspace**, the **Open Workspace** dialog box appears. This dialog box contains a list of all named workspaces in the **Workspaces** area. Default or implicit workspaces are not listed since opening them directly will cause problems with the implicit ordering. If you want to open an implicit workspace directly, you must save it explicitly. For more information on named and default workspaces, see [Creating and Opening a Workspace](creating-and-opening-a-workspace.md). + +Enter the name of the workspace that you want to open in the **Workspace** box or select the workspace name in the **Workspaces** area. Then, click **OK** to open the selected workspace, or click **Cancel** to return the debugger to its previous state. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Open%20Workspace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---recent-files.md b/windows-driver-docs-pr/debugger/file---recent-files.md new file mode 100644 index 0000000000..db9d94fd9d --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---recent-files.md @@ -0,0 +1,35 @@ +--- +title: File Recent Files +description: File Recent Files +ms.assetid: dd68f4b5-9d50-4d65-8177-2ca039afa8ea +keywords: ["File Recent Files", "source files and paths, File Recent Files"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Recent Files + + +## + + +Point to **Recent Files** on the **File** menu to display a list of the four source files that you most recently opened in WinDbg. + +To open one of these files, click its name from the menu. + +### Additional Information + +For more information about source files and source paths, and for other ways to load source files, see [Source Path](source-path.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Recent%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---save-workspace-as.md b/windows-driver-docs-pr/debugger/file---save-workspace-as.md new file mode 100644 index 0000000000..20d82862ad --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---save-workspace-as.md @@ -0,0 +1,41 @@ +--- +title: File Save Workspace As +description: File Save Workspace As +ms.assetid: 5b1da6f0-8a72-4aa9-a03b-542e14523fa4 +keywords: ["File Save Workspace As", "workspaces, File Save Workspace As"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Save Workspace As + + +## + + +Click **Save Workspace As** on the **File** menu to save the current workspace under a new workspace name. + +### Dialog Box + +When you click **Save Workspace As**, the **Save Workspace As** dialog box appears. This dialog box contains a list of all existing workspace names in the **Workspaces** area. The name of the current workspace is shown in the **Workspace** box. + +Enter the name that you want to use to save the workspace in the **Workspace** box, select the workspace name in the **Workspaces** area, or just leave the current name as it exists. + +Click **OK** to save the workspace, or click **Cancel** to not save the workspace. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Save%20Workspace%20As%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---save-workspace-to-file.md b/windows-driver-docs-pr/debugger/file---save-workspace-to-file.md new file mode 100644 index 0000000000..f0eeb9abc9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---save-workspace-to-file.md @@ -0,0 +1,39 @@ +--- +title: File Save Workspace to File +description: File Save Workspace to File +ms.assetid: 7fdb47b2-96fa-4070-a996-814b6201c30c +keywords: ["File Save Workspace to File", "workspaces, File Save Workspace to File"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Save Workspace to File + + +## + + +Click **Save Workspace to File** on the **File** menu to save the current workspace to a file. + +### Dialog Box + +When you click **Save Workspace to File**, the **Save Workspace to File** dialog box appears. In this dialog box, enter the name of the file that you want to save the workspace as. Then, use the **Save in** list to navigate to the directory where you want to save the file, or select a specific file you want to overwrite. (The default file extension is .wew.) + +Click **OK** to save the file, or click **Cancel** to exit. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Save%20Workspace%20to%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---save-workspace.md b/windows-driver-docs-pr/debugger/file---save-workspace.md new file mode 100644 index 0000000000..3b4fcfc219 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---save-workspace.md @@ -0,0 +1,33 @@ +--- +title: File Save Workspace +description: File Save Workspace +ms.assetid: 6ad31213-071a-42e3-8586-afb83e71d9a3 +keywords: ["File Save Workspace", "workspaces, File Save Workspace"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Save Workspace + + +## + + +Click **Save Workspace** on the **File** menu to save the current workspace under its current workspace name. + +### Additional Information + +For more information about the different levels of workspaces and how to use them, see [Using Workspaces](using-workspaces.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Save%20Workspace%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---source-file-path.md b/windows-driver-docs-pr/debugger/file---source-file-path.md new file mode 100644 index 0000000000..9cd1998ae8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---source-file-path.md @@ -0,0 +1,53 @@ +--- +title: File Source File Path +description: File Source File Path +ms.assetid: 2fa7cbc1-a1e6-411b-95d2-18fd183ee117 +keywords: ["File Source File Path", "source files and paths, File Source File Path"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Source File Path + + +## + + +Click **Source File Path** on the **File** menu to display, set, or append to the source path. + +This command is equivalent to pressing CTRL+P. + +### Source Search Path Dialog Box + +When you click **Source File Path**, the **Source Search Path** dialog box appears. This dialog box displays the current source path. If the **Source path** box is blank, there is no current source path. + +You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons. + +If you are performing remote debugging, the **Local** check box will be available. Select this box to edit your debugging client's local source path; clear it to edit the debugging server's source path. + +Click **OK** to save changes, or click **Cancel** to discard changes. + +You can also click **Browse** to open the **Browse For Folder** dialog box. + +### Browse For Folder Dialog Box + +In the **Browse For Folder** dialog box, you can browse through the folders on your computer or your network. You can also click the **Make New Folder** button to create a new folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears. + +Click **OK** to append the selected folder to the source path and return to the **Source Search Path** dialog box. + +### Additional Information + +For more information and for other ways to change this path, see [Source Path](source-path.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Source%20File%20Path%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file---symbol-file-path.md b/windows-driver-docs-pr/debugger/file---symbol-file-path.md new file mode 100644 index 0000000000..0ec62c7f91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file---symbol-file-path.md @@ -0,0 +1,53 @@ +--- +title: File Symbol File Path +description: File Symbol File Path +ms.assetid: 22d32b1b-d1b9-4627-99ed-08656da9b849 +keywords: ["File Symbol File Path", "symbol files and paths, File Symbol File Path"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File | Symbol File Path + + +## + + +Click **Symbol File Path** on the **File** menu to display, set, or append to the symbol path. + +This command is equivalent to pressing CTRL+S. + +### Symbol Search Path Dialog Box + +When you click **Symbol File Path**, the **Symbol Search Path** dialog box appears. This dialog box displays the current symbol path. If the **Symbol path** box is blank, there is no current symbol path. + +You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons. + +Click **OK** to save changes, or click **Cancel** to discard changes. + +If you select the **Reload** check box, the debugger will reload all loaded symbols and images after you click **OK**. The **Reload** command is equivalent to using the [**.reload (Reload Module)**](-reload--reload-module-.md) command. + +You can also click **Browse** to open the **Browse For Folder** dialog box. + +### Browse For Folder Dialog Box + +In the **Browse For Folder** dialog box, you can browse through the folders on your computer or your network. You can also click the **Make New Folder** button to create a new folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears. + +Click **OK** to append the selected folder to the symbol path and return to the **Symbol Search Path** dialog box. + +### Additional Information + +For more information and for other ways to change the symbol path, see [Symbol Path](symbol-path.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20|%20Symbol%20File%20Path%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file-menu.md b/windows-driver-docs-pr/debugger/file-menu.md new file mode 100644 index 0000000000..eb76cdebfe --- /dev/null +++ b/windows-driver-docs-pr/debugger/file-menu.md @@ -0,0 +1,67 @@ +--- +title: File Menu +description: File Menu +ms.assetid: ce9652a8-cee5-4294-b90b-fe1a24a862dc +--- + +# File Menu + + +## + + +This section describes the following commands on the **File** menu of WinDbg: + +[File | Open Source File](file---open-source-file.md) + +[File | Close Current Window](file---close-current-window.md) + +[File | Open Executable](file---open-executable.md) + +[File | Attach to a Process](file---attach-to-a-process.md) + +[File | Open Crash Dump](file---open-crash-dump.md) + +[File | Connect to Remote Session](file---connect-to-remote-session.md) + +[File | Connect to Remote Stub](file---connect-to-remote-stub.md) + +[File | Kernel Debug](file---kernel-debug.md) + +[File | Symbol File Path](file---symbol-file-path.md) + +[File | Source File Path](file---source-file-path.md) + +[File | Image File Path](file---image-file-path.md) + +[File | Open Workspace](file---open-workspace.md) + +[File | Save Workspace](file---save-workspace.md) + +[File | Save Workspace As](file---save-workspace-as.md) + +[File | Clear Workspace](file---clear-workspace.md) + +[File | Delete Workspaces](file---delete-workspaces.md) + +[File | Open Workspace in File](file---open-workspace-in-file.md) + +[File | Save Workspace to File](file---save-workspace-to-file.md) + +[File | Map Network Drive](file---map-network-drive.md) + +[File | Disconnect Network Drive](file---disconnect-network-drive.md) + +[File | Recent Files](file---recent-files.md) + +[File | Exit](file---exit.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/file-share--smb--symbol-server.md b/windows-driver-docs-pr/debugger/file-share--smb--symbol-server.md new file mode 100644 index 0000000000..a1430b58e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file-share--smb--symbol-server.md @@ -0,0 +1,123 @@ +--- +title: File Share (SMB) Symbol Server +description: Running a SMB Symbol Server is simply a matter of creating a file share and granting users access to that file share. +ms.assetid: C5CF9665-9289-48EB-AA12-8881F812488A +--- + +# File Share (SMB) Symbol Server + + +Running a SMB Symbol Server is simply a matter of creating a file share and granting users access to that file share. + +## Creating a SMB File Share Symbol Store + + +Use Windows Explorer or Computer Management to create the File Share and assign security. These steps assume that the symbols will be located in *D:\\SymStore\\Symbols*. Complete these steps using Windows Explorer: + +1. Open **Windows Explorer**. + +2. Right-click *D:\\SymStore\\Symbols* and choose **Properties**. + +3. Click on the **Sharing** tab. + +4. Click on **Advanced Sharing**… . + +5. Check *Share this folder*. + +6. Click on **Permissions**. + +7. Remove the *Everyone* group. + +8. Using **Add…**, add the Users/Security Groups requiring access. + +9. For each User/Security Group added, grant Read or Read/Change access. + +10. Click on **OK** (Permissions dialog). + +11. Click on **OK** (Advanced Sharing dialog). + +12. Press **Close** (Properties dialog). + +Complete these steps using Computer Management: + +1. Type *Computer* in Window Start (resolves as This PC in Windows 8). + +2. Right-click and select *Manage*. + +3. Navigate to *System Tools | Shared Folders | Shares*. + +4. Right-click and select **New | Share…** . + +5. Press **Next** (Create a Shared Folder Wizard dialog). + +6. Enter **D:\\SymStore\\Symbols** as the Folder Path. + +7. Press **Next** twice. + +8. Select **Customize permissions**. + +9. Press **Custom…** . + +10. Remove *Everyone*. + +11. Using **Add…**, add the Users/Security Groups requiring access. + +12. For each User/Security Group added, grant Read or Read/Change access. + +13. Press **OK** (Customize Permissions dialog). + +14. Press **Finish** twice to complete the process. + +## Test The SMB File Share + + +Configure a debugger to use this symbol path: + +``` +srv*C:\Symbols*\\MachineName\Symbols +``` + +To view the location of the PDBs being referenced in the debugger, use the lm (list modules) command. The path to the PDBs should all begin with C:\\Symbols. By running “!sym noisy”, and “.reload /f”, you will see extensive symbol logging of the download of the symbols and images from the \\\\MachineName\\Symbols file server to C:\\Symbols. + +## File Share Symbol Path + + +There are multiples ways to configure your debugger’s symbol path (.sympath) to use a File Share. The syntax of the symbol path determines if the symbol file will be cached locally or not, and where it is cached. + +Direct File Share use (no local caching): + +``` +srv*\\MachineName\Symbols +``` + +Local Caching of the File Share’s files to a particular local folder (e.g. c:\\Symbols): + +``` +srv*c:\Symbols*\\MachineName\Symbols +``` + +Local Caching of the File Share’s files to the %DBGHELP\_HOMEDIR%\\Sym folder: + +``` +srv**\\MachineName\Symbols +``` + +The second “\*” in the example shown above, represents the default local server cache. + +If the DBGHELP\_HOMEDIR variable is not set, DBGHELP\_HOMEDIR defaults to the debugger executable folder (for example C:\\Program Files\\Windows Kits\\10.0\\Debuggers\\x86) and causes caching to occur in C:\\Program Files\\Windows Kits\\10.0\\Debuggers\\x86\\Sym. + +## Related topics + + +[Symbol Store Folder Tree](symbol-store-folder-tree.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20Share%20%28SMB%29%20Symbol%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/file-system-references-and-symbol-files.md b/windows-driver-docs-pr/debugger/file-system-references-and-symbol-files.md new file mode 100644 index 0000000000..e6f83d2c27 --- /dev/null +++ b/windows-driver-docs-pr/debugger/file-system-references-and-symbol-files.md @@ -0,0 +1,33 @@ +--- +title: File System References and Symbol Files +description: File System References and Symbol Files +ms.assetid: c667380f-2942-453c-9ec8-70d3e1355e72 +keywords: ["SymStore, short file names", "short file names and SymStore"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File System References and Symbol Files + + +## + + +Files on disk can have both long file names and automatically generated abbreviated MS-DOS compatible 8.3 short file names. After adding a symbol file to a symbol store, it is possible that the symbols in that symbol file may not be accessible during debug if the symbol file contains any abbreviated MS-DOS 8.3 file names. + +When the tools create a symbol file, the version of the file name that is recorded in the symbol file debug record depends on the tools and how they are run. If a symbol file has an abbreviated MS-DOS 8.3 file name instead of the actual file name embedded in the record, symbol loading at debug time may experience problems because the abbreviated file names vary from system to system. If this problem occurs, the contents of these symbol files may not be accessible during debug. Whenever possible, the user should refrain from using abbreviated file path names when creating symbol files. Some ways to use abbreviated file names inadvertently are to use the abbreviated file path name for a source file, an *include* directory, or an included library file. + +For further information, see [Matching Symbol Names](matching-symbol-names.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20File%20System%20References%20and%20Symbol%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/filtering-the-logviewer-function-list.md b/windows-driver-docs-pr/debugger/filtering-the-logviewer-function-list.md new file mode 100644 index 0000000000..2b3cdb7205 --- /dev/null +++ b/windows-driver-docs-pr/debugger/filtering-the-logviewer-function-list.md @@ -0,0 +1,39 @@ +--- +title: Filtering the LogViewer Function List +description: Filtering the LogViewer Function List +ms.assetid: 258da8c3-ab94-40bd-bfa5-344571d34428 +keywords: ["LogViewer, filtering the LogViewer function list"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Filtering the LogViewer Function List + + +## + + +Logger usually captures some function calls that are not needed for your analysis. These can be filtered out by Logger when it creates the log file. However, this process is not reversible, so it is usually preferable to allow all functions to be logged, and then filter the display in LogViewer. + +There are several ways to filter out function calls in LogViewer: + +- In the main viewing area, selected a function by clicking on it or using the cursor keys. (When a function is selected, LogViewer outlines it in red.) Then, press the DELETE key, or right-click and select **Hide**. This will hide all instances of that function call from view. + +- Select **View | APIs Display**. A dialog box will appear that has three areas. On the right is an alphabetical listing of all functions, and on the left are categorical groupings. You can enable or disable the display of any function by checking or clearing the box to the left of its name. + +- Select **View | Modules Display**. A dialog box will appear that allows you to select calling modules; only those functions that were called from these modules will be displayed. + +- Select **View | First Level Calls Only**. This will display only calls that have "d0" in the left column. It is often desirable to hide function calls that are made by other logged functions. (For example, it is usually not interesting to know that **ShellExecuteEx** makes thirty different registry calls during its course of execution.) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Filtering%20the%20LogViewer%20Function%20List%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/finding-a-kernel-mode-memory-leak.md b/windows-driver-docs-pr/debugger/finding-a-kernel-mode-memory-leak.md new file mode 100644 index 0000000000..970acac14a --- /dev/null +++ b/windows-driver-docs-pr/debugger/finding-a-kernel-mode-memory-leak.md @@ -0,0 +1,36 @@ +--- +title: Finding a Kernel-Mode Memory Leak +description: Finding a Kernel-Mode Memory Leak +ms.assetid: 7e707b89-8614-46d7-9c2e-bea2ddf16164 +keywords: ["memory leak, kernel-mode", "memory leak, kernel-mode, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Finding a Kernel-Mode Memory Leak + + +Use the following techniques to determine the cause of a kernel-mode memory leak: + +[Using PoolMon to Find a Kernel-Mode Memory Leak](using-poolmon-to-find-a-kernel-mode-memory-leak.md) + +[Using the Kernel Debugger to Find a Kernel-Mode Memory Leak](using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md) + +[Using Driver Verifier to Find a Kernel-Mode Memory Leak](using-driver-verifier-to-find-a-kernel-mode-memory-leak.md) + +If you do not know which kernel-mode driver or component is responsible for the leak, you should use the PoolMon technique first. This technique reveals the pool tag associated with the memory leak; the driver or component that uses this pool tag is responsible for the leak. + +If you have already identified the responsible driver or component, use the second and third techniques in the preceding list to determine the cause of the leak more specifically. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Finding%20a%20Kernel-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/finding-a-memory-leak.md b/windows-driver-docs-pr/debugger/finding-a-memory-leak.md new file mode 100644 index 0000000000..9eeecdac1b --- /dev/null +++ b/windows-driver-docs-pr/debugger/finding-a-memory-leak.md @@ -0,0 +1,37 @@ +--- +title: Finding a Memory Leak +description: Finding a Memory Leak +ms.assetid: 1227c5e8-d83b-4f27-aa69-6e54aebc3ad8 +keywords: ["memory leak", "memory leak, debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Finding a Memory Leak + + +## + + +A memory leak occurs when a process allocates memory from the paged or nonpaged pools, but does not free the memory. As a result, these limited pools of memory are depleted over time, causing Windows to slow down. If memory is completely depleted, failures may result. + +This section includes the following: + +- [Determining Whether a Leak Exists](determining-whether-a-leak-exists.md) describes a technique you can use if you are not sure whether there is a memory leak on your system. + +- [Finding a Kernel-Mode Memory Leak](finding-a-kernel-mode-memory-leak.md) describes how to find a leak that is caused by a kernel-mode driver or component. + +- [Finding a User-Mode Memory Leak](finding-a-user-mode-memory-leak.md) describes how to find a leak that is caused by a user-mode driver or application. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Finding%20a%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/finding-a-user-mode-memory-leak.md b/windows-driver-docs-pr/debugger/finding-a-user-mode-memory-leak.md new file mode 100644 index 0000000000..507e2f274f --- /dev/null +++ b/windows-driver-docs-pr/debugger/finding-a-user-mode-memory-leak.md @@ -0,0 +1,32 @@ +--- +title: Finding a User-Mode Memory Leak +description: Finding a User-Mode Memory Leak +ms.assetid: 5ce5a237-d2c4-4fca-9fb4-d927522a5352 +keywords: ["memory leak, user-mode", "memory leak, user-mode, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Finding a User-Mode Memory Leak + + +Use the following techniques to determine the cause of a user-mode memory leak: + +[Using Performance Monitor to Find a User-Mode Memory Leak](using-performance-monitor-to-find-a-user-mode-memory-leak.md) + +[Using UMDH to Find a User-Mode Memory Leak](using-umdh-to-find-a-user-mode-memory-leak.md) + +The first technique determines which process is leaking memory. After you know which process is involved, the second technique can determine the specific routine that is at fault. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Finding%20a%20User-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/finding-the-failed-process.md b/windows-driver-docs-pr/debugger/finding-the-failed-process.md new file mode 100644 index 0000000000..02b5439ab3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/finding-the-failed-process.md @@ -0,0 +1,160 @@ +--- +title: Finding the Failed Process +description: Finding the Failed Process +ms.assetid: 64d1fa71-940f-4f67-87a6-00d41d6f24e0 +keywords: ["process, finding failed process"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Finding the Failed Process + + +## + + +Before finding the failed process, make sure that you are in the context of the accepting processor. To determine the accepting processor, use the [**!pcr**](-pcr.md) extension on each processor and looking for the processor for which an exception handler has been loaded. The exception handler of the accepting processor has an address other than 0xFFFFFFFF. + +For example, because the address of **NtTib.ExceptionList** on this processor, is 0xFFFFFFFF, this is not the processor with the failed process: + +``` +0: kd> !pcr +PCR Processor 0 @ffdff000 + NtTib.ExceptionList: ffffffff + NtTib.StackBase: 80470650 + NtTib.StackLimit: 8046d860 + NtTib.SubSystemTib: 00000000 + NtTib.Version: 00000000 + NtTib.UserPointer: 00000000 + NtTib.SelfTib: 00000000 + + SelfPcr: ffdff000 + Prcb: ffdff120 + Irql: 00000000 + IRR: 00000000 + IDR: ffffffff + InterruptMode: 00000000 + IDT: 80036400 + GDT: 80036000 + TSS: 80257000 + + CurrentThread: 8046c610 + NextThread: 00000000 + IdleThread: 8046c610 + + DpcQueue: +``` + +However, the results for Processor 1 are quite different. In this case, the value of **NtTib.ExceptionList** is **f0823cc0**, not 0xFFFFFFFF, indicating that this is the processor on which the exception occurred. + +``` +0: kd> ~1 +1: kd> !pcr +PCR Processor 1 @81497000 + NtTib.ExceptionList: f0823cc0 + NtTib.StackBase: f0823df0 + NtTib.StackLimit: f0821000 + NtTib.SubSystemTib: 00000000 + NtTib.Version: 00000000 + NtTib.UserPointer: 00000000 + NtTib.SelfTib: 00000000 + + SelfPcr: 81497000 + Prcb: 81497120 + Irql: 00000000 + IRR: 00000000 + IDR: ffffffff + InterruptMode: 00000000 + IDT: 8149b0e8 + GDT: 8149b908 + TSS: 81498000 + + CurrentThread: 81496d28 + NextThread: 00000000 + IdleThread: 81496d28 + + DpcQueue: +``` + +When you are in the correct processor context, the [**!process**](-process.md) extension displays the currently running process. + +The most interesting parts of the process dump are: + +- The times (a high value indicates that process might be the culprit). + +- The handle count (this is the number in parentheses after **ObjectTable** in the first entry). + +- The thread status (many processes have multiple threads). If the current process is *Idle*, it is likely that either the machine is truly idle or it hung due to some unusual problem. + +Although using the **!process 0 7** extension is the best way to find the problem on a hung system, it is sometimes too much information to filter. Instead, use a **!process 0 0** and then a **!process** on the process handle for CSRSS and any other suspicious processes. + +When using a **!process 0 7**, many of the threads might be marked "kernel stack not resident" because those stacks are paged out. If those pages are still in the cache that is in transition, you can get more information by using a **.cache decodeptes** before **!process 0 7**: + +``` +kd> .cache decodeptes +kd> !process 0 7 +``` + +If you can identify the failing process, use **!process** *<process>* **7** to show the kernel stacks for each thread in the process. This output can identify the problem in kernel mode and reveal what the suspect process is calling. + +In addition to **!process**, the following extensions can help to determine the cause of an unresponsive computer: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExtensionEffect

[!ready](-ready.md)

Identifies the threads that are ready to run, in order of priority.

[!kdext*.locks](-locks---kdext--locks-.md)

Identifies any held resource locks, in case there is a deadlock with retail time outs.

[!vm](-vm.md)

Checks the virtual memory usage.

[!poolused](-poolused.md)

Determines whether one type of pool allocation is disproportionately large (pool tagging required).

[!memusage](-memusage.md)

Checks the physical memory status.

[!heap](-heap.md)

Checks the validity of the heap.

[!irpfind](-irpfind.md)

Searches nonpaged pool for active IRPs.

+ +  + +If the information provided does not indicate an unusual condition, try setting a breakpoint at **ntoskrnl!KiSwapThread** to determine whether the processor is stuck in one process or if it is still scheduling other processes. If it is not stuck, set breakpoints in common functions, such as **NtReadFile**, to determine whether the computer is stuck in a specific code path. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Finding%20the%20Failed%20Process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/finding-the-process-id.md b/windows-driver-docs-pr/debugger/finding-the-process-id.md new file mode 100644 index 0000000000..075eef13bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/finding-the-process-id.md @@ -0,0 +1,59 @@ +--- +title: Finding the Process ID +description: Finding the Process ID +ms.assetid: 963e9b5b-2b88-41b5-a103-dc4611ff41ea +keywords: ["process, process ID (PID)", "PID (process ID)", "TList, related techniques", "Task Manager"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Finding the Process ID + + +## + + +Each process running in Microsoft Windows is assigned a unique decimal number called the *process ID*, or *PID*. This number is used to specify the process when attaching a debugger to it. + +There are several ways to determine the PID for a given application: using the Task Manager, using the **tasklist** command, using the TList utility, or using the debugger. + +### Task Manager + +The *Task Manager* may be activated in a number of ways, but the simplest is to press CTRL+ALT+DELETE and then click **Task Manager**. + +If you select the **Processes** tab, each process and its PID will be listed, along with other useful information. + +Some kernel errors may cause delays in Task Manager's graphical interface. + +### The Tasklist Command + +In Windows XP and later versions of Windows, you can use the **tasklist** command from a Command Prompt window. This displays all processes, their PIDs, and a variety of other details. + +### TList + +TList (Task List Viewer, tlist.exe) is a command-line utility that displays a list of tasks, or user-mode processes, currently running on the local computer. TList is included in the Debugging Tools for Windows package. + +When you run TList from the command prompt, it will display a list of all the user-mode processes in memory with a unique process identification (PID) number. For each process, it shows the PID, process name, and, if the process has a window, the title of that window. + +For more information, see [TList](tlist.md). + +### The .tlist Debugger Command + +If there is already a user-mode debugger running on the system in question, the [**.tlist (List Process IDs)**](-tlist--list-process-ids-.md) command will display a list of all PIDs on that system. + +### CSRSS and User-Mode Drivers + +To debug a user-mode driver running on another computer, debug the Client Server Run-Time Subsystem (CSRSS) process. For more information, see [Debugging CSRSS](debugging-csrss.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Finding%20the%20Process%20ID%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/firewalls-and-proxy-servers.md b/windows-driver-docs-pr/debugger/firewalls-and-proxy-servers.md new file mode 100644 index 0000000000..ce4a4d511f --- /dev/null +++ b/windows-driver-docs-pr/debugger/firewalls-and-proxy-servers.md @@ -0,0 +1,63 @@ +--- +title: Firewalls and Proxy Servers +description: Firewalls and Proxy Servers +ms.assetid: 6b438602-299e-4cc5-ac75-ac9ee3cb50bb +keywords: ["SymSrv, firewalls and proxy servers", "firewalls and SymSrv", "internet firewalls and SymSrv", "proxy servers and SymSrv"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Firewalls and Proxy Servers + + +## + + +If you are using SymSrv to access symbols, and your computer is on a network that uses a proxy server or the symbol store is outside your firewall, authentication may be required for data transmission to take place. + +When SymSrv receives authentication requests, the debugger can either display the authentication request or automatically refuse the request, depending on how it has been configured. + +SymSrv has integrated support for a proxy server. It can either use the default proxy server, [SymProxy](symproxy.md), or it can use another proxy server of your choice. + +### Authentication Requests + +The debugger can be configured to allow authentication requests. When a firewall or proxy server requests authorization, a dialog box will appear. You will have to enter some sort of information (usually a user name and password) before the debugger can download symbols. If you enter incorrect information, the dialog box will be redisplayed. If you select the **Cancel** button, the dialog box will vanish and no symbol information will be transferred. + +If the debugger is configured to refuse all authentication requests, no dialog box will appear, and no symbols will be transferred if authentication is required. + +If you refuse an authentication request, or if the debugger automatically refuses an authentication request, SymSrv will make no further attempts to contact the symbol store. If you wish to renew contact, you must either restart the debugging session or use [**!symsrv close**](-symsrv.md). + +**Note**   If you are using KD or CDB, the authentication dialog box may appear behind an open window. If this occurs, you may have to move or minimize some windows in order to find this dialog box. + +  + +In WinDbg, authentication requests are allowed by default. In KD and CDB, authentication requests are automatically refused by default. + +To allow authentication requests, use either [**!sym prompts**](-sym.md) or [**.symopt-0x80000**](-symopt--set-symbol-options-.md). To refuse all requests, use either **!sym prompts off** or **.symopt+0x80000**. To display the current setting, use **!sym**. + +You must use [**.reload (Reload Module)**](-reload--reload-module-.md) after making any changes to the authentication permission status. + +### Choosing a Proxy Server + +To select a default proxy server for Windows, open **Internet Options** in Control Panel, select the **Connections** tab, and then select the **LAN Settings** button. You can then enter the proxy server name and port number, or select **Advanced** to configure multiple proxy servers. For more details, see Internet Explorer's help file. + +To select a specific proxy server for symsrv to use, set the \_NT\_SYMBOL\_PROXY environment variable equal to the name or IP of the proxy server, followed by a colon and then the port number. For example: + +``` +set _NT_SYMBOL_PROXY=myproxyserver:80 +``` + +When a proxy server is chosen in this way, it will be used by any Windows debugger that is using SymSrv to access a symbol server. It will also be used by any other debugging tool that uses DbgHelp as its symbol handler. No other programs will be affected by this setting. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Firewalls%20and%20Proxy%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-debugger.md b/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-debugger.md new file mode 100644 index 0000000000..106bfd5cd8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-debugger.md @@ -0,0 +1,33 @@ +--- +title: Forcing a System Crash from the Debugger +description: Forcing a System Crash from the Debugger +ms.assetid: 7d7d9b07-00a3-4f87-8eb9-01b3f2fa312f +keywords: ["system crash, causing from debugger", "bug check, causing from debugger", "forcing system crash from debugger"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Forcing a System Crash from the Debugger + + +## + + +If KD or WinDbg is performing kernel-mode debugging, it can force a system crash to occur. This is done by entering the [**.crash (Force System Crash)**](-crash--force-system-crash-.md) command at the command prompt. (If the target computer does not crash immediately, follow this with the [**g (Go)**](g--go-.md) command.) + +When this command is issued, the system will call **KeBugCheck** and issue [**bug check 0xE2**](bug-check-0xe2--manually-initiated-crash.md) (MANUALLY\_INITIATED\_CRASH). Unless crash dumps have been disabled, a crash dump file is written at this point. + +After the crash dump file has been written, the kernel debugger on the host computer will be alerted and can be used to actively debug the crashed target. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Forcing%20a%20System%20Crash%20from%20the%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-keyboard.md b/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-keyboard.md new file mode 100644 index 0000000000..e9bfd57e91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/forcing-a-system-crash-from-the-keyboard.md @@ -0,0 +1,166 @@ +--- +title: Forcing a System Crash from the Keyboard +description: Forcing a System Crash from the Keyboard +ms.assetid: 0c3ec6f3-d233-46e4-b599-1a0f89318ed2 +keywords: ["boot process, causing system crash from keyboard", "CTRL+SCROLL LOCK", "system crash, causing from keyboard", "bug check, causing from keyboard", "keyboard-caused system crash", "USB keyboard and system crash", "PS/2 keyboard and system crash", "forcing system crash from keyboard"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Forcing a System Crash from the Keyboard + + +## + + +Most of the following keyboards can cause a system crash directly: + + PS/2 keyboards connected on i8042prt ports +This feature is available in Windows 2000 and later versions of Windows operating system. + + USB keyboards +This feature is available in: + +- Windows Server 2003 Service Pack 1 if the hotfix available with [KB 244139](http://go.microsoft.com/fwlink/p/?linkid=106065) is installed. + +- Windows Server 2003 (with Service Pack 2 or later). + +- Windows Vista Service Pack 1 if the hotfix available with [KB 971284](http://go.microsoft.com/fwlink/p/?LinkId=241349) is installed. + +- Windows Vista Service Pack 2. + +- Windows Server 2008 Service Pack 1 if the hotfix available with [KB 971284](http://go.microsoft.com/fwlink/p/?LinkId=241349) is installed. +- Windows Server 2008 (with Service Pack 2 or later). +- Windows 7 and later versions of Windows operating system. + +**Note**  This feature is not available in Windows XP. + +  + +You must ensure the following three settings before the keyboard can cause a system crash: + +1. If you wish a crash dump file to be written, you must enable such dump files, choose the path and file name, and select the size of the dump file. For more information, see [Enabling a Kernel-Mode Dump File](enabling-a-kernel-mode-dump-file.md). + +2. With PS/2 keyboards, you must enable the keyboard-initiated crash in the registry. In the registry key **HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Services\\i8042prt\\Parameters**, create a value named **CrashOnCtrlScroll**, and set it equal to a REG\_DWORD value of 0x01. + +3. With USB keyboards, you must enable the keyboard-initiated crash in the registry. In the registry key **HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Services\\kbdhid\\Parameters,** create a value named **CrashOnCtrlScroll**, and set it equal to a REG\_DWORD value of 0x01. + +You must restart the system for these settings to take effect. + +After this is completed, the keyboard crash can be initiated by using the following hotkey sequence: Hold down the rightmost CTRL key, and press the SCROLL LOCK key twice. + +The system then calls **KeBugCheck** and issues [**bug check 0xE2**](bug-check-0xe2--manually-initiated-crash.md) (MANUALLY\_INITIATED\_CRASH). Unless crash dumps have been disabled, a crash dump file is written at this point. + +If a kernel debugger is attached to the crashed machine, the machine will break into the kernel debugger after the crash dump file has been written. + +For more information on using this feature, refer to the article [Generate a memory dump file by using the keyboard (KB 244139)](http://go.microsoft.com/fwlink/p/?linkid=106065). + +### Defining Alternate Keyboard Shortcuts to Force a System Crash from the Keyboard + +You can configure values under the following registry subkeys for different keyboard shortcut sequences to generate the memory dump file: + +- For PS/2 keyboards: + + **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\i8042prt\\crashdump** + +- For USB keyboards: + + **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\kbdhid\\crashdump** + +You must create the following registry REG\_DWORD values under these subkeys: + +**Dump1Keys** +The **Dump1Keys** registry value is a bit map of the first hot key to use. For example, instead of using the rightmost CTRL key to initiate the hot key sequence, you can set the first hot key to be the leftmost SHIFT key. + +The values for the first hot key are described in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueFirst key used in the keyboard shortcut sequence

0x01

Rightmost SHIFT key

0x02

Rightmost CTRL key

0x04

Rightmost ALT key

0x10

Leftmost SHIFT key

0x20

Leftmost CTRL key

0x40

Leftmost ALT key

+ +  + +**Note**  You can assign **Dump1Keys** a value that enables one or more keys as the first key used in the keyboard shortcut sequence. For example, assign **Dump1Keys** a value of 0x11 to define both the rightmost and leftmost SHIFT keys as the first key in the keyboard shortcut sequence. + +  + +**Dump2Key** +The **Dump2Key** registry value is the index into the scancode table for the keyboard layout of the target computer. The following is the actual table in the driver. + +``` +const UCHAR keyToScanTbl[134] = { + 0x00,0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09, + 0x0A,0x0B,0x0C,0x0D,0x7D,0x0E,0x0F,0x10,0x11,0x12, + 0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,0x00, + 0x3A,0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26, + 0x27,0x28,0x2B,0x1C,0x2A,0x00,0x2C,0x2D,0x2E,0x2F, + 0x30,0x31,0x32,0x33,0x34,0x35,0x73,0x36,0x1D,0x00, + 0x38,0x39,0xB8,0x00,0x9D,0x00,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0xD2,0xD3,0x00,0x00,0xCB, + 0xC7,0xCF,0x00,0xC8,0xD0,0xC9,0xD1,0x00,0x00,0xCD, + 0x45,0x47,0x4B,0x4F,0x00,0xB5,0x48,0x4C,0x50,0x52, + 0x37,0x49,0x4D,0x51,0x53,0x4A,0x4E,0x00,0x9C,0x00, + 0x01,0x00,0x3B,0x3C,0x3D,0x3E,0x3F,0x40,0x41,0x42, + 0x43,0x44,0x57,0x58,0x00,0x46,0x00,0x00,0x00,0x00, + 0x00,0x7B,0x79,0x70 }; +``` + +**Note**   Index 124 (sysreq) is a special case because an 84-key keyboard has a different scan code. + +  + +If you define alternate keyboard shortcuts to force a system crash from a USB or PS/2 keyboard, you must either set the **CrashOnCtrlScroll** registry value to 0 or remove it from the registry. + +### Limitations + +It is possible for a system to freeze in such a way that the keyboard shortcut sequence will not work. However, this should be a very rare occurrence. Using the keyboard shortcut sequence to initiate a crash will work even in many instances where CTRL+ALT+DELETE does not work. + +Forcing a system crash from the keyboard does not work if the computer stops responding at a high interrupt request level (IRQL). This limitation exists because the Kbdhid.sys driver, which allows the memory dump process to run, operates at a lower IRQL than the i8042prt.sys driver. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Forcing%20a%20System%20Crash%20from%20the%20Keyboard%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/forcing-a-system-crash.md b/windows-driver-docs-pr/debugger/forcing-a-system-crash.md new file mode 100644 index 0000000000..f48f20c600 --- /dev/null +++ b/windows-driver-docs-pr/debugger/forcing-a-system-crash.md @@ -0,0 +1,47 @@ +--- +title: Forcing a System Crash +description: Forcing a System Crash +ms.assetid: db93b032-2ca7-4197-87dd-4ae77c328f60 +keywords: ["system crash, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Forcing a System Crash + + +## + + +Once kernel-mode dump files have been [enabled](enabling-a-kernel-mode-dump-file.md), most system crashes should cause a crash file to be written and the blue screen to be displayed. + +However, there are times that a system freezes without actually initiating a kernel crash. Possible symptoms of such a freeze include: + +- The mouse pointer moves, but can't do anything. + +- All video is frozen, the mouse pointer does not move, but paging continues. + +- There is no response at all to the mouse or keyboard, and no use of the disk. + +If an experienced debugging technician is present, he or she can hook up a kernel debugger and analyze the problem. For some tips on what to look for when this situation occurs, see [Debugging a Stalled System](debugging-a-stalled-system.md). + +However, if no technician is present, you may wish to create a kernel-mode dump file and send it to an off-site technician. This dump file can be used to analyze the cause of the error. + +There are two ways to deliberately cause a system crash: + +[Forcing a System Crash from the Debugger](forcing-a-system-crash-from-the-debugger.md) + +[Forcing a System Crash from the Keyboard](forcing-a-system-crash-from-the-keyboard.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Forcing%20a%20System%20Crash%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/full-user-mode-dumps.md b/windows-driver-docs-pr/debugger/full-user-mode-dumps.md new file mode 100644 index 0000000000..afe6088dcf --- /dev/null +++ b/windows-driver-docs-pr/debugger/full-user-mode-dumps.md @@ -0,0 +1,39 @@ +--- +title: Full User-Mode Dumps +description: Full User-Mode Dumps +ms.assetid: 7bf69ca0-afee-4c30-b24f-984e5d411f1b +keywords: ["dump file, full user-mode dump", "full user-mode dump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Full User-Mode Dumps + + +## + + +A *full user-mode dump* is the basic user-mode dump file. + +This dump file includes the entire memory space of a process, the program's executable image itself, the handle table, and other information that will be useful to the debugger. + +It is possible to "shrink" a full user-mode dump file into a minidump. Simply load the dump file into the debugger and then use the [**.dump (Create Dump File)**](-dump--create-dump-file-.md) command to save a new dump file in minidump format. + +**Note**   Despite their names, the largest "minidump" file actually contains more information than the full user-mode dump. For example, **.dump /mf** or **.dump /ma** will create a larger and more complete file than **.dump /f**. + +  + +In user mode, **.dump /m\[***MiniOptions***\]** is the best choice. The dump files created with this switch can vary in size from very small to very large. By specifying the proper *MiniOptions* you can control exactly what information is included. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Full%20User-Mode%20Dumps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/g--go-.md b/windows-driver-docs-pr/debugger/g--go-.md new file mode 100644 index 0000000000..9b93fd7203 --- /dev/null +++ b/windows-driver-docs-pr/debugger/g--go-.md @@ -0,0 +1,100 @@ +--- +title: g (Go) +description: The g command starts executing the given process or thread. Execution will halt at the end of the program, when BreakAddress is hit, or when another event causes the debugger to stop. +ms.assetid: 9b6aac94-6c53-40c2-a8de-2ad106678c65 +keywords: ["g (Go) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- g (Go) +api_type: +- NA +--- + +# g (Go) + + +The **g** command starts executing the given process or thread. Execution will halt at the end of the program, when *BreakAddress* is hit, or when another event causes the debugger to stop. + +User-Mode Syntax + +``` +[~Thread] g[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +Kernel-Mode Syntax + +``` +g[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +## Parameters + + + *Thread* +(User mode only) Specifies the thread to execute. For syntax details, see [Thread Syntax](thread-syntax.md). + + **a** +Causes any breakpoint created by this command to be a processor breakpoint (like those created by [**ba**](ba--break-on-access-.md)) rather than a software breakpoint (like those created by [**bp**](bp--bu--bm--set-breakpoint-.md) and **bm**). If *BreakAddress* is not specified, no breakpoint is created and the **a** flag has no effect. + + *StartAddress* +Specifies the address where execution should begin. If this is not specified, the debugger passes execution to the address specified by the current value of the instruction pointer. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakAddress* +Specifies the address for a breakpoint. If *BreakAddress* is specified, it must specify an instruction address (that is, the address must contain the first byte of an instruction). Up to ten break addresses, in any order, can be specified at one time. If *BreakAddress* cannot be resolved, it is stored as an [unresolved breakpoint](unresolved-breakpoints---bu-breakpoints-.md). For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakCommands* +Specifies one or more commands to be automatically executed when the breakpoint specified by *BreakAddress* is hit. The *BreakCommands* parameter must be preceded by a semicolon. If multiple *BreakAddress* values are specified, *BreakCommands* applies to all of them. + +**Note**   The *BreakCommands* parameter is only available when you are embedding this command within a command string used by another command -- for example, within another breakpoint command or within an except or event setting. On a command line, the semicolon will terminate the **g** command, and any additional commands listed after the semicolon will be executed immediately after the **g** command is done. + +  + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of issuing this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +If *Thread* is specified, then the **g** command is executed with the specified thread unfrozen and all others frozen. For example, if the **~123g**, **~\#g**, or **~\*g** command is specified, the specified threads are unfrozen and all others are frozen. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20g%20%28Go%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gc--go-from-conditional-breakpoint-.md b/windows-driver-docs-pr/debugger/gc--go-from-conditional-breakpoint-.md new file mode 100644 index 0000000000..7cdb394f76 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gc--go-from-conditional-breakpoint-.md @@ -0,0 +1,84 @@ +--- +title: gc (Go from Conditional Breakpoint) +description: The gc command resumes execution from a conditional breakpoint in the same fashion that was used to hit the breakpoint (stepping, tracing, or freely executing). +ms.assetid: 7850269a-3fc7-48b6-a369-bb020a5e11c3 +keywords: ["gc (Go from Conditional Breakpoint) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gc (Go from Conditional Breakpoint) +api_type: +- NA +--- + +# gc (Go from Conditional Breakpoint) + + +The **gc** command resumes execution from a conditional breakpoint in the same fashion that was used to hit the breakpoint (stepping, tracing, or freely executing). + +``` +gc +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +When a [conditional breakpoint](setting-a-conditional-breakpoint.md) includes an execution command at the end, this should be the **gc** command. + +For example, the following is a proper conditional breakpoint formulation: + +``` +0:000> bp Address "j (Condition) 'OptionalCommands'; 'gc' " +``` + +When this breakpoint is encountered and the expression is false, execution will resume using the same execution type that was previously used. For example, if you used a **g (Go)** command to reach this breakpoint, execution would resume freely. But if you reached this breakpoint while stepping or tracing, execution would resume with a step or a trace. + +On the other hand, the following is an improper breakpoint formulation, since execution will always resume freely even if you had been stepping before reaching the breakpoint: + +``` +0:000> bp Address "j (Condition) 'OptionalCommands'; 'g' " +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20gc%20%28Go%20from%20Conditional%20Breakpoint%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/general-environment-variables.md b/windows-driver-docs-pr/debugger/general-environment-variables.md new file mode 100644 index 0000000000..cb04250de9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/general-environment-variables.md @@ -0,0 +1,106 @@ +--- +title: General Environment Variables +description: General Environment Variables +ms.assetid: 1f37de92-0c62-4317-b3c6-24b3efd9b3b3 +keywords: ["environment variables, general", "_NO_DEBUG_HEAP environment variable", "_NT_ALT_SYMBOL_PATH environment variable", "_NT_DEBUG_HISTORY_SIZE environment variable", "_NT_DEBUG_LOG_FILE_APPEND environment variable", "_NT_DEBUG_LOG_FILE_OPEN environment variable", "_NT_DEBUGGER_EXTENSION_PATH environment variable", "_NT_EXECUTABLE_IMAGE_PATH environment variable", "_NT_SOURCE_PATH environment variable"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# General Environment Variables + + +## + + +The following table lists the environment variables that can be used in both user-mode and kernel-mode debugging. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableMeaning

_NT_DEBUGGER_EXTENSION_PATH = Path

Specifies the path that the debugger will first search for extension DLLs. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;). For details, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md).

_NT_EXECUTABLE_IMAGE_PATH = Path

Specifies the path containing the binary executable files. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;).

_NT_SOURCE_PATH = Path

Specifies the path containing the source files for the target. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;). For details, and for other ways to change this path, see [Source Path](source-path.md).

_NT_SYMBOL_PATH = Path

Specifies the root of a directory tree containing the symbol files. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;). For details, and for other ways to change this path, see [Symbol Path](symbol-path.md).

_NT_ALT_SYMBOL_PATH = Path

Specifies an alternate symbol path searched before _NT_SYMBOL_PATH. This is useful for keeping private versions of symbol files. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;). For details, see [Symbol Path](symbol-path.md).

_NT_SYMBOL_PROXY = Proxy:Port

Specifies the proxy server to be used by SymSrv. For details, see [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md).

_NT_DEBUG_HISTORY_SIZE = Number

Specifies the number of commands in the command history that can be accessed during remote debugging. Because commands vary in length, the number of lines available may not exactly match Number. For details, and for other ways to change this number, see [Using Debugger Commands](using-debugger-commands.md).

_NT_DEBUG_LOG_FILE_OPEN = Filename

(CDB and KD only) Specifies the log file to which the debugger should send output.

_NT_DEBUG_LOG_FILE_APPEND = Filename

(CDB and KD only) Specifies the log file to which the debugger should append output.

_NT_EXPR_EVAL = {masm | c++}

Specifies the default expression evaluator. If masm is specified, MASM expression syntax will be used. If c++ is specified, C++ expression syntax will be used. MASM expression syntax is the default. See [Evaluating Expressions](evaluating-expressions.md) for details.

_NO_DEBUG_HEAP

(Windows XP and later) Specifies that the debug heap should not be used for user-mode debugging.

DBGENG_NO_DEBUG_PRIVILEGE

Prevents processes spawned by the debugger from inheriting SeDebugPrivilege.

DBGENG_NO_BUGCHECK_ANALYSIS

Prevents automated bugcheck analysis.

DBGHELP_HOMEDIR

Specifies the path for the root of the default downstream store used by SymSrv and SrcSrv. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;).

SRCSRV_INI_FILE

Specifies the path and name of the configuration file used by [SrcSrv](srcsrv.md). By default, the path is the srcsrv subdirectory of the Debugging Tools for Windows installation directory, and the file name is Srcsrv.ini. See [Source Indexing](source-indexing.md) for details.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20General%20Environment%20Variables%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/general-extensions.md b/windows-driver-docs-pr/debugger/general-extensions.md new file mode 100644 index 0000000000..1dc9fa7689 --- /dev/null +++ b/windows-driver-docs-pr/debugger/general-extensions.md @@ -0,0 +1,35 @@ +--- +title: General Extensions +description: General Extensions +ms.assetid: 99ff4111-9f65-4e3d-beb3-0aa49f35a015 +keywords: ["extension commands ( commands), general extensions", "exts.dll (general extensions)", "dbghelp.dll (general extensions)", "general extensions (exts.dll - dbghelp.dll)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# General Extensions + + +## + + +This section describes extension commands that are frequently used during both user-mode and kernel-mode debugging. + +The debugger automatically loads the proper version of these extension commands. Unless you have manually loaded a different version, you do not have to keep track of the DLL versions that are being used. For more information about the default module search order, see [Using Debugger Extension Commands](using-debugger-extension-commands.md). For more information about how to load extension modules, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +Each extension command reference topics lists the DLLs that expose that command. Use the following rules to determine the proper directory to load this extension DLL from: + +- If your target computer is running Microsoft Windows XP or a later version of Windows, use winxp\\kdexts.dll, winxp\\ntsdexts.dll, winxp\\exts.dll, winext\\ext.dll, or dbghelp.dll. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20General%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/general-troubleshooting-tips.md b/windows-driver-docs-pr/debugger/general-troubleshooting-tips.md new file mode 100644 index 0000000000..c675805dfe --- /dev/null +++ b/windows-driver-docs-pr/debugger/general-troubleshooting-tips.md @@ -0,0 +1,28 @@ +--- +title: General Tips for Blue Screens +description: General Tips for Blue Screens +ms.assetid: 692bd17f-16bf-4611-9ada-e524d9246a09 +keywords: ["bug check, troubleshooting"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# General Tips for Blue Screens + + +If your computer stops working and displays a blue screen, the computer has shut down abruptly to protect itself from data loss. A hardware device, its driver, or related software might have caused this error. If your copy of Windows came with your computer, you may want to contact the manufacturer of your computer. + +If you have experience with computers and want to try to recover from this error, follow the steps described in [Troubleshoot blue screen errors](http://go.microsoft.com/fwlink/p/?linkid=183646). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20General%20Tips%20for%20Blue%20Screens%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/get-rpc-call-information.md b/windows-driver-docs-pr/debugger/get-rpc-call-information.md new file mode 100644 index 0000000000..3175ebf423 --- /dev/null +++ b/windows-driver-docs-pr/debugger/get-rpc-call-information.md @@ -0,0 +1,88 @@ +--- +title: Get RPC Call Information +description: Get RPC Call Information +ms.assetid: bb883bb1-3ab8-4702-896d-4ff8076bad68 +keywords: ["RPC call information", "SCALL (server call)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Get RPC Call Information + + +## + + +Server-side call (SCALL) information is displayed by the **!rpcexts.getcallinfo** extension, or by DbgRpc when the **-c** switch is used. + +Four optional parameters are permitted. Three of these -- *CallID*, *IfStart*, and *ProcNum* -- are identifying information used by RPC to keep track of its calls. The fourth parameter, *ProcessID*, is the PID of the server process that owns the call. You should supply whatever parameters you know to narrow down the search. + +If no parameters are supplied, all known SCALLs in the system will be displayed. The following is an example of this long display: + +``` +D:\wmsg>dbgrpc -c +Searching for call info ... +## PID CELL ID ST PNO IFSTART TIDNUMBER CALLFLAG CALLID LASTTIME CONN/CLN +---------------------------------------------------------------------------- +00c4 0000.0002 00 00f 82273fdc 0000.0007 00000001 00000002 0003595d 0000.0010 +00c4 0000.0006 00 009 367abb81 0000.0015 00000001 0000004d 000185bd 0000.0005 +00c4 0000.000a 00 007 367abb81 0000.002d 00000001 0000009f 00014672 0000.0009 +00c4 0000.000c 00 007 367abb81 0000.002d 00000001 00000083 000122e3 0000.000b +00c4 0000.000d 00 03b 8d9f4e40 0000.002d 00000001 000000f7 0001aba5 0000.0020 +00c4 0000.000e 00 03b 8d9f4e40 0000.0026 00000001 00000002 00023056 0000.0021 +00c4 0000.000f 00 008 82273fdc 0000.001e 00000009 baadf00d 000366b4 00ec.03bc +00c4 0000.0012 00 00d 8d9f4e40 0000.0004 00000001 00000051 0000a334 0000.0011 +00c4 0000.0014 00 000 367abb81 0000.0015 00000001 0000004c 0002db53 0000.0013 +00c4 0000.0017 00 007 367abb81 0000.0015 00000001 00000006 0000d102 0000.0016 +00c4 0000.0019 00 007 367abb81 0000.0004 00000001 00000006 0000f09e 0000.0018 +00c4 0000.001b 00 009 65a93890 0000.0007 00000001 0000012e 00630f65 0000.001a +00c4 0000.001e 00 026 8d9f4e40 0000.0015 00000001 0000037d 0005e579 0000.002c +00c4 0000.001f 00 008 82273fdc 0000.0033 00000009 baadf00d 000145b3 00c4.02f8 +00c4 0000.0023 00 000 367abb81 0000.0004 00000001 0000007e 000372f3 0000.0022 +00c4 0000.0025 00 03b 8d9f4e40 0000.0026 00000001 0000000b 000122e3 0000.0024 +00c4 0000.0027 00 000 367abb81 0000.002d 00000001 0000000b 00012e27 0000.0028 +00c4 0000.002a 00 008 82273fdc 0000.0033 00000009 baadf00d 0001245f 022c.0290 +00c4 0000.002f 00 007 367abb81 0000.0026 00000001 0000000a 0002983c 0000.002e +00c4 0000.0031 00 004 3ba0ffc0 0000.0026 00000001 00000007 0005c439 0000.001c +00c4 0000.0032 00 00b 82273fdc 0000.0039 00000009 baadf00d 00687db6 00d0.01d4 +00c4 0000.0036 00 007 367abb81 0000.0030 00000001 00000065 0003a5e1 0000.0035 +00c4 0000.0037 00 00d 8d9f4e40 0000.0015 00000001 0000033f 000376fa 0000.002b +00c4 0000.0038 00 008 8d9f4e40 0000.0015 00000001 00000803 0018485c 0000.003b +00c4 0000.003c 00 00b 82273fdc 0000.0034 00000009 baadf00d 0001f956 00a8.0244 +00c4 0000.003d 00 008 82273fdc 0000.0034 00000009 baadf00d 0001ff02 01b8.037c +0170 0000.0009 00 002 e60c73e6 0000.0013 00000009 baadf00d 0005a371 00ec.031c +0170 0000.000a 00 002 0b0a6584 0000.0002 00000009 baadf00d 000126ae 00c4.0130 +0170 0000.000c 00 002 0b0a6584 0000.0010 00000009 baadf00d 00012bc4 022c.0290 +0170 0000.000d 00 003 00000136 0000.001b 00000009 baadf00d 0005ba71 00ec.0310 +0170 0000.000e 00 000 412f241e 0000.0002 00000009 baadf00d 00012f21 02a8.029c +0170 0000.0010 00 003 00000136 0000.0013 00000009 00000003 000341da 0370.0060 +0170 0000.0011 00 006 e60c73e6 0000.001b 00000009 baadf00d 000f1d00 0370.0328 +0170 0000.0017 00 002 0b0a6584 0000.001b 00000009 baadf00d 0006c803 0278.0184 +0170 0000.001a 00 004 00000136 0000.0012 00000001 baadf00d 00038e9b 00ec.0348 +00ec 0000.0006 00 009 00000134 0000.0011 00000009 baadf00d 000b233f 0170.0244 +00ec 0000.000b 00 001 2f5f6520 0000.001c 00000009 baadf00d 00035510 00ec.0334 +00ec 0000.000e 00 001 629b9f66 0000.0014 00000009 baadf00d 00035813 00ec.01c4 +00ec 0000.0012 00 000 629b9f66 0000.0014 00000009 baadf00d 00026cc6 00a8.0164 +00ec 0000.001b 00 001 2f5f6520 0000.0004 00000001 baadf00d 000352c1 00ec.03a8 +02a8 0000.0004 00 009 00000134 0000.0002 00000009 baadf00d 0009a540 0170.0244 +0370 0000.0006 00 003 00000134 0000.0005 0000000b baadf00d 0002e7cd 00ec.0350 +0370 0000.0008 00 009 00000134 0000.0007 0000000b 01cee9e4 000838fa 0170.0244 +0278 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 00072c09 0000.0003 +``` + +For details on the optional parameters, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +For a similar example using the RPC debugger extensions, see [**!rpcexts.getcallinfo**](-rpcexts-getcallinfo.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Get%20RPC%20Call%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/get-rpc-cell-information.md b/windows-driver-docs-pr/debugger/get-rpc-cell-information.md new file mode 100644 index 0000000000..e4278340de --- /dev/null +++ b/windows-driver-docs-pr/debugger/get-rpc-cell-information.md @@ -0,0 +1,46 @@ +--- +title: Get RPC Cell Information +description: Get RPC Cell Information +ms.assetid: 7dd5e77e-914d-4b00-90c5-92705eebf436 +keywords: ["RPC cell information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Get RPC Cell Information + + +## + + +Detailed cell information is displayed by the **!rpcexts.getdbgcell** extension, or by DbgRpc when the **-l** switch is used. + +The process ID of the process that contains the preferred cell must be specified, as well as the cell number. + +In the following example, the process ID is 0x278, and the cell number is 0000.0002: + +``` +D:\wmsg>dbgrpc -l -P 278 -L 0.2 +Getting cell info ... +Thread +Status: Dispatched +Thread ID: 0x1A4 (420) +Last update time (in seconds since boot):470.25 (0x1D6.19) +``` + +For details on the optional parameters, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +For a similar example using the RPC debugger extensions, see [**!rpcexts.getdbgcell**](-rpcexts-getdbgcell.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Get%20RPC%20Cell%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/get-rpc-client-call-information.md b/windows-driver-docs-pr/debugger/get-rpc-client-call-information.md new file mode 100644 index 0000000000..76e978967e --- /dev/null +++ b/windows-driver-docs-pr/debugger/get-rpc-client-call-information.md @@ -0,0 +1,49 @@ +--- +title: Get RPC Client Call Information +description: Get RPC Client Call Information +ms.assetid: 8b23428d-50e7-4613-a0ce-d1da5fa96ddf +keywords: ["RPC client call information", "CCALL (client call)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Get RPC Client Call Information + + +## + + +Client call (CCALL) call information is displayed by the **!rpcexts.getclientcallinfo** extension, or by DbgRpc when the **-a** switch is used. + +Four optional parameters are permitted. Three of these -- *CallID*, *IfStart*, and *ProcNum* -- are identifying information used by RPC to keep track of its calls. The fourth parameter, *ProcessID*, is the PID of the process that owns the call. You should supply whatever parameters you know to narrow down the search. + +If no parameters are supplied, all known CCALLs in the system will be displayed. The following is an example of this (potentially long) display: + +``` +D:\wmsg>dbgrpc -a +Searching for call info ... +## PID CELL ID PNO IFSTART TIDNUMBER CALLID LASTTIME PS CLTNUMBER ENDPOINT +------------------------------------------------------------------------------ +0390 0000.0001 0000 19bb5061 0000.0000 00000001 00072bff 07 0000.0002 1120 +``` + +For details on the optional parameters, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +For a similar example using the RPC debugger extensions, see [**!rpcexts.getclientcallinfo**](-rpcexts-getclientcallinfo.md). + +**Note**   Information about Client Call objects is only gathered if the **Full** state information is being gathered. See [Enabling RPC State Information](enabling-rpc-state-information.md) for details. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Get%20RPC%20Client%20Call%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/get-rpc-endpoint-information.md b/windows-driver-docs-pr/debugger/get-rpc-endpoint-information.md new file mode 100644 index 0000000000..3484830137 --- /dev/null +++ b/windows-driver-docs-pr/debugger/get-rpc-endpoint-information.md @@ -0,0 +1,80 @@ +--- +title: Get RPC Endpoint Information +description: Get RPC Endpoint Information +ms.assetid: 8e852855-896c-4553-8a58-8ca49c7b2e0a +keywords: ["RPC endpoint Information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Get RPC Endpoint Information + + +## + + +Endpoint information is displayed by the **!rpcexts.getendpointinfo** extension, or by DbgRpc when the **-e** switch is used. + +If an endpoint number is specified, information about that endpoint is shown. If it is omitted, the endpoints for all processes on the system are displayed. + +The following example displays all endpoints. This is often a useful way to obtain process IDs and cell numbers that can be used as arguments for additional commands: + +``` +D:\wmsg>dbgrpc -e +Searching for endpoint info ... +## PID CELL ID ST PROTSEQ ENDPOINT +------------------------------------------------------- +00a8 0000.0001 01 NMP \PIPE\InitShutdown +00a8 0000.0003 01 NMP \PIPE\SfcApi +00a8 0000.0004 01 NMP \PIPE\ProfMapApi +00a8 0000.0007 01 NMP \pipe\winlogonrpc +00a8 0000.0008 01 LRPC OLE5 +00c4 0000.0001 01 LRPC ntsvcs +00c4 0000.0003 01 NMP \PIPE\ntsvcs +00c4 0000.0008 01 NMP \PIPE\scerpc +00d0 0000.0001 01 NMP \PIPE\lsass +00d0 0000.0004 01 NMP \pipe\WMIEP_d0 +00d0 0000.000b 01 NMP \PIPE\POLICYAGENT +00d0 0000.000c 01 LRPC policyagent +0170 0000.0001 01 LRPC epmapper +0170 0000.0003 01 TCP 135 +0170 0000.0005 01 SPX 34280 +0170 0000.0006 01 NB 135 +0170 0000.0007 01 NB 135 +0170 0000.000b 01 NMP \pipe\epmapper +01b8 0000.0001 01 NMP \pipe\spoolss +01b8 0000.0003 01 LRPC spoolss +01b8 0000.0007 01 LRPC OLE7 +00ec 0000.0001 01 LRPC OLE2 +00ec 0000.0003 01 LRPC senssvc +00ec 0000.0007 01 NMP \pipe\tapsrv +00ec 0000.0008 01 LRPC tapsrvlpc +00ec 0000.000c 01 NMP \PIPE\ROUTER +00ec 0000.0010 01 NMP \pipe\WMIEP_ec +0214 0000.0001 01 NMP \PIPE\winreg +022c 0000.0001 01 LRPC LRPC0000022c.00000001 +022c 0000.0003 01 TCP 1058 +022c 0000.0005 01 SPX 24576 +022c 0000.0006 01 NMP \PIPE\atsvc +02a8 0000.0001 01 LRPC OLE3 +0370 0000.0001 01 LRPC OLE9 +0278 0000.0001 01 TCP 1120 +030c 0000.0001 01 LRPC OLE12 +``` + +For details on the optional parameters, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +For a similar example using the RPC debugger extensions, see [**!rpcexts.getendpointinfo**](-rpcexts-getendpointinfo.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Get%20RPC%20Endpoint%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/get-rpc-thread-information.md b/windows-driver-docs-pr/debugger/get-rpc-thread-information.md new file mode 100644 index 0000000000..5b72cf3c63 --- /dev/null +++ b/windows-driver-docs-pr/debugger/get-rpc-thread-information.md @@ -0,0 +1,46 @@ +--- +title: Get RPC Thread Information +description: Get RPC Thread Information +ms.assetid: 4cb8d11f-5b0a-4526-9f64-ee69fd15d1ba +keywords: ["RPC thread information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Get RPC Thread Information + + +## + + +Thread information is displayed by the **!rpcexts.getthreadinfo** extension, or by DbgRpc when the **-t** switch is used. + +The PID of a process must be specified. You may specify a thread within that process as well. If the thread is omitted, all threads within that process will be displayed. + +In the following example, the process ID is 0x278 and the thread ID is omitted: + +``` +D:\wmsg>dbgrpc -t -P 278 +Searching for thread info ... +## PID CELL ID ST TID LASTTIME +----------------------------------- +0278 0000.0002 01 000001a4 00072c09 +0278 0000.0005 03 0000031c 00072bf5 +``` + +For details on the optional parameters, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +For a similar example using the RPC debugger extensions, see [**!rpcexts.getthreadinfo**](-rpcexts-getthreadinfo.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Get%20RPC%20Thread%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/getting-set-up-for-debugging.md b/windows-driver-docs-pr/debugger/getting-set-up-for-debugging.md new file mode 100644 index 0000000000..fc2c33bb87 --- /dev/null +++ b/windows-driver-docs-pr/debugger/getting-set-up-for-debugging.md @@ -0,0 +1,42 @@ +--- +title: Setting Up Debugging (Kernel-Mode and User-Mode) +description: There are two ways you can set up debugging with the Windows debuggers. +ms.assetid: 3575B850-A0F9-4AAE-9432-E970D40069D2 +keywords: ["setup debugging", "configure debugging", "configure debugger", "WinDbg", "Visual Studio debugging", "kernel-mode debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Debugging (Kernel-Mode and User-Mode) + + +There are two ways you can set up debugging with the Windows debuggers. You can use Microsoft Visual Studio (integrated with the Windows Driver Kit (WDK)), or you can do the setup manually. After you set up kernel-mode debugging, you can use Visual Studio, WinDbg, or KD to establish a debugging session. After you set up user-mode debugging, you can use Visual Studio, WinDbg, CDB, or NTSD to establish a debugging session. + +**Note**  The Windows debuggers are included in Debugging Tools for Windows. These debuggers are different from the Visual Studio debugger, which is included with Visual Studio. For more information, see [Windows Debugging](index.md). + +  + +## In this section + + +- [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) +- [Supported Ethernet NICs for Network Kernel Debugging in Windows 10](supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md) +- [Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) +- [Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) +- [Setting Up User-Mode Debugging in Visual Studio](setting-up-user-mode-debugging-in-visual-studio.md) +- [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md) +- [Configuring tools.ini](configuring-tools-ini.md) +- [Using KDbgCtrl](using-kdbgctrl.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Debugging%20%28Kernel-Mode%20and%20User-Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/getting-started-with-windbg--kernel-mode-.md b/windows-driver-docs-pr/debugger/getting-started-with-windbg--kernel-mode-.md new file mode 100644 index 0000000000..ab9263e8d4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/getting-started-with-windbg--kernel-mode-.md @@ -0,0 +1,436 @@ +--- +title: Getting Started with WinDbg (Kernel-Mode) +description: This topic provides hands-on exercises that will help you get started using WinDbg as a kernel-mode debugger. +ms.assetid: 1B61591F-0D48-4FBD-B242-68BB90D27FAF +--- + +# Getting Started with WinDbg (Kernel-Mode) + + +WinDbg is a kernel-mode and user-mode debugger that is included in Debugging Tools for Windows. Here we provide hands-on exercises that will help you get started using WinDbg as a kernel-mode debugger. + +For information about how to get Debugging Tools for Windows, see [Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](index.md). After you have installed the debugging tools, locate the installation directories for 64-bit (x64) and 32-bit (x86) versions of the tools. For example: + +- C:\\Program Files (x86)\\Windows Kits\\8.1\\Debuggers\\x64 +- C:\\Program Files (x86)\\Windows Kits\\8.1\\Debuggers\\x86 + +## Set up a kernel-mode debugging + + +A kernel-mode debugging environment typically has two computers: the *host computer* and the *target computer*. The debugger runs on the host computer, and the code being debugged runs on the target computer. The host and target are connected by a debug cable. + +The Windows debuggers support these types of cables for debugging: + +- Ethernet +- USB 2.0 +- USB 3.0 +- 1394 +- Serial (also called null modem) + +If your target computer is running Windows 8 or later, you can use any type of debug cable, including Ethernet. This diagram illustrates a host and target computer connected for debugging over Ethernet cable. + +![diagram of host and target with ethernet connection](images/configfortest01.png) + +If your target computer is running a version of Windows earlier than Window 8, then you cannot use Ethernet for debugging; you must use USB, 1394, or serial. This diagram illustrates a host and target computer connected by a USB, 1394, or serial debug cable. + +![diagram of host and target with debug cable](images/configfortest02.png) + +For details about how to set up the host and target computers, see [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md). + +## Establish a kernel-mode debugging session + + +After you have set up your host and target computer and connected them with a debug cable, you can establish a kernel-mode debugging session by following the instructions in the same topic that you used for getting set up. For example, if you decided to set up your host and target computers for debugging over Ethernet, you can find instructions for establishing a kernel-mode debugging session is this topic: + +- [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) + +Likewise, if you decided to set up your host and target computers for debugging over USB 2.0, you can find instructions for establishing a kernel-mode debugging session is this topic: + +- [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually](setting-up-a-usb-2-0-debug-cable-connection.md) + +## Get started using WinDbg + + +1. On the host computer, open WinDbg and establish a kernel-mode debugging session with the target computer. +2. In WinDbg, choose **Contents** from the **Help** menu. This opens the debugger documentation CHM file. The debugger documentation is also available on line [here](index.md). +3. When you establish a kernel-mode debugging session, WinDbg might break in to the target computer automatically. If WinDbg has not already broken in, choose **Break** from the **Debug** menu. + +4. Near the bottom of the WinDbg window, in the command line, enter this command: + + [**.sympath srv\***](http://go.microsoft.com/fwlink/p?linkid=399238) + + The output is similar to this: + + ``` + Symbol search path is: srv* + Expanded Symbol search path is: cache*;SRV*https://msdl.microsoft.com/download/symbols + ``` + + The symbol search path tells WinDbg where to look for symbol (PDB) files. The debugger needs symbol files to obtain information about code modules (function names, variable names, and the like). + + Enter this command, which tells WinDbg to do its initial finding and loading of symbol files: + + [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) + +5. To see a list of loaded modules, enter this command: + + [**lm**](http://go.microsoft.com/fwlink/p?linkid=399237) + + The output is similar to this: + + ``` + 0:000>3: kd> lm + start end module name + fffff800`00000000 fffff800`00088000 CI (deferred) + ... + fffff800`01143000 fffff800`01151000 BasicRender (deferred) + fffff800`01151000 fffff800`01163000 BasicDisplay (deferred) + ... + fffff800`02a0e000 fffff800`03191000 nt (pdb symbols) C:\...\ntkrnlmp.pdb + fffff800`03191000 fffff800`03200000 hal (deferred) + ... + ``` + +6. To start target computer running, enter this command: + + [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) + +7. To break in again, choose **Break** from the **Debug** menu. + +8. Enter this command to examine the \_FILE\_OBJECT data type in the nt module: + + [**dt nt!\_FILE\_OBJECT**](http://go.microsoft.com/fwlink/p?linkid=399397) + + The output is similar to this: + + ``` + 0:000>0: kd> dt nt!_FILE_OBJECT + +0x000 Type : Int2B + +0x002 Size : Int2B + +0x008 DeviceObject : Ptr64 _DEVICE_OBJECT + +0x010 Vpb : Ptr64 _VPB + ... + +0x0c0 IrpList : _LIST_ENTRY + +0x0d0 FileObjectExtension : Ptr64 Void + ``` + +9. Enter this command to examine some of the symbols in the nt module: + + [**x nt!\*CreateProcess\***](http://go.microsoft.com/fwlink/p?linkid=399240) + + The output is similar to this: + + ``` + 0:000>0: kd> x nt!*CreateProcess* + fffff800`030821cc nt!ViCreateProcessCallbackInternal () + ... + fffff800`02e03904 nt!MmCreateProcessAddressSpace () + fffff800`02cece00 nt!PspCreateProcessNotifyRoutine = + ... + ``` + +10. Enter this command to put a breakpoint at **MmCreateProcessAddressSpace**: + + [**bu nt!MmCreateProcessAddressSpace**](http://go.microsoft.com/fwlink/p?linkid=399390) + + To verify that the breakpoint is set, enter this command: + + [**bl**](http://go.microsoft.com/fwlink/p?linkid=399391) + + The output is similar to this: + + ``` + 0:000>0: kd> bu nt!MmCreateProcessAddressSpace + 0: kd> bl + 0 e fffff800`02e03904 0001 (0001) nt!MmCreateProcessAddressSpace + ``` + + Enter [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) to let the target computer run. + +11. If the target computer doesn't break in to the debugger immediately, perform a few actions on the target computer (for example, open Notepad). The target computer will break in to the debugger when **MmCreateProcessAddressSpace** is called. To see the stack trace, enter these commands: + + [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) + + [**k**](http://go.microsoft.com/fwlink/p?linkid=399389) + + The output is similar to this: + + ``` + 0:000>2: kd> k + Child-SP RetAddr Call Site + ffffd000`224b4c88 fffff800`02d96834 nt!MmCreateProcessAddressSpace + ffffd000`224b4c90 fffff800`02dfef17 nt!PspAllocateProcess+0x5d4 + ffffd000`224b5060 fffff800`02b698b3 nt!NtCreateUserProcess+0x55b + ... + 000000d7`4167fbb0 00007ffd`14b064ad KERNEL32!BaseThreadInitThunk+0xd + 000000d7`4167fbe0 00000000`00000000 ntdll!RtlUserThreadStart+0x1d + ``` + +12. On the **View** menu, choose **Disassembly**. + + On the **Debug** menu, choose **Step Over** (or press **F10**). Enter step commands a few more times as you watch the Disassembly window. + +13. Clear your breakpoint by entering this command: + + [**bc \***](http://go.microsoft.com/fwlink/p?linkid=399401) + + Enter [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) to let the target computer run. Break in again by choosing **Break** from the **Debug** menu or pressing **CTRL-Break**. + +14. To see a list of all processes, enter this command: + + [**!process 0 0**](http://go.microsoft.com/fwlink/p?linkid=399241) + + The output is similar to this: + + ``` + 0:000>0: kd> !process 0 0 + **** NT ACTIVE PROCESS DUMP **** + PROCESS ffffe000002287c0 + SessionId: none Cid: 0004 Peb: 00000000 ParentCid: 0000 + DirBase: 001aa000 ObjectTable: ffffc00000003000 HandleCount: + Image: System + + PROCESS ffffe00001e5a900 + SessionId: none Cid: 0124 Peb: 7ff7809df000 ParentCid: 0004 + DirBase: 100595000 ObjectTable: ffffc000002c5680 HandleCount: + Image: smss.exe + ... + PROCESS ffffe00000d52900 + SessionId: 1 Cid: 0910 Peb: 7ff669b8e000 ParentCid: 0a98 + DirBase: 3fdba000 ObjectTable: ffffc00007bfd540 HandleCount: + Image: explorer.exe + ``` + +15. Copy the address of one process, and enter this command: + + [**!process** *Address* **2**](http://go.microsoft.com/fwlink/p?linkid=399241) + + For example: **!process ffffe00000d5290 2** + + The output shows the threads in the process. + + ``` + 0:000>0:000>0: kd> !process ffffe00000d52900 2 + PROCESS ffffe00000d52900 + SessionId: 1 Cid: 0910 Peb: 7ff669b8e000 ParentCid: 0a98 + DirBase: 3fdba000 ObjectTable: ffffc00007bfd540 HandleCount: + Image: explorer.exe + + THREAD ffffe00000a0d880 Cid 0910.090c Teb: 00007ff669b8c000 + ffffe00000d57700 SynchronizationEvent + + THREAD ffffe00000e48880 Cid 0910.0ad8 Teb: 00007ff669b8a000 + ffffe00000d8e230 NotificationEvent + ffffe00000cf6870 Semaphore Limit 0xffff + ffffe000039c48c0 SynchronizationEvent + ... + THREAD ffffe00000e6d080 Cid 0910.0cc0 Teb: 00007ff669a10000 + ffffe0000089a300 QueueObject + ``` + +16. Copy the address of one thread, and enter this command: + + [**!thread** *Address*](http://go.microsoft.com/fwlink/p?linkid=399244) + + For example: **!thread ffffe00000e6d080** + + The output shows information about the individual thread. + + ``` + 0: kd> !thread ffffe00000e6d080 + THREAD ffffe00000e6d080 Cid 0910.0cc0 Teb: 00007ff669a10000 Win32Thread: 0000000000000000 WAIT: ... + ffffe0000089a300 QueueObject + Not impersonating + DeviceMap ffffc000034e7840 + Owning Process ffffe00000d52900 Image: explorer.exe + Attached Process N/A Image: N/A + Wait Start TickCount 13777 Ticks: 2 (0:00:00:00.031) + Context Switch Count 2 IdealProcessor: 1 + UserTime 00:00:00.000 + KernelTime 00:00:00.000 + Win32 Start Address ntdll!TppWorkerThread (0x00007ffd14ab2850) + Stack Init ffffd00021bf1dd0 Current ffffd00021bf1580 + Base ffffd00021bf2000 Limit ffffd00021bec000 Call 0 + Priority 13 BasePriority 13 UnusualBoost 0 ForegroundBoost 0 IoPriority 2 PagePriority 5 + ... + ``` + +17. To see all the device nodes in the Plug and Play device tree, enter this command: + + [**!devnode 0 1**](http://go.microsoft.com/fwlink/p?linkid=399242) + + ``` + 0:000>0: kd> !devnode 0 1 + Dumping IopRootDeviceNode (= 0xffffe000002dbd30) + DevNode 0xffffe000002dbd30 for PDO 0xffffe000002dc9e0 + InstancePath is "HTREE\ROOT\0" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe000002d9d30 for PDO 0xffffe000002daa40 + InstancePath is "ROOT\volmgr\0000" + ServiceName is "volmgr" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + DevNode 0xffffe00001d49290 for PDO 0xffffe000002a9a90 + InstancePath is "STORAGE\Volume\{3007dfd3-df8d-11e3-824c-806e6f6e6963}#0000000000100000" + ServiceName is "volsnap" + TargetDeviceNotify List - f 0xffffc0000031b520 b 0xffffc0000008d0f0 + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeStartPostWork (0x307) + ... + ``` + +18. To see the device nodes along with their hardware resources, enter this command: + + [**!devnode 0 9**](http://go.microsoft.com/fwlink/p?linkid=399242) + + ``` + 0:000>... + DevNode 0xffffe000010fa770 for PDO 0xffffe000010c2060 + InstancePath is "PCI\VEN_8086&DEV_2937&SUBSYS_2819103C&REV_02\3&33fd14ca&0&D0" + ServiceName is "usbuhci" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + TranslatedResourceList at 0xffffc00003c78b00 Version 1.1 Interface 0x5 Bus #0 + Entry 0 - Port (0x1) Device Exclusive (0x1) + Flags (0x131) - PORT_MEMORY PORT_IO 16_BIT_DECODE POSITIVE_DECODE + Range starts at 0x3120 for 0x20 bytes + Entry 1 - DevicePrivate (0x81) Device Exclusive (0x1) + Flags (0000) - + Data - {0x00000001, 0x00000004, 0000000000} + Entry 2 - Interrupt (0x2) Shared (0x3) + Flags (0000) - LEVEL_SENSITIVE + Level 0x8, Vector 0x81, Group 0, Affinity 0xf + ... + ``` + +19. To see a device node that has a service name of disk, enter this command: + + [**!devnode 0 1 disk**](http://go.microsoft.com/fwlink/p?linkid=399242) + + ``` + 0: kd> !devnode 0 1 disk + Dumping IopRootDeviceNode (= 0xffffe000002dbd30) + DevNode 0xffffe0000114fd30 for PDO 0xffffe00001159610 + InstancePath is "IDE\DiskST3250820AS_____________________________3.CHL___\5&14544e82&0&0.0.0" + ServiceName is "disk" + State = DeviceNodeStarted (0x308) + Previous State = DeviceNodeEnumerateCompletion (0x30d) + ... + ``` + +20. The output of [**!devnode 0 1**](http://go.microsoft.com/fwlink/p?linkid=399242) displays the address of the physical device object (PDO) for the node. Copy the address of a physical device object (PDO), and enter this command: + + [**!devstack** *PdoAddress*](http://go.microsoft.com/fwlink/p?linkid=399245) + + For example: *PdoAddress***!devstack 0xffffe00001159610** + + ``` + 0:000>0: kd> !devstack 0xffffe00001159610 + !DevObj !DrvObj !DevExt ObjectName + ffffe00001d50040 \Driver\partmgr ffffe00001d50190 + ffffe00001d51450 \Driver\disk ffffe00001d515a0 DR0 + ffffe00001156e50 \Driver\ACPI ffffe000010d8bf0 + ``` + +21. To get information about the driver disk.sys, enter this command: + + [**!drvobj disk 2**](http://go.microsoft.com/fwlink/p?linkid=399246) + + ``` + 0:000>0: kd> !drvobj disk 2 + Driver object (ffffe00001d52680) is for: + \Driver\disk + DriverEntry: fffff800006b1270 disk!GsDriverEntry + DriverStartIo: 00000000 + DriverUnload: fffff800010b0b5c CLASSPNP!ClassUnload + AddDevice: fffff800010aa110 CLASSPNP!ClassAddDevice + + Dispatch routines: + [00] IRP_MJ_CREATE fffff8000106d160 CLASSPNP!ClassGlobalDispatch + [01] IRP_MJ_CREATE_NAMED_PIPE fffff80002b0ab24 nt!IopInvalidDeviceRequest + [02] IRP_MJ_CLOSE fffff8000106d160 CLASSPNP!ClassGlobalDispatch + [03] IRP_MJ_READ fffff8000106d160 CLASSPNP!ClassGlobalDispatch + ... + [1b] IRP_MJ_PNP fffff8000106d160 CLASSPNP!ClassGlobalDispatch + ``` + +22. The output of !drvobj displays addresses of dispatch routines: for example, CLASSPNP!ClassGlobalDispatch. To set and verify a breakpoint at ClassGlobalDispatch, enter these commands: + + [**bu CLASSPNP!ClassGlobalDispatch**](http://go.microsoft.com/fwlink/p?linkid=399390) + + [**bl**](http://go.microsoft.com/fwlink/p?linkid=399391) + + Enter g to let the target computer run. + + If the target computer doesn't break in to the debugger immediately, perform a few actions on the target computer (for example, open Notepad and save a file). The target computer will break in to the debugger when **ClassGlobalDispatch** is called. To see the stack trace, enter these commands: + + [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) + + [**k**](http://go.microsoft.com/fwlink/p?linkid=399389) + + The output is similar to this: + + ``` + 2: kd> k + Child-SP RetAddr Call Site + ffffd000`21d06cf8 fffff800`0056c14e CLASSPNP!ClassGlobalDispatch + ffffd000`21d06d00 fffff800`00f2c31d volmgr!VmReadWrite+0x13e + ffffd000`21d06d40 fffff800`0064515d fvevol!FveFilterRundownReadWrite+0x28d + ffffd000`21d06e20 fffff800`0064578b rdyboost!SmdProcessReadWrite+0x14d + ffffd000`21d06ef0 fffff800`00fb06ad rdyboost!SmdDispatchReadWrite+0x8b + ffffd000`21d06f20 fffff800`0085cef5 volsnap!VolSnapReadFilter+0x5d + ffffd000`21d06f50 fffff800`02b619f7 Ntfs!NtfsStorageDriverCallout+0x16 + ... + ``` + +23. To end your debugging session, enter this command: + + [**qd**](http://go.microsoft.com/fwlink/p?linkid=399394) + +## Summary of commands + + +- **Contents** command on the **Help** menu +- [.sympath (Set Symbol Path)](http://go.microsoft.com/fwlink/p?linkid=399238) +- [.reload (Reload Module)](http://go.microsoft.com/fwlink/p?linkid=399239) +- [x (Examine Symbols)](http://go.microsoft.com/fwlink/p?linkid=399240) +- [g (Go)](http://go.microsoft.com/fwlink/p?linkid=399388) +- [dt (Display Type)](http://go.microsoft.com/fwlink/p?linkid=399397) +- **Break** command on the **Debug** menu +- [lm (List Loaded Modules)](http://go.microsoft.com/fwlink/p?linkid=399237) +- [k (Display Stack Backtrace)](http://go.microsoft.com/fwlink/p?linkid=399389) +- [bu (Set Breakpoint)](http://go.microsoft.com/fwlink/p?linkid=399390) +- [bl (Breakpoint List)](http://go.microsoft.com/fwlink/p?linkid=399391) +- [bc (Breakpoint Clear)](http://go.microsoft.com/fwlink/p?linkid=399401) +- **Step Into** command on the **Debug** menu (**F11**) +- [!process](http://go.microsoft.com/fwlink/p?linkid=399241) +- [!thread](http://go.microsoft.com/fwlink/p?linkid=399244) +- [!devnode](http://go.microsoft.com/fwlink/p?linkid=399242) +- [!devstack](http://go.microsoft.com/fwlink/p?linkid=399245) +- [!drvobj](http://go.microsoft.com/fwlink/p?linkid=399246) +- [qd (Quit and Detach)](http://go.microsoft.com/fwlink/p?linkid=399394) + +## Related topics + + +[Getting Started with WinDbg (User-Mode)](getting-started-with-windbg.md) + +[Setting Up Kernel-Mode Debugging Manually](http://go.microsoft.com/fwlink/p?linkid=272138) + +[Debugger Operation](http://go.microsoft.com/fwlink/p?linkid=399247) + +[Debugging Techniques](http://go.microsoft.com/fwlink/p?linkid=399248) + +[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](http://go.microsoft.com/fwlink/p?linkid=223405) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Getting%20Started%20with%20WinDbg%20%28Kernel-Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/getting-started-with-windbg.md b/windows-driver-docs-pr/debugger/getting-started-with-windbg.md new file mode 100644 index 0000000000..84a676d6a4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/getting-started-with-windbg.md @@ -0,0 +1,355 @@ +--- +title: Getting Started with WinDbg (User-Mode) +description: WinDbg is a kernel-mode and user-mode debugger that is included in Debugging Tools for Windows. Here we provide hands-on exercises that will help you get started using WinDbg as a user-mode debugger. +ms.assetid: 8C2D2D0C-7E54-4711-A6FD-970E040F1C50 +--- + +# Getting Started with WinDbg (User-Mode) + + +WinDbg is a kernel-mode and user-mode debugger that is included in Debugging Tools for Windows. Here we provide hands-on exercises that will help you get started using WinDbg as a user-mode debugger. + +For information about how to get Debugging Tools for Windows, see [Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](http://go.microsoft.com/fwlink/p?linkid=223405). After you have installed the debugging tools, locate the installation directories for 64-bit (x64) and 32-bit (x86) versions of the tools. For example: + +- C:\\Program Files (x86)\\Windows Kits\\8.1\\Debuggers\\x64 +- C:\\Program Files (x86)\\Windows Kits\\8.1\\Debuggers\\x86 + +## Launch Notepad and attach WinDbg + + +1. Navigate to your installation directory, and open WinDbg.exe. + +2. On the **Help** menu, choose **Contents**. This opens the debugger documentation CHM file. The debugger documentation is also available on line [here](http://go.microsoft.com/fwlink/p?linkid=223405). +3. On the **File** menu, choose **Open Executable**. In the Open Executable dialog box, navigate to the folder that contains notepad.exe (for example, C:\\Windows\\System32). For **File name**, enter notepad.exe. Click **Open**. + + ![screen shot of windbg after starting notepad](images/windbggetstart01.png) + +4. Near the bottom of the WinDbg window, in the command line, enter this command: + + [**.sympath srv\***](http://go.microsoft.com/fwlink/p?linkid=399238). + + The output is similar to this: + + ``` + Symbol search path is: srv* + Expanded Symbol search path is: cache*;SRV*https://msdl.microsoft.com/download/symbols + ``` + + The symbol search path tells WinDbg where to look for symbol (PDB) files. The debugger needs symbol files to obtain information about code modules (function names, variable names, and the like). + + Enter this command, which tells WinDbg to do its initial finding and loading of symbol files: + + [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) + +5. To see the symbols for the Notepad.exe module, enter this command: + + [**x notepad!\***](http://go.microsoft.com/fwlink/p?linkid=399240) + + **Note**  If you don't see any output, enter [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) again. + +   + + To see symbols in the Notepad.exe module that contain main, enter this command: + + **x notepad!\*main\*** + + The output is similar to this: + + ``` + 000000d0`428ff7e8 00007ff6`3282122f notepad!WinMain + ... + ``` + +6. To put a breakpoint at notepad!WinMain, enter this command: + + [**bu notepad!WinMain**](http://go.microsoft.com/fwlink/p?linkid=399390) + + To verify that your breakpoint was set, enter this command: + + [**bl**](http://go.microsoft.com/fwlink/p?linkid=399391) + + The output is similar to this: + + ``` + 0 e 00007ff6`32825f64 0001 (0001) 0:**** notepad!WinMain + ``` + +7. To start Notepad running, enter this command: + + [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) + + Notepad runs until it comes to the **WinMain** function, and then breaks in to the debugger. + + To see a list of code modules that are loaded in the Notepad process, enter this command: + + [**lm**](http://go.microsoft.com/fwlink/p?linkid=399237) + + The output is similar to this: + + ``` + 0:000> lm + start end module name + 00007ff6`32820000 00007ff6`3285a000 notepad (pdb symbols) C:\...\notepad.pdb + 00007ffc`ab7e0000 00007ffc`ab85b000 WINSPOOL (deferred) + 00007ffc`aba10000 00007ffc`abc6a000 COMCTL32 (deferred) + 00007ffc`adea0000 00007ffc`adf3f000 SHCORE (deferred) + 00007ffc`af490000 00007ffc`af59f000 KERNELBASE (deferred) + 00007ffc`af7d0000 00007ffc`af877000 msvcrt (deferred) + 00007ffc`af880000 00007ffc`b0c96000 SHELL32 (deferred) + 00007ffc`b0e40000 00007ffc`b0ef7000 OLEAUT32 (deferred) + 00007ffc`b0f00000 00007ffc`b0f57000 sechost (deferred) + 00007ffc`b0f60000 00007ffc`b1005000 ADVAPI32 (deferred) + 00007ffc`b1010000 00007ffc`b1155000 GDI32 (deferred) + 00007ffc`b1160000 00007ffc`b1296000 RPCRT4 (deferred) + 00007ffc`b12a0000 00007ffc`b1411000 USER32 (deferred) + 00007ffc`b1420000 00007ffc`b15f6000 combase (deferred) + 00007ffc`b16c0000 00007ffc`b17f9000 MSCTF (deferred) + 00007ffc`b1800000 00007ffc`b189a000 COMDLG32 (deferred) + 00007ffc`b18a0000 00007ffc`b18f1000 SHLWAPI (deferred) + 00007ffc`b1b60000 00007ffc`b1cd8000 ole32 (deferred) + 00007ffc`b1cf0000 00007ffc`b1e2a000 KERNEL32 (pdb symbols) C:\...\kernel32.pdb + 00007ffc`b1eb0000 00007ffc`b1ee4000 IMM32 (deferred) + 00007ffc`b1f50000 00007ffc`b20fa000 ntdll (private pdb symbols) C:\...\ntdll.pdb + ``` + + To see a stack trace, enter this command: + + [**k**](http://go.microsoft.com/fwlink/p?linkid=399389) + + The output is similar to this: + + ``` + Breakpoint 0 hit + notepad!WinMain: + 00007ff6`32825f64 488bc4 mov rax,rsp + 0:000> k + Child-SP RetAddr Call Site + 00000048`4e0cf6a8 00007ff6`3282122f notepad!WinMain + 00000048`4e0cf6b0 00007ffc`b1cf16ad notepad!WinMainCRTStartup+0x1a7 + 00000048`4e0cf770 00007ffc`b1fc4629 KERNEL32!BaseThreadInitThunk+0xd + 00000048`4e0cf7a0 00000000`00000000 ntdll!RtlUserThreadStart+0x1d ... + ``` + +8. To start Notepad running again, enter this command: + + [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) + +9. To break in to Notepad, choose **Break** from the **Debug** menu. + +10. To set and verify a breakpoint at **ZwWriteFile**, enter these commands: + + [**bu ntdll!ZwWriteFile**](http://go.microsoft.com/fwlink/p?linkid=399390) + + [**bl**](http://go.microsoft.com/fwlink/p?linkid=399391) + +11. Enter [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) to start Notepad running again. In the Notepad window, enter some text and choose **Save** from the **File** menu. The running code breaks in when it comes to **ZwCreateFile**. Enter [**k**](http://go.microsoft.com/fwlink/p?linkid=399389) to see the stack trace. + + ![screen shot of stack trace in windbg](images/windbggetstart02.png) + + In the WinDbg window, just to the left of the command line, notice the processor and thread numbers. In this example the current processor number is 0, and the current thread number is 11. So we are looking at the stack trace for thread 11 (which happens to be running on processor 0). + +12. To see a list of all threads in the Notepad process, enter this command (the tilde): + + [**~**](http://go.microsoft.com/fwlink/p?linkid=399392) + + The output is similar to this: + + ``` + 0:011> ~ + 0 Id: 10c8.128c Suspend: 1 Teb: 00007ff6`31cdd000 Unfrozen + 1 Id: 10c8.1a10 Suspend: 1 Teb: 00007ff6`31cdb000 Unfrozen + 2 Id: 10c8.1850 Suspend: 1 Teb: 00007ff6`31cd9000 Unfrozen + 3 Id: 10c8.1774 Suspend: 1 Teb: 00007ff6`31cd7000 Unfrozen + 4 Id: 10c8.1e80 Suspend: 1 Teb: 00007ff6`31cd5000 Unfrozen + 5 Id: 10c8.10ac Suspend: 1 Teb: 00007ff6`31cd3000 Unfrozen + 6 Id: 10c8.13a4 Suspend: 1 Teb: 00007ff6`31bae000 Unfrozen + 7 Id: 10c8.2b4 Suspend: 1 Teb: 00007ff6`31bac000 Unfrozen + 8 Id: 10c8.1df0 Suspend: 1 Teb: 00007ff6`31baa000 Unfrozen + 9 Id: 10c8.1664 Suspend: 1 Teb: 00007ff6`31ba8000 Unfrozen + 10 Id: 10c8.15e4 Suspend: 1 Teb: 00007ff6`31ba6000 Unfrozen + . 11 Id: 10c8.8bc Suspend: 1 Teb: 00007ff6`31ba4000 Unfrozen + ``` + + In this example, there are 12 threads with indexes 0 through 11. + +13. To look at the stack trace for thread 0, enter these commands: + + [**~0s**](http://go.microsoft.com/fwlink/p?linkid=399393) + + [**k**](http://go.microsoft.com/fwlink/p?linkid=399389) + + The output is similar to this: + + ``` + 0:011> ~0s + USER32!SystemParametersInfoW: + 00007ffc`b12a4d20 48895c2408 mov qword ptr [rsp+8], ... + 0:000> k + Child-SP RetAddr Call Site + 00000033`d1e9da48 00007ffc`adfb227d USER32!SystemParametersInfoW + (Inline Function) --------`-------- uxtheme!IsHighContrastMode+0x1d + 00000033`d1e9da50 00007ffc`adfb2f12 uxtheme!IsThemeActive+0x4d + ... + 00000033`d1e9f810 00007ffc`b1cf16ad notepad!WinMainCRTStartup+0x1a7 + 00000033`d1e9f8d0 00007ffc`b1fc4629 KERNEL32!BaseThreadInitThunk+0xd + 00000033`d1e9f900 00000000`00000000 ntdll!RtlUserThreadStart+0x1d + ``` + +14. To quit debugging and detach from the Notepad process, enter this command: + + [**qd**](http://go.microsoft.com/fwlink/p?linkid=399394) + +## Launch your own application and attach WinDbg + + +Suppose you have written and built this small console application. + +``` +... +void MyFunction(long p1, long p2, long p3) +{ + long x = p1 + p2 + p3; + long y = 0; + y = x / p2; +} + +void main () +{ + long a = 2; + long b = 0; + MyFunction(a, b, 5); +} +``` + +For this exercise, we will assume that the built application (MyApp.exe) and the symbol file (MyApp.pdb) are in C:\\MyApp\\x64\\Debug. We will also assume that the application source code is in C:\\MyApp\\MyApp. + +1. Open WinDbg. + +2. On the **File** menu, choose **Open Executable**. In the Open Executable dialog box, navigate to C:\\MyApp\\x64\\Debug. For **File name**, enter MyApp.exe. Click **Open**. +3. Enter these commands: + + [**.sympath srv\***](http://go.microsoft.com/fwlink/p?linkid=399238) + + **.sympath+ C:\\MyApp\\x64\\Debug** + + [**.srcpath C:\\MyApp\\MyApp**](http://go.microsoft.com/fwlink/p?linkid=399395) + + Now WinDbg knows where to find symbols and source code for your application. + +4. Enter these commands: + + [**.reload**](http://go.microsoft.com/fwlink/p?linkid=399239) + + [**bu MyApp!main**](http://go.microsoft.com/fwlink/p?linkid=399390) + + [**g**](http://go.microsoft.com/fwlink/p?linkid=399388) + + Your application breaks in to the debugger when it comes to its **main** function. + + WinDbg displays your source code and the Command window. + + ![screen shot of source code in windbg](images/windbggetstart03.png) + +5. On the **Debug** menu, choose **Step Into** (or press **F11**). Continue stepping until you have stepped into **MyFunction**. When you step into the line `y = x / p2`, your application will crash and break in to the debugger. The output is similar to this: + + ``` + (1450.1424): Integer divide-by-zero - code c0000094 (first chance) + First chance exceptions are reported before any exception handling. + This exception may be expected and handled. + MyApp!MyFunction+0x44: + 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] ss:00000063`2036f808=00000000 + ``` + +6. Enter this command: + + [**!analyze -v**](http://go.microsoft.com/fwlink/p?linkid=399396) + + WinDbg displays an analysis of the problem (division by 0 in this case). + + ``` + FAULTING_IP: + MyApp!MyFunction+44 [c:\myapp\myapp\myapp.cpp @ 7] + 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] + + EXCEPTION_RECORD: ffffffffffffffff -- (.exr 0xffffffffffffffff) + ExceptionAddress: 00007ff63be11064 (MyApp!MyFunction+0x0000000000000044) + ExceptionCode: c0000094 (Integer divide-by-zero) + ExceptionFlags: 00000000 + NumberParameters: 0 + ... + STACK_TEXT: + 00000063`2036f7e0 00007ff6`3be110b8 : ... : MyApp!MyFunction+0x44 + 00000063`2036f800 00007ff6`3be1141d : ... : MyApp!main+0x38 + 00000063`2036f840 00007ff6`3be1154e : ... : MyApp!__tmainCRTStartup+0x19d + 00000063`2036f8b0 00007ffc`b1cf16ad : ... : MyApp!mainCRTStartup+0xe + 00000063`2036f8e0 00007ffc`b1fc4629 : ... : KERNEL32!BaseThreadInitThunk+0xd + 00000063`2036f910 00000000`00000000 : ... : ntdll!RtlUserThreadStart+0x1d + + STACK_COMMAND: dt ntdll!LdrpLastDllInitializer BaseDllName ;dt ntdll!LdrpFailureData ;.cxr 0x0 ;kb + + FOLLOWUP_IP: + MyApp!MyFunction+44 [c:\myapp\myapp\myapp.cpp @ 7] + 00007ff6`3be11064 f77c2428 idiv eax,dword ptr [rsp+28h] + + FAULTING_SOURCE_LINE: c:\myapp\myapp\myapp.cpp + + FAULTING_SOURCE_FILE: c:\myapp\myapp\myapp.cpp + + FAULTING_SOURCE_LINE_NUMBER: 7 + + FAULTING_SOURCE_CODE: + 3: void MyFunction(long p1, long p2, long p3) + 4: { + 5: long x = p1 + p2 + p3; + 6: long y = 0; + > 7: y = x / p2; + 8: } + 9: + 10: void main () + 11: { + 12: long a = 2; + ... + ``` + +## Summary of commands + + +- **Contents** command on the **Help** menu +- [.sympath (Set Symbol Path)](http://go.microsoft.com/fwlink/p?linkid=399238) +- [.reload (Reload Module)](http://go.microsoft.com/fwlink/p?linkid=399239) +- [x (Examine Symbols)](http://go.microsoft.com/fwlink/p?linkid=399240) +- [g (Go)](http://go.microsoft.com/fwlink/p?linkid=399388) +- **Break** command on the **Debug** menu +- [lm (List Loaded Modules)](http://go.microsoft.com/fwlink/p?linkid=399237) +- [k (Display Stack Backtrace)](http://go.microsoft.com/fwlink/p?linkid=399389) +- [bu (Set Breakpoint)](http://go.microsoft.com/fwlink/p?linkid=399390) +- [bl (Breakpoint List)](http://go.microsoft.com/fwlink/p?linkid=399390) +- [~ (Thread Status)](http://go.microsoft.com/fwlink/p?linkid=399392) +- [~s (Set Current Thread)](http://go.microsoft.com/fwlink/p?linkid=399393) +- [.sympath+ (Set Symbol Path) append to existing symbol path](http://go.microsoft.com/fwlink/p?linkid=399238) +- [.srcpath (Set Source Path)](http://go.microsoft.com/fwlink/p?linkid=399395) +- **Step Into** command on the **Debug** menu (**F11**) +- [!analyze -v](http://go.microsoft.com/fwlink/p?linkid=399396) +- [qd (Quit and Detach)](http://go.microsoft.com/fwlink/p?linkid=399394) + +## Related topics + + +[Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md) + +[Debugger Operation](http://go.microsoft.com/fwlink/p?linkid=399247) + +[Debugging Techniques](http://go.microsoft.com/fwlink/p?linkid=399248) + +[Debugging Tools for Windows (WinDbg, KD, CDB, NTSD)](http://go.microsoft.com/fwlink/p?linkid=223405) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Getting%20Started%20with%20WinDbg%20%28User-Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/getting-started-with-windows-debugging.md b/windows-driver-docs-pr/debugger/getting-started-with-windows-debugging.md new file mode 100644 index 0000000000..8afa382d91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/getting-started-with-windows-debugging.md @@ -0,0 +1,94 @@ +--- +title: Getting Started with Windows Debugging +description: This section covers how to get started with Windows Debugging. If your goal is to use the debugger to analyze a crash dump, see Crash dump analysis using the Windows debuggers (WinDbg). +ms.assetid: 4981928E-A33D-4F60-AAA0-124C360B7E03 +--- + +# Getting Started with Windows Debugging + + +This section covers how to get started with Windows Debugging. If your goal is to use the debugger to analyze a crash dump, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md). + +To get started with Windows Debugging, complete the following tasks. + +1. Determine which devices will serve as the host system and the target system. +The debugger runs on the host system and the code that you want to debug runs on the target system. + +**Host <--------------------------------------------------> Target** + +![host and target pcs connected with a double arrow](images/targethost1.png) + +Because it is common to stop instruction execution on the processor during debugging, typically, two systems are used. In some situations, it is possible that the second system is a virtual system, for example, a virtual PC that is running on the same PC. However, if your code is communicating to low level hardware, using a virtual PC may not be the best approach. For more information, see [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md). + +2. Determine if you will be doing kernel or user mode debugging. +*Kernel mode* - Kernel mode is the processor access mode in which the operating system and privileged programs run. Kernel mode code has permission to access any part of the system, and is not restricted like user mode code. It can gain access to any part of any other process running in either user mode or kernel mode. Much of the core OS functionality and many hardware device drivers run in kernel mode. + +*User mode* - Applications and subsystems run on the computer in user mode. Processes that run in user mode do so within their own virtual address spaces. They are restricted from gaining direct access to many parts of the system, including system hardware, memory that was not allocated for their use, and other portions of the system that might compromise system integrity. Because processes that run in user mode are effectively isolated from the system and other user mode processes, they cannot interfere with these resources. + +If your goal is to debug a driver, determine if the driver is a kernel mode driver (typically described as a WDM or KMDF driver) or a user mode driver (UMDF). + +For some issues, it can be difficult to determine which mode the code is executing in. In that case, you may need to pick one mode and look to see what information is available in that mode. Some issues require using the debugger in both user and kernel mode. + +Depending on what mode you decide to debug in, you will need to configure and use the debuggers in different ways. Some debug commands operate the same, and some commands operate differently in different modes. + +For information about using the debugger in kernel mode, see [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md) and [Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md) and [Debug Drivers - Step by Step Lab (Sysvad Kernel-Mode)](debug-universal-drivers--kernel-mode-.md). For information about using the debugger in user mode, see [Getting Started with WinDbg (User-Mode)](getting-started-with-windbg.md). + +3. Chose your debugger environment. +WinDbg works well in most situations, but there are times when you may want to use another debugger such as console debuggers for automation or even Visual Studio. For more information, see [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md). + +4. Determine how you will connect the target and host system. +Typically, an Ethernet network connection is used to connect the target and host system. If you are doing early bring up work, or don't have an Ethernet connection on the device, other network connection options are available. For more information, see these topics: + +- [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) +- [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) +- [Setting Up Kernel-Mode Debugging using Serial over USB Manually](setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md) +- [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md) + +If you wish to debug using Visual Studio, then refer to these topics. + +- [Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio](setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio](setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md) +- [Setting Up User-Mode Debugging in Visual Studio](setting-up-user-mode-debugging-in-visual-studio.md) + +5. Choose either the 32-bit or 64-bit debugging tools. +This choice is dependent on the version of Windows that is running on the target and host systems and whether you are debugging 32-bit or 64-bit code. For more information, see [Choosing the 32-Bit or 64-Bit Debugging Tools](choosing-a-32-bit-or-64-bit-debugger-package.md). + +6. Configure symbols. +You must load the proper symbols to use all of the advanced functionality that WinDbg provides. If you do not have symbols properly configured, you will receive messages indicating that symbols are not available when you attempt to use functionality that is dependent on symbols. For more information, see [Symbols for Windows debugging (WinDbg, KD, CDB, NTSD)](symbols.md). + +7. Configure source code. +If your goal is to debug your own source code, you will need to configure a path to your source code. For more information, see [Source Path](source-path.md). + +8. Become familiar with debugger operation. +The [Debugger Operation](debugger-operation-win8.md) section of the documentation describes debugger operation for various tasks. For example, the [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) topic explains how to load debugger extensions. To learn more about working with WinDbg, see [Debugging Using WinDbg](debugging-using-windbg.md). + +9. Become familiar with debugging techniques. +[Standard Debugging Techniques](standard-debugging-techniques.md) apply to most debugging scenarios, and examples include setting breakpoints, inspecting the call stack, and finding a memory leak. [Specialized Debugging Techniques](specialized-debugging-techniques.md) apply to particular technologies or types of code. Examples are Plug and Play debugging, Kernel Mode Driver Framework debugging, and RPC debugging. + +10. Use the debugger reference commands. +Over time, you will use different debug commands as you work in the debugger. Use the [.hh (Open HTML Help File)](-hh--open-html-help-file-.md) command in the debugger to display help information about any debug command. For more information about the available commands, see [Debugger Reference](debugger-reference.md). + +11. Use debugging extensions for specific technologies. +There are a number of debugging extensions that provide parsing of domain specific data structures. For more information, see [Specialized Extensions](specialized-extensions.md). + +This section contains the following topics. + +- [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md) +- [Getting Started with WinDbg (User-Mode)](getting-started-with-windbg.md) +- [Choosing the 32-Bit or 64-Bit Debugging Tools](choosing-a-32-bit-or-64-bit-debugger-package.md) +- [Debugging Environments](debuggers-in-the-debugging-tools-for-windows-package.md) +- [Setting Up Debugging (Kernel-Mode and User-Mode)](getting-set-up-for-debugging.md) +- [Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md) +- [Debug Drivers - Step by Step Lab (Sysvad Kernel-Mode)](debug-universal-drivers--kernel-mode-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Getting%20Started%20with%20Windows%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-and-pageheap.md b/windows-driver-docs-pr/debugger/gflags-and-pageheap.md new file mode 100644 index 0000000000..beb719c471 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-and-pageheap.md @@ -0,0 +1,43 @@ +--- +title: GFlags and PageHeap +description: GFlags and PageHeap +ms.assetid: 9ced92d9-b37c-4db5-b3f9-fa2fe5325e57 +keywords: ["GFlags, GFlags and PageHeap", "PageHeap (pageheap.exe)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags and PageHeap + + +## + + +This version of GFlags includes the functionality of PageHeap (pageheap.exe), a tool that enables heap allocation monitoring in Windows. PageHeap enables Windows features that reserve memory at the boundary of each allocation to detect attempts to access memory beyond the allocation. + +The page heap options in GFlags let you select *standard heap verification*, which writes fill patterns at the end of each heap allocation and examines the patterns when the allocations are freed, or *full-page heap verification*, which places an inaccessible page at the end of each allocation so that the program stops immediately if if accesses memory beyond the allocation. Because full heap verification uses a full page of memory for each allocation, its widespread use can cause system memory shortages. + +- To enable standard page heap verification for all processes, use **gflags /r +hpa** or **gflags /k +hpa**. + +- To enable standard page heap verification for one process, use **gflags /p /enable** *ImageFileName*. + +- To enable full page heap verification for one process, use **gflags /i** *ImageFileName* **+hpa** or **gflags /p /enable** *ImageFileName* **/full**. + +All page heap settings, except for **/k**, are stored in the registry and remain effective until you change them. + +Use care in interpreting the **Enable page heap** check box for an image file in the GFlags dialog box. It indicates that page heap verification is enabled for an image file, but it does not indicate whether it is full or standard page heap verification. If the check results from selecting the check box, then full page heap verification is enabled for the image file. However, if the check results from use of the command-line interface, then the check can represent the enabling of either full or standard page heap verification for the image file. + +To determine whether full or standard page heap verification is enabled for a program, at the command line, type **gflags /p**. In the resulting display, **traces** indicates that standard page heap verification is enabled for the program and **full traces** indicates that full page heap verification is enabled for the program. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20and%20PageHeap%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-commands.md b/windows-driver-docs-pr/debugger/gflags-commands.md new file mode 100644 index 0000000000..bccb3d4ad4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-commands.md @@ -0,0 +1,398 @@ +--- +title: GFlags Commands +description: To use GFlags, type the following commands at the command line. You can use the GFlags commands and the Global Flags Dialog Box interchangeably. +ms.assetid: 832b7269-623a-4f32-8bda-1059087bab09 +keywords: ["GFlags Commands Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- GFlags Commands +api_type: +- NA +--- + +# GFlags Commands + + +To use GFlags, type the following commands at the command line. + +You can use the GFlags commands and the [Global Flags Dialog Box](global-flags-dialog-box.md) interchangeably. + +To open the GFlags dialog box: + +``` +gflags +``` + +To set or clear global flags in the registry: + +``` +gflags /r [{+ | -}Flag [{+ | -}Flag...]] +``` + +To set or clear global flags for the current session: + +``` +gflags /k [{+ | -}Flag [{+ | -}Flag...]] +``` + +To set or clear global flags for an image file: + +``` +gflags /i ImageFile [{+ | -}Flag [{+ | -}Flag...]] +gflags /i ImageFile /tracedb SizeInMB +``` + +To set or clear the Special Pool feature (Windows Vista and later) + +``` +gflags {/r | /k} {+ | -}spp {PoolTag | 0xSize} +``` + +To enable or disable the Object Reference Tracing feature (Windows Vista and later) + +``` +gflags {/ro | /ko} [/p] [/i ImageFile | /t PoolTag;[PoolTag...]] +``` + +``` +gflags {/ro | /ko} /d +``` + +To enable and configure page heap verification: + +``` +gflags /p /enable ImageFile [ /full [/backwards] | /random Probability | /size SizeStart SizeEnd | /address AddressStart AddressEnd | /dlls DLL [DLL...] ] +[/debug ["DebuggerCommand"] | /kdebug] [/unaligned] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync] [/no_lock_checks] +``` + +To disable page heap verification: + +``` +gflags /p [/disable ImageFile] [/?] +``` + +To display help: + +``` +glags /? +``` + +## Parameters + + + *Flag* +Specifies a three-letter abbreviation (*FlagAbbr*) or hexadecimal value (*FlagHex*) that represents a debugging feature. The abbreviations and hexadecimal values are listed in the [GFlags Flag Table](gflags-flag-table.md). + +Use one of the following flag formats: + + ++++ + + + + + + + + + + + + + + + + +
FormatDescription

{+ | -}FlagAbbr

Sets (+) or clears (-) the flag represented by the flag abbreviation. Without a plus (+) or minus (-) symbol, the command has no effect.

[+ | -]FlagHex

Adds (+) or subtracts (-) the hexadecimal value of a flag. A flag is set when its value is included in the sum. Add (+) is the default. Enter a hexadecimal value (without 0x) that represents a single flag or enter the sum of hexadecimal values for multiple flags.

+ +  + + *ImageFile* +Specifies the name of an executable file, including the file name extension (for example, notepad.exe or mydll.dll). + + **/r** +Registry. Displays or changes system-wide debugging flags stored in the registry. These settings take effect when you restart Windows and remain effective until you change them. + +With no additional parameters, **gflags /r** displays the system-wide flags set in the registry. + + **/k** +Kernel flag settings. Displays or changes system-wide debugging flags for this session. These settings are effective immediately, but are lost when Windows shuts down. The settings affect processes started after this command completes. + +With no additional parameters, **gflags /k** displays system-wide flags set for the current session. + + **/i** +Image file settings. Displays or changes debugging flags for a particular process. These settings are stored in the registry. They are effective for all new instances of this process and they remain effective until you change them. + +With no additional parameters, **gflags /i** *ImageFile* displays the flags set for the specified process. + + **/tracedb** *SizeInMB* +Sets the maximum size of the user-mode stack trace database for the process. To use this parameter, the [Create user mode stack trace database](create-user-mode-stack-trace-database.md) (ust) flag must be set for the process. + +*SizeInMB* is a whole number representing the number of megabytes in decimal units. The default value is the minimum size, 8 MB; there is no maximum size. To revert to the default size, set *SizeInMB* to 0. + + **spp** +(Windows Vista and later.) Sets or clears the [Special Pool](special-pool.md) feature. For an example, see [Example 14: Configuring Special Pool](example-14---configuring-special-pool.md). + + *PoolTag* +(Windows Vista and later.) Specifies a pool tag for the [Special Pool](special-pool.md) feature. Use only with the **spp** flag. + +Enter a four-character pattern for *PoolTag*, such as Tag1. It can include the **?** (substitute for any single character) and **\*** (substitute for multiple characters) wildcard characters. For example, Fat\* or Av?4. Pool tags are always case-sensitive. + +**0x***Size* +(Windows Vista and later.) Specifies a size range for the Special Pool feature. Use only with the **spp** flag. For guidance on selecting a size value, see "Selecting an Allocation Size" in [Special Pool](special-pool.md). + + **/ro** +Enables, disables, and displays [Object Reference Tracing](object-reference-tracing.md) settings in the registry. To make a change to this setting effective, you must restart Windows. + +Without additional parameters, **/ro** displays the Object Reference Tracing settings in the registry. + +To enable Object Reference Tracing, you must include at least one pool tag (**/t** *PoolTag*) or one image file (**/i** ImageFile) in the command. For details, see [Example 15: Using Object Reference Tracing](example-15--using-object-reference-tracing.md). + +The following table lists the subparameters that are valid with **/ro**. + + ++++ + + + + + + + + + + + + + + + + + + +

/t PoolTags

Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags.

+

Enter a four-character pattern for PoolTags, such as Tag1.

+

If you specify more than one pool tag, Windows traces objects with any of the specified pool tags .

+

If you do not specify any pool tags, Windows traces all objects that are created by the image.

/i ImageFile

Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter.

+

Enter an image file name, such as notepad.exe, with up to 64 characters. "System" and "Idle" are not valid image names.

+

If you do not specify an image file, Windows traces all objects with the specified pool tags. If you specify both an image file (/i) and one or more pool tags (/t), Windows traces objects with any of the specified pool tags that are created by the specified image.

/d

Clears the Object Reference Tracing feature settings. When used with /ro, it clears the settings in the registry.

/p

Permanent. The trace data is retained until Object Reference Tracing is disabled, or the computer is shut down or restarted. By default, the trace data for an object is discarded when the object is destroyed.

+ +  + + **/ko** +Enables, disables, and displays kernel flag (run time) [Object Reference Tracing](object-reference-tracing.md) settings. Changes to this setting are effective immediately, but are lost when the system is shut down or restarted. For details, see [Example 15: Using Object Reference Tracing](example-15--using-object-reference-tracing.md). + +Without additional parameters, **/ko** displays the kernel flag (run time) Object Reference Tracing settings. + +To enable Object Reference Tracing, you must include at least one pool tag (**/t** *PoolTag*) or one image file (**/i** *ImageFile*) in the command. + +The following table lists the subparameters that are valid with **/ko**. + + ++++ + + + + + + + + + + + + + + + + + + +

/t PoolTags

Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags.

+

Enter a four-character pattern for PoolTags, such as Tag1.

+

If you specify more than one pool tag, Windows traces objects with any of the specified pool tags.

+

If you do not specify any pool tags, Windows traces all objects that are created by the image.

/i ImageFile

Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter.

+

If you do not specify an image file, Windows traces all objects with the specified pool tags.

+

If you specify both an image file (/i) and one or more pool tags (/t), Windows traces objects with any of the specified pool tags that are created by the specified image.

/d

Clears the Object Reference Tracing feature settings. When used with /ro, it clears the settings in the registry.

/p

Permanent. The trace data is retained until Object Reference Tracing is disabled, or the computer is shut down or restarted. By default, the trace data for an object is discarded when the object is destroyed.

+ +  + + **/p** +Sets page heap verification options for a process. + +With no additional parameters, **gflags /p** displays a list of image files for which page heap verification is enabled. + +Page heap verification monitors dynamic heap memory operations, including allocate operations and free operations, and causes a debugger break when it detects a heap error. + + **/disable** *ImageFile* +Turns off page heap verification (standard or full) for the specified image file. + +This command is equivalent to turning off the [Enable page heap](enable-page-heap.md) (hpa) flag for a process (**gflags /i** *ImageFile* **-hpa**). You can use the commands interchangeably. + + **/enable** *ImageFile* +Turns on page heap verification for the specified image file. + +By default, the **/enable** parameter turns on *standard* page heap verification for the image file. To enable *full* page heap verification for the image file, add the **/full** parameter to the command or use the **/i** parameter with the **+hpa** flag. + + **/full** +Turns on full page heap verification for the process. Full page heap verification places a zone of reserved virtual memory at the end of each allocation. + +Using this parameter is equivalent to turning on the [Enable page heap](enable-page-heap.md) (hpa) flag for a process (**gflags /i** *ImageFile* **+hpa**). You can use the commands interchangeably. + + **/backwards** +Places the zone of reserved virtual memory at the beginning of an allocation, rather than at the end. As a result, the debugger traps overruns at the beginning of the buffer, instead of those at the end of the buffer. Valid only with the **/full** parameter. + + **/random** *Probability* +Chooses full or standard page heap verification for each allocation, based on the specified probability. + +*Probability* is a decimal integer from 0 through 100 representing the probability of full page heap verification. A probability of 100 is the same as using the **/full** parameter. A probability of 0 is the same as using standard page heap verification. + + **/size** *SizeStart SizeEnd* +Enables full page heap verification for allocations within the specified size range and enables standard page heap verification for all other allocations by the process. + +*SizeStart* and *SizeEnd* are decimal integers. The default is standard page heap verification for all allocations. + + **/address** *AddressStart AddressEnd* +Enables full page heap verification for memory allocated while a return address in the specified address range is on the run-time call stack. It enables standard page heap verification for all other allocations by the process. + +To use this feature, specify a range that includes the addresses of all functions that call the function with the suspect allocation. The address of the calling function will be on the call stack when the suspect allocation occurs. + +*AddressStart* and *AddressEnd* specify the address range searched in allocation stack traces. The addresses are specified in hexadecimal format, such as, 0xAABBCCDD. + +On Windows Server 2003 and earlier systems, the **/address** parameter is valid only on *x*86-based computers. On Windows Vista,: it is valid on all supported architectures. + + **/dlls** *DLL*\[**,** *DLL*...\] +Enables full page heap verification for allocations requested by the specified DLLs and standard page heap verification for all other allocations by the process. + +*DLL* is the name of a binary file, including its file name extension. The specified file must be a function library that the process loads during execution. + + **/debug** +Automatically launches the process specified by the **/enable** parameter under a debugger. + +By default, this parameter uses the NTSD debugger with the command line **ntsd -g -G -x** and with page heap enabled, but you can use the *DebuggerCommand* variable to specify a different debugger and command line. + +For information about NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + +This option is useful for programs that are difficult to start from a command prompt and those that are started by other processes. + +**"***DebuggerCommand***"** +Specifies a debugger and the command sent to the debugger. This quoted string can include a fully qualified path to the debugger, the debugger name, and command parameters that the debugger interprets. The quotation marks are required. + +If the command includes a path to the debugger, the path cannot contain any other quotation marks. If other quotation marks appear, the command shell (*cmd.exe*) will misinterpret the command. + + **/kdebug** +Automatically launches the process specified by the **/enable** parameter under the NTSD debugger with the command line **ntsd -g -G -x**, with page heap enabled, and with control of NTSD redirected to the kernel debugger. + +For information about NTSD, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md). + + **/unaligned** +Aligns the end of each allocation at an end-of-page boundary, even if doing so means that the starting address is not aligned on an 8-byte block. By default, the heap manager guarantees that the starting address of an allocation is aligned on an 8-byte block. + +This option is used to detect off-by-one-byte errors. When this parameter is used with the **/full** parameter, the zone of reserved virtual memory begins just after the last byte of the allocation and an immediate fault occurs when a process tries to read or write even one byte beyond the allocation. + + **/decommit** +This option is no longer valid. It is accepted, but ignored. + +The PageHeap program (pageheap.exe) included in Windows 2000 implemented full page heap verification by placing an inaccessible page after an allocation. In that tool, the **/decommit** parameter substituted a zone of reserved virtual memory for the inaccessible page. In this version of GFlags, a zone of reserved virtual memory is always used to implement full page heap verification. + + **/notraces** +Specifies that run-time stack traces are not saved. + +This option improves performance slightly, but it makes debugging much more difficult. This parameter is valid, but its use is not recommended. + + **/fault** +Forces the program's memory allocations to fail at the specified rate and after the specified time-out. + +This parameter inserts heap allocation errors into the image file being tested (a practice known as "fault injection") so that some memory allocations fail, as might occur when the program runs in low memory conditions. This test helps to detect errors in handling allocation failure, such as failing to release resources. + + ++++ + + + + + + + + + + +

Rate

Specifies a decimal integer from 1 (.01%) through 10000 (100%) representing the probability that an allocation will fail. The default is 100 (1%).

TimeOut

Determines the time interval between the start of the program and the start of the fault injection routines.

+

TimeOut is measured in seconds. The default is 5 (seconds).

+ +  + + **/leaks** +Checks for heap leaks when a process ends. + +The **/leaks** parameter disables full page heap. When **/leaks** is used, the **/full** parameter and parameters that modify the **/full** parameter, such as **/backwards**, are ignored, and GFlags performs standard page heap verification with a leak check. + + **/protect** +Protects heap internal structures. This test is used to detect random heap corruptions. It can make execution significantly slower. + + **/no\_sync** +Checks for unsynchronized access. This parameter causes a break if it detects that a heap created with the HEAP\_NO\_SERIALIZE flag is accessed by different threads. + +Do not use this flag to debug a program that includes a customized heap manager. Functions that synchronize heap access cause the page heap verifier to report synchronization faults that do not exist. + + **/no\_lock\_checks** +Disables the critical section verifier. + + **/?** +Displays help for GFlags. With **/p**, **/?** displays help for the page heap verification options in GFlags. + +### Comments + +Typing **gflags** without parameters opens the **Global Flags** dialog box. + +Typing **gflags /p** without additional parameters displays a list of programs that have page heap verification enabled. + +To clear all flags, set *Flag* to **-FFFFFFFF**. (Setting *Flag* to 0 adds zero to the current flag value. It does not clear all flags.) + +When you set *Flag* for an image file to **FFFFFFFF**, Windows clears all flags and deletes the GlobalFlag entry in the registry subkey for the image file. The subkey remains. + +The **/full**, **/random**, **/size**, **/address**, and **/dlls** parameters for the page heap **/enable** operation determine which allocations are subject to page heap verification and the verification method used. You can use only one of these parameters in each command. The default is standard page heap verification of all allocations of the process. The remaining parameters set options for page heap verification. + +The page heap features in GFlags only monitor heap memory allocations that use the standard Windows heap manager functions (**HeapAlloc**, **GlobalAlloc**, **LocalAlloc**, **malloc**, **new**, **new\[\]**, or their corresponding deallocation functions), or those that use custom operations that call the standard heap manager functions. + +To determine whether full or standard page heap verification is enabled for a program, at the command line, type **gflags /p**. In the resulting display, **traces** indicates that standard page heap verification is enabled for the program and **full traces** indicates that full page heap verification is enabled for the program. + +The **/enable** parameter sets the [Enable page heap](enable-page-heap.md) (hpa) flag for the image file in the registry. However, the **/enable** parameter turns on *standard* heap verification for the image file by default, unlike the **/i** parameter with the **+hpa** flag, which turns on *full* heap verification for an image file. + +*Standard* page heap verification places random patterns at the end of an allocation and examines the patterns when a heap block is freed. *Full* page heap verification places a zone of reserved virtual memory at the end of each allocation. + +Full page heap verification can consume system memory quickly. To enable full page heap verification for memory-intensive processes, use the **/size** or **/dlls** parameter. + +After using global flags for debugging, submit a **gflags /p /disable** command to turn off the page heap verification and delete associated registry entries. Otherwise, entries that the debugger reads remain in the registry. You cannot use the **gflags /i hpa** command for this task, because it turns off page heap verification, but does not delete the registry entries. + +By default, on Windows Vista and later versions of Windows, program-specific settings (image file flags and page heap verification settings) are stored in the current user account. + +This version of GFlags includes the **-v** options, which enable features being developed for GFlags. However, these features are not yet complete and, therefore, are not documented. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-details.md b/windows-driver-docs-pr/debugger/gflags-details.md new file mode 100644 index 0000000000..4da5965ac6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-details.md @@ -0,0 +1,125 @@ +--- +title: GFlags Details +description: GFlags Details +ms.assetid: 97faa63d-b876-4973-812f-f3bdd57c1778 +keywords: ["GFlags, details"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags Details + + +## + + +GFlags enables and disables system features by editing the Windows registry and internal settings. This section explains the operation of GFlags in detail and includes tips for using GFlags most efficiently. + +### General Information + +- To display the GFlags dialog box, at the command line, type **gflags** (with no parameters). + +- On Windows Server 2003 and earlier versions of Windows, to set flags in the registry or in kernel mode, you must be a member of the Administrators group on the computer. However, users with at least Guest account access can launch a program from the GFlags dialog box. + +- GFlags system-level registry settings appear in the registry immediately, but do not take effect until you restart the system. + +- GFlags image file registry settings appear in the registry immediately, but do not take effect until you restart the process. + +- The debugger and launch features in the GFlags dialog box are program specific. You can only set them on one image file at a time. + +### Flag Details + +- To clear all flags, set the flag to -FFFFFFFF. Setting the flag to 0 adds 0 to the current flag value. + +- When you set the flags for an image file to FFFFFFFF (0xFFFFFFFF), Windows clears all flags for the image file and deletes the **GlobalFlag** entry in the image file registry key. The image file registry key is retained. + +### Dialog Box and Command Line + +You can run GFlags by using its handy dialog box or from the command line. Most features are available in both forms, with the following exceptions. + +**Dialog box only** + +- Launch. Start a program using the specified flags. + +- Run the program in a debugger. + +- [Special Pool](special-pool.md) on systems prior to Windows Vista. On Windows Vista and later versions of Windows, you can configure the Special Pool feature at the command line or in the Gflags dialog box. + +**Command line only** + +- Set the size of the user mode stack trace database (/tracedb). + +- Set page heap verification options. + +### Registry Information + +GFlags settings that are saved between sessions are stored in the registry. You can use the registry APIs, Regedit, or reg.exe to query or change these values. The following table lists the types of settings and where they are stored in the registry. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Systemwide settings ("Registry")

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\GlobalFlag

Program-specific settings ("Image file") for all users of the computer.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\GlobalFlag

Silent exit settings for a specific program ("Silent Process Exit") for all users of the computer.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\SilentProcessExit\ImageFileName

Page heap options for an image file for all users of the computer

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\PageHeapFlags

User mode stack trace database size (tracedb)

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\StackTraceDatabaseSizeInMb

Create user mode stack trace database (ust, 0x1000) for an image file

Windows adds the image file name to the value of the USTEnabled registry entry (HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\USTEnabled).

Load image using large pages if possible

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\UseLargePages.

Special Pool

+

(Kernel Special Pool Tag)

HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\PoolTag

Verify Start / Verify End

HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\PoolTagOverruns. The Verify Start option sets the value to 0. The Verify End option sets the value to 1.

Debugger for an image file

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\Debugger

Object Reference Tracing

HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Kernel\ObTraceProcessName, ObTracePermanent and ObTracePoolTags

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20Details%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-examples.md b/windows-driver-docs-pr/debugger/gflags-examples.md new file mode 100644 index 0000000000..8095d0c953 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-examples.md @@ -0,0 +1,63 @@ +--- +title: GFlags Examples +description: GFlags Examples +ms.assetid: 0aeb4a55-22b7-4eb9-a4d9-a1dd4f661ba8 +keywords: ["GFlags, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags Examples + + +## + + +The following examples show how to submit GFlags commands and how to use GFlags features in practical scenarios. + +This section includes the following topics. + +[Example 1: Displaying Global Flags](example-1---displaying-global-flags.md) + +[Example 2: Setting a Flag by Using a Flag Abbreviation](example-2---setting-a-flag-by-using-a-flag-abbreviation.md) + +[Example 3: Setting a Flag by Using Its Hexadecimal Value](example-3---setting-a-flag-by-using-its-hexadecimal-value.md) + +[Example 4: Setting Multiple Flags](example-4---setting-multiple-flags.md) + +[Example 5: Clearing a Flag](example-5---clearing-a-flag.md) + +[Example 6: Clearing All Flags](example-6---clearing-all-flags.md) + +[Example 7: Clearing All Flags for an Image File](example-7---clearing-all-flags-for-an-image-file.md) + +[Example 8: Enlarging the User-Mode Stack Trace Database](example-8---enlarging-the-user-mode-stack-trace-database.md) + +[Example 9: Detecting a Pool Memory Leak](example-9---detecting-a-pool-memory-leak.md) + +[Example 10: Detecting a Heap Memory Leak in a Process](example-10---detecting-a-heap-memory-leak-in-a-process.md) + +[Example 11: Enabling Page Heap Verification](example-11---enabling-page-heap-verification.md) + +[Example 12: Using Page Heap Verification to Find a Bug](example-12---using-page-heap-verification-to-find-a-bug.md) + +[Example 13: Listing Image Files with Global Flags](example-13---listing-image-files-with-global-flags.md) + +[Example 14: Configuring Special Pool](example-14---configuring-special-pool.md) + +[Example 15: Using Object Reference Tracing](example-15--using-object-reference-tracing.md) + +The examples in the second section apply to features available only in Windows Vista and later versions of Windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-flag-table.md b/windows-driver-docs-pr/debugger/gflags-flag-table.md new file mode 100644 index 0000000000..801ab700e9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-flag-table.md @@ -0,0 +1,313 @@ +--- +title: GFlags Flag Table +description: GFlags Flag Table +ms.assetid: 09029471-8b29-4232-bee1-d2802035b0fb +keywords: ["GFlags, flag table"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags Flag Table + + +## + + +The following table lists the flags that GFlags changes, the hexadecimal value and abbreviation for each flag, and the destination (R for registry, K for kernel, I for image file) in which the flag is valid. + +For a detailed description of each flag, see the [Global Flag Reference](global-flag-reference.md). + +For information about using GFlags, see [GFlags Overview](gflags-overview.md) and [GFlags Details](gflags-details.md). + +**Important**   Pool tagging is permanently enabled in Windows Server 2003 and later versions of Windows. On these systems, the **Enable pool tagging** check box on the **Global Flags** dialog box is dimmed, and commands to enable or disable pool tagging fail. + +  + +**Note**  The symbolic name of each flag is provided for reference only. Because symbolic names change, they are not a reliable identifier of a global flag. + +  + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DescriptionSymbolic NameHexadecimal ValueAbbreviationDestination

[Buffer DbgPrint Output](buffer-dbgprint-output.md)

FLG_DISABLE_DBGPRINT

0x08000000

ddp

R,K

[Create kernel mode stack trace database](create-kernel-mode-stack-trace-database.md)

FLG_KERNEL_STACK_TRACE_DB

0x2000

kst

R

[Create user mode stack trace database](create-user-mode-stack-trace-database.md)

FLG_USER_STACK_TRACE_DB

0x1000

ust

R,K,I

[Debug initial command](debug-initial-command.md)

FLG_DEBUG_INITIAL_COMMAND

0x04

dic

R

[Debug WinLogon](debug-winlogon.md)

FLG_DEBUG_INITIAL_COMMAND_EX

0x04000000

dwl

R

[Disable heap coalesce on free](disable-heap-coalesce-on-free.md)

FLG_HEAP_DISABLE_COALESCING

0x00200000

dhc

R,K,I

[Disable paging of kernel stacks](disable-paging-of-kernel-stacks.md)

FLG_DISABLE_PAGE_KERNEL_STACKS

0x080000

dps

R

[Disable protected DLL verification](disable-protected-dll-verification.md)

FLG_DISABLE_PROTDLLS

0x80000000

dpd

R,K,I

[Disable stack extension](disable-stack-extension.md)

FLG_DISABLE_STACK_EXTENSION

0x010000

dse

I

[Early critical section event creation](early-critical-section-event-creation.md)

FLG_CRITSEC_EVENT_CREATION

0x10000000

cse

R,K,I

[Enable application verifier](enable-application-verifier.md)

FLG_APPLICATION_VERIFIER

0x0100

vrf

R,K,I

[Enable bad handles detection](enable-bad-handles-detection.md)

FLG_ENABLE_HANDLE_EXCEPTIONS

0x40000000

bhd

R,K

[Enable close exception](enable-close-exception.md)

FLG_ENABLE_CLOSE_EXCEPTIONS

0x400000

ece

R,K

[Enable debugging of Win32 subsystem](enable-debugging-of-win32-subsystem.md)

FLG_ENABLE_CSRDEBUG

0x020000

d32

R

[Enable exception logging](enable-exception-logging.md)

FLG_ENABLE_EXCEPTION_LOGGING

0x800000

eel

R,K

[Enable heap free checking](enable-heap-free-checking.md)

FLG_HEAP_ENABLE_FREE_CHECK

0x20

hfc

R,K,I

[Enable heap parameter checking](enable-heap-parameter-checking.md)

FLG_HEAP_VALIDATE_PARAMETERS

0x40

hpc

R,K,I

[Enable heap tagging](enable-heap-tagging.md)

FLG_HEAP_ENABLE_TAGGING

0x0800

htg

R,K,I

[Enable heap tagging by DLL](enable-heap-tagging-by-dll.md)

FLG_HEAP_ENABLE_TAG_BY_DLL

0x8000

htd

R,K,I

[Enable heap tail checking](enable-heap-tail-checking.md)

FLG_HEAP_ENABLE_TAIL_CHECK

0x10

htc

R,K,I

[Enable heap validation on call](enable-heap-validation-on-call.md)

FLG_HEAP_VALIDATE_ALL

0x80

hvc

R,K,I

[Enable loading of kernel debugger symbols](enable-loading-of-kernel-debugger-symbols.md)

FLG_ENABLE_KDEBUG_SYMBOL_LOAD

0x040000

ksl

R,K

[Enable object handle type tagging](enable-object-handle-type-tagging.md)

FLG_ENABLE_HANDLE_TYPE_TAGGING

0x01000000

eot

R,K

[Enable page heap](enable-page-heap.md)

FLG_HEAP_PAGE_ALLOCS

0x02000000

hpa

R,K,I

+[Enable pool tagging](enable-pool-tagging.md) +(Windows 2000 and Windows XP only)

FLG_POOL_ENABLE_TAGGING

0x0400

ptg

R

[Enable system critical breaks](enable-system-critical-breaks.md)

FLG_ENABLE_SYSTEM_CRIT_BREAKS

0x100000

scb

R, K, I

[Load image using large pages if possible](load-image-using-large-pages-if-possible.md)

lpg

I

[Maintain a list of objects for each type](maintain-a-list-of-objects-for-each-type.md)

FLG_MAINTAIN_OBJECT_TYPELIST

0x4000

otl

R

[Enable silent process exit monitoring](enable-silent-process-exit-monitoring.md)

FLG_MONITOR_SILENT_PROCESS_EXIT

0x200

R

[Object Reference Tracing](object-reference-tracing.md)

+

(Windows Vista and later)

R, K

[Show loader snaps](show-loader-snaps.md)

FLG_SHOW_LDR_SNAPS

0x02

sls

R,K,I

[Special Pool](special-pool.md)

spp

R

+

R,K (Windows Vista and later)

[Stop on exception](stop-on-exception.md)

FLG_STOP_ON_EXCEPTION

0x01

soe

R,K,I

[Stop on hung GUI](stop-on-hung-gui.md)

FLG_STOP_ON_HUNG_GUI

0x08

shg

K

[Stop on unhandled user-mode exception](stop-on-unhandled-user-mode-exception.md)

FLG_STOP_ON_UNHANDLED_EXCEPTION

0x20000000

sue

R,K,I

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20Flag%20Table%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags-overview.md b/windows-driver-docs-pr/debugger/gflags-overview.md new file mode 100644 index 0000000000..b60c2f4a30 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags-overview.md @@ -0,0 +1,57 @@ +--- +title: GFlags Overview +description: GFlags Overview +ms.assetid: fa5c48bf-c0d0-4010-a101-381c692082bf +keywords: ["GFlags, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags Overview + + +## + + +GFlags (gflags.exe), the Global Flags Editor, enables and disables advanced internal system diagnostic and troubleshooting features. You can run GFlags from a Command Prompt window or use its graphical user interface dialog box. + +Use GFlags to activate the following features: + +Registry +Set system-wide debugging features for all processes running on the computer. These settings are stored in the **GlobalFlag** registry entry (**HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\GlobalFlag**). They take effect when you restart Windows and remain effective until you change them and restart again. + +Kernel flag settings +Set debugging features for this session. These settings are effective immediately, but are lost when Windows shuts down. The settings affect all processes started after this command completes. + +Image file settings +Set debugging features for a particular program. These settings are stored in a GlobalFlag registry entry for each program (**HKEY\_LOCAL\_MACHINE\\ SOFTWARE\\ Microsoft\\ Windows NT\\ CurrentVersion\\ Image File Execution Options\\ *ImageFileName*\\ GlobalFlag**). They take effect when you restart the program and remain effective until you change them. + +Debugger +Specify that a particular program always runs in a debugger. This setting is stored in the registry. It is effective immediately and remains effective until you change it. (This feature is available only in the **Global Flags** dialog box.) + +Launch +Run a program with the specified debugging settings. The debugging settings are effective until the program stops. (This feature is available only from the **Global Flags** dialog box.) + +Special Pool +Request that allocation with a specified pool tag or of a specified size are filled from the special pool. This feature helps you to detect and identify the source of errors in kernel pool use, such as writing beyond the allocated memory space, or referring to memory that has already been freed. + +Beginning in Windows Vista, you can enable, disable, and configure the special pool feature (**Kernel Special Pool Tag**) as a kernel flags setting, which does not require a reboot, or as a registry setting, which requires a reboot. + +Page heap verification +Enable, disable, and configure page heap verification for a program. When enabled, page heap monitors dynamic heap memory operations, including allocation and free operations, and causes a debugger break when it detects a heap error. + +Silent process exit +Enable, disable, and configure monitoring and reporting of silent exits for a process. You can specify actions that occur when a process exits silently, including notification, event logging, and creation of dump files. For more information, see [Monitoring Silent Process Exit](registry-entries-for-silent-process-exit.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20Overview%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gflags.md b/windows-driver-docs-pr/debugger/gflags.md new file mode 100644 index 0000000000..c7ce2319ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/gflags.md @@ -0,0 +1,86 @@ +--- +title: GFlags +description: GFlags (the Global Flags Editor), gflags.exe, enables and disables advanced debugging, diagnostic, and troubleshooting features. +ms.assetid: e268af2e-90a9-411e-8e29-ab486d2aac48 +keywords: GFlags, Global Flags Editor, gflags.exe +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# GFlags + + +GFlags (the Global Flags Editor), gflags.exe, enables and disables advanced debugging, diagnostic, and troubleshooting features. It is most often used to turn on indicators that other tools track, count, and log. + +## Where to get GFlags + + +GFlags is included in [Debugging Tools for Windows](index.md). + +## Overview of GFlags + + +Driver developers and testers often use GFlags to turn on debugging, logging and test features, either directly, or by including GFlags commands in a test script. The page heap verification features can help you to identify memory leaks and buffer errors in kernel-mode drivers. + +GFlags has both a dialog box and a command-line interface. Most features are available from both interfaces, but some features are accessible from only one of the interfaces. (See [GFlags Details](gflags-details.md).) + +### Features + +- Page heap verification. GFlags now includes the functions of PageHeap (pageheap.exe), a tool that enables heap allocation monitoring. PageHeap was included in previous versions of Windows. + +- No reboot required for the Special Pool feature. On Windows Vista and later versions of Windows, you can enable, disable, and configure the Special Pool feature without restarting ("rebooting") the computer. For information, see [Special Pool](special-pool.md). + +- Object Reference Tracing. A new flag enables tracing of object referencing and object dereferencing in the kernel. This new feature of Windows detects when an object reference count is decremented too many times or not decremented even though an object is no longer used. This flag is supported only in Windows Vista and later versions of Windows. + +- New dialog box design. The GFlags dialog box has tabbed pages for easier navigation. + +### Requirements + +To use most GFlags features, including setting flags in the registry or in kernel mode, or enabling page heap verification, you must be a member of the Administrators group on the computer. However, prior to Windows Vista, users with at least Guest account access can launch a program from the **Global Flags** dialog box. + +When features do not work, or work differently, on particular operating system versions, the differences are explained in the description of the feature. + +This topic includes: + +[GFlags Overview](gflags-overview.md) + +[GFlags Details](gflags-details.md) + +[**GFlags Commands**](gflags-commands.md) + +[GFlags Flag Table](gflags-flag-table.md) + +[GFlags and PageHeap](gflags-and-pageheap.md) + +[Global Flags Dialog Box](global-flags-dialog-box.md) + +[GFlags Examples](gflags-examples.md) + +[Global Flag Reference](global-flag-reference.md) + +**Note**   Incorrect use of this tool can degrade system performance or prevent Windows from starting, requiring you to reinstall Windows. + +  + +**Important**  Pool tagging is permanently enabled on Windows Server 2003 and later versions of Windows, including Windows Vista. On these systems, the **Enable pool tagging** check box on the **Global Flags** dialog box is dimmed and commands to enable or disable pool tagging fail. + +  + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GFlags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/gh--go-with-exception-handled-.md b/windows-driver-docs-pr/debugger/gh--go-with-exception-handled-.md new file mode 100644 index 0000000000..851c164712 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gh--go-with-exception-handled-.md @@ -0,0 +1,102 @@ +--- +title: gh (Go with Exception Handled) +description: The gh command marks the given thread's exception as having been handled and allows the thread to restart execution at the instruction that caused the exception. +ms.assetid: 3e06a3ff-b57d-435f-9625-011f38d7b26a +keywords: ["gh (Go with Exception Handled) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gh (Go with Exception Handled) +api_type: +- NA +--- + +# gh (Go with Exception Handled) + + +The **gh** command marks the given thread's exception as having been handled and allows the thread to restart execution at the instruction that caused the exception. + +User-Mode Syntax + +``` +[~Thread] gh[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +Kernel-Mode Syntax + +``` +gh[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +## Parameters + + + *Thread* +(User mode only) Specifies the thread to execute. This thread must have been stopped by an exception. For syntax details, see [Thread Syntax](thread-syntax.md). + + **a** +Causes any breakpoint created by this command to be a processor breakpoint (like those created by [**ba**](ba--break-on-access-.md)) rather than a software breakpoint (like those created by [**bp**](bp--bu--bm--set-breakpoint-.md) and **bm**). If *BreakAddress* is not specified, no breakpoint is created and the **a** flag has no effect. + + *StartAddress* +Specifies the address at which execution should begin. If this is not specified, the debugger passes execution to the address where the exception occurred. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakAddress* +Specifies the address for a breakpoint. If *BreakAddress* is specified, it must specify an instruction address (that is, the address must contain the first byte of an instruction). Up to ten break addresses, in any order, can be specified at one time. If *BreakAddress* cannot be resolved, it is stored as an [unresolved breakpoint](unresolved-breakpoints---bu-breakpoints-.md). For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakCommands* +Specifies one or more commands to be automatically executed when the breakpoint specified by *BreakAddress* is hit. The *BreakCommands* parameter must be preceded by a semicolon. If multiple *BreakAddress* values are specified, *BreakCommands* applies to all of them. + +**Note**   The *BreakCommands* parameter is only available when you are embedding this command within a command string used by another command -- for example, within another breakpoint command or within an except or event setting. On a command line, the semicolon will terminate the **gh** command, and any additional commands listed after the semicolon will be executed immediately after the **gh** command is done. + +  + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of issuing this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +If you use the *BreakAddress* parameter to set a breakpoint, this new breakpoint will only be triggered by the current thread. Other threads that execute the code at that location will not be stopped. + +If *Thread* is specified, then the **gh** command is executed with the specified thread unfrozen and all others frozen. For example, if the **~123gh**, **~\#gh**, or **~\*gh** command is specified, the specified threads are unfrozen and all others are frozen. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20gh%20%28Go%20with%20Exception%20Handled%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/global-flag-reference.md b/windows-driver-docs-pr/debugger/global-flag-reference.md new file mode 100644 index 0000000000..8714ee0fec --- /dev/null +++ b/windows-driver-docs-pr/debugger/global-flag-reference.md @@ -0,0 +1,101 @@ +--- +title: Global Flag Reference +description: Global Flag Reference +ms.assetid: 17de082d-a252-46e6-a0ca-9f8d4273c1c4 +keywords: ["GFlags, global flag reference"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Global Flag Reference + + +## + + +This reference describes the flags that GFlags sets. + +**Note**   The symbolic name of each flag is provided for reference only. Because symbolic names change, they are not a reliable identifier of a global flag. + +  + +The global flags include: + +[Buffer DbgPrint Output](buffer-dbgprint-output.md) + +[Create kernel mode stack trace database](create-kernel-mode-stack-trace-database.md) + +[Create user mode stack trace database](create-user-mode-stack-trace-database.md) + +[Debug initial command](debug-initial-command.md) + +[Debug WinLogon](debug-winlogon.md) + +[Disable heap coalesce on free](disable-heap-coalesce-on-free.md) + +[Disable paging of kernel stacks](disable-paging-of-kernel-stacks.md) + +[Disable protected DLL verification](disable-protected-dll-verification.md) + +[Disable stack extension](disable-stack-extension.md) + +[Early critical section event creation](early-critical-section-event-creation.md) + +[Enable application verifier](enable-application-verifier.md) + +[Enable bad handles detection](enable-bad-handles-detection.md) + +[Enable close exception](enable-close-exception.md) + +[Enable debugging of Win32 subsystem](enable-debugging-of-win32-subsystem.md) + +[Enable exception logging](enable-exception-logging.md) + +[Enable heap free checking](enable-heap-free-checking.md) + +[Enable heap tagging](enable-heap-tagging.md) + +[Enable heap tagging by DLL](enable-heap-tagging-by-dll.md) + +[Enable heap tail checking](enable-heap-tail-checking.md) + +[Enable heap validation on call](enable-heap-validation-on-call.md) + +[Enable loading of kernel debugger symbols](enable-loading-of-kernel-debugger-symbols.md) + +[Enable object handle type tagging](enable-object-handle-type-tagging.md) + +[Enable page heap](enable-page-heap.md) + +[Enable pool tagging](enable-pool-tagging.md) + +[Enable system critical breaks](enable-system-critical-breaks.md) + +[Load image using large pages if possible](load-image-using-large-pages-if-possible.md) + +[Maintain a list of objects for each type](maintain-a-list-of-objects-for-each-type.md) + +[Object Reference Tracing](object-reference-tracing.md) + +[Show loader snaps](show-loader-snaps.md) + +[Special Pool](special-pool.md) + +[Stop on exception](stop-on-exception.md) + +[Stop on hung GUI](stop-on-hung-gui.md) + +[Stop on unhandled user-mode exception](stop-on-unhandled-user-mode-exception.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Global%20Flag%20Reference%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/global-flags-dialog-box.md b/windows-driver-docs-pr/debugger/global-flags-dialog-box.md new file mode 100644 index 0000000000..f168ea731e --- /dev/null +++ b/windows-driver-docs-pr/debugger/global-flags-dialog-box.md @@ -0,0 +1,61 @@ +--- +title: Global Flags Dialog Box +description: Global Flags Dialog Box +ms.assetid: c6987d72-4141-45f2-af06-f4c7040a7e6b +keywords: ["GFlags, dialog box"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Global Flags Dialog Box + + +## + + +You can use the **Global Flags** dialog box to set and clear global flags from a user interface that lists all flags by name. There is no need to look up flag abbreviations or hexadecimal values. + +Also, the dialog box provides access to the following features that are not available from the command line: + +- **Debugger** − Specifies that a particular program always runs in a debugger. + +- **Launch** − Runs a program with the specified debugging settings. + +- **Kernel Special Pool Tag** − Configures the Special Pool feature. + +This topic includes instructions for the following procedures: + +[Opening the Dialog Box](opening-the-dialog-box.md) + +[Setting and Clearing System-wide Flags](setting-and-clearing-system-wide-flags.md) + +[Setting and Clearing Kernel Flags](setting-and-clearing-kernel-flags.md) + +[Setting and Clearing Image File Flags](setting-and-clearing-image-file-flags.md) + +[Launching a Program with Flags](launching-a-program-with-flags.md) + +[Running a Program in a Debugger](running-a-program-in-a-debugger.md) + +[Configuring Special Pool](configuring-special-pool.md) + +[Configuring Object Reference Tracing](configuring-object-reference-tracing.md) + +Pool tagging is permanently enabled on Windows Server 2003 and later versions of Windows. On these systems, the **Enable pool tagging** check box on the **Global Flags** dialog box is dimmed, and commands to enable or disable pool tagging fail. + +Use care in interpreting the **Enable page heap** check box for an image file in the **Global Flags** dialog box. This check box indicates that page heap verification is enabled for an image file, but it does not indicate whether it is full or standard page heap verification. If the check results from selecting the check box, then full page heap verification is enabled for the image file. However, if the check results from use of the command-line interface, then the check can represent the enabling of either full or standard page heap verification for the image file. + +To determine whether a full or standard page heap verification is enabled for a program, at the command line, type **gflags /p**. In the resulting display, **traces** indicates that standard page heap verification is enabled for the program and **full traces** indicates that full page heap verification is enabled for the program. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Global%20Flags%20Dialog%20Box%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/glossary.md b/windows-driver-docs-pr/debugger/glossary.md new file mode 100644 index 0000000000..f48aefd62a --- /dev/null +++ b/windows-driver-docs-pr/debugger/glossary.md @@ -0,0 +1,21 @@ +--- +title: Glossary +description: This glossary contains terms and acronyms related to the Microsoft Debugging Tools for Windows. +Robots: noindex, nofollow +ms.assetid: efe5bf4a-1527-42af-b060-92e6e9ea6333 +--- + +# Glossary + + +This glossary contains terms and acronyms related to the Microsoft Debugging Tools for Windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Glossary%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gn--gn--go-with-exception-not-handled-.md b/windows-driver-docs-pr/debugger/gn--gn--go-with-exception-not-handled-.md new file mode 100644 index 0000000000..f34da6a101 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gn--gn--go-with-exception-not-handled-.md @@ -0,0 +1,106 @@ +--- +title: gn, gN (Go with Exception Not Handled) +description: The gn and gN commands continue execution of the given thread without marking the exception as having been handled. This allows the application's exception handler to handle the exception. +ms.assetid: b6f69882-b30a-45b7-b777-1b4857719e7f +keywords: ["gn, gN (Go with Exception Not Handled) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gn, gN (Go with Exception Not Handled) +api_type: +- NA +--- + +# gn, gN (Go with Exception Not Handled) + + +The **gn** and **gN** commands continue execution of the given thread without marking the exception as having been handled. This allows the application's exception handler to handle the exception. + +User-Mode Syntax + +``` +[~Thread] gn[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +[~Thread] gN[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +Kernel-Mode Syntax + +``` +gn[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +gN[a] [= StartAddress] [BreakAddress ... [; BreakCommands]] +``` + +## Parameters + + + *Thread* +(User mode only) Specifies the thread to execute. This thread must have been stopped by an exception. For syntax details, see [Thread Syntax](thread-syntax.md). + + **a** +Causes any breakpoint created by this command to be a processor breakpoint (like those created by [**ba**](ba--break-on-access-.md)) rather than a software breakpoint (like those created by [**bp**](bp--bu--bm--set-breakpoint-.md) and **bm**). If *BreakAddress* is not specified, no breakpoint is created and the **a** flag has no effect. + + *StartAddress* +Specifies the address where execution should begin. If this is not specified, the debugger passes execution to the address where the exception occurred. For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakAddress* +Specifies the address for a breakpoint. If *BreakAddress* is specified, it must specify an instruction address (that is, the address must contain the first byte of an instruction). Up to ten break addresses, in any order, can be specified at one time. If *BreakAddress* cannot be resolved, it is stored as an [unresolved breakpoint](unresolved-breakpoints---bu-breakpoints-.md). For more syntax details, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *BreakCommands* +Specifies one or more commands to be automatically executed when the breakpoint specified by *BreakAddress* is hit. The *BreakCommands* parameter must be preceded by a semicolon. If multiple *BreakAddress* values are specified, *BreakCommands* applies to all of them. + +**Note**   The *BreakCommands* parameter is only available when you are embedding this command within a command string used by another command -- for example, within another breakpoint command or within an except or event setting. On a command line, the semicolon will terminate the command, and any additional commands listed after the semicolon will be executed immediately after the **gn** or **gN** command is done. + +  + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of issuing this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +If the debugger is not stopped at a breakpoint, **gn** and **gN** behave identically. If the debugger is stopped at a breakpoint, **gn** will not work; you must capitalize the "N" to execute this command. This is a safety precaution, since it is rarely wise to continue a breakpoint unhandled. + +If you use the *BreakAddress* parameter to set a breakpoint, this new breakpoint will only be triggered by the current thread. Other threads that execute the code at that location will not be stopped. + +If *Thread* is specified, then the **gn** command is executed with the specified thread unfrozen and all others frozen. For example, if the **~123gn**, **~\#gn**, or **~\*gn** command is specified, the specified threads are unfrozen and all others are frozen. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20gn,%20gN%20%28Go%20with%20Exception%20Not%20Handled%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gpio-extensions.md b/windows-driver-docs-pr/debugger/gpio-extensions.md new file mode 100644 index 0000000000..9138478195 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gpio-extensions.md @@ -0,0 +1,97 @@ +--- +title: GPIO Extensions +description: The General Purpose Input/Output (GPIO) extension commands display the software state of GPIO controllers. +ms.assetid: 1703C402-D770-4D3F-AB70-F2D30712A5D9 +--- + +# GPIO Extensions + + +The General Purpose Input/Output (GPIO) extension commands display the software state of GPIO controllers. These commands display information from data structures maintained by the GPIO framework extension driver (Msgpioclx.sys). For information about the GPIO framework extension, see [General-Purpose I/O (GPIO) Drivers](http://go.microsoft.com/fwlink/p?LinkID=299823). + +The GPIO debugger extension commands are implemented in gpiokd.dll. To load the GPIO commands, enter **.load gpiokd.dll** in the debugger. + +Each GPIO controller has a set of banks. Each bank has a pin table that has an array of pins. The GPIO debugger extension commands display information about GPIO controllers, banks, pin tables, and pins. + +## Data structures used by the GPIO commands + + +The GPIO debugger extension commands use these data structures, which are defined by Msgpioclx.sys. + +**msgpioclx!\_DEVICE\_EXTENSION** +The device extension structure for the GPIO framework extension driver. This structure holds information about an individual GPIO controller. + +**msgpioclx!\_GPIO\_BANK\_ENTRY** +This structure holds information about an individual bank of a GPIO controller. + +**msgpioclx!\_GPIO\_PIN\_INFORMATION\_ENTRY** +This structure holds information about an individual pin in a bank of a GPIO controller. + +## Getting started with GPIO debugging + + +To start debugging a GPIO issue, enter the [**!gpiokd.clientlist**](-gpiokd-clientlist.md) command. The **!gpiokd.clientlist** command displays an overview of all registered GPIO controllers and displays addresses that you can pass to other GPIO debugger commands. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[!gpiokd.help](-gpiokd-help.md)

The [!gpiokd.help](-gpiokd-help.md) command displays help for the GPIO debugger extension commands.

[!gpiokd.bankinfo](-gpiokd-bankinfo.md)

The [!gpiokd.bankinfo](-gpiokd-bankinfo.md) command displays information about a GPIO bank.

[!gpiokd.clientlist](-gpiokd-clientlist.md)

The [!gpiokd.clientlist](-gpiokd-clientlist.md) command displays all registered GPIO controllers.

[!gpiokd.gpioext](-gpiokd-gpioext.md)

The [!gpiokd.gpioext](-gpiokd-gpioext.md) command displays information about a GPIO controller.

[!gpiokd.pininfo](-gpiokd-pininfo.md)

The [!gpiokd.pininfo](-gpiokd-pininfo.md) command displays information about a specified GPIO pin.

[!gpiokd.pinisrvec](-gpiokd-pinisrvec.md)

The [!gpiokd.pinisrvec](-gpiokd-pinisrvec.md) command displays Interrupt Service Routine (ISR) vector information for a specified pin.

[!gpiokd.pintable](-gpiokd-pintable.md)

The [!gpiokd.pintable](-gpiokd-pintable.md) command displays information about an array of GPIO pins.

+ +  + +## Related topics + + +[Specialized Extension Commands](specialized-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20GPIO%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/graph-analysis-with-unloadable-modules.md b/windows-driver-docs-pr/debugger/graph-analysis-with-unloadable-modules.md new file mode 100644 index 0000000000..094c540081 --- /dev/null +++ b/windows-driver-docs-pr/debugger/graph-analysis-with-unloadable-modules.md @@ -0,0 +1,107 @@ +--- +title: Graph Analysis with Unloadable Modules +description: Graph Analysis with Unloadable Modules +ms.assetid: 12441fa1-3d19-4485-815c-546367f31567 +keywords: ["kernel streaming debugging, unloadable modules"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Graph Analysis with Unloadable Modules + + +This section describes a scenario that may affect you if you are working with unloadable modules such as KMixer. + +After loading, the extension module initializes at the first command usage. At initialization, the extension module checks whether every module is loaded and has correct symbols. If any individual module is unloaded or has incorrect symbols loaded, the extension disables the library extension which handles identification, dumping, etc. for that module. In this case, you need to manually re-enable the disabled module. + +The above situation may occur if you load the extension at boot time. Specifically, you may encounter this scenario if you load Ks.dll and then issue a [**.reboot**](-reboot--reboot-target-computer-.md) command. Or, it could happen if you break into the debugger during boot and load Ks.dll at that point. + +In the following example, we are capturing two streams (sndrec32) from a Telex USB microphone. Breaking on **splitter!FilterProcess** and running [**!ks.graph**](-ks-graph.md) on splitter's filter yields: + +``` +kd> !graph ffa0c6d4 7 +Attempting a graph build on ffa0c6d4... Please be patient... +Graph With Starting Point ffa0c6d4: +"usbaudio" Filter ffaaa768, Child Factories 2 + Output Factory 0: + Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p) = 7, 1 +"splitter" Filter ffa0c660, Child Factories 2 + Output Factory 0: + Pin 81250008 (File ffb10028) Irps(q/p) = 3, 0 + Pin 811df9c0 (File ffaaf2f0) Irps(q/p) = 3, 0 + Input Factory 1: + Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p) = 1, 7 +``` + +In this example, KMixer has been loaded and connected to splitter, but Kmixer does not appear in the graph. There are IRPs queued to splitter's output pin, yet the **!ks.graph** command is unable to backtrace and discover KMixer. Issue a [**!ks.libexts details**](-ks-libexts.md) command to investigate further: + +``` +kd> !libexts details +## LibExt Details: +-------------------------------------------------- +LibExt "portcls!" : + Status : ACTIVE + This is the port class library extension to the KS DLL. It supports + dumping wave cyclic, wave pci, irp streams, and several other upper + level structures. + Commands Exported: pciaudio + Help : pchelp + Hooks : dump dumpqueue dumpcircuit conv(file) conv(device) graph +LibExt "STREAM!" : + Status : ACTIVE + This is the stream class library extension to the KS DLL. It supports + dumping device extensions, filters, streams, and SRBs. + Hooks : dump enumdevobj graph +LibExt "kmixer!" : + Status : INACTIVE + This is the KMIXER extension to the KS DLL. It supports + virtually nothing at this point! + Hooks : dump graph +``` + +According to the above output, the KMixer section of the extension is currently disabled (Status : INACTIVE). Since the extension module was first used in a context in which KMixer was not loaded, Ks.dll has disabled the KMixer section of the extension to prevent time-consuming references to an unloaded module. + +To enable KMixer explicitly, you can use [**!ks.libexts**](-ks-libexts.md) with the **enable** parameter, as follows: + +``` +kd> !libexts enable kmixer +LibExt "kmixer" has been enabled. + +kd> !graph ffa0c6d4 7 +Attempting a graph build on ffa0c6d4... Please be patient... +Graph With Starting Point ffa0c6d4: +"usbaudio" Filter ffaaa768, Child Factories 2 + Output Factory 0: + Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p) = 7, 1 +"splitter" Filter ffa0c660, Child Factories 2 + Output Factory 0: + Pin 81250008 (File ffb10028, -> "kmixer" 8123c000) Irps(q/p) = 3, 0 + Pin 811df9c0 (File ffaaf2f0, -> "kmixer" 81236000) Irps(q/p) = 3, 0 + Input Factory 1: + Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p) = 1, 7 +"kmixer" Filter ffa65b70, Child Factories 4 + Input Factory 2: + Pin 81236000 (File ffaaf7d0, <- "splitter" 811df9c0) Irps(q/p) = 0, 0 + Output Factory 3: + Pin 81252d00 (File 811df1d8) Irps(q/p) = 10, 0 +"kmixer" Filter ffb03808, Child Factories 4 + Input Factory 2: + Pin 8123c000 (File ffb10130, <- "splitter" 81250008) Irps(q/p) = 0, 0 + Output Factory 3: + Pin ffa1e9c0 (File 81253468) Irps(q/p) = 10, 0 +``` + +KMixer now appears as expected in the capture graph. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Graph%20Analysis%20with%20Unloadable%20Modules%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/graphics-driver-extensions--gdikdx-dll-.md b/windows-driver-docs-pr/debugger/graphics-driver-extensions--gdikdx-dll-.md new file mode 100644 index 0000000000..8c012c7a4c --- /dev/null +++ b/windows-driver-docs-pr/debugger/graphics-driver-extensions--gdikdx-dll-.md @@ -0,0 +1,31 @@ +--- +title: Graphics Driver Extensions (Gdikdx.dll) +description: Graphics Driver Extensions (Gdikdx.dll) +ms.assetid: f8fa570c-e225-4b7d-a3db-a04d5ab04882 +keywords: ["graphics driver extensions (gdikdx.dll)", "gdikdx.dll (graphics driver extensions)", "extensions, graphics driver"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Graphics Driver Extensions (Gdikdx.dll) + + +## + + +Extension commands that are useful for debugging the Graphics Driver Interface (GDI) can be found in Gdikdx.dll. + +The Windows 2000 version of this extension DLL appears in the w2kfre and w2kchk directories. There is no version of this DLL for Windows XP or later versions of Windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Graphics%20Driver%20Extensions%20%28Gdikdx.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/gu--go-up-.md b/windows-driver-docs-pr/debugger/gu--go-up-.md new file mode 100644 index 0000000000..dbc9628a75 --- /dev/null +++ b/windows-driver-docs-pr/debugger/gu--go-up-.md @@ -0,0 +1,92 @@ +--- +title: gu (Go Up) +description: The gu command causes the target to execute until the current function is complete. +ms.assetid: 10022292-92a4-4663-b277-26aa3c0d73a7 +keywords: ["gu (Go Up) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- gu (Go Up) +api_type: +- NA +--- + +# gu (Go Up) + + +The **gu** command causes the target to execute until the current function is complete. + +User-Mode Syntax + +``` +[~Thread] gu +``` + +Kernel-Mode Syntax + +``` +gu +``` + +## Parameters + + + *Thread* +(User mode only) Specifies the thread to execute. This thread must have been stopped by an exception. For syntax details, see [Thread Syntax](thread-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

user mode, kernel mode

Targets

live debugging only

Platforms

all

+ +  + +### Additional Information + +For other methods of issuing this command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **gu** command executes the target until the current function call returns. + +If the current function is called recursively, the **gu** command will not halt execution until the *current instance* of the current function returns. In this way, **gu** differs from **g @$ra**, which will halt any time the return address of this function is hit. + +**Note**   The **gu** command distinguishes different instances of a function by measuring the call stack depth. Executing this command in assembly mode after the arguments have been pushed to the stack and just before the call is made may cause this measurement to be incorrect. Function returns that are optimized away by the compiler may similarly cause this command to stop at the wrong instance of this return. These errors are rare, and can only happen during recursive function calls. + +  + +If *Thread* is specified, then the **gu** command is executed with the specified thread unfrozen and all others frozen. For example, if the **~123gu**, **~\#gu**, or **~\*gu** command is specified, the specified threads are unfrozen and all others are frozen. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20gu%20%28Go%20Up%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/h.md b/windows-driver-docs-pr/debugger/h.md new file mode 100644 index 0000000000..e08e8b16a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/h.md @@ -0,0 +1,32 @@ +--- +title: H (Windows Debugger Glossary) +description: Glossary page - H +Robots: noindex, nofollow +ms.assetid: 478e6900-86f9-487c-a2fd-18543402f5e2 +--- + +# H + + +**host** +See host computer. + +**handling status** +The handling status specifies whether the debugger engine should flag an exception event as handled or not. The handling status is part of an exception filter. + +See also break status. For more information, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md) and [Event Filters](event-filters.md) + +**host computer** +The host computer is the computer that runs the debugging session. All debugger operations--such as executing commands and extensions, and symbol loading--are performed on the host computer. + +In a typical two-system kernel debugging session, the debugger is running on the host computer, which is connected to the target computer being debugged. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20H%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/handling-a-bug-check-when-driver-verifier-is-enabled.md b/windows-driver-docs-pr/debugger/handling-a-bug-check-when-driver-verifier-is-enabled.md new file mode 100644 index 0000000000..546c766a0c --- /dev/null +++ b/windows-driver-docs-pr/debugger/handling-a-bug-check-when-driver-verifier-is-enabled.md @@ -0,0 +1,177 @@ +--- +title: Handling a Bug Check When Driver Verifier is Enabled +description: Driver Verifier detects driver errors at run time. You can use Driver Verifier along with the analyze debugger command to detect and display information about errors in your driver. +ms.assetid: 4226B62B-0AA5-4D04-A32D-7DD22FD694E3 +keywords: ["Driver Verifier", "Verifier"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a Bug Check When Driver Verifier is Enabled + + +[Driver Verifier](http://go.microsoft.com/fwlink/p?LinkID=268663) detects driver errors at run time. You can use Driver Verifier along with the [**!analyze**](-analyze.md) debugger command to detect and display information about errors in your driver. + +In Windows 8, [Driver Verifier](http://go.microsoft.com/fwlink/p?LinkID=268663) has been enhanced with new features, including [DDI Compliance Checking](http://go.microsoft.com/fwlink/p?LinkID=268676). Here we give an example that demonstrates DDI Compliance Checking. + +Use the following procedure to get set up. + +1. Establish a kernel-mode debugging session between a host and target computer. +2. Install your driver on the target computer. +3. On the target computer, open a Command Prompt window and enter the command **verifier**. Use [Driver Verifier Manager](http://go.microsoft.com/fwlink/p?LinkID=268659) to enable Driver Verifier for your driver. +4. Reboot the target computer. + +When Driver Verifier detects an error, it generates a bug check. Then Windows breaks into the debugger and displays a brief description of the error. Here is an example where Driver Verifier generates Bug Check [**DRIVER\_VERIFIER\_DETECTED\_VIOLATION (C4)**](bug-check-0xc4--driver-verifier-detected-violation.md). + +``` +Driver Verifier: Extension abort with Error Code 0x20005 +Error String ExAcquireFastMutex should only be called at IRQL <= APC_LEVEL. + +*** Fatal System Error: 0x000000c4 + (0x0000000000020005,0xFFFFF88000E16F50,0x0000000000000000,0x0000000000000000) + +Break instruction exception - code 80000003 (first chance) + +A fatal system error has occurred. +Debugger entered on first try; Bugcheck callbacks have not been invoked. + +A fatal system error has occurred. + +nt!DbgBreakPointWithStatus: +fffff802`a40ef930 cc int 3 +``` + +In the debugger, enter [**!analyze -v**](-analyze.md) to get a detailed description of the error. + +``` +0: kd> !analyze -v +Connected to Windows 8 9200 x64 target at (Thu Oct 11 13:48:31.270 2012 (UTC - 7:00)), ptr64 TRUE +Loading Kernel Symbols +............................................................... +................................................................ +................... +Loading User Symbols +.................................................. +Loading unloaded module list +............ +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +DRIVER_VERIFIER_DETECTED_VIOLATION (c4) +A device driver attempting to corrupt the system has been caught. This is +because the driver was specified in the registry as being suspect (by the +administrator) and the kernel has enabled substantial checking of this driver. +If the driver attempts to corrupt the system, bugchecks 0xC4, 0xC1 and 0xA will +be among the most commonly seen crashes. +Arguments: +Arg1: 0000000000020005, ID of the 'IrqlExApcLte1' rule that was violated. +Arg2: fffff88000e16f50, A pointer to the string describing the violated rule condition. +Arg3: 0000000000000000, An optional pointer to the rule state variable(s). +Arg4: 0000000000000000, Reserved (unused) + +## Debugging Details: + +... + +DV_VIOLATED_CONDITION: ExAcquireFastMutex should only be called at IRQL <= APC_LEVEL. + +DV_MSDN_LINK: !url http://go.microsoft.com/fwlink/p/?linkid=216022 + +DV_RULE_INFO: !ruleinfo 0x20005 + +BUGCHECK_STR: 0xc4_IrqlExApcLte1_XDV + +DEFAULT_BUCKET_ID: WIN8_DRIVER_FAULT + +PROCESS_NAME: TiWorker.exe + +CURRENT_IRQL: 9 +``` + +In the preceding output, you can see the name and description of the rule, **IrqlExApcLte1**, that was violated, and you can click a link to the reference page that describes the rule: . You can also click a debugger command link, **!ruleinfo 0x20005**, to get information about the rule. In this case, the rule states that you cannot call [ExAcquireFastMutex](http://go.microsoft.com/fwlink/p?LinkID=268628) if the interrupt request level (IRQL) is greater than APC\_LEVEL. The output shows that the current IRQL is 9, and in wdm.h you can see that APC\_LEVEL has a value of 1. For more information about IRQLs, see [Managing Hardware Priorities](http://go.microsoft.com/fwlink/p?LinkID=268625). + +The output of [**!analyze -v**](-analyze.md) continues with a stack trace and information about the code that caused the error. In the following output, you can see that the **OnInterrupt** routine in MyDriver.sys called [ExAcquireFastMutex](http://go.microsoft.com/fwlink/p?LinkID=268628). **OnInterrupt** is an interrupt service routine that runs at an IRQL greater than APC\_LEVEL, so it is a violation for this routine to call [ExAcquireFastMutex](http://go.microsoft.com/fwlink/p?LinkID=268628). + +``` +LAST_CONTROL_TRANSFER: from fffff802a41f00ea to fffff802a40ef930 + +STACK_TEXT: +... : nt!DbgBreakPointWithStatus ... +... : nt!KiBugCheckDebugBreak+0x12 ... +... : nt!KeBugCheck2+0x79f ... +... : nt!KeBugCheckEx+0x104 ... +... : VerifierExt!SLIC_abort+0x47 ... +... : VerifierExt!SLIC_ExAcquireFastMutex_entry_irqlexapclte1+0x25 ... +... : VerifierExt!ExAcquireFastMutex_wrapper+0x1a ... +... : nt!ViExAcquireFastMutexCommon+0x1d ... +... : nt!VerifierExAcquireFastMutex+0x1a ... +... : MyDriver!OnInterrupt+0x69 ... +... : nt!KiScanInterruptObjectList+0x6f ... +... : nt!KiChainedDispatch+0x19a ... +... + +STACK_COMMAND: kb + +FOLLOWUP_IP: +MyDriver!OnInterrupt+69 ... +fffff880`16306649 4c8d0510040000 lea r8,[MyDriver! ?? ::FNODOBFM::`string' (fffff880`16306a60)] + +FAULTING_SOURCE_LINE: c:\MyDriverwdm03\cpp\MyDriver\pnp.c + +FAULTING_SOURCE_FILE: c:\MyDriverwdm03\cpp\MyDriver\pnp.c + +FAULTING_SOURCE_LINE_NUMBER: 26 + +FAULTING_SOURCE_CODE: + 22: if(1 == interruptStatus) + 23: { + 24: ... + 25: ExAcquireFastMutex( &(fdoExt->fastMutex) ); +> 26: ... + 27: ExReleaseFastMutex( &(fdoExt->fastMutex) ); + 28: ... + 29: return TRUE; + 30: } + 31: else + + +SYMBOL_STACK_INDEX: 9 + +SYMBOL_NAME: MyDriver!OnInterrupt+69 + +FOLLOWUP_NAME: ... + +MODULE_NAME: MyDriver + +IMAGE_NAME: MyDriver.sys + +DEBUG_FLR_IMAGE_TIMESTAMP: 50772f37 + +BUCKET_ID_FUNC_OFFSET: 69 + +FAILURE_BUCKET_ID: 0xc4_IrqlExApcLte1_XDV_VRF_MyDriver!OnInterrupt + +BUCKET_ID: 0xc4_IrqlExApcLte1_XDV_VRF_MyDriver!OnInterrupt +``` + +## Related topics + + +[Static Driver Verifier](http://go.microsoft.com/fwlink/p?LinkID=268668) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Handling%20a%20Bug%20Check%20When%20Driver%20Verifier%20is%20Enabled%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/handling-file-pointers.md b/windows-driver-docs-pr/debugger/handling-file-pointers.md new file mode 100644 index 0000000000..2d4e6874eb --- /dev/null +++ b/windows-driver-docs-pr/debugger/handling-file-pointers.md @@ -0,0 +1,28 @@ +--- +title: Handling File Pointers +description: Handling File Pointers +ms.assetid: 9bc03ae0-3e03-492a-b8d7-760eeb18106a +keywords: ["SymProxy, file pointers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling File Pointers + + +A UNC symbol store supports placing the actual files to be served in a separate location, with the client code finding the location of the files through file pointers. These pointers are generated in the symbol store using SymStore with the **/p** option. This handling is supported with other HTTP-based symbol stores only if the file pointers point to a UNC location that is directly accessible by the client. When SymProxy is loaded into the Web server, file-pointer handling is automatically enhanced. The client no longer needs to be able to directly access the target files because SymProxy serves them through the HTTP interface. + +Because this feature is automatically applied, an option exists to turn it off in case you must use the proxy for serving some files and regular file pointer implementation for others. To do this, create a REG\_DWORD called "NoFilePointerHandler" in **HKLM\\Software\\Microsoft\\Symbol Server**. Set this value to 1 (or anything other than 0) to turn off the internal file pointer handler in SymProxy. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Handling%20File%20Pointers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/help---about.md b/windows-driver-docs-pr/debugger/help---about.md new file mode 100644 index 0000000000..d54637b2fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/help---about.md @@ -0,0 +1,31 @@ +--- +title: Help About +description: Help About +ms.assetid: 0eb9b790-00aa-4070-b854-cf936745313a +keywords: ["Help About", "WinDbg, version information"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Help | About + + +## + + +Click **About** on the **Help** menu to open a message box that shows the version information for the WinDbg binaries that you are using. + +Click **OK** to close this message box. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Help%20|%20About%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/help---contents.md b/windows-driver-docs-pr/debugger/help---contents.md new file mode 100644 index 0000000000..954e746ab1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/help---contents.md @@ -0,0 +1,35 @@ +--- +title: Help Contents +description: Help Contents +ms.assetid: 9a37d67b-2c1d-4dc7-af15-7b006ab0f621 +keywords: ["Help Contents", "help file, Help Contents"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Help | Contents + + +## + + +Click **Contents** on the **Help** menu to open the **Contents** tab in this Help documentation. + +This command is equivalent to pressing F1. + +### Additional Information + +For more information about how to use this Help file, see [Using the Help File](using-the-help-documentation.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Help%20|%20Contents%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/help---index.md b/windows-driver-docs-pr/debugger/help---index.md new file mode 100644 index 0000000000..c81b1646cd --- /dev/null +++ b/windows-driver-docs-pr/debugger/help---index.md @@ -0,0 +1,33 @@ +--- +title: Help Index +description: Help Index +ms.assetid: 72d2baa5-83f5-4033-ba57-63d8b0acc5a3 +keywords: ["Help Index", "help file, Help Index"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Help | Index + + +## + + +Click **Index** on the **Help** menu to open the **Index** tab in this Help documentation. + +### Additional Information + +For more information about how to use this Help file, see [Using the Help File](using-the-help-documentation.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Help%20|%20Index%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/help---search.md b/windows-driver-docs-pr/debugger/help---search.md new file mode 100644 index 0000000000..f05955cfc2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/help---search.md @@ -0,0 +1,33 @@ +--- +title: Help Search +description: Help Search +ms.assetid: 27cc64cc-50bc-4f3b-8346-d95fb3ffdf9c +keywords: ["Help Search", "help file, Help Search"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Help | Search + + +## + + +Click **Search** on the **Help** menu to open the **Search** tab in this Help documentation. + +### Additional Information + +For more information about how to use this Help file, see [Using the Help File](using-the-help-documentation.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Help%20|%20Search%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/help-menu.md b/windows-driver-docs-pr/debugger/help-menu.md new file mode 100644 index 0000000000..bf697be377 --- /dev/null +++ b/windows-driver-docs-pr/debugger/help-menu.md @@ -0,0 +1,41 @@ +--- +title: Help Menu +description: Help Menu +ms.assetid: 088a8ff1-1a86-4a8f-a5f9-8adf55e6119c +keywords: ["Help Menu (complete listing)", "graphical interface, help menu"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Help Menu + + +## + + +This section describes the following commands on the **Help** menu of WinDbg: + +[Help | Contents](help---contents.md) + +**Help | Window** + +**Help | Selection** + +[Help | Index](help---index.md) + +[Help | Search](help---search.md) + +[Help | About](help---about.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Help%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/hid-extensions.md b/windows-driver-docs-pr/debugger/hid-extensions.md new file mode 100644 index 0000000000..cd5aaac1ce --- /dev/null +++ b/windows-driver-docs-pr/debugger/hid-extensions.md @@ -0,0 +1,79 @@ +--- +title: HID Extensions +description: This section describes the Human Interface Device (HID) debugger extension commands. +ms.assetid: 796DB87B-1E04-40FA-90F9-699EE7032B3C +--- + +# HID Extensions + + +This section describes the Human Interface Device (HID) debugger extension commands. + +The HID debugger extension commands are implemented in Hidkd.dll. To load the HID commands, enter **.load hidkd.dll** in the debugger. + +## Getting started with the HID extensions + + +To start debugging a HID issue, enter the [**!hidtree**](-hidkd-hidtree.md) command. The **!hidtree** command displays a list of commands and addresses that you can use to investigate device objects, preparsed HID data, and HID report descriptors. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[!hidkd.help](-hidkd-help.md)

The [!hidkd.help](-hidkd-help.md) command displays help for the HID debugger extension commands.

[!hidkd.hidfdo](-hidkd-hidfdo.md)

The [!hidkd.hidfdo](-hidkd-hidfdo.md) command displays HID information associated with a functional device object (FDO).

[!hidkd.hidpdo](-hidkd-hidpdo.md)

The [!hidkd.hidpdo](-hidkd-hidpdo.md) command displays HID information associated with a physical device object (PDO).

[!hidkd.hidtree](-hidkd-hidtree.md)

The [!hidkd.hidtree](-hidkd-hidtree.md) command displays a list of all device nodes that have a HID function driver along with their child nodes. The child nodes have a physical device object (PDO) that was created by the parent node's HID function driver.

[!hidkd.hidppd](-hidkd-hidppd.md)

The [!hidkd.hidppd](-hidkd-hidppd.md) command displays HID preparsed data.

[!hidkd.hidrd](-hidkd-hidrd.md)

The [!hidkd.hidrd](-hidkd-hidrd.md) command displays a HID report descriptor in both raw and parsed format.

+ +  + +## Related topics + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +[Specialized Extension Commands](specialized-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20HID%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/how-the-debugger-recognizes-symbols.md b/windows-driver-docs-pr/debugger/how-the-debugger-recognizes-symbols.md new file mode 100644 index 0000000000..4d4a571079 --- /dev/null +++ b/windows-driver-docs-pr/debugger/how-the-debugger-recognizes-symbols.md @@ -0,0 +1,29 @@ +--- +title: How the Debugger Recognizes Symbols +description: How the Debugger Recognizes Symbols +ms.assetid: 2e96fd22-a1e9-4a25-8904-4db78948e5be +--- + +# How the Debugger Recognizes Symbols + + +## + + +This section includes: + +[Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md) + +[Symbol Options](symbol-options.md) + +[Symbol Status Abbreviations](symbol-status-abbreviations.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20How%20the%20Debugger%20Recognizes%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/http-sites-and-unc-shares.md b/windows-driver-docs-pr/debugger/http-sites-and-unc-shares.md new file mode 100644 index 0000000000..48f3974654 --- /dev/null +++ b/windows-driver-docs-pr/debugger/http-sites-and-unc-shares.md @@ -0,0 +1,32 @@ +--- +title: HTTP Sites and UNC Shares +description: HTTP Sites and UNC Shares +ms.assetid: a1b79242-41ba-4c95-89fd-dbb7f70b24eb +--- + +# HTTP Sites and UNC Shares + + +It is possible to set up a Web site that provides version-specific source to WinDbg using SrcSrv. Such a mechanism does not provide dynamic extraction of the source files from version control, but it is a valuable feature because it allows you to set the source path of WinDbg to a single unified path that provides source from many versions of many modules, instead of having to set separate paths for each debugging scenario. This is not of interest to debugging clients that have direct access to the actual version control systems but can be of assistance to those wanting to provide secure HTTP-based access to source from remote locations. The Web sites in question can be secured through HTTPS and smart cards, if desired. This same technique can be used to provide source files through a simple UNC share. + +This section includes: + +[Setting Up the Web Site](setting-up-the-web-site.md) + +[Extracting Source Files](extracting-source-files.md) + +[Modifying the Source Indexing Streams in a .pdb File](modifying-the-source-indexing-streams-in-a--pdb-file.md) + +[Using UNC Shares](using-unc-shares.md) + +[Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control](using-http-sites-and-unc-shares-in-conjuction-with-regular-version-con.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20HTTP%20Sites%20and%20UNC%20Shares%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/http-symbol-stores.md b/windows-driver-docs-pr/debugger/http-symbol-stores.md new file mode 100644 index 0000000000..6d3bd03996 --- /dev/null +++ b/windows-driver-docs-pr/debugger/http-symbol-stores.md @@ -0,0 +1,204 @@ +--- +title: HTTP Symbol Stores +description: HTTP Symbol Stores +ms.assetid: b7dd1f3c-0135-4b69-9d70-b7cbf37fa969 +keywords: ["HTTP symbol stores"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HTTP Symbol Stores + + +## + + +By using the SRV protocol supported through symsrv.dll (shipped with debugger), the symbol store can be accessed using HTTP (instead of just UNC/SMB). + +HTTP is commonly used instead of SMB when a firewall doesn’t allow SMB between the client and the server. Production and Lab environments are good examples of this. + +An HTTP symbol server can’t be a downstream store in a symbol path chain due to its read-only nature. Symbol Server Proxy (ISAPI Filter) works around this limit. SymProxy downloads the missing files to the server’s file system using preconfigured upstream symbol stores. The filter downloads the file to the file system, allowing IIS to download the file to the client, thereby restoring the concept of symbol store chaining. Refer to [SymProxy](symproxy.md) for more information. + +Configuring IIS as a symbol store is relatively easy as the symbol files are just served as static files. The only non-default setting is the configuration of the MIME Types to allow the download of the symbol files as binary streams. This can be done by using a “\*” wildcard applied to the virtual directory of the symbol folder. + +In order to make a symbol store accessible over the Internet, you must configure both the directories containing the symbol files and Internet Information Services (IIS). + +**Note**  Because of the way IIS will be configured to serve symbol files, it is not recommended that the same server instance be used for any other purpose. Typically the desired security settings for a symbol server will not make sense for other uses, for example for an external facing commerce server. Make sure that the sample configuration described here makes sense for your environment and adapt it as appropriate for your specific needs. + +  + +### Creating the Symbol Directory + +Begin by selecting the directory you will use as your symbol store. In our examples, we call this directory c:\\symstore and the name of the server on the network is \\SymMachineName. + +For details on how to populate your symbol store, see [SymStore](symstore.md) and [Symbol Store Folder Tree](symbol-store-folder-tree.md). + +### Configuring IIS + +Internet Information Services (IIS) must be configured to serve the symbols by creating a virtual directory and configuring MIME types. After this has been done, the authentication method may be chosen. + +**To create a virtual directory** + +1. From **Administrative Tools** open **Internet Information Services (IIS) Manager**. + +2. Navigate to **Web Sites**. + +3. Right-click **Default Web Site** or the name of the site being used and select **Add Virtual Directory…**. + +4. Type **Symbols** for **Alias** and click **Next**. + + For ease of administration, it’s recommended that the same name be used for the Folder, Share and Virtual Directory. + +5. For the **Path** enter **c:\\SymStore** and click **Next**. + +6. Click **OK** to finish the adding the virtual directory. + +Perform the subdirectory configuration process once for the server. Note that this is a global setting and will effect applications not hosted in the root folder of a site. + +**Subdirectory Configuration** + +1. Navigate to **\[Computer\]**. + +2. Open the **Configuration Editor**. + +3. Navigate to **system ApplicationHost/sites**. + +4. Expand **virtualDirectoryDefaults**. + +5. Set **allowSubDirConfig** to *False*. + +Perform this process once for the server. Note that this is a global setting and will effect applications not hosted in the root folder of a site. + +**Optionaly Make the Symbol Files Browseable** + +1. Navigate to **\[Computer\] | Sites | \[Web Site\] | Symbols**. + +2. Double click **Directory Browsing** in the center pane. + +3. Click **Enable** in the right pane. + +The MIME Type for the downloaded content needs to be set to application/octet-stream to allow all symbols files to be delivered by IIS. + +**Configuring MIME types** + +1. Right-click the **Symbols** virtual directory and choose **Properties**. + +2. Select **HTTP Headers**. + +3. Click **MIME Types**. + +4. Click **New**. + +5. For **Extension**, type **\***. + +6. For **MIME type**, type **application/octet-stream**. + +7. To exit the **MIME Types** dialog box, click **OK**. + +8. To exit **Symbols Properties**, click **OK**. + +You can edit the web.config file to configure MIME types for Symbols. This approach clears the inherited MIME Types and adds a catch-all wild card \* MIME Type. This approach may be necessary when MIME types are being inherited in certain IIS configurations. + +**Using web.config to configure MIME types** + +1. Edit the web.config file as shown here. + + ``` + + + + + + + + + + + ``` + +2. Restart IIS. + +IIS is now ready to serve symbol files of all types from the symbol store. + +## Configuring Authentication + + +It is possible to configure IIS to use “Integrated Windows Authentication” so that clients (windbg.exe for example) can automatically authenticate against IIS without prompting the end-user for credentials. + +**Note**  Only configure Windows Authentication on IIS to control access to the symbol server if that is appropriate for your environment. There are other security options available to further control access to IIS if that is required for your environment. + +  + +**To configure the authentication method as Anonymous** + +1. Launch the **Internet Information Services (IIS) Manager**. + +2. Navigate to **\[Computer\] | Sites | \[Web Site\] | Symbols**. + +3. Double click **Authentication** in the center pane. + +4. Under **Authentication and access control** click **Edit**. + +5. Right click **Windows Authentication** and select **Enable**. + +6. For all other authentication providers, right click each provider and select **Disable**. + +7. Click **OK** to finish configuring authentication. + +If Window Authentication is not listed, use **Turn Windows features on and off** to enable the feature. The location of the feature is different in each version of Windows. In Windows 8.1/Windows 2012 R2, it is located under Internet Information Services | World Wide Web Services | Security. + +## Disable Kerberos Support + + +SymSrv.dll does not support Kerberos authentication when connecting to IIS. As such, Kerberos authentication must be disabled in IIS and NTLM needs to be set as the only Windows Authentication protocol. + +**Note**  Only disable Kerberos security if that is appropriate for your environment. + +  + +**Disable Kerberos Support Using appcmd.exe** + +1. Open a Command Prompt window + +2. To disable Kerberos and force the use of NTLM, use this command: + + ``` + appcmd.exe set config -section:system.webServer/security/authentication/windowsAuthentication /+"providers.[value='NTLM']" /commit:apphost + ``` + +3. To return to the default value with Kerberos enabled, use this command: + + ``` + appcmd.exe set config -section:system.webServer/security/authentication/windowsAuthentication /+"providers.[value='Negotiate,NTLM']" /commit:apphost + ``` + +## Configuring SymSrv Client Authentication Prompts + + +When SymSrv receives authentication requests, the debugger can either display the authentication dialog box or automatically refuse the request, depending on how it has been configured. You can configure this behavior using !sym prompts on|off. For example to turn prompts on, use this command. + +``` +!sym prompts on +``` + +To check the current setting, use this command. + +``` +!sym prompts +``` + +For more information see [**!sym**](-sym.md) and [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md) on MSDN. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20HTTP%20Symbol%20Stores%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/i.md b/windows-driver-docs-pr/debugger/i.md new file mode 100644 index 0000000000..cdb212d38b --- /dev/null +++ b/windows-driver-docs-pr/debugger/i.md @@ -0,0 +1,64 @@ +--- +title: I (Windows Debugger Glossary) +description: Glossary page - H +Robots: noindex, nofollow +ms.assetid: 4415522d-6ea3-42f6-9acc-0e3ceaa36dc7 +--- + +# I + + +**I/O Request Packet (IRP)** +A data structure used to represent an I/O request and control its processing. An IRP structure consists of a header and one or more stack locations. + +**image** +An executable, DLL, or driver that Windows has loaded as part of a user-mode process or the Windows kernel. + +See also image file. + +**image file** +The file from which an image was loaded. + +**implicit process** +In kernel-mode debugging, the process used to determine which virtual address space to use when performing virtual to physical address translation. When an event occurs, the implicit process is set to the event process. + +See also implicit thread. + +For more information, see [Threads and Processes](threads-and-processes.md). + +**implicit thread** +In kernel-mode debugging, the thread used to determine some of the target's registers, including frame offset and instruction offset. When an event occurs, the implicit thread is set to the event thread. + +**inaccessible** +A debugging session is *inaccessible* when all the targets are executing. + +**initial breakpoint** +A breakpoint that automatically occurs near the beginning of a debugging session, after a reboot, or after a target application is restarted. + +For more information, see [Using Breakpoints](using-breakpoints.md). + +**input callback objects** +Instances of the [IDebugInputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550785) interface which have been registered with a client. Whenever the debugger engine requires input it asks the input callbacks to provide it. + +See also output callbacks. + +For more information, see [Using AMLI Debugger Commands](using-amli-debugger-commands.md). + +**input callbacks** +See input callback objects. + +**interrupt** +A condition that disrupts normal command execution and transfers control to an interrupt handler. I/O devices requiring service from the processor usually initiate interrupts. + +**Interrupt Request Level (IRQL)** +The priority ranking of an interrupt. Each processor has an IRQL setting that threads can raise or lower. Interrupts that occur at or below the processor's IRQL setting are masked and will not interfere with the current operation. Interrupts that occur above the processor's IRQL setting take precedence over the current operation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20I%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ib--iw--id--input-from-port-.md b/windows-driver-docs-pr/debugger/ib--iw--id--input-from-port-.md new file mode 100644 index 0000000000..14144192ee --- /dev/null +++ b/windows-driver-docs-pr/debugger/ib--iw--id--input-from-port-.md @@ -0,0 +1,82 @@ +--- +title: ib, iw, id (Input from Port) +description: The ib, iw, and id commands read and display a byte, word, or double word from the selected port. +ms.assetid: 68f9e0c2-3cfd-46e1-a513-5a96c93de63c +keywords: ["ib, iw, id (Input from Port) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ib, iw, id (Input from Port) +api_type: +- NA +--- + +# ib, iw, id (Input from Port) + + +The **ib**, **iw**, and **id** commands read and display a byte, word, or double word from the selected port. + +``` +ib Address +iw Address +id Address +``` + +## Parameters + + + *Address* +The address of the port. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

x86-based computer only

+ +  + +Remarks +------- + +The **ib** command reads a single byte, the **iw** command reads a word, and the **id** command reads a double word. + +Make sure that reading an I/O port does not affect the behavior of the device that you are reading from. Some devices change state after a read-only port has been read. You should also not try to read a word or double-word from a port that does not allow values of this length. + +## See also + + +[**ob, od, ow (Output to Port)**](ob--ow--od--output-to-port-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ib,%20iw,%20id%20%28Input%20from%20Port%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/identifying-the-caller-from-the-server-thread.md b/windows-driver-docs-pr/debugger/identifying-the-caller-from-the-server-thread.md new file mode 100644 index 0000000000..d82ebedfea --- /dev/null +++ b/windows-driver-docs-pr/debugger/identifying-the-caller-from-the-server-thread.md @@ -0,0 +1,85 @@ +--- +title: Identifying the Caller From the Server Thread +description: Identifying the Caller From the Server Thread +ms.assetid: d19dc242-1043-4e61-9fcb-eadac0ab63c8 +keywords: ["RPC debugging, identifying the caller"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Identifying the Caller From the Server Thread + + +## + + +It is possible to determine what made a given RPC call, even if the only information you have is the server thread that serviced the call. + +This can be very useful -- for example, to find out who passed invalid parameters to an RPC call. + +Depending on which protocol sequence is used by this particular call, you can get varying degrees of detail. Some protocols (such as NetBios) do not have this information at all. + +**Identifying the caller from the server thread** + +1. Start a user-mode debugger with the server thread as the target. + +2. Get the process ID by using the [**| (Process Status)**](---process-status-.md) command: + ``` + 0:001> | + 0 id: 3d4 name: rtsvr.exe + ``` + +3. Get the active calls in this process by using the [**!rpcexts.getcallinfo**](-rpcexts-getcallinfo.md) extension. (See the reference page for an explanation of the syntax.) You need to supply the process ID of 0x3D4: + + ``` + 0:001> !rpcexts.getcallinfo 0 0 FFFF 3d4 + Searching for call info ... + PID CELL ID ST PNO IFSTART THRDCELL CALLFLAG CALLID LASTTIME CONN/CLN + ---------------------------------------------------------------------------- + 03d4 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 00a1aced 0000.0003 + ``` + + Look for calls with status 02 or 01 (dispatched or active). In this example, the process only has one call. If there were more, you would have to use the [**!rpcexts.getdbgcell**](-rpcexts-getdbgcell.md) extension with the cell number in the THRDCELL column. This would allow you to examine the thread IDs so you could determine which call you were interested in. + +4. After you know which call you are interested in, look at the cell number in the CONN/CLN column. This is the cell ID of the connection object. In this case, the cell number is 0000.0003. Pass this cell number and the process ID to **!rpcexts.getdbgcell**: + ``` + 0:001> !rpcexts.getdbgcell 3d4 0.3 + Getting cell info ... + Connection + Connection flags: Exclusive + Authentication Level: Default + Authentication Service: None + Last Transmit Fragment Size: 24 (0x6F56D) + Endpoint for the connection: 0x0.1 + Last send time (in seconds since boot):10595.565 (0x2963.235) + Last receive time (in seconds since boot):10595.565 (0x2963.235) + Getting endpoint info ... + Process object for caller is 0xFF9DF5F0 + ``` + +This extension will display all the information available about the client of this connection. The amount of actual information will vary, depending on the transport being used. + +In this example, local named pipes are being used as the transport and the process object address of the caller is displayed. If you attach a kernel debugger (or start a local kernel debugger), you can use the [**!process**](-process.md) extension to interpret this process address. + +If LRPC is used as the transport, the process ID and thread ID of the caller will be displayed. + +If TCP is used as the transport, the IP address of the caller will be displayed. + +If remote named pipes are used as the transport, no information will be available. + +**Note**   The previous example shows how to find the client thread if you know the server thread. For an example of the reverse technique, see [Analyzing a Stuck Call Problem](analyzing-a-stuck-call-problem.md). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Identifying%20the%20Caller%20From%20the%20Server%20Thread%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-dataflows.png b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-dataflows.png new file mode 100644 index 0000000000..3a69288d8f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-dataflows.png differ diff --git a/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-networkinterfaces.png b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-networkinterfaces.png new file mode 100644 index 0000000000..499a36cebf Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem-networkinterfaces.png differ diff --git a/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem.png b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem.png new file mode 100644 index 0000000000..b7079ede61 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-activesystem.png differ diff --git a/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-crashdump.png b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-crashdump.png new file mode 100644 index 0000000000..4d33c38973 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/!ndiskd-netreport-crashdump.png differ diff --git a/windows-driver-docs-pr/debugger/images/bug-check-example-blue-screen-page-fault.png b/windows-driver-docs-pr/debugger/images/bug-check-example-blue-screen-page-fault.png new file mode 100644 index 0000000000..5ba4ccd02e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/bug-check-example-blue-screen-page-fault.png differ diff --git a/windows-driver-docs-pr/debugger/images/clientservertarget.png b/windows-driver-docs-pr/debugger/images/clientservertarget.png new file mode 100644 index 0000000000..ded111a91e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/clientservertarget.png differ diff --git a/windows-driver-docs-pr/debugger/images/configfortest01.png b/windows-driver-docs-pr/debugger/images/configfortest01.png new file mode 100644 index 0000000000..242d949df1 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/configfortest01.png differ diff --git a/windows-driver-docs-pr/debugger/images/configfortest02.png b/windows-driver-docs-pr/debugger/images/configfortest02.png new file mode 100644 index 0000000000..bc04d67a84 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/configfortest02.png differ diff --git a/windows-driver-docs-pr/debugger/images/crashpanel.png b/windows-driver-docs-pr/debugger/images/crashpanel.png new file mode 100644 index 0000000000..23bfea4241 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/crashpanel.png differ diff --git a/windows-driver-docs-pr/debugger/images/debugfa01.png b/windows-driver-docs-pr/debugger/images/debugfa01.png new file mode 100644 index 0000000000..58cdadb83b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debugfa01.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-echo-deviceadd.png b/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-echo-deviceadd.png new file mode 100644 index 0000000000..0ccafed448 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-echo-deviceadd.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-end-deviceadd.png b/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-end-deviceadd.png new file mode 100644 index 0000000000..29eca8778a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-breakpoint-end-deviceadd.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-device-manager-echo.png b/windows-driver-docs-pr/debugger/images/debuglab-image-device-manager-echo.png new file mode 100644 index 0000000000..3a63835f28 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-device-manager-echo.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-device-node-tree.png b/windows-driver-docs-pr/debugger/images/debuglab-image-device-node-tree.png new file mode 100644 index 0000000000..dee290889c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-device-node-tree.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-display-callstacks.png b/windows-driver-docs-pr/debugger/images/debuglab-image-display-callstacks.png new file mode 100644 index 0000000000..ba90b64f3c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-display-callstacks.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-display-variables.png b/windows-driver-docs-pr/debugger/images/debuglab-image-display-variables.png new file mode 100644 index 0000000000..d5bc922d6e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-display-variables.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-echo-visual-studio.png b/windows-driver-docs-pr/debugger/images/debuglab-image-echo-visual-studio.png new file mode 100644 index 0000000000..eac0b3d690 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-echo-visual-studio.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-driver-signing.png b/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-driver-signing.png new file mode 100644 index 0000000000..c91782cbe4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-driver-signing.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-properties.png b/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-properties.png new file mode 100644 index 0000000000..7f76ad1643 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-echoapp-properties.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-find-dialog.png b/windows-driver-docs-pr/debugger/images/debuglab-image-find-dialog.png new file mode 100644 index 0000000000..e1278df917 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-find-dialog.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-firewall-dialog-box.png b/windows-driver-docs-pr/debugger/images/debuglab-image-firewall-dialog-box.png new file mode 100644 index 0000000000..0c1c34ac62 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-firewall-dialog-box.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-github.png b/windows-driver-docs-pr/debugger/images/debuglab-image-github.png new file mode 100644 index 0000000000..faf110b678 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-github.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-install-security-warning.png b/windows-driver-docs-pr/debugger/images/debuglab-image-install-security-warning.png new file mode 100644 index 0000000000..c47e1cc548 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-install-security-warning.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-prefer-dml-help.png b/windows-driver-docs-pr/debugger/images/debuglab-image-prefer-dml-help.png new file mode 100644 index 0000000000..6c3b7471f2 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-prefer-dml-help.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-targethostdrawing1.png b/windows-driver-docs-pr/debugger/images/debuglab-image-targethostdrawing1.png new file mode 100644 index 0000000000..128ec3189f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-targethostdrawing1.png differ diff --git a/windows-driver-docs-pr/debugger/images/debuglab-image-winddbg-hh.png b/windows-driver-docs-pr/debugger/images/debuglab-image-winddbg-hh.png new file mode 100644 index 0000000000..27da6ec8fc Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/debuglab-image-winddbg-hh.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlcommands01.png b/windows-driver-docs-pr/debugger/images/dmlcommands01.png new file mode 100644 index 0000000000..9333176902 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlcommands01.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlcommands02.png b/windows-driver-docs-pr/debugger/images/dmlcommands02.png new file mode 100644 index 0000000000..0dcb0b7d17 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlcommands02.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlcommands03.png b/windows-driver-docs-pr/debugger/images/dmlcommands03.png new file mode 100644 index 0000000000..1dae0dc50a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlcommands03.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlcommands04.png b/windows-driver-docs-pr/debugger/images/dmlcommands04.png new file mode 100644 index 0000000000..d6475cf1c6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlcommands04.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlflow01.png b/windows-driver-docs-pr/debugger/images/dmlflow01.png new file mode 100644 index 0000000000..507d3c6f8f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlflow01.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlproc01.png b/windows-driver-docs-pr/debugger/images/dmlproc01.png new file mode 100644 index 0000000000..8cfd17fed6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlproc01.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlproc02.png b/windows-driver-docs-pr/debugger/images/dmlproc02.png new file mode 100644 index 0000000000..e4ce4eafe3 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlproc02.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlstart01.png b/windows-driver-docs-pr/debugger/images/dmlstart01.png new file mode 100644 index 0000000000..f2b1ea0f7a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlstart01.png differ diff --git a/windows-driver-docs-pr/debugger/images/dmlstart02.png b/windows-driver-docs-pr/debugger/images/dmlstart02.png new file mode 100644 index 0000000000..8d7154eb79 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dmlstart02.png differ diff --git a/windows-driver-docs-pr/debugger/images/dx-grid-example.png b/windows-driver-docs-pr/debugger/images/dx-grid-example.png new file mode 100644 index 0000000000..b5c1ec7ae7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/dx-grid-example.png differ diff --git a/windows-driver-docs-pr/debugger/images/extmatch01.png b/windows-driver-docs-pr/debugger/images/extmatch01.png new file mode 100644 index 0000000000..6e3c70be64 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/extmatch01.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-debugger.png b/windows-driver-docs-pr/debugger/images/gflags-debugger.png new file mode 100644 index 0000000000..15d78edffd Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-debugger.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-image.png b/windows-driver-docs-pr/debugger/images/gflags-image.png new file mode 100644 index 0000000000..09c8d763cf Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-image.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-kernel.png b/windows-driver-docs-pr/debugger/images/gflags-kernel.png new file mode 100644 index 0000000000..97129c80eb Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-kernel.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-launch.png b/windows-driver-docs-pr/debugger/images/gflags-launch.png new file mode 100644 index 0000000000..290f01b14e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-launch.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-obj.png b/windows-driver-docs-pr/debugger/images/gflags-obj.png new file mode 100644 index 0000000000..870e755eae Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-obj.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-overruns.png b/windows-driver-docs-pr/debugger/images/gflags-overruns.png new file mode 100644 index 0000000000..cd3b75e11e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-overruns.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-registry.png b/windows-driver-docs-pr/debugger/images/gflags-registry.png new file mode 100644 index 0000000000..8f1d557a80 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-registry.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-specialpool-hex.png b/windows-driver-docs-pr/debugger/images/gflags-specialpool-hex.png new file mode 100644 index 0000000000..11cd217548 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-specialpool-hex.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-specialpool-size.png b/windows-driver-docs-pr/debugger/images/gflags-specialpool-size.png new file mode 100644 index 0000000000..158fcf4f51 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-specialpool-size.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflags-specialpool-text.png b/windows-driver-docs-pr/debugger/images/gflags-specialpool-text.png new file mode 100644 index 0000000000..a2fcf9b0b1 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflags-specialpool-text.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit01.png b/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit01.png new file mode 100644 index 0000000000..f48004e779 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit01.png differ diff --git a/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit02.png b/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit02.png new file mode 100644 index 0000000000..23fa12fe27 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/gflagssilentprocessexit02.png differ diff --git a/windows-driver-docs-pr/debugger/images/hidkd01.png b/windows-driver-docs-pr/debugger/images/hidkd01.png new file mode 100644 index 0000000000..73e8e2d66f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/hidkd01.png differ diff --git a/windows-driver-docs-pr/debugger/images/optimizedcode01.png b/windows-driver-docs-pr/debugger/images/optimizedcode01.png new file mode 100644 index 0000000000..d9d99d0717 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/optimizedcode01.png differ diff --git a/windows-driver-docs-pr/debugger/images/optimizedcode02.png b/windows-driver-docs-pr/debugger/images/optimizedcode02.png new file mode 100644 index 0000000000..9d7a5852e4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/optimizedcode02.png differ diff --git a/windows-driver-docs-pr/debugger/images/printf01.png b/windows-driver-docs-pr/debugger/images/printf01.png new file mode 100644 index 0000000000..f8501ddaa4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/printf01.png differ diff --git a/windows-driver-docs-pr/debugger/images/printf02.png b/windows-driver-docs-pr/debugger/images/printf02.png new file mode 100644 index 0000000000..0b0b12d8a2 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/printf02.png differ diff --git a/windows-driver-docs-pr/debugger/images/serialoverusb01.png b/windows-driver-docs-pr/debugger/images/serialoverusb01.png new file mode 100644 index 0000000000..22c600bf63 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/serialoverusb01.png differ diff --git a/windows-driver-docs-pr/debugger/images/setup1394vs.png b/windows-driver-docs-pr/debugger/images/setup1394vs.png new file mode 100644 index 0000000000..c48fefc503 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setup1394vs.png differ diff --git a/windows-driver-docs-pr/debugger/images/setupnetvs.png b/windows-driver-docs-pr/debugger/images/setupnetvs.png new file mode 100644 index 0000000000..b2a1122dc1 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setupnetvs.png differ diff --git a/windows-driver-docs-pr/debugger/images/setupserialoverusbvs.png b/windows-driver-docs-pr/debugger/images/setupserialoverusbvs.png new file mode 100644 index 0000000000..2affdb69b6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setupserialoverusbvs.png differ diff --git a/windows-driver-docs-pr/debugger/images/setupserialvs.png b/windows-driver-docs-pr/debugger/images/setupserialvs.png new file mode 100644 index 0000000000..ceb07c7332 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setupserialvs.png differ diff --git a/windows-driver-docs-pr/debugger/images/setupusb2vs.png b/windows-driver-docs-pr/debugger/images/setupusb2vs.png new file mode 100644 index 0000000000..d3cdde129f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setupusb2vs.png differ diff --git a/windows-driver-docs-pr/debugger/images/setupusbvs.png b/windows-driver-docs-pr/debugger/images/setupusbvs.png new file mode 100644 index 0000000000..0832bc69f7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/setupusbvs.png differ diff --git a/windows-driver-docs-pr/debugger/images/sharkscovedebugconnector.png b/windows-driver-docs-pr/debugger/images/sharkscovedebugconnector.png new file mode 100644 index 0000000000..a4a0409191 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sharkscovedebugconnector.png differ diff --git a/windows-driver-docs-pr/debugger/images/sourcecodedebuggingvs01.png b/windows-driver-docs-pr/debugger/images/sourcecodedebuggingvs01.png new file mode 100644 index 0000000000..1edfce600f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sourcecodedebuggingvs01.png differ diff --git a/windows-driver-docs-pr/debugger/images/statusbar3.png b/windows-driver-docs-pr/debugger/images/statusbar3.png new file mode 100644 index 0000000000..eb83c01e44 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/statusbar3.png differ diff --git a/windows-driver-docs-pr/debugger/images/symproxy-configuration.png b/windows-driver-docs-pr/debugger/images/symproxy-configuration.png new file mode 100644 index 0000000000..8c9e47b508 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/symproxy-configuration.png differ diff --git a/windows-driver-docs-pr/debugger/images/symproxy-registry.png b/windows-driver-docs-pr/debugger/images/symproxy-registry.png new file mode 100644 index 0000000000..ade3d37c56 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/symproxy-registry.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-device-manager.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-device-manager.png new file mode 100644 index 0000000000..9f86833c6a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-device-manager.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-disassembly-window.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-disassembly-window.png new file mode 100644 index 0000000000..dd4078a76e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-disassembly-window.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-display-registers.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-display-registers.png new file mode 100644 index 0000000000..12e3674f56 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-display-registers.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-find-dialog.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-find-dialog.png new file mode 100644 index 0000000000..35378110fc Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-find-dialog.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-memory-display.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-memory-display.png new file mode 100644 index 0000000000..e3d3e4faf4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-audio-memory-display.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-call-stack.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-call-stack.png new file mode 100644 index 0000000000..bac704b7ed Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-call-stack.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-display-variables.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-display-variables.png new file mode 100644 index 0000000000..9039e08086 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-display-variables.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-github.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-github.png new file mode 100644 index 0000000000..9d4cc6099b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-github.png differ diff --git a/windows-driver-docs-pr/debugger/images/sysvad-lab-visual-studio-solution.png b/windows-driver-docs-pr/debugger/images/sysvad-lab-visual-studio-solution.png new file mode 100644 index 0000000000..71ee2e3ebd Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/sysvad-lab-visual-studio-solution.png differ diff --git a/windows-driver-docs-pr/debugger/images/targethost1.png b/windows-driver-docs-pr/debugger/images/targethost1.png new file mode 100644 index 0000000000..128ec3189f Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/targethost1.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbasm.png b/windows-driver-docs-pr/debugger/images/tbasm.png new file mode 100644 index 0000000000..67f73f62f6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbasm.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbbp.png b/windows-driver-docs-pr/debugger/images/tbbp.png new file mode 100644 index 0000000000..de22f98224 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbbp.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbbreak.png b/windows-driver-docs-pr/debugger/images/tbbreak.png new file mode 100644 index 0000000000..97ad2e54a7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbbreak.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbcall.png b/windows-driver-docs-pr/debugger/images/tbcall.png new file mode 100644 index 0000000000..5aa7815f9b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbcall.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbcmd.png b/windows-driver-docs-pr/debugger/images/tbcmd.png new file mode 100644 index 0000000000..3b7b03fa9a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbcmd.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbcopy.png b/windows-driver-docs-pr/debugger/images/tbcopy.png new file mode 100644 index 0000000000..19c14d1e5d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbcopy.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbcursor.png b/windows-driver-docs-pr/debugger/images/tbcursor.png new file mode 100644 index 0000000000..b86a35e94b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbcursor.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbcut.png b/windows-driver-docs-pr/debugger/images/tbcut.png new file mode 100644 index 0000000000..dda420db47 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbcut.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbdisasm2.png b/windows-driver-docs-pr/debugger/images/tbdisasm2.png new file mode 100644 index 0000000000..af13a78e91 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbdisasm2.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbfont.png b/windows-driver-docs-pr/debugger/images/tbfont.png new file mode 100644 index 0000000000..08787b5671 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbfont.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbgo.png b/windows-driver-docs-pr/debugger/images/tbgo.png new file mode 100644 index 0000000000..3f815a3e9c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbgo.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbinto.png b/windows-driver-docs-pr/debugger/images/tbinto.png new file mode 100644 index 0000000000..d26d59ce3a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbinto.png differ diff --git a/windows-driver-docs-pr/debugger/images/tblocal.png b/windows-driver-docs-pr/debugger/images/tblocal.png new file mode 100644 index 0000000000..70a41f63f5 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tblocal.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbmem.png b/windows-driver-docs-pr/debugger/images/tbmem.png new file mode 100644 index 0000000000..c1040423c3 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbmem.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbopen.png b/windows-driver-docs-pr/debugger/images/tbopen.png new file mode 100644 index 0000000000..255cda0fa1 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbopen.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbopt.png b/windows-driver-docs-pr/debugger/images/tbopt.png new file mode 100644 index 0000000000..628e5b91c9 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbopt.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbout.png b/windows-driver-docs-pr/debugger/images/tbout.png new file mode 100644 index 0000000000..b44baa4bd7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbout.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbover.png b/windows-driver-docs-pr/debugger/images/tbover.png new file mode 100644 index 0000000000..3250da2cea Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbover.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbpaste.png b/windows-driver-docs-pr/debugger/images/tbpaste.png new file mode 100644 index 0000000000..1d9794e3fc Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbpaste.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbreg.png b/windows-driver-docs-pr/debugger/images/tbreg.png new file mode 100644 index 0000000000..089ed64597 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbreg.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbrestart.png b/windows-driver-docs-pr/debugger/images/tbrestart.png new file mode 100644 index 0000000000..2324b22aea Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbrestart.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbspad.png b/windows-driver-docs-pr/debugger/images/tbspad.png new file mode 100644 index 0000000000..3d59057720 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbspad.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbsrc.png b/windows-driver-docs-pr/debugger/images/tbsrc.png new file mode 100644 index 0000000000..8767b84813 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbsrc.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbsrcasm.png b/windows-driver-docs-pr/debugger/images/tbsrcasm.png new file mode 100644 index 0000000000..f3e35c1473 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbsrcasm.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbstop.png b/windows-driver-docs-pr/debugger/images/tbstop.png new file mode 100644 index 0000000000..46a377d54d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbstop.png differ diff --git a/windows-driver-docs-pr/debugger/images/tbwatch.png b/windows-driver-docs-pr/debugger/images/tbwatch.png new file mode 100644 index 0000000000..3573ec1d23 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/tbwatch.png differ diff --git a/windows-driver-docs-pr/debugger/images/theme-multimon.jpg b/windows-driver-docs-pr/debugger/images/theme-multimon.jpg new file mode 100644 index 0000000000..d8881c07c7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/theme-multimon.jpg differ diff --git a/windows-driver-docs-pr/debugger/images/theme-srcdisassembly.jpg b/windows-driver-docs-pr/debugger/images/theme-srcdisassembly.jpg new file mode 100644 index 0000000000..06797aa8d4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/theme-srcdisassembly.jpg differ diff --git a/windows-driver-docs-pr/debugger/images/theme-standard.jpg b/windows-driver-docs-pr/debugger/images/theme-standard.jpg new file mode 100644 index 0000000000..9374a9cb30 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/theme-standard.jpg differ diff --git a/windows-driver-docs-pr/debugger/images/theme-standardvs.jpg b/windows-driver-docs-pr/debugger/images/theme-standardvs.jpg new file mode 100644 index 0000000000..f9725f1d42 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/theme-standardvs.jpg differ diff --git a/windows-driver-docs-pr/debugger/images/toolbar4.png b/windows-driver-docs-pr/debugger/images/toolbar4.png new file mode 100644 index 0000000000..554d30c75b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/toolbar4.png differ diff --git a/windows-driver-docs-pr/debugger/images/ucxcontrollerlist01.png b/windows-driver-docs-pr/debugger/images/ucxcontrollerlist01.png new file mode 100644 index 0000000000..999fe2265b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/ucxcontrollerlist01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usb2tree01.png b/windows-driver-docs-pr/debugger/images/usb2tree01.png new file mode 100644 index 0000000000..c2ce1c71b6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usb2tree01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usb3structures01.png b/windows-driver-docs-pr/debugger/images/usb3structures01.png new file mode 100644 index 0000000000..309d7606ff Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usb3structures01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usb3structures02.png b/windows-driver-docs-pr/debugger/images/usb3structures02.png new file mode 100644 index 0000000000..85ed6b309e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usb3structures02.png differ diff --git a/windows-driver-docs-pr/debugger/images/usb3tree01.png b/windows-driver-docs-pr/debugger/images/usb3tree01.png new file mode 100644 index 0000000000..dec1f18b17 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usb3tree01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usbkd01.png b/windows-driver-docs-pr/debugger/images/usbkd01.png new file mode 100644 index 0000000000..b9ae75149c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usbkd01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usbtree01.png b/windows-driver-docs-pr/debugger/images/usbtree01.png new file mode 100644 index 0000000000..ac050c11e9 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usbtree01.png differ diff --git a/windows-driver-docs-pr/debugger/images/usbview01.png b/windows-driver-docs-pr/debugger/images/usbview01.png new file mode 100644 index 0000000000..f7fe035dba Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/usbview01.png differ diff --git a/windows-driver-docs-pr/debugger/images/virtualmemorydialog.png b/windows-driver-docs-pr/debugger/images/virtualmemorydialog.png new file mode 100644 index 0000000000..c40ffd442a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/virtualmemorydialog.png differ diff --git a/windows-driver-docs-pr/debugger/images/wdfumtriage2.png b/windows-driver-docs-pr/debugger/images/wdfumtriage2.png new file mode 100644 index 0000000000..6f284643b7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/wdfumtriage2.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbggetstart01.png b/windows-driver-docs-pr/debugger/images/windbggetstart01.png new file mode 100644 index 0000000000..eed1fa4e2d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbggetstart01.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbggetstart02.png b/windows-driver-docs-pr/debugger/images/windbggetstart02.png new file mode 100644 index 0000000000..930aed659c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbggetstart02.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbggetstart03.png b/windows-driver-docs-pr/debugger/images/windbggetstart03.png new file mode 100644 index 0000000000..52db386690 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbggetstart03.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-attach-to-a-process.png b/windows-driver-docs-pr/debugger/images/windbgx-attach-to-a-process.png new file mode 100644 index 0000000000..02591fe64d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-attach-to-a-process.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-attach-to-kernel.png b/windows-driver-docs-pr/debugger/images/windbgx-attach-to-kernel.png new file mode 100644 index 0000000000..4c7b3bc805 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-attach-to-kernel.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-menu.png new file mode 100644 index 0000000000..9c9e260700 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-window.png b/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-window.png new file mode 100644 index 0000000000..d9e335b4ef Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-breakpoints-window.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-explore-window.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-explore-window.png new file mode 100644 index 0000000000..3da5eba9ab Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-explore-window.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-menu.png new file mode 100644 index 0000000000..6d4bb05dde Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-new-model-dialog.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-new-model-dialog.png new file mode 100644 index 0000000000..058510c3f0 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-new-model-dialog.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-pnp-device.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-pnp-device.png new file mode 100644 index 0000000000..8f8ae75fe7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-pnp-device.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads-grid.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads-grid.png new file mode 100644 index 0000000000..819d45187e Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads-grid.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads.png b/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads.png new file mode 100644 index 0000000000..3616caaaec Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-data-model-process-threads.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-disassembly.png b/windows-driver-docs-pr/debugger/images/windbgx-disassembly.png new file mode 100644 index 0000000000..e356899689 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-disassembly.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-feedback.png b/windows-driver-docs-pr/debugger/images/windbgx-feedback.png new file mode 100644 index 0000000000..cabce6cfdf Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-feedback.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-home-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-home-menu.png new file mode 100644 index 0000000000..3ea220e942 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-home-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-javascript-new-script.png b/windows-driver-docs-pr/debugger/images/windbgx-javascript-new-script.png new file mode 100644 index 0000000000..092f285e69 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-javascript-new-script.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-launch-app-package.png b/windows-driver-docs-pr/debugger/images/windbgx-launch-app-package.png new file mode 100644 index 0000000000..4a27e8bb41 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-launch-app-package.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-launch-executable-advanced.png b/windows-driver-docs-pr/debugger/images/windbgx-launch-executable-advanced.png new file mode 100644 index 0000000000..891af49220 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-launch-executable-advanced.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-locals-window.png b/windows-driver-docs-pr/debugger/images/windbgx-locals-window.png new file mode 100644 index 0000000000..6e1702dd99 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-locals-window.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-main-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-main-menu.png new file mode 100644 index 0000000000..e608bc5c29 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-main-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-preview-logo.png b/windows-driver-docs-pr/debugger/images/windbgx-preview-logo.png new file mode 100644 index 0000000000..3a427fc5c6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-preview-logo.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-ribbon-home-menu-alt-keys.png b/windows-driver-docs-pr/debugger/images/windbgx-ribbon-home-menu-alt-keys.png new file mode 100644 index 0000000000..114a58b7a3 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-ribbon-home-menu-alt-keys.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-scripting-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-scripting-menu.png new file mode 100644 index 0000000000..90cecf2a3c Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-scripting-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-settings-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-settings-menu.png new file mode 100644 index 0000000000..4e5deb6556 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-settings-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-source-windows-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-source-windows-menu.png new file mode 100644 index 0000000000..a32ecce723 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-source-windows-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-start-debugging-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-start-debugging-menu.png new file mode 100644 index 0000000000..f195aeb2a4 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-start-debugging-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-start-up-options.png b/windows-driver-docs-pr/debugger/images/windbgx-start-up-options.png new file mode 100644 index 0000000000..6b34f88e75 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-start-up-options.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-store-app-install.png b/windows-driver-docs-pr/debugger/images/windbgx-store-app-install.png new file mode 100644 index 0000000000..70b503e5d0 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-store-app-install.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-threads-window.png b/windows-driver-docs-pr/debugger/images/windbgx-threads-window.png new file mode 100644 index 0000000000..fe3bbde968 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-threads-window.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-view-menu.png b/windows-driver-docs-pr/debugger/images/windbgx-view-menu.png new file mode 100644 index 0000000000..a6ead6e99d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-view-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/windbgx-workspace-right-click.png b/windows-driver-docs-pr/debugger/images/windbgx-workspace-right-click.png new file mode 100644 index 0000000000..667a2a051b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windbgx-workspace-right-click.png differ diff --git a/windows-driver-docs-pr/debugger/images/windock.png b/windows-driver-docs-pr/debugger/images/windock.png new file mode 100644 index 0000000000..d7f725218a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/windock.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-calls.png b/windows-driver-docs-pr/debugger/images/window-calls.png new file mode 100644 index 0000000000..a38b1e254b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-calls.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-command-browser-icon.png b/windows-driver-docs-pr/debugger/images/window-command-browser-icon.png new file mode 100644 index 0000000000..5ee232ca62 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-command-browser-icon.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-command.png b/windows-driver-docs-pr/debugger/images/window-command.png new file mode 100644 index 0000000000..28a2d8b2f0 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-command.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-commandbrowser.png b/windows-driver-docs-pr/debugger/images/window-commandbrowser.png new file mode 100644 index 0000000000..062dcc6d76 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-commandbrowser.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-disassembly.png b/windows-driver-docs-pr/debugger/images/window-disassembly.png new file mode 100644 index 0000000000..c6cf3f2f2d Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-disassembly.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-locals-menu-icon.png b/windows-driver-docs-pr/debugger/images/window-locals-menu-icon.png new file mode 100644 index 0000000000..3ab1958eab Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-locals-menu-icon.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-locals.png b/windows-driver-docs-pr/debugger/images/window-locals.png new file mode 100644 index 0000000000..addea440dc Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-locals.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-memory.png b/windows-driver-docs-pr/debugger/images/window-memory.png new file mode 100644 index 0000000000..0111777cd7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-memory.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-processes-threads.png b/windows-driver-docs-pr/debugger/images/window-processes-threads.png new file mode 100644 index 0000000000..befb12c807 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-processes-threads.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-prth.png b/windows-driver-docs-pr/debugger/images/window-prth.png new file mode 100644 index 0000000000..b61e8ab7f8 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-prth.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-registers.png b/windows-driver-docs-pr/debugger/images/window-registers.png new file mode 100644 index 0000000000..5b97df15f6 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-registers.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-scratchpad.png b/windows-driver-docs-pr/debugger/images/window-scratchpad.png new file mode 100644 index 0000000000..809dc4dc4a Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-scratchpad.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-source-icon.png b/windows-driver-docs-pr/debugger/images/window-source-icon.png new file mode 100644 index 0000000000..57ed3392ad Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-source-icon.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-source.png b/windows-driver-docs-pr/debugger/images/window-source.png new file mode 100644 index 0000000000..e2fc090ce7 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-source.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-watch-menu.png b/windows-driver-docs-pr/debugger/images/window-watch-menu.png new file mode 100644 index 0000000000..bae9ee440b Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-watch-menu.png differ diff --git a/windows-driver-docs-pr/debugger/images/window-watch.png b/windows-driver-docs-pr/debugger/images/window-watch.png new file mode 100644 index 0000000000..89f2651c48 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/window-watch.png differ diff --git a/windows-driver-docs-pr/debugger/images/xhcidumpall01.png b/windows-driver-docs-pr/debugger/images/xhcidumpall01.png new file mode 100644 index 0000000000..3d582efa78 Binary files /dev/null and b/windows-driver-docs-pr/debugger/images/xhcidumpall01.png differ diff --git a/windows-driver-docs-pr/debugger/important-breakpoints-for-analyzing-reproducible-problems.md b/windows-driver-docs-pr/debugger/important-breakpoints-for-analyzing-reproducible-problems.md new file mode 100644 index 0000000000..0b3d53dd34 --- /dev/null +++ b/windows-driver-docs-pr/debugger/important-breakpoints-for-analyzing-reproducible-problems.md @@ -0,0 +1,39 @@ +--- +title: Important Breakpoints for Analyzing Reproducible Problems +description: Important Breakpoints for Analyzing Reproducible Problems +ms.assetid: 3f501bbe-990a-4f46-ba88-c1fc4b73537f +keywords: ["SCSI Miniport Debugging, breakpoints and reproducible problems"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Important Breakpoints for Analyzing Reproducible Problems + + +## + + +When debugging a SCSI miniport driver, there are three routines in which it is useful to set a breakpoint: + +- **scsiport!scsiportnotification** + +- **scsiport!spstartiosynchronized** + +- **miniport!HwStartIo** + +The routine **scsiport!scsiportnotification** is called right after a request is sent to the miniport. Thus, if you set a breakpoint in **scsiport!scsiportnotification** and then run a stack backtrace using [**kb 3**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md), you can determine whether the miniport is receiving and completing requests. If the first parameter is zero, the request has been completed. If the first parameter is nonzero, the third parameter is the address of the SCSI request block (SRB) that is not being completed, and you can use the [**!minipkd.srb**](-minipkd-srb.md) extension to further analyze the situation. + +Placing a breakpoint in either **scsiport!spstartiosynchronized** or **miniport!HwStartIo** will cause a break just prior to sending a request to the miniport. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Important%20Breakpoints%20for%20Analyzing%20Reproducible%20Problems%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/index.md b/windows-driver-docs-pr/debugger/index.md new file mode 100644 index 0000000000..b802216d1e --- /dev/null +++ b/windows-driver-docs-pr/debugger/index.md @@ -0,0 +1,104 @@ +--- +title: Debugging Tools for Windows (WinDbg, KD, CDB, NTSD) +description: Start here for an overview of Debugging Tools for Windows. This tool set includes WinDbg and other debuggers. +ms.assetid: 938ef180-84de-442f-9b6c-1138c2fc8d5a +keywords: ["Debugging Tools for Windows", "Windows debugging", "Windows Debugger", "Kernel debugging", "Kernel debugger", "WinDbg"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Debugging Tools for Windows (WinDbg, KD, CDB, NTSD) + + +April 2017 + +Start here for an overview of Debugging Tools for Windows. This tool set includes WinDbg and other debuggers. + +## 3 ways to get Debugging Tools for Windows + + +- **As part of the WDK** + +    Install Microsoft Visual Studio and then install the Windows Driver Kit (WDK). Debugging Tools for Windows is included in the WDK. You can [get the integrated environment here](https://go.microsoft.com/fwlink/p?LinkID=239721). + +- **As part of the Windows SDK** + + Install the Windows Software Development Kit (SDK). Debugging Tools for Windows is included in the Windows SDK. You can [get the Windows SDK here](https://go.microsoft.com/fwlink/p?LinkID=271979). + +- **As a standalone tool set** + + If you want to download only Debugging Tools for Windows, [install the Windows SDK](https://go.microsoft.com/fwlink/p?LinkID=271979), and, during the installation, select the **Debugging Tools for Windows** box and clear all the other boxes. + +## Getting Started with Windows Debugging + + +To get started with Windows debugging, see [Getting Started with Windows Debugging](getting-started-with-windows-debugging.md). + +To get started with debugging kernel mode drivers, see [Debug Universal Drivers - Step by Step Lab (Echo Kernel-Mode)](debug-universal-drivers---step-by-step-lab--echo-kernel-mode-.md). This is a step by step lab that shows how to use WinDbg to debug the sample KMDF echo driver. + +## Debugging environments + + +After you install Visual Studio and the WDK, you'll have six available [debugging environments](debuggers-in-the-debugging-tools-for-windows-package.md). All of these debugging environments provide user interfaces for the same underlying debugging engine, which is implemented in dbgeng.dll. This debugging engine is called the *Windows debugger*, and the six debugging environments are collectively called the *Windows debuggers*. + +**Note**  Visual Studio includes its own debugging environment and debugging engine, which together are called the *Visual Studio debugger*. For information on debugging in Visual Studio, see [Visual Studio debugger](https://go.microsoft.com/fwlink/p/?LinkID=238333). If you are looking to debug managed code such as C#, using the Visual Studio is often easiest way to get started. + +  + +## Windows debuggers + + +The Windows debuggers can run on x86-based, x64-based, or ARM-based processors, and they can debug code that's running on x86-based, x64-based, or ARM-based processors. Sometimes the debugger and the code being debugged run on the same computer, but other times the debugger and the code being debugged run on separate computers. In either case, the computer that's running the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. The Windows debuggers support the following versions of Windows for both the host and target computers. + +- Windows 10 and Windows Server 2016 + +- Windows 8.1 and Windows Server 2012 R2 + +- Windows 8 and Windows Server 2012 + +- Windows 7 and Windows Server 2008 R2 + +## Symbols and Symbol Files + + +Symbol files hold a variety of data which are not actually needed when running the binaries, but are very useful when debugging code. For more information about creating and using symbol files, see [Symbols for Windows debugging (WinDbg, KD, CDB, NTSD)](symbols.md). + +## Blue Screens and crash dump files + + +If Windows stops working and displays a blue screen, the computer has shut down abruptly to protect itself from data loss and displays a bug check code. For more information, see [Bug Checks (Blue Screens)](bug-checks--blue-screens-.md). You analyze crash dump files that are created when Windows shuts down by using WinDbg and other Windows debuggers. For more information, see [Crash dump analysis using the Windows debuggers (WinDbg)](crash-dump-files.md). + +## Tools and utilities + + +In addition to the debuggers, Debugging Tools for Windows includes a set of tools that are useful for debugging. For a full list of the tools, see [Tools Included in Debugging Tools for Windows](extra-tools.md). + +## Additional documentation + + +For additional information related to Debugging Tools for Windows, see [Debugging Resources](debugging-resources.md). For information on what's new in Windows 10, see [Debugging Tools for Windows: New for Windows 10](debugging-tools-for-windows--new-for-windows-10.md). + +## In this section + + +- [Getting Started with Windows Debugging](getting-started-with-windows-debugging.md) +- [Debugging Resources](debugging-resources.md) +- [Debugger Operation](debugger-operation-win8.md) +- [Debugging Techniques](debugging-techniques.md) +- [Symbols](symbols.md) +- [Crash Dump Analysis](crash-dump-files.md) +- [Bug Checks (Blue Screens)](bug-checks--blue-screens-.md) +- [Debugger Reference](debugger-reference.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Tools%20for%20Windows%20%28WinDbg,%20KD,%20CDB,%20NTSD%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/initial-breakpoint.md b/windows-driver-docs-pr/debugger/initial-breakpoint.md new file mode 100644 index 0000000000..28f55c4f9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/initial-breakpoint.md @@ -0,0 +1,34 @@ +--- +title: Initial Breakpoint +description: Initial Breakpoint +ms.assetid: c7fda1f0-bbfb-41d8-b3c9-568f2f0a74e1 +keywords: ["initial breakpoint", "breakpoints, initial breakpoint"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Initial Breakpoint + + +When the debugger starts a new target application, an initial breakpoint automatically occurs after the main image and all statically-linked DLLs are loaded before any DLL initialization routines are called. + +When the debugger attaches to an existing user-mode application, an initial [breakpoint](using-breakpoints.md) occurs immediately. + +The **-g** command-line option causes WinDbg or CDB to ignore the initial breakpoint. You can automatically execute a command at this point. For more information about this situation, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +If you want to start a new target and break into it when the execution of the actual application is about to begin, do not use the **-g** option. Instead, let the initial breakpoint occur. After the debugger is active, set a breakpoint on the **main** or **winmain** routine and then use the [**g (Go)**](g--go-.md) command. All of the initialization procedures then run, and the application stops when execution of the main application is about to begin. + +For more information about automatic breakpoints in kernel mode, see [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Initial%20Breakpoint%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/input-and-output.md b/windows-driver-docs-pr/debugger/input-and-output.md new file mode 100644 index 0000000000..a4a50c4016 --- /dev/null +++ b/windows-driver-docs-pr/debugger/input-and-output.md @@ -0,0 +1,38 @@ +--- +title: Input and Output +description: Input and Output +ms.assetid: 78e181c1-c577-49ca-910b-d2e8db2495b5 +keywords: ["Debugger Engine, input and output", "input and output", "output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Input and Output + + +The input and output facilities of the [debugger engine](introduction.md#debugger-engine) can be used for interactive debugger operation and logging. The input usually represents commands and responses that are typed by the user, and the output usually represents information presented to the user or sent to log files. + +The debugger engine maintains an *input stream* and an *output stream*. Input can be requested from the input stream, and output sent to the output stream. + +When the [**Input**](https://msdn.microsoft.com/library/windows/hardware/ff550962) method is called to request input from the engine's input stream, the engine will call all the registered [input callbacks](using-input-and-output.md#input-callbacks) to inform them that it is waiting for input. It then waits for the input callbacks to provide the input by calling the [**ReturnInput**](https://msdn.microsoft.com/library/windows/hardware/ff554600) method. + +When output is sent to the engine's output stream, the engine will call the registered [output callbacks](using-input-and-output.md#output-callbacks) passing the output to them. When sending output to the output stream, it can be filtered by the client object; in which case, only output callbacks that are registered with particular client objects will receive the output. + +The input and output streams are transparently available to the remote clients. Remote clients can request input and send output to the engine's input and output stream, and the engine will call the callbacks registered with remote clients to request input or send output. + +### Additional Information + +For details about using input and output, see [Using Input and Output](using-input-and-output.md). For more information about client objects and input and output callbacks, see [Client Objects](client-objects.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Input%20and%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/installing-symproxy.md b/windows-driver-docs-pr/debugger/installing-symproxy.md new file mode 100644 index 0000000000..c5ef01e33a --- /dev/null +++ b/windows-driver-docs-pr/debugger/installing-symproxy.md @@ -0,0 +1,50 @@ +--- +title: Installing SymProxy +description: Installing SymProxy +ms.assetid: 63633de7-d254-415d-bf06-c0e81bd03e74 +keywords: ["SymProxy, installation"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Installing SymProxy + + +## Summary of installation tasks + + +The following summarizes the tasks to install and configure SymProxy. + +- The SymProxy files need to be copied to the %WINDIR%\\system32\\inetsrv folder for IIS. This task is discussed below. + +- The registry needs to be configured for SymProxy. For more information see [Configuring the Registry](configuring-the-registry.md). + +- The manifest needs to be registered as Performance Counters and ETW events, and the Event Log needs to be configured. + +- IIS needs to be configured. For more information, see [Choosing Network Security Credentials](choosing-network-security-credentials.md) and [Configuring IIS for SymProxy](configuring-iis-for-symproxy.md). + +- Confirm that SymProxy is running as expected using the status page. For more information see [Checking and Updating Status](checking-and-updating-status.md). + +These steps can be automated using the Install.cmd file. For more information, see [SymProxy Automated Installation](symproxy-automated-installation.md). + +## Copy the SymProxy files to IIS + + +The SymProxy files are included in the Debuggers directory of the Windows Driver Kit. For example this is the location of the 64 bit files for Windows 10 kit. C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\symproxy. + +To install SymProxy on the server, copy symproxy.dll, symsrv.dll and symproxy.man to %WINDIR%\\system32\\inetsrv. + +In order to prevent problems that could occur in accessing the Microsoft Symbol Store at http://msdl.microsoft.com/downloads/symbols, create a blank file called %WINDIR%\\system32\\inetsrv\\symsrv.yes. The contents of this file are not important. When symsrv.yes file is present, it automatically accepts the EULA for the Microsoft Public Symbol Store. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Installing%20SymProxy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/installing-windows-symbol-files.md b/windows-driver-docs-pr/debugger/installing-windows-symbol-files.md new file mode 100644 index 0000000000..d79535f196 --- /dev/null +++ b/windows-driver-docs-pr/debugger/installing-windows-symbol-files.md @@ -0,0 +1,89 @@ +--- +title: Installing Windows Symbol Files +description: Installing Windows Symbol Files +ms.assetid: fbafb14c-9b92-47c5-9954-5c5ba2301c47 +keywords: ["symbols, Windows", "symbols, user-mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Installing Windows Symbol Files + + +## + + +Before you debug the Windows kernel or a driver or application running on Windows, you need access to the proper symbol files. + +If you have access to the internet while your debugger is running, you may wish to use Microsoft's public symbol store. You can connect to this with one simple use of the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command. For full details, see [Microsoft Public Symbols](microsoft-public-symbols.md). + +If you plan to install symbols manually, it is crucial that you remember this basic rule: the symbol files on the host computer are required to match the version of Windows installed on the target computer. If you are planning to do a kernel mode debug of a Windows XP target from a Windows 2000 host, you need to install the Windows XP symbol files on the Windows 2000 system. If you plan to perform user-mode debugging on the same computer as the target application, then install the symbol files that match the version of Windows running on that system. If you are analyzing a memory dump file, then the version of symbol files needed on the debug computer are those that match the version of the operating system that produced the dump file, not necessarily those matching the version of the operating system on the machine running the debug session. + +**Note**   If you are going to use your host computer to debug several different target computers, you may need symbols for more than one build of Windows. In this case, be sure to install each symbol collection in a distinct directory path. + +  + +If you are debugging from a Windows computer attached to a network, it may be useful to install symbols for a variety of different builds on a network server. Microsoft debuggers will accept a network path (*\\\\server\\share\\dir*) as a valid symbol directory path. This avoids the need for each debugging computer on the network to install the symbol files separately. + +Symbol files stored on a crashed target computer are not usable by the debugger on the host computer. + +**To install symbol files for Windows XP or later** + +1. Make sure you have at least 1000 MB of available space on the disk drive of the host computer. + +2. Open the [Windows Symbols](http://go.microsoft.com/fwlink/p/?linkid=17363) Web site in your internet browser. + +3. Follow the links to download the appropriate symbol package. + +**To install symbol files for Windows 2000 from the Web** + +1. Make sure you have at least 1000 MB of available space on the disk drive of the host computer. + +2. Open the [Windows Symbols](http://go.microsoft.com/fwlink/p/?linkid=17363) Web site in your internet browser. + +3. Follow the links to download Windows 2000 symbols. + +**To install symbol files for Windows 2000 from the Support CD** + +1. Make sure you have at least 500 MB of available space on the disk drive of the host computer. + +2. Insert the Windows 2000 Customer Support Diagnostics CD. + +3. Click **Install Symbols**. + +4. Select either **Install Retail Symbols** (free build) or **Install Debug Symbols** (checked build). The symbols must match the version of the operating system being debugged. + +5. Enter the path where the symbols are to be stored, or accept the default path. The default path is %windir%\\symbols. + +### Sequence of Symbol File Installation + +If you intend to keep your symbols in a single directory tree, the installation sequence of symbol files should mirror the installation sequence of operating system files: + +**To install the symbol files in correct sequence** + +1. Install the operating system symbol files. + +2. Install the symbol files for the currently installed Service Pack (if any). + +3. Install the symbol files for any Hot Fixes that were installed after the current Service Pack was installed (if any). + +However, a superior setup would be to install the symbols from each Service Pack and Hot Fix in a separate directory tree, and put all these directories in your symbol search path. The debugger will then find the proper symbols. (Since the symbol files have date and time stamps, the debugger will be able to tell which are the most recent.) See [Symbol Path](symbol-path.md) for details. + +### Installing User-Mode Symbols + +If you are going to debug a user-mode application, you need to install the symbols for this application as well. + +You can debug an application if you have its symbols but not Windows symbols. However, your results will be much more limited. You will still be able to step through the application code, but any debugger activity which requires analysis of the kernel (such as getting a stack trace) is likely to fail. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Installing%20Windows%20Symbol%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/interacting-with-the-engine.md b/windows-driver-docs-pr/debugger/interacting-with-the-engine.md new file mode 100644 index 0000000000..554207399b --- /dev/null +++ b/windows-driver-docs-pr/debugger/interacting-with-the-engine.md @@ -0,0 +1,60 @@ +--- +title: Interacting with the Engine +description: Interacting with the Engine +ms.assetid: 80f5320f-ed34-4839-a16e-b3ff5d8edbfe +keywords: ["Debugger Engine API, use"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interacting with the Engine + + +### Commands and Expressions + +The debugger engine API provides methods to execute commands and evaluate expressions, like those typed into WinDbg's [Debugger Command Window](the-debugger-command-window.md). To execute a debugger command, use [**Execute**](https://msdn.microsoft.com/library/windows/hardware/ff543208). Or, to execute all of the commands in a file, use [**ExecuteCommandFile**](https://msdn.microsoft.com/library/windows/hardware/ff543215). + +The method [**Evaluate**](https://msdn.microsoft.com/library/windows/hardware/ff543046) will evaluate expressions using the C++ or MASM syntax. The syntax used by the debugger engine to evaluate expressions--such as in the **Evaluate** method--is given by [**GetExpressionSyntax**](https://msdn.microsoft.com/library/windows/hardware/ff546701) and can be changed using [**SetExpressionSyntaxByName**](https://msdn.microsoft.com/library/windows/hardware/ff556697) and [**SetExpressionSyntax**](https://msdn.microsoft.com/library/windows/hardware/ff556696). The number of different syntaxes that are recognized by the debugger is returned by [**GetNumberExpressionSyntaxes**](https://msdn.microsoft.com/library/windows/hardware/ff547913), and their names are returned by [**GetExpressionSyntaxNames**](https://msdn.microsoft.com/library/windows/hardware/ff546708). + +The type of value that is returned by **Evaluate** is determined by the symbols and constants used in the string that was evaluated. The value is contained in a [**DEBUG\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff541719) structure and can be cast to different types using [**CoerceValue**](https://msdn.microsoft.com/library/windows/hardware/ff539158) and [**CoerceValues**](https://msdn.microsoft.com/library/windows/hardware/ff539162). + +### Aliases + +*Aliases* are character strings that are automatically replaced with other character strings when used in debugger commands and expressions. For an overview of aliases, see [Using Aliases](using-aliases.md). The debugger engine has several classes of aliases. + +The *fixed-name aliases* are indexed by number and have the names **$u0**, **$u1**, ..., **$u9**. The values of these aliases can be set using the [**SetTextMacro**](https://msdn.microsoft.com/library/windows/hardware/ff556809) method and can be retrieved using [**GetTextMacro**](https://msdn.microsoft.com/library/windows/hardware/ff549270) method. + +The *automatic aliases* and *user-named aliases* can have any name. The automatic aliases are defined by the debugger engine and the user-named aliases are defined by the user through debugger commands or the debugger engine API. To define or remove a user-named alias, use the [**SetTextReplacement**](https://msdn.microsoft.com/library/windows/hardware/ff556818) method. The [**GetTextReplacement**](https://msdn.microsoft.com/library/windows/hardware/ff549280) method returns the name and value of an automatic alias or a user-named alias. All the user-named aliases can be removed using the [**RemoveTextReplacements**](https://msdn.microsoft.com/library/windows/hardware/ff554548) method. The [**GetNumberTextReplacements**](https://msdn.microsoft.com/library/windows/hardware/ff547988) method will return the number of user-name and automatic aliases; this can be used with **GetTextReplacement** to iterate over all these aliases. The [**OutputTextReplacements**](https://msdn.microsoft.com/library/windows/hardware/ff553268) method will print a list of all the user-named aliases, including their names and values. + +**Note**   if a user-named alias is given the same name as an automatic alias, the user-named alias will hide the automatic alias so that when retrieving the value of the alias by name, the user-named alias will be used. + +  + +### Engine Options + +The engine has a number of options that control its behavior. These options are listed in [**DEBUG\_ENGOPT\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541475). They are returned by [**GetEngineOptions**](https://msdn.microsoft.com/library/windows/hardware/ff546598) and can be set using [**SetEngineOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556670). Individual options can be set using [**AddEngineOptions**](https://msdn.microsoft.com/library/windows/hardware/ff537884) and unset using [**RemoveEngineOptions**](https://msdn.microsoft.com/library/windows/hardware/ff554491). + +### Interrupts + +An interrupt is a way to force a break into the debugger or to tell the engine to stop processing the current command, for example, by pressing Ctrl+Break in WinDbg. + +To request a break into the debugger, or to interrupt the debugger's current task, use [**SetInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff556722). To check if there has been an interrupt, use [**GetInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff546944). + +**Note**   When undertaking a long task from a debugger extension, it is recommended that the extension check **GetInterrupt** regularly and stop processing if an interrupt has been requested. + +  + +When requesting a break into the debugger, the engine might time out if it takes too long for the target to carry out the break-in. This can occur if the target is in a non-responsive state or if the break-in request is blocked or delayed by resource contention. The length of time the engine will wait is returned by [**GetInterruptTimeout**](https://msdn.microsoft.com/library/windows/hardware/ff546955) and can be set using [**SetInterruptTimeout**](https://msdn.microsoft.com/library/windows/hardware/ff556725). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Interacting%20with%20the%20Engine%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/interpreting-a-log-comparison.md b/windows-driver-docs-pr/debugger/interpreting-a-log-comparison.md new file mode 100644 index 0000000000..66c1270e1e --- /dev/null +++ b/windows-driver-docs-pr/debugger/interpreting-a-log-comparison.md @@ -0,0 +1,73 @@ +--- +title: Interpreting a Log Comparison +description: Interpreting a Log Comparison +ms.assetid: fe2acdd5-00aa-4414-a59e-e6203ad48363 +keywords: ["UMDH, interpreting a log comparison"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interpreting a Log Comparison + + +## + + +You can generate multiple User-Mode Dump Heap (UMDH) logs of the same process over time. Then, you can use UMDH to compare the logs and determine which call stack allocations have grown the most between trials. + +For example, the following command directs UMDH to compare two UMDH logs, Log1.txt and Log2.txt, and redirects the output to a third file, Compare.txt. + +``` +umdh -v Log1.txt Log2.txt > Compare.txt +``` + +The resulting Compare.txt file lists the call stacks recorded in each log and, for each stack, displays the change in heap allocations between the log files. + +For example, the following line from the file shows the change in allocation size for the functions in the call stack labeled "Backtrace00053." + +In Log1.txt, the calls in the stack accounts for 40,432 (0x9DF0) bytes, but in Log2.txt, the same call stack accounts for 61,712 (0xF110) bytes, a difference of 21,280 (0x5320) bytes. + +``` ++ 5320 (f110 - 9df0) 3a allocs BackTrace00053 +Total increase == 5320 +``` + +Following is the stack for the allocation: + +``` +ntdll!RtlDebugAllocateHeap+0x000000FD +ntdll!RtlAllocateHeapSlowly+0x0000005A +ntdll!RtlAllocateHeap+0x00000808 +MyApp!_heap_alloc_base+0x00000069 +MyApp!_heap_alloc_dbg+0x000001A2 +MyApp!_nh_malloc_dbg+0x00000023 +MyApp!_nh_malloc+0x00000016 +MyApp!operator new+0x0000000E +MyApp!LeakyFunc+0x0000001E +MyApp!main+0x0000002C +MyApp!mainCRTStartup+0x000000FC +KERNEL32!BaseProcessStart+0x0000003D +``` + +An examination of the call stack shows that the **LeakyFunc** function is allocating memory by using the Visual C++ run-time library. If examination of the other log files shows that the allocation grows over time, you might be able to conclude that memory allocated from the heap is not being freed. + +### Symbol Files for Analyzing a Log File + +Suppose you have two computers: a *logging computer* where you create a UMDH log and an *analysis computer* where you analyze the UMDH log. The symbol path on your analysis computer must point to the symbols for the version of Windows that was loaded on the logging computer at the time the log was made. Do not point the symbol path on the analysis computer to a symbol server. If you do, UMDH will retrieve symbols for the version of Windows that is running on the analysis computer, and UMDH will not display meaningful results. + +### See Also + +[Using UMDH to Find a User-Mode Memory Leak](using-umdh-to-find-a-user-mode-memory-leak.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Interpreting%20a%20Log%20Comparison%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/interpreting-a-umdh-log.md b/windows-driver-docs-pr/debugger/interpreting-a-umdh-log.md new file mode 100644 index 0000000000..80cba9ea76 --- /dev/null +++ b/windows-driver-docs-pr/debugger/interpreting-a-umdh-log.md @@ -0,0 +1,46 @@ +--- +title: Interpreting a UMDH Log +description: Interpreting a UMDH Log +ms.assetid: c5c74a3a-9598-4d89-8c5b-445138ae845f +keywords: ["UMDH, interpreting a UMDH log"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interpreting a UMDH Log + + +## + + +User-Mode Dump Heap (UMDH) log files display the list of heap allocations in the process and the stacks where the allocations were made. + +This example shows how to generate a log for a process that has ID 1204. The log is written to the file log1.txt. + +``` +umdh -p:1204 -f:log1.txt +``` + +The log file is not readable because the symbols are not resolved. UMDH resolves symbols when you analyze the log. This example shows how to analyze log1.txt and store the result in result.txt. + +``` +umdh -v log1.txt > result.txt +``` + +## Symbol Files for Analyzing a Log File + + +Suppose you have two computers: a *logging computer* where you create a UMDH log and an *analysis computer* where you analyze the UMDH log. The symbol path on your analysis computer must point to the symbols for the version of Windows that was loaded on the logging computer at the time the log was made. Do not point the symbol path on the analysis computer to a symbol server. If you do, UMDH will retrieve symbols for the version of Windows that is running on the analysis computer, and UMDH will not display meaningful results. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Interpreting%20a%20UMDH%20Log%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/interpreting-bug-check-0xcb.md b/windows-driver-docs-pr/debugger/interpreting-bug-check-0xcb.md new file mode 100644 index 0000000000..ae6d2772a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/interpreting-bug-check-0xcb.md @@ -0,0 +1,87 @@ +--- +title: Interpreting Bug Check 0xCB +description: Interpreting Bug Check 0xCB +ms.assetid: 82951e2b-cbb2-45d2-a6b8-4fddece035ce +keywords: ["kernel streaming debugging, video stream stall, bug check 0xcb"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interpreting Bug Check 0xCB + + +The most common bug check code associated with debugging a video stream stall is Bug Check 0xCB (DRIVER\_LEFT\_LOCKED\_PAGES\_IN\_PROCESS). For a detailed list of its parameters, see [**Bug Check 0xCB**](bug-check-0xcb--driver-left-locked-pages-in-process.md). + +The message displayed when the bug check occurs will point to Ks.sys as the cause. + +``` +Use !analyze -v to get detailed debugging information. +BugCheck CB, {f90c6ae0, f9949215, 81861788, 26} +Probably caused by : ks.sys ( ks!KsProbeStreamIrp+333 ) +``` + +As suggested, use [**!analyze -v**](-analyze.md) to get more detailed information. + +``` +kd> !analyze -v +DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS (cb) +Caused by a driver not cleaning up completely after an I/O. +When possible, the guilty driver's name (Unicode string) is printed on +the bugcheck screen and saved in KiBugCheckDriver. +Arguments: +Arg3: 81861788, A pointer to the MDL containing the locked pages. +``` + +Now, use the [**!search**](-search.md) extension to find the virtual addresses that are associated with the MDL pointer. + +``` +kd> !search 81861788 +Searching PFNs in range 00000001 - 0000FF76 for [FFFFFFFF81861788 - FFFFFFFF81861788] + +Pfn Offset Hit Va Pte +- - - - - - - - - - - - - - - - - - - - - - - - - - - +000008A7 00000B0C 81861788 808A7B0C C020229C +00000A04 00000224 16000001 80A04224 C0202810 +... +00001732 000009B4 81861788 817329B4 C0205CC8 +``` + +For each virtual address (VA) found, look for an IRP signature. Do this by using the [**dd**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command with the VA minus one DWORD. + +``` +kd> dd 808A7B0C-4 l4 +808a7b08 f9949215 81861788 00000026 00000000 +kd> $ Not an Irp +kd> dd 80A04224-4 l4 +80a04220 00000000 00000000 00000000 00000000 +kd> $ Not an Irp +kd> dd 817329B4-4 l4 +817329b0 01900006 81861788 00000070 ffa59220 +kd> $ Matches signature +``` + +After a VA with an IRP signature has been found, use the [**!irp**](-irp.md) extension to find out what driver is pending on this IRP. + +``` +kd> !irp 817329b0 7 +Irp is active with 2 stacks 2 is current (= 0x81732a44) + Mdl = 81861788 System buffer = ffa59220 Thread 00000000: Irp stack trace. +>[ e, 0] 1 1 81a883c8 81ae6158 00000000-00000000 pending + \Driver\TESTCAP + Args: 00000070 00000000 002f4017 00000000 +``` + +In this case, \\Driver\\TESTCAP is the likely cause of the bug check. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Interpreting%20Bug%20Check%200xCB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/introduction-to-symbols.md b/windows-driver-docs-pr/debugger/introduction-to-symbols.md new file mode 100644 index 0000000000..767c759daf --- /dev/null +++ b/windows-driver-docs-pr/debugger/introduction-to-symbols.md @@ -0,0 +1,27 @@ +--- +title: Introduction to Symbols +description: Introduction to Symbols +ms.assetid: 3c896a1e-51db-4c98-a6f4-842c82bdeaef +--- + +# Introduction to Symbols + + +## + + +This section includes: + +[Symbols and Symbol Files](symbols-and-symbol-files.md) + +[Public and Private Symbols](public-and-private-symbols.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Introduction%20to%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/introduction-to-the-amli-debugger.md b/windows-driver-docs-pr/debugger/introduction-to-the-amli-debugger.md new file mode 100644 index 0000000000..75aed621bc --- /dev/null +++ b/windows-driver-docs-pr/debugger/introduction-to-the-amli-debugger.md @@ -0,0 +1,35 @@ +--- +title: Introduction to the AMLI Debugger +description: Introduction to the AMLI Debugger +ms.assetid: f210171c-2226-4bd6-bbb4-aee4b087e575 +keywords: ["AMLI Debugger, overview", "ACPI debugging, machine language", "AML interpreter"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to the AMLI Debugger + + +## + + +There are significant differences between debugging standard kernel-mode code and debugging an ACPI (Advanced Configuration and Power Interface) BIOS. + +Whereas Windows and its drivers are composed of binary machine code compiled for a specific processor, the core of an ACPI BIOS is not in machine code. Rather, it is stored as ACPI Machine Language (AML) and is processed by the Microsoft AML interpreter as it is run. + +The Microsoft AMLI Debugger is a special debugging tool that can debug AML code. The AMLI Debugger is not actually a free-standing program. Rather, it consists of two components. One component is the checked build of the Microsoft Windows ACPI driver (Acpi.sys). The other component is located in certain debugger extensions included in the Debugging Tools for Windows package. + +On Windows XP and later versions of Windows, the AMLI Debugger is completely 64-bit aware. No matter what processor is being used by the target computer or the host computer, the AMLI Debugger will function correctly. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Introduction%20to%20the%20AMLI%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/introduction.md b/windows-driver-docs-pr/debugger/introduction.md new file mode 100644 index 0000000000..11cfb5923f --- /dev/null +++ b/windows-driver-docs-pr/debugger/introduction.md @@ -0,0 +1,72 @@ +--- +title: Debugger Engine Introduction +description: Debugger Engine Introduction +ms.assetid: fa52a1f0-9397-48a5-acbd-ce5347c0baef +--- + +# Debugger Engine Introduction + +This documentation describes how to use the debugger engine and how to write extensions that will run in WinDbg, KD, CDB, and NTSD. These debugger extensions can be used when performing user-mode or kernel-mode debugging on Microsoft Windows. + +### Debugger Engine + +The debugger engine provides an interface for examining and manipulating debugging targets in user-mode and kernel-mode on Microsoft Windows. + +The debugger engine can acquire targets, set breakpoints, monitor events, query symbols, read and write memory, and control threads and processes in a target. + +You can use the debugger engine to write both debugger extension libraries and stand-alone applications. Such applications are *debugger engine applications*. A debugger engine application that uses the full functionality of the debugger engine is a *debugger*. For example, WinDbg, CDB, NTSD, and KD are debuggers; the debugger engine provides the core of their functionality. + +The debugger engine API is specified by the prototypes in the header file dbgeng.h. + +### Incomplete Documentation + +This is a preliminary document and is currently incomplete. + +For many concepts relating to the debuggers and the debugger engine that are not yet documented here, look in the [Debugging Techniques](debugging-techniques.md) section of this documentation. + +To obtain some of the currently undocumented functionality of the debugger engine API, use the [**Execute**](https://msdn.microsoft.com/library/windows/hardware/ff543208) method to execute individual debugger commands. + +### Extensions + +You can create your own debugging commands by writing and building an extension DLL. For example, you might want to write an extension command to display a complex data structure. + +There are three different types of debugger extension DLLs: + +- *DbgEng extension DLLs*. These are based on the prototypes in the dbgeng.h header file. Each DLL of this type may export DbgEng extension commands. These extension commands use the Debugger Engine API and may also use the WdbgExts API. + +- *EngExtCpp extension DLLs*. These are based on the prototypes in the engextcpp.h and dbgeng.h header files. Each DLL of this type may export DbgEng extension commands. These extension commands use both the Debugger Engine API and the EngExtCpp extension framework, and may also use the WdbgExts API. + +- *WdbgExts extension DLLs*. These are based on the prototypes in the wdbgexts.h header file. Each DLL of this type exports one or more WdbgExts extension commands. These extension commands use the WdbgExts API exclusively. + +The DbgEng API can be used to create extensions or stand-alone applications. The WdbgExts API contains a subset of the functionality of the debugger engine API and can be used only by extensions. + +All debugger extensions should be compiled and built by using the Build utility. The Build utility is included in the Windows Driver Kit (WDK). + +Extension code samples are installed as part of the Debugging Tools for Windows package if you perform a custom installation and select the **SDK** component and all its subcomponents. They can be found in the sdk\\samples subdirectory of the Debugging Tools for Windows installation directory. + +The easiest way to write new debugger extensions is to study the sample extensions. Each sample extension includes makefile and sources files for use with the Build utility. Both types of extensions are represented in the samples. + +## Writing Custom Analysis Debugger Extensions + + +You can extend the capabilities of the [**!analyze**](-analyze.md) debugger command by writing an analysis extension plugin. By providing an analysis extension plugin, you can participate in the analysis of a bug check or an exception in a way that is specific to your own component or application. When you write an analysis extension plugin, you also write a metadata file that describes the situations for which you want your plugin to be called. When **!analyze** runs, it locates, loads, and runs the appropriate analysis extension plugins. For more information, see [Writing Custom Analysis Debugger Extensions](writing-custom-analysis-debugger-extensions.md) + +## Customizing Debugger Output Using DML + + +You can customize debugger output using DML. For more information see [Customizing Debugger Output Using DML](customizing-debugger-output-using-dml.md). + +## Using JavaScript to Extend the Capabilities of the Debugger + + +Use JavaScript to create scripts that understand debugger objects and extend and customize the capabilities of the debugger. JavaScript providers bridge a scripting language to the debugger's internal object model. The JavaScript debugger scripting provider, allows the for use of JavaScript with the debugger. For more information, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugger%20Engine%20Introduction%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/j--execute-if---else-.md b/windows-driver-docs-pr/debugger/j--execute-if---else-.md new file mode 100644 index 0000000000..30e126b71b --- /dev/null +++ b/windows-driver-docs-pr/debugger/j--execute-if---else-.md @@ -0,0 +1,106 @@ +--- +title: j (Execute If - Else) +description: The j command conditionally executes one of the specified commands, depending on the evaluation of a given expression. +ms.assetid: c6bb2415-e888-458b-8fb9-9d50b90cc531 +keywords: ["j (Execute If - Else) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- j (Execute If - Else) +api_type: +- NA +--- + +# j (Execute If - Else) + + +The **j** command conditionally executes one of the specified commands, depending on the evaluation of a given expression. + +``` +j Expression Command1 ; Command2 +j Expression 'Command1' ; 'Command2' +``` + +## Parameters + + + *Expression* +The expression to evaluate. If this expression evaluates to a nonzero value, *Command1* is executed. If this expression evaluates to zero, *Command2* is executed. For more information about the syntax of this expression, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + *Command1* +The command string to be executed if the expression in *Expression* evaluates to a nonzero value (TRUE). You can combine multiple commands by surrounding the command string with single straight quotation marks ( **'** ) and separating commands by using semicolons. If the command string is a single command, the single quotation marks are optional. + + *Command2* +The command string to be executed if the expression in *Expression* evaluates to zero (FALSE). You can combine multiple commands by surrounding the command string with single straight quotation marks ( **'** ) and separating commands by using semicolons. If the command string is a single command, the single quotation marks are optional. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +You cannot add a semicolon or additional commands after the **j** command. If a semicolon appears after *Command2*, everything after the semicolon is ignored. + +The following command displays the value of **eax** if **MySymbol** is equal to zero and displays the values of **ebx** and **ecx** otherwise. + +``` +0:000> j (MySymbol=0) 'r eax'; 'r ebx; r ecx' +``` + +You could omit the single quotation marks around **r eax**, but they make the command easier to read. If you want to omit one of the commands, you can include empty quotation marks or omit the parameter for that command, as in the following commands. + +``` +0:000> j (MySymbol=0) ''; 'r ebx; r ecx' +0:000> j (MySymbol=0) ; 'r ebx; r ecx' +``` + +You can also use the **j** command inside other commands. For example, you can use a **j** command to create conditional breakpoints. + +``` +0:000> bp `mysource.cpp:143` "j (poi(MyVar)>0n20) ''; 'gc' " +``` + +For more information about the syntax for conditional breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +## See also + + +[**z (Execute While)**](z--execute-while-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20j%20%28Execute%20If%20-%20Else%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/javascript-debugger-example-scripts.md b/windows-driver-docs-pr/debugger/javascript-debugger-example-scripts.md new file mode 100644 index 0000000000..7cb6e68d86 --- /dev/null +++ b/windows-driver-docs-pr/debugger/javascript-debugger-example-scripts.md @@ -0,0 +1,721 @@ +--- +title: JavaScript Debugger Example Scripts +description: This topic provides the information on user and kernel mode JavaScript code samples, such as the Data Filtering Plug and Play Device Tree sample. +ms.assetid: F477430B-10C7-4039-9C5F-25556C306643 +--- + +# JavaScript Debugger Example Scripts + + +This topic provides the following user and kernel mode JavaScript code samples. + +- [Data Filtering: Plug and Play Device Tree in KD (Kernel Mode)](#filter) +- [Extend Devices Specific To Multimedia (Kernel Mode)](#multimedia) +- [Adding Bus Information to \_DEVICE\_OBJECT (Kernel Mode)](#bus) +- [Find an Application Title (User Mode)](#title) + +## Working with Samples + + +Use the general process to test any of the samples. + +1. Determine if the sample JavaScript is intended for kernel or user mode debugging. Then either load an appropriate dump file or establish a live connection to a target system. + +2. Use a text editor such as Notepad to create a text file named and save it with a .js file extension, such as *HelloWorld.js* + +``` +// WinDbg JavaScript sample +// Says Hello World! + +// Code at root will be run with .scriptrun and .scriptload +host.diagnostics.debugLog("***> Hello World! \n"); + +function sayHi() +{ + //Say Hi + host.diagnostics.debugLog("Hi from JavaScript! \n"); +} +``` + +3. Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +4. Use the [**.scriptrun (Run Script)**](-scriptrun--run-script-.md)command to load and execute the script. The .scriptrun command will run code at the root/top and the code under the function names *initializeScript* and *invokeScript*. + +``` +0:000> .scriptrun c:\WinDbg\Scripts\HelloWorld.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\HelloWorld.js' +***> Hello World! +``` + +5. If the script contains a uniquely named function, use the dx command to execute that function, that is located in Debugger.State.Scripts.*ScriptName*.Contents.*FunctionName*. + +``` +0:001> dx Debugger.State.Scripts.HelloWorld.Contents.sayHi() +Hi from JavaScript! +Debugger.State.Scripts.HelloWorld.Contents.sayHi() +``` + +Refer to [JavaScript Debugger Scripting](javascript-debugger-scripting.md) for additional information about working with JavaScript. + +## Data Filtering: Plug and Play Device Tree in KD (Kernel Mode) + + +This sample code filters the device node tree to display just devices that contain a path of PCI that are started. + +This script is intended to support kernel mode debugging. + +You can use the !devnode 0 1 command to display information about the device tree. For more information, see [**!devnode**](-devnode.md). + +``` +// PlugAndPlayDeviceTree.js +// An ES6 generator function which recursively filters the device tree looking for PCI devices in the started state. +// +function *filterDevices(deviceNode) +{ + // + // If the device instance path has "PCI" in it and is started (state == 776), yield it from the generator. + // + if (deviceNode.InstancePath.indexOf("PCI") != -1 && deviceNode.State == 776) + { + yield deviceNode; + } + + // + // Recursively invoke the generator for all children of the device node. + // + for (var childNode of deviceNode.Children) + { + yield* filterDevices(childNode); + } +} + +// +// A function which finds the device tree of the first session in the debugger and passes it to our filter function. +// +function filterAllDevices() +{ + return filterDevices(host.namespace.Debugger.Sessions.First().Devices.DeviceTree.First()); +} +``` + +Either load a kernel dump file or establish a kernel mode connection to a target system. + +``` +0: kd> !load jsprovider.dll +``` + +``` +0: kd> .scriptload c:\WinDbg\Scripts\deviceFilter.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\deviceFilter.js' +``` + +Call the filterAllDevices() function. + +``` +0: kd> dx Debugger.State.Scripts.PlugAndPlayDeviceTree.Contents.filterAllDevices() +Debugger.State.Scripts.PlugAndPlayDeviceTree.Contents.filterAllDevices() : [object Generator] + [0x0] : PCI\VEN_8086&DEV_D131&SUBSYS_304A103C&REV_11\3&21436425&0&00 + [0x1] : PCI\VEN_8086&DEV_D138&SUBSYS_304A103C&REV_11\3&21436425&0&18 (pci) + [0x2] : PCI\VEN_10DE&DEV_06FD&SUBSYS_062E10DE&REV_A1\4&324c21a&0&0018 (nvlddmkm) + [0x3] : PCI\VEN_8086&DEV_3B64&SUBSYS_304A103C&REV_06\3&21436425&0&B0 (HECIx64) + [0x4] : PCI\VEN_8086&DEV_3B3C&SUBSYS_304A103C&REV_05\3&21436425&0&D0 (usbehci) + [0x5] : PCI\VEN_8086&DEV_3B56&SUBSYS_304A103C&REV_05\3&21436425&0&D8 (HDAudBus) +... +``` + +Each of these objects presented above, automatically supports DML, and can be clicked through just as with any other dx query. + +Alternatively to using this script, it is possible to use a LINQ query to accomplish a similar result. + +``` +0: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.InstancePath.Contains("PCI") && n.State == 776) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.InstancePath.Contains("PCI") && n.State == 776) + [0x0] : PCI\VEN_8086&DEV_D131&SUBSYS_304A103C&REV_11\3&21436425&0&00 + [0x1] : PCI\VEN_8086&DEV_D138&SUBSYS_304A103C&REV_11\3&21436425&0&18 (pci) + [0x2] : PCI\VEN_10DE&DEV_06FD&SUBSYS_062E10DE&REV_A1\4&324c21a&0&0018 (nvlddmkm) + [0x3] : PCI\VEN_8086&DEV_3B64&SUBSYS_304A103C&REV_06\3&21436425&0&B0 (HECIx64) + [0x4] : PCI\VEN_8086&DEV_3B3C&SUBSYS_304A103C&REV_05\3&21436425&0&D0 (usbehci) + [0x5] : PCI\VEN_8086&DEV_3B56&SUBSYS_304A103C&REV_05\3&21436425&0&D8 (HDAudBus) +... +``` + +## Extend Devices Specific To Multimedia (Kernel Mode) + + +This larger JavaScript example extends a kernel \_DEVICE\_OBJECT for information specific to multimedia and adds StreamingDevices to a debugger session. + +This script is intended to support kernel mode debugging. + +Note that the choice to extend Session with StreamingDevices is done for example purposes only. This should be either left to \_DEVICE\_OBJECT only or deeper inside a namespace under the existing .Devices.\* hierarchy. + +``` +// StreamingFinder.js +// Extends a kernel _DEVICE_OBJECT for information specific to multimedia +// and adds StreamingDevices to a debugger session. +// + +"use strict"; + +function initializeScript() +{ + // isStreamingDeviceObject: + // + // Returns whether devObj (as a _DEVICE_OBJECT -- not a pointer) looks like it is a device + // object for a streaming device. + // + function isStreamingDeviceObject(devObj) + { + try + { + var devExt = devObj.DeviceExtension; + var possibleStreamingExtPtrPtr = host.createPointerObject(devExt.address, "ks.sys", "_KSIDEVICE_HEADER **", devObj); + var possibleStreamingExt = possibleStreamingExtPtrPtr.dereference().dereference(); + var baseDevice = possibleStreamingExt.BaseDevice; + + if (devObj.targetLocation == baseDevice.dereference().targetLocation) + { + return true; + } + } + // + // The above code expects to fail (walking into invalid or paged out memory) often. A failure to read the memory + // of the target process will result in an exception. Catch such exception and indicate that the object does not + // match the profile of a "streaming device object". + // + catch(exc) + { + } + + return false; + } + + // findStreamingFDO(pdo): + // + // From a physical device object, walks up the device stack and attempts to find a device which + // looks like a streaming device (and is thus assumed to be the FDO). pdo is a pointer to + // the _DEVICE_OBJECT for the pdo. + // + function findStreamingFDO(pdo) + { + for (var device of pdo.UpperDevices) + { + if (isStreamingDeviceObject(device.dereference())) + { + return device; + } + } + + return null; + } + + // streamingDeviceList: + // + // A class which enumerates all streaming devices on the system. + // + class streamingDeviceList + { + constructor(session) + { + this.__session = session; + } + + *[Symbol.iterator]() + { + // + // Get the list of all PDOs from PNP using LINQ: + // + var allPDOs = this.__session.Devices.DeviceTree.Flatten(function(dev) { return dev.Children; }) + .Select (function(dev) { return dev.PhysicalDeviceObject; }); + + // + // Walk the stack up each PDO to find the functional device which looks like a KS device. This is + // a very simple heuristic test: the back pointer to the device in the KS device extension is + // accurate. Make sure this is wrapped in a try/catch to avoid invalid memory reads causing + // us to bail out. + // + // Don't even bother checking the PDO. + // + for (var pdo of allPDOs) + { + var fdo = findStreamingFDO(pdo); + if (fdo != null) + { + yield fdo; + } + } + } + } + + // streamingDeviceExtension: + // + // An object which will extend "session" and include the list of streaming devices. + // + class streamingDeviceExtension + { + get StreamingDevices() + { + return new streamingDeviceList(this); + } + }; + + // createEntryList: + // + // An abstraction over the create entry list within a streaming device. + // + class createEntryList + { + constructor(ksHeader) + { + this.__ksHeader = ksHeader; + } + + *[Symbol.iterator]() + { + for (var entry of host.namespace.Debugger.Utility.Collections.FromListEntry(this.__ksHeader.ChildCreateHandlerList, "ks!KSICREATE_ENTRY", "ListEntry")) + { + if (!entry.CreateItem.Create.isNull) + { + yield entry; + } + } + } + } + + // streamingInformation: + // + // Represents the streaming state of a device. + // + class streamingInformation + { + constructor(fdo) + { + this.__fdo = fdo; + + var devExt = fdo.DeviceExtension; + var streamingExtPtrPtr = host.createPointerObject(devExt.address, "ks.sys", "_KSIDEVICE_HEADER **", fdo); + this.__ksHeader = streamingExtPtrPtr.dereference().dereference(); + } + + get CreateEntries() + { + return new createEntryList(this.__ksHeader); + } + } + + // createEntryVisualizer: + // + // A visualizer for KSICREATE_ENTRY + // + class createEntryVisualizer + { + toString() + { + return this.CreateItem.ObjectClass.toString(); + } + + get CreateContext() + { + // + // This is probably not entirely accurate. The context is not *REQUIRED* to be an IUnknown. + // More analysis should probably be performed. + // + return host.createTypedObject(this.CreateItem.Context.address, "ks.sys", "IUnknown", this); + } + } + + // deviceExtension: + // + // Extends our notion of a device in the device tree to place streaming information on + // top of it. + // + class deviceExtension + { + get StreamingState() + { + if (isStreamingDeviceObject(this)) + { + return new streamingInformation(this); + } + + // + // If we cannot find a streaming FDO, returning undefined will indicate that there is no value + // to the property. + // + return undefined; + } + } + + return [new host.namedModelParent(streamingDeviceExtension, "Debugger.Models.Session"), + new host.typeSignatureExtension(deviceExtension, "_DEVICE_OBJECT"), + new host.typeSignatureRegistration(createEntryVisualizer, "KSICREATE_ENTRY")] +} +``` + +First load the script provider as described previously. Then load the script. + +``` +0: kd> .scriptload c:\WinDbg\Scripts\StreamingFinder.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\StreamingFinder.js' +``` + +Then use the dx command to access the new StreamingDevices capabilities that the script provides. + +``` +0: kd> dx -r3 @$cursession.StreamingDevices.Select(d => d->StreamingState.CreateEntries) +@$cursession.StreamingDevices.Select(d => d->StreamingState.CreateEntries) + [0x0] : [object Object] + [0x0] : "e0HDMIOutTopo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x1] : [object Object] + [0x0] : "AnalogDigitalCaptureTopo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x1] : "AnalogDigitalCapture1Topo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x2] : "AnalogDigitalCapture2Topo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x3] : "AnalogDigitalCapture2Wave" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortWaveRT] + [0x4] : "HeadphoneTopo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x5] : "RearLineOutTopo" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortTopology] + [0x6] : "RearLineOutWave" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: CPortWaveRT] + [0x2] : [object Object] + [0x0] : "GLOBAL" [Type: KSICREATE_ENTRY] + [] [Type: KSICREATE_ENTRY] + CreateContext [Type: IUnknown] +``` + +## Adding Bus Information to \_DEVICE\_OBJECT (Kernel Mode) + + +This script extends the visualization of \_DEVICE\_OBJECT to add a BusInformation field which has PCI specific information underneath it. The manner and namespacing of this sample are still being discussed. It should be considered a sample of the capabilities of the JavaScript provider. + +This script is intended to support kernel mode debugging. + +``` +"use strict"; + +/************************************************* +DeviceExtensionInformation.js: + +An example which extends _DEVICE_OBJECT to add bus specific information +to each device object. + +NOTE: The means of conditionally adding and the style of namespacing this +are still being discussed. This currently serves as an example of the capability +of JavaScript extensions. + +*************************************************/ + +function initializeScript() +{ + // __getStackPDO(): + // + // Returns the physical device object of the device stack whose device object + // is passed in as 'devObj'. + // + function __getStackPDO(devObj) + { + var curDevice = devObj; + var nextDevice = curDevice.DeviceObjectExtension.AttachedTo; + while (!nextDevice.isNull) + { + curDevice = nextDevice; + nextDevice = curDevice.DeviceObjectExtension.AttachedTo; + } + return curDevice; + } + + // pciInformation: + // + // Class which abstracts our particular representation of PCI information for a PCI device or bus + // based on a _PCI_DEVICE structure or a _PCI_BUS structure. + // + class pciInformation + { + constructor(pciDev) + { + this.__pciDev = pciDev; + this.__pciPDO = __getStackPDO(this.__pciDev); + this.__isBridge = (this.__pciDev.address != this.__pciPDO.address); + + if (this.__isBridge) + { + this.__deviceExtension = host.createTypedObject(this.__pciPDO.DeviceExtension.address, "pci.sys", "_PCI_DEVICE", this.__pciPDO); + this.__busExtension = host.createTypedObject(this.__pciDev.DeviceExtension.address, "pci.sys", "_PCI_BUS", this.__pciPDO); + + this.__hasDevice = (this.__deviceExtension.Signature == 0x44696350); /* 'PciD' */ + this.__hasBus = (this.__busExtension.Signature == 0x42696350); /* 'PciB' */ + + if (!this.__hasDevice && !this.__hasBus) + { + throw new Error("Unrecognized PCI device extension"); + } + } + else + { + this.__deviceExtension = host.createTypedObject(this.__pciPDO.DeviceExtension.address, "pci.sys", "_PCI_DEVICE", this.__pciPDO); + + this.__hasDevice = (this.__deviceExtension.Signature == 0x44696350); /* 'PciD' */ + this.__hasBus = false; + + if (!this.__hasDevice) + { + throw new Error("Unrecognized PCI device extension"); + } + } + } + + toString() + { + + if (this.__hasBus && this.__hasDevice) + { + return "Bus: " + this.__busExtension.toString() + " Device: " + this.__deviceExtension.toString(); + } + else if (this.__hasBus) + { + return this.__busExtension.toString(); + } + else + { + return this.__deviceExtension.toString(); + } + } + + get Device() + { + if (this.__hasDevice) + { + // NatVis supplies the visualization for _PCI_DEVICE + return this.__deviceExtension; + } + + return undefined; + } + + get Bus() + { + if (this.__hasBus) + { + // NatVis supplies the visualization for _PCI_BUS + return this.__busExtension; + } + + return undefined; + } + } + + // busInformation: + // + // Our class which does analysis of what bus a particular device is on and places information about + // about that bus within the _DEVICE_OBJECT visualization. + // + class busInformation + { + constructor(devObj) + { + this.__devObj = devObj; + } + + get PCI() + { + // + // Check the current device object. This may be a PCI bridge + // in which both the FDO and PDO are relevant (one for the bus information + // and one for the bridge device information). + // + var curName = this.__devObj.DriverObject.DriverName.toString(); + if (curName.includes("\\Driver\\pci")) + { + return new pciInformation(this.__devObj); + } + + var stackPDO = __getStackPDO(this.__devObj); + var pdoName = stackPDO.DriverObject.DriverName.toString(); + if (pdoName.includes("\\Driver\\pci")) + { + return new pciInformation(stackPDO); + } + + return undefined; + } + } + + // busInformationExtension: + // + // An extension placed on top of _DEVICE_OBJECT in order to provide bus analysis and bus specific + // information to the device. + // + class busInformationExtension + { + get BusInformation() + { + return new busInformation(this); + } + } + + return [new host.typeSignatureExtension(busInformationExtension, "_DEVICE_OBJECT")]; +} +``` + +First load the script provider as described previously. Then load the script. + +``` +0: kd> .scriptload c:\WinDbg\Scripts\DeviceExtensionInformation.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\DeviceExtensionInformation.js' +``` + +We need to locate the address of the device object we are interested in. In this example, we will examine the audio HDAudBus driver. + +``` +0: kd> !drvobj HDAudBus +Driver object (ffffb60757a4ae60) is for: + \Driver\HDAudBus +Driver Extension List: (id , addr) +(fffff8050a9eb290 ffffb60758413180) +Device Object list: +ffffb60758e21810 ffffb60757a67c60 +``` + +After the script is loaded use the dx command to display bus information for device objects. + +``` +0: kd> dx -r1 (*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)) +(*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)) : Device for "\Driver\HDAudBus" [Type: _DEVICE_OBJECT] + [] [Type: _DEVICE_OBJECT] + Flags : 0x2004 + UpperDevices : None + LowerDevices : Immediately below is Device for "\Driver\ACPI" [at 0xffffe000003d9820] + Driver : 0xffffe00001ccd060 : Driver "\Driver\HDAudBus" [Type: _DRIVER_OBJECT *] + BusInformation : [object Object] + +0: kd> dx -r1 (*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)).@"BusInformation" +(*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)).@"BusInformation" : [object Object] + PCI : (d=0x14 f=0x2) Vendor=0x1022 Device=0x780d Multimedia Device / Unknown Sub Class + +0: kd> dx -r1 (*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)).@"BusInformation".@"PCI" +(*((ntkrnlmp!_DEVICE_OBJECT *)0xffffe00001b567c0)).@"BusInformation".@"PCI" : (d=0x14 f=0x2) Vendor=0x1022 Device=0x780d Multimedia Device / Unknown Sub Class + Device : (d=0x14 f=0x2) Vendor=0x1022 Device=0x780d Multimedia Device / Unknown Sub Class [Type: _PCI_DEVICE] + +0: kd> dx -r1 (*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)) +(*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)) : (d=0x14 f=0x2) Vendor=0x1022 Device=0x780d Multimedia Device / Unknown Sub Class [Type: _PCI_DEVICE] + [] [Type: _PCI_DEVICE] + Device : 0xffffe000003fe060 : Device for "\Driver\pci" [Type: _DEVICE_OBJECT *] + Requirements + Resources + +0: kd> dx -r1 (*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)).@"Resources" +(*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)).@"Resources" + BaseAddressRegisters + Interrupt : Line Based -- Interrupt Line = 0x10 [Type: _PCI_DEVICE_INTERRUPT_RESOURCE] + +0: kd> dx -r1 (*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)).@"Resources".@"BaseAddressRegisters" +(*((pci!_PCI_DEVICE *)0xffffe000003fe1b0)).@"Resources".@"BaseAddressRegisters" + [0x0] : Memory Resource: 0xf0340000 of length 0x4000 [Type: _CM_PARTIAL_RESOURCE_DESCRIPTOR] +``` + +## Find an Application Title (User Mode) + + +This example iterates through all the threads in the debugger's current process, finds a frame which includes *\_\_mainCRTStartup* and then returns the string from the StartupInfo.lpTitle within the CRT's startup. This script shows examples of iteration, string manipulation, and LINQ queries within JavaScript. + +This script is intended to support user mode debugging. + +``` +// TitleFinder.js +// A function which uses just JavaScript concepts to find the title of an application +// +function findTitle() +{ + var curProcess = host.currentProcess; + for (var thread of curProcess.Threads) + { + for (var frame of thread.Stack.Frames) + { + if (frame.toString().includes("__mainCRTStartup")) + { + var locals = frame.LocalVariables; + + // + // locals.StartupInfo.lpTitle is just an unsigned short *. We need to actually call an API to + // read the UTF-16 string in the target address space. This would be true even if this were + // a char* or wchar_t*. + // + return host.memory.readWideString(locals.StartupInfo.lpTitle); + } + } + } +} + +// +// A function which uses both JavaScript and integrated LINQ concepts to do the same. +// +function findTitleWithLINQ() +{ + var isMainFrame = function(frame) { return frame.toString().includes("__mainCRTStartup"); }; + var isMainThread = function(thread) { return thread.Stack.Frames.Any(isMainFrame); }; + + var curProcess = host.currentProcess; + var mainThread = curProcess.Threads.Where(isMainThread).First(); + var mainFrame = mainThread.Stack.Frames.Where(isMainFrame).First(); + + var locals = mainFrame.LocalVariables; + + // + // locals.StartupInfo.lpTitle is just an unsigned short *. We need to actually call an API to + // read the UTF-16 string in the target address space. This would be true even if this were + // a char* or wchar_t*. + // + return host.memory.readWideString(locals.StartupInfo.lpTitle); +} +``` + +``` +0: kd> .scriptload c:\WinDbg\Scripts\TitleFinder.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\TitleFinder.js' +``` + +Calling the findTitle() function returns notepad.exe + +``` +0:000> dx Debugger.State.Scripts.TitleFinder.Contents.findTitle() +Debugger.State.Scripts.TitleFinder.Contents.findTitle() : C:\Windows\System32\notepad.exe +``` + +Calling the LINQ version, findTitleWithLINQ() also returns notepad.exe + +``` +0:000> dx Debugger.State.Scripts.TitleFinder.Contents.findTitleWithLINQ() +Debugger.State.Scripts.titleFinder.Contents.findTitleWithLINQ() : C:\Windows\System32\notepad.exe +``` + +## Related topics + + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20JavaScript%20Debugger%20Example%20Scripts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/javascript-debugger-scripting.md b/windows-driver-docs-pr/debugger/javascript-debugger-scripting.md new file mode 100644 index 0000000000..939aa1de31 --- /dev/null +++ b/windows-driver-docs-pr/debugger/javascript-debugger-scripting.md @@ -0,0 +1,921 @@ +--- +title: JavaScript Debugger Scripting +description: This topic describes how to use JavaScript to create scripts that understand debugger objects and extend and customize the capabilities of the debugger. +ms.assetid: 3442E2C4-4054-4698-B7FB-8FE19D26C171 +--- + +# JavaScript Debugger Scripting + + +This topic describes how to use JavaScript to create scripts that understand debugger objects and extend and customize the capabilities of the debugger. + +## Overview of JavaScript Debugger Scripting + + +Script providers bridge a scripting language to the debugger's internal object model. The JavaScript debugger scripting provider, allows the for use of JavaScript with the debugger. + +When a JavaScript is loaded via the .scriptload command, the root code of the script is executed, the names which are present in the script are bridged into the root namespace of the debugger (dx Debugger) and the script stays resident in memory until it is unloaded and all references to its objects are released. The script can provide new functions to the debugger's expression evaluator, modify the object model of the debugger, or can act as a visualizer in much the same way that a NatVis visualizer does. + +This topic describes some of what you can do with JavaScript debugger scripting. + +[Load The Debugger JavaScript Provider](#provider) + +[Use the JavaScript Scripting Meta Commands](#commands) + +[Get Started with JavaScript Debugger Scripting](#started) + +[Automate Debugger Commands](#automate) + +[Set Conditional Breakpoints with JavaScript](#breakpoints) + +[Create a Debugger Visualizer in JavaScript](#visualizer) + +[Work With 64-Bit Values in JavaScript Extensions](#bitvalues) + +[JavaScript Resources](#resources) + +These two topics provide additional information about working with JavaScript in the debugger. + +[JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md) + +[Native Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md) + +## The Debugger JavaScript Provider + + +The JavaScript provider included with the debugger takes full advantage of the latest ECMAScript6 object and class enhancements. For more information, see [ECMAScript 6 — New Features: Overview & Comparison](http://es6-features.org/). + +**JsProvider.dll** + +JsProvider.dll is the JavaScript provider that is loaded to support JavaScript Debugger Scripting. + +**Requirements** + +JavaScript Debugger Scripting is designed to work with all supported versions of Windows. + +## Loading the JavaScript Scripting Provider + + +Before using any of the .script commands, a scripting provider needs to be loaded using the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command. To load the JavaScript provider, use the following command. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptproviders command to confirm that the JavaScript provider is loaded. + +``` +0:000> .scriptproviders +Available Script Providers: + NatVis (extension '.NatVis') + JavaScript (extension '.js') +``` + +## JavaScript Scripting Meta Commands + + +The following commands are available to work with JavaScript Debugger Scripting. + +- [**.scriptproviders (List Script Providers)**](-scriptproviders--list-script-providers-.md) +- [**.scriptload (Load Script)**](-scriptload--load-script-.md) +- [**.scriptunload (Unload Script)**](-scriptunload--unload-script-.md) +- [**.scriptrun (Run Script)**](-scriptrun--run-script-.md) +- [**.scriptlist (List Loaded Scripts)**](-scriptlist--list-loaded-scripts-.md) + +**Requirements** + +Before using any of the .script commands, a scripting provider needs to be loaded using the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command. To load the JavaScript provider, use the following command. + +``` +0:000> .load jsprovider.dll +``` + +## .scriptproviders (List Script Providers) + + +The .scriptproviders command will list all the script languages which are presently understood by the debugger and the extension under which they are registered. + +In the example below, the JavaScript and NatVis providers are loaded. + +``` +0:000> .scriptproviders +Available Script Providers: + NatVis (extension '.NatVis') + JavaScript (extension '.js') +``` + +Any file ending in ".NatVis" is understood as a NatVis script and any file ending in ".js" is understood as a JavaScript script. Either type of script can be loaded with the .scriptload command. + +For more information, see [**.scriptproviders (List Script Providers)**](-scriptproviders--list-script-providers-.md) + +## .scriptload (Load Script) + + +The .scriptload command will load a script and execute the root code of a script and the *initializeScript* function. If there are any errors in the initial load and execution of the script, the errors will be displayed to console. The following command shows the successful load of TestScript.js. + +``` +0:000> .scriptload C:\WinDbg\Scripts\TestScript.js +JavaScript script successfully loaded from 'C:\WinDbg\Scripts\TestScript.js' +``` + +Any object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content. + +For more information, see [**.scriptload (Load Script)**](-scriptload--load-script-.md) + +## .scriptrun + + +The .scriptrun command will load a script, execute the root code of the script, the *initializeScript* and the *invokeScript* function. If there are any errors in the initial load and execution of the script, the errors will be displayed to console. + +``` +0:000> .scriptrun C:\WinDbg\Scripts\helloWorld.js +JavaScript script successfully loaded from 'C:\WinDbg\Scripts\helloWorld.js' +Hello World! We are in JavaScript! +``` + +Any debugger object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content. + +For more information, see [**.scriptrun (Run Script)**](-scriptrun--run-script-.md). + +## .scriptunload (Unload Script) + + +The .scriptunload command unloads a loaded script and calls the *uninitializeScript* function. Use the following command syntax to unload a script + +``` +0:000:x86> .scriptunload C:\WinDbg\Scripts\TestScript.js +JavaScript script unloaded from 'C:\WinDbg\Scripts\TestScript.js' +``` + +For more information, see [**.scriptunload (Unload Script)**](-scriptunload--unload-script-.md). + +## .scriptlist (List Loaded Scripts) + + +The .scriptlist command will list any scripts which have been loaded via the .scriptload or the .scriptrun command. If the TestScript was successfully loaded using .scriptload, the .scriptlist command would display the name of the loaded script. + +``` +0:000> .scriptlist +Command Loaded Scripts: + JavaScript script from 'C:\WinDbg\Scripts\TestScript.js' +``` + +For more information, see [**.scriptlist (List Loaded Scripts)**](-scriptlist--list-loaded-scripts-.md). + +## Get Started with JavaScript Debugger Scripting + + +### HelloWorld Example Script + +This section describes how to create and execute a simple JavaScript debugger script that prints out, Hello World. + +``` +// WinDbg JavaScript sample +// Prints Hello World +function initializeScript() +{ + host.diagnostics.debugLog("***> Hello World! \n"); +} +``` + +Use a text editor such as Notepad to create a text file named *HelloWorld.js* that contains the JavaScript code shown above. + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptload command to load and execute the script. Because we used the function name *initializeScript*, the code in the function is run when the script is loaded. + +``` +0:000> .scriptload c:\WinDbg\Scripts\HelloWorld.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\HelloWorld.js' +***> Hello World! +``` + +After the script is loaded the additional functionality is available in the debugger. Use the [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) command to display *Debugger.State.Scripts* to see that our script is now resident. + +``` +0:000> dx Debugger.State.Scripts +Debugger.State.Scripts + HelloWorld +``` + +In the next example, we will add and call a named function. + +### Adding Two Values Example Script + +This section describes how to create and execute a simple JavaScript debugger script that adds takes input and adds two numbers. + +This simple script provides a single function, addTwoValues. + +``` +// WinDbg JavaScript sample +// Adds two functions +function addTwoValues(a, b) + { + return a + b; + } +``` + +Use a text editor such as Notepad to create a text file named *FirstSampleFunction.js* + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptload command to load the script. + +``` +0:000> .scriptload c:\WinDbg\Scripts\FirstSampleFunction.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\FirstSampleFunction.js' +``` + +After the script is loaded the additional functionality is available in the debugger. Use the [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) command to display *Debugger.State.Scripts* to see that our script is now resident. + +``` +0:000> dx Debugger.State.Scripts +Debugger.State.Scripts + FirstSampleFunction +``` + +We can click on the *FirstSampleFunction*, to see what functions it provides. + +``` +0:000> dx -r1 Debugger.State.Scripts.FirstSampleFunction.Contents +Debugger.State.Scripts.FirstSampleFunction.Contents : [object Object] + host : [object Object] + addTwoValues +``` + +To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command. + +``` +0:000> dx @$myScript = Debugger.State.Scripts.FirstSampleFunction.Contents +``` + +Use the dx expression evaluator to call the addTwoValues function. + +``` +0:000> dx @$myScript.addTwoValues(10, 41),d +@$myScript.addTwoValues(10, 41),d : 51 +``` + +You can also use the *@$scriptContents* built in alias to work with the scripts. The *@$scriptContents* alias merges all of the .Content of all of the scripts that are loaded. + +``` +0:001> dx @$scriptContents.addTwoValues(10, 40),d +@$scriptContents.addTwoValues(10, 40),d : 50 +``` + +When you are done working with the script use the .scriptunload command to unload the script. + +``` +0:000> .scriptunload c:\WinDbg\Scripts\FirstSampleFunction.js +JavaScript script successfully unloaded from 'c:\WinDbg\Scripts\FirstSampleFunction.js' +``` + +### Debugger Command Automation + +This section describes how to create and execute a simple JavaScript debugger script that automates the sending of the [**u (Unassemble)**](u--unassemble-.md) command. The sample also shows how to gather and display command output in a loop. + +This script provides a single function, RunCommands(). + +``` +// WinDbg JavaScript sample +// Shows how to call a debugger command and display results +"use strict"; + +function RunCommands() +{ +var ctl = host.namespace.Debugger.Utility.Control; +var output = ctl.ExecuteCommand("u"); +host.diagnostics.debugLog("***> Displaying command ouput \n"); + +for (var line of output) + { + host.diagnostics.debugLog(" ", line, "\n"); + } + +host.diagnostics.debugLog("***> Exiting RunCommands Function \n"); + +} +``` + +Use a text editor such as Notepad to create a text file named *RunCommands.js* + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptload command to load the RunCommands script. + +``` +0:000> .scriptload c:\WinDbg\Scripts\RunCommands.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\RunCommands.js' +``` + +After the script is loaded the additional functionality is available in the debugger. Use the [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) command to display *Debugger.State.Scripts.RunCommands* to see that our script is now resident. + +``` +0:000>dx -r3 Debugger.State.Scripts.RunCommands +Debugger.State.Scripts.RunCommands + Contents : [object Object] + host : [object Object] + diagnostics : [object Object] + namespace + currentSession : Live user mode: + currentProcess : notepad.exe + currentThread : ntdll!DbgUiRemoteBreakin (00007ffd`87f2f440) + memory : [object Object] +``` + +Use the dx command to call the RunCommands function in the RunCommands script. + +``` +0:000> dx Debugger.State.Scripts.RunCommands.Contents.RunCommands() + ***> Displaying command ouput + ntdll!ExpInterlockedPopEntrySListEnd+0x17 [d:\rs1\minkernel\ntos\rtl\amd64\slist.asm @ 196]: + 00007ffd`87f06e67 cc int 3 + 00007ffd`87f06e68 cc int 3 + 00007ffd`87f06e69 0f1f8000000000 nop dword ptr [rax] + ntdll!RtlpInterlockedPushEntrySList [d:\rs1\minkernel\ntos\rtl\amd64\slist.asm @ 229]: + 00007ffd`87f06e70 0f0d09 prefetchw [rcx] + 00007ffd`87f06e73 53 push rbx + 00007ffd`87f06e74 4c8bd1 mov r10,rcx + 00007ffd`87f06e77 488bca mov rcx,rdx + 00007ffd`87f06e7a 4c8bda mov r11,rdx +***> Exiting RunCommands Function +``` + +## Special JavaScript Debugger Functions + + +There are several special functions in a JavaScript script called by the script provider itself. + +### initializeScript + +When a JavaScript script loads and is executed, it goes through a series of steps before the variables, functions, and other objects in the script affect the object model of the debugger. + +- The script is loaded into memory and parsed. +- The root code in the script is executed. +- If the script has a method called initializeScript, that method is called. +- The return value from initializeScript is used to determine how to automatically modify the object model of the debugger. +- The names in the script are bridged to the debugger's namespace. + +As mentioned, initializeScript will be called immediately after the root code of the script is executed. Its job is to return a JavaScript array of registration objects to the provider indicating how to modify the object model of the debugger. + +``` +function initializeScript() +{ + // Add code here that you want to run everytime the script is loaded. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***> initializeScript was called\n"); +} +``` + +### invokeScript + +The invokeScript method is the primary script method and is called when .scriptload and .scriptrun are run. + +``` +function invokeScript() +{ + // Add code here that you want to run everytime the script is executed. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***> invokeScript was called\n"); +} +``` + +### uninitializeScript + +The uninitializeScript method is the behavioral opposite of initializeScript. It is called when a script is unlinked and is getting ready to unload. Its job is to undo any changes to the object model which the script made imperatively during execution and/or to destroy any objects which the script cached. + +If a script neither makes imperative manipulations to the object model nor caches results, it does not need to have an uninitializeScript method. Any changes to the object model performed as indicated by the return value of initializeScript are undone automatically by the provider. Such changes do not require an explicit uninitializeScript method. + +``` +function uninitializeScript() +{ + // Add code here that you want to run everytime the script is unloaded. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***> uninitialize was called\n"); +} +``` + +## Summary of Functions Called by Script Commands + + +This table summarizes which functions are called by the script commands + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
.[.scriptload](-scriptload--load-script-.md)[.scriptrun (Run Script)](-scriptrun--run-script-.md)[.scriptunload (Unload Script)](-scriptunload--unload-script-.md)
rootyesyes
initializeScriptyesyes
invokeScriptyes
uninitializeScriptyes
+ +  + +Use this sample code to see when each function is called as the script is loaded, executed and unloaded. + +``` +// Root of Script +host.diagnostics.debugLog("***>; Code at the very top (root) of the script is always run \n"); + + +function initializeScript() +{ + // Add code here that you want to run everytime the script is loaded. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***>; initializeScript was called \n"); +} + +function invokeScript() +{ + // Add code here that you want to run everytime the script is executed. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***>; invokeScript was called \n"); +} + + +function uninitializeScript() +{ + // Add code here that you want to run everytime the script is unloaded. + // We will just send a message to indicate that function was called. + host.diagnostics.debugLog("***>; uninitialize was called\n"); +} + + +function main() +{ + // main is just another function name in JavaScript + // main is not called by .scriptload or .scriptrun + host.diagnostics.debugLog("***>; main was called \n"); +} +``` + +## Creating a Debugger Visualizer in JavaScript + + +Custom visualization files allow you to group and organize data in a visualization structure that better reflects the data relationships and content. You can use the JavaScript debugger extensions to write debugger visualizers which act in a way very similar to NatVis. This is accomplished via authoring a JavaScript prototype object (or an ES6 class) which acts as the visualizer for a given data type. For more information about NatVis and the debugger see [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md). + +**Example class - Simple1DArray** + +Consider an example of a C++ class which represents a single dimensional array. This class has two members, m\_size which is the overall size of the array, and m\_pValues which is a pointer to a number of ints in memory equal to the m\_size field. + +``` +class Simple1DArray +{ +private: + + ULONG64 m_size; + int *m_pValues; +}; +``` + +We can use the dx command to look at the default data structure rendering. + +``` +0:000> dx g_array1D +g_array1D [Type: Simple1DArray] + [+0x000] m_size : 0x5 [Type: unsigned __int64] + [+0x008] m_pValues : 0x8be32449e0 : 0 [Type: int *] +``` + +**JavaScript Visualizer** + +In order to visualize this type, we need to author a prototype (or ES6) class which has all the fields and properties we want the debugger to show. We also need to have the initializeScript method return an object which tells the JavaScript provider to link our prototype as a visualizer for the given type. + +``` +function initializeScript() +{ + // + // Define a visualizer class for the object. + // + class myVisualizer + { + // + // Create an ES6 generator function which yields back all the values in the array. + // + *[Symbol.iterator]() + { + var size = this.m_size; + var ptr = this.m_pValues; + for (var i = 0; i < size; ++i) + { + yield ptr.dereference(); + + // + // Note that the .add(1) method here is effectively doing pointer arithmetic on + // the underlying pointer. It is moving forward by the size of 1 object. + // + ptr = ptr.add(1); + } + } + } + + return [new host.typeSignatureRegistration(myVisualizer, "Simple1DArray")]; +} +``` + +Save the script in a file named arrayVisualizer.js. + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load C:\ScriptProviders\jsprovider.dll +``` + +Use .scriptload to load the array visualizer script. + +``` +0:000> .scriptload c:\WinDbg\Scripts\arrayVisualizer.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\arrayVisualizer.js' +``` + +Now, when the dx command is used the script visualizer will display rows of array content. + +``` +0:000> dx g_array1D +g_array1D : [object Object] [Type: Simple1DArray] + [] [Type: Simple1DArray] + [0x0] : 0x0 + [0x1] : 0x1 + [0x2] : 0x2 + [0x3] : 0x3 + [0x4] : 0x4 +``` + +In addition, this JavaScript visualization provides LINQ functionality, such as Select. + +``` +0:000> dx g_array1D.Select(n => n * 3),d +g_array1D.Select(n => n * 3),d + [0] : 0 + [1] : 3 + [2] : 6 + [3] : 9 + [4] : 12 +``` + +**What Affects the Visualization** + +A prototype or class which is made the visualizer for a native type through a return of a host.typeSignatureRegistration object from initializeScript will have all of the properties and methods within JavaScript added to the native type. In addition, the following semantics apply: + +- Any name which does not start with two underscores (\_\_) will be available in the visualization. + +- Names which are part of standard JavaScript objects or are part of protocols which the JavaScript provider creates will not show up in the visualization. + +- An object can be made iterable via the support of \[Symbol.iterator\]. + +- An object can be made indexable via the support of a custom protocol consisting of several functions: getDimensionality, getValueAt, and optionally setValueAt. + +**Native and JavaScript Object Bridge** + +The bridge between JavaScript and the object model of the debugger is two-way. Native objects can be passed into JavaScript and JavaScript objects can be passed into the Debugger's expression evaluator. As an example of this, consider the addition of the following method in our script: + +``` +function multiplyBySeven(val) +{ + return val * 7; +} +``` + +This method can now be utilized in the example LINQ query above. First we load the JavaScript visualization. + +``` +0:000> .scriptload c:\WinDbg\Scripts\arrayVisualizer2.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\arrayVisualizer2.js' + +0:000> dx @$myScript = Debugger.State.Scripts.arrayVisualizer2.Contents +``` + +Then we can use the multiplyBySeven function inline as shown below. + +``` +0:000> dx g_array1D.Select(@$myScript.multiplyBySeven),d +g_array1D.Select(@$myScript.multiplyBySeven),d + [0] : 0 + [1] : 7 + [2] : 14 + [3] : 21 + [4] : 28 +``` + +## Conditional Breakpoints with JavaScript + + +You can use JavaScript to do supplemental processing after a breakpoint is hit. For example, script can be used to examine other run time values and then determine if you want to automatically continue code execution or stop and do additional manual debugging. + +For general information on working with breakpoints, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +**DebugHandler.js Example Breakpoint Processing Script** + +This example will evaluate notepad's open and save dialog: *notepad!ShowOpenSaveDialog*. This script will evaluate the pszCaption variable to determine if the current dialog is an "Open" dialog or if it is a "Save As" dialog. If it's an open dialog, code execution will continue. If it's a save as dialog, code execution will stop, and the debugger will break in. + +``` + // Use JavaScript stric mode +"use strict"; + +// Define the invokeScript method to handle breakpoints + + function invokeScript() + { + var ctl = host.namespace.Debugger.Utility.Control; + + //Get the address of my string + var address = host.evaluateExpression("pszCaption"); + + //The open and save dialogs use the same function + //When we hit the open dialog, continue. + //When we hit the save dialog, break. + if(host.memory.readWideString(address)=="Open"){ + //host.diagnostics.debugLog("We're opening, let's continue!\n"); + ctl.ExecuteCommand("gc"); + }else{ + //host.diagnostics.debugLog("We're saving, let's break!\n"); + } + + } +``` + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +This command sets a breakpoint on notepad!ShowOpenSaveDialog, and will run the script above whenever that breakpoint is hit. + +``` +bp notepad!ShowOpenSaveDialog ".scriptrun C:\\WinDbg\\Scripts\\DebugHandler.js" +``` + +Then when the File > Save option is selected in notepad, the script is run, the g command is not sent, and a break in code execution occurs. + +``` +JavaScript script successfully loaded from 'C:\WinDbg\Scripts\DebugHandler.js' +notepad!ShowOpenSaveDialog: +00007ff6`f9761884 48895c2408 mov qword ptr [rsp+8],rbx ss:000000db`d2a9f2f0=0000021985fe2060 +``` + +## Work With 64-Bit Values in JavaScript Extensions + + +This section describes how 64-bit values passed into a JavaScript debugger extension behave. This issue arises as JavaScript only has the ability to store numbers using 53-bits. + +**64-Bit and JavaScript 53-Bit Storage** + +Ordinal values passed into JavaScript are normally marshaled as JavaScript numbers. The problem with this is that JavaScript numbers are 64-bit double precision floating point values. Any ordinal over 53-bits would lose precision on entry into JavaScript. This presents an issue for 64-bit pointers and other 64-bit ordinal values which may have flags in the highest bytes. In order to deal with this, any 64-bit native value (whether from native code or the data model) which enters JavaScript enters as a library type -- not as a JavaScript number. This library type will round trip back to native code without losing numeric precision. + +**Auto-Conversion** + +The library type for 64-bit ordinal values supports the standard JavaScript valueOf conversion. If the object is used in a math operation or other construct which requires value conversion, it will automatically convert to a JavaScript number. If loss of precision were to occur (the value utilizes more than 53-bits of ordinal precision), the JavaScript provider will throw an exception. + +Note that if you use bitwise operators in JavaScript, you are further limited to 32-bits of ordinal precision. + +This sample code sums two numbers and will be used to test the conversion of 64 bit values. + +``` +function playWith64BitValues(a64, b64) +{ + // Sum two numbers to demonstrate 64-bit behavior. + // + // Imagine a64==100, b64==1000 + // The below would result in sum==1100 as a JavaScript number. No exception is thrown. The values auto-convert. + // + // Imagine a64==2^56, b64=1 + // The below will **Throw an Exception**. Conversion to numeric results in loss of precision! + // + var sum = a64 + b64; + host.diagnostics.debugLog("Sum >> ", sum, "\n"); + +} + +function performOp64BitValues(a64, b64, op) +{ + // + // Call a data model method passing 64-bit value. There is no loss of precision here. This round trips perfectly. + // For example: + // 0:000> dx @$myScript.playWith64BitValues(0x4444444444444444ull, 0x3333333333333333ull, (x, y) => x + y) + // @$myScript.playWith64BitValues(0x4444444444444444ull, 0x3333333333333333ull, (x, y) => x + y) : 0x7777777777777777 + // + return op(a64, b64); +} +``` + +Use a text editor such as Notepad to create a text file named *PlayWith64BitValues.js* + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptload command to load the script. + +``` +0:000> .scriptload c:\WinDbg\Scripts\PlayWith64BitValues.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\PlayWith64BitValues.js' +``` + +To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command. + +``` +0:000> dx @$myScript = Debugger.State.Scripts.PlayWith64BitValues.Contents +``` + +Use the dx expression evaluator to call the addTwoValues function. + +First we will calculate the value of 2^53 =9007199254740992 (Hex 0x20000000000000). + +First to test, we will use (2^53) - 2 and see that it returns the correct value for the sum. + +``` +0:000> dx @$myScript.playWith64BitValues(9007199254740990, 9007199254740990) +Sum >> 18014398509481980 +``` + +Then we will calculate (2^53) -1 =9007199254740991. This returns the error indicating that the conversion process will lose precision, so this is the largest value that can be used with the sum method in JavaScript code. + +``` +0:000> dx @$myScript.playWith64BitValues(9007199254740990, 9007199254740991) +Error: 64 bit value loses precision on conversion to number +``` + +Call a data model method passing 64-bit values. There is no loss of precision here. + +``` +0:001> dx @$myScript.performOp64BitValues( 0x7FFFFFFFFFFFFFFF, 0x7FFFFFFFFFFFFFFF, (x, y) => x + y) +@$myScript.performOp64BitValues( 0x7FFFFFFFFFFFFFFF, 0x7FFFFFFFFFFFFFFF, (x, y) => x + y) : 0xfffffffffffffffe +``` + +**Comparison** + +The 64-bit library type is a JavaScript object and not a value type such as a JavaScript number. This has some implications for comparison operations. Normally, equality (==) on an object would indicate that operands refer to the same object and not the same value. The JavaScript provider mitigates this by tracking live references to 64-bit values and returning the same "immutable" object for non-collected 64-bit value. This means that for comparison, the following would occur. + +``` +// Comparison with 64 Bit Values + +function comparisonWith64BitValues(a64, b64) +{ + // + // No auto-conversion occurs here. This is an *EFFECTIVE* value comparison. This works with ordinals with above 53-bits of precision. + // + var areEqual = (a64 == b64); + host.diagnostics.debugLog("areEqual >> ", areEqual, "\n"); + var areNotEqual = (a64 != b64); + host.diagnostics.debugLog("areNotEqual >> ", areNotEqual, "\n"); + + // + // Auto-conversion occurs here. This will throw if a64 does not pack into a JavaScript number with no loss of precision. + // + var isEqualTo42 = (a64 == 42); + host.diagnostics.debugLog("isEqualTo42 >> ", isEqualTo42, "\n"); + var isLess = (a64 < b64); + host.diagnostics.debugLog("isLess >> ", isLess, "\n"); +``` + +Use a text editor such as Notepad to create a text file named *ComparisonWith64BitValues.js* + +Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load the JavaScript provider. + +``` +0:000> .load jsprovider.dll +``` + +Use the .scriptload command to load the script. + +``` +0:000> .scriptload c:\WinDbg\Scripts\ComparisonWith64BitValues.js +JavaScript script successfully loaded from 'c:\WinDbg\Scripts\ComparisonWith64BitValues.js' +``` + +To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command. + +``` +0:000> dx @$myScript = Debugger.State.Scripts.comparisonWith64BitValues.Contents +``` + +First to test, we will use (2^53) - 2 and see that it returns the expected values. + +``` +0:001> dx @$myScript.comparisonWith64BitValues(9007199254740990, 9007199254740990) +areEqual >> true +areNotEqual >> false +isEqualTo42 >> false +isLess >> false +``` + +We will also try the number 42 as the first value to validate the comparison operator is working as it should. + +``` +0:001> dx @$myScript.comparisonWith64BitValues(42, 9007199254740990) +areEqual >> false +areNotEqual >> true +isEqualTo42 >> true +isLess >> true +``` + +Then we will calculate (2^53) -1 =9007199254740991. This value returns the error indicating that the conversion process will lose precision, so this is the largest value that can be used with the comparison operators in JavaScript code. + +``` +0:000> dx @$myScript.playWith64BitValues(9007199254740990, 9007199254740991) +Error: 64 bit value loses precision on conversion to number +``` + +**Maintaining Precision in Operations** + +In order to allow a debugger extension to maintain precision, a set of math functions are projected on top of the 64-bit library type. If the extension needs (or may possibly) need precision above 53-bits for incoming 64-bit values, the following methods should be utilized instead of relying on standard operators: + +| | | | +|-------------------|---------------------------|---------------------------------------------------------------------------------------------------------------| +| **Method Name** | **Signature** | **Description** | +| asNumber | .asNumber() | Converts the 64-bit value to a JavaScript number. If loss of precision occurs, \*\*AN EXCEPTION IS THROWN\*\* | +| convertToNumber | .convertToNumber() | Converts the 64-bit value to a JavaScript number. If loss of precision occurs, \*\*NO EXCEPTION IS THROWN\*\* | +| getLowPart | .getLowPart() | Converts the lower 32-bits of the 64-bit value to a JavaScript number | +| getHighPart | .getHighPart() | Converts the high 32-bits of the 64-bit value to a JavaScript number | +| add | .add(value) | Adds a value to the 64-bit value and returns the result | +| subtract | .subtract(value) | Subtracts a value from the 64-bit value and returns the result | +| multiply | .multiply(value) | Multiplies the 64-bit value by the supplied value and returns the result | +| divide | .divide(value) | Divides the 64-bit value by the supplied value and returns the result | +| bitwiseAnd | .bitwiseAnd(value) | Computes the bitwise and of the 64-bit value with the supplied value and returns the result | +| bitwiseOr | .bitwiseOr(value) | Computes the bitwise or of the 64-bit value with the supplied value and returns the result | +| bitwiseXor | .bitwiseXor(value) | Computes the bitwise xor of the 64-bit value with the supplied value and returns the result | +| bitwiseShiftLeft | .bitwiseShiftLeft(value) | Shifts the 64-bit value left by the given amount and returns the result | +| bitwiseShiftRight | .bitwiseShiftRight(value) | Shifts the 64-bit value right by the given amount and returns the result | +| toString | .toString(\[radix\]) | Converts the 64-bit value to a display string in the default radix (or the optionally supplied radix) | + +  + +## JavaScript Resources + + +The following are JavaScript resources that may be useful as you develop JavaScript debugging extensions. + +- [Writing JavaScript Code](https://msdn.microsoft.com/library/cte3c772.aspx) + +- [JScript Language Tour](https://msdn.microsoft.com/library/t895bwkh.aspx) + +- [Mozilla JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript) + +- [WinJS: The Windows library for JavaScript](https://developer.microsoft.com/windows/develop/winjs) + +- [ECMAScript 6 — New Features: Overview & Comparison](http://es6-features.org/) + +## Related topics + + +[JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md) + +[Native Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20JavaScript%20Debugger%20Scripting%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md b/windows-driver-docs-pr/debugger/k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md new file mode 100644 index 0000000000..47380b7a5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md @@ -0,0 +1,236 @@ +--- +title: k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace) +description: The k* commands display the stack frame of the given thread, together with related information. +ms.assetid: 1061015f-cb0c-490b-b256-e0dedb659f22 +keywords: ["k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace) +api_type: +- NA +--- + +# k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace) + + +The **k*\**** commands display the stack frame of the given thread, together with related information.. + +User-Mode, x86 Processor + +``` +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = BasePtr [FrameCount] +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = BasePtr StackPtr InstructionPtr +[~Thread] kd [WordCount] +``` + +Kernel-Mode, x86 Processor + +``` +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr FrameCount +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = BasePtr StackPtr InstructionPtr +[Processor] kd [WordCount] +``` + +User-Mode, x64 Processor + +``` +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr FrameCount +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr InstructionPtr FrameCount +[~Thread] kd [WordCount] +``` + +Kernel-Mode, x64 Processor + +``` +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr FrameCount +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr InstructionPtr FrameCount +[Processor] kd [WordCount] +``` + +User-Mode, ARM Processor + +``` +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr FrameCount +[~Thread] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr InstructionPtr FrameCount +[~Thread] kd [WordCount] +``` + +Kernel-Mode, ARM Processor + +``` +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] [FrameCount] +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr FrameCount +[Processor] k[b|p|P|v] [c] [n] [f] [L] [M] = StackPtr InstructionPtr FrameCount +[Processor] kd [WordCount] +``` + +## Parameters + + + *Thread* +Specifies the thread whose stack is to be displayed. If you omit this parameter, the stack of the current thread is displayed. For more information about thread syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + *Processor* +Specifies the processor whose stack is to be displayed. For more information about processor syntax, see [Multiprocessor Syntax](multiprocessor-syntax.md). + + b +Displays the first three parameters that are passed to each function in the stack trace. + + c +Displays a clean stack trace. Each display line includes only the module name and the function name. + + p +Displays all of the parameters for each function that is called in the stack trace. The parameter list includes each parameter's data type, name, and value. The p option is case sensitive. This parameter requires full symbol information. + + P +Displays all of the parameters for each function that is called in the stack trace, like the p parameter. However, for P, the function parameters are printed on a second line of the display, instead of on the same line as the rest of the data. + + v +Displays frame pointer omission (FPO) information. On x86-based processors, the display also includes calling convention information. + + n +Displays frame numbers. + + f +Displays the distance between adjacent frames. This distance is the number of bytes that separate the frames on the actual stack. + + L +Hides source lines in the display. L is case sensitive. + + M +Displays output using [Debugger Markup Language](debugger-markup-language-commands.md). Each frame number in the display is a link that you can click to set the local context and display local variables. For information about the local context, see [**.frame**](-frame--set-local-context-.md). + + *FrameCount* +Specifies the number of stack frames to display. You should specify this number in hexadecimal format, unless you have changed the radix by using the [**n (Set Number Base)**](n--set-number-base-.md) command. The default value is 20 (0x14), unless you have changed the default value by using the [**.kframes (Set Stack Length)**](-kframes--set-stack-length-.md) command. + + *BasePtr* +Specifies the base pointer for the stack trace. The *BasePtr* parameter is available only if there is an equal sign (=) after the command. + + *StackPtr* +Specifies the stack pointer for the stack trace. If you omit *StackPtr* and *InstructionPtr*, the command uses the stack pointer that the rsp (or esp) register specifies and the instruction pointer that the rip (or eip) register specifies. + + *InstructionPtr* +Specifies the instruction pointer for the stack trace. If you omit *StackPtr* and *InstructionPtr*, the command uses the stack pointer that the rsp (or esp) register specifies and the instruction pointer that the rip (or eip) register specifies. + + *WordCount* +Specifies the number of DWORD\_PTR values in the stack to dump. The default value is 20 (0x14), unless you changed the default value by using the [**.kframes (Set Stack Length)**](-kframes--set-stack-length-.md) command. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +When you issue the **k**, **kb**, **kp**, **kP**, or **kv** command, a stack trace is displayed in a tabular format. If line loading is enabled, source modules and line numbers are also displayed. + +The stack trace includes the base pointer for the stack frame, the return address, and function names. + +If you use the **kp** or **kP** command, the full parameters for each function that is called in the stack trace are displayed. The parameter list includes each parameter's data type, name, and value. + +This command might be slow. For example, when **MyFunction1** calls **MyFunction2**, the debugger must have full symbol information for **MyFunction1** to display the parameters that are passed in this call. This command does not fully display internal Microsoft Windows routines that are not exposed in public symbols. + +If you use the **kb** or **kv** command, the first three parameters that are passed to each function are displayed. If you use the **kv** command, FPO data is also displayed. + +On an x86-based processor, the **kv** command also displays calling convention information. + +When you use the **kv** command, the FPO information is added at the end of the line in the following format. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FPO textMeaning
FPO: [non-Fpo]

No FPO data for the frame.

FPO: [N1,N2,N3]

N1 is the total number of parameters.

+

N2 is the number of DWORD values for the local variables.

+

N3 is the number of registers that are saved.

FPO: [N1,N2] TrapFrame @ Address

N1 is the total number of parameters.

+

N2 is the number of DWORD values for the locals.

+

Address is the address of the trap frame.

FPO: TaskGate Segment:0

Segment is the segment selector for the task gate.

FPO: [EBP 0xBase]

Base is the base pointer for the frame.

+ +  + +The **kd** command displays the raw stack data. Each DWORD value is displayed on a separate line. Symbol information is displayed for those lines together with associated symbols. This format creates a more detailed list than the other **k***\** commands. The **kd** command is equivalent to a [**dds (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command that uses the stack address as its parameter. + +If you use the **k** command at the beginning of a function (before the function prolog has been executed), you receive incorrect results. The debugger uses the frame register to compute the current backtrace, and this register is not set correctly for a function until its prolog has been executed. + +In user mode, the stack trace is based on the stack of the current thread. For more information about threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +In kernel mode, the stack trace is based on the current [register context](changing-contexts.md#register-context). You can set the register context to match a specific thread, context record, or trap frame. + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20k,%20kb,%20kc,%20kd,%20kp,%20kP,%20kv%20%28Display%20Stack%20Backtrace%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/k.md b/windows-driver-docs-pr/debugger/k.md new file mode 100644 index 0000000000..32d7a24ace --- /dev/null +++ b/windows-driver-docs-pr/debugger/k.md @@ -0,0 +1,63 @@ +--- +title: K (Windows Debugger Glossary) +description: Glossary page - K +Robots: noindex, nofollow +ms.assetid: 93b65114-f680-41f7-b754-699f773955ba +--- + +# K + + +**KD connection server** +A proxy used during some forms of kernel-mode remote debugging. It listens for connections from smart client and performs memory, processor, or Windows operations as requested by these remote clients. + +See also debugging server. + +For more information, see [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md). + +**kernel** +The kernel is the portion of the Windows operating system that manages and controls access to hardware resources. It performs thread scheduling and dispatching, interrupt and exception handling, and multiprocessor synchronization. + +**kernel error** +See bug check. + +**kernel mode** +Kernel-mode code has permission to access any part of the system, and is not restricted like user-mode code. It can gain access to any part of any other process running in either user mode or kernel mode. + +Performance-sensitive operating system components run in kernel mode. In this way they can interact with the hardware and with each other without the overhead of context switch. All the kernel-mode components are fully protected from applications running in user mode. They can be grouped as follows: + +- Executive. + + This contains the base operating system components such as memory management, process and thread management, security, I/O, interprocess communication. + +- Kernel. + + This performs low-level functions such as thread scheduling, interrupt and exception dispatching, and multiprocessor synchronization. It also provides a set of routines and basic objects used by the Executive to implement higher-level semantics. + +- Hardware Abstraction Layer (HAL). + + This handles all direct interface to hardware. It thus isolates the Windows Kernel, device drivers, and Windows Executive from platform-specific hardware differences. + +- Window and Graphics Subsystem. + + This implements the graphical user interface (GUI) functions. + +When a process erroneously accesses a portion of memory that is in use by another application or by the system, the lack of restrictions on kernel-mode processes forces Windows to stop the entire system. This is referred to as a bug check. + +Malfunctioning hardware devices or device drivers, which reside in kernel mode, are often the culprits in bug checks. + +**kernel-mode target** +See target computer. + +**kernel-mode debugging** +A debugger session in which the target is running in kernel mode. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20K%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kd-command-line-options.md b/windows-driver-docs-pr/debugger/kd-command-line-options.md new file mode 100644 index 0000000000..e38c2d190a --- /dev/null +++ b/windows-driver-docs-pr/debugger/kd-command-line-options.md @@ -0,0 +1,258 @@ +--- +title: KD Command-Line Options +description: First-time users of KD should begin with the Debugging Using KD and NTKD section. +ms.assetid: 76c11b45-8469-4f27-840d-06477d8922b8 +keywords: ["KD Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KD Command-Line Options +api_type: +- NA +--- + +# KD Command-Line Options + + +First-time users of KD should begin with the [Debugging Using KD and NTKD](debugging-using-kd-and-ntkd.md) section. + +The KD command line uses the following syntax. + +``` +kd [ -server ServerTransport | -remote ClientTransport ] + [-b | -x] [-d] [-bonc] [-m] [-myob] [-lines] [-n] [-r] [-s] + [-v] [-clines lines] [-failinc] [-noio] [-noshell] + [-secure] [-sdce] [-ses] [-sicv] [-sins] [-snc] [-snul] + [-sup] [-sflags 0xNumber] [-log{a|au|o|ou} LogFile] + [-aExtension] [-zp PageFile] + [-i ImagePath] [-y SymbolPath] [-srcpath SourcePath] + [-k ConnectType | -kl | -kqm | -kx ExdiOptions] [-ee {masm|c++}] + [-z DumpFile] [-cf "filename"] [-cfr "filename"] [-c "command"] + [-t PrintErrorLevel] [-version] + +kd -iu KeyString + +kd -QR Server + +kd -wake PID + +kd -? +``` + +Descriptions of the KD command-line options follow. Only the **-remote** and **-server** options are case-sensitive. The initial hyphen can be replaced with a forward-slash (/). Options which do not take any additional parameters can be concatenated -- so **kd -r -n -v** can be written as **kd -rnv**. + +If the **-remote** or **-server** option is used, it must appear before any other options on the command line. + +## Parameters + + + **-server** *ServerTransport* +Creates a debugging server that can be accessed by other debuggers. For an explanation of the possible *ServerTransport*, see [**Activating a Debugging Server**](activating-a-debugging-server.md). When this parameter is used, it must be the first parameters on the command line. + + **-remote** *ClientTransport* +Creates a debugging client, and connects to a debugging server that is already running. For an explanation of the possible *ClientTransport* values, see [**Activating a Debugging Client**](activating-a-debugging-client.md). When this parameter is used, it must be the first parameters on the command line. + + **-a** *Extension* +Sets the default extension DLL. The default is kdextx86.dll or kdexts.dll. There must be no space after the "a", and the .dll file name extension must not be included. For details, and other methods of setting this default, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + + **-b** +This option no longer supported. + + **-bonc** +If this option is specified, the debugger will break into the target as soon as the session begins. This is especially useful when connecting to a debugging server that might not be currently broken into the target. + + **-c "***command***"** +Specifies the initial debugger command to run at start-up. This command must be surrounded with quotation marks. Multiple commands can be separated with semicolons. (If you have a long command list, it may be easier to put them in a script and then use the **-c** option with the [**$<, $><, $><, $$>< (Run Script File)**](-----------------------a---run-script-file-.md) command.) + +If you are starting a debugging client, this command must be intended for the debugging server. Client-specific commands, such as **.lsrcpath**, are not allowed. + + **-cf "***filename***"** +Specifies the path and name of a script file. This script file is executed as soon as the debugger is started. If *filename* contains spaces it must be enclosed in quotation marks. If the path is omitted, the current directory is assumed. If the -cf option is not used, the file ntsd.ini in the current directory is used as the script file. If the file does not exist, no error occurs. For details, see [Using Script Files](using-script-files.md). + + **-cfr "***filename***"** +Specifies the path and name of a script file. This script file is executed as soon as the debugger is started, and any time the target is restarted. If *filename* contains spaces it must be enclosed in quotation marks. If the path is omitted, the current directory is assumed. If the file does not exist, no error occurs. For details, see [Using Script Files](using-script-files.md). + + **-clines** *lines* +Sets the approximate number of commands in the command history which can be accessed during remote debugging. For details, and for other ways to change this number, see [Using Debugger Commands](using-debugger-commands.md). + + **-d** +After a reboot, the debugger will break into the target computer as soon as a kernel module is loaded. (This break is earlier than the break from the **-b** option.) See [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) for details and for other methods of changing this status. + + **-ee** {**masm**|**c++**} +Sets the default expression evaluator. If **masm** is specified, MASM expression syntax will be used. If **c++** is specified, C++ expression syntax will be used. If the **-ee** option is omitted, MASM expression syntax is used as the default. See [Evaluating Expressions](evaluating-expressions.md) for details. + + **-failinc** +Causes the debugger to ignore any questionable symbols. When debugging a user-mode or kernel-mode minidump file, this option will also prevent the debugger from loading any modules whose images can't be mapped. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-i** *ImagePath* +Specifies the location of the executables that generated the fault. If the path contains spaces, it should be enclosed in quotation marks. + + **-iu** *KeyString* +Registers debugger remoting as an URL type so that users can auto-launch a debugger remote client with an URL. *KeyString* has the format `remdbgeng://RemotingOption`. *RemotingOption* is a string that defines the transport protocol as defined in the topic [**Activating a Debugging Client**](activating-a-debugging-client.md). If this action succeeds, no message is displayed; if it fails, an error message is displayed. + +The **-iu** parameter must not be used with any other parameters. This command will not actually start KD. + + **-k** *ConnectType* +Tells the debugger how to connect to the target. For details, see [Debugging Using KD and NTKD](debugging-using-kd-and-ntkd.md). + + **-kl** +(Windows XP and later) Starts a kernel debugging session on the same machine as the debugger. + + **-kqm** +Starts KD in quiet mode. + + **-kx** *ExdiOptions* +Starts a kernel debugging session using an EXDI driver. EXDI drivers are not described in this documentation. If you have an EXDI interface to your hardware probe or hardware simulator, please contact Microsoft for debugging information. + + **-lines** +Enables source line debugging. If this option is omitted, the [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command will have to be used before source debugging will be allowed. For other methods of controlling this, see [SYMOPT\_LOAD\_LINES](symbol-options.md#symopt-load-lines). + + **-log**{**a|au|o|ou**} *LogFile* +Begins logging information to a log file. If *LogFile* already exists, it will be overwritten if **-logo** is used, or output will be appended to the file if **-loga** is used. The **-logau** and **-logou** options operate similar to **-loga** and **-logo** respectively, except that the log file is a Unicode file. For more details, see [Keeping a Log File in KD](keeping-a-log-file-in-kd.md). + + **-m** +Indicates that the serial port is connected to a modem. Instructs the debugger to watch for the carrier-detect signal. + + **-myob** +If there is a version mismatch with dbghelp.dll, the debugger will continue to run. (Without the **-myob** switch, this is considered a fatal error.) + +A secondary effect of this option is that the warning that normally appears when breaking into the target computer is suppressed. + + **-n** +*Noisy symbol load*: Enables verbose output from symbol handler. For details and for other methods of controlling this, see [SYMOPT\_DEBUG](symbol-options.md#symopt-debug). + + **-noio** +Prevents the debugging server from being used for input or output. Input will only be accepted from the debugging client (plus any initial command or command script specified by the **-c** command-line option). + +All output will be directed to the debugging client. For more details, see [**Activating a Debugging Server**](activating-a-debugging-server.md). + + **-noshell** +Prohibits all **.shell** commands. This prohibition will last as long as the debugger is running, even if a new debugging session is begun. For details, and for other ways to disable shell commands, see [Using Shell Commands](using-shell-commands.md). + + **-QR** *Server* +Lists all debugging servers running on the specified network server. The double backslash (**\\\\**) preceding *Server* is optional. See [**Searching for Debugging Servers**](searching-for-debugging-servers.md) for details. + +The **-QR** parameter must not be used with any other parameters. This command will not actually start KD. + + **-r** +Displays registers. + + **-s** +Disables lazy symbol loading. This will slow down process startup. For details and for other methods of controlling this, see [SYMOPT\_DEFERRED\_LOADS](symbol-options.md#symopt-deferred-loads). + + **-sdce** +Causes the debugger to display **File access error** dialog boxes during symbol load. For details and for other methods of controlling this, see [SYMOPT\_FAIL\_CRITICAL\_ERRORS](symbol-options.md#symopt-fail-critical-errors). + + **-secure** +Activates [Secure Mode](secure-mode.md). + + **-ses** +Causes the debugger to perform a strict evaluation of all symbol files and ignore any questionable symbols. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-sflags 0x***Number* +Sets all the symbol handler options at once. *Number* should be a hexadecimal number prefixed with **0x** -- a decimal without the **0x** is permitted, but the symbol options are binary flags and therefore hexadecimal is recommended. This option should be used with care, since it will override all the symbol handler defaults. For details, see [Setting Symbol Options](symbol-options.md). + + **-sicv** +Causes the symbol handler to ignore the CV record. For details and for other methods of controlling this, see [SYMOPT\_IGNORE\_CVREC](symbol-options.md#symopt-ignore-cvrec). + + **-sins** +Causes the debugger to ignore the symbol path and executable image path environment variables. For details, see [SYMOPT\_IGNORE\_NT\_SYMPATH](symbol-options.md#symopt-ignore-nt-sympath). + + **-snc** +Causes the debugger to turn off C++ translation. For details and for other methods of controlling this, see [SYMOPT\_NO\_CPP](symbol-options.md#symopt-no-cpp). + + **-snul** +Disables automatic symbol loading for unqualified names. For details and for other methods of controlling this, see [SYMOPT\_NO\_UNQUALIFIED\_LOADS](symbol-options.md#symopt-no-unqualified-loads). + + **-srcpath** *SourcePath* +Specifies the source file search path. Separate multiple paths with a semicolon (**;**). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Source Path](source-path.md). + + **-sup** +Causes the symbol handler to search the public symbol table during every symbol search. For details and for other methods of controlling this, see [SYMOPT\_AUTO\_PUBLICS](symbol-options.md#symopt-auto-publics). + + **-t** *PrintErrorLevel* +Specifies the error level that will cause the debugger to display an error message. This is a decimal number equal to 0, 1, 2, or 3. The values are described as follows: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueConstantMeaning

0

NONE

Do not display any errors.

1

ERROR

Display ERROR level debugging events.

2

MINORERROR

Display MINORERROR and ERROR level debugging events.

3

WARNING

Display WARNING, MINORERROR, and ERROR level debugging events.

+ +  + +This error level only has meaning in checked builds of Microsoft Windows. The default value is 1. + + **-v** +Generates verbose messages for loads, deferred loads, and unloads. + + **-version** +Prints the debugger version string. + + **-wake** *PID* +Causes sleep mode to end for the user-mode debugger whose process ID is specified by *PID*. This command must be issued on the target machine during sleep mode. See [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) for details. + +The **-wake** parameter must not be used with any other parameters. This command will not actually start KD. + + **-x** +Causes the debugger to break in when an exception first occurs, rather than letting the application or module that caused the exception deal with it. (Same as **-b**, except with an initial **eb nt!NtGlobalFlag 9;g** command.) + + **-y** *SymbolPath* +Specifies the symbol search path. Separate multiple paths with a semicolon (**;**). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Symbol Path](symbol-path.md). + + **-z** *DumpFile* +Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several dump files at once by including multiple **-z** options, each followed by a different *DumpFile* value. For details, see [Analyzing a Kernel-Mode Dump File with KD](analyzing-a-kernel-mode-dump-file-with-kd.md). + + **-zp** *PageFile* +Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the [**.pagein (Page In Memory)**](-pagein--page-in-memory-.md) command. You cannot use **-zp** with a standard Windows page file—only specially-modified page files can be used. + + **-?** +Displays command-line help text. + +KD will automatically detect the platform on which the target is running. You do not need to specify the target on the KD command line. The older syntax (using the name *I386KD* or *IA64KD*) is obsolete. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20KD%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kd-connection-server-examples.md b/windows-driver-docs-pr/debugger/kd-connection-server-examples.md new file mode 100644 index 0000000000..cf8c029189 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kd-connection-server-examples.md @@ -0,0 +1,76 @@ +--- +title: KD Connection Server Examples +description: KD Connection Server Examples +ms.assetid: 5e54dda7-4f79-40e3-bcc5-248a3a047e31 +keywords: ["KD connection server, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# KD Connection Server Examples + + +## + + +Suppose a debugging technician is not present at the site where the computer to be debugged is located. The debugging technician asks someone at this site to connect this target computer to some other computer with a debug cable. + +Let this other computer be at IP address 127.0.0.42. The debug cable connects COM1 on this computer to whichever port has been debug-enabled on the target computer. The KD connection server is started with this command: + +``` +E:\Debugging Tools for Windows> kdsrv -t tcp:port=1027 +``` + +Then at the other location, the technician starts WinDbg as a smart client with this command: + +``` +G:\Debugging Tools> windbg -k kdsrv:server=@{tcp:server=127.0.0.42,port=1027},trans=@{com:port=com1,baud=57600} -y SymbolPath +``` + +The symbol path will be relative to the computer where the smart client is running. + +Here is another example. In this case, NPIPE protocol is chosen, and KD is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric string -- in this example, "KernelPipe". The first user opens an elevated Command Prompt window (Run as Administrator) and starts a debugging server by entering these commands: + +``` +E:\Debugging Tools for Windows> set _NT_DEBUG_PORT=com1 +E:\Debugging Tools for Windows> kdsrv -t npipe:pipe=KernelPipe +``` + +The technician is logged on to the client computer with an account that does not have access to the server computer. But the technician knows the username and password for an account that does have access to the server computer. The username for that account is Contoso. The technician enters the following command: + +``` +net use \\BOX17\ipc$ /user:Contoso +``` + +When prompted, the technician enters the password for the Contoso account. + +The technician is not sure what name was used for the named pipe, so she queries 127.0.0.42 for KD connection servers: + +``` +G:\Debugging Tools> cdb -QR 127.0.0.42 +Servers on 127.0.0.42: +Debugger Server - npipe:Pipe=MainPipe +Remote Process Server - npipe:Pipe=AnotherPipe +Remote Kernel Debugger Server - npipe:Pipe=KernelPipe +``` + +Three pipes are shown. However, only one is a KD connection server -- the others are a debugging server and a user-mode process server. The technician enters the following command can to start the smart client: + +``` +G:\Debugging Tools> kd -k kdsrv:server=@{npipe:server=127.0.0.42,pipe=KernelPipe},trans=@{com:baud=57600} -y SymbolPath +``` + +Notice that although the baud rate is specified, the port is not. This causes the debugger to default to the port specified by \_NT\_DEBUG\_PORT on the computer where KdSrv is running. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20KD%20Connection%20Server%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kd-connection-servers--kernel-mode-.md b/windows-driver-docs-pr/debugger/kd-connection-servers--kernel-mode-.md new file mode 100644 index 0000000000..7b3439ba25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kd-connection-servers--kernel-mode-.md @@ -0,0 +1,47 @@ +--- +title: KD Connection Servers (Kernel Mode) +description: KD Connection Servers (Kernel Mode) +ms.assetid: fe0c9110-8fbf-46ae-ae1d-75ab5231aef3 +keywords: ["remote debugging through a KD connection server", "KD connection server", "KD connection server, overview", "smart client (kernel mode)", "KdSrv", "KdSrv, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# KD Connection Servers (Kernel Mode) + + +## + + +Kernel-mode remote debugging through a KD connection server involves running a small application called a *KD connection server* on the server. Then a kernel-mode debugger is started on the client. Since this debugger will be doing all of the actual processing, it is called the *smart client*. + +The Debugging Tools for Windows package includes a KD connection server called KdSrv (kdsrv.exe). + +The two computers do not have to be running the same version of Windows; they can be running any version of Windows. However, the debugger binaries used on the client and the KdSrv binary used on the server must be from the same release of the Debugging Tools for Windows package. This method cannot be used for dump-file debugging. + +To set up this remote session, the KD connection server is set up first, and then the smart client is activated. Any number of smart clients can operate through a single KD connection server, but they must each be connected to a different kernel debugging session. + +This section includes: + +[Activating a KD Connection Server](activating-a-kd-connection-server.md) + +[Searching for KD Connection Servers](searching-for-kd-connection-servers.md) + +[Activating a Smart Client (Kernel Mode)](activating-a-smart-client--kernel-mode-.md) + +[KD Connection Server Examples](kd-connection-server-examples.md) + +[Controlling a KD Connection Server Session](controlling-a-kd-connection-server-session.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20KD%20Connection%20Servers%20%28Kernel%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kdbgctrl-command-line-options.md b/windows-driver-docs-pr/debugger/kdbgctrl-command-line-options.md new file mode 100644 index 0000000000..a67504ad3c --- /dev/null +++ b/windows-driver-docs-pr/debugger/kdbgctrl-command-line-options.md @@ -0,0 +1,129 @@ +--- +title: KDbgCtrl Command-Line Options +description: The KDbgCtrl command line uses the following syntax +ms.assetid: 0367a09d-c475-4aeb-8f88-47d51ec7e9d5 +keywords: ["KDbgCtrl Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KDbgCtrl Command-Line Options +api_type: +- NA +--- + +# KDbgCtrl Command-Line Options + + +The KDbgCtrl command line uses the following syntax: + +``` +kdbgctrl [-e|-d|-c] [-ea|-da|-ca] [-eu|-du|-cu] [-eb|-db|-cb] [-sdb Size | -cdb] + +kdbgctrl -cx + +kdbgctrl -td ProcessID File + +kdbgctrl -? +``` + +## Parameters + + + **-e** +Enables Full Kernel Debugging. + + **-d** +Disables Full Kernel Debugging. + + **-c** +Checks whether Full Kernel Debugging is enabled. Displays true if Full Kernel Deubugging is enabled, and displays false if Full Kernel Debugging is disabled. + + **-ea** +Enables Automatic Kernel Debugging. + + **-da** +Disables Automatic Kernel Debugging. + + **-ca** +Checks whether Automatic Kernel Debugging is enabled. Displays true if Automatic Kernel Deubugging is enabled, and displays false if Automatic Kernel Debugging is disabled. + + **-eu** +Enables User-Mode Error Handling. + + **-du** +Disables User-Mode Error Handling. + + **-cu** +Checks whether User-Mode Error Handling is enabled. Displays true if User-Mode Error Handling is enabled, and displays false if User-Mode Error Handling is disabled. + +**-eb** +Enables blocking of kernel debugging. + +**-db** +Disables blocking of kernel debugging + +**-cb** +Checks whether kernel debugging is blocked. Displays true if kernel debugging is blocked, and displays false if kernel debugging is not blocked. + + **-sdb** *Size* +Sets the size of the DbgPrint buffer. If *Size* is prefixed with **0x** it will be interpreted as a hexadecimal number. If it is prefixed with **0** (zero), it will be interpreted as octal. Otherwise, it will be interpreted as decimal. + + **-cdb** +Displays the current size, in bytes, of the DbgPrint buffer. + + **-cx** +Determines the current Full Kernel Debugging setting and returns an appropriate value. This option cannot be combined with other options, and it does not display any output. It is designed for use in a batch file where the return value of the KDbgCtrl program can be tested. Possible return values are as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + +
ValueMeaning

0x10001

Full Kernel Debugging is enabled.

0x10002

Full Kernel Debugging is disabled.

Any other value

An error occurred. KDbgCtrl was unable to determine the current status of Full Kernel Debugging.

+ +  + +**-td** *ProcessID* *File* +Obtains a kernel triage dump file. Enter the process ID and a name for the dump file. + + **-?** +Displays command-line help for KDbgCtrl. + +### Additional Information + +For a description of all the KDbgCtrl settings, see [Using KDbgCtrl](using-kdbgctrl.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20KDbgCtrl%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kdsrv-command-line-options.md b/windows-driver-docs-pr/debugger/kdsrv-command-line-options.md new file mode 100644 index 0000000000..4e57d2036d --- /dev/null +++ b/windows-driver-docs-pr/debugger/kdsrv-command-line-options.md @@ -0,0 +1,46 @@ +--- +title: KdSrv Command-Line Options +description: The KdSrv command line uses the following syntax. +ms.assetid: 95b144c0-4507-4ce4-b828-1ac385dd7165 +keywords: ["KdSrv Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- KdSrv Command-Line Options +api_type: +- NA +--- + +# KdSrv Command-Line Options + + +The KdSrv command line uses the following syntax. + +``` +kdsrv -t ServerTransport +``` + +## Parameters + + + **-t** *ServerTransport* +Specifies the transport protocol. For a list of the possible protocols and the syntax for *ServerTransport* in each case, see [**Activating a KD Connection Server**](activating-a-kd-connection-server.md). + +If you type **kdsrv** with no parameters, a message box with help text appears. + +For information about using KdSrv, see [KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20KdSrv%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/keeping-a-log-file-in-cdb.md b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-cdb.md new file mode 100644 index 0000000000..28080f2c6a --- /dev/null +++ b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-cdb.md @@ -0,0 +1,55 @@ +--- +title: Keeping a Log File in CDB +description: Keeping a Log File in CDB +ms.assetid: 02164ABF-BF57-4E1D-BD4B-CEEE60E0D7D0 +--- + +# Keeping a Log File in CDB + + +## + + +CDB can write a log file that records the debugging session. This log file contains all of the commands that you type and the responses from the debugger. + +### Opening a New Log File + +To open a new log file, or to overwrite a previous log file, do one of the following: + +- Before you start the debugger, set the \_NT\_DEBUG\_LOG\_FILE\_OPEN [environment variable](environment-variables.md). + +- When you start the debugger, use the **-logo** command-line option. + +- Enter the [**.logopen (Open Log File)**](-logopen--open-log-file-.md) command. If you use the **/t** option, the date and time are appended to your specified file name. If you use the **/u** option, the log file is written in Unicode instead of in ASCII. + +### Appending to an Existing Log File + +To append command window text to a log file, do one of the following: + +- Before you start the debugger, set the \_NT\_DEBUG\_LOG\_FILE\_APPEND [environment variable](environment-variables.md). + +- When you start the debugger, use the **-loga** command-line option. + +- Enter the [**.logappend (Append Log File)**](-logappend--append-log-file-.md) command. If you are appending to a Unicode log file, you must use the **/u** option. + +### Closing a Log File + +To close an open log file, do the following: + +- Enter the [**.logclose (Close Log File)**](-logclose--close-log-file-.md) command. + +### Checking Log File Status + +To determine the log file status, do the following: + +- Enter the [**.logfile (Display Log File Status)**](-logfile--display-log-file-status-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Keeping%20a%20Log%20File%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/keeping-a-log-file-in-kd.md b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-kd.md new file mode 100644 index 0000000000..d49a8564b3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-kd.md @@ -0,0 +1,55 @@ +--- +title: Keeping a Log File in KD +description: Keeping a Log File in KD +ms.assetid: 8A260D7F-5E05-4DD0-9CDF-56D3A0C4C2B6 +--- + +# Keeping a Log File in KD + + +## + + +KD can write a log file that records the debugging session. This log file contains all of the commands that you type and the responses from the debugger. + +### Opening a New Log File + +To open a new log file, or to overwrite a previous log file, do one of the following: + +- Before you start the debugger, set the \_NT\_DEBUG\_LOG\_FILE\_OPEN [environment variable](environment-variables.md). + +- When you start the debugger, use the **-logo** command-line option. + +- Enter the [**.logopen (Open Log File)**](-logopen--open-log-file-.md) command. If you use the **/t** option, the date and time are appended to your specified file name. If you use the **/u** option, the log file is written in Unicode instead of in ASCII. + +### Appending to an Existing Log File + +To append text to an existing log file, do one of the following: + +- Before you start the debugger, set the \_NT\_DEBUG\_LOG\_FILE\_APPEND [environment variable](environment-variables.md). + +- When you start the debugger, use the **-loga** command-line option. + +- Enter the [**.logappend (Append Log File)**](-logappend--append-log-file-.md) command. If you are appending to a Unicode log file, you must use the **/u** option. + +### Closing a Log File + +To close an open log file, do the following: + +- Enter the [**.logclose (Close Log File)**](-logclose--close-log-file-.md) command. + +### Checking Log File Status + +To determine the log file status, do the following: + +- Enter the [**.logfile (Display Log File Status)**](-logfile--display-log-file-status-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Keeping%20a%20Log%20File%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/keeping-a-log-file-in-visual-studio.md b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-visual-studio.md new file mode 100644 index 0000000000..4e4df12e67 --- /dev/null +++ b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-visual-studio.md @@ -0,0 +1,43 @@ +--- +title: Keeping a Log File in Visual Studio +description: The Windows Debugger can write a log file that records the debugging session. +ms.assetid: 6A7588D0-A477-4BE9-874F-3AFB52561903 +--- + +# Keeping a Log File in Visual Studio + + +The Windows Debugger can write a log file that records the debugging session. This log file contains all of the commands that you type and the responses from the debugger. In Microsoft Visual Studio, you can open, append, and close log files by entering commands in the Debugger Immediate Window. + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +## + + +If the Debugger Immediate Window is not already open, from the **Debug** menu, choose **Windows>Immediate**. + +### Opening a New Log File + +To open a new log file, enter the [**.logopen (Open Log File)**](-logopen--open-log-file-.md) command. If you use the **/t** option, the date and time are appended to your specified file name. If you use the **/u** option, the log file is written in Unicode instead of in ASCII. + +### Appending to an Existing Log File + +To append text to an existing log file, enter the [**.logappend (Append Log File)**](-logappend--append-log-file-.md) command. If you are appending to a Unicode log file, you must use the **/u** option. + +### Closing a Log File + +To close an open log file, enter the [**.logclose (Close Log File)**](-logclose--close-log-file-.md) command. + +### Checking Log File Status + +To determine the log file status, enter the [**.logfile (Display Log File Status)**](-logfile--display-log-file-status-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Keeping%20a%20Log%20File%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/keeping-a-log-file-in-windbg.md b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-windbg.md new file mode 100644 index 0000000000..b03d4a8a08 --- /dev/null +++ b/windows-driver-docs-pr/debugger/keeping-a-log-file-in-windbg.md @@ -0,0 +1,59 @@ +--- +title: Keeping a Log File in WinDbg +description: Keeping a Log File in WinDbg +ms.assetid: 96CFF42B-CBBB-40F7-8CD3-1CF4A538A963 +--- + +# Keeping a Log File in WinDbg + + +## + + +WinDbg can write a log file that records the debugging session. This log file contains all of the contents of the [Debugger Command window](debugger-command-window.md), including the commands that you type and the responses from the debugger. + +### Opening a New Log File + +To open a new log file, or to overwrite a previous log file, do one of the following: + +- Choose **Open/Close Log file** from the **Edit** menu. + +- When you start WinDbg in a Command Prompt window, use the **-logo** command-line option. + +- Enter the [**.logopen (Open Log File)**](-logopen--open-log-file-.md) command. If you use the **/t** option, the date and time are appended to your specified file name. If you use the **/u** option, the log file is written in Unicode instead of in ASCII. + +### Appending to an Existing Log File + +To append command window text to a log file, do one of the following: + +- Choose **Open/Close Log file** from the **Edit** menu. + +- When you start WinDbg in a Command Prompt window, use the **-loga** command-line option. + +- Enter the [**.logappend (Append Log File)**](-logappend--append-log-file-.md) command. If you are appending to a Unicode log file, you must use the **/u** option. + +### Closing a Log File + +To close an open log file, do one of the following: + +- Choose **Open/Close Log file** from the **Edit** menu. + +- Enter the [**.logclose (Close Log File)**](-logclose--close-log-file-.md) command. + +### Checking Log File Status + +To determine the log file status, do one of the following: + +- Choose **Open/Close Log file** from the **Edit** menu, and see whether a log file is listed. + +- Enter the [**.logfile (Display Log File Status)**](-logfile--display-log-file-status-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Keeping%20a%20Log%20File%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-memory-dump.md b/windows-driver-docs-pr/debugger/kernel-memory-dump.md new file mode 100644 index 0000000000..836e2411ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-memory-dump.md @@ -0,0 +1,49 @@ +--- +title: Kernel Memory Dump +description: Kernel Memory Dump +ms.assetid: 466f5b92-c9bd-4050-9ef8-469979ba0cbe +keywords: ["dump file, Kernel Memory Dump", "Kernel Memory Dump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel Memory Dump + + +## + + +A *Kernel Memory Dump* contains all the memory in use by the kernel at the time of the crash. + +This kind of dump file is significantly smaller than the Complete Memory Dump. Typically, the dump file will be around one-third the size of the physical memory on the system. This quantity will vary considerably, depending on your circumstances. + +This dump file will not include unallocated memory, or any memory allocated to user-mode applications. It only includes memory allocated to the Windows kernel and hardware abstraction level (HAL), as well as memory allocated to kernel-mode drivers and other kernel-mode programs. + +For most purposes, this crash dump is the most useful. It is significantly smaller than the Complete Memory Dump, but it only omits those portions of memory that are unlikely to have been involved in the crash. + +Since this kind of dump file does not contain images of any user-mode executables residing in memory at the time of the crash, you may also need to set the executable image path if these executables turn out to be important. + +The Kernel Memory Dump file is written to %SystemRoot%\\Memory.dmp by default. + +If a second bug check occurs and another Kernel Memory Dump (or Complete Memory Dump) is created, the previous file will be overwritten. + +To suppress missing page error messages when debugging a Kernel Memory Dump, use the [**.ignore\_missing\_pages**](-ignore-missing-pages--suppress-missing-page-errors-.md) command. + +## Related topics + + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-debugging.md b/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-debugging.md new file mode 100644 index 0000000000..2982e854f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-debugging.md @@ -0,0 +1,38 @@ +--- +title: Kernel-Mode Driver Framework Debugging +description: Kernel-Mode Driver Framework Debugging +ms.assetid: bec840f8-b500-464f-8e49-53f03f34aa6a +keywords: ["Kernel-Mode Driver Framework debugging", "Windows Driver Foundation"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Driver Framework Debugging + + +Debugging extensions for Kernel-Mode Driver Framework (KMDF) are contained in the Wdfkd.dll extension library. + +You can use the extension commands that the Wdfkd.dll extension library contains to debug drivers that use KMDF. + +For a description of the extension commands in Wdfkd.dll, see [Kernel-Mode Driver Framework Extensions (Wdfkd.dll)](kernel-mode-driver-framework-extensions--wdfkd-dll-.md). + +These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions; these restrictions are noted on the individual reference pages. + +**Note**  When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. If your driver name exceeds the maximum length, your driver will fail to load. + +  + +To use this extension library, you must load the library into your debugger. For information about how to load extension libraries into a debugger, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel-Mode%20Driver%20Framework%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-extensions--wdfkd-dll-.md b/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-extensions--wdfkd-dll-.md new file mode 100644 index 0000000000..0a49b369b7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-mode-driver-framework-extensions--wdfkd-dll-.md @@ -0,0 +1,34 @@ +--- +title: Windows Driver Framework Extensions (Wdfkd.dll) +description: Windows Driver Framework Extensions (Wdfkd.dll) +ms.assetid: 2fa2b131-f6fd-459b-a4e3-799246076338 +keywords: ["Kernel-Mode Driver Framework debugging, extensions (wdfkd.dll)", "Kernel-Mode Driver Framework extensions (wdfkd.dll)", "wdfkd.dll (Kernel-Mode Driver Framework extensions)", "extensions, Kernel-Mode Driver Framework"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Windows Driver Framework Extensions (Wdfkd.dll) + + +Extension commands that are useful for debugging drivers built with the Kernel-Mode Driver Framework (KMDF) or version 2 of the User-Mode Driver Framework (UMDF 2) are implemented in Wdfkd.dll. + +These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions; these restrictions are noted on the individual reference pages. + +**Note**  When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. If your driver name exceeds the maximum length, your driver will fail to load. + +  + +For more information about how to use these extensions, see [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Windows%20Driver%20Framework%20Extensions%20%28Wdfkd.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-mode-dump-files.md b/windows-driver-docs-pr/debugger/kernel-mode-dump-files.md new file mode 100644 index 0000000000..127058be4c --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-mode-dump-files.md @@ -0,0 +1,49 @@ +--- +title: Kernel-Mode Dump Files +description: Kernel-Mode Dump Files +ms.assetid: f04dc580-0e14-41aa-88a2-e04f4406add8 +keywords: ["dump file, kernel mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Dump Files + + +## + + +When a kernel-mode error occurs, the default behavior of Microsoft Windows is to display the blue screen with bug check data. + +However, there are several alternative behaviors that can be selected: + +- A kernel debugger (such as WinDbg or KD) can be contacted. + +- A memory dump file can be written. + +- The system can automatically reboot. + +- A memory dump file can be written, and the system can automatically reboot afterwards. + +This section covers how to create and analyze a kernel-mode memory dump file. There are three different varieties of crash dump files. However, it should be remembered that no dump file can ever be as useful and versatile as a live kernel debugger attached to the system that has failed. + +This section includes: + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +[Creating a Kernel-Mode Dump File](creating-a-kernel-mode-dump-file.md) + +[Analyzing a Kernel-Mode Dump File](analyzing-a-kernel-mode-dump-file.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel-Mode%20Dump%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-mode-environment-variables.md b/windows-driver-docs-pr/debugger/kernel-mode-environment-variables.md new file mode 100644 index 0000000000..ffde1552c2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-mode-environment-variables.md @@ -0,0 +1,92 @@ +--- +title: Kernel-Mode Environment Variables +description: Kernel-Mode Environment Variables +ms.assetid: 619ebe55-1b57-4182-ada9-0c99c78056b3 +keywords: ["environment variables, kernel-mode", "_NT_DEBUG_PORT environment variable", "_NT_DEBUG_BAUD_RATE environment variable", "KDQUIET environment variable", "_NT_DEBUG_CACHE_SIZE environment variable", "_NT_DEBUG_BUS environment variable", "_NT_DEBUG_1394_CHANNEL environment variable", "_NT_DEBUG_1394_SYMLINK environment variable", "_NT_DEBUG_OPTIONS environment variable"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Environment Variables + + +## + + +The following table lists the environment variables that are used only in kernel-mode debugging. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableMeaning

_NT_DEBUG_PORT = ComPort

Specifies the COM port to be used in a kernel connection. For details, see [Getting Set Up for Debugging](getting-set-up-for-debugging.md).

_NT_DEBUG_BAUD_RATE = BaudRate

Specifies the baud rate to be used over the COM port connection.

_NT_DEBUG_BUS = 1394

Specifies that kernel debugging will be done over a 1394 cable connection.

_NT_DEBUG_1394_CHANNEL = 1394Channel

Specifies the channel to be used for the 1394 kernel connection.

_NT_DEBUG_1394_SYMLINK = Protocol

Specifies the connection protocol to be used for the 1394 kernel connection.

KDQUIET =Anything

If KDQUIET is defined, the debugger will run in quiet mode. Quiet mode involves three distinct effects:

+

1. The debugger does not display messages each time an extension DLL is loaded or unloaded.

+

2. The [r (Registers)](r--registers-.md) command no longer requires an equal sign in its syntax.

+

3. The debugger will not display a warning message when breaking into the target computer.

+

Quiet mode can also be controlled by using the [sq (Set Quiet Mode)](sq--set-quiet-mode-.md) command.

+_NT_DEBUG_CACHE_SIZE += Size

Specifies the maximum kernel debugging cache size, in bytes. This cache holds data received by the host computer from the serial connection. The default is 1,024,000.

_NT_DEBUG_OPTIONS = Option

Specifies one of the following two values:

+

NOEXTWARNING tells the debugger not to output a warning when it cannot find an extension command.

+

NOVERSIONCHECK tells the debugger not to check the version of debugger extensions.

+

+

These options can be modified or displayed by using the [so (Set Kernel Options)](so--set-kernel-debugging-options-.md) command.

_NT_KD_FILES = MapFile

Specifies a driver replacement map file. For details and for other methods of controlling driver replacement, see [Mapping Driver Files](mapping-driver-files.md).

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel-Mode%20Environment%20Variables%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-mode-extensions.md b/windows-driver-docs-pr/debugger/kernel-mode-extensions.md new file mode 100644 index 0000000000..686a0d12a0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-mode-extensions.md @@ -0,0 +1,37 @@ +--- +title: Kernel-Mode Extensions +description: Kernel-Mode Extensions +ms.assetid: e8e1e692-d991-427f-a2e7-b9eb1893fe83 +keywords: ["extension commands ( commands), kernel-mode extensions", "kdextx86.dll (kernel-mode extensions)", "kdexts.dll (kernel-mode extensions)", "kext.dll (kernel-mode extensions)", "kernel-mode extensions (kdext .dll and kext.dll)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Extensions + + +## + + +This section of the reference describes extension commands that are primarily used during kernel-mode debugging. + +The debugger will automatically load the proper version of these extension commands. Unless you have manually loaded a different version, you do not have to keep track of the DLL versions being used. See [Using Debugger Extension Commands](using-debugger-extension-commands.md) for a description of the default module search order. See [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) for an explanation of how to load extension modules. + +Each extension command reference page lists the DLLs that expose that command. Use the following rules to determine the proper directory from which to load this extension DLL: + +- If your target computer is running Windows XP or a later version of Windows, use winxp\\Kdexts.dll. + +In addition, kernel-mode extensions that are not specific to any single operating system can be found in winext\\kext.dll. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel-Mode%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-streaming-debugging.md b/windows-driver-docs-pr/debugger/kernel-streaming-debugging.md new file mode 100644 index 0000000000..820e87b231 --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-streaming-debugging.md @@ -0,0 +1,38 @@ +--- +title: Kernel Streaming Debugging +description: Kernel Streaming Debugging +ms.assetid: d7728973-76d3-4d1e-84f9-bef88c4949da +keywords: ["kernel streaming debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel Streaming Debugging + + +This section includes: + +[Overview of Kernel Streaming Debugging](overview-of-kernel-streaming-debugging.md) + +[Analyzing a Video Stream Stall](analyzing-a-video-stream-stall.md) + +[Analyzing a Capture Stall](analyzing-a-capture-stall.md) + +[Live Local Debugging](live-local-debugging.md) + +[Graph Analysis with Unloadable Modules](graph-analysis-with-unloadable-modules.md) + +[Using !ks.graph](using--ks-graph.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel%20Streaming%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kernel-streaming-extensions--ks-dll-.md b/windows-driver-docs-pr/debugger/kernel-streaming-extensions--ks-dll-.md new file mode 100644 index 0000000000..70d558654b --- /dev/null +++ b/windows-driver-docs-pr/debugger/kernel-streaming-extensions--ks-dll-.md @@ -0,0 +1,36 @@ +--- +title: Kernel Streaming Extensions (Ks.dll) +description: Kernel Streaming Extensions (Ks.dll) +ms.assetid: ad25aac3-0052-47b6-a9b6-064f781473e9 +keywords: ["kernel streaming debugging, extensions (ks.dll)", "ks.dll (kernel streaming extensions)", "extensions, kernel streaming"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel Streaming Extensions (Ks.dll) + + +Extension commands that are useful for debugging kernel streaming drivers and AVStream drivers can be found in Ks.dll. + +Most of the sample output in these reference pages was generated by debugging the filter-centric sample Avssamp.sys. This sample is included in the Windows Driver Kit. + +If you wish to use the Ks.dll extensions with Windows 2000, you must copy Ks.dll from the kdexts directory to the w2kfre directory. + +You need special symbols to use this extension. For more information, see the [Debugging Tools for Windows](http://go.microsoft.com/fwlink/p/?linkid=8708) Web site. + +You can get additional information for many of the extension commands in this section simply by entering the command into the debugger with no arguments. + +For more information, see [Kernel Streaming Debugging](kernel-streaming-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel%20Streaming%20Extensions%20%28Ks.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/keyboard-shortcuts.md b/windows-driver-docs-pr/debugger/keyboard-shortcuts.md new file mode 100644 index 0000000000..9bd5cf69eb --- /dev/null +++ b/windows-driver-docs-pr/debugger/keyboard-shortcuts.md @@ -0,0 +1,536 @@ +--- +title: Keyboard Shortcuts +description: Keyboard Shortcuts +ms.assetid: 57c16d54-5b7a-4de8-9798-790aac7ec30d +keywords: ["control keys, WinDbg shortcut keys", "WinDbg, shortcut keys", "shortcut keys"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Keyboard Shortcuts + + +## + + +You can use the following keyboard shortcuts to switch between windows. For more information about how to move between the windows, see [Positioning the Windows](positioning-the-windows.md). + + ++++ + + + + + + + + + + + + + + + + +
KeysEffect

CTRL+TAB

Switches between debugging information windows. By using this key repeatedly, you can scan through all of the windows, regardless of whether they are floating, docked by themselves, or part of a tabbed collection of docked windows.

ALT+TAB

Switches between the windows that are currently on your desktop. You can also use this keyboard shortcut to switch between the WinDbg frame and any additional docks you have created.

+ +  + +You can use the following keyboard shortcuts instead of the mouse to select menu commands. For more information about each command, see the individual command topics. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeysMenu equivalent

F1

[Help | Contents](help---contents.md)

F3

[Edit | Find Next](edit---find-next.md)

SHIFT+F3

Same as [Edit | Find Next](edit---find-next.md), except the search is performed in the reverse direction.

ALT+F4

[File | Exit](file---exit.md)

CTRL+F4

[File | Close Current Window](file---close-current-window.md)

F5

[Debug | Go](debug---go.md)

SHIFT+F5

[Debug | Stop Debugging](debug---stop-debugging.md)

CTRL+SHIFT+F5

[Debug | Restart](debug---restart.md)

F6

[File | Attach to a Process](file---attach-to-a-process.md)

F7

[Debug | Run to Cursor](debug---run-to-cursor.md)

F8

[Debug | Step Into](debug---step-into.md)

F9

If the active window is a Source or Disassembly window: Inserts a breakpoint at the current line. (If there already is a breakpoint set at the current line, this button removes the breakpoint.)

+

Otherwise: Opens the Breakpoints dialog box like [Edit | Breakpoints](edit---breakpoints.md).

ALT+F9

[Edit | Breakpoints](edit---breakpoints.md)

F10

[Debug | Step Over](debug---step-over.md)

CTRL+F10

[Debug | Run to Cursor](debug---run-to-cursor.md)

F11

[Debug | Step Into](debug---step-into.md)

SHIFT+F11

[Debug | Step Out](debug---step-out.md)

ALT+1

Opens the [Debugger Command window](debugger-command-window.md) (same as [View | Command](view---command.md)).

ALT+SHIFT+1

Closes the Command window.

ALT+2

Opens the Watch window (same as [View | Watch](view---watch.md)).

ALT+SHIFT+2

Closes the Watch window

ALT+3

Opens the [Locals window](locals-window.md) (same as [View | Locals](view---locals.md))

ALT+SHIFT+3

Closes the Locals window.

ALT+4

Opens the [Registers window](registers-window.md) (same as [View | Registers](view---registers.md)).

ALT+SHIFT+4

Closes the Registers window.

ALT+5

Opens a new [Memory window](memory-window.md) (same as [View | Memory](view---memory.md)).

ALT+SHIFT+5

Closes the Memory window.

ALT+6

Opens the [Calls window](calls-window.md) (same as [View | Call Stack](view---call-stack.md)).

ALT+SHIFT+6

Closes the Calls window

ALT+7

Opens the [Disassembly window](disassembly-window.md) (same as [View | Disassembly](view---disassembly.md)).

ALT+SHIFT+7

Closes the Disassembly window.

ALT+8

Opens the Scratch Pad (same as [View | Scratch Pad](view---scratch-pad.md)).

ALT+SHIFT+8

Closes the Scratch Pad.

ALT+9

Opens the [Processes and Threads window](processes-and-threads-window.md) (same as [View | Processes and Threads](view---processes-and-threads.md)).

ALT+SHIFT+9

Closes the Processes and Threads window.

CTRL+A

[Edit | Select All](edit---select-all.md)

CTRL+C

[Edit | Copy](edit---copy.md)

CTRL+D

[File | Open Crash Dump](file---open-crash-dump.md)

CTRL+E

[File | Open Executable](file---open-executable.md)

CTRL+F

[Edit | Find](edit---find.md)

CTRL+G

[Edit | Go to Address](edit---go-to-address.md)

CTRL+I

[File | Image File Path](file---image-file-path.md)

CTRL+SHIFT+I

[Edit | Set Current Instruction](edit---set-current-instruction.md)

CTRL+K

[File | Kernel Debug](file---kernel-debug.md)

CTRL+L

[Edit | Go to Line](edit---go-to-line.md)

CTRL+O

[File | Open Source File](file---open-source-file.md)

CTRL+P

[File | Source File Path](file---source-file-path.md)

CTRL+R

[File | Connect to Remote Session](file---connect-to-remote-session.md)

CTRL+S

[File | Symbol File Path](file---symbol-file-path.md)

CTRL+V

[Edit | Paste](edit---paste.md)

CTRL+SHIFT+V

[Edit | Evaluate Selection](edit---evaluate-selection.md)

CTRL+W

[File | Open Workspace](file---open-workspace.md)

CTRL+X

[Edit | Cut](edit---cut.md)

CTRL+SHIFT+Y

[Edit | Display Selected Type](edit---display-selected-type.md)

+ALT+* +(number keypad)

[Edit | Go to Current Instruction](edit---go-to-current-instruction.md)

SHIFT+DELETE

[Edit | Cut](edit---cut.md)

SHIFT+INSERT

[Edit | Paste](edit---paste.md)

CTRL+INSERT

[Edit | Copy](edit---copy.md)

CTRL+BREAK

[Debug | Break](debug---break.md)

ALT+DEL

[Debug | Break](debug---break.md)

+ +  + +The following shortcut keys are equivalent to KD / CDB control keys. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeysMenu equivalentKD / CDB control key

CTRL+ALT+A

[Debug | Kernel Connection | Cycle Baud Rate](debug---kernel-connection---cycle-baud-rate.md)

CTRL+A

CTRL+ALT+D

[CTRL+D (Toggle Debug Info)](ctrl-d--toggle-debug-info-.md)

CTRL+ALT+K

[Debug | Kernel Connection | Cycle Initial Break](debug---kernel-connection---cycle-initial-break.md)

CTRL+K

CTRL+ALT+R

[Debug | Kernel Connection | Resynchronize](debug---kernel-connection---resynchronize.md)

CTRL+R

CTRL+ALT+V

[View | Verbose Output](view---verbose-output.md)

CTRL+V

CTRL+ALT+W

[View | Show Version](view---show-version.md)

CTRL+W

+ +  + +You can use the following keyboard shortcuts to move the caret (^) in most of the debugging information windows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Caret movementKey

One character left

LEFT

One character right

RIGHT

Word left

CTRL+LEFT

Word right

CTRL+RIGHT

Line up

UP

Line down

DOWN

Page up

PAGE UP

Page down

PAGE DOWN

Beginning of the current line

HOME

End of the line

END

Beginning of the file

CTRL+HOME

End of the file

CTRL+END

+ +  + +**Note**   In the [Debugger Command window](debugger-command-window.md), the UP and DOWN keys browse through the command history. You can use the INSERT key to turn insert mode on and off. + +  + +Use the following keyboard shortcuts to select text. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SelectKeys

Character to the left

SHIFT+LEFT

Character to the right

SHIFT+RIGHT

Word to the left

SHIFT+CTRL+LEFT

Word to the right

SHIFT+CTRL+RIGHT

Current line

SHIFT+DOWN if the caret is in column 1

Line above

SHIFT+UP if the caret is in column 1

To the end of the line

SHIFT+END

To the beginning of the line

SHIFT+HOME

Screen up

SHIFT+PAGE UP

Screen down

SHIFT+PAGE DOWN

To beginning of file

SHIFT+CTRL+HOME

To end of file

SHIFT+CTRL+END

+ +  + +Use the following keyboard shortcuts to delete text. + + ++++ + + + + + + + + + + + + + + + + + + + + +
DeleteKey

Character to the right of caret

DELETE

Character to the left of caret

BACKSPACE

Selected text

DELETE

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Keyboard%20Shortcuts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/kill-tool.md b/windows-driver-docs-pr/debugger/kill-tool.md new file mode 100644 index 0000000000..7b4677ba2b --- /dev/null +++ b/windows-driver-docs-pr/debugger/kill-tool.md @@ -0,0 +1,80 @@ +--- +title: Kill Tool +description: The Kill tool, kill.exe, terminates one or more processes and all of their threads. This tool works only on processes running on the local computer. +ms.assetid: e1733a74-2a31-436f-87b8-e704b27b6f04 +keywords: kill Tool, Kill.exe, kill.exe +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kill Tool + + +The Kill tool, kill.exe, terminates one or more processes and all of their threads. This tool works only on processes running on the local computer. + +## Where to get Kill Tool + + +Kill.exe is included in [Debugging Tools for Windows](index.md). + +## Kill Tool command-line options + + +``` +kill [/f] { PID | Pattern* } +``` + +### Parameters + + **/f** +Forces the termination of the process without prompting the user for confirmation. This option is required to terminate a protected process, such as a system service. + + *PID* +Specifies the process identifier (PID) of the task to be terminated. + +To find the PID for a task, use TaskList in Microsoft Windows XP and later or [TList](tlist.md) in Windows 2000. + + *Pattern***\*** +Specifies all or part of the name of a task or window. The Kill tool terminates all processes whose process names or window names match the pattern. The asterisk is required. + +Before using a pattern that might match many process or window names unintentionally, use the **tlist** *pattern* command to test the pattern. See [TList](tlist.md) for details. + +## Examples + + +The following command terminates processes whose names begin with "myapp." + +``` +kill myapp* +``` + +The following command terminates the process whose process ID (PID) is 2520: + +``` +kill 2520 +``` + +The following command terminates processes whose names begin with "my\*." It does not prompt for confirmation. This command succeeds even when this process is a system service: + +``` +kill /f my* +``` + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kill%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/l---l---set-source-options-.md b/windows-driver-docs-pr/debugger/l---l---set-source-options-.md new file mode 100644 index 0000000000..eebfdcece5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/l---l---set-source-options-.md @@ -0,0 +1,102 @@ +--- +title: l+, l- (Set Source Options) +description: The l+and l- commands set the source line options that control source display and program stepping options. +ms.assetid: 7b169af0-e799-47eb-b197-c4408a755702 +keywords: ["l+, l- (Set Source Options) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- l+, l- (Set Source Options) +api_type: +- NA +--- + +# l+, l- (Set Source Options) + + +The **l+**and **l-** commands set the source line options that control source display and program stepping options. + +``` +l+Option +l-Option +l{+|-} +``` + +## Parameters + + + **+** or **-** +Specifies whether a given option is to be turned on (plus sign \[+\])or turned off (minus sign \[-\]). + + *Option* +One of the following options. The options must be in lowercase letters. + +**l** +Displays source line numbers at the command prompt. You can disable source line display through l-ls or .prompt\_allow -src. To make the source line numbers visible, you must enable source line display through both mechanisms. + +**o** +Hides all messages (other than the source line and line number) when you are stepping through code. (The **s** option must also be active for the **o** option to have any effect.) + +**s** +Displays source lines and source line numbers at the command prompt. + +**t** +Starts [source mode](debugging-in-source-mode.md). If this mode is not set, the debugger is in [assembly mode](debugging-in-assembly-mode.md). + +**\*** +Turns on or turns off all options. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about source debugging and related commands, see [Debugging in Source Mode](debugging-in-source-mode.md). For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +If you omit *Option*, the previously set options are displayed. In this case, the **l+** and **l-** commands have identical effects. However, you must include a plus sign (**+**) or minus sign (-) for the **l** command to work. + +You can include only one *Option* every time that you issue this command. If you list more than one option, only the first option is detected. However, by repeatedly issuing this command, you can turn on or off as many options as you want. (In other words, **l+lst** does not work, but **l+l; l+s; l+t** does achieve the effect that you want.) + +When you specify the **s** option, source lines and line numbers are displayed when you step through code, regardless of whether you specified the **l** option. The **o** option has no effect unless you specify the **s** option. + +Source line options do not take effect unless you enable line number loading by using the [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command or the [-lines command-line option](command-line-options.md). By default, if you have not used these commands, WinDbg turns on source line support and CDB turns it off. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20l+,%20l-%20%28Set%20Source%20Options%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/l.md b/windows-driver-docs-pr/debugger/l.md new file mode 100644 index 0000000000..437ae8f522 --- /dev/null +++ b/windows-driver-docs-pr/debugger/l.md @@ -0,0 +1,38 @@ +--- +title: L (Windows Debugger Glossary) +description: Glossary page - L +Robots: noindex, nofollow +ms.assetid: d290c203-4cb3-423c-a41f-baabb3c9a3c1 +--- + +# L + + +**live kernel-mode debugging** +Kernel-mode debugging using live targets. + +See also live user-mode debugging. + +**live target** +A target application or target computer that is currently operational (as opposed to a dump target). + +**live user-mode debugging** +User-mode debugging using live targets. + +See also live user-mode debugging. + +**local context** +See scope. + +**local debugging** +This refers to a debugging session in which the debugger and the application to be debugged reside on the same computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20L%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/language-specification-1.md b/windows-driver-docs-pr/debugger/language-specification-1.md new file mode 100644 index 0000000000..014977f11b --- /dev/null +++ b/windows-driver-docs-pr/debugger/language-specification-1.md @@ -0,0 +1,196 @@ +--- +title: Language Specification 1 +description: Language Specification 1 +ms.assetid: 7c770200-ed2a-47e0-8389-e79a5624a3dd +--- + +# Language Specification 1 + + +The first version of SrcSrv works as follows. (This behavior may change in future versions.) + +First, the client calls **SrcSrvInit** with the target path to be used as a base for all source file extractions. This path is stored in the special variable TARG. + +When DbgHelp loads a module's .pdb file, it extracts the SrcSrv stream from the .pdb file and passes this data block to SrcSrv by calling **SrcSrvLoadModule**. + +Then when DbgHelp needs to obtain a source file, it calls **SrcSrvGetFile** to retrieve a specified source file from version control. + +SrcSrv reviews all the source file entries in the data block for an entry that matches exactly the requested source specification. This match is found in VAR1. + +After SrcSrv finds the entry, it fills in the special variables (VAR1, VAR2, etc.) with the contents of this source file entry. Then the SRCSRVTRG variable is resolved using these special variables. + +The following shows how the SRCSRVTRG variable is resolved using the special variables. We assume that the source path is still: + +``` +c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3 +``` + +Each line shows the resolution of one more special variable. The resolved variables are bold. + +``` +SRCSRVTRG=%sdtrg% +SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) +c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) +c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) +c:\src\WIN_SDKTOOLS\%fnbksl%( sdktools/debuggers/srcsrv/shell.cpp )\%var4%\%fnfile%(%var1%) +c:\src\WIN_SDKTOOLS\ sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%) +c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%) +c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%( c:\db\srcsrv\shell.cpp) +c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp +``` + +Notice how this generated target path is unique and does not allow two versions of the same file to be extracted to the same location. + +SrcSrv now looks to see if the file is already there. If it is, SrcSrv returns the location to the caller. Otherwise, SrcSrv builds the execution command to extract the file by resolving SRCSRVCMD. + +In the following example, each line shows the resolution of one more special variable. The resolved variables are bold. + +``` +DEPOT=//depot +WIN_SDKTOOLS= sserver.microsoft.com:4444 +SRCSRVCMD=%sdcmd% +SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% +sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% +sd.exe -p sserver.microsoft.com:4444 print -o %srcsrvtrg% -q %depot%/%var3%#%var4% +sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q %depot%/%var3%#%var4% +sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/%var3%#%var4% +sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#%var4% +sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#3 +``` + +Now SrcSrv executes this command. If the result of this command is a file in the expected location, this path is returned to the caller. + +Note that if a variable cannot be resolved, an attempt is made to look it up as an OS environment variable. If that fails, the variable name is deleted from the text being processed. + +Two consecutive percent sign characters are interpreted as a single percent sign. + +### Source Server Data Blocks + +SrcSrv relies on two blocks of data within the .pdb file, the source file list and the data block. + +The source file list is created automatically when a module is built. This list contains fully qualified paths to the source files used to build the module. + +The data block is created during source indexing. At this time, an alternative stream named "srcsrv" is added to the .pdb file. The script that inserts this data is dependent on the specific build process and source control system in use. + +The data block is divided into three sections: ini, variables, and source files. The data block has the following syntax. + +``` +SRCSRV: ini ------------------------------------------------ +VERSION=1 +VERCTRL= +DATETIME= +SRCSRV: variables ------------------------------------------ +SRCSRVTRG=%sdtrg% +SRCSRVCMD=%sdcmd% +SRCSRVENV=var1=string1\bvar2=string2 +DEPOT=//depot +SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% +SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) +WIN_SDKTOOLS= sserver.microsoft.com:4444 +SRCSRV: source files --------------------------------------- +*** +*** +*** +*** +SRCSRV: end ------------------------------------------------ +``` + +All text is interpreted literally, except for text enclosed in percent signs (%). Text enclosed in percent signs is treated as a variable name to be resolved recursively, unless it is one of the following functions: + +**%fnvar%()** +The parameter text should be enclosed in percent signs and treated as a variable to be resolved. + +**%fnbksl%()** +All forward slashes (/) in the parameter text should be replaced with backward slashes (\). + +**%fnfile%()** +All path information in the parameter text should be stripped out, leaving only the file name. + +The \[ini\] section of the data block contains variables that describe the requirements. The indexing script can add any number of variables to this section. The following are examples: + +**VERSION** +The language specification version. This variable is required. If you develop a script based on the current language specification, set this value to 1. The SrcSrv client code does not attempt to execute any script that has a value greater than its own. Current versions of SrcSrv use a value of 2. + +**VERCTL** +A string that describes the source version control system. This variable is optional. + +**DATETIME** +A string that indicates the date and time the .pdb file was processed. This variable is optional. + +The \[variables\] section of the data block contains variables that describe how to extract a file from source control. It can also be used to define commonly used text as variables to reduce the size of the data block. + +**SRCSRV** +Describes how to build the target path for the extracted file. This is a required variable. + +**SRCSRVCMD** +Describes how to build the command to extract the file from source control. This includes the name of the executable file and its command-line parameters. This is required if any extraction command must be executed. + +**SRCSRVENV** +Lists environment variables to be created during the file extraction. This is a string. Separate multiple entries with a backspace character (\\b). This is an optional variable. + +**SRCSRVVERCTRL** +Specifies the version control system in use. For Perforce, this is perforce. For Visual SourceSafe, this is vss. For Team Foundation Server, this is tfs. This variable is used to persist server errors. This is an optional variable. + +**SRCSRVVERRDESC** +Specifies the text to display when the version control client is unable to contact the server that contains the source files to extract. SrcSrv uses this value to check for connection problems. This is an optional variable. + +**SRCSRVERRVAR** +Indicates which variable in a file entry corresponds to a version control server. It is used by SrcSrv to identify commands that do not work, based on previous failures. The format of the text is **var***X* where *X* is the number of the variable being indicated. This is an optional variable. + +The \[source files\] section of the data block contains an entry for each source file that has been indexed. The contents of each line are interpreted as variables with the names VAR1, VAR2, VAR3, and so on until VAR10. The variables are separated by asterisks. VAR1 must specify the fully qualified path to the source file as listed elsewhere in the .pdb file. For example: + +``` +c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3 +``` + +is interpreted as follows: + +``` +VAR1=c:\proj\src\file.cpp +VAR2=TOOLS_PRJ +VAR3=tools/mytool/src/file.cpp +VAR4=3 +``` + +In this example, VAR4 is a revision number. However, most source control systems support labeling files in such a way that the source state for a given build can be restored. Therefore, you could instead use the label for the build. The sample data block could be modified to contain a variable such as the following: + +``` +LABEL=BUILD47 +``` + +Then, presuming the source control system uses the at sign (@) to indicate a label, you could modify the SRCSRVCMD variable as follows: + +``` +sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label% +``` + +### Handling Server Errors + +Sometimes a client is unable to extract any files at all from a single version control server. This can be because the server is down and off the network or because the user does not have appropriate privileges to access the source. However, the time consumed attempting to get this source can slow things down significantly. In this situation, it is best to disable any attempt to extract from a source that has been proven to be unavailable. + +Whenever SrcSrv fails to extract a file, it examines the output text produced by the command. If any part of this command contains an exact match for the contents of the SRCSRVERRDESC, all future commands to the same version control server are skipped. Note that you can define multiple error strings by adding numbers or arbitrary text to the end of the SRCSRVERRDESC variable name. Here is an example: + +``` +SRCSRVERRDESC=lime: server not found +SRCSRVERRDESC_2=pineapple: network error +``` + +The identity of the server is acquired from SRCSRVERRVAR. So if SRCSRVERRVAR contains "var2" and the file entry in the .pdb file looks like this: + +``` +c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3 +``` + +all future attempts to obtain source using a file entry that contains "TOOLS\_PRJ" in variable 2 are bypassed. + +You can also add error indicators on the debugger client by editing [Srcsrv.ini](the-srcsrv-ini-file.md). See the included sample version of srcsrv.ini for details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Language%20Specification%201%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/language-specification-2.md b/windows-driver-docs-pr/debugger/language-specification-2.md new file mode 100644 index 0000000000..059c5a6987 --- /dev/null +++ b/windows-driver-docs-pr/debugger/language-specification-2.md @@ -0,0 +1,20 @@ +--- +title: Language Specification 2 +description: Language Specification 2 +ms.assetid: 4555ab3c-5bfa-458e-bb22-3fdaedbf3bca +--- + +# Language Specification 2 + + +This package ships with a srcsrv.dll that can operate without SRCSRVCMD being defined in the srcsrv data stream of a .pdb file. While such capability is of no use for normal file extraction from source control systems, it is useful for direct access of files from a UNC share or HTTP site. See [HTTP Sites and UNC Shares](http-sites-and-unc-shares.md) for more details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Language%20Specification%202%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/launching-a-program-with-flags.md b/windows-driver-docs-pr/debugger/launching-a-program-with-flags.md new file mode 100644 index 0000000000..480761dabe --- /dev/null +++ b/windows-driver-docs-pr/debugger/launching-a-program-with-flags.md @@ -0,0 +1,50 @@ +--- +title: Launching a Program with Flags +description: Launching a Program with Flags +ms.assetid: 81c0ac6a-3114-4b6a-b154-248801a07f8b +keywords: ["GFlags, launching a program with flags"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Launching a Program with Flags + + +## + + +This feature runs a program once with the specified flags. These settings affect only the instance of the program launched. They are not saved in the registry. + +**To launch a program with flags** + +1. Click the **Image File** tab. + +2. In the **Image** box, type the name of an executable file or DLL, including the file name extension, and any commands for the program, and then press the TAB key. + + This activates the **Launch** button and the check boxes on the **Image File** tab. + +3. Set or clear a flag by selecting or clearing the check box associated with the flag. + +4. Click the **Launch** button. + + The following screen shot shows the **Launch** button on the **Image File** tab in Windows Vista. + + ![screen shot of the image file tab in windows vista ](images/gflags-launch.png) + +**Note**   Flags set in the registry do not affect the instance of the program that is launched. +Flags set in the dialog box are used for the launched instance even when they are not image file flags. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Launching%20a%20Program%20with%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ld--load-symbols-.md b/windows-driver-docs-pr/debugger/ld--load-symbols-.md new file mode 100644 index 0000000000..1473883845 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ld--load-symbols-.md @@ -0,0 +1,81 @@ +--- +title: ld (Load Symbols) +description: The ld command loads symbols for the specified module and updates all module information. +ms.assetid: 1dae519f-8dd1-4f30-98f4-fe904454c84c +keywords: ["ld (Load Symbols) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ld (Load Symbols) +api_type: +- NA +--- + +# ld (Load Symbols) + + +The **ld** command loads symbols for the specified module and updates all module information. + +``` +ld ModuleName [/f FileName] +``` + +## Parameters + + + *ModuleName* +Specifies the name of the module whose symbols are to be loaded. *ModuleName* can contain a variety of wildcard characters and specifiers. + + **/f** *FileName* +Changes the name selected for the match. By default the module name is matched, but when **/f** is used the file name is matched instead of the module name. *FileName* can contain a variety of wildcard characters and specifiers. For more information on the syntax of wildcard characters and specifiers, see [String Wildcard Syntax](string-wildcard-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The debugger's default behavior is to use *lazy symbol loading* (also known as [deferred symbol loading](deferred-symbol-loading.md)). This means that symbols are not actually loaded until they are needed. + +The **ld** command, on the other hand, forces all symbols for the specified module to be loaded. + +### Additional Information + +For more information about deferred (lazy) symbol loading, see [Deferred Symbol Loading](deferred-symbol-loading.md). For more information about other symbol options, see [Setting Symbol Options](symbol-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ld%20%28Load%20Symbols%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/list-of-open-windows.md b/windows-driver-docs-pr/debugger/list-of-open-windows.md new file mode 100644 index 0000000000..b79ed3db84 --- /dev/null +++ b/windows-driver-docs-pr/debugger/list-of-open-windows.md @@ -0,0 +1,29 @@ +--- +title: List of Open Windows +description: List of Open Windows +ms.assetid: 1da745b9-803e-45c8-abad-61e0b427b2d7 +keywords: ["debugging information windows, list of open windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# List of Open Windows + + +## + + +At the bottom of the **Window** menu, there is a list of all currently open debugging information windows. Click any window from this list to open the window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20List%20of%20Open%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/live-kernel-mode-targets.md b/windows-driver-docs-pr/debugger/live-kernel-mode-targets.md new file mode 100644 index 0000000000..a96527ba91 --- /dev/null +++ b/windows-driver-docs-pr/debugger/live-kernel-mode-targets.md @@ -0,0 +1,37 @@ +--- +title: Live Kernel-Mode Targets +description: Live Kernel-Mode Targets +ms.assetid: 88820097-4a47-428d-88dd-d0a08e5debdc +keywords: ["targets, live kernel-mode", "kernel-mode targets"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Live Kernel-Mode Targets + + +## + + +To attach the [debugger engine](introduction.md#debugger-engine) to a target computer for kernel-mode debugging, use the method [**AttachKernel**](https://msdn.microsoft.com/library/windows/hardware/ff538145). + +**Note**   The engine doesn't completely attach to the kernel until the [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) method has been called. Only after the kernel has generated an event -- for example, the [initial breakpoint](initial-breakpoint.md) -- does it become available in the debugger session. See [Debugging Session and Execution Model](debugging-session-and-execution-model.md) for more details. + +  + +If the debugger engine is attached to a kernel which is not the local kernel and the connection is not an eXDI connection, the connection options used to find the target computer can be queried using [**GetKernelConnectionOptions**](https://msdn.microsoft.com/library/windows/hardware/ff546970). The connection can also be re-synchronized or the connection speed changed using [**SetKernelConnectionOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556729). + +The debugger can attach to the local kernel, but only in a limited way and only if the computer was booted with the **/debug** boot switch. (In some Windows installations, local kernel debugging is supported when other switches are used, such as **/debugport**, but this is not a guaranteed feature of Windows and should not be relied on.) [**IsKernelDebuggerEnabled**](https://msdn.microsoft.com/library/windows/hardware/ff551088) is used to determine if the local computer is available for debugging. For more information about kernel debugging on a single machine, see [Performing Local Kernel Debugging](performing-local-kernel-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Live%20Kernel-Mode%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/live-local-debugging.md b/windows-driver-docs-pr/debugger/live-local-debugging.md new file mode 100644 index 0000000000..55fe449af6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/live-local-debugging.md @@ -0,0 +1,85 @@ +--- +title: Live Local Debugging +description: Live Local Debugging +ms.assetid: ec76a71e-f173-4b66-beaf-d57a1c991acd +keywords: ["kernel streaming debugging, live local debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Live Local Debugging + + +In Microsoft Windows XP and later operating systems, it is possible to do local kernel debugging by starting the kernel debugger (KD) or WinDbg with the **-kl** command line option: + +``` +kd [-y SymbolPath] -kl +``` + +or + +``` +windbg [-y SymbolPath] -kl +``` + +In Windows Vista and later, local kernel debugging requires the computer to be booted with the **/debug** option. Open a Command Prompt Window as Administrator, and enter **bcdedit /debug on**. Reboot the computer. + +In Windows Vista and later, local kernel debugging requires the debugger to be run as Administrator. + +Live local debugging is extremely useful for debugging issues that are difficult to reproduce when the debugger is attached; however, anything that requires knowledge of time sensitive information, including packet, IRP, and SRB data, is unlikely to work unless the problem is a hang or a stall. + +When performing local debugging, consider the following variables: + +- **Overall states.** For example, is the stream running? Is the stream paused? + +- **Packet counts.** For example, are there IRPs queued to the stream? + +- **Changes in packet counts.** Is the stream moving? + +- **Changes in packet lists.** + +- **Hung kernel threads.** + +Consider the last of these. + +### Examining a Hung Thread in LKD + +First, use the [**!process 0 0**](-process.md) extension to identify the process containing the hung thread. Then, issue **!process** again for more information about that thread: + +``` +lkd> !process 816a550 7 + THREAD 81705da8 Cid 0b5c.0b60 Teb: 7ffde000 Win32Thread: e1b2d890 WAIT: (Suspended) + IRP List: + 816c9ad8: (0006,0190) Flags: 00000030 Mdl: 00000000 + Start Address kernel32!BaseProcessStartThunk (0x77e5c650) + Win32 Start Address 0x0101c9be + Stack Init f50bf000 Current f50bea74 Base f50bf000 Limit f50b9000 Call 0 + Priority 10 BasePriority 8 PriorityDecrement 0 +``` + +The threads are not displayed, but the stack addresses are. Using the [**dds**](dds--dps--dqs--display-words-and-symbols-.md) (or **ddq**) command on the current address on the stack yields a starting point for further investigation, because it specifies which process is calling. + +``` +lkd> dds f50bea74 +f50bea74 f50bebc4 +f50bea78 00000000 +f50bea7c 80805795 nt!KiSwapContext+0x25 +f50beab4 8080ece0 nt!KeWaitForSingleObject +f50beabc f942afda ks!CKsQueue::CancelAllIrps+0x14 +f50bead8 f94406c4 ks!CKsQueue::SetDeviceState+0x170 +f50beb00 f943f6f1 ks!CKsPipeSection::DistributeDeviceStateChange+0x1d +f50beb24 f943fb1e ks!CKsPipeSection::SetDeviceState+0xb2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Live%20Local%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/live-user-mode-targets.md b/windows-driver-docs-pr/debugger/live-user-mode-targets.md new file mode 100644 index 0000000000..47a55fe12e --- /dev/null +++ b/windows-driver-docs-pr/debugger/live-user-mode-targets.md @@ -0,0 +1,53 @@ +--- +title: Live User-Mode Targets +description: Live User-Mode Targets +ms.assetid: 2709dd01-6486-471d-afa1-a8441665da8d +keywords: ["Debugger Engine API, targets, user-mode", "Debugger Engine API, disconnecting from a process", "Debugger Engine API, process options"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Live User-Mode Targets + + +## + + +The methods for creating and attaching to processes that are listed in this topic can be used for the local computer and for a remote computer running a process server. + +A user-mode process can be created using [**Create Process**](https://msdn.microsoft.com/library/windows/hardware/ff539321) or [**CreateProcess2**](https://msdn.microsoft.com/library/windows/hardware/ff539323), which execute a given command to create a process. The method [**AttachProcess**](https://msdn.microsoft.com/library/windows/hardware/ff538150) can be used to attach the [debugger engine](introduction.md#debugger-engine) to an existing user-mode process. [**CreateProcessAndAttach**](https://msdn.microsoft.com/library/windows/hardware/ff540048) and [**CreateProcessAndAttach2**](https://msdn.microsoft.com/library/windows/hardware/ff540055) create a new user-mode process and attach to it or another user-mode process on the same computer. The [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operations [**DEBUG\_REQUEST\_GET\_ADDITIONAL\_CREATE\_OPTIONS**](https://msdn.microsoft.com/library/windows/hardware/ff541553), [**DEBUG\_REQUEST\_SET\_ADDITIONAL\_CREATE\_OPTIONS**](https://msdn.microsoft.com/library/windows/hardware/ff541586), and [**DEBUG\_REQUEST\_SET\_LOCAL\_IMPLICIT\_COMMAND\_LINE**](https://msdn.microsoft.com/library/windows/hardware/ff541592) can be used to set some of the default options for creating processes. + +**Note**   The engine doesn't completely attach to the process until the [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) method has been called. Only after the process has generated an event -- for example, the process creation event -- does it become available in the debugger session. See [Debugging Session and Execution Model](debugging-session-and-execution-model.md) for more details. + +  + +The method [**GetRunningProcessSystemIds**](https://msdn.microsoft.com/library/windows/hardware/ff548265) will return the process IDs of all the running processes on the computer. The process ID of a particular program can be found using [**GetRunningProcessSystemIdByExecutableName**](https://msdn.microsoft.com/library/windows/hardware/ff548254). Given a process ID, a description of the process is returned by [**GetRunningProcessDescription**](https://msdn.microsoft.com/library/windows/hardware/ff548243). + +### Process Options + +The process options determine part of the engine's behavior when attached to a user-mode process, including whether or not the debugger engine will automatically attach to child processes created by the target process and what the engine does with the target processes when it exits. See [**DEBUG\_PROCESS\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541534) for a description of the process options. + +The process options can be queried using [**GetProcessOptions**](https://msdn.microsoft.com/library/windows/hardware/ff548163). They can be changed using [**AddProcessOptions**](https://msdn.microsoft.com/library/windows/hardware/ff537917), [**RemoveProcessOptions**](https://msdn.microsoft.com/library/windows/hardware/ff554505), and [**SetProcessOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556765). + +### Disconnecting from Processes + +There are three different ways for the engine to disconnect from a process. + +1. *Detach*. Resume all the threads in the process so that it will continue running, no longer being debugged. [**DetachCurrentProcess**](https://msdn.microsoft.com/library/windows/hardware/ff541846) will detach the engine from the current process and [**DetachProcesses**](https://msdn.microsoft.com/library/windows/hardware/ff541851) will detach the engine from all processes. Not all targets support detaching. The [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operation [**DEBUG\_REQUEST\_TARGET\_CAN\_DETACH**](https://msdn.microsoft.com/library/windows/hardware/ff541602) can be used to check if the target supports detaching. + +2. *Terminate*. Attempt to kill the process. [**TerminateCurrentProcess**](https://msdn.microsoft.com/library/windows/hardware/ff558866) will terminate the current process and [**TerminateProcesses**](https://msdn.microsoft.com/library/windows/hardware/ff558867) will terminate all processes in the debugger session. + +3. *Abandon*. Remove the process from the list of processes being debugged. The operating system will still consider the process as being debugged and it will remain suspended until another debugger attaches to it or it is killed. [**AbandonCurrentProcess**](https://msdn.microsoft.com/library/windows/hardware/ff537786) will abandon the current process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Live%20User-Mode%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/lm--list-loaded-modules-.md b/windows-driver-docs-pr/debugger/lm--list-loaded-modules-.md new file mode 100644 index 0000000000..7ad8e0af82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/lm--list-loaded-modules-.md @@ -0,0 +1,197 @@ +--- +title: lm (List Loaded Modules) +description: The lm command displays the specified loaded modules. The output includes the status and the path of the module. +ms.assetid: ee2283bd-4d3f-4e30-8b32-e286a415bb3a +keywords: ["lm (List Loaded Modules) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lm (List Loaded Modules) +api_type: +- NA +--- + +# lm (List Loaded Modules) + + +The **lm** command displays the specified loaded modules. The output includes the status and the path of the module. + +``` +lmOptions [a Address] [m Pattern | M Pattern] +``` + +## Parameters + + + *Options* +Any combination of the following options: + +D +Displays output using [Debugger Markup Language](debugger-markup-language-commands.md). + +o +Displays only loaded modules. + +l +Displays only modules whose symbol information has been loaded. + +v +Causes the display to be verbose. The display includes the symbol file name, the image file name, checksum information, version information, date stamps, time stamps, and information about whether the module is managed code (CLR). This information is not displayed if the relevant headers are missing or paged out. + +u +(Kernel mode only) Displays only user-mode symbol information. + +k +(Kernel mode only) Displays only kernel-mode symbol information. + +e +Displays only modules that have a symbol problem. These symbols include modules that have no symbols and modules whose symbol status is C, T, \#, M, or Export. For more information about these notations, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). + +c +Displays checksum data. + +1m +Reduces the output so that nothing is included except the names of the modules. This option is useful if you are using the [**.foreach**](-foreach.md) token to pipe the command output into another command's input. + +sm +Sorts the display by module name instead of by the start address. + +In addition, you can include only one of the following options. If you do not include any of these options, the display includes the symbol file name. + +i +Displays the image file name. + +f +Displays the full image path. (This path always matches the path that is displayed in the initial load notification, unless you issued a [**.reload -s**](-reload--reload-module-.md) command.) When you use f, symbol type information is not displayed. + +n +Displays the image name. When you use n, symbol type information is not displayed. + +p +Displays the mapped image name. When you use p, symbol type information is not displayed. + +t +Displays the file time stamps. When you use t, symbol type information is not displayed. + + a *Address* +Specifies an address that is contained in this module. Only the module that contains this address is displayed. If Address contains an expression, it must be enclosed in parentheses. + + m *Pattern* +Specifies a pattern that the module name must match. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax of this information, see [String Wildcard Syntax](string-wildcard-syntax.md). + +**Note**   In most cases, the module name is the file name without the file name extension. For example, if you want to display information about the Flpydisk.sys driver, use the lm mflpydisk command, not lm mflpydisk.sys. In some cases, the module name differs significantly from the file name. + +  + + M *Pattern* +Specifies a pattern that the image path must match. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax of this information, see [String Wildcard Syntax](string-wildcard-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **lm** command lists all of the modules and the status of symbols for each module. + +Microsoft Windows Server 2003 and later versions of Windows maintain an unloaded module list for user-mode processes. When you are debugging a user-mode process or dump file, the **lm** command also shows these unloaded modules. + +This command shows several columns or fields, each with a different title. Some of these titles have specific meanings: + +- *module name* is typically the file name without the file name extension. In some cases, the module name differs significantly from the file name. + +- The symbol type immediately follows the module name. This column is not labeled. For more information about the various status values, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). If you have loaded symbols, the symbol file name follows this column. + +- The first address in the module is shown as start. The first address after the end of the module is shown as end. For example, if start is "faab4000" and end is "faab8000", the module extends from 0xFAAB4000 to 0xFAAB7FFF, inclusive. + +- **lmv** only: The image path column shows the name of the executable file, including the file name extension. Typically, the full path is included in user mode but not in kernel mode. + +- **lmv** only: The loaded symbol image file value is the same as the image name, unless Microsoft CodeView symbols are present. + +- **lmv** only: The mapped memory image file value is typically not used. If the debugger is mapping an image file (for example, during minidump debugging), this value is the name of the mapped image. + +The following code example shows the **lm** command with a Windows Server 2003 target computer. This example includes the m and s\* options, so only modules that begin with "s" are displayed. + +``` +kd> lm m s* +start end module name +f9f73000 f9f7fd80 sysaudio (deferred) +fa04b000 fa09b400 srv (deferred) +faab7000 faac8500 sr (deferred) +facac000 facbae00 serial (deferred) +fb008000 fb00ba80 serenum e:\mysymbols\SereEnum.pdb\....... +fb24f000 fb250000 swenum (deferred) + +Unloaded modules: +f9f53000 f9f61000 swmidi.sys +fb0ae000 fb0b0000 splitter.sys +fb040000 fb043000 Sfloppy.SYS +``` + +Examples +-------- + +The following two examples show the **lm** command once without any options and once with the sm option. Compare the sort order in the two examples. + +Example 1: + +``` +0:000> lm +start end module name +01000000 0100d000 stst (deferred) +77c10000 77c68000 msvcrt (deferred) +77dd0000 77e6b000 ADVAPI32 (deferred) +77e70000 77f01000 RPCRT4 (deferred) +7c800000 7c8f4000 kernel32 (deferred) +7c900000 7c9b0000 ntdll (private pdb symbols) c:\db20sym\ntdll.pdb +``` + +Example 2: + +``` +0:000> lmsm +start end module name +77dd0000 77e6b000 ADVAPI32 (deferred) +7c800000 7c8f4000 kernel32 (deferred) +77c10000 77c68000 msvcrt (deferred) +7c900000 7c9b0000 ntdll (private pdb symbols) c:\db20sym\ntdll.pdb +77e70000 77f01000 RPCRT4 (deferred) +01000000 0100d000 stst (deferred) +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20lm%20%28List%20Loaded%20Modules%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ln--list-nearest-symbols-.md b/windows-driver-docs-pr/debugger/ln--list-nearest-symbols-.md new file mode 100644 index 0000000000..6350c265a2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ln--list-nearest-symbols-.md @@ -0,0 +1,80 @@ +--- +title: ln (List Nearest Symbols) +description: The ln command displays the symbols at or near the given address. +ms.assetid: ff01ace7-398a-4e32-9d58-00873eca3201 +keywords: ["ln (List Nearest Symbols) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ln (List Nearest Symbols) +api_type: +- NA +--- + +# ln (List Nearest Symbols) + + +The **ln** command displays the symbols at or near the given address. + +``` +ln Address +ln /D Address +``` + +## Parameters + + + *Address* +Specifies the address where the debugger should start to search for symbols. The nearest symbols, either before or after *Address*, are displayed. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +**/D** +Specifies that the output is displayed using [Debugger Markup Language (DML)](debugger-markup-language-commands.md). The DML output includes a link that you can use to explore the module that contains the nearest symbol. It also includes a link that you can use to set a breakpoint. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +You can use the **ln** command to help determine what a pointer is pointing to. This command can also be useful when you are looking at a corrupted stack to determine which procedure made a call. + +If source line information is available, the **ln** display also includes the source file name and line number information. + +If you are using a [source server](using-a-source-server.md), the **ln** command displays information that is related to the source server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ln%20%28List%20Nearest%20Symbols%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/load-image-using-large-pages-if-possible.md b/windows-driver-docs-pr/debugger/load-image-using-large-pages-if-possible.md new file mode 100644 index 0000000000..1593ba02e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/load-image-using-large-pages-if-possible.md @@ -0,0 +1,62 @@ +--- +title: Load image using large pages if possible +description: Load image using large pages if possible +ms.assetid: 7f75b5bd-cc25-4f09-9d60-55b86969d16b +keywords: ["Load image using large pages if possible (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Load image using large pages if possible + + +## + + +The **Load image using large pages if possible** setting directs the system to use large pages (4 MB) rather than the standard small pages (4 KB) when mapping binaries into the process address space. + +This setting is most helpful for large executable files, because it significantly reduces the number of page table entries in physical memory. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

lpg

Hexadecimal value

(none)

Symbolic Name

Destination

Image file registry entry

+ +  + +### Comments + +This setting is not technically a global flag, because its value is stored in a separate registry entry, not as a value of the GlobalFlag registry entry. As a result, you cannot set it by using a hexadecimal value, and when you select this setting for an image file, it appears in the **Other settings** field of the display. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Load%20image%20using%20large%20pages%20if%20possible%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/loading-a-theme.md b/windows-driver-docs-pr/debugger/loading-a-theme.md new file mode 100644 index 0000000000..0cc5ddf366 --- /dev/null +++ b/windows-driver-docs-pr/debugger/loading-a-theme.md @@ -0,0 +1,36 @@ +--- +title: Loading a Theme +description: Loading a Theme +ms.assetid: 375b7365-6526-4282-893e-91b58a14c31f +keywords: ["themes, loading"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Loading a Theme + + +Before loading a theme, we recommend that you clear all of your workspace data. This can be done in three ways: + +By using the WinDbg user-interface. Under the **File** menu, select **Clear Workspace...** Select **Clear All** in the pop-up window and then click **OK**. + +By deleting the registry key under **HKCU\\Software\\Microsoft\\Windbg\\Workspaces**. + +By running the command **reg delete HKCU\\Software\\Microsoft\\Windbg**. + +After all of your workspace data has been cleared, run one of the themes. These are stored as .reg files in the Themes directory of your Debugging Tools for Windows installation. Running a theme imports its settings into the registry, redefining your base workspace. + +After you have loaded a theme, you may alter it to more closely suit your preferences. For more details on some common options, see [Customizing a Theme](customizing-a-theme.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Loading%20a%20Theme%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/loading-debugger-extension-dlls.md b/windows-driver-docs-pr/debugger/loading-debugger-extension-dlls.md new file mode 100644 index 0000000000..bafc739082 --- /dev/null +++ b/windows-driver-docs-pr/debugger/loading-debugger-extension-dlls.md @@ -0,0 +1,59 @@ +--- +title: Loading Debugger Extension DLLs +description: Loading Debugger Extension DLLs +ms.assetid: 6ca70732-cbf6-44fd-a020-c297b40d41f6 +keywords: ["extension commands ( commands), loading", "loading extension commands", "nt4fre directory", "nt4chk directory", "w2kfre directory", "w2kchk directory", "winxp directory", "winext directory"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Loading Debugger Extension DLLs + + +## + + +There are several methods of loading debugger extension DLLs, as well as controlling the default debugger extension DLL and the default debugger extension path: + +- (Before starting the debugger) Use the \_NT\_DEBUGGER\_EXTENSION\_PATH [environment variable](environment-variables.md) to set the default path for extension DLLs. This can be a number of directory paths, separated by semicolons. + +- Use the [**.load (Load Extension DLL)**](-load---loadby--load-extension-dll-.md) command to load a new DLL. + +- Use the [**.unload (Unload Extension DLL)**](-unload--unload-extension-dll-.md) command to unload a DLL. + +- Use the [**.unloadall (Unload All Extension DLLs)**](-unloadall--unload-all-extension-dlls-.md) command to unload all debugger extensions. + +- (Before starting the debugger; CDB only) Use the [tools.ini](configuring-tools-ini.md) file to set the default extension DLL. + +- (Before starting the debugger) Use the **-a** [command-line option](command-line-options.md) to set the default extension DLL. + +- Use the [**.extpath (Set Extension Path)**](-extpath--set-extension-path-.md) command to set the extension DLL search path. + +- Use the [**.setdll (Set Default Extension DLL)**](-setdll--set-default-extension-dll-.md) command to set the default extension DLL. + +- Use the [**.chain (List Debugger Extensions)**](-chain--list-debugger-extensions-.md) command to display all loaded debugger extension modules, in their default search order. + +You can also load an extension DLL simply by using the full **!***module***.***extension* syntax the first time you issue a command from that module. See [Using Debugger Extension Commands](using-debugger-extension-commands.md) for details. + +The extension DLLs that you are using must match the operating system of the target computer. The extension DLLs that ship with the Debugging Tools for Windows package are each placed in a different subdirectory of the installation directory: + +- The winxp directory contains extensions that can be used with Windows XP and later versions of Windows. + +- The winext directory contains extensions that can be used with any version of Windows. The dbghelp.dll module, located in the base directory of Debugging Tools for Windows, also contains extensions of this type. + +If you write your own debugger extensions, you can place them in any directory. However, it is advised that you place them in a new directory and add that directory to the debugger extension path. + +There can be as many as 32 extension DLLs loaded. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Loading%20Debugger%20Extension%20DLLs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/locals-window.md b/windows-driver-docs-pr/debugger/locals-window.md new file mode 100644 index 0000000000..5466d64a4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/locals-window.md @@ -0,0 +1,126 @@ +--- +title: Viewing and Editing Local Variables in WinDbg +description: In WinDbg, you can view local variables by entering commands, by using the Locals window, or by using the Watch window. +ms.assetid: 9d816df7-2b20-4be3-90d7-7a11b0f30238 +keywords: ["debugging information windows, Locals window", "Locals window", "memory, Locals window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Viewing and Editing Local Variables in WinDbg + + +In WinDbg, you can view local variables by entering commands, by using the Locals window, or by using the Watch window. + +## Debugger Command Window + + +You can view local variables and parameters by entering the [**dv**](dv--display-local-variables-.md) command or the [**dt**](dt--display-type-.md) command in the Debugger Command window. + +## Opening the Locals Window + + +The Locals window displays information about all of the local variables in the current scope. + +To open or switch to the Locals window, in the WinDbg window, on the **View** menu, click **Locals**. (You can also press ALT+3 or click the **Locals** button (![screen shot of the locals button](images/tblocal.png)) on the toolbar. ALT+SHIFT+3 closes the Locals window.) + +The following screen shot shows an example of a Locals window. + +![screen shot of the locals window ](images/window-locals.png) + +The Locals window can contain four columns. The **Name** and **Value** columns are always displayed, and the **Type** and **Location** columns are optional. To display the **Type** and **Location** columns, click the **Typecast** and **Locations** buttons, respectively, on the toolbar. + +## Using the Locals Window + + +In the Locals window, you can do the following: + +- The **Name** column displays the name of each local variable. If a variable is a data structure, a check box appears next to its name. To expand or collapse the display of structure members, select or clear the check box. + +- The **Value** column displays the current value of each variable. + + - To enter a new value for the variable, double-click the current value and type the new value, or edit the old value. (The cut, copy, and paste commands are available to use for editing.) You can type any [C++ expression](c---numbers-and-operators.md). + - To save the new value, press ENTER. + - To discard the new value, press ESC. + - If you type an invalid value, the old value will reappear when you press ENTER. + + Integers of type **int** are displayed as decimal values; integers of type **UINT** are displayed in the current radix. To change the current radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command in the Debugger Command window. + +- The **Type** column (if it is displayed in the Locals window) shows the current data type of each variable. Each variable is displayed in the format that is proper for its own data type. Data structures have their type names in the **Type** column. Other variable types display "Enter new type" in this column. + + If you double-click "Enter new type", you can cast the type by entering a new data type. This cast alters the current display of this variable only in the Locals window; it does not change anything in the debugger or on the target computer. Moreover, if you enter a new value in the **Value** column, the text you enter will be parsed based on the actual type of the symbol, rather than any new type you may have entered in the **Type** column. If you close and reopen the Locals window, you will lose the data type changes. + + You can also enter an extension command in the **Type** column. The debugger will pass the address of the symbol to this extension, and will display the resulting output in a series of collapsible rows beneath the current row. For example, if the symbol in this row is a valid address for a thread environment block, you can enter **!teb** in the **Type** column to run the [**!teb**](-teb.md) extension on this symbol's address. + +- The **Location** column (if it is displayed in the Locals window) shows the offset of each member of a data structure. + +- If a local variable is an instance of a class that contains Vtables, the **Name** column displays the Vtables, and you can expand the Vtables to show the function pointers. If a Vtable is contained in a base class that points to a derived implementation, the notation **\_vtcast\_Class** is displayed to indicate the members that are being added because of the derived class. These members expand like the derived class type. + +- The [local context](changing-contexts.md#local-context) determines which set of local variables will be displayed in the Locals window. When the local context changes for any reason, the Locals window is automatically updated. By default, the local context matches the current position of the program counter. For more information about how to change the local context, see Local Context. + +The Locals window has a toolbar that contains two buttons (**Typecast** and **Locations**) and a shortcut menu with additional commands. To access the menu, right-click the title bar of the window or click the icon near the upper-right corner of the window (![the two button icons in this topic are the same, but they seem to serve different functions](images/window-locals-menu-icon.png)). The toolbar and menu contain the following buttons and commands: + +- (Toolbar and menu) **Typecast** turns the display of the **Type** column on and off. + +- (Toolbar and menu) **Locations** turns the display of the **Location** column on and off. + +- (Menu only) **Display 16-bit values as Unicode** displays Unicode strings in this window. This command turns on and off a global setting that affects the Locals window, the Watch window, and debugger command output. This command is equivalent to using the [**.enable\_unicode (Enable Unicode Display)**](-enable-unicode--enable-unicode-display-.md) command. + +- (Menu only) **Always display numbers in default radix** causes integers to be displayed in the default radix instead of displaying them in decimal format. This command turns on and off a global setting that affects the Locals window, the Watch window, and debugger command output. This command is equivalent to using the [**.force\_radix\_output (Use Radix for Integers)**](-force-radix-output--use-radix-for-integers-.md) command. + + **Note**   The **Always display numbers in default radix** command does not affect long integers. Long integers are displayed in decimal format unless the [**.enable\_long\_status (Enable Long Integer Display)**](-enable-long-status--enable-long-integer-display-.md) command is set. The **.enable\_long\_status** command affects the display in the Locals window, the Watch window, and in debugger command output; there is no equivalent for this command in the menu in the Locals window. + +   + +- (Menu only) **Open memory window for selected value** opens a new docked Memory window that displays memory starting at the address of the selected expression. + +- (Menu only) **Invoke dt for selected memory value** runs the [**dt (Display Type)**](dt--display-type-.md) command with the selected symbol as its parameter. The result appears in the Debugger Command window. The **-n** option is automatically used to differentiate the symbol from a hexadecimal address. No other options are used. Note that the content that is produced by using this menu selection is identical to the content produced when running the **dt** command from the command line, but the format is slightly different. + +- (Menu only) **Toolbar** turns the toolbar on and off. + +- (Menu only) **Dock** or **Undock** causes the window to enter or leave the docked state. + +- (Menu only) **Move to new dock** closes the Locals window and opens it in a new dock. + +- (Menu only) **Set as tab-dock target for window type** is unavailable for the Locals window. This option is only available for Source or Memory windows. + +- (Menu only) **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- (Menu only) **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +- (Menu only) **Help** opens this topic in the Debugging Tools for Windows documentation. + +- (Menu only) **Close** closes this window. + +## The Watch Window + + +In WinDbg, you can use the Watch window to display and change local variables. The Watch window can display any list of variables that you want. These variables can include global variables and local variables from any function. At any time, the Watch window displays the values of those variables that match the current function's scope. You can also change the values of these variables through the Watch window. + +Unlike the Locals window, the Watch window is not affected by changes to the local context. Only those variables that are defined in the scope of the current program counter can have their values displayed or modified. + +To open the Watch window, choose **Watch** from the **View** menu. You can also press ALT+2 or click the **Watch** button on the toolbar: ![screen shot of the watch button](images/tbwatch.png). ALT+SHIFT+2 closes the Watch window. + +The following screen shot shows an example of a Watch window. + +![screen shot of the watch window ](images/window-watch.png) + +The Watch window can contain four columns. The **Name** and **Value** columns are always displayed, and the **Type** and **Location** columns are optional. To display the **Type** and **Location** columns, click the **Typecast** and **Locations** buttons, respectively, on the toolbar. + +## Additional Information + + +For more information about controlling local variables, an overview of using variables and changing the scope, and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Local%20Variables%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/logger-and-logviewer.md b/windows-driver-docs-pr/debugger/logger-and-logviewer.md new file mode 100644 index 0000000000..ade70efca4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/logger-and-logviewer.md @@ -0,0 +1,49 @@ +--- +title: Logger and LogViewer +description: Logger and LogViewer +ms.assetid: 10f2d006-6ebc-4098-a401-afc6351ff3dd +keywords: ["Logger", "LogViewer"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Logger and LogViewer + + +## + + +The *Logger* and *LogViewer* tools provide an alternative to standard user-mode debugging. Logger can monitor the actions of a user-mode target application and record all of its API calls. The resulting information can be displayed in the debugger, saved as a text file, or displayed in a powerful interactive format by the LogViewer tool.. + +## Where to get Logger and LogViewer + + +Logger and LogViewer are included in [Debugging Tools for Windows](index.md). + +## In this section + + +[Logger](logger.md) + +[LogViewer](logviewer.md) + +[The Logger Manifest](the-logger-manifest.md) + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Logger%20and%20LogViewer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/logger-extensions--logexts-dll-.md b/windows-driver-docs-pr/debugger/logger-extensions--logexts-dll-.md new file mode 100644 index 0000000000..6e7fa3c676 --- /dev/null +++ b/windows-driver-docs-pr/debugger/logger-extensions--logexts-dll-.md @@ -0,0 +1,31 @@ +--- +title: Logger Extensions (Logexts.dll) +description: Logger Extensions (Logexts.dll) +ms.assetid: f1031b91-6324-41ff-b9b7-86d551ca42bd +keywords: ["logger extensions (logexts.dll)", "logexts.dll (logger extensions)", "extensions, logger"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Logger Extensions (Logexts.dll) + + +## + + +Extension commands related to the Logger and LogViewer tools can be found in Logexts.dll. + +This DLL appears in the winext directory. It can be used with all Windows operating systems. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Logger%20Extensions%20%28Logexts.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/logger-restrictions-and-limitations.md b/windows-driver-docs-pr/debugger/logger-restrictions-and-limitations.md new file mode 100644 index 0000000000..68269f7b37 --- /dev/null +++ b/windows-driver-docs-pr/debugger/logger-restrictions-and-limitations.md @@ -0,0 +1,33 @@ +--- +title: Logger Restrictions and Limitations +description: Logger Restrictions and Limitations +ms.assetid: cb16c193-5420-4900-bf07-44b49859e296 +keywords: ["Logger, restrictions", "Logger, limitations"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Logger Restrictions and Limitations + + +## + + +Logger increases stack consumption for a process because it introduces an additional "wrapping" function before the actual function call. + +This can expose bugs in applications that are usually related to uninitialized variables. Since Logger alters stack usage, a local variable declared in a function call might take a different initial value than it does without the presence of Logger. If the program uses this variable without initializing it, the program might crash or otherwise behave differently than if Logger was not present. + +Unfortunately, there is no easy way around such problems. The only workaround is to try disabling categories of functions in an attempt to isolate the area that is causing the problem. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Logger%20Restrictions%20and%20Limitations%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/logger.md b/windows-driver-docs-pr/debugger/logger.md new file mode 100644 index 0000000000..a5cc6d1852 --- /dev/null +++ b/windows-driver-docs-pr/debugger/logger.md @@ -0,0 +1,39 @@ +--- +title: Logger +description: Logger +ms.assetid: ad9d18b4-cb7f-40e1-98a3-a78f978b8937 +keywords: ["Logger, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Logger + + +## + + +The Logger tool can be activated through two different vehicles. One way is to use the stand-alone Logger.exe program. The other is to start CDB or WinDbg, and use the Logexts.dll debugger extensions. Both of these methods will produce the same type of log output. However, the best vehicle to use on any NT-based operating system is CDB or WinDbg with the Logexts.dll extension commands. + +The Logger vehicle works as well, but using the debugger gives you the full power of the debugger along with the power of Logger. + +This section includes: + +[Using the Debugger and Logexts.dll](using-the-debugger-and-logexts-dll.md) + +[Using Logger.exe](using-logger-exe.md) + +[Logger Restrictions and Limitations](logger-restrictions-and-limitations.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Logger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/logviewer.md b/windows-driver-docs-pr/debugger/logviewer.md new file mode 100644 index 0000000000..087a592daf --- /dev/null +++ b/windows-driver-docs-pr/debugger/logviewer.md @@ -0,0 +1,39 @@ +--- +title: LogViewer +description: LogViewer +ms.assetid: 0aeda310-4b4c-4156-ac8d-76a0cf14f402 +keywords: ["LogViewer, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# LogViewer + + +## + + +The LogViewer utility can manipulate an .lgv file, which is a compressed log file produced by the Logger tool. To load a file, simply launch Logviewer.exe through Windows Explorer or from a Command Prompt window. It will take a moment to parse the manifest files. Once this is complete, you can invoke **File | Open** and select the desired .lgv file. + +Once LogViewer has opened an .lgv file, it will display a list of all functions in the order they were logged. LogViewer supports powerful commands to filter out functions that you are not interested in. It can also save a filtered version of the log file as a text file. + +This section includes: + +[Reading the LogViewer Display](reading-the-logviewer-display.md) + +[Filtering the LogViewer Function List](filtering-the-logviewer-function-list.md) + +[Exporting LogViewer Files to Text](exporting-logviewer-files-to-text.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20LogViewer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ls--lsa--list-source-lines-.md b/windows-driver-docs-pr/debugger/ls--lsa--list-source-lines-.md new file mode 100644 index 0000000000..315016707f --- /dev/null +++ b/windows-driver-docs-pr/debugger/ls--lsa--list-source-lines-.md @@ -0,0 +1,92 @@ +--- +title: ls, lsa (List Source Lines) +description: The ls and lsa commands display a series of lines from the current source file and advance the current source line number. +ms.assetid: ca5cd2f7-4920-4d36-b338-c934451bc511 +keywords: ["ls, lsa (List Source Lines) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ls, lsa (List Source Lines) +api_type: +- NA +--- + +# ls, lsa (List Source Lines) + + +The **ls** and **lsa** commands display a series of lines from the current source file and advance the current source line number. + +``` +ls [.] [first] [, count] +lsa [.] address [, first [, count]] +``` + +## Parameters + + + **.** +Causes the command to look for the source file that the debugger engine or the [**.srcpath (Set Source Path)**](-srcpath---lsrcpath--set-source-path-.md) command are using. If the period (**.**) is not included, **ls** uses the file that was most recently loaded with the [**lsf (Load Source File)**](lsf--lsf---load-or-unload-source-file-.md) command. + + *address* +Specifies the address where the source display is to begin. + +For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *first* +Specifies the first line to display. The default value is the current line. + + *count* +Specifies the quantity of lines to display. The default value is 20 (0x14), unless you have changed the default value by using the [**lsp -a**](lsp--set-number-of-source-lines-.md) command. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +After you run the **ls** or **lsa** command, the current line is redefined as the final line that is displayed plus one. The current line is used in future **ls**, **lsa**, and [**lsc**](lsc--list-current-source-.md) commands. + +## See also + + +[**lsc (List Current Source)**](lsc--list-current-source-.md) + +[**lsf, lsf- (Load or Unload Source File)**](lsf--lsf---load-or-unload-source-file-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ls,%20lsa%20%28List%20Source%20Lines%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/lsc--list-current-source-.md b/windows-driver-docs-pr/debugger/lsc--list-current-source-.md new file mode 100644 index 0000000000..8c83041bb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/lsc--list-current-source-.md @@ -0,0 +1,72 @@ +--- +title: lsc (List Current Source) +description: The lsc command displays the current source file name and line number. +ms.assetid: 5c500974-c405-4335-94bd-a36e7389667b +keywords: ["lsc (List Current Source) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lsc (List Current Source) +api_type: +- NA +--- + +# lsc (List Current Source) + + +The **lsc** command displays the current source file name and line number. + +``` +lsc +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +## See also + + +[**ls, lsa (List Source Lines)**](ls--lsa--list-source-lines-.md) + +[**lsf, lsf- (Load or Unload Source File)**](lsf--lsf---load-or-unload-source-file-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20lsc%20%28List%20Current%20Source%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/lse--launch-source-editor-.md b/windows-driver-docs-pr/debugger/lse--launch-source-editor-.md new file mode 100644 index 0000000000..70738f44e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/lse--launch-source-editor-.md @@ -0,0 +1,76 @@ +--- +title: lse (Launch Source Editor) +description: The lse command opens an editor for the current source file. +ms.assetid: 2f66b5c3-1cd6-4641-8dea-5e3a11c87db0 +keywords: ["lse (Launch Source Editor) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lse (Launch Source Editor) +api_type: +- NA +--- + +# lse (Launch Source Editor) + + +The **lse** command opens an editor for the current source file. + +``` +lse +``` + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User-mode, kernel-mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **lse** command opens an editor for the current source file. This command is equivalent to clicking **Edit this file** in the shortcut menu of the [Source window](source-window.md) in WinDbg. + +The editor is opened on the computer that the target is running on, so you cannot use the **lse** command from a remote client. + +The WinDiff editor registry information or the value of the WINDBG\_INVOKE\_EDITOR environment variable determine which editor is opened. For example, consider the following value of WINDBG\_INVOKE\_EDITOR. + +``` +c:\my\path\myeditor.exe -file %f -line %l +``` + +This value indicates that Myeditor.exe opens to the one-based line number of the current source file. The **%l** option indicates that line numbers should be read as one-based, and **%f** indicates that the current source file should be used. You could also include **%L** to indicate that line numbers are zero-based or **%p** to indicate that the current source file should be used. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20lse%20%28Launch%20Source%20Editor%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/lsf--lsf---load-or-unload-source-file-.md b/windows-driver-docs-pr/debugger/lsf--lsf---load-or-unload-source-file-.md new file mode 100644 index 0000000000..a96f9c7f8b --- /dev/null +++ b/windows-driver-docs-pr/debugger/lsf--lsf---load-or-unload-source-file-.md @@ -0,0 +1,87 @@ +--- +title: lsf, lsf- (Load or Unload Source File) +description: The lsf and lsf- commands load or unload a source file. +ms.assetid: e788a778-e331-4b7b-8aad-072b3d08442b +keywords: ["lsf, lsf- (Load or Unload Source File) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lsf, lsf- (Load or Unload Source File) +api_type: +- NA +--- + +# lsf, lsf- (Load or Unload Source File) + + +The **lsf** and **lsf-** commands load or unload a source file. + +``` +lsf Filename +lsf- Filename +``` + +## Parameters + + + *Filename* +Specifies the file to load or unload. If this file is not located in the directory where the debugger was opened from, you must include an absolute or relative path. The file name must follow Microsoft Windows file name conventions. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **lsf** command loads a source file. + +The **lsf-** command unloads a source file. You can use this command to unload files that you previously loaded with **lsf** or automatically loaded source files. You cannot use **lsf-** to unload files that were loaded through WinDbg's [File | Open Source File](file---open-source-file.md) command or files that a WinDbg workspace loaded. + +In CDB or KD, you can view source files in the [Debugger Command window](debugger-command-window.md). In WinDbg, source files are loaded as new [Source windows](source-window.md). + +For more information about source files, source paths, and other ways to load source files, see [Source Path](source-path.md). + +## See also + + +[**ls, lsa (List Source Lines)**](ls--lsa--list-source-lines-.md) + +[**lsc (List Current Source)**](lsc--list-current-source-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20lsf,%20lsf-%20%28Load%20or%20Unload%20Source%20File%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/lsp--set-number-of-source-lines-.md b/windows-driver-docs-pr/debugger/lsp--set-number-of-source-lines-.md new file mode 100644 index 0000000000..e4cb3d601b --- /dev/null +++ b/windows-driver-docs-pr/debugger/lsp--set-number-of-source-lines-.md @@ -0,0 +1,89 @@ +--- +title: lsp (Set Number of Source Lines) +description: The lsp command controls how many source lines are displayed while you step through or execute code or use the ls and lsa commands. +ms.assetid: 350933f1-5459-4ba2-9ca7-a42341cf95de +keywords: ["lsp (Set Number of Source Lines) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- lsp (Set Number of Source Lines) +api_type: +- NA +--- + +# lsp (Set Number of Source Lines) + + +The **lsp** command controls how many source lines are displayed while you step through or execute code or use the [**ls and lsa commands**](ls--lsa--list-source-lines-.md). + +``` +lsp [-a] LeadingLines TrailingLines +lsp [-a] TotalLines +lsp [-a] +``` + +## Parameters + + + **-a** +Sets or displays the number of lines that **ls** and **lsa** show. If you omit **-a**, **lsp** sets or displays the number of lines that are shown while you step through and execute code. + + *LeadingLines* +Specifies the number of lines to show before the current line. + + *TrailingLines* +Specifies the number of lines to show after the current line. + + *TotalLines* +Specifies the total number of lines to show. This number is divided evenly between leading and trailing lines. (If this number is odd, more trailing lines are displayed.) + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +When you use the **lsp** command together with no parameters, **lsp** displays the current leading line and trailing line values that you used while stepping. When you use this command together with only the **-a** parameter, **lsp** displays the values that you used while stepping and for the [**ls and lsa commands**](ls--lsa--list-source-lines-.md). + +When you step through a program or break in after program execution, the previous **lsp** command determines the number of leading and trailing lines that are displayed. When you use **lsa**, the previous **lsp -a** command determines the number of leading and trailing lines that are displayed. When you use **ls**, all lines appear as a single block, so the previous **lsp -a** command determines the total number of lines that are displayed. + +### Additional Information + +For more information about source debugging and related commands, see [Debugging in Source Mode](debugging-in-source-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20lsp%20%28Set%20Number%20of%20Source%20Lines%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/m--move-memory-.md b/windows-driver-docs-pr/debugger/m--move-memory-.md new file mode 100644 index 0000000000..9e798b1921 --- /dev/null +++ b/windows-driver-docs-pr/debugger/m--move-memory-.md @@ -0,0 +1,81 @@ +--- +title: m (Move Memory) +description: The m command copies the contents of memory from one location to another. Do not confuse this command with the ~m (Resume Thread) command. +ms.assetid: afcac933-6bba-4566-ae07-bb9110f851d2 +keywords: ["m (Move Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- m (Move Memory) +api_type: +- NA +--- + +# m (Move Memory) + + +The **m** command copies the contents of memory from one location to another. + +Do not confuse this command with the [**~m (Resume Thread)**](-m--resume-thread-.md) command. + +``` +m Range Address +``` + +## Parameters + + + *Range* +Specifies the memory area to copy. For more information about the syntax of this parameter, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Address* +Specifies the starting address of the destination memory area. For more information about the syntax of this parameter, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +The memory area that *Address* specifies can be part of the memory area that *Range* specifies. Overlapping moves are handled correctly. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20m%20%28Move%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/m.md b/windows-driver-docs-pr/debugger/m.md new file mode 100644 index 0000000000..0c192f25c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/m.md @@ -0,0 +1,22 @@ +--- +title: M (Windows Debugger Glossary) +description: Glossary page - M +Robots: noindex, nofollow +ms.assetid: 41d36320-1a5b-4919-bad8-e6d6e62ec355 +--- + +# M + + +**module** +An image in a target process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20M%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/maintain-a-list-of-objects-for-each-type.md b/windows-driver-docs-pr/debugger/maintain-a-list-of-objects-for-each-type.md new file mode 100644 index 0000000000..db5b03b336 --- /dev/null +++ b/windows-driver-docs-pr/debugger/maintain-a-list-of-objects-for-each-type.md @@ -0,0 +1,64 @@ +--- +title: Maintain a list of objects for each type +description: Maintain a list of objects for each type +ms.assetid: 845ba6cb-60b3-4053-9d54-f43ed344f82d +keywords: ["Maintain a list of objects for each type (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Maintain a list of objects for each type + + +## + + +The **Maintain a list of objects for each type** flag collects and maintains a list of active objects by object type, for example, event, mutex, and semaphore. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

otl

Hexadecimal value

0x4000

Symbolic Name

FLG_MAINTAIN_OBJECT_TYPELIST

Destination

System-wide registry entry

+ +  + +### Comments + +To display the object list, use Open Handles (oh.exe), a tool included in the Windows 2000 Resource Kit, and now available for download from the [Microsoft Windows 2000 Resource Kit](http://go.microsoft.com/fwlink/p/?linkid=11233) Web site. Because Open Handles automatically sets the OTL flag, but does not clear it, use **GFlags -otl** to clear the flag. + +**Note**   The linked lists created when you set this flag use eight bytes of overhead for each object. Remember to clear this flag when your analysis is complete. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Maintain%20a%20list%20of%20objects%20for%20each%20type%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/manifest-file-format.md b/windows-driver-docs-pr/debugger/manifest-file-format.md new file mode 100644 index 0000000000..6bcc027f9c --- /dev/null +++ b/windows-driver-docs-pr/debugger/manifest-file-format.md @@ -0,0 +1,304 @@ +--- +title: Manifest File Format +description: Manifest File Format +ms.assetid: 1b0dc305-878c-4eb2-9e92-f7f7017ae4eb +keywords: ["LogViewer, manifest, file format"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Manifest File Format + + +## + + +The file format for the manifest files borrows as much from C++ and IDL as possible. As a result, it is fairly easy to take a normal C++ SDK header file and modify it to be a manifest file. The parser fully supports C and C++ style comments to help you organize and document the file. + +If you are attempting to add a manifest file or make alterations to an existing file, the best way to do it is to just experiment. When you issue a **!logexts.logi** or **!logexts.loge** command in the debugger, Logger will attempt to parse the manifest files. If it encounters a problem, it will produce an error message which might indicate the mistake. + +A manifest file is made up of the following basic elements: module labels, category labels, function declarations, COM interface definitions, and type definitions. Other types of elements exist as well, but these are the most important. + +### Module Labels + +A module label simply declares what DLL exports the functions that are declared thereafter. For example, if your manifest file is for logging a group of functions from Comctl32.dll, you would include the following module label before declaring any function prototypes: + +``` +module COMCTL32.DLL: +``` + +A module label must appear before any function declarations in a manifest file. A manifest file can contain any number of module labels. + +### Category Labels + +Similar to a module label, a category label identifies which "category" all subsequent functions and/or COM interfaces belong to. For example, if you are creating a Comctl32.dll manifest file, you can use the following as your category label: + +``` +category CommonControls: +``` + +A manifest file can contain any number of category labels. + +### Function Declarations + +A function declaration is what actually prompts Logger to log something. It is nearly identical to a function prototype found in a C/C++ header file. There are a few notable additions to the format, which can be best illustrated by the following example: + +``` +HANDLE [gle] FindFirstFileA( + LPCSTR lpFileName, + [out] LPWIN32_FIND_DATAA lpFindFileData); +``` + +The function **FindFirstFileA** takes two parameters. The first is *lpFileName*, which is a full path (usually with wildcards) defining where to search for a file or files. The second is a pointer to a WIN32\_FIND\_DATAA structure that will be used to contain the search results. The returned HANDLE is used for future calls to **FindNextFileA**. If **FindFirstFileA** returns INVALID\_HANDLE\_VALUE, then the function call failed and an error code can be procured by calling the **GetLastError** function. + +The HANDLE type is declared as follows: + +``` +value DWORD HANDLE +{ +#define NULL 0 [fail] +#define INVALID_HANDLE_VALUE -1 [fail] +}; +``` + +If the value returned by this function is 0 or -1 (0xFFFFFFFF), Logger will assume that the function failed, because such values have a \[fail\] modifier in the value declaration. (See the Value Types section later in this section.) Since there is a \[gle\] modifier right before the function name, Logger recognizes that this function uses **GetLastError** to return error codes, so it captures the error code and logs it to the log file. + +The \[out\] modifier on the *lpFindFileData* parameter informs Logger that the data structure is filled in by the function and should be logged when the function returns. + +### COM Interface Definitions + +A COM interface is basically a vector of functions that can be called by a COM object's client. The manifest format borrows heavily from the Interface Definition Language (IDL) used in COM to define interfaces. + +Consider the following example: + +``` +interface IDispatch : IUnknown +{ + HRESULT GetTypeInfoCount( UINT pctinfo ); + + HRESULT GetTypeInfo( + UINT iTInfo, + LCID lcid, + LPVOID ppTInfo ); + + HRESULT GetIDsOfNames( + REFIID riid, + LPOLECHAR* rgszNames, + UINT cNames, + LCID lcid, + [out] DISPID* rgDispId ); + + HRESULT Invoke( + DISPID dispIdMember, + REFIID riid, + LCID lcid, + WORD wFlags, + DISPPARAMS* pDispParams, + VARIANT* pVarResult, + EXCEPINFO* pExcepInfo, + UINT* puArgErr ); +}; +``` + +This declares an interface called **IDispatch** that is derived from **IUnknown**. It contains four member functions, which are declared in specific order within the interface's braces. Logger will intercept and log these member functions by replacing the function pointers in the interface's vtable (the actual binary vector of function pointers used at run time) with its own. See the COM\_INTERFACE\_PTR Types section later in this section for more details on how Logger captures interfaces as they are handed out. + +### Type Definitions + +Defining data types is the most important (and most tedious) part of manifest file development. The manifest language allows you to define human-readable labels for numeric values that are passed in or returned from a function. + +For example, Winerror.h defines a type called "WinError" that is a list of error values returned by most Microsoft Win32 functions and their corresponding human-readable labels. This allows Logger and LogViewer to replace uninformative error codes with meaningful text. + +You can also label individual bits within a bit mask to allow Logger and LogViewer to break a DWORD bit mask into its components. + +There are 13 basic types supported by the manifest. They are listed in the following table. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeLengthDisplay Example

Pointer

4 bytes

0x001AF320

VOID

0 bytes

BYTE

1 byte

0x32

WORD

2 bytes

0x0A23

DWORD

4 bytes

-234323

BOOL

1 byte

TRUE

LPSTR

Length byte plus any number of characters

"Quick brown fox"

LPWSTR

Length byte plus any number of Unicode characters

"Jumped over the lazy dog"

GUID

16 bytes

{0CF774D0-F077-11D1-B1BC-00C04F86C324}

COM_INTERFACE_PTR

4 bytes

0x0203404A

value

Dependent on base type

ERROR_TOO_MANY_OPEN_FILES

mask

Dependent on base type

WS_MAXIMIZED | WS_ALWAYSONTOP

struct

Dependent on size of encapsulated types

++ lpRect +nLeft 34 +nRight 54 +nTop 100 +nBottom 300
+ +  + +Type definitions in manifest files work like C/C++ typedefs. For example, the following statement defines PLONG as a pointer to a LONG: + +``` +typedef LONG *PLONG; +``` + +Most basic typedefs have already been declared in Main.h. You should only have to add typedefs that are specific to your component. Structure definitions have the same format as C/C++ struct types. + +There are four special types: value, mask, GUID, and COM\_INTERFACE\_PTR. + +Value Types +A value is a basic type that is broken out into human-readable labels. Most function documentation only refers to the **\#define** value of a particular constant used in a function. For example, most programmers are unaware of what the actual value is for all the codes returned by **GetLastError**, making it unhelpful to see a cryptic numerical value in LogViewer. The manifest value overcomes this by allowing value declarations like as in the following example: + +``` +value LONG ChangeNotifyFlags +{ +#define SHCNF_IDLIST 0x0000 // LPITEMIDLIST +#define SHCNF_PATHA 0x0001 // path name +#define SHCNF_PRINTERA 0x0002 // printer friendly name +#define SHCNF_DWORD 0x0003 // DWORD +#define SHCNF_PATHW 0x0005 // path name +#define SHCNF_PRINTERW 0x0006 // printer friendly name +}; +``` + +This declares a new type called "ChangeNotifyFlags" derived from LONG. If this is used as a function parameter, the human-readable aliases will be displayed instead of the raw numbers. + +Mask Types +Similar to value types, a mask type is a basic type (usually a DWORD) that is broken out into human-readable labels for each of the bits that have meaning. Take the following example: + +``` +mask DWORD DirectDrawOptSurfaceDescCapsFlags +{ +#define DDOSDCAPS_OPTCOMPRESSED 0x00000001 +#define DDOSDCAPS_OPTREORDERED 0x00000002 +#define DDOSDCAPS_MONOLITHICMIPMAP 0x00000004 +}; +``` + +This declares a new type derived from DWORD that, if used as a function parameter, will have the individual values broken out for the user in LogViewer. So, if the value is 0x00000005, LogViewer will display: + +``` +DDOSDCAPS_OPTCOMPRESSED | DDOSDCAPS_MONOLITHICMIPMAP +``` + +GUID Types +GUIDs are 16-byte globally-unique identifiers that are used extensively in COM. They are declared in two ways: + +``` +struct __declspec(uuid("00020400-0000-0000-C000-000000000046")) IDispatch; +``` + +or + +``` +class __declspec(uuid("11219420-1768-11D1-95BE-00609797EA4F")) ShellLinkObject; +``` + +The first method is used to declare an interface identifier (IID). When displayed by LogViewer, "IID\_" is appended to the beginning of the display name. The second method is used to declare a class identifier (CLSID). LogViewer appends "CLSID\_" to the beginning of the display name. + +If a GUID type is a parameter to a function, LogViewer will compare the value against all declared IIDs and CLSIDs. If a match is found, it will display the IID friendly name. If not, it will display the 32-hexadecimal-character value in standard GUID notation. + +COM\_INTERFACE\_PTR Types +The COM\_INTERFACE\_PTR type is the base type of a COM interface pointer. When you declare a COM interface, you are actually defining a new type that is derived from COM\_INTERFACE\_PTR. As such, a pointer to such a type can be a parameter to a function. If a COM\_INTERFACE\_PTR basic type is declared as an OUT parameter to a function and there is a separate parameter that has an \[iid\] label, Logger will compare the passed in IID against all declared GUIDs. If there is a match and a COM interface was declared that has the same name as the IID, Logger will hook all the functions in that interface and log them. + +Here is an example: + +``` +STDAPI CoCreateInstance( + REFCLSID rclsid, //Class identifier (CLSID) of the object + LPUNKNOWN pUnkOuter, //Pointer to controlling IUnknown + CLSCTX dwClsContext, //Context for running executable code + [iid] REFIID riid, //Reference to the identifier of the interface + [out] COM_INTERFACE_PTR * ppv + //Address of output variable that receives + //the interface pointer requested in riid +); +``` + +In this example, *riid* has an \[iid\] modifier. This indicates to Logger that the pointer returned in *ppv* is a COM interface pointer for the interface identified by *riid*. + +It is also possible to declare a function as follows: + +``` +DDRESULT DirectDrawCreateClipper( DWORD dwFlags, [out] LPDIRECTDRAWCLIPPER *lplpDDClipper, IUnknown *pUnkOuter ); +``` + +In this example, LPDIRECTDRAWCLIPPER is defined as a pointer to the **IDirectDrawClipper** interface. Since Logger can identify which interface type is being returned in the *lplpDDClipper* parameter, there is no need for an \[iid\] modifier on any of the other parameters. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Manifest%20File%20Format%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/manifest-file-placement.md b/windows-driver-docs-pr/debugger/manifest-file-placement.md new file mode 100644 index 0000000000..7f32c8bc30 --- /dev/null +++ b/windows-driver-docs-pr/debugger/manifest-file-placement.md @@ -0,0 +1,43 @@ +--- +title: Manifest File Placement +description: Manifest File Placement +ms.assetid: ebf10463-3aa1-403a-8508-1462259a5f8a +keywords: ["LogViewer, manifest, file placement"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Manifest File Placement + + +## + + +The primary manifest file must be named Main.h. + +When Logger is running, Main.h must be located in the Manifest subdirectory of the directory containing Logexts.dll. + +LogViewer is more flexible than Logger. It will search for Main.h in the following directories in this order: + +1. The Manifest directory subordinate to the directory containing Logviewer.exe + +2. The WinExt\\Manifest directory subordinate to the directory containing logviewer.exe + +3. The %WinDir%\\System32\\Manifest directory + +4. The %WinDir%\\System\\Manifest directory + +All additional manifest files must reside in the same directory as Main.h. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Manifest%20File%20Placement%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/manually-walking-a-stack.md b/windows-driver-docs-pr/debugger/manually-walking-a-stack.md new file mode 100644 index 0000000000..11cf845549 --- /dev/null +++ b/windows-driver-docs-pr/debugger/manually-walking-a-stack.md @@ -0,0 +1,233 @@ +--- +title: Manually Walking a Stack +description: Manually Walking a Stack +ms.assetid: 9235fe4d-3e94-4143-867f-18b696e489d0 +keywords: ["stack trace, walking the stack manually", "walking the stack"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Manually Walking a Stack + + +## + + +In some cases, the stack trace function will fail in the debugger. This can be caused by a call to an invalid address that caused the debugger to lose the location of the return address; or you may have come across a stack pointer for which you cannot directly get a stack trace; or there could be some other debugger problem. In any case, being able to manually walk a stack is often valuable. + +The basic concept is fairly simple: dump out the stack pointer, find out where the modules are loaded, find possible function addresses, and verify by checking to see if each possible stack entry makes a call to the next. + +Before going through an example, it is important to note that the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command has an additional feature on Intel systems. By doing a kb=\[ebp\] \[eip\] \[esp\], the debugger will display the stack trace for the frame with the given values for base pointer, instruction pointer, and stack pointer, respectively. + +For the example, a failure that actually gives a stack trace is used so the results can be checked at the end. + +The first step is to find out what modules are loaded where. This is accomplished with the [**x (Examine Symbols)**](x--examine-symbols-.md) command (some symbols are edited out for reasons of length): + +``` +kd> x *! +start end module name +77f70000 77fb8000 ntdll (C:\debug\ntdll.dll, \\ntstress\symbols\dll\ntdll.DBG) +80010000 80012320 Aha154x (load from Aha154x.sys deferred) +80013000 8001aa60 SCSIPORT (load from SCSIPORT.SYS deferred) +8001b000 8001fba0 Scsidisk (load from Scsidisk.sys deferred) + +80100000 801b7b40 NT (ntoskrnl.exe, \\ntstress\symbols\exe\ntoskrnl.DBG) +802f0000 8033c000 Ntfs (load from Ntfs.sys deferred) +80400000 8040c000 hal (load from hal.dll deferred) +fe4c0000 fe4c38c0 vga (load from vga.sys deferred) +fe4d0000 fe4d3e60 VIDEOPRT (load from VIDEOPRT.SYS deferred) +fe4e0000 fe4f0e40 ati (load from ati.SYS deferred) +fe500000 fe5057a0 Msfs (load from Msfs.SYS deferred) +fe510000 fe519560 Npfs (load from Npfs.SYS deferred) + +fe520000 fe521f60 ndistapi (load from ndistapi.sys deferred) +fe530000 fe54ed20 Fastfat (load from Fastfat.SYS deferred) +fe5603e0 fe575360 NDIS (NDIS.SYS, \\ntstress\symbols\SYS\NDIS.DBG) +fe580000 fe585920 elnkii (elnkii.sys, \\ntstress\symbols\sys\elnkii.DBG) +fe590000 fe59b8a0 ndiswan (load from ndiswan.sys deferred) +fe5a0000 fe5b7c40 nbf (load from nbf.sys deferred) +fe5c0000 fe5c1b40 TDI (load from TDI.SYS deferred) +fe5d0000 fe5dd580 nwlnkipx (load from nwlnkipx.sys deferred) + +fe5e0000 fe5ee220 nwlnknb (load from nwlnknb.sys deferred) +fe5f0000 fe5fb320 afd (load from afd.sys deferred) +fe610000 fe62bf00 tcpip (load from tcpip.sys deferred) +fe630000 fe648600 netbt (load from netbt.sys deferred) +fe650000 fe6572a0 netbios (load from netbios.sys deferred) +fe660000 fe660000 Parport (load from Parport.SYS deferred) +fe670000 fe670000 Parallel (load from Parallel.SYS deferred) +fe680000 fe6bcf20 rdr (rdr.sys, \\ntstress\symbols\sys\rdr.DBG) + +fe6c0000 fe6f0920 srv (load from srv.sys deferred) +``` + +The second step is dumping out the stack pointer to look for addresses in the modules given by the **x \*!** command: + +``` +kd> dd esp +fe4cc97c 80136039 00000270 00000000 00000000 +fe4cc98c fe682ae4 801036fe 00000000 fe68f57a +fe4cc99c fe682a78 ffb5b030 00000000 00000000 +fe4cc9ac ff680e08 801036fe 00000000 00000000 +fe4cc9bc fe6a1198 00000001 fe4cca78 ffae9d98 + +fe4cc9cc 02000901 fe4cca68 ffb50030 ff680e08 +fe4cc9dc ffa449a8 8011c901 fe4cca78 00000000 +fe4cc9ec 80127797 80110008 00000246 fe6a1430 + +kd> dd +fe4cc9fc 00000270 fe6a10ae 00000270 ffa44abc +fe4cca0c ffa449a8 ff680e08 fe6b2c04 ff680e08 +fe4cca1c ffa449a8 e12820c8 e1235308 ffa449a8 +fe4cca2c fe685968 ff680e08 e1235308 ffa449a8 +fe4cca3c ffb0ad48 ffb0ad38 00100000 ffb0ad38 +fe4cca4c 00000000 ffa44a84 e1235308 0000000a +fe4cca5c c00000d6 00000000 004ccb28 fe4ccbc4 + +fe4cca6c fe680ba4 fe682050 00000000 fe4ccbd4 +``` + +To determine which values are likely function addresses and which are parameters or saved registers, the first thing to consider is what the different types of information look like on the stack. Most integers are going to be smaller value, which means they will be mostly zeros when displayed as DWORDs (like 0x00000270). Most pointers to local addresses will be near the stack pointer (like fe4cca78). Status codes usually begin with a c (c00000d6). Unicode and ASCII strings can be identified by the fact that each character will be in the range of 20-7f. (In KD, the [**dc (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command will show the characters on the right.) Most importantly, the function addresses will be in the range listed by **x \*!**. + +Notice that all modules listed are in the ranges of 77f70000 to 8040c000 and fe4c0000 to fe6f0920. Based on these ranges, the possible function addresses in the preceding list are: 80136039, 801036fe (listed twice, so more likely a parameter), fe682ae4, fe68f57a, fe682a78, fe6a1198, 8011c901, 80127797, 80110008, fe6a1430, fe6a10ae, fe6b2c04, fe685968, fe680ba4, and fe682050. Investigate these locations by using an [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) command for each address: + +``` +kd> ln 80136039 +(80136039) NT!_KiServiceExit+0x1e | (80136039) NT!_KiServiceExit2-0x177 +kd> ln fe682ae4 +(fe682ae4) rdr!_RdrSectionInfo+0x2c | (fe682ae4) rdr!_RdrFcbReferenceLock-0xb4 +kd> ln 801036fe +(801036fe) NT!_KeWaitForSingleObject | (801036fe) NT!_MmProbeAndLockPages-0x2f8 +kd> ln fe68f57a +(fe68f57a) rdr!_RdrDereferenceDiscardableCode+0xb4 + (fe68f57a) rdr!_RdrUninitializeDiscardableCode-0xa +kd> ln fe682a78 +(fe682a78) rdr!_RdrDiscardableCodeLock | (fe682a78) rdr!_RdrDiscardableCodeTimeout-0x38 + +kd> ln fe6a1198 +(fe6a1198) rdr!_SubmitTdiRequest+0xae | (fe6a1198) rdr!_RdrTdiAssociateAddress-0xc +kd> ln 8011c901 +(8011c901) NT!_KeSuspendThread+0x13 | (8011c901) NT!_FsRtlCheckLockForReadAccess-0x55 +kd> ln 80127797 +(80127797) NT!_ZwCloseObjectAuditAlarm+0x7 | (80127797) NT!_ZwCompleteConnectPort-0x9 +kd> ln 80110008 +(80110008) NT!_KeWaitForMultipleObjects+0x27c | (80110008) NT!_FsRtlLookupMcbEntry-0x164 +kd> ln fe6a1430 +(fe6a1430) rdr!_RdrTdiCloseConnection+0xa | (fe6a1430) rdr!_RdrDoTdiConnect-0x4 + +kd> ln fe6a10ae +(fe6a10ae) rdr!_RdrTdiDisconnect+0x56 | (fe6a10ae) rdr!_SubmitTdiRequest-0x3c +kd> ln fe6b2c04 +(fe6b2c04) rdr!_CleanupTransportConnection+0x64 | (fe6b2c04)rdr!_RdrReferenceServer-0x20 +kd> ln fe685968 +(fe685968) rdr!_RdrReconnectConnection+0x1b6 + (fe685968) rdr!_RdrInvalidateServerConnections-0x32 +kd> ln fe682050 +(fe682050) rdr!__strnicmp+0xaa | (fe682050) rdr!_BackPackSpinLock-0xa10 +``` + +As noted before, 801036fe is not likely to be part of the stack trace as it is listed twice. If the return addresses have an offset of zero, they can be ignored (you cannot return to the beginning of a function). Based on this information, the stack trace is revealed to be: + +``` +NT!_KiServiceExit+0x1e +rdr!_RdrSectionInfo+0x2c +rdr!_RdrDereferenceDiscardableCode+0xb4 +rdr!_SubmitTdiRequest+0xae +NT!_KeSuspendThread+0x13 +NT!_ZwCloseObjectAuditAlarm+0x7 +NT!_KeWaitForMultipleObjects+0x27c +rdr!_RdrTdiCloseConnection+0xa +rdr!_RdrTdiDisconnect+0x56 +rdr!_CleanupTransportConnection+0x64 +rdr!_RdrReconnectConnection+0x1b6 +rdr!__strnicmp+0xaa +``` + +To verify each symbol, unassemble immediately before the return address specified to see if it does a call to the function above it. To reduce length, the following is edited (the offsets used were found by trial and error): + +``` +kd> u 80136039-2 l1 // looks ok, its a call +NT!_KiServiceExit+0x1c: +80136037 ffd3 call ebx +kd> u fe682ae4-2 l1 // paged out (all zeroes) unknown +rdr!_RdrSectionInfo+0x2a: +fe682ae2 0000 add [eax],al +kd> u fe68f57a-6 l1 // looks ok, its a call, but not anything above +rdr!_RdrDereferenceDiscardableCode+0xae: +fe68f574 ff15203568fe call dword ptr [rdr!__imp__ExReleaseResourceForThreadLite] +kd> u fe682a78-6 l1 // paged out (all zeroes) unknown + +rdr!_DiscCodeInitialized+0x2: +fe682a72 0000 add [eax],al +kd> u fe6a1198-5 l1 // looks good, call to something above +rdr!_SubmitTdiRequest+0xa9: +fe6a1193 e82ee3feff call rdr!_RdrDereferenceDiscardableCode (fe68f4c6) +kd> u 8011c901-2 l1 // not good, its a jump in the function +NT!_KeSuspendThread+0x11: +8011c8ff 7424 jz NT!_KeSuspendThread+0x37 (8011c925) +kd> u 80127797-2 l1 // looks good, an int 2e -> KiServiceExit + +NT!_ZwCloseObjectAuditAlarm+0x5: +80127795 cd2e int 2e +kd> u 80110008-2 l1 // not good, its a test instruction not a call +NT!_KeWaitForMultipleObjects+0x27a: +80110006 85c9 test ecx,ecx +kd> u 80110008-5 l1 // paged out (all zeroes) unknown +NT!_KeWaitForMultipleObjects+0x277: +80110003 0000 add [eax],al +kd> u fe6a1430-6 l1 // looks good its a call to ZwClose... +rdr!_RdrTdiCloseConnection+0x4: +fe6a142a ff15f83468fe call dword ptr [rdr!__imp__ZwClose (fe6834f8)] + +kd> u fe6a10ae-2 l1 // paged out (all zeroes) unknown +rdr!_RdrTdiDisconnect+0x54: +fe6a10ac 0000 add [eax],al +kd> u fe6b2c04-5 l1 // looks good, call to something above +rdr!_CleanupTransportConnection+0x5f: +fe6b2bff e854e4feff call rdr!_RdrTdiDisconnect (fe6a1058) +kd> u fe685968-5 l1 // looks good, call to immediately above +rdr!_RdrReconnectConnection+0x1b1: +fe685963 e838d20200 call rdr!_CleanupTransportConnection (fe6b2ba0) + +kd> u fe682050-2 l1 // paged out (all zeroes) unknown +rdr!__strnicmp+0xa8: +fe68204e 0000 add [eax],al +``` + +Based on this, it appears that **RdrReconnectConnection** called **RdrCleanupTransportConnection**, to **RdrTdiDisconnect**, to **ZwCloseObjectAuditAlarm**, to **KiSystemServiceExit**. The other functions on the stack are probably leftover portions of previously active stacks. + +In this case, the stack trace worked properly. Following is the actual stack trace to check the answer: + +``` +kd> k +ChildEBP RetAddr +fe4cc978 80136039 NT!_NtClose+0xd +fe4cc978 80127797 NT!_KiServiceExit+0x1e + +fe4cc9f4 fe6a1430 NT!_ZwCloseObjectAuditAlarm+0x7 +fe4cca10 fe6b2c04 rdr!_RdrTdiCloseConnection+0xa +fe4cca28 fe685968 rdr!_CleanupTransportConnection+0x64 +fe4cca78 fe688157 rdr!_RdrReconnectConnection+0x1b6 +fe4ccbd4 80106b1e rdr!_RdrFsdCreate+0x45b +fe4ccbe8 8014b289 NT!IofCallDriver+0x38 +fe4ccc98 8014decd NT!_IopParseDevice+0x693 +fe4ccd08 8014d6d2 NT!_ObpLookupObjectName+0x487 +fe4ccde4 8014d3ad NT!_ObOpenObjectByName+0xa2 +fe4cce90 8016660d NT!_IoCreateFile+0x433 +fe4cced0 80136039 NT!_NtCreateFile+0x2d +``` + +The first entry was the current location based on the stack trace, but otherwise, the stack was correct up to the point where **RdrReconnectConnection** was called. The same process could have been used to trace the entire stack. For a more exact method of manual stack walking, you would need to unassemble each potential function and follow each **push** and **pop** to identify each DWORD on the stack. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Manually%20Walking%20a%20Stack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/mapping-driver-files.md b/windows-driver-docs-pr/debugger/mapping-driver-files.md new file mode 100644 index 0000000000..26943827d8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/mapping-driver-files.md @@ -0,0 +1,153 @@ +--- +title: Mapping Driver Files +description: Mapping Driver Files +ms.assetid: 9a13a6a9-b585-4be1-b7c8-da65fa3ba6c6 +keywords: ["mapping driver files", "driver replacement map", "driver replacement map, overview", "driver replacement map, file format", "driver replacement map, replacing boot drivers", "boot driver replacement"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Mapping Driver Files + + +## + + +Replacing driver files can be difficult. Frequently, you have to boot to the Microsoft Windows *safe build*, replace the driver binary, and then boot again. + +However, Windows XP and later versions of Windows support a simpler method of replacing driver files. You can use this method to replace any kernel-mode driver (including display drivers), any Windows subsystem driver, or any other kernel-mode module. For simplicity, these files are called *drivers* in this topic, even though you can use this method for any kernel-mode module. + +You can use this method whenever WinDbg or KD is attached as a kernel debugger. You can also use this method on a boot driver, but it is more difficult. For more information about how to use this method with boot drivers, see Replacing Boot Drivers. + +To use a driver replacement map to replace driver files, do the following: + +1. Create a *driver replacement map file*. This file is a text file that lists the drivers on the target computer and their replacement drivers on the host computer. You can replace any number of drivers. For example, you might create a file that is named Mymap.ini in the d:\\Map\_Files directory of your host computer that contains the following information. + + ``` + map + \Systemroot\system32\drivers\videoprt.sys + \\myserver\myshare\new_drivers\videoprt.sys + ``` + + For more information about the syntax of this file, see Driver Replacement Map File Format. + +2. Set up a kernel debugging connection to the target computer, and start the kernel debugger (KD or WinDbg) on your host computer. (You do not have to actually break in to the target computer.) + +3. Load the driver replacement map file by doing one of the following: + - Set the \_NT\_KD\_FILES [environment variable](environment-variables.md) before you start the kernel debugger. + + ``` + D:\Debugging Tools for Windows> set _NT_KD_FILES=d:\Map_Files\mymap.ini + D:\Debugging Tools for Windows> kd + ``` + + - Use the [**.kdfiles (Set Driver Replacement Map)**](-kdfiles--set-driver-replacement-map-.md) command after you start the kernel debugger. + + ``` + D:\Debugging Tools for Windows> kd + kd> .kdfiles d:\Map_Files\mymap.ini + KD file associations loaded from 'd:\Map_Files\mymap.ini' + ``` + + You can also use the **.kdfiles** command to display the current driver replacement map file or to delete the driver replacement map. If you do not use this command, the map persists until you exit the debugger. + +After you complete this procedure, the driver replacement map takes effect. + +Whenever the target computer is about to load a driver, it queries the kernel debugger to determine whether this driver has been mapped. If the driver has been mapped, the replacement file is sent over the kernel connection and copied over the old driver file. The new driver is then loaded. + +### Driver Replacement Map File Format + +Each driver file replacement is indicated by three lines in the driver replacement map file. + +- The first line consists of the word "map". + +- The second line specifies the path and file name of the old driver on the target computer. + +- The third line specifies the full path of the new driver. This driver can be located on the host computer or on some other server. + +You can repeat this pattern of information any number of times. + +Paths and file names are case insensitive, and the actual driver file names can be different. The file that you specify on the third line is copied over the file that you specify on the second line when the target computer is about to load that driver. + +Kdfiles will attempt to match the file name that is stored in the Service Control Manager (SCM) database. The name in the SCM database is identical to the name that was passed to MmLoadSystemImage. + +In Windows 10 and later versions of the debugging tools, driver mapping works to match the driver name dynamically and determine the proper path. The full path does not need to be specified and the file extension is optional. You can use any of these entries to match the NT file system driver. + +- ntfs +- NTFS +- ntfs.sys +- windows\\system32\\drivers\\ntfs.sys + +You can use any of these entries to match the NT kernel driver. + +- ntoskrnl +- NTOSKRNL +- ntoskrnl.sys +- windows\\system32\\drivers\\ntoskrnl.sys + +The map file can include blank lines and can include comment lines that begin with a number sign (**\#**). However, after "map" appears in the file, the next two lines must be the old driver and the new driver. The blank lines and comment lines cannot break up the three-line map blocks. + +The following example shows a driver replacement map file. + +``` +map +\Systemroot\system32\drivers\videoprt.sys +e:\MyNewDriver\binaries\videoprt.sys +map +\Systemroot\system32\mydriver.sys +\\myserver\myshare\new_drivers\mydriver0031.sys + +# Here is a comment +map +\??\c:\windows\system32\beep.sys +\\myserver\myshare\new_drivers\new_beep.sys +``` + +The driver replacement map file must be a text file, but you can use any file name and file name extension (.ini, .txt, .map, and so on). + +### Additional Notes + +When driver substitution occurs, a message appears in the kernel debugger. + +If you use [**CTRL+D**](ctrl-d--toggle-debug-info-.md) (in KD) or CTRL+ALT+D (in WinDbg), you see verbose information about the replacement request. This information can be useful if you are not sure whether the name that you have listed matches the one in the SCM database. + +You can enable the bcdedit bootdebug option to view early boot information that is useful for replacing the kernel, the hal, or boot drivers. + +``` +bcdedit -bootdebug on +``` + +For more information, see [BCDEdit Options Reference](https://msdn.microsoft.com/library/windows/hardware/ff542205). + +If the kernel debugger exits, no more driver replacement occurs. However, any drivers that have already been replaced do not revert to their old binaries, because the driver files are actually overwritten. + +This driver replacement feature automatically bypasses Windows File Protection (WFP). + +You do not have to restart the target computer. Driver replacement occurs any time that the target computer loads a driver, regardless of whether it has been restarted. Of course, most drivers are loaded during the boot process, so in practice you should restart the target computer after the map file has been loaded. + +If the \_NT\_KD\_FILES variable is defined, the specified driver replacement map file is read when the kernel debugger is started. If you issue the **.kdfiles** command, the specified file is read immediately. At this point, the debugger verifies that the file has the basic map/line/line format. But the actual paths and file names are not verified until substitution occurs. + +After the map file has been read, the debugger stores its contents. If you change this file after this point, the changes have no effect (unless you reissue the **.kdfiles** command). + +### Replacing Boot Drivers + +If you want to replace a boot driver file by using this driver replacement method, you must connect the kernel debugger to the Windows boot loader (Ntldr), not to the Windows kernel. Before you can make this connection, you must install a special debugger-enabled version of Ntldr. You can find this version of Ntldr in the Windows Driver Kit (WDK), in the %DDKROOT%\\debug directory. + +Because the target computer bypasses its Boot.ini file, you cannot set the kernel connection protocol in the typical manner. You must make the connection through the COM1 port on the target computer. The baud rate is 115200. Therefore, the kernel debugger on the host computer should be configured to use a COM connection at the 115200 speed. + +This special method applies only to boot drivers (that is, Acpi.sys, Classpnp.sys, Disk.sys, and anything else that [**lm t n**](lm--list-loaded-modules-.md) displays at the initial Windows breakpoint). If you have to replace a standard driver that **MmLoadSystemImage** loads after the boot has been completed, you should use the standard method described earlier. + +You cannot replace boot drivers on a computer that uses EFI firmware instead of the Boot.ini file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Mapping%20Driver%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/mapping-symbols-when-the-peb-is-paged-out.md b/windows-driver-docs-pr/debugger/mapping-symbols-when-the-peb-is-paged-out.md new file mode 100644 index 0000000000..18649158c9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/mapping-symbols-when-the-peb-is-paged-out.md @@ -0,0 +1,112 @@ +--- +title: Mapping Symbols When the PEB is Paged Out +description: Mapping Symbols When the PEB is Paged Out +ms.assetid: dba9e686-81fc-4efa-a5c7-293b9e47e0b1 +--- + +# Mapping Symbols When the PEB is Paged Out + + +## + + +To load symbols, the debugger looks at the list of modules loaded by the operating system. The pointer to the user-mode module list is one of the items stored in the process environment block (PEB). + +To reclaim memory, the Memory Manager may page out user-mode data to make space for other process or kernel mode components. The user-mode data that is paged out may include the PEB data structure. Without this data structure, the debugger cannot determine for which images to load symbols. + +**Note**   This affects symbol files only for the user-mode modules. Kernel-mode modules and symbols are not affected, as they are tracked in a different list. + +  + +Suppose a user-mode module is mapped into the current process and you want to fix the symbols for it. Find any address in the range of virtual addresses of the module. For example, suppose a module is mapped into a virtual address range that contains the address 7f78e9e000F. Enter the following command. + +``` +3: kd> !vad 7f78e9e000F 1 +``` + +The command output displays information about the virtual address descriptor (VAD) for the module. The command output also includes a Reload command string that you can use to load the symbols for the module. The Reload command string includes the starting address (000007f7\`8e9e0000) and size (32000) of the notepad module. + +``` +VAD @ fffffa80056fb960 +... +Reload command: .reload notepad.exe=000007f7`8e9e0000,32000 +``` + +To load the symbols, enter the command that was given in the Reload command string. + +``` +.reload notepad.exe=000007f7`8e9e0000,32000 +``` + +Here is another example that uses a slightly different technique. The example demonstrates how to use the [**!vad**](-vad.md) extension to map symbols when the PEB is paged out. The basic idea is to find the starting address and size of the relevant DLL so that you can then use the [**.reload**](-reload--reload-module-.md) command to load the necessary symbols. Suppose that the address of the current process is 0xE0000126\`01BA0AF0 and you want to fix the symbols for it. First, use the [**!process**](-process.md) command to obtain the virtual address descriptor (VAD) root address: + +``` +kd> !process e000012601ba0af0 1 +PROCESS e000012601ba0af0 + SessionId: 2 Cid: 0b50 Peb: 6fbfffde000 ParentCid: 0efc + DirBase: 079e8461 ObjectTable: e000000600fbceb0 HandleCount: 360. + Image: explorer.exe + VadRoot e000012601a35e70 Vads 201 Clone 0 Private 917. Modified 2198. Locked 0. +... +``` + +Then use the [**!vad**](-vad.md) extension to list the VAD tree associated with the process. Those VADs labeled "EXECUTE\_WRITECOPY" belong to code modules. + +``` +kd> !vad e000012601a35e70 +VAD level start end commit +... +e0000126019f9790 ( 6) 3fff0 3fff7 -1 Private READONLY +e000012601be1080 ( 7) 37d9bd30 37d9bd3e 2 Mapped Exe EXECUTE_WRITECOPY <-- these are DLLs +e000012600acd970 ( 5) 37d9bec0 37d9bece 2 Mapped Exe EXECUTE_WRITECOPY +e000012601a5cba0 ( 7) 37d9c910 37d9c924 2 Mapped Exe EXECUTE_WRITECOPY +... +``` + +Then use the [**!vad**](-vad.md) extension again to find the starting address and size of the paged out memory which holds the DLL of interest. This confirms that you have found the correct DLL: + +``` +kd> !vad e000012601be1080 1 + +VAD @ e000012601be1080 + Start VPN: 37d9bd30 End VPN: 37d9bd3e Control Area: e00001260197b8d0 + First ProtoPte: e0000006013e00a0 Last PTE fffffffffffffffc Commit Charge 2 (2.) + Secured.Flink 0 Blink 0 Banked/Extend: 0 + File Offset 0 + ImageMap ViewShare EXECUTE_WRITECOPY + +... + File: \Windows\System32\ExplorerFrame.dll +``` + +The "Start VPN" field - in this case, 0x37D9BD30 - indicates the starting virtual page number. This must be converted to an actual address, by multiplying it by the page size. You can use the [**? (Evaluate Expression)**](---evaluate-expression-.md) command to multiply this value by 0x2000, which is the page size for the Itanium-based machine the example comes from. + +``` +kd> ? 37d9bd3e*2000 +Evaluate expression: 7676040298496 = 000006fb`37a7c000 +``` + +Then the size of the range can be converted to bytes: + +``` +kd> ? 37d9bd3e-37d9bd30+1 <-- computes the number of pages +Evaluate expression: 15 = 00000000`0000000f +kd> ? f*2000 +Evaluate expression: 122880 = 00000000`0001e000 +``` + +So ExplorerFrame.dll starts at address 0x000006Fb\`37A7C000 and is 0x1E000 bytes large. You can load its symbols with: + +``` +kd> .reload /f ExplorerFrame.dll=6fb`37a7c000,1e000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Mapping%20Symbols%20When%20the%20PEB%20is%20Paged%20Out%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/masm-expressions-vs--c---expressions.md b/windows-driver-docs-pr/debugger/masm-expressions-vs--c---expressions.md new file mode 100644 index 0000000000..9b2f35469c --- /dev/null +++ b/windows-driver-docs-pr/debugger/masm-expressions-vs--c---expressions.md @@ -0,0 +1,43 @@ +--- +title: MASM Expressions vs. C++ Expressions +description: MASM Expressions vs. +ms.assetid: 3ec06b61-9f17-49b1-b7c5-66a349b5d275 +keywords: ["expressions, MASM and C++", "MASM expressions, MASM vs. C++", "C++ expressions, C++ vs. MASM"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# MASM Expressions vs. C++ Expressions + + +## + + +The most significant differences between MASM expression evaluation and C++ expression evaluation are as follows: + +- In an MASM expression, the numeric value of any symbol is its memory address. In a C++ expression, the numeric value of a variable is its actual value, not its address. Data structures do not have numeric values. Instead, they are treated as actual structures and you must use them accordingly. The value of a function name or any other entry point is the memory address and is treated as a function pointer. If you use a symbol that does not correspond to a C++ data type (such as an unmodified module name), a syntax error occurs. + +- The MASM expression evaluator treats all numbers as ULONG64 values. The C++ expression evaluator casts numbers to ULONG64 and preserves type information of all data types. + +- The MASM expression evaluator lets you to use any operator together with any number. The C++ expression evaluator generates an error if you use an operator together with an incorrect data type. + +- In the MASM expression evaluator, all arithmetic is performed literally. In the C++ expression evaluator, pointer arithmetic is scaled properly and is not permitted when inappropriate. + +- An MASM expression can use two underscores ( **\_\_** ) or two colons ( **::** ) to indicate members of a class. The C++ expression evaluator uses only the two-colon syntax. Debugger *output* always uses two colons. + +- In an MASM expression, you should add an at sign (**@**) before all except the most common registers. If you omit this at sign, the register name might be interpreted as a hexadecimal number or as a symbol. In a C++ expression, this prefix is required for all registers. + +- MASM expressions might contain references to source lines. These references are indicated by grave accents ( **\`** ). You cannot reference source line numbers in a C++ expression. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20MASM%20Expressions%20vs.%20C++%20Expressions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/masm-numbers-and-operators.md b/windows-driver-docs-pr/debugger/masm-numbers-and-operators.md new file mode 100644 index 0000000000..19dd19859d --- /dev/null +++ b/windows-driver-docs-pr/debugger/masm-numbers-and-operators.md @@ -0,0 +1,272 @@ +--- +title: MASM Numbers and Operators +description: MASM Numbers and Operators +ms.assetid: 9aeb3ef2-d83a-4f99-9a55-4bbd8a7e11b5 +keywords: ["expressions, MASM expression syntax", "numerical expressions (MASM)", "MASM expressions, numbers", "MASM expressions, operators", "operators (MASM)", "(MASM prefix)", "binary operators", "shift operators", "unary operators"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# MASM Numbers and Operators + + +## + + +Before version 4.0 of the Debugging Tools for Windows package, NTSD, CDB, KD, and WinDbg used only Microsoft Macro Assembler (MASM) expression syntax. + +### Numbers in MASM Expressions + +You can put numbers in MASM expressions in base 16, 10, 8, or 2. + +Use the [**n (Set Number Base)**](n--set-number-base-.md) command to set the default radix to 16, 10, or 8. All unprefixed numbers are then interpreted in this base. You can override the default radix by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + +You can also specify hexadecimal numbers by adding an **h** after the number. You can use uppercase or lowercase letters within numbers. For example, "0x4AB3", "0X4aB3", "4AB3h", "4ab3h", and "4aB3H" have the same meaning. + +If you do not add a number after the prefix in an expression, the number is read as 0. Therefore, you can write 0 as 0, the prefix followed by 0, and only the prefix. For example, in hexadecimal, "0", "0x0", and "0x" have the same meaning. + +You can enter hexadecimal 64-bit values in the **xxxxxxxx\`xxxxxxxx** format. You can also omit the grave accent (\`). If you include the grave accent, [automatic sign extension](sign-extension.md) is disabled. + +### Symbols in MASM Expressions + +In MASM expressions, the numeric value of any symbol is its memory address. Depending on what the symbol refers to, this address is the address of a global variable, local variable, function, segment, module, or any other recognized label. + +To specify which module the address is associated with, include the module name and an exclamation point (!) before the name of the symbol. If the symbol could be interpreted as a hexadecimal number, include the module name and an exclamation point, or just an exclamation point, before the symbol name. For more information about symbol recognition, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +Use two colons (::) or two underscores (\_\_) to indicate the members of a class. + +Use a grave accent (\`) or an apostrophe (') in a symbol name only if you add a module name and exclamation point before the symbol. + +### Numeric Operators in MASM Expressions + +You can modify any component of an expression by using a unary operator. You can combine any two components by using a binary operator. Unary operators take precedence over binary operators. When you use multiple binary operators, the operators follow the fixed precedence rules that are described in the following tables. + +You can always use parentheses to override precedence rules. + +If part of an MASM expression is enclosed in parentheses and two at signs (@@) appear before the expression, the expression is interpreted according to [C++ expression rules](c---numbers-and-operators.md). You cannot add a space between the two at signs and the opening parenthesis. You can also specify the [expression evaluator](evaluating-expressions.md) by using **@@c++( ... )** or **@@masm( ... )**. + +When you perform arithmetic computations, the MASM expression evaluator treats all numbers and symbols as ULONG64 types. + +Unary address operators assume DS as the default segment for addresses. Expressions are evaluated in order of operator precedence. If adjacent operators have equal precedence, the expression is evaluated from left to right. + +You can use the following unary operators. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning

+

Unary plus

-

Unary minus

not

Returns 1 if the argument is zero. Returns zero for any nonzero argument.

hi

High 16 bits

low

Low 16 bits

by

Low-order byte from the specified address.

$pby

Same as by except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.

wo

Low-order word from the specified address.

$pwo

Same as wo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.

dwo

Double-word from the specified address.

$pdwo

Same as dwo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.

qwo

Quad-word from the specified address.

$pqwo

Same as qwo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.

poi

Pointer-sized data from the specified address. The pointer size is 32 bits or 64 bits. In kernel debugging, this size is based on the processor of the target computer. In user-mode debugging on an Itanium-based computer, this size is 32 bits or 64 bits, depending on the target application. Therefore, poi is the best operator to use if you want pointer-sized data.

$ppoi

Same as poi except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.

+ +  + +You can use the following binary operators. The operators in each cell take precedence over those in lower cells. Operators in the same cell are of the same precedence and are parsed from left to right. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning

*

+

/

+

mod (or %)

Multiplication

+

Integer division

+

Modulus (remainder)

+

+

-

Addition

+

Subtraction

<<

+

>>

+

>>>

Left shift

+

Logical right shift

+

Arithmetic right shift

= (or ==)

+

<

+

>

+

<=

+

>=

+

!=

Equal to

+

Less than

+

Greater than

+

Less than or equal to

+

Greater than or equal to

+

Not equal to

and (or &)

Bitwise AND

xor (or ^)

Bitwise XOR (exclusive OR)

or (or |)

Bitwise OR

+ +  + +The <, >, =, ==, and != comparison operators evaluate to 1 if the expression is true or zero if the expression is false. A single equal sign (=) is the same as a double equal sign (==). You cannot use side effects or assignments within a MASM expression. + +An invalid operation (such as division by zero) results in an "Operand error" is returned to the [Debugger Command window](debugger-command-window.md). + +### Non-Numeric Operators in MASM Expressions + +You can also use the following additional operators in MASM expressions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning

$fnsucc(FnAddress, RetVal, Flag)

Interprets the RetVal value as a return value for the function that is located at the FnAddress address. If this return value qualifies as a success code, $fnsucc returns TRUE. Otherwise, $fnsucc returns FALSE.

+

If the return type is BOOL, bool, HANDLE, HRESULT, or NTSTATUS, $fnsucc correctly understands whether the specified return value qualifies as a success code. If the return type is a pointer, all values other than NULL qualify as success codes. For any other type, success is defined by the value of Flag. If Flag is 0, a nonzero value of RetVal is success. If Flag is 1, a zero value of RetVal is success.

$iment (Address)

Returns the address of the image entry point in the loaded module list. Address specifies the Portable Executable (PE) image base address. The entry is found by looking up the image entry point in the PE image header of the image that Address specifies.

+

You can use this function for both modules that are already in the module list and to set [unresolved breakpoints](unresolved-breakpoints---bu-breakpoints-.md) by using the [bu](bp--bu--bm--set-breakpoint-.md) command.

$scmp("String1", "String2")

Evaluates to -1, 0, or 1, like the strcmp C function.

$sicmp("String1", "String2")

Evaluates to -1, 0, or 1, like the stricmp Microsoft Win32 function .

$spat("String", "Pattern")

Evaluates to TRUE or FALSE depending on whether String matches Pattern. The matching is case-insensitive. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md).

$vvalid(Address, Length)

Determines whether the memory range that begins at Address and extends for Length bytes is valid. If the memory is valid, $vvalid evaluates to 1. If the memory is invalid, $vvalid evaluates to 0.

+ +  + +### Registers and Pseudo-Registers in MASM Expressions + +You can use registers and pseudo-registers within MASM expressions. You can add an at sign (@) before all registers and pseudo-registers. The at sign causes the debugger to access the value more quickly. This at sign is unnecessary for the most common x86-based registers. For other registers and pseudo-registers, we recommend that you add the at sign, but it is not actually required. If you omit the at sign for the less common registers, the debugger tries to parse the text as a hexadecimal number, then as a symbol, and finally as a register. + +You can also use a period (.) to indicate the current instruction pointer. You should not add an at sign before this period, and you cannot use a period as the first parameter of the [**r command**](r--registers-.md). This period has the same meaning as the **$ip** pseudo-register. + +For more information about registers and pseudo-registers, see [Register Syntax](register-syntax.md) and [Pseudo-Register Syntax](pseudo-register-syntax.md). + +### Source Line Numbers in MASM Expressions + +You can use source file and line number expressions within MASM expressions. You must enclose these expressions by using grave accents (\`). For more information about the syntax, see [Source Line Syntax](source-line-syntax.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20MASM%20Numbers%20and%20Operators%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/matching-symbol-names.md b/windows-driver-docs-pr/debugger/matching-symbol-names.md new file mode 100644 index 0000000000..5db9163d5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/matching-symbol-names.md @@ -0,0 +1,30 @@ +--- +title: Matching Symbol Names +description: Matching Symbol Names +ms.assetid: 34e2401e-9074-4adc-9644-48ad768c7c2f +--- + +# Matching Symbol Names + + +In certain situations, the actual name of a symbol is replaced with an alternative form which can then result in symbol matching problems. This most commonly happens when changing between public and private symbols or when using MS-DOS compatibility 8.3 short names for files. + +### Public vs. Private Symbol Matching + +Switching between public symbols and private symbols can sometimes cause symbol matching problems. Typically, a public symbol and the corresponding private symbol have the same name with different symbol decorations. But in some cases, they may have entirely different names. In such cases, you might have to explicitly reference both names. For example, you could set up two breakpoints: one on the public symbol, and a second one on the private symbol. For more details, see [Public and Private Symbols](public-and-private-symbols.md). + +### MS-DOS Compatibility 8.3 Short Name Symbol Matching + +Files that have very long names are sometimes given auto-generated MS-DOS compatibility 8.3 short names. Depending on the tools and options used for creating symbol files and for debugging, the file name stored in the image's debug record can be either the long name or one of these short names. If the short names is used, this can cause symbol matching problems because the short name assigned is system dependent. + +For example, suppose there are two files, Longfilename1.pdb and Longfilename2.pdb. If they are put in the same directory one will have an MS-DOS compatibility 8.3 name of Longfi~1.pdb and the other will be Longfi~2.pdb. If they are not put in the same directory they will both be Longfi~1.pdb. Thus, if the associated .pdb files are copied carelessly, the short filenames can change, causing symbol matching problems. For more details, see [File System References and Symbol Files](file-system-references-and-symbol-files.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Matching%20Symbol%20Names%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/memory-access.md b/windows-driver-docs-pr/debugger/memory-access.md new file mode 100644 index 0000000000..795dbaff4d --- /dev/null +++ b/windows-driver-docs-pr/debugger/memory-access.md @@ -0,0 +1,43 @@ +--- +title: Memory Access +description: Memory Access +ms.assetid: a5265f2c-61b9-4f0f-8cff-05da26010c6a +keywords: ["Debugger Engine, memory access", "memory access"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Memory Access + + +## + + +The [debugger engine](introduction.md#debugger-engine) provides [*interfaces*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-interface) to directly read from and write to the target's main memory, registers, and other data spaces. + +In user-mode debugging, only the virtual memory and registers can be accessed; the physical memory and other data spaces cannot be accessed. + +The debugger engine API always uses 64-bit addresses when referring to memory locations on the target. + +If the target uses 32-bit addresses, the native 32-bit address will automatically be sign-extended by the engine to 64-bit addresses. The engine will automatically convert between 64-bit addresses and native 32-bit addresses when communicating with the target. + +This section includes: + +[Virtual and Physical Memory](virtual-and-physical-memory.md) + +[Registers](registers.md) + +[Other Data Spaces](other-data-spaces.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Memory%20Access%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/memory-window.md b/windows-driver-docs-pr/debugger/memory-window.md new file mode 100644 index 0000000000..aac7031b60 --- /dev/null +++ b/windows-driver-docs-pr/debugger/memory-window.md @@ -0,0 +1,125 @@ +--- +title: Viewing and Editing Memory in WinDbg +description: In WinDbg, you can view and edit memory by entering commands or by using a Memory window. +ms.assetid: 4ac3b94c-5d92-4074-bf79-6da151ce52c8 +keywords: ["debugging information windows, Memory window", "Memory window", "memory, Memory window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Viewing and Editing Memory in WinDbg + + +In WinDbg, you can view and edit memory by entering commands or by using a Memory window. + +## Debugger Command Window + + +You can view memory by entering one of the [**Display Memory**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) commands in the Debugger Command window. You can edit memory by entering one of the [**Enter Values**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) commands in the Debugger Command window. For more information, see [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) and [Accessing Memory by Physical Address](accessing-memory-by-physical-address.md). + +## Opening a Memory Window + + +To open a Memory window, choose **Memory** from the **View** menu. (You can also press ALT+5 or click the **Memory** button (![screen shot of the memory button](images/tbmem.png)) on the toolbar. ALT+SHIFT+5 closes the active Memory window.) + +The following screen shot shows an example of a Memory window. + +![screen shot of the memory window](images/window-memory.png) + +## Using a Memory Window + + +The Memory window displays data in several columns. The column on the left side of the window shows the beginning address of each line. The remaining columns display the requested information, from left to right. If you select **Bytes** in the **Display format** menu, the ASCII characters that correspond to these bytes are displayed in the right side of the window. + +**Note**   By default, the Memory window displays virtual memory. This type of memory is the only type of memory that is available in user mode. In kernel mode, you can use the **Memory Options** dialog box to display physical memory and other data spaces. The **Memory Options** dialog box is described later in this topic. + +  + +In the Memory window, you can do the following: + +- To write to memory, click inside the Memory window and type new data. You can edit only hexadecimal data—you cannot directly edit ASCII and Unicode characters. Changes take effect as soon as you type new information. + +- To see other sections of memory, use the **Previous** and **Next** buttons on the Memory window toolbar, or press the PAGE UP or PAGE DOWN keys. These buttons and keys display the immediately preceding or following sections of memory. If you request an invalid page, an error message appears. + +- To navigate within the window, use the RIGHT ARROW, LEFT ARROW, UP ARROW, and DOWN ARROW keys. If you use these keys to move off of the page, a new page is displayed. Before you use these keys, you should resize the Memory window so that it does not have scroll bars. This sizing enables you to distinguish between the actual page edge and the window cutoff. + +- To change the memory location that is being viewed, enter a new address into the address box at the top of the Memory window. Note that the Memory window refreshes its display while you enter an address, so you could get error messages before you have completed typing the address. + **Note**   The address that you enter into the box is interpreted in the current radix. If the current radix is not 16, you should prefix a hexadecimal address with **0x**. To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command in the Debugger Command window. The display within the Memory window itself is not affected by the current radix. + +   + +- To change the data type that the window uses to display memory, use the **Display format** menu in the Memory window toolbar. Supported data types include short words, double words, and quad-words; short, long, and quad integers and unsigned integers; 10-byte, 16-byte, 32-byte, and 64-byte real numbers; ASCII characters; Unicode characters; and hexadecimal bytes. The display of hexadecimal bytes includes ASCII characters as well. + +The Memory window has a toolbar that contains two buttons, a menu, and a box and has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button that displays the memory window toolbar shortcut menu](images/tbmem.png)). The toolbar and shortcut menu contain the following choices: + +- (Toolbar only) The address box enables you to specify a new address or offset. The exact meaning of this box depends on the memory type you are viewing. For example, if you are viewing virtual memory, the box enables you to specify a new virtual address or offset. + +- (Toolbar only) **Display format** enables you to select a new display format. + +- (Toolbar and menu) **Previous** (on the toolbar) and **Previous page** (on the shortcut menu) cause the previous section of memory to be displayed. + +- (Toolbar and menu) **Next** (on the toolbar) and **Next page** (on the shortcut menu) cause the next section of memory to be displayed. + +- (Menu only) **Toolbar** turns the toolbar on and off. + +- (Menu only) **Auto-fit columns** ensures that the number of columns displayed in the Memory window fits the width of the Memory window. + +- (Menu only) **Dock** or **Undock** causes the window to enter or leave the docked state. + +- (Menu only) **Move to new dock** closes the Memory window and opens it in a new dock. + +- (Menu only) **Set as tab-dock target for window type** sets the selected Memory window as the tab-dock target for other Memory windows. All Memory windows that are opened after one is chosen as the tab-dock target are automatically grouped with that window in a tabbed collection. + +- (Menu only) **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- (Menu only) **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +- (Menu only) **Properties** opens the **Memory Options** dialog box, which is described in the following section within this topic. + +- (Menu only) **Help** opens this topic in the Debugging Tools for Windows documentation. + +- (Menu only) **Close** closes this window. + +### Memory Options Dialog Box + +When you click **Properties** on the shortcut menu, the **Memory Options** dialog box appears. + +In kernel mode, there are six memory types available as tabs in this dialog box: **Virtual Memory**, **Physical Memory**, **Bus Data**, **Control Data**, **I/O** (I/O port information), and **MSR** (model-specific register information). Click the tab that corresponds to the information that you want to access. + +In user mode, only the **Virtual Memory** tab is available. + +Each tab enables you to specify the memory that you want to display: + +- In the **Virtual Memory** tab, in the **Offset** box, specify the address or offset of the beginning of the memory range that you want to view. + +- In the **Physical Memory** tab, in the **Offset** box, specify the physical address of the beginning of the memory range that you want to view. The Memory window can display only described, cacheable physical memory. If you want to display physical memory that has other attributes, use the [**d\* (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command or the [**!d\***](-db---dc---dd---dp---dq---du---dw.md) extension. + +- In the **Bus Data** tab, in the **Bus Data Type** menu, specify the bus data type. Then, use the **Bus number**, **Slot number**, and **Offset** boxes to specify the bus data that you want to view. + +- In the **Control Data** tab, use the **Processor** and **Offset** text boxes to specify the control data that you want to view. + +- In the **I/O** tab, in the **Interface Type** menu, specify the I/O interface type. Use the **Bus number**, **Address space**, and **Offset** boxes to specify the data that you want to view. + +- In the **MSR** tab, in the **MSR** box, specify the model-specific register that you want to view. + +Each tab also includes a **Display format** menu. This menu has the same effect as the **Display format** menu in the Memory window. + +Click **OK** in the **Memory Options** dialog box to cause your changes to take effect. + +## Additional Information + + +For more information about memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Memory%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/memory.md b/windows-driver-docs-pr/debugger/memory.md new file mode 100644 index 0000000000..0db244be25 --- /dev/null +++ b/windows-driver-docs-pr/debugger/memory.md @@ -0,0 +1,32 @@ +--- +title: Memory +description: Memory +ms.assetid: 4aa5cf2b-e5f8-4358-b2cc-c677cd012f46 +keywords: ["Debugger Engine, memory", "data spaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Memory + + +The [debugger engine](introduction.md#debugger-engine) can directly read and write the target's main memory, registers, and other data spaces. In kernel-mode debugging, all of the target's memory is available, including virtual memory, physical memory, registers, Model Specific Registers (MSRs), System Bus Memory, Control-Space Memory, and I/O Memory. In user-mode debugging, only the virtual memory and registers are available. + +The engine exposes, to the clients, all memory in the target using 64-bit addresses. If the target uses 32-bit addresses, when communicating with the target and the clients, the engine will automatically convert between 32-bit and 64-bit addresses, as needed. If a 32-bit address is recovered from the target--for example, by reading from memory or a register--it must be sign-extended to 64 bits before it can be used in the debugger engine API. Sign extension is performed automatically by the **ReadPointersVirtual** method. + +### Additional Information + +For details about reading and writing memory, see [Memory Access](memory-access.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Memory%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/messages-from-the-target.md b/windows-driver-docs-pr/debugger/messages-from-the-target.md new file mode 100644 index 0000000000..8729392d61 --- /dev/null +++ b/windows-driver-docs-pr/debugger/messages-from-the-target.md @@ -0,0 +1,39 @@ +--- +title: Messages from the Target +description: Messages from the Target +ms.assetid: d2ef68c6-90be-434a-b719-1619b063da47 +keywords: ["debugging messages", "debugging messages, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Messages from the Target + + +## + + +A target application or target computer can send messages to the debugger or break into the debugger, either conditionally or unconditionally, by using a variety of routines. A kernel-mode target can also test whether a debugger is currently attached. + +This section includes: + +- [Breaking Into the Debugger](breaking-into-the-debugger.md) + +- [Sending Output to the Debugger](sending-output-to-the-debugger.md) + +- [Reading and Filtering Debugging Messages](reading-and-filtering-debugging-messages.md) + +- [Determining if a Debugger is Attached](determining-if-a-debugger-is-attached.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Messages%20from%20the%20Target%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/meta-commands.md b/windows-driver-docs-pr/debugger/meta-commands.md new file mode 100644 index 0000000000..ea7aadae84 --- /dev/null +++ b/windows-driver-docs-pr/debugger/meta-commands.md @@ -0,0 +1,29 @@ +--- +title: Meta-Commands +description: This section of the reference discusses the various debugger meta-commands that can be used in CDB, KD, and WinDbg. +ms.assetid: 8aa960d4-834c-46f5-aa9f-b528402ad52c +keywords: debug, Windbg, meta-commands, commands +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Meta-Commands + + +## + + +This section of the reference discusses the various debugger *meta-commands* that can be used in CDB, KD, and WinDbg. These commands are preceded by a period (.). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Meta-Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/metadata-files-for-analysis-extensions.md b/windows-driver-docs-pr/debugger/metadata-files-for-analysis-extensions.md new file mode 100644 index 0000000000..c6560d9622 --- /dev/null +++ b/windows-driver-docs-pr/debugger/metadata-files-for-analysis-extensions.md @@ -0,0 +1,107 @@ +--- +title: Metadata Files for Analysis Extension Plug-ins +description: When you write an analysis extension plug-in, you also write a metadata file that describes the situations for which you want your plug-in to be called. +ms.assetid: 13B9B7A5-1D68-49A3-825B-454AC070FCC1 +--- + +# Metadata Files for Analysis Extension Plug-ins + + +When you write an analysis extension plug-in, you also write a metadata file that describes the situations for which you want your plug-in to be called. When the [**!analyze**](-analyze.md) debugger command runs, it uses metadata files to determine which plug-ins to load. + +Create a metadata file that has the same name as your analysis extension plug-in and an extension of .alz. For example, if your analysis extension plug-in is named MyAnalyzer.dll, your metadata file must be named MyAnalyzer.alz. Place the metadata file in the same directory as your analysis extension plug-in. + +A metadata file for an analysis extension plug-in is an ASCII text file that contains key-value pairs. Keys and values are separated by white space. A key can have any non-whitespace character. Keys are not case sensitive. + +After the key and the following white space, the corresponding value begins. A value can have one of the following forms. + +- Any set of characters to the end of the line. This form works for values that do not contain any newline characters. + + **Important**  If the last value in the metadata file has a value of this form, the line must end with a newline character. + +   + +- Any set of characters between braces { }. The form works for values that contain newline characters. + +A line beginning with \# is a comment and is ignored. Comments can start only where keys are expected. + +You can use the following keys in a metadata file. + +| Key | Description | +|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| PluginId | String - Identifies the plug-in. | +| DebuggeeClass | String - Possible values are “Kernel” and "User". Indicates that the plug-in is interested in analyzing only kernel-mode failures or only user-mode failures. | +| BugCheckCode | 32-bit bug check code - Indicates that the plug-in is interested in analyzing this [bug check code](bug-check-code-reference2.md). A single metadata file can specify multiple bug check codes. | +| ExceptionCode | 32-bit exception code - Indicates that the plug-in is interested in analyzing this [exception code](http://go.microsoft.com/fwlink/p?LinkID=282670). A single metadata file can specify multiple exception codes. | +| ExecutableName | String - Indicates that the plug-in is interested only in sessions where this is the running executable of the process to be analyzed. A single metadata file can specify multiple executable names. | +| ImageName | String - Indicates that the plug-in is only interested only in sessions where the default analysis considers this image (dll, sys, or exe) to be at fault. The plug-in is invoked after analysis has determined which image is at fault. A single metadata file can specify multiple image names. | +| MaxTagCount | Integer - The maximum number of custom tags that the plug-in needs. Custom tags are tags other than the ones defined in extsfns.h. | + +  + +## Example Metadata Files + + +The following metadata file describes a plug-in that is interested in analyzing bug check code 0xE2. (Recall that the last line must end with a newline character.) + +``` +PluginId MyPlugin +DebuggeeClass Kernel +BugCheckCode 0xE2 +``` + +The following metadata file describes a plug-in that is interested in analyzing bug checks 0x8, 0x9, and 0xA if MyDriver.sys is considered to be the module at fault. + +``` +PluginId MyPlugin +DebuggeeClass Kernel +BugCheckCode 0x8 +BugCheckCode 0x9 +BugCheckCode 0xA +ImageName MyDriver.sys +``` + +The following metadata file describes a plug-in that is interested in analyzing exception code 0xC0000005 if MyApp.exe is the running executable of the process being analyzed. Also, the plug-in might create as many as three custom tags. + +``` +PluginId MyPlugin +DebuggeeClass User +ExceptionCode 0xC0000005 +ExecutableName MyApp.exe +``` + +Debugging Tools for Windows has a sample that you can use to build a debugger extension module named dbgexts.dll. This extension module implements several debugger extension commands, but it can also serve as an analysis extension plug-in; that is, it exports an [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function. Here is a metadata file that describes dbgexts.dll as an analysis extension plug-in. + +``` +PluginId PluginSample +DebuggeeClass User +ExceptionCode 0xc0000005 +ExecutableName cdb.exe +ExecutableName windbg.exe +# +# Custom tag descriptions +# +TagDesc 0xA0000000 SAMPLE_PLUGIN_DEBUG_TEXT {Sample debug +help text from plug-in analysis} +# +``` + +## Related topics + + +[Writing an Analysis Extension Plug-in to Extend !analyze](writing-an-analysis-extension-to-extend--analyze.md) + +[**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) + +[**!analyze**](-analyze.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Metadata%20Files%20for%20Analysis%20Extension%20Plug-ins%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/methods-of-controlling-breakpoints.md b/windows-driver-docs-pr/debugger/methods-of-controlling-breakpoints.md new file mode 100644 index 0000000000..5cd954f68f --- /dev/null +++ b/windows-driver-docs-pr/debugger/methods-of-controlling-breakpoints.md @@ -0,0 +1,92 @@ +--- +title: Methods of Controlling Breakpoints +description: Methods of Controlling Breakpoints +ms.assetid: 69de05e8-1b41-403a-a628-88da9528e1ab +keywords: ["breakpoints, controlling"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Methods of Controlling Breakpoints + + +You can specify the location of a breakpoint by virtual address, module and routine offsets, or source file and line number (when in source mode). If you put a breakpoint on a routine without an offset, the breakpoint is activated when that routine is entered. + +There are several additional kinds of breakpoints: + +- A breakpoint can be associated with a certain thread. + +- A breakpoint can enable a fixed number of passes through an address before it is triggered. + +- A breakpoint can automatically issue certain commands when it is triggered. + +- A breakpoint can be set on non-executable memory and watch for that location to be read or written to. + +If you are debugging more than one process in user mode, the collection of breakpoints depends on the current process. To view or change a process' breakpoints, you must select the process as the current process. For more information about the current process, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +### Debugger Commands for Controlling and Displaying Breakpoints + +To control or display breakpoints, you can use the following methods: + +- Use the [**bl (Breakpoint List)**](bl--breakpoint-list-.md) command to list existing breakpoints and their current status. + +- Use the [**.bpcmds (Display Breakpoint Commands)**](-bpcmds--display-breakpoint-commands-.md) command to list all breakpoints along with the commands that were used to create them. + +- Use the [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command to set a new breakpoint. + +- Use the [**bu (Set Unresolved Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command to set a new breakpoint. Breakpoints that are set with **bu** are called unresolved breakpoints; they have different characteristics than breakpoints that are set with **bp**. For complete details, see [Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md). + +- Use the [**bm (Set Symbol Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command to set new breakpoints on symbols that match a specified pattern. A breakpoint set with **bm** will be associated with an address (like a **bp** breakpoint) if the **/d** switch is included; it will be unresolved (like a **bu** breakpoint) if this switch is not included. + +- Use the [**ba (Break on Access)**](ba--break-on-access-.md) command to set a *processor breakpoint*, also known as a *data breakpoint*. These breakpoints can be triggered when the memory location is written to, when it is read, when it is executed as code, or when kernel I/O occurs. For complete details, see [Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md). + +- Use the [**bc (Breakpoint Clear)**](bc--breakpoint-clear-.md) command to permanently remove one or more breakpoints. + +- Use the [**bd (Breakpoint Disable)**](bd--breakpoint-disable-.md) command to temporarily disable one or more breakpoints. + +- Use the [**be (Breakpoint Enable)**](be--breakpoint-enable-.md) command to re-enable one or more disabled breakpoints. + +- Use the [**br (Breakpoint Renumber)**](br--breakpoint-renumber-.md) command to change the ID of an existing breakpoint. + +- Use the [**bs (Update Breakpoint Command)**](bs--update-breakpoint-command-.md) command to change the command associated with an existing breakpoint. + +- Use the [**bsc (Update Conditional Breakpoint)**](bsc--update-conditional-breakpoint-.md) command to change the condition under which an existing conditional breakpoint occurs. + +In Visual Studio and WinDbg, there are several user interface elements that facilitate controlling and displaying breakpoints. See [Setting Breakpoints in Visual Studio](setting-breakpoints-in-visual-studio.md) and [Setting Breakpoints in WinDbg](setting-breakpoints-in-windbg.md). + +Each breakpoint has a decimal number called the breakpoint ID associated with it. This number identifies the breakpoint in various commands. + +### Breakpoint Commands + +You can include a command in a breakpoint that is automatically executed when the breakpoint is hit. For example, the following command breaks at MyFunction+0x47, writes a dump file, and then resumes execution. + +``` +0:000> bu MyFunction+0x47 ".dump c:\mydump.dmp; g" +``` + +**Note**  If you are controlling the user-mode debugger from the kernel debugger, do not use [**g (Go)**](g--go-.md) in the breakpoint command string. The serial interface might be unable to keep up with this command, and you will be unable to break back into CDB. For more information about this situation, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +  + +### Number of Breakpoints + +In kernel mode, you can use a maximum of 32 software breakpoints. In user mode, you can use any number of software breakpoints. + +The number of processor breakpoints that are supported depends on the target processor architecture. + +### Conditional Breakpoints + +You can set a breakpoint that is triggered only under certain conditions. For more information about these kinds of breakpoints, see [Setting a Conditional Breakpoint](setting-a-conditional-breakpoint.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Methods%20of%20Controlling%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/microsoft-public-symbols.md b/windows-driver-docs-pr/debugger/microsoft-public-symbols.md new file mode 100644 index 0000000000..8a50746c18 --- /dev/null +++ b/windows-driver-docs-pr/debugger/microsoft-public-symbols.md @@ -0,0 +1,52 @@ +--- +title: Microsoft public symbol server +description: The Microsoft symbol server makes Windows debugger symbols publicly available. +ms.assetid: b0d38104-c386-4d20-8d9c-7701347c1643 +keywords: ["SymSrv, public Microsoft symbols", "symbol servers, public Microsoft symbols", "public symbol store", "Microsoft symbol store"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Microsoft public symbol server + + +The Microsoft symbol server makes Windows debugger symbols publicly available. + +You can refer directly to the public symbol server in your symbol path in the following manner: + +``` +set _NT_SYMBOL_PATH=srv*DownstreamStore*https://msdl.microsoft.com/download/symbols +``` + +*DownstreamStore* must specify a directory on your local computer or network that will be used to cache symbols. This downstream store holds symbols that the debugger has accessed; the vast majority of symbols that have never been accessed remain on the symbol store at Microsoft. This keeps your downstream store relatively small and allows the symbol server to work quickly, only downloading each file once. + +To avoid typing this long symbol path, use the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command. The following command appends the public symbol store to your existing symbol path: + +``` +.symfix+ DownstreamStore +``` + +**Note**   To successfully access Microsoft's public symbol store, you will need a fast internet connection. If your internet connection is only 56 Kbps or slower, you should install Windows symbols directly onto your hard drive. For details, see [Installing Windows Symbol Files](installing-windows-symbol-files.md). + +  + +For more information about the public symbol store, see the [Windows Symbols](http://go.microsoft.com/fwlink/p/?linkid=17363) Web site. + +**Symbol File Compression** + +The Microsoft Symbol Server provides compressed versions of the symbol files. The files have an underscore at the end of the filename’s extension to indicate that they are compressed. For example, the PDB for ntdll.dll is available as ntdll.pd\_. When SymProxy downloads a compressed file, it will store the file decompressed in the local file system. The DontUncompress registry key can be set to disable this behavior in SymProxy. + +Refer to the Debugger topic [SymStore](symstore.md) for information on using SymStore.exe /compress to store your own symbols compressed on your symbol server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Microsoft%20public%20symbol%20server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/minidumps.md b/windows-driver-docs-pr/debugger/minidumps.md new file mode 100644 index 0000000000..7823c3424c --- /dev/null +++ b/windows-driver-docs-pr/debugger/minidumps.md @@ -0,0 +1,112 @@ +--- +title: Minidumps +description: Minidumps +ms.assetid: 2cb54df3-2e61-4d5c-9ef6-3c81787d2233 +keywords: ["dump file, minidump", "minidump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Minidumps + + +## + + +A user-mode dump file that includes only selected parts of the memory associated with a process is called a *minidump*. + +The size and contents of a minidump file vary depending on the program being dumped and the application doing the dumping. Sometimes, a minidump file is fairly large and includes the full memory and handle table. Other times, it is much smaller -- for example, it might only contain information about a single thread, or only contain information about modules that are actually referenced in the stack. + +The name "minidump" is misleading, because the largest minidump files actually contain more information than the "full" user-mode dump. For example, **.dump /mf** or **.dump /ma** will create a larger and more complete file than **.dump /f**. For this reason, **.dump /m**\[*MiniOptions*\] recommended over **.dump /f** for all user-mode dump file creation. + +If you are creating a minidump file with the debugger, you can choose exactly what information to include. A simple **.dump /m** command will include basic information about the loaded modules that make up the target process, thread information, and stack information. This can be modified by using any of the following options: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
.dump optionEffect on dump file

/ma

Creates a minidump with all optional additions. The /ma option is equivalent to /mfFhut -- it adds full memory data, handle data, unloaded module information, basic memory information, and thread time information to the minidump.

/mf

Adds full memory data to the minidump. All accessible committed pages owned by the target application will be included.

/mF

Adds all basic memory information to the minidump. This adds a stream to the minidump that contains all basic memory information, not just information about valid memory. This allows the debugger to reconstruct the complete virtual memory layout of the process when the minidump is being debugged.

/mh

Adds data about the handles associated with the target application to the minidump.

/mu

Adds unloaded module information to the minidump. This is only available in Windows Server 2003 and later versions of Windows.

/mt

Adds additional thread information to the minidump. This includes thread times, which can be displayed by using [.ttime (Display Thread Times)](-ttime--display-thread-times-.md) when debugging the minidump.

/mi

Adds secondary memory to the minidump. Secondary memory is any memory referenced by a pointer on the stack or backing store, plus a small region surrounding this address.

/mp

Adds process environment block (PEB) and thread environment block (TEB) data to the minidump. This can be useful if you need access to Windows system information regarding the application's processes and threads.

/mw

Adds all committed read-write private pages to the minidump.

/md

Adds all read-write data segments within the executable image to the minidump.

/mc

Adds code sections within images.

/mr

Deletes from the minidump those portions of the stack and store memory that are not useful for recreating the stack trace. Local variables and other data type values are deleted as well. This option does not make the minidump smaller (since these memory sections are simply zeroed), but it is useful if you wish to protect the privacy of other applications.

/mR

Deletes the full module paths from the minidump. Only the module names will be included. This is a useful option if you wish to protect the privacy of the user's directory structure.

/mk " FileName "

(Windows Vista only) Creates a kernel-mode minidump in addition to the user-mode minidump. The kernel-mode minidump will be restricted to the same threads that are stored in the user-mode minidump. FileName must be enclosed in quotation marks.

+ +  + +These options can be combined. For example, the command **.dump /mfiu** can be used to create a fairly large minidump, or the command **.dump /mrR** can be used to create a minidump that preserves the user's privacy. For full syntax details, see [**.dump (Create Dump File)**](-dump--create-dump-file-.md). + +For details on the internals of minidump files, see the DbgHelp Reference in the Microsoft Windows SDK. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Minidumps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/modifying-the-source-indexing-streams-in-a--pdb-file.md b/windows-driver-docs-pr/debugger/modifying-the-source-indexing-streams-in-a--pdb-file.md new file mode 100644 index 0000000000..57fc0f0bee --- /dev/null +++ b/windows-driver-docs-pr/debugger/modifying-the-source-indexing-streams-in-a--pdb-file.md @@ -0,0 +1,40 @@ +--- +title: Modifying the Source Indexing Streams in a .pdb File +description: Modifying the Source Indexing Streams in a .pdb File +ms.assetid: 9c319667-fc71-4baf-ad12-a20e18b67d40 +--- + +# Modifying the Source Indexing Streams in a .pdb File + + +For the debugger clients to use the SrcSrv Web site, the .pdb files must be modified to point to it. To do this manually, you make a copy of all the .pdb files, change them, and make them available from a separate location--usually the Web site itself. + +Debugging Tools for Windows provides three files to assist in reconfiguring the .pdb files. The Cv2http.cmd and Cv2http.pl files extract the SrcSrv stream, modify it using a Perl script, and put the altered stream back in the .pdb file. The syntax is as follows: + +``` +cv2http.cmd PDB Alias URL +``` + +where *PDB* specifies the name of the .pdbfile to modify, *Alias* specifies the logical name to apply to your Web site, and *URL* specifies the full URL of the site. Note that the *Alias* parameter is stored in the PDB as a variable name that can be overridden on the debugger client in Scrsrv.ini, should you ever move the location of the Web site. + +This script requires that all the standard SrcSrv tools be available in the path because it calls both SrcTool and PDBStr. Remember that Cv2http.pl is a Perl script and can be modified to meet your needs. + +The third file, the Walk (walk.cmd) script, modifies an entire set of .pdb files. For example: + +``` +walk.cmd *.pdb cv2http.cmd HttpAlias https:///source +``` + +The preceding command calls Cv2http.cmd on every .pdb file in a tree, using HttpAlias for the alias and https://server/source for the URL. For more details on Walk, see [Extracting Source Files](extracting-source-files.md). + +After this command is executed on a tree of .pdb files, they are ready for installation into the Web site or whatever location in which you want to put them. Remember that you can use SrcTool and PDBStr to examine the changes to the .pdb files. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Modifying%20the%20Source%20Indexing%20Streams%20in%20a%20.pdb%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/modules.md b/windows-driver-docs-pr/debugger/modules.md new file mode 100644 index 0000000000..9b26f548ee --- /dev/null +++ b/windows-driver-docs-pr/debugger/modules.md @@ -0,0 +1,77 @@ +--- +title: Modules +description: Modules +ms.assetid: 0cd99869-4014-4f9f-b5f1-d06c69fd134e +keywords: ["symbols, modules", "modules"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Modules + + +## + + +An *image* is an executable, DLL, or driver that Windows has loaded as part of a user-mode process or the kernel. The file from which the image was loaded is referred to as its *image file*. + +The [debugger engine](introduction.md#debugger-engine) caches a list of *modules* for each process (or, in kernel-mode, the virtual process). Typically each module in this list represents an image in the process. The engine's module list can be synchronized with the target using **Reload**. + +**Note**   In kernel-mode debugging, the engine's module list for the virtual process contains both the system-wide kernel-mode modules and the current process's user-mode modules. + +  + +A module can be specified by its base address in the target's virtual address space, or by its index in the list of modules the engine maintains for the target. The module's index equals its position in the list of modules, and therefore this index will change if a module with a lower index is unloaded. All unloaded modules have indexes; these are always higher than the indexes of loaded modules. The base address of a module will not change as long as it remains loaded; in some cases it may change if the module is unloaded and then reloaded. + +The index is a number between zero and the number of modules in the target minus one. The number of modules in the current process can be found by calling [**GetNumberModules**](https://msdn.microsoft.com/library/windows/hardware/ff547927). + +The index can be used to find the base address by calling [**GetModuleByIndex**](https://msdn.microsoft.com/library/windows/hardware/ff547080). The base address of a module owning a symbol with a given name can be found using [**GetSymbolModule**](https://msdn.microsoft.com/library/windows/hardware/ff549112). + +The following methods return both the index and base address of the specified module: + +- To find a module with a given module name, use [**GetModuleByModuleName**](https://msdn.microsoft.com/library/windows/hardware/ff547095). + +- The module whose virtual address range contains a given address is returned by [**GetModuleByOffset**](https://msdn.microsoft.com/library/windows/hardware/ff547132). This method can be used to find the module index given the base address of the module. + +The following methods return information about modules specified either by base address or index: + +- The names of a module are returned by [**GetModuleNames**](https://msdn.microsoft.com/library/windows/hardware/ff547146) and [**GetModuleNameString**](https://msdn.microsoft.com/library/windows/hardware/ff547149). + +- Version information for the module is returned by [**GetModuleVersionInformation**](https://msdn.microsoft.com/library/windows/hardware/ff547170). + +- Some of the parameters used to describe a module are returned by [**GetModuleParameters**](https://msdn.microsoft.com/library/windows/hardware/ff547161). For details on the parameters returned by this method, see [**DEBUG\_MODULE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff541514). + +### Unloaded Modules + +During user-mode debugging, unloaded modules are tracked only in Windows Server 2003 and later versions of Windows. Earlier versions of Windows only tracked unloaded modules in kernel mode. When they are tracked, they are indexed after the loaded modules. Hence any method that searches the target's modules will search all the loaded modules and then the unloaded modules. Unloaded modules can be used to analyze failures caused by an attempt to call unloaded code. + +### Synthetic Modules + +*Synthetic modules* can be created as a way to label a region of memory. These modules cannot contain real symbols, but they can contain synthetic symbols. The method [**AddSyntheticModule**](https://msdn.microsoft.com/library/windows/hardware/ff537937) creates a new synthetic module. Synthetic modules can be removed using [**RemoveSyntheticModule**](https://msdn.microsoft.com/library/windows/hardware/ff554536). Reloading all the modules in the target deletes all synthetic modules. + +### Image Path + +The *executable image path* is used by the engine when searching for executable images. + +The executable image path can consist of several directories separated by semicolons (**;**). These directories are searched in order. + +For an overview of the executable image path, see Executable Image Path. + +To add a directory to the executable image path, use the method [**AppendImagePath**](https://msdn.microsoft.com/library/windows/hardware/ff538092). The whole executable image path is returned by [**GetImagePath**](https://msdn.microsoft.com/library/windows/hardware/ff546851) and can be changed using [**SetImagePath**](https://msdn.microsoft.com/library/windows/hardware/ff556708). + +### Additional Information + +For more information about processes and virtual processes, see [Threads and Processes](controlling-threads-and-processes.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Modules%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/monitoring-events.md b/windows-driver-docs-pr/debugger/monitoring-events.md new file mode 100644 index 0000000000..3ec5190f7c --- /dev/null +++ b/windows-driver-docs-pr/debugger/monitoring-events.md @@ -0,0 +1,73 @@ +--- +title: Monitoring Events +description: Monitoring Events +ms.assetid: f0381cf9-e568-4789-af08-69d8b2c3ecbf +keywords: ["Debugger Engine, events", "events"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Monitoring Events + + +## + + +For an overview of events in the [debugger engine](introduction.md#debugger-engine), see [Events](events.md). + +Events occurring in a target or the debugger engine may be monitored using the [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550) interface. An **IDebugEventCallbacks** object may be registered with a client using [*SetEventCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556671). Each client can only have at most one **IDebugEventCallbacks** object registered with it. + +When an **IDebugEventCallbacks** object is registered with a client, the engine will call the object's [**IDebugEventCallbacks::GetInterestMask**](https://msdn.microsoft.com/library/windows/hardware/ff550737) to determine which events the object is interested in. Only events in which the object is interested will be sent to it. + +For each type of event, the engine calls a corresponding callback method on [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550). For events from the target, the [**DEBUG\_STATUS\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541651) value returned from these calls specifies how the execution of the target should proceed. The engine collects these return values from each **IDebugEventCallbacks** object it calls and acts on the one with the highest precedence. + +### Events from the Target That Break into the Debugger by Default + +The following events break into the debugger by default: + +- Breakpoint Events + +- Exception Events (not documented here) + +- System Error + +### Events from the Target that Do Not Break into the Debugger by Default + +The following events do not break into the debugger by default: + +- Create Process Event + +- Exit Process Event + +- Create Thread Event + +- Exit Thread Event + +- Load Module Event + +- Unload Module Event + +### Internal Engine Changes + +The following are not actual events, but are merely internal engine changes: + +- Target Change + +- Engine Change + +- Engine Symbol Change + +- Session Status Change + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Monitoring%20Events%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/moving-through-a-window.md b/windows-driver-docs-pr/debugger/moving-through-a-window.md new file mode 100644 index 0000000000..b90bf61fae --- /dev/null +++ b/windows-driver-docs-pr/debugger/moving-through-a-window.md @@ -0,0 +1,63 @@ +--- +title: Moving Through a Window +description: Moving Through a Window +ms.assetid: c164a446-1f6c-4d37-8ad6-aa254d3268bc +keywords: ["debugging information windows, navigating"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Moving Through a Window + + +## + + +There are several ways of moving through a debugging information window. + +If a scrollbar appears in the window, you can use it to display more of the window. + +In addition, some windows support the **Find**, **Go to Address**, or **Go to Line** commands. These commands only change the WinDbg display. They do not affect the execution of the target or any other debugger operations. + +### Find Command + +You can use the **Find** command in the [Debugger Command window](debugger-command-window.md) or in a [Source window](source-window.md). + +When one of these windows is active, click **Find** on the **Edit** menu or press CTRL+F. The **Find** dialog box opens. + +Enter the text that you want to find in the dialog box, and select **Up** or **Down** to determine the direction of your search. The search begins wherever the cursor is in the window. You can put the cursor at any point by using the mouse. + +Select the **Match whole word only** check box if you want to search for a single whole word. (If you select this check box and you enter multiple words, this check box is ignored.) Select the **Match case** check box to perform a case-sensitive search. + +If you close the **Find** dialog box, you can repeat the previous search in a forward direction by clicking **Find Next** on the **Edit** menu or pressing F3. You can repeat the search in a backward direction by pressing SHIFT+F3. + +### Go to Address Command + +The **Go to Address** command searches for an address in the application that you are debugging. To use this option, click **Go to Address** on the **Edit** menu or press CTRL+G. + +When the **View Code Offset** dialog box appears, enter the address that you want to search for. You can enter this address as an expression, such as a function, symbol, or integer memory address. If the address is ambiguous, a list appears with all of the ambiguous items. + +After you click **OK**, the debugger moves the cursor to the beginning of the function or address in the [Disassembly window](disassembly-window.md) or a [Source window](source-window.md). + +You can use the **Go to Address** command regardless of which debugging information window is open. If the debugger is in disassembly mode, the debugger finds the address that you are searching for in the Disassembly window. If the debugger is in source mode, the debugger tries to find the address in a Source window. If the debugger cannot find the address in a Source window, the debugger finds the address in the Disassembly window. If the needed window is not open, the debugger opens it. + +### Moving to a Specific Line + +The **Go to Line** command searches for a line number in the active Source window. If the active window is not a Source window, you cannot use the **Go to Line** command. + +To activate this option, click **Go to Line** on the **Edit** menu or press CTRL+L. + +When the **Go to Line** dialog box appears, enter the line number that you want to find and then click **OK**. The debugger moves the cursor to that line. If the line number is larger than the last line in the file, the cursor moves to the end of the file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Moving%20Through%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/multiprocessor-syntax.md b/windows-driver-docs-pr/debugger/multiprocessor-syntax.md new file mode 100644 index 0000000000..cc1e2d435a --- /dev/null +++ b/windows-driver-docs-pr/debugger/multiprocessor-syntax.md @@ -0,0 +1,114 @@ +--- +title: Multiprocessor Syntax +description: This topic covers Multiprocessor Syntax +ms.assetid: 71adc522-f078-457c-8bc9-9e971e914a41 +keywords: multiprocessor computer, multiprocessor, command syntax, dual-processor computer, syntax rules for commands, processor identifier +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Multiprocessor Syntax + + +## + + +KD and kernel-mode WinDbg support multiple processor debugging. You can perform this kind of debugging on any multiprocessor platform. + +Processors are numbered zero through *n*. + +If the current processor is processor 0 (that is, if it is the processor that currently caused the debugger to be active), you can examine the other non-current processors (processors one through *n*). However, you cannot change anything in the non-current processors. You can only view their state. + +### Selecting a Processor + +You can use the [**.echocpunum (Show CPU Number)**](-echocpunum--show-cpu-number-.md) command to display the processor numbers of the current processor. The output from this command enables you to immediately tell when you are working on a multiple processor system by the text in the kernel debugging prompt. + +In the following example, **0:** in front of the **kd>** prompt indicates that you are debugging the first processor in the computer. + +``` +0: kd> +``` + +Use the [**~s (Change Current Processor)**](-s--change-current-processor-.md) command to switch between processors, as the following example shows. + +``` +0: kd> ~1s +1: kd> +``` + +Now you are debugging the second processor in the computer. + +You might have to change processors on a multiprocessor system if you encounter a break and you cannot understand the stack trace. The break might have occurred on a different processor. + +### Specifying Processors in Other Commands + +You can add a processor number before several commands. This number is not preceded by a tilde (**~**), except in the **~S** command. + +**Note**   In user-mode debugging, the tilde is used to specify threads. For more information about this syntax, see [Thread Syntax](thread-syntax.md). + +  + +Processor IDs do not have to be referred to explicitly. Instead, you can use a numerical expression that resolves to an integer that corresponds to a processor ID. To indicate that the expression should be interpreted as a processor, use the following syntax. + +``` +||[Expression] +``` + +In this syntax, the square brackets are required, and *Expression* stands for any numerical expression that resolves to an integer that corresponds to a processor ID. + +In the following example, the processor changes depending on the value of a user-defined pseudo-register. + +``` +||[@$t0] +``` + +### Examples + +The following example uses the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) command to display a stack trace from processor two. + +``` +1: kd> 2k +``` + +The following example uses the [**r (Registers)**](r--registers-.md) command to display the **eax** register of processor three. + +``` +1: kd> 3r eax +``` + +However, the following command gives a syntax error, because you cannot change the state of a processor other than the current processor. + +``` +1: kd> 3r eax=808080 +``` + +### Breakpoints + +During kernel debugging, the [**bp, bu, bm (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) and [**ba (Break on Access)**](ba--break-on-access-.md) commands apply to all processors of a multiple processor computer. + +For example, if the current processor is three, you can enter the following command to put a breakpoint at **SomeAddress**. + +``` +1: kd> bp SomeAddress +``` + +Then, any processor (not only processor one) that executes at that address causes a breakpoint trap. + +### Displaying Processor Information + +You can use the [**!running**](-running.md) extension to display the status of each processor on the target computer. For each processor, **!running** can also display the current and next thread fields from the process control block (PRCB), the state of the 16 built-in queued spinlocks, and a stack trace. + +You can use the [**!cpuinfo**](-cpuinfo.md) and [**!cpuid**](-cpuid.md) extensions to display information about the processors themselves. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Multiprocessor%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/n--set-number-base-.md b/windows-driver-docs-pr/debugger/n--set-number-base-.md new file mode 100644 index 0000000000..65a911d707 --- /dev/null +++ b/windows-driver-docs-pr/debugger/n--set-number-base-.md @@ -0,0 +1,109 @@ +--- +title: n (Set Number Base) +description: The n command sets the default number base (radix) to the specified value or displays the current number base.Do not confuse this command with the ~n (Suspend Thread) command. +ms.assetid: a2af7cf4-b0f1-4ceb-b9c0-7517a9517c3e +keywords: ["n (Set Number Base) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- n (Set Number Base) +api_type: +- NA +--- + +# n (Set Number Base) + + +The **n** command sets the default number base (radix) to the specified value or displays the current number base. + +Do not confuse this command with the [**~n (Suspend Thread)**](-n--suspend-thread-.md) command. + +``` +n [Radix] +``` + +## Parameters + + + *Radix* +Specifies the default number base that is used for numeric display and entry. You can use one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + +
ValueDescription

8

Octal

10

Decimal

16

Hexadecimal

+ +  + +If you omit *Radix*, the current default number base is displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The current radix affects the input and output of MASM expressions. It does not affect the input or output of C++ expressions. For more information about these expressions, see [Evaluating Expressions](evaluating-expressions.md). + +The default radix is set to 16 when the debugger is started. + +In all MASM expressions, numeric values are interpreted as numbers in the current radix (16, 10, or 8). You can override the default radix by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20n%20%28Set%20Number%20Base%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/n.md b/windows-driver-docs-pr/debugger/n.md new file mode 100644 index 0000000000..890019c094 --- /dev/null +++ b/windows-driver-docs-pr/debugger/n.md @@ -0,0 +1,22 @@ +--- +title: N (Windows Debugger Glossary) +description: Glossary page - N +Robots: noindex, nofollow +ms.assetid: 43e791bb-7346-4056-acb2-b728648e01f5 +--- + +# N + + +**nonpaged pool** +A portion of system memory that will not be paged to disk. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20N%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/native-debugger-objects-in-natvis.md b/windows-driver-docs-pr/debugger/native-debugger-objects-in-natvis.md new file mode 100644 index 0000000000..5699ca9dc2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/native-debugger-objects-in-natvis.md @@ -0,0 +1,120 @@ +--- +title: Native Debugger Objects in NatVis +description: The dx command displays a C++ expression using the NatVis extension model. For more information about NatVis, see Create custom views of native objects in the debugger. +keywords: [Native Debugger Objects in NatVis"] +ms.author: windowsdriverdev +ms.date: 08/10/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native Debugger Objects in NatVis + +## Overview + +Native debugger objects represent various constructs and behaviors of the debugger environment. Example debugger objects include the following. + +- Session +- Threads / Thread +- Processes / Process +- Stack Frames / Stack Frame +- Local Variables +- Modules / Module +- Utility +- State +- Settings + +You can use the dx command and LINQ to interact with the debugger objects. For more informaton, see [dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md) and [Using LINQ With the debugger objects](using-linq-with-the-debugger-objects.md). + +You can also work with debugger objects using JavaScript. For more information about that see, +[Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md). + +This topic describes how you can create custom NatVis visualizers to display debugger objects. + +## NatVis Development Resources + +Refer to these resources for general information about working with NatVis. + +[Create custom views of native objects](http://msdn.microsoft.com/library/jj620914.aspx) + +[Writing debugger type visualizers for C++ using .natvis files](http://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2) + +[**.nvload**](-nvload--natvis-load-.md) + +[**.nvlist**](-nvlist--natvis-list-.md) + +[**.nvunload**](-nvunload--natvis-unload-.md) + +[**.nvunloadall**](-nvunloadall--natvis-unload-all-.md) + + +## Custom NatVis object example + + +Create a simple C++ application that has an instance of the class **CDog**. + +```ManagedCPlusPlus +class CDog +{ +public: + CDog(){m_age = 8; m_weight = 30;} + long m_age; + long m_weight; +}; + +int main() +{ + CDog MyDog; + printf_s("%d, %d\n", MyDog.m_age, MyDog.m_weight); + return 0; +} +``` + +Create a file named Dog.natvis that contains this XML: + +```XML + + + + {{Age = {m_age} years. Weight = {m_weight} pounds.}} + + +``` + +Copy Dog.natvis to the Visualizers folder in your installation directory for Debugging Tools for Windows. For example: + +C:\\Program Files\\Debugging Tools for Windows (x64)\\Visualizers + +Run your program, and break in at the main function. Take a step so that the variable `MyDog` gets initialized. Display `MyDog` using [**??**](----evaluate-c---expression-.md) and again using **dx**. + +``` +0:000> ??MyDog +class CDog + +0x000 m_age : 0n8 + +0x004 m_weight : 0n30 +0:000> * +0:000> dx -r1 MyDog +..... +MyDog : {Age = 8 years. Weight = 30 pounds.} [Type: CDog] +``` + + +## See also + +[dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md) + +[Using LINQ With the debugger objects](using-linq-with-the-debugger-objects.md) + +[Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md)  + +  +--- +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dx%20%28Display%20Debugger%20Object%20Model%20Expression%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/native-objects-in-javascript-extensions.md b/windows-driver-docs-pr/debugger/native-objects-in-javascript-extensions.md new file mode 100644 index 0000000000..c06727e99a --- /dev/null +++ b/windows-driver-docs-pr/debugger/native-objects-in-javascript-extensions.md @@ -0,0 +1,1077 @@ +--- +title: Native Debugger Objects in JavaScript Extensions +description: Native debugger objects represent various constructs and behaviors of the debugger environment. The objects can be passed into (or acquired in) JavaScript extensions. +ms.assetid: A8E12564-D083-43A7-920E-22C4D627FEE8 +--- + +# Native Debugger Objects in JavaScript Extensions + + +Native debugger objects represent various constructs and behaviors of the debugger environment. The objects can be passed into (or acquired in) JavaScript extensions to manipulate the state of the debugger. + +Example debugger objects include the following. + +- Session +- Threads / Thread +- Processes / Process +- Stack Frames / Stack Frame +- Local Variables +- Modules / Module +- Utility +- State +- Settings + +For example the host.namespace.Debugger.Utility.Control.ExecuteCommand object can be used to send the u command to the debugger with following two lines of JavaScript code. + +``` +var ctl = host.namespace.Debugger.Utility.Control; +var output = ctl.ExecuteCommand("u"); +``` + +This topic describes how to work with common objects and provides reference information on their attributes and behaviors. + +[Extending the Debugger via the Data Model](#extending) +[Extending a Debugger Object in JavaScript](#extending-debugger-object) +[Debugger Objects in JavaScript Extensions](#debugger-objects) +[Host APIs for JavaScript Extensions](#host-apis) +[Data Model Concepts in JavaScript](#data-model) +[Debugger Data Model Design Considerations](#design-considerations) +For general information about working with JavaScript, see [JavaScript Debugger Scripting](javascript-debugger-scripting.md). For JavaScript examples that use the debugger objects, see [JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md). For information about working with the settings objects, see [**.settings (Set Debug Settings)**](-settings--set-debug-settings-.md). + +To explore the objects available in a debugger session, use the [**dx (Display NatVis Expression)**](dx--display-visualizer-variables-.md) command. For example, you can display some of the top level debugger objects with this dx command. + +``` +0: kd> dx -r2 Debugger +Debugger + Sessions : [object Object] + [0x0] : Remote KD: KdSrv:Server=@{},Trans=@{NET:Port=50000,Key=1.2.3.4,Target} + Settings + Debug + Display + EngineInitialization + Extensions + Input + Sources + Symbols + AutoSaveSettings : false + State + DebuggerVariables + PseudoRegisters + Scripts + UserVariables + Utility + Collections + Control + Objects +``` + +All of the items listed above are clickable DML and can be recursed further down to view the debugger object structure. + +## Extending the Debugger via the Data Model + + +The debugger data model allows for the creation of an interface to information about applications and drivers in Windows that has the following attributes. + +- Is discoverable and organized- a logically structured name space can be queried using the dx command. +- Can be queried using LINQ- This allows for extraction and sorting of data using a standard query language. +- Can be logically and consistently extended - Extensible using techniques described in this topic with debugger scripting providers such as Natvis and JavaScript. + +## Extending a Debugger Object in JavaScript + + +In addition to being able to create a visualizer in JavaScript, script extensions can also modify the core concepts of the debugger - sessions, processes, threads, stacks, stack frames, local variables - and even publish themselves as extension points that other extensions can consume. + +This section describes how to extend a core concept within the debugger. Extensions which are built to be shared should conform to the guidelines presented in [Debugger Data Model Design Considerations](#design-considerations). + +**Registering an Extension** + +A script can register the fact that it provides an extension through an entry in the array returned from the initializeScript method. + +``` +function initializeScript() +{ + return [new host.namedModelParent(comProcessExtension, "Debugger.Models.Process")]; +} +``` + +The presence of a host.namedModelParent object within the returned array indicates to the debugger that a given prototype object or ES6 class (comProcessExtension in this case) is going to be a parent data model to the model which is registered under the name Debugger.Models.Process. + +**Debugger Object Extension Points** + +The following debugger extension points are integral to the debugger and available to be used by script providers such as JavaScript. + +| | | +|--------------------------------|----------------------------------------------------------------------------------------------| +| Debugger.Models.Sessions | The list of sessions (targets) that the debugger is attached to | +| Debugger.Models.Session | An individual session (target) that the debugger is attached to (live user mode, KD, etc...) | +| Debugger.Models.Processes | The list of processes within a session | +| Debugger.Models.Threads | The list of threads within a process | +| Debugger.Models.Thread | An individual thread within a process (regardless of whether user or kernel mode) | +| Debugger.Models.Stack | The stack of a thread | +| Debugger.Models.StackFrames | The collection of frames which make up a stack | +| Debugger.Models.StackFrame | An individual stack frame within a stack | +| Debugger.Models.LocalVariables | The local variables within a stack frame | +| Debugger.Models.Parameters | The parameters for a call within a stack frame | +| Debugger.Models.Module | An individual module within the address space of a process | + +  + +**Addtional Data Model Objects** + +In addition, there are some additional data model objects that are defined by the core data model. + +| | | +|---------------------------------------------|---------------------------------------------------------------| +| DataModel.Models.Intrinsic | An intrinsic value (ordinals, floats, etc...) | +| DataModel.Models.String | A string | +| DataModel.Models.Array | A native array | +| DataModel.Models.Guid | A GUID | +| DataModel.Models.Error | An error object | +| DataModel.Models.Concepts.Iterable | Applied to every object which is iterable | +| DataModel.Models.Concepts.StringDisplayable | Applied to every object which has a display string conversion | + +  + +**Example COM Debugger Object Extension Overview** + +Let's consider an example. Imagine that you want to create a debugger extension to display information specific to COM, such as the global interface table (GIT). + +In the past, there might be an existing debugger extension with a number of commands which provide a means to access things about COM. One command might display process centric information (the global interface table for instance). Another command might provide thread centric information such as what apartment code is executing within. You might need to know about and load a second debugger extension to explore other aspects of COM. + +Instead of having a set of hard to discover commands, a JavaScript extension can modify the debugger's concept of what a process and a thread is, to add this information in a way that's natural, explorable, and composable with other debugger extensions. + +**User or Kernel Mode Debugger Object Extension** + +The debugger and the debugger objects have different behavior in user and kernel mode. When you create your debugger model objects you need to decide which environments you will be working in. Because we will be working with COM in user mode, we will create and test this com extension in user mode. In other situations, you may be able to create a debugger JavaScript that will work in both user and kernel mode debugging. + +**Creating a Sub-Namespace** + +Going back to our example, we can define a prototype or ES6 class, *comProcessExtension* which contains the set of things we want to add to a process object. + +**Important**   The intent with the sub-namespace is to create a logically structured and naturally explorable paradigm. For example, avoid dumping unrelated items into the same sub-namespace. Carefully review the information discussed in [Debugger Data Model Design Considerations](#design-considerations) before creating a sub-namespace. + +  + +In this code snippet, we create add a sub-namespace called 'COM' on to the existing process debugger object. + +``` +var comProcessExtension = +{ + // + // Add a sub-namespace called 'COM' on process. + // + get COM() + { + // + // What is 'this' below...? It's the debugger's process object. Yes -- this means that there is a cross-language + // object hierarchy here. A C++ object implemented in the debugger has a parent model (prototype) which is + // implemented in JavaScript. + // + return new comNamespace(this); + } +} +``` + +**Namespace Implementation** + +Next, create the object which implements the sub-namespace COM on a process. + +**Important**   +There can be multiple processes (whether attached to such in user mode or under KD). This extension cannot assume that the present state of the debugger is the what the user intended. Someone can capture <someProcess>.COM in a variable and modify it, which can lead to presenting information from the wrong process context. The solution is to add code in the extension so that each instantiation will keep track of what process it is attached to. For this code sample, this information is passed via the 'this' pointer of the property. + +`this.__process = process;` + +  + +``` +class comNamespace +{ + constructor(process) + { + // + // This is an entirely JavaScript object. Each instantiation of a comNamespace will keep track + // of what process it is attached to (passed via the ''this'' pointer of the property getter + // we authored above. + // + this.__process = process; + } + + get GlobalObjects() + { + return new globalObjects(this.__process); + } +} +``` + +**Implementation logic for the COM global interface table** + +To separate this out the implementation logic for the COM global interface table more clearly, we'll define one ES6 class, *gipTable* which abstracts away the COM GIP table and another, *globalObjects*, which is what will get returned from the GlobalObjects() getter defined in the Namespace Implementation code snip shown above. All of these details can be hidden inside the closure of initializeScript to avoid publishing any of these internal details out into the debugger namespace. + +``` +// gipTable: +// +// Internal class which abstracts away the GIP Table. It iterates objects of the form +// {entry : GIPEntry, cookie : GIT cookie} +// +class gipTable +{ + constructor(gipProcess) + { + // + // Windows 8 through certain builds of Windows 10, it's in CGIPTable::_palloc. In certain builds + // of Windows 10 and later, this has been moved to GIPEntry::_palloc. We need to check which. + // + var gipAllocator = undefined; + try + { + gipAllocator = host.getModuleSymbol("combase.dll", "CGIPTable::_palloc", "CPageAllocator", gipProcess)._pgalloc; + } + catch(err) + { + } + + if (gipAllocator == undefined) + { + gipAllocator = host.getModuleSymbol("combase.dll", "GIPEntry::_palloc", "CPageAllocator", gipProcess)._pgalloc; + } + + this.__data = { + process : gipProcess, + allocator : gipAllocator, + pageList : gipAllocator._pPageListStart, + pageCount : gipAllocator._cPages, + entriesPerPage : gipAllocator._cEntriesPerPage, + bytesPerEntry : gipAllocator._cbPerEntry, + PAGESHIFT : 16, + PAGEMASK : 0x0000FFFF, + SEQNOMASK : 0xFF00 + }; + } + + *[Symbol.iterator]() + { + for (var pageNum = 0; pageNum < this.__data.pageCount; ++pageNum) + { + var page = this.__data.pageList[pageNum]; + for (var entryNum = 0; entryNum < this.__data.entriesPerPage; ++entryNum) + { + var entryAddress = page.address.add(this.__data.bytesPerEntry * entryNum); + var gipEntry = host.createPointerObject(entryAddress, "combase.dll", "GIPEntry *", this.__data.process); + if (gipEntry.cUsage != -1 && gipEntry.dwType != 0) + { + yield {entry : gipEntry, cookie : (gipEntry.dwSeqNo | (pageNum << this.__data.PAGESHIFT) | entryNum)}; + } + } + } + } + + entryFromCookie(cookie) + { + var sequenceNo = (cookie & this.__data.SEQNOMASK); + cookie = cookie & ~sequenceNo; + var pageNum = (cookie >> this.__data.PAGESHIFT); + if (pageNum < this.__data.pageCount) + { + var page = this.__data.pageList[pageNum]; + var entryNum = (cookie & this.__data.PAGEMASK); + if (entryNum < this.__data.entriesPerPage) + { + var entryAddress = page.address.add(this.__data.bytesPerEntry * entryNum); + var gipEntry = host.createPointerObject(entryAddress, "combase.dll", "GIPEntry *", this.__data.process); + if (gipEntry.cUsage != -1 && gipEntry.dwType != 0 && gipEntry.dwSeqNo == sequenceNo) + { + return {entry : gipEntry, cookie : (gipEntry.dwSeqNo | (pageNum << this.__data.PAGESHIFT) | entryNum)}; + } + } + } + + // + // If this exception flows back to C/C++, it will be a failed HRESULT (according to the type of error -- here E_BOUNDS) + // with the message being encapsulated by an error object. + // + throw new RangeError("Unable to find specified value"); + } +} + + + + + +// globalObjects: +// +// The class which presents how we want the GIP table to look to the data model. It iterates the actual objects +// in the GIP table indexed by their cookie. +// +class globalObjects +{ + constructor(process) + { + this.__gipTable = new gipTable(process); + } + + *[Symbol.iterator]() + { + for (var gipCombo of this.__gipTable) + { + yield new host.indexedValue(gipCombo.entry.pUnk, [gipCombo.cookie]); + } + } + + getDimensionality() + { + return 1; + } + + getValueAt(cookie) + { + return this.__gipTable.entryFromCookie(cookie).entry.pUnk; + } +} +``` + +Lastly, use host.namedModelRegistration to register the new COM functionality. + +``` +function initializeScript() +{ + return [new host.namedModelParent(comProcessExtension, "Debugger.Models.Process"), + new host.namedModelRegistration(comNamespace, "Debugger.Models.ComProcess")]; +} +``` + +Save the code to GipTableAbstractor.js using an application such as notepad. + +Here is the process information available in user mode before loading this extension. + +``` +0:000:x86> dx @$curprocess +@$curprocess : DataBinding.exe + Name : DataBinding.exe + Id : 0x1b9c + Threads + Modules +``` + +Load the JavaScript scripting provider and the extension. + +``` +0:000:x86> !load jsprovider.dll +0:000:x86> .scriptload C:\JSExtensions\GipTableAbstractor.js +JavaScript script successfully loaded from 'C:\JSExtensions\GipTableAbstractor.js' +``` + +Then use the dx command to display information about the process using the predefined @$curprocess. + +``` +0:000:x86> dx @$curprocess +@$curprocess : DataBinding.exe + Name : DataBinding.exe + Id : 0x1b9c + Threads + Modules + COM : [object Object] +``` + +``` +0:000:x86> dx @$curprocess.COM +@$curprocess.COM : [object Object] + GlobalObjects : [object Object] +0:000:x86> dx @$curprocess.COM.GlobalObjects +@$curprocess.COM.GlobalObjects : [object Object] + [0x100] : 0x12f4fb0 [Type: IUnknown *] + [0x201] : 0x37cfc50 [Type: IUnknown *] + [0x302] : 0x37ea910 [Type: IUnknown *] + [0x403] : 0x37fcfe0 [Type: IUnknown *] + [0x504] : 0x12fe1d0 [Type: IUnknown *] + [0x605] : 0x59f04e8 [Type: IUnknown *] + [0x706] : 0x59f0eb8 [Type: IUnknown *] + [0x807] : 0x59f5550 [Type: IUnknown *] + [0x908] : 0x12fe340 [Type: IUnknown *] + [0xa09] : 0x5afcb58 [Type: IUnknown *] +``` + +This table is also programmatically accessible via GIT cookie. + +``` +0:000:x86> dx @$curprocess.COM.GlobalObjects[0xa09] +@$curprocess.COM.GlobalObjects[0xa09] : 0x5afcb58 [Type: IUnknown *] + [+0x00c] __abi_reference_count [Type: __abi_FTMWeakRefData] + [+0x014] __capture [Type: Platform::Details::__abi_CapturePtr] +``` + +**Extending Debugger Object Concepts with LINQ** + +In addition to being able to extend objects like process and thread, JavaScript can extend concepts associated with the data model as well. For example, it is possible to add a new LINQ method to every iterable. Consider an example extension, "DuplicateDataModel" which duplicates every entry in an iterable N times. The following code shows how this could be implemented. + +``` +function initializeScript() +{ + var newLinqMethod = + { + Duplicate : function *(n) + { + for (var val of this) + { + for (var i = 0; i < n; ++i) + { + yield val; + } + }; + } + }; + + return [new host.namedModelParent(newLinqMethod, "DataModel.Models.Concepts.Iterable")]; +} +``` + +Save the code to DuplicateDataModel.js using an application such as notepad. + +Load the JavaScript scripting provider if necessary and then load the DuplicateDataModel.js extension. + +``` +0:000:x86> !load jsprovider.dll +0:000:x86> .scriptload C:\JSExtensions\DuplicateDataModel.js +JavaScript script successfully loaded from 'C:\JSExtensions\DuplicateDataModel.js' +``` + +Use the dx command to test the new Duplicate function. + +``` +0: kd> dx -r1 Debugger.Sessions.First().Processes.First().Threads.Duplicate(2),d +Debugger.Sessions.First().Processes.First().Threads.Duplicate(2),d : [object Generator] + [0] : nt!DbgBreakPointWithStatus (fffff800`9696ca60) + [1] : nt!DbgBreakPointWithStatus (fffff800`9696ca60) + [2] : intelppm!MWaitIdle+0x18 (fffff805`0e351348) + [3] : intelppm!MWaitIdle+0x18 (fffff805`0e351348) +… +``` + +## Debugger Objects in JavaScript Extensions + + +**Passing Native Objects** + +Debugger objects can be passed into or acquired in JavaScript extensions in a variety of ways. + +- They can be passed to JavaScript functions or methods +- They can be the instance object for a JavaScript prototype (as a visualizer, for instance) +- They can be returned from host methods designed to create native debugger objects +- They can be returned from host methods designed to create debugger native objects + +Debugger objects that are passed to a JavaScript extension have a set of functionality that is described in this section. + +- Property Access +- Projected Names +- Special Types Pertaining to Native Debugger Objects +- Additional Attributes + +**Property Access** + +While there are some properties on objects which are placed there by the JavaScript provider itself, the majority of properties on a native object which enters JavaScript are provided by the data model. This means that for a property access --- object.propertyName or object\[propertyName\], the following will occur. + +- If *propertyName* is the name of a property projected onto the object by the JavaScript provider itself, it will resolve to this first; otherwise +- If *propertyName* is the name of a key projected onto the object by the data model (another Visualizer), it will resolve to this name second; otherwise +- If *propertyName* is the name of a field of the native object, it will resolve to this name third; otherwise +- If object is a pointer, the pointer will be dereferenced, and the cycle above will continue (a projected property of the dereferenced object followed by a key followed by a native field) + +The normal means of property access in JavaScript -- object.propertyName and object\[propertyName\] -- will access the underlying native fields of an object, much as the 'dx' command would within the debugger. + +**Projected Names** + +The following properties (and methods) are projected onto native objects which enter JavaScript. + +| Method | Signature | Description | +|--------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| hostContext | Property | Returns an object which represents the context the object is within (the address space, debug target, etc...) | +| targetLocation | Property | Returns an object which is an abstraction of where the object is within an address space (virtual address, register, sub-register, etc...) | +| targetSize | Property | Returns the size of the object (effectively: sizeof(<TYPE OF OBJECT>) | +| addParentModel | .addParentModel(object) | Adds a new parent model (akin to a JavaScript prototype but on the data mdoel side) to the object | +| removeParentModel | .removeParentModel(object) | Removes a given parent model from the object | +| runtimeTypedObject | Property | Performs analysis on the object and tries to convert it to the runtime (most derived) type | + +  + +If the object is a pointer, the following properties (and methods) are projected onto the pointer which enters JavaScript: + +| Property Name | Signature | Description | +|-------------------------------------------------------------------------------------------------|----------------|--------------------------------------------------------------------------------| +| add | .add(value) | Performs pointer math addition between the pointer and the specified value | +| address Property Returns the address of the pointer as a 64-bit ordinal object (a library type) | Property | Returns the address of the pointer as a 64-bit ordinal object (a library type) | +| dereference | .dereference() | Dereferences the pointer and returns the underlying object | +| isNull | Property | Returns whether or not the pointer value is nullptr (0) | + +  + +**Special Types Pertaining to Native Debugger Objects** + +**Location Objects** + +The location object which is returned from the targetLocation property of a native object contains the following properties (and methods). + +| Property Name | Signature | Description | +|---------------|------------------|------------------------------------------------------| +| add | .add(value) | Adds an absolute byte offset to the location. | +| subtract | .subtract(value) | Subtracts an absolute byte offset from the location. | + +  + +**Additional Attributes** + +**Iterability** + +Any object which is understood as iterable by the data model (it is a native array or it has a visualizer (NatVis or otherwise) which makes it iterable) will have an iterator function (indexed via the ES6 standard Symbol.iterator) placed upon it. This means that you can iterate a native object in JavaScript as follows. + +``` +function iterateNative(nativeObject) +{ + for (var val of nativeObject) + { + // + // val will contain each element iterated from the native object. This would be each element of an array, + // each element of an STL structure which is made iterable through NatVis, each element of a data structure + // which has a JavaScript iterator accessible via [Symbol.iterator], or each element of something + // which is made iterable via support of IIterableConcept in C/C++. + // + } +} +``` + +**Indexability** + +Objects which are understood as indexable in one dimension via ordinals (e.g.: native arrays) will be indexable in JavaScript via the standard property access operator -- object\[index\]. If an object is indexable by name or is indexable in more than one dimension, the getValueAt and setValueAt methods will be projected onto the object so that JavaScript code can utilize the indexer. + +``` +function indexNative(nativeArray) +{ + var first = nativeArray[0]; +} +``` + +**String Conversion** + +Any native object which has a display string conversion via support of IStringDisplayableConcept or a NatVis DisplayString element will have that string conversion accessible via the standard JavaScript toString method. + +``` +function stringifyNative(nativeObject) +{ + var myString = nativeObject.toString(); +} +``` + +## Creating Native Debugger Objects + + +As mentioned, a JavaScript script can get access to native objects by having them passed into JavaScript in one of several ways or it can create them through calls to the host library. Use the following functions to create native debugger objects. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodSignatureDescription

host.getModuleSymbol

getModuleSymbol(moduleName, symbolName, [contextInheritor])

+

getModuleSymbol(moduleName, symbolName, [typeName], [contextInheritor])

Returns an object for a global symbol within a particular module. The module name and symbol name are strings.

+

If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context.

+

If the optional typeName argument is supplied, the symbol will be assumed to be of the passed type and the type indicated in symbol(s) will be ignored. Note that any caller which expects to operate on public symbols for a module should always supply an explicit type name.

host.createPointerObject

createPointerObject(address, moduleName, typeName, [contextInheritor])

Creates a pointer object at the specified address or location. The module name and type name are strings.

+

If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context.

host.createTypedObject

createTypedObject(location, moduleName, typeName, [contextInheritor])

Creates a object which represents a native typed object within the address space of a debug target at the specified location. The module name and type name are strings.

+

If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context.

+ +  + +## Host APIs for JavaScript Extensions + + +The JavaScript provider inserts an object called host into the global namespace of every script which it loads. This object provides access to critical functionality for the script as well as access to the namespace of the debugger. It is set up in two phases. + +- **Phase 1**: Before any script executes, the host object only contains the minimal set of functionality necessary for a script to initialize itself and register its extensibility points (both as producer and consumer). The root and initialization code is not intended to manipulate the state of a debug target or perform complex operations and, as such, the host is not fully populated until after the initializeScript method returns. + +- **Phase 2**: After initializeScript returns, the host object is populated with everything necessary to manipulate the state of debug targets. + +**Host Object Level** + +A few key pieces of functionality are directly under the host object. The remainder are sub-namespaced. Namespaces include the following. + +| Namespace | Description | +|-------------|--------------------------------------------------------------------------| +| diagnostics | Functionality to assist in the diagnosis and debugging of script code | +| memory | Functionality to enable memory reading and writing within a debug target | + +  + +**Root Level** + +Directly within the host object, the following properties, methods, and constructors can be found. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSignaturePhase PresentDescription
createPointerObject

createPointerObject(address, moduleName, typeName, [contextInheritor])

2Creates a pointer object at the specified address or location. The module name and type name are strings. The optional contextInheritor argument works as with getModuleSymbol.
createTypedObject

createTypedObject(location, moduleName, typeName, [contextInheritor])

2Creates a object which represents a native typed object within the address space of a debug target at the specified location. The module name and type name are strings. The optional contextInheritor argument works as with getModuleSymbol.
currentProcess

Property

2Returns the object representing the current process of the debugger
currentSession

Property

2Returns the object representing the current session of the debugger (which target, dump, etc...) is being debugged
currentThread

Property

2Returns the object representing the current thread of the debugger
evaluateExpression

evaluateExpression(expression, [contextInheritor])

2This calls into the debug host to evaluate an expression using the language of the debug target only. If the optional contextInheritor argument is supplied, the expression will be evaluated in the context (e.g.: address space and debug target) of the argument; otherwise, it will be evaluated in the current context of the debugger
evaluateExpressionInContext

evaluateExpressionInContext(context, expression)

2This calls into the debug host to evaluate an expression using the language of the debug target only. The context argument indicates the implicit this pointer to utilize for the evaluation. The expression will be evaluated in the context (e.g.: address space and debug target) indicated by the context argument.
getModuleSymbol

getModuleSymbol(moduleName, symbolName, [contextInheritor])

2Returns an object for a global symbol within a particular module. The module name and symbol name are strings. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off script should always supply an explicit context
getNamedModel

getNamedModel(modelName)

2Returns the data model which was registered against a given name. Note that it is perfectly legal to call this against a name which is not yet registered. Doing so will create a stub for that name and manipulations of the stub will be made to the actual object upon registration
indexedValue

new indexedValue(value, indicies)

2A constructor for an object which can be returned from a JavaScript iterator in order to assign a default set of indicies to the iterated value. The set of indicies must be expressed as a JavaScript array.
Int64

new Int64(value, [highValue])

1This constructs a library Int64 type. The single argument version will take any value which can pack into an Int64 (without conversion) and place it into such. If an optional second argument is supplied, a conversion of the first argument is packed into the lower 32-bits and a conversion of the second argument is packed into the upper 32 bits.
namedModelParent

new namedModelParent(object, name)

1A constructor for an object intended to be placed in the array returned from initializeScript, this represents using a JavaScript prototype or ES6 class as a data model parent extension of a data model with the given name
namedModelRegistration

new namedModelRegistration(object, name)

1A constructor for an object intended to be placed in the array returned from initializeScript, this represents the registration of a JavaScript prototype or ES6 class as a data model via a known name so that other extensions can find and extend
namespace

Property

2Gives direct access to the root namespace of the debugger. One could, for example, access the process list of the first debug target via host.namespace.Debugger.Sessions.First().Processes using this property
registerNamedModel

registerNamedModel(object, modelName)

2This registers a JavaScript prototype or ES6 class as a data model under the given name. Such a registration allows the prototype or class to be located and extended by other scripts or other debugger extensions. Note that a script should prefer to return a namedModelRegistration object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up.
registerExtensionForTypeSignature

registerExtensionForTypeSignature(object, typeSignature)

2This registers a JavaScript prototype or ES6 class as an extension data model for a native type as given by the supplied type signature. Note that a script should prefer to return a typeSignatureExtension object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up.
registerPrototypeForTypeSignature

registerPrototypeForTypeSignature(object, typeSignature)

2This registers a JavaScript prototype or ES6 class as the canonical data model (e.g.: visualizer) for a native type as given by the supplied type signature. Note that a script should prefer to return a typeSignatureExtension object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an uninitializeScriptmethod in order to clean up.
parseInt64

parseInt64(string, [radix])

1This method acts similarly to the standard JavaScript parseInt method except that it returns a library Int64 type instead. If a radix is supplied, the parse will occur in either base 2, 8, 10, or 16 as indicated.
typeSignatureExtension

new typeSignatureExtension(object, typeSignature, [moduleName], [minVersion], [maxVersion])

1A constructor for an object intended to be placed in the array returned from initializeScript, this represents an extension of a native type described via a type signature by a JavaScript prototype or ES6 class. Such a registration "adds fields" to the debugger's visualization of any type which matches the signature rather than taking it over entirely. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings.
typeSignatureRegistration

new typeSignatureRegistration(object, typeSignature, [moduleName], [minVersion], [maxVersion])

1A constructor for an object intended to be placed in the array returned from initializeScript, this represents a canonical registration of a JavaScript prototype or ES6 class against a native type signature. Such a registration "takes over" the debugger's visualization of any type which matches the signature rather than merely than extending it. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings.
unregisterNamedModel

unregisterNamedModel(modelName)

2This unregisters a data model from lookup by the given name undoing any operation performed by registerNamedModel
unregisterExtensionForTypeSignature

unregisterExtensionForTypeSignature(object, typeSignature, [moduleName], [minVersion], [maxVersion])

2This unregisters a JavaScript prototype or ES6 class from being an extension data model for a native type as given by the supplied type signature. It is the logical undo of registerExtensionForTypeSignature. Note that a script should prefer to return a typeSignatureExtension object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings.
unregisterPrototypeForTypeSignature

unregisterPrototypeForTypeSignature(object, typeSignature, [moduleName], [minVersion], [maxVersion])

2This unregisters a JavaScript prototype or ES6 class from being the canonical data model (e.g.: visualizer) for a native type as given by the supplied type signature. It is the logical undo of registerPrototypeForTypeSignature. Note that a script should prefer to return a typeSignatureRegistration object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an uninitializeScript method in order to clean up. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings.
+ +  + +**Diagnostics Functionality** + +The diagnostics sub-namespace of the host object contains the following. + +| Name | Signature | Phase Present | Description | +|----------|---------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| debugLog | debugLog(object...) | 1 | This provides printf style debugging to a script extension. At present, output from debugLog is routed to the output console of the debugger. At a later point in time, there are plans to provide flexibility on routing this output. NOTE: This should not be used as a means of printing user output to console. It may not be routed there in the future. | + +  + +**Memory Functionality** + +The memory sub-namespace of the host object contains the following. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSignaturePhase PresentDescription
readMemoryValues

readMemoryValues(location, numElements, [elementSize], [isSigned], [contextInheritor])

2This reads a raw array of values from the address space of the debug target and places a typed array on top of the view of this memory. The supplied location can be an address (a 64-bit value), a location object, or a native pointer. The size of the array is indicated by the numElements argument. The size (and type) of each element of the array is given by the optional elementSize and isSigned arguments. If no such arguments are supplied, the default is byte (unsigned / 1 byte). If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. Note that using this method on 8, 16, and 32-bit values results in a fast typed view being placed over the read memory. Using this method on 64-bit values results in an array of 64-bit library types being constructed which is significantly more expensive!
readString

readString(location, [contextInheritor])

+

readString(location, [length], [contextInheritor])

2This reads a narrow (current code page) string from the address space of a debug target, converts it to UTF-16, and returns the result as a JavaScript string. It may throw an exception if the memory could not be read. The supplied location can be an address (a 64-bit value), a location object, or a native char*. If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. If the optional length argument is supplied, the read string will be of the specified length.
readWideString

readWideString(location, [contextInheritor])

+

readWideString(location, [length], [contextInheritor])

2This reads a wide(UTF-16) string from the address space of a debug target and returns the result as a JavaScript string. It may throw an exception if the memory could not be read. The supplied location can be an address (a 64-bit value), a location object, or a native wchar_t*. If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. If the optional length argument is supplied, the read string will be of the specified length.
+ +  + +## Data Model Concepts in JavaScript + + +**Data Model Mapping** + +The following data model concepts map to JavaScript. + +| Concept | Native Interface | JavaScript Equivalent | +|-------------------------|------------------------------|----------------------------------------------------------------------| +| String Conversion | IStringDisplayableConcept | standard: toString(...){...} | +| Iterability | IIterableConcept | standard: \[Symbol.iterator\](){...} | +| Indexability | IIndexableConcept | protocol: getDimensionality(...) / getValueAt(...) / setValueAt(...) | +| Runtime Type Conversion | IPreferredRuntimeTypeConcept | protocol: getPreferredRuntimeTypedObject(...) | + +  + +**String Conversion** + +The string conversion concept (IStringDisplayableConcept) directly translates to the standard JavaScript **toString** method. As all JavaScript objects have a string conversion (provided by Object.prototype if not provided elsewhere), every JavaScript object returned to the data model can be converted to a display string. Overriding the string conversion simply requires implementing your own toString. + +``` +class myObject +{ + // + // This method will be called whenever any native code calls IStringDisplayableConcept::ToDisplayString(...) + // + toString() + { + return "This is my own string conversion!"; + } +} +``` + +**Iterability** + +The data model's concept of whether an object is iterable or not maps directly to the ES6 protocol of whether an object is iterable. Any object which has a \[Symbol.iterator\] method is considered iterable. Implementation of such will make the object iterable. + +An object which is only iterable can have an implementation such as follows. + +``` +class myObject +{ + // + // This method will be called whenever any native code calls IIterableConcept::GetIterator + // + *[Symbol.iterator]() + { + yield "First Value"; + yield "Second Value"; + yield "Third Value"; + } +} +``` + +Special consideration must be given for objects which are both iterable and indexable as the objects returned from the iterator must include the index as well as the value via a special return type. + +**Iterable and Indexable** + +An object which is iterable and indexable requires a special return value from the iterator. Instead of yielding the values, the iterator yields instances of indexedValue. The indicies are passed as an array in the second argument to the indexedValue constructor. They can be multi-dimensional but must match the dimensionality returned in the indexer protocol. + +This code shows an example implementaion. + +``` +class myObject +{ + // + // This method will be called whenever any native code calls IIterableConcept::GetIterator + // + *[Symbol.iterator]() + { + // + // Consider this a map which mapped 42->"First Value", 99->"Second Value", and 107->"Third Value" + // + yield new host.indexedValue("First Value", [42]); + yield new host.indexedValue("Second Value", [99]); + yield new host.indexedValue("Third Value", [107]); + } +} +``` + +**Indexability** + +Unlike JavaScript, the data model makes a very explicit differentiation between property access and indexing. Any JavaScript object which wishes to present itself as indexable in the data model must implement a protocol consisting of a getDimensionality method which returns the dimensionality of the indexer and an optional pair of getValueAt and setValueAt methods which perform reads and writes of the object at supplied indicies. It is acceptable to omit either the getValueAt or setValueAt methods if the object is read-only or write-only + +``` +class myObject +{ + // + // This method will be called whenever any native code calls IIndexableConcept::GetDimensionality or IIterableConcept::GetDefaultIndexDimensionality + // + getDimensionality() + { + // + // Pretend we are a two dimensional array. + // + return 2; + } + + // + // This method will be called whenever any native code calls IIndexableConcept::GetAt + // + getValueAt(row, column) + { + return this.__values[row * this.__columnCount + column]; + } + + // + // This method will be called whenever any native code calls IIndexableConcept::SetAt + // + setValueAt(value, row, column) + { + this.__values[row * this.__columnCount + column] = value; + } +} +``` + +**Runtime Type Conversion** + +This is only relevant for JavaScript prototypes/classes which are registered against type system (native) types. The debugger is often capable of performing analysis (e.g. Run-Time Type Information (RTTI) / v-table analysis) to determine the true runtime type of an object from a static type expressed in code. A data model registered against a native type can override this behavior via an implementation of the IPreferredRuntimeTypeConcept. Likewise, a JavaScript class or prototype registered against a native object can provide its own implementation via implementation of a protocol consisting of the getPreferredRuntimeTypedObject method. + +Note that while this method can technically return anything, it is considered bad form for it to return something which isn't really the runtime type or a derived type. Such can result in significant confusion for users of the debugger. Overriding this method can, however, be valuable for things such as C-style header+object styles of implementation, etc... + +``` +class myNativeModel +{ + // + // This method will be called whenever the data model calls IPreferredRuntimeTypeConcept::CastToPreferredRuntimeType + // + getPreferredRuntimeTypedObject() + { + var loc = this.targetLocation; + + // + // Perform analysis... + // + var runtimeLoc = loc.Add(runtimeObjectOffset); + + return host.createTypedObject(runtimeLoc, runtimeModule, runtimeTypeName); + } +} +``` + +## Debugger Data Model Design Considerations + + +**Design Principles** + +Consider the following principles to make your debugger extensions present information that is discoverable, queryable, and scriptable. + +- Information is close to where it is needed. For example, information on a registry key should be displayed as part of a local variable that contains a registry key handle. +- Information is structured. For example, information about a registry key is presented in separate fields such as key type, key ACL, key name, and value. This means that the individual fields can be accessed without parsing text. +- Information is consistent. Information about registry key handles is presented in as similar a way as possible to information about file handles. + +Avoid these approaches that do not support these principles. + +- Do not structure your items into a single flat "Kitchen sink". An organized hierarchy allows users to browse for the information they are looking for without prior knowledge of what they are looking for and supports discoverability. +- Do not convert a classic dbgeng extension by simply moving it to the model while still outputting screens of raw text. This is not composable with other extensions and cannot be queried with LINQ expressions. Instead break the data into separate, queryable fields. + +**Naming Guidelines** + +- Capitalization of fields should be PascalCase. An exception could be considered for names that are widely known in another casing, such as jQuery. +- Avoid using special characters that would not normally be used in a C++ identifier. For example, avoid using names such as "Total Length" (that contains a space), or "\[size\]" (that contains square brackets). This convention allows for easier consumption from scripting languages where these characters are not allowed as part of identifiers, and also allows easier consumption from the command window. + +**Organization and Hierarchy Guidelines** + +- Do not extend the top level of the debugger namespace. Instead, you should extend an existing node in the debugger so that the information is displayed where it is most relevant. +- Do not duplicate concepts. If you are creating a data model extension that lists additional information about a concept that already exists in the debugger, extend the existing information rather than trying to replace it with new information. In other words, an extension that displays details about a module should extend the existing *Module* object rather than creating a new list of modules. +- Free floating utility commands must be part of the *Debugger.Utility* namespace. They should also be sub-namespaced appropriately (e.g. *Debugger.Utility.Collections.FromListEntry*) + +**Backwards Compatibility and Breaking Changes** + +A script that is published should not break compatibility with other scripts that depend on it. For example, if a function is published to the model, it should remain in the same location and with the same parameters, whenever possible. + +**No Use of Outside Resources** + +- Extensions must not spawn external processes. External processes can interfere with the behavior of the debugger, and will misbehave in various remote debugger scenarios (e.g. dbgsrv remotes, ntsd remotes, and "ntsd -d remotes") +- Extensions must not display any user interface. Displaying user interface elements will behave incorrectly on remote debugging scenarios, and can break console debugging scenarios. +- Extensions must not manipulate the debugger engine or debugger UI through undocumented methods. This causes compatibility problems and will behave incorrectly on debugger clients with different UI. +- Extensions must access target information only through the documented debugger APIs. Trying to access information about a target through win32 APIs will fail for many remote scenarios, and even some local debugging scenarios across security boundaries. + +**No Use of Dbgeng Specific Features** + +Scripts that are intended to be used as extensions must not rely on dbgeng-specific features whenever possible (such as executing "classic" debugger extensions). Scripts should be usable on top of any debugger that hosts the data model. + +## Testing Debugger Extensions + + +Extensions are expected to work in a wide range of scenarios. While some extensions may be specific to a scenario (such as a kernel debugging scenario), most extensions should be expected to work in all scenarios, or have metadata indicating the supported scenarios. + +Kernel Mode + +- Live kernel debugging +- Kernel dump debugging + +User Mode + +- Live user mode debugging +- User mode dump debugging + +In addition, consider these debugger usage scenarios + +- Multi-process debugging +- Multi-session debugging (e.g. dump + live user within a single session) + +**Remote Debugger Usage** + +Test for proper operation with the remote debugger usage scenarios. + +- dbgsrv remotes +- ntsd remotes +- ntsd -d remotes + +For more information, see [Debugging Using CDB and NTSD](debugging-using-cdb-and-ntsd.md) and [**Activating a Process Server**](activating-a-process-server.md). + +**Regression testing** + +Investigate the use of test automation that can verify the functionality of your extensions, as new versions of the debugger are released. + +## Related topics + + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +[JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Native%20Debugger%20Objects%20in%20JavaScript%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/ndis-debugging.md b/windows-driver-docs-pr/debugger/ndis-debugging.md new file mode 100644 index 0000000000..3cd200c9ec --- /dev/null +++ b/windows-driver-docs-pr/debugger/ndis-debugging.md @@ -0,0 +1,32 @@ +--- +title: NDIS Debugging +description: NDIS Debugging +ms.assetid: 80c72934-bb0d-4299-8ed1-5eeeea668bd4 +keywords: ["NDIS debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS Debugging + + +This section includes: + +[Overview of NDIS Debugging](overview-of-ndis-debugging.md) + +[Preparing for NDIS Debugging](preparing-for-ndis-debugging.md) + +[Enabling NDIS Debug Tracing](enabling-ndis-debug-tracing.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20NDIS%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ndis-extensions--ndiskd-dll-.md b/windows-driver-docs-pr/debugger/ndis-extensions--ndiskd-dll-.md new file mode 100644 index 0000000000..d735ead79a --- /dev/null +++ b/windows-driver-docs-pr/debugger/ndis-extensions--ndiskd-dll-.md @@ -0,0 +1,197 @@ +--- +title: NDIS Extensions (Ndiskd.dll) +description: NDIS Extensions (Ndiskd.dll) +ms.assetid: bf4a7cc2-0116-4d6d-8a6f-2e9dc77d3631 +keywords: ["NDIS extensions (ndiskd.dll)", "ndiskd.dll (NDIS extensions)", "extensions, NDIS"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS Extensions (Ndiskd.dll) + + +## + + +This section describes commands available in !ndiskd, a debugger extension that is useful for debugging NDIS (Network Device Interface Specification) drivers. These commands enable network driver developers to see a bigger picture of the Windows networking stack and how their drivers interact with it. With !ndiskd, you can see the state of all network adapters ([**!ndiskd.netadapter**](-ndiskd-netadapter.md)), a visual diagram of the computer's network stack ([**!ndiskd.netreport**](-ndiskd-netreport.md)), a log of traffic on the network adapters([**!ndiskd.nbllog**](-ndiskd-nbllog.md)), or a list of all pending OID requests ([**!ndiskd.oid**](-ndiskd-oid.md)). + +The commands can be found in Ndiskd.dll. To load the symbols, enter **.reload /f ndis.sys** in the debugger command window. To confirm the symbols loaded successfully, use the [**!lmi ndis**](-lmi.md) extension and look for the phrase "Symbols loaded successfully" toward the bottom. Your output should look similar to the following example: + +``` +3: kd> !lmi ndis +Loaded Module Info: [ndis] + Module: ndis + Base Address: fffff80e2e150000 + Image Name: ndis.sys + Machine Type: 34404 (X64) + Time Stamp: 57f4c58d Wed Oct 5 02:19:09 2016 + Size: 128000 + CheckSum: 1213f7 +Characteristics: 22 +Debug Data Dirs: Type Size VA Pointer + CODEVIEW 21, 7b1b8, 79fb8 RSDS - GUID: {06A2E58C-996D-4419-81A0-BB293BD63BCA} + Age: 1, Pdb: ndis.pdb + ?? 880, 7b1dc, 79fdc [Data not mapped] + Image Type: MEMORY - Image read successfully from loaded memory. + Symbol Type: PDB - Symbols loaded successfully from image header. + c:\Debuggers\sym\ndis.pdb\06A2E58C996D441981A0BB293BD63BCA1\ndis.pdb + Compiler: Linker - front end [0.0 bld 0] - back end [14.0 bld 23917] + Load Report: private symbols & lines, source indexed + c:\Debuggers\sym\ndis.pdb\06A2E58C996D441981A0BB293BD63BCA1\ndis.pdb +``` + +## !ndiskd Hyperlinks + + +Many of the extension commands in !ndiskd present you with hyperlinks in the results they display in the debugger window. The text for these hyperlinks has been left in the samples provided to illustrate the exact format of what you will see when you run the command on your debugee machine. Some of the examples also refer explicitly to clicking on these links so you can understand typical usage flows, though the examples also provide the alternate command line forms of each command. + +## Common Parameters + + +All !ndiskd commands support the following generic parameters. + + *-verbose* +Shows additional details. + + *-terse* +Suppresses some boilerplate output. + + *-static* +Suppresses some interactive output. + + *-dml 0|1* +Controls whether DML (debugger markup language) output is enabled. + + *-unicode 0|1* +Controls whether Unicode character output is allowed. + + *-indent N* +Uses *N* spaces per level of indent. + + *-force* +Overrides some safety checks on remote data sanity. + + *-tracedata* +Shows verbose trace messages to debug !ndiskd itself. + +## Net Adapter, NDIS Driver, and General Commands + + +The following commands display information about the machine's network adapters, network drivers, and general commands associated with the network stack (such as rcvqueues, opens, filters, OIDs, and RW locks). + +- [**!ndiskd.netadapter**](-ndiskd-netadapter.md) +- [**!ndiskd.minidriver**](-ndiskd-minidriver.md) +- [**!ndiskd.rcvqueue**](-ndiskd-rcvqueue.md) +- [**!ndiskd.protocol**](-ndiskd-protocol.md) +- [**!ndiskd.mopen**](-ndiskd-mopen.md) +- [**!ndiskd.filter**](-ndiskd-filter.md) +- [**!ndiskd.filterdriver**](-ndiskd-filterdriver.md) +- [**!ndiskd.oid**](-ndiskd-oid.md) +- [**!ndiskd.ndisrwlock**](-ndiskd-ndisrwlock.md) +- [**!ndiskd.netreport**](-ndiskd-netreport.md) + +## NET\_BUFFER\_LIST and NET\_BUFFER Commands + + +The following commands display information relating to [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-list-structure) and [**NET\_BUFFER**](https://msdn.microsoft.com/windows/hardware/drivers/network/net-buffer-structure) structures. + +- [**!ndiskd.nbl**](-ndiskd-nbl.md) +- [**!ndiskd.nb**](-ndiskd-nb.md) +- [**!ndiskd.nblpool**](-ndiskd-nblpool.md) +- [**!ndiskd.nbpool**](-ndiskd-nbpool.md) +- [**!ndiskd.pendingnbls**](-ndiskd-pendingnbls.md) +- [**!ndiskd.nbllog**](-ndiskd-nbllog.md) + +## NetAdapterCx Commands + + +The following commands display information relating to the Network Adapter WDF Class Extension (NetAdapterCx)\[LINK TBD\] and its associated structures, NET\_RING\_BUFFER \[LINK TBD\] and NET\_PACKET \[LINK TBD\]. + +- [**!ndiskd.cxadapter**](-ndiskd-cxadapter.md) +- [**!ndiskd.netqueue**](-ndiskd-netqueue.md) +- [**!ndiskd.netrb**](-ndiskd-netrb.md) +- [**!ndiskd.netpacket**](-ndiskd-netpacket.md) +- [**!ndiskd.netpacketfragment**](-ndiskd-netpacketfragment.md) + +## Network Interface Commands + + +The following commands display information relating to network interfaces. + +- [**!ndiskd.interfaces**](-ndiskd-interfaces.md) +- [**!ndiskd.ifprovider**](-ndiskd-ifprovider.md) + +## NDIS\_PACKET Commands + + +The following commands display information about [NDIS\_PACKET](https://msdn.microsoft.com/library/windows/hardware/ff557086) structures. These extensions are for legacy NDIS 5.x drivers. The NDIS\_PACKET structure and its associated architecture have been deprecated. + +- [**!ndiskd.pkt**](-ndiskd-pkt.md) +- [**!ndiskd.pktpools**](-ndiskd-pktpools.md) +- [**!ndiskd.findpacket**](-ndiskd-findpacket.md) + +## CoNDIS Commands + + +The following commands display information about [Connection-Oriented NDIS](https://msdn.microsoft.com/windows/hardware/drivers/network/connection-oriented-ndis) connections. + +- [**!ndiskd.vc**](-ndiskd-vc.md) +- [**!ndiskd.af**](-ndiskd-af.md) + +## NDIS Debugging Commands + + +The following commands display information relating to NDIS refcounts, event logs, stack traces, and debug traces. + +- [**!ndiskd.ndisref**](-ndiskd-ndisref.md) +- [**!ndiskd.ndisevent**](-ndiskd-ndisevent.md) +- [**!ndiskd.ndisstack**](-ndiskd-ndisstack.md) +- [**!ndiskd.dbglevel**](-ndiskd-dbglevel.md) +- [**!ndiskd.dbgsystems**](-ndiskd-dbgsystems.md) + +## WDI Commands + + +The following commands display information about [WDI Miniport Drivers](https://msdn.microsoft.com/windows/hardware/drivers/network/wdi-miniport-driver-design-guide). + +- [**!ndiskd.wdiadapter**](-ndiskd-wdiadapter.md) +- [**!ndiskd.wdiminidriver**](-ndiskd-wdiminidriver.md) +- [**!ndiskd.nwadapter**](-ndiskd-nwadapter.md) + +## NDIS and !ndiskd Information Commands + + +The following commands display information about NDIS.sys and ndiskd.dll. + +- [**!ndiskd.ndis**](-ndiskd-ndis.md) +- [**!ndiskd.ndiskdversion**](-ndiskd-ndiskdversion.md) + +## Miscellaneous Commands + + +- [**!ndiskd.ifstacktable**](-ndiskd-ifstacktable.md) +- [**!ndiskd.compartments**](-ndiskd-compartments.md) +- [**!ndiskd.ndisslot**](-ndiskd-ndisslot.md) + +## Related Topics + + +For more information about designing NDIS drivers for Windows Vista and later, see the [Network Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/network/index). + +For more information about reference for NDIS drivers for Windows Vista and later, see [Windows Vista and Later Networking Reference](https://msdn.microsoft.com/library/windows/hardware/ff571081). + +For a demonstration of using the !ndiskd debugger commands to debug the network stack, see [Debugging the Network Stack](https://go.microsoft.com/fwlink/p/?linkid=845311). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20NDIS%20Extensions%20%28Ndiskd.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/no-header-information-available.md b/windows-driver-docs-pr/debugger/no-header-information-available.md new file mode 100644 index 0000000000..b175cf4a29 --- /dev/null +++ b/windows-driver-docs-pr/debugger/no-header-information-available.md @@ -0,0 +1,31 @@ +--- +title: No Header Information Available +description: No Header Information Available +ms.assetid: cafc98c0-cae7-4140-8be7-6a535523f0e3 +keywords: ["No header information available (warning)", "header information not available (warning)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# No Header Information Available + + +## + + +The debugger identifies the proper symbols by examining the headers of the relevant modules. If these module headers are paged out, the debugger (and the symbol server) are unable to find the proper symbols. When this occurs, "No Header Information Available" is displayed within the symbol error message. + +For information about how to debug a target when module headers are paged out, see [Reading Symbols from Paged-Out Headers](reading-symbols-from-paged-out-headers.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20No%20Header%20Information%20Available%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/noninvasive-debugging--user-mode-.md b/windows-driver-docs-pr/debugger/noninvasive-debugging--user-mode-.md new file mode 100644 index 0000000000..64c28c1347 --- /dev/null +++ b/windows-driver-docs-pr/debugger/noninvasive-debugging--user-mode-.md @@ -0,0 +1,89 @@ +--- +title: Noninvasive Debugging (User Mode) +description: Noninvasive Debugging (User Mode) +ms.assetid: 91f09fb1-9f5e-4081-89b3-78c95eada817 +keywords: ["process, debugging noninvasively", "noninvasive debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Noninvasive Debugging (User Mode) + + +## + + +If a user-mode application is already running, the debugger can debug it *noninvasively*. With noninvasive debugging, you do not have as many debugging actions. However, you can minimize the debugger's interference with the target application. Noninvasive debugging is useful if the target application has stopped responding. + +In noninvasive debugging, the debugger does not actually attach to the target application. The debugger suspends all of the target's threads and has access to the target's memory, registers, and other such information. However, the debugger cannot control the target, so commands like [**g (Go)**](g--go-.md) do not work. + +If you try to execute commands that are not permitted during noninvasive debugging, you receive an error message that states, "The debugger is not attached, so process execution cannot be monitored." + +### Selecting the Process to Debug + +You can specify the target application by the process ID (PID) or process name. + +If you specify the application by name, you should use the complete name of the process, including the file name extension. If two processes have the same name, you must use the process ID instead. + +For more information about how to determine the process ID and the process name, see [Finding the Process ID](finding-the-process-id.md). + +For information about starting and stopping a noninvasive debugging session, see the following topics: + +- [Debugging a User-Mode Process Using Visual Studio](debugging-a-user-mode-process-using-visual-studio.md) +- [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md) +- [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md) + +### CDB Command Line + +To noninvasively debug a running process from the CDB command line, specify the -pv option, the -p option, and the process ID, in the following syntax. + +**cdb -pv -p** *ProcessID* + +Or, to noninvasively debug a running process by specifying the process name, use the following syntax instead. + +**cdb -pv -pn** *ProcessName* + +There are several other useful command-line options. For more information about the command-line syntax, see [**CDB Command-Line Options**](cdb-command-line-options.md). + +### WinDbg Command Line + +To noninvasively debug a running process from the WinDbg command line, specify the -pv option, the -p option, and the process ID, in the following syntax. + +**windbg -pv -p** *ProcessID* + +Or, to noninvasively debug a running process by specifying the process name, use the following syntax instead. + +**windbg -pv -pn** *ProcessName* + +There are several other useful command-line options. For more information about the command-line syntax, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +### WinDbg Menu + +When WinDbg is in dormant mode, you can noninvasively debug a running process by clicking Attach to a Process on the File menu or by pressing F6. + +When the Attach to Process dialog box appears, select the Noninvasive check box. Then, select the line that contains the process ID and name that you want. (You can also enter the process ID in the Process ID box.) Finally, click OK. + +### Debugger Command Window + +If the debugger is already active, you can noninvasively debug a running process by using the [**.attach -v (Attach to Process)**](-attach--attach-to-process-.md) command in the [Debugger Command window](the-debugger-command-window.md). + +You can use the .attach command if the debugger is already debugging one or more processes invasively. You can use this command in CDB if it is dormant, but not in a dormant WinDbg. + +If the .attach -v command is successful, the debugger debugs the specified process the next time that the debugger issues an execution command. Because execution is not permitted during noninvasive debugging, the debugger cannot noninvasively debug more than one process at a time. This restriction also means that using the .attach -v command might make an existing invasive debugging session less useful. + +### Beginning the Debugging Session + +For more information about how to begin a debugging session, see [Debugger Operation](debugger-operation-win8.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Noninvasive%20Debugging%20%28User%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/numerical-expression-syntax.md b/windows-driver-docs-pr/debugger/numerical-expression-syntax.md new file mode 100644 index 0000000000..fa78b04213 --- /dev/null +++ b/windows-driver-docs-pr/debugger/numerical-expression-syntax.md @@ -0,0 +1,43 @@ +--- +title: Numerical Expression Syntax +description: Numerical Expression Syntax +ms.assetid: 65f2df02-62f5-410a-bcb9-7a7eb7df9c74 +keywords: ["expressions", "numerical expressions", "MASM expressions", "C++ expressions", "syntax rules for commands, numerical expressions", "syntax rules for commands, MASM expressions", "syntax rules for commands, C++ expressions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Numerical Expression Syntax + + +## + + +The debugger accepts two different kinds of numeric expressions: *C++ expressions* and *MASM expressions*. Each of these expressions follows its own syntax rules for input and output. + +For more information about when each syntax type is used, see [Evaluating Expressions](evaluating-expressions.md). + +This section includes the following topics: + +[MASM Numbers and Operators](masm-numbers-and-operators.md) + +[C++ Numbers and Operators](c---numbers-and-operators.md) + +[MASM Expressions vs. C++ Expressions](masm-expressions-vs--c---expressions.md) + +[Expression Examples](expression-examples.md) + +[Sign Extension](sign-extension.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Numerical%20Expression%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/o.md b/windows-driver-docs-pr/debugger/o.md new file mode 100644 index 0000000000..6a348294b3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/o.md @@ -0,0 +1,25 @@ +--- +title: O (Windows Debugger Glossary) +description: Glossary page - O +Robots: noindex, nofollow +ms.assetid: b7510a3d-61f3-4eeb-8781-be3eb27ba27d +--- + +# O + + +**output callback objects** +Instances of the [IDebugOutputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550801) interface which have been registered with a client object. All output from the debugger engine is sent to the output callbacks. + +**output callbacks** +See output callback objects. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20O%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ob--ow--od--output-to-port-.md b/windows-driver-docs-pr/debugger/ob--ow--od--output-to-port-.md new file mode 100644 index 0000000000..742fd084d5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ob--ow--od--output-to-port-.md @@ -0,0 +1,85 @@ +--- +title: ob, ow, od (Output to Port) +description: The ob, ow, and od commands send a byte, word, or double word to the selected port. +ms.assetid: 04133df7-4b60-4709-a9e1-5946c8d30f8c +keywords: ["ob, ow, od (Output to Port) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ob, ow, od (Output to Port) +api_type: +- NA +--- + +# ob, ow, od (Output to Port) + + +The **ob**, **ow**, and **od** commands send a byte, word, or double word to the selected port. + +``` +ob Address Value +ow Address Value +od Address Value +``` + +## Parameters + + + *Address* +Specifies the address of the port. + + *Value* +Specifies the hexadecimal value to write to the port. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

x86-based only

+ +  + +Remarks +------- + +The **ob** command writes a single byte, the **ow** command writes a word, and the **od** command writes a double word. + +Make sure that you do not send a word or a double-word to a port that does not support this size. + +## See also + + +[**ib, id, iw (Input from Port)**](ib--iw--id--input-from-port-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ob,%20ow,%20od%20%28Output%20to%20Port%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/object-reference-tracing.md b/windows-driver-docs-pr/debugger/object-reference-tracing.md new file mode 100644 index 0000000000..e3bdc5fbd4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/object-reference-tracing.md @@ -0,0 +1,48 @@ +--- +title: Object Reference Tracing +description: Object Reference Tracing +ms.assetid: b5af0ab0-954b-4da1-a074-df88d2d039f8 +keywords: ["Object Reference Tracing", "Object Reference Tracing, overview", "GFlags, Object Reference Tracing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Reference Tracing + + +The **Object Reference Tracing** feature records sequential stack traces each time that an object reference counter is incremented or decremented. The traces can help you to detect object reference errors, including double-dereferencing, failure to reference, and failure to dereference objects. This feature is supported only in Windows Vista and later versions of Windows. + +For information about configuring the Object Reference Tracing feature in the **Global Flags** dialog box, see [Configuring Object Reference Tracing](configuring-object-reference-tracing.md). For information about configuring the Object Reference Tracing feature at the command prompt, see [**GFlags Commands**](gflags-commands.md). For an example, see [Example 15: Using Object Reference Tracing](example-15--using-object-reference-tracing.md). + +Object reference traces are most useful when you suspect that a particular object is not being referenced or dereferenced properly, typically because increased pool usage indicates that an object is leaking, or a process or session cannot be ended, even though its handle count is zero. Unlike traces that are recorded in logs for later review, object reference traces are designed to be used in real time, while the process is running and the object is being referenced and dereferenced. You view an object reference trace in the debugger by using the [**!obtrace debugger extension**](-obtrace.md). Because this extension requires a specified object address, you must know in advance which object is the likely source of the error. + +The following rules apply to Object Reference Tracing: + +- You can run only one object reference trace at a time. + +- Because a kernel-wide trace is not practical, you must limit the trace to objects that are created with specified pool tags, or to objects that are created by a specified process (indicated by an image file name), or both. + +- You can specify only one image file for each trace. If you specify an image file, the trace is limited to objects that are created by the processes that the image represents. Objects that are referenced by the process, but are created by a different process, are not traced. + +- You can specify a maximum of 16 pool tags for each trace. Objects with any of the specified pool tags are traced. + +- If you specify both an image file and one or more pool tags, the trace is limited to objects that are created by the process and have any of the specified pool tags. + +- Object Reference Tracing cannot trace processes that are already running when a trace is started. The trace includes only the objects of processes that start after the trace begins. + +- Objects marked for tracing are traced until the object is destroyed or tracing is disabled. By default, the traces for an object are maintained only until the object is destroyed, but you can specify a "permanent" trace (**/p**) where the trace is retained until tracing is disabled. + +- You can store the Object Reference Tracing configuration as a registry setting or a kernel flag (run-time) setting. If you have both registry and kernel flag settings, the run-time settings take precedence, but are lost when you shut down or restart the computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Object%20Reference%20Tracing%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/oem-support-extensions--kdex2x86-dll-.md b/windows-driver-docs-pr/debugger/oem-support-extensions--kdex2x86-dll-.md new file mode 100644 index 0000000000..9e85e6808b --- /dev/null +++ b/windows-driver-docs-pr/debugger/oem-support-extensions--kdex2x86-dll-.md @@ -0,0 +1,33 @@ +--- +title: OEM Support Extensions (kdex2x86.dll) +description: OEM Support Extensions (kdex2x86.dll) +ms.assetid: b3265c1b-2079-417f-8fc4-cceae5c114e1 +keywords: ["OEM Support extensions (kdex2x86.dll)", "kdex2x86.dll (OEM Support extensions)", "OEM Support Tools", "OEM Support Tools, kdex2x86.dll extensions", "extensions, OEM support"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# OEM Support Extensions (kdex2x86.dll) + + +## + + +The OEM Support Extensions can be found in the w2kfre\\kdex2x86.dll subdirectory of the Debugging Tools for Windows installation directory. + +You can use these extensions only with Windows 2000 targets. + +These extensions are not described in this documentation. For descriptions of these extensions, see the OEM Support Tools documentation. To get this documentation, along with the entire OEM Support Tools package, go to [Microsoft Support Article 253066](http://go.microsoft.com/fwlink/p/?LinkId=241339) and follow the instructions on that page. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20OEM%20Support%20Extensions%20%28kdex2x86.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-cdb.md b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-cdb.md new file mode 100644 index 0000000000..fd15c49a80 --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-cdb.md @@ -0,0 +1,32 @@ +--- +title: Opening a Dump File Using CDB +description: Opening a Dump File Using CDB +ms.assetid: 204DFA6F-2BA2-4B76-AFE0-28207710322B +--- + +# Opening a Dump File Using CDB + + +## Command Prompt + + +In a Command Prompt window, you can open a user-mode dump file when you launch CDB. Enter the following command. + +**cdb -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For more information about the command-line syntax, see [**CDB Command-Line Options**](cdb-command-line-options.md) + +## CDB Command Line + + +You can also open a dump file after the debugger is running by entering the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed by [**g (Go)**](g--go-.md). This allows you to debug multiple dump files at the same time. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20a%20Dump%20File%20Using%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-kd.md b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-kd.md new file mode 100644 index 0000000000..ce400bc0e2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-kd.md @@ -0,0 +1,32 @@ +--- +title: Opening a Dump File Using KD +description: Opening a Dump File Using KD +ms.assetid: 458E9BA6-6FA0-4FEF-93A0-062C9E11D21F +--- + +# Opening a Dump File Using KD + + +## Command Prompt + + +In a Command Prompt window, you can open a dump file when you launch KD. Use the following command. + +**kd -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For more information about the command-line syntax, see [**KD Command-Line Options**](kd-command-line-options.md). + +## KD Command Line + + +You can also open a dump file after the debugger is running by entering the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed by [**g (Go)**](g--go-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20a%20%20Dump%20File%20Using%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-visual-studio.md b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-visual-studio.md new file mode 100644 index 0000000000..dffe56a145 --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-visual-studio.md @@ -0,0 +1,26 @@ +--- +title: Opening a Dump File Using Visual Studio +description: The procedures Opening a Dump File Using Visual Studio. +ms.assetid: 3B7327FE-335F-46FB-94C3-75D5B52A295D +--- + +# Opening a Dump File Using Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=391063). + +To open a dump file using Visual Studio: + +1. In Visual Studio, from the **File** menu, choose **Open | Crash Dump** . +2. Navigate to the dump file you want to open. +3. Click **Open.** + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20a%20Dump%20File%20Using%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-windbg.md b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-windbg.md new file mode 100644 index 0000000000..ed2644188c --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-a-crash-dump-file-using-windbg.md @@ -0,0 +1,36 @@ +--- +title: Opening a Dump File Using WinDbg +description: There are several ways you can use WinDbg to open a dump file. +ms.assetid: DE2EABE7-2B7A-4DF9-82FD-EF19D69E31A7 +--- + +# Opening a Dump File Using WinDbg + + +There are several ways you can use WinDbg to open a dump file. + +### WinDbg Menu + +If WinDbg is already running and is in dormant mode, you can open a dump by choosing **Open Crash Dump** from the **File** menu or by pressing CTRL+D. When the Open Crash Dump dialog box appears, enter the full path and name of the crash dump file in the **File name** box, or use the dialog box to select the proper path and file name. When the proper file has been chosen, click **Open**. + +### Command Prompt + +In a Command Prompt window, you can open a dump file when you launch WinDbg. Use the following command: + +**windbg -y** *SymbolPath* **-i** *ImagePath* **-z** *DumpFileName* + +The **-v** option (verbose mode) is also useful. For more information about the command-line syntax, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +### Debugger Command Window + +If WinDbg is already in a kernel-mode debugging session, you can open a dump file by using the [**.opendump (Open Dump File)**](-opendump--open-dump-file-.md) command, followed by [**g (Go)**](g--go-.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20a%20Dump%20File%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-a-window.md b/windows-driver-docs-pr/debugger/opening-a-window.md new file mode 100644 index 0000000000..6b391297d6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-a-window.md @@ -0,0 +1,116 @@ +--- +title: Opening a Window +description: Opening a Window +ms.assetid: e056a556-8201-47e5-9a21-dbd5277c15c2 +keywords: ["debugging information windows, opening"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Opening a Window + + +## + + +When WinDbg begins a debugging session, the [Debugger Command window](debugger-command-window.md) automatically opens. The [Disassembly window](disassembly-window.md) also automatically opens, unless you deselect [Automatically Open Disassembly](window---automatically-open-disassembly.md) on the **Window** menu. + +Whenever WinDbg discovers a source file that corresponds to the current program counter, WinDbg opens a [Source window](source-window.md) for that file. For other ways to open Source windows, see [Source Path](source-path.md). + +You can use the following menu commands, toolbar buttons, and shortcut keys to switch to these windows. That is, if a window is not open, it opens. If a window is open but inactive, it becomes active. If a window is docked and there is a floating window in front of it, the docked window becomes active but the floating window stays in front of the docked window. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WindowMenu commandButtonShortcut keys

[Debugger Command window](debugger-command-window.md)

View | Command

Screen shot of the Debugger Command window button

ALT+1

Watch window

View | Watch

Screen shot of the Watch button

ALT+2

[Locals window](locals-window.md)

View | Locals

Screen shot of the Locals button

ALT+3

[Registers window](registers-window.md)

View | Registers

Screen shot of the Registers button

ALT+4

[Memory window](memory-window.md)

View | Memory

Screen shot of the Memory button

ALT+5

[Calls window](calls-window.md)

View | Call Stack

Screen shot of the Call Stack button

ALT+6

[Disassembly window](disassembly-window.md)

View | Disassembly

Screen shot of the Disassembly button

ALT+7

Scratch Pad window

View | Scratch Pad

Screen shot of the Scratch Pad button

ALT+8

[Processes and Threads window](processes-and-threads-window.md)

View | Processes and Threads

Screen shot of the Processes and Threads button

ALT+9

[Source window](source-window.md)

Click [File | Open Source File](file---open-source-file.md) and then select a source file.

Screen shot of the Open Source File button

CTRL+O

+ +  + +You can also activate a window by selecting it from the [list of open windows](list-of-open-windows.md) at the bottom of the **Window** menu. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/opening-the-dialog-box.md b/windows-driver-docs-pr/debugger/opening-the-dialog-box.md new file mode 100644 index 0000000000..d54ae4ddd9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/opening-the-dialog-box.md @@ -0,0 +1,37 @@ +--- +title: Opening the Dialog Box +description: Opening the Dialog Box +ms.assetid: 7cb5a947-0830-4208-a6de-cdb7812179c0 +keywords: ["GFlags, dialog box (opening)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Opening the Dialog Box + + +## + + +**To open the Global Flags dialog box** + +- Double-click the **gflags.exe** icon or, at the command line, or in the **Run** dialog box, type **gflags** (without parameters). + +- - OR + +- Click **Start**, point to **All Programs**, point to **Debugging Tools for Windows,** and then click **Global Flags**. + + On Windows Vista, click **Start**, click **All Programs**, click **Debugging Tools for Windows**, right-click **Global Flags** and then click **Run as administrator**. If you omit this step, Windows displays the **System Registry Gflags Error: 5**. The Gflags dialog box opens, but Gflags commands fail. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Opening%20the%20Dialog%20Box%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/other-acpi-debugging-extensions.md b/windows-driver-docs-pr/debugger/other-acpi-debugging-extensions.md new file mode 100644 index 0000000000..a821db6de9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/other-acpi-debugging-extensions.md @@ -0,0 +1,51 @@ +--- +title: Other ACPI Debugging Extensions +description: Other ACPI Debugging Extensions +ms.assetid: ea5c9ca6-f872-40ff-8e0d-5d6d096ccc34 +keywords: ["ACPI debugging, useful extensions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Other ACPI Debugging Extensions + + +## + + +The following extension commands are useful for debugging problems with an Advanced Configuration and Power Interface (ACPI) BIOS: + +- [**!acpicache**](-acpicache.md) displays all of the ACPI tables cached by the hardware application layer (HAL) + +- [**!acpiinf**](-acpiinf.md) displays information on the configuration of the ACPI + +- [**!acpiirqarb**](-acpiirqarb.md) displays the contents of the ACPI IRQ arbiter structure + +- [**!facs**](-facs.md) displays a Firmware ACPI Control Structure + +- [**!fadt**](-fadt.md) displays a Fixed ACPI Description Table + +- [**!mapic**](-mapic.md) displays an ACPI Multiple APIC Table + +- [**!nsobj**](-nsobj.md) displays an ACPI namespace object + +- [**!nstree**](-nstree.md) displays a section of the ACPI namespace tree + +- [**!rsdt**](-rsdt.md) displays the ACPI Root System Description Table + +For a complete list of ACPI-related extensions, see [**!acpikd.help**](-acpikd-help.md). + +For details on the **!amli***xxx* extensions, see [The AMLI Debugger](the-amli-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Other%20ACPI%20Debugging%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/other-data-spaces.md b/windows-driver-docs-pr/debugger/other-data-spaces.md new file mode 100644 index 0000000000..fe339ae5e4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/other-data-spaces.md @@ -0,0 +1,51 @@ +--- +title: Other Data Spaces +description: Other Data Spaces +ms.assetid: f676a478-c02a-4400-8173-a1b3103c6c1b +keywords: ["Debugger Engine API, memory, data spaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Other Data Spaces + + +## + + +In kernel-mode debugging, it is possible to read and write data to a variety of data spaces in addition to the main memory and registers. The following data spaces can be accessed: + +System Bus +The methods [**ReadBusData**](https://msdn.microsoft.com/library/windows/hardware/ff553519) and [**WriteBusData**](https://msdn.microsoft.com/library/windows/hardware/ff561371) read and write system bus data. + +Control-Space Memory +The methods [**ReadControl**](https://msdn.microsoft.com/library/windows/hardware/ff553524) and [**WriteControl**](https://msdn.microsoft.com/library/windows/hardware/ff561374) read and write control-space memory. + +I/O Memory. +The methods [**ReadIo**](https://msdn.microsoft.com/library/windows/hardware/ff553573) and [**WriteIo**](https://msdn.microsoft.com/library/windows/hardware/ff561402) read and write system and bus I/O memory. + +Model Specific Register (MSR) +The methods [**ReadMsr**](https://msdn.microsoft.com/library/windows/hardware/ff554292) and [**WriteMsr**](https://msdn.microsoft.com/library/windows/hardware/ff561424) read and write MSRs, which are control registers that enable and disable features, and support debugging, for a particular model of CPU. + +### Handles + +In user-mode debugging, information about system objects can be obtained using system handles owned by a target process. The method [**ReadHandleData**](https://msdn.microsoft.com/library/windows/hardware/ff553542) can be used to read this information. + +System handles for thread and process system objects can be obtained by using the [**GetCurrentThreadHandle**](https://msdn.microsoft.com/library/windows/hardware/ff545904) and [**GetCurrentProcessHandle**](https://msdn.microsoft.com/library/windows/hardware/ff545816) methods. These handles are also provided to the [**IDebugEventCallbacks::CreateThread**](https://msdn.microsoft.com/library/windows/hardware/ff550713) and [**IDebugEventCallbacks::CreateProcess**](https://msdn.microsoft.com/library/windows/hardware/ff550697) callback methods when create-thread and create-process debugging event occur. + +**Note**   In kernel mode, the process and thread handles are artificial handles. They are not system handles. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Other%20Data%20Spaces%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/other-symbol-servers.md b/windows-driver-docs-pr/debugger/other-symbol-servers.md new file mode 100644 index 0000000000..6aac89d5aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/other-symbol-servers.md @@ -0,0 +1,53 @@ +--- +title: Other Symbol Servers +description: Other Symbol Servers +ms.assetid: 69d88a60-88b6-4118-9f8b-0d7b80bad1ab +keywords: ["symbol servers, writing your own symbol server"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Other Symbol Servers + + +## + + +If you wish to use a different method for your symbol search, you can provide your own symbol server DLL rather than using SymSrv. + +### Setting the Symbol Path + +When implementing a symbol server other than SymSrv, the debugger's symbol path is set in the same way as with SymSrv. See [SymSrv](symsrv.md) for an explanation of the symbol path syntax. The only change you need to make is to replace the string **symsrv.dll** with the name of your own symbol server DLL. + +If you wish, you are free to use a different syntax within the parameters to indicate the use of different technologies such as UNC paths, SQL database identifiers, or Internet specifications. + +### Implementing Your Own Symbol Server + +The central portion of the server is the code that communicates with DbgHelp to find the symbols. Every time DbgHelp requires symbols for a newly loaded module, it calls the symbol server to locate the appropriate symbol files. The symbol server locates each file according to unique parameters such as the time stamp or image size. The server returns a validated path to the requested file. To implement this, the server must export the **SymbolServer** function. + +The server should also support the **SymbolServerSetOptions** and **SymbolServerGetOptions** functions. And DbgHelp will call the **SymbolServerClose** function, if it is exported by the server. See [Symbol Server API](symbol-server-api.md) for information about where these routines are documented. + +You must not change the actual symbol file name returned by your symbol server. DbgHelp stores the name of a symbol file in multiple locations. Therefore, the server must return a file of the same name as that specified when the symbol was requested. This restriction is needed to assure that the symbol names displayed during symbol loading are the ones that the programmer will recognize. + +### Restrictions on Multiple Symbol Servers + +DbgHelp supports the use of only one symbol server at a time. Your symbol path can contain multiple instances of the same symbol server DLL, but not two different symbol server DLLs. This is not much of a restriction, since you are still free to include multiple instances of a symbol server in your symbol path, each pointing to a different symbol store. But if you want to switch between two different symbol server DLLs, you will have to change the symbol path each time. + +### Installing Your Symbol Server + +The details of your symbol server installation will depend on your situation. You might wish to set up an installation process that copies your symbol server DLL and sets the \_NT\_SYMBOL\_PATH environment variable automatically. + +Depending on the technology used in your server, you may also need to install or access the symbol data itself. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Other%20Symbol%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/other-symbol-stores.md b/windows-driver-docs-pr/debugger/other-symbol-stores.md new file mode 100644 index 0000000000..7df0997fb1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/other-symbol-stores.md @@ -0,0 +1,33 @@ +--- +title: Other Symbol Stores +description: Other Symbol Stores +ms.assetid: 65bb4291-c56a-4837-ac45-6751ebdbd579 +keywords: ["symbol stores, writing your own symbol store"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Other Symbol Stores + + +## + + +It is possible to write your own symbol store creation program, rather than using SymStore. + +Since SymStore transactions are all logged in CSV-format text files, you can leverage any existing SymStore log files for use in your own database program. + +If you plan to use the SymSrv program provided with Debugging Tools for Windows package, it is recommended that you use SymStore as well. Updates to these two programs will always be released together, and therefore their versions will always match. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Other%20Symbol%20Stores%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/overview-of-kernel-streaming-debugging.md b/windows-driver-docs-pr/debugger/overview-of-kernel-streaming-debugging.md new file mode 100644 index 0000000000..d4633bdfe2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/overview-of-kernel-streaming-debugging.md @@ -0,0 +1,32 @@ +--- +title: Overview of Kernel Streaming Debugging +description: Overview of Kernel Streaming Debugging +ms.assetid: 7e09eccf-f74e-4faa-bb59-5c11f93c4b90 +keywords: ["kernel streaming debugging", "kernel streaming debugging, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of Kernel Streaming Debugging + + +Kernel streaming debugging extensions can be found in the extension module Ks.dll. + +You can use Ks.dll to help debug KS, AVStream, port class and stream class drivers. + +For a complete list of the extension commands in Ks.dll, see [Kernel Streaming Extensions (Ks.dll)](kernel-streaming-extensions--ks-dll-.md). + +If you wish to use these extensions with Windows 2000, you must copy Ks.dll from the kdexts directory to the w2kfre directory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Overview%20of%20Kernel%20Streaming%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/overview-of-ndis-debugging.md b/windows-driver-docs-pr/debugger/overview-of-ndis-debugging.md new file mode 100644 index 0000000000..94d7c1903c --- /dev/null +++ b/windows-driver-docs-pr/debugger/overview-of-ndis-debugging.md @@ -0,0 +1,32 @@ +--- +title: Overview of NDIS Debugging +description: Overview of NDIS Debugging +ms.assetid: d15e8a0c-e553-4e0d-84ed-5fdc2026a2d3 +keywords: ["NDIS debugging, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of NDIS Debugging + + +The two primary tools for debugging a network driver are debug tracing and the Network Driver Interface Specification (NDIS) extensions. For more information on debug tracing, see [Enabling NDIS Debug Tracing](enabling-ndis-debug-tracing.md). For more information on the NDIS debugging extensions, see [NDIS Extensions](ndis-extensions--ndiskd-dll-.md), which provides a complete list of the extension commands found in the extension module Ndiskd.dll. The Windows 2000 version of this extension module appears in the w2kfre and w2kchk directories. The Windows XP and later version of this extension module appear in the winxp directory. + +An additional tool for debugging a network driver is the collection of regular debugging extensions, which are useful for obtaining debugging information. For example, entering [**!stacks 2 ndis!**](-stacks.md) displays all threads in the stack beginning with **ndis!**. This information can be useful for debugging hangs and stalls. + +There is also an NDIS-specific bug check code, bug check 0x7C (BUGCODE\_NDIS\_DRIVER). For a complete list of its parameters, see [**Bug Check 0x7C**](bug-check-0x7c--bugcode-ndis-driver.md). + +Another useful tool for testing an NDIS driver is NDIS Verifier. For more information, consult the NDIS Verifier topic in the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Overview%20of%20NDIS%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/overview-of-rpc-debugging.md b/windows-driver-docs-pr/debugger/overview-of-rpc-debugging.md new file mode 100644 index 0000000000..224cc46691 --- /dev/null +++ b/windows-driver-docs-pr/debugger/overview-of-rpc-debugging.md @@ -0,0 +1,43 @@ +--- +title: Overview of RPC Debugging +description: Overview of RPC Debugging +ms.assetid: 21db61fe-a4a1-45d3-9026-f58aecd3a3bc +keywords: ["RPC debugging, overview", "remote procedure call (RPC)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of RPC Debugging + + +## + + +Microsoft Remote Procedure Call (RPC) makes it easy to cross process and machine boundaries and carry data around. This network programming standard is one reason that networking with Microsoft Windows is so powerful. + +However, because RPC hides network calls from individual processes, it obscures the details of the interactions between the computers. This can make it hard to be sure why threads are doing what they are doing -- or fail to do what they are supposed to do. As a result, debugging and troubleshooting RPC errors can be difficult. In addition, the vast majority of problems that appear to be RPC errors are actually configuration issues, or network connectivity issues, or other component issues. + +Debugging Tools for Windows contains a tool called DbgRpc, as well as RPC-related debugger extensions. These can be used to analyze a variety of RPC problems on Windows XP and later versions of Windows. + +These Windows versions can be configured to save RPC run-time state information. Different amounts of state information can be saved; this allows you to obtain the information you need without placing a significant burden on your computer. See [Enabling RPC State Information](enabling-rpc-state-information.md) for details. + +This information can then be accessed through either the debugger or the DbgRpc tool. In each case, a collection of queries is available. See [Displaying RPC State Information](displaying-rpc-state-information.md) for details. + +In many cases, you can troubleshoot a problem by using the techniques outlined in [Common RPC Debugging Techniques](common-rpc-debugging-techniques.md). + +If you want to explore the mechanics of how this information is stored, or if you want to devise your own techniques for state information analysis, see [RPC State Information Internals](rpc-state-information-internals.md). + +These tools and techniques do not work on Windows 2000. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Overview%20of%20RPC%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/overview-of-scsi-miniport-debugging.md b/windows-driver-docs-pr/debugger/overview-of-scsi-miniport-debugging.md new file mode 100644 index 0000000000..1e981702e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/overview-of-scsi-miniport-debugging.md @@ -0,0 +1,30 @@ +--- +title: Overview of SCSI Miniport Debugging +description: Overview of SCSI Miniport Debugging +ms.assetid: 9d05d416-aae4-453a-bdb0-2ac9148ad81d +keywords: ["SCSI Miniport Debugging, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of SCSI Miniport Debugging + + +Small computer system interface (SCSI) debugging extensions can be found in two extension modules: Scsikd.dll and Minipkd.dll. For an overview of the most important extension commands in these modules, see [Extensions for Debugging SCSI Miniport Drivers](extensions-for-debugging-scsi-miniport-drivers.md). For a complete list, see [SCSI Miniport Extensions](scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md). + +The SCSIkd.dll extension commands can be used in any version of Windows. The Minipkd.dll extension commands can only be used in Windows XP and later versions of Windows. Commands in Minipkd.dll are only applicable to miniport drivers that work with the SCSI Port driver. + +To test a SCSI miniport driver, use the SCSI Verification feature of Driver Verifier. For information about Driver Verifier, see [Driver Verifier](http://go.microsoft.com/fwlink/p/?linkid=120480) in the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Overview%20of%20SCSI%20Miniport%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/overview-of-the-logging-manifest.md b/windows-driver-docs-pr/debugger/overview-of-the-logging-manifest.md new file mode 100644 index 0000000000..2fb0070f84 --- /dev/null +++ b/windows-driver-docs-pr/debugger/overview-of-the-logging-manifest.md @@ -0,0 +1,39 @@ +--- +title: Overview of the Logging Manifest +description: Overview of the Logging Manifest +ms.assetid: abf550c5-6b70-4043-b2e9-d3dc5096cc4e +keywords: ["LogViewer, manifest", "LogViewer, manifest, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of the Logging Manifest + + +## + + +The logging manifest is the group of "header" files that define the functions and COM interfaces that are intercepted and logged. These are not true C++ header files -- they are in a slightly different format that explicitly declares the information needed by Logger. + +For example, the manifest format facilitates the following features: + +- Designation of OUT parameters. These are parameters that should be logged both on their way into an function and also on their way out. + +- Definition of flag masks. This feature allows LogViewer to break a DWORD flag into its constituent bit labels for easier reading. + +- Definition of failure cases. This feature allows LogViewer to shade the rows of functions that have returned a failure status code or another error code. Also, if the function sets the "LastError" value for the thread, LogViewer can store away the error code and expand it to its corresponding human-readable error message. + +- Designation of parameters that can be aliased for log differencing. This feature gives LogViewer the option of assigning a constant string to a value that changes from execution to execution like pointers and handles when it exports the data to a file. You can then use a differencing tool to compare two execution logs for discrepancies. If pointers and handle values were not aliased, they would produce uninteresting discrepancies when the two files are compared. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Overview%20of%20the%20Logging%20Manifest%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/p--step-.md b/windows-driver-docs-pr/debugger/p--step-.md new file mode 100644 index 0000000000..1c641c1327 --- /dev/null +++ b/windows-driver-docs-pr/debugger/p--step-.md @@ -0,0 +1,104 @@ +--- +title: p (Step) +description: The p command executes a single instruction or source line and optionally displays the resulting values of all registers and flags. +ms.assetid: 4ee24e76-b751-4346-80af-d481d9513ce0 +keywords: ["p (Step) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- p (Step) +api_type: +- NA +--- + +# p (Step) + + +The **p** command executes a single instruction or source line and optionally displays the resulting values of all registers and flags. When subroutine calls or interrupts occur, they are treated as a single step. + +User-Mode + +``` +[~Thread] p[r] [= StartAddress] [Count] ["Command"] +``` + +Kernel-Mode + +``` +p[r] [= StartAddress] [Count] ["Command"] +``` + +## Parameters + + + *Thread* +Specifies the threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **pr**, [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All three of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where execution should begin. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of instructions or source lines to step through before stopping. Each step is displayed as a separate action in the [Debugger Command window](debugger-command-window.md). The default value is one. + + *Command* +Specifies a debugger command to execute after the step is performed. This command is executed before the standard **p** results are displayed. If you also use *Count*, the specified command is executed after all stepping is complete (but before the results from the final step are displayed). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about issuing the **p** command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +When you specify *Count*, each instruction is displayed as it is stepped through. + +If the debugger encounters a **call** instruction or interrupt while stepping, the called subroutine will execute completely unless a breakpoint is encountered. Control is returned to the debugger at the next instruction after the call or interrupt. + +Each step executes a single assembly instruction or a single source line, depending on whether the debugger is in assembly mode or source mode. Use the [**l+t**](l---l---set-source-options-.md) and l-t commands or the buttons on the WinDbg toolbar to switch between these modes. + +When you are quickly stepping many times in WinDbg, the debugging information windows are updated after each step. If this update causes slower response time, use [**.suspend\_ui (Suspend WinDbg Interface)**](-suspend-ui--suspend-windbg-interface-.md) to temporarily suspend the refreshing of these windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20p%20%28Step%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/p.md b/windows-driver-docs-pr/debugger/p.md new file mode 100644 index 0000000000..6db8fd8cca --- /dev/null +++ b/windows-driver-docs-pr/debugger/p.md @@ -0,0 +1,59 @@ +--- +title: P (Windows Debugger Glossary) +description: Glossary page - P +Robots: noindex, nofollow +ms.assetid: 4cfad26c-d8c0-4f80-aa54-b9cadbc84df3 +--- + +# P + + +**page table** +A process-specific table that maps virtual memory addresses to physical memory addresses. + +**Page Table Entry (PTE)** +An item in the page table. + +**paged pool** +A portion of system memory that can be paged to disk. + +Note that this term does not only refer to memory that actually has actually been paged out to the disk - it includes any memory that the operating system is permitted to page. + +**paging** +A virtual memory operation in which the memory manager transfers pages from memory to disk when physical memory becomes full. A *page fault* occurs when a thread accesses a page that is not in memory. + +**parent symbol** +A *symbol* that is contains in other symbols, for example, a structure contains its member. + +See also *child symbol*. + +For more information, see [Scopes and Symbol Groups](scopes-and-symbol-groups.md). + +**primary client** +A client object that has joined the current debugging session + +For more information, see [Client Objects](client-objects.md). + +**process server** +An instance of the debugger engine acting as a proxy, listening for connections from smart client and performing memory, processor, or Windows operations as requested by these remote clients. + +See also *debugging server*. + +For more information, see [Process Servers (User Mode)](process-servers--user-mode-.md) and Process Server and Smart Client. + +**processor breakpoint** +A breakpoint that is implemented by the processor. The debugger engine instructs the target's processor to insert this breakpoint. + +See also software breakpoint. See also *software breakpoint*. + +For more information, see [Using Breakpoints](using-breakpoints.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20P%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pa--step-to-address-.md b/windows-driver-docs-pr/debugger/pa--step-to-address-.md new file mode 100644 index 0000000000..d3d9a03b4b --- /dev/null +++ b/windows-driver-docs-pr/debugger/pa--step-to-address-.md @@ -0,0 +1,116 @@ +--- +title: pa (Step to Address) +description: The pa command executes the program until the specified address is reached, displaying each step. +ms.assetid: 497261a9-69fb-4df2-b342-cd62bda8a51f +keywords: ["pa (Step to Address) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pa (Step to Address) +api_type: +- NA +--- + +# pa (Step to Address) + + +The **pa** command executes the program until the specified address is reached, displaying each step. + +User-Mode + +``` +[~Thread] pa [r] [= StartAddress] StopAddress ["Command"] +``` + +Kernel-Mode + +``` +pa [r] [= StartAddress] StopAddress ["Command"] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **par**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *StopAddress* +Specifies the address where execution will stop. This address must match the exact address of an instruction. + + *Command* +Specifies a debugger command to execute after the step is performed. This command is executed before the standard **pa** results are displayed. If you also use *StopAddress*, the specified command is executed after *StopAddress* is reached (but before the results from the final step are displayed). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **pa** command causes the target to begin executing. This execution continues until the specified instruction is reached or a breakpoint is encountered. + +**Note**   If you use this command in kernel mode, execution stops when an instruction is encountered at the specified virtual address in any virtual address space. + +  + +During this execution, all steps are displayed explicitly. Called functions are treated as a single unit. Therefore, the display of this command is similar to what you see if you execute [**p (Step)**](p--step-.md) repeatedly until the program counter reaches the specified address. + +For example, the following command explicitly steps through the target code until the return address of the current function is reached. + +``` +0:000> pa @$ra +``` + +The following example demonstrates using the **pa** command along with the **kb** command to display the stack trace: + +``` +0:000> pa 70b5d2f1 "kb" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20pa%20%28Step%20to%20Address%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/parsing-extension-arguments.md b/windows-driver-docs-pr/debugger/parsing-extension-arguments.md new file mode 100644 index 0000000000..bcf2d6d50e --- /dev/null +++ b/windows-driver-docs-pr/debugger/parsing-extension-arguments.md @@ -0,0 +1,166 @@ +--- +title: Parsing Extension Arguments +description: Parsing Extension Arguments +ms.assetid: 3c75fb75-50d0-48e4-abf4-e4dba9a080f9 +keywords: ["EngExtCpp extensions, parsing arguments"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Parsing Extension Arguments + + +The EngExtCpp extension framework provides methods to aid in parsing the command-line arguments passed to an extension. To take advantage of these methods, the extension must first declare the format of the command-line arguments in the [**EXT\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/ff544514) macro. + +To bypass the command-line argument parsing done by the framework and let the extension itself parse the arguments, set the command-line description to `"{{custom}}"` and use the method [**GetRawArgStr**](https://msdn.microsoft.com/library/windows/hardware/ff548226) to get the command-line arguments for parsing. + +Command-line description strings will automatically be wrapped when printed, to fit the column width of the display. However, newline characters can be embedded in the description strings - using '`\n`' - to start new lines. + +The command-line description can be **NULL** or the empty string. If either occurs, it indicates that the extension command does not take any arguments. + +### Command-Line Description + +The description of the command-line arguments is a sequence that contains two types of components: directives and arguments. The description can optionally contain one of each directive and can contain up to 64 arguments. + +### Directives + +Directives specify how the arguments are parsed. They are enclosed by double braces (`'{{'` and `'}}'`). Each directive can optionally appear zero or one times in the string that describes the arguments. + +The following directives are available: + +`custom` +Turns off the parsing done by the extension framework and lets the extension perform its own parsing. + +`l:str` +Overrides the default long description of the command-line arguments. The extension framework will use *str* for the full description of all the arguments. + +`opt:str` +Overrides the default prefix characters for named commands. The default value is `"/-"`, allowing '`/`' or '`-`' to be used as the prefix that identifies named arguments. + +`s:str` +Overrides the default short description of the command-line arguments. The extension framework will use *str* for the short description of all the arguments. + +Here are some examples of directives. The following string is used by an extension command that parses its own arguments. It also provides short and long descriptions for use with the automatic **!help** extension command: + +``` +{{custom}}{{s: }}{{l:arg1 - Argument 1\narg2 - Argument 2}} +``` + +The following string changes the argument option prefix characters to '`/`' or '`-`'. With this directive, the arguments will be specified using '`+arg`' and '`:arg`' instead of '`/arg`' and '`-arg`': + +``` +{{opt:+:}} +``` + +### Arguments + +Arguments can be of two types: named and unnamed. Unnamed arguments are read positionally. Both types of argument also have a display name, used by the help command. + +Argument descriptions are enclosed by single braces (`'{'` and `'}'`). + +Each argument description has the following syntax: + +``` +{[optname];[type[,flags]];[argname];[argdesc]} +``` + +where: + +*optname* +The name of the argument. This is the name used in commands and in methods that fetch arguments by name. This name is optional. If it is present, the argument becomes a "named argument"; it can appear anywhere on the command-line and is referenced by name. If it is not present, the argument becomes an "unnamed argument"; its position on the command-line is important and it is referenced by its position relative to the other unnamed arguments. + +*type* +The type of the argument. This affects how the argument is parsed and how it is retrieved. The *type* parameter can have one of the following values: + +b +Boolean type. The argument is either present or not present. Named Boolean arguments can be retrieved using [**HasArg**](https://msdn.microsoft.com/library/windows/hardware/ff549721). + +e\[d\]\[s\]\[bits\] +Expression type. The argument has a numeric value. Named expression arguments can be retrieved using [**GetArgU64**](https://msdn.microsoft.com/library/windows/hardware/ff545596) and unnamed expression arguments can be retrieved using [**GetUnnamedArgU64**](https://msdn.microsoft.com/library/windows/hardware/ff549465). + +d +The expression is limited to the next space character in the argument string. If this is not present, the expression evaluator will consume characters from the command line until it determines that it reached the end of the expression. + +s +The value of the expression is signed. Otherwise, the value of the expression is unsigned. + +bits +The number of bits in the value of the argument. The maximum value for *bits* is 64. + +s +String type. The string is limited to the next space character. Named string arguments can be retrieved using [**GetArgStr**](https://msdn.microsoft.com/library/windows/hardware/ff545586) and unnamed string arguments can be retrieved using [**GetUnnamedArgStr**](https://msdn.microsoft.com/library/windows/hardware/ff549464). + +x +String type. The argument is the rest of the command line. The argument is retrieved using **GetArgStr** or **GetUnnamedArgStr**, as with the s string type. + +*flags* +The argument flags. These determine how the argument will be treated by the parser. The *flags* parameter can have one of the following values: + +d=expr +The default value of the argument. If the argument is not present on the command line, then the argument is set to *expr*. The default value is a string that is parsed according to the type of the argument. + +ds +The default value will not be displayed in the argument description provided by the help. + +o +The argument is optional. This is the default for named arguments. + +r +The argument is required. This is the default for unnamed arguments. + +*argname* +The display name of the argument. This is the name used by the automatic **!help** extension command and by the automatic **/?** or **-?** command-line arguments. Used when printing a summary of the command-line options. + +*argdesc* +A description of the argument. This is the description printed by the automatic **!help** extension and by the automatic "**/?**" or "**-?**" command-line arguments. + +Here are some examples of argument descriptions. The following expression defines a command which takes a single optional expression argument. The argument must fit in 32 bits. If the argument isn't present on the command line, the default value of 0x100 will be used. + +``` +{;e32,o,d=0x100;flags;Flags to control command} +``` + +The following expression defines a command with an optional Boolean "**/v**" argument and a required unnamed string argument. + +``` +{v;b;;Verbose mode}{;s;name;Name of object} +``` + +The following expression defines a command that has an optional named expression argument **/oname** *expr* and an optional named string argument **/eol** *str*. If **/eol** is present, its value will be set to the remainder of the command line and no further arguments will be parsed. + +``` +{oname;e;expr;Address of object}{eol;x;str;Commands to use} +``` + +### Command Line + +The following is a list of some ways that arguments are parsed on the command line: + +- The values of named expression and string arguments follow the name on the command line. For example, **/name** *expr* or **/name** *str*. + +- For named Boolean arguments, the value is true if the name appears on the command line; false otherwise. + +- Multiple single-character-named Boolean options can be grouped together on the command line. For example, "/a /b /c" can be written using the shorthand notation "/abc" (unless there is already an argument named "abc"). + +- If the command line contains the named argument "?" - for example, "/?" and "-?" - the argument parsing ends, and the help text for the extension is displayed. + +### Parsing Internals + +Several methods are used by the argument parser to set arguments. + +The method [**SetUnnamedArg**](https://msdn.microsoft.com/library/windows/hardware/ff556876) will change the value of an unnamed argument. And, for convenience, the methods [**SetUnnamedArgStr**](https://msdn.microsoft.com/library/windows/hardware/ff556878) and [**SetUnnamedArgU64**](https://msdn.microsoft.com/library/windows/hardware/ff556879) will set unnamed string and expression arguments respectively. + +Similar methods exist for named arguments. [**SetArg**](https://msdn.microsoft.com/library/windows/hardware/ff556614) is used to change the value of any named argument and [**SetArgStr**](https://msdn.microsoft.com/library/windows/hardware/ff556618) and [**SetArgU64**](https://msdn.microsoft.com/library/windows/hardware/ff556622) are used for named string and expression arguments respectively. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Parsing%20Extension%20Arguments%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pc--step-to-next-call-.md b/windows-driver-docs-pr/debugger/pc--step-to-next-call-.md new file mode 100644 index 0000000000..542380375e --- /dev/null +++ b/windows-driver-docs-pr/debugger/pc--step-to-next-call-.md @@ -0,0 +1,99 @@ +--- +title: pc (Step to Next Call) +description: The pc command executes the program until a call instruction is reached. +ms.assetid: 4b9b786c-2ecc-44a6-a82b-0641d7991abc +keywords: ["pc (Step to Next Call) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pc (Step to Next Call) +api_type: +- NA +--- + +# pc (Step to Next Call) + + +The **pc** command executes the program until a call instruction is reached. + +User-Mode + +``` +[~Thread] pc [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +pc [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **pcr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **call** instructions that the debugger must encounter for this command to stop. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **pc** command causes the target to begin executing. This execution continues until a **call** instruction is reached or a breakpoint is encountered. + +If the program counter is already on a **call** instruction, the entire call is executed. After this call is returned, execution continues until another **call** is reached. This execution, rather than tracing, of the call is the only difference between **pc** and [**tc (Trace to Next Call)**](tc--trace-to-next-call-.md). + +In source mode, you can associate one source line with multiple assembly instructions. The **pc** command does not stop at a **call** instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20pc%20%28Step%20to%20Next%20Call%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pct--step-to-next-call-or-return-.md b/windows-driver-docs-pr/debugger/pct--step-to-next-call-or-return-.md new file mode 100644 index 0000000000..cb1ea707d1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/pct--step-to-next-call-or-return-.md @@ -0,0 +1,99 @@ +--- +title: pct (Step to Next Call or Return) +description: The pct command executes the program until it reaches a call instruction or a return instruction. +ms.assetid: ff4b5708-b9d0-4809-9fe4-9a22d4cacbc0 +keywords: ["pct (Step to Next Call or Return) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- pct (Step to Next Call or Return) +api_type: +- NA +--- + +# pct (Step to Next Call or Return) + + +The **pct** command executes the program until it reaches a call instruction or a return instruction. + +User-Mode + +``` +[~Thread] pct [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +pct [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display through the **pctr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **call** or **return** instructions that must be encountered for this command to stop. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **pct** command causes the target to begin executing. This execution continues until a call or **return** instruction is reached or a breakpoint is encountered. + +If the program counter is already on a **call** or **return** instruction, the entire call or return is executed. After this call or return is returned, execution continues until another **call** or **return** is reached. This execution, rather than tracing, of the call is the only difference between **pct** and [**tct (Trace to Next Call or Return)**](tct--trace-to-next-call-or-return-.md). + +In source mode, you can associate one source line with multiple assembly instructions. The **pct** command does not stop at a **call** or **return** instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20pct%20%28Step%20to%20Next%20Call%20or%20Return%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pdbcopy-command-line-options.md b/windows-driver-docs-pr/debugger/pdbcopy-command-line-options.md new file mode 100644 index 0000000000..7fa2fa9e54 --- /dev/null +++ b/windows-driver-docs-pr/debugger/pdbcopy-command-line-options.md @@ -0,0 +1,82 @@ +--- +title: PDBCopy Command-Line Options +description: The PDBCopy command line uses the following syntax. The parameters can be included in any order. +ms.assetid: a793f860-db21-41fb-a0d2-931812400f0d +keywords: ["PDBCopy Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PDBCopy Command-Line Options +api_type: +- NA +--- + +# PDBCopy Command-Line Options + + +The PDBCopy command line uses the following syntax. The parameters can be included in any order. + +``` +pdbcopy OldPDB NewPDB [Options] + +pdbcopy OldPDB NewPDB -p [-f:Symbol] [-f:@TextFile] [Options] + +pdbcopy OldPDB NewPDB -p [-F:Symbol] [-F:@TextFile] [Options] + +pdbcopy /? +``` + +## Parameters + + + *OldPDB* +Specifies the path and file name of the original symbol file to be read, including the .pdb file name extension. *OldPDB* may contain the absolute or relative path of a directory on the local computer, or a UNC path. If no path is specified, the current working directory is used. If *OldPDB* contains spaces, it must be enclosed in quotation marks. + + *NewPDB* +Specifies the path and file name of the new symbol file to be created, including the .pdb file name extension. *NewPDB* may contain the absolute or relative path of a directory on the local computer, or a UNC path. This path must already exist; PDBCopy will not create a new directory. If no path is specified, the current working directory is used. If *NewPDB* contains spaces, you must enclose it in quotation marks. The specified file should not already exist; if it does, the new file may not be written, or may be written incorrectly. + + **-p** +Causes PDBCopy to remove private symbol data from the new symbol file. If the old symbol file contains no private symbols, this option has no effect. If this option is omitted, PDBCopy creates a new file with identical symbol content as the original file. + +**-f:***Symbol* +Causes PDBCopy to remove the specified public symbol from the new symbol file. *Symbol* must specify the name of the symbol to be removed, including any symbol name decorations (for example, initial underscores), but not including the module name. This option requires the -p option. If you use multiple **-f** or **-f:@** parameters, PDBCopy removes all the specified symbols from the new symbol file. + +**-f:@***TextFile* +Causes PDBCopy to remove the public symbols listed in the specified text file from the new symbol file. *TextFile* specifies the file name and path (absolute or relative) of this file. This file can list the names of any number of symbols, one on each line, including any symbol name decorations (for example, initial underscores), but not including module names. This option requires the -p option. + +**-F:***Symbol* +Causes PDBCopy to remove all public and private symbols from the new symbol file, except for the specified public symbol. *Symbol* must specify the name of the symbol to be retained, including any symbol name decorations (for example, initial underscores), but not including the module name. This option requires the -p option. If multiple **-F** or **-F:@** parameters are used, all the specified symbols are retained in the new symbol file. + +**-F:@***TextFile* +Causes PDBCopy to remove all public and private symbols from the new symbol file, except for the public symbols listed in the specified text file. *TextFile* specifies the file name and path (absolute or relative) of this file. This file can list the names of any number of symbols, one on each line, including any symbol name decorations (for example, initial underscores), but not including module names. This option requires the -p option. + + *Options* +Any combination of the following options. These options are case-sensitive. + +**-s** +Causes the new symbol file to have a different signature than the old file. Normally you should not use the -s option, because a new signature may cause SymSrv to assign a different index value to the new file than to the old file, preventing new file from properly replacing the old one. + +**-vc6** +Causes PDBCopy to use mspdb60.dll instead of mspdb80.dll. This option is never required, because PDBCopy automatically looks for the proper version of mspdb\*.dll. By default, PDBCopy uses mspdb80.dll, which is the version used by Visual Studio .NET 2002 and later versions of Visual Studio. If your symbols were built using Visual Studio 6.0 or an earlier version, you can specify this command-line option so that PDBCopy will use mspdb60.dll instead. However, this is not required, since PDBCopy looks for the appropriate file even if this option is not used. Whichever version of mspdb\*.dll you use must be in the executable path of the Command Prompt window from which you launch PDBCopy. + + **-?** +Displays help text for the PDBCopy command line. + +### Additional Information + +For more information about the PDBCopy tool, see [Using PDBCopy](using-pdbcopy.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20PDBCopy%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pdbcopy.md b/windows-driver-docs-pr/debugger/pdbcopy.md new file mode 100644 index 0000000000..e4138db924 --- /dev/null +++ b/windows-driver-docs-pr/debugger/pdbcopy.md @@ -0,0 +1,34 @@ +--- +title: PDBCopy +description: PDBCopy +ms.assetid: 9f250b0a-597e-4ca2-8e73-306626358bc9 +keywords: ["PDBCopy", "PDBCopy, overview", "symbols, PDBCopy"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PDBCopy + + +The PDBCopy tool (pdbcopy.exe) is a command-line tool that removes private symbol information from a symbol file. It can also remove selected information from the public symbol table. + +This section includes: + +[Using PDBCopy](using-pdbcopy.md) + +[Choosing Which Public Symbols to Remove](choosing-which-public-symbols-to-remove.md) + +[**PDBCopy Command-Line Options**](pdbcopy-command-line-options.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20PDBCopy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-kd.md b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-kd.md new file mode 100644 index 0000000000..a09d575dcb --- /dev/null +++ b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-kd.md @@ -0,0 +1,115 @@ +--- +title: Live Kernel-Mode Debugging Using KD +description: Live Kernel-Mode Debugging Using KD +ms.assetid: 4C3DB315-CF92-44FC-A54C-0C100A32EB3C +--- + +# Live Kernel-Mode Debugging Using KD + + +In a Command Prompt window, you can initiate a live kernel-mode debugging session when you launch KD. Enter one of the following commands. + +**kd \[-y** *SymbolPath***\] -k net:port=***PortNumber***,key=***Key* +**kd \[-y** *SymbolPath***\] -k 1394:channel=***1394Channel***\[,symlink=***1394Protocol***\]** +**kd \[-y** *SymbolPath***\] -k usb:targetname=***USBString* +**kd \[-y** *SymbolPath***\] -k com:port=***ComPort***,baud=***BaudRate* +**kd \[-y** *SymbolPath***\] -k com:pipe,port=\\\\***VMHost***\\pipe\\***PipeName***\[,resets=0\]\[,reconnect\]** +**kd \[-y** *SymbolPath***\] -k com:***modem* +**kd \[-y** *SymbolPath***\] -kl** +**kd \[-y** *SymbolPath***\] -k** +For more information, see [**KD Command-Line Options**](kd-command-line-options.md). + +### Environment Variables + +For debugging over a serial (COM port) or 1394 connection, you can use environment variables to specify the connection settings. + +Use the following variables to specify a serial connection. + +**set \_NT\_DEBUG\_PORT =** *ComPort* +**set \_NT\_DEBUG\_BAUD\_RATE =** *BaudRate* +Use the following variables to specify a 1394 connection. + +**set \_NT\_DEBUG\_BUS = 1394** +**set \_NT\_DEBUG\_1394\_CHANNEL =** *1394Channel* **** +**set \_NT\_DEBUG\_1394\_SYMLINK =** *1394Protocol* **** +For more information, see [Kernel-Mode Environment Variables](kernel-mode-environment-variables.md). + +### Parameters + + *SymbolPath* +A list of directories where symbol files are located. Directories in the list are separated by semicolons. For more information, see [Symbol Path](symbol-path.md). + + *PortNumber* +A port number to use for network debugging. You can choose any number from 49152 through 65535. For more information, see [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md). + + *Key* +The encryption key to use for network debugging. We recommend that you use an automatically generated key, which is provided by bcdedit when you configure the target computer. For more information, see [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md). + + *1394Channel* +The 1394 channel number. Valid channel numbers are any integer between 0 and 62, inclusive. *1394Channel* must match the number used by the target computer, but does not depend on the physical 1394 port chosen on the adapter. For more information, see [Setting Up a 1394 Connection Manually](setting-up-a-1394-cable-connection.md). + + *1394Protocol* +The connection protocol to be used for the 1394 kernel connection. This can almost always be omitted, because the debugger will automatically choose the correct protocol. If you wish to set this manually, and the target computer is running Windows XP, *1394Protocol* should be set equal to "channel". If the target computer is running Windows Server 2003 or later, *1394Protocol* should be set equal to "instance". If it is omitted, the debugger will default to the protocol appropriate for the current target computer. This can only be specified through the command line or the environment variables, not through the WinDbg graphical interface. + + *USBString* +A USB connection string. This must match the string specified with the /targetname boot option. For more information, see [Setting Up a USB 3.0 Connection Manually](setting-up-a-usb-3-0-debug-cable-connection.md) and [Setting Up a USB 2.0 Connection Manually](setting-up-a-usb-2-0-debug-cable-connection.md). + + *ComPort* +The name of the COM port. This can be in the format "com2" or in the format "\\\\.\\com2", but should not simply be a number. For more information, see [Setting Up a Serial Connection Manually](setting-up-a-null-modem-cable-connection.md). + + *BaudRate* +The baud rate. This can be 9600, 19200, 38400, 57600, or 115200. + + *VMHost* +When debugging a virtual machine, *VMHost* specifies the name of the physical computer on which the virtual machine is running. If the virtual machine is running on the same computer as the kernel debugger itself, use a single period (.) for *VMHost*. For more information, see [Setting Up a Connection to a Virtual Machine](attaching-to-a-virtual-machine--kernel-mode-.md). + + *PipeName* +The name of the pipe created by the virtual machine for the debugging connection. + + **resets=0** +Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. This parameter is only needed when debugging certain kinds of virtual machines. + + **reconnect** +Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the named pipe is not found when the debugger is started, the reconnect parameter will cause it to wait for a pipe of this name to appear. This parameter is only needed when debugging certain kinds of virtual machines. + + **-kl** +Causes the debugger to perform local kernel-mode debugging. For more information, see [Local Kernel-Mode Debugging](performing-local-kernel-debugging.md). + +### Examples + +The following batch file could be used to set up and start a debugging session over a COM port connection. + +``` +set _NT_SYMBOL_PATH=d:\mysymbols +set _NT_DEBUG_PORT=com1 +set _NT_DEBUG_BAUD_RATE=115200 +set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log +kd +``` + +The following batch file could be used to set up and start a debugging session over a 1394 connection. + +``` +set _NT_SYMBOL_PATH=d:\mysymbols +set _NT_DEBUG_BUS=1394 +set _NT_DEBUG_1394_CHANNEL=44 +set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log +kd +``` + +The following command lines could be used to start WinDbg without any environment variables. + +**kd -y d:\\mysymbols -k com:port=com2,baud=57600** +**kd -y d:\\mysymbols -k com:port=\\\\.\\com2,baud=115200** +**kd -y d:\\mysymbols -k 1394:channel=20,symlink=instance** +**kd -y d:\\mysymbols -k net:port=50000,key=***AutoGeneratedKey* + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Live%20Kernel-Mode%20Debugging%20Using%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-visual-studio.md b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-visual-studio.md new file mode 100644 index 0000000000..6a0f060b06 --- /dev/null +++ b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-visual-studio.md @@ -0,0 +1,36 @@ +--- +title: Kernel-Mode Debugging in Visual Studio +description: To perform kernel-mode debugging in Microsoft Visual Studio +ms.assetid: 6E77843F-4907-4193-B987-92BD0719AE10 +keywords: ["kernel-mode debugging visual studio"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Debugging in Visual Studio + + +To perform kernel-mode debugging in Microsoft Visual Studio: + +1. On the host computer, in Visual Studio, from the **Tools** Menu, choose **Attach to Process**. +2. In the **Attach to Process** dialog box, set **Transport** to **Windows Kernel Mode Debugger**, and set **Qualifier** to the name of a previously configured target computer. For information about configuring a target computer, see [Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) or [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md). +3. Click **Attach.** + +## Related topics + + +[Debugging Using Visual Studio](debugging-using-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Kernel-Mode%20Debugging%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-windbg.md b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-windbg.md new file mode 100644 index 0000000000..06aaa24433 --- /dev/null +++ b/windows-driver-docs-pr/debugger/performing-kernel-mode-debugging-using-windbg.md @@ -0,0 +1,136 @@ +--- +title: Live Kernel-Mode Debugging Using WinDbg +description: There are two ways you can use WinDbg to initiate a live kernel-mode debugging session. +ms.assetid: CC911199-A16D-4B06-A5BE-FA476F916F21 +--- + +# Live Kernel-Mode Debugging Using WinDbg + + +There are two ways you can use WinDbg to initiate a live kernel-mode debugging session. + +## WinDbg Menu + + +When WinDbg is in dormant mode, you can begin a kernel debugging session by choosing **Kernel Debug** from the **File** menu or by pressing CTRL+K. When the **Kernel Debugging** dialog box appears, click the appropriate tab: **NET**, **1394**, **USB**, **COM**, or **Local**. Each tab specifies a different connection method. For more information about the dialog box and its entries, see [File | Kernel Debug](file---kernel-debug.md). + +## Command Prompt + + +In a Command Prompt window, you can initiate a kernel-mode debugging session when you launch WinDbg. Enter one of the following commands: + +**windbg \[-y** *SymbolPath***\] -k net:port=***PortNumber***,key=***Key* +**windbg \[-y** *SymbolPath***\] -k 1394:channel=***1394Channel***\[,symlink=***1394Protocol***\]** +**windbg \[-y** *SymbolPath***\] -k usb:targetname=***USBString* +**windbg \[-y** *SymbolPath***\] -k com:port=***ComPort***,baud=***BaudRate* +**windbg \[-y** *SymbolPath***\] -k com:pipe,port=\\\\***VMHost***\\pipe\\***PipeName***\[,resets=0\]\[,reconnect\]** +**windbg \[-y** *SymbolPath***\] -k com:***modem* +**windbg \[-y** *SymbolPath***\] -kl** +**windbg \[-y** *SymbolPath***\] -k** +For more information, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +## Environment Variables + + +For debugging over a serial (COM port) or 1394 connection, you can use environment variables to specify the connection settings. + +Use the following variables to specify a serial connection. + +**set \_NT\_DEBUG\_PORT =** *ComPort* +**set \_NT\_DEBUG\_BAUD\_RATE =** *BaudRate* +Use the following variables to specify a 1394 connection. + +**set \_NT\_DEBUG\_BUS = 1394** +**set \_NT\_DEBUG\_1394\_CHANNEL =** *1394Channel* **** +**set \_NT\_DEBUG\_1394\_SYMLINK =** *1394Protocol* **** +For more information, see [Kernel-Mode Environment Variables](kernel-mode-environment-variables.md). + +## Parameters + + + *SymbolPath* +A list of directories where symbol files are located. Directories in the list are separated by semicolons. For more information, see [Symbol Path](symbol-path.md). + + *PortNumber* +A port number to use for network debugging. You can choose any number from 49152 through 65535. For more information, see [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md). + + *Key* +The encryption key to use for network debugging. We recommend that you use an automatically generated key, which is provided by bcdedit when you configure the target computer. For more information, see [Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md). + + *1394Channel* +The 1394 channel number. Valid channel numbers are any integer between 0 and 62, inclusive. *1394Channel* must match the number used by the target computer, but does not depend on the physical 1394 port chosen on the adapter. For more information, see [Setting Up a 1394 Connection Manually](setting-up-a-1394-cable-connection.md). + + *1394Protocol* +The connection protocol to be used for the 1394 kernel connection. This can almost always be omitted, because the debugger will automatically choose the correct protocol. If you wish to set this manually, and the target computer is running Windows XP, *1394Protocol* should be set equal to "channel". If the target computer is running Windows Server 2003 or later, *1394Protocol* should be set equal to "instance". If it is omitted, the debugger will default to the protocol appropriate for the current target computer. This can only be specified through the command line or the environment variables, not through the WinDbg graphical interface. + + *USBString* +A USB connection string. This must match the string specified with the /targetname boot option. For more information, see [Setting Up a USB 3.0 Connection Manually](setting-up-a-usb-3-0-debug-cable-connection.md) and [Setting Up a USB 2.0 Connection Manually](setting-up-a-usb-2-0-debug-cable-connection.md). + + *ComPort* +The name of the COM port. This can be in the format "com2" or in the format "\\\\.\\com2", but should not simply be a number. For more information, see [Setting Up a Serial Connection Manually](setting-up-a-null-modem-cable-connection.md). + + *BaudRate* +The baud rate. This can be 9600, 19200, 38400, 57600, or 115200. + + *VMHost* +When debugging a virtual machine, *VMHost* specifies the name of the physical computer on which the virtual machine is running. If the virtual machine is running on the same computer as the kernel debugger itself, use a single period (.) for *VMHost*. For more information, see [Setting Up a Connection to a Virtual Machine](attaching-to-a-virtual-machine--kernel-mode-.md). + + *PipeName* +The name of the pipe created by the virtual machine for the debugging connection. + + **resets=0** +Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. This parameter is only needed when debugging certain kinds of virtual machines. + + **reconnect** +Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the named pipe is not found when the debugger is started, the reconnect parameter will cause it to wait for a pipe of this name to appear. This parameter is only needed when debugging certain kinds of virtual machines. + + **-kl** +Causes the debugger to perform local kernel-mode debugging. For more information, see [Local Kernel-Mode Debugging](performing-local-kernel-debugging.md). + +## Examples + + +The following batch file could be used to set up and start a debugging session over a COM port connection. + +``` +set _NT_SYMBOL_PATH=d:\mysymbols +set _NT_DEBUG_PORT=com1 +set _NT_DEBUG_BAUD_RATE=115200 +set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log +windbg -k +``` + +The following batch file could be used to set up and start a debugging session over a 1394 connection. + +``` +set _NT_SYMBOL_PATH=d:\mysymbols +set _NT_DEBUG_BUS=1394 +set _NT_DEBUG_1394_CHANNEL=44 +set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log +windbg -k +``` + +The following command lines could be used to start WinDbg without any environment variables. + +**windbg -y d:\\mysymbols -k com:port=com2,baud=57600** +**windbg -y d:\\mysymbols -k com:port=\\\\.\\com2,baud=115200** +**windbg -y d:\\mysymbols -k 1394:channel=20,symlink=instance** +**windbg -y d:\\mysymbols -k net:port=50000,key=***AutoGeneratedKey* + +## Related topics + + +[**WinDbg Command-Line Options**](windbg-command-line-options.md) + +[Kernel-Mode Environment Variables](kernel-mode-environment-variables.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Live%20Kernel-Mode%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/performing-local-kernel-debugging.md b/windows-driver-docs-pr/debugger/performing-local-kernel-debugging.md new file mode 100644 index 0000000000..3b6f1d387d --- /dev/null +++ b/windows-driver-docs-pr/debugger/performing-local-kernel-debugging.md @@ -0,0 +1,88 @@ +--- +title: Local Kernel-Mode Debugging +description: Local Kernel-Mode Debugging +ms.assetid: e66dc23b-9254-4148-9828-d27c30bfa492 +keywords: ["local kernel debugging", "local kernel debugging, commands available", "local kernel debugging, LiveKD tool", "LiveKD tool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Local Kernel-Mode Debugging + + +Debugging Tools for Windows supports *local kernel debugging*. This is kernel-mode debugging on a single computer. In other words, the debugger runs on the same computer that is being debugged. + +## Setting Up Local Kernel-Mode Debugging + + +For information on setting up local kernel-mode debugging, see [Setting Up Local Kernel-Mode Debugging of a Single Computer Manually](setting-up-local-kernel-debugging-of-a-single-computer-manually.md). + +## Starting the Debugging Session + + +### Using WinDbg + +Open WinDbg as Administrator. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **Local** tab. Click **OK**. + +You can also start a session with WinDbg by opening a Command Prompt window as Administrator and entering the following command: + +**windbg -kl** + +### Using KD + +Open a Command Prompt window as Administrator, and enter the following command: + +**kd -kl** + +## Commands That Are Not Available + + +Not all commands are available in a local kernel debugging session. Typically, you cannot use any command that causes the target computer to stop, even momentarily, because you cannot resume operation. + +In particular, you cannot use the following commands: + +- Execution commands, such as **g (Go)**, **p (Step)**, **t (Trace)**, **wt (Trace and Watch Data)**, **tb (Trace to Next Branch)**, **gh (Go with Exception Handled)**, and **gn (Go with Exception Not Handled)** + +- Shutdown and dump file commands, such as **.crash**, **.dump**, and **.reboot** + +- Breakpoint commands, such as **bp**, **bu**, **ba**, **bc**, **bd**, **be**, and **bl** + +- Register display commands, such as **r** and variations + +- Stack trace commands, such as **k** and variations + +If you are performing local kernel debugging with WinDbg, all of the equivalent menu commands and buttons are also unavailable. + +## Commands That Are Available + + +All memory input and output commands are available. You can freely read from user memory and kernel memory. You can also write to memory. Make sure that you do not write to the wrong part of kernel memory, because it can corrupt data structures and frequently causes the computer to stop responding (that is, *crash*). + +## Difficulties in Performing Local Kernel Debugging + + +Local kernel debugging is a very delicate operation. Be careful that you do not corrupt or crash the system. + +One of the most difficult aspects of local kernel debugging is that the machine state is constantly changing. Memory is paged in and out, the active process constantly changes, and virtual address contexts do not remain constant. However, under these conditions, you can effectively analyze things that change slowly, such as certain device states. + +Kernel-mode drivers and the Windows operating system frequently send messages to the kernel debugger by using **DbgPrint** and related functions. These messages are not automatically displayed during local kernel debugging. You can display them by using the [**!dbgprint**](-dbgprint.md) extension. + +## LiveKD + + +The LiveKD tool simulates local kernel debugging. This tool creates a "snapshot" dump file of the kernel memory, without actually stopping the kernel while this snapshot is made. (Therefore, the snapshot might not actually show a single instant state of the computer.) + +LiveKD is not part of the Debugging Tools for Windows package. You can download [LiveKd](http://go.microsoft.com/fwlink/p/?linkid=56552) from the Windows Sysinternals site. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Local%20Kernel-Mode%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ph--step-to-next-branching-instruction-.md b/windows-driver-docs-pr/debugger/ph--step-to-next-branching-instruction-.md new file mode 100644 index 0000000000..fbd69fe944 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ph--step-to-next-branching-instruction-.md @@ -0,0 +1,99 @@ +--- +title: ph (Step to Next Branching Instruction) +description: The ph command executes the program until any kind of branching instruction is reached, including conditional or unconditional branches, calls, returns, and system calls. +ms.assetid: ba4699d3-9872-4deb-96c7-e8b54c1d8ec6 +keywords: ["ph (Step to Next Branching Instruction) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ph (Step to Next Branching Instruction) +api_type: +- NA +--- + +# ph (Step to Next Branching Instruction) + + +The **ph** command executes the program until any kind of branching instruction is reached, including conditional or unconditional branches, calls, returns, and system calls. + +User-Mode + +``` +[~Thread] ph [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +ph [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **phr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of branching instructions that must be encountered for this command to stop. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **ph** command causes the target to begin executing. This execution continues until a branching instruction is reached or a breakpoint is encountered. + +If the program counter is already on a branching instruction, the entire branching instruction is executed. After this branching instruction is returned, execution continues until another branching instruction is reached. This execution, rather than tracing, of the call is the only difference between **ph** and [**th (Trace to Next Branching Instruction)**](th--trace-to-next-branching-instruction-.md). + +In source mode, you can associate one source line with multiple assembly instructions. The **ph** command does not stop at a branching instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ph%20%28Step%20to%20Next%20Branching%20Instruction%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/plmdebug.md b/windows-driver-docs-pr/debugger/plmdebug.md new file mode 100644 index 0000000000..3713a30e7e --- /dev/null +++ b/windows-driver-docs-pr/debugger/plmdebug.md @@ -0,0 +1,180 @@ +--- +title: PLMDebug +description: PLMDebug.exe is a tool that enables you to use the Windows debugger to debug Windows app, which run under Process Lifecycle Management (PLM). +ms.assetid: 68BE8F5D-6425-43E2-B5BC-C1D35614AB32 +keywords: ["PLMDebug Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- PLMDebug +api_type: +- NA +--- + +# PLMDebug + + +PLMDebug.exe is a tool that enables you to use the Windows debugger to debug Windows app, which run under Process Lifecycle Management (PLM). With PLMDebug, you can take manual control of suspending, resuming, and terminating a Windows app. + +**Tip**  With Windows 10, version 1607 or later, you can use the UWP commands, such as .createpackageapp to debug UWP apps. For more information see [Debugging a UWP app using WinDbg](debugging-a-uwp-app-using-windbg.md). + +  + +**Where to get PLMDebug** + +PLMDebug.exe is included in [Debugging Tools for Windows](index.md). + +``` +plmdebug /query [Package] +plmdebug /enableDebug Package [DebuggerCommandLine] +plmdebug /terminate Package +plmdebug /forceterminate Package +plmdebug /cleanterminate Package +plmdebug /suspend Package +plmdebug /resume Package +plmdebug /disableDebug Package +plmdebug /enumerateBgTasks Package +plmdebug /activateBgTaskTaskId +``` + +## Parameters + + + *Package* +The full name of a package or the ID of a running process. + + *DebuggerCommandLine* +A command line to open a debugger. The command line must include the full path to the debugger. If the path has blank spaces, it must be enclosed in quotes. The command line can also include arguments. Here are some examples: + +`"C:\Program Files (x86)\Windows Kits\8.0\Debuggers\x64\WinDbg.exe"` + +`"\"C:\Program Files\Debugging Tools for Windows (x64)\WinDbg.exe\" -server npipe:pipe=test"` + + **/query** \[*Package*\] +Displays the running state for an installed package. If *Package* is not specified, this command displays the running states for all installed packages. + + **/enableDebug** *Package* \[*DebuggerCommandLine*\] +Increments the debug reference count for a package. The package is exempt from PLM policy if it has a non-zero debug reference count. Each call to **/enableDebug** must be paired with a call to /**disableDebug**. If you specify *DebuggerCommandLine*, the debugger will attach when any app from the package is launched. + + **/terminate** *Package* +Terminates a package. + + **/forceTerminate** *Package* +Forces termination of a package. + + **/cleanTerminate** *Package* +Suspends and then terminates a package. + + **/suspend** *Package* +Suspends a package. + + **/resume** *Package* +Resumes a package. + + **/disableDebug** *Package* +Decrements the debug reference count for a package. + + **/enumerateBgTasks***Package* +Enumerate background task ids for a package. + + **/activateBgTask***TaskId* +Activates a background task. Note that not all background tasks can be activated using PLMDebug. + +Remarks +------- + +You must call **plmdebug /enableDebug** before you call any of the suspend, resume, or terminate functions. + +The PLMDebug tool calls the methods of the [IPackageDebugSettings interface](http://go.microsoft.com/fwlink/p/?LinkID=267918). This interface enables you to take manual control of the process lifecycle management for your apps. Through this interface (and as a result, through this tool), you can suspend, resume, and terminate your Windows app. Note that the methods of the [IPackageDebugSettings interface](http://go.microsoft.com/fwlink/p/?LinkID=267918) apply to an entire package. Suspend, resume, and terminate affect all currently running apps in the package. + +Examples +-------- + +**Example 1** + +**Attach a debugger when your app is launched** + +Suppose you have an app named MyApp that is in a package named MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c. Verify that your package is installed by displaying the full names and running states all installed packages. In a Command Prompt window, enter the following command. + +**plmdebug /query** + +``` +Package full name: 1daa103b-74e1-426d-8193-b6bc7ed66fed_1.0.0.0_x86__tnq5r49etfg3c +Package state: Terminated + +Package full name: 41fb5f27-7b60-4f5e-8459-803673131dd9_1.0.0.0_x86__tnq5r49etfg3c +Package state: Suspended +... +Package full name: MyApp_1.0.0.0_x64__tnq5r49etfg3c +Package state: Terminated +... +``` + +Increment the debug reference count for your package, and specify that you want WinDbg to attach when your app is launched. + +**plmdebug /enableDebug MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c "C:\\Program Files (x86)\\Windows Kits\\8.0\\Debuggers\\x64\\WinDbg.exe"** + +When you launch your app, WinDbg will attach and break in. + +When you have finished debugging, detach the debugger. Then decrement the debug reference count for your package. + +**plmdebug /disableDebug MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c** + +**Example 2** + +**Attach a debugger to an app that is already running** + +Suppose you want to attach WinDbg to MyApp, which is already running. In WinDbg, on the **File** menu, choose **Attach to a Process**. Note the process ID for MyApp. Let's say the process ID is 4816. + +Increment the debug reference count for the package that contains MyApp. + +**plmdebug /enableDebug 4816** + +In WinDbg, in the **Attach to Process** dialog box, select process 4816, and click **OK**. WinDbg will attach to MyApp. + +When you have finished debugging MyApp, detach the debugger. Then decrement the debug reference count for the package. + +**plmdebug /disableDebug 4816** + +**Example 3** + +**Manually suspend and resume your app** + +Suppose you want to manually suspend and resume your app. First, increment the debug reference count for the package that contains your app. + +**plmdebug /enableDebug MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c** + +Suspend the package. Your app's suspend handler is called, which can be helpful for debugging. + +**plmdebug /suspend MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c** + +When you have finished debugging, resume the package. + +**plmdebug /resume MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c** + +Finally, decrement the debug reference count for the package. + +**plmdebug /disableDebug MyApp\_1.0.0.0\_x64\_\_tnq5r49etfg3c** + +## See also + + +[How to trigger suspend, resume, and background events in Windows Apps](http://go.microsoft.com/fwlink/p/?LinkID=267916) + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20PLMDebug%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/plug-and-play-and-power-debugger-commands.md b/windows-driver-docs-pr/debugger/plug-and-play-and-power-debugger-commands.md new file mode 100644 index 0000000000..73cbb65a2f --- /dev/null +++ b/windows-driver-docs-pr/debugger/plug-and-play-and-power-debugger-commands.md @@ -0,0 +1,24 @@ +--- +title: Debugging Plug and Play and Power Issues +description: The following extensions are useful for debugging Plug and Play and power issues. +ms.assetid: 2F047A62-F27C-4650-9081-F8BFA7525A02 +--- + +# Debugging Plug and Play and Power Issues + + +The following extensions are useful for debugging Plug and Play and power issues. + +- [**!pnpevent**](-pnpevent.md) +- [**!pocaps**](-pocaps.md) +- [**!popolicy**](-popolicy.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Plug%20and%20Play%20and%20Power%20Issues%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/plug-and-play-debugging.md b/windows-driver-docs-pr/debugger/plug-and-play-debugging.md new file mode 100644 index 0000000000..5c8d8d8d18 --- /dev/null +++ b/windows-driver-docs-pr/debugger/plug-and-play-debugging.md @@ -0,0 +1,39 @@ +--- +title: Plug and Play Debugging +description: This topic describes Plug and Play Debugging +ms.assetid: 59023a95-5eeb-4a5d-9239-a28459c70f42 +keywords: Plug and Play, PnP, drivers, debugging +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Plug and Play Debugging + + +## + + +This section includes: + +[Extensions for Debugging Plug and Play Drivers](extensions-for-debugging-plug-and-play-drivers.md) + +[Determining the Status of a Device](determining-the-status-of-a-device.md) + +[Device Node Status Flags](device-node-status-flags.md) + +[Device Manager Problem Codes](important-breakpoints-for-analyzing-reproducible-problems.md) + +[Checking for Resource Conflicts](checking-for-resource-conflicts.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Plug%20and%20Play%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/positioning-the-windows.md b/windows-driver-docs-pr/debugger/positioning-the-windows.md new file mode 100644 index 0000000000..34ea75e9f5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/positioning-the-windows.md @@ -0,0 +1,47 @@ +--- +title: Positioning the Windows +description: Positioning the Windows +ms.assetid: 18c0ba52-ed47-4d93-a9d3-c0b5c9c26489 +keywords: ["debugging information windows, positioning", "floating windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Positioning the Windows + + +## + + +Each debugging information window can be *floating* or *docked*. + +You can position *floating windows* separately from other windows. *Docked windows* are connected to the WinDbg window or to an independent dock. Each docked window can occupy a unique position in its dock or can be combined with other docked windows in a *tabbed collection*. + +This section includes the following topics: + +[Debugging with Floating and Docked Windows](debugging-with-floating-and-docked-windows.md) + +[Docking a Window](docking-a-window.md) + +[Tabbing a Window](tabbing-a-window.md) + +[Undocking a Window](undocking-a-window.md) + +[Creating a New Dock](creating-a-new-dock.md) + +[Resizing and Moving Windows](resizing-and-moving-a-window.md) + +[Arranging Windows](arranging-windows.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Positioning%20the%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/preparing-for-ndis-debugging.md b/windows-driver-docs-pr/debugger/preparing-for-ndis-debugging.md new file mode 100644 index 0000000000..44f1a3865c --- /dev/null +++ b/windows-driver-docs-pr/debugger/preparing-for-ndis-debugging.md @@ -0,0 +1,28 @@ +--- +title: Preparing for NDIS Debugging +description: Preparing for NDIS Debugging +ms.assetid: 9a23cc3a-5940-46c3-928f-7fac46dfaba2 +keywords: ["NDIS debugging, setup"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Preparing for NDIS Debugging + + +To debug NDIS components, a checked version of Ndis.sys is required on the target computer. However, instead of installing an entire checked-build operating system, you can copy the checked version of Ndis.sys onto an otherwise free-build operating system. Before you copy the checked version of Ndis.sys to the target computer, you must disable Windows File Protection (WFP). To ensure that WFP is disabled, start the operating system in safe mode. + +The NDIS symbols are publicly available on the Microsoft symbol store. For details on how to access this, see [Microsoft Public Symbols](microsoft-public-symbols.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Preparing%20for%20NDIS%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/preparing-to-debug-the-service-application.md b/windows-driver-docs-pr/debugger/preparing-to-debug-the-service-application.md new file mode 100644 index 0000000000..cd0e5121bd --- /dev/null +++ b/windows-driver-docs-pr/debugger/preparing-to-debug-the-service-application.md @@ -0,0 +1,266 @@ +--- +title: Preparing to Debug the Service Application +description: Preparing to Debug the Service Application +ms.assetid: 332b7bcf-22e4-4b98-bcb3-3646f8bd63fd +--- + +# Preparing to Debug the Service Application + + +This topic lists all the preparatory steps that may be required prior to debugging a service application. Which steps are required in your scenario depends on which attach option you have chosen and which debugging configuration you have chosen. For a list of these choices, see [Choosing the Best Method](choosing-the-best-method.md). + +Each of the preparatory steps described in this topic specifies the conditions under which it is required. These steps can be done in any order. + +### Enabling the Debugging of the Initialization Code + +If you plan to debug the service application from the beginning of its execution, including its initialization code, this preparatory step is required. + +Locate or create the following registry key, where *ProgramName* is the name of the service application's executable file: + +``` +HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ProgramName +``` + +*ProgramName* should include the file name extension, but not the path. For example, *ProgramName* might be Myservice.exe or Thisservice.dll. + +Under this registry key, create a string data value entitled **Debugger**. The value of this string should be set to the full path and file name of a debugger to be attached to the service application. + +- If you plan to debug locally, use a string such as the following: + + ``` + c:\Debuggers\windbg.exe + ``` + + Do not choose this option if you are running Windows Vista or a later version of Windows. + +- If you plan to use remote debugging, specify NTSD with the -noio option. This causes NTSD to run without any console of its own, accessible only through the remote connection. For example: + + ``` + c:\Debuggers\ntsd.exe -server ServerTransport -noio -y SymbolPath + ``` + + If your debugging session begins before Windows is fully loaded, you may not be able to access symbols from a remote share; in such a case, you must use local symbols. *ServerTransport* must specify a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or NPIPE. For the syntax of *ServerTransport*, see [**Activating a Debugging Server**](activating-a-debugging-server.md). + +- If you plan to control the user-mode debugger from a kernel-mode debugger, specify NTSD with the -d option. For example: + + ``` + c:\Debuggers\ntsd.exe -d -y SymbolPath + ``` + + If you plan to use this method and your user-mode symbols will be accessed from a symbol server, you should combine this method with remote debugging. In this case, specify NTSD with the -ddefer option. Choose a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or NPIPE. For example: + + ``` + c:\Debuggers\ntsd.exe -server ServerTransport -ddefer -y SymbolPath + ``` + + For details, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +After this registry edit is complete, the debugger is launched whenever a service with this name is started or restarted. + +### Enabling the Service Application to Break Into the Debugger + +If you want the service application to break into the debugger when it crashes or encounters an exception, this preparatory step is required. This step is also required if you want the service application to break into the debugger by calling the **DebugBreak** function. + +**Note**   If you have enabled debugging of the initialization code (the step described in the subsection "Enabling the Debugging of the Initialization Code"), you should skip this step. When initialization code debugging is enabled, the debugger attaches to the service application when it starts, which causes all crashes, exceptions, and calls to **DebugBreak** to be routed to the debugger without additional preparations being needed. + +  + +This preparatory step involves registering the chosen debugger as the postmortem debugger. This is done by using the -iae or -iaec options on the debugger command line. We recommend the following commands, but if you want to vary them, see the syntax details in [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +- If you plan to debug locally, use a command such as the following: + + ``` + windbg -iae + ``` + + Do not choose this option if you are running Windows Vista or a later version of Windows. + +- If you plan to use remote debugging, specify NTSD with the -noio option. This causes NTSD to run without any console of its own, accessible only through the remote connection. To install a postmortem debugger that includes the -server parameter, you must manually edit the registry; for details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). For example, the **Debugger** value of the **AeDebug** key could be the following: + + ``` + ntsd -server npipe:pipe=myproc%x -noio -p %ld -e %ld -g -y SymbolPath + ``` + + In the pipe specification, the **%x** token is replaced with the process ID of the process that launches the debugger. This guarantees that if more than one process launches a postmortem debugger, each has a unique pipe name. If your debugging session begins before Windows is fully loaded, you may not be able to access symbols from a remote share; in such a case, you must use local symbols. *ServerTransport* must specify a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or NPIPE. For the syntax of *ServerTransport*, see [**Activating a Debugging Server**](activating-a-debugging-server.md). + +- If you plan to control the user-mode debugger from a kernel-mode debugger, specify NTSD with the -d option. For example: + + ``` + ntsd -iaec -d -y SymbolPath + ``` + + If you choose this method and intend to access user-mode symbols from a symbol server, you should combine this method with remote debugging. In this case, specify NTSD with the -ddefer option. Choose a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or NPIPE. To install a postmortem debugger that includes the -server parameter, you must manually edit the registry; for details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). For example, the **Debugger** value of the **AeDebug** key could be the following: + + ``` + ntsd -server npipe:pipe=myproc%x -ddefer -p %ld -e %ld -g -y SymbolPath + ``` + + For details, see [Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md). + +When you issue one of these commands, the postmortem debugger is registered. This debugger will be launched whenever any user-mode program, including a service application, encounters an exception or runs a **DebugBreak** function. + +### Adjusting the Service Application Timeout + +If you plan to launch the debugger automatically (either when the service starts or when it encounters an exception), this preparatory step is required. + +Locate the following registry key: + +``` +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control +``` + +Under this key, locate or create a DWORD data value called **ServicesPipeTimeout**. Set this entry to the amount of time in milliseconds that you want the service to wait before timing out. For example, a value of 60,000 is one minute, while a value of 86,400,000 is 24 hours. When this registry value is not set, the default timeout is about thirty seconds. + +The significance of this value is that a clock starts to run when each service is launched, and when the timeout value is reached, any debugger attached to the service is terminated. Therefore, the value you choose should be longer than the total amount of time that elapses between the launching of the service and the completion of your debugging session. + +This setting applies to every service that is started or restarted after the registry edit is complete. If some service crashes or hangs and this setting is still in effect, the problem is not detected by Windows. Therefore, you should use this setting only while you are debugging, and return the registry key to its original value after your debugging is complete. + +### Isolating the Service + +Sometimes, multiple services are combined in a single Service Host (Svchost) process. If you want to debug such a service, you must first isolate it into a separate Svchost process. + +There are three methods by which you can isolate a service. Microsoft recommends the Moving the Service to its Own Group method, as follows. The alternative methods (Changing the Service Type and Duplicating the SvcHost Binary) can be used on a temporary basis for debugging, but because they alter the way the service runs, they are not as reliable as the first method. + +**Preferred Method: Moving the Service to its Own Group** + +1. Issue the following Service Configuration tool (Sc.exe) command, where *ServiceName* is the name of the service: + + ``` + sc qc ServiceName + ``` + + This displays the current configuration values for the service. The value of interest is BINARY\_PATH\_NAME, which specifies the command line used to launch the service control program. In this scenario, because your service is not yet isolated, this command line includes a directory path, Svchost.exe, and some SvcHost parameters, including the -k switch, followed by a group name. For example, it may look something like this: + + ``` + %SystemRoot%\System32\svchost.exe -k LocalServiceNoNetwork + ``` + + Remember this path and the group name; they are used in steps 5 and 6. + +2. Locate the following registry key: + + ``` + HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost + ``` + + Create a new REG\_MULTI\_SZ value with a unique name (for example, **TempGrp**). + +3. Set this new value equal to the name of the service that you want to isolate. Do not include any directory path or file name extension. For example, you might set the new value **TempGrp** equal to **MyService**. + +4. Under the same registry key, create a new key with the same name you used in step 2. For example: + + ``` + HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\TempGrp + ``` + + Now the SvcHost key contains a value with the new name and also has a subordinate key with this same name. + +5. Look for another key subordinate to the SvcHost key that has the same name as the group you found in step 1. If such a key exists, examine all the values in it, and create duplicates of them in the new key you created in step 4. + + For example, the old key might be named this: + + ``` + HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\LocalServiceNoNetwork + ``` + + and it might contain values such as **CoInitializeSecurityParam**, **AuthenticationCapabilities**, and other values. You would go to the newly created key: + + ``` + HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\TempGrp + ``` + + and create values in it that are identical in name, type, and data to those in the old key. + + If the old key does not exist, you do not need to create a new key. + +6. Use the following Service Configuration tool command to revise the path found in step 1: + + ``` + sc config ServiceName binPath= "RevisedPath" + ``` + + In this command, *ServiceName* is the name of the service, and *RevisedPath* is the new value you are supplying for BINARY\_PATH\_NAME. For *RevisedPath*, use the exact same path as the one displayed in step 1, including all the options shown on that line, making only one change: replace the parameter following the -k switch with the name of the new registry value you created in step 2. Enclose *RevisedPath* in quotation marks. The space after the equal sign is required. + + For example, your command might look like this: + + ``` + sc config MyService binPath= "%SystemRoot%\System32\svchost.exe -k TempGrp" + ``` + + You may want to use the **sc qc** command again to review the change you have made. + +These settings will take effect the next time the service is started. To clear the effects of the old service, we recommend that you restart Windows rather than just restarting the service. + +After you have completed your debugging, if you want to return this service to the shared service host, use the **sc config** command again to return the binary path to its original value, and delete the new registry keys and values you created.. + +**Alternative Method: Changing the Service Type** + +1. Issue the following Service Configuration tool (Sc.exe) command, where *ServiceName* is the name of the service: + + ``` + sc config ServiceName type= own + ``` + + The space after the equal sign is required. + +2. Restart the service, by using the following commands: + ``` + net stop ServiceName + net start ServiceName + ``` + +This alternative is not the recommended method because it can alter the behavior of the service. If you do use this method, use the following command to revert to the normal behavior after you have completed your debugging: + +``` +sc config ServiceName type= share +``` + +**Alternative Method: Duplicating the SvcHost Binary** + +1. The Svchost.exe executable file is located in the system32 directory of Windows. Make a copy of this file, name it svhost2.exe, and place it in the system32 directory as well. + +2. Issue the following Service Configuration tool (Sc.exe) command, where *ServiceName* is the name of the service: + + ``` + sc qc ServiceName + ``` + + This command displays the current configuration values for the service. The value of interest is BINARY\_PATH\_NAME, which specifies the command line used to launch the service control program. In this scenario, because your service is not yet isolated, this command line will include a directory path, Svchost.exe, and probably some SvcHost parameters. For example, it may look something like this: + + ``` + %SystemRoot%\System32\svchost.exe -k LocalServiceNoNetwork + ``` + +3. To revise this path, issue the following command: + + ``` + sc config ServiceName binPath= "RevisedPath" + ``` + + In this command, *ServiceName* is the name of the service, and *RevisedPath* is the new value you are supplying for BINARY\_PATH\_NAME. For *RevisedPath*, use the exact same path as the one displayed in step 2, including all the options shown on that line, making only one change: replace Svchost.exe with Svchost2.exe. Enclose *RevisedPath* in quotation marks. The space after the equal sign is required. + + For example, your command might look like this: + + ``` + sc config MyService binPath= "%SystemRoot%\System32\svchost2.exe -k LocalServiceNoNetwork" + ``` + + You can use the **sc qc** command again to review the change you have made. + +4. Restart the service by using the following commands: + ``` + net stop ServiceName + net start ServiceName + ``` + +This alternative is not the recommended method because it can alter the behavior of the service. If you do use this method, use the **sc config** command to change the path back to its original value after you have completed your debugging. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Preparing%20to%20Debug%20the%20Service%20Application%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/preparing-to-use-umdh.md b/windows-driver-docs-pr/debugger/preparing-to-use-umdh.md new file mode 100644 index 0000000000..b9cd962832 --- /dev/null +++ b/windows-driver-docs-pr/debugger/preparing-to-use-umdh.md @@ -0,0 +1,87 @@ +--- +title: Preparing to Use UMDH +description: Preparing to Use UMDH +ms.assetid: 9adebe43-3167-4e1a-ac98-db19ace944be +keywords: ["UMDH, preparing to use UMDH", "UMDH, disabling BSTR caching", "SetNoOaCache function", "OANOCACHE environment variable", "stack trace database"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Preparing to Use UMDH + + +## + + +You must complete the configuration tasks described in this section before using User-Mode Dump Heap (UMDH) to capture the heap allocations for a process. If the computer is not configured correctly, UMDH will not generate any results or the results will be incomplete or incorrect. + +### Create the user-mode stack trace database + +Before using UMDH to capture the heap allocations for a process, you must configure Windows to capture stack traces. + +To enable stack trace capturing for a process, use [GFlags](gflags.md) to set the **Create user mode stack trace database** flag for the process. This can be done by either of the following methods: + +- In the GFlags graphical interface, choose the **Image File** tab. Type the process name, including the file name extension (for example, Notepad.exe). Press the **TAB** key, select **Create user mode stack trace database**, and then click **Apply**. + +- Or, equivalently, use the following GFlags command line, where *ImageName* is the process name (including the file name extension): + + **gflags /i** *ImageName* **+ust** + +By default, the amount of stack trace data that Windows gathers is limited to 32 MB on an x86 processor, and 64 MB on an x64 processor. If you must increase the size of this database, choose the **Image File** tab in the GFlags graphical interface, type the process name, press the **TAB** key, check the **Stack Backtrace (Megs)** check box, type a value (in MB) in the associated text box, and then click **Apply**. + +**Note**   Increase this database only when necessary, because it may deplete limited Windows resources. When you no longer need the larger size, return this setting to its original value. + +  + +These settings affects all new instances of the program. It does not affect currently running instances of the program. + +### Access the Necessary Symbols + +Before using UMDH, you must have access to the proper symbols for your application. UMDH uses the symbol path specified by the environment variable \_NT\_SYMBOL\_PATH. Set this variable equal to a path containing the symbols for your application. + +If you also include a path to Windows symbols, the analysis may be more complete. The syntax for this symbol path is the same as that used by the debugger; for details, see [Symbol Path](symbol-path.md). + +For example, if the symbols for your application are located at C:\\MyApp\\Symbols, and you have installed the Windows symbol files to \\\\myshare\\winsymbols, you would use the following command to set your symbol path: + +``` +set _NT_SYMBOL_PATH=c:\myapp\symbols;\\myshare\winsymbols +``` + +As another example, if the symbols for your application are located at C:\\MyApp\\Symbols, and you want to use the public Microsoft symbol store for your Windows symbols, using C:\\MyCache as your downstream store, you would use the following command to set your symbol path: + +``` +set _NT_SYMBOL_PATH=c:\myapp\symbols;srv*c:\mycache*https://msdl.microsoft.com/download/symbols +``` + +**Important**  Suppose you have two computers: a *logging computer* where you create a UMDH log and an *analysis computer* where you analyze the UMDH log. The symbol path on your analysis computer must point to the symbols for the version of Windows that was loaded on the logging computer at the time the log was made. Do not point the symbol path on the analysis computer to a symbol server. If you do, UMDH will retrieve symbols for the version of Windows that is running on the analysis computer, and UMDH will not display meaningful results. + +  + +### Disable BSTR Caching + +Automation (formerly known as OLE Automation) caches the memory used by BSTR strings. This can prevent UMDH from correctly determining the owner of a memory allocation. To avoid this problem, you must disable BSTR caching. + +To disable BSTR caching, set the OANOCACHE environment variable equal to one (1). This setting must be made before launching the application whose allocations are to be traced. + +Alternatively, you can disable BSTR caching from within the application itself by calling the .NET Framework **SetNoOaCache** function. If you choose this method, you should call this function early, because any BSTR allocations that have already been cached when **SetNoOaCache** is called will remain cached. + +If you need to trace the allocations made by a service, you must set OANOCACHE as a system environment variable and then restart Windows for this setting to take effect. + +On Windows 2000, in addition to setting OANOCACHE equal to 1, you must also install the hotfix available with [Microsoft Support Article 139071](http://go.microsoft.com/fwlink/p/?LinkId=241583). This hotfix is not needed on Windows XP and later versions of Windows. + +### Find the Process ID + +UMDH identifies the process by its process identifier (PID). You can find the PID of any running process by using Task Manager, Tasklist (Windows XP and later operating systems), or [TList](tlist.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Preparing%20to%20Use%20UMDH%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/process-server-examples.md b/windows-driver-docs-pr/debugger/process-server-examples.md new file mode 100644 index 0000000000..addffddc40 --- /dev/null +++ b/windows-driver-docs-pr/debugger/process-server-examples.md @@ -0,0 +1,72 @@ +--- +title: Process Server Examples +description: Process Server Examples +ms.assetid: f87e6ff5-05a4-4dae-8151-913ea469b4ec +keywords: ["process server, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Process Server Examples + + +## + + +Suppose one person is running an application on a computer named \\\\BOX17. This application has problems, but the debugging technician is at a different site. + +The first person sets up a process server using DbgSrv on \\\\BOX17. The target application has a process ID of 122. TCP protocol is chosen, with a socket port number of 1025. The server is started with the following command: + +``` +E:\Debugging Tools for Windows> dbgsrv -t tcp:port=1025 +``` + +On the other computer, the technician starts WinDbg as a smart client with this command: + +``` +G:\Debugging Tools> windbg -premote tcp:server=BOX17,port=1025 -p 122 +``` + +Here is another example. In this case, NPIPE protocol is chosen, and CDB is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric string -- in this example, "AnotherPipe". The first user opens an elevated Command Prompt window (Run as Administrator) and starts a debugging server by entering this command: + +``` +E:\Debugging Tools for Windows> dbgsrv -t npipe:pipe=AnotherPipe +``` + +The technician is logged on to the client computer with an account that does not have access to the server computer. But the technician knows the username and password for an account that does have access to the server computer. The username for that account is Contoso. The technician enters the following command: + +``` +net use \\BOX17\ipc$ /user:Contoso +``` + +When prompted, the technician enters the password for the Contoso account. + +The technician is not sure what name was used for the named pipe, so she queries BOX17 for process servers: + +``` +G:\Debugging Tools> cdb -QR \\BOX17 +Servers on \\BOX17: +Debugger Server - npipe:Pipe=MainPipe +Remote Process Server - npipe:Pipe=AnotherPipe +``` + +Two pipes are shown. However, only one is a process server -- the other is a debugging server, and we are not interested in that. So **AnotherPipe** must be the correct name. The technician enters the following command to start the smart client: + +``` +G:\Debugging Tools> cdb -premote npipe:server=BOX17,pipe=AnotherPipe -v sol.exe +``` + +For a more complicated example using a process server, see [Symbols in the Middle](symbols-in-the-middle.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Process%20Server%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/process-servers--user-mode-.md b/windows-driver-docs-pr/debugger/process-servers--user-mode-.md new file mode 100644 index 0000000000..0576967bd9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/process-servers--user-mode-.md @@ -0,0 +1,44 @@ +--- +title: Process Servers (User Mode) +description: Process Servers (User Mode) +ms.assetid: 9391fcd4-c64f-4c2b-89c2-da09be7646d1 +keywords: ["remote debugging through a process server", "process server", "process server, overview", "smart client (user mode)", "DbgSrv", "DbgSrv, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Process Servers (User Mode) + + +## + + +Remote debugging through a process server involves running a small application called a *process server* on the server computer. Then a user-mode debugger is started on the client computer. Since this debugger will be doing all of the actual processing, it is called the *smart client*. + +The Debugging Tools for Windows package includes a process server called DbgSrv (dbgsrv.exe) for use in user mode. + +The two computers do not have to be running the same version of Windows; they can be running any version of Windows. However, the debugger binaries used on the client and the DbgSrv binary used on the server must be from the same release of the Debugging Tools for Windows package. This method cannot be used for dump-file debugging. + +To set up this remote session, the process server is set up first, and then the smart client is activated. Any number of smart clients can operate through a single process server -- these debugging sessions will remain separate and will not interfere with each other. If a debugging session is ended, the process server will continue to run and can be used for new debugging sessions. + +## In this section + + +- [**Activating a Process Server**](activating-a-process-server.md) +- [**Searching for Process Servers**](searching-for-process-servers.md) +- [**Activating a Smart Client**](activating-a-smart-client.md) +- [Process Server Examples](process-server-examples.md) +- [Controlling a Process Server Session](controlling-a-process-server-session.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Process%20Servers%20%28User%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/process-syntax.md b/windows-driver-docs-pr/debugger/process-syntax.md new file mode 100644 index 0000000000..3f62a94d14 --- /dev/null +++ b/windows-driver-docs-pr/debugger/process-syntax.md @@ -0,0 +1,84 @@ +--- +title: Process Syntax +description: Process Syntax +ms.assetid: fe08b5fe-ec27-4264-baee-de4c11bcb2bf +keywords: ["process, command syntax", "(process identifier)", "process, process identifier ( )", "process, process ID (PID)", "PID (process ID)", "(process identifier)", "syntax rules for commands, (process identifier)", "syntax rules for commands, (process identifier)", "process identifier ( )"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Process Syntax + + +## + + +Many debugger commands have process identifiers as their parameters. A vertical bar ( | ) appears before the process identifier. + +The process identifier can be one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Process identifierDescription

|.

The current process.

|#

The process that caused the current exception or debug event.

|*

All processes.

|Number

The process whose ordinal is Number.

|~[PID]

The process whose process ID is PID. (The brackets are required and you cannot add a space between the tilde (~) and the opening bracket.)

|[Expression]

The process whose process ID is the integer to which the numerical Expression resolves.

+ +  + +Processes are assigned ordinals as they are created. Note that this number differs from the process ID (PID) that the Microsoft Windows operating system uses. + +The current process defines the memory space and the set of threads that are used. When debugging begins, the current process is the one that caused the present exception or debug event (or the process that the debugger attached to). That process remains the current process until you specify a new one by using a [**|s (Set Current Process)**](-s--set-current-process-.md) command or by using the [Processes and Threads window](processes-and-threads-window.md) in WinDbg. + +Process identifiers are used as parameters in several commands, frequently as the command prefix. Note that WinDbg and CDB can debug child processes that the original process created. WinDbg and CDB can also attach to multiple unrelated processes. + +An example of the |\[*Expression*\] syntax would be \[|@$t0\]. In this example, the process changes depending on the value of a user-defined pseudo-register. This syntax allows debugger scripts to programmatically select a process. + +### Controlling Processes in Kernel Mode + +In kernel mode, you cannot control processes by using process identifiers. For more information about how to access process-specific information in kernel mode, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Process%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/processes-and-threads-window.md b/windows-driver-docs-pr/debugger/processes-and-threads-window.md new file mode 100644 index 0000000000..c4874ee23d --- /dev/null +++ b/windows-driver-docs-pr/debugger/processes-and-threads-window.md @@ -0,0 +1,61 @@ +--- +title: Controlling Processes and Threads in WinDbg +description: Controlling Processes and Threads in WinDbg +ms.assetid: d4755889-9a65-4e81-b3a3-e0bbc6324d3e +keywords: ["debugging information windows, Processes and Threads window", "Processes and Threads window", "process, Processes and Threads window", "thread, Processes and Threads window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Processes and Threads in WinDbg + + +## + + +In WinDbg, the Processes and Threads window displays information about the systems, processes, and threads that are being debugged. This window also enables you to select a new system, process, and thread to be active. + +### Opening the Processes and Threads Window + +To open the Processes and Threads window, choose **Processes and Threads** from the **View** menu. (You can also press ALT+9 or click the **Processes and Threads** button (![screen shot of the processes and threads button](images/window-processes-threads.png)) on the toolbar. ALT+SHIFT+9 closes the Processes and Threads window.) + +The following screen shot shows an example of a Processes and Threads window. + +![screen shot of the processes and threads window](images/window-prth.png) + +The Processes and Threads window displays a list of all processes that are currently being debugged. The threads in the process appear under each process. If the debugger is attached to multiple systems, the systems are shown at the top level of the tree, with the processes subordinate to them, and the threads subordinate to the processes. + +Each system listing includes the server name and the protocol details. The system that the debugger is running on is identified as **<Local>**. + +Each process listing includes the internal decimal process index that the debugger uses, the hexadecimal process ID, and the name of the application that is associated with the process. + +Each thread listing includes the internal decimal thread index that the debugger uses and the hexadecimal thread ID. + +### Using the Processes and Threads Window + +In the Processes and Threads window, the current or active system, process, and thread appear in bold type. To make a new system, process, or thread active, click its line in the window. + +The Processes and Threads window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button that displays the scratch pad window toolbar shortcut menu](images/window-processes-threads.png)). The following list describes some of the menu commands: + +- **Move to new dock** closes the Processes and Threads window and opens it in a new dock. + +- **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. + +### Additional Information + +For other methods of displaying or controlling systems, see [Debugging Multiple Targets](debugging-multiple-targets.md). For other methods of displaying or controlling processes and threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Processes%20and%20Threads%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/processor-architecture.md b/windows-driver-docs-pr/debugger/processor-architecture.md new file mode 100644 index 0000000000..35f065c4f5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/processor-architecture.md @@ -0,0 +1,33 @@ +--- +title: Processor Architecture +description: Processor Architecture +ms.assetid: 96006d9c-86d3-4744-b100-754e7041d6e4 +keywords: ["processor architecture", "architecture of processors", "CPU architecture"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processor Architecture + + +## + + +This section includes: + +[The x86 Processor](the-x86-processor.md) + +[The x64 Processor](the-x64-processor.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Processor%20Architecture%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/processor-breakpoints---ba-breakpoints-.md b/windows-driver-docs-pr/debugger/processor-breakpoints---ba-breakpoints-.md new file mode 100644 index 0000000000..e9ea599ceb --- /dev/null +++ b/windows-driver-docs-pr/debugger/processor-breakpoints---ba-breakpoints-.md @@ -0,0 +1,111 @@ +--- +title: Processor Breakpoints (ba Breakpoints) +description: Processor Breakpoints (ba Breakpoints) +ms.assetid: 2681cebd-dce2-48f1-8953-9af65d15f378 +keywords: ["breakpoints, processor breakpoints", "breakpoints, data breakpoints", "breakpoints, software breakpoints", "breakpoints, BP versus BA", "software breakpoint", "software breakpoint, overview", "software breakpoint, limitations", "processor breakpoint", "processor breakpoint, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processor Breakpoints (ba Breakpoints) + + +Breakpoints that are controlled by the processor at the request of the debugger are known as *processor breakpoints* or *data breakpoints*. Breakpoints that are controlled directly by the debugger are known as *software breakpoints*. + +**Note**   Although the term *data breakpoint* is commonly used as a synonym for *processor breakpoint*, this term can be misleading. There are two fundamental types of breakpoints: processor breakpoints, which are controlled by the processor, and software breakpoints, which are controlled by the debugger. Processor breakpoints are usually set on program data -- this is the reason they are called "data breakpoints" -- but they can also be set on executable code. Software breakpoints are usually set on executable code, but they can also be set on program data. Unfortunately, it is common in debugging literature to refer to processor breakpoints as "data breakpoints", even when they are set on executable code. + +  + +### Processor Breakpoints + +A processor breakpoint is triggered when a specific memory location is accessed. There are four types of processor breakpoints, corresponding to the kind of memory access that triggers it: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Breakpoint typeAction

e (execute)

Triggered when the processor retrieves an instruction from the specified address.

r (read/write)

Triggered when the processor reads or writes memory at the specified address.

w (write)

Triggered when the processor writes memory at the specified address.

i (i/o)

Triggered when the I/O port at the specified Address is accessed.

+ +  + +Each processor breakpoint has a size associated with it. For example, a **w** (write) processor breakpoint could be set at the address 0x70001008 with a size of four bytes. This would monitor the block of addresses from 0x70001008 to 0x7000100B, inclusive. If this block of memory is written to, the breakpoint will be triggered. + +It can happen that the processor performs an operation on a memory region that overlaps with, but is not identical to, the specified region. In the example given in the preceding paragraph, a single write operation that includes the range 0x70001000 to 0x7000100F, or a write operation that includes only the byte at 0x70001009, would be an overlapping operation. In such a situation, whether the breakpoint is triggered is processor-dependent. For details of how this situation is handled on a specific processor, consult the processor archictecture manual and look for "debug register" or "debug control register". To take one specific processor type as an example, on an x86 processor, a read or write breakpoint is triggered whenever the accessed range overlaps the breakpoint range. + +Similarly, if an **e** (execute) breakpoint is set on the address 0x00401003, and then a two-byte instruction spanning the addresses 0x00401002 and 0x00401003 is executed, the result is processor-dependent. Again, consult the processor architecture manual for details. + +The processor distinguishes between breakpoints set by a user-mode debugger and breakpoints set by a kernel-mode debugger. A user-mode processor breakpoint does not affect any kernel-mode processes. A kernel-mode processor breakpoint might or might not affect a user-mode process, depending on whether the user-mode code is using the debug register state and whether there is a user-mode debugger that is attached. + +To apply the current process' existing data breakpoints to a different register context, use the [**.apply\_dbp (Apply Data Breakpoint to Context)**](-apply-dbp--apply-data-breakpoint-to-context-.md) command. + +On a multiprocessor computer, each processor breakpoint applies to all processors. For example, if the current processor is 3 and you use the command `ba e1 MyAddress` to put a breakpoint at **MyAddress**, any processor -- not only processor 3 -- that executes at that address triggers the breakpoint. This holds for software breakpoints as well. + +### Software Breakpoints + +Software breakpoints, unlike processor breakpoints, are controlled by the debugger. When the debugger sets a software breakpoint at some location, it temporarily replaces the contents of that memory location with a break instruction. The debugger remembers the original contents of this location, so that if this memory is displayed in the debugger, the debugger will show the original contents of that memory location, not the break instruction. When the target process executes the code at this location, the break instruction causes the process to break into the debugger. After you have performed whatever actions you choose, you can cause the target to resume execution, and execution will resume with the instruction that was originally in that location. + +### Availability of Processor Breakpoint Types + +On Windows Server 2003 with Service Pack 1 (SP1), on an Itanium-based computer that uses WOW64 to emulate x86, processor breakpoints do not work with the **e** (execute) option but they do work with the **r** (read/write) and **w** (write) options. + +The **i** (i/o) option is available only during kernel-mode debugging, with a target computer that is running Windows XP or a later version of Windows on an x86-based processor. + +Not all data sizes can be used with all processor breakpoint types. The permitted sizes depend on the processor of the target computer. For details, see [**ba (Break on Access)**](ba--break-on-access-.md). + +### Limitations of Software Breakpoints and Processor Breakpoints + +It is possible to specify a data address rather than a program address when using the [**bp**](bp--bu--bm--set-breakpoint-.md) or bm /a commands. However, even if a data location is specified, these commands create software breakpoints, not processor breakpoints. When the debugger places a software breakpoint at some location, it temporarily replaces the contents of that memory location with a break instruction. This does not corrupt the executable image, because the debugger remembers the original contents of this location, and when the target process attempts to execute this code the debugger can respond appropriately. But when a software breakpoint is set in a data location, the resulting overwrite can lead to data corruption. Therefore, setting a software breakpoint on a data location is safe only if you are certain that this location will be used only as executable code. + +The **bp**, **bu**, and **bm** commands set software breakpoints by replacing the processor instruction with a break instruction. Therefore these cannot be used in read-only code or any other code that cannot be overwritten. To set a breakpoint in such code, you must use [**ba (Break on Access)**](ba--break-on-access-.md) with the **e** (execute) option. + +You cannot create multiple processor breakpoints at the same address that differ only in the command that is automatically executed when the breakpoint is triggered. However, you can create multiple breakpoints at the same address that differ in their other restrictions (for example, you can create multiple breakpoints at the same address by using the **ba** command with different values of the **/p**, **/t**, **/c**, and **/C** options). + +The initial breakpoint in a user-mode process (typically set on the **main** function or its equivalent) cannot be a processor breakpoint. + +The number of processor breakpoints that are supported depends on the target processor architecture. + +### Controlling Software Breakpoints and Processor Breakpoints + +Software breakpoints can be created with the [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md), **bm (Set Symbol Breakpoint)**, and **bu (Set Unresolved Breakpoint)** commands. Processor breakpoints can be created with the [**ba (Break on Access)**](ba--break-on-access-.md) command. Commands that disable, enable, and modify breakpoints apply to all kinds of breakpoints. Commands that display a list of breakpoints include all breakpoints, and indicate the type of each. For a listing of these commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +The WinDbg **Breakpoints** dialog box displays all breakpoints, indicating processor breakpoints with the notation "e", "r", "w", or "i' followed by the size of the block. This dialog box can be used to modify any breakpoint. The **Command** text box on this dialog box can be used to create any type of breakpoint.If a processor breakpoint is desired, begin the input with "ba". For details, see [Edit | Breakpoints](edit---breakpoints.md). When you set a breakpoint by using the mouse in the WinDbg [Disassembly window](disassembly-window.md) or [Source window](source-window.md), the debugger creates an unresolved software breakpoint. + +Processor breakpoints are stored in the processor's debug registers. It is possible to set a breakpoint by manually editing a debug register value, but this is strongly discouraged. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Processor%20Breakpoints%20%20%28ba%20Breakpoints%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/pseudo-register-syntax.md b/windows-driver-docs-pr/debugger/pseudo-register-syntax.md new file mode 100644 index 0000000000..0dba136be4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/pseudo-register-syntax.md @@ -0,0 +1,392 @@ +--- +title: Pseudo-Register Syntax +description: Pseudo-Register Syntax +ms.assetid: f7dc52ea-e97e-4251-a517-c115cbc7d056 +keywords: ["pseudo-registers", "pseudo-registers, automatic", "pseudo-registers, user defined", "registers, pseudo-registers", "loop variables", "return address", "$to to $t19 pseudo-registers", "$bp ID pseudo-register", "$ea"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Pseudo-Register Syntax + + +## + + +The debugger supports several pseudo-registers that hold certain values. + +The debugger sets *automatic pseudo-registers* to certain useful values. *User-defined pseudo-registers* are integer variables that you can write to or read. + +All pseudo-registers begin with a dollar sign (**$**). If you are using MASM syntax, you can add an at sign ( **@** ) before the dollar sign. This at sign tells the debugger that the following token is a register or pseudo-register, not a symbol. If you omit the at sign, the debugger responds more slowly, because it has to search the whole symbol table. + +For example, the following two commands produce the same output, but the second command is faster. + +``` +0:000> ? $exp +Evaluate expression: 143 = 0000008f +0:000> ? @$exp +Evaluate expression: 143 = 0000008f +``` + +If a symbol exists with the same name as the pseudo-register, you must add the at sign. + +If you are using C++ expression syntax, the at sign ( **@** ) is always required. + +The [**r (Registers)**](r--registers-.md) command is an exception to this rule. The debugger always interprets its first argument as a register or pseudo-register. (An at sign is not required or permitted.) If there is a second argument for the **r** command, it is interpreted according to the default expression syntax. If the default expression syntax is C++, you must use the following command to copy the **$t2** pseudo-register to the **$t1** pseudo-register. + +``` +0:000> r $t1 = @$t2 +``` + +### Automatic Pseudo-Registers + +The debugger automatically sets the following pseudo-registers. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Pseudo-registerDescription

$ea

The effective address of the last instruction that was executed. If this instruction does not have an effective address, the debugger displays "Bad register error". If this instruction has two effective addresses, the debugger displays the first address.

$ea2

The second effective address of the last instruction that was executed. If this instruction does not have two effective addresses, the debugger displays "Bad register error".

$exp

The last expression that was evaluated.

$ra

The return address that is currently on the stack.

+

This address is especially useful in execution commands. For example, g @$ra continues until the return address is found (although [gu (Go Up)](gu--go-up-.md) is a more precise effective way of "stepping out" of the current function).

$ip

The instruction pointer register.

+

+x86-based processors: The same as eip. +Itanium-based processors: Related to iip. (For more information, see the note following this table.) +x64-based processors: The same as rip.

$eventip

The instruction pointer at the time of the current event. This pointer typically matches $ip, unless you switched threads or manually changed the value of the instruction pointer.

$previp

The instruction pointer at the time of the previous event. (Breaking into the debugger counts as an event.)

$relip

An instruction pointer that is related to the current event. When you are branch tracing, this pointer is the pointer to the branch source.

$scopeip

The instruction pointer for the current [local context](changing-contexts.md#local-context) (also known as the scope).

$exentry

The address of the entry point of the first executable of the current process.

$retreg

The primary return value register.

+

+x86-based processors: The same as eax. +Itanium-based processors: The same as ret0. +x64-based processors: The same as rax.

$retreg64

The primary return value register, in 64-bit format.

+

x86 processor: The same as the edx:eax pair.

$csp

The current call stack pointer. This pointer is the register that is most representative of call stack depth.

+

+x86-based processors: The same as esp. +Itanium-based processors: The same as bsp. +x64-based processors: The same as rsp.

$p

The value that the last [d* (Display Memory)](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command printed.

$proc

The address of the current process (that is, the address of the EPROCESS block).

$thread

The address of the current thread. In kernel-mode debugging, this address is the address of the ETHREAD block. In user-mode debugging, this address is the address of the thread environment block (TEB).

$peb

The address of the process environment block (PEB) of the current process.

$teb

The address of the thread environment block (TEB) of the current thread.

$tpid

The process ID (PID) for the process that owns the current thread.

$tid

The thread ID for the current thread.

$dtid

$dpid

$dsid

$bpNumber

The address of the corresponding breakpoint. For example, $bp3 (or $bp03) refers to the breakpoint whose breakpoint ID is 3. Number is always a decimal number. If no breakpoint has an ID of Number, $bpNumber evaluates to zero. For more information about breakpoints, see [Using Breakpoints](using-breakpoints.md).

$frame

The current frame index. This index is the same frame number that the [.frame (Set Local Context)](-frame--set-local-context-.md) command uses.

$dbgtime

The current time, according to the computer that the debugger is running on.

$callret

The return value of the last function that [.call (Call Function)](-call--call-function-.md) called or that is used in an [.fnret /s](-fnret--display-function-return-value-.md) command. The data type of $callret is the data type of this return value.

$extret

$extin

$clrex

$lastclrex

Managed debugging only: The address of the last-encountered common language runtime (CLR) exception object.

$ptrsize

The size of a pointer. In kernel mode, this size is the pointer size on the target computer.

$pagesize

The number of bytes in one page of memory. In kernel mode, this size is the page size on the target computer.

$pcr

$pcrb

$argreg

$exr_chance

The chance of the current exception record.

$exr_code

The exception code for the current exception record.

$exr_numparams

The number of parameters in the current exception record.

$exr_param0

The value of Parameter 0 in the current exception record.

$exr_param1

The value of Parameter 1 in the current exception record.

$exr_param2

The value of Parameter 2 in the current exception record.

$exr_param3

The value of Parameter 3 in the current exception record.

$exr_param4

The value of Parameter 4 in the current exception record.

$exr_param5

The value of Parameter 5 in the current exception record.

$exr_param6

The value of Parameter 6 in the current exception record.

$exr_param7

The value of Parameter 7 in the current exception record.

$exr_param8

The value of Parameter 8 in the current exception record.

$exr_param9

The value of Parameter 9 in the current exception record.

$exr_param10

The value of Parameter 10 in the current exception record.

$exr_param11

The value of Parameter 11 in the current exception record.

$exr_param12

The value of Parameter 12 in the current exception record.

$exr_param13

The value of Parameter 13 in the current exception record.

$exr_param14

The value of Parameter 14 in the current exception record.

$bug_code

If a bug check has occurred, this is the bug code. Applies to live kernel-mode debugging and kernel crash dumps.

$bug_param1

If a bug check has occurred, this is the value of Parameter 1. Applies to live kernel-mode debugging and kernel crash dumps.

$bug_param2

If a bug check has occurred, this is the value of Parameter 2. Applies to live kernel-mode debugging and kernel crash dumps.

$bug_param3

If a bug check has occurred, this is the value of Parameter 3. Applies to live kernel-mode debugging and kernel crash dumps.

$bug_param4

If a bug check has occurred, this is the value of Parameter 4. Applies to live kernel-mode debugging and kernel crash dumps.

+ +  + +Some of these pseudo-registers might not be available in certain debugging scenarios. For example, you cannot use **$peb**, **$tid**, and **$tpid** when you are debugging a user-mode minidump or certain kernel-mode dump files. There will be situations where you can learn thread information from [**~ (Thread Status)**](---thread-status-.md) but not from **$tid**. You cannot use the **$previp** pseudo-register on the first debugger event. You cannot use the **$relip** pseudo-register unless you are branch tracing. If you use an unavailable pseudo-register, a syntax error occurs. + +A pseudo-register that holds the address of a structure -- such as **$thread**, **$proc**, **$teb**, **$peb**, and **$lastclrex** -- will be evaluated according to the proper data type in the C++ expression evaluator, but not in the MASM expression evaluator. For example, the command **? $teb** displays the address of the TEB, while the command **?? @$teb** displays the entire TEB structure. For more information, see [Evaluating Expressions](evaluating-expressions.md). + +On an Itanium-based processor, the **iip** register is *bundle-aligned*, which means that it points to slot 0 in the bundle containing the current instruction, even if a different slot is being executed. So **iip** is not the full instruction pointer. The **$ip** pseudo-register is the actual instruction pointer, including the bundle and the slot. The other pseudo-registers that hold address pointers (**$ra**, **$retreg**, **$eventip**, **$previp**, **$relip**, and **$exentry**) have the same structure as **$ip** on all processors. + +You can use the **r** command to change the value of **$ip**. This change also automatically changes the corresponding register. When execution resumes, it resumes at the new instruction pointer address. This register is the only automatic pseudo-register that you can change manually. + +**Note**   In MASM syntax, you can indicate the **$ip** pseudo-register with a period ( **.** ). You do not add an at sign (@) before this period, and do not use the period as the first parameter of the **r** command. This syntax is not permitted within a C++ expression. + +  + +Automatic pseudo-registers are similar to [automatic aliases](using-aliases.md). But you can use automatic aliases together with alias-related tokens (such as **${ }**), and you cannot use pseudo-registers with such tokens. + +### User-Defined Pseudo-Registers + +There are 20 user-defined pseudo-registers (**$t0**, **$t1**, ..., **$t19**). These pseudo-register are variables that you can read and write through the debugger. You can store any integer value in these pseudo-registers. They can be especially useful as loop variables. + +To write to one of these pseudo-registers, use the [**r (Registers)**](r--registers-.md) command, as the following example shows. + +``` +0:000> r $t0 = 7 +0:000> r $t1 = 128*poi(MyVar) +``` + +Like all pseudo-registers, you can use the user-defined pseudo-register in any expression, as the following example shows. + +``` +0:000> bp $t3 +0:000> bp @$t4 +0:000> ?? @$t1 + 4*@$t2 +``` + +A pseudo-register is always typed as an integer, unless you use the **?** switch together with the **r** command. If you use this switch, the pseudo-register acquires the type of whatever is assigned to it. For example, the following command assigns the UNICODE\_STRING\*\* type and the 0x0012FFBC value to **$t15**. + +``` +0:000> r? $t15 = * (UNICODE_STRING*) 0x12ffbc +``` + +User-defined pseudo-registers use zero as the default value when the debugger is started. + +**Note**  The aliases **$u0**, **$u1**, ..., **$u9** are not pseudo-registers, despite their similar appearance. For more information about these aliases, see [Using Aliases](using-aliases.md). + +  + +### Example + +The following example sets a breakpoint that is hit every time that the current thread calls **NtOpenFile**. But this breakpoint is not hit when other threads call **NtOpenFile**. + +``` +kd> bp /t @$thread nt!ntopenfile +``` + +### Example + +The following example executes a command until the register holds a specified value. First, put the following code for conditional stepping in a script file named "eaxstep". + +``` +.if (@eax == 1234) { .echo 1234 } .else { t "$Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **ptr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **return** instructions that must be encountered for this command to stop. The default value is one. + + *Command* +Specifies a debugger command to execute after the step is performed. This command is executed before the standard **pt** results are displayed. If you also use *Count*, the specified command is executed after all stepping is complete (but before the results from the final step are displayed). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **pt** command causes the target to begin executing. This execution continues until a **return** instruction is reached or a breakpoint is encountered. + +If the program counter is already on a **return** instruction, the entire return is executed. After this return is returned, execution continues until another **return** is reached. This execution, rather than tracing, of the call is the only difference between **pt** and [**tt (Trace to Next Return)**](tt--trace-to-next-return-.md). + +In source mode, you can associate one source line with multiple assembly instructions. The **pt** command does not stop at a **return** instruction that is associated with the current source line. + +The following example demonstrates using the **pt** command along with the **kb** command to display the stack trace: + +``` +0:000> pt "kb" +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20pt%20%28Step%20to%20Next%20Return%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/public-and-private-symbols.md b/windows-driver-docs-pr/debugger/public-and-private-symbols.md new file mode 100644 index 0000000000..bc703ba17c --- /dev/null +++ b/windows-driver-docs-pr/debugger/public-and-private-symbols.md @@ -0,0 +1,190 @@ +--- +title: Public and Private Symbols +description: Public and Private Symbols +ms.assetid: 61ed583d-8b97-4929-8d86-1a6353c13304 +keywords: ["symbols, public", "symbols, private", "public symbols", "private symbols", "retail symbols", "export symbols", "symbol file, full symbol file", "symbol file, stripped symbol file", "full symbol file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Public and Private Symbols + + +When a full-sized .pdb or .dbg symbol file is built by a linker, it contains two distinct collections of information: the *private symbol data* and a *public symbol table*. These collections differ in the list of items they contain and the information they store about each item. + +The private symbol data includes the following items: + +- Functions + +- Global variables + +- Local variables + +- Information about user-defined structures, classes, and data types + +- The name of the source file and the line number in that file corresponding to each binary instruction + +The public symbol table contains fewer items: + +- Functions (except for functions declared **static**) + +- Global variables specified as **extern** (and any other global variables visible across multiple object files) + +As a general rule, the public symbol table contains exactly those items that are accessible from one source file to another. Items visible in only one object file--such as **static** functions, variables that are global only within a single source file, and local variables--are not included in the public symbol table. + +These two collections of data also differ in what information they include for each item. The following information is typically included for each item contained in the private symbol data: + +- Name of the item + +- Address of the item in virtual memory + +- Frame pointer omission (FPO) records for each function + +- Data type of each variable, structure, and function + +- Types and names of the parameters for each function + +- Scope of each local variable + +- Symbols associated with each line in each source file + +On the other hand, the public symbol table stores only the following information about each item included in it: + +- The name of the item. + +- The address of the item in the virtual memory space of its module. For a function, this is the address of its entry point. + +- Frame pointer omission (FPO) records for each function. + +In other words, the public symbol data can be thought of as a subset of the private symbol data in two ways: it contains a shorter list of items, and it also contains less information about each item. For example, the public symbol data does not include local variables at all. Each local variable is included only in the private symbol data, with its address, data type, and scope. Functions, on the other hand, are included both in the private symbol data and public symbol table, but while the private symbol data includes the function name, address, FPO records, input parameter names and types, and output type, the public symbol table includes just the function name, address, and FPO record. + +There is one other difference between the private symbol data and the public symbol table. Many of the items in the public symbol table have names that are *decorated* with a prefix, a suffix, or both. These decorations are added by the C compiler, the C++ compiler, and the MASM assembler. Typical prefixes include a series of underscores or the string **\_\_imp\_** (designating an imported function). Typical suffixes include one or more at signs ( **@** ) followed by addresses or other identifying strings. These decorations are used by the linker to disambiguate the symbol, since it is possible that function names or global variable names could be repeated across different modules. These decorations are an exception to the general rule that the public symbol table is a subset of the private symbol data. + +### Full Symbol Files and Stripped Symbol Files + +A *full symbol file* contains both the private symbol data and the public symbol table. This kind of file is sometimes referred to as a *private symbol file*, but this name is misleading, for such a file contains both private and public symbols. + +A *stripped symbol file* is a smaller file that contains only the public symbol table - or, in some cases, only a subset of the public symbol table. This file is sometimes referred to as a *public symbol file*. + +### Creating Full and Stripped Symbol Files + +If you build your binaries with Visual Studio, you can create either full or stripped symbol files. When building a "debug build" of a binary, Visual Studio typically will create full symbol files. When building a "retail build", Visual Studio typically creates no symbol files, but a full or stripped symbol file will be created if the proper options are set. + +If you build your binaries with the Build utility, the utility will create full symbol files. + +Using the BinPlace tool, you can create a stripped symbol file from a full symbol file. When the most common BinPlace options are used (**-a -x -s -n**), the stripped symbol files are placed in the directory that is listed after the **-s** switch, and the full symbol files are placed in the directory that is listed after the **-n** switch. When BinPlace strips a symbol file, the stripped and full versions of the file are given identical signatures and other identifying information. This allows you to use either version for debugging. + +Using the PDBCopy tool, you can create a stripped symbol file from a full symbol file by removing the private symbol data. PDBCopy can also remove a specified subset of the public symbol table. For details, see [PDBCopy](pdbcopy.md). + +Using the SymChk tool, you can determine whether a symbol file contains private symbols. For details, see [SymChk](symchk.md). + +### Viewing Public and Private Symbols in the Debugger + +You can use WinDbg, KD, or CDB to view symbols. When one of these debuggers has access to a full symbol file, it has both the information listed in the private symbol data and the information listed in the public symbol table. The private symbol data is more detailed, while the public symbol data contains symbol decorations. + +When accessing private symbols, private symbol data is always used because these symbols are not included in the public symbol table. These symbols are never decorated. + +When accessing public symbols, the debugger's behavior depends on certain [symbol options](symbol-options.md): + +- When the [SYMOPT\_UNDNAME](symbol-options.md#symopt-undname) option is on, decorations are not included when the name of a public symbol is displayed. Moreover, when searching for symbols, decorations are ignored. When this option is off, decorations are displayed when displaying public symbols, and decorations are used in searches. Private symbols are never decorated in any circumstances. This option is on by default in all debuggers. + +- When the [SYMOPT\_PUBLICS\_ONLY](symbol-options.md#symopt-publics-only) option is on, private symbol data is ignored, and only the public symbol table is used. This option is off by default in all debuggers. + +- When the [SYMOPT\_NO\_PUBLICS](symbol-options.md#symopt-no-publics) option is on, the public symbol table is ignored, and searches and symbol information use the private symbol data alone. This option is off by default in all debuggers. + +- When the [SYMOPT\_AUTO\_PUBLICS](symbol-options.md#symopt-auto-publics) option is on (and both SYMOPT\_PUBLICS\_ONLY and SYMOPT\_NO\_PUBLICS are off), the first symbol search is performed in the private symbol data. If the desired symbol is found there, the search terminates. If not, the public symbol table is searched. Since the public symbol table contains a subset of the symbols in the private data, normally this results in the public symbol table being ignored. + +- When the SYMOPT\_PUBLICS\_ONLY, SYMOPT\_NO\_PUBLICS, and SYMOPT\_AUTO\_PUBLICS options are all off, both private symbol data and the public symbol table are searched each time a symbol is needed. However, when matches are found in both places, the match in the private symbol data is used. Therefore, the behavior in this instance is the same as when SYMOPT\_AUTO\_PUBLICS is on, except that using SYMOPT\_AUTO\_PUBLICS may cause symbol searches to happen slightly faster. + +Here is an example in which the command [**x (Examine Symbols)**](x--examine-symbols-.md) is used three times. The first time, the default symbol options are used, and so the information is taken from the private symbol data. Note that this includes information about the address, size, and data type of the array **typingString**. Next, the command .symopt+ 4000 is used, causing the debugger to ignore the private symbol data. When the **x** command is then run again, the public symbol table is used; this time there is no size and data type information for **typingString**. Finally, the command .symopt- 2 is used, which causes the debugger to include decorations. When the **x** command is run this final time, the decorated version of the function name, **\_typingString**, is shown. + +``` +0:000> x /t /d *!*typingstring* +00434420 char [128] TimeTest!typingString = char [128] "" + +0:000> .symopt+ 4000 + +0:000> x /t /d *!*typingstring* +00434420 TimeTest!typingString = + +0:000> .symopt- 2 + +0:000> x /t /d *!*typingstring* +00434420 TimeTest!_typingString = +``` + +### Viewing Public and Private Symbols with the DBH Tool + +Another way to view symbols is by using the [the DBH tool](dbh.md). DBH uses the same symbol options as the debugger. Like the debugger, DBH leaves [SYMOPT\_PUBLICS\_ONLY](symbol-options.md#symopt-publics-only) and [SYMOPT\_NO\_PUBLICS](symbol-options.md#symopt-no-publics) off by default, and turns [SYMOPT\_UNDNAME](symbol-options.md#symopt-undname) and [SYMOPT\_AUTO\_PUBLICS](symbol-options.md#symopt-auto-publics) on by default. These defaults can be overridden by a command-line option or by a DBH command. + +Here is an example in which the DBH command **addr 414fe0** is used three times. The first time, the default symbol options are used, and so the information is taken from the private symbol data. Note that this includes information about the address, size, and data type of the function **fgets**. Next, the command symopt +4000 is used, which causes DBH to ignore the private symbol data. When the **addr 414fe0** is then run again, the public symbol table is used; this time there is no size and data type information for the function **fgets**. Finally, the command symopt -2 is used, which causes DBH to include decorations. When the **addr 414fe0** is run this final time, the decorated version of the function name, **\_fgets**, is shown. + +``` +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +fgets + name : fgets + addr : 414fe0 + size : 113 + flags : 0 + type : 7e +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagFunction (5) + index : 7d + +pid:4308 mod:TimeTest[400000]: symopt +4000 + +Symbol Options: 0x10c13 +Symbol Options: 0x14c13 + +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +fgets + name : fgets + addr : 414fe0 + size : 0 + flags : 0 + type : 0 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagPublicSymbol (a) + index : 7f + +pid:4308 mod:TimeTest[400000]: symopt -2 + +Symbol Options: 0x14c13 +Symbol Options: 0x14c11 + +pid:4308 mod:TimeTest[400000]: addr 414fe0 + +_fgets + name : _fgets + addr : 414fe0 + size : 0 + flags : 0 + type : 0 +modbase : 400000 + value : 0 + reg : 0 + scope : SymTagNull (0) + tag : SymTagPublicSymbol (a) + index : 7f +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Public%20and%20Private%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/q--qq--quit-.md b/windows-driver-docs-pr/debugger/q--qq--quit-.md new file mode 100644 index 0000000000..62108f1899 --- /dev/null +++ b/windows-driver-docs-pr/debugger/q--qq--quit-.md @@ -0,0 +1,76 @@ +--- +title: q, qq (Quit) +description: The q and qq commands end the debugging session. +ms.assetid: 94d35997-8b21-4d25-b2ae-4b2a78240153 +keywords: ["q, qq (Quit) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- q, qq (Quit) +api_type: +- NA +--- + +# q, qq (Quit) + + +The **q** and **qq** commands end the debugging session. (In CDB and KD, this command also exits the debugger itself. In WinDbg, this command returns the debugger to dormant mode.) + +``` +q +qq +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +In user-mode debugging, the **q** command ends the debugging session and closes the target application. + +In kernel-mode debugging, the **q** command saves the log file and ends the debugging session. The target computer remains locked. + +If this command does not work in KD, press [**CTRL+R+ENTER**](ctrl-r--re-synchronize-.md) on the debugger keyboard, and then retry the **q** command. If this action does not work, you must use CTRL+B+ENTER to exit the debugger. + +The **qq** command behaves exactly like the **q** command, unless you are performing remote debugging. During remote debugging, the **q** command has no effect, but the **qq** command ends the debugging server. For more information about this effect, see [Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20q,%20qq%20%28Quit%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/qd--quit-and-detach-.md b/windows-driver-docs-pr/debugger/qd--quit-and-detach-.md new file mode 100644 index 0000000000..ccdb8c4914 --- /dev/null +++ b/windows-driver-docs-pr/debugger/qd--quit-and-detach-.md @@ -0,0 +1,71 @@ +--- +title: qd (Quit and Detach) +description: The qd command ends the debugging session and leaves any user-mode target application running. +ms.assetid: 3282c78b-6c4b-4c1b-a086-4890c3140ab9 +keywords: ["qd (Quit and Detach) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- qd (Quit and Detach) +api_type: +- NA +--- + +# qd (Quit and Detach) + + +The **qd** command ends the debugging session and leaves any user-mode target application running. (In CDB and KD, this command also exits the debugger itself. In WinDbg, this command returns the debugger to dormant mode.) + +``` +qd +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode only

Targets

Live debugging only

Platforms

All

+ +  + +Remarks +------- + +The **qd** command detaches from a target application and ends the debugging session, leaving the target still running. However, this command is supported only on Microsoft Windows XP and later versions of Windows. On Windows 2000, **qd** generates a warning message and has no effect. + +When you are performing remote debugging through the debugger, you cannot use the **qd** command from a debugging client. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20qd%20%28Quit%20and%20Detach%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/r--registers-.md b/windows-driver-docs-pr/debugger/r--registers-.md new file mode 100644 index 0000000000..605a0c360c --- /dev/null +++ b/windows-driver-docs-pr/debugger/r--registers-.md @@ -0,0 +1,399 @@ +--- +title: r (Registers) +description: The r command displays or modifies registers, floating-point registers, flags, pseudo-registers, and fixed-name aliases. +ms.assetid: c0d0af2f-1852-47a4-8f01-95f6ec198112 +keywords: ["r (Registers) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- r (Registers) +api_type: +- NA +--- + +# r (Registers) + + +The **r** command displays or modifies registers, floating-point registers, flags, pseudo-registers, and fixed-name aliases. + +User-Mode + +``` +[~Thread] r[M Mask|F|X|?] [ Register[:[Num]Type] [= [Value]] ] +r. +``` + +Kernel-Mode + +``` +[Processor] r[M Mask|F|X|Y|YI|?] [ Register[:[Num]Type] [= [Value]] ] +r. +``` + +## Parameters + + + *Processor* +Specifies the processor that the registers are read from. The default value is zero. If you specify *Processor*, you cannot include the *Register* parameter--all registers are displayed. For more information about the syntax, see [Multiprocessor Syntax](multiprocessor-syntax.md). You can specify processors only in kernel mode. + + *Thread* +Specifies the thread that the registers are read from. If you do not specify a thread, the current thread is used. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **M** *Mask* +Specifies the mask to use when the debugger displays the registers. The "M" must be an uppercase letter. *Mask* is a sum of bits that indicate something about the register display. The meaning of the bits depends on the processor and the mode (see the tables in the following Remarks section for more information). If you omit **M**, the default mask is used. You can set or display the default mask by using the [**Rm (Register Mask)**](rm--register-mask-.md) command. + + **F** +Displays the floating-point registers. The "F" must be an uppercase letter. This option is equivalent to **M 0x4**. + + **X** +Displays the SSE XMM registers. This option is equivalent to **M 0x40**. + + **Y** +Displays the AVX YMM registers. This option is equivalent to **M 0x200**. + + **YI** +Displays the AVX YMM integer registers. This option is equivalent to **M 0x400**. + + **?** +(Pseudo-register assignment only) Causes the pseudo-register to acquire typed information. Any type is permitted. For more information about the **r?** syntax, see [Debugger Command Program Examples](debugger-command-program-examples.md). + + *Register* +Specifies the register, flag, pseudo-register, or fixed-name alias to display or modify. You must not precede this parameter with at (**@**) sign. For more information about the syntax, see [Register Syntax](register-syntax.md). + + *Num* +Specifies the number of elements to display. If you omit this parameter but you include *Type*, the full register length is displayed. + + *Type* +Specifies the data format to display each register element in. You can use *Type* only with 64-bit and 128-bit vector registers. You can specify multiple types. + +You can specify one or more of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDisplay format

ib

Signed byte

ub

Unsigned byte

iw

Signed word

uw

Unsigned word

id

Signed DWORD

ud

Unsigned DWORD

iq

Signed quad-word

uq

Unsigned quad-word

f

32-bit floating-point

d

64-bit floating-point

+ +  + + *Value* +Specifies the value to assign to the register. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + + **.** +Displays the registers used in the current instruction. If no registers are used, no output is displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +Remarks +------- + +If you do not specify *Register*, the **r** command displays all the non-floating-point registers, and the **rF** command displays all the floating-point registers. You can change this behavior by using the [**rm (Register Mask)**](rm--register-mask-.md) command. + +If you specify *Register* but you omit the equal sign (=) and the *Value* parameter, the command displays the current value of the register. + +If you specify *Register* and an equal sign (=) but you omit *Value*, the command displays the current value of the register and prompts for a new value. + +If you specify *Register*, the equal sign (=), and *Value*, the command changes the register to contain the value. (If *quiet mode* is active, you can omit the equal sign. You can turn on quiet mode by using the [**sq (Set Quiet Mode)**](sq--set-quiet-mode-.md) command. In kernel mode, you can also turn on quiet mode by using the KDQUIET [environment variable](kernel-mode-environment-variables.md).) + +You can specify multiple registers, separated by commas. + +In user mode, the **r** command displays registers that are associated with the current thread. For more information about the threads, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +In kernel mode, the **r** command displays registers that are associated with the current *register context*. You can set the register context to match a specific thread, context record, or trap frame. Only the most important registers for the specified register context are actually displayed, and you cannot change their values. For more information about register context, see [Register Context](changing-contexts.md#register-context). + +When you specify a floating-point register by name, the **F** option is not required. When you specify a single floating-point register, the raw hexadecimal value is displayed in addition to the decimal value. + +The following *Mask* bits are supported for an x86-based processor or an x64-based processor. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitValueDescription

+0 +1

+0x1 +0x2

Displays the basic integer registers. (Setting one or both of these bits has the same effect.)

2

0x4

Displays the floating-point registers.

3

0x8

Displays the segment registers.

4

0x10

Displays the MMX registers.

5

0x20

Displays the debug registers. In kernel mode, setting this bit also displays the CR4 register.

6

0x40

Displays the SSE XMM registers.

7

0x80

(Kernel mode only) Displays the control registers, for example CR0, CR2, CR3 and CR8.

8

0x100

(Kernel mode only) Displays the descriptor and task state registers.

9

0x200

Displays the AVX YMM registers in floating point.

10

0x400

Displays the AVX YMM registers in decimal integers.

11

0x800

Displays the AVX XMM registers in decimal integers.

+ +  + +The following *Mask* bits are supported for an Itanium-based processor. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitValueDescription

+0 +1

+0x1 +0x2

Displays the basic integer registers. (Setting one or both of these bits has the same effect.)

2

0x4

Displays the floating-point registers.

3

0x8

Displays the high, floating-point registers (f32 to f127).

4

0x10

Displays the user debug registers.

5

0x20

(Kernel mode only) Displays the KSPECIAL_REGISTERS.

+ +  + +The following code examples show **r** commands for an x86-based processor. + +In kernel mode, the following command shows the registers for processor 2. + +``` +1: kd> 2r +``` + +In user mode, the following command shows the registers for thread 2. + +``` +0:000> ~2 r +``` + +In user mode, the following command displays all of the **eax** registers that are associated with all threads (in thread index order). + +``` +0:000> ~* r eax +``` + +The following command sets the **eax** register for the current thread to 0x000000FF. + +``` +0:000> r eax=0x000000FF +``` + +The following command sets the **st0** register to 1.234e+10 (the **F** is optional). + +``` +0:000> rF st0=1.234e+10 +``` + +The following command displays the zero flag. + +``` +0:000> r zf +``` + +The following command displays the **xmm0** register as 16 unsigned bytes and then displays the full contents of the **xmm1** register in double-precision floating-point format. + +``` +0:000> r xmm0:16ub, xmm1:d +``` + +If the current syntax is C++, you must precede registers by an at sign (**@**). Therefore, you could use the following command to copy the **ebx** register to the **eax** register. + +``` +0:000> r eax = @ebx +``` + +The following command displays pseudo-registers in the same way that the **r** command displays registers. + +``` +0:000> r $teb +``` + +You can also use the **r** command to create *fixed-name aliases*. These aliases are not registers or pseudo-registers, even though they are associated with the **r** command. For more information about these aliases, see [Using Aliases](using-aliases.md). + +Here is an example of the **r.** command on an x86-based processor. The last entry of the call stack precedes the command itself. + +``` +01004af3 8bec mov ebp,esp +0:000> r. +ebp=0006ffc0 esp=0006ff7c +``` + +Here is an example of the **r.** command on an Itanium-based processor. + +``` +e0000000`83066cf0 ld8.acq r25 = [r45] e0000000`ffff0b18=???????????????? +1: kd> r. +r25=ffffffff`d0000006 r45=e0000000`ffff0b18 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20r%20%28Registers%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/r.md b/windows-driver-docs-pr/debugger/r.md new file mode 100644 index 0000000000..3869c704bb --- /dev/null +++ b/windows-driver-docs-pr/debugger/r.md @@ -0,0 +1,41 @@ +--- +title: R (Windows Debugger Glossary) +description: Glossary page - R +Robots: noindex, nofollow +ms.assetid: 77bd1a66-39b3-4990-801e-4192a6e9cf47 +--- + +# R + + +**remote debugging** +Remote debugging is the practice of using a remote connection to perform debugging. + +Since user-mode debugging is usually done on one machine, remote user-mode debugging typically uses two machines. In this scenario, one computer contains the target application and a debugging server, while the other computer contains the debugging client. An alternate method is to have the target application and a process server on one computer, and a smart client on the other. + +Since kernel-mode debugging is usually done on two machines, remote kernel-mode debugging requires three machines. The target computer is the computer being debugged. The server is attached to the target; it contains the kernel-mode debugger. The client is the computer which is controlling the session remotely. Typically, one computer is the being debugged, another contains the debugging server, and the third contains the debugging client. + +In addition, there are other methods of remote debugging: using the Remote tool, using a KD connection server, or using a repeater. The method you should choose depends on the configuration of the machines in question and the available connections. + +For more information, see [Remote Debugging](remote-debugging.md). + +**register** +A very fast temporary memory location in the CPU. + +**register context** +The full processor state which includes all the processor's registers. + +For more information, see [**Register Context**](-thread--set-register-context-.md). + +**retail build** +See free build. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20R%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/rcdrkd-extensions.md b/windows-driver-docs-pr/debugger/rcdrkd-extensions.md new file mode 100644 index 0000000000..81e6e82429 --- /dev/null +++ b/windows-driver-docs-pr/debugger/rcdrkd-extensions.md @@ -0,0 +1,54 @@ +--- +title: RCDRKD Extensions +description: This section describes the RCDRKD debugger extension commands. These commands display WPP trace messages created by drivers. +ms.assetid: 11CEBCED-2C11-4450-A5FB-BC5B48B1E1A3 +--- + +# RCDRKD Extensions + + +This section describes the RCDRKD debugger extension commands. These commands display WPP trace messages created by drivers. Starting with Windows 8, you no longer need a separate trace message format (TMF) file to parse WPP messages. The TMF information is stored in the regular symbol file (PDB file). + +Starting in Windows 10, kernel-mode and user-mode drivers can use [Inflight Trace Recorder (IFR) for logging traces](https://msdn.microsoft.com/library/windows/hardware/dn914610). Your kernel-mode driver can use the RCDRKD commands to read messages from the circular buffers, format the messages, and display the messages in the debugger. + +**Note**  You cannot use the RCDRKD commands to view UMDF driver logs, UMDF framework logs, and KMDF framework logs. To view those logs, use [Windows Driver Framework Extensions (Wdfkd.dll)](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) commands. + +  + +The RCDRKD debugger extension commands are implemented in Rcdrkd.dll. To load the RCDRKD commands, enter **.load rcdrkd.dll** in the debugger. + +The following two commands are the primary commands for displaying trace messages. + +- [**!rcdrkd.rcdrlogdump**](-rcdrkd-rcdrlogdump.md) +- [**!rcdrkd.rcdrcrashdump**](-rcdrkd-rcdrcrashdump.md) + +The following auxiliary commands provide services related to displaying and saving trace messages. + +- [**!rcdrkd.rcdrloglist**](-rcdrkd-rcdrloglist.md) +- [**!rcdrkd.rcdrlogsave**](-rcdrkd-rcdrlogsave.md) +- [**!rcdrkd.rcdrsearchpath**](-rcdrkd-rcdrsearchpath.md) +- [**!rcdrkd.rcdrsettraceprefix**](-rcdrkd-rcdrsettraceprefix.md) +- [**!rcdrkd.rcdrtmffile**](-rcdrkd-rcdrtmffile.md) +- [**!rcdrkd.rcdrtraceprtdebug**](-rcdrkd-rcdrtraceprtdebug.md) + +The [**!rcdrkd.rcdrhelp**](-rcdrkd-rcdrhelp.md) displays help for the RCDRKD commands in the debugger. + +## Related topics + + +[WPP Software Tracing](http://go.microsoft.com/fwlink/p?LinkID=251984) + +[Using the Framework's Event Logger](http://go.microsoft.com/fwlink/p?LinkID=251985) + +[USB 3.0 Extensions](usb-3-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20RCDRKD%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/rdmsr--read-msr-.md b/windows-driver-docs-pr/debugger/rdmsr--read-msr-.md new file mode 100644 index 0000000000..e90d5ad889 --- /dev/null +++ b/windows-driver-docs-pr/debugger/rdmsr--read-msr-.md @@ -0,0 +1,78 @@ +--- +title: rdmsr (Read MSR) +description: The rdmsr command reads a Model-Specific Register (MSR) value from the specified address. +ms.assetid: 693f1be5-f215-4719-ae6f-30e367cefd77 +keywords: ["rdmsr (Read MSR) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rdmsr (Read MSR) +api_type: +- NA +--- + +# rdmsr (Read MSR) + + +The **rdmsr** command reads a [Model-Specific Register (MSR)](other-data-spaces.md) value from the specified address. + +``` +rdmsr Address +``` + +## Parameters + + + *Address* +Specifies the address of the MSR. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

All

+ +  + +Remarks +------- + +The **rdmsr** command can display MSR's on x86-based, Itanium-based, and x64-based platforms. The MSR definitions are platform-specific. + +## See also + + +[**wrmsr (Write MSR)**](wrmsr--write-msr-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20rdmsr%20%28Read%20MSR%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/reading-and-filtering-debugging-messages.md b/windows-driver-docs-pr/debugger/reading-and-filtering-debugging-messages.md new file mode 100644 index 0000000000..25f235d1e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/reading-and-filtering-debugging-messages.md @@ -0,0 +1,202 @@ +--- +title: Reading and Filtering Debugging Messages +description: Reading and Filtering Debugging Messages +ms.assetid: 785469d2-30b8-4f73-b397-80bf89ed20ea +keywords: ["reading and filtering debugging messages", "debugging messages, reading and filtering"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading and Filtering Debugging Messages + + +## + + +Kernel-mode code can use the **DbgPrintEx** and **KdPrintEx** routines to send a messages to the kernel debugger that are only transmitted under certain conditions. This allows you to filter out messages that you are not interested in. + +**Note**   In Windows Server 2003 and earlier versions of Windows, **DbgPrint** and **KdPrint** send messages to the kernel debugger unconditionally. In Windows Vista and later versions of Windows, these routines send messages conditionally, like **DbgPrintEx** and **KdPrintEx**. Whichever version of Windows you are using, it is recommended that you use **DbgPrintEx** and **KdPrintEx**, since these allow you to control the conditions under which the message will be sent. + +  + +For complete documentation of these routines, see the Windows Driver Kit. + +The basic procedure is as follows: + +**To filter debugging messages** + +1. For each message you wish to send to the debugger, use the function **DbgPrintEx** or **KdPrintEx** in your driver's code. Pass the appropriate component name to the *ComponentId* parameter, and pass a value to the *Level* parameter that reflects the severity or nature of this message. The message itself is passed to the *Format* and *arguments* parameters as with **printf**. + +2. Set the value of the appropriate *component filter mask*. Each component has a different mask; the mask value indicates which of that component's messages will be displayed. The component filter mask may be set in the registry using a registry editor, or in memory using a kernel debugger. + +3. Attach a kernel debugger to the computer. Each time your driver passes a message to **DbgPrintEx** or **KdPrintEx**, the values passed to *ComponentId* and *Level* will be compared with the value of the corresponding component filter mask. If these values satisfy certain criteria, the message will be sent to the kernel debugger and displayed. Otherwise, no message will be sent. + +Full details follow. All references on this page to **DbgPrintEx** apply equally to **KdPrintEx**. + +### Identifying the Component Name + +Each component has a separate filter mask. This allows the debugger to configure the filter for each component separately. + +Each component is referred to in different ways, depending on the context. In the *ComponentId* parameter of **DbgPrintEx**, the component name is prefixed with "DPFLTR\_" and suffixed with "\_ID". In the registry, the component filter mask has the same name as the component itself. In the debugger, the component filter mask is prefixed with "Kd\_" and suffixed with "\_Mask". + +There is a complete list of all component names (in DPFLTR\_*XXXX*\_ID format) in the Microsoft Windows Driver Kit (WDK) header ntddk.h and the Windows SDK header ntrtl.h. Most of these component names are reserved for Windows and for drivers written by Microsoft. + +There are six component names reserved for independent hardware vendors. To avoid mixing your driver's output with the output of Windows components, you should use one of the following component names: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Component nameDriver type

IHVVIDEO

Video driver

IHVAUDIO

Audio driver

IHVNETWORK

Network driver

IHVSTREAMING

Kernel streaming driver

IHVBUS

Bus driver

IHVDRIVER

Any other type of driver

+ +  + +For example, if you are writing a video driver, you would use DPFLTR\_IHVVIDEO\_ID as the *ComponentId* parameter of **DbgPrintEx**, use the value name **IHVVIDEO** in the registry, and refer to **Kd\_IHVVIDEO\_Mask** in the debugger. + +In Windows Vista and later versions of Windows, all messages sent by **DbgPrint** and **KdPrint** are associated with the **DEFAULT** component. + +### Choosing the Correct Level + +The *Level* parameter of the **DbgPrintEx** routine is of type DWORD. It is used to determine the *importance bit field*. The connection between the *Level* parameter and this bit field depends on the size of *Level*: + +- If *Level* is equal to a number between 0 and 31, inclusive, it is interpreted as a bit shift. The importance bit field is set to the value 1 << *Level*. Thus choosing a value between 0 and 31 for *Level* results in a bit field with exactly one bit set. If *Level* is 0, the bit field is equivalent to 0x00000001;if *Level* is 31, the bit field is equivalent to 0x80000000. + +- If *Level* is a number between 32 and 0xFFFFFFFF inclusive, the importance bit field is set to the value of *Level* itself. + +Thus, if you wish to set the bit field to 0x00004000, you can specify *Level* as 0x00004000 or simply as 14. Note that certain bit field values are not possible by this system -- including a bit field which is entirely zero. + +The following constants can be useful for setting the value of *Level*. They are defined in the Microsoft Windows Driver Kit (WDK) header ntddk.h and the Windows SDK header ntrtl.h: + +``` +#define DPFLTR_ERROR_LEVEL 0 +#define DPFLTR_WARNING_LEVEL 1 +#define DPFLTR_TRACE_LEVEL 2 +#define DPFLTR_INFO_LEVEL 3 +#define DPFLTR_MASK 0x8000000 +``` + +One easy way to use the *Level* parameter is to always use values between 0 and 31 -- using the bits 0, 1, 2, 3 with the meaning given by DPFLTR\_*XXXX*\_LEVEL, and using the other bits to mean whatever you choose. + +Another easy way to use the *Level* parameter is to always use explicit bit fields. If you choose this method, you may wish to OR the value DPFLTR\_MASK with your bit field; this assures that you will not accidentally use a value less than 32. + +To make your driver compatible with the way Windows uses message levels, you should only set the lowest bit (0x1) of the importance bit field if a serious error occurs. If you are using *Level* values less than 32, this corresponds to DPFLTR\_ERROR\_LEVEL. If this bit is set, your message is going to be viewed any time someone attaches a kernel debugger to a computer on which your driver is running. + +The warning, trace, and information levels should be used in the appropriate situations. Other bits can be freely used for any purposes that you find useful. This allows you to have a wide variety of message types that can be selectively seen or hidden. + +In Windows Vista and later versions of Windows, all messages sent by **DbgPrint** and **KdPrint** behave like **DbgPrintEx** and **KdPrintEx** messages with *Level* equal to DPFLTR\_INFO\_LEVEL. In other words, these messages have the third bit of their importance bit field set. + +### Setting the Component Filter Mask + +There are two ways to set a component filter mask: + +- The component filter mask can be accessed in the registry key **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Debug Print Filter**. Using a registry editor, create or open this key. Under this key, create a value with the name of the desired component, in uppercase. Set it equal to the DWORD value that you wish to use as the component filter mask. + +- If a kernel debugger is active, it can access the component filter mask value by dereferencing the address stored in the symbol **Kd\_***XXXX***\_Mask**, where *XXXX* is the desired component name. You can display the value of this mask in WinDbg or KD with the **dd (Display DWORD)** command, or enter a new component filter mask with the **ed (Enter DWORD)** command. If there is a danger of symbol ambiguity, you may wish to specify this symbol as **nt!Kd\_***XXXX***\_Mask**. + +Filter masks stored in the registry take effect during boot. Filter masks created by the debugger take effect immediately, and persist until Windows is rebooted. A value set in the registry can be overridden by the debugger, but the component filter mask will return to the value specified in the registry if the system is rebooted. + +There is also a system-wide mask called **WIN2000**. This is equal to 0x1 by default, though it can be changed through the registry or the debugger like all other components. When filtering is performed, each component filter mask is first ORed with the **WIN2000** mask. In particular, this means that components whose masks have never been specified default to 0x1. + +### Criteria for Displaying the Message + +When **DbgPrintEx** is called in kernel-mode code, Windows compares the message importance bit field specified by *Level* with the filter mask of the component specified by *ComponentId*. + +**Note**   Recall that when the *Level* parameter is between 0 and 31, the importance bit field is equal to 1 << *Level*, but when the *Level* parameter is 32 or higher, the importance bit field is simply equal to *Level*. + +  + +Windows performs an AND operation on the importance bit field and the component filter mask. If the result is nonzero, the message is sent to the debugger. + +### Example + +Here is an example. + +Suppose that before the last boot, you created the following values in the **Debug Print Filter** key: + +- **IHVVIDEO**, with a value equal to DWORD 0x2 + +- **IHVBUS**, equal to DWORD 0x7FF + +Now you issue the following commands in the kernel debugger: + +``` +kd> ed Kd_IHVVIDEO_Mask 0x8 +kd> ed Kd_IHVAUDIO_Mask 0x7 +``` + +At this point, the **IHVVIDEO** component has a filter mask of 0x8, the **IHVAUDIO** component has a filter mask of 0x7, and the **IHVBUS** component has a filter mask of 0x7FF. + +However, because these masks are automatically ORed with the **WIN2000** system-wide mask (which is usually equal to 0x1), the **IHVVIDEO** mask is effectively equal to 0x9. Indeed, components whose filter masks have not been set at all (for instance, **IHVSTREAMING** or **DEFAULT**) will have a filter mask of 0x1. + +Now suppose that the following function calls occur in various drivers: + +``` +DbgPrintEx( DPFLTR_IHVVIDEO_ID, DPFLTR_INFO_LEVEL, "First message.\n"); +DbgPrintEx( DPFLTR_IHVAUDIO_ID, 7, "Second message.\n"); +DbgPrintEx( DPFLTR_IHVBUS_ID, DPFLTR_MASK | 0x10, "Third message.\n"); +DbgPrint( "Fourth message.\n"); +``` + +The first message has its *Level* parameter equal to DPFLTR\_INFO\_LEVEL, which is 3. Since this is less than 32, it is treated as a bit shift, resulting in an importance bit field of 0x8. This value is then ANDed with the effective **IHVVIDEO** component filter mask of 0x9, giving a nonzero result. So the first message is transmitted to the debugger. + +The second message has its *Level* parameter equal to 7. Again, this is treated as a bit shift, resulting in an importance bit field of 0x80. This is then ANDed with the **IHVAUDIO** component filter mask of 0x7, giving a result of zero. So the second message is not transmitted. + +The third message has its *Level* parameter equal to DPFLTR\_MASK | 0x10. This is greater than 31, and therefore the importance bit field is set equal to the value of *Level* -- in other words, to 0x80000010. This is then ANDed with the **IHVBUS** component filter mask of 0x7FF, giving a nonzero result. So the third message is transmitted to the debugger. + +The fourth message was passed to **DbgPrint** instead of **DbgPrintEx**. In Windows Server 2003 and earlier versions of Windows, messages passed to this routine are always transmitted. In Windows Vista and later versions of Windows, messages passed to this routine are always given a default filter. The importance bit field is equal to 1 << DPFLTR\_INFO\_LEVEL, which is 0x00000008. The component for this routine is **DEFAULT**. Since you have not set the **DEFAULT** component filter mask, it has a value of 0x1. When this is ANDed with the importance bit field, the result is zero. So the fourth message is not transmitted. + +### The DbgPrint Buffer + +When **DbgPrint**, **DbgPrintEx**, **KdPrint**, or **KdPrintEx** transmits a message to the debugger, the formatted string is sent to the *DbgPrint buffer*. In most cases, the contents of this buffer are displayed immediately in the Debugger Command window. This display can be disabled by using the **Buffer DbgPrint Output** option of the Global Flags Utility (gflags.exe). This display does not automatically appear during local kernel debugging. + +During local kernel debugging, and any other time this display has been disabled, the contents of the DbgPrint buffer can only be viewed by using the [**!dbgprint**](-dbgprint.md) extension command. + +Any single call to **DbgPrint**, **DbgPrintEx**, **KdPrint**, or **KdPrintEx** will only transmit 512 bytes of information. Any output longer than this will be lost. The DbgPrint buffer itself can hold up to 4 KB of data on a free build of Windows, and up to 32 KB of data on a checked build of Windows. On Windows Server 2003 and later versions of Windows, you can use the KDbgCtrl tool to alter the size of the DbgPrint buffer. See [Using KDbgCtrl](using-kdbgctrl.md) for details. + +If a message is filtered out because of its *ComponentId* and *Level* values, it is not transmitted across the debugging connection. Therefore there is no way to display this message in the debugger. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reading%20and%20Filtering%20Debugging%20Messages%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/reading-and-writing-memory.md b/windows-driver-docs-pr/debugger/reading-and-writing-memory.md new file mode 100644 index 0000000000..34884187ff --- /dev/null +++ b/windows-driver-docs-pr/debugger/reading-and-writing-memory.md @@ -0,0 +1,41 @@ +--- +title: Reading and Writing Memory +description: Reading and Writing Memory +ms.assetid: bbe054a1-9522-4275-b550-9a6fc4e4b448 +keywords: ["memory", "memory, reading", "memory, writing", "reading memory", "writing memory"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading and Writing Memory + + +## + + +The Windows debuggers can read and write directly into memory. This memory can be referenced by addresses or by the names of variables. + +This section includes the following topics: + +[Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) + +[Accessing Memory by Physical Address](accessing-memory-by-physical-address.md) + +[Accessing Global Variables](accessing-global-variables.md) + +[Accessing Local Variables](accessing-local-variables.md) + +[Controlling Variables Through the Watch Window](controlling-variables-through-the-watch-window.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reading%20and%20Writing%20Memory%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/reading-bug-check-callback-data.md b/windows-driver-docs-pr/debugger/reading-bug-check-callback-data.md new file mode 100644 index 0000000000..27024391e9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/reading-bug-check-callback-data.md @@ -0,0 +1,125 @@ +--- +title: Reading Bug Check Callback Data +description: Reading Bug Check Callback Data +ms.assetid: 638074bb-5133-4edc-86c5-33aafa837a0c +keywords: ["callback data for bug checks", "callback data for bug checks, displaying callback data", "callback data for bug checks, displaying secondary data", "secondary bug check callback data", "bug check, callback routines", "dbgeng.h header file, IDebugDataSpaces3", "dbgeng.h header file, ReadTagged", "dbgeng.h header file, StartEnumTagged", "dbgeng.h header file, GetNextTagged"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading Bug Check Callback Data + + +Many drivers supply *bug check callback routines*. When Windows issues a bug check, it calls these routines before shutting down the system. These routines can specify and write to areas of memory known as *callback data* and *secondary callback data*. + +[BugCheckCallback](http://go.microsoft.com/fwlink/p/?LinkID=254479) +Data written by this routine becomes part of callback data. The data is not included in the crash dump file. (See [Earlier Versions of Windows](#earlier-versions-of-windows) for an exception.) + +[BugCheckSecondaryDumpDataCallback](http://go.microsoft.com/fwlink/p/?LinkID=254481) +Data written by this routine becomes part of secondary callback data. The data is included in the crash dump file. + +[BugCheckAddPagesCallback](http://go.microsoft.com/fwlink/p/?LinkID=254480) +Pages specified by this routine become part of callback data. The data in those pages is included in the crash dump file. + +The amount of callback and secondary callback data that is available to the debugger depends on several factors: + +- If you are performing live debugging of a crashed system, callback data that has already been written by [BugCheckCallback](http://go.microsoft.com/fwlink/p/?LinkID=254479) or specified by [BugCheckAddPagesCallback](http://go.microsoft.com/fwlink/p/?LinkID=254480) will be available. Secondary callback data will not be available, because it is not stored in any fixed memory location. + +- If you are debugging a Complete Memory Dump or Kernel Memory Dump, callback data specified by [BugCheckAddPagesCallback](http://go.microsoft.com/fwlink/p/?LinkID=254480) and secondary callback data written by [BugCheckSecondaryDumpDataCallback](http://go.microsoft.com/fwlink/p/?LinkID=254481) will be available. Callback data written by [BugCheckCallback](http://go.microsoft.com/fwlink/p/?LinkID=254479) will not be available. (See [Earlier Versions of Windows](#earlier-versions-of-windows) for an exception.) + +- If you are debugging a Small Memory Dump, callback data will not be available. Secondary callback data will be available. + +See [Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) for more details on these different dump file sizes. + +## Earlier Versions of Windows + + +In versions of Windows earlier than Windows XP SP1, callback data written by [BugCheckCallback](http://go.microsoft.com/fwlink/p/?LinkID=254479) is included in the crash dump file. + +## + + +### Displaying Callback Data + +To display bug check callback data, you can use the [**!bugdump**](-bugdump.md) extension. + +Without any parameters, [**!bugdump**](-bugdump.md) will display data for all callbacks. + +To view data for one specific callback routine, use [**!bugdump**](-bugdump.md)*Component*, where *Component* is the same parameter that was passed to **KeRegisterBugCheckCallback** when that routine was registered. + +### Displaying Secondary Callback Data + +There are two methods for displaying secondary callback data in Windows XP SP1, Windows Server 2003, and later versions of Windows. You can use the **.enumtag** command or you can write your own debugger extension. + +Each block of secondary callback data is identified by a GUID tag. This tag is specified by the **Guid** field of the **(KBUGCHECK\_SECONDARY\_DUMP\_DATA)ReasonSpecificData** parameter passed to [BugCheckSecondaryDumpDataCallback](http://go.microsoft.com/fwlink/p/?LinkID=254481). + +The [**.enumtag (Enumerate Secondary Callback Data)**](-enumtag--enumerate-secondary-callback-data-.md) command is not a very precise instrument. It displays every secondary data block, showing the tag and then showing the data in hexadecimal and ASCII format. It is generally useful only to determine what tags are actually being used for secondary data blocks. + +To use this data in a more practical way, it is recommended that you write your own debugger extension. This extension must call methods in the dbgeng.h header file. For details, see [Writing New Debugger Extensions](writing-new-debugger-extensions.md). + +If you know the GUID tag of the secondary data block, your extension should use the method **IDebugDataSpaces3::ReadTagged** to access the data. Its prototype is as follows: + +``` +STDMETHOD(ReadTagged)( + THIS_ + IN LPGUID Tag, + IN ULONG Offset, + OUT OPTIONAL PVOID Buffer, + IN ULONG BufferSize, + OUT OPTIONAL PULONG TotalSize + ) PURE; +``` + +Here is an example of how to use this method: + +``` +UCHAR RawData[MY_DATA_SIZE]; +GUID MyGuid = .... ; + +Success = DataSpaces->ReadTagged( &MyGuid, 0, RawData, + sizeof(RawData), NULL); +``` + +If you supply a *BufferSize* that is too small, **ReadTagged** will succeed but will write only the requested number of bytes to *Buffer*. If you specify a *BufferSize* that is too large, **ReadTagged** will succeed but will write only the actual block size to *Buffer*. If you supply a pointer for *TotalSize*, **ReadTagged** will use it to return the size of the actual block. If the block cannot be accessed, **ReadTagged** will return a failure status code. + +If two blocks have identical GUID tags, the first matching block will be returned, and the second block will be inaccessible. + +If you are not sure of the GUID tag of your block, you can use the **IDebugDataSpaces3::StartEnumTagged**, **IDebugDataSpaces3::GetNextTagged**, and **IDebugDataSpaces3::EndEnumTagged** methods to enumerate the tagged blocks. Their prototypes are as follows: + +``` +STDMETHOD(StartEnumTagged)( + THIS_ + OUT PULONG64 Handle + ) PURE; + +STDMETHOD(GetNextTagged)( + THIS_ + IN ULONG64 Handle, + OUT LPGUID Tag, + OUT PULONG Size + ) PURE; + +STDMETHOD(EndEnumTagged)( + THIS_ + IN ULONG64 Handle + ) PURE; +``` + +### Debugging Callback Routines + +It is also possible to debug the callback routine itself. Breakpoints within callback routines work just like any other breakpoint. + +If the callback routine causes a second bug check, this new bug check will be processed first. However, Windows will not repeat certain parts of the Stop process—for example, it will not write a second crash dump file. The Stop code displayed on the blue screen will be the second bug check code. If a kernel debugger is attached, messages about both bug checks will usually appear. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reading%20Bug%20Check%20Callback%20Data%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/reading-symbols-from-paged-out-headers.md b/windows-driver-docs-pr/debugger/reading-symbols-from-paged-out-headers.md new file mode 100644 index 0000000000..c7016c605c --- /dev/null +++ b/windows-driver-docs-pr/debugger/reading-symbols-from-paged-out-headers.md @@ -0,0 +1,118 @@ +--- +title: Reading Symbols from Paged-Out Headers +description: Reading Symbols from Paged-Out Headers +ms.assetid: 74ec20d8-e2b5-449d-8b93-7553c57fac07 +keywords: ["symbols, paged-out header problems"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading Symbols from Paged-Out Headers + + +## + + +The kernel debugger must read the header for each loaded module's image in order to know which symbols correspond to that module. + +If a module's header is paged out to disk, the debugger will not load symbols for this module. If this happens with a module that is essential to the debugging process, it can be a critical problem. + +The following procedure can be used to solve this problem. + +**To acquire symbols for paged-out headers** + +1. Make a second copy of the kernel itself. It is probably easiest to put this on a network share. + +2. Append the root directory of this share to the symbol path. See [Symbol Path](symbol-path.md) for the ways to change the symbol path. + +3. Use the [**.reload (Reload Module)**](-reload--reload-module-.md) command. + +4. Use the [**!sym noisy**](-sym.md) extension command to see more verbose output. If this is used, you will be able to see which symbols are loaded from the module images on the target computer, and which are loaded from the copy of the kernel modules. + +This technique must be used with care, since the debugger has no way of verifying whether the file copies actually match the originals. So it is crucial that the version of Windows used on the network share matches the version used on the target computer. + +This technique is only used for kernel-mode debugging. The operating system is capable of paging in any headers required during user-mode debugging (unless the disk holding the paging file is dismounted or otherwise inaccessible). + +Here is an example of this technique being used: + +``` +kd> .reload +Connected to Windows XP 2268 x86 compatible target, ptr64 FALSE +Loading Kernel Symbols +..........Unable to read image header for dmload.sys at fe0be000 - NTSTATUS 0xC0000001 +..........Unable to read image header for dmboot.sys at fda93000 - NTSTATUS 0xC0000001 +.....................................Unable to read image header for fdc.sys at fdfc2000 - NTSTATUS 0xC0000001 +...Unable to read image header for flpydisk.sys at fde4a000 - NTSTATUS 0xC0000001 +.Unable to read image header for Fs_Rec.SYS at fe0c8000 - NTSTATUS 0xC0000001 +.Unable to read image header for Null.SYS at fe2c4000 - NTSTATUS 0xC0000001 +...................Unable to read image header for win32k.sys at a0000000 - NTSTATUS 0xC0000001 +..Unable to read image header for dxg.sys at a0194000 - NTSTATUS 0xC0000001 +.......Unable to read image header for ati2draa.dll at a01a4000 - NTSTATUS 0xC0000001 +..Unable to read image header for ParVdm.SYS at fe116000 - NTSTATUS 0xC0000001 +....... +Loading unloaded module list +.............. +Loading User Symbols +Unable to retrieve the PEB address. This is usually caused +by being in the wrong process context or by paging +``` + +Notice that many images have inaccessible headers. Check the symbols from one of these files (in this example, fs\_rec.sys): + +``` +kd> x fs_rec!* +*** ERROR: Module load completed but symbols could not be loaded for fs_rec.sys +``` + +These headers are apparently paged out. So you need to add the proper images to the symbol path: + +``` +kd> .sympath+ \\myserver\myshare\symbols\x86fre\symbols +Symbol search path is: symsrv*symsrv.dll*c:\localcache*https://msdl.microsoft.com/download/symbols;\\myserver\myshare\symbols\x86fre\symbols + +kd> .reload +Connected to Windows XP 2268 x86 compatible target, ptr64 FALSE +Loading Kernel Symbols +..........Unable to read image header for dmload.sys at fe0be000 - NTSTATUS 0xC0000001 +..........Unable to read image header for dmboot.sys at fda93000 - NTSTATUS 0xC0000001 +.....................................Unable to read image header for fdc.sys at fdfc2000 - NTSTATUS 0xC0000001 +...Unable to read image header for flpydisk.sys at fde4a000 - NTSTATUS 0xC0000001 +.Unable to read image header for Fs_Rec.SYS at fe0c8000 - NTSTATUS 0xC0000001 +.Unable to read image header for Null.SYS at fe2c4000 - NTSTATUS 0xC0000001 +...................Unable to read image header for win32k.sys at a0000000 - NTSTATUS 0xC0000001 +..Unable to read image header for dxg.sys at a0194000 - NTSTATUS 0xC0000001 +.......Unable to read image header for ati2draa.dll at a01a4000 - NTSTATUS 0xC0000001 +..Unable to read image header for ParVdm.SYS at fe116000 - NTSTATUS 0xC0000001 +....... +Loading unloaded module list +.............. +Loading User Symbols +Unable to retrieve the PEB address. This is usually caused +by being in the wrong process context or by paging +``` + +The same warnings have appeared, but the symbols themselves are now accessible: + +``` +kd> x fs_Rec!* +fe0c8358 Fs_Rec!_imp___allmul +fe0c8310 Fs_Rec!_imp__IoCreateDevice +fe0c835c Fs_Rec!_imp___allshr +........ +fe0c8360 Fs_Rec!ntoskrnl_NULL_THUNK_DATA +fe0c832c Fs_Rec!_imp__KeSetEvent +fe0c9570 Fs_Rec!_NULL_IMPORT_DESCRIPTOR +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reading%20Symbols%20from%20Paged-Out%20Headers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/reading-the-logviewer-display.md b/windows-driver-docs-pr/debugger/reading-the-logviewer-display.md new file mode 100644 index 0000000000..6511a40486 --- /dev/null +++ b/windows-driver-docs-pr/debugger/reading-the-logviewer-display.md @@ -0,0 +1,83 @@ +--- +title: Reading the LogViewer Display +description: Reading the LogViewer Display +ms.assetid: 425aff5d-780e-4600-a43a-8012d70263f1 +keywords: ["LogViewer, display"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading the LogViewer Display + + +## + + +LogViewer displays a list of all functions in the order they were logged. + +Each row of the display contains several columns. The significance of each column is as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnMeaning

+/-

If this column contains a "+" (plus sign), it indicates that the function takes one or more parameters. To see the parameters and their values, either double-click the row or hit the right arrow key when the row is outlined in red. To hide it again, double click it again or hit the left arrow key when the row is outlined in red.

+

There is also a "d#" value in this column. This indicates the "depth" of the function call (in other words, how deep the call is nested in other logged function calls).

#

The sequential row number of the function call. This is useful when you have filters applied and are interested to know how far apart two function calls are.

Thrd

The thread number on which the function call was made. This number is not a thread ID, but is rather an assigned number based on the order that threads were created in the process.

Caller

The instruction address that made the function call. This is derived from the return address for the call. It is actually the return address minus 5 bytes (the typical size of a call dword ptr instruction).

Module

The module that contains the calling instruction.

API Function

The name of the function. The name of the module that contains the function is omitted for brevity.

Return Value

The value returned by the function, if it is not a void function.

+ +  + +Double-clicking on a row in the viewer will expand the row to reveal the parameters to the function and their values "going in" to the function. If they are designated as OUT parameters, their value "coming out" is shown on the right. + +You can also use the ENTER key or the right and left arrow keys to expand and collapse rows. + +Function calls that returned failure status codes are shaded in pink. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reading%20the%20LogViewer%20Display%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/reattaching-to-the-target-application.md b/windows-driver-docs-pr/debugger/reattaching-to-the-target-application.md new file mode 100644 index 0000000000..61ea3ebff9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/reattaching-to-the-target-application.md @@ -0,0 +1,57 @@ +--- +title: Reattaching to the Target Application +description: Reattaching to the Target Application +ms.assetid: cc137185-58a7-44bf-b262-2698c46730f6 +keywords: ["re-attaching to the target application", "process, re-attaching debugger to"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reattaching to the Target Application + + +## + + +If the debugger freezes or otherwise stops responding (that is, *crashes*) while you perform user-mode debugging, you can attach a new debugger to the existing process. + +**Note**  This method is supported only on Microsoft Windows XP and later versions of Windows. This method does not depend on whether the debugger originally created the process or attached to an existing process. This method does not depend on whether you used the **-pd** option. + +  + +To reattach a debugger to an existing target application, do the following: + +1. [Determine the process ID](finding-the-process-id.md) of the target application. + +2. Start a new instance of CDB or WinDbg. Use the **-pe** command-line option. + + ``` + Debugger -pe -p PID + ``` + + You can also use other [command-line options](command-line-options.md). + + You can also connect from a dormant debugger by using the [**.attach (Attach to Process)**](-attach--attach-to-process-.md) command together with the **-e** option. + +3. After the attach is complete, end the original debugger process. + +4. If the process does not respond properly, it might have a suspend count that is too high. You can use the [**~m (Resume Thread)**](-m--resume-thread-.md) command to reduce the suspend count. For more information about suspend counts, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +If the original debugger is still operating properly, this method might not work. The two debuggers are competing for debugging events, and the Windows operating system does not necessarily assign all of the debugging events to the new debugger. + +If the original debugger is ended before you attach the new debugger, the target application is also closed. (However, if the debugger attached with the **-pd** option and then exits normally, the target application continues running. In this situation, a second debugger can attach to the target application without using the **-pe** option.) + +If you are already debugging a process and want to detach from the process but leave it frozen in a debugging state, you can use the [**.abandon (Abandon Process)**](-abandon--abandon-process-.md) command. After this command, any Windows debugger can reattach to the process by using the procedure that is described in this topic. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Reattaching%20to%20the%20Target%20Application%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/register-syntax.md b/windows-driver-docs-pr/debugger/register-syntax.md new file mode 100644 index 0000000000..f0d261a211 --- /dev/null +++ b/windows-driver-docs-pr/debugger/register-syntax.md @@ -0,0 +1,55 @@ +--- +title: Register Syntax +description: Register Syntax +ms.assetid: 64a566b1-c10b-4329-947c-af69904a21f8 +keywords: ["expressions, registers", "registers, command syntax", "(register prefix)", "syntax rules for commands, (register prefix)", "syntax rules for commands, registers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Register Syntax + + +## + + +The debugger can control registers and floating-point registers. + +When you use a register in an expression, you should add an at sign ( **@** ) before the register. This at sign tells the debugger that the following text is the name of a register. + +If you are using MASM expression syntax, you can omit the at sign for certain very common registers. On x86-based systems, you can omit the at sign for the **eax**, **ebx**, **ecx**, **edx**, **esi**, **edi**, **ebp**, **eip**, and **efl** registers. However, if you specify a less common register without an at sign, the debugger first tries to interpret the text as a hexadecimal number. If the text contains non-hexadecimal characters, the debugger next interprets the text as a symbol. Finally, if the debugger does not find a symbol match, the debugger interprets the text as a register. + +If you are using C++ expression syntax, the at sign is always required. + +The [**r (Registers)**](r--registers-.md) command is an exception to this rule. The debugger always interprets its first argument as a register. (An at sign is not required or permitted.) If there is a second argument for the **r** command, it is interpreted according to the default expression syntax. If the default expression syntax is C++, you must use the following command to copy the **ebx** register to the **eax** register. + +``` +0:000> r eax = @ebx +``` + +For more information about the registers and instructions that are specific to each processor, see [Processor Architecture](processor-architecture.md). + +### Flags on an x86-based Processor + +x86-based processors also use several 1-bit registers known as *flags*. For more information about these flags and the syntax that you can use to view or change them, see [x86 Flags](x86-architecture.md#x86-flags). + +### Registers and Threads + +Each thread has its own register values. These values are stored in the CPU registers when the thread is executing and in memory when another thread is executing. + +In user mode, any reference to a register is interpreted as the register that is associated with the current thread. For more information about the current thread, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +In kernel mode, any reference to a register is interpreted as the register that is associated with the current register context. You can set the register context to match a specific thread, context record, or trap frame. You can display only the most important registers for the specified register context, and you cannot change their values. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Register%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/registers-window.md b/windows-driver-docs-pr/debugger/registers-window.md new file mode 100644 index 0000000000..7cc1111bb6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/registers-window.md @@ -0,0 +1,115 @@ +--- +title: Viewing and Editing Registers in WinDbg +description: In WinDbg, you can view and edit registers by entering commands, by using the Registers window, or by using the Watch Window. +ms.assetid: bd7ced3b-7f71-4ea5-a45b-38339dc3e87c +keywords: ["debugging information windows, Registers window", "Registers window", "registers, Registers window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Viewing and Editing Registers in WinDbg + + +Registers are small volatile memory units that are located on the CPU. Many registers are dedicated to specific uses, and other registers are available for user-mode applications to use. The x86-based and x64-based processors have different collections of registers available. For more information about the registers on each processor, see [Processor Architecture](processor-architecture.md). + +In WinDbg, you can view and edit registers by entering commands, by using the Registers window, or by using the Watch Window. + +## Commands + + +You can view and edit registers by entering the [**r (Registers)**](r--registers-.md) command in the Debugger Command window. You can customize the display by using several options or by using the [**rm (Register Mask)**](rm--register-mask-.md) command. + +Registers are also automatically displayed every time that the target stops. If you are stepping through your code with the [**p (Step)**](p--step-.md) or [**t (Trace)**](t--trace-.md) commands, you see a register display at every step. To stop this display, use the **r** option when you use these commands. + +On an x86-based processor, the **r** option also controls several one-bit registers known as flags. To change these flags, you use a slightly different syntax than when changing regular registers. For more information about these flags and an explanation of this syntax, see [x86 Flags](x86-architecture.md#x86-flags). + +## The Registers Window + + +### Opening the Registers Window + +To open or switch to the Registers window, choose **Registers** from the **View** menu. (You can also press ALT+4 or click the **Registers** button (![screen shot of the registers button](images/tbreg.png)) on the toolbar. ALT+SHIFT+4 closes the Registers window.) + +The following screen shot shows an example of a Registers window. + +![screen shot of the registers window](images/window-registers.png) + +The Registers window contains two columns. The **Reg** column lists all of the registers for the target processor. The **Value** column displays the current value of each register. This window also contains a **Customize** button on the toolbar that opens the **Customize Register List** dialog box. + +### Using the Registers Window + +In the Registers window, you can do the following: + +- The **Value** column displays the current value of each register. The value of the most recently changed register is displayed in red text. + - To enter a new value, double-click a **Value** cell, and then type a new value or edit the old value. (The cut, copy, and paste commands are available to use for editing.) + - To save the new value, press ENTER. + - To discard the new value, press ESC. + - If you type an invalid value, the old value will reappear when you press ENTER. +- Register values are displayed in the current radix, and you must type new values in the same radix. To change the current radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command in the Debugger Command window. + +- In user mode, the Registers window displays the registers that are associated with the current thread. For more information about the current thread, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +- In kernel mode, the Registers window displays the registers that are associated with the current [register context](changing-contexts.md#register-context). You can set the register context to match a specific thread, context record, or trap frame. Only the most important registers for the specified register context are actually displayed; you cannot change their values. + +The Registers window has a toolbar that contains a **Customize** button and has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button icon for displaying the registers window shortcut menu](images/tbreg.png)). The toolbar and menu contain the following button and commands: + +- (Toolbar and menu) **Customize** opens the **Customize Register List** dialog box, which is described in the following section within this topic. + +- (Menu only) **Toolbar** turns the toolbar on and off. + +- (Menu only) **Dock** or **Undock** causes the window to enter or leave the docked state. + +- (Menu only) **Move to new dock** closes the Registers window and opens it in a new dock. + +- (Menu only) **Set as tab-dock target for window type** is unavailable for the Registers window. This option is only available for Source or Memory windows. + +- (Menu only) **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- (Menu only) **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +- (Menu only) **Help** opens this topic in the Debugging Tools for Windows documentation. + +- (Menu only) **Close** closes this window. + +### Customize Register List Dialog Box + +To change the list of registers that are displayed, click the **Customize** button. The **Customize Register List** dialog box will appear. + +In this dialog box, you can edit the list of registers to change the order in which registers are displayed. (You cannot actually delete a register from the list; if you do, it will reappear at the end.) There must be a space between register names. + +If you select the **Display modified register values first** check box, the register whose values have been changed most recently appears at the top. + +If you select the **Do not display subregisters** check box, subregisters are not displayed. For example, **eax** will be displayed, but not **ax**, **ah**, or **al**. + +Click **OK** to save your changes or **Cancel** to discard your changes. + +If you are debugging a multi-processor computer with more than one kind of processor, WinDbg stores the customization settings for each processor type separately. This separation enables you to customize the display of each processor's registers simultaneously. + +## The Watch Window + + +In WinDbg, you can use the Watch window to display registers. You cannot use the Watch window to alter the values of registers. + +To open the Watch window, choose **Watch** from the **View** menu. You can also press ALT+2 or click the **Watch** button on the toolbar: ![screen shot of the watch button](images/tbwatch.png). ALT+SHIFT+2 closes the Watch window. + +The following screen shot shows an example of a Watch window. + +![screen shot of the watch window ](images/window-watch.png) + +## Additional Information + + +For more information about the register context and other context settings, see [Changing Contexts](changing-contexts.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Registers%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/registers.md b/windows-driver-docs-pr/debugger/registers.md new file mode 100644 index 0000000000..f4c15da805 --- /dev/null +++ b/windows-driver-docs-pr/debugger/registers.md @@ -0,0 +1,75 @@ +--- +title: Registers +description: Registers +ms.assetid: fa334c9f-46c6-4288-95ce-43128fff7f03 +keywords: ["memory access, registers", "registers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registers + + +## + + +The [debugger engine](introduction.md#debugger-engine) can be used to examine and alter the target's registers. + +The registers available on the target depend on its processor architecture. For a description of the registers for the x86 and Itanium processors, see [Processor Architecture](processor-architecture.md). For a complete description of the registers available for a processor, see that processor's documentation. + +### The Register Set + +The [**GetNumberRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff547960) method can be used to find the number of registers on the target. + +Each register is referred to by its index. The index of the first register is zero, and the index of the last register is the number of registers minus one. To find the index of a register whose name is known, use [**GetIndexByName**](https://msdn.microsoft.com/library/windows/hardware/ff546881). + +The method [**GetDescription**](https://msdn.microsoft.com/library/windows/hardware/ff546575) returns information about a register. This includes the register's name, the type of values it can hold, and whether it is a subregister. + +A *subregister* is a register that is contained within another register. When the subregister changes, the register that contains it also changes. For example, on an x86 processor, the **ax** subregister is the same as the low 16 bits of the 32-bit **eax** register. + +There are three special registers whose values may be found by using the following methods. The interpretation of the values of these registers is platform dependent. + +- The location of the current instruction may be found with [**GetInstructionOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546916) and [**GetInstructionOffset2**](https://msdn.microsoft.com/library/windows/hardware/ff546933). + +- The location of the current processor stack slot may be found with [**GetStackOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548403) and [**GetStackOffset2**](https://msdn.microsoft.com/library/windows/hardware/ff548414). + +- The location of the stack frame for the current function may be found with [**GetFrameOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546806) and [**GetFrameOffset2**](https://msdn.microsoft.com/library/windows/hardware/ff546815). + +### Manipulating Registers + +The value of a register can be read by using the method [**GetValue**](https://msdn.microsoft.com/library/windows/hardware/ff549476). Multiple registers can be read by using [**GetValues**](https://msdn.microsoft.com/library/windows/hardware/ff549480) and [**GetValues2**](https://msdn.microsoft.com/library/windows/hardware/ff549487). + +A value can be written to a register by using the method [**SetValue**](https://msdn.microsoft.com/library/windows/hardware/ff556881). Multiple registers can be written by using [**SetValues**](https://msdn.microsoft.com/library/windows/hardware/ff556883) and [**SetValues2**](https://msdn.microsoft.com/library/windows/hardware/ff556884). + +When writing a value to a register, if the value supplied has a different type to the type of the register then the value is converted into the register's type. This conversion is the same as that performed by the method [**CoerceValue**](https://msdn.microsoft.com/library/windows/hardware/ff539158). This conversion may result in data loss if the register's type is not capable of holding the value supplied. + +### Pseudo-Registers + +*Pseudo-registers* are variables maintained by the debugger engine that hold certain values, for example, **$teb** is the name of the pseudo-register whose value is the address of the current thread's Thread Environment Block (TEB). For more information, and a list of the pseudo-registers, see [Pseudo-Register Syntax](pseudo-register-syntax.md). + +Each pseudo-register has an index. The index is a number between zero and the number of pseudo-registers - (returned by [**GetNumberPseudoRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff547957)) minus one. To find the index of a pseudo-register by its name, use [**GetPseudoIndexByName**](https://msdn.microsoft.com/library/windows/hardware/ff548206). The values of pseudo-registers can be read using [**GetPseudoValues**](https://msdn.microsoft.com/library/windows/hardware/ff548215), and values can be written to pseudo-registers using [**SetPseudoValues**](https://msdn.microsoft.com/library/windows/hardware/ff556767). For a description of a pseudo-register, including its type, use [**GetPseudoDescription**](https://msdn.microsoft.com/library/windows/hardware/ff548189). + +**Note**   Not all of the pseudo-registers are available in all debugging sessions or at all times in a particular session. + +  + +### Displaying Registers + +The methods [**OutputRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff553242) and [**OutputRegisters2**](https://msdn.microsoft.com/library/windows/hardware/ff553245) format the target's registers and sends them to the clients as output. + +### Events + +Whenever the values of the target's registers change, the engine will call the [**IDebugEventCallbacks::ChangeDebuggeeState**](https://msdn.microsoft.com/library/windows/hardware/ff550678) callback method with the parameter *Flags* set to DEBUG\_CDS\_REGISTERS. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Registers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/registry-entries-for-silent-process-exit.md b/windows-driver-docs-pr/debugger/registry-entries-for-silent-process-exit.md new file mode 100644 index 0000000000..d00fc12f56 --- /dev/null +++ b/windows-driver-docs-pr/debugger/registry-entries-for-silent-process-exit.md @@ -0,0 +1,150 @@ +--- +title: Monitoring Silent Process Exit +description: Beginning with Windows 7, you can use the Silent Process Exit tab in GFlags to enter the name of a process that you want to monitor for silent exit. +ms.assetid: 116B2053-7F48-48B4-AEAC-333B7D9C38C7 +--- + +# Monitoring Silent Process Exit + + +Beginning with Windows 7, you can use the **Silent Process Exit** tab in GFlags to enter the name of a process that you want to monitor for silent exit. + +In the context of this monitoring feature, we use the term *silent exit* to mean that the monitored process terminates in one of the following ways. + +Self termination +The monitored process terminates itself by calling **ExitProcess**. + +Cross-process termination +A second process terminates the monitored process by calling **TerminateProcess**. + +The monitoring feature does not detect normal process termination that happens when the last thread of the process exits. The monitoring feature does not detect process termination that is initiated by kernel-mode code. + +To register a process for silent exit monitoring, open the **Silent Process Exit** tab in GFlags. Enter the process name as the **Image** and press the **Tab** key. Check the **Enable Silent Process Exit Monitoring** box, and click **Apply**. This sets the FLG\_MONITOR\_SILENT\_PROCESS\_EXIT flag in the following registry entry. + +**HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Image File Execution Options\\*ProcessName*\\GlobalFlag** + +For more information about this flag, see [Enable silent process exit monitoring](enable-silent-process-exit-monitoring.md). + +For more information about using the **Silent Process Exit** tab in GFlags, see [Configuring Silent Process Exit Monitoring](setting-and-clearing-flags-for-silent-process-exit.md). + +In the **Silent Process Exit** tab of GFlags, you can configure the actions that will take place when a monitored process exits silently. You can configure notification, event logging, and creation of dump files. You can specify a process that will be launched when silent exit is detected, and you can specify a list of modules that the monitor will ignore. Several of these settings are available both globally and for individual applications. Global settings apply to all processes that you register for silent exit monitoring. Application settings apply to an individual process and override global settings. + +Global settings are stored in the registry under the following key. + +**HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\SilentProcessExit** + +Application settings are stored in the registry under the following key. + +**HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\SilentProcessExit\\*ProcessName*** + +## Reporting Mode + + +The **Reporting Mode** setting is available as an application setting, but not as a global setting. You can use the following check boxes to set the reporting mode. + +**Launch monitor process** +**Enable dump collection** +**Enable notification** +The **ReportingMode** registry entry is a bitwise OR of the following flags. + +| Flag | Value | Meaning | +|------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| LAUNCH\_MONITORPROCESS | 0x1 | When silent exit is detected, the monitor process (specified in the **Monitor Process** box) is launched. | +| LOCAL\_DUMP | 0x2 | When silent exit is detected, a dump file is created for the monitored process. In the case of cross-process termination, a dump file is also created for the process that caused the termination. | +| NOTIFICATION | 0x4 | When silent exit is detected, a pop-up notification is displayed. | + +  + +## Ignore Self Exits + + +The **Ignore Self Exits** setting is available as an application setting, but not as a global setting. You can use the **Ignore Self Exits** check box to specify whether self exits are ignored. + +The **IgnoreSelfExits** registry entry has one of the following values. + +| Value | Meaning | +|-------|----------------------------------------------------------------------------| +| 0x0 | Detect and respond to both self termination and cross-process termination. | +| 0x1 | Ignore self termination. Detect and respond to cross-process termination. | + +  + +## Monitor Process + + +You can specify a monitor process by entering a process name, along with command line parameters, in the **Monitor Process** text box. You can use the following variables in your command line. + +| Varaible | Meaning | +|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| %e | ID of the exiting process. This is the monitored process that exited silently. | +| %i | ID of the initiating process. In the case of self termination, this is the same as the exiting process. In the case of cross-process termination, this is the ID of the process that caused the termination. | +| %t | ID of the initiating thread. This is the thread that caused the termination. | +| %c | The status code passed to **ExitThread** or **TerminateThread** . | + +  + +For example, the following value for **Monitor Process** specifies that on silent exit, WinDbg is launched and attached to the exiting process. + +**windbg -p %e** + +The **Monitor Process** command line is stored in the **MonitorProcess** registry entry. + +## Dump Folder Location + + +You can use the **Dump folder location** text box to specify a location for the dump files that are written when a silent exit is detected. + +The string that you enter for **Dump folder location** is stored in the **LocalDumpFolder** registry entry. + +If you do not specify a dump folder location, dump files are written to the default location, which is %TEMP%\\Silent Process Exit. + +## Dump Folder Size + + +You can use the **Dump folder size** text box to specify the maximum number of dump files that can be written to the dump folder. Enter this value as a decimal integer. + +The value that you enter for **Dump folder size** is stored in the **MaximumNumberOfDumpFiles** registry entry. + +By default, there is no limit to the number of dump files that can be written. + +## Dump Type + + +You can use the **Dump Type** drop-down list to specify the type of dump file (Micro, Mini, Heap, or Custom) that is written when a silent exit is detected. + +The dump type is stored in the **DumpType** registry entry, which is a bitwise OR of the members of the **MINIDUMP\_TYPE** enumeration. This enumeration is defined in dbghelp.h, which is included in the Debugging Tools for Windows package. + +For example, suppose you chose a dump type of **Micro**, and you see that the **DumpType** registry entry has a value of 0x88. The value 0x88 is a bitwise OR of the following two **MINIDUMP\_TYPE** enumeration values. + +| | | +|---------------------------|------------| +| MiniDumpFilterModulePaths | 0x00000080 | +| MiniDumpFilterMemory | 0x00000008 | + +  + +If you choose a dump type of **Custom**, enter your own bitwise OR of **MINIDUMP\_TYPE** enumeration values in the **Custom Dump Type** box. Enter this value as a decimal integer. + +## Module Ignore List + + +You can use the **Module Ignore List** box to specify a list of modules that will be ignored when a silent exit is detected. If the monitored process is terminated by one of the modules in this list, the silent exit is ignored. + +The list of modules that you enter in the **Module Ignore List** box is stored in the **ModuleIgnoreList** registry entry. + +## Reading Process Exit Reports in Event Viewer + + +When a monitored process exits silently, the monitor creates an entry in Event Viewer. To open Event Viewer, enter the command **eventvwr.msc**. Navigate to **Windows Logs > Application**. Look for log entries that have a **Source** of Process Exit Monitor. + +![event properties dialog box showing general tab displaying the source as process exit monitor](images/gflagssilentprocessexit02.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Monitoring%20Silent%20Process%20Exit%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remode-debugging-using-windbg.md b/windows-driver-docs-pr/debugger/remode-debugging-using-windbg.md new file mode 100644 index 0000000000..49376ffac3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remode-debugging-using-windbg.md @@ -0,0 +1,74 @@ +--- +title: Remote Debugging Using WinDbg +description: Remote debugging involves two debuggers running at two different locations. +ms.assetid: 3030CEE4-DF10-4F84-A32D-38613D7EE072 +--- + +# Remote Debugging Using WinDbg + + +Remote debugging involves two debuggers running at two different locations. The debugger that performs the debugging is called the *debugging server*. The second debugger, called the *debugging client*, controls the debugging session from a remote location. To establish a remote session, you must set up the debugging server first and then activate the debugging client. + +The code that is being debugged could be running on the same computer that is running the debugging server, or it could be running on a separate computer. If the debugging server is performing user-mode debugging, then the process that is being debugged can run on the same computer as the debugging server. If the debugging server is performing kernel-mode debugging, then the code being debugged would typically run on a separate target computer. + +The following diagram illustrates a remote session where the debugging server, running on a host computer, is performing kernel-mode debugging of code that is running on a separate target computer. + +![diagram that shows remote, host, and target computers](images/clientservertarget.png) + +There are several transport protocols you can use for a remote debugging connection: TCP, NPIPE, SPIPE, SSL, and COM Port. Suppose you have chosen to use TCP as the protocol and you have chosen to use WinDbg as both the debugging client and the debugging server. You can use the following procedure to establish a remote kernel-mode debugging session: + +1. On the host computer, open WinDbg and establish a kernel-mode debugging session with a target computer. (See [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md).) +2. Break in by choosing **Break** from the **Debug** menu or by pressing CRTL-Break. +3. In the [Debugger Command Window](debugger-command-window.md), enter the following command. + + **.server tcp:port=5005** + + **Note**  The port number 5005 is arbitrary. The port number is your choice. + +   + +4. WinDbg will respond with output similar to the following. + + ``` + Server started. Client can connect with any of these command lines + 0: -remote tcp:Port=5005,Server=YourHostComputer + ``` + +5. On the remote computer, open WinDbg, and choose **Connect to Remote Session** from the **File** menu. +6. Under **Connection String**, enter the following string. + + **tcp:Port=5005,Server=***YourHostComputer* + + where *YourHostComputer* is the name of your host computer, which is running the debugging server. + + Click **OK**. + +## Using the Command Line + + +As an alternative to the procedure given in the preceding section, you can set up a remote debugging session at the command line. Suppose you are set up to establish a kernel-mode debugging session, between a host computer and a target computer, over a 1394 cable on channel 32. You can use the following procedure to establish a remote debugging session: + +1. On the host computer, enter the following command in a Command Prompt window. + + **windbg -server tcp:port=5005 -k 1394:channel=32** + +2. On the remote computer, enter the following command in a Command Prompt window. + + **windbg -remote tcp:Port=5005,Server=***YourHostComputer* + + where *YourHostComputer* is the name of your host computer, which is running the debugging server. + +## Additional Information + + +There are many ways to establish remote debugging other than the ones shown in this topic. For complete information about setting up a debugging server in the WinDbg [Debugger Command Window](debugger-command-window.md), see [**.server (Create Debugging Server)**](-server--create-debugging-server-.md). For complete information about launching WinDbg (and establishing remote debugging) at the command line, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-client-syntax.md b/windows-driver-docs-pr/debugger/remote-client-syntax.md new file mode 100644 index 0000000000..2d64450753 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-client-syntax.md @@ -0,0 +1,103 @@ +--- +title: Remote Client Syntax +description: To start the client side of the Remote tool, use the following syntax at the command line. +ms.assetid: 4728ef17-a365-4024-815c-2719b51b81f6 +keywords: ["Remote Client Syntax Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Remote Client Syntax +api_type: +- NA +--- + +# Remote Client Syntax + + +To start the client side of the Remote tool, use the following syntax at the command line. + +``` +remote /c Server SessionName [/L Lines] [/f] [/b] [/k ColorFile] +``` + +## Parameters + + + **/c** +Connects the client to a remote session. + + *Server* +Specifies the computer name of the server that established the session. + + *SessionName* +Specifies the name of the remote session. This parameter is not case-sensitive. + + **/L** *Lines* +Specifies the number of lines from the console display that are sent to the client computer. The default is 200 lines. *Lines* is a decimal number. + + **/f** +Specifies the color of the text in the server command window. + + **/b** +Specifies the background color of the server command window. + + *Color* +Specifies a color. Valid values are black, blue, green, cyan, red, purple, yellow, white, lblack, lblue, lgreen, lred, lpurple, lyellow, and lwhite. + + **/k** *ColorFile* +Indicates the path (optional) and name of a formatted text file that specifies the colors for displaying the output on the client computer. + +The color file associates keywords in the output with text colors. When the keywords appear in a line of output, the Remote tool applies the associated text color to that line. For the format of the file, see "Remarks". + + **/q** *Computer* +Displays the remote sessions available on the specified computer. Only visible sessions appear in the list. (See **/v** in [**Remote Server Syntax**](remote-server-syntax.md).) + +### Comments + +The *Server* and *SessionName* parameters must appear in the order shown on the syntax line. + +To disconnect from a remote session, type **@q**. For more information, see [Remote Session Commands](remote-session-commands.md). + +**Keyword Color File.** The format of the keyword color file is as follows. The keyword interpreter is not case sensitive. + +The keyword or phrase appears on a line by itself. The colors associated with that keyword appear by themselves on the following line, as shown in the syntax: + +``` +Keyword +TextColor[, BackgroundColor] +``` + +For example, the following file directs Remote to display lines that include the word "error" in black text on a light red background; to display lines that include the word "warning" in light blue (on the default background), and lines that include the phrase "Windows Vista" in light green on the default background. + +``` +ERROR +black, lred +WARNING +lblue +Windows Vista +lgreen +``` + +### Sample Usage + +``` +remote /c Server01 TestSession +remote /c Domain1\ComputerA0 "cmd" "My Remote Session" +remote /c Server01 TestSession /L 50 /f black /b white /k c:\remote_file.txt +remote /q Server01 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Client%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging-on-workgroup-computers.md b/windows-driver-docs-pr/debugger/remote-debugging-on-workgroup-computers.md new file mode 100644 index 0000000000..f75a583a16 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging-on-workgroup-computers.md @@ -0,0 +1,76 @@ +--- +title: Remote Debugging on Workgroup Computers +description: You can perform remote debugging with computers that are joined to a workgroup. +ms.assetid: 0E740E1A-8DEA-4086-AE9D-6B135BF278B0 +--- + +# Remote Debugging on Workgroup Computers + + +You can perform remote debugging with computers that are joined to a workgroup. First configure the computer that will run the debugging server. Then activate the debugging server. After the debugging server is activated, you can connect to the server from a debugging client. + +## Configuring the debugging server computer + + +- Create a local administrator account, and log on using that account. +- Enable file and printer sharing for your active network. For example if your active network is Private, enable file and printer sharing for Private networks. + + You can use Control Panel to enable file and printer sharing. For example, here are the steps in Windows 8. + + 1. Open Control Panel. + 2. Click **Network and Internet** and then **Network and Sharing Center**. Under **View your active networks**, note the type of network (for example, Private) that is active. + 3. Click **Change advanced sharing settings**. For your active network type, select **Turn on network discovery** and **Turn on file and printer sharing**. +- Start the remote registry service by following these steps. + + 1. In a Command Prompt window or in the Run box, enter **services.msc**. + 2. Right click **Remote Registry**, and choose **Start**. +- Turn off the ForceGuest feature by following these steps. + + 1. In a Command Prompt window or in the Run box, enter **regedit**. + 2. In Registry Editor, set this value to 0. + + **HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Lsa ForceGuest** + +## Activating the debugging server + + +You can activate the debugging server through the debugger or by using a process server or a KD connection server. For more information, see the following topics. + +- [**Activating a Debugging Server**](activating-a-debugging-server.md) +- [**Activating a Process Server**](activating-a-process-server.md) +- [**Activating a KD Connection Server**](activating-a-kd-connection-server.md) + +## Activating the debugging client + + +There are several ways to activate a debugging client. For more information, see the following topics. + +- [**Activating a Debugging Client**](activating-a-debugging-client.md) +- [**Activating a Smart Client**](activating-a-smart-client.md) +- [**Activating a Smart Client (Kernel Mode)**](activating-a-smart-client--kernel-mode-.md) +- [**Searching for Process Servers**](searching-for-process-servers.md) +- [**Searching for KD Connection Servers**](searching-for-kd-connection-servers.md) + +**Note**   +If you are using a named pipe to connect a debugging client to a debugging server, you must provide the user name and password of an account that has access to the computer running the debugging server. Use one, but not both, of the following options. + +- Log on to the debugging client computer with an account that shares the user name and password of an account on the debugging server computer. +- On the debugging client computer, in a Command Prompt window, enter the following command. + + **net use \\\\***Server***\\ipc$ /user:***UserName* + + where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + + When you are prompted, enter the password for *UserName*. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20on%20Workgroup%20Computers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging-through-remote-exe.md b/windows-driver-docs-pr/debugger/remote-debugging-through-remote-exe.md new file mode 100644 index 0000000000..d420f3a446 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging-through-remote-exe.md @@ -0,0 +1,43 @@ +--- +title: Remote Debugging Through Remote.exe +description: Remote Debugging Through Remote.exe +ms.assetid: 138cd409-bf89-498a-8c7c-74fca7c227d5 +keywords: ["remote debugging through remote.exe", "remote debugging through remote.exe, overview", "Remote.exe", "Remote.exe, overview", "Remote.exe, Remote.exe Client", "Remote.exe, Remote.exe Server"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Debugging Through Remote.exe + + +## + + +Remote debugging through remote.exe involves running the debugger on the remote computer and running the remote.exe tool on the local computer. + +The remote computer and the local computer can be running any Windows operating system. + +**Note**   Since remote.exe only works for console applications, it cannot be used to remotely control WinDbg. + +  + +This section includes: + +[The Remote.exe Utility](the-remote-exe-utility.md) + +[Starting a Remote.exe Session](starting-a-remote-exe-session.md) + +[Remote.exe Batch Files](remote-exe-batch-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20Through%20Remote.exe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging-through-the-debugger.md b/windows-driver-docs-pr/debugger/remote-debugging-through-the-debugger.md new file mode 100644 index 0000000000..2433b59ac1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging-through-the-debugger.md @@ -0,0 +1,51 @@ +--- +title: Remote Debugging Through the Debugger +description: Remote Debugging Through the Debugger +ms.assetid: a9f6f355-e684-471f-a45c-b2235a5372b1 +keywords: ["remote debugging through the debugger", "remote debugging through the debugger, overview", "debugging client", "debugging server", "TCP (remote debugging protocol)", "COM port (remote debugging protocol)", "modem (remote debugging protocol)", "named pipe (remote debuggi"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Debugging Through the Debugger + + +## + + +Remote debugging directly through the debugger is usually the best and easiest method of performing remote debugging. + +This technique involves running two debuggers at different locations. The debugger that is actually doing the debugging is called the *debugging server*. The debugger that is controlling the session from a distance is called the *debugging client*. + +The two computers do not have to be running the same version of Windows; they can be running any version of Windows. The actual debuggers used need not be the same; a WinDbg debugging client can connect to a CDB debugging server, and so on. + +However, it is best that the debugger binaries on the two computers both be from the same release of the Debugging Tools for Windows package, or at least both from recent releases. + +To set up this remote session, the debugging server is set up first, and then the debugging client is activated. Any number of debugging clients can connect to a debugging server. A single debugger can turn itself into several debugging servers at the same time, to facilitate different kinds of connections. + +However, no single debugger can be a debugging client and a debugging server simultaneously. + +This section includes: + +[Activating a Debugging Server](activating-a-debugging-server.md) + +[Searching for Debugging Servers](searching-for-debugging-servers.md) + +[Activating a Debugging Client](activating-a-debugging-client.md) + +[Client and Server Examples](client-and-server-examples.md) + +[Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20Through%20the%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging-using-kd.md b/windows-driver-docs-pr/debugger/remote-debugging-using-kd.md new file mode 100644 index 0000000000..6bf3b35dec --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging-using-kd.md @@ -0,0 +1,56 @@ +--- +title: Remote Debugging Using KD +description: Remote debuggng involves two debuggers running at two different locations. +ms.assetid: 274CAB1D-DD3B-4ACD-919C-8B8C253BCE50 +--- + +# Remote Debugging Using KD + + +Remote debuggng involves two debuggers running at two different locations. The debugger that performs the debugging is called the *debugging server*. The second debugger, called the *debugging client*, controls the debugging session from a remote location. To establish a remote session, you must set up the debugging server first and then activate the debugging client. + +The code that is being debugged could be running on the same computer that is running the debugging server, or it could be running on a separate computer. If the debugging server is performing user-mode debugging, then the process that is being debugged can run on the same computer as the debugging server. If the debugging server is performing kernel-mode debugging, then the code being debugged would typcially run on a separate target computer. + +The following diagram illustrates a remote session where the debugging server, running on a host computer, is performing kernel-mode debugging of code that is running on a separate target computer. + +![diagram that shows remote, host, and target computers](images/clientservertarget.png) + +There are several transport protocols you can use for a remote debugging connection: TCP, NPIPE, SPIPE, SSL, and COM Port. Suppose you have chosen to use TCP as the protocol and you have chosen to use KD as both the debugging client and the debugging server. You can use the following procedure to establish a remote kernel-mode debugging session: + +1. On the host computer, open KD and establish a kernel-mode debugging session with a target computer. (See [Performing Kernel-Mode Debugging Using KD](performing-kernel-mode-debugging-using-kd.md).) +2. Break in by pressing CRTL-Break. +3. Enter the following command. + + **.server tcp:port=5005** + + **Note**  The port number 5005 is arbitrary. The port number is your choice. + +   + +4. KD will respond with output similar to the following. + + ``` + Server started. Client can connect with any of these command lines + 0: -remote tcp:Port=5005,Server=YourHostComputer + ``` + +5. On the remote computer, open a Command Prompt window, and enter the following command. + + **kd -remote tcp:Port=5005,Server=***YourHostComputer* + + where *YourHostComputer* is the name of your host computer, which is running the debugging server. + +## Additional Information + + +For complete information about launching KD (and establishing remote debugging) at the command line, see [**KD Command-Line Options**](kd-command-line-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20Using%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging-using-visual-studio.md b/windows-driver-docs-pr/debugger/remote-debugging-using-visual-studio.md new file mode 100644 index 0000000000..17bb6d880c --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging-using-visual-studio.md @@ -0,0 +1,25 @@ +--- +title: Remote Debugging Using Visual Studio +description: The procedure covers Remote Debugging Using Visual Studio. +ms.assetid: 9FA347BF-878E-46C8-8459-DC73A8B1EB26 +--- + +# Remote Debugging Using Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +To perform remote debugging using Visual Studio: + +1. On the remote computer, in Visual Studio, choose **Connect to Remote Debugger** from the **Tools** menu. +2. In the **Connect to Remote Debugger** dialog box, enter a connection string, and click **Connect**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20Using%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging.md b/windows-driver-docs-pr/debugger/remote-debugging.md new file mode 100644 index 0000000000..61f072d4fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging.md @@ -0,0 +1,49 @@ +--- +title: Remote Debugging +description: This topic provides an overview of remote user-mode debugging. This involves two computers: the client and the server. +ms.assetid: fa87b55c-c339-4b8c-8614-c7355d203a6e +keywords: remote debugging +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Debugging + + +## + + +Remote user-mode debugging involves two computers: the *client* and the *server*. The server is the computer that runs the application to be debugged. The server also runs the user-mode debugger or a process server. The client is the computer that remotely controls the debugging session. + +Remote kernel-mode debugging involves three computers: the *client*, the *server*, and the *target computer*. The target computer is the computer to be debugged. The server is a computer that runs the kernel debugger or a KD connection server. The client is the computer that remotely controls the debugging session. + +[Choosing the Best Remote Debugging Method](choosing-the-best-remote-debugging-method.md) + +[Remote Debugging Through the Debugger](remote-debugging-through-the-debugger.md) + +[Controlling the User-Mode Debugger from the Kernel Debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md) + +[Remote Debugging Through Remote.exe](remote-debugging-through-remote-exe.md) + +[Process Servers (User Mode)](process-servers--user-mode-.md) + +[KD Connection Servers (Kernel Mode)](kd-connection-servers--kernel-mode-.md) + +[Repeaters](repeaters.md) + +[Advanced Remote Debugging Scenarios](advanced-remote-debugging-scenarios.md) + +[Remote Debugging on Workgroup Computers](remote-debugging-on-workgroup-computers.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-debugging5.md b/windows-driver-docs-pr/debugger/remote-debugging5.md new file mode 100644 index 0000000000..c71dddf8a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-debugging5.md @@ -0,0 +1,42 @@ +--- +title: Remote Debugging (Debugger Engine) +description: Remote debugging occurs when a client's communication with a target is indirect, for example, through a network connection. +ms.assetid: e52cc5fb-9f10-415e-9fe8-6eba71daab6d +keywords: ["Debugger Engine, remote debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Debugging + + +Remote debugging occurs when a client's communication with a target is indirect, for example, through a network connection. When remote debugging, more than one instance of the debugger engine can be involved in debugging a target. However, exactly one of these instances is responsible for the debugging session; this instance is called the *host engine*. + +There are many possible configurations: the client object can be created in the host engine (smart clients), or a different instance of the engine (debugging clients); the host engine can be connected directly to the target (debugging server); or a proxy can be directly connected to the target (process server and kernel connection server). + +Multiple clients can simultaneously connect to the host engine. And the host engine can connect to multiple targets in the same debugging session. Optionally, there can be one or more proxies between the clients and the host engine and between the host engine and each target. + +Smart clients are client objects that communicate directly with the host engine. A debugging client is created by calling [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465); the client communicates with the host engine using RPC calls that represent method calls in the engine's API (including calls that the host engine makes to the client's [callback objects](client-objects.md#callback-objects)). + +A debugging server is an engine instance that communicates directly with the target and is also the host engine. Process servers and kernel connection servers communicate directly with the target but are not the host engine. The host engine communicates with the process server, or kernel connection server, by sending low-level memory, processor, and operating system requests, and the server sends back the results. + +**Note**   A typical two-computer setup for kernel debugging--where one computer is the target and the other the host computer--is not considered to be remote debugging as there is only one instance of the engine (on the host computer) and it communicates directly with the target. + +  + +### Additional Information + +For details about performing remote debugging, see [Remote Targets](remote-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-exe-batch-files.md b/windows-driver-docs-pr/debugger/remote-exe-batch-files.md new file mode 100644 index 0000000000..9f7633a7ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-exe-batch-files.md @@ -0,0 +1,59 @@ +--- +title: Remote.exe Batch Files +description: Remote.exe Batch Files +ms.assetid: e774d39f-4625-41e7-9309-9dbdd46e986e +keywords: ["remote debugging through remote.exe, batch files"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote.exe Batch Files + + +## + + +As a more detailed example of remote debugging with remote.exe, assume the following about a local host computer in a three-computer kernel debugging scenario: + +- Debugging needs to take place over a null-modem cable on COM2. + +- The symbol files are in the folder c:\\winnt\\symbols. + +- A log file called debug.log is created in **c:\\temp**. + +The log file holds a copy of everything you see on the Debug screen during your debug session. All input from the person doing the debugging, and all output from the kernel debugger on the target system, is written to that log file. + +A sample batch file for running a debugging session on the local host is: + +``` +set _NT_DEBUG_PORT=com2 +set _NT_DEBUG_BAUD_RATE=19200 +set _NT_SYMBOL_PATH=c:\winnt\symbols +set _NT_LOG_FILE_OPEN=c:\temp\debug.log +remote /s "KD -v" debug +``` + +**Note**   If this batch file is not in the same directory as Remote.exe, and Remote.exe is not in a directory listed in the system path, then you should give the full path to the utility when invoking Remote.exe in this batch file. + +  + +After this batch file is run, anyone with a Windows computer that is networked to the local host computer can connect to the debug session by using the following command: + +``` +remote /c computername debug +``` + +where *computername* is the NetBIOS name of the local host computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote.exe%20Batch%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-server-query-command.md b/windows-driver-docs-pr/debugger/remote-server-query-command.md new file mode 100644 index 0000000000..628643a974 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-server-query-command.md @@ -0,0 +1,65 @@ +--- +title: Remote Server Query Command +description: To display a list of available sessions on a local or Remote Server, use the following syntax. +ms.assetid: c95114a3-2ff5-456b-90e2-4d7bc6346f1f +keywords: ["Remote Server Query Command Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Remote Server Query Command +api_type: +- NA +--- + +# Remote Server Query Command + + +To display a list of available sessions on a local or Remote Server, use the following syntax. + +``` +remote /q Computer +``` + +## Parameters + + + **/q** +Query. Displays the visible remote sessions on the specified computer. + + *Computer* +Specifies the name of the computer. This parameter is required (even on the local computer). + +### Comments + +The query display includes only server sessions; it does not display client connections to remote sessions. + +The query display includes only visible sessions. There is no command to display invisible sessions. + +The query display includes all visible sessions, including those that restrict users (**/u** and **/ud**). The user might not have permission to connect to all of the sessions in the list. + +When there are no remote sessions running on the server, the Remote tool displays the following message: + +``` +No Remote servers running on \\Computer +``` + +However, when the only remote sessions running on the computer are invisible remote sessions, the Remote tool displays the following message: + +``` +No visible sessions on server \\Computer +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Server%20Query%20Command%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-server-syntax.md b/windows-driver-docs-pr/debugger/remote-server-syntax.md new file mode 100644 index 0000000000..bea0b35a68 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-server-syntax.md @@ -0,0 +1,93 @@ +--- +title: Remote Server Syntax +description: To start the server side of the Remote tool, use the following syntax at the command line. +ms.assetid: fecc9f43-6946-4d99-840b-a85c75ac397c +keywords: ["Remote Server Syntax Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Remote Server Syntax +api_type: +- NA +--- + +# Remote Server Syntax + + +To start the server side of the Remote tool, use the following syntax at the command line. + +``` +remote /s Command SessionName [/f Color] [/b] [/u User [/u User...]] [/ud User [/ud User...]] [/v | /-v] +``` + +## Parameters + + + **/s** +Starts a server session. + + *Command* +Specifies the command that starts the console-based program. The command can include parameters. If the command includes spaces, enclose it in quotation marks. + + *SessionName* +Assigns a name to the remote session. If the name includes spaces, enclose it in quotation marks. This parameter is not case-sensitive. + + **/f** +Specifies the color of the text in the server command window. + + **/b** +Specifies the background color of the server command window. + + *Color* +Specifies a color. Valid values are black, blue, green, cyan, red, purple, yellow, white, lblack, lblue, lgreen, lred, lpurple, lyellow, and lwhite. + + **/u** +Specifies users or groups that are permitted to connect to the remote session; by default, everyone is permitted. When you use this parameter, everyone is denied permission, except for the users and groups specified by the *User* subparameter. + + **/ud** +Specifies users or groups that are denied permission to connect to the remote session; by default, no one is denied permission. + + *User* +Specifies the name of a user or group in \[*domain* | *computer*\]\\{*user* | *group*} format. When specifying users or groups on the local computer, omit the computer name. + + **/v** +Makes a session visible. For more information, see [Visible Session](remote-tool-concepts.md#visible-session). + +By default, only debugger sessions are visible, that is, sessions in which the value of the *Command* parameter include the words **kd**, **dbg**, **remoteds**, **ntsd**, or **cdb**; otherwise, the session is not visible. + + **-v** +Makes a remote debugger session invisible. For more information, see [Visible Session](remote-tool-concepts.md#visible-session). + +### Comments + +The *Command* and *SessionName* parameters must appear in the order shown on the syntax line. + +To end a remote session, type **@k**. For more information, see [Remote Session Commands](remote-session-commands.md). + +The Remote tool will not create a session that the current user does not have permission to join. + +When starting more than one remote session on a single computer, open a new command window for each session. Also, use a different session name for each session. Because the session names are used to label the named pipes, they must be unique on the computer. + +### Sample Usage + +``` +remote /s "i386kd -v" TestSession +remote /s "cmd" "My Remote Session" /f white /b black /u Server01\Administrators +remote /s "ntsd -d -g -x" DebugIt /-v +remote /q Server01 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Server%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-session-commands.md b/windows-driver-docs-pr/debugger/remote-session-commands.md new file mode 100644 index 0000000000..5b25373183 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-session-commands.md @@ -0,0 +1,50 @@ +--- +title: Remote Session Commands +description: Remote Session Commands +ms.assetid: 8c7da3e9-c983-4253-92fb-ce64f22cdc6c +keywords: ["Remote Tool, remote session commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Session Commands + + +## + + +Use the following commands to communicate with the Remote tool during a console session. + +**@H** +Displays the session commands on server and client computers. Works on server and client computers. + +**@M** *Message* +Displays the specified message on all server and client computers in the session. Works on server and client computers. + +**@P** *Message* +Generates a pop-up window on the server computer with the specified message. On client computers, the message appears in the command window. Works on server and client computers. + +**@Q** +Quit. Disconnects a client computer from the session. Works only on a client computer. + +**@K** +Disconnects all clients and ends the remote session. Works only on a server computer. + +### Comments + +For samples, see "Using the Session Commands" in [Remote Tool Examples](remote-tool-examples.md). + +In response to the session commands, the Remote tool displays a label with the day and time that the command was executed. The time for all events is displayed in the time zone of the server computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Session%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-targets.md b/windows-driver-docs-pr/debugger/remote-targets.md new file mode 100644 index 0000000000..d051fadf82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-targets.md @@ -0,0 +1,53 @@ +--- +title: Remote Targets +description: Remote Targets +ms.assetid: ed7ea3dc-07d1-481c-90e0-7f0b0e77ad42 +keywords: ["Debugger Engine API, targets, remote", "Debugger Engine API, debugging servers", "Debugger Engine API, process servers", "Debugger Engine API, kernel connection servers", "Debugger Engine API, smart clients"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Targets + + +## + + +There are two different forms of remote debugging, depending on which computer (remote client or server) is the host computer. The *host computer* is the computer on which the [debugger engine](introduction.md#debugger-engine) is active. On the other computer, the debugger engine is merely acting as a proxy relaying commands and data to the host engine. + +All debugger operations -- such as executing commands and [extensions](introduction.md#extensions), and symbol loading -- are performed by the host engine. A debugger session is also relative to the host engine. + +To list the debugging servers and process servers currently running on a computer, use [**OutputServers**](https://msdn.microsoft.com/library/windows/hardware/ff553247). + +### Debugging Servers and Debugging Clients + +A *debugging server* is an instance of the debugger engine acting as a host and listening for connections from debugging clients. The method [**StartServer**](https://msdn.microsoft.com/library/windows/hardware/ff558813) will tell the debugger engine to start listening for connections from debugging clients. + +A *debugging client* is an instance of the debugger engine acting as a proxy, sending debugger commands and I/O to the debugging server. The function [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465) can be used to connect to the debugging server. + +The client object returned by **DebugConnect** is not automatically joined to the debugger session on the debugging server. The method [**ConnectSession**](https://msdn.microsoft.com/library/windows/hardware/ff539245) can be used to join the session, synchronizing input and output. + +The communication between a debugging server and a debugging client mostly consists of debugger commands and RPC calls sent to the server, and command output sent back to the client. + +### Process Servers, Kernel Connection Servers, and Smart Clients + +*Process servers* and *kernel connection servers* are both instances of the debugger engine acting as proxies, listening for connections from smart clients, and performing memory, processor, or operating system operations as requested by these remote clients. A *process server* facilitates the debugging of processes that are running on the same computer. A *kernel connection server* facilitates the debugging of a Windows kernel debugging target that is connected to the computer that is running the connection server. A process server can be started using the method [**StartProcessServer**](https://msdn.microsoft.com/library/windows/hardware/ff558810) or the program [DbgSrv](process-servers--user-mode-.md). The method [**WaitForProcessServerEnd**](https://msdn.microsoft.com/library/windows/hardware/ff561230) will wait for a process server started with **StartProcessServer** to end. A kernel connection server can be activated using the program [**KdSrv**](activating-a-kd-connection-server.md). + +A *smart client* is an instance of the debugger engine acting as a host engine and connected to a process server. The method [**ConnectProcessServer**](https://msdn.microsoft.com/library/windows/hardware/ff539237) will connect to a process server. Once connected, the methods described in [Live User-Mode Targets](live-user-mode-targets.md) can be used. + +When the remote client is finished with the process server, it can disconnect using [**DisconnectProcessServer**](https://msdn.microsoft.com/library/windows/hardware/ff541969), or it can use [**EndProcessServer**](https://msdn.microsoft.com/library/windows/hardware/ff542993) to request that the process server shut down. To shut down the process server from the computer that it is running on, use Task Manager to end the process. If the instance of the debugger engine that used **StartProcessServer** is still running, it can use [**Execute**](https://msdn.microsoft.com/library/windows/hardware/ff543208) to issue the debugger command [**.endsrv 0**](-endsrv--end-debugging-server-.md), which will end the process server (this is an exception to the usual behavior of **.endsrv**, which generally does not affect process servers). + +The communication between a process server and a smart client typically consists of low-level memory, processor, and operating system operations and requests that are sent from the remote client to the server. Their results are then sent back to the client. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-tool-commands.md b/windows-driver-docs-pr/debugger/remote-tool-commands.md new file mode 100644 index 0000000000..7a126bd51e --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-tool-commands.md @@ -0,0 +1,41 @@ +--- +title: Remote Tool Commands +description: Remote Tool Commands +ms.assetid: 23ce5a62-dcea-4460-a354-f391c105e3bd +keywords: ["Remote Tool, commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Tool Commands + + +## + + +The Remote tool has a separate command syntax for the client and server sides of a session. Commands to start a server session must be entered first because they establish the communications pipe to which the client connects. + +The Remote tool also has a query command and a separate set of commands that you use to communicate with the Remote tool (instead of the console program) during a remote session. + +These commands are described in the following topics: + +[**Remote Server Syntax**](remote-server-syntax.md) + +[**Remote Client Syntax**](remote-client-syntax.md) + +[**Remote Server Query Command**](remote-server-query-command.md) + +[Remote Session Commands](remote-session-commands.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Tool%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-tool-concepts.md b/windows-driver-docs-pr/debugger/remote-tool-concepts.md new file mode 100644 index 0000000000..2b19c61a71 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-tool-concepts.md @@ -0,0 +1,55 @@ +--- +title: Remote Tool Concepts +description: Remote Tool Concepts +ms.assetid: 509b25cd-d69a-442d-bd5b-a69266d341c3 +keywords: ["Remote Tool, Remote Tool Concepts"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Tool Concepts + + +## + + +The following concepts are used in the Remote tool. + +### Client and Server + +The Remote tool uses a client-server paradigm that avoids the words *local* and *remote*, which are relative terms that can be confusing when there are multiple users and multiple computers. + +Commands that you type at the client and server computers appear in the Command Prompt windows of both computers. + +### The Server + +The *server* is the computer on which the console program runs. The *Remote Server* is the instance of the Remote tool running on the server. The server establishes and names the remote session (named pipe), issues the command to start the console program, and determines who is permitted to connect to the session. + +### The Client + +The *client* is a remote computer that sends commands to the console program. The *Remote Client* is the instance of the Remote tool running on the client computer. The client connects to the remote session that the server established and uses the remote session (named pipe) that the server created to send commands to the console program that runs on the server. + +The Remote tool supports multiple clients in each remote session. Each client is running one Remote Client. All of the clients can send commands to the console program running on the server, and all of the clients can see the commands sent and output displayed. + +### Visible Session + +When remote sessions are *visible*, they appear in the list of remote sessions on the computer. To display the list, use the [**Remote Server query command**](remote-server-query-command.md) (**/q**). + +By default, only debugger sessions are visible, that is, sessions in which the value of the *Command* parameter include the words **kd**, **dbg**, **remoteds**, **ntsd**, or **cdb**; otherwise, the session is not visible. The *Command* parameter is part of the Remote tool command on the server. + +To make a session visible, add the **/v** parameter to the [**Remote Server**](remote-server-syntax.md) command. To make a debugger session invisible, add the **/-v** parameter to the command. + +For help with the Remote Server query command, see [**Remote Server Query Command**](remote-server-query-command.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Tool%20Concepts%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-tool-examples.md b/windows-driver-docs-pr/debugger/remote-tool-examples.md new file mode 100644 index 0000000000..81fd50192b --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-tool-examples.md @@ -0,0 +1,244 @@ +--- +title: Remote Tool Examples +description: Remote Tool Examples +ms.assetid: 624f1a78-04da-45c2-8f8d-a593d557be7d +keywords: ["Remote Tool, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Tool Examples + + +## + + +The examples in this section demonstrate the use of the Remote tool and show sample input and output. + +### Basic Server Command + +The following command starts a remote session on the computer. + +The command uses the **/s** parameter to indicate a server-side command. It uses the command, **cmd**, to start the Windows command shell (Cmd.exe), and names the session **test1**. + +``` +remote /s cmd test1 +``` + +In response, the Remote tool starts the session and displays the command that clients would use to connect to the session. + +``` +************************************** +*********** REMOTE ************ +*********** SERVER ************ +************************************** +To Connect: Remote /C SERVER06 "test1" + +Microsoft Windows XP [Version 5.1.2600] +(C) Copyright 1985-2001 Microsoft Corp. +``` + +### Basic Client Command + +The following command connects to a remote session on the Server01 computer. The command uses the **/c** parameter to indicate a client-side command. It specifies the name of the server computer, **Server01**, and the name of the session on that computer, **test1**. + +``` +remote /c server01 test1 +``` + +In response, the Remote tool displays a message reporting that the client computer is connected to the session on the server computer. The message displays the name of the server computer and local user (**Server04 user1**). + +``` +************************************** +*********** REMOTE ************ +*********** CLIENT ************ +************************************** +Connected... + +Microsoft Windows XP [Version 5.1.2600] +(C) Copyright 1985-2001 Microsoft Corp. + +C:\Program Files\Debugging Tools for Windows> +**Remote: Connected to SERVER04 user1 [Tue 9:39 AM] +``` + +After the client connects to the server, the commands typed at the command prompt on the client and server computers appear on both displays.. + +For example, if you type **dir** at the command prompt of the client computer, the directory display appears in the Command Prompt window on both the client and server computers. + +### Using Server Options + +The following server-side command starts a remote session with the NTSD debugger. + +The command uses the **/s** parameter to indicate a server-side command. The next parameter, **"ntsd -d -v"**, is the console command that starts the debugger, along with the debugger options. Because the console command includes spaces, it is enclosed in quotation marks. The command includes a name for the session, **debugit**. + +The command uses the **/u** parameter to permit only administrators of the computer and a particular user, User03 in Domain01, to connect to the session. It uses the **/f** and **/b** options to specify black text (foreground) on a white background. + +Finally, the command uses the **/-v** parameter to make the session invisible to user queries. Debugger sessions are visible by default. + +``` +remote /s "ntsd -d -v" DebugIt /u Administrators /u Domain01\User03 +/f black /b white /-v +``` + +In response, the Remote tool creates a session named DebugIt and starts NTSD with the specified parameters. The message indicates that only the specified users have permission to connect. It also changes the command window to the specified colors. + +``` +************************************** +*********** REMOTE ************ +*********** SERVER ************ +************************************** + +Protected Server! Only the following users or groups can connect: + Administrators + Domain01\User03 +To Connect: Remote /C SERVER06 "debugit" + +Microsoft Windows XP [Version 5.1.2600] +(C) Copyright 1985-2001 Microsoft Corp. +``` + +### Using Client Options + +The following command connects to the remote session with the NTSD debugger that was started in the previous example. + +The command uses the **/c** parameter to indicate a client-side command. It specifies the name of the server computer, **server06**, and the name of the remote session, **debugit**. + +The command also includes the **/k** parameter to specify the location of a keyword color file. + +``` +remote /c server06 debugit /k c:\remote_client.txt +``` + +The color file includes the following text: + +``` +Registry +white, blue +Token +red, white +``` + +This text instructs the Remote tool to display lines of output with the word "registry" (not case sensitive) in white text on a blue background and to display lines of output with the word "token" in red text on a white background. + +In response, the Remote tool connects the client to the server session and displays the following message. + +``` +************************************** +*********** REMOTE ************ +*********** CLIENT ************ +************************************** +Connected... + +Microsoft Windows XP [Version 5.1.2600] +(C) Copyright 1985-2001 Microsoft Corp. +``` + +The client can now send commands to the NTSD debugger on the server computer. The output from the command appears on both the client and server computers. + +Lines of output with the word "registry" are displayed on the client computer in white text on a blue background, and lines of output with the word "kernel" in red text on a white background. + +### Querying a Session + +The Remote tool includes a query parameter (**/q**) that displays a list of remote sessions on a particular computer. The display includes only visible sessions (debugger sessions started without the **/-v** parameter and non-debugger sessions started with the **/v** parameter). + +You can query for sessions from the server or client computers. You must specify the computer name, even when querying for sessions on the local computer. + +The following command queries for sessions on the local computer, **Server04**. + +``` +remote /q Server04 +``` + +In response, the Remote tool reports that there are no remote sessions running on the local computer. + +``` +Querying server \\Server04 +No Remote servers running on \\Server04 +``` + +In contrast, in response to a query about sessions on a different computer, **Server06**, the Remote tool lists the sessions running on that computer. + +``` +Querying server \\Server06 + +Visible sessions on server Server06: + +ntsd [Remote /C SERVER06 "debug"] visible +cmd [Remote /C SERVER06 "test"] visible +``` + +The display lists the visible sessions, the console programs running on those sessions (NTSD and the Command Prompt window), and the command that connects to the session. The session name appears in the command syntax in quotation marks. + +The display does not show the permissions established for these sessions, if any. Therefore, the display might include sessions that you do not have permission to join. + +### Using the Session Commands + +You can use the remote session commands at any time during a remote session. + +The following command sends a message to all computers connected to the session. + +``` +@M I think I found the problem. +``` + +As a result, the message appears in the Command Prompt windows of all computers in the session. The message includes the computer name and the day and time of the message. + +``` +@m I think I found the problem. [SERVER01 Wed 11:53 AM] +``` + +When the message is sent from the server computer, "Local" appears in the label instead of the computer name. + +``` +@m I think I found the problem. [Local Wed 11:52 AM] +``` + +The following command generates a pop-up message that appears on the server computer. On all client computers in the session, it writes a message to the Command Prompt window. + +``` +@P Did you see that? +``` + +On client computers, the pop-up message appears in the command window. + +``` +From SERVER02 [Wed 11:58 AM] + + Did you see that? +``` + +The time that appears in the message label is always the time on the server computer, even if the client computer that sent the message is in a different time zone. + +### Ending a Remote Session + +The following examples demonstrate how to use the remote session commands to disconnect a client computer from a session and to end a remote session. Only the server computer that started the remote session can end it. + +To disconnect a client computer from a remote session, on the client computer, type **@q**. + +In response, the following message appears on the client computer that disconnected. + +``` +*** SESSION OVER *** +``` + +On all other computers in the session, the Remote tool posts a message with the name of the computer and user who disconnected, and the day and time of the disconnect. + +``` +**Remote: Disconnected from SERVER04 User01 [Wed 12:01 PM] +``` + +To end a remote session, on the server computer, type **@k**. This command automatically disconnects the clients, and then ends the session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Tool%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/remote-tool.md b/windows-driver-docs-pr/debugger/remote-tool.md new file mode 100644 index 0000000000..a62b709a35 --- /dev/null +++ b/windows-driver-docs-pr/debugger/remote-tool.md @@ -0,0 +1,64 @@ +--- +title: Remote Tool +description: The Remote tool, Remote.exe, is a command-line tool that lets you run and control any console program from a remote computer. +ms.assetid: b6fbde9b-1a2a-46b8-9edc-7fa143f5a711 +keywords: ["Remote Tool", "Remote.exe", "Remote.exe, See Remote Tool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote Tool + + +The Remote tool, Remote.exe, is a command-line tool that lets you run and control any console program from a remote computer. + +## Where to get the Remote tool + + +Remote.exe is included in [Debugging Tools for Windows](index.md). + +## Remote tool components + + +The Remote tool includes the following components: + +- A server application that starts a console program and opens a named pipe for client connections. + +- A client application that establishes a connection to a server. Commands typed on the client computer are sent to the console application on the server, and the remote client displays the output from the server's console window. + +- A query feature that lists the remote sessions running on a server computer. + +With the Remote tool, you can start multiple server sessions on a single computer where multiple clients can connect to each session. The sessions are limited only by the computer's resources. + +This is an older tool that has been eclipsed by more sophisticated tools, primarily Remote Desktop. However, because it is simple and uses very few resources, it is still widely used, typically for remote debugging. + +The Remote tool requires that commands be submitted on both the local and remote computers. As such, to use this tool on a computer without a local user, you must develop an alternate way to submit the commands and to restart the computer, if necessary. + +The Remote tool can compromise security on your computer, because it does not authenticate users or use Microsoft Windows permissions. By default, any remote computer that can connect and provide the session name can use the named pipe that this tool creates, although you can use Remote tool options to include and exclude particular users and groups. + +This section includes: + +[Remote Tool Concepts](remote-tool-concepts.md) + +[Remote Tool Commands](remote-tool-commands.md) + +[Remote Tool Examples](remote-tool-examples.md) + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Remote%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/repeater-examples.md b/windows-driver-docs-pr/debugger/repeater-examples.md new file mode 100644 index 0000000000..6f4fe886e6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/repeater-examples.md @@ -0,0 +1,69 @@ +--- +title: Repeater Examples +description: Repeater Examples +ms.assetid: 83aff647-65a7-409f-adce-254305395775 +keywords: ["repeater, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Repeater Examples + + +## + + +Let us suppose you have three computers, \\\\BOXA, \\\\BOXB, and \\\\BOXC, and you wish to use them as the server, the repeater, and the client, respectively. + +You can start a debugging server on \\\\BOXA, using process 122 as the target, in the following manner: + +``` +E:\Debugging Tools for Windows> cdb -server tcp:port=1025,password=wrought -p 122 +``` + +Then you can start a repeater on \\\\BOXB as follows: + +``` +C:\Misc> dbengprx -c tcp:server=BOXA,port=1025 -s npipe:pipe=MyPipe +``` + +Finally, start a debugging client on \\\\BOXC in the following manner: + +``` +G:\Debugging Tools> windbg -remote npipe:server=BOXB,pipe=MyPipe,password=wrought +``` + +Here is another example. Your symbols are at the remote location, 127.0.0.30. So you decide to use a process server on the computer where the target is, 127.0.0.10. You put a repeater at 127.0.0.20. + +You also decide to use reverse connections. So you begin by starting the client on 127.0.0.30: + +``` +G:\Debugging Tools> windbg -premote tcp:clicon=127.0.0.20,port=1033 notepad.exe +``` + +Then start the repeater on 127.0.0.20: + +``` +C:\Misc> dbengprx -c tcp:clicon=127.0.0.10,port=1025 -s tcp:port=1033,clicon=127.0.0.10 +``` + +And finally start the process server on 127.0.0.10: + +``` +E:\Debugging Tools for Windows> dbgsrv -t tcp:port=1025,clicon=127.0.0.20 +``` + +For a more complicated example using repeaters, see [Two Firewalls](two-firewalls.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Repeater%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/repeaters.md b/windows-driver-docs-pr/debugger/repeaters.md new file mode 100644 index 0000000000..dbde41758e --- /dev/null +++ b/windows-driver-docs-pr/debugger/repeaters.md @@ -0,0 +1,41 @@ +--- +title: Repeaters +description: Repeaters +ms.assetid: 10f4f033-f6c1-4b4f-a35f-eadb4e15686d +keywords: ["remote debugging through a repeater", "repeater", "repeater, overview", "DbEngPrx", "DbEngPrx, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Repeaters + + +## + + +A *repeater* is a lightweight proxy server that runs on a computer and relays data between two other computers. The repeater does not process the data in any way. The two other computers barely notice the repeater; from their perspective it seems as if they are directly connected to each other. + +The processes running on these two other computers are called the *server* and the *client*. There is not any fundamental difference between them from the repeater's point of view, except that in most cases the server is started first, then the repeater, and finally the client. + +The Debugging Tools for Windows package includes a repeater called DbEngPrx (dbengprx.exe). + +This section includes: + +[**Activating a Repeater**](activating-a-repeater.md) + +[Using a Repeater](using-a-repeater.md) + +[Repeater Examples](repeater-examples.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Repeaters%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/requesting-special-pool-by-allocation-size.md b/windows-driver-docs-pr/debugger/requesting-special-pool-by-allocation-size.md new file mode 100644 index 0000000000..c1fc437f9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/requesting-special-pool-by-allocation-size.md @@ -0,0 +1,43 @@ +--- +title: Requesting Special Pool by Allocation Size +description: Requesting Special Pool by Allocation Size +ms.assetid: 040d1a1a-1849-4253-8d4b-6c57a8643225 +--- + +# Requesting Special Pool by Allocation Size + + +## + + +You can request special pool for allocations within a specified size range. + +In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see [**GFlags Commands**](gflags-commands.md). + +**Note**   This method is rarely useful for diagnosing driver errors, because it affects all kernel pool requests of the specified size, regardless of which driver or kernel module requested the allocation. + +  + +### To request special pool by allocation size + +1. Select the **System Registry** tab or the **Kernel Flags** tab. + + On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the **System Registry** tab. + +2. In the **Kernel Special Pool Tag** section, click **Hex**, and then type a number in hexadecimal format that represents a range of sizes. All allocations within this size range will be allocated from special pool. This number must be less than PAGE\_SIZE. + +3. Click **Apply**. + + The following screen shot shows an allocation size entered as a hexadecimal value. + + ![screen shot that shows an allocation size entered as a hexadecimal value](images/gflags-specialpool-size.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Requesting%20Special%20Pool%20by%20Allocation%20Size%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/requesting-special-pool-by-pool-tag.md b/windows-driver-docs-pr/debugger/requesting-special-pool-by-pool-tag.md new file mode 100644 index 0000000000..455bdfdf98 --- /dev/null +++ b/windows-driver-docs-pr/debugger/requesting-special-pool-by-pool-tag.md @@ -0,0 +1,53 @@ +--- +title: Requesting Special Pool by Pool Tag +description: Requesting Special Pool by Pool Tag +ms.assetid: 201eb8a5-b38b-4625-853d-448488214e52 +--- + +# Requesting Special Pool by Pool Tag + + +## + + +You can request special pool for all allocations that use a specified pool tag. Only one pool tag on the system can be associated with kernel special pool requests at one time. + +In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see [**GFlags Commands**](gflags-commands.md). + +**To request special pool by pool tag** + +1. Select the **System Registry** tab or the **Kernel Flags** tab. + + On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the **System Registry** tab. + +2. In the **Kernel Special Pool Tag** section, click **Text**, and then type a four-character pattern for the tag. + + The tag can include the **?** (single character) and **\*** (multiple characters) wildcard characters. For example, Fat\* or Av?4. + +3. The following screen shot shows a tag entered as text on the System Registry tab. + + ![screen shot of a tag entered as text on the system registry tab](images/gflags-specialpool-text.png) + +4. Click **Apply**. + + When you click **Apply**, GFlags changes the selection from **Text** to **Hex** and displays the ASCII characters as hexadecimal values in reverse (lower endian) order. For example, if you type **Tag1**, GFlags displays the tag as **0x31676154** (1gaT). This is the way that it is stored in the registry and displayed by the debugger and other tools. + + The following illustration shows the effect of clicking **Apply**. + + ![screen shot that shows the effect of clicking apply](images/gflags-specialpool-hex.png) + +### Remarks + +To use this feature effectively, make sure that your driver or other kernel-mode program uses a unique pool tag. If you suspect that your driver is consuming all of the special pool, consider using multiple pool tags in your code. You can then test your driver several times, assigning special pool to one pool tag in each test. + +Also, select a pool tag with a hexadecimal value that is greater than the page size of the system. For kernel mode code, if you enter a pool tag that has a value less than PAGE\_SIZE, Gflags requests special pool for all allocations whose size is within the corresponding range and requests special pool for allocations with an equivalent pool tag. For example, if you select a size of **30**, special pool will be used for all allocations between 17 and 32 bytes in size, and for allocations with the pool tag 0x0030. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Requesting%20Special%20Pool%20by%20Pool%20Tag%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/resizing-and-moving-a-window.md b/windows-driver-docs-pr/debugger/resizing-and-moving-a-window.md new file mode 100644 index 0000000000..b84271aa03 --- /dev/null +++ b/windows-driver-docs-pr/debugger/resizing-and-moving-a-window.md @@ -0,0 +1,37 @@ +--- +title: Resizing and Moving a Window +description: Resizing and Moving a Window +ms.assetid: 135e1ec1-9d58-45de-a0b4-5f962ed9e1f7 +keywords: ["debugging information windows, resizing and moving a window", "resizing and moving windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Resizing and Moving a Window + + +## + + +Floating windows are always associated with the WinDbg window. If you minimize WinDbg, all floating windows are minimized. And if you restore WinDbg, all floating windows are restored. You can never put a floating window behind the WinDbg window. + +Each floating window moves independently from each other and from the WinDbg window, unless you have selected **Move with frame** on the window's shortcut menu. + +A docked window occupies a fixed position within the WinDbg frame. If you resize WinDbg, all of the docked windows are automatically scaled to the new size. The same situation applies to windows that have been docked in a separate dock. + +If you move the mouse pointer to the border between two docked windows, the mouse pointer becomes an arrow. By dragging this arrow, you can resize the two adjacent windows and leave them in the docked state. + +The WinDbg window is always filled with docked windows. There is never any empty area in the window unless there are no windows docked. The same situation applies to independent docks. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Resizing%20and%20Moving%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/resource-time-outs.md b/windows-driver-docs-pr/debugger/resource-time-outs.md new file mode 100644 index 0000000000..a0c9f2bee5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/resource-time-outs.md @@ -0,0 +1,110 @@ +--- +title: Resource Time Outs +description: Resource Time Outs +ms.assetid: ea5b61e0-cb51-4da2-9596-ab85f7b01bed +keywords: ["resource time outs"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Resource Time Outs + + +## + + +During a resource time out, the thread waiting for the resource will break into the kernel debugger with a message similar to the following: + +``` +Resource @ 800e99c0 + ActiveCount = 0001 Flags = IsOwnedExclusive sharedWaiter + NumberOfExclusiveWaiters = 0000 + Thread = 809cd2f0, Count = 01 + Thread = 809ebc50, Count = 01 + Thread = 00000000, Count = 00 + Thread = 00000000, Count = 00 + Thread = 00000000, Count = 00 +NT!DbgBreakPoint+0x4: +800cee04: 000000ad callkd +``` + +The thread that holds the lock is the first thread listed (or multiple threads if it is a shared lock). To examine that thread, use a **!thread** extension on the thread ID (809cd2f0, in the previous example). This will give a stack for the thread owning the resource. If it is also waiting for a resource to become available, either the **ExpWaitForResourceExclusive** function or the **ExpWaitForResourceShared** function will be on the stack for that thread. + +The first parameter to **ExpWaitForResource*Xxx*** is the lock that is being waited on. To find out about that resource, use a **!locks <*resource id*>** extension, which will give you another thread to check. + +If you get to a thread that is not waiting for another resource, that thread is probably the source of the problem. For a list of all held locks, use a **!locks** extension with no parameter at the **kd>** prompt. + +### Example + +``` +Resource @ fc664ee0 // Here's the resource lock address + + ActiveCount = 0001 Flags = IsOwnedExclusive ExclusiveWaiter + NumberOfExclusiveWaiters = 0001 + Thread = ffaf5410, Count = 01 // Here's the owning thread + Thread = 00000000, Count = 00 +ntoskrnl!_DbgBreakPoint: +80131400 cc int 3 + +kd> kb // Start with a stack +ChildEBP RetAddr Args to Child +fcd44980 801154c0 fc664ee0 ffab45d0 00110001 ntoskrnl!_DbgBreakPoint +fcd4499c 80102521 fc664ee0 ffb08ea8 fcd44a4c ntoskrnl!_ExpWaitForResource+0x114 // Lock being waited on... + +fcd449e8 fc6509fa e12597c8 fef27c08 fee4fca8 ntoskrnl!_ExAcquireResourceExclusiveLite+0xa5 +00380020 00000000 00000000 00000000 00000000 nwrdr!_CreateScb+0x2ff + +kd> !locks fc664ee0 // !locks resource address gives lock info +Resource @ nwrdr!_NwScavengerSpinLock (0xfc664ee0) Exclusively owned + Contention Count = 45 + NumberOfExclusiveWaiters = 1 + Threads: ffaf5410-01 // Owning thread again +1 total locks, 1 locks currently held + +kd> !thread ffaf5410 // Check the owning thread + +THREAD ffaf5410 Cid e7.e8 Teb: 7ffde000 WAIT: (Executive) KernelMode Non-Alertable + feecf698 SynchronizationEvent +IRP List: + fef29208: (0006,00b8) Flags: 00000884 Mdl: feed8328 +Not impersonating +Owning Process ffaf5690 +WaitTime (seconds) 2781250 +Context Switch Count 183175 +UserTime 0:00:23.0153 +KernelTime 0:01:01.0187 +Start Address 0x77f04644 +Initial Sp fec6c000 Current Sp fec6b938 +Priority 11 BasePriority 7 PriorityDecrement 0 DecrementCount 8 + +ChildEBP RetAddr Args to Child +fec6b950 801044fc feecf668 feecf668 00000080 ntoskrnl!KiSwapContext+0x25 +fec6b974 fc655976 feecf698 00000000 00000000 ntoskrnl!_KeWaitForSingleObject+0x218 +fec6ba5c fc6509fa e1263968 fef29208 feecf668 nwrdr!_ExchangeWithWait+0x38 +fec6ba28 fc6533e5 feecf668 e125b3c8 ffafae08 nwrdr!_CreateScb+0x2ff +fec6bac0 fc652f26 feecf668 fec6bae4 fef29208 nwrdr!_CreateRemoteFile+0x2c9 +fec6bb6c fc652b14 feecf668 fef29208 fee50b60 nwrdr!_NwCommonCreate+0x3a2 + +fec6bbac 80107aea fee50b60 fef29208 804052ac nwrdr!_NwFsdCreate+0x56 +fec6bbc0 80142792 fef37700 fec6bdbc fee50b28 ntoskrnl!IofCallDriver+0x38 +fec6bd10 80145403 fee50b60 00000000 fec6bdbc ntoskrnl!_IopParseDevice+0x6a0 +fec6bd7c 80144c0c 00000000 fec6be34 00000040 ntoskrnl!_ObpLookupObjectName+0x479 +fec6be5c 80127803 0012dd64 00000000 80127701 ntoskrnl!_ObOpenObjectByName+0xa2 +fec6bef4 801385c3 0012dd64 0012dd3c 00000000 ntoskrnl!_NtQueryAttributesFile+0xc1 +fec6bef4 77f716ab 0012dd64 0012dd3c 00000000 ntoskrnl!_KiSystemService+0x83 + +0012dd20 00000000 00000000 00000000 00000000 ntdll!_ZwQueryAttributesFile+0xb +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Resource%20Time%20Outs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/risks-entailed-when-setting-breakpoints.md b/windows-driver-docs-pr/debugger/risks-entailed-when-setting-breakpoints.md new file mode 100644 index 0000000000..b333b2f9f5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/risks-entailed-when-setting-breakpoints.md @@ -0,0 +1,52 @@ +--- +title: Risks Entailed When Setting Breakpoints +description: Risks Entailed When Setting Breakpoints +ms.assetid: 92c1007b-f871-48e9-a215-4d36ed1371ea +keywords: ["breakpoints, risks"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Risks Entailed When Setting Breakpoints + + +When you are setting a [breakpoints](using-breakpoints.md) by specifying a memory address or a symbol plus an offset, you must not put this breakpoint in the middle of an instruction. + +For example, consider the following disassembled code. + +``` +770000f1 5e pop esi +770000f2 5b pop ebx +770000f3 c9 leave +770000f4 c21000 ret 0x10 +770000f7 837ddc00 cmp dword ptr [ebp-0x24],0x0 +``` + +The first three instructions are only one byte long. However, the fourth instruction is three bytes long. (It includes bytes 0x770000F4, 0x770000F5, and 0x770000F6.) If you want to put a breakpoint on this instruction by using the **bp**, **bu**, or **ba** command, you must specify the 0x770000F4 address. + +If you put a breakpoint in the 0x770000F5 address by using the **ba** command, the processor puts a breakpoint at that location. But this breakpoint would never be triggered, because the processor considers 0x770000F4 to be the actual address of the instruction. + +If you put a breakpoint in the 0x770000F5 address by using the **bp** or **bu** commands, the debugger writes a breakpoint at that location. However, this breakpoint might corrupt the target because of how the debugger creates breakpoints: + +1. The debugger saves the contents of 0x770000F5 and overwrites this memory with a breakpoint instruction. + +2. If you try to display this memory in the debugger, the debugger does not show the breakpoint instruction that it has written. Instead, the debugger shows the memory that "should" be there. That is, the debugger shows the original memory, or any modifications to that memory that you have made since inserting the breakpoint. + +3. If you use the **BC** command to remove the breakpoint, the debugger restores the original memory to its proper location. + +When you put a breakpoint at 0x770000F5, the debugger saves this byte and a break instruction is written here. However, when the application runs, it reaches the 0x770000F4 address and recognizes this address as the first byte of a multibyte instruction. The processor then tries to combine 0x770000F4, 0x770000F5, and possibly some later bytes into a single instruction. This combination can create a variety of behaviors, none of which are desirable. + +Therefore, when you put breakpoints by using a **bp**, **bu**, or **ba** command, make sure that you always put the breakpoints at the proper address. If you are using the WinDbg graphical interface to add breakpoints, you do not have to be concerned about this situation because the correct address is chosen automatically. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Risks%20Entailed%20When%20Setting%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/rm--register-mask-.md b/windows-driver-docs-pr/debugger/rm--register-mask-.md new file mode 100644 index 0000000000..9c95f26f57 --- /dev/null +++ b/windows-driver-docs-pr/debugger/rm--register-mask-.md @@ -0,0 +1,213 @@ +--- +title: rm (Register Mask) +description: The rm command modifies or displays the register display mask. This mask controls how registers are displayed by the r (Registers) command. +ms.assetid: b3203bf3-b614-490b-8cbd-6abb291a801a +keywords: ["rm (Register Mask) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- rm (Register Mask) +api_type: +- NA +--- + +# rm (Register Mask) + + +The **rm** command modifies or displays the register display mask. This mask controls how registers are displayed by the [**r (Registers)**](r--registers-.md) command. + +``` +rm +rm ? +rm Mask +``` + +## Parameters + + + **?** +Displays a list of possible *Mask* bits. + + *Mask* +Specifies the mask to use when the debugger displays the registers. *Mask* is a sum of bits that indicate something about the register display. The meaning of the bits depends on the processor and the mode. For more information; see the tables in the following Remarks section. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The "m" in the command name must be a lowercase letter. + +If you use **rm** with no parameters, the current value is displayed, along with an explanation about its bits. + +To display the basic integer registers, you must set bit 0 (0x1) or bit 1 (0x2). By default, 0x1 is set for 32-bit targets and 0x2 is set for 64-bit targets. You cannot set these two bits at the same time--if you try to set both bits, 0x2 overrides 0x1. + +You can override the default mask by using the [**r (Registers)**](r--registers-.md) command together with the **M** option. + +The following *Mask* bits are supported for an x86-based processor or an x64-based processor. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitValueDescription

+0 +1

+0x1 +0x2

Displays the basic integer registers. (Setting one or both of these bits has the same effect.)

2

0x4

Displays the floating-point registers.

3

0x8

Displays the segment registers.

4

0x10

Displays the MMX registers.

5

0x20

Displays the debug registers. In kernel mode, setting this bit also displays the CR4 register.

6

0x40

Displays the SSE XMM registers.

7

0x80

(Kernel mode only) Displays the control registers, for example CR0, CR2, CR3 and CR8.

8

0x100

(Kernel mode only) Displays the descriptor and task state registers.

9

0x200

Displays the AVX YMM registers in floating point.

10

0x400

Displays the AVX YMM registers in decimal integers.

11

0x800

Displays the AVX XMM registers in decimal integers.

+ +  + +The following *Mask* bits are supported for an Itanium-based processor. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitValueDescription

+0 +1

+0x1 +0x2

Displays the basic integer registers. (Setting one or both of these bits has the same effect.)

2

0x4

Displays the floating-point registers.

3

0x8

Displays the high, floating-point registers (f32 to f127).

4

0x10

Displays the user debug registers.

5

0x20

(Kernel mode only) Displays the KSPECIAL_REGISTERS.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20rm%20%28Register%20Mask%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/rpc-debugging.md b/windows-driver-docs-pr/debugger/rpc-debugging.md new file mode 100644 index 0000000000..45e961e0aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/rpc-debugging.md @@ -0,0 +1,39 @@ +--- +title: RPC Debugging +description: RPC Debugging +ms.assetid: 5b3918d7-0a1c-4efd-8b83-bc20741b5afe +keywords: ["RPC debugging", "RPC state information", "DbgRpc, RPC debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# RPC Debugging + + +## + + +This section includes: + +[Overview of RPC Debugging](overview-of-rpc-debugging.md) + +[Enabling RPC State Information](enabling-rpc-state-information.md) + +[Displaying RPC State Information](displaying-rpc-state-information.md) + +[Common RPC Debugging Techniques](common-rpc-debugging-techniques.md) + +[RPC State Information Internals](rpc-state-information-internals.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20RPC%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/rpc-extensions--rpcexts-dll-.md b/windows-driver-docs-pr/debugger/rpc-extensions--rpcexts-dll-.md new file mode 100644 index 0000000000..542e744cbe --- /dev/null +++ b/windows-driver-docs-pr/debugger/rpc-extensions--rpcexts-dll-.md @@ -0,0 +1,33 @@ +--- +title: RPC Extensions (Rpcexts.dll) +description: RPC Extensions (Rpcexts.dll) +ms.assetid: 2c5c1d99-4eb0-459e-949b-e02db7f1a300 +keywords: ["RPC extensions (rpcexts.dll), complete listing", "extensions, RPC"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# RPC Extensions (Rpcexts.dll) + + +## + + +Extension commands that are useful for debugging Microsoft Remote Procedure Call (RPC) can be found in Rpcexts.dll. + +The Windows 2000 version of this extension DLL appears in the w2kfre and w2kchk directories. The Windows XP and later version of this extension DLL appear in the winxp directory. + +For more information about how to use these extensions, see [Using the RPC Debugger Extensions](using-the-rpc-debugger-extensions.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20RPC%20Extensions%20%28Rpcexts.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/rpc-state-information-internals.md b/windows-driver-docs-pr/debugger/rpc-state-information-internals.md new file mode 100644 index 0000000000..d2f72a3343 --- /dev/null +++ b/windows-driver-docs-pr/debugger/rpc-state-information-internals.md @@ -0,0 +1,145 @@ +--- +title: RPC State Information Internals +description: RPC State Information Internals +ms.assetid: fac4a1e4-e1ec-41f2-8de9-073a04a979be +keywords: ["RPC debugging, RPC state information internals"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# RPC State Information Internals + + +## + + +This section provides details of the internal structure of the state information gathered by the RPC Run-Time. + +All RPC run-time state information is contained in cells. A cell is the smallest unit of information that can be viewed and updated individually. + +Each key object in the RPC Run-Time will maintain one or more cells of information about its state. Each cell has a cell ID. When an objects refers to another object, it does so by specifying that object's cell ID. The key objects that the RPC Run-Time can maintain information about are endpoints, threads, connection objects, Server Call (SCALL) objects, and Client Call (CCALL) objects. + +**When an RPC server is running**, the RPC Run-Time listens on a set of endpoints using one or more worker threads. Whenever data is transmitted to the server, a thread picks up the data and determines what the incoming request is. If the request is to create a connection, a Connection object is created, and this object then services all calls on the connection. When an RPC call is made on the connection, the Connection object instantiates a Server Call (SCALL) object corresponding to the Client Call (CCALL) object. This Server Call object then handles this particular call. + +**When an RPC client is running**, the RPC Run-Time creates a Client Call object each time a call is made. This Client Call object contains information about this particular call. + +### Endpoint Cells + +From the RPC run-time's point of view, an endpoint is an entry point through which the particular server can be contacted. The endpoint is always associated with a given RPC transport. The endpoint state information is used to associate a client call with a particular process on the server. + +The fields in an endpoint cell are: + +**ProtseqType** +The protocol sequence for this endpoint. + +**Status** +The status value: *allocated*, *active*, or *inactive*. Most endpoints are active. An endpoint has *allocated* status when the creation process has started, but is not complete yet. An endpoint is *inactive* if it is no longer in use (for example, when a protocol has been uninstalled). + +**EndpointName** +The first 28 characters of the endpoint name. + +### Thread Cells + +Server threads are worker threads (standard Win32 threads for use by RPC). + +The fields in a thread cell are: + +**Status** +The status value: *processing*, *dispatched*, *allocated*, or *idle*. A *processing* thread is one that is within the Run-Time and is processing information. A *dispatched* thread has already dispatched (called) to the server-provided manager routine (usually just called the *server routine*). An *allocated* thread has been cached. An *idle* thread is available to service requests. + +**LastUpdateTime** +The time (in milliseconds after boot) when the information was last updated. + +**TID** +The thread ID of this thread. This is useful when trying to correlate with the thread list in the debugger. + +### Connection Object Cells + +The fields in a connection object cell are: + +**Flags** +Flag values include *exclusive*/*non-exclusive*, *authentication level*, and *authentication service*. + +**LastTransmitFragmentSize** +The size of the last fragment transmitted over the connection. + +**Endpoint** +The cell ID of the endpoint that this connection was picked up from. + +**LastSendTime** +The last time data was sent on a connection. + +**LastReceiveTime** +The last time data was received on a connection. + +### Server Call Object Cells + +The fields in a Server Call (SCALL) object cell are: + +**Status** +The status value: *allocated*, *active*, or *dispatched*. An *allocated* call is inactive and cached. When a call is *active*, the RPC Run-Time is processing information related to this call. When a call is *dispatched*, the manager routine (server routine) has been called and has not returned yet. + +**ProcNum** +The procedure number (operation number, in netmon capture files) of this call. The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file. The first routine in the interface will be number zero, the second number one, and so on. + +**InterfaceUUIDStart** +The first DWORD of the interface UUID. + +**ServicingTID** +The cell ID of the thread that is servicing this call. If the call is not *active* or *dispatched*, this contains stale information. + +**CallFlags** +These flag values indicate whether this is the cached call in an exclusive connection, whether this is an asynchronous call, whether this is a pipe call, and whether this is an LRPC or OSF call. + +**LastUpdateTime** +The time (in milliseconds after boot) when the call object state information was last updated. + +**PID** +The Process ID of the caller. Valid only for LRPC calls. + +**TID** +The Thread ID of the caller. Valid only for LRPC calls. + +### Client Call Object Cells + +A Client Call (CCALL) object is broken into two cells, because the information about a client call is too large to fit in one cell. The first cell is called *Client Call Information*, and the second is called *Call Target Information*. Most tools will show the information together, so you do not need to distinguish between them. + +Information about client calls is not maintained unless you are gathering Full state information. There is one exception to this rule: information about client calls made within a server call is maintained even when only Server state information is being gathered. This allows you to trace calls spanning multiple hops. + +The fields in the Client Call Information cell are: + +**ProcNum** +The procedure number (operation number, in netmon capture files) of the method being called. The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file. The first routine in the interface will be number zero, the second number one, and so on. + +**ServicingThread** +The cell ID of the thread on which this call is made. + +**IfStart** +The first DWORD of the interface UUID on which the call is made. + +**Endpoint** +The first 12 characters of the endpoint on the server to which the call was made. + +The fields in the Call Target Information cell are: + +**ProtocolSequence** +The protocol sequence for this call. + +**LastUpdateTime** +The time (in milliseconds after boot) when the information about the client call or the call target was updated. + +**TargetServer** +The first 24 characters of the name of the server to which the call is made. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20RPC%20State%20Information%20Internals%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/running-a-program-in-a-debugger.md b/windows-driver-docs-pr/debugger/running-a-program-in-a-debugger.md new file mode 100644 index 0000000000..229bb9f36e --- /dev/null +++ b/windows-driver-docs-pr/debugger/running-a-program-in-a-debugger.md @@ -0,0 +1,47 @@ +--- +title: Running a Program in a Debugger +description: Running a Program in a Debugger +ms.assetid: e34b9560-33a2-47ed-83eb-84712b65a7f0 +keywords: ["GFlags, running a program in a debugger"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Running a Program in a Debugger + + +## + + +This feature configures the program so that it always runs in a debugger with the specified options. This setting is saved in the registry. It affects all new instances of the program and remains effective until you change it. + +**To run a program in a debugger** + +1. Click the **Image File** tab. + +2. In the **Image** box, type the name of an executable file or DLL, including the file name extension,and then press the TAB key. + + This activates the check boxes on the **Image File** tab. + +3. Click the **Debugger** check box to select it. + + The following screen shot shows the **Debugger** check box on the **Image File** tab in Windows Vista. + + ![screen shot of the debugger check box on the image file tab in windows vista ](images/gflags-debugger.png) + +4. In the **Debugger** box, type the command to run the debugger, including the path (optional) and name of the debugger and parameters. For example, **ntsd -d -g -G -x** or **c:\\debuggers\\cdb.exe -g -G**. + +5. Click **Apply**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Running%20a%20Program%20in%20a%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/s--search-memory-.md b/windows-driver-docs-pr/debugger/s--search-memory-.md new file mode 100644 index 0000000000..7dc20c965e --- /dev/null +++ b/windows-driver-docs-pr/debugger/s--search-memory-.md @@ -0,0 +1,236 @@ +--- +title: s (Search Memory) +description: The s command searches through memory to find a specific byte pattern. +ms.assetid: fdca07c3-95c8-46cf-8da1-07a5e6767f67 +keywords: ["s (Search Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- s (Search Memory) +api_type: +- NA +--- + +# s (Search Memory) + + +The **s** command searches through memory to find a specific byte pattern. + +Do not confuse this command with the [**~s (Change Current Processor)**](-s--change-current-processor-.md), [**~s (Set Current Thread)**](-s--set-current-thread-.md), [**|s (Set Current Process)**](-s--set-current-process-.md), or [**||s (Set Current System)**](--s--set-current-system-.md) commands. + +``` +s [-[[Flags]Type]] Range Pattern +s -[[Flags]]v Range Object +s -[[Flags]]sa Range +s -[[Flags]]su Range +``` + +## Parameters + + + **\[** *Flags*\] +Specifies one or more search options. Each flag is a single letter. You must enclose the flags in a single set of brackets (\[\]). You cannot add spaces between the brackets, except between **n** or **l** and its argument. For example, if you want to specify the **s** and **w** options, use the command s -\[sw\]Type Range Pattern. + +You can specify one or more of the following flags: + +**s** +Saves all of the results of the current search. You can use these results to repeat the search later. + +**r** +Restricts the current search to the results from the last saved search. You cannot use the **s** and **r** flags in the same command. When you use **r**, the value of *Range* is ignored, and the debugger searches only those hits that were saved by the previous **s** command. + +**n** *Hits* +Specifies the number of hits to save when you use the **s** flag. The default value is 1024 hits. If you use **n** together with other flags, **n** must be the last flag, followed by its *Hits* argument. The space between **n** and *Hits* is optional, but you cannot add any other spaces within the brackets. If any later search that uses the **s** flag discovers more than the specified number of hits, the **Overflow error** message is displayed to notify you that not all hits are being saved. + +**l** *Length* +Causes a search for arbitrary ASCII or Unicode strings to return only strings that are at least *Length* characters long. The default length is 3. This value affects only searches that use the **-sa** or **-su** flags. + +**w** +Searches only writeable memory regions. You must enclose the "w" in brackets. + +**1** +Displays only the addresses of search matches in the search output. This option is useful if you are using the [**.foreach**](-foreach.md) token to pipe the command output into another command's input. + + *Type* +Specifies the memory type to search for. Add a hyphen (-) in front of *Type* . You can use one of the following *Type* values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription

b

Byte (8 bits)

w

WORD (16 bits)

d

DWORD (32 bits)

q

QWORD (64 bits)

a

+ASCII string +(not necessarily a null-terminated string)

u

+Unicode string +(not necessarily a null-terminated string)
+ +  + +If you omit *Type*, byte values are used. However, if you use *Flags*, you cannot omit *Type*. + + **sa** +Searches for any memory that contains printable ASCII strings. Use the **l** *Length* flag to specify a minimum length of such strings. The default minimum length is 3 characters. + + **su** +Searches for any memory that contains printable Unicode strings. Use the **l** *Length* flag to specify a minimum length of such strings. The default minimum length is 3 characters. + + *Range* +Specifies the memory area to search through. This range cannot be more than 256 MB long unless you use the **L?** syntax. For more information about this syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Pattern* +Specifies one or more values to search for. By default, these values are byte values. You can specify different types of memory in *Type*. If you specify a WORD, DWORD, or QWORD value, enclose it in single quotation marks (for example, **'Tag7'**). If you specify a string, enclose it in double quotation marks (for example, **"This string"**). + + **-v** +Searches for objects of the same type as the specified *Object*. + + *Object* +Specifies the address of an object or the address of a pointer to an object. The debugger then searches for objects of the same type as the object that *Object* specifies. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about memory manipulation and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). + +Remarks +------- + +If the debugger finds the byte pattern that you specify, the debugger displays the first memory address in the *Range* memory area where the pattern was found. The debugger displays an excerpt of memory that begins at that location in a format that matches the specified *Type* memory type. If *Type* is **a** or **u**, the memory contents and the corresponding ASCII or Unicode characters are displayed. + +You must specify the *Pattern* parameter as a series of bytes, unless you specify a different *Type* value. You can enter byte values as numeric or ASCII characters: + +- Numeric values are interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command. You can override the default radix by specifying the **0x** prefix (hexadecimal), the **0n** prefix (decimal), the **0t** prefix (octal), or the **0y** prefix (binary). + **Note**   The default radix behaves differently when you use C++ expressions. For more information about these expressions and the radix, see [Evaluating Expressions](evaluating-expressions.md). + +   + +- You must enclose ASCII characters in single straight quotation marks. You cannot use C-style escape characters (such as '\\0' or '\\n'). + +If you specify multiple bytes, you must separate them by spaces. + +The **s-a** and **s-u** commands search for specified ASCII and Unicode strings, respectively. These strings do not have to be null-terminated. + +The **s-sa** and **s-su** commands search for unspecified ASCII and Unicode strings. These are useful if you are checking a range of memory to see whether it contains any printable characters. The flags options allow you to specify a minimum length of string to find. + +Example: The following command finds ASCII strings that are of length >=3 in the range beginning at 0000000140000000 and ending 400 bytes later. + +``` +s-sa 0000000140000000 L400 +``` + +The following command finds ASCII strings that are of length >=4 in the range beginning at 0000000140000000 and ending 400 bytes later + +``` +s -[l4]sa 0000000140000000 L400 +``` + +The following command does the same thing, but it limits the search to writeable memory regions. + +``` +s -[wl4]sa 0000000140000000 L400 +``` + +The following command does the same thing, but displays only the address of the match, rather than the address and the value. + +``` +s -[1wl4]sa 0000000140000000 L400 +``` + +The **s-v** command searches for objects of the same data type as the *Object* object. You can use this command only if the desired object is a C++ class or another object that is associated with virtual function tables (Vtables). The **s-v** command searches the *Range* memory area for the addresses of this class's Vtables. If multiple Vtables exist in this class, the search algorithm looks for all of these pointer values, separated by the proper number of bytes. If any matches are found, the debugger returns the base address of the object and full information about this object--similar to the output of the [**dt (Display Type)**](dt--display-type-.md) command. + +Example: Assume the current radix is 16. The following three command all do the same thing: search memory locations 0012FF40 through 0012FF5F for "Hello". + +``` +0:000> s 0012ff40 L20 'H' 'e' 'l' 'l' 'o' +``` + +``` +0:000> s 0012ff40 L20 48 65 6c 6c 6f +``` + +``` +0:000> s -a 0012ff40 L20 "Hello" +``` + +These commands locate each appearance of "Hello" and return the address of each such pattern--that is, the address of the letter "H". + +The debugger returns only patterns that are completely contained in the search range. Overlapping patterns are found correctly. (In other words, the pattern "QQQ" is found three times in "QQQQQ".) + +The following example shows a search that uses the *Type* parameter. This command searches memory locations 0012FF40 through 0012FF5F for the double-word 'VUTS': + +``` +0:000> s -d 0012ff40 L20 'VUTS' +``` + +On little-endian computers, 'VUTS' is the same as the byte pattern 'S' 'T' 'U' 'V'. However, searches for WORDs, DWORDs, and QWORDs return only results that are correctly byte-aligned. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20s%20%28Search%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/s.md b/windows-driver-docs-pr/debugger/s.md new file mode 100644 index 0000000000..a47994d181 --- /dev/null +++ b/windows-driver-docs-pr/debugger/s.md @@ -0,0 +1,92 @@ +--- +title: S (Windows Debugger Glossary) +description: Glossary page - S +Robots: noindex, nofollow +ms.assetid: 94cbf33b-e975-49eb-a266-774798955a48 +keywords: ["suspended thread", "suspended process"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# S + + +**scope** +The context that defines the local variables. The scope has three components: a stack frame, a current instruction, and a register context. + +Sometimes referred to as *local context* or *lexical scope*. + +**second-chance exception** +The second opportunity to handle an exception. This opportunity is only provided if the exception was not handled on the first chance. + +**smart client** +An instance of the debugger engine acting as a host. The smart client is connected to a process server. or a KD connection server. + +**specific exception filter** +An event filter for an exception for which the engine has a built-in filter. Most specific exception filters refer to specific types of exceptions (identified by exception code), but the default exception filter also qualifies as a specific exception filter. + +**specific event filter** +An event filter for an event which is not an exception. The specific event filters are listed in [**DEBUG\_FILTER\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541490). + +**specific filter** +An event filter for an event for which the engine has a built-in filter. + +**software breakpoint** +A breakpoint that is implemented by the debugger engine temporarily modifying the target's executable code. The breakpoint is triggered when the code is executed. The code modification is invisible to users of the debugger or the debugger engine API. + +**stack** +See call stack. + +**stack frame** +The memory in the call stack containing the data for a single function call. This includes the return address, parameters passed to the function, and local variables. + +**stop code** +See bug check code. + +**stop error** +See bug check. + +**stop screen** +See blue screen. + +**subregister** +A register that is contained within another register. When the subregister changes, the portion of the register that contains the subregister also changes. + +**suspended** +A target, process, or thread is suspended if it has been blocked it from executing. + +**symbol** +A unit of debugging information which provides interpretive information about the target in a debugging session. Examples of symbols include variables (local and global), functions, types and function entries. Information about symbols can include the name, type (if applicable), and the address or regisgter where it is stored, as well as any parent or child symbols. This information is stored in symbol files and is typically not available in the module itself. + +The debugger engine can synthesize certain symbols when symbol files are not available (for example, exported symbols), but these symbols generally provide only minimal information. + +**symbol file** +A supplemental file created when an application, library, driver, or operating system is built. A symbol file contains data which is not actually needed when running the binaries, but which is very useful in the debugging process. + +**symbol group** +A group of symbols, typically representing all the local variables in a scope. + +**symbol type** +Descriptive information about a symbol's representation, such as its layout in memory. This is part of the information a compiler uses to generate code to manipulate the symbol. It is also used by the debugger engine to manipulate symbols. The symbol type is distributed in symbol files. + +**synthetic module** +A region of memory that the engine treats like a module. A synthetic module may contain synthetic symbols. + +**synthetic symbol** +A memory address that the engine treats like a symbol. + +**system crash** +See bug check. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20S%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/scopes-and-symbol-groups.md b/windows-driver-docs-pr/debugger/scopes-and-symbol-groups.md new file mode 100644 index 0000000000..e96eda48df --- /dev/null +++ b/windows-driver-docs-pr/debugger/scopes-and-symbol-groups.md @@ -0,0 +1,87 @@ +--- +title: Scopes and Symbol Groups +description: Scopes and Symbol Groups +ms.assetid: f14b6361-9962-4fa3-bb1a-dfde066754b9 +keywords: ["Debugger Engine API, symbols, symbol groups", "symbol group, scopes", "Debugger Engine API, symbols, scopes", "scopes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Scopes and Symbol Groups + + +## + + +A *symbol group* contains a set of symbols for efficient manipulation as a group. A symbol group can be created and populated manually or can be automatically generated and updated based on symbols in lexical scopes, such as local variables and function arguments. The interface [IDebugSymbolGroup](https://msdn.microsoft.com/library/windows/hardware/ff550838) is used to represent a symbol group. + +There are two ways to create a symbol group. An empty symbol group is returned by [**CreateSymbolGroup**](https://msdn.microsoft.com/library/windows/hardware/ff540093), and the symbol group for the current lexical scope is returned by [**GetScopeSymbolGroup**](https://msdn.microsoft.com/library/windows/hardware/ff548280). + +**Note**   The symbol group generated from the current scope is a snapshot of the local variables. If any execution occurs in the target, the symbols may no longer be accurate. Also, if the current scope changes, the symbol group will no longer represent the *current* scope (because it will continue to represent the scope for which it was created). + +  + +Symbols can be added to a symbol group using [**AddSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff537925), and removed using [**RemoveSymbolByIndex**](https://msdn.microsoft.com/library/windows/hardware/ff554510) or [**RemoveSymbolByName**](https://msdn.microsoft.com/library/windows/hardware/ff554518). The method [**OutputAsType**](https://msdn.microsoft.com/library/windows/hardware/ff553191) tells the debugger to use a different symbol type when handling a symbol's data. + +**Note**   The values for scoped symbols may not be accurate. In particular, the machine architecture and compiler optimizations may prevent the debugger from accurately determining a symbol's value. + +  + +The *symbol entry information* is a description of a symbol, including its location and its type. To find this information for a symbol in a module, use the [**IDebugSymbols3::GetSymbolEntryInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548484). To find this information for a symbol in a symbol group, use [**IDebugSymbolGroup2::GetSymbolEntryInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548487). See [**DEBUG\_SYMBOL\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff541662) for details of the symbol entry information. + +The following methods return information about a symbol in a symbol group: + +- [**GetSymbolName**](https://msdn.microsoft.com/library/windows/hardware/ff549121) returns the name of the symbol. + +- [**GetSymbolOffset**](https://msdn.microsoft.com/library/windows/hardware/ff549135) returns the absolute address in the target's virtual address space of the symbol, if the symbol has an absolute address. + +- [**GetSymbolRegister**](https://msdn.microsoft.com/library/windows/hardware/ff549165) returns the register containing the symbol, if the symbol is contained in a register. + +- [**GetSymbolSize**](https://msdn.microsoft.com/library/windows/hardware/ff549169) returns the size of the data for the symbol. + +- [**GetSymbolTypeName**](https://msdn.microsoft.com/library/windows/hardware/ff549188) returns the name of the symbol's type. + +- [**GetSymbolValueText**](https://msdn.microsoft.com/library/windows/hardware/ff549201) returns the value of the symbol as a string. + +If a symbol is stored in a register or in a memory location known to the debugger engine, its value can be changed using [**WriteSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff561457). + +A symbol is a *parent symbol* if it contains other symbols. For example, a structure contains its members. A symbol is a *child symbol* if it is contained in another symbol. A symbol may be both a parent and child symbol. Each symbol group has a flat structure and contains parent symbols and their children. Each symbol has a *depth* -- symbols without parents in the symbol group have a depth of zero, and the depth of each child symbol is one greater than the depth of its parent. The children of a parent symbol may or may not be present in the symbol group. When the children are present in the symbol group, the parent symbol is referred to as *expanded*. To add or remove the children of a symbol in a symbol group, use [**ExpandSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff543271). + +The number of symbols in a symbol group is returned by [**GetNumberSymbols**](https://msdn.microsoft.com/library/windows/hardware/ff547975). The *index* of a symbol in a symbol group is an identification number; the index ranges from zero to the number of symbols minus one. Each time a symbol is added to or removed from a symbol group -- for example, by expanding a symbol -- the index of all the symbols in the symbol group may change. + +The symbol parameters, including information about parent-child relationships, can be found by using [**GetSymbolParameters**](https://msdn.microsoft.com/library/windows/hardware/ff549146). This method returns a [**DEBUG\_SYMBOL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff541673) structure. + +The symbols in a symbol group can be printed to the debugger's output stream using the method [**OutputSymbols**](https://msdn.microsoft.com/library/windows/hardware/ff553264). + +### Scopes + +The *current scope*, or *current local context*, determines the local variables exposed by the debugger engine. The scope has three components: + +1. A stack frame. + +2. A current instruction. + +3. A register context. + +If the stack frame is at the top of the call stack, the current instruction is the instruction that resulted in the last event. Otherwise the current instruction is the function call which resulted in the next higher stack frame. + +The methods [**GetScope**](https://msdn.microsoft.com/library/windows/hardware/ff548270) and [**SetScope**](https://msdn.microsoft.com/library/windows/hardware/ff556773) can be used to get and set the current scope. When an event occurs, the current scope is set to the scope of the event. The current scope can be reset to the scope of the last event using [**ResetScope**](https://msdn.microsoft.com/library/windows/hardware/ff554577). + +### Thread Context + +The *thread context* is the state preserved by Windows when switching threads. This is similar to the register context, except that there is some kernel-only processor state that is part of the register context but not the thread context. This extra state is available as registers during kernel-mode debugging. + +The thread context is represented by the CONTEXT structure defined in ntddk.h. This structure is platform-dependent and its interpretation depends on the effective processor type. The methods [**GetThreadContext**](https://msdn.microsoft.com/library/windows/hardware/ff549291) and [**SetThreadContext**](https://msdn.microsoft.com/library/windows/hardware/ff556829) can be used to get and set the thread context. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Scopes%20and%20Symbol%20Groups%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/scratch-pad.md b/windows-driver-docs-pr/debugger/scratch-pad.md new file mode 100644 index 0000000000..65dc5e76f1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/scratch-pad.md @@ -0,0 +1,69 @@ +--- +title: Using the Scratch Pad +description: Using the Scratch Pad +ms.assetid: a0f6ce9c-7fad-4df6-bad8-0ea1bc5bfc52 +keywords: ["debugging information windows, Scratch Pad", "Scratch Pad"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Scratch Pad + + +## + + +The Scratch Pad window is a clipboard on which you can type and save text. + +### Opening the Scratch Pad Window + +To open or switch to the Scratch Pad window, in the WinDbg window, on the **View** menu, click **Scratch Pad**. (You can also press ALT+8 or click the **Scratch Pad (Alt+8)** button (![screen shot of the scratch pad button](images/tbspad.png)) on the toolbar.) + +The following screen shot shows an example of a Scratch Pad window. + +![screen shot of the scratch pad window](images/window-scratchpad.png) + +### Using the Scratch Pad Window + +In the Scratch Pad window, you can do the following: + +- To type in the Scratch Pad window, click in the window where you want to add text and begin typing. You can also use standard copy-and-paste features. The contents of the Scratch Pad window do not affect the operation of the debugger. This window exists solely to help with text editing. + +- If you close the Scratch Pad window, your text is preserved and is available when you reopen the window. You can also save text from the Scratch Pad window by associating it with a file. + +The Scratch Pad window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the window (![screen shot of the button that displays the scratch pad window toolbar shortcut menu](images/tbspad.png)). This menu contains the following commands: + +- (Menu only) **Associate with file** opens a dialog box through which you can select a text file. After the file is selected, the current text in the Scratch Pad is cleared and replaced with the text in the selected file. While Scratch Pad is associated with this file, all new text typed into Scratch Pad is saved to the file. Association with the file can be ended either by selecting the **End file association** short-cut menu option or by closing and reopening Scratch Pad. + +- (Menu only) **End file association** ends Scratch Pad's association with a specified text file. All text in Scratch Pad prior to selecting this option is saved in the file. All text typed in Scratch Pad after the association is ended is no longer saved in the text file. + +- **Dock** or **Undock** causes the window to enter or leave the docked state. + +- (Menu only) **Move to new dock** closes Scratch Pad and opens it in a new dock. + +- (Menu only) **Set as tab-dock target for window type** is unavailable for Scratch Pad. This option is only available for [Source](source-window.md) or [Memory](memory-window.md) windows. + +- **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +- **Help** opens this topic in the Debugging Tools for Windows documentation. + +- **Close** closes this window. + +### Additional Information + +For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). For more information about all techniques that you can use to control debugging information windows, see [Using Debugging Information Windows](using-debugging-information-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Scratch%20Pad%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/scsi-miniport-debugging.md b/windows-driver-docs-pr/debugger/scsi-miniport-debugging.md new file mode 100644 index 0000000000..e6dc54c4d8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/scsi-miniport-debugging.md @@ -0,0 +1,36 @@ +--- +title: SCSI Miniport Debugging +description: SCSI Miniport Debugging +ms.assetid: 6d1e9931-aab5-4f9b-940f-86d4fcb63dcb +keywords: ["SCSI Miniport debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SCSI Miniport Debugging + + +This section includes: + +[Overview of SCSI Miniport Debugging](overview-of-scsi-miniport-debugging.md) + +[Extensions for Debugging SCSI Miniport Drivers](extensions-for-debugging-scsi-miniport-drivers.md) + +[Bug Checks for SCSI Miniport Debugging](bug-checks-for-scsi-miniport-debugging.md) + +[Analyzing Stalled Drivers and Time-Outs](analyzing-stalled-drivers-and-time-outs.md) + +[Important Breakpoints for Analyzing Reproducible Problems](important-breakpoints-for-analyzing-reproducible-problems.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SCSI%20Miniport%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md b/windows-driver-docs-pr/debugger/scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md new file mode 100644 index 0000000000..7dd6fc4e15 --- /dev/null +++ b/windows-driver-docs-pr/debugger/scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md @@ -0,0 +1,30 @@ +--- +title: SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll) +description: SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll) +ms.assetid: 0c22fda3-8b89-4ee4-9547-3d10f417c2e4 +keywords: ["SCSI Miniport debugging, extensions (scsikd.dll and minipkd.dll)", "scsikd.dll (scsi miniport extensions)", "minipkd.dll (scsi miniport extensions)", "extensions, SCSI Miniport"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll) + + +Extension commands that are useful for debugging SCSI miniport drivers can be found in Scsikd.dll and Minipkd.dll. + +You can use the Scsikd.dll extension commands with any version of Windows. However, you can only use the Minipkd.dll extension commands with Windows XP and later versions of Windows. Commands in Minipkd.dll are only applicable to SCSIport-based miniports. + +For more information, see [SCSI Miniport Debugging](scsi-miniport-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SCSI%20Miniport%20Extensions%20%28Scsikd.dll%20and%20Minipkd.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/searching-for-debugging-servers.md b/windows-driver-docs-pr/debugger/searching-for-debugging-servers.md new file mode 100644 index 0000000000..4fcf74f757 --- /dev/null +++ b/windows-driver-docs-pr/debugger/searching-for-debugging-servers.md @@ -0,0 +1,63 @@ +--- +title: Searching for Debugging Servers +description: You can use KD or CDB with the -QR command-line option to obtain a list of available debugging servers that are running on a network server. +ms.assetid: 510d5f9a-cde8-4dc8-8e2f-80f84ad44fce +keywords: ["Searching for Debugging Servers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Searching for Debugging Servers +api_type: +- NA +--- + +# Searching for Debugging Servers + + +You can use KD or CDB with the **-QR** command-line option to obtain a list of available debugging servers that are running on a network server. + +This list may include servers that no longer exist but which were not shut down properly -- connecting to one of these generates an error message. The list will also include process servers and KD connection servers. The server type will be indicated in each case. + +The syntax for this is as follows: + +``` +Debugger -QR \\Server +``` + +## + + +*Debugger* can be either KD or CDB -- the display will be the same in either case. The two backslashes (**\\\\**) preceding *Server* are optional. + +In WinDbg, you can use the **Connect to Remote Debugger Session** dialog box to browse a list of available servers. See [File | Connect to Remote Session](file---connect-to-remote-session.md) for details. + +**Note**  For a debugging server to be discoverable, it must be activated with elevated privileges. For more information, see [Activating a Debugging Server](activating-a-debugging-server.md). + +  + +**Note**   +If you are not logged on to the client computer with an account that has access to the server computer, you might need to provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can discover debugging servers (running on the server computer) by using **-QR** or **Connect to Remote Debugger Session**. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Searching%20for%20Debugging%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/searching-for-kd-connection-servers.md b/windows-driver-docs-pr/debugger/searching-for-kd-connection-servers.md new file mode 100644 index 0000000000..f6cf13d531 --- /dev/null +++ b/windows-driver-docs-pr/debugger/searching-for-kd-connection-servers.md @@ -0,0 +1,63 @@ +--- +title: Searching for KD Connection Servers +description: You can use KD or CDB with the -QR command-line option to obtain a list of available KD connection servers that are running on a network server. +ms.assetid: 24ff0e2f-d40a-4f52-91ef-e766b9387a8a +keywords: ["Searching for KD Connection Servers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Searching for KD Connection Servers +api_type: +- NA +--- + +# Searching for KD Connection Servers + + +You can use KD or CDB with the **-QR** command-line option to obtain a list of available KD connection servers that are running on a network server. + +This list may include servers that no longer exist but which were not shut down properly -- connecting to one of these generates an error message. The list will also include debugging servers and user-mode process servers. The server type will be indicated in each case. + +The syntax for this is as follows: + +``` +Debugger -QR \\Server +``` + +## + + +*Debugger* can be either KD or CDB -- the display will be the same in either case. The two backslashes (**\\\\**) preceding *Server* are optional. + +In WinDbg, you can use the **Connect to Remote Stub Server** dialog box to browse a list of available KD connection servers. See [File | Connect to Remote Stub](file---connect-to-remote-stub.md) for more details. + +**Note**  For a KD connection server to be discoverable, it must be activated with elevated privileges. For more information, see [Activating a KD Connection Server](activating-a-kd-connection-server.md). + +  + +**Note**   +If you are not logged on to the client computer with an account that has access to the server computer, you might need to provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can discover KD connection servers (running on the server computer) by using **-QR** or **Connect to Remote Stub**. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Searching%20for%20KD%20Connection%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/searching-for-process-servers.md b/windows-driver-docs-pr/debugger/searching-for-process-servers.md new file mode 100644 index 0000000000..6d2a456cc5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/searching-for-process-servers.md @@ -0,0 +1,63 @@ +--- +title: Searching for Process Servers +description: You can use KD or CDB with the -QR command-line option to obtain a list of available process servers that are running on a network server computer. +ms.assetid: 2f0cd4df-f18a-4222-ab90-7aba0f177eff +keywords: ["Searching for Process Servers Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- Searching for Process Servers +api_type: +- NA +--- + +# Searching for Process Servers + + +You can use KD or CDB with the **-QR** command-line option to obtain a list of available process servers that are running on a network server computer. + +This list may include servers that no longer exist but which were not shut down properly -- connecting to one of these generates an error message. The list will also include debugging servers and KD connection servers. The server type will be indicated in each case. + +The syntax for this is as follows: + +``` +Debugger -QR \\Server +``` + +## + + +*Debugger* can be either KD or CDB -- the display will be the same in either case. The two backslashes (**\\\\**) preceding *Server* are optional. + +In WinDbg, you can use the **Connect to Remote Stub Server** dialog box to browse a list of available process servers. See [File | Connect to Remote Stub](file---connect-to-remote-stub.md) for more details. + +**Note**  For a process server to be discoverable, it must be activated with elevated privileges. For more information, see [Activating a Process Server](activating-a-process-server.md). + +  + +**Note**   +If you are not logged on to the client computer with an account that has access to the server computer, you might need to provide a user name and password. On the client computer, in a Command Prompt window, enter the following command. + +**net use \\\\***Server***\\ipc$ /user:***UserName* +where *Server* is the name of the server computer, and *UserName* is the name of an account that has access to the server computer. + +When you are prompted, enter the password for *UserName*. + +After this command succeeds, you can discover process servers (running on the server computer) by using **-QR** or **Connect to Remote Stub**. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Searching%20for%20Process%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/secure-mode.md b/windows-driver-docs-pr/debugger/secure-mode.md new file mode 100644 index 0000000000..11437b73db --- /dev/null +++ b/windows-driver-docs-pr/debugger/secure-mode.md @@ -0,0 +1,37 @@ +--- +title: Secure Mode +description: Secure Mode +ms.assetid: 6f233eb2-b2e6-478f-8127-4c6fbc46d613 +keywords: ["Secure Mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Secure Mode + + +## + + +When you are performing kernel-mode debugging, you can run the debugger in *Secure Mode*. This prevents the debugger from affecting the host computer, yet does not significantly decrease its freedom to debug the target computer. + +Secure Mode is recommended if you are going to allow remote clients to join your debugging session. + +This section includes: + +[Features of Secure Mode](features-of-secure-mode.md) + +[Activating Secure Mode](activating-secure-mode.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Secure%20Mode%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-considerations.md b/windows-driver-docs-pr/debugger/security-considerations.md new file mode 100644 index 0000000000..4fd37f5fe3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-considerations.md @@ -0,0 +1,33 @@ +--- +title: Security Considerations +description: Security Considerations for Windows Debugging Tools +ms.assetid: fb03b432-6c97-4b23-90b0-fd384376331f +keywords: security considerations, debugger security +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security Considerations + + +## + + +This section includes: + +[Security Vulnerabilities](security-vulnerabilities.md) + +[Secure Mode](secure-mode.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20Considerations%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-during-kernel-mode-debugging.md b/windows-driver-docs-pr/debugger/security-during-kernel-mode-debugging.md new file mode 100644 index 0000000000..a419dd3ad8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-during-kernel-mode-debugging.md @@ -0,0 +1,49 @@ +--- +title: Security During Kernel-Mode Debugging +description: Security During Kernel-Mode Debugging +ms.assetid: 0dc78f83-a695-4b2c-a5cd-d7f365a9560f +keywords: ["security considerations, kernel-mode debugging", "local kernel debugging, security considerations"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security During Kernel-Mode Debugging + + +## + + +Security during kernel-mode debugging is never about protecting the *target* computer. The target is completely vulnerable to the debugger -- this is the very nature of debugging. + +If a debugging connection was enabled during boot, it will remain vulnerable through the debugging port until its next boot. + +However, you should be concerned about security on the *host* computer. In an ideal situation, the debugger runs as an application on your host computer, but does not interact with other applications on this computer. There are three possible ways in which security problems could arise: + +- If you use corrupt or destructive extension DLLs, they could cause your debugger to take unexpected actions, possibly affecting the host computer. + +- It is possible that corrupt or destructive symbol files could also cause your debugger to take unexpected actions, possibly affecting the host computer. + +- If you are running a remote debugging session, an unexpected client might attempt to link to your server. Or perhaps the client you are expecting might attempt to perform actions that you do not anticipate. + +If you want to prevent a remote user from performing actions on your host computer, use [Secure Mode](secure-mode.md). + +For suggestions on how to guard against unexpected remote connections, see [Security During Remote Debugging](security-during-remote-debugging.md). + +If you are not performing remote debugging, you should still beware of bad symbol files and extension DLLs. Do not load symbols or extensions that you distrust! + +### Local Kernel Debugging + +Only users who have debug privileges can start a local kernel debugging session. If you are the administrator of a machine that has multiple user accounts, you should be aware that any user with these privileges can start a local kernel debugging session, effectively giving them control of all processes on the computer -- and therefore giving them access to all peripherals as well. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20During%20Kernel-Mode%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-during-postmortem-debugging.md b/windows-driver-docs-pr/debugger/security-during-postmortem-debugging.md new file mode 100644 index 0000000000..6e05f4ef4e --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-during-postmortem-debugging.md @@ -0,0 +1,35 @@ +--- +title: Security During Postmortem Debugging +description: Security During Postmortem Debugging +ms.assetid: 59c411c4-d829-4d1c-9820-e58188f0656c +keywords: ["security considerations, postmortem debugging", "postmortem debugging, security considerations"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security During Postmortem Debugging + + +## + + +Only an administrator can enable [postmortem debugging](enabling-postmortem-debugging.md). + +However, postmortem debugging is enabled for the entire system, not just for one user. Thus, after it has been enabled, any application crash will activate the debugger that has been chosen -- even if the current user does not have administrative privileges. + +Also, a postmortem debugger inherits the same privileges as the application that crashed. Thus, if a Windows service such as CSRSS and LSASS crashes, the debugger will have very high-level privileges. + +You should take this into account when choosing to enable postmortem debugging. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20During%20Postmortem%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-during-remote-debugging.md b/windows-driver-docs-pr/debugger/security-during-remote-debugging.md new file mode 100644 index 0000000000..da1431df79 --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-during-remote-debugging.md @@ -0,0 +1,55 @@ +--- +title: Security During Remote Debugging +description: Security During Remote Debugging +ms.assetid: 55e570d2-b005-4c09-ac8f-0632233a64bd +keywords: ["security considerations, remote debugging", "remote debugging through remote.exe, security considerations", "remote debugging through the debugger, security considerations", "process server, security considerations"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security During Remote Debugging + + +## + + +There are two ways to increase security during remote debugging: by restricting who can connect to your session and by restricting the powers of someone who does connect. + +### Controlling Access to the Debugging Session + +If you are performing [remote debugging through the debugger](remote-debugging-through-the-debugger.md), or using a [process server](process-servers--user-mode-.md) or [KD connection server](kd-connection-servers--kernel-mode-.md), any computer on your local network can attempt to attach to your debugging session. + +If you are using the TCP, 1394, COM, or named pipe protocols, you can require the Debugging Client to supply a password. However, this password is not encrypted during transmission, and therefore these protocols are not secure. + +If you want your Debugging Server to be secure, you must use secure sockets layer (SSL) or secure pipe (SPIPE) protocol. + +If you are performing [remote debugging through remote.exe](remote-debugging-through-remote-exe.md), you can use the **/u** parameter to prohibit connections from unauthorized users. + +### Restricting the Powers of the Client + +If you are setting up a kernel-mode debugging session, you can restrict the debugger's ability to interfere with the host machine by using [Secure Mode](secure-mode.md). + +In user mode, Secure Mode is not available. You can stop an intrusive client from issuing Microsoft MS-DOS commands and running external programs by issuing the [**.noshell (Prohibit Shell Commands)**](-noshell--prohibit-shell-commands-.md) command. However, there are many other ways for a client to interfere with your computer. + +Note that both Secure Mode and **.noshell** will prevent both the Debugging Client and the Debugging Server from taking certain actions. There is no way to place a restriction on the client but not on the server. + +### Forgotten Process Servers + +When you start a process server on a remote machine, the process server runs silently. + +If you perform remote debugging through this process server and then end the session, the process server continues to run. + +A forgotten process server is a potential target for an attack. You should always shut down an unneeded process server. Use the Kill.exe utility or Task Manager to terminate the process server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20During%20Remote%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-during-user-mode-debugging.md b/windows-driver-docs-pr/debugger/security-during-user-mode-debugging.md new file mode 100644 index 0000000000..f3a45c78f1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-during-user-mode-debugging.md @@ -0,0 +1,41 @@ +--- +title: Security During User-Mode Debugging +description: Security During User-Mode Debugging +ms.assetid: e198c29a-d793-4974-8ee3-f26679bd70b4 +keywords: ["security considerations, user-mode debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security During User-Mode Debugging + + +## + + +When a user-mode debugger is active, it can effectively control any of the processes on the computer. + +There are three possible ways in which security problems could arise during user-mode debugging: + +- If you use corrupt or destructive extension DLLs, they could cause your debugger to take unexpected actions, possibly affecting applications other than your target. + +- It is possible that corrupt or destructive symbol files could also cause your debugger to take unexpected actions, possibly affecting applications other than your target. + +- If you are running a remote debugging session, an unexpected client might attempt to link to your server. Or perhaps the client you are expecting might attempt to perform actions that you do not anticipate. + +For suggestions on how to guard against unexpected remote connections, see [Security During Remote Debugging](security-during-remote-debugging.md). After a remote client has joined a user-mode debugging session, there is no way to restrict its access to processes on your computer. + +If you are not performing remote debugging, you should still beware of bad symbol files and extension DLLs. do not load symbols or extensions that you distrust! + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20During%20User-Mode%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/security-vulnerabilities.md b/windows-driver-docs-pr/debugger/security-vulnerabilities.md new file mode 100644 index 0000000000..9e10d9310f --- /dev/null +++ b/windows-driver-docs-pr/debugger/security-vulnerabilities.md @@ -0,0 +1,37 @@ +--- +title: Security Vulnerabilities +description: This section covers debugging security vulnerabilities +ms.assetid: 2767987e-e247-4319-bc8e-0ff6906f2a5a +keywords: security vulnerabilities, debugger, security +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security Vulnerabilities + + +## + + +This section includes: + +[Security During Kernel-Mode Debugging](security-during-kernel-mode-debugging.md) + +[Security During User-Mode Debugging](security-during-user-mode-debugging.md) + +[Security During Postmortem Debugging](security-during-postmortem-debugging.md) + +[Security During Remote Debugging](security-during-remote-debugging.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Security%20Vulnerabilities%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/sending-output-to-the-debugger.md b/windows-driver-docs-pr/debugger/sending-output-to-the-debugger.md new file mode 100644 index 0000000000..c292cc7727 --- /dev/null +++ b/windows-driver-docs-pr/debugger/sending-output-to-the-debugger.md @@ -0,0 +1,49 @@ +--- +title: Sending Output to the Debugger +description: Sending Output to the Debugger +ms.assetid: e0640e70-9846-4239-a3ff-b78788751384 +keywords: ["sending output to the debugger", "OutputDebugString function", "DbgPrint function", "DbgPrintEx function", "KdPrint function", "KdPrintEx function"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending Output to the Debugger + + +## + + +User-mode and kernel-mode code use different routines to send output to the debugger. + +### User-Mode Output Routines + +**OutputDebugString** sends a null-terminated string to the debugger of the calling process. In a user-mode driver, **OutputDebugString** displays the string in the Debugger Command window. If a debugger is not running, this routine has no effect. **OutputDebugString** does not support the variable arguments of a **printf** formatted string. + +For complete documentation of this routine, see the Microsoft Windows SDK. + +### Kernel-Mode Output Routines + +**DbgPrint** displays output in the debugger window. This routine supports the basic **printf** format parameters. Only kernel-mode code can call **DbgPrint**. + +**DbgPrintEx** is similar to **DbgPrint**, but it allows you to "tag" your messages. When running the debugger, you can permit only those messages with certain tags to be sent. This allows you to view only those messages that you are interested in. For details, see [Reading and Filtering Debugging Messages](reading-and-filtering-debugging-messages.md). + +**Note**   In Windows Vista and later versions of Windows, **DbgPrint** produces tagged messages as well. This is a change from previous versions of Windows. + +  + +**KdPrint** and **KdPrintEx** are identical to **DbgPrint** and **DbgPrintEx**, respectively, when compiled in the checked build environment. When compiled in the free build environment, they have no effect. + +For complete documentation of these routines, as well as the build environment, see the Windows Driver Kit. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Sending%20Output%20to%20the%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-a-conditional-breakpoint.md b/windows-driver-docs-pr/debugger/setting-a-conditional-breakpoint.md new file mode 100644 index 0000000000..b45cb87d80 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-a-conditional-breakpoint.md @@ -0,0 +1,146 @@ +--- +title: Conditional breakpoints in WinDbg and other Windows debuggers +description: Conditional breakpoints in WinDbg and other Windows debuggers are useful when you need to break in only if a specific condition is satisfied. +ms.assetid: 9fa5b417-8904-48bc-ad5c-62ba35d70b73 +keywords: ["breakpoints, conditional", "conditional breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Conditional breakpoints in WinDbg and other Windows debuggers + + +Conditional breakpoints in WinDbg and other Windows debuggers are useful when you need to break in only if a specific condition is satisfied. + +## + + +A conditional breakpoint is created by combining a breakpoint command with either the [**j (Execute If - Else)**](j--execute-if---else-.md) command or the [**.if**](-if.md) token, followed by the [**gc (Go from Conditional Breakpoint)**](gc--go-from-conditional-breakpoint-.md) command. This breakpoint causes a break to occur only if a specific condition is satisfied. + +The basic syntax for a conditional breakpoint using the **j** command is as follows: + +``` +0:000> bp Address "j (Condition) 'OptionalCommands'; 'gc' " +``` + +The basic syntax for a conditional breakpoint using the **.if** token is as follows: + +``` +0:000> bp Address ".if (Condition) {OptionalCommands} .else {gc}" +``` + +Conditional breakpoints are best illustrated with an example. The following command sets a breakpoint at line 143 of the Mysource.cpp source file. When this breakpoint is hit, the variable **MyVar** is tested. If this variable is less than or equal to 20, execution continues; if it is greater than 20, execution stops. + +``` +0:000> bp `mysource.cpp:143` "j (poi(MyVar)>0n20) ''; 'gc' " +0:000> bp `mysource.cpp:143` ".if (poi(MyVar)>0n20) {} .else {gc}" +``` + +The preceding command has a fairly complicated syntax that contains the following elements: + +- The [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command sets breakpoints. Although the preceding example uses the bp command, you could also use the **bu (Set Unresolved Breakpoint)** command. For more information about the differences between **bp** and **bu**, and for a basic introduction to breakpoints, see [Using Breakpoints](using-breakpoints.md). + +- Source line numbers are specified by using grave accents ( **\`** ). For details, see [Source Line Syntax](source-line-syntax.md). + +- When the breakpoint is hit, the command in straight quotation marks ( **"** ) is executed. In this example, this command is a [**j (Execute If - Else)**](j--execute-if---else-.md) command or an [**.if**](-if.md) token, which tests the expression in parentheses. + +- In the source program, **MyVar** is an integer. If you are using C++ expression syntax, **MyVar** is interpreted as an integer. However, in this example (and in the default debugger configuration), MASM expression syntax is used. In a MASM expression, **MyVar** is treated as an address. Thus, you need to use the **poi** operator to dereference it. (If your variable actually is a C pointer, you will need to dereference it twice--for example, **poi(poi(MyPtr))**.) The **0n** prefix specifies that this number is decimal. For syntax details, see [MASM Numbers and Operators](masm-numbers-and-operators.md). + +- The expression in parentheses is followed by two commands, surrounded by single quotation marks ( **'** ) for the **j** command and curly brackets ( {} ) for the **.if** token. If the expression is true, the first of these commands is executed. In this example, there is no first command, so command execution will end and control will remain with the debugger. If the expression in parentheses is false, the second command will execute. The second command should almost always be a [**gc (Go from Conditional Breakpoint)**](gc--go-from-conditional-breakpoint-.md) command, because this command causes execution to resume in the same manner that was occurring before the breakpoint was hit (stepping, tracing, or free execution). + +If you want to see a message each time the breakpoint is passed or when it is finally hit, you can use additional commands in the single quotation marks or curly brackets. For example: + +``` +0:000> bp `:143` "j (poi(MyVar)>5) '.echo MyVar Too Big'; '.echo MyVar Acceptable; gc' " +0:000> bp `:143` ".if (poi(MyVar)>5) {.echo MyVar Too Big} .else {.echo MyVar Acceptable; gc} " +``` + +These comments are especially useful if you have several such breakpoints running at the same time, because the debugger does not display its standard "Breakpoint *n* Hit" messages when you are using a command string in the **bp** command. + +### Conditional Breakpoint Based on String Comparison + +In some situations you might want to break into the debugger only if a string variable matches a pattern. For example, suppose you want to break at kernel32!CreateEventW only if the *lpName* argument points to a string that matches the pattern "Global\*". The following example shows how to create the conditional breakpoint. + +``` +bp kernel32!CreateEventW "$$Conditional Breakpoints and Register Sign Extension + +You can set a breakpoint that is conditional on a register value. + +The following command will break at the beginning of the **myFunction** function if the **eax** register is equal to 0xA3: + +``` +0:000> bp mydriver!myFunction "j @eax = 0xa3 '';'gc'" +0:000> bp mydriver!myFunction ".if @eax = 0xa3 {} .else {gc}" +``` + +However, the following similar command will not necessarily break when **eax** equals 0xC0004321: + +``` +0:000> bp mydriver!myFunction "j @eax = 0xc0004321 '';'gc'" +0:000> bp mydriver!myFunction ".if @eax = 0xc0004321 {} .else {gc}" +``` + +The reason the preceding command will fail is that the MASM expression evaluator sign-extends registers whose high bit equals one. When **eax** has the value 0xC0004321, it will be treated as 0xFFFFFFFF\`C0004321 in computations--even though **eax** will still be displayed as 0xC0004321. However, the numeral **0xc0004321** is sign-extended in kernel mode, but not in user mode. Therefore, the preceding command will not work properly in user mode. If you mask the high bits of **eax**, the command will work properly in kernel mode--but now it will fail in user mode. + +You should formulate your commands defensively against sign extension in both modes. In the preceding command, you can make the command defensive by masking the high bits of a 32-bit register by using an AND operation to combine it with 0x00000000\`FFFFFFFF and by masking the high bits of a numeric constant by including a grave accent ( **\`** ) in its syntax. + +The following command will work properly in user mode and kernel mode: + +``` +0:000> bp mydriver!myFunction "j (@eax & 0x0`ffffffff) = 0x0`c0004321 '';'gc'" +0:000> bp mydriver!myFunction ".if (@eax & 0x0`ffffffff) = 0x0`c0004321 {} .else {gc}" +``` + +For more information about which numbers are sign-extended by the debugger, see [Sign Extension](sign-extension.md). + +### Conditional Breakpoints in WinDbg + +In WinDbg, you can create a conditional breakpoint by clicking [Breakpoints](edit---breakpoints.md) from the **Edit** menu, entering a new breakpoint address into the **Command** box, and entering a condition into the **Condition** box. + +For example, typing **mymod!myFunc+0x3A** into the **Command** box and **myVar < 7** into the **Condition** box is equivalent to issuing the following command: + +``` +0:000> bu mymod!myFunc+0x3A "j(myVar<7) '.echo "Breakpoint hit, condition myVar<7"'; 'gc'" +0:000> bu mymod!myFunc+0x3A ".if(myVar<7) {.echo "Breakpoint hit, condition myVar<7"} .else {gc}" +``` + +### Restrictions on Conditional Breakpoints + +If you are [controlling the user-mode debugger from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md), you cannot use conditional breakpoints or any other breakpoint command string that contains the [**gc (Go from Conditional Breakpoint)**](gc--go-from-conditional-breakpoint-.md) or [**g (Go)**](g--go-.md) commands. If you use these commands, the serial interface might not be able to keep up with the number of breakpoint passes, and you will be unable to break back into CDB. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Conditional%20breakpoints%20in%20WinDbg%20and%20other%20Windows%20debuggers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-and-clearing-flags-for-silent-process-exit.md b/windows-driver-docs-pr/debugger/setting-and-clearing-flags-for-silent-process-exit.md new file mode 100644 index 0000000000..f4705a6378 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-and-clearing-flags-for-silent-process-exit.md @@ -0,0 +1,49 @@ +--- +title: Configuring Silent Process Exit Monitoring +description: Beginning in Windows 7, you can use the Silent Process Exit tab to enable and configure monitoring of silent exit for a process. +ms.assetid: 93DD3B6A-533D-4060-9EE6-0CE91B2BE612 +--- + +# Configuring Silent Process Exit Monitoring + + +Beginning in Windows 7, you can use the **Silent Process Exit** tab to enable and configure monitoring of silent exit for a process. + +## + + +Settings that you specify in the **Silent Process Exit** tab are saved in the registry and remain effective until you change them. + +**To enable and configure silent process exit monitoring** + +1. Click the **Silent Process Exit** tab. + + The following screen shot shows the **Silent Process Exit** tab in Windows 8. + + ![screen shot of the image file tab in windows vista ](images/gflagssilentprocessexit01.png) + +2. In the **Image** box, type the name of an executable file, including the file name extension, and then press the TAB key. + + This activates the check boxes on the **Silent Process Exit** tab. + +3. Specify your preferences by selecting or clearing check boxes and by entering values in text boxes. + +4. When you specified all of your preferences, click **Apply**. + +## Related topics + + +[Monitoring Silent Process Exit](registry-entries-for-silent-process-exit.md) + +[Enable silent process exit monitoring](enable-silent-process-exit-monitoring.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Configuring%20Silent%20Process%20Exit%20Monitoring%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-and-clearing-image-file-flags.md b/windows-driver-docs-pr/debugger/setting-and-clearing-image-file-flags.md new file mode 100644 index 0000000000..97e714bb33 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-and-clearing-image-file-flags.md @@ -0,0 +1,45 @@ +--- +title: Setting and Clearing Image File Flags +description: Setting and Clearing Image File Flags +ms.assetid: 8f9ea2df-c172-43e0-98c5-0983f68a66f4 +keywords: ["GFlags, image file flags"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting and Clearing Image File Flags + + +## + + +Image file settings affect instances of the specified program that start after the command completes. They are saved in the registry and remain effective until you change them. + +**To set and clear the image file registry flags** + +1. Click the **Image File** tab. + + The following screen shot shows the **Image File** tab in Windows Vista. + + ![screen shot of the image file tab in windows vista ](images/gflags-image.png) + +2. In the **Image** box, type the name of an executable file or DLL, including the file name extension,and then press the TAB key. + + This activates the check boxes on the **Image File** tab. + +3. Set or clear a flag by selecting or clearing the check box associated with the flag. + +4. When you have selected or cleared all of the flags you want, click **Apply**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20and%20Clearing%20Image%20File%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-and-clearing-kernel-flags.md b/windows-driver-docs-pr/debugger/setting-and-clearing-kernel-flags.md new file mode 100644 index 0000000000..d40ee7fe6b --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-and-clearing-kernel-flags.md @@ -0,0 +1,43 @@ +--- +title: Setting and Clearing Kernel Flags +description: Setting and Clearing Kernel Flags +ms.assetid: 6bca8007-2d9f-4b93-b5fb-300c262604c8 +keywords: ["GFlags, kernel flags", "GFlags, run-time settings"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting and Clearing Kernel Flags + + +## + + +Kernel flag settings, also known as "run-time settings," affect the entire system. They take effect immediately without rebooting, but they are lost if you shut down or restart the system. + +Kernel settings take precedence over registry settings during run time, but when you shut down or restart the system, the kernel flag settings are lost and the registry settings are effective again. + +**To set and clear kernel flags** + +1. Click the **Kernel Flags** tab. + + The following screen shot shows the **Kernel Flags** tab in Windows Vista. + + ![screen shot of the kernel flags tab in windows vista ](images/gflags-kernel.png) + +2. Set or clear a flag by selecting or clearing the check box associated with the flag. + +3. When you have selected or cleared all of the flags that you want, click **Apply**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20and%20Clearing%20Kernel%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-and-clearing-system-wide-flags.md b/windows-driver-docs-pr/debugger/setting-and-clearing-system-wide-flags.md new file mode 100644 index 0000000000..f249c618a4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-and-clearing-system-wide-flags.md @@ -0,0 +1,41 @@ +--- +title: Setting and Clearing System-wide Flags +description: Setting and Clearing System-wide Flags +ms.assetid: 447bf08e-b178-4aaf-956a-469222b5029a +keywords: ["GFlags, system-wide flags"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting and Clearing System-wide Flags + + +## + + +System-wide registry settings affect all processes running on Windows. They are saved in the registry and remain effective until you change them. + +**To set and clear system-wide registry flags** + +1. Click the **System Registry** tab. + + The following screen shot shows the System Registry tab in Windows Vista.![screen shot of the system registry tab in windows vista](images/gflags-registry.png) + +2. Set or clear a flag by selecting or clearing the check box associated with the flag. + +3. When you have selected or cleared all of the flags that you want, click **Apply**. + +4. Restart Windows to make the changes effective. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20and%20Clearing%20System-wide%20Flags%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-breakpoints-in-cdb.md b/windows-driver-docs-pr/debugger/setting-breakpoints-in-cdb.md new file mode 100644 index 0000000000..5d8238dc3b --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-breakpoints-in-cdb.md @@ -0,0 +1,20 @@ +--- +title: Setting Breakpoints in CDB +description: Setting Breakpoints in CDB +ms.assetid: 7FCD6540-6593-42CB-A148-8974F25F3886 +--- + +# Setting Breakpoints in CDB + + +You can set, view, and manipulate breakpoints in CDB by entering commands. For a list of commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Breakpoints%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-breakpoints-in-kd.md b/windows-driver-docs-pr/debugger/setting-breakpoints-in-kd.md new file mode 100644 index 0000000000..7f46aab029 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-breakpoints-in-kd.md @@ -0,0 +1,20 @@ +--- +title: Setting Breakpoints in KD +description: Setting Breakpoints in KD +ms.assetid: AA7F46B7-A140-48CB-B5C0-F64BF800B0D3 +--- + +# Setting Breakpoints in KD + + +You can set, view, and manipulate breakpoints in KD by entering commands. For a list of commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Breakpoints%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-breakpoints-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-breakpoints-in-visual-studio.md new file mode 100644 index 0000000000..b0fbdc12e1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-breakpoints-in-visual-studio.md @@ -0,0 +1,22 @@ +--- +title: Setting Breakpoints in Visual Studio +description: The procedure covers Setting Breakpoints in Visual Studio. +ms.assetid: 503CAAEB-B400-4941-A0AE-B3C5CC8C364B +--- + +# Setting Breakpoints in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +You can set, view, and manipulate breakpoints by entering commands in the Debugger Immediate Window. For a list of commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). If the Debugger Immediate window is not already open, from the **Debug** menu, choose **Windows>Immediate**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Breakpoints%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-breakpoints-in-windbg.md b/windows-driver-docs-pr/debugger/setting-breakpoints-in-windbg.md new file mode 100644 index 0000000000..b12240882c --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-breakpoints-in-windbg.md @@ -0,0 +1,37 @@ +--- +title: Setting Breakpoints in WinDbg +description: There are several ways you can set, view, and manipulate breakpoints using WinDbg. +ms.assetid: 4A7BE6D2-05AF-4EFB-8F24-C19B1A98217C +--- + +# Setting Breakpoints in WinDbg + + +There are several ways you can set, view, and manipulate breakpoints using WinDbg. + +## Debugger Command Window + + +You can set, view, and manipulate breakpoints by entering commands in the Debugger Command Window. For a list of commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +## WinDbg Menu + + +You can open the **Breakpoints** dialog box by choosing **Breakpoints** from the **Edit** menu or by pressing ALT+F9. This dialog box lists all breakpoints, and you can use it to disable, enable, or clear existing breakpoints or to set new breakpoints. + +## Code Windows + + +The Disassembly window and the Source windows highlight lines that have breakpoints set. Enabled breakpoints are red, and disabled breakpoints are yellow. + +If you set the cursor on a specific line in the Disassembly window or in a Source window, you can press F9 to set a breakpoint at that line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Breakpoints%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-breakpoints.md b/windows-driver-docs-pr/debugger/setting-breakpoints.md new file mode 100644 index 0000000000..e793ead02a --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-breakpoints.md @@ -0,0 +1,41 @@ +--- +title: Setting Breakpoints +description: Setting Breakpoints +ms.assetid: 9715c35a-0c8c-4e89-be28-2899f21ec964 +keywords: ["Debugger Engine API, setting breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Breakpoints + + +## + + +Breakpoints are created with the [**AddBreakpoint**](https://msdn.microsoft.com/library/windows/hardware/ff537856) method. This method creates an [IDebugBreakpoint](https://msdn.microsoft.com/library/windows/hardware/ff549812) object that represents the breakpoint. It also set the *breakpoint type* (software breakpoint or processor breakpoint). Once a breakpoint has been created, its type cannot be changed. + +Breakpoints are deleted with the [**RemoveBreakpoint**](https://msdn.microsoft.com/library/windows/hardware/ff554487) method. This also deletes the **IDebugBreakpoint** object; this object may not be used again. + +**Note**   Although **IDebugBreakpoint** implements the **IUnknown** interface, the methods **IUnknown::AddRef** and **IUnknown::Release** are not used to control the lifetime of the breakpoint. These methods have no effect on the lifetime of the breakpoint. Instead, an **IDebugBreakpoint** object is deleted after the method [**RemoveBreakpoint**](https://msdn.microsoft.com/library/windows/hardware/ff554487) is called. + +  + +When the breakpoint is created, it is given a unique *breakpoint ID*. This identifier will not change. However, after the breakpoint has been deleted, its ID may be used for another breakpoint. For details on how to receive notification of the removal of a breakpoint, see [Monitoring Events](monitoring-events.md). + +When a breakpoint is created, it is initially disabled; this means that it will not cause the target to stop executing. This breakpoint may be enabled by using the method [**AddFlags**](https://msdn.microsoft.com/library/windows/hardware/ff537903) to add the DEBUG\_BREAKPOINT\_ENABLED flag. + +When a breakpoint is first created, it has the memory location 0x00000000 associated with it. The location can be changed by using [**SetOffset**](https://msdn.microsoft.com/library/windows/hardware/ff556741) with an address, or by using [**SetOffsetExpression**](https://msdn.microsoft.com/library/windows/hardware/ff556745) with a symbolic expression. The breakpoint's location should be changed from its initial value before it is used. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-cdb.md b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-cdb.md new file mode 100644 index 0000000000..cbc3a003c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-cdb.md @@ -0,0 +1,70 @@ +--- +title: Setting Symbol and Executable Image Paths in CDB +description: Setting Symbol and Executable Image Paths in CDB +ms.assetid: 6BBB7DC4-716E-4717-8C48-7E778907E85B +--- + +# Setting Symbol and Executable Image Paths in CDB + + +## Symbol Path + + +The symbol path specifies the directories where the symbol files are located. For more information about symbols and symbol files, see [Symbols](symbols.md). + +**Note**   If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the srv\* or symsrv\* string within your symbol path. For more information about symbol servers, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +  + +To control the symbol path in CDB, do one of the following: + +- Enter the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command. If you are using a symbol server, the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command is similar to .sympath but saves you typing. + +- When you start the debugger, use the **-y** command-line option. See [**CDB Command-Line Options**](cdb-command-line-options.md). + +- Before you start the debugger, use the \_NT\_SYMBOL\_PATH and \_NT\_ALT\_SYMBOL\_PATH [environment variables](environment-variables.md) to set the path. The symbol path is created by appending \_NT\_SYMBOL\_PATH after \_NT\_ALT\_SYMBOL\_PATH. (Typically, the path is set through the \_NT\_SYMBOL\_PATH. However, you might want to use \_NT\_ALT\_SYMBOL\_PATH to override these settings in special cases, such as when you have private versions of shared symbol files.) + + **Note**  If you use the **-sins** command-line option, the debugger ignores the symbol path environment variable. + +   + +## Executable Image Path + + +### + +An executable file is a binary file that the processor can run. These files typically have the .exe, .dll, or .sys file name extension. Executable files are also known as modules, especially when executable files are described as units of a larger application. Before the Windows operating system runs an executable file, it loads it into memory. The copy of the executable file in memory is called the executable image or the image. + +**Note**   These terms are sometimes used imprecisely. For example, some documents might use "image" for the actual file on the disk. Also, the Windows kernel and HAL have special module names. For example, the **nt** module corresponds to the Ntoskrnl.exe file. + +  + +The executable image path specifies the directories that the binary executable files are located in. + +In most situations, the debugger knows the location of the executable files, so you do not have to set the path for this file. + +However, there are situations when this path is required. For example, kernel-mode [small memory dump](small-memory-dump.md) files do not contain all of the executable files that exist in memory at the time of a stop error (that is, a crash). Similarly, user-mode minidump files do not contain the application binaries. If you set the path of the executable files, the debugger can find these binary files. + +The debugger's executable image path is a string that consists of multiple directory paths, separated by semicolons. Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported. The debugger searches the executable image path recursively. That is, the debugger searches the subdirectories of each directory that is listed in this path. + +To control the executable image path in CDB, do one of the following: + +- Enter the [**.exepath (Set Executable Path)**](-exepath--set-executable-path-.md) command. + +- When you start the debugger, use the **-i** command-line option. See [**CDB Command-Line Options**](cdb-command-line-options.md). + +- Before you start the debugger, use the \_NT\_EXECUTABLE\_IMAGE\_PATH [environment variable](environment-variables.md) to set the path. + + **Note**  If you use the **-sins** command-line option, the debugger ignores the executable image path environment variable. + +   + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Symbol%20and%20Executable%20Image%20Paths%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-kd.md b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-kd.md new file mode 100644 index 0000000000..a7df280a7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-kd.md @@ -0,0 +1,71 @@ +--- +title: Setting Symbol and Executable Image Paths in KD +description: Setting Symbol and Executable Image Paths in KD +ms.assetid: AF1D0A9A-2A5C-4E69-8F8A-EF74027F6742 +--- + +# Setting Symbol and Executable Image Paths in KD + + +## Symbol Path + + +The symbol path specifies the directories where the symbol files are located. For more information about symbols and symbol files, see [Symbols](symbols.md). + +**Note**   If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the srv\* or symsrv\* string within your symbol path. For more information about symbol servers, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +  + +To control the symbol path in KD, do one of the following: + +- Enter the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command. If you are using a symbol server, the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command is similar to **.sympath** but saves you typing. + +- When you start the debugger, use the **-y** command-line option. See [**KD Command-Line Options**](kd-command-line-options.md). + +- Before you start the debugger, use the \_NT\_SYMBOL\_PATH and \_NT\_ALT\_SYMBOL\_PATH [environment variables](environment-variables.md) to set the path. The symbol path is created by appending \_NT\_SYMBOL\_PATH after \_NT\_ALT\_SYMBOL\_PATH. (Typically, the path is set through the \_NT\_SYMBOL\_PATH. However, you might want to use \_NT\_ALT\_SYMBOL\_PATH to override these settings in special cases, such as when you have private versions of shared symbol files.) + + **Note**  If you use the **-sins** command-line option, the debugger ignores the symbol path environment variable. + +   + +## Executable Image Path + + +### + +An executable file is a binary file that the processor can run. These files typically have the .exe, .dll, or .sys file name extension. Executable files are also known as modules, especially when executable files are described as units of a larger application. Before the Windows operating system runs an executable file, it loads it into memory. The copy of the executable file in memory is called the executable image or the image. + +**Note**   These terms are sometimes used imprecisely. For example, some documents might use "image" for the actual file on the disk. Also, Windows-based applications refer to the executable name, which typically includes the file name extension. But these applications refer to the module name, which does not include the file name extension. +Also, the Windows kernel and HAL have special module names. For example, the **nt** module corresponds to the Ntoskrnl.exe file. + +  + +The executable image path specifies the directories that the binary executable files are located in. + +In most situations, the debugger knows the location of the executable files, so you do not have to set the path for this file. + +However, there are situations when this path is required. For example, kernel-mode [small memory dump](small-memory-dump.md) files do not contain all of the executable files that exist in memory at the time of a stop error (that is, a crash). Similarly, user-mode minidump files do not contain the application binaries. If you set the path of the executable files, the debugger can find these binary files. + +The debugger's executable image path is a string that consists of multiple directory paths, separated by semicolons. Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported. The debugger searches the executable image path recursively. That is, the debugger searches the subdirectories of each directory that is listed in this path. + +To control the executable image path in KD, do one of the following: + +- Enter the [**.exepath (Set Executable Path)**](-exepath--set-executable-path-.md) command. + +- When you start the debugger, use the **-i** command-line option. See [**KD Command-Line Options**](kd-command-line-options.md). + +- Before you start the debugger, use the \_NT\_EXECUTABLE\_IMAGE\_PATH [environment variable](environment-variables.md) to set the path. + + **Note**  If you use the **-sins** command-line option, the debugger ignores the executable image path environment variable. + +   + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Symbol%20and%20Executable%20Image%20Paths%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-visual-studio.md new file mode 100644 index 0000000000..50c63ec571 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-visual-studio.md @@ -0,0 +1,38 @@ +--- +title: Setting Symbol and Executable Image Paths in Visual Studio +description: The procedure covers Setting Symbol and Executable Image Paths in Visual Studio +ms.assetid: BFFF9BBC-C926-4974-A43E-C3A2DDA74AA4 +--- + +# Setting Symbol and Executable Image Paths in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +## Setting the Symbol Path by Using a Property Page + + +1. On the host computer, in Visual Studio, choose **Options** from the **Tools** menu. +2. In the **Options** property box, navigate to **Debugging>Symbols**. +3. If you want to get symbols from a Microsoft symbol server, check **Microsoft Symbol Servers**. +4. If you want to get symbols from folders on the host computer, check **Environment Variable: \_NT\_SYMBOL\_PATH**. Then set the \_NT\_SYMBOL\_PATH [environment variable](general-environment-variables.md). + +## Setting the Symbol Path by Entering a Command + + +In Visual Studio, in the Debugger Immediate Window, enter the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command. + +## Setting the Executable Image Path by Entering a Command + + +In Visual Studio, in the Debugger Immediate Window, enter the [**.exepath (Set Executable Path)**](-exepath--set-executable-path-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Symbol%20and%20Executable%20Image%20Paths%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-windbg.md b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-windbg.md new file mode 100644 index 0000000000..75b63d630a --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-symbol-and-source-paths-in-windbg.md @@ -0,0 +1,74 @@ +--- +title: Setting Symbol and Executable Image Paths in WinDbg +description: Setting Symbol and Executable Image Paths in WinDbg +ms.assetid: 8EA2509E-0B47-4D28-B934-F1F58F5CFC45 +--- + +# Setting Symbol and Executable Image Paths in WinDbg + + +## Symbol Path + + +The symbol path specifies the directories where the symbol files are located. For more information about symbols and symbol files, see [Symbols](symbols.md). + +**Note**   If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the srv\* or symsrv\* string within your symbol path. For more information about symbol servers, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +  + +To control the symbol path in WinDbg, do one of the following: + +- Choose **Symbol File Path** from the **File** menu or press CTRL+S. + +- Use the [**.sympath (Set Symbol Path)**](-sympath--set-symbol-path-.md) command. If you are using a symbol server, the [**.symfix (Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command is similar to **.sympath** but saves you typing. + +- When you start the debugger, use the **-y** command-line option. See [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +- Before you start the debugger, use the \_NT\_SYMBOL\_PATH and \_NT\_ALT\_SYMBOL\_PATH [environment variables](environment-variables.md) to set the path. The symbol path is created by appending \_NT\_SYMBOL\_PATH after \_NT\_ALT\_SYMBOL\_PATH. (Typically, the path is set through the \_NT\_SYMBOL\_PATH. However, you might want to use \_NT\_ALT\_SYMBOL\_PATH to override these settings in special cases, such as when you have private versions of shared symbol files.) If you try to add an invalid directory through these environment variables, the debugger ignores this directory. + + **Note**  If you use the -**sins** command-line option, the debugger ignores the symbol path environment variable. + +   + +## Executable Image Path + + +### + +An executable file is a binary file that the processor can run. These files typically have the .exe, .dll, or .sys file name extension. Executable files are also known as modules, especially when executable files are described as units of a larger application. Before the Windows operating system runs an executable file, it loads it into memory. The copy of the executable file in memory is called the executable image or the image. + +**Note**   These terms are sometimes used imprecisely. For example, some documents might use "image" for the actual file on the disk. Also, the Windows kernel and HAL have special module names. For example, the **nt** module corresponds to the Ntoskrnl.exe file. + +  + +The executable image path specifies the directories that the binary executable files are located in. + +In most situations, the debugger knows the location of the executable files, so you do not have to set the path for this file. + +However, there are situations when this path is required. For example, kernel-mode [small memory dump](small-memory-dump.md) files do not contain all of the executable files that exist in memory at the time of a stop error (that is, a crash). Similarly, user-mode minidump files do not contain the application binaries. If you set the path of the executable files, the debugger can find these binary files. + +The debugger's executable image path is a string that consists of multiple directory paths, separated by semicolons. Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported. The debugger searches the executable image path recursively. That is, the debugger searches the subdirectories of each directory that is listed in this path. + +To control the executable image path in WinDbg, do one of the following: + +- Choose **Image File Path** from the **File** menu, or press CTRL+I. + +- Use the [**.exepath (Set Executable Path)**](-exepath--set-executable-path-.md) command. + +- When you start the debugger, use the **-i** command-line option. See [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +- Before you start the debugger, use the \_NT\_EXECUTABLE\_IMAGE\_PATH [environment variable](environment-variables.md) to set the path. + + **Note**  If you use the **-sins** command-line option, the debugger ignores the executable image path environment variable. + +   + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Symbol%20and%20Executable%20Image%20Paths%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection-in-visual-studio.md new file mode 100644 index 0000000000..3c68c4b789 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection-in-visual-studio.md @@ -0,0 +1,116 @@ +--- +title: Setting Up Kernel-Mode Debugging over a 1394 Cable in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a 1394 (Firewire) cable. +ms.assetid: 07784500-83F1-4927-998F-7CEEEADAA2B0 +--- + +# Setting Up Kernel-Mode Debugging over a 1394 Cable in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a 1394 (Firewire) cable. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up 1394 debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging over a 1394 Cable Manually](setting-up-a-1394-cable-connection.md). + +The computer that runs the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. The host and target computers must each have a 1394 adapter. + +## Configuring the host and target computers + + +1. Connect a 1394 cable to the 1394 controllers that you have chosen for debugging on the host and target computers. +2. Begin configuring your host and target computers as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +3. On the host computer, in Visual Studio, when you get to the Computer Configuration dialog, select **Provision computer and choose debugger settings**. +4. For **Connection Type**, choose **Firewire**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, port number, key, host ip, and bus parameters](images/setup1394vs.png) + + For **Channel**, enter a decimal number of your choice from 1 through 62. + + **Note**  Do not set the channel to 0 when you first set up debugging. Because the default channel value is 0, the software assumes there is no change and does not update the settings. If you must use channel 0, first use an alternate channel (1 through 62) and then switch to channel 0. + +   + + If you have more than one 1394 controller on the target computer, enter a **Bus Parameters** value of *b*.*d*.*f*, where *b*, *d*, and *f* are the bus, device, and function numbers for the 1394 controller that you intend to use for debugging on the target computer. The bus, device, and function numbers must be in decimal format (example: 4.4.0). + +5. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +## Verifying dbgsettings on the Target Computer + + +On the target computer, open a Command Prompt window as Administrator, and enter this command: + +**bcdedit /dbgsettings** + +**bcdedit /enum** + +``` +... +debugtype 1394 +debugport 1 +baudrate 115200 +channel 1 +... +busparams 4.0.0 +... +``` + +Verify that *debugtype* is 1394 and *channel* is the channel number you specified in Visual Studio on the host computer. You can ignore the values of *debugport* and *baudrate*; they do not apply to debugging over 1394. + +If you entered **Bus Parameters** in Visual Studio, verify that *busparams* matches the bus parameters you specified. + +If you do not see the value you entered for **Bus Parameters**, enter this command: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +where *b*, *d*, and *f* are the bus, device, and function numbers of the 1394 controller on the target computer that you have chosen to use for debugging. + +For example: + +**bcdedit /set "{dbgsettings}" busparams 4.4.0** + +## Starting a Debugging Session for the First Time + + +1. On the host computer, open Visual Studio as Administrator. +2. On the **Tools** menu, choose **Attach to Process**. +3. For **Transport**, choose **Windows Kernel Mode Debugger**. +4. For **Qualifier**, select the name of the target computer that you previously configured. +5. Click **Attach**. + +At this point, the 1394 debug driver gets installed on the host computer. This is why it is important to run Visual Studio as Administrator. After the 1394 debug driver is installed, you do not need to run as Administrator for subsequent debugging sessions. + +## Starting a Debugging Session + + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the name of the target computer that you previously configured. +4. Click **Attach**. + +## Troubleshooting Tips for Debugging over a 1394 Cable + + +Most 1394 debugging problems are caused by using multiple 1394 controllers in either the host or target computer. Using multiple 1394 controllers in the host computer is not supported. The 1394 debug driver, which runs on the host, can communicate only with the first 1394 controller enumerated in the registry. If you have a 1394 controller built into the motherboard and a separate 1394 card, either remove the card or disable (by using Device Manager) the built-in controller. + +The target computer can have multiple 1394 controllers, although this is not recommended. If your target computer has a 1394 controller on the motherboard, use that controller for debugging, if possible. If there is an additional 1394 card, you should remove the card and use the onboard controller. Another solution is to disable the onboard 1394 controller in the BIOS settings of the computer. + +If you decide to have multiple 1394 controllers enabled on the target computer, you must specify bus parameters so that the debugger knows which controller to claim for debugging. To specify the bus parameters, Open Device Manager, and locate the 1394 controller that you want to use for debugging. Open the property page for the controller, and make a note of the bus number, device number, and function number. In an elevated Command Prompt Window, enter the following command, where *b*, *d*, and *f* are the bus, device and function numbers in decimal format: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +Reboot the target computer. + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%201394%20Cable%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection.md b/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection.md new file mode 100644 index 0000000000..97661fea9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-1394-cable-connection.md @@ -0,0 +1,109 @@ +--- +title: Setting Up Kernel-Mode Debugging over a 1394 Cable Manually +description: Debugging Tools for Windows supports kernel debugging over a 1394 (Firewire) cable. This topic describes how to set up 1394 debugging manually. +ms.assetid: bcfc61a1-0315-451c-a279-f6305995b05f +keywords: making a 1394 cable connection, 1394 connection, IEEE 1394 cable, FireWire cable +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging over a 1394 Cable Manually + + +Debugging Tools for Windows supports kernel debugging over a 1394 (Firewire) cable. This topic describes how to set up 1394 debugging manually. + +As an alternative to setting up 1394 debugging manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging over a 1394 Cable in Visual Studio](setting-up-a-1394-cable-connection-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. The host and target computers must each have a 1394 adapter and must be running Windows XP or later. The host and target computers do not have to be running the same version of Windows. + +## Setting Up the Target Computer + + +1. Connect a 1394 cable to the 1394 controllers that you have chosen for debugging on the host and target computers. +2. In an elevated Command Prompt window, enter the following commands, where *n* is a channel number of your choice, from 0 through 62: + + **bcdedit /debug on** + + **bcdedit /dbgsettings 1394 channel:***n* + +3. If there is more than one 1394 controller on the target computer, you must specify the bus, device, and function numbers of the 1394 controller that you intend to use for debugging. For more information, see [Troubleshooting Tips for 1394 Debugging](#troubleshooting-tips-for-debugging-over-a-1394-cable). + +4. Do not reboot the target computer yet. + +## Starting a Debugging Session for the First Time + + +1. Determine the bitness (32-bit or 64-bit) of Windows running on the host computer. +2. On the host computer, open a version of WinDbg (as Administrator) that matches the bitness of Windows running on the host computer. For example, if the host computer is running a 64-bit version of Windows, open the 64-bit version of WinDbg as Administrator. +3. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **1394** tab. Enter your channel number, and click **OK**. + + At this point, the 1394 debug driver gets installed on the host computer. This is why it is important to match the bitness of WinDbg to the bitness of Windows. After the 1394 debug driver is installed, you can use either the 32-bit or 64-bit version of WinDbg for subsequent debugging sessions. + +4. Reboot the target computer. + +## Starting a Debugging Session + + +### Using WinDbg + +- On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **1394** tab. Enter your channel number, and click **OK**. + + You can also start a session with WinDbg by entering the following command in a Command Prompt window, where *n* is your channel number: + + **windbg /k 1394:channel=***n* + +### Using KD + +- On the host computer, open a Command Prompt window and enter the following command, where *n* is your channel number: + + **kd /k 1394:channel=***n* + +## Using Environment Variables + + +On the host computer, you can use environment variables to specify the 1394 channel. Then you do not have to specify the channel each time you start a debugging session. To use environment variables to specify the 1394 channel, open a Command Prompt window and enter the following commands, where *n* is your channel number: + +- **set \_NT\_DEBUG\_BUS=1394** +- **set \_NT\_DEBUG\_1394\_CHANNEL=***n* + +To start a debugging session, open a Command Prompt window and enter one of the following commands: + +- **kd** +- **windbg** + +## Additional Information + + +For complete documentation of the **bcdedit** command and the boot.ini file, see Boot Options for Driver Testing and Debugging in the Windows Driver Kit (WDK) documentation. + +## Troubleshooting Tips for Debugging over a 1394 Cable + + +Most 1394 debugging problems are caused by using multiple 1394 controllers in either the host or target computer. Using multiple 1394 controllers in the host computer is not supported. The 1394 debug driver, which runs on the host, can communicate only with the first 1394 controller enumerated in the registry. If you have a 1394 controller built into the motherboard and a separate 1394 card, either remove the card or disable the built-in controller in the BIOS settings of the computer. + +The target computer can have multiple 1394 controllers, although this is not recommended. If your target computer has a 1394 controller on the motherboard, use that controller for debugging, if possible. If there is an additional 1394 card, you should remove the card and use the onboard controller. Another solution is to disable the onboard 1394 controller in the BIOS settings of the computer. + +If you decide to have multiple 1394 controllers enabled on the target computer, you must specify bus parameters so that the debugger knows which controller to claim for debugging. To specify the bus parameters, Open Device Manager on the target computer, and locate the 1394 controller that you want to use for debugging. Open the property page for the controller, and make a note of the bus number, device number, and function number. In an elevated Command Prompt Window, enter the following command, where *b*, *d*, and *f* are the bus, device and function numbers in decimal format: + +**bcdedit -set "{dbgsettings}" busparams** *b***.***d***.***f*. + +Reboot the target computer. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%201394%20Cable%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md new file mode 100644 index 0000000000..19685f62ae --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md @@ -0,0 +1,98 @@ +--- +title: Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging of a virtual machine. +ms.assetid: E7A289CA-29CE-4C6F-AD08-529E58379715 +--- + +# Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging of a virtual machine. The virtual machine can be located on the same physical computer as the debugger or on a different computer that is connected to the same network. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up debugging of a virtual machine, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging of a Virtual Machine Manually](attaching-to-a-virtual-machine--kernel-mode-.md). + +The computer that runs the debugger is called the *host computer*, and the virtual machine that is being debugged is called the *target virtual machine*. + +## Configuring the Target Virtual Machine + + +1. In the virtual machine, in an elevated Command Prompt window, enter the following commands. + + **bcdedit /debug on** + + **bcdedit /dbgsettings serial debugport:***n* **baudrate:115200** + + where *n* is the number of a COM port on the virtual machine. + +2. Reboot the virtual machine. +3. In the virtual machine, configure the COM port to map to a named pipe. The debugger will connect through this pipe. For more information about how to create this pipe, see your virtual machine's documentation. + +## Configuring the Host Computer + + +The host computer can be the same physical computer that is running the virtual machine, or it can be a separate computer. + +1. On the host computer, in Visual Studio, on the **Driver** menu, choose **Test > Configure Computer**. +2. Click **Add New Computer**. +3. For **Computer name**, enter the name of the physical computer that is running the target virtual machine. +4. Select **Manually configure debuggers and do not provision**, and click **Next**. +5. For **Connection Type**, select **Serial**. +6. Check **Pipe**, and check **Reconnect**. +7. If the debugger is running on the same computer as the virtual machine, enter the following for **Pipe name**: + + **\\\\.\\pipe\\***PipeName*. + + If the debugger is running on a different computer from the virtual machine, enter the following for **Pipe name**: + + **\\\\***VMHost***\\pipe\\***PipeName* + + where, *VMHost* is the name of the physical computer that is running the target virtual machine, and *PipeName* is the name of the pipe that you associated with the COM port on the target virtual machine. + +8. Click **Next**. Click **Finish**. + +## Starting the Debugging Session + + +1. On the host computer, in Visual Studio, on the **Debug** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the name of the physical computer that is running the target virtual machine. +4. Click **Attach**. + +## Generation 2 Virtual Machines + + +By default, COM ports are not presented in generation 2 virtual machines. You can add COM ports through PowerShell or WMI. For the COM ports to be displayed in the Hyper-V Manager console, they must be created with a path. + +To enable kernel debugging using a COM port on a generation 2 virtual machine, follow these steps: + +1. Disable Secure Boot by entering this PowerShell command: + + **Set-VMFirmware –Vmname** *VmName* **–EnableSecureBoot Off** + + where *VmName* is the name of your virtual machine. + +2. Add a COM port to the virtual machine by entering this PowerShell command: + + **Set-VMComPort –VMName** *VmName* **1 \\\\.\\pipe\\***PipeName* + + For example, the following command configures the first COM port on virtual machine TestVM to connect to named pipe TestPipe on the local computer. + + **Set-VMComPort –VMName TestVM 1 \\\\.\\pipe\\TestPipe** + +For more information, see [Generation 2 Virtual Machine Overview](http://go.microsoft.com/fwlink/p/?Linkid=331326). + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20of%20a%20Virtual%20Machine%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection-in-visual-studio.md new file mode 100644 index 0000000000..f25cbec663 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection-in-visual-studio.md @@ -0,0 +1,166 @@ +--- +title: Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over an Ethernet network. +ms.assetid: 4D442355-526A-4F39-8341-614BB7A41A3E +keywords: ["network debugging visual studio", "ethernet debugging visual studio", "debugging over ethernet visual studio"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over an Ethernet network. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up Ethernet debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md). + +Debugging over an Ethernet network has the following advantages compared to debugging over other types of cable: + +- The host and target computers can be anywhere on the local network. +- It is easy to debug many target computers from one host computer. +- Network cable is inexpensive and readily available. +- Given any two computers, it is likely that they will both have Ethernet adapters. It is less likely that they will both have serial ports or both have 1394 ports. + +The computer that runs the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. The host computer must be running Windows XP or later, and the target computer must be running Windows 8 or later. + +## Supported network adapters + + +The host computer can use any wired or wireless network adapter, but the target computer must use a network adapter that is supported by Debugging Tools for Windows. For a list of supported network adapters, see [Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md). + +## Configuring the host and target computer + + +1. Connect the network adapter of the target computer to a network hub or switch using standard CAT5 (or higher-level) network cable. Do not use a crossover cable, and do not use a crossover port in your hub or switch. Connect the network adapter of the host computer to a network hub or switch using a standard cable or a wireless connection. +2. Begin configuring your host and target computers as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +3. On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select **Provision computer and choose debugger settings**. +4. For **Connection Type**, choose **Network**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, target name, and bus parameters](images/setupnetvs.png) + + For **Port Number**, accept the default value or fill in a value of your choice. You can choose any number from 49152 through 65535. The port that you choose will be opened for exclusive access by the debugger running on the host computer. Take care to choose a port number that is not used by any other applications that run on the host computer. + + **Note**  The range of port numbers that can be used for network debugging might be limited by your company's network policy. There is no way to tell from the host computer what the limitations are. To determine whether your company's policy limits the range of ports that can be used for network debugging, check with your network administrators. + +   + + For **Key**, we strongly recommend that you use the automatically generated default value. However, you can enter your own key if you prefer. For more information, see [Creating your own key](#creating-your-own-key) later in this topic. For **Host IP**, accept the default value. This is the IP address of your host computer. + + If your target computer has only one network adapter, you can leave **Bus Parameters** empty. If there is more than one network adapter on the target computer, use Device Manager on the target computer to determine the PCI bus, device, and function numbers for the adapter you want to use for debugging. For **Bus Parameters**, enter *b*.*d*.*f* where *b*, *d*, and *f* are the bus number, device number, and function number of the adapter. + +5. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +**Caution**  If your target computer is in a docking station, and you have network debugging enabled for a network adapter that is part of the docking station, do not remove the computer from the docking station. If you need to remove the target computer from the docking station, disable kernel debugging first. To disable kernel debugging on the target computer, open a Command Prompt window as Administrator and enter the command **bcdedit /debug off**. Reboot the target computer. + +  + +**Note**  If you intend to install the Hyper-V role on the target computer, see [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md). + +  + +## Verifying dbgsettings on the Target Computer + + +On the target computer, open a Command Prompt window as Administrator, and enter these commands: + +**bcdedit /dbgsettings** + +**bcdedit /enum** + +``` +... +key RF8...KNE +debugtype NET +hostip 10.125.5.10 +port 50001 +dhcp Yes +... +busparams 0.29.7 +... +``` + +Verify that *debugtype* is NET and *port* is the port number you specified in Visual Studio on the host computer. Also verify that *key* is the key that was automatically generated (or you specified) in Visual Studio. + +If you entered **Bus Parameters** in Visual Studio, verify that *busparams* matches the bus parameters you specified. + +If you do not see the value you entered for **Bus Parameters**, enter this command: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +where *b*, *d*, and *f* are the bus, device, and function numbers of the network adapter on the target computer that you have chosen to use for debugging. + +For example: + +**bcdedit /set "{dbgsettings}" busparams 0.29.7** + +## Starting the Debugging Session + + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the name of the target computer that you previously configured. +4. Click **Attach**. + +## Allowing the debugger through the firewall + + +When you first attempt to establish a network debugging connection, you might be prompted to allow the debugging application (Microsoft Visual Studio) through the firewall. Client versions of Windows display the prompt, but Server versions of Windows do not display the prompt. Respond to the prompt by checking the boxes for all three network types: domain, private, and public. If you do not get the prompt, or if you did not check the boxes when the prompt was available, you must use Control Panel to allow access through the firewall. Open **Control Panel > System and Security**, and click **Allow an app through Windows Firewall**. In the list of applications, use the check boxes to allow Visual Studio through the firewall. Restart Visual Studio. + +## Creating Your Own Key + + +To keep the target computer secure, packets that travel between the host and target computers must be encrypted. We strongly recommend that you use an automatically generated encryption key (provided by the Visual Studio configuration wizard) when you configure the target computer). However, you can choose to create your own key. Network debugging uses a 256-bit key that is specified as four 64-bit values, in base 36, separated by periods. Each 64-bit value is specified by using up to 13 characters. Valid characters are the letters a through z and the digits 0 through 9. Special characters are not allowed. The following list gives examples of valid (although not strong) keys: + +- 1.2.3.4 +- abc.123.def.456 +- dont.use.previous.keys + +## Troubleshooting Tips for Debugging over a Network Cable + + +### Debugging application must be allowed through firewall + +Your debugger (WinDbg or KD) must have access through the firewall. You can use Control Panel to allow access through the firewall. Open **Control Panel > System and Security**, and click **Allow an app through Windows Firewall**. In the list of applications, use the check boxes to allow Visual Studio through the firewall. Restart Visual Studio. + +### Port number must be in range allowed by network policy + +The range of port numbers that can be used for network debugging might be limited by your company's network policy. To determine whether your company's policy limits the range of ports that can be used for network debugging, check with your network administrator. + +Use the following procedure if you need to change the port number. + +1. On the host computer, in Visual Studio, on the **Driver** menu, choose **Test > Configure Computers**. +2. Select the name of your test computer, and click **Next**. +3. Select **Provision computer and choose debugger settings**. Click **Next**. +4. For **Port Number**, enter a number that is in the range allowed by your network administrator. Click **Next**. +5. The reconfiguration process takes a few minutes and automatically reboots the target computer. When the process is complete, click **Next** and **Finish**. + +### Specify busparams if target computer has multiple network adapters + +If your target computer has more than one network adapter, you must specify the bus, device, and function numbers of the network adapter that you intend to use for debugging. To specify the bus parameters, open Device Manager, and locate the network adapter that you want to use for debugging. Open the property page for the network adapter, and make a note of the bus number, device number, and function number. In an elevated Command Prompt Window, enter the following command, where *b*, *d*, and *f* are the bus, device and function numbers in decimal format: + +**bcdedit -set "{dbgsettings}" busparams** *b***.***d***.***f* + +Reboot the target computer. + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20Network%20Cable%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection.md b/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection.md new file mode 100644 index 0000000000..696ecc4324 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-network-debugging-connection.md @@ -0,0 +1,203 @@ +--- +title: Setting Up Kernel-Mode Debugging over a Network Cable Manually +description: Debugging Tools for Windows supports kernel debugging over an Ethernet network. +ms.assetid: B4A79B2E-D4B1-42CA-9121-DEC923C76927 +keywords: ["Network debugging", "Ethernet debugging", "Docking station"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging over a Network Cable Manually + + +Debugging Tools for Windows supports kernel debugging over an Ethernet network. This topic describes how to set up Ethernet debugging manually. + +As an alternative to setting up Ethernet debugging manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. The host computer must be running Windows XP or later, and the target computer must be running Windows 8 or later. + +Debugging over a network has the following advantages compared to debugging over other types of cable. + +- The host and target computers can be anywhere on the local network. +- It is easy to debug many target computers from one host computer. +- Network cable is inexpensive and readily available. +- Given any two computers, it is likely that they will both have Ethernet adapters. It is less likely that they will both have serial ports or both have 1394 ports. + +## Supported Network Adapters + + +The host computer can use any network adapter, but the target computer must use a network adapter that is supported by Debugging Tools for Windows. For a list of supported network adapters, see [Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md). + +## Determining the IP Address of the Host Computer + + +Use one of the following procedures to determine the IP address of the host computer. + +- On the host computer, open a Command Prompt window and enter the following command: + + **ipconfig** + + Make a note of the IPv4 address of the network adapter that you intend to use for debugging. + +- On the target computer, open a Command Prompt window and enter the following command, where *HostName* is the name of the host computer: + + **ping -4** *HostName* + +## Choosing a Port for Network Debugging + + +Choose a port number that will be used for debugging on both the host and target computers. You can choose any number from 49152 through 65535. The port that you choose will be opened for exclusive access by the debugger running on the host computer. Take care to choose a port number that is not used by any other applications that run on the host computer. + +**Note**  The range of port numbers that can be used for network debugging might be limited by your company's network policy. There is no way to tell from the host computer what the limitations are. To determine whether your company's policy limits the range of ports that can be used for network debugging, check with your network administrators. + +  + +If you connect several target computers to a single host computer, each connection must have a unique port number. For example, if you connect 100 target computers to a single host computer, you can assign port 50000 to the first connection, port 50001 to the second connection, port 50002 to the third connection, and so on. + +**Note**  A different host computer could use the same range of ports (50000 through 50099) to connect to another 100 target computers. + +  + +## Setting Up the Target Computer + + +1. Verify that the target computer has a supported network adapter. + +2. Connect the supported adapter to a network hub or switch using standard CAT5 or better network cable. Do not use a crossover cable, and do not use a crossover port in your hub or switch. + +3. In an elevated Command Prompt window, enter the following commands, where *w.x.y.z* is the IP address of the host computer, and *n* is a port number of your choice: + + **bcdedit /debug on** + + **bcdedit /dbgsettings net hostip:***w.x.y.z* **port:***n* + +4. **bcdedit** will display an automatically generated key. Copy the key and store it on a removable storage device like a USB flash drive. You will need the key when you start a debugging session on the host computer. + + **Note**  We strongly recommend that you use an automatically generated key. However, you can create your own key as described later in the Creating Your Own Key section. + +   + +5. If there is more than one network adapter in the target computer, use Device Manager to determine the PCI bus, device, and function numbers for the adapter you want to use for debugging. Then in an elevated Command Prompt window, enter the following command, where *b*, *d*, and *f* are the bus number, device number, and function number of the adapter: + + **bcdedit /set "{dbgsettings}" busparams** *b.d.f* + +6. Reboot the target computer. + +**Caution**  If your target computer is in a docking station, and you have network debugging enabled for a network adapter that is part of the docking station, do not remove the computer from the docking station. If you need to remove the target computer from the docking station, disable kernel debugging first. To disable kernel debugging on the target computer, open a Command Prompt window as Administrator and enter the command **bcdedit /debug off**. Reboot the target computer. + +  + +**Note**  If you intend to install the Hyper-V role on the target computer, see [Setting Up Network Debugging of a Virtual Machine Host](setting-up-network-debugging-of-a-virtual-machine-host.md). + +  + +## Setting Up the Host Computer + + +Connect the network adapter of the host computer to a network hub or switch using standard CAT5 (or higher-level) network cable. Do not use a crossover cable, and do not use a crossover port in your hub or switch. + +## Starting the Debugging Session + + +### Using WinDbg + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **Net** tab. Enter your port number and key. Click **OK**. + +You can also start a session with WinDbg by opening a Command Prompt window and entering the following command, where *n* is your port number and *Key* is the key that was automatically generated by **bcdedit** when you set up the target computer: + +**windbg -k net:port=***n***,key=***Key* + +If you are prompted about allowing WinDbg to access the port through the firewall, allow WinDbg to access the port for all the different network types. + +### Using KD + +On the host computer, open a Command Prompt window. Enter the following command, where *n* is your port number and *Key* is the key that was automatically generated by **bcdedit** when you set up the target computer: + +**kd -k net:port=***n***,key=***Key* + +If you are prompted about allowing KD to access the port through the firewall, allow KD to access the port for all the different network types. + +### Allowing the debugger through the firewall + +When you first attempt to establish a network debugging connection, you might be prompted to allow the debugging application (WinDbg or KD) access through the firewall. Client versions of Windows display the prompt, but Server versions of Windows do not display the prompt. You should respond to the prompt by checking the boxes for all three network types: domain, private, and public. If you do not get the prompt, or if you did not check the boxes when the prompt was available, you must use Control Panel to allow access through the firewall. Open **Control Panel > System and Security**, and click **Allow an app through Windows Firewall**. In the list of applications, locate Windows GUI Symbolic Debugger and Windows Kernel Debugger. Use the check boxes to allow those two applications through the firewall. Restart your debugging application (WinDbg or KD). + +## How the Debugger Obtains an IP Address for the Target Computer + + +The kernel debugging driver on the target computer attempts to use Dynamic Host Configuration Protocol (DHCP) to get a routable IP address for the network adapter that is being used for debugging. If the driver obtains a DHCP-assigned address, then the target computer can be debugged by host computers located anywhere on the network. If the driver fails to obtain a DHCP-assigned address, it uses Automatic Private IP Addressing (APIPA) to obtain a local link IP address. Local link IP addresses are not routable, so a host and target cannot use a local link IP address to communicate through a router. In that case, network debugging will work if you plug the host and target computers into the same network hub or switch. + +## Creating Your Own Key + + +To keep the target computer secure, packets that travel between the host and target computers must be encrypted. We strongly recommend that you use an automatically generated encryption key (provided by **bcdedit** when you configure the target computer). However, you can choose to create your own key. Network debugging uses a 256-bit key that is specified as four 64-bit values, in base 36, separated by periods. Each 64-bit value is specified by using up to 13 characters. Valid characters are the letters a through z and the digits 0 through 9. Special characters are not allowed. The following list gives examples of valid (although not strong) keys: + +- 1.2.3.4 +- abc.123.def.456 +- dont.use.previous.keys + +To specify your own key, open an elevated Command Prompt window on the target computer. Enter the following command, where *w.x.y.z* is the IP address of the host computer, and *n* is your port number, and *Key* is your key: + +**bcdedit /dbgsettings net hostip:***w.x.y.z* **port:***n* **key:***Key* + +Reboot the target computer. + +## Troubleshooting Tips for Debugging over a Network Cable + + +### Debugging application must be allowed through firewall + +Your debugger (WinDbg or KD) must have access through the firewall. You can use Control Panel to allow access through the firewall. Open **Control Panel > System and Security**, and click **Allow an app through Windows Firewall**. In the list of applications, locate Windows GUI Symbolic Debugger and Windows Kernel Debugger. Use the check boxes to allow those two applications through the firewall. Restart your debugging application (WinDbg or KD). + +### Port number must be in range allowed by network policy + +The range of port numbers that can be used for network debugging might be limited by your company's network policy. To determine whether your company's policy limits the range of ports that can be used for network debugging, check with your network administrator. On the target computer, open a Command Prompt window as Administrator and enter the command **bcdedit /dbgsettings**. The output will be similar to this. + +``` +key XXXXXX.XXXXX.XXXXX.XXXXX +debugtype NET +debugport 1 +baudrate 115200 +hostip 10.125.4.86 +port 50085 +``` + +Notice the value of **port**. For example, in the preceding output, the value of **port** is 50085. If the value of **port** lies outside the range allowed by your network administrator, enter the following command, where *w.x.y.z* is the IP address of the host computer, and *n* is a port number in the allowed range + +**bcdedit /dbgsettings net hostip:***w.x.y.z* **port:***n* + +Reboot the target computer. + +**Note**  In the preceding output from **bcdedit**, the debugport and baudrate entries to not apply to debugging over a network cable. Those entries apply to debugging over a serial cable, but they sometimes appear even though the target is configured for debugging over a network cable. + +  + +### Specify busparams if target computer has multiple network adapters + +If your target computer has more than one network adapter, you must specify the bus, device, and function numbers of the network adapter that you intend to use for debugging. To specify the bus parameters, Open Device Manager, and locate the network adapter that you want to use for debugging. Open the property page for the network adapter, and make a note of the bus number, device number, and function number. In an elevated Command Prompt Window, enter the following command, where *b*, *d*, and *f* are the bus, device and function numbers in decimal format: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +Reboot the target computer. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20Network%20Cable%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection-in-visual-studio.md new file mode 100644 index 0000000000..1afe35237b --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection-in-visual-studio.md @@ -0,0 +1,116 @@ +--- +title: Setting Up Kernel-Mode Debugging over a Serial Cable in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a null-modem cable. +ms.assetid: 9E50AA5F-92A2-4360-BB21-A9D4F3E9CA83 +--- + +# Setting Up Kernel-Mode Debugging over a Serial Cable in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a null-modem cable. Null-modem cables are serial cables that have been configured to send data between two serial ports. They are available at most computer stores. Do not confuse null-modem cables with standard serial cables. Standard serial cables do not connect serial ports to each other. For information about how null-modem cables are wired, see [Null-Modem Cable Wiring](#null-modem-cable-wiring). + +To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up serial debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging over a Serial Cable Manually](setting-up-a-null-modem-cable-connection.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. + +## Configuring the host and target computers + + +1. Begin configuring your host and target computer as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +2. On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select **Provision computer and choose debugger settings**. +3. For **Connection Type**, choose **Serial**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, target name, and bus parameters](images/setupserialvs.png) + + For **Baud Rate**, accept the default value or enter the baud rate you want to use. For **Port**, enter the name of the COM port that you want to use for debugging on the host computer. For **Target Port**, enter the name of the COM port that you want to use for debugging on the target computer. + +4. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +## Starting the Debugging Session + + +1. Connect the null-modem cable to the COM ports that you have chosen for debugging on the host and target computers. +2. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +3. For **Transport**, choose **Windows Kernel Mode Debugger**. +4. For **Qualifier**, select the name of the target computer that you previously configured. +5. Click **Attach**. + +## Troubleshooting Tips for Debugging over a Serial Cable + + +### Specify correct COM ports and baud rate + +Determine the numbers of the COM ports you are using for debugging on the host and target computers. For example, suppose you have your null-modem cable connected to COM1 on the host computer and COM2 on the target computer. Also suppose you have chosen a baud rate of 115200. + +1. On the host computer, in Visual Studio, on the **Driver** menu, choose **Test > Configure Computers**. +2. Select the name of your test computer, and click **Next**. +3. Select **Provision computer and choose debugger settings**. Click **Next**. +4. If you are using COM1 on the host computer, for **Port**, enter com1. If you are using COM2 on the target computer, for **Target Port**, enter com2. +5. If you have chosen to use a baud rate of 115200, for **Baud Rate**, enter 115200. + +You can double check the COM port and baud rate settings on the target computer by opening a Command Prompt window as Administrator, and entering **bcdedit /dbgsettings**. If you are using COM2 on the target computer and a baud rate of 115200, the output of **bcdedit** should show `debugport 2` and `baudrate 115200`. + +## Null Modem Cable Wiring + + +The following tables show how null-modem cables are wired. + +### 9-pin connector + +| Connector 1 | Connector 2 | Signals | +|-------------|-------------|----------------| +| 2 | 3 | Tx - Rx | +| 3 | 2 | Rx - Tx | +| 7 | 8 | RTS - CTS | +| 8 | 7 | CTS - RTS | +| 4 | 1+6 | DTR - (CD+DSR) | +| 1+6 | 4 | (CD+DSR) - DTR | +| 5 | 5 | Signal ground | + +  + +### 25-pin connector + +| Connector 1 | Connector 2 | Signals | +|-------------|-------------|---------------| +| 2 | 3 | Tx - Rx | +| 3 | 2 | Rx - Tx | +| 4 | 5 | RTS - CTS | +| 5 | 4 | CTS - RTS | +| 6 | 20 | DSR - DTR | +| 20 | 6 | DTR - DSR | +| 7 | 7 | Signal ground | + +  + +### Signal Abbreviations + +| Abbreviation | Signal | +|--------------|---------------------| +| Tx | Transmit data | +| Rx | Receive data | +| RTS | Request to send | +| CTS | Clear to send | +| DTR | Data terminal ready | +| DSR | Data set ready | +| CD | Carrier detect | + +  + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20Serial%20Cable%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection.md b/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection.md new file mode 100644 index 0000000000..1cf5f7488e --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-null-modem-cable-connection.md @@ -0,0 +1,164 @@ +--- +title: Setting Up Kernel-Mode Debugging over a Serial Cable Manually +description: Debugging Tools for Windows supports kernel debugging over a null-modem cable. +ms.assetid: f7311928-bab1-4692-8dd6-5e464dd7127a +keywords: ["setup, making a debug cable connection", "null-modem cable", "debug cable", "cable connection", "cable connection, debug (null-modem) cable)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging over a Serial Cable Manually + + +Debugging Tools for Windows supports kernel debugging over a null-modem cable. Null-modem cables are serial cables that have been configured to send data between two serial ports. They are available at most computer stores. Do not confuse null-modem cables with standard serial cables. Standard serial cables do not connect serial ports to each other. For information about how null-modem cables are wired, see [Null-Modem Cable Wiring](#null-modem-cable-wiring). + +This topic describes how to set up serial debugging manually. As an alternative to setting up serial debugging manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging over a Serial Cable in Visual Studio](setting-up-a-null-modem-cable-connection-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. + +## Setting Up the Target Computer + + +1. On the target computer, open a Command Prompt window as Administrator, and enter the following commands, where *n* is the number of the COM port used for debugging on the target computer, and *rate* is the baud rate used for debugging: + + **bcdedit /debug on** + + **bcdedit /dbgsettings serial debugport:***n* **baudrate:***rate* + + **Note**  The baud rate must be the same on the host computer and target computer. The recommended rate is 115200. + +   + +2. Reboot the target computer. + +## Starting the Debugging Session + + +Connect the null-modem cable to the COM ports that you have chosen for debugging on the host and target computers. + +### Using WinDbg + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **COM** tab. In the **Baud rate** box, enter the rate you have chosen for debugging. In the **Port** box, enter COM*n* where *n* is the COM port number you have chosen for debugging on the host computer. Click **OK**. + +You can also start a session with WinDbg by entering the following command in a Command Prompt window; *n* is the number of the COM port used for debugging on the host computer, and *rate* is the baud rate used for debugging: + +**windbg -k com:port=COM***n***,baud=***rate* + +### Using KD + +On the host computer, open a Command Prompt window, and enter the following command, where *n* is the number of the COM port used for debugging on the host computer, and *rate* is the baud rate used for debugging: + +**kd -k com:port=COM***n***,baud=***rate* + +## Using Environment Variables + + +On the host computer, you can use environment variables to specify the COM port and the baud rate. Then you do not have to specify the port and baud rate each time you start a debugging session. To use environment variables to specify the COM port and baud rate, open a Command Prompt window and enter the following commands, where *n* is the number of the COM port used for debugging on the host computer, and *rate* is the baud rate used for debugging: + +- **set \_NT\_DEBUG\_PORT=COM***n* +- **set \_NT\_DEBUG\_BAUD\_RATE=***rate* + +To start a debugging session, open a Command Prompt window, and enter one of the following commands: + +- **kd** +- **windbg** + +## Troubleshooting Tips for Debugging over a Serial Cable + + +### Specify correct COM port on both host and target + +Determine the numbers of the COM ports you are using for debugging on the host and target computers. For example, suppose you have your null-modem cable connected to COM1 on the host computer and COM2 on the target computer. + +On the target computer, open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. If you are using COM2 on the target computer, the output of **bcdedit** should show `debugport 2`. + +On the host computer, specify the correct COM port when you start the debugger or when you set environment variables. If you are using COM1 on the host computer, use one of the following methods to specify the COM port. + +- In WinDbg, in the Kernel Debugging dialog box, enter COM1 in the **Port** box. +- **windbg -k com:port=COM1, ...** +- **kd -k com:port=COM1, ...** +- **set \_NT\_DEBUG\_PORT=COM1** + +### Baud rate must be the same on host and target + +The baud rate used for debugging over a serial cable must be set to the same value on the host and target computers. For example, suppose you have chosen a baud rate of 115200. + +On the target computer, open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. The output of **bcdedit** should show `baudrate 115200`. + +On the host computer, specify the correct baud rate when you start the debugger or when you set environment variables. Use one of the following methods to specify a baud rate of 115200. + +- In WinDbg, in the Kernel Debugging dialog box, enter 115200 in the **Baud rate** box. +- **windbg -k ..., baud=115200** +- **kd -k ..., baud=115200** +- **set \_NT\_DEBUG\_BAUD\_RATE=115200** + +## Null Modem Cable Wiring + + +The following tables show how null-modem cables are wired. + +### 9-pin connector + +| Connector 1 | Connector 2 | Signals | +|-------------|-------------|----------------| +| 2 | 3 | Tx - Rx | +| 3 | 2 | Rx - Tx | +| 7 | 8 | RTS - CTS | +| 8 | 7 | CTS - RTS | +| 4 | 1+6 | DTR - (CD+DSR) | +| 1+6 | 4 | (CD+DSR) - DTR | +| 5 | 5 | Signal ground | + +  + +### 25-pin connector + +| Connector 1 | Connector 2 | Signals | +|-------------|-------------|---------------| +| 2 | 3 | Tx - Rx | +| 3 | 2 | Rx - Tx | +| 4 | 5 | RTS - CTS | +| 5 | 4 | CTS - RTS | +| 6 | 20 | DSR - DTR | +| 20 | 6 | DTR - DSR | +| 7 | 7 | Signal ground | + +  + +### Signal Abbreviations + +| Abbreviation | Signal | +|--------------|---------------------| +| Tx | Transmit data | +| Rx | Receive data | +| RTS | Request to send | +| CTS | Clear to send | +| DTR | Data terminal ready | +| DSR | Data set ready | +| CD | Carrier detect | + +  + +## Additional Information + + +For complete documentation of the **bcdedit** command, see Boot Options for Driver Testing and Debugging in the Windows Driver Kit (WDK) documentation. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20Serial%20Cable%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-cable-connection-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-cable-connection-in-visual-studio.md new file mode 100644 index 0000000000..ed468d423f --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-cable-connection-in-visual-studio.md @@ -0,0 +1,145 @@ +--- +title: Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a USB 2.0 cable. +ms.assetid: 3BEE43E2-32E5-4E7A-BA71-9ADB224578B1 +--- + +# Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a USB 2.0 cable. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up USB 2.0 debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually](setting-up-a-usb-2-0-debug-cable-connection.md). + +The computer that runs the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. + +Debugging over a USB 2.0 connection requires the following hardware: + +- A Universal Serial Bus (USB) 2.0 debug cable. This cable is not a standard USB 2.0 cable, because it has an extra hardware component that makes it compatible with the USB2 Debug Device Functional Specification. You can find these cables by doing an Internet search for "USB 2.0 debug cable". + +- On the host computer, an EHCI (USB 2.0) host controller + +- On the target computer, an EHCI (USB 2.0) host controller that supports debugging + +## Identifying a Debug Port on the Target Computer + + +1. On the target computer, launch the UsbView tool. The UsbView tool is included in Debugging Tools for Windows. +2. In UsbView, locate all of the host controllers that are compatible with the EHCI specification. For example, you could look for controllers that are listed as Enhanced. +3. In UsbView, expand the nodes of the EHCI host controllers. Look for an indication that a host controller supports debugging, and look for the number of the debug port. For example, UsbView displays this output for an EHCI host controller that supports debugging on port 1. + + ``` + Xxx xxx xxx USB2 Enhanced Host Controller - 293A + ... + Debug Port Number: 1 + Bus.Device.Function (in decimal): 0.29.7 + ``` + + **Note**  Many EHCI host controllers support debugging on port 1, but some EHCI host controllers support debugging on port 2. + +   + +4. Make a note of the bus, device, and function numbers for the EHCI controller that you intend to use for debugging. UsbView displays these number. In the preceding example, the bus number is 0, the device number is 29, and the function number is 7. + +5. After you have identified the EHCI controller and the port number that supports debugging, the next step is to locate the physical USB connector that is associated with the correct port number. To find the physical connector, plug any USB 2.0 device into any USB connector on the target computer. Refresh UsbView to see where your device is located. If UsbView shows your device connected to the EHCI host controller and port that you identified as the debug port, then you have found a physical USB connector that you can use for debugging. It could be that there is no external physical USB connector that is associated with a debug port on an EHCI controller. In that case, you can look for a physical USB connector inside the computer. Perform the same steps to determine whether the internal USB connector is suitable for kernel debugging. If you cannot find a physical USB connector (either external or internal) that is associated with a debug port, then you cannot use the computer as a target for debugging over a USB 2.0 cable. + + **Note**  See [this remark](setting-up-a-usb-2-0-debug-cable-connection.md#what-if-usbview-shows-a-debug-capable-port) for an exception. + +   + +## Connecting the USB debug cable + + +1. Verify that the host computer is not configured to be the target of USB debugging. (If necessary, open a Command Prompt window as Administrator, enter **bcdedit /debug off**, and reboot.) +2. On the host computer, use UsbView to find the EHCI host controllers and ports that support debugging. If possible, plug one end of the USB 2.0 debug cable into an EHCI port (on the host computer) that does not support debugging. Otherwise, plug the cable into any EHCI port on the host computer. +3. Plug the other end of the USB 2.0 debug cable into the connector that you identified previously on the target computer. + +## Configuring the host and target computers + + +1. Begin configuring your host and target computers as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +2. On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select **Provision computer and choose debugger settings**. +3. For **Connection Type**, choose **USB**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, target name, and bus parameters](images/setupusb2vs.png) + + For **Target Name**, enter a string to represent the target computer. This string does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions: + + - The maximum length of the string is 24 characters. + - The only characters in the string are the hyphen (-), the underscore(\_), the digits 0 through 9, and the letters A through Z (upper or lower case). + + If you have more than one USB host controller on the target computer, enter a **Bus Parameters** value of *b*.*d*.*f*, where *b*, *d*, and *f* are the bus, device, and function numbers for the USB host controller that you intend to use for debugging on the target computer. The bus, device, and function numbers must be in decimal format (example: 0.29.7). + +4. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +## Verifying dbgsettings on the Target Computer + + +On the target computer, open a Command Prompt window as Administrator, and enter these commands: + +**bcdedit /dbgsettings** + +**bcdedit /enum** + +``` +... +targetname MyUsbTarget +debugtype USB +debugport 1 +baudrate 115200 +... +busparams 0.29.7 +... +``` + +Verify that *debugtype* is USB and *targetname* is the name you specified in Visual Studio on the host computer. You can ignore the values of *debugport* and *baudrate*; they do not apply to debugging over USB. + +If you entered **Bus Parameters** in Visual Studio, verify that *busparams* matches the bus parameters you specified. + +If you do not see the value you entered for **Bus Parameters**, enter this command: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +where *b*, *d*, and *f* are the bus, device, and function numbers of the EHCI controller on the target computer that you have chosen to use for debugging. + +Example: + +**bcdedit /set "{dbgsettings}" busparams 0.29.7** + +Reboot the target computer. + +## Starting a Debugging Session for the First Time + + +1. Connect a USB 2.0 debug cable to the USB 2.0 ports that you have chosen for debugging on the host and target computers. +2. On the host computer, open Visual Studio as Administrator. +3. On the **Tools** menu, choose **Attach to Process**. +4. For **Transport**, choose **Windows Kernel Mode Debugger**. +5. For **Qualifier**, select the name of the target computer that you previously configured. +6. Click **Attach**. + +At this point, the USB debug driver gets installed on the host computer. This is why it is important to run Visual Studio as Administrator. After the USB debug driver is installed, you do not need to run as Administrator for subsequent debugging sessions. + +## Starting a Debugging Session + + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the target name that you entered during configuration. +4. Click **Attach**. + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20%20USB%202.0%20Cable%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-debug-cable-connection.md b/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-debug-cable-connection.md new file mode 100644 index 0000000000..4d3400d26d --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-usb-2-0-debug-cable-connection.md @@ -0,0 +1,168 @@ +--- +title: Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually +description: Debugging Tools for Windows supports kernel debugging over a USB 2.0 cable. This topic describes how to set up USB 2.0 debugging manually. +ms.assetid: 8dd0703a-ddcd-461f-b164-1c079a93bb3a +keywords: ["setup, making a USB 2.0 cable connection", "cable connection, USB 2.0 debug cable", "USB 2.0 debugging connection", "USB 2.0 debugging connection, setting up the hardware", "USB 2.0 debugging connection, software requirements"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually + + +Debugging Tools for Windows supports kernel debugging over a USB 2.0 cable. This topic describes how to set up USB 2.0 debugging manually. + +As an alternative to setting up USB 2.0 debugging manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio](setting-up-a-usb-2-0-cable-connection-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. + +Debugging over a USB 2.0 cable requires the following hardware: + +- A USB 2.0 debug cable. This cable is not a standard USB 2.0 cable because it has an extra hardware component that makes it compatible with the USB2 Debug Device Functional Specification. You can find these cables with an Internet search for the term *USB 2.0 debug cable*. + +- On the host computer, an EHCI (USB 2.0) host controller + +- On the target computer, an EHCI (USB 2.0) host controller that supports debugging + +## Setting Up the Target Computer + + +1. On the target computer, launch the UsbView tool. The UsbView tool is included in Debugging Tools for Windows. +2. In UsbView, locate all of the host controllers that are compatible with the EHCI specification. For example, you could look for controllers that are listed as Enhanced. +3. In UsbView, expand the nodes of the EHCI host controllers. Look for an indication that a host controller supports debugging, and look for the number of the debug port. For example, UsbView displays this output for an EHCI host controller that supports debugging on port 1. + + ``` + Xxx xxx xxx USB2 Enhanced Host Controller - 293A + ... + Debug Port Number: 1 + Bus.Device.Function (in decimal): 0.29.7 + ``` + + **Note**  Many EHCI host controllers support debugging on port 1, but some EHCI host controllers support debugging on port 2. + +   + +4. Make a note of the bus, device, and function numbers for the EHCI controller that you intend to use for debugging. UsbView displays these number. In the preceding example, the bus number is 0, the device number is 29, and the function number is 7. + +5. After you have identified the EHCI controller and the port number that supports debugging, the next step is to locate the physical USB connector that is associated with the correct port number. To find the physical connector, plug any USB 2.0 device into any USB connector on the target computer. Refresh UsbView to see where your device is located. If UsbView shows your device connected to the EHCI host controller and port that you identified as the debug port, then you have found a physical USB connector that you can use for debugging. It could be that there is no external physical USB connector that is associated with a debug port on an EHCI controller. In that case, you can look for a physical USB connector inside the computer. Perform the same steps to determine whether the internal USB connector is suitable for kernel debugging. If you cannot find a physical USB connector (either external or internal) that is associated with a debug port, then you cannot use the computer as a target for debugging over a USB 2.0 cable. + + **Note**  See [this remark](#what-if-usbview-shows-a-debug-capable-port) for an exception. + +   + +6. On the target computer, open a Command Prompt window as Administrator, and enter these commands: + + - **bcdedit /debug on** + - **bcdedit /dbgsettings usb targetname:***TargetName* + + where *TargetName* is a name that you create for the target computer. Note that *TargetName* does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions: + + - The maximum length of the string is 24 characters. + - The only characters in the string are the hyphen (-), the underscore(\_), the digits 0 through 9, and the letters A through Z (upper or lower case). + +7. If there is more than one USB host controller on the target computer, enter this command: + + Windows 7 or later + **bcdedit /set "{dbgsettings}" busparams** *b.d.f* + + where *b*, *d*, and *f* are the bus, device, and function numbers for the host controller. The bus, device, and function numbers must be in decimal format (for example, **busparams 0.29.7**). + + Windows Vista + **bcdedit /set "{current}" loadoptions busparams=***f.d.f* + + where *b*, *d*, and *f* are the bus, device, and function numbers for the host controller. The bus, device, and function numbers must be in hexadecimal format (for example, **busparams=0.1D.7**). + +8. Reboot the target computer. + +## Setting Up the Host Computer + + +1. Verify that the host computer is not configured to be the target of USB debugging. (If necessary, open a Command Prompt window as Administrator, enter **bcdedit /debug off**, and reboot.) +2. On the host computer, use UsbView to find the EHCI host controllers and ports that support debugging. If possible, plug one end of the USB 2.0 debug cable into an EHCI port (on the host computer) that does not support debugging. Otherwise, plug the cable into any EHCI port on the host computer. +3. Plug the other end of the USB 2.0 debug cable into the connector that you identified previously on the target computer. + +## Starting a Debugging Session for the First Time + + +1. Determine the bitness (32-bit or 64-bit) of Windows running on the host computer. +2. On the host computer, open a version of WinDbg (as Administrator) that matches the bitness of Windows running on the host computer. For example, if the host computer is running a 64-bit version of Windows, open the 64-bit version of WinDbg as Administrator. +3. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **USB** tab. Enter the target name that you created when you set up the target computer. Click **OK**. + +At this point, the USB debug driver gets installed on the host computer. This is why it is important to match the bitness of WinDbg to the bitness of Windows. After the USB debug driver is installed, you can use either the 32-bit or 64-bit version of WinDbg for subsequent debugging sessions. + +**Note**  The USB 2.0 debug cable is actually two cables with a dongle in the middle. The direction of the dongle is important; one side powers the device, and the other side does not. If USB debugging doesn’t work, try swapping the direction of the dongle. That is, unplug both cables from the dongle, and swap the sides that the cables are connected to. + +  + +## Starting a Debugging Session + + +### Using WinDbg + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **USB** tab. Enter the target name that you created when you set up the target computer. Click **OK**. + +You can also start a session with WinDbg by entering the following command in a Command Prompt window, where *TargetName* is the target name you created when you set up the target computer: + +**windbg /k usb:targetname=***TargetName* + +### Using KD + +On the host computer, open a Command Prompt window and enter the following command, where *TargetName* is the target name you created when you set up the target computer: + +**kd /k usb:targetname=***TargetName* + +## What if USBView shows a debug-capable port, but does not show the port mapped to any physical connector? + + +On some computers, USBView shows a debug-capable port, but does not show the port mapped to any physical USB connector. For example, USBView might show port 2 as the debug port number for an eHCI controller. + +``` +... USB Enhanced Host Controller ... +... +Debug Port Number: 2 +Bus.Device.Function (in decimal): 0.29.0 +``` + +Also, when you use USBView to look at the individual port, it is listed as debug-capable. + +``` +[Port 2] +Is Port User Connectiable: Yes +Is Port Debug Capable: Yes +... +Protocols Supported + USB 1.1 yes + USB 2.0 yes + USB 3.0 no +``` + +But when you plug in a USB 2.0 device (like a flash drive) to all the USB connectors on the computer, USBView never show your device connected to the debug-capable port (port 2 in this example). USBView might show the external connector mapped to a port of an xHCI controller when in fact the external connector is mapped to the debug-capable port of the eHCI controller. + +![screenshot of xhci and ehci in usbview](images/usbview01.png) + +In a case like this, you might still be able to establish kernel-mode debugging over a USB 2.0 cable. In the example given here, you would plug your USB 2.0 debug cable into the connector that shows as being mapped to Port 2 of the xHCI controller. Then you would set your bus parameters to the bus, device, and function numbers of the eHCI controller (in this example, 0.29.0). + +**bcdedit /set "{dbgsettings}" busparams 0.29.0** + +### Additional Support + +For troubleshooting tips and detailed instructions on setting up kernel debugging over USB, see [Setting Up Kernel Debugging with USB 2.0](http://go.microsoft.com/fwlink/p?linkid=389435) in MSDN Blogs. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20USB%202.0%20Cable%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-cable-connection-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-cable-connection-in-visual-studio.md new file mode 100644 index 0000000000..0f8081cacc --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-cable-connection-in-visual-studio.md @@ -0,0 +1,153 @@ +--- +title: Setting Up Kernel-Mode Debugging over a USB 3.0 Cable in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a USB 3.0 cable. +ms.assetid: F8DD0475-13CE-464A-A491-AEFA962A96DB +--- + +# Setting Up Kernel-Mode Debugging over a USB 3.0 Cable in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging over a USB 3.0 cable. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up USB 3.0 debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually](setting-up-a-usb-3-0-debug-cable-connection.md). + +The computer that runs the debugger is called the *host computer*, and the computer that is being debugged is called the *target computer*. + +Debugging over a USB 3.0 connection requires the following hardware: + +- A USB 3.0 debug cable. This is an A-A crossover cable that has only the USB 3.0 lines and no Vbus. + +- On the host computer, an xHCI (USB 3.0) host controller + +- On the target computer, an xHCI (USB 3.0) host controller that supports debugging + +## Identifying a Debug Port on the Target Computer + + +1. On the target computer, launch the UsbView tool. The UsbView tool is included in Debugging Tools for Windows. +2. In UsbView, locate all of the xHCI host controllers. +3. In UsbView, expand the nodes of the xHCI host controllers. Look for an indication that a port on the host controller supports debugging. + + ``` + [Port1] + + Is Port User Connectable: yes + Is Port Debug Capable: yes + Companion Port Number: 3 + Companion Hub Symbolic Link Name: USB#ROOT_HUB30#5&32bab638&0&0#{...} + Protocols Supported: + USB 1.1: no + USB 2.0: no + USB 3.0: yes + ``` + +4. Make a note of the bus, device, and function numbers for the xHCI controller that you intend to use for debugging. UsbView displays these number. In the following example, the bus number is 48, the device number is 0, and the function number is 0. + + ``` + USB xHCI Compliant Host Controller + ... + DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020 + ... + Bus.Device.Function (in decimal): 48.0.0 + ``` + +5. After you have identified an xHCI controller that supports debugging, the next step is to locate the physical USB connector that is associated with a port on the xHCI controller. To find the physical connector, plug any USB 3.0 device into any USB connector on the target computer. Refresh UsbView to see where your device is located. If UsbView shows your device connected to the xHCI host controller, then you have found a physical USB connector that you can use for USB 3.0 debugging. + +## Configuring the host and target computers + + +1. Begin configuring your host and target computers as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +2. On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select **Provision computer and choose debugger settings**. +3. For **Connection Type**, choose **USB**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, target name, and bus parameters](images/setupusbvs.png) + + For **Target Name**, enter a string to represent the target computer. This string does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions: + + - The maximum length of the string is 24 characters. + - The only characters in the string are the hyphen (-), the underscore(\_), the digits 0 through 9, and the letters A through Z (upper or lower case). + + If you have more than one USB host controller on the target computer, enter a **Bus Parameters** value of *b*.*d*.*f*, where *b*, *d*, and *f* are the bus, device, and function numbers for the USB host controller that you intend to use for debugging on the target computer. The bus, device, and function numbers must be in decimal format (example: 48.0.0). + +4. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +## Verifying dbgsettings on the Target Computer + + +On the target computer, open a Command Prompt window as Administrator, and enter these commands: + +**bcdedit /dbgsettings** + +**bcdedit /enum** + +``` +... +targetname MyUsbTarget +debugtype USB +debugport 1 +baudrate 115200 +... +busparams 48.0.0 +``` + +Verify that *debugtype* is USB and *targetname* is the name you specified in Visual Studio on the host comptuer. You can ignore the values of *debugport* and *baudrate*; they do not apply to debugging over USB. + +If you entered **Bus Parameters** in Visual Studio, verify that *busparams* matches the bus parameters you specified. + +If you do not see the value you entered for **Bus Parameters**, enter this command: + +**bcdedit /set "{dbgsettings}" busparams** *b***.***d***.***f* + +where *b*, *d*, and *f* are the bus, device, and function numbers of the xHCI controller on the target computer that you have chosen to use for debugging. + +Example: + +**bcdedit /set "{dbgsettings}" busparams 48.0.0** + +Reboot the target computer. + +## Starting a Debugging Session for the First Time + + +1. Connect a Universal Serial Bus (USB) 3.0 debug cable to the USB 3.0 ports that you have chosen for debugging on the host and target computers. +2. On the host computer, open Visual Studio as Administrator. +3. On the **Tools** menu, choose **Attach to Process**. +4. For **Transport**, choose **Windows Kernel Mode Debugger**. +5. For **Qualifier**, select the name of the target computer that you previously configured. +6. Click **Attach**. + +At this point, the USB debug driver gets installed on the host computer. This is why it is important to run Visual Studio as Administrator. After the USB debug driver is installed, you do not need to run as Administrator for subsequent debugging sessions. + +## Starting a Debugging Session + + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the name of the target computer that you previously configured. +4. Click **Attach**. + +## Troubleshooting tips for debugging over USB 3.0 + + +In some cases, power transitions can interfere with debugging over USB 3.0. If you have this problem, disable selective suspend for the xHCI host controller (and its root hub) that you are using for debugging. + +1. In Device Manager, navigate to the node for the xHCI host controller. Right click the node, and choose **Properties**. If there is a **Power Management** tab, open the tab, and clear the **Allow the computer to turn off this device to save power** check box. +2. In Device Manager, navigate to the node for the root hub of the xHCI host controller. Right click the node, and choose **Properties**. If there is a **Power Management** tab, open the tab, and clear the **Allow the computer to turn off this device to save power** check box. + +When you have finished using the xHCI host controller for debugging, enable selective suspend for the xHCI host controller. + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20USB%203.0%20Cable%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-debug-cable-connection.md b/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-debug-cable-connection.md new file mode 100644 index 0000000000..69a9f4a40c --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-a-usb-3-0-debug-cable-connection.md @@ -0,0 +1,129 @@ +--- +title: Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually +description: Debugging Tools for Windows supports kernel debugging over a USB 3.0 cable. This topic describes how to set up USB 3.0 debugging manually. +ms.assetid: 9A9F5DA0-B98A-4C19-A723-67D06B2409B5 +--- + +# Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually + + +Debugging Tools for Windows supports kernel debugging over a USB 3.0 cable. This topic describes how to set up USB 3.0 debugging manually. + +As an alternative to setting up USB 3.0 debugging manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable in Visual Studio](setting-up-a-usb-3-0-cable-connection-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. + +Debugging over a USB 3.0 cable requires the following hardware: + +- A USB 3.0 debug cable. This is an A-A crossover cable that has only the USB 3.0 lines and no Vbus. + +- On the host computer, an xHCI (USB 3.0) host controller + +- On the target computer, an xHCI (USB 3.0) host controller that supports debugging + +## Setting Up the Target Computer + + +1. On the target computer, launch the UsbView tool. The UsbView tool is included in Debugging Tools for Windows. +2. In UsbView, locate all of the xHCI host controllers. +3. In UsbView, expand the nodes of the xHCI host controllers. Look for an indication that a port on the host controller supports debugging. + + ``` + [Port1] + + Is Port User Connectable: yes + Is Port Debug Capable: yes + Companion Port Number: 3 + Companion Hub Symbolic Link Name: USB#ROOT_HUB30#5&32bab638&0&0#{...} + Protocols Supported: + USB 1.1: no + USB 2.0: no + USB 3.0: yes + ``` + +4. Make a note of the bus, device, and function numbers for the xHCI controller that you intend to use for debugging. UsbView displays these number. In the following example, the bus number is 48, the device number is 0, and the function number is 0. + + ``` + USB xHCI Compliant Host Controller + ... + DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020 + ... + Bus.Device.Function (in decimal): 48.0.0 + ``` + +5. After you have identified an xHCI controller that supports debugging, the next step is to locate the physical USB connector that is associated with a port on the xHCI controller. To find the physical connector, plug any USB 3.0 device into any USB connector on the target computer. Refresh UsbView to see where your device is located. If UsbView shows your device connected to your chosen xHCI host controller, then you have found a physical USB connector that you can use for USB 3.0 debugging. + +6. On the target computer, open a Command Prompt window as Administrator, and enter these commands: + + - **bcdedit /debug on** + - **bcdedit /dbgsettings usb targetname:***TargetName* + + where *TargetName* is a name that you create for the target computer. Note that *TargetName* does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions: + + - The maximum length of the string is 24 characters. + - The only characters in the string are the hyphen (-), the underscore(\_), the digits 0 through 9, and the letters A through Z (upper or lower case). + +7. If you have more than one USB host controller on the target computer, enter this command: + + **bcdedit /set "{dbgsettings}" busparams** *b.d.f* + + where *b*, *d*, and *f* are the bus, device, and function numbers for the USB host controller that you intend to use for debugging. The bus, device, and function numbers must be in decimal format. + + Example: + + **bcdedit /set "{dbgsettings}" busparams 48.0.0** + +8. Reboot the target computer. + +## Starting a Debugging Session for the First Time + + +1. Connect a Universal Serial Bus (USB) 3.0 debug cable to the USB 3.0 ports that you have chosen for debugging on the host and target computers. +2. Determine the bitness (32-bit or 64-bit) of Windows running on the host computer. +3. On the host computer, open a version of WinDbg (as Administrator) that matches the bitness of Windows running on the host computer. For example, if the host computer is running a 64-bit version of Windows, open the 64-bit version of WinDbg as Administrator. +4. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **USB** tab. Enter the target name that you created when you set up the target computer. Click **OK**. + +At this point, the USB debug driver gets installed on the host computer. This is why it is important to match the bitness of WinDbg to the bitness of Windows. After the USB debug driver is installed, you can use either the 32-bit or 64-bit version of WinDbg for subsequent debugging sessions. + +## Starting a Debugging Session + + +### Using WinDbg + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **USB** tab. Enter the target name that you created when you set up the target computer. Click **OK**. + +You can also start a session with WinDbg by entering the following command in a Command Prompt window, where *TargetName* is the target name you created when you set up the target computer: + +**windbg /k usb:targetname=***TargetName* + +### Using KD + +On the host computer, open a Command Prompt window and enter the following command, where *TargetName* is the target name you created when you set up the target computer: + +**kd /k usb:targetname=***TargetName* + +## Troubleshooting tips for debugging over USB 3.0 + + +In some cases, power transitions can interfere with debugging over USB 3.0. If you have this problem, disable selective suspend for the xHCI host controller (and its root hub) that you are using for debugging. + +1. In Device Manager, navigate to the node for the xHCI host controller. Right click the node, and choose **Properties**. If there is a **Power Management** tab, open the tab, and clear the **Allow the computer to turn off this device to save power** check box. +2. In Device Manager, navigate to the node for the root hub of the xHCI host controller. Right click the node, and choose **Properties**. If there is a **Power Management** tab, open the tab, and clear the **Allow the computer to turn off this device to save power** check box. + +When you have finished using the xHCI host controller for debugging, enable selective suspend for the xHCI host controller. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20over%20a%20USB%203.0%20Cable%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-an-aml-debugging-session.md b/windows-driver-docs-pr/debugger/setting-up-an-aml-debugging-session.md new file mode 100644 index 0000000000..e41fffb473 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-an-aml-debugging-session.md @@ -0,0 +1,31 @@ +--- +title: Setting Up an AML Debugging Session +description: Setting Up an AML Debugging Session +ms.assetid: 04a44b92-215c-4735-9724-2b9f173f76a2 +keywords: ["AMLI Debugger, setup", "checked build (debug build), of acpi.sys", "acpi.sys"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up an AML Debugging Session + + +## + + +The AMLI Debugger code is contained in Acpi.sys. In order to fully perform AML debugging, this driver must be installed on your target computer. + +To activate breaking into debugger on free builds, use the **!amli set dbgbrkon** command, that is part of the AMLI Debugger extensions. For more information, see [**!amli set**](-amli-set.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20an%20AML%20Debugging%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-exclusion-lists.md b/windows-driver-docs-pr/debugger/setting-up-exclusion-lists.md new file mode 100644 index 0000000000..ae7d40f8aa --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-exclusion-lists.md @@ -0,0 +1,57 @@ +--- +title: Setting Up Exclusion Lists +description: Setting Up Exclusion Lists +ms.assetid: 0b50e8a6-f68c-43e5-b8d5-4b2c40252d38 +keywords: ["SymProxy, exclusion lists"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Exclusion Lists + + +In some environments, you may find yourself debugging systems that have a large quantity of modules loaded for which you cannot obtain symbols. This is often the case if you have code that is called by a third-party vendor. This can result in a lot of failed attempts to find symbols, which is time-consuming and clogs up network resources. To alleviate this situation, you can use an *exclusion list* to specify symbols that should be excluded from the search. This feature exists in the client debugger, but you can also configure the SymProxy filter to use its own the exclusion list and prevent such network activity where it is most likely to take up resources. + +The exclusion list is made up of the names of the files for which you want to prevent processing. The file names can contain wildcards. For example: + +``` +dbghelp.pdb +symsrv.* +mso* +``` + +The list can be implemented in two ways. The first is in an .ini file, %WINDIR%\\system32\\inetsrv\\Symsrv.ini. A section called "exclusions" should contain the list: + +``` +[exclusions] +dbghelp.pdb +symsrv.* +mso* +``` + +Alternatively, you can store the exclusions in the registry. Create a key named + +``` +HKLM\ Software\Microsoft\Symbol Server\Exclusions +``` + +Store the file name list as string values (REG\_SZ) within this key. The name of the string value acts as the file name to exclude. The contents of the string value can be used as a comment describing why the file is being excluded. + +SymProxy reads from the exclusion list every half-hour so that you do not need to restart the Web service to see changes take effect. Add files to the list in the registry or .ini file and wait a short period for the exclusions to be used. + +**Note**   SymProxy does not support the use of both Symsrv.ini and the registry. If the .ini file exists, it is used. Otherwise, the registry is checked. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Exclusion%20Lists%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-visual-studio.md new file mode 100644 index 0000000000..de3d0dba39 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-visual-studio.md @@ -0,0 +1,53 @@ +--- +title: Setting Up Kernel-Mode Debugging in Visual Studio +description: You can use Microsoft Visual Studio to set up and perform kernel-mode debugging of Windows. +ms.assetid: 38E57F45-71D9-4467-BECF-42769563751E +keywords: ["Kernel-mode debugging, Visual Studio", "Setting up kernel-mode debugging, Visual Studio"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging in Visual Studio + + +You can use Microsoft Visual Studio to set up and perform kernel-mode debugging of Windows. To use Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Development](http://go.microsoft.com/fwlink/p?linkid=301383). + +**Important**  This feature is not available in Windows 10, version 1507 and later versions of the WDK. + +  + +As an alternative to using Visual Studio to set up kernel-mode debugging, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md). + +Kernel-mode debugging typically requires two computers. The debugger runs on the *host computer,* and the code being debugged runs on the *target computer*. + +## In this section + + +- [Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging over a 1394 Cable in Visual Studio](setting-up-a-1394-cable-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable in Visual Studio](setting-up-a-usb-3-0-cable-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable in Visual Studio](setting-up-a-usb-2-0-cable-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging over a Serial Cable in Visual Studio](setting-up-a-null-modem-cable-connection-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio](setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md) +- [Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio](setting-up-a-connection-to-a-virtual-machine-in-visual-studio.md) + +## Related topics + + +[Setting Up Debugging (Kernel-Mode and User-Mode)](getting-set-up-for-debugging.md) + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md new file mode 100644 index 0000000000..c37b23f494 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md @@ -0,0 +1,46 @@ +--- +title: Setting Up Kernel-Mode Debugging Manually +description: This section describes how to set up kernel-mode debugging manually. +ms.assetid: 268DF246-46AA-4F4E-BCBB-FCA37A3C0353 +keywords: ["Kernel-mode debugging", "Setting up kernel-mode debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up Kernel-Mode Debugging Manually + + +This section describes how to set up kernel-mode debugging manually. + +## In this section + + +- [Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) +- [Setting Up Kernel-Mode Debugging over a 1394 Cable Manually](setting-up-a-1394-cable-connection.md) +- [Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually](setting-up-a-usb-3-0-debug-cable-connection.md) +- [Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually](setting-up-a-usb-2-0-debug-cable-connection.md) +- [Setting Up Kernel-Mode Debugging over a Serial Cable Manually](setting-up-a-null-modem-cable-connection.md) +- [Setting Up Kernel-Mode Debugging using Serial over USB Manually](setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md) +- [Setting Up Kernel-Mode Debugging of a Virtual Machine Manually](attaching-to-a-virtual-machine--kernel-mode-.md) +- [Setting Up Local Kernel Debugging of a Single Computer Manually](setting-up-local-kernel-debugging-of-a-single-computer-manually.md) + +## Related topics + + +[Setting Up Debugging (Kernel-Mode and User-Mode)](getting-set-up-for-debugging.md) + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md new file mode 100644 index 0000000000..59a4efd422 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md @@ -0,0 +1,99 @@ +--- +title: Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio with a Sharks Cove development board +description: This topic describes setting up Kernel-Mode Debugging USB in Visual Studio with a Sharks Cove development board. +ms.assetid: D909CA2C-3870-4521-8F23-FBF93738F338 +--- + +# Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio + + +The [Sharks Cove development board](http://go.microsoft.com/fwlink/p?linkid=403168) supports serial debugging over a USB cable. + +To use Microsoft Visual Studio for kernel-mode debugging, you must have the Windows Driver Kit (WDK) integrated with Visual Studio. For information about how to install the integrated environment, see [Windows Driver Kit (WDK)](http://go.microsoft.com/fwlink/p?linkid=301383). + +As an alternative to using Visual Studio to set up serial debugging over a USB cable, you can do the setup manually. For more information, see [Setting Up Kernel-Mode Debugging using Serial over USB Manually](setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. In this topic, the Sharks Cove board is the target computer. + +## Setting up a Host Computer for debugging the Sharks Cove board + + +1. On the host computer, open Device Manager. On the **View** menu, choose **Devices by Type**. + +2. On the Sharks Cove board, locate the debug connector. This is the micro USB connector shown in the following picture. + + ![picture that shows debug connector on sharks cove board](images/sharkscovedebugconnector.png) + +3. Use a USB 2.0 cable to connect the host computer to the debug connector on the Sharks cove board. + +4. On the host computer, in Device Manager, two COM ports will get enumerated. Select the lowest numbered COM port. On the **View** menu, choose **Devices by Connection**. Verify that the COM port is listed under one of the USB host controllers. + + ![screen show that shows com ports in device manager](images/serialoverusb01.png) + + Make a note of the COM port number. This is the lowest COM port number that shows under the USB host controller node. For example, in the preceding screen shot, the lowest COM port number under the USB host controller is COM3. You will need this COM port number later when you start a debugging session. If the driver is not already installed for the COM port, right click the COM port node, and choose **Update Driver**. Then select **Search automatically for updated driver software**. You will need an internet connection for this. + +## Configuring the host and target computers + + +In these steps, the Sharks Cove board is the target computer. + +1. Begin configuring your host and target computer as described in [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909). +2. On the host computer, in Visual Studio, when you come to the Computer Configuration dialog box, select **Provision computer and choose debugger settings**. +3. For **Connection Type**, choose **Serial**. + + ![screen shot showing an example of debugger settings with values for the following fields: connection type, target name, and bus parameters](images/setupserialoverusbvs.png) + + For **Baud Rate**, enter 115200. For **Port**, enter the name of the COM port that you noted previously in Device Manager (for example, com3). For **Target Port**, enter com1. + +4. The configuration process takes several minutes and might automatically reboot the target computer once or twice. When the process is complete, click **Finish**. + +## Starting the Debugging Session + + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows Kernel Mode Debugger**. +3. For **Qualifier**, select the name of the target computer that you previously configured. +4. Click **Attach**. + +## Troubleshooting Tips for Serial Debugging over a USB Cable + + +### Specify correct COM port on both host and target + +On the target computer (Sharks Cove board), verify that you are using COM1 for debugging. Open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. The output of **bcdedit** should show `debugport 1`. + +On the host computer, verify that you are using the COM port that you noted earlier in Device Manager. + +1. On the host computer, in Visual Studio, on the **Driver** menu, choose **Test > Configure Computers**. +2. Select the name of your test computer, and click **Next**. +3. Select **Provision computer and choose debugger settings**. Click **Next**. +4. Verify that the correct COM port number is listed for **Port**. + +### Baud rate must be the same on host and target + +The baud rate must be 115200 on both the host and target computers. + +On the target computer (Sharks Cove board), open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. The output of **bcdedit** should show `baudrate 115200`. + +On the host computer, verify that you are using a baud rate of 115200. + +1. On the host computer, in Visual Studio, on the **Driver** menu, choose **Test > Configure Computers**. +2. Select the name of your test computer, and click **Next**. +3. Select **Provision computer and choose debugger settings**. Click **Next**. +4. Verify that the **Baud Rate** is 115200. + +## Related topics + + +[Setting Up Kernel-Mode Debugging in Visual Studio](setting-up-kernel-mode-debugging-in-visual-studio.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20using%20Serial%20over%20USB%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md new file mode 100644 index 0000000000..c1ecb32bd7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-kernel-mode-debugging-using-serial-over-usb-manually-.md @@ -0,0 +1,120 @@ +--- +title: Setting Up Kernel-Mode Debugging using Serial over USB Manually for a Sharks cove development board +description: This topic describes setting up Kernel-Mode Debugging manually for a Sharks cove development board. +ms.assetid: E6157263-74E8-4704-9668-B845043737A7 +--- + +# Setting Up Kernel-Mode Debugging using Serial over USB Manually + + +The [Sharks Cove development board](http://go.microsoft.com/fwlink/p?linkid=403168) supports serial debugging over a USB cable. + +This topic describes how to set up serial debugging over a USB cable manually. As an alternative to setting up manually, you can do the setup using Microsoft Visual Studio. For more information, see [Setting Up Kernel-Mode Debugging using Serial over USB in Visual Studio](setting-up-kernel-mode-debugging-using-serial-over-usb-in-visual-studio.md). + +The computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. In this topic, the Sharks Cove board is the target computer. + +## Setting up a Host Computer for debugging the Sharks Cove board + + +1. On the host computer, open Device Manager. On the **View** menu, choose **Devices by Type**. + +2. On the Sharks Cove board, locate the debug connector. This is the micro USB connector shown in the following picture. + + ![picture that shows debug connector on sharks cove board](images/sharkscovedebugconnector.png) + +3. Use a USB 2.0 cable to connect the host computer to the debug connector on the Sharks cove board. + +4. On the host computer, in Device Manager, two COM ports will get enumerated. Select the lowest numbered COM port. On the **View** menu, choose **Devices by Connection**. Verify that the COM port is listed under one of the USB host controllers. + + ![screen show that shows com ports in device manager](images/serialoverusb01.png) + + Make a note of the COM port number. This is the lowest COM port number that shows under the USB host controller node. For example, in the preceding screen shot, the lowest COM port number under the USB host controller is COM3. You will need this COM port number later when you start a debugging session. If the driver is not already installed for the COM port, right click the COM port node, and choose **Update Driver**. Then select **Search automatically for updated driver software**. You will need an internet connection for this. + +## Setting Up the Sharks Cove Board as the Target Computer + + +1. On the target computer (Sharks Cove board), open a Command Prompt window as Administrator, and enter these commands: + + **bcdedit /debug on** + + **bcdedit /dbgsettings serial debugport:1 baudrate:115200** + +2. Reboot the target computer. + +## Starting the Debugging Session + + +### Using WinDbg + +On the host computer, open WinDbg. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **COM** tab. In the **Baud rate** box, enter 115200. In the **Port** box, enter COM*n* where *n* is the COM port number you noted previously. Click **OK**. + +You can also start a session with WinDbg by entering the following command in a Command Prompt window; *n* is the number of the COM port that you noted on the host computer: + +**windbg -k com:port=COM***n***,baud=115200** + +### Using KD + +On the host computer, open a Command Prompt window, and enter the following command, where *n* is the COM port number you noted previously: + +**kd -k com:port=COM***n***,baud=115200** + +## Using Environment Variables + + +On the host computer, you can use environment variables to specify the COM port and the baud rate. Then you do not have to specify the port and baud rate each time you start a debugging session. To use environment variables to specify the COM port and baud rate, open a Command Prompt window and enter the following commands, where *n* is the number COM port number you noted previously: + +- **set \_NT\_DEBUG\_PORT=COM***n* +- **set \_NT\_DEBUG\_BAUD\_RATE=115200** + +To start a debugging session, open a Command Prompt window, and enter one of the following commands: + +- **kd** +- **windbg** + +## Troubleshooting Tips for Serial Debugging over a USB Cable + + +### Specify correct COM port on both host and target + +On the target computer (Sharks Cove board), verify that you are using COM1 for debugging. Open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. The output of **bcdedit** should show `debugport 1`. + +On the host computer, specify the correct COM port when you start the debugger or when you set environment variables. This is the lowest numbered COM port that was enumerated under the USB host controller in Device Manager. For example, if COM3 is the desired port, use one of the following methods to specify the COM port. + +- In WinDbg, in the Kernel Debugging dialog box, enter COM3 in the **Port** box. +- **windbg -k com:port=COM3, ...** +- **kd -k com:port=COM3, ...** +- **set \_NT\_DEBUG\_PORT=COM3** + +### Baud rate must be the same on host and target + +The baud rate must be 115200 on both the host and target computers. + +On the target computer (Sharks Cove board), open a Command Prompt window as Administrator, and enter **bcdedit /dbgsettings**. The output of **bcdedit** should show `baudrate 115200`. + +On the host computer, specify the correct baud rate when you start the debugger or when you set environment variables. Use one of the following methods to specify a baud rate of 115200. + +- In WinDbg, in the Kernel Debugging dialog box, enter 115200 in the **Baud rate** box. +- **windbg -k ..., baud=115200** +- **kd -k ..., baud=115200** +- **set \_NT\_DEBUG\_BAUD\_RATE=115200** + +## Additional Information + + +For complete documentation of the **bcdedit** command, see Boot Options for Driver Testing and Debugging in the Windows Driver Kit (WDK) documentation. + +## Related topics + + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Kernel-Mode%20Debugging%20using%20Serial%20over%20USB%20Manually%20%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-local-kernel-debugging-of-a-single-computer-manually.md b/windows-driver-docs-pr/debugger/setting-up-local-kernel-debugging-of-a-single-computer-manually.md new file mode 100644 index 0000000000..f16391d75d --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-local-kernel-debugging-of-a-single-computer-manually.md @@ -0,0 +1,54 @@ +--- +title: Setting Up Local Kernel Debugging of a Single Computer Manually +description: Setting Up Local Kernel Debugging of a Single Computer Manually +ms.assetid: FC717B1C-A68A-4002-A528-BFC3521C5E8A +--- + +# Setting Up Local Kernel Debugging of a Single Computer Manually + + +Debugging Tools for Windows supports *local kernel debugging*. This is kernel-mode debugging on a single computer. In other words, the debugger runs on the same computer that is being debugged. With local debugging you can examine state, but not break into kernel mode processes that would cause the OS to stop running. + +The *local* bcdedit option is available in Windows 8.0 and Windows Server 2012 and later. + +## Setting Up Local Kernel-Mode Debugging + + +1. Open a Command Prompt window as Administrator. Enter **bcdedit /debug on** +2. If the computer is not already configured as the target of a debug transport, enter **bcdedit /dbgsettings local** +3. Reboot the computer. + +## Starting the Debugging Session + + +### Using WinDbg + +Open WinDbg as Administrator. On the **File** menu, choose **Kernel Debug**. In the Kernel Debugging dialog box, open the **Local** tab. Click **OK**. + +You can also start a session with WinDbg by opening a Command Prompt window as Administrator and entering the following command: + +**windbg -kl** + +### Using KD + +Open a Command Prompt window as Administrator, and enter the following command: + +**kd -kl** + +## Related topics + + +[Local Kernel-Mode Debugging](performing-local-kernel-debugging.md) + +[Setting Up Kernel-Mode Debugging Manually](setting-up-kernel-mode-debugging-in-windbg--cdb--or-ntsd.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Local%20Kernel%20Debugging%20of%20a%20Single%20Computer%20Manually%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-network-debugging-of-a-virtual-machine-host.md b/windows-driver-docs-pr/debugger/setting-up-network-debugging-of-a-virtual-machine-host.md new file mode 100644 index 0000000000..c1e8dac196 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-network-debugging-of-a-virtual-machine-host.md @@ -0,0 +1,38 @@ +--- +title: Setting Up Network Debugging of a Virtual Machine Host +description: If your target computer is a virtual machine host, you can set up network debugging and still have network access for the virtual machines. +ms.assetid: E4C4D2A1-2FB0-4028-8A52-30B8F4F738D0 +--- + +# Setting Up Network Debugging of a Virtual Machine Host + + +If your target computer is a virtual machine host, you can set up network debugging and still have network access for the virtual machines. + +Suppose you want to set up network debugging in the following situation. + +- The target computer has a single network interface card. +- You intend to install the Hyper-V role on the target computer. +- You intend to create one or more virtual machines on the target computer. + +The best approach is to set up network debugging on the target computer before you install the Hyper-V role. Then the virtual machines will have access to the network. + +If you decide to set up network debugging after the Hyper-V role has been installed on the target computer, you must change the network settings for your virtual machines to bridge them to the Microsoft Kernel Network Debug Adapter. Otherwise, the virtual machines will not have access to the network. + +## Related topics + + +[Setting Up Network Debugging in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) + +[Setting Up a Network Connection Manually](setting-up-a-network-debugging-connection.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20Network%20Debugging%20of%20a%20Virtual%20Machine%20Host%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-the-web-site.md b/windows-driver-docs-pr/debugger/setting-up-the-web-site.md new file mode 100644 index 0000000000..853095e14f --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-the-web-site.md @@ -0,0 +1,50 @@ +--- +title: Setting Up the Web Site +description: Setting Up the Web Site +ms.assetid: 9c719557-bca0-4c9c-9208-70e106d976f9 +--- + +# Setting Up the Web Site + + +Set up a Web site from which to share the source files and note the root directory of the site. Your source is then available from a site such as: + +``` +https://SrcMachineName/source +``` + +In order to make your source files accessible over the Internet, you must configure the directories containing the source files. + +Begin by selecting the directory in which your indexed source resides. In our examples, we call this directory c:\\source and the name of the server on the network \\SrcMachineName. Permissions must be set so that users can access the site, and you must add the security groups that must access the source content over the network. The amount of security to enable varies from environment to environment. For some installations, this group is **Everyone**. + +**To set up the permissions for the directory:** + +1. Open **Windows Explorer**. + +2. Expand **My Computer**. + +3. Expand the C: drive. + +4. Right-click **c:\\source** and choose **Sharing and Security**. + +5. Check the **Share this folder** button. + +6. Click the **Permissions** button. + +7. Verify that the desired security groups have read access by adding them under **Group or user names** and checking the appropriate box. + +8. Click **OK** to exit Permissions. + +9. Click **OK** to exit Source Properties. + +The source directory can now be used for debugging by another computer with a source path of srv\*\\\\SrcMachineName\\source. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20the%20Web%20Site%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/setting-up-user-mode-debugging-in-visual-studio.md b/windows-driver-docs-pr/debugger/setting-up-user-mode-debugging-in-visual-studio.md new file mode 100644 index 0000000000..8b9bd6fb10 --- /dev/null +++ b/windows-driver-docs-pr/debugger/setting-up-user-mode-debugging-in-visual-studio.md @@ -0,0 +1,42 @@ +--- +title: Setting Up User-Mode Debugging in Visual Studio +description: There are two user-mode debuggers available in the Microsoft Visual Studio environment. +ms.assetid: D36220DF-1ACB-4D8B-BC4C-1A6FCB54CA15 +--- + +# Setting Up User-Mode Debugging in Visual Studio + + +There are two user-mode debuggers available in the Microsoft Visual Studio environment. One is the Windows User-Mode Debugger, which is included in Debugging Tools for Windows. The other is the Visual Studio Debugger, which is part of the Visual Studio product. This topic describes how to get set up to use the Windows User-Mode Debugger from within the Visual Studio environment. + +## Debugging a User-Mode Process on the Local Computer + + +No special setup is required for debugging a user-mode process on the local computer. For information about attaching to a process or launching a process under the debugger, see [Debugging a User-Mode Process Using Visual Studio](debugging-a-user-mode-process-using-visual-studio.md). + +## Debugging a User-Mode Process on a Target Computer + + +In some cases, two computers are used for debugging. The debugger runs on the *host computer*, and the code that is being debugged runs on the *target computer*. In Visual Studio (running on the host computer), you can use the Windows User-Mode Debugger to attach to a user-mode process on a target computer. + +On the target computer, go to **Control Panel>Network and Internet>Network and Sharing Center>Advanced sharing settings**. Under **Guest or Public**, select **Turn on network discovery** and **Turn on file and printer sharing**. + +You can do the rest of the configuration from the host computer: + +1. On the host computer, in Visual Studio, on the **Tools** menu, choose **Attach to Process**. +2. For **Transport**, choose **Windows User Mode Debugger**. +3. To the right of the **Qualifier** box, click the **Browse** button. +4. Click the **Add** button. +5. Enter the name of the target computer. +6. To the right of **Configure Target Computer**, click the **Configure** button. The **Configure Target Computer** dialog box opens and displays the configuration progress. +7. When the configuration is complete, in the **Configure Computers** dialog box, click **OK**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Setting%20Up%20User-Mode%20Debugging%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/show-loader-snaps.md b/windows-driver-docs-pr/debugger/show-loader-snaps.md new file mode 100644 index 0000000000..e22af31d8f --- /dev/null +++ b/windows-driver-docs-pr/debugger/show-loader-snaps.md @@ -0,0 +1,62 @@ +--- +title: Show loader snaps +description: Show loader snaps +ms.assetid: fb3843fe-451f-444c-a690-862253df944e +keywords: ["Show loader snaps (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Show loader snaps + + +## + + +The **Show loader snaps** flag captures detailed information about the loading and unloading of executable images and their supporting library modules and displays the data in the kernel debugger console. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

sls

Hexadecimal value

0x2

Symbolic Name

FLG_SHOW_LDR_SNAPS

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +For system-wide (registry or kernel flag), this flag displays information about driver loading and unloading operations. + +For per-process (image file), this flag displays information about loading and unloading of DLLs. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Show%20loader%20snaps%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/sieextpub-dll.md b/windows-driver-docs-pr/debugger/sieextpub-dll.md new file mode 100644 index 0000000000..afc671f616 --- /dev/null +++ b/windows-driver-docs-pr/debugger/sieextpub-dll.md @@ -0,0 +1,29 @@ +--- +title: SieExtPub.dll +description: SieExtPub.dll +ms.assetid: 7f917fb0-a951-42df-a618-428c42bc972a +--- + +# SieExtPub.dll + + +## + + +The SieExtPub.dll extension module is not part of Microsoft Debugging Tools for Windows, and SieExtPub.dll is no longer included in Debug Diagnostic Tool. Many of the extension commands that were in SieExtPub.dll are now in ext.dll. To see a list of extension commands in ext.dll, enter the following command in the debugger. + +**.extmatch /e ext \*** + +**Note**  The **!critlist** extension command is no longer available. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SieExtPub.dll%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/sign-extension.md b/windows-driver-docs-pr/debugger/sign-extension.md new file mode 100644 index 0000000000..ae210ad9ab --- /dev/null +++ b/windows-driver-docs-pr/debugger/sign-extension.md @@ -0,0 +1,72 @@ +--- +title: Sign Extension +description: Sign Extension +ms.assetid: 58e84d09-ab70-4cb2-b12f-4addb34f69d6 +keywords: ["sign extension of numbers", "sign extension of registers", "MASM expressions, sign extension", "registers, sign extension"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sign Extension + + +## + + +When a 32-bit signed integer is negative, its highest bit is equal to one. When this 32-bit signed integer is cast to a 64-bit number, the high bits can be set to zero (preserving the unsigned integer and hexadecimal value of the number) or the high bits can be set to one (preserving the signed value of the number). The latter situation is called *sign extension*. + +The debugger follows different rules for sign extension in MASM expressions, in C++ expressions, and when displaying numbers. + +### Sign Extension in MASM Expressions + +Under certain conditions, numbers are automatically *sign extended* by the MASM expression evaluator. Sign extension can affect only numbers from 0x80000000 through 0xFFFFFFFF. That is, sign extension affects only numbers that can be written in 32 bits with the high bit equal to 1. + +The number 0x12345678 always remains 0x00000000\`12345678 when the debugger treats it as a 64-bit number. On the other hand, when 0x890ABCDE is treated as a 64-bit value, it might remain 0x00000000\`890ABCDE or the MASM expression evaluator might sign extend it to 0xFFFFFFFF\`890ABCDE. + +A number from 0x80000000 through 0xFFFFFFFF is sign extended based on the following criteria: + +- Numeric constants are never sign extended in user mode. In kernel mode, a numeric constant is sign extended unless it contains a grave accent ( **\`** ) before the low bytes. For example, in kernel mode, the hexadecimal numbers **EEAA1122** and **00000000EEAA1122** are sign extended, but **00000000\`EEAA1122** and **0\`EEAA1122** are not. + +- A 32-bit register is sign extended in both modes. + +- Pseudo-registers are always stored as 64-bit values. They are not sign extended when they are evaluated. When a pseudo-register is *assigned* a value, the expression that is used is evaluated according to the standard C++ criteria. + +- Individual numbers and registers in an expression can be sign extended, but no other calculations during expression evaluation are sign extended. As a result, you can mask the high bits of a number or register by using the following syntax. + ``` + ( 0x0`FFFFFFFF & expression ) + ``` + +### Sign Extension in C++ Expressions + +When the debugger evaluates a C++ expression, the following rules apply: + +- Registers and pseudo-registers are never sign extended. + +- All other values are treated exactly like C++ would treat values of their type. + +### Displaying Sign-Extended and 64-Bit Numbers + +Other than 32-bit and 16-bit registers, all numbers are stored internally within the debugger as 64-bit values. However, when a number satisfies certain criteria, the debugger displays it as a 32-bit number in command output. + +The debugger uses the following criteria to determine how to display numbers: + +- If the high 32 bits of a number are all zeros (that is, if the number is from 0x00000000\`00000000 through 0x00000000\`FFFFFFFF), the debugger displays the number as a 32-bit number. + +- If the high 32 bits of a number are all ones and if the highest bit of the low 32 bits is also a one (that is, if the number is from 0xFFFFFFFF\`80000000 through 0xFFFFFFFF\`FFFFFFFF), the debugger assumes the number is a sign-extended 32-bit number and displays it as a 32-bit number. + +- If the previous two condition do not apply (that is, if the number is from 0x00000001\`00000000 through 0xFFFFFFFF\`7FFFFFFF) the debugger displays the number as a 64-bit number. + +Because of these display rules, when a number is displayed as a 32-bit number from 0x80000000 through 0xFFFFFFFF, you cannot confirm whether the high 32 bits are all ones or all zeros. To distinguish between these two cases, you must perform an additional computation on the number (such as masking one or more of the high bits and displaying the result). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Sign%20Extension%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/small-memory-dump.md b/windows-driver-docs-pr/debugger/small-memory-dump.md new file mode 100644 index 0000000000..2de71152a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/small-memory-dump.md @@ -0,0 +1,65 @@ +--- +title: Small Memory Dump +description: Small Memory Dump +ms.assetid: bc502411-5366-49d3-b650-9dddda286934 +keywords: ["dump file, Small Memory Dump", "Small Memory Dump"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Small Memory Dump + + +## + + +A *Small Memory Dump* is much smaller than the other two kinds of kernel-mode crash dump files. It is exactly 64 KB in size, and requires only 64 KB of pagefile space on the boot drive. + +This dump file includes the following: + +- The bug check message and parameters, as well as other blue-screen data. + +- The processor context (PRCB) for the processor that crashed. + +- The process information and kernel context (EPROCESS) for the process that crashed. + +- The thread information and kernel context (ETHREAD) for the thread that crashed. + +- The kernel-mode call stack for the thread that crashed. If this is longer than 16 KB, only the topmost 16 KB will be included. + +- A list of loaded drivers. + +In Windows XP and later versions of Windows, the following items are also included: + +- A list of loaded modules and unloaded modules. + +- The debugger data block. This contains basic debugging information about the system. + +- Any additional memory pages that Windows identifies as being useful in debugging failures. This includes the data pages that the registers were pointing to when the crash occurred, and other pages specifically requested by the faulting component. + +- (Windows Server 2003 and later) The Windows SKU -- for example, "Professional" or "Server". + +This kind of dump file can be useful when space is greatly limited. However, due to the limited amount of information included, errors that were not directly caused by the thread executing at time of crash may not be discovered by an analysis of this file. + +Since this kind of dump file does not contain images of any executables residing in memory at the time of the crash, you may also need to set the executable image path if these executables turn out to be important. + +If a second bug check occurs and a second Small Memory Dump file is created, the previous file will be preserved. Each additional file will be given a distinct name, which contains the date of the crash encoded in the filename. For example, mini022900-01.dmp is the first memory dump file generated on February 29, 2000. A list of all Small Memory Dump files is kept in the directory %SystemRoot%\\Minidump. + +## Related topics + + +[Varieties of Kernel-Mode Dump Files](varieties-of-kernel-mode-dump-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Small%20Memory%20Dump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/so--set-kernel-debugging-options-.md b/windows-driver-docs-pr/debugger/so--set-kernel-debugging-options-.md new file mode 100644 index 0000000000..e657c26f9f --- /dev/null +++ b/windows-driver-docs-pr/debugger/so--set-kernel-debugging-options-.md @@ -0,0 +1,80 @@ +--- +title: so (Set Kernel Debugging Options) +description: The so command sets or displays the kernel debugging options. +ms.assetid: b40260c7-6e60-4198-988f-bcafecb165bc +keywords: ["so (Set Kernel Debugging Options) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- so (Set Kernel Debugging Options) +api_type: +- NA +--- + +# so (Set Kernel Debugging Options) + + +The **so** command sets or displays the kernel debugging options. + +``` +so [Options] +``` + +## Parameters + + + *Options* +One or more of the following options: + +**NOEXTWARNING** +Does not issue a warning when the debugger cannot find an extension command. + +**NOVERSIONCHECK** +Does not check the version of debugger extension DLLs. + +If you omit *Options*, the current options are displayed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +You can also set kernel debugging options using the \_NT\_DEBUG\_OPTIONS [environment variable](kernel-mode-environment-variables.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20so%20%28Set%20Kernel%20Debugging%20Options%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-code.md b/windows-driver-docs-pr/debugger/source-code.md new file mode 100644 index 0000000000..ecc9e26072 --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-code.md @@ -0,0 +1,25 @@ +--- +title: Source Code +description: This section contains the following topics. +ms.assetid: C8275DAF-5062-4244-A78E-C14CC90055E2 +--- + +# Source Code + + +This section contains the following topics. + +- [Source Path](source-path.md) +- [Using a Source Server](using-a-source-server.md) +- [Creating Your Own Source Control System](creating-your-own-source-control-system.md) +- [SrcSrv](srcsrv.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Code%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-control-systems.md b/windows-driver-docs-pr/debugger/source-control-systems.md new file mode 100644 index 0000000000..9b9871707f --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-control-systems.md @@ -0,0 +1,36 @@ +--- +title: Source Control Systems +description: Source Control Systems +ms.assetid: b958a687-9c42-44a2-a2e3-4436877092ad +keywords: ["source control systems", "source servers, source control systems"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Source Control Systems + + +SrcSrv includes provider modules for Visual SourceSafe (vss.pm), Perforce (p4.pm), Team Foundation Servers (tfn.pm), and Subversion (svn.pm). There is also a Concurrent Versions Systems (CVS) module for use with SrcSrv, but it has not been tested extensively. It is also possible to generate your own modules to support other versions of control systems. + +This section includes: + +[Using Visual SourceSafe](using-visual-sourcesafe.md) + +[Debugging with Visual SourceSafe](debugging-with-visual-sourcesafe.md) + +[Using CVS](using-cvs.md) + +[Using Other Source Control Systems](using-other-source-control-systems.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Control%20Systems%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-indexing.md b/windows-driver-docs-pr/debugger/source-indexing.md new file mode 100644 index 0000000000..17409bcdca --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-indexing.md @@ -0,0 +1,48 @@ +--- +title: Source Indexing +description: Source Indexing +ms.assetid: 381020c6-26b1-48ab-bc7d-9ab718ecb89f +keywords: ["source indexing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Source Indexing + + +Generally, binaries are source-indexed during the build process after the application has been built. The information needed by SrcSrv is stored in the .pdb files. SrcSrv currently supports the following source control systems: + +- Perforce + +- Microsoft Visual SourceSafe + +- Microsoft Team Foundation Server + +You can also create a custom script to index your code for a different source control system. One such module for Subversion is included in this package. + +SrcSrv includes five tools that are used in the source indexing process: + +[The Srcsrv.ini File](the-srcsrv-ini-file.md) + +[The Ssindex.cmd Script](the-ssindex-cmd-script.md) + +[The SrcTool Utility](the-srctool-utility.md) + +[The PDBStr Tool](the-pdbstr-tool.md) + +[The VSSDump Tool](the-vssdump-tool.md) + +These tools are installed with Debugging Tools for Windows in the subdirectory srcsrv, and should remain installed in the same path as SrcSrv. The PERL scripts in these tools require PERL 5.6 or later. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Indexing%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-line-syntax.md b/windows-driver-docs-pr/debugger/source-line-syntax.md new file mode 100644 index 0000000000..28bf43c6ba --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-line-syntax.md @@ -0,0 +1,49 @@ +--- +title: Source Line Syntax +description: Source Line Syntax +ms.assetid: a4622a89-6419-4547-9650-eb10c3803462 +keywords: ["expressions, source line numbers", "source files and paths, line number syntax", "line number syntax", "source files and paths, file name syntax", "file name syntax", "syntax rules for commands, source line numbers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Source Line Syntax + + +## + + +You can specify source file line numbers as all or part of an MASM expression. These numbers evaluate to the offset of the executable code that corresponds to this source line. + +**Note**   You cannot use source line numbers as part of a C++ expression. For more information about when MASM and C++ expression syntax is used, see [Evaluating Expressions](evaluating-expressions.md). + +  + +You must enclose source file and line number expressions by grave accents ( **\`** ). The following example shows the full format for source file line numbers. + +``` +`[[Module!]Filename][:LineNumber]` +``` + +If you have multiple files that have identical file names, *Filename* should include the whole directory path and file name. This directory path should be the one that is used at compilation time. If you supply only the file name or only part of the path and if there are multiple matches, the debugger uses the first match that it finds. + +If you omit *Filename*, the debugger uses the source file that corresponds to the current program counter. + +*LineNumber* is read as a decimal number unless you precede it with **0x**, regardless of the current default radix. If you omit *LineNumber*, the expression evaluates to the initial address of the executable that corresponds to the source file. + +Source line expressions are not evaluated in CDB unless you issue a [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command or you include the [**-lines command-line option**](cdb-command-line-options.md) when you start WinDbg.. + +For more information about source debugging, see [Debugging in Source Mode](debugging-in-source-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Line%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-path.md b/windows-driver-docs-pr/debugger/source-path.md new file mode 100644 index 0000000000..e55b301540 --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-path.md @@ -0,0 +1,81 @@ +--- +title: Source Path +description: This topic covers how to set the source path or load the individual source files. +ms.assetid: b5dcb557-b413-401a-be4b-2d45b2597e6c +keywords: source files and paths, source path +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Source Path + + +## + + +The *source path* specifies the directories where the C and C++ source files are located. + +If you are debugging a user-mode process on the computer where the executable file was built, and if the source files are still in their original location, the debugger can automatically locate the source files. + +In most other situations, you have to set the source path or load the individual source files. + +When you are performing [remote debugging through the debugger](remote-debugging-through-the-debugger.md), the debugging server uses the source path. If you are using WinDbg as your debugger, each debugging client also has its own *local source path*. All source-related commands access the source files on the local computer. You have to set the proper paths on any client or server that you want to use source commands. + +This multiple-path system also enables a debugging client to use source-related commands without actually sharing the source files with other clients or with the server. This system is useful if there are private or confidential source files that one of the users has access to. + +You can also load source files at any time, regardless of the source path. + +### Source Path Syntax + +The debugger's source path is a string that consists of multiple directory paths, separated by semicolons. + +Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported. + +**Note**   If you are connected to a corporate network, the most efficient way to access source files is to use a source server. You can use a source server by using the **srv\*** string within your source path. For more information about source servers, see [Using a Source Server](using-a-source-server.md). + +  + +### Controlling the Source Path + +To control the source path and local source path, you can do one of the following: + +- Before you start the debugger, use the \_NT\_SOURCE\_PATH [environment variable](environment-variables.md) to set the source path. If you try to add an invalid directory through this environment variable, the debugger ignores this directory. + +- When you start the debugger, use the **-srcpath**[command-line option](command-line-options.md) to set the source path. + +- Use the [**.srcpath (Set Source Path)**](-srcpath---lsrcpath--set-source-path-.md) command to display, set, change, or append to the source path. If you are using a source server, [**.srcfix (Use Source Server)**](-srcfix---lsrcfix--use-source-server-.md) is slightly easier. + +- (WinDbg only) Use the [**.lsrcpath (Set Local Source Path)**](-srcpath---lsrcpath--set-source-path-.md) command to display, set, change, or append to the local source path. If you are using a source server, [**.lsrcfix (Use Local Source Server)**](-srcfix---lsrcfix--use-source-server-.md) is slightly easier. You can also use the WinDbg Command-Line with the parameter -lscrpath. For more information, see [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +- (WinDbg only) Use the [File | Source File Path](file---source-file-path.md) command or press CTRL+P to display, set, change, or append to the source path or the local source path. + +You can also directly open or close a source file by doing one of the following: + +- Use the [**lsf (Load or Unload Source File)**](lsf--lsf---load-or-unload-source-file-.md) command to open or close a source file. + +- (WinDbg only) Use the [**.open (Open Source File)**](-open--open-source-file-.md) command to open a source file. + +- (WinDbg only) Use the [file | open source file](file---open-source-file.md) command or press ctrl+o to open a source file. you can also use the **open source file (ctrl+o)** button (![screen shot of the open source file button](images/tbopen.png)) on the toolbar. + + **Note**   When you use **File | Open Source File** (or its shortcut menu or button equivalents) to open a source file, the path of that file is automatically appended to the source path. + +   + +- (WinDbg only) Use the [File | Recent Files](file---recent-files.md) command to open one of the four source files that you most recently opened in WinDbg. + +- (WinDbg only) Use the [File | Close Current Window](file---close-current-window.md) command or click the **Close** button in the corner of the [Source window](source-window.md) to close a source file. + +For more information about how to use source files, see [Debugging in Source Mode](debugging-in-source-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Path%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/source-window.md b/windows-driver-docs-pr/debugger/source-window.md new file mode 100644 index 0000000000..e1293cf7b7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/source-window.md @@ -0,0 +1,125 @@ +--- +title: Source Code Debugging in WinDbg +description: Source Code Debugging in WinDbg +ms.assetid: 0f939d29-0d90-442e-96d7-fe756b92a7da +keywords: ["debugging information windows, Source windows", "Source windows", "source debugging, Source windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Source Code Debugging in WinDbg + + +## Source Path + + +The source path specifies the directories where the C and C++ source files are located. For more information about viewing source code in the debugger, see [Source Code](source-code.md). + +**Note**   If you are connected to a corporate network, the most efficient way to access source files is to use a source server. You can use a source server by using the srv\* string within your source path. For more information about source servers, see [Using a Source Server](using-a-source-server.md). + +  + +To control the source path in WinDbg, do one of the following: + +- Choose **Source File Path** from the **File** menu or press CTRL+P. + +- Use the [**.srcpath (Set Source Path)**](-srcpath---lsrcpath--set-source-path-.md) command. If you are using a source server, [**.srcfix (Use Source Server)**](-srcfix---lsrcfix--use-source-server-.md) is slightly easier. + +- Use the [**.lsrcpath (Set Local Source Path)**](-srcpath---lsrcpath--set-source-path-.md) command. If you are using a source server, [**.lsrcfix (Use Local Source Server)**](-srcfix---lsrcfix--use-source-server-.md) is slightly easier. + +- When you start the debugger, use the **-srcpath** or **-lsrcpath** command-line option. See [**WinDbg Command-Line Options**](windbg-command-line-options.md). + +- Before you start the debugger, set the \_NT\_SOURCE\_PATH [environment variable](environment-variables.md). + +## Opening and Closing Source Files + + +To open or close a source file directly, do one of the following: + +- Choose **Open Source File** from the **File** menu, or press CTRL+O. You can also use the **Open source file** button (![screen shot of the open source file button](images/tbopen.png)) on the toolbar. + + **Note**  When you use the menu or the toolbar button to open a source file, the path of that file is automatically appended to the source path. + +   + +- Choose **Close Current Window** from the **File** menu. +- Click the **Close** button in the corner of the Source window. +- Choose **Recent Files** from the **File** menu to open one of the four source files that you most recently opened in WinDbg. +- Enter the [**.open (Open Source File)**](-open--open-source-file-.md) command. +- Enter the [**lsf (Load or Unload Source File)**](lsf--lsf---load-or-unload-source-file-.md) command. + +## + + +In WinDbg, the Source window displays source files that have been loaded into the debugger. + +### Opening the Source Window + +The debugger opens a source window when it loads a new source file. To restore or switch to an open Source window, go to the **Window** menu and choose from the list of windows at the bottom of the menu. + +The following screen shot shows an example of a Source window. + +![screen shot of the source window, displaying a source file that has been loaded into the debugger](images/window-source.png) + +Each source file resides in its own Source window. The title of each Source window is the full path of the source file. + +### Using the Source Window + +Each Source window displays the text of one source file. You cannot edit a source file in the debugger. For more information about changing the font and tab settings, see [Changing Text Properties](changing-text-properties.md). + +Each Source window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon that appears near the upper-right corner of the window (![screen shot of the button that displays the source window toolbar shortcut menu](images/window-source-icon.png)). The following list describes some of the menu commands: + +- **Set instruction pointer to current line** changes the value of the instruction pointer to the instruction that corresponds to the current line. This command is equivalent to using the [Edit | Set Current Instruction](edit---set-current-instruction.md) command or pressing CTRL+SHIFT+I. + +- **Edit this file** opens the source file in a text editor. The editor is determined by the WinDiff editor registry information or by the value of the WINDBG\_INVOKE\_EDITOR environment variable. For example, consider the case when the value of WINDBG\_INVOKE\_EDITOR is the following. + + ``` + c:\my\path\myeditor.exe -file %f -line %l + ``` + + In this case, Myeditor.exe will open to the one-based line number of the current source file. The %l option indicates that line numbers should be read as one-based, while %f indicates that the current source file should be used. Other substitution possibilities include %L, which indicates that line numbers are zero-based, and %p, which can also indicate that the current source file should be used. + +- **Evaluate selection** evaluates the currently selected text by using the C++ expression evaluator. The result appears in the [Debugger Command window](debugger-command-window.md). If the selected text includes more than one line, a syntax error results. This command is equivalent to using the [Edit | Evaluate Selection](edit---evaluate-selection.md) command, pressing CTRL+SHIFT+V, or using the [**?? (Evaluate C++ Expression)**](----evaluate-c---expression-.md) command with the selected text as its argument. + +- **Display selected type** displays the data type of the selected object. This display appears in the Debugger Command window. If the selected text includes more than a single object, a syntax error or other irregular results might be displayed. This command is equivalent to using the [Edit | Display Selected Type](edit---display-selected-type.md) command or pressing CTRL+SHIFT+Y. + +- **Open memory window for selection** opens a new docked Memory window that displays memory starting at the address of the selected expression. + +- **Add selection to Watch window** appends the selected source token to the Watch window. + +- **Disassemble at current line** causes the instruction that corresponds to the current line to appear in the [Disassembly window](disassembly-window.md). The selected line is highlighted in the Source window and in the Disassembly window, but this command affects only the display—the instruction pointer is not changed. If the Disassembly window is closed when this command is clicked, it is opened. + +- **Select source language** displays a list of programming languages. Select the programming language that you used to generate the source file, and then click **OK** to enable basic syntax highlighting for the current Source window. Select **<None>** to disable syntax highlighting for the current Source window. + +### Source Window Colors and Hover Evaluation + +If the debugger recognizes the source file name extension, the Source window displays certain syntax elements in color. To turn off or change the colors, do the following: + +- To turn the syntax colors off in a single window, open the Source window's shortcut menu, click **Select source language**, and then click **<None>**. + +- To turn the syntax colors off for all Source windows, choose **Options** from the **View** menu. Then clear the **Parse Source Languages** check box. + +- To change the syntax colors, choose **Options** from the **View** menu. Then, in the **Colors** area, select a syntax element and click the **Change** button to change the color. + +- The parsing method that is used for the highlighting is determined by the programming language that is associated with the file extension for the source file. To change the programming language that is associated with a specific file extension, use the [File Extensions for Source Languages dialog box](view---source-language-file-extensions.md). To open this dialog box, choose **Source language file extensions** from the **View** menu. + +The line that represents the current program counter is highlighted. Lines at which breakpoints are set are highlighted as well. + +If you select a Source window and then use the mouse to hover over a symbol in that window, the symbol will be evaluated. The evaluation is the same as that produced by the [**dt (Display Type)**](dt--display-type-.md) command. To deactivate this evaluation, choose **Options** from the **View** menu. Then clear the **Evaluate on hover** check box. + +### Additional Information + +For more information about source debugging and related commands, see [Debugging in Source Mode](debugging-in-source-mode.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Code%20Debugging%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/special-pool.md b/windows-driver-docs-pr/debugger/special-pool.md new file mode 100644 index 0000000000..d9b3475396 --- /dev/null +++ b/windows-driver-docs-pr/debugger/special-pool.md @@ -0,0 +1,166 @@ +--- +title: Special Pool +description: Special Pool +ms.assetid: 8904913d-78ed-4e5f-acef-3c21eeb87b8d +keywords: ["Special Pool", "Special Pool, overview", "GFlags, Special Pool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Special Pool + + +The **Special Pool** feature configures Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is within a specified size range. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

spp

Hexadecimal value

(None)

Symbolic Name

(None)

Destination

System-wide registry entry

+

(Windows Vista and later) System-wide registry entry, kernel flag

+ +  + +### Selecting a Pool Tag + +When requesting special pool for a particular pool tag, make sure that your driver or other kernel-mode program uses a unique pool tag. + +Also, when creating a pool tag (such as by using **ExAllocatePoolWithTag**), consider entering the tag characters in reverse order. For example, if the tag is **Fred**, consider entering it as **derF** (0x64657246). Pool tags are stored in the registry and displayed in the debugger and other tools in reverse (lower endian) order. If you enter them in reverse order, they are displayed in forward order (0x46726564) + +If you suspect that your driver is consuming all of the special pool, consider using multiple pool tags in your code. You can then test your driver several times, assigning special pool to one pool tag in each test. + +Also, select a pool tag with a hexadecimal value that is greater than the page size of the system. For kernel mode code, if you enter a pool tag that has a value less than PAGE\_SIZE, Gflags requests special pool for all allocations whose size is within the corresponding range and requests special pool for allocations with an equivalent pool tag. For example, if you select a size of **30**, special pool will be used for all allocations between 17 and 32 bytes in size, and for allocations with the pool tag 0x0030. + +### Selecting an Allocation Size + +Use the following guidelines to select an allocation size for the Special Pool feature. + +On a computer with an x86 processor, PAGE\_SIZE is 0x1000 and the allocation size ranges are 8 bytes in length. To configure the Special Pool feature for all allocations with sizes in this range, enter a number equal to the maximum of this range plus 8. (This number is always a multiple of 8.) The following table illustrates these values: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Size rangeEnter this number

1 to 8 bytes

10 (decimal 16)

9 to 16 bytes

18 (decimal 24)

17 to 24 bytes

20 (decimal 32)

...

...

0xFE9 to 0xFF0 bytes

FF8 (decimal 4088)

+ +  + +On a computer with an AMD x86-64 processor, PAGE\_SIZE is 0x1000 and the allocation size ranges are 16 bytes in length. To configure the Special Pool feature for all allocations with sizes in this range, enter a number equal to the maximum of this range plus 16. (This number is always a multiple of 16.) The following table illustrates these values: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Size rangeEnter this number

1 to 16 bytes

20 (decimal 32)

17 to 32 bytes

30 (decimal 48)

33 to 48 bytes

40 (decimal 64)

...

...

0xFD1 to 0xFE0 bytes

FF0 (decimal 4080)

+ +  + +On a computer with any processor, you can use an asterisk ( **\*** ) or 0x2A (decimal 42) to configure the Special Pool feature for all memory allocations on the system. + +### Comments + +For information about configuring the Special Pool feature in the Global Flags Dialog Box, see [Configuring Special Pool](configuring-special-pool.md). For information about configuring the Special Pool feature at the command line, see [**GFlags Commands**](gflags-commands.md). For an example, see [Example 14: Configuring Special Pool](example-14---configuring-special-pool.md). + +The Special Pool feature of Gflags directs Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is within a specified size range. To request special pool for all allocations by a particular driver, use Driver Verifier. For more information, see the "Special Pool" topic in the "Driver Verifier" section of the Windows Driver Kit (WDK). + +The special pool features of Gflags and Driver Verifier help you to detect and identify the source of errors in kernel pool use, such as writing beyond the allocated memory space, or referring to memory that has already been freed. + +Not all special pool requests are fulfilled. Each allocation from the special pool uses one page of nonpageable physical memory and two pages of virtual address space. If the special pool is exhausted, memory is allocated from the standard pool until the special pool becomes available again. When a special pool request is filled from the standard pool, the requesting function returns a success status. It does not return an error, because the allocation has succeeded, even though it was not filled from special pool. + +The size of the special pool increases with the amount of physical memory on the system; ideally this should be at least 1 Gigabyte (GB). On x86 machines, because virtual (in addition to physical) space is consumed, do not use the **/3GB** boot option when using special pool. It is also a good idea to increase the pagefile minimum/maximum quantities by a factor of two or three. + +You can also configure the Special Pool feature to align memory allocation to detect references to memory preceding the allocation ("underruns") or references to memory beyond the allocation ("overruns"). This feature is available only in the Global Flags dialog box on all versions of Windows. For details, see [Detecting Overruns and Underruns](detecting-overruns-and-underruns.md). + +On Windows Vista and later versions of Windows, you can configure the Special Pool feature as a registry setting that requires a reboot, but remains effective until you change it, or as a kernel flag setting that does not require a reboot, but is effective only until you reboot or shut down Windows. In earlier versions of Windows, Special Pool is only available as a registry setting. + +On Windows Vista and later versions of Windows, you can configure the Special Pool feature either by using the Global Flags dialog box or at the command line. In earlier version of Windows, this feature is available only in the Global Flags dialog box. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Special%20Pool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/specialized-debugging-techniques.md b/windows-driver-docs-pr/debugger/specialized-debugging-techniques.md new file mode 100644 index 0000000000..0bbaca6ad3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/specialized-debugging-techniques.md @@ -0,0 +1,37 @@ +--- +title: Specialized Debugging Techniques +description: This section describes debugging techniques that apply to particular technologies and types of code modules. +ms.assetid: ADCEC5D6-5CA1-4F46-AAFD-D4BFD27D8A29 +--- + +# Specialized Debugging Techniques + + +This section describes debugging techniques that apply to particular technologies and types of code modules. + +You can learn more in the following topics. + +- [Windows Runtime Debugging](windows-runtime-debugger-commands.md) +- [Kernel-Mode Driver Framework Debugging](kernel-mode-driver-framework-debugging.md) +- [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md) +- [Debugging Managed Code](debugging-managed-code.md) +- [Debugging Device Nodes and Device Stacks](device-node-and-stack-debugger-commands.md) +- [Debugging Plug and Play and Power Issues](plug-and-play-and-power-debugger-commands.md) +- [Debugging a User-Mode Failure with KD](debugging-a-user-mode-failure-with-kd.md) +- [Debugging a Device Installation Co-Installer](debugging-a-device-installation-co-installer.md) +- [Debugging a Dual-Boot Machine](debugging-a-dual-boot-machine.md) +- [Debugging Windows Setup and the OS Loader](debugging-windows-setup-and-the-os-loader.md) +- [Debugging CSRSS](debugging-csrss.md) +- [Debugging WinLogon](debugging-winlogon.md) +- [Debugging BIOS Code](debugging-bios-code.md) +- [Specifying Module and Function Owners](specifying-module-and-function-owners.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Specialized%20Debugging%20Techniques%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/specialized-extensions.md b/windows-driver-docs-pr/debugger/specialized-extensions.md new file mode 100644 index 0000000000..366fe10c8a --- /dev/null +++ b/windows-driver-docs-pr/debugger/specialized-extensions.md @@ -0,0 +1,52 @@ +--- +title: Specialized Extensions +description: Specialized Extensions +ms.assetid: 4329fade-2458-4a60-a06c-4069fc339f3e +keywords: ["extension commands ( commands), specialized extensions", "extension commands ( commands), specialized extensions, Also see individual extension types"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specialized Extensions + + +## + + +This section of the reference discusses extension commands in the extension DLLs that are used less often. + +## In this section + + +- [Storage Kernel Debugger Extensions](storage-kernel-debugger-extensions.md) +- [Bluetooth Extensions (Bthkd.dll)](bluetooh-extensions--bthkd-dll-.md) +- [GPIO Extensions](gpio-extensions.md) +- [USB 3.0 Extensions](usb-3-extensions.md) +- [USB 2.0 Debugger Extensions](usb-2-0-extensions.md) +- [RCDRKD Extensions](rcdrkd-extensions.md) +- [HID Extensions](hid-extensions.md) +- [Logger Extensions (Logexts.dll)](logger-extensions--logexts-dll-.md) +- [NDIS Extensions (Ndiskd.dll)](ndis-extensions--ndiskd-dll-.md) +- [RPC Extensions (Rpcexts.dll)](rpc-extensions--rpcexts-dll-.md) +- [ACPI Extensions (Acpikd.dll and Kdexts.dll)](acpi-extensions--acpikd-dll-and-kdexts-dll-.md) +- [Graphics Driver Extensions (Gdikdx.dll)](graphics-driver-extensions--gdikdx-dll-.md) +- [Kernel Streaming Extensions (Ks.dll)](kernel-streaming-extensions--ks-dll-.md) +- [SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll)](scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md) +- [Windows Driver Framework Extensions (Wdfkd.dll)](kernel-mode-driver-framework-extensions--wdfkd-dll-.md) +- [User-Mode Driver Framework Extensions (Wudfext.dll)](user-mode-driver-framework-extensions--wudfext-dll-.md) +- [WMI Tracing Extensions (Wmitrace.dll)](wmi-tracing-extensions--wmitrace-dll-.md) +- [OEM Support Extensions (kdex2x86.dll)](oem-support-extensions--kdex2x86-dll-.md) +- [SieExtPub.dll](sieextpub-dll.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Specialized%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/specifying-module-and-function-owners.md b/windows-driver-docs-pr/debugger/specifying-module-and-function-owners.md new file mode 100644 index 0000000000..d3d5b4ce49 --- /dev/null +++ b/windows-driver-docs-pr/debugger/specifying-module-and-function-owners.md @@ -0,0 +1,128 @@ +--- +title: Specifying Module and Function Owners +description: Specifying Module and Function Owners +ms.assetid: be227712-7f70-4e74-b090-ca8b3ecd1e13 +keywords: ["executable files and paths, specifying module owner", "function owners", "owners of modules and functions", "triage.ini file", "triage.ini file, syntax", "analyze extension, triage.ini file"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specifying Module and Function Owners + + +## + + +The **!analyze** and **!owner** extensions use a file that is named Triage.ini to determine the owner of the symbols that the debugger encounters. + +When you use these extensions, the identities of the function or module owner are displayed after the word "Followup". + +The Triage.ini file is a text file that resides in the \\triage subdirectory of your Debugging Tools for Windows installation. A sample Triage.ini file is included as part of the Debugging Tools for Windows package. + +**Warning**   If you install an updated version of Debugging Tools for Windows in the same directory as the current version, it overwrites all of the files in that directory, including Triage.ini. After you modify or replace the sample Triage.ini file, save a copy of it to a different directory. After you reinstall the debuggers, you can copy the saved Triage.ini over the default version. + +  + +### Format of the Triage.ini File + +Although the Triage.ini file is intended to help you determine the owner of a function that has broken into the debugger, the "owner" strings in this file can be anything that might help you with debugging. The strings can be names of people who wrote or maintain the code. Or, the strings can be short instructions about what you can do when an error occurs in a module or function. + +Each line in this file has the following syntax. + +``` +Module[!Function]=Owner +``` + +You can add an asterisk (\*) only at the end of a module or function name. If it appears elsewhere, it is interpreted as a literal character. + +You cannot add spaces in the owner string. If spaces do exist in the owner string, they are ignored. + +For more information about syntax options, see Special Triage.ini Syntax. + +The following examples shows a sample Triage.ini file. + +``` +module1=Person1 +module2!functionA=Person2 +module2!functionB=Person3 +module2!funct*=Person4 +module2!*=Person5 +module3!singleFunction=Person6 +mod*!functionC=Person7 +``` + +### Triage.ini and !owner + +When you pass a module or function name to the [**!owner**](-owner.md) extension, the debugger displays the word "Followup" followed by the name of the module or function's owner. + +The following example uses the previous sample Triage.ini file. + +``` +0:000> !owner module2!functionB +Followup: Person3 +``` + +According to the file, "Person3" owns **module2!functionB**, and "Person4" owns **module2!funct\***. Both of these strings match the argument that is passed to **!owner**, so the more complete match is used. + +### Triage.ini and !analyze + +When you use the [**!analyze**](-analyze.md) extension, the debugger looks at the top faulting frame in the stack and tries to determine the owner of the module and function in this frame. If the debugger can determine the owner, the owner information is displayed. + +If the debugger cannot determine the owner, the debugger passes to the next stack frame, and so on, until the debugger determines the owner or the stack is completely examined. + +If the debugger can determine the owner, the owner name is displayed after the word "Followup". If the debugger searches the whole stack without finding any information, no name is displayed. + +The following example uses the sample Triage.ini file that is given earlier in this topic. + +Suppose the first frame on the stack is **MyModule!someFunction**. The debugger does not find **MyModule** in the Triage.ini file. Next, it continues to the second frame on the stack. + +Suppose the second frame is **module3!anotherFunction**. The debugger does see an entry for **module3**, but there is no match for **anotherFunction** in this module. Next, the debugger continues to the third frame. + +Suppose the third frame is **module2!functionC**. The debugger first looks for an exact match, but such a match does not exist. The debugger then trims the function name and discovers **module2!funct\*** in Triage.ini. This match ends the search, because the debugger determines that the owner is "Person4". + +The debugger then displays output that is similar to the following example. + +``` +0:000> !analyze +******************************************************************************* +* * +* Exception Analysis * +* * +******************************************************************************* + +Use !analyze -v to get detailed debugging information. + +Probably caused by : module2 ( module2!functionC+15a ) + +Followup: Person4 +--------- +``` + +A more complete match takes precedence over a shorter match. However, a module name match is always preferred to a function name match. If **module2!funct\*** had not been in this Triage.ini file, the debugger would have selected **module2!\*** as the match. And if both **module2!funct\*** and **module2!\*** were removed, **mod\*!functionC** would have been selected. + +### Special Triage.ini Syntax + +If you omit the exclamation point and function name or add **!\*** after a module name, all functions in that module are indicated. If a function within this module is also specified separately, the more precise specification takes precedence. + +If you use "default" as a module name or a function name, it is equivalent to a wildcard character. For example, **nt!\*** is the same as **nt!default**, and **default** is the same as **\*!\***. + +If a match is made, but the word **ignore** appears to the right of the equal sign (=), the debugger continues to the next frame in the stack. + +You can add **last\_** or **maybe\_** before an owner's name. This prefix gives the owner less priority when you run **!analyze**. The debugger chooses a definite match that is lower on the stack over a **maybe\_** match that is higher on the stack. The debugger also chooses a **maybe\_** match that is lower on the stack over a **last\_** match that is higher on the stack. + +### Sample Triage.ini + +A sample Triage.ini template is included in the Debugging Tools for Windows package. You can add the owners of any modules and functions that you want to this file. If you want to have no global default, delete the **default=MachineOwner** line at the beginning of this file. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Specifying%20Module%20and%20Function%20Owners%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/sq--set-quiet-mode-.md b/windows-driver-docs-pr/debugger/sq--set-quiet-mode-.md new file mode 100644 index 0000000000..211e4b503d --- /dev/null +++ b/windows-driver-docs-pr/debugger/sq--set-quiet-mode-.md @@ -0,0 +1,82 @@ +--- +title: sq (Set Quiet Mode) +description: The sq command turns quiet mode on or off. +ms.assetid: db8a266c-e2e5-4de7-8154-993a78585f04 +keywords: ["sq (Set Quiet Mode) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sq (Set Quiet Mode) +api_type: +- NA +--- + +# sq (Set Quiet Mode) + + +The **sq** command turns quiet mode on or off. + +``` +sq +sq{e|d} +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The **sqe** command turns quiet mode on, and the **sqd** command turns it off. The **sq** command turns on and off quiet mode. Each of these commands also displays the new quiet mode status. + +You can set quiet mode in KD or kernel-mode WinDbg by using the KDQUIET [environment variable](kernel-mode-environment-variables.md). (Note that quiet mode exists in both user-mode and kernel-mode debugging, but the KDQUIET environment variable is only recognized in kernel mode.) + +*Quiet mode* has three distinct effects: + +- The debugger does not display messages every time that an extension DLL is loaded or unloaded. + +- The [**r (Registers)**](r--registers-.md) command no longer requires an equal sign (=) in its syntax. + +- When you break into a target computer while kernel debugging, the long warning message is suppressed. + +Do not confuse quiet mode with the effects of the **-myob** [command-line option](command-line-options.md) (in CDB and KD) or the **-Q** [**command-line option**](windbg-command-line-options.md) (in WinDbg). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20sq%20%28Set%20Quiet%20Mode%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/srcsrv.md b/windows-driver-docs-pr/debugger/srcsrv.md new file mode 100644 index 0000000000..d67d2b53c3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/srcsrv.md @@ -0,0 +1,38 @@ +--- +title: SrcSrv +description: SrcSrv +ms.assetid: 4d9a236c-2a0a-4107-8f99-3f9437c79404 +keywords: ["source servers", "SrcSrv"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SrcSrv + + +The SrcSrv tool (Srcsrv.dll) enables a client to retrieve the exact version of the source files that were used to build an application. Because the source code for a module can change between versions and over the course of years, it is important to look at the source code as it existed when the version of the module in question was built. + +SrcSrv retrieves the appropriate files from source control. To use SrcSrv, the application must have been source-indexed. + +This section includes: + +[Using SrcSrv](using-srcsrv.md) + +[Source Indexing](source-indexing.md) + +[Source Control Systems](source-control-systems.md) + +[HTTP Sites and UNC Shares](http-sites-and-unc-shares.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SrcSrv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ss--set-symbol-suffix-.md b/windows-driver-docs-pr/debugger/ss--set-symbol-suffix-.md new file mode 100644 index 0000000000..c3c23495e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ss--set-symbol-suffix-.md @@ -0,0 +1,82 @@ +--- +title: ss (Set Symbol Suffix) +description: The ss command sets or displays the current suffix value that is used for symbol matching in numeric expressions. +ms.assetid: acf4cf2e-5b09-4d46-aa42-e539ee968685 +keywords: ["ss (Set Symbol Suffix) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ss (Set Symbol Suffix) +api_type: +- NA +--- + +# ss (Set Symbol Suffix) + + +The **ss** command sets or displays the current suffix value that is used for symbol matching in numeric expressions. + +``` +ss [a|w|n] +``` + +## Parameters + + + **a** +Specifies that the symbol suffix should be "A", matching many ASCII symbols. + + **w** +Specifies that the symbol suffix should be "W", matching many Unicode symbols. + + **n** +Specifies that the debugger should not use a symbol suffix. (This parameter is the default behavior.) + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about symbol matching, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +Remarks +------- + +If you specify the **ss** command together with no parameters, the current state of the suffix value is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ss%20%28Set%20Symbol%20Suffix%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/stack-unwind-information-not-available.md b/windows-driver-docs-pr/debugger/stack-unwind-information-not-available.md new file mode 100644 index 0000000000..267b5a0a63 --- /dev/null +++ b/windows-driver-docs-pr/debugger/stack-unwind-information-not-available.md @@ -0,0 +1,35 @@ +--- +title: Stack Unwind Information Not Available +description: Stack Unwind Information Not Available +ms.assetid: 82260f85-780b-4f30-bebd-62faed6efeeb +keywords: ["Stack unwind information not available (warning)", "call stack, Stack unwind information not available (warning)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stack Unwind Information Not Available + + +## + + +When the debugger is examining the call stack, it may display the message "Stack unwind information not available. Following frames may be wrong." + +This warning indicates that the debugger is not certain that the frames in the call stack listed after this message are correct. + +To trace the call stack, the debugger examines the stack and analyzes the functions that have used the stack. This lets it identify the chain of return addresses that form the call stack. However, this procedure requires symbol information for each module containing the functions that used the stack. + +If this symbol information is not available, the debugger is forced to make a best guess about which frames are return addresses. This warning information is displayed to indicate the uncertain nature of the call stack after this point. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Stack%20Unwind%20Information%20Not%20Available%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/standard-debugging-techniques.md b/windows-driver-docs-pr/debugger/standard-debugging-techniques.md new file mode 100644 index 0000000000..0855434e07 --- /dev/null +++ b/windows-driver-docs-pr/debugger/standard-debugging-techniques.md @@ -0,0 +1,60 @@ +--- +title: Standard Debugging Techniques +description: This section discusses standard debugging techniques that you can apply across different technologies and different types of code. +ms.assetid: D7752D63-E2A7-418C-A06F-6D5CCF3EDAEB +--- + +# Standard Debugging Techniques + + +This section discusses standard debugging techniques that you can apply across different technologies and different types of code. + +## In this section + + +- [Using Breakpoints](using-breakpoints.md) +- [Reading and Writing Memory](reading-and-writing-memory.md) +- [Using the !analyze Extension](using-the--analyze-extension.md) +- [Handling a Bug Check When Driver Verifier is Enabled](handling-a-bug-check-when-driver-verifier-is-enabled.md) +- [Noninvasive Debugging (User Mode)](noninvasive-debugging--user-mode-.md) +- [Debugging in Assembly Mode](debugging-in-assembly-mode.md) +- [Debugging in Source Mode](debugging-in-source-mode.md) +- [Debugging Optimized Code and Inline Functions](debugging-optimized-code-and-inline-functions-external.md) +- [Debugging Managed Code Using the Windows Debugger](debugging-managed-code.md) +- [Debugging Windows Apps Using the Windows Debugger](debugging-windows-store-apps-using-the-windows-debugger.md) +- [Changing Contexts](changing-contexts.md) +- [Controlling Processes and Threads](controlling-processes-and-threads.md) +- [Using Debugger Markup Language](debugger-markup-language-commands.md) +- [Controlling Exceptions and Events](controlling-exceptions-and-events.md) +- [Finding the Process ID](finding-the-process-id.md) +- [Debugging a Stack Overflow](debugging-a-stack-overflow.md) +- [Manually Walking a Stack](manually-walking-a-stack.md) +- [Debugging a Stack Trace that has JScript Frames](debugging-a-stack-trace-that-has-jscript-frames.md) +- [Debugging an Application Failure](debugging-an-application-failure.md) +- [Reattaching to the Target Application](reattaching-to-the-target-application.md) +- [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) +- [Synchronizing with the Target Computer](synchronizing-with-the-target-computer.md) +- [Finding a Memory Leak](finding-a-memory-leak.md) +- [Debugging a Time Out](debugging-a-time-out.md) +- [Debugging a Stalled System](debugging-a-stalled-system.md) +- [Debugging Multiple Targets](debugging-multiple-targets.md) +- [Tracking Down a Processor Hog](tracking-down-a-processor-hog.md) +- [Determining the ACL of an Object](determining-the-acl-of-an-object.md) +- [Displaying a Critical Section](displaying-a-critical-section.md) +- [Debugging a Deadlock](debugging-a-deadlock.md) +- [Debugging a Failed Driver Unload](debugging-a-failed-driver-unload.md) +- [Reading Bug Check Callback Data](reading-bug-check-callback-data.md) +- [Debugging a User-Mode Failure with KD](debugging-a-user-mode-failure-with-kd.md) +- [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) +- [Mapping Driver Files](mapping-driver-files.md) +- [Messages from the Target](messages-from-the-target.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Standard%20Debugging%20Techniques%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/starting-a-remote-exe-session.md b/windows-driver-docs-pr/debugger/starting-a-remote-exe-session.md new file mode 100644 index 0000000000..bcbaba8b3d --- /dev/null +++ b/windows-driver-docs-pr/debugger/starting-a-remote-exe-session.md @@ -0,0 +1,103 @@ +--- +title: Starting a Remote.exe Session +description: Starting a Remote.exe Session +ms.assetid: 2b70e54e-ab02-46f1-9af1-e7379c89cf3c +keywords: ["remote debugging through remote.exe, starting the session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Starting a Remote.exe Session + + +## + + +There are two ways to start a remote.exe session with KD or CDB. Only the second of these methods works with NTSD. + +### Customizing Your Command Prompt Window + +The Remote.exe Client and Remote.exe Server run in Command Prompt windows. + +To prepare for the remote session, you should customize this window to increase its usability. Open a Command Prompt window. Right-click the title bar and select **Properties**. Select the **Layout** tab. Go to the section titled "Screen Buffer Size" and type **90** in the **Width** box and a value between **4000** and **9999** in the **Height** box. This enables scroll bars in the remote session on the kernel debugger. + +Change the values for the height and width of the "Windows Size" section if you want to alter the shape of the command prompt. Select the **Options** tab. Enable the **Edit Options** quickedit mode and insert mode. This allows you to cut and paste information in the command prompt session. Click **OK** to apply the changes. Select the option to apply the changes to all future sessions when prompted. + +### Starting the Remote.exe Server: First Method + +The general syntax for starting a Remote.exe Server is as follows: + +``` +remote /s "Command_Line" Unique_Id [/f Foreground_Color] [/b Background_Color] +``` + +This can be used to start KD or CDB on the remote computer, as in the following examples: + +``` +remote /s "KD [options]" MyBrokenBox + +remote /s "CDB [options]" MyBrokenApp +``` + +This starts the Remote.exe Server in the Command Prompt window, and starts the debugger. + +You cannot use this method to start NTSD directly, because the NTSD process runs in a different window than the one in which it was invoked. + +### Starting the Remote.exe Server: Second Method + +There is an alternate method that can start a Remote.exe Server. This method involves first starting the debugger, and then using the [**.remote (Create Remote.exe Server)**](-remote--create-remote-exe-server-.md) command to start the server. + +Since the **.remote** command is issued after the debugger has started, this method works equally well with KD, CDB, and NTSD. + +Here is an example. First, start the debugger in the normal fashion: + +``` +KD [options] +``` + +Once the debugger is running, use the **.remote** command: + +``` +.remote MyBrokenBox +``` + +This results in a KD process that is also a Remote.exe Server with an ID of "MyBrokenBox", exactly as in the first method. + +One advantage of this method is that you do not have to decide in advance if you intend to use remote debugging. If you are debugging with one of the console debuggers and then decide that you would prefer someone in a remote location to take over, you can use the **.remote** command and then they can connect to your session. + +### Starting the Remote.exe Client + +The general syntax for starting a Remote.exe Client is as follows: + +``` +remote /c ServerNetBIOSName Unique_ID [/l Lines_to_Get] [/f Foreground_Color] [/b Background_Color] +``` + +For example, if the "MyBrokenBox" session, described above, was started on a local host computer whose network name was "Server2", you can connect to it with the command: + +``` +remote /c server2 MyBrokenBox +``` + +Anyone on the network with appropriate permission can connect to this debug session, as long as they know your machine name and the session ID. + +### Issuing Commands + +Commands are issued through the Remote.exe Client and are sent to the Remote.exe Server. You can enter any command into the client as if you were directly entering it into the debugger. + +To exit from the remote.exe session on the Remote.exe Client, enter the **@Q** command. This leaves the Remote.exe Server and the debugger running. + +To end the server session, enter the **@K** command on the Remote.exe Server. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Starting%20a%20Remote.exe%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/starting-the-debugging-session.md b/windows-driver-docs-pr/debugger/starting-the-debugging-session.md new file mode 100644 index 0000000000..433949abca --- /dev/null +++ b/windows-driver-docs-pr/debugger/starting-the-debugging-session.md @@ -0,0 +1,57 @@ +--- +title: Starting the Debugging Session +description: Starting the Debugging Session +ms.assetid: 789c61cf-edd2-4354-91a8-87a0a7af28a3 +--- + +# Starting the Debugging Session + + +## + + +In this documentation of how to [control user-mode debugging from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md), *target application* refers to the user-mode application that is being debugged, *target computer* refers to the computer that contains the target application and the NTSD or CDB process, and *host computer* refers to the computer that contains the kernel debugger. + +To begin using this technique, you must do the following. You can do steps 1 and 2 in either order. + +1. Start NTSD or CDB on the target computer, with the -d command-line option. + + For example, you can attach to a running process by using the following syntax. + + **ntsd -d \[-y** *UserSymbolPath***\] -p** *PID* + + Or, you can start a new process as the target by using the following syntax. + + **ntsd -d \[-y** *UserSymbolPath***\]** *ApplicationName* + + If you are installing this as a postmortem debugger, you would use the following syntax. + + **ntsd -d \[-y** *UserSymbolPath***\]** + + For more information about this step, see [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md). + +2. Start WinDbg or KD on the host computer, as if you were going to debug the target computer, but do not actually break in to the target computer. To use WinDbg, use the following syntax. + + **windbg \[-y** *KernelSymbolPath***\] \[-k** *ConnectionOptions***\]** + + For more information about this step, see [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md). + + **Note**  If you use WinDbg as the kernel debugger, many of the familiar features of WinDbg are not available in this scenario. For example, you cannot use the Locals window, the Disassembly window, or the Call Stack window, and you cannot step through source code. This is because WinDbg is only acting as a viewer for the debugger (NTSD or CDB) running on the target computer. + +   + +3. If you have not set the user-mode symbol path, set it from the Input> prompt. If you have not set the kernel-mode symbol path, set it from the kd> prompt. For information on how to access these prompts and to switch between modes, see [Switching Modes](switching-modes.md). + +If you use CDB, the Command Prompt window that is associated with CDB remains locked and unavailable while debugging continues. If you use NTSD, no additional window is created, even though NTSD has a process ID associated with it on the target computer. + +If you want to run the user-mode debugger from the kernel debugger while also using it as a debugging server, see [Combining This Method with Remote Debugging](combining-this-method-with-remote-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Starting%20the%20Debugging%20Session%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/stop-on-exception.md b/windows-driver-docs-pr/debugger/stop-on-exception.md new file mode 100644 index 0000000000..b4f8507465 --- /dev/null +++ b/windows-driver-docs-pr/debugger/stop-on-exception.md @@ -0,0 +1,60 @@ +--- +title: Stop on exception +description: Stop on exception +ms.assetid: f459fa28-2fdf-4094-ba58-7e01a2309bb7 +keywords: ["Stop on exception (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stop on exception + + +## + + +The **Stop on exception** flag causes the kernel to break into the kernel debugger whenever a kernel-mode exception occurs. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

soe

Hexadecimal value

0x1

Symbolic Name

FLG_STOP_ON_EXCEPTION

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +### Comments + +Windows passes all first chance exceptions (except for STATUS\_PORT\_DISCONNECT) with a severity of Warning or Error to the debugger before passing them to a local exception handler. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Stop%20on%20exception%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/stop-on-hung-gui.md b/windows-driver-docs-pr/debugger/stop-on-hung-gui.md new file mode 100644 index 0000000000..b61de4f71b --- /dev/null +++ b/windows-driver-docs-pr/debugger/stop-on-hung-gui.md @@ -0,0 +1,56 @@ +--- +title: Stop on hung GUI +description: Stop on hung GUI +ms.assetid: f1c1a045-e5ca-4274-9b47-b64d389b5fe5 +keywords: ["Stop on hung GUI (global flag)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stop on hung GUI + + +## + + +The **Stop on hung GUI** flag appears in GFlags, but it has no effect on Windows. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

shg

Hexadecimal value

0x8

Symbolic Name

FLG_STOP_ON_HUNG_GUI

Destination

Kernel flag

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Stop%20on%20hung%20GUI%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/stop-on-unhandled-user-mode-exception.md b/windows-driver-docs-pr/debugger/stop-on-unhandled-user-mode-exception.md new file mode 100644 index 0000000000..7feb812c8b --- /dev/null +++ b/windows-driver-docs-pr/debugger/stop-on-unhandled-user-mode-exception.md @@ -0,0 +1,50 @@ +--- +title: Stop on unhandled user-mode exception +description: Stop on unhandled user-mode exception +ms.assetid: BD8E1000-29B0-425D-BEA1-D4FD55CF0E4F +--- + +# Stop on unhandled user-mode exception + + +## + + +The **Stop on unhandled user-mode exception** flag causes a break into the kernel debugger whenever an unhandled user-mode exception occurs. + + ++++ + + + + + + + + + + + + + + + + + + +

Abbreviation

sue

Hexadecimal value

0x20000000

Symbolic Name

FLG_STOP_ON_UNHANDLED_EXCEPTION

Destination

System-wide registry entry, kernel flag, image file registry entry

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Stop%20on%20unhandled%20user-mode%20exception%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/storage-kernel-debugger-extensions.md b/windows-driver-docs-pr/debugger/storage-kernel-debugger-extensions.md new file mode 100644 index 0000000000..057919baa1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/storage-kernel-debugger-extensions.md @@ -0,0 +1,80 @@ +--- +title: Storage Kernel Debugger Extensions +description: The storage kernel debugger extensions (storagekd) are used for debugging the storage drivers on Windows 8 and above operating system (OS) targets. +ms.assetid: 8EF83BC8-6ABB-496C-98A6-EF0298D78F76 +--- + +# Storage Kernel Debugger Extensions + + +The storage kernel debugger extensions (storagekd) are used for debugging the storage drivers on Windows 8 and above operating system (OS) targets. + +Extension commands that are useful for debugging storage drivers, via classpnp managed storage class drivers and Storport managed storage miniport drivers, can be found in **Storagekd.dll**. + +Please refer to [SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll)](scsi-miniport-extensions--scsikd-dll-and-minipkd-dll-.md) for debugging needs for Windows 7 and below version of OS targets. + +**Important**  You need special symbols to use this extension. For more information, see [Debugging Tools for Windows](index.md). + +  + +## Storage kernel debugger extension commands + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription

[!storagekd.storhelp](-storagekd-storhelp.md)

Displays help text for Storagekd.dll extension commands.

[!storagekd.storclass](-storagekd-storclass.md)

Displays information about the specified classpnp device.

[!storagekd.storadapter](-storagekd-storadapter.md)

Displays information about the specified Storport adapter.

[!storagekd.storunit](-storagekd-storunit.md)

Displays information about the specified Storport logical unit.

[!storagekd.storloglist](-storagekd-storloglist.md)

Displays the Storport adapter’s internal log entries.

[!storagekd.storlogirp](-storagekd-storlogirp.md)

Displays the Storport’s internal log entries for the adapter filtered for the IRP provided.

[!storagekd.storlogsrb](-storagekd-storlogsrb.md)

Displays the Storport’s internal log entries for the adapter filtered for the Storage (or SCSI) Request Block (SRB) provided.

[!storagekd.storsrb](-storagekd-storsrb.md)

Displays information about the specified Storage (or SCSI) Request Block (SRB).

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Storage%20Kernel%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/string-wildcard-syntax.md b/windows-driver-docs-pr/debugger/string-wildcard-syntax.md new file mode 100644 index 0000000000..945d18ee9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/string-wildcard-syntax.md @@ -0,0 +1,45 @@ +--- +title: String Wildcard Syntax +description: This topic covers string wildcard syntax. Some debugger commands have string parameters that accept a variety of wildcard characters. +ms.assetid: 11e73f81-5d5c-4d9a-8380-ec767b27f603 +keywords: string wildcards, expressions, regular expressions, syntax rules for commands +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# String Wildcard Syntax + + +## + + +Some debugger commands have string parameters that accept a variety of wildcard characters. These parameters are noted on their respective reference pages. + +These kinds of parameters support the following syntax features: + +- An asterisk (\*) represents zero or more characters. + +- A question mark (?) represents any single character. + +- Brackets ( \[ \] ) that contain a list of characters represent any single character in the list. Exactly one character in the list is matched. Within these brackets, you can use a hyphen (-) to specify a range. For example, **Prog\[er-t7\]am** matches "Progeam", "Program", "Progsam", "Progtam", and "Prog7am". + +- A number sign (\#) represents zero or more of the preceding characters. For example, **Lo\#p** matches "Lp", "Lop", "Loop", "Looop", and so on. You can also combine a number sign with brackets, so **m\[ia\]\#n** matches "mn", "min", "man", "maan", "main", "mian", "miin", "miain", and so on. + +- A plus sign (+) represents one or more of the preceding characters. For example, **Lo+p** is the same as **Lo\#p**, except that **Lo+p** does not match "Lp". Similarly, **m\[ia\]+n** is the same as **m\[ia\]\#n**, except that m**\[ia\]+n** does not match "mn". **a?+b** is also the same as **a\*b**, except that **a?+b** does not match "ab". + +- If you have to specify a literal number sign (\#), question mark (?), opening bracket (\[), closing bracket (\]), asterisk (\*), or plus sign (+) character, you must add a backslash ( \\ ) in front of the character. Hyphens are always literal when you do not enclose them in brackets. But you cannot specify a literal hyphen within a bracketed list. + +Parameters that specify symbols also support some additional features. In addition to the standard string wildcard characters, you can use an underscore (\_) before a text expression that you use to specify a symbol. When matching this expression to a symbol, the debugger treats the underscore as any quantity of underscores, even zero. This feature applies only when you are matching symbols. It does not apply to string wildcard expressions in general. For more information about symbol syntax, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20String%20Wildcard%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md new file mode 100644 index 0000000000..8fc0c2bc59 --- /dev/null +++ b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-10.md @@ -0,0 +1,477 @@ +--- +title: Supported Ethernet NICs for Network Kernel Debugging in Windows 10 +description: You can do kernel debugging over an Ethernet network cable when the target computer is running Windows. The target computer must have a supported network interface card (NIC) or network adapter. +ms.assetid: F98A7ACE-DD04-423C-A438-89E21363C693 +--- + +# Supported Ethernet NICs for Network Kernel Debugging in Windows 10 + + +You can do kernel debugging over an Ethernet network cable when the target computer is running Windows. The target computer must have a supported network interface card (NIC) or network adapter. + +During kernel debugging, the computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. To do [kernel debugging over a network cable](setting-up-a-network-debugging-connection.md), the target computer must have a supported network adapter. When the target computer is running Windows, the network adapters listed here are supported for kernel debugging. + +**Note**   +The list of supported adapters is for the following versions of Windows + +- Windows 10, version 1703 +- Windows Server 2016 + +  + +## Finding the vendor ID and device ID + + +First find the vendor ID and device ID of the network adapter on your target computer. + +- On the target computer, open Device Manager (enter **devmgmt** in a Command Prompt window). +- In Device Manager, locate the network adapter that you want to use for debugging. +- Right click the network adapter node, and choose **Properties**. +- In the **Details** tab, under **Property**, select **Hardware Ids**. + +The vendor and device IDs are shown as VEN\_*VendorID* and DEV\_*DeviceID*. For example, if you see PCI\\VEN\_8086&DEV\_104B, the vendor ID is 8086, and the device ID is 104B. + +## Vendor ID 8086, Intel Corporation + + +For vendor ID 8086, these device IDs are supported: + +0001 +0008 +000C +000D +0438 +043A +043C +0440 +0470 +1000 +1001 +1004 +1008 +1009 +100C +100D +100E +100F +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +101A +101D +101E +1026 +1027 +1028 +1049 +104A +104B +104C +104D +105E +105F +1060 +1071 +1075 +1076 +1077 +1078 +1079 +107A +107B +107C +107D +107E +107F +108A +108B +108C +1096 +1098 +1099 +109A +10A4 +10A5 +10A7 +10A9 +10B5 +10B9 +10BA +10BB +10BC +10BD +10BF +10C0 +10C2 +10C3 +10C4 +10C5 +10C6 +10C7 +10C8 +10C9 +10CB +10CC +10CD +10CE +10D3 +10D5 +10D6 +10D9 +10DA +10DB +10DD +10DE +10DF +10E1 +10E5 +10E6 +10E7 +10E8 +10EA +10EB +10EC +10EF +10F0 +10F1 +10F4 +10F5 +10F6 +10F7 +10F8 +10F9 +10FB +10FC +11A9 +1501 +1502 +1503 +1507 +150A +150B +150C +150D +150E +150F +1510 +1511 +1514 +1516 +1517 +1518 +151C +1521 +1522 +1523 +1524 +1525 +1526 +1527 +1528 +1529 +152A +1533 +1534 +1535 +1536 +1537 +1538 +1539 +153A +153B +1546 +154A +154D +1557 +1558 +1559 +155A +1560 +1563 +156F +1570 +157B +157C +15A0 +15A1 +15A2 +15A3 +15AA +15AB +15AC +15AD +15AE +15B7 +15B8 +17D0 +1F40 +1F41 +1F45 +1F63 +1F72 +211B +2159 +294C +8976 +## Vendor ID 10EC, Realtek Semiconductor Corp. + + +For vendor ID 10EC, these device IDs are supported: + +8136 +8137 +8166 +8167 +8168 +8169 +## Vendor ID 14E4, Broadcom + + +For vendor ID 14E4, these device IDs are supported: + +1600 +1601 +1639 +163A +163B +163C +163D +163E +1641 +1642 +1643 +1644 +1645 +1646 +1647 +1648 +164A +164C +164D +164E +164F +1650 +1653 +1654 +1655 +1656 +1657 +1659 +165A +165B +165C +165D +165E +165F +1662 +1663 +1665 +1668 +1669 +166A +166B +166D +166E +1672 +1673 +1674 +1676 +1677 +1678 +1679 +167A +167B +167C +167D +167F +168A +168D +168E +1680 +1681 +1682 +1683 +1684 +1686 +1687 +1688 +1690 +1691 +1692 +1693 +1694 +1696 +1698 +1699 +169A +169B +169D +16A0 +16A1 +16A2 +16A4 +16A5 +16A6 +16A7 +16A8 +16AA +16AC +16AE +16B0 +16B1 +16B2 +16B3 +16B4 +16B5 +16B6 +16B7 +16C6 +16C7 +16DD +16F7 +16FD +16FE +16FF +170D +170E +170F +## Vendor ID 1969, Atheros Communications + + +For vendor ID 1969, these device IDs are supported: + +1062 +1063 +1073 +1083 +1090 +1091 +10A0 +10A1 +10B0 +10B1 +10C0 +10C1 +10D0 +10D1 +10E0 +10E1 +10F0 +10F1 +2060 +2062 +E091 +E0A1 +E0B1 +E0C1 +E0D1 +E0E1 +E0F1 +## Vendor ID 19A2, ServerEngines (Emulex) + + +For vendor ID 19A2, these device IDs are supported: + +0211 +0215 +0221 +0700 +0710 +## Vendor ID 10DF, Emulex Corporation + + +For vendor ID 10DF, these device IDs are supported: + +0720 +E220 +## Vendor ID 15B3, Mellanox Technology + + +For vendor ID 15B3, these device IDs are supported: + +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +100A +100B +100C +100D +100E +100F +1010 +1013 +1015 +1017 +1019 +101B +101D +101F +1021 +1023 +1025 +1027 +1029 +102B +102F +6340 +6341 +634A +634B +6354 +6368 +6369 +6372 +6732 +6733 +673C +673D +6746 +6750 +6751 +675A +6764 +6765 +676E +6778 + +## Vendor ID 1137, Cisco Systems Inc + + +For vendor ID 1137, these device IDs are supported: + +0043 +## Related topics + + +[Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) + +[Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Supported%20Ethernet%20NICs%20for%20Network%20Kernel%20Debugging%20in%20Windows%2010%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md new file mode 100644 index 0000000000..bf55a04eac --- /dev/null +++ b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md @@ -0,0 +1,407 @@ +--- +title: Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1 +description: You can do kernel debugging over an Ethernet network cable when the target computer is running Windows 8.1. The target computer must have a supported network interface card (NIC) or network adapter. +ms.assetid: C608A406-C008-4075-B6BE-C14CFFC3A820 +--- + +# Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1 + + +You can do kernel debugging over an Ethernet network cable when the target computer is running Windows 8.1. The target computer must have a supported network interface card (NIC) or network adapter. + +During kernel debugging, the computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. To do [kernel debugging over a network cable](setting-up-a-network-debugging-connection.md), the target computer must have a supported network adapter. When the target computer is running Windows 8.1, the network adapters listed here are supported for kernel debugging. + +**Note**  Support for kernel debugging over selected 10 gigabit network adapters is a new feature in Windows 8.1. Debugging over 10 gigabit network adapters is not supported in Windows 8. For a list of network adapters supported by Windows 8 for kernel debugging, see [Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md). + +  + +## System Requirements + + +Kernel debugging through Ethernet NICs requires certain low-level platform support. Windows requires that these NICs be attached via PCI/PCIe for this debugging solution. In most cases, simply plugging in one of these supported NICs will allow a robust kernel debugging experience. However, there may be cases where BIOS configuration details hinder the Windows debug path. The following platform requirement should be considered: + +- System firmware should discover and configure the NIC device such that its resources do not conflict with any other devices that have been BIOS-configured. + +## Finding the vendor ID and device ID + + +First find the vendor ID and device ID of the network adapter on your target computer. + +- On the target computer, open Device Manager (enter **devmgmt** in a Command Prompt window). +- In Device Manager, locate the network adapter that you want to use for debugging. +- Right click the network adapter node, and choose **Properties**. +- In the **Details** tab, under **Property**, select **Hardware Ids**. + +The vendor and device IDs are shown as VEN\_*VendorID* and DEV\_*DeviceID*. For example, if you see PCI\\VEN\_8086&DEV\_104B, the vendor ID is 8086, and the device ID is 104B. + +## Vendor ID 8086, Intel Corporation + + +For vendor ID 8086, these device IDs are supported: + +0438 +043A +043C +0440 +1000 +1001 +1004 +1008 +1009 +100C +100D +100E +100F +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +101A +101D +101E +1026 +1027 +1028 +1049 +104A +104B +104C +104D +105E +105F +1060 +1075 +1076 +1077 +1078 +1079 +107A +107B +107C +107D +107E +107F +108A +108B +108C +1096 +1098 +1099 +109A +10A4 +10A5 +10A7 +10A9 +10B5 +10B9 +10BA +10BB +10BC +10BD +10BF +10C0 +10C2 +10C3 +10C4 +10C5 +10C6 +10C7 +10C8 +10C9 +10CB +10CC +10CD +10CE +10D3 +10D5 +10D6 +10D9 +10DA +10DB +10DD +10DE +10DF +10E1 +10E5 +10E6 +10E7 +10E8 +10EA +10EB +10EC +10EF +10F0 +10F1 +10F4 +10F5 +10F6 +10F7 +10F8 +10F9 +10FA +10FB +10FC +1501 +1502 +1503 +1507 +150A +150B +150C +150D +150E +150F +1510 +1511 +1514 +1516 +1517 +1518 +151C +1521 +1522 +1523 +1524 +1525 +1526 +1527 +1528 +1529 +152A +1533 +1534 +1535 +1536 +1537 +1538 +1539 +153A +153B +1546 +154A +154D +1557 +1558 +1559 +155A +1560 +157B +157C +1F40 +1F41 +1F45 +294C +## Vendor ID 10EC, Realtek Semiconductor Corp. + + +For vendor ID 10EC, these device IDs are supported: + +8136 +8137 +8167 +8168 +8169 +## Vendor ID 14E4, Broadcom + + +For vendor ID 14E4, these device IDs are supported: + +1600 +1601 +1639 +163A +163B +163C +1644 +1645 +1646 +1647 +1648 +164A +164C +164D +1653 +1654 +1655 +1656 +1657 +1658 +1659 +165A +165B +165C +165D +165E +165F +1668 +1669 +166A +166B +166D +166E +1672 +1673 +1674 +1676 +1677 +1678 +1679 +167A +167B +167C +167D +167F +1680 +1681 +1684 +1688 +1690 +1691 +1692 +1693 +1694 +1696 +1698 +1699 +169A +169B +169D +16A0 +16A6 +16A7 +16A8 +16AA +16AC +16B0 +16B1 +16B2 +16B4 +16B5 +16B6 +16C6 +16C7 +16DD +16F7 +16FD +16FE +16FF +170D +170E +170F +## Vendor ID 1969, Atheros Communications + + +For vendor ID 1969, these device IDs are supported: + +1062 +1063 +1073 +1083 +1090 +1091 +10A0 +10A1 +10B0 +10B1 +10C0 +10C1 +10D0 +10D1 +10E0 +10E1 +10F0 +10F1 +2060 +2062 +E091 +E0A1 +E0B1 +E0C1 +E0D1 +E0E1 +E0F1 +## Vendor ID 19A2, ServerEngines (Emulex) + + +For vendor ID 19A2, these device IDs are supported: + +0211 +0215 +0221 +0700 +0710 +## Vendor ID 10DF, Emulex Corporation + + +For vendor ID 10DF, these device IDs are supported: + +0720 +E220 +## Vendor ID 15B3, Mellanox Technology + + +For vendor ID 15B3, these device IDs are supported: + +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +100A +100B +100C +100D +100E +100F +1010 +6340 +6341 +634A +634B +6354 +6368 +6369 +6372 +6732 +6733 +673C +673D +6746 +6750 +6751 +675A +6764 +6765 +676E +6778 + +## Related topics + + +[Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) + +[Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Supported%20Ethernet%20NICs%20for%20Network%20Kernel%20Debugging%20in%20Windows%208.1%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md new file mode 100644 index 0000000000..700fa91e45 --- /dev/null +++ b/windows-driver-docs-pr/debugger/supported-ethernet-nics-for-network-kernel-debugging-in-windows-8.md @@ -0,0 +1,290 @@ +--- +title: Supported Ethernet NICs for Network Kernel Debugging in Windows 8 +description: You can do kernel debugging over an Ethernet network cable when the target computer is running Windows 8. The target computer must have a supported network interface card (NIC) or network adapter. +ms.assetid: 92FEEBAF-9978-4BDE-BB4F-81454D84A7E7 +--- + +# Supported Ethernet NICs for Network Kernel Debugging in Windows 8 + + +You can do kernel debugging over an Ethernet network cable when the target computer is running Windows 8. The target computer must have a supported network interface card (NIC) or network adapter. + +During kernel debugging, the computer that runs the debugger is called the *host computer*, and the computer being debugged is called the *target computer*. To do [kernel debugging over a network cable](setting-up-a-network-debugging-connection.md), the target computer must have a supported network adapter. When the target computer is running Windows 8, the network adapters listed here are supported for kernel debugging. + +**Note**  For a list of network adapters supported by Windows 8.1 for kernel debugging, see [Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md). + +  + +## System Requirements + + +Kernel debugging through Ethernet NICs requires certain low-level platform support. Windows requires that these NICs be attached via PCI/PCIe for this debugging solution. In most cases, simply plugging in one of these supported NICs will allow a robust kernel debugging experience. However, there may be cases where BIOS configuration details hinder the Windows debug path. The following set of platform requirements should be considered: + +- System firmware should discover and configure the NIC device such that its resources do not conflict with any other devices that have been BIOS-configured. +- System firmware should place the NIC’s resources under address windows that are not marked prefetchable. + +## Finding the vendor ID and device ID + + +First find the vendor ID and device ID of the network adapter on your target computer. + +- On the target computer, open Device Manager (enter **devmgmt** in a Command Prompt window). +- In Device Manager, locate the network adapter that you want to use for debugging. +- Right click the network adapter node, and choose **Properties**. +- In the **Details** tab, under **Property**, select **Hardware Ids**. + +The vendor and device IDs are shown as VEN\_*VendorID* and DEV\_*DeviceID*. For example, if you see PCI\\VEN\_8086&DEV\_104B, the vendor ID is 8086, and the device ID is 104B. + +## Vendor ID 8086, Intel Corporation + + +For vendor ID 8086, these device IDs are supported: + +1000 +1001 +1004 +1008 +1009 +100C +100D +100E +100F +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +101A +101D +101E +1026 +1027 +1028 +1049 +104A +104B +104C +104D +105E +105F +1060 +1075 +1076 +1077 +1078 +1079 +107A +107B +107C +107D +107E +107F +108A +108B +108C +1096 +1098 +1099 +109A +10A4 +10A5 +10A7 +10A9 +10B5 +10B9 +10BA +10BB +10BC +10BD +10BF +10C9 +10CB +10CC +10CD +10CE +10D3 +10D5 +10D6 +10D9 +10DA +10E5 +10E6 +10E7 +10E8 +10EA +10EB +10EF +10F0 +10F5 +10F6 +1501 +1502 +1503 +150A +150C +150D +150E +150F +1510 +1511 +1516 +1518 +1521 +1522 +1523 +1524 +1526 +294C +## Vendor ID 10EC, Realtek Semiconductor Corp. + + +For vendor ID 10EC, these device IDs are supported: + +8136 +8137 +8167 +8168 +8169 +## Vendor ID 14E4, Broadcom + + +For vendor ID 14E4, these device IDs are supported: + +1600 +1601 +1639 +163A +163B +163C +1644 +1645 +1646 +1647 +1648 +164A +164C +164D +1653 +1654 +1655 +1656 +1657 +1658 +1659 +165A +165B +165C +165D +165E +165F +1668 +1669 +166A +166B +166D +166E +1672 +1673 +1674 +1676 +1677 +1678 +1679 +167A +167B +167C +167D +167F +1680 +1681 +1684 +1688 +1690 +1691 +1692 +1693 +1694 +1696 +1698 +1699 +169A +169B +169D +16A0 +16A6 +16A7 +16A8 +16AA +16AC +16B0 +16B1 +16B2 +16B4 +16B5 +16B6 +16C6 +16C7 +16DD +16F7 +16FD +16FE +16FF +170D +170E +170F +## Vendor ID 1969, Atheros Communications + + +Support for Atheros network adapters is provided by a separate module that is available from Qualcomm. These device IDs are supported. + +1062 +1063 +1073 +1083 +1090 +1091 +10A0 +10A1 +10B0 +10B1 +10C0 +10C1 +10D0 +10D1 +10E0 +10E1 +10F0 +10F1 +2060 +2062 +E091 +E0A1 +E0B1 +E0C1 +E0D1 +E0E1 +E0F1 +## Related topics + + +[Setting Up Kernel-Mode Debugging over a Network Cable in Visual Studio](setting-up-a-network-debugging-connection-in-visual-studio.md) + +[Setting Up Kernel-Mode Debugging over a Network Cable Manually](setting-up-a-network-debugging-connection.md) + +[Supported Ethernet NICs for Network Kernel Debugging in Windows 8.1](supported-ethernet-nics-for-network-kernel-debugging-in-windows-8-1.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Supported%20Ethernet%20NICs%20for%20Network%20Kernel%20Debugging%20in%20Windows%208%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/switching-modes.md b/windows-driver-docs-pr/debugger/switching-modes.md new file mode 100644 index 0000000000..1673724ee0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/switching-modes.md @@ -0,0 +1,63 @@ +--- +title: Switching Modes +description: Switching Modes +ms.assetid: 167e5352-4ebc-423d-bf4f-ba1d459b394f +--- + +# Switching Modes + + +## + + +When you [control user-mode debugging from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md), you encounter four different modes, and can switch between them in a variety of ways. + +**Note**   In describing this scenario, *target application* refers to the user-mode application that is being debugged, *target computer* refers to the computer that contains the target application and the CDB or NTSD process, and *host computer* refers to the computer that contains the kernel debugger. + +  + +The following four modes will be encountered: + +*User-mode debugging* +The target computer and target application are frozen. The user-mode debugging prompt appears in the [Debugger Command window](debugger-command-window.md) of the kernel debugger. In WinDbg, the prompt in the lower panel of the WinDbg window displays Input>. You can enter commands at this prompt, as if they are entered during user-mode debugging, to analyze the target application's state or cause it to run or step through its execution. Symbol files, extension DLLs, and other files that the debugger accesses will be those files on the target computer, not the host computer. + +*Target application execution* +The target computer is running, the target application is running, and the debugger is waiting. This mode is the same as letting the target run in ordinary debugging. + +*Sleep mode* +The target computer is running, but the target application is frozen, and both debuggers are frozen. This mode is useful if you have to do something on the target computer but you do not want to change the state of the debugging session. + +*Kernel-mode debugging* +The target computer and the target application are frozen. The kernel-mode debugging prompt kd> appears in the Debugger Command window of the kernel debugger. This mode is the typical kernel-mode debugging state. + +The session begins in user-mode debugging mode. The following actions and events cause the mode to change: + +- To switch from user-mode debugging to target application execution, use the [**g (Go)**](g--go-.md) command at the `Input>` prompt. + +- To temporarily switch from user-mode debugging to target application execution and then return to user-mode debugging, use a step, trace, or other temporary execution command. For a list of such commands, see [Controlling the Target](controlling-the-target.md). + +- To switch from user-mode debugging to sleep mode, use the [**.sleep (Pause Debugger)**](-sleep--pause-debugger-.md) command. This command is timed. When the time expires, the system returns to user-mode debugging. + +- To switch from user-mode debugging to kernel-mode debugging, use the [**.breakin (Break to the Kernel Debugger)**](-breakin--break-to-the-kernel-debugger-.md) command. Note that **.breakin** might fail with an access denied error if the calling process does not have administrator rights. In this case, switch to KD by issuing a short **.sleep** command and pressing CTRL+C. + +- You can switch from target application execution to user-mode debugging only in certain environments. If the target computer is running Microsoft Windows XP or a later version of the Windows operating system, you can use the [**!bpid**](-bpid.md) extension command. If you are using CDB (not NTSD), you can activate the CDB window on the target computer and press CTRL+C. + +- If the target application hits a breakpoint, encounters an exception, encounters some other controlled event, or ends, the system switches from target application execution to user-mode debugging. You should plan such events in advance, especially when you are using NTSD. For more information about these events, see [Using Breakpoints](using-breakpoints2.md) and [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +- To switch from target application execution to kernel-mode debugging, press CTRL+C in the KD window, press CTRL+BREAK or click **Break** on the **Debug** menu in the WinDbg window, or press SYSRQ or ALT+SYSRQ on the target computer keyboard. (If your kernel debugger is KD and if you press CTRL+C at the same time that the kernel debugger is communicating with the user-mode debugger, the user-mode debugger might capture you pressing CTRL+C.) + +- If the debugger encounters a kernel error or if you use the Breakin.exe tool, the system switches from target application execution to kernel-mode debugging. + +- To switch from sleep mode to user-mode debugging, wait for the sleep time to expire, start a new CDB process on the target computer by using the -wake [**command-line option**](cdb-command-line-options.md), or use the [**.wake (Wake Debugger)**](-wake--wake-debugger-.md) command in a different copy of CDB or NTSD on the target computer. + +- To switch out of kernel-mode debugging, use the [**g (Go)**](g--go-.md) command at the `kd>` prompt. This command returns to user-mode debugging or target application execution (whichever of the two was the most recently-used state). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Switching%20Modes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md b/windows-driver-docs-pr/debugger/sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md new file mode 100644 index 0000000000..08a7f64e12 --- /dev/null +++ b/windows-driver-docs-pr/debugger/sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-.md @@ -0,0 +1,197 @@ +--- +title: sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions) +description: The sx* commands control the action that the debugger takes when an exception occurs in the application that is being debugged, or when certain events occur. +ms.assetid: fdb5059f-e7d9-4e14-aa3d-030e72c30732 +keywords: ["sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions) +api_type: +- NA +--- + +# sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions) + + +The **sx***\** commands control the action that the debugger takes when an exception occurs in the application that is being debugged, or when certain events occur. + +``` +sx + +sx{e|d|i|n} [-c "Cmd1"] [-c2 "Cmd2"] [-h] {Exception|Event|*} + +sx- [-c "Cmd1"] [-c2 "Cmd2"] {Exception|Event|*} + +sxr +``` + +## Parameters + + +**-c "***Cmd1***"** +Specifies a command that is executed if the exception or event occurs. This command is executed when the first chance to handle this exception occurs, regardless of whether this exception breaks into the debugger. You must enclose the *Cmd1* string in quotation marks. This string can include multiple commands, separated by semicolons. The space between the -c and the quoted command string is optional. + +**-c2"***Cmd2***"** +Specifies a command that is executed if the exception or event occurs and is not handled on the first chance. This command is executed when the second chance to handle this exception occurs, regardless of whether this exception breaks into the debugger. You must enclose the *Cmd2* string in quotation marks. This string can include multiple commands, separated by semicolons. The space between the -c2 and the quoted command string is optional. + + **-h** +Changes the specified event's handling status instead of its break status. If *Event* is **cc**, **hc**, **bpec**, or **ssec**, you do not have to use the **-h** option. + + *Exception* +Specifies the exception number that the command acts on, in the current radix. + + *Event* +Specifies the event that the command acts on. These events are identified by short abbreviations. For a list of the events, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + + **\*** +Affects all exceptions that are not otherwise explicitly named for **sx**. For a list of explicitly named exceptions, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about break status and handling status, descriptions of all event codes, a list of the default status for all events, and other methods of controlling this status, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + +Remarks +------- + +The **sx** command displays the list of exceptions for the current process and the list of all nonexception events and displays the default behavior of the debugger for each exception and event. + +The **sxe**, **sxd**, **sxn**, and **sxi** commands control the debugger settings for each exception and event. + +The **sxr** command resets all of the exception and event filter states to the default settings. Commands are cleared, break and continue options are reset to their default settings, and so on. + +The **sx-** command does not change the handling status or the break status of the specified exception or event. This command can be used if you wish to change the first-chance command or second-chance command associated with a specific event, but do not wish to change anything else. + +If you include the **-h** option (or if the **cc**, **hc**, **bpec**, or **ssec** events are specified), the **sxe**, **sxd**, **sxn**, and **sxi** commands control the [handling status](https://msdn.microsoft.com/library/windows/hardware/ff541490#handling-status) of the exception or event. In all other cases, these commands control the [break status](https://msdn.microsoft.com/library/windows/hardware/ff541490#break-status) of the exception or event. + +When you are setting the break status, these commands have the following effects. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandStatus nameDescription

sxe

Break

+

(Enabled)

When this exception occurs, the target immediately breaks into the debugger before any other error handlers are activated. This kind of handling is called first chance handling.

sxd

Second chance break

+

(Disabled)

The debugger does not break for a first-chance exception of this type (although a message is displayed). If other error handlers do not address this exception, execution stops and the target breaks into the debugger. This kind of handling is called second chance handling.

sxn

Output

+

(Notify)

When this exception occurs, the target application does not break into the debugger at all. However, a message is displayed that notifies the user of this exception.

sxi

Ignore

When this exception occurs, the target application does not break into the debugger at all, and no message is displayed.

+ +  + +When you are setting the handling status, these commands have the following effects: + + +++++ + + + + + + + + + + + + + + + + + + + +
CommandStatus nameDescription

sxe

Handled

The event is considered handled when execution resumes.

sxd,sxn,sxi

Not Handled

The event is considered not handled when execution resumes.

+ +  + +You can use the **-h** option together with exceptions, not events. Using this option with **ch**, **bpe**, or **sse** sets the handling status for **hc**, **bpec**, or **ssec**, respectively. If you use the -h option with any other event, it has no effect. + +Using the **-c** or **-c2** options with **hc**, **bpec**, or **ssec** associates the specified commands with **ch**, **bpe**, or **sse**, respectively. + +In the following example, the **sxe** command is used to set the break status of access violation events to break on the first chance, and to set the first-chance command that will be executed at that point to **r eax**. Then the **sx-** command is used to alter the first-chance command to **r ebx**, without changing the handling status. Finally, a portion of the **sx** output is shown, indicating the current settings for access violation events: + +``` +0:000> sxe -c "r eax" av + +0:000> sx- -c "r ebx" av + +0:000> sx + av - Access violation - break - not handled + Command: "r ebx" + . . . +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20sx,%20sxd,%20sxe,%20sxi,%20sxn,%20sxr,%20sx-%20%28Set%20Exceptions%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-options.md b/windows-driver-docs-pr/debugger/symbol-options.md new file mode 100644 index 0000000000..65cd5288b0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-options.md @@ -0,0 +1,372 @@ +--- +title: Symbol Options +description: Symbol Options +ms.assetid: 4a501ea3-431c-4c11-8826-154eb8799a64 +keywords: ["symbols, setting symbol options", "symbols, SYMOPT_XXXX", "noisy symbol loading", "CV record"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Options + + +## + + +A number of options are available to control how symbols are loaded and used. These options can be set in a variety of ways. + +The following table lists these symbol options: + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagOption NameDefault in debuggerDefault in DBH

0x1

[SYMOPT_CASE_INSENSITIVE](#symopt-case-insensitive)

On

On

0x2

[SYMOPT_UNDNAME](#symopt-undname)

On

On

0x4

[SYMOPT_DEFERRED_LOADS](#symopt-deferred-loads)

On

Off

0x8

[SYMOPT_NO_CPP](#symopt-no-cpp)

Off

Off

0x10

[SYMOPT_LOAD_LINES](#symopt-load-lines)

Off in KD and CDB

+

On in WinDbg

On

0x20

[SYMOPT_OMAP_FIND_NEAREST](#symopt-omap-find-nearest)

On

Off

0x40

[SYMOPT_LOAD_ANYTHING](#symopt-load-anything)

Off

Off

0x80

[SYMOPT_IGNORE_CVREC](#symopt-ignore-cvrec)

Off

Off

0x100

[SYMOPT_NO_UNQUALIFIED_LOADS](#symopt-no-unqualified-loads)

Off

Off

0x200

[SYMOPT_FAIL_CRITICAL_ERRORS](#symopt-fail-critical-errors)

On

Off

0x400

[SYMOPT_EXACT_SYMBOLS](#symopt-exact-symbols)

Off

On

0x800

[SYMOPT_ALLOW_ABSOLUTE_SYMBOLS](#symopt-allow-absolute-symbols)

Off

On

0x1000

[SYMOPT_IGNORE_NT_SYMPATH](#symopt-ignore-nt-sympath)

Off

Off

0x2000

SYMOPT_INCLUDE_32BIT_MODULES

Off

Off

0x4000

[SYMOPT_PUBLICS_ONLY](#symopt-publics-only)

Off

Off

0x8000

[SYMOPT_NO_PUBLICS](#symopt-no-publics)

Off

Off

0x10000

[SYMOPT_AUTO_PUBLICS](#symopt-auto-publics)

On

On

0x20000

[SYMOPT_NO_IMAGE_SEARCH](#symopt-no-image-search)

On

Off

0x40000

[SYMOPT_SECURE](#symopt-secure)

Off

Off

0x80000

[SYMOPT_NO_PROMPTS](#symopt-no-prompts)

On in KD and CDB

+

Off in WinDbg

Off

0x80000000

[SYMOPT_DEBUG](#symopt-debug)

Off

Off

+ +  + +### Changing the Symbol Option Settings + +The [**.symopt (Set Symbol Options)**](-symopt--set-symbol-options-.md) command can be used to change or display the symbol option settings. In addition, a number of command-line parameters and commands are available to change these settings; these are listed in the individual SYMOPT\_*XXX* sections. + +You can also control all the settings at once with the **-sflags**[command-line option](command-line-options.md). This option can be followed with a decimal number, or with a hexadecimal number prefixed by **0x**. It is recommended that you use hexadecimal, since the symbol flags are aligned properly that way. Be cautious in using this method, since it sets the entire bitfield and will override all the symbol handler defaults. For example, **-sflags 0x401** will not only turn on SYMOPT\_EXACT\_SYMBOLS and SYMOPT\_CASE\_INSENSITIVE, but will also turn off all the other options that normally are on by default! + +The default value for the total flag bits is 0x30237 in WinDbg, 0xB0227 in CDB and KD, and 0x10C13 in [the DBH tool](dbh.md), when these programs are launched without any symbol-related command line options. + +### SYMOPT\_CASE\_INSENSITIVE + +This symbol option causes all searches for symbol names to be case-insensitive. + +This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x1** or .symopt-0x1, respectively. + +This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +1 or symopt -1, respectively. + +### SYMOPT\_UNDNAME + +This symbol option causes public symbol names to be undecorated when they are displayed, and causes searches for symbol names to ignore symbol decorations. Private symbol names are never decorated, regardless of whether this option is active. For information on symbol name decorations, see [Public and Private Symbols](public-and-private-symbols.md). + +This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x2** or .symopt-0x2, respectively. + +This option is on by default in DBH. It is turned off if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +2 or symopt -2, respectively. + +### SYMOPT\_DEFERRED\_LOADS + +This symbol option is called *deferred symbol loading* or *lazy symbol loading*. When it is active, symbols are not actually loaded when the target modules are loaded. Instead, symbols are loaded by the debugger as they are needed. See [Deferred Symbol Loading](deferred-symbol-loading.md) for details. + +This option is on by default in all debuggers. In CDB and KD, the -s command-line option will turn this option off. It can also be turned off in CDB by using the **LazyLoad** variable in the [tools.ini](configuring-tools-ini.md) file. Once the debugger is running, this option can be turned on or off by using **.symopt+0x4** or .symopt-0x4, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +4 or symopt -4, respectively. + +### SYMOPT\_NO\_CPP + +This symbol option turns off C++ translation. When this symbol option is set, **::** is replaced by **\_\_** in all symbols. + +This option is off by default in all debuggers. It can be activated by using the -snc command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x8** or .symopt-0x8, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +8 or symopt -8, respectively. + +### SYMOPT\_LOAD\_LINES + +This symbol option allows line number information to be read from source files. This option must be on for source debugging to work correctly. + +In KD and CDB, this option is off by default; in WinDbg, this option is on by default. In CDB and KD, the -lines command-line option will turn this option on. Once the debugger is running, it can be turned on or off by using **.symopt+0x10** or .symopt-0x10, respectively. It can also be toggled on and off by using the [**.lines (Toggle Source Line Support)**](-lines--toggle-source-line-support-.md) command. + +This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +10 or symopt -10, respectively. + +### SYMOPT\_OMAP\_FIND\_NEAREST + +When code has been optimized and there is no symbol at the expected location, this option causes the nearest symbol to be used instead. + +This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x20** or .symopt-0x20, respectively. + +This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +20 or symopt -20, respectively. + +### SYMOPT\_LOAD\_ANYTHING + +This symbol option reduces the pickiness of the symbol handler when it is attempting to match symbols. + +This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x40** or .symopt-0x40, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +40 or symopt -40, respectively. + +### SYMOPT\_IGNORE\_CVREC + +This symbol option causes the symbol handler to ignore the CV record in the loaded image header when searching for symbols. + +This option is off by default in all debuggers. It can be activated by using the -sicv command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x80** or .symopt-0x80, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +80 or symopt -80, respectively. + +### SYMOPT\_NO\_UNQUALIFIED\_LOADS + +This symbol option disables the symbol handler's automatic loading of modules. When this option is set and the debugger attempts to match a symbol, it will only search modules which have already been loaded. + +This option can be used as a defense against mistyping a symbol name. Normally, a mistyped symbol will cause the debugger to pause while it searches all unloaded symbol files. When this option is active, a mistyped symbol will not be found in the loaded modules, and then the search will terminate. + +This option is off by default in all debuggers. It can be activated by using the -snul command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x100** or .symopt-0x100, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +100 or symopt -100, respectively. + +### SYMOPT\_FAIL\_CRITICAL\_ERRORS + +This symbol option causes file access error dialog boxes to be suppressed. + +If this option is off, file access errors, such as "drive not ready", encountered during symbol loading, will result in dialog boxes appearing. If this option is on, these boxes are suppressed and all access errors receive a "fail" response. + +This option is on by default in all debuggers. It can be deactivated by using the -sdce command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x200** or .symopt-0x200, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +200 or symopt -200, respectively. + +### SYMOPT\_EXACT\_SYMBOLS + +This symbol option causes the debugger to perform a strict evaluation of all symbol files. + +When this option is on, even the slightest discrepancy between the symbol files and the symbol handler's expectations will cause the symbols to be ignored. + +This option is off by default in all debuggers. It can be activated by using the -ses command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x400** or .symopt-0x400, respectively. + +The -failinc command-line option also turns on SYMOPT\_EXACT\_SYMBOLS. In addition, if you are debugging a user-mode minidump or a kernel-mode minidump, -failinc will prevent the debugger from loading any modules whose images can't be mapped. + +This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +400 or symopt -400, respectively. + +### SYMOPT\_ALLOW\_ABSOLUTE\_SYMBOLS + +This symbol option allows DbgHelp to read symbols that are stored at an absolute address in memory. This option is not needed in the vast majority of cases. + +This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x800** or .symopt-0x800, respectively. + +This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +800 or symopt -800, respectively. + +### SYMOPT\_IGNORE\_NT\_SYMPATH + +This symbol option causes the debugger to ignore the environment variable settings for the symbol path and the executable image path. + +This option is off by default in all debuggers. It can be activated by using the -sins command-line option. However, it cannot be controlled by **.symopt** once the debugger is running, because the environment variables are only read at startup. + +This option is off by default in DBH, and is ignored by DBH in all cases. + +### SYMOPT\_PUBLICS\_ONLY + +This symbol option causes DbgHelp to ignore private symbol data, and search only the public symbol table for symbol information. This emulates the behavior of DbgHelp before support for these types was added. see [Public and Private Symbols](public-and-private-symbols.md). + +This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x4000** or .symopt-0x4000, respectively. + +This option is off by default in DBH. It is turned on if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +4000 or symopt -4000, respectively. + +### SYMOPT\_NO\_PUBLICS + +This symbol option prevents DbgHelp from searching the public symbol table. This can make symbol enumeration and symbol searches much faster. If you are concerned solely with search speed, the SYMOPT\_AUTO\_PUBLICS option is generally preferable to this one. For information on the public symbol table, see [Public and Private Symbols](public-and-private-symbols.md). + +This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x8000** or .symopt-0x8000, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +8000 or symopt -8000, respectively. + +### SYMOPT\_AUTO\_PUBLICS + +This symbol option causes DbgHelp to search the public symbol table in a .pdb file only as a last resort. If any matches are found when searching the private symbol data, the public symbols will not be searched. This improves symbol search speed. + +This option is on by default in all debuggers. It can be deactivated by using the -sup command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x10000** or .symopt-0x10000, respectively. + +This option is on by default in DBH. It is turned off if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +10000 or symopt -10000, respectively. + +### SYMOPT\_NO\_IMAGE\_SEARCH + +This symbol option prevents DbgHelp from searching the disk for a copy of the image when symbols are loaded. + +This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using **.symopt+0x20000** or .symopt-0x20000, respectively. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +20000 or symopt -20000, respectively. + +### SYMOPT\_SECURE + +(Kernel mode only) This symbol option indicates whether [Secure Mode](secure-mode.md) is active. + +Secure Mode is off by default in all debuggers. It can be activated by using the -secure command-line option. If the debugger is running, is in dormant mode, and has not established any Debugging Servers, Secure Mode can be turned on by using **.symopt+0x40000** or [**.secure (Activate Secure Mode)**](-secure--activate-secure-mode-.md). + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +40000 or symopt -40000, respectively. + +Secure mode can never be turned off once it has been activated. + +### SYMOPT\_NO\_PROMPTS + +This symbol option suppresses authentication dialog boxes from the proxy server. This may result in SymSrv being unable to access a symbol store on the internet. + +For details, see [Firewalls and Proxy Servers](firewalls-and-proxy-servers.md). + +In KD and CDB, this option is on by default; in WinDbg, this option is off by default. Once the debugger is running, it can be turned on or off by using **.symopt+0x80000** or .symopt-0x80000, respectively, followed by the [**.reload (Reload Module)**](-reload--reload-module-.md) command. It can also be turned on and off by using the [**!sym prompts off**](-sym.md) and **!sym prompts** extension commands, followed by the **.reload (Reload Module)** command. + +This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +80000 or symopt -80000, respectively. + +### + +### + +### -SYMOPT\_DEBUG + +This symbol option turns on *noisy symbol loading*. This instructs the debugger to display information about its search for symbols. + +The name of each symbol file will be displayed as it is loaded. If the debugger cannot load a symbol file, it will display an error message. Error messages for .pdb files will be displayed in text. Error messages for .dbg files will be in the form of an error code; these codes are explained in the winerror.h file. + +If an image file is loaded solely to recover symbolic header information, this will be displayed as well. + +This option is off by default in all debuggers. It can be activated by using the -n command-line option. Once the debugger is running, it can be turned on or off by using **.symopt+0x80000000** or .symopt-0x80000000, respectively. It can also be turned on and off by using the [**!sym noisy**](-sym.md) and **!sym quiet** extension commands. + +**Note**   This option should not be confused with noisy *source* loading -- that is controlled by the [**.srcnoisy (Noisy Source Loading)**](-srcnoisy--noisy-source-loading-.md) command. + +  + +This option is off by default in DBH. It can be activated by using the -n command-line option. Once DBH is running, it can be turned on or off by using symopt +80000000 or symopt -80000000, respectively. It can also be turned on and off by using the verbose on and verbose off commands. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-path.md b/windows-driver-docs-pr/debugger/symbol-path.md new file mode 100644 index 0000000000..8859e2edfa --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-path.md @@ -0,0 +1,148 @@ +--- +title: Symbol path for Windows debuggers +description: The symbol path specifies locations where the Windows debuggers (WinDbg, KD, CDB, NTST) look for symbol files. +ms.assetid: 705df98f-717f-40ad-a424-101826970691 +keywords: symbol files and paths, symbols, lazy symbol loading, deferred symbol loading, symbol path +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol path for Windows debuggers + + +The symbol path specifies locations where the Windows debuggers (WinDbg, KD, CDB, NTST) look for symbol files. For more information about symbols and symbol files, see [Symbols](symbols.md). + +Some compilers (such as Microsoft Visual Studio) put symbol files in the same directory as the binary files. The symbol files and the checked binary files contain path and file name information. This information frequently enables the debugger to find the symbol files automatically. If you are debugging a user-mode process on the computer where the executable was built, and if the symbol files are still in their original location, the debugger can locate the symbol files without you setting the symbol path. + +In most other situations, you have to set the symbol path to point to your symbol file locations. + +## Symbol Path Syntax + + +The debugger's symbol path is a string that consists of multiple directory paths, separated by semicolons. + +Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported. + +For each directory in the symbol path, the debugger looks in three directories. For example, if the symbol path includes the `c:\MyDir` directory, and the debugger is looking for symbol information for a DLL, the debugger first looks in `c:\MyDir\symbols\dll`, then in `c:\MyDir\dll`, and finally in `c:\MyDir`. The debugger then repeats this process for each directory in the symbol path. Finally, the debugger looks in the current directory and then in the current directory with `..\dll` appended to it. (The debugger appends `..\dll` , `..\exe` , or `..\sys` , depending on which binaries it is debugging.) + +Symbol files have date and time stamps. You do not have to worry that the debugger will use the wrong symbols that it may find first in this sequence. It always looks for the symbols that match the time stamp on the binary files that it is debugging. For more information about responses when symbols files are not available, see [Compensating for Symbol-Matching Problems](matching-symbol-names.md). + +One way to set the symbol path is by entering the [**.sympath**](-sympath--set-symbol-path-.md) command. For other ways to set the symbol path, see [Controlling the Symbol Path](#controlling-the-symbol-path) later in this topic. + +## Caching Symbols Locally + + +We strongly recommend that you always cache your symbols locally. One way to cache symbols locally is to include `cache*;` or `cache*localsymbolcache;*` in your symbol path. + +If you include the string `cache*;` in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to get symbols from the network share `\\someshare` and cache the symbols in the default location on the local computer. + +``` +.sympath cache*;\\someshare +``` + +If you include the string `cache*localsymbolcache;` in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the *localsymbolcache* directory. + +For example, the following command tells the debugger to obtain symbols from the network share `\\someshare` and cache the symbols in the `c:\MySymbols` directory. + +``` +.sympath cache*c:\MySymbols;\\someshare +``` + +## Using a Symbol Server + + +If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the `srv*`, `srv*symbolstore`, or `srv*localsymbolcache*symbolstore` string in your symbol path. + +If you include the string `srv*` in your symbol path, the debugger uses a symbol server to get symbols from the default symbol store. For example, the following command tells the debugger to use a symbol server to get symbols from the default symbol store. These symbols are not cached on the local computer. + +``` +.sympath srv* +``` + +If you include the string `srv*symbolstore` in your symbol path, the debugger uses a symbol server to get symbols from the *symbolstore* store. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols. These symbols are not cached on the local computer. + +``` +.sympath srv*https://msdl.microsoft.com/download/symbols +``` + +If you include the string `srv*localcache*symbolstore` in your symbol path, the debugger uses a symbol server to get symbols from the *symbolstore* store and caches them in the *localcache* directory. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols and cache the symbols in `c:\MyServerSymbols`. + +``` +.sympath srv*c:\MyServerSymbols*https://msdl.microsoft.com/download/symbols +``` + +If you have a directory on your computer where you manually place symbols, do not use that directory as the cache for symbols obtained from a symbol server. Instead, use two separate directories. For example, you can manually place symbols in `c:\MyRegularSymbols` and then designate `c:\MyServerSymbols` as a cache for symbols obtained from a server. The following example shows how to specify both directories in your symbol path. + +``` +.sympath c:\MyRegularSymbols;srv*c:\MyServerSymbols*https://msdl.microsoft.com/download/symbols +``` + +For more information about symbol servers, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +## Combining cache\* and srv\* + + +If you include the string `cache*;` in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache them in the default symbol cache directory. + +``` +.sympath cache*;srv*https://msdl.microsoft.com/download/symbols +``` + +If you include the string `cache*localsymbolcache;` in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the *localsymbolcache* directory. + +For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache the symbols in the `c:\MySymbols` directory. + +``` +.sympath cache*c:\MySymbols;srv*https://msdl.microsoft.com/download/symbols +``` + +## Using AgeStore to Reduce the Cache Size + + +You can use the AgeStore tool to delete cached files that are older than a specified date, or to delete enough old files that the resulting size of the cache is less than a specified amount. This can be useful if your downstream store is too large. For details, see [AgeStore](agestore.md). + +For more information about symbol servers and symbol stores, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +## Lazy Symbol Loading + + +The debugger's default behavior is to use *lazy symbol loading* (also known as *deferred symbol loading*). This kind of loading means that symbols are not loaded until they are required. + +When the symbol path is changed, for example by using the [`.sympath`](-sympath--set-symbol-path-.md) command, all loaded modules with export symbols are lazily reloaded. + +Symbols of modules with full PDB symbols will be lazily reloaded if the new path no longer includes the original path that was used to load the PDB symbols. If the new path still includes the original path to the PDB symbol file, those symbols will not be lazily reloaded. + +For more information about lazy symbol loading, see [Deferred Symbol Loading](deferred-symbol-loading.md). + +You can turn off lazy symbol loading in CDB and KD by using the `-s` [command-line option](command-line-options.md). You can also force symbol loading by using the `ld` [**(Load Symbols)**](ld--load-symbols-.md) command or by using the `.reload` [**(Reload Module)**](-reload--reload-module-.md) command together with the `/f` option. + +## + + +### Controlling the Symbol Path + +To control the symbol path, you can do one of the following: + +- Use the [`.sympath`](-sympath--set-symbol-path-.md) command to display, set, change, or append to the path. The `.symfix` [**(Set Symbol Store Path)**](-symfix--set-symbol-store-path-.md) command is similar to `.sympath` but saves you some typing. + +- Before you start the debugger, use the `_NT_SYMBOL_PATH` and `_NT_ALT_SYMBOL_PATH` [environment variables](environment-variables.md) to set the path. The symbol path is created by appending `_NT_SYMBOL_PATH` after `_NT_ALT_SYMBOL_PATH`. (Typically, the path is set through the `_NT_SYMBOL_PATH`. However, you might want to use `_NT_ALT_SYMBOL_PATH` to override these settings in special cases, such as if you have private versions of shared symbol files.) If you try to add an invalid directory through these environment variables, the debugger ignores this directory. + +- When you start the debugger, use the `-y` [command-line option](command-line-options.md) to set the path. + +- (WinDbg only) Use the [File | Symbol File Path](file---symbol-file-path.md) command or press `CTRL+S` to display, set, change, or append to the path. + +If you use the `-sins` [command-line option](command-line-options.md), the debugger ignores the symbol path environment variable. + +## Related topics + + +[Advanced SymSrv Use](advanced-symsrv-use.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20path%20for%20Windows%20debuggers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/debugger/symbol-problems-while-debugging.md b/windows-driver-docs-pr/debugger/symbol-problems-while-debugging.md new file mode 100644 index 0000000000..da428b0020 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-problems-while-debugging.md @@ -0,0 +1,39 @@ +--- +title: Symbol Problems While Debugging +description: Symbol Problems While Debugging +ms.assetid: 2713c371-9683-4d0d-a8ab-8a4c897ba0ab +--- + +# Symbol Problems While Debugging + + +## + + +Invalid or missing symbols are one of the most common causes of debugger problems. When you see some sort of problem, you need to find out if you have a symbol issue. + +In some cases, the solution involves acquiring the correct symbol files. In other cases, you simply need to reconfigure the debugger to recognize symbol files you already have. But if you are not able to get the correct symbol files, you will need to work around this problem and debug the target in a more limited manner. + +This section includes: + +[Verifying Symbols](verifying-symbols.md) + +[Matching Symbol Names](matching-symbol-names.md) + +[Reading Symbols from Paged-Out Headers](reading-symbols-from-paged-out-headers.md) + +[Mapping Symbols When the PEB is Paged Out](mapping-symbols-when-the-peb-is-paged-out.md) + +[Debugging User-Mode Processes Without Symbols](debugging-user-mode-processes-without-symbols.md) + +[Debugging Performance-Optimized Code](debugging-performance-optimized-code.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Problems%20While%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-server-api.md b/windows-driver-docs-pr/debugger/symbol-server-api.md new file mode 100644 index 0000000000..f8134ce80b --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-server-api.md @@ -0,0 +1,31 @@ +--- +title: Symbol Server API +description: Symbol Server API +ms.assetid: 7a74bdc8-edb2-4615-9c26-a1b3cf9850a4 +keywords: ["symbol servers, Symbol Server API", "SymbolServerXxx routines", "DbgHelp interface", "ImageHlp interface", "dbghelp.chm (Debug Help Library documentation), Symbol Server API", "Debug Help Library documentation (dbghelp.chm), Symbol Server API"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Server API + + +## + + +The **SymbolServer*Xxx*** routines are needed if you want to write your own symbol server. + +These routines are part of the DbgHelp interface. For full documentation regarding the DbgHelp and ImageHlp interfaces, see the "Debug Help Library" documentation (dbghelp.chm). This can be found in the sdk\\help subdirectory of the Debugging Tools for Windows installation directory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Server%20API%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-status-abbreviations.md b/windows-driver-docs-pr/debugger/symbol-status-abbreviations.md new file mode 100644 index 0000000000..ee29c7eeb9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-status-abbreviations.md @@ -0,0 +1,94 @@ +--- +title: Symbol Status Abbreviations +description: Symbol Status Abbreviations +ms.assetid: 198453f2-fc9a-4313-875e-ac963b843df9 +keywords: ["symbols, symbol status abbreviations", "deferred (symbol status abbreviation)", "(symbol status abbreviation)", "T (symbol status abbreviation)", "C (symbol status abbreviation)", "DIA (symbol status abbreviation)", "Export (symbol status abbreviation)", "PERF (symbol status abbreviation)", "PDB (symbol status abbreviation)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Status Abbreviations + + +## + + +Symbol file types and their loading status can be determined by using the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command, the [**!lmi**](-lmi.md) extension, or WinDbg's [Debug | Modules](debug---modules.md) menu command. + +Each of these displays information about loaded modules and their symbols. + +The following abbreviations are used in the displays generated by these commands: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AbbreviationMeaning

deferred

The module has been loaded, but the debugger has not attempted to load the symbols. Symbols will be loaded when needed. See [Deferred Symbol Loading](deferred-symbol-loading.md) for details.

#

There is a mismatch between the symbol file and the executable, either in their timestamps or in their checksums.

T

The timestamp is missing, not accessible, or equal to zero.

C

The checksum is missing, not accessible, or equal to zero.

DIA

Symbol files were loaded through Debug Interface Access (DIA).

Export

No actual symbol files were found, so symbol information was extracted from the binary file's export table.

M

There is a mismatch between the symbol file and the executable, either in their timestamps or in their checksums. However, symbol files have been loaded anyway due to the symbol option settings.

PERF

This binary contains [performance-optimized code](debugging-performance-optimized-code.md). Standard address arithmetic may not produce correct results.

Stripped

Debug information was stripped from the image file.

PDB

The symbols are in .pdb format.

COFF

The symbols are in common object file format (COFF) symbol format.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Status%20Abbreviations%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-storage-format.md b/windows-driver-docs-pr/debugger/symbol-storage-format.md new file mode 100644 index 0000000000..e0934723c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-storage-format.md @@ -0,0 +1,165 @@ +--- +title: Symbol Storage Format +description: Symbol Storage Format +ms.assetid: 4aeaa644-9da4-4567-9dc7-86db38b7e93c +keywords: ["SymStore, storage format"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Storage Format + + +## + + +SymStore uses the file system itself as a database. It creates a large tree of directories, with directory names based on such things as the symbol file time stamps, signatures, age, and other data. + +For example, after several different acpi.dbgs have been added to the server, the directories could look like this: + +``` +Directory of \\mybuilds\symsrv\acpi.dbg +10/06/1999 05:46p . +10/06/1999 05:46p .. +10/04/1999 01:54p 37cdb03962040 +10/04/1999 01:49p 37cdb04027740 +10/04/1999 12:56p 37e3eb1c62060 +10/04/1999 12:51p 37e3ebcc27760 +10/04/1999 12:45p 37ed151662060 +10/04/1999 12:39p 37ed15dd27760 +10/04/1999 11:33a 37f03ce962020 +10/04/1999 11:21a 37f03cf7277c0 +10/06/1999 05:38p 37fa7f00277e0 +10/06/1999 05:46p 37fa7f01620a0 +``` + +In this example, the lookup path for the acpi.dbg symbol file might look like this: \\\\mybuilds\\symsrv\\acpi.dbg\\37cdb03962040. + +Three files may exist inside the lookup directory: + +1. acpi.dbg, if the file was stored + +2. file.ptr with a path to the actual symbol file, if a pointer was stored + +3. refs.ptr, which contains a list of all the current locations for acpi.dbg with this timestamp and image size that are currently added to the symbol store + +Displaying the directory listing of \\\\mybuilds\\symsrv\\acpi.dbg\\37cdb03962040 gives the following: + +``` +10/04/1999 01:54p 52 file.ptr +10/04/1999 01:54p 67 refs.ptr +``` + +The file file.ptr contains the text string "\\\\mybuilds\\symbols\\x86\\2128.chk\\symbols\\sys\\acpi.dbg". Since there is no file called acpi.dbg in this directory, the debugger will try to find the file at \\\\mybuilds\\symbols\\x86\\2128.chk\\symbols\\sys\\acpi.dbg. + +The contents of refs.ptr are used only by SymStore, not the debugger. This file contains a record of all transactions that have taken place in this directory. A sample line from refs.ptr might be: + +``` +0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg +``` + +This shows that a pointer to \\\\mybuilds\\symbols\\x86\\2128.chk\\symbols\\sys\\acpi.dbg was added with transaction "0000000026". + +Some symbol files stay constant through various products or builds or a particular product. One example of this is the Windows 2000 file msvcrt.pdb. A directory listing of \\\\mybuilds\\symsrv\\msvcrt.pdb shows that only two versions of msvcrt.pdb have been added to the symbols server: + +``` +Directory of \\mybuilds\symsrv\msvcrt.pdb +10/06/1999 05:37p . +10/06/1999 05:37p .. +10/04/1999 11:19a 37a8f40e2 +10/06/1999 05:37p 37f2c2272 +``` + +However, a directory listing of \\\\mybuilds\\symsrv\\msvcrt.pdb\\37a8f40e2 shows that refs.ptr has several pointers in it. + +``` +Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 +10/05/1999 02:50p 54 file.ptr +10/05/1999 02:50p 2,039 refs.ptr +``` + +The contents of \\\\mybuilds\\symsrv\\msvcrt.pdb\\37a8f40e2\\refs.ptr are the following: + +``` +0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb +0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb +0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb +0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb +0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb +0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb +0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb +0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb +0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb +0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb +0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb +0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb +0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb +0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb +0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb +0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb +0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb +0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb +0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb +0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb +0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb +0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb +0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb +0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb +0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb +0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb +0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb +0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb +0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb +0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb +``` + +This shows that the same msvcrt.pdb was used for multiple builds of symbols for Windows 2000 stored on \\\\mybuilds\\symsrv. + +Here is an example of a directory that contains a mixture of file and pointer additions: + +``` +Directory of E:\symsrv\dbghelp.dbg\38039ff439000 +10/12/1999 01:54p 141,232 dbghelp.dbg +10/13/1999 04:57p 49 file.ptr +10/13/1999 04:57p 306 refs.ptr +``` + +In this case, refs.ptr has the following contents: + +``` +0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg +0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg +0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg +0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg +0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg +``` + +Thus, transactions 43, 44, and 45 added the same file to the server, and transactions 46 and 47 added pointers. If transactions 43, 44, and 45 are deleted, then the file dbghelp.dbg will be deleted from the directory. The directory will then have the following contents: + +``` +Directory of e:\symsrv\dbghelp.dbg\38039ff439000 +10/13/1999 05:01p 49 file.ptr +10/13/1999 05:01p 130 refs.ptr +``` + +Now file.ptr contains "\\\\foo2\\bin\\symbols\\retail\\dll\\dbghelp.dbg", and refs.ptr contains + +``` +0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg +0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg +``` + +Whenever the final entry in refs.ptr is a pointer, the file file.ptr will exist and contain the path to the associated file. Whenever the final entry in refs.ptr is a file, no file.ptr will exist in this directory. Therefore, any delete operation that removes the final entry in refs.ptr may result in file.ptr being created, deleted, or changed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Storage%20Format%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-store-folder-tree.md b/windows-driver-docs-pr/debugger/symbol-store-folder-tree.md new file mode 100644 index 0000000000..a91e630bea --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-store-folder-tree.md @@ -0,0 +1,57 @@ +--- +title: Symbol Store Folder Tree +description: The symbol store backing SMB and HTTP requests is a folder tree residing on a local disk. +ms.assetid: AB23A180-71C3-4EBE-A3DE-765D264EF130 +--- + +# Symbol Store Folder Tree + + +The symbol store backing SMB and HTTP requests is a folder tree residing on a local disk. + +To keep administration simple, the sub-folder name (e.g. Symbols) can also be used as the File Share name and also the Virtual Directory name. If a new symbol store was to be added, a new sub-folder would be made under D:\\SymStore, and a new File Share and Virtual Directory of that name would be made to expose the store to clients. + +The folder tree’s location should be chosen carefully as well as the disk’s file system. The symbol store can get extremely big (terabytes) when caching files from (internal) build servers and the Internet. The folder tree should reside on a disk that is capable of a high number of reads and low number of writes. The file system can affect performance - ReFS may perform better than NTFS and should be investigated for large deployments. Equally, the networking to the server should be of sufficient speed to handle the load from the clients and also the load to the upstream symbol stores to retrieve the symbols for cache population. + +## Symbol Store Single-Tier or Two-Tier Structure + + +Normally files are placed in a single tier directory structure in which a single subdirectory exists for each filename cached. Under each filename folder, additional folders are made to store each version of the file. The tree will have this structure: + +``` +D:\SymStore\Symbols\ntdll.dll\...\ +D:\SymStore\Symbols\ntdll.pdb\...\ +D:\SymStore\Symbols\kernel32.dll\...\ +D:\SymStore\Symbols\kernel32.pdb\...\ +``` + +If a large number of files are to be stored, a two-tier structure can be used at the root of the symbol store. The first 2 letters of the filename are used as an intermediate folder name. + +To use a two-tier structure, place a file called index2.txt in the root of D:\\SymStore\\Symbols. The content of the file is of no importance. When this file exists, symsrv.dll will create and consume files from the two-tier tree using this structure: + +``` +D:\SymStore\Symbols\nt\ntdll.dll\...\ +D:\SymStore\Symbols\nt\ntdll.pdb\...\ +D:\SymStore\Symbols\ke\kernel32.dll\...\ +D:\SymStore\Symbols\ke\kernel32.pdb\...\ +``` + +If you want to convert the structure after the symbol store is populated, use the convertstore.exe application in the debugger folder. To allow the tool to work, create a folder called 000Admin in the root folder. This folder is required by convertstore.exe so that it can control the locking of the symbol store. + +## Related topics + + +[HTTP Symbol Stores](http-symbol-stores.md) + +[File Share (SMB) Symbol Server](file-share--smb--symbol-server.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Store%20Folder%20Tree%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-stores-and-symbol-servers.md b/windows-driver-docs-pr/debugger/symbol-stores-and-symbol-servers.md new file mode 100644 index 0000000000..8999874d0d --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-stores-and-symbol-servers.md @@ -0,0 +1,47 @@ +--- +title: Symbol Stores and Symbol Servers +description: Symbol Stores and Symbol Servers +ms.assetid: de35abe7-93ad-4ca0-94d4-bed1230e057b +keywords: ["symbol servers", "symbol servers, overview", "symbol stores", "symbol stores, overview", "SymSrv", "SymSrv, overview", "SymStore", "SymStore, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Stores and Symbol Servers + + +## + + +A *symbol store* is a collection of symbol files, an index, and a tool for adding and deleting files. A symbol store may also contain executable image files. The debugger accesses the files in a symbol store by using a *symbol server*. Debugging Tools for Windows includes both a symbol store creation tool, [SymStore](symstore.md), and a symbol server, [SymSrv](symsrv.md). It also includes a tool, [SymProxy](symproxy.md), for setting up an HTTP symbol store on a network to serve as a proxy for all symbol stores that the debugger may need to access. + +This section includes: + +[SymSrv](symsrv.md) + +[Using a Symbol Server](using-a-symbol-server.md) + +[HTTP Symbol Stores](http-symbol-stores.md) + +[File Share (SMB) Symbol Server](file-share--smb--symbol-server.md) + +[SymStore](symstore.md) + +[SymProxy](symproxy.md) + +[SymStore](symstore.md) + +If you are not setting up your own symbol store, but just intend to use the public Microsoft symbol store, see [Microsoft Public Symbols](microsoft-public-symbols.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Stores%20and%20Symbol%20Servers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbol-syntax-and-symbol-matching.md b/windows-driver-docs-pr/debugger/symbol-syntax-and-symbol-matching.md new file mode 100644 index 0000000000..5e8a53c687 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbol-syntax-and-symbol-matching.md @@ -0,0 +1,65 @@ +--- +title: Symbol Syntax and Symbol Matching +description: Symbol Syntax and Symbol Matching +ms.assetid: 7fda24bf-57be-4c7d-9eff-bd688de7cf1b +keywords: ["symbols, symbol syntax", "symbols, symbol matching", "symbols, symbol suffix", "syntax rules for commands, $ (local symbol identifier)", "$ (local symbol identifier)", "local symbol identifier ( $ )", "local variables, local symbol identifier ( $ )"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbol Syntax and Symbol Matching + + +## + + +Symbols allow you to directly manipulate tokens that are used by the program being debugged. For example, you can set a breakpoint at the function **main** with the command **bp main**, or display the integer variable **MyInt** with the command **dd MyInt L1**. + +In many cases, symbols can be used as parameters in debugger commands. This is supported for most numerical parameters, and is also supported in some text parameters. In addition to general rules for symbol syntax, there are also symbol syntax rules that apply in each of these cases. + +### General Symbol Syntax Rules + +A symbol name consists of one or more characters, but always begins with a letter, underscore (**\_**), question mark (**?**), or dollar sign (**$**). + +A symbol name may be qualified by a module name. An exclamation mark (**!**) separates the module name from the symbol (for instance, **mymodule!main**). If no module name is used, the symbol can still be prefixed with an exclamation mark. Using an exclamation mark with no module name can be especially useful, even for local variables, to indicate to a debugger command that a parameter is a name and not a hexadecimal number. For example, the variable **fade** will be read by the [**dt (Display Type)**](dt--display-type-.md) command as an address, unless it is prefixed by an exclamation mark or the -n option is used. However, to specify that a symbol is local, precede it with a dollar sign ( $ ) and an exclamation point ( ! ), as in **$!lime**. + +Symbol names are completely case-insensitive. This means that the presence of a **myInt** and a **MyInt** in your program will not be correctly understood by the debuggers; any command that references one of these may access the other one, regardless of how the command is capitalized. + +### Symbol Syntax in Numerical Expressions + +The debugger understands two different kinds of expressions: Microsoft Macro Assembler (MASM) expressions and C++ expressions. As far as symbols are concerned, these two forms of syntax differ as follows: + +- In MASM expressions, each symbol is interpreted as an address. Depending on what the symbol refers to, this will be the address of a global variable, local variable, function, segment, module, or any other recognized label. + +- In C++ expressions, each symbol is interpreted according to its type. Depending on what the symbol refers to, it may be interpreted as an integer, a data structure, a function pointer, or any other data type. A symbol that does not correspond to a C++ data type (such as an unmodified module name) will result in a syntax error. + +For an explanation of when and how to use each type of syntax, see [Evaluating Expressions](evaluating-expressions.md). + +If you are using MASM expression syntax, any symbol that could be interpreted as a hexadecimal number or as a register (e.g., **BadFeed**, **ebX**) should always be prefixed by an exclamation point. This makes sure the debugger recognizes it as a symbol. + +The [**ss (Set Symbol Suffix)**](ss--set-symbol-suffix-.md) command can be used to set the symbol suffix. This instructs the debugger to automatically append "A" or "W" to any symbol name it cannot find otherwise. + +Many Win32 routines exist in both ASCII and Unicode versions. These routines often have an "A" or "W" appended to the end of their names, respectively. Using a symbol suffix will aid the debugger when searching for these symbols. + +Suffix matching is not active by default. + +### Symbol Syntax in Text Expressions + +Symbols can be used in the text parameters of some commands -- for example, [**bm (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) and [**x (Examine Symbols)**](x--examine-symbols-.md). + +These text parameters support a variety of wildcards and specifiers. See [String Wildcard Syntax](string-wildcard-syntax.md) for details. In addition to the standard string wildcards, a text expression used to specify a symbol can be prefixed with a leading underscore. When matching this to a symbol, the debugger will treat this as any quantity of underscores, even zero. + +The symbol suffix is not used when matching symbols in text expressions. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbol%20Syntax%20and%20Symbol%20Matching%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbols-and-symbol-files.md b/windows-driver-docs-pr/debugger/symbols-and-symbol-files.md new file mode 100644 index 0000000000..56aa759738 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbols-and-symbol-files.md @@ -0,0 +1,106 @@ +--- +title: Symbols and Symbol Files +description: Symbols and Symbol Files +ms.assetid: b9ace4f0-8363-4dec-806f-798d30983dc1 +keywords: ["symbols, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbols and Symbol Files + + +## + + +When applications, libraries, drivers, or operating systems are linked, the linker that creates the .exe and .dll files also creates a number of additional files known as *symbol files*. + +Symbol files hold a variety of data which are not actually needed when running the binaries, but which could be very useful in the debugging process. + +Typically, symbol files might contain: + +- Global variables + +- Local variables + +- Function names and the addresses of their entry points + +- Frame pointer omission (FPO) records + +- Source-line numbers + +Each of these items is called, individually, a *symbol*. For example, a single symbol file Myprogram.pdb might contain several hundred symbols, including global variables and function names and hundreds of local variables. Often, software companies release two versions of each symbol file: a full symbol file containing both *public symbols* and *private symbols*, and a reduced (stripped) file containing only public symbols. For details, see [Public and Private Symbols](public-and-private-symbols.md). + +When debugging, you must make sure that the debugger can access the symbol files that are associated with the target you are debugging. Both live debugging and debugging crash dump files require symbols. You must obtain the proper symbols for the code that you wish to debug, and load these symbols into the debugger. + +### Windows Symbols + +Windows keeps its symbols in files with the extension .pdb. + +The compiler and the linker control the symbol format. The Visual C++ linker, places all symbols into .pdb files. + +The Windows operating system is built in two versions. The [*free build*](https://msdn.microsoft.com/library/windows/hardware/ff556280#wdkgloss-free-build) (or *retail build*) has relatively small binaries, and the [*checked build*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-checked-build) (or *debug build*) has larger binaries, with more debugging symbols in the code itself. Each of these builds has its own symbol files. When debugging a target on Windows, you must use the symbol files that match the build of Windows on the target. + +The following table lists several of the directories which exist in a standard Windows symbol tree: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DirectoryContains Symbol Files for

ACM

Microsoft Audio Compression Manager files

COM

Executable files (.com)

CPL

Control Panel programs

DLL

Dynamic-link library files (.dll)

DRV

Driver files (.drv)

EXE

Executable files (.exe)

SCR

Screen-saver files

SYS

Driver files (.sys)

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbols%20and%20Symbol%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbols-in-the-middle.md b/windows-driver-docs-pr/debugger/symbols-in-the-middle.md new file mode 100644 index 0000000000..5af8826c08 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbols-in-the-middle.md @@ -0,0 +1,51 @@ +--- +title: Symbols in the Middle +description: Symbols in the Middle +ms.assetid: 0fbf47fc-1216-4eaa-b4b9-96e206194b54 +keywords: ["remote debugging, symbols on third machine"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbols in the Middle + + +## + + +In this scenario, you have three computers. The first has the target application, the second has the symbols, and the third has the technician. + +Since the smart client behaves like a regular debugger in every way, it can be used as a debugging server at the same time. This allows you to link three machines together with the smart client in the middle. + +First, you start a process server on the computer \\\\BOXA: + +``` +dbgsrv -t npipe:pipe=FarPipe +``` + +The middle machine, named \\\\BOXB, starts the debugger with both the **-premote** and **-server** parameters. Suppose the PID of the target application is 400 and the symbol path is G:\\MySymbols: + +``` +cdb -server npipe:pipe=NearPipe -premote npipe:server=BOXA,pipe=FarPipe -v -y g:\mysymbols -p 400 +``` + +Then a debugging client on a third machine can be started as follows: + +``` +windbg -remote npipe:server=BOXB,pipe=NearPipe +``` + +The third machine is then used to control the debugging, while the second machine is where the actual processing is done and the symbols are accessed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbols%20in%20the%20Middle%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbols.md b/windows-driver-docs-pr/debugger/symbols.md new file mode 100644 index 0000000000..c419cebfc6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbols.md @@ -0,0 +1,43 @@ +--- +title: Symbols for Windows debugging (WinDbg, KD, CDB, NTSD) +description: Symbols for the Windows debuggers (WinDbg, KD, CDB, and NTSD) are available from a public symbol server. You can also download entire symbol packages. +ms.assetid: 9a6977d9-91c8-4366-a545-064e77cd6600 +keywords: ["symbols", "setup, symbols", "symbols, setup"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbols for Windows debugging (WinDbg, KD, CDB, NTSD) + + +Symbols for the Windows debuggers (WinDbg, KD, CDB, and NTSD) are available from a public symbol server. You can also download entire symbol packages. + +## + + +This section includes: + +[Introduction to Symbols](introduction-to-symbols.md) + +[Accessing Symbols for Debugging](accessing-symbols-for-debugging.md) + +[How the Debugger Recognizes Symbols](how-the-debugger-recognizes-symbols.md) + +[Symbol Problems While Debugging](symbol-problems-while-debugging.md) + +These topics explain what symbols are, how to access them during a debugging session, how to control the debugger's symbol options and symbol matching, and how to respond to various symbol-related problems during debugging. + +If you simply want to configure your debugger to access symbols for your own programs and for Windows, you may find it quicker to read the less-detailed introductory topics [Symbol Path](symbol-path.md) and [Using a Symbol Server](using-a-symbol-server.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbols%20for%20Windows%20debugging%20%28WinDbg,%20KD,%20CDB,%20NTSD%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symbols4.md b/windows-driver-docs-pr/debugger/symbols4.md new file mode 100644 index 0000000000..1a309537e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symbols4.md @@ -0,0 +1,38 @@ +--- +title: Symbols +description: Symbols +ms.assetid: 7eec815b-f81a-4c0f-b862-6ee31be7ed8f +keywords: ["Debugger Engine, symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Symbols + + +A *symbol* is a named unit of data or code from a source file that appears in a module. Information about symbols can include the name, type (if applicable), the address or register where it is stored, and any parent or child symbols. Examples of symbols include variables (local and global), functions, and any entry point into a module. + +The symbol information is used by the engine to help interpret data and code in the target. With this information, the engine can search for symbols by name or location in memory and provide a description of a symbol. + +The engine gets its information about symbols from symbol files, which are located on the local file system or loaded from a symbol server. When using a symbol server, the engine will automatically use the correct version of the symbol file to match the module in the target. Symbol files can be loaded whenever the corresponding module is loaded, or they can be loaded as needed. + +**Note**   Often optimizing compilers do not include accurate information in symbol files. This can cause the engine to misinterpret the value of some variables as the variable's location or lifetime might be incorrectly described, causing the engine to look at the wrong piece of memory or think a variable value is live when it is dead (or vice versa). It is also possible for an optimizing compiler to change the order of execution or to split a function into several pieces. Best results are usually obtained when debugging unoptimized code. + +  + +### Additional Information + +For details about using symbols, see [Using Symbols](using-symbols.md). For an overview of using symbol files and symbol servers, see [Symbols](symbols.md) in the Debuggers section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symchk-command-line-options.md b/windows-driver-docs-pr/debugger/symchk-command-line-options.md new file mode 100644 index 0000000000..718504df50 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symchk-command-line-options.md @@ -0,0 +1,308 @@ +--- +title: SymChk Command-Line Options +description: SymChk uses the following syntax +ms.assetid: e17dd001-2830-49bd-b727-fcd772ee23b4 +keywords: ["SymChk Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SymChk Command-Line Options +api_type: +- NA +--- + +# SymChk Command-Line Options + + +SymChk uses the following syntax: + +``` +symchk [/r] [/v | /q ] FileNames /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /ie ExeFile /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /id DumpFile /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /ih HotFixFile /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /ip ProcessID /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /it TextFileList /s[Opts] SymbolPath Options + +symchk [/r] [/v | /q ] /om Manifest FileNames + +symchk [/v | /q ] /im ManifestList /s[Opts] SymbolPath Options + +symchk [/v | /q ] /om Manifest /ie ExeFile + +symchk [/v | /q ] /om Manifest /id DumpFile + +symchk [/v | /q ] /om Manifest /ih HotFixFile + +symchk [/v | /q ] /om Manifest /ip ProcessFile + +symchk [/v | /q ] /om Manifest /it TextFileList +``` + +## Parameters + + + **/r** +If *Files* specifies a directory, the **/r** option causes SymChk to recursively search all subdirectories under this directory for program files. + + **/v** +Displays verbose information. This includes the file name of every program file whose symbols were investigated and whether it passed, failed, or was ignored. + + **/q** +Enables quiet mode. All output will be suppressed (unless the **/ot** option is included). + + *FileNames* +Specifies the program files whose symbols are to be checked. Absolute paths, relative paths, and UNC paths are permitted. An asterisk (**\***) wildcard is permitted. If *FileNames* ends in a slash, it is taken to be a directory name, and all files within that directory are checked. If *FileNames* contains spaces, it must be enclosed in quotation marks. + + **/ie** *ExeFile* +Specifies the name of a program that is currently executing. The symbols for this program will be checked. *ExeFile* must include the name of the file and file extension (usually .exe), but no path information. If there are two different executables with the same name, this option is not recommended. *ExeFile* can specify any program, including a kernel-mode driver. If *ExeFile* is a single asterisk ( **\*** ), SymChk will check the symbols for all running processes, including drivers. + + **/id** *DumpFile* +Specifies a memory dump file. The symbols for this dump file will be checked. + + **/ih** *HotFixFile* +Specifies a self-extracting Hotfix CAB file. + + **/ip** *ProcessID* +Specifies the process ID of a program that is currently executing. The symbols for this program will be checked. *ProcessID* must be specified as a decimal number. There are two special wildcards supported: + +- If *ProcessID* is zero ( **0** ), SymChk will check the symbols for all running drivers. + +- If *ProcessID* is a single asterisk ( **\*** ), SymChk will check the symbols for all running processes, including drivers. + + **/it** *TextFileList* +Specifies a text file that contains a list of program files. The symbols for all these programs will be checked. *TextFileList* must specify exactly one file (by relative, absolute, or UNC path, but with no wildcards); if it contains spaces it should be enclosed in quotation marks. Within this file, each line indicates a program file (by relative, absolute, or UNC paths), and an asterisk wildcard (**\***) is permitted. However, any line using this wildcard must use a relative path. + +If a line in this file contains spaces, it should be enclosed in quotation marks. A semicolon within this file is a comment character -- everything between a semicolon and the end of the line will be ignored. + + **/im** *ManifestList* +Specifies that the input to the command is a manifest file previously created by using the **/om** parameter. The manifest file contains information about the files for which symbols are retrieved. For more information about using a manifest file, see [Using a Manifest File with SymChk](using-a-manifest-file-with-symchk.md). + + **/om** *Manifest* +Specifies that a manifest file is created. The manifest file contains information about a set of files for which symbols will be retrieved, by using the **/im** parameter, at a later time. + + **/s**\[*Opts*\] *SymbolPath* +Specifies the directories containing symbols. Absolute paths, relative paths, and UNC paths are permitted. Any number of directories can be specified -- multiple directories should be separated with semicolons. If *SymbolPath* contains spaces, it must be enclosed in quotation marks. If you wish to specify a symbol server within this path, you should use one of the following syntaxes: + +``` +srv*DownstreamStore*\\Server\Share +srv*\\Server\Share +``` + +It is not recommended that you omit the **/s**\[*Opts*\] *SymbolPath* parameter, but if it is omitted, SymChk will point to the public symbol store by using the following default path: + +``` +srv*%SystemRoot%\symbols*https://msdl.microsoft.com/download/symbols +``` + +Any number of the following options can follow **/s**. There can be no space between the **/s** and these options: + +**e** +SymChk will check each path individually instead of checking all paths at once. + +**u** +Downstream stores will be updated. If the symbol path includes a downstream store, the symbol store will be searched for the symbol files. Only symbol stores that are being checked by SymChk will be updated. + +**p** +Force checking for private symbols. Public symbols will be treated as not matching. The **p** option implies **e** and **u**, and cannot be used with **s**. + +**s** +Force checking for public (split) symbols. Private symbols will be treated as not matching. The **s** option implies **e** and **u**, and cannot be used with **p**. + + *Options* +The available options are divided into several classes. Each class of options controls a different set of features. + +**Output options.** Any number of the following options can be specified. These options can be abbreviated by using **/o** only once -- for example, **/oi /oe** can be written as **/oie**. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

/oe

Output will include individual errors. This option is only useful if /q is used, because individual errors are automatically displayed if quiet mode hasn't been activated.

/op

Output will list each file that passes. (By default, SymChk only displays files that fail testing.)

/oi

Output will list each file that was ignored. (By default, SymChk only displays files that fail testing.)

/od

Output will include full details. Same as /oe /op /oi.

/ot

Output will include result totals. This option is only useful if /q is used, because these totals are automatically displayed if quiet mode hasn't been activated.

/ob

The full path for binaries will be included in all output messages.

/os

The full path for symbols will be included in all output messages.

/oc Dir

SymChk will create a traditional symbol tree in the directory Dir that contains a list of all the symbol files checked.

+ +  + +**DBG file options.** These options control how SymChk checks *.dbg* symbol files. Only one of the following options can be specified. + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionEffect

/ds

SymChk will verify that .dbg information was stripped from the executable and only appears in the .dbg file, and that the executable points to the .dbg file. If the program was built without .dbg symbol files, this option has no effect. This is the default.

/de

SymChk will verify that .dbg information was not stripped from the executable and that the executable does not point to a .dbg file. If the program was built without .dbg symbol files, this option has no effect.

/dn

SymChk will verify that .dbg information is not present in the image, and that the image does not point to a .dbg file.

+ +  + +**PDB file options.** These options control how SymChk checks .pdb symbol files. Only one of the following options can be specified. + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionEffect

/pf

SymChk performs no checking on the contents of the .pdb file -- it just verifies that the files exist and match the binary. This is the default.

/ps

SymChk will verify that the .pdb files have been stripped of source line, data type, and global information.

/pt

SymChk will verify that the .pdb files contain data type information.

+ +  + +**Filtering options.** These options control how module filtering is performed when SymChk is checking processes or dump files. Only one of the following options can be specified. + + ++++ + + + + + + + + + + + + +
OptionEffect

/fm Module

SymChk will only check dump files or processes associated with the specified module. Module must include the full filename, but must not include any part of the directory path.

+ +  + +**Symbol checking options.** Any number of the following options can be specified. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

/cs

SymChk won't verify that CodeView data is present. (By default, the presence of CodeView data is verified.)

/cc

When SymChk is checking a hotfix CAB file, it will not look for symbols inside the cab. (By default, SymChk will look for symbols in the cab as well as in the provided symbol path.)

/ea File

SymChk won't verify symbols for the programs listed in the specified file. This allows you to veto certain programs that would otherwise be verified. File must specify exactly one file (by relative, absolute, or UNC path, but without wildcards); if it contains spaces it should be enclosed in quotation marks. Within File, each line indicates a program file (by relative, absolute, or UNC paths); no wildcards are permitted. If a line in this file contains spaces it should be enclosed in quotation marks. A semicolon within this file is a comment character -- everything between a semicolon and the end of the line will be ignored. If a symbol server is being used, symbols for these programs will not be copied to the downstream store.

/ee File

Error messages for those programs listed in the specified file are suppressed. "Success" and "ignore" messages will appear as usual, and symbol files will be copied to the downstream store as usual. The format of File and the format of its contents are the same as that for /ea File.

+ +  + +### Additional Information + +For more information about SymChk, see [Using SymChk](using-symchk.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymChk%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symchk.md b/windows-driver-docs-pr/debugger/symchk.md new file mode 100644 index 0000000000..77c0380459 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symchk.md @@ -0,0 +1,35 @@ +--- +title: SymChk +description: SymChk +ms.assetid: ba025aac-2a72-4150-9f29-0dc57b6483b7 +keywords: ["SymChk", "SymChk, overview", "symbols, SymChk"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymChk + + +## + + +SymChk (the Microsoft Symbol Checker tool), Symchk.exe, is a program that compares executable files to symbol files to verify that the correct symbols are available. + +This section includes: + +[Using SymChk](using-symchk.md) + +[**SymChk Command-Line Options**](symchk-command-line-options.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymChk%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symproxy-automated-installation.md b/windows-driver-docs-pr/debugger/symproxy-automated-installation.md new file mode 100644 index 0000000000..b2a9cb2076 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symproxy-automated-installation.md @@ -0,0 +1,147 @@ +--- +title: SymProxy Automated Installation +description: These steps along with the Install.cmd script below can help automate the installation of SymProxy to a default IIS installation. +ms.assetid: 9E5433D8-D024-4E2B-AEAA-2271C133FD0E +--- + +# SymProxy Automated Installation + + +These steps along with the Install.cmd script below can help automate the installation of SymProxy to a default IIS installation. You will likely need to adapt these steps to the specific needs of your environment. + +1. Create D:\\SymStore\\Symbols folder. + + - Grant Read to Everyone + + - Grant Read\\Write to the SymProxy App Pool user account (Domain\\User) + +2. Share D:\\SymStore\\Symbols as Symbols. + + - Grant Read to Everyone (or be more specific) + +3. (Optionally) Create an empty file called index2.txt in D:\\SymStore\\Symbols. +4. (Optionally) Create an empty file called %WINDIR%\\system32\\inetsrv\\symsrv.yes. This accepts the EULA for the Microsoft Public Symbol Store. +5. Determine the parameters for Install.cmd and run it. +6. Configure the clients symbol path using the server name that you created. + ``` + SRV*\\MachineName\Symbols*http://MachineName/Symbols + ``` + +The Install.cmd script requires 3 parameters: + +- Virtual Directory path (e.g. D:\\SymStore\\Symbols ) +- Username (for the Application Pool) +- Password (for the Application Pool) + +To clear the MIME Type inheritance, an XML file is needed to drive the associated AppCmd.exe command. Place the staticContentClear.xml file shown below in the same folder as the Install.cmd script to achieve this result. + +Example Install.Cmd parameter usage: + +``` +Install.cmd D:\SymStore\Symbols CONTOSO\SymProxyService Pa$$word +``` + +## Install.cmd + + +``` +@echo off + +SET VirDirectory=%1 +SET UserName=%2 +SET Password=%3 + +:: +:: SymProxy dll installation. +:: + +copy symproxy.dll %windir%\system32\inetsrv +copy symproxy.man %windir%\system32\inetsrv +copy symsrv.dll %windir%\system32\inetsrv + +lodctr.exe /m:%windir%\system32\inetsrv\symproxy.man +wevtutil.exe install-manifest %windir%\System32\inetsrv\symproxy.man +regedit.exe /s symproxy.reg + +:: +:: Web server Configuraiton +:: + +IF not exist %VirDirectory% mkdir %VirDirectory% + +rem Make the 'Default Web Site' +%windir%\system32\inetsrv\appcmd.exe add site -site.name:"Default Web Site" -bindings:"http/*:80:" -physicalPath:C:\inetpub\wwwroot + +rem Enabled Directory Browsing on the 'Default Web Site' +%windir%\system32\inetsrv\appcmd.exe set config "Default Web Site" -section:system.webServer/directoryBrowse /enabled:"True" + +rem Make the 'SymProxy App Pool' +%windir%\system32\inetsrv\appcmd.exe add apppool -apppool.name:SymProxyAppPool -managedRuntimeVersion: +%windir%\system32\inetsrv\appcmd.exe set apppool -apppool.name:SymProxyAppPool -processModel.identityType:SpecificUser -processModel.userName:%UserName% -processModel.password:%Password% + +rem Make the 'Symbols' Virtual Directory and assign the 'SymProxy App Pool' +%windir%\system32\inetsrv\appcmd.exe add app -site.name:"Default Web Site" -path:/Symbols -physicalpath:%VirDirectory% +%windir%\system32\inetsrv\appcmd.exe set app -app.name:"Default Web Site/Symbols" -applicationPool:SymProxyAppPool + +rem Disable 'web.config' for folders under virtual directories in the 'Default Web Site' +%windir%\system32\inetsrv\appcmd.exe set config -section:system.applicationHost/sites "/[name='Default Web Site'].virtualDirectoryDefaults.allowSubDirConfig:false + +rem Add the 'SymProxy ISAPI Filter' +%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/isapiFilters /+"[name='SymProxy',path='%windir%\system32\inetsrv\SymProxy.dll',enabled='True'] + +rem Clear the MIME Types on the 'Default Web Site' +%windir%\system32\inetsrv\appcmd.exe set config -in "Default Web Site" < staticContentClear.xml + +rem Add * to the MIME Types of the 'Default Web Site' +%windir%\system32\inetsrv\appcmd.exe set config "Default Web Site" -section:staticContent /+"[fileExtension='.*',mimeType='application/octet-stream']" +``` + +## staticContentClear.xml + + +``` + + + + + + + +``` + +## Testing the SymProxy Installation + + +The system should now be ready to acquire and serve files. To test it, start by restarting the IISAdmin service by running iisreset.exe. This will reload the ISAPI filter with the current IIS and SymProxy configuration. + +Configure a debugger to use this symbol path: + +``` +srv*\\MachineName\Symbols*http://MachineName/Symbols +``` + +If *MissTimeout* is enabled (it is set to 300 seconds by default), running the .reload /f command twice should result in much faster execution the second time. + +To view the location of the PDBs being referenced, use the lm (list modules) command. The path to the PDBs should all begin with \\\\MachineName\\Symbols. + +If directory browsing is enabled on the web site, browse to http://MachineName/Symbols to see the files that are cached. + +Open the Performance Monitor and view the Symbol Proxy counters. + +Open the Event Viewer and view the Microsoft\\Windows\\SymProxy events. + +## Related topics + + +[Installing SymProxy](installing-symproxy.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymProxy%20Automated%20Installation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/symproxy.md b/windows-driver-docs-pr/debugger/symproxy.md new file mode 100644 index 0000000000..d79d1ccc67 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symproxy.md @@ -0,0 +1,102 @@ +--- +title: SymProxy +description: SymProxy +ms.assetid: c0b122fe-4996-4659-a3f1-95831605c0b3 +keywords: ["symbols, SymProxy (symproxy.dll)", "symbol stores, HTTP", "symbol stores, SymProxy (symproxy.dll)", "SymProxy"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymProxy + + +## + + +You can configure your HTTP-based symbol store to act as a proxy between client computers and other symbol stores. The implementation is through an Internet Server Application Programming Interface (ISAPI) filter called SymProxy (Symproxy.dll). The SymProxy server can be used as a gateway computer to the Internet or other sources within your company network. The following diagram shows an example SymProxy configuration. + +![diagram of an example symproxy configuration](images/symproxy-configuration.png) + +SymProxy is useful in many situations. For example: + +- You are debugging many systems within a lab environment in which the computers are not attached to the company network, but the symbols are stored in the network and must be accessed using Integrated Windows Authentication (IWA). + +- Your corporate computing environment includes a firewall that prevents access to the Internet from computers that are debugging and you must obtain symbols from an internet Web site. + +- You want to present a single symbol path for all users in your company so that they need not know or care about where symbols are located, and you can add new symbol stores without user intervention. + +- You have a remote site that is physically far from the rest of your company resources, and network access is slow. This system can be used to acquire symbols and cache them to the remote site. + +To install SymProxy, you must manually copy the files to the correct location, configure the registry, choose network security credentials, and configure Internet Information Services (IIS). To ensure that your HTTP symbol store is properly configured, see [HTTP Symbol Stores](http-symbol-stores.md). + +### Multiple Symbol Server Performance Considerations + +Each Virtual Directory can be associated with multiple (upstream) symbol stores. Each symbol store is queried independently. For performance, local SMB servers should be processed before internet HTTP servers. Unlike a debugger symbol path, multiple HTTP symbol stores can be specified in a SymProxy symbol path. A maximum of 10 entries are supported per Virtual Directory. + +### SymProxy Symbol Path + +SymProxy splits the (registry defined) symbol path value up in to the individual entries and uses each entry to generate a SRV\* based symbol path to retrieve the file. It uses the Virtual Directory’s folder as the downstream store in each of the queries – in effect, merging the upstream stores in to a single downstream symbol store. + +The (generated) symbol path used by SymProxy is equivalent to this: + +``` +SRV** +``` + +In this example, a UNC path and two HTTP paths are associated with a Virtual Directory to merge the symbols from a corporate symbol server, Microsoft and a 3rd party (Contoso). The SymProxy SymbolPath would be set like this: + +``` +\\MainOffice\Symbols;https://msdl.microsoft.com/download/symbols; +http://symbols.contoso.com/symbols +``` + +The Main Office Symbol file share is queried first using a (generated) symbol path of: + +``` +SRV*D:\SymStore\Symbols*\\MainOffice\Symbols +``` + +If the symbol file is not found, the Microsoft Symbol Store is queried using a (generated) symbol path of: + +``` +SRV*D:\SymStore\Symbols*https://msdl.microsoft.com/download/symbols +``` + +If the file is still not found, the Contoso Symbol Store (http://symbols.contoso.com/symbols) is queried using a (generated) symbol path of: + +``` +SRV*D:\SymStore\Symbols*http://symbols.contoso.com/symbols +``` + +This section includes: + +[Installing SymProxy](installing-symproxy.md) + +[Configuring the Registry](configuring-the-registry.md) + +[Choosing Network Security Credentials](choosing-network-security-credentials.md) + +[Configuring IIS for SymProxy](configuring-iis-for-symproxy.md) + +[Setting Up Exclusion Lists](setting-up-exclusion-lists.md) + +[Dealing with Unavailable Symbol Stores](dealing-with-unavailable-symbol-stores.md) + +[Checking and Updating Status](checking-and-updating-status.md) + +[Handling File Pointers](handling-file-pointers.md) + +[Caching Acquired Symbol Files](caching-acquired-symbol-files.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymProxy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symsrv.md b/windows-driver-docs-pr/debugger/symsrv.md new file mode 100644 index 0000000000..a476db5c3f --- /dev/null +++ b/windows-driver-docs-pr/debugger/symsrv.md @@ -0,0 +1,39 @@ +--- +title: SymSrv symbol server DLL +description: SymSrv (symsrv.dll) is a symbol server that is included in the Debugging Tools for Windows package. +ms.assetid: 43bcb5b5-cf00-4fc9-99cc-fb5c122fbde1 +keywords: ["SymSrv, using", "symbol servers, SymSrv (symsrv.dll)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymSrv + + +## + + +SymSrv (symsrv.dll) is a symbol server that is included in the Debugging Tools for Windows package. + +Many users of Debugging Tools for Windows use the public symbol store on the Microsoft Web site to access symbols for Microsoft products. If this is your goal, you only need to read the first topic listed below. + +This section includes: + +[Microsoft Public Symbols](microsoft-public-symbols.md) + +[Advanced SymSrv Use](advanced-symsrv-use.md) + +[Firewalls and Proxy Servers](firewalls-and-proxy-servers.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymSrv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symstore-command-line-options.md b/windows-driver-docs-pr/debugger/symstore-command-line-options.md new file mode 100644 index 0000000000..e71c4db895 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symstore-command-line-options.md @@ -0,0 +1,127 @@ +--- +title: SymStore Command-Line Options +description: The following syntax forms are supported for SymStore transactions. The first parameter must always be add or del. The order of the other parameters is immaterial. +ms.assetid: 44009878-8f8a-4301-b075-eb0164b4f3a3 +keywords: ["SymStore Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- SymStore Command-Line Options +api_type: +- NA +--- + +# SymStore Command-Line Options + + +The following syntax forms are supported for SymStore transactions. The first parameter must always be **add** or **del**. The order of the other parameters is immaterial. + +``` +symstore add [/r] [/p [/l] [-:MSG Message] [-:REL] [-:NOREFS]] /f File /s Store /t Product [/v Version] [/o] [/c Comment] [/d LogFile] [/compress] + +symstore add [/r] [/p [/l] [-:REL] [-:NOREFS]] /g Share /f File /x IndexFile [/a] [/o] [/d LogFile] + +symstore add /y IndexFile /g Share /s Store [/p [-:MSG Message] [-:REL] [-:NOREFS]] /t Product [/v Version] [/o] [/c Comment] [/d LogFile] [/compress] + +symstore query [/r] /f File /s Store [/o] [/d LogFile] + +symstore del /i ID /s Store [/o] [/d LogFile] + +symstore /? + + +``` + +## Parameters + + + **/f** *File* +Specifies the network path of files or directories to add. + + **/g** *Share* +Specifies the server and share where the symbol files were originally stored. When used with **/f**, *Share* should be identical to the beginning of the *File* specifier. When used with **/y**, *Share* should be the location of the original symbol files (not the index file). This allows you to later change this portion of the file path in case you move the symbol files to a different server and share. + + **/s** *Store* +Specifies the root directory for the symbol store. + + **/m** *Prefix* +Causes SymStore to prefer using symbols from paths beginning with *Prefix* when storing files or updating pointers. This option cannot be used with the **/x** option. + + **/h** { **PUB | PRI** } +Causes SymStore to prefer using public symbols (if PUB is specified), or private symbols (if PRI is specified) when storing or updating symbols. This option has no effect on binary files. + + **/i** *ID* +Specifies the transaction ID string. + + **/p** +Causes SymStore to store a pointer to the file, rather than the file itself. + + **/l** +Allows the file specified by *File* to be in a local directory rather than a network path. (This option can only be used when both **/f** and **/p** are used.) + + **-:MSG** *Message* +Adds the specified *Message* to each file. (This option can only be used when **/p** is used.) + + **-:REL** +Allows the paths in the file pointers to be relative. This option implies the /**l** option. (This option can only be used when **/p** is used.) + + **-:NOREFS** +Omits the creation of reference pointer files for the files and pointers being stored. This option is only valid during the initial creation of a symbol store if the store being changed was created with this option. + + **/r** +Causes SymStore to add files or directories recursively. + + **/t** *Product* +Specifies the name of the product. + + **/v** *Version* +Specifies the version of the product. + + **/c** *Comment* +Specifies a comment for the transaction. + + **/d** *LogFile* +Specifies a log file to be used for command output. If this is not included, transaction information and other output is sent to **stdout**. + + **/o** +Causes SymStore to display verbose output. + + **/x** *IndexFile* +Causes SymStore not to store the actual symbol files. Instead, SymStore records information in the *IndexFile* that will enable SymStore to access the symbol files at a later time. + + **/a** +Causes SymStore to append new indexing information to an existing index file. (This option is only used with the **/x** option.) + + **/y** *IndexFile* +Causes SymStore to read the data from a file created with **/x**. + + **/yi** *IndexFile* +Appends a comment with the transaction ID to the end of an index file created with the /**x** option. + + **/z** { **PUB | PRI** } +Causes SymStore to index only the type of symbols specified. If **PUB** is specified, then only the symbols that have had the full source information stripped will be indexed. If **PRI** is specified, then only the symbols that contain the full source information will be indexed. SymStore will always index binary symbols. + + **/compress** +Causes SymStore to create a compressed version of each file copied to the symbol store instead of using an uncompressed copy of the file. This option is only valid when storing files and not pointers, and consequently cannot be used when the **/p** option is used. + + **/?** +Displays help text for the SymStore command. + +### Additional Information + +For more information about SymStore, see [Using Symbol Servers and Symbol Stores](symbol-stores-and-symbol-servers.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymStore%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symstore-compressed-files.md b/windows-driver-docs-pr/debugger/symstore-compressed-files.md new file mode 100644 index 0000000000..90a984b285 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symstore-compressed-files.md @@ -0,0 +1,37 @@ +--- +title: SymStore Compressed Files +description: SymStore Compressed Files +ms.assetid: 4ec6a7f5-ceee-46d5-9a5e-36ab9fe9db52 +keywords: ["SymStore, compressed files"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymStore Compressed Files + + +## + + +SymStore can be used with compressed files in two different ways: + +1. Use SymStore with the **/p** option to store pointers to the symbol files. After SymStore finishes, compress the files that the pointers refer to. + +2. Use SymStore with the **/x** option to create an index file. After SymStore finishes, compress the files listed in the index file. Then, use SymStore with the **/y** option (and, if you wish, the **/p** option) to store the files or pointers to the files in the symbol store. (SymStore will not need to uncompress the files to perform this operation.) + +Your symbol server will be responsible for uncompressing the files at the proper time. + +If you are using SymSrv as your symbol server, any compression should be done using the compress.exe tool which is available [here](http://go.microsoft.com/fwlink/p/?linkid=239917). Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd\_ or module2.db\_). For details, see [SymSrv](symsrv.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymStore%20Compressed%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symstore-transactions.md b/windows-driver-docs-pr/debugger/symstore-transactions.md new file mode 100644 index 0000000000..d53ad7e76e --- /dev/null +++ b/windows-driver-docs-pr/debugger/symstore-transactions.md @@ -0,0 +1,189 @@ +--- +title: SymStore Transactions +description: SymStore Transactions +ms.assetid: f0bb2f3f-0f6b-4ed6-809e-f55b1c537d7f +keywords: ["SymStore, transactions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymStore Transactions + + +## + + +Every call to SymStore is recorded as a transaction. There are two types of transactions: add and delete. + +When the symbol store is created, a directory, called "000admin", is created under the root of the server. The 000admin directory contains one file for each transaction, as well as the log files server.txt and history.txt. The server.txt file contains a list of all transactions that are currently on the server. The history.txt file contains a chronological history of all transactions. + +Each time SymStore stores or removes symbol files, a new transaction number is created. Then, a file, whose name is this transaction number, is created in 000admin. This file contains a list of all the files or pointers that have been added to the symbol store during this transaction. If a transaction is deleted, SymStore will read through its transaction file to determine which files and pointers it should delete. + +The **add** and **del** options specify whether an add or delete transaction is to be performed. Including the **/p** option with an add operation specifies that a pointer is to be added; omitting the **/p** option specifies that the actual symbol file is to be added. + +It is also possible to create the symbol store in two separate stages. In the first stage, you use SymStore with the **/x** option to create an index file. In the second stage, you use SymStore with the **/y** option to create the actual store of files or pointers from the information in the index file. + +This can be a useful technique for a variety of reasons. For instance, this allows the symbol store to be easily recreated if the store is somehow lost, as long as the index file still exists. Or perhaps the computer containing the symbol files has a slow network connection to the computer on which the symbol store will be created. In this case, you can create the index file on the same machine as the symbol files, transfer the index file to the second machine, and then create the store on the second machine. + +For a full listing of all SymStore parameters, see [**SymStore Command-Line Options**](symstore-command-line-options.md). + +**Note**   SymStore does not support simultaneous transactions from multiple users. It is recommended that one user be designated "administrator" of the symbol store and be responsible for all **add** and **del** transactions. + +  + +### Transaction Examples + +Here are two examples of SymStore adding symbol pointers for build 2195 of Windows 2000 to \\\\MyDir\\symsrv: + +``` +symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 free" /c "Sample add" +symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 checked" /c "Sample add" +``` + +In the following example, SymStore adds the actual symbol files for an application project in \\\\largeapp\\appserver\\bins to \\\\MyDir\\symsrv: + +``` +symstore add /r /f \\largeapp\appserver\bins\*.* /s \\MyDir\symsrv /t "Large Application" /v "Build 432" /c "Sample add" +``` + +Here is an example of how an index file is used. First, SymStore creates an index file based on the collection of symbol files in \\\\largeapp\\appserver\\bins\\. In this case, the index file is placed on a third computer, \\\\hubserver\\hubshare. You use the **/g** option to specify that the file prefix "\\\\largeapp\\appserver" might change in the future: + +``` +symstore add /r /p /g \\largeapp\appserver /f \\largeapp\appserver\bins\*.* /x \\hubserver\hubshare\myindex.txt +``` + +Now suppose you move all the symbol files off of the machine \\\\largeapp\\appserver and put them on \\\\myarchive\\appserver. You can then create the symbol store itself from the index file \\\\hubserver\\hubshare\\myindex.txt as follows: + +``` +symstore add /y \\hubserver\hubshare\myindex.txt /g \\myarchive\appserver /s \\MyDir\symsrv /p /t "Large Application" /v "Build 432" /c "Sample Add from Index" +``` + +Finally, here is an example of SymStore deleting a file added by a previous transaction. See "The server.txt and history.txt Files" section below for an explanation of how to determine the transaction ID (in this case, 0000000096). + +``` +symstore del /i 0000000096 /s \\MyDir\symsrv +``` + +### The server.txt and history.txt Files + +When a transaction is added, several items of information are added to server.txt and history.txt for future lookup capability. The following is an example of a line in server.txt and history.txt for an add transaction: + +``` +0000000096,add,ptr,10/09/99,00:08:32,Windows Vista SP 1,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols, +``` + +This is a comma-separated line. The fields are explained as follows: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription

0000000096

Transaction ID number, as created by SymStore.

add

Type of transaction. This field can be either add or del.

ptr

Whether files or pointers were added. This field can be either file or ptr.

10/09/99

Date when transaction occurred.

00:08:32

Time when transaction started.

Windows Vista SP 1

Product.

x86 fre

Version (optional).

Added from

Comment (optional)

Unused

(Reserved for later use.)

+ +  + +Here are some sample lines from the transaction file 0000000096. Each line records the directory and the location of the file or pointer that was added to the directory. + +``` +canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg +canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg +certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg +certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg +certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg +certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg +``` + +If you use a **del** transaction to undo the original **add** transactions, these lines will be removed from server.txt, and the following line will be added to history.txt: + +``` +0000000105,del,0000000096 +``` + +The fields for the delete transaction are described as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + +
FieldDescription

0000000105

Transaction ID number, as created by SymStore.

del

Type of transaction. This field can be either add or del.

0000000096

Transaction that was deleted.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymStore%20Transactions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/symstore.md b/windows-driver-docs-pr/debugger/symstore.md new file mode 100644 index 0000000000..2ab4e80423 --- /dev/null +++ b/windows-driver-docs-pr/debugger/symstore.md @@ -0,0 +1,43 @@ +--- +title: SymStore +description: SymStore +ms.assetid: acc7bf3a-62ea-4c93-843e-b81d4f71555f +keywords: ["SymStore, features", "SymStore, using", "symbol stores, SymStore (symstore.exe)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SymStore + + +## + + +SymStore (symstore.exe) is a tool for creating symbol stores. It is included in the Debugging Tools for Windows package. + +SymStore stores symbols in a format that enables the debugger to look up the symbols based on the time stamp and size of the image (for a .dbg or executable file), or signature and age (for a .pdb file). The advantage of the symbol store over the traditional symbol storage format is that all symbols can be stored or referenced on the same server and retrieved by the debugger without any prior knowledge of which product contains the corresponding symbol. + +Note that multiple versions of .pdb symbol files (for example, public and private versions) cannot be stored on the same server, because they each contain the same signature and age. + +This section includes: + +[SymStore Transactions](symstore-transactions.md) + +[File System References and Symbol Files](file-system-references-and-symbol-files.md) + +[SymStore Compressed Files](symstore-compressed-files.md) + +[Symbol Storage Format](symbol-storage-format.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20SymStore%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/synchronizing-with-the-target-computer.md b/windows-driver-docs-pr/debugger/synchronizing-with-the-target-computer.md new file mode 100644 index 0000000000..d26655e2de --- /dev/null +++ b/windows-driver-docs-pr/debugger/synchronizing-with-the-target-computer.md @@ -0,0 +1,37 @@ +--- +title: Synchronizing with the Target Computer +description: Synchronizing with the Target Computer +ms.assetid: bc9bbe35-6665-49ee-ba95-16ff03e25e96 +keywords: ["synchronizing with the target computer", "synchronizing with the target computer, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronizing with the Target Computer + + +## + + +Sometimes during kernel-mode debugging, the target computer stops responding to the debugger. + +In KD, you can press [**CTRL+R (Re-synchronize)**](ctrl-r--re-synchronize-.md) and then press ENTER to synchronize with the target computer. In WinDbg, use [CTRL+ALT+R](debug---kernel-connection---resynchronize.md) or Debug | Kernel Connection | Resynchronize. + +These commands frequently restore communication between the host and the target. However, resynchronization might not always be successful, especially if you are using a 1394 kernel connection. + +The [**.restart (Restart Kernel Connection)**](-restart--restart-kernel-connection-.md) command provides a more powerful method of resynchronization. This command is equivalent to exiting the debugger and then attaching a new debugger to the existing session. This command is available only in KD, not in WinDbg. + +The **.restart** command is most useful when you are performing [remote debugging through remote.exe](remote-debugging-through-remote-exe.md). (In this kind of debugging, it might be difficult to end and restart the debugger.) However, you cannot use **.restart** from a debugging client if you are performing remote debugging through the debugger. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Synchronizing%20with%20the%20Target%20Computer%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/syntax-rules.md b/windows-driver-docs-pr/debugger/syntax-rules.md new file mode 100644 index 0000000000..814f3798fd --- /dev/null +++ b/windows-driver-docs-pr/debugger/syntax-rules.md @@ -0,0 +1,71 @@ +--- +title: Syntax Rules +description: This section describes the syntax rules that you must follow to use debugger commands. +ms.assetid: bd1605f9-8e98-4d80-8742-acba222872ef +keywords: commands, syntax rules, meta-commands +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Syntax Rules + + +## + + +This section describes the syntax rules that you must follow to use debugger commands. + +When you are debugging, you should obey the following general syntax rules: + +- You can use any combination of uppercase and lowercase letters in commands and arguments, except when specifically noted in the topics in this section. + +- You can separate multiple command parameters by one or more spaces or by a comma (**,**). + +- You can typically omit the space between a command and its first parameter . You can frequently omit other spaces if this omission does not cause any ambiguity. + +The command reference topics in this section use the following items: + +- Characters in **bold** font style indicate items that you must literally type. + +- Characters in *italic* font style indicate parameters that are explained in the "Parameters" section of the reference topic. + +- Parameters in brackets (**\[***xxx***\]**) are optional. Brackets with a vertical bar (**\[***xxx***|***yyy***\]**) indicate that you can use one, or none, of the enclosed parameters. + +- Braces with vertical bars (**{***xxx***|***yyy***}**) indicate that you must use exactly one of the enclosed parameters . + +The following topics describe the syntax that the following parameter types use: + +[Numerical Expression Syntax](numerical-expression-syntax.md) + +[String Wildcard Syntax](string-wildcard-syntax.md) + +[Register Syntax](register-syntax.md) + +[Pseudo-Register Syntax](pseudo-register-syntax.md) + +[Source Line Syntax](source-line-syntax.md) + +[Address and Address Range Syntax](address-and-address-range-syntax.md) + +[Thread Syntax](thread-syntax.md) + +[Process Syntax](process-syntax.md) + +[System Syntax](system-syntax.md) + +[Multiprocessor Syntax](multiprocessor-syntax.md) + +Syntax also plays an important role in using symbols. For further details, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Syntax%20Rules%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/system-syntax.md b/windows-driver-docs-pr/debugger/system-syntax.md new file mode 100644 index 0000000000..e6123ae8b9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/system-syntax.md @@ -0,0 +1,87 @@ +--- +title: System Syntax +description: System Syntax +ms.assetid: f2b327cd-8ba5-45f3-9116-756df82358f4 +keywords: ["system, command syntax", "(system identifier)", "system, system identifier ( )", "syntax rules for commands, systems", "syntax rules for commands, (system identifier)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Syntax + + +## + + +Many debugger commands have process identifiers as their parameters. + +Two vertical bars ( || ) appear before the system identifier. The system identifier can be one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
System identifierDescription

||.

The current system

||#

The system that caused the current exception or debug event.

||*

All systems.

||ddd

The system whose ordinal is ddd.

+ +  + +Systems are assigned ordinals in the order that the debugger attaches to them. + +When debugging begins, the current system is the one that caused the present exception or debug event (or the one that the debugger most recently attached to). That system remains the current system until you specify a new one by using a [**||s (Set Current System)**](--s--set-current-system-.md) command or by using the [Processes and Threads window](processes-and-threads-window.md) in WinDbg. + +Example +------- +This example shows three dump files are loaded. System 1 is active and system 2 caused the debug event. + +``` +||1:1:017> || + 0 User mini dump: c:\notepad.dmp +. 1 User mini dump: c:\paint.dmp +# 2 User mini dump: c:\calc.dmp + +``` + + +Remarks +------- + +To work with multiple systems, you can use the [.opendump](-opendump--open-dump-file-.md) to debug multiple crash dumps at the same time. For more information about how to control a multiple-target session, see [Debugging Multiple Targets](debugging-multiple-targets.md). + +**Note**   There are complications, when you debug live targets and dump targets together, because commands behave differently for each type of debugging. For example, if you use the **g (Go)** command when the current system is a dump file, the debugger begins executing, but you cannot break back into the debugger, because the break command is not recognized as valid for dump file debugging. + + + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20System%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/t--trace-.md b/windows-driver-docs-pr/debugger/t--trace-.md new file mode 100644 index 0000000000..654d70c345 --- /dev/null +++ b/windows-driver-docs-pr/debugger/t--trace-.md @@ -0,0 +1,106 @@ +--- +title: t (Trace) +description: The t command executes a single instruction or source line and optionally displays the resulting values of all registers and flags. +ms.assetid: 0cb3ac96-5d5c-4ebd-8ef1-2fbb066e6458 +keywords: ["t (Trace) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- t (Trace) +api_type: +- NA +--- + +# t (Trace) + + +The **t** command executes a single instruction or source line and optionally displays the resulting values of all registers and flags. When subroutine calls or interrupts occur, each of their steps is also traced. + +User-Mode + +``` +[~Thread] t [r] [= StartAddress] [Count] ["Command"] +``` + +Kernel-Mode + +``` +t [r] [= StartAddress] [Count] ["Command"] +``` + +## Parameters + + + *Thread* +Specifies threads to thaw. All other threads are frozen. For more information about this syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the [**pr**](p--step-.md), **tr**, or .prompt\_allow -reg commands. All three of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where execution should begin. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of instructions or source lines to trace through before stopping. Each step is displayed as a separate action in the [Debugger Command window](debugger-command-window.md). The default value is one. + + *Command* +Specifies a debugger command to execute after the trace is performed. This command is executed before the standard **t** results are displayed. If you also use *Count*, this command is executed after all tracing is complete (but before the results from the final trace are displayed). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about how to issue the **t** command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +When you specify *Count*, each instruction is displayed as it is stepped through. + +Each trace executes a single assembly instruction or a single source line, depending on whether the debugger is in assembly mode or source mode. Use the [**l+t**](l---l---set-source-options-.md) and l-t commands or the buttons on the WinDbg toolbar to switch between these modes. + +If you want to trace most function calls but skip certain calls, you can use [**.step\_filter (Set Step Filter)**](-step-filter--set-step-filter-.md) to indicate which calls to step over. + +You can use the **t** command to trace instructions in ROM. + +When you are quickly tracing many times in WinDbg, the debugging information windows are updated after each trace. If this update causes slower response time, use [**.suspend\_ui (Suspend WinDbg Interface)**](-suspend-ui--suspend-windbg-interface-.md) to temporarily suspend the updating of these windows. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20t%20%28Trace%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/t.md b/windows-driver-docs-pr/debugger/t.md new file mode 100644 index 0000000000..8415434438 --- /dev/null +++ b/windows-driver-docs-pr/debugger/t.md @@ -0,0 +1,57 @@ +--- +title: T (Windows Debugger Glossary) +description: Glossary page - T +Robots: noindex, nofollow +ms.assetid: e17a63eb-a002-4e72-86a9-8176bf5f75d0 +--- + +# T + + +**target** +A target application, target computer, or dump target. + +Sometimes referred to as the*debuggee* . + +**target application** +An application that is being debugged in user-mode. + +**target computer** +A computer that is being debugged in kernel-mode. + +**target ID** +The unique identifier for a target. + +**target process** +In user-mode debugging, an operating system process that is part of the target application. + +In kernel-mode debugging, the virtual process representing the kernel. + +**target thread** +In user-mode debugging, an operating system thread in the target application. + +In kernel-mode debugging, a virtual thread representing a processor. + +**thread context** +The state preserved by Windows when switching threads. This is similar to the register context, except that there is some extra kernel-only processor state that is part of the register context but not the thread context. This extra state is available as registers during kernel-mode debugging. + +For more information, see Scopes and Symbol Groups. + +**transport layer** +This controls communication between the host and target computers during remote debugging. + +**trap** +See bug check. + +**type** +See symbol type. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20T%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ta--trace-to-address-.md b/windows-driver-docs-pr/debugger/ta--trace-to-address-.md new file mode 100644 index 0000000000..5bfc7390b0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ta--trace-to-address-.md @@ -0,0 +1,107 @@ +--- +title: ta (Trace to Address) +description: The ta command executes the program until the specified address is reached, displaying each step (including steps within called functions). +ms.assetid: 99741659-dd43-44ea-ac27-06d821b47fbe +keywords: ["ta (Trace to Address) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ta (Trace to Address) +api_type: +- NA +--- + +# ta (Trace to Address) + + +The **ta** command executes the program until the specified address is reached, displaying each step (including steps within called functions). + +User-Mode + +``` +[~Thread] ta [r] [= StartAddress] StopAddress +``` + +Kernel-Mode + +``` +ta [r] [= StartAddress] StopAddress +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **tar**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and use of any of them overrides any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *StopAddress* +Specifies the address at which execution stops. This address must match the exact address of an instruction. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **ta** command causes the target to begin executing. This execution continues until the specified instruction is reached or a breakpoint is encountered. + +**Note**   If you use the **ta** command in kernel mode, execution stops when an instruction is encountered at the specified virtual address in any virtual address space. + +  + +During this execution, all steps are displayed explicitly. If a function is called, the debugger also traces through that function. Therefore, the display of this command resembles what you see if you executed [**t (Trace)**](t--trace-.md) repeatedly until the program counter reached the specified address. + +For example, the following command explicitly traces through the target code until the return address of the current function is reached. + +``` +0:000> ta @$ra +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ta%20%28Trace%20to%20Address%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tabbing-a-window.md b/windows-driver-docs-pr/debugger/tabbing-a-window.md new file mode 100644 index 0000000000..fdb5cd9be9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tabbing-a-window.md @@ -0,0 +1,36 @@ +--- +title: Tabbing a Window +description: Tabbing a Window +ms.assetid: 4fff713b-ce76-42a6-91f7-9ae8f2acaafd +keywords: ["debugging information windows, tabbed windows", "tabbing windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Tabbing a Window + + +To tab a floating or docked window, drag it on top of another docked window. Drag the window with the mouse pointer over the center of an already-docked window, and then release the mouse button. The dragged window joins the already-docked window as a tabbed window collection. + +All Source windows can be grouped automatically into a tabbed collection by selecting one Source window and designating it as the tab-dock target for all Source windows by choosing the **Set as tab-dock target for window type** option in its short-cut menu. Once this is done, all future Source windows that are opened will automatically be included in a tabbed collection with this first Source window. The Source window marked as the tab-dock target will not be closed when the **Window | Close All Source Windows** menu command is selected. Thus you can set up a placeholder window for the Source windows without worrying that it will be closed when you don't want it to be. The same process also works for Memory windows. + +**Note**   If you want a window to join another window in a tabbed window collection, watch the outline of the window that moves as you drag the window. When this outline completely surrounds the window that you want to join, release the mouse button. + +  + +A set of tabs always controls the window immediately above the tabs. In the following illustration, the [Debugger Command window](debugger-command-window.md) is selected and is visible above the tabs. + +![screen shot of docked and tabbed windows](images/windock.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Tabbing%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/target-information.md b/windows-driver-docs-pr/debugger/target-information.md new file mode 100644 index 0000000000..88f8590937 --- /dev/null +++ b/windows-driver-docs-pr/debugger/target-information.md @@ -0,0 +1,60 @@ +--- +title: Target Information +description: Target Information +ms.assetid: e818c0bb-ba91-4752-8baf-00fff759106f +keywords: ["Debugger Engine API, targets, info"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Target Information + + +The method [**GetDebuggeeType**](https://msdn.microsoft.com/library/windows/hardware/ff546559) returns the nature of the current target (for example, whether it is a kernel-mode or user-mode target), and how the [debugger engine](introduction.md#debugger-engine) is connected to it. + +If the target is a crash dump file file, the method [**GetDumpFormatFlags**](https://msdn.microsoft.com/library/windows/hardware/ff546592) will indicate what information is contained in the dump. + +### Target's Computer + +The page size of the target's computer is returned by [**GetPageSize**](https://msdn.microsoft.com/library/windows/hardware/ff548086). [**IsPointer64Bit**](https://msdn.microsoft.com/library/windows/hardware/ff551092) will indicate if the computer uses 32-bit or 64-bit addresses. + +**Note**  Internally, the debugger engine always uses 64-bit addresses for the target. If the target only uses 32-bit addresses, the engine automatically converts them when communicating with the target. + +  + +The number of processors in the target's computer is returned by [**GetNumberProcessors**](https://msdn.microsoft.com/library/windows/hardware/ff547950). + +There are three different processor types associated with the target's computer: + +- The *actual processor type* is the type of the physical processor in the target's computer. This is returned by [**GetActualProcessorType**](https://msdn.microsoft.com/library/windows/hardware/ff545572). + +- The *executing processor type* is the type of the processor used in the currently executing processor context. This is returned by [**GetExecutingProcessorType**](https://msdn.microsoft.com/library/windows/hardware/ff546670). + +- The *effective processor type* is the processor type the debugger uses when interpreting information from the target -- for example, setting breakpoints, accessing registers, and getting stack traces. The effective processor type is returned by [**GetEffectiveProcessorType**](https://msdn.microsoft.com/library/windows/hardware/ff546595) and can be changed using [**SetEffectiveProcessorType**](https://msdn.microsoft.com/library/windows/hardware/ff556657). + +The effective processor type and executing processor type may differ from the actual processor type -- for example, when the physical processor is an x64 processor and it is running in x86 mode. + +The different executing processor types that are supported by the physical processor on the target's computer are returned by [**GetPossibleExecutingProcessorTypes**](https://msdn.microsoft.com/library/windows/hardware/ff548130). The number of these is returned by [**GetNumberPossibleExecutingProcessorTypes**](https://msdn.microsoft.com/library/windows/hardware/ff547939). + +The list of processor types that is supported by the debugger engine is returned by [**GetSupportedProcessorTypes**](https://msdn.microsoft.com/library/windows/hardware/ff548438). The number of supported processor types is returned by [**GetNumberSupportedProcessorTypes**](https://msdn.microsoft.com/library/windows/hardware/ff547966). + +The names (full and abbreviated) of a processor type are returned by [**GetProcessorTypeNames**](https://msdn.microsoft.com/library/windows/hardware/ff548169). + +The current time on the target's computer is returned by [**GetCurrentTimeDate**](https://msdn.microsoft.com/library/windows/hardware/ff546553). The length of time the target's computer has been running since the last boot is returned by [**GetCurrentSystemUpTime**](https://msdn.microsoft.com/library/windows/hardware/ff545883). Time information may not be available for all targets. + +### Target Versions + +The Windows version running on the target's computer is returned by [**GetSystemVersionValues**](https://msdn.microsoft.com/library/windows/hardware/ff549258) and the [**Request**](https://msdn.microsoft.com/library/windows/hardware/ff554564) operation [**DEBUG\_REQUEST\_GET\_WIN32\_MAJOR\_MINOR\_VERSIONS**](https://msdn.microsoft.com/library/windows/hardware/ff541563), and a description of the Windows version is returned by [**GetSystemVersionString**](https://msdn.microsoft.com/library/windows/hardware/ff549245). Some of this information is also returned by [**GetSystemVersion**](https://msdn.microsoft.com/library/windows/hardware/ff549234). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Target%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/target-state.md b/windows-driver-docs-pr/debugger/target-state.md new file mode 100644 index 0000000000..eab4b82ff7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/target-state.md @@ -0,0 +1,42 @@ +--- +title: Target State +description: Target State +ms.assetid: befd6c0b-dd16-40a1-bc6b-634b354d2a75 +keywords: ["Debugger Engine API, targets, state"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Target State + + +The method [**OutputCurrentState**](https://msdn.microsoft.com/library/windows/hardware/ff553206) will print the current state of the target to the debugger's output stream. + +The current execution status of the target is returned by [**GetExecutionStatus**](https://msdn.microsoft.com/library/windows/hardware/ff546675). If the target is suspended, the method [**SetExecutionStatus**](https://msdn.microsoft.com/library/windows/hardware/ff556693) can be used to resume execution in one of the execution modes. + +The method [**GetReturnOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548237) returns the address of the instruction that will execute when the current function returns. + +[**GetNearInstruction**](https://msdn.microsoft.com/library/windows/hardware/ff547197) returns the location of an instruction relative to a given address. + +### Examining the Stack Trace + +A *call stack* contains the data for the function calls that are made by a thread. The data for each function call is called a *stack frame* and includes the return address, parameters passed to the function, and the function's local variables. Each time a function call is made, a new stack frame is pushed onto the top of the stack. When that function returns, the stack frame is popped off the stack. Each thread has its own call stack, which represents the calls that are made in that thread. + +**Note**   Not all of the data for a function call can be stored in the stack frame. Parameters and local variables, at times, can be stored in registers. + +  + +To retrieve the call stack or *stack trace*, use the methods [**GetStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff548425) and [**GetContextStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff545748). The stack trace can be printed using [**OutputStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff553252) and [**OutputContextStackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff553203). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Target%20State%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/targets.md b/windows-driver-docs-pr/debugger/targets.md new file mode 100644 index 0000000000..a79b037e82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/targets.md @@ -0,0 +1,62 @@ +--- +title: Targets +description: Targets +ms.assetid: 103d9b0a-2d51-404e-b8b9-513465427f7b +keywords: ["Debugger Engine, targets"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Targets + + +The [debugger engine](introduction.md#debugger-engine) supports debugging different types of targets, [user-mode](#live--user-mode-targets) and [kernel-mode](#live--kernel-mode-targets) targets, live targets and crash dump files, and local and remote targets. There are different methods for connecting the engine to these different types of targets. + +### Crash Dump Files + +Both user-mode, and kernel-mode crash-dump files are opened with [**OpenDumpFile**](https://msdn.microsoft.com/library/windows/hardware/ff552322). The engine is also able to create dump files from a target with [**WriteDumpFile2**](https://msdn.microsoft.com/library/windows/hardware/ff561382). + +### Live, User-Mode Targets + +The debugger engine can both create and attach to user-mode processes. + +Creating a process is done by providing a command line, and optionally an initial directory and environment, for the new process. The engine can then connect to the new process, or keep the new process suspended while it connects to another process. For example, when debugging an application that consists of both a client and server, it is possible to create a client in a suspended state and attach to an already running server, allowing server breakpoints to be set before the client runs and provokes server operations. + +When detaching from a process, the engine can optionally leave the process running normally, kill the process, or abandon the process (leaving it suspended until another debugger attaches to it or it is killed). + +The engine can be queried for information about all of the user-mode processes that are running on the computer, including the process ID and name of the executable image that is used to start the process. This information can be used to help locate a process to debug. + +### Live, Kernel-Mode Targets + +The method [**AttachKernel**](https://msdn.microsoft.com/library/windows/hardware/ff538145) connects the debugger engine to a Windows kernel. + +### Remote Targets + +When using the debugger engine to debug remotely, there are potentially two extra steps: + +1. Connect to the host engine. If the host engine is not the local engine instance, use [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465) to create a client object that is connected to the host engine. + +2. Connect the host engine to the process server or kernel connection server. If the host engine does not connect directly to the target, it must connect to a process server or kernel connection server that does. + +Now the client can tell the host engine to acquire a target through the process server or kernel connection server. + +### Acquiring Targets + +When acquiring a target, the acquisition of the target is not complete until the target generates an event. Typically, this means first calling a method to attach the debugger to the target, then calling [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) to let the target generate an event. This still holds true when the target is a crash dump file, as these always store an event-typically the event that caused the dump file to be created. + +### Additional Information + +For details about attaching to targets, see [Connecting to Targets](connecting-to-targets.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Targets%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tb--trace-to-next-branch-.md b/windows-driver-docs-pr/debugger/tb--trace-to-next-branch-.md new file mode 100644 index 0000000000..611d4660b2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tb--trace-to-next-branch-.md @@ -0,0 +1,97 @@ +--- +title: tb (Trace to Next Branch) +description: The tb command executes the program until a branch instruction is reached. +ms.assetid: 28b736f9-69f5-405b-9684-48b4205e7633 +keywords: ["tb (Trace to Next Branch) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tb (Trace to Next Branch) +api_type: +- NA +--- + +# tb (Trace to Next Branch) + + +The **tb** command executes the program until a branch instruction is reached. + +``` +tb [r] [= StartAddress] [Count] +``` + +## Parameters + + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **tbr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger starts execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of branches to allow. Every time that a branch is encountered, the instruction address and the instruction are displayed. If you omit *Count*, the default number is 1. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

+x86-based: Kernel mode only +Itanium-based: User mode, kernel mode +x64-based: User mode, kernel mode

Targets

Live debugging only

Platforms

x86-based (GenuineIntel processor family 6 and later), Itanium-based, x64-based

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **tb** command causes the target to begin executing. This execution continues until a branch command is reached. + +Execution stops at any branch command that is to be taken. This stopping of execution is always based on the *disassembly* code, even when the debugger is in source mode. + +Branch instructions include calls, returns, jumps, counted loops, and while loops. If the debugger encounters an unconditional branch, or a conditional branch for which the condition is true, execution stops. If the debugger encounters a conditional branch whose condition is false, execution continues. + +When execution stops, the address of the branch instruction and any associated symbols are displayed. This information is followed by an arrow and then the address and instructions of the new program counter location. + +The **tb** command works only on the current processor. If you use **tb** on a multiprocessor system, execution stops when a branch command is reached or when another processor's event occurs, whichever comes first. + +Usually, branch tracing is enabled after the processor control block (PRCB) has been initialized. (The PRCB is initialized early in the boot process.) However, if you have to use the **tb** command before this point, you can use [**.force\_tb (Forcibly Allow Branch Tracing)**](-force-tb--forcibly-allow-branch-tracing-.md) to enable branch tracing earlier. Use the **.force\_tb** command cautiously, because it can corrupt your processor state. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20tb%20%28Trace%20to%20Next%20Branch%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tc--trace-to-next-call-.md b/windows-driver-docs-pr/debugger/tc--trace-to-next-call-.md new file mode 100644 index 0000000000..0e9874c9ed --- /dev/null +++ b/windows-driver-docs-pr/debugger/tc--trace-to-next-call-.md @@ -0,0 +1,99 @@ +--- +title: tc (Trace to Next Call) +description: The tc command executes the program until a call instruction is reached. +ms.assetid: cdeb448e-1032-46b1-a791-2fb84005fce4 +keywords: ["tc (Trace to Next Call) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tc (Trace to Next Call) +api_type: +- NA +--- + +# tc (Trace to Next Call) + + +The **tc** command executes the program until a call instruction is reached. + +User-Mode + +``` +[~Thread] tc [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +tc [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **tcr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **call** instructions that the debugger must encounter for the **tc** command to end. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **tc** command causes the target to begin executing. This execution continues until the debugger reaches a **call** instruction or encounters a breakpoint. + +If the program counter is already on a **call** instruction, the debugger traces into the call and continues executing until it encounters another **call**. This tracing, rather than execution, of the call is the only difference between **tc** and [**pc (Step to Next Call)**](pc--step-to-next-call-.md). + +In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a **call** instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20tc%20%28Trace%20to%20Next%20Call%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tct--trace-to-next-call-or-return-.md b/windows-driver-docs-pr/debugger/tct--trace-to-next-call-or-return-.md new file mode 100644 index 0000000000..c21555053a --- /dev/null +++ b/windows-driver-docs-pr/debugger/tct--trace-to-next-call-or-return-.md @@ -0,0 +1,99 @@ +--- +title: tct (Trace to Next Call or Return) +description: The tct command executes the program until it reaches a call instruction or return instruction. +ms.assetid: 059d8071-577f-4306-8273-8fdff6a80626 +keywords: ["tct (Trace to Next Call or Return) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tct (Trace to Next Call or Return) +api_type: +- NA +--- + +# tct (Trace to Next Call or Return) + + +The **tct** command executes the program until it reaches a call instruction or return instruction. + +User-Mode + +``` +[~Thread] tct [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +tct [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **tctr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **call** or **return** instructions that the debugger must encounter for the **tct** command to end. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **tct** command causes the target to begin executing. This execution continues until the debugger reaches a **call** or **return** instruction or encounters a breakpoint. + +If the program counter is already on a **call** or **return** instruction, the debugger traces into the call or return and continues executing until it encounters another **call** or **return**. This tracing, rather than execution, of the call is the only difference between **tct** and [**pct (Step to Next Call or Return)**](pct--step-to-next-call-or-return-.md). + +In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a **call** or **return** instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20tct%20%28Trace%20to%20Next%20Call%20or%20Return%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/th--trace-to-next-branching-instruction-.md b/windows-driver-docs-pr/debugger/th--trace-to-next-branching-instruction-.md new file mode 100644 index 0000000000..cb2364e1dc --- /dev/null +++ b/windows-driver-docs-pr/debugger/th--trace-to-next-branching-instruction-.md @@ -0,0 +1,101 @@ +--- +title: th (Trace to Next Branching Instruction) +description: The th command executes the program until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls. +ms.assetid: 42b7ceb6-c507-45b3-9186-0a4014b68a28 +keywords: ["th (Trace to Next Branching Instruction) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- th (Trace to Next Branching Instruction) +api_type: +- NA +--- + +# th (Trace to Next Branching Instruction) + + +The **th** command executes the program until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls. + +User-Mode + +``` +[~Thread] th [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +th [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **thr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of branching instructions that the debugger must encounter for the **th** command to end. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **th** command causes the target to begin executing. Execution continues until the debugger reaches a branching instruction or encounters a breakpoint. + +If the program counter is already on a branching instruction, the debugger traces into the branching instruction and continues executing until another branching instruction is reached. This tracing, rather than execution, of the call is the only difference between **th** and [**ph (Step to Next Branching Instruction)**](ph--step-to-next-branching-instruction-.md). + +**th** is available for all live sessions. This availability is the primary difference between **th** and [**tb (Trace to Next Branch)**](tb--trace-to-next-branch-.md). + +In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a branching instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20th%20%28Trace%20to%20Next%20Branching%20Instruction%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-amli-debugger.md b/windows-driver-docs-pr/debugger/the-amli-debugger.md new file mode 100644 index 0000000000..014f443e60 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-amli-debugger.md @@ -0,0 +1,41 @@ +--- +title: The AMLI Debugger +description: This topic describes the AMLI Debugger +ms.assetid: f9a9c646-e8a0-4ae0-b2a2-147e256f8683 +keywords: AML debugging, ACPI debugging, AMLI, BIOS debugging, ACPI Machine Language, debugging +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The AMLI Debugger + + +## + + +This section includes: + +[Introduction to the AMLI Debugger](introduction-to-the-amli-debugger.md) + +[Setting Up an AML Debugging Session](setting-up-an-aml-debugging-session.md) + +[Basic AML Debugging](basic-aml-debugging.md) + +[Using AMLI Debugger Extensions](using-amli-debugger-extensions.md) + +[Using AMLI Debugger Commands](using-amli-debugger-commands.md) + +[AML Debugging Examples](aml-debugging-examples.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20AMLI%20Debugger%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-dbgeng-h-header-file.md b/windows-driver-docs-pr/debugger/the-dbgeng-h-header-file.md new file mode 100644 index 0000000000..231c94ea2f --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-dbgeng-h-header-file.md @@ -0,0 +1,33 @@ +--- +title: The dbgeng.h Header File +description: This topic describes the dbgeng.h Header File. Routines in the dbgeng.h header file are used to write DbgEng extensions. +ms.assetid: a1328e9a-2910-4446-938d-1b2d1434ff10 +keywords: DbgEng API, dbgeng.h header file, dbgeng.h +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The dbgeng.h Header File + + +## + + +Routines in the dbgeng.h header file are used to write DbgEng extensions. + +For details on the dbgeng.h header file and information about how to write debugger extensions, see + +For information about how to write debugger extensions, see [Writing DbgEng Extensions](writing-dbgeng-extensions.md) and [Using the Debugger Engine API](using-the-debugger-engine-api.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20dbgeng.h%20Header%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-debugger-command-window.md b/windows-driver-docs-pr/debugger/the-debugger-command-window.md new file mode 100644 index 0000000000..5640ba1f5b --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-debugger-command-window.md @@ -0,0 +1,41 @@ +--- +title: Using the Debugger Command Window +description: Using the Debugger Command Window +ms.assetid: d93e8c96-e2f7-4a8a-8e9a-ea29dad2a822 +keywords: ["Debugger Command window", "Debugger Command window, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Debugger Command Window + + +## + + +This section includes the following topics: + +[Using Debugger Commands](using-debugger-commands.md) + +[Evaluating Expressions](evaluating-expressions.md) + +[Using Shell Commands](using-shell-commands.md) + +[Using Aliases](using-aliases.md) + +[Using Script Files](using-script-files.md) + +[Using Debugger Command Programs](using-debugger-command-programs.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Debugger%20Command%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-logger-manifest.md b/windows-driver-docs-pr/debugger/the-logger-manifest.md new file mode 100644 index 0000000000..aa8ebe1956 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-logger-manifest.md @@ -0,0 +1,35 @@ +--- +title: The Logger Manifest +description: The Logger Manifest +ms.assetid: 7f9bbb4e-0627-446e-8bd9-2827f11a2bf6 +keywords: ["Logger, manifest"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The Logger Manifest + + +## + + +This section includes: + +[Overview of the Logging Manifest](overview-of-the-logging-manifest.md) + +[Manifest File Placement](manifest-file-placement.md) + +[Manifest File Format](manifest-file-format.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20Logger%20Manifest%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-pdbstr-tool.md b/windows-driver-docs-pr/debugger/the-pdbstr-tool.md new file mode 100644 index 0000000000..f810470227 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-pdbstr-tool.md @@ -0,0 +1,28 @@ +--- +title: The PDBStr Tool +description: The PDBStr Tool +ms.assetid: a70e92ac-4d72-4c71-9396-f470314257f2 +keywords: ["SrcSrv, PDBStr tool", "PDBStr tool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The PDBStr Tool + + +The PDBStr (Pdbstr.exe) tool is used by the indexing scripts to insert the version control information into the "srcsrv" alternative stream of the target .pdb file. It can also read any stream from a .pdb file. You can use this information to verify that the indexing scripts are working properly. + +For more information, run PDBStr with the **-?** option. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20PDBStr%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-remote-exe-utility.md b/windows-driver-docs-pr/debugger/the-remote-exe-utility.md new file mode 100644 index 0000000000..40362f2943 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-remote-exe-utility.md @@ -0,0 +1,35 @@ +--- +title: The Remote.exe Utility +description: The Remote.exe Utility +ms.assetid: 3780d632-939e-4adb-82f1-fd7c25706b54 +keywords: ["remote debugging through remote.exe, remote.exe utility"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The Remote.exe Utility + + +## + + +The remote.exe utility is a versatile server/client tool that allows you to run command-line programs on remote computers. + +Remote.exe provides remote network access by means of named pipes to applications that use STDIN and STDOUT for input and output. Users at other computers on a network, or connected by a direct-dial modem connection. can either view the remote session or enter commands themselves. + +This utility has a large number of uses. For example, when you are developing software, you can compile code with the processor and resources of a remote computer while you perform other tasks on your computer. You can also use remote.exe to distribute the processing requirements for a particular task across several computers. + +Please note that remote.exe does no security authorization, and will permit anyone running Remote.exe Client to connect to your Remote.exe Server. This leaves the account under which the Remote.exe Server was run open to anyone who connects. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20Remote.exe%20Utility%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-srcsrv-ini-file.md b/windows-driver-docs-pr/debugger/the-srcsrv-ini-file.md new file mode 100644 index 0000000000..7127cd5cbd --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-srcsrv-ini-file.md @@ -0,0 +1,54 @@ +--- +title: The Srcsrv.ini File +description: The Srcsrv.ini File +ms.assetid: 5a3f5990-e43a-4c50-a16f-cbaa9f706ece +keywords: ["SrcSrv, Srcsrv.ini file", "Srcsrv.ini file", "SrcSrv, SRCSRV_INI_FILE environment variable", "SRCSRV_INI_FILE environment variable"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The Srcsrv.ini File + + +The Srcsrv.ini file is the master list of all source control servers. Each entry has the following format: + +``` +MYSERVER=ServerInfo +``` + +When using Perforce, the *ServerInfo* consists of the full network path to the server, followed by a colon, followed by the port number it uses. For example: + +``` +MYSERVER=machine.corp.company.com:1666 +``` + +Srcsrv.ini is a required file when you are actually source indexing a build using the modules shipped with this package. This entry creates an alias that is used to describe the server info. The value should be unique for every server that you support. + +This file can also be installed on the computer running the debugger. When SrcSrv starts, it looks at Srcsrv.ini for values; these values override the information contained in the .pdb file. This enables users to configure a debugger to use an alternative source control server at debug time. However, if you manage your servers well and do not rename them, there should be no need to include this file with your client debugger installations. + +This file also serves other purposes on the client side. For more information, see the sample Srcsrv.ini file installed with SrcSrv tools. + +### Using a Different Location or File Name + +By default, SrcSrv uses as its master configuration file the file named Srcsrv.ini, located in the srcsrv subdirectory of the Debugging Tools for Windows installation directory. + +You can specify a different file for configuration by setting the SRCSRV\_INI\_FILE environment variable equal to the full path and file name of the desired file. + +For example, if several people want to share a single configuration file, they could place it on a share accessible to all of their systems, and then set an environment variable like the following: + +``` +set SRCSRV_INI_FILE=\\ourserver\ourshare\bestfile.txt +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20Srcsrv.ini%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-srctool-utility.md b/windows-driver-docs-pr/debugger/the-srctool-utility.md new file mode 100644 index 0000000000..012dac460f --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-srctool-utility.md @@ -0,0 +1,34 @@ +--- +title: The SrcTool Utility +description: The SrcTool Utility +ms.assetid: d8669a91-4361-41d6-a7ba-a6d1a706ff66 +keywords: ["SrcSrv, SrcTool utility", "SrcTool utility"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The SrcTool Utility + + +The SrcTool (Srctool.exe) utility lists all files indexed within the .pdb file. For each file, it lists the full path, source control server, and version number of the file. You can use this information for reference. + +You can also use SrcTool to list the raw source file information from the .pdb file. To do this, use the **-s** switch on the command line. + +SrcTool has other options as well. Use the **?** switch to see them. Of most interest is that this utility can be used to extract all of the source files from version control. This is done with the **-x** switch. + +**Note**   Previous versions of this program created a directory called src below the current directory when extracting files. This is no longer the case. If you want the src directory used, you must create it yourself and run the command from that directory. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20SrcTool%20Utility%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-ssindex-cmd-script.md b/windows-driver-docs-pr/debugger/the-ssindex-cmd-script.md new file mode 100644 index 0000000000..8ff1b8fd36 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-ssindex-cmd-script.md @@ -0,0 +1,36 @@ +--- +title: The Ssindex.cmd Script +description: The Ssindex.cmd Script +ms.assetid: 38bff31a-af4e-4fd4-bdf6-da901067bdd0 +keywords: ["SrcSrv, Ssindex.cmd script", "Ssindex.cmd script"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The Ssindex.cmd Script + + +The Ssindex.cmd script builds the list of files checked into source control along with the version information of each file. It stores a subset of this information in the .pdb files generated when you built the application. SSIndex uses one of the following Perl modules to interface with source control: + +- p4.pm (Perforce) + +- vss.pm (Visual SourceSafe) + +- tfs.pm (Team Foundation Servers) + +- svn.pm (Subversion) + +For more information, run Ssindex.cmd with the **-?** or **-??** (verbose help) option or examine the script. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20Ssindex.cmd%20Script%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-vssdump-tool.md b/windows-driver-docs-pr/debugger/the-vssdump-tool.md new file mode 100644 index 0000000000..de77406e62 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-vssdump-tool.md @@ -0,0 +1,110 @@ +--- +title: The VSSDump Tool +description: The VSSDump Tool +ms.assetid: b213c949-3433-4686-8323-5af83a6ee5b1 +keywords: ["SrcSrv, VSSDump tool", "VSSDump tool"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The VSSDump Tool + + +The VSSDump (Vssdump.exe) tool is used by the indexing script for Microsoft Visual SourceSafe. It gathers the list of source files to be indexed. This program is also a valuable command-line utility that you can use to examine which files may be processed by the indexing script. + +To prepare for source indexing, edit Srcsrv.ini so that it contains an entry for your version control server. This is an operation that you must do only once. Details are listed in the sample version Srcsrv.ini. You can use an environment variable or switch to the indexing script to denote the location of this file. However, it is best to put it in the same directory as the script because the contents of this file are intended to be global across all projects in your business or development system. This file serves to uniquely identify different version control servers. Note that you can provide a different version of this file to debuggers so that they look at a replicated copy of the version control server, which can be useful if you want to reduce traffic on the server. + +To source-index a particular build, make certain that no source files are checked out on the build computer. If any files are checked out and edited, those changes are not reflected in the final source indexed .pdb files. Furthermore, if your build process includes a pre-compilation pass that generates source files from other files, you must check in those generated files to version control as part of the pre-compilation. + +Upon completion of the build, set the current working directory to be the root of all source files and generated .pdb files. Then run SSIndex. You must specify what version control system you are using as a parameter. For example: + +**ssindex.cmd -server=vss** + +SSIndex accepts parameters that allow you to run the script from anywhere and to specify the location of the source files and .pdb files separately. This is most useful if the source is kept in another location from the output .pdb files. For example: + +**ssindex.cmd -server=vss -source=c:\\***source* **-symbols=c:\\***outputdir* + +These directories can also be specified with environment variables. Use the -? or -?? command line options for more information. + +Here is an example of the output generated by this script: + +``` +## C:\ >ssindex.cmd -system=vss -? + +SSIndex.cmd [/option= [...]] [ModuleOptions] [/Debug] +General SrcSrv settings: + NAME SWITCH ENV. VAR Default + ----------------------------------------------------------------------------- + 1) srcsrv.ini Ini SRCSRV_INI .\srcsrv.ini + 2) Source root Source SRCSRV_SOURCE . + 3) Symbols root Symbols SRCSRV_SYMBOLS . + 4) Control system System SRCSRV_SYSTEM + 5) Save File (opt.) Save SRCSRV_SAVE + 6) Load File (opt.) Load SRCSRV_LOAD +Visual Source Safe specific settings: + NAME SWITCH ENV. VAR Default + ----------------------------------------------------------------------------- + A) VSS Server Server SSDIR + B) VSS Client Client SSROOT + C) VSS Project Project SSPROJECT + D) VSS Label Label SSLABEL +Precedence is: Default, environment, cmdline switch. (ie. env overrides default, +switch overrides env). +Using '/debug' will turn on verbose output. +Use "SSIndex.cmd -??" for verbose help information. +## See SrcSrv documentation for more information. + +``` + +You can also use one of the provided wrapper scripts (Vssindex.cmd) to avoid specifying the version control system. The script source-indexes all .pdb files found in the current directory and below with version control information to locate all source files found in the current directory and below. You can specify different locations for these files by using environment variables and command-line switches. + +Upon completion of the source indexing, you can test the output by running SrcTool on the .pdb files. This program displays data that indicates whether or not the .pdb file is source indexed. It also displays the specific information for every source file. Lastly, it displays the number of indexed sources and the number of sources that no indexing information was found for. It sets an %ERRORLEVEL% of -1 if the file is not source-indexed. Otherwise, it sets %ERRORLEVEL% to the number of indexed source files. + +VSSDump can also be used independently to diagnose issues while source-indexing. The syntax is as follows: + +**vssdump.exe** *Options* + +*Options* can be any combination of the following options. + +**-a** +Causes all projects to be searched, rather than restricting to the current project. This option may not be used with the **-p** option. + +**-p** *ProjectName* +Causes *VSSDump* to restrict its search to the project specified by *ProjectName*. If this option is not present, the current project is used. This option may not be used with the **-a** option. + +**-d** *RootDirectory* +Causes *VSSDump* to restrict its search to the root directory specified by *RootDirectory*. If this option is not present, the current directory is used. + +**-l** *Label* +Causes *VSSDump* to list only those files with a label that matches that specified by *Label*. + +*VSSDump***-v** *SharePath* +Specifies that the location of the Virtual SourceSafe database is in *SharePath*. This option overrides the path specified in the SSDIR environment variable. + +**-r** +Causes *VSSDump* to search subdirectories recursively. + +**-f** +Causes *VSSDump* to list directories containing source files without listing the files themselves. + +**-i** +Causes *VSSDump* to ignore the current directory and list the entire project. This option may not be used with **-r**. + +**-s** +Causes *VSSDump* to format output for use with script files. + +**-c** +Causes *VSSDump* to display only the Virtual SourceSafe configuration information. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20VSSDump%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-wdbgexts-h-header-file.md b/windows-driver-docs-pr/debugger/the-wdbgexts-h-header-file.md new file mode 100644 index 0000000000..815cb54ea6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-wdbgexts-h-header-file.md @@ -0,0 +1,31 @@ +--- +title: The wdbgexts.h Header File +description: This topic describes the wdbgexts.h Header File. Routines in the wdbgexts.h header file are used to write DbgEng extensions and WdbgExts extensions. +ms.assetid: a2c59657-b151-41e3-aa44-bdd8303eaf49 +keywords: WdbgExts API, wdbgexts.h, wdbgexts.h header file +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The wdbgexts.h Header File + + +## + + +Routines in the wdbgexts.h header file are used to write DbgEng extensions and WdbgExts extensions. + +For details on the wdbgexts.h header file and information about how to write debugger extensions, see [Writing WdbgExts Extensions](writing-wdbgexts-extensions.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20wdbgexts.h%20Header%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-x64-processor.md b/windows-driver-docs-pr/debugger/the-x64-processor.md new file mode 100644 index 0000000000..61f4760c89 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-x64-processor.md @@ -0,0 +1,39 @@ +--- +title: The x64 Processor +description: This section provides information on the x64 Processor +ms.assetid: b3e00741-9d39-4078-a758-e71d224a62b1 +keywords: x64 processor, AMD64 processor, x86-64 processor", AMD x86-64 processor +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The x64 Processor + + +## + + +This section includes: + +[x64 Architecture](x64-architecture.md) + +[x64 Instructions](x64-instructions.md) + +[Annotated x64 Disassembly](annotated-x64-disassembly.md) + +**Note**   The x64 processor architecture is sometimes referred to as "AMD64", "x86-64", "AMD x86-64" or "Intel64". + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20x64%20Processor%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/the-x86-processor.md b/windows-driver-docs-pr/debugger/the-x86-processor.md new file mode 100644 index 0000000000..9b0ea29354 --- /dev/null +++ b/windows-driver-docs-pr/debugger/the-x86-processor.md @@ -0,0 +1,35 @@ +--- +title: The x86 Processor +description: This section provides information on the x86 Processor +ms.assetid: 9827d7d3-4b7e-43dd-98c0-0b437bf4bd67 +keywords: x86 processor, i386 processor" +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The x86 Processor + + +## + + +This section includes: + +[x86 Architecture](x86-architecture.md) + +[x86 Instructions](x86-instructions.md) + +[Annotated x86 Disassembly](annotated-x86-disassembly.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20The%20x86%20Processor%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/thread-syntax.md b/windows-driver-docs-pr/debugger/thread-syntax.md new file mode 100644 index 0000000000..e836384a22 --- /dev/null +++ b/windows-driver-docs-pr/debugger/thread-syntax.md @@ -0,0 +1,88 @@ +--- +title: Thread Syntax +description: Thread Syntax +ms.assetid: f3eaa0ee-7c4f-47a4-aba9-c1d21c1529d1 +keywords: ["thread, command syntax", "~ (thread identifier)", "thread, thread identifier ( ~ )", "thread, thread ID", "~ (thread identifier)", "syntax rules for commands, ~ (thread identifier)", "syntax rules for commands, ~ (thread identifier)", "syntax rules for commands, threads"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Thread Syntax + + +## + + +Many debugger commands have thread identifiers as their parameters. A tilde ( ~ ) appears before the thread identifier. + +The thread identifier can be one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Thread identifierDescription

~.

The current thread.

~#

The thread that caused the current exception or debug event.

~*

All threads in the process.

~Number

The thread whose index is Number.

~~[TID]

The thread whose thread ID is TID. (The brackets are required And you cannot add a space between the second tilde and the opening bracket.)

~[Expression]

The thread whose thread ID is the integer to which the numerical Expression resolves.

+ +  + +Threads are assigned indexes as they are created. Note that this number differs from the thread ID that the Microsoft Windows operating system uses. + +When debugging begins, the current thread is the one that caused the present exception or debug event (or the active thread when the debugger attached to the process). That thread remains the current thread until you specify a new one by using a [**~s (Set Current Thread)**](-s--set-current-thread-.md) command or by using the [Processes and Threads window](processes-and-threads-window.md) in WinDbg. + +Thread identifiers typically appear as command prefixes. Note that not all wildcard characters are available in all commands that use thread identifiers. + +An example of the ~\[*Expression*\] syntax would be `~[@$t0]`. In this example, the thread changes depending on the value of a user-defined pseudo-register. This syntax allows debugger scripts to programmatically select a thread. + +### Controlling Threads in Kernel Mode + +In kernel mode, you cannot control threads by using thread identifiers. For more information about how to access thread-specific information in kernel mode, see [Changing Contexts](changing-contexts.md). + +**Note**  You can use the tilde character ( ~ ) to specify threads during user-mode debugging. In kernel-mode debugging, you can use the tilde to specify processors. For more information about how to specify processors, see [Multiprocessor Syntax](multiprocessor-syntax.md). + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Thread%20Syntax%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/threads-and-processes.md b/windows-driver-docs-pr/debugger/threads-and-processes.md new file mode 100644 index 0000000000..49c46f94c8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/threads-and-processes.md @@ -0,0 +1,50 @@ +--- +title: Threads and Processes +description: Threads and Processes +ms.assetid: 7ba8226c-3fb3-4ed6-8f87-69a7999e34ad +keywords: ["Debugger Engine, threads and processes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Threads and Processes + + +### Terminology + +Thread and a process concepts are different between user-mode debugging and kernel-mode debugging. + +- In *user-mode debugging*, a *process* is an operating system process and a *thread* is an operating system thread. + +- In *kernel-mode debugging*, the [debugger engine](introduction.md#debugger-engine) creates a *virtual process* for each target; this process represents the kernel and does not correspond to any operating system process. For each physical processor in the target computer, the debugger creates a *virtual thread*; these threads represent the processors and do not correspond to any operating system threads. + +When an event occurs, the engine sets the *event process* and *event thread* to the process and thread (operating system or virtual) in which the event occurred. + +The *current thread* is the thread (operating system or virtual) that the engine is currently controlling. The *current process* is the process (operating system or virtual) that the engine is currently controlling. When an event occurs, the current thread and process are initially set to the event thread and process; but, they can be changed using the clients while the session is accessible. + +In kernel mode, the debugger keeps track of an implicit process and implicit thread. The *implicit process* is the operating system process that determines the translation from virtual to physical memory addresses. + +The *implicit thread* is the operating system thread that determines the target's registers, including call stack, stack frame, and instruction offset. + +When an event occurs, the implicit thread and implicit process are initially set to the event thread and process; they can be changed while the session is accessible. + +### Thread and Process Data + +The engine maintains several pieces of information about each thread and process. This includes the system thread and process ID and system handles, and the process environment (PEB), the thread environment block (TEB), and their locations in target's memory. + +### Additional Information + +For details about using thread and processes, see [Controlling Threads and Processes](controlling-threads-and-processes.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Threads%20and%20Processes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tlist-commands.md b/windows-driver-docs-pr/debugger/tlist-commands.md new file mode 100644 index 0000000000..fadfdce3f2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tlist-commands.md @@ -0,0 +1,102 @@ +--- +title: TList Commands +description: The syntax of the TList command is as follows +ms.assetid: d1527ffe-ea80-4e02-9a32-b6eccddc1c6a +keywords: TList Commands, Windows debugging +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- TList Commands +api_type: +- NA +--- + +# TList Commands + + +The syntax of the TList command is as follows: + +``` +tlist [/p ProcessName | PID | Pattern | /t | /c | /e | /k | /m [Module] | /s | /v +``` + +## Parameters + + + **tlist** +Without additional parameters, TList displays all running processes, their process identifiers (PIDs), and the title of the window in which they are running, if any. + + **/p** *ProcessName* +Displays the process identifier (PID) of the specified process. + +*ProcessName* is the name of the process (with or without file name extension), not a pattern. + +If the value of *ProcessName* does not match any running process, TList displays -1. If it matches more than one process name, TList displays only the PID of the first matching process. + + *PID* +Displays detailed information about the process specified by the PID. For information about the display, see the "Remarks" section below. To find a process ID, type **tlist** without additional parameter. + + *Pattern* +Displays detailed information about all processes whose names or window titles match the specified pattern. Pattern can be a complete name or a regular expression. + + **/t** +Displays a task tree in which each process appears as a child of the process that created it. + + **/c** +Displays the command line that started each process. + + **/e** +Displays the session identifier for each process. + + **/k** +Displays the COM components active in each process. + + **/m** *Module* +Lists tasks in which the specified DLL or executable module is loaded. Module can be a complete module name or a module name pattern. + + **/s** +Displays the services that are active in each process. + + **/v** +Displays details of running processes including the process ID, session ID, window title, command line, and the services running in the process. + +### Comments + +In its detailed display of a process (**tlist** *PID* or **tlist** *Pattern*), TList displays the following information. + +- Process ID, executable name, friendly name of the program. + +- Current working directory (CWD). + +- The command line that started the process (CmdLine). + +- Current virtual address space values. + +- Number of threads. + +- A list of threads running in the process. For each thread, TList displays the thread ID (TID), the function that the thread is running, the address of the entry point, the address of the last reported error (if any), and the thread state. + +- A list of the modules loaded for the process. For each module, TList displays the version number, attributes, virtual address of the module, and the module name. + +When using the **/e** parameter, valid session identifiers appear in the process list only under the following conditions. Otherwise, the session identifier is zero (0). + +- On Windows 2000 and Windows Server 2003, at least one user must be connected to a session other than the console session. + +- On Windows XP, Fast User Switching must be enabled and more than one user must be connected to the non-console session. + +- On Windows Vista, where all processes are associated with two Terminal Services sessions by default, at least one user must be connected to the non-console session. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20TList%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tlist-examples.md b/windows-driver-docs-pr/debugger/tlist-examples.md new file mode 100644 index 0000000000..68859a7761 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tlist-examples.md @@ -0,0 +1,184 @@ +--- +title: TList Examples +description: TList Examples +ms.assetid: 9c9a1e81-03c2-4b7c-b0da-b25942548aa9 +keywords: ["TList, TList examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# TList Examples + + +## + + +The following examples demonstrate how to use TList. + +### Simplest TList Command (tlist) + +Typing **tlist** without additional parameters displays a list of running processes, their process IDs (PIDs), and the title of the window in which they are running, if any. + +``` +c:\>tlist + + 0 System Process + 4 System + 308 smss.exe + 356 csrss.exe + 380 winlogon.exe NetDDE Agent + 424 services.exe + 436 lsass.exe + 604 svchost.exe + 776 svchost.exe + 852 spoolsv.exe +1000 clisvcl.exe +1036 InoRpc.exe +1064 InoRT.exe +1076 InoTask.exe +1244 WTTSvc.exe +1492 Sysparse_com.exe OleMainThreadWndName +1980 explorer.exe Program Manager +1764 launch32.exe SMS Client User Application Launcher +1832 msmsgs.exe MSBLNetConn +2076 ctfmon.exe +2128 ISATRAY.EXE IsaTray +4068 tlist.exe +``` + +### Find a process ID (-p) + +The following command uses the **-p** parameter and process name to find the process ID of the Explorer.exe (Explorer) process. + +In response, TList displays the process ID of the Explorer process, 328. + +``` +c:\>tlist -p explorer +328 +``` + +### Find process details using PID + +The following command uses the process ID of the process in which Explorer is running to find detailed information about the Explorer process. + +``` +c:\>tlist 328 +``` + +In response, TList displays details of the Explorer process including the following elements: + +- Process ID, executable name, program friendly name. + +- Current working directory (CWD). + +- The command line that started the process (CmdLine). + +- Current virtual address space values. + +- Number of threads. + +- A list of threads running in the process. For each thread, TList displays the thread ID (TID), the function that the thread is running, the address of the entry point, the address of the last reported error (if any), and the thread state. + +- A list of the modules loaded for the process. For each module, TList displays the version number, attributes, virtual address of the module, and the module name. + +The following is an excerpt of the output resulting from this command. + +``` + 328 explorer.exe Program Manager + CWD: C:\Documents and Settings\user01\ + CmdLine: C:\WINDOWS\Explorer.EXE + VirtualSize: 90120 KB PeakVirtualSize: 104844 KB + WorkingSetSize: 19676 KB PeakWorkingSetSize: 35716 KB + NumberOfThreads: 17 + 332 Win32StartAddr:0x010160cc LastErr:0x00000008 State:Waiting + 1232 Win32StartAddr:0x70a7def2 LastErr:0x00000000 State:Waiting + 1400 Win32StartAddr:0x77f883de LastErr:0x00000000 State:Waiting + 1452 Win32StartAddr:0x77f91e38 LastErr:0x00000000 State:Waiting + 1484 Win32StartAddr:0x70a7def2 LastErr:0x00000006 State:Waiting + 1904 Win32StartAddr:0x74b02ed6 LastErr:0x00000000 State:Ready + 1948 Win32StartAddr:0x72d22ecc LastErr:0x00000000 State:Waiting + .... (thread data deleted here) + + 6.0.2800.1106 shp 0x01000000 Explorer.EXE + 5.1.2600.1217 shp 0x77F50000 ntdll.dll + 5.1.2600.1106 shp 0x77E60000 kernel32.dll + 7.0.2600.1106 shp 0x77C10000 msvcrt.dll + 5.1.2600.1106 shp 0x77DD0000 ADVAPI32.dll + 5.1.2600.1254 shp 0x78000000 RPCRT4.dll + 5.1.2600.1106 shp 0x77C70000 GDI32.dll + 5.1.2600.1255 shp 0x77D40000 USER32.dll + .... (module data deleted here) +``` + +### Find multiple processes (Pattern) + +The following command searches for processes by a regular expression that represents the process name or window name of one or more processes. In this example, the command searches for a process whose process name or window name begins with "ino." + +``` +c:\>tlist ino* +``` + +In response, TList displays process details for Inorpc.exe, Inort.exe, and Inotask.exe. For a description of the output, see the "Find process details using PID" subsection above. + +### Display a process tree (/t) + +The following command displays a tree that represents the processes running on the computer. Processes appear as the children of the process that created them. + +``` +c:\>tlist /t +``` + +The resulting process tree follows. This tree shows, among other things, that the System (4) process created the Smss.exe process, which created Csrss.exe, Winlogon.exe, Lsass.exe and Rundll32.exe. Also, Winlogon.exe created Services.exe, which created all of the service-related processes. + +``` +System Process (0) +System (4) + smss.exe (404) + csrss.exe (452) + winlogon.exe (476) NetDDE Agent + services.exe (520) + svchost.exe (700) + svchost.exe (724) + svchost.exe (864) + svchost.exe (888) + spoolsv.exe (996) + scardsvr.exe (1040) + alg.exe (1172) + atievxx.exe (1200) ATI video bios poller + InoRpc.exe (1248) + InoRT.exe (1264) + InoTask.exe (1308) + mdm.exe (1392) + dllhost.exe (2780) + lsass.exe (532) + rundll32.exe (500) +explorer.exe (328) Program Manager + WLANMON.exe (1728) TI Wireless LAN Monitor + ISATRAY.EXE (1712) IsaTray + cmmon32.exe (456) + WINWORD.EXE (844) Tlist.doc - Microsoft Word + dexplore.exe (2096) Platform SDK - CreateThread +``` + +### Find process by module (/m) + +The following command finds all of the processes running on the computer that load a particular DLL. + +``` +c:\>tlist /m +``` + +In response, TList displays process details for Inorpc.exe, Inort.exe, and Inotask.exe. For a description of the output, see the "Find process details using PID" subsection above. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20TList%20Examples%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tlist.md b/windows-driver-docs-pr/debugger/tlist.md new file mode 100644 index 0000000000..13453b0751 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tlist.md @@ -0,0 +1,51 @@ +--- +title: TList +description: TList (Task List Viewer), Tlist.exe, displays the processes running on the local computer along with useful information about each process. +ms.assetid: 4cba525f-12f0-45c9-8dee-c3e0ab9fd944 +keywords: TList, Task List Viewer, Task List Viewer, See TList +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# TList + + +## + + +TList (Task List Viewer), Tlist.exe, is a command-line tool that displays the processes running on the local computer along with useful information about each process. + +TList displays: + +- All processes running on the computer, along with their process IDs (PIDs). + +- A tree showing which processes created each process. + +- Details of the process, including its virtual memory use and the command that started the process. + +- Threads running in each process, including their thread IDs, entry points, last reported error, and thread state. + +- The modules running in each process, including the version number, attributes, and virtual address of the module. + +You can use TList to search for a process by name or PID, or to find all processes that have loaded a specified module. + +In Windows XP and later versions of Windows, TList was replaced by TaskList (Tasklist.exe), which is described in Help and Support for those systems. TList is included in Debugging Tools for Windows to support users who do not have access to TaskList. + +This section includes: + +[**TList Commands**](tlist-commands.md) + +[TList Examples](tlist-examples.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20TList%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/toolbar-buttons.md b/windows-driver-docs-pr/debugger/toolbar-buttons.md new file mode 100644 index 0000000000..736652088f --- /dev/null +++ b/windows-driver-docs-pr/debugger/toolbar-buttons.md @@ -0,0 +1,145 @@ +--- +title: Toolbar Buttons +description: Toolbar Buttons +ms.assetid: a32702fe-28c5-4b41-b4da-9a750946e5dd +keywords: ["toolbar (WinDbg), button descriptions", "buttons (WinDbg Toolbar), descriptions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Toolbar Buttons + + +## + + +Except for the breakpoint button, each button on the toolbar is equivalent to a menu command. For a full description of each button's effects, see the page for the corresponding menu command. + +The buttons on the toolbar have the following effects. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ButtonDescription
Screen shot of the Open Source File button

Opens a source file as a read-only file. Equivalent to [File | Open Source File](file---open-source-file.md).

Screen shot of the Cut button

Removes the selected text from the active window and puts it on the clipboard. Equivalent to [Edit | Cut](edit---cut.md).

Screen shot of the Copy button

Copies the selected text from the active window to the clipboard. Equivalent to [Edit | Copy](edit---copy.md).

Screen shot of the Paste button

Pastes the text on the clipboard to where the cursor is located. Equivalent to [Edit | Paste](edit---paste.md).

Screen shot of the Go button

Starts or resumes execution. Execution continues until a breakpoint is reached, an exception or event occurs, the process ends, or the debugger breaks into the target. Equivalent to [Debug | Go](debug---go.md).

Screen shot of the Restart button

Restarts execution at the beginning of the process. Equivalent to [Debug | Restart](debug---restart.md).

Screen shot of the Stop Debugging button

Stops execution and terminates the target process permanently. Equivalent to [Debug | Stop Debugging](debug---stop-debugging.md).

Screen shot of the Break button

In user mode, this button stops the process and its threads. In kernel mode, this button breaks into the target computer. Control is returned to the debugger. This button is also useful for cutting off long [Debugger Command window](the-debugger-command-window.md) displays. Equivalent to [Debug | Break](debug---break.md).

Screen shot of the Step Into button

Executes a single instruction. If the instruction is a function call, the debugger steps into the function. Equivalent to [Debug | Step Into](debug---step-into.md).

Screen shot of the Step Over button

Executes a single instruction. If the instruction is a function call, the debugger executes the whole function in one step. Equivalent to [Debug | Step Over](debug---step-over.md).

Screen shot of the Step Out button

Executes the rest of the current function, and breaks when the function return is completed. Equivalent to [Debug | Step Out](debug---step-out.md).

Screen shot of the Run to Cursor button

Executes all instructions from the current instruction up to the instruction marked in the active Disassembly window or Source window. Equivalent to [Debug | Run to Cursor](debug---run-to-cursor.md).

Screen shot of the Breakpoints button

If the active window is a Source or Disassembly window: Inserts a breakpoint at the current line. (If there already is a breakpoint set at the current line, this button removes the breakpoint.)

+

Otherwise: Opens the Breakpoints dialog box like [Edit | Breakpoints](edit---breakpoints.md).

Screen shot of the Command button

Opens or activates the [Debugger Command](the-debugger-command-window.md) window. Equivalent to [View | Command](view---command.md).

Screen shot of the Watch button

Opens or activates the Watch window. Equivalent to [View | Watch](view---watch.md).

Screen shot of the Locals button

Opens or activates the Locals window. Equivalent to [View | Locals](view---locals.md).

Screen shot of the Registers button

Opens or activates the Registers window. Equivalent to [View | Registers](view---registers.md).

Screen shot of the Memory button

Opens a new Memory window. Equivalent to [View | Memory](view---memory.md).

Screen shot of the Call Stack button

Opens or activates the Calls window. Equivalent to [View | Call Stack](view---call-stack.md).

Screen shot of the Disassembly button

Opens or activates the Disassembly window. Equivalent to [View | Disassembly](view---disassembly.md).

Screen shot of the Scratch Pad button

Opens or activates the Scratch Pad. Equivalent to [View | Scratch Pad](view---scratch-pad.md).

Screen shot of the Source Mode button

Switches between source-mode and assembly-mode debugging. Equivalent to selecting or clearing [Debug | Source Mode](debug---source-mode.md).

Screen shot of the Font button

Enables you to change the font that is used in the debugging information windows. Equivalent to [View | Font](view---font.md).

Screen shot of the Options button

Displays the Options dialog box. Equivalent to [View | Options](view---options.md).

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Toolbar%20Buttons%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tools-related-to-debugging-tools-for-windows.md b/windows-driver-docs-pr/debugger/tools-related-to-debugging-tools-for-windows.md new file mode 100644 index 0000000000..ec9de9e83b --- /dev/null +++ b/windows-driver-docs-pr/debugger/tools-related-to-debugging-tools-for-windows.md @@ -0,0 +1,34 @@ +--- +title: Tools Related to Debugging Tools for Windows +description: This section describes tools that are related to debugging but are not included in the Debugging Tools for Windows package. +ms.assetid: A121BF0C-53BF-48E0-9000-3BDA255FD884 +--- + +# Tools Related to Debugging Tools for Windows + + +This section describes tools that are related to debugging but are not included in the Debugging Tools for Windows package. + +[Application Verifier](application-verifier.md) +Monitor application actions while the application runs, subject the application to a variety of stresses and tests, and generate a report about potential errors in application execution or design. Application Verifier is included in the Windows Software Development Kit (SDK) for Windows 8. You can find information about downloading and installing the Windows SDK for Windows 8 [here](http://go.microsoft.com/fwlink/p?LinkID=271979). + +[Windows Error Reporting](windows-error-reporting.md) +You can configure Windows Error Reporting (WER) to write user-mode dump files when exceptions and other errors occur in user-mode code. WER is included in Windows Vista and later versions of Windows. + +## Related topics + + +[Tools Included in Debugging Tools for Windows](extra-tools.md) + +[Debugging Tools for Windows](index.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Tools%20Related%20to%20Debugging%20Tools%20for%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/tracking-contention-in-the-server-process.md b/windows-driver-docs-pr/debugger/tracking-contention-in-the-server-process.md new file mode 100644 index 0000000000..b526cd565a --- /dev/null +++ b/windows-driver-docs-pr/debugger/tracking-contention-in-the-server-process.md @@ -0,0 +1,55 @@ +--- +title: Tracking Contention in the Server Process +description: Tracking Contention in the Server Process +ms.assetid: ef0c0294-a010-439b-82dd-25148e05a7f1 +keywords: ["RPC debugging, tracking contention"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Tracking Contention in the Server Process + + +## + + +In order to service incoming requests, RPC will maintain a set of worker threads. Ideally, the number of threads will be small. However, this ideal situation has only been seen in lab environments, where the server manager routines are carefully tuned. In a real situation, the number of threads will vary depending on server workload, but it can be anywhere from 1 to 50. + +If the number of worker threads is above 50, you may have excessive contention in the server process. Common causes of this are indiscriminate use of the heap, memory pressure, or serializing most activities in a server through a single critical section. + +To see the number of threads in a given server process, use the [**!rpcexts.getthreadinfo**](-rpcexts-getthreadinfo.md) extension, or use DbgRpc with the **-t** switch. Supply the process ID (in the following example, 0xC4): + +``` +D:\wmsg>dbgrpc -t -P c4 +Searching for thread info ... +## PID CELL ID ST TID LASTTIME +----------------------------------- +00c4 0000.0004 03 0000011c 000f164f +00c4 0000.0007 03 00000120 008a6290 +00c4 0000.0015 03 0000018c 008a6236 +00c4 0000.0026 03 00000264 0005c443 +00c4 0000.002d 03 00000268 000265bb +00c4 0000.0030 03 0000026c 000f1d32 +00c4 0000.0034 03 00000388 007251e9 +``` + +In this case, there are only seven worker threads, which is reasonable. + +If there are over 100 threads, a debugger should be attached to this process and the cause investigated. + +**Note**   Running queries such as **dbgrpc -t** remotely is expensive to the server and the network. If you use this query in a script, you should make sure this command is not run too often. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Tracking%20Contention%20in%20the%20Server%20Process%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tracking-down-a-processor-hog.md b/windows-driver-docs-pr/debugger/tracking-down-a-processor-hog.md new file mode 100644 index 0000000000..13cc065242 --- /dev/null +++ b/windows-driver-docs-pr/debugger/tracking-down-a-processor-hog.md @@ -0,0 +1,148 @@ +--- +title: Tracking Down a Processor Hog +description: Tracking Down a Processor Hog +ms.assetid: 8ecd000d-34e6-4471-a040-b50627915a20 +keywords: ["processor hog", "hogging a processor", "starving applications"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Tracking Down a Processor Hog + + +## + + +If one application is consuming ("hogging") all the processor's attention, other processes will end up "starving" and unable to run. + +Use the following procedure to correct a bug of this sort. + +**Debugging an application that is using all the CPU cycles** + +1. **Identify which application is causing this problem:** Use **Task Manager** or **Perfmon** to find which process is using 99% or 100% of the processor's cycles. This may tell you the offending thread as well. + +2. Attach WinDbg, KD, or CDB to this process. + +3. **Identify which thread is causing the problem:** Break into the offending application. Use the [**!runaway 3**](-runaway.md) extension to take a "snapshot" of where all the CPU time is going. Use [**g (Go)**](g--go-.md) and wait a few seconds. Then break in and use **!runaway 3** again. + + ``` + 0:002> !runaway 3 + User Mode Time + Thread Time + 4e0 0:12:16.0312 + 268 0:00:00.0000 + 22c 0:00:00.0000 + Kernel Mode Time + Thread Time + 4e0 0:00:05.0312 + 268 0:00:00.0000 + 22c 0:00:00.0000 + + 0:002> g + + 0:001> !runaway 3 + User Mode Time + Thread Time + 4e0 0:12:37.0609 + 3d4 0:00:00.0000 + 22c 0:00:00.0000 + Kernel Mode Time + Thread Time + 4e0 0:00:07.0421 + 3d4 0:00:00.0000 + 22c 0:00:00.0000 + ``` + + Compare the two sets of numbers and look for the thread whose user-mode time or kernel-mode time has increased the most. Because **!runaway** sorts by descending CPU time, the offending thread is usually the one at the top of the list. In this case, thread 0x4E0 is causing the problem. + +4. Use the [**~ (Thread Status)**](---thread-status-.md) and [**~s (Set Current Thread)**](-s--set-current-thread-.md) commands to make this the current thread: + ``` + 0:001> ~ + 0 Id: 3f4.3d4 Suspend: 1 Teb: 7ffde000 Unfrozen + . 1 Id: 3f4.22c Suspend: 1 Teb: 7ffdd000 Unfrozen + 2 Id: 3f4.4e0 Suspend: 1 Teb: 7ffdc000 Unfrozen + + 0:001> ~2s + ``` + +5. Use [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) to obtain a stack trace of this thread: + ``` + 0:002> kb + FramePtr RetAddr Param1 Param2 Param3 Function Name + 0b4ffc74 77f6c600 000000c8.00000000 77fa5ad0 BuggyProgram!CreateMsgFile+0x1b + 0b4ffce4 01836060 0184f440 00000001 0b4ffe20 BuggyProgram!OpenDestFileStream+0xb3 + 0b4ffd20 01843eba 02b5b920 00000102 02b1e0e0 BuggyProgram!SaveMsgToDestFolder+0xb3 + 0b4ffe20 01855924 0b4ffef0 00145970 0b4ffef0 BuggyProgram!DispatchToConn+0xa4 + 0b4ffe5c 77e112e6 01843e16 0b4ffef0 0b4fff34 RPCRT4!DispatchToStubInC+0x34 + 0b4ffeb0 77e11215 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0 + 0b4ffed0 77e1a3b1 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41 + 0b4fff40 77e181e4 02b1e0b0 00000074 0b4fff90 RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b + 0b4fff60 77e1a5df 02b1e0b0 00000074 00149210 RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91 + 0b4fff90 77e1ac1c 77e15eaf 00149210 0b4fffec RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76 + ``` + +6. Set a breakpoint on the return address of the currently-running function. In this case, the return address is shown on the first line as 0x77F6C600. The return address is equivalent to the function offset shown on the second line (**BuggyProgram!OpenDestFileStream+0xB3**). If no symbols are available for the application, the function name may not appear. Use the [**g (Go)**](g--go-.md) command to execute until this return address is reached, using either the symbolic or hexadecimal address: + ``` + 0:002> g BuggyProgram!OpenDestFileStream+0xb3 + ``` + +7. If this breakpoint is hit, repeat the process. For example, suppose this breakpoint is hit. The following steps should be taken: + + ``` + 0:002> kb + FramePtr RetAddr Param1 Param2 Param3 Function Name + 0b4ffce4 01836060 0184f440 00000001 0b4ffe20 BuggyProgram!OpenDestFileStream+0xb3 + 0b4ffd20 01843eba 02b5b920 00000102 02b1e0e0 BuggyProgram!SaveMsgToDestFolder+0xb3 + 0b4ffe20 01855924 0b4ffef0 00145970 0b4ffef0 BuggyProgram!DispatchToConn+0xa4 + 0b4ffe5c 77e112e6 01843e16 0b4ffef0 0b4fff34 RPCRT4!DispatchToStubInC+0x34 + 0b4ffeb0 77e11215 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0 + 0b4ffed0 77e1a3b1 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41 + 0b4fff40 77e181e4 02b1e0b0 00000074 0b4fff90 RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b + 0b4fff60 77e1a5df 02b1e0b0 00000074 00149210 RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91 + 0b4fff90 77e1ac1c 77e15eaf 00149210 0b4fffec RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76 + + 0:002> g BuggyProgram!SaveMsgToDestFolder+0xb3 + ``` + + If this is hit, continue with: + + ``` + 0:002> kb + FramePtr RetAddr Param1 Param2 Param3 Function Name + 0b4ffd20 01843eba 02b5b920 00000102 02b1e0e0 BuggyProgram!SaveMsgToDestFolder+0xb3 + 0b4ffe20 01855924 0b4ffef0 00145970 0b4ffef0 BuggyProgram!DispatchToConn+0xa4 + 0b4ffe5c 77e112e6 01843e16 0b4ffef0 0b4fff34 RPCRT4!DispatchToStubInC+0x34 + 0b4ffeb0 77e11215 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0 + 0b4ffed0 77e1a3b1 0b4ffef0 00000000 0b4fff34 RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41 + 0b4fff40 77e181e4 02b1e0b0 00000074 0b4fff90 RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b + 0b4fff60 77e1a5df 02b1e0b0 00000074 00149210 RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91 + 0b4fff90 77e1ac1c 77e15eaf 00149210 0b4fffec RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76 + + 0:002> g BuggyProgram!DispatchToConn+0xa4 + ``` + +8. Finally you will find a breakpoint that is not hit. In this case, you should assume that the last **g** command set the target running and it did not break. This means that the **SaveMsgToDestFolder()** function will never return. + +9. Break into the thread again and set a breakpoint on **BuggyProgram!SaveMsgToDestFolder+0xB3** with the [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command. Then use the **g** command repeatedly. If this breakpoint hits immediately, regardless of how many times you have executed the target, it is very likely that you have identified the offending function: + ``` + 0:002> bp BuggyProgram!SaveMsgToDestFolder+0xb3 + + 0:002> g + + 0:002> g + ``` + +10. Use the [**p (Step)**](p--step-.md) command to proceed through the function until you identify the place where the looping sequence of instructions are. You can then analyze the application's source code to identify the cause of the spinning thread. The cause will usually turn out to be a problem in the logic of a **while**, **do-while**, **goto**, or **for** loop. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Tracking%20Down%20a%20Processor%20Hog%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/troubleshooting-hyper-v-debugging.md b/windows-driver-docs-pr/debugger/troubleshooting-hyper-v-debugging.md new file mode 100644 index 0000000000..ecc4720b7f --- /dev/null +++ b/windows-driver-docs-pr/debugger/troubleshooting-hyper-v-debugging.md @@ -0,0 +1,50 @@ +--- +title: Troubleshooting Hyper-V Debugging +description: Troubleshooting Hyper-V Debugging +ms.assetid: e1062300-0855-476c-9375-fdc6bc774949 +--- + +# Troubleshooting Hyper-V Debugging + + +## + + +This section discusses some problems that can arise during Hyper-V debugging. + +### Cabling and Configuration Problems + +If there is no connection string when the root partition starts up, this is usually caused by a cabling or configutation issue. For example, output such as the following might be displayed: + +``` +Waiting to reconnect... +Connected to Windows 6001 x64 target, ptr64 TRUE +Kernel Debugger connection established. +Symbol search path is: c:\mysymbols\ +Executable search path is: +Loading symbols for fffff800`01602000 ntkrnlmp.exe -> ntkrnlmp.exe +ModLoad: fffff800`01602000 fffff800`01b17000 ntkrnlmp.exe +Windows Kernel Version 6001 MP (1 procs) Free x64 +``` + +To address this problem, check the configuration of the root partition by typing **bcdedit** at a command prompt, and verify that the values are correct. + +### Vmdemux Problems + +If you restart vmdemux (virtual machine demultiplexer) after you have begun debugging Windows hypervisor, you must add -channel 0 to its command-line options in order to have the hypervisor channel re-created. This is typically done automatically by Windows hypervisor, but in this case it is not possible, because Windows hypervisor is already being debugged. + +For a full list of the VMDemux command-line options, type vmdemux -? at the command prompt. + +### Problems with Unmodified Partitions + +If you have already set up Hyper-V debugging across a null-modem cable, and have copied the Kdhvcom.dll file to the root partition, and then you later restart the target computer in another partition that does not have this file installed, the debugger may freeze. In this case, restart vmdemux. This problem arises because unmodified partitions cannot handle multiplexed traffic. Typically, vmdemux closes down all the pipes on a clean shutdown. However, a non-clean shutdown, such as doing a hard restart, is not detectable. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Troubleshooting%20Hyper-V%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/tt--trace-to-next-return-.md b/windows-driver-docs-pr/debugger/tt--trace-to-next-return-.md new file mode 100644 index 0000000000..c72c32969d --- /dev/null +++ b/windows-driver-docs-pr/debugger/tt--trace-to-next-return-.md @@ -0,0 +1,99 @@ +--- +title: tt (Trace to Next Return) +description: The tt command executes the program until a return instruction is reached. +ms.assetid: fbc6627f-62e0-4832-8da5-dd4d3323965a +keywords: ["tt (Trace to Next Return) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- tt (Trace to Next Return) +api_type: +- NA +--- + +# tt (Trace to Next Return) + + +The **tt** command executes the program until a return instruction is reached. + +User-Mode + +``` +[~Thread] tt [r] [= StartAddress] [Count] +``` + +Kernel-Mode + +``` +tt [r] [= StartAddress] [Count] +``` + +## Parameters + + + *Thread* +Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see [Thread Syntax](thread-syntax.md). You can specify threads only in user mode. + + **r** +Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the **ttr**, [**pr**](p--step-.md), [**tr**](t--trace-.md), or .prompt\_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands. + +You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are displayed, use the [**rm (Register Mask)**](rm--register-mask-.md) command. + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Count* +Specifies the number of **return** instructions that the debugger must encounter for the **th** command to end. The default value is one. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

All

+ +  + +### Additional Information + +For more information about related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **tt** command causes the target to begin executing. This execution continues until the debugger reaches a **return** instruction or encounters a breakpoint + +If the program counter is already on a **return** instruction, the debugger traces into the return and continues executing until another **return** is reached. This tracing, rather than execution, of the call is the only difference between **tt** and [**pt (Step to Next Return)**](pt--step-to-next-return-.md). + +In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a **return** instruction that is associated with the current source line. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20tt%20%28Trace%20to%20Next%20Return%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/two-firewalls.md b/windows-driver-docs-pr/debugger/two-firewalls.md new file mode 100644 index 0000000000..c0ff2c22eb --- /dev/null +++ b/windows-driver-docs-pr/debugger/two-firewalls.md @@ -0,0 +1,79 @@ +--- +title: Two Firewalls +description: Two Firewalls +ms.assetid: e6192cf8-02a4-4dbe-8ed7-a64f8efc24f6 +keywords: ["remote debugging, two firewalls", "firewalls and remote debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Two Firewalls + + +## + + +In this scenario, you need to perform kernel debugging on a computer in Building A. Your technician is located in Building C, and he or she has access to symbols there. However, both buildings have firewalls that will not allow incoming connections. + +You need to set up a repeater at a neutral site -- say, Building B. Then you can connect A outward to B, and connect C outward to B. + +There will be four computers involved in this scenario: + +- The target computer, located in Building A. + +- The local host computer, located in Building A. This computer will run a KD connection server. It will be connected to the target computer by a debug cable or 1394 cable, and will connect outward to the repeater. Let this computer's IP address be 127.0.10.10. + +- The computer in Building B. This will run the repeater. Let its IP address be 127.0.20.20. + +- The computer in Building C where the technician is located. This computer will run WinDbg as a smart client. Let its IP address be 127.0.30.30. + +First, make sure the target computer is configured for debugging and is attached to the local host computer. In this example, a 1394 cable is used. + +Second, start the repeater on 127.0.20.20: + +``` +dbengprx -p -s tcp:port=9001 -c tcp:port=9000,clicon=127.0.10.10 +``` + +Third, start the KD connection server on 127.0.10.10 in Building A as follows: + +``` +kdsrv -t tcp:port=9000,clicon=127.0.20.20,password=longjump +``` + +Finally, start the smart client on 127.0.30.30 in Building C. (This can actually be done before or after starting the server in Building A.) + +``` +windbg -k kdsrv:server=@{tcp:server=127.0.20.20,port=9001,password=longjump},trans=@{1394:channel=9} -y SymbolPath +``` + +### Five-Computer Scenario + +This scenario can be made even more complicated if you suppose that the symbols are on one computer in Building C, but the technician is at a different computer. + +Suppose that 127.0.30.30 has the symbols, as before, and that its local name is \\\\BOXC. The smart client can be started with the same command as above but with an additional **-server** parameter. Since no one will be using this machine, it will take less processing time if you use KD instead of WinDbg: + +``` +kd -server npipe:pipe=randomname -k kdsrv:server=@{tcp:server=127.0.20.20,port=9001,password=longjump},trans=@{1394:channel=9} -y SymbolPath +``` + +Then the technician, elsewhere in the building, can start a debugging client as follows: + +``` +windbg -remote npipe:server=\\BOXC,pipe=randomname +``` + +Notice that the password must be supplied by the first non-repeater in the chain (the smart client on \\\\BOXC), not by the final debugger in the chain. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Two%20Firewalls%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/typed-data.md b/windows-driver-docs-pr/debugger/typed-data.md new file mode 100644 index 0000000000..96635c7325 --- /dev/null +++ b/windows-driver-docs-pr/debugger/typed-data.md @@ -0,0 +1,42 @@ +--- +title: Typed Data +description: Typed Data +ms.assetid: 44a84dfd-03f8-4d7b-8d71-e4b3ee23d105 +--- + +# Typed Data + + +The EngExtCpp extension framework provides a few classes to help manipulate the target's memory. The [**ExtRemoteData**](https://msdn.microsoft.com/library/windows/hardware/ff544003) class describes a small piece of the target's memory. If the type of this memory is known, it is referred to as *typed data* and is described by [**ExtRemoteTyped**](https://msdn.microsoft.com/library/windows/hardware/ff544162) objects. + +Windows lists can be iterated over by using [**ExtRemoteList**](https://msdn.microsoft.com/library/windows/hardware/ff544114) and, if the type of the objects in the list is known, [**ExtRemoteTypedList**](https://msdn.microsoft.com/library/windows/hardware/ff544173). + +**Note**   Like the client objects in [**ExtExtension**](https://msdn.microsoft.com/library/windows/hardware/ff543981), instances of these classes are only valid while the extension library is used to execute an extension command or format a structure for output. In particular, they should not be cached. For more information about when client objects are valid, see [Client Objects and the Engine](client-objects-and-the-engine.md), . + +  + +### Remote Data + +Remote data should be handled using the class [**ExtRemoteData**](https://msdn.microsoft.com/library/windows/hardware/ff544003). This class is a wrapper around a small section of a target's memory. **ExtRemoteData** automatically retrieves the memory and wraps other common requests with throwing methods. + +### Remote Typed Data + +If the type of the remote data is known, it should be handled using the [**ExtRemoteTyped**](https://msdn.microsoft.com/library/windows/hardware/ff544162) class. This class is an enhanced remote data object that understands data typed with type information from symbols. It is initialized to a particular object by symbol or cast, after which it can be used like an object of the given type. + +### Remote Lists + +To handle remote lists, use the [**ExtRemoteList**](https://msdn.microsoft.com/library/windows/hardware/ff544114) class. This class can be used for either a singly linked or doubly linked list. If the list is doubly linked, it is assumed that the previous pointer immediately follows the next pointer. The class contains methods that can iterate over the list and retrieve nodes both forward and backward. **ExtRemoteList** can be used with either null-terminated or circular lists also. + +### Remote Typed Lists + +To handle remote lists when the type of the nodes in the list is known, use the [**ExtRemoteTypedList**](https://msdn.microsoft.com/library/windows/hardware/ff544173) class. This is an enhanced version of [**ExtRemoteList**](https://msdn.microsoft.com/library/windows/hardware/ff544114). In addition to the basic functionality of **ExtRemoteList**, **ExtRemoteTypedList** automatically determines link offsets from type information. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Typed%20Data%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/types.md b/windows-driver-docs-pr/debugger/types.md new file mode 100644 index 0000000000..414c67576a --- /dev/null +++ b/windows-driver-docs-pr/debugger/types.md @@ -0,0 +1,67 @@ +--- +title: Types +description: Types +ms.assetid: 234f4f36-ccd3-426a-a361-33727e9ece5a +keywords: ["symbols, types", "types"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Types + + +## + + +Type information from a module's symbol file is identified by two pieces of information: a type ID and the base address of the module to which the type belongs. The following methods can be used to find a type ID: + +- [**GetTypeId**](https://msdn.microsoft.com/library/windows/hardware/ff549376) returns the type ID for a given type name. + +- [**GetSymbolTypeId**](https://msdn.microsoft.com/library/windows/hardware/ff549173) returns the type ID for the type of a symbol with the given name. + +- [**GetOffsetTypeId**](https://msdn.microsoft.com/library/windows/hardware/ff548062) returns the type ID for the symbol found at the given location. + +The name and size of a type are returned by [**GetTypeName**](https://msdn.microsoft.com/library/windows/hardware/ff549408) and [**GetTypeSize**](https://msdn.microsoft.com/library/windows/hardware/ff549457), respectively. + +The following convenience methods can be used for reading and writing typed data in the target's physical and virtual memory: + +[**ReadTypedDataPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff554344) + +[**WriteTypedDataPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff561463) + +[**ReadTypedDataVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554345) + +[**WriteTypedDataVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff561466) + +### Printing Typed Data + +To format typed data and send it to the output callbacks, use [*OutputTypedDataPhysical*](https://msdn.microsoft.com/library/windows/hardware/ff553269) and [*OutputTypedDataVirtual*](https://msdn.microsoft.com/library/windows/hardware/ff553274) for data in the target's physical and virtual memory respectively. + +The type options described in [**DEBUG\_TYPEOPTS\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541712) affect how the engine formats typed data before sending it to the output callbacks. + +The type options may be turned on by using [**AddTypeOptions**](https://msdn.microsoft.com/library/windows/hardware/ff537949), and turned off by using [**RemoveTypeOptions**](https://msdn.microsoft.com/library/windows/hardware/ff554551). + +[**GetTypeOptions**](https://msdn.microsoft.com/library/windows/hardware/ff549428) returns the current type options. To set all the type options at once, use [**SetTypeOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556874). + +### Interpreting Raw Data Using Type Information + +The debugger engine API supports interpreting typed data. This provides a way to walk object hierarchies on the target, including finding members of structures, dereferencing pointers, and locating array elements. + +Typed data is described by instances of the [**DEBUG\_TYPED\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff541706) structure and represents regions of memory on the target cast to a particular type. The [**DEBUG\_REQUEST\_EXT\_TYPED\_DATA\_ANSI**](https://msdn.microsoft.com/library/windows/hardware/ff541547)**Request** operation is used to manipulate these instances. They can be initialized to the result of expressions or by casting regions of memory to a specified type. For a list of all the sub-operations that the DEBUG\_REQUEST\_EXT\_TYPED\_DATA\_ANSI **Request** operation supports, see [**EXT\_TDOP**](https://msdn.microsoft.com/library/windows/hardware/ff544529). + +### Additional Information + +For details on output callbacks, see [Input and Output](using-input-and-output.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Types%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/u--unassemble-.md b/windows-driver-docs-pr/debugger/u--unassemble-.md new file mode 100644 index 0000000000..8fb4db9a16 --- /dev/null +++ b/windows-driver-docs-pr/debugger/u--unassemble-.md @@ -0,0 +1,91 @@ +--- +title: u, ub, uu (Unassemble) +description: The u* commands display an assembly translation of the specified program code in memory. This command should not be confused with the ~u (Unfreeze Thread) command. +ms.assetid: 933a308c-61d1-4ca4-89c1-5749ba1b41c1 +keywords: ["u, ub, uu (Unassemble) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- u, ub, uu (Unassemble) +api_type: +- NA +--- + +# u, ub, uu (Unassemble) + + +The **u\*** commands display an assembly translation of the specified program code in memory. + +This command should not be confused with the [**~u (Unfreeze Thread)**](-u--unfreeze-thread-.md) command. + +``` +u[u|b] Range +u[u|b] Address +u[u|b] +``` + +## Parameters + + + *Range* +Specifies the memory range that contains the instructions to disassemble. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). If you use the **b** flag, you must specify *Range* by using the "*Address* **L***Length*" syntax, not the "*Address1 Address2*" syntax. + + *Address* +Specifies the beginning of the memory range to disassemble. Eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor) are unassembled. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + **b** +Determines the memory range to disassemble by counting backward. If **ub** *Address* is used, the disassembled range will be the eight or nine byte range ending with *Address*. If a range is specified using the syntax **ub** *Address* **L***Length*, the disassembled range will be the range of the specified length ending at *Address*. + + **u** +Specifies that the disassembly will continue even if there is a memory read error. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +If you do not specify a parameter for the **u** command, the disassembly begins at the current address and extends eight instructions (on an x86-based or x64-based processor) or nine instructions (on an Itanium-based processor). When you use **ub** without a parameter, the disassembly includes the eight or nine instructions before the current address. + +Do not confuse this command with the [**up (Unassemble from Physical Memory)**](up--unassemble-from-physical-memory-.md). The **u** command disassembles only virtual memory, while the **up** command disassembles only physical memory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20u,%20ub,%20uu%20%28Unassemble%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/u.md b/windows-driver-docs-pr/debugger/u.md new file mode 100644 index 0000000000..21f8570535 --- /dev/null +++ b/windows-driver-docs-pr/debugger/u.md @@ -0,0 +1,46 @@ +--- +title: U (Windows Debugger Glossary) +description: Glossary page - U +Robots: noindex, nofollow +ms.assetid: f3866ed9-eb94-4433-8a73-3b37f7e67303 +--- + +# U + + +**user mode** +Applications and subsystems run within Windows in *user mode*. Processes that run in user mode do so within their own virtual address spaces. They are restricted from gaining direct access to many parts of the system, including system hardware, memory that was not allocated for their use, and other portions of the system that might compromise system integrity. Because processes that run in user mode are effectively isolated from the system and other user-mode processes, they cannot interfere with these resources. + +User-mode processes can be grouped in the following categories: + +- System Processes + + These perform important functions and are integral part of the operating system. System processes include such items as the logon process and the session manager process. + +- Server Processes + + These are operating system services such as the Event Log and the Scheduler. They can be configured to start automatically at boot time. + +- Environment Subsystems + + These are used to create a complete operating system environment for the applications. Windows provides the following three environments: Win32, POSIX, and OS/2. + +- User Applications + + There are five types: Win32, Windows 3.1, Microsoft MS-DOS, POSIX, and OS/2. + +**user-mode debugging** +A debugger session in which the target is running in user mode. + +**user-mode target** +See target application. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20U%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/uf--unassemble-function-.md b/windows-driver-docs-pr/debugger/uf--unassemble-function-.md new file mode 100644 index 0000000000..fe31ede284 --- /dev/null +++ b/windows-driver-docs-pr/debugger/uf--unassemble-function-.md @@ -0,0 +1,97 @@ +--- +title: uf (Unassemble Function) +description: The uf command displays an assembly translation of the specified function in memory. +ms.assetid: 344e3afd-6b8d-48f2-9e07-dd7e1937f71b +keywords: ["uf (Unassemble Function) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- uf (Unassemble Function) +api_type: +- NA +--- + +# uf (Unassemble Function) + + +The **uf** command displays an assembly translation of the specified function in memory. + +``` +uf [Options] Address +``` + +## Parameters + + + *Options* +One or more of the following options: + +**/c** +Displays only the call instructions in a routine instead of the full disassembly. Call instructions can be useful for determination of caller and callee relationships from disassembled code. + +**/D** +Creates linked callee names for navigation of the call graph. + +**/m** +Relaxes the blocking requirements to permit multiple exits. + +**/o** +Sorts the display by address instead of by function offset. This option presents a memory-layout view of a full function. + +**/O** +Creates linked call lines for accessing call information and creating breakpoints. + +**/i** +Displays the number of instructions in a routine. + + *Address* +Specifies the address of the function to disassemble. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +The display shows the whole function, according to the function order. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20uf%20%28Unassemble%20Function%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/umdh-commands.md b/windows-driver-docs-pr/debugger/umdh-commands.md new file mode 100644 index 0000000000..dcaa142bc9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/umdh-commands.md @@ -0,0 +1,33 @@ +--- +title: UMDH Commands +description: UMDH Commands +ms.assetid: 85508eb6-b041-4d2d-a431-d8bcfe874141 +keywords: ["UMDH, UMDH commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# UMDH Commands + + +## + + +UMDH has two different modes, each with its own command syntax and parameters: + +- [**Analyze a Running Process**](analyze-a-running-process.md) - Displays all the heap allocation in a process. + +- [**Analyze UMDH Logs**](analyze-umdh-logs.md) - Compares the allocation list made at two different times for the same process. Analyzing the differences can help to identify memory leaks. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20UMDH%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/umdh.md b/windows-driver-docs-pr/debugger/umdh.md new file mode 100644 index 0000000000..09c62827a6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/umdh.md @@ -0,0 +1,43 @@ +--- +title: User-Mode Dump Heap (UMDH) tool +description: The User-Mode Dump Heap (UMDH) tool, Umdh.exe, analyzes the Microsoft Windows heap memory allocations for a given process +ms.assetid: 112795a9-57c0-43a4-9f21-2a8655b65d1b +keywords: UMDH, User-Mode Dump Heap +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# UMDH + + +## + + +The User-Mode Dump Heap (UMDH) tool, Umdh.exe, analyzes the Microsoft Windows heap memory allocations for a given process. UMDH has the following modes. + +- **Analyze a running process** ("Mode 1"). UMDH captures and analyzes the heap memory allocations for a process. For each allocation, UMDH displays the size of the allocation, the size of the overhead, the pointer to the allocation and the allocation stack. If a process has more than one active memory heap, UMDH captures all heaps. This analysis can be displayed in realtime or saved in a log file. + +- **Analyze UMDH log files** ("Mode 2"). UMDH analyzes the log files it has previously created. UMDH can compare two logs created for the same process at different times, and display the calls in which the allocation size increased the most. This technique can be used to find memory leaks. + +This section includes: + +[Preparing to Use UMDH](preparing-to-use-umdh.md) + +[UMDH Commands](umdh-commands.md) + +[Interpreting a UMDH Log](interpreting-a-umdh-log.md) + +[Interpreting a Log Comparison](interpreting-a-log-comparison.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20UMDH%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/undocking-a-window.md b/windows-driver-docs-pr/debugger/undocking-a-window.md new file mode 100644 index 0000000000..6edcf8963b --- /dev/null +++ b/windows-driver-docs-pr/debugger/undocking-a-window.md @@ -0,0 +1,41 @@ +--- +title: Undocking a Window +description: Undocking a Window +ms.assetid: e035b511-949f-4ce1-a948-a8b35fd6562f +keywords: ["debugging information windows, undocking windows", "undocked windows", "undocking windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Undocking a Window + + +## + + +To undock a window and make it a floating window, do one of the following: + +- Double-click the window's title bar. + +- Open the shortcut menu by right-clicking the window's title bar, right-clicking the window's tab if it is part of a tabbed collection, or clicking the window's icon in the upper-right corner, and then click **Undock**. + +- In the WinDbg window, on the **Window** menu, click **Undock All**. This command changes all of the docked windows into floating windows. + +When you undock a window by one of the preceding methods, the window returns to its previous undocked position. + +You can also drag a docked window by clicking its title bar. This action enables you to move the window to a different docked position or undock it. (Dragging a docked window to a new position works exactly like dragging a floating window to a new position. For more information about dragging a floating window to a new position, see [Docking a Window](docking-a-window.md).) + +When you try to undock or drag a tabbed window by any of these methods, only the active window in the tabbed collection is moved. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Undocking%20a%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/unresolved-breakpoints---bu-breakpoints-.md b/windows-driver-docs-pr/debugger/unresolved-breakpoints---bu-breakpoints-.md new file mode 100644 index 0000000000..ee1eb7ae02 --- /dev/null +++ b/windows-driver-docs-pr/debugger/unresolved-breakpoints---bu-breakpoints-.md @@ -0,0 +1,42 @@ +--- +title: Unresolved Breakpoints (bu Breakpoints) +description: Unresolved Breakpoints (bu Breakpoints) +ms.assetid: 2c97314b-3098-47a0-8f15-3b7d61c95529 +keywords: ["breakpoints, deferred", "deferred breakpoints", "breakpoints, BP versus BU", "breakpoints, unresolved"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Unresolved Breakpoints (bu Breakpoints) + + +If a [breakpoint](using-breakpoints.md) is set for a routine name that has not been loaded, the breakpoint is called a *deferred*, *virtual*, or *unresolved* breakpoint. (These terms are used interchangeably.) Unresolved breakpoints are not associated with any specific load of a module. Every time that a new application is loaded, it is checked for this routine name. If this routine appears, the debugger computes the actual coded address of the virtual breakpoint and enables the breakpoint. + +If you set a breakpoint by using the **bu** command, the breakpoint is automatically considered unresolved. If this breakpoint is in a loaded module, the breakpoint is still enabled and functions normally. However, if the module is later unloaded and reloaded, this breakpoint does not vanish. On the other hand, a breakpoint that you set with **bp** is immediately resolved to an address. + +There are three primary differences between **bp** breakpoints and **bu** breakpoints: + +- A **bp** breakpoint location is always converted to an address. If a module change moves the code at which a **bp** breakpoint was set, the breakpoint remains at the same address. On the other hand, a **bu** breakpoint remains associated with the symbolic value (typically a symbol plus an offset) that was used, and it tracks this symbolic location even if its address changes. + +- If a **bp** breakpoint address is found in a loaded module, and if that module is later unloaded, the breakpoint is removed from the breakpoint list. On the other hand, **bu** breakpoints persist after repeated unloads and loads. + +- Breakpoints that you set with **bp** are not saved in WinDbg [workspaces](using-workspaces.md). Breakpoints that are set with **bu** are saved in workspaces. + +### Controlling Address Breakpoints and Unresolved Breakpoints + +Address breakpoints can be created with the [**bp (Set Breakpoint)**](bp--bu--bm--set-breakpoint-.md) command, or the **bm (Set Symbol Breakpoint)** command when the **/d** switch is included. Unresolved breakpoints can be created with the **bu (Set Unresolved Breakpoint)** command, or the **bm** command when the **/d** switch is not included. Commands that disable, enable, and modify breakpoints apply to all kinds of breakpoints. Commands that display a list of breakpoints include all breakpoints, and indicate the type of each. For a listing of these commands, see [Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md). + +The WinDbg **Breakpoints** dialog box displays all breakpoints, indicating unresolved breakpoints with the notation "u". This dialog box can be used to modify any breakpoint.The **Command** text box on this dialog box can be used to create any type of breakpoint; if the type is omitted, an unresolved breakpoint is created. For details, see [Edit | Breakpoints](edit---breakpoints.md). When you set a breakpoint by using the mouse in the WinDbg [Disassembly window](disassembly-window.md) or [Source window](source-window.md), the debugger creates an unresolved breakpoint. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Unresolved%20Breakpoints%20%28bu%20Breakpoints%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/up--unassemble-from-physical-memory-.md b/windows-driver-docs-pr/debugger/up--unassemble-from-physical-memory-.md new file mode 100644 index 0000000000..464ff9917a --- /dev/null +++ b/windows-driver-docs-pr/debugger/up--unassemble-from-physical-memory-.md @@ -0,0 +1,83 @@ +--- +title: up (Unassemble from Physical Memory) +description: The up command displays an assembly translation of the specified program code in physical memory. +ms.assetid: 4db66566-b7b8-4f1e-9492-b4b78016b45a +keywords: ["up (Unassemble from Physical Memory) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- up (Unassemble from Physical Memory) +api_type: +- NA +--- + +# up (Unassemble from Physical Memory) + + +The **up** command displays an assembly translation of the specified program code in physical memory. + +``` +up Range +up Address +up +``` + +## Parameters + + + *Range* +Specifies the memory range in physical memory that contains the instructions to disassemble. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Address* +Specifies the beginning of the memory range in physical memory to disassemble. Eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor) are unassembled. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about assembly debugging and related commands, see [Debugging in Assembly Mode](debugging-in-assembly-mode.md). + +Remarks +------- + +If you do not specify a parameter for the **up** command, the disassembly begins at the current address and extends eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor). + +Do not confuse this command with the [**u (Unassemble)**](u--unassemble-.md). The **up** command disassembles only physical memory, while the **u** command disassembles only virtual memory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20up%20%28Unassemble%20from%20Physical%20Memory%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ur--unassemble-real-mode-bios-.md b/windows-driver-docs-pr/debugger/ur--unassemble-real-mode-bios-.md new file mode 100644 index 0000000000..2b292203d0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/ur--unassemble-real-mode-bios-.md @@ -0,0 +1,87 @@ +--- +title: ur (Unassemble Real Mode BIOS) +description: The ur command displays an assembly translation of the specified 16-bit real-mode code. +ms.assetid: 7ea3421a-3841-47ea-ab40-99d10516bb14 +keywords: ["ur (Unassemble Real Mode BIOS) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ur (Unassemble Real Mode BIOS) +api_type: +- NA +--- + +# ur (Unassemble Real Mode BIOS) + + +The **ur** command displays an assembly translation of the specified 16-bit real-mode code. + +``` +ur Range +ur Address +ur +``` + +## Parameters + + + *Range* +Specifies the memory range that contains the instructions to disassemble. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *Address* +Specifies the beginning of the memory range to disassemble. Eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor) are unassembled. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +### Additional Information + +For more information about how to debug BIOS code, see [Debugging BIOS Code](debugging-bios-code.md). + +Remarks +------- + +If you do not specify *Range* or *Address*, the disassembly begins at the current address and extends eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor). + +If you are examining 16-bit real-mode code on an x86-based processor, both the **ur** command and the [**u (Unassemble)**](u--unassemble-.md) command give correct results. + +However, if real-mode code exists in a location where the debugger is not expecting it (for example, a non-x86 computer that is running or emulating x86-based BIOS code from a plug-in card), you must use **ur** to correctly disassemble this code. + +If you use **ur** on 32-bit or 64-bit code, the command tries to disassemble the code as if it were 16-bit code. This situation produces meaningless results. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ur%20%28Unassemble%20Real%20Mode%20BIOS%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/usb-2-0-extensions.md b/windows-driver-docs-pr/debugger/usb-2-0-extensions.md new file mode 100644 index 0000000000..f4b3de50c0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/usb-2-0-extensions.md @@ -0,0 +1,106 @@ +--- +title: USB 2.0 Extensions +description: This section describes the USB 2.0 debugger extension commands. These commands display information from data structures maintained by drivers in the USB 2.0 driver stack. +ms.assetid: 42A78738-CE0D-42EA-9E3D-04CDC2060266 +--- + +# USB 2.0 Extensions + + +This section describes the USB 2.0 debugger extension commands. These commands display information from data structures maintained by drivers in the USB 2.0 driver stack. For more information about these three drivers, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkId=251983). + +The USB 2.0 debugger extension commands are implemented in Usbkd.dll. To load the Usbkd commands, enter **.load usbkd.dll** in the debugger. + +## USB 2.0 Tree + + +The USB 2.0 tree contains the device nodes that represent execution units on EHCI host controller devices along with the child nodes that represent hubs and connected devices. This diagram shows an example of a USB 2.0 tree. + +![diagram that shows usb 2tree](images/usbkd01.png) + +The diagram shows one physical host controller device that has two execution units. Each execution unit appears as a device node in the Plug and Play device tree. One execution unit appears as a UHCI USB host controller node, and the other execution unit shows as an EHCI USB host controller node. Each of those nodes has a child node that represents a USB root hub. Each root hub has a single child node that represents a connected USB device. + +Notice that the diagram is not a tree in the sense that not all nodes descend from a single parent node. However, when we use the term *USB 2.0 tree*, we are referring to the set of device nodes that represent execution units on EHCI host controller devices along with the nodes for hubs and connected devices. + +## Getting started with USB 2.0 debugging + + +To start debugging a USB 2.0 issue, enter the [**!usb2tree**](-usbkd-usb2tree.md) command. The **!usb2tree** command displays a list of commands and addresses that you can use to investigate host controllers, hubs, ports, devices, endpoints, and other elements of the USB 2.0 tree. + +## In this section + + +- [**!usbkd.usbhelp**](-usbkd-usbhelp.md) +- [**!usbkd.\_ehcidd**](-usbkd--ehcidd.md) +- [**!usbkd.\_ehciep**](-usbkd--ehciep.md) +- [**!usbkd.\_ehciframe**](-usbkd--ehciframe.md) +- [**!usbkd.\_ehciqh**](-usbkd--ehciqh.md) +- [**!usbkd.\_ehciregs**](-usbkd--ehciregs.md) +- [**!usbkd.\_ehcisitd**](-usbkd--ehcisitd.md) +- [**!usbkd.\_ehcistq**](-usbkd--ehcistq.md) +- [**!usbkd.\_ehcitd**](-usbkd--ehcitd.md) +- [**!usbkd.\_ehcitfer**](-usbkd--ehcitfer.md) +- [**!usbkd.\_ehciitd**](-usbkd--ehciitd.md) +- [**!usbkd.doesdumphaveusbdata**](-usbkd-doesdumphaveusbdata.md) +- [**!usbkd.isthisdumpasyncissue**](-usbkd-isthisdumpasyncissue.md) +- [**!usbkd.urbfunc**](-usbkd-urbfunc.md) +- [**!usbkd.usb2**](-usbkd-usb2.md) +- [**!usbkd.usb2tree**](-usbkd-usb2tree.md) +- [**!usbkd.usbchain**](-usbkd-usbchain.md) +- [**!usbkd.usbdevobj**](-usbkd-usbdevobj.md) +- [**!usbkd.usbdpc**](-usbkd-usbdpc.md) +- [**!usbkd.ehci\_info\_from\_fdo**](-usbkd-ehci-info-from-fdo.md) +- [**!usbkd.usbdevh**](-usbkd-usbdevh.md) +- [**!usbkd.usbep**](-usbkd-usbep.md) +- [**!usbkd.usbfaildata**](-usbkd-usbfaildata.md) +- [**!usbkd.usbhcdext**](-usbkd-usbhcdext.md) +- [**!usbkd.usbdstatus**](-usbkd-usbdstatus.md) +- [**!usbkd.usbhcdhccontext**](-usbkd-usbhcdhccontext.md) +- [**!usbkd.usbhcdlist**](-usbkd-usbhcdlist.md) +- [**!usbkd.usbhcdlistlogs**](-usbkd-usbhcdlistlogs.md) +- [**!usbkd.usbhcdlog**](-usbkd-usbhcdlog.md) +- [**!usbkd.usbhcdlogex**](-usbkd-usbhcdlogex.md) +- [**!usbkd.usbhcdpnp**](-usbkd-usbhcdpnp.md) +- [**!usbkd.usbhcdpow**](-usbkd-usbhcdpow.md) +- [**!usbkd.hub2\_info\_from\_fdo**](-usbkd-hub2-info-from-fdo.md) +- [**!usbkd.usbhuberr**](-usbkd-usbhuberr.md) +- [**!usbkd.usbhubext**](-usbkd-usbhubext.md) +- [**!usbkd.usbhubinfo**](-usbkd-usbhubinfo.md) +- [**!usbkd.usbhublog**](-usbkd-usbhublog.md) +- [**!usbkd.usbhubmddevext**](-usbkd-usbhubmddevext.md) +- [**!usbkd.usbhubmdpd**](-usbkd-usbhubmdpd.md) +- [**!usbkd.usbhubpd**](-usbkd-usbhubpd.md) +- [**!usbkd.usbhubs**](-usbkd-usbhubs.md) +- [**!usbkd.usblist**](-usbkd-usblist.md) +- [**!usbkd.usbpo**](-usbkd-usbpo.md) +- [**!usbkd.usbpdos**](-usbkd-usbpdos.md) +- [**!usbkd.usbpdoxls**](-usbkd-usbpdoxls.md) +- [**!usbkd.usbpnp**](-usbkd-usbpnp.md) +- [**!usbkd.usbportisasyncadv**](-usbkd-usbportisasyncadv.md) +- [**!usbkd.usbportmdportlog**](-usbkd-usbportmdportlog.md) +- [**!usbkd.usbportmddcontext**](-usbkd-usbportmddcontext.md) +- [**!usbkd.usbportmddevext**](-usbkd-usbportmddevext.md) +- [**!usbkd.usbtriage**](-usbkd-usbtriage.md) +- [**!usbkd.usbtt**](-usbkd-usbtt.md) +- [**!usbkd.usbtx**](-usbkd-usbtx.md) +- [**!usbkd.usbusb2ep**](-usbkd-usbusb2ep.md) +- [**!usbkd.usbusb2tt**](-usbkd-usbusb2tt.md) +- [**!usbkd.usbver**](-usbkd-usbver.md) + +## Related topics + + +[USB 3.0 Extensions](usb-3-extensions.md) + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20USB%202.0%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/usb-3-0-data-structures.md b/windows-driver-docs-pr/debugger/usb-3-0-data-structures.md new file mode 100644 index 0000000000..b1457ba37e --- /dev/null +++ b/windows-driver-docs-pr/debugger/usb-3-0-data-structures.md @@ -0,0 +1,75 @@ +--- +title: USB 3.0 Data Structures +description: This topic describes the data structures used by the USB 3.0 host controller driver. +ms.assetid: 39BD7413-48A5-4199-BA8E-D2A77E4D23F1 +--- + +# USB 3.0 Data Structures + + +This topic describes the data structures used by the USB 3.0 host controller driver. Understanding these data structures will help you use the [USB 3.0](usb-3-extensions.md) and [RCDRKD](rcdrkd-extensions.md) debugger extension commands effectively. The data structures presented here have names that are consistent with the [USB 3.0 specification](http://go.microsoft.com/fwlink/p?LinkID=224892). Familiarity with the USB 3.0 specification will further enhance your ability to use the extension commands to debug USB 3.0 drivers. + +The USB 3.0 host controller driver is part of the USB 3.0 core driver stack. For more information, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkID=251983). + +Each USB 3.0 host controller can have up to 255 devices, and each device can have up to 31 endpoints. The following diagram shows some of the data structures that represent one host controller and the connected devices. + +![usb 3.0 data structures that represent one host controller and the connected devices that have device context that in turn have slot and end point context](images/usb3structures01.png) + +## Device Context Base Array + + +The Device Context Base Array is an array of pointers to Device Context structures. There is one Device Context structure for each device connected to the host controller. Elements 1 through 255 point to Device Context structures. Element 0 points to a context structure for the host controller. + +## Device Context and Slot Context + + +A Device Context structure holds an array of pointers to Endpoint Context structures. There is one Endpoint Context structure for each endpoint on the device. Elements 1 through 31 point to Endpoint Context structures. Element 0 points to a Slot Context structure, which holds context information for the device. + +## Command Ring + + +The Command Ring is used by software to pass commands to the host controller. Some of these commands are directed at the host controller, and some are directed at particular devices connected to the host controller. + +## Event Ring + + +The Event Ring is used by the host controller to pass events to software. That is, the Event Ring is a structure that the host controller uses to inform drivers that an action has completed. + +## Doorbell Register Array + + +The Doorbell Register Array is an array of doorbell registers, one for each device connected to the host controller. Elements 1 through 255 are doorbell registers. Element 0 indicates whether there is a pending command in the Command Ring. + +Software notifies the host controller that it has device-related or endpoint-related work to perform by writing context information into the doorbell register for the device. + +The following diagram continues to the right of the preceding diagram. It shows additional data structures that represent a single endpoint. + +![usb 3.0 data structure showing end point context that has multiple trbs that have data and tds](images/usb3structures02.png) + +## Transfer Ring + + +Each endpoint has one or more Transfer Rings. A Transfer Ring is an array of Transfer Request Blocks (TRBs). Each TRB points to a block of contiguous data (up to 64 KB) that will be transferred between hardware and memory as a single unit. + +When the USB 3.0 core stack receives a transfer request from a USB client driver, it identifies the Endpoint Context for the transfer, and then breaks the transfer request into one or more Transfer Descriptors (TDs). Each TD contains one or more TRBs. + +## Endpoint Context + + +An Endpoint Context structure holds context information for a single endpoint. It also has **Dequeue** and **Enqueue** members, which are used to track where TRBs are being consumed by the hardware and where TRBs are being added by software. + +## Related topics + + +[USB Debugging Innovations in Windows 8](http://go.microsoft.com/fwlink/p/?LinkID=249153) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20USB%203.0%20Data%20Structures%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/usb-3-extensions.md b/windows-driver-docs-pr/debugger/usb-3-extensions.md new file mode 100644 index 0000000000..cef7add081 --- /dev/null +++ b/windows-driver-docs-pr/debugger/usb-3-extensions.md @@ -0,0 +1,88 @@ +--- +title: USB 3.0 Extensions +description: This section describes the USB 3.0 debugger extension commands. +ms.assetid: 7CE2B9F8-50EF-41C0-B306-B7B7A6DA1636 +--- + +# USB 3.0 Extensions + + +This section describes the USB 3.0 debugger extension commands. These commands display information from data structures maintained by three drivers in the USB 3.0 stack: the USB 3.0 hub driver, the USB host controller extension driver, and the USB 3.0 host controller driver. For more information about these three drivers, see [USB Driver Stack Architecture](http://go.microsoft.com/fwlink/p?LinkId=251983). For an explanation of the data structures used by the drivers in the USB 3.0 stack, see [USB 3.0 Data Structures](usb-3-0-data-structures.md) and Part 2 of the [USB Debugging Innovations in Windows 8](http://go.microsoft.com/fwlink/p/?LinkID=249153) video. + +The USB 3.0 debugger extension commands are implemented in Usb3kd.dll. To load the Usb3kd commands, enter **.load usb3kd.dll** in the debugger. + +## USB 3.0 Tree + + +The USB 3.0 tree contains all USB 3.0 host controllers and all hubs and devices that are connected to USB 3.0 host controllers. The following diagram shows an example of a USB 3.0 tree. + +![usb 3.0 tree showing a mix of usb 3.0 and usb 2.0 devices roots and controllers](images/usb3tree01.png) + +The tree shown in the diagram has two USB 3.0 host controllers. Notice that not every device shown in the diagram is a USB 3.0 device. But all of the devices shown (including the hubs) are part of the USB 3.0 tree, because each device is on a branch that originates at a USB 3.0 host controller. + +You can think of the diagram as two trees, one for each host controller. However, when we use the term *USB 3.0 tree*, we are referring to the set of all USB 3.0 host controllers along with their connected hubs and devices. + +## Getting started with USB 3.0 debugging + + +To start debugging a USB 3.0 issue, enter the [**!usb\_tree**](-usb3kd-usb-tree.md) command. The **!usb\_tree** command displays a list of commands and addresses that you can use to investigate host controllers, hubs, ports, devices, endpoints, and other elements of the USB 3.0 tree. + +## Hub commands + + +The following extension commands display information about USB 3.0 hubs, devices, and ports. The displayed information is based on data structures maintained by the USB 3.0 hub driver. + +- [**!usb3kd.usb\_tree**](-usb3kd-usb-tree.md) +- [**!usb3kd.hub\_info**](-usb3kd-hub-info.md) +- [**!usb3kd.hub\_info\_from\_fdo**](-usb3kd-hub-info-from-fdo.md) +- [**!usb3kd.device\_info**](-usb3kd-device-info.md) +- [**!usb3kd.device\_info\_from\_pdo**](-usb3kd-device-info-from-pdo.md) +- [**!usb3kd.port\_info**](-usb3kd-port-info.md) + +## UCX commands + + +The following extension commands display information about USB 3.0 host controllers, devices, and ports. The displayed information is based on data structures maintained by the USB host controller extension driver. + +- [**!usb3kd.ucx\_controller\_list**](-usb3kd-ucx-controller-list.md) +- [**!usb3kd.ucx\_controller**](-usb3kd-ucx-controller.md) +- [**!usb3kd.ucx\_device**](-usb3kd-ucx-device.md) +- [**!usb3kd.ucx\_endpoint**](-usb3kd-ucx-endpoint.md) + +## Host controller commands + + +The following extension commands display information from data structures maintained by the USB 3.0 host controller driver. + +- [**!usb3kd.xhci\_dumpall**](-usb3kd-xhci-dumpall.md) +- [**!usb3kd.xhci\_capability**](-usb3kd-xhci-capability.md) +- [**!usb3kd.xhci\_commandring**](-usb3kd-xhci-commandring.md) +- [**!usb3kd.xhci\_deviceslots**](-usb3kd-xhci-deviceslots.md) +- [**!usb3kd.xhci\_eventring**](-usb3kd-xhci-eventring.md) +- [**!usb3kd.xhci\_registers**](-usb3kd-xhci-registers.md) +- [**!usb3kd.xhci\_resourceusage**](-usb3kd-xhci-resourceusage.md) +- [**!usb3kd.xhci\_trb**](-usb3kd-xhci-trb.md) +- [**!usb3kd.xhci\_transferring**](-usb3kd-xhci-transferring.md) +- [**!usb3kd.xhci\_findowner**](-xhci-findowner.md) + +## Miscellaneous commands + + +- [**!usb3kd.usbdstatus**](-usb3kd-usbdstatus.md) +- [**!usb3kd.urb**](-usb3kd-urb.md) + +## Related topics + + +[RCDRKD Extensions](rcdrkd-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20USB%203.0%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/usbview.md b/windows-driver-docs-pr/debugger/usbview.md new file mode 100644 index 0000000000..8f234c8817 --- /dev/null +++ b/windows-driver-docs-pr/debugger/usbview.md @@ -0,0 +1,42 @@ +--- +title: USBView +description: USBView +ms.assetid: 88d2a93f-2e7c-493c-bb9e-487f1d1f2016 +keywords: ["USBView"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# USBView + + +USBView (Universal Serial Bus Viewer, Usbview.exe) is a Windows graphical user interface application that enables you to browse all USB controllers and connected USB devices on your computer. USBView works on all versions of Windows. + +## Where to get USBView + + +USBView is included in [Debugging Tools for Windows](index.md). + +[USBView](http://go.microsoft.com/fwlink/p/?LinkId=618004) is also available in the [Windows driver samples](http://go.microsoft.com/fwlink/p/?LinkId=616507) repository on GitHub. + +## Using USBView + + +USBView can enumerate USB host controllers, USB hubs, and attached USB devices. It can also query information about the devices from the registry and through USB requests to the devices. + +The main USBView window contains two panes. The left pane displays a connection-oriented tree view, enabling you to select any USB device. + +The right pane displays the USB data structures that pertain to the selected USB device. These structures include Device, Configuration, Interface, and Endpoint Descriptors, as well as the current device configuration. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20USBView%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/user-mode-driver-framework-debugging.md b/windows-driver-docs-pr/debugger/user-mode-driver-framework-debugging.md new file mode 100644 index 0000000000..daa663b89e --- /dev/null +++ b/windows-driver-docs-pr/debugger/user-mode-driver-framework-debugging.md @@ -0,0 +1,40 @@ +--- +title: User-Mode Driver Framework Debugging +description: User-Mode Driver Framework Debugging +ms.assetid: f59a420e-57d3-4ae0-84e3-58ec6e088b63 +keywords: ["User-Mode Driver Framework debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# User-Mode Driver Framework Debugging + + +For an overview of how to debug User-Mode Driver Framework (UMDF) drivers, including information on how to start this kind of debugging session, see the [Debugging UMDF Drivers](http://go.microsoft.com/fwlink/p/?linkid=153578) section of the Windows Driver Kit (WDK) documentation. + +### UMDF Debugging Extensions + +User-Mode Driver Framework (UMDF) debugging extensions are implemented in the extension module Wudfext.dll. You can use these extensions to debug drivers that use UMDF. + +For a complete description of the extension commands in Wudfext.dll, see [User-Mode Driver Framework Extensions (Wudfext.dll)](user-mode-driver-framework-extensions--wudfext-dll-.md). + +These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions on the Windows version or UMDF version that is required; these restrictions are noted on the individual reference pages. + +**Note**  When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. If your driver name exceeds the maximum length, your driver will fail to load. + +  + +To use this extension library, you must load the library into your debugger. For information about how to load extension libraries into a debugger, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20User-Mode%20Driver%20Framework%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/user-mode-driver-framework-extensions--wudfext-dll-.md b/windows-driver-docs-pr/debugger/user-mode-driver-framework-extensions--wudfext-dll-.md new file mode 100644 index 0000000000..8842ed4ba6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/user-mode-driver-framework-extensions--wudfext-dll-.md @@ -0,0 +1,34 @@ +--- +title: User-Mode Driver Framework Extensions (Wudfext.dll) +description: User-Mode Driver Framework Extensions (Wudfext.dll) +ms.assetid: 56b1c794-5740-44fd-9e5b-691fbfefe5a9 +keywords: ["user-mode driver framework extensions (wudfext.dll)", "user-mode driver framework debugging, extensions (wudfext.dll)", "wudfext.dll (user-mode driver framework extensions)", "extensions, user-mode driver framework"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# User-Mode Driver Framework Extensions (Wudfext.dll) + + +Extension commands that are useful for debugging User-Mode Driver Framework drivers are implemented in Wudfext.dll. + +You can use the Wudfext.dll extension commands in Microsoft Windows XP and later operating systems. Some extensions have additional restrictions on the Windows version or UMDF version that is required; these restrictions are noted on the individual reference pages. + +**Note**  When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. If your driver name exceeds the maximum length, your driver will fail to load. + +  + +For ways to use these extensions, see [User-Mode Driver Framework Debugging](user-mode-driver-framework-debugging.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20User-Mode%20Driver%20Framework%20Extensions%20%28Wudfext.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/user-mode-dump-files.md b/windows-driver-docs-pr/debugger/user-mode-dump-files.md new file mode 100644 index 0000000000..795fa7b9e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/user-mode-dump-files.md @@ -0,0 +1,35 @@ +--- +title: User-Mode Dump Files +description: User-Mode Dump Files +ms.assetid: bef29d75-6620-4219-b402-36fbddc4fe1f +keywords: ["dump file, user-mode"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# User-Mode Dump Files + + +## + + +This section includes: + +[Varieties of User-Mode Dump Files](varieties-of-user-mode-dump-files.md) + +[Creating a User-Mode Dump File](creating-a-user-mode-dump-file.md) + +[Analyzing a User-Mode Dump File](analyzing-a-user-mode-dump-file.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20User-Mode%20Dump%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/user-mode-extensions.md b/windows-driver-docs-pr/debugger/user-mode-extensions.md new file mode 100644 index 0000000000..3ed87a2c23 --- /dev/null +++ b/windows-driver-docs-pr/debugger/user-mode-extensions.md @@ -0,0 +1,37 @@ +--- +title: User-Mode Extensions +description: User-Mode Extensions +ms.assetid: 83b0aca1-ad08-4384-a035-3d7bd2c1b4fe +keywords: ["extension commands ( commands), user-mode extensions", "ntsdexts.dll (user-mode extensions)", "uext.dll (user-mode extensions)", "user-mode extensions (ntsdexts.dll and uext.dll)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# User-Mode Extensions + + +## + + +This section of the reference describes extension commands that are primarily used during user-mode debugging. + +The debugger will automatically load the proper version of these extension commands. Unless you have manually loaded a different version, you do not have to keep track of the DLL versions being used. See [Using Debugger Extension Commands](using-debugger-extension-commands.md) for a description of the default module search order. See [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md) for an explanation of how to load extension modules. + +Each extension command reference page lists the DLLs that expose that command. Use the following rules to determine the proper directory from which to load this extension DLL: + +- If your target application is running on Windows XP or a later version of Windows, use winxp\\Ntsdexts.dll. + +In addition, user-mode extensions that are not specific to any single operating system can be found in winext\\Uext.dll. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20User-Mode%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/user-space-and-system-space.md b/windows-driver-docs-pr/debugger/user-space-and-system-space.md new file mode 100644 index 0000000000..62e65eaf5f --- /dev/null +++ b/windows-driver-docs-pr/debugger/user-space-and-system-space.md @@ -0,0 +1,56 @@ +--- +title: User Space and System Space +description: User Space and System Space +ms.assetid: 2d988178-cd19-4dc4-8dc1-39b9b6a1aaad +keywords: ["system space", "system space, addresses", "system space, breakpoints", "kernel space", "kernel space, addresses", "kernel space, breakpoints", "user space", "user space, addresses", "user space, breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# User Space and System Space + + +Windows gives each user-mode application a block of virtual addresses. This is known as the *user space* of that application. The other large block of addresses, known as *system space* or *kernel space*, cannot be directly accessed by the application. + +When WinDbg or CDB sets a [breakpoint](using-breakpoints.md) in user space, this breakpoint is set at the specified address in the user space of a single process. During user-mode debugging, the current process determines the meaning of virtual addresses. For more information, see [Controlling Processes and Threads](controlling-processes-and-threads.md). + +In kernel mode, you can set breakpoints in user space with the **bp**, **bu**, and **ba** commands or with the **Breakpoints** dialog box. You must first use the *process context* to specify the user-mode process that owns that address space by using **.process /i** (or a process-specific breakpoint on some kernel-space function) to switch the target to the correct [process context](changing-contexts.md#process-context). + +Breakpoints in user space are always associated with the process whose process context was active when the breakpoints were set. If a user-mode debugger is debugging this process and if a kernel debugger is debugging the computer that the process is running on, this breakpoint breaks into the user-mode debugger, even though the breakpoint was actually set from the kernel debugger. You can break into the system from the kernel debugger at this point, or use the [**.breakin (Break to the Kernel Debugger)**](-breakin--break-to-the-kernel-debugger-.md) command from the user-mode debugger to transfer control to the kernel debugger. + +### Determining the Range of User Space and System Space + +If you need to determine the extent of user space and system space on the target computer, you can use the [**dp (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command from a kernel debugger to display the Windows global variable **MmHighestUserAddress**. This variable contains the address of the top of user space. Since system space addresses are always higher than user space addresses, this value allows you to determine whether any given address is in user space or in kernel space. + +For example, on a 32-bit target computer with an x86 processor and standard boot parameters, this command will show the following result: + +``` +kd> dp nt!mmhighestuseraddress L1 +81f71864 7ffeffff +``` + +This indicates that user space ranges from the address 0x00000000 to 0x7FFEFFFF, and system space therefore ranges from 0x80000000 up to the highest possible address (which is 0xFFFFFFFF on a standard 32-bit Windows installation). + +With a 64-bit target computer, different values will occur. For example, this command might show the following: + +``` +0: kd> dp nt!mmhighestuseraddress L1 +fffff800`038b4010 000007ff`fffeffff +``` + +This indicates that user space ranges from 0x00000000\`00000000 to 0x000007FF\`FFFEFFFF. Therefore, system space includes all addresses from 0x00000800\`00000000 upward. + +For more information about Windows memory management, see *Microsoft Windows Internals* by David Solomon and Mark Russinovich (4th edition, Microsoft Press, 2005). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20User%20Space%20and%20System%20Space%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/userdump.md b/windows-driver-docs-pr/debugger/userdump.md new file mode 100644 index 0000000000..f0b07b2a9b --- /dev/null +++ b/windows-driver-docs-pr/debugger/userdump.md @@ -0,0 +1,33 @@ +--- +title: UserDump +description: UserDump +ms.assetid: cbc3d75f-e298-4cbc-a44f-bc019afff27a +keywords: ["dump file, UserDump", "UserDump", "OEM Support Tools, UserDump", "User Mode Process Dump tool (UserDump)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# UserDump + + +## + + +The UserDump tool (Userdump.exe), also known as User-Mode Process Dump, can create user-mode dump files. + +UserDump and its documentation are part of the OEM Support Tools package. + +To download these tools, go to [Microsoft Supoort Article 253066](http://go.microsoft.com/fwlink/p/?LinkId=241339) and follow the instructions on that page. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20UserDump%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using--ks-graph.md b/windows-driver-docs-pr/debugger/using--ks-graph.md new file mode 100644 index 0000000000..daf49e1226 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using--ks-graph.md @@ -0,0 +1,114 @@ +--- +title: Using ks.graph +description: Using ks.graph +ms.assetid: 05dcd5d3-fac6-4af5-8149-955435fb016f +keywords: ["kernel streaming debugging, displaying a graph"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using !ks.graph + + +The [**!ks.graph**](-ks-graph.md) command is one of most powerful extension commands in the kernel streaming extension module. This command displays a picture of an entire graph in kernel mode from any given starting point. + +Before running [**!ks.graph**](-ks-graph.md), you may want to enable all library extensions that are capable of being active. To do this, issue a [**!ks.libexts enableall**](-ks-libexts.md) command. The output of **!ks.graph** will be a textual description of the kernel mode graph in topologically sorted order. Here is an example: + +``` +kd> !graph ffa0c6d4 7 +Attempting a graph build on ffa0c6d4... Please be patient... +Graph With Starting Point ffa0c6d4: +"usbaudio" Filter ffaaa768, Child Factories 2 + Output Factory 0: + Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p) = 7, 1 +``` + +This example displays a capture graph in which two Sndrec32.exe's are capturing from a Telex USB Microphone. Each individual record begins with a name (usbaudio, in the above section) and shows the filter address (0xFFAAA768) and quantity of child pin factories (2) on the filter. + +Below each entry, each factory is enumerated and lists the address of each pin instance (0xFFB1CAF0), the file object (0x811DEEB8) corresponding to each instance, the direction of the connection, the destination of that connection, and the address of the destination pin (0xFFA8B008). The number of queued (7) and pending IRPs (1) for each pin is also displayed. + +Connections which have forward direction symbols (->) indicate that the pin is an output pin and is connected to an input pin. Connections which have reverse direction symbols (<-), on the other hand, are input pins and show the origination of the connection. The output continues as follows: + +``` +"splitter" Filter ffa0c660, Child Factories 2 + Output Factory 0: + Pin 81250008 (File ffb10028, -> "kmixer" 8123c000) Irps(q/p) = 3, 0 + Pin 811df9c0 (File ffaaf2f0, -> "kmixer" 81236000) Irps(q/p) = 3, 0 + Input Factory 1: + Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p) = 1, 7 +"kmixer" Filter ffa65b70, Child Factories 4 + Input Factory 2: + Pin 81236000 (File ffaaf7d0, <- "splitter" 811df9c0) Irps(q/p) = 0, 0 + Output Factory 3: + Pin 81252d00 (File 811df1d8) Irps(q/p) = 10, 0 +"kmixer" Filter ffb03808, Child Factories 4 + Input Factory 2: + Pin 8123c000 (File ffb10130, <- "splitter" 81250008) Irps(q/p) = 0, 0 + Output Factory 3: + Pin ffa1e9c0 (File 81253468) Irps(q/p) = 10, 0 +``` + +In order to follow the graph, use the following procedure: + +**To follow this graph:** + +1. Find the pin of interest. Consider 0xFFB1CAF0, usbaudio's output pin (factory 0). + +2. Find the connected pin. In this example, this is splitter pin 0xFFA8B008. + +3. Look at the connection direction and visually move that way looking for the filter name. (Remember, the list is topologically sorted.) In this example, the right-pointing arrow indicates that we need to look below this entry in the list to find the corresponding pin. The splitter filter 0xFFA0C660 is immediately below. + +4. Find the destination pin address in the filter pin instance list. In this case, this address is 0xFFA8B008. + +The To follow this graph: command can also be used to analyze stalled graphs from any given starting point. To do this, specify 4 in the *Flags* parameter: + +``` +kd> !graph 812567c0 7 4 + +Attempting a graph build on 812567c0... Please be patient... + +Graph With Starting Point 812567c0: + +"emu10k" Filter ff9ebb98, Child Factories 5 + Output Factory 0: + Pin 812567c0 (File 811c6630, -> "splitter" 811df960) Irps(q/p) = 8, 0 +"splitter" Filter ffb18890, Child Factories 2 + Output Factory 0: + Pin 811df430 (File ffa55f90) Irps(q/p) = 10, 0 + Input Factory 1: + Pin 811df960 (File 81187820, <- "emu10k" 812567c0) Irps(q/p) = 0, 8 + +Analyzing a Hung Graph From 812567c0: + +Suspect Filters (For a Hung Graph): + "emu10k" Filter ff9ebb98 or class "PortCls Wave Cyclic" is suspect. + Reasons For This Analysis: + - No critical pin has less than 8 queued Irps + - Downstream "splitter" pin 811df960 is starved + Irps to check: + 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98 + +NOTE: The above is based on heuristic analysis. It is not designed to be a + replacement for an actual developer looking at this particular hang! The + filters listed as suspects may or may not be the actual cause of the + stall! +``` + +For such output, look at the "suspects" list. These suspect filters are those that are in the critical path of progress being made in the graph. Begin debugging from that point based on the reasons that the analyzer has produced for the stall. + +**Note**   This functionality should only be used on stalled graphs! The analyzer has no way of knowing how long the graph has been in this state. Breaking into the debugger and analyzing a running graph as a stalled graph still displays a suspect filter. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20!ks.graph%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-a-manifest-file-with-symchk.md b/windows-driver-docs-pr/debugger/using-a-manifest-file-with-symchk.md new file mode 100644 index 0000000000..a080618c0e --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-a-manifest-file-with-symchk.md @@ -0,0 +1,55 @@ +--- +title: Using a Manifest File with SymChk +description: Using a Manifest File with SymChk +ms.assetid: ee5d0c39-1838-4595-adf4-6cd1261a57c8 +--- + +# Using a Manifest File with SymChk + + +## + + +In some cases, you might need to retrieve symbols for files that are on an isolated computer; that is, a computer that is either not on any network or is on a network that has no symbol store. In that situation, you can use the following procedure to retrieve symbols. + +1. Run SymChk with the **/om** parameter to create a manifest file that describes the files for which you want to retrieve symbols. + +2. Move the manifest file to a network that has a symbol store. + +3. Run SymChk with **/im** parameter to retrieve symbols for the files described int the manifest file. + +4. Move the symbol files back to the isolated computer. + +### Example + +Suppose yourApp.exe is running on an isolated computer. The following command creates a manifest file that describes all the symbols needed to debug the yourApp.exe pocess. + +``` +C:\>SymChk /om c:\Manifest\man.txt /ie yourApp.exe + +SYMCHK: FAILED files = 0 +SYMCHK: PASSED + IGNORED files = 28 +``` + +Now assume you have moved the manifest file to a different computer that is on a network that has access to a symbol store. The following command retrieves the symbols described in the manifest file and places them in the mySymbols folder. + +``` +C:\>SymChk /im c:\FolderOnOtherComputer\man.txt /s srv*c:\mysymbols*\\aServer\symbols + +SYMCHK: myApp.exe ERROR - Unable to download file. Error reported was 2 +. . . +SYMCHK: FAILED files = 28 +SYMCHK: PASSED + IGNORED files = 28 +``` + +Now you can move the symbols to the isolated computer and use them for debugging. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20a%20Manifest%20File%20with%20SymChk%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-a-repeater.md b/windows-driver-docs-pr/debugger/using-a-repeater.md new file mode 100644 index 0000000000..e075ad284a --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-a-repeater.md @@ -0,0 +1,41 @@ +--- +title: Using a Repeater +description: Using a Repeater +ms.assetid: c6904b6d-f28b-4494-95d0-9e6fc3dc10f3 +keywords: ["repeater, using a repeater"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Repeater + + +## + + +A repeater connection obeys very simple rules: + +- Any communication that the server and client intend for each other passes through the repeater without alteration. + +- Any action that the server performs with respect to the transport connection affects the repeater (and only indirectly affects the client). + +- Any action that the client performs with respect to the transport connection affects the repeater (and only indirectly affects the server). + +This means that any debugging commands, debugger output, control keys, and file access will take place exactly as if the client and server were directly connected. The repeater will be invisible to all these commands. + +Actions that terminate the connection itself will affect the repeater. For example, if you issue a [**qq (Quit)**](q--qq--quit-.md) command from the client, the server will shut down and will send a shutdown signal to the transport. This will cause the repeater to exit (unless it was started with the **-p** option). As another example, the [**.clients (List Debugging Clients)**](-clients--list-debugging-clients-.md) command will list the client's computer name, but it will show the connection protocol used to connect the server with the repeater. + +If the server is shut down, the repeater will automatically exit (unless it was started with the **-p** option). When the repeater shuts down, this will cause a debugging client to exit as well, although a smart client will not. If for some reason you need to terminate the repeater directly, you can use Task Manager or the kill.exe tool. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20a%20Repeater%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-a-source-server.md b/windows-driver-docs-pr/debugger/using-a-source-server.md new file mode 100644 index 0000000000..8190eccda2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-a-source-server.md @@ -0,0 +1,75 @@ +--- +title: Using a Source Server +description: Using a Source Server +ms.assetid: b3467f26-1ce3-42cb-a8c8-a7d10efc5079 +keywords: ["source server (srcsrv.dll)", "source server (srcsrv.dll), overview", "SrcSrv (srcsrv.dll)", "SrcSrv (srcsrv.dll), overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Source Server + + +A source server enables the debugger to automatically retrieve the source files that match the current target. To use a source server, you must be debugging binaries that have been source indexed at build time and whose source file locations are embedded in the PDB files. + +Debugging Tools for Windows includes the source server [SrcSrv](srcsrv.md) (Srcsrv.exe). + +### Using SrcSrv with a Debugger + +[SrcSrv](srcsrv.md) can be used with WinDbg, KD, NTSD, or CDB. + +To use [SrcSrv](srcsrv.md) with the debugger, enter the following command to set the source path to srv\*. + +``` +.srcfix +``` + +You can get the same result by entering the following command. + +``` +.srcpath srv* +``` + +Setting the source path to srv\* tells the debugger that it should retrieve source files from locations specified in the target modules' symbol files. + +If you want to use [SrcSrv](srcsrv.md) and also include a list of directories in your source path, use semicolons to separate `srv*` from any directories that are in the path. + +For example: + +``` +.srcpath srv*;c:\someSourceCode +``` + +If the source path is set as shown in the preceding example, the debugger first uses [SrcSrv](srcsrv.md) to retrieve source files from locations specified in the target modules' symbol files. If SrcSrv is unable to retrieve a source file, the debugger attempts to retrieve it from c:\\someSourceCode. Regardless of whether srv\* is the first element in the path or appears later, the debugger always uses SymSrv before it searches any other directories listed in the path. + +You can also use [**.srcfix+**](-srcfix---lsrcfix--use-source-server-.md) to append `srv*` to your existing source path, as shown in the following example. + +``` +3: kd> .srcpath c:\mySource +Source search path is: c:\mySource +3: kd> .srcfix+ +Source search path is: c:\mySource;SRV* +``` + +If a source file is retrieved by the source server, it will remain on your hard drive after the debugging session is over. Source files are stored locally in the src subdirectory of the home directory (unlike the symbol server, the source server does not specify a local cache in the `srv*` syntax itself). The home directory defaults to the debugger installation directory; it can be changed by using the [**!homedir**](-homedir.md) extension or by setting the DBGHELP\_HOMEDIR environment variable. If this subdirectory does not already exist, it will be created. + +If you use the [**.open (Open Source File)**](-open--open-source-file-.md) command to open a new source file through [SrcSrv](srcsrv.md), you must include the -m Address parameter. + +For information on how to index your sources, or if you plan to create your own source control provider module, see [SrcSrv](srcsrv.md). + +### Using AgeStore to Reduce the Cache Size + +Any source files downloaded by [SrcSrv](srcsrv.md) will remain on your hard drive after the debugging session is over. To control the size of the source cache, the AgeStore tool can be used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. For details, see [AgeStore](agestore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20a%20Source%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-a-symbol-server.md b/windows-driver-docs-pr/debugger/using-a-symbol-server.md new file mode 100644 index 0000000000..3d560c6810 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-a-symbol-server.md @@ -0,0 +1,46 @@ +--- +title: Using a Symbol Server +description: Using a Symbol Server +ms.assetid: 6c1687c7-7b9d-45f7-8778-c7284c4a8222 +--- + +# Using a Symbol Server + + +A symbol server enables the debugger to automatically retrieve the correct symbol files from a symbol store - an indexed collection of symbol files - without the user needing to know product names, releases, or build numbers. The Debugging Tools for Windows package includes the symbol server [SymSrv](symsrv.md) (symsrv.exe). + +### Using SymSrv with a Debugger + +SymSrv can be used with WinDbg, KD, NTSD, or CDB. + +To use this symbol server with the debugger, simply include the text **srv\*** in the symbol path. For example: + +``` +set _NT_SYMBOL_PATH = srv*DownstreamStore*SymbolStoreLocation +``` + +where *DownstreamStore* specifies the local directory or network share that will be used to cache individual symbol files, and *SymbolStoreLocation* is the location of the symbol store either in the form *\\\\server\\share* or as an internet address. For more syntax options, see [Advanced SymSrv Use](advanced-symsrv-use.md). + +Microsoft has a Web site that makes Windows symbols publicly available. You can refer directly to this site in your symbol path in the following manner: + +``` +set _NT_SYMBOL_PATH=srv*DownstreamStore*https://msdl.microsoft.com/download/symbols +``` + +where, again, *DownstreamStore* specifies the local directory or network share that will be used to cache individual symbol files. For more information, see [Microsoft Public Symbols](microsoft-public-symbols.md). + +If you plan to create a symbol store, configure a symbol store for web (HTTP) access, or write your own symbol server or symbol store, see [Symbol Stores and Symbol Servers](symbol-stores-and-symbol-servers.md). + +### Using AgeStore to Reduce the Cache Size + +Any symbol files downloaded by SymSrv will remain on your hard drive after the debugging session is over. To control the size of the symbol cache, the AgeStore tool can be used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. For details, see [AgeStore](agestore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20a%20Symbol%20Server%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-agestore.md b/windows-driver-docs-pr/debugger/using-agestore.md new file mode 100644 index 0000000000..44f4fde378 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-agestore.md @@ -0,0 +1,79 @@ +--- +title: Using AgeStore +description: Using AgeStore +ms.assetid: 188eac5c-e84c-45a4-a4ea-1c9bfaa93cca +keywords: ["AgeStore, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using AgeStore + + +AgeStore is a tool that deletes files in a directory or directory tree, based on their last access dates. Its primary use is for removing old files from the downstream store used by a symbol server or a source server, in order to conserve disk space. It can also be used as a general file deletion tool. + +AgeStore can delete all files in a single directory (the *target directory*), or in all the directories within a tree (the *target tree*). The -s option indicates that an entire tree is to be targeted. + +There are three ways to specify which files within the target directory or target tree are to be deleted. The agestore -date=Month-Day-Year command deletes all files that were last accessed prior to the specified date. The agestore -days=NumberOfDays command deletes all files that were last accessed more than the specified number of days ago. The agestore -size=SizeRemaining command deletes all files in the target directory or target tree, beginning with the least-recently-accessed files, until the total size of the remaining files is less than or equal to *SizeRemaining*. + +For example, the following command deletes all files in C:\\MyDir that were last accessed prior to January 7, 2008: + +``` +agestore c:\mydir -date=01-07-2008 +``` + +The following command deletes all files in the directory tree subordinate to C:\\symbols\\downstreamstore that were last accessed over thirty days ago: + +``` +agestore c:\symbols\downstreamstore -days=30 -s +``` + +The following command deletes files in the directory tree subordinate to C:\\symbols\\downstreamstore, beginning with those accessed longest ago, until the total size of all files in this tree is less than or equal to 50,000 bytes: + +``` +agestore c:\symbols\downstreamstore -size=50000 -s +``` + +The -l option causes AgeStore to delete no files, but merely to list all the files that would be deleted without this option. Before you use any AgeStore command you should run the intended command with the -l option added, to verify that it will delete exactly those files you intend it to delete. + +For the complete command line syntax, see [**AgeStore Command-Line Options**](agestore-command-line-options.md). + +### Running AgeStore on Windows Vista and Later + +Because AgeStore deletes files based on the last time that they were accessed, it can run successfully only if your your file system stores Last Access Time (LAT) data. In the NTFS file system, LAT data storage can be either enabled or disabled. If it is disabled, AgeStore will not run, but will display the following error message instead: + +``` +Last-Access-Time support is disabled on this computer. +Please read the documentation for more details. +``` + +In Windows 2000, Windows XP, and Windows Server 2003, LAT data storage is enabled by default. In Windows Vista and later versions of Windows, LAT data storage is disabled by default, and therefore AgeStore will not run unless you first enable this data. + +In Windows Vista and later versions of Windows, you can use the FSUtil (Fsutil.exe) tool to enable the gathering of LAT data. From a Command Prompt window, issue the following command: + +``` +fsutil behavior set disablelastaccess 0 +``` + +To disable the gathering of LAT data, using the following command: + +``` +fsutil behavior set disablelastaccess 1 +``` + +These changes take effect after the next restart of Windows. + +The FAT32 file system always stores LAT information (although only the date, and not the time, are stored). Therefore, AgeStore works with FAT32 file systems. However, since AgeStore will not run when the NTFS LAT is disabled, you must enable NTFS LAT even if your file system is FAT32. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20AgeStore%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-aliases.md b/windows-driver-docs-pr/debugger/using-aliases.md new file mode 100644 index 0000000000..c09819e6e7 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-aliases.md @@ -0,0 +1,314 @@ +--- +title: Using Aliases +description: Using Aliases +ms.assetid: ee0540d0-5bfd-47ef-92b1-ec1d6954aec7 +--- + +# Using Aliases + + +## + + +*Aliases* are character strings that are automatically replaced with other character strings. You can use them in debugger commands and to avoid retyping certain common phrases. + +An alias consists of an *alias name* and an *alias equivalent*. When you use an alias name as part of a debugger command, the name is automatically replaced by the alias equivalent. This replacement occurs immediately, before the command is parsed or executed. + +The debugger supports three kinds of aliases: + +- You can set and name *user-named aliases*. + +- You can set *fixed-name aliases*, but they are named **$u0**, **$u1**, ..., **$u9**. + +- The debugger sets and names *automatic aliases*. + +### Defining a User-Named Alias + +When you define a user-named alias, you can choose the alias name and the alias equivalent: + +- The alias name can be any string that does not contain white space. + +- The alias equivalent can be any string. If you enter it at the keyboard, the alias equivalent cannot contain leading spaces or carriage returns. Alternatively, you can set it equal to a string in memory, the value of a numeric expression, the contents of a file, the value of an environment variable, or the output of one or more debugger commands. + +Both the alias name and the alias equivalent are case sensitive. + +To define or redefine a user-named alias, use the [**as (Set Alias)**](as--as--set-alias-.md) or **aS (Set Alias)** command. + +To remove an alias, use the [**ad (Delete Alias)**](ad--delete-alias-.md) command. + +To list all current user-named aliases, use the [**al (List Aliases)**](al--list-aliases-.md) command. + +### Defining a Fixed-Name Alias + +There are 10 fixed-name aliases. Their alias names are **$u0**, **$u1**, ..., **$u9**. Their alias equivalents can be any string that does not contain the ENTER keystroke. + +Use the [**r (Registers)**](r--registers-.md) command to define the alias equivalents for fixed-name aliases. When you define a fixed-name alias, you must insert a period (**.**) before the letter "u". The text after the equal sign (=) is the alias equivalent. The alias equivalent can include spaces or semicolons, but leading and trailing spaces are ignored. You should not enclose the alias equivalent in quotation marks (unless you want quotation marks in the results). + +**Note**   Do not be confused by using the **r (Registers)** command for fixed-name aliases. These aliases are not registers or pseudo-registers, even though you use the **r** command to set their alias equivalents. You do not have to add an at (**@**) sign before these aliases, and you cannot use the **r** command to *display* the value of one of these aliases. + +  + +By default, if you do not define a fixed-name alias, it is an empty string. + +### Automatic Aliases + +The debugger sets the following automatic aliases. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Alias nameAlias equivalent

$ntnsym

The most appropriate module for NT symbols on the computer's native architecture. This alias can equal either ntdll or nt.

$ntwsym

The most appropriate module for NT symbols during 32-bit debugging that uses WOW64. This alias could be ntdll32 or some other 32-bit version of Ntdll.dll.

$ntsym

The most appropriate module for NT symbols that match the current machine mode. When you are debugging in native mode, this alias is the same as $ntnsym. When you are debugging in a non-native mode, the debugger tries to find a module that matches this mode. (For example, during 32-bit debugging that uses WOW64, this alias is the same as $ntwsym.)

$CurrentDumpFile

The name of the last dump file that the debugger loaded.

$CurrentDumpPath

The directory path of the last dump file that the debugger loaded.

$CurrentDumpArchiveFile

The name of the last dump archive file (CAB file) that the debugger loaded.

$CurrentDumpArchivePath

The directory path of the last dump archive file (CAB file) that the debugger loaded.

+ +  + +Automatic aliases are similar to [automatic pseudo-registers](pseudo-register-syntax.md), except that you can use automatic aliases with alias-related tokens (such as **${ }**), while you cannot use pseudo-registers with these tokens. + +### Using an Alias in the Debugger Command Window + +After you define an alias, you can use it in any command entry. The alias name is automatically replaced with the alias equivalent. Therefore, you can use the alias as an expression or as a macro. + +An alias name expands correctly even if it is enclosed in quotation marks. Because the alias equivalent can include any number of quotation marks or semicolons, the alias equivalent can represent multiple commands. + +A user-named alias is recognized only if its name is separated from other characters by white space. The first character of its alias name must begin the line or follow a space, a semicolon, or a quotation mark. The last character of its alias name must end the line or be followed by a space, a semicolon, or a quotation mark. + +**Note**   Any text that you enter into the [Debugger Command window](debugger-command-window.md) that begins with "as", "aS", "ad", or "al" does not receive alias replacement. This restriction prevents the alias commands from being rendered inoperable. However, this restriction also means that commands that follow **ad** or **al** on a line do not have their aliases replaced. If you want aliases to be replaced in a line that begins with one of these strings, add a semicolon before the alias. + +  + +However, you can use the **${ }** token to expand a user-named alias even when it is next to other text. You can also use this token together with certain switches to prevent an alias from being expanded or to display certain alias-related values. For more information about these situations, see [**${ } (Alias Interpreter)**](-------alias-interpreter-.md). + +A fixed-name alias expands correctly from any point within a line, regardless of how it is embedded within the text of the line. + +You cannot use commands that are available only in WinDbg ([**.open**](-open--open-source-file-.md), [**.write\_cmd\_hist (Write Command History)**](-write-cmd-hist--write-command-history-.md), [**.lsrcpath**](-srcpath---lsrcpath--set-source-path-.md), and [**.lsrcfix**](-srcfix---lsrcfix--use-source-server-.md)) and a few additional commands ([**.hh**](-hh--open-html-help-file-.md), [**.cls**](-cls--clear-screen-.md), [**.wtitle**](-wtitle--set-window-title-.md), [**.remote**](-remote--create-remote-exe-server-.md), kernel-mode [**.restart**](-restart--restart-kernel-connection-.md), and user-mode [**.restart**](-restart--restart-target-application-.md)) with aliases. + +### Using an Alias in a Script File + +When you use an alias in a script file, you must take special care to make sure that the alias is expanded at the correct time. Consider the following script: + +``` +.foreach (value {dd 610000 L4}) +{ + as /x ${/v:myAlias} value + 1 + .echo value myAlias +} + +ad myAlias +``` + +The first time through the loop, the [**as, aS (Set Alias)**](as--as--set-alias-.md) command assigns a value to the myAlias. The value assigned to myAlias is 1 plus 610000 (the first output of the dd command). However, when the [**.echo (Echo Comment)**](-echo--echo-comment-.md) command is executed, myAlias has not yet been expanded, so instead of seeing 610001, we see the text "myAlias". + +``` +0:001> $$>< c:\Script02.txt +00610000 myAlias +00905a4d 0x610001 +00000003 0x905a4e +00000004 0x4 +0000ffff 0x5 +``` + +The problem is that myAlias is not expanded until a new block of code is entered. The next entry to the loop is a new block, so myAlias gets expanded to 610001. But it is too late: we should have seen 610001 the first time through the loop, not the second time.We can fix this problem by enclosing the [**.echo (Echo Comment)**](-echo--echo-comment-.md) command in a new block as shown in the following script. + +``` +.foreach (value {dd 610000 L4}) +{ + as /x ${/v:myAlias} value + 1 + .block{.echo value myAlias} +} + +ad myAlias +``` + +With the altered script, we get the following correct output. + +``` +0:001> $$>< c:\Script01.txt +00610000 0x610001 +00905a4d 0x905a4e +00000003 0x4 +00000004 0x5 +0000ffff 0x10000 +``` + +For more information, see [**.block**](-block.md) and [**${ } (Alias Interpreter)**](-------alias-interpreter-.md). + +### Using a .foreach Token in an Alias + +When you use a [**.foreach**](-foreach.md) token in the definition of an alias, you must take special care to ensure that the token is expanded. Consider the following sequence of commands. + +``` +r $t0 = 5 +ad myAlias +.foreach /pS 2 /ps 2 (Token {?@$t0}) {as myAlias Token} +al +``` + +The first command sets the value of the **$t0** pseudo register to 5. The second command deletes any value that might have been previously assigned to myAlias. The third command takes the third token of the **?@$t0** command and attempts to assign the value of that token to myAlias. The fourth command lists all aliases and their values. We would expect the value of myAlias to be 5, but instead the value is the word "Token". + +``` + Alias Value + ------- ------- + myAlias Token +``` + +The problem is that the [**as**](as--as--set-alias-.md) command is at the beginning of the line in the body of the [**.foreach**](-foreach.md) loop. When a line begins with an **as** command, aliases and tokens in that line are not expanded. If we put a semicolon or blank space before the **as** command, then any alias or token that already has a value is expanded. In this example, myAlias is not expanded because it does not already have a value. Token is expanded because it has a value of 5. Here is the same sequence of commands with the addition of a semicolon before the **as** command. + +``` +r $t0 = 5 +ad myAlias +.foreach /pS 2 /ps 2 (Token {?@$t0}) {;as myAlias Token} +al +``` + +Now we get the expected output. + +``` + Alias Value + ------- ------- + myAlias 5 +``` + +### Recursive Aliases + +You can use a fixed-name alias in the definition of any alias. You can also use a user-named alias in the definition of a fixed-name alias. However, to use a user-named alias in the definition of another user-named alias, you have to add a semicolon before the **as** or **aS** command, or else the alias replacement does not occur on that line. + +When you are using recursive definitions of this type, each alias is translated as soon as it is used. For example, the following example displays **3**, not **7**. + +``` +0:000> r $.u2=2 +0:000> r $.u1=1+$u2 +0:000> r $.u2=6 +0:000> ? $u1 +Evaluate expression: 3 = 00000003 +``` + +Similarly, the following example displays **3**, not **7**. + +``` +0:000> as fred 2 +0:000> r $.u1= 1 + fred +0:000> as fred 6 +0:000> ? $u1 +Evaluate expression: 3 = 00000003 +``` + +The following example is also permitted and displays **9**. + +``` +0:000> r $.u0=2 +0:000> r $.u0=7+$u0 +0:000> ? $u0 +Evaluate expression: 9 = 00000009 +``` + +### Examples + +You can use aliases so that you do not have to type long or complex symbol names, as in the following example. + +``` +0:000> as Short usersrv!NameTooLongToWantToType +0:000> dw Short +8 +``` + +The following example is similar to the preceding example but it uses a fixed-name alias. + +``` +0:000> r $.u0=usersrv!NameTooLongToWantToType +0:000> dw $u0+8 +``` + +You can use aliases as macros for commands that you use frequently. The following example increments the **eax** and **ebx** registers two times. + +``` +0:000> as GoUp r eax=eax+1; r ebx=ebx+1 +0:000> GoUp +0:000> GoUp +``` + +The following example uses an alias to simplify typing of commands. + +``` +0:000> as Cmd "dd esp 14; g" +0:000> bp MyApi Cmd +``` + +The following example is similar to the preceding example but it uses a fixed-name alias. + +``` +0:000> r $.u5="dd esp 14; g" +0:000> bp MyApi $u5 +``` + +Both of the preceding examples are equivalent to the following command. + +``` +0:000> bp MyApi "dd esp 14; g" +``` + +### Tools.ini File + +In CDB (and NTSD), you can predefine fixed-name aliases in the [tools.ini](configuring-tools-ini.md) file. To predefine a fixed-name alias, add the **$u** fields that you want to your \[NTSD\] entry, as in the following example. + +``` +[NTSD] +$u1:_ntdll!_RtlRaiseException +$u2:"dd esp 14;g" +$u9:$u1 + 42 +``` + +You cannot set user-named aliases in the Tools.ini file. + +### Fixed-Name Aliases vs. User-Named Aliases + +User-name aliases are easier to use than fixed-named aliases. Their definition syntax is simpler, and you can list them by using the [**al (List Aliases)**](al--list-aliases-.md) command. + +Fixed-named aliases are replaced if they are used next to other text. To make a user-named alias be replaced when it is next to other text, enclose it in the [**${ } (Alias Interpreter)**](-------alias-interpreter-.md) token. + +Fixed-name alias replacement occurs before user-named alias replacement. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Aliases%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-amli-debugger-commands.md b/windows-driver-docs-pr/debugger/using-amli-debugger-commands.md new file mode 100644 index 0000000000..522f311385 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-amli-debugger-commands.md @@ -0,0 +1,254 @@ +--- +title: Using AMLI Debugger Commands +description: Using AMLI Debugger Commands +ms.assetid: 8efa6f13-67db-417a-83ec-8219afc9874c +keywords: ["AMLI Debugger, AMLI Debugger commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using AMLI Debugger Commands + + +## + + +The following commands can be issued from the AMLI Debugger prompt. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
General CategorySpecific ActionAMLI Debugger Commands

Controlling the Debugger

+Continue Execution +Break to Kernel Debugger

+g +q

Controlling AML Execution

+Run Method +Step Over AML Code +Trace Into AML Code

+run +p +t

Controlling Trace Mode Settings

Configure Trace Mode

trace

Notifying a Namespace Object

Notify Namespace Object

notify

Displaying the Object Count Table

Display Object Count Table

dc

Accessing Memory

+Display Data +Display Data Bytes +Display Data Words +Display Data DWORDs +Display Data String +Edit Memory

+d +db +dw +dd +da +e

Accessing Ports

+Read Byte from Port +Read Word from Port +Read DWORD from Port +Write Byte to Port +Write Word to Port +Write DWORD to Port

+i +iw +id +o +ow +od

Displaying Help

Display Help

?

+ +  + +### Controlling the Debugger + +These commands exit the AMLI Debugger. The **g** command will resume normal execution of the target computer, and the **q** command will freeze the target computer and break into the kernel debugger. + +**g** +**q** +### Controlling AML Execution + +These commands allow you to run or step through AML methods. The **run** command begins execution at a specified point. The **p** and **t** commands allow you to step through one instruction at a time. If a function call is encountered, the **p** command treats the function as a single step, while the **t** command traces into the new function one instruction at a time. + +**run** *MethodName* **\[***ArgumentList***\]** +**run** *CodeAddress* **\[***ArgumentList***\]** +**p** +**t** + +*MethodName* +Specifies the full path and name of a method. Execution will start at the beginning of this method's memory location. + +*CodeAddress* +Specifies the address where execution is to begin. + +*ArgumentList* +Specifies a list of arguments to be passed to the method. Each argument must be an integer. Multiple arguments should be separated with spaces. + +### Controlling Trace Mode Settings + +The **trace** command controls the AML interpreter's trace mode settings. If this command is used with no parameters, the current trace mode settings are displayed. + +**trace \[trigon|trigoff\] \[level=***Level***\] \[add=***TPStrings***\] \[zap=***TPNumbers***\]** + +**trigon** +Activates trace trigger mode. + +**trigoff** +Deactivates trace trigger mode. + +*Level* +Specifies the new setting for the trace level. + +*TPStrings* +Specifies one or more trigger points to be added. Each trigger point is specified by name. Multiple trigger point strings should be separated by commas. + +*TPNumbers* +Specifies one or more trigger points to be deleted. Each trigger point is specified by number. Multiple trigger point numbers should be separated by commas. To see a list of trigger point numbers, use the **trace** command with no parameters. + +### Notifying a Namespace Object + +The **notify** command sends a notification to an ACPI namespace object. The notification will be placed in the specified object's queue. + +**notify** *ObjectName Value* + +**notify** *ObjectAddress Value* + +*ObjectName* +Specifies the full namespace path of the object to be notified. + +*ObjectAddress* +Specifies the address of the object to be notified. + +*Value* +Specifies the notification value. + +### Displaying the Object Count Table + +The **dc** command displays the memory object count table. + +**dc** + +### Accessing Memory + +The memory access commands allow you to read and write to memory. When reading memory, you can choose the size of the memory units with the **db**, **dw**, **dd** or **da** command. A simple **d** command displays memory in the most recently-chosen units. If this is the first display command used, byte units are used. + +If no address or method is specified, display will begin where the previous display command ended. + +These commands have the same effect as the standard kernel debugger memory commands; they are duplicated within the AMLI Debugger for easy access. + +**d\[b|w|d|a\] \[ \[l=***Length***\] \[** *Method* **| \[%%\]***Address* **\] \]** + +**e \[%%\]***Address Datalist* + +**b** +Specifies that the data should be displayed in byte units. + +**w** +Specifies that the data should be displayed in word (16-bit) units. + +**d** +Specifies that the data should be displayed in DWORD (32-bit) units. + +**a** +Specifies that the data should be displayed as a string. The data is displayed as ASCII characters. The display terminates when a NULL character is read, or when *Length* characters have been displayed. + +*Length* +Specifies the number of bytes to be displayed. *Length* must be a hexadecimal number (without an **0x** prefix). If *Length* is omitted, the default display size is 0x80 bytes. + +*Method* +Specifies the full path and name of a method. The display will start at the beginning of this method's memory location. + +*Address* +Specifies the memory address where reading or writing will begin. If the address is prefixed with two percent signs (**%%**), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. + +*DataList* +Specifies the data to be written to memory. Each item in the list can be either a hexadecimal byte or a string. When a string is used, it must be enclosed in quotation marks. Multiple items should be separated by spaces. + +### Accessing Ports + +The port commands allow you to send output or receive input from a data port. The **i** and **o** commands transfer single bytes, the **iw** and **ow** commands transfer words (16 bits), and the **id** and **od** commands transfer DWORDS (32 bits). + +These commands have the same effect as the standard kernel debugger port commands; they are duplicated within the AMLI Debugger for easy access. + +**i** *Port* +**iw** *Port* +**id** *Port* +**o** *Port* *DataForPort* +**ow** *Port* *DataForPort* +**od** *Port* *DataForPort* + +*Port* +Specifies the address of the port to be accessed. The port size must match the command chosen. + +*DataForPort* +Specifies the data to be written to the port. The size of this data must match the command chosen. + +### Displaying Help + +This command displays help text for the AMLI Debugger commands. + +**? \[***Command***\]** + +*Command* +Specifies the command for which to display help. If this is omitted, a list of all AMLI Debugger commands and AMLI Debugger extensions is displayed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20AMLI%20Debugger%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-amli-debugger-extensions.md b/windows-driver-docs-pr/debugger/using-amli-debugger-extensions.md new file mode 100644 index 0000000000..201eeeac07 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-amli-debugger-extensions.md @@ -0,0 +1,142 @@ +--- +title: Using AMLI Debugger Extensions +description: Using AMLI Debugger Extensions +ms.assetid: 98b9cd6e-b2e1-44bd-aff6-376b9cf2daa2 +keywords: ["AMLI Debugger, AMLI Debugger extensions", "amli extension", "acpikd.amli extension"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using AMLI Debugger Extensions + + +## + + +In Windows XP and later versions of Windows, AMLI Debugger extension commands are contained in the extension module Kdexts.dll and use the following syntax: + +``` +kd> !amli command [parameters] +``` + +In Windows 2000, these extension commands are contained in Acpikd.dll and use the following syntax: + +``` +kd> !acpikd.amli command [parameters] +``` + +As with any extension module, after it has been loaded you can omit the **acpikd** prefix. + +If you are at the AMLI Debugger prompt, you can execute any of these extension commands by simply entering the *command* name without the **!amli** prefix: + +``` +AMLI(? for help)-> command [parameters] +``` + +When you are at this prompt, the **!amli debugger** command is not available (because it would be meaningless). Also, the help command ( **?** ) at this prompt shows all AMLI Debugger extensions and commands, while the **!amli ?** extension only displays help on actual extensions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActionExtension Command

Display Help

[!amli ?](-amli--.md)

Set AML Breakpoint

[!amli bp](-amli-bp.md)

List AML Breakpoints

[!amli bl](-amli-bl.md)

Disable AML Breakpoint

[!amli bd](-amli-bd.md)

Enable AML Breakpoint

[!amli be](-amli-be.md)

Clear AML Breakpoint

[!amli bc](-amli-bc.md)

Enter AMLI Debugger

[!amli debugger](-amli-debugger.md)

Display Event Log

[!amli dl](-amli-dl.md)

Clear Event Log

[!amli cl](-amli-cl.md)

Display Heap

[!amli dh](-amli-dh.md)

Display Data Object

[!amli do](-amli-do.md)

Display Stack

[!amli ds](-amli-ds.md)

Display Namespace Object

[!amli dns](-amli-dns.md)

Find Namespace Object

[!amli find](-amli-find.md)

Display Nearest Method

[!amli ln](-amli-ln.md)

List All Contexts

[!amli lc](-amli-lc.md)

Display Context Information

[!amli r](-amli-r.md)

Unassemble AML Code

[!amli u](-amli-u.md)

Set AMLI Debugger Options

[!amli set](-amli-set.md)

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20AMLI%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-and-customizing-windbg-themes.md b/windows-driver-docs-pr/debugger/using-and-customizing-windbg-themes.md new file mode 100644 index 0000000000..7c4b2db33e --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-and-customizing-windbg-themes.md @@ -0,0 +1,38 @@ +--- +title: Using and Customizing WinDbg Themes +description: Using and Customizing WinDbg Themes +ms.assetid: ad1fb350-dfad-48a1-8374-609f5f82494b +keywords: ["themes", "workspaces, themes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using and Customizing WinDbg Themes + + +A theme is a preconfigured WinDbg workspace that contains a useful configuration of debugging information windows. + +Any theme can be saved as your base workspace. Themes in the Debugging Tools for Windows package are provided as a set of registry files (with the .reg extension). As you accumulate more debugging sessions, various default workspaces are automatically set up. These default workspaces use the base workspace as a starting point. For more information on default workspaces, see [Creating and Opening a Workspace](creating-and-opening-a-workspace.md). + +For the best user experience, we recommend that you follow the instructions in this topic before starting your debugging session. + +This section includes the following topics: + +[Loading a Theme](loading-a-theme.md) + +[Customizing a Theme](customizing-a-theme.md) + +[Using Themes Provided in Debugging Tools for Windows](using-themes-provided-in-debugging-tools-for-windows.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20and%20Customizing%20WinDbg%20Themes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-breakpoints.md b/windows-driver-docs-pr/debugger/using-breakpoints.md new file mode 100644 index 0000000000..f04da3fbd1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-breakpoints.md @@ -0,0 +1,42 @@ +--- +title: Using Breakpoints - Debugging Techniques +description: Overview of Using Breakpoints with the Windows Debugger (Debugging Techniques) +ms.assetid: 93c46047-ab04-41ca-ad13-89741735c055 +keywords: ["breakpoints", "breakpoints, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Breakpoints + + +A *breakpoint* is a location in executable code at which the operating system stops execution and breaks into the debugger. This allows you to analyze the target and issue debugger commands. + +This section includes the following topics: + +[Methods of Controlling Breakpoints](methods-of-controlling-breakpoints.md) + +[Breakpoint Syntax](breakpoint-syntax.md) + +[Unresolved Breakpoints (bu Breakpoints)](unresolved-breakpoints---bu-breakpoints-.md) + +[Processor Breakpoints (ba Breakpoints)](processor-breakpoints---ba-breakpoints-.md) + +[Initial Breakpoint](initial-breakpoint.md) + +[User Space and System Space](user-space-and-system-space.md) + +[Risks Entailed When Setting Breakpoints](risks-entailed-when-setting-breakpoints.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-breakpoints2.md b/windows-driver-docs-pr/debugger/using-breakpoints2.md new file mode 100644 index 0000000000..40920d5bdc --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-breakpoints2.md @@ -0,0 +1,37 @@ +--- +title: Using Breakpoints with the Debugger Engine API +description: Using Breakpoints Debugger Engine API - Setting and Controlling +ms.assetid: d1880895-dc01-429b-af48-762cb24539f1 +keywords: ["Debugger Engine, breakpoints", "breakpoints"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Breakpoints + + +## + + +Breakpoints are event triggers which, when the breakpoint's conditions are satisfied, will halt execution of the target and break into the debugger. Breakpoints allow the user to analyze and perhaps modify the target when execution reaches a certain point or when a certain memory location is accessed. + +The debugger engine inserts a *software breakpoint* into a target by modifying the processor instruction at the breakpoint's location; this modification is invisible to the engine's clients. A software breakpoint is triggered when the target executes the instruction at the breakpoint location. A *processor breakpoint* is inserted into the target's processor by the debugger engine; its capabilities are processor-specific. It is triggered by the processor when the memory at the breakpoint location is accessed; what type of access will trigger this breakpoint is specified when the breakpoint is created. + +This topic includes: + +[Setting Breakpoints](setting-breakpoints.md) + +[Controlling Breakpoint Flags and Parameters](controlling-breakpoint-flags-and-parameters.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Breakpoints%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-callback-objects.md b/windows-driver-docs-pr/debugger/using-callback-objects.md new file mode 100644 index 0000000000..389ef9eef3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-callback-objects.md @@ -0,0 +1,54 @@ +--- +title: Using Callback Objects +description: Using Callback Objects +ms.assetid: 9090a465-b6ab-4e99-8155-b0abdb729468 +keywords: ["Debugger Engine API, callback objects", "callback objects", "callback objects, event callbacks", "event callbacks", "callback objects, input callbacks", "input callbacks", "callback objects, output callbacks", "output callbacks"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Callback Objects + + +There are three callback COM like interfaces that are used by the engine: [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550) for notifying [debugger extensions](debugger-extensions.md) and applications of changes to the engine or target, [IDebugInputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550785) for requesting input, and [IDebugOutputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550801) for sending output. + +Callback objects are registered with clients. At most, one instance of each of the three callback interfaces can be registered with each client (the Unicode and ASCII versions of a interface count as the same interface). + +When a client is created, the engine remembers the thread in which it was created. The engine uses this same thread whenever it makes a call to a callback instance registered with the client. If the thread is in use, the engine will queue the calls it needs to make. To allow the engine to make these calls, the method [*DispatchCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff541970) should be called whenever a client's thread is idle. The method [**ExitDispatch**](https://msdn.microsoft.com/library/windows/hardware/ff543265) will cause *DispatchCallbacks* to return. If the thread is the same thread that was used to start the debugger session, then the engine can make the callback calls during the [**WaitForEvent**](https://msdn.microsoft.com/library/windows/hardware/ff561229) method, and *DispatchCallbacks* does not need to be called. + +The method [**FlushCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff545475) tells the engine to send all buffered output to the output callbacks. + +### Event Callback Objects + +The [IDebugEventCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550550) interface is used by the engine to notify the debugger extensions and applications of [events](events.md#events) and changes to the engine and target. An implementation of **IDebugEventCallbacks** can be registered with a client using [*SetEventCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556671). The current implementation registered with a client can be found using [*GetEventCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff546601). The number of event callbacks registered across all clients can be found using [*GetNumberEventCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff547896). + +For details on how the engine manages events, see [Monitoring Events](monitoring-events.md). + +### Input Callback Objects + +The [IDebugInputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550785) interface is used by the engine to request input from debugger extensions and applications. An implementation of **IDebugInputCallbacks** can be registered with a client using [*SetInputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556721). The current implementation registered with a client can be found using [*GetInputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff546892). The number of input callbacks registered across all clients can be found using [*GetNumberInputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff547923). + +For details on how the engine manages input, see [Input and Output](using-input-and-output.md). + +### Output Callback Objects + +The **IDebugOutputCallbacks** interface is used by the engine to send output to the debugger extensions and applications. An implementation of **IDebugOutputCallbacks** can be registered with a client using [*SetOutputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556751). The current implementation registered with a client can be found using [*GetOutputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff548071). The number of output callbacks registered across all clients can be found using [*GetNumberOutputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff547931). + +For details on how the engine manages output, see [Input and Output](using-input-and-output.md). + +**Note**   As is typical for COM objects, the engine will call **IUnknown::AddRef** on a callback COM object when it is registered with a client, and **IUnknown::Release** when the object is replaced or the client is deleted. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Callback%20Objects%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-client-objects.md b/windows-driver-docs-pr/debugger/using-client-objects.md new file mode 100644 index 0000000000..f83dc1d2cf --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-client-objects.md @@ -0,0 +1,53 @@ +--- +title: Using Client Objects +description: Using Client Objects +ms.assetid: 07311a2e-86a7-4985-9dfa-55a876cd7899 +keywords: ["Debugger Engine, COM Interfaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Client Objects + + +For an overview of the role of client objects in interacting with the debugger engine, see [Client Objects](client-objects.md). + +In general, a client's methods may be called only from the thread in which the client was created. Typically, methods called from the wrong thread will fail immediately. The notable exception to this rule is the method [**CreateClient**](https://msdn.microsoft.com/library/windows/hardware/ff539320); this method may be called from any thread, and returns a new client that can be used in the thread from which it was called. Other exceptions are documented in the reference section. + +A string describing a client object is returned by the method [**GetIdentity**](https://msdn.microsoft.com/library/windows/hardware/ff546831) or can be written to the engine's output stream using [**OutputIdentity**](https://msdn.microsoft.com/library/windows/hardware/ff553219). + +### COM Interfaces + +The debugger engine API contains several COM like interfaces; they implement the **IUnknown** interface. + +The interfaces described in the section [Debug Engine Interfaces](https://msdn.microsoft.com/library/windows/hardware/ff539131) is implemented by the client (though not necessarily at the latest version). You may use the COM method **IUnknown::QueryInterface** to obtain each of these interfaces from any of the others. + +The clients implement the **IUnknown** COM interface and use it for maintaining reference counts and interface selection. However, the clients are not registered COM objects. The method **IUnknown::AddRef** is used to increment the reference count on the object, and the method **IUnknown::Release** is used to decrement the reference count. When **IUnknown::QueryInterface** is called, the reference count is incremented, so when a client interface pointer is no longer needed **IUnknown::Release** should be called to decrement the reference count. + +The reference count will be initialized to one when the client object is created using [**DebugCreate**](https://msdn.microsoft.com/library/windows/hardware/ff540469) or [**DebugConnect**](https://msdn.microsoft.com/library/windows/hardware/ff540465). + +See the Platform SDK for more information about when reference counts should be incremented and decremented. + +**IUnknown::QueryInterface**, **DebugCreate**, and **DebugConnect** each take an interface ID as one of their arguments. This interface ID can be obtained using the **\_\_uuidof** operator. For example: + +``` +IDebugClient * debugClient; +HRESULT Hr = DebugCreate( __uuidof(IDebugClient), (void **)&debugClient ); +``` + +**Important**  The IDebug\* interfaces such as [**IDebugEventCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff550550) interface, although COM like, are not proper COM APIs. Calling these interfaces from managed code is an unsupported scenario. Issues such as garbage collection and thread ownership, lead to system instability when the interfaces are called with managed code. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Client%20Objects%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-clients-and-the-engine.md b/windows-driver-docs-pr/debugger/using-clients-and-the-engine.md new file mode 100644 index 0000000000..ef86ee07e5 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-clients-and-the-engine.md @@ -0,0 +1,37 @@ +--- +title: Using Clients and the Engine +description: Using Clients and the Engine +ms.assetid: 899184f5-334b-4fd1-98ce-64475650ace5 +keywords: ["DbgEng Extensions, engine client objects"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Clients and the Engine + + +## + + +A DbgEng extension interacts with the [debugger engine](introduction.md#debugger-engine) through a client object. + +When an extension function is called, it is passed a client. The extension function should use this client for all its interaction with the debugger engine, unless it has a specific reason to use another client. + +An extension library may create its own client object upon initialization by using [**DebugCreate**](https://msdn.microsoft.com/library/windows/hardware/ff540469). This client can be used to register callback objects from the DLL. + +**Note**   Care should be taken when modifying the client passed to an extension function. In particular, registering callbacks with this client could disrupt the input, output, or event handling of the debugger. It is recommended that a new client be created to register callbacks. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Clients%20and%20the%20Engine%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-cvs.md b/windows-driver-docs-pr/debugger/using-cvs.md new file mode 100644 index 0000000000..e7791ff153 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-cvs.md @@ -0,0 +1,44 @@ +--- +title: Using CVS +description: Using CVS +ms.assetid: 4ad1202e-0be5-4adc-af8b-6b8d7cb34b04 +keywords: ["Concurrent Versions System (CVS)", "source servers, CVS", "SrcSrv, CVS", "Concurrent Versions System (CVS), overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using CVS + + +The CVS module for Source Server was developed using Concurrent Versions System (CVS) 1.11.17 (client). It has not been tested with any other versions of CVS. Furthermore, the current version of the module is a beta version. + +### CVSROOT + +On the computer on which you source index the build, CVSROOT cannot contain password and user information. Use cvs.exe to set your credentialing information. + +To prepare the [Srcsrv.ini](the-srcsrv-ini-file.md) file for CVS indexing you must enter an alias for your repository that uniquely distinguishes it from any others in your network. This repository must match the value of CVSROOT in your environment. There is no need to set this value in the copy of Srcsrv.ini that you keep with your debugger clients because the alias is defined in the source indexed .pdb file. + +### Client Computer + +The client computer that extracts files during debugging does not need a CVS sandbox or CVSROOT set. It does need CVS binaries in the path, and if the repository is locked, you must set the username and password with Cvs.exe. + +### Revision Tags + +CVS is unable to extract a file by its version number. Instead, it must be done using what is known as a *tag*. When indexing a CVS-based system, you must ensure that all changes are checked into the repository and then apply a tag using the "cvs tag" command. Then, when indexing the file, make certain you use the "label" command-line parameter to specify the tag that you want to associate with the build you are indexing. You can achieve the same result by setting CVS\_LABEL in the environment. Other values can be set from the environment or the command line. Use the **-??** command-line option with SSIndex to examine your choices and to verify that all was configured correctly: + +``` +ssindex.cmd -system=cvs -?? +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20CVS%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-dbh.md b/windows-driver-docs-pr/debugger/using-dbh.md new file mode 100644 index 0000000000..29ceef7d02 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-dbh.md @@ -0,0 +1,98 @@ +--- +title: Using DBH +description: Using DBH +ms.assetid: c544013d-e925-40bf-b76d-bf9cefb9fd6d +keywords: ["DBH, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using DBH + + +DBH is a command-line tool that exposes many of the functions in the DbgHelp API (dbghelp.dll). It can display information about the contents of a symbol file, display specific details of the symbols in the file, and search through the file for symbols matching various criteria. + +The functionality provided by DBH is similar to that provided within WinDbg, KD, and CDB by commands such as [**x (Examine Symbols)**](x--examine-symbols-.md). + +### Running DBH in Interactive Mode + +You start DBH with a simple command line, on which you specify the target module whose symbols you wish to investigate. A target module can be an EXE program or a PDB symbol file. You can also specify a process ID (PID) to investigate. See [**DBH Command-Line Options**](dbh-command-line-options.md) for the full syntax. + +When DBH starts, it loads the symbols for the specified module, and then presents you with a prompt at which you can type a variety of commands. See [DBH Commands](dbh-commands.md) for a list of available commands. + +For example, the following sequence starts DBH by specifying the target process with process ID 4672, then executes the **enum** command at the DBH prompt to display symbols matching a specific pattern, and then executes the **q** command to quit DBH: + +``` +C:\> dbh -p:4672 + 400000 : TimeTest + 77820000 : ntdll + 77740000 : kernel32 + +pid:4672 mod:TimeTest[400000]: enum TimeTest!ma* + + index address name + 1 42cc56 : main + 3 415810 : malloc + 5 415450 : mainCRTStartup + +pid:4672 mod:TimeTest[400000]: q + +goodbye +``` + +### Running DBH in Batch Mode + +If you wish to run only a single DBH command, you can specify it at the end of the command line. This causes DBH to start, load the specified module, run the specified command, and then exit. + +For example, the previous example could be replaced with a single command line: + +``` +C:\> dbh -p:4672 enum TimeTest!ma* + 400000 : TimeTest + 77820000 : ntdll + 77740000 : kernel32 + +index address name + 1 42cc56 : main + 3 415810 : malloc + 5 415450 : mainCRTStartup +``` + +This method of running DBH is called *batch mode*, because it can be easily used in batch files. This version of the command line can also be followed by a pipe ( **|** ) which redirects the DBH output to another program. + +### Specifying the Target + +DBH can select a target in three ways: by the process ID of a running process, by the name of the executable, or by the name of the symbol file. For example, if there is exactly one instance of MyProg.exe currently running, with process ID 1234, then the following commands are almost equivalent: + +``` +C:\> dbh -v -p:1234 +C:\> dbh -v c:\mydir\myprog.exe +C:\> dbh -v c:\mydir\myprog.pdb +``` + +One difference between these commands is that when you start DBH by specifying the process ID, DBH uses the actual virtual addresses being used by this process. When you start DBH by specifying the executable name or the symbol file name, DBH assumes that the module's base address is a standard value (for example, 0x01000000). You can then use the **base** command to specify the actual base address, thus shifting the addresses of all the symbols in the module. + +DBH does not attach to the target process in the way that a debugger does. DBH cannot cause a process to begin or end, nor can it alter how that process runs. For DBH to attach to a process by its process ID, the target process has to be running, but once DBH has been started the target process can be terminated and DBH will continue to access its symbols. + +### Decorated and Undecorated Symbols + +By default, DBH uses undecorated symbol names when displaying and searching for symbols. If you turn off the [SYMOPT\_UNDNAME](symbol-options.md#symopt-undname) symbol option, or include the -d option on the DBH command line, decorations will be included. + +For information on symbol decorations, see [Public and Private Symbols](public-and-private-symbols.md). + +### Exiting DBH + +To exit DBH, use the **q** command at the DBH prompt. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20DBH%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-debugger-command-programs.md b/windows-driver-docs-pr/debugger/using-debugger-command-programs.md new file mode 100644 index 0000000000..f4a0bd13fe --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-debugger-command-programs.md @@ -0,0 +1,37 @@ +--- +title: Using Debugger Command Programs +description: Using Debugger Command Programs +ms.assetid: b73b1b4a-601f-4027-a511-6f96e9dc9504 +keywords: ["debugger command program", "debugger command program, operation"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugger Command Programs + + +## + + +This section includes the following topics: + +[Elements of a Debugger Command Program](elements-of-a-debugger-command-program.md) + +[Control Flow Tokens](control-flow-tokens.md) + +[Debugger Command Program Execution](executing-a-debugger-command-program.md) + +[Debugger Command Program Examples](debugger-command-program-examples.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugger%20Command%20Programs%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-debugger-commands.md b/windows-driver-docs-pr/debugger/using-debugger-commands.md new file mode 100644 index 0000000000..f9c3e86961 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-debugger-commands.md @@ -0,0 +1,165 @@ +--- +title: Using Debugger Commands +description: This section describes using Debugger Commands. You enter commands at the prompt at the bottom of the window. +ms.assetid: 64dcc364-53b5-41d3-9266-abcfe4b328f4 +keywords: commands, debugger commands, meta-commands +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugger Commands + + +## + + +For KD or CDB, "Debugger Command window" refers to the whole window. You enter commands at the prompt at the bottom of the window. If the commands have any output, the window displays the output and then displays the prompt again. + +For Visual Studio, "Debugger Command window" refers to a window that is labeled "Debugger Immediate Window" in the title bar. This window has two panes: + +- In the small, bottom pane, you enter commands. + +- In the large, upper pane, you view command output. + +For WinDbg, "Debugger Command window" refers to the window that is labeled "Command" in the title bar. This window contains two panes: + +- In the small, bottom pane, you enter commands. + +- In the large, upper pane, you view command output. + +This window is always open at the beginning of a debugging session. You can reopen or switch to this window by clicking **Command** on the **View** menu, pressing ALT+1, or clicking the **Command (Alt+1)** button (![screen shot of the debugger command window button](images/tbcmd.png)) on the toolbar. + +You can use the UP ARROW and DOWN ARROW keys to scroll through the command history. When a previous command appears, you can edit it and then press ENTER to execute the previous command (or the edited version of the previous command). The cursor does not have to be at the end of the line for this procedure to work correctly. + +### Debugger Command Window Prompt + +When you are performing user-mode debugging, the prompt in the Debugger Command window looks like the following example. + +``` +2:005> +``` + +In the preceding example, 2 is the current process number, and 005 is the current thread number. + +If you attach the debugger to more than one computer, the system number is included before the process and thread number, as in the following example. + +``` +3:2:005> +``` + +In this example, 3 is the current system number, 2 is the current process number, and 005 is the current thread number. + +When you are performing kernel-mode debugging on a target computer that has only one processor, the prompt looks like the following example. + +``` +kd> +``` + +However, if the target computer has multiple processors, the number of the current processor appears before the prompt, as in the following example. + +``` +0: kd> +``` + +If the debugger is busy processing a previously issued command, new commands will temporarily not be processed, although they can be added to the command buffer. In addition, you can still use [control keys](control-keys.md) in KD and CDB, and you can still use menu commands and [shortcut keys](keyboard-shortcuts.md) in WinDbg. When KD or CDB is in this busy state, no prompt is displayed. When WinDbg is in this busy state, the following indicator will appear in place of the prompt: + +``` +*BUSY* +``` + +You can use the [**.pcmd (Set Prompt Command)**](-pcmd--set-prompt-command-.md) command to add text to this prompt. + +### Kinds of Commands + +WinDbg, KD, and CDB support a variety of commands. Some commands are shared between the debuggers, and some are available only on one or two of the debuggers. + +Some commands are available only in live debugging, and other commands are available only when you debug a dump file. + +Some commands are available only during user-mode debugging, and other commands are available only during kernel-mode debugging. + +Some commands are available only when the target is running on certain processors. For more information about all of the commands and their restrictions, see [Debugger Commands](debugger-commands.md). + +### Editing, Repeating, and Canceling Commands + +You can use standard editing keys when you enter a command: + +- Use the UP ARROW and DOWN ARROW keys to find previous commands. + +- Edit the current command with the BACKSPACE, DELETE, INSERT, and LEFT ARROW and RIGHT ARROW keys. + +- Press the ESC key to clear the current line. + +You can press the TAB key to automatically complete your text entry. In any of the debuggers, press the TAB key after you enter at least one character to automatically complete a command. Press the TAB key repeatedly to cycle through text completion options, and hold down the SHIFT key and press TAB to cycle backward. You can also use wildcard characters in the text and press TAB to expand to the full set of text completion options. For example, if you type **fo\*!ba** and then press TAB, the debugger expands to the set of all symbols that start with "ba", in all modules with module names that start with "fo". As another example, you can complete all extension commands that have "prcb" in them by typing **!\*prcb** and then pressing TAB. + +When you use the TAB key to perform text completion, if your text fragment begins with a period (.), the text is matched to a dot command. If your text fragment begins with an exclamation point (!), the text is matched to an extension command. Otherwise, the text is matched with a symbol. When you usee the TAB key to enter symbols, pressing the TAB key completes code and type symbols and module names. If no module name is apparent, local symbols and module names are completed. If a module or module pattern is given, symbol completion completes code and type symbols from all matches. + +You can right-click in the Debugger Command window to automatically paste the contents of the clipboard into the command that you are typing. + +The maximum command length is 4096 characters. However, if you are [controlling the user-mode debugger from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md), the maximum line length is 512 characters. + +In CDB and KD, press the ENTER key by itself to repeat the previous command. In WinDbg, you can enable or disable this behavior. For more information about this behavior, see [**ENTER (Repeat Last Command)**](enter--repeat-last-command-.md). + +If the last command that you issued presents a long display and you want to cut it off, use the [**CTRL+C**](ctrl-c--break-.md) key in CDB or KD. In WinDbg, use [Debug | Break](debug---break.md) or press CTRL+BREAK. + +In kernel-mode debugging, you can cancel commands from the keyboard of the target computer by pressing [**CTRL+C**](ctrl-c--break-.md). + +You can use the [**.cls (Clear Screen)**](-cls--clear-screen-.md) command to clear all of the text from the [Debugger Command window](debugger-command-window.md). This command clears the whole command history. In WinDbg, you can clear the command history by using the [Edit | Clear Command Output](edit---clear-command-output.md) command or by clicking **Clear command output** on the shortcut menu of the Debugger Command window. + +### Expression Syntax + +Many commands and extension commands accept *expressions* as their arguments. The debugger evaluates these expressions before executing the command. For more information about expressions, see [Evaluating Expressions](evaluating-expressions.md). + +### Aliases + +*Aliases* are text macros that you can use to avoid having to retype complex phrases. There are two kinds of aliases. For more information about aliases, see [Using Aliases](using-aliases.md). + +### Self-Repeating Commands + +You can use the following commands to repeat an action or conditionally execute other commands: + +- The [**j (Execute If-Else)**](j--execute-if---else-.md) conditional command + +- The [**z (Execute While)**](z--execute-while-.md) conditional command + +- The [**~e (Thread-Specific Command)**](-e--thread-specific-command-.md) command qualifier + +- (Windows XP and later versions of Windows) The [**!list**](-list.md) extension command + +For more information about each command, see the individual command topics. + +### Controlling Scrolling + +You can use the scrollbar to view your previous commands and their output. + +When you are using CDB or KD, any keyboard entry automatically scrolls down the Debugger Command window back to the bottom. + +In WinDbg, the display automatically scrolls down to the bottom whenever a command produces output or you press the ENTER key. If you want to disable this automatic scrolling, click the [Options](view---options.md) on the **View** menu and then clear the **Automatically scroll** check box. + +### WinDbg Text Features + +In WinDbg, you can use several additional features to change how text is displayed in the [Debugger Command window](debugger-command-window.md). You can access some of these features in the WinDbg window, some in the shortcut menu in the Debugger Command window, and some by clicking on the appropriate menu icon. + +- The **Word wrap** command on the shortcut menu turns on and off the word wrap status. This command affects the whole window, not only commands that you use after this state is changed. Because many commands and extensions produce formatted displays, we typically do not recommend word wrap. + +- The [Edit | Add to Command Output](edit---add-to-command-output.md) menu command adds a comment in the Debugger Command window. The **Add to command output** command on the shortcut menu has the same effect. + +- You can customize the colors that are used for the text and the background of the Debugger Command window. You can specify different colors for different kinds of text. For example, you can display the automatic register output in one color, error messages in another color, and **DbgPrint** messages in a third color. For more information about this customization, see [View | Options](view---options.md). + +- You can use all of the features common to WinDbg's debugging information windows, such as customizing the fonts and using special editing commands. For more information about these features, see [Using Debugging Information Windows](using-debugging-information-windows.md). + +### Remote Debugging + +When you are performing remote debugging through the debugger, the debugging client can access a limited number of commands. To change the number of commands that the client can access, use the **-clines** [command-line option](command-line-options.md) or the \_NT\_DEBUG\_HISTORY\_SIZE [environment variable](environment-variables.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugger%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-debugger-extension-commands.md b/windows-driver-docs-pr/debugger/using-debugger-extension-commands.md new file mode 100644 index 0000000000..e7d29ba1bb --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-debugger-extension-commands.md @@ -0,0 +1,93 @@ +--- +title: Using Debugger Extension Commands +description: Using Debugger Extension Commands +ms.assetid: 1db9a835-accb-41b9-9ab1-c4c9f0596aa5 +keywords: ["extension commands ( commands), using", "extension commands ( commands), default search order"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugger Extension Commands + + +## + + +The use of debugger extension commands is very similar to the use of [debugger commands](using-debugger-commands.md). The command is typed in the Debugger Command window, producing either output in this window or a change in the target application or target computer. + +An actual debugger extension command is an entry point in a DLL called by the debugger. + +Debugger extensions are invoked by the following syntax: + +**!\[***module***.\]***extension* **\[***arguments***\]** + +The module name should not be followed with the .dll file name extension. If *module* includes a full path, the default string size limit is 255 characters. + +If the module has not already been loaded, it will be loaded into the debugger using a call to **LoadLibrary**(*module*). After the debugger has loaded the extension library, it calls the **GetProcAddress** function to locate the extension name in the extension module. The extension name is case-sensitive and must be entered exactly as it appears in the extension module's .def file. If the extension address is found, the extension is called. + +### Search Order + +If the module name is not specified, the debugger will search the loaded extension modules for this export. + +The default search order is as follows: + +1. The extension modules that work with all operating systems and in both modes: Dbghelp.dll and winext\\ext.dll. + +2. The extension module that works in all modes but is operating-system-specific. For Windows XP and later versions of Windows, this is winxp\\exts.dll. There is no corresponding module for Windows 2000. + +3. The extension module that works with all operating systems but is mode-specific. For kernel mode, this is winext\\kext.dll. For user mode, this is winext\\uext.dll. + +4. The extension module that is both operating-system-specific and mode-specific. The following table specifies this module. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Windows BuildUser ModeKernel Mode

Windows 2000 (free build)

w2kfre \ ntsdexts.dll

w2kfre \ kdextx86.dll

Windows 2000 (checked build)

w2kchk \ ntsdexts.dll

w2kchk \ kdextx86.dll

Windows XP and later

winxp \ ntsdexts.dll

winxp \ kdexts.dll

+ +   + +When an extension module is unloaded, it is removed from the search chain. When an extension module is loaded, it is added to the beginning of the search order. The [**.setdll (Set Default Extension DLL)**](-setdll--set-default-extension-dll-.md) command can be used to promote any module to the top of the search chain. By using this command repeatedly, you can completely control the search chain. + +Use the [**.chain (List Debugger Extensions)**](-chain--list-debugger-extensions-.md) command to display a list of all loaded extension modules in their current search order. + +If you attempt to execute an extension command that is not in any of the loaded extension modules, you will get an Export Not Found error message. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugger%20Extension%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-debugging-information-windows.md b/windows-driver-docs-pr/debugger/using-debugging-information-windows.md new file mode 100644 index 0000000000..5052175b93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-debugging-information-windows.md @@ -0,0 +1,45 @@ +--- +title: Using Debugging Information Windows +description: Using Debugging Information Windows +ms.assetid: b7dab453-24ac-4ef4-a48b-e734989b87bf +keywords: ["debugging information windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Debugging Information Windows + + +## + + +WinDbg has ten kinds of debugging information windows. You can have only one instance of the following windows open at the same time: the [Debugger Command window](debugger-command-window.md), the Watch window, the [Locals window](locals-window.md), the [Registers window](registers-window.md), the [Calls window](calls-window.md), the [Disassembly window](disassembly-window.md), the [Processes and Threads window](processes-and-threads-window.md), and the Scratch Pad. In addition to these eight individual windows, WinDbg can display multiple [Source windows](source-window.md) and [Memory windows](memory-window.md) at the same time. + +This section describes the features that are common to all of these windows: + +[Opening a Window](opening-a-window.md) + +[Closing a Window](closing-a-window.md) + +[Configuring a Window](configuring-a-window.md) + +[Moving Through a Window](moving-through-a-window.md) + +[Cutting and Pasting Text](cutting-and-pasting-text.md) + +[Changing Text Properties](changing-text-properties.md) + +[Positioning the Windows](positioning-the-windows.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Debugging%20Information%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-driver-verifier-to-find-a-kernel-mode-memory-leak.md b/windows-driver-docs-pr/debugger/using-driver-verifier-to-find-a-kernel-mode-memory-leak.md new file mode 100644 index 0000000000..403cf94ace --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-driver-verifier-to-find-a-kernel-mode-memory-leak.md @@ -0,0 +1,28 @@ +--- +title: Using Driver Verifier to Find a Kernel-Mode Memory Leak +description: Using Driver Verifier to Find a Kernel-Mode Memory Leak +ms.assetid: d81a8b72-91d3-4132-9cc2-1cf1b597306a +--- + +# Using Driver Verifier to Find a Kernel-Mode Memory Leak + + +Driver Verifier determines whether a kernel-mode driver is leaking memory. + +The Pool Tracking feature of Driver Verifier monitors the memory allocations made by a specified driver. At the time that the driver is unloaded, Driver Verifier verifies that all allocations made by the driver have been freed. If some of the driver's allocations have not been freed, a bug check is issued, and the parameters of the bug check indicate the nature of the problem. + +While this feature is active, use the Driver Verifier Manager graphical interface to monitor pool allocation statistics. If a kernel debugger is attached to the driver, use the [**!verifier 0x3**](-verifier.md) extension to display allocation statistics. + +If the driver uses Direct Memory Access (DMA), the DMA Verification feature of Driver Verifier is also helpful in finding memory leaks. DMA Verification tests for a number of common misuses of DMA routines, including failure to free common buffers and other errors that can lead to memory leaks. If a kernel debugger is attached while this option is active, use the [**!dma**](-dma.md) extension to show allocation statistics. + +For information about Driver Verifier, see [Driver Verifier](http://go.microsoft.com/fwlink/p/?linkid=120480) in the Windows Driver Kit (WDK) documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Driver%20Verifier%20to%20Find%20a%20Kernel-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-http-sites-and-unc-shares-in-conjuction-with-regular-version-con.md b/windows-driver-docs-pr/debugger/using-http-sites-and-unc-shares-in-conjuction-with-regular-version-con.md new file mode 100644 index 0000000000..34213a8e56 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-http-sites-and-unc-shares-in-conjuction-with-regular-version-con.md @@ -0,0 +1,34 @@ +--- +title: Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control +description: Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control +ms.assetid: 1b045a00-45e7-47e8-9447-7d94f70253fe +--- + +# Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control + + +You may find that you must support your developers using the standard SrcSrv functionality that extracts files from version control but must also make source files available through a Web site or UNC share. This could happen if you have set up a test lab that does not have access to version control. It is possible to support both users using the same set of .pdb files. + +First, extract the source files using SrcTool; see [Extracting Source Files](extracting-source-files.md) for details. Make the share available as either a Web site or UNC share. For the current purpose, you should not convert the .pdb files using the Cv2http.cmd script. + +Now on the computers that will use the HTTP/UNC shares, edit the [Srcsrv.ini](the-srcsrv-ini-file.md) file that is in the debugger directory. In the variables section of the file, add the following three statements: + +``` +MY_SOURCE_ROOT=\\server\share + SRCSRVCMD= + SRCSRVTRG=%MY_SOURCE_ROOT%\%var2%\%var3%\%var4%\%fnfile%(%var1%) +``` + +You should replace \\\\server\\share with the root of the UNC share that you are providing or the URL of the Web site that contains the source files. You can also change MY\_SOURCE\_ROOT to be any alias you want to describe this location. With these exceptions, everything else should be entered exactly as described. + +All debuggers set up in this fashion ignore the standard version control extraction instructions and instead access the source files from the location specified. Meanwhile, all debuggers without these items included in Srcsrv.ini use the normal version control mechanism to extract source files. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20HTTP%20Sites%20and%20UNC%20Shares%20in%20Conjuction%20with%20Regular%20Version%20Control%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-input-and-output.md b/windows-driver-docs-pr/debugger/using-input-and-output.md new file mode 100644 index 0000000000..a1cdd475b1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-input-and-output.md @@ -0,0 +1,81 @@ +--- +title: Using Input and Output +description: Using Input and Output +ms.assetid: 7a23ee09-0314-400a-8152-eef49a225427 +keywords: ["Debugger Engine, Input and Output", "Input and Output", "Output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Input and Output + + +## + + +For an overview of the input and output streams in the debugger engine, see [Input and Output](input-and-output.md). + +### Input + +The engine will ask for input from all its clients if the [**Input**](https://msdn.microsoft.com/library/windows/hardware/ff550962) method is called on a client. The input is returned to the caller of **Input**. + +### Input Callbacks + +When the engine asks for input from a client, it uses the [IDebugInputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550785) object registered with that client. An **IDebugInputCallbacks** object may be registered with a client using [*SetInputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556721). Each client can have at most one **IDebugInputCallbacks** object registered with it. + +The request for input begins with the engine calling the [**IDebugInputCallbacks::StartInput**](https://msdn.microsoft.com/library/windows/hardware/ff550797) method. This informs the **IDebugInputCallbacks** object that the engine is now waiting for input. + +If the **IDebugInputCallbacks** object has some input for the engine, it can call the [**ReturnInput**](https://msdn.microsoft.com/library/windows/hardware/ff554600) method of any client. Once the **ReturnInput** method has been called, the engine will not take any more input. Subsequent callers of this method will be informed that the input was not received. + +The engine will then call [**IDebugInputCallbacks::EndInput**](https://msdn.microsoft.com/library/windows/hardware/ff550791) to indicate that it has stopped waiting for input. + +Finally, the engine will echo this input to the registered **IDebugOutputCallbacks** object of every client (except the one used to provide the input) by using [**IDebugOutputCallbacks::Output**](https://msdn.microsoft.com/library/windows/hardware/ff550815) with the bit-mask set to DEBUG\_OUTPUT\_PROMPT. + +### Output + +Output may be sent to the engine using several client methods -- for example [*Output*](https://msdn.microsoft.com/library/windows/hardware/ff553183) and [*OutputVaList*](https://msdn.microsoft.com/library/windows/hardware/ff553280). Upon receiving output, the engine sends it to some clients. + +Clients use an *output mask* to indicate which types of output they are interested in. Whenever output is produced by the engine, it is accompanied by a mask specifying its output type. If the type of output matches the output mask of the client, the client will receive the output. The output mask may be set by calling [**SetOutputMask**](https://msdn.microsoft.com/library/windows/hardware/ff556756) and queried using [**GetOutputMask**](https://msdn.microsoft.com/library/windows/hardware/ff548080). See [**DEBUG\_OUTPUT\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541518) for details of the output mask values. + +The list of clients that the engine will send output to is controlled by the *output control*. Typically, the output control is set to send output to all clients; however, it can be temporarily changed using [*ControlledOutput*](https://msdn.microsoft.com/library/windows/hardware/ff539248) and [*ControlledOutputVaList*](https://msdn.microsoft.com/library/windows/hardware/ff539252). See [**DEBUG\_OUTCTL\_XXX**](https://msdn.microsoft.com/library/windows/hardware/ff541517) for details about output control values. + +Output may be buffered by the engine. If multiple pieces of output are passed to the engine, it may collect them and send them to the clients in one large piece. To flush this buffer, use [**FlushCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff545475). + +Each client object has an *output width*, which is the width of the output display for the client object. While this width is only used as a hint, some commands and extension functions format their output based on this width. The width is returned by the GetOutputWidth method and can be set using the SetOutputWidth method. + +### Output Callbacks + +When the engine sends output to a client, it uses the [IDebugOutputCallbacks](https://msdn.microsoft.com/library/windows/hardware/ff550801) object registered with the client. An **IDebugOutputCallbacks** object may be registered with a client using [*SetOutputCallbacks*](https://msdn.microsoft.com/library/windows/hardware/ff556751). Each client can have at most one **IDebugInputCallbacks** object registered with it. + +To send the output, the engine calls the [**IDebugOutputCallbacks::Output**](https://msdn.microsoft.com/library/windows/hardware/ff550815) method. + +### Output Line Prefix + +Each client object has an *output line prefix* which is prepended to every line of output sent to the output callback associated with the client object. This can be used for indentation or to place identifying marks on each line of output. + +The output line prefix is returned by GetOutputLinePrefix and can be set using SetOutputLinePrefix. To temporarily change the output line prefix and later change it back again, use PushOutputLinePrefix and PopOutputLinePrefix. + +### Log Files + +The debugger engine supports opening a log file to record a debugging session. At most, one log file can be open at a time. Output sent to the output callbacks is also sent to this log file (unless it is flagged to not be logged). + +To open a log file, use [**OpenLogFile2**](https://msdn.microsoft.com/library/windows/hardware/ff553155) (or [**OpenLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff553154)). The method [**GetLogFile2**](https://msdn.microsoft.com/library/windows/hardware/ff547025) (or [**GetLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff547016)) returns the currently open log file. To close the log file, use [**CloseLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff539148). + +The method [**SetLogMask**](https://msdn.microsoft.com/library/windows/hardware/ff556734) can be used to filter the output sent to the log file, and [**GetLogMask**](https://msdn.microsoft.com/library/windows/hardware/ff547066) will return the current log file filter. + +### Prompt + +In an interactive debugging session, a prompt can be used to indicate to the user that the debugger is waiting for user input. The prompt is sent to the output callbacks using the [*OutputPrompt*](https://msdn.microsoft.com/library/windows/hardware/ff553227) and [*OutputPromptVaList*](https://msdn.microsoft.com/library/windows/hardware/ff553231) methods. The contents of the standard prompt are returned by [**GetPromptText**](https://msdn.microsoft.com/library/windows/hardware/ff548180). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Input%20and%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-kdbgctrl.md b/windows-driver-docs-pr/debugger/using-kdbgctrl.md new file mode 100644 index 0000000000..5d1e7fd345 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-kdbgctrl.md @@ -0,0 +1,135 @@ +--- +title: Using KDbgCtrl +description: Using KDbgCtrl +ms.assetid: 386e8861-dd55-440c-9309-7e8cf6c27690 +keywords: ["KDbgCtrl", "KDbgCtrl, basic use", "DbgPrint buffer, changing buffer size", "DbgPrint buffer, KDbgCtrl utility"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using KDbgCtrl + + +The KDbgCtrl (Kernel Debugging Control, kdbgctrl.exe) tool can be used to control the kernel debugging connection from the target computer. + +To use this tool, your target computer must be running Windows Server 2003 or a later version of Windows. + +KDbgCtrl can control five different settings: Full Kernel Debugging, Automatic Kernel Debugging, User-Mode Error Handling, Blocking of Kernel Debugging, and the size of the DbgPrint buffer. + +To use KDbgCtrl, you must have already enabled kernel debugging in the boot settings of the target computer before the last boot. KDbgCtrl cannot be used to enable kernel debugging if this was not done. See [Boot Parameters to Enable Debugging](https://msdn.microsoft.com/library/windows/hardware/ff542279) for details on these boot settings. + +### Full Kernel Debugging + +When Full Kernel Debugging is enabled, a kernel debugger running on the host computer can break into the target computer. The target computer will break into the kernel debugger if a kernel-mode exception is hit. Messages from the target to the host, such as **DbgPrint** output, symbol load messages, and redirected user-mode debuggers, are also allowed. + +If this setting is disabled, all signals from the host computer will be ignored by the target. + +Full Kernel Debugging is enabled by default. To check the current setting value, use **kdbgctrl -c**. To disable this setting, use **kdbgctrl -d**. To enable this setting, use **kdbgctrl -e**. + +If you wish to check the current setting and use it to control execution within a batch file, you can use the **kdbgctrl -cx** command. For details on this command, see [**KDbgCtrl Command-Line Options**](kdbgctrl-command-line-options.md). + +### Automatic Kernel Debugging + +If Full Kernel Debugging is enabled, the current setting for Automatic Kernel Debugging is immaterial -- all communication is permitted. + +When Full Kernel Debugging is disabled and Automatic Kernel Debugging is enabled, only the target computer can initiate a debugging connection. + +In this case, only a kernel-mode exception, breakpoint, or other kernel-mode event will cause a connection to be established. The connection will not be established for **DbgPrint** output, symbol load messages, redirected user-mode debugger input and output, or other similar messages -- these will be stored in the DbgPrint buffer instead of being sent to the kernel debugger. + +If an exception or event causes the target to break into the kernel debugger, then Full Kernel Debugging will be automatically turned on, just as if you had executed **kdbgctrl -e**. + +Automatic Kernel Debugging is disabled by default (although this is immaterial unless Full Kernel Debugging is disabled as well). To check the current setting value, use **kdbgctrl -ca**. To disable this setting, use **kdbgctrl -da**. To enable this setting, use **kdbgctrl -ea**. + +### User-Mode Error Handling + +When User-Mode Error Handling is enabled, some user-mode events will cause the target computer to break into the kernel debugger. + +Specifically, all **int 3** interrupts -- such as breakpoints inserted into the code by a debugger or calls to **DbgBreakPoint** -- will cause a break into the kernel debugger. However, standard exceptions -- such as access violations and division by zero -- will usually not be sent to the kernel debugger. + +If a user-mode debugger is already attached to the process, this debugger will capture all user-mode errors, and the kernel debugger will not be alterted. For the precedence ranking of the various user-mode error handlers, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +For User-Mode Error Handling to function, either Full Kernel Debugging or Automatic Kernel Debugging must be enabled as well. + +User-Mode Error Handling is enabled by default. To check the current setting value, use **kdbgctrl -cu**. To disable this setting, use **kdbgctrl -du**. To enable this setting, use **kdbgctrl -eu**. + +### Blocking Kernel Debugging + +In some cases you might want to set up the target computer for kernel debugging, but wait to enable kernel debugging until after the target computer is started. You can do that by blocking kernel debugging. + +To block kernel debugging, set up the target computer by using commands similar to the following: + +``` +bcdedit /debug on +bcdedit /dbgsettings 1394 channel:32 /start DISABLE /noumex +``` + +When you restart the target computer, it will be prepared for kernel debugging, but kernel debugging and User-Mode Error Handling will be disabled. At that point, a host computer will not be able to attach to the target computer, bug checks will not be caught by the kernel debugger, and user-mode exceptions will not cause a break in to the kernel debugger. + +When you are ready, you can enable kernel debugging (without restarting the target computer) by entering the following commands. + +``` +kdbgctrl -db +kdbgctrl -e +``` + +Later, you can disable kernel debugging by entering the following commands. + +``` +kdbgctrl -d +kdbgctrl -eb +``` + +You can use **kdbgctrl -cb** to check whether kernel debugging is blocked. + +### The DbgPrint Buffer Size + +The DbgPrint buffer stores messages that the target computer has sent to the kernel debugger. + +If Full Kernel Debugging is enabled, these messages will automatically appear in the kernel debugger. But if this option is disabled, these messages will be stored in the buffer. At a later point in time, you can enable kernel debugging, connect to a kernel debugger, and use the [**!dbgprint**](-dbgprint.md) extension to see the contents of this buffer. For more information about this buffer, see The DbgPrint Buffer. + +The default size of the DbgPrint buffer is 4 KB on a free build of Windows, and 32 KB on a checked build of Windows. To determine the current buffer size, use **kdbgctrl -cdb**. To change the buffer size, use **kdbgctrl -sdb***Size*, where *Size* specifies the new buffer size. For syntax details, see [**KDbgCtrl Command-Line Options**](kdbgctrl-command-line-options.md). + +### Examples + +To display all the current settings, use the following command: + +``` +kdbgctrl -c -ca -cu -cb -cdb +``` + +To restore the default settings, use the following command: + +``` +kdbgctrl -e -da -eu -db -sdb 0x1000 +``` + +To lock out the host computer so that it only is contacted on exceptions, use the following command: + +``` +kdbgctrl -d -ea -eu +``` + +To disable all kernel debugging, use the following command: + +``` +kdbgctrl -d -da +``` + +If you are disabling all kernel debugging, you may also wish to increase the size of the DbgPrint buffer. This insures that all messages will be saved in case you need to see them later. If you have a megabyte of memory to spare, you might use the following command: + +``` +kdbgctrl -sdb 0x100000 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20KDbgCtrl%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-linq-with-the-debugger-objects.md b/windows-driver-docs-pr/debugger/using-linq-with-the-debugger-objects.md new file mode 100644 index 0000000000..b6f48dc7d4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-linq-with-the-debugger-objects.md @@ -0,0 +1,724 @@ +--- +title: Using LINQ With the debugger objects +description: Using LINQ With the debugger objects. LINQ syntax can be used with the debugger objects to search and manipulate data. +keywords: ["Using LINQ With the debugger objects"] +ms.author: windowsdriverdev +ms.date: 08/10/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using LINQ With the debugger objects + +LINQ syntax can be used with the debugger objects to search and manipulate data. LINQ is conceptually similar to the Structured Query Language (SQL) that is used to query databases. You can use a number of LINQ methods to search, filter and parse debug data. The LINQ C# method syntax is used. For more information on LINQ and the LINQ C# syntax, see the following topics: + +[LINQ (Language-Integrated Query)](https://msdn.microsoft.com/library/bb397926.aspx) + +[Getting Started with LINQ in C#](https://msdn.microsoft.com/library/bb397933.aspx) + +## Native debugger objects + +Native debugger objects represent various constructs and behaviors of the debugger environment. Example debugger objects include the following. + +- Session +- Threads / Thread +- Processes / Process +- Stack Frames / Stack Frame +- Local Variables +- Modules / Module +- Utility +- State +- Settings + +You can work with the debugger objects with NatVis. For more information see [Native Debugger Objects in NatVis](native-debugger-objects-in-natvis.md). For information about using debugger objects with JavaScript, see [Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md) + +## Dx command + +The examples shown here use the dx command, for more information about working with the dx command, see [dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md). + + +## Function Objects (Lambda Expressions) + +Many of the methods that are used to query data are based on the concept of repeatedly running a user provided function across objects in a collection. To support the ability to query and manipulate data in the debugger, the dx command supports lambda expressions using the equivalent C# syntax. A lambda expression is defined by usage of the => operator as follows: + +(arguments) => (result) + +To see how LINQ is used with dx, try this simple example to add together 5 and 7. + +``` +kd> dx ((x, y) => (x + y))(5, 7) +``` + +The dx command echos back the lambda expression and displays the result of 12. + +``` +((x, y) => (x + y))(5, 7) : 12 +``` + +This example lambda expression combines the strings "Hello" and "World". + +``` +kd> dx ((x, y) => (x + y))("Hello", "World") +((x, y) => (x + y))("Hello", "World") : HelloWorld +``` + +## Debugger Objects Examples + +Debugger objects are projected into a namespace rooted at "Debugger". Processes, modules, threads, stacks, stack frames, and local variables are all available to be used in a LINQ query. + +LINQ commands such as the following can be used .All, .Any, .Count, .First, .Flatten, .GroupBy, .Last, .OrderBy, .OrderByDescending, .Select, and .Where. These methods follow (as closely as possible) the C# LINQ method form. + +This example shows the top 5 processes running the most threads: + +``` +0: kd> dx -r2 Debugger.Sessions.First().Processes.Select(p => new { Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.ThreadCount),5 +Debugger.Sessions.First().Processes.Select(p => new { Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.ThreadCount),5 + +: + [0x4] : + Name : + ThreadCount : 0x73 + [0x708] : + Name : explorer.exe + ThreadCount : 0x2d + [0x37c] : + Name : svchost.exe + ThreadCount : 0x2c + [0x6b0] : + Name : MsMpEng.exe + ThreadCount : 0x22 + [0x57c] : + Name : svchost.exe + ThreadCount : 0x15 + [...] +``` + +This example shows the devices in the plug and play device tree grouped by the name of the physical device object's driver. Not all of the output is shown. + +``` +kd> dx -r2 Debugger.Sessions.First().Devices.DeviceTree.Flatten(n => n.Children).GroupBy(n => n.PhysicalDeviceObject->Driver->DriverName.ToDisplayString()) +Debugger.Sessions.First().Devices.DeviceTree.Flatten(n => n.Children).GroupBy(n => n.PhysicalDeviceObject->Driver->DriverName.ToDisplayString()) + +: + ["\"\\Driver\\PnpManager\""] : + [0x0] : HTREE\ROOT\0 + [0x1] : ROOT\volmgr\0000 (volmgr) + [0x2] : ROOT\BasicDisplay\0000 (BasicDisplay) + [0x3] : ROOT\CompositeBus\0000 (CompositeBus) + [0x4] : ROOT\vdrvroot\0000 (vdrvroot) + ... +``` + +## Dx Command Tab Auto Completion + +Contextual TAB key auto completion is aware of the LINQ query methods and will work for parameters of lambdas. + +As an example, type (or copy and paste) the following text into the debugger. Then hit the TAB key several times to cycle through potential completions. + +``` +dx -r2 Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p. +``` + +Press the TAB key until ".Name" appears. Add a closing parenthesis ")" and press enter to execute the command. + +``` +kd> dx -r2 Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.Name) +Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.Name) : + [0x274] : + Name : winlogon.exe + ThreadCount : 0x4 + [0x204] : + Name : wininit.exe + ThreadCount : 0x2 + [0x6c4] : + Name : taskhostex.exe + ThreadCount : 0x8 + ... +``` + +This example shows completion with a key comparator method. The substitution will show string methods, since the key is a string. + +``` +dx -r2 Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.Name, (a, b) => a. +``` + +Press the TAB key until ".Length" appears. Add a closing parenthesis ")" and press enter to execute the command. + +``` +kd> dx -r2 Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.Name, (a, b) => a.Length) +Debugger.Sessions.First().Processes.Select(p => new {Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.Name, (a, b) => a.Length) : + [0x544] : + Name : spoolsv.exe + ThreadCount : 0xc + [0x4d4] : + Name : svchost.exe + ThreadCount : 0xa + [0x438] : + Name : svchost.exe +``` + +## User Defined Variables + +A user defined variable can be defined by prefixing the variable name with @$. A user defined variable can be assigned to anything dx can utilize, for example, lambdas, the results of LINQ queries, etc. + +You can create and set the value of a user variable like this. + +``` +kd> dx @$String1="Test String" +``` + +You can display the defined user variables using *Debugger.State.UserVariables* or *@$vars*. + +``` +kd> dx Debugger.State.UserVariables +Debugger.State.UserVariables : + mySessionVar : + String1 : Test String +``` + +You can remove a variable using .Remove. + +``` +kd> dx @$vars.Remove("String1") +``` + +This example shows how to define a user variable to reference Debugger.Sesssions. + +``` +kd> dx @$mySessionVar = Debugger.Sessions +``` + +The user defined variable can then be used as shown below. + +``` +kd> dx -r2 @$mySessionVar +@$mySessionVar : + [0x0] : Remote KD: KdSrv:Server=@{},Trans=@{COM:Port=\\.\com3,Baud=115200,Timeout=4000} + Processes : + Devices +``` + +**User Defined Variables - Anonymous Types** + +This creation of dynamic objects is done using the C# anonymous type syntax (new { ... }). For more information see about anonymous types, see [Anonymous Types (C# Programming Guide)](https://msdn.microsoft.com/library/bb397696.aspx). This example create an anonymous type with an integer and string value. + +``` +kd> dx -r1 new { MyInt = 42, MyString = "Hello World" } +new { MyInt = 42, MyString = "Hello World" } : + MyInt : 42 + MyString : Hello World +``` + +## System Defined Variables + +The following system defined variables can be used in any LINQ dx query. + +- @$cursession - The current session + +- @$curprocess - The current process + +- @$curthread - The current thread + +This example show the use of the system defined variables. + +``` +kd> dx @$curprocess.Threads.Count() +@$curprocess.Threads.Count() : 0x4 +``` + +``` +kd> dx -r1 @$curprocess.Threads +@$curprocess.Threads : + [0x4adc] : + [0x1ee8] : + [0x51c8] : + [0x62d8] : + ... +``` + +## Supported LINQ Syntax - Query Methods + +Any object which dx defines as iterable (be that a native array, a type which has NatVis written describing it as a container, or a debugger extension object) has a series of LINQ (or LINQ equivalent) methods projected onto it. Those query methods are described below. The signatures of the arguments to the query methods are listed after all of the query methods. + +Filtering Methods + +| | | +|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| .Where ( PredicateMethod ) | Returns a new collection of objects containing every object in the input collection for which the predicate method returned true. | + +  + +Projection Methods + +| | | +|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .Flatten ( \[KeyProjectorMethod\] ) | Takes an input container of containers (a tree) and flattens it into a single container which has every element in the tree. If the optional key projector method is supplied, the tree is considered a container of keys which are themselves containers and those keys are determined by a call to the projection method. | +| .Select ( KeyProjectorMethod ) | Returns a new collection of objects containing the result of calling the projector method on every object in the input collection. | + +  + +Grouping Methods + +| | | +|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .GroupBy ( KeyProjectorMethod, \[KeyComparatorMethod\] ) | Returns a new collection of collections by grouping all objects in the input collection having the same key as determined by calling the key projector method. An optional comparator method can be provided. | +| Join (InnerCollection, Outer key selector method, Inner key selector method, Result selector method, \[ComparatorMethod\]) | Joins two sequences based on key selector functions and extracts pairs of values. An optional comparator method can also be specified. | +| Intersect (InnerCollection, \[ComparatorMethod\]) | Returns the set intersection, which means elements that appear in each of two collections. An optional comparator method can also be specified. | +| Union (InnerCollection, \[ComparatorMethod\]) | Returns the set union, which means unique elements that appear in either of two collections. An optional comparator method can also be specified. | + +  + +Data Set Methods + +| | | +|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Contains (Object, \[ComparatorMethod\]) | Determines whether a sequence contains a specified element. An optional comparator method can be provided that will be called each time the element is compared against an entry in the sequence. | +| Distinct (\[ComparatorMethod\]) | Removes duplicate values from a collection. An optional comparator method can be provided to be called each time objects in the collection must be compared. | +| Except (InnerCollection, \[ComparatorMethod\]) | Returns the set difference, which means the elements of one collection that do not appear in a second collection. An optional comparator method can be specified. | +| Concat (InnerCollection) | Concatenates two sequences to form one sequence. | + +  + +Ordering Methods + +| | | +|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .OrderBy ( KeyProjectorMethod, \[KeyComparatorMethod\] ) | Sorts the collection in ascending order according to a key as provided by calling the key projection method on every object in the input collection. An optional comparator method can be provided. | +| .OrderByDescending ( KeyProjectorMethod, \[KeyComparatorMethod\] ) | Sorts the collection in descending order according to a key as provided by calling the key projection method on every object in the input collection. An optional comparator method can be provided. | + +  + +Aggregating Methods + +| | | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Count () | A method that returns the number of elements in the collection. | +| Sum (\[ProjectionMethod\]) | Calculates the sum of the values in a collection. Can optionally specify a projector method to transform the elements before summation occurs. | + +  + +Skip Methods + +| | | +|-----------------------------|-----------------------------------------------------------------------------------------------| +| Skip (Count) | Skips elements up to a specified position in a sequence. | +| SkipWhile (PredicateMethod) | Skips elements based on a predicate function until an element does not satisfy the condition. | + +  + +Take Methods + +| | | +|-----------------------------|-----------------------------------------------------------------------------------------------| +| Take (Count) | Takes elements up to a specified position in a sequence. | +| TakeWhile (PredicateMethod) | Takes elements based on a predicate function until an element does not satisfy the condition. | + +  + +Comparison Methods + +| | | +|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| +| SequenceEqual (InnerCollection, \[ComparatorMethod\]) | Determines whether two sequences are equal by comparing elements in a pair-wise manner. An optional comparator can be specified. | + +  + +Error Handling Methods + +| | | +|-------------------------------------|-----------------------------------------------------------------------------------| +| AllNonError (PredicateMethod) | Returns whether all non-error elements of a collection satisfy a given condition. | +| FirstNonError (\[PredicateMethod\]) | Returns the first element of a collection that isn’t an error. | +| LastNonError (\[PredicateMethod\]) | Returns the last element of a collection that isn’t an error. | + +  + +Other Methods + +| | | +|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .All ( PredicateMethod ) | Returns whether the result of calling the specified predicate method on every element in the input collection is true. | +| .Any ( PredicateMethod ) | Returns whether the result of calling the specified predicate method on any element in the input collection is true. | +| .First ( \[PredicateMethod\] ) | Returns the first element in the collection. If the optional predicate is passed, returns the first element in the collection for which a call to the predicate returns true. | +| .Last ( \[PredicateMethod\] ) | Returns the last element in the collection. If the optional predicate is passed, returns the last element in the collection for which a call to the predicate returns true. | +| Min(\[KeyProjectorMethod\]) | Returns the minimum element of the collection. An optional projector method can be specified to project each method before it is compared to others. | +| Max(\[KeyProjectorMethod\]) | Returns the maximum element of the collection. An optional projector method can be specified to project each method before it is compared to others. | +| Single(\[PredicateMethod\]) | Returns the only element from the list (or an error if the collection contains more than one element). If a predicate is specified, returns the single element that satisfies that predicate (if more than one element satisfies it, the function returns an error instead). | + +  + +**Signatures of the Arguments** + + ++++ + + + + + + + + + + + + + + +
KeyProjectorMethod : ( obj => arbitrary key )Takes an object of the collection and returns a key from that object.
KeyComparatorMethod: ( (a, b) => integer value )Takes two keys and compares them returning: +

-1 if ( a < b )

+

0 if ( a == b)

+

1 if ( a > b )

PredicateMethod: ( obj => boolean value )Takes an object of the collection and returns true or false based on whether that object meets certain criteria.
+ +  + +## Supported LINQ Syntax - String Manipulation + +All string objects have the following methods projected into them, so that they are available for use: + +Query Relevant Methods & Properties + +| | | +|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .Contains ( OtherString ) | Returns a boolean value indicating whether the input string contains OtherString. | +| .EndsWith ( OtherString ) | Returns a boolean value indicating whether the input string ends with OtherString. | +| Length | A property which returns the length of the string. | +| .StartsWith ( OtherString ) | Returns a boolean value indicating whether the input string starts with OtherString. | +| .Substring ( StartPos, \[Length\] ) | Returns a substring within the input string starting at the given starting position. If the optional length is supplied, the returned substring will be of the specified length; otherwise – it will go to the end of the string. | + +  + +Miscellaneous Methods + +| | | +|------------------------------|-----------------------------------------------------------------------------------| +| .IndexOf ( OtherString ) | Returns the index of the first occurrence of OtherString within the input string. | +| .LastIndexOf ( OtherString ) | Returns the index of the last occurrence of OtherString within the input string. | + +  + +Formatting Methods + +| | | +|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .PadLeft ( TotalWidth ) | Adds spaces as necessary to the left side of the string in order to bring the total length of the string to the specified width. | +| .PadRight ( TotalWidth ) | Adds spaces as necessary to the right side of the string in order to bring the total length of the string to the specified width. | +| .Remove ( StartPos, \[Length\] ) | Removes characters from the input string starting as the specified starting position. If the optional length parameter is supplied, that number of characters will be removed; otherwise – all characters to the end of the string will be removed. | +| .Replace ( SearchString, ReplaceString ) | Replaces every occurrence of SearchString within the input string with the specified ReplaceString. | + +  + +String Object Projections + +In addition to the methods which are projected directly onto string objects, any object which itself has a string conversion has the following method projected onto it, making it method available for use: + +| | | +|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .ToDisplayString ( ) | Returns a string conversion of the object. This is the string conversion which would be shown in a dx invocation for the object. You can provide a formatting specifier to format the output of ToDisplayString. | + +  + +The following examples illustrate the use of format specifiers. + +``` +kd> dx (10).ToDisplayString("d") +(10).ToDisplayString("d") : 10 + +kd> dx (10).ToDisplayString("x") +(10).ToDisplayString("x") : 0xa + +kd> dx (10).ToDisplayString("o") +(10).ToDisplayString("o") : 012 + +kd> dx (10).ToDisplayString("b") +(10).ToDisplayString("b") : 0y1010 +``` + +## Debugging Plug and Play Example + + +This section illustrates how the built in debugger objects used with LINQ queries, can be used to debug plug and play objects. + +**View all devices** + +Use *Flatten* on the device tree to view all devices. + +``` + 1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children) + [0x0] : HTREE\ROOT\0 + [0x1] : ROOT\volmgr\0000 (volmgr) + [0x2] : ROOT\BasicDisplay\0000 (BasicDisplay) + [0x3] : ROOT\CompositeBus\0000 (CompositeBus) + [0x4] : ROOT\vdrvroot\0000 (vdrvroot) + [0x5] : ROOT\spaceport\0000 (spaceport) + [0x6] : ROOT\KDNIC\0000 (kdnic) + [0x7] : ROOT\UMBUS\0000 (umbus) + [0x8] : ROOT\ACPI_HAL\0000 +... +``` + +**Grid Display** + +As with other dx commands, you can right click on a command after it was executed and click "Display as grid" or add "-g" to the command to get a grid view of the results. + +``` +# 0: kd> dx -g @$cursession.Devices.DeviceTree.Flatten(n => n.Children) +===================================================================================================================================================================================================================================================================================================================== +# = = (+) DeviceNodeObject = InstancePath = ServiceName = (+) PhysicalDeviceObject = State = (+) Resoures = (+) Children = +===================================================================================================================================================================================================================================================================================================================== += [0x0] : HTREE\ROOT\0 - {...} - HTREE\ROOT\0 - - 0xffffb6075614be40 : Device for "\Driver\PnpManager" - DeviceNodeStarted (776) - {...} - [object Object] = += [0x1] : ROOT\volmgr\0000 (volmgr) - {...} - ROOT\volmgr\0000 - volmgr - 0xffffb607561fbe40 : Device for "\Driver\PnpManager" - DeviceNodeStarted (776) - {...} - [object Object] = += [0x2] : ROOT\BasicDisplay\0000 (BasicDisplay) - {...} - ROOT\BasicDisplay\0000 - BasicDisplay - 0xffffb607560739b0 : Device for "\Driver\PnpManager" - DeviceNodeStarted (776) - {...} - [object Object] = += [0x3] : ROOT\CompositeBus\0000 (CompositeBus) - {...} - ROOT\CompositeBus\0000 - CompositeBus - 0xffffb607561f9060 : Device for "\Driver\PnpManager" - DeviceNodeStarted (776) - {...} - [object Object] = +... +``` + +**View Devices by State** + +Use *Where* to specify a specific device state. + +``` +dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.State ) +``` + +For example to view devices in state DeviceNodeStarted use this command. + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.State == 776) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.State == 776) + [0x0] : HTREE\ROOT\0 + [0x1] : ROOT\volmgr\0000 (volmgr) + [0x2] : ROOT\BasicDisplay\0000 (BasicDisplay) + [0x3] : ROOT\CompositeBus\0000 (CompositeBus) + [0x4] : ROOT\vdrvroot\0000 (vdrvroot) +... +``` + +**View Not Started Devices** + +Use this command to view devices not in state DeviceNodeStarted. + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.State != 776) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.State != 776) + [0x0] : ACPI\PNP0C01\1 + [0x1] : ACPI\PNP0000\4&215d0f95&0 + [0x2] : ACPI\PNP0200\4&215d0f95&0 + [0x3] : ACPI\PNP0100\4&215d0f95&0 + [0x4] : ACPI\PNP0800\4&215d0f95&0 + [0x5] : ACPI\PNP0C04\4&215d0f95&0 + [0x6] : ACPI\PNP0700\4&215d0f95&0 (fdc) + [0x7] : ACPI\PNP0C02\1 + [0x8] : ACPI\PNP0C02\2 +``` + +**View Devices by Problem Code** + +Use the *DeviceNodeObject.Problem* object to view devices that have specific problem codes. + +``` +dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem ) +``` + +For example, to view devices that have a non zero problem code use this command. This provides similar information to "[**!devnode**](-devnode.md) 0 21". + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem != 0) + [0x0] : HTREE\ROOT\0 + [0x1] : ACPI\PNP0700\4&215d0f95&0 (fdc) +``` + +**View All Devices Without a Problem** + +Use this command to view all devices without a problem + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem == 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem == 0) + [0x0] : ROOT\volmgr\0000 (volmgr) + [0x1] : ROOT\BasicDisplay\0000 (BasicDisplay) + [0x2] : ROOT\CompositeBus\0000 (CompositeBus) + [0x3] : ROOT\vdrvroot\0000 (vdrvroot) +... +``` + +**View All Devices With a Specific Problem** + +Use this command to view devices with a problem state of 0x16. + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem == 0x16) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.DeviceNodeObject.Problem == 0x16) + [0x0] : HTREE\ROOT\0 + [0x1] : ACPI\PNP0700\4&215d0f95&0 (fdc) +``` + +**View Devices by Function Driver** + +Use this command to view devices by function driver. + +``` +dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.ServiceName ) +``` + +To view devices using a certain function driver, such as atapi, use this command. + +``` +1: kd> dx @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.ServiceName == "atapi") +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => n.ServiceName == "atapi") + [0x0] : PCIIDE\IDEChannel\4&10bf2f88&0&0 (atapi) + [0x1] : PCIIDE\IDEChannel\4&10bf2f88&0&1 (atapi) +``` + +**Viewing a List of Boot Start Drivers** + +To view the list of what winload loaded as boot start drivers, you need to be in a context where you have access to the LoaderBlock and early enough the LoaderBlock is still around. For example, during nt!IopInitializeBootDrivers. A breakpoint can be set to stop in this context. + +``` +1: kd> g +Breakpoint 0 hit +nt!IopInitializeBootDrivers: +8225c634 8bff mov edi,edi +``` + +Use the ?? command to display the boot driver structure. + +``` +1: kd> ?? LoaderBlock->BootDriverListHead +struct _LIST_ENTRY + [ 0x808c9960 - 0x808c8728 ] + +0x000 Flink : 0x808c9960 _LIST_ENTRY [ 0x808c93e8 - 0x808a2e18 ] + +0x004 Blink : 0x808c8728 _LIST_ENTRY [ 0x808a2e18 - 0x808c8de0 ] +``` + +Use the Debugger.Utility.Collections.FromListEntry debugger object to view of the data, using the starting address of the nt!\_LIST\_ENTRY structure. + +``` +1: kd> dx Debugger.Utility.Collections.FromListEntry(*(nt!_LIST_ENTRY *)0x808c9960, "nt!_BOOT_DRIVER_LIST_ENTRY", "Link") +Debugger.Utility.Collections.FromListEntry(*(nt!_LIST_ENTRY *)0x808c9960, "nt!_BOOT_DRIVER_LIST_ENTRY", "Link") + [0x0] [Type: _BOOT_DRIVER_LIST_ENTRY] + [0x1] [Type: _BOOT_DRIVER_LIST_ENTRY] + [0x2] [Type: _BOOT_DRIVER_LIST_ENTRY] + [0x3] [Type: _BOOT_DRIVER_LIST_ENTRY] + [0x4] [Type: _BOOT_DRIVER_LIST_ENTRY] + [0x5] [Type: _BOOT_DRIVER_LIST_ENTRY] +... +``` + +Use the -g option to create a grid view of the data. + +``` +dx -r1 -g Debugger.Utility.Collections.FromListEntry(*(nt!_LIST_ENTRY *)0x808c9960, "nt!_BOOT_DRIVER_LIST_ENTRY", "Link") +``` + +**View devices by Capability** + +View devices by capability using the DeviceNodeObject.CapabilityFlags object. + +``` +dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & ) != 0) +``` + +This table summarizes the use of the dx command with common device capability flags. + + ++++ + + + + + + + + + + + + + + + + + + + + + + +
Removable
+``` +0: kd> dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x10) != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x10) != 0) + [0x0] : SWD\PRINTENUM\{2F8DBBB6-F246-4D84-BB1D-AA8761353885} + [0x1] : SWD\PRINTENUM\{F210BC77-55A1-4FCA-AA80-013E2B408378} + [0x2] : SWD\PRINTENUM\{07940A8E-11F4-46C3-B714-7FF9B87738F8} + [0x3] : DISPLAY\Default_Monitor\6&1a097cd8&0&UID5527112 (monitor) +``` +
UniqueID
+``` +0: kd> dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x40) != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x40) != 0) + [0x0] : HTREE\ROOT\0 + [0x1] : ROOT\volmgr\0000 (volmgr) + [0x2] : ROOT\spaceport\0000 (spaceport) +... +``` +
SilentInstall
+``` +0: kd> dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x80) != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x80) != 0) + [0x0] : HTREE\ROOT\0 + [0x1] : ROOT\volmgr\0000 (volmgr) + [0x2] : ROOT\spaceport\0000 (spaceport) +... +``` +
RawDeviceOk
+``` +0: kd> dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x100) != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x100) != 0) + [0x0] : HTREE\ROOT\0 + [0x1] : SWD\MMDEVAPI\MicrosoftGSWavetableSynth + [0x2] : SWD\IP_TUNNEL_VBUS\IP_TUNNEL_DEVICE_ROOT +... +``` +
SurpriseRemovalOK
+``` +0: kd> dx -r1 @$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x200) != 0) +@$cursession.Devices.DeviceTree.Flatten(n => n.Children).Where(n => (n.DeviceNodeObject.CapabilityFlags & 0x200) != 0) + [0x0] : SWD\MMDEVAPI\MicrosoftGSWavetableSynth + [0x1] : SWD\IP_TUNNEL_VBUS\IP_TUNNEL_DEVICE_ROOT + [0x2] : SWD\PRINTENUM\PrintQueues +... +``` +
+ +  +For more information about the CapabilityFlags, see [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095). + + +## See also + +[dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md) + +[Native Debugger Objects in NatVis](native-debugger-objects-in-natvis.md) + +[Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md)  + +--- + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20dx%20%28Display%20Debugger%20Object%20Model%20Expression%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/using-logger-exe.md b/windows-driver-docs-pr/debugger/using-logger-exe.md new file mode 100644 index 0000000000..99551f7e04 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-logger-exe.md @@ -0,0 +1,82 @@ +--- +title: Using Logger.exe +description: Using Logger.exe +ms.assetid: da2ec999-4529-49dc-855e-a7d3b15583f7 +keywords: ["Logger, logger.exe", "logger.exe", "Logger, stand-alone"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Logger.exe + + +## + + +One way to activate Logger is to run the stand-alone Logger.exe program. This is essentially a very small debugger that can only take a single target. To run it, include the name of the target application on the command line: + +``` +logger Target +``` + +When this is activated, it will load the specified application, and insert code into the target application that will jump off to a routine that loads and initializes Logexts.dll in the target application process. This is referred to as "injecting Logger into the target application." + +The Logger.exe utility and the Logexts.dll module are the two components of this Logger vehicle. They communicate through a shared section of memory that includes the output file handles, current category mask, and a pointer to the log output buffer. + +A window entitled **Logger (debugger)** will appear. This window will display the progress of Logger. + +### Change Settings Dialog Box + +After the initialization finishes and the initial display is complete, the **Change Settings** dialog box will appear. This allows you to configure the Logger settings. The various settings are described here: + +**API Settings** +This list displays the available API categories. The highlighted categories will be logged; the non-highlighted categories will not. The first time you run Logger, all categories will be highlighted. However, on subsequent runs, Logger will keep track of which categories are selected for a given target application. + +If a category is disabled, the hooks for all APIs in that category will be removed so that there is no longer any performance overhead. COM hooks are not removed because they cannot be re-enabled at will. + +Enabling only certain categories can be useful when you are only interested in a particular type of interaction that the program is having with Windows -- for example, file operations. This reduces the log file size and also reduces the effect that Logger has on the execution speed of the process. + +**Logging** +This section contains **Enable** and **Disable** radio buttons. Disabling logging will cause all API hooks to be removed in an effort to allow the program to run freely. COM hooks are not removed because they cannot be re-enabled at will. + +**Inclusion / Exclusion List** +This section controls the module inclusion/exclusion list. It is often desirable to log only those function calls that are made from a certain module or set of modules. To facilitate that, Logger allows you to specify a module inclusion list or, alternatively, a module exclusion list. For instance, you would use an inclusion list if you only wanted to log calls from one or two module. If you wanted to log calls made from all modules except a short list of modules, you would use an exclusion list. The modules Logexts.dll and Kernel32.dll are always excluded, since Logger is not permitted to log itself. + +**Flush the Buffer** +This button will flush the current output buffer. As a performance consideration, log output is flushed to disk only when the output buffer is full. By default, the buffer is 2144 bytes. + +Since the buffer memory is managed by the target application, the automatic writing of the buffer to the log files on the disk will not occur if there is an access violation or some other non-recoverable error in the target application. In such cases, you should try to activate the target application's window and hit F12 to get this dialog box back, and then press **Flush the Buffer**. If this is not done, the most recently-logged functions might not appear in the log files. + +**Go** +This causes the target application to begin executing. + +### Running the Target Application + +Once you have chosen the settings, click **Go**. The dialog box will close and the target application will begin to run. + +If you make the target application's window active and press F12, it will break into Logger. This will cause the target application to freeze and the **Change Settings** dialog box to reappear. You can alter the settings if you wish, and then press **Go** to continue execution. + +You can let the target application run for as long as you wish. If it terminates normally or due to an error, the logging will stop and cannot be restarted. + +When you wish to exit, select **File | Exit** and click **Yes**. If the target application is still running, it will be terminated. + +### Limitations of Logger.exe + +When you are running Logger through the Logger.exe tool, it will create only one output file -- an .lgv file. No text file will be written. However, a .txt file of size zero will be created; this could overwrite a text log written by the debugger previously. + +The output file will always be placed in LogExts subdirectory of the desktop; this location cannot be changed. + +These limitations will not apply if you are running Logger through the debugger and Logexts.dll. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Logger.exe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-logging-to-track-important-events.md b/windows-driver-docs-pr/debugger/using-logging-to-track-important-events.md new file mode 100644 index 0000000000..37e7c729d6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-logging-to-track-important-events.md @@ -0,0 +1,142 @@ +--- +title: Using Logging to Track Important Events +description: Using Logging to Track Important Events +ms.assetid: 297336c2-85fb-4235-a7ab-0bbf571b8b98 +keywords: ["kernel streaming debugging, video stream stall, logging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Logging to Track Important Events + + +In general, data is moved downstream only by triggering events, the minidriver's processing, and buffer completions. To isolate the cause of a hang or stall: + +- Check for mismatched **KsGate*Xxx*** calls. + +- Check for omitted **Ks*Xxx*AttemptProcessing** calls. + +- Look for problems in code related to triggering events, including code that either references the pin flags for the problem stream or that calls **KsPinAttemptProcessing**. + +- Look for problems in the code related to the processing dispatch, in particular where it queues to hardware and where clone pointers are created. + +- Look for problems in the code related to the driver's deferred procedure call (DPC), especially where buffers are completed or any calls are made to [KsStreamPointerDelete](http://go.microsoft.com/fwlink/p/?linkid=56550). + +- Look for problems in the startup code for the stream. + +The most effective way to collect this information is by logging everything in the affected region, including processing, buffer acquisition (such as cloning and programming hardware), buffer release (such as deleting clones), and any gate manipulations. Most of this information is highly timing dependent and requires memory-based logging or ETW. + +To maintain a rolling memory-based log, use the following code: + +``` +typedef struct _LOGENTRY { + ULONG Tag; + ULONG Arg[3]; +} LOGENTRY, *PLOGENTRY; +#define LOGSIZE 2048 +LONG g_LogCount; +LOGENTRY g_Log [LOGSIZE]; +#define LOG(tag,arg1,arg2,arg3) do { \ + LONG i = InterlockedIncrement (&g_LogCount) % LOGSIZE; \ + g_Log [i].Tag = tag; \ + g_Log [i].Arg [0] = (ULONG)(arg1); \ + g_Log [i].Arg [1] = (ULONG)(arg2); \ + g_Log [i].Arg [2] = (ULONG)(arg3); \ +} while (0) +``` + +Then, use a simple "dc g\_Log" to view the contents of the **g\_Log** array in the debugger. + +The following example uses the above memory-based scheme to determine the cause of a processing stall. Output is from an AVStream streaming scenario in graphedt. The following minidriver events were logged: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AbbreviationDescription

Strt

This event occurs when the minidriver first queues buffers for the device from within the minidriver's Start dispatch.

Prc<

This event occurs at the start of the minidriver's Process dispatch.

AddB

This event occurs when the minidriver queues buffers to the device from within its Process dispatch.

DPC<

This event occurs at the start of the minidriver's CallOnDPC. It indicates buffer completion.

Atmp

This event occurs when the minidriver calls from within the DPC to KsPinAttemptProcessing.

Dele

This event occurs when the minidriver calls from within the DPC to delete a clone stream pointer.

+ +  + +Log excerpts are as follows: + +``` +f9494b80 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f9494b90 656c6544 816e2c90 81750260 00000000 Dele.,n.`.u..... +f9494ba0 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +f9494bb0 3c637250 819c1f00 00000000 00000000 Prc<............ +f9494bc0 42646441 819c1f00 ffa2eb08 00000000 AddB............ +f9494bd0 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f9494be0 656c6544 816e2c90 ffa80348 00000000 Dele.,n.H....... +f9494bf0 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +f9494c00 3c637250 819c1f00 00000000 00000000 Prc<............ +f9494c10 42646441 819c1f00 ffa3d9b8 00000000 AddB............ +``` + +This first log excerpt is representative of the normal streaming state. In the first line, the minidriver's *CallOnDPC* is called to complete a buffer (*DPC<*). The buffer is deleted (*Dele*), and **KsPinAttemptProcessing** is called to move the leading edge forward, if there are any unprocessed buffers in the queue (*Atmp*). In this case, there were, as can be seen by the call to the process dispatch (*Prc<*). More buffers are added to the queue (*AddB*), and the whole scenario repeats. + +This next excerpt includes the last entries in the log right before the stall occurred. + +``` +f949b430 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f949b440 656c6544 816e2c90 ffac4de8 00000000 Dele.,n..M...... +f949b450 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +f949b460 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f949b470 656c6544 816e2c90 816ffc80 00000000 Dele.,n...o..... +f949b480 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +f949b490 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f949b4a0 656c6544 816e2c90 ffa80348 00000000 Dele.,n.H....... +f949b4b0 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +f949b4c0 3c435044 816e2c90 00000000 00000000 DPC<.,n......... +f949b4d0 656c6544 816e2c90 8174e1c0 00000000 Dele.,n...t..... +f949b4e0 706d7441 816e2c90 ffa4d418 00000000 Atmp.,n......... +``` + +In this example, several buffers are being completed (indicated by the repeated instances of *DPC<*), but there are no unprocessed buffers in the queue, so the process dispatch is not being called (indicated by the absence of *Prc<*). In fact, all of the processed buffers in the queue have been completed, apparently before any new unprocessed buffers could be added. Because the application is already running (so that *Start* will not be called) and no calls are being made to *CallOnDPC* (because there are no processed buffers ready to be completed), any new buffers are apparently accumulating ahead of the leading edge, waiting to be processed, with nothing initiating processing. + +The problem is that the KSPIN\_FLAG\_DO\_NOT\_INITIATE\_PROCESSING flag has been set. When this flag is set, processing occurs only through a call to *Start* or *CallOnDPC*. If this flag is not set, processing will be initiated whenever new buffers are added to the queue. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Logging%20to%20Track%20Important%20Events%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-other-source-control-systems.md b/windows-driver-docs-pr/debugger/using-other-source-control-systems.md new file mode 100644 index 0000000000..69823b6243 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-other-source-control-systems.md @@ -0,0 +1,32 @@ +--- +title: Using Other Source Control Systems +description: Using Other Source Control Systems +ms.assetid: c8ce0bec-7218-486e-8600-c217f2e6c069 +keywords: ["version control systems", "version control systems, Subversion", "source servers, writing your own version control system", "provider modules", "provider modules, creating your own"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Other Source Control Systems + + +Included in this package is Svn.pm. A closer look at this file shows how you can modify one of the existing scripts to support the Subversion Version Control system. Other control systems, even a control system that you create yourself, can be supported by creating your own provider module. + +This section includes: + +[Creating Your Own Provider Module](creating-your-own-provider-module.md) + +[Creating Your Own Source Control System](creating-your-own-source-control-system.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Other%20Source%20Control%20Systems%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-pdbcopy.md b/windows-driver-docs-pr/debugger/using-pdbcopy.md new file mode 100644 index 0000000000..af4929cc94 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-pdbcopy.md @@ -0,0 +1,115 @@ +--- +title: Using PDBCopy +description: Using PDBCopy +ms.assetid: f8207b09-5a1b-4ff3-b99d-20daa88cfe10 +keywords: ["PDBCopy, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PDBCopy + + +PDBCopy is a command-line tool that creates a stripped symbol file from a full symbol file. In other words, it takes a symbol file that contains both private symbol data and a public symbol table, and creates a copy of that file that contains only the public symbol table. Depending on which PDBCopy options are used, the stripped symbol file contains either the entire public symbol table or a specified subset of the public symbol table. + +PDBCopy works with any PDB-format symbol file (with file name extension .pdb), but not with the older format (.dbg) symbol files. + +For a description of public symbol tables and private symbol data, see [Public and Private Symbols](public-and-private-symbols.md). + +### Removing Private Symbols + +If you wish to create a stripped symbol file that contains all the public symbols and none of the private symbols, use PDBCopy with three parameters: the path and name of the original symbol file, the path and name of the new symbol file, and the -p option. + +For example, the following command creates a new file, named publicsymbols.pdb, which contains the same public symbol table as mysymbols.pdb but contains none of the private symbol data: + +**pdbcopy mysymbols.pdb publicsymbols.pdb -p** + +If mysymbols.pdb happens to already be a stripped symbol file, the symbolic content of the new file and the old file will be identical. + +After issuing this command, you should move the new file to a new location and rename it to the original name of the symbol file (in this example, mysymbols.pdb), because most debugging programs and symbol extraction programs look for symbols based on a specific file name. Alternatively, you could use the same file name for the input file and the output file on the PDBCopy command line, as long as different directories are specified: + +**pdbcopy c:\\dir1\\mysymbols.pdb c:\\dir2\\mysymbols.pdb -p** + +**Note**  The destination file should not exist before PDBCopy is run. If a file with this name exists, various errors may occur. + +  + +### Removing Private Symbols and Selected Public Symbols + +If you wish to not only remove the private symbol data, but also reduce the amount of information in the public symbol table, you can use the -f option to specify a list of public symbols that are to be removed. + +The following example illustrates this procedure: + +1. Determine the full names, including decorations, of the symbols you wish to remove. If you are not sure of the decorated symbol names, you can use the [DBH](dbh.md) tool to determine them. See Determining the Decorations of a Specific Symbol for details. In this example, let us suppose that the decorated names of the symbols you wish to remove are **\_myGlobal1** and **\_myGlobal2**. + +2. Create a text file containing a list of the symbols to be removed. Each line in this file should include the name of one symbol, including decorations, but not including module names. In this example, the file would contain the following two lines: + + ``` + _myGlobal1 + _myGlobal2 + ``` + + The file can be given any name you choose. Let us suppose that you name this file listfile.txt and place it in the directory C:\\Temp. + +3. Use the following PDBCopy command line: + + ``` + pdbcopy OldPDB NewPDB-p -f:@TextFile + ``` + + where *OldPDB* and *NewPDB* are the original symbol file and the new symbol file, and *TextFile* is the file created in step two. The -f option indicates that certain public symbols are to be removed, and the ampersand ( @ ) indicates that these symbols are listed in the specified text file. + + In the current example, the command would look like this: + + ``` + pdbcopy c:\dir1\mysymbols.pdb c:\dir3\mysymbols.pdb -p -f:@c:\temp\listfile.txt + ``` + + This creates a new symbol file, C:\\dir2\\mysymbols.pdb, which does not contain any private symbols and does not contain the two global variables you listed in listfile.txt. + +As shown in this example, PDBCopy's -f option removes a specific list of public symbols. The ampersand ( @ ) indicates that these symbols are listed in a text file. An alternate method is to list all the symbols on the command line, using the -f option without an ampersand. Thus the following command line is equivalent to the example in the procedure above: + +**pdbcopy c:\\dir1\\mysymbols.pdb c:\\dir3\\mysymbols.pdb -p -f:\_myGlobal1 -f:\_myGlobal2** + +Unless you wish to remove only one or two symbols, it is simpler to use a text file than to list them on the command line. + +If you wish to remove the majority of public symbols from your .pdb file, the -F option is the easiest method. While the -f option requires you to list those public symbols you wish to remove, the -F option requires you to list those public symbols you do not wish to remove. All other public symbols (as well as all private symbols) will be removed. The -F option supports the same two syntax options as the -f option: either -F: followed by the name of a symbol to be retained, or -F:@ followed by the name of a text file that contains a list of the symbols to be retained. In either case, decorated symbol names must be used. + +For example, the following command removes all private symbols and almost all public symbols, leaving only the symbols **\_myFunction5** and **\_myGlobal7**: + +**pdbcopy c:\\dir1\\mysymbols.pdb c:\\dir3\\mysymbols.pdb -p -F:\_myFunction5 -F:\_myGlobal7** + +If you combine multiple instances of the -f option on one line, all the specified symbols are removed. If you combine multiple instances of the -F option on one line, all the specified symbols are retained, and all other symbols are removed. You cannot combine -f with -F. + +The -f and -F options cannot be used without the -p option, which removes all private symbol data. Even if your original file contains no private symbols, you must still include the -p option (although it has no effect in this case). + +The -F option cannot be used to prevent the private symbol data from being removed. If you use this option with a symbol that is not included in the public symbol table, PDBCopy ignores it. + +### The mspdb\*.dll File + +PDBCopy must access either the Mspdb80.dll file or the Mspdb60.dll file in order to run. By default, PDBCopy uses Mspdb80.dll, which is the version used by Visual Studio .NET 2002 and later versions of Visual Studio. If your symbols were built using Visual Studio 6.0 or an earlier version, you can specify the -vc6 command-line option so that PDBCopy uses Mspdb60.dll instead, although this is not required. PDBCopy looks for the appropriate file even if the -vc6 option is not used. You can find these files within your installation of Visual Studio, the Platform SDK, or the Windows Driver Kit (WDK). + +Before running PDBCopy, make sure that the correct version of mspdb\*.dll file is accessible to your computer, and make sure that its location is part of the command path. If it is not, you should use the **path** command to add this location to the command path. + +### The File Signature and the SymSrv Index + +Each symbol file has a fixed signature that uniquely identifies it. SymSrv uses the signature to generate a unique "index value" for the file. If two files have different contents or different creation times, they will also have distinct signatures and distinct SymSrv index values. + +Files created with PDBCopy are an exception to the rule of unique index values. When PDBCopy creates a new symbol file, it has the same signature and SymSrv index value as the old file. This feature allows one file to be replaced with the other without altering the behavior of symbol-related tools. + +If you wish the new file to have a distinct signature and SymSrv index, use the -s option. In most cases you will not wish to use this option, since the most common use of PDBCopy is to create an altered symbol file that can replace the old file without causing a mismatch. A new signature may cause SymSrv to assign a different index value to the new file than to the old file, preventing new file from properly replacing the old one. + +For the complete command line syntax, see [**PDBCopy Command-Line Options**](pdbcopy-command-line-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20PDBCopy%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-performance-monitor-to-find-a-user-mode-memory-leak.md b/windows-driver-docs-pr/debugger/using-performance-monitor-to-find-a-user-mode-memory-leak.md new file mode 100644 index 0000000000..5da01b0990 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-performance-monitor-to-find-a-user-mode-memory-leak.md @@ -0,0 +1,40 @@ +--- +title: Using Performance Monitor to Find a User-Mode Memory Leak +description: Using Performance Monitor to Find a User-Mode Memory Leak +ms.assetid: 07ba4c55-299c-4558-b4c7-4ffe5c47f496 +keywords: ["memory leak, user-mode, performance monitor"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Performance Monitor to Find a User-Mode Memory Leak + + +If you suspect there is a user-mode memory leak but are not sure which process is causing it, you can use Performance Monitor to measure the memory usage of individual processes. + +Launch Performance Monitor. Add the following counters: + +- **Process**-->**Private Bytes** (for each process you want to examine) + +- **Process**-->**Virtual Bytes** (for each process you wish to examine) + +Change the update time to 600 seconds to capture a graph of the leak over time. You might also want to log the data to a file for later examination. + +The **Private Bytes** counter indicates the total amount of memory that a process has allocated, not including memory shared with other processes. The **Virtual Bytes** counter indicates the current size of the virtual address space that the process is using. + +Some memory leaks appear in the data file as an increase in private bytes allocated. Other memory leaks show up as an increase in the virtual address space. + +After you have determined which process is leaking memory, use the UMDH tool to determine the specific routine that is at fault. For details, see [Using UMDH to Find User-Mode Memory Leaks](using-umdh-to-find-a-user-mode-memory-leak.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Performance%20Monitor%20to%20Find%20a%20User-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-poolmon-to-find-a-kernel-mode-memory-leak.md b/windows-driver-docs-pr/debugger/using-poolmon-to-find-a-kernel-mode-memory-leak.md new file mode 100644 index 0000000000..5f4000f636 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-poolmon-to-find-a-kernel-mode-memory-leak.md @@ -0,0 +1,130 @@ +--- +title: Using PoolMon to Find a Kernel-Mode Memory Leak +description: Using PoolMon to Find a Kernel-Mode Memory Leak +ms.assetid: 383b5d9a-3e99-4dc5-bce9-bd44f2ef1dc0 +keywords: ["memory leak, kernel-mode, PoolMon", "PoolMon", "PoolMon, finding a memory leak"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PoolMon to Find a Kernel-Mode Memory Leak + + +If you suspect there is a kernel-mode memory leak, the easiest way to determine which pool tag is associated with the leak is to use the PoolMon tool. + +PoolMon (Poolmon.exe) monitors pool memory usage by pool tag name. This tool is included in the Windows Driver Kit (WDK). For a full description, see [PoolMon](http://go.microsoft.com/fwlink/p/?linkid=122776) in the WDK documentation. + +### Enable Pool Tagging (Windows 2000 and Windows XP) + +On Windows 2000 and Windows XP you must first use GFlags to enable pool tagging. GFlags is included in Debugging Tools for Windows. Start GFlags, choose the **System Registry** tab, check the **Enable Pool Tagging** box, and then click **Apply**. You must restart Windows for this setting to take effect. For more details, see [GFlags](gflags.md). + +On Windows Server 2003 and later versions of Windows, pool tagging is always enabled. + +### Using PoolMon + +The PoolMon header displays the total paged and non-paged pool bytes. The columns show pool use for each pool tag. The display is updated automatically every few seconds. For example: + +``` +Memory: 16224K Avail: 4564K PageFlts: 31 InRam Krnl: 684K P: 680K +Commit: 24140K Limit: 24952K Peak: 24932K Pool N: 744K P: 2180K + +## Tag Type Allocs Frees Diff Bytes Per Alloc + + +CM Paged 1283 ( 0) 1002 ( 0) 281 1377312 ( 0) 4901 +Strg Paged 10385 ( 10) 6658 ( 4) 3727 317952 ( 512) 85 +Fat Paged 6662 ( 8) 4971 ( 6) 1691 174560 ( 128) 103 +MmSt Paged 614 ( 0) 441 ( 0) 173 83456 ( 0) 482 +``` + +PoolMon has command keys that sort the output according to various criteria. Press the letter associated with each command in order to re-sort the data. It takes a few seconds for each command to work. + +The sort commands include: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Command KeyOperation

P

Limits the tags shown to nonpaged pool, paged pool, or both. Repeatedly pressing P cycles through each of these options, in that order.

B

Sorts tags by maximum byte usage.

M

Sorts tags by maximum byte allocations.

T

Sorts tags alphabetically by tag name.

E

Causes the display to include the paged and non-paged totals across the bottom.

A

Sorts tags by allocation size.

F

Sorts tags by free operations.

S

Sorts tags by the difference between allocations and frees.

Q

Quits PoolMon.

+ +  + +### Using the PoolMon Utility to Find a Memory Leak + +To find a memory leak with the PoolMon utility, follow this procedure: + +1. Start PoolMon. + +2. If you have determined that the leak is occurring in non-paged pool, press **P** once; if you have determined that it is occurring in paged pool, press **P** twice. If you do not know, do not press **P** and both kinds of pool are included. + +3. Press **B** to sort the display by maximum byte use. + +4. Start your test. Take a screen shot and copy it to Notepad. + +5. Take a new screen shot every half hour. By comparing screen shots, determine which tag's bytes are increasing. + +6. Stop your test and wait a few hours. How much of the tag was freed up in this time? + +Typically, after an application reaches a stable running state, it allocates memory and free memory at roughly the same rate. If it tends to allocate memory faster than it frees it, its memory use will grow over time. This often indicates a memory leak. + +### Addressing the Leak + +After you have determined which pool tag is associated with the leak, this might reveal all you need to know about the leak. If you need to determine which specific instance of the allocation routine is causing the leak, see [Using the Kernel Debugger to Find Kernel-Mode Memory Leaks](using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20PoolMon%20to%20Find%20a%20Kernel-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-script-files.md b/windows-driver-docs-pr/debugger/using-script-files.md new file mode 100644 index 0000000000..767667bede --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-script-files.md @@ -0,0 +1,43 @@ +--- +title: Using Script Files +description: Using Script Files +ms.assetid: b78a651e-57c8-4863-a8cf-dedd8e308e66 +keywords: ["script file", "script file, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Script Files + + +## + + +A *script file* is a text file that contains a sequence of debugger commands. There are a variety of ways for the debugger to load a script file and execute it. A script file can contain commands to be executed sequentially or can use a more complex flow of execution. + +To execute a script file, you can do one of the following: + +- (KD and CDB only; only when the debugger starts) Create a script file that is named Ntsd.ini and put it in the directory where you are starting the debugger from. The debugger automatically executes this file when the debugger starts. To use a different file for the startup script file, specify the path and file name by using the **-cf** [command-line option](command-line-options.md) or by using the **IniFile** entry in the [Tools.ini](configuring-tools-ini.md) file. + +- (KD and CDB only; when each session starts) Create a script file and specify its path and file name by using the **-cfr** [command-line option](command-line-options.md). The debugger automatically executes this script file when the debugger starts and every time that the target is restarted. + +- Use the **$<**, **$><**, **$$<**, and **$$><** commands to execute a script file after the debugger is running. For more information about the syntax, see [**$<, $><, $><, $$>< (Run Script File)**](-----------------------a---run-script-file-.md). + +The **$><** and **$$><** commands differ from the other methods of running scripts in one important way. When you use these commands, the debugger opens the specified script file, replaces all carriage returns with semicolons, and executes the resulting text as a single command block. These commands are useful for running scripts that contain debugger command programs. For more information about these programs, see [Using Debugger Command Programs](using-debugger-command-programs.md).X + +You cannot use commands that are available only in WinDbg (such as [**.lsrcfix (Use Local Source Server)**](-srcfix---lsrcfix--use-source-server-.md), [**.lsrcpath (Set Local Source Path)**](-srcpath---lsrcpath--set-source-path-.md), [**.open (Open Source File)**](-open--open-source-file-.md), and [**.write\_cmd\_hist (Write Command History)**](-write-cmd-hist--write-command-history-.md)) in script files, even if the script file is executed in WinDbg. In addition, you cannot use the [**.beep (Speaker Beep)**](-beep--speaker-beep-.md), [**.cls (Clear Screen)**](-cls--clear-screen-.md), [**.hh (Open HTML Help File)**](-hh--open-html-help-file-.md), [**.idle\_cmd (Set Idle Command)**](-idle-cmd--set-idle-command-.md), [**.remote (Create Remote.exe Server)**](-remote--create-remote-exe-server-.md), kernel-mode [**.restart (Restart Kernel Connection)**](-restart--restart-kernel-connection-.md), user-mode [**.restart (Restart Target Application)**](-restart--restart-target-application-.md), or [**.wtitle (Set Window Title)**](-wtitle--set-window-title-.md) commands in a script file. + +WinDbg supports the same scripts as KD and CDB, with one minor exception. You can use the [**.remote\_exit (Exit Debugging Client)**](-remote-exit--exit-debugging-client-.md) command only in a script file that KD or CDB uses. You cannot exit from a debugging client though a script that is executed in WinDbg. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Script%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-shell-commands.md b/windows-driver-docs-pr/debugger/using-shell-commands.md new file mode 100644 index 0000000000..7b14fc0caf --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-shell-commands.md @@ -0,0 +1,39 @@ +--- +title: Using Shell Commands +description: Using Shell Commands +ms.assetid: 16df2592-0e7d-4cd3-bc35-5323578cf555 +keywords: ["shell commands", "shell commands, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Shell Commands + + +## + + +The debugger can transmit certain commands to the Microsoft Windows environment in which the debugger is running. + +You can use the [**.shell (Command Shell)**](-shell--command-shell-.md) command in any Windows debugger. With this command, you can execute an application or a Microsoft MS-DOS command directly from the debugger. If you are performing [remote debugging](remote-debugging.md), these shell commands are executed on the server. + +The [**.noshell (Prohibit Shell Commands)**](-noshell--prohibit-shell-commands-.md) command or the **-noshell** [command-line option](command-line-options.md) disables all shell commands. The commands are disabled while the debugger is running, even if you begin a new debugging session. The commands remain disabled even if you issue a [**.restart (Restart Kernel Connection)**](-restart--restart-kernel-connection-.md) command in KD. + +If you are running a debugging server,you might want to disable shell commands. If the shell is available, a remote connection can use the **.shell** command to change your computer. + +### Network Drive Control + +In WinDbg, you can use the [File | Map Network Drive](file---map-network-drive.md) and [File | Disconnect Network Drive](file---disconnect-network-drive.md) commands to control the network drive mappings. These changes always occur on the computer that WinDbg is running on, never on any computer that is remotely connected to WinDbg. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Shell%20Commands%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-source-files.md b/windows-driver-docs-pr/debugger/using-source-files.md new file mode 100644 index 0000000000..ba02d3b5b0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-source-files.md @@ -0,0 +1,44 @@ +--- +title: Using Source Files +description: Using Source Files +ms.assetid: c6dfcb37-140f-43d8-aa15-14f0317b5e19 +keywords: ["Debugger Engine API, source"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Source Files + + +The [debugger engine](introduction.md#debugger-engine) maintains a *source path*, which is a list of directories and source servers that contain source code files associated with the current targets. The debugger engine can search these directories and source servers for the source files. With the help of symbol files, the debugger engine can match lines in the source files with locations in the target's memory. + +For an overview of using source files with debuggers, see [Debugging in Source Mode](debugging-in-source-mode.md). For an overview of source paths, see [Source Path](source-path.md). For an overview of using source servers from the debugger engine, see [Using a Source Server](using-a-source-server.md). + +### Source Path + +To add a directory or source server to the source path, use the method [**AppendSourcePath**](https://msdn.microsoft.com/library/windows/hardware/ff538102). The whole source path is returned by [**GetSourcePath**](https://msdn.microsoft.com/library/windows/hardware/ff548358) and can be changed using [**SetSourcePath**](https://msdn.microsoft.com/library/windows/hardware/ff556781). A single directory or source server can be retrieved from the source path using [**GetSourcePathElement**](https://msdn.microsoft.com/library/windows/hardware/ff548367). + +To find a source file relative to the source path, use [**FindSourceFile**](https://msdn.microsoft.com/library/windows/hardware/ff545423) or, for more advanced options when using source servers, use [**FindSourceFileAndToken**](https://msdn.microsoft.com/library/windows/hardware/ff545430). **FindSourceFileAndToken** can also be used along with [**GetSourceFileInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548321) to retrieve variables related to a file on a source server. + +### Matching Source Files to Code in Memory + +The debugger engine provides three methods for locating the memory locations that correspond to lines in a source file. To map a single line of source code to a memory location, use [**GetOffsetByLine**](https://msdn.microsoft.com/library/windows/hardware/ff548022). To search for memory locations for more than one source line or for nearby source lines, use [**GetSourceEntriesByLine**](https://msdn.microsoft.com/library/windows/hardware/ff548305). The [**GetSourceFileLineOffsets**](https://msdn.microsoft.com/library/windows/hardware/ff548339) method will return the memory location of every line in a source file. + +To perform the opposite operation and find the line of a source file that matches a location in the target's memory, use [**GetLineByOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546995). + +**Note**  The relationship between memory locations and lines in a source file is not necessarily one-to-one. It is possible for a single line of source code to correspond to multiple memory locations and for a single memory location to correspond to multiple lines of source code. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Source%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-srcsrv.md b/windows-driver-docs-pr/debugger/using-srcsrv.md new file mode 100644 index 0000000000..828fac9865 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-srcsrv.md @@ -0,0 +1,50 @@ +--- +title: Using SrcSrv +description: Using SrcSrv +ms.assetid: 2696e5e9-343f-49a2-bdab-23a54f8c9e5c +keywords: ["source servers, SrcSrv (srcsrv.dll)", "SrcSrv, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using SrcSrv + + +To use [SrcSrv](srcsrv.md) with WinDbg, KD, NTSD, or CDB, verify that you have installed a recent version of the Debugging Tools for Windows package (version 6.3 or later). Then, include the text `srv*` in the source path, separated by semicolons from any directories that are also in the source path. + +For example: + +``` +.srcpath srv*;c:\someSourceCode +``` + +If the source path is set as shown in the preceding example, the debugger first uses [SrcSrv](srcsrv.md) to retrieve source files from locations specified in the target modules' symbol files. If SrcSrv is unable to retrieve a source file, the debugger attempts to retrieve it from c:\\someSourceCode. Regardless of whether srv\* is the first element in the path or appears later, the debugger always uses SymSrv before it searches any other directories listed in the path. + +If a source file is retrieved by [SrcSrv](srcsrv.md), it remains on your hard drive after the debugging session is over. Source files are stored locally in the src subdirectory of the home directory (unlike the symbol server, the source server does not specify a local cache in the `srv*` syntax itself). The home directory defaults to the Debugging Tools for Windows installation directory; it can be changed by using the [**!homedir**](-homedir.md) extension or by setting the DBGHELP\_HOMEDIR environment variable. If the src subdirectory of the home directory does not already exist, it is created. + +### Debugging SrcSrv + +If you experience any trouble extracting the source files from the debugger, start the debugger with the -n command-line parameter to view the actual source extraction commands along with the output of those commands. The !sym noisy command does the same thing, but you may have already missed important information from previous extraction attempts. This is because the debugger gives up trying to access source from version control repositories that appear to be unreachable. + +### Retrieving Source Files + +If you use the [**.open (Open Source File)**](-open--open-source-file-.md) command to open a new source file through [SrcSrv](srcsrv.md), you must include the -m Address parameter. + +To facilitate the use of [SrcSrv](srcsrv.md) from tools other than the debuggers listed previously, the DbgHelp API provides access to SrcSrv functionality through the **SymGetSourceFile** function. To retrieve the name of the source file to be retrieved, call the **SymEnumSourceFiles** or **SymGetLineFromAddr64** function. For more details on the DbgHelp API, see the dbghelp.chm documentation, which can be found in the sdk/help subdirectory of the Debugging Tools for Windows installation directory, or see [Debug Help Library](http://go.microsoft.com/fwlink/p/?linkid=125231) on MSDN. + +### Using AgeStore to Reduce the Cache Size + +Any source files downloaded by [SrcSrv](srcsrv.md) remain on your hard drive after the debugging session is over. To control the size of the source cache, the AgeStore tool can be used to delete cached files that are older than a specified date or to reduce the contents of the cache below a specified size. For details, see [AgeStore](agestore.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20SrcSrv%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-symbols.md b/windows-driver-docs-pr/debugger/using-symbols.md new file mode 100644 index 0000000000..a6c2d2d3f6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-symbols.md @@ -0,0 +1,69 @@ +--- +title: Using Symbols +description: Using Symbols +ms.assetid: 1de1441f-b4d7-49e9-87ad-392a75b3d4be +keywords: ["Debugger Engine, symbols", "symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Symbols + + +## + + +For an overview of symbols, including using symbol files and symbol servers, see [Symbols](symbols.md). + +### Symbol Names and Locations + +To find the location of a symbol given its name, use [**GetOffsetByName**](https://msdn.microsoft.com/library/windows/hardware/ff548035). For details on the syntax used to specify symbol names, see [Symbol Syntax and Symbol Matching](symbol-syntax-and-symbol-matching.md). + +If the exact name of a symbol is not known, or multiple symbols have the same name, [**StartSymbolMatch**](https://msdn.microsoft.com/library/windows/hardware/ff558815) will begin a search for symbols whose names match a given pattern. For details on the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). + +To find the name of a symbol given its location, use [**GetNameByOffset**](https://msdn.microsoft.com/library/windows/hardware/ff547183). To find the names of symbols in a module near a given location, use [**GetNearNamebyOffset**](https://msdn.microsoft.com/library/windows/hardware/ff547204). + +**Note**   Whenever possible, qualify the symbol with the module name -- for example **mymodule!main**. Otherwise, if the symbol does not exist (for example, because of a typographical error) the engine will have to load and search the symbols for every module; this can be a slow process, especially for kernel-mode debugging. If the symbol name was qualified with a module name, the engine will only need to search the symbols for that module. + +  + +A symbol is uniquely identified using the structure [**DEBUG\_MODULE\_AND\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff541511). This structure is returned by the methods [**GetSymbolEntriesByName**](https://msdn.microsoft.com/library/windows/hardware/ff548458) and [**GetSymbolEntriesByOffset**](https://msdn.microsoft.com/library/windows/hardware/ff548476), which search for symbols based on their name and location, respectively. + +The method [**GetSymbolEntryInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548484) returns a description of a symbol using the [**DEBUG\_SYMBOL\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff541662) structure. + +To find the offset of a field within a structure, use [**GetFieldOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546758). To find the name of a field given its index within a structure, use [**GetFieldName**](https://msdn.microsoft.com/library/windows/hardware/ff546747). To find the name of an enumeration constant given its value, use [**GetConstantName**](https://msdn.microsoft.com/library/windows/hardware/ff545702). + +The method [**GetSymbolInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548505) can perform several requests for information about symbols. + +### Symbol Options + +A number of options control how the symbols are loaded and unloaded. For a description of these options, see [Setting Symbol Options](symbol-options.md). + +Symbol options may be turned on by using [**AddSymbolOptions**](https://msdn.microsoft.com/library/windows/hardware/ff537930), and turned off by using [**RemoveSymbolOptions**](https://msdn.microsoft.com/library/windows/hardware/ff554535). + +[**GetSymbolOptions**](https://msdn.microsoft.com/library/windows/hardware/ff549139) returns the current symbol options. To set all the symbol options at once, use [**SetSymbolOptions**](https://msdn.microsoft.com/library/windows/hardware/ff556798). + +### Reloading Symbols + +After loading symbol files, the engine stores the symbol information in an internal cache. To flush this cache, use [**Reload**](https://msdn.microsoft.com/library/windows/hardware/ff554379). These symbols will have to be loaded again now or at a later time. + +### Synthetic Symbols + +*Synthetic symbols* are a way to label an arbitrary address for easy reference. Synthetic symbols can be created in any existing module. The method [**AddSyntheticSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff537943) creates a new synthetic symbol. Synthetic symbols can be removed using [**RemoveSyntheticSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff554542). Reloading the symbols for the module deletes all synthetic symbols associated with that module. + +### Symbol Path + +To add a directory or symbol server to the symbol path, use the method [**AppendSymbolPath**](https://msdn.microsoft.com/library/windows/hardware/ff538110). The whole symbol path is returned by [**GetSymbolPath**](https://msdn.microsoft.com/library/windows/hardware/ff549155) and can be changed using [**SetSymbolPath**](https://msdn.microsoft.com/library/windows/hardware/ff556802). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-symchk.md b/windows-driver-docs-pr/debugger/using-symchk.md new file mode 100644 index 0000000000..2f3eb57b72 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-symchk.md @@ -0,0 +1,154 @@ +--- +title: Using SymChk +description: Using SymChk +ms.assetid: 60c3df99-a842-4e46-a504-8e2b54030eef +keywords: ["SymChk, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using SymChk + + +## + + +The basic syntax for SymChk is as follows: + +``` +symchk [/r] FileNames /s SymbolPath +``` + +*FileNames* specifies one or more program files whose symbols are needed. If *FileNames* is a directory and the **/r** flag is used, this directory is explored recursively, and SymChk will try to find symbols for all program files in this directory tree. *SymbolPath* specifies where SymChk is to search for symbols. + +There are many more command-line options. For a full listing, see [**SymChk Command-Line Options**](symchk-command-line-options.md). + +The symbol path specified can include any number of local directories, UNC directories, or symbol servers. Local directories and UNC directories are not searched recursively. Only the specified directory and a subdirectory based on the executable's extension are searched. For example, the query + +``` +symchk thisdriver.sys /s g:\symbols +``` + +will search g:\\mysymbols and g:\\mysymbols\\sys. + +You can specify a symbol server by using either of the following syntaxes as part of your symbol path: + +``` +srv*DownstreamStore*\\Server\Share +srv*\\Server\Share +``` + +This is very similar to using a symbol server in the debugger's symbol path. For details on this, see [Using Symbol Servers and Symbol Stores](symbol-stores-and-symbol-servers.md). + +If a downstream store is specified, SymChk will make copies of all valid symbol files found by the symbol server and place them in the downstream store. Only symbol files that are complete matches are copied downstream. + +SymChk always searches the downstream store before querying the symbol server. Therefore you should be careful about using a downstream store when someone else is maintaining the symbol store. If you run SymChk once and it finds symbol files, it will copy those to the downstream store. If you then run SymChk again after these files have been altered or deleted on the symbol store, SymChk will not notice this fact, since it will find what it is looking for on the downstream store and look no further. + +**Note**   SymChk always uses SymSrv (Symsrv.dll) as its symbol server DLL. On the other hand, the debuggers can choose a symbol server DLL other than SymSrv if one is available. (SymSrv is the symbol server included in the Debugging Tools for Windows package.) + +  + +### Using SymChk to determine whether symbols are private or public + +To determine whether a symbol file is private or public, use the **/v** parameter so that SymChk displays verbose output. Suppose MyApp.exe and MyApp.pdb are in the folder c:\\sym. Enter this command. + +**symchk /v c:\\sym\\MyApp.exe /s c:\\sym** + +If MyApp.pdb contains private symbols, the output of SymChk looks like this. + +``` +[SYMCHK] Searching for symbols to c:\sym\MyApp.exe in path c:\sym +... +DBGHELP: MyApp - private symbols & lines + c:\sym\MyApp.pdb +... +SYMCHK: FAILED files = 0 +SYMCHK: PASSED + IGNORED files = 1 +``` + +If MyApp.pdb contains only public symbols, the output of SymChk looks like this. + +``` +[SYMCHK] Searching for symbols to c:\sym\MyApp.exe in path c:\sym +... +DBGHELP: MyApp - public symbols + c:\sym\MyApp.pdb +... +SYMCHK: FAILED files = 0 +SYMCHK: PASSED + IGNORED files = 1 +``` + +To limit your search so that it finds only public symbol files, use the **s** option with the **/s** parameter (**/ss**). The following command finds a match if MyApp.pdb contains only public symbols. It does not find a match if MyApp.pdb contains private symbols. + +**symchk /v c:\\sym\\MyApp.exe /ss c:\\sym** + +For more information, see [Public and Private Symbols](public-and-private-symbols.md). + +### Examples + +Here are some examples. The following command searches for symbols for the program Myapp.exe: + +``` +e:\debuggers> symchk f:\myapp.exe /s f:\symbols\applications + +SYMCHK: Myapp.exe FAILED - Myapp.pdb is missing + +SYMCHK: FAILED files = 1 +SYMCHK: PASSED + IGNORED files = 0 +``` + +You can try again with a different symbol path: + +``` +e:\debuggers> symchk f:\myapp.exe /s f:\symbols\newdirectory + +SYMCHK: FAILED files = 0 +SYMCHK: PASSED + IGNORED files = 1 +``` + +The search was successful this time. If the verbose option is not used, SymChk will only list files for which it failed to find symbols. So in this example no files were listed. You can tell that the search succeeded because there is now one file listed in the "passed" category and none in the "failed" category. + +A program file is ignored if it contains no executable code. Many resource files are of this type. + +If you prefer to see the file names of all program files, you can use the **/v** option to generate verbose output: + +``` +e:\debuggers> symchk /v f:\myapp.exe /s f:\symbols\newdirectory + +SYMCHK: MyApp.exe PASSED + +SYMCHK: FAILED files = 0 +SYMCHK: PASSED + IGNORED files = 1 +``` + +The following command searches for a huge number of Windows symbols in a symbol server. There are a great variety of possible error messages: + +``` +e:\debuggers> symchk /r c:\windows\system32 /s srv*\\manysymbols\windows + +SYMCHK: msisam11.dll FAILED - MSISAM11.pdb is missing +SYMCHK: msuni11.dll FAILED - msuni11link.pdb is missing +SYMCHK: msdxm.ocx FAILED - Image is split correctly, but msdxm.dbg i +s missing +SYMCHK: expsrv.dll FAILED - Checksum doesn't match with expsrv.DBG +SYMCHK: imeshare.dll FAILED - imeshare.opt.pdb is missing +SYMCHK: ir32_32.dll FAILED - Built with no debugging information +SYMCHK: author.dll FAILED - rpctest.pdb is missing +SYMCHK: msvcrt40.dll FAILED - Built with no debugging information +...... +SYMCHK: FAILED files = 211 +SYMCHK: PASSED + IGNORED files = 4809 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20SymChk%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the--analyze-extension.md b/windows-driver-docs-pr/debugger/using-the--analyze-extension.md new file mode 100644 index 0000000000..f801ec4d3d --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the--analyze-extension.md @@ -0,0 +1,354 @@ +--- +title: Using the analyze Extension +description: Using the analyze Extension +ms.assetid: 0aa74153-e992-4d1c-b734-ccc60cff452c +keywords: ["analyze extension, examples"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the !analyze Extension + + +## + + +The first step in debugging a crashed target computer or application is to use the [**!analyze**](-analyze.md) extension command. + +This extension performs a tremendous amount of automated analysis. The results of this analysis are displayed in the Debugger Command window. + +You should use the **-v** option for a fully verbose display of data. For details on other options, see the [**!analyze**](-analyze.md) reference page. + +This topic contains: + +A User-Mode !analyze -v Example + +A Kernel-Mode !analyze -v Example + +The Followup Field and the triage.ini File + +Additional !analyze Techniques + +### A User-Mode !analyze -v Example + +In this example, the debugger is attached to a user-mode application that has encountered an exception. + +``` +0:000> !analyze -v +******************************************************************************* +* * +* Exception Analysis * +* * +******************************************************************************* + +Debugger SolutionDb Connection::Open failed 80004005 +``` + +If you are connected to the internet, the debugger attempts to access a database of crash solutions maintained by Microsoft. In this case, an error message was displayed, indicating that either your machine was unable to access the internet or the web site was not working. + +``` +FAULTING_IP: +ntdll!PropertyLengthAsVariant+73 +77f97704 cc int 3 +``` + +The FAULTING\_IP field shows the instruction pointer at the time of the fault. + +``` +EXCEPTION_RECORD: ffffffff -- (.exr ffffffffffffffff) +ExceptionAddress: 77f97704 (ntdll!PropertyLengthAsVariant+0x00000073) + ExceptionCode: 80000003 (Break instruction exception) + ExceptionFlags: 00000000 +NumberParameters: 3 + Parameter[0]: 00000000 + Parameter[1]: 00010101 + Parameter[2]: ffffffff +``` + +The EXCEPTION\_RECORD field shows the exception record for this crash. This information can also be viewed by using the [**.exr (Display Exception Record)**](-exr--display-exception-record-.md) command. + +``` +BUGCHECK_STR: 80000003 +``` + +The BUGCHECK\_STR field shows the exception code. The name is a misnomer—the term *bug check* actually signifies a kernel-mode crash. In user-mode debugging, the exception code will be displayed—in this case, 0x80000003. + +``` +DEFAULT_BUCKET_ID: APPLICATION_FAULT +``` + +The DEFAULT\_BUCKET\_ID field shows the general category of failures that this failure belongs to. + +``` +PROCESS_NAME: MyApp.exe +``` + +The PROCESS\_NAME field specifies the name of the process that raised the exception. + +``` +LAST_CONTROL_TRANSFER: from 01050963 to 77f97704 +``` + +The LAST\_CONTROL\_TRANSFER field shows the last call on the stack. In this case, the code at address 0x01050963 called a function at 0x77F97704. You can use these addresses with the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) command to determine what modules and functions these addresses reside in. + +``` +STACK_TEXT: +0006b9dc 01050963 00000000 0006ba04 000603fd ntdll!PropertyLengthAsVariant+0x73 +0006b9f0 010509af 00000002 0006ba04 77e1a449 MyApp!FatalErrorBox+0x55 [D:\source_files\MyApp\util.c @ 541] +0006da04 01029f4e 01069850 0000034f 01069828 MyApp!ShowAssert+0x47 [D:\source_files\MyApp\util.c @ 579] +0006db6c 010590c3 000e01ea 0006fee4 0006feec MyApp!SelectColor+0x103 [D:\source_files\MyApp\colors.c @ 849] +0006fe04 77e11d0a 000e01ea 00000111 0000413c MyApp!MainWndProc+0x1322 [D:\source_files\MyApp\MyApp.c @ 1031] +0006fe24 77e11bc8 01057da1 000e01ea 00000111 USER32!UserCallWinProc+0x18 +0006feb0 77e172b4 0006fee4 00000001 010518bf USER32!DispatchMessageWorker+0x2d0 +0006febc 010518bf 0006fee4 00000000 01057c5d USER32!DispatchMessageA+0xb +0006fec8 01057c5d 0006fee4 77f82b95 77f83920 MyApp!ProcessQCQPMessage+0x3b [D:\source_files\MyApp\util.c @ 2212] +0006ff70 01062cbf 00000001 00683ed8 00682b88 MyApp!main+0x1e6 [D:\source_files\MyApp\MyApp.c @ 263] +0006ffc0 77e9ca90 77f82b95 77f83920 7ffdf000 MyApp!mainCRTStartup+0xff [D:\source_files\MyApp\crtexe.c @ 338] +0006fff0 00000000 01062bc0 00000000 000000c8 KERNEL32!BaseProcessStart+0x3d +``` + +The STACK\_TEXT field shows a stack trace of the faulting component. + +``` +FOLLOWUP_IP: +MyApp!FatalErrorBox+55 +01050963 5e pop esi + +FOLLOWUP_NAME: dbg + +SYMBOL_NAME: MyApp!FatalErrorBox+55 + +MODULE_NAME: MyApp + +IMAGE_NAME: MyApp.exe + +DEBUG_FLR_IMAGE_TIMESTAMP: 383490a9 +``` + +When [**!analyze**](-analyze.md) determines the instruction that has probably caused the error, it displays it in the FOLLOWUP\_IP field. The SYMBOL\_NAME, MODULE\_NAME, IMAGE\_NAME, and DBG\_FLR\_IMAGE\_TIMESTAMP fields show the symbol, module, image name, and image timestamp corresponding to this instruction. + +``` +STACK_COMMAND: .ecxr ; kb +``` + +The STACK\_COMMAND field shows the command that was used to obtain the STACK\_TEXT. You can use this command to repeat this stack trace display, or alter it to obtain related stack information. + +``` +BUCKET_ID: 80000003_MyApp!FatalErrorBox+55 +``` + +The BUCKET\_ID field shows the specific category of failures that the current failure belongs to. This category helps the debugger determine what other information to display in the analysis output. + +``` +Followup: dbg +--------- +``` + +For information about the FOLLOWUP\_NAME and the Followup fields, see The Followup Field and the triage.ini File. + +There are a variety of other fields that may appear: + +- If control was transferred to an invalid address, then the FAULTING\_IP field will contain this invalid address. Instead of the FOLLOWUP\_IP field, the FAILED\_INSTRUCTION\_ADDRESS field will show the disassembled code from this address, although this disassembly will probably be meaningless. In this situation, the SYMBOL\_NAME, MODULE\_NAME, IMAGE\_NAME, and DBG\_FLR\_IMAGE\_TIMESTAMP fields will refer to the caller of this instruction. + +- If the processor misfires, you may see the SINGLE\_BIT\_ERROR, TWO\_BIT\_ERROR, or POSSIBLE\_INVALID\_CONTROL\_TRANSFER fields. + +- If memory corruption seems to have occurred, the CHKIMG\_EXTENSION field will specify the [**!chkimg**](-chkimg.md) extension command that should be used to investigate. + +### A Kernel-Mode !analyze -v Example + +In this example, the debugger is attached to a computer that has just crashed. + +``` +kd> !analyze -v +******************************************************************************* +* * +* Bugcheck Analysis * +* * +******************************************************************************* + +DRIVER_IRQL_NOT_LESS_OR_EQUAL (d1) +An attempt was made to access a pagable (or completely invalid) address at an +interrupt request level (IRQL) that is too high. This is usually +caused by drivers using improper addresses. +If kernel debugger is available get stack backtrace. +``` + +The first element of the display shows the bug check code and information about this type of bug check. Some of the text displayed may not apply to this specific instance. For more details on each bug check, see the [Bug Check Code Reference](bug-check-code-reference2.md) section. + +``` +Arguments: +Arg1: 00000004, memory referenced +Arg2: 00000002, IRQL +Arg3: 00000001, value 0 = read operation, 1 = write operation +Arg4: f832035c, address which referenced memory +``` + +The bug check parameters are displayed next. They are each followed by a description. For example, the third parameter is 1, and the comment following it explains that this indicates that a write operation failed. + +``` +## Debugging Details: + + +WRITE_ADDRESS: 00000004 Nonpaged pool + +CURRENT_IRQL: 2 +``` + +The next few fields vary depending on the nature of the crash. In this case, we see WRITE\_ADDRESS and CURRENT\_IRQL fields. These are simply restating the information shown in the bug check parameters. By comparing the statement "Nonpaged pool" to the bug check text that reads "an attempt was made to access a pagable (or completely invalid) address," we can see that the address was invalid. The invalid address in this case was 0x00000004. + +``` +FAULTING_IP: +USBPORT!USBPORT_BadRequestFlush+7c +f832035c 894204 mov [edx+0x4],eax +``` + +The FAULTING\_IP field shows the instruction pointer at the time of the fault. + +``` +DEFAULT_BUCKET_ID: DRIVER_FAULT +``` + +The DEFAULT\_BUCKET\_ID field shows the general category of failures that this failure belongs to. + +``` +BUGCHECK_STR: 0xD1 +``` + +The BUGCHECK\_STR field shows the bug check code, which we have already seen. In some cases additional triage information is appended. + +``` +TRAP_FRAME: f8950dfc -- (.trap fffffffff8950dfc) +.trap fffffffff8950dfc +ErrCode = 00000002 +eax=81cc86dc ebx=81cc80e0 ecx=81e55688 edx=00000000 esi=81cc8028 edi=8052cf3c +eip=f832035c esp=f8950e70 ebp=f8950e90 iopl=0 nv up ei pl nz ac po nc +cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000 efl=00010216 +USBPORT!USBPORT_BadRequestFlush+7c: +f832035c 894204 mov [edx+0x4],eax ds:0023:00000004=???????? +.trap +Resetting default context +``` + +The TRAP\_FRAME field shows the trap frame for this crash. This information can also be viewed by using the [**.trap (Display Trap Frame)**](-trap--display-trap-frame-.md) command. + +``` +LAST_CONTROL_TRANSFER: from f83206e0 to f832035c +``` + +The LAST\_CONTROL\_TRANSFER field shows the last call on the stack. In this case, the code at address 0xF83206E0 called a function at 0xF832035C. You can use the [**ln (List Nearest Symbols)**](ln--list-nearest-symbols-.md) command to determine what module and function these addresses reside in. + +``` +STACK_TEXT: +f8950e90 f83206e0 024c7262 00000000 f8950edc USBPORT!USBPORT_BadRequestFlush+0x7c +f8950eb0 804f5561 81cc8644 81cc8028 6d9a2f30 USBPORT!USBPORT_DM_TimerDpc+0x10c +f8950fb4 804f5644 6e4be98e 00000000 ffdff000 nt!KiTimerListExpire+0xf3 +f8950fe0 8052c47c 8053cf20 00000000 00002e42 nt!KiTimerExpiration+0xb0 +f8950ff4 8052c16a efdefd44 00000000 00000000 nt!KiRetireDpcList+0x31 +``` + +The STACK\_TEXT field shows a stack trace of the faulting component. + +``` +FOLLOWUP_IP: +USBPORT!USBPORT_BadRequestFlush+7c +f832035c 894204 mov [edx+0x4],eax +``` + +The FOLLOWUP\_IP field shows the disassembly of the instruction that has probably caused the error. + +``` +FOLLOWUP_NAME: usbtri + +SYMBOL_NAME: USBPORT!USBPORT_BadRequestFlush+7c + +MODULE_NAME: USBPORT + +IMAGE_NAME: USBPORT.SYS + +DEBUG_FLR_IMAGE_TIMESTAMP: 3b7d868b +``` + +The SYMBOL\_NAME, MODULE\_NAME, IMAGE\_NAME, and DBG\_FLR\_IMAGE\_TIMESTAMP fields show the symbol, module, image, and image timestamp corresponding to this instruction (if it is valid), or to the caller of this instruction (if it is not). + +``` +STACK_COMMAND: .trap fffffffff8950dfc ; kb +``` + +The STACK\_COMMAND field shows the command that was used to obtain the STACK\_TEXT. You can use this command to repeat this stack trace display, or alter it to obtain related stack information. + +``` +BUCKET_ID: 0xD1_W_USBPORT!USBPORT_BadRequestFlush+7c +``` + +The BUCKET\_ID field shows the specific category of failures that the current failure belongs to. This category helps the debugger determine what other information to display in the analysis output. + +``` +INTERNAL_SOLUTION_TEXT: http://oca.microsoft.com/resredir.asp?sid=62&State=1 +``` + +If you are connected to the internet, the debugger attempts to access a database of crash solutions maintained by Microsoft. This database contains links to a tremendous number of Web pages that have information about known bugs. If a match is found for your problem, the INTERNAL\_SOLUTION\_TEXT field will show a URL that you can access for more information. + +``` +Followup: usbtri +--------- + + This problem has a known fix. + Please connect to the following URL for details: + ------------------------------------------------ + http://oca.microsoft.com/resredir.asp?sid=62&State=1 +``` + +For information about the FOLLOWUP\_NAME and the Followup fields, see The Followup Field and the triage.ini File: + +There are a variety of other fields that may appear: + +- If control was transferred to an invalid address, then the FAULTING\_IP field will contain this invalid address. Instead of the FOLLOWUP\_IP field, the FAILED\_INSTRUCTION\_ADDRESS field will show the disassembled code from this address, although this disassembly will probably be meaningless. In this situation, the SYMBOL\_NAME, MODULE\_NAME, IMAGE\_NAME, and DBG\_FLR\_IMAGE\_TIMESTAMP fields will refer to the caller of this instruction. + +- If the processor misfires, you may see the SINGLE\_BIT\_ERROR, TWO\_BIT\_ERROR, or POSSIBLE\_INVALID\_CONTROL\_TRANSFER fields. + +- If memory corruption seems to have occurred, the CHKIMG\_EXTENSION field will specify the [**!chkimg**](-chkimg.md) extension command that should be used to investigate. + +- If a bug check occurred within the code of a device driver, its name may be displayed in the BUGCHECKING\_DRIVER field. + +### The Followup Field and the triage.ini File + +In both user mode and kernel mode, the Followup field in the display will show information about the owner of the current stack frame, if this can be determined. This information is determined in the following manner: + +1. When the [**!analyze**](-analyze.md) extension is used, the debugger begins with the top frame in the stack and determines whether it is responsible for the error. If it isn't, the next frame is analyzed. This process continues until a frame that might be at fault is found. + +2. The debugger attempts to determine the owner of the module and function in this frame. If the owner can be determined, this frame is considered to be at fault. + +3. If the owner cannot be determined, the debugger passes to the next stack frame, and so on, until the owner is determined (or the stack is completely examined). The first frame whose owner is found in this search is considered to be at fault. If the stack is exhausted without any information being found, no Followup field is displayed. + +4. The owner of the frame at fault is displayed in the Followup field. If **!analyze -v** is used, the FOLLOWUP\_IP, SYMBOL\_NAME, MODULE\_NAME, IMAGE\_NAME, and DBG\_FLR\_IMAGE\_TIMESTAMP fields will refer to this frame. + +For the Followup field to display useful information, you must first create a Triage.ini file containing the names of the module and function owners. + +The Triage.ini file should identify the owners of all modules that could possibly have errors. You can use an informational string instead of an actual owner, but this string cannot contain spaces. If you are certain that a module will not fault, you can omit this module or indicate that it should be skipped. It is also possible to specify owners of individual functions, giving the triage process an even finer granularity. + +For details on the syntax of the Triage.ini file, see [Specifying Module and Function Owners](specifying-module-and-function-owners.md). + +### Additional !analyze Techniques + +If you do not believe that the BUCKET\_ID is correct, you can override the bucket choice by using [**!analyze**](-analyze.md) with the **-D** parameter. + +If no crash or exception has occurred, [**!analyze**](-analyze.md) will display a very short text giving the current status of the target. In certain situations you may want to force the analysis to take place as if a crash had occurred. Use **!analyze -f** to accomplish this task. + +In user mode, if an exception has occurred but you believe the underlying problem is a hung thread, set the current thread to the thread you are investigating, and then use **!analyze -hang**. This extension will perform a thread stack analysis to determine if any threads are blocking other threads. + +In kernel mode, if a bug check has occurred but you believe the underlying problem is a hung thread, use **!analyze -hang**. This extension will investigate locks held by the system and scan the DPC queue chain, and will display any indications of hung threads. If you believe the problem is a kernel-mode resource deadlock, use the [**!deadlock**](-deadlock.md) extension along with the **Deadlock Detection** option of Driver Verifier. + +You can also automatically ignore known issues. To do this, you must first create an XML file containing a formatted list of known issues. Use the **!analyze -c -load***KnownIssuesFile* extension to load this file. Then when an exception or break occurs, use the **!analyze -c** extension. If the exception matches one of the known issues, the target will resume execution. If the target does not resume executing, then you can use **!analyze -v** to determine the cause of the problem. A sample XML file can be found in the sdk\\samples\\analyze\_continue subdirectory of the debugger installation directory. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20!analyze%20Extension%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-dbgrpc-tool.md b/windows-driver-docs-pr/debugger/using-the-dbgrpc-tool.md new file mode 100644 index 0000000000..7a05ee22a9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-dbgrpc-tool.md @@ -0,0 +1,54 @@ +--- +title: Using the DbgRpc Tool +description: Using the DbgRpc Tool +ms.assetid: a98b9141-72e1-4957-a65c-36e677d159a6 +keywords: ["DbgRpc", "DbgRpc, basic use"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the DbgRpc Tool + + +## + + +The DbgRpc tool (Dbgrpc.exe) is located in the root directory of the Debugging Tools for Windows installation and must be started in a Command Prompt window. Double-clicking the icon will not start this tool. + +The Command Prompt window must be running under an account with administrative privileges on the local computer, or with domain administrative privileges. + +DbgRpc makes no calls to any system services (such as LSASS). This makes it useful for debugging even if a system service has crashed, as long as the kernel is still running. + +### Using DbgRpc on a Remote Computer + +DbgRpc can also be used to examine information from a remote machine. For this to work, the remote machine must be able to accept remote connections and authenticate remote users. If the remote machine's RPCSS (RPC Endpoint Mapper) service has crashed, DbgRpc will not be able to work. Administrative or domain administrative privileges on the remote machine are required. + +The **-s** command-line option is used to specify the server name, and the **-p** parameter is used to specify the transport protocol. Both TCP and named pipe protocols are available. TCP is the recommended protocol; it should work in almost every situation. + +Here is an example: + +``` +G:\>dbgrpc -s MyServer -p ncacn_ip_tcp -l -P 1e8 -L 0.1 +Getting remote cell info ... +Endpoint +Status: Active +Protocol Sequence: LRPC +Endpoint name: OLE18 +``` + +### DbgRpc Command Line + +For a description of the full command syntax, see [**DbgRpc Command-Line Options**](dbgrpc-command-line-options.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20DbgRpc%20Tool%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-debugger-and-logexts-dll.md b/windows-driver-docs-pr/debugger/using-the-debugger-and-logexts-dll.md new file mode 100644 index 0000000000..787898cbe2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-debugger-and-logexts-dll.md @@ -0,0 +1,70 @@ +--- +title: Using the Debugger and Logexts.dll +description: Using the Debugger and Logexts.dll +ms.assetid: 7f7d3ca2-9b40-41ce-b66c-4367b93a7ff7 +keywords: ["Logger, logexts.dll", "Logger, CDB", "Logger, WinDbg", "logexts.dll"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Debugger and Logexts.dll + + +## + + +One way to activate Logger is to start CDB or WinDbg and attach to a user-mode target application as usual. Then, use the [**!logexts.logi**](-logexts-logi.md) or [**!logexts.loge**](-logexts-loge.md) extension command. + +This will insert code at the current breakpoint that will jump off to a routine that loads and initializes Logexts.dll in the target application process. This is referred to as "injecting Logger into the target application." + +There will actually be two instances of Logexts.dll running, since this module is both a debugger extension DLL and the program that is injected into the target application. The debugger and target instances of Logexts.dll communicate through a shared section of memory that includes the output file handles, current category mask, and a pointer to the log output buffer. + +### Attaching to the Target Application + +For information about attaching the debugger to the target application, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md) or [Debugging a User-Mode Process Using CDB](debugging-a-user-mode-process-using-cdb.md). + +### Using the Logger Extension Commands + +For the full syntax of each extension, see its reference page. + +[**!logexts.logi**](-logexts-logi.md) +Injects Logger into the target application. This initializes logging, but does not enable it. + +[**!logexts.loge**](-logexts-loge.md) +Enables logging. If [**!logexts.logi**](-logexts-logi.md) has not been used, this extension will initialize and then enable logging. + +[**!logexts.logd**](-logexts-logd.md) +Disables logging. This will cause all API hooks to be removed in an effort to allow the program to run freely. COM hooks are not removed because they cannot be re-enabled at will. + +[**!logexts.logo**](-logexts-logo.md) +Displays or modifies output options. Three types of output are possible: messages sent directly to the debugger, a text file, or an .lgv file. The .lgv file contains much more information than the other two; it can be read with [LogViewer](logviewer.md). + +If you disable the text file output, a .txt file of size zero will still be created. This may overwrite a previously-saved text file in the same location. + +[**!logexts.logc**](-logexts-logc.md) +Displays available API categories, controls which categories will be logged and which will not, and displays the APIs that are contained in any category. + +If a category is disabled, the hooks for all APIs in that category will be removed so that there is no longer any performance overhead. COM hooks are not removed because they cannot be re-enabled at will. + +Enabling only certain categories can be useful when you are only interested in a particular type of interaction that the program is having with Windows -- for example, file operations. This reduces the log file size and also reduces the effect that Logger has on the execution speed of the process. + +[**!logexts.logb**](-logexts-logb.md) +Displays or flushes the current output buffer. As a performance consideration, log output is flushed to disk only when the output buffer is full. By default, the buffer is 2144 bytes. + +Since the buffer memory is managed by the target application, the automatic writing of the buffer to the log files on the disk will not occur if there is an access violation or some other non-recoverable error in the target application. In such cases, you should use this command to manually flush the buffer to the disk, or else the most recently-logged APIs may not appear in the log files. + +[**!logexts.logm**](-logexts-logm.md) +Displays or creates a module inclusion/exclusion list. It is often desirable to only log those API calls that are made from a certain module or set of modules. To facilitate that, Logger allows you to specify a module inclusion list or, alternatively, a module exclusion list. For instance, you would use an inclusion list if you only wanted to log calls from one or two modules. If you wanted to log calls made from all modules except a short list of modules, you would use an exclusion list. The modules Logexts.dll and Kernel32.dll are always excluded, since Logger is not permitted to log itself. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Debugger%20and%20Logexts.dll%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-debugger-engine-api.md b/windows-driver-docs-pr/debugger/using-the-debugger-engine-api.md new file mode 100644 index 0000000000..a286c0be76 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-debugger-engine-api.md @@ -0,0 +1,33 @@ +--- +title: Using the Debugger Engine API +description: Using the Debugger Engine API +ms.assetid: 64785cb6-819c-4a27-b2be-71cc489418ab +keywords: ["Debugger Engine, API", "Debugger Engine API"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Debugger Engine API + + +## + + +This section includes: + +[Debugger Engine API Overview](debugger-engine-api-overview.md) + +[Debugger Engine Reference](https://msdn.microsoft.com/library/windows/hardware/ff540540) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Debugger%20Engine%20API%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-declare-api-macro.md b/windows-driver-docs-pr/debugger/using-the-declare-api-macro.md new file mode 100644 index 0000000000..74349e9bed --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-declare-api-macro.md @@ -0,0 +1,56 @@ +--- +title: Using the DECLARE_API Macro +description: Using the DECLARE_API Macro +ms.assetid: 469f5ae4-2da8-4bbe-b5c0-75fcef227ba5 +keywords: ["WdbgExts extensions, DECLARE_API macro", "DECLARE_API macro (WdbgExts)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the DECLARE\_API Macro + + +## + + +Each extension command in a WdbgExts extension DLL is declared using the DECLARE\_API macro. This macro is defined in wdbgexts.h. + +The basic format of the code for an extension command is: + +``` +DECLARE_API( myextension ) +{ + code for myextension +} +``` + +The DECLARE\_API macro sets up a standard interface for extension commands. For example, if the user passed any arguments to the extension command, the entire argument string will be stored as a string, and a pointer to this string (PCSTR) will be passed to the extension function as **args**. + +If you are using 64-bit pointers, the DECLARE\_API macro is defined as follows: + +``` +#define DECLARE_API(s) \ + CPPMOD VOID \ + s( \ + HANDLE hCurrentProcess, \ + HANDLE hCurrentThread, \ + ULONG64 dwCurrentPc, \ + ULONG dwProcessor, \ + PCSTR args \ + ) +``` + +If you are using 32-bit pointers, DECLARE\_API remains the same, except that **dwCurrentPc** will be of the type ULONG instead of ULONG64. However, 64-bit pointers are recommended for any extension that you are writing. See [32-Bit Pointers and 64-Bit Pointers](32-bit-pointers-and-64-bit-pointers.md) for details. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20DECLARE_API%20Macro%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-help-documentation.md b/windows-driver-docs-pr/debugger/using-the-help-documentation.md new file mode 100644 index 0000000000..b385fb67f9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-help-documentation.md @@ -0,0 +1,93 @@ +--- +title: Using the Help Documentation +description: Using the Help Documentation +ms.assetid: ad826f45-3bad-4e10-811f-26ebf4f06c4d +keywords: ["HTML Help", "searching the Help file", "index of the Help file", "favorites in the Help file", "printing topics from the Help file", "hh.exe", "help file", "help file, overview", "help file, searching"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Help Documentation + + +## + + +The WinDbg Help documentation that you are reading is the documentation for the Debugging Tools for Windows package. + +This documentation uses the viewer that is supplied with Microsoft HTML Help (hh.exe). This viewer provides a table of contents and index and enables you to search through the documentation, mark your favorite or frequently used topics, and print one or more topics. + +The following sections in this topic describe the features of and how to use the Help documentation. + +### Contents Tab + +The **Contents** tab provides an expandable view of the documentation's table of contents. + +Click the plus sign (**+**) next to a node or double-click the node's title to expand or contract the table of contents under that node. + +### Index Tab + +The **Index** tab displays the complete index of terms that are used in this documentation. You can enter the beginning of a term or use the scrollbar to look through this index. + +### Search Tab + +In the **Search** tab, you can search for any word or phrase that is contained in the documentation. You can search all text or limit your search to topic titles. + +To search for phrases that contain more than one word, enclose the phrase in quotation marks. You can connect multiple words and phrases with the AND, OR, and NOT operators. The default operator is AND. + +Note that "AND NOT" is invalid. To search for topics that contain *x* and not *y*, use "*x* NOT *y*". You can also use NEAR in searches. + +Wildcard characters are also permitted. Use a question mark (**?**) to represent any single character and an asterisk (**\***) to represent zero or more characters. However, you cannot use wildcard characters within quoted strings. + +All letters and numbers are treated literally, but some symbols are not permitted in searches. + +A search returns a list of all topics that match the specified criteria. If you select the **Search previous results** box, you can then search these results for more terms. + +### Favorites Tab + +In the **Favorites** tab, you can save the titles of commonly-visited topics. While you are viewing a topic, click the **Favorites** tab and then click the **Add** button. + +To rename a page on your favorites list, click its name two times slowly, and retype the name. To view a topic on the Favorites list, double-click its name or click it one time and then click **Display**. To remove a topic from the favorites list, click it one time and then click **Remove**. + +### Printing Topics + +To print one or more topics, click a topic in the **Contents** tab, and then click the **Print** button on the toolbar. You will be asked whether you want to print only the selected topic or that topic and all of its subtopics. + +You can also print the topic that you are viewing by right-clicking within the view window, and clicking **Print** on the shortcut menu. However, this method does not enable you to print subtopics. + +### Searching Within a Topic + +To search for a text string within the topic that you are viewing, press CTRL+F, or click **Find in this Topic** on the **Edit** menu. + +### Accessing the Help Documentation + +To open this Help documentation, do one of the following: + +- Click **Start**, point to **All Programs**, point to **Debugging Tools for Windows**, and then click **Debugging Help**. + +- Open Windows Explorer, locate the Debugger.chm file, and then double-click it. + +- At a command prompt, browse to the folder that contains Debugger.chm and run **hh debugger.chm**. + +- In any Windows debugger, use the [**.hh (Open HTML Help File)**](-hh--open-html-help-file-.md) command. + +- In WinDbg, click **Contents** on the **Help** menu. This command open the Help documentation and opens the **Contents** tab. + +- In WinDbg, click **Index** on the **Help** menu. This command open the Help documentation and opens the **Index** tab. + +- In WinDbg, click **Search** on the **Help** menu. This command opens the Help documentation and opens the **Search** tab. + +- Many dialog boxes in WinDbg have **Help** buttons. Click **Help** to open this documentation and open the relevant page. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Help%20Documentation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md b/windows-driver-docs-pr/debugger/using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md new file mode 100644 index 0000000000..3883810c78 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-kernel-debugger-to-find-a-kernel-mode-memory-leak.md @@ -0,0 +1,88 @@ +--- +title: Using the Kernel Debugger to Find a Kernel-Mode Memory Leak +description: Using the Kernel Debugger to Find a Kernel-Mode Memory Leak +ms.assetid: eeadd505-b887-498d-9369-877156526355 +keywords: ["memory leak, kernel-mode, kernel debugger"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Kernel Debugger to Find a Kernel-Mode Memory Leak + + +The kernel debugger determines the precise location of a kernel-mode memory leak. + +### Enable Pool Tagging (Windows 2000 and Windows XP) + +On Windows 2000 and Windows XP, you must first use [GFlags](gflags.md) to enable pool tagging. GFlags is included in Debugging Tools for Windows. Start GFlags, choose the **System Registry** tab, check the **Enable Pool Tagging** box, and then click **Apply**. You must restart Windows for this setting to take effect. + +On Windows Server 2003 and later versions of Windows, pool tagging is always enabled. + +### Determining the Pool Tag of the Leak + +To determine which pool tag is associated with the leak, it is usually easiest to use the PoolMon tool for this step. For details, see [Using PoolMon to Find Kernel-Mode Memory Leaks](using-poolmon-to-find-a-kernel-mode-memory-leak.md). + +Alternatively, you can use the kernel debugger to look for tags associated with large pool allocations. To do so, follow this procedure: + +1. Reload all modules by using the [**.reload (Reload Module)**](-reload--reload-module-.md) command. + +2. Use the [**!poolused**](-poolused.md) extension. Include the flag "4" to sort the output by paged memory use: + ``` + kd> !poolused 4 + Sorting by Paged Pool Consumed + + Pool Used: + NonPaged Paged + Tag Allocs Used Allocs Used + Abc 0 0 36405 33930272 + Tron 0 0 552 7863232 + IoN7 0 0 10939 998432 + Gla5 1 128 2222 924352 + Ggb 0 0 22 828384 + ``` + +3. Determine which pool tag is associated with the greatest usage of memory. In this example, the driver using the tag "Abc" is using the most memory--almost 34 MB. Therefore, the memory leak is most likely to be in this driver. + +### Finding the Leak + +After you have determined the pool tag associated with the leak, follow this procedure to locate the leak itself: + +1. Use the [**ed (Enter Values)**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) command to modify the value of the global system variable **PoolHitTag**. This global variable causes the debugger to break whenever a pool tag matching its value is used. + +2. Set **PoolHitTag** equal to the tag that you suspect to be the source of the memory leak. The module name "nt" should be specified for faster symbol resolution. The tag value must be entered in little-endian format (that is, backward). Because pool tags are always four characters, this tag is actually A-b-c-space, not merely A-b-c. So use the following command: + ``` + kd> ed nt!poolhittag ' cbA' + ``` + +3. To verify the current value of **PoolHitTag**, use the [**db (Display Memory)**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) command: + ``` + kd> db nt!poolhittag L4 + 820f2ba4 41 62 63 20 Abc + ``` + +4. The debugger will break every time that pool is allocated or freed with the tag **Abc**. Each time the debugger breaks on one of these allocations or free operations, use the [**kb (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) debugger command to view the stack trace. + +Using this procedure, you can determine which code resident in memory is overallocating pool with the tag **Abc**. + +To clear the breakpoint, set **PoolHitTag** to zero: + +``` +kd> ed nt!poolhittag 0 +``` + +If there are several different places where memory with this tag is being allocated and these are in an application or driver that you have written, you can alter your source code to use unique tags for each of these allocations. + +If you cannot recompile the program but you want to determine which one of several possible locations in the code is causing the leak, you can unassemble the code at each location and use the debugger to edit this code resident in memory so that each instance uses a distinct (and previously unused) pool tag. Then allow the system to run for several minutes or more. After some time has passed, break in again with the debugger and use the [**!poolfind**](-poolfind.md) extension to find all pool allocations associated with each of the new tags. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Kernel%20Debugger%20to%20Find%20a%20Kernel-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-rpc-debugger-extensions.md b/windows-driver-docs-pr/debugger/using-the-rpc-debugger-extensions.md new file mode 100644 index 0000000000..d1afa5a528 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-rpc-debugger-extensions.md @@ -0,0 +1,37 @@ +--- +title: Using the RPC Debugger Extensions +description: Using the RPC Debugger Extensions +ms.assetid: 55303052-c5b3-4fe7-96ce-6f41a45a2358 +keywords: ["RPC extensions (rpcexts.dll)", "RPC debugging, extensions (rpcexts.dll)", "rpcexts.dll (RPC extensions)"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the RPC Debugger Extensions + + +## + + +A variety of RPC debugger extensions are exported from Rpcexts.dll. + +The RPC extensions used to display RPC state information will only run in user mode. They can be used from CDB (or NTSD) or from user-mode WinDbg. + +The user-mode debugger must have a target application, but the target is irrelevant to the RPC extensions. If the debugger is not already running, you can simply start it with an uninteresting target (for example, **windbg notepad** or **cdb winmine**). Then, use [**CTRL+C**](ctrl-c--break-.md) in CDB or [Debug | Break](debug---break.md) in WinDbg to stop the target and access the Debugger Command window. + +If you need to analyze RPC state information from a remote computer, you should start the user-mode debugger on the computer that needs to be analyzed, and then use [Remote Debugging](remote-debugging.md). + +Accessing RPC state information through the debugger is especially useful in stress environments, or when a debugger already happens to be running. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20RPC%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-the-toolbar-and-status-bar.md b/windows-driver-docs-pr/debugger/using-the-toolbar-and-status-bar.md new file mode 100644 index 0000000000..4a29502e66 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-the-toolbar-and-status-bar.md @@ -0,0 +1,110 @@ +--- +title: Using the Toolbar and Status Bar +description: Using the Toolbar and Status Bar +ms.assetid: 96427166-b6df-4f6b-b550-69d0eb33042d +keywords: ["toolbar (WinDbg)", "toolbar (WinDbg), overview", "buttons (WinDbg Toolbar)", "buttons (WinDbg Toolbar), overview", "status bar", "status bar, overview", "WinDbg, toolbar", "WinDbg, status bar", "WinDbg, buttons"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Toolbar and Status Bar + + +## + + +The *toolbar* appears underneath the menu bar, near the top of the WinDbg window. The *status bar* appears at the bottom of the WinDbg window. + +### Using the Toolbar + +The following screen shot shows the WinDbg toolbar. + +![screen shot of the windbg toolbar](images/toolbar4.png) + +The toolbar buttons have various effects. Most of them are equivalent to menu commands. To execute the command that is associated with a toolbar button, click the toolbar button. When you cannot use a button, it appears unavailable. + +For more information about each button, see [Toolbar Buttons](toolbar-buttons.md). + +### Using the Status Bar + +The following screen shot shows the WinDbg status bar. + +![screen shot of the windbg status bar](images/statusbar3.png) + +The following table describes the sections of the WinDbg status bar. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SectionDescription

Message

Displays messages from the debugger.

Ln, Col

Displays the line number and column number at the cursor in the active [Source window](source-window.md).

Sys

Shows the internal decimal number of the system that you are debugging, followed by its computer name (or <Local> if it is the same as the computer as the debugger is running on).

Proc

Shows the internal decimal number of the process that you are debugging, followed by its hexadecimal process ID.

Thrd

Shows the internal decimal number of the thread that you are debugging, followed by its hexadecimal thread ID.

ASM

Indicates that WinDbg is in assembly mode. If ASM is unavailable, WinDbg is in source mode.

OVR

Indicates that overtype mode is active. If OVR is unavailable, insert mode is active.

CAPS

Indicates that CAPS LOCK is on.

NUM

Indicates that NUM LOCK is on.

+ +  + +### Hiding the Toolbar or Status Bar + +To display or hide the toolbar, select or clear [Toolbar](view---toolbar.md) on the **View** menu. To display or hide the status bar, select or clear [Status Bar](view---status-bar.md) on the **View** menu. + +If you hide the toolbar or the status bar, you have more space for debugging information windows in the WinDbg display area. + +### Setting the Window Title + +You can change the title of the WinDbg window by using the [**.wtitle (Set Window Title)**](-wtitle--set-window-title-.md) command. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Toolbar%20and%20Status%20Bar%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-themes-provided-in-debugging-tools-for-windows.md b/windows-driver-docs-pr/debugger/using-themes-provided-in-debugging-tools-for-windows.md new file mode 100644 index 0000000000..2cf88e8b63 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-themes-provided-in-debugging-tools-for-windows.md @@ -0,0 +1,61 @@ +--- +title: Using Themes Provided in Debugging Tools for Windows +description: Using Themes Provided in Debugging Tools for Windows +ms.assetid: d3571a7a-cdab-4a17-b4e0-ffb1690de642 +keywords: ["themes, provided"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Themes Provided in Debugging Tools for Windows + + +## + + +This topic shows screen shots of the configurations from each of the four themes provided in Debugging Tools for Windows. Those themes are Standard.reg, Standardvs.reg, Srcdisassembly.reg, and Multimon.reg. + +### Standard.reg + +The Standard.reg theme can be used for most debugging purposes. In this arrangement, the lower third of the WinDbg window is taken by the Debugger Command window. The upper two-thirds is divided roughly in half. The left half is taken up by a placeholder window that indicates where the Source windows open in a tabbed collection. The right half is further divided into halves vertically. The upper half contains a tabbed collection that includes the Watch, Locals, Registers, and Disassembly windows. The lower half contains a tabbed collection that includes the Calls and Processes and Threads windows. + +In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing them may change the configuration of the windows. All of the windows in this arrangement are docked.The following screen shot shows the Standard.reg theme. + +![screen shot of the standard.reg theme](images/theme-standard.jpg) + +### Standardvs.reg + +The Standardvs.reg theme can be used for most debugging purposes, but is more similar in layout to Visual Studio. In this arrangement, the WinDbg window is divided horizontally into thirds. The upper third is further divided vertically into halves. The left half of the upper third contains a tabbed collection that includes the Watch, Locals, Registers, Memory, Disassembly, and Scratchpad windows. The right half of the upper third contains a tabbed collection that includes the Calls and Processes and Threads windows. The lower third of the WinDbg window is taken by the Debugger Command window. The middle third is filled by a placeholder window that indicates where the Source windows are opened in a tabbed collection. + +In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing them may change the configuration of the windows. All of the windows in this arrangement are docked. The following screen shot shows the Standardvs.reg theme. + +![screen shot of the standardvs.reg theme](images/theme-standardvs.jpg) + +### Srcdisassembly.reg + +The Srcdisassembly.reg theme includes a Disassembly window, for debugging in assembly mode. In this arrangement, the WinDbg window is divided in half vertically, and each half formed is further divided into thirds horizontally. On the right half, the upper third is a tabbed collection of the Locals and Watch windows, the middle third is the Debugger Command window, and the lower third is a tabbed collection of the Processes and Threads and Calls windows. On the left half, the upper two-thirds are taken by a placeholder window that indicates where the Source windows opens in a tabbed collection; the lower third is taken up by the Disassembly window. + +In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing them may change the configuration of the windows. All of the windows in this arrangement are docked. The following screen shot shows the Srcdisassembly.reg theme. + +![screen shot of the srcdisassembly.reg theme](images/theme-srcdisassembly.jpg) + +### Multimon.reg + +The Multimon.reg theme is set up for debugging with multiple monitors. In this arrangement, a new dock is created so that the WinDbg window can be viewed on one monitor and the new dock can be viewed on the other monitor. The WinDbg window is filled by a placeholder window that indicates where the Source windows open in a tabbed collection. The new dock is divided into fourths. The upper left contains a tabbed collection that includes the Watch and Locals windows. The upper right contains a tabbed collection that includes the Registers, Memory, Disassembly, Scratchpad, and Processes and Threads windows. The lower left contains the Debugger Command window. The lower right contains the Calls window. + +In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing them may change the configuration of the windows. All of the windows in this arrangement are docked. The following screen shot shows the Multimon.reg theme. + +![screen shot of the multimon.reg theme](images/theme-multimon.jpg) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Themes%20Provided%20in%20Debugging%20Tools%20for%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-umdh-to-find-a-user-mode-memory-leak.md b/windows-driver-docs-pr/debugger/using-umdh-to-find-a-user-mode-memory-leak.md new file mode 100644 index 0000000000..531e01e99e --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-umdh-to-find-a-user-mode-memory-leak.md @@ -0,0 +1,119 @@ +--- +title: Using UMDH to Find a User-Mode Memory Leak +description: Using UMDH to Find a User-Mode Memory Leak +ms.assetid: b15ed695-3f35-4a72-93ab-3cbfd2e33980 +keywords: ["memory leak, user-mode, UMDH", "UMDH, memory leak detection"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using UMDH to Find a User-Mode Memory Leak + + +The user-mode dump heap (UMDH) utility works with the operating system to analyze Windows heap allocations for a specific process. UMDH locates which routine in a specific process is leaking memory. + +UMDH is included in Debugging Tools for Windows. For full details, see [UMDH](umdh.md). + +### Preparing to Use UMDH + +If you have not already determined which process is leaking memory, do that first. For details, see [Using Performance Monitor to Find User-Mode Memory Leaks](using-performance-monitor-to-find-a-user-mode-memory-leak.md). + +The most important data in the UMDH logs are the stack traces of the heap allocations. To determine whether a process is leaking heap memory, analyze these stack traces. + +Before using UMDH to display the stack trace data, you must use [GFlags](gflags.md) to configure your system properly. GFlags is included in Debugging Tools for Windows. + +The following GFlags settings enable UMDH stack traces: + +- In the GFlags graphical interface, choose the Image File tab, type the process name (including the file name extension), press the TAB key, select **Create user mode stack trace database**, and then click **Apply**. + + Or, equivalently, use the following GFlags command line, where *ImageName* is the process name (including the file name extension): + + ``` + gflags /i ImageName +ust + ``` + +- By default, the amount of stack trace data that Windows gathers is limited to 32 MB on an x86 processor, and 64 MB on an x64 processor. If you must increase the size of this database, choose the **Image File** tab in the GFlags graphical interface, type the process name, press the TAB key, check the **Stack Backtrace (Megs)** check box, type a value (in MB) in the associated text box, and then click **Apply**. Increase this database only when necessary, because it may deplete limited Windows resources. When you no longer need the larger size, return this setting to its original value. + +- If you changed any flags on the **System Registry** tab, you must restart Windows to make these changes effective. If you changed any flags on the **Image File** tab, you must restart the process to make the changes effective. Changes to the **Kernel Flags** tab are effective immediately, but they are lost the next time Windows restarts. + +Before using UMDH, you must have access to the proper symbols for your application. UMDH uses the symbol path specified by the environment variable \_NT\_SYMBOL\_PATH. Set this variable equal to a path containing the symbols for your application. If you also include a path to Windows symbols, the analysis may be more complete. The syntax for this symbol path is the same as that used by the debugger; for details, see [Symbol Path](symbol-path.md). + +For example, if the symbols for your application are located at C:\\MySymbols, and you want to use the public Microsoft symbol store for your Windows symbols, using C:\\MyCache as your downstream store, you would use the following command to set your symbol path: + +``` +set _NT_SYMBOL_PATH=c:\mysymbols;srv*c:\mycache*https://msdl.microsoft.com/download/symbols +``` + +In addition, to assure accurate results, you must disable BSTR caching. To do this, set the OANOCACHE environment variable equal to one (1). Make this setting before you launch the application whose allocations are to be traced. + +If you need to trace the allocations made by a service, you must set OANOCACHE as a system environment variable and then restart Windows for this setting to take effect. + +On Windows 2000, in addition to setting OANOCACHE equal to 1, you must also install the hotfix available with [Microsoft Support Article 139071](http://go.microsoft.com/fwlink/p/?LinkId=241583). This hotfix is not needed on Windows XP and later versions of Windows. + +### Detecting Increases in Heap Allocations with UMDH + +After making these preparations, you can use UMDH to capture information about the heap allocations of a process. To do so, follow this procedure: + +1. Determine the [process ID (PID)](finding-the-process-id.md) for the process you want to investigate. + +2. Use UMDH to analyze the heap memory allocations for this process, and save it to a log file. Use the -p switch with the PID, and the -f switch with the name of the log file. For example, if the PID is 124, and you want to name the log file Log1.txt, use the following command: + + ``` + umdh -p:124 -f:log1.txt + ``` + +3. Use Notepad or another program to open the log file. This file contains the call stack for each heap allocation, the number of allocations made through that call stack, and the number of bytes consumed through that call stack. + +4. Because you are looking for a memory leak, the contents of a single log file are not sufficient. You must compare log files recorded at different times to determine which allocations are growing. + + UMDH can compare two different log files and display the change in their respective allocation sizes. You can use the greater-than symbol (**>**) to redirect the results into a third text file. You may also want to include the -d option, which converts the byte and allocation counts from hexadecimal to decimal. For example, to compare Log1.txt and Log2.txt, saving the results of the comparison to the file LogCompare.txt, use the following command: + + ``` + umdh log1.txt log2.txt > logcompare.txt + ``` + +5. Open the LogCompare.txt file. Its contents resemble the following: + + ``` + + 5320 ( f110 - 9df0) 3a allocs BackTrace00B53 + Total increase == 5320 + ``` + + For each call stack (labeled "BackTrace") in the UMDH log files, there is a comparison made between the two log files. In this example, the first log file (Log1.txt) recorded 0x9DF0 bytes allocated for BackTrace00B53, while the second log file recorded 0xF110 bytes, which means that there were 0x5320 additional bytes allocated between the time the two logs were captured. The bytes came from the call stack identified by BackTrace00B53. + +6. To determine what is in that backtrace, open one of the original log files (for example, Log2.txt) and search for "BackTrace00B53." The results are similar to this data: + + ``` + 00005320 bytes in 0x14 allocations (@ 0x00000428) by: BackTrace00B53 + ntdll!RtlDebugAllocateHeap+0x000000FD + ntdll!RtlAllocateHeapSlowly+0x0000005A + ntdll!RtlAllocateHeap+0x00000808 + MyApp!_heap_alloc_base+0x00000069 + MyApp!_heap_alloc_dbg+0x000001A2 + MyApp!_nh_malloc_dbg+0x00000023 + MyApp!_nh_malloc+0x00000016 + MyApp!operator new+0x0000000E + MyApp!DisplayMyGraphics+0x0000001E + MyApp!main+0x0000002C + MyApp!mainCRTStartup+0x000000FC + KERNEL32!BaseProcessStart+0x0000003D + ``` + + This UMDH output shows that there were 0x5320 (decimal 21280) total bytes allocated from the call stack. These bytes were allocated from 0x14 (decimal 20) separate allocations of 0x428 (decimal 1064) bytes each. + + The call stack is given an identifier of "BackTrace00B53," and the calls in this stack are displayed. In reviewing the call stack, you see that the **DisplayMyGraphics** routine is allocating memory through the **new** operator, which calls the routine *malloc*, which uses the Visual C++ run-time library to obtain memory from the heap. + + Determine which of these calls is the last one to explicitly appear in your source code. In this case, it is probably the **new** operator because the call to *malloc* occurred as part of the implementation of **new** rather than as a separate allocation. So this instance of the **new** operator in the **DisplayMyGraphics** routine is repeatedly allocating memory that is not being freed. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20UMDH%20to%20Find%20a%20User-Mode%20Memory%20Leak%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-unc-shares.md b/windows-driver-docs-pr/debugger/using-unc-shares.md new file mode 100644 index 0000000000..f13df47ada --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-unc-shares.md @@ -0,0 +1,38 @@ +--- +title: Using UNC Shares +description: Using UNC Shares +ms.assetid: 7baf157d-e8c3-4ad5-a56e-58f8983da4d9 +--- + +# Using UNC Shares + + +The Cv2http.cmd, Cv2http.pl, and Walk (Walk.cmd) scripts are used to provide source files from a simple UNC share. The files Cv2http.cmd and Cv2http.pl extract the SrcSrv stream, modify it using a Perl script, and put the altered stream back in the .pdb file. The syntax is as follows: + +``` +cv2http.cmd PDB Alias SourceRoot +``` + +where *PDB* specifies the name of the .pdbfile to modify, *Alias* specifies the logical name to apply to your Web site, and *SourceRoot* specifies the root of the UNC share to which you extracted the source files. Note that the *Alias* parameter is stored in the PDB as a varaible name that can be overridden on the debugger client in Scrsrv.ini, should you ever move the location of the Web site. + +This script requires that all the standard SrcSrv tools be available in the path because it calls both SrcTool and PDBStr. Remember that Cv2http.pl is a Perl script and can be modified to meet your needs. + +The third file, the Walk (walk.cmd) script, modifies an entire set of .pdb files. For example: + +``` +walk.cmd *.pdb cv2http.cmd SourceRoot \\server\share +``` + +The preceding command calls Cv2http.cmd on every .pdb file in a tree, using SourceRoot for the alias and \\\\server\\share for the UNC share. For more details on Walk, see [Extracting Source Files](extracting-source-files.md). + +After this command is executed on a tree of .pdb files, they are ready for installation into the Web site or whatever location in which you want to put them. Remember that you can use SrcTool and PDBStr to examine the changes to the .pdb files. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20UNC%20Shares%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-visual-sourcesafe.md b/windows-driver-docs-pr/debugger/using-visual-sourcesafe.md new file mode 100644 index 0000000000..906c4a7883 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-visual-sourcesafe.md @@ -0,0 +1,103 @@ +--- +title: Using Visual SourceSafe +description: Using Visual SourceSafe +ms.assetid: a315a1c5-1427-4432-aec0-314dbb6d7ae5 +keywords: ["Visual SourceSafe", "source servers, Visual SourceSafe", "SrcSrv, Visual SourceSafe", "Visual SourceSafe, SrcSrv", "Visual SourceSafe, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Visual SourceSafe + + +Visual SourceSafe is an x86-based application, and the source indexing scripts and tools associated with it are installed only with the x86 package of Debugging Tools for Windows. + +To successfully use Visual SourceSafe with SrcSrv, several defaults must be set in the system, including the Visual SourceSafe default database, the current project, and the working folder. You must also stamp each build project with a label so that Visual SourceSafe can differentiate between versions of a given file. Finally, you must set up any credentials needed to access the Visual SourceSafe database. + +### Visual SourceSafe Database + +The default Visual SourceSafe database can be set with the SSDIR environment variable. If it is not set there, the SrcSrv indexing script can usually determine this from the registry. If it cannot, the script prompts you to set SSDIR. Regardless, this database value must be listed in your [Srcsrv.ini](the-srcsrv-ini-file.md) file along with a simple alias to identify the database. More instructions can be found in the comments in Srcsrv.ini. You should add the entry in the variables section of Srcsrv.ini using the following syntax: + +``` +MYDATABASE=\\server\VssShare +``` + +### Current Project + +Visual SourceSafe uses the concept of a *current project*. The SrcSrv indexing script respects this value and limits processing to those source files that are part of the current project. To display the current project, use the following command: + +``` +ss.exe project +``` + +To change the current project, use the following command: + +``` +ss.exe cp Project +``` + +where *Project* indicates the current project. For example, to process all projects, set the current project to the root: + +``` +ss.exe cp $/ +``` + +### Working Folder + +Visual SourceSafe projects are associated with *working folders*. A working folder is the location on the client computer that corresponds to the root of a project. However it is possible for such a computer to obtain and build source without a working folder being specified, usually when creating projects through the Visual Studio interface or by using the command: + +``` +ss.exe get -R +``` + +However, this mode of operation is incompatible with SrcSrv indexing. SrcSrv requires that a working folder be specified. To set the working folder, use the command: + +``` +ss.exe workfold Project Folder +``` + +where *Project* indicates the current project and *Folder* indicates the location corresponding to the root of the project. + +### Labels + +Visual SourceSafe cannot determine what version of a file exists within the working directory of a build machine. Consequently, you must use labels to stamp the project with an identifier that is used to extract source files on the debugger client. Thus, before indexing, you must verify that all changes are checked into the database and then apply a label to the project. Labels can be applied using the command: + +``` +ss.exe label Project +``` + +where *Project* indicates the current project. + +In the following example, the label "VERSION\_3" is applied to a project called "$/sdktools": + +``` +E:\nt\user>ss.exe label $/sdktools + Label for $/sdktools: VERSION_3 + Comment for $/sdktools: + This is a comment. +``` + +After the label is applied, you can specify this label to the SrcSrv indexing script by setting the environment variable, SSLABEL, or by passing it as a command-line parameter, as in the following example: + +``` +vssindex.cmd -label=VERSION_3 +``` + +Again, this label is required for SrcSrv indexing to work. Note that if you pass a label that does not exist in the project, it can take a long time for the script to complete and the results are of no use. + +### Credentials + +If your Visual SourceSafe database requires a user and optional password for access, these values must be set through the SSUSER and SSPWD environment variables. This applies not only at the time the build is indexed, but also on the debugger client. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Visual%20SourceSafe%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-wdbgexts-extension-callbacks.md b/windows-driver-docs-pr/debugger/using-wdbgexts-extension-callbacks.md new file mode 100644 index 0000000000..5530bacc83 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-wdbgexts-extension-callbacks.md @@ -0,0 +1,56 @@ +--- +title: Using WdbgExts Extension Callbacks +description: Using WdbgExts Extension Callbacks +ms.assetid: b9a2f30a-b09c-43eb-b105-a6b0ffdb1342 +keywords: ["WdbgExts extensions, callbacks, using"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using WdbgExts Extension Callbacks + + +## + + +When you write a WdbgExts extension DLL, you can export certain functions: + +- You must export a function named [*WinDbgExtensionDllInit*](https://msdn.microsoft.com/library/windows/hardware/ff561303). When the debugger loads your extension DLL, it first calls *WinDbgExtensionDllInit* and passes it three arguments. + + - A pointer to a **WINDBG\_EXTENSION\_APIS64** structure, which contains pointers to functions that are implemented by the debugger and declared in Wdbgexts.h. You must copy the entire structure to a global variable that you create in your DLL. + - A major version number. You must copy the major version number to a global variable that you create in your DLL. + - A minor version number. You must copy the minor version number to a global variable that you create in your DLL. + + For example, you could create global variables named ExtensionApis, SavedMajorVersion, and SavedMinorVersion as shown in the following example. + + ```ManagedCPlusPlus + WINDBG_EXTENSION_APIS64 ExtensionApis; + USHORT SavedMajorVersion; + USHORT SavedMinorVersion; + + VOID WinDbgExtensionDllInit(PWINDBG_EXTENSION_APIS64 lpExtensionApis, + USHORT MajorVersion, USHORT MinorVersion) + { + ExtensionApis = *lpExtensionApis; + SavedMajorVersion = MajorVersion; + SavedMinorVersion = MinorVersion; + ... + } + ``` + +- You must export a function called [*ExtensionApiVersion*](https://msdn.microsoft.com/library/windows/hardware/ff543968). The debugger calls this function and expects back a pointer to an **EXT\_API\_VERSION** structure that contains the version number of the extension DLL. The debugger uses this version number when executing commands like [**.chain**](-chain--list-debugger-extensions-.md) and [**version**](version--show-debugger-version-.md) that display the extension version number. + +- You can optionally export a function called [*CheckVersion*](https://msdn.microsoft.com/library/windows/hardware/ff539096). The debugger calls this routine every time you use an extension command. You can use this to print out version mismatch warnings when your DLL is of a slightly different version than the debugger, but not different enough to prevent it from running. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20WdbgExts%20Extension%20Callbacks%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/using-workspaces.md b/windows-driver-docs-pr/debugger/using-workspaces.md new file mode 100644 index 0000000000..55beb1f491 --- /dev/null +++ b/windows-driver-docs-pr/debugger/using-workspaces.md @@ -0,0 +1,37 @@ +--- +title: Using Workspaces +description: Using Workspaces +ms.assetid: 2d729db2-a7c9-4905-a913-85d9b2a94e95 +keywords: ["workspaces", "workspaces, overview", "WinDbg, workspaces"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Workspaces + + +## + + +When you exit WinDbg, it saves your session configuration in a *workspace*. A workspace enables you to easily preserve your settings from one session to another. You can also save or clear the workspaces manually, or even use a workspace to save a debugging session that is still in progress. + +This section includes the following topics: + +[Creating and Opening a Workspace](creating-and-opening-a-workspace.md) + +[Workspace Contents](workspace-contents.md) + +[Using and Customizing WinDbg Themes](using-and-customizing-windbg-themes.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20Workspaces%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/ux--unassemble-x86-bios-.md b/windows-driver-docs-pr/debugger/ux--unassemble-x86-bios-.md new file mode 100644 index 0000000000..26e4fc09ac --- /dev/null +++ b/windows-driver-docs-pr/debugger/ux--unassemble-x86-bios-.md @@ -0,0 +1,78 @@ +--- +title: ux (Unassemble x86 BIOS) +description: The ux command displays the instruction set of the x86-based BIOS code. +ms.assetid: d3616255-1a07-4a5d-8171-c8316179a7dc +keywords: ["ux (Unassemble x86 BIOS) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- ux (Unassemble x86 BIOS) +api_type: +- NA +--- + +# ux (Unassemble x86 BIOS) + + +The **ux** command displays the instruction set of the x86-based BIOS code. + +``` +ux [Address] +``` + +## Parameters + + + *Address* +Specifies the memory offset within the x86-based BIOS code. If you omit this parameter or specify zero, the default offset is the beginning of the BIOS. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

x86-based only

+ +  + +### Additional Information + +For more information about how to debug BIOS code, see [Debugging BIOS Code](debugging-bios-code.md). + +Remarks +------- + +The debugger displays the instructions that are generated from the first eight lines of code, beginning at the *Address* offset. + +To make the **ux** command work correctly, HAL symbols must be available to the debugger. If the debugger cannot find these symbols, the debugger displays a "couldn't resolve" error. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20ux%20%28Unassemble%20x86%20BIOS%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/v.md b/windows-driver-docs-pr/debugger/v.md new file mode 100644 index 0000000000..ca7c6fbfae --- /dev/null +++ b/windows-driver-docs-pr/debugger/v.md @@ -0,0 +1,25 @@ +--- +title: V (Windows Debugger Glossary) +description: Glossary page - V +Robots: noindex, nofollow +ms.assetid: bbafe8f0-f77e-4fb4-ad28-7e57f866869a +--- + +# V + + +**virtual process** +In kernel-mode debugging the debugger engine creates a single *virtual process* to represent the target's kernel. + +**virtual thread** +In kernel-mode debugging the debugger engine creates a *virtual thread* for each processor in the target computer. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20V%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/varieties-of-kernel-mode-dump-files.md b/windows-driver-docs-pr/debugger/varieties-of-kernel-mode-dump-files.md new file mode 100644 index 0000000000..4f60b35671 --- /dev/null +++ b/windows-driver-docs-pr/debugger/varieties-of-kernel-mode-dump-files.md @@ -0,0 +1,61 @@ +--- +title: Varieties of Kernel-Mode Dump Files +description: Varieties of Kernel-Mode Dump Files +ms.assetid: 6db2a755-ed9c-492a-a650-9ae34ae59968 +keywords: ["dump file, kernel-mode file types"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Varieties of Kernel-Mode Dump Files + + +## + + +There are five settings for kernel-mode crash dump files: + +[Complete Memory Dump](complete-memory-dump.md) + +[Kernel Memory Dump](kernel-memory-dump.md) + +[Small Memory Dump](small-memory-dump.md) + +[Automatic Memory Dump](automatic-memory-dump.md) + +[Active Memory Dump](active-memory-dump.md) + +The difference between these dump files is one of size. The *Complete Memory Dump* is the largest and contains the most information, including some User-Mode memory. The *Active Memory Dump* is somewhat smaller but contains similar information for most purposes. The *Kernel Memory Dump* is smaller still and typically omits User-Mode memory, and the *Small Memory Dump* is only 64 KB in size. + +If you select *Automatic Memory Dump*, the dump file is the same as a Kernel Memory Dump, but Windows has more flexibility in setting the size of the system paging file. + +The advantage to the larger files is that, since they contain more information, they are more likely to help you find the cause of the crash. + +The advantage of the smaller files is that they are smaller and written more quickly. Speed is often valuable; if you are running a server, you may want the server to reboot as quickly as possible after a crash, and the reboot will not take place until the dump file has been written. + +After a Complete Memory Dump or Kernel Memory Dump has been created, it is possible to create a Small Memory Dump file from the larger dump file. See the [**.dump (Create Dump File)**](-dump--create-dump-file-.md) command for details. + +**Note**   Much information can be obtained by analyzing a kernel-mode dump file. However, no kernel-mode dump file can provide as much information as actually debugging the crash directly with a kernel debugger. + +  + +## Related topics + + +[Kernel-Mode Dump Files](kernel-mode-dump-files.md) + +[Enabling a Kernel-Mode Dump File](enabling-a-kernel-mode-dump-file.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Varieties%20of%20Kernel-Mode%20Dump%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/varieties-of-user-mode-dump-files.md b/windows-driver-docs-pr/debugger/varieties-of-user-mode-dump-files.md new file mode 100644 index 0000000000..f936c4f162 --- /dev/null +++ b/windows-driver-docs-pr/debugger/varieties-of-user-mode-dump-files.md @@ -0,0 +1,39 @@ +--- +title: Varieties of User-Mode Dump Files +description: Varieties of User-Mode Dump Files +ms.assetid: 683f7c77-f14f-4076-b40d-26ff2a117fc1 +keywords: ["dump file, user-mode file types"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Varieties of User-Mode Dump Files + + +## + + +There are several kinds of user-mode crash dump files, but they are divided into two categories: + +[Full User-Mode Dumps](full-user-mode-dumps.md) + +[Minidumps](minidumps.md) + +The difference between these dump files is one of size. Minidumps are usually more compact, and can be easily sent to an analyst. + +**Note**   Much information can be obtained by analyzing a dump file. However, no dump file can provide as much information as actually debugging the crash directly with a debugger. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Varieties%20of%20User-Mode%20Dump%20Files%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/vercommand--show-debugger-command-line-.md b/windows-driver-docs-pr/debugger/vercommand--show-debugger-command-line-.md new file mode 100644 index 0000000000..167596942c --- /dev/null +++ b/windows-driver-docs-pr/debugger/vercommand--show-debugger-command-line-.md @@ -0,0 +1,64 @@ +--- +title: vercommand (Show Debugger Command Line) +description: The vercommand command displays the command that opened the debugger. +ms.assetid: cfac4fb6-8a70-4eeb-a755-caffc6d146e3 +keywords: ["vercommand (Show Debugger Command Line) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vercommand (Show Debugger Command Line) +api_type: +- NA +--- + +# vercommand (Show Debugger Command Line) + + +The **vercommand** command displays the command that opened the debugger. + +``` +vercommand +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20vercommand%20%28Show%20Debugger%20Command%20Line%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/verifying-symbols.md b/windows-driver-docs-pr/debugger/verifying-symbols.md new file mode 100644 index 0000000000..1b6471959c --- /dev/null +++ b/windows-driver-docs-pr/debugger/verifying-symbols.md @@ -0,0 +1,296 @@ +--- +title: Verifying Symbols +description: Verifying Symbols +ms.assetid: 61b4fcce-960b-4091-b575-4dd53c39cff2 +keywords: ["symbols, verifying"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Verifying Symbols + + +## + + +Symbol problems can show up in a variety of ways. Perhaps a stack trace shows incorrect information or fails to identify the names of the functions in the stack. Or perhaps a debugger command failed to understand the name of a module, function, variable, structure, or data type. + +If you suspect that the debugger is not loading symbols correctly, there are several steps you can take to investigate this problem. + +First, use the [**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) command to display the list of loaded modules with symbol information. The most useful form of this command is the following: + +``` +0:000> lml +``` + +If you are using WinDbg, the [Debug | Modules](debug---modules.md) menu command will let you see this information as well. + +Pay particular attention to any notes or abbreviations you may see in these displays. For an interpretation of these, see [Symbol Status Abbreviations](symbol-status-abbreviations.md). + +If you don't see the proper symbol files, the first thing to do is to check the symbol path: + +``` +0:000> .sympath +Current Symbol Path is: d:\MyInstallation\i386\symbols\retail +``` + +If your symbol path is wrong, fix it. If you are using the kernel debugger make sure your local %WINDIR% is not on your symbol path. + +Then reload symbols using the [**.reload (Reload Module)**](-reload--reload-module-.md) command: + +``` +0:000> .reload ModuleName +``` + +If your symbol path is correct, you should activate *noisy mode* so you can see which symbol files **dbghelp** is loading. Then reload your module. See [Setting Symbol Options](symbol-options.md) for information about how to activate noisy mode. + +Here is an example of a "noisy" reload of the Microsoft Windows symbols: + +``` +kd> !sym noisy +kd> .reload nt + 1: Kernel Version 2081 MP Checked + 2: Kernel base = 0x80400000 PsLoadedModuleList = 0x80506fa0 + 3: DBGHELP: FindExecutableImageEx-> Looking for D:\MyInstallation\i386\ntkrnlmp.exe...mismatched timestamp + 4: DBGHELP: No image file available for ntkrnlmp.exe + 5: DBGHELP: FindDebugInfoFileEx-> Looking for + 6: d:\MyInstallation\i386\symbols\retail\symbols\exe\ntkrnlmp.dbg... no file + 7: DBGHELP: FindDebugInfoFileEx-> Looking for + 8: d:\MyInstallation\i386\symbols\retail\symbols\exe\ntkrnlmp.pdb... no file + 9: DBGHELP: FindDebugInfoFileEx-> Looking for d:\MyInstallation\i386\symbols\retail\exe\ntkrnlmp.dbg... OK +10: DBGHELP: LocatePDB-> Looking for d:\MyInstallation\i386\symbols\retail\exe\ntkrnlmp.pdb... OK +11: *** WARNING: symbols checksum and timestamp is wrong 0x0036a4ea 0x00361a83 for ntkrnlmp.exe +``` + +The symbol handler first looks for an image that matches the module it is trying to load (lines three and four). The image itself is not always necessary, but if an incorrect one is present, the symbol handler will often fail. These lines show that the debugger found an image at **D:\\MyInstallation\\i386\\ntkrnlmp.exe**, but the time-date stamp didn't match. Because the time-date stamp didn't match, the search continues. Next, the debugger looks for a .dbg file and a .pdb file that match the loaded image. These are on lines 6 through 10. Line 11 indicates that even though symbols were loaded, the time-date stamp for the image did not match (that is, the symbols were wrong). + +If the symbol-search encountered a catastrophic failure, you would see a message of the form: + +``` +ImgHlpFindDebugInfo(00000000, module.dll, c:\MyDir;c:\SomeDir, 0823345, 0) failed +``` + +This could be caused by items such as file system failures, network errors, and corrupt .dbg files. + +### Diagnosing Symbol Loading Errors + +When in noisy mode, the debugger may print out error codes when it cannot load a symbol file. The error codes for .dbg files are listed in winerror.h. The .pdb error codes come from another source and the most common errors are printed in plain English text. + +Some common error codes for .dbg files from winerror.h are: + +0xB +ERROR\_BAD\_FORMAT + +0x3 +ERROR\_PATH\_NOT\_FOUND + +0x35 +ERROR\_BAD\_NETPATH + +It's possible that the symbol file cannot be loaded because of a networking error. If you see ERROR\_BAD\_FORMAT or ERROR\_BAD\_NETPATH and you are loading symbols from another machine on the network, try copying the symbol file to your host computer and put its path in your symbol path. Then try to reload the symbols. + +### Verifying Your Search Path and Symbols + +Let "c:\\MyDir;c:\\SomeDir" represent your symbol path. Where should you look for debug information? + +In cases where the binary has been stripped of debug information, such as the free builds of Windows, first look for a .dbg file in the following locations: + +``` +c:\MyDir\symbols\exe\ntoskrnl.dbg +c:\SomeDir\symbols\exe\ntoskrnl.dbg +c:\MyDir\exe\ntoskrnl.dbg +c:\SomeDir\exe\ntoskrnl.dbg +c:\MyDir\ntoskrnl.dbg +c:\SomeDir\ntoskrnl.dbg +current-working-directory\ntoskrnl.dbg +``` + +Next, look for a .pdb file in the following locations: + +``` +c:\MyDir\symbols\exe\ntoskrnl.pdb +c:\MyDir\exe\ntoskrnl.pdb +c:\MyDir\ntoskrnl.pdb +c:\SomeDir\symbols\exe\ntoskrnl.pdb +c:\SomeDir\exe\ntoskrnl.pdb +c:\SomeDir\ntoskrnl.pdb +current-working-directory\ntoskrnl.pdb +``` + +Note that in the search for the .dbg file, the debugger interleaves searching through the MyDir and SomeDir directories, but in the .pdb search it does not. + +Windows XP and later versions of Windows do not use any .dbg symbol files. See [Symbols and Symbol Files](symbols-and-symbol-files.md) for details. + +### Mismatched Builds + +One of the most common problems in debugging failures on a machine that is often updated is mismatched symbols from different builds. Three common causes of this problem are: pointing at symbols for the wrong build, using a privately built binary without the corresponding symbols, and using the uniprocessor hardware abstraction level (HAL) and kernel symbols on a multiprocessor machine. The first two are simply a matter of matching your binaries and symbols; the third can be corrected by renaming your hal\*.dbg and ntkrnlmp.dbg to hal.dbg and ntoskrnl.dbg. + +To find out what build of Windows is installed on the target computer, use the [**vertarget (Show Target Computer Version)**](vertarget--show-target-computer-version-.md) command: + +``` +kd> vertarget +Windows XP Kernel Version 2505 UP Free x86 compatible +Built by: 2505.main.010626-1514 +Kernel base = 0x804d0000 PsLoadedModuleList = 0x80548748 +Debug session time: Mon Jul 02 14:41:11 2001 +System Uptime: 0 days 0:04:53 +``` + +### Testing the Symbols + +Testing the symbols is more difficult. It involves verifying a stack trace on the debugger and seeing if the debug output is correct. Here's one example to try: + +``` +kd> u videoprt!videoportfindadapter2 +Loading symbols for 0xf2860000 videoprt.sys -> videoprt.sys + +VIDEOPRT!VideoPortFindAdapter2: +f2856f42 55 push ebp +f2856f43 8bec mov ebp,esp +f2856f45 81ecb8010000 sub esp,0x1b8 +f2856f4b 8b4518 mov eax,[ebp+0x18] +f2856f4e 53 push ebx +f2856f4f 8365f400 and dword ptr [ebp-0xc],0x +f2856f53 8065ff00 and byte ptr [ebp-0x1],0x0 +f2856f57 56 push esi +``` + +The **u** command unassembles the videoportfindadapter string in videoprt.sys. The symbols are correct on the debugger because common stack commands like **push** and **mov** show up on the stack. Most functions begin with an add, sub, or push operation using either the base pointer (ebp) or the stack pointer (esp). + +It's usually obvious when the symbols aren't working correctly. Glintmp.sys doesn't have symbols in this example because a function isn't listed next to **Glintmp**: + +``` +kd> kb +Loading symbols for 0xf28d0000 videoprt.sys -> videoprt.sys +Loading symbols for 0xf9cdd000 glintmp.sys -> glintmp.sys +*** ERROR: Symbols could not be loaded for glintmp.sys +ChildEBP RetAddr Args to Child +f29bf1b0 8045b5fa 00000001 0000a100 00000030 ntoskrnl!RtlpBreakWithStatusInstruction +f29bf1b0 8044904e 00000001 0000a100 00000030 ntoskrnl!KeUpdateSystemTime+0x13e +f29bf234 f28d1955 f9b7d000 ffafb2dc f9b7d000 ntoskrnl!READ_REGISTER_ULONG+0x6 +f29bf248 f9cde411 f9b7d000 f29bf2b0 f9ba0060 VIDEOPRT!VideoPortReadRegisterUlong+0x27 +00000002 00000000 00000000 00000000 00000000 glintMP+0x1411 [No function listed.] +``` + +The wrong build symbols were loaded for this stack trace. Notice how there are no functions listed for the first two calls. This stack trace looks like a problem with win32k.sys drawing rectangles: + +``` +1: kd> +1: kd> kb [Local 9:50 AM] +Loading symbols for 0xf22b0000 agpcpq.sys -> agpcpq.sys +*** WARNING: symbols checksum is wrong 0x0000735a 0x00000000 for agpcpq.sys +*** ERROR: Symbols could not be loaded for agpcpq.sys +Loading symbols for 0xa0000000 win32k.sys -> win32k.sys +*** WARNING: symbols checksum is wrong 0x00191a41 0x001995a9 for win32k.sys +ChildEBP RetAddr Args to Child +be682b18 f22b372b 82707128 f21c1ffc 826a70f8 agpCPQ+0x125b [No function listed.] +be682b4c a0140dd4 826a72f0 e11410a8 a0139605 agpCPQ+0x372b [No function listed.] +be682b80 a00f5646 e1145100 e1cee560 e1cee560 win32k!vPatCpyRect1_6x6+0x20b +00000001 00000000 00000000 00000000 00000000 win32k!RemoteRedrawRectangle+0x32 +``` + +Here's the correct stack trace. The problem is really with AGP440.sys. The first item appearing on a stack trace is usually at fault. Notice that the win32k.sys rectangle error is gone: + +``` +1: kd> kb [Local 9:49 AM] +ChildEBP RetAddr Args to Child +be682b18 f22b372b 82707128 f21c1ffc 826a70f8 agpCPQ!AgpReleaseMemory+0x88 +be682b30 f20a385c 82703638 e183ec68 00000000 agpCPQ!AgpInterfaceReleaseMemory+0x8b +be682b4c a0140dd4 826a72f0 e11410a8 a0139605 VIDEOPRT!AgpReleasePhysical+0x44 +be682b58 a0139605 e1cee560 e11410a8 a00e5f0a win32k!OsAGPFree+0x14 +be682b64 a00e5f0a e1cee560 e11410a8 e1cee560 win32k!AGPFree+0xd +be682b80 a00f5646 e1145100 e1cee560 e1cee560 win32k!HeapVidMemFini+0x49 +be682b9c a00f5c20 e1cee008 e1cee008 be682c0c win32k!vDdDisableDriver+0x3a +be682bac a00da510 e1cee008 00000000 be682c0c win32k!vDdDisableDirectDraw+0x2d +be682bc4 a00da787 00000000 e1843df8 e1843de8 win32k!PDEVOBJ__vDisableSurface+0x27 +be682bec a00d59fb 00000000 e1843de8 00000000 win32k!PDEVOBJ__vUnreferencePdev+0x204 +be682c04 a00d7421 e1cee008 82566a98 00000001 win32k!DrvDestroyMDEV+0x30 +be682ce0 a00a9e7f e1843e10 e184a008 00000000 win32k!DrvChangeDisplaySettings+0x8b3 +be682d20 a008b543 00000000 00000000 00000000 win32k!xxxUserChangeDisplaySettings+0x106 +be682d48 8045d119 00000000 00000000 00000000 win32k!NtUserChangeDisplaySettings+0x48 +be682d48 77e63660 00000000 00000000 00000000 ntkrnlmp!KiSystemService+0xc9 +``` + +### Useful Commands and Extensions + +The following commands and extensions may be useful in tracking down symbol problems: + +[**lm (List Loaded Modules)**](lm--list-loaded-modules-.md) +Lists all modules and gives the loading status of all symbols in these modules. + +[**!dh image-header-base**](-dh.md) +Displays header information for a loaded image beginning at *image-header-base*. + +[**.reload /n**](-reload--reload-module-.md) +Reloads all kernel symbols. + +[**.reload \[image-name\]**](-reload--reload-module-.md) +(CDB or WinDbg only) Reloads symbols for the image *image-name*. If no *image-name* is specified, reloads symbols for all images. (It is necessary to reload symbols after the symbol path has been changed.) + +[**!sym noisy**](-sym.md) +Turns on verbose mode for symbol loads. This can be used to get information about the module loads. See [Setting Symbol Options](symbol-options.md) for details. + +[**.sympath \[new-symbol-path\]**](-sympath--set-symbol-path-.md) +Sets a new symbol path, or displays the current symbol path. See [Symbol Path](symbol-path.md) for details. + +If the kernel symbols are correct, but you aren't getting a complete stack, the following commands may also be useful: + +[**X \*!**](x--examine-symbols-.md) +This will list the modules which currently have symbols loaded. This is useful if the kernel symbols are correct. + +[**.reload /user**](-reload--reload-module-.md) +This will attempt to reload all user-mode symbols. This is needed while performing kernel debugging if symbols were loaded while one process was running, and a break later occurred in another process. In this case, the user-mode symbols from the new process will not be loaded unless this command is executed. + +[**X wdmaud!\*start\***](x--examine-symbols-.md) +This will list only the symbols in the **wdmaud** module whose names contain the "start" string. This has the advantage that it forces the reloading of all the symbols in **wdmaud**, but only displays those with "start" in them. (This means a shorter listing, but since there are always some symbols with "start" in them, there will be some verification that the load has taken place.) + +One other useful technique for verifying symbols is unassembling code. Most functions begin with an add, sub, or push operation using either the base pointer (**ebp**) or the stack pointer (**esp** or **sp**). Try unassembling ([**U Function**](u--unassemble-.md)) some of the functions on the stack (from offset zero) to verify the symbols. + +### Network and Port Problems + +Problems will occur with the symbol files and while connecting to the debugger. Here are a few things to keep in mind if you encounter problems: + +- Determine which COM port the debug cable is connected to on the test system. + +- Check the boot.ini settings of the test system. Look for the **/debug** switch and check the baud rate and COM port settings. + +- Network problems can interfere with debugging if the symbols files are accessed through the network. + +- .dll and .sys files with the same name (for example − mga64.sys and mga64.dll) will confuse the debugger if they aren't separated into the proper directories of the symbol tree. + +- The kernel debugger doesn't always like replacing the build symbol files with private symbol files. Double check the symbol path and do a **.reload***FileName* on the misbehaving symbol. The [**!dlls**](-dlls.md) command is sometimes useful. + +### Questions and Misconceptions + +**Q:** I've successfully loaded symbols, but the stack seems to be wrong. Is the debugger broken? + +**A:** Not necessarily. The most likely cause of your problem is that you've got incorrect symbols. Go through the steps outlined in this section to determine whether you've loaded valid symbols or not. Do not assume that because some things work you have valid symbols. For example, you very well may be able to execute **dd nt!ntbuildnumber** or **u nt!KeInitializeProcess** with incorrect symbols. Verify that they are correct using the procedures outlined above. + +**Q:** Will the debugger still work with incorrect symbols? + +**A:** Yes and no. Often you can get away with symbols that don't strictly match. For example, symbols from a previous Windows build will often work in certain cases, but there is no rule as to when this will work and when it will not. + +**Q:** I'm stopped in the kernel debugger and I want to view symbols for my user-mode process. Can I do it? + +**A:** Mostly. The support for this scenario is poor because the kernel debugger doesn't keep enough information around to track the module loads for each process, but there's a reasonable workaround. To load symbols for a user-mode module, execute a **.reload -user** command. This will load the user-mode modules for the current context. + +**Q:** What does the following message mean? + +``` +*** WARNING: symbols checksum and timestamp is wrong 0x0036d6bf 0x0036ab55 for ntkrnlmp.exe +``` + +**A:** It means your symbols for ntkrnlmp.exe are wrong. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Verifying%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/verifying-the-creation-of-a-kernel-mode-dump-file.md b/windows-driver-docs-pr/debugger/verifying-the-creation-of-a-kernel-mode-dump-file.md new file mode 100644 index 0000000000..5f3ad31a8d --- /dev/null +++ b/windows-driver-docs-pr/debugger/verifying-the-creation-of-a-kernel-mode-dump-file.md @@ -0,0 +1,39 @@ +--- +title: Verifying the Creation of a Kernel-Mode Dump File +description: Verifying the Creation of a Kernel-Mode Dump File +ms.assetid: ea1dc18d-8974-4de8-accd-1cbc515d71d0 +keywords: ["dump file, verifying kernel-mode dump creation"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Verifying the Creation of a Kernel-Mode Dump File + + +## + + +If you have a machine that has broken into the debugger, but you are unsure whether the crash dump file was successfully written, execute the following command: + +``` +dd nt!IopFinalCrashDumpStatus L1 +``` + +This displays the value of the **IopFinalCrashDumpStatus** variable. + +If this value equals zero, the process was successful. If it equals -1 (0xFFFFFFFF), the dump process has not started. + +Any other value is a status code indicating an error during the dump process. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Verifying%20the%20Creation%20of%20a%20Kernel-Mode%20Dump%20File%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/version--show-debugger-version-.md b/windows-driver-docs-pr/debugger/version--show-debugger-version-.md new file mode 100644 index 0000000000..9e7de2d699 --- /dev/null +++ b/windows-driver-docs-pr/debugger/version--show-debugger-version-.md @@ -0,0 +1,74 @@ +--- +title: version (Show Debugger Version) +description: The version command displays version information about the debugger and all loaded extension DLLs. +ms.assetid: 51819d56-c24f-41f2-9090-5787e24ea773 +keywords: ["version (Show Debugger Version) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- version (Show Debugger Version) +api_type: +- NA +--- + +# version (Show Debugger Version) + + +The **version** command displays version information about the debugger and all loaded extension DLLs. This command also displays the current version of the operating system of the target computer. + +Do not confuse this command with the [**!version (Show DLL Version)**](-version.md) extension command. + +``` +version +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +## See also + + +[**CTRL+W (Show Debugger Version)**](ctrl-w--show-debugger-version-.md) + +[**vertarget (Show Target Computer Version)**](vertarget--show-target-computer-version-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20version%20%28Show%20Debugger%20Version%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/vertarget--show-target-computer-version-.md b/windows-driver-docs-pr/debugger/vertarget--show-target-computer-version-.md new file mode 100644 index 0000000000..a690176912 --- /dev/null +++ b/windows-driver-docs-pr/debugger/vertarget--show-target-computer-version-.md @@ -0,0 +1,72 @@ +--- +title: vertarget (Show Target Computer Version) +description: The vertarget command displays the current version of the Microsoft Windows operating system of the target computer. +ms.assetid: 27aa26ac-6343-412f-a0ed-6d5e3546827b +keywords: ["vertarget (Show Target Computer Version) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- vertarget (Show Target Computer Version) +api_type: +- NA +--- + +# vertarget (Show Target Computer Version) + + +The **vertarget** command displays the current version of the Microsoft Windows operating system of the target computer. + +``` +vertarget +``` + +## + + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +## See also + + +[**CTRL+W (Show Debugger Version)**](ctrl-w--show-debugger-version-.md) + +[**version (Show Debugger Version)**](version--show-debugger-version-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20vertarget%20%28Show%20Target%20Computer%20Version%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/view---call-stack.md b/windows-driver-docs-pr/debugger/view---call-stack.md new file mode 100644 index 0000000000..9b42cda2ff --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---call-stack.md @@ -0,0 +1,33 @@ +--- +title: View Call Stack +description: View Call Stack +ms.assetid: a62332fd-f2d2-4715-bda5-4e8d73250d14 +keywords: ["View Call Stack"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Call Stack + + +## + + +Click **Call Stack** on the **View** menu to open the [Calls window](calls-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+6 or clicking the **Call stack (Alt+6)** button (![screen shot of the call stack button](images/tbcall.png)) on the toolbar. + +For more information about this window and its uses, see [Calls Window](calls-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Call%20Stack%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---command-browser.md b/windows-driver-docs-pr/debugger/view---command-browser.md new file mode 100644 index 0000000000..35ab23e632 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---command-browser.md @@ -0,0 +1,30 @@ +--- +title: View Command Browser +description: View Command Browser +ms.assetid: 61ddbca3-e718-41a4-8b02-b57e2c36751d +keywords: ["View Command Browser", "command browser window, View Command Browser"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Command Browser + + +Click **Command Browser** on the **View** menu to open the [Command Browser window](command-browser-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing CTRL+N or clicking the **Command Browser (Ctrl+N)** button (![screen shot of the command browser button](images/window-command-browser-icon.png)) on the toolbar. + +For more information about this window and its uses, see [Command Browser Window](command-browser-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Command%20Browser%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---command.md b/windows-driver-docs-pr/debugger/view---command.md new file mode 100644 index 0000000000..f3bcdf9d93 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---command.md @@ -0,0 +1,33 @@ +--- +title: View Command +description: View Command +ms.assetid: 5ed8a9bb-efc7-4954-8cb9-b6ee41686bf5 +keywords: ["View Command"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Command + + +## + + +Click **Command** on the **View** menu to open the [Debugger Command window](debugger-command-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+1 or clicking the **Command (Alt+1)** button (![screen shot of the debugger command window button](images/tbcmd.png)) on the toolbar. + +For more information about this window and its uses, see [Debugger Command Window](debugger-command-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Command%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---disassembly.md b/windows-driver-docs-pr/debugger/view---disassembly.md new file mode 100644 index 0000000000..e9f0e17e78 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---disassembly.md @@ -0,0 +1,33 @@ +--- +title: View Disassembly +description: View Disassembly +ms.assetid: b48bb067-aa7b-458e-a6da-35fba3dc7c21 +keywords: ["View Disassembly"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Disassembly + + +## + + +Click **Disassembly** on the **View** menu to open the [Disassembly window](disassembly-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+7 or clicking the **Disassembly (Alt+7)** button (![screen shot of the disassembly button](images/tbdisasm2.png)) on the toolbar. + +For more information about this window and its uses, see [Disassembly Window](disassembly-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Disassembly%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---font.md b/windows-driver-docs-pr/debugger/view---font.md new file mode 100644 index 0000000000..c6602fec80 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---font.md @@ -0,0 +1,41 @@ +--- +title: View Font +description: View Font +ms.assetid: 808cd0e5-5433-4705-830e-acf1087a6df5 +keywords: ["View Font"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Font + + +## + + +Click **Font** on the **View** menu to change the font that appears in the debugging information windows. + +This command is equivalent to clicking the **Font** button (![screen shot of the font button](images/tbfont.png)) on the toolbar. + +### Dialog Box + +When you click **Font**, the **Font** dialog box appears. In this dialog box, you can select the font, style, and size from the appropriate lists,. You can also select the script from a drop-down menu to get the appropriate alphabet. To accept your changes, click **OK**. + +Click **Cancel** to cancel changes to the font. + +### Additional Information + +For more information about how to change the character display of the debugging information windows, see [Changing Text Properties](changing-text-properties.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Font%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---locals.md b/windows-driver-docs-pr/debugger/view---locals.md new file mode 100644 index 0000000000..97c788aaf8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---locals.md @@ -0,0 +1,33 @@ +--- +title: View Locals +description: View Locals +ms.assetid: 27ecd1f9-76c3-4e9a-ad0f-2c92e5d6a0ba +keywords: ["View Locals"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Locals + + +## + + +Click **Locals** on the **View** menu to open the Locals window. If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+3 or clicking the **Locals (Alt+3)** button (![screen shot of the locals button](images/tblocal.png)) on the toolbar. + +For more information about this window and its uses, see [Locals Window](locals-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Locals%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---memory.md b/windows-driver-docs-pr/debugger/view---memory.md new file mode 100644 index 0000000000..fa1beb0067 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---memory.md @@ -0,0 +1,37 @@ +--- +title: View Memory +description: View Memory +ms.assetid: 6d4630c0-2b57-417d-8ab1-85116d8e0ff0 +keywords: ["View Memory"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Memory + + +## + + +Click **Memory** on the **View** menu to open a new [Memory window](memory-window.md). + +**Note**   You can have multiple Memory windows open at the same time. Each window can display a different region of memory. Only the Memory window and the [Source window](source-window.md) have this ability. All other debugging information windows are limited to a single instance. + +  + +The **View** command is equivalent to pressing ALT+5 or clicking the **Memory window (Alt+5)** button (![screen shot of the memory button](images/tbmem.png)) on the toolbar. + +For more information about this window and its uses, see [Memory Window](memory-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Memory%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---options.md b/windows-driver-docs-pr/debugger/view---options.md new file mode 100644 index 0000000000..a437e768a8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---options.md @@ -0,0 +1,80 @@ +--- +title: View Options +description: View Options +ms.assetid: 2579c586-f1f3-4b03-a47f-22be98fe6c51 +keywords: ["View Options"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Options + + +## + + +Click **Options** on the **View** menu to open the **Options** dialog box. This command is equivalent to clicking the button (![screen shot of the options button](images/tbopt.png)) on the toolbar. + +### Dialog Box + +In the **Options** dialog box, you can select or deselect the following options: + +**Tab width** +The **Tab width** box controls how tab characters are displayed in any Source window. In the **Tab width** box, enter the number of spaces that you want to have between each tab setting. (The default setting is 8. For more information about text properties, see [Changing Text Properties](changing-text-properties.md).) + +**Reuse after opening this many** +The **Reuse after opening this many** box controls the number of document, or source, windows that can be open at the same time. If the specified number of source windows has been reached, opening a new window causes an existing window to close. Windows that are marked as tab-dock targets do not close. The last windows to close are the ones you used most recently. + +**Parse source languages** +If the **Parse source languages** check box is selected, the text of source code in all Source windows is colored according to a simple parse of the source syntax. To change the colors, in the **Colors** area of the dialog box, select a syntax element and then click **Change**. (To turn the syntax colors off in a single Source window, open that window's shortcut menu, click **Select source language**, and then click **<None>**.) + +**Evaluate on hover** +If the **Evaluate on hover** check box is selected (and the **Parse source languages** check box is selected as well), symbols in a Source window will be evaluated when you select that window and then hover over a symbol with the mouse. The evaluation is the same as that produced by the [**dt (Display Type)**](dt--display-type-.md) command. + +**Enter repeats last command** +If the **Enter repeats last command** check box is selected, you can press the ENTER key at an empty prompt in the [Debugger Command window](debugger-command-window.md) to repeat the previous command. If you clear this check box, the ENTER key generates a new prompt. + +**Automatically scroll** +The **Automatically scroll** check box controls the automatic scrolling that occurs when new text is sent to the Debugger Command window. If you want to turn off this feature, clear the **Automatically scroll** check box. For more information about this scrolling, see [Using Debugger Commands](using-debugger-commands.md). + +**Workspace Prompts** +In the **Workspace Prompts** area, you can click one of three options to determine when and how frequently the workspace is saved in WinDbg. + +- If you click **Always ask**, when a workspace changes (such as when a debugging session ends), the debugger displays the **Workspace save** dialog box where you can save the workspace. + + In the **Workspace save** dialog box, if you click **Don't ask again**, WinDbg resets the **Workspace Prompts** option to **Never save** or **Always save**. + +- If you click **Always save**, the workspace is saved automatically whenever it changes. + +- If you click **Never save**, the workspace is not saved when it changes, and you are not prompted to save it. + +**QuickEdit Mode** +If the **QuickEdit Mode** check box is selected, you can right-click an item to copy or paste, depending on the window selection state. When you clear this check, QuickEdit is disabled and you can right-click an item to open a shortcut menu for the window. You cannot give individual windows different settings; the QuickEdit setting applies globally to all windows. By default, this box is selected. The QuickEdit setting is saved in the current workspace. + +**Colors** +To change the color of the source text that is displayed, select an item from the **Colors** area and then click **Change**. Select a color, or select a custom color, and then click **OK**. + +In the **Colors** menu, you can change the colors of the following items: + +- The first ten items represent text in the [Disassembly window](disassembly-window.md) and the [Source window](source-window.md). + +- The **Changed data text** item represents data entries that have been changed (for example, in the [Registers window](registers-window.md)). + +- The ten **Source** *Xxx* items control the colors that are used for syntax elements in the Source window. + +- The remaining items refer to different kinds of text in the Debugger Command window. + +These color changes take effect when you click **OK**. To discard these changes, click **Cancel**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---processes-and-threads.md b/windows-driver-docs-pr/debugger/view---processes-and-threads.md new file mode 100644 index 0000000000..4797e79ab1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---processes-and-threads.md @@ -0,0 +1,33 @@ +--- +title: View Processes and Threads +description: View Processes and Threads +ms.assetid: 00a496e9-6791-4df4-bf95-18b20d5d9677 +keywords: ["View Processes and Threads"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Processes and Threads + + +## + + +Click **Processes and Threads** on the **View** menu to open the [Processes and Threads window](processes-and-threads-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+9 or clicking the **Processes and Threads (Alt+9)** button (![screen shot of the processes and threads button](images/window-processes-threads.png)) on the toolbar. + +For more information about this window and its uses, see [Processes and Threads Window](processes-and-threads-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Processes%20and%20Threads%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---registers.md b/windows-driver-docs-pr/debugger/view---registers.md new file mode 100644 index 0000000000..81c8a25845 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---registers.md @@ -0,0 +1,33 @@ +--- +title: View Registers +description: View Registers +ms.assetid: d5299e53-1735-452b-9fd8-dbcb69e7cccd +keywords: ["View Registers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Registers + + +## + + +Click **Registers** on the **View** menu to open the [Registers window](registers-window.md). If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+4 or clicking the **Registers (Alt+4)** button (![screen shot of the registers button](images/tbreg.png)) on the toolbar. + +For more information about this window and its uses, see [Registers Window](registers-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Registers%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---scratch-pad.md b/windows-driver-docs-pr/debugger/view---scratch-pad.md new file mode 100644 index 0000000000..e4ef0260e0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---scratch-pad.md @@ -0,0 +1,31 @@ +--- +title: View Scratch Pad +description: View Scratch Pad +ms.assetid: 7bff1956-d38f-43ac-89a2-ad0afd9e2919 +keywords: ["View Scratch Pad"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Scratch Pad + + +## + + +Click **Scratch Pad** on the **View** menu to open the Scratch Pad. If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+8 or clicking the **Scratch Pad (Alt+8)** button (![screen shot of the scratch pad button](images/tbspad.png)) on the toolbar. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Scratch%20Pad%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---show-version.md b/windows-driver-docs-pr/debugger/view---show-version.md new file mode 100644 index 0000000000..914b69c960 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---show-version.md @@ -0,0 +1,33 @@ +--- +title: View Show Version +description: View Show Version +ms.assetid: d4a61e8a-600e-4dd5-a0dc-0da05923f3f1 +keywords: ["View Show Version"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Show Version + + +## + + +Click **Show Version** on the **View** menu to display version information about the debugger and all loaded extension DLLs. This information is displayed in the [Debugger Command window](debugger-command-window.md). + +This command is equivalent to pressing CTRL+ALT+W (and pressing CTRL+W in KD). + +This command has the same effect as the [**version (Show Debugger Version)**](version--show-debugger-version-.md) command, except that the latter command also displays the version of the Microsoft Windows operating system. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Show%20Version%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---source-language-file-extensions.md b/windows-driver-docs-pr/debugger/view---source-language-file-extensions.md new file mode 100644 index 0000000000..314915911b --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---source-language-file-extensions.md @@ -0,0 +1,30 @@ +--- +title: View Source language file extensions +description: View Source language file extensions +ms.assetid: 98deead3-1d4f-41b0-be71-0bae4c0f5c81 +keywords: ["View Source Language File Extensions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Source language file extensions + + +Click **Source language file extensions** on the **View** menu to control the file name extensions that WinDbg recognizes as source file name extensions. You can also specify which programming languages are associated with which file name extensions. + +### Dialog Box + +When you click **Source language file extensions**, the **File Extensions for Source Languages** dialog box appears. In this dialog box, you can add or delete file name extensions by inserting the cursor in the **Extensions and languages** box and typing the appropriate information. Make sure that you specify the appropriate programming language for each file name extension. For example, **cxx=C++** indicates that a .cxx file name extension is a source file and that the corresponding programming language of any file that has that extension is C++. Click **OK** to implement your changes, or click **Cancel** to discard any changes. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Source%20language%20file%20extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---status-bar.md b/windows-driver-docs-pr/debugger/view---status-bar.md new file mode 100644 index 0000000000..0a0a3566d1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---status-bar.md @@ -0,0 +1,31 @@ +--- +title: View Status Bar +description: View Status Bar +ms.assetid: e8b38975-46ca-4a27-aff7-f5f0d03e9158 +keywords: ["View Status Bar", "status bar, View Status Bar"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Status Bar + + +## + + +Select or clear **Status Bar** on the **View** menu to cause the status bar to become visible or invisible. + +For more information about how to use the status bar, see [Using the Toolbar and Status Bar](using-the-toolbar-and-status-bar.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Status%20Bar%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---toolbar.md b/windows-driver-docs-pr/debugger/view---toolbar.md new file mode 100644 index 0000000000..8dc409f0da --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---toolbar.md @@ -0,0 +1,31 @@ +--- +title: View Toolbar +description: View Toolbar +ms.assetid: 0c8e8a6e-2924-4afd-925e-346511b943de +keywords: ["View Toolbar", "toolbar (WinDbg), View Toolbar"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Toolbar + + +## + + +Select or clear **Toolbar** on the **View** menu to cause the toolbar to appear or disappear. + +For more information about how to use the toolbar, see [Using the Toolbar and Status Bar](using-the-toolbar-and-status-bar.md). For more information about each toolbar button, see [Toolbar Buttons](toolbar-buttons.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Toolbar%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---verbose-output.md b/windows-driver-docs-pr/debugger/view---verbose-output.md new file mode 100644 index 0000000000..373d5f2009 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---verbose-output.md @@ -0,0 +1,33 @@ +--- +title: View Verbose Output +description: View Verbose Output +ms.assetid: 728cf574-30ec-4e30-b951-2d9997d8defe +keywords: ["View Verbose Output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Verbose Output + + +## + + +Click **Verbose Output** on the **View** menu to turn verbose mode on and off. + +This command is equivalent to pressing CTRL+ALT+V. (and to pressing CTRL+V in KD). + +When verbose mode is turned on, some display commands (such as register dumping) produce more detailed output. Every MODULE LOAD operation that is sent to the debugger is displayed. And every time that a driver or DLL is loaded by the operating system, the debugger is notified. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Verbose%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---watch.md b/windows-driver-docs-pr/debugger/view---watch.md new file mode 100644 index 0000000000..473549cad1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---watch.md @@ -0,0 +1,31 @@ +--- +title: View Watch +description: View Watch +ms.assetid: 722d6b80-32d8-406b-b9af-ef40d75462e5 +keywords: ["View Watch"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | Watch + + +## + + +Click **Watch** on the **View** menu to open the Watch window. If this window is already open, it becomes active. + +This command is equivalent to pressing ALT+2 or clicking the **Watch (Alt+2)** button (![screen shot of the watch button](images/tbwatch.png)) on the toolbar. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20Watch%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view---windbg-command-line.md b/windows-driver-docs-pr/debugger/view---windbg-command-line.md new file mode 100644 index 0000000000..f2d011298e --- /dev/null +++ b/windows-driver-docs-pr/debugger/view---windbg-command-line.md @@ -0,0 +1,31 @@ +--- +title: View WinDbg Command Line +description: View WinDbg Command Line +ms.assetid: 8127d6c9-ad63-47cb-8975-b2671d896e44 +keywords: ["View WinDbg Command Line"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View | WinDbg Command Line + + +## + + +Click **WinDbg Command Line** on the **View** menu to display the command that was used to open the current WinDbg session. + +The command appears in a small message window. Click **OK** to close this window. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20|%20WinDbg%20Command%20Line%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/view-menu.md b/windows-driver-docs-pr/debugger/view-menu.md new file mode 100644 index 0000000000..19449a0352 --- /dev/null +++ b/windows-driver-docs-pr/debugger/view-menu.md @@ -0,0 +1,71 @@ +--- +title: View Menu +description: View Menu +ms.assetid: 2ebdff44-5593-46be-8bd8-8ececf8d9031 +keywords: ["View Menu (complete listing)", "graphical interface, view menu"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# View Menu + + +## + + +This section describes the following commands on the **View** menu of WinDbg: + +[View | Command](view---command.md) + +[View | Watch](view---watch.md) + +[View | Locals](view---locals.md) + +[View | Registers](view---registers.md) + +[View | Memory](view---memory.md) + +[View | Call Stack](view---call-stack.md) + +[View | Disassembly](view---disassembly.md) + +[View | Scratch Pad](view---scratch-pad.md) + +[View | Processes and Threads](view---processes-and-threads.md) + +[View | Command Browser](view---command-browser.md) + +**View | Recent Commands** + +**View | Set Browser Start Command** + +[View | Verbose Output](view---verbose-output.md) + +**View | Event Timestamps** + +[View | Show Version](view---show-version.md) + +[View | Toolbar](view---toolbar.md) + +[View | Status Bar](view---status-bar.md) + +[View | Font](view---font.md) + +[View | Options](view---options.md) + +[View | Source language file extensions](view---source-language-file-extensions.md) + +[View | WinDbg Command Line](view---windbg-command-line.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20View%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-and-editing-global-variables-in-windbg.md b/windows-driver-docs-pr/debugger/viewing-and-editing-global-variables-in-windbg.md new file mode 100644 index 0000000000..5c04d1ea08 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-and-editing-global-variables-in-windbg.md @@ -0,0 +1,35 @@ +--- +title: Viewing and Editing Global Variables in WinDbg +description: Viewing and Editing Global Variables in WinDbg +ms.assetid: 4273F6D8-A2A1-43FA-80BF-97E5673FAF05 +--- + +# Viewing and Editing Global Variables in WinDbg + + +## + + +The debugger interprets the name of a global variable as a virtual address. Therefore, you can use all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) to read or write global variables. + +In addition, you can use the [**? (Evaluate Expression)**](---evaluate-expression-.md) command to display the address that is associated with any symbol. + +In WinDbg, you can also use the Watch window to display and change global and local variables. The Watch window can display any list of variables that you want. These variables can include global variables and local variables from any function. At any time, the Watch window displays the values of those variables that match the current function's scope. You can also change the values of these variables through the Watch window. + +To open the Watch window, choose **Watch** from the **View** menu. You can also press ALT+2 or click the **Watch** button on the toolbar: ![screen shot of the watch button](images/tbwatch.png). ALT+SHIFT+2 closes the Watch window. + +The following screen shot shows an example of a Watch window. + +![screen shot of the watch window ](images/window-watch.png) + +The Watch window can contain four columns. The **Name** and **Value** columns are always displayed, and the **Type** and **Location** columns are optional. To display the **Type** and **Location** columns, click the **Typecast** and **Locations** buttons, respectively, on the toolbar. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Global%20Variables%20in%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-cdb.md b/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-cdb.md new file mode 100644 index 0000000000..d12a880041 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-cdb.md @@ -0,0 +1,26 @@ +--- +title: Viewing and Editing Registers in CDB +description: In CDB, you can view registers by entering the r (Registers) command in the Debugger Command window. You can customize the display by using several options or by using the rm (Register Mask) command. +ms.assetid: 33A2AF32-B4A6-430A-AD08-73B51D5D6301 +--- + +# Viewing and Editing Registers in CDB + + +Registers are small volatile memory units that are located on the CPU. Many registers are dedicated to specific uses, and other registers are available for user-mode applications to use. The x86-based and x64-based processors have different collections of registers available. For more information about the registers on each processor, see [Processor Architecture](processor-architecture.md). + +In CDB, you can view registers by entering the [**r (Registers)**](r--registers-.md) command in the Debugger Command window. You can customize the display by using several options or by using the [**rm (Register Mask)**](rm--register-mask-.md) command. + +Registers are also automatically displayed every time that the target stops. If you are stepping through your code with the [**p (Step)**](p--step-.md) or [**t (Trace)**](t--trace-.md) commands, you see a register display at every step. To stop this display, use the **r** option when you use these commands. + +On an x86-based processor, the **r** option also controls several one-bit registers known as flags. To change these flags, you use a slightly different syntax than when changing regular registers. For more information about these flags and an explanation of this syntax, see [x86 Flags](x86-architecture.md#x86-flags). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Registers%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-kd.md b/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-kd.md new file mode 100644 index 0000000000..147aa8fb68 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-and-editing-registers-in-kd.md @@ -0,0 +1,26 @@ +--- +title: Viewing and Editing Registers in KD +description: In KD, you can view and edit registers by entering the r (Registers) command. You can customize the display by using several options or by using the rm (Register Mask) command. +ms.assetid: 42306338-6E11-4724-B62F-D1E0BDBA7F8D +--- + +# Viewing and Editing Registers in KD + + +Registers are small volatile memory units that are located on the CPU. Many registers are dedicated to specific uses, and other registers are available for user-mode applications to use. The x86-based and x64-based processors have different collections of registers available. For more information about the registers on each processor, see [Processor Architecture](processor-architecture.md). + +In KD, you can view and edit registers by entering the [**r (Registers)**](r--registers-.md) command. You can customize the display by using several options or by using the [**rm (Register Mask)**](rm--register-mask-.md) command. + +Registers are also automatically displayed every time that the target stops. If you are stepping through your code with the [**p (Step)**](p--step-.md) or [**t (Trace)**](t--trace-.md) commands, you see a register display at every step. To stop this display, use the **r** option when you use these commands. + +On an x86-based processor, the **r** option also controls several one-bit registers known as flags. To change these flags, you use a slightly different syntax than when changing regular registers. For more information about these flags and an explanation of this syntax, see [x86 Flags](x86-architecture.md#x86-flags). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Registers%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-cdb.md b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-cdb.md new file mode 100644 index 0000000000..4b377b638b --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-cdb.md @@ -0,0 +1,30 @@ +--- +title: Viewing and Editing Memory in CDB +description: Viewing and Editing Memory in CDB +ms.assetid: EE2424F3-A692-4AEA-9F09-337C5758D8AD +--- + +# Viewing and Editing Memory in CDB + + +## Viewing and Editing Memory + + +In CDB, you can view and edit memory by entering one of the [**Display Memory**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) commands, and you can edit memory by entering one of the [**Enter Values**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) commands. For a detailed discussion of these commands, see [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) and [Accessing Memory by Physical Address](accessing-memory-by-physical-address.md). + +## Viewing and Editing Variables + + +In CDB, you can view and edit global variables by entering commands. The debugger interprets the name of a global variable as a virtual address. Therefore, all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) can be used to read or write global variables. For additional information about viewing and editing global variables, see [Accessing Global Variables](accessing-global-variables.md). + +In CDB you can view and edit local variables by entering commands. The debugger interprets the name of a local variable as an address. Therefore, all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) can be used to read or write local variables. However, if it is necessary to indicate to a command that a symbol is local, precede the symbol with a dollar sign ( $ ) and an exclamation point ( ! ), as in `$!var`. For additional information about viewing and editing local variables, see [Accessing Local Variables](accessing-local-variables.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Memory%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-kd.md b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-kd.md new file mode 100644 index 0000000000..b3cf7de89f --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-kd.md @@ -0,0 +1,30 @@ +--- +title: Viewing and Editing Memory in KD +description: Viewing and Editing Memory in KD +ms.assetid: 7E40F32F-C7B4-44A2-B3F9-84D673013EB2 +--- + +# Viewing and Editing Memory in KD + + +## Viewing and Editing Memory + + +In KD, you can view and edit memory by entering one of the [**Display Memory**](d--da--db--dc--dd--dd--df--dp--dq--du--dw--dw--dyb--dyd--display-memor.md) commands, and you can edit memory by entering one of the [**Enter Values**](e--ea--eb--ed--ed--ef--ep--eq--eu--ew--eza--ezu--enter-values-.md) commands. For a detailed discussion of these commands, see [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) and [Accessing Memory by Physical Address](accessing-memory-by-physical-address.md). + +## Viewing and Editing Variables + + +In KD, you can view and edit global variables by entering commands. The debugger interprets the name of a global variable as a virtual address. Therefore, all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) can be used to read or write global variables. For additional information about viewing and editing global variables, see [Accessing Global Variables](accessing-global-variables.md). + +In KD you can view and edit local variables by entering commands. The debugger interprets the name of a local variable as an address. Therefore, all of the commands that are described in [Accessing Memory by Virtual Address](accessing-memory-by-virtual-address.md) can be used to read or write local variables. However, if it is necessary to indicate to a command that a symbol is local, precede the symbol with a dollar sign ( $ ) and an exclamation point ( ! ), as in `$!var`. For additional information about viewing and editing local variables, see [Accessing Local Variables](accessing-local-variables.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Memory%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-visual-studio.md b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-visual-studio.md new file mode 100644 index 0000000000..052eeb9865 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-memory--variables--and-registers-in-visual-studio.md @@ -0,0 +1,28 @@ +--- +title: Viewing and Editing Memory and Registers in Visual Studio +description: The procedure covers Viewing and Editing Memory and Registers in Visual Studio. +ms.assetid: BE365305-F1C7-4D29-885A-55D040D5D900 +--- + +# Viewing and Editing Memory and Registers in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +Visual Studio provides several windows that you can use to view local variables, global variables, registers, and arbitrary memory buffers. To open any of the following windows, from the **Debug** menu, choose **Windows**. + +- Locals +- Autos +- Registers +- Watch +- Memory + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20and%20Editing%20Memory%20and%20Registers%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-source-and-assembly-code-in-visual-studio.md b/windows-driver-docs-pr/debugger/viewing-source-and-assembly-code-in-visual-studio.md new file mode 100644 index 0000000000..ed4c6ea432 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-source-and-assembly-code-in-visual-studio.md @@ -0,0 +1,26 @@ +--- +title: Source Code Debugging in Visual Studio +description: The procedure covers Source Code Debugging in Visual Studio. +ms.assetid: C2E5BAA8-913A-4B0E-8ADF-E2758CCFEC84 +--- + +# Source Code Debugging in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +To use source debugging, you must have your compiler or linker create symbol files (.pdb files) when the binaries are built. These symbol files show the debugger how the binary instructions correspond to the source lines. Also, the debugger must be able to access the actual source files. For more information, see [Source Path](source-path.md). + +When you break in to the target computer, or when code running on the target computer hits a breakpoint, Visual Studio displays source code if it can find the source file. You can step through the source code by choosing one of the **Step** commands from the **Debug** menu. You can also set breakpoints by clicking in the left column of the source window. The following screen shot shows a source code window in the Visual Studio debugger. + +![screen shot of source code in the visual studio debugger](images/sourcecodedebuggingvs01.png) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Source%20Code%20Debugging%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-cdb.md b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-cdb.md new file mode 100644 index 0000000000..4dd9646875 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-cdb.md @@ -0,0 +1,22 @@ +--- +title: Viewing the Call Stack in CDB +description: In CDB, you can view the call stack by entering one of the k (Display Stack Backtrace) commands. +ms.assetid: 4694AFEC-24CF-4331-AA0A-1AE176048295 +--- + +# Viewing the Call Stack in CDB + + +The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, the next function is the function that called the current function, and so on. The call stack that is displayed is based on the current program counter, unless you change the register context. For more information about how to change the register context, see [Changing Contexts](changing-contexts.md). + +In CDB, you can view the call stack by entering one of the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20the%20Call%20Stack%20in%20CDB%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-kd.md b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-kd.md new file mode 100644 index 0000000000..d417fb1fc3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-kd.md @@ -0,0 +1,22 @@ +--- +title: Viewing the Call Stack in KD +description: In KD, you can view the call stack by entering one of the k (Display Stack Backtrace) commands. +ms.assetid: 81F5D9EA-48CE-4F29-B74E-282824E690F6 +--- + +# Viewing the Call Stack in KD + + +The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, the next function is the function that called the current function, and so on. The call stack that is displayed is based on the current program counter, unless you change the register context. For more information about how to change the register context, see [Changing Contexts](changing-contexts.md). + +In KD, you can view the call stack by entering one of the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20the%20Call%20Stack%20in%20KD%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-visual-studio.md b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-visual-studio.md new file mode 100644 index 0000000000..1b7c7044a1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-the-call-stack-in-visual-studio.md @@ -0,0 +1,30 @@ +--- +title: Viewing the Call Stack in Visual Studio +description: The procedure describes how to view the Call Stack in Visual Studio +ms.assetid: 060A2441-C1A7-4485-82E5-2C024E6A3FBE +--- + +# Viewing the Call Stack in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +## Using the Call Stack Window + + +To open the **Call Stack** window in Visual Studio, from the **Debug** menu, choose **Windows>Call Stack**. To set the local context to a particular row in the stack trace display, double click the first column of the row. + +## Viewing the Call Stack by Entering Commands + + +In the Debugger Immediate Window, you can view the call stack by entering one of the [**k (Display Stack Backtrace)**](k--kb--kc--kd--kp--kp--kv--display-stack-backtrace-.md) commands. If the Debugger Immediate window is not already open, from the **Debug** menu, choose **Windows>Immediate**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Viewing%20the%20Call%20Stack%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/viewing-threads-and-processes-in-visual-studio.md b/windows-driver-docs-pr/debugger/viewing-threads-and-processes-in-visual-studio.md new file mode 100644 index 0000000000..cff0e9b97f --- /dev/null +++ b/windows-driver-docs-pr/debugger/viewing-threads-and-processes-in-visual-studio.md @@ -0,0 +1,22 @@ +--- +title: Controlling Threads and Processes in Visual Studio +description: The procedures covers Controlling Threads and Processes in Visual Studio. +ms.assetid: 5A1F9A59-EFCD-4BC9-BDEC-DED11A184651 +--- + +# Controlling Threads and Processes in Visual Studio + + +The procedures shown in this topic require that you have the Windows Driver Kit integrated into Visual Studio. To get the integrated environment, first install Microsoft Visual Studio, and then install the Windows Driver Kit (WDK). For more information, see [Windows Driver Development](https://msdn.microsoft.com/library/windows/hardware/ff557573). + +To open the Threads Window in Visual Studio, from the **Debug** menu, choose **Windows>Threads**. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Controlling%20Threads%20and%20Processes%20in%20Visual%20Studio%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/virtual-and-physical-memory.md b/windows-driver-docs-pr/debugger/virtual-and-physical-memory.md new file mode 100644 index 0000000000..e17bd58de9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/virtual-and-physical-memory.md @@ -0,0 +1,61 @@ +--- +title: Virtual and Physical Memory +description: Virtual and Physical Memory +ms.assetid: 346a46ea-9d44-4e12-8623-d118cd0c7e25 +keywords: ["memory access, virtual and physical memory", "virtual memory access", "physical memory access"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Virtual and Physical Memory + + +## + + +The engine provides a number of methods for reading and writing the virtual and physical memory of a target. + +### Virtual Memory + +When specifying a location in the virtual memory of a target, the target's virtual address space is used. In user-mode debugging, this is the virtual address space of the current process. In kernel-mode debugging, this is the virtual address space of the implicit process. See [Threads and Processes](controlling-threads-and-processes.md) for more information about the current and implicit process. + +The virtual memory (of the target) can be read by using [**ReadVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554359) and written using [**WriteVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff561468). + +Pointers in the target's memory can be read and written by using the convenience methods [**ReadPointersVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554323) and [**WritePointersVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff561451). These methods will automatically convert between the 64-bit pointers used by the engine and the native pointers used by the target. These methods are useful when requesting memory that contains pointers that will be used for subsequent requests -- for example, a pointer to a string. + +The [**SearchVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554747) and [**SearchVirtual2**](https://msdn.microsoft.com/library/windows/hardware/ff554755) methods can be used to search the target's virtual memory for a pattern of bytes. + +The [**FillVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff545395) method can be used to copy a pattern of bytes, multiple times, to the target's virtual memory. + +The target's virtual memory can also be read and written in a way that bypasses the debugger engine's virtual memory cache using the methods [**ReadVirtualUncached**](https://msdn.microsoft.com/library/windows/hardware/ff554361) and [**WriteVirtualUncached**](https://msdn.microsoft.com/library/windows/hardware/ff561473). These uncached versions are useful for reading virtual memory that is inherently volatile, such as memory-mapped device areas, without contaminating or invalidating the cache. Uncached memory access should only be used in situations when it is required, as the performance of uncached access can be significantly lower than cached access. + +The engine provides some convenience methods to read strings from the target's virtual memory. To read a multibyte string from the target, use [**ReadMultiByteStringVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554300) and [**ReadMultiByteStringVirtualWide**](https://msdn.microsoft.com/library/windows/hardware/ff554304). To read a Unicode string from the target, use [**ReadUnicodeStringVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff554351) and [**ReadUnicodeStringVirtualWide**](https://msdn.microsoft.com/library/windows/hardware/ff554357). + +To find information about a memory location, use [**GetOffsetInformation**](https://msdn.microsoft.com/library/windows/hardware/ff548055). Not all of the virtual address space in the target contains valid memory. To find valid memory within a region, use [**GetValidRegionVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff549471). When manually searching for valid memory in a target, the method [**GetNextDifferentlyValidOffsetVirtual**](https://msdn.microsoft.com/library/windows/hardware/ff547847) will find the next location where the validity may change. + +### Physical Memory + +The physical memory can only be directly accessed in kernel-mode debugging. + +Physical memory on the target can be read by using [**ReadPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff554313) and [**ReadPhysical2**](https://msdn.microsoft.com/library/windows/hardware/ff554311), and written by using [**WritePhysical**](https://msdn.microsoft.com/library/windows/hardware/ff561432) and [**WritePhysical2**](https://msdn.microsoft.com/library/windows/hardware/ff561441). + +The [**FillPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff545394) method can be used to copy a pattern of bytes, multiple times, to the target's physical memory. + +An address in the target's virtual address space can be translated to a physical address on the target by using the [**VirtualToPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff560335) method. The system's paging structures used to translate a virtual address to a physical address can be found by using [**GetVirtualTranslationPhysicalOffsets**](https://msdn.microsoft.com/library/windows/hardware/ff549498). + +### Events + +When the virtual or physical memory of the target is changed, the [**IDebugEventCallbacks::ChangeDebuggeeState**](https://msdn.microsoft.com/library/windows/hardware/ff550678) callback method is called. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Virtual%20and%20Physical%20Memory%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/w.md b/windows-driver-docs-pr/debugger/w.md new file mode 100644 index 0000000000..be24fac754 --- /dev/null +++ b/windows-driver-docs-pr/debugger/w.md @@ -0,0 +1,28 @@ +--- +title: W (Windows Debugger Glossary) +description: Glossary page - W +Robots: noindex, nofollow +ms.assetid: 99a1fa3e-f690-458a-afcd-ff54a7c40ba6 +--- + +# W + + +**WdbgExts API** +An interface exposed by the debugger engine for extensions. It contains a subset of the functionality of the debugger engine API and can only be used by extensions. + +**WdbgExts extension** +An extension based on the prototypes in the wdbgexts.h header file. These extensions use the WdbgExts API. + +**WOW64** +An emulation layer in 64-bit Windows that can run 32-bit Windows applications. When debugging a 32-bit application running on 64-bit Windows, it is important to distinguish between the application itself and the WOW64 subsystem. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20W%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/watch-window.md b/windows-driver-docs-pr/debugger/watch-window.md new file mode 100644 index 0000000000..5c6e0d5fd2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/watch-window.md @@ -0,0 +1,121 @@ +--- +title: Using the Watch Window +description: Using the Watch Window +ms.assetid: 233adbcd-c712-4cbb-abe6-5d4e18fa6c27 +keywords: ["debugging information windows, Watch window", "Watch window", "memory, Watch window"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Watch Window + + +## + + +The Watch window displays information about global variables, local variables, and registers. You can customize this window to show the items that you are tracking. + +### Opening the Watch Window + +To open or switch to the Watch window, in the WinDbg window, on the **View** menu, click **Watch**. + +You can also press ALT+2 or click the **Watch (ALT+2)** button on the toolbar: ![screen shot of the watch button](images/tbwatch.png) + +ALT+SHIFT+2 will close the Watch window. + +The following screen shot shows an example of a Watch window. + +![screen shot of the watch window ](images/window-watch.png) + +The Watch window can contain four columns. The **Name** and **Value** columns are always displayed, and the **Type** and **Location** columns are optional. To display the **Type** and **Location** columns, click the **Typecast** and **Locations** buttons, respectively, on the toolbar. + +### Using the Watch Window + +In the Watch window, you can do the following: + +- To add a variable to the Watch window, select the first empty cell in the **Name** column, type the variable name, and then press ENTER. Separate the module name from the variable with an exclamation point (**!**). If you do not specify a module, the current module is used. To enter an address in the **Name** field, the address must begin with a decimal digit (if necessary, use the prefix **0x**). + + If the variable name that you have entered is defined in the current function's scope, its value appears in the **Value** column. If it is not defined, the **Value**column displays "Error: Cannot get value". + + Even if a variable is not defined, it can be useful to add it to the Watch window. If the program counter enters a function in which a variable of this name is defined, its value appears in the window at that time. + +- To remove a variable from the Watch window, double-click its name, press DELETE, and then press ENTER. You can also replace an old name with a new name by double-clicking the old name, typing the new name, and then pressing ENTER. + +- If a variable is a data structure, a check box appears next to its name. To expand and collapse the display of structure members, select or clear the check box. + +- Integers of type **int** are displayed as decimal values; integers of type **UINT** are displayed in the current radix. To change the current radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command in the Debugger Command window. + +- To change the value of a local variable, double-click its **Value** cell. Enter the new value, or edit the old value. (The cut, copy, and paste commands are available to use for editing.) The value that you enter can include any [C++ expression](c---numbers-and-operators.md). After you enter a new value or edit the old value, you can press ENTER to store the new value or press ESC to discard it. If you submit an invalid value, the old value will reappear after you press ENTER. + + Integers of type **int** are displayed as decimal values; integers of type **UINT** are displayed in the current radix. To change the current radix, use the [**n (Set Number Base)**](n--set-number-base-.md) command in the Debugger Command window. + +- The **Type** column (if it is displayed in the Watch window) shows the current data type of each variable. Each variable is displayed in the format that is proper for its own data type. Data structures have their type names in the **Type** column. Other variable types display "Enter new type" in this column. + + If you double-click "Enter new type", you can cast the type by entering a new data type. This cast alters the current display of this variable only in the Watch window; it does not change anything in the debugger or on the target computer. Moreover, if you enter a new value in the **Value** column, the text you enter will be parsed based on the actual type of the symbol, rather than any new type you may have entered in the **Type** column. If you close and reopen the Watch window, you will lose the data type changes. + + You can also enter an extension command in the **Type** column. The debugger will pass the address of the symbol to this extension, and will display the resulting output in a series of collapsible rows beneath the current row. For example, if the symbol in this row is a valid address for a thread environment block, you can enter **!teb** in the **Type** column to run the [**!teb**](-teb.md) extension on this symbol's address. + +- The **Location** column (if it is displayed in the Watch window) shows the offset of each member of a data structure. + +- In addition to variables, you can also monitor the following items in the Watch window: + - Registers. When you add a register to the Watch window, prefix its name with an at sign (**@**). Unlike variables, you cannot change register values through the Watch window. + - Vtables that contain function pointers. When a Vtable appears in the Watch window, you can browse the function entries in the table. If a Vtable is contained in a base class that points to a derived implementation, the notation **\_vtcast\_***Class* is displayed to indicate the members that are being added because of the derived class. These members expand like the derived class type. + - The return values of extension functions, such as \_EFN\_GetPoolData. + +Unlike the [Locals window](locals-window.md), the Watch window is not affected by changes to the [register context](changing-contexts.md#register-context). In the Watch window, you can see and modify only those variables that are defined in the scope of the current program counter. + +If you open a new workspace, the Watch window contents are discarded and replaced with those in the new workspace. + +### Toolbar and Shortcut Menu + +The Watch window has a toolbar that contains two buttons (**Typecast** and **Locations**) and a shortcut menu with additional commands. To access the menu, right-click the title bar of the window or click the icon near the upper-right corner of the window: ![screen shot of the button icon for accessing the watch window toolbar shortcut menu ](images/window-watch-menu.png) + +The toolbar and menu contain the following buttons and commands: + +- (Toolbar and menu) **Typecast** turns the display of the **Type** column on and off. + +- (Toolbar and menu) **Locations** turns the display of the **Location** column on and off. + +- (Menu only) **Display 16-bit values as Unicode** displays Unicode strings in this window. This command turns on and off a global setting that affects the [Locals window](locals-window.md), the Watch window, and debugger command output. This command is equivalent to using the [**.enable\_unicode (Enable Unicode Display)**](-enable-unicode--enable-unicode-display-.md) command. + +- (Menu only) **Always display numbers in default radix** causes integers to be displayed in the default radix instead of always displaying them in decimal format. This command turns on and off a global setting that affects the Locals window, the Watch window, and debugger command output. This command is equivalent to using the [**.force\_radix\_output (Use Radix for Integers)**](-force-radix-output--use-radix-for-integers-.md) command. + **Note**   The **Always display numbers in default radix** command does not affect long integers. Long integers are displayed in decimal format unless the [**.enable\_long\_status (Enable Long Integer Display)**](-enable-long-status--enable-long-integer-display-.md) command is used. The **.enable\_long\_status** command affects the display in the Locals window, the Watch window, and debugger command output. There is no equivalent for this command in the menu in the Watch window. + +   + +- (Menu only) **Open memory window for selected value** opens a new docked Memory window that displays memory starting at the address of the selected expression. + +- (Menu only) **Invoke dt for selected memory value** runs the [**dt (Display Type)**](dt--display-type-.md) command with the selected symbol as its parameter. The result appears in the [Debugger Command window](debugger-command-window.md). The **-n** option is automatically used to differentiate the symbol from a hexadecimal address. No other options are used. Note that the content produced using this menu selection is identical to the content produced when running the **dt** command from the command line, but the format is slightly different. + +- (Menu only) **Toolbar** turns the toolbar on and off. + +- (Menu only) **Dock** or **Undock** causes the window to enter or leave the docked state. + +- (Menu only) **Move to new dock** closes the Watch window and opens it in a new dock. + +- (Menu only) **Set as tab-dock target for window type** is unavailable for the Watch window. This option is only available for [Source](source-window.md) or [Memory](memory-window.md) windows. + +- (Menu only) **Always floating** causes the window to remain undocked even if it is dragged to a docking location. + +- (Menu only) **Move with frame** causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +- (Menu only) **Help** opens this topic in the Debugging Tools for Windows documentation. + +- (Menu only) **Close** closes this window. + +### Additional Information + +For more information about controlling variables and a description of other memory-related commands, see [Reading and Writing Memory](reading-and-writing-memory.md). For more information about registers and their manipulation, see [Viewing and Editing Registers in WinDbg](registers-window.md). For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). For more information about all techniques that you can use to control debugging information windows, see [Using Debugging Information Windows](using-debugging-information-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20Watch%20Window%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-extension-api-overview.md b/windows-driver-docs-pr/debugger/wdbgexts-extension-api-overview.md new file mode 100644 index 0000000000..3d124587fa --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-extension-api-overview.md @@ -0,0 +1,37 @@ +--- +title: WdbgExts Extension API Overview +description: WdbgExts Extension API Overview +ms.assetid: e54d330f-ab48-407f-a9f2-e4a521f5e27b +keywords: ["WdbgExts extensions, overview"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Extension API Overview + + +## + + +Each WdbgExts extension DLL exports one or more functions that are used to implement *extension commands*. These functions are named according to the standard C convention, except that upper-case letters are not permitted. + +The function name and the extension command name are identical, except that the extension command begins with an exclamation point ( **!** ). For example, when you load Myextension.dll into the debugger and then type **!stack** into the Debugger Command window, the debugger looks for an exported function named **stack** in Myextension.dll. + +If Myextension.dll is not already loaded, or if there are other extension commands with the same name in other extension DLLs, you can type **!myextension.stack** into the Debugger Command window to indicate the extension DLL and the extension command in that DLL. + +Each WdbgExts extension DLL also exports a number of *callback functions*. These functions are called by the debugger when the DLL is loaded and when extension commands are used. + +The debugger engine will place a **try / except** block around a call to an extension DLL. This protects the engine from some types of bugs in the extension code. However, since the extension calls are executed in the same thread as the engine, they can still cause the engine to crash. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Extension%20API%20Overview%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-extension-design-guide.md b/windows-driver-docs-pr/debugger/wdbgexts-extension-design-guide.md new file mode 100644 index 0000000000..ae7d9b631f --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-extension-design-guide.md @@ -0,0 +1,41 @@ +--- +title: WdbgExts Extension Design Guide +description: WdbgExts Extension Design Guide +ms.assetid: 8e4a9d26-5b25-4858-b0c0-a63e854e6773 +keywords: ["WdbgExts extensions, design guide"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Extension Design Guide + + +## + + +This section includes: + +[WdbgExts Extension API Overview](wdbgexts-extension-api-overview.md) + +[32-Bit Pointers and 64-Bit Pointers](32-bit-pointers-and-64-bit-pointers.md) + +[Using WdbgExts Extension Callbacks](using-wdbgexts-extension-callbacks.md) + +[Using the DECLARE\_API Macro](using-the-declare-api-macro.md) + +[Writing WdbgExts Extension Code](writing-wdbgexts-extension-code.md) + +[Building WdbgExts Extensions](building-wdbgexts-extensions.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Extension%20Design%20Guide%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-input-and-output.md b/windows-driver-docs-pr/debugger/wdbgexts-input-and-output.md new file mode 100644 index 0000000000..1b27ede063 --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-input-and-output.md @@ -0,0 +1,32 @@ +--- +title: WdbgExts Input and Output +description: WdbgExts Input and Output +ms.assetid: 5648b509-7bdd-4d2a-947f-db55a8c69100 +keywords: ["WdbgExts extensions, input", "WdbgExts extensions, output"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Input and Output + + +This topic provides a brief overview of how input and output can be performed using the WdbgExts API. For an overview of the input and output streams in the [debugger engine](introduction.md#debugger-engine), see [Input and Output](input-and-output.md) in the [Debugger Engine Overview](debugger-engine-overview.md) section of this documentation. + +The function [**dprintf**](https://msdn.microsoft.com/library/windows/hardware/ff542750) works in a way similar to the standard C **printf** function and prints a formatted string to the Debugger Command window or, more precisely, the formatted string is sent to the [output callbacks](using-input-and-output.md#output-callbacks). To read a line of input from the debugger engine, use the function [**GetInputLine**](https://msdn.microsoft.com/library/windows/hardware/ff546905). + +To check for a user-initiated interrupt, use [**CheckControlC**](https://msdn.microsoft.com/library/windows/hardware/ff539072). This function should be used in loops to determine if the user has attempted to cancel execution of an extension. + +For a more powerful input and output API, see [Using Input and Output](using-input-and-output.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Input%20and%20Output%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-memory-access.md b/windows-driver-docs-pr/debugger/wdbgexts-memory-access.md new file mode 100644 index 0000000000..f948cd639a --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-memory-access.md @@ -0,0 +1,60 @@ +--- +title: WdbgExts Memory Access +description: WdbgExts Memory Access +ms.assetid: 7b600d18-343e-4c22-b1e9-5dcc83d88695 +--- + +# WdbgExts Memory Access + + +This topic provides a brief overview of how memory access can be performed using the WdbgExts API. For an overview of memory access in the [debugger engine](introduction.md#debugger-engine), see [Memory](memory.md) in the [Debugger Engine Overview](debugger-engine-overview.md) section of this documentation. + +### Virtual Memory + +The virtual memory of the target can be read by using the [**ReadMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554287) function and written using the [**WriteMemory**](https://msdn.microsoft.com/library/windows/hardware/ff561420) function. Pointers in the target's memory can be read and written by using the [**ReadPointer**](https://msdn.microsoft.com/library/windows/hardware/ff554318), [**ReadPtr**](https://msdn.microsoft.com/library/windows/hardware/ff554330), and [**WritePointer**](https://msdn.microsoft.com/library/windows/hardware/ff561450) functions. + +To search the virtual memory for a pattern of bytes, use the [**SearchMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554742) function. + +The [**TranslateVirtualToPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff558914) function can be used to convert a virtual memory address to a physical memory address. + +The [**Disasm**](https://msdn.microsoft.com/library/windows/hardware/ff541945) function can be used to disassemble a single assembly instruction on the target. + +To check the low 4 GB of memory for corruption when using physical address extension (PAE), use the [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operation [**IG\_LOWMEM\_CHECK**](https://msdn.microsoft.com/library/windows/hardware/ff550931). + +### Physical Memory + +Physical memory can only be directly accessed in kernel-mode debugging. + +The physical memory on the target can be read by using the [**ReadPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff554310) and [**ReadPhysicalWithFlags**](https://msdn.microsoft.com/library/windows/hardware/ff554315) functions, and written by using the [**WritePhysical**](https://msdn.microsoft.com/library/windows/hardware/ff561432) and [**WritePhysicalWithFlags**](https://msdn.microsoft.com/library/windows/hardware/ff561448) functions. + +To search the physical memory for pointers to locations within a specified range, use the [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operation [**IG\_POINTER\_SEARCH\_PHYSICAL**](https://msdn.microsoft.com/library/windows/hardware/ff550935). + +### Other Data Spaces + +In kernel-mode debugging, it is possible to read and write data to a variety of data spaces in addition to the main memory. The following data spaces can be accessed: + +Control-Space Memory +The functions [**ReadControlSpace**](https://msdn.microsoft.com/library/windows/hardware/ff553527), [**ReadControlSpace64**](https://msdn.microsoft.com/library/windows/hardware/ff553532), [**ReadTypedControlSpace32**](https://msdn.microsoft.com/library/windows/hardware/ff554339), and [**ReadTypedControlSpace64**](https://msdn.microsoft.com/library/windows/hardware/ff554341) will read data from a control space. The [**WriteControlSpace**](https://msdn.microsoft.com/library/windows/hardware/ff561375) function will write data to a control space. + +I/O Memory +The functions [**ReadIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff553574), [**ReadIoSpace64**](https://msdn.microsoft.com/library/windows/hardware/ff553577), **ReadIoSpace64**, [**ReadIoSpaceEx64**](https://msdn.microsoft.com/library/windows/hardware/ff553583) will read data from system I/O memory and bus I/O memory. The functions [**WriteIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff561406), [**WriteIoSpace64**](https://msdn.microsoft.com/library/windows/hardware/ff561408), [**WriteIoSpaceEx**](https://msdn.microsoft.com/library/windows/hardware/ff561413), and [**WriteIoSpaceEx64**](https://msdn.microsoft.com/library/windows/hardware/ff561414) will write data to system I/O memory and bus I/O memory. + +Model Specific Register (MSR) +The functions [**ReadMsr**](https://msdn.microsoft.com/library/windows/hardware/ff554289) and [**WriteMsr**](https://msdn.microsoft.com/library/windows/hardware/ff561424) read and write MSRs. + +System Bus +The [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operations [**IG\_GET\_BUS\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff550913) and **IG\_SET\_BUS\_DATA** read and write system bus data. + +### Additional Information + +For a more powerful memory access API, see [Memory Access](memory-access.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Memory%20Access%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-symbols.md b/windows-driver-docs-pr/debugger/wdbgexts-symbols.md new file mode 100644 index 0000000000..27527ea391 --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-symbols.md @@ -0,0 +1,46 @@ +--- +title: WdbgExts Symbols +description: WdbgExts Symbols +ms.assetid: 7e1a1799-b87c-42cb-94ce-fbdc9a5ec973 +keywords: ["WdbgExts extensions, symbols"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Symbols + + +This topic provides a brief overview of how symbols can be manipulated using the WdbgExts API. For an overview of using symbols in the [debugger engine](introduction.md#debugger-engine), see [Symbols](symbols.md) in the [Debugger Engine Overview](debugger-engine-overview.md) section of this documentation. + +To evaluate a MASM or C++ expression, use the functions [**GetExpression**](https://msdn.microsoft.com/library/windows/hardware/ff546683) or [**GetExpressionEx**](https://msdn.microsoft.com/library/windows/hardware/ff546691). + +To read the value of a member in a structure, use the [**GetFieldData**](https://msdn.microsoft.com/library/windows/hardware/ff546743) function or, if, the member contains a primitive value, [**GetFieldValue**](https://msdn.microsoft.com/library/windows/hardware/ff546781) can be used. To determine the size of an instance of a symbol in the target's memory, use the [**GetTypeSize**](https://msdn.microsoft.com/library/windows/hardware/ff549446) function. + +To locate the offset of a member in a structure, use the [**GetFieldOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546758) function. + +To read multiple members in a structure, first use the [**InitTypeRead**](https://msdn.microsoft.com/library/windows/hardware/ff550953) function to initialize the structure. Then, you can use the [**ReadField**](https://msdn.microsoft.com/library/windows/hardware/ff553539) function to read the members with size less than or equal to 8 bytes one at a time. For structure addresses in physical memory, use the [**InitTypeReadPhysical**](https://msdn.microsoft.com/library/windows/hardware/ff550957) function instead of **InitTypeRead**. + +There are two functions that you can use for iterating over linked lists. For doubly-linked lists that use the LIST\_ENTRY32 or LIST\_ENTRY64 structures, the function [**ReadListEntry**](https://msdn.microsoft.com/library/windows/hardware/ff553585) can be used to find the next and previous entries. The function [**ListType**](https://msdn.microsoft.com/library/windows/hardware/ff551988) will iterate over all the entries in a linked list and call a callback function for each entry. + +To locate a symbol near a specified address in the target's memory, use the [**GetSymbol**](https://msdn.microsoft.com/library/windows/hardware/ff548447) function. + +To delete all the symbol information from the debugger engine's cache, use the [**ReloadSymbols**](https://msdn.microsoft.com/library/windows/hardware/ff554381) function. To read or change the symbol path, which is used to search for symbol files, use the [**GetSetSympath**](https://msdn.microsoft.com/library/windows/hardware/ff548291) function. + +Almost all symbol operations provided by the debugger engine can be executed using the [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operation [**IG\_DUMP\_SYMBOL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff550906). However, while being a very flexible function, it is advanced and we recommend that you use the above simpler functions where applicable. + +### Additional Information + +For a more powerful symbols API, see [Using Symbols](using-symbols.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Symbols%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-target-information.md b/windows-driver-docs-pr/debugger/wdbgexts-target-information.md new file mode 100644 index 0000000000..ac718258f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-target-information.md @@ -0,0 +1,36 @@ +--- +title: WdbgExts Target Information +description: WdbgExts Target Information +ms.assetid: 70b26047-2f3a-4d35-861f-a9ca17d1d5f9 +keywords: ["WdbgExts extensions, target"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Target Information + + +To determine if the target uses 32-bit or 64-bit pointers for memory addresses, use the function [**IsPtr64**](https://msdn.microsoft.com/library/windows/hardware/ff551094). + +For information about the target's operating system, use the [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operation [**IG\_GET\_KERNEL\_VERSION**](https://msdn.microsoft.com/library/windows/hardware/ff550918). To get the total number of processors on the target and find out which one is the current processor, use the function [**GetKdContext**](https://msdn.microsoft.com/library/windows/hardware/ff546962). + +The [**GetDebuggerData**](https://msdn.microsoft.com/library/windows/hardware/ff546573) function returns a KDDEBUGGER\_DATA64 or KDDEBUGGER\_DATA32 structure that contains information about the target that the [debugger engine](introduction.md#debugger-engine) has queried or determined during the current session. This information includes certain key target locations and specific status values. + +The debugger caches some information obtained from the target. The function [**GetDebuggerCacheSize**](https://msdn.microsoft.com/library/windows/hardware/ff546568) will return the size of this cache. + +### Additional Information + +For a more powerful target API, see [Target Information](target-information.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Target%20Information%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wdbgexts-threads-and-processes.md b/windows-driver-docs-pr/debugger/wdbgexts-threads-and-processes.md new file mode 100644 index 0000000000..5845871c5d --- /dev/null +++ b/windows-driver-docs-pr/debugger/wdbgexts-threads-and-processes.md @@ -0,0 +1,46 @@ +--- +title: WdbgExts Threads and Processes +description: WdbgExts Threads and Processes +ms.assetid: fa513435-ea91-4dc5-9488-85087d585f96 +keywords: ["WdbgExts extensions, threads", "WdbgExts extensions, processes"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WdbgExts Threads and Processes + + +This topic provides a brief overview of how threads and processes can be manipulated using the WdbgExts API. For an overview of threads and processes in the [debugger engine](introduction.md#debugger-engine), see [Threads and Processes](threads-and-processes.md) in the [Debugger Engine Overview](debugger-engine-overview.md) section of this documentation. + +### Threads + +To get the address of the thread environment block (TEB) that describes the current thread, use the method [**GetTebAddress**](https://msdn.microsoft.com/library/windows/hardware/ff549267). In kernel-mode debugging, the KTHREAD structure is also available to describe a thread. This structure is returned by [**GetCurrentThreadAddr**](https://msdn.microsoft.com/library/windows/hardware/ff545889) (in user-mode debugging, **GetCurrentThreadAddr** returns the address of the TEB). + +The [thread context](scopes-and-symbol-groups.md#thread-context) is the state preserved by Windows when switching threads; it is represented by the CONTEXT structure. This structure varies with the operating system and platform and care should be taken when using the CONTEXT structure. The thread context is returned by the [**GetContext**](https://msdn.microsoft.com/library/windows/hardware/ff545736) function and can be set using the [**SetContext**](https://msdn.microsoft.com/library/windows/hardware/ff556644) function. + +To examine the stack trace for the current thread, use the [**StackTrace**](https://msdn.microsoft.com/library/windows/hardware/ff558794) function. To temporarily change the thread used for examining the stack trace, use the [**SetThreadForOperation**](https://msdn.microsoft.com/library/windows/hardware/ff556830) or [**SetThreadForOperation64**](https://msdn.microsoft.com/library/windows/hardware/ff556832) functions. See [Examining the Stack Trace](examining-the-stack-trace.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation for additional methods for examining the stack. + +To get information about an operating system thread in the target, use the [**Ioctl**](https://msdn.microsoft.com/library/windows/hardware/ff551084) operation [**IG\_GET\_THREAD\_OS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff550924). + +### Processes + +To get the address of the process environment block (PEB) that describes the current process use the method [**GetPebAddress**](https://msdn.microsoft.com/library/windows/hardware/ff548122). In kernel-mode debugging, the KPROCESS structure is also available to describe a process. This structure is returned by [**GetCurrentProcessAddr**](https://msdn.microsoft.com/library/windows/hardware/ff545779) (in user-mode debugging, **GetCurrentProcessAddr** returns the address of the PEB). + +The method [**GetCurrentProcessHandle**](https://msdn.microsoft.com/library/windows/hardware/ff545816) returns the system handle for the current process. + +### Additional Information + +For a more powerful thread manipulation and process manipulation API, see [Controlling Threads and Processes](controlling-threads-and-processes.md) in the [Using the Debugger Engine API](using-the-debugger-engine-api.md) section of this documentation. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WdbgExts%20Threads%20and%20Processes%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/when-to-use-this-technique.md b/windows-driver-docs-pr/debugger/when-to-use-this-technique.md new file mode 100644 index 0000000000..1eb8e9ceef --- /dev/null +++ b/windows-driver-docs-pr/debugger/when-to-use-this-technique.md @@ -0,0 +1,29 @@ +--- +title: When to Use This Technique +description: When to Use This Technique +ms.assetid: 40c9e2aa-35a3-4169-8305-bddc199a5c98 +--- + +# When to Use This Technique + + +## + + +There are several situations in which it is useful, or even necessary, to [control user-mode debugging from the kernel debugger](controlling-the-user-mode-debugger-from-the-kernel-debugger.md): + +- When you need to perform user-mode debugging, but also need control over the Windows kernel that the user-mode target is running on or need to use some kernel-mode debugging features to analyze the problem. + +- When your user-mode target is a Windows process such as CSRSS or WinLogon. For a detailed description of how to debug these targets, see [Debugging CSRSS](debugging-csrss.md) and [Debugging WinLogon](debugging-winlogon.md). + +- When your user-mode target is a service application. For a detailed description of how to debug these targets, see [Debugging a Service Application](debugging-a-service-application.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20When%20to%20Use%20This%20Technique%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-breakpoints-preview.md b/windows-driver-docs-pr/debugger/windbg-breakpoints-preview.md new file mode 100644 index 0000000000..953bda7942 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-breakpoints-preview.md @@ -0,0 +1,43 @@ +--- +title: WinDbg Preview - Breakpoints +description: This section describes how to set and clear breakpoints using the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/15/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Breakpoints + +This section describes how to work with breakpoints using the WinDbg preview debugger. + +## Breakpoints Menu + +Use the breakpoints menu to create new and remove existing breakpoints as well as toggle the initial breakpoint (initial breakpoint is currently kernel only). + +![Breakpoint menu in debugger](images/windbgx-breakpoints-menu.png) + +## Breakpoints Window + +Use the breakpoints window, opened via the View menu, to view, set and clear breakpoints. You can also double-click a breakpoint to open its source file. + +![Breakpoint menu in debugger](images/windbgx-breakpoints-window.png) + +The breakpoint window keep a running total of each time the breakpoint is hit. + + +The general process of working with breakpoints is similar to previous versions of WinDbg. For more information about setting breakpoints, see [Setting Breakpoints in WinDbg](setting-breakpoints-in-windbg.md). + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-command-line-options.md b/windows-driver-docs-pr/debugger/windbg-command-line-options.md new file mode 100644 index 0000000000..e9e7c8cb82 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-command-line-options.md @@ -0,0 +1,264 @@ +--- +title: WinDbg Command-Line Options +description: First-time users of WinDbg should begin with the Debugging Using WinDbg section. +ms.assetid: bd169c73-0a46-41b5-bd7b-71adf7747069 +keywords: ["WinDbg Command-Line Options Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- WinDbg Command-Line Options +api_type: +- NA +--- + +# WinDbg Command-Line Options + + +First-time users of WinDbg should begin with the [Debugging Using WinDbg](debugging-using-windbg.md) section. + +The WinDbg command line uses the following syntax: + +``` +windbg [ -server ServerTransport | -remote ClientTransport ] [-lsrcpath ] + [ -premote SmartClientTransport ] [-?] [-ee {masm|c++}] + [-clines lines] [-b] [-d] [-aExtension] + [-failinc] [-g] [-G] [-hd] [-j] [-n] [-noshell] [-o] + [-Q | -QY] [-QS | -QSY] [-robp] [-secure] [-ses] [-sdce] + [-sicv] [-sins] [-snc] [-snul] [-sup] [-sflags 0xNumber] + [-T Title] [-v] [-log{o|a} LogFile] [-noinh] + [-i ImagePath] [-y SymbolPath] [-srcpath SourcePath] + [-k [ConnectType] | -kl | -kx ExdiOptions] [-c "command"] + [-pb] [-pd] [-pe] [-pr] [-pt Seconds] [-pv] + [-W Workspace] [-WF Filename] [-WX] [-zp PageFile] + [ -p PID | -pn Name | -psn ServiceName | -z DumpFile | executable ] + +windbg -I[S] + +windbg -IU KeyString + +windbg -IA[S] +``` + +Descriptions of the WinDbg command-line options follow. All command-line options are case-sensitive except for **-j**. The initial hyphen can be replaced with a forward-slash (/). + +If the **-remote** or **-server** option is used, it must appear before any other options on the command line. If an *executable* is specified, it must appear last on the command line; any text after the *executable* name is passed to the executable program as its own command-line parameters. + +## Parameters + + + **-server** *ServerTransport* +Creates a debugging server that can be accessed by other debuggers. For an explanation of the possible *ServerTransport* values, see [**Activating a Debugging Server**](activating-a-debugging-server.md). When this parameter is used, it must be the first parameters on the command line. + + **-remote** *ClientTransport* +Creates a debugging client, and connects to a debugging server that is already running. For an explanation of the possible *ClientTransport* values, see [**Activating a Debugging Client**](activating-a-debugging-client.md). When this parameter is used, it must be the first parameters on the command line. + + **-premote** *SmartClientTransport* +Creates a smart client, and connects to a process server that is already running. For an explanation of the possible *SmartClientTransport* values, see [**Activating a Smart Client**](activating-a-smart-client.md). + + **-a** *Extension* +Sets the default extension DLL. The default is kdextx86.dll or kdexts.dll. There must be no space after the "a", and the .dll file name extension must not be included. For details, and other methods of setting this default, see [Loading Debugger Extension DLLs](loading-debugger-extension-dlls.md). + + **-b** +This option is no longer supported. + + **-c "** *command* **"** +Specifies the initial debugger command to run at start-up. This command must be enclosed in quotation marks. Multiple commands can be separated with semicolons. (If you have a long command list, it may be easier to put them in a script and then use the **-c** option with the [**$<, $><, $><, $$>< (Run Script File)**](-----------------------a---run-script-file-.md) command.) + +If you are starting a debugging client, this command must be intended for the debugging server. Client-specific commands, such as **.lsrcpath**, are not allowed. + + **-clines** *lines* +Sets the approximate number of commands in the command history which can be accessed during remote debugging. For details, and for other ways to change this number, see [Using Debugger Commands](using-debugger-commands.md). + + **-d** +(Kernel mode only) After a reboot, the debugger will break into the target computer as soon as a kernel module is loaded. (This break is earlier than the break from the **-b** option.) See [Crashing and Rebooting the Target Computer](crashing-and-rebooting-the-target-computer.md) for details and for other methods of changing this status. + + **-ee** {**masm**|**c++**} +Sets the default expression evaluator. If **masm** is specified, MASM expression syntax will be used. If **c++** is specified, C++ expression syntax will be used. If the **-ee** option is omitted, MASM expression syntax is used as the default. See [Evaluating Expressions](evaluating-expressions.md) for details. + + **-failinc** +Causes the debugger to ignore any questionable symbols. When debugging a user-mode or kernel-mode minidump file, this option will also prevent the debugger from loading any modules whose images can't be mapped. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-g** +(User mode only) Ignores the initial breakpoint in target application. This option will cause the target application to continue running after it is started or WinDbg attaches to it, unless another breakpoint has been set. See [Initial Breakpoint](initial-breakpoint.md) for details. + + **-G** +(User mode only) Ignores the final breakpoint at process termination. Typically, the debugging session ends during the image run-down process. This option will cause the debugging session to end immediately when the child terminates. This has the same effect as entering the command **sxd epr**. For more information, see [Controlling Exceptions and Events](controlling-exceptions-and-events.md). + + **-hd** +(Windows XP and later, user mode only) Specifies that the debug heap should not be used. + + **-I**\[**S**\] +Installs WinDbg as the postmortem debugger. For details, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md). + +After this action is attempted, a success or failure message is displayed. If **S** is included, this procedure is done silently if it is successful; only failure messages are displayed. + +The **-I** parameter must not be used with any other parameters. This command will not actually start WinDbg, although a WinDbg window may appear for a moment. + + **-IA**\[**S**\] +Associates WinDbg with the file extensions .dmp, .mdmp, and .wew in the registry. After this action is attempted, a success or failure message is displayed. If **S** is included, this procedure is done silently if it is successful; only failure messages are displayed. After this association is made, double-clicking a file with one of these extensions will start WinDbg. + +The **-IA** parameter must not be used with any other parameters. This command will not actually start WinDbg, although a WinDbg window may appear for a moment. + + **-IU** *KeyString* +Registers debugger remoting as an URL type so that users can auto-launch a debugger remote client with an URL. *KeyString* has the format `remdbgeng://RemotingOption`. *RemotingOption* is a string that defines the transport protocol as defined in the topic [**Activating a Debugging Client**](activating-a-debugging-client.md). If this action succeeds, no message is displayed; if it fails, an error message is displayed. + +The **-IU** parameter must not be used with any other parameters. Although a WinDbg window may appear for a moment, this command will not actually start WinDbg. + + **-i** *ImagePath* +Specifies the location of the executables that generated the fault. If the path contains spaces, it should be enclosed in quotation marks. + + **-j** +Allow journaling. + + **-k** \[*ConnectType*\] +(Kernel mode only) Starts a kernel debugging session. For details, see [Live Kernel-Mode Debugging Using WinDbg](performing-kernel-mode-debugging-using-windbg.md). If **-k** is used without any *ConnectType* options following it, it must be the final entry on the command line. + + **-kl** +(Windows XP and later, kernel mode only) Starts a kernel debugging session on the same machine as the debugger. + + **-kx** *ExdiOptions* +(Kernel mode only) Starts a kernel debugging session using an EXDI driver. EXDI drivers are not described in this documentation. If you have an EXDI interface to your hardware probe or hardware simulator, please contact Microsoft for debugging information. + + **-log**{**o**|**a**} *LogFile* +Begins logging information to a log file. If the specified log file already exists, it will be overwritten if **-logo** is used. If **loga** is used, the output will be appended to the file. For more details, see [Keeping a Log File in WinDbg](keeping-a-log-file-in-windbg.md). + + **-lsrcpath** +Sets the local source path for a remote client. This option must follow **-remote** on the command line. + + **-n** +*Noisy symbol load*: Enables verbose output from symbol handler. For details and for other methods of controlling this, see [SYMOPT\_DEBUG](symbol-options.md#symopt-debug). + + **-noinh** +(User mode only) Prevents processes created by the debugger from inheriting handles from the debugger. For other methods of controlling this, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md). + + **-noprio** +Prevents any priority change. This parameter will prevent WinDbg from taking priority for CPU time while active. + + **-noshell** +Prohibits all **.shell** commands. This prohibition will last as long as the debugger is running, even if a new debugging session is begun. For details, and for other ways to disable shell commands, see [Using Shell Commands](using-shell-commands.md). + + **-o** +(User mode only) Debugs all processes launched by the target application (child processes). By default, processes created by the one you are debugging will run as they normally do. + + **-p** *PID* +Specifies the decimal process ID to be debugged. This is used to debug a process that is already running. + + **-pb** +(Windows XP and later, user mode only) Prevents the debugger from requesting an initial break-in when attaching to a target process. This can be useful if the application is already suspended, or if you wish to avoid creating a break-in thread in the target. + + **-pd** +(Windows XP and later, user mode only) Causes the target application not to be terminated at the end of the debugging session. See [Ending a Debugging Session in WinDbg](ending-a-debugging-session-in-windbg.md) for details. + + **-pe** +(Windows XP and later, user mode only) Indicates that the target application is already being debugged. See [Re-attaching to the Target Application](reattaching-to-the-target-application.md) for details. + + **-pn** *Name* +Specifies the name of the process to be debugged. (This name must be unique.) This is used to debug a process that is already running. + + **-pr** +(Windows XP and later, user mode only) Causes the debugger to start the target process running when it attaches to it. This can be useful if the application is already suspended and you wish it to resume execution. + + **-psn** *ServiceName* +Specifies the name of a service contained in the process to be debugged. This is used to debug a process that is already running. + + **-pt** *Seconds* +Specifies the break timeout, in seconds. The default is 30. See [Controlling the Target](controlling-the-target.md) for details. + + **-pv** +(User mode only) Specifies that the debugger should attach to the target process noninvasively. For details, see [Noninvasive Debugging (User Mode)](noninvasive-debugging--user-mode-.md). + + **-Q** +Suppresses the "Save Workspace?" dialog box. Workspaces are not automatically saved. See [Using Workspaces](using-workspaces.md) for details. + + **-QS** +Suppresses the "Reload Source?" dialog box. Source files are not automatically reloaded. + + **-QSY** +Suppresses the "Reload Source?" dialog box and automatically reloads source files. + + **-QY** +Suppresses the "Save Workspace?" dialog box and automatically saves workspaces. See [Using Workspaces](using-workspaces.md) for details. + + **-robp** +This allows CDB to set a breakpoint on a read-only memory page. (The default is for such an operation to fail.) + + **-sdce** +Causes the debugger to display **File access error** messages during symbol load. For details and for other methods of controlling this, see [SYMOPT\_FAIL\_CRITICAL\_ERRORS](symbol-options.md#symopt-fail-critical-errors). + + **-secure** +Activates [Secure Mode](secure-mode.md). + + **-ses** +Causes the debugger to perform a strict evaluation of all symbol files and ignore any questionable symbols. For details and for other methods of controlling this, see [SYMOPT\_EXACT\_SYMBOLS](symbol-options.md#symopt-exact-symbols). + + **-sflags 0x** *Number* +Sets all the symbol handler options at once. *Number* should be a hexadecimal number prefixed with **0x** -- a decimal without the **0x** is permitted, but the symbol options are binary flags and therefore hexadecimal is recommended. This option should be used with care, since it will override all the symbol handler defaults. For details, see [Setting Symbol Options](symbol-options.md). + + **-sicv** +Causes the symbol handler to ignore the CV record. For details and for other methods of controlling this, see [SYMOPT\_IGNORE\_CVREC](symbol-options.md#symopt-ignore-cvrec). + + **-sins** +Causes the debugger to ignore the symbol path and executable image path environment variables. For details, see [SYMOPT\_IGNORE\_NT\_SYMPATH](symbol-options.md#symopt-ignore-nt-sympath). + + **-snc** +Causes the debugger to turn off C++ translation. For details and for other methods of controlling this, see [SYMOPT\_NO\_CPP](symbol-options.md#symopt-no-cpp). + + **-snul** +Disables automatic symbol loading for unqualified names. For details and for other methods of controlling this, see [SYMOPT\_NO\_UNQUALIFIED\_LOADS](symbol-options.md#symopt-no-unqualified-loads). + + **-srcpath** *SourcePath* +Specifies the source file search path. Separate multiple paths with a semicolon (**;**). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Source Path](source-path.md). + + **-sup** +Causes the symbol handler to search the public symbol table during every symbol search. For details and for other methods of controlling this, see [SYMOPT\_AUTO\_PUBLICS](symbol-options.md#symopt-auto-publics). + + **-T** *Title* +Sets WinDbg window title. + + **-v** +Enables verbose output from debugger. + + **-W** *Workspace* +Loads the given named workspace. If the workspace name contains spaces, enclose it in quotation marks. If no workspace of this name exists, you will be given the option of creating a new workspace with this name or abandoning the load attempt. For details, see [Using Workspaces](using-workspaces.md). + + **-WF** *Filename* +Loads the workspace from the given file. *Filename* should include the file and the extension (usually .wew). If the workspace name contains spaces, enclose it in quotation marks. If no workspace file with this name exists, you will be given the option of creating a new workspace file with this name or abandoning the load attempt. For details, see [Using Workspaces](using-workspaces.md). + + **-WX** +Disables automatic workspace loading. For details, see [Using Workspaces](using-workspaces.md). + + **-y** *SymbolPath* +Specifies the symbol search path. Separate multiple paths with a semicolon (**;**). If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to change this path, see [Symbol Path](symbol-path.md). + + **-z** *DumpFile* +Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several dump files at once by including multiple **-z** options, each followed by a different *DumpFile* value. For details, see [Analyzing a User-Mode Dump File with WinDbg](analyzing-a-user-mode-dump-file-with-windbg.md) or [Analyzing a Kernel-Mode Dump File with WinDbg](analyzing-a-kernel-mode-dump-file-with-windbg.md). + + **-zp** *PageFile* +Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the [**.pagein (Page In Memory)**](-pagein--page-in-memory-.md) command. You cannot use **-zp** with a standard Windows page file -- only specially-modified page files can be used. + + *executable* +Specifies the command line of an executable process. This is used to launch a new process and debug it. This has to be the final item on the command line. All text after the executable name is passed to the executable as its argument string. For details, see [Debugging a User-Mode Process Using WinDbg](debugging-a-user-mode-process-using-windbg.md). + + **-?** +Pops up this HTML Help window. + +When you are running the debugger from the command line, specify arguments for the target application after application's file name. For instance: + +``` +windbg myexe arg1 arg2 +``` + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WinDbg%20Command-Line%20Options%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-command-line-preview.md b/windows-driver-docs-pr/debugger/windbg-command-line-preview.md new file mode 100644 index 0000000000..9cd9d2a119 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-command-line-preview.md @@ -0,0 +1,112 @@ +--- +title: WinDbg Preview - Command line startup options +description: This section covers the command line startup options for the WinDbg Preview debugger. +ms.author: windowsdriverdev +ms.date: 08/17/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Command line startup options + +## Starting WinDbg Preview + +After WinDbg Preview is installed, WinDbgX.exe is available to run from any directory location. + + +## Command line startup options + +``` +WinDbgX [options] +``` + +This following tables summarizes the available command line options. + +**General Options** + +Option | Description +|------ | -----------| +c | Executes a command line after the debugger is attached. +v | Enables verbose output in the debugger. +T | Sets the window title. +? | Displays a summary of commands available. + +**Kernel Options** + +Option | Description +|------ | -----------| +k | Starts a kernel debugging session. +kqm | Starts KD in quiet mode. +kl | Starts a kernel debugging session on the same machine as the debugger. +kx | Starts a kernel debugging session using an EXDI driver. +d | After a reboot, the debugger will break into the target computer as soon as a kernel module is loaded. + + +**User Mode Options** + +Option | Description +|------ | -----------| +o | Debugs all processes launched by the target application (child processes). +g | Ignores the initial breakpoint in target application. +G |Ignores the final breakpoint in target application. +pv | Specifies that the debugger should attach to the target process noninvasively. +hd | Specifies that the debug heap should not be used. +cimp | Specifies that any processes created will use an implicit command-line set by the server instead of a user-given command-line string from the client. + + +**Target Options** + +Option | Description +|------ | -----------| +remote | Connects to a debugging server that is already running +premote | Connects to a process server (dbgsrv) that is already running. +p| Specifies the decimal process ID to be debugged. +tid | Specifies the thread ID of a thread to be resumed when the debugging session is started. +psn | Specifies the name of the service contained in the process to be debugged. This is used to debug a process that is already running. +pn | Specifies the name of the process to be debugged. +z | Specifies the name of a crash dump file to debug. + + +**Symbol Options** + +Option | Description +|------ | -----------| +y | Specifies the symbol path to use +n | Enables verbose output from symbol handler. +i | Sets the image search path to use. +sdce | Causes the debugger to display 'File access error' messages during symbol load. +ses | Causes the debugger to perform a strict evaluation of all symbol files and ignore any questionable symbols. +sicv |Causes the symbol handler to ignore the CV record +sins |Causes the debugger to ignore the symbol path and executable image path environment variables. +snc | Causes the debugger to turn off C++ translation. +snul | Disables automatic symbol loading for unqualified names. +sup | Causes the symbol handler to search the public symbol table during every symbol search +sflags| Sets all the symbol handler options at once + +For general information on the startup parameters, see [WinDbg Command-Line Options](windbg-command-line-options.md). + + +You can use /? to list the supported command line options. + +![Screen shot of command line help output listing about 50 options](images/windbgx-start-up-options.png) + + + +--- + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-data-model-preview.md b/windows-driver-docs-pr/debugger/windbg-data-model-preview.md new file mode 100644 index 0000000000..70f49c8e31 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-data-model-preview.md @@ -0,0 +1,85 @@ +--- +title: WinDbg Preview - Data Model +description: This section describes how to work with the data model menu in the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/10/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +## WinDbg Preview - Data Model + +This section describes how to work with the data model menu in the WinDbg Preview debugger. + +![Screen shot of data model menu in debugger](images/windbgx-data-model-menu.png) + + +### New Model Query + +Use the New Model Query dialog to create a new model query. You can put anything here you'd put into a normal `dx` command. + +For example, specify `Debugger.Sessions` to examine the debugger sessions objects. + +![New data model query dialog box](images/windbgx-data-model-new-model-dialog.png) + +For general information about the debugger objects refer to [dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md). + +Use LINQ queries to dig deeper into the session. This query shows the top 5 processes running the most threads. + +``` +Debugger.Sessions.First().Processes.Select(p => new { Name = p.Name, ThreadCount = p.Threads.Count() }).OrderByDescending(p => p.ThreadCount),5 +``` +![Data model explore window showing process and threads](images/windbgx-data-model-process-threads.png) + + +### Data Model Explorer + +Use the data model explorer to quickly browse every data model object in the `Debugger` namespace. + +![Data model explorer window showing debug object sessions](images/windbgx-data-model-explore-window.png) + + +### Change Query + +Use change query to change the query that is used in the active data model window. + + +### Display Mode + +Use display mode to toggle between grid and hierarchy display mode. You can right-click column headers to hide or show more columns. + +Grid mode can be useful to dig down in the objects. For example, here is the previous top threads query in grid view. + +![Data model explore window showing top threads](images/windbgx-data-model-process-threads-grid.png) + +When you click on any underlined item a new tab is opened and a query is run to display that information. + + +This query shows the devices in the plug and play device tree grouped by the name of the physical device object's driver. + +``` +Debugger.Sessions.First().Devices.DeviceTree.Flatten(n => n.Children).GroupBy(n => n.PhysicalDeviceObject->Driver->DriverName.ToDisplayString()) +``` +![Data model explore window showing plug and play device tree in a grid view](images/windbgx-data-model-pnp-device.png) + +--- +  +## See Also + +[dx (Display Debugger Object Model Expression)](dx--display-visualizer-variables-.md) + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-file-preview.md b/windows-driver-docs-pr/debugger/windbg-file-preview.md new file mode 100644 index 0000000000..a2e7252eea --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-file-preview.md @@ -0,0 +1,77 @@ +--- +title: WinDbg Preview - File Menu +description: This section describes how to use the file menu in the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/04/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - File Menu + +This topic describes how to how to use the file menu. + +### Start debugging + +When you first open the file menu, you'll see *Start debugging* and your recent debugger targets. Use *Start debugging* to configure new and open previous debugger sessions. + +#### Recent + +The recent list contains a list of your recent workspaces and debugger connections. For more information on working settings an workspaces see [WinDbg Preview Setup – Settings and workspaces](windbg-setup-preview.md). + +You can use the right click menu to manage your workspaces, like pinning, renaming and moving them. As well as editing them in notepad. + +![Workspace file right click menu showing open rename edit in notepad pin and remove from list as well as clear unpinned targets](images/windbgx-workspace-right-click.png) + +#### Start a new session + +Use the other tabs in the *Start debugging* section to start a new debugger session, like attaching or launching a process. For more information on starting a new session see [WinDbg Preview - Start a user-mode session](windbg-user-mode-preview.md) +and [WinDbg Preview - Start a kernel mode session](windbg-kernel-mode-preview.md) + + +### Save workspace + +Use *Save workspace* to save the current workspace. + +Session connection information is stored in workspace configuration files. Workspace files are stored with a .debugTarget file extension. + +The default location for workspace files is: + +``` +C:\Users\*UserName*\AppData\Local\DBG\targets +``` + +### Open source file + +Use *Open source file* to open a source file. Do this when you want to work with additional source files that have not been loaded because of code execution. For more information on working with source files, see [Source Code Debugging in WinDbg](source-window.md) + + +### Open script + +Use *Open script* to open an existing Javascript or NatVis script. For more information on working with scripts see [WinDbg Preview - Scripting Menu](windbg-scripting-preview.md). + +### Settings + +Use the settings menu to set the source and symbol path as well as choose the light and dark theme for the debugger. For more information on settings see [WinDbg Preview Setup – settings and workspaces](windbg-setup-preview.md). + + +### About +Use *About* to display build version information for the debugger. You can use also use this screen to view the Microsoft privacy statement. + +--- +  +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-graphical-interface-features.md b/windows-driver-docs-pr/debugger/windbg-graphical-interface-features.md new file mode 100644 index 0000000000..c540ee891c --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-graphical-interface-features.md @@ -0,0 +1,45 @@ +--- +title: WinDbg Graphical Interface Features +description: WinDbg Graphical Interface Features +ms.assetid: 715b0502-6915-402c-aecb-0b762eb7b846 +keywords: ["WinDbg, graphical interface (reference)", "graphical interface, details"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WinDbg Graphical Interface Features + + +## + + +This section discusses the elements of the WinDbg graphical user interface. These elements include the following: + +[File Menu](file-menu.md) + +[Edit Menu](edit-menu.md) + +[View Menu](view-menu.md) + +[Debug Menu](debug-menu.md) + +[Window Menu](window-menu.md) + +[Help Menu](help-menu.md) + +[Toolbar Buttons](toolbar-buttons.md) + +[Shortcut Keys](keyboard-shortcuts.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WinDbg%20Graphical%20Interface%20Features%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-graphical-interface.md b/windows-driver-docs-pr/debugger/windbg-graphical-interface.md new file mode 100644 index 0000000000..b60dff0765 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-graphical-interface.md @@ -0,0 +1,37 @@ +--- +title: Using the WinDbg Graphical Interface +description: This section covers using the WinDbg Graphical Interface +ms.assetid: 15276b1e-e424-4c2a-a33f-3e1e13fda74e +keywords: WinDbg, graphical interface, GUI, graphical interface +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the WinDbg Graphical Interface + + +## + + +This section includes the following topics: + +[Using Debugging Information Windows](using-debugging-information-windows.md) + +[Using Workspaces](using-workspaces.md) + +[Using the Toolbar and Status Bar](using-the-toolbar-and-status-bar.md) + +[Using the Help Documentation](using-the-help-documentation.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Using%20the%20WinDbg%20Graphical%20Interface%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-home-preview.md b/windows-driver-docs-pr/debugger/windbg-home-preview.md new file mode 100644 index 0000000000..ad42dc98f4 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-home-preview.md @@ -0,0 +1,50 @@ +--- +title: WinDbg Preview - Scripting +description: This section describes how to use the home menu in the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/04/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Home Menu + +This topic describes how to work with the home menu. + +![View menu in debugger](images/windbgx-home-menu.png) + + +## Flow Control + +Use the *Flow Control* buttons to break into a connected debugging target, resume code execution on the target and step in to and out of code. + +## End + +Use the *End* buttons to restart, detach and stop debugging. + +## Source Mode + +Use *Source Mode* buttons to toggle between source code and assembly views. + +## Help (Support) + +Use *Help* buttons to do the following: +- Review Help +- Send Feedback (For more information on sending feedback to improve WinDbg, see [Providing feedback](debugging-using-windbg-preview.md#providingfeedback).) + +  +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-install-preview.md b/windows-driver-docs-pr/debugger/windbg-install-preview.md new file mode 100644 index 0000000000..bd0d679ca9 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-install-preview.md @@ -0,0 +1,54 @@ +--- +title: WinDbg Preview - Installation +description: This section describes how to install the WinDbg Preview debugger. +ms.author: windowsdriverdev +ms.date: 08/17/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Installation + + +## Installation + +This section describes how to install the WinDbg Preview debugger. + +The WinDbg Preview debugger is available in the Windows Store. It requires Windows 10 Anniversary Update to install. To install it, open the Windows Store and search for "WinDbg Preview", or click [here]( +https://www.microsoft.com/store/apps/9pgjgd53tn86). + +Once the app is a located, click on it to download and install. + + +## Checking for updates + +1. Open the Store app and click on your account picture next to the search box. + +2. Click on **Downloads and Updates** to check for updates. + +3. On the downloads and updates page, select **Get updates**. + + +## Debugger coexistence + +The WinDbg preview coexists with the classic WinDbg debugger on the same machine, so you can work with both versions at the same time. + + +--- + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-kernel-mode-preview.md b/windows-driver-docs-pr/debugger/windbg-kernel-mode-preview.md new file mode 100644 index 0000000000..e4974df162 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-kernel-mode-preview.md @@ -0,0 +1,43 @@ +--- +title: WinDbg Preview - Starting a kernel mode session +description: This section describes how to how to start a kernel mode session with WinDbg Preview. +ms.author: windowsdriverdev +ms.date: 08/15/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + + +# WinDbg Preview - Starting a kernel mode session + +This topic describes how to start a kernel mode session with WinDbg Preview. + +The process is very similar to how it has been done with previous versions of WinDbg. Select the tab for the type of transport you're using, fill in the required fields, and click OK. + +> [!NOTE] +> Local kernel debugging requires WinDbg Preview to be launched elevated. + +![Start debugging attach to kernel menu showing Net tab](images/windbgx-attach-to-kernel.png) + +The *Paste* tab allows you to paste in custom connection strings. + +If you are not familiar with setting up a debugger kernel mode session, see [Getting Started with WinDbg (Kernel-Mode)](getting-started-with-windbg--kernel-mode-.md) + + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-keyboard-shortcuts-preview.md b/windows-driver-docs-pr/debugger/windbg-keyboard-shortcuts-preview.md new file mode 100644 index 0000000000..0bb862de92 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-keyboard-shortcuts-preview.md @@ -0,0 +1,110 @@ +--- +title: WinDbg Preview - keyboard shortcuts +description: This section provides the keyboard shortcuts for the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/02/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview keyboard shortcuts + +This section summarizes the keyboard shortcuts for the WinDbg preview debugger. + +All of the ribbon menu options are available using the **Alt +** the first letter of the option. For example **Alt + H** to go to the home menu, **Alt + H + P** to view help. + +![Screen shot of home menu showing letters uses for quick keys for ribbon](images/windbgx-ribbon-home-menu-alt-keys.png) + + +### Flow control + +| Keystroke | Description | +| ------------- |-------------------------| + F5 | Continue +F10 | Step over +F11 | Step Into +Shift+F11 | Step out +F7 | Run to line +Ctrl+Shift+I | Set instruction pointer to highlighted line +Ctrl+Break or Alt+Del | Break +Ctrl+Shift+F5 | Restart +Shift+F5 | Stop debugging +Alt+H,D | Detach + + + +### Setup + +| Keystroke | Description | +| ------------- |-------------------------| +F6 | Attach to process +Ctrl+R | Connect to remote +Ctrl+D | Open dump file +Ctrl+K | Attach to kernel debugger +Ctrl+E | Launch process +Ctrl+P | Launch app package + +### Breakpoints + +| Keystroke | Description | +| ------------- |-------------------------| +F9 | Toggle breakpoint on highlighted line +Ctrl+Alt+K | Toggle initial break +Alt+B,A | Add breakpoint + +### Windowing + +| Keystroke | Description | +| ------------- |-------------------------| +Ctrl+Tab | Open window changer +Ctrl+1 | Open/focus on command window +Ctrl+2 | Open/focus on watch window +Ctrl+3 | Open/focus on locals window +Ctrl+4 | Open/focus on registers window +Ctrl+5 | Open/focus on memory window +Ctrl+6 | Open/focus on stack window +Ctrl+7 | Open/focus on disassembly window +Ctrl+8 | Open/focus on breakpoints window +Ctrl+9 | Open/focus on thread window + + +### Scripting + +| Keystroke | Description | +| ------------- |-------------------------| +Ctrl+Shift+O | Open script +Ctrl+Shift+Enter | Execute script +Ctrl+S | Save script +Alt+S,N | New script +Alt+S,U | Unlink script + + +### Stack navigation +| Keystroke | Description | +| ------------- |-------------------------| +Ctrl+↑ / ↓ | Move up/down a stack frame + + +### Help +| Keystroke | Description | +| ------------- |-------------------------| +F1 | Open help file +Shift+F1 | Search selection on MSDN (source window) + + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-preview---software-license-terms.md b/windows-driver-docs-pr/debugger/windbg-preview---software-license-terms.md new file mode 100644 index 0000000000..58ab22d209 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-preview---software-license-terms.md @@ -0,0 +1,80 @@ +--- +title: WinDbg Preview - Software License Terms +description: WinDbg Preview - Software License Terms +ms.assetid: ECDF9741-F8F6-498B-8033-8CB392021BB8 +ms.author: windowsdriverdev +ms.date: 08/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WinDbg Preview - Software License Terms + +## MICROSOFT SOFTWARE LICENSE TERMS +## MICROSOFT WINDBG PREVIEW + +--- + +**IF YOU LIVE IN (OR ARE A BUSINESS WITH YOUR PRINCIPAL PLACE OF BUSINESS IN) THE UNITED STATES, PLEASE READ THE “BINDING ARBITRATION AND CLASS ACTION WAIVER” SECTION BELOW. IT AFFECTS HOW DISPUTES ARE RESOLVED.** + +--- + +These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. + +1. **INSTALLATION AND USE RIGHTS.** + 1. **General.** You may install and run one instance of the software on your Windows 10 devices that are linked to the Microsoft account associated with your Windows Store account. You may not use the software in a live operating environment unless Microsoft permits you to do so under another agreement. + 2. **Included Microsoft Applications.** The software may include other Microsoft applications. These license terms apply to those included applications, if any, unless other license terms are provided with the other Microsoft applications. + 3. **Third Party Software.** The software may include third party applications that Microsoft, not the third party, licenses to you under this agreement. Any included notices for third party applications are for your information only. +2. **PRE-RELEASE SOFTWARE.** The software is a pre-release version. It may not operate correctly. It may be different from the commercially released version. +3. **FEEDBACK.** If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because Microsoft includes your feedback in them. These rights survive this agreement. +4. **DATA COLLECTION.** The software may collect information about you and your use of the software and send that to Microsoft. Microsoft may use this information to provide services and improve Microsoft’s products and services. Your opt-out rights, if any, are described in the product documentation. Some features in the software may enable collection of data from users of your applications that access or use the software. If you use these features to enable data collection in your applications, you must comply with applicable law, including getting any required user consent, and maintain a prominent privacy policy that accurately informs users about how you use, collect, and share their data. You can learn more about Microsoft’s data collection and use in the product documentation and the Microsoft Privacy Statement at https://go.microsoft.com/fwlink/?LinkId=521839. You agree to comply with all applicable provisions of the Microsoft Privacy Statement. +5. **SCOPE OF LICENSE.** The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to): + 1. work around any technical limitations in the software that only allow you to use it in certain ways; + 2. reverse engineer, decompile or disassemble the software; + 3. remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software; + 4. disclose the results of any benchmark tests of the software to any third party without Microsoft’s prior written approval; + 5. use the software for commercial, non-profit, or revenue-generating activities; + 6. use the software in any way that is against the law or to create or propagate malware; or + 7. share, publish, distribute, or lend the software, provide the software as a stand-alone hosted solution for others to use, or transfer the software or this agreement to any third party. +6. **VIDEO CODECS.** THIS PRODUCT IS LICENSED UNDER THE AVC, THE VC-1, AND THE MPEG-4 PART 2 VISUAL PATENT PORTFOLIO LICENSES FOR THE PERSONAL AND NON-COMMERCIAL USE OF A CONSUMER TO (i) ENCODE VIDEO IN COMPLIANCE WITH THE ABOVE STANDARDS (“VIDEO STANDARDS”) OR (ii) DECODE AVC, VC-1, AND MPEG-4 PART 2 VIDEO THAT WAS ENCODED BY A CONSUMER ENGAGED IN A PERSONAL AND NON-COMMERCIAL ACTIVITY OR WAS OBTAINED FROM A VIDEO PROVIDER LICENSED TO PROVIDE SUCH VIDEO. NO LICENSE IS GRANTED OR SHALL BE IMPLIED FOR ANY OTHER USE. ADDITIONAL INFORMATION MAY BE OBTAINED FROM MPEG LA, L.L.C. SEE http://aka.ms/mpegla. +7. **EXPORT RESTRICTIONS.** You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit http://aka.ms/exporting. +8. **SUPPORT SERVICES.** Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind. +9. **UPDATES.** The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices. +10. **BINDING ARBITRATION AND CLASS ACTION WAIVER. This Section applies if you live in (or, if a business, your principal place of business is in) the United States.** If you and Microsoft have a dispute, you and Microsoft agree to try for 60 days to resolve it informally. If you and Microsoft can’t, you and Microsoft agree to **binding individual arbitration before the American Arbitration Association** under the Federal Arbitration Act (“FAA”), and **not to sue in court in front of a judge or jury**. Instead, a neutral arbitrator will decide. **Class action lawsuits, class-wide arbitrations, private attorney-general actions**, and any other proceeding where someone acts in a representative capacity **are not allowed**; nor is combining individual proceedings without the consent of all parties. The complete Arbitration Agreement contains more terms and is at http://aka.ms/arb-agreement-1. You and Microsoft agree to these terms. +11. **ENTIRE AGREEMENT.** This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software. +12. **APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES.** If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration). +13. **CONSUMER RIGHTS; REGIONAL VARIATIONS.** This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state, province, or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state, province, or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: + 1. **Australia.** You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights. + 2. **Canada.** If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software. + 3. **Germany and Austria.** + 1. **Warranty.** The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software. + 2. **Limitation of Liability.** In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law. +Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence. +14. **DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.** +15. **LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES.** +**This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.** +**It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.** +16. **CONFIDENTIAL INFORMATION.** The software, including its user interface, features and documentation, is confidential and proprietary to Microsoft and its suppliers. + 1. **Use.** For five years after installation of the software or its commercial release, whichever is first, you may not disclose confidential information to third parties. You may disclose confidential information only to your employees and consultants who need to know the information. You must have written agreements with them that protect the confidential information at least as much as this agreement. + 2. **Survival.** Your duty to protect confidential information survives this agreement. + 3. **Exclusions.** You may disclose confidential information in response to a judicial or governmental order. You must first give written notice to Microsoft to allow it to seek a protective order or otherwise protect the information. Confidential information does not include information that: + 1. becomes publicly known through no wrongful act; + 2. you received from a third party who did not breach confidentiality obligations to Microsoft or its suppliers; or + 3. you developed independently. + +**Please note: As this software is distributed in Canada, some of the clauses in this agreement are provided below in French.** + +**Remarque: Ce logiciel étant distribué au Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français.** + +**EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection des consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues.** + +**LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices.** + +**Cette limitation concerne:** +- **tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers; et** +- **les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur.** + +**Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre égard.** + +**EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas.** \ No newline at end of file diff --git a/windows-driver-docs-pr/debugger/windbg-scripting-preview.md b/windows-driver-docs-pr/debugger/windbg-scripting-preview.md new file mode 100644 index 0000000000..5fd9357bab --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-scripting-preview.md @@ -0,0 +1,76 @@ +--- +title: WinDbg Preview - Scripting Menu +description: This section describes how to use scripting in the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + + +# WinDbg Preview - Scripting + +This section describes how to how to use the scripting support in the WinDbg Preview. + +![Screen shot of scripting menu in debugger](images/windbgx-javascript-new-script.png) + +The WinDbg Preview script window features basic syntax highlighting, IntelliSense, and error recognition. + +Use the ribbon buttons to: +- Create a new script +- Open an existing script +- Execute a script +- Save a script +- Unlink a script +- Load the JavaScript Provider + +You can also automatically execute scripts by right-clicking in the script window and selecting *Execute Script on Save*. When you successfully load a script, a green check box will appear on the script title bar. If there are errors in the script, a red x will be displayed. + +## JavaScript Scripting + +To start using JavaScript, you must first be debugging a target. When you're ready to start working on your JavaScript, click "Load JavaScript Provider". After that you can create a new JavaScript, by picking between these two types of script templates. + +- **Extension Script** - A script which is designed to act as an extension to the debugger. It manipulates the object model of the debugger and provides continued functionality. No action happens upon hitting the Execute button on the ribbon. + +- **Imperative Script** - A script which is designed to perform an action each and every time the Execute button is clicked on the ribbon. Such a script does not generally modify the object model of the debugger. + +For more information about working with JavaScript, see these topics: + +[JavaScript Debugger Scripting](javascript-debugger-scripting.md) + +[Native Debugger Objects in JavaScript Extensions](native-objects-in-javascript-extensions.md) + +[JavaScript Debugger Example Scripts](javascript-debugger-example-scripts.md) + +## NatVis Scripting + +Use **New Script** > **NatVis** to open the following blank NatVis template. + +``` + + + + +``` + +For more information about working with NatVis, see [Debugger Objects in NatVis](native-debugger-objects-in-natvis.md). + +  +--- + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-setup-preview.md b/windows-driver-docs-pr/debugger/windbg-setup-preview.md new file mode 100644 index 0000000000..93223259f3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-setup-preview.md @@ -0,0 +1,134 @@ +--- +title: WinDbg Preview - Settings and workspaces +description: This section describes how to setup the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/17/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Settings and workspaces + +This section describes how to setup and configure the WinDbg Preview debugger. + + +## Settings + +Use the settings menu to set the source and symbol path as well as choose the light and dark theme for the debugger. + +![Screen shot of feedback hub showing feedback options including the add new feedback button](images/windbgx-settings-menu.png) + +For more information on setting the paths, see [Accessing Symbols for Debugging](accessing-symbols-for-debugging.md) and [Source Code Debugging in WinDbg](source-window.md). + +## Workspaces + +Workspaces allows you to save configuration information in the target connection information file. + +The options in workspaces are saved upon closing the debugger or can be manually saved using *File* -> *Save Workspace*. + +Workspaces are automatically loaded when launching from the recent targets list or they can be manually loaded in the file menu. + +In addition to the target connection information, the following settings are stored in the workspaces file. + +#### General Settings +> [!NOTE] +> This list and format isn't final and is subject to change. + +Setting | Default | Description +--- | --- | --- +FinalBreak |true | If true, ignores the final breakpoint (-g command-line option). +SourceDebugging |true | Toggles between source or assembly mode. +DebugChildProcesses | false| (User mode only) If true will debug child processes launched by the target application. (-o command-line option). +Noninvasive | false | Specifies non-invasive attach (-pv command-line option). +NoDebugHeap | false | Specifies the debug heap should not be used (-hd command-line option). +Verbose | false | When verbose mode is turned on, some display commands (such as register dumping) produce more detailed output. (-v command-line option). +Elevate | - | Used internally by WinDbg - Do not modify. +Restartable | - | Used internally by WinDbg - Do not modify. +UseImplicitCommandLine | false | Use implicit command-line (-cimp command-line option). This starts teh debugger with an implicit command line instead of an explicit process to run. + +For more information about the command line options, see [WinDbg Command-Line Options](windbg-command-line-options.md). + + +#### Symbol Settings + +Setting | Default | Description +--- | --- | --- +SymbolOptionsOverride | 0 | An explicit symbol option mask, in the form of a single hex number. +ShouldOverrideSymbolOptions | false | If set to *true* override all of the symbol options listed below with the provided symbol option mask, described above. +SymOptExactSymbols | false | This option causes the debugger to perform a strict evaluation of all symbol files. +SymOptFailCriticalErrors | false | This symbol option causes file access error dialog boxes to be suppressed. +SymOptIgnoreCvRec | false | This option causes the symbol handler to ignore the CV record in the loaded image header when searching for symbols. +SymOptIgnoreNtSympath | false | This option causes the debugger to ignore the environment variable settings for the symbol path and the executable image path. +SymOptNoCpp | false | This symbol option turns off C++ translation. When this symbol option is set, :: is replaced by __ in all symbols. +SymOptNoUnqualifiedLoads | false | This symbol option disables the symbol handler's automatic loading of modules. When this option is set and the debugger attempts to match a symbol, it will only search modules which have already been loaded. +SymOptAutoPublics | false | This symbol option causes DbgHelp to search the public symbol table in a .pdb file only as a last resort. If any matches are found when searching the private symbol data, the public symbols will not be searched. This improves symbol search speed. +SymOptDebug | false | This symbol option turns on noisy symbol loading. This instructs the debugger to display information about its search for symbols. + +For more information on symbol options, see [Symbol Options](symbol-options.md). + + +#### Window layout settings + + Window layout is saved globally and are not saved in the workspaces file. + + +#### Workspaces XML file + +The workspace and target connection information is stored in XML format. + +The following file, shows an example workspaces configuration file. + +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +Note that this file format will continue to evolve as more features are added to the WinDbg Preview debugger. + + +--- +  +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-user-mode-preview.md b/windows-driver-docs-pr/debugger/windbg-user-mode-preview.md new file mode 100644 index 0000000000..53e437dcd1 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-user-mode-preview.md @@ -0,0 +1,80 @@ +--- +title: WinDbg Preview - Start a user mode session +description: This section describes how to start a user mode session with the WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/04/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - Start a user mode session + +This section describes how to start a user mode session with the WinDbg preview debugger. + +Select *File*, *Start debugging*, and select either of these four options: + +- *Launch Executable* - Starts an executable and attaches to it by browsing for the target. +- *Launch Executable (advanced)* - Starts an executable and attaches to it using a set of dialog boxes with advanced options. +- *Attach to a process* - Attaches to an existing process. +- *Launch App Package* - Launches and attaches to an app package. + +All four options are described here. + + +## Launch Executable + +Use this option to starts an executable and attach to it. + +Browse to the desired executable in the provided file dialog and open it. + + +## Launch Executable (advanced) + +Use this option to start an executable and attach to it it using a set of text boxes with advanced options. + +Specify the following options: +- Path to the executable, such as *C:\Windows\notepad.exe* +- Optional arguments to provide to the executable when launched +- Optional start directory location + +![Launch Executable (advanced) dialog box with advanced options](images/windbgx-launch-executable-advanced.png) + + +## Attach to a process + +Use this option to attach to an existing process. + +Select *Show process from all users* to show additional processes. + +> [!NOTE] +> Items with a UAC shield will need the debugger to be elevated to attach. + +Use the pull down dialog on the *Attach* button to select *non-invasive attach*. + +![Launch Executable (advanced) dialog box with advanced options](images/windbgx-attach-to-a-process.png) + + +## Launch App Package + +Use this option to launch and attach to an app package. Use the search box to locate a specific app or background task. Use the Package Details button to display information about the package. + +![Launch App Package Applications tab showing cal in the search box with three apps listed](images/windbgx-launch-app-package.png) + + +--- + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-view-preview.md b/windows-driver-docs-pr/debugger/windbg-view-preview.md new file mode 100644 index 0000000000..b55c285581 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-view-preview.md @@ -0,0 +1,92 @@ +--- +title: WinDbg Preview - View Menu +description: This section describes how work with the view menu. +ms.author: windowsdriverdev +ms.date: 08/09/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + +# WinDbg Preview - View Menu + +This section describes how work with the view menu in WinDbg Preview. + +![View menu in debugger](images/windbgx-view-menu.png) + +The view menu will open a new Window for each item, or bring focus to the existing Window, if one is already open. + +## Command +The command Window allows you to enter debugger commands. For more information about debugger commands, see [Debugger Commands](debugger-commands.md). + +## Watch + +The watch Window allows you to watch local variables and registers. + +The locals and watch windows are both based off of the data model that is used by the dx command. This means the locals and watch windows will benefit from any NatVis or JavaScript extensions you have loaded, and support full LINQ queries, just like the dx command. For more information about the data model, see [WinDbg Preview - Data Model](windbg-data-model-preview.md). + +## Locals +The locals window displays information about all of the local variables in the current scope. The locals window will highlight values that have changed during the previous code execution. + +![Locals window in debugger](images/windbgx-locals-window.png) + +## Registers + +Registers displays the contents of the processors registers when they are available. For more information about registers, see [Registers](registers.md) and [Viewing and Editing Registers in WinDbg](registers-window.md). + +## Memory + +Use the memory window to display memory locations. In addition to providing a memory address, you can use the Pseudo-Register values such as $scopeip and $eventip to examine memory. Pre-append the @ symbol to use the pseudo-register values in the memory window, for example, `@$scopeip`. For more information, see [Pseudo-Register Syntax](pseudo-register-syntax.md) + + +## Stack + +Use the stack Window to view the current call stack. The stack window provides basic highlighting of the current frame. + +## Disassembly + +The disassembly window highlights the current instruction and retains that position when you scroll. + +![ Disassembly window in debugger](images/windbgx-disassembly.png) + + +## Threads + +The thread window highlights the current thread. + + +## Breakpoints + +Use the breakpoints window to view, enable and clear breakpoints. + +![ Disassembly window in debugger](images/windbgx-breakpoints-window.png) + + +## Logs + + This log is of the WinDbg Preview internals. It can be viewed to monitor long running processes and for troubleshooting the debugger itself. + + You can continue to create a traditional debugger command log, using the .logopen command. For more information on that, see [Keeping a Log File in WinDbg](keeping-a-log-file-in-windbg.md). + +## Reset Windows + +Use this function to reset the debugger windows to their default positions. + + +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windbg-what-is-new-preview.md b/windows-driver-docs-pr/debugger/windbg-what-is-new-preview.md new file mode 100644 index 0000000000..f8617fd780 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windbg-what-is-new-preview.md @@ -0,0 +1,40 @@ +--- +title: WinDbg Preview - What's New +description: This topic provides inofmration on what's new in WinDbg preview debugger. +ms.author: windowsdriverdev +ms.date: 08/17/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +> [!NOTE] +> The information in this topic is preliminary. Updated information will be provided in a later release of the documentation. +> + + +# WinDbg Preview - What's New + +This topic provides information on what's new in the WinDbg Preview debugger. + + +## Initial Release +For information on the initial set of features available in WinDbg Preview, [Debugging Using WinDbg Preview](debugging-using-windbg-preview.md). + + +## Future Releases +We will provide information on the latest features when they are available in this topic in the future. + + +--- +  +## See Also + +[Debugging Using WinDbg Preview](debugging-using-windbg-preview.md) +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Debugging%20Using%20WinDbg%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---automatically-open-disassembly.md b/windows-driver-docs-pr/debugger/window---automatically-open-disassembly.md new file mode 100644 index 0000000000..1b108fb364 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---automatically-open-disassembly.md @@ -0,0 +1,31 @@ +--- +title: Window Automatically Open Disassembly +description: Window Automatically Open Disassembly +ms.assetid: f3fbdb58-e41b-4150-b762-2b8ef2baed55 +keywords: ["Window Automatically Open Disassembly"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Automatically Open Disassembly + + +## + + +Select **Automatically Open Disassembly** on the **Window** menu to cause the [Disassembly window](disassembly-window.md) to open every time WinDbg begins a debugging session. + +If you clear this command, you can still open the Disassembly window by clicking **Disassembly** on the **View** menu, pressing ALT+7, or clicking the **Disassembly (Alt+F7)** button (![screen shot of the disassembly button](images/tbdisasm2.png)) on the toolbar. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Automatically%20Open%20Disassembly%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---close-all-error-windows.md b/windows-driver-docs-pr/debugger/window---close-all-error-windows.md new file mode 100644 index 0000000000..5712e4a2d8 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---close-all-error-windows.md @@ -0,0 +1,29 @@ +--- +title: Window Close All Error Windows +description: Window Close All Error Windows +ms.assetid: 1de8e4f8-926d-434c-8b45-e0d27d5002b1 +keywords: ["Window Close All Error Windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Close All Error Windows + + +## + + +Click **Close All Error Windows** on the **Window** menu to close all error message boxes that have opened from source files that were not found. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Close%20All%20Error%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---close-all-source-windows.md b/windows-driver-docs-pr/debugger/window---close-all-source-windows.md new file mode 100644 index 0000000000..be257b2dfa --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---close-all-source-windows.md @@ -0,0 +1,29 @@ +--- +title: Window Close All Source Windows +description: Window Close All Source Windows +ms.assetid: 855efeeb-9182-43f5-b617-e056a6ad4bb7 +keywords: ["Window Close All Source Windows"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Close All Source Windows + + +## + + +Click **Close All Source Windows** on the **Window** menu to close all [Source windows](source-window.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Close%20All%20Source%20Windows%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---dock-all.md b/windows-driver-docs-pr/debugger/window---dock-all.md new file mode 100644 index 0000000000..725b489394 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---dock-all.md @@ -0,0 +1,35 @@ +--- +title: Window Dock All +description: Window Dock All +ms.assetid: 93c46cf2-d396-4485-a00c-d5540362af83 +keywords: ["Window Dock All", "docking windows, Window Dock All"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Dock All + + +## + + +Click **Dock All** on the **Window** menu to dock all of the floating windows, except for those with **Always floating** selected on their shortcut menus. + +WinDbg automatically positions each floating window. If a window has never been docked before, WinDbg moves it to a new untabbed location. If a window has been docked before, WinDbg moves it to its most recent docking location, which might be either tabbed or untabbed. + +### Additional Information + +For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Dock%20All%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---mdi-emulation.md b/windows-driver-docs-pr/debugger/window---mdi-emulation.md new file mode 100644 index 0000000000..6a6e907135 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---mdi-emulation.md @@ -0,0 +1,32 @@ +--- +title: Window MDI Emulation +description: Window MDI Emulation +ms.assetid: 495faabb-48d1-4d5d-b454-74ecbc200a2e +keywords: ["Window MDI Emulation"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | MDI Emulation + + +Select **MDI Emulation** on the **Window** menu to cause WinDbg to emulate the Multiple Document Interface (MDI) style of windowing. This kind of windowing differs from docking mode because all windows are floating, but floating windows are constrained within the frame window. This behavior emulates the behavior of WinDbg before docking mode was introduced. + +Clear **MDI Emulation** on the **Window** menu to return WinDbg to docking mode. + +### Additional Information + +For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20MDI%20Emulation%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---open-dock.md b/windows-driver-docs-pr/debugger/window---open-dock.md new file mode 100644 index 0000000000..d4ca6d9c7e --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---open-dock.md @@ -0,0 +1,33 @@ +--- +title: Window Open Dock +description: Window Open Dock +ms.assetid: 2cf9d55d-6a4c-45c3-b4c8-e6cb5d12b7a4 +keywords: ["Window Open Dock", "docking windows, Window Open Dock"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Open Dock + + +## + + +Click **Open Dock** on the **Window** menu to create a new dock. A *dock* is an independent window that you can drag debugging information windows to. For more information about docks, see [Creating New Docks](creating-a-new-dock.md). + +### Additional Information + +For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Open%20Dock%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window---undock-all.md b/windows-driver-docs-pr/debugger/window---undock-all.md new file mode 100644 index 0000000000..b143919ea0 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window---undock-all.md @@ -0,0 +1,35 @@ +--- +title: Window Undock All +description: Window Undock All +ms.assetid: 6d3b4704-7681-4b07-a8c6-335660a01ad9 +keywords: ["Window Undock All", "undocked windows, Window Undock All"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window | Undock All + + +## + + +Click **Undock All** on the **Window** menu to change all of the docked windows to floating windows. + +WinDbg returns each docked window to the position that it occupied the last time that it was a floating window. + +### Additional Information + +For more information about docked, tabbed, and floating windows, see [Positioning the Windows](positioning-the-windows.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20|%20Undock%20All%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/window-menu.md b/windows-driver-docs-pr/debugger/window-menu.md new file mode 100644 index 0000000000..1808a70ed3 --- /dev/null +++ b/windows-driver-docs-pr/debugger/window-menu.md @@ -0,0 +1,51 @@ +--- +title: Window Menu +description: Window Menu +ms.assetid: e22fb1ac-a94b-4e37-bf27-1a3516bca8db +keywords: ["Window Menu (complete listing)", "graphical interface, window menu"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Window Menu + + +## + + +This section describes the following commands on the **Window** menu of WinDbg: + +[Window | Close All Source Windows](window---close-all-source-windows.md) + +[Window | Close All Error Windows](window---close-all-error-windows.md) + +[Window | Open Dock](window---open-dock.md) + +[Window | Dock All](window---dock-all.md) + +[Window | Undock All](window---undock-all.md) + +**Window | Cascade Floating Windows** + +**Window | Horizontally Tile Floating Windows** + +**Window | Vertically Tile Floating Windows** + +[Window | MDI Emulation](window---mdi-emulation.md) + +[Window | Automatically Open Disassembly](window---automatically-open-disassembly.md) + +[List of Open Windows](list-of-open-windows.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Window%20Menu%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windows-error-reporting.md b/windows-driver-docs-pr/debugger/windows-error-reporting.md new file mode 100644 index 0000000000..bc8e284945 --- /dev/null +++ b/windows-driver-docs-pr/debugger/windows-error-reporting.md @@ -0,0 +1,22 @@ +--- +title: Windows Error Reporting +description: Windows Error Reporting (WER) is included in Windows Vista and later versions of Windows. +ms.assetid: 1602C45E-AB27-4578-AC78-A1C91D3A207B +--- + +# Windows Error Reporting + + +Windows Error Reporting (WER) is included in Windows Vista and later versions of Windows. You can configure WER to write user-mode dump files when exceptions and other errors occur in user-mode code. For more information, see [Enabling Postmortem Debugging](enabling-postmortem-debugging.md) and [Collecting User-Mode Dumps](http://go.microsoft.com/fwlink/p?LinkID=257798). + +WER replaced Dr. Watson, which was included in Windows XP. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Windows%20Error%20Reporting%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/windows-runtime-debugger-commands.md b/windows-driver-docs-pr/debugger/windows-runtime-debugger-commands.md new file mode 100644 index 0000000000..29b338e63d --- /dev/null +++ b/windows-driver-docs-pr/debugger/windows-runtime-debugger-commands.md @@ -0,0 +1,30 @@ +--- +title: Windows Runtime Debugging +description: You can use the following debugger extensions to debug code that uses data types defined by the Windows Runtime. +ms.assetid: 8E8F6255-D362-4BD0-AE6C-18E2D4DCD1F7 +keywords: ["Windows Runtime", "WinRT", "HSTRING"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Windows Runtime Debugging + + +You can use the following debugger extensions to debug code that uses data types defined by the Windows Runtime. + +- [**!hstring**](-hstring.md) +- [**!hstring2**](-hstring2.md) +- [**!winrterr**](-winrterr.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Windows%20Runtime%20Debugging%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wmi-tracing-extensions--wmitrace-dll-.md b/windows-driver-docs-pr/debugger/wmi-tracing-extensions--wmitrace-dll-.md new file mode 100644 index 0000000000..44db811ada --- /dev/null +++ b/windows-driver-docs-pr/debugger/wmi-tracing-extensions--wmitrace-dll-.md @@ -0,0 +1,29 @@ +--- +title: WMI Tracing Extensions (Wmitrace.dll) +description: WMI Tracing Extensions (Wmitrace.dll) +ms.assetid: 3fa3eabf-72f2-4695-ae7e-4d11cf754927 +keywords: ["WMI tracing extensions (wmitrace.dll)", "wmitrace.dll (WMI tracing extensions)", "extensions, WMI tracing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Tracing Extensions (Wmitrace.dll) + + +## + + +The extension commands for software tracing sessions can be found in Wmitrace.dll, a library of functions designed to use Windows Management Instrumentation (WMI) for event tracing. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20WMI%20Tracing%20Extensions%20%28Wmitrace.dll%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/workspace-contents.md b/windows-driver-docs-pr/debugger/workspace-contents.md new file mode 100644 index 0000000000..6dff3eb3df --- /dev/null +++ b/windows-driver-docs-pr/debugger/workspace-contents.md @@ -0,0 +1,103 @@ +--- +title: Workspace Contents +description: Workspace Contents +ms.assetid: aa0a3bab-2907-4bcf-9a48-5669c423447a +keywords: ["workspaces, contents of workspaces", "workspaces, automatically starting a session"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Workspace Contents + + +## + + +Each workspace preserves the following information about the current debugging session. This information is applied cumulatively, starting with the base workspace and ending with the most recently-loaded workspace. + +- All break and handling information for exceptions and events. For more information about the break and handling information, see Breakpoints in Workspaces. + +- All open source files. If a source file is not found, an error message appears. You can close these error messages individually or by using the [Window | Close All Error Windows](window---close-all-error-windows.md) command. + +- All user-defined aliases. + +Each workspace preserves the following information about the debugger configuration settings. This information is applied cumulatively, starting with the base workspace and ending with the most recently-loaded workspace. + +- The symbol path. + +- The executable image path. + +- The source path. (In remote debugging, the main source path and the local source path are saved.) + +- The current source options that were set with [**l+, l- (Set Source Options)**](l---l---set-source-options-.md). + +- Log file settings. + +- The COM or 1394 kernel connection settings, if the connection was started by using the graphical interface. + +- The most recent paths in each **Open** dialog box (except for the workspace file and text file paths, which are not saved). + +- The current [**.enable\_unicode**](-enable-unicode--enable-unicode-display-.md), [**.force\_radix\_output**](-force-radix-output--use-radix-for-integers-.md), and [**.enable\_long\_status**](-enable-long-status--enable-long-integer-display-.md) settings. + +All default workspaces and named workspaces preserve the following information about the WinDbg graphical interface. This information is loaded cumulatively, starting with the base workspace and ending with the most recently-loaded workspace. + +- The title of the WinDbg window + +- The [Automatically Open Disassembly](window---automatically-open-disassembly.md) setting + +- The default font + +All default workspaces and named workspaces preserve the following information about the WinDbg graphical interface. This information is not applied cumulatively. It depends only on the most recently-loaded workspace. + +- The size and position of the WinDbg window on the desktop. + +- Which debugging information windows are open. + +- The size and position of each open window, including the window's size, its floating or docked status, whether it is tabbed with other windows, and all of the related settings in its shortcut menu. + +- The location of the pane boundary in the [Debugger Command window](debugger-command-window.md) and the word wrap setting in that window. + +- Whether the toolbar and status bar, and the individual toolbars on each debugging information window, are visible. + +- The customization of the [Registers window](registers-window.md). + +- The flags in the [Calls window](calls-window.md), Locals window, and Watch window. + +- The items that were viewed in the Watch window. + +- The cursor location in each [Source window](source-window.md). + +### Named Workspaces + +Named workspaces contain additional information that is not stored in default workspaces. + +This additional information includes information about the current session state. When a named workspace is saved, the current session is saved. If this workspace is later opened, this session is automatically restarted. + +You can start only kernel debugging, dump file debugging, and debugging of spawned user-mode processes in this manner. Remote sessions and user-mode processes that the debugger attached to do not have this session information saved in their workspaces. + +You cannot open this kind of named workspace if another session is already active. + +### Debugging Clients and Workspaces + +When you use WinDbg as a debugging client, its workspace saves only values that you set through the graphical interface. Changes that you make through the Debugger Command window are not saved. (This restriction guarantees that only changes that the local client made are reflected, because the Debugger Command window accepts input from all clients and the debugging server.) For more information, see [Controlling a Remote Debugging Session](controlling-a-remote-debugging-session.md). + +### Breakpoints in Workspaces + +In addition, breakpoint information is saved in workspaces, including the break address and status. Breakpoints that are active when a session ends are active when the next session is started. However, some of these breakpoints might be unresolved if the proper modules have not yet been loaded. + +Breakpoints that you specify by a symbol expression, by a line number, by a numeric address, or by using the mouse in a Source window are all saved in workspaces. Breakpoints that you specify by using the mouse in a Disassembly or Calls window are not saved in workspaces. + +If you are debugging multiple user-mode processes, only breakpoints that are associated with process zero are saved. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Workspace%20Contents%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-an-analysis-extension-to-extend--analyze.md b/windows-driver-docs-pr/debugger/writing-an-analysis-extension-to-extend--analyze.md new file mode 100644 index 0000000000..42c6cdabf6 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-an-analysis-extension-to-extend--analyze.md @@ -0,0 +1,239 @@ +--- +title: Writing an Analysis Extension Plugin to Extend analyze +description: You can extend the capabilities of the analyze debugger command by writing an analysis extension plugin. +ms.assetid: 7648F789-85D5-4247-90DD-2EAA43543483 +--- + +# Writing an Analysis Extension Plugin to Extend !analyze + + +You can extend the capabilities of the [**!analyze**](-analyze.md) debugger command by writing an analysis extension plugin. By providing an analysis extension plugin, you can participate in the analysis of a bug check or an exception in a way that is specific to your own component or application. + +When you write an analysis extension plugin, you also write a metadata file that describes the situations for which you want your plugin to be called. When [**!analyze**](-analyze.md) runs, it locates, loads, and runs the appropriate analysis extension plugins. + +To write an analysis extension plugin and make it available to [**!analyze**](-analyze.md), follow these steps. + +- Create a DLL that exports an [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function. +- Create a metadata file that has the same name as your DLL and an extension of .alz. For example, if your DLL is named MyAnalyzer.dll, your metadata file must be named MyAnalyzer.alz. For information about how to create a metadata file, see [Metadata Files for Analysis Extensions](metadata-files-for-analysis-extensions.md). Place the metadata file in the same directory as your DLL. +- In the debugger, use the [**.extpath**](-extpath--set-extension-path-.md) command to add your directory to the extension file path. For example, if your DLL and metadata file are in the folder named c:\\MyAnalyzer, enter the command **.extpath+ c:\\MyAnalyzer**. + +When the [**!analyze**](-analyze.md) command runs in the debugger, the analysis engine looks in the extension file path for metadata files that have the .alz extension. The analysis engine reads the metadata files to determine which analysis extension plugins should be loaded. For example, suppose the analysis engine is running in response to Bug Check 0xA IRQL\_NOT\_LESS\_OR\_EQUAL, and it reads a metadata file named MyAnalyzer.alz that contains the following entries. + +``` +PluginId MyPlugin +DebuggeeClass Kernel +BugCheckCode 0xA +BugCheckCode 0xE2 +``` + +The entry `BugCheckCode 0x0A` specifies that this plugin wants to participate in the analysis of Bug Check 0xA, so the analysis engine loads MyAnalyzer.dll (which must be in the same directory as MyAnalyzer.alz) and calls its [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function. + +**Note**  The last line of the metadata file must end with a newline character. + +  + +## Skeleton Example + + +Here is a skeleton example that you can use as a starting point. + +1. Build a DLL named MyAnalyzer.dll that exports the [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function shown here. + + ```ManagedCPlusPlus + #include + #define KDEXT_64BIT + #include + #include + #include + + extern "C" __declspec(dllexport) HRESULT _EFN_Analyze(_In_ PDEBUG_CLIENT4 Client, + _In_ FA_EXTENSION_PLUGIN_PHASE CallPhase, _In_ PDEBUG_FAILURE_ANALYSIS2 pAnalysis) + { + HRESULT hr = E_FAIL; + + PDEBUG_CONTROL pControl = NULL; + hr = Client->QueryInterface(__uuidof(IDebugControl), (void**)&pControl); + + if(S_OK == hr && NULL != pControl) + { + IDebugFAEntryTags* pTags = NULL; + pAnalysis->GetDebugFATagControl(&pTags); + + if(NULL != pTags) + { + if(FA_PLUGIN_INITILIZATION == CallPhase) + { + pControl->Output(DEBUG_OUTPUT_NORMAL, "My analyzer: initialization\n"); + } + else if(FA_PLUGIN_STACK_ANALYSIS == CallPhase) + { + pControl->Output(DEBUG_OUTPUT_NORMAL, "My analyzer: stack analysis\n"); + } + else if(FA_PLUGIN_PRE_BUCKETING == CallPhase) + { + pControl->Output(DEBUG_OUTPUT_NORMAL, "My analyzer: prebucketing\n"); + } + else if(FA_PLUGIN_POST_BUCKETING == CallPhase) + { + pControl->Output(DEBUG_OUTPUT_NORMAL, "My analyzer: post bucketing\n"); + FA_ENTRY_TYPE entryType = pTags->GetType(DEBUG_FLR_BUGCHECK_CODE); + pControl->Output(DEBUG_OUTPUT_NORMAL, "The data type for the DEBUG_FLR_BUGCHECK_CODE tag is 0x%x.\n\n", entryType); + } + } + + pControl->Release(); + } + return hr; + } + ``` + +2. Create a metadata file named MyAnalyzer.alz that has the following entries. + + ``` + PluginId MyPlugin + DebuggeeClass Kernel + BugCheckCode 0xE2 + ``` + + **Note**  The last line of the metadata file must end with a newline character. + +   + +3. Establish a kernel-mode debugging session between a host and target computer. + +4. On the host computer, put MyAnalyzer.dll and MyAnalyzer.alz in the folder c:\\MyAnalyzer. + +5. On the host computer, in the debugger, enter these commands. + + **.extpath+ c:\\MyAnalyzer** + + **.crash** + +6. The [**.crash**](-crash--force-system-crash-.md) command generates Bug Check 0xE2 MANUALLY\_INITIATED\_CRASH on the target computer, which causes a break in to the debugger on the host computer. The bug check analysis engine (running in the debugger on the host computer) reads MyAnalyzer.alz and sees that MyAnalyzer.dll is able to participate in analyzing bug check 0xE2. So the analysis engine loads MyAnalyzer.dll and calls its [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function. + + Verify that you see output similar to the following in the debugger. + + ``` + * Bugcheck Analysis * + * * + ******************************************************************************* + + Use !analyze -v to get detailed debugging information. + + BugCheck E2, {0, 0, 0, 0} + + My analyzer: initialization + My analyzer: stack analysis + My analyzer: prebucketing + My analyzer: post bucketing + The data type for the DEBUG_FLR_BUGCHECK_CODE tag is 0x1. + ``` + +The preceding debugger output shows that the analysis engine called the [**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) function four times: once for each phase of the analysis. The analysis engine passes the **\_EFN\_Analyze** function two interface pointers. *Client* is an [**IDebugClient4**](https://msdn.microsoft.com/library/windows/hardware/ff550494) interface, and *pAnalysis* is an [**IDebugFailureAnalysis2**](https://msdn.microsoft.com/library/windows/hardware/jj983405) interface. The code in the preceding skeleton example shows how to obtain two more interface pointers. `Client->QueryInterface` gets an [**IDebugControl**](https://msdn.microsoft.com/library/windows/hardware/ff550508) interface, and `pAnalysis->GetDebugFATagControl` gets an **IDebugFAEntryTags** interface. + +## Failure Analysis Entries, Tags, and Data Types + + +The analysis engine creates a [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object to organize the data related to a particular code failure. A **DebugFailureAnalysis** object has a collection of [failure analysis entries](failure-analysis-entries.md) (FA entries), each of which is represented by an **FA\_ENTRY** structure. An analysis extension plugin uses the **IDebugFailureAnalysis2** interface to get access to this collection of FA entries. Each FA entry has a tag that identifies the kind of information that the entry contains. For example, an FA entry might have the tag **DEBUG\_FLR\_BUGCHECK\_CODE**, which tells us that the entry contains a bug check code. Tags are values in the **DEBUG\_FLR\_PARAM\_TYPE** enumeration (defined in extsfns.h), which is also called the **FA\_TAG** enumeration. + +```ManagedCPlusPlus +typedef enum _DEBUG_FLR_PARAM_TYPE { + ... + DEBUG_FLR_BUGCHECK_CODE, + ... + DEBUG_FLR_BUILD_VERSION_STRING, + ... +} DEBUG_FLR_PARAM_TYPE; + +typedef DEBUG_FLR_PARAM_TYPE FA_TAG; +``` + +Most [FA entries](failure-analysis-entries.md) have an associated data block. The **DataSize** member of the **FA\_ENTRY** structure holds the size of the data block. Some FA entries do not have an associated data block; all the information is conveyed by the tag. In those cases, the **DataSize** member has a value of 0. + +```ManagedCPlusPlus +typedef struct _FA_ENTRY +{ + FA_TAG Tag; + USHORT FullSize; + USHORT DataSize; +} FA_ENTRY, *PFA_ENTRY; +``` + +Each tag has a set of properties: for example, name, description, and data type. A [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object is associated with a [DebugFailureAnalysisTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) object, which contains a collection of tag properties. The following diagram illustrates this association. + +![diagram that shows the analysis engine, a debugfailureanalysis object, and a debugfailureanalysistags object](images/debugfa01.png) + +A [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object has a collection of [FA entries](failure-analysis-entries.md) that belong to a particular analysis session. The associated [DebugFailureAnalysisTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) object has a collection of tag properties that includes only the tags used by that same analysis session. As the preceding diagram shows, the analysis engine has a global tag table that holds limited information about a large set of tags that are generally available for use by analysis sessions. + +Typically most of the tags used by an analysis session are standard tags; that is, the tags are values in the [**FA\_TAG**](https://msdn.microsoft.com/library/windows/hardware/jj991810) enumeration. However, an analysis extension plug-in can create custom tags. An analysis extension plug-in can add an [FA entry](failure-analysis-entries.md) to a [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object and specify a custom tag for the entry. In that case, properties for the custom tag are added to the collection of tag properties in the associated [DebugFailureAnalysisTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) object. + +You can access a [DebugFailureAnalysisTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) through an IDebugFAEntry tags interface. To get a pointer to an IDebugFAEntry interface, call the [**GetDebugFATagControl**](https://msdn.microsoft.com/library/windows/hardware/jj983414) method of the [**IDebugFailureAnalysis2**](https://msdn.microsoft.com/library/windows/hardware/jj983405) interface. + +Each tag has a data type property that you can inspect to determine the data type of the data in a failure analysis entry. A data type is represented by a value in the **FA\_ENTRY\_TYPE** enumeration. + +The following line of code gets the data type of the **DEBUG\_FLR\_BUILD\_VERSION\_STRING** tag. In this case, the data type is **DEBUG\_FA\_ENTRY\_ANSI\_STRING**. In the code, `pAnalysis` is a pointer to an [**IDebugFailureAnalysis2**](https://msdn.microsoft.com/library/windows/hardware/jj983405) interface. + +```ManagedCPlusPlus +IDebugFAEntryTags* pTags = pAnalysis->GetDebugFATagControl(&pTags); + +if(NULL != pTags) +{ + FA_ENTRY_TYPE entryType = pTags->GetType(DEBUG_FLR_BUILD_VERSION_STRING); +} +``` + +If a failure analysis entry has no data block, the data type of the associated tag is **DEBUG\_FA\_ENTRY\_NO\_TYPE**. + +Recall that a [**DebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) object has a collection of [FA entries](failure-analysis-entries.md). To inspect all the FA entries in the collection, use the **NextEntry** method. The following example shows how to iterate through the entire collection of FA entries. Assume that *pAnalysis* is a pointer to an **IDebugFailureAnalysis2** interface. Notice that we get the first entry by passing **NULL** to **NextEntry**. + +```ManagedCPlusPlus +PFA_ENTRY entry = pAnalysis->NextEntry(NULL); + +while(NULL != entry) +{ + // Do something with the entry + + entry = pAnalysis->NextEntry(entry); +} +``` + +A tag can have a name and a description. In the following code, *pAnalysis* is a pointer to an [**IDebugFailureAnalysis**](https://msdn.microsoft.com/library/windows/hardware/jj983405) interface, *pControl* is a pointer to an [**IDebugControl**](https://msdn.microsoft.com/library/windows/hardware/ff550508) interface, and `pTags` is a pointer to an [IDebugFAEntryTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) interface. The code shows how to use the **GetProperties** method to get the name and description of the tag associated with an [FA entry](failure-analysis-entries.md). + +```ManagedCPlusPlus +#define MAX_NAME_LENGTH 64 +#define MAX_DESCRIPTION_LENGTH 512 + +CHAR name[MAX_NAME_LENGTH] = {0}; +ULONG nameSize = MAX_NAME_LENGTH; +CHAR desc[MAX_DESCRIPTION_LENGTH] = {0}; +ULONG descSize = MAX_DESCRIPTION_LENGTH; + +PFA_ENTRY pEntry = pAnalysis->NextEntry(NULL); +pTags->GetProperties(pEntry->Tag, name, &nameSize, desc, &descSize, NULL); +pControl->Output(DEBUG_OUTPUT_NORMAL, "The name is %s\n", name); +pControl->Output(DEBUG_OUTPUT_NORMAL, "The description is %s\n", desc); +``` + +## Related topics + + +[Writing Custom Analysis Debugger Extensions](writing-custom-analysis-debugger-extensions.md) + +[**\_EFN\_Analyze**](https://msdn.microsoft.com/library/windows/hardware/jj983432) + +[Metadata Files for Analysis Extension Plug-ins](metadata-files-for-analysis-extensions.md) + +[**IDebugFailureAnalysis2**](https://msdn.microsoft.com/library/windows/hardware/jj983405) + +[IDebugFAEntryTags](https://msdn.microsoft.com/library/windows/hardware/jj983404) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20an%20Analysis%20Extension%20Plugin%20to%20Extend%20!analyze%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/writing-custom-analysis-debugger-extensions.md b/windows-driver-docs-pr/debugger/writing-custom-analysis-debugger-extensions.md new file mode 100644 index 0000000000..c52669614c --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-custom-analysis-debugger-extensions.md @@ -0,0 +1,25 @@ +--- +title: Writing Custom Analysis Debugger Extensions +description: Writing Custom Analysis Debugger Extensions +ms.assetid: 45D4E287-ACDB-4479-892F-FCE2287758BA +--- + +# Writing Custom Analysis Debugger Extensions + + +## In this section + + +- [Writing an Analysis Extension Plug-in to Extend !analyze](writing-an-analysis-extension-to-extend--analyze.md) +- [Metadata Files for Analysis Extension Plug-ins](metadata-files-for-analysis-extensions.md) +- [Failure Analysis Entries](failure-analysis-entries.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20Custom%20Analysis%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-dbgeng-extension-code.md b/windows-driver-docs-pr/debugger/writing-dbgeng-extension-code.md new file mode 100644 index 0000000000..9c74ac31d2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-dbgeng-extension-code.md @@ -0,0 +1,47 @@ +--- +title: Writing DbgEng Extension Code +description: This section describes writing DbgEng extension code +ms.assetid: b1ee686b-986e-46eb-a4bf-93e2de6d1aeb +keywords: ["DbgEng Extensions, writing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing DbgEng Extension Code + + +## + + +[DbgEng extension](debugger-engine-and-extension-apis.md) commands can include any standard C++ code. They can also include the C++ interfaces that appear in the dbgeng.h header file, in addition to the C functions that appear in the wdbgexts.h header file. + +If you intend to use functions from wdbgexts.h, you need to define KDEXT\_64BIT before wdbgexts.h is included. For example: + +``` +#define KDEXT_64BIT +#include wdbgexts.h +#include dbgeng.h +``` + +For a full list of interfaces in dbgeng.h that can be used in an extension command, see [Debugger Engine Reference](https://msdn.microsoft.com/library/windows/hardware/ff540540). + +For a full list of functions in wdbgexts.h that can be used in an extension command, see [WdbgExts Functions](https://msdn.microsoft.com/library/windows/hardware/ff561258). A number of these functions appear in 32-bit versions and 64-bit versions. Typically, the 64-bit versions end in "64" and the 32-bit versions have no numerical ending -- for example, **ReadIoSpace64** and **ReadIoSpace**. When calling a wdbgexts.h function from a DbgEng extension, you should always use the function name ending in "64". This is because the [debugger engine](introduction.md#debugger-engine) always uses 64-bit pointers internally, regardless of the target platform. + +If you include wdbgexts.h in your DbgEng extension, you should call [**GetWindbgExtensionApis64**](https://msdn.microsoft.com/library/windows/hardware/ff549510) during the initialization of your extension DLL (see [*DebugExtensionInitialize*](https://msdn.microsoft.com/library/windows/hardware/ff540476)). + +**Note**   You must not attempt to call any DbgHelp or ImageHlp routines from any debugger extension. Calling these routines is not supported and may cause a variety of problems. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20DbgEng%20Extension%20Code%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-dbgeng-extensions.md b/windows-driver-docs-pr/debugger/writing-dbgeng-extensions.md new file mode 100644 index 0000000000..f16d39f178 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-dbgeng-extensions.md @@ -0,0 +1,33 @@ +--- +title: Writing DbgEng Extensions +description: Writing DbgEng Extensions +ms.assetid: 5549b684-8417-415b-ba53-54f90f42e316 +keywords: DbgEng Extensions, debugger extensions +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing DbgEng Extensions + + +## + + +This section includes: + +[DbgEng Extension Design Guide](dbgeng-extension-design-guide.md) + +[DbgEng Extension Reference](https://msdn.microsoft.com/library/windows/hardware/ff540395) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20DbgEng%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-engextcpp-extensions.md b/windows-driver-docs-pr/debugger/writing-engextcpp-extensions.md new file mode 100644 index 0000000000..b7e0da5509 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-engextcpp-extensions.md @@ -0,0 +1,39 @@ +--- +title: Writing EngExtCpp Extensions +description: Writing EngExtCpp Extensions +ms.assetid: ac8684f9-26a3-415f-9d96-938ebda29a27 +keywords: ["EngExtCpp extensions, writing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing EngExtCpp Extensions + + +## + + +The EngExtCpp extension library can include any standard C++ code. It can also include the C++ interfaces that appear in the engextcpp.h and dbgeng.h header files, in addition to the C functions that appear in the wdbgexts.h header file. Both dbgeng.h and wdbgexts.h are included from engextcpp.h. + +For a full list of interfaces in dbgeng.h that can be used in an extension command, see [Debugger Engine Reference](https://msdn.microsoft.com/library/windows/hardware/ff540540). + +For a full list of functions in wdbgexts.h that can be used in an extension command, see [WdbgExts Functions](https://msdn.microsoft.com/library/windows/hardware/ff561258). A number of these functions appear in 32-bit versions and 64-bit versions. Typically, the 64-bit versions end in "64" and the 32-bit versions have no numerical ending -- for example, **ReadIoSpace64** and **ReadIoSpace**. When calling a wdbgexts.h function from a DbgEng extension, you should always use the function name ending in "64". This is because the [debugger engine](introduction.md#debugger-engine) always uses 64-bit pointers internally, regardless of the target platform. When including wdbgexts.h, engextcpp.h selects the 64-bit version of the API. The **ExtensionApis** global variable used by the WDbgExts API is automatically initialized on entry to a EngExtCpp method and cleared on exit. + +When an EngExtCpp extension is used with remote DbgEng interfaces, the WDbgExts interfaces will not be available and the **ExtensionApis** structure can be zeroed. If an EngExtCpp extension is expected to function in such an environment, it should avoid using the WDbgExts API. + +**Note**   You must not attempt to call any DbgHelp or ImageHlp routines from any debugger extension. Calling these routines is not supported and may cause a variety of problems. + +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20EngExtCpp%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-new-debugger-extensions.md b/windows-driver-docs-pr/debugger/writing-new-debugger-extensions.md new file mode 100644 index 0000000000..a1b0b33388 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-new-debugger-extensions.md @@ -0,0 +1,37 @@ +--- +title: Writing New Debugger Extensions +description: Writing New Debugger Extensions +ms.assetid: 6a0d3478-1c7a-44e0-8e48-1334de228c64 +keywords: ["extension commands ( commands), writing extensions", "writing extension commands", "dbgeng.h header file, writing extension commands", "wdbgexts.h header file, writing extension commands"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing New Debugger Extensions + + +## + + +You can create your own debugging commands by writing an extension DLL. For example, you might want to write a command to display a complex data structure, or a command that will stop and start the target depending on the value of certain variables or memory locations. + +There are two different types of debugger extensions: + +- *DbgEng extensions*. These are based on the prototypes in the dbgeng.h header file, and also those in the wdbgexts.h header file. + +- *WdbgExts extensions*. These are based on the prototypes in the wdbgexts.h header file alone. + +For information about how to write debugger extensions, see [Writing DbgEng Extensions](writing-dbgeng-extensions.md) and [Writing WdbgExts Extensions](writing-wdbgexts-extensions.md). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20New%20Debugger%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-wdbgexts-extension-code.md b/windows-driver-docs-pr/debugger/writing-wdbgexts-extension-code.md new file mode 100644 index 0000000000..2057349416 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-wdbgexts-extension-code.md @@ -0,0 +1,53 @@ +--- +title: Writing WdbgExts Extension Code +description: Writing WdbgExts Extension Code +ms.assetid: bb37ea19-8355-42f3-aca5-32cc2b3be3b2 +keywords: ["WdbgExts extensions", "extensions, WdbgExts"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing WdbgExts Extension Code + + +## + + +WdbgExts extension commands can call any standard C function, as well as the debugger-related functions that appear in the WdbgExts.h header file. + +The WdbgExts functions are intended for use in debugger extension commands only. They are useful for controlling and inspecting the computer or application that is being debugged. The WdbgExts.h header file should be included by any code that is calling these WdbgExts functions. + +A number of these functions have 32-bit versions as well as 64-bit versions. Typically, the names of the 64-bit WdbgExts functions end in "64," for example **ReadIoSpace64**. The 32-bit versions have no numerical ending, for example, **ReadIoSpace**. If you are using 64-bit pointers, you should use the function name ending in "64"; if you are using 32-bit pointers, you should use the "undecorated" function name. 64-bit pointers are recommended for any extension that you are writing. See [32-Bit Pointers and 64-Bit Pointers](32-bit-pointers-and-64-bit-pointers.md) for details. + +WdbgExts extensions cannot use the C++ interfaces that appear in the DbgEng.h header file. If you wish to use these interfaces, you should write a DbgEng extension or an EngExtCpp extension instead. Both DbgEng extensions and EngExtCpp extensions can use all the interfaces in DbgEng.h as well as those in WdbgExts.h. For details, see [Writing DbgEng Extensions](writing-dbgeng-extensions.md) and [Writing EngExtCpp Extensions](writing-engextcpp-extensions.md). + +**Note**   You must not attempt to call any DbgHelp or ImageHlp routines from a debugger extension. This is not supported and may cause a variety of problems. + +  + +The following topics give an overview of various categories of WdbgExts functions: + +[WdbgExts Input and Output](wdbgexts-input-and-output.md) + +[WdbgExts Memory Access](wdbgexts-memory-access.md) + +[WdbgExts Threads and Processes](wdbgexts-threads-and-processes.md) + +[WdbgExts Symbols](wdbgexts-symbols.md) + +[WdbgExts Target Information](wdbgexts-target-information.md) + +For a full list of these functions, see [WdbgExts Functions](https://msdn.microsoft.com/library/windows/hardware/ff561258). + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20WdbgExts%20Extension%20Code%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/writing-wdbgexts-extensions.md b/windows-driver-docs-pr/debugger/writing-wdbgexts-extensions.md new file mode 100644 index 0000000000..8f37395c01 --- /dev/null +++ b/windows-driver-docs-pr/debugger/writing-wdbgexts-extensions.md @@ -0,0 +1,37 @@ +--- +title: Writing WdbgExts Extensions +description: Writing WdbgExts Extensions +ms.assetid: ac1711d9-66f8-4f6b-89e6-08370c1cdc12 +keywords: ["WdbgExts extensions, writing"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing WdbgExts Extensions + + +## + + +WdbgExts extensions are the original kind of debugger extensions. They are less powerful than DbgEng extensions, but they still offer a wide range of functionality when performing user-mode or kernel-mode debugging on Microsoft Windows. + +If you performed a full install of Debugging Tools for Windows, a sample WdbgExts extension called "simplext" can be found in the sdk\\samples\\simplext subdirectory of the installation directory. + +This section includes: + +[WdbgExts Extension Design Guide](wdbgexts-extension-design-guide.md) + +[WdbgExts Extension Reference](https://msdn.microsoft.com/library/windows/hardware/ff561252) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20Writing%20WdbgExts%20Extensions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/wrmsr--write-msr-.md b/windows-driver-docs-pr/debugger/wrmsr--write-msr-.md new file mode 100644 index 0000000000..cacf9d4b1a --- /dev/null +++ b/windows-driver-docs-pr/debugger/wrmsr--write-msr-.md @@ -0,0 +1,81 @@ +--- +title: wrmsr (Write MSR) +description: The wrmsr command writes a value to a Model-Specific Register (MSR) at the specified address. +ms.assetid: fe90b984-e2d6-4af7-b708-56fbcd2bbadd +keywords: ["wrmsr (Write MSR) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wrmsr (Write MSR) +api_type: +- NA +--- + +# wrmsr (Write MSR) + + +The **wrmsr** command writes a value to a Model-Specific Register (MSR) at the specified address. + +``` +wrmsr Address Value +``` + +## Parameters + + + *Address* +Specifies the address of the MSR. + + *Value* +Specifies the 64-bit hexadecimal value to write to the MSR. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

Kernel mode only

Targets

Live debugging only

Platforms

All

+ +  + +Remarks +------- + +The **wrmsr** command can display MSR's on x86-based, Itanium-based, and x64-based platforms. The MSR definitions are platform-specific. + +## See also + + +[**rdmsr (Read MSR)**](rdmsr--read-msr-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20wrmsr%20%28Write%20MSR%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/wt--trace-and-watch-data-.md b/windows-driver-docs-pr/debugger/wt--trace-and-watch-data-.md new file mode 100644 index 0000000000..87acbaf61c --- /dev/null +++ b/windows-driver-docs-pr/debugger/wt--trace-and-watch-data-.md @@ -0,0 +1,221 @@ +--- +title: wt (Trace and Watch Data) +description: The wt command runs through the whole function and then displays statistics, when you execute this command at the beginning of a function call. +ms.assetid: 2dd62a7f-67d9-4b13-b04e-5cd02e6ef9f0 +keywords: ["wt (Trace and Watch Data) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- wt (Trace and Watch Data) +api_type: +- NA +--- + +# wt (Trace and Watch Data) + + +The **wt** command runs through the whole function and then displays statistics, when you execute this command at the beginning of a function call. + +``` +wt [WatchOptions] [= StartAddress] [EndAddress] +``` + +## Parameters + + + *WatchOptions* +Specifies how to modify the display. You can use any of the following options. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionEffect

-l Depth

(User mode only) Specifies the maximum depth of the calls to display. Any calls that are at least Depth levels deeper than the starting point are executed silently.

-m Module

(User mode only) Restricts the display to code inside the specified module, plus the first level of calls made from that module. You can include multiple -m options to display code from multiple modules and no other modules.

-i Module

(User mode only) Ignores any code within the specified module. You can include multiple -i options to ignore code from multiple modules. If you use a -m option, the debugger ignores all -i options.

-ni

(User mode only) Does not display any entry into code that is being ignored because of an -m or -i option.

-nc

Does not display individual call information.

-ns

Does not display summary information.

-nw

Does not display warnings during the trace.

-oa

(User mode only) Displays the actual address of call sites.

-or

(User mode only) Displays the return register values of the called function, using the default radix as the base.

-oR

(User mode only) Displays the return register values of the called function, in the appropriate type for each return value.

+ +  + + *StartAddress* +Specifies the address where the debugger begins execution. If you do not use *StartAddress*, execution begins at the instruction that the instruction pointer points to. For more information about the syntax, see [Address and Address Range Syntax](address-and-address-range-syntax.md). + + *EndAddress* +Specifies the address where tracing ends. If you do not use *EndAddress*, a single instruction or function call is executed. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live debugging only

Platforms

+User mode: all +Kernel mode: x86-based only
+ +  + +### Additional Information + +For more information about issuing the **wt** command and an overview of related commands, see [Controlling the Target](controlling-the-target.md). + +Remarks +------- + +The **wt** command is useful if you want information about the behavior of a specific function, but you do not want to step through the function. Instead, go to the beginning of that function and then issue the **wt** command. + +If the program counter is at a point that corresponds to a symbol (such as the beginning of a function or entry point into a module), the **wt** command traces until it reaches the current return address. If the program counter is on a **call** instruction, the **wt** command traces until it returns to the current location. This tracing is profiled in the [Debugger Command window](debugger-command-window.md) together with output that describes the various calls that the command encounters. + +If the **wt** command is issued somewhere other than the beginning of a function, the command behaves like the [**p (Step)**](p--step-.md) command. However, if you specify *EndAddress*, execution continues until that address is reached, even if this execution involves many program steps and function calls. + +When you are debugging in source mode, you should trace into the function only to the point where you see the opening bracket of the function body. Then, you can use the **wt** command. (It is typically easier to insert a breakpoint at the first line of the function, or use [Debug | Run to Cursor](debug---run-to-cursor.md), and then use the **wt** command.) + +Because the output from **wt** can be long, you might want to use a log file to record your output. + +The following example shows a typical log file. + +``` +0:000> l+ Source options set to show source lines +Source options are f: + 1/t - Step/trace by source line + 2/l - List source line for LN and prompt + 4/s - List source code at prompt + 8/o - Only show source code at prompt +0:000> p Not yet at the function call: use "p" +> 44: minorVariableOne = 12; +0:000> p +> 45: variableOne = myFunction(2, minorVariable); +0:000> t At the function call: now use "t" +MyModule!ILT+10(_myFunction): +0040100f e9cce60000 jmp MyModule!myFunction (0040f6e0) +0:000> t +> 231: { +0:000> wt At the function beginning: now use "wt" +Tracing MyModule!myFunction to return address 00401137 + + 105 0 [ 0] MyModule!myFunction + 1 0 [ 1] MyModule!ILT+1555(_printf) + 9 0 [ 1] MyModule!printf + 1 0 [ 2] MyModule!ILT+370(__stbuf) + 11 0 [ 2] MyModule!_stbuf + 1 0 [ 3] MyModule!ILT+1440(__isatty) + 14 0 [ 3] MyModule!_isatty + 50 15 [ 2] MyModule!_stbuf + 17 66 [ 1] MyModule!printf + 1 0 [ 2] MyModule!ILT+980(__output) + 59 0 [ 2] MyModule!_output + 39 0 [ 3] MyModule!write_char + 111 39 [ 2] MyModule!_output + 39 0 [ 3] MyModule!write_char + +.... + + 11 0 [ 5] kernel32!__SEH_epilog4 + 54 11675 [ 4] kernel32!ReadFile + 165 11729 [ 3] MyModule!_read + 100 11895 [ 2] MyModule!_filbuf + 91 11996 [ 1] MyModule!fgets +54545 83789 [ 0] MyModule!myFunction + 1 0 [ 1] MyModule!ILT+1265(__RTC_CheckEsp) + 2 0 [ 1] MyModule!_RTC_CheckEsp +54547 83782 [ 0] MyModule!myFunction + +112379 instructions were executed in 112378 events (0 from other threads) + +Function Name Invocations MinInst MaxInst AvgInst +MyModule!ILT+1265(__RTC_CheckEsp) 1 1 1 1 +MyModule!ILT+1440(__isatty) 21 1 1 1 +MyModule!ILT+1540(__ftbuf) 21 1 1 1 +.... +ntdll!memcpy 24 1 40 19 +ntdll!memset 2 29 29 29 + +23 system calls were executed + +Calls System Call + 23 ntdll!KiFastSystemCall +``` + +In the listing of the trace, the first number specifies the number of instructions that were executed, the second number specifies the number of instructions executed by child processes of the function, and the third number (in brackets) specifies the depth of the function in the stack (taking the initial function as zero). The indentation of the function name shows the call depth. + +In the preceding example, **MyModule!myFunction** executes 105 instructions before it calls several subroutines, including **printf** and **fgets**, and then executes 54545 additional instructions after calling those functions, but before issuing a few more calls. However, in the final count, the display shows that **myFunction** executes 112,379 instructions, because this count includes all of the instructions that **myFunction** and its children execute. (The *children* of **myFunction** are functions that are called from **myFunction**, either directly or indirectly.) + +In the preceding example, note also that **ILT+1440 (\_\_isatty)** is called 21 times. In the final count, the summary of this function's behavior shows the number of times that it was called, the smallest number of instructions in any single execution, the largest number of instructions in any single execution, and the average number of instructions per execution. + +If any system calls are made, they appear in the counter and are listed again at the end of the command output. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20wt%20%28Trace%20and%20Watch%20Data%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/x--examine-symbols-.md b/windows-driver-docs-pr/debugger/x--examine-symbols-.md new file mode 100644 index 0000000000..dbceab0926 --- /dev/null +++ b/windows-driver-docs-pr/debugger/x--examine-symbols-.md @@ -0,0 +1,291 @@ +--- +title: x (Examine Symbols) +description: The x command displays the symbols in all contexts that match the specified pattern. +ms.assetid: 8c71c2ca-4a9d-43e4-91b3-f05b5475316d +keywords: ["x (Examine Symbols) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- x (Examine Symbols) +api_type: +- NA +--- + +# x (Examine Symbols) + + +The **x** command displays the symbols in all contexts that match the specified pattern. + +``` +x [Options] Module!Symbol +x [Options] * +``` + +## Parameters + + + *Options* +Specifies symbol searching options. You can use one or more of the following options: + +**/0** +Displays only the address of each symbol. + +**/1** +Displays only the name of each symbol. + +**/2** +Displays only the address and name of each symbol (not the data type). + +**/D** +Displays the output using [Debugger Markup Language](debugger-markup-language-commands.md). + +**/t** +Displays the data type of each symbol, if the data type is known. + +**/v** +Displays the symbol type (local, global, parameter, function, or unknown) of each symbol. This option also displays the size of each symbol. The size of a function symbol is the size of the function in memory. The size of other symbols is the size of the data type that the symbol represents. Size is always measured in bytes and displayed in hexadecimal format. + +**/s** *Size* +Display only those symbols whose size, in bytes, equals the value of *Size*. The *Size* of a function symbol is the size of the function in memory. The *Size* of other symbols is the size of the data type that the symbol represents. Symbols whose size cannot be determined are always displayed. *Size* must be a nonzero integer. + +**/q** +Displays symbol names in quoted format. + +**/p** +Omits the space before the opening parenthesis when the debugger displays a function name and its arguments. This kind of display can make it easier if you are copying function names and arguments from the **x** display to another location. + +**/f** +Displays the data size of a function. + +**/d** +Displays the data size of data. + +**/a** +Sorts the display by address, in ascending order. + +**/A** +Sorts the display by address, in descending order. + +**/n** +Sorts the display by name, in ascending order. + +**/N** +Sorts the display by name, in descending order. + +**/z** +Sorts the display by size, in ascending order. + +**/Z** +Sorts the display by size, in descending order. + + *Module* +Specifies the module to search. This module can be an .exe, .dll, or .sys file. *Module* can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). + + *Symbol* +Specifies a pattern that the symbol must contain. *Symbol* can contain a variety of wildcard characters and specifiers. For more information about the syntax, see [String Wildcard Syntax](string-wildcard-syntax.md). + +Because this pattern is matched to a symbol, the match is not case sensitive, and a single leading underscore (\_) represents any quantity of leading underscores. You can add spaces within *Symbol*, so that you can specify symbol names that contain spaces (such as "operator new" or "Template<A, B>") without using wildcard characters. + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +The following command finds all of the symbols in MyModule that contain the string "spin". + +``` +0:000> x mymodule!*spin* +``` + +The following command quickly locates the "DownloadMinor" and "DownloadMajor" symbols in MyModule. + +``` +0:000> x mymodule!downloadm??or +``` + +You can also show all symbols in the MyModule by using the following command. + +``` +0:000> x mymodule!* +``` + +The preceding commands also force the debugger to reload symbol information from MyModule. If you want to reload the symbols in the module with a minimal display, use the following command. + +``` +0:000> x mymodule!*start* +``` + +A few symbols always contain the string "start". Therefore, the preceding command always displays some output to verify that the command works. But the preceding command avoids the excessive display length of **x mymodule!\***. + +The display shows the starting address of each symbol and the full symbol name. If the symbol is a function name, the display also includes a list of its argument types. If the symbol is a global variable, its current value is displayed. + +There is one other special case of the **x** command. To display the addresses and names of all local variables for the current context, use the following command. + +``` +0:000> x * +``` + +**Note**   In most cases, you cannot access local variables unless private symbols have been loaded. For more information about this situation, see [dbgerr005: Private Symbols Required](dbgerr005--private-symbols-required.md). To display the values of local variables, use the [**dv (Display Local Variables)**](dv--display-local-variables-.md) command. + +  + +The following example illustrates the **/0**, **/1**, and **/2** options. + +``` +0:000:x86> x /0 MyApp!Add* +00b51410 +00b513d0 + +0:000:x86> x /1 MyApp!Add* +MyApp!AddThreeIntegers +MyApp!AddTwoIntegers + +0:000:x86> x /2 MyApp!Add* +00b51410 MyApp!AddThreeIntegers +00b513d0 MyApp!AddTwoIntegers +``` + +The **/0**, **/1**, and **/2** options are useful if you want to use the output of the **x** command as input to the [**.foreach**](-foreach.md) command. + +``` +.foreach ( place { x /0 MyApp!*MySym*} ) { .echo ${place}+0x18 } +``` + +The following example demonstrates the switch **/f** when used to filter functions on the module notepad.exe. + +``` +0:000> x /f /v notepad!*main* +prv func 00000001`00003340 249 notepad!WinMain (struct HINSTANCE__ *, struct HINSTANCE__ *, char *, int) +prv func 00000001`0000a7b0 1c notepad!WinMainCRTStartup$filt$0 (void) +prv func 00000001`0000a540 268 notepad!WinMainCRTStartup (void) +``` + +When you use the **/v** option, the first column of the display shows the symbol type (local, global, parameter, function, or unknown). The second column is the address of the symbol. The third column is the size of the symbol, in bytes. The fourth column shows the module name and symbol name. In some cases, this display is followed by an equal sign (=) and then the data type of the symbol. The source of the symbol (public or full symbol information) is also displayed. + +``` +kd> x /v nt!CmType* +global 806c9e68 0 nt!CmTypeName = struct _UNICODE_STRING [] +global 806c9e68 150 nt!CmTypeName = struct _UNICODE_STRING [42] +global 806c9e68 0 nt!CmTypeName = struct _UNICODE_STRING [] +global 805bd7b0 0 nt!CmTypeString = unsigned short *[] +global 805bd7b0 a8 nt!CmTypeString = unsigned short *[42] +``` + +In the preceding example, the size is given in hexadecimal format, while the data type is given in decimal format. Therefore, in the last line of the preceding example, the data type is an array of 42 pointers to unsigned short integers. The size of this array is 42\*4 = 168, and 168 is displayed in hexadecimal format as 0xA8. + +You can use the **/s***Size* option to display only those symbols whose size, in bytes, is a certain value. For example, you can restrict the command in the preceding example to symbols that represent objects whose size is 0xA8. + +``` +kd> x /v /s a8 nt!CmType* +global 805bd7b0 a8 nt!CmTypeString = unsigned short *[42] +``` + +**Working With Data Types** + +The **/t** option causes the debugger to display information about each symbol's data type. Note that for many symbols, this information is displayed even without the **/t** option. When you use **/t**, such symbols have their data type information displayed twice. + +``` +0:001> x prymes!__n* +00427d84 myModule!__nullstring = 0x00425de8 "(null)" +0042a3c0 myModule!_nstream = 512 +Type information missing error for _nh_malloc +004021c1 myModule!MyStructInstance = struct MyStruct +00427d14 myModule!_NLG_Destination = + +0:001> x /t prymes!__n* +00427d84 char * myModule!__nullstring = 0x00425de8 "(null)" +0042a3c0 int myModule!_nstream = 512 +Type information missing error for _nh_malloc +004021c1 struct MyStruct myModule!MyStructInstance = struct MyStruct +00427d14 myModule!_NLG_Destination = +``` + +The x command will display an instance of a type. + +``` +0:001> x foo!MyClassInstance +00f4f354 foo!MyClassInstance = 0x00f78768 +``` + +The x command does not display anything based on just the name of a type. + +``` +0:001> x foo!MyClass +0:001> +``` + +To display type information using the name of a type, consider using [**dt (Display Type)**](dt--display-type-.md), it provides information for both types and instances of types: + +``` +0:001> dt foo!MyClass + +0x000 IntMemberVariable : Int4B + +0x004 FloatMemberVariable : Float + +0x008 BoolMemberVariable : Bool + +0x00c PtrMemberVariable : Ptr32 MyClass +``` + +**Working With Templates** + +You can use wild cards with the x command to display template classes as shown in this sample. + +``` +0:001> x Fabric!Common::ConfigEntry*TimeSpan? +000007f6`466a2f9c Fabric!Common::ConfigEntry::ConfigEntry (void) +000007f6`466a3020 Fabric!Common::ConfigEntry::~ConfigEntry (void) +``` + +Consider using the [**dt (Display Type)**](dt--display-type-.md) command when working with templates, as the x command does not display individual template class items. + +``` +0:001> dt foo!Common::ConfigEntry + +0x000 __VFN_table : Ptr64 + +0x008 componentConfig_ : Ptr64 Common::ComponentConfig + +0x010 section_ : std::basic_string,std::allocator > + +0x038 key_ : std::basic_string,std::allocator > +``` + +## See also + + +[Verifying Symbols](verifying-symbols.md) + +[**dv (Display Local Variables)**](dv--display-local-variables-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20x%20%28Examine%20Symbols%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/debugger/x64-architecture.md b/windows-driver-docs-pr/debugger/x64-architecture.md new file mode 100644 index 0000000000..5c4d3f4cee --- /dev/null +++ b/windows-driver-docs-pr/debugger/x64-architecture.md @@ -0,0 +1,200 @@ +--- +title: x64 Architecture +description: x64 Architecture +ms.assetid: 6c0d92d5-cb16-4909-bae5-39fc5c15f736 +keywords: ["x64 processor, architecture", "registers, on an x64 processor", "x64 processor, registers"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# x64 Architecture + + +## + + +The x64 architecture is a backwards-compatible extension of x86. It provides a legacy 32-bit mode, which is identical to x86, and a new 64-bit mode. + +The term "x64" includes both AMD 64 and Intel64. The instruction sets are close to identical. + +### Registers + +x64 extends x86's 8 general-purpose registers to be 64-bit, and adds 8 new 64-bit registers. The 64-bit registers have names beginning with "r", so for example the 64-bit extension of **eax** is called **rax**. The new registers are named **r8** through **r15**. + +The lower 32 bits, 16 bits, and 8 bits of each register are directly addressable in operands. This includes registers, like **esi**, whose lower 8 bits were not previously addressable. The following table specifies the assembly-language names for the lower portions of 64-bit registers. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
64-bit registerLower 32 bitsLower 16 bitsLower 8 bits

rax

eax

ax

al

rbx

ebx

bx

bl

rcx

ecx

cx

cl

rdx

edx

dx

dl

rsi

esi

si

sil

rdi

edi

di

dil

rbp

ebp

bp

bpl

rsp

esp

sp

spl

r8

r8d

r8w

r8b

r9

r9d

r9w

r9b

r10

r10d

r10w

r10b

r11

r11d

r11w

r11b

r12

r12d

r12w

r12b

r13

r13d

r13w

r13b

r14

r14d

r14w

r14b

r15

r15d

r15w

r15b

+ +  + +Operations that output to a 32-bit subregister are automatically zero-extended to the entire 64-bit register. Operations that output to 8-bit or 16-bit subregisters are *not* zero-extended (this is compatible x86 behavior). + +The high 8 bits of **ax**, **bx**, **cx**, and **dx** are still addressable as **ah**, **bh**, **ch**, **dh**, but cannot be used with all types of operands. + +The instruction pointer, **eip**, and **flags** register have been extended to 64 bits (**rip** and **rflags**, respectively) as well. + +The x64 processor also provides several sets of floating-point registers: + +- Eight 80-bit x87 registers. + +- Eight 64-bit MMX registers. (These overlap with the x87 registers.) + +- The original set of eight 128-bit SSE registers is increased to sixteen. + +### Calling Conventions + +Unlike the x86, the C/C++ compiler only supports one calling convention on x64. This calling convention takes advantage of the increased number of registers available on x64: + +- The first four integer or pointer parameters are passed in the **rcx**, **rdx**, **r8**, and **r9** registers. + +- The first four floating-point parameters are passed in the first four SSE registers, **xmm0**-**xmm3**. + +- The caller reserves space on the stack for arguments passed in registers. The called function can use this space to spill the contents of registers to the stack. + +- Any additional arguments are passed on the stack. + +- An integer or pointer return value is returned in the **rax** register, while a floating-point return value is returned in **xmm0**. + +- **rax**, **rcx**, **rdx**, **r8**-**r11** are volatile. + +- **rbx**, **rbp**, **rdi**, **rsi**, **r12**-**r15** are nonvolatile. + +The calling convention for C++ is very similar: the **this** pointer is passed as an implicit first parameter. The next three parameters are passed in registers, while the rest are passed on the stack. + +### Addressing Modes + +The addressing modes in 64-bit mode are similar to, but not identical to, x86. + +- Instructions that refer to 64-bit registers are automatically performed with 64-bit precision. (For example **mov rax, \[rbx\]** moves 8 bytes beginning at **rbx** into **rax**.) + +- A special form of the **mov** instruction has been added for 64-bit immediate constants or constant addresses. For all other instructions, immediate constants or constant addresses are still 32 bits. + +- x64 provides a new **rip**-relative addressing mode. Instructions that refer to a single constant address are encoded as offsets from **rip**. For example, the **mov rax, \[***addr***\]** instruction moves 8 bytes beginning at *addr* + **rip** to **rax**. + +Instructions, such as **jmp**, **call**, **push**, and **pop**, that implicitly refer to the instruction pointer and the stack pointer treat them as 64 bits registers on x64. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20x64%20Architecture%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/x64-instructions.md b/windows-driver-docs-pr/debugger/x64-instructions.md new file mode 100644 index 0000000000..19b405d7d2 --- /dev/null +++ b/windows-driver-docs-pr/debugger/x64-instructions.md @@ -0,0 +1,169 @@ +--- +title: x64 Instructions +description: x64 Instructions +ms.assetid: f05cbf3e-001c-43cc-8a53-0e22fd161a53 +keywords: ["x64 processor, instructions"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# x64 Instructions + + +## + + +Most x86 instructions continue to be valid for x64 in 64-bit mode. Some rarely-used operations are no longer supported in 64-bit mode, such as: + +- binary-coded decimal arithmetic instructions: AAA, AAD, AAM, AAS, DAA, DAS + +- BOUND + +- PUSHAD and POPAD + +- most operations that dealt with segment registers, such as PUSH DS and POP DS. (Operations that use the FS or GS segment registers are still valid.) + +The x64 instruction set includes recent additions to the x86, such as SSE 2. Programs compiled for x64 can freely use these instructions. + +### Data Transfer + +The x64 provides new variants of the MOV instruction that can handle 64-bit immediate constants or memory addresses. + + +++++ + + + + + + + + + + + + + + + + + +

MOV

r,#n

r = #n

MOV

rax, m

Move contents at 64-bit address to rax.

MOV

m, rax

Move contents of rax to 64-bit address.

+ +  + +The x64 also provides a new instruction to sign-extend 32-bit operands to 64 bits. + + +++++ + + + + + + + +

MOVSXD

r1, r/m

Move DWORD with sign extension to QWORD.

+ +  + +Ordinary MOV operations into 32-bit subregisters automatically zero extend to 64 bits, so there is no MOVZXD instruction. + +Two SSE instructions can be used to move 128-bit values (such as GUIDs) from memory to an **xmm***n* register or vice versa. + + +++++ + + + + + + + + + + + + +

MOVDQA

r1/m, r2/m

Move 128-bit aligned value to xmmn register, or vice versa.

MOVDQU

r1/m, r2/m

Move 128-bit value (not necessarily aligned) to register, or vice versa.

+ +  + +### Data Conversion + + ++++ + + + + + + + + + + +

CDQE

Convert dword (eax) to qword (rax).

CQO

convert qword (rax) to oword (rdx:rax).

+ +  + +### String Manipulation + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

MOVSQ

Move qword from rsi to rdi.

CMPSQ

Compare qword at rsi with rdi.

SCASQ

Scan qword at rdi. Compares qword at rdi to rax.

LODSQ

Load qword from rsi into rax.

STOSQ

Store qword to rdi from rax.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20x64%20Instructions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/x86-architecture.md b/windows-driver-docs-pr/debugger/x86-architecture.md new file mode 100644 index 0000000000..5554ed6318 --- /dev/null +++ b/windows-driver-docs-pr/debugger/x86-architecture.md @@ -0,0 +1,623 @@ +--- +title: x86 Architecture +description: x86 Architecture +ms.assetid: 42c62647-7c9a-496e-839f-91283db73a29 +keywords: ["x86 processor, architecture", "registers, on an x86 processor", "x86 processor, registers", "x86 processor, calling conventions", "x86 processor, data types"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# x86 Architecture + + +## + + +The Intel x86 processor uses complex instruction set computer (CISC) architecture, which means there is a modest number of special-purpose registers instead of large quantities of general-purpose registers. It also means that complicated special-purpose instructions will predominate. + +The x86 processor traces its heritage at least as far back as the 8-bit Intel 8080 processor. Many peculiarities in the x86 instruction are due to the backward compatibility with that processor (and with its Zilog Z-80 variant). + +Microsoft Win32 uses the x86 processor in *32-bit flat mode*. This documentation will focus only on the flat mode. + +### Registers + +The x86 architecture consists of the following unprivileged integer registers. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

eax

Accumulator

ebx

Base register

ecx

Count register

edx

Double-precision register

esi

Source index register

edi

Destination index register

ebp

Base pointer register

esp

Stack pointer

+ +  + +All integer registers are 32 bit. However, many of them have 16-bit or 8-bit subregisters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

ax

Low 16 bits of eax

bx

Low 16 bits of ebx

cx

Low 16 bits of ecx

dx

Low 16 bits of edx

si

Low 16 bits of esi

di

Low 16 bits of edi

bp

Low 16 bits of ebp

sp

Low 16 bits of esp

al

Low 8 bits of eax

ah

High 8 bits of ax

bl

Low 8 bits of ebx

bh

High 8 bits of bx

cl

Low 8 bits of ecx

ch

High 8 bits of cx

dl

Low 8 bits of edx

dh

High 8 bits of dx

+ +  + +Operating on a subregister affects only the subregister and none of the parts outside the subregister. For example, storing to the **ax** register leaves the high 16 bits of the **eax** register unchanged. + +When using the [**? (Evaluate Expression)**](---evaluate-expression-.md) command, registers should be prefixed with an "at" sign ( **@** ). For example, you should use **? @ax** rather than **? ax**. This ensures that the debugger recognizes **ax** as a register rather than a symbol. + +However, the (@) is not required in the [**r (Registers)**](r--registers-.md) command. For instance, **r ax=5** will always be interpreted correctly. + +Two other registers are important for the processor's current state. + + ++++ + + + + + + + + + + +

eip

instruction pointer

flags

flags

+ +  + +The instruction pointer is the address of the instruction being executed. + +The flags register is a collection of single-bit flags. Many instructions alter the flags to describe the result of the instruction. These flags can then be tested by conditional jump instructions. See [x86 Flags](#x86-flags) for details. + +### Calling Conventions + +The x86 architecture has several different calling conventions. Fortunately, they all follow the same register preservation and function return rules: + +- Functions must preserve all registers, except for **eax**, **ecx**, and **edx**, which can be changed across a function call, and **esp**, which must be updated according to the calling convention. + +- The **eax** register receives function return values if the result is 32 bits or smaller. If the result is 64 bits, then the result is stored in the **edx:eax** pair. + +The following is a list of calling conventions used on the x86 architecture: + +- Win32 (**\_\_stdcall**) + + Function parameters are passed on the stack, pushed right to left, and the callee cleans the stack. + +- Native C++ method call (also known as thiscall) + + Function parameters are passed on the stack, pushed right to left, the "this" pointer is passed in the **ecx** register, and the callee cleans the stack. + +- COM (**\_\_stdcall** for C++ method calls) + + Function parameters are passed on the stack, pushed right to left, then the "this" pointer is pushed on the stack, and then the function is called. The callee cleans the stack. + +- **\_\_fastcall** + + The first two DWORD-or-smaller arguments are passed in the **ecx** and **edx** registers. The remaining parameters are passed on the stack, pushed right to left. The callee cleans the stack. + +- **\_\_cdecl** + + Function parameters are passed on the stack, pushed right to left, and the caller cleans the stack. The **\_\_cdecl** calling convention is used for all functions with variable-length parameters. + +### Debugger Display of Registers and Flags + +Here is a sample debugger register display: + +``` +eax=00000000 ebx=008b6f00 ecx=01010101 edx=ffffffff esi=00000000 edi=00465000 +eip=77f9d022 esp=05cffc48 ebp=05cffc54 iopl=0 nv up ei ng nz na po nc +cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000 efl=00000286 +``` + +In user-mode debugging, you can ignore the **iopl** and the entire last line of the debugger display. + +### x86 Flags + +In the preceding example, the two-letter codes at the end of the second line are *flags*. These are single-bit registers and have a variety of uses. + +The following table lists the x86 flags: + +Flag Code +Flag Name +Value +Flag Status +Status Description +**of** + +Overflow Flag + +0 +1 +**nvov** + +No overflow +Overflow +**df** + +Direction Flag + +0 +1 +**updn** + +Direction up +Direction down +**if** + +Interrupt Flag + +0 +1 +**diei** + +Interrupts disabled +Interrupts enabled +**sf** + +Sign Flag + +0 +1 +**plng** + +Positive (or zero) +Negative +**zf** + +Zero Flag + +0 +1 +**nzzr** + +Nonzero +Zero +**af** + +Auxiliary Carry Flag + +0 +1 +**naac** + +No auxiliary carry +Auxiliary carry +**pf** + +Parity Flag + +0 +1 +**pepo** + +Parity even +Parity odd +**cf** + +Carry Flag + +0 +1 +**nccy** + +No carry +Carry +**tf** + +Trap Flag + +If **tf** equals 1, the processor will raise a STATUS\_SINGLE\_STEP exception after the execution of one instruction. This flag is used by a debugger to implement single-step tracing. It should not be used by other applications. + +**iopl** + +I/O Privilege Level + +This is a two-bit integer, with values between zero and 3. It is used by the operating system to control access to hardware. It should not be used by applications. + +  + +When registers are displayed as a result of some command in the Debugger Command window, it is the *flag status* that is displayed. However, if you want to change a flag using the [**r (Registers)**](r--registers-.md) command, you should refer to it by the *flag code*. + +In the Registers window of WinDbg, the flag code is used to view or alter flags. The flag status is not supported. + +Here is an example. In the preceding register display, the flag status **ng** appears. This means that the sign flag is currently set to 1. To change this, use the following command: + +``` +r sf=0 +``` + +This sets the sign flag to zero. If you do another register display, the **ng** status code will not appear. Instead, the **pl** status code will be displayed. + +The Sign Flag, Zero Flag, and Carry Flag are the most commonly-used flags. + +### Conditions + +A *condition* describes the state of one or more flags. All conditional operations on the x86 are expressed in terms of conditions. + +The assembler uses a one or two letter abbreviation to represent a condition. A condition can be represented by multiple abbreviations. For example, AE ("above or equal") is the same condition as NB ("not below"). The following table lists some common conditions and their meaning. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Condition NameFlagsMeaning

Z

ZF=1

Result of last operation was zero.

NZ

ZF=0

Result of last operation was not zero.

C

CF=1

Last operation required a carry or borrow. (For unsigned integers, this indicates overflow.)

NC

CF=0

Last operation did not require a carry or borrow. (For unsigned integers, this indicates overflow.)

S

SF=1

Result of last operation has its high bit set.

NS

SF=0

Result of last operation has its high bit clear.

O

OF=1

When treated as a signed integer operation, the last operation caused an overflow or underflow.

NO

OF=0

When treated as signed integer operation, the last operation did not cause an overflow or underflow.

+ +  + +Conditions can also be used to compare two values. The **cmp** instruction compares its two operands, and then sets flags as if subtracted one operand from the other. The following conditions can be used to check the result of **cmp** *value1*, *value2*. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Condition NameFlagsMeaning after a CMP operation.

E

ZF=1

value1 == value2.

NE

ZF=0

value1 != value2.

+GE +NL

SF=OF

+value1 >= value2. +Values are treated as signed integers.

+LE +NG

ZF=1 or SF!=OF

value1 <= value2. Values are treated as signed integers.

+G +NLE

ZF=0 and SF=OF

value1 > value2. Values are treated as signed integers.

+L +NGE

SF!=OF

value1 < value2. Values are treated as signed integers.

+AE +NB

CF=0

value1 >= value2. Values are treated as unsigned integers.

+BE +NA

CF=1 or ZF=1

value1 <= value2. Values are treated as unsigned integers.

+A +NBE

CF=0 and ZF=0

value1 > value2. Values are treated as unsigned integers.

+B +NAE

CF=1

value1 < value2. Values are treated as unsigned integers.

+ +  + +Conditions are typically used to act on the result of a **cmp** or **test** instruction. For example, + +``` +cmp eax, 5 +jz equal +``` + +compares the **eax** register against the number 5 by computing the expression (**eax** - 5) and setting flags according to the result. If the result of the subtraction is zero, then the **zr** flag will be set, and the **jz** condition will be true so the jump will be taken. + +### Data Types + +- byte: 8 bits + +- word: 16 bits + +- dword: 32 bits + +- qword: 64 bits (includes floating-point doubles) + +- tword: 80 bits (includes floating-point extended doubles) + +- oword: 128 bits + +### Notation + +The following table indicates the notation used to describe assembly language instructions. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NotationMeaning

r, r1, r2...

Registers

m

Memory address (see the succeeding Addressing Modes section for more information.)

#n

Immediate constant

r/m

Register or memory

r/#n

Register or immediate constant

r/m/#n

Register, memory, or immediate constant

cc

A condition code listed in the preceding Conditions section.

T

"B", "W", or "D" (byte, word or dword)

accT

Size T accumulator: al if T = "B", ax if T = "W", or eax if T = "D"

+ +  + +### Addressing Modes + +There are several different addressing modes, but they all take the form **T ptr \[expr\]**, where **T** is some data type (see the preceding Data Types section) and **expr** is some expression involving constants and registers. + +The notation for most modes can be deduced without much difficulty. For example, **BYTE PTR \[esi+edx\*8+3\]** means "take the value of the **esi** register, add to it eight times the value of the **edx** register, add three, then access the byte at the resulting address." + +### Pipelining + +The Pentium is dual-issue, which means that it can perform up to two actions in one clock tick. However, the rules on when it is capable of doing two actions at once (known as *pairing*) are very complicated. + +Because x86 is a CISC processor, you do not have to worry about jump delay slots. + +### Synchronized Memory Access + +Load, modify, and store instructions can receive a **lock** prefix, which modifies the instruction as follows: + +1. Before issuing the instruction, the CPU will flush all pending memory operations to ensure coherency. All data prefetches are abandoned. + +2. While issuing the instruction, the CPU will have exclusive access to the bus. This ensures the atomicity of the load/modify/store operation. + +The **xchg** instruction automatically obeys the previous rules whenever it exchanges a value with memory. + +All other instructions default to nonlocking. + +### Jump Prediction + +Unconditional jumps are predicted to be taken. + +Conditional jumps are predicted to be taken or not taken, depending on whether they were taken the last time they were executed. The cache for recording jump history is limited in size. + +If the CPU does not have a record of whether the conditional jump was taken or not taken the last time it was executed, it predicts backward conditional jumps as taken and forward conditional jumps as not taken. + +### Alignment + +The x86 processor will automatically correct unaligned memory access, at a performance penalty. No exception is raised. + +A memory access is considered aligned if the address is an integer multiple of the object size. For example, all BYTE accesses are aligned (everything is an integer multiple of 1), WORD accesses to even addresses are aligned, and DWORD addresses must be a multiple of 4 in order to be aligned. + +The **lock** prefix should not be used for unaligned memory accesses. + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20x86%20Architecture%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/x86-instructions.md b/windows-driver-docs-pr/debugger/x86-instructions.md new file mode 100644 index 0000000000..e4690eef31 --- /dev/null +++ b/windows-driver-docs-pr/debugger/x86-instructions.md @@ -0,0 +1,1051 @@ +--- +title: x86 Instructions +description: x86 Instructions +ms.assetid: 237796d5-ef82-4eab-8d56-3191b3e63597 +keywords: ["x86 processor, instructions", "x86 processor, arithmetic"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# x86 Instructions + + +## + + +In the lists in this section, instructions marked with an asterisk (**\***) are particularly important. Instructions not so marked are not critical. + +On the x86 processor, instructions are variable-sized, so disassembling backward is an exercise in pattern matching. To disassemble backward from an address, you should start disassembling at a point further back than you really want to go, then look forward until the instructions start making sense. The first few instructions may not make any sense because you may have started disassembling in the middle of an instruction. There is a possibility, unfortunately, that the disassembly will never synchronize with the instruction stream and you will have to try disassembling at a different starting point until you find a starting point that works. + +For well-packed **switch** statements, the compiler emits data directly into the code stream, so disassembling through a **switch** statement will usually stumble across instructions that make no sense (because they are really data). Find the end of the data and continue disassembling there. + +### Instruction Notation + +The general notation for instructions is to put the destination register on the left and the source on the right. However, there can be some exceptions to this rule. + +Arithmetic instructions are typically two-register with the source and destination registers combining. The result is stored into the destination. + +Some of the instructions have both 16-bit and 32-bit versions, but only the 32-bit versions are listed here. Not listed here are floating-point instructions, privileged instructions, and instructions that are used only in segmented models (which Microsoft Win32 does not use). + +To save space, many of the instructions are expressed in combined form, as shown in the following example. + + ++++++ + + + + + + + + +

*

MOV

r1, r/m/#n

r1 = r/m/#n

+ +  + +means that the first parameter must be a register, but the second can be a register, a memory reference, or an immediate value. + +To save even more space, instructions can also be expressed as shown in the following. + + ++++++ + + + + + + + + +

*

MOV

r1/m, r/m/#n

r1/m = r/m/#n

+ +  + +which means that the first parameter can be a register or a memory reference, and the second can be a register, memory reference, or immediate value. + +Unless otherwise noted, when this abbreviation is used, you cannot choose memory for both source and destination. + +Furthermore, a bit-size suffix (8, 16, 32) can be appended to the source or destination to indicate that the parameter must be of that size. For example, r8 means an 8-bit register. + +### Memory, Data Transfer, and Data Conversion + +Memory and data transfer instructions do not affect flags. + +### Effective Address + + ++++++ + + + + + + + + +

*

LEA

r, m

Load effective address.

+

(r = address of m)

+ +  + +For example, **LEA eax, \[esi+4\]** means **eax** = **esi** + 4. This instruction is often used to perform arithmetic. + +### Data Transfer + + ++++++ + + + + + + + + + + + + + + + + + + + + +

*

MOV

r1/m, r2/m/#n

r1/m = r/m/#n

*

MOVSX

r1, r/m

Move with sign extension.

*

MOVZX

r1, r/m

Move with zero extension.

+ +  + +**MOVSX** and **MOVZX** are special versions of the **mov** instruction that perform sign extension or zero extension from the source to the destination. This is the only instruction that allows the source and destination to be different sizes. (And in fact, they must be different sizes. + +### Stack Manipulation + +The stack is pointed to by the **esp** register. The value at **esp** is the top of the stack (most recently pushed, first to be popped); older stack elements reside at higher addresses. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*

PUSH

r/m/#n

Push value onto stack.

*

POP

r/m

Pop value from stack.

PUSHFD

Push flags onto stack.

POPFD

Pop flags from stack.

PUSHAD

Push all integer registers.

POPAD

Pop all integer registers.

ENTER

#n, #n

Build stack frame.

*

LEAVE

Tear down stack frame

+ +  + +The C/C++ compiler does not use the **enter** instruction. (The **enter** instruction is used to implement nested procedures in languages like Algol or Pascal.) + +The **leave** instruction is equivalent to: + +``` +mov esp, ebp +pop ebp +``` + +### Data Conversion + + ++++ + + + + + + + + + + + + + + + + + + +

CBW

Convert byte (al) to word (ax).

CWD

Convert word (ax) to dword (dx:ax).

CWDE

Convert word (ax) to dword (eax).

CDQ

convert dword (eax) to qword (edx:eax).

+ +  + +All conversions perform sign extension. + +### Arithmetic and Bit Manipulation + +All arithmetic and bit manipulation instructions modify flags. + +### Arithmetic + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*

ADD

r1/m, r2/m/#n

r1/m += r2/m/#n

ADC

r1/m, r2/m/#n

r1/m += r2/m/#n + carry

*

SUB

r1/m, r2/m/#n

r1/m -= r2/m/#n

SBB

r1/m, r2/m/#n

r1/m -= r2/m/#n + carry

*

NEG

r1/m

r1/m = -r1/m

*

INC

r/m

r/m += 1

*

DEC

r/m

r/m -= 1

*

CMP

r1/m, r2/m/#n

Compute r1/m - r2/m/#n

+ +  + +The **cmp** instruction computes the subtraction and sets flags according to the result, but throws the result away. It is typically followed by a conditional **jump** instruction that tests the result of the subtraction. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

MUL

r/m8

ax = al * r/m8

MUL

r/m16

dx:ax = ax * r/m16

*

MUL

r/m32

edx:eax = eax * r/m32

IMUL

r/m8

ax = al * r/m8

IMUL

r/m16

dx:ax = ax * r/m16

*

IMUL

r/m32

edx:eax = eax * r/m32

*

IMUL

r1, r2/m

r1 *= r2/m

*

IMUL

r1, r2/m, #n

r1 = r2/m * #n

+ +  + +Unsigned and signed multiplication. The state of flags after multiplication is undefined. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

DIV

r/m8

(ah, al) = (ax % r/m8, ax / r/m8)

DIV

r/m16

(dx, ax) = dx:ax / r/m16

*

DIV

r/m32

(edx, eax) = edx:eax / r/m32

IDIV

r/m8

(ah, al) = ax / r/m8

IDIV

r/m16

(dx, ax) = dx:ax / r/m16

*

IDIV

r/m32

(edx, eax) = edx:eax / r/m32

+ +  + +Unsigned and signed division. The first register in the pseudocode explanation receives the remainder and the second receives the quotient. If the result overflows the destination, a division overflow exception is generated. + +The state of flags after division is undefined. + + ++++++ + + + + + + + + +

*

SETcc

r/m8

Set r/m8 to 0 or 1

+ +  + +If the condition *cc* is true, then the 8-bit value is set to 1. Otherwise, the 8-bit value is set to zero. + +### Binary-coded Decimal + +You will not see these instructions unless you are debugging code written in COBOL. + + +++++ + + + + + + + + + + + + +

DAA

Decimal adjust after addition.

DAS

Decimal adjust after subtraction.

+ +  + +These instructions adjust the **al** register after performing a packed binary-coded decimal operation. + + ++++ + + + + + + + + + + +

AAA

ASCII adjust after addition.

AAS

ASCII adjust after subtraction.

+ +  + +These instructions adjust the **al** register after performing an unpacked binary-coded decimal operation. + + ++++ + + + + + + + + + + +

AAM

ASCII adjust after multiplication.

AAD

ASCII adjust after division.

+ +  + +These instructions adjust the **al** and **ah** registers after performing an unpacked binary-coded decimal operation. + +### Bits + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*

AND

r1/m, r2/m/#n

r1/m = r1/m and r2/m/#n

*

OR

r1/m, r2/m/#n

r1/m = r1/m or r2/m/#n

*

XOR

r1/m, r2/m/#n

r1/m = r1/m xor r2/m/#n

*

NOT

r1/m

r1/m = bitwise not r1/m

*

TEST

r1/m, r2/m/#n

Compute r1/m and r2/m/#n

+ +  + +The **test** instruction computes the logical AND operator and sets flags according to the result, but throws the result away. It is typically followed by a conditional jump instruction that tests the result of the logical AND. + + ++++++ + + + + + + + + + + + + + + + + + + + + +

*

SHL

r1/m, cl/#n

r1/m <<= cl/#n

*

SHR

r1/m, cl/#n

r1/m >>= cl/#n zero-fill

*

SAR

r1/m, cl/#n

r1/m >>= cl/#n sign-fill

+ +  + +The last bit shifted out is placed in the carry. + + ++++++ + + + + + + + + +

SHLD

r1, r2/m, cl/#n

Shift left double.

+ +  + +Shift **r1** left by **cl**/\#n, filling with the top bits of **r2**/m. The last bit shifted out is placed in the carry. + + +++++ + + + + + + + +

SHRD

r1, r2/m, cl/#n

Shift right double.

+ +  + +Shift **r1** right by **cl**/\#n, filling with the bottom bits of **r2**/m. The last bit shifted out is placed in the carry. + + +++++ + + + + + + + + + + + + + + + + + + + + + + +

ROL

r1, cl/#n

Rotate r1 left by cl/#n.

ROR

r1, cl/#n

Rotate r1 right by cl/#n.

RCL

r1, cl/#n

Rotate r1/C left by cl/#n.

RCR

r1, cl/#n

Rotate r1/C right by cl/#n.

+ +  + +Rotation is like shifting, except that the bits that are shifted out reappear as the incoming fill bits. The C-language version of the rotation instructions incorporate the carry bit into the rotation. + + +++++ + + + + + + + + + + + + + + + + + +

BT

r1, r2/#n

Copy bit r2/#n of r1 into carry.

BTS

r1, r2/#n

Set bit r2/#n of r1, copy previous value into carry.

BTC

r1, r2/#n

Clear bit r2/#n of r1, copy previous value into carry.

+ +  + +### Control Flow + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*

Jcc

dest

Branch conditional.

*

JMP

dest

Jump direct.

*

JMP

r/m

Jump indirect.

*

CALL

dest

Call direct.

*

CALL

r/m

Call indirect.

+ +  + +The **call** instruction pushes the return address onto the stack then jumps to the destination. + + ++++++ + + + + + + + + +

*

RET

#n

Return

+ +  + +The **ret** instruction pops and jumps to the return address on the stack. A nonzero *\#n* in the **RET** instruction indicates that after popping the return address, the value *\#n* should be added to the stack pointer. + + ++++ + + + + + + + + + + + + + + + + + + +

LOOP

Decrement ecx and jump if result is nonzero.

LOOPZ

Decrement ecx and jump if result is nonzero and zr was set.

LOOPNZ

Decrement ecx and jump if result is nonzero and zr was clear.

JECXZ

Jump if ecx is zero.

+ +  + +These instructions are remnants of the x86's CISC heritage and in recent processors are actually slower than the equivalent instructions written out the long way. + +### String Manipulation + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

*

MOVST

Move T from esi to edi.

CMPST

Compare T from esi with edi.

SCAST

Scan T from edi for accT.

LODST

Load T from esi into accT.

*

STOST

Store T to edi from accT.

+ +  + +After performing the operation, the source and destination register are incremented or decremented by sizeof(*T*), according to the setting of the direction flag (up or down). + +The instruction can be prefixed by **REP** to repeat the operation the number of times specified by the **ecx** register. + +The **rep mov** instruction is used to copy blocks of memory. + +The **rep stos** instruction is used to fill a block of memory with acc*T*. + +### Flags + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

LAHF

Load ah from flags.

SAHF

Store ah to flags.

STC

Set carry.

CLC

Clear carry.

CMC

Complement carry.

STD

Set direction to down.

CLD

Set direction to up.

STI

Enable interrupts.

CLI

Disable interrupts.

+ +  + +### Interlocked Instructions + + +++++ + + + + + + + + + + + + + + + + + +

XCHG

r1, r/m

Swap r1 and r/m.

XADD

r1, r/m

Add r1 to r/m, put original value in r1.

CMPXCHG

r1, r/m

Compare and exchange conditional.

+ +  + +The **cmpxchg** instruction is the atomic version of the following: + +``` + cmp accT, r/m + jz match + mov accT, r/m + jmp done +match: + mov r/m, r1 +done: +``` + +### Miscellaneous + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

INT

#n

Trap to kernel.

BOUND

r, m

Trap if r not in range.

*

NOP

No operation.

XLATB

al = [ebx + al]

BSWAP

r

Swap byte order in register.

+ +  + +Here is a special case of the **int** instruction. + + +++++ + + + + + + + +

INT

3

Debugger breakpoint trap.

+ +  + +The opcode for **INT 3** is 0xCC. The opcode for **NOP** is 0x90. + +When debugging code, you may need to patch out some code. You can do this by replacing the offending bytes with 0x90. + +### Idioms + + ++++++ + + + + + + + + + + + + + + + + + + + + +

*

XOR

r, r

r = 0

*

TEST

r, r

Check if r = 0.

*

ADD

r, r

Shift r left by 1.

+ +  + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20x86%20Instructions%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/debugger/z--execute-while-.md b/windows-driver-docs-pr/debugger/z--execute-while-.md new file mode 100644 index 0000000000..398598653f --- /dev/null +++ b/windows-driver-docs-pr/debugger/z--execute-while-.md @@ -0,0 +1,121 @@ +--- +title: z (Execute While) +description: The z command executes a command while a given condition is true. +ms.assetid: 075dc012-68c2-4172-9d37-57bc8358297c +keywords: ["z (Execute While) Windows Debugging"] +ms.author: windowsdriverdev +ms.date: 05/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +topic_type: +- apiref +api_name: +- z (Execute While) +api_type: +- NA +--- + +# z (Execute While) + + +The **z** command executes a command while a given condition is true. + +User-Mode + +``` +Command ; z( Expression ) +``` + +Kernel-Mode + +``` +Command ; [Processor] z( Expression ) +``` + +## Parameters + + + *Command* +Specifies the command to execute while the *Expression* condition evaluates to a nonzero value. This command is always executed at least once. + + *Processor* +Specifies the processor that applies to the test. For more information about the syntax, see [Multiprocessor Syntax](multiprocessor-syntax.md). You can specify processors only in kernel mode. + + *Expression* +Specifies the condition to test. If this condition evaluates to a nonzero value, the *Command* command is executed again and then *Expression* is tested again. For more information about the syntax, see [Numerical Expression Syntax](numerical-expression-syntax.md). + +### Environment + + ++++ + + + + + + + + + + + + + + +

Modes

User mode, kernel mode

Targets

Live, crash dump

Platforms

All

+ +  + +Remarks +------- + +In many debugger commands, the semicolon is used to separate unrelated commands. However, in the **z** command, a semicolon separates the "z" from the *Command* parameter. + +The *Command* command is always executed at least once, and then *Expression* is tested. If the condition is a nonzero value, the command is again executed, and then *Expression* is tested again. (This behavior is similar to a C-language **do - while** loop, not a simple **while** loop.) + +If there are several semicolons to the left of the "z", all commands to the left of the "z" repeat as long as the *Expression* condition is true. Such commands can be any debugger commands that permit a terminal semicolon. + +If you add another semicolon and additional commands after the **z** command, these additional commands are executed after the loop is complete. We do not typically recommend a line that begins with "z" because it generates uninteresting output forever unless the condition becomes false because of some other action. Note that you can nest **z** commands. + +To break a loop that is continuing for too long, use [**CTRL+C**](ctrl-c--break-.md) in CDB or KD, or use [Debug | Break](debug---break.md) or CTRL+BREAK in WinDbg. + +The following code example shows an unnecessarily complex way to zero the **eax** register. + +``` +0:000> reax = eax - 1 ; z(eax) +``` + +The following example increments the **eax** and **ebx** registers until one of them is at least 8 and then it increments the **ecx** register once. + +``` +0:000> reax=eax+1; rebx=ebx+1; z((eax<8)|(ebx<8)); recx=ecx+1 +``` + +The following example uses C++ expression syntax and uses the pseudo-register **$t0** as a loop variable. + +``` +0:000> .expr /s c++ +Current expression evaluator: C++ - C++ source expressions + +0:000> db pindexcreate[@$t0].szKey; r$t0=@t0+1; z( @$t0 < cIndexCreate ) +``` + +## See also + + +[**j (Execute If-Else)**](j--execute-if---else-.md) + +  + +  + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[debugger\debugger]:%20z%20%28Execute%20While%29%20%20RELEASE:%20%285/15/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + + + + diff --git a/windows-driver-docs-pr/devapps/TOC.md b/windows-driver-docs-pr/devapps/TOC.md index 080e3e2b04..ee8b0a0a07 100644 --- a/windows-driver-docs-pr/devapps/TOC.md +++ b/windows-driver-docs-pr/devapps/TOC.md @@ -28,6 +28,6 @@ ## [Windows Store device apps for internal devices](windows-store-device-apps-for-specialized-devices.md) ## [Automatic installation for Windows Store device apps](auto-install-for-windows-store-device-apps.md) ## [Hardware access for Universal Windows Platform Apps](hardware-access-for-universal-windows-platform-apps.md) -### [Custom Capabilities for Universal Windows Platform Apps](custom-capabilities-for-universal-windows-platform-apps.md) -### [Developing a Universal Windows Platform app with Custom Capabilities](developing-a-universal-windows-platform-app-with-custom-capabilities.md) +### [Creating a custom capability to pair a driver with a Hardware Support App (HSA)](creating-a-custom-capability-to-pair-driver-with-hsa.md) +### [Using a custom capability to pair a Hardware Support App (HSA) with a driver](using-a-custom-capability-to-pair-hsa-with-driver.md) ### [FAQ on custom capabilities](FAQ-on-custom-capabilities.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/devapps/creating-a-camera-driver-mft.md b/windows-driver-docs-pr/devapps/creating-a-camera-driver-mft.md index 4d1c15d484..e7d3416dfc 100644 --- a/windows-driver-docs-pr/devapps/creating-a-camera-driver-mft.md +++ b/windows-driver-docs-pr/devapps/creating-a-camera-driver-mft.md @@ -1,9 +1,9 @@ --- title: Creating a camera driver MFT for a Windows Store device app -description: In Windows 8.1, Windows Store device apps let device manufacturers apply custom settings and special effects on the camera's video stream with a camera driver MFT (media foundation transform). +description: Windows Store device apps let device manufacturers apply custom settings and special effects on the camera's video stream with a camera driver MFT (media foundation transform). ms.assetid: 079CB01E-D16C-4597-8F08-BD75F1D02427 ms.author: windowsdriverdev -ms.date: 04/20/2017 +ms.date: 06/29/2017 ms.topic: article ms.prod: windows-hardware ms.technology: windows-devices @@ -11,11 +11,9 @@ ms.technology: windows-devices # Creating a camera driver MFT for a Windows Store device app +Windows Store device apps let device manufacturers apply custom settings and special effects on the camera's video stream with a camera driver MFT (media foundation transform). This topic introduces driver MFTs and uses the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample to show how to create one. To learn more about Windows Store device apps in general, see [Meet Windows Store device apps](meet-windows-store-device-apps.md). -In Windows 8.1, Windows Store device apps let device manufacturers apply custom settings and special effects on the camera's video stream with a camera driver MFT (media foundation transform). This topic introduces driver MFTs and uses the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample to show how to create one. To learn more about Windows Store device apps in general, see [Meet Windows Store device apps](meet-windows-store-device-apps.md). - -## The driver MFT - +## The driver MFT This section describes the Media Foundation Transform (MFT) that you create to apply effects to the media capture stream coming from the camera. This is how you provide transforms for color effects, scheme modes, and face-tracking effects that really distinguish your camera from others. This MFT, known as the driver MFT, is first applied to the connected video stream coming from the camera driver when a Windows Store app begins video capture. When that app invokes the **Camera options** UI, Windows automatically provides access to any interfaces the driver MFT implements for controlling its custom effects. @@ -23,72 +21,69 @@ This section describes the Media Foundation Transform (MFT) that you create to a A Driver MFT is not required for a Windows Store device app. A device manufacturer may choose to implement a Windows Store device app without a driver MFT, simply to provide a differentiated user interface containing branding for their hardware, without applying custom settings and special effects to the video stream. -### How a driver MFT is used +### How a driver MFT is used The Windows Store device app for a camera runs in a different process than the Windows Store app that invokes it from the [CameraCaptureUI](http://go.microsoft.com/fwlink/p/?LinkId=317985) API. For the Windows Store device app to control a driver MFT, a specific sequence of events across different process spaces must occur. -1. A Windows Store app wants to capture a photo, so it calls the [CaptureFileAsync](http://go.microsoft.com/fwlink/p/?LinkId=317986) method -2. Windows requests the driver MFT pointer and the camera's device ID -3. The driver MFT pointer is passed to a settings host -4. The host queries device properties for the app ID of the Windows Store device app associated with the camera (per device metadata) -5. If no Windows Store device app is found, the default flyout interacts with the capture engine -6. If a Windows Store device app is found, it is activated and the settings host passes the driver MFT pointer to it -7. The Windows Store device app controls the driver MFT using the interface exposed through the pointer +1. A Windows Store app wants to capture a photo, so it calls the [CaptureFileAsync](http://go.microsoft.com/fwlink/p/?LinkId=317986) method +2. Windows requests the driver MFT pointer and the camera's device ID +3. The driver MFT pointer is passed to a settings host +4. The host queries device properties for the app ID of the Windows Store device app associated with the camera (per device metadata) +5. If no Windows Store device app is found, the default flyout interacts with the capture engine +6. If a Windows Store device app is found, it is activated and the settings host passes the driver MFT pointer to it +7. The Windows Store device app controls the driver MFT using the interface exposed through the pointer ![the process interaction for invoking a windows store device app.](images/372798-cameradrivermft-internals.png) -### AvStream driver model requirement +### AvStream driver model requirement Your camera’s driver must use the AvStream driver model. For more info about the AVStream driver model, see [AVStream Minidrivers Design Guide](http://go.microsoft.com/fwlink/p/?LinkID=228585). -### How the driver MFT is exposed to apps +### How the driver MFT is exposed to apps A driver MFT is registered with Windows as a COM interface so that the transform it implements can be applied to the media stream coming out of a specific device, such as a camera. **Note**  A driver MFT shouldn’t be registered using the `MFTRegister` function because it is device specific and not a general purpose MFT. For info on the registry key, see the [Installing and registering the driver MFT](#installing) section later in this topic. -  - When an app initiates a video capture, a Media Foundation Source Reader is instantiated to provide the video stream. This media source reads a registry value from the device registry key. If the CLSID of the driver MFT’s COM class is found in the registry value, the source reader instantiates the driver MFT and inserts it into the media pipeline. In addition to Windows Store device apps, the driver MFT functionality can be accessed when the device associated with it is used to capture video using the following APIs: -- HTML5 <video> tags in a Windows Store app using HTML. Transforms that the driver MFT has enabled will affect video that is being played using the <video> element, as in the following code example: +- HTML5 <video> tags in a Windows Store app using HTML. Transforms that the driver MFT has enabled will affect video that is being played using the <video> element, as in the following code example: - ```HTML - var video = document.getElementById('myvideo'); - video.src = URL.createObjectURL(fileItem); - video.play(); + ``` + var video = document.getElementById('myvideo'); + video.src = URL.createObjectURL(fileItem); + video.play(); ``` -- Windows.Media.MediaCapture API in a Windows Store app using the Windows Runtime. For more info on how this API is used, see the [Media Capture](http://go.microsoft.com/fwlink/p/?LinkId=243997) sample. +- Windows.Media.MediaCapture API in a Windows Store app using the Windows Runtime. For more info on how this API is used, see the [Media Capture](http://go.microsoft.com/fwlink/p/?LinkId=243997) sample. -- Media Foundation’s Source Reader, for apps processing media data. The driver MFT will be exposed to applications as the first (0th) MFT when calling `IMFSourceReaderEx::GetTransformForStream`. The category that will be returned is `MFT_CATEGORY_VIDEO_EFFECT`. +- Media Foundation’s Source Reader, for apps processing media data. The driver MFT will be exposed to applications as the first (0th) MFT when calling `IMFSourceReaderEx::GetTransformForStream`. The category that will be returned is `MFT_CATEGORY_VIDEO_EFFECT`. ![source reader's role in media capture.](images/372842-cameracaptureengine.png) -### Multi-pin cameras +### Multi-pin cameras If you have a three-pin or other multi-pin camera, see [Considerations for driver MFTs on multi-pin cameras](driver-mfts-on-multi-pin-cameras.md). -## Driver MFT implementation - +## Driver MFT implementation This section provides information on implementing your driver MFT. For a full example of a driver MFT that works together with a Windows Store device app, see the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample. -### Development tools +### Development tools Microsoft Visual Studio Professional 2013 or Microsoft Visual Studio Ultimate 2013 is required. -### Driver MFT characteristics +### Driver MFT characteristics The driver MFT is instantiated per stream. For each stream the camera supports, an instance of the MFT is instantiated and connected to it. The driver MFT is expected to have a single input stream and a single output stream. The driver MFT may be either a synchronous MFT or an asynchronous MFT. -### Communication between the camera and the driver MFT +### Communication between the camera and the driver MFT To enable two-way communication between the media source and the driver MFT, the pointer to source stream’s attribute store is set on the input stream attribute store of the driver MFT as `MFT_CONNECTED_STREAM_ATTRIBUTE`. This occurs through a handshake process you enable by exposing `MFT_ENUM_HARDWARE_URL_Attribute` in the driver MFT, as in the following example: -```ManagedCPlusPlus +``` HRESULT CDriverMft::GetAttributes(IMFAttributes** ppAttributes) { HRESULT hr = S_OK; @@ -109,11 +104,11 @@ HRESULT CDriverMft::GetAttributes(IMFAttributes** ppAttributes) In this example, the `MFT_CONNECTED_STREAM_ATTRIBUTE` in the driver MFT’s attribute store is set to point to the device source stream’s attribute store. See [Hardware Handshake Sequence](http://go.microsoft.com/fwlink/p/?LinkId=320139) for further details on how communication between the camera and the MFT is set up. -### How to access device source information +### How to access device source information The following code example shows how the driver MFT can get the pointer to the source transform from its input attribute store. The driver MFT can then use the source pointer to get device source info. -```ManagedCPlusPlus +``` if(!m_pSourceTransform && m_pInputAttributes) { m_pInputAttributes-> @@ -131,32 +126,32 @@ if(!m_pSourceTransform && m_pInputAttributes) { } ``` -### How to implement passthrough mode +### How to implement passthrough mode To put the driver MFT in passthrough mode, specify the same media type for the input and output stream. `ProcessInput` and `ProcessOutput` calls on the MFT will still be made. It is left up to your driver MFT implementation to determine whether or not any processing occurs in passthrough mode. -### Header files to include +### Header files to include You’ll need to include header files for the `IInspectable` and `IMFTransform` methods that the driver MFT must implement. For a list of header files to include, see **stdafx.h** in the **SampleMFT0** directory of the [Windows Store device app for camera](http://go.microsoft.com/fwlink/p/?LinkID=227865) sample. -```ManagedCPlusPlus +``` // required for IInspectable #include ``` -### How to implement IInspectable +### How to implement IInspectable A driver MFT that’s intended for use from a camera’s Windows Store device app must implement the methods of `IInspectable` so that the Windows Store device app can access a pointer to the driver MFT when launched. Your driver MFT should implement the methods of `IInspectable` as follows: -- **IInspectable::GetIids** should return null in the *iids* out parameter, and return 0 in the *iidCount* out parameter. +- **IInspectable::GetIids** should return null in the *iids* out parameter, and return 0 in the *iidCount* out parameter. -- **IInspectable::GetRuntimeClassName** should return null in the out parameter. +- **IInspectable::GetRuntimeClassName** should return null in the out parameter. -- **IInspectable::GetRuntiGetTrustLevel** should return `TrustLevel::BaseTrust` in the out parameter. +- **IInspectable::GetRuntiGetTrustLevel** should return `TrustLevel::BaseTrust` in the out parameter. The following code example shows how the `IInspectable` methods are implemented in the sample driver MFT. This code can be found in the **Mft0.cpp** file, in the **SampleMFT0** directory of the sample. -```ManagedCPlusPlus +``` // Mft0.cpp STDMETHODIMP CMft0::GetIids( /* [out] */ __RPC__out ULONG *iidCount, @@ -198,11 +193,11 @@ STDMETHODIMP CMft0::GetTrustLevel( } ``` -### COM implementation +### COM implementation Each interface your driver MFT implements should implement and derive from `IUnknown`, in order to be correctly marshaled to the camera’s Windows Store device app. The following is an example **.idl** file for a driver MFT that demonstrates this. -```ManagedCPlusPlus +``` // SampleMft0.idl : IDL source for SampleMft0 // @@ -247,31 +242,26 @@ library SampleMft0Lib **Note**  The driver MFT is a regular COM class that can be created using `CoCreateInstance`. You should not use the `MFTRegister` function to register it because it is not a general-purpose MFT. -  - -### Creating a proxy +### Creating a proxy The driver MFT is an out-of-process server. To use it in a Windows Store device app, you must provide marshaling support in a proxy so that your driver MFT interface can be used across process boundaries. You can find an example of this in the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample. The sample uses the MIDL compiler to generate a stubless proxy. -### Exposing the driver MFT to apps +### Exposing the driver MFT to apps To write a Windows Store device app in C# or JavaScript that interacts with a driver MFT, you need to create an additional component in the Windows Store device app’s Microsoft Visual Studio project. This component is a wrapper that exposes the driver MFT interfaces in a Windows Runtime Component that is visible to the Windows Store device app. The Wrapper subproject in the [Windows Store device app for camera](http://go.microsoft.com/fwlink/p/?LinkID=227865) sample provides an example of how to expose your driver MFT to the Windows Runtime so that you can use it from a Windows Store device app implemented in C# or JavaScript. It is designed to work together with the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample. See the [Driver MFT](http://go.microsoft.com/fwlink/p/?LinkID=251566) sample page for a step-by-step guide to installing, running, and testing the samples. -## Installing and registering the driver MFT - +## Installing and registering the driver MFT This section lists steps for installing the driver MFT: -1. The driver MFT DLL must be installed in a subdirectory of one of the following locations: - - %SystemDrive%\\Program Files\\ - - %SystemDrive%\\Program Files (x86)\\ +1. The driver MFT DLL must be installed in a subdirectory in the following location: + - %SystemDrive%\\Program Files\\ +2. Your camera installer registers the driver MFT by calling **regsvr32** on your driver MFT DLL, or by providing a driver manifest (.man) file for the DLL that the installer uses for registration. +3. Set the `CameraPostProcessingPluginCLSID` value in the registry key for your camera. Your INF file should specify the CLSID of the Driver MFT in the device class registry key for the device, by setting the `CameraPostProcessingPluginCLSID` value to the CLSID GUID of the driver MFT class. The following is an example from an INF file entry that populates the registry keys for a camera: -2. Install both the x86 and the x64 versions of the DLL on an x64 system. -3. Your camera installer registers the driver MFT by calling **regsvr32** on your driver MFT DLL, or by providing a driver manifest (.man) file for the DLL that the installer uses for registration. -4. Set the `CameraPostProcessingPluginCLSID` value in the registry key for your camera. Your INF file should specify the CLSID of the Driver MFT in the device class registry key for the device, by setting the `CameraPostProcessingPluginCLSID` value to the CLSID GUID of the driver MFT class. The following is an example from an INF file entry that populates the registry keys for a camera: - ```ManagedCPlusPlus + ``` KSCATEGORY_VIDEO_CAMERA: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{E5323777-F976-4f5b-9B55-B94699C46E44}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{E5323777-F976-4f5b-9B55-B94699C46E44}\#GLOBAL\Device Parameters] @@ -292,42 +282,36 @@ This section lists steps for installing the driver MFT: **Note**  `KSCATEGORY_VIDEO_CAMERA` is recommended for cameras. You will normally only need one of the registry keys, depending on how the device is registered. -   - -## Associate your app with the camera - +## Associate your app with the camera This section contains information on steps required to identify your camera in device metadata and in the Windows registry. This metadata enables you to pair your Windows Store device app and identifies your app so that it can be downloaded seamlessly the first time the camera is connected. -### Updates +### Updates After the first installation of the app, if the user downloads an updated version of the app, then the updates are automatically integrated into the camera capture experience. However, updates are not downloaded automatically. The user must download additional app updates from the Windows Store, because the app is [automatically installed](auto-install-for-windows-store-device-apps.md) only on first connect. The main page of your Windows Store device app can provide notifications that updates are available and provide links to download updates. **Important**  Your updated app should work with any updated drivers distributed through Windows Update. -  - -### Multiple cameras +### Multiple cameras Multiple camera models can declare the same Windows Store device app in their device metadata. If a system has more than one internally embedded camera, the cameras must share the same Windows Store device app. The app includes logic for determining which camera is in use and can show different UI for each camera in its **More options** experience. For more info about customizing that experience, see [How to customize camera options](how-to-customize-camera-options.md). -### Internal cameras +### Internal cameras Windows Store device apps for internal cameras are eligible for [Automatic installation](auto-install-for-windows-store-device-apps.md) from the Windows Store, but it is recommended that they be pre-installed for the most seamless user experience. There are additional steps required to support internal cameras and associate a Windows Store device app with them. For more info, see [Identifying the location of internal cameras](identifying-the-location-of-internal-cameras.md). -### Creating the device metadata package +### Creating the device metadata package For both internal and external cameras, you need to create a device metadata package. When you submit your camera’s Windows Store device app to the Windows Store (or preinstall it using the OPK, in the case of internal cameras), in addition to the app itself, you’ll need to provide metadata containing the following: -- Application publisher name -- Application package name -- Application element identifier -- Device experience identifier +- Application publisher name +- Application package name +- Application element identifier +- Device experience identifier For more info about how to use device metadata to associate your app with your device, see [Building Windows Store device apps](the-workflow.md). -## Related topics - +## Related topics [Building Windows Store device apps](the-workflow.md) @@ -344,10 +328,6 @@ For more info about how to use device metadata to associate your app with your d     - +-------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devapps\devapps]:%20Creating%20a%20camera%20driver%20MFT%20for%20a%20Windows%20Store%20device%20app%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") - - - - diff --git a/windows-driver-docs-pr/devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md b/windows-driver-docs-pr/devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md new file mode 100644 index 0000000000..14e0679738 --- /dev/null +++ b/windows-driver-docs-pr/devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md @@ -0,0 +1,156 @@ +--- +title: Creating a custom capability to pair a driver with a Hardware Support App (HSA) +author: windows-driver-content +description: getting Creating a custom capability to pair a driver with a Hardware Support App (HSA) +keywords: +- Custom , Capabilities +- UWP Apps +- custom capabilities +- UWP +- Hardware +ms.author: windowsdriverdev +ms.date: 08/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a custom capability to pair a driver with a Hardware Support App (HSA) + +A Hardware Support App (HSA) is a [Universal Windows Platform (UWP)](https://msdn.microsoft.com/50a5605e-3a91-41db-800a-9180717c1e86) app that is paired with a specific driver or [RPC (Remote Procedure Call)](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378651) using a custom capability. The owner of the driver or RPC endpoint reserves the custom capability, permits access to UWP apps that advertise it, and then provides the capability to the app developer. This page describes that process. + +The steps for the app developer are described in [Using a custom capability to pair a Hardware Support App (HSA) with a driver](using-a-custom-capability-to-pair-hsa-with-driver.md). + +## Reserving a custom capability + +To reserve a custom capability: + +1. Email Microsoft Hardware Support Apps Review () with the following information: + + * Contact information + * Company name + * Name of the capability (must be unique and reference the owner) + * What resources does capability need to access? + * Any security or privacy concerns + * What data does your capability provide access to? + * Include the Windows Store App Publisher ID. To get one, create a skeleton app entry on the Windows Store page. For more info on reserving your App PFN, see [Create your app by reserving a name](https://msdn.microsoft.com/en-us/windows/uwp/publish/create-your-app-by-reserving-a-name). + +2. If the request is approved, Microsoft emails back a unique custom capability string name in the format **CompanyName.capabilityName\_PublisherID**. + +Now you can use the custom capability to allow access to either an RPC endpoint or a driver. + +## Allowing access to an RPC endpoint to a UWP app using the custom capability + +To allow access to an RPC endpoint to a UWP app that has the custom capability, follow these steps: + +1. Call [**DeriveCapabilitySidsFromName**](https://msdn.microsoft.com/library/windows/desktop/mt803273) to convert the custom capability name to a security ID (SID). +2. Add the SID to your access allowed ACE along with any other SIDs that are needed for the security descriptor of your RPC endpoint. +3. Create an RPC endpoint using the information from the Security Descriptor. + +You can see an implementation of the above in the [RPC server code](https://github.com/Microsoft/Windows-universal-samples/blob/master/Samples/CustomCapability/Service/Server/RpcServer.cpp) in the [Custom Capability sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/CustomCapability). + +## Allowing access to a driver to a UWP app using the custom capability + +To allow access to a driver to a UWP app with the custom capability, add a few lines to either the INF file or the driver source. + +In the INF file, specify your custom capability as follows: + +``` +[WDMPNPB003_Device.NT.Interfaces] +AddInterface= {B0823231-61F1-4685-85CA-8DF9DDDEBF6E},,AddInterfaceSection + +[AddInterfaceSection] +AddProperty= AddInterfaceSection.AddProps + +[AddInterfaceSection.AddProps] +; DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities +{026e516e-b814-414b-83cd-856d6fef4822}, 8, 0x2012,, “CompanyName.myCustomCapabilityNameTBD_YourStorePubId” +``` + +Or, do the following in the driver: + +```c++ +WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = {}; +WCHAR customCapabilities[] = L”CompanyName.yourCustomCapabilityNameTBD_YourStorePubId\0”; + +WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT( + &PropertyData, + &m_VendorDefinedSubType, + &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities); + +Status = WdfDeviceAssignInterfaceProperty( + m_FxDevice, + &PropertyData, + DEVPROP_TYPE_STRING_LIST, + ARRAYSIZE(customCapabilities), + reinterpret_cast(customCapabilities)); + +``` + +For an example of the driver code shown immediately above, see the [Driver package installation toolkit for universal drivers](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU). + +## Preparing the Signed Custom Capability Descriptor (SCCD) file + +A Signed Custom Capability Descriptor (SCCD) file is a signed XML file authorizing the use of one or more custom capabilities. The owner of the driver or RPC endpoint grants the custom capability to the app developer by providing this file. + +To prepare the SCCD file, first update the custom capability string. Use the following example as a starting point: + +```xml + + + + + + + + + + +``` + +Next, the custom capability owner obtains the Package Family Name (PFN) and the signature hash from the app developer and updates those strings in the SCCD file. + +**Note:** The app does not have to be signed directly with the certificate, but the specified certificate must be part of the cert chain that signs the app. + +After completing the SCCD, the capability owner emails it to Microsoft for signing. Microsoft returns the signed SCCD to the capability owner. + +The capability owner then sends the SCCD to the app developer. The app developer includes the signed SCCD in the app manifest. To learn what the app developer needs to do, see [Using a custom capability to pair a Hardware Support App (HSA) with a driver](using-a-custom-capability-to-pair-hsa-with-driver.md). + +## Limiting the scope of an SCCD + +For testing purposes, a custom capability owner can restrict installation of a hardware support app to computers in developer mode. + +To do so, before getting the SCCD signed by Microsoft, add **DeveloperModeOnly**: + +```xml + + + + + + + + + + + + + + + +``` + +The resulting signed SCCD works only on devices in [Developer Mode](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development). + +## Summary + +The following diagram summarizes the sequence described above: + +![Getting an SCCD signed](images/signsccd.png) + +### See Also + +* [App capability declarations](https://docs.microsoft.com/windows/uwp/packaging/app-capability-declarations) +* [Custom Capability sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/CustomCapability) +* [Getting Started with Universal Windows drivers](../develop/getting-started-with-universal-drivers.md) +* [Pairing a driver with a Universal Windows Platform (UWP) app](../install/pairing-app-and-driver-versions.md) diff --git a/windows-driver-docs-pr/devapps/custom-capabilities-for-universal-windows-platform-apps.md b/windows-driver-docs-pr/devapps/custom-capabilities-for-universal-windows-platform-apps.md deleted file mode 100644 index 611e81265f..0000000000 --- a/windows-driver-docs-pr/devapps/custom-capabilities-for-universal-windows-platform-apps.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Custom Capabilities for Universal Windows Platform Apps -author: windows-driver-content -description: getting custom capabilities for Universal Windows Platform Apps -keywords: -- Custom , Capabilities -- UWP Apps -- Custom Capabilities -- UWP -- Hardware -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# Custom Capabilities - -Custom capabilities are a new capability class introduced to allow -developers to make better use of the UWP. They are similar to the -previously defined [restricted -capabilities](https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations#special-and-restricted-capabilities) -which give access to protected resources. However, there are some key -differences between the two. Unlike restricted resources, 3^rd^ party -partners can define or claim their own capabilities. Custom capabilities -also do not have to be built into Windows at compilation time. They are -different from previous [app -capabilities](https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations) -as they do not use the same authorization model and instead, app -authorization to use the capability verifies during the app installation -instead of when uploaded to the store. - -For a developer to get access to a custom capability, they must have a -signed custom capability descriptor (SCCD) which allows the authorized -use of one or more custom capabilities. For more information on SCCD’s, -read the section on SCCD’s [here.](#signed-custom-capability-descriptors) - -## UWP Apps Getting Access to System Software with Custom Capabilities - - -A [Universal Windows Platform -(UWP)](https://msdn.microsoft.com/50a5605e-3a91-41db-800a-9180717c1e86) -application can utilize Custom Capabilities to gain access to system -software. - -There is a similar function in [Windows Store device apps -(WSDA)](https://msdn.microsoft.com/en-us/windows/hardware/drivers/devapps/index) -which were first introduced in Windows 8 to provide a way for to provide -hardware support services (HSS) for certain devices and peripherals. -However, they do not provide support for all services that HSS typically -need to communicate with, such as Win32 services, device-specific -registry values, and 3rd party APIs. WSDA’s are only available for the -Desktop device family and does not take advantage of the common app -platform offered by the UWP which targets the Universal device family. - -![Learn more about device families](images/device-fam.png) - -*Learn more about device families* -[here](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide#device-families)*.* - -Unlike a WSDA, a UWP can install on a system for all its users either as -part of the imaging process of the OS when a new device or peripheral is -connected, or manually by the user. - -A UWP Developer can deliver on-the-fly updates and new experiences -independent of driver updates. UWP servicing is handled through the -existing app servicing mechanisms and workflows for apps in the Windows -Store. Upon publishing an update, users will receive the update -immediately if an internet connection is available. - -## Signed Custom Capability Descriptors - -A signed custom capability descriptor (SCCD) contains the name of the -capability or capabilities the SCCD is authorizing, a list of Authorized -Entities that are authorized to use the Custom Capability, and the -catalog containing the signature of the SCCD file itself. An authorized -entity identifies an app by its Package Family Name and the Certificate -Signature Hash of the certificate that signs the app. The hash must be -SHA256 and match the hash of the signing certificate. The hash must -match the hash of the signing certificate. Below is an example of an -SCCD with the Catalog truncated. - -**Note:** If the app isn't signed directly with -that certificate it's fine if the certificate specified lies somewhere -in the cert chain that signs the app. -```xml - - - - - - - - - - -``` - - -## Claiming a Custom Capability - - -The ability for a UWP to use custom capabilities is currently only -available to known, trusted hardware vendors. Apps should only talk to -the drivers, or software installed with a driver package, for which the -driver author has access granted. - -For a capability owner to claim a custom capability, they must do the -following steps: - -1. Send a request to Microsoft Hardware Support Apps Review - () requesting a custom capability. The - request should include the following information: - - Contact information for the PM - - - Contact information for the developer - - - The Company Name - - - The name of the capability (The name of the capability must be - unique and have some associated with the organization of the - party that is claiming the capability) - - - What resources does capability need to access? - - - Any security or privacy concerns that drive the introduction of - this capability - - - Does your capability provide access to data that has privacy - concerns? - - - Include the Windows Store App Publisher ID. You can get this by - creating a skeleton app entry on the Windows Store page. This - [MSDN - article](https://msdn.microsoft.com/en-us/windows/uwp/publish/create-your-app-by-reserving-a-name) - walks you through the process of reserving your App PFN on the - store page - -Microsoft then validates the Capability Owner and the intention of the -custom capability. - -Reply to confirm Custom capability addition request. - -Once approved, the custom capability a unique custom capability string -name in the format **CompanyName.capabilityName\_PublisherID** is -recorded and emailed back to the Capability Owner - -![How to claim a custom capability](images/claim-cc.png) - -*Claiming a Custom Capability* - -## Authoring and Signing an SCCD as a Capability Owner - -After being given the information from an app developer from a request -for access to a custom capability, it is up to the Capability Owner -whether the app developer should get granted this Capability. A -Capability owner must make sure that the certificate hash provided by -app developer can be trusted. - -![Getting an SCCD signed](images/signsccd.png) - -*Getting an SCCD signed* - -After the Capability owner completes the SCCD, it is sent to Microsoft -for signing and returned signed to the Capability Owner. The Capability -Owner then sends it back to the app developer. - -### Limiting an SCCD’s scope - -It is also possible for the owner of a Custom capability to create a -scoped SCCD; for example, a Capability owner may not have completely -vetted an App Developer but would still like to let a developer develop -an UWP. To create such an SCCD, the Custom capability owner can limit -the scope of use of the SCCD by putting *“DeveloperModeOnly”* in the -SCCD file before getting it signed by Microsoft.  A scoped SCCD will -ONLY work on devices in Developer Mode. -```xml - - - - - - - - - - - - - - - -``` - diff --git a/windows-driver-docs-pr/devapps/developing-a-universal-windows-platform-app-with-custom-capabilities.md b/windows-driver-docs-pr/devapps/developing-a-universal-windows-platform-app-with-custom-capabilities.md deleted file mode 100644 index 80c9ae9474..0000000000 --- a/windows-driver-docs-pr/devapps/developing-a-universal-windows-platform-app-with-custom-capabilities.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Developing a Universal Windows Platform app with Custom Capabilities -author: windows-driver-content -description: Guide to developing a UWP app with custom capabilities -keywords: -- Custom , Capabilities -- UWP Apps -- Custom Capabilities -- UWP -- Hardware -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- -# Developing a Universal Windows Platform app with Custom Capabilities - -## Configure Machine - -Before you can begin creating an UWP app, you need to install the latest -version of Visual Studio and create an UWP app project. If you -haven't done that yet, you can [download the tools -here](http://go.microsoft.com/fwlink/p/?LinkId=302196). To get started -with Microsoft Visual Studio, see[ Develop Windows Store apps using -Visual -Studio](https://developer.microsoft.com/en-us/windows/apps/develop). - -### Create a Windows Store account - -A developer account on the Windows Store is required. Hardware partners -will need a Windows Store account that will be different from their -Hardware partner account. You’ll need the publisher name when you author -the app manifest and the device metadata in later steps. You can also -reserve a name for your app once you've created a store profile. - -To create a Windows Store account, go to the [Windows Store apps sign up -page](http://go.microsoft.com/fwlink/p/?LinkId=302197) and click Sign up -now. For more information on how to Create a Windows Store developer -account, see[ Opening a developer -account](accounthttps://docs.microsoft.com/en-us/windows/uwp/publish/opening-a-developer-account). - -## Contacting the Custom Capability Owner - -For an App Developer to develop UWP Apps with custom capabilities, they -must request access to a Custom capability from a Capability Owner. The -request should have the following: - -- App PFN acquired from the Windows Store -- The name of the custom capability -- Signature Hash of the app signing cert which can be generated from - your .cer file using certutil.exe. The certificate must be SHA-256. - -To generate the Signature Hash run: -```bat -C:\Windows\System32\certutil.exe -dump CertificateName.cer -``` -Look for the signature hash near the bottom and ensure it’s SHA256. If -it’s not, you’ll need to use a SHA256 cert to sign your app. It should -look something like the following example hash below. -```text -Signature Hash: -ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4 -``` -The Capability owner reviews the app developer request and chooses to -either approve the request or not. Once approved, the Capability Owner -generates a [Signed Custom Capability Descriptor](custom-capabilities-for-universal-windows-platform-apps.md) with the provided -information and signs it; it is returned to the app developer once -properly signed. - -## Writing an SCCD as Developer - -An app developer can continue developing their apps with Custom -capabilities in "developer mode" while waiting for the Capability owner -to approve their request. Ignore the following in the SCCD on a desktop -PC in developer mode: - -- Catalog entry. It’s set it to FFFF. - -- Certificate Signature Hash in the authorized entity. While it will - neither enforced nor validated, please put a 64-char sequence. - -## Granting Custom Capability Access to System Software - -Currently, there are two types of system software that you can grant -access to using Custom Capabilities: RPC Endpoints (from within an NT -Service) and Drivers. - -![Custom Capability Architecture Diagram](images/cc-arch.png) - -*Custom Capability Architecture Diagram* - -### Granting custom capability access to an RPC Endpoint - -When an UWP declares a custom capability in its app manifest, it will at -a later point contain the SID form of the Custom capability in its -process token at runtime. By default, RPC endpoints don’t allow UWP’s -(AppContainer processes) to connect to them so some security must be set -at the endpoint to allow access to UWP’s with the correct Custom -capabilities. The following steps are taken to do so: - -1. Convert the custom capability name to a SID - -2. Create a Security Descriptor to the SID of the Custom capability along -with all other needed SID. For more information on creating a Security -Descriptor follow the example[here](https://msdn.microsoft.com/en-us/library/windows/desktop/aa446595(v=vs.85).aspx). - -3. Create an RPC endpoint with the Security Descriptor from above. - -### Granting Custom Capability Access to a Driver - -To allow a UWP app to communicate with a custom driver, you must use -**Windows.Devices.Custom**. You’ll need to have the Driver itself (or -driver INF file) set the property -**DEVPKEY\_DeviceInterface\_UnrestrictedAppCapabilities** of type -*DEVPKEY\_STRING\_LIST* on the Device Interface to grant your custom -capability access. In this property, you can specify one or more custom -capabilities. - -There are two methods for granting custom capability access to a driver -either via INF or with just the driver code as seen below. - -*INF Method* -``` -[WDMPNPB003_Device.NT.Interfaces] -AddInterface= {B0823231-61F1-4685-85CA-8DF9DDDEBF6E},,AddInterfaceSection - -[AddInterfaceSection] -AddProperty= AddInterfaceSection.AddProps - -[AddInterfaceSection.AddProps] -; DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities -{026e516e-b814-414b-83cd-856d6fef4822}, 8, 0x2012,, “CompanyName.myCustomCapabilityNameTBD_YourStorePubId” -``` -*Driver Method* -```c++ -WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = {}; -WCHAR customCapabilities[] = L”CompanyName.yourCustomCapabilityNameTBD_YourStorePubId\0”; - -WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT( - &PropertyData, - &m_VendorDefinedSubType, - &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities); - -Status = WdfDeviceAssignInterfaceProperty( - m_FxDevice, - &PropertyData, - DEVPROP_TYPE_STRING_LIST, - ARRAYSIZE(customCapabilities), - reinterpret_cast(customCapabilities)); - -``` - -## Adding a Custom capability to App Package Manifest - -Capabilities must be declared in your Universal Windows Platform (UWP) -app's [package -manifest](https://msdn.microsoft.com/library/windows/apps/BR211474) to -access APIs or resources protected with capabilities. An app package -manifest is an XML document that contains information needed by the -system to deploy, display, and update a UWP. Inside an app package -manifest, an app must contain information such as package identity, -dependencies, required capabilities, visual elements, and extensibility -points. Every app package must include one package manifest. - -The app developer must modify the app package manifest to include a -capabilities attribute that declares the custom capabilities in a -similar fashion to below. -```xml - - - - -``` -Afterward, the App developer includes the SCCD file from the previous -steps into the appx package. The signed custom capability descriptor -(SCCD) is a signed XML file that goes in the package root of the appx -package. It has the file extension of ".sccd." They can do this by -simply copying the SCCD file to the root of an app project folder. Once -located in the root, go through Visual Studio’s solution explorer, -right-click on “project-> Add -> Existing Item…” to add the SCCD -to your project; you may also use the shortcut (Shift + Alt + A). - -![Adding an SCCD file into the appx package](images/addSCCDToAppx.png) - -*Adding an SCCD file into the appx package* - -Now you can create your appx package using your preferred method. If -using VS, right-click the project, select Store, then Create App -Packages. At installation time, every capability declared in an app -manifest is checked if it also is defined the SCCD by the Operating -System. - -## Deploying and debugging UWPs - -Microsoft Visual Studio allows you to deploy and debug your apps on a -variety of Windows 10 devices. - -You can enable a device for development, or just for sideloading. -*Windows Store apps* are the default setting. If you aren't development -apps or using special internal apps issued by your company, keep this -setting active. - -- *Developer mode* lets you sideload apps, and run apps from Visual - Studio in debug mode. - -- *Sideloading* is installing and then running or testing an app that - has not been certified by the Windows Store. For example, an app - that is internal to your company only. - -By default, you can only install Universal Windows Platform (UWP) apps -from the Windows Store. Changing these settings to use developer -features can change the level of security of your device. You should not -install apps from unverified sources. - -### Picking a deployment target - -To pick a target, go to the debug target drop-down next to the **Start -Debugging** button and choose which target to deploy your app to. After -the target is selected, select **Start Debugging (F5)** to deploy and -debug on that target, or select **Ctrl+F5** to just deploy to that -target. - -![Pick Target](images/pickTarget.png) - -**Note**: At the current time there is no support -for UWP’s with Custom Capabilities on mobile platforms. - -### Sideload an UWP with Custom Capabilities - -Typically, companies or schools that need to install custom apps on -managed devices without going through the Windows Store use the Sideload -apps setting. In this case, it's common for the organization to enforce -a policy that disables the *Windows Store apps* setting, as shown -previously in the image of the settings page. The organization also -provides the required certificate and install location to sideload apps. -For more info, see the TechNet articles [Sideload apps in Windows -10](https://technet.microsoft.com/library/mt269549.aspx) and [Get -started with app deployment in Microsoft -Intune](https://technet.microsoft.com/library/dn646955.aspx). - -UWP Users will be able to side-load and install a properly signed UWP -onto on a system if it passes the Trust Model check at install time. diff --git a/windows-driver-docs-pr/devapps/faq-on-custom-capabilities.md b/windows-driver-docs-pr/devapps/faq-on-custom-capabilities.md index 84ba938a04..0e033341d1 100644 --- a/windows-driver-docs-pr/devapps/faq-on-custom-capabilities.md +++ b/windows-driver-docs-pr/devapps/faq-on-custom-capabilities.md @@ -1,7 +1,7 @@ --- -title: FAQ on custom capabilities +title: FAQ on Custom Capabilities author: windows-driver-content -description: Describes custom capabilities for Hardware Support Apps (HSA) and how they differ from other capabilities. +description: Describes Custom Capabilities for Hardware Support Apps (HSA) and how they differ from other capabilities. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -9,9 +9,9 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# FAQ on custom capabilities +# FAQ on Custom Capabilities -## How are custom capabilities different from other capabilities? +## How are Custom Capabilities different from other capabilities? 1) 3rd party Microsoft partners can define new capabilities. @@ -20,14 +20,16 @@ ms.technology: windows-devices 3) App authorization to use the capability verifies during the app installation instead of when uploaded to the store. -## What’s the difference between UWP’s with Custom Capabilities and DCA’s (Device Companion Apps)? +## What is the best way to install a UWP app with Custom Capabilities? +The suggested method to install a UWP app with Custom Capabilities is to pre-install the app using DISM (Deployment Image Servicing and Management). For more information on DISM's see [DISM - Deployment Image Servicing and Management](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/dism---deployment-image-servicing-and-management-technical-reference-for-windows). +## What’s the difference between UWP apps with Custom Capabilities and DCA’s (Device Companion Apps)? -| | **DCA** | **RPAL** | **UWP App with Custom Capabilities**| -|---------------------------|----------------------------------------------------------|-------------------------------------------------------------|-------------------------------------| -|Communication|Device Scenario APIS (image capture, scanning, etc.)
Device protocol APIs (USB, HID, etc.)
Customer driver access| Blanket access to APIS, Drivers, Services|DCA support + NT Services | -|Trust Model|Defined at a “container” level
The system's OEM must submit apps for internal components|Defined at a system level
The system's OEM must submit apps for internal components|Defined at a component level
IHVs own the trust boundaries for their components| -|Automatic App Acquisition |Available for peripherals | Not available |Available for all hardware | -|Deployment Dependencies |WU: Driver package
Store: App|N/A – preload only|WU: Driver package
Store: App | +| | **DCA** | **UWP app with Custom Capabilities**| +|---------------------------|----------------------------------------------------------|-------------------------------------| +|Communication|Device Scenario APIS (image capture, scanning, etc.)
Device protocol APIs (USB, HID, etc.)
Customer driver access| +|Trust Model|Defined at a “container” level
The system's OEM must submit apps for internal components|Defined at a system level
The system's OEM must submit apps for internal components| +|Automatic App Acquisition |Available for peripherals |Available for all hardware | +|Deployment Dependencies |WU: Driver package
Store: App|WU: Driver package
Store: App | diff --git a/windows-driver-docs-pr/devapps/hardware-access-for-universal-windows-platform-apps.md b/windows-driver-docs-pr/devapps/hardware-access-for-universal-windows-platform-apps.md index bbd3d57235..334ba74106 100644 --- a/windows-driver-docs-pr/devapps/hardware-access-for-universal-windows-platform-apps.md +++ b/windows-driver-docs-pr/devapps/hardware-access-for-universal-windows-platform-apps.md @@ -1,7 +1,7 @@ --- title: Hardware access for Universal Windows Platform apps author: windows-driver-content -description: Writing apps with custom capabilities +description: Writing apps with Custom Capabilities keywords: - Custom , Capabilities - UWP Apps @@ -18,35 +18,21 @@ ms.technology: windows-devices # Hardware access for Universal Windows Platform apps ## Overview -The extensibility of the Windows platform has led to the creation of a -diverse ecosystem of device builders where innovative differentiation is -key to success for these device manufacturers, which enables unique -hardware and software experiences. [Universal Windows Platform + +This section describes how to pair a device-specific [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) -applications create a broad range of scenarios such as to control -hardware device settings and provide a diverse app platform available on -any device running Windows 10. - -Device and System vendors often provide their users with applications -that allow them to have some control over the functionality of their -hardware; previously apps with such functionality were not made as UWP -apps as they were unable to get access to system software from the app -container. They would come pre-installed or become installed with a -driver by a Windows Update or as an installation downloaded from the -internet. A problem would be that these applications couldn’t update -outside of an updater app, often required a co-installer, and could very -easily get out of sync. - -For more information about developing specific types of UWP apps, see -[Develop UWP -apps](https://developer.microsoft.com/en-us/windows/apps/develop)**.** +application with a device on Windows 10. + +After the app is installed, you can easily update it through the Windows Store. + +To associate the UWP app with your device, you'll need to create a Custom Capability. ## In this Section |Topic|Description| |-----|-----------| -|[Custom Capabilities for Universal Windows Platform Apps](custom-capabilities-for-universal-windows-platform-apps.md)| This section goes over what Custom Capabilities are and how they can be used in UWP Apps.| -|[Developing a Universal Windows Platform app with Custom Capabilities](developing-a-universal-windows-platform-app-with-custom-capabilities.md)| This section goes over how to use Custom Capabilities in developing UWP Apps.| -|[FAQ on custom capabilities](FAQ-on-custom-capabilities.md)| This Section goes over some of the frequently asked question about custom capabilities.| +|[Creating a custom capability to pair a driver with a Hardware Support App (HSA)](creating-a-custom-capability-to-pair-driver-with-hsa.md)| This section goes over what Custom Capabilities are and how they can be used in UWP Apps.| +|[Using a custom capability to pair a Hardware Support App (HSA) with a driver](using-a-custom-capability-to-pair-hsa-with-driver.md)| This section goes over how to use Custom Capabilities in developing UWP Apps.| +|[FAQ on Custom Capabilities](FAQ-on-custom-capabilities.md)| This Section goes over some of the frequently asked question about Custom Capabilities.| ## See Also @@ -58,6 +44,8 @@ apps](https://developer.microsoft.com/en-us/windows/apps/develop)**.** - [Custom Capability Sample App](http://go.microsoft.com/fwlink/p/?LinkId=846904) +- [Custom Capability Driver Sample](https://aka.ms/customcapabilitydriversample ) + - [Sideload apps in Windows 10](https://technet.microsoft.com/library/mt269549.aspx) -- [FAQ on custom capabilities](FAQ-on-custom-capabilities.md) +- [FAQ on Custom Capabilities](FAQ-on-custom-capabilities.md) diff --git a/windows-driver-docs-pr/devapps/how-to-customize-print-settings.md b/windows-driver-docs-pr/devapps/how-to-customize-print-settings.md index bad4cf9aed..0669c28a82 100644 --- a/windows-driver-docs-pr/devapps/how-to-customize-print-settings.md +++ b/windows-driver-docs-pr/devapps/how-to-customize-print-settings.md @@ -1,6 +1,6 @@ --- title: How to customize print settings (Windows Store device apps) -description: This topic introduces the advanced print settings flyout, and shows how the C\ version of the Print settings and print notifications sample replaces the default flyout with a custom flyout. +description: This topic introduces the advanced print settings flyout, and shows how the C# version of the Print settings and print notifications sample replaces the default flyout with a custom flyout. ms.assetid: 099BD9B2-1AA6-49A5-AB84-0AF6FA0EFB26 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devapps/how-to-display-printer-status.md b/windows-driver-docs-pr/devapps/how-to-display-printer-status.md index 85b0c86ac9..2365030efe 100644 --- a/windows-driver-docs-pr/devapps/how-to-display-printer-status.md +++ b/windows-driver-docs-pr/devapps/how-to-display-printer-status.md @@ -1,6 +1,6 @@ --- title: How to display printer status in a Windows Store device app -description: This topic uses the C\ version of the Print settings and print notifications sample to demonstrate how to query the printer status and display it. +description: This topic uses the C# version of the Print settings and print notifications sample to demonstrate how to query the printer status and display it. ms.assetid: 91AD1B3B-0D0B-4FB6-8A0F-4943143D8FCE ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devapps/images/pickTarget.png b/windows-driver-docs-pr/devapps/images/pickTarget.png deleted file mode 100644 index 07a980ffee..0000000000 Binary files a/windows-driver-docs-pr/devapps/images/pickTarget.png and /dev/null differ diff --git a/windows-driver-docs-pr/devapps/index.md b/windows-driver-docs-pr/devapps/index.md index 3fc8311de9..514fc82c15 100644 --- a/windows-driver-docs-pr/devapps/index.md +++ b/windows-driver-docs-pr/devapps/index.md @@ -72,6 +72,11 @@ If you're looking for info about Windows Store mobile broadband apps, see [Mobil

[Automatic installation for Windows Store device apps](auto-install-for-windows-store-device-apps.md)

This topic describes how automatic installation works and how the app, metadata, and drivers can be updated and uninstalled.

+ + +

[Hardware access for Universal Windows Platform apps](hardware-access-for-universal-windows-platform-apps.md)

+

This topic introduces getting Hardware access for Universal Windows Platform apps.

+ diff --git a/windows-driver-docs-pr/devapps/using-a-custom-capability-to-pair-hsa-with-driver.md b/windows-driver-docs-pr/devapps/using-a-custom-capability-to-pair-hsa-with-driver.md new file mode 100644 index 0000000000..da5185985e --- /dev/null +++ b/windows-driver-docs-pr/devapps/using-a-custom-capability-to-pair-hsa-with-driver.md @@ -0,0 +1,106 @@ +--- +title: Using a custom capability to pair a Hardware Support App (HSA) with a driver +author: windows-driver-content +description: Guide to developing a Hardware Support App (HSA) with custom capabilities +keywords: +- Custom , Capabilities +- UWP Apps +- custom capabilities +- UWP +- Hardware +ms.author: windowsdriverdev +ms.date: 08/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a custom capability to pair a Hardware Support App (HSA) with a driver + +This topic describes how to associate your [Universal Windows Platform (UWP)](https://msdn.microsoft.com/50a5605e-3a91-41db-800a-9180717c1e86) app with a driver or [RPC (Remote Procedure Call)](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378651) endpoint using a custom capability. When paired in this fashion, the UWP app is referred to as a Hardware Support App (HSA). + +The steps required by the owner of the driver or RPC endpoint are described in [Creating a custom capability to pair a driver with a Hardware Support App (HSA)](creating-a-custom-capability-to-pair-driver-with-hsa.md). + +Before you get started, install the latest version of Visual Studio and create an UWP app project. For more info, see [Develop Windows Store apps using Visual Studio](https://developer.microsoft.com/en-us/windows/apps/develop). + +## Create a Windows Store account + +A developer account on the Windows Store is required. Hardware partners will need a Windows Store account that is different from their Hardware partner account. You'll need the publisher name when you author the app manifest and the device metadata in later steps. You can also reserve a name for your app once you've created a store profile. + +To create a Windows Store account, go to the [Windows Store apps sign up page](http://go.microsoft.com/fwlink/p/?LinkId=302197). For more info, see [Opening a developer account](https://docs.microsoft.com/windows/uwp/publish/opening-a-developer-account). + +## Choosing a programming language for the app + +If your app will communicate with a driver, you can use [Windows.Devices.Custom](https://docs.microsoft.com/uwp/api/windows.devices.custom), which is part of the WinRT API, and therefore available in JavaScript, C#, and C++. + +If your app will communicate with an NT service, then you need to use the RPC APIs. Because RPC APIs are Win32 APIs that are not available in WinRT, you need to either use C++, or wrap the RPC calls using .NET interop (PInvoke). For more info, see [Calling Native Functions from Managed Code](https://docs.microsoft.com/cpp/dotnet/calling-native-functions-from-managed-code). + +## Contact the custom capability owner + +Now you're ready to request access to a custom capability from a capability owner. You'll need to gather the following info: + +- App PFN (Package Family Name) from the Windows Store +- Name of the custom capability +- Signature Hash of the app signing cert which can be generated from your .cer file using certutil.exe. The certificate must be SHA-256. + +To generate the signature hash, run `C:\Windows\System32\certutil.exe -dump CertificateName.cer`. + +Look for the signature hash near the bottom and ensure it's SHA256. Otherwise, use a SHA256 cert to sign your app. The result should look like this: + +``` +Signature Hash: +ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4 +``` + +The capability owner uses this info to generate a [Signed custom capability Descriptor](creating-a-custom-capability-to-pair-driver-with-hsa.md) file and sends this file to the app developer. + +The app developer can continue developing an app with custom capabilities in developer mode while waiting for the capability owner to approve the request. For example, use the following in the SCCD on a desktop PC in [Developer Mode](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development): + +- Catalog entry in the SCCD. + + ```xml + FFFF + ``` +- Certificate Signature Hash in the authorized entity entry in the SCCD. While it is + neither enforced nor validated, please put a 64-char sequence. + + ```xml + + ``` + +## Add a custom capability to the App Package Manifest + +Next, modify the app [package manifest](https://msdn.microsoft.com/library/windows/apps/BR211474) to include a capabilities attribute: + +```xml + + + + +``` +Then copy the SCCD file to the package root of the appx package. In Visual Studio's solution explorer, right-click on “project-> Add -> Existing Item…” to add the SCCD to your project. + +![Adding an SCCD file into the appx package](images/addSCCDToAppx.png) + +Finally, right click the project, select **Store**, then **Create App Packages**. + +**Note**: There is no support for UWP apps with custom capabilities on mobile platforms. + +## Troubleshooting + +When the target machine is in Developer Mode, you can try the following steps to debug app registration failure: + +1. Remove the custom capability entry from your AppX manifest. +2. Build your app and deploy it. +3. In a PowerShell window, type `Get-AppxPackage`. +4. Look for your app in the list and verify the exact package family name for your app. +5. Update your SCCD with the package family name. +6. Add the custom capability entry back into your AppX manifest. +7. Rebuild and deploy. + +## See Also + +* [Enable your device for development](https://docs.microsoft.com/windows/uwp/get-started/enable-your-device-for-development) +* [Custom Capability sample](https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/CustomCapability) +* [Getting Started with Universal Windows drivers](../develop/getting-started-with-universal-drivers.md) +* [Pairing a driver with a Universal Windows Platform (UWP) app](../install/pairing-app-and-driver-versions.md) diff --git a/windows-driver-docs-pr/devapps/what-s-new.md b/windows-driver-docs-pr/devapps/what-s-new.md index c561b83b4f..001878de64 100644 --- a/windows-driver-docs-pr/devapps/what-s-new.md +++ b/windows-driver-docs-pr/devapps/what-s-new.md @@ -21,7 +21,7 @@ This section provides a glimpse of what's new for Windows Store device apps. For ## What's new for Windows 10 -With Windows 10, there are no changes to the Windows Store device app functionality. The Windows 8.1 processes for building, testing, and submitting Windows Store device apps will continue to work with Windows 10. However, it is recomended to develop a Universal Windows Platform app with Custom Capabilities. For more info, see [Developing a Universal Windows Platform app with Custom Capabilities](developing-a-universal-windows-platform-app-with-custom-capabilities.md) +With Windows 10, there are no changes to the Windows Store device app functionality. The Windows 8.1 processes for building, testing, and submitting Windows Store device apps will continue to work with Windows 10. However, it is recomended to develop a Universal Windows Platform app with Custom Capabilities. For more info, see [Using a custom capability to pair a Hardware Support App (HSA) with a driver](using-a-custom-capability-to-pair-hsa-with-driver.md) ## Device metadata wizard diff --git a/windows-driver-docs-pr/devapps/working-with-print-notifications.md b/windows-driver-docs-pr/devapps/working-with-print-notifications.md index 8db0e9b5c8..84336ef508 100644 --- a/windows-driver-docs-pr/devapps/working-with-print-notifications.md +++ b/windows-driver-docs-pr/devapps/working-with-print-notifications.md @@ -1,6 +1,6 @@ --- title: Working with print notifications in a Windows Store device app -description: This topic introduces print notifications, and shows how the C\ version of the Print settings and print notifications sample uses a background task to respond to print notification. +description: This topic introduces print notifications, and shows how the C# version of the Print settings and print notifications sample uses a background task to respond to print notification. ms.assetid: 39A06A8A-5603-44AB-8884-C12B8E2F1A45 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/develop/TOC.md b/windows-driver-docs-pr/develop/TOC.md index 99899f9880..76e642f231 100644 --- a/windows-driver-docs-pr/develop/TOC.md +++ b/windows-driver-docs-pr/develop/TOC.md @@ -1,16 +1,17 @@ # [Developing, Testing, and Deploying Drivers](index.md) # [Getting Started with Universal Drivers](getting-started-with-universal-drivers.md) -# [Validating Universal Drivers](validating-universal-drivers.md) -# [Installing a Universal Driver](installing-a-universal-driver.md) -# [Target platform on MSDN driver reference pages](windows-10-editions-for-universal-drivers.md) -# [Driver convergence model for Windows 10](driver-model-convergence.md) +## [Validating Universal Drivers](validating-universal-drivers.md) +## [Universal Driver Scenarios](universal-driver-scenarios.md) +## [Debugging a Universal driver](debugging-a-universal-driver.md) +## [Target platform on MSDN driver reference pages](windows-10-editions-for-universal-drivers.md) +## [Driver convergence model for Windows 10](driver-model-convergence.md) # [Creating a New Device Function Driver](creating-a-new-driver.md) # [Creating a New Filter Driver](creating-a-new-filter-driver.md) # [Creating a New Software Driver](creating-a-new-software-driver.md) # [Creating a Driver From Existing Source Files](creating-a-driver-from-existing-source-files.md) # [Building a Driver with the WDK](building-a-driver.md) ## [Building Drivers for Different Versions of Windows](building-drivers-for-different-versions-of-windows.md) -## [Installing the Enterprise WDK 10](installing-the-enterprise-wdk.md) +## [Using the Enterprise WDK 10](using-the-enterprise-wdk.md) ## [Installing the WDK 8.1 Build Environment in a Lab](installing-the-wdk-build-environment-in-a-lab.md) ## [Using the Microsoft C Runtime with User-Mode Drivers and Desktop Apps](using-the-microsoft-c-runtime-with-user-mode-drivers-and-apps.md) ## [Avoiding Floating Point Errors in Custom Build Environments](avoiding-floating-point-errors-in-custom-build-environments.md) @@ -39,6 +40,7 @@ ## [UMDF Verifier Properties for Driver Package Projects](umdf-verifier-properties-for-driver-package-projects.md) ## [Inf2Cat Properties for Driver Package Projects](inf2cat-properties-for-driver-package-projects.md) ## [How to create a custom driver installation script](create-a-custom-driver-installation-script.md) +## [Installing a driver on Windows 10 Mobile](using-pkggen.md) # [Debugging a Driver](debugging-a-driver.md) # [Testing a Driver](testing-a-driver.md) ## [Tips for testing drivers during development](strategies-for-testing-drivers-during-development.md) @@ -55,4 +57,3 @@ ## [Creating a log file for the code analysis tool](creating-a-log-file-for-the-code-analysis-tool.md) ## [Creating a log file for Static Driver Verifier](creating-a-log-file-for-static-driver-verifier.md) # [Distributing a driver package](distributing-a-driver-package-win8.md) - diff --git a/windows-driver-docs-pr/develop/avoiding-floating-point-errors-in-custom-build-environments.md b/windows-driver-docs-pr/develop/avoiding-floating-point-errors-in-custom-build-environments.md index 4915ec9f94..ca85708c56 100644 --- a/windows-driver-docs-pr/develop/avoiding-floating-point-errors-in-custom-build-environments.md +++ b/windows-driver-docs-pr/develop/avoiding-floating-point-errors-in-custom-build-environments.md @@ -29,7 +29,7 @@ To avoid these problem with floating-point calculations, add the **/kernel** fla In addition, if you build a driver using the WDK and the Visual Studio Professional 2012 development environment, or use MSBuild, in a Visual Studio Command prompt window, the Microsoft provided platform toolset (**WindowsKernelModeDriver8.0**) sets the **/kernel** flag. As a result, floating-point generation errors are avoided. -``` syntax +``` msbuild myProject.vcxproj /p:PlatformToolset=WindowsKernelModeDriver8.0 ``` diff --git a/windows-driver-docs-pr/develop/building-a-driver.md b/windows-driver-docs-pr/develop/building-a-driver.md index eedfb79f24..888030d416 100644 --- a/windows-driver-docs-pr/develop/building-a-driver.md +++ b/windows-driver-docs-pr/develop/building-a-driver.md @@ -1,7 +1,7 @@ --- ms.assetid: f5676c9c-b582-47d0-9b7c-02b6443103ad title: Building a Driver with the WDK -description: This topic describes how to build a driver with the Windows Driver Kit \(WDK\). +description: This topic describes how to build a driver with the Windows Driver Kit (WDK). ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -41,8 +41,8 @@ The default Solution build configuration is **Debug** and **Win32**. In versions 1. Ensure that you have the same version of SDK and WDK installed on your computer. 2. Open the driver project or solution in Visual Studio. 3. Right-click the solution in the **Solutions Explorer** and select **Configuration Manager**. -4. From the **Configuration Manager**, select the Active Solution Configuration (for example, **Debug** or **Release**) and the Active Solution Platform (for example, **Win32**) that correspond to the type of build you are interested in. -5. Select the target operating system for which to build the driver. Navigate to the project properties in **Driver > General**, and set the **TargetVersion** property. +4. From the **Configuration Manager**, select the **Active solution configuration** (for example, **Debug** or **Release**) and the **Active solution platform** (for example, **Win32**) that correspond to the type of build you are interested in. +5. Right click the Avshws project and select **Properties**. Navigate to **Driver Settings > General**, and set **Target OS Version** and **Target Platform**. 6. Configure the project properties for your driver or driver package. You can set properties for deployment, driver signing, or other tasks. For more information, see [Configuring project properties for your driver and driver package](#configure_project_props). 7. From the **Build** menu, click **Build Solution** (**Ctrl+Shift+B**). @@ -61,19 +61,19 @@ You can build a driver from the command line using the **Visual Studio Command P For example, to perform a clean build of a Visual Studio driver project called MyDriver.vcxproj using the default Platform and Configuration, navigate to the project directory and enter the following MSBuild command: - ``` syntax + ``` msbuild /t:clean /t:build .\MyDriver.vcxproj ``` **Syntax** - To specify a specific configuration and platform, use the following command syntax: - ``` syntax + ``` msbuild /t:clean /t:build ProjectFile /p:Configuration= /p:Platform=architecture /p:TargetPlatformVersion=a.b.c.d /p:TargetVersion=OS ``` For example, the following command builds a Universal Windows driver for the "Debug" configuration, "Win32" platform, and for Windows 10. - ``` syntax + ``` msbuild /t:clean /t:build .\MyDriver.vcxproj /p:Configuration="Debug" /p:Platform=Win32 /p:TargetVersion=”Windows10” /p:TargetPlatformVersion=”10.0.10010.0” ``` @@ -122,7 +122,7 @@ You can set properties for an individual driver or for an entire driver package. [WPP Preprocessor (WPP Tracing)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff556201) -

[Inf2Cat Properties for Driver Package Projects](inf2cat-properties-for-driver-package-projects.md) (see the [Inf2Cat](https://devtest.inf2cat) tool)

+

[Inf2Cat Properties for Driver Package Projects](inf2cat-properties-for-driver-package-projects.md) (see the [Inf2Cat](../devtest/inf2cat.md) tool)

diff --git a/windows-driver-docs-pr/develop/building-a-universal-driver.md b/windows-driver-docs-pr/develop/building-a-universal-driver.md new file mode 100644 index 0000000000..59f9098e9d --- /dev/null +++ b/windows-driver-docs-pr/develop/building-a-universal-driver.md @@ -0,0 +1,35 @@ +# Building a Universal Windows driver + +You can use Microsoft Visual Studio 2015 in conjunction with Windows Driver Kit (WDK) 10 to build drivers for desktop, mobile, or universal. You can download kits and tools from the [Windows Hardware Dev Center](http://go.microsoft.com/fwlink/p/?LinkId=524487). + +In many cases, you can recompile a legacy kernel-mode driver as a Universal Windows driver, as long as the driver does not work with any user-mode components. Legacy WDM and KMDF drivers should recompile as Universal Windows drivers targeting Windows 10 with no conversion required. + +In contrast, existing user-mode drivers may require modification to compile as Universal Windows drivers. Specifically, your driver package must not have any dependencies outside of UWP. For example, only some of the Win32 APIs are part of UWP. + +## Converting an existing driver project to a Universal Windows driver project + +1. In Visual Studio 2015, open the existing driver project. +2. In the Solution Explorer pane, right-click the solution and choose **Configuration Manager**. Set the target operating system to Windows 10. +3. Right-click the driver project and choose **Properties**. Under Configuration Properties->Driver, verify that **Target Platform** is set to **Universal**. Other choices include **Desktop**, to build a driver that runs on Windows 10 for desktop editions only, and **Mobile**, to build a driver that runs on Windows 10 Mobile only. +4. Build the driver. You might see linker errors. +5. Fix the errors one by one by going through the error log. Refer to individual reference pages in the documentation for possible alternate APIs. If replacements are not available, you may need to redesign your driver. + +## Creating a New Universal Windows driver Project in Microsoft Visual Studio + +1. Create a new driver from a template (**File>New Project->Templates->Visual C++->Windows Driver->WDF**) and choose either **User Mode Driver (UMDF V2)** or **Kernel Mode Driver (KMDF)**. +2. After you create the project, in the Solution Explorer pane, right-click the solution and choose **Configuration Manager**. Set **Active solution configuration** to the desired target Windows version, and set **Active solution platform** to **Win32** or **x64**. If **ARM** is not listed, choose **<New...>** to build for ARM. + + If you choose Windows 10, the driver model defaults to **Universal**. + + To change driver model manually, right-click the driver project and choose Properties. Under **Configuration Properties->Driver Settings->General**, find the **Target Platform** entry. Choose **Universal**, **Desktop**, or **Mobile**. Microsoft Visual Studio uses this setting to determine what libraries to link against. + + **Note**  You cannot build a Universal Windows driver for Windows versions earlier than Windows 10. +3. You might need to modify the .inf file to specify the provider, specified as an %*ManufacturerName*% token that is expanded later in the INF file's [**Strings**](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff547485) section. For example: + + ``` + Provider="Contoso" + ``` + +4. You can now build the solution. Visual Studio links against the required libraries and generates a .cat file, an .inf file, and a driver binary. + +For information about the configuration settings you can use in Visual Studio when building your driver, see [Building a Driver with the WDK](building-a-driver.md). diff --git a/windows-driver-docs-pr/develop/building-drivers-for-different-versions-of-windows.md b/windows-driver-docs-pr/develop/building-drivers-for-different-versions-of-windows.md index 26e522f805..f078a2f7ba 100644 --- a/windows-driver-docs-pr/develop/building-drivers-for-different-versions-of-windows.md +++ b/windows-driver-docs-pr/develop/building-drivers-for-different-versions-of-windows.md @@ -1,7 +1,7 @@ --- ms.assetid: 176A3794-E9E9-46C3-B242-422843436D2A title: Building Drivers for Different Versions of Windows -description: If you are writing drivers for different versions of Windows, the following section provides some guidelines about how you should build those drivers using the Windows Driver Kit \(WDK\) 8.1 or WDK 8, Visual Studio, and MSBuild. +description: If you are writing drivers for different versions of Windows, the following section provides some guidelines about how you should build those drivers using the Windows Driver Kit (WDK) 8.1 or WDK 8, Visual Studio, and MSBuild. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -33,7 +33,7 @@ If you are [writing drivers for different versions of Windows](https://msdn.micr **Using MSBuild:** - ``` syntax + ``` msbuild /p:KernelBufferOverflowLib="C:\Program Files (x86)\Windows Kits\8.1\Lib\win8\km\x64\BufferOverflowK.lib" /p:platform=x64 /p:Configuration="Win8 Release" myDriver.sln ``` diff --git a/windows-driver-docs-pr/develop/converting-wdk-8-1-projects-to-wdk-10.md b/windows-driver-docs-pr/develop/converting-wdk-8-1-projects-to-wdk-10.md index 4b9ff88e34..ea79964f16 100644 --- a/windows-driver-docs-pr/develop/converting-wdk-8-1-projects-to-wdk-10.md +++ b/windows-driver-docs-pr/develop/converting-wdk-8-1-projects-to-wdk-10.md @@ -1,7 +1,7 @@ --- ms.assetid: 51CD05AB-2626-4E27-AA08-09547D546218 title: Converting WDK 8.1 Projects to WDK 10 -description: This topic describes how to convert a driver project that was created using Microsoft Visual Studio 2013 and Windows Driver Kit \(WDK\) 8.1 to a driver project that builds in Microsoft Visual Studio 2015 with the Windows Driver Kit \(WDK\) 10. +description: How to convert a driver project created with Microsoft Visual Studio 2013 and the Windows Driver Kit (WDK) 8.1 to a driver project that builds in Microsoft Visual Studio 2015 with the Windows Driver Kit (WDK) 10. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/creating-a-driver-verification-log.md b/windows-driver-docs-pr/develop/creating-a-driver-verification-log.md index 373c5b097c..467f3d4d9a 100644 --- a/windows-driver-docs-pr/develop/creating-a-driver-verification-log.md +++ b/windows-driver-docs-pr/develop/creating-a-driver-verification-log.md @@ -1,7 +1,7 @@ --- ms.assetid: 5EB802D0-1894-4D64-ACB0-77B848B7E644 title: Creating a Driver Verification Log -description: The Windows Server 2012&\#32;Hardware Certification Program requires a Driver Verification Log \(DVL\) for all applicable driver submissions. +description: The Windows Server 2012 Hardware Certification Program requires a Driver Verification Log (DVL) for all applicable driver submissions. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -39,19 +39,19 @@ For the most up-to-date information about the Code Analysis tool, Static Driver You can also create the driver verification log from a Visual Studio Command Prompt window. Set up the environment by running one of the following batch files. -``` syntax +``` "C:\Program Files\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` -Or- -``` syntax +``` "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` Create the driver verification log. -``` syntax +``` msbuild.exe /target:dvl /p:Configuration="Win8 Release" /P:Platform=x64 ``` diff --git a/windows-driver-docs-pr/develop/creating-a-log-file-for-static-driver-verifier.md b/windows-driver-docs-pr/develop/creating-a-log-file-for-static-driver-verifier.md index 97f0284f08..d73a1eef45 100644 --- a/windows-driver-docs-pr/develop/creating-a-log-file-for-static-driver-verifier.md +++ b/windows-driver-docs-pr/develop/creating-a-log-file-for-static-driver-verifier.md @@ -1,7 +1,7 @@ --- ms.assetid: EDA6357A-D18D-439D-A0DD-050BA51E1A79 title: Creating a log file for Static Driver Verifier -description: The Windows Server 2012&\#32;Hardware Certification Program requires a Driver Verification Log \(DVL\) for all applicable driver submissions. +description: The Windows Server 2012 Hardware Certification Program requires a Driver Verification Log (DVL) for all applicable driver submissions. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -34,19 +34,19 @@ For the most up-to-date information about Static Driver Verifier and the Driver You can also run Static Driver Verifier from a Visual Studio Command Prompt window. Set up the environment by running one of the following batch files. -``` syntax +``` "C:\Program Files\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` -Or- -``` syntax +``` "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` Run Static Driver Verifier. -``` syntax +``` msbuild.exe /p:Configuration="Win8 Release" /p:Platform=x64 /target:sdv /p:inputs="/clean" msbuild.exe /p:Configuration="Win8 Release" /p:Platform=x64 /target:sdv /p:inputs="/check:default.sdv" ``` diff --git a/windows-driver-docs-pr/develop/creating-a-log-file-for-the-code-analysis-tool.md b/windows-driver-docs-pr/develop/creating-a-log-file-for-the-code-analysis-tool.md index 7cb3763896..3031616815 100644 --- a/windows-driver-docs-pr/develop/creating-a-log-file-for-the-code-analysis-tool.md +++ b/windows-driver-docs-pr/develop/creating-a-log-file-for-the-code-analysis-tool.md @@ -1,7 +1,7 @@ --- ms.assetid: 4985B206-9E7F-45FE-9067-7CFD15A7AAAD title: Creating a log file for the code analysis tool -description: The Windows Server 2012&\#32;Hardware Certification Program requires a Driver Verification Log \(DVL\) for all applicable driver submissions. +description: The Windows Server 2012 Hardware Certification Program requires a Driver Verification Log (DVL) for all applicable driver submissions. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -28,19 +28,19 @@ Code Analysis for Drivers is a compile-time static verification tool that detect You can also run the Code Analysis tool from a Visual Studio Command Prompt window. Set up the environment by running one of the following batch files. -``` syntax +``` "C:\Program Files\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` -Or- -``` syntax +``` "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x64 ``` Run the Code Analysis tool. -``` syntax +``` msbuild.exe /p:Configuration="Win8 Release" /P:Platform=x64 /target:clean msbuild.exe /p:Configuration="Win8 Release" /P:Platform=x64 /P:RunCodeAnalysisOnce=True ``` diff --git a/windows-driver-docs-pr/develop/debugging-a-universal-driver.md b/windows-driver-docs-pr/develop/debugging-a-universal-driver.md new file mode 100644 index 0000000000..4a590523ab --- /dev/null +++ b/windows-driver-docs-pr/develop/debugging-a-universal-driver.md @@ -0,0 +1,26 @@ +# Debugging a Universal Windows driver + +Starting in Windows 10, you can build your KMDF or UMDF driver binary so that it gets additional driver debugging information through the [Inflight Trace Recorder](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn914610). Universal Windows drivers can take advantage of this feature. + +In addition, if you used the Visual Studio KMDF template, your driver uses Windows software trace preprocessor (WPP) to write trace messages. Your driver binary is an ETW provider with a provider GUID. + +To send a trace message from your driver binary, use this code: + + ``` + TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry"); + ``` + +You can access the ETW logs either using Tracelog via the [TShell tool](http://go.microsoft.com/fwlink/p/?linkid=617388) on a phone, or by using [!wmitrace](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff561362) in a debugger session. + +To use Tracelog on a phone: + +1. Establish a kernel-mode debugging session between a host computer and the phone. +2. On the host computer, in TShell, enter this command: + + ``` + exec-device tracelog -addautologger MyLogger05 -guid c:\SteveGuid.txt -level 4 -flag 0xF –kd + ``` + +3. Reboot the phone, and watch for trace messages in the debugger. + +All existing kernel mode debug transports continue to work on Windows 10 for desktop editions. However, for both user-mode and kernel-mode driver binaries, you must use a remote debugger session over KDNET to test Windows 10 Mobile. For more info, see [Setting Up Kernel-Mode Debugging over a Network Cable Manually](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Hh439346) in Visual Studio. diff --git a/windows-driver-docs-pr/develop/deploying-a-driver-to-a-test-computer.md b/windows-driver-docs-pr/develop/deploying-a-driver-to-a-test-computer.md index 27b58a5b71..472676bd35 100644 --- a/windows-driver-docs-pr/develop/deploying-a-driver-to-a-test-computer.md +++ b/windows-driver-docs-pr/develop/deploying-a-driver-to-a-test-computer.md @@ -25,11 +25,11 @@ Taking advantage of the Visual Studio development environment, the WDK provides ## Setting deployment properties for your driver solution -From the property pages for your driver package, you have additional control over how you want your driver deployed for testing. You can choose to deploy the driver automatically whenever you build the driver solution in each configuration. +From the property pages for your driver project, you have additional control over how you want your driver deployed for testing. You can choose to deploy the driver automatically whenever you build the driver solution in each configuration. -1. Open the property pages for your driver package. Right-click the driver package project in Solution Explorer and select **Properties**. -2. In the property pages for the driver package, click **Configuration Properties**, click **Driver Install**, and then click **Deployment**. -3. Select the **Enable deployment** option. When this option is selected, you must select a test computer that you have configured, or select the name of a computer that you want to configure for testing. See [Provision a computer for driver deployment and testing (WDK 10)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn745909). +1. Open the property pages for your driver project. Right-click the driver project in Solution Explorer and select **Properties**. +2. In the property pages for the driver project, click **Configuration Properties**, click **Driver Install**, and then click **Deployment**. +3. Select a test computer that you have configured, or select the name of a computer that you want to configure for testing. See [Provision a computer for driver deployment and testing (WDK 10)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn745909). When you enable deployment for your driver package project, the driver is automatically deployed to the test computer you have selected when you build your solution. You can use the **Deployment** property page to configure options for driver installation and deployment. See [Deployment Properties for Driver Package Projects](deployment-properties-for-driver-projects.md). @@ -45,6 +45,7 @@ From the property pages for your driver package, you have additional control ove 2. Before you deploy the driver to the test computer, you also need to sign the driver package. See [Signing a Driver During Development and Testing](signing-a-driver-during-development-and-testing.md). 3. Select the test computer that you have configured. 4. To deploy the driver, click **Build Solution** or **Deploy Solution** from the **Build** menu, or press **F5** to build, deploy, and start debugging. +5. On the test computer, you might see a dialog box asking you to confirm that changes should be made. In this case, deployment is paused until you confirm. When you deploy a driver, the driver files are copied to the %Systemdrive%\\drivertest\\drivers folder on the test computer. If something goes wrong during deployment, you can check to see if the files are copied to the test computer. Verify that the .inf, .cat, test cert, and .sys files, and any other necessary files, are present %systemdrive%\\drivertest\\drivers folder. @@ -79,25 +80,3 @@ Starting with Windows Vista, all 64-bit versions of Windows require driver code **Problems installing the driver (general)** The WDK can deploy and install a driver package on a test computer, but only if the driver has all the necessary components for installation, such as an INF file. See [Driver Packages](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff544840) more information. Make sure you can install the driver outside of Visual Studio and the WDK. For example, use the Device Console utility, [Devcon](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff544707) to test whether you can install the driver. Make sure the device (if you have one) is connected to the target computer. For more information, see [Device and Driver Installation](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff549731) and [Creating a Driver Package](creating-a-driver-package.md). - -## Related topics - - -* [Provision a computer for driver deployment and testing (WDK 10)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn745909) -* [Troubleshooting Configuration of Driver Deployment, Testing and Debugging](troubleshooting-configuration-of-driver-deployment--testing-and-debugging.md) -* [Signing a Driver During Development and Testing](signing-a-driver-during-development-and-testing.md) -* [Deployment Properties for Driver Projects](deployment-properties-for-driver-projects.md) -* [Driver Verifier Properties for Driver Projects](driver-verifier-properties-for--driver-projects.md) -* [KMDF Verifier Properties for Driver Package Projects](kmdf-verifier-properties-for-driver-package-projects.md) -* [UMDF Verifier Properties for Driver Package Projects](umdf-verifier-properties-for-driver-package-projects.md) -* [How to create a custom driver installation script](create-a-custom-driver-installation-script.md) -* [Inf2Cat Properties for Driver Package Projects](inf2cat-properties-for-driver-package-projects.md) -  - -  - - - - - - diff --git a/windows-driver-docs-pr/develop/getting-started-with-universal-drivers.md b/windows-driver-docs-pr/develop/getting-started-with-universal-drivers.md index 0df4104be7..b57771dc4c 100644 --- a/windows-driver-docs-pr/develop/getting-started-with-universal-drivers.md +++ b/windows-driver-docs-pr/develop/getting-started-with-universal-drivers.md @@ -11,165 +11,46 @@ ms.technology: windows-devices # Getting Started with Universal Windows drivers -Universal Windows drivers enable developers to create a single driver that runs across multiple different device types, from embedded systems to tablets and desktop PCs. Hardware developers can use their existing components and device drivers across different form factors. Universal Windows drivers run on Windows 10 for desktop editions (Home, Pro, and Enterprise), Windows 10 Mobile, Windows 10 IoT Core, Windows Server 2016 Technical Preview, as well as other Windows 10 editions that share a common set of interfaces. +Universal Windows drivers enable developers to create a single driver package that runs across multiple different device types, from embedded systems to tablets and desktop PCs. -## Introduction to Universal Windows drivers +A Universal Windows driver is a driver package that contains an INF file and binaries that will install and run on Universal Windows Platform (UWP) based editions of Windows 10, such as Windows 10 for desktop editions (Home, Pro, and Enterprise), Windows 10 S, Windows 10 Mobile, Windows 10 IoT Core, Windows Server 2016, as well as other Windows 10 editions that share a common set of interfaces. +A Universal INF file is an INF file that only uses the [subset of INF syntax](../install/using-a-universal-inf-file.md#which-inf-sections-are-invalid-in-a-universal-inf-file) that is supported on [UWP-based editions of Windows 10](windows-10-editions-for-universal-drivers.md). -Windows 10 provides a set of API and DDI interfaces that are common to multiple editions of Windows. This set of interfaces is called the Universal Windows Platform (UWP). +Any binaries referenced by the Universal INF file must use only device driver interfaces (DDI) that are included in [UWP-based editions of Windows 10](windows-10-editions-for-universal-drivers.md). These DDIs are marked as **Universal** on the corresponding documentation reference pages. The driver binary can use [KMDF](../wdf/index.md), [UMDF 2](../wdf/getting-started-with-umdf-version-2.md) or the Windows Driver Model (WDM). -A Universal Windows driver is a kernel-mode or user-mode driver binary that installs and runs on UWP-based editions of Windows 10. +Other binaries contained in your Universal Windows driver must pass the [API validation tests](../devtest/infverif.md). -A Universal Windows driver calls only device driver interfaces (DDIs) that are part of UWP. These DDIs are marked as **Universal** on the corresponding MSDN reference pages. +## Design Principles -To determine if your existing driver calls any interfaces outside of UWP, recompile your driver as a Universal Windows driver. The compiler displays [ApiValidator errors](validating-universal-drivers.md) if the driver calls interfaces that are not part of UWP. In some cases, you can replace these calls with alternate DDIs that are listed on the MSDN reference pages for the desktop-only DDI. If you cannot find a suitable replacement, please submit [feedback](http://go.microsoft.com/fwlink/p/?linkid=529549). +When you write a universal driver package, there are four design principles to consider: -In other cases, you may have to code a workaround if there is not a suitable replacement. If you need to, write a new Universal Windows driver starting from the driver templates in the unified WDK. +* Declarative: Use directives in the INF file for installation operations and not extension points such as co-installers, RegisterDlls, etc. +* Componentized: System and/or OEM-specific customizations are in an [extension INF](../install/using-an-extension-inf-file.md) driver package separate from the primary driver package, facilitating independent updates of different components owned by different organizations. +* Hardware Support Apps (HSA): Use [custom capabilities](../devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md) to associate a hardware-specific UWP (Universal Windows Platform) application with your driver. The resulting app can be delivered and serviced from the Windows Store. +* Universal API compliance: Binaries in the universal driver package only call APIs and DDIs that are included in the OneCore subset. INF files use only universal INF syntax. -The compiler might also display [INF validation errors](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn929320) if you are not [using a universal INF file](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn941087). +Below, you'll find requirements and recommendations related to these principles. Also check out [Universal Driver Scenarios](universal-driver-scenarios.md), which describes how the [DCHU universal driver sample](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU) applies the DCHU design principles. -A Universal Windows driver can use [KMDF](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff557565), [UMDF 2](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn384105) or the Windows Driver Model (WDM). - -## Building a Universal Windows driver - - -You can use Microsoft Visual Studio 2015 in conjunction with Windows Driver Kit (WDK) 10 to build drivers for desktop, mobile, or universal. You can download kits and tools from the [Windows Hardware Dev Center](http://go.microsoft.com/fwlink/p/?LinkId=524487). - -In many cases, you can recompile an existing kernel-mode driver that runs on Windows 8.1 as a Universal Windows driver, as long as the driver does not work with any user-mode components. WDM and KMDF drivers that work with Windows 8.1 should recompile as Universal Windows drivers targeting Windows 10 with no conversion required. - -In contrast, existing user-mode drivers may require modification to compile as Universal Windows drivers. Specifically, your driver package must not have any dependencies outside of UWP. For example, only some of the Win32 APIs are part of UWP. - -**Converting an existing driver project to a Universal Windows driver project** - -1. In Visual Studio 2015, open the existing driver project. -2. In the Solution Explorer pane, right-click the solution and choose **Configuration Manager**. Set the target operating system to Windows 10. -3. Right-click the driver project and choose **Properties**. Under Configuration Properties->Driver, verify that **Target Platform** is set to **Universal**. Other choices include **Desktop**, to build a driver that runs on Windows 10 for desktop editions only, and **Mobile**, to build a driver that runs on Windows 10 Mobile only. -4. Build the driver. You might see linker errors. -5. Fix the errors one by one by going through the error log. Refer to individual reference pages in the documentation for possible alternate APIs. If replacements are not available, you may need to redesign your driver. - -**Creating a New Universal Windows driver Project in Microsoft Visual Studio** - -1. Create a new driver from a template (**File>New Project->Templates->Visual C++->Windows Driver->WDF**) and choose either **User Mode Driver (UMDF V2)** or **Kernel Mode Driver (KMDF)**. -2. After you create the project, in the Solution Explorer pane, right-click the solution and choose **Configuration Manager**. Set **Active solution configuration** to the desired target Windows version, and set **Active solution platform** to **Win32** or **x64**. If **ARM** is not listed, choose **<New...>** to build for ARM. - - If you choose Windows 10, the driver model defaults to **Universal**. - - To change driver model manually, right-click the driver project and choose Properties. Under **Configuration Properties->Driver Settings->General**, find the **Target Platform** entry. Choose **Universal**, **Desktop**, or **Mobile**. Microsoft Visual Studio uses this setting to determine what libraries to link against. - - **Note**  You cannot build a Universal Windows driver for Windows versions earlier than Windows 10. -3. You might need to modify the .inf file to specify the provider, specified as an %*ManufacturerName*% token that is expanded later in the INF file's [**Strings**](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff547485) section. For example: - - ``` syntax - Provider="Contoso" - ``` - -4. You can now build the solution. Visual Studio links against the required libraries and generates a .cat file, an .inf file, and a driver binary. - -For information about the configuration settings you can use in Visual Studio when building your driver, see [Building a Driver with the WDK](building-a-driver.md). - -## Installing a Universal Windows driver - - -**Note**  The SetupAPI component is not part of UWP, so a Universal Windows driver cannot call functions in this API set. - -  - -If you want to install a Universal Windows driver on a device that is running Windows 10 for desktop editions, you can still use an INF file, with a few caveats. An INF for a Universal Windows driver cannot include any of the following: - -- Coinstallers -- Class installers -- RegisterDLL, DelFile, or DelReg directives -- Non-HKR AddReg directives - -For more information, see [Using a Universal INF File](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn941087). - -If you want to install your Universal Windows driver on Windows 10 Mobile, you can use an .spkg file. An .spkg ("*package file*") is a standalone module that contains your driver package. If you are not deploying to Windows 10 Mobile, you do not need to generate a package file. You can still compile a Universal Windows driver (as defined by the driver source code) without a package file. - -WDK 10 includes PkgGen, a tool that generates package files. You run PkgGen in Visual Studio when you build your driver, using the following procedure. - -**Using PkgGen to generate a package file** - -1. Right-click the driver project and choose **Add->New Item**. Next, under **Visual C++->Windows Driver**, choose **Package Manifest**. Click **Add**. -2. Visual Studio adds a file called Package.pkg.xml to your driver project. You can right-click the file and choose properties to verify that the item type is **PkgGen**. (On this same property page, you can set **Excluded from Build** to **Yes** if you decide later that you want to build this driver project and not generate a package file.) Click **OK**. -3. Right-click the driver project and choose **Properties**. Under Configuration Properties, open the PackageGen node and change Version to any value you like. -4. Save your work and restart Visual Studio as administrator. -5. Build your driver. Visual Studio links against the required libraries and generates a .cat file, an .inf file, a driver binary, and an .spkg file. - -To view the contents of the package file, append a .cab suffix to the file name and then open the cab file in Windows Explorer. - -To learn about running PkgGen outside of Visual Studio, see [Creating packages](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn756642). - -To install a mobile driver package (.spkg file), you have two options. - -- If you are updating an existing package on a target system or adding a new package to the target, use IUTool.exe to install an .spkg driver package. -- If you are combining packages into a mobile OS image, use ImgGen to add the .spkg driver package to a full flash update (FFU) image that can then be flashed to a mobile device. - -**Using IUTool to add a mobile driver package (.spkg) to a running device** - -1. [IUTool.exe](http://go.microsoft.com/fwlink/p/?linkid=617385) is in the \\tools\\bin\\*<architecture>* subdirectory of WDK 10. - - Attach your mobile device to the PC. Then, from an elevated command prompt, issue the following command: - - ``` syntax - IUTool -p MyKmdfDriver.spkg - ``` - -2. For more information, see [IUTool.exe: Update packages on a phone](http://go.microsoft.com/fwlink/p/?linkid=617385) and [Adding a driver to a test image](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Mt131832). - -**Using ImgGen to add a driver package (.spkg) to a mobile OS image (.ffu)** - -1. After you install Visual Studio, on the Start screen, click the Visual Studio 2015 folder. Right-click **Developer Command Prompt for VS2015**, and choose **Run as Administrator**. -2. For more information about ImgGen, see [Building a phone image using ImgGen.cmd](http://go.microsoft.com/fwlink/p/?linkid=617386). - -## Flashing a mobile OS image (.ffu) - - -To flash the image to the device, either use the Microsoft-supplied FFUTool, or develop custom OEM flashing tools. For more information, see [Update packages in an .FFU image file](http://go.microsoft.com/fwlink/p/?linkid=617387). - -## Debugging a Universal Windows driver - - -Starting in Windows 10, you can build your KMDF or UMDF driver so that it gets additional driver debugging information through the [Inflight Trace Recorder](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn914610). Universal Windows drivers can take advantage of this feature. - -In addition, if you used the Visual Studio KMDF template, your driver uses Windows software trace preprocessor (WPP) to write trace messages. Your driver is an ETW provider with a provider GUID. - -To send a trace message from your driver, use this code: - - ``` syntax - TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry"); - ``` - -You can access the ETW logs either using Tracelog via the [TShell tool](http://go.microsoft.com/fwlink/p/?linkid=617388) on a phone, or by using [!wmitrace](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Ff561362) in a debugger session. - -To use Tracelog on a phone: - -1. Establish a kernel-mode debugging session between a host computer and the phone. -2. On the host computer, in TShell, enter this command: - - ``` syntax - exec-device tracelog -addautologger MyLogger05 -guid c:\SteveGuid.txt -level 4 -flag 0xF –kd - ``` - -3. Reboot the phone, and watch for trace messages in the debugger. - -All existing kernel mode debug transports continue to work on Windows 10 for desktop editions. However, for both user-mode and kernel-mode drivers, you must use a remote debugger session over KDNET to test Windows 10 Mobile. For more info, see [Setting Up Kernel-Mode Debugging over a Network Cable Manually](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Hh439346) in Visual Studio. - -## Related topics - - -* [Building a Driver with the WDK](building-a-driver.md) -* [Windows 10 Editions for Universal Windows drivers](windows-10-editions-for-universal-drivers.md) -* [Write a Universal Windows driver (UMDF 2) based on a template](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Hh439659) -* [Write a universal Hello World driver (KMDF)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Hh439665) -* [Write a Universal Windows driver (KMDF) based on a template](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Hh439654) -* [Provision a computer for driver deployment and testing (WDK 10)](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn745909) -* [What's new in driver development](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn927349) -  - -  +## Requirements +The following are required when writing a universal driver package: +* Create a universal INF file for your driver: + 1. Review the list of INF sections and directives that are valid in universal driver packages in [Using a Universal INF File](../install/using-a-universal-inf-file.md#which-inf-sections-are-invalid-in-a-universal-inf-file). + 2. Use the [InfVerif](../devtest/infverif.md) tool to verify that your driver package's INF file is universal. +* Use the ApiValidator tool to verify that the APIs your binaries call are valid for a universal driver package. See [Validating Universal Windows drivers](validating-universal-drivers.md). +## Best Practices +Use the following best practices: +* If you are using the WDK with Visual Studio, set the **Target Platform** value in the driver project properties to `Universal`. This will automatically pull in the correct libraries, as well as running the Universal INF validation and APIValidator as a part of build. To do this: + 1. Open the driver project properties. + 2. Select **Driver Settings**. + 3. Use the drop-down menu to set **Target Platform** to `Universal`. + +* If your INF performs any custom setup actions that depend on the target platform, consider separating them out into an extension INF. You can update an extension INF independently from the primary driver package to improve robustness and servicing. See [Using an Extension INF File](../install/using-an-extension-inf-file.md). +* If you would like to provide an application that works with your device, please provide a UWP app. For details, see [Hardware access for Universal Windows Platform apps](../devapps/hardware-access-for-universal-windows-platform-apps.md). In Windows 10, version 1703, the OEM needs to pre-load such an app using [DISM - Deployment Image Servicing and Management](https://docs.microsoft.com/windows-hardware/manufacture/desktop/dism---deployment-image-servicing-and-management-technical-reference-for-windows). Alternatively, users can manually download the app from the Windows Store. +* In [**INF DestinationDirs Section**](../install/inf-destinationdirs-section.md), set the destination directories to 13 to make the driver run from the Driver Store. This will not work for some devices. diff --git a/windows-driver-docs-pr/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt.md b/windows-driver-docs-pr/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt.md index 334f030eca..f104b58c2c 100644 --- a/windows-driver-docs-pr/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt.md +++ b/windows-driver-docs-pr/develop/how-to-test-a-driver-at-runtime-from-a-command-prompt.md @@ -32,7 +32,7 @@ Instructions The TAEF command to run the tests uses the following syntax: -``` syntax +``` Te.exe [/name:] [.dll | ] [/rebootStateFile= ] [/enablewttlogging] [/P:"DQ= <>" ] ``` @@ -43,13 +43,13 @@ You must specify the test binary (.dll) or script (.wsc) file. The test method ( For example, to run all PnP tests in the Devfund\_PnPDTest.dll on a device with a specific device ID. -``` syntax +``` Te.exe Devfund_PnPDTest.dll /P:"DQ=DeviceID='USB\ROOT_HUB\4&1CD5D022&0'" ``` For example, to run PnP Surprise Remove test on a device with a specific device ID. -``` syntax +``` Te.exe /name:"*PNPSurpriseRemoveAndRestartDevice" Devfund_PnPDTest.dll /P:"DQ=DeviceID='USB\ROOT_HUB\4&1CD5D022&0'" ``` diff --git a/windows-driver-docs-pr/develop/how-to-write-a-driver-test-.md b/windows-driver-docs-pr/develop/how-to-write-a-driver-test-.md index 2a826b67d7..4cde94b8c8 100644 --- a/windows-driver-docs-pr/develop/how-to-write-a-driver-test-.md +++ b/windows-driver-docs-pr/develop/how-to-write-a-driver-test-.md @@ -1,7 +1,7 @@ --- ms.assetid: 79AB7242-72D6-4198-9AF0-482CBFB756C7 title: How to write a driver test using a Driver Test template -description: You can use the Windows Driver Kit \(WDK\) for Windows 8 to create your own driver tests or to customize some of the tests that are provided. +description: Use the Windows Driver Kit (WDK) for Windows 8 to create your own driver tests or to customize some of the tests that are provided. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/images/universal-scenarios.png b/windows-driver-docs-pr/develop/images/universal-scenarios.png new file mode 100644 index 0000000000..7f0021422d Binary files /dev/null and b/windows-driver-docs-pr/develop/images/universal-scenarios.png differ diff --git a/windows-driver-docs-pr/develop/installing-a-universal-driver.md b/windows-driver-docs-pr/develop/installing-a-universal-driver.md deleted file mode 100644 index 4b7caf5dfb..0000000000 --- a/windows-driver-docs-pr/develop/installing-a-universal-driver.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -ms.assetid: 1D47B648-C652-4188-A406-AA5EB537138F -title: Installing a Universal Windows driver -description: A driver for any OneCoreUAP-based edition of Windows 10 other than Windows 10 for desktop editions \(Home, Pro, Enterprise, and Education\) must be a Universal Windows driver, and it must be installed using a universal INF file. -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# Installing a Universal Windows driver - -A driver for any OneCoreUAP-based edition of Windows 10 other than Windows 10 for desktop editions (Home, Pro, and Enterprise) must be a [Universal Windows driver](getting-started-with-universal-drivers.md), and it must be installed using a *universal INF file*. - -To install a Universal Windows driver on Windows 10 for desktop editions, we recommend using a universal INF file due to improved performance, but you can use a legacy (non-configurable) INF file. - -## Related topics - - -* [Using a Universal INF File](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn941087) -* [InfVerif](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn929319) -  - -  - - - - - - diff --git a/windows-driver-docs-pr/develop/installing-the-wdk-build-environment-in-a-lab.md b/windows-driver-docs-pr/develop/installing-the-wdk-build-environment-in-a-lab.md index f2eaf00afe..7324f82179 100644 --- a/windows-driver-docs-pr/develop/installing-the-wdk-build-environment-in-a-lab.md +++ b/windows-driver-docs-pr/develop/installing-the-wdk-build-environment-in-a-lab.md @@ -1,7 +1,7 @@ --- ms.assetid: D4B35683-5BD1-40F8-9734-95DADF9E0F20 title: Installing the WDK Build Environment in a Lab -description: The Windows Driver Kit \(WDK\) 8.1 provides a feature that enables you to copy components of Visual Studio and the WDK to a new location and then launch the build environment from the command line. +description: The Windows Driver Kit (WDK) 8.1 enables you to copy components of Visual Studio and the WDK to a new location and then launch the build environment from the command line. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -69,7 +69,7 @@ The build lab support files include the **setup.ps1** PowerShell command file, w For example, the following command runs the script from BuildLabSupport directory and installs the build environment in C:\\BuildLabInstall directory. - ``` syntax + ``` c:\BuildLabSupport>powershell -executionpolicy bypass -file Setup.ps1 -DeployBuildLab -VSInstallerPath c:\VSSetup -KitInstallersPath c:\Kits -E xpansionRoot C:\BuildLabInstall -CatalogFile files.xml ``` @@ -83,7 +83,7 @@ The build lab support files include the **setup.ps1** PowerShell command file, w 2. Launch the build environment by running **LaunchBuildEnv.cmd**. 3. Use MSBuild commands to build your driver projects and solutions. For example: - ``` syntax + ``` msbuild /t:clean /t:build .\MyDriver.vcxproj /p:Configuration="Win8.1 Debug" /p:Platform=Win32 ``` diff --git a/windows-driver-docs-pr/develop/message-compiler-properties-for-driver-projects.md b/windows-driver-docs-pr/develop/message-compiler-properties-for-driver-projects.md index e97e49796b..d147f1b252 100644 --- a/windows-driver-docs-pr/develop/message-compiler-properties-for-driver-projects.md +++ b/windows-driver-docs-pr/develop/message-compiler-properties-for-driver-projects.md @@ -1,7 +1,7 @@ --- ms.assetid: 388C0D27-F3B9-4EF0-A03C-B58F38F2EFD6 title: Message Compiler Properties for Driver Projects -description: Sets the properties for the Message Compiler \(MC.exe\) tool. +description: Sets the properties for the Message Compiler (MC.exe) tool. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/run-the-hck-test-suites-in-the-wdk.md b/windows-driver-docs-pr/develop/run-the-hck-test-suites-in-the-wdk.md index f12c226659..4cffbb558b 100644 --- a/windows-driver-docs-pr/develop/run-the-hck-test-suites-in-the-wdk.md +++ b/windows-driver-docs-pr/develop/run-the-hck-test-suites-in-the-wdk.md @@ -53,7 +53,7 @@ You can also copy one of the provided HCK Test Suites and export it, along with 1. Open a Visual Studio Command Prompt window. Navigate to the %WindowsSdkDir%\\Testing\\Tests\\HCK Tests\\Basic directory. For example, C:\\Program Files (x86)\\Windows Kits\\8.1\\Testing\\Tests\\HCK Tests\\Basic 2. Run the **CopyMe.cmd** script and specify the name of test suite and destination directory. The script has the following syntax: - ``` syntax + ``` CopyMe.cmd testSuite destinationPath ``` @@ -73,7 +73,7 @@ You can also copy one of the provided HCK Test Suites and export it, along with The *destinationPath* can be any valid path, including UNC paths. For example, you can copy an HCK Test Suite to a USB flash drive, or to a share on a server. - ``` syntax + ``` C:\Program Files (x86)\Windows Kits\8.1\Testing\Tests\HCK Tests\Basic>CopyMe "De vice.Device Fundamentals" d:\temp\devfund Copying test target setup installers @@ -101,13 +101,13 @@ You can also copy one of the provided HCK Test Suites and export it, along with 2. Run the **RunMe.cmd** script and specify the path and name of the INF file. The script has the following syntax: - ``` syntax + ``` RunMe.cmd infFileName ``` For example: - ``` syntax + ``` RunMe.cmd myDriver.inf ``` diff --git a/windows-driver-docs-pr/develop/to-add-test-metadata.md b/windows-driver-docs-pr/develop/to-add-test-metadata.md index acb5db337a..f361205a69 100644 --- a/windows-driver-docs-pr/develop/to-add-test-metadata.md +++ b/windows-driver-docs-pr/develop/to-add-test-metadata.md @@ -1,7 +1,7 @@ --- ms.assetid: 8BADC31C-6446-41FA-82F3-F46D66954481 title: How to add test metadata -description: For Windows 8, the Windows Driver Kit \(WDK\) uses the Test Authoring and Execution Framework \(TAEF\) for creating test content. +description: Create test content for Windows 8, using the Windows Driver Kit (WDK) and the Test Authoring and Execution Framework (TAEF). ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/troubleshooting-configuration-of-driver-deployment--testing-and-debugging.md b/windows-driver-docs-pr/develop/troubleshooting-configuration-of-driver-deployment--testing-and-debugging.md index 36d8c49e4c..6254903d05 100644 --- a/windows-driver-docs-pr/develop/troubleshooting-configuration-of-driver-deployment--testing-and-debugging.md +++ b/windows-driver-docs-pr/develop/troubleshooting-configuration-of-driver-deployment--testing-and-debugging.md @@ -65,7 +65,7 @@ You might see several messages before you see the message **The network path was   -``` syntax +``` Connecting to computer "MyComputer" Installing driver test automation service Getting computer system information @@ -83,7 +83,7 @@ You might see several messages before you see the message **The network name can   -``` syntax +``` Connecting to computer "NonExistentComputer" Installing driver test automation service Getting computer system information @@ -96,7 +96,7 @@ The messages that are displayed when you enter an incorrect target computer name   -``` syntax +``` Connecting to computer "NonExistentComputer" Installing driver test automation service Could not access remote machine "NonExistentComputer" over the network. @@ -107,7 +107,7 @@ target machine. Or you might be prompted to enter credentials. -``` syntax +``` Enter your password to connect to: NonExistentComputer ``` @@ -122,7 +122,7 @@ When you start to provision a target computer, you might see a message that says 1. Deploy the driver with breakpoints disabled. 2. Manually break into the kernel-mode debugger. 3. Set an exception on load of the module: -``` syntax +``` sxe ld ``` 4. Enable the breakpoint and resume execution. diff --git a/windows-driver-docs-pr/develop/troubleshooting-the-device-fundamental-tests.md b/windows-driver-docs-pr/develop/troubleshooting-the-device-fundamental-tests.md index c07ba79d9f..b6ee450f3d 100644 --- a/windows-driver-docs-pr/develop/troubleshooting-the-device-fundamental-tests.md +++ b/windows-driver-docs-pr/develop/troubleshooting-the-device-fundamental-tests.md @@ -65,7 +65,7 @@ You might see several messages before you see the message **The network path was   -``` syntax +``` Connecting to computer "MyComputer" Installing driver test automation service Getting computer system information @@ -83,7 +83,7 @@ You might see several messages before you see the message **The network name can   -``` syntax +``` Connecting to computer "NonExistentComputer" Installing driver test automation service Getting computer system information @@ -96,7 +96,7 @@ The messages that are displayed when you enter an incorrect target computer name   -``` syntax +``` Connecting to computer "NonExistentComputer" Installing driver test automation service Could not access remote machine "NonExistentComputer" over the network. @@ -107,7 +107,7 @@ target machine. Or you might be prompted to enter credentials. -``` syntax +``` Enter your password to connect to: NonExistentComputer ``` @@ -122,7 +122,7 @@ When you start to provision a target computer, you might see a message that says 1. Deploy the driver with breakpoints disabled. 2. Manually break into the kernel-mode debugger. 3. Set an exception on load of the module: -``` syntax +``` sxe ld ``` 4. Enable the breakpoint and resume execution. diff --git a/windows-driver-docs-pr/develop/universal-driver-scenarios.md b/windows-driver-docs-pr/develop/universal-driver-scenarios.md new file mode 100644 index 0000000000..1f1bebc337 --- /dev/null +++ b/windows-driver-docs-pr/develop/universal-driver-scenarios.md @@ -0,0 +1,204 @@ +# Universal Driver Scenarios + +This topic describes how the [DCHU universal driver sample](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU) applies the DCHU design principles. You can use it as a model for your own universal driver package. + +If you would like a local copy of the sample repo, clone from [Windows-driver-samples](https://github.com/Microsoft/Windows-driver-samples). + +This sample is intended to be used with Windows 10 Version 1703 and later. + +## Prerequisites + +Before you read this section, check out the requirements and best practices for universal driver packages described in [Getting Started with Universal Windows drivers](getting-started-with-universal-drivers.md). + +## Overview + +The DCHU sample provides example scenarios where two hardware partners, Contoso (OEM) and Fabrikam (IHV) are working together to create a Universal Windows Driver for a device in Contoso's upcoming system. The device in question is an [OSR USB FX2 learning kit](https://store.osr.com/product/osr-usb-fx2-learning-kit-v2/). In the past, Fabrikam would write a non-universal driver package that was customized to a specific Contoso product line, and then hand it to the OEM to handle servicing. This resulted in significant maintenance overhead, so Fabrikam decides to refactor the code and create a universal driver package instead. + +## Use only declarative sections and directives + +First, Fabrikam reviews the [list of INF sections and directives](../install/using-a-universal-inf-file.md#which-inf-sections-are-invalid-in-a-universal-inf-file) that are invalid in universal driver packages. During this exercise, Fabrikam notices that they're using many of these sections and directives in their driver package. + +Their non-universal driver INF registers a co-installer that applies platform-dependent settings and files. This means that the driver package is larger than it should be, and it is harder to service the driver when a bug affects only a subset of the OEM systems that ship the driver. Also, most of the OEM-specific modifications are related to branding, so Fabrikam needs to update the driver package every time an OEM is added or when a minor issue affects a subset of OEM systems. + +Fabrikam removes the non-universal sections and directives and uses the [InfVerif](../devtest/infverif.md) tool to verify that the new driver package's INF file is universal. + +## Use extension INFs to componentize a driver package + +Next, Fabrikam separates customizations that are specific to OEM partners (such as Contoso) from the base driver package into an [extension INF](../install/using-an-extension-inf-file.md). + +The following snippet, updated from [`osrfx2_DCHU_extension.inx`], specifies the `Extension` class and identifies Contoso as the provider since they will own the extension driver package: + +``` +[Version] +Class = Extension +ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} +Provider = Contoso +ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID +``` + +In [`osrfx2_DCHU_base.inx`], Fabrikam specifies the following entries: + +``` +[OsrUsbFx2_AddReg] +HKR, OSR, "OperatingMode",, "Default" ; FLG_ADDREG_TYPE_SZ +HKR, OSR, "OperatingParams",, "None" ; FLG_ADDREG_TYPE_SZ +``` + +In [`osrfx2_DCHU_extension.inx`], Contoso overrides the **OperatingParams** registry value set by the base and adds **OperatingExceptions**: + +``` +[OsrUsbFx2Extension_AddReg] +HKR, OSR, "OperatingParams",, "-Extended" +HKR, OSR, "OperatingExceptions",, "x86" +``` + +Note that extensions are always processed after the base INF in no definite order. If a base INF is updated to a newer version, then the extensions will still be re-applied after the new base INF is installed. + +## Install a service from an INF file + +Fabrikam uses a Win32 service to control the the LEDs on the OSR board. They view this component as part of the core functionality of the device, so they include it as part of their base INF ([`osrfx2_DCHU_base.inx`]). This user-mode service (usersvc) can be added and started declaratively by specifying the [**AddService**](../install/inf-addservice-directive.md) directive in the INF file: + +``` +[OsrFx2_Install.NT] +CopyFiles = OsrFx2_UserSvcCopyFiles + +[OsrFx2_Install.NT.Services] +AddService = osrfx2_DCHU_usersvc, 0x00000800, UserSvc_ServiceInstall + +[UserSvc_ServiceInstall] +DisplayName = %UserSvcDisplayName% +ServiceType = 0x00000010 +StartType = 3 +ErrorControl = 1 +ServiceBinary = %13%\osrfx2_DCHU_usersvc.exe + +[OsrFx2_UserSvcCopyFiles] +osrfx2_DCHU_usersvc.exe +``` +Note that such a service could also be installed in a component or extension INF, depending on the scenario. + +## Use a component to install legacy software from a driver package + +Fabrikam has an executable file `osrfx2_DCHU_componentsoftware.exe` that they previously installed using a co-installer. This legacy software displays the registry keys set by the board and is required by the OEM. This is a GUI-based executable that only runs on Windows for desktop editions. To install it, Fabrikam creates a separate component driver package and adds it in their extension INF. + +The following snippet from [`osrfx2_DCHU_extension.inx`] uses the [**AddComponent**](../install/inf-addcomponent-directive.md) directive to create a virtual child device: + +``` +[OsrFx2Extension_Install.NT.Components] +AddComponent = osrfx2_DCHU_component,,OsrFx2Extension_ComponentInstall + + +[OsrFx2Extension_ComponentInstall] +ComponentIds=VID_045e&PID_94ab +``` + +Then, in the component INF [`osrfx2_DCHU_component.inx`], Fabrikam specifies the [**AddSoftware**](../install/inf-addsoftware-directive.md) directive to install the optional executable: + +``` +[OsrFx2Component_Install.NT.Software] +AddSoftware = osrfx2_DCHU_componentsoftware,, OsrFx2Component_SoftwareInstall + +[OsrFx2Component_SoftwareInstall] +SoftwareType = 1 +SoftwareBinary = osrfx2_DCHU_componentsoftware.exe +SoftwareArguments = <> +SoftwareVersion = 1.0.0.0 + +[OsrFx2Component_CopyFiles] +osrfx2_DCHU_componentsoftware.exe +``` + +The [source code for the Win32 app](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU/osrfx2_DCHU_extension_loose/osrfx2_DCHU_componentsoftware) is included in the DCHU sample. + +Note that the component driver package is only distributed on Desktop SKUs due to targeting set in the [Windows Hardware Dev Center dashboard](https://developer.microsoft.com/dashboard/Registration/Hardware). For more info, see [Publish a driver to Windows Update](https://docs.microsoft.com/windows-hardware/drivers/dashboard/publish-a-driver-to-windows-update). + +## Allow communication with a hardware support app + +Fabrikam would like to provide a GUI-based companion app as part of the universal driver package. Because Win32-based companion applications cannot be part of a universal driver package, they port their Win32 app to the Universal Windows Platform (UWP) and [pair the app with the device](https://docs.microsoft.com/windows-hardware/drivers/devapps/hardware-access-for-universal-windows-platform-apps). + +The following snippet from [`osrfx2_DCHU_base/device.c`](https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_base/osrfx2_DCHU_base/device.c) shows how the base driver package adds a custom capability to the device interface instance: + +```cpp + WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = { 0 }; + static const wchar_t customCapabilities[] = L"CompanyName.yourCustomCapabilityNameTBD_YourStorePubId\0"; + + WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT(&PropertyData, + &GUID_DEVINTERFACE_OSRUSBFX2, + &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities); + + Status = WdfDeviceAssignInterfaceProperty(Device, + &PropertyData, + DEVPROP_TYPE_STRING_LIST, + sizeof(customCapabilities), + (PVOID)customCapabilities); +``` + +The new app (not included in the DCHU sample) is secure and can be updated easily in the Windows Store. With the UWP application ready, Contoso uses [DISM - Deployment Image Servicing and Management](https://docs.microsoft.com/windows-hardware/manufacture/desktop/dism---deployment-image-servicing-and-management-technical-reference-for-windows) to pre-load the application on Windows desktop edition images. + +## Registering a COM component in an INF file + +Fabrikam needs to register a COM component without using a co-installer. In order to accomplish this in a universal INF file, they use the [Reg2inf tool](https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/reg2inf) distributed in the WDK. After building their COM server project (taken from the [In-process ATL COM server sample](https://code.msdn.microsoft.com/ATLDllCOMServer-b52a7d5d)), they provide the COM .dll as an input to the Reg2inf tool. The tool then generates the following INF directives that Fabrikam includes in their base INF ([`osrfx2_DCHU_base.inx`]): + +``` +; Add all registry keys to successfully register the +; In-Process ATL COM Server MSFT Sample. +[OsrFx2_AddReg_COM] +HKCR,AppID\ATLDllCOMServer.DLL,AppID,,"{9DD18FED-55F6-4741-AF25-798B90C4AED5}" +HKCR,AppID\{9DD18FED-55F6-4741-AF25-798B90C4AED5},,,"ATLDllCOMServer" +HKCR,ATLDllCOMServer.SimpleObject,,,"SimpleObject Class" +HKCR,ATLDllCOMServer.SimpleObject\CLSID,,,"{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}" +HKCR,ATLDllCOMServer.SimpleObject\CurVer,,,"ATLDllCOMServer.SimpleObject.1" +HKCR,ATLDllCOMServer.SimpleObject.1,,,"SimpleObject Class" +HKCR,ATLDllCOMServer.SimpleObject.1\CLSID,,,"{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084},,,"SimpleObject Class" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\InprocServer32,,%REG_EXPAND_SZ%,"%%SystemRoot%%\System32\ATLDllCOMServer.dll" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\InprocServer32,ThreadingModel,,"Apartment" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\ProgID,,,"ATLDllCOMServer.SimpleObject.1" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\Programmable,,%FLG_ADDREG_KEYONLY% +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\TypeLib,,,"{9B23EFED-A0C1-46B6-A903-218206447F3E}" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\VersionIndependentProgID,,,"ATLDllCOMServer.SimpleObject" +``` + +## Tightly coupling multiple INF files + +Ideally, there should be strong versioning contracts between base, extensions and components. There are servicing advantages in having these three packages serviced independently (the "loosely coupled" scenario), but there are scenarios where they need to be bundled in a single driver package ("tightly coupled") due to poor versioning contracts. The sample includes examples of both scenarios: + + * [DCHU_Sample\osrfx2_DCHU_extension_loose](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU/osrfx2_DCHU_extension_loose) + * [DCHU_Sample\osrfx2_DCHU_extension_tight](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU/osrfx2_DCHU_extension_tight) + + When the extension and component are in the same driver package ("tightly coupled"), the extension INF specifies the [CopyINF directive](../install/inf-copyinf-directive.md) to cause the component INF to be copied to the target system. This is demonstrated in [DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx](https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_extension_tight/osrfx2_DCHU_extension/osrfx2_DCHU_extension.inx): + +``` +[OsrFx2Extension_Install.NT] +CopyInf=osrfx2_DCHU_component.inf +``` + +This directive can also be used to coordinate installation of INF files in multifunction devices. For more details, see [Copying INF files](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/copying-inf-files). + +## Run from the driver store + +To make it easier to update the driver, Fabrikam specifies the [Driver Store](../install/driver-store.md) as the destination to copy the driver files by using [DirId 13](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/using-dirids) where possible. Here is an example from [`osrfx2_DCHU_base.inx`]: + +``` +[DestinationDirs] +OsrFx2_UserSvcCopyFiles = 13 ; copy to Driver Store +``` + +Using a destination directory value of 13 can result in improved stability during the driver update process. + +## Summary + +The following diagram shows the driver packages that Fabrikam and Contoso created for their Universal Windows Driver. In the loosely coupled example, they will make three separate submissions on the [Windows Hardware Dev Center dashboard](https://developer.microsoft.com/dashboard/Registration/Hardware): one for the base, one for the extension, and one for the component. In the tightly coupled example, they will make two submissions: base and extension/component. + +![Extension, base, and component driver packages](images/universal-scenarios.png) + +Note that the component INF will match on the component hardware ID, whereas the base and extensions will match on the board's hardware ID. + +## See also + +[Getting Started with Universal Windows drivers](getting-started-with-universal-drivers.md) + +[`osrfx2_DCHU_base.inx`]: https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_base/osrfx2_DCHU_base/osrfx2_DCHU_base.inx +[`osrfx2_DCHU_usersvc.inx`]: https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_base/osrfx2_DCHU_usersvc/osrfx2_DCHU_usersvc.inx +[`osrfx2_DCHU_component.inx`]: https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_extension_loose/osrfx2_DCHU_component/osrfx2_DCHU_component.inx +[`osrfx2_DCHU_extension.inx`]: https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_extension_loose/osrfx2_DCHU_extension/osrfx2_DCHU_extension.inx diff --git a/windows-driver-docs-pr/develop/using-pkggen.md b/windows-driver-docs-pr/develop/using-pkggen.md new file mode 100644 index 0000000000..e8c7e4e821 --- /dev/null +++ b/windows-driver-docs-pr/develop/using-pkggen.md @@ -0,0 +1,42 @@ +# Installing a driver on Windows 10 Mobile + +To install a driver on Windows 10 Mobile, use an .spkg file. An .spkg ("*package file*") is a standalone module that contains your driver package. + +WDK 10 includes PkgGen, a tool that generates package files. You run PkgGen in Visual Studio when you build your driver, using the following procedure. + +**Using PkgGen to generate a package file** + +1. Right-click the driver project and choose **Add->New Item**. Next, under **Visual C++->Windows Driver**, choose **Package Manifest**. Click **Add**. +2. Visual Studio adds a file called Package.pkg.xml to your driver project. You can right-click the file and choose properties to verify that the item type is **PkgGen**. (On this same property page, you can set **Excluded from Build** to **Yes** if you decide later that you want to build this driver project and not generate a package file.) Click **OK**. +3. Right-click the driver project and choose **Properties**. Under Configuration Properties, open the PackageGen node and change Version to any value you like. +4. Save your work and restart Visual Studio as administrator. +5. Build your driver. Visual Studio links against the required libraries and generates a .cat file, an .inf file, a driver binary, and an .spkg file. + +To view the contents of the package file, append a .cab suffix to the file name and then open the cab file in Windows Explorer. + +To learn about running PkgGen outside of Visual Studio, see [Creating mobile packages](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Dn756642). + +To install a mobile driver package (.spkg file), you have two options. + +- If you are updating an existing package on a target system or adding a new package to the target, use IUTool.exe to install an .spkg driver package. +- If you are combining packages into a mobile OS image, use ImgGen to add the .spkg driver package to a full flash update (FFU) image that can then be flashed to a mobile device. + +**Using IUTool to add a mobile driver package (.spkg) to a running device** + +1. IUTool.exe is in the \\tools\\bin\\*<architecture>* subdirectory of WDK 10. + + Attach your mobile device to the PC. Then, from an elevated command prompt, issue the following command: + + ``` + IUTool -p MyKmdfDriver.spkg + ``` + +2. For more information, see [Adding a driver to a test image](https://msdn.microsoft.com/en-us/Library/Windows/Hardware/Mt131832). + +**Using ImgGen to add a driver package (.spkg) to a mobile OS image (.ffu)** + +1. After you install Visual Studio, on the Start screen, click the Visual Studio 2015 folder. Right-click **Developer Command Prompt for VS2015**, and choose **Run as Administrator**. + +## Flashing a mobile OS image (.ffu) + +To flash the image to the device, either use the Microsoft-supplied FFUTool, or develop custom OEM flashing tools. diff --git a/windows-driver-docs-pr/develop/installing-the-enterprise-wdk.md b/windows-driver-docs-pr/develop/using-the-enterprise-wdk.md similarity index 65% rename from windows-driver-docs-pr/develop/installing-the-enterprise-wdk.md rename to windows-driver-docs-pr/develop/using-the-enterprise-wdk.md index ceca9c61fc..4b3714ab0d 100644 --- a/windows-driver-docs-pr/develop/installing-the-enterprise-wdk.md +++ b/windows-driver-docs-pr/develop/using-the-enterprise-wdk.md @@ -1,37 +1,33 @@ --- -title: Installing the Enterprise WDK 10 +title: Using the Enterprise WDK 10 description: Describes how to set up a command-line based environment for organization use of the WDK. author: Dansimp ms.author: windowsdriverdev -ms.date: 04/20/2017 +ms.date: 08/25/2017 ms.topic: article ms.prod: windows-hardware ms.technology: windows-devices --- -# Installing the Enterprise WDK 10 -The current Windows Driver Kit (WDK) is optimized for individual developers using a state-based installation. Organizations with many developers using the WDK assume a high cost of individual installations of Visual Studio 2015 and the WDK. To address this, the Enterprise Windows Driver Kit (Enterprise WDK) is a command-line build environment that is file-based, rather than machine based. Once you create the environment file structure, you can have it consumed by version control software or you can zip the files and copy as needed. A .zip file created with the Enterprise WDK contains all the necessary compilers, linkers, build tools, headers and libs to build Visual Studio-based driver projects. +# Using the Enterprise WDK 10 -The Enterprise WDK contains the necessary elements to build drivers and basic Win32 test applications, and is based on Visual Studio 2015 Enterprise, WDK, and the standalone Windows Software Development Kit (SDK). Use your favorite code editor to modify source code and project files. Because it's a command-line, the Enterprise WDK does lack some of the features incorporated into Visual Studio, such as testing and driver deployment. +The current Windows Driver Kit (WDK) is optimized for individual developers using a state-based installation. Organizations with many developers using the WDK assume a high cost of individual installations of Visual Studio 2015 and the WDK. To address this, the Enterprise Windows Driver Kit (Enterprise WDK) is a command-line build environment that is file-based, rather than machine based. Once you create the environment file structure, you can have it consumed by version control software or you can zip the files and copy as needed. A .zip file created with the Enterprise WDK contains all the necessary compilers, linkers, build tools, headers and libs to build Visual Studio-based driver projects. +The Enterprise WDK contains the necessary elements to build drivers and basic Win32 test applications. Use your favorite code editor to modify source code and project files. Because it's a command-line, the Enterprise WDK does lack some of the features incorporated into Visual Studio, such as testing and driver deployment. ## Enterprise WDK 1703 Prerequisites -* Visual Studio build tools, C/C++ compiler, linker and libs for Visual Studio build 14.0.25431.01 (VS 2015 Update 3) - * Note that the Enterprise WDK does not include the IDE, devenv.exe. -* Windows SDK build 10.1.15063.137 + * .NET Framework 4.6 SDK build 4.6.01586 -* Windows Driver Development Kit build 10.1.15063.0 ## Enterprise WDK 1607 Prerequisites -* Visual Studio build tools, C/C++ compiler, linker and libs for Visual Studio build 14.00.24720.0 (VS 2015 Update 1) - * Note that the Enterprise WDK does not include the IDE, devenv.exe. -* Windows SDK build 10586.13 + * .NET Framework 4.6 SDK build 10586.13 -* Windows Driver Development Kit build 10586 +## Getting Started +> [!NOTE] +> In current [Windows 10 Insider Preview](https://insider.windows.com/) builds, the Enterprise WDK is ISO-based. To get started, download and mount the ISO, then run `LaunchBuildEnv`. -## Installation Instructions 1. Download one of the following: * [Enterprise WDK 1703](https://developer.microsoft.com/windows/hardware/license-terms-enterprise-wdk-1703) * [Enterprise WDK 1607](https://developer.microsoft.com/en-us/windows/hardware/license-terms-enterprise-wdk) @@ -48,20 +44,13 @@ Basic MSBuild commands for projects and solutions: To create a desktop shortcut: -%comspec% /k pushd "" && LaunchBuildEnv.cmd +%comspec% /k pushd `` && LaunchBuildEnv.cmd -Where drive\dir is the location that the files were extracted to, for example, d:\ewdk +Where `` is the location that the files were extracted to, for example, d:\ewdk %comspec% /k pushd "d:\ewdk" && LaunchBuildEnv.cmd ## See Also -[ MSBuild Reference](https://msdn.microsoft.com/en-us/library/0k6kkbsd.aspx) - - - - - - - +[ MSBuild Reference](https://msdn.microsoft.com/en-us/library/0k6kkbsd.aspx) diff --git a/windows-driver-docs-pr/develop/validating-universal-drivers.md b/windows-driver-docs-pr/develop/validating-universal-drivers.md index d25e16621b..7b9a11636d 100644 --- a/windows-driver-docs-pr/develop/validating-universal-drivers.md +++ b/windows-driver-docs-pr/develop/validating-universal-drivers.md @@ -11,7 +11,7 @@ ms.technology: windows-devices # Validating Universal Windows drivers -You can use the ApiValidator.exe tool to verify that the APIs that your driver calls are valid for a Universal Windows driver. The tool returns an error if your driver calls an API that is outside the set of valid APIs for Universal Windows drivers. This tool is part of the Windows Driver Kit (WDK) for Windows 10. +You can use the ApiValidator.exe tool to verify that the APIs that your binaries call are valid for a Universal Windows driver. The tool returns an error if your binaries call an API that is outside the set of valid APIs for Universal Windows drivers. This tool is part of the Windows Driver Kit (WDK) for Windows 10. ## Running ApiValidator in Visual Studio @@ -22,7 +22,7 @@ To view all the messages displayed by ApiValidator, navigate to **Tools > Opt For the umdf2\_fx2 driver sample, API validation errors look this: -``` syntax +``` Warning 1 warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe osrusbfx2um Warning 2 warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe osrusbfx2um Warning 3 warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe osrusbfx2um @@ -37,16 +37,17 @@ Error 10 error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\ **Fixing validation errors** -1. If you switched a legacy desktop driver to universal, verify that you are including the correct libraries. Right click the project and choose properties. Navigate to **Linker->Input**. The **Additional Dependencies** should contain: +1. If you switched a legacy desktop UMDF driver project to universal, verify that you are including the correct libraries when building your binaries. Right click the project and choose properties. Navigate to **Linker->Input**. The **Additional Dependencies** should contain: - ``` syntax - %AdditionalDependencies);$(SDK_LIB_PATH)\mincore.lib;$(SDK_LIB_PATH)\WppRecorderUM.lib + ``` + %AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib ``` 2. Remove or replace the non-universal API calls one at a time and rerun the tool until there are no errors. -## Running ApiValidator from the Command Prompt +3. In some cases, you can replace these calls with alternate DDIs that are listed on the reference pages for the desktop-only DDI. If you cannot find a suitable replacement, please [submit feedback](http://go.microsoft.com/fwlink/p/?linkid=529549). You may have to code a workaround if there is not a suitable replacement. If you need to, write a new Universal Windows driver starting from the driver templates in the WDK. +## Running ApiValidator from the Command Prompt You can also run Apivalidator.exe from the command prompt. In your WDK installation, navigate to C:\\Program Files (x86)\\Windows Kits\\10\\bin\\*<arch>*. @@ -60,7 +61,7 @@ For example, to verify the APIs called by the Activity sample in the WDK, first The command produces the following output: -``` syntax +``` ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API. ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API. ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API. @@ -81,7 +82,7 @@ The XML files that enumerate the valid APIs for Universal Windows drivers are lo If ApiValidator.exe outputs an incorrect format error such as the following: -``` syntax +``` Error 1 error : AitStatic output file has incorrect format or analysis run on incorrect file types. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe osrusbfx2um ``` @@ -89,7 +90,7 @@ Use this workaround: 1. Open Project properties, navigate to **General**, and rename **Output Directory** to the following: - ``` syntax + ``` $(SolutionDir)$(Platform)\$(ConfigurationName)\ ``` diff --git a/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-0-.md b/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-0-.md index 91a5edd44f..626bda5075 100644 --- a/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-0-.md +++ b/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-0-.md @@ -1,7 +1,7 @@ --- ms.assetid: A8888EF1-5A6F-4B08-8743-27EEECD4FF72 -title: What happens when you provision a computer \(WDK 8.0\) -description: Here we show what happens when you use version 8.0 of the Windows Driver Kit \(WDK\) to provision a target computer. +title: What happens when you provision a computer (WDK 8.0) +description: Here we show what happens when you use version 8.0 of the Windows Driver Kit (WDK) to provision a target computer. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-1-.md b/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-1-.md index 46c35a9eaa..51fd11b080 100644 --- a/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-1-.md +++ b/windows-driver-docs-pr/develop/what-happens-when-you-provision-a-computer--wdk-8-1-.md @@ -1,7 +1,7 @@ --- ms.assetid: 92F58B13-3447-4715-A6D2-69E63FE04A77 -title: What happens when you provision a computer \(WDK 8.1\) -description: Here we show what happens when you use version 8.1 of the Windows Driver Kit \(WDK\) to provision a target computer. +title: What happens when you provision a computer (WDK 8.1) +description: Here we show what happens when you use version 8.1 of the Windows Driver Kit (WDK) to provision a target computer. ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/develop/windows-10-editions-for-universal-drivers.md b/windows-driver-docs-pr/develop/windows-10-editions-for-universal-drivers.md index 5d73cf5fd7..eec775c7a8 100644 --- a/windows-driver-docs-pr/develop/windows-10-editions-for-universal-drivers.md +++ b/windows-driver-docs-pr/develop/windows-10-editions-for-universal-drivers.md @@ -35,23 +35,23 @@ Here are the values you might see for **Target Platform** on MSDN, and what they

Universal

-

A Universal Windows driver can call this device driver interface (DDI).

+

A driver binary in a Universal Windows driver can call this device driver interface (DDI).

A Universal Windows driver runs on the following Universal Windows Platform (UWP)-based editions of Windows 10:

  • Windows 10 for desktop editions (Home, Pro, and Enterprise)
  • Windows 10 Mobile
  • Windows 10 IoT Core
  • -
  • Windows Server 2016 Technical Preview
  • +
  • Windows Server 2016

For more info, see [Getting Started with Universal Windows drivers](getting-started-with-universal-drivers.md).

Desktop

-

A driver for Windows 10 for desktop editions or Windows Server 2016 Technical Preview can call this DDI.

+

A driver binary for Windows 10 for desktop editions or Windows Server 2016 can call this DDI.

Mobile

-

A driver for Windows 10 Mobile can call this DDI.

+

A driver binary for Windows 10 Mobile can call this DDI.

diff --git a/windows-driver-docs-pr/device-and-driver-technologies.md b/windows-driver-docs-pr/device-and-driver-technologies.md index 6e10c625af..661a62ba63 100644 --- a/windows-driver-docs-pr/device-and-driver-technologies.md +++ b/windows-driver-docs-pr/device-and-driver-technologies.md @@ -52,7 +52,7 @@ Windows 10 Mobile is optimized for the unique needs of mobile devices. Instead - [Storage Devices](https://msdn.microsoft.com/library/windows/hardware/ff563893) - [Streaming Media Devices](https://msdn.microsoft.com/library/windows/hardware/ff567782) - [System Technologies](https://msdn.microsoft.com/en-us/library/windows/hardware/ff557564) -- [Universal Serial Bus (USB)] https://msdn.microsoft.com/en-us/library/windows/hardware/mt807557) +- [Universal Serial Bus (USB)](https://msdn.microsoft.com/en-us/library/windows/hardware/mt807557) - [Windows Portable Devices](https://msdn.microsoft.com/library/windows/hardware/ff597729) - [Windows SideShow Devices](https://msdn.microsoft.com/library/windows/hardware/ff548077) diff --git a/windows-driver-docs-pr/devtest/-clear-switch.md b/windows-driver-docs-pr/devtest/-clear-switch.md index 398a8d1741..080ad5c83b 100644 --- a/windows-driver-docs-pr/devtest/-clear-switch.md +++ b/windows-driver-docs-pr/devtest/-clear-switch.md @@ -1,6 +1,6 @@ --- title: /Clear Switch -description: The /Clear switch of the Enhanced Storage Certificate Management tool removes most of the certificates from the authentication silo certificate (ASC) store on a specified IEEE 1667-compliant USB storage device.Note  In this topic, the specified IEEE 1667-compliant USB storage device is referred to as the target device.� +description: The /Clear switch of the Enhanced Storage Certificate Management tool removes most of the certificates from the authentication silo certificate (ASC) store on a specified IEEE 1667-compliant USB storage device.Note  In this topic, the specified IEEE 1667-compliant USB storage device is referred to as the target device. ms.assetid: b8002d0c-450a-4c4c-bee6-83e382984b34 keywords: - /Clear Switch Driver Development Tools @@ -26,7 +26,7 @@ The **/Clear** switch of the Enhanced Storage Certificate Management tool remove   -``` syntax +``` EhStorCertMgrCmd /Clear -Volume: VolumeName diff --git a/windows-driver-docs-pr/devtest/-debug-switch.md b/windows-driver-docs-pr/devtest/-debug-switch.md index 5b3e5d6010..068b911aa0 100644 --- a/windows-driver-docs-pr/devtest/-debug-switch.md +++ b/windows-driver-docs-pr/devtest/-debug-switch.md @@ -32,7 +32,7 @@ The /**Debug** switch of the Enhanced Storage Certificate Management tool report   -``` syntax +``` EhStorCertMgrCmd /Debug -Volume: VolumeName diff --git a/windows-driver-docs-pr/devtest/-export-switch.md b/windows-driver-docs-pr/devtest/-export-switch.md index ab28f99fe9..8616e44727 100644 --- a/windows-driver-docs-pr/devtest/-export-switch.md +++ b/windows-driver-docs-pr/devtest/-export-switch.md @@ -22,11 +22,11 @@ ms.technology: windows-devices The **/Export** switch of the Enhanced Storage Certificate Management tool exports a specified certificate from the authentication silo certificate (ASC) store in an IEEE 1667-compliant USB storage device to a file. This switch also supports the export of a certificate signing request (CSR) to a file. -**Note**In this topic, the specified IEEE 1667-compliant USB storage device is referred to as the *target device*. +**Note** In this topic, the specified IEEE 1667-compliant USB storage device is referred to as the *target device*. - + -``` syntax +``` EhStorCertMgrCmd /Export -Volume: @@ -39,9 +39,9 @@ The **/Export** switch of the Enhanced Storage Certificate Management tool expor **-Volume:** The volume name of the target device. For more information about the format of this parameter, see [Overview of the Enhanced Storage Certificate Management Tool](overview-of-the-enhanced-storage-certificate-management-tool.md). -**Note**To produce a list of the volume names of the IEEE 1667-compliant USB storage devices that are currently connected to a computer, type **EhStorCertMgrCmd /List** at the command prompt and then press Enter. +**Note** To produce a list of the volume names of the IEEE 1667-compliant USB storage devices that are currently connected to a computer, type **EhStorCertMgrCmd /List** at the command prompt and then press Enter. - + **-Path** The full path and name of the file that will contain the exported certificate or CSR. @@ -113,7 +113,7 @@ If the **-Certificate** parameter is specified, the tool will automatically appe - + For example, the following command, which exports the PCp certificate from the target device, produces a file that is named c:\\MyCertificates\\myCertPCp.cer: @@ -131,8 +131,8 @@ The following example shows how to export the certificate at index 1 from the AS EhStorCertMgrCmd /export -Certificate -Volume:"\\?\usbstor#ieee1667control&ven_&prod_&rev_#123456789&0&control#{4f40006f-b933-4550-b532-2b58cee614d3}" -Index:1 -Path:c:\MyCertificates\myCert.cer ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20/Export%20Switch%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/-flt-completioncontext-outptr--annotation.md b/windows-driver-docs-pr/devtest/-flt-completioncontext-outptr--annotation.md index fbaa90a0e9..df53cc9dfd 100644 --- a/windows-driver-docs-pr/devtest/-flt-completioncontext-outptr--annotation.md +++ b/windows-driver-docs-pr/devtest/-flt-completioncontext-outptr--annotation.md @@ -1,6 +1,6 @@ --- -title: '\_Flt\_CompletionContext\_Outptr\_ Annotation' -description: Use the \_Flt\_CompletionContext\_Outptr\_ annotation when you declare the file system minifilter pre-operation callback function PFLT\_PRE\_OPERATION\_CALLBACK. +title: '_Flt_CompletionContext_Outptr_ Annotation' +description: Use the _Flt_CompletionContext_Outptr_ annotation when you declare the file system minifilter pre-operation callback function PFLT_PRE_OPERATION_CALLBACK. ms.assetid: C3B285EA-0DAB-48D4-AE2F-CB4FBB30EF15 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/-initialize-switch.md b/windows-driver-docs-pr/devtest/-initialize-switch.md index 3a739fb3e9..efe2fdc9b4 100644 --- a/windows-driver-docs-pr/devtest/-initialize-switch.md +++ b/windows-driver-docs-pr/devtest/-initialize-switch.md @@ -26,7 +26,7 @@ The **/Initialize** switch of the Enhanced Storage Certificate Management tool i   -``` syntax +``` EhStorCertMgrCmd /Initialize -Volume: VolumeName [-Quiet] diff --git a/windows-driver-docs-pr/devtest/-kernel-iogetdmaadapter--annotation-for-drivers.md b/windows-driver-docs-pr/devtest/-kernel-iogetdmaadapter--annotation-for-drivers.md index abf725e525..faff672937 100644 --- a/windows-driver-docs-pr/devtest/-kernel-iogetdmaadapter--annotation-for-drivers.md +++ b/windows-driver-docs-pr/devtest/-kernel-iogetdmaadapter--annotation-for-drivers.md @@ -1,6 +1,6 @@ --- -title: '\_Kernel\_IoGetDmaAdapter\_ Annotation for drivers' -description: Use the \_Kernel\_IoGetDmaAdapter\_ annotation to direct the code analysis tools to look for misuse of DMA pointers. +title: '_Kernel_IoGetDmaAdapter_ Annotation for drivers' +description: Use the _Kernel_IoGetDmaAdapter_ annotation to direct the code analysis tools to look for misuse of DMA pointers. ms.assetid: 51F71815-D899-48F5-8F81-92B139FC6B8E ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/-list-switch.md b/windows-driver-docs-pr/devtest/-list-switch.md index 47b80126b8..45932e07dd 100644 --- a/windows-driver-docs-pr/devtest/-list-switch.md +++ b/windows-driver-docs-pr/devtest/-list-switch.md @@ -22,7 +22,7 @@ ms.technology: windows-devices The **/List** switch of the Enhanced Storage Certificate Management tool lists all the IEEE 1667-compliant USB storage devices that are connected to the computer. This switch can also be used to list the certificates (together with their properties) within the authentication silo certificate (ASC) store in a specified USB storage device. -``` syntax +``` EhStorCertMgrCmd /List [-Volume: VolumeName ] diff --git a/windows-driver-docs-pr/devtest/-remove-switch.md b/windows-driver-docs-pr/devtest/-remove-switch.md index 604e25dd5b..91b6f24196 100644 --- a/windows-driver-docs-pr/devtest/-remove-switch.md +++ b/windows-driver-docs-pr/devtest/-remove-switch.md @@ -1,6 +1,6 @@ --- title: /Remove Switch -description: The /Remove switch of the Enhanced Storage Certificate Management tool removes a specified certificate from the authentication silo certificate (ASC) store in an IEEE 1667-compliant USB storage device.Note  To produce a list of the volume names of the IEEE 1667-compliant USB storage devices that are currently connected to a computer, type EhStorCertMgrCmd /List at the command prompt and then press Enter.� +description: The /Remove switch of the Enhanced Storage Certificate Management tool removes a specified certificate from the authentication silo certificate (ASC) store in an IEEE 1667-compliant USB storage device.Note  To produce a list of the volume names of the IEEE 1667-compliant USB storage devices that are currently connected to a computer, type EhStorCertMgrCmd /List at the command prompt and then press Enter. ms.assetid: c74fe7c3-264e-4bbd-9036-b5a254b3ba5b keywords: - /Remove Switch Driver Development Tools @@ -26,7 +26,7 @@ The **/Remove** switch of the Enhanced Storage Certificate Management tool remov   -``` syntax +``` EhStorCertMgrCmd /Remove -Volume: VolumeName -Index: diff --git a/windows-driver-docs-pr/devtest/-replace-switch.md b/windows-driver-docs-pr/devtest/-replace-switch.md index 312ac5df96..49ef07b5fe 100644 --- a/windows-driver-docs-pr/devtest/-replace-switch.md +++ b/windows-driver-docs-pr/devtest/-replace-switch.md @@ -26,7 +26,7 @@ The **/Replace** switch of the Enhanced Storage Certificate Management tool repl   -``` syntax +``` EhStorCertMgrCmd /Replace -Volume: diff --git a/windows-driver-docs-pr/devtest/-static-driver-verifier-commands--msbuild-.md b/windows-driver-docs-pr/devtest/-static-driver-verifier-commands--msbuild-.md index d863acadf3..7d4552a58e 100644 --- a/windows-driver-docs-pr/devtest/-static-driver-verifier-commands--msbuild-.md +++ b/windows-driver-docs-pr/devtest/-static-driver-verifier-commands--msbuild-.md @@ -14,19 +14,19 @@ ms.technology: windows-devices You can run Static Driver Verifier (SDV) in a **Visual Studio Command Prompt** window. Navigate to the directory where the driver's project file or the library's project file is stored. The parameters can appear in any order on the command line. -**Note**Previously available in the Windows Driver Kit (WDK) as a stand-alone tool, SDV is now integrated into Visual Studio and can be run as an MSBuild target, or from the **Driver** menu in Visual Studio. +**Note** Previously available in the Windows Driver Kit (WDK) as a stand-alone tool, SDV is now integrated into Visual Studio and can be run as an MSBuild target, or from the **Driver** menu in Visual Studio. - + -``` syntax +``` msbuild /t:sdv /p:Inputs="Parameters" ProjectFile /p:Configuration=configuration /p:Platform=platform ``` You must select a Release configuration (for example, **/p:Configuration="Windows 7 Release"**). For the list of supported Release Configurations, see [Building a Driver](https://msdn.microsoft.com/windows-drivers/develop/building_a_driver). The Platform can be **Win32** (for x86) or **x64** (for example, **/p:Platform=Win32**). -**Note**Be sure to check your computer's power management plan to ensure the computer will not go into a sleep state during the analysis. +**Note** Be sure to check your computer's power management plan to ensure the computer will not go into a sleep state during the analysis. - + ## Parameters @@ -88,7 +88,7 @@ Displays usage for SDV commands. Commands that use this parameter do not have to ### Comments -Running **msbuild /t:/sdv p:/Inputs=/?** without parameters displays usage for the SDV commands. +Running **msbuild /t:/sdv p:/Inputs= /? ** without parameters displays usage for the SDV commands. A **/clean** command deletes the files that SDV uses to create the Static Driver Verifier Report display for a verification. After running this command, the Static Driver Verifier Report display for the verification is no longer available. @@ -134,9 +134,9 @@ msbuild /t:sdv /p:Inputs="/view" mydriver.VcxProj /p:Configuration="Windows 7 Re [Using Static Driver Verifier to Find Defects in Windows Drivers](using-static-driver-verifier-to-find-defects-in-drivers.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20%20Static%20Driver%20Verifier%20commands%20%28MSBuild%29%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/28126-accessmode-param-incorrect.md b/windows-driver-docs-pr/devtest/28126-accessmode-param-incorrect.md index 890ad971e1..5c64edba7a 100644 --- a/windows-driver-docs-pr/devtest/28126-accessmode-param-incorrect.md +++ b/windows-driver-docs-pr/devtest/28126-accessmode-param-incorrect.md @@ -1,6 +1,6 @@ --- title: C28126 -description: Warning C28126 The AccessMode parameter to ObReferenceObject\ should be IRP- RequestorMode. +description: Warning C28126 The AccessMode parameter to ObReferenceObject* should be IRP->RequestorMode. ms.assetid: be8f909e-2d4a-4e22-b457-81a048d90df8 keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28143-iomarkirppending-must-return-statuspending.md b/windows-driver-docs-pr/devtest/28143-iomarkirppending-must-return-statuspending.md index bbbb0a0a92..7a9e3b1f57 100644 --- a/windows-driver-docs-pr/devtest/28143-iomarkirppending-must-return-statuspending.md +++ b/windows-driver-docs-pr/devtest/28143-iomarkirppending-must-return-statuspending.md @@ -1,6 +1,6 @@ --- title: C28143 -description: Warning C28143 A dispatch routine that calls IoMarkIrpPending must also return STATUS\_PENDING. +description: Warning C28143 A dispatch routine that calls IoMarkIrpPending must also return STATUS_PENDING. ms.assetid: 3b9e6c4f-73d1-4abc-9495-85bb56e2532b keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28152-do-device-initializing-flag-not-cleared.md b/windows-driver-docs-pr/devtest/28152-do-device-initializing-flag-not-cleared.md index 4eccbf77e5..30cb13d860 100644 --- a/windows-driver-docs-pr/devtest/28152-do-device-initializing-flag-not-cleared.md +++ b/windows-driver-docs-pr/devtest/28152-do-device-initializing-flag-not-cleared.md @@ -1,6 +1,6 @@ --- title: C28152 -description: Warning C28152 The return from an AddDevice-like function unexpectedly DO\_DEVICE\_INITIALIZING. +description: Warning C28152 The return from an AddDevice-like function unexpectedly DO_DEVICE_INITIALIZING. ms.assetid: df2b68dc-b22b-4aaa-b1ba-b34bfdd9b886 keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28168-dispatch-function-dispatch-annotation.md b/windows-driver-docs-pr/devtest/28168-dispatch-function-dispatch-annotation.md index ebb5ce1c17..4a926ed951 100644 --- a/windows-driver-docs-pr/devtest/28168-dispatch-function-dispatch-annotation.md +++ b/windows-driver-docs-pr/devtest/28168-dispatch-function-dispatch-annotation.md @@ -1,6 +1,6 @@ --- title: C28168 -description: Warning C28168 The dispatch function does not have a \_Dispatch\_type\_ annotation matching this dispatch table entry. +description: Warning C28168 The dispatch function does not have a _Dispatch_type_ annotation matching this dispatch table entry. ms.assetid: 5e5acc54-acb3-4366-a625-eb79865e932e ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -66,7 +66,7 @@ __drv_dispatchType(IRP_MJ_CREATE_NAMED_PIPE) In this situation, the Code Analysis tool reports this error: -``` syntax +``` The function 'DispatchPassIrp' does not have a _Dispatch_type_ annotation matching dispatch table position 'IRP_MJ_CREATE' (0x00): This can be corrected either by adding a _Dispatch_type_ annotation to the function declaration or correcting the dispatch table entry being used. ``` diff --git a/windows-driver-docs-pr/devtest/28169-dispatch-function-does-not-have-proper-annotation.md b/windows-driver-docs-pr/devtest/28169-dispatch-function-does-not-have-proper-annotation.md index 154e1bbc94..2bd366ace3 100644 --- a/windows-driver-docs-pr/devtest/28169-dispatch-function-does-not-have-proper-annotation.md +++ b/windows-driver-docs-pr/devtest/28169-dispatch-function-does-not-have-proper-annotation.md @@ -1,6 +1,6 @@ --- title: C28169 -description: Warning C28169 The dispatch function does not have any \_Dispatch\_type\_ annotations. +description: Warning C28169 The dispatch function does not have any _Dispatch_type_ annotations. ms.assetid: ce33993f-f967-43b0-89fb-d8553517aae3 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28170-pageable-code-macro-not-found.md b/windows-driver-docs-pr/devtest/28170-pageable-code-macro-not-found.md index 10544bb217..8e4906791d 100644 --- a/windows-driver-docs-pr/devtest/28170-pageable-code-macro-not-found.md +++ b/windows-driver-docs-pr/devtest/28170-pageable-code-macro-not-found.md @@ -1,6 +1,6 @@ --- title: C28170 -description: Warning C28170 The function has been declared to be in a paged segment, but neither PAGED\_CODE nor PAGED\_CODE\_LOCKED was found. +description: Warning C28170 The function has been declared to be in a paged segment, but neither PAGED_CODE nor PAGED_CODE_LOCKED was found. ms.assetid: 9efffcc8-54b6-46f8-b037-53c66a8eace2 keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28171-function-has-more-than-one-page-macro-instance.md b/windows-driver-docs-pr/devtest/28171-function-has-more-than-one-page-macro-instance.md index 552432dffe..360c11ec94 100644 --- a/windows-driver-docs-pr/devtest/28171-function-has-more-than-one-page-macro-instance.md +++ b/windows-driver-docs-pr/devtest/28171-function-has-more-than-one-page-macro-instance.md @@ -1,6 +1,6 @@ --- title: C28171 -description: Warning C28171 The function has more than one instance of PAGED\_CODE or PAGED\_CODE\_LOCKED. +description: Warning C28171 The function has more than one instance of PAGED_CODE or PAGED_CODE_LOCKED. ms.assetid: 7a3740aa-53fc-4219-9606-edc0e9bd9879 keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28172-function-macros-not-in-paged-segment.md b/windows-driver-docs-pr/devtest/28172-function-macros-not-in-paged-segment.md index c227bdec73..03df5ec792 100644 --- a/windows-driver-docs-pr/devtest/28172-function-macros-not-in-paged-segment.md +++ b/windows-driver-docs-pr/devtest/28172-function-macros-not-in-paged-segment.md @@ -1,6 +1,6 @@ --- title: C28172 -description: Warning C28172 The function has PAGED\_CODE or PAGED\_CODE\_LOCKED but is not declared to be in a paged segment. +description: Warning C28172 The function has PAGED_CODE or PAGED_CODE_LOCKED but is not declared to be in a paged segment. ms.assetid: c97bf9e8-583c-41ca-9c50-ac2af3dd5dc0 keywords: - warnings listed WDK PREfast for Drivers diff --git a/windows-driver-docs-pr/devtest/28601-avoid-blocking-on-hwnd-broadcast.md b/windows-driver-docs-pr/devtest/28601-avoid-blocking-on-hwnd-broadcast.md index e89c1725ea..98b3be1273 100644 --- a/windows-driver-docs-pr/devtest/28601-avoid-blocking-on-hwnd-broadcast.md +++ b/windows-driver-docs-pr/devtest/28601-avoid-blocking-on-hwnd-broadcast.md @@ -1,6 +1,6 @@ --- title: C28601 -description: Warning C28601 Avoid blocking on HWND\_BROADCAST. +description: Warning C28601 Avoid blocking on HWND_BROADCAST. ms.assetid: 51fc27da-012a-4cf3-adbf-bd7f7c497b01 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28602-avoid-calling-sendmessagetimeout-with-hwnd-broadcast.md b/windows-driver-docs-pr/devtest/28602-avoid-calling-sendmessagetimeout-with-hwnd-broadcast.md index 0c65ad4ee1..8784ce2d9e 100644 --- a/windows-driver-docs-pr/devtest/28602-avoid-calling-sendmessagetimeout-with-hwnd-broadcast.md +++ b/windows-driver-docs-pr/devtest/28602-avoid-calling-sendmessagetimeout-with-hwnd-broadcast.md @@ -1,6 +1,6 @@ --- title: C28602 -description: Warning C28602 Avoid calling SendMessageTimeout with HWND\_BROADCAST. +description: Warning C28602 Avoid calling SendMessageTimeout with HWND_BROADCAST. ms.assetid: 511df04e-97dc-43a2-9c48-ea1ffe62b813 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28604-smto-abortifhung-with-0-timeout-.md b/windows-driver-docs-pr/devtest/28604-smto-abortifhung-with-0-timeout-.md index 332eaed582..cef44f0533 100644 --- a/windows-driver-docs-pr/devtest/28604-smto-abortifhung-with-0-timeout-.md +++ b/windows-driver-docs-pr/devtest/28604-smto-abortifhung-with-0-timeout-.md @@ -1,6 +1,6 @@ --- title: C28604 -description: Warning C28604 Avoid calling SendMessageTimeout with SMTO\_ABORTIFHUNG with a timeout of 0. +description: Warning C28604 Avoid calling SendMessageTimeout with SMTO_ABORTIFHUNG with a timeout of 0. ms.assetid: d9be9747-20f6-4a2b-a841-eaf3255f2f65 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28615-must-call-resetstkoflw-in-except-block.md b/windows-driver-docs-pr/devtest/28615-must-call-resetstkoflw-in-except-block.md index 853b684984..6fc11d3e8e 100644 --- a/windows-driver-docs-pr/devtest/28615-must-call-resetstkoflw-in-except-block.md +++ b/windows-driver-docs-pr/devtest/28615-must-call-resetstkoflw-in-except-block.md @@ -1,6 +1,6 @@ --- title: C28615 -description: Warning C28615 Must call \_resetstkoflw in the \_\_except() block when calling \_alloca in the \_\_try block. Don't call \_resetstkoflw from inside a catch() block. +description: Warning C28615 Must call _resetstkoflw in the __except() block when calling _alloca in the __try block. Don't call _resetstkoflw from inside a catch() block. ms.assetid: bccfc846-58b9-4c20-bbe7-383ecf836165 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28617-avoid-using-the-return-value-of-beginthread.md b/windows-driver-docs-pr/devtest/28617-avoid-using-the-return-value-of-beginthread.md index 4900cc3396..a1ef40fa7c 100644 --- a/windows-driver-docs-pr/devtest/28617-avoid-using-the-return-value-of-beginthread.md +++ b/windows-driver-docs-pr/devtest/28617-avoid-using-the-return-value-of-beginthread.md @@ -1,6 +1,6 @@ --- title: C28617 -description: Warning C28617 Avoid using the return value of \_beginthread(). Use \_beginthreadex() instead. +description: Warning C28617 Avoid using the return value of _beginthread(). Use _beginthreadex() instead. ms.assetid: b0de0809-1583-4c1d-ad70-c3e27afc3e6d ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28623-unsigned-cast-of-getmessagepos-coordinates.md b/windows-driver-docs-pr/devtest/28623-unsigned-cast-of-getmessagepos-coordinates.md index dcdef9350a..bd75933179 100644 --- a/windows-driver-docs-pr/devtest/28623-unsigned-cast-of-getmessagepos-coordinates.md +++ b/windows-driver-docs-pr/devtest/28623-unsigned-cast-of-getmessagepos-coordinates.md @@ -1,6 +1,6 @@ --- title: C28623 -description: Warning C28623 Unsigned cast of GetMessagePos() coordinates. Use GET\_X\_LPARAM/GET\_Y\_LPARAM instead of LOWORD/HIWORD. +description: Warning C28623 Unsigned cast of GetMessagePos() coordinates. Use GET_X_LPARAM/GET_Y_LPARAM instead of LOWORD/HIWORD. ms.assetid: 155da4f5-4e77-451e-b26b-69a39c32effa ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28644-return-value-from-dpa-insertptr-not-checked.md b/windows-driver-docs-pr/devtest/28644-return-value-from-dpa-insertptr-not-checked.md index e99fdd2eb0..e7ce598c40 100644 --- a/windows-driver-docs-pr/devtest/28644-return-value-from-dpa-insertptr-not-checked.md +++ b/windows-driver-docs-pr/devtest/28644-return-value-from-dpa-insertptr-not-checked.md @@ -1,6 +1,6 @@ --- title: C28644 -description: Warning C28644 Return value from DPA\_InsertPtr not checked. +description: Warning C28644 Return value from DPA_InsertPtr not checked. ms.assetid: F145330F-E597-405F-935E-B12D65F64DDB ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/28650-generic-value-is-not-treated-as-failure.md b/windows-driver-docs-pr/devtest/28650-generic-value-is-not-treated-as-failure.md index 3f17793fa7..2285b44b9c 100644 --- a/windows-driver-docs-pr/devtest/28650-generic-value-is-not-treated-as-failure.md +++ b/windows-driver-docs-pr/devtest/28650-generic-value-is-not-treated-as-failure.md @@ -18,11 +18,11 @@ Returning a status value such as !TRUE is not the same as returning a status val Certain data types such as **NTSTATUS** and **HRESULT** have associated macros that classify values of these types into SUCCESS or FAILURE. These macros check the most significant bit of the returned value or values to determine this. Thus, 0 and 1 are both classified as SUCCESS values. -The proper way to fix this warning is to return a proper error code instead of a generic value such as 1. +The proper way to fix this warning is to return a proper error code instead of a generic value such as -1. - +  - +  [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20C28650%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/28730-possible-null-character-assignment.md b/windows-driver-docs-pr/devtest/28730-possible-null-character-assignment.md index c321200747..c4c3d9ddc2 100644 --- a/windows-driver-docs-pr/devtest/28730-possible-null-character-assignment.md +++ b/windows-driver-docs-pr/devtest/28730-possible-null-character-assignment.md @@ -1,6 +1,6 @@ --- title: C28730 -description: Warning C28730 Possible assignment of '\\\\0' directly to a pointer. +description: Warning C28730 Possible assignment of '\\0' directly to a pointer. ms.assetid: 3cca1ba3-42fa-446d-b9f2-c31ee0a5944a ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/30032-forcing-request-of-executable-memory.md b/windows-driver-docs-pr/devtest/30032-forcing-request-of-executable-memory.md index 6f03edf53c..d0db9efe7c 100644 --- a/windows-driver-docs-pr/devtest/30032-forcing-request-of-executable-memory.md +++ b/windows-driver-docs-pr/devtest/30032-forcing-request-of-executable-memory.md @@ -1,6 +1,6 @@ --- title: C30032 -description: Warning C30032 Calling a memory allocating function and forcing the request of executable memory through use of the POOL\_NX\_OPTOUT directive. +description: Warning C30032 Calling a memory allocating function and forcing the request of executable memory through use of the POOL_NX_OPTOUT directive. ms.assetid: 7C6F9ACE-DD02-45A7-A601-C5C7A5C89256 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/30033-executable-allocation-detected-with-pool-nx-optin.md b/windows-driver-docs-pr/devtest/30033-executable-allocation-detected-with-pool-nx-optin.md index cd2fe977a2..464aa2b634 100644 --- a/windows-driver-docs-pr/devtest/30033-executable-allocation-detected-with-pool-nx-optin.md +++ b/windows-driver-docs-pr/devtest/30033-executable-allocation-detected-with-pool-nx-optin.md @@ -1,6 +1,6 @@ --- title: C30033 -description: Warning C30033 Executable allocation was detected in a driver compiled with POOL\_NX\_OPTIN. +description: Warning C30033 Executable allocation was detected in a driver compiled with POOL_NX_OPTIN. ms.assetid: A5212960-F33D-485A-9B80-23F3D95D475C ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/30034-passing-flag-value-to-allocating-function.md b/windows-driver-docs-pr/devtest/30034-passing-flag-value-to-allocating-function.md index 7bdb71721c..aa559e2e9c 100644 --- a/windows-driver-docs-pr/devtest/30034-passing-flag-value-to-allocating-function.md +++ b/windows-driver-docs-pr/devtest/30034-passing-flag-value-to-allocating-function.md @@ -45,9 +45,9 @@ ExInitializeNPagedLookasideList( pLookaside, depth); ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20C30034%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/TOC.md b/windows-driver-docs-pr/devtest/TOC.md index da34c73161..54da17c4a4 100644 --- a/windows-driver-docs-pr/devtest/TOC.md +++ b/windows-driver-docs-pr/devtest/TOC.md @@ -11,6 +11,7 @@ ## [InfVerif](infverif.md) ### [Running InfVerif from the command line](running-infverif-from-the-command-line.md) ### [INF Validation Errors and Warnings](inf-validation-errors-and-warnings.md) +## [Reg2inf](reg2inf.md) # [Tools for Changing Boot Options for Driver Testing and Debugging](boot-options-for-driver-testing-and-debugging.md) ## [Introduction to Boot Options](introduction-to-boot-options.md) ### [Boot Options in a Boot.ini File](boot-options-in-a-boot-ini-file.md) @@ -726,3 +727,6 @@ ### [Troubleshooting the metadata authoring wizards](troubleshooting.md) ### [XML reference](xml-reference.md) ### [Additional resources](additional-resources.md) +# [Data-Driven System Fundamentals Tests](data-driven-system-fundamentals-tests.md) +## [Configure the Machine for Testing](configure-the-machine-for-testing.md) +## [Run the Tests](run-the-tests.md) diff --git a/windows-driver-docs-pr/devtest/adding-event-tracing-to-kernel-mode-drivers.md b/windows-driver-docs-pr/devtest/adding-event-tracing-to-kernel-mode-drivers.md index 44b7c08e77..96fc034b91 100644 --- a/windows-driver-docs-pr/devtest/adding-event-tracing-to-kernel-mode-drivers.md +++ b/windows-driver-docs-pr/devtest/adding-event-tracing-to-kernel-mode-drivers.md @@ -459,7 +459,7 @@ You must install the manifest on the target system so that event consumers (for For example, to install the manifest for the Evntdrv.sys sample driver, open a Command Prompt windows with elevated privileges (**Run as administrator**) navigate to the directory where the evntdrv.xml file is located and enter the following command: -``` syntax +``` Wevtutil.exe im evntdrv.xml ``` diff --git a/windows-driver-docs-pr/devtest/adding-wpp-software-tracing-to-a-windows-driver.md b/windows-driver-docs-pr/devtest/adding-wpp-software-tracing-to-a-windows-driver.md index 1bdda9a0d8..417371457e 100644 --- a/windows-driver-docs-pr/devtest/adding-wpp-software-tracing-to-a-windows-driver.md +++ b/windows-driver-docs-pr/devtest/adding-wpp-software-tracing-to-a-windows-driver.md @@ -406,7 +406,7 @@ You can use any trace message function you choose, provided the trace message fu 1. Add the [**DoTraceMessage**](https://msdn.microsoft.com/library/windows/hardware/ff544918) macro to your code like you would a debug print routine. The **DoTraceMessage** macro takes 3 parameters: the flag level (*TraceFlagName*), which defines the condition when the trace message is written, the *Message* string, and the optional variable list. - ``` syntax + ``` DoTraceMessage(TraceFlagName, Message, [VariableList... ] ``` @@ -453,7 +453,7 @@ If you are using the Windows driver templates in Visual Studio, the **TraceEvent 1. Add the **TraceEvents** macro to your code like you would a debug print routine. The **TraceEvents** macro takes the following parameters: the trace level (*Level*) and the trace flag (*Flags*), which define the condition when the trace message is written, the *Message* string, and the optional variable list. - ``` syntax + ``` TraceEvents(Level, Flags, Message, [VariableList... ] ``` @@ -514,7 +514,7 @@ To verify that all your messages are generated, you might just set the trace lev (Example) Starting a trace session using Logman -``` syntax +``` logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl logman start "myWPP_session" @@ -524,7 +524,7 @@ logman stop "myWPP_session" (Example) Starting a trace session using TraceLog -``` syntax +``` tracelog -start MyTrace -guid MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF ``` diff --git a/windows-driver-docs-pr/devtest/binplace-command-line-syntax.md b/windows-driver-docs-pr/devtest/binplace-command-line-syntax.md index 98a2775726..17ca95c2ea 100644 --- a/windows-driver-docs-pr/devtest/binplace-command-line-syntax.md +++ b/windows-driver-docs-pr/devtest/binplace-command-line-syntax.md @@ -22,7 +22,7 @@ ms.technology: windows-devices BinPlace uses the following syntax at the command line: -``` syntax +``` binplace [Options] File [ [Options] [@PlaceFile] File [...] ] diff --git a/windows-driver-docs-pr/devtest/boot-options-in-a-boot-ini-file.md b/windows-driver-docs-pr/devtest/boot-options-in-a-boot-ini-file.md index a98a583315..67b9a27198 100644 --- a/windows-driver-docs-pr/devtest/boot-options-in-a-boot-ini-file.md +++ b/windows-driver-docs-pr/devtest/boot-options-in-a-boot-ini-file.md @@ -1,6 +1,6 @@ --- title: Boot Options in a Boot.ini File -description: Boot.ini is a text file located at the root of the system partition, typically c \\Boot.ini. Boot.ini stores boot options for computers with BIOS firmware, traditionally, computers with x86 and x64-based processors. +description: Boot.ini is a text file located at the root of the system partition, typically c:\Boot.ini. Boot.ini stores boot options for computers with BIOS firmware, traditionally, computers with x86 and x64-based processors. ms.assetid: a2593b6d-03df-49d1-ae77-efec4c2ac8be keywords: - Boot.ini files WDK diff --git a/windows-driver-docs-pr/devtest/boot-options-in-efi-nvram.md b/windows-driver-docs-pr/devtest/boot-options-in-efi-nvram.md index 62d5ba6f61..6fc4f02dfc 100644 --- a/windows-driver-docs-pr/devtest/boot-options-in-efi-nvram.md +++ b/windows-driver-docs-pr/devtest/boot-options-in-efi-nvram.md @@ -41,9 +41,9 @@ This section includes: [Backing up Boot Options in EFI](backing-up-boot-options-in-efi.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Boot%20Options%20in%20EFI%20NVRAM%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/boot-options-in-windows-vista-and-later.md b/windows-driver-docs-pr/devtest/boot-options-in-windows-vista-and-later.md index e822d18c98..991634f9a9 100644 --- a/windows-driver-docs-pr/devtest/boot-options-in-windows-vista-and-later.md +++ b/windows-driver-docs-pr/devtest/boot-options-in-windows-vista-and-later.md @@ -27,11 +27,11 @@ ms.technology: windows-devices # Overview of Boot Options in Windows Vista and Later -Windows Vista introduced a new boot loader architecture, a new firmware-independent boot configuration and storage system called *Boot Configuration Data* (BCD), and a new boot option editing tool, BCDEdit (BCDEdit.exe). During development, you can use BCDEdit to configure boot options for debugging, testing, and troubleshooting your driver on computers running Windows10, Windows8, Windows Server2012, Windows 7, and Windows Server 2008. +Windows Vista introduced a new boot loader architecture, a new firmware-independent boot configuration and storage system called *Boot Configuration Data* (BCD), and a new boot option editing tool, BCDEdit (BCDEdit.exe). During development, you can use BCDEdit to configure boot options for debugging, testing, and troubleshooting your driver on computers running Windows 10, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008. -**Important**Administrative privileges are required to use BCDEdit to modify BCD. Changing some boot entry options using BCDEdit could render your computer inoperable. As an alternative, use the System Configuration utility (MSConfig.exe) to change boot settings. +**Important** Administrative privileges are required to use BCDEdit to modify BCD. Changing some boot entry options using BCDEdit could render your computer inoperable. As an alternative, use the System Configuration utility (MSConfig.exe) to change boot settings. - + ### Boot Loading Architecture @@ -55,7 +55,7 @@ Windows boot options are stored in the Boot Configuration Data (BCD) store on BI BCD replaces the traditional Boot.ini text file in BIOS-based systems. Storing boot parameters in a text file, however simple, was considered to be too vulnerable to malicious attacks to justify its use. On EFI-based computers, where boot options are stored in NVRAM, you use the same BCD methods to edit boot options as you would use on a BIOS-based computer, instead of accessing NVRAM directly using Windows APIs or specialized tools. -BCD provides a common, firmware-independent boot option interface for all computers running Windows10, Windows8, Windows Server2012, Windows 7, and Windows Server 2008. It is more secure than previous boot option storage configurations, because it permits secure lockdown of the BCD store and lets Administrators assign rights for managing boot options. BCD is available at run time and during all phases of setup. You can even call BCD during power state transitions and use it to define the boot process for resuming after hibernation. +BCD provides a common, firmware-independent boot option interface for all computers running Windows 10, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008. It is more secure than previous boot option storage configurations, because it permits secure lockdown of the BCD store and lets Administrators assign rights for managing boot options. BCD is available at run time and during all phases of setup. You can even call BCD during power state transitions and use it to define the boot process for resuming after hibernation. You can manage BCD remotely and manage BCD when the system boots from media other than the media on which the BCD store resides. This feature is extremely important for debugging and troubleshooting, especially when a BCD store must be restored while running Startup Repair from a CD, from USB-based storage media, or even remotely. @@ -98,9 +98,9 @@ To change boot options programmatically in Windows, use the Windows Management I [Boot Configuration Data](http://go.microsoft.com/fwlink/p/?linkid=74322) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Overview%20of%20Boot%20Options%20in%20Windows%20Vista%20and%20Later%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/boot-parameters-to-enable-debugging.md b/windows-driver-docs-pr/devtest/boot-parameters-to-enable-debugging.md index dfc90b86b4..8bb2b13beb 100644 --- a/windows-driver-docs-pr/devtest/boot-parameters-to-enable-debugging.md +++ b/windows-driver-docs-pr/devtest/boot-parameters-to-enable-debugging.md @@ -74,7 +74,7 @@ If BCDEdit has not been used, the default global debug settings are for serial c To display the current settings, use the following command: -``` syntax +``` bcdedit /dbgsettings debugtype Serial @@ -90,7 +90,7 @@ To set the global debug settings to serial communications, use the following syn The following example shows how to specify serial communications as the global debug setting. -``` syntax +``` bcdedit /dbgsettings serial debugport:1 baudrate:115200 ``` @@ -106,19 +106,19 @@ If no **{***ID***}** is specified, the settings apply to the currently active bo The following example shows how to specify the serial debug settings for a specific boot entry. To enable the debug settings, you must reboot your computer and select that boot entry you have configured for debugging. -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype serial ``` -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugport 1 ``` -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} baudrate 115200 ``` -``` syntax +``` bcdedit /debug {18b123cd-2bf6-11db-bfae-00e018e2b8db} on ``` @@ -138,7 +138,7 @@ To set the debug settings for 1394 globally, use the following syntax: The following example shows how to specify 1394 as the global debug setting. -``` syntax +``` bcdedit /dbgsettings 1394 channel:32 ``` @@ -152,15 +152,15 @@ If an **{***ID***}** is not specified, the settings apply to the current boot en The following example shows how to specify the 1394 debug settings for a specific boot entry, and how to use the **/debug** option to enable kernel debugging for that boot entry. Note that to enable the debug settings, you must reboot your computer and select the boot entry you have configured for debugging. -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype 1394 ``` -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} channel 32 ``` -``` syntax +``` bcdedit /debug {18b123cd-2bf6-11db-bfae-00e018e2b8db} on ``` @@ -180,7 +180,7 @@ To set the debug settings for USB globally, use the following syntax: The following example shows how to specify USB as the global debug setting. -``` syntax +``` bcdedit /dbgsettings usb targetname:U1 ``` @@ -194,15 +194,15 @@ If no **{***ID***}** is specified, the settings apply to the current boot entry. The following example shows how to specify the USB debug settings for a specific boot entry, and how to use the **/debug** command to enable kernel debugging for that boot entry. Note that to enable the debug settings, you must reboot your computer and select the boot entry you have configured for debugging. -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype usb ``` -``` syntax +``` bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} targetname u2 ``` -``` syntax +``` bcdedit /debug {18b123cd-2bf6-11db-bfae-00e018e2b8db} on ``` diff --git a/windows-driver-docs-pr/devtest/capture-and-view-tracelogging-data.md b/windows-driver-docs-pr/devtest/capture-and-view-tracelogging-data.md index b20a41e928..e0882081aa 100644 --- a/windows-driver-docs-pr/devtest/capture-and-view-tracelogging-data.md +++ b/windows-driver-docs-pr/devtest/capture-and-view-tracelogging-data.md @@ -117,7 +117,7 @@ The WPR and WPA tools must be compatible with the version of the TraceLogging th 2. For kernel mode providers, you need to add the NonPagedMemory="true" attribute to the EventProvider Id element. - ``` syntax + ``` ``` @@ -125,7 +125,7 @@ The WPR and WPA tools must be compatible with the version of the TraceLogging th 3. Save the file with the file name extension (.WPRP). 4. Start the capture using WPR from a Command Prompt window. - ``` syntax + ``` \wpr.exe -start GeneralProfile -start yourTraceLoggingProvider.wprp ``` @@ -134,13 +134,13 @@ The WPR and WPA tools must be compatible with the version of the TraceLogging th 5. Run your test scenario (load and unload the driver or component to trigger events). 6. Stop trace capture and merge all recordings. - ``` syntax + ``` \wpr.exe -stop GeneralProfile -stop yourTraceCaptureFile.etl description ``` You can also use Windows Performance Recorder user interface (Wprui.exe) to collect trace data. -``` syntax +``` \wprui.exe ``` @@ -154,26 +154,26 @@ You can also use Windows Performance Recorder user interface (Wprui.exe) to coll 1. Start trace capture of your provider. - ``` syntax + ``` cmdd tracelog '-start test -f c:\test.etl -guid #providerguid' ``` 2. Run your test scenarios to log events. 3. Stop trace capture. - ``` syntax + ``` cmdd tracelog '-stop test' ``` 4. Merge trace results. - ``` syntax + ``` cmdd xperf -merge c:\test.etl c:\testmerged.etl ``` 5. Retrieve the merged log file. - ``` syntax + ``` getd c:\testmerged.etl ``` @@ -183,7 +183,7 @@ Currently, WPA is the only viewer you can use to view the etl files that TraceLo 1. Start WPA. - ``` syntax + ``` \wpa.exe ``` diff --git a/windows-driver-docs-pr/devtest/certmgr.md b/windows-driver-docs-pr/devtest/certmgr.md index 33c9cbf8f7..762f32334d 100644 --- a/windows-driver-docs-pr/devtest/certmgr.md +++ b/windows-driver-docs-pr/devtest/certmgr.md @@ -24,7 +24,7 @@ CertMgr (Certmgr.exe) is a command-line [CryptoAPI](http://go.microsoft.com/fwli CertMgr supports a large number of switches, but this section describes only those that are relevant to managing [test certificates](https://msdn.microsoft.com/library/windows/hardware/ff553457) within a certificate store. -``` syntax +``` CertMgr [/add|/del|/put] [Switches] [/s [/r RegistryLocation ] ] SourceName [/s [/r RegistryLocation] ] [DestinationName] ``` diff --git a/windows-driver-docs-pr/devtest/chkinf-command-syntax.md b/windows-driver-docs-pr/devtest/chkinf-command-syntax.md index eb8d6c9716..6355f2741e 100644 --- a/windows-driver-docs-pr/devtest/chkinf-command-syntax.md +++ b/windows-driver-docs-pr/devtest/chkinf-command-syntax.md @@ -1,6 +1,6 @@ --- title: ChkINF Command Syntax -description: The ChkINF scripts are located in the WindowSdkDir \\Tools\\x86\\Chkinf subdirectory. +description: The ChkINF scripts are located in the %WindowSdkDir%\Tools\x86\Chkinf subdirectory. ms.assetid: 62919c28-73f1-4401-95de-59ac45e4a8e7 keywords: - ChkINF Command Syntax Driver Development Tools @@ -24,7 +24,7 @@ The ChkINF scripts are located in the %WindowSdkDir%\\Tools\\x86\\Chkinf subdire Use the following command syntax: -``` syntax +``` chkinf {INFFile [INFFile...] | Directory} [/L TextFile] [/B] [/LO] [/DC Options] diff --git a/windows-driver-docs-pr/devtest/code-analysis-for-drivers.md b/windows-driver-docs-pr/devtest/code-analysis-for-drivers.md index 53b4b4ec72..36112b5edd 100644 --- a/windows-driver-docs-pr/devtest/code-analysis-for-drivers.md +++ b/windows-driver-docs-pr/devtest/code-analysis-for-drivers.md @@ -14,9 +14,9 @@ ms.technology: windows-devices Code Analysis for Drivers is a compile-time static verification tool that detects basic coding errors in C and C++ programs and includes a specialized module that is designed to detect errors in (primarily) kernel-mode driver code. -**Note**In previous versions of the WDK, the driver-specific module for code analysis was part of a stand-alone tool called PREfast for Drivers (PFD). PREfast for Drivers was also integrated into the WDK Build environment, as part of Microsoft Automated Code Review (OACR). Starting with Windows Driver Kit (WDK)8, the driver-specific features have been integrated with the [Code Analysis tool in Visual Studio](http://go.microsoft.com/fwlink/p/?linkid=226836). +**Note** In previous versions of the WDK, the driver-specific module for code analysis was part of a stand-alone tool called PREfast for Drivers (PFD). PREfast for Drivers was also integrated into the WDK Build environment, as part of Microsoft Automated Code Review (OACR). Starting with Windows Driver Kit (WDK) 8, the driver-specific features have been integrated with the [Code Analysis tool in Visual Studio](http://go.microsoft.com/fwlink/p/?linkid=226836). - + ## In this section @@ -26,9 +26,9 @@ Code Analysis for Drivers is a compile-time static verification tool that detect - [SAL 2 Annotations for Windows Drivers](sal-2-annotations-for-windows-drivers.md) - [Code Analysis for Drivers Warnings](prefast-for-drivers-warnings.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Code%20Analysis%20for%20Drivers%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/command-line-output.md b/windows-driver-docs-pr/devtest/command-line-output.md index def03978a2..49a292c5dc 100644 --- a/windows-driver-docs-pr/devtest/command-line-output.md +++ b/windows-driver-docs-pr/devtest/command-line-output.md @@ -21,7 +21,7 @@ For example, the following illustration shows the command-line output from a com In this verification, SDV found four defects, one for each rule that it verified. -``` syntax +``` C:\Program Files (x86)\Windows Kits\8.0\Tools\sdv\samples\fail_drivers\wdm\fail_driver1>msbuild fail_driver1.vcxproj /t:sdv /p:inputs="/check=config.sdv" /p:configuration="Win8 beta release" /p:platform=win32 Microsoft (R) Build Engine version 4.0.30319.17369 [Microsoft .NET Framework, version 4.0.30319.17369] diff --git a/windows-driver-docs-pr/devtest/computerhardwareids-overview.md b/windows-driver-docs-pr/devtest/computerhardwareids-overview.md index c7daf8ef6e..f43dfd47d7 100644 --- a/windows-driver-docs-pr/devtest/computerhardwareids-overview.md +++ b/windows-driver-docs-pr/devtest/computerhardwareids-overview.md @@ -22,7 +22,7 @@ ms.technology: windows-devices To run ComputerHardwareIds, type a command at the command prompt. Use the following syntax and parameters. -``` syntax +``` ComputerHardwareIds diff --git a/windows-driver-docs-pr/devtest/configure-the-machine-for-testing.md b/windows-driver-docs-pr/devtest/configure-the-machine-for-testing.md new file mode 100644 index 0000000000..bff76a471b --- /dev/null +++ b/windows-driver-docs-pr/devtest/configure-the-machine-for-testing.md @@ -0,0 +1,28 @@ +#Configure the Machine for Testing +The steps required to install WDTF and TAEF, copy the data-driven tests, configure the machine, and run the tests are outlined below. + +**Step 1**: Obtain the packages and files from the latest [EWDK] (https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/installing-the-enterprise-wdk) by accepting the licensing terms and saving the EWDK zip file to the machine on which the tests will run. Unzip the EWDK. + +**Step 2**: Install TAEF by navigating to the location of the TAEF MSI and installing the package for the desired architecture: + + cd \Program Files\Windows Kits\10\Testing\Runtimes + msiexec /i "Test Authoring and Execution Framework x64-x64_en-us.msi" + +The TAEF MSI installs TAEF to \Program Files\Windows Kits\10\Testing\Runtimes\TAEF. Add this directory to the system PATH environment variable and restart the command prompt. + +Start the TAEF service if it’s not already running and set to Autostart: + 1. Launch Services: services.msc + 2. Double click Te.Service + 3. Set “Startup type” to “Automatic” + 4. Click “Start” to start the service + +**Step 3**: Install WDTF by navigating to the location of the WDTF MSI (same location as the TAEF MSI above) and installing the package for the desired architecture: + + cd \Program Files\Windows Kits\10\Testing\Runtimes + msiexec /i "Windows Driver Testing Framework (WDTF) Runtime Libraries-x64_en-us.msi" + +The WDTF MSI installs WDTF to \Program Files\Windows Kits\10\Testing\Runtimes\WDTF. + +**Step 4**: Configure the machine for testing: + 1. Configure the machine to collect full dumps or attach a kernel debugger + 2. Since the tests can potentially reboot the machine and need to control the sleep cycles, configure the machine to never sleep, never turn off display, and autologon to a test account (netplwiz.exe). Obviously, autologon should be used with caution. diff --git a/windows-driver-docs-pr/devtest/converting-a-wdk-sources-file-to-a-visual-studio-project.md b/windows-driver-docs-pr/devtest/converting-a-wdk-sources-file-to-a-visual-studio-project.md index 4b59312ec0..fd49a05b05 100644 --- a/windows-driver-docs-pr/devtest/converting-a-wdk-sources-file-to-a-visual-studio-project.md +++ b/windows-driver-docs-pr/devtest/converting-a-wdk-sources-file-to-a-visual-studio-project.md @@ -12,11 +12,11 @@ ms.technology: windows-devices # Converting a WDK sources file to a Visual Studio project -**Note**The Nmake2MsBuild tool was removed from the WDK starting in Windows10, version 1511. +**Note** The Nmake2MsBuild tool was removed from the WDK starting in Windows 10, version 1511. - + -For most Windows7 WDK projects that were built using Build.exe, you can use the [Nmake2MsBuild](nmake2msbuild.md) utility, or the automatic conversion process within Visual Studio, to generate a project file (.VcxProj). In most cases, the Visual Studio project file closely maps to the original *sources* file so the project can be built successfully in Visual Studio, or from an MSBuild command. For some build targets, you need to customize the rule-based mapping that the conversion tools uses. This topic describes how the conversion utility works and how you can extend it by creating your own rule mapping. +For most Windows 7 WDK projects that were built using Build.exe, you can use the [Nmake2MsBuild](nmake2msbuild.md) utility, or the automatic conversion process within Visual Studio, to generate a project file (.VcxProj). In most cases, the Visual Studio project file closely maps to the original *sources* file so the project can be built successfully in Visual Studio, or from an MSBuild command. For some build targets, you need to customize the rule-based mapping that the conversion tools uses. This topic describes how the conversion utility works and how you can extend it by creating your own rule mapping. ## The Nmake2MsBuild conversion process @@ -71,17 +71,17 @@ The NMake2MsBuild utility does not support conversion of custom targets or the c - Expansion of Macro references in Inference rules that define optional directories: - ``` syntax + ``` INPUT_DIR= c:\MyDirectory .FromExt{$(INPUT_DIR)}.ToExt: - cmd.exe /c echo something + cmd.exe /c echo something ``` - Youd have to change the above to: + You d have to change the above to: - ``` syntax + ``` .FromExt{ c:\MyDirectory}.ToExt: - cmd.exe /c echo something + cmd.exe /c echo something ``` - NMAKE inline files and macro substitutions are not supported. @@ -90,9 +90,9 @@ The NMake2MsBuild utility does not support conversion of custom targets or the c Macro substitutions: See **Macro Substitution** - Because inline files and macro substitutions are not supported the following target wont be converted correctly: + Because inline files and macro substitutions are not supported the following target won t be converted correctly: - ``` syntax + ``` fsdkmsg.mc : ..\..\wrapper\fsdkmsgbase.src copy ..\..\wrapper\fsdkmsgbase.src @type <<$(ECHO_RSP) @@ -104,10 +104,10 @@ The NMake2MsBuild utility does not support conversion of custom targets or the c <<$(BUILD_NOKEEP) ``` -- **!Error** statements will not be converted. Theres no equivalent in MSBuild that would work outside MSBuild targets as well. +- **!Error** statements will not be converted. There s no equivalent in MSBuild that would work outside MSBuild targets as well. - Target definitions must match 1:1 with NTTARGETFILE\* macros that invoke the target: The following is not supported: - ``` syntax + ``` Sources File: OBJ_NAME=Something NTTARGETFILES=$(_OBJ_DIR)\$(TARGET_DIRECTORY)\$(OBJ_NAME).obj @@ -116,11 +116,11 @@ The NMake2MsBuild utility does not support conversion of custom targets or the c ``` -- Both the targets definition and NTTARGETFILES must match; they both should use $(OBJ\_NAME).obj or *Somename*.obj. $? And $< tokens in Targets are always expanded for all dependents. +- Both the target s definition and NTTARGETFILES must match; they both should use $(OBJ\_NAME).obj or *Somename*.obj. $? And $< tokens in Targets are always expanded for all dependents. See **Filename Macros** for more information. -- $? Expands to All dependents with a later timestamp than the current target. For converted projects the timestamp is ignored and this evaluates to all dependents. The same holds true for $< +- $? Expands to All dependents with a later timestamp than the current target. For converted projects the timestamp is ignored and this evaluates to all dependents. The same holds true for $< ## Limitations of Converted Projects @@ -136,9 +136,9 @@ Converted projects do not support VS .Filters files. [Creating a Driver From Existing Source Files](https://msdn.microsoft.com/windows-drivers/develop/creating_a_driver_from_existing_source_files) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Converting%20a%20WDK%20sources%20file%20to%20a%20Visual%20Studio%20project%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/could-not-write-slam-cfiles.md b/windows-driver-docs-pr/devtest/could-not-write-slam-cfiles.md index 4efab30635..81142b0893 100644 --- a/windows-driver-docs-pr/devtest/could-not-write-slam-cfiles.md +++ b/windows-driver-docs-pr/devtest/could-not-write-slam-cfiles.md @@ -1,6 +1,6 @@ --- -title: Could not write SLAM\_CFILES -description: Could not write SLAM\_CFILES +title: Could not write SLAM_CFILES +description: Could not write SLAM_CFILES ms.assetid: c347a549-8dd3-431a-aa26-633ba511870c ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/creating-certificates-for-usb-storage-devices.md b/windows-driver-docs-pr/devtest/creating-certificates-for-usb-storage-devices.md index 74a98473f4..49c4f7ddc6 100644 --- a/windows-driver-docs-pr/devtest/creating-certificates-for-usb-storage-devices.md +++ b/windows-driver-docs-pr/devtest/creating-certificates-for-usb-storage-devices.md @@ -22,7 +22,7 @@ ms.technology: windows-devices The Enhanced Storage Certificate Management tool can create a self-signed certificate that is imported to an IEEE 1667-compliant USB storage device. The specifications for the certificate are stored within either a text (.txt) or initialization (.ini) file and must contain the following entries: -``` syntax +``` [certificate] Subject=SubjectString diff --git a/windows-driver-docs-pr/devtest/ctrpp-task.md b/windows-driver-docs-pr/devtest/ctrpp-task.md index c5e9c19a6c..2de97b4c26 100644 --- a/windows-driver-docs-pr/devtest/ctrpp-task.md +++ b/windows-driver-docs-pr/devtest/ctrpp-task.md @@ -29,7 +29,7 @@ The following example shows how to edit the metadata in the .vcxproj file. The following example shows the command-line invocation: -``` syntax +``` ctrpp.exe –ch "c:\test\abc.h" a.manifest ``` diff --git a/windows-driver-docs-pr/devtest/data-driven-system-fundamentals-tests.md b/windows-driver-docs-pr/devtest/data-driven-system-fundamentals-tests.md new file mode 100644 index 0000000000..cf407369de --- /dev/null +++ b/windows-driver-docs-pr/devtest/data-driven-system-fundamentals-tests.md @@ -0,0 +1,4 @@ +#Data-driven System Fundamentals Tests +Starting with Enterprise WDK (EWDK) 1703, Microsoft provides configurable command-line versions of the System Fundamentals tests and associated utilities. These are known as “data-driven” tests and utilities. +The data-driven System Fundamentals (SysFund) tests are configurable and customizable via an XML file (wdtftest.xml), and run via the command line. The tests are designed to run early and often during driver and device development. +Since the data-driven SysFund tests are functionally identical to the SysFund tests in the HLK, if a system can pass the data-driven SysFund tests, it should also be able to pass the HLK SysFund tests. However, unlike the SysFund tests in the HLK, the data-driven SysFund tests are configurable to target a set of devices from one device to all devices on the system. This allows for an iterative testing process for new or updated devices and systems. diff --git a/windows-driver-docs-pr/devtest/ddi-compliance-checking.md b/windows-driver-docs-pr/devtest/ddi-compliance-checking.md index ea7bba0096..7747e21a17 100644 --- a/windows-driver-docs-pr/devtest/ddi-compliance-checking.md +++ b/windows-driver-docs-pr/devtest/ddi-compliance-checking.md @@ -106,7 +106,7 @@ You can activate the DDI compliance checking feature for one or more drivers by At the command line, DDI compliance checking is represented by **verifier /flags 0x00020000** (Bit 17). To activate DDI compliance checking, use a flag value of 0x00020000 or add 0x00020000 to the flag value. For example: - ``` syntax + ``` verifier /flags 0x00020000 /driver MyDriver.sys ``` @@ -145,7 +145,7 @@ You can activate the **DDI compliance checking (additional)** rules for one or m At the command line, DDI compliance checking is represented by **verifier /flags 0x00080000** (Bit 19). To activate **DDI compliance checking (additional)**, use a flag value of 0x00080000 or add 0x00080000 to the flag value. For example: - ``` syntax + ``` verifier /flags 0x00080000 /driver MyDriver.sys ``` diff --git a/windows-driver-docs-pr/devtest/debugging-bug-check-0xc4--driver-verifier-detected-violation.md b/windows-driver-docs-pr/devtest/debugging-bug-check-0xc4--driver-verifier-detected-violation.md index 151c224730..c45da8b160 100644 --- a/windows-driver-docs-pr/devtest/debugging-bug-check-0xc4--driver-verifier-detected-violation.md +++ b/windows-driver-docs-pr/devtest/debugging-bug-check-0xc4--driver-verifier-detected-violation.md @@ -1,5 +1,5 @@ --- -title: Debugging Bug Check 0xC4 DRIVER\_VERIFIER\_DETECTED\_VIOLATION +title: Debugging Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION description: If Driver Verifier detects a violation, it generates a bug check to stop the computer. ms.assetid: 4B957C57-9095-4C81-9EBC-C92C620C5824 ms.author: windowsdriverdev diff --git a/windows-driver-docs-pr/devtest/debugging-ddi-compliance-bugs----driver-verifier-detected-violation--c4---0x000200--.md b/windows-driver-docs-pr/devtest/debugging-ddi-compliance-bugs----driver-verifier-detected-violation--c4---0x000200--.md index 3ed6db2ec8..c68b59aa0b 100644 --- a/windows-driver-docs-pr/devtest/debugging-ddi-compliance-bugs----driver-verifier-detected-violation--c4---0x000200--.md +++ b/windows-driver-docs-pr/devtest/debugging-ddi-compliance-bugs----driver-verifier-detected-violation--c4---0x000200--.md @@ -1,6 +1,6 @@ --- title: Debugging DRIVER_VERIFIER_DETECTED_VIOLATION (C4) 0x20002 - 0x20022 -description: When you have the DDI compliance checking option selected, and Driver Verifier detects that the driver violates one of the DDI compliance rules, Driver Verifier generates Bug Check 0xC4 DRIVER\_VERIFIER\_DETECTED\_VIOLATION (with Parameter 1 equal to the identifier of the specific compliance rule). +description: When you have the DDI compliance checking option selected, and Driver Verifier detects that the driver violates one of the DDI compliance rules, Driver Verifier generates Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION (with Parameter 1 equal to the identifier of the specific compliance rule). ms.assetid: 9817AC4B-2BE8-44AC-8C9B-DED5EF0A7DD8 ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -28,7 +28,7 @@ The DDI Compliance rules ensure that a driver correctly interacts with the Windo As with any bug check that occurs, once you have control of the debugger, the best first step is to run the [**!analyze -v**](https://msdn.microsoft.com/library/windows/hardware/ff562112) command. -``` syntax +``` ******************************************************************************* * * * Bugcheck Analysis * @@ -73,7 +73,7 @@ The [**!analyze**](https://msdn.microsoft.com/library/windows/hardware/ff562112) The **DV\_RULE\_INFO:** field of the **!analyze** output shows the command you can use to find more information about this rule violation. For this example, you can use the command: **!ruleinfo 0x20004** -``` syntax +``` kd> !ruleinfo 0x20004 RULE_ID: 0x20004 @@ -99,7 +99,7 @@ MSDN_LINK: http://go.microsoft.com/fwlink/p/?linkid=216021 When this violation is caught, Driver Verifier will bug check the system immediately. The **!analyze** output will show the current IRQL, current stack, point where the call to allocate memory was made, and if source-code enabled The **!analyze –v** (for verbose) output will also show the source file and line number where the allocation request was made: -``` syntax +``` CURRENT_IRQL: 10 ANALYSIS_VERSION: 6.13.0016.1929 (debuggers(dbg).130725-1857) amd64fre diff --git a/windows-driver-docs-pr/devtest/debugging-deadlocks---driver-verifier-detected-violation--c4---0x1001.md b/windows-driver-docs-pr/devtest/debugging-deadlocks---driver-verifier-detected-violation--c4---0x1001.md index 1e0b82349d..4b8bd6b7b8 100644 --- a/windows-driver-docs-pr/devtest/debugging-deadlocks---driver-verifier-detected-violation--c4---0x1001.md +++ b/windows-driver-docs-pr/devtest/debugging-deadlocks---driver-verifier-detected-violation--c4---0x1001.md @@ -1,6 +1,6 @@ --- -title: Debugging deadlocks - DRIVER\_VERIFIER\_DETECTED\_VIOLATION (C4) 0x1001 -description: When Driver Verifier detects a spin lock hierarchy violation, Driver Verifiergenerates Bug Check 0xC4 DRIVER\_VERIFIER\_DETECTED\_VIOLATION with a parameter 1 value of 0x1001. +title: Debugging deadlocks - DRIVER_VERIFIER_DETECTED_VIOLATION (C4) 0x1001 +description: When Driver Verifier detects a spin lock hierarchy violation, Driver Verifiergenerates Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION with a parameter 1 value of 0x1001. ms.assetid: 4C3ED1DB-5EDC-4386-B91C-CF86973EE1F6 ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -22,7 +22,7 @@ When the Deadlock Detection option is active (Deadlock Detection is part of the **New in Windows 8.1** When [Driver Verifier](driver-verifier.md) encounters this violation, if the debugger is attached, the debugger will ask you for input about the error. In Windows 8 and previous versions of Windows, this violation result in an immediate bug check. -``` syntax +``` ************ Verifier Detected a Potential Deadlock ************* ** ** Type !deadlock in the debugger for more information. @@ -35,7 +35,7 @@ When the Deadlock Detection option is active (Deadlock Detection is part of the To debug this violation on a computer running Windows 8.1, choose **B** (Break), and enter the suggested debugger command ([**!deadlock**](https://msdn.microsoft.com/library/windows/hardware/ff562326)): -``` syntax +``` kd> !deadlock issue: 00001001 97dd800c 86858ce0 00000000 @@ -55,7 +55,7 @@ Lock B = 97dd8008 (MyTestDriver!BravoLock+0x00000000) - Type 'Spinlock'. The [**!deadlock**](https://msdn.microsoft.com/library/windows/hardware/ff562326) **3** command can also be used to show more information, including the stack at the time of last acquire: -``` syntax +``` kd> !deadlock 3 issue: 00001001 97dd800c 86858ce0 00000000 @@ -114,7 +114,7 @@ Lock A = 97dd800c (MyTestDriver!AlphaLock+0x00000000) - Type 'Spinlock'. The debugger suggests using the [**kb (Display Stack Backtrace)**](https://msdn.microsoft.com/library/windows/hardware/ff551943) command to display the current stack trace. -``` syntax +``` kd> kb ChildEBP RetAddr Args to Child 89b2cac4 820da328 97dd800c 86858ce0 00000000 nt!VfReportIssueWithOptions+0x86 @@ -136,7 +136,7 @@ At this point, a review of the source code of each function should reveal that a Both *MyTestDriver!AlphaLock* and *MyTestDriver!BravoLock* are objects globally available in the driver: -``` syntax +``` include "MyTestDriverHeader.h" // Locks used to control access to various objects diff --git a/windows-driver-docs-pr/devtest/debugging-memory-leaks---driver-verifier-detected-violation--c4---0x62.md b/windows-driver-docs-pr/devtest/debugging-memory-leaks---driver-verifier-detected-violation--c4---0x62.md index 5fc1b51720..0959421c93 100644 --- a/windows-driver-docs-pr/devtest/debugging-memory-leaks---driver-verifier-detected-violation--c4---0x62.md +++ b/windows-driver-docs-pr/devtest/debugging-memory-leaks---driver-verifier-detected-violation--c4---0x62.md @@ -1,6 +1,6 @@ --- -title: Debugging memory leaks - DRIVER\_VERIFIER\_DETECTED\_VIOLATION (C4) 0x62 -description: Driver Verifier generates Bug Check 0xC4 DRIVER\_VERIFIER\_DETECTED\_VIOLATION with a parameter 1 value of 0x62 when a driver unloads without first freeing all of its pool allocations. +title: Debugging memory leaks - DRIVER_VERIFIER_DETECTED_VIOLATION (C4) 0x62 +description: Driver Verifier generates Bug Check 0xC4 DRIVER_VERIFIER_DETECTED_VIOLATION with a parameter 1 value of 0x62 when a driver unloads without first freeing all of its pool allocations. ms.assetid: CDBE9A18-4126-4AD7-8E53-6D75DCA8B022 ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -29,7 +29,7 @@ When you have a kernel debugger connected to a test computer running [Driver Ver As with any bug check that occurs, once you have control of the debugger, the best first step is to run the [**!analyze -v**](https://msdn.microsoft.com/library/windows/hardware/ff562112) command. -``` syntax +``` kd> !analyze -v Connected to Windows 8 9600 x86 compatible target Loading Kernel Symbols @@ -80,7 +80,7 @@ Specify [Pool Tracking](pool-tracking.md) (**verifier /flags 0x8**). The Pool Tr For this particular bug check, the information provided in parameter 4 (Arg4) is the most important. Arg4 shows number of allocations that weren’t freed. The output of the [**!analyze**](https://msdn.microsoft.com/library/windows/hardware/ff562112) command also shows the [**!verifier**](https://msdn.microsoft.com/library/windows/hardware/ff565591) debugger extension command that you can use to display what those allocations were. The full output of **!verifier 3 MyDriver.sys** command is shown in the following example: -``` syntax +``` kd> !verifier 3 Mydriver.sys Verify Flags Level 0x000209bb @@ -162,7 +162,7 @@ Of the tags displayed, only one (for the allocation at address 0x8645a000) was s When symbols are loaded for the driver, if those symbols contain the line number information, you can use the **ln** *CallerAddress* command to show the line where the call was made. This output will also show the offset in the function that made the allocation. -``` syntax +``` kd> ln 0x9a3bf6ac d:\coding\wdmdrivers\mydriver\handleioctl.c(50)+0x15 (9a3bf660) MyDriver!DeviceControlDispatch+0x4c | (9a3bf6d0) MyDriver!DeviceControlDispatch @@ -182,7 +182,7 @@ Driver Verifier also keeps a circular log of all memory allocations made in kern This log can be accessed by using the command **!verifier 0x80** *AddressOfPoolAllocation*. Note that this will list all of the allocations and frees in the log for this particular address. To cancel or stop display of the log history, use the keyboard shortcuts: **Ctrl + Break** with WinDbg and **Ctrl + C** with KD. -``` syntax +``` kd> !verifier 0x80 0x982a8fe0 Log of recent kernel pool Allocate and Free operations: diff --git a/windows-driver-docs-pr/devtest/debugging-ndis-wifi-timeouts---driver-verifier-detected-violation--c4---0x92003--etc-.md b/windows-driver-docs-pr/devtest/debugging-ndis-wifi-timeouts---driver-verifier-detected-violation--c4---0x92003--etc-.md index 1acc35aa21..48e3ea7e7e 100644 --- a/windows-driver-docs-pr/devtest/debugging-ndis-wifi-timeouts---driver-verifier-detected-violation--c4---0x92003--etc-.md +++ b/windows-driver-docs-pr/devtest/debugging-ndis-wifi-timeouts---driver-verifier-detected-violation--c4---0x92003--etc-.md @@ -28,7 +28,7 @@ When Driver Verifier is testing a NDIS/WIFI time-out rule, such as [**NdisTimedO As with any bug check that occurs, once you have control of the debugger, the best first step is to run the [**!analyze -v**](https://msdn.microsoft.com/library/windows/hardware/ff562112) command. -``` syntax +``` DRIVER_VERIFIER_DETECTED_VIOLATION (c4) A device driver attempting to corrupt the system has been caught. This is because the driver was specified in the registry as being suspect (by the @@ -44,7 +44,7 @@ Arg4: 9c1f3480, Address of supplemental states (third argument to !ruleinfo). In the following section of the **!analyze -v** output, the reason why the rule was violated under is shown under the DV\_VIOLATED\_CONDITION field. The DV\_MSDN\_LINK section is also useful to pull up a link to documentation on this rule. -``` syntax +``` ## Debugging Details: @@ -68,7 +68,7 @@ FAULTING_MODULE: 9fee1000 NdisTimedOidComplete Further down this analysis output, you can click on the link under the DV\_RULE\_INFO section for additional rule descriptions. For time-out type of rules, the current stack might not contain relevant information. -``` syntax +``` DV_RULE_INFO: 0x92003 BUGCHECK_STR: 0xc4_NdisTimedOidComplete_XDV @@ -103,7 +103,7 @@ STACK_TEXT: The **DV\_RULE\_INFO:** field of the **!analyze** output shows a link to the command you can use to find more information about this rule violation. For this example, if you click the link, it runs the [**!ruleinfo**](https://msdn.microsoft.com/library/windows/hardware/dn265374) command with the RULE\_ID (0x92003) the Arg3 and Arg 4 bug check values. -``` syntax +``` kd> !ruleinfo 0x92003 0xffffffff9c17b860 0xffffffff9c1f3480 RULE_ID: 0x92003 @@ -131,7 +131,7 @@ RULE_STATE: 0x9C1F3480 In the example we are using here, the miniport driver, NdisTimedOidComplete.sys, has a sleep cycle injected into its *MPOidRequest* function. We can check by clicking on the LAST\_CALL\_STACK link in the [**!ruleinfo**](https://msdn.microsoft.com/library/windows/hardware/dn265374) output. This is the last call stack seen by Driver Verifier, where we see that NDIS called *ndisMInvokeOidRequest* before the time out occurred. -``` syntax +``` kd> dps 0x9C1F3480 + 0x10 9c1f3490 850e1e37 ndis!ndisMInvokeOidRequest+0x16641 9c1f3494 850765c8 ndis!ndisMDoOidRequest+0x24a diff --git a/windows-driver-docs-pr/devtest/devcon-classes.md b/windows-driver-docs-pr/devtest/devcon-classes.md index 5b262b19ec..c6e92d8d01 100644 --- a/windows-driver-docs-pr/devtest/devcon-classes.md +++ b/windows-driver-docs-pr/devtest/devcon-classes.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Lists all [device setup classes](https://msdn.microsoft.com/library/windows/hardware/ff541509), including classes that devices on the system do not use. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] classes diff --git a/windows-driver-docs-pr/devtest/devcon-classfilter.md b/windows-driver-docs-pr/devtest/devcon-classfilter.md index 80d9f60e2b..b8a3f4c9dc 100644 --- a/windows-driver-docs-pr/devtest/devcon-classfilter.md +++ b/windows-driver-docs-pr/devtest/devcon-classfilter.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Adds, deletes, displays, and changes the order of filter drivers for a device setup class. Valid only on the local computer. -``` syntax +``` devcon classfilter class {upper | lower} [ = | @driver | -driver | +driver | !driver ]... diff --git a/windows-driver-docs-pr/devtest/devcon-disable.md b/windows-driver-docs-pr/devtest/devcon-disable.md index 3ebd9b1788..f518b2609e 100644 --- a/windows-driver-docs-pr/devtest/devcon-disable.md +++ b/windows-driver-docs-pr/devtest/devcon-disable.md @@ -24,7 +24,7 @@ Disables devices on the computer. Valid only on the local computer. To *disable* a device means that the device remains physically connected to the computer, but its driver is unloaded from memory and its resources are freed so that the device cannot be used. -``` syntax +``` devcon [/r] disable {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-dp-add.md b/windows-driver-docs-pr/devtest/devcon-dp-add.md index 2821535395..e95d341c0a 100644 --- a/windows-driver-docs-pr/devtest/devcon-dp-add.md +++ b/windows-driver-docs-pr/devtest/devcon-dp-add.md @@ -1,5 +1,5 @@ --- -title: DevCon Dp\_add +title: DevCon Dp_add description: Adds a third-party (OEM) driver package to the driver store on the local computer. ms.assetid: 929bb59b-f227-47c5-9351-270ffbe4d745 keywords: @@ -22,7 +22,7 @@ ms.technology: windows-devices Adds a third-party (OEM) driver package to the driver store on the local computer. -``` syntax +``` devcon dp_add inf diff --git a/windows-driver-docs-pr/devtest/devcon-dp-delete.md b/windows-driver-docs-pr/devtest/devcon-dp-delete.md index 18dd93bd32..c7b5f482e2 100644 --- a/windows-driver-docs-pr/devtest/devcon-dp-delete.md +++ b/windows-driver-docs-pr/devtest/devcon-dp-delete.md @@ -1,5 +1,5 @@ --- -title: DevCon Dp\_delete +title: DevCon Dp_delete description: Deletes a third-party (OEM) driver package from the driver store on the local computer. This command deletes the INF file, the PNF file, and the associated catalog file (.cat). ms.assetid: bc9d8d66-4aa1-423b-b907-40a8c0194eb1 keywords: @@ -22,7 +22,7 @@ ms.technology: windows-devices Deletes a third-party (OEM) driver package from the driver store on the local computer. This command deletes the INF file, the PNF file, and the associated catalog file (.cat). -``` syntax +``` devcon dp_delete [-f] inf diff --git a/windows-driver-docs-pr/devtest/devcon-dp-enum.md b/windows-driver-docs-pr/devtest/devcon-dp-enum.md index c84c94269b..7fc05ef9c7 100644 --- a/windows-driver-docs-pr/devtest/devcon-dp-enum.md +++ b/windows-driver-docs-pr/devtest/devcon-dp-enum.md @@ -1,5 +1,5 @@ --- -title: DevCon Dp\_enum +title: DevCon Dp_enum description: Lists the third-party (OEM) driver packages in the driver store on the local computer. ms.assetid: 974b34db-ac83-4d92-87d2-067c15492046 keywords: @@ -22,7 +22,7 @@ ms.technology: windows-devices Lists the third-party (OEM) driver packages in the driver store on the local computer. -``` syntax +``` devcon dp_enum diff --git a/windows-driver-docs-pr/devtest/devcon-driverfiles.md b/windows-driver-docs-pr/devtest/devcon-driverfiles.md index 346c419147..4780a500ad 100644 --- a/windows-driver-docs-pr/devtest/devcon-driverfiles.md +++ b/windows-driver-docs-pr/devtest/devcon-driverfiles.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Displays the full path and file name of installed INF files and device driver files for the specified devices. Valid only on the local computer. -``` syntax +``` devcon driverfiles {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-drivernodes.md b/windows-driver-docs-pr/devtest/devcon-drivernodes.md index 7820b3387e..ca36da751e 100644 --- a/windows-driver-docs-pr/devtest/devcon-drivernodes.md +++ b/windows-driver-docs-pr/devtest/devcon-drivernodes.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Lists all [driver packages](https://msdn.microsoft.com/library/windows/hardware/ff539954) that are compatible with the device, along with their version and ranking. Valid only on the local computer. -``` syntax +``` devcon drivernodes {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-enable.md b/windows-driver-docs-pr/devtest/devcon-enable.md index 2b0c072cbc..4ff47f2dd2 100644 --- a/windows-driver-docs-pr/devtest/devcon-enable.md +++ b/windows-driver-docs-pr/devtest/devcon-enable.md @@ -24,7 +24,7 @@ Enables devices on the computer. Valid only on the local computer. To *enable* a device means that the device driver is loaded into memory and the device is ready for use. -``` syntax +``` devcon [/r] enable {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-find.md b/windows-driver-docs-pr/devtest/devcon-find.md index ea706357ad..905e219adb 100644 --- a/windows-driver-docs-pr/devtest/devcon-find.md +++ b/windows-driver-docs-pr/devtest/devcon-find.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Finds all devices that are currently attached to the computer. Displays the device instance ID and device description. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] find {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-findall.md b/windows-driver-docs-pr/devtest/devcon-findall.md index ca5aa7ed5f..f47294b8bc 100644 --- a/windows-driver-docs-pr/devtest/devcon-findall.md +++ b/windows-driver-docs-pr/devtest/devcon-findall.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Finds all devices on the computer, including devices that were once attached to the computer but have been detached or moved. (These are known as nonpresent devices or *phantom* devices.) The **DevCon FindAll** operation also finds devices that are enumerated differently as a result of a BIOS change. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] findall {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-general-commands.md b/windows-driver-docs-pr/devtest/devcon-general-commands.md index ab60c13993..e8dba536e7 100644 --- a/windows-driver-docs-pr/devtest/devcon-general-commands.md +++ b/windows-driver-docs-pr/devtest/devcon-general-commands.md @@ -22,7 +22,7 @@ ms.technology: windows-devices DevCon (DevCon.exe) is a command line tool that can display detailed information about devices on computers running Windows. You can also use DevCon to enable, disable, install, configure, and remove devices. DevCon uses the following syntax. -``` syntax +``` devcon [/m:\\computer] [/r] command [arguments] ``` diff --git a/windows-driver-docs-pr/devtest/devcon-hwids.md b/windows-driver-docs-pr/devtest/devcon-hwids.md index 9e63b92a51..2c9d422122 100644 --- a/windows-driver-docs-pr/devtest/devcon-hwids.md +++ b/windows-driver-docs-pr/devtest/devcon-hwids.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Displays the hardware IDs, compatible IDs, and device instance IDs of the specified devices. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] hwids {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-install.md b/windows-driver-docs-pr/devtest/devcon-install.md index ed9efe8313..c121983168 100644 --- a/windows-driver-docs-pr/devtest/devcon-install.md +++ b/windows-driver-docs-pr/devtest/devcon-install.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Creates a new, root-enumerated devnode for a non-Plug and Play device and installs its supporting software. Valid only on the local computer. -``` syntax +``` devcon [/r] install INFfile HardwareID diff --git a/windows-driver-docs-pr/devtest/devcon-listclass.md b/windows-driver-docs-pr/devtest/devcon-listclass.md index d2d69f3526..b40886bc0e 100644 --- a/windows-driver-docs-pr/devtest/devcon-listclass.md +++ b/windows-driver-docs-pr/devtest/devcon-listclass.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Lists all devices in the specified device setup classes. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] listclass class [class...] diff --git a/windows-driver-docs-pr/devtest/devcon-reboot.md b/windows-driver-docs-pr/devtest/devcon-reboot.md index 9468697fc4..b4bd23e139 100644 --- a/windows-driver-docs-pr/devtest/devcon-reboot.md +++ b/windows-driver-docs-pr/devtest/devcon-reboot.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Stops and then starts the operating system. Valid only on the local computer. -``` syntax +``` devcon reboot diff --git a/windows-driver-docs-pr/devtest/devcon-remove.md b/windows-driver-docs-pr/devtest/devcon-remove.md index 8d7a489970..e26b3e5f99 100644 --- a/windows-driver-docs-pr/devtest/devcon-remove.md +++ b/windows-driver-docs-pr/devtest/devcon-remove.md @@ -26,7 +26,7 @@ This operation does not delete the device driver or any files installed for the Valid only on the local computer. -``` syntax +``` devcon [/r] remove {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-rescan.md b/windows-driver-docs-pr/devtest/devcon-rescan.md index 410441adde..cafb591743 100644 --- a/windows-driver-docs-pr/devtest/devcon-rescan.md +++ b/windows-driver-docs-pr/devtest/devcon-rescan.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Uses Windows Plug and Play features to update the device list for the computer. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] [/r] rescan diff --git a/windows-driver-docs-pr/devtest/devcon-resources.md b/windows-driver-docs-pr/devtest/devcon-resources.md index 65be1d6142..7695b554ce 100644 --- a/windows-driver-docs-pr/devtest/devcon-resources.md +++ b/windows-driver-docs-pr/devtest/devcon-resources.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Lists the resources allocated to the specified devices. Resources are assignable and addressable bus paths, such as DMA channels, I/O ports, IRQ, and memory addresses. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] resources {* | ID [ID ...] | =class [ID [ID...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-restart.md b/windows-driver-docs-pr/devtest/devcon-restart.md index fb727dab6d..66635df4b2 100644 --- a/windows-driver-docs-pr/devtest/devcon-restart.md +++ b/windows-driver-docs-pr/devtest/devcon-restart.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Stops and restarts the specified devices. Valid only on the local computer. -``` syntax +``` devcon [/r] restart {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-sethwid.md b/windows-driver-docs-pr/devtest/devcon-sethwid.md index 8167a5bf3a..5bdb758b97 100644 --- a/windows-driver-docs-pr/devtest/devcon-sethwid.md +++ b/windows-driver-docs-pr/devtest/devcon-sethwid.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Adds, deletes, and changes the order of hardware IDs of root-enumerated devices on a local or remote computer. -``` syntax +``` devcon [/m:\\computer] sethwid {* | ID [ID ...] | =class [ID [ID ...]]} := [ = | + | - | ! ]HardwareIDs ... diff --git a/windows-driver-docs-pr/devtest/devcon-stack.md b/windows-driver-docs-pr/devtest/devcon-stack.md index 34a6a532e9..83483c012b 100644 --- a/windows-driver-docs-pr/devtest/devcon-stack.md +++ b/windows-driver-docs-pr/devtest/devcon-stack.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Displays the expected driver stack for the specified devices, and the GUID and the name of the device setup class for each device. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] stack {* | ID [ID ...] | =class [ID [ID...]]} @@ -34,9 +34,9 @@ Displays the expected driver stack for the specified devices, and the GUID and t **/m:\\\\***computer* Runs the command on the specified remote computer. The backslashes are required. -**Note** To run DevCon commands on a remote computer, the Group Policy setting must allow the Plug and Play service to run on the remote computer. On computers that run Windows Vista and Windows 7, the Group Policy disables remote access to the service by default. On computers that run WDK8.1 and WDK8, the remote access is unavailable. +**Note** To run DevCon commands on a remote computer, the Group Policy setting must allow the Plug and Play service to run on the remote computer. On computers that run Windows Vista and Windows 7, the Group Policy disables remote access to the service by default. On computers that run WDK 8.1 and WDK 8, the remote access is unavailable. - + **\*** Represents all devices on the computer. @@ -74,7 +74,7 @@ The following special characters modify the ID parameter. - + **=***class* Specifies the device setup class of the devices. The equal sign (**=**) identifies the string as a class name. You can also specify hardware IDs, compatible IDs, device instance IDs, or ID patterns following the class name. Type a space between each ID or pattern. DevCon finds devices in the class that match the specified IDs. @@ -104,9 +104,9 @@ devcon stack =multifunction [Example 16: Display the stack for related devices on a remote computer](devcon-examples.md#ddk_example_16_display_the_stack_for_related_devices_on_a_remote_compu) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20DevCon%20Stack%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/devcon-status.md b/windows-driver-docs-pr/devtest/devcon-status.md index 81a93c28d8..796550ba0e 100644 --- a/windows-driver-docs-pr/devtest/devcon-status.md +++ b/windows-driver-docs-pr/devtest/devcon-status.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Displays the status (running, stopped, or disabled) of the driver for devices on the computer. Valid on local and remote computers. -``` syntax +``` devcon [/m:\\computer] status {* | ID [ID ...] | =class [ID [ID ...]]} diff --git a/windows-driver-docs-pr/devtest/devcon-update.md b/windows-driver-docs-pr/devtest/devcon-update.md index b4dcfbf46f..0d38f8581a 100644 --- a/windows-driver-docs-pr/devtest/devcon-update.md +++ b/windows-driver-docs-pr/devtest/devcon-update.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Forcibly replaces the current device drivers for a specified device with drivers listed in the specified INF file. Valid only on the local computer. -``` syntax +``` devcon [/r] update INFfile HardwareID diff --git a/windows-driver-docs-pr/devtest/devcon-updateni.md b/windows-driver-docs-pr/devtest/devcon-updateni.md index 657dec28a6..cc84bb4deb 100644 --- a/windows-driver-docs-pr/devtest/devcon-updateni.md +++ b/windows-driver-docs-pr/devtest/devcon-updateni.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Forcibly replaces the current device drivers with drivers listed in the specified INF file without prompting the user for information or confirmation. Valid only on the local computer. -``` syntax +``` devcon [/r] updateni INFfile HardwareID diff --git a/windows-driver-docs-pr/devtest/devcon.md b/windows-driver-docs-pr/devtest/devcon.md index 047a4fcd20..9de16aa2dc 100644 --- a/windows-driver-docs-pr/devtest/devcon.md +++ b/windows-driver-docs-pr/devtest/devcon.md @@ -45,21 +45,21 @@ DevCon runs on Microsoft Windows 2000 and later versions of Windows.

DevCon (Devcon.exe) is included when you install the WDK, Visual Studio, and the Windows SDK for desktop apps. For information about downloading the kits, see [Windows Hardware Downloads](http://go.microsoft.com/fwlink/p/?linkid=290798).

-

Windows Driver Kit (WDK)8 and Windows Driver Kit (WDK)8.1 (installation path)

+

Windows Driver Kit (WDK) 8 and Windows Driver Kit (WDK) 8.1 (installation path)

%WindowsSdkDir%\tools\x64\devcon.exe

%WindowsSdkDir%\tools\x86\devcon.exe

%WindowsSdkDir%\tools\arm\devcon.exe

-NoteThe Visual Studio environment variable, %WindowsSdkDir%, represents the path to the Windows kits directory where the kits are installed, for example, C:\Program Files (x86)\Windows Kits\8.1. +Note The Visual Studio environment variable, %WindowsSdkDir%, represents the path to the Windows kits directory where the kits are installed, for example, C:\Program Files (x86)\Windows Kits\8.1.
- +
- + This section includes: @@ -74,9 +74,9 @@ Windows driver developers and testers can use DevCon to verify that a driver is DevCon is a command-line tool that performs device management functions on local computers and remote computers. -**Note** To run DevCon commands on a remote computer, the Group Policy setting must allow the Plug and Play service to run on the remote computer. On computers that run Windows Vista and Windows 7, the Group Policy disables remote access to the service by default. On computers that run WDK8.1 and WDK8, the remote access is unavailable. +**Note** To run DevCon commands on a remote computer, the Group Policy setting must allow the Plug and Play service to run on the remote computer. On computers that run Windows Vista and Windows 7, the Group Policy disables remote access to the service by default. On computers that run WDK 8.1 and WDK 8, the remote access is unavailable. - + Devcon features include: @@ -116,9 +116,9 @@ The DevCon source code is also available so that you can examine the methods tha [DevCon Examples](devcon-examples.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Windows%20Device%20Console%20%28Devcon.exe%29%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/device-fundamentals-tests.md b/windows-driver-docs-pr/devtest/device-fundamentals-tests.md index e25615acff..279659e64f 100644 --- a/windows-driver-docs-pr/devtest/device-fundamentals-tests.md +++ b/windows-driver-docs-pr/devtest/device-fundamentals-tests.md @@ -66,11 +66,11 @@ ms.technology: windows-devices - + - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Device%20Fundamentals%20Tests%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/device-metadata-authoring-wizard-portal.md b/windows-driver-docs-pr/devtest/device-metadata-authoring-wizard-portal.md index efc65f7a35..cec20a0e3e 100644 --- a/windows-driver-docs-pr/devtest/device-metadata-authoring-wizard-portal.md +++ b/windows-driver-docs-pr/devtest/device-metadata-authoring-wizard-portal.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Device Metadata Authoring Wizard -\[This topic describes the Device Metadata Authoring tool provided in the Windows Driver Kit (WDK)8. If youre developing device experiences for Windows 8.1, use the Device Metadata Authoring Wizard available with [Microsoft Visual Studio2013 and Windows Driver Kit (WDK)8.1](http://go.microsoft.com/fwlink/p/?LinkId=226411). For more information, see [Windows 8.1 device experience](http://go.microsoft.com/fwlink/p/?linkid=325561). \] +\[This topic describes the Device Metadata Authoring tool provided in the Windows Driver Kit (WDK) 8. If you're developing device experiences for Windows 8.1, use the Device Metadata Authoring Wizard available with [Microsoft Visual Studio 2013 and Windows Driver Kit (WDK) 8.1](http://go.microsoft.com/fwlink/p/?LinkId=226411). For more information, see [Windows 8.1 device experience](http://go.microsoft.com/fwlink/p/?linkid=325561). \] ## Purpose @@ -43,9 +43,9 @@ After using the tool to define these elements for your device or service, you ca The Device Metadata Authoring Wizard is designed for use by Independent Hardware Vendors (IHVs), Original Equipment Manufacturers (OEMs), and mobile broadband carriers. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\dma]:%20Device%20Metadata%20Authoring%20Wizard%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/do-device-initializing-annotation-for-drivers.md b/windows-driver-docs-pr/devtest/do-device-initializing-annotation-for-drivers.md index b6883dbb64..839b6b5200 100644 --- a/windows-driver-docs-pr/devtest/do-device-initializing-annotation-for-drivers.md +++ b/windows-driver-docs-pr/devtest/do-device-initializing-annotation-for-drivers.md @@ -1,6 +1,6 @@ --- -title: DO\_DEVICE\_INITIALIZING Annotation for drivers -description: Use to specify whether the annotated function is expected to clear the DO\_DEVICE\_INITIALIZING bit in the Flags field of the device object. +title: DO_DEVICE_INITIALIZING Annotation for drivers +description: Use to specify whether the annotated function is expected to clear the DO_DEVICE_INITIALIZING bit in the Flags field of the device object. ms.assetid: EFC5F0A3-7B20-49A5-9D50-1737DF76DC9E ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -16,7 +16,7 @@ Use the \_Kernel\_clear\_do\_init\_ annotation to specify whether the annotated This annotation has the following syntax: -``` syntax +``` _Kernel_clear_do_init_(yes|no) ``` @@ -44,9 +44,9 @@ typedef DRIVER_ADD_DEVICE *PDRIVER_ADD_DEVICE; [SAL 2.0 Annotations for Windows Drivers](sal-2-annotations-for-windows-drivers.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20DO_DEVICE_INITIALIZING%20Annotation%20for%20drivers%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/do-i-need-to-call-wpp-check-for-null-string-.md b/windows-driver-docs-pr/devtest/do-i-need-to-call-wpp-check-for-null-string-.md index dcbf073ba3..6c7d0bd79c 100644 --- a/windows-driver-docs-pr/devtest/do-i-need-to-call-wpp-check-for-null-string-.md +++ b/windows-driver-docs-pr/devtest/do-i-need-to-call-wpp-check-for-null-string-.md @@ -1,6 +1,6 @@ --- -title: Do I need to call WPP\_CHECK\_FOR\_NULL\_STRING -description: Do I need to call WPP\_CHECK\_FOR\_NULL\_STRING +title: Do I need to call WPP_CHECK_FOR_NULL_STRING +description: Do I need to call WPP_CHECK_FOR_NULL_STRING ms.assetid: 4a4dfe91-a70b-4297-9f11-fcc4b0e5a900 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/driver-verifier.md b/windows-driver-docs-pr/devtest/driver-verifier.md index 5f98ad3297..5b626d7c4b 100644 --- a/windows-driver-docs-pr/devtest/driver-verifier.md +++ b/windows-driver-docs-pr/devtest/driver-verifier.md @@ -41,7 +41,7 @@ You can run Driver Verifier on multiple drivers simultaneously, or on one driver -

You don't need to. Driver Verifier (Verifier.exe) is included in every version of Windows, starting with Windows 2000 (in the %windir%\system32 directory). There isn't a separate Driver Verifier download package.

+

You don't need to download Driver Verifier (Verifier.exe) as it is included in every version of Windows after Windows 2000, except for Windows 10 S. There isn't a separate Driver Verifier download package, it is located in the %windir%\system32 directory.

  • Open a Command Prompt window (Run as administrator).
  • Type verifier to open the Driver Verifier Manager, or type verifier /? to view command line options. See [Driver Verifier Command Syntax](verifier-command-line.md) for more information.
  • @@ -53,6 +53,7 @@ You can run Driver Verifier on multiple drivers simultaneously, or on one driver
  • Running Driver Verifier could cause the computer to crash.
  • You should only run Driver Verifier on computers you are using for testing and debugging.
  • You must be in the Administrators group on the computer to use Driver Verifier.
  • +
  • Driver verifier is not included in Windows 10 S. We recommend testing driver behavior in Windows 10 instead.
@@ -134,7 +135,7 @@ You should only run Driver Verifier on test computers, or computers you are test   -``` syntax +``` verifier /standard /driver myDriver.sys ``` @@ -153,7 +154,7 @@ See [**Driver Verifier Command Syntax**](verifier-command-line.md) for more info Or type the following command in a Command Prompt window and reboot the computer. -``` syntax +``` verifier /reset ``` @@ -164,7 +165,7 @@ verifier /reset Or type the following command in a Command Prompt window. -``` syntax +``` verifier /querysettings ``` @@ -175,7 +176,7 @@ verifier /querysettings Or type the following command in a Command Prompt window. -``` syntax +``` verifier /query ``` @@ -201,7 +202,7 @@ For more information see [Handling a Bug Check When Driver Verifier is Enabled]( When you start a new debug session, use the debugger extension command [**!analyze**](https://msdn.microsoft.com/library/windows/hardware/ff562112). In kernel mode, the **!analyze** command displays information about the most recent bug check. The **!analyze -v** command displays additional information and attempts to pinpoint the faulting driver. -``` syntax +``` kd> !analyze -v ``` @@ -209,25 +210,25 @@ In addition [**!analyze**](https://msdn.microsoft.com/library/windows/hardware/f - [**!verifier**](https://msdn.microsoft.com/library/windows/hardware/ff565591) dumps captured Driver Verifier statistics. Use **!verifier -?** to display all of the available options. - ``` syntax + ``` kd> !verifier ``` - [**!deadlock**](https://msdn.microsoft.com/library/windows/hardware/ff562326) displays information related to locks or objects tracked by Driver Verifier's deadlock detection feature. Use **!deadlock -?** to display all of the available options. - ``` syntax + ``` kd> !deadlock ``` - [**!iovirp**](https://msdn.microsoft.com/library/windows/hardware/ff563252) \[*address*\] displays information related to an IRP tracked by I/O Verifier. For example: - ``` syntax + ``` kd> !iovirp 947cef68 ``` - [**!ruleinfo**](https://msdn.microsoft.com/library/windows/hardware/dn265374) \[*RuleID*\] displays information related to the [DDI compliance checking](ddi-compliance-checking.md) rule that was violated (*RuleID* is always the first argument to the bug check. All DDI Compliance Checking *RuleID* are in the form 0x200nn). For example: - ``` syntax + ``` kd> !ruleinfo 0x20005 ``` diff --git a/windows-driver-docs-pr/devtest/driverinstall-tests--device-fundamentals-.md b/windows-driver-docs-pr/devtest/driverinstall-tests--device-fundamentals-.md index e0c57cf9a1..59837a437a 100644 --- a/windows-driver-docs-pr/devtest/driverinstall-tests--device-fundamentals-.md +++ b/windows-driver-docs-pr/devtest/driverinstall-tests--device-fundamentals-.md @@ -66,7 +66,7 @@ The Setup API logs (setupapi.app.log and setupapi.dev.log) contain useful inform To increase the verbosity and potential usefulness of these logs, set the following registry key to 0x2000FFFF before running the Reinstall test: -``` syntax +``` HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel ``` diff --git a/windows-driver-docs-pr/devtest/enabling-wpp-tracing-through-windows-event-log.md b/windows-driver-docs-pr/devtest/enabling-wpp-tracing-through-windows-event-log.md index 2439b30739..5eaf23b5b9 100644 --- a/windows-driver-docs-pr/devtest/enabling-wpp-tracing-through-windows-event-log.md +++ b/windows-driver-docs-pr/devtest/enabling-wpp-tracing-through-windows-event-log.md @@ -62,9 +62,9 @@ Declaring a channel in this manner enables both the WPP provider (whose control WPP events are not decoded. To get message strings associated with these events, place the TMF files in the %windir%\\System32\\winevt\\TraceFormat directory. You can get the TMF files by using a utility such as Tracepdb.exe, which takes the PDB file for input and returns TMF files. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20How%20Do%20I%20Enable%20WPP%20Tracing%20Through%20the%20Windows%20Event%20Log%20Service?%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/enhanced-storage-certificate-management-tool-command-syntax.md b/windows-driver-docs-pr/devtest/enhanced-storage-certificate-management-tool-command-syntax.md index d103590c32..1e2098f540 100644 --- a/windows-driver-docs-pr/devtest/enhanced-storage-certificate-management-tool-command-syntax.md +++ b/windows-driver-docs-pr/devtest/enhanced-storage-certificate-management-tool-command-syntax.md @@ -24,7 +24,7 @@ The Enhanced Storage Certificate Management tool provides certificate management The Enhanced Storage Certificate Management tool is run from the command line. -``` syntax +``` EhStorCertMgrCmd [/Add AddParameters diff --git a/windows-driver-docs-pr/devtest/enhstor-add-switch.md b/windows-driver-docs-pr/devtest/enhstor-add-switch.md index c58a26368e..bfe375a3a2 100644 --- a/windows-driver-docs-pr/devtest/enhstor-add-switch.md +++ b/windows-driver-docs-pr/devtest/enhstor-add-switch.md @@ -22,11 +22,11 @@ ms.technology: windows-devices The **/Add** switch of the Enhanced Storage Certificate Management tool adds a certificate to the authentication silo certificate (ASC) store on a specified IEEE 1667-compliant USB storage device. -**Note**In this topic, the specified IEEE 1667-compliant USB storage device is known as the *target device*. +**Note** In this topic, the specified IEEE 1667-compliant USB storage device is known as the *target device*. - + -``` syntax +``` EhStorCertMgrCmd /Add -Volume: @@ -40,9 +40,9 @@ The **/Add** switch of the Enhanced Storage Certificate Management tool adds a c **-Volume** The volume name of the target device. For more information about the format of this parameter, see [Overview of the Enhanced Storage Certificate Management Tool](overview-of-the-enhanced-storage-certificate-management-tool.md). -**Note**To produce a list of the volume names of the IEEE 1667-compliant USB storage devices currently connected to a computer, type **EhStorCertMgrCmd /List** at the command prompt and then press **Enter**. +**Note** To produce a list of the volume names of the IEEE 1667-compliant USB storage devices currently connected to a computer, type **EhStorCertMgrCmd /List** at the command prompt and then press **Enter**. - + **-Type** The type of the certificate to be added to the ASC store in the target device. The following table defines the valid certificate types. @@ -84,7 +84,7 @@ The type of the certificate to be added to the ASC store in the target device. T - + **-Validation** The type of certificate validation procedure that is performed by the addressable command target (ACT) in the target device. The following table defines the correct validation types. @@ -116,11 +116,11 @@ The type of certificate validation procedure that is performed by the addressabl - + -**Note**If the -Validation: parameter is not specified, the tool uses a validation value of **None**. +**Note** If the -Validation: parameter is not specified, the tool uses a validation value of **None**. - + **-Index** The index within the ASC store where the certificate will be saved. If the specified index contains a certificate, that certificate will be replaced. The index value must be greater than zero. @@ -146,28 +146,28 @@ The following guidelines apply when you add certificates to the target device: - The PCp certificate is used to perform administrative authentication between the host and the target device. If the target device does not have a PCp certificate, you must first provision the target device with a PCp certificate. For the PCp certificate type, the **-Index** switch must be specified with a value of one. - **Important**It is best to only provision the target device with a PCp certificate that has its private key stored in a certificate store on your computer. If an incorrect PCp certificate is provisioned on the target device, you will not be able to clear the certificate store (which includes the PCp certificate) by using the [**/Initialize switch**](-initialize-switch.md). + **Important** It is best to only provision the target device with a PCp certificate that has its private key stored in a certificate store on your computer. If an incorrect PCp certificate is provisioned on the target device, you will not be able to clear the certificate store (which includes the PCp certificate) by using the [**/Initialize switch**](-initialize-switch.md). - + - If the **-Index** switch is not specified when you add HCh, ASCh, and SCh certificates, the tool stores the certificate in the first index within the ASC store that is not used. - **Note**In order to add these certificate types to the target device, the correct PCp certificate must reside in the host in order to pass administrative authentication with the device. + **Note** In order to add these certificate types to the target device, the correct PCp certificate must reside in the host in order to pass administrative authentication with the device. - + - If the specified index is not empty in the target device, the **/Add** switch replaces the existing certificate with the specified certificate. - **Note**If the Enhanced Storage Certificate Management tool replaces an ASCh certificate at the specified index, the tool removes all related SCh in the ASCh certificate chain. + **Note** If the Enhanced Storage Certificate Management tool replaces an ASCh certificate at the specified index, the tool removes all related SCh in the ASCh certificate chain. If the tool replaces an SCh certificate at the specified index that is part of an ASCh certificate chain, the tool removes the SCh certificate together with all its parent SCh certificates in the certificate chain. - + - Only one of the **-Store**, -**File** or **-New** parameters must be specified. -**Note** The Enhanced Storage Certificate Management tool cannot add, remove, or replace the ASC-manufacturer (ASCm) certificate from the ASC store in the target device. +**Note** The Enhanced Storage Certificate Management tool cannot add, remove, or replace the ASC-manufacturer (ASCm) certificate from the ASC store in the target device. - + ### Example @@ -177,9 +177,9 @@ The following example shows how to add a certificate from the certificate store EhStorCertMgrCmd /Add -Volume:"\\?\usbstor#ieee1667control&ven_&prod_&rev_#123456789&0&control#{4f40006f-b933-4550-b532-2b58cee614d3}" -Index:1 -Store:TestCert -Type:PCp -Validation:None ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20/Add%20Switch%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/example-15--measuring-dpc-isr-time.md b/windows-driver-docs-pr/devtest/example-15--measuring-dpc-isr-time.md index 2b49d2901d..6b0e893321 100644 --- a/windows-driver-docs-pr/devtest/example-15--measuring-dpc-isr-time.md +++ b/windows-driver-docs-pr/devtest/example-15--measuring-dpc-isr-time.md @@ -149,7 +149,7 @@ In this command, the **-report** parameter specifies the method of analysis and When creating this report in Windows Server 2003 with SP1 and later versions of Windows, you can create an HTML-formatted report by using the following command. ``` -tracerpt test01.etl -report dpcisr.txt -f HTML +tracerpt test01.etl -report dpcisr.html -f HTML ``` In this command, the **-report** parameter specifies the name of the output file and the **-f** parameter specifies the report format. diff --git a/windows-driver-docs-pr/devtest/floating-point-annotations-for-drivers.md b/windows-driver-docs-pr/devtest/floating-point-annotations-for-drivers.md index 3a456c7656..e6da4539dd 100644 --- a/windows-driver-docs-pr/devtest/floating-point-annotations-for-drivers.md +++ b/windows-driver-docs-pr/devtest/floating-point-annotations-for-drivers.md @@ -68,7 +68,7 @@ KeSaveFloatingPointState ( In the following example, the \_Kernel\_float\_used\_ annotation suppresses warnings about the use of the floating-point state. The annotation also causes the code analysis tools to confirm that any calls to MyDoesFloatingPoint occur in a safe floating-point context. -``` syntax +``` _Kernel_float_used_ void MyDoesFloatingPoint(arguments); diff --git a/windows-driver-docs-pr/devtest/how-to-collect-irp-coverage-data.md b/windows-driver-docs-pr/devtest/how-to-collect-irp-coverage-data.md index 9f412fabd2..f2d5a0dc0e 100644 --- a/windows-driver-docs-pr/devtest/how-to-collect-irp-coverage-data.md +++ b/windows-driver-docs-pr/devtest/how-to-collect-irp-coverage-data.md @@ -44,13 +44,13 @@ For information about setting up the WDK and the Visual Studio test environment, After the test computer has restarted, verify that the filter driver is installed and the correct devices are enabled for IRP coverage. To do this, run the **Display Devices enabled for IRP coverage data collection** tool on the test computer. - ``` syntax + ``` Drvcov /D ``` The following example shows sample output from this tool: - ``` syntax + ``` |------------------------------------------------------------------ | List of devices we can get coverage data from. |------------------------------------------------------------------ diff --git a/windows-driver-docs-pr/devtest/how-to-fix-tracelogging-build-errors.md b/windows-driver-docs-pr/devtest/how-to-fix-tracelogging-build-errors.md index d80213a73f..cbfcd9269e 100644 --- a/windows-driver-docs-pr/devtest/how-to-fix-tracelogging-build-errors.md +++ b/windows-driver-docs-pr/devtest/how-to-fix-tracelogging-build-errors.md @@ -33,7 +33,7 @@ Include windows.h before including TraceLoggingProvider.h in your source file. Build Error (snippet): After copying the TraceLogging header files into your build environment and adding this line: -``` syntax +``` TraceLoggingRegisterByGuid(g_3DBuilderTraceProvider, &s_3DBuilderTraceProviderGuid); ``` diff --git a/windows-driver-docs-pr/devtest/inf-validation-errors-and-warnings.md b/windows-driver-docs-pr/devtest/inf-validation-errors-and-warnings.md index e90ff5ecc6..722f254273 100644 --- a/windows-driver-docs-pr/devtest/inf-validation-errors-and-warnings.md +++ b/windows-driver-docs-pr/devtest/inf-validation-errors-and-warnings.md @@ -134,29 +134,29 @@ CatalogFile=wudf.cat
 [MyAddReg]
-HKR,,DllPath,%SystemRoot%\System32\myDll.sys
+HKR,,DllPath,%SystemRoot%\System32\myDll.sys
 
-

This line causes the INF parser to attempt to locate the token "SystemRoot" from the [Strings] section, rather than the intended behavior of storing the literal "%SystemRoot%" in the registry. To use the literal value %SystemRoot% rather than perform a string replacement, use the escape sequence %%.

+

This line causes the INF parser to attempt to locate the token "SystemRoot" from the [Strings] section, rather than the intended behavior of storing the literal "%SystemRoot%" in the registry. To use the literal value %SystemRoot% rather than perform a string replacement, use the escape sequence %%.

 [MyAddReg]
-HKR,,DllPath,%%SystemRoot%%\System32\myDll.sys
+HKR,,DllPath,%%SystemRoot%%\System32\myDll.sys
 
- + ## Universal INF errors (1300-1309) -**Important** +**Important** If you do not get any errors or warnings with error number 130*x* and error text ("Found legacy *Xxx* operation..."), your driver INF file is universal. - + The following errors and warnings are related to INF configurability: @@ -173,15 +173,15 @@ The following errors and warnings are related to INF configurability: -

1301: Found legacyXxx

+

1301: Found legacyXxx

You'll see this error if you use deprecated sections or directives such as [LogConfig](https://msdn.microsoft.com/library/windows/hardware/ff547448) or [DDInstall.CoInstallers](https://msdn.microsoft.com/library/windows/hardware/ff547321).

-

1302: Found legacyXxxoperationXxx

+

1302: Found legacyXxxoperationXxx

You'll see this error if you use deprecated sections or directives such as [LogConfig](https://msdn.microsoft.com/library/windows/hardware/ff547448) or [DDInstall.CoInstallers](https://msdn.microsoft.com/library/windows/hardware/ff547321).

-

1303: Found legacyXxxoperation forXxx

+

1303: Found legacyXxxoperation forXxx

This error occurs when the operation affects something external to the driver package, like deleting a service or deleting a file.

@@ -208,7 +208,7 @@ AddReg = HKR,,CoInstallers32,0x00010000,"MyCoinstaller.dll" - + Whether these issues appear as errors or warnings depends on the following: @@ -283,10 +283,10 @@ LogConfig=LogConfigSection - - - + + + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20INF%20Validation%20Errors%20and%20Warnings%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/inf2cat.md b/windows-driver-docs-pr/devtest/inf2cat.md index 7b6debc667..97196ee179 100644 --- a/windows-driver-docs-pr/devtest/inf2cat.md +++ b/windows-driver-docs-pr/devtest/inf2cat.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Inf2Cat (Inf2Cat.exe) is a command-line tool that determines whether a [driver package's](https://msdn.microsoft.com/library/windows/hardware/ff544840) INF file can be digitally-signed for a specified list of Windows versions. If so, Inf2Cat generates the unsigned [catalog files](https://msdn.microsoft.com/library/windows/hardware/ff537872) that apply to the specified Windows versions. -``` syntax +``` Inf2Cat /driver: PackagePath /os: diff --git a/windows-driver-docs-pr/devtest/interpreting-a-bug-check-code.md b/windows-driver-docs-pr/devtest/interpreting-a-bug-check-code.md index ba261b6185..2a17439804 100644 --- a/windows-driver-docs-pr/devtest/interpreting-a-bug-check-code.md +++ b/windows-driver-docs-pr/devtest/interpreting-a-bug-check-code.md @@ -28,7 +28,7 @@ If no debugger is attached, a blue text screen appears with information about th The exact appearance of the bug check screen depends on the cause of the error. The following is an example of one possible bug check screen: -``` syntax +``` STOP: 0x00000079 (0x00000002, 0x00000001, 0x00000002, 0x00000000) Mismatched kernel and hal image. @@ -40,7 +40,7 @@ technical support group. On the other hand, some blue screens look like this: -``` syntax +``` STOP: c000021a {Fatal System Error} The Windows Logon Process system process terminated unexpectedly with diff --git a/windows-driver-docs-pr/devtest/irp-logging.md b/windows-driver-docs-pr/devtest/irp-logging.md index 6dbc275de5..b17b5e788b 100644 --- a/windows-driver-docs-pr/devtest/irp-logging.md +++ b/windows-driver-docs-pr/devtest/irp-logging.md @@ -104,7 +104,7 @@ For each device the format is: Here is a sample DC2WMIParser log file. In an actual file there will not be any spaces, comments, or blank lines, but these have been added to this example to make it more clear. -``` syntax +``` 2 There are two devices described by this log file. The first device begins here: diff --git a/windows-driver-docs-pr/devtest/jsconstraintsdebug.md b/windows-driver-docs-pr/devtest/jsconstraintsdebug.md index 840a855ce0..846d815601 100644 --- a/windows-driver-docs-pr/devtest/jsconstraintsdebug.md +++ b/windows-driver-docs-pr/devtest/jsconstraintsdebug.md @@ -102,7 +102,7 @@ function validatePrintTicket(PrintTicket, scriptContext) ## JSConstraintsDebug Command Syntax -``` syntax +``` JSConstraintsDebug [MergePrintTicket] [Constraints] ``` @@ -152,19 +152,19 @@ JSConstraintsDebug [MergePrintTicket] [Constraints] Debug a print driver against a known test print ticket. -``` syntax +``` JSConstraintsDebug “Contoso Printer” PrintTicket.xml ``` Debug a print driver with a new constraints source file against a known test print ticket. -``` syntax +``` JSConstraintsDebug “Contoso Printer” PrintTicket.xml Constraints.js ``` Test merge and validate operations between two custom print tickets. -``` syntax +``` JSConstraintsDebug “Contoso Printer” PrintTicket.xml PrintTicket2.xml ``` diff --git a/windows-driver-docs-pr/devtest/makecert.md b/windows-driver-docs-pr/devtest/makecert.md index 921a526e6c..e4948241e7 100644 --- a/windows-driver-docs-pr/devtest/makecert.md +++ b/windows-driver-docs-pr/devtest/makecert.md @@ -24,7 +24,7 @@ MakeCert (Makecert.exe) is a command-line [CryptoAPI](http://go.microsoft.com/fw MakeCert supports a large number of switches but this section only describes the basic switches that are relevant to creating a [test certificate](https://msdn.microsoft.com/library/windows/hardware/ff548693) that can be used to test-sign a [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) or embed a signature in a driver file. -``` syntax +``` MakeCert [/b DateStart] [/e DateEnd] [/len KeyLength] [/m nMonths] [/n "Name"] [/pe] [/r] [/sc SubjectCertFile] [/sk SubjectKey] [/sr SubjectCertStoreLocation] [/ss SubjectCertStoreName] [/sv SubjectKeyFile]OutputFile ``` diff --git a/windows-driver-docs-pr/devtest/message-compiler-task.md b/windows-driver-docs-pr/devtest/message-compiler-task.md index 5fcf77f5e7..dab364f3aa 100644 --- a/windows-driver-docs-pr/devtest/message-compiler-task.md +++ b/windows-driver-docs-pr/devtest/message-compiler-task.md @@ -29,7 +29,7 @@ The following example shows how to edit the metadata in the .vcxproj file. The following example shows the command-line invocation: -``` syntax +``` mc.exe –s "c:\test\" a.mc ``` diff --git a/windows-driver-docs-pr/devtest/miscellaneous-checks.md b/windows-driver-docs-pr/devtest/miscellaneous-checks.md index d77bc84e84..33168d67a3 100644 --- a/windows-driver-docs-pr/devtest/miscellaneous-checks.md +++ b/windows-driver-docs-pr/devtest/miscellaneous-checks.md @@ -73,7 +73,7 @@ You can activate the Miscellaneous Checks option for one or more drivers by usin On Windows Vista and later versions of Windows, you can also activate and deactivate Miscellaneous Checks without rebooting the computer by adding the **/volatile** parameter to the command. For example: - ``` syntax + ``` verifier /volatile /flags 0x800 /adddriver MyDriver.sys ``` @@ -81,7 +81,7 @@ You can activate the Miscellaneous Checks option for one or more drivers by usin The Miscellaneous Checks option is also included in the standard settings. For example: - ``` syntax + ``` verifier /standard /driver MyDriver.sys ``` @@ -100,7 +100,7 @@ To view the results of the Miscellaneous Checks option, use the **!verifier** ex In the following example, the Miscellaneous Checks option detected an active ERESOURCE structure in memory that the driver was trying to free, resulting in [**Bug Check 0xC4: DRIVER\_VERIFIER\_DETECTED\_VIOLATION**](https://msdn.microsoft.com/library/windows/hardware/ff560187). The Bug Check 0xC4 display includes the address of the ERESOURCE and the affected memory. -``` syntax +``` 1: kd> !verifier 1 Verify Level 800 ... enabled options are: @@ -153,7 +153,7 @@ Pool page 9655d468 region is Paged pool To find information about the ERESOURCE, use the [**!locks (!kdext\*.locks)**](https://msdn.microsoft.com/library/windows/hardware/ff563980) debugger extension with the address of the structure. -``` syntax +``` 1: kd> !locks 0x9655D4A8 <<<<<- ERESOURCE @0x9655D4A8 lives inside the pool block being freed Resource @ 0x9655d4a8 Available @@ -162,7 +162,7 @@ Resource @ 0x9655d4a8 Available You can also use the **kb** debugger command to display a stack trace of the calls that led to the failure. The following example shows the stack, including the call to **ExFreePoolWithTag** that Driver Verifier intercepted. -``` syntax +``` 1: kd> kb ChildEBP RetAddr Args to Child 92f6374c 82c2c95a 00000003 92f68cdc 00000000 nt!RtlpBreakWithStatusInstruction diff --git a/windows-driver-docs-pr/devtest/nmake2msbuild.md b/windows-driver-docs-pr/devtest/nmake2msbuild.md index 4f8e7a76a8..f805dd8748 100644 --- a/windows-driver-docs-pr/devtest/nmake2msbuild.md +++ b/windows-driver-docs-pr/devtest/nmake2msbuild.md @@ -25,7 +25,7 @@ For information about using the utility, see [Converting a WDK sources file to a The Nmake2MsBuild.exe utility has the following syntax: -``` syntax +``` NMake2MSBuild.exe < sources [...] | dirs > [-Name:] [-Package:] @@ -102,7 +102,7 @@ To build a driver project that was built with a previous version of the WDK (usi For example, to convert a driver that was previously built with the Windows 7 WDK, called MyDriver, you first open a **Visual Studio Command Prompt** window. Browse to the directory or supply the path to the directory that contains the *sources* or *dirs* build configuration file. For example, the following command generates the MyDriver.Vcxproj file in the same folder as the *sources* file. -``` syntax +``` nmake2msbuild.exe .\myDriver\sources ``` diff --git a/windows-driver-docs-pr/devtest/overview-of-the-boot-ini-file.md b/windows-driver-docs-pr/devtest/overview-of-the-boot-ini-file.md index 5ea3650ff6..de6d2b71a6 100644 --- a/windows-driver-docs-pr/devtest/overview-of-the-boot-ini-file.md +++ b/windows-driver-docs-pr/devtest/overview-of-the-boot-ini-file.md @@ -1,6 +1,6 @@ --- title: Overview of the Boot.ini File -description: The Boot.ini file is a text file that contains the boot options for computers with BIOS firmware running NT-based operating system prior to Windows Vista. It is located at the root of the system partition, typically c \\Boot.ini. +description: The Boot.ini file is a text file that contains the boot options for computers with BIOS firmware running NT-based operating system prior to Windows Vista. It is located at the root of the system partition, typically c:\Boot.ini. ms.assetid: bc9bb063-4caa-42fe-bb3d-dc588fbbb8d9 keywords: - Boot.ini files WDK , about Boot.ini files diff --git a/windows-driver-docs-pr/devtest/place-file-syntax.md b/windows-driver-docs-pr/devtest/place-file-syntax.md index 07bda6d26f..2ffd2ac16c 100644 --- a/windows-driver-docs-pr/devtest/place-file-syntax.md +++ b/windows-driver-docs-pr/devtest/place-file-syntax.md @@ -30,7 +30,7 @@ The path and name of this file are specified by the -p PlaceFile command-line pa Each line of a place file has the same format. -``` syntax +``` FileName Class[:Class[...] [ ; Comment ] diff --git a/windows-driver-docs-pr/devtest/pnp-tests--device-fundamentals-.md b/windows-driver-docs-pr/devtest/pnp-tests--device-fundamentals-.md index d16d021498..e5c2803b0b 100644 --- a/windows-driver-docs-pr/devtest/pnp-tests--device-fundamentals-.md +++ b/windows-driver-docs-pr/devtest/pnp-tests--device-fundamentals-.md @@ -291,7 +291,7 @@ The Setup API logs (setupapi.app.log and setupapi.dev.log) might contain useful To increase the verbosity and potential usefulness of these logs, set the following registry key to 0x2000FFFF before running the Reinstall test: -``` syntax +``` HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel ``` diff --git a/windows-driver-docs-pr/devtest/pnputil-command-syntax.md b/windows-driver-docs-pr/devtest/pnputil-command-syntax.md index 358c3da15e..e130108f08 100644 --- a/windows-driver-docs-pr/devtest/pnputil-command-syntax.md +++ b/windows-driver-docs-pr/devtest/pnputil-command-syntax.md @@ -1,6 +1,6 @@ --- title: PnPUtil Command Syntax -description: To run PnPUtil, open a Command Prompt window (Run as Administrator) and type a command using the following syntax and parameters.Note  PnPUtil (PnPUtil.exe) is included in every version of Windows, starting with Windows Vista (in the windir \\system32 directory). � +description: How to run PnPUtil, including syntax and parameters. ms.assetid: f14ceb98-8d82-43dd-b06e-2595b59b6999 keywords: - PnPUtil Command Syntax Driver Development Tools @@ -26,7 +26,7 @@ To run PnPUtil, open a Command Prompt window (**Run as Administrator**) and type   -``` syntax +``` PnPUtil [/a [/i] InfFileName] [/d [/f] PublishedInfFileName] [/e] [/?] ``` @@ -38,7 +38,7 @@ Adds a [driver package](https://msdn.microsoft.com/library/windows/hardware/ff54 The **/a** switch has the following optional parameters: -/i +**/i** Installs the [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) on matching devices that are connected to the system. The driver package is installed after it is added to the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868). **Note**  When you add a [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) to the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868) by using the **/a** switch, Windows uses a different name (*published name*) for the driver package's [INF file](https://msdn.microsoft.com/library/windows/hardware/ff547402). You must use the published name of the INF file for the *PublishedInfFileName* parameter of the **/d** switch. @@ -50,7 +50,7 @@ Removes a [driver package](https://msdn.microsoft.com/library/windows/hardware/f The **/d** switch has the following optional parameters: -/f +**/f** Forces the deletion of the specified [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) from the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868). You must use this parameter if the specified driver package is installed on a device that is connected to the system. If this parameter is not specified, PnPUtil only removes a driver package if it was not used to install drivers for devices that are connected to the system. **Note**  Removing the driver package in this manner will not affect the operation of currently connected devices for which drivers were previously installed from the package. diff --git a/windows-driver-docs-pr/devtest/pnputil-examples.md b/windows-driver-docs-pr/devtest/pnputil-examples.md index 70ca159ac7..f6711fdd88 100644 --- a/windows-driver-docs-pr/devtest/pnputil-examples.md +++ b/windows-driver-docs-pr/devtest/pnputil-examples.md @@ -16,11 +16,13 @@ This topic provides the following examples on how to use the PnPUtil tool: - [Adding a driver package to the driver store](#adding-a-driver-package-to-the-driver-store) +- [Installing a driver package](#installing-a-driver-package) + - [Listing the driver packages within the driver store](#listing-the-driver-packages-within-the-driver-store) - [Deleting a driver package from the driver store](#deleting-a-driver-package-from-the-driver-store) -### Adding a driver package to the driver store +## Adding a driver package to the driver store The following example adds a [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840), which contains the [INF](https://msdn.microsoft.com/library/windows/hardware/ff547402) file that is named MyDriver.inf, to the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868): @@ -36,8 +38,16 @@ Published name : oem22.inf As soon as it is added to the driver store, the INF file for the driver package is referenced within the store through its published named (oem22.inf). -### Listing the driver packages within the driver store +## Installing a driver package + +The following example adds the driver package to the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868) and then installs the driver package on the computer: + +``` +C:\>pnputil /a m:\MyDriver.inf /i +Microsoft PnP Utility +``` +## Listing the driver packages within the driver store The following example lists the [driver packages](https://msdn.microsoft.com/library/windows/hardware/ff544840) that are currently in the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868). Only driver packages that are not in-box packages are listed. An *in-box* driver package is one which is included in the default installation of Windows or its service packs: @@ -64,7 +74,7 @@ In this example, information is displayed about the [driver package](https://msd   -### Deleting a driver package from the driver store +## Deleting a driver package from the driver store The following example removes the [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) from the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868). The driver package is referenced by its published INF file (oem22.inf): diff --git a/windows-driver-docs-pr/devtest/pnputil.md b/windows-driver-docs-pr/devtest/pnputil.md index 149485fc7b..28c745e354 100644 --- a/windows-driver-docs-pr/devtest/pnputil.md +++ b/windows-driver-docs-pr/devtest/pnputil.md @@ -16,6 +16,8 @@ PnPUtil (PnPUtil.exe) is a command line tool that lets an administrator perform - Adds a driver package to the [driver store](https://msdn.microsoft.com/library/windows/hardware/ff544868). +- Installs a driver package on the computer. + - Deletes a driver package from the driver store. - Enumerates the driver packages that are currently in the driver store. Only driver packages that are not in-box packages are listed. An *in-box* driver package is one which is included in the default installation of Windows or its service packs. @@ -50,7 +52,7 @@ PnPUtil (PnPUtil.exe) is a command line tool that lets an administrator perform This section includes the following: -[**PnPUtil Command Syntax**](pnputil-command-syntax.md) +[PnPUtil Command Syntax](pnputil-command-syntax.md) [PnPUtil Examples](pnputil-examples.md) diff --git a/windows-driver-docs-pr/devtest/pool-tracking.md b/windows-driver-docs-pr/devtest/pool-tracking.md index d5aef81f0a..b8c56b48f9 100644 --- a/windows-driver-docs-pr/devtest/pool-tracking.md +++ b/windows-driver-docs-pr/devtest/pool-tracking.md @@ -96,9 +96,9 @@ You can activate the Pool Tracking feature for one or more drivers by using Driv The Pool Tracking feature is also included in the standard settings. To use this feature, in Driver Verifier Manager, click **Create Standard Settings**. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20Pool%20Tracking%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/poolmon-display.md b/windows-driver-docs-pr/devtest/poolmon-display.md index c4b928f79a..c8ed054fae 100644 --- a/windows-driver-docs-pr/devtest/poolmon-display.md +++ b/windows-driver-docs-pr/devtest/poolmon-display.md @@ -89,7 +89,7 @@ The following table describes the columns in the PoolMon display. The following sample PoolMon output is sorted by number of allocations. (To sort your display this way, start PoolMon with the **/a** parameter.) -``` syntax +``` Memory: 260620K Avail: 96364K PageFlts: 0 InRam Krnl: 1916K P:17856K Commit: 203500K Limit: 640916K Peak: 260632K Pool N: 8332K P:27220K System pool information diff --git a/windows-driver-docs-pr/devtest/poolmon-run-time-commands.md b/windows-driver-docs-pr/devtest/poolmon-run-time-commands.md index 5988778485..9041cd473b 100644 --- a/windows-driver-docs-pr/devtest/poolmon-run-time-commands.md +++ b/windows-driver-docs-pr/devtest/poolmon-run-time-commands.md @@ -22,7 +22,7 @@ ms.technology: windows-devices To change the display while PoolMon is running, use the run-time commands. Each run-time command consists of a single keyboard character. Press the key to execute the command. -``` syntax +``` [p] [( | )] [s] [TSSessionID] [i] [l] [e] [t] [a] [f] [d] [b] [m] [h | ?] [q | ESC] @@ -80,9 +80,9 @@ Displays the startup command parameters, the run-time commands, and a descriptio **q** or **ESC** Stops PoolMon. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20PoolMon%20Run-time%20Commands%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/poolmon-startup-command.md b/windows-driver-docs-pr/devtest/poolmon-startup-command.md index a4706f7d5d..4ac54f1824 100644 --- a/windows-driver-docs-pr/devtest/poolmon-startup-command.md +++ b/windows-driver-docs-pr/devtest/poolmon-startup-command.md @@ -22,7 +22,7 @@ ms.technology: windows-devices To start PoolMon, type a command at the command line using the following syntax and parameters. -``` syntax +``` poolmon [/iTag] [/xTag] [/c [LocalTagFile]] [/g [PoolTagFile]] [/s[TSSessionID]] [ /p | /p /p ] [/e] [/( | /)] [/t | /a| /f| /d | /b| /m] [/l] [/n [File]] [/? | /h] diff --git a/windows-driver-docs-pr/devtest/projectupgradetool.md b/windows-driver-docs-pr/devtest/projectupgradetool.md index 200aa54958..b668103e53 100644 --- a/windows-driver-docs-pr/devtest/projectupgradetool.md +++ b/windows-driver-docs-pr/devtest/projectupgradetool.md @@ -1,6 +1,6 @@ --- title: ProjectUpgradeTool -description: The ProjectUpgradeTool takes Microsoft Visual Studio 2012 project (\ .vcxproj) and solution files (\ .sln) that were created with the Windows Driver Kit (WDK) for Windows 8 and upgrades them to work with the WDK for Windows 8.1 and Microsoft Visual Studio 2013. +description: The ProjectUpgradeTool takes Microsoft Visual Studio 2012 projects (*.vcxproj) and solution files (*.sln) that were created with the Windows Driver Kit (WDK) for Windows 8 and upgrades them to work with the WDK for Windows 8.1 and Microsoft Visual Studio 2013. ms.assetid: DEB7799C-D505-40E6-B2B0-CF774A99B1BE ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -23,7 +23,7 @@ The ProjectUpgradeTool takes Microsoft Visual Studio 2012 project (\*.vcxproj) a 1. Open a Visual Studio Command Prompt window. 2. Type the command **ProjectUpgradeTool** and specify the root (or parent) directory that contains the Windows Driver Kit (WDK) 8 project or solution files that you want to upgrade to the Windows Driver Kit (WDK) 8.1 for Windows 8.1. For example, the following command upgrades all the files in C:\\myDriver directory and subdirectories. - ``` syntax + ``` ProjectUpgradeTool.exe C:\myDriver ``` @@ -39,7 +39,7 @@ The project upgrade tool is located in the %WindowsSdkDir%\\bin\\x86\\ directory The ProjectUpgradeTool.exe has the following syntax: -``` syntax +``` ProjectUpgradeTool.exe < rootDir > [-Log:[]:[]] [-ConsoleLog:] @@ -105,7 +105,7 @@ ProjectUpgradeTool.exe < rootDir > If you attempt to open a project or solution that was created with WDK 8, you might see the following error message when you attempt to build the project using WDK 8.1. -``` syntax +``` 1>C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V120\Microsoft.Cpp.Platform.targets(54,5): error MSB8020: The builds tools for WindowsKernelModeDriver8.0 (Platform Toolset = 'WindowsKernelModeDriver8.0') cannot be found. To build using the WindowsKernelModeDriver8.0 build tools, please install WindowsKernelModeDriver8.0 build tools. Alternatively, you may update to the current Visual Studio tools by selecting the Project menu or right-click the solution, and then selecting "Update VC++ Projects...". ``` @@ -119,17 +119,17 @@ The platform toolset in the WDK 8 was **WindowsKernelModeDriver8.0**. To fix thi You open the project in WDK 8.1. When you build a Win32 Windows Vista target, you might see the following error message: -``` syntax +``` error MSB6004: The specified task executable location "C:\Program Files (x86)\Windows Kits\8.0\bin\x86\x86\CL.exe" is invalid. C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V110\Microsoft.CppCommon.targets 347 5 KMDF Driver1 ``` When you build an x64 Windows Vista target, you might see the following error messages: -``` syntax +``` error TRK0002: Failed to execute command: ""C:\Program Files (x86)\Windows Kits\8.0\bin\x64\stampinf.exe" -d * -a amd64 -v * -k 1.11 -u 1.11.0 -f x64\VistaRelease\KMDFDriver1.inf". The operation identifier is not valid. C:\Users\Administrator\Desktop\KMDF Driver1 - Copy\KMDF Driver1\TRACKER KMDF Driver1 ``` -``` syntax +``` error : Verification Error: Driver package has no driver version. C:\Program Files (x86)\Windows Kits\8.0\build\WindowsDriver8.0.common.targets 1338 5 KMDF Driver1 Package ``` diff --git a/windows-driver-docs-pr/devtest/pvk2pfx.md b/windows-driver-docs-pr/devtest/pvk2pfx.md index d0076a02c4..c376a1e56c 100644 --- a/windows-driver-docs-pr/devtest/pvk2pfx.md +++ b/windows-driver-docs-pr/devtest/pvk2pfx.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Pvk2Pfx (Pvk2Pfx.exe) is a command-line tool copies public key and private key information contained in .spc, .cer, and .pvk files to a Personal Information Exchange (.pfx) file. -``` syntax +``` pvk2pfx /pvk pvkfilename.pvk [/pi pvkpassword] /spc spcfilename.ext [/pfx pfxfilename.pfx [/po pfxpassword] [/f]] ``` @@ -59,7 +59,7 @@ A 32-bit version of the Pvk2Pfx tool is located in the bin\\x86 folder of the WD The following command generates the .pfx file Mypfxfile.pfx from Mypvkfile.pvk and Myspcfile.spc. The command supplies the password mypassword for the .pvk file, which becomes the password for the .pfx file Mypfxfile.pfx. If there is an existing file named Mypfxfile.pfx, the **-f** switch configures the Pvk2Pfx tool to replace the existing file with a new file. -``` syntax +``` pvk2pfx -pvk mypvkfile.pvk -pi mypassword -spc myspcfile.spc -pfx mypfxfile.pfx -f ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-battery-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-battery-scenario.md index f80f3e801b..fb0723e17f 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-battery-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-battery-scenario.md @@ -18,7 +18,7 @@ PwrTest is capable of logging battery capacity, voltage, rate of drain, and gene ### Syntax -``` syntax +``` pwrtest /battery [/c:n] [/i:n] [/?] ``` @@ -30,11 +30,11 @@ Specifies the polling interval in milliseconds (the default is 5000). **Examples** -``` syntax +``` pwrtest /battery ``` -``` syntax +``` pwrtest /battery /c:4 /i:1000 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-connected-standby--cs--scenario.md b/windows-driver-docs-pr/devtest/pwrtest-connected-standby--cs--scenario.md index e3b5541ff9..f0bc044282 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-connected-standby--cs--scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-connected-standby--cs--scenario.md @@ -21,7 +21,7 @@ This scenario requires the test system to support the *Always on Always connecte ## Syntax -``` syntax +``` pwrtest /cs [/c:n] [/d:n] [/p:n][/?] ``` @@ -36,11 +36,11 @@ Specifies the connected standby exit time (in seconds; 60 seconds is the default **Examples** -``` syntax +``` pwrtest /cs /c:4 ``` -``` syntax +``` pwrtest /cs /c:4 /p:120 /d:150 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-device-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-device-scenario.md index 87d3a9f44f..78edb9f992 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-device-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-device-scenario.md @@ -19,7 +19,7 @@ This scenario is primarily used for Windows 7 device power activity, subsequent ## Syntax -``` syntax +``` pwrtest /device [/t:n] [/?] ``` @@ -28,11 +28,11 @@ Specifies the total time (in minutes) for the scenario to run (the default value **Examples** -``` syntax +``` pwrtest /device /t:60 ``` -``` syntax +``` pwrtest /device ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-disk-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-disk-scenario.md index af821ab901..a55f0c7dcc 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-disk-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-disk-scenario.md @@ -24,7 +24,7 @@ This scenario does not work for all types of disks or controllers because not al ## Syntax -``` syntax +``` pwrtest /disk [/t:n] [/?] ``` @@ -33,11 +33,11 @@ Specifies the total time (in minutes) for the scenario to run (the default value **Examples** -``` syntax +``` pwrtest /disk /t:60 ``` -``` syntax +``` pwrtest /disk ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-execution-state-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-execution-state-scenario.md index 40346b5082..15955d666a 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-execution-state-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-execution-state-scenario.md @@ -25,7 +25,7 @@ You can use the **/es** scenario together with [PwrTest Idle Scenario](pwrtest-i ### Syntax -``` syntax +``` pwrtest /es [/t:n] [/stes:{y|n}] [/rss:{y|n}] [/sss:{y|n}] [/all] [/user] [/kernel] [/idle] [/?] ``` @@ -55,43 +55,43 @@ Log idle statistics. **Examples** -``` syntax +``` pwrtest /es /all ``` -``` syntax +``` pwrtest /es /user ``` -``` syntax +``` pwrtest /es /kernel ``` -``` syntax +``` pwrtest /es /kernel /sss:n ``` -``` syntax +``` pwrtest /es /kernel /rss:n ``` -``` syntax +``` pwrtest /es /kernel /rss:y /sss:n ``` -``` syntax +``` pwrtest /es /sss:n ``` -``` syntax +``` pwrtest /es /rss:n /sss:n ``` -``` syntax +``` pwrtest /es /stes:n ``` -``` syntax +``` pwrtest /es /all /idle ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-idle-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-idle-scenario.md index 8c82864325..fcf1fd1e05 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-idle-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-idle-scenario.md @@ -23,7 +23,7 @@ You can combine this scenario with the [PwrTest Execution State Scenario](pwrtes ## Syntax -``` syntax +``` pwrtest /idle [/t:n] [/?] [/es [es_options] ``` @@ -35,15 +35,15 @@ Runs the [PwrTest Execution State (ES) Scenario](pwrtest-execution-state-scenari **Examples** -``` syntax +``` pwrtest /idle /t:60 ``` -``` syntax +``` pwrtest /idle /es /user ``` -``` syntax +``` pwrtest /idle /es /kernel ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-info-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-info-scenario.md index 375dad1ae6..86a50e615e 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-info-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-info-scenario.md @@ -17,7 +17,7 @@ The PwrTest Info Scenario captures and logs the current system power information ## Syntax -``` syntax +``` pwrtest /info:option [/p:{n|a|*}] [/w:n] [/?] ``` @@ -84,27 +84,27 @@ Specifies the time in seconds to wait for PPM rundown event (default is 10 secon **Examples** -``` syntax +``` pwrtest /info:all ``` -``` syntax +``` pwrtest /info:battery ``` -``` syntax +``` pwrtest /info:ppm ``` -``` syntax +``` pwrtest /info:ppm /p:1 ``` -``` syntax +``` pwrtest /info:ppmidle ``` -``` syntax +``` pwrtest /info:ppmperf /p:2 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-monitor-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-monitor-scenario.md index b187b15946..e1d053f557 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-monitor-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-monitor-scenario.md @@ -21,7 +21,7 @@ If you run both scenarios, be sure to use the **/ln:***name* parameter so that y ## Syntax -``` syntax +``` pwrtest /monitor [/t:n] [/?] ``` @@ -30,11 +30,11 @@ Specifies the total time (in minutes) for the scenario to run (the default value **Examples** -``` syntax +``` pwrtest /device ``` -``` syntax +``` pwrtest /device /t:60 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-platform-idle---platidle--scenario.md b/windows-driver-docs-pr/devtest/pwrtest-platform-idle---platidle--scenario.md index 798481d681..0f0ed2ce6e 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-platform-idle---platidle--scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-platform-idle---platidle--scenario.md @@ -21,7 +21,7 @@ The **/platidle** scenario requires that the computer has support for the *Alway ## Syntax -``` syntax +``` pwrtest /platidle [/t:n] [/i:n] [/?] ``` @@ -33,11 +33,11 @@ Specifies the polling interval (in seconds) for gathering platform idle statisti **Examples** -``` syntax +``` pwrtest /platidle /t:60 ``` -``` syntax +``` pwrtest /platidle ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-ppm-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-ppm-scenario.md index d8fe430a7e..d56b375228 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-ppm-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-ppm-scenario.md @@ -17,7 +17,7 @@ The PwrTest PPM Scenario logs processor power management (PPM) information and p ## Syntax -``` syntax +``` pwrtest /ppm [/n:n] [/i:n] [/c:[y|n]] [/p:{y|n}] [/u:{y|n}] [/live] [/t:n] [/?] ``` @@ -44,19 +44,19 @@ Specifies the indicates the total runtime, in minutes, for the **/live** option **Examples** -``` syntax +``` pwrtest /ppm /c:y /p:y /u:y /n:60 /i:1000 ``` -``` syntax +``` pwrtest /ppm /c:n /p:n /u:y /n:3600 /i:1000 ``` -``` syntax +``` pwrtest /ppm /live ``` -``` syntax +``` pwrtest /ppm /live /t:60 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-processidle-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-processidle-scenario.md index 977cd44d4f..23855da421 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-processidle-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-processidle-scenario.md @@ -17,7 +17,7 @@ The PwrTest ProcessIdle Scenario forces background maintenance tasks to run (now ## Syntax -``` syntax +``` pwrtest /processidle [/t:n] [/?] ``` @@ -26,11 +26,11 @@ Specifies the maximum time (in minutes) for the scenario to run, after which the **Examples** -``` syntax +``` pwrtest /processidle ``` -``` syntax +``` pwrtest /processidle /t:30 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-requests-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-requests-scenario.md index efb3a0b37f..4279d83878 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-requests-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-requests-scenario.md @@ -21,7 +21,7 @@ You could also use the administrator tool [PowerCfg](http://go.microsoft.com/fwl ## Syntax -``` syntax +``` pwrtest /requests [/t:n] [/?] ``` @@ -30,11 +30,11 @@ Specifies the total time (in minutes) for the scenario to run (the default value **Examples** -``` syntax +``` pwrtest /requests ``` -``` syntax +``` pwrtest /requests /t:60 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-sleep-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-sleep-scenario.md index f51b31928c..ceea518394 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-sleep-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-sleep-scenario.md @@ -19,7 +19,7 @@ PwrTest is capable of directing the platform into one or more sleep states in an ## Syntax -``` syntax +``` pwrtest /sleep [/c:n] [/d:n] [/p:n] [/h:{y|n}] [/s:{1|3|4|all|rnd|hibernate|standby}] [/unattend] [/e:n] [/?] ``` @@ -66,11 +66,11 @@ Specifies the timeout in seconds to wait for the transition end event (120 secon **Examples** -``` syntax +``` pwrtest pwrtest /sleep /c:4 /s:all ``` -``` syntax +``` pwrtest /sleep /c:4 /p:120 /d:150 /s:all ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-syntax.md b/windows-driver-docs-pr/devtest/pwrtest-syntax.md index 16ac99ac43..4dcec54560 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-syntax.md +++ b/windows-driver-docs-pr/devtest/pwrtest-syntax.md @@ -16,7 +16,7 @@ You run PwrTest from a Command Prompt window. You can select and configure [PwrT The syntax for the PwrTest tool is: -``` syntax +``` pwrtest /scenario [/scenario_options] [/common_options] ``` @@ -62,15 +62,15 @@ For example: **pwrtest.exe /sleep /?** **Examples** -``` syntax +``` pwrtest /? ``` -``` syntax +``` pwrtest /requests /? ``` -``` syntax +``` pwrtest /requests /t:60 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest-thermal-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-thermal-scenario.md index 87bd2138f4..6cf034f3a2 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-thermal-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-thermal-scenario.md @@ -14,14 +14,14 @@ ms.technology: windows-devices The PwrTest Thermal Scenario monitors ACPI thermal zone information and statistics. This scenario is only supported on systems that report thermal zones and temperature changes. -**Note**This scenario only works on systems that report thermal data to the operating system. +**Note** This scenario only works on systems that report thermal data to the operating system. - + ## Syntax -``` syntax +``` pwrtest /thermal [/t:n] [/?] ``` @@ -33,15 +33,15 @@ Specifies the temperature scale Kelvin (**k**), Celsius (**c**), Fahrenheit (**f **Examples** -``` syntax +``` pwrtest /thermal ``` -``` syntax +``` pwrtest /thermal /t:30 ``` -``` syntax +``` pwrtest /thermal /t:30 /temp:f ``` @@ -176,7 +176,7 @@ The following table describes the XML elements that appear in the log file. - + ## Related topics @@ -185,9 +185,9 @@ The following table describes the XML elements that appear in the log file. [PowerCfg](http://go.microsoft.com/fwlink/p/?linkid=294568) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20PwrTest%20Thermal%20Scenario%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/pwrtest-timer-scenario.md b/windows-driver-docs-pr/devtest/pwrtest-timer-scenario.md index 264c4113ca..2c5634637c 100644 --- a/windows-driver-docs-pr/devtest/pwrtest-timer-scenario.md +++ b/windows-driver-docs-pr/devtest/pwrtest-timer-scenario.md @@ -17,7 +17,7 @@ The PwrTest Timer Scenario logs system timer resolution changes as they happen. ## Syntax -``` syntax +``` pwrtest /timer /? [/t:n] [/?] ``` @@ -26,11 +26,11 @@ Specifies the total time (in minutes) for the scenario to run (the default value **Examples** -``` syntax +``` pwrtest /timer ``` -``` syntax +``` pwrtest /timer /t:5 ``` diff --git a/windows-driver-docs-pr/devtest/pwrtest.md b/windows-driver-docs-pr/devtest/pwrtest.md index aad5ceeb61..bdb6703fcf 100644 --- a/windows-driver-docs-pr/devtest/pwrtest.md +++ b/windows-driver-docs-pr/devtest/pwrtest.md @@ -53,11 +53,11 @@ PwrTest functionality is separated into scenarios. For information about these s **Examples** - ``` syntax + ``` pwrtest /? ``` - ``` syntax + ``` pwrtest /battery /c:4 /i:1000 ``` diff --git a/windows-driver-docs-pr/devtest/reg2inf.md b/windows-driver-docs-pr/devtest/reg2inf.md new file mode 100644 index 0000000000..d16f2f396c --- /dev/null +++ b/windows-driver-docs-pr/devtest/reg2inf.md @@ -0,0 +1,35 @@ +--- +title: Reg2inf +description: Reg2inf is a tool that converts registry keys to make a driver package universal. +ms.assetid: e43a137e-c08a-4715-84f7-32cda67399e3 +ms.author: windowsdriverdev +ms.date: 08/23/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reg2inf + +The Driver Package INF Registry Conversion Tool (`reg2inf.exe`) tool converts a registry key and its values or a COM .dll implementing a [**DllRegisterServer**](https://msdn.microsoft.com/library/windows/desktop/ms682162) routine into a set of [INF AddReg directives](../install/inf-addreg-directive.md) for inclusion into a driver package INF file. This tool is particularly useful for converting existing [INF RegisterDlls directives](../install/inf-registerdlls-directive.md) into INF AddReg directives in order to make an INF file universal. For more info about universal INF files, see [Using a Universal INF File](../install/using-a-universal-inf-file.md). + +The tool currently ships as part of the WDK 10 installation in current Windows 10 Insider Preview builds. You can find it in the \tools subdirectory of your WDK 10 installation, for example `c:\Program Files(x86)\Windows Kits\10\tools\`. + +While Reg2inf attempts to generate a COM registration, it may not capture the full registry state that the COM registration provides. As always, you should inspect the output of the tool for completeness and correctness, and test the results. + +## Running Reg2inf from the command line + +This section lists the command line options for Reg2inf. + +``` +USAGE: reg2inf.exe [/key | /dll ] [/targetkey ] + +/key + Process a specific registry key, e.g.: reg2inf /key HKEY_LOCAL_MACHINE\SOFTWARE\Fabrikam +/dll + Process a COM DLL module that implements DllRegisterServer entrypoint, typically called by regsvr32 or legacy INF RegisterDlls directive in order to register COM class under HKEY_CLASSES_ROOT, e.g.: reg2inf /dll %SystemRoot%\System32\fabkobj.dll +/targetkey + Remap target registry key to be under a different base key path, e.g.: reg2inf /key HKLM\SYSTEM\Temp /targetkey HKR\Parameters +``` + +**Note** Reg2inf requires that the full path length must not exceed 259 characters. diff --git a/windows-driver-docs-pr/devtest/run-a--staticdv--clean--command-in---drivername-.md b/windows-driver-docs-pr/devtest/run-a--staticdv--clean--command-in---drivername-.md index 9e290b4516..585484634a 100644 --- a/windows-driver-docs-pr/devtest/run-a--staticdv--clean--command-in---drivername-.md +++ b/windows-driver-docs-pr/devtest/run-a--staticdv--clean--command-in---drivername-.md @@ -1,6 +1,6 @@ --- title: Run a "staticdv /clean" command in drivername -description: Run a \ 0034;staticdv /clean \ 0034; command in drivername +description: Run a "staticdv /clean" command in drivername ms.assetid: 179ade54-625f-427e-b680-f9814c41808f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/run-the-tests.md b/windows-driver-docs-pr/devtest/run-the-tests.md new file mode 100644 index 0000000000..23de1a886d --- /dev/null +++ b/windows-driver-docs-pr/devtest/run-the-tests.md @@ -0,0 +1,142 @@ +#Run the Tests +##Description of the Tests and Configuration File +The data-driven SysFund tests live at \Program Files\Windows Kits\10\Testing\Tests\Additional Tests\x64\DevFund\DataDriven. The data-driven test suite consists of the following files: + - Two test DLL’s which use the XML configuration file WDTFTest.xml: + * Sysfund_PNP_DisableEnable_With_IO_BeforeAndAfter_DataDriven.dll + * Sysfund_Sleep_With_IO_BeforeAndAfter_DataDriven.dll + - Two utility DLL’s which use the XML configuration file WDTFTest.xml: + * Utility_DeviceStatusCheck_DataDriven.dll + * Utility_EnableDisableDriverVerifier_DataDriven.dll + - The XML configuration file: + * WDTFTest.xml + +**System - PNP (disable and enable) with IO Before and After (Reliability)** + - Binary: Sysfund_PNP_DisableEnable_With_IO_BeforeAndAfter_DataDriven.dll + - [Documentation](https://msdn.microsoft.com/de-de/library/windows/hardware/dn941373(v=vs.85).aspx) + +**System - Sleep with IO Before and After (Reliability SysFund)** + - Binary: Sysfund_Sleep_With_IO_BeforeAndAfter_DataDriven.dll + - [Documentation](https://msdn.microsoft.com/en-us/library/windows/hardware/dn940448(v=vs.85).aspx) + +**Device Status Check** + - Binary: Utility_DeviceStatusCheck_DataDriven.dll + - This utility DLL verifies that the Problem Codes of the target devices are 0 (working properly). It is generally used before running the SysFund tests to verify the target devices are working properly. + +**Enable/Disable Driver Verifier** + - Binary: Utility_EnableDisableDriverVerifier_DataDriven.dll + - This utility enables or disables Driver Verifier for the drivers associated with the target devices. + +**Data-driven Test Configuration File** + - File: WDTFTest.xml + - This file contains all of the configuration information for the data-driven SysFund tests and associated utilities. + +##Configure the Tests + +The data-driven test configuration file (WDTFTest.xml) contains several elements that define the parameters passed to the tests and utilities. All of the data-driven tests and utilities share the same configuration file (WDTFTest.xml). By default, the configuration file will configure the tests and utilities to target all devices on the system, but this can easily be customized to suit the requirements of the test pass. + +As shown below, the configuration file can be customized so the tests and utilities will target any set of devices on the system, from one device or driver to all devices and drivers. + +The tests and utilities will only use the elements they need and will ignore all other elements. +###Description of WDTFTest.xml Parameters and Usage +####Configuring the SDEL Query +The [SDEL language] (https://msdn.microsoft.com/en-us/library/windows/hardware/ff538361%28v=vs.85%29.aspx) is used to create the query which returns the devices targeted by the tests and utilities. The following SDEL-related parameters are ‘AND’ed together to create the complete query: + +**SDEL**: the value IsDevice specifies the complete set of devices on the system. Typically, this parameter is not edited unless you only want to test a specific driver or device. The next SDEL-related parameters will create a subset of devices from this superset by specifying drivers or devices which should be excluded from testing, so this parameter can be left unchanged. +``` + IsDevice +``` + +**SdelExcludeVMDevnode**: excludes device nodes that are critical to VM operation and cannot be disabled. This parameter should be left unchanged as it will have no effect if the system is not a virtual machine. +``` + (DisplayName!='Microsoft Hyper-V Virtual Machine Bus') +``` + +**SdelExcludeDrivers**: this is the recommended place to use SDEL to exclude drivers and/or devices. For example, this could be used to exclude drivers that have known bugs, or to narrow the scope of the test. Running with the default of "(DriverBinaryNames!='')" will target all drivers of all devices on the system (except the “Microsoft Hyper-V Virtual Machine Bus” device node as noted above). +``` + (DriverBinaryNames!='') +``` + +####General Test Configuration Parameters +**TestCycles**: specifies for how many iterations the test should run. +``` + 1 +``` + +**IOPeriod** specifies for how many minutes I/O should run. +``` + 1 +``` + +**ResumeDelay**: specifies for how many seconds to wait before sending I/O after resuming from sleep. +``` + 10 +``` + +**Wpa2PskAesSsid**: specifies the name of the test WiFi access point. +``` + WiFiRouterName +``` + +**Wpa2PskPassword**: specifies the password of the test WiFi access point. +``` + WiFiRouterPassword +``` + +####The following parameters apply to utility_enabledisabledriververifier_datadriven.dll only: + +**DriverVerifierLevel**: the default value of 0x209BB is equal to "standard flags" for [Driver Verifier] (https://msdn.microsoft.com/en-us/windows/hardware/drivers/devtest/driver-verifier). +``` + 0x209BB +``` + +**AddOnly**: specifies that the resulting SDEL query results should add drivers to Driver Verifier without removing any. This is useful if Driver Verifier is already enabled on a set of drivers which should be appended rather than replaced. +``` + false +``` + +**NoReboot**: specifies that the machine should not reboot automatically to enable Driver Verifier settings. If the NoReboot parameter is set to true, the augmented Driver Verifier settings will not take effect until the machine is manually rebooted. +``` + false +``` + +###Enable Driver Verifier +To turn on Driver Verifier, run the following command: + te.exe utility_enabledisabledriververifier_datadriven.dll /name:Utility_DriverVerifier#0::EnableDriverVerifier /rebootstatefile=state.xml +In certain instances, the machine may not reboot. This is a known technical limitation of the test framework. If the machine does not begin rebooting within 30 seconds after changing Driver Verifier settings with this utility, you must manually reboot the machine for the updated Driver Verifier settings to take effect. + +After the reboot, open a command prompt and run “verifier /querysettings” to ensure Driver Verifier has been enabled. + +###Verify Devices are Working +The data-driven SysFund tests expect any devices targeted by the tests to have a Problem Code of 0 (working properly). To ensure all devices being targeted are working properly, use the DeviceStatusCheck utility: + te.exe Utility_DeviceStatusCheck_DataDriven.dll +This utility will use the SDEL queries defined in WDTFTest.xml to find the set of devices under test and verify they all have **Problem Code 0**. A “Passed” result means that the set of devices queried are all working properly. Review “TestTextLog.log” to investigate failures. For an explanation of Device Manager problem codes, see https://docs.microsoft.com/en-us/windows-hardware/drivers/install/device-manager-error-messages + +###Launch a Test +Launch either of the data-driven SysFund tests via the following commands: + te.exe Sysfund_PNP_DisableEnable_With_IO_BeforeAndAfter_DataDriven.dll + te.exe Sysfund_Sleep_With_IO_BeforeAndAfter_DataDriven.dll + +###Refine the Configuration File +It is recommended that you back up the original copy of WDTFTest.xml before making any changes. + +The test configuration file (WDTFTest.xml) can be refined based on the results of running the data-driven SysFund tests. For example, if a data-driven SysFund test is initially run targeting all devices on the system, and one particular device or driver fails the test, the test configuration file can be updated to filter-out testing of that device while the bug is investigated. This allows testing to continue in parallel while bugs are investigated. + +Filtering-out a specific device requires editing the **SdelExcludeDrivers** element in WDTFTest.xml. To filter-out mydriver.sys because a bug has been discovered, do the following: +``` + (DriverBinaryNames!=’mydriver.sys’) +``` + +Likewise, to filter-out a device based on the Device Instance Path, do the following +``` + (DeviceId!=’my\device\id’) +``` + +Complex SDEL queries can be created to filter-out multiple devices: +``` + (DriverBinaryNames!=’mydriver1.sys’ AND DriverBinaryNames!=’mydriver2.sys’) +``` + +After the bugs in mydriver1.sys and mydriver2.sys are fixed, the **SdelExcludeDrivers** element in WDTFTest.xml can be reset to the default value to include these drivers and associated devices as targets: +``` + (DriverBinaryNames!='') +``` diff --git a/windows-driver-docs-pr/devtest/running-infverif-from-the-command-line.md b/windows-driver-docs-pr/devtest/running-infverif-from-the-command-line.md index c25619dea5..f99bd247fe 100644 --- a/windows-driver-docs-pr/devtest/running-infverif-from-the-command-line.md +++ b/windows-driver-docs-pr/devtest/running-infverif-from-the-command-line.md @@ -16,7 +16,7 @@ This topic lists the options that are available when you run InfVerif.exe from t > [!NOTE] > InfVerif requires that each combined path and file name must be less than 260 characters. -``` syntax +``` USAGE: InfVerif.exe [/v] [/u | /universal] [/info] [/stampinf] [/l ] [/osver TargetOSVersion>] [/product ] /v diff --git a/windows-driver-docs-pr/devtest/signtool.md b/windows-driver-docs-pr/devtest/signtool.md index 01d7e95fba..038673acf3 100644 --- a/windows-driver-docs-pr/devtest/signtool.md +++ b/windows-driver-docs-pr/devtest/signtool.md @@ -22,7 +22,7 @@ ms.technology: windows-devices SignTool (Signtool.exe) is a command-line [CryptoAPI](http://go.microsoft.com/fwlink/p/?linkid=136391) tool that digitally-signs files, verifies signatures in files, and time stamps files. -``` syntax +``` SignTool [Operation] [Options] [FileName ...] ``` diff --git a/windows-driver-docs-pr/devtest/stack-based-failure-injection.md b/windows-driver-docs-pr/devtest/stack-based-failure-injection.md index f775b51085..98baeda724 100644 --- a/windows-driver-docs-pr/devtest/stack-based-failure-injection.md +++ b/windows-driver-docs-pr/devtest/stack-based-failure-injection.md @@ -66,13 +66,13 @@ Most of the issues found with Stack Based Failure Injection result in bug checks - From the debugger command prompt, type the following command: **!***<path>\\***kmautofaildbg.dll.autofail**. For example, assuming debugger extensions are installed at c:\\dbgext and that kmautofail.pdb is in the symbol path, you would enter the following command: - ``` syntax + ``` !c:\dbgext\kmautofaildbg.dll.autofail ``` This will dump information to your debugger showing the call stacks from the most recent failures injected. Each entry looks something like the following, taken from a real test run. In the following example, Stack Based Failure Injection is enabled on Mydriver.sys -``` syntax +``` Sequence: 2, Test Number: 0, Process ID: 0, Thread ID: 0 IRQ Level: 2, HASH: 0xea98a56083aae93c 0xfffff8800129ed83 kmautofail!ShimHookExAllocatePoolWithTag+0x37 @@ -99,7 +99,7 @@ Note that if a driver has returned failure from its [*DriverEntry*](https://msdn This next entry shows a call to the driver by means of an IOCTL from user mode. Note the process ID and the IRQ level. Since Mydriver.sys is an NDIS filter driver, the IOCTL came through Ndis.sys. Note that nt!NtDeviceIoControlFile is on the stack. Any test that you run on your driver that uses IOCTLs will go through this function. -``` syntax +``` Sequence: 5, Test Number: 0, Process ID: 2052, Thread ID: 4588 IRQ Level: 0, HASH: 0xecd4650e9c25ee4 0xfffff8800129ed83 kmautofail!ShimHookExAllocatePoolWithTag+0x37 diff --git a/windows-driver-docs-pr/devtest/stampinf-command-options.md b/windows-driver-docs-pr/devtest/stampinf-command-options.md index 26afebc840..476fc546b5 100644 --- a/windows-driver-docs-pr/devtest/stampinf-command-options.md +++ b/windows-driver-docs-pr/devtest/stampinf-command-options.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Stampinf is a command-line tool that updates common INF file directives. -``` syntax +``` Stampinf -f filename [-s section] [-d [date | *]] diff --git a/windows-driver-docs-pr/devtest/stampinf-task.md b/windows-driver-docs-pr/devtest/stampinf-task.md index 01932a38d8..2a739eb144 100644 --- a/windows-driver-docs-pr/devtest/stampinf-task.md +++ b/windows-driver-docs-pr/devtest/stampinf-task.md @@ -33,7 +33,7 @@ The following example shows how the edit metadata in the .vcxproj file. The following example shows the command-line invocation: -``` syntax +``` stampinf.exe –a "x86" a.inf stampinf.exe b.inf ``` diff --git a/windows-driver-docs-pr/devtest/sys-error--slam-bp--permission-denied---exception.md b/windows-driver-docs-pr/devtest/sys-error--slam-bp--permission-denied---exception.md index 6622783365..809b803af8 100644 --- a/windows-driver-docs-pr/devtest/sys-error--slam-bp--permission-denied---exception.md +++ b/windows-driver-docs-pr/devtest/sys-error--slam-bp--permission-denied---exception.md @@ -1,6 +1,6 @@ --- -title: Sys\_error("slam.bp Permission denied") Exception -description: Sys\_error( \ 0034;slam.bp Permission denied \ 0034;) Exception +title: Sys_error("slam.bp Permission denied") Exception +description: Sys_error("slam.bp Permission denied") Exception ms.assetid: d7b2da9c-792f-4cdc-9945-2877f48f775f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/systematic-low-resource-simulation.md b/windows-driver-docs-pr/devtest/systematic-low-resource-simulation.md index 609e60afce..eb97afcadc 100644 --- a/windows-driver-docs-pr/devtest/systematic-low-resource-simulation.md +++ b/windows-driver-docs-pr/devtest/systematic-low-resource-simulation.md @@ -125,7 +125,7 @@ Most of the issues found with Systematic low resources simulation result in bug - From the debugger command prompt, type the following command: - ``` syntax + ``` !verifier 0x800 ``` diff --git a/windows-driver-docs-pr/devtest/the-process-cannot-access-the-file---path---because-it-is-being-used-b.md b/windows-driver-docs-pr/devtest/the-process-cannot-access-the-file---path---because-it-is-being-used-b.md index 4741c01b7d..43b36418bd 100644 --- a/windows-driver-docs-pr/devtest/the-process-cannot-access-the-file---path---because-it-is-being-used-b.md +++ b/windows-driver-docs-pr/devtest/the-process-cannot-access-the-file---path---because-it-is-being-used-b.md @@ -1,6 +1,6 @@ --- title: Process cannot access file Path because it is being used by another process -description: The process cannot access the file \ 0034; Path \ 0034; because it is being used by another process +description: The process cannot access the file path because it is being used by another process. ms.assetid: 3fd89733-e520-4736-a882-b16e0ecfef95 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/tracefmt-commands.md b/windows-driver-docs-pr/devtest/tracefmt-commands.md index 64aa3b6e67..23792e64d4 100644 --- a/windows-driver-docs-pr/devtest/tracefmt-commands.md +++ b/windows-driver-docs-pr/devtest/tracefmt-commands.md @@ -26,7 +26,7 @@ To display the trace messages in readable form, Tracefmt must apply the formatti To provide a TMF file or a path to a directory of TMF files: -``` syntax +``` tracefmt [EtlFile | -rt SessionName][-tmf TMFFile | -p TMFPath ] [Options] @@ -34,7 +34,7 @@ To provide a TMF file or a path to a directory of TMF files: To create a TMF file: -``` syntax +``` tracefmt [EtlFile | -rt SessionName]-i ImageFiles [-r SymbolPath ] [-p TmfPath ] [Options] @@ -42,7 +42,7 @@ To create a TMF file: To display the syntax at the command line. -``` syntax +``` tracefmt -h | /? diff --git a/windows-driver-docs-pr/devtest/tracelog-command-syntax.md b/windows-driver-docs-pr/devtest/tracelog-command-syntax.md index 6e7ed1bfdd..91bd0b4475 100644 --- a/windows-driver-docs-pr/devtest/tracelog-command-syntax.md +++ b/windows-driver-docs-pr/devtest/tracelog-command-syntax.md @@ -26,7 +26,7 @@ Tracelog has commands (or actions) that start, stop, and control a [trace sessio   -``` syntax +``` tracelog [actions] [options] | [-h | -help | -?] diff --git a/windows-driver-docs-pr/devtest/tracelogging-for-kernel-mode-drivers-and-components.md b/windows-driver-docs-pr/devtest/tracelogging-for-kernel-mode-drivers-and-components.md index ced0545a8d..8ced65dbe2 100644 --- a/windows-driver-docs-pr/devtest/tracelogging-for-kernel-mode-drivers-and-components.md +++ b/windows-driver-docs-pr/devtest/tracelogging-for-kernel-mode-drivers-and-components.md @@ -40,13 +40,13 @@ To use the TraceLogging API, include the TraceLogging header file TraceLoggingPr 1. Add the [**TRACELOGGING\_DECLARE\_PROVIDER**](https://msdn.microsoft.com/library/windows/desktop/dn904623) macro to declare the provider handle variable. The macro has the syntax: - ``` syntax + ``` TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName) ``` The following example TraceLogging statement declares the variable named *g\_hProvider*. - ``` syntax + ``` TRACELOGGING_DECLARE_PROVIDER(g_hProvider); ``` @@ -58,13 +58,13 @@ To use the TraceLogging API, include the TraceLogging header file TraceLoggingPr 2. Add the [**TRACELOGGING\_DEFINE\_PROVIDER**](https://msdn.microsoft.com/library/windows/desktop/dn904624) macro, and specify a name for the trace provider and the trace provider handle. The handle is the variable you declared in step 1. The syntax of the macro is: - ``` syntax + ``` TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option]) ``` For example, the following statement defines a provider called MyTraceLoggingProviderKM and assigns it to the handle g\_hProvider. The providerId parameter is the ETW provider GUID. - ``` syntax + ``` TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM", (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71)); ``` @@ -106,7 +106,7 @@ TraceLogging provides macros for logging events. The basic macro is [**TraceLoggingWrite**](https://msdn.microsoft.com/library/windows/desktop/dn904617). This macro has the following syntax: -``` syntax +``` TraceLoggingWrite(g_hProvider, "EventName", args...) ``` diff --git a/windows-driver-docs-pr/devtest/tracepdb-commands.md b/windows-driver-docs-pr/devtest/tracepdb-commands.md index 982ab29bc1..24a92c9296 100644 --- a/windows-driver-docs-pr/devtest/tracepdb-commands.md +++ b/windows-driver-docs-pr/devtest/tracepdb-commands.md @@ -24,7 +24,7 @@ To use Tracepdb, type the commands in a Command Prompt window. The following syn Use the following parameters to specify the location of the PDB files. -``` syntax +``` tracepdb [-f PDBFiles] [-s] [-p TMFDirectory] [-v] [-c] @@ -32,7 +32,7 @@ Use the following parameters to specify the location of the PDB files. Use the following parameters to specify an image file for the [trace provider](trace-provider.md). -``` syntax +``` tracepdb -i ImageFiles [-r SymbolPaths] [-p TMFDiretory] [-v] diff --git a/windows-driver-docs-pr/devtest/traceview--parsepdb.md b/windows-driver-docs-pr/devtest/traceview--parsepdb.md index 670de6a13c..50282c078e 100644 --- a/windows-driver-docs-pr/devtest/traceview--parsepdb.md +++ b/windows-driver-docs-pr/devtest/traceview--parsepdb.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Use a **TraceView -parsepdb** command to create [trace message format files](trace-message-format-file.md) from data in a [PDB symbol file](pdb-symbol-files.md). -``` syntax +``` traceview -parsepdb PDBfile [-p TMFPath] diff --git a/windows-driver-docs-pr/devtest/traceview--process.md b/windows-driver-docs-pr/devtest/traceview--process.md index e58d89ddc7..15ad93e471 100644 --- a/windows-driver-docs-pr/devtest/traceview--process.md +++ b/windows-driver-docs-pr/devtest/traceview--process.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Use a **TraceView -process** command to format the binary trace messages in a [trace log](trace-log.md) or from a real-time trace seesion. The **TraceView -process** command creates a text file of a trace messages and a summary file that describes the input and output files. -``` syntax +``` traceview -process [EtlFile | -rt SessionName][Parameters] diff --git a/windows-driver-docs-pr/devtest/traceview-control-commands.md b/windows-driver-docs-pr/devtest/traceview-control-commands.md index 2bcefb51cf..f5f37e6152 100644 --- a/windows-driver-docs-pr/devtest/traceview-control-commands.md +++ b/windows-driver-docs-pr/devtest/traceview-control-commands.md @@ -22,13 +22,13 @@ ms.technology: windows-devices Use a Traceview control command to manage trace sessions, including starting and stopping the session, enabling and disabling providers, updating the properties of the trace session, and flushing trace buffers. -``` syntax +``` traceview {-start | -stop | -update | -enable | -disable | -flush | -q} SessionName [Parameters] ``` -``` syntax +``` traceview {-enumguid | -l | -h | -x} @@ -124,7 +124,7 @@ TraceView passes the values of the following subparameters to the specified prov - + **-b** *BufferSize* Specifies the size, in KB, of each buffer allocated for the trace session. Use only with **-start**. @@ -212,9 +212,9 @@ You can use the TraceView -start command to start a [Global Logger trace session traceview -start GlobalLogger [parameters] ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20TraceView%20Control%20Commands%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/tracewpp-task.md b/windows-driver-docs-pr/devtest/tracewpp-task.md index 827ab65422..8ffe16f082 100644 --- a/windows-driver-docs-pr/devtest/tracewpp-task.md +++ b/windows-driver-docs-pr/devtest/tracewpp-task.md @@ -18,9 +18,9 @@ WppEnabled is a new metadata for the ClCompile item that enables tracing for sou The WppEnabled metadata was added to the ClCompile Item because the WPP task runs on the same type of input files as the CL task, in this case .c, .cpp, and .h files. -**Note**You access the Item metadata for tracewpp by using the ClCompile item in project files. MSBuild uses the TraceWpp item internally inside the target to pass it to the task. +**Note** You access the Item metadata for tracewpp by using the ClCompile item in project files. MSBuild uses the TraceWpp item internally inside the target to pass it to the task. - + The following example shows how to edit the metadata in the .vcxproj file. @@ -43,9 +43,9 @@ The following example shows how to edit the metadata in the .vcxproj file. The command-line invocation would be: -``` syntax -tracewpp.exe km /Ic:\test\b.c -tracewpp.exe dll test2.c +``` +tracewpp.exe km /Ic:\test\b.c +tracewpp.exe dll test2.c ``` The example above shows that MSBuild invokes **tracewpp.exe** only on b.c and test2.c because the **WppEnabled** metadata is set to **TRUE** for these inputs. Also note that the metadata for these two inputs are different. Therefore, the switches will also be different for these inputs. In other words, you can call each input with its own set of metadata. @@ -211,7 +211,7 @@ The example above shows that MSBuild invokes **tracewpp.exe** only on b.c and te - + ## Related topics @@ -220,9 +220,9 @@ The example above shows that MSBuild invokes **tracewpp.exe** only on b.c and te [WPP Software Tracing](wpp-software-tracing.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20TraceWPP%20task%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/umdf-settings-test-use-only-tab.md b/windows-driver-docs-pr/devtest/umdf-settings-test-use-only-tab.md index a186135384..0838e54ca7 100644 --- a/windows-driver-docs-pr/devtest/umdf-settings-test-use-only-tab.md +++ b/windows-driver-docs-pr/devtest/umdf-settings-test-use-only-tab.md @@ -22,14 +22,14 @@ By default, the [UMDF In-Flight Recorder (IFR)](https://msdn.microsoft.com/libra Also, sometimes analysis tools such as Driver Verifier can decrease system performance enough in CPU-intensive tests that the default UMDF timeout triggers even though the driver did nothing wrong. In this case, increasing the timeout value may reduce this type of accidental timeout. -**Warning** +**Warning** Using these options actually reduces the likelihood of catching or diagnosing a UMDF driver failure, so you should use them only when needed. They are more likely to be of use for testing an overall system. - + - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20UMDF%20Settings%20%28Test%20Use%20Only%29%20Tab%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/using---sdv-save-adapter-context-to-track-adapter-context-fields.md b/windows-driver-docs-pr/devtest/using---sdv-save-adapter-context-to-track-adapter-context-fields.md index 74d71c06f0..c1dc754e90 100644 --- a/windows-driver-docs-pr/devtest/using---sdv-save-adapter-context-to-track-adapter-context-fields.md +++ b/windows-driver-docs-pr/devtest/using---sdv-save-adapter-context-to-track-adapter-context-fields.md @@ -1,6 +1,6 @@ --- -title: Using \_\_sdv\_save\_adapter\_context to Track Adapter Context Fields -description: Using \_\_sdv\_save\_adapter\_context to Track Adapter Context Fields +title: Using __sdv_save_adapter_context to Track Adapter Context Fields +description: Using __sdv_save_adapter_context to Track Adapter Context Fields ms.assetid: b43d7ef5-0464-4e07-a5ec-9d7d8a55479e ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/using---sdv-save-request-and---sdv-retrieve-request-for-deferred-proce.md b/windows-driver-docs-pr/devtest/using---sdv-save-request-and---sdv-retrieve-request-for-deferred-proce.md index 5020411dc1..1b8e1bc476 100644 --- a/windows-driver-docs-pr/devtest/using---sdv-save-request-and---sdv-retrieve-request-for-deferred-proce.md +++ b/windows-driver-docs-pr/devtest/using---sdv-save-request-and---sdv-retrieve-request-for-deferred-proce.md @@ -1,6 +1,6 @@ --- title: Use __sdv_save_request and __sdv_retrieve_request for Deferred Procedure Calls -description: Using \_\_sdv\_save\_request and \_\_sdv\_retrieve\_request for Deferred Procedure Calls +description: Using __sdv_save_request and __sdv_retrieve_request for Deferred Procedure Calls ms.assetid: 14d3a022-3e74-4526-9bf5-fee1ce36ac9e keywords: - __sdv_save_request diff --git a/windows-driver-docs-pr/devtest/using-the--analysis-assume-function-to-suppress-false-defects.md b/windows-driver-docs-pr/devtest/using-the--analysis-assume-function-to-suppress-false-defects.md index ffe9cf3754..189efd5bcc 100644 --- a/windows-driver-docs-pr/devtest/using-the--analysis-assume-function-to-suppress-false-defects.md +++ b/windows-driver-docs-pr/devtest/using-the--analysis-assume-function-to-suppress-false-defects.md @@ -1,6 +1,6 @@ --- -title: Using the \_analysis\_assume Function to Suppress False Defects -description: Using the \_analysis\_assume Function to Suppress False Defects +title: Using the _analysis_assume Function to Suppress False Defects +description: Using the _analysis_assume Function to Suppress False Defects ms.assetid: eb71a664-ada5-44e3-b75d-b1a7348b115f ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/using-volatile-settings.md b/windows-driver-docs-pr/devtest/using-volatile-settings.md index f2cb7ecbf4..a269ed39dd 100644 --- a/windows-driver-docs-pr/devtest/using-volatile-settings.md +++ b/windows-driver-docs-pr/devtest/using-volatile-settings.md @@ -69,7 +69,7 @@ To add or delete volatile options, use the **/volatile /flags** parameter. - To start or stop the verification of a driver without rebooting: - ``` syntax + ``` verifier /volatile /adddriver DriverName.sys verifier /volatile /removedriver DriverName.sys ``` @@ -78,13 +78,13 @@ To add or delete volatile options, use the **/volatile /flags** parameter. - To activate or deactivate options without rebooting: - ``` syntax + ``` verifier /volatile /flags Options ``` You can use this command syntax with any Driver Verifier option, except for [SCSI Verification](scsi-verification.md) and [Disk Integrity Checking](disk-integrity-checking.md). For example, - ``` syntax + ``` verifier /volatile /flags 0x20 ``` @@ -94,7 +94,7 @@ To add or delete volatile options, use the **/volatile /flags** parameter. You cannot stop the verification of a driver that is currently loaded without rebooting. However, you can use the following command syntax to deactivate all of the Driver Verifier options without rebooting, thereby minimizing the overhead until the next reboot. - ``` syntax + ``` verifier /volatile /flags 0 ``` diff --git a/windows-driver-docs-pr/devtest/verifier-command-line.md b/windows-driver-docs-pr/devtest/verifier-command-line.md index 39c43c5e11..dd92b72db7 100644 --- a/windows-driver-docs-pr/devtest/verifier-command-line.md +++ b/windows-driver-docs-pr/devtest/verifier-command-line.md @@ -32,7 +32,7 @@ verifier /flags 7 /driver beep.sys flpydisk.sys You can use the **/volatile** parameter with some Driver Verifier **/flags** options and with **/standard**. You cannot use **/volatile** with the **/flags** options for [DDI compliance checking](ddi-compliance-checking.md), [Power Framework Delay Fuzzing](concurrency-stress-test.md), [Storport Verification](dv-storport-verification.md), or [SCSI Verification](scsi-verification.md). For details, see [Using Volatile Settings](using-volatile-settings.md). -``` syntax +``` verifier /standard /all verifier /standard /driver NAME [NAME ...] verifier /flags /all @@ -60,7 +60,7 @@ You can use the **/volatile** parameter with some Driver Verifier **/flags** opt You can use the **/volatile** parameter with some Driver Verifier **/flags** options and with **/standard**. You cannot use **/volatile** with the **/flags** options for [DDI compliance checking](ddi-compliance-checking.md), [Power Framework Delay Fuzzing](concurrency-stress-test.md), [Storport Verification](dv-storport-verification.md), or [SCSI Verification](scsi-verification.md). For details, see [Using Volatile Settings](using-volatile-settings.md). -``` syntax +``` verifier /standard /all verifier /standard /driver NAME [NAME ...] verifier /flags /all @@ -84,7 +84,7 @@ You can use the **/volatile** parameter with some Driver Verifier **/flags** opt You can use the **/volatile** parameter with some Driver Verifier **/flags** options and with **/standard**. You cannot use **/volatile** with the /flags options for [DDI compliance checking](ddi-compliance-checking.md), [Power Framework Delay Fuzzing](concurrency-stress-test.md), [Storport Verification](dv-storport-verification.md), [SCSI Verification](scsi-verification.md) or with **/disk**. For details, see [Using Volatile Settings](using-volatile-settings.md). -``` syntax +``` verifier [/volatile] [/standard | /flags Options ] [ /all | /driver DriverList ] verifier /volatile /faults [Probability PoolTags Applications DelayMins] /driver DriverList verifier /volatile {/adddriver | /removedriver} DriverList @@ -99,7 +99,7 @@ verifier /? **Windows Server 2003 Syntax** -``` syntax +``` verifier [/disk] [ /standard | /flags Options ] [ /all | /driver DriverList ] verifier /volatile /flags VolatileOptions verifier /volatile {/adddriver | /removedriver} DriverList @@ -147,6 +147,11 @@ Controls whether the settings for Driver Verifier are enabled after a reboot. To

oneboot

Only enables the Driver Verifier settings for the next time the computer starts. Driver Verifier is disabled for subsequent reboots.

+ +

resetonunusualshutdown

+

(Introduced in Windows 10, build 1709) Driver Verifier will persist until an unusual shutdown occurs. Its abbrevation, 'rous', can be used. +

+ diff --git a/windows-driver-docs-pr/devtest/wdf-verifier-control-application.md b/windows-driver-docs-pr/devtest/wdf-verifier-control-application.md index 3a07d84df6..d75788b3a8 100644 --- a/windows-driver-docs-pr/devtest/wdf-verifier-control-application.md +++ b/windows-driver-docs-pr/devtest/wdf-verifier-control-application.md @@ -23,11 +23,11 @@ ms.technology: windows-devices The Windows Driver Frameworks (WDF) Verifier control application (WdfVerifier.exe) is a tool for debugging Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) drivers. You can use the tool for a quick assessment of drivers on a machine, and to make changes to their debugger settings. -This documentation describes options found in the version of the application that ships as part of Windows Driver Kit (WDK)8.1. +This documentation describes options found in the version of the application that ships as part of Windows Driver Kit (WDK) 8.1. -**Important** To use WDF Verifier, you must have administrative privileges on the computer. +**Important** To use WDF Verifier, you must have administrative privileges on the computer. - + ### What can I do with it? @@ -70,16 +70,16 @@ This documentation describes options found in the version of the application tha

[My Preferences Tab](my-preferences-tab.md)

-

This topic describes WDF Verifier's My Preferences page. On this page, you can set preferences for some of the control panels features.

+

This topic describes WDF Verifier's My Preferences page. On this page, you can set preferences for some of the control panel's features.

- + - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20WDF%20Verifier%20Control%20Application%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/devtest/where-do-i-put-the--include-statement-for-the-trace-message-header-fil.md b/windows-driver-docs-pr/devtest/where-do-i-put-the--include-statement-for-the-trace-message-header-fil.md index a17c17928d..09c1b61273 100644 --- a/windows-driver-docs-pr/devtest/where-do-i-put-the--include-statement-for-the-trace-message-header-fil.md +++ b/windows-driver-docs-pr/devtest/where-do-i-put-the--include-statement-for-the-trace-message-header-fil.md @@ -1,6 +1,6 @@ --- -title: Where do I put the \ include statement for the trace message header file -description: Where do I put the \ include statement for the trace message header file +title: Where do I put the #include statement for the trace message header file +description: Where do I put the #include statement for the trace message header file ms.assetid: 5d8a2bb7-efe1-4cf2-9424-b63d4f17805e ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/devtest/wpp-preprocessor.md b/windows-driver-docs-pr/devtest/wpp-preprocessor.md index cb124eef4e..1ff887fd69 100644 --- a/windows-driver-docs-pr/devtest/wpp-preprocessor.md +++ b/windows-driver-docs-pr/devtest/wpp-preprocessor.md @@ -38,7 +38,7 @@ You can invoke the WPP preprocessor using Visual Studio and the MSBuild environm If you need to provide more than one configuration file, for instance to specify custom data types, reference your file in **Command Line** using the **-scan** option, for example: - ``` syntax + ``` -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h" ``` diff --git a/windows-driver-docs-pr/devtest/xpsanalyzer-command-syntax.md b/windows-driver-docs-pr/devtest/xpsanalyzer-command-syntax.md index 3c7b00203d..a8437183ca 100644 --- a/windows-driver-docs-pr/devtest/xpsanalyzer-command-syntax.md +++ b/windows-driver-docs-pr/devtest/xpsanalyzer-command-syntax.md @@ -22,7 +22,7 @@ ms.technology: windows-devices To run XpsAnalyzer, type a command at the command line using the following syntax and parameters. -``` syntax +``` XpsAnalyzer [/XpsFile:FileName] [/Directory:DirectoryName] [/FlushSql:SqlFormat]] diff --git a/windows-driver-docs-pr/devtest/xpsconverter.md b/windows-driver-docs-pr/devtest/xpsconverter.md index e0669832f8..bf2769c3b8 100644 --- a/windows-driver-docs-pr/devtest/xpsconverter.md +++ b/windows-driver-docs-pr/devtest/xpsconverter.md @@ -30,7 +30,7 @@ XPS Converter (XpsConverter.exe) is a command-line tool for converting XML Paper - + The XpsConverter is not intended to be used in any other capacity than as a stand-alone tool. It is not supported for any other use. It may not be used in part or whole in any application or driver, and de-compiling or modifying the tool is strictly prohibited. Microsoft retains all rights and holds copyright on XpsConverter.exe and all its supporting documentation. @@ -42,7 +42,7 @@ The XpsConverter is not intended to be used in any other capacity than as a stan For example, the following command converts the MSXPS file called text.xps to OpenXPS format. - ``` syntax + ``` XpsConverter /OpenXPS /InputFile=Text.xps /OutputFile=Test.oxps ``` @@ -51,7 +51,7 @@ The XpsConverter is not intended to be used in any other capacity than as a stan ## XpsConverter Command Syntax -``` syntax +``` XpsConverter [/InputFile= /OutputFile= | /InputFolder= /OutputFolder=] @@ -88,10 +88,10 @@ The XpsConverter is not intended to be used in any other capacity than as a stan

/InputFolder=<inputfolder> /OutputFolder=<outputfolder>

Use this option to convert all the files in <inputfolder> and save them to the <outputfolder>. Files in <inputfolder> must have .xps or .oxps file name extensions.

-Note Converting a folder is a recursive operation. The tool converts all files in the specified s<inputfolder> and all subdirectories. +Note Converting a folder is a recursive operation. The tool converts all files in the specified s<inputfolder> and all subdirectories.
- +
@@ -109,7 +109,7 @@ The XpsConverter is not intended to be used in any other capacity than as a stan - + ## Remarks @@ -119,10 +119,10 @@ You can use the **isXPS.exe (isXPS Conformance Tool)** to tests a file's conform ## Examples -``` syntax +``` XpsConverter /OpenXPS /InputFile=Text.xps /OutputFile=Test.oxps XpsConverter /XPS /InputFolder=c:\OpenXPS /OutputFolder=c:\MSXPS -XpsConverter /OpenXPS /InputFile=MyDoc.xps /OutputFile=ConvertedMyDoc.oxps logger:file logfile:MyLog.txt +XpsConverter /OpenXPS /InputFile=MyDoc.xps /OutputFile=ConvertedMyDoc.oxps logger:file logfile:MyLog.txt ``` ## Related topics @@ -130,9 +130,9 @@ XpsConverter /OpenXPS /InputFile=MyDoc.xps /OutputFile=ConvertedMyDoc.oxps **isXPS.exe (isXPS Conformance Tool)** - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[devtest\devtest]:%20XpsConverter%20%20RELEASE:%20%2811/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/-sourcedisknames--section-directives.md b/windows-driver-docs-pr/display/-sourcedisknames--section-directives.md index cf70e970be..22af7a02b3 100644 --- a/windows-driver-docs-pr/display/-sourcedisknames--section-directives.md +++ b/windows-driver-docs-pr/display/-sourcedisknames--section-directives.md @@ -1,6 +1,6 @@ --- -title: '\ SourceDiskNames\ section directives' -description: On WindowsVista and later, in-box INFs use the \ SourceDisksXxx\ directives. +title: '[SourceDiskNames] section directives' +description: On Windows Vista and later, in-box INFs use the [SourceDisksXxx] directives. ms.assetid: 0AC01548-3E53-41ED-9C7E-E33FC2DD14FD ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -12,7 +12,7 @@ ms.technology: windows-devices # \[SourceDiskNames\] section directives -On WindowsVista and later, in-box INFs use the *\[SourceDisksXxx\]* directives. However, the values of these sections were changed from what had previously typically been noted in an independent hardware vendor (IHV) production driver package. +On Windows Vista and later, in-box INFs use the *\[SourceDisksXxx\]* directives. However, the values of these sections were changed from what had previously typically been noted in an independent hardware vendor (IHV) production driver package. ## *\[SourceDisksNames\]* and *\[SourceDisksFiles\]* section directives @@ -44,7 +44,7 @@ IHVVID.dll = 3426 ## *\[SignatureAttributes\]* section directives -On WindowsVista and later, inbox INFs use the *\[SignatureAttributes\]* directives. +On Windows Vista and later, inbox INFs use the *\[SignatureAttributes\]* directives. There is no need to reference the miniport (.sys) file. @@ -59,9 +59,9 @@ IHVUMD2.dll=SignatureAttributes.PETrust PETrust=true ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20[SourceDiskNames]%20section%20directives%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/-string--section-changes-for-localized-strings.md b/windows-driver-docs-pr/display/-string--section-changes-for-localized-strings.md index eb6b460f4a..81289e7a92 100644 --- a/windows-driver-docs-pr/display/-string--section-changes-for-localized-strings.md +++ b/windows-driver-docs-pr/display/-string--section-changes-for-localized-strings.md @@ -1,5 +1,5 @@ --- -title: '\ String\ section changes for localized strings' +title: '[String] section changes for localized strings' description: This INF requirement ensures that pseudo-localized builds work. The requirement is to delineate localizable versus non-localizable strings within the strings section ms.assetid: F0A0C309-9FA3-4941-AF35-15CD63DB25E3 ms.author: windowsdriverdev @@ -41,9 +41,9 @@ REG_MULTI_SZ = 0x00010000 REG_DWORD = 0x00010001 ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20[String]%20section%20changes%20for%20localized%20strings%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/-version--section-directives.md b/windows-driver-docs-pr/display/-version--section-directives.md index 5d0b667222..7b2c27d6ce 100644 --- a/windows-driver-docs-pr/display/-version--section-directives.md +++ b/windows-driver-docs-pr/display/-version--section-directives.md @@ -1,6 +1,6 @@ --- -title: '\ Version\ section directives' -description: This topic describes \ Version\ section directives in the INF. +title: '[Version] section directives' +description: This topic describes [Version] section directives in the INF. ms.assetid: 76AC10DC-AECC-4C35-8BEE-4B2E8B06FEE0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/display/access-to-non-resident-allocation.md b/windows-driver-docs-pr/display/access-to-non-resident-allocation.md index 1bd85187a8..846c1b0295 100644 --- a/windows-driver-docs-pr/display/access-to-non-resident-allocation.md +++ b/windows-driver-docs-pr/display/access-to-non-resident-allocation.md @@ -19,9 +19,9 @@ There are two distinct models of handling such invalid access dependent on wheth - For engines which don’t support GPU virtual addressing and use the allocation and patch location list to patch memory references, an invalid access occurs when the user mode driver submits an allocation list which references an allocation which is not resident on the device (i.e. the user mode driver hasn’t called [*MakeResidentCb*](https://msdn.microsoft.com/library/windows/hardware/dn906357) on that allocation). When this occurs, the graphics kernel will put the faulty context/device in error. - For engines which do support GPU virtual addressing but access a GPU virtual address that is invalid, either because there is no allocation behind the virtual address or there is a valid allocation but it hasn’t been made resident, the GPU is expected to raise an unrecoverable page fault in the form of an interrupt. When the page fault interrupt occurs, the kernel mode driver will need to forward the error to the graphics kernel through a new page fault notification. Upon receiving this notification, the graphics kernel will initiate an engine reset on the faulting engine and put the faulty context/device in error. If the engine reset is unsuccessful, the graphics kernel will promote the error to a full adapter wide timeout detection and recovery (TDR). - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Access%20to%20non-resident%20allocation%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/bdxva-func-variable.md b/windows-driver-docs-pr/display/bdxva-func-variable.md index 6d4e565b80..e71cba5063 100644 --- a/windows-driver-docs-pr/display/bdxva-func-variable.md +++ b/windows-driver-docs-pr/display/bdxva-func-variable.md @@ -1,6 +1,6 @@ --- -title: bDXVA\_Func Variable -description: bDXVA\_Func Variable +title: bDXVA_Func Variable +description: bDXVA_Func Variable ms.assetid: 6db9fa71-7bc2-4eb6-afcb-b16df48f7e8b keywords: - video decoding WDK DirectX VA , formats diff --git a/windows-driver-docs-pr/display/calling-displayconfig-functions-for-a-miracast-target.md b/windows-driver-docs-pr/display/calling-displayconfig-functions-for-a-miracast-target.md index c3909dae4e..0bed1d41fa 100644 --- a/windows-driver-docs-pr/display/calling-displayconfig-functions-for-a-miracast-target.md +++ b/windows-driver-docs-pr/display/calling-displayconfig-functions-for-a-miracast-target.md @@ -20,9 +20,9 @@ To reduce compatibility issues of existing apps being exposed to new Miracast ta - The [**DISPLAYCONFIG\_VIDEO\_SIGNAL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff554007) structure has a VSync frequency divider member, **vSyncFreqDivider**, that’s used similarly to [**D3DKMDT\_VIDEO\_SIGNAL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff546625).**vSyncFreqDivider**. - The [**DisplayConfigGetDeviceInfo**](https://msdn.microsoft.com/library/windows/hardware/ff553903) function provides the base connector type for any target. In the case of a Miracast target, this function always returns a value of **DISPLAYCONFIG\_OUTPUT\_TECHNOLOGY\_MIRACAST** in the [**DISPLAYCONFIG\_VIDEO\_OUTPUT\_TECHNOLOGY**](https://msdn.microsoft.com/library/windows/hardware/ff554003) enumeration. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Calling%20DisplayConfig%20functions%20for%20a%20Miracast%20target%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/container-id-support-for-displays-.md b/windows-driver-docs-pr/display/container-id-support-for-displays-.md index fd11a5e6f2..41ca5efe83 100644 --- a/windows-driver-docs-pr/display/container-id-support-for-displays-.md +++ b/windows-driver-docs-pr/display/container-id-support-for-displays-.md @@ -1,6 +1,6 @@ --- title: Container ID support for displays -description: This topic describes Container ID support for displays \ 8212;visual representation of devices that are embedded within a display or monitor device. +description: Describes Container ID support for displays--visual representation of devices that are embedded within a display or monitor device. ms.assetid: 3149C156-34F4-4C55-AE77-1CC40C2B35BC ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/display/conversion-from-bgr8888-to-xr-bias.md b/windows-driver-docs-pr/display/conversion-from-bgr8888-to-xr-bias.md index 7243955fc9..8544aad2fa 100644 --- a/windows-driver-docs-pr/display/conversion-from-bgr8888-to-xr-bias.md +++ b/windows-driver-docs-pr/display/conversion-from-bgr8888-to-xr-bias.md @@ -1,6 +1,6 @@ --- -title: Conversion from BGR8888 to XR\_BIAS -description: Conversion from BGR8888 to XR\_BIAS +title: Conversion from BGR8888 to XR_BIAS +description: Conversion from BGR8888 to XR_BIAS ms.assetid: 53145cfe-d344-4242-b124-ddb507d876ad keywords: - Direct3D version 10.1 WDK Windows 7 display , converting BGR8888 to XR_BIAS diff --git a/windows-driver-docs-pr/display/direct3d-version.md b/windows-driver-docs-pr/display/direct3d-version.md index 08f2fe3d40..7286d40694 100644 --- a/windows-driver-docs-pr/display/direct3d-version.md +++ b/windows-driver-docs-pr/display/direct3d-version.md @@ -1,6 +1,6 @@ --- -title: DIRECT3D\_VERSION -description: DIRECT3D\_VERSION +title: DIRECT3D_VERSION +description: DIRECT3D_VERSION ms.assetid: 09032f06-d31f-4d9f-80bd-e6b9b8d5cbaa keywords: - DirectX 8.0 release notes WDK Windows 2000 display , header files diff --git a/windows-driver-docs-pr/display/driver-residency-in-wddm-2-0.md b/windows-driver-docs-pr/display/driver-residency-in-wddm-2-0.md index c2a2a4e0ff..2b41af8377 100644 --- a/windows-driver-docs-pr/display/driver-residency-in-wddm-2-0.md +++ b/windows-driver-docs-pr/display/driver-residency-in-wddm-2-0.md @@ -46,8 +46,8 @@ This section provides details about the driver residency changes for Windows Dis

Graphics processing unit (GPU) access to allocations which are not resident is illegal and will result in a device removed for the application that generated the error.

There are two distinct models of handling such invalid access dependent on whether the faulting engine supports GPU virtual addressing or not:

    -
  • For engines which don’t support GPU virtual addressing and use the allocation and patch location list to patch memory references, an invalid access occurs when the user mode driver submits an allocation list which references an allocation which is not resident on the device (i.e. the user mode driver hasn’t called [MakeResidentCb](https://msdn.microsoft.com/library/windows/hardware/dn906357) on that allocation). When this occurs, the graphics kernel will put the faulty context/device in error.
  • -
  • For engines which do support GPU virtual addressing but access a GPU virtual address that is invalid, either because there is no allocation behind the virtual address or there is a valid allocation but it hasn’t been made resident, the GPU is expected to raise an unrecoverable page fault in the form of an interrupt. When the page fault interrupt occurs, the kernel mode driver will need to forward the error to the graphics kernel through a new page fault notification. Upon receiving this notification, the graphics kernel will initiate an engine reset on the faulting engine and put the faulty context/device in error. If the engine reset is unsuccessful, the graphics kernel will promote the error to a full adapter wide timeout detection and recovery (TDR).
  • +
  • For engines that don't support GPU virtual addressing and use the allocation and patch location list to patch memory references, an invalid access occurs when the user mode driver submits an allocation list which references an allocation which is not resident on the device (i.e. the user mode driver hasn't called [MakeResidentCb](https://msdn.microsoft.com/library/windows/hardware/dn906357) on that allocation). When this occurs, the graphics kernel puts the faulty context/device in error.
  • +
  • For engines that do support GPU virtual addressing but access a GPU virtual address that is invalid, either because there is no allocation behind the virtual address or there is a valid allocation but it hasn't been made resident, the GPU is expected to raise an unrecoverable page fault in the form of an interrupt. When the page fault interrupt occurs, the kernel mode driver needs to forward the error to the graphics kernel through a new page fault notification. Upon receiving this notification, the graphics kernel initiates an engine reset on the faulting engine and puts the faulty context/device in error. If the engine reset is unsuccessful, the graphics kernel promotes the error to a full adapter wide timeout detection and recovery (TDR).
diff --git a/windows-driver-docs-pr/display/driver-services-start-type-directive.md b/windows-driver-docs-pr/display/driver-services-start-type-directive.md index 065db6600b..09d0423f22 100644 --- a/windows-driver-docs-pr/display/driver-services-start-type-directive.md +++ b/windows-driver-docs-pr/display/driver-services-start-type-directive.md @@ -1,6 +1,6 @@ --- -title: Driver\\services start type directive -description: The driver\\services start type directive is a service installation setting requirement for all display drivers. Windows Display Driver Model (WDDM) drivers are Plug and Play (PnP) and therefore must be demand started, where StartType 3. +title: Driver\services start type directive +description: The "driver\services" start type directive is a service installation setting requirement for all display drivers. Windows Display Driver Model (WDDM) drivers are Plug and Play (PnP) and therefore must be demand started, where StartType=3. ms.assetid: 1B34DC18-EA81-44DB-B60A-D05B685E9321 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/display/dxgi-format-r10g10b10-xr-bias-a2-unorm.md b/windows-driver-docs-pr/display/dxgi-format-r10g10b10-xr-bias-a2-unorm.md index 20242adba6..0522eb44f0 100644 --- a/windows-driver-docs-pr/display/dxgi-format-r10g10b10-xr-bias-a2-unorm.md +++ b/windows-driver-docs-pr/display/dxgi-format-r10g10b10-xr-bias-a2-unorm.md @@ -1,6 +1,6 @@ --- -title: DXGI\_FORMAT\_R10G10B10\_XR\_BIAS\_A2\_UNORM -description: DXGI\_FORMAT\_R10G10B10\_XR\_BIAS\_A2\_UNORM +title: DXGI_FORMAT_R10G10B10_XR_BIAS_A2_UNORM +description: DXGI_FORMAT_R10G10B10_XR_BIAS_A2_UNORM ms.assetid: 2aef590f-2328-4175-ab60-c72b1fd83db7 keywords: - Direct3D version 10.1 WDK Windows 7 display , DXGI_FORMAT_R10G10B10_XR_BIAS_A2_UNORM diff --git a/windows-driver-docs-pr/display/dxva-configqueryorreplyflag-and-dxva-configqueryorreplyfunc-variables.md b/windows-driver-docs-pr/display/dxva-configqueryorreplyflag-and-dxva-configqueryorreplyfunc-variables.md index c087970453..7cf5cbcfe2 100644 --- a/windows-driver-docs-pr/display/dxva-configqueryorreplyflag-and-dxva-configqueryorreplyfunc-variables.md +++ b/windows-driver-docs-pr/display/dxva-configqueryorreplyflag-and-dxva-configqueryorreplyfunc-variables.md @@ -1,6 +1,6 @@ --- -title: DXVA\_ConfigQueryOrReplyFlag and DXVA\_ConfigQueryorReplyFunc Variables -description: DXVA\_ConfigQueryOrReplyFlag and DXVA\_ConfigQueryorReplyFunc Variables +title: DXVA_ConfigQueryOrReplyFlag and DXVA_ConfigQueryorReplyFunc Variables +description: DXVA_ConfigQueryOrReplyFlag and DXVA_ConfigQueryorReplyFunc Variables ms.assetid: bfb1a98e-b9f0-4baa-b486-b2ff33a8bac5 keywords: - video decoding WDK DirectX VA , formats diff --git a/windows-driver-docs-pr/display/float-to-xr-bias-conversion-rules.md b/windows-driver-docs-pr/display/float-to-xr-bias-conversion-rules.md index f3ae0d8868..a015b4eb3f 100644 --- a/windows-driver-docs-pr/display/float-to-xr-bias-conversion-rules.md +++ b/windows-driver-docs-pr/display/float-to-xr-bias-conversion-rules.md @@ -1,6 +1,6 @@ --- -title: Float to XR\_BIAS Conversion Rules -description: Float to XR\_BIAS Conversion Rules +title: Float to XR_BIAS Conversion Rules +description: Float to XR_BIAS Conversion Rules ms.assetid: 496306d5-7494-4df6-8af7-9acb0e2708f9 keywords: - Direct3D version 10.1 WDK Windows 7 display , converting float to XR_BIAS diff --git a/windows-driver-docs-pr/display/general-install-section-directives.md b/windows-driver-docs-pr/display/general-install-section-directives.md index 6fe8d80493..a107a346f5 100644 --- a/windows-driver-docs-pr/display/general-install-section-directives.md +++ b/windows-driver-docs-pr/display/general-install-section-directives.md @@ -16,9 +16,9 @@ This is a general reminder that all references to out-of-box or production/retai Do not refer to anything that is required by your OpenGL ICDs, OpenCL, Control Panel, Help files, out-of-box services, polling applications, and so on. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20General%20install%20section%20directives%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/general-unicode-requirement.md b/windows-driver-docs-pr/display/general-unicode-requirement.md index 7dd10f2342..f5b0d94951 100644 --- a/windows-driver-docs-pr/display/general-unicode-requirement.md +++ b/windows-driver-docs-pr/display/general-unicode-requirement.md @@ -12,7 +12,7 @@ ms.technology: windows-devices # General Unicode requirement in INF files -INF files should be saved and encoded as Unicode; they must not be ANSI. +INF files should be saved and encoded as Unicode (UTF-16); they must not be ANSI or UTF-8. **To check for Unicode in INF files** diff --git a/windows-driver-docs-pr/display/gpu-power-management-of-idle-and-active-power.md b/windows-driver-docs-pr/display/gpu-power-management-of-idle-and-active-power.md index e74dc935cd..fef6dfd08e 100644 --- a/windows-driver-docs-pr/display/gpu-power-management-of-idle-and-active-power.md +++ b/windows-driver-docs-pr/display/gpu-power-management-of-idle-and-active-power.md @@ -12,7 +12,7 @@ ms.technology: windows-devices # GPU power management of idle states and active power -Starting with Windows8, an optional GPU power management infrastructure is available that lets Windows Display Driver Model (WDDM) 1.2 and later drivers manage power for individual devices or a set of devices. This infrastructure provides a standardized mechanism to support F-state and P-state power management in collaboration with Windows. +Starting with Windows 8, an optional GPU power management infrastructure is available that lets Windows Display Driver Model (WDDM) 1.2 and later drivers manage power for individual devices or a set of devices. This infrastructure provides a standardized mechanism to support F-state and P-state power management in collaboration with Windows. | | | |-----------------------------------------------------------------------------------|----------------------------------------| @@ -21,12 +21,12 @@ Starting with Windows | Driver implementation | Optional | | [WHCK]( http://go.microsoft.com/fwlink/p/?linkid=258342) requirements and tests | **Device.Graphics…RuntimePowerMgmt** | - + ## GPU power management device driver interface (DDI) -These new and updated functions and structures are available starting with Windows8 for the display miniport driver to transition the state of power components and to communicate power events with the Microsoft DirectX graphics kernel subsystem. +These new and updated functions and structures are available starting with Windows 8 for the display miniport driver to transition the state of power components and to communicate power events with the Microsoft DirectX graphics kernel subsystem. - [*DxgkCbCompleteFStateTransition*](https://msdn.microsoft.com/library/windows/hardware/jj128349) - [*DxgkCbPowerRuntimeControlRequest*](https://msdn.microsoft.com/library/windows/hardware/hh451323) @@ -53,18 +53,18 @@ GPUs and display screens are two of the largest power consumers in laptops, mobi These are the key power management scenarios to reduce power consumption and extend battery life: - Mobile form factor devices can go into an idle state and save power because individual system components shut down if they are not in use. -- Windows System on a Chip (SoC)–based devices behave like consumer devices and mobile phonesthat is, they turn on immediately when they are needed, thereby saving energy. +- Windows System on a Chip (SoC)–based devices behave like consumer devices and mobile phones that is, they turn on immediately when they are needed, thereby saving energy. ## Hardware certification requirements For info on requirements that hardware devices must meet when they implement this feature, refer to the relevant [WHCK documentation]( http://go.microsoft.com/fwlink/p/?linkid=258342) on **Device.Graphics…RuntimePowerMgmt**. -See [WDDM 1.2 features](wddm-v1-2-features.md) for a review of features added with Windows8. +See [WDDM 1.2 features](wddm-v1-2-features.md) for a review of features added with Windows 8. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20GPU%20power%20management%20of%20idle%20states%20and%20active%20power%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/gpu-virtual-memory-in-wddm-2-0.md b/windows-driver-docs-pr/display/gpu-virtual-memory-in-wddm-2-0.md index ab7bd90aba..8b060b5881 100644 --- a/windows-driver-docs-pr/display/gpu-virtual-memory-in-wddm-2-0.md +++ b/windows-driver-docs-pr/display/gpu-virtual-memory-in-wddm-2-0.md @@ -12,7 +12,7 @@ ms.technology: windows-devices # GPU virtual memory in WDDM 2.0 -This section provides details about GPU virtual memory, including why the changes were made and how drivers will use it. This functionality is available starting with Windows10. +This section provides details about GPU virtual memory, including why the changes were made and how drivers will use it. This functionality is available starting with Windows 10. ## Introduction @@ -42,9 +42,9 @@ In the *IoMmu* model, the CPU and GPU share a common address space and page tabl For more information, see [IoMmu model](iommu-model.md). - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20GPU%20virtual%20memory%20in%20WDDM%202.0%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/gpummu-model.md b/windows-driver-docs-pr/display/gpummu-model.md index 3f68458802..520a678a27 100644 --- a/windows-driver-docs-pr/display/gpummu-model.md +++ b/windows-driver-docs-pr/display/gpummu-model.md @@ -16,7 +16,7 @@ In the *GpuMmu* model, the graphics processing unit (GPU) has its own memory man Each process has separate CPU and GPU virtual address spaces that use distinct page tables. The video memory manager manages the GPU virtual address space of all processes and is in charge of allocating, growing, updating, ensuring residency and freeing page tables. The hardware format of the page tables, used by the GPU MMU, is unknown to the video memory manager and is abstracted through device driver interfaces (DDIs). The abstraction supports a multilevel level translation, including a fixed size page table and a resizable root page table. -Although the video memory manager is responsible for managing the GPU virtual address space and its underlying page tables, the video memory manager doesn’t automatically assign GPU virtual addresses to allocations. This responsibility falls onto the user mode driver. +Although the video memory manager is responsible for managing the GPU virtual address space and its underlying page tables, the video memory manager doesn't automatically assign GPU virtual addresses to allocations. This responsibility falls onto the user mode driver. The video memory manager offers two set of services to the user mode driver. First, the user mode driver may allocate video memory through the existing [*Allocate*](https://msdn.microsoft.com/library/windows/hardware/ff568893) callback and free that memory through the existing [*Deallocate*](https://msdn.microsoft.com/library/windows/hardware/ff568898) callback. Just like today, this returns the user mode driver a handle to a video memory manager allocation, which can be operated on by a GPU engine. Such allocation represents only the physical portion of an allocation and may be referenced by an engine, operating physically, through allocation list reference. diff --git a/windows-driver-docs-pr/display/h261-a.md b/windows-driver-docs-pr/display/h261-a.md index dc9f788e15..cdf0f13464 100644 --- a/windows-driver-docs-pr/display/h261-a.md +++ b/windows-driver-docs-pr/display/h261-a.md @@ -1,6 +1,6 @@ --- -title: H261\_A -description: H261\_A +title: H261_A +description: H261_A ms.assetid: 3212a331-06f8-437e-9f04-e8397d16b7b4 keywords: - H261_A restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h261-b.md b/windows-driver-docs-pr/display/h261-b.md index 5c731aad9b..9927aa30cb 100644 --- a/windows-driver-docs-pr/display/h261-b.md +++ b/windows-driver-docs-pr/display/h261-b.md @@ -1,6 +1,6 @@ --- -title: H261\_B -description: H261\_B +title: H261_B +description: H261_B ms.assetid: 9a2ccb4b-4bdf-4fb4-ba11-7f43f8423756 keywords: - H261_B restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-a.md b/windows-driver-docs-pr/display/h263-a.md index c41520a3a3..a2cd572842 100644 --- a/windows-driver-docs-pr/display/h263-a.md +++ b/windows-driver-docs-pr/display/h263-a.md @@ -1,6 +1,6 @@ --- -title: H263\_A -description: H263\_A +title: H263_A +description: H263_A ms.assetid: 55ebafec-5924-44e3-96cc-c2b0c6e912c8 keywords: - H263_A restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-b.md b/windows-driver-docs-pr/display/h263-b.md index f9c8ad6c7f..c92ebf7f13 100644 --- a/windows-driver-docs-pr/display/h263-b.md +++ b/windows-driver-docs-pr/display/h263-b.md @@ -1,6 +1,6 @@ --- -title: H263\_B -description: H263\_B +title: H263_B +description: H263_B ms.assetid: 3a4b8911-caa1-41f3-803a-26a831aa91f0 keywords: - H263_B restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-c.md b/windows-driver-docs-pr/display/h263-c.md index c161708196..56836154c5 100644 --- a/windows-driver-docs-pr/display/h263-c.md +++ b/windows-driver-docs-pr/display/h263-c.md @@ -1,6 +1,6 @@ --- -title: H263\_C -description: H263\_C +title: H263_C +description: H263_C ms.assetid: 30ddb90d-3947-426c-b780-7214c9cb3b49 keywords: - H263_C restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-d.md b/windows-driver-docs-pr/display/h263-d.md index 0025757521..2dc720be72 100644 --- a/windows-driver-docs-pr/display/h263-d.md +++ b/windows-driver-docs-pr/display/h263-d.md @@ -1,6 +1,6 @@ --- -title: H263\_D -description: H263\_D +title: H263_D +description: H263_D ms.assetid: c25cded7-ea4e-4e82-9200-f90b2bdefc97 keywords: - H263_D restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-e.md b/windows-driver-docs-pr/display/h263-e.md index 4f45709b82..3326fb8dfa 100644 --- a/windows-driver-docs-pr/display/h263-e.md +++ b/windows-driver-docs-pr/display/h263-e.md @@ -1,6 +1,6 @@ --- -title: H263\_E -description: H263\_E +title: H263_E +description: H263_E ms.assetid: 21022bc6-8102-4727-8f8b-9cec6cce35cb keywords: - H263_E restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/h263-f.md b/windows-driver-docs-pr/display/h263-f.md index 38fceb09dd..d0360d25ec 100644 --- a/windows-driver-docs-pr/display/h263-f.md +++ b/windows-driver-docs-pr/display/h263-f.md @@ -1,6 +1,6 @@ --- -title: H263\_F -description: H263\_F +title: H263_F +description: H263_F ms.assetid: 7b7a6b8b-0383-4d2e-84be-d5dd6392c876 keywords: - H263_F restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/handling-the-e-invalidarg-return-value.md b/windows-driver-docs-pr/display/handling-the-e-invalidarg-return-value.md index 03f9293534..9720ad8e60 100644 --- a/windows-driver-docs-pr/display/handling-the-e-invalidarg-return-value.md +++ b/windows-driver-docs-pr/display/handling-the-e-invalidarg-return-value.md @@ -1,6 +1,6 @@ --- -title: Handling the E\_INVALIDARG Return Value -description: Handling the E\_INVALIDARG Return Value +title: Handling the E_INVALIDARG Return Value +description: Handling the E_INVALIDARG Return Value ms.assetid: 312b2452-71b3-4fbe-93fb-f4b0e6099c0f keywords: - user-mode display drivers WDK Windows Vista , E_INVALIDARG return value diff --git a/windows-driver-docs-pr/display/handling-unsupported-ioctl-video-xxx-requests.md b/windows-driver-docs-pr/display/handling-unsupported-ioctl-video-xxx-requests.md index efc839b1b1..27ee07d331 100644 --- a/windows-driver-docs-pr/display/handling-unsupported-ioctl-video-xxx-requests.md +++ b/windows-driver-docs-pr/display/handling-unsupported-ioctl-video-xxx-requests.md @@ -1,6 +1,6 @@ --- -title: Handling Unsupported IOCTL\_VIDEO\_XXX Requests -description: Handling Unsupported IOCTL\_VIDEO\_XXX Requests +title: Handling Unsupported IOCTL_VIDEO_XXX Requests +description: Handling Unsupported IOCTL_VIDEO_XXX Requests ms.assetid: e3a96cc2-bb7f-4060-bf71-d8a63b918329 keywords: - video miniport drivers WDK Windows 2000 , processing requests diff --git a/windows-driver-docs-pr/display/hardware-support-for-direct3d-feature-levels.md b/windows-driver-docs-pr/display/hardware-support-for-direct3d-feature-levels.md index c93b193e00..c2fa7e6076 100644 --- a/windows-driver-docs-pr/display/hardware-support-for-direct3d-feature-levels.md +++ b/windows-driver-docs-pr/display/hardware-support-for-direct3d-feature-levels.md @@ -1,6 +1,6 @@ --- title: Hardware support for Direct3D feature levels -description: Display device hardware must support Microsoft Direct3D feature levels as described in the following Direct3D topics Direct3D feature levels10Level9 ID3D11Device Methods10Level9 ID3D11DeviceContext MethodsHardware Support for Direct3D 10Level9 FormatsIn addition, the user-mode driver must expose certain capabilities in Direct3D feature levels 9\_1, 9\_2, and 9\_3 in order for Direct3D features to be properly exposed to applications. These driver topics list the specific capabilities and display formats that the driver must expose Required Direct3D 9 capabilitiesRequired DXGI formats. +description: Display device hardware must support Microsoft Direct3D feature levels as described in the following Direct3D topics Direct3D feature levels10Level9 ID3D11Device Methods10Level9 ID3D11DeviceContext MethodsHardware Support for Direct3D 10Level9 FormatsIn addition, the user-mode driver must expose certain capabilities in Direct3D feature levels 9_1, 9_2, and 9_3 in order for Direct3D features to be properly exposed to applications. These driver topics list the specific capabilities and display formats that the driver must expose Required Direct3D 9 capabilitiesRequired DXGI formats. ms.assetid: 32FF5A1F-FBD0-4273-BA21-85CC0E759DC0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/display/hybrid-system-ddi.md b/windows-driver-docs-pr/display/hybrid-system-ddi.md index 15dc5461db..b7fb60c830 100644 --- a/windows-driver-docs-pr/display/hybrid-system-ddi.md +++ b/windows-driver-docs-pr/display/hybrid-system-ddi.md @@ -1,6 +1,6 @@ --- title: Hybrid system DDI -description: Starting with Windows 8.1, these user-mode and kernel-mode structures and enumerations of the display device driver interface (DDI) are updated to handle cross-adapter resources on a hybrid system D3D10\_DDI\_RESOURCE\_MISC\_FLAGD3DDDI\_RESOURCEFLAGS2D3DDDI\_SYNCHRONIZATIONOBJECT\_FLAGSD3DKMDT\_GDISURFACEDATAD3DKMDT\_GDISURFACETYPEDXGK\_DRIVERCAPSDXGK\_VIDMMCAPSThis function, new for Windows 8.1, is implemented by the user-mode display driver QueryDListForApplication1. +description: Starting with Windows 8.1, these user-mode and kernel-mode structures and enumerations of the display device driver interface (DDI) are updated to handle cross-adapter resources on a hybrid system D3D10_DDI_RESOURCE_MISC_FLAGD3DDDI_RESOURCEFLAGS2D3DDDI_SYNCHRONIZATIONOBJECT_FLAGSD3DKMDT_GDISURFACEDATAD3DKMDT_GDISURFACETYPEDXGK_DRIVERCAPSDXGK_VIDMMCAPSThis function, new for Windows 8.1, is implemented by the user-mode display driver QueryDListForApplication1. ms.assetid: 8AABE677-2C2D-4CFD-AF22-06D65524A158 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/display/mpeg1-a.md b/windows-driver-docs-pr/display/mpeg1-a.md index 1339ced4f0..2a207fa26d 100644 --- a/windows-driver-docs-pr/display/mpeg1-a.md +++ b/windows-driver-docs-pr/display/mpeg1-a.md @@ -1,6 +1,6 @@ --- -title: MPEG1\_A -description: MPEG1\_A +title: MPEG1_A +description: MPEG1_A ms.assetid: 2c4d79b7-3331-49f9-a561-6e5b609543df keywords: - MPEG1_A restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/mpeg2-a.md b/windows-driver-docs-pr/display/mpeg2-a.md index a6d9d6eb32..dd775b0eda 100644 --- a/windows-driver-docs-pr/display/mpeg2-a.md +++ b/windows-driver-docs-pr/display/mpeg2-a.md @@ -1,6 +1,6 @@ --- -title: MPEG2\_A -description: MPEG2\_A +title: MPEG2_A +description: MPEG2_A ms.assetid: 4f9e2aad-4072-4a49-87df-dfc6b4bf5f56 keywords: - MPEG2_A restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/mpeg2-b.md b/windows-driver-docs-pr/display/mpeg2-b.md index 098fa56d6f..e96f04463e 100644 --- a/windows-driver-docs-pr/display/mpeg2-b.md +++ b/windows-driver-docs-pr/display/mpeg2-b.md @@ -1,6 +1,6 @@ --- -title: MPEG2\_B -description: MPEG2\_B +title: MPEG2_B +description: MPEG2_B ms.assetid: 7d67f0ef-a5eb-40db-9f00-6f652d28e530 keywords: - MPEG2_B restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/mpeg2-c.md b/windows-driver-docs-pr/display/mpeg2-c.md index 1590744e89..58e9846244 100644 --- a/windows-driver-docs-pr/display/mpeg2-c.md +++ b/windows-driver-docs-pr/display/mpeg2-c.md @@ -1,6 +1,6 @@ --- -title: MPEG2\_C -description: MPEG2\_C +title: MPEG2_C +description: MPEG2_C ms.assetid: 610ca80d-b29a-4c30-98df-8df8fe825157 keywords: - MPEG2_C restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/mpeg2-d.md b/windows-driver-docs-pr/display/mpeg2-d.md index f733cef5c0..94601740f9 100644 --- a/windows-driver-docs-pr/display/mpeg2-d.md +++ b/windows-driver-docs-pr/display/mpeg2-d.md @@ -1,6 +1,6 @@ --- -title: MPEG2\_D -description: MPEG2\_D +title: MPEG2_D +description: MPEG2_D ms.assetid: f5cb5e49-c64c-46d2-92bb-68db1d9c5d18 keywords: - MPEG2_D restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/performing-copp-operations-example.md b/windows-driver-docs-pr/display/performing-copp-operations-example.md index 93bfaae40c..acffa6ac4a 100644 --- a/windows-driver-docs-pr/display/performing-copp-operations-example.md +++ b/windows-driver-docs-pr/display/performing-copp-operations-example.md @@ -143,9 +143,9 @@ DWORD APIENTRY } ``` - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Performing%20COPP%20Operations%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/plug-and-play--pnp--start-and-stop-cases.md b/windows-driver-docs-pr/display/plug-and-play--pnp--start-and-stop-cases.md index 227ee8a8b3..f82b698558 100644 --- a/windows-driver-docs-pr/display/plug-and-play--pnp--start-and-stop-cases.md +++ b/windows-driver-docs-pr/display/plug-and-play--pnp--start-and-stop-cases.md @@ -31,7 +31,7 @@ All Windows Display Driver Model (WDDM) 1.2 and later display miniport drivers m 8 -Driver implementationFull graphics and Display only +Driver implementation-Full graphics and Display only Mandatory @@ -41,12 +41,12 @@ All Windows Display Driver Model (WDDM) 1.2 and later display miniport drivers m - + ## Display miniport driver PnP DDI -Starting in Windows8, the Microsoft DirectX graphics kernel subsystem provides this function that a driver can call if the display device is started or resumed from hibernation: +Starting in Windows 8, the Microsoft DirectX graphics kernel subsystem provides this function that a driver can call if the display device is started or resumed from hibernation: - [**DxgkCbAcquirePostDisplayOwnership**](https://msdn.microsoft.com/library/windows/hardware/hh451339) @@ -82,7 +82,7 @@ These are the return codes that the driver should return after a PnP start proce

Success

-

Behavior is the same as in Windows7.

+

Behavior is the same as in Windows 7.

For a BIOS-based system, if the driver starts successfully, the frame buffer is still active and the driver must be ready to set to a valid mode.

@@ -93,7 +93,7 @@ These are the return codes that the driver should return after a PnP start proce - + ## PnP stop operation @@ -130,14 +130,14 @@ These are the return codes that the driver should return after a PnP stop proces

Failure

-

The operating system calls the Windows7-style PnP stop driver interface through the [DxgkDdiStopDevice](https://msdn.microsoft.com/library/windows/hardware/ff560781) function.

+

The operating system calls the Windows 7-style PnP stop driver interface through the [DxgkDdiStopDevice](https://msdn.microsoft.com/library/windows/hardware/ff560781) function.

For a BIOS-based system, the driver must set the display into a BIOS-compatible mode.

For a UEFI-based system, the basic display driver runs in headless mode on the graphics adapter.

- + For further requirements on PnP and other state transitions, see [Providing seamless state transitions in WDDM 1.2 and later](seamless-state-transitions-in-wddm-1-2-and-later.md). @@ -146,11 +146,11 @@ For further requirements on PnP and other state transitions, see [Providing seam For info on requirements that hardware devices must meet when they implement this feature, refer to the relevant [WHCK documentation]( http://go.microsoft.com/fwlink/p/?linkid=258342) on **Device.Graphics.WDDM12.Display.PnpStopStartSupport**. -See [WDDM 1.2 features](wddm-v1-2-features.md) for a review of features added with Windows8. +See [WDDM 1.2 features](wddm-v1-2-features.md) for a review of features added with Windows 8. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Plug%20and%20Play%20%28PnP%29%20in%20WDDM%201.2%20and%20later%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/privately-defined-display-miniport-driver-ioctl-video-xxx-requests.md b/windows-driver-docs-pr/display/privately-defined-display-miniport-driver-ioctl-video-xxx-requests.md index 65150c14e8..1fddbcef0b 100644 --- a/windows-driver-docs-pr/display/privately-defined-display-miniport-driver-ioctl-video-xxx-requests.md +++ b/windows-driver-docs-pr/display/privately-defined-display-miniport-driver-ioctl-video-xxx-requests.md @@ -1,6 +1,6 @@ --- -title: Privately Defined Display-Miniport Driver IOCTL\_VIDEO\_XXX Requests -description: Privately Defined Display-Miniport Driver IOCTL\_VIDEO\_XXX Requests +title: Privately Defined Display-Miniport Driver IOCTL_VIDEO_XXX Requests +description: Privately Defined Display-Miniport Driver IOCTL_VIDEO_XXX Requests ms.assetid: 45d8c9bc-993c-4fd3-949d-dfb30bb685d7 keywords: - video miniport drivers WDK Windows 2000 , processing requests diff --git a/windows-driver-docs-pr/display/processing-the-d3ddp2op-clear-dp2-token.md b/windows-driver-docs-pr/display/processing-the-d3ddp2op-clear-dp2-token.md index 34bf18e573..e363a81032 100644 --- a/windows-driver-docs-pr/display/processing-the-d3ddp2op-clear-dp2-token.md +++ b/windows-driver-docs-pr/display/processing-the-d3ddp2op-clear-dp2-token.md @@ -1,6 +1,6 @@ --- -title: Processing the D3DDP2OP\_CLEAR DP2 Token -description: Processing the D3DDP2OP\_CLEAR DP2 Token +title: Processing the D3DDP2OP_CLEAR DP2 Token +description: Processing the D3DDP2OP_CLEAR DP2 Token ms.assetid: ec027f44-bdd5-4d5a-8c47-1ac6a0c1cb6e keywords: - DirectX 8.0 release notes WDK Windows 2000 display , pure devices, D3DDP2OP_CLEAR DP2 token processing diff --git a/windows-driver-docs-pr/display/required-direct3d-9-capabilities.md b/windows-driver-docs-pr/display/required-direct3d-9-capabilities.md index 9a8b473081..2bc52c46e3 100644 --- a/windows-driver-docs-pr/display/required-direct3d-9-capabilities.md +++ b/windows-driver-docs-pr/display/required-direct3d-9-capabilities.md @@ -168,13 +168,13 @@ For applications to fully access the features of Microsoft Direct3D versions 9\_ - + -**Note**These requirements also apply: +**Note** These requirements also apply: - The driver must also set the **TextureCaps** member to a value of D3DPTEXTURECAPS\_NONPOW2CONDITIONAL and D3DPTEXTURECAPS\_POW2, or to neither. - When the driver responds to an event, where [**D3DDDIARG\_CREATEQUERY**](https://msdn.microsoft.com/library/windows/hardware/ff542958).**QueryType** is D3DDDIQUERYTYPE\_EVENT, it must always set the event's **BOOL** value to **TRUE** when responding. See [*CreateQuery*](https://msdn.microsoft.com/library/windows/hardware/ff540673) and **D3DDDIARG\_CREATEQUERY**. - + ## Minimum capabilities for Direct3D level 9\_2 @@ -244,12 +244,12 @@ These capabilities must be set in addition to those listed for Direct3D level 9\ - + -**Note**This requirement also applies: +**Note** This requirement also applies: - When the driver responds to a *z*-testing query, where [**D3DDDIARG\_CREATEQUERY**](https://msdn.microsoft.com/library/windows/hardware/ff542958).**QueryType** is D3DDDIQUERYTYPE\_OCCLUSION, it must always set the query's **UINT** value to a non-zero value when responding. See [*CreateQuery*](https://msdn.microsoft.com/library/windows/hardware/ff540673) and **D3DDDIARG\_CREATEQUERY**. - + ## Minimum capabilities for Direct3D level 9\_3 @@ -320,15 +320,15 @@ These capabilities must be set in addition to those listed for Direct3D levels 9 - + -**Note**The **VertexShaderVersion** value of D3DVS\_VERSION(3,0) guarantees instancing support. Direct3D 10Level 9 does not expose Shader Model 3.0. +**Note** The **VertexShaderVersion** value of D3DVS\_VERSION(3,0) guarantees instancing support. Direct3D 10Level 9 does not expose Shader Model 3.0. - + - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Required%20Direct3D%209%20capabilities%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/support-for-headless-systems.md b/windows-driver-docs-pr/display/support-for-headless-systems.md index 29ba927e2b..d62a6ced45 100644 --- a/windows-driver-docs-pr/display/support-for-headless-systems.md +++ b/windows-driver-docs-pr/display/support-for-headless-systems.md @@ -18,9 +18,9 @@ Because the stub display is used when no PnP driver is available, no third-party On architectures in which VGA has been the norm, MSBDD requires positive confirmation that VGA is not present; otherwise, it assumes that VGA hardware is available and that the system is not headless. System firmware should set the VGA Not Present flag in the IAPC\_BOOT\_ARCH field of FADT and if there is any VBIOS, it should implement an empty mode list through the VESA BIOS Extensions (VBE). These mechanisms should indicate that VGA is not present even if the system implements a VBIOS with int 10h mode 12h support for compatibility with previous versions of Windows. In the absence of VBE support, the Basic Display Driver uses a display that is initialized by the boot loader, so a headless system should not represent a working display through UEFI GOP. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Support%20for%20headless%20systems%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/supporting-brightness-controls-for-external-display-connectors.md b/windows-driver-docs-pr/display/supporting-brightness-controls-for-external-display-connectors.md index 129174c8e5..72c3b63e9e 100644 --- a/windows-driver-docs-pr/display/supporting-brightness-controls-for-external-display-connectors.md +++ b/windows-driver-docs-pr/display/supporting-brightness-controls-for-external-display-connectors.md @@ -13,7 +13,9 @@ This feature does not support the ability to control the individual panel bright ### General Requirements A new DWORD registry value will be added: “BrightnessControl”. -Registry Path: HKLM\\SYSTEM\\CurrentControlSet\\Control\\Class\\{4D36E96E-E325-11CE-BFC1-08002BE10318} +Registry Path: HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E96E-E325-11CE-BFC1-08002BE10318}\XXXX +Where XXXX is for the targeted individual display. + * The first bit in this registry value defines the non-internal monitor brightness control support. * The second bit defines an ACPI override that forces ACPI brightness to be used. diff --git a/windows-driver-docs-pr/display/supporting-display-output.md b/windows-driver-docs-pr/display/supporting-display-output.md index a9b57db87e..e2df5a909c 100644 --- a/windows-driver-docs-pr/display/supporting-display-output.md +++ b/windows-driver-docs-pr/display/supporting-display-output.md @@ -27,17 +27,17 @@ The display miniport driver or ACPI methods that are exposed by the system BIOS The following aliases for the ACPI display output are defined in Dispmprt.h: -- ACPI\_METHOD\_DISPLAY\_DOD- Enumerates all the devices attached to the display adapter. This method is required if the integrated controller supports switching of output devices. This is the alias name for the DOD\_ method defined by the ACPI specification. -- ACPI\_METHOD\_DISPLAY\_DOS- Indicates that the system firmware is capable of automatically switching the active display output. This is the alias name for the SOD\_ method defined by the ACPI specification. The following are the allowed parameters: +- ACPI\_METHOD\_DISPLAY\_DOD - Enumerates all the devices attached to the display adapter. This method is required if the integrated controller supports switching of output devices. This is the alias name for the DOD\_ method defined by the ACPI specification. +- ACPI\_METHOD\_DISPLAY\_DOS - Indicates that the system firmware is capable of automatically switching the active display output. This is the alias name for the SOD\_ method defined by the ACPI specification. The following are the allowed parameters: - ACPI\_ARG\_ENABLE\_SWITCH\_EVENT. States that the system firmware should not automatically switch the active display output device. Instead, it must save the desired change in state variables associated with each display output device and generate a display switch event. The operating system can query the active status of a device by calling the ACPI\_METHOD\_OUTPUT\_DGS method. - ACPI\_ARG\_ENABLE\_AUTO\_SWITCH. States that the system firmware should automatically switch the active display output device without interacting with the operating system. It does not generate a display switch event. - ACPI\_ARG\_DISABLE\_SWITCH\_EVENT. States that the system firmware should not perform any action; that is, neither switch the output device nor notify the operating system. The values returned by the ACPI\_METHOD\_OUTPUT\_DGS method are locked. -- ACPI\_METHOD\_OUTPUT\_DCS- Returns the status of a display output device. This is the alias name for the CSD\_ method defined by the ACPI specification. -- ACPI\_METHOD\_OUTPUT\_DGS- Checks whether the status of a display output device is active. This is the alias name for the SGD\_ method defined by the ACPI specification. -- ACPI\_METHOD\_OUTPUT\_DSS- Sets the status of a display output device to active or inactive. This is the alias name for the SSD\_ method defined by the ACPI specification. The operating system manages this action to avoid flickering. -- ACPI\_METHOD\_DISPLAY\_GPD- Queries the CMOS entry to determine which video device is posted at boot time. This is the alias name for the DPG\_ method defined by the ACPI specification. -- ACPI\_METHOD\_DISPLAY\_SPD- Updates the CMOS entry that determines which video device is posted at boot time. This is the alias name for the DPS\_ method defined by the ACPI specification. -- ACPI\_METHOD\_DISPLAY\_VPO- Determines what video options are implemented. This is the alias name for the OPV\_ method defined by the ACPI specification. +- ACPI\_METHOD\_OUTPUT\_DCS - Returns the status of a display output device. This is the alias name for the CSD\_ method defined by the ACPI specification. +- ACPI\_METHOD\_OUTPUT\_DGS - Checks whether the status of a display output device is active. This is the alias name for the SGD\_ method defined by the ACPI specification. +- ACPI\_METHOD\_OUTPUT\_DSS - Sets the status of a display output device to active or inactive. This is the alias name for the SSD\_ method defined by the ACPI specification. The operating system manages this action to avoid flickering. +- ACPI\_METHOD\_DISPLAY\_GPD - Queries the CMOS entry to determine which video device is posted at boot time. This is the alias name for the DPG\_ method defined by the ACPI specification. +- ACPI\_METHOD\_DISPLAY\_SPD - Updates the CMOS entry that determines which video device is posted at boot time. This is the alias name for the DPS\_ method defined by the ACPI specification. +- ACPI\_METHOD\_DISPLAY\_VPO - Determines what video options are implemented. This is the alias name for the OPV\_ method defined by the ACPI specification. ## External Asynchronous Events @@ -48,27 +48,27 @@ The operating system must be notified about external, asynchronous events that a - ACPI\_NOTIFY\_NEXT\_DISPLAY\_HOTKEY - Notifies the operating system that the user has pressed the next display keyboard shortcut. - ACPI\_NOTIFY\_PREV\_DISPLAY\_HOTKEY - Notifies the operating system that the user has pressed the previous display keyboard shortcut. -**Note**The previous notifications depend on the handling of the event caused by the user when pressing the keyboard shortcuts. +**Note** The previous notifications depend on the handling of the event caused by the user when pressing the keyboard shortcuts. - + The following are the types of requests that the display miniport driver can make to the operating system. - DXGK\_ACPI\_CHANGE\_DISPLAY\_MODE - Requests to initiate a mode change to the new recommended active video present network (VidPN). - DXGK\_ACPI\_POLL\_DISPLAY\_CHILDREN - Requests to poll the connectivity of the children of the display adapter. -**Note**The previous requests are the values of the *AcpiFlags* parameter returned by the [**DxgkDdiNotifyAcpiEvent**](https://msdn.microsoft.com/library/windows/hardware/ff559695) function. +**Note** The previous requests are the values of the *AcpiFlags* parameter returned by the [**DxgkDdiNotifyAcpiEvent**](https://msdn.microsoft.com/library/windows/hardware/ff559695) function. - + ## Related topics [Supporting Brightness Controls on Integrated Display Panels](supporting-brightness-controls-on-integrated-display-panels.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Supporting%20Display%20Output%20and%20ACPI%20Events%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/system-defined-ioctl-video-xxx-requests.md b/windows-driver-docs-pr/display/system-defined-ioctl-video-xxx-requests.md index 3e904f8730..47edc7bf6d 100644 --- a/windows-driver-docs-pr/display/system-defined-ioctl-video-xxx-requests.md +++ b/windows-driver-docs-pr/display/system-defined-ioctl-video-xxx-requests.md @@ -1,6 +1,6 @@ --- -title: System-Defined IOCTL\_VIDEO\_XXX Requests -description: System-Defined IOCTL\_VIDEO\_XXX Requests +title: System-Defined IOCTL_VIDEO_XXX Requests +description: System-Defined IOCTL_VIDEO_XXX Requests ms.assetid: 30309de1-c991-402d-a701-7e88c3367d24 keywords: - video miniport drivers WDK Windows 2000 , processing requests diff --git a/windows-driver-docs-pr/display/using-cross-adapter-resources-in-a-hybrid-system.md b/windows-driver-docs-pr/display/using-cross-adapter-resources-in-a-hybrid-system.md index 80ce414f0e..b85525d4d3 100644 --- a/windows-driver-docs-pr/display/using-cross-adapter-resources-in-a-hybrid-system.md +++ b/windows-driver-docs-pr/display/using-cross-adapter-resources-in-a-hybrid-system.md @@ -12,7 +12,7 @@ ms.technology: windows-devices # Using cross-adapter resources in a hybrid system -Starting in Windows8.1, a Windows Display Driver Model (WDDM) driver can support a *hybrid system*, where *cross-adapter resources* are shared between an integrated GPU and a discrete GPU, and an application can be run on either GPU, depending on the needs of the application. The operating system and driver together determine which GPU an application should run on. +Starting in Windows 8.1, a Windows Display Driver Model (WDDM) driver can support a *hybrid system*, where *cross-adapter resources* are shared between an integrated GPU and a discrete GPU, and an application can be run on either GPU, depending on the needs of the application. The operating system and driver together determine which GPU an application should run on. The display miniport driver should express support for cross-adapter resources by setting the **CrossAdapterResource** member of the [**DXGK\_VIDMMCAPS**](https://msdn.microsoft.com/library/windows/hardware/ff562072) structure. @@ -38,7 +38,7 @@ These subsequent topics give more details on driver implementation for hybrid sy ## Definition and properties of a cross-adapter resource: -- A cross-adapter resource is available only starting in Windows8.1. +- A cross-adapter resource is available only starting in Windows 8.1. - It can be paged-in only to the aperture GPU memory segment. - It is allocated as a shared resource. - It has only one allocation, in a linear format. @@ -48,9 +48,9 @@ These subsequent topics give more details on driver implementation for hybrid sy - It might be created as a standard allocation from kernel mode by the display miniport driver and then be opened later by the user-mode display driver. - It might be created by the user-mode display driver. - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Using%20cross-adapter%20resources%20in%20a%20hybrid%20system%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/what-s-new-for-windows-8-display-drivers.md b/windows-driver-docs-pr/display/what-s-new-for-windows-8-display-drivers.md index d9846b1575..59e4f7866b 100644 --- a/windows-driver-docs-pr/display/what-s-new-for-windows-8-display-drivers.md +++ b/windows-driver-docs-pr/display/what-s-new-for-windows-8-display-drivers.md @@ -15,7 +15,7 @@ ms.technology: windows-devices # What's new for Windows 8 display drivers (WDDM 1.2) -Windows8 introduced version 1.2 of the Windows Display Driver Model (WDDM). WDDM 1.2 also supports Microsoft Direct3D Version 11.1. See these topics for info on features, guidance to independent hardware vendors (IHVs), and hardware requirements: +Windows 8 introduced version 1.2 of the Windows Display Driver Model (WDDM). WDDM 1.2 also supports Microsoft Direct3D Version 11.1. See these topics for info on features, guidance to independent hardware vendors (IHVs), and hardware requirements: [WDDM 1.2 and Windows 8](wddm-in-windows-8.md) Overview of WDDM 1.2 @@ -51,9 +51,9 @@ XR and XR\_BIAS format requirements have been corrected in these topics: [Conversion from BGR8888 to XR\_BIAS](conversion-from-bgr8888-to-xr-bias.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20What's%20new%20for%20Windows%208%20display%20drivers%20%28WDDM%201.2%29%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/what-s-new-for-windows-threshold-display-drivers--wddm-2-0-.md b/windows-driver-docs-pr/display/what-s-new-for-windows-threshold-display-drivers--wddm-2-0-.md index 83f9e28150..5f48c24eb1 100644 --- a/windows-driver-docs-pr/display/what-s-new-for-windows-threshold-display-drivers--wddm-2-0-.md +++ b/windows-driver-docs-pr/display/what-s-new-for-windows-threshold-display-drivers--wddm-2-0-.md @@ -1,5 +1,5 @@ --- -title: What's new for Windows10 display drivers (WDDM 2.0) +title: What's new for Windows 10 display drivers (WDDM 2.0) description: Describes new features in Windows 10 for display drivers ms.assetid: 619175D4-98DA-4B17-8F6F-71B13A31374D ms.author: windowsdriverdev @@ -9,7 +9,7 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# What's new for Windows10 display drivers (WDDM 2.0) +# What's new for Windows 10 display drivers (WDDM 2.0) ### Memory Management @@ -31,9 +31,9 @@ Driver residency - New DDIs have been added for process synchronization and context monitoring. For more details, see [Driver residency in WDDM 2.0](driver-residency-in-wddm-2-0.md). - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20What's%20new%20for%20Windows%C2%A010%20display%20drivers%20%28WDDM%202.0%29%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/windows-8-in-box-graphics-drivers-treated-as-generic-drivers-.md b/windows-driver-docs-pr/display/windows-8-in-box-graphics-drivers-treated-as-generic-drivers-.md index afff6377ea..09fdaef6d3 100644 --- a/windows-driver-docs-pr/display/windows-8-in-box-graphics-drivers-treated-as-generic-drivers-.md +++ b/windows-driver-docs-pr/display/windows-8-in-box-graphics-drivers-treated-as-generic-drivers-.md @@ -20,14 +20,14 @@ If the default settings for Windows 8 Windows Update are being used, an Importan When Windows 8 ships, the in-box graphics drivers are significantly older than the latest driver updates on Windows Update. This behavior ensures that the user experiences Windows 8 by using the latest/best graphics driver available. -**Note** +**Note** The Windows 8 certified OEM graphics drivers that is provided on new computers sold with Windows 8 pre-installed are not considered generic. A newer, matching graphics driver on Windows Update would be offered as an Optional update in these cases. The user must actively choose to install an Optional driver update. - + - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[display\display]:%20Windows%208%20in-box%20graphics%20drivers%20treated%20as%20generic%20drivers%20%20%20RELEASE:%20%282/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/display/wireless-displays--miracast-.md b/windows-driver-docs-pr/display/wireless-displays--miracast-.md index 455535c18e..bc2364ff18 100644 --- a/windows-driver-docs-pr/display/wireless-displays--miracast-.md +++ b/windows-driver-docs-pr/display/wireless-displays--miracast-.md @@ -14,7 +14,7 @@ ms.technology: windows-devices Wireless (Miracast) displays can optionally be supported by Windows Display Driver Model (WDDM) 1.3 and later drivers. This capability is new starting with Windows 8.1. -For more information on the requirements of drivers and hardware to support Miracast displays, refer to the [Building best-in-class Miracast solutions with Windows 10](http://download.microsoft.com/download/3/F/9/3F9F0453-04AE-4E4B-87EF-729FF931C1F9/Building best-in-class Miracast solutions with Windows 10.docx) guide and the relevant [WHCK documentation]( http://go.microsoft.com/fwlink/p/?linkid=258342) at **Device.Graphics.WDDM13.DisplayRender.WirelessDisplay**. +For more information on the requirements of drivers and hardware to support Miracast displays, refer to the [Building best-in-class Miracast solutions with Windows 10](http://download.microsoft.com/download/3/F/9/3F9F0453-04AE-4E4B-87EF-729FF931C1F9/Building%20best-in-class%20Miracast%20solutions%20with%20Windows%2010%20.docx) guide and the relevant [WHCK documentation]( http://go.microsoft.com/fwlink/p/?linkid=258342) at **Device.Graphics.WDDM13.DisplayRender.WirelessDisplay**. ## Miracast design guide diff --git a/windows-driver-docs-pr/display/wmv8-a--wmv8-b--wmv9-a--wmv9-b--and-wmv9-c.md b/windows-driver-docs-pr/display/wmv8-a--wmv8-b--wmv9-a--wmv9-b--and-wmv9-c.md index 466eba9ce1..558f0495f1 100644 --- a/windows-driver-docs-pr/display/wmv8-a--wmv8-b--wmv9-a--wmv9-b--and-wmv9-c.md +++ b/windows-driver-docs-pr/display/wmv8-a--wmv8-b--wmv9-a--wmv9-b--and-wmv9-c.md @@ -1,6 +1,6 @@ --- -title: WMV8\_A, WMV8\_B, WMV9\_A, WMV9\_B, and WMV9\_C -description: WMV8\_A, WMV8\_B, WMV9\_A, WMV9\_B, and WMV9\_C +title: WMV8_A, WMV8_B, WMV9_A, WMV9_B, and WMV9_C +description: WMV8_A, WMV8_B, WMV9_A, WMV9_B, and WMV9_C ms.assetid: ffc203e9-fca4-48d3-842b-d9f75ad7caa0 keywords: - WMV8_A restricted profile WDK DirectX VA diff --git a/windows-driver-docs-pr/display/xr-bias-color-channel-conversion-rules.md b/windows-driver-docs-pr/display/xr-bias-color-channel-conversion-rules.md index e92d6e4a28..41f29ab138 100644 --- a/windows-driver-docs-pr/display/xr-bias-color-channel-conversion-rules.md +++ b/windows-driver-docs-pr/display/xr-bias-color-channel-conversion-rules.md @@ -1,6 +1,6 @@ --- -title: XR\_BIAS Color Channel Conversion Rules -description: XR\_BIAS Color Channel Conversion Rules +title: XR_BIAS Color Channel Conversion Rules +description: XR_BIAS Color Channel Conversion Rules ms.assetid: B3014241-A86A-4B6E-BC9D-50057B924D98 --- diff --git a/windows-driver-docs-pr/display/xr-bias-to-float-conversion-rules.md b/windows-driver-docs-pr/display/xr-bias-to-float-conversion-rules.md index 7074690dcf..34791bc052 100644 --- a/windows-driver-docs-pr/display/xr-bias-to-float-conversion-rules.md +++ b/windows-driver-docs-pr/display/xr-bias-to-float-conversion-rules.md @@ -1,6 +1,6 @@ --- -title: XR\_BIAS to Float Conversion Rules -description: XR\_BIAS to Float Conversion Rules +title: XR_BIAS to Float Conversion Rules +description: XR_BIAS to Float Conversion Rules ms.assetid: fef4a1cb-6567-4d8f-aa8a-ceed00eefec8 keywords: - Direct3D version 10.1 WDK Windows 7 display , converting XR_BIAS to float diff --git a/windows-driver-docs-pr/docfx.json b/windows-driver-docs-pr/docfx.json index 0cc4001a41..147d555db9 100644 --- a/windows-driver-docs-pr/docfx.json +++ b/windows-driver-docs-pr/docfx.json @@ -17,7 +17,9 @@ "ROBOTS": "INDEX, FOLLOW", "Search.Product": "eADQiWindows 10XVcnh", "uhfHeaderId": "MSDocsHeader-WinHW", - "breadcrumb_path": "/windows-hardware/drivers/breadcrumbs/toc.json" + "breadcrumb_path": "/windows-hardware/drivers/breadcrumbs/toc.json", + "searchScope": ["Drivers"], + "contributors_to_exclude": ["barrygolden", "PageWriter-MSFT", "tedhudek"] }, "externalReference": [ ], diff --git a/windows-driver-docs-pr/gettingstarted/concepts-and-knowledge-for-all-driver-developers.md b/windows-driver-docs-pr/gettingstarted/concepts-and-knowledge-for-all-driver-developers.md index a79193dc11..617ff6818f 100644 --- a/windows-driver-docs-pr/gettingstarted/concepts-and-knowledge-for-all-driver-developers.md +++ b/windows-driver-docs-pr/gettingstarted/concepts-and-knowledge-for-all-driver-developers.md @@ -25,9 +25,9 @@ In this section: - [Header files in the Windows Driver Kit](header-files-in-the-windows-driver-kit.md) - [Writing drivers for different versions of Windows](platforms-and-driver-versions.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[wdkgetstart\wdkgetstart]:%20Concepts%20%20for%20all%20driver%20developers%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/gettingstarted/extensions-and-driver-triples.md b/windows-driver-docs-pr/gettingstarted/extensions-and-driver-triples.md index 94132abe08..4b51a1b228 100644 --- a/windows-driver-docs-pr/gettingstarted/extensions-and-driver-triples.md +++ b/windows-driver-docs-pr/gettingstarted/extensions-and-driver-triples.md @@ -42,9 +42,9 @@ Here are some examples of event handlers that are implemented by SpbCx.sys - EvtIoRead - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[wdkgetstart\wdkgetstart]:%20KMDF%20extensions%20and%20driver%20triples%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/gettingstarted/kmdf-as-a-generic-pair-model.md b/windows-driver-docs-pr/gettingstarted/kmdf-as-a-generic-pair-model.md index 75f4a7d27c..4f65778e59 100644 --- a/windows-driver-docs-pr/gettingstarted/kmdf-as-a-generic-pair-model.md +++ b/windows-driver-docs-pr/gettingstarted/kmdf-as-a-generic-pair-model.md @@ -66,9 +66,9 @@ In a (KMDF driver, Framework) pair, the Framework handles tasks that are common [Kernel-Mode Driver Framework](https://msdn.microsoft.com/library/windows/hardware/ff557565) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[wdkgetstart\wdkgetstart]:%20KMDF%20as%20a%20generic%20driver%20pair%20model%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/gettingstarted/upper-and-lower-edges-of-drivers.md b/windows-driver-docs-pr/gettingstarted/upper-and-lower-edges-of-drivers.md index 3e5afc6ac3..3dcf6b5683 100644 --- a/windows-driver-docs-pr/gettingstarted/upper-and-lower-edges-of-drivers.md +++ b/windows-driver-docs-pr/gettingstarted/upper-and-lower-edges-of-drivers.md @@ -74,9 +74,9 @@ The terms *upper edge* and *lower edge* are used to describe the interfaces that [Network Drivers Starting with Windows Vista](https://msdn.microsoft.com/library/windows/hardware/ff570021) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[wdkgetstart\wdkgetstart]:%20Upper%20and%20lower%20edges%20of%20drivers%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/gettingstarted/writing-a-very-small-kmdf--driver.md b/windows-driver-docs-pr/gettingstarted/writing-a-very-small-kmdf--driver.md index c672a9d1c9..68eca26593 100644 --- a/windows-driver-docs-pr/gettingstarted/writing-a-very-small-kmdf--driver.md +++ b/windows-driver-docs-pr/gettingstarted/writing-a-very-small-kmdf--driver.md @@ -16,7 +16,7 @@ ms.technology: windows-devices This topic describes how to write a very small [Universal Windows driver](https://msdn.microsoft.com/windows-drivers/develop/getting_started_with_universal_drivers) using Kernel-Mode Driver Framework (KMDF). -To get started, be sure you have [Microsoft Visual Studio2015](https://go.microsoft.com/fwlink/p/?LinkId=698539) and the [Windows Driver Kit (WDK) 10](https://go.microsoft.com/fwlink/p/?LinkId=733614) installed. +To get started, be sure you have [Microsoft Visual Studio 2015](https://go.microsoft.com/fwlink/p/?LinkId=698539) and the [Windows Driver Kit (WDK) 10](https://go.microsoft.com/fwlink/p/?LinkId=733614) installed. [Debugging Tools for Windows](http://go.microsoft.com/fwlink/p?linkid=223405) is included when you install the WDK. @@ -28,9 +28,9 @@ To get started, be sure you have [Microsoft Visual Studio 3. In the middle pane, select **Kernel Mode Driver, Empty (KMDF)**. 4. In the **Name** field, enter "KmdfHelloWorld" for the project name. - **Note**\*When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. + **Note** \*When you create a new KMDF or UMDF driver, you must select a driver name that has 32 characters or less. This length limit is defined in wdfglobals.h. - + 5. In the **Location** field, enter the directory where you want to create the new project. 6. Check **Create directory for solution**. Click **OK**. @@ -46,9 +46,9 @@ To get started, be sure you have [Microsoft Visual Studio 8. In the **Solution Explorer** window, right-click **KmdfHelloWorld** and choose **Add > New Item**. 9. In the **Add New Item** dialog box, select **C++ File**. For **Name**, enter "Driver.c". - **Note**The file name extension is **.c**, not **.cpp**. + **Note** The file name extension is **.c**, not **.cpp**. - + Click **Add**. The Driver.c file is added under Source Files, as shown here. @@ -115,7 +115,7 @@ So far you've used Visual Studio to build a driver on the host computer. Now you ![screen shot showing the kmdfhelloworld package property pages window with the deployment driver install selected ](images/vs2015-kmdf-hello-world-property-pages.png) - **Note**In this exercise, the hardware ID does not identify a real piece of hardware. It identifies an imaginary device that will be given a place in the [device tree](device-nodes-and-device-stacks.md) as a child of the root node. For real hardware, do not select **Hardware ID Driver Update**; instead, select **Install and Verify**. + **Note** In this exercise, the hardware ID does not identify a real piece of hardware. It identifies an imaginary device that will be given a place in the [device tree](device-nodes-and-device-stacks.md) as a child of the root node. For real hardware, do not select **Hardware ID Driver Update**; instead, select **Install and Verify**. You'll see the hardware ID in your driver's information (INF) file. In the **Solution Explorer** window, go to **KmdfHelloWorld > Driver Files**, and double-click KmdfHelloWorld.inf. The hardware ID is located under \[Standard.NT$ARCH$\]. ```ManagedCPlusPlus @@ -123,7 +123,7 @@ So far you've used Visual Studio to build a driver on the host computer. Now you %KmdfHelloWorld.DeviceDesc%=KmdfHelloWorld_Device, Root\KmdfHelloWorld ``` - + 7. On the **Debug** menu, choose **Start Debugging**, or press **F5** on the keyboard. 8. Visual Studio first shows progress in the **Output** window. Then it opens the **Debugger Immediate** window and continues to show progress. @@ -153,9 +153,9 @@ So far you've used Visual Studio to build a driver on the host computer. Now you [Write your first driver](writing-your-first-driver.md) - + - + [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20[wdkgetstart\wdkgetstart]:%20Write%20a%20universal%20Hello%20World%20driver%20%28KMDF%29%20%20RELEASE:%20%281/20/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/gnss/adding-support-for-actual-hardware.md b/windows-driver-docs-pr/gnss/adding-support-for-actual-hardware.md index f8c851b42b..b977d5d36a 100644 --- a/windows-driver-docs-pr/gnss/adding-support-for-actual-hardware.md +++ b/windows-driver-docs-pr/gnss/adding-support-for-actual-hardware.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Adding support for real hardware to the geolocation driver sample +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The geolocation driver sample was provided as a starting point that simulates a GPS device. This topic describes how you can add support for real hardware. diff --git a/windows-driver-docs-pr/gnss/defining-the-geolocation-object.md b/windows-driver-docs-pr/gnss/defining-the-geolocation-object.md index 2224deb55a..f637f07e94 100644 --- a/windows-driver-docs-pr/gnss/defining-the-geolocation-object.md +++ b/windows-driver-docs-pr/gnss/defining-the-geolocation-object.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Defining the geolocation sensor as an object +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The sensors geolocation driver sample treats its simulated geolocation-sensor as an object. This object is declared in the header file named geolocation.h. (For a description of the header file and the other driver sample files refer to [The sample driver file list](the-sample-driver-file-list.md) section.) diff --git a/windows-driver-docs-pr/gnss/initializing-the-geolocation-object.md b/windows-driver-docs-pr/gnss/initializing-the-geolocation-object.md index 28a4f8fdaf..ca46fd672c 100644 --- a/windows-driver-docs-pr/gnss/initializing-the-geolocation-object.md +++ b/windows-driver-docs-pr/gnss/initializing-the-geolocation-object.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Initializing the geolocation object +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The object source file, geolocation.cpp, contains an **Initialize** method that initializes the settable property keys and data-field keys for the simulated geolocation-sensor. This method is invoked by the sensor manager at startup. diff --git a/windows-driver-docs-pr/gnss/installing-the-radio-manager-dll.md b/windows-driver-docs-pr/gnss/installing-the-radio-manager-dll.md index 0ca06b3ed0..2588b4ea29 100644 --- a/windows-driver-docs-pr/gnss/installing-the-radio-manager-dll.md +++ b/windows-driver-docs-pr/gnss/installing-the-radio-manager-dll.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Installing the radio manager DLL +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. To install the radio manager DLL, you’ll need to follow the steps below. diff --git a/windows-driver-docs-pr/gnss/installing-the-sample-driver.md b/windows-driver-docs-pr/gnss/installing-the-sample-driver.md index dd95d20287..5584787e3b 100644 --- a/windows-driver-docs-pr/gnss/installing-the-sample-driver.md +++ b/windows-driver-docs-pr/gnss/installing-the-sample-driver.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Installing the geolocation driver sample +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. Because the geolocation driver sample simulates hardware, there is no Plug-n-Play functionality to automate the installation. Instead, must use a Windows utility, devcon.exe, to install the sample. diff --git a/windows-driver-docs-pr/gnss/sensors-geolocation-driver-sample.md b/windows-driver-docs-pr/gnss/sensors-geolocation-driver-sample.md index b596713f6b..0c94cf056b 100644 --- a/windows-driver-docs-pr/gnss/sensors-geolocation-driver-sample.md +++ b/windows-driver-docs-pr/gnss/sensors-geolocation-driver-sample.md @@ -20,6 +20,8 @@ ms.technology: windows-devices # Geolocation driver sample for Windows 8.1 +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The geolocation sample driver for Windows 8.1 demonstrates a sensor driver for a Global Positioning System (GPS) device. This driver does not connect to hardware; otherwise, it is fully compliant with best practices for building a UMDF sensor driver. Instead of sending real coordinates, this sample simulates a sensor that issues altitude, latitude, longitude, and other simulated GPS data. In addition, this sample issues a timestamp that is useful when testing and debugging. diff --git a/windows-driver-docs-pr/gnss/setting-and-retrieving-the-geolocation-properties.md b/windows-driver-docs-pr/gnss/setting-and-retrieving-the-geolocation-properties.md index c1a57ebb8a..b181659868 100644 --- a/windows-driver-docs-pr/gnss/setting-and-retrieving-the-geolocation-properties.md +++ b/windows-driver-docs-pr/gnss/setting-and-retrieving-the-geolocation-properties.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Setting and retrieving the geolocation properties +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. When an application retrieves a particular property value, a corresponding property-retrieval method is called in the sample driver. For the simulated sensor, this would be **CGeolocation::GetPropertyValuesForGeolocationObject**. The Sensor API will pass the property keys for the properties requested by the application and the driver bundles the property values in an **IPortableDeviceValues** object which it returns to the API. diff --git a/windows-driver-docs-pr/gnss/supporting-radio-management.md b/windows-driver-docs-pr/gnss/supporting-radio-management.md index 8c48fde390..0b78709f86 100644 --- a/windows-driver-docs-pr/gnss/supporting-radio-management.md +++ b/windows-driver-docs-pr/gnss/supporting-radio-management.md @@ -18,6 +18,8 @@ ms.technology: windows-devices # Supporting radio management +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. When the user chooses the Wireless option in PC settings on their Windows 8 laptop, notebook, or tablet, they can turn any connected wireless devices on or off. These wireless devices may include a Wi-Fi antennae or a GPS device. The internal linkage between PC settings and a given wireless device is the [Radio Management API](https://msdn.microsoft.com/library/windows/hardware/hh406615) and a corresponding Radio Management DLL for the given device. diff --git a/windows-driver-docs-pr/gnss/supporting-the-geolocation-properties.md b/windows-driver-docs-pr/gnss/supporting-the-geolocation-properties.md index b68f4f1f51..2b5180a9e7 100644 --- a/windows-driver-docs-pr/gnss/supporting-the-geolocation-properties.md +++ b/windows-driver-docs-pr/gnss/supporting-the-geolocation-properties.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Supporting the geolocation properties +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The source file, geolocation.cpp, contains three arrays of PROPERTYKEY structures that define the properties supported by the simulated sensor. diff --git a/windows-driver-docs-pr/gnss/the-radio-manager-file-list.md b/windows-driver-docs-pr/gnss/the-radio-manager-file-list.md index e52139473e..88a280c36e 100644 --- a/windows-driver-docs-pr/gnss/the-radio-manager-file-list.md +++ b/windows-driver-docs-pr/gnss/the-radio-manager-file-list.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # The radio-manager file list +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The following table describes the files that are found in the radio manager DLL. diff --git a/windows-driver-docs-pr/gnss/the-sample-driver-file-list.md b/windows-driver-docs-pr/gnss/the-sample-driver-file-list.md index 0308155de4..3cdadc3936 100644 --- a/windows-driver-docs-pr/gnss/the-sample-driver-file-list.md +++ b/windows-driver-docs-pr/gnss/the-sample-driver-file-list.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Geolocation sample driver file list +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The source file of the geolocation driver sample includes the following categories of files. diff --git a/windows-driver-docs-pr/gnss/using-the-sensor-class-extension-to-handle-events.md b/windows-driver-docs-pr/gnss/using-the-sensor-class-extension-to-handle-events.md index d21367584e..a09645fb3c 100644 --- a/windows-driver-docs-pr/gnss/using-the-sensor-class-extension-to-handle-events.md +++ b/windows-driver-docs-pr/gnss/using-the-sensor-class-extension-to-handle-events.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Using the sensor class extension to handle events +> [!IMPORTANT] +> This documentation and the geolocation driver sample for Windows 8.1 has been deprecated. The sensor class extension handles the event-linkage between a sensor driver and the Sensor API. diff --git a/windows-driver-docs-pr/gpio/interrupt-synchronization-for-gpio-controller-drivers.md b/windows-driver-docs-pr/gpio/interrupt-synchronization-for-gpio-controller-drivers.md index 241b013580..d33b948ee9 100644 --- a/windows-driver-docs-pr/gpio/interrupt-synchronization-for-gpio-controller-drivers.md +++ b/windows-driver-docs-pr/gpio/interrupt-synchronization-for-gpio-controller-drivers.md @@ -1,7 +1,7 @@ --- title: Interrupt Synchronization for GPIO Controller Drivers author: windows-driver-content -description: GPIO controller drivers can call the GPIO\_CLX\_AcquireInterruptLock and GPIO\_CLX\_ReleaseInterruptLock methods to acquire and release interrupt locks that are implemented internally by the GPIO framework extension (GpioClx). +description: GPIO controller drivers can call the GPIO_CLX_AcquireInterruptLock and GPIO_CLX_ReleaseInterruptLock methods to acquire and release interrupt locks that are implemented internally by the GPIO framework extension (GpioClx). ms.assetid: D9698A50-7CC2-463C-9E46-7FE428F3193E ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/gpio/optional-and-required-gpio-callback-functions.md b/windows-driver-docs-pr/gpio/optional-and-required-gpio-callback-functions.md index 751d682c4b..a405bc4976 100644 --- a/windows-driver-docs-pr/gpio/optional-and-required-gpio-callback-functions.md +++ b/windows-driver-docs-pr/gpio/optional-and-required-gpio-callback-functions.md @@ -1,7 +1,7 @@ --- title: Optional and Required GPIO Callback Functions author: windows-driver-content -description: A general-purpose I/O (GPIO) controller driver calls the GPIO\_CLX\_RegisterClient method to register as a client of the GPIO framework extension (GpioClx). +description: A general-purpose I/O (GPIO) controller driver calls the GPIO_CLX_RegisterClient method to register as a client of the GPIO framework extension (GpioClx). ms.assetid: 2F126431-13AB-4E3F-9E5E-56DC7D9AF024 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/hid/TOC.md b/windows-driver-docs-pr/hid/TOC.md index 2e4c958d61..6a03d99d5c 100644 --- a/windows-driver-docs-pr/hid/TOC.md +++ b/windows-driver-docs-pr/hid/TOC.md @@ -76,4 +76,4 @@ ##### [Axis Selection](axis-selection.md) #### [Force Feedback Device Driver Interface](force-feedback-device-driver-interface.md) #### [Extending the DirectInput Game Controller Control Panel](extending-the-directinput-game-controller-control-panel.md) - +## [Hdpi.h Macros](hdpi-h-macros.md) diff --git a/windows-driver-docs-pr/hid/buttons.md b/windows-driver-docs-pr/hid/buttons.md index 7230789ea1..e6287c0187 100644 --- a/windows-driver-docs-pr/hid/buttons.md +++ b/windows-driver-docs-pr/hid/buttons.md @@ -56,6 +56,7 @@ Here are some general pointers to help you decide which implementation you shoul

If you are implementing a GPIO button, describe the button in the system ACPI so that Windows can load the in-box driver, Hidinterrupt.sys, as the button driver that reports events to the operating system.

  • [ACPI button device](acpi-button-device.md)
  • +
  • [Button Behavior](https://msdn.microsoft.com/en-us/library/windows/hardware/dn457871(v=vs.85).aspx)
  • [Sample buttons ACPI for phone/tablet](acpi-button-device.md#acpi-button-phone)
  • [Sample buttons ACPI for desktop](acpi-button-device.md#acpi-button-desktop)
diff --git a/windows-driver-docs-pr/hid/hdpi-h-macros.md b/windows-driver-docs-pr/hid/hdpi-h-macros.md new file mode 100644 index 0000000000..3e817e062f --- /dev/null +++ b/windows-driver-docs-pr/hid/hdpi-h-macros.md @@ -0,0 +1,90 @@ +--- +title: 'Hdpi.h Macros' +author: windows-driver-content +description: 'Macros contained in the Hdpi.h header.' +--- + +# Hdpi.h Macros + +The Hdpi.h header file contains several macros. +This topic documents the following macros: + +* [**HidP\_GetButtons**](#HidPGetButtons) +* [**HidP\_GetButtonsEx**](#HidPGetButtonsEx) +* [**HidP\_SetButtons**](#HidPSetButtons) +* [**HidP\_UnsetButtons**](#HidPUnsetButtons) + + +## HidP\_GetButtons + + +The **HidP\_GetButtons** macro is a mnemonic alias for the [**HidP\_GetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539742) routine. + +``` +#define HidP_GetButtons(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) \ + HidP_GetUsages(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) +``` + +## HidP\_GetButtonsEx + + +The **HidP\_GetButtonsEx** macro is an mnemonic alias for the [**HidP\_GetUsagesEx**](https://msdn.microsoft.com/library/windows/hardware/ff539745) routine. + +``` +#define HidP_GetButtonsEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe) \ + HidP_GetUsagesEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe) +``` + + +## HidP\_SetButtons + + +The **HidP\_SetButtons** macro is a mnemonic alias for the [**HidP\_SetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539792) routine. + +``` +#define HidP_SetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \ + HidP_SetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) +``` + +## HidP\_UnsetButtons + + +The **HidP\_UnsetButtons** macro is a mnemonic alias for the [**HidP\_UnsetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539819) routine. + +``` +#define HidP_UnsetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \ + HidP_UnsetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) +``` + +Requirements +------------ + + ++++ + + + + + + +

Header

Hidpi.h (include Hidpi.h)
+ +## See also + +[**HidP\_GetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539742) + +[**HidP\_GetUsagesEx**](https://msdn.microsoft.com/library/windows/hardware/ff539745) + +[**HidP\_SetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539792) + +[**HidP\_UnsetUsages**](https://msdn.microsoft.com/library/windows/hardware/ff539819) + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhid\hid%5D:%20Hdpi_Macros%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + + + diff --git a/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-bioses-section.md b/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-bioses-section.md index 83e2ee1561..37bd0460c5 100644 --- a/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-bioses-section.md +++ b/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-bioses-section.md @@ -1,7 +1,7 @@ --- -title: INF PS2\_Inst.NoInterruptInit.Bioses Section +title: INF PS2_Inst.NoInterruptInit.Bioses Section author: windows-driver-content -description: INF PS2\_Inst.NoInterruptInit.Bioses Section +description: INF PS2_Inst.NoInterruptInit.Bioses Section ms.assetid: 2bf1dc0f-00b6-4f4a-99f0-e9843fe6e66b keywords: - INF files WDK non-HID keyboard/mouse diff --git a/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-section.md b/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-section.md index 913675fe25..3b9b515c9c 100644 --- a/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-section.md +++ b/windows-driver-docs-pr/hid/inf-ps2-inst-nointerruptinit-section.md @@ -1,7 +1,7 @@ --- -title: INF PS2\_Inst.NoInterruptInit Section +title: INF PS2_Inst.NoInterruptInit Section author: windows-driver-content -description: INF PS2\_Inst.NoInterruptInit Section +description: INF PS2_Inst.NoInterruptInit Section ms.assetid: e84cc7fc-8b17-4119-84f9-12ac888c68aa keywords: - INF files WDK non-HID keyboard/mouse diff --git a/windows-driver-docs-pr/hid/obtaining-hid-reports-by-kernel-mode-drivers.md b/windows-driver-docs-pr/hid/obtaining-hid-reports-by-kernel-mode-drivers.md index c9a352a158..331b341b5a 100644 --- a/windows-driver-docs-pr/hid/obtaining-hid-reports-by-kernel-mode-drivers.md +++ b/windows-driver-docs-pr/hid/obtaining-hid-reports-by-kernel-mode-drivers.md @@ -1,7 +1,7 @@ --- title: Obtaining HID Reports by Kernel-Mode Drivers author: windows-driver-content -description: This topic discusses how a kernel-mode driver should use IRP\_MJ\_READ requests as its main approach for continuously obtaining HID input reports. +description: This topic discusses how a kernel-mode driver should use IRP_MJ_READ requests as its main approach for continuously obtaining HID input reports. ms.assetid: 017481f1-8021-4fd5-ab8e-f09f6006e616 --- diff --git a/windows-driver-docs-pr/hid/obtaining-hid-reports-by-user-mode-applications.md b/windows-driver-docs-pr/hid/obtaining-hid-reports-by-user-mode-applications.md index 824e521879..5ad7a7d797 100644 --- a/windows-driver-docs-pr/hid/obtaining-hid-reports-by-user-mode-applications.md +++ b/windows-driver-docs-pr/hid/obtaining-hid-reports-by-user-mode-applications.md @@ -1,7 +1,7 @@ --- title: Obtaining HID Reports by User-Mode Applications author: windows-driver-content -description: This topic discusses the obtaining of HID input reports or HID feature reports, by user-mode applications using ReadFile or the HidD\_GetXxx routines. +description: This topic discusses the obtaining of HID input reports or HID feature reports, by user-mode applications using ReadFile or the HidD_GetXxx routines. ms.assetid: 28f560dd-b919-4652-93f6-691051a0ffbe --- diff --git a/windows-driver-docs-pr/hid/virtual-hid-framework--vhf-.md b/windows-driver-docs-pr/hid/virtual-hid-framework--vhf-.md index 8db0a58c73..4d55dacae5 100644 --- a/windows-driver-docs-pr/hid/virtual-hid-framework--vhf-.md +++ b/windows-driver-docs-pr/hid/virtual-hid-framework--vhf-.md @@ -12,7 +12,6 @@ ms.technology: windows-devices # Write a HID source driver by using Virtual HID Framework (VHF) - **Summary** - Write a Kernel-Mode Driver Framework (KMDF)HID source driver that submits HID Read Reports to the operating system. @@ -39,13 +38,10 @@ Starting in Windows 10, the new Virtual HID Framework (VHF) eliminates the need **Note**  In this release, VHF supports a HID source driver only in kernel mode. -  - This topic describes the architecture of the framework, the virtual HID device tree, and the configuration scenarios. ## Virtual HID device tree - In this image, the device tree shows the drivers and their associated device objects. ![virtual hid device tree](images/vhf.png) @@ -68,43 +64,40 @@ The Hidclass/Mshidkmdf pair enumerates [Top-Level Collections (TLC)](top-level-c **Note**  In some scenarios, a HID client might need to identify the source of HID data. For example, a system has a built-in sensor and receives data from a remote sensor of the same type. The system might want to choose one sensor to be more reliable. To differentiate between the two sensors connected to the system, the HID client queries for the container ID of the TLC. In this case, a HID source driver can provide the container ID, which is reported as the container ID of the virtual HID device by VHF. -  - **HID client (application)** Queries and consumes the TLCs that are reported by the HID device stack. ## Header and library requirements - This procedure describes how to write a simple HID source driver that reports headset buttons to the operating system. In this case, the driver that implements this code can be an existing KMDF audio driver that has been modified to act as a HID source reporting headset buttons by using VHF. 1. Include Vhf.h, included in the WDK for Windows 10. 2. Link to Vhflkm.lib, included in the WDK. 3. Create a HID Report Descriptor that your device wants to report to the operating system. In this example, the HID Report Descriptor describes the headset buttons. The report specifies a HID Input Report, size 8 bits (1 byte). The first three bits are for the headset middle, volume-up, and volume-down buttons. The remaining bits are unused. - ``` - UCHAR HeadSetReportDescriptor[] = { - 0x05, 0x01, // USAGE_PAGE (Generic Desktop Controls) - 0x09, 0x0D, // USAGE (Portable Device Buttons) - 0xA1, 0x01, // COLLECTION (Application) - 0x85, 0x01, // REPORT_ID (1) - 0x05, 0x09, // USAGE_PAGE (Button Page) - 0x09, 0x01, // USAGE (Button 1 - HeadSet : middle button) - 0x09, 0x02, // USAGE (Button 2 - HeadSet : volume up button) - 0x09, 0x03, // USAGE (Button 3 - HeadSet : volume down button) - 0x15, 0x00, // LOGICAL_MINIMUM (0) - 0x25, 0x01, // LOGICAL_MAXIMUM (1) - 0x75, 0x01, // REPORT_SIZE (1) - 0x95, 0x03, // REPORT_COUNT (3) - 0x81, 0x02, // INPUT (Data,Var,Abs) - 0x95, 0x05, // REPORT_COUNT (5) - 0x81, 0x03, // INPUT (Cnst,Var,Abs) - 0xC0, // END_COLLECTION - }; - ``` -## Create a virtual HID device +``` +UCHAR HeadSetReportDescriptor[] = { + 0x05, 0x01, // USAGE_PAGE (Generic Desktop Controls) + 0x09, 0x0D, // USAGE (Portable Device Buttons) + 0xA1, 0x01, // COLLECTION (Application) + 0x85, 0x01, // REPORT_ID (1) + 0x05, 0x09, // USAGE_PAGE (Button Page) + 0x09, 0x01, // USAGE (Button 1 - HeadSet : middle button) + 0x09, 0x02, // USAGE (Button 2 - HeadSet : volume up button) + 0x09, 0x03, // USAGE (Button 3 - HeadSet : volume down button) + 0x15, 0x00, // LOGICAL_MINIMUM (0) + 0x25, 0x01, // LOGICAL_MAXIMUM (1) + 0x75, 0x01, // REPORT_SIZE (1) + 0x95, 0x03, // REPORT_COUNT (3) + 0x81, 0x02, // INPUT (Data,Var,Abs) + 0x95, 0x05, // REPORT_COUNT (5) + 0x81, 0x03, // INPUT (Cnst,Var,Abs) + 0xC0, // END_COLLECTION +}; +``` +## Create a virtual HID device Initialize a [**VHF\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/dn925044) structure by calling the [**VHF\_CONFIG\_INIT**](https://msdn.microsoft.com/library/windows/hardware/dn925046) macro and then call the [**VhfCreate**](https://msdn.microsoft.com/library/windows/hardware/dn925036) method. The driver must call **VhfCreate** at PASSIVE\_LEVEL after the [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926) call, typically, in the driver's [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback function. @@ -145,8 +138,6 @@ The virtual HID device is deleted by calling the [**VhfDelete**](https://msdn.mi **Note**  After an asynchronous operation completes, the driver must call [**VhfAsyncOperationComplete**](https://msdn.microsoft.com/library/windows/hardware/dn925060) to set the results of the operation. You can call the method from the event callback or at a later time after returning from the callback. -  - ``` NTSTATUS VhfSourceCreateDevice( @@ -167,7 +158,7 @@ _Inout_ PWDFDEVICE_INIT DeviceInit status = WdfDeviceCreate(&DeviceInit, &deviceAttributes, &device); - if (NT_SUCCESS(status)) + if (NT_SUCCESS(status)) { deviceContext = DeviceGetContext(device); @@ -198,39 +189,38 @@ Error: ## Submit the HID input report - Submit the HID input report by calling [**VhfReadReportSubmit**](https://msdn.microsoft.com/library/windows/hardware/dn925040). Typically, a HID device sends information about state changes by sending input reports through interrupts. For example, the headset device might send a report when the state of a button changes. In such an event, the driver's interrupt service routine (ISR) is invoked. In that routine, the driver might schedule a deferred procedure call (DPC) that processes the input report and submits it to VHF, which sends the information to the operating system. By default, VHF buffers the report and the HID source driver can start submitting HID Input Reports as they come in. This and eliminates the need for the HID source driver to implement complex synchronization. The HID source driver can submit input reports by implementing the buffering policy for pending reports. To avoid duplicate buffering, the HID source driver can implement the [*EvtVhfReadyForNextReadReport*](https://msdn.microsoft.com/library/windows/hardware/dn897135) callback function and keep track of whether VHF invoked this callback. If it was previously invoked, the HID source driver can call [**VhfReadReportSubmit**](https://msdn.microsoft.com/library/windows/hardware/dn925040) to submit a report. It must wait for *EvtVhfReadyForNextReadReport* to get invoked before it can call **VhfReadReportSubmit** again. - ``` - VOID - MY_SubmitReadReport( - PMY_CONTEXT Context, - BUTTON_TYPE ButtonType, - BUTTON_STATE ButtonState - ) - { - PDEVICE_CONTEXT deviceContext = (PDEVICE_CONTEXT)(Context); - if (ButtonState == ButtonStateUp) { - deviceContext->VhfHidReport.ReportBuffer[0] &= ~(0x01 << ButtonType); - } else { - deviceContext->VhfHidReport.ReportBuffer[0] |= (0x01 << ButtonType); - } +``` +VOID +MY_SubmitReadReport( + PMY_CONTEXT Context, + BUTTON_TYPE ButtonType, + BUTTON_STATE ButtonState + ) +{ + PDEVICE_CONTEXT deviceContext = (PDEVICE_CONTEXT)(Context); - status = VhfSubmitReadReport(deviceContext->VhfHandle, &deviceContext->VhfHidReport); + if (ButtonState == ButtonStateUp) { + deviceContext->VhfHidReport.ReportBuffer[0] &= ~(0x01 << ButtonType); + } else { + deviceContext->VhfHidReport.ReportBuffer[0] |= (0x01 << ButtonType); + } - if (!NT_SUCCESS(status)) { - TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,"VhfSubmitReadReport failed %!STATUS!", status); - } + status = VhfSubmitReadReport(deviceContext->VhfHandle, &deviceContext->VhfHidReport); + + if (!NT_SUCCESS(status)) { + TraceEvents(TRACE_LEVEL_ERROR, TRACE_DEVICE,"VhfSubmitReadReport failed %!STATUS!", status); } - ``` +} +``` ## Delete the virtual HID device - Delete the virtual HID device by calling [**VhfDelete**](https://msdn.microsoft.com/library/windows/hardware/dn925038). [**VhfDelete**](https://msdn.microsoft.com/library/windows/hardware/dn925038) can be called synchronous or asynchronously by specifying the Wait parameter. For a synchronous call, the method must be called at PASSIVE\_LEVEL, such as from [*EvtCleanupCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540840) of the device object. **VhfDelete** returns after deleting the virtual HID device. If the driver calls **VhfDelete** asynchronously, it returns immediately and VHF invokes [*EvtVhfCleanup*](https://msdn.microsoft.com/library/windows/hardware/dn897134) after the delete operation is complete. The method can be called at maximum DISPATCH\_LEVEL. In this case, the driver must have registered and implemented an *EvtVhfCleanup* callback function when it previously called [**VhfCreate**](https://msdn.microsoft.com/library/windows/hardware/dn925036). Here is the sequence of events when HID source driver wants to delete the virtual HID device: @@ -262,29 +252,22 @@ _In_ WDFOBJECT DeviceObject } } - ``` ## Install the HID source driver - In the INF file that installs the HID source driver, make sure that you declare Vhf.sys as a lower filter driver to your HID source driver by using the [**AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320). ``` - -[HIDVHF_Inst.NT.HW] -AddReg = HIDVHF_Inst.NT.AddReg - -[HIDVHF_Inst.NT.AddReg] -HKR,,"LowerFilters",0x00010000,"vhf" - - +[HIDVHF_Inst.NT.HW] +AddReg = HIDVHF_Inst.NT.AddReg + +[HIDVHF_Inst.NT.AddReg] +HKR,,"LowerFilters",0x00010000,"vhf" ``` ## Related topics -[Human Interface Device](https://msdn.microsoft.com/library/windows/hardware/ff543301) +[Human Interface Device](https://msdn.microsoft.com/library/windows/hardware/ff543301) -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bhid\hid%5D:%20Write%20a%20HID%20source%20driver%20by%20using%20Virtual%20HID%20Framework%20%28VHF%29%20%20RELEASE:%20%287/18/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") - - diff --git a/windows-driver-docs-pr/ifs/-optional--registering-callback-routines.md b/windows-driver-docs-pr/ifs/-optional--registering-callback-routines.md index 0f7870be5a..7751501a02 100644 --- a/windows-driver-docs-pr/ifs/-optional--registering-callback-routines.md +++ b/windows-driver-docs-pr/ifs/-optional--registering-callback-routines.md @@ -1,7 +1,7 @@ --- -title: '\ Optional\ Registering Callback Routines' +title: '[Optional] Registering Callback Routines' author: windows-driver-content -description: '\ Optional\ Registering Callback Routines' +description: '[Optional] Registering Callback Routines' ms.assetid: 59d15b37-e31e-45fc-bdb0-fed6f791839c keywords: - registering callback routines diff --git a/windows-driver-docs-pr/ifs/-optional--saving-a-copy-of-the-registry-path-string.md b/windows-driver-docs-pr/ifs/-optional--saving-a-copy-of-the-registry-path-string.md index 0686afc45b..c66f95de61 100644 --- a/windows-driver-docs-pr/ifs/-optional--saving-a-copy-of-the-registry-path-string.md +++ b/windows-driver-docs-pr/ifs/-optional--saving-a-copy-of-the-registry-path-string.md @@ -1,7 +1,7 @@ --- -title: '\ Optional\ Saving a Copy of the Registry Path String' +title: '[Optional] Saving a Copy of the Registry Path String' author: windows-driver-content -description: '\ Optional\ Saving a Copy of the Registry Path String' +description: '[Optional] Saving a Copy of the Registry Path String' ms.assetid: cf3b8649-6fb0-4ada-816c-5c7783918b2f keywords: - RegistryPath string copies diff --git a/windows-driver-docs-pr/ifs/adding-auditing-on-irp-mj-create.md b/windows-driver-docs-pr/ifs/adding-auditing-on-irp-mj-create.md index e9788c0573..8ed6c79a2c 100644 --- a/windows-driver-docs-pr/ifs/adding-auditing-on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/adding-auditing-on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Adding Auditing on IRP\_MJ\_CREATE +title: Adding Auditing on IRP_MJ_CREATE author: windows-driver-content -description: Adding Auditing on IRP\_MJ\_CREATE +description: Adding Auditing on IRP_MJ_CREATE ms.assetid: cb71fe83-44f4-48dd-8fff-250f1d27c123 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/allocated-altitudes.md b/windows-driver-docs-pr/ifs/allocated-altitudes.md index 8329bc0417..17ae97d940 100644 --- a/windows-driver-docs-pr/ifs/allocated-altitudes.md +++ b/windows-driver-docs-pr/ifs/allocated-altitudes.md @@ -269,6 +269,7 @@ The current altitude allocations are listed for each of the following load order | Backupreader.sys | 385500 | Microsoft | | AppVMon.sys | 385400 | Microsoft | | DpmFilter.sys | 385300 | Microsoft | +| Sysmondrv.sys | 385201 | Microsoft | | Procmon11.sys | 385200 | Microsoft | | minispy.sys - Top | 385100 | Microsoft | | fdrtrace.sys | 385001 | Microsoft | diff --git a/windows-driver-docs-pr/ifs/anti-virus-optimization-for-windows-containers.md b/windows-driver-docs-pr/ifs/anti-virus-optimization-for-windows-containers.md index c4d33dc263..44001a73f7 100644 --- a/windows-driver-docs-pr/ifs/anti-virus-optimization-for-windows-containers.md +++ b/windows-driver-docs-pr/ifs/anti-virus-optimization-for-windows-containers.md @@ -15,7 +15,7 @@ ms.technology: windows-devices **Applies to:** - Windows 10, version 1607 -- Windows Server 2016 Technical Preview +- Windows Server 2016 - AV products running on the Host This topic describes optimizations that anti-virus products can utilize to avoid redundant scanning of Windows Container files and help improve Container start up time. diff --git a/windows-driver-docs-pr/ifs/assigning-security-to-a-new-file-on-irp-mj-create.md b/windows-driver-docs-pr/ifs/assigning-security-to-a-new-file-on-irp-mj-create.md index 9bb82d41d3..883d755ff8 100644 --- a/windows-driver-docs-pr/ifs/assigning-security-to-a-new-file-on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/assigning-security-to-a-new-file-on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Assigning Security to a New File on IRP\_MJ\_CREATE +title: Assigning Security to a New File on IRP_MJ_CREATE author: windows-driver-content -description: Assigning Security to a New File on IRP\_MJ\_CREATE +description: Assigning Security to a New File on IRP_MJ_CREATE ms.assetid: f01a09c4-f71f-4b9e-99c8-9bc7ca5ca316 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/attaching-ecps-to-irp-mj-create-operations-that-a-kernel-mode-driver-o.md b/windows-driver-docs-pr/ifs/attaching-ecps-to-irp-mj-create-operations-that-a-kernel-mode-driver-o.md index 19cd64eff4..85ed6c44c3 100644 --- a/windows-driver-docs-pr/ifs/attaching-ecps-to-irp-mj-create-operations-that-a-kernel-mode-driver-o.md +++ b/windows-driver-docs-pr/ifs/attaching-ecps-to-irp-mj-create-operations-that-a-kernel-mode-driver-o.md @@ -1,7 +1,7 @@ --- title: Attach ECPs to IRP_MJ_CREATE Operations that a Kernel-Mode Driver Originated author: windows-driver-content -description: Attaching ECPs to IRP\_MJ\_CREATE Operations that a Kernel-Mode Driver Originated +description: Attaching ECPs to IRP_MJ_CREATE Operations that a Kernel-Mode Driver Originated ms.assetid: 87daa861-b0d5-4877-bf16-fad120108de6 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/ifs/checking-for-other-special-cases--on-irp-mj-create.md b/windows-driver-docs-pr/ifs/checking-for-other-special-cases--on-irp-mj-create.md index 3744efe8ae..2f6a05835b 100644 --- a/windows-driver-docs-pr/ifs/checking-for-other-special-cases--on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/checking-for-other-special-cases--on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Checking for Other Special Cases on IRP\_MJ\_CREATE +title: Checking for Other Special Cases on IRP_MJ_CREATE author: windows-driver-content -description: Checking for Other Special Cases on IRP\_MJ\_CREATE +description: Checking for Other Special Cases on IRP_MJ_CREATE ms.assetid: e6af44c2-fd39-469b-8530-cf88edb329f7 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/checking-for-traverse-privilege-on-irp-mj-create.md b/windows-driver-docs-pr/ifs/checking-for-traverse-privilege-on-irp-mj-create.md index a4760abbaf..95fc21a5c1 100644 --- a/windows-driver-docs-pr/ifs/checking-for-traverse-privilege-on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/checking-for-traverse-privilege-on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Checking for Traverse Privilege on IRP\_MJ\_CREATE +title: Checking for Traverse Privilege on IRP_MJ_CREATE author: windows-driver-content -description: Checking for Traverse Privilege on IRP\_MJ\_CREATE +description: Checking for Traverse Privilege on IRP_MJ_CREATE ms.assetid: 9ba743d6-8e78-4f9a-9cb8-cb98f734c290 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/clearing-the-do-device-initializing-flag.md b/windows-driver-docs-pr/ifs/clearing-the-do-device-initializing-flag.md index 53f8312b3b..a063a6c11a 100644 --- a/windows-driver-docs-pr/ifs/clearing-the-do-device-initializing-flag.md +++ b/windows-driver-docs-pr/ifs/clearing-the-do-device-initializing-flag.md @@ -1,7 +1,7 @@ --- -title: Clearing the DO\_DEVICE\_INITIALIZING Flag +title: Clearing the DO_DEVICE_INITIALIZING Flag author: windows-driver-content -description: Clearing the DO\_DEVICE\_INITIALIZING Flag +description: Clearing the DO_DEVICE_INITIALIZING Flag ms.assetid: 1c1cca60-bb95-4a8d-9e17-4db54983bbb0 keywords: - filter drivers WDK file system , attaching filters diff --git a/windows-driver-docs-pr/ifs/handling-quotas-on-irp-mj-create.md b/windows-driver-docs-pr/ifs/handling-quotas-on-irp-mj-create.md index 3e698419b8..ad2de029de 100644 --- a/windows-driver-docs-pr/ifs/handling-quotas-on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/handling-quotas-on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Handling Quotas on IRP\_MJ\_CREATE +title: Handling Quotas on IRP_MJ_CREATE author: windows-driver-content -description: Handling Quotas on IRP\_MJ\_CREATE +description: Handling Quotas on IRP_MJ_CREATE ms.assetid: 71cf5e78-c87a-48fe-ba0b-f5efe8166525 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/irp-mj-create-dispatch-routine.md b/windows-driver-docs-pr/ifs/irp-mj-create-dispatch-routine.md index dbba062564..83ee001def 100644 --- a/windows-driver-docs-pr/ifs/irp-mj-create-dispatch-routine.md +++ b/windows-driver-docs-pr/ifs/irp-mj-create-dispatch-routine.md @@ -1,7 +1,7 @@ --- -title: IRP\_MJ\_CREATE Dispatch Routine +title: IRP_MJ_CREATE Dispatch Routine author: windows-driver-content -description: IRP\_MJ\_CREATE Dispatch Routine +description: IRP_MJ_CREATE Dispatch Routine ms.assetid: 1ff7915a-0949-43fe-9cf4-c0ad9abf6592 keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/irp-mj-directory-control2.md b/windows-driver-docs-pr/ifs/irp-mj-directory-control2.md index 07ebc511ac..e8730a42dc 100644 --- a/windows-driver-docs-pr/ifs/irp-mj-directory-control2.md +++ b/windows-driver-docs-pr/ifs/irp-mj-directory-control2.md @@ -1,7 +1,7 @@ --- -title: IRP\_MJ\_DIRECTORY\_CONTROL +title: IRP_MJ_DIRECTORY_CONTROL author: windows-driver-content -description: IRP\_MJ\_DIRECTORY\_CONTROL +description: IRP_MJ_DIRECTORY_CONTROL ms.assetid: 27c2de1c-5550-4211-97cc-4c66f18d3b99 keywords: - IRP_MJ_DIRECTORY_CONTROL diff --git a/windows-driver-docs-pr/ifs/irp-mj-query-security-and-irp-mj-set-security.md b/windows-driver-docs-pr/ifs/irp-mj-query-security-and-irp-mj-set-security.md index 3e8d2bef08..4ec6dd524a 100644 --- a/windows-driver-docs-pr/ifs/irp-mj-query-security-and-irp-mj-set-security.md +++ b/windows-driver-docs-pr/ifs/irp-mj-query-security-and-irp-mj-set-security.md @@ -1,7 +1,7 @@ --- -title: IRP\_MJ\_QUERY\_SECURITY and IRP\_MJ\_SET\_SECURITY +title: IRP_MJ_QUERY_SECURITY and IRP_MJ_SET_SECURITY author: windows-driver-content -description: IRP\_MJ\_QUERY\_SECURITY and IRP\_MJ\_SET\_SECURITY +description: IRP_MJ_QUERY_SECURITY and IRP_MJ_SET_SECURITY ms.assetid: 64216496-55f0-4ad4-b475-341ed9eb6886 keywords: - IRP_MJ_QUERY_SECURITY diff --git a/windows-driver-docs-pr/ifs/irp-mj-set-information3.md b/windows-driver-docs-pr/ifs/irp-mj-set-information3.md index 63146f234f..6b17c9e910 100644 --- a/windows-driver-docs-pr/ifs/irp-mj-set-information3.md +++ b/windows-driver-docs-pr/ifs/irp-mj-set-information3.md @@ -1,7 +1,7 @@ --- -title: IRP\_MJ\_SET\_INFORMATION +title: IRP_MJ_SET_INFORMATION author: windows-driver-content -description: IRP\_MJ\_SET\_INFORMATION +description: IRP_MJ_SET_INFORMATION ms.assetid: 2a6c837c-85c9-46d8-85d8-d779f22be54e keywords: - IRP_MJ_SET_INFORMATION diff --git a/windows-driver-docs-pr/ifs/management-of-access-control-lists-on-irp-mj-create.md b/windows-driver-docs-pr/ifs/management-of-access-control-lists-on-irp-mj-create.md index 4c90741068..c423db612d 100644 --- a/windows-driver-docs-pr/ifs/management-of-access-control-lists-on-irp-mj-create.md +++ b/windows-driver-docs-pr/ifs/management-of-access-control-lists-on-irp-mj-create.md @@ -1,7 +1,7 @@ --- -title: Management of Access Control Lists on IRP\_MJ\_CREATE +title: Management of Access Control Lists on IRP_MJ_CREATE author: windows-driver-content -description: Management of Access Control Lists on IRP\_MJ\_CREATE +description: Management of Access Control Lists on IRP_MJ_CREATE ms.assetid: 07b35931-8e20-4789-b2ef-14c6195b817f keywords: - IRP_MJ_CREATE diff --git a/windows-driver-docs-pr/ifs/propagating-the-do-buffered-io-and-do-direct-io-flags.md b/windows-driver-docs-pr/ifs/propagating-the-do-buffered-io-and-do-direct-io-flags.md index cbf1564e58..7ef587a7cc 100644 --- a/windows-driver-docs-pr/ifs/propagating-the-do-buffered-io-and-do-direct-io-flags.md +++ b/windows-driver-docs-pr/ifs/propagating-the-do-buffered-io-and-do-direct-io-flags.md @@ -1,7 +1,7 @@ --- -title: Propagating the DO\_BUFFERED\_IO and DO\_DIRECT\_IO Flags +title: Propagating the DO_BUFFERED_IO and DO_DIRECT_IO Flags author: windows-driver-content -description: Propagating the DO\_BUFFERED\_IO and DO\_DIRECT\_IO Flags +description: Propagating the DO_BUFFERED_IO and DO_DIRECT_IO Flags ms.assetid: a0cb4f1a-3c27-4608-a208-ffcf4113b722 keywords: - filter drivers WDK file system , attaching filters diff --git a/windows-driver-docs-pr/ifs/propagating-the-file-device-secure-open-flag.md b/windows-driver-docs-pr/ifs/propagating-the-file-device-secure-open-flag.md index f550387cc7..c5973dd8c2 100644 --- a/windows-driver-docs-pr/ifs/propagating-the-file-device-secure-open-flag.md +++ b/windows-driver-docs-pr/ifs/propagating-the-file-device-secure-open-flag.md @@ -1,7 +1,7 @@ --- -title: Propagating the FILE\_DEVICE\_SECURE\_OPEN Flag +title: Propagating the FILE_DEVICE_SECURE_OPEN Flag author: windows-driver-content -description: Propagating the FILE\_DEVICE\_SECURE\_OPEN Flag +description: Propagating the FILE_DEVICE_SECURE_OPEN Flag ms.assetid: cbc254ab-3ac6-44aa-bb16-16d701d5ada7 keywords: - filter drivers WDK file system , attaching filters diff --git a/windows-driver-docs-pr/ifs/returning-flt-preop-success-no-callback.md b/windows-driver-docs-pr/ifs/returning-flt-preop-success-no-callback.md index 325f9efa43..77e54c5ea5 100644 --- a/windows-driver-docs-pr/ifs/returning-flt-preop-success-no-callback.md +++ b/windows-driver-docs-pr/ifs/returning-flt-preop-success-no-callback.md @@ -1,7 +1,7 @@ --- -title: Returning FLT\_PREOP\_SUCCESS\_NO\_CALLBACK +title: Returning FLT_PREOP_SUCCESS_NO_CALLBACK author: windows-driver-content -description: Returning FLT\_PREOP\_SUCCESS\_NO\_CALLBACK +description: Returning FLT_PREOP_SUCCESS_NO_CALLBACK ms.assetid: cde708b0-b572-4444-ba4b-158b6906884e keywords: - FLT_PREOP_SUCCESS_NO_CALLBACK diff --git a/windows-driver-docs-pr/ifs/returning-flt-preop-success-with-callback.md b/windows-driver-docs-pr/ifs/returning-flt-preop-success-with-callback.md index 43845f6dfa..e4754d647d 100644 --- a/windows-driver-docs-pr/ifs/returning-flt-preop-success-with-callback.md +++ b/windows-driver-docs-pr/ifs/returning-flt-preop-success-with-callback.md @@ -1,7 +1,7 @@ --- -title: Returning FLT\_PREOP\_SUCCESS\_WITH\_CALLBACK +title: Returning FLT_PREOP_SUCCESS_WITH_CALLBACK author: windows-driver-content -description: Returning FLT\_PREOP\_SUCCESS\_WITH\_CALLBACK +description: Returning FLT_PREOP_SUCCESS_WITH_CALLBACK ms.assetid: 6247b952-3189-4792-a15b-c3a4b3dc80ae keywords: - FLT_PREOP_SUCCESS_WITH_CALLBACK diff --git a/windows-driver-docs-pr/ifs/returning-flt-preop-synchronize.md b/windows-driver-docs-pr/ifs/returning-flt-preop-synchronize.md index cb3f957253..8e360a2ee7 100644 --- a/windows-driver-docs-pr/ifs/returning-flt-preop-synchronize.md +++ b/windows-driver-docs-pr/ifs/returning-flt-preop-synchronize.md @@ -1,7 +1,7 @@ --- -title: Returning FLT\_PREOP\_SYNCHRONIZE +title: Returning FLT_PREOP_SYNCHRONIZE author: windows-driver-content -description: Returning FLT\_PREOP\_SYNCHRONIZE +description: Returning FLT_PREOP_SYNCHRONIZE ms.assetid: b1331f8d-e230-45b2-be1b-f85d85557350 keywords: - FLT_PREOP_SYNCHRONIZE diff --git a/windows-driver-docs-pr/ifs/rx-context-and-irp-management.md b/windows-driver-docs-pr/ifs/rx-context-and-irp-management.md index f9f9f3c373..020dadee61 100644 --- a/windows-driver-docs-pr/ifs/rx-context-and-irp-management.md +++ b/windows-driver-docs-pr/ifs/rx-context-and-irp-management.md @@ -1,7 +1,7 @@ --- -title: RX\_CONTEXT and IRP Management +title: RX_CONTEXT and IRP Management author: windows-driver-content -description: RX\_CONTEXT and IRP Management +description: RX_CONTEXT and IRP Management ms.assetid: 74ca681d-2599-442c-aebe-3556d6354f7f keywords: - RDBSS WDK file systems , IRPs diff --git a/windows-driver-docs-pr/ifs/the-srv-call-structure.md b/windows-driver-docs-pr/ifs/the-srv-call-structure.md index d641a7f323..53b8b76789 100644 --- a/windows-driver-docs-pr/ifs/the-srv-call-structure.md +++ b/windows-driver-docs-pr/ifs/the-srv-call-structure.md @@ -1,7 +1,7 @@ --- -title: The SRV\_CALL Structure +title: The SRV_CALL Structure author: windows-driver-content -description: The SRV\_CALL Structure +description: The SRV_CALL Structure ms.assetid: 9a3bb194-0289-47f4-a5c8-848d8d82cdd7 keywords: - SRV_CALL structure diff --git a/windows-driver-docs-pr/ifs/the-srv-open-structure.md b/windows-driver-docs-pr/ifs/the-srv-open-structure.md index 4aed1c674d..0e5354d6dc 100644 --- a/windows-driver-docs-pr/ifs/the-srv-open-structure.md +++ b/windows-driver-docs-pr/ifs/the-srv-open-structure.md @@ -1,7 +1,7 @@ --- -title: The SRV\_OPEN Structure +title: The SRV_OPEN Structure author: windows-driver-content -description: The SRV\_OPEN Structure +description: The SRV_OPEN Structure ms.assetid: 6cf4c6f6-a21f-4919-92b5-2403b650d8d0 keywords: - server open WDK RDBSS diff --git a/windows-driver-docs-pr/ifs/the-v-net-root-structure.md b/windows-driver-docs-pr/ifs/the-v-net-root-structure.md index bc18fabaa3..c2b3c26077 100644 --- a/windows-driver-docs-pr/ifs/the-v-net-root-structure.md +++ b/windows-driver-docs-pr/ifs/the-v-net-root-structure.md @@ -1,7 +1,7 @@ --- -title: The V\_NET\_ROOT Structure +title: The V_NET_ROOT Structure author: windows-driver-content -description: The V\_NET\_ROOT Structure +description: The V_NET_ROOT Structure ms.assetid: 866eba91-13b6-4b15-93de-4f627a635c92 keywords: - share mapping WDK RDBSS diff --git a/windows-driver-docs-pr/ifs/using-ecps-to-process-irp-mj-create-operations-in-a-file-system-filter.md b/windows-driver-docs-pr/ifs/using-ecps-to-process-irp-mj-create-operations-in-a-file-system-filter.md index b609920e78..09975af122 100644 --- a/windows-driver-docs-pr/ifs/using-ecps-to-process-irp-mj-create-operations-in-a-file-system-filter.md +++ b/windows-driver-docs-pr/ifs/using-ecps-to-process-irp-mj-create-operations-in-a-file-system-filter.md @@ -1,7 +1,7 @@ --- title: Using ECPs to Process IRP_MJ_CREATE in File System Filter Drivers author: windows-driver-content -description: Using ECPs to Process IRP\_MJ\_CREATE Operations in a File System Filter Driver +description: Using ECPs to Process IRP_MJ_CREATE Operations in a File System Filter Driver ms.assetid: 969709a9-cdca-4a1a-95a0-0bb89cd17693 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/ifs/using-extra-create-parameters-with-an-irp-mj-create-operation.md b/windows-driver-docs-pr/ifs/using-extra-create-parameters-with-an-irp-mj-create-operation.md index f8e7c571d4..2cca19e4dc 100644 --- a/windows-driver-docs-pr/ifs/using-extra-create-parameters-with-an-irp-mj-create-operation.md +++ b/windows-driver-docs-pr/ifs/using-extra-create-parameters-with-an-irp-mj-create-operation.md @@ -1,7 +1,7 @@ --- -title: Using Extra Create Parameters with an IRP\_MJ\_CREATE Operation +title: Using Extra Create Parameters with an IRP_MJ_CREATE Operation author: windows-driver-content -description: Using Extra Create Parameters with an IRP\_MJ\_CREATE Operation +description: Using Extra Create Parameters with an IRP_MJ_CREATE Operation ms.assetid: e32aeec6-1a0a-4d21-8358-89d9fc0a15eb ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/image/challenging-a-disconnected-scanner-with-the-wsd-challenger.md b/windows-driver-docs-pr/image/challenging-a-disconnected-scanner-with-the-wsd-challenger.md index 5551d25c6b..b27a8dc3c2 100644 --- a/windows-driver-docs-pr/image/challenging-a-disconnected-scanner-with-the-wsd-challenger.md +++ b/windows-driver-docs-pr/image/challenging-a-disconnected-scanner-with-the-wsd-challenger.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Challenging a Disconnected Scanner with the WSD Challenger +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. A web services scanner driver can challenge a disconnected scanner to reestablish communication with the device when the scanner comes back online. To challenge a disconnected scanner, the driver uses the WSD Challenger DLL (*WSDCHNGR.DLL*) that is provided with Windows Vista. The Windows Image Acquisition (WIA) Service also uses *WSDCHNGR.DLL* to actively monitor all WSDScan scanner devices and enable drivers to respond to a challenge following a device communication failure. diff --git a/windows-driver-docs-pr/image/code-example-for-challenging-a-potentially-disconnected-device.md b/windows-driver-docs-pr/image/code-example-for-challenging-a-potentially-disconnected-device.md index 48931045cc..ce688cfc25 100644 --- a/windows-driver-docs-pr/image/code-example-for-challenging-a-potentially-disconnected-device.md +++ b/windows-driver-docs-pr/image/code-example-for-challenging-a-potentially-disconnected-device.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Code Example for Challenging a Potentially Disconnected Device +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. The following code example shows a call to the **RegisterDeviceToChallenge** function (which is listed in the code example in [Sample Code for Implementing Helper Methods](code-example-for-implementing-helper-methods.md)) to challenge a potentially disconnected device. diff --git a/windows-driver-docs-pr/image/code-example-for-implementing-helper-methods.md b/windows-driver-docs-pr/image/code-example-for-implementing-helper-methods.md index cc30a202e2..d000120bd3 100644 --- a/windows-driver-docs-pr/image/code-example-for-implementing-helper-methods.md +++ b/windows-driver-docs-pr/image/code-example-for-implementing-helper-methods.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Code Example for Implementing Helper Methods +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. The following code example shows the implementation of the helper methods that are used to initialize the WSD Challenge interface and register the device challenge. diff --git a/windows-driver-docs-pr/image/creating-a--hello-world--wia-minidriver-ui-extension.md b/windows-driver-docs-pr/image/creating-a--hello-world--wia-minidriver-ui-extension.md index 0fb356aba5..d46f670744 100644 --- a/windows-driver-docs-pr/image/creating-a--hello-world--wia-minidriver-ui-extension.md +++ b/windows-driver-docs-pr/image/creating-a--hello-world--wia-minidriver-ui-extension.md @@ -1,7 +1,7 @@ --- title: Creating a "Hello World" WIA Minidriver UI Extension author: windows-driver-content -description: Creating a \ 0034;Hello World \ 0034; WIA Minidriver UI Extension +description: Creating a "Hello World" WIA Minidriver UI Extension ms.assetid: 8de1f8ca-f618-44d7-b6dd-c02cdee8a556 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/image/definitions-and-variables-used-in-the-examples.md b/windows-driver-docs-pr/image/definitions-and-variables-used-in-the-examples.md index 804f7c2781..e76d2f2e69 100644 --- a/windows-driver-docs-pr/image/definitions-and-variables-used-in-the-examples.md +++ b/windows-driver-docs-pr/image/definitions-and-variables-used-in-the-examples.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Definitions and Variables Used in the Examples +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. The following code shows constant definitions and common variables that are used in the code examples in this section. diff --git a/windows-driver-docs-pr/image/esc-twain-capability-escape-code.md b/windows-driver-docs-pr/image/esc-twain-capability-escape-code.md index 101e7be966..f44ef5d90a 100644 --- a/windows-driver-docs-pr/image/esc-twain-capability-escape-code.md +++ b/windows-driver-docs-pr/image/esc-twain-capability-escape-code.md @@ -1,7 +1,7 @@ --- -title: ESC\_TWAIN\_CAPABILITY Escape Code +title: ESC_TWAIN_CAPABILITY Escape Code author: windows-driver-content -description: ESC\_TWAIN\_CAPABILITY Escape Code +description: ESC_TWAIN_CAPABILITY Escape Code ms.assetid: 3fd3f03b-ea72-4151-a19c-3e71cf3193fa ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/image/esc-twain-private-supported-caps-escape-code.md b/windows-driver-docs-pr/image/esc-twain-private-supported-caps-escape-code.md index b124a0d7b7..4739cd56eb 100644 --- a/windows-driver-docs-pr/image/esc-twain-private-supported-caps-escape-code.md +++ b/windows-driver-docs-pr/image/esc-twain-private-supported-caps-escape-code.md @@ -1,7 +1,7 @@ --- -title: ESC\_TWAIN\_PRIVATE\_SUPPORTED\_CAPS Escape Code +title: ESC_TWAIN_PRIVATE_SUPPORTED_CAPS Escape Code author: windows-driver-content -description: ESC\_TWAIN\_PRIVATE\_SUPPORTED\_CAPS Escape Code +description: ESC_TWAIN_PRIVATE_SUPPORTED_CAPS Escape Code ms.assetid: 99b9f180-018b-47c4-ab8d-dc037e3f637a ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/image/macro-example-to-filter-error-codes.md b/windows-driver-docs-pr/image/macro-example-to-filter-error-codes.md index 68ab5a0a48..b074fdf898 100644 --- a/windows-driver-docs-pr/image/macro-example-to-filter-error-codes.md +++ b/windows-driver-docs-pr/image/macro-example-to-filter-error-codes.md @@ -12,6 +12,8 @@ ms.technology: windows-devices # Macro Example to Filter Error Codes +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. The following macro example filters communication failure error codes. @@ -29,8 +31,6 @@ The following macro example filters communication failure error codes.   -  - -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bimage\image%5D:%20Macro%20Example%20to%20Filter%20Error%20Codes%20%20RELEASE:%20%288/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/image/ptp-driver.md b/windows-driver-docs-pr/image/ptp-driver.md index 92e64446d9..e73903e2ab 100644 --- a/windows-driver-docs-pr/image/ptp-driver.md +++ b/windows-driver-docs-pr/image/ptp-driver.md @@ -4,7 +4,7 @@ author: windows-driver-content description: PTP Driver ms.assetid: c8bfdea9-0778-498f-a87d-d2766c9c02cc ms.author: windowsdriverdev -ms.date: 04/20/2017 +ms.date: 08/9/2017 ms.topic: article ms.prod: windows-hardware ms.technology: windows-devices @@ -12,13 +12,11 @@ ms.technology: windows-devices # PTP Driver +The Picture Transfer Protocol (PTP) driver enables PTP devices to support the WIA driver model. -## +This driver is written using the WIA architecture and adheres to Picture Transfer Protocol (PTP) standard. - -The Picture Transfer Protocol (PTP) driver enables PTP devices to support the WIA driver model. This driver is written using the WIA architecture and adheres to the PIMA 15740:2000 standard, First Edition, and Revision 1.0 of the USB Still Image Capture Device Definition (USB SICDD). - -Several terms used in the PIMA 15740:2000, First Edition standard are used in this documentation: StorageInfo dataset, ObjectInfo dataset, and DeviceInfo dataset. Refer to the I3A PTP-Picture Transfer Protocol standard on the [I3A IT10 Electronic Still Picture Imaging](http://www.i3a.org/technologies/digitalimaging/ptp/) website for definitions of these structures. +Refer to the [ISO 15740:2013 Picture transfer protocol](http://go.microsoft.com/fwlink/p/?LinkId=517024) website for definitions of these structures. This section covers the following topics: @@ -45,8 +43,6 @@ This section covers the following topics:     - - -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bimage\image%5D:%20PTP%20Driver%20%20RELEASE:%20%288/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/image/ptp-references.md b/windows-driver-docs-pr/image/ptp-references.md index 4fd9ce20a8..0e32ea19c6 100644 --- a/windows-driver-docs-pr/image/ptp-references.md +++ b/windows-driver-docs-pr/image/ptp-references.md @@ -12,19 +12,13 @@ ms.technology: windows-devices # PTP References - -## - - -I3A PTP-Picture Transfer Protocol standard on the [I3A IT10 Electronic Still Picture Imaging](http://go.microsoft.com/fwlink/p/?LinkId=517024) website. +Picture Transfer Protocol (PTP) standard on the [ISO 15740:2013 Picture transfer protocol](http://go.microsoft.com/fwlink/p/?LinkId=517024) website. *Universal Serial Bus Still Image Capture Device Definition*, *Revision 1.0*, July 11, 2000 on the [USB.org Documents](http://go.microsoft.com/fwlink/p/?LinkId=517016) website.     - - -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bimage\image%5D:%20PTP%20References%20%20RELEASE:%20%288/17/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/image/wia-ips-deskew-x-and-wia-ips-deskew-y-properties.md b/windows-driver-docs-pr/image/wia-ips-deskew-x-and-wia-ips-deskew-y-properties.md index ccec33b4ce..feeef620d7 100644 --- a/windows-driver-docs-pr/image/wia-ips-deskew-x-and-wia-ips-deskew-y-properties.md +++ b/windows-driver-docs-pr/image/wia-ips-deskew-x-and-wia-ips-deskew-y-properties.md @@ -1,7 +1,7 @@ --- -title: WIA\_IPS\_DESKEW\_X and WIA\_IPS\_DESKEW\_Y Properties +title: WIA_IPS_DESKEW_X and WIA_IPS_DESKEW_Y Properties author: windows-driver-content -description: WIA\_IPS\_DESKEW\_X and WIA\_IPS\_DESKEW\_Y Properties +description: WIA_IPS_DESKEW_X and WIA_IPS_DESKEW_Y Properties ms.assetid: 748b08f7-e838-4df8-abcb-4ff1cdd20f7e ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/image/wia-with-web-services-for-devices.md b/windows-driver-docs-pr/image/wia-with-web-services-for-devices.md index 5218333763..4c7c0cdde0 100644 --- a/windows-driver-docs-pr/image/wia-with-web-services-for-devices.md +++ b/windows-driver-docs-pr/image/wia-with-web-services-for-devices.md @@ -17,7 +17,12 @@ In Windows Vista and later versions of Windows, the operating system supports ne The WSD Scan driver is an inbox Microsoft Windows Image Acquisition (WIA) class driver for web services scanners. This driver is compliant with the Windows Device Protocol (WDP) for scanners and is new with Windows Vista. -The WSD Scan driver package contains a reusable kernel driver component, *WSDScan.sys*, that is intended specifically to install web services scanner devices. Windows Vista also includes the *WSD Challenger*, which is a module that enables web services clients to challenge disconnected devices to reestablish device communication when the device comes back online. +The WSD Scan driver package contains a reusable kernel driver component, *WSDScan.sys*, that is intended specifically to install web services scanner devices. + +Windows Vista also includes the *WSD Challenger*, which is a module that enables web services clients to challenge disconnected devices to reestablish device communication when the device comes back online. + +> [!IMPORTANT] +> WSD Challenger functionality has been deprecated and all WSD Challenger-related documentation will be removed in 2018. The following sections describe how to use *WSDScan.sys* to install a WIA driver for a web services scanner, how to use function discovery to initialize SOAP communications with the scanner device from within the WIA driver, and how to challenge a disconnected device by using the WSD Challenger: diff --git a/windows-driver-docs-pr/fish.png b/windows-driver-docs-pr/images/fish.png similarity index 100% rename from windows-driver-docs-pr/fish.png rename to windows-driver-docs-pr/images/fish.png diff --git a/windows-driver-docs-pr/install/--registry-subkey.md b/windows-driver-docs-pr/install/--registry-subkey.md index 3cd06ceb01..91f3c29d25 100644 --- a/windows-driver-docs-pr/install/--registry-subkey.md +++ b/windows-driver-docs-pr/install/--registry-subkey.md @@ -1,6 +1,6 @@ --- -title: '\ Registry Subkey' -description: '\ Registry Subkey' +title: '* Registry Subkey' +description: '* Registry Subkey' ms.assetid: 19b72c64-5a64-4655-b922-4a4bca162b32 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/TOC.md b/windows-driver-docs-pr/install/TOC.md index aff6133ee8..dd1d9ff444 100644 --- a/windows-driver-docs-pr/install/TOC.md +++ b/windows-driver-docs-pr/install/TOC.md @@ -34,8 +34,9 @@ ### [INF Files](inf-files.md) #### [Overview of INF Files](overview-of-inf-files.md) ##### [Looking at an INF File](looking-at-an-inf-file.md) -##### [Using a Universal INF File](using-a-configurable-inf-file.md) -##### [Using an Extension INF File](creating-an-extensible-inf-file.md) +##### [Using a Universal INF File](using-a-universal-inf-file.md) +##### [Using an Extension INF File](using-an-extension-inf-file.md) +##### [Updating Device Firmware using Windows Update](updating-device-firmware-using-windows-update.md) ##### [Summary of INF Sections](summary-of-inf-sections.md) ##### [Summary of INF Directives](summary-of-inf-directives.md) ##### [General Guidelines for INF Files](general-guidelines-for-inf-files.md) @@ -74,6 +75,7 @@ ####### [Trusted Root Certification Authorities Certificate Store](trusted-root-certification-authorities-certificate-store.md) ####### [Trusted Publishers Certificate Store](trusted-publishers-certificate-store.md) ##### [Kernel-Mode Code Signing Policy](kernel-mode-code-signing-policy--windows-vista-and-later-.md) +#### [Windows 10 S Driver Requirements](Windows10SDriverRequirements.md) #### [Managing the Signing Process](managing-the-signing-process.md) ##### [Selecting the Appropriate Signature Type](selecting-the-appropriate-signature-type.md) ###### [Kernel-Mode Code Signing Requirements](kernel-mode-code-signing-requirements--windows-vista-and-later-.md) @@ -280,6 +282,8 @@ ### [Updating Driver Files](updating-driver-files.md) ## [Device and Driver Installation Advanced Topics](device-and-driver-installation-advanced-topics.md) ### [Creating Secure Device Installations](creating-secure-device-installations.md) +### [Using a Component INF File](using-a-component-inf-file.md) +### [Pairing a driver with a Universal Windows Platform (UWP) app](pairing-app-and-driver-versions.md) ### [Device Identification and Properties](device-identification-and-properties.md) #### [Device Identification](device-identification.md) ##### [Device Identification Strings](device-identification-strings.md) @@ -514,6 +518,7 @@ ## [Early Launch AntiMalware](early-launch-antimalware.md) ### [ELAM Prerequisites](elam-prerequisites.md) ### [ELAM Driver Requirements](elam-driver-requirements.md) +### [ELAM Driver Submission](elam-driver-submission.md) ## [INF File Sections and Directives](inf-file-sections-and-directives.md) ### [INF Sections](inf-sections.md) #### [INF ClassInstall32 Section](inf-classinstall32-section.md) @@ -521,11 +526,13 @@ #### [INF ControlFlags Section](inf-controlflags-section.md) #### [INF DDInstall Section](inf-ddinstall-section.md) #### [INF DDInstall.CoInstallers Section](inf-ddinstall-coinstallers-section.md) +#### [INF DDInstall.Components Section](inf-ddinstall-components-section.md) #### [INF DDInstall.FactDef Section](inf-ddinstall-factdef-section.md) #### [INF DDInstall.HW Section](inf-ddinstall-hw-section.md) #### [INF DDInstall.Interfaces Section](inf-ddinstall-interfaces-section.md) #### [INF DDInstall.LogConfigOverride Section](inf-ddinstall-logconfigoverride-section.md) #### [INF DDInstall.Services Section](inf-ddinstall-services-section.md) +#### [INF DDInstall.Software Section](inf-ddinstall-software-section.md) #### [INF DDInstall.WMI Section](inf-ddinstall-wmi-section.md) #### [INF DefaultInstall Section](inf-defaultinstall-section.md) #### [INF DefaultInstall.Services Section](inf-defaultinstall-services-section.md) @@ -539,11 +546,13 @@ #### [INF Strings Section](inf-strings-section.md) #### [INF Version Section](inf-version-section.md) ### [INF Directives](inf-directives.md) +#### [INF AddComponent Directive](inf-addcomponent-directive.md) #### [INF AddInterface Directive](inf-addinterface-directive.md) #### [INF AddPowerSetting Directive](inf-addpowersetting-directive.md) #### [INF AddProperty Directive](inf-addproperty-directive.md) #### [INF AddReg Directive](inf-addreg-directive.md) #### [INF AddService Directive](inf-addservice-directive.md) +#### [INF AddSoftware Directive](inf-addsoftware-directive.md) #### [INF BitReg Directive](inf-bitreg-directive.md) #### [INF CopyFiles Directive](inf-copyfiles-directive.md) #### [INF CopyINF Directive](inf-copyinf-directive.md) @@ -563,4 +572,3 @@ #### [INF UnregisterDlls Directive](inf-unregisterdlls-directive.md) #### [INF UpdateIniFields Directive](inf-updateinifields-directive.md) #### [INF UpdateInis Directive](inf-updateinis-directive.md) - diff --git a/windows-driver-docs-pr/install/Windows10SDriverRequirements.md b/windows-driver-docs-pr/install/Windows10SDriverRequirements.md new file mode 100644 index 0000000000..afd033adcd --- /dev/null +++ b/windows-driver-docs-pr/install/Windows10SDriverRequirements.md @@ -0,0 +1,59 @@ +--- +title: Windows 10 S Driver Requirements +ms.author: windowsdriverdev +ms.date: 05/05/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Windows 10 S Driver Requirements + +This section describes driver installation requirements and blocked components on Windows 10 S. + +## Driver Requirements + +To install on Windows 10 S, driver packages must meet the following requirements: + +- Driver packages must be digitally signed with a **Windows, WHQL, ELAM, or Store** certificate from the [Windows Hardware Developer Center Dashboard](https://aka.ms/DevCenterPortal). +- Companion software must be signed with a [Windows Store Certificate](https://docs.microsoft.com/windows/uwp/publish/the-app-certification-process). +- Does not include an \*.exe, \*.zip, \*.msi or \*.cab in the driver package that extracts unsigned binaries. +- Driver installs using only INF directives. +- Co-installers are used only to install or register signed binaries, and do not contain user interface components. (*Only allowed until Fall Creators update) +- Driver does not call [blocked inbox components](#blocked-inbox-components). +- Drivers does not include any user interface components, apps, or settings. Instead, use Universal applications from the Windows Store, for example: + * [Hardware Support Apps](https://docs.microsoft.com/windows-hardware/drivers/devapps/hardware-access-for-universal-windows-platform-apps) + * [Windows Store Device Apps](https://docs.microsoft.com/windows-hardware/drivers/devapps/meet-windows-store-device-apps) + * [Centennial Apps](https://developer.microsoft.com/windows/bridges/desktop) +- Driver and firmware servicing uses Windows Update and not an updater app. + +Finally, we recommend using a Universal Windows driver where possible. For more info, see: + +- [Getting Started with Universal Drivers](https://docs.microsoft.com/windows-hardware/drivers/develop/getting-started-with-universal-drivers) +- [Validating Universal Drivers](https://docs.microsoft.com/windows-hardware/drivers/develop/validating-universal-driver) + +## Blocked inbox components + +The following components are blocked from executing on Windows 10 S: + +- bash.exe +- cdb.exe +- cmd.exe +- cscript.exe +- csi.exe +- dnx.exe +- kd.exe +- lxssmanager.dll +- msbuild.exe +- ntsd.exe +- powershell.exe +- powershell\_ise.exe +- rcsi.exe +- reg.exe +- regedt32.exe +- windbg.exe +- wmic.exe +- wscript.exe + +> [!NEXT] +> To ensure your Windows app will operate correctly on devices that run Windows 10 S, please review the [test guidance](https://docs.microsoft.com/en-us/windows/uwp/porting/desktop-to-uwp-test-windows-s) for apps. diff --git a/windows-driver-docs-pr/install/accessing-device-instance-spdrp-xxx-properties.md b/windows-driver-docs-pr/install/accessing-device-instance-spdrp-xxx-properties.md index f1b17a1ad7..114c46c4f8 100644 --- a/windows-driver-docs-pr/install/accessing-device-instance-spdrp-xxx-properties.md +++ b/windows-driver-docs-pr/install/accessing-device-instance-spdrp-xxx-properties.md @@ -1,6 +1,6 @@ --- -title: Accessing Device Instance SPDRP\_Xxx Properties -description: Accessing Device Instance SPDRP\_Xxx Properties +title: Accessing Device Instance SPDRP_Xxx Properties +description: Accessing Device Instance SPDRP_Xxx Properties ms.assetid: 15ee51f8-1904-43ee-8bc2-311688c860e0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/accessing-the-registry-by-class-installers-and-co-installers.md b/windows-driver-docs-pr/install/accessing-the-registry-by-class-installers-and-co-installers.md index 596de77440..008425d915 100644 --- a/windows-driver-docs-pr/install/accessing-the-registry-by-class-installers-and-co-installers.md +++ b/windows-driver-docs-pr/install/accessing-the-registry-by-class-installers-and-co-installers.md @@ -20,7 +20,7 @@ This section provides guidelines that [*class installers*](https://msdn.microsof [Modifying Registry Values by Class Installers and Co-installers](modifying-registry-values-by-class-installers-and-co-installers.md) -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/authenticode-signing-of-csps.md b/windows-driver-docs-pr/install/authenticode-signing-of-csps.md index ffb665850b..ff2c84995c 100644 --- a/windows-driver-docs-pr/install/authenticode-signing-of-csps.md +++ b/windows-driver-docs-pr/install/authenticode-signing-of-csps.md @@ -30,7 +30,7 @@ You can sign binaries from a command-line, or sign as an integrated build step i The command to [**SignTool**](https://msdn.microsoft.com/library/windows/hardware/ff551778) is: -``` syntax +``` signtool.exe sign /ac /sha1 /t /d <”optional_description_in_double_quotes”> ``` @@ -42,7 +42,7 @@ signtool.exe sign /ac /sha1 /t \ ``` @@ -162,12 +163,12 @@ The driver must meet the performance requirements defined in the following table Once the boot drivers are evaluated by the ELAM driver, the Kernel uses the classification returned by ELAM to decide whether to initialize the driver. This decision is dictated by policy and is stored here in the registry at: -``` syntax +``` HKLM\System\CurrentControlSet\Control\EarlyLaunch\DriverLoadPolicy ``` This can be configured through Group Policy on a domain-joined client. An antimalware solution may want to expose this functionality to the end user in nonmanaged scenarios. The following values are defined for DriverLoadPolicy: -``` syntax +``` PNP_INITIALIZE_DRIVERS_DEFAULT 0x0 (initializes known Good drivers only) PNP_INITIALIZE_UNKNOWN_DRIVERS 0x1 PNP_INITIALIZE_BAD_CRITICAL_DRIVERS 0x3 (this is the default setting) @@ -184,7 +185,7 @@ If a boot driver is skipped due to the initialization policy, the Kernel continu When the ELAM driver is installed, a backup copy of the driver must also be installed. The back-up location will be stored in the **BackupPath** key stored in -``` syntax +``` HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\EarlyLaunch ``` @@ -195,7 +196,7 @@ In the event of a failure to load or initialize the primary driver due to a corr If the ELAM driver detects a policy violation (a rootkit, for example), it can invalidate the PCRs that indicated that the system was in a good state by using the Tbsi\_Revoke\_Attestation() function: -``` syntax +``` TBS_RESULT WINAPI Tbsi_Revoke_Attestation(); ``` diff --git a/windows-driver-docs-pr/install/elam-driver-submission.md b/windows-driver-docs-pr/install/elam-driver-submission.md new file mode 100644 index 0000000000..6bd9454db8 --- /dev/null +++ b/windows-driver-docs-pr/install/elam-driver-submission.md @@ -0,0 +1,21 @@ +--- +title: ELAM Prerequisites +description: Early Launch Antimalware (ELAM) drivers can be submitted using the listed steps to ensure validation and adherence to documented requirements +ms.assetid: +ms.author: windowsdriverdev +ms.date: 04/27/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- +# ELAM driver submission Process + +The following steps can be used to submit an Early Launch Antimalware (ELAM) driver: + +1. Ensure your driver adheres to the documented requirements for ELAM drivers. Be sure to update the INF to include the **[SignatureAttributes]** section for the ELAM driver you are submitting. See [ELAM driver requirements](https://msdn.microsoft.com/windows/hardware/drivers/install/elam-driver-requirements) and [INF SignatureAttributes Section](https://msdn.microsoft.com/windows/hardware/drivers/install/inf-signatureattributes-section) for more information. + +2. Validate your driver using the Hardware Logo Kit (HLK) and Hardware Certification Kit (HCK). If your driver will be used in Windows 8 as well as Windows 10, you need to run both versions of the kit. Include the results with your submission. See [HLK tools technical reference](https://msdn.microsoft.com/library/windows/hardware/dn939924) for more information. For information about required HCK tests, see [ELAM Prerequisites](https://docs.microsoft.com/windows-hardware/drivers/install/elam-prerequisites) + +3. Follow the kernel mode driver signing policy as stated in the [Driver signing policy](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/kernel-mode-code-signing-policy--windows-vista-and-later-) topic. + +4. Submit the driver package for evaluation at the [Windows Hardware Dev Center](https://developer.microsoft.com/en-us/windows) diff --git a/windows-driver-docs-pr/install/elam-prerequisites.md b/windows-driver-docs-pr/install/elam-prerequisites.md index 5ef1296e57..573cd0f16b 100644 --- a/windows-driver-docs-pr/install/elam-prerequisites.md +++ b/windows-driver-docs-pr/install/elam-prerequisites.md @@ -17,12 +17,12 @@ Early Launch Antimalware drivers must adhere to the following program requiremen ## Antimalware Vendor Participation Requirements -Microsoft requires that Early Launch Antimalware vendors be members of the Microsoft Virus Initiative (MVI). This membership ensures that the vendors are active antimalware community participants with a positive industry reputation. Please reach out to wscisv@microsoft.com if you have any questions about ELAM driver signing. +Microsoft requires that Early Launch Antimalware vendors either be members of the [**Microsoft Virus Initiative (MVI)**](https://www.microsoft.com/en-us/wdsi/alliances/virus-initiative) or pre-approved members of the [**Virus Information Alliance (VIA)**](https://www.microsoft.com/en-us/wdsi/alliances/virus-information-alliance). This membership ensures that the vendors are active antimalware community participants with a positive industry reputation. Please reach out to [**mvi@microsoft.com**](mailto:mvi@microsoft.com) if you have questions about ELAM driver signing or becoming a pre-approved VIA member. ## Hardware Certification Kit Tests -Each driver must pass the following HCK tests, which are administered by the ISV: +Each driver targeting a pre-Windows 10 operating system must pass the following HCK tests, which are administered by the ISV: PERFORMANCE TEST - CALLBACK LATENCY - Each early launch AM driver is required to return the driver verification callbacks from the kernel within .5ms. This time is measured from when the kernel issues the callback to the driver to the time the driver returns the callback. @@ -43,11 +43,8 @@ The AM driver must be a single binary (not import any other DLLs). ## Windows Hardware Quality Lab (WHQL) submission - -- The ISV submits the driver package, along with its HCK test results, to the **WHQL** Portal. A parameter of the submission is an indication that the driver is an early launch driver. -- The **WHQL** process verifies that the vendor is permitted to submit early launch drivers, and it verifies that the driver has passed its HCK tests. -- The **WHQL** process creates a code signing catalog for the driver package. -- **WHQL** returns to the vendor the signed catalog as well as the driver’s binaries signed by a special code signing certificate. +-   Submit your driver for verification as documented at [ELAM Driver Submission](elam-driver-submission.md) +- The **WHQL** process will verify that the vendor is permitted to submit early launch drivers. Your submission will fail if you are not an MVI member, or a pre-approved VIA member.   diff --git a/windows-driver-docs-pr/install/finish-install-actions--windows-vista-and-later-.md b/windows-driver-docs-pr/install/finish-install-actions--windows-vista-and-later-.md index 39350e9155..b2b3e5712b 100644 --- a/windows-driver-docs-pr/install/finish-install-actions--windows-vista-and-later-.md +++ b/windows-driver-docs-pr/install/finish-install-actions--windows-vista-and-later-.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Finish-Install Actions -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-control-registry-tree.md b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-control-registry-tree.md index 2ef14385f9..961ec25b13 100644 --- a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-control-registry-tree.md +++ b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-control-registry-tree.md @@ -1,6 +1,6 @@ --- -title: HKLM\\SYSTEM\\CurrentControlSet\\Control Registry Tree -description: HKLM\\SYSTEM\\CurrentControlSet\\Control Registry Tree +title: HKLM\SYSTEM\CurrentControlSet\Control Registry Tree +description: HKLM\SYSTEM\CurrentControlSet\Control registry tree contains information for controlling system startup and some aspects of device configuration. ms.assetid: 58eacd32-425d-4224-8d37-21e2caf124cf ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-enum-registry-tree.md b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-enum-registry-tree.md index 1ddc6212ce..ee539d0bd1 100644 --- a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-enum-registry-tree.md +++ b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-enum-registry-tree.md @@ -1,6 +1,6 @@ --- -title: HKLM\\SYSTEM\\CurrentControlSet\\Enum Registry Tree -description: HKLM\\SYSTEM\\CurrentControlSet\\Enum Registry Tree +title: HKLM\SYSTEM\CurrentControlSet\Enum Registry Tree +description: The HKLM\SYSTEM\CurrentControlSet\Enum registry tree contains information about the devices on the system. ms.assetid: 9de3ca54-d23f-4ee6-a638-27e52a60dfdd ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-hardwareprofiles-registry-tree.md b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-hardwareprofiles-registry-tree.md index a7dc85d484..0c579c6a34 100644 --- a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-hardwareprofiles-registry-tree.md +++ b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-hardwareprofiles-registry-tree.md @@ -1,6 +1,6 @@ --- -title: HKLM\\SYSTEM\\CurrentControlSet\\HardwareProfiles Registry Tree -description: HKLM\\SYSTEM\\CurrentControlSet\\HardwareProfiles Registry Tree +title: HKLM\SYSTEM\CurrentControlSet\HardwareProfiles Registry Tree +description: HKLM\SYSTEM\CurrentControlSet\HardwareProfiles registry tree contains information about the hardware profiles on the system. ms.assetid: 548d7a50-b3b1-4413-8898-9ed13bcbdcfc ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-services-registry-tree.md b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-services-registry-tree.md index ac8b55d8c7..f680934916 100644 --- a/windows-driver-docs-pr/install/hklm-system-currentcontrolset-services-registry-tree.md +++ b/windows-driver-docs-pr/install/hklm-system-currentcontrolset-services-registry-tree.md @@ -1,6 +1,6 @@ --- -title: HKLM\\SYSTEM\\CurrentControlSet\\Services Registry Tree -description: HKLM\\SYSTEM\\CurrentControlSet\\Services Registry Tree +title: HKLM\SYSTEM\CurrentControlSet\Services Registry Tree +description: HKLM\SYSTEM\CurrentControlSet\Services registry tree stores information about each service on the system. ms.assetid: c966b029-8171-4db7-9fbb-3a4222ff184b ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/how-the-dmrc-determines-when-to-search-the-wmis-server.md b/windows-driver-docs-pr/install/how-the-dmrc-determines-when-to-search-the-wmis-server.md index 722d147f9b..708477d0f8 100644 --- a/windows-driver-docs-pr/install/how-the-dmrc-determines-when-to-search-the-wmis-server.md +++ b/windows-driver-docs-pr/install/how-the-dmrc-determines-when-to-search-the-wmis-server.md @@ -30,7 +30,7 @@ This registry value indicates the number of days that the DMRC waits before it r The **CheckBackMDNotRetrieved** value is located under the following registry key: -``` syntax +``` HKLM\Software\Microsoft\Windows\CurrentVersion\Device Metadata ``` @@ -47,7 +47,7 @@ This registry value indicates the number of days that the DMRC waits before it q The **CheckBackMDRetrieved** value is located under the following registry key: -``` syntax +``` HKLM\Software\Microsoft\Windows\CurrentVersion\Device Metadata ``` diff --git a/windows-driver-docs-pr/install/images/component-device-hierarchy.png b/windows-driver-docs-pr/install/images/component-device-hierarchy.png new file mode 100644 index 0000000000..335f433c03 Binary files /dev/null and b/windows-driver-docs-pr/install/images/component-device-hierarchy.png differ diff --git a/windows-driver-docs-pr/install/images/extension-base-inf-example.png b/windows-driver-docs-pr/install/images/extension-base-inf-example.png new file mode 100644 index 0000000000..716119be9b Binary files /dev/null and b/windows-driver-docs-pr/install/images/extension-base-inf-example.png differ diff --git a/windows-driver-docs-pr/install/images/extension-component-inf-hierarchy.png b/windows-driver-docs-pr/install/images/extension-component-inf-hierarchy.png new file mode 100644 index 0000000000..c9fac4d706 Binary files /dev/null and b/windows-driver-docs-pr/install/images/extension-component-inf-hierarchy.png differ diff --git a/windows-driver-docs-pr/install/images/single-devnode.png b/windows-driver-docs-pr/install/images/single-devnode.png new file mode 100644 index 0000000000..7af434e7a7 Binary files /dev/null and b/windows-driver-docs-pr/install/images/single-devnode.png differ diff --git a/windows-driver-docs-pr/install/images/two-devnodes.png b/windows-driver-docs-pr/install/images/two-devnodes.png new file mode 100644 index 0000000000..49f7763cc0 Binary files /dev/null and b/windows-driver-docs-pr/install/images/two-devnodes.png differ diff --git a/windows-driver-docs-pr/install/inf-addcomponent-directive.md b/windows-driver-docs-pr/install/inf-addcomponent-directive.md new file mode 100644 index 0000000000..e2e5b4b6c1 --- /dev/null +++ b/windows-driver-docs-pr/install/inf-addcomponent-directive.md @@ -0,0 +1,69 @@ +--- +title: INF AddComponent Directive +description: An AddComponent directive creates a software component device underneath the current device. +ms.author: windowsdriverdev +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# INF AddComponent Directive + +An **AddComponent** directive is used within an [**INF *DDInstall*.Components**](inf-ddinstall-components-section.md) section of an [extension INF file](using-an-extension-inf-file.md). It creates a virtual child device for the software component under the current device. This directive is supported for Windows 10 version 1703 and later. + +``` +[DDInstall.Components] + +AddComponent=ComponentName,[flags],component-install-section +``` + +## Entries + +*ComponentName* + +Specifies the name of the software component to create. Each **AddComponent** directive in an INF file must have a unique value. + +*flags* + +Specifies one or more (ORed) flags, currently undefined but reserved for future use. + +*component-install-section* + +References an INF-writer-defined section that contains information for creating the named software component for this device. + +## Remarks + +Each INF-writer-created section name must be unique within the INF file and must follow the general rules for defining section names. For more information about these rules, see [General Syntax Rules for INF Files](general-syntax-rules-for-inf-files.md). + +An **AddComponent** directive must reference a named *component-install-section* elsewhere in the INF file. Each such section has the following form: + +``` +[component-install-section] + +ComponentIDs=component-id[,component-id] … +[Description=description] +``` + +Each *component-install-section* must have at least the **ComponentIDs** entry as shown here. However, the remaining entries are optional. + +Note that **ComponentIDs** are [HardwareIDs](hardware-ids.md), which means they are strings defined by the hardware developer. To ensure uniqueness of these IDs, in most cases, we recommend following the identifier schema used for [PCI devices](identifiers-for-pci-devices.md). It is possible that a vendor might want to use a different schema, but that depends on the scenario. + +## Component-Install Section Entries and Values + +**ComponentIDs**=*id1[, id2] … [, idN]* + +Specifies the component identifiers for a software component. Component IDs work the same way that Hardware IDs do, and should follow [similar formatting](hardware-ids.md). For a software component, the system prepends the INF-supplied values with `SWC\` to create the Hardware IDs. For example, a **ComponentIDs** value of `VID0001&PID0001` results in a hardware ID of `SWC\VID0001&PID0001`. + +**Description**=*description* + +Optionally specifies a string that describes the software component, typically for localization, expressed as a %strkey% token defined in an [INF Strings section](inf-strings-section.md). + +If a description string contains any %strkey% tokens, each token can represent a maximum of 511 characters. The total string, after any string token substitutions, should not exceed 1024 characters. + +## See Also + +[Using a Component INF File](using-a-component-inf-file.md). + +[*DDInstall*.**Components**](inf-ddinstall-components-section.md) + +[INF AddSoftware Directive](inf-addsoftware-directive.md) diff --git a/windows-driver-docs-pr/install/inf-addinterface-directive.md b/windows-driver-docs-pr/install/inf-addinterface-directive.md index 126cfeb064..8e5b290635 100644 --- a/windows-driver-docs-pr/install/inf-addinterface-directive.md +++ b/windows-driver-docs-pr/install/inf-addinterface-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices One or more **AddInterface** directives can be specified within an [**INF DDInstall.Interfaces section**](inf-ddinstall-interfaces-section.md). This directive installs device-specific support for [device interface classes](device-interface-classes.md) exported to higher level components, such as other drivers or applications. The directive typically references an *add-interface-section* , which sets up registry information for the device-specific instance of the device interface class. -``` syntax +``` [DDInstall.Interfaces] AddInterface={InterfaceClassGUID} [,[reference-string] [,[add-interface-section][,flags]]] @@ -60,7 +60,7 @@ Each **AddInterface** directive in an [**INF DDInstall.Interfaces section**](inf An *add-interface-section* referenced by the **AddInterface** directive has the following form: -``` syntax +``` [add-interface-section] AddReg=add-registry-section[, add-registry-section]... diff --git a/windows-driver-docs-pr/install/inf-addpowersetting-directive.md b/windows-driver-docs-pr/install/inf-addpowersetting-directive.md index e3613094c2..6e032b7c06 100644 --- a/windows-driver-docs-pr/install/inf-addpowersetting-directive.md +++ b/windows-driver-docs-pr/install/inf-addpowersetting-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices An **AddPowerSetting** directive references one or more sections that are used to modify or create power setting information. Each *add-power-setting-section* defines a power setting, the allowed values for the power setting, the friendly name of the power setting, and the description of the power setting. An *add-power-setting-section* also specifies the default value for each power scheme personality. For more information about power settings and power scheme personalities, see [Managing Device Performance States](https://msdn.microsoft.com/library/windows/hardware/ff554353). -``` syntax +``` [DDInstall] | [DDInstall.HW] | [DDInstall.CoInstallers] | @@ -45,7 +45,7 @@ An *add-power-setting-section* takes one of the following two possible forms: - If the allowed power settings values can best be defined as a set of two or more discrete values, use a list of **Value** directives to specify the allowed values, as follows: - ``` syntax + ``` [add-power-setting-section] [SubGroup = {subgroup-guid}] | SubGroup = {subgroup-guid}, subgroup-name, subgroup-description, subgroup-icon @@ -63,7 +63,7 @@ An *add-power-setting-section* takes one of the following two possible forms: - If the allowed power settings values can best be defined as an incremented sequence of nonnegative integer values within a specified range, use one **ValueRange** directive to specify allowed values, as follows: - ``` syntax + ``` [add-power-setting-section] [SubGroup = {subgroup-guid}] | @@ -171,7 +171,7 @@ A required entry that supplies the data for the corresponding setting value, the **ValueRange** Use the **ValueRange** directive if the allowed power settings values can best be defined as an incremented sequence of non-negative integer values within a specified range. The power manager validates that a setting that a user selects in **Power Options** in Control Panel is one of these allowed values. The set of allowed values is determined by a minimum allowed value, a maximum allowed value, and an increment between the allowed values within the range. A value is allowed if it satisfies the following: -``` syntax +``` range-minimum-value + k*range-increment ``` @@ -239,7 +239,7 @@ Except for *value-data* entries of type REG\_SZ, all the other string entry valu Language-neutral registry values are used to support Windows Multilingual User Interface (MUI) and are specified as follows: -``` syntax +``` "@file-path,-resourceID[;comment]" ``` diff --git a/windows-driver-docs-pr/install/inf-addproperty-directive.md b/windows-driver-docs-pr/install/inf-addproperty-directive.md index 60cd53a875..36dee06c52 100644 --- a/windows-driver-docs-pr/install/inf-addproperty-directive.md +++ b/windows-driver-docs-pr/install/inf-addproperty-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices An **AddProperty** directive references one or more INF file sections that modify the [device properties](device-properties.md) that are set for a device instance, a [device setup class](device-setup-classes.md), a [device interface class](device-interface-classes.md), or a device interface. -``` syntax +``` [DDInstall] | [DDInstall.nt] | [DDInstall.ntx86] | @@ -51,7 +51,7 @@ Each *add-property-section* can have entries to do the following: An *add-property-section* that is referenced by an **AddProperty** directive has the following format: -``` syntax +``` [add-property-section] (property-name, , , [flags], value]) | ({property-category-guid}, property-pid, type, [flags], value) diff --git a/windows-driver-docs-pr/install/inf-addreg-directive.md b/windows-driver-docs-pr/install/inf-addreg-directive.md index 73c5951beb..a991a119c3 100644 --- a/windows-driver-docs-pr/install/inf-addreg-directive.md +++ b/windows-driver-docs-pr/install/inf-addreg-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices An **AddReg** directive references one or more INF-writer-defined *add-registry-sections* that are used to modify or create registry information. -``` syntax +``` [DDInstall] | [DDInstall.HW] | [DDInstall.CoInstallers] | @@ -45,7 +45,7 @@ Each *add-registry section* can have entries to do the following: Each named *add-registry section* referenced by an **AddReg** directive has the following format: -``` syntax +``` [add-registry-section] reg-root, [subkey],[value-entry-name],[flags],[value][,[value]] reg-root, [subkey],[value-entry-name],[flags],[value][,[value]] @@ -206,7 +206,7 @@ This technique can be used to define new registry types for numeric values, but Special keywords are defined for use in the HKR **AddReg** entries. The format for the entries that use these keywords is as follows: -``` syntax +``` [HKR,,DeviceCharacteristics,0x10001,characteristics] [HKR,,DeviceType,0x10001,device-type] [HKR,,Security,,security-descriptor-string] @@ -226,7 +226,7 @@ A **DeviceCharacteristics** HKR **AddReg** entry specifies characteristics for t Only the following values can be specified in an INF: -``` syntax +``` #define FILE_REMOVABLE_MEDIA 0x00000001 #define FILE_READ_ONLY_DEVICE 0x00000002 #define FILE_FLOPPY_DISKETTE 0x00000004 diff --git a/windows-driver-docs-pr/install/inf-addservice-directive.md b/windows-driver-docs-pr/install/inf-addservice-directive.md index 27a362deb2..61470aa843 100644 --- a/windows-driver-docs-pr/install/inf-addservice-directive.md +++ b/windows-driver-docs-pr/install/inf-addservice-directive.md @@ -26,7 +26,7 @@ ms.technology: windows-devices An **AddService** directive is used within an [**INF *DDInstall*.Services section**](inf-ddinstall-services-section.md) or [**INF DefaultInstall.Services section**](inf-defaultinstall-services-section.md). It specifies characteristics of the services associated with drivers, such as how and when the services are loaded, and any dependencies on other underlying legacy drivers or services. Optionally, this directive also sets up event-logging services for the device. -``` syntax +``` [DDInstall.Services] AddService=ServiceName,[flags],service-install-section @@ -101,7 +101,7 @@ Each INF-writer-created section name must be unique within the INF file and must An **AddService** directive must reference a named *service-install-section* elsewhere in the INF file. Each such section has the following form: -``` syntax +``` [service-install-section] [DisplayName=name] @@ -265,7 +265,7 @@ Depending on the boot scenario, you can use the **BootFlags** registry value to The *service-install-section* has the following general form: -``` syntax +``` [service-install-section] AddReg=add-registry-section ... @@ -278,7 +278,7 @@ HKR,,BootFlags,0x00010003,0x14 ; CM_SERVICE_USB3_DISK_BOOT_LOAD|CM_SERVICE_USB_D An **AddService** directive can also reference an *event-log-install-section* elsewhere in the INF file. Each such section has the following form: -``` syntax +``` [event-log-install-section] AddReg=add-registry-section[, add-registry-section]... @@ -289,7 +289,7 @@ AddReg=add-registry-section[, add-registry-section]... For a typical device/driver INF file, the *event-log-install-section* uses only the **AddReg** directive to set up an event-logging message file for the driver. An **HKR** specification in an *add-registry-section* designates the **HKLM\\System\\CurrentControlSet\\Services\\EventLog\\***EventLogType***\\***EventName* registry key. This event-logging *add-registry-section* has the following general form: -``` syntax +``` [drivername_EventLog_AddReg] HKR,,EventMessageFile,0x00020000,"path\IoLogMsg.dll;path\driver.sys" HKR,,TypesSupported,0x00010001,7 diff --git a/windows-driver-docs-pr/install/inf-addsoftware-directive.md b/windows-driver-docs-pr/install/inf-addsoftware-directive.md new file mode 100644 index 0000000000..3f7fd60b56 --- /dev/null +++ b/windows-driver-docs-pr/install/inf-addsoftware-directive.md @@ -0,0 +1,130 @@ +--- +title: INF AddSoftware Directive +description: An AddSoftware directive describes the installation of standalone software. +ms.author: windowsdriverdev +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# INF AddSoftware Directive + +Each **AddSoftware** directive describes the installation of standalone software. Use this directive in an INF file of the **SoftwareComponent** setup class. For more details on software components, see [Using a Component INF File](using-a-component-inf-file.md). This directive is supported for Windows 10 version 1703 and later. + +Valid installation types depend on the [target platform](../develop/windows-10-editions-for-universal-drivers.md). For example, Desktop supports MSI installers and setup EXEs. + +When a software component INF file specifies **AddSoftware**, the system queues software to be installed after device installation. There is no guarantee when or if the software will be installed. +If referenced software fails to install, the system tries again when the referencing software component is updated. + +An **AddSoftware** directive is used within an [**INF *DDInstall*.Software**](inf-ddinstall-software-section.md) section. + +``` +[DDInstall.Software] + +AddSoftware=SoftwareName,[flags],software-install-section +``` + +## Entries + +*SoftwareName* + +Specifies the name of the software to be installed. This name uniquely identifies the software. The processing of an **AddSoftware** directive checks the version against previous software installed with the same name by an **AddSoftware** directive from any driver package. We recommend prefacing the SoftwareName with the vendor name, for example `ContosoControlPanel`. + +*flags* + +Specifies one or more (ORed) flags. This value must be zero. + +*software-install-section* + +References an INF-writer-defined section that contains information for installing software. + +## Remarks + +Each INF-writer-created section name must be unique within the INF file and must follow the general rules for defining section names. For more information about these rules, see [General Syntax Rules for INF Files](general-syntax-rules-for-inf-files.md). + +An **AddSoftware** directive must reference a named *software-install-section* elsewhere in the INF file. Each such section has the following form: + +``` +[software-install-section] + +SoftwareType=type-code +[SoftwareBinary=path-to-binary] +[SoftwareArguments=argument[, argument] …] +[SoftwareVersion=w.x.y.z] +[SoftwareID=pfn://x.y.z] +``` + +The **SoftwareType** entry is required. If **SoftwareType** is set to 1, **SoftwareBinary** and **SoftwareVersion** are also required, but arguments and flags are optional. If **SoftwareType** is set to 2, **SoftwareID** is required, and flags are optional. For info about this feature, see [Pairing a driver with a Universal Windows Platform (UWP) app](pairing-app-and-driver-versions.md) and [Creating a custom capability to pair a driver with a Hardware Support App (HSA)](../devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md). + +Any software installed using **AddSoftware** must be installed silently (or quietly). In other words, no user interface can be shown to the user during installation. + +## Software-Install Section Entries and Values + +**SoftwareType**=*type-code* + +Specifies the type of software installation. + +A value of 1 indicates that the associated software is an MSI or EXE binary. When this value is set, the **SoftwareBinary** entry is also required. In current Windows Insiders builds, a value of 2 indicates that the associated software is a Windows Store link. + +**SoftwareBinary**=*filename* + +Specifies the path to the executable. The system generates command lines like the following: + +`MSI: msiexec /i "” ALLUSERS=1 /quiet /qn /promptrestart []` + +`EXE: []` + +If you use this entry, you must add the executable to the DriverStore by specifying the [INF CopyINF Directive](inf-copyfiles-directive.md) with a **DestinationDirs** value of 13. + +**SoftwareArguments**=*argument1[, argument2[, … argumentN]]* + +Specifies extension-specific arguments to append to the command line. You can specify command line arguments that the system simply passes through into the generated command line. You can also specify special strings called *runtime context variables*. When you specify a runtime context variable, the system converts it into a device-specific value before appending it to the generated command line. You can mix and match literal string arguments with runtime context variables. Supported runtime context variables are: + +`<>` + +The system replaces the string above with the device instance ID of the software component. + +For example: + +``` + [DDInstall.Software] + AddSoftware=ContosoControlPanel,,Contoso_ControlPanel_Software + + [Contoso_ControlPanel_Software] + SoftwareType=1 + SoftwareBinary=ContosoControlPanel.exe + SoftwareArguments=<> + SoftwareVersion=1.0.0.0 +``` + +The above example results in a command line like this: + +`\ContosoControlPanel.exe PCI\VEN_0000&DEV_0001&SUBSYS_00000000&REV_00\0123` + +If SoftwareArguments contains multiple arguments: + +``` + SoftwareArguments=arg1,<>,arg2 +``` + +The above results in: + +`\ContosoControlPanel.exe arg1 PCI\VEN_0000&DEV_0001&SUBSYS_00000000&REV_00\0123 arg2` + +**SoftwareVersion**=*w.x.y.z* + +Specifies the software version. Each value should not exceed 65535. When the system encounters a duplicate **SoftwareName**, it checks the **SoftwareVersion** against the previous **SoftwareVersion**. If it is greater, Windows runs the software. + +**SoftwareID**=*x.y.z* + +Specifies a Windows Store identifier and identifier type. Currently, only Package Family Name (PFN) is supported. Use a PFN to reference a Universal Windows Platform (UWP) app using the form `pfn://`. + + + +## See Also + +* [Using a Component INF File](using-a-component-inf-file.md). +* [INF DDInstall.Software Section](inf-ddinstall-software-section.md) +* [INF AddComponent Directive](inf-addcomponent-directive.md) +* [Pairing a driver with a Universal Windows Platform (UWP) app](pairing-app-and-driver-versions.md) +* [Creating a custom capability to pair a driver with a Hardware Support App (HSA)](../devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md) diff --git a/windows-driver-docs-pr/install/inf-bitreg-directive.md b/windows-driver-docs-pr/install/inf-bitreg-directive.md index 111247a2f9..344abd5f26 100644 --- a/windows-driver-docs-pr/install/inf-bitreg-directive.md +++ b/windows-driver-docs-pr/install/inf-bitreg-directive.md @@ -1,6 +1,6 @@ --- title: INF BitReg Directive -description: A BitReg directive references one or more INF-writer-defined sections used to set or clear bits within an existing REG\_BINARY-type value entry in the registry. However, this directive is very rarely used in device/driver INF files. +description: A BitReg directive references one or more INF-writer-defined sections used to set or clear bits within an existing REG_BINARY-type value entry in the registry. However, this directive is very rarely used in device/driver INF files. ms.assetid: d9dc601a-e0bb-488f-8bed-221ad600a88c keywords: - INF BitReg Directive Device and Driver Installation @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF BitReg Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **BitReg** directive references one or more INF-writer-defined sections used to set or clear bits within an existing REG\_BINARY-type value entry in the registry. However, this directive is very rarely used in device/driver INF files. -``` syntax +``` [DDInstall] | [DDInstall.HW] | [DDInstall.CoInstallers] | @@ -46,7 +46,7 @@ A **BitReg** directive can be specified under any of the sections shown in the f Each named section referenced by a **BitReg** directive has the following form: -``` syntax +``` [bit-registry-section] reg-root, [subkey], value-entry-name, [flags], byte-mask, byte-to-modify reg-root, [subkey], value-entry-name, [flags], byte-mask, byte-to-modify diff --git a/windows-driver-docs-pr/install/inf-classinstall32-section.md b/windows-driver-docs-pr/install/inf-classinstall32-section.md index e71140b5c3..eee6bd3fdc 100644 --- a/windows-driver-docs-pr/install/inf-classinstall32-section.md +++ b/windows-driver-docs-pr/install/inf-classinstall32-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF ClassInstall32 Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **ClassInstall32** section installs a new [device setup class](device-setup-classes.md) (and possibly a class installer) for devices in the new class. -``` syntax +``` [ClassInstall32] | [ClassInstall32.nt] | [ClassInstall32.ntx86] | @@ -139,7 +139,7 @@ Under this *SetupClassGUID* subkey, such an INF also provides registry informati Such a class-specific add-registry section has the following general form: -``` syntax +``` [SetupClassAddReg] HKR,,,,%DevClassName% ; device-class friendly name diff --git a/windows-driver-docs-pr/install/inf-classinstall32-services-section.md b/windows-driver-docs-pr/install/inf-classinstall32-services-section.md index bcc422c233..76ff62beea 100644 --- a/windows-driver-docs-pr/install/inf-classinstall32-services-section.md +++ b/windows-driver-docs-pr/install/inf-classinstall32-services-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF ClassInstall32.Services Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **ClassInstall32** section installs a new [device setup class](device-setup-classes.md) (and possibly a class installer) for devices in the new class. -``` syntax +``` [ClassInstall32.Services] | [ClassInstall32.nt.Services] | [ClassInstall32.ntx86.Services] | diff --git a/windows-driver-docs-pr/install/inf-controlflags-section.md b/windows-driver-docs-pr/install/inf-controlflags-section.md index c020459372..7406c1a18a 100644 --- a/windows-driver-docs-pr/install/inf-controlflags-section.md +++ b/windows-driver-docs-pr/install/inf-controlflags-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF ControlFlags Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **ControlFlags** section identifies devices for which Windows should take certain unique actions during installation. -``` syntax +``` [ControlFlags] ExcludeFromSelect=* | diff --git a/windows-driver-docs-pr/install/inf-copyfiles-directive.md b/windows-driver-docs-pr/install/inf-copyfiles-directive.md index 2cefde3e44..3f37a273b9 100644 --- a/windows-driver-docs-pr/install/inf-copyfiles-directive.md +++ b/windows-driver-docs-pr/install/inf-copyfiles-directive.md @@ -25,7 +25,7 @@ A **CopyFiles** directive can do either of the following: - Cause a single file to be copied from the source media to the default destination directory. - Reference one or more INF-writer-defined sections in the INF that each specifies a list of files to be copied from the source media to the destination. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -43,7 +43,7 @@ A **CopyFiles** directive can be specified within any of the sections shown in t Each named section referenced by a **CopyFiles** directive has one or more entries of the following form: -``` syntax +``` [file-list-section] destination-file-name[,[source-file-name][,[unused][,flag]]] ... @@ -53,7 +53,7 @@ An INF-writer-defined *file-list-section* can have any number of entries, each o Each *file-list-section* can have an optional, associated *file-list-section***.security** section of the following form: -``` syntax +``` [file-list-section.security] "security-descriptor-string" ``` diff --git a/windows-driver-docs-pr/install/inf-copyinf-directive.md b/windows-driver-docs-pr/install/inf-copyinf-directive.md index 3f392e12d0..d21fda73fc 100644 --- a/windows-driver-docs-pr/install/inf-copyinf-directive.md +++ b/windows-driver-docs-pr/install/inf-copyinf-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices A **CopyINF** directive causes specified INF files to be copied to the target system. The **CopyINF** directive is supported in Windows XP and later versions of Windows. -``` syntax +``` [DDInstall] CopyINF=filename1.inf[,filename2.inf]... diff --git a/windows-driver-docs-pr/install/inf-ddinstall-coinstallers-section.md b/windows-driver-docs-pr/install/inf-ddinstall-coinstallers-section.md index d08f5023d4..8005908000 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-coinstallers-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-coinstallers-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DDInstall.CoInstallers Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This optional section registers one or more device-specific co-installers supplied on the distribution media to supplement the operations of existing device class installers. -``` syntax +``` [install-section-name.CoInstallers] | [install-section-name.nt.CoInstallers] | [install-section-name.ntx86.CoInstallers] | @@ -132,7 +132,7 @@ All co-installer files must be copied into the *%SystemRoot%\\system32* director Registering one or more device-specific co-installers requires adding a REG\_MULTI\_SZ-typed value entry to the registry. Specify an *add-registry-section* referenced by the [**AddReg**](inf-addreg-directive.md) directive, by using the following general form: -``` syntax +``` [DDInstall.CoInstallers_DeviceAddReg] HKR,,CoInstallers32,0x00010000,"DevSpecificCoInstall.dll @@ -150,7 +150,7 @@ For more information, see [Registering a Device-Specific Co-installer](registeri To add a value entry (and setup-class subkey, if it does not exist already) for one or more device-class co-installers to the registry, an *add-registry-section* referenced by the [**AddReg**](inf-addreg-directive.md) directive has the following general form: -``` syntax +``` [DDInstall.CoInstallers_ClassAddReg] HKLM,System\CurrentControlSet\Control diff --git a/windows-driver-docs-pr/install/inf-ddinstall-components-section.md b/windows-driver-docs-pr/install/inf-ddinstall-components-section.md new file mode 100644 index 0000000000..e78cf364b0 --- /dev/null +++ b/windows-driver-docs-pr/install/inf-ddinstall-components-section.md @@ -0,0 +1,55 @@ +--- +title: INF DDInstall.Components Section +description: The DDInstall.Components section contains one or more INF AddComponent directives that reference additional INF-writer-defined sections in a driver package INF file. +ms.author: windowsdriverdev +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# INF DDInstall.Components Section + +This optional section contains one or more [**INF AddComponent directives**](inf-addcomponent-directive.md) that reference additional INF-writer-defined sections in a driver package INF file. This section is supported for Windows 10 Version 1703 and later. + +``` +[install-section-name.Components] | +[install-section-name.nt.Components] | +[install-section-name.ntx86.Components] | +[install-section-name.ntia64.Components] | +[install-section-name.ntamd64.Components] + +AddComponent=ComponentName,[flags],component-install-section +``` + +You can provide a *DDInstall*.**Components** section with one or more **AddComponent** directives to create a symbolic relationship between a driver package and any number of software components. + +## Entries + +**AddComponent**=*ComponentName,[flags],component-install-section* + +This directive references an INF-writer-defined component-install-section elsewhere in the INF file for the drivers of the devices covered by this *DDInstall* section. For more information, see [**INF AddComponent Directive**](inf-addcomponent-directive.md). + +## Remarks + +*DDInstall*.**Components** sections should have the same platform and operating system decorations as their related *DDInstall* sections. For example, an *install-section-name*.**ntx86** section would have a corresponding *install-section-name*.**ntx86.Components** section. + +The specified *DDInstall* section must be referenced in a device/models-specific entry under the per-manufacturer *Models* section of the INF file. The case-insensitive extensions to the *install-section-name* shown in the formal syntax statement can be inserted into such a *DDInstall*.**Components** section name in cross-platform INF files. + +For more information about how to use the system-defined **.nt**, **.ntx86**, **.ntia64**, and **.ntamd64** extensions, see [Creating INF Files for Multiple Platforms and Operating Systems](creating-inf-files-for-multiple-platforms-and-operating-systems.md). + +## Examples + +``` +[ContosoGrfx.NT.Components] +AddComponent = ContosoControlPanel,,Component_Inst + +[Component_Inst] +ComponentIDs = VID0001&PID0001&SID0001 +DisplayName = %ContosoControlPanelDisplayName% +``` + +## See also + +[Using a Component INF File](using-a-component-inf-file.md) + +[INF AddComponent Directive](inf-addcomponent-directive.md) diff --git a/windows-driver-docs-pr/install/inf-ddinstall-factdef-section.md b/windows-driver-docs-pr/install/inf-ddinstall-factdef-section.md index 421609e454..54cfaeac82 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-factdef-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-factdef-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DDInstall.FactDef Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This section should be used in an INF for any manually installed non-PnP device that an end-user might install. This section specifies the factory-default hardware configuration settings, such as the bus-relative I/O ports and IRQ (if any), for such a card. -``` syntax +``` [install-section-name.FactDef] | [install-section-name.nt.FactDef] | [install-section-name.ntx86.FactDef] | @@ -68,7 +68,7 @@ Specifies the bus-relative DMA channel as a decimal number. *DMAattrs* is option **IOConfig=***io-range* Specifies the I/O port range for the device in the following form: -``` syntax +``` start-end[([decode-mask][:alias-offset][:attr])] ``` @@ -99,7 +99,7 @@ Specifies the letter **M** if the specified range is in system memory. If omitte **MemConfig=***mem-range* Specifies the memory range for the device in the following form: -``` syntax +``` start-end[(attr)] ``` diff --git a/windows-driver-docs-pr/install/inf-ddinstall-hw-section.md b/windows-driver-docs-pr/install/inf-ddinstall-hw-section.md index 1614a63189..03fc233973 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-hw-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-hw-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices *DDInstall***.HW** sections are typically used for installing multifunction devices, for installing PnP filter drivers, and for setting up any user-accessible device-specific but driver-independent information in the registry, whether with explicit [**AddReg**](inf-addreg-directive.md) directives or with **Include** and **Needs** entries. -``` syntax +``` [install-section-name.HW] | [install-section-name.nt.HW] | [install-section-name.ntx86.HW] | diff --git a/windows-driver-docs-pr/install/inf-ddinstall-interfaces-section.md b/windows-driver-docs-pr/install/inf-ddinstall-interfaces-section.md index ebe7cf47ac..7e83f0f289 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-interfaces-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-interfaces-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Each per-Models *DDInstall***.Interfaces** section can have one or more [**AddInterface**](inf-addinterface-directive.md) directives, depending on how many device interfaces a particular device/driver supports. -``` syntax +``` [install-section-name.Interfaces] | [install-section-name.nt.Interfaces] | [install-section-name.ntx86.Interfaces] | diff --git a/windows-driver-docs-pr/install/inf-ddinstall-logconfigoverride-section.md b/windows-driver-docs-pr/install/inf-ddinstall-logconfigoverride-section.md index 56865febc2..3bd96940e1 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-logconfigoverride-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-logconfigoverride-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DDInstall.LogConfigOverride Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   *DDInstall***.LogConfigOverride** sections are used to create an [override configuration](https://msdn.microsoft.com/library/windows/hardware/ff547012#logical-configuration-types-for-resource-requirements-lists), which overrides the hardware resource requirements that a Plug and Play device's bus driver reports. -``` syntax +``` [install-section-name.LogConfigOverride] | [install-section-name.nt.LogConfigOverride] | [install-section-name.ntx86.LogConfigOverride] | diff --git a/windows-driver-docs-pr/install/inf-ddinstall-section.md b/windows-driver-docs-pr/install/inf-ddinstall-section.md index 01a8b26236..40e93a937b 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-section.md @@ -24,7 +24,7 @@ Each per-Models *DDInstall* section contains an optional **DriverVer** directive The sections referenced by these directives contain instructions for installing driver files and writing any device-specific and/or driver-specific information into the registry. -``` syntax +``` [install-section-name] | [install-section-name.nt] | [install-section-name.ntx86] | @@ -92,7 +92,7 @@ This optional entry specifies one or more additional system-supplied INF files t For example, the system INF files for device drivers that depend on the system's kernel-streaming support specify this entry as follows: -``` syntax +``` Include= ks.inf[, [kscaptur.inf,] [ksfilter.inf]]... ``` @@ -103,7 +103,7 @@ This optional entry specifies sections within system-supplied INF files that mus For example, the INF files for device drivers that have the preceding **Include** entry specify this entry as follows: -``` syntax +``` Needs= KS.Registration[, KSCAPTUR.Registration | KSCAPTUR.Registration.NT, MSPCLOCK.Installation] ``` diff --git a/windows-driver-docs-pr/install/inf-ddinstall-services-section.md b/windows-driver-docs-pr/install/inf-ddinstall-services-section.md index 91efff98d2..067c85f3cf 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-services-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-services-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices Each per-Models *DDInstall***.Services** section contains one or more [**INF AddService directives**](inf-addservice-directive.md) that reference additional INF-writer-defined sections in an INF file. -``` syntax +``` [install-section-name.Services] | [install-section-name.nt.Services] | [install-section-name.ntx86.Services] | @@ -40,10 +40,9 @@ You can provide a *DDInstall***.Services** section with at least one **AddServic ## Entries - -**AddService=***ServiceName*,\[*flags*\]**,***service-install-section* - -                                       \[,*event-log-install-section*\[**,**\[*EventLogType*\]\[**,***EventName*\]\]\]...\] + + +**AddService=***ServiceName*,\[*flags*\]**,***service-install-section*\[,*event-log-install-section*\[**,**\[*EventLogType*\]\[**,***EventName*\]\]\]...\] This directive references an INF-writer-defined *service-install-section* and, possibly, an *event-log-install-section* elsewhere in the INF file for the drivers of the devices covered by this *DDInstall* section. For more information, see [**INF AddService Directive**](inf-addservice-directive.md). **DelService=***ServiceName*\[**,**\[*flags*\]\[**,**\[*EventLogType*\]\[**,***EventName*\]\]\]... diff --git a/windows-driver-docs-pr/install/inf-ddinstall-software-section.md b/windows-driver-docs-pr/install/inf-ddinstall-software-section.md new file mode 100644 index 0000000000..970c5f5f18 --- /dev/null +++ b/windows-driver-docs-pr/install/inf-ddinstall-software-section.md @@ -0,0 +1,59 @@ +--- +title: INF DDInstall.Software Section +description: The DDInstall.Software section contains one or more INF AddSoftware directives that reference additional INF-writer-defined sections in a software component INF file. +ms.author: windowsdriverdev +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# INF DDInstall.Software Section + +Each per-Models *DDInstall*.**Software** section contains one or more [**INF AddSoftware directives**](inf-addsoftware-directive.md) that reference additional INF-writer-defined sections in a software component INF file. This section is supported for Windows 10 Version 1703 and later. + +``` +[install-section-name.Software] | +[install-section-name.nt.Software] | +[install-section-name.ntx86.Software] | +[install-section-name.ntia64.Software] | +[install-section-name.ntamd64.Software] + +AddSoftware=SoftwareName,[flags],software-install-section +``` + +You can provide a *DDInstall*.**Software** section with at least one [AddSoftware directive](inf-addsoftware-directive.md) to install software from a software component. + +The software installation must be non-interactive. + +## Entries + +**AddSoftware**=*SoftwareName,[flags],software-install-section* + +This directive references an INF-writer-defined *software-install-section* elsewhere in the software component INF file. For more information, see [**INF AddSoftware directive**](inf-addsoftware-directive.md). + +## Remarks + +*DDInstall*.**Software** sections should have the same platform and operating system decorations as their related *DDInstall* sections. For example, an *install-section-name*.**ntx86** section would have a corresponding *install-section-name*.**ntx86.Software** section. + +The specified *DDInstall* section must be referenced in a device/models-specific entry under the per-manufacturer *Models* section of the INF file. The case-insensitive extensions to the *install-section-name* shown in the formal syntax statement can be inserted into such a *DDInstall***.Software** section name in cross-platform INF files. + +For more information about how to use the system-defined **.nt**, **.ntx86**, **.ntia64**, and **.ntamd64** extensions, see [Creating INF Files for Multiple Platforms and Operating Systems](creating-inf-files-for-multiple-platforms-and-operating-systems.md). + +## Examples + +``` +[ContosoCtrlPnl.NT.Software] +AddSoftware = ContosoGrfx1CtrlPnl,, Software_Inst + +[Software_Inst] +SoftwareType = 1 +SoftwareBinary = %13%\ContosoCtrlPnl.exe +SoftwareArguments = <> +SoftwareVersion = 1.0.0.0 +``` + +## See also + +[Using a Component INF File](using-a-component-inf-file.md). + +[INF AddSoftware Directive](inf-addsoftware-directive.md) diff --git a/windows-driver-docs-pr/install/inf-ddinstall-wmi-section.md b/windows-driver-docs-pr/install/inf-ddinstall-wmi-section.md index db881bb5c9..e276878afb 100644 --- a/windows-driver-docs-pr/install/inf-ddinstall-wmi-section.md +++ b/windows-driver-docs-pr/install/inf-ddinstall-wmi-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices An INF *DDInstall*.**WMI** section contains one or more **WMIInterface** directives that specify characteristics for each WMI class that the driver provides. -``` syntax +``` [install-section-name.WMI] | [install-section-name.nt.WMI] | [install-section-name.ntx86.WMI] | diff --git a/windows-driver-docs-pr/install/inf-defaultinstall-section.md b/windows-driver-docs-pr/install/inf-defaultinstall-section.md index 01ac99104b..f08a9cf668 100644 --- a/windows-driver-docs-pr/install/inf-defaultinstall-section.md +++ b/windows-driver-docs-pr/install/inf-defaultinstall-section.md @@ -1,6 +1,6 @@ --- title: INF DefaultInstall Section -description: An INF file's DefaultInstall section is accessed if a user selects the \ 0034;Install \ 0034; menu item after right-clicking on the INF file name. +description: An INF file's DefaultInstall section is accessed if a user selects the "Install" menu item after right-clicking on the INF file name. ms.assetid: 41412124-38d9-43c0-9954-d34b242a3922 keywords: - INF DefaultInstall Section Device and Driver Installation @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DefaultInstall Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   An INF file's **DefaultInstall** section is accessed if a user selects the "Install" menu item after right-clicking on the INF file name. -``` syntax +``` [DefaultInstall] | [DefaultInstall.nt] | [DefaultInstall.ntx86] | @@ -75,7 +75,7 @@ This optional entry specifies one or more additional system-supplied INF files t For example, the system INF files for device drivers that depend on the system's kernel-streaming support specify this entry as follows: -``` syntax +``` Include= ks.inf[,[kscaptur.inf,][ksfilter.inf]] ``` @@ -86,7 +86,7 @@ This optional entry specifies sections within system-supplied INF files that mus For example, the INF files for device drivers that have the preceding **Include** entry specify this entry as follows: -``` syntax +``` Needs= KS.Registration[,KSCAPTUR.Registration |                         KSCAPTUR.Registration.NT,MSPCLOCK.Installation] ``` @@ -164,7 +164,7 @@ Providing a **DefaultInstall** section is optional. If an INF file does not incl To install a **DefaultInstall** section from a [*device installation application*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-installation-application), use the following call to **InstallHinfSection**: -``` syntax +``` InstallHinfSection(NULL,NULL,TEXT("DefaultInstall 132 path-to-inf\infname.inf"),0); ``` @@ -177,7 +177,7 @@ Examples The following example shows a typical **DefaultInstall** section: -``` syntax +``` [DefaultInstall] CopyFiles=MyAppWinFiles, MyAppSysFiles, @SRSutil.exe AddReg=MyAppRegEntries diff --git a/windows-driver-docs-pr/install/inf-defaultinstall-services-section.md b/windows-driver-docs-pr/install/inf-defaultinstall-services-section.md index 88c44bd4c1..2da8210c53 100644 --- a/windows-driver-docs-pr/install/inf-defaultinstall-services-section.md +++ b/windows-driver-docs-pr/install/inf-defaultinstall-services-section.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DefaultInstall.Services Section -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **DefaultInstall.Services** section contains one or more [**AddService**](inf-addservice-directive.md) directives referencing additional INF-writer-defined sections in an INF file. This section is equivalent to the [**INF *DDInstall*.Services**](inf-ddinstall-services-section.md) section, and is used in association with an [**INF DefaultInstall**](inf-defaultinstall-section.md) section. -``` syntax +``` [DefaultInstall.Services] | [DefaultInstall.nt.Services] | [DefaultInstall.ntx86.Services] | diff --git a/windows-driver-docs-pr/install/inf-delfiles-directive.md b/windows-driver-docs-pr/install/inf-delfiles-directive.md index 7a853c63ea..6fd9a28765 100644 --- a/windows-driver-docs-pr/install/inf-delfiles-directive.md +++ b/windows-driver-docs-pr/install/inf-delfiles-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DelFiles Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **DelFiles** directive references an INF-writer-defined section elsewhere in the INF file, and causes that list of files to be deleted in the context of operations on the section in which the referring **DelFiles** directive is specified. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -44,7 +44,7 @@ A **DelFiles** directive can be specified within any of the sections shown in th Each named section referenced by a **DelFiles** directive has one or more entries of the following form: -``` syntax +``` [file-list-section] destination-file-name[,,,flag] diff --git a/windows-driver-docs-pr/install/inf-delproperty-directive.md b/windows-driver-docs-pr/install/inf-delproperty-directive.md index 228cdc3dd1..b176f09776 100644 --- a/windows-driver-docs-pr/install/inf-delproperty-directive.md +++ b/windows-driver-docs-pr/install/inf-delproperty-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DelProperty Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **DelProperty** directive references one or more INF file sections that delete [device properties](device-properties.md) for a device instance, a [device setup class](device-setup-classes.md), a [device interface class](device-interface-classes.md), or a device interface. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -47,7 +47,7 @@ A **DelProperty** directive can be specified under any of the sections shown in A *del-property-section* that is referenced by a **DelProperty** directive has the following format: -``` syntax +``` [del-property-section] (property-name [ ,, flags [, value]]) | ({property-category-guid}, property-pid [ , flags [, value]]) (property-name [ ,, flags [, value]]) | ({property-category-guid}, property-pid [ , flags [, value]]) diff --git a/windows-driver-docs-pr/install/inf-delreg-directive.md b/windows-driver-docs-pr/install/inf-delreg-directive.md index 23010d00b9..184dcac201 100644 --- a/windows-driver-docs-pr/install/inf-delreg-directive.md +++ b/windows-driver-docs-pr/install/inf-delreg-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DelReg Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **DelReg** directive references one or more INF-writer-defined sections describing keys and/or value entries to be removed from the registry. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -39,7 +39,7 @@ DelReg=del-registry-section[,del-registry-section]... Each *del-registry-section* referenced by a **DelReg** directive has the following form: -``` syntax +``` [del-registry-section] reg-root-string,subkey[,value-entry-name][,flags][,value] reg-root-string,subkey[,value-entry-name][,flags][,value] @@ -124,13 +124,13 @@ Each *del-registry-section* name must be unique to the INF file, but it can be r With operating system versions prior to Windows XP, the only way to delete a key is by specifying the following: -``` syntax +``` reg-root-string, subkey ``` For Windows XP and later versions of Windows, the following is also permitted (to specify the 32-bit registry): -``` syntax +``` reg-root-string, subkey,,0x4000 ``` diff --git a/windows-driver-docs-pr/install/inf-delservice-directive.md b/windows-driver-docs-pr/install/inf-delservice-directive.md index 0296b42b6f..e179b92041 100644 --- a/windows-driver-docs-pr/install/inf-delservice-directive.md +++ b/windows-driver-docs-pr/install/inf-delservice-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF DelService Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **DelService** directive is used in a [***DDInstall*.Services**](inf-ddinstall-services-section.md) section to remove one or more previously installed device/driver services from the target computer. -``` syntax +``` [DDInstall.Services] DelService=ServiceName[,[flags][,[EventLogType][,EventName]] diff --git a/windows-driver-docs-pr/install/inf-destinationdirs-section.md b/windows-driver-docs-pr/install/inf-destinationdirs-section.md index 6844066ce5..8d66f095a2 100644 --- a/windows-driver-docs-pr/install/inf-destinationdirs-section.md +++ b/windows-driver-docs-pr/install/inf-destinationdirs-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices A **DestinationDirs** section specifies the target destination directory or directories for all copy, delete, and/or rename operations on files referenced by name elsewhere in the INF file. -``` syntax +``` [DestinationDirs] [DefaultDestDir=dirid[,subdir]] diff --git a/windows-driver-docs-pr/install/inf-directives.md b/windows-driver-docs-pr/install/inf-directives.md index 1402620b6e..dde9361c48 100644 --- a/windows-driver-docs-pr/install/inf-directives.md +++ b/windows-driver-docs-pr/install/inf-directives.md @@ -14,229 +14,5 @@ ms.technology: windows-devices This section describes the syntax of the directives that can appear within the sections of INF files. The following topics provide detailed information about the INF directives, and are listed in alphabetical order. -## In this section - - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TopicDescription

[INF AddInterface Directive](inf-addinterface-directive.md)

One or more AddInterface directives can be specified within an [INF DDInstall.Interfaces section](inf-ddinstall-interfaces-section.md). This directive installs device-specific support for [device interface classes](device-interface-classes.md) exported to higher level components, such as other drivers or applications. The directive typically references an add-interface-section , which sets up registry information for the device-specific instance of the device interface class.

[INF AddPowerSetting Directive](inf-addpowersetting-directive.md)

An AddPowerSetting directive references one or more sections that are used to modify or create power setting information. Each add-power-setting-section defines a power setting, the allowed values for the power setting, the friendly name of the power setting, and the description of the power setting. An add-power-setting-section also specifies the default value for each power scheme personality. For more information about power settings and power scheme personalities, see [Managing Device Performance States](https://msdn.microsoft.com/library/windows/hardware/ff554353).

[INF AddProperty Directive](inf-addproperty-directive.md)

An AddProperty directive references one or more INF file sections that modify the [device properties](device-properties.md) that are set for a device instance, a [device setup class](device-setup-classes.md), a [device interface class](device-interface-classes.md), or a device interface.

[INF AddReg Directive](inf-addreg-directive.md)

An AddReg directive references one or more INF-writer-defined add-registry-sections that are used to modify or create registry information.

[INF AddService Directive](inf-addservice-directive.md)

-Note  This directive is not used in INF files that install devices that do not require any drivers, such as modems or display monitors. -
-
-  -
-

An AddService directive is used within an [INF DDInstall.Services section](inf-ddinstall-services-section.md) or [INF DefaultInstall.Services section](inf-defaultinstall-services-section.md). It specifies characteristics of the services associated with drivers, such as how and when the services are loaded, and any dependencies on other underlying legacy drivers or services. Optionally, this directive also sets up event-logging services for the device.

[INF BitReg Directive](inf-bitreg-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A BitReg directive references one or more INF-writer-defined sections used to set or clear bits within an existing REG_BINARY-type value entry in the registry. However, this directive is very rarely used in device/driver INF files.

[INF CopyFiles Directive](inf-copyfiles-directive.md)

A CopyFiles directive can do either of the following:

-
    -
  • Cause a single file to be copied from the source media to the default destination directory.
  • -
  • Reference one or more INF-writer-defined sections in the INF that each specifies a list of files to be copied from the source media to the destination.
  • -

[INF CopyINF Directive](inf-copyinf-directive.md)

A CopyINF directive causes specified INF files to be copied to the target system. The CopyINF directive is supported in Windows XP and later versions of Windows.

[INF DelFiles Directive](inf-delfiles-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A DelFiles directive references an INF-writer-defined section elsewhere in the INF file, and causes that list of files to be deleted in the context of operations on the section in which the referring DelFiles directive is specified.

[INF DelProperty Directive](inf-delproperty-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A DelProperty directive references one or more INF file sections that delete [device properties](device-properties.md) for a device instance, a [device setup class](device-setup-classes.md), a [device interface class](device-interface-classes.md), or a device interface.

[INF DelReg Directive](inf-delreg-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A DelReg directive references one or more INF-writer-defined sections describing keys and/or value entries to be removed from the registry.

[INF DelService Directive](inf-delservice-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A DelService directive is used in a [DDInstall.Services](inf-ddinstall-services-section.md) section to remove one or more previously installed device/driver services from the target computer.

[INF DriverVer Directive](inf-driverver-directive.md)

A DriverVer directive specifies version information for drivers installed by this INF.

[INF FeatureScore Directive](inf-featurescore-directive.md)

The FeatureScore directive provides an additional ranking criterion for drivers based on the features that a driver supports. For example, feature scores might be defined for a [device setup class](device-setup-classes.md) that distinguishes between drivers that are based on class-specific criteria.

[INF HardwareId Directive](inf-hardwareid-directive.md)

-Note  The HardwareId directive is only supported within an Autorun.inf file. This directive must not be used within the INF files that are used for PnP device installations. -
-
-  -
-

Starting with Windows Vista, the Found New Hardware Wizard and Hardware Update Wizard support INF HardwareId directives in the [DeviceInstall] section of an Autorun.inf file. The author of Autorun.inf can use these HardwareId directives to specify Plug and Play (PnP) hardware identifiers (IDs) of the devices for which the AutoRun-enabled application provides and installs drivers.

[INF Ini2Reg Directive](inf-ini2reg-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

An Ini2Reg directive references one or more named sections in which lines or sections from a supplied INI file are moved into the registry. This creates or replaces one or more value entries under a specified key.

[INF LogConfig Directive](inf-logconfig-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A LogConfig directive references one or more INF-writer-defined sections, each of which specifies a logical configuration of hardware resources − the interrupt request lines, memory ranges, I/O ports, and DMA channels that can be used by the device. Each log-config-section specifies an alternative set of bus-relative hardware resources that can be used by the device.

[INF ProfileItems Directive](inf-profileitems-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A ProfileItems directive is used in an [INF DDInstall section](inf-ddinstall-section.md) to list one or more profile-items-sections that contain items or groups to be added to, or removed from, the Start menu.

[INF Reboot Directive](inf-reboot-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A Reboot directive indicates that the caller should be notified to reboot the system after installation is complete.

[INF RegisterDlls Directive](inf-registerdlls-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A RegisterDlls directive references one or more INF sections used to specify files that are OLE controls and require self-registration.

[INF RenFiles Directive](inf-renfiles-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A RenFiles directive references an INF-writer-defined section elsewhere in the INF file, which causes that list of files to be renamed in the context of operations on the section in which the referring RenFiles directive is specified.

[INF UnregisterDlls Directive](inf-unregisterdlls-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

An UnregisterDlls directive references one or more INF sections used to specify files that are OLE controls and require self-unregistration (self-removal).

[INF UpdateIniFields Directive](inf-updateinifields-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

An UpdateIniFields directive references one or more named sections in which fine-grained modifications within the lines of an INI file can be specified.

[INF UpdateInis Directive](inf-updateinis-directive.md)

-Note  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

An UpdateInis directive references one or more named sections, specifying an INI file from which a particular section or line is to be read and applied to an existing INI file of the same name on the target computer. Optionally, line-by-line modifications from and to such INI files can be specified in the update-ini-section.

- -  - For more information about the syntax rules for INF directives, see [General Syntax Rules for INF Files](general-syntax-rules-for-inf-files.md). -  - -  - - - - - diff --git a/windows-driver-docs-pr/install/inf-driverver-directive.md b/windows-driver-docs-pr/install/inf-driverver-directive.md index 04eeb5e85f..b96820f2de 100644 --- a/windows-driver-docs-pr/install/inf-driverver-directive.md +++ b/windows-driver-docs-pr/install/inf-driverver-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices A **DriverVer** directive specifies version information for drivers installed by this INF. -``` syntax +``` [Version] | [DDInstall] diff --git a/windows-driver-docs-pr/install/inf-featurescore-directive.md b/windows-driver-docs-pr/install/inf-featurescore-directive.md index 0d6d404701..80f6f8d453 100644 --- a/windows-driver-docs-pr/install/inf-featurescore-directive.md +++ b/windows-driver-docs-pr/install/inf-featurescore-directive.md @@ -22,7 +22,7 @@ ms.technology: windows-devices The **FeatureScore** directive provides an additional ranking criterion for drivers based on the features that a driver supports. For example, feature scores might be defined for a [device setup class](device-setup-classes.md) that distinguishes between drivers that are based on class-specific criteria. -``` syntax +``` [DDInstall] FeatureScore=featurescore diff --git a/windows-driver-docs-pr/install/inf-hardwareid-directive.md b/windows-driver-docs-pr/install/inf-hardwareid-directive.md index 0756990304..e7765b86d0 100644 --- a/windows-driver-docs-pr/install/inf-hardwareid-directive.md +++ b/windows-driver-docs-pr/install/inf-hardwareid-directive.md @@ -1,6 +1,6 @@ --- title: INF HardwareId Directive -description: Starting with Windows Vista, the Found New Hardware Wizard and Hardware Update Wizard support INF HardwareId directives in the \ DeviceInstall\ section of an Autorun.inf file. +description: The Found New Hardware Wizard and Hardware Update Wizard support INF HardwareId directives in the [DeviceInstall] section of an Autorun.inf file. ms.assetid: aceb4db2-ae00-47f3-994a-49541437e260 keywords: - INF HardwareId Directive Device and Driver Installation @@ -26,7 +26,7 @@ ms.technology: windows-devices Starting with Windows Vista, the Found New Hardware Wizard and Hardware Update Wizard support INF **HardwareId** directives in the **\[DeviceInstall\]** section of an *Autorun.inf* file. The author of *Autorun.inf* can use these **HardwareId** directives to specify Plug and Play (PnP) hardware identifiers (IDs) of the devices for which the AutoRun-enabled application provides and installs drivers. -``` syntax +``` [DeviceInstall] HardwareId="pnp-hardware-id" diff --git a/windows-driver-docs-pr/install/inf-ini2reg-directive.md b/windows-driver-docs-pr/install/inf-ini2reg-directive.md index 523b309e0a..dce2123dc4 100644 --- a/windows-driver-docs-pr/install/inf-ini2reg-directive.md +++ b/windows-driver-docs-pr/install/inf-ini2reg-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF Ini2Reg Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   An **Ini2Reg** directive references one or more named sections in which lines or sections from a supplied INI file are moved into the registry. This creates or replaces one or more value entries under a specified key. -``` syntax +``` [ DDInstall ] | @@ -41,7 +41,7 @@ Ini2Reg=ini-to-registry-section[,ini-to-registry-section]... Each named section referenced by an **Ini2Reg** directive has the following form: -``` syntax +``` [ini-to-registry-section] ini-file,ini-section,[ini-key],reg-root,subkey[,flags] diff --git a/windows-driver-docs-pr/install/inf-interfaceinstall32-section.md b/windows-driver-docs-pr/install/inf-interfaceinstall32-section.md index f9aabe76e9..967e76e616 100644 --- a/windows-driver-docs-pr/install/inf-interfaceinstall32-section.md +++ b/windows-driver-docs-pr/install/inf-interfaceinstall32-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices This section creates one or more new [device interface classes](device-interface-classes.md). After a new class is created, subsequently installed devices/drivers can be registered to support the new device interface class by using [**INF *DDInstall*.Interfaces sections**](inf-ddinstall-interfaces-section.md) in their respective INF files, or by calling [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506). -``` syntax +``` [InterfaceInstall32] {InterfaceClassGUID}=install-interface-section[,flags] @@ -54,7 +54,7 @@ Each *install-interface-section* name must be unique within the INF file and mus Any specified *install-interface-section* has the following general form: -``` syntax +``` [interface-install-section] | [interface-install-section.nt] | [interface-install-section.ntx86] | diff --git a/windows-driver-docs-pr/install/inf-logconfig-directive.md b/windows-driver-docs-pr/install/inf-logconfig-directive.md index baa9a5bdc2..dd054c09e0 100644 --- a/windows-driver-docs-pr/install/inf-logconfig-directive.md +++ b/windows-driver-docs-pr/install/inf-logconfig-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF LogConfig Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **LogConfig** directive references one or more INF-writer-defined sections, each of which specifies a logical configuration of hardware resources − the interrupt request lines, memory ranges, I/O ports, and DMA channels that can be used by the device. Each *log-config-section* specifies an alternative set of bus-relative hardware resources that can be used by the device. -``` syntax +``` [DDInstall] | [DDInstall.LogConfigOverride] @@ -39,7 +39,7 @@ INF files for PnP devices use this directive only to create override configurati Each named section referenced by a **LogConfig** directive has the following form: -``` syntax +``` [log-config-section] ConfigPriority=priority-value[,config-type] @@ -166,7 +166,7 @@ Specifies the letter **M** if the given range is in system memory. If omitted, t **MemConfig=***mem-range*\[**,***mem-range*\]... Specifies one or more memory ranges for the device in one of the following forms: -``` syntax +``` start-end[(attr)] | size@min-max[%align-mask][(attr)] ``` diff --git a/windows-driver-docs-pr/install/inf-manufacturer-section.md b/windows-driver-docs-pr/install/inf-manufacturer-section.md index 9201c48a81..ce18df2716 100644 --- a/windows-driver-docs-pr/install/inf-manufacturer-section.md +++ b/windows-driver-docs-pr/install/inf-manufacturer-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices The **Manufacturer** section identifies the manufacturer of one or more devices that can be installed by using the INF file. -``` syntax +``` [Manufacturer] manufacturer-identifier @@ -37,7 +37,7 @@ manufacturer-identifier *manufacturer-identifier* Uniquely identifies a manufacturer and an INF section that contains information that identifies a manufacturer's device models. Each *manufacturer-identifier* entry must exist on a separate line and use the following format: -``` syntax +``` manufacturer-name | %strkey%=models-section-name | %strkey%=models-section-name [,TargetOSVersion] [,TargetOSVersion] ... (Windows XP and later versions of Windows) @@ -78,11 +78,11 @@ For Windows XP and later versions of Windows, *models-section-name* entries in t For Windows XP to Windows 10, version 1511, the format of *TargetOSVersion* decoration is as follows: -``` syntax +``` nt[Architecture][.[OSMajorVersion][.[OSMinorVersion][.[ProductType][.SuiteMask]]]] ``` Starting with Windows 10, version 1607 (Build 14310 and later), the format of the *TargetOSVersion* decoration is as follows: -``` syntax +``` nt[Architecture][.[OSMajorVersion][.[OSMinorVersion][.[ProductType][.SuiteMask][.[BuildNumber]]]]] ``` diff --git a/windows-driver-docs-pr/install/inf-models-section.md b/windows-driver-docs-pr/install/inf-models-section.md index 1a503ed363..11156bfc5d 100644 --- a/windows-driver-docs-pr/install/inf-models-section.md +++ b/windows-driver-docs-pr/install/inf-models-section.md @@ -24,7 +24,7 @@ A per-manufacturer *Models* section identifies at least one device, references t Any entry in the per-manufacturer *Models* section can also specify one or more additional device IDs for models that are compatible with the device designated by the initial hardware ID and are controlled by the same drivers. -``` syntax +``` [models-section-name] | [models-section-name.TargetOSVersion] (Windows XP and later versions of Windows) diff --git a/windows-driver-docs-pr/install/inf-profileitems-directive.md b/windows-driver-docs-pr/install/inf-profileitems-directive.md index 2ea0b99224..a97dffd7a9 100644 --- a/windows-driver-docs-pr/install/inf-profileitems-directive.md +++ b/windows-driver-docs-pr/install/inf-profileitems-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF ProfileItems Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **ProfileItems** directive is used in an [**INF *DDInstall* section**](inf-ddinstall-section.md) to list one or more *profile-items-sections* that contain items or groups to be added to, or removed from, the Start menu. -``` syntax +``` [DDInstall] ProfileItems=profile-items-section[,profile-items-section]... @@ -35,7 +35,7 @@ ProfileItems=profile-items-section[,profile-items-section]... Each named section referenced by a **ProfileItems** directive has the following form: -``` syntax +``` [profile-items-section] Name=link-name[,name-attributes] @@ -123,7 +123,7 @@ The *info-tip* value can also be specified as **"@***ResDllPath***\\***ResDll*** Use this format to support Windows Multilingual User Interface (MUI). An example is as follows: -``` syntax +``` InfoTip = "@%11%\shell32.dll,-22531" ``` @@ -132,7 +132,7 @@ This optional entry specifies a string resource that identifies a localizable st *ResDllPath* and *ResDll* specify the path and file name of a resource DLL, and *resID* is a positive value that represents a resource ID. An example is as follows: -``` syntax +``` DisplayResource="%11%\shell32.dll",22019 ``` diff --git a/windows-driver-docs-pr/install/inf-reboot-directive.md b/windows-driver-docs-pr/install/inf-reboot-directive.md index a585dd382f..e31b103e65 100644 --- a/windows-driver-docs-pr/install/inf-reboot-directive.md +++ b/windows-driver-docs-pr/install/inf-reboot-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF Reboot Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **Reboot** directive indicates that the caller should be notified to reboot the system after installation is complete. -``` syntax +``` [DDInstall] Reboot diff --git a/windows-driver-docs-pr/install/inf-registerdlls-directive.md b/windows-driver-docs-pr/install/inf-registerdlls-directive.md index c31a84208c..0fb17de58a 100644 --- a/windows-driver-docs-pr/install/inf-registerdlls-directive.md +++ b/windows-driver-docs-pr/install/inf-registerdlls-directive.md @@ -20,13 +20,11 @@ ms.technology: windows-devices # INF RegisterDlls Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). - -  +**Note**  If you are building a universal or mobile driver package, this directive is not valid. You can use the [Reg2inf tool](../devtest/reg2inf.md) to convert existing [INF RegisterDlls directives](../install/inf-registerdlls-directive.md) into [INF AddReg directives](../install/inf-addreg-directive.md) in order to make a driver package universal. For more info, see [Using a Universal INF File](using-a-universal-inf-file.md). A **RegisterDlls** directive references one or more INF sections used to specify files that are OLE controls and require self-registration. -``` syntax +``` [DDInstall] RegisterDlls=register-dll-section[,register-dll-section]... @@ -34,7 +32,7 @@ RegisterDlls=register-dll-section[,register-dll-section]... Each INF section referenced by a **RegisterDlls** directive must have the following entry format: -``` syntax +``` [register-dll-section] dirid,[subdir],filename,registration-flags[,[timeout][,argument]] diff --git a/windows-driver-docs-pr/install/inf-renfiles-directive.md b/windows-driver-docs-pr/install/inf-renfiles-directive.md index 2c7051c070..1adaedf101 100644 --- a/windows-driver-docs-pr/install/inf-renfiles-directive.md +++ b/windows-driver-docs-pr/install/inf-renfiles-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF RenFiles Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   A **RenFiles** directive references an INF-writer-defined section elsewhere in the INF file, which causes that list of files to be renamed in the context of operations on the section in which the referring **RenFiles** directive is specified. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -44,7 +44,7 @@ A **RenFiles** directive can be specified within any of the sections shown in th Each named section referenced by a **RenFiles** directive has one or more entries of the following form: -``` syntax +``` [file-list-section] new-dest-file-name,old-source-file-name diff --git a/windows-driver-docs-pr/install/inf-sections.md b/windows-driver-docs-pr/install/inf-sections.md index 1d2aec17de..566a3ba690 100644 --- a/windows-driver-docs-pr/install/inf-sections.md +++ b/windows-driver-docs-pr/install/inf-sections.md @@ -14,172 +14,7 @@ ms.technology: windows-devices The topics in this section describe the syntax of the sections that can appear in INF files. These topics provide detailed information about the INF sections, and are listed in the order in which they typically appear within an INF file. -## In this section - - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TopicDescription

[INF ClassInstall32 Section](inf-classinstall32-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A ClassInstall32 section installs a new [device setup class](device-setup-classes.md) (and possibly a class installer) for devices in the new class.

[INF ClassInstall32.Services Section](inf-classinstall32-services-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A ClassInstall32 section installs a new [device setup class](device-setup-classes.md) (and possibly a class installer) for devices in the new class.

[INF ControlFlags Section](inf-controlflags-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A ControlFlags section identifies devices for which Windows should take certain unique actions during installation.

[INF DDInstall Section](inf-ddinstall-section.md)

Each per-Models DDInstall section contains an optional DriverVer directive and one or more directives referencing additional named sections in the INF file, shown here with the most frequently specified INF directives, CopyFiles and AddReg, listed first.

-

The sections referenced by these directives contain instructions for installing driver files and writing any device-specific and/or driver-specific information into the registry.

[INF DDInstall.CoInstallers Section](inf-ddinstall-coinstallers-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

This optional section registers one or more device-specific co-installers supplied on the distribution media to supplement the operations of existing device class installers.

[INF DDInstall.FactDef Section](inf-ddinstall-factdef-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

This section should be used in an INF for any manually installed non-PnP device that an end-user might install. This section specifies the factory-default hardware configuration settings, such as the bus-relative I/O ports and IRQ (if any), for such a card.

[INF DDInstall.HW Section](inf-ddinstall-hw-section.md)

DDInstall .HW sections are typically used for installing multifunction devices, for installing PnP filter drivers, and for setting up any user-accessible device-specific but driver-independent information in the registry, whether with explicit [AddReg](inf-addreg-directive.md) directives or with Include and Needs entries.

[INF DDInstall.Interfaces Section](inf-ddinstall-interfaces-section.md)

Each per-Models DDInstall.Interfaces section can have one or more [AddInterface](inf-addinterface-directive.md) directives, depending on how many device interfaces a particular device/driver supports.

[INF DDInstall.LogConfigOverride Section](inf-ddinstall-logconfigoverride-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

DDInstall .LogConfigOverride sections are used to create an [override configuration](https://msdn.microsoft.com/library/windows/hardware/ff547012#logical-configuration-types-for-resource-requirements-lists), which overrides the hardware resource requirements that a Plug and Play device's bus driver reports.

[INF DDInstall.Services Section](inf-ddinstall-services-section.md)

Each per-Models DDInstall.Services section contains one or more [INF AddService directives](inf-addservice-directive.md) that reference additional INF-writer-defined sections in an INF file.

[INF DDInstall.WMI Section](inf-ddinstall-wmi-section.md)

An INF DDInstall.WMI section contains one or more WMIInterface directives that specify characteristics for each WMI class that the driver provides.

[INF DefaultInstall Section](inf-defaultinstall-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

An INF file's DefaultInstall section is accessed if a user selects the "Install" menu item after right-clicking on the INF file name.

[INF DefaultInstall.Services Section](inf-defaultinstall-services-section.md)

-Note  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). -
-
-  -
-

A DefaultInstall.Services section contains one or more [AddService](inf-addservice-directive.md) directives referencing additional INF-writer-defined sections in an INF file. This section is equivalent to the [INF DDInstall.Services](inf-ddinstall-services-section.md) section, and is used in association with an [INF DefaultInstall](inf-defaultinstall-section.md) section.

[INF DestinationDirs Section](inf-destinationdirs-section.md)

A DestinationDirs section specifies the target destination directory or directories for all copy, delete, and/or rename operations on files referenced by name elsewhere in the INF file.

[INF InterfaceInstall32 Section](inf-interfaceinstall32-section.md)

This section creates one or more new [device interface classes](device-interface-classes.md). After a new class is created, subsequently installed devices/drivers can be registered to support the new device interface class by using [INF DDInstall.Interfaces sections](inf-ddinstall-interfaces-section.md) in their respective INF files, or by calling [IoRegisterDeviceInterface](https://msdn.microsoft.com/library/windows/hardware/ff549506).

[INF Manufacturer Section](inf-manufacturer-section.md)

The Manufacturer section identifies the manufacturer of one or more devices that can be installed by using the INF file.

[INF Models Section](inf-models-section.md)

A per-manufacturer Models section identifies at least one device, references the DDInstall section of the INF file for that device, and specifies a unique-to-the-model-section [hardware identifier (ID)](hardware-ids.md) for that device.

-

Any entry in the per-manufacturer Models section can also specify one or more additional device IDs for models that are compatible with the device designated by the initial hardware ID and are controlled by the same drivers.

[INF SignatureAttributes Section](inf-signatureattributes-section.md)

This section allows users to request additional signatures as required by certain certification scenarios. Examples of these scenarios are: Protected Environment media playback, Early Launch Antimalware, and third party HAL extensions. These additional signatures will only be applied if your Hardware Certification Kit package contains the proper Features and passing Tests.

[INF SourceDisksFiles Section](inf-sourcedisksfiles-section.md)

The SourceDisksFiles section names the source files that are used during installation, identifies the installation disks that contain those files, and provides the directory paths, if any, on the distribution disks that contain individual files.

-

In order for a driver file or an application file to be included as part of a signed [driver package](driver-packages.md), the file must have a corresponding INF SourceDisksFiles section entry and a corresponding [INF CopyFiles directive](inf-copyfiles-directive.md).

[INF SourceDisksNames Section](inf-sourcedisksnames-section.md)

A SourceDisksNames section identifies the distribution disks or CD-ROM discs that contain the source files to be transferred to the target computer during installation.

[INF Strings Section](inf-strings-section.md)

An INF file must have at least one Strings section to define every %strkey% token specified elsewhere in that INF.

[INF Version Section](inf-version-section.md)

By convention, the Version section appears first in INF files. Every INF file must have this section.

- -  - For more information about the syntax rules for INF sections, see [General Syntax Rules for INF Files](general-syntax-rules-for-inf-files.md). -  - -  - - - diff --git a/windows-driver-docs-pr/install/inf-signatureattributes-section.md b/windows-driver-docs-pr/install/inf-signatureattributes-section.md index 55670dbd0b..9867684d28 100644 --- a/windows-driver-docs-pr/install/inf-signatureattributes-section.md +++ b/windows-driver-docs-pr/install/inf-signatureattributes-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices This section allows users to request additional signatures as required by certain certification scenarios. Examples of these scenarios are: Protected Environment media playback, Early Launch Antimalware, and third party HAL extensions. These additional signatures will only be applied if your Hardware Certification Kit package contains the proper Features and passing Tests. -``` syntax +``` [SignatureAttributes] FileOne = SignatureAttributes.SigType diff --git a/windows-driver-docs-pr/install/inf-sourcedisksfiles-section.md b/windows-driver-docs-pr/install/inf-sourcedisksfiles-section.md index 0ad18783df..dc2d95b3b3 100644 --- a/windows-driver-docs-pr/install/inf-sourcedisksfiles-section.md +++ b/windows-driver-docs-pr/install/inf-sourcedisksfiles-section.md @@ -24,7 +24,7 @@ The **SourceDisksFiles** section names the source files that are used during ins In order for a driver file or an application file to be included as part of a signed [driver package](driver-packages.md), the file must have a corresponding INF **SourceDisksFiles** section entry and a corresponding [**INF CopyFiles directive**](inf-copyfiles-directive.md). -``` syntax +``` [SourceDisksFiles] | [SourceDisksFiles.x86] | [SourceDisksFiles.ia64] | (Windows XP and later versions of Windows) diff --git a/windows-driver-docs-pr/install/inf-sourcedisksnames-section.md b/windows-driver-docs-pr/install/inf-sourcedisksnames-section.md index a582673264..6e5dfd266c 100644 --- a/windows-driver-docs-pr/install/inf-sourcedisksnames-section.md +++ b/windows-driver-docs-pr/install/inf-sourcedisksnames-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices A **SourceDisksNames** section identifies the distribution disks or CD-ROM discs that contain the source files to be transferred to the target computer during installation. -``` syntax +``` [SourceDisksNames] | [SourceDisksNames.x86] | [SourceDisksNames.ia64] | (Windows XP and later versions of Windows) diff --git a/windows-driver-docs-pr/install/inf-strings-section.md b/windows-driver-docs-pr/install/inf-strings-section.md index ce40f5279e..9ef9934212 100644 --- a/windows-driver-docs-pr/install/inf-strings-section.md +++ b/windows-driver-docs-pr/install/inf-strings-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices An INF file must have at least one **Strings** section to define every %*strkey*% token specified elsewhere in that INF. -``` syntax +``` [Strings] | [Strings.LanguageID] ... diff --git a/windows-driver-docs-pr/install/inf-unregisterdlls-directive.md b/windows-driver-docs-pr/install/inf-unregisterdlls-directive.md index f3c274ea57..644dfa9205 100644 --- a/windows-driver-docs-pr/install/inf-unregisterdlls-directive.md +++ b/windows-driver-docs-pr/install/inf-unregisterdlls-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF UnregisterDlls Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   An **UnregisterDlls** directive references one or more INF sections used to specify files that are OLE controls and require self-unregistration (self-removal). -``` syntax +``` [DDInstall] UnregisterDlls=unregister-dll-section[,unregister-dll-section]... @@ -34,7 +34,7 @@ UnregisterDlls=unregister-dll-section[,unregister-dll-section]... Each INF section referenced by an **UnregisterDlls** directive must have the following entry format: -``` syntax +``` [unregister-dll-section] dirid,[subdir],filename,registration-flags[,[timeout][,argument]] diff --git a/windows-driver-docs-pr/install/inf-updateinifields-directive.md b/windows-driver-docs-pr/install/inf-updateinifields-directive.md index 946a83a45e..0c4e8878ea 100644 --- a/windows-driver-docs-pr/install/inf-updateinifields-directive.md +++ b/windows-driver-docs-pr/install/inf-updateinifields-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF UpdateIniFields Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   An **UpdateIniFields** directive references one or more named sections in which fine-grained modifications within the lines of an INI file can be specified. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -39,7 +39,7 @@ UpdateIniFields=update-inifields-section[,update-inifields-section]... Each named section referenced by an **UpdateIniFields** directive has the following form: -``` syntax +``` [update-inifields-section] ini-file,ini-section,profile-name[,old-field][,new-field][,flags] diff --git a/windows-driver-docs-pr/install/inf-updateinis-directive.md b/windows-driver-docs-pr/install/inf-updateinis-directive.md index 9f78e925e4..290136cd63 100644 --- a/windows-driver-docs-pr/install/inf-updateinis-directive.md +++ b/windows-driver-docs-pr/install/inf-updateinis-directive.md @@ -20,13 +20,13 @@ ms.technology: windows-devices # INF UpdateInis Directive -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   An **UpdateInis** directive references one or more named sections, specifying an INI file from which a particular section or line is to be read and applied to an existing INI file of the same name on the target computer. Optionally, line-by-line modifications from and to such INI files can be specified in the *update-ini-section*. -``` syntax +``` [DDInstall] | [DDInstall.CoInstallers] | [ClassInstall32] | @@ -41,7 +41,7 @@ This directive is almost never specified in INF files for installation on Window Each named section referenced by an **UpdateInis** directive has the following form: -``` syntax +``` [update-ini-section] ini-file,ini-section[,old-ini-entry][,new-ini-entry][,flags] @@ -62,7 +62,7 @@ Specifies the name of the section within the given INI file. If the next two val *old-ini-entry* This optional value specifies the name of an entry in the given *ini-section*, usually expressed in the following form: -``` syntax +``` "key=value" ``` diff --git a/windows-driver-docs-pr/install/inf-version-section.md b/windows-driver-docs-pr/install/inf-version-section.md index f5e04c69c2..e4637f2dd9 100644 --- a/windows-driver-docs-pr/install/inf-version-section.md +++ b/windows-driver-docs-pr/install/inf-version-section.md @@ -22,7 +22,7 @@ ms.technology: windows-devices By convention, the **Version** section appears first in INF files. Every INF file must have this section. -``` syntax +``` [Version] Signature="signature-name" diff --git a/windows-driver-docs-pr/install/makecert-test-certificate.md b/windows-driver-docs-pr/install/makecert-test-certificate.md index 2e2e48f7cb..ebc8600344 100644 --- a/windows-driver-docs-pr/install/makecert-test-certificate.md +++ b/windows-driver-docs-pr/install/makecert-test-certificate.md @@ -15,7 +15,7 @@ ms.technology: windows-devices # MakeCert Test Certificate -A MakeCert test certificate is an [X.509 digital certificate](digital-certificates.md) that is created by using the command-line [CryptoAPI](http://go.microsoft.com/fwlink/p/?linkid=136391)[**MakeCert**](https://msdn.microsoft.com/library/windows/hardware/ff548309) tool. A MakeCert test certificate is a self-signed root certificate that can be used to test-sign a [driver package's](driver-packages.md) [catalog file](catalog-files.md) or to test-sign a driver file by embedding a signature in the driver file. +A MakeCert test certificate is an [X.509 digital certificate](digital-certificates.md) that is created by using the command-line [CryptoAPI](http://go.microsoft.com/fwlink/p/?linkid=136391) [**MakeCert**](https://msdn.microsoft.com/library/windows/hardware/ff548309) tool. A MakeCert test certificate is a self-signed root certificate that can be used to test-sign a [driver package's](driver-packages.md) [catalog file](catalog-files.md) or to test-sign a driver file by embedding a signature in the driver file. To create a MakeCert test certificate, use the [**MakeCert**](https://msdn.microsoft.com/library/windows/hardware/ff548309) tool as follows: diff --git a/windows-driver-docs-pr/install/modifying-registry-keys-by-class-installers-and-co-installers.md b/windows-driver-docs-pr/install/modifying-registry-keys-by-class-installers-and-co-installers.md index be1483242d..ec3037ce10 100644 --- a/windows-driver-docs-pr/install/modifying-registry-keys-by-class-installers-and-co-installers.md +++ b/windows-driver-docs-pr/install/modifying-registry-keys-by-class-installers-and-co-installers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Modifying Registry Keys by Class Installers and Co-installers -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/modifying-registry-values-by-class-installers-and-co-installers.md b/windows-driver-docs-pr/install/modifying-registry-values-by-class-installers-and-co-installers.md index d7a7b9146a..6aa676e697 100644 --- a/windows-driver-docs-pr/install/modifying-registry-values-by-class-installers-and-co-installers.md +++ b/windows-driver-docs-pr/install/modifying-registry-values-by-class-installers-and-co-installers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Modifying Registry Values by Class Installers and Co-installers -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/overview-of-inf-files.md b/windows-driver-docs-pr/install/overview-of-inf-files.md index 72109015e0..68190be81f 100644 --- a/windows-driver-docs-pr/install/overview-of-inf-files.md +++ b/windows-driver-docs-pr/install/overview-of-inf-files.md @@ -28,30 +28,4 @@ An INF file is a text file that contains all the information that [device instal - Driver version information - Registry information -## In this section - - -- [Looking at an INF File](looking-at-an-inf-file.md) -- [Using a Universal INF File](using-a-configurable-inf-file.md) -- [Using an Extension INF File](creating-an-extensible-inf-file.md) -- [Summary of INF Sections](summary-of-inf-sections.md) -- [Summary of INF Directives](summary-of-inf-directives.md) -- [General Guidelines for INF Files](general-guidelines-for-inf-files.md) -- [General Syntax Rules for INF Files](general-syntax-rules-for-inf-files.md) -- [Specifying the Source and Target Locations for Device Files](specifying-the-source-and-target-locations-for-device-files.md) -- [Creating INF Files for Multiple Platforms and Operating Systems](creating-inf-files-for-multiple-platforms-and-operating-systems.md) -- [Combining Platform Extensions with Operating System Versions](combining-platform-extensions-with-operating-system-versions.md) -- [Creating International INF Files](creating-international-inf-files.md) -- [Specifying Driver Load Order](specifying-driver-load-order.md) -- [Using Dirids](using-dirids.md) - See [INF File Sections and Directives](inf-file-sections-and-directives.md) for a complete description of INF file format. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/install/pairing-app-and-driver-versions.md b/windows-driver-docs-pr/install/pairing-app-and-driver-versions.md new file mode 100644 index 0000000000..4d4b594ff1 --- /dev/null +++ b/windows-driver-docs-pr/install/pairing-app-and-driver-versions.md @@ -0,0 +1,40 @@ +--- +title: Pairing a driver with a Universal Windows Platform (UWP) app +description: This topic describes how to specify that a Universal Windows Platform (UWP) app should only load if a specific driver is present. +ms.assetid: 50f981bb-e17b-4454-88f9-46b09eb05509 +ms.author: windowsdriverdev +ms.date: 08/24/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Pairing a driver with a Universal Windows Platform (UWP) app + +In current Windows Insider builds, you can specify that a Universal Windows Platform (UWP) app should only load if a specific driver is present. The app can further constrain loading to a particular driver version or date. This topic describes the steps required in both the app and driver to create such a requirement. + +## Steps in the app + +To cause a UWP app to load only when a specific driver is present, add two XML elements to the manifest XML (.appx) file for the app: + +* [uap5:DriverDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-driverdependency) +* [uap5:DriverConstraint](/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-driverconstraint) + +In particular, use these elements to specify at least one driver dependency containing at least one driver constraint. See further details on use of these elements on the reference pages linked to above. The latter page contains an example. + +## Steps in the driver + +Next, do the following in the driver's INF file: + +1. Specify the [INF AddSoftware Directive](inf-addsoftware-directive.md). +2. Set the **SoftwareType** entry to 2. +3. Provide a Package Family Name (PFN) in the **SoftwareID** entry. + +In addition to matching the most recent app and driver versions, the system also tries to match previous app and driver versions. For example, if app version 2 specifies minimum driver version 2, and app version 1 specifies minimum driver version 1, a system that has driver version 1 will successfully load app version 1. + +## See Also + +* [uap5:DriverDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-driverdependency?branch=lahugh-rs3) +* [uap5:DriverConstraint](https://review.docs.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-driverconstraint?branch=lahugh-rs3) +* [INF AddSoftware Directive](inf-addsoftware-directive.md) +* [Creating a custom capability to pair a driver with a Hardware Support App (HSA)](../devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md) diff --git a/windows-driver-docs-pr/install/providing-device-property-pages.md b/windows-driver-docs-pr/install/providing-device-property-pages.md index 66437eec9c..d60f14458f 100644 --- a/windows-driver-docs-pr/install/providing-device-property-pages.md +++ b/windows-driver-docs-pr/install/providing-device-property-pages.md @@ -24,7 +24,7 @@ ms.technology: windows-devices ## -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/registering-for-notification-of-device-interface-arrival-and-device-removal.md b/windows-driver-docs-pr/install/registering-for-notification-of-device-interface-arrival-and-device-removal.md index 2ed7a816b4..77f643c7e3 100644 --- a/windows-driver-docs-pr/install/registering-for-notification-of-device-interface-arrival-and-device-removal.md +++ b/windows-driver-docs-pr/install/registering-for-notification-of-device-interface-arrival-and-device-removal.md @@ -29,6 +29,7 @@ Typically, a user-mode component calls [**CM\_Register\_Notification**](https:// 5. Use this table as you implement your device handle notification callback. +
@@ -48,20 +49,21 @@ Typically, a user-mode component calls [**CM\_Register\_Notification**](https:// +

First, unregister the notifications for your old handle by calling [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228). You must do this from a deferred routine because you cannot call CM_Unregister_Notification from a notification callback for the notification handle you are unregistering. See the Remarks section of [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) for more information.

+

Then, either continuing in the deferred routine, or back in your notification callback, call [CreateFile](https://msdn.microsoft.com/library/windows/desktop/aa363858) to create a new handle. Then call [CM_Register_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780224) with the new handle and CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE.

+

Note that if you register for notifications on a device that is in the process of being query removed after the CM_NOTIFY_ACTION_DEVICEQUERYREMOVE notifications have been sent, you may receive a CM_NOTIFY_ACTION_DEVICEQUERYREMOVEFAILED notification without first receiving a CM_NOTIFY_ACTION_DEVICEQUERYREMOVE notification.

- + - +
CM_NOTIFY_ACTION_DEVICEQUERYREMOVEFAILED

The query remove failed, so the device and its interface are still valid. To continue sending I/O to the interface, open a new handle to it.

-

First, unregister the notifications for your old handle by calling [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228). You must do this from a deferred routine because you cannot call CM_Unregister_Notification from a notification callback for the notification handle you are unregistering. You can use methods such as [TrySubmitThreadpoolCallback](https://msdn.microsoft.com/library/windows/desktop/ms686862) to defer this processing to another thread.

-

Then, either continuing in the deferred routine, or back in your notification callback, call [CreateFile](https://msdn.microsoft.com/library/windows/desktop/aa363858) to create a new handle. Then call [CM_Register_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780224) with the new handle and CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE.

CM_NOTIFY_ACTION_DEVICEREMOVEPENDING

Call [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) to unregister the notifications for your handle. You must do this from a deferred routine. You can use methods such as [TrySubmitThreadpoolCallback](https://msdn.microsoft.com/library/windows/desktop/ms686862) to defer this processing to another thread. If you still have an open handle to the device, call [CloseHandle](https://msdn.microsoft.com/library/windows/desktop/ms724211) to close the device handle.

Call [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) to unregister the notifications for your handle. You must do this from a deferred routine. See the Remarks section of [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) for more information. If you still have an open handle to the device, call [CloseHandle](https://msdn.microsoft.com/library/windows/desktop/ms724211) to close the device handle.

CM_NOTIFY_ACTION_DEVICEREMOVECOMPLETE

Call [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) to unregister the notifications for your handle. You must do this from a deferred routine. You can use methods such as [TrySubmitThreadpoolCallback](https://msdn.microsoft.com/library/windows/desktop/ms686862) to defer this processing to another thread. If you still have an open handle to the device, call [CloseHandle](https://msdn.microsoft.com/library/windows/desktop/ms724211) to close the device handle.

Call [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) to unregister the notifications for your handle. You must do this from a deferred routine. See the Remarks section of [CM_Unregister_Notification](https://msdn.microsoft.com/library/windows/hardware/hh780228) for more information. If you still have an open handle to the device, call [CloseHandle](https://msdn.microsoft.com/library/windows/desktop/ms724211) to close the device handle.

- +
  6. Once you are finished with the device, call [**CM\_Unregister\_Notification**](https://msdn.microsoft.com/library/windows/hardware/hh780228) to unregister the interface notification callback that you registered in step 1. diff --git a/windows-driver-docs-pr/install/retrieving-spcrp-xxx-properties.md b/windows-driver-docs-pr/install/retrieving-spcrp-xxx-properties.md index 1475847033..73fc5221a8 100644 --- a/windows-driver-docs-pr/install/retrieving-spcrp-xxx-properties.md +++ b/windows-driver-docs-pr/install/retrieving-spcrp-xxx-properties.md @@ -1,6 +1,6 @@ --- -title: Retrieving SPCRP\_Xxx Properties -description: Retrieving SPCRP\_Xxx Properties +title: Retrieving SPCRP_Xxx Properties +description: Retrieving SPCRP_Xxx Properties ms.assetid: a5d52da9-a593-42bd-aeaf-8ab203bc3d21 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/sample-inf-models-sections-for-one-or-more-target-operating-system.md b/windows-driver-docs-pr/install/sample-inf-models-sections-for-one-or-more-target-operating-system.md index 5099340cd8..c8c5dc663c 100644 --- a/windows-driver-docs-pr/install/sample-inf-models-sections-for-one-or-more-target-operating-system.md +++ b/windows-driver-docs-pr/install/sample-inf-models-sections-for-one-or-more-target-operating-system.md @@ -28,7 +28,7 @@ This topic shows a sample INF file that installs a driver package on various ope - [**INF CopyFiles directives**](inf-copyfiles-directive.md) that copies platform-specific files to the target x86- and AMD64-based systems. -``` syntax +``` [Version] Signature = "$Windows NT$" Class = Net diff --git a/windows-driver-docs-pr/install/setting-spcrp-xxx-properties.md b/windows-driver-docs-pr/install/setting-spcrp-xxx-properties.md index 81147be1d1..ed8a7f181b 100644 --- a/windows-driver-docs-pr/install/setting-spcrp-xxx-properties.md +++ b/windows-driver-docs-pr/install/setting-spcrp-xxx-properties.md @@ -1,6 +1,6 @@ --- -title: Setting SPCRP\_Xxx Properties -description: Setting SPCRP\_Xxx Properties +title: Setting SPCRP_Xxx Properties +description: Setting SPCRP_Xxx Properties ms.assetid: efb0d02e-ec4c-4c1b-900b-c81f504d2919 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/install/specifying-hardware-ids-for-a-computer.md b/windows-driver-docs-pr/install/specifying-hardware-ids-for-a-computer.md index d9f56b7c29..89a32666db 100644 --- a/windows-driver-docs-pr/install/specifying-hardware-ids-for-a-computer.md +++ b/windows-driver-docs-pr/install/specifying-hardware-ids-for-a-computer.md @@ -11,140 +11,25 @@ ms.technology: windows-devices # Specifying Hardware IDs for a Computer - -Devices and Printers recognizes the computer as a [device container](container-ids.md). As a result, the computer can be identified within a device metadata package by using a [**HardwareID**](https://msdn.microsoft.com/library/windows/hardware/ff546114) XML element that specifies a unique [hardware ID](hardware-ids.md) value. For the computer, this hardware ID value can specifies a combination of the System Management BIOS (SMBIOS) field data. +Devices and Printers recognizes the computer as a [device container](container-ids.md). As a result, the computer can be identified within a device metadata package by using a [**HardwareID**](https://msdn.microsoft.com/library/windows/hardware/ff546114) XML element that specifies a unique [hardware ID](hardware-ids.md) value. This hardware ID value for the computer (sometimes referred to as a computer hardware ID, or CHID) can specify a combination of the System Management BIOS (SMBIOS) field data. Unlike [hardware IDs](hardware-ids.md) for other device containers, the hardware ID for the computer is generated by Windows every time the system boots. The hardware IDs for a computer can be generated by running the ComputerHardwareIds tool (ComputerHardwareIDs.exe), which is included in the Windows Driver Kit (WDK) for Windows 7, Windows 8 and Windows 8.1. Beginning with Windows 10, the ComputerHardwareIds tool is included in the Software Development Kit (SDK). The ComputerHardwareIds tool generates a set of hardware IDs for the computer that is based on information from the fields in the system's System Management BIOS (SMBIOS). The following table describes these SMBIOS fields. - --------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameStructure name and typeSMBIOS specification versionOffsetLengthValueDescription

Manufacturer

System Information (Type 1)

2.0+

04h

BYTE

STRING

The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the name of the computer manufacturer.

Family

System Information (Type 1)

2.4+

1Ah

BYTE

STRING

The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the family to which a particular computer belongs.

-

A family refers to a set of computers that are similar but not identical from a hardware or software point of view.

-

Typically a family is composed of different computer models, which have different configurations and pricing points. Computers in the same family often have similar branding and cosmetic features.

Product Name

System Information (Type 1)

2.0+

05h

BYTE

STRING

The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the product name of the computer.

Vendor

BIOS Information (Type 0)

2.0+

04h

BYTE

STRING

The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the name of the BIOS vendor.

BIOS Version

BIOS Information (Type 0)

2.+0

05h

BYTE

STRING

The index of a null-terminated string within the dmiStrucBuffer array. This string can contain information about the processor core and OEM version.

System BIOS Major Release

BIOS Information (Type 0)

2.4+

14h

BYTE

Varies.

The major release of the system BIOS.

System BIOS Minor Release

BIOS Information (Type 0)

2.4+

15h

BYTE

Varies

The minor release of the system BIOS.

Enclosure type

System Enclosure (Type 3)

2.0+

05h

BYTE

Varies

The system enclosure or chassis types.

SKU Number

SKU Number (Type 1)

2.4+

19h

BYTE

STRING

The identification of a particular computer configuration for sale.

Baseboard Manufacturer

Manufacturer (Type 2)

04h

BYTE

STRING

Number of null-terminated string. This string identifies the Manufacturer of the Baseboard, where the Baseboard – Board Type is 0Ah (Motherboard).

Baseboard Product

Product (Type 2)

05h

BYTE

STRING

Number of null-terminated string. This string identifies the Product name of the Baseboard, where the Baseboard – Board Type is 0Ah (Motherboard).

- -  +|Field name|Structure name and type|SMBIOS specification version|Offset|Length|Value|Description| +|--- |--- |--- |--- |--- |--- |--- | +|Manufacturer|System Information (Type 1)|2.0+|04h|BYTE|STRING|The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the name of the computer manufacturer.| +|Family|System Information (Type 1)|2.4+|1Ah|BYTE|STRING|The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the family to which a particular computer belongs. A family refers to a set of computers that are similar but not identical from a hardware or software point of view. Typically a family is composed of different computer models, which have different configurations and pricing points. Computers in the same family often have similar branding and cosmetic features.| +|Product Name|System Information (Type 1)|2.0+|05h|BYTE|STRING|The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the product name of the computer.| +|Vendor|BIOS Information (Type 0)|2.0+|04h|BYTE|STRING|The index of a null-terminated string within the dmiStrucBuffer array. This string specifies the name of the BIOS vendor.| +|BIOS Version|BIOS Information (Type 0)|2.+0|05h|BYTE|STRING|The index of a null-terminated string within the dmiStrucBuffer array. This string can contain information about the processor core and OEM version.| +|System BIOS Major Release|BIOS Information (Type 0)|2.4+|14h|BYTE|Varies.|The major release of the system BIOS.| +|System BIOS Minor Release|BIOS Information (Type 0)|2.4+|15h|BYTE|Varies|The minor release of the system BIOS.| +|Enclosure type|System Enclosure (Type 3)|2.0+|05h|BYTE|Varies|The system enclosure or chassis types.| +|SKU Number|SKU Number (Type 1)|2.4+|19h|BYTE|STRING|The identification of a particular computer configuration for sale.| +|Baseboard Manufacturer|Manufacturer (Type 2)| |04h|BYTE|STRING|Number of null-terminated string. This string identifies the Manufacturer of the Baseboard, where the Baseboard – Board Type is 0Ah (Motherboard).| +|Baseboard Product|Product (Type 2)| |05h|BYTE|STRING|Number of null-terminated string. This string identifies the Product name of the Baseboard, where the Baseboard – Board Type is 0Ah (Motherboard).| For more information about the *dmiStrucBuffer* array and the SMBIOS fields, see the [System Management BIOS (SMBIOS)](http://go.microsoft.com/fwlink/p/?linkid=145867) specification on the Distributed Management Task Force (DMTF) website. diff --git a/windows-driver-docs-pr/install/summary-of-inf-directives.md b/windows-driver-docs-pr/install/summary-of-inf-directives.md index 792b91cbef..45c9f84ada 100644 --- a/windows-driver-docs-pr/install/summary-of-inf-directives.md +++ b/windows-driver-docs-pr/install/summary-of-inf-directives.md @@ -30,7 +30,7 @@ The particular INF section in which an **AddReg** (or **DelReg**) directive resi Additional *add-registry-sections* can set up registry information for vendor-supplied co-installers, for system-defined device interfaces (such as kernel streaming interfaces) exported to higher level drivers, for new device interfaces exported by an installed component for a given class of devices, for driver services, or (rarely) for a new setup class of devices if the INF has a **ClassInstall32** section. [**DelReg Directive**](inf-delreg-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   @@ -40,14 +40,14 @@ This directive references one or more *del-registry-section*s used to remove obs This directive references one or more *file-list-section*s specifying transfers of model/device-specific driver images and any other necessary files from the distribution media to the destination directory for each such file. Alternatively, this directive can specify a single file to be copied from the distribution media to the default destination directory. [**DelFiles Directive**](inf-delfiles-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This rarely used directive references one or more *file-list-section*s specifying files to be deleted from the target of the installation. [**RenFiles Directive**](inf-renfiles-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   @@ -59,7 +59,7 @@ This directive references at least a *service-install-section*, possibly with an INF files for most kinds of devices (those that install drivers) have an INF-writer-defined *service-install-section* to specify any dependencies on system-supplied drivers or services, during which stage of the system initialization process the supplied drivers should be loaded, and so forth. Many INF files for device drivers also have an INF-writer-defined *event-log-install-section* that is referenced by the **AddService** directive to set up event logging by the device driver. [**DelService Directive**](inf-delservice-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   @@ -69,35 +69,35 @@ This rarely used directive deletes a previously installed service. This directive references an *add-interface-section* in which one or more **AddReg** directives are specified referencing sections that set up the registry entries for the device interfaces supported by this device/driver. Optionally, such an *add-interface-section* can reference one or more additional sections that specify delete-registry, file-transfer, file-delete, and/or file-rename operations. [**BitReg Directive**](inf-bitreg-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This rarely used directive references one or more *bit-registry-section*s specifying existing REG\_BINARY-type value entries in the registry for which particular bits in the values are to be modified. [**LogConfig Directive**](inf-logconfig-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This directive references one or more *log-config-section*s that specify acceptable bus-relative and device-specific hardware configurations in an INF for devices that are detected (by PnP device enumerators) or manually installed. For example, INF files for non-PnP ISA, EISA, and MCA devices, which are manually installed, use this directive. (Also see [**INF DDInstall.LogConfigOverride Section**](inf-ddinstall-logconfigoverride-section.md).) [**UpdateInis Directive**](inf-updateinis-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This rarely used directive references one or more *update-ini-section*s specifying parts of a supplied INI file to be read during installation and, possibly specifying line-by-line modifications to be made in that INI file. [**UpdateIniFields Directive**](inf-updateinifields-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This rarely used directive references one or more *update-inifields-section*s specifying modifications to be made on fields within the lines of an INI file. [**Ini2Reg Directive**](inf-ini2reg-directive.md) -**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this directive is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   @@ -105,7 +105,7 @@ This rarely used directive references one or more *ini-to-registry-section*s spe The sections under which any of the directives in the previous list can be specified is system-determined. The basic form of each directive is shown in the formal syntax of the reference for each section, as for example: -``` syntax +``` [DDInstall] | [DDInstall.HW] | [DDInstall.CoInstallers] | [ClassInstall32] | [ClassInstall32.ntx86] | [ClassInstall32.ntia64] | [ClassInstall32.ntamd64] diff --git a/windows-driver-docs-pr/install/summary-of-inf-sections.md b/windows-driver-docs-pr/install/summary-of-inf-sections.md index 2c3673de64..a16e8cbf93 100644 --- a/windows-driver-docs-pr/install/summary-of-inf-sections.md +++ b/windows-driver-docs-pr/install/summary-of-inf-sections.md @@ -68,7 +68,7 @@ Starting with Microsoft Windows 2000, this section is required as an expansion o This optional section adds device-specific (and typically, driver-independent) information to the registry or removes such information from the registry, possibly for a multifunction device or to install one or more PnP filter drivers. [***DDInstall*.CoInstallers Section**](inf-ddinstall-coinstallers-section.md) -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   @@ -77,14 +77,14 @@ This optional section registers one or more device-specific co-installers suppli A co-installer is an IHV/OEM-provided Win32 DLL that typically writes additional configuration information to the registry or performs other installation tasks that require dynamically generated, machine-specific information that is not available when the device's INF file is created. For more information, see [Writing a Co-installer](writing-a-co-installer.md). [***DDInstall*.FactDef Section**](inf-ddinstall-factdef-section.md) -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   This section should be included in the INF file of any manually installed non-PnP device. It specifies the factory default hardware configuration settings, such as the bus-relative I/O ports, IRQ (if any), and so forth, for the card. [***DDInstall*.LogConfigOverride Section**](inf-ddinstall-logconfigoverride-section.md) -**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  If you are building a universal or mobile driver package, this section is not valid. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/updating-device-firmware-using-windows-update.md b/windows-driver-docs-pr/install/updating-device-firmware-using-windows-update.md new file mode 100644 index 0000000000..09ff374863 --- /dev/null +++ b/windows-driver-docs-pr/install/updating-device-firmware-using-windows-update.md @@ -0,0 +1,107 @@ +--- +title: Updating Device Firmware using Windows Update +description: This topic describes how to update your device's firmware using the Windows Update (WU) service. +ms.assetid: 778c5ab5-572f-43b9-8e9a-9dd608de17a9 +ms.author: windowsdriverdev +ms.date: 08/24/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Updating Device Firmware using Windows Update + +This topic describes how to update a removable or in-chassis device's firmware using the Windows Update (WU) service. For information about updating system firmware, see [Windows UEFI firmware update platform](../bringup/windows-uefi-firmware-update-platform.md). + +To do this, you'll provide an update mechanism, implemented as a device driver, that includes the firmware payload. If your device uses a vendor-supplied driver, you have the option of adding the firmware update logic and payload to your existing function driver, or providing a separate firmware update driver package. If your device uses a Microsoft-supplied driver, you must provide a separate firmware update driver package. In both cases, the firmware update driver package must be universal. For more info about universal drivers, see [Getting Started with Universal Windows drivers](../develop/getting-started-with-universal-drivers.md). The driver binary can use [KMDF](../wdf/index.md), [UMDF 2](../wdf/getting-started-with-umdf-version-2.md) or the [Windows Driver Model](https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/windows-driver-model). + +Because WU cannot execute software, the firmware update driver must hand the firmware to Plug and Play (PnP) for installation. + +## Firmware update driver actions + +Typically, the firmware update driver is a lightweight device driver that does the following: + +* At device start or in the driver's [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback function: + + 1. Identify the device to which it is attached. + 2. Determine whether the driver has a firmware version that is more recent than the version on the device. + 3. If a firmware update is necessary, set an event timer to schedule the update. + 4. Otherwise, do nothing until the driver is started again. + +* During system runtime: + + 1. If an update is queued, wait for a set of conditions to be met. + 2. When conditions are met, perform the firmware update on the device. + +## Firmware update driver contents + +Typically, the firmware update driver package contains the following: + +* [Universal Driver INF](using-a-universal-inf-file.md) +* Driver catalog +* Function driver (.sys or .dll) +* Firmware update payload binary + +Submit your firmware update package as a separate driver submission. + +## Adding firmware update logic to a vendor-supplied driver + +The existing function driver can implement the firmware update mechanism, as shown in the following diagram: + +![Using Windows Update to deliver firmware update via existing function driver](images/single-devnode.png) + +Alternatively, if you want to update the function driver and the firmware update driver separately, create a second device node, on which you will install the firmware update driver. The following diagram shows how one device can have two separate device nodes: + +![Using Windows Update to deliver firmware update via separate device node](images/two-devnodes.png) + +In this case, the function and firmware device nodes must have different hardware IDs in order to be targeted independently. + +There are a couple ways to create a second device node. Certain device types have the ability to expose a second device node on one physical device, such as USB. You can use this functionality to create a device node targetable by WU, and install a firmware update driver on it. Many device types, however, do not allow a single physical device to enumerate more than one device node. + +In this case, use an extension INF that specifies the [AddComponent](../install/inf-addcomponent-directive.md) directive to create a device node that can be targeted by Windows Update and install the firmware update driver on it. The following snippet from an INF file shows how you can do this: + +``` +[Manufacturer] +%Contoso%=Standard,NTamd64 +[Standard.NTamd64] +%DeviceName%=Device_Install, PCI\DEVICE_ID +[Device_Install.Components] +AddComponent=ComponentName,,AddComponentSection +[AddComponentSection] +ComponentIDs = ComponentDeviceId +``` + +In the above INF sample, `ComponentIDs = ComponentDeviceId` indicates that the child device will have a hardware ID of `SWC\ComponentDeviceId`. When installed, this INF creates the following device hierarchy: + +![Parent device, primary device, AddComponent device](images/component-device-hierarchy.png) + +For future firmware updates, update the INF and binary file containing the firmware payload. + +## Adding firmware update logic to a Microsoft-supplied driver + +To update firmware for devices that use a Microsoft-supplied driver, you need to create a second device node, as shown above. + +## Best practices + +* In your firmware update driver INF, specify [DIRID 13](using-dirids.md) to cause PnP to leave the files in the driver package in the DriverStore: + + ``` + [Firmware_AddReg] + ; Store location of firmware payload + HKR,,FirmwareFilename,,"%13%\firmware_payload.bin" + ``` + + PnP resolves this location when it installs the device. The driver can then open this registry key to determine the location of the payload. + +* Firmware update drivers should specify the following INF entries: + + ``` + Class=Firmware + ClassGuid={f2e7dd72-6468-4e36-b6f1-6488f42c1b52} + ``` + +* To locate another device node, the firmware driver should walk the device tree relative to itself, not by enumerating all device nodes for a match. A user may have plugged in multiple instances of the device, and the firmware driver should only update the device with which it is associated. Typically, the device node to be located is the parent or sibling of the device node on which the firmware driver is installed. For example, in the diagram above with two device nodes, the firmware update driver can look for a sibling device to find the function driver. In the diagram immediately above, the firmware driver can look for the parent device to find the primary device with which it needs to communicate. + +* The driver should be robust to multiple instances of the device being on the system, possibly with multiple different firmware versions. For example, there may be one instance of the device that has been connected and updated several times; a brand new device may then be plugged in which is several firmware versions old. This means that state (such as current version) must be stored against the device, and not in a global location. + +* If there is an existing method to update the firmware (EXE or co-installer, for example), you can largely reuse the update code within a UMDF driver. diff --git a/windows-driver-docs-pr/install/using-a-component-inf-file.md b/windows-driver-docs-pr/install/using-a-component-inf-file.md new file mode 100644 index 0000000000..4e24296b41 --- /dev/null +++ b/windows-driver-docs-pr/install/using-a-component-inf-file.md @@ -0,0 +1,163 @@ +--- +title: Using a Component INF File +description: Describes how to use software components to include user-mode software that is specific to a device. +ms.author: windowsdriverdev +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Component INF File + +If you want to include user-mode software for use with a device on Windows 10, you have the following options to create a [DCHU-compliant universal driver](../develop/getting-started-with-universal-drivers.md): + +|Method|Scenario| +|---|---| +|[Hardware support apps (HSA)](../devapps/creating-a-custom-capability-to-pair-driver-with-hsa.md) | Device add-on software packaged as a UWP app that is delivered and serviced from the Windows Store. Recommended approach. | +|Software components|Device add-on software is an MSI or EXE binary, a Win32 service, or software installed using AddReg and CopyFiles. Referenced binary only runs on desktop editions (Home, Pro, and Enterprise). The referenced binary will not run on Windows 10S.| + +A software component is a separate, standalone driver package that can install one or more software modules. The installed software enhances the value of the device, but is not necessary for basic device functionality and does not require an associated function driver service. + +This page provides guidelines for the use of software components. + +## Getting started + +To create components, an [extension INF file](using-an-extension-inf-file.md) specifies the [INF AddComponent directive](inf-addcomponent-directive.md) one or more times in the [INF DDInstall.Components](inf-ddinstall-components-section.md) section. For each software component referenced in an extension INF file, the system creates a virtual software-enumerated child device. More than one driver package can reference the same software component. + +Virtual device children can be updated independently just like any other device, as long as the parent device is started. We recommend separating functionality into as many different groupings as makes sense from a servicing perspective, and then creating one software component for each grouping. + +You'll provide an INF file for each software component. + +If your software component INF specifies the [**AddSoftware** directive](inf-addsoftware-directive.md), the component INF: + +* Must be a [universal INF file](../install/using-a-universal-inf-file.md). +* Must specify the **SoftwareComponent** setup class. + +You can specify the [**AddSoftware** directive](inf-addsoftware-directive.md) one or more times. + +Additionally, any INF (component or not) matching on a software component device: + +* Can specify Win32 user services using the [AddService directive](inf-addservice-directive.md). +* Can install software using the [INF AddReg directive](inf-addreg-directive.md) and the [INF CopyFiles directive](inf-copyfiles-directive.md). +* Does not require a function driver service. +* Can be uninstalled by the user independently from the parent device. + +You can find an [example of an component INF](https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_component/osrfx2_DCHU_component/osrfx2_DCHU_component.inx) in the [Driver package installation toolkit for universal drivers](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU). + +## Accessing a device from a software component + +To retrieve the device instance ID of a device that is associated with a software component, use the **SoftwareArguments** value in the [INF AddSoftware directive](inf-addsoftware-directive.md) section with the `<>` runtime context variable. + +The executable can then retrieve the device instance ID of the software component from its incoming argument list. + +Next, if the software component is targeting the Universal [target platform](../develop/windows-10-editions-for-universal-drivers.md), use the following procedure: + +1. Call [**CM_Locate_DevNode**](https://msdn.microsoft.com/library/windows/hardware/ff538742) with the device instance ID of the software component to retrieve a device handle. +2. Call [**CM_Get_Parent**](https://msdn.microsoft.com/library/windows/hardware/ff538610) to retrieve a handle to that device’s parent. This parent is the device that added the software component using the [INF AddComponent Directive](inf-addcomponent-directive.md). +3. Then, to retrieve the device instance ID of the parent, call [**CM_Get_Device_ID**](https://msdn.microsoft.com/library/windows/hardware/ff538405) on the handle from [**CM_Get_Parent**](https://msdn.microsoft.com/library/windows/hardware/ff538610). + +If the software component is targeting the Desktop [target platform](../develop/windows-10-editions-for-universal-drivers.md) only, use the following procedure: + +1. Call [**SetupDiCreateDeviceInfoList**](https://msdn.microsoft.com/library/windows/hardware/ff550956) to create an empty device information set. +2. Call [**SetupDiOpenDeviceInfo**](https://msdn.microsoft.com/library/windows/hardware/ff552071) with the software component device's device instance ID. +3. Call [**SetupDiGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff551963) with `DEVPKEY_Device_Parent` to retrieve the device instance ID of the parent. + +## Example + +The following example shows how you might use a software component to install a control panel using an executable for a graphics card. + +### Driver package INF file + +``` +[Version] +Signature = "$WINDOWS NT$" +Class = Extension +ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} +ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID +Provider = %CONTOSO% +DriverVer = 06/21/2006,1.0.0.0 +CatalogFile = ContosoGrfx.cat + +[Manufacturer] +%CONTOSO%=Contoso,NTx86 + +[Contoso.NTx86] +%ContosoGrfx.DeviceDesc%=ContosoGrfx, PCI\VEN0001&DEV0001 + +[ContosoGrfx.NT] +;empty + +[ContosoGrfx.NT.Components] +AddComponent = ContosoControlPanel,, Component_Inst + +[Component_Inst] +ComponentIDs = VID0001&PID0001&SID0001 + +[Strings] +CONTOSO = "Contoso Inc." +ContosoGrfx.DeviceDesc = "Contoso Graphics Card Extension" +``` + +### Software component INF file + +``` +[Version] +Signature = "$WINDOWS NT$" +Class = SoftwareComponent +ClassGuid = {5c4c3332-344d-483c-8739-259e934c9cc8} +Provider = %CONTOSO% +DriverVer = 06/21/2006,1.0.0.0 +CatalogFile = ContosoCtrlPnl.cat + +[SourceDisksNames] +1 = %Disk%,,,"" + +[SourceDisksFiles] +ContosoCtrlPnl.exe = 1 + +[DestinationDirs] +DefaultDestDir = 13 + +[Manufacturer] +%CONTOSO%=Contoso,NTx86 + +[Contoso.NTx86] +%ContosoCtrlPnl.DeviceDesc%=ContosoCtrlPnl, SWC\VID0001&PID0001&SID0001 + +[ContosoCtrlPnl.NT] +CopyFiles=ContosoCtrlPnl.NT.Copy + +[ContosoCtrlPnl.NT.Copy] +ContosoCtrlPnl.exe + +[ContosoCtrlPNl.NT.Services] +AddService = , %SPSVCINST_ASSOCSERVICE% + +[ContosoCtrlPnl.NT.Software] +AddSoftware = ContosoGrfx1CtrlPnl,, Software_Inst + +[Software_Inst] +SoftwareType = 1 +SoftwareBinary = %13%\ContosoCtrlPnl.exe +SoftwareArguments = <> +SoftwareVersion = 1.0.0.0 + +[Strings] +SPSVCINST_ASSOCSERVICE = 0x00000002 +CONTOSO = "Contoso" +ContosoCtrlPnl.DeviceDesc = "Contoso Control Panel" +``` + +The driver validation and submission process is the same for component INFs as for regular INFs. For more info, see [Windows HLK Getting Started](https://msdn.microsoft.com/library/windows/hardware/dn915002). + +For more info on setup classes, see [System-Defined Device Setup Classes Available to Vendors](https://msdn.microsoft.com/library/windows/hardware/ff553426). + +## See Also + +[INF AddComponent Directive](inf-addcomponent-directive.md) + +[INF AddSoftware directive](inf-addsoftware-directive.md) + +[INF DDInstall.Components Section](inf-ddinstall-components-section.md) + +[INF DDInstall.Software Section](inf-ddinstall-software-section.md) diff --git a/windows-driver-docs-pr/install/using-a-configurable-inf-file.md b/windows-driver-docs-pr/install/using-a-universal-inf-file.md similarity index 72% rename from windows-driver-docs-pr/install/using-a-configurable-inf-file.md rename to windows-driver-docs-pr/install/using-a-universal-inf-file.md index dc520acb95..b98432dc0a 100644 --- a/windows-driver-docs-pr/install/using-a-configurable-inf-file.md +++ b/windows-driver-docs-pr/install/using-a-universal-inf-file.md @@ -11,13 +11,11 @@ ms.technology: windows-devices # Using a Universal INF File - If you are building a universal or mobile driver package, you must use a universal INF file. If you are building a desktop driver package, you don't have to use a universal INF file, but doing so is recommended because of the performance benefits. A universal INF file uses a subset of the [INF syntax](inf-file-sections-and-directives.md) that is available to a Windows driver. A universal INF file installs a driver and configures device hardware, but does not perform any other action, such as running a co-installer. -## Why is a universal INF file required on OneCoreUAP-based, non-desktop editions of Windows? - +## Why is a universal INF file required on non-desktop editions of Windows? Some editions of Windows, such as Windows 10 Mobile, do not support the Plug and Play mechanism for driver installation. Therefore, driver installation takes place on an offline image of the target system. When Microsoft Visual Studio builds your driver for such a target system, it generates an XML-based configuration file that contains all of the registry settings to be applied. As a result, an INF file for such a system must perform only additive operations that do not depend on the runtime behavior of the system. An INF file with such restricted syntax is called a universal INF file. @@ -25,11 +23,10 @@ A universal INF file installs predictably, with the same result each time. The r As a result, a driver package with a universal INF file can be configured in advance and added to an offline system. -You can use the [InfVerif](https://msdn.microsoft.com/library/windows/hardware/dn929319) tool to test if your driver's INF file is universal. +You can use the [InfVerif](../devtest/infverif.md) tool to test if your driver's INF file is universal. ## Which INF sections are invalid in a universal INF file? - You can use any INF section in a universal INF file except for the following: - [**INF ClassInstall32 Section**](inf-classinstall32-section.md) @@ -60,29 +57,26 @@ You can use any INF directive in a universal INF file except for the following: The following directives are valid with some caveats: -- The [**INF AddReg Directive**](inf-addreg-directive.md) is valid only if entries in the specified *add-registry-section* have a *reg-root* value of **HKR**. +- The [**INF AddReg Directive**](inf-addreg-directive.md) is valid if entries in the specified *add-registry-section* have a *reg-root* value of **HKR**, or in the following cases: + - For registration of [Component Object Model](https://msdn.microsoft.com/en-us/library/ee663262(v=vs.85).aspx) (COM) objects, a key may be written under: + - HKCR + - HKLM\SOFTWARE\Classes + - For creation of [Hardware Media Foundation Transforms](https://msdn.microsoft.com/en-us/library/windows/desktop/ms703138.aspx) (MFTs), a key may be written under: + - HKLM\SOFTWARE\Microsoft\Windows Media Foundation + - HKLM\SOFTWARE\WOW6432Node\Microsoft\Windows Media Foundation + - HKLM\SOFTWARE\WOW3232Node\Microsoft\Windows Media Foundation - [**INF CopyFiles Directive**](inf-copyfiles-directive.md) is valid only if the [destination directory](inf-destinationdirs-section.md) is one of the following: - 11 (corresponds to %WINDIR%\\System32) - 12 (corresponds to %WINDIR%\\System32\\Drivers) - 13 (corresponds to the directory under %WINDIR%\\System32\\DriverStore\\FileRepository where the driver is stored) - **Note:** This location may not be valid on all SKUs + **Note:** 13 is only valid on Windows 10 products for a limited subset of device installation scenarios. Please consult guidance and samples for your specific device class for more details. - 10,SysWOW64 (corresponds to %WINDIR%\\SysWOW64) + - 10,*vendor-specific subdirectory name* + **Note:** In Windows 10 Fall Creators Update, using DIRID 10 with a vendor-specific subdirectory name is valid in a universal INF as measured using the [InfVerif](../devtest/infverif.md) tool. In later releases, this value may not be supported. We recommend moving to DIRID 13. -## Related topics - - -[Installing a Universal Windows driver](https://msdn.microsoft.com/windows-drivers/develop/installing_a_universal_driver) - -[InfVerif](https://msdn.microsoft.com/library/windows/hardware/dn929319) - -  - -  - - - - - +## See Also +* [Installing a Universal Windows driver](https://msdn.microsoft.com/windows-drivers/develop/installing_a_universal_driver) +* [InfVerif](https://msdn.microsoft.com/library/windows/hardware/dn929319) diff --git a/windows-driver-docs-pr/install/using-an-extension-inf-file.md b/windows-driver-docs-pr/install/using-an-extension-inf-file.md new file mode 100644 index 0000000000..5f0493f022 --- /dev/null +++ b/windows-driver-docs-pr/install/using-an-extension-inf-file.md @@ -0,0 +1,279 @@ +--- +title: Using an Extension INF File +description: Starting in Windows 10, you can extend a driver package INF file's functionality by providing an additional INF file called an extension INF. +ms.assetid: 124C4E58-7F06-46F5-B530-29A03FA75C0A +ms.author: windowsdriverdev +ms.date: 06/5/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using an Extension INF File + +Prior to Windows 10, Windows selected a single driver package to install for a given device. This resulted in large, complex driver packages that included code for all scenarios and configurations, and each minor update required an update to the entire driver package. Starting in Windows 10, you can split INF functionality into multiple components, each of which can be serviced independently. To extend a driver package INF file's functionality, provide an extension INF in a separate driver package. An extension INF: + +* Can be provided by a different company and updated independently from the base INF. +* Looks the same as a base INF, but can extend the base INF for customization or specialization. +* Enhances the value of the device, but is not necessary for the base driver to work. +* Must be a [universal INF file](../install/using-a-universal-inf-file.md). + +Every device must have one base INF, and can optionally have one or more extension INFs associated with it. + +Typical scenarios where you might use an extension INF include: + +* Modifying settings provided in a base INF, such as customizing the device friendly name or modifying a hardware configuration setting. +* Creating one or more software components by specifying the [INF AddComponent directive](inf-addcomponent-directive.md) and providing a [component INF file](using-a-component-inf-file.md). + +You can find sample code for these scenarios in the examples below on this page. Also see [Universal Driver Scenarios](../develop/universal-driver-scenarios.md), which describes how the [DCHU universal driver sample](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU) uses extension INFs. + +In the following diagram, two different companies have created separate driver packages for the same device, which are shown in the dotted lines. The first contains just an extension INF, and the second contains a component INF and a legacy software module. The diagram also shows how an extension INF can reference a component INF, which can in turn reference software modules to install. + +![Extension and Component INF Hierarchy](images/extension-component-inf-hierarchy.png) + +## How extension INF and base INF work together + +Settings in an extension INF are applied after settings in a base INF. As a result, if an extension INF and a base INF specify the same setting, the version in the extension INF is applied. Similarly, if the base INF changes, the extension INF remains and is applied over the new base INF. + +## Specifying ExtensionId + +When you write an extension INF, you generate a special GUID called the **ExtensionId**, which is an entry in the INF's **\[Version\]** section. + +The system identifies possible extension INFs for a specific device by matching the hardware ID and compatible IDs of the device to those specified in an extension INF in a [**Models**](inf-models-section.md) section that applies to that system. + +Among all possible extension INFs that specify the same **ExtensionId** value, the system selects only one to install and applies its settings over those of the base INF. The driver date and driver version specified in the INF are used, in that order, to choose the single INF between multiple extension INFs with the same **ExtensionId**. + +To illustrate, consider the following scenario that includes a hypothetical device for which there are three extension INFs: + +![Diagram showing how base INF and extension INFs are selected](images/extension-base-inf-example.png) + +The **ExtensionId** values are shown in curly brackets, and each driver's [rank](how-setup-ranks-drivers--windows-vista-and-later-.md) is shown in the banner ribbons. + +First, the system selects the driver with the most recent version and highest rank. + +Next, the system processes the available extension INFs. Two have **ExtensionId** value `{B}`, and one has **ExtensionId** value `{A}`. From the first two, let's say that driver date is the same. The next tiebreaker is driver version, so the system selects the extension INF with v2.0. + +The extension INF with the unique **ExtensionId** value is also selected. The system applies the base INF for the device, and then applies the two extension INFs for that device. + +Note that extension INF files are always applied after the base INF, but that there is no determined order in which the extension INFs are applied. + +## Creating an extension INF + +Here are the entries you need to define an INF as an extension INF. + +1. Specify these values for **Class** and **ClassGuid** in the [**Version**](inf-version-section.md) section. For more info on setup classes, see [System-Defined Device Setup Classes Available to Vendors](https://msdn.microsoft.com/library/windows/hardware/ff553426). + + ``` + [Version] + ... + Class = Extension + ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} + ``` + +2. Provide an **ExtensionId** entry in the [**\[Version\]**](inf-version-section.md) section. Generate a new GUID for the initial version of an extension INF, or reuse the last GUID for subsequent updates of the initial extension INF. + + ``` + ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID + ``` + +3. If you are updating an extension INF, keep the **ExtensionId** the same and increment the version or date (or both) specified by the [**DriverVer**](inf-driverver-directive.md) directive. For a given **ExtensionId** value, PnP selects the INF with the highest **DriverVer**. + +4. In the [**INF Models section**](inf-models-section.md), specify one or more hardware and compatible IDs that match those of the target device. Note that these hardware and compatible IDs do not need to match those of the base INF. Typically, an extension INF lists a more specific hardware ID than the base INF, with the goal of further specializing a specific driver configuration. However, the extension INF might list the same hardware ID as the base INF, for instance if the device is already very narrowly targeted, or if the base INF already lists the most specific hardware ID. In some cases, the extension INF might provide a less specific device ID, like a compatible ID, in order to customize a setting across a broader set of devices. + + ``` + [DeviceExtensions.NTamd64] + %Device.ExtensionDesc% = DeviceExtension_Install, USB\VID_XXXX&PID_XXXX&REV_XXXX + ``` + +5. Optionally, provide a **TargetComputers** section if you want to constrain which computers this INF can be installed on. You might do this if you are using extension INFs with less specific hardware IDs or compatible IDs that are applicable to a large number of devices. +6. Do not define a service with `SPSVCINST_ASSOCSERVICE`. However, an extension INF can define other services, such as a filter driver for the device. For more info about specifying services, see [**INF AddService Directive**](inf-addservice-directive.md). + +The driver validation and submission process is the same for extension INFs as for regular INFs. For more info, see [Windows HLK Getting Started](https://msdn.microsoft.com/library/windows/hardware/dn915002). + +## Example 1: Using an extension INF to set the device friendly name + +In one common scenario, a device manufacturer (IHV) provides a base driver and a base INF, and then a system builder (OEM) provides an extension INF that supplements and in some cases overrides the configuration and settings of the base INF. The following snippet is a complete extension INF that shows how to set the device friendly name. + +``` +[Version] +Signature = "$WINDOWS NT$" +Class = Extension +ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} +Provider = %CONTOSO% +ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID +DriverVer = 05/28/2013,1.0.0.0 +CatalogFile = delta.cat + +[Manufacturer] +%CONTOSO% = DeviceExtensions,NTamd64 + +[DeviceExtensions.NTamd64] +%Device.ExtensionDesc% = DeviceExtension_Install, USB\VID_XXXX&PID_XXXX&REV_XXXX + +[DeviceExtension_Install] +; No changes + +[DeviceExtension_Install.HW] +AddReg = FriendlyName_AddReg + +[FriendlyName_AddReg] +HKR,,FriendlyName,, "New Device Friendly Name" + +[Strings] +CONTOSO = "Contoso" +Device.ExtensionDesc = "Sample Device Extension" +``` + +## Example 2: Using an extension INF to install additional software + +The following snippet is a complete extension INF that is included the [Driver package installation toolkit for universal drivers](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU). This example uses [INF AddComponent directive](inf-addcomponent-directive.md) to create components that install a service and an executable. For more info about what you can do in a component INF, see [Using a Component INF File](using-a-component-inf-file.md). + +To access this file online, see [`osrfx2_DCHU_extension.inx`](https://github.com/Microsoft/Windows-driver-samples/blob/master/general/DCHU/osrfx2_DCHU_extension_loose/osrfx2_DCHU_extension/osrfx2_DCHU_extension.inx). + +``` +;/*++ +; +;Copyright (c) Microsoft Corporation. All rights reserved. +; +; THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY +; KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +; IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR +; PURPOSE. +; +;Module Name: +; +; osrfx2_DCHU_extension.INF +; +;Abstract: +; +; Extension inf for the OSR FX2 Learning Kit +; +;--*/ + +[Version] +Signature = "$WINDOWS NT$" +Class = Extension +ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} +Provider = %ManufacturerName% +ExtensionId = {3846ad8c-dd27-433d-ab89-453654cd542a} +CatalogFile = osrfx2_DCHU_extension.cat +DriverVer = 05/16/2017,15.14.36.721 + +[Manufacturer] +%ManufacturerName% = OsrFx2Extension, NT$ARCH$ + +[OsrFx2Extension.NT$ARCH$] +%OsrFx2.ExtensionDesc% = OsrFx2Extension_Install, USB\Vid_045e&Pid_94aa&mi_00 +%OsrFx2.ExtensionDesc% = OsrFx2Extension_Install, USB\Vid_0547&PID_1002 + +[OsrFx2Extension_Install.NT] +CopyInf=osrfx2_DCHU_usersvc.inf + +[OsrFx2Extension_Install.NT.HW] +AddReg = OsrFx2Extension_AddReg +AddReg = OsrFx2Extension_COMAddReg + +[OsrFx2Extension_AddReg] +HKR, OSR, "OperatingParams",, "-Extended" +HKR, OSR, "OperatingExceptions",, "x86" + +; Add all registry keys to successfully register the +; In-Process ATL COM Server MSFT Sample. +[OsrFx2Extension_COMAddReg] +HKCR,AppID\ATLDllCOMServer.DLL,AppID,,"{9DD18FED-55F6-4741-AF25-798B90C4AED5}" +HKCR,AppID\{9DD18FED-55F6-4741-AF25-798B90C4AED5},,,"ATLDllCOMServer" +HKCR,ATLDllCOMServer.SimpleObject,,,"SimpleObject Class" +HKCR,ATLDllCOMServer.SimpleObject\CLSID,,,"{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}" +HKCR,ATLDllCOMServer.SimpleObject\CurVer,,,"ATLDllCOMServer.SimpleObject.1" +HKCR,ATLDllCOMServer.SimpleObject.1,,,"SimpleObject Class" +HKCR,ATLDllCOMServer.SimpleObject.1\CLSID,,,"{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084},,,"SimpleObject Class" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\InprocServer32,,%REG_EXPAND_SZ%,"%%SystemRoot%%\System32\ATLDllCOMServer.dll" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\InprocServer32,ThreadingModel,,"Apartment" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\ProgID,,,"ATLDllCOMServer.SimpleObject.1" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\Programmable,,%FLG_ADDREG_KEYONLY% +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\TypeLib,,,"{9B23EFED-A0C1-46B6-A903-218206447F3E}" +HKCR,CLSID\{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}\VersionIndependentProgID,,,"ATLDllCOMServer.SimpleObject" + +[OsrFx2Extension_Install.NT.Components] +AddComponent = osrfx2_DCHU_component,,OsrFx2Extension_ComponentInstall +AddComponent = osrfx2_DCHU_usersvc,,OsrFx2Extension_ComponentInstall_UserSvc + +[OsrFx2Extension_ComponentInstall] +ComponentIds=VID_045e&PID_94ab + +[OsrFx2Extension_ComponentInstall_UserSvc] +ComponentIds=VID_045e&PID_94ac + +[Strings] +ManufacturerName = "Contoso" +OsrFx2.ExtensionDesc = "OsrFx2 DCHU Device Extension" +REG_EXPAND_SZ = 0x00020000 +FLG_ADDREG_KEYONLY = 0x00000010 +``` + +## Example 3: Using an extension INF to install a filter driver + +You can also use an extension INF to install a filter driver for a device that uses system-supplied device drivers. The extension INF specifies the hardware ID of the device, and provides the service and filter driver settings. + +The following code snippet shows how to use an extension INF to install a filter driver. + +``` +[Version] +Signature = "$WINDOWS NT$" +Class = Extension +ClassGuid = {e2f84ce7-8efa-411c-aa69-97454ca4cb57} +Provider = %CONTOSO% +ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID +DriverVer = 05/28/2013,1.0.0.0 +CatalogFile = delta.cat + +[Manufacturer] +%CONTOSO% = DeviceExtensions,NTx86 + +[DeviceExtensions.NTx86] +%Device.ExtensionDesc% = DeviceExtension_Install,USB\VID_XXXX&PID_XXXX&REV_XXXX + +[DeviceExtension_Install] +CopyFiles = Filter_CopyFiles + +[DeviceExtension_Install.HW] +AddReg = DeviceExtensionFilter_AddReg + +[DeviceExtensionFilter_AddReg] +HKR,,"UpperFilters",0x00010008,"fltsample" + +[DeviceExtension_Install.Services] +AddService = fltsample,,FilterService_Install + +[FilterService_Install] +DisplayName = %FilterSample.ServiceDesc% +ServiceType = 1 ; SERVICE_KERNEL_DRIVER +StartType = 3 ; SERVICE_DEMAND_START +ErrorControl = 1 ; SERVICE_ERROR_NORMAL +ServiceBinary = %12%\fltsample.sys + +[Filter_CopyFiles] +fltsample.sys + +[SourceDisksFiles] +fltsample.sys = 1 + +[SourceDisksNames] +1 = Disk + +[DestinationDirs] +Filter_CopyFiles = 12 + +[Strings] +CONTOSO = "Contoso" +Device.ExtensionDesc = "Sample Extension Device" +FilterSample.ServiceDesc = "Sample Upper Filter" +``` + +## Related topics + +* [Universal Driver Scenarios](../develop/universal-driver-scenarios.md) +* [Using a Universal INF File](using-a-universal-inf-file.md) +* [Getting Started with Universal Drivers](../develop/getting-started-with-universal-drivers.md) +* [Driver package installation toolkit for universal drivers](https://github.com/Microsoft/Windows-driver-samples/tree/master/general/DCHU) diff --git a/windows-driver-docs-pr/install/using-dirids.md b/windows-driver-docs-pr/install/using-dirids.md index 4c9002f3c3..ff9b3ce05d 100644 --- a/windows-driver-docs-pr/install/using-dirids.md +++ b/windows-driver-docs-pr/install/using-dirids.md @@ -99,7 +99,7 @@ The following table shows several commonly used *dirids*, and the directories th

13

-

Driver package's Driver Store directory.

+

Driver package's Driver Store directory.

For Windows 8.1 and later versions of Windows, specifies the path to the Driver Store directory where the driver package was imported.

@@ -142,7 +142,7 @@ The following table shows several commonly used *dirids*, and the directories th

51

-

Spool directory (not used for installing printer drivers − see Printer Dirids)

+

Spool directory (not used for installing printer drivers − see Printer Dirids)

52

diff --git a/windows-driver-docs-pr/install/writing-a-co-installer.md b/windows-driver-docs-pr/install/writing-a-co-installer.md index 3e9edf54ee..5ba79094f7 100644 --- a/windows-driver-docs-pr/install/writing-a-co-installer.md +++ b/windows-driver-docs-pr/install/writing-a-co-installer.md @@ -21,7 +21,7 @@ ms.technology: windows-devices ## -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/writing-a-device-installation-application.md b/windows-driver-docs-pr/install/writing-a-device-installation-application.md index a9e4a1e2ea..7be2eeb983 100644 --- a/windows-driver-docs-pr/install/writing-a-device-installation-application.md +++ b/windows-driver-docs-pr/install/writing-a-device-installation-application.md @@ -25,7 +25,7 @@ ms.technology: windows-devices ## -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/writing-class-installers-and-co-installers.md b/windows-driver-docs-pr/install/writing-class-installers-and-co-installers.md index 5efb1cffcd..484752faa6 100644 --- a/windows-driver-docs-pr/install/writing-class-installers-and-co-installers.md +++ b/windows-driver-docs-pr/install/writing-class-installers-and-co-installers.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Writing Class Installers and Co-Installers -**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-configurable-inf-file.md). +**Note**  Features described in this section are not supported in universal or mobile driver packages. See [Using a Universal INF File](using-a-universal-inf-file.md).   diff --git a/windows-driver-docs-pr/install/writing-inf-files.md b/windows-driver-docs-pr/install/writing-inf-files.md index 90d4bde39c..69e1835784 100644 --- a/windows-driver-docs-pr/install/writing-inf-files.md +++ b/windows-driver-docs-pr/install/writing-inf-files.md @@ -19,7 +19,7 @@ When you write an [INF file](inf-files.md) for your [driver package](driver-pack - An INF file must use valid structure and syntax to pass driver package validation checks at the beginning of the installation process. - Use the [ChkINF](https://msdn.microsoft.com/library/windows/hardware/ff543461) tool to validate the structure and syntax of INF files. + Use the [INFVerif](../devtest/infverif.md) tool to validate the structure and syntax of INF files. - An INF file must contain valid INF [**SourceDisksFiles**](inf-sourcedisksfiles-section.md) and [**SourceDisksNames**](inf-sourcedisksnames-section.md) sections. Starting with Windows Vista, the operating system does not copy the driver package into the [driver store](driver-store.md) unless these sections are present and filled in correctly. diff --git a/windows-driver-docs-pr/kernel/64-bit-compiler.md b/windows-driver-docs-pr/kernel/64-bit-compiler.md new file mode 100644 index 0000000000..6c16804ccf --- /dev/null +++ b/windows-driver-docs-pr/kernel/64-bit-compiler.md @@ -0,0 +1,130 @@ +--- +title: 64-Bit Compiler +author: windows-driver-content +description: 64-Bit Compiler +ms.assetid: c119d6b3-03e2-4ffc-b0a9-8077b141a2f1 +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows", "compilers WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# 64-Bit Compiler + + +## + + +After you convert your 32-bit driver source code to use the [new data types](the-new-data-types.md), you can use the 64-bit compiler to identify any type-related problems that you initially missed. The first time you compile this code for 64-bit Windows, the compiler might generate many pointer-truncation or type-mismatch warnings. Use these warnings as a guide to make your code more robust. It is good practice to eliminate all warnings, especially pointer-truncation warnings. + +The following is an example of such a warning: + +``` +warning C4311: 'type cast' : pointer truncation from 'unsigned char *' to 'unsigned long ' +``` + +For example, the following code can generate the C4311 warning: + +``` +buffer = (PUCHAR)srbControl; +(ULONG)buffer += srbControl->HeaderLength; +``` + +To correct the code, make the following changes: + +``` +buffer = (PUCHAR)srbControl; +(ULONG_PTR)buffer += srbControl->HeaderLength; +``` + +### Predefined macros + +The compiler defines the following macros to identify the platform. + + ++++ + + + + + + + + + + + + + + + + + + + + +
MacroMeaning

_WIN64

A 64-bit platform.

_WIN32

A 32-bit platform. This value is also defined by the 64-bit compiler for backward compatibility.

_WIN16

A 16-bit platform.

+ +  + +The following macros are specific to the architecture. + + ++++ + + + + + + + + + + + + + + + + +
MacroMeaning

_M_IA64

A 64-bit Intel platform.

_M_IX86

A 32-bit Intel platform.

+ +  + +Do not use these macros except with architecture-specific code. Instead, use \_WIN64, \_WIN32, and \_WIN16 whenever possible. + +### 64-Bit compiler switches and warnings + +There is a warning option to assist porting to 64-bit Windows. The -Wp64-W3 switch enables the following warnings: + +- **C4305**: Truncation warning. For example, "return": truncation from "unsigned int64" to "long." + +- **C4311**: Truncation warning. For example, "type cast": pointer truncation from "int\*\_ptr64" to "int." + +- **C4312**: Conversion to bigger-size warning. For example, "type cast": conversion from "int" to "int\*\_ptr64" of greater size. + +- **C4318**: Passing zero length. For example, passing constant zero as the length to the **memset** function. + +- **C4319**: Not operator. For example, "~": zero extending "unsigned long" to "unsigned \_int64" of greater size. + +- **C4313**: Calling the **printf** family of functions with conflicting conversion type specifiers and arguments. For example, "printf": "%p" in format string conflicts with argument 2 of type "\_int64." Another example is the call printf("%x", pointer\_value); this causes a truncation of the upper 32 bits. The correct call is printf("%p", pointer\_value). + +- **C4244**: Same as the existing warning C4242. For example, "return": conversion from "\_int64" to "unsigned int," possible loss of data. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%2064-Bit%20Compiler%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/TOC.md b/windows-driver-docs-pr/kernel/TOC.md new file mode 100644 index 0000000000..11e7a89796 --- /dev/null +++ b/windows-driver-docs-pr/kernel/TOC.md @@ -0,0 +1,774 @@ +# [Kernel-Mode Driver Architecture Design Guide](index.md) +## [Introduction to Windows Drivers](introduction-to-windows-drivers.md) +### [Overview of Windows Components](overview-of-windows-components.md) +### [Types of Windows Drivers](types-of-windows-drivers.md) +### [Design Goals for Kernel-Mode Drivers](design-goals-for-kernel-mode-drivers.md) +#### [Portable](portable.md) +#### [Configurable](configurable.md) +#### [Always Preemptible and Always Interruptible](always-preemptible-and-always-interruptible.md) +#### [Multiprocessor-Safe](multiprocessor-safe.md) +#### [Object-Based](object-based.md) +#### [Packet-Driven I/O with Reusable IRPs](packet-driven-i-o-with-reusable-irps.md) +#### [Supporting Asynchronous I/O](supporting-asynchronous-i-o.md) +### [Sample Kernel-Mode Drivers](sample-kernel-mode-drivers.md) +## [Kernel-Mode Managers and Libraries](kernel-mode-managers-and-libraries.md) +### [Windows Kernel-Mode Object Manager](windows-kernel-mode-object-manager.md) +### [Windows Kernel-Mode Memory Manager](windows-kernel-mode-memory-manager.md) +### [Windows Kernel-Mode Process and Thread Manager](windows-kernel-mode-process-and-thread-manager.md) +### [Windows Kernel-Mode I/O Manager](windows-kernel-mode-i-o-manager.md) +### [Windows Kernel-Mode Plug and Play Manager](windows-kernel-mode-plug-and-play-manager.md) +### [Windows Kernel-Mode Power Manager](windows-kernel-mode-power-manager.md) +### [Windows Kernel-Mode Configuration Manager](windows-kernel-mode-configuration-manager.md) +### [Windows Kernel-Mode Kernel Transaction Manager](windows-kernel-mode-kernel-transaction-manager.md) +### [Windows Kernel-Mode Security Reference Monitor](windows-kernel-mode-security-reference-monitor.md) +### [Windows Kernel-Mode Kernel Library](windows-kernel-mode-kernel-library.md) +### [Windows Kernel-Mode Executive Support Library](windows-kernel-mode-executive-support-library.md) +### [Windows Kernel-Mode Run-Time Library](windows-kernel-mode-run-time-library.md) +### [Windows Kernel-Mode Safe String Library](windows-kernel-mode-safe-string-library.md) +### [Windows Kernel-Mode DMA Library](windows-kernel-mode-dma-library.md) +### [Windows Kernel-Mode HAL Library](windows-kernel-mode-hal-library.md) +### [Windows Kernel-Mode CLFS Library](windows-kernel-mode-clfs-library.md) +### [Windows Kernel-Mode WMI Library](windows-kernel-mode-wmi-library.md) +## [Writing WDM Drivers](writing-wdm-drivers.md) +### [Windows Driver Model (WDM)](windows-driver-model.md) +#### [Introduction to WDM](introduction-to-wdm.md) +#### [Types of WDM Drivers](types-of-wdm-drivers.md) +##### [Bus Drivers](bus-drivers.md) +##### [Function Drivers](function-drivers.md) +##### [Filter Drivers](filter-drivers.md) +##### [WDM Driver Layers: An Example](wdm-driver-layers---an-example.md) +#### [Device Configurations and Layered Drivers](device-configurations-and-layered-drivers.md) +##### [Sample Device and Driver Configuration](sample-device-and-driver-configuration.md) +##### [Points to Consider When Adding Drivers](points-to-consider-when-adding-drivers.md) +#### [WDM Versions](wdm-versions.md) +##### [Determining the WDM Version](determining-the-wdm-version.md) +##### [Differences in WDM Versions](differences-in-wdm-versions.md) +### [Kernel-Mode Driver Components](kernel-mode-driver-components.md) +#### [Introduction to Standard Driver Routines](introduction-to-standard-driver-routines.md) +#### [Standard Driver Routine Requirements](standard-driver-routine-requirements.md) +#### [Introduction to Driver Objects](introduction-to-driver-objects.md) +##### [Driver Entry Points in Driver Objects](driver-entry-points-in-driver-objects.md) +##### [Other Standard Driver Routines](other-standard-driver-routines.md) +#### [Writing a DriverEntry Routine](writing-a-driverentry-routine.md) +##### [DriverEntry's Required Responsibilities](driverentry-s-required-responsibilities.md) +##### [DriverEntry's Optional Responsibilities](driverentry-s-optional-responsibilities.md) +##### [DriverEntry Return Values](driverentry-return-values.md) +#### [Writing a Reinitialize Routine](writing-a-reinitialize-routine.md) +#### [Writing an AddDevice Routine](writing-an-adddevice-routine.md) +##### [AddDevice Routines in Function or Filter Drivers](adddevice-routines-in-function-or-filter-drivers.md) +##### [AddDevice Routines in Bus Drivers](adddevice-routines-in-bus-drivers.md) +##### [Guidelines for Writing AddDevice Routines](guidelines-for-writing-adddevice-routines.md) +#### [Writing Dispatch Routines](writing-dispatch-routines.md) +##### [Dispatch Routine Functionality](dispatch-routine-functionality.md) +##### [Required Dispatch Routines](required-dispatch-routines.md) +##### [Optional Dispatch Routines](optional-dispatch-routines.md) +##### [Dispatch Routines and IRQLs](dispatch-routines-and-irqls.md) +##### [When to Check the Driver's I/O Stack Location](when-to-check-the-driver-s-i-o-stack-location.md) +##### [DispatchCreate, DispatchClose, and DispatchCreateClose Routines](dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md) +###### [Separate DispatchCreate and DispatchClose Routines](separate-dispatchcreate-and-dispatchclose-routines.md) +###### [A Single DispatchCreateClose Routine](a-single-dispatchcreateclose-routine.md) +###### [Rules for Implementing DispatchCreate, DispatchClose, and DispatchCreateClose Routines](rules-for-implementing-dispatchcreate--dispatchclose--and-dispatchcrea.md) +##### [DispatchCleanup Routines](dispatchcleanup-routines.md) +##### [DispatchRead, DispatchWrite, and DispatchReadWrite Routines](dispatchread--dispatchwrite--and-dispatchreadwrite-routines.md) +###### [Handling Transfers Asynchronously](handling-transfers-asynchronously.md) +###### [DispatchReadWrite Using Buffered I/O](dispatchreadwrite-using-buffered-i-o.md) +###### [DispatchReadWrite Using Direct I/O](dispatchreadwrite-using-direct-i-o.md) +###### [DispatchReadWrite in Higher-Level Drivers](dispatchreadwrite-in-higher-level-drivers.md) +###### [Summary of Read/Write Dispatch Routines](summary-of-read-write-dispatch-routines.md) +##### [DispatchDeviceControl and DispatchInternalDeviceControl Routines](dispatchdevicecontrol-and-dispatchinternaldevicecontrol-routines.md) +###### [DispatchDeviceControl in Lowest-Level Drivers](dispatchdevicecontrol-in-lowest-level-drivers.md) +###### [DispatchDeviceControl in Higher-Level Drivers](dispatchdevicecontrol-in-higher-level-drivers.md) +###### [Dispatch(Internal)DeviceControl in Class/Port Drivers](dispatch-internal-devicecontrol-in-class-port-drivers.md) +###### [Guidelines for Writing Dispatch(Internal)DeviceControl Routines](guidelines-for-writing-dispatch-internal-devicecontrol-routines.md) +##### [DispatchPnP Routines](dispatchpnp-routines.md) +##### [DispatchPower Routines](dispatchpower-routines.md) +##### [DispatchQueryInformation Routines](dispatchqueryinformation-routines.md) +##### [DispatchSetInformation Routines](dispatchsetinformation-routines.md) +##### [DispatchFlushBuffers Routines](dispatchflushbuffers-routines.md) +##### [DispatchShutdown Routines](dispatchshutdown-routines.md) +##### [DispatchSystemControl Routines](dispatchsystemcontrol-routines.md) +#### [Writing an Unload Routine](writing-an-unload-routine.md) +##### [Unload Routine Environment](unload-routine-environment.md) +##### [Unload Routine Functionality](unload-routine-functionality.md) +###### [PnP Driver's Unload Routine](pnp-driver-s-unload-routine.md) +###### [Non-PnP Driver's Unload Routine](non-pnp-driver-s-unload-routine.md) +###### [Releasing Driver-Allocated Resources](releasing-driver-allocated-resources.md) +###### [Releasing Device and Controller Objects](releasing-device-and-controller-objects.md) +### [Device Objects and Device Stacks](device-objects-and-device-stacks.md) +#### [Introduction to Device Objects](introduction-to-device-objects.md) +#### [WDM Device Objects and Device Stacks](wdm-device-objects-and-device-stacks.md) +##### [Types of WDM Device Objects](types-of-wdm-device-objects.md) +##### [Example WDM Device Objects](example-wdm-device-objects.md) +##### [When Are WDM Device Objects Created?](when-are-wdm-device-objects-created-.md) +##### [Example WDM Device Stack](example-wdm-device-stack.md) +#### [Creating a Device Object](creating-a-device-object.md) +#### [Initializing a Device Object](initializing-a-device-object.md) +#### [Named Device Objects](named-device-objects.md) +##### [NT Device Names](nt-device-names.md) +##### [MS-DOS Device Names](ms-dos-device-names.md) +###### [Introduction to MS-DOS Device Names](introduction-to-ms-dos-device-names.md) +###### [Local and Global MS-DOS Device Names](local-and-global-ms-dos-device-names.md) +#### [Device Extensions](device-extensions.md) +#### [Properties of Device Objects](properties-of-device-objects.md) +##### [Specifying Device Types](specifying-device-types.md) +##### [Specifying Device Characteristics](specifying-device-characteristics.md) +##### [Specifying Exclusive Access to Device Objects](specifying-exclusive-access-to-device-objects.md) +##### [Setting Device Object Properties in the Registry](setting-device-object-properties-in-the-registry.md) +###### [Setting Device Object Registry Properties During Installation](setting-device-object-registry-properties-during-installation.md) +###### [Setting Device Object Registry Properties After Installation](setting-device-object-registry-properties-after-installation.md) +#### [Securing Device Objects](securing-device-objects.md) +##### [Controlling Device Access](controlling-device-access.md) +##### [Controlling Device Namespace Access](controlling-device-namespace-access.md) +##### [SDDL for Device Objects](sddl-for-device-objects.md) +#### [Points to Consider About Device Objects](points-to-consider-about-device-objects.md) +### [Managing Kernel Objects](managing-kernel-objects.md) +#### [Object Names](object-names.md) +#### [Object Directories](object-directories.md) +#### [Life Cycle of an Object](life-cycle-of-an-object.md) +#### [Object Handles](object-handles.md) +#### [Object Security](object-security.md) +##### [Access Rights](access-rights.md) +##### [Security Descriptors](security-descriptors.md) +##### [Privileges](privileges.md) +### [Memory Management for Windows Drivers](managing-memory-for-drivers.md) +#### [Overview of Windows Memory Space](overview-of-windows-memory-space.md) +#### [Allocating System-Space Memory](allocating-system-space-memory.md) +#### [Map Registers](map-registers.md) +#### [Mapping Bus-Relative Addresses to Virtual Addresses](mapping-bus-relative-addresses-to-virtual-addresses.md) +#### [Using the Kernel Stack](using-the-kernel-stack.md) +#### [Using Lookaside Lists](using-lookaside-lists.md) +#### [Making Drivers Pageable](making-drivers-pageable.md) +##### [When Should Code and Data Be Pageable?](when-should-code-and-data-be-pageable-.md) +##### [Making Driver Code or Data Pageable](making-driver-code-or-data-pageable.md) +###### [Detecting Code That Can Be Pageable](detecting-code-that-can-be-pageable.md) +###### [Isolating Pageable Code](isolating-pageable-code.md) +###### [Locking Pageable Code or Data](locking-pageable-code-or-data.md) +###### [Paging an Entire Driver](paging-an-entire-driver.md) +#### [Accessing Read-Only System Memory](accessing-read-only-system-memory.md) +#### [Accessing User-Space Memory](accessing-user-space-memory.md) +#### [No-Execute (NX) Nonpaged Pool](no-execute-nonpaged-pool.md) +##### [NX and Execute Pool Types](nx-and-execute-pool-types.md) +##### [NX Pool Compatibility Issues](nx-pool-compatibility-issues.md) +##### [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md) +###### [Single Binary Opt-In: POOL_NX_OPTIN](single-binary-opt-in-pool-nx-optin.md) +###### [Multiple Binary Opt-In: POOL_NX_OPTIN_AUTO](multiple-binary-opt-in-pool-nx-optin-auto.md) +###### [Selective Opt-Out: POOL_NX_OPTOUT](selective-opt-out-pool-nx-optout.md) +#### [Section Objects and Views](section-objects-and-views.md) +##### [File-Backed and Page-File-Backed Sections](file-backed-and-page-file-backed-sections.md) +##### [Managing Memory Sections](managing-memory-sections.md) +##### [Security Issues for Section Objects and Views](security-issues-for-section-objects-and-views.md) +#### [Using MDLs](using-mdls.md) +### [Managing Input/Output for Drivers](managing-input-output-for-drivers.md) +#### [Handling IRPs](handling-irps.md) +##### [Overview of the Windows I/O Model](overview-of-the-windows-i-o-model.md) +##### [End-User I/O Requests and File Objects](end-user-i-o-requests-and-file-objects.md) +##### [The Life of an I/O Request](the-life-of-an-i-o-request.md) +###### [Example I/O Request - An Overview](example-i-o-request---an-overview.md) +###### [Example I/O Request - The Details](example-i-o-request---the-details.md) +###### [Driver Thread Context](driver-thread-context.md) +###### [Points to Consider about User I/O Requests](points-to-consider-about-user-i-o-requests.md) +##### [IRP Major Function Codes](irp-major-function-codes.md) +###### [IRP_MJ_CLEANUP](irp-mj-cleanup.md) +###### [IRP_MJ_CLOSE](irp-mj-close.md) +###### [IRP_MJ_CREATE](irp-mj-create.md) +###### [IRP_MJ_DEVICE_CONTROL](irp-mj-device-control.md) +###### [IRP_MJ_FILE_SYSTEM_CONTROL](irp-mj-file-system-control.md) +###### [IRP_MJ_FLUSH_BUFFERS](irp-mj-flush-buffers.md) +###### [IRP_MJ_INTERNAL_DEVICE_CONTROL](irp-mj-internal-device-control.md) +###### [IRP_MJ_PNP](irp-mj-pnp.md) +###### [IRP_MJ_POWER](irp-mj-power.md) +###### [IRP_MJ_QUERY_INFORMATION](irp-mj-query-information.md) +###### [IRP_MJ_READ](irp-mj-read.md) +###### [IRP_MJ_SET_INFORMATION](irp-mj-set-information.md) +###### [IRP_MJ_SHUTDOWN](irp-mj-shutdown.md) +###### [IRP_MJ_SYSTEM_CONTROL](irp-mj-system-control.md) +###### [IRP_MJ_WRITE](irp-mj-write.md) +##### [I/O Stack Locations](i-o-stack-locations.md) +##### [I/O Status Blocks](i-o-status-blocks.md) +##### [Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md) +##### [Creating IRPs for Lower-Level Drivers](creating-irps-for-lower-level-drivers.md) +##### [Queuing and Dequeuing IRPs](queuing-and-dequeuing-irps.md) +##### [Writing a StartIo Routine](writing-a-startio-routine.md) +###### [StartIo Routines in Lowest-Level Drivers](startio-routines-in-lowest-level-drivers.md) +###### [StartIo Routines in Higher-Level Drivers](startio-routines-in-higher-level-drivers.md) +###### [Points to Consider For StartIo Routines](points-to-consider-for-startio-routines.md) +##### [Driver-Managed IRP Queues](driver-managed-irp-queues.md) +###### [Setting Up and Using Device Queues](setting-up-and-using-device-queues.md) +###### [Managing Device Queues](managing-device-queues.md) +###### [Setting Up and Using Interlocked Queues](setting-up-and-using-interlocked-queues.md) +###### [Managing Interlocked Queues with a Driver-Created Thread](managing-interlocked-queues-with-a-driver-created-thread.md) +###### [Cancel-Safe IRP Queues](cancel-safe-irp-queues.md) +##### [Completing IRPs](completing-irps.md) +##### [When to Complete an IRP](when-to-complete-an-irp.md) +##### [Completing IRPs in Dispatch Routines](completing-irps-in-dispatch-routines.md) +###### [How to Complete an IRP in a Dispatch Routine](how-to-complete-an-irp-in-a-dispatch-routine.md) +###### [When to Complete an IRP in a Dispatch Routine](when-to-complete-an-irp-in-a-dispatch-routine.md) +##### [Using IoCompletion Routines](using-iocompletion-routines.md) +###### [Registering an IoCompletion Routine](registering-an-iocompletion-routine.md) +###### [Implementing an IoCompletion Routine](implementing-an-iocompletion-routine.md) +##### [Canceling IRPs](canceling-irps.md) +###### [Introduction to Cancel Routines](introduction-to-cancel-routines.md) +###### [Registering a Cancel Routine](registering-a-cancel-routine.md) +###### [Points to Consider When Canceling IRPs](points-to-consider-when-canceling-irps.md) +##### [Synchronizing IRP Cancellation](synchronizing-irp-cancellation.md) +###### [Using the System's Cancel Spin Lock](using-the-system-s-cancel-spin-lock.md) +###### [Synchronizing Cancellation in Driver Routines that Process IRPs](synchronizing-cancellation-in-driver-routines-that-process-irps.md) +###### [Synchronizing Cancellation in Higher-Level Drivers without Cancel Routines](synchronizing-cancellation-in-higher-level-drivers-without-cancel-rout.md) +###### [Using a Driver-Supplied Spin Lock](using-a-driver-supplied-spin-lock.md) +##### [Implementing a Cancel Routine](implementing-a-cancel-routine.md) +###### [Cancel Routines in Drivers with StartIo Routines](cancel-routines-in-drivers-with-startio-routines.md) +###### [Cancel Routines in Drivers without StartIo Routines](cancel-routines-in-drivers-without-startio-routines.md) +##### [Reusing IRPs](reusing-irps.md) +##### [Device Type-Specific I/O Requests](device-type-specific-i-o-requests.md) +##### [Using I/O Control Codes](using-i-o-control-codes.md) +###### [Introduction to I/O Control Codes](introduction-to-i-o-control-codes.md) +###### [Creating IOCTL Requests in Drivers](creating-ioctl-requests-in-drivers.md) +###### [Defining I/O Control Codes](defining-i-o-control-codes.md) +###### [Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md) +###### [Security Issues for I/O Control Codes](security-issues-for-i-o-control-codes.md) +##### [Using IRP Priority Hints](using-irp-priority-hints.md) +##### [IRP Processing Examples](irp-processing-examples.md) +###### [Processing IRPs in a Lowest-Level Driver](processing-irps-in-a-lowest-level-driver.md) +###### [Processing IRPs in an Intermediate-Level Driver](processing-irps-in-an-intermediate-level-driver.md) +#### [I/O Programming Techniques](i-o-programming-techniques.md) +#### [General I/O Programming Techniques](general-i-o-programming-techniques.md) +##### [Synchronous I/O Programming](synchronous-i-o-programming.md) +##### [Asynchronous I/O Programming](asynchronous-i-o-programming.md) +##### [Restricting Waits in Vista](restricting-waits-in-vista.md) +##### [Avoid Polling Devices](avoid-polling-devices.md) +##### [Maintaining Cache Coherency](maintaining-cache-coherency.md) +#### [Methods for Accessing Data Buffers](methods-for-accessing-data-buffers.md) +##### [Using Buffered I/O](using-buffered-i-o.md) +##### [Using Direct I/O](using-direct-i-o.md) +##### [Using Direct I/O with DMA](using-direct-i-o-with-dma.md) +##### [Using Direct I/O with PIO](using-direct-i-o-with-pio.md) +##### [Using Neither Buffered Nor Direct I/O](using-neither-buffered-nor-direct-i-o.md) +#### [DMA Programming Techniques](dma-programming-techniques.md) +##### [Flushing Cached Data during DMA Operations](flushing-cached-data-during-dma-operations.md) +##### [Splitting DMA Transfer Requests](splitting-dma-transfer-requests.md) +#### [Adapter Objects and DMA](adapter-objects-and-dma.md) +##### [Introduction to Adapter Objects](introduction-to-adapter-objects.md) +##### [Getting an Adapter Object](getting-an-adapter-object.md) +##### [Using Scatter/Gather DMA](using-scatter-gather-dma.md) +##### [Writing AdapterControl Routines](writing-adaptercontrol-routines.md) +###### [Storage Requirements for AdapterControl Routines](storage-requirements-for-adaptercontrol-routines.md) +###### [Setting Up AdapterControl Routines](setting-up-adaptercontrol-routines.md) +###### [AdapterControl Routine Requirements](adaptercontrol-routine-requirements.md) +#### [Using System DMA](using-system-dma.md) +##### [Using Packet-Based System DMA](using-packet-based-system-dma.md) +###### [Allocating an Adapter Channel for Packet-Based DMA](allocating-an-adapter-channel-for-packet-based-dma.md) +###### [Setting Up the System DMA Controller for Packet-Based DMA](setting-up-the-system-dma-controller-for-packet-based-dma.md) +##### [Using Common-Buffer System DMA](using-common-buffer-system-dma.md) +###### [Allocating an Adapter Channel for Common-Buffer System DMA](allocating-an-adapter-channel-for-common-buffer-system-dma.md) +###### [Setting Up the System DMA Controller for Common-Buffer DMA](setting-up-the-system-dma-controller-for-common-buffer-dma.md) +#### [Using Bus-Master DMA](using-bus-master-dma.md) +##### [Using Packet-Based Bus-Master DMA](using-packet-based-bus-master-dma.md) +###### [Allocating the Bus-Master Adapter Object](allocating-the-bus-master-adapter-object.md) +###### [Setting Up a Transfer Operation](setting-up-a-transfer-operation.md) +##### [Using Common-Buffer Bus-Master DMA](using-common-buffer-bus-master-dma.md) +#### [Version 3 of the DMA Operations Interface](version-3-of-the-dma-operations-interface.md) +##### [Basic Calling Pattern for Version-3 DMA Routines](basic-calling-pattern-for-version-3-dma-routines.md) +##### [Using the MapTransferEx Routine](using-the-maptransferex-routine.md) +#### [PIO Techniques](pio-techniques.md) +##### [Flushing Cached Data during PIO Operations](flushing-cached-data-during-pio-operations.md) +#### [Legacy I/O Programming](legacy-i-o-programming.md) +##### [Accessing Device Configuration Space](accessing-device-configuration-space.md) +###### [Obtaining Device Configuration Information at IRQL = PASSIVE_LEVEL](obtaining-device-configuration-information-at-irql---passive-level.md) +###### [Obtaining Device Configuration Information at IRQL = DISPATCH_LEVEL](obtaining-device-configuration-information-at-irql---dispatch-level.md) +###### [Obtaining Configuration Information from Other Driver Stacks](obtaining-configuration-information-from-other-driver-stacks.md) +##### [Using Controller Objects](using-controller-objects.md) +###### [Introduction to Controller Objects](introduction-to-controller-objects.md) +###### [Creating Controller Objects and Controller Extensions](creating-controller-objects-and-controller-extensions.md) +###### [Allocating Controller Objects for I/O Operations](allocating-controller-objects-for-i-o-operations.md) +##### [Writing ControllerControl Routines](writing-controllercontrolroutines.md) +###### [Storage Requirements for ControllerControl Routines](storage-requirements-for-controllercontrol-routines.md) +###### [Setting Up ControllerControl Routines](setting-up-controllercontrolroutines.md) +###### [ControllerControl Routine Requirements](controllercontrol-routine-requirements.md) +#### [Servicing Interrupts](servicing-interrupts.md) +##### [Interrupt Service Routines](interrupt-service-routines.md) +###### [Introduction to Interrupt Service Routines](introduction-to-interrupt-service-routines.md) +###### [Removing an ISR](removing-an-isr.md) +###### [Making an ISR Active or Inactive](making-an-isr-active-or-inactive.md) +###### [Interrupt Affinity](interrupt-affinity-and-priority.md) +###### [Providing ISR Context Information](providing-isr-context-information.md) +###### [Writing an ISR](writing-an-isr.md) +###### [Synchronizing Access to Device Data](synchronizing-access-to-device-data.md) +##### [Using Message-Signaled Interrupts](using-message-signaled-interrupts.md) +###### [Introduction to Message-Signaled Interrupts](introduction-to-message-signaled-interrupts.md) +###### [Enabling Message-Signaled Interrupts in the Registry](enabling-message-signaled-interrupts-in-the-registry.md) +###### [Using Interrupt Resource Descriptors](using-interrupt-resource-descriptors.md) +###### [Dynamically Configuring MSI-X](dynamically-configuring-msi-x.md) +##### [Registering an ISR](registering-an-isr.md) +###### [Using the CONNECT_LINE_BASED Version of IoConnectInterruptEx](using-the-connect-line-based-version-of-ioconnectinterruptex.md) +###### [Using the CONNECT_MESSAGE_BASED Version of IoConnectInterruptEx](using-the-connect-message-based-version-of-ioconnectinterruptex.md) +###### [Using the CONNECT_FULLY_SPECIFIED Version of IoConnectInterruptEx](using-the-connect-fully-specified-version-of-ioconnectinterruptex.md) +###### [Using Passive-Level Interrupt Service Routines](using-passive-level-interrupt-handling-routines.md) +###### [Using IoConnectInterruptEx Prior to Windows Vista](using-ioconnectinterruptex-prior-to-windows-vista.md) +##### [DPC Objects and DPCs](dpc-objects-and-dpcs.md) +###### [Introduction to DPC Objects](introduction-to-dpc-objects.md) +###### [Introduction to DPCs](introduction-to-dpcs.md) +###### [Which Type of DPC Should You Use?](which-type-of-dpc-should-you-use-.md) +###### [Registering and Queuing a DpcForIsr Routine](registering-and-queuing-a-dpcforisr-routine.md) +###### [Registering and Queuing a CustomDpc Routine](registering-and-queuing-a-customdpc-routine.md) +###### [Handling Overlapped I/O Operations](handling-overlapped-i-o-operations.md) +###### [Writing DPC Routines](writing-dpc-routines.md) +###### [Guidelines for Writing DPC Routines](guidelines-for-writing-dpc-routines.md) +###### [Organization of DPC Queues](organization-of-dpc-queues.md) +##### [Threaded DPCs](threaded-dpcs.md) +###### [Introduction to Threaded DPCs](introduction-to-threaded-dpcs.md) +###### [Synchronization and Threaded DPCs](synchronization-and-threaded-dpcs.md) +###### [Converting an Ordinary DPC to a Threaded DPC](converting-an-ordinary-dpc-to-a-threaded-dpc.md) +##### [Using Critical Sections](using-critical-sections.md) +###### [Introduction to SynchCritSection Routines](introduction-to-synchcritsection-routines.md) +###### [Writing SynchCritSection Routines](writing-synchcritsection-routines.md) +###### [Programming a Device for an I/O Operation](programming-a-device-for-an-i-o-operation.md) +###### [Accessing Shared State Information](accessing-shared-state-information.md) +##### [Managing Hardware Priorities](managing-hardware-priorities.md) +### [Implementing Plug and Play](implementing-plug-and-play.md) +#### [Introduction to Plug and Play](introduction-to-plug-and-play.md) +##### [PnP Components](pnp-components.md) +##### [Levels of Support for PnP](levels-of-support-for-pnp.md) +##### [PnP Driver Design Guidelines](pnp-driver-design-guidelines.md) +##### [Device Tree](device-tree.md) +##### [Hardware Resources](hardware-resources.md) +##### [State Transitions for PnP Devices](state-transitions-for-pnp-devices.md) +#### [Adding a PnP Device to a Running System](adding-a-pnp-device-to-a-running-system.md) +#### [Plug and Play Minor IRPs](plug-and-play-minor-irps.md) +##### [IRP_MN_CANCEL_REMOVE_DEVICE](irp-mn-cancel-remove-device.md) +##### [IRP_MN_CANCEL_STOP_DEVICE](irp-mn-cancel-stop-device.md) +##### [IRP_MN_DEVICE_ENUMERATED](irp-mn-device-enumerated.md) +##### [IRP_MN_DEVICE_USAGE_NOTIFICATION](irp-mn-device-usage-notification.md) +##### [IRP_MN_EJECT](irp-mn-eject.md) +##### [IRP_MN_FILTER_RESOURCE_REQUIREMENTS](irp-mn-filter-resource-requirements.md) +##### [IRP_MN_QUERY_BUS_INFORMATION](irp-mn-query-bus-information.md) +##### [IRP_MN_QUERY_CAPABILITIES](irp-mn-query-capabilities.md) +##### [IRP_MN_QUERY_DEVICE_RELATIONS](irp-mn-query-device-relations.md) +##### [IRP_MN_QUERY_DEVICE_TEXT](irp-mn-query-device-text.md) +##### [IRP_MN_QUERY_ID](irp-mn-query-id.md) +##### [IRP_MN_QUERY_INTERFACE](irp-mn-query-interface.md) +##### [IRP_MN_QUERY_LEGACY_BUS_INFORMATION](irp-mn-query-legacy-bus-information.md) +##### [IRP_MN_QUERY_PNP_DEVICE_STATE](irp-mn-query-pnp-device-state.md) +##### [IRP_MN_QUERY_REMOVE_DEVICE](irp-mn-query-remove-device.md) +##### [IRP_MN_QUERY_RESOURCE_REQUIREMENTS](irp-mn-query-resource-requirements.md) +##### [IRP_MN_QUERY_RESOURCES](irp-mn-query-resources.md) +##### [IRP_MN_QUERY_STOP_DEVICE](irp-mn-query-stop-device.md) +##### [IRP_MN_READ_CONFIG](irp-mn-read-config.md) +##### [IRP_MN_REMOVE_DEVICE](irp-mn-remove-device.md) +##### [IRP_MN_SET_LOCK](irp-mn-set-lock.md) +##### [IRP_MN_START_DEVICE](irp-mn-start-device.md) +##### [IRP_MN_STOP_DEVICE](irp-mn-stop-device.md) +##### [IRP_MN_SURPRISE_REMOVAL](irp-mn-surprise-removal.md) +##### [IRP_MN_WRITE_CONFIG](irp-mn-write-config.md) +#### [Passing PnP IRPs Down the Device Stack](passing-pnp-irps-down-the-device-stack.md) +#### [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md) +#### [Starting a Device](starting-a-device.md) +##### [Starting a Device in a Function Driver](starting-a-device-in-a-function-driver.md) +##### [Starting a Device in a Filter Driver](starting-a-device-in-a-filter-driver.md) +##### [Starting a Device in a Bus Driver](starting-a-device-in-a-bus-driver.md) +##### [Design Guidelines for Starting Devices](design-guidelines-for-starting-devices.md) +#### [Stopping a Device](stopping-a-device.md) +##### [Stopping a Device to Rebalance Resources](stopping-a-device-to-rebalance-resources.md) +##### [Stopping a Device to Disable It (Windows 98/Me)](stopping-a-device-to-disable-it--windows-98-me-.md) +##### [Stopping a Device after a Failed Start (Windows 98/Me)](stopping-a-device-after-a-failed-start--windows-98-me-.md) +##### [Handling Stop IRPs (Windows 2000 and Later)](handling-stop-irps--windows-2000-and-later-.md) +###### [Handling an IPR_MN_QUERY_STOP_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-query-stop-device-request--windows-2000-and-later-.md) +###### [Handling an IRP_MN_STOP_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-stop-device-request--windows-2000-and-later-.md) +###### [Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-cancel-stop-device-request--windows-2000-and-later-.md) +###### [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md) +##### [Handling Stop IRPs (Windows 98/Me)](handling-stop-irps--windows-98-me-.md) +###### [Handling an IRP_MN_QUERY_STOP_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-query-stop-device-request--windows-98-me-.md) +###### [Handling an IRP_MN_STOP_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-stop-device-request--windows-98-me-.md) +###### [Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-cancel-stop-device-request--windows-98-me-.md) +#### [Removing a Device](removing-a-device.md) +##### [Understanding When Remove IRPs Are Issued](understanding-when-remove-irps-are-issued.md) +##### [Handling an IRP_MN_QUERY_REMOVE_DEVICE Request](handling-an-irp-mn-query-remove-device-request.md) +##### [Handling an IRP_MN_REMOVE_DEVICE Request](handling-an-irp-mn-remove-device-request.md) +###### [Removing a Device in a Function Driver](removing-a-device-in-a-function-driver.md) +###### [Removing a Device in a Filter Driver](removing-a-device-in-a-filter-driver.md) +###### [Removing a Device in a Bus Driver](removing-a-device-in-a-bus-driver.md) +##### [Handling an IRP_MN_CANCEL_REMOVE_DEVICE Request](handling-an-irp-mn-cancel-remove-device-request.md) +##### [Handling an IRP_MN_SURPRISE_REMOVAL Request](handling-an-irp-mn-surprise-removal-request.md) +##### [Using Remove Locks](using-remove-locks.md) +#### [Using PnP Notification](using-pnp-notification.md) +##### [PnP Notification Overview](pnp-notification-overview.md) +##### [Guidelines for Writing PnP Notification Callback Routines](guidelines-for-writing-pnp-notification-callback-routines.md) +##### [Using PnP Device Interface Change Notification](using-pnp-device-interface-change-notification.md) +###### [Registering for Device Interface Change Notification](registering-for-device-interface-change-notification.md) +###### [Handling Device Interface Change Events](handling-device-interface-change-events.md) +##### [Using PnP Target Device Change Notification](using-pnp-target-device-change-notification.md) +###### [Registering for Target Device Change Notification](registering-for-target-device-change-notification.md) +###### [Handling a GUID_TARGET_DEVICE_QUERY_REMOVE Event](handling-a-guid-target-device-query-remove-event.md) +###### [Handling a GUID_TARGET_DEVICE_REMOVE_COMPLETE Event](handling-a-guid-target-device-remove-complete-event.md) +###### [Handling a GUID_TARGET_DEVICE_REMOVE_CANCELLED Event](handling-a-guid-target-device-remove-cancelled-event.md) +##### [Using PnP Hardware Profile Change Notification](using-pnp-hardware-profile-change-notification.md) +###### [Registering for Hardware Profile Change Notification](registering-for-hardware-profile-change-notification.md) +###### [Handling Hardware Profile Change Events](handling-hardware-profile-change-events.md) +##### [Using PnP Custom Notification](using-pnp-custom-notification.md) +### [Power Management for Windows Drivers](implementing-power-management.md) +#### [Introduction to Power Management](introduction-to-power-management.md) +##### [Industry Initiatives for Power Management](industry-initiatives-for-power-management.md) +##### [Support for Power Management](support-for-power-management.md) +##### [System-Wide Overview of Power Management](system-wide-overview-of-power-management.md) +##### [Power States](power-states.md) +#### [Kernel-Mode Power Management Components](kernel-mode-power-management-components.md) +##### [ACPI BIOS](acpi-bios.md) +##### [Acpi.sys: The Windows ACPI Driver](acpi-driver.md) +##### [Power Manager](power-manager.md) +##### [Driver Role in Power Management](driver-role-in-power-management.md) +#### [Power Management Responsibilities for Drivers](power-management-responsibilities-for-drivers.md) +##### [Reporting Device Power Capabilities](reporting-device-power-capabilities.md) +###### [DeviceD1 and DeviceD2](deviced1-and-deviced2.md) +###### [WakeFromD0, WakeFromD1, WakeFromD2, and WakeFromD3](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md) +###### [DeviceState](devicestate.md) +###### [SystemWake](systemwake.md) +###### [DeviceWake](devicewake.md) +###### [D1Latency, D2Latency, and D3Latency](d1latency--d2latency--and-d3latency.md) +##### [Setting Device Object Flags for Power Management](setting-device-object-flags-for-power-management.md) +##### [Handling Power IRPs](handling-power-irps.md) +###### [Power IRPs for the System](power-irps-for-the-system.md) +###### [Power IRPs for Individual Devices](power-irps-for-individual-devices.md) +##### [Power Management Minor IRPs](power-management-minor-irps.md) +###### [IRP_MN_POWER_SEQUENCE](irp-mn-power-sequence.md) +###### [IRP_MN_QUERY_POWER](irp-mn-query-power.md) +###### [IRP_MN_SET_POWER](irp-mn-set-power.md) +###### [IRP_MN_WAIT_WAKE](irp-mn-wait-wake.md) +##### [Powering Up a Device](powering-up-a-device.md) +##### [Powering Down a Device](powering-down-a-device.md) +##### [Enabling Device Wake-Up](enabling-device-wake-up.md) +##### [Managing Device Performance States](managing-device-performance-states.md) +##### [Distinguishing Fast Startup from Wake-from-Hibernation](distinguishing-fast-startup-from-wake-from-hibernation.md) +#### [Rules for Handling Power IRPs](rules-for-handling-power-irps.md) +##### [Calling IoCallDriver vs. Calling PoCallDriver](calling-iocalldriver-versus-calling-pocalldriver.md) +##### [Calling PoStartNextPowerIrp](calling-postartnextpowerirp.md) +###### [Calling PoStartNextPowerIrp from a Filter Driver](calling-postartnextpowerirp-from-a-filter-driver.md) +###### [Calling PoStartNextPowerIrp from a Device Power Policy Owner](calling-postartnextpowerirp-from-a-device-power-policy-owner.md) +###### [Calling PoStartNextPowerIrp from a Bus Driver](calling-postartnextpowerirp-from-a-bus-driver.md) +##### [Passing Power IRPs](passing-power-irps.md) +##### [Queuing I/O Requests While a Device Is Sleeping](queuing-i-o-requests-while-a-device-is-sleeping.md) +##### [Handling Unsupported or Unrecognized Power IRPs](handling-unsupported-or-unrecognized-power-irps.md) +##### [Calling ExSetTimerResolution While Processing a Power IRP](calling-exsettimerresolution-while-processing-a-power-irp.md) +#### [Managing Power for Individual Devices](managing-power-for-individual-devices.md) +##### [Device Power States](device-power-states.md) +###### [Device Working State D0](device-working-state-d0.md) +###### [Device Low-Power States](device-sleeping-states.md) +###### [Required Support for Device Power States](required-support-for-device-power-states.md) +##### [Managing Device Power Policy](managing-device-power-policy.md) +##### [Handling IRP_MN_SET_POWER for Device Power States](handling-irp-mn-set-power-for-device-power-states.md) +###### [Handling Device Power-Down IRPs](handling-device-power-down-irps.md) +###### [Handling Device Power-Up IRPs](handling-device-power-up-irps.md) +###### [IoCompletion Routines for Device Power IRPs](iocompletion-routines-for-device-power-irps.md) +##### [Handling IRP_MN_QUERY_POWER for Device Power States](handling-irp-mn-query-power-for-device-power-states.md) +##### [Sending IRP_MN_QUERY_POWER or IRP_MN_SET_POWER for Device Power States](sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md) +##### [Detecting an Idle Device](detecting-an-idle-device.md) +###### [Using Power Manager Routines for Idle Detection](using-power-manager-routines-for-idle-detection.md) +###### [Performing Device-Specific Idle Detection](performing-device-specific-idle-detection.md) +##### [Supporting D3cold in a Driver](supporting-d3cold-in-a-driver.md) +###### [Enabling Transitions to D3cold](enabling-transitions-to-d3cold.md) +###### [D3cold Capabilities of a Device](d3cold-capabilities-of-a-device.md) +###### [Using the GUID_D3COLD_SUPPORT_INTERFACE Driver Interface](using-guid-d3cold-support-interface.md) +###### [Surprise Wake-Up](surprise-wake-up.md) +#### [Handling System Power State Requests](handling-system-power-state-requests.md) +##### [System Power States](system-power-states.md) +###### [System Working State S0](system-working-state-s0.md) +###### [System Sleeping States](system-sleeping-states.md) +###### [System Shutdown State S5](system-shutdown-state-s5.md) +###### [System Power Actions](system-power-actions.md) +##### [System Power Policy](system-power-policy.md) +##### [Preventing System Power State Changes](preventing-system-power-state-changes.md) +##### [Handling IRP_MN_QUERY_POWER for System Power States](handling-irp-mn-query-power-for-system-power-states.md) +###### [Handling a System Query-Power IRP in a Device Power Policy Owner](handling-a-system-query-power-irp-in-a-device-power-policy-owner.md) +###### [Handling a System Query-Power IRP in a Filter or Function Driver](handling-a-system-query-power-irp-in-a-filter-or-function-driver.md) +###### [Failing a System Query-Power IRP in a Filter or Function Driver](failing-a-system-query-power-irp-in-a-filter-or-function-driver.md) +###### [Handling a System Query-Power IRP in a Bus Driver](handling-a-system-query-power-irp-in-a-bus-driver.md) +##### [Handling IRP_MN_SET_POWER for System Power States](handling-irp-mn-set-power-for-system-power-states.md) +###### [Handling a System Set-Power IRP in a Device Power Policy Owner](handling-a-system-set-power-irp-in-a-device-power-policy-owner.md) +###### [Determining the Correct Device Power State](determining-the-correct-device-power-state.md) +###### [Sending a Device Set-Power IRP in Response to a System Set-Power IRP](sending-a-device-set-power-irp-in-response-to-a-system-set-power-irp.md) +###### [Handling a System Set-Power IRP in a Bus Driver](handling-a-system-set-power-irp-in-a-bus-driver.md) +###### [Handling a System Set-Power IRP in a Filter Driver](handling-a-system-set-power-irp-in-a-filter-driver.md) +#### [Overview of the Power Management Framework](overview-of-the-power-management-framework.md) +##### [Component-Level Power Management](component-level-power-management.md) +##### [Component-Level Performance State Management](component-level-performance-management.md) +#### [Platform Extension Plug-ins (PEPs)](platform-extension-plug-ins--peps-.md) +##### [Using PEPs for ACPI services](using-peps-for-acpi-services.md) +##### [Platform Performance Thresholds](platform-performance-thresholds.md) +#### [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md) +##### [Overview of Wait/Wake Operation](overview-of-wait-wake-operation.md) +###### [Determining Whether a Device Can Wake the System](determining-whether-a-device-can-wake-the-system.md) +###### [Understanding the Path of Wait/Wake IRPs through a Device Tree](understanding-the-path-of-wait-wake-irps-through-a-device-tree.md) +###### [Overview of Wait/Wake IRP Completion](overview-of-wait-wake-irp-completion.md) +##### [Receiving a Wait/Wake IRP](receiving-a-wait-wake-irp.md) +###### [Handling a Wait/Wake IRP in a Function (FDO) or Filter Driver (Filter DO)](handling-a-wait-wake-irp-in-a-function--fdo--or-filter-driver--filter-.md) +###### [Handling a Wait/Wake IRP in a Bus Driver (PDO)](handling-a-wait-wake-irp-in-a-bus-driver--pdo-.md) +###### [IoCompletion Routines for Wait/Wake IRPs](iocompletion-routines-for-wait-wake-irps.md) +##### [Sending a Wait/Wake IRP](sending-a-wait-wake-irp.md) +###### [Determining When to Send a Wait/Wake IRP](determining-when-to-send-a-wait-wake-irp.md) +###### [Wait/Wake IRP Requests](wait-wake-irp-requests.md) +###### [Wait/Wake Callback Routines](wait-wake-callback-routines.md) +##### [Canceling a Wait/Wake IRP](canceling-a-wait-wake-irp.md) +#### [Improving System Startup Performance](improving-system-startup-performance.md) +##### [Sharing Processor Resources During Startup from a Low-Power State](sharing-processor-resources-during-startup-from-a-low-power-state.md) +##### [Fast Startup from a Low-Power State](fast-startup-from-a-low-power-state.md) +#### [Device-Level Thermal Management](device-level-thermal-management.md) +##### [Passive and Active Cooling Modes](passive-and-active-cooling-modes.md) +### [Implementing WMI](implementing-wmi.md) +#### [Introduction to WMI](introduction-to-wmi.md) +#### [WMI Architecture](wmi-architecture.md) +#### [WMI Requirements for WDM Drivers](wmi-requirements-for-wdm-drivers.md) +#### [MOF Syntax for WMI Data and Event Blocks](mof-syntax-for-wmi-data-and-event-blocks.md) +##### [WMI Class Qualifiers](wmi-class-qualifiers.md) +##### [WMI Class Names and Base Classes](wmi-class-names-and-base-classes.md) +##### [Required Items in WMI Classes](required-items-in-wmi-classes.md) +##### [WMI Property Qualifiers](wmi-property-qualifiers.md) +##### [Driver-Defined WMI Data Items](driver-defined-wmi-data-items.md) +##### [WMI Class Examples](wmi-class-examples.md) +#### [Designing WMI Data and Event Blocks](designing-wmi-data-and-event-blocks.md) +##### [Supporting Standard WMI Blocks](supporting-standard-wmi-blocks.md) +##### [Implementing Custom WMI Blocks](implementing-custom-wmi-blocks.md) +##### [Defining WMI Instance Names](defining-wmi-instance-names.md) +#### [Publishing a WMI Schema](publishing-a-wmi-schema.md) +##### [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md) +##### [Setting the MofImagePath Registry Value](setting-the-mofimagepath-registry-value.md) +##### [Implementing Dynamic MOF Data](implementing-dynamic-mof-data.md) +##### [Localizing MOF Files](localizing-mof-files.md) +###### [Creating the Localized MOF File](creating-the-localized-mof-file.md) +###### [Building and Deploying the Localized MOF File](building-and-deploying-the-localized-mof-file.md) +#### [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md) +##### [Using the WMI Library to Register Blocks](using-the-wmi-library-to-register-blocks.md) +##### [Handling IRP_MN_REGINFO and IRP_MN_REGINFO_EX to Register Blocks](handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md) +##### [WMI Registration Flags](wmi-registration-flags.md) +##### [Updating WMI Registration Information](updating-wmi-registration-information.md) +#### [Handling WMI Requests](handling-wmi-requests.md) +##### [WMI Minor IRPs](wmi-minor-irps.md) +###### [IRP_MN_CHANGE_SINGLE_INSTANCE](irp-mn-change-single-instance.md) +###### [IRP_MN_CHANGE_SINGLE_ITEM](irp-mn-change-single-item.md) +###### [IRP_MN_DISABLE_COLLECTION](irp-mn-disable-collection.md) +###### [IRP_MN_DISABLE_EVENTS](irp-mn-disable-events.md) +###### [IRP_MN_ENABLE_COLLECTION](irp-mn-enable-collection.md) +###### [IRP_MN_ENABLE_EVENTS](irp-mn-enable-events.md) +###### [IRP_MN_EXECUTE_METHOD](irp-mn-execute-method.md) +###### [IRP_MN_QUERY_ALL_DATA](irp-mn-query-all-data.md) +###### [IRP_MN_QUERY_SINGLE_INSTANCE](irp-mn-query-single-instance.md) +###### [IRP_MN_REGINFO](irp-mn-reginfo.md) +###### [IRP_MN_REGINFO_EX](irp-mn-reginfo-ex.md) +##### [Calling WmiSystemControl to Handle WMI IRPs](calling-wmisystemcontrol-to-handle-wmi-irps.md) +##### [Processing WMI IRPs in a DispatchSystemControl Routine](processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md) +##### [WMI WNODE_XXX Structures](wmi-wnode-xxx-structures.md) +#### [Sending WMI Events](sending-wmi-events.md) +##### [Sending an Event with WmiFireEvent](sending-an-event-with-wmifireevent.md) +##### [Sending an Event with IoWMIWriteEvent](sending-an-event-with-iowmiwriteevent.md) +##### [Using Custom WMI Events](using-custom-wmi-events.md) +#### [WMI Property Sheets](wmi-property-sheets.md) +##### [WMI Generic Property Page Provider](wmi-generic-property-page-provider.md) +##### [WMI and the Power Management Tab](wmi-and-the-power-management-tab.md) +#### [Using Wmimofck.exe](using-wmimofck-exe.md) +#### [WMI Event Tracing](wmi-event-tracing.md) +#### [Testing and Troubleshooting WMI Driver Support](testing-and-troubleshooting-wmi-driver-support.md) +##### [General Techniques for Testing WMI Driver Support](general-techniques-for-testing-wmi-driver-support.md) +##### [Troubleshooting Specific WMI Problems](troubleshooting-specific-wmi-problems.md) +## [Driver Programming Techniques](driver-programming-techniques.md) +### [Using Nt and Zw Versions of the Native System Services Routines](using-nt-and-zw-versions-of-the-native-system-services-routines.md) +#### [PreviousMode](previousmode.md) +#### [Libraries and Headers](libraries-and-headers.md) +#### [What Does the Zw Prefix Mean?](what-does-the-zw-prefix-mean-.md) +#### [Specifying Access Rights](access-mask.md) +#### [NtXxx Routines](ntxxx-routines.md) +### [Synchronization Techniques](synchronization-techniques.md) +#### [Kernel Dispatcher Objects](kernel-dispatcher-objects.md) +##### [Introduction to Kernel Dispatcher Objects](introduction-to-kernel-dispatcher-objects.md) +##### [Timer Objects](timer-objects.md) +##### [KeXxxTimer Routines, KTIMER Objects, and DPCs](timer-objects-and-dpcs.md) +###### [Using Timer Objects](using-timer-objects.md) +###### [Timer Accuracy](timer-accuracy.md) +###### [Registering and Queuing a CustomTimerDpc Routine](registering-and-queuing-a-customtimerdpc-routine.md) +###### [Providing CustomTimerDpc Context Information](providing-customtimerdpc-context-information.md) +###### [Using a CustomTimerDpc Routine](using-a-customtimerdpc-routine.md) +##### [ExXxxTimer Routines and EX_TIMER Objects](exxxxtimer-routines-and-ex-timer-objects.md) +###### [High-Resolution Timers](high-resolution-timers.md) +###### [No-Wake Timers](no-wake-timers.md) +###### [Deleting a System-Allocated Timer Object](deleting-a-system-allocated-timer-object.md) +##### [Event Objects](event-objects.md) +###### [Defining and Using an Event Object](defining-and-using-an-event-object.md) +###### [Standard Event Objects](standard-event-objects.md) +##### [Semaphore Objects](semaphore-objects.md) +##### [Mutex Objects](mutex-objects.md) +###### [Introduction to Mutex Objects](introduction-to-mutex-objects.md) +###### [Alternatives to Mutex Objects](alternatives-to-mutex-objects.md) +##### [Thread Objects](thread-objects.md) +###### [Introduction to Thread Objects](introduction-to-thread-objects.md) +###### [Thread Priorities](thread-priorities.md) +###### [Device-Dedicated Threads](device-dedicated-threads.md) +###### [System Worker Threads](system-worker-threads.md) +##### [Waits and APCs](waits-and-apcs.md) +#### [Callback Objects](callback-objects.md) +##### [Defining a Callback Object](defining-a-callback-object.md) +##### [Using a Driver-Defined Callback Object](using-a-driver-defined-callback-object.md) +##### [Using a System-Defined Callback Object](using-a-system-defined-callback-object.md) +#### [Spin Locks](spin-locks.md) +##### [Introduction to Spin Locks](introduction-to-spin-locks.md) +##### [Providing Storage for Spin Locks and Protected Data](providing-storage-for-spin-locks-and-protected-data.md) +##### [Initializing Spin Locks](initializing-spin-locks.md) +##### [Calling Support Routines That Use Spin Locks](calling-support-routines-that-use-spin-locks.md) +##### [Using Spin Locks: An Example](using-spin-locks--an-example.md) +##### [Preventing Errors and Deadlocks While Using Spin Locks](preventing-errors-and-deadlocks-while-using-spin-locks.md) +##### [Queued Spin Locks](queued-spin-locks.md) +##### [Reader/Writer Spin Locks](reader-writer-spin-locks.md) +#### [Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md) +#### [ERESOURCE Structures](eresource-structures.md) +##### [Introduction to ERESOURCE Routines](introduction-to-eresource-routines.md) +#### [Additional Timers and Counters](additional-timers-and-counters.md) +##### [IoTimer Routines](iotimer-routines.md) +###### [Registering and Enabling an IoTimer Routine](registering-and-enabling-an-iotimer-routine.md) +###### [Providing IoTimer Context Information](providing-iotimer-context-information.md) +###### [Using an IoTimer Routine](using-an-iotimer-routine.md) +##### [Counters](counters.md) +#### [Asynchronous Procedure Calls](asynchronous-procedure-calls.md) +##### [Types of APCs](types-of-apcs.md) +##### [Disabling APCs](disabling-apcs.md) +##### [Critical Regions and Guarded Regions](critical-regions-and-guarded-regions.md) +#### [Acquire and Release Semantics](acquire-and-release-semantics.md) +#### [Run-Down Protection](run-down-protection.md) +### [Using Common Log File System](using-common-log-file-system.md) +#### [Introduction to the Common Log File System](introduction-to-the-common-log-file-system.md) +#### [CLFS Terminology](clfs-terminology.md) +#### [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md) +#### [CLFS Marshalling Areas](clfs-marshalling-areas.md) +#### [Writing Data Records to a CLFS Stream](writing-data-records-to-a-clfs-stream.md) +#### [Writing Restart Records to a CLFS Stream](writing-restart-records-to-a-clfs-stream.md) +#### [Reading Data Records from a CLFS Stream](reading-data-records-from-a-clfs-stream.md) +#### [Reading Restart Records from a CLFS Stream](reading-restart-records-from-a-clfs-stream.md) +#### [CLFS Stable Storage](clfs-stable-storage.md) +#### [Dedicated CLFS Logs](dedicated-clfs-logs.md) +#### [Multiplexed CLFS Logs](multiplexed-clfs-logs.md) +#### [CLFS Support for Archiving](clfs-support-for-archiving.md) +### [Using Kernel Transaction Manager](using-kernel-transaction-manager.md) +#### [Introduction to KTM](introduction-to-ktm.md) +##### [When to Use Kernel-Mode KTM](when-to-use-kernel-mode-ktm.md) +##### [Transaction Processing Terms](transaction-processing-terms.md) +##### [Understanding TPS Components](understanding-tps-components.md) +##### [Additional Transactional Interfaces](additional-transactional-interfaces.md) +#### [KTM Objects](ktm-objects.md) +##### [Transaction Manager Objects](transaction-manager-objects.md) +##### [Resource Manager Objects](resource-manager-objects.md) +##### [Transaction Objects](transaction-objects.md) +##### [Enlistment Objects](enlistment-objects.md) +#### [Using KTM](using-ktm.md) +##### [Creating a Resource Manager](creating-a-resource-manager.md) +##### [Creating a Transactional Client](creating-a-transactional-client.md) +##### [Creating a Superior Transaction Manager](creating-a-superior-transaction-manager.md) +##### [Handling Transaction Operations](handling-transaction-operations.md) +###### [Handling Commit Operations](handling-commit-operations.md) +###### [Handling Rollback Operations](handling-rollback-operations.md) +###### [Handling Recovery Operations](handling-recovery-operations.md) +##### [Transaction Notifications](transaction-notifications.md) +##### [Using Log Streams with KTM](using-log-streams-with-ktm.md) +##### [Using Virtual Clock Values](using-virtual-clock-values.md) +##### [Using TmXxx Routines](using-tmxxx-routines.md) +### [Dynamic Hardware Partitioning Techniques](dynamic-hardware-partitioning-techniques.md) +#### [Introduction to Dynamic Hardware Partitioning](introduction-to-dynamic-hardware-partitioning.md) +#### [Dynamic Hardware Partitioning Architecture](dynamic-hardware-partitioning-architecture.md) +#### [Critical Issues for Device Drivers](critical-issues-for-device-drivers.md) +##### [Changes to the Number of Processors](changes-to-the-number-of-processors.md) +##### [Changes to the Amount of Physical Memory](changes-to-the-amount-of-physical-memory.md) +##### [Hot Replace of Partition Units](hot-replace-of-partition-units.md) +#### [Driver Notification](driver-notification.md) +##### [Introduction to Driver Notification](introduction-to-driver-notification.md) +##### [Synchronous Driver Notification](synchronous-driver-notification.md) +###### [Registering for Synchronous Driver Notification](registering-for-synchronous-driver-notification.md) +###### [Processing a Synchronous Driver Notification](processing-a-synchronous-driver-notification.md) +##### [Asynchronous Driver Notification](asynchronous-driver-notification.md) +###### [Registering for Asynchronous Driver Notification](registering-for-asynchronous-driver-notification.md) +###### [Processing an Asynchronous Driver Notification](processing-an-asynchronous-driver-notification.md) +#### [Application Notification](application-notification.md) +##### [Introduction to Application Notification](introduction-to-application-notification.md) +##### [Registering for Application Notification](registering-for-application-notification.md) +##### [Processing an Application Notification](processing-an-application-notification.md) +### [Miscellaneous Driver Programming Techniques](miscellaneous-driver-programming-techniques.md) +#### [NTSTATUS Values](ntstatus-values.md) +##### [Using NTSTATUS Values](using-ntstatus-values.md) +##### [Defining New NTSTATUS Values](defining-new-ntstatus-values.md) +#### [Singly and Doubly Linked Lists](singly-and-doubly-linked-lists.md) +#### [Handling Exceptions](handling-exceptions.md) +#### [Logging Errors](logging-errors.md) +##### [Writing to the System Event Log](writing-to-the-system-event-log.md) +##### [Defining Custom Error Types](defining-custom-error-types.md) +##### [Registering as a Source of Error Messages](registering-as-a-source-of-error-messages.md) +#### [Writing a Bug Check Callback Routine](writing-a-bug-check-callback-routine.md) +#### [Using Safe String Functions](using-safe-string-functions.md) +##### [Summary of Kernel-Mode Safe String Functions](summary-of-kernel-mode-safe-string-functions.md) +##### [Importing Kernel-Mode Safe String Functions](importing-kernel-mode-safe-string-functions.md) +#### [Using Safe Integer Functions](ntintsafe-design-guide.md) +##### [Summary of Kernel-Mode Safe Integer Functions](summary-of-safe-integer-functions.md) +##### [Importing Kernel-Mode Safe Integer Functions](importing-safe-integer-functions.md) +#### [Determining Whether the Operating System Is Running in Safe Mode](determining-whether-the-operating-system-is-running-in-safe-mode.md) +#### [Using GUIDs in Drivers](using-guids-in-drivers.md) +##### [Defining and Exporting New GUIDs](defining-and-exporting-new-guids.md) +##### [Including GUIDs in Driver Code](including-guids-in-driver-code.md) +#### [Using Floating Point in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md) +#### [Using Files In A Driver](using-files-in-a-driver.md) +##### [Opening a Handle to a File](opening-a-handle-to-a-file.md) +##### [Using a File Handle](using-a-file-handle.md) +##### [Using the Current File Position](using-the-current-file-position.md) +#### [Using the Registry in a Driver](using-the-registry-in-a-driver.md) +##### [Registry Key Object Routines](registry-key-object-routines.md) +###### [Opening a Handle to a Registry-Key Object](opening-a-handle-to-a-registry-key-object.md) +###### [Using a Handle to a Registry-Key Object](using-a-handle-to-a-registry-key-object.md) +##### [Registry Run-Time Library Routines](registry-run-time-library-routines.md) +##### [Plug and Play Registry Routines](plug-and-play-registry-routines.md) +#### [Supporting Removable Media](supporting-removable-media.md) +##### [Responding to Check-Verify Requests from the File System](responding-to-check-verify-requests-from-the-file-system.md) +##### [Notifying the File System of Possible Media Changes](notifying-the-file-system-of-possible-media-changes.md) +##### [Checking Flags in the Device Object](checking-flags-in-the-device-object.md) +##### [Setting up IRPs in Intermediate Drivers](setting-up-irps-in-intermediate-drivers.md) +#### [Creating Export Drivers](creating-export-drivers.md) +#### [Creating Reliable Kernel-Mode Drivers](creating-reliable-kernel-mode-drivers.md) +##### [Failure to Validate Device Objects](failure-to-validate-device-objects.md) +##### [Failure to Validate Object Handles](failure-to-validate-object-handles.md) +##### [Errors in a Multiprocessor Environment](errors-in-a-multiprocessor-environment.md) +##### [Failure to Check a Driver's State](failure-to-check-a-driver-s-state.md) +##### [Errors in Buffered I/O](errors-in-buffered-i-o.md) +###### [Failure to Check the Size of Buffers](failure-to-check-the-size-of-buffers.md) +###### [Failure to Initialize Output Buffers](failure-to-initialize-output-buffers.md) +###### [Failure to Validate Variable-Length Buffers](failure-to-validate-variable-length-buffers.md) +##### [Errors in Direct I/O](errors-in-direct-i-o.md) +##### [Errors in Referencing User-Space Addresses](errors-in-referencing-user-space-addresses.md) +##### [Errors in Handling Cleanup and Close Operations](errors-in-handling-cleanup-and-close-operations.md) +##### [Additional Errors in Handling IRPs](additional-errors-in-handling-irps.md) +#### [Hiding Devices from Device Manager](hiding-devices-from-device-manager.md) +#### [Filtering Registry Calls](filtering-registry-calls.md) +##### [Registering for Notifications](registering-for-notifications.md) +##### [Handling Notifications](handling-notifications.md) +##### [Supporting Layered Registry Filtering Drivers](supporting-layered-registry-filtering-drivers.md) +##### [Specifying Context Information](specifying-context-information.md) +##### [Obtaining Additional Registry Information](obtaining-additional-registry-information.md) +##### [Invalid Key Object Pointers in Registry Notifications](invalid-key-object-pointers-in-registry-notifications.md) +##### [Filtering Registry Operations on Application Hives](filtering-registry-operations-on-application-hives.md) +#### [Object Reference Tracing with Tags](object-reference-tracing-with-tags.md) +#### [Programming Issues for 64-Bit Drivers](programming-issues-for-64-bit-drivers.md) +##### [Porting Your Driver to 64-Bit Windows](porting-your-driver-to-64-bit-windows.md) +###### [What's Changed](what-s-changed.md) +###### [The New Data Types](the-new-data-types.md) +###### [64-Bit Compiler](64-bit-compiler.md) +###### [Performing DMA in 64-Bit Windows](performing-dma-in-64-bit-windows.md) +###### [Using extended processor features in Windows drivers](floating-point-support-for-64-bit-drivers.md) +###### [Porting Issues Checklist](porting-issues-checklist.md) +##### [Supporting 32-Bit I/O in Your 64-Bit Driver](supporting-32-bit-i-o-in-your-64-bit-driver.md) +###### [Why Thunking Is Necessary](why-thunking-is-necessary.md) +###### [Which Data Types Need Thunking](which-data-types-need-thunking.md) +###### [How Drivers Identify 32-Bit Callers](how-drivers-identify-32-bit-callers.md) +###### [Technique 1: Defining a 64Bit Field](technique-1--defining-a--64bit--field.md) +###### [Technique 2: Using IoIs32bitProcess](technique-2--using-iois32bitprocess.md) +###### [Extended Example: Defining a 64Bit Field](extended-example--defining-a--64bit--field.md) +###### [Extended Example: Using IoIs32bitProcess](extended-example--using-iois32bitprocess.md) +###### [Avoiding Misalignment of Fixed-Precision Data Types](avoiding-misalignment-of-fixed-precision-data-types.md) +##### [Driver x64 Restrictions](driver-x64-restrictions.md) +#### [Obsolete and Reserved Kernel Programming Interfaces](obsolete-and-reserved-kernel-programming-interfaces.md) +##### [Windows kernel obsolete macros](compute-pages-spanned.md) +##### [Windows kernel obsolete routines](mmcreatemdl.md) +##### [Windows kernel routines reserved for system use](ioacquireremovelockex.md) +##### [Windows kernel run-time library obsolete routines](rtlenlargedintegermultiply.md) +#### [Kernel Macros, Global Variables, and Opaque Structures](kernel-macros--global-variables--and-opaque-structures.md) +##### [Windows kernel global variables](mm64bitphysicaladdress.md) +##### [Windows kernel macros](mm-bad-pointer.md) +##### [Windows kernel opaque structures](eprocess.md) + diff --git a/windows-driver-docs-pr/kernel/a-single-dispatchcreateclose-routine.md b/windows-driver-docs-pr/kernel/a-single-dispatchcreateclose-routine.md new file mode 100644 index 0000000000..b5e68203fd --- /dev/null +++ b/windows-driver-docs-pr/kernel/a-single-dispatchcreateclose-routine.md @@ -0,0 +1,56 @@ +--- +title: A Single DispatchCreateClose Routine +author: windows-driver-content +description: A Single DispatchCreateClose Routine +ms.assetid: 6127d696-2409-49fc-9cbd-ba1b13c0c672 +keywords: ["dispatch routines WDK kernel , DispatchCreateClose routine", "DispatchCreateClose routine", "IRP_MJ_CREATE I/O function code", "IRP_MJ_CLOSE I/O function code", "create dispatch routines WDK kernel", "close dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# A Single DispatchCreateClose Routine + + +## + + +Many drivers, particularly lower-level drivers in a chain of layered drivers, merely need to establish their existence on receipt of a *create* request and merely need to acknowledge the receipt of a *close* request. + +For example, a port driver for a device controller with one or more closely coupled class drivers that call [**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198) might have a minimal [*DispatchCreateClose*](https://msdn.microsoft.com/library/windows/hardware/ff543270) routine. The routine might do nothing more than complete the IRP as follows: + +``` + : : +{ + Irp->IoStatus.Status = STATUS_SUCCESS; + Irp->IoStatus.Information = 0; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + return STATUS_SUCCESS; +} +``` + +This minimal *DispatchCreateClose* routine sets the **Information** member of the I/O status block to zero, indicating the file object is opened for a create request; **Information** has no meaning for a close request. The routine sets the **Status** member to STATUS\_SUCCESS and also returns this status value, indicating that the driver is ready to accept I/O requests. + +This minimal *DispatchCreateClose* routine completes the create IRP without boosting the priority of the originator of the IRP (IO\_NO\_INCREMENT), because the originator is assumed to wait for an indeterminate but very small interval for the request to complete. + +How much work a *DispatchCreateClose* routine does depends partly on the nature of the driver's device or the underlying device and partly on the design of the driver. If a driver performs very different operations for create and close requests, it should handle these requests in [separate DispatchCreate and DispatchClose routines](separate-dispatchcreate-and-dispatchclose-routines.md). + +To handle a create request to open a file object representing a logical or physical device, a highest-level driver should do the following: + +1. Call [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) to get a pointer to its I/O stack location in the IRP. + +2. Check **FileObject**.**FileName** in the I/O stack location and complete the IRP with STATUS\_SUCCESS if the Unicode string at **FileName** has a zero length; otherwise, complete the IRP with STATUS\_INVALID\_PARAMETER. + +Following the preceding steps ensures that no attempt to open a pseudofile on a device can cause problems later. For example, this prevents attempts to open a nonexistent \\\\device\\parallel0\\temp.dat. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20A%20Single%20DispatchCreateClose%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/access-mask.md b/windows-driver-docs-pr/kernel/access-mask.md new file mode 100644 index 0000000000..b8deca7c64 --- /dev/null +++ b/windows-driver-docs-pr/kernel/access-mask.md @@ -0,0 +1,151 @@ +--- +title: Specifying Access Rights +author: windows-driver-content +description: Specifying Access Rights +ms.assetid: 8ef4b4bb-5f4e-4095-b4ab-1182c0f75619 +--- + +# Specifying Access Rights + + +The ACCESS\_MASK type is a bitmask that specifies a set of access rights in the [access mask](https://msdn.microsoft.com/library/windows/hardware/ff538834) of an [access control entry](https://msdn.microsoft.com/library/windows/hardware/ff538813). + +``` syntax +typedef ULONG ACCESS_MASK; +``` + +The following standard specific access rights apply to all types of executive objects. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription

DELETE

The caller can delete the object.

READ_CONTROL

The caller can read the access control list (ACL) and ownership information for the file.

SYNCHRONIZE

The caller can perform a wait operation on the object. (For example, the object can be passed to [KeWaitForMultipleObjects](https://msdn.microsoft.com/library/windows/hardware/ff553324).)

WRITE_DAC

The caller can change the discretionary access control list (DACL) information for the object.

WRITE_OWNER

The caller can change the ownership information for the file.

+ +  + +Note that normally only DELETE and SYNCHRONIZE are of interest to driver writers. + +You can also specify the following generic access rights. These also apply to all types of executive objects. The meaning of each generic access right is specific to that type of object. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription

GENERIC_READ

The caller can perform normal read operations on the object.

GENERIC_WRITE

The caller can perform normal write operations on the object.

GENERIC_EXECUTE

The caller can execute the object. (Note this generally only makes sense for certain kinds of objects, such as file objects and section objects.)

GENERIC_ALL

The caller can perform all normal operations on the object.

+ +  + +The following combinations of standard specific access rights are also defined. These are not normally used directly, but are used as templates to define other bitmasks. (For example, when you specify GENERIC\_READ for a file object, the system maps this to the FILE\_GENERIC\_READ bitmask of specific access rights. FILE\_GENERIC\_READ is defined in terms of STANDARD\_RIGHTS\_READ.) + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitmaskDescription

STANDARD_RIGHTS_READ

Standard specific rights that correspond to GENERIC_READ

STANDARD_RIGHTS_WRITE

Standard specific rights that correspond to GENERIC_WRITE

STANDARD_RIGHTS_EXECUTE

Standard specific rights that correspond to GENERIC_EXECUTE

STANDARD_RIGHTS_REQUIRED

Standard specific rights that correspond to GENERIC_ALL. This includes DELETE, but not SYNCHRONIZE.

STANDARD_RIGHTS_ALL

All standard access rights.

+ +  + +Each type of object can have its own additional access rights. For a description of the access rights that are applicable to a file, directory, or device, see [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424). For a description of the access rights that are applicable to an object manager directory, see [**ZwCreateDirectoryObject**](https://msdn.microsoft.com/library/windows/hardware/ff566421). For a description of the access rights that are applicable to a registry key, see [**ZwCreateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566425). For a description of the access rights that are applicable to a section object, see [**ZwOpenSection**](https://msdn.microsoft.com/library/windows/hardware/ff567029). For a description of the access rights that are applicable to a WMI data block, see [**IoWMIOpenBlock**](https://msdn.microsoft.com/library/windows/hardware/ff550453). + +For more information about access rights, see the following topics in the Microsoft Windows SDK documentation: + +- [Access Rights and Access Masks](https://msdn.microsoft.com/library/windows/desktop/aa374902) +- [ACCESS\_MASK](https://msdn.microsoft.com/library/windows/desktop/aa374892) + +Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h) + +## Related topics +[**IoWMIOpenBlock**](https://msdn.microsoft.com/library/windows/hardware/ff550453) +[**ZwCreateDirectoryObject**](https://msdn.microsoft.com/library/windows/hardware/ff566421) +[**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424) +[**ZwCreateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566425) +[**ZwOpenSection**](https://msdn.microsoft.com/library/windows/hardware/ff567029) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Specifying%20Access%20Rights%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/access-rights.md b/windows-driver-docs-pr/kernel/access-rights.md new file mode 100644 index 0000000000..7070978b7a --- /dev/null +++ b/windows-driver-docs-pr/kernel/access-rights.md @@ -0,0 +1,55 @@ +--- +title: Access Rights +author: windows-driver-content +description: Access Rights +ms.assetid: 518e60db-7058-4ebe-8640-eb8f6b9e7645 +keywords: ["access rights WDK objects", "generic access rights WDK objects", "standard access rights WDK objects", "specific access rights WDK objects", "object access rights WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Access Rights + + +An *access right* is the right to perform a particular operation on the object. For example, the FILE\_READ\_DATA access right specifies the right to read from a file. + +When you open a handle to an object, you specify a set of access rights corresponding to the operations that may be performed on the object. The system checks the specified access rights against the object's security descriptor to see if each operation is permitted for the current user. (For more information, see [Security Descriptors](https://msdn.microsoft.com/library/windows/hardware/ff556612).) + +Access rights come in two types: + +A *specific* access right is a right to perform a single operation. Specific access rights can depend on the type of object. + +A *generic* access right is a right to perform one of a set of similar operations. Generic access rights are independent of the type of object. + +*Standard access rights* are specific access rights that apply to all types of objects. For example, the DELETE access right is the right to delete an object, regardless of type. For more information about the available standard access rights, see [**ACCESS\_MASK**](access-mask.md). + +Objects also have specific access rights that depend on the type of the object. For example, the FILE\_READ\_DATA represents the right to read from a file, while the KEY\_QUERY\_VALUE represents the right to read the value entries for a registry key. + +An object type can have zero, one, or more access rights that correspond to the general notion of reading from or writing to an object. For example, in addition to FILE\_READ\_DATA, file objects have the FILE\_READ\_ATTRIBUTES access right, which represents to read a file's metadata (such as file creation time). Key objects have both KEY\_QUERY\_VALUE and KEY\_ENUMERATE\_SUBKEYS, which represents the right to read the subkeys of a key. + +To simplify specifying all access rights that correspond to a general notion such as reading or writing, the system provides generic access rights. The system maps a generic access right to the appropriate set of specific access rights for the object. + +The system provides the following generic access rights: + +- GENERIC\_READ + +- GENERIC\_WRITE + +- GENERIC\_EXECUTE + +- GENERIC\_ALL + +Thus, the system maps GENERIC\_READ to a set of rights that includes FILE\_READ\_DATA and FILE\_READ\_ATTRIBUTES for a file, and KEY\_QUERY\_VALUE and KEY\_ENUMERATE\_SUBKEYS for a key. For more information about each generic access right, see [**ACCESS\_MASK**](access-mask.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Access%20Rights%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/accessing-device-configuration-space.md b/windows-driver-docs-pr/kernel/accessing-device-configuration-space.md new file mode 100644 index 0000000000..5139f6ed47 --- /dev/null +++ b/windows-driver-docs-pr/kernel/accessing-device-configuration-space.md @@ -0,0 +1,34 @@ +--- +title: Accessing Device Configuration Space +author: windows-driver-content +description: Accessing Device Configuration Space +ms.assetid: 082500ae-9df2-4f8b-8be3-ff2b95067a12 +keywords: ["I/O WDK kernel , device configuration space", "device configuration space WDK I/O", "configuration space WDK I/O", "space WDK I/O", "resource information WDK I/O", "driver stacks WDK configuration info"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Device Configuration Space + + +## + + +Some buses provide a way of accessing a special configuration space for each device attached to the bus. This section explains how a driver can get information from a target device's configuration space, provided the driver is loaded in the same driver stack as the driver for the target device, either as a function driver or a filter driver. + +In Microsoft Windows NT 4.0, drivers get information from a target device's configuration space by scanning the bus and calling the [**HalGetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff546599) and [**HalGetBusDataByOffset**](https://msdn.microsoft.com/library/windows/hardware/ff546606) routines. In Windows 2000 and later operating systems, the hardware buses are controlled by their respective bus drivers and not by HAL. Therefore, all of the HAL routines that used to help drivers retrieve bus-related information are obsolete in Windows 2000. + +The configuration space for a device contains a description of the device and its resource requirements. On Windows 2000 and later operating systems, a driver does not need to query a device to find resources. The driver gets the resources from the Plug and Play (PnP) manager in its [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. Typically, a well-written driver would not require any of this information to function correctly. If, for some reason, the driver requires this information, the code sample in the [Obtaining Device Configuration Information at IRQL = PASSIVE\_LEVEL](obtaining-device-configuration-information-at-irql---passive-level.md) section shows how to get the resources. The driver must be part of the target device's driver stack, because it requires the underlying physical device objects (PDO) of the target device to send the appropriate PnP request. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Accessing%20Device%20Configuration%20Space%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/accessing-read-only-system-memory.md b/windows-driver-docs-pr/kernel/accessing-read-only-system-memory.md new file mode 100644 index 0000000000..de83aed508 --- /dev/null +++ b/windows-driver-docs-pr/kernel/accessing-read-only-system-memory.md @@ -0,0 +1,56 @@ +--- +title: Accessing Read-Only System Memory +author: windows-driver-content +description: Accessing Read-Only System Memory +ms.assetid: d2c1f933-3a7e-4e82-b96d-4f019b27abd5 +keywords: ["memory management WDK kernel , read-only memory", "read-only memory WDK kernel", "intercepting system calls", "global strings WDK memory"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Read-Only System Memory + + +## + + +The Windows [memory manager](windows-kernel-mode-memory-manager.md) enforces read-only access of pages that are not marked as writable. + +Read-only memory has always been protected in user mode. However, in Windows NT 4.0 and earlier versions, read-only memory was not protected in kernel mode. + +If a Windows kernel-mode driver or application tries to write to a read-only memory segment, the system issues a bug check. For more information, see [**Bug Check 0xBE: ATTEMPTED\_WRITE\_TO\_READONLY\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff560161). + +### Intercepting System Calls + +Some drivers intercept system calls by overwriting the driver's own code and inserting jump instructions or other changes. Because the driver's own code is read-only, this technique will cause a bug check to be issued. + +### Global Strings + +If a global string is to be modified, it must not be declared as a pointer to a constant value: + +``` +CHAR *myString = "This string cannot be modified."; +``` + +In this case, the linker might put the string in a read-only memory segment. Then an attempt to modify the string will result in a bug check. + +Instead, the string should be explicitly declared as an array of L-value characters: + +``` +CHAR myString[] = "This string can be modified."; +``` + +This declaration makes sure that the string is put in writable memory. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Accessing%20Read-Only%20System%20Memory%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/accessing-shared-state-information.md b/windows-driver-docs-pr/kernel/accessing-shared-state-information.md new file mode 100644 index 0000000000..9a72341b89 --- /dev/null +++ b/windows-driver-docs-pr/kernel/accessing-shared-state-information.md @@ -0,0 +1,60 @@ +--- +title: Accessing Shared State Information +author: windows-driver-content +description: Accessing Shared State Information +ms.assetid: f3e5ac07-cab1-4f66-90e4-88b2e28079a5 +keywords: ["critical section routines WDK kernel", "timer counters WDK kernel", "shared state information WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing Shared State Information + + +## + + +Use the following general guidelines for designing and writing [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines that maintain state: + +- To access data that an ISR also accesses, a driver routine must call a *SynchCritSection* routine. Non-critical section code can be interrupted. Remember that it is not sufficient to simply acquire a spin lock to protect data that ISRs also access, because ISRs execute at DIRQL and acquiring a spin lock ([**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917)) only raises IRQL to DISPATCH\_LEVEL, which allows an interrupt to invoke the ISR on the current processor. + +- Give each *SynchCritSection* routine that maintains state information responsibility for a discrete set of state variables. That is, avoid writing *SynchCritSection* routines that maintain overlapping state information. + + This prevents contention, and possibly race conditions, between *SynchCritSection* routines (and the ISR) trying to access the same state concurrently. + + This also ensures that each *SynchCritSection* routine returns control as quickly as possible because one *SynchCritSection* routine never has to wait for another that updates some of the same state information to return control. + +- Avoid writing a single, large, general-purpose *SynchCritSection* routine that does more testing of conditions to determine what to do than actually doing useful work. On the other hand, avoid having many *SynchCritSection* routines that never execute a conditional statement because each updates only a single byte of state information. + +- Every *SynchCritSection* routine must return control as quickly as possible, because running any *SynchCritSection* routine prevents the driver's ISR from executing. + +Following is a technique for maintaining a timer counter in a device extension. Assume the driver uses the counter to determine if an I/O operation has timed out. Also assume the driver does not overlap I/O operations. + +- The driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine initializes the timer counter to some initial value for each I/O request. The driver then adds a second to its device time-out value, in case its [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine has just returned control. + +- The driver's ISR must set this timer counter to minus one. + +- The driver's [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine is called once per second to read the time counter and determine whether the ISR has already set it to minus one. If not, the *IoTimer* routine decrements the counter by using [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a SynchCritSection\_1 routine. + + If the counter goes to zero, indicating that the request timed out, the SynchCritSection\_1 routine calls a SynchCritSection\_2 routine to program a device reset operation. If the counter is minus one, the [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine simply returns. + +- If the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine must reprogram the device to begin a partial-transfer operation, it must reinitialize the timer counter as the [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine did. + + The [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine also must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call the SynchCritSection\_2 routine, or possibly a SynchCritSection\_3 routine, to program the device for another transfer operation. + +In this scenario, the driver has more than one *SynchCritSection* routine, each with discrete, specific responsibilities; one to maintain its timer counter, and one or more others to program the device. Each *SynchCritSection* routine can return control quickly because it performs a single, discrete task. + +Note that the driver has a single SynchCritSection\_1 routine which, along with the driver's ISR, maintains the state to the timer counter. Thus, there is no contention for access to the timer counter among several *SynchCritSection* routines and the ISR. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Accessing%20Shared%20State%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/accessing-user-space-memory.md b/windows-driver-docs-pr/kernel/accessing-user-space-memory.md new file mode 100644 index 0000000000..7868f3976f --- /dev/null +++ b/windows-driver-docs-pr/kernel/accessing-user-space-memory.md @@ -0,0 +1,34 @@ +--- +title: Accessing User-Space Memory +author: windows-driver-content +description: Accessing User-Space Memory +ms.assetid: db0b6ba2-4cec-46c1-b13f-aba4c10a2d8c +keywords: ["memory management WDK kernel , user-space memory", "user-space memory WDK kernel", "virtual user-space memory WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Accessing User-Space Memory + + +## + + +A driver cannot directly access memory through user-mode virtual addresses unless it is running in the context of the user-mode thread that caused the driver's current I/O operation and it is using that thread's virtual addresses. + +Only highest-level drivers, such as FSDs, can be sure their dispatch routines will be called in the context of such a user-mode thread. A highest-level driver can call [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) to lock down a user buffer before setting up an IRP for lower drivers. + +Lowest-level and intermediate drivers that set up their device objects for [buffered I/O](methods-for-accessing-data-buffers.md) or [direct I/O](methods-for-accessing-data-buffers.md) can rely on the I/O manager or a highest-level driver to pass valid access to locked-down user buffers or to system-space buffers in IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Accessing%20User-Space%20Memory%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/acpi-bios.md b/windows-driver-docs-pr/kernel/acpi-bios.md new file mode 100644 index 0000000000..88ff723cb3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/acpi-bios.md @@ -0,0 +1,36 @@ +--- +title: ACPI BIOS +author: windows-driver-content +description: ACPI BIOS +ms.assetid: 787e82ed-e58c-461f-abb6-71ed6cba411c +keywords: ["ACPI BIOS WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ACPI BIOS + + +## + + +The integrated power management features supported by Microsoft Windows operating systems are available only on computers that have an Advanced Configuration and Power Interface (ACPI) BIOS. + +Windows Server 2003, Windows XP, and Windows 2000 require that an ACPI BIOS be dated January 1, 1999 or later. However, if one of these Windows versions determines that such a BIOS is known to exhibit ACPI problems, the loader disables ACPI and instead uses Advanced Power Management (APM). Beginning with Windows Vista, the operating system supports only a computer with an ACPI-compliant BIOS that is dated January 1, 1999 or later. + +Device Manager shows whether an individual computer supports ACPI. Check the driver information for the **Computer** device category. + +For more information about ACPI, see the Advanced Configuration and Power Interface Specification at the [ACPI website](http://www.acpi.info). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20ACPI%20BIOS%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/acpi-driver.md b/windows-driver-docs-pr/kernel/acpi-driver.md new file mode 100644 index 0000000000..d2cea6a119 --- /dev/null +++ b/windows-driver-docs-pr/kernel/acpi-driver.md @@ -0,0 +1,68 @@ +--- +title: Acpi.sys The Windows ACPI Driver +author: windows-driver-content +description: The Windows ACPI driver, Acpi.sys, is an inbox component of the Windows operating system. +ms.assetid: 38ca54e0-defe-48b2-ab00-a5f688c2eb01 +keywords: ["ACPI drivers WDK power management", "enumerators WDK power management", "PDOs WDK power management", "filter DOs WDK power management", "physical device objects WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Acpi.sys: The Windows ACPI Driver + + +The Windows ACPI driver, Acpi.sys, is an inbox component of the Windows operating system. The responsibilities of Acpi.sys include support for power management and Plug and Play (PnP) device enumeration. On hardware platforms that have an [ACPI BIOS](acpi-bios.md), the [HAL](windows-kernel-mode-hal-library.md) causes Acpi.sys to be loaded during system startup at the base of the [device tree](device-tree.md). Acpi.sys acts as the interface between the operating system and the ACPI BIOS. Acpi.sys is transparent to the other drivers in the device tree. + +Other tasks performed by Acpi.sys on a particular hardware platform might include reprogramming the resources for a COM port or enabling the USB controller for system wake-up. + +**In this topic** + +- [ACPI devices](#acpi-devices) +- [ACPI control methods](#acpi-control-methods) +- [ACPI specification](#acpi-specification) +- [ACPI debugging](#acpi-debugging) + +## ACPI devices + + +The hardware platform vendor specifies a hierarchy of ACPI namespaces in the ACPI BIOS to describe the hardware topology of the platform. For more information, see [ACPI Namespace Hierarchy](https://msdn.microsoft.com/library/windows/hardware/dn495659). + +For each device described in the ACPI namespace hierarchy, the Windows ACPI driver, Acpi.sys, creates either a filter device object (filter DO) or a physical device object (PDO). If the device is integrated into the system board, Acpi.sys creates a filter device object, representing an ACPI bus filter, and attaches it to the device stack immediately above the bus driver (PDO). For other devices described in the ACPI namespace but not on the system board, Acpi.sys creates the PDO. Acpi.sys provides power management and PnP features to the device stack by means of these device objects. For more information, see [Device Stacks for an ACPI Device](https://msdn.microsoft.com/library/windows/hardware/ff536137). + +A device for which Acpi.sys creates a device object is called an [ACPI device](https://msdn.microsoft.com/library/windows/hardware/ff536161). The set of ACPI devices varies from one hardware platform to the next, and depends on the ACPI BIOS and the configuration of the motherboard. Note that Acpi.sys loads an ACPI bus filter only for a device that is described in the ACPI namespace and is permanently connected to the hardware platform (typically, this device is integrated into the core silicon or soldered to the system board). Not all motherboard devices have an ACPI bus filter. + +All ACPI functionality is transparent to higher-level drivers. These drivers must make no assumptions about the presence or absence of an ACPI filter in any given device stack. + +Acpi.sys and the ACPI BIOS support the basic functions of an ACPI device. To enhance the functionality of an ACPI device, the device vendor can supply a WDM function driver. For more information, see [Operation of an ACPI Device Function Driver](https://msdn.microsoft.com/library/windows/hardware/ff536152). + +An ACPI device is specified by a definition block in the [system description tables](https://msdn.microsoft.com/library/windows/hardware/dn495660) in the ACPI BIOS. A device's definition block specifies, among other things, an operation region, which is a contiguous block of device memory that is used to access device data. Only Acpi.sys modifies the data in an operation region. The device's function driver can read the data in an operation region but must not modify the data. When called, an [operation region handler](https://msdn.microsoft.com/library/windows/hardware/ff536143) transfers bytes in the operation region to and from the data buffer in Acpi.sys. The combined operation of the function driver and Acpi.sys is device-specific and is defined in the ACPI BIOS by the hardware vendor. In general, the function driver and Acpi.sys access particular areas in an operation region to perform device-specific operations and retrieve information. For more information, see [Supporting an Operation Region](https://msdn.microsoft.com/library/windows/hardware/ff536162). + +## ACPI control methods + + +ACPI control methods are software objects that declare and define simple operations to query and configure ACPI devices. Control methods are stored in the ACPI BIOS and are encoded in a byte-code format called ACPI Machine Language (AML). The control methods for a device are loaded from the system firmware into the device's ACPI namespace in memory, and interpreted by the Windows ACPI driver, Acpi.sys. + +To invoke a control method, the kernel-mode driver for an ACPI device initiates an [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request, which is handled by Acpi.sys. For drivers loaded on ACPI-enumerated devices, Acpi.sys always implements the physical device object (PDO) in the driver stack. For more information, see [Evaluating ACPI Control Methods](https://msdn.microsoft.com/library/windows/hardware/ff536139). + +## ACPI specification + + +The *Advanced Configuration and Power Interface Specification* is available at the [ACPI website](http://www.acpi.info). Revision 5.0 of the ACPI specification introduces a set of features to support low-power, mobile PCs that are based on System on a Chip (SoC) integrated circuits and that implement the [connected standby](https://msdn.microsoft.com/library/windows/hardware/mt282515) power model. Starting with Windows 8 and Windows 8.1, the Windows ACPI driver, Acpi.sys, supports the new features in the ACPI 5.0 specification. For more information, see [Windows ACPI design guide for SoC platforms](https://msdn.microsoft.com/library/windows/hardware/dn495676). + +## ACPI debugging + + +System integrators and ACPI device driver developers can use the Microsoft [AMLI debugger](https://msdn.microsoft.com/library/windows/hardware/ff551079) to debug AML code. Because AML is an interpreted language, AML debugging requires special software tools. Checked versions of the Windows ACPI driver, Acpi.sys, contain a debugger component to support AML debugging. For more information about the AMLI debugger, see [ACPI Debugging](https://msdn.microsoft.com/library/windows/hardware/ff537808). For information about how to download a checked build of Windows, see [Downloading a Checked Build of Windows](https://msdn.microsoft.com/library/windows/hardware/ff549603). For information about compiling ACPI Source Language (ASL) into AML, see [Microsoft ASL Compiler](https://msdn.microsoft.com/library/windows/hardware/dn551195). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Acpi.sys:%20The%20Windows%20ACPI%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/acquire-and-release-semantics.md b/windows-driver-docs-pr/kernel/acquire-and-release-semantics.md new file mode 100644 index 0000000000..00403236df --- /dev/null +++ b/windows-driver-docs-pr/kernel/acquire-and-release-semantics.md @@ -0,0 +1,100 @@ +--- +title: Acquire and Release Semantics +author: windows-driver-content +description: Acquire and Release Semantics +ms.assetid: a0852881-c33f-427a-be8a-5b9edac81f9a +keywords: ["synchronization WDK kernel , acquire semantics", "synchronization WDK kernel , release semantics", "acquire semantics WDK kernel", "release semantics WDK kernel", "semantics WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Acquire and Release Semantics + + +## + + +An operation has *acquire semantics* if other processors will always see its effect before any subsequent operation's effect. An operation has *release semantics* if other processors will see every preceding operation's effect before the effect of the operation itself. + +Consider the following code example: + +``` + a++; + b++; + c++; +``` + +From another processor's point of view, the preceding operations can appear to occur in any order. For example, the other processor might see the increment of `b` before the increment of `a`. + +Atomic operations, such as those that the **Interlocked*Xxx*** routines perform, have both acquire and release semantics by default. However, Itanium-based processors execute operations that have only acquire or only release semantics faster than those that have both. Therefore, the system provides **Interlocked*Xxx*Acquire** and **Interlocked*Xxx*Release** versions of some of the **Interlocked*Xxx*** routines. + +For example, the [**InterlockedIncrementAcquire**](https://msdn.microsoft.com/library/windows/hardware/ff547916) routine uses acquire semantics to increment a variable. If you rewrote the preceding code example as follows: + +``` + InterlockedIncrementAcquire(&a); + b++; + c++; +``` + +other processors would always see the increment of `a` before the increments of `b` and `c`. + +Likewise, the [**InterlockedIncrementRelease**](https://msdn.microsoft.com/library/windows/hardware/ff547919) routine uses release semantics to increment a variable. If you rewrote the code example once again, as follows: + +``` + a++; + b++; + InterlockedIncrementRelease(&c); +``` + +other processors would always see the increments of `a` and `b` before the increment of `c`. + +If the processor does not provide instructions that have only acquire or only release semantics, the system will use the corresponding routine that provides both types of semantics. For example, on x86 processors both **InterlockedIncrementAcquire** and **InterlockedIncrementRelease** are equivalent to **InterlockedIncrement**. + +The following table lists the routines that have acquire-only and release-only variants. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
InterlockedXxx RoutineAcquire-Semantics-Only VersionRelease-Semantics-Only Version

[InterlockedIncrement](https://msdn.microsoft.com/library/windows/hardware/ff547910)

[InterlockedIncrementAcquire](https://msdn.microsoft.com/library/windows/hardware/ff547916)

[InterlockedIncrementRelease](https://msdn.microsoft.com/library/windows/hardware/ff547919)

[InterlockedDecrement](https://msdn.microsoft.com/library/windows/hardware/ff547871)

[InterlockedDecrementAcquire](https://msdn.microsoft.com/library/windows/hardware/ff547875)

[InterlockedDecrementRelease](https://msdn.microsoft.com/library/windows/hardware/ff547883)

[InterlockedCompareExchange](https://msdn.microsoft.com/library/windows/hardware/ff547853)

[InterlockedCompareExchangeAcquire](https://msdn.microsoft.com/library/windows/hardware/ff547857)

[InterlockedCompareExchangeRelease](https://msdn.microsoft.com/library/windows/hardware/ff547867)

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Acquire%20and%20Release%20Semantics%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/adapter-objects-and-dma.md b/windows-driver-docs-pr/kernel/adapter-objects-and-dma.md new file mode 100644 index 0000000000..097bd72dff --- /dev/null +++ b/windows-driver-docs-pr/kernel/adapter-objects-and-dma.md @@ -0,0 +1,42 @@ +--- +title: Adapter Objects and DMA +author: windows-driver-content +description: Adapter Objects and DMA +ms.assetid: 8bc672b4-0f4d-4e0c-9904-c8d0a3f3639c +keywords: ["adapter objects WDK kernel", "I/O WDK kernel , adapter objects", "I/O WDK kernel , DMA", "DMA transfers WDK kernel", "AdapterControl routines", "Direct Memory Access WDK kernel", "data transfers WDK kernel , adapter objects", "transferring data WDK kernel , ad"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Adapter Objects and DMA + + +## + + +This section describes adapter objects and [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routines, and how they are used to control DMA operations. The section contains the following topics: + +[Introduction to Adapter Objects](introduction-to-adapter-objects.md) + +[Getting an Adapter Object](getting-an-adapter-object.md) + +[Using System DMA](using-system-dma.md) + +[Using Bus-Master DMA](using-bus-master-dma.md) + +[Using Scatter/Gather DMA](using-scatter-gather-dma.md) + +[Writing AdapterControl Routines](writing-adaptercontrol-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Adapter%20Objects%20and%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/adaptercontrol-routine-requirements.md b/windows-driver-docs-pr/kernel/adaptercontrol-routine-requirements.md new file mode 100644 index 0000000000..a48ad3acc6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/adaptercontrol-routine-requirements.md @@ -0,0 +1,60 @@ +--- +title: AdapterControl Routine Requirements +author: windows-driver-content +description: AdapterControl Routine Requirements +ms.assetid: 09ce4ad8-eb1b-4fd0-9a22-4249d09584b3 +keywords: ["AdapterControl routines, requirements", "AdapterControl routines, writing", "adapter objects WDK kernel , writing AdapterControl routines", "DMA transfers WDK kernel , writing AdapterControl routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# AdapterControl Routine Requirements + + +## + + +At a minimum, an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine must do the following: + +1. Save the input *MapRegisterBase* value along with any other context information that the driver needs to carry out one or more DMA transfer operations for the current IRP. The driver must pass the *MapRegisterBase* value to [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) when each DMA transfer operation is complete. + +2. Return the appropriate [**IO\_ALLOCATION\_ACTION**](https://msdn.microsoft.com/library/windows/hardware/ff550534) value: + + - **KeepObject** if the device is a subordinate device so the driver uses system DMA. + + - **DeallocateObjectKeepRegisters** if the device is a bus master so the driver uses packet-based, bus-master DMA. + +Depending on the driver's design, its *AdapterControl* routine also can do the following before it returns control: + +1. Determine the starting location for the transfer on its device. + +2. Calculate the size of the transfer possible, given any limitations of its device due to the starting location of the transfer. + + In general, it is the responsibility of the routine that calls [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) to determine whether a transfer request must be split up into partial transfers due to any platform-specific limitations on the *NumberOfMapRegisters* available for each DMA transfer operation, as mentioned in the preceding section and detailed in [Splitting Transfer Requests](splitting-dma-transfer-requests.md). + +3. Set up any driver-maintained state about each transfer request in the device (or controller) extension. + + For example, an *AdapterControl* routine might call [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) with the entry point for a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine that times out DMA transfer operations for the driver. + +4. Call [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) with the MDL pointer passed at **Irp->MdlAddress** to get an index for the start of the transfer, suitable for passing to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402). + +5. Call **MapTransfer** to set up the system DMA controller or to obtain a physical-to-logical address mapping for a bus-master device. + +6. Program the driver's device for a transfer operation, by using a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that is invoked by calling [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302). For more information, see [Using Critical Sections](using-critical-sections.md). + +If a transfer request requires the driver to perform a sequence of partial-transfer operations to satisfy the current IRP, the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine is typically responsible for reprogramming the device for subsequent transfer operations. An *AdapterControl* routine is called only once for each incoming transfer IRP. + +The driver routine that completes the current transfer IRP, usually the *DpcForIsr* or *CustomDpc* routine, also is responsible for releasing the system DMA controller or bus-master adapter by calling [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) or [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513), respectively. This driver routine should make the appropriate call as soon as possible when its last partial-transfer operation is done so that drivers of subordinate DMA devices can allocate the system DMA controller or a bus-master driver can begin processing the next transfer IRP promptly. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20AdapterControl%20Routine%20Requirements%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/adddevice-routines-in-bus-drivers.md b/windows-driver-docs-pr/kernel/adddevice-routines-in-bus-drivers.md new file mode 100644 index 0000000000..6e5224e117 --- /dev/null +++ b/windows-driver-docs-pr/kernel/adddevice-routines-in-bus-drivers.md @@ -0,0 +1,30 @@ +--- +title: AddDevice Routines in Bus Drivers +author: windows-driver-content +description: AddDevice Routines in Bus Drivers +ms.assetid: 70af7116-2f29-4d77-a6d5-c1e0417e6f81 +keywords: ["bus drivers WDK kernel", "AddDevice routines WDK kernel , bus drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# AddDevice Routines in Bus Drivers + + +## + + +A PnP bus driver has an *AddDevice* routine, but it is called when the bus driver is acting as the function driver for its controller or adapter. For example, the PnP manager calls the USB Hub bus driver's *AddDevice* routine to add the hub device. The hub driver's *AddDevice* routine is not called for a child of the hub (a device that plugs into the hub). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20AddDevice%20Routines%20in%20Bus%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/adddevice-routines-in-function-or-filter-drivers.md b/windows-driver-docs-pr/kernel/adddevice-routines-in-function-or-filter-drivers.md new file mode 100644 index 0000000000..6544822447 --- /dev/null +++ b/windows-driver-docs-pr/kernel/adddevice-routines-in-function-or-filter-drivers.md @@ -0,0 +1,74 @@ +--- +title: AddDevice Routines in Function or Filter Drivers +author: windows-driver-content +description: AddDevice Routines in Function or Filter Drivers +ms.assetid: 0a095c17-2295-46df-9908-f306f7fe9f67 +keywords: ["function drivers WDK kernel", "filter drivers WDK kernel", "AddDevice routines WDK kernel , function drivers", "AddDevice routines WDK kernel , filter drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# AddDevice Routines in Function or Filter Drivers + + +## + + +An [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine in a function or filter driver should take the following steps: + +1. Call [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) to create a functional or filter device object (an FDO or filter DO) for the device being added. + + Do not specify a *DeviceName* for the device object, because doing so bypasses the PnP manager's security. If a user-mode component needs a symbolic link to the device, register a device interface (see the next step below). If a kernel-mode component needs a legacy device name, the driver must name the device object, but naming is not recommended. + + Include FILE\_DEVICE\_SECURE\_OPEN in the *DeviceCharacteristics* parameter. This characteristic directs the I/O manager to perform security checks against the device object for all open requests, including relative opens and trailing file name opens. + +2. \[optional\] Create one or more symbolic links to the device. + + Call [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) to register device functionality and create a symbolic link that applications or system components can use to open the device. The driver should enable the interface by calling [**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700) when it handles the [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. For more information, see [Device Interface Classes](https://msdn.microsoft.com/library/windows/hardware/ff541339). + +3. Store the pointer to the device's PDO in the device extension. + + The PnP manager supplies a pointer to the PDO as the *PhysicalDeviceObject* parameter to *AddDevice*. Drivers use the PDO pointer in calls to routines such as [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203). + +4. Define flags in the device extension to track certain PnP states of the device, such as device paused, removed, and surprise-removed. + + For example, define one flag to indicate that incoming IRPs should be held while the device is in a paused state. Create a queue for holding IRPs, if the driver does not already have a mechanism for queuing IRPs. See [Queuing and Dequeuing IRPs](queuing-and-dequeuing-irps.md) for more information. + + Also allocate an **IO\_REMOVE\_LOCK** structure in the device extension and call [**IoInitializeRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549324) to initialize this structure. For more information, see [Using Remove Locks](using-remove-locks.md). + +5. Set the DO\_BUFFERED\_IO or DO\_DIRECT\_IO flag bit in the device object to specify the type of buffering that the I/O manager is to use for I/O requests that are sent to the device stack. Higher-level drivers OR this member with the same value as the next-lower driver in the stack, except possibly for highest-level drivers. For more information, see [Initializing a Device Object](initializing-a-device-object.md). + +6. Set the DO\_POWER\_INRUSH or DO\_POWER\_PAGABLE flag for power management, if necessary. Drivers that are pageable must set the DO\_POWER\_PAGABLE flag. The device object flags are typically set by the bus driver when it creates the PDO for the device. However, higher-level drivers may occasionally need to alter the values of these flags in their *AddDevice* routines when they create the FDO or filter DO. See [Setting Device Object Flags for Power Management](setting-device-object-flags-for-power-management.md) for details. + +7. Create and/or initialize any other software resources the driver uses to manage this device, such as events, spin locks, or other objects. (Hardware resources, such as I/O ports, are configured later, in response to an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request.) + + Because an *AddDevice* routine runs in a system thread context at IRQL = PASSIVE\_LEVEL, any memory allocated with [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) for use exclusively during initialization can be from paged pool, as long as the driver does not control the device that holds the system page file. Such a memory allocation must be released with [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) before *AddDevice* returns control. + +8. Attach the device object to the device stack ([**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300)). + + Specify a pointer to the device's PDO in the *TargetDevice* parameter. + + Store the pointer returned by **IoAttachDeviceToDeviceStack**. This pointer, which points to the device object of the next-lower driver for the device, is a required parameter to [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) and [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) when passing IRPs down the device stack. + +9. Clear the DO\_DEVICE\_INITIALIZING flag in the FDO or filter DO with a statement like the following: + + ``` + FunctionalDeviceObject->Flags &= ~DO_DEVICE_INITIALIZING; + ``` + +10. Be prepared to handle PnP IRPs for the device (such as [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff551715) and **IRP\_MN\_START\_DEVICE**). + +A driver must not start controlling the device until it receives an **IRP\_MN\_START\_DEVICE** containing the list of hardware resources assigned to the device by the PnP manager. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20AddDevice%20Routines%20in%20Function%20or%20Filter%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/adding-a-pnp-device-to-a-running-system.md b/windows-driver-docs-pr/kernel/adding-a-pnp-device-to-a-running-system.md new file mode 100644 index 0000000000..c8bb0ca45e --- /dev/null +++ b/windows-driver-docs-pr/kernel/adding-a-pnp-device-to-a-running-system.md @@ -0,0 +1,224 @@ +--- +title: Adding a PnP Device to a Running System +author: windows-driver-content +description: Adding a PnP Device to a Running System +ms.assetid: 73d14ba1-6cf1-44eb-8a98-8c2fe44c11bb +keywords: ["PnP WDK kernel , adding device to running system", "Plug and Play WDK kernel , adding device to running system", "adding PnP device to running system", "enumerating PnP devices WDK PnP", "reporting PnP devices", "devnodes WDK PnP", "device nodes WDK PnP", "function drivers WDK PnP", "filter drivers WDK PnP", "AddDevice routine WDK PnP", "IRPs WDK PnP", "I/O request packets WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Adding a PnP Device to a Running System + + +## + + +This section describes the sequence of events that occur when the system configures a PnP device that a user has added to a running machine. This discussion highlights the roles of the PnP manager, bus drivers, and function and filter drivers in enumerating and configuring a new device. + +Most of this discussion is also relevant to configuring a PnP device that is present when the machine is booted. Specifically, devices whose drivers are marked SERVICE\_DEMAND\_START in an INF file are configured in essentially the same way whether the device is added dynamically or is present at boot time. + +The following figure shows the first steps in configuring the device, starting from when the user plugs the hardware into the machine. + +![diagram illustrating enumerating and reporting a plug and play device](images/hotplug.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. A user plugs a PnP device into a free slot on a PnP bus. + + In this example, the user plugs a PnP USB joystick into the hub on a USB host controller. The USB hub is a PnP bus device because child devices can be attached to it. + +2. The function driver for the bus device determines that a new device is on its bus. + + How the driver determines this depends on the bus architecture. For some buses, the bus function driver receives hot-plug notification of new devices. If the bus does not support hot-plug notification, the user must take appropriate action in Control Panel to cause the bus to be enumerated. + + In this example, the USB bus supports hot-plug notification so the function driver for the USB bus is notified that its children have changed. + +3. The function driver for the bus device notifies the PnP manager that its set of child devices has changed. + + The function driver notifies the PnP manager by calling [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) with a *Type* of **BusRelations**. + +4. The PnP manager queries the bus's drivers for the current list of devices on the bus. + + The PnP manager sends an [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) request to the device stack for the bus. The **Parameters.QueryDeviceRelations.Type** value is **BusRelations**, indicating that the PnP manager is asking for the current list of devices present on the bus (*bus relations*). + + The PnP manager sends the IRP to the top driver in the device stack for the bus. According to the rules for PnP IRPs, each driver in the stack handles the IRP, if appropriate, and passes the IRP down to the next driver. + +5. The function driver for the bus device handles the IRP. + + See the reference page for [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) for detailed information about handling this IRP. + + In this example, the USB hub driver handles this IRP for the hub [*FDO*](https://msdn.microsoft.com/library/windows/hardware/ff556280#wdkgloss-fdo). The hub driver creates a [*PDO*](https://msdn.microsoft.com/library/windows/hardware/ff556325#wdkgloss-pdo) for the joystick device and includes a referenced pointer to the joystick PDO in its list of child devices returned with the IRP. + + When the USB hub's parent bus driver (the USB host controller class/miniclass driver pair) completes the IRP, the IRP travels back up the device stack by means of any [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines registered by the hub drivers. + +Note that the bus function driver reports a change in its list of children by requesting that the PnP manager query for its list of child devices. The resulting **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** request is seen by all the drivers for the bus device. Typically, the bus function driver is the only driver to handle the IRP and report children. In some device stacks, a bus filter driver is present and participates in constructing the list of bus relations. One example is ACPI, which attaches as a bus filter driver for ACPI devices. In some device stacks, nonbus filter drivers handle the **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** request, but this is not typical. + +At this point, the PnP manager has the current list of devices on the bus. The PnP manager then determines whether any devices are newly arrived or have been removed. In this example, there is one new device. The following figure shows the PnP manager creating a devnode for the new device and beginning to configure the device. + +![diagram illustrating creating a devnode for a new plug and play device](images/credvnd.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. The PnP manager creates devnodes for any new child devices on the bus. + + The PnP manager compares the list of bus relations returned in the **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** IRP to the list of children for the bus currently recorded in the PnP device tree. The PnP manager creates a devnode for each new device and initiates removal processing for any devices that have been removed. + + In this example, there is one new device (a joystick), so the PnP manager creates a devnode for the joystick. At this point, the only driver that is configured for the joystick is the parent USB hub bus driver, which created the joystick's PDO. Any optional bus filter drivers would also be present in the device stack, but the example omits bus filter drivers for simplicity. + + The wide arrow between the two devnodes in the previous figure indicates that the joystick devnode is a child of the USB hub devnode. + +2. The PnP manager gathers information about the new device and begins configuring the device. + + The PnP manager sends a sequence of IRPs to the device stack to gather information about the device. At this point, the device stack consists of only the PDO created by the device's parent bus driver and filter DOs for any optional bus filter drivers. Therefore, the bus driver and bus filter drivers are the only drivers that respond to these IRPs. In this example, the only driver in the joystick device stack is the parent bus driver, the USB hub driver. + + The PnP manager gathers information about a new device by sending IRPs to the device stack. These IRPs include the following: + + - [**IRP\_MN\_QUERY\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff551679), a separate IRP for each of the following types of hardware IDs: + + **BusQueryDeviceID** + + **BusQueryInstanceID** + + **BusQueryHardwareIDs** + + **BusQueryCompatibleIDs** + + **BusQueryContainerID** + + - [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) + + - [**IRP\_MN\_QUERY\_DEVICE\_TEXT**](https://msdn.microsoft.com/library/windows/hardware/ff551674), a separate IRP for each of the following items: + + **DeviceTextDescription** + + **DeviceTextLocationInformation** + + - [**IRP\_MN\_QUERY\_BUS\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff551654) + - [**IRP\_MN\_QUERY\_RESOURCES**](https://msdn.microsoft.com/library/windows/hardware/ff551710) + - [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff551715) + + The PnP manager sends the IRPs listed above at this stage of processing a new PnP device, but not necessarily in the order listed, so you should not make assumptions about the order in which the IRPs are sent. Also, you should not assume that the PnP manager sends only the IRPs listed above. + + The PnP manager checks the registry to determine whether the device has been installed on this machine previously. The PnP manager checks for an <*enumerator*>\\<*deviceID*> subkey for the device under the **Enum** branch. In this example, the device is new and must be configured "from scratch." + +3. The PnP manager stores information about the device in the registry. + + The registry's **Enum** branch is reserved for use by operating system components and its layout is subject to change. Driver writers must use system routines to extract information related to drivers. Do not access the **Enum** branch directly from a driver. The following **Enum** information is listed for debugging purposes only. + + - The PnP manager creates a subkey for the device under the key for the device's enumerator. + + The PnP manager creates a subkey named **HKLM\\System\\CurrentControlSet\\Enum\\**<*enumerator*>**\\**<*deviceID*>. It creates the <*enumerator*> subkey if it does not already exist. + + An *enumerator* is a component that discovers PnP devices based on a PnP hardware standard. The tasks of an enumerator are carried out by a PnP bus driver in partnership with the PnP manager. A device is typically enumerated by its parent bus driver, such as PCI or PCMCIA. Some devices are enumerated by a bus filter driver, such as ACPI. + + - The PnP manager creates a subkey for this instance of the device. + + If **Capabilities.UniqueID** is returned as **TRUE** for **IRP\_MN\_QUERY\_CAPABILITIES**, the device's unique ID is unique across the system. If not, the PnP manager modifies the ID so that it is unique system-wide. + + The PnP manager creates a subkey named **HKLM\\System\\CurrentControlSet\\Enum\\**<*enumerator*>**\\**<*deviceID*>**\\**<*instanceID*>. + + - The PnP manager writes information about the device to the subkey for the device instance. + + The PnP manager stores information, including the following, if it was supplied for the device: + + **DeviceDesc** — from [**IRP\_MN\_QUERY\_DEVICE\_TEXT**](https://msdn.microsoft.com/library/windows/hardware/ff551674) + + **Location** — from **IRP\_MN\_QUERY\_DEVICE\_TEXT** + + **Capabilities** — the flags from [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) + + **UINumber** — from **IRP\_MN\_QUERY\_CAPABILITIES** + + **HardwareID** — from [**IRP\_MN\_QUERY\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff551679) + + **CompatibleIDs** — from **IRP\_MN\_QUERY\_ID** + + **ContainerID** — from **IRP\_MN\_QUERY\_ID** + + **LogConf\\BootConfig** — from [**IRP\_MN\_QUERY\_RESOURCES**](https://msdn.microsoft.com/library/windows/hardware/ff551710) + + **LogConf\\BasicConfigVector** — from [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff551715) + +At this point, the PnP manager is ready to locate the function driver and filter drivers for the device, if any. (See the following figure.) + +![diagram illustrating finding function and filter drivers](images/finddrv.png) + +The following notes correspond to the numbered circles in the previous figure: + +1. The kernel-mode PnP manager coordinates with the user-mode PnP manager and user-mode Setup components to find the function and filter drivers for the device, if there are any. + + The kernel-mode PnP manager queues an event to the user-mode PnP manager, identifying a device that needs to be installed. Once a privileged user logs in, the user-mode components proceed with finding drivers. See the [device installation overview](https://msdn.microsoft.com/library/windows/hardware/ff549455) For information about Setup components and their role in installing a device. + +2. The user-mode Setup components direct the kernel-mode PnP manager to load the function and filter drivers. + + The user-mode components call back to kernel mode to get the drivers loaded, causing their [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routines to be called. + +The following figure shows the PnP manager loading the drivers (if appropriate), calling their *AddDevice* routines, and directing the drivers to start the device. + +![diagram illustrating calling adddevice routines and starting the new device](images/addstart.png) + +The following notes correspond to the numbered circles in the previous figure: + +1. Lower-filter drivers + + Before the function driver attaches to the device stack, the PnP manager processes any lower-filter drivers. For each lower-filter driver, the PnP manager calls the driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine if the driver is not yet loaded. Then the PnP manager calls the driver's *AddDevice* routine. In its *AddDevice* routine, the filter driver creates a filter device object (filter DO) and attaches it to the device stack ([**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300)). Once it attaches its device object to the device stack, the driver is engaged as a driver for the device. + + In the USB joystick example, there is one lower-filter driver for the device. + +2. Function driver + + After any lower filters are attached, the PnP manager processes the function driver. The PnP manager calls the function driver's **DriverEntry** routine if the driver is not yet loaded and calls the function driver's *AddDevice* routine. The function driver creates a function device object (FDO) and attaches it to the device stack. + + In this example, the function driver for the USB joystick is actually a pair of drivers: the HID class driver and the HID miniclass driver. The two drivers work together to serve as the function driver. The driver pair creates only one FDO and attaches it to the device stack. + +3. Upper-filter drivers + + After the function driver is attached, the PnP manager processes any upper-filter drivers. + + In this example, there is one upper-filter driver for the device. + +4. Assigning resources and starting the device + + The PnP manager assigns resources to the device, if needed, and issues an IRP to start the device. + + - Assigning resources + + Earlier in the configuration process, the PnP manager gathered the hardware resource requirements for the device from the device's parent bus driver. After the full set of drivers is loaded for the device, the PnP manager sends an [**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550874) request to the device stack. All drivers in the stack have the opportunity to handle this IRP and modify the device's resource requirements list, if necessary. + + The PnP manager assigns resources to the device, if the device requires any, based on the device's requirements and the resources currently available. + + The PnP manager might need to rearrange the resource assignments of existing devices to satisfy the needs of the new device. This reassignment of resources is called "rebalancing." The drivers for the existing devices receive a sequence of stop and start IRPs during a rebalance, but the rebalance must be transparent to users. + + In the example of the USB joystick, USB devices do not require hardware resources so the PnP manager sets the resource list to **NULL**. + + - Starting the device (**IRP\_MN\_START\_DEVICE**) + + Once the PnP manager assigns resources to the device, it sends an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) IRP to the device stack to direct the drivers to start the device. + + After the device is started, the PnP manager sends three more IRPs to the drivers for the device: + + - [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) + + After the start IRP completes successfully, the PnP manager sends another **IRP\_MN\_QUERY\_CAPABILITIES** IRP to the device stack. All the drivers for the device have the option of handling the IRP. The PnP manager sends this IRP at this time, after all drivers are attached and the device is started, because the function or filter drivers might need to access the device to collect capability information. + + - [**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff551698) + + This IRP gives a driver the opportunity to, for example, report that the device should not be displayed in user interfaces such as Device Manager and the Hotplug program. This is useful for devices that are present on a system but are not usable in the current configuration, such as a game port on a laptop that is not usable when the laptop is undocked. + + - [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) for bus relations + + The PnP manager sends this IRP to determine whether the device has any child devices. If so, the PnP manager configures each child device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Adding%20a%20PnP%20Device%20to%20a%20Running%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/additional-errors-in-handling-irps.md b/windows-driver-docs-pr/kernel/additional-errors-in-handling-irps.md new file mode 100644 index 0000000000..697ea4cae8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/additional-errors-in-handling-irps.md @@ -0,0 +1,38 @@ +--- +title: Additional Errors in Handling IRPs +author: windows-driver-content +description: Additional Errors in Handling IRPs +ms.assetid: fb46e7a8-8181-46d3-a929-cec01fd71f20 +keywords: ["reliability WDK kernel , double-completed IRPs", "double-completed IRPs WDK kernel", "lost IRPs WDK kernel", "reliability WDK kernel , lost IRPs", "converging public IOCTL and private IOCTL paths", "reliability WDK kernel , converge public and private IOCTL paths"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Additional Errors in Handling IRPs + + +## + + +The following are additional errors that drivers sometimes make when handling IRPs. + +### Lost or double-completed IRPs + +These problems, along with missing calls to I/O manager routines such as [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358), often occur in error-handling paths. Quick reviews of driver paths can find such problems. + +### Converging public IOCTL and private IOCTL paths + +As a general rule, drivers should contain separate execution paths for public and private IOCTLs (or FSCTLs). A driver cannot determine whether an IOCTL or FSCTL request originates in kernel mode or user mode by looking at the control code. Consequently, handling both public and private codes in the same execution path (or performing minimal validation and then calling the same routines) can open a driver to security breaches. If a private IOCTL or FSCTL is privileged, then unprivileged users who know the control codes might be able to gain access to it. Therefore, if your driver supports private IOCTL or FSCTL requests, make sure it handles such requests separately from any public IOCTLs or FSCTLs it must also support. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Additional%20Errors%20in%20Handling%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/additional-timers-and-counters.md b/windows-driver-docs-pr/kernel/additional-timers-and-counters.md new file mode 100644 index 0000000000..a26753b5b9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/additional-timers-and-counters.md @@ -0,0 +1,28 @@ +--- +title: Additional Timers and Counters +author: windows-driver-content +description: Additional Timers and Counters +ms.assetid: d61adb40-adcd-4a8d-88f5-f217576d1147 +--- + +# Additional Timers and Counters + + +## + + +This section contains information about additional timers and counters provided by the system for driver use. It includes the following topics: + +[IoTimer Routines](iotimer-routines.md) + +[Counters](counters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Additional%20Timers%20and%20Counters%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/additional-transactional-interfaces.md b/windows-driver-docs-pr/kernel/additional-transactional-interfaces.md new file mode 100644 index 0000000000..851ff1f708 --- /dev/null +++ b/windows-driver-docs-pr/kernel/additional-transactional-interfaces.md @@ -0,0 +1,35 @@ +--- +title: Additional Transactional Interfaces +author: windows-driver-content +description: Additional Transactional Interfaces +ms.assetid: cbd88c96-6445-436b-8e02-09dd9cf40d77 +keywords: ["transactions WDK KTM , non-KTM interfaces", "transactional interfaces WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Additional Transactional Interfaces + + +In addition to the transactional interfaces that you can use by accessing KTM, Microsoft provides several additional transactional interfaces, including the following: + +- For file system minifilter drivers, the [filter manager](https://msdn.microsoft.com/library/windows/hardware/ff541591) provides routines that enable minifilter drivers to enlist in transactions, receive notification about transaction state changes, and attach contexts to transactions. For more information about these capabilities, see [**FltEnlistInTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff542053). + +- Beginning with Windows Vista, the NTFS file system and the registry are implemented as resource managers that support transactional operations. For more information about transactional NTFS and transactional registry capabilities, see the Microsoft Windows SDK. + +- The Distributed Transaction Coordinator (DTC) provides interoperability with KTM through the **IKernelTransaction** interface. For more information about the **IKernelTransaction** interface, see the Microsoft Windows SDK. + +- The .NET Framework supports the **System.Transactions** namespace. For more information about this namespace, see the [MSDN website](http://go.microsoft.com/fwlink/p/?linkid=8714). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Additional%20Transactional%20Interfaces%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-common-buffer-system-dma.md b/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-common-buffer-system-dma.md new file mode 100644 index 0000000000..f493fbaec5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-common-buffer-system-dma.md @@ -0,0 +1,54 @@ +--- +title: Allocating an Adapter Channel for Common-Buffer System DMA +author: windows-driver-content +description: Allocating an Adapter Channel for Common-Buffer System DMA +ms.assetid: 3b426b5e-e555-458c-8e16-0d59a7cb9bd6 +keywords: ["allocating adapter channels", "adapter channel allocations WDK kernel", "AllocateAdapterChannel", "system DMA WDK kernel , common buffer", "common buffer DMA WDK kernel", "DMA transfers WDK kernel , common buffer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Allocating an Adapter Channel for Common-Buffer System DMA + + +## + + +A driver calls [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) after its [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) or [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) routine (or any other dispatch routine that handles a DMA transfer) has checked the validity of the IRP's parameters, possibly queued one or more IRPs to another driver routine for further processing, and possibly loaded its common buffer with data to be transferred, if appropriate. + +The driver routine that calls **AllocateAdapterChannel** must be executing at IRQL = DISPATCH\_LEVEL. The **AllocateAdapterChannel** routine queues the driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, which runs after the system DMA controller has been assigned to this driver and a set of [map registers](map-registers.md) has been allocated for the driver's DMA operation. + +On entry, the *AdapterControl* routine is given pointers to the device object and context passed in the call to **AllocateAdapterChannel**, as well as a handle for the allocated map registers. The *AdapterControl* routine also is given a pointer to the **DeviceObject->CurrentIrp** if the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. If the driver manages its own queuing of IRPs instead of having a *StartIo* routine, the driver should include a pointer to the current IRP as part of the context data it passes when it calls **AllocateAdapterChannel**. + +The *AdapterControl* routine typically does the following: + +1. Saves or initializes whatever context the driver maintains about DMA operations. The context might include the input *MapRegisterBase* handle the driver must pass to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) and [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) and, possibly, the **Length** of the requested transfer from its I/O stack location in the IRP. + +2. Sets up the subordinate device to start the transfer operation. + +3. Returns the value **KeepObject**. + +For additional information, see [Writing AdapterControl Routines](writing-adaptercontrol-routines.md). + +For drivers that use a system DMA controller's auto-initialize mode, the *AdapterControl* routine must return the value **KeepObject**. This allows the driver to retain "ownership" of the system DMA controller and allocated map register(s) until it has transferred all the data. + +Because an *AdapterControl* routine cannot wait for the subordinate device to carry out the DMA operation, the *AdapterControl* routine must at least do the following: + +1. Save context information, particularly the *MapRegisterBase* handle, in the driver's device extension, controller extension, or other driver-accessible resident storage area (nonpaged pool allocated by the driver). + +2. Return **KeepObject**. + +Another driver routine (probably the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine) must call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) and [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) when the DMA transfer operation is complete. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Allocating%20an%20Adapter%20Channel%20for%20Common-Buffer%20System%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-packet-based-dma.md b/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-packet-based-dma.md new file mode 100644 index 0000000000..c5f23eff1d --- /dev/null +++ b/windows-driver-docs-pr/kernel/allocating-an-adapter-channel-for-packet-based-dma.md @@ -0,0 +1,72 @@ +--- +title: Allocating an Adapter Channel for Packet-Based DMA +author: windows-driver-content +description: Allocating an Adapter Channel for Packet-Based DMA +ms.assetid: c95e4b2d-ce19-453a-bcc5-4bb37fc5d9ed +keywords: ["system DMA WDK kernel , packet-based", "packet-based DMA WDK kernel", "DMA transfers WDK kernel , packet-based", "allocating adapter channels", "adapter channel allocations WDK kernel", "AllocateAdapterChannel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Allocating an Adapter Channel for Packet-Based DMA + + +## + + +To prepare for packet-based system DMA, a driver calls [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) and [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) after receiving an [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) request. + +Before the driver calls these routines, its [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) or [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) routine (or any other dispatch routine that handles a DMA transfer) should already have checked the validity of the IRP's parameters. The dispatch routine might also have queued the IRP to another driver routine for further processing. + +The driver routine that calls **AllocateAdapterChannel** must be executing at IRQL = DISPATCH\_LEVEL. Along with a pointer to the adapter object returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220), a driver must supply the following when it calls **AllocateAdapterChannel**: + +- A pointer to the target device object + +- The entry point for its [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine + +- A pointer to any driver-determined context information the *AdapterControl* routine will use + +**AllocateAdapterChannel** queues the driver's *AdapterControl* routine, which runs when the system DMA controller is assigned to this driver and a set of [map registers](map-registers.md) has been allocated for the driver's DMA operation(s). + +On entry, the *AdapterControl* routine receives the *DeviceObject* and *Context* pointers passed in the call to **AllocateAdapterChannel**, as well as a handle (*MapRegisterBase*) for the allocated map registers. + +The *AdapterControl* routine also receives a pointer to the **DeviceObject->CurrentIrp** if the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. If the driver manages its own queuing of IRPs (instead of having a *StartIo* routine), the driver should include a pointer to the current IRP as part of the context it passes when it calls **AllocateAdapterChannel**. + +The *AdapterControl* routine typically does the following: + +1. Saves or initializes whatever context the driver maintains about DMA operations. The context might include the input *MapRegisterBase* handle the driver must pass to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) and [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) and, possibly, the **Length** of the requested transfer from its I/O stack location in the IRP. + +2. Calls [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) followed by **MapTransfer**. See [Setting Up the System DMA Controller for Packet-Based DMA](setting-up-the-system-dma-controller-for-packet-based-dma.md). + +3. Sets up the subordinate device to start the transfer operation. + +4. Returns the value **KeepObject**. + +Every *AdapterControl* routine must return a system-defined value of type [**IO\_ALLOCATION\_ACTION**](https://msdn.microsoft.com/library/windows/hardware/ff550534). For drivers that use system DMA, the *AdapterControl* routine must return the value **KeepObject**. This allows the driver to retain "ownership" of the system DMA controller and allocated map registers until it has transferred all the requested data. + +Because an *AdapterControl* routine cannot wait for the subordinate device to carry out the DMA operation, each *AdapterControl* routine must, at a minimum, do the following: + +1. Save context information, particularly the *MapRegisterBase* handle, in the driver's device extension, controller extension, or other driver-accessible resident storage area (nonpaged pool allocated by the driver). + +2. Return **KeepObject**. + +For additional information, see [Writing AdapterControl Routines](writing-adaptercontrol-routines.md). + +Another driver routine (probably the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine) must call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) when each DMA transfer operation is complete. This routine also must call **MapTransfer** and **FlushAdapterBuffers** again if it is necessary to set up the DMA controller more than once to satisfy the current IRP's transfer request. + +When a driver has satisfied the current IRP's request, it must call [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507). This support routine should be called immediately following the last call to **FlushAdapterBuffers** for the current IRP so that the system DMA controller can be made available for use (by any driver) to satisfy other transfer requests expeditiously. + +The driver of a subordinate device with scatter/gather capabilities should also return **KeepObject** from its *AdapterControl* routine. The device must be capable of waiting while the system DMA controller is reprogrammed between DMA operations when the driver must split up a given DMA request. On some Windows platforms, such devices can transfer at most a page of data per DMA operation because the HAL can assign only a single map register to the driver of that device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Allocating%20an%20Adapter%20Channel%20for%20Packet-Based%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/allocating-controller-objects-for-i-o-operations.md b/windows-driver-docs-pr/kernel/allocating-controller-objects-for-i-o-operations.md new file mode 100644 index 0000000000..4d0a220181 --- /dev/null +++ b/windows-driver-docs-pr/kernel/allocating-controller-objects-for-i-o-operations.md @@ -0,0 +1,64 @@ +--- +title: Allocating Controller Objects for I/O Operations +author: windows-driver-content +description: Allocating Controller Objects for I/O Operations +ms.assetid: 8a5e3741-f8ea-4e27-bb7f-6c20da1d618d +keywords: ["controller objects WDK kernel , allocating", "ControllerControl routines, controller object allocation", "IoAllocateController", "allocating controller objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Allocating Controller Objects for I/O Operations + + +## + + +After a driver that uses a controller object has started its device, it is ready to process IRPs sent to its target device objects. Whenever an IRP requires the driver to program the physical device represented by the controller object for an I/O operation, the driver calls [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224). The following figure illustrates such a call. + +![diagram illustrating allocating a controller object for i/o](images/3ctlaloc.png) + +As the previous figure shows, a driver must supply more than the *ControllerObject* pointer that was returned by [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395) when it calls [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224). Along with this pointer, it must pass pointers to the device object representing the target of the current I/O request, to a driver-supplied [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine, and to whatever *Context* its *ControllerControl* routine will need to set up the device for the requested I/O operation. + +**IoAllocateController** queues the driver-supplied *ControllerControl* routine if the device represented by the controller object is busy. Otherwise, the *ControllerControl* routine is called immediately with the input parameters shown in the previous figure. The input *Context* pointer to **IoAllocateController** is passed to the driver's *ControllerControl* routine when it is run. + +Use the following guidelines to determine where to store context information: + +- The driver-supplied context area should not be in the controller extension unless the driver processes each IRP to completion before starting another operation on the physical controller. Otherwise, a context area in the controller extension could be overwritten by other driver routines or on receipt of a new IRP. + +- Even if the driver overlaps a device I/O operation for another device object, a context area in the device extension of the target device object cannot be overwritten. + +- If another I/O request is made for a particular device object and the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, a context area in its device extension also cannot be overwritten because the incoming IRP will be queued when the driver calls [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) and the same IRP will remain in the device queue until the driver calls [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) just before it completes the current IRP for that device object. + +The I/O manager passes a pointer to the *DeviceObject*->**CurrentIrp** to a *ControllerControl* routine if the driver has a *StartIo* routine. If a driver manages its own queuing of IRPs instead of having a *StartIo* routine, the I/O manager cannot give the *ControllerControl* routine a pointer to the current IRP. When the driver calls **IoAllocateController**, it should pass the current IRP as part of the *Context*-accessible data. + +The driver routine that calls **IoAllocateController** must be executing at IRQL = DISPATCH\_LEVEL when the call occurs. A driver that makes this call from its *StartIo* routine is already running at DISPATCH\_LEVEL. + +The *ControllerControl* routine sets up the physical controller for the IRP's requested operation. + +As shown in the previous figure, the *ControllerControl* routine returns a value of type [**IO\_ALLOCATION\_ACTION**](https://msdn.microsoft.com/library/windows/hardware/ff550534), which can be either of the following system-defined values: + +- If the *ControllerControl* routine can start another operation on the physical controller, it should return **DeallocateObject** so the driver can overlap the next requested I/O operation. + + For example, if the *ControllerControl* routine can program a disk controller for a seek operation on one disk, complete that IRP, and return **DeallocateObject**, the *ControllerControl* routine can be called again to program the disk controller for a transfer operation on the other disk if any transfer requests currently are queued to the other disk. + +- If the current IRP requires further processing by other driver routines, the *ControllerControl* routine must return **KeepObject**. + + For example, if the driver programs a disk controller for a transfer operation but cannot complete the IRP until the transfer is complete, the *ControllerControl* routine must return **KeepObject**. + +When a *ControllerControl* routine returns **KeepObject**, usually the driver's ISR runs when the device interrupts, and its [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine completes the I/O operation and the current IRP for the target device object. + +Whenever the *ControllerControl* routine returns **KeepObject**, the routine that completes the IRP must call [**IoFreeController**](https://msdn.microsoft.com/library/windows/hardware/ff549104). Such a driver routine should call **IoFreeController** as soon as possible so that its next device I/O operation can be set up promptly. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Allocating%20Controller%20Objects%20for%20I/O%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/allocating-system-space-memory.md b/windows-driver-docs-pr/kernel/allocating-system-space-memory.md new file mode 100644 index 0000000000..1987262fcd --- /dev/null +++ b/windows-driver-docs-pr/kernel/allocating-system-space-memory.md @@ -0,0 +1,62 @@ +--- +title: Allocating System-Space Memory +author: windows-driver-content +description: Allocating System-Space Memory +ms.assetid: eee425b3-6ddd-4e9d-b51d-1f2c9ea106a5 +keywords: ["memory management WDK kernel , system-allocated space", "system-allocated space WDK kernel", "allocating system-space memory", "allocating I/O buffer memory", "I/O buffer memory allocations WDK kernel", "buffer memory allocations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Allocating System-Space Memory + + +## + + +Drivers can use system-allocated space within their [device extensions](device-extensions.md) as global storage areas for device-specific information. Drivers can use only the kernel stack to pass small amounts of data to their internal routines. Some drivers have to allocate additional, larger amounts of system-space memory, typically for I/O buffers. + +To allocate I/O buffer space, the best memory allocation routines to use are [**MmAllocateNonCachedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554479), [**MmAllocateContiguousMemorySpecifyCache**](https://msdn.microsoft.com/library/windows/hardware/ff554464), [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575) (if the driver's device uses bus-master DMA or a system DMA controller's auto-initialize mode), or [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520). + +Nonpaged pool typically becomes fragmented as the system runs, so a driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine should call these routines to set up any long-term I/O buffers the driver needs. Each of these routines, except [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520), allocates memory that is aligned on a processor-specific boundary (determined by the processor's data-cache-line size) to provide best performance. + +Drivers should allocate I/O buffers as economically as possible, because nonpaged pool memory is a limited system resource. Typically, a driver should avoid calling these support routines repeatedly to request allocations of less than PAGE\_SIZE because each allocation that is less than PAGE\_SIZE also comes with a pool header that is used to internally manage the allocation. + +### Tips for Allocating Driver Buffer Space Economically + +To allocate I/O buffer memory economically, be aware of the following: + +- Each call to [**MmAllocateNonCachedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554479) or [**MmAllocateContiguousMemorySpecifyCache**](https://msdn.microsoft.com/library/windows/hardware/ff554464) always returns a full multiple of the system's page size, of nonpaged system-space memory, whatever the size of the requested allocation. Therefore, requests for less than a page are rounded up to a full page and any remainder bytes on the page are wasted; they are inaccessible by the driver that called the function and are unusable by other kernel-mode code. + +- Each call to [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575) uses at least one adapter object map register, which maps at least one byte and at most one page. For more information about map registers and using common buffers, see [Adapter Objects and DMA](adapter-objects-and-dma.md). + +### Allocating Memory with ExAllocatePoolWithTag + +Drivers can also call [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520), specifying one of the following system-defined [**POOL\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff559707) values for the *PoolType* parameter: + +- *PoolType* = **NonPagedPool** for any objects or resources not stored in a device extension or controller extension that the driver might access while it is running at IRQL > APC\_LEVEL. + + For this *PoolType* value, [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) allocates the amount of memory that is requested if the specified *NumberOfBytes* is less than or equal to PAGE\_SIZE. Otherwise, any remainder bytes on the last-allocated page are wasted: inaccessible to the caller and unusable by other kernel-mode code. + + For example, on an x86, an allocation request of 5 kilobytes (KB) returns two 4-KB pages. The last 3 KB of the second page is unavailable to the caller or another caller. To avoid wasting nonpaged pool, the driver should allocate multiple pages efficiently. In this case, for example, the driver could make two allocations, one for PAGE\_SIZE and the other for 1 KB, to allocate a total of 5 KB. + + **Note**  Starting with Windows Vista, the system automatically adds the additional memory so two allocations are unnecessary. + +   + +- *PoolType* = **PagedPool** for memory that is always accessed at IRQL <= APC\_LEVEL and is not in the file system's write path. + +**ExAllocatePoolWithTag** returns a **NULL** pointer if it cannot allocate the requested number of bytes. Drivers should always check the returned pointer. If its value is **NULL**, the **DriverEntry** routine (or any other driver routine that returns NTSTATUS values) should return STATUS\_INSUFFICIENT\_RESOURCES or handle the error condition if possible. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Allocating%20System-Space%20Memory%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/allocating-the-bus-master-adapter-object.md b/windows-driver-docs-pr/kernel/allocating-the-bus-master-adapter-object.md new file mode 100644 index 0000000000..e890ca0f1a --- /dev/null +++ b/windows-driver-docs-pr/kernel/allocating-the-bus-master-adapter-object.md @@ -0,0 +1,84 @@ +--- +title: Allocating the Bus-Master Adapter Object +author: windows-driver-content +description: Allocating the Bus-Master Adapter Object +ms.assetid: fc80d3f8-a12e-40bd-8b0e-c6bca2f9e7de +keywords: ["allocating bus-master adapter objects", "bus-master DMA WDK kernel", "DMA transfers WDK kernel , bus-master DMA", "adapter objects WDK kernel , bus-master DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Allocating the Bus-Master Adapter Object + + +## + + +To prepare for packet-based, bus-master DMA, a driver calls [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) and [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) after receiving an [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819). Before the driver calls these routines, its dispatch routine should check the validity of the IRP's parameters. It might also queue the IRP to another driver routine for further processing. The transfer request is the current IRP requiring a device I/O operation. + +The driver routine that calls **AllocateAdapterChannel** must be executing at IRQL = DISPATCH\_LEVEL. Along with a pointer to the adapter object returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220), a driver must supply the following when it calls **AllocateAdapterChannel**: + +- A pointer to the target device object for the current IRP + +- The entry point for its [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine + +- A pointer to any driver-determined context information the *AdapterControl* routine will use + +**AllocateAdapterChannel** queues the driver's *AdapterControl* routine, which runs when the adapter object is free and a set of [map registers](map-registers.md) has been allocated for the driver's DMA operations to or from the target device. + +On entry, an *AdapterControl* routine is given the *DeviceObject* and *Context* pointers passed in the call to **AllocateAdapterChannel**, as well as a handle (*MapRegisterBase*) for the allocated map registers. + +The *AdapterControl* routine also is given a pointer to the **DeviceObject->CurrentIrp** if the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. If the driver manages its own queuing of IRPs instead of having a *StartIo* routine, the driver should include a pointer to the current IRP as part of the context it passes when it calls **AllocateAdapterChannel**. + +For the driver of a bus-master DMA device without scatter/gather capabilities, the *AdapterControl* routine usually does the following: + +1. Saves or initializes whatever context the driver maintains about DMA operations. The context might include the input *MapRegisterBase* handle the driver must pass to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) and [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917), the **Length** in bytes of the requested transfer from its I/O stack location in the IRP, and so forth. + +2. Calls [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) followed by **MapTransfer** (described in [Setting Up a Transfer Operation](setting-up-a-transfer-operation.md), next) to get the logical address its device can use to start the transfer operation. + +3. Sets up the bus-master adapter to start the transfer operation. + +4. Returns the value **DeallocateObjectKeepRegisters**. + +For the driver of a bus-master device with scatter/gather capabilities, the *AdapterControl* routine usually does the following: + +1. Saves or initializes whatever state the driver maintains about DMA operations, such as saving the *MapRegisterBase* handle the driver must pass to **MapTransfer** and **FlushAdapterBuffers**, the **Length** in bytes of the requested transfer from its I/O stack location in the IRP, and so forth. + +2. Calls **MmGetMdlVirtualAddress** followed by **MapTransfer** (described in the next subsection) to get the logical address its device can use to start the transfer operation. + + The *AdapterControl* routine calls MapTransfer repeatedly until it has used all the available map registers to build a scatter/gather list for the bus-master adapter. + +3. Sets up the bus-master adapter to start the transfer operation. + +4. Returns the value **DeallocateObjectKeepRegisters**. + +For additional information, see [Writing AdapterControl Routines](writing-adaptercontrol-routines.md). + +Note that drivers that perform bus-master DMA can use the [**GetScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff546531) and [**PutScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff559967) routines regardless of whether their devices support scatter/gather DMA. Using these routines changes the requirements for the driver's *AdapterControl* routine; see [Using Scatter/Gather DMA](using-scatter-gather-dma.md) for details. + +An *AdapterControl* routine must return a system-defined value of type IO\_ALLOCATION\_ACTION. For drivers that use bus-master DMA, the *AdapterControl* routine should typically return the value **DeallocateObjectKeepRegisters**, which allows the driver to retain the allocated map registers for the target device object until it has transferred all the requested data for the current IRP. After the transfer is complete, the DPC routine should call [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) to free the allocated map registers. In cases where the device does not support command queuing, however, the *AdapterControl* routine can return **KeepObject** when the transfer for the current IRP is complete, and the DPC routine can call [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) instead. + +An *AdapterControl* routine cannot wait for the bus-master adapter to complete a DMA operation. + +Regardless of whether the bus-master adapter supports scatter/gather, the *AdapterControl* routine must at least do the following: + +1. Save necessary context information—particularly the *MapRegisterBase* handle—in the driver's device extension, controller extension, or other driver-accessible resident storage area (nonpaged pool, allocated by the driver). The driver must pass this handle when it calls **MapTransfer** and **FlushAdapterBuffers**. + +2. Return **DeallocateObjectKeepRegisters**. + +Another driver routine (probably the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine) must call **FlushAdapterBuffers** when each DMA transfer operation is done. This routine also must set up any additional DMA operations necessary to satisfy the current IRP. + +When the driver has satisfied the current IRP's transfer request or must fail the IRP due to a device or bus I/O error, it must call **FreeMapRegisters**. This call should occur immediately following the last call to **FlushAdapterBuffers** for the current IRP, so that the driver can service other DMA requests, possibly for other devices on the bus. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Allocating%20the%20Bus-Master%20Adapter%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/alternatives-to-mutex-objects.md b/windows-driver-docs-pr/kernel/alternatives-to-mutex-objects.md new file mode 100644 index 0000000000..7b6720307d --- /dev/null +++ b/windows-driver-docs-pr/kernel/alternatives-to-mutex-objects.md @@ -0,0 +1,33 @@ +--- +title: Alternatives to Mutex Objects +author: windows-driver-content +description: Alternatives to Mutex Objects +ms.assetid: c3b78155-426a-449d-8678-5666a7a12cbd +keywords: ["kernel dispatcher objects WDK , mutex objects", "dispatcher objects WDK kernel , mutex objects", "mutex objects WDK kernel", "fast mutexes WDK kernel", "guarded mutexes WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Alternatives to Mutex Objects + + +Fast mutexes and guarded mutexes can be used as a replacement for mutex objects. A fast mutex or guarded mutex can be acquired and released faster than a mutex object, but they have the following restrictions: + +- Drivers cannot use the [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324) routines to wait for a fast or guarded mutex. Thus, a driver cannot wait for a fast or guarded mutex and a dispatcher object simultaneously. + +- Drivers cannot acquire a fast or guarded mutex recursively. If a driver tries to acquire a fast or guarded mutex that it has already acquired, the driver will deadlock. A mutex object, however, can be acquired recursively. + +For more information about fast and guarded mutexes, see [Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Alternatives%20to%20Mutex%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/always-preemptible-and-always-interruptible.md b/windows-driver-docs-pr/kernel/always-preemptible-and-always-interruptible.md new file mode 100644 index 0000000000..6a97411a01 --- /dev/null +++ b/windows-driver-docs-pr/kernel/always-preemptible-and-always-interruptible.md @@ -0,0 +1,62 @@ +--- +title: Always Preemptible and Always Interruptible +author: windows-driver-content +description: Always Preemptible and Always Interruptible +ms.assetid: 3da667b4-50f3-4536-9049-65719fa003ce +keywords: ["preemptible designs WDK kernel", "interruptible designs WDK kernel", "interrupt request levels WDK kernel", "IRQL levels WDK kernel", "variable priority attributes WDK kernel", "prioritizing criteria WDK kernel", "hardware priorities WDK kernel", "higher IRQL levels WDK kernel", "lower IRQL levels WDK kernel", "PASSIVE_LEVEL WDK", "APC_LEVEL WDK", "DISPATCH_LEVEL WDK", "WAKE_LEVEL WDK", "deferred procedure calls WDK kernel", "DPCs WDK kernel", "arbitrary thread context WDK kernel", "thread preemption WDK kernel", "thread priorities WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Always Preemptible and Always Interruptible + + +## + + +The goal of the preemptible, interruptible design of the operating system is to maximize system performance. Any thread can be preempted by a thread with a higher priority, and any driver's interrupt service routine (ISR) can be interrupted by a routine that runs at a higher interrupt request level (IRQL). + +The kernel component determines when a code sequence runs, according to one of these prioritizing criteria: + +- The kernel-defined run-time priority scheme for threads. + + Every thread in the system has an associated priority attribute. In general, most threads have *variable* priority attributes: they are always preemptible and are scheduled to run round-robin with all other threads that are currently at the same priority level. Some threads have *real-time* priority attributes: these time-critical threads run to completion unless they are preempted by a thread that has a higher real-time priority attribute. The Microsoft Windows architecture does not provide an inherently real-time system. + + Whatever its priority attribute, any thread in the system can be preempted when hardware interrupts and certain types of software interrupts occur. + +- The kernel-defined *interrupt request level* (IRQL) to which a particular interrupt vector is assigned on a given platform. + + The kernel prioritizes hardware and software interrupts so that some kernel-mode code, including most drivers, runs at higher IRQLs, thereby making it have a higher scheduling priority than other threads in the system. The particular IRQL at which a piece of kernel-mode driver code executes is determined by the *hardware priority* of its underlying device. + + Kernel-mode code is always interruptible: an interrupt with a higher IRQL value can occur at any time, thereby causing another piece of kernel-mode code that has a higher system-assigned IRQL to be run immediately on that processor. However, when a piece of code runs at a given IRQL, the kernel masks all interrupt vectors with a lesser or equal IRQL value on the processor. + +The lowest IRQL level is called PASSIVE\_LEVEL. At this level, no interrupt vectors are masked. Threads generally run at IRQL=PASSIVE\_LEVEL. The next higher IRQL levels are for software interrupts. These levels include APC\_LEVEL, DISPATCH\_LEVEL or, for kernel debugging, WAKE\_LEVEL. Device interrupts have still higher IRQL values. The kernel reserves the highest IRQL values for system-critical interrupts, such as those from the system clock or bus errors. + +Some system support routines run at IRQL=PASSIVE\_LEVEL, either because they are implemented as pageable code or access pageable data, or because some kernel-mode components set up their own threads. + +Similarly, some [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842) usually run at IRQL=PASSIVE\_LEVEL. However, several standard driver routines run either at IRQL=DISPATCH\_LEVEL or, for a lowest-level driver, at device IRQL (also called *DIRQL*). For more information about IRQLs, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +Every routine in a driver is interruptible. This includes any routine that is running at a higher IRQL than PASSIVE\_LEVEL. Any routine that is running at a particular IRQL retains control of the processor only if no interrupt for a higher IRQL occurs while that routine is running. + +Unlike the drivers in some older personal computer operating systems, a Microsoft Windows driver's ISR is never a large, complex routine that does most of the driver's I/O processing. This is because any driver's *interrupt service routine* (ISR) can be interrupted by another routine (for example, by another driver's ISR) that runs at a higher IRQL. Thus, the driver's ISR does not necessarily retain control of a CPU, uninterrupted, from the beginning of its execution path to the end. + +In Windows drivers, an ISR typically saves hardware state information, queues a *deferred procedure call* (DPC), and then quickly exits. Later, the system dequeues the driver's DPC so that the driver can complete I/O operations at a lower IRQL (DISPATCH\_LEVEL). For good overall system performance, all routines that run at high IRQLs must relinquish control of the CPU quickly. + +In Windows, all threads have a thread context. This context consists of information that identifies the process that owns the thread, plus other characteristics such as the thread's access rights. + +In general, only a highest-level driver is called in the context of the thread that is requesting the driver's current I/O operation. An intermediate-level or lowest-level driver can never assume that it is executing in the context of the thread that requested its current I/O operation. + +Consequently, driver routines usually execute in an *arbitrary thread context*—the context of whatever thread is current when a standard driver routine is called. For performance reasons (to avoid context switches), very few drivers set up their own threads. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Always%20Preemptible%20and%20Always%20Interruptible%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/application-notification.md b/windows-driver-docs-pr/kernel/application-notification.md new file mode 100644 index 0000000000..e7220c58b7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/application-notification.md @@ -0,0 +1,35 @@ +--- +title: Application Notification +author: windows-driver-content +description: Application Notification +ms.assetid: ca6cf2e7-e710-4c23-8440-54cdff736dc0 +keywords: ["dynamic hardware partitioning WDK , application notification", "hardware partitioning WDK dynamic , application notification", "partitions WDK dynamic hardware , application notification", "application notification WDK dynamic hardware partitioning", "notification WDK dynamic hardware partitioning , application"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Application Notification + + +This section discusses how the operating system can notify a user-mode application when you dynamically add a new processor or memory module to a hardware partition. + +This section includes the following topics: + +[Introduction to Application Notification](introduction-to-application-notification.md) + +[Registering for Application Notification](registering-for-application-notification.md) + +[Processing an Application Notification](processing-an-application-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Application%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/asynchronous-driver-notification.md b/windows-driver-docs-pr/kernel/asynchronous-driver-notification.md new file mode 100644 index 0000000000..fdb02d903d --- /dev/null +++ b/windows-driver-docs-pr/kernel/asynchronous-driver-notification.md @@ -0,0 +1,33 @@ +--- +title: Asynchronous Driver Notification +author: windows-driver-content +description: Asynchronous Driver Notification +ms.assetid: a7f79de5-8958-4d85-8eea-761e04f1a52e +keywords: ["driver notification WDK dynamic hardware partitioning , asynchronous", "asynchronous notification WDK dynamic hardware partitioning", "notification WDK dynamic hardware partitioning , asynchronous", "asynchronous driver notification WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Asynchronous Driver Notification + + +This section discusses asynchronous driver notification when you dynamically add a new processor or memory module to a hardware partition. + +This section includes the following topics: + +[Registering for Asynchronous Driver Notification](registering-for-asynchronous-driver-notification.md) + +[Processing an Asynchronous Driver Notification](processing-an-asynchronous-driver-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Asynchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/asynchronous-i-o-programming.md b/windows-driver-docs-pr/kernel/asynchronous-i-o-programming.md new file mode 100644 index 0000000000..69a4595060 --- /dev/null +++ b/windows-driver-docs-pr/kernel/asynchronous-i-o-programming.md @@ -0,0 +1,21 @@ +--- +title: Asynchronous I/O Programming +author: windows-driver-content +description: Asynchronous I/O Programming +ms.assetid: f50c98ab-3aae-43f6-be91-2ae587105767 +--- + +# Asynchronous I/O Programming + + +Asynchronous programming does not force everyone else to wait. This is the preferred technique for programming Windows device drivers. Supporting asynchronous I/O is one of the design goals of WDM drivers. For more information about asynchronous I/O in drivers, see [Supporting Asynchronous I/O](supporting-asynchronous-i-o.md). For device drivers, using interrupts is the best way to program asynchronously. You simply send a request to your device and let the system take control. Then when your device wants to tell you something, it triggers an interrupt that the operating system processes by calling an interrupt handler in your driver. This communication is handled through IRPs. For more information about IRPS, see [Handling IRPs](handling-irps.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Asynchronous%20I/O%20Programming%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/asynchronous-procedure-calls.md b/windows-driver-docs-pr/kernel/asynchronous-procedure-calls.md new file mode 100644 index 0000000000..31ec4daa61 --- /dev/null +++ b/windows-driver-docs-pr/kernel/asynchronous-procedure-calls.md @@ -0,0 +1,33 @@ +--- +title: Asynchronous Procedure Calls +author: windows-driver-content +description: Asynchronous Procedure Calls +ms.assetid: c2d45c84-9b61-41e1-9a8e-eabbc0609a0b +keywords: ["synchronization WDK kernel , asynchronous procedure calls", "kernel APCs WDK", "thread APCs WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Asynchronous Procedure Calls + + +This section includes: + +[Types of APCs](types-of-apcs.md) + +[Disabling APCs](disabling-apcs.md) + +[Critical Regions and Guarded Regions](critical-regions-and-guarded-regions.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Asynchronous%20Procedure%20Calls%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/avoid-polling-devices.md b/windows-driver-docs-pr/kernel/avoid-polling-devices.md new file mode 100644 index 0000000000..366ccf5fe8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/avoid-polling-devices.md @@ -0,0 +1,45 @@ +--- +title: Avoid Polling Devices +author: windows-driver-content +description: Avoid Polling Devices +ms.assetid: c50c9c6f-c8eb-4e52-854a-3ebc4fdc874c +keywords: ["I/O WDK kernel , device polling", "device polling WDK I/O", "polling devices WDK I/O", "loop counters WDK I/O", "counters WDK I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Avoid Polling Devices + + +## + + +A device driver should avoid polling its device unless absolutely necessary, and should never use a whole time-slice for polling. Polling a device is an expensive operation that makes any operating system compute-bound within the polling driver. A device driver that does much polling interferes with I/O operations on other devices and can make the system slow and unresponsive to users. + +Recently developed devices, which are as technologically advanced as the processors on which Windows is designed to run, seldom require a driver to poll its device, either to ensure that the device is ready to start an I/O operation or that an operation is complete. + +Nevertheless, some devices still in use were designed to work with old processors, which had narrow data buses, slow clock rates, and single-user, single-tasking operating systems that did synchronous I/O. Such devices might require polling or some other means of waiting for the device to update its registers. + +Although it might seem logical to solve a slow-device problem by coding a simple loop that increments a counter, thereby "wasting" a minimum interval while the device updates registers, such a driver is unlikely to be portable across Windows platforms. The loop counter maximum would require customization for each platform. Furthermore, if the driver is compiled with a good optimizing compiler, the compiler might remove the driver's counter variable and the loop(s) where it is incremented. + +**Note**   Follow this implementation guideline if the driver must stall while the device hardware updates state: +A driver can call [**KeStallExecutionProcessor**](https://msdn.microsoft.com/library/windows/hardware/ff553295) before it reads device registers. The driver should minimize the interval it stalls and should, in general, specify a stall interval no longer than 50 microseconds. + +The granularity of a **KeStallExecutionProcessor** interval is one microsecond. + +If the device frequently requires more than 50 microseconds to update state, consider setting up a [device-dedicated thread](device-dedicated-threads.md) in the driver. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Avoid%20Polling%20Devices%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/avoiding-misalignment-of-fixed-precision-data-types.md b/windows-driver-docs-pr/kernel/avoiding-misalignment-of-fixed-precision-data-types.md new file mode 100644 index 0000000000..b2ef1354f7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/avoiding-misalignment-of-fixed-precision-data-types.md @@ -0,0 +1,153 @@ +--- +title: Avoiding Misalignment of Fixed-Precision Data Types +author: windows-driver-content +description: Avoiding Misalignment of Fixed-Precision Data Types +ms.assetid: 4e214bd8-b622-447a-b484-bd1d5d239de7 +keywords: ["file system control codes WDK 64-bit", "FSCTL WDK 64-bit", "control codes WDK 64-bit", "I/O control codes WDK kernel , 32-bit I/O in 64-bit drivers", "IOCTLs WDK kernel , 32-bit I/O in 64-bit drivers", "pointer precision WDK 64-bit", "fixed-precision data types WDK 64-bit", "misaligned fixed-precision data types"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Avoiding Misalignment of Fixed-Precision Data Types + + +## + + +Unfortunately, it is possible for a data type to have the same size, but different alignment requirements, for 32-bit and 64-bit programming. Thus not all IOCTL/FSCTL buffer misalignment problems can be avoided by changing pointer-precision data types to fixed-precision types. This means that kernel-mode driver IOCTLs and FSCTLs that pass buffers containing certain fixed-precision data types (or pointers to them) may also need to be thunked. + +### Which Data Types Are Affected + +The problem affects fixed-precision data types that are themselves structures. This is because the rules for determining alignment requirements for structures are platform-specific. + +For example, **\_\_int64**, LARGE\_INTEGER, and KFLOATING\_SAVE must be aligned on a 4-byte boundary on x86 platforms. However, on Itanium-based machines, they must be aligned on an 8-byte boundary. + +To determine the alignment requirement for a given data type on a particular platform, use the **TYPE\_ALIGNMENT** macro on that platform. + +### How To Fix the Problem + +In the following example, the IOCTL is a METHOD\_NEITHER IOCTL, so the **Irp->UserBuffer** pointer is passed directly from the user-mode application to the kernel-mode driver. No validation is performed on buffers used in IOCTLs and FSCTLs. Thus a call to [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) or [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) is required before the buffer pointer can be safely dereferenced. + +Assuming that the 32-bit application has passed a valid value for **Irp->UserBuffer**, the LARGE\_INTEGER structure pointed to by **p->DeviceTime** will be aligned on a 4-byte boundary. **ProbeForRead** checks this alignment against the value passed in its *Alignment* parameter, which in this case is **TYPE\_ALIGNMENT** (LARGE\_INTEGER). On x86 platforms, this macro expression returns 4 (bytes). However, on Itanium-based machines, it returns 8, causing **ProbeForRead** to raise a STATUS\_DATATYPE\_MISALIGNMENT exception. + +**Note**   Removing the **ProbeForRead** call does not fix the problem, but only makes it harder to diagnose. + +  + +``` +typedef struct _IOCTL_PARAMETERS2 { + LARGE_INTEGER DeviceTime; +} IOCTL_PARAMETERS2, *PIOCTL_PARAMETERS2; + +#define SETTIME_FUNCTION 1 +#define IOCTL_SETTIME CTL_CODE(FILE_DEVICE_UNKNOWN, \ + SETTIME_FUNCTION, METHOD_NEITHER, FILE_ANY_ACCESS) + +... + +case IOCTL_SETTIME: + PIOCTL_PARAMETERS2 p = (PIOCTL_PARAMETERS2)Irp->UserBuffer; + + try { + if (Irp->RequestorMode != KernelMode) { + ProbeForRead ( p->DeviceTime, + sizeof( LARGE_INTEGER ), + TYPE_ALIGNMENT( LARGE_INTEGER )); + } + status = DoSomeWork(p->DeviceTime); + + } except( EXCEPTION_EXECUTE_HANDLER ) { +``` + +The following sections tell how to fix the problem described above. Note that all code snippets have been edited for brevity. + +### Solution 1: Copy the Buffer + +The safest way to avoid misalignment problems is to make a copy of the buffer before accessing its contents, as in the following example. + +``` +case IOCTL_SETTIME: { + PIOCTL_PARAMETERS2 p = (PIOCTL_PARAMETERS2)Irp->UserBuffer; +#if _WIN64 + IOCTL_PARAMETERS2 LocalParams2; + + RtlCopyMemory(&LocalParams2, p, sizeof(IOCTL_PARAMETERS2)); + p = &LocalParams2; +#endif + + status = DoSomeWork(p->DeviceTime); + break; +} +``` + +This solution can be optimized for better performance by first checking whether the buffer contents are correctly aligned. If so, the buffer can be used as is. Otherwise, the driver makes a copy of the buffer. + +``` +case IOCTL_SETTIME: { + PIOCTL_PARAMETERS2 p = (PIOCTL_PARAMETERS2)Irp->UserBuffer; +#if _WIN64 + IOCTL_PARAMETERS2 LocalParams2; + + if ( (ULONG_PTR)p & (TYPE_ALIGNMENT(IOCTL_PARAMETERS2)-1)) { + // The buffer contents are not correctly aligned for this + // platform, so copy them into a properly aligned local + // buffer. + RtlCopyMemory(&LocalParams2, p, sizeof(IOCTL_PARAMETERS2)); + p = &LocalParams2; + } +#endif + + status = DoSomeWork(p->DeviceTime); + break; +} +``` + +### Solution 2: Use the UNALIGNED Macro + +The **UNALIGNED** macro tells the C compiler to generate code that can access the **DeviceTime** field without taking an alignment fault. Note that using this macro on Itanium-based platforms is likely to make your driver significantly larger and slower. + +``` +typedef struct _IOCTL_PARAMETERS2 { + LARGE_INTEGER DeviceTime; +} IOCTL_PARAMETERS2; +typedef IOCTL_PARAMETERS2 UNALIGNED *PIOCTL_PARAMETERS2; +``` + +### Pointers Are Also Affected + +The misalignment problem described earlier can also occur in buffered I/O requests. In the following example, the IOCTL buffer contains an embedded pointer to a LARGE\_INTEGER structure. + +``` +typedef struct _IOCTL_PARAMETERS3 { + LARGE_INTEGER *pDeviceCount; +} IOCTL_PARAMETERS3, *PIOCTL_PARAMETERS3;0 + +#define COUNT_FUNCTION 1 +#define IOCTL_GETCOUNT CTL_CODE(FILE_DEVICE_UNKNOWN, \ + COUNT_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) +``` + +Like the METHOD\_NEITHER IOCTL and FSCTL buffer pointers described earlier, pointers embedded in buffered I/O requests are also passed directly from the user-mode application to the kernel-mode driver. No validation is performed on these pointers. Thus a call to [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) or [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879), enclosed in a **try/except** block, is required before the embedded pointer can be safely dereferenced. + +As in the earlier example, assuming that the 32-bit application has passed a valid value for **pDeviceCount**, the LARGE\_INTEGER structure pointed to by **pDeviceCount** will be aligned on a 4-byte boundary. **ProbeForRead** and **ProbeForWrite** check this alignment against the value of the *Alignment* parameter, which in this case is TYPE\_ALIGNMENT (LARGE\_INTEGER). On x86 platforms, this macro expression returns 4 (bytes). However, on Itanium-based machines, it returns 8, causing **ProbeForRead** or **ProbeForWrite** to raise a STATUS\_DATATYPE\_MISALIGNMENT exception. + +This problem can be fixed either by making a properly aligned copy of the LARGE\_INTEGER structure, as in Solution 1, or by using the UNALIGNED macro as follows: + +``` +typedef struct _IOCTL_PARAMETERS3 { + LARGE_INTEGER UNALIGNED *pDeviceCount; +} IOCTL_PARAMETERS3, *PIOCTL_PARAMETERS3; +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Avoiding%20Misalignment%20of%20Fixed-Precision%20Data%20Types%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/basic-calling-pattern-for-version-3-dma-routines.md b/windows-driver-docs-pr/kernel/basic-calling-pattern-for-version-3-dma-routines.md new file mode 100644 index 0000000000..3269dfb81b --- /dev/null +++ b/windows-driver-docs-pr/kernel/basic-calling-pattern-for-version-3-dma-routines.md @@ -0,0 +1,111 @@ +--- +title: Basic Calling Pattern for Version-3 DMA Routines +author: windows-driver-content +description: To perform a DMA transfer that uses the routines in version 3 of the DMA operations interface, your driver should follow the steps described in the following list. +ms.assetid: 5D73120F-79F5-4C9A-8AE5-25D5CF9B06F5 +--- + +# Basic Calling Pattern for Version-3 DMA Routines + + +To perform a DMA transfer that uses the routines in version 3 of the DMA operations interface, your driver should follow the steps described in the following list. These steps are common to both subordinate devices and bus-master devices. Version 3 of this interface is available starting with Windows 8. For more information about the routines in this interface, see [**DMA\_OPERATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff544071). + +## Step 1: Obtain a DMA adapter object + + +In preparation for a DMA transfer, the driver calls the [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) routine to obtain a DMA adapter object. A DMA adapter object is a software object that represents either a bus-master device, or a request line on a system DMA controller. This object contains the DMA operations interface for the bus that is used to transfer data to or from the device. Additionally, this object synchronizes the driver's access to the shared resources that are required to perform the transfer. For more information, see [Introduction to Adapter Objects](introduction-to-adapter-objects.md). + +## Step 2: Obtain a description of the required DMA resources + + +The driver calls the [**GetDmaTransferInfo**](https://msdn.microsoft.com/library/windows/hardware/hh451125) routine to get a description of the DMA resources that it needs to perform the transfer. + +The input parameters to this call describe the memory buffer to use for the transfer, and the direction (read or write) of the transfer. + +The resource requirements obtained from this call include the number of map registers and the size of the scatter/gather list that is needed to describe the data buffer for the transfer. In the subsequent call to the [**AllocateAdapterChannelEx**](https://msdn.microsoft.com/library/windows/hardware/hh406340) routine (see [step 3](#step-3)), the driver supplies the map register count as an input parameter. + +## Step 3: Request the required DMA resources + + +The driver calls the [**AllocateAdapterChannelEx**](https://msdn.microsoft.com/library/windows/hardware/hh406340) routine to allocate resources to assign to the DMA adapter object. These resources include a DMA channel and map registers. + +An **AllocateAdapterChannelEx** call can be asynchronous or synchronous. + +If the DMA\_SYNCHRONOUS\_CALLBACK flag is not set, the call is asynchronous. In this case, the *ExecutionRoutine* parameter points to a caller-supplied execution routine that is called when the requested resources are available. If successful, an asynchronous **AllocateAdapterChannelEx** call returns STATUS\_SUCCESS without waiting for the execution routine to run. + +If the DMA\_SYNCHRONOUS\_CALLBACK flag is set, the **AllocateAdapterChannelEx** call is synchronous. In this case, the *ExecutionRoutine* parameter in the call is optional, and **AllocateAdapterChannelEx** behaves as follows: + +- If *ExecutionRoutine* is non-NULL, and the DMA resources can be allocated immediately, **AllocateAdapterChannelEx** calls the execution routine in the context of the calling thread. After the execution routine finishes running, **AllocateAdapterChannelEx** returns STATUS\_SUCCESS. If the resources are not immediately available, **AllocateAdapterChannelEx** fails and returns error status code STATUS\_INSUFFICIENT\_RESOURCES. + +- If *ExecutionRoutine* is NULL, and **AllocateAdapterChannelEx** can immediately allocate the DMA resources, **AllocateAdapterChannelEx** returns STATUS\_SUCCESS. If all resources are not immediately available, the call fails with error status code STATUS\_INSUFFICIENT\_RESOURCES. + +For synchronous calls that return STATUS\_SUCCESS, if the *MapRegisterBase* parameter to **AllocateAdapterChannelEx** is non-NULL, **AllocateAdapterChannelEx** writes the base address of the allocated map registers to the address pointed to by the *MapRegisterBase* parameter. If *ExecutionRoutine* is NULL, *MapRegisterBase* must be non-NULL. If *ExecutionRoutine* is non-NULL, the *MapRegisterBase* parameter to **AllocateAdapterChannelEx** is optional, and the execution routine receives the map register base address as an input parameter. + +For asynchronous **AllocateAdapterChannelEx** calls, *ExecutionRoutine* must be non-NULL, and the execution routine receives the map register base address as an input parameter. + +In subsequent calls to the [**MapTransferEx**](https://msdn.microsoft.com/library/windows/hardware/hh406521) routine (see [step 5](#step-5)), the driver supplies the map register base address as an input parameter. + +If *ExecutionRoutine* is non-NULL, the execution routine returns a status value to indicate the disposition of the allocated resources. For system DMA transfers, this return value must be **KeepObject**. This value informs the operating system that the adapter object (and all of its allocated resources) is in use and should not be freed. If no execution routine is supplied, the driver must instead call the [**FreeAdapterObject**](https://msdn.microsoft.com/library/windows/hardware/hh451107) routine and supply **KeepObject** as the *AllocationOption* parameter. + +## Step 4: If necessary, cancel the pending resource request + + +After an **AllocateAdapterChannelEx** call queues a DMA adapter to wait for DMA resources, the driver can, if necessary, call the [**CancelAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/hh406374) routine to cancel the pending resource request. + +If **CancelAdapterChannel** returns TRUE, the resource request is successfully canceled. If an execution routine was supplied in the **AllocateAdapterChannelEx** call, this routine does not run. + +If **CancelAdapterChannel** returns FALSE, the resource request cannot be canceled because it was already granted. If an execution routine was supplied in the **AllocateAdapterChannelEx** call, this routine will be called. + +## Step 5: Initialize the DMA resources and start the DMA transfer + + +The driver calls [**MapTransferEx**](https://msdn.microsoft.com/library/windows/hardware/hh406521) to initialize the DMA resources and to start the DMA transfer. This call might occur in the same driver thread that calls **AllocateAdapterChannelEx**, or it might occur in the execution routine that the driver supplies to **AllocateAdapterChannelEx**. If more than one **MapTransferEx** call is required to transfer the entire DMA data buffer, a later **MapTransferEx** call might occur in the completion routine for the previous **MapTransferEx** call. + +**MapTransferEx** supports chained MDLs as input parameters. Each MDL describes a region of the DMA buffer that is contiguous in virtual memory. When **MapTransferEx** builds the scatter/gather list, it automatically handles transitions from one virtually contiguous buffer region to the next without driver intervention. For more information, see [Using the MapTransferEx Routine](using-the-maptransferex-routine.md). + +For a system DMA transfer, a pointer to a DMA completion routine can be passed to **MapTransferEx** in the optional *DmaCompletionRoutine* parameter. This routine is scheduled to run at dispatch level in response to an interrupt from the system DMA controller that indicates that the DMA transfer is complete. + +If **MapTransferEx** is unable to map the entire requested transfer size, it will set the \**Length* output parameter to the length that was mapped, and return STATUS\_SUCCESS. + +## Step 6: If necessary, perform hardware-specific operations + + +**MapTransferEx** returns STATUS\_SUCCESS to indicate that the DMA transfer is successfully initiated. On some platforms, the driver might have to take some additional action, outside of the **MapTransferEx** call, to start the transfer, but this type of delayed start is not required for all platforms. Drivers must not depend on such delays for decisions about using and freeing allocated resources. + +The routines in the DMA operations interface maintain cache coherency for DMA transfers in a way that is transparent to the drivers that use these routines. On platforms that do not enforce cache coherency in hardware, **MapTransferEx** ensures that processor data caches are flushed before write (memory-to-device) transfers. For read (device-to-memory) transfers, the caches are invalidated during the call to the [**FlushAdapterBuffersEx**](https://msdn.microsoft.com/library/windows/hardware/hh451102) routine (see [step 8](#step-8)) that follows every **MapTransferEx** call. + +## Step 7: Receive notification when the DMA transfer finishes + + +When a DMA transfer completes, the driver is notified in one of these two ways: + +- An interrupt to the device driver, for a bus-master device +- Execution of the driver-supplied completion routine, for a subordinate device that uses a system DMA controller + +For a system DMA transfer, a driver can supply a completion routine to **MapTransferEx** as an input parameter. +## Step 8: Flush any data that remains in the cache + + +After the DMA transfer completes, the driver must call the [**FlushAdapterBuffersEx**](https://msdn.microsoft.com/library/windows/hardware/hh451102) routine to flush any data that remains in the cache. The driver must call **FlushAdapterBuffersEx** after every **MapTransferEx** call. + +If a **MapTransferEx** call maps only a part of the DMA data buffer, the driver must call **MapTransferEx** again to map the remaining data. A complex transfer might require several **MapTransferEx** calls. For each additional **MapTransferEx** call, repeat steps 5 through 8. + +## Step 9: Free the DMA channel and map registers + + +After the entire DMA data buffer is successfully mapped and the final transfer completes, the driver must call the [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff549101) routine to free the DMA channel and any previously allocated map registers. + +## Step 10: Release the DMA adapter object + + +After all DMA transfers are complete and any previously allocated map registers are freed, the driver calls the [**PutDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff559965) routine to release the adapter object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Basic%20Calling%20Pattern%20for%20Version-3%20DMA%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/buffer-descriptions-for-i-o-control-codes.md b/windows-driver-docs-pr/kernel/buffer-descriptions-for-i-o-control-codes.md new file mode 100644 index 0000000000..27421fd39f --- /dev/null +++ b/windows-driver-docs-pr/kernel/buffer-descriptions-for-i-o-control-codes.md @@ -0,0 +1,61 @@ +--- +title: Buffer Descriptions for I/O Control Codes +author: windows-driver-content +description: Buffer Descriptions for I/O Control Codes +ms.assetid: a458f3fb-a6c7-42ae-870e-1617a96b496f +keywords: ["I/O control codes WDK kernel , buffer descriptions", "control codes WDK IOCTLs , buffer descriptions", "IOCTLs WDK kernel , buffer descriptions", "buffer descriptions WDK IOCTLs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Buffer Descriptions for I/O Control Codes + + +## + + +I/O control codes are contained in [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests. The I/O manager creates these requests as a result of calls to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) (described in the Microsoft Windows SDK documentation) and [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318). + +Because [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) and **IoBuildDeviceIoControlRequest** accept both an input buffer and an output buffer as arguments, all **IRP\_MJ\_DEVICE\_CONTROL** and **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests supply both an input buffer and an output buffer. The way the system describes these buffers is dependent on the data transfer type. The transfer type is specified by the *TransferType* value in the [**CTL\_CODE**](defining-i-o-control-codes.md) macro that creates IOCTL code values. + +The system describes buffers for each *TransferType* value as follows: + +METHOD\_BUFFERED +For this transfer type, IRPs supply a pointer to a buffer at **Irp->AssociatedIrp.SystemBuffer**. This buffer represents both the input buffer and the output buffer that are specified in calls to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) and **IoBuildDeviceIoControlRequest**. The driver transfers data out of, and then into, this buffer. + +For input data, the buffer size is specified by **Parameters.DeviceIoControl.InputBufferLength** in the driver's [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure. For output data, the buffer size is specified by **Parameters.DeviceIoControl.OutputBufferLength** in the driver's **IO\_STACK\_LOCATION** structure. + +The size of the space that the system allocates for the single input/output buffer is the larger of the two length values. + +METHOD\_IN\_DIRECT or METHOD\_OUT\_DIRECT +For these transfer types, IRPs supply a pointer to a buffer at **Irp->AssociatedIrp.SystemBuffer**. This represents the input buffer that is specified in calls to **DeviceIoControl** and **IoBuildDeviceIoControlRequest**. The buffer size is specified by **Parameters.DeviceIoControl.InputBufferLength** in the driver's **IO\_STACK\_LOCATION** structure. + +For these transfer types, IRPs also supply a pointer to an MDL at **Irp->MdlAddress**. This represents the output buffer that is specified in calls to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) and **IoBuildDeviceIoControlRequest**. However, this buffer can actually be used as either an input buffer or an output buffer, as follows: + +- METHOD\_IN\_DIRECT is specified if the driver that handles the IRP receives data in the buffer when it is called. The MDL describes an input buffer, and specifying METHOD\_IN\_DIRECT ensures that the executing thread has read-access to the buffer. + +- METHOD\_OUT\_DIRECT is specified if the driver that handles the IRP will write data into the buffer before completing the IRP. The MDL describes an output buffer, and specifying METHOD\_OUT\_DIRECT ensures that the executing thread has write-access to the buffer. + +For both of these transfer types, **Parameters.DeviceIoControl.OutputBufferLength** specifies the size of the buffer that is described by the MDL. + +METHOD\_NEITHER +The I/O manager does not provide any system buffers or MDLs. The IRP supplies the user-mode virtual addresses of the input and output buffers that were specified to **DeviceIoControl** or **IoBuildDeviceIoControlRequest**, without validating or mapping them. + +The input buffer's address is supplied by **Parameters.DeviceIoControl.Type3InputBuffer** in the driver's **IO\_STACK\_LOCATION** structure, and the output buffer's address is specified by **Irp->UserBuffer**. + +Buffer sizes are supplied by **Parameters.DeviceIoControl.InputBufferLength** and **Parameters.DeviceIoControl.OutputBufferLength** in the driver's **IO\_STACK\_LOCATION** structure. + +For more information about the **CTL\_CODE** macro and the transfer types listed above, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Buffer%20Descriptions%20for%20I/O%20Control%20Codes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/building-and-deploying-the-localized-mof-file.md b/windows-driver-docs-pr/kernel/building-and-deploying-the-localized-mof-file.md new file mode 100644 index 0000000000..af0b269d0d --- /dev/null +++ b/windows-driver-docs-pr/kernel/building-and-deploying-the-localized-mof-file.md @@ -0,0 +1,103 @@ +--- +title: Building and Deploying the Localized MOF File +author: windows-driver-content +description: Building and Deploying the Localized MOF File +ms.assetid: 3a741dc6-a789-44e1-9d68-cdb41b7161ed +keywords: ["MOF files WDK WMI", "localizing MOF files", "MUI versions WDK WMI", "master MOF files WDK WMI", "languages WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Building and Deploying the Localized MOF File + + +## + + +International versions of Windows XP and later versions of the operating system come in two flavors — single-language (localized) versions, and Multilanguage User Interface (MUI) versions. An MUI version of Windows can support several languages simultaneously. + +Drivers that are deployed on a localized version of Windows should contain a MOF resource that contains the language-neutral version of all the classes, as well as the localized language amendment and the American English language amendment. + +On an MUI version of Windows, the driver image itself should contain the language-neutral and American English versions of the WMI classes. For each additional language supported, a resource-only image can be placed in the %windir%\\system32\\drivers\\MUI\\*langid* directory, where *langid* is the LCID of the for the locale. + +Optionally, the driver image itself can contain every language supported. + +If a language is not supported by one of these mechanisms, the English language version is used. + +### Building Distinct MOF Files For Each Language + +Driver writers can use one master MOF text file to contain the basic class, and all of its amendments. + +You can use the [MOF compiler](compiling-a-driver-s-mof-file.md) to generate a file containing the language-neutral classes as well as a file to contain the amended classes for a particular language. + +``` +mofcomp -amendment:namespace [ -MOF:mof] [ -MFL:mfl] masterfile +``` + +The *namespace* parameter is of the form MS\_*XXX*, where *XXX* is the LCID for the locale to be generated. The mof file created contains the language-neutral classes, and the mfl file created contains the amended classes. + +When building your driver on NT-based operating systems, you can merge the two files by using the copy command. On Windows 98/Me, the copy command does not correctly append Unicode files, but the following command can be used. + +``` +wmimofck localizedfile -ymof -zmfl +``` + +You can combine any number of languages into a single text file. + +The localized file can then be compiled into a binary file by the same method as for the MOF files that have not been localized: + +``` +mofcomp -B:binaryfile localizedfile +``` + +For a single-language version of Windows, drivers attach the binary MOF as a resource to the driver image. See [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md) for details. + +On an MUI system, the driver image itself must be built for American English. For each additional language, install each localized binary MOF file as a resource in a separate image file in the appropriate %windir%\\system32\\drivers\\MUI\\*langid* directory, where *langid* is the hexadecimal LCID for the locale (for example, 409 for American English). The file name must be either *drivername.sys* or *drivername.sys*.mui, where *drivername.sys* is the name of the driver binary. + +### Building One MOF File for All Supported Languages + +If the driver image will contain every supported language, there is a simpler way to build a MOF file supporting every language. By using **\#pragma** directives in the MOF text file, drivers can also combine all of the amended classes in one binary. Since each localization exists in a distinct namespace, they can safely be combined in a single binary. + +When writing the combined MOF text file, driver writers must precede each amended class declaration with a **\#pragma** directive as follows + +``` +#pragma namespace ("namespace") +``` + +where `namespace` is the correct namespace for the declaration. For example, the amended class declaration for American English must be preceded with a declaration of the form: + +``` +#pragma namespace ("\\\\.\\root\\wmi\\ms_409") +``` + +For example, you declare a class and its amendments as follows. + +``` +#pragma namespace ("\\\\.\\root\\wmi) + +[guid(xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx)] +class MyClass +{ +} + +#pragma namespace(\\\\.\\root\\wmi\\ms_409) +[amendment, locale(0x407)] +class MyClass +{ +} +``` + +Using this approach, building the binary MOF file is identical to the nonlocalized approach. See [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Building%20and%20Deploying%20the%20Localized%20MOF%20File%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/bus-drivers.md b/windows-driver-docs-pr/kernel/bus-drivers.md new file mode 100644 index 0000000000..579441577b --- /dev/null +++ b/windows-driver-docs-pr/kernel/bus-drivers.md @@ -0,0 +1,52 @@ +--- +title: Bus Drivers +author: windows-driver-content +description: Bus Drivers +ms.assetid: d1a92c06-882d-49dc-befa-5b9a9e8aecd7 +keywords: ["bus drivers WDK WDM", "enumerating bus devices WDK WDM", "bus controllers WDK WDM", "adapters WDK WDM", "bridges WDK WDM", "WDM bus drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Bus Drivers + + +## + + +A *bus driver* services a bus controller, adapter, or bridge (see the [Possible Driver Layers](types-of-wdm-drivers.md#possible-driver-layers) figure). Microsoft provides bus drivers for most common buses, such as PCI, PnpISA, SCSI, and USB. Other bus drivers can be provided by IHVs or OEMs. Bus drivers are required drivers; there is one bus driver for each type of bus on a machine. A bus driver can service more than one bus if there is more than one bus of the same type on the machine. + +The primary responsibilities of a bus driver are to: + +- Enumerate the devices on its bus. + +- Respond to Plug and Play IRPs and power management IRPs. + +- Multiplex access to the bus (for some buses). + +- Generically administer the devices on its bus. + +Bus drivers are essentially [function drivers](function-drivers.md) that also enumerate children. + +During enumeration, a bus driver identifies the devices on its bus and creates device objects for them. (For information about device objects, see [Device Objects and Device Stacks](device-objects-and-device-stacks.md).) The method a bus driver uses to identify connected devices depends on the particular bus. + +A bus driver performs certain operations on behalf of the devices on its bus, including accessing device registers to physically change the power state of a device. For example, when the device goes to sleep, the bus driver sets device registers to put the device in the proper device power state. + +Note, however, that a bus driver does not handle read and write requests for the child devices that are connect to its bus. Read and write requests to a child device are handled by the child device's [function driver](function-drivers.md). Only if the child device is being used in [*raw mode*](https://msdn.microsoft.com/library/windows/hardware/ff556331#wdkgloss-raw-mode) does the parent bus driver handle reads and writes for the device. + +Because a bus driver acts as the function driver for its controller, adapter, or bridge, it also manages device power policy for these components. + +A bus driver can be implemented as a driver/minidriver pair, the way a SCSI port/miniport driver pair drives a SCSI host bus adapter (HBA). In such driver pairs, the minidriver is linked to the second driver, which is a DLL. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Bus%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/callback-objects.md b/windows-driver-docs-pr/kernel/callback-objects.md new file mode 100644 index 0000000000..c56a6771eb --- /dev/null +++ b/windows-driver-docs-pr/kernel/callback-objects.md @@ -0,0 +1,44 @@ +--- +title: Callback Objects +author: windows-driver-content +description: Callback Objects +ms.assetid: d6ccb064-5936-4996-a5cd-795803958b5d +keywords: ["synchronization WDK kernel , callback objects", "callback objects WDK kernel", "objects WDK callback objects", "kernel callback mechanism WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Callback Objects + + +## + + +The kernel's callback mechanism provides a general way for drivers to request and provide notification when certain conditions are satisfied. + +A driver can create a callback object, and other drivers can request notification for conditions associated with this driver-defined callback. In addition, the system defines two callback objects for driver use. + +Every callback object has a name and a set of attributes, defined when the object is created. The system-defined callback objects are named **\\Callback\\SetSystemTime**, **\\Callback\\PowerState**, and **\\Callback\\ProcessorAdd**; driver-defined callbacks must not duplicate these names. + +To request notification from a system- or driver-defined callback, a driver opens the callback object and registers a callback routine. When the conditions defined for the callback become true, its creator triggers notification. In turn, the system calls all the callback routines registered for the callback. + +This section contains the following topics: + +[Defining a Callback Object](defining-a-callback-object.md) + +[Using a Driver-Defined Callback Object](using-a-driver-defined-callback-object.md) + +[Using a System-Defined Callback Object](using-a-system-defined-callback-object.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Callback%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-exsettimerresolution-while-processing-a-power-irp.md b/windows-driver-docs-pr/kernel/calling-exsettimerresolution-while-processing-a-power-irp.md new file mode 100644 index 0000000000..06e4817e20 --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-exsettimerresolution-while-processing-a-power-irp.md @@ -0,0 +1,21 @@ +--- +title: Calling ExSetTimerResolution While Processing a Power IRP +author: windows-driver-content +description: Calling ExSetTimerResolution While Processing a Power IRP +ms.assetid: 999a76ab-1586-4157-bfa7-8cc5dd517c71 +--- + +# Calling ExSetTimerResolution While Processing a Power IRP + + +During the processing of an [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) request, the power manager holds a lock on a resource that [**ExSetTimerResolution**](https://msdn.microsoft.com/library/windows/hardware/ff545614) must acquire to complete. Consequently, a deadlock will occur if a driver directly or indirectly calls this routine while processing a power request, and then waits for the call to the routine to return before the driver completes the power request. While processing a power request, a driver can safely call **ExSetTimerResolution** only if the driver does not wait for the call to this routine to return before completing the power request. For example, a driver can create a worker thread that calls **ExSetTimerResolution**, as long as the driver then completes the power request without waiting for the call to this routine to return. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20ExSetTimerResolution%20While%20Processing%20a%20Power%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-iocalldriver-versus-calling-pocalldriver.md b/windows-driver-docs-pr/kernel/calling-iocalldriver-versus-calling-pocalldriver.md new file mode 100644 index 0000000000..19f54a6bcf --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-iocalldriver-versus-calling-pocalldriver.md @@ -0,0 +1,44 @@ +--- +title: Calling IoCallDriver versus Calling PoCallDriver +author: windows-driver-content +description: Calling IoCallDriver versus Calling PoCallDriver +ms.assetid: a47e2310-e89b-4552-bbe3-d4984ae8b564 +keywords: ["PoCallDriver", "active power IRPs WDK kernel", "power IRPs WDK kernel , IoCallDriver versus PoCallDriver"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling IoCallDriver versus Calling PoCallDriver + + +## + + +Beginning with Windows Vista, a driver should call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) instead of [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654), to pass power IRPs to the next-lower driver. In Windows Server 2003, Windows XP, and Windows 2000, a driver must call **PoCallDriver**, not **IoCallDriver**, to pass power IRPs to the next-lower driver. Note, however, that drivers that use the same code to run both in Windows Vista and in earlier Windows versions, must call **PoCallDriver**, not **IoCallDriver**. + +Beginning with Windows Vista, [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) and **IoCallDriver** ensure that the power manager properly synchronizes power IRPs throughout the system. In Windows Server 2003, Windows XP, and Windows 2000, **PoRequestPowerIrp**, **PoCallDriver**, and [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), ensure that the power manager properly synchronizes power IRPs throughout the system. + +The system limits the number of active power IRPs as follows: + +- No more than one system power IRP ([**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744), [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699)) can be active for each physical device object ([PDO](https://msdn.microsoft.com/library/windows/hardware/ff556325#wdkgloss-pdo)) at any given time. + +- No more than one device set-power IRP (**IRP\_MN\_SET\_POWER)** can be active for each PDO at any given time. + +- No more than one device power IRP that requires an inrush of power can be active anywhere in the system at any given time. + +To ensure that two inrush devices do not attempt to power up simultaneously, the power manager keeps track of active inrush power IRPs across the whole system and allows only one to be active at a time. An additional inrush IRP cannot start until the active inrush IRP has completed. + +Because of these restrictions on inrush IRPs, a device power IRP might block while an inrush IRP for another device completes. Driver writers should be aware of this behavior while debugging. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20IoCallDriver%20versus%20Calling%20PoCallDriver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-bus-driver.md b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-bus-driver.md new file mode 100644 index 0000000000..6e0bb6eb3d --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-bus-driver.md @@ -0,0 +1,32 @@ +--- +title: Calling PoStartNextPowerIrp from a Bus Driver +author: windows-driver-content +description: Calling PoStartNextPowerIrp from a Bus Driver +ms.assetid: 4e23ebe1-c939-48e1-82bf-cdb4980a5a7b +keywords: ["bus drivers WDK power management", "power IRPs WDK kernel , PoStartNextPowerIrp", "PoStartNextPowerIrp"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling PoStartNextPowerIrp from a Bus Driver + + +## + + +Beginning with Windows Vista, calling [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) is not required and call to this routine performs no power management operation. However, in Windows Server 2003, Windows XP, and Windows 2000, a bus driver must call **PoStartNextPowerIrp** once for every [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) or [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request that the driver receives. + +A bus driver always calls this routine in its *DispatchPower* routine, before it calls the [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20PoStartNextPowerIrp%20from%20a%20Bus%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-device-power-policy-owner.md b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-device-power-policy-owner.md new file mode 100644 index 0000000000..e4315d2cc5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-device-power-policy-owner.md @@ -0,0 +1,69 @@ +--- +title: Calling PoStartNextPowerIrp from a Device Power Policy Owner +author: windows-driver-content +description: Calling PoStartNextPowerIrp from a Device Power Policy Owner +ms.assetid: 58576ff8-638e-4928-9a2d-337ac3f4d2d8 +keywords: ["power IRPs WDK kernel , PoStartNextPowerIrp", "PoStartNextPowerIrp", "device power policy WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling PoStartNextPowerIrp from a Device Power Policy Owner + + +## + + +Beginning with Windows Vista, calling [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) is not required and call to this routine performs no power management operation. However, in Windows Server 2003, Windows XP, and Windows 2000, a function driver that owns device power policy must call **PoStartNextPowerIrp** once for every [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) or [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request that the driver receives. When the call occurs depends on the type of request and whether the driver will fail or succeed the request, as the following table shows. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type of requestIf driver succeeds the request, the call occurs:If driver fails the request, the call occurs:

IRP_MN_QUERY_POWER (device power state)

In an [IoCompletion](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, immediately before returning.

In [DispatchPower](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine, before calling [IoCompleteRequest](https://msdn.microsoft.com/library/windows/hardware/ff548343).

IRP_MN_QUERY_POWER (system power state)

In the [PoRequestPowerIrp](https://msdn.microsoft.com/library/windows/hardware/ff559734) callback routine for the related device IRP, immediately before completing the system IRP.

In DispatchPower routine, before calling IoCompleteRequest.

IRP_MN_SET_POWER (device power state)

In an IoCompletion routine, immediately before returning.

Not allowed.

IRP_MN_SET_POWER (system power state)

In the PoRequestPowerIrp callback routine for the related device IRP, immediately before completing the system IRP.

Not allowed.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20PoStartNextPowerIrp%20from%20a%20Device%20Power%20Policy%20Owner%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-filter-driver.md b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-filter-driver.md new file mode 100644 index 0000000000..90a52892ef --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp-from-a-filter-driver.md @@ -0,0 +1,66 @@ +--- +title: Calling PoStartNextPowerIrp from a Filter Driver +author: windows-driver-content +description: Calling PoStartNextPowerIrp from a Filter Driver +ms.assetid: 6005f107-8f90-4530-91c2-9f0947cacb0a +keywords: ["power IRPs WDK kernel , PoStartNextPowerIrp", "PoStartNextPowerIrp", "filter drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling PoStartNextPowerIrp from a Filter Driver + + +Beginning with Windows Vista, calling [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) is not required and call to this routine performs no power management operation. However, in Windows Server 2003, Windows XP, and Windows 2000, a filter driver must call **PoStartNextPowerIrp** once for every [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) or [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request that the driver receives. When the call occurs depends on the type of request and whether the driver will fail or succeed the request, as the following table shows. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type of requestIf driver succeeds the request, the call occurs:If driver fails the request, the call occurs:

IRP_MN_QUERY_POWER (device power state)

In an [IoCompletion](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, immediately before returning.

In [DispatchPower](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine, before calling IoCompleteRequest.

IRP_MN_QUERY_POWER (system power state)

In DispatchPower routine, after acquiring remove lock and before setting IRP stack location.

In DispatchPower routine, before calling [IoCompleteRequest](https://msdn.microsoft.com/library/windows/hardware/ff548343).

IRP_MN_SET_POWER (device power state)

In an IoCompletion routine, immediately before returning.

Not allowed.

IRP_MN_SET_POWER (system power state)

In DispatchPower routine, after acquiring remove lock and before setting IRP stack location.

Not allowed.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20PoStartNextPowerIrp%20from%20a%20Filter%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-postartnextpowerirp.md b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp.md new file mode 100644 index 0000000000..7283f72018 --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-postartnextpowerirp.md @@ -0,0 +1,44 @@ +--- +title: Calling PoStartNextPowerIrp +author: windows-driver-content +description: Calling PoStartNextPowerIrp +ms.assetid: 8b3fb578-2ac2-4a04-ac99-1cfd51b07b01 +keywords: ["power IRPs WDK kernel , PoStartNextPowerIrp", "PoStartNextPowerIrp"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling PoStartNextPowerIrp + + +## + + +Beginning with Windows Vista, calling [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) is not required and a call to this routine performs no power management operation. However, in Windows Server 2003, Windows XP, and Windows 2000, after a driver processes a query-power IRP or a set-power IRP, the driver must call **PoStartNextPowerIrp** to notify the power manager that it is ready to receive another power IRP. Drivers must call **PoStartNextPowerIrp** while the IRP stack location points to the current driver and before calling [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654). + +A driver must call this routine once for each [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) or [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request that it receives. Drivers do not need to call **PoStartNextPowerIrp** when handling [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) or [**IRP\_MN\_POWER\_SEQUENCE**](https://msdn.microsoft.com/library/windows/hardware/ff551644) requests. + +When a driver calls **PoStartNextPowerIrp**, the current IRP stack location must point to the current driver. As a general rule, this call is best made from an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. **PoStartNextPowerIrp** must be called before [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355), and **PoCallDriver**. Calling the routines in the other order might cause a system deadlock. + +Even if a driver fails the IRP, it must nevertheless call **PoStartNextPowerIrp** to inform the power manager that it is ready to handle another power IRP. + +The following sections clarify when each type of driver should call this routine: + +[Calling PoStartNextPowerIrp from a Filter Driver](calling-postartnextpowerirp-from-a-filter-driver.md) + +[Calling PoStartNextPowerIrp from a Device Power Policy Owner](calling-postartnextpowerirp-from-a-device-power-policy-owner.md) + +[Calling PoStartNextPowerIrp from a Bus Driver](calling-postartnextpowerirp-from-a-bus-driver.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20PoStartNextPowerIrp%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-support-routines-that-use-spin-locks.md b/windows-driver-docs-pr/kernel/calling-support-routines-that-use-spin-locks.md new file mode 100644 index 0000000000..e46fa3dc04 --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-support-routines-that-use-spin-locks.md @@ -0,0 +1,38 @@ +--- +title: Calling Support Routines That Use Spin Locks +author: windows-driver-content +description: Calling Support Routines That Use Spin Locks +ms.assetid: 89cf1fd4-4f4b-4b82-9e50-e5766918c421 +keywords: ["KeAcquireSpinLock", "KeAcquireInStackQueuedSpinLock", "spin locks WDK kernel", "calling spin lock support routines WDK kernel", "executive spin locks WDK kernel", "interrupt spin locks WDK kernel", "queued spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling Support Routines That Use Spin Locks + + +## + + +Calling [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) or [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) sets the IRQL on the current processor to DISPATCH\_LEVEL until a corresponding call to [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145) or [**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) restores the previous IRQL. Consequently, drivers must be executing at IRQL <= DISPATCH\_LEVEL when they call **KeAcquireSpinLock** or **KeAcquireInStackQueuedSpinLock**. + +Callers of [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921), [**KeAcquireInStackQueuedSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551908), [**KeReleaseInStackQueuedSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553137), and [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150) run faster because they are already running at IRQL = DISPATCH\_LEVEL so these support routines need not reset IRQL on the current processor. Consequently, it is a fatal error on most Windows platforms to call **KeAcquireSpinLockAtDpcLevel** or **KeAcquireInStackQueuedSpinLockAtDpcLevel** while running at IRQL less than DISPATCH\_LEVEL. It is also an error to release a spin lock that was acquired with **KeAcquireSpinLock** by calling **KeReleaseSpinLockFromDpcLevel** because the caller's original IRQL is not restored. + +Routines that hold an executive spin lock, such as the **ExInterlocked*Xxx***, usually execute at IRQL = DISPATCH\_LEVEL until they release the spin lock and return control to the caller. However, it is possible for a driver's [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine and [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines (which run at DIRQL) to call certain **ExInterlocked*Xxx*** routines, such as the **ExInterlocked*Xxx*List** routines, as long as the spin lock passed to the routine is used exclusively by the ISR and *SynchCritSection* routines. + +Each routine that holds an interrupt spin lock executes at the DIRQL of an associated set of interrupt objects. Therefore, a driver must not call **KeAcquireSpinLock** and **KeReleaseSpinLock** nor any other routine that uses an executive spin lock from its ISR or *SynchCritSection* routines. Such a call is an error that can cause a system deadlock, requiring the user to reboot his or her machine. Note that if a driver's ISR or *SynchCritSection* routine calls an **ExInterlocked*Xxx*List** routine, the driver cannot reuse the spin lock it passes to the **ExInterlocked*Xxx*List** routines in calls to the **Ke*Xxx*SpinLock** or **Ke*Xxx*SpinLock*Xxx*DpcLevel** support routines. + +If a driver has a multivector ISR or more than one ISR, its routines can call [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) while executing at any IRQL up to the *SynchronizeIrql* value specified for the associated interrupt objects when they were connected. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20Support%20Routines%20That%20Use%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/calling-wmisystemcontrol-to-handle-wmi-irps.md b/windows-driver-docs-pr/kernel/calling-wmisystemcontrol-to-handle-wmi-irps.md new file mode 100644 index 0000000000..480c0543a8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/calling-wmisystemcontrol-to-handle-wmi-irps.md @@ -0,0 +1,62 @@ +--- +title: Calling WmiSystemControl to Handle WMI IRPs +author: windows-driver-content +description: Calling WmiSystemControl to Handle WMI IRPs +ms.assetid: a2fa53e2-6468-4c3c-8b41-9a97305abc43 +keywords: ["WMI WDK kernel , requests", "requests WDK WMI", "IRPs WDK WMI", "WmiSystemControl"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Calling WmiSystemControl to Handle WMI IRPs + + +## + + +WMI library routines simplify handling of WMI requests because instead of processing each such request, a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834). In the **WmiSystemControl** call, the driver passes an initialized [**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) structure that contains entry points to the driver's [WMI library callback routines](https://msdn.microsoft.com/library/windows/hardware/ff566357) (*DpWmiXxx* routines) and information about the driver's data blocks and event blocks. + +Because the WMI library provides no mechanism for passing dynamic instance names or a static instance name list, a driver can use the WMI library to handle requests involving only data blocks with static instance names based on a PDO or a single base name string. For more information about static and dynamic instance names, see [Defining WMI Instance Names](defining-wmi-instance-names.md). Nothing prevents a driver from using the WMI library to handle requests for such blocks and processing requests for other blocks in its [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine. For more information, see [Processing WMI IRPs in a DispatchSystemControl Routine](processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md). + +To handle WMI IRPs by calling **WmiSystemControl**, a driver must implement certain required *DpWmiXxx* callback routines, and might implement additional optional *DpWmiXxx* callback routines: + +- [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097)—(Required) Provides information about the data and event blocks being registered by the driver. WMI calls a driver's *DpWmiQueryReginfo* routine to process an [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request. For more information, see [Using the WMI Library to Register Blocks](using-the-wmi-library-to-register-blocks.md). + +- [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096)—(Required) Returns either a single instance or all instances of a data block. WMI calls a driver's *DpWmiQueryDataBlock* routine to process an [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) or [**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) request. + +- [*DpWmiSetDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544104)—(Optional) Changes all data items in a single instance of a data block. WMI calls a driver's *DpWmiSetDataBlock* routine to process an [**IRP\_MN\_CHANGE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff550831) request. + +- [*DpWmiSetDataItem*](https://msdn.microsoft.com/library/windows/hardware/ff544108)—(Optional) Changes a single data item in an instance of a data block. WMI calls a driver's *DpWmiSetDataItem* routine to process an [**IRP\_MN\_CHANGE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff550836) request. + +- [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094)—(Optional) Enables and disables event notification and data collection for blocks registered as expensive to collect. WMI calls a driver's *DpWmiFunctionControl* routine to process an [**IRP\_MN\_ENABLE\_COLLECTION**](https://msdn.microsoft.com/library/windows/hardware/ff550857), [**IRP\_MN\_DISABLE\_COLLECTION**](https://msdn.microsoft.com/library/windows/hardware/ff550848), [**IRP\_MN\_ENABLE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550859), or [**IRP\_MN\_DISABLE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550851) request. + +- [*DpWmiExecuteMethod*](https://msdn.microsoft.com/library/windows/hardware/ff544090)—(Optional) Executes a method associated with a data block. WMI calls a driver's *DpWmiExecuteMethod* routine to process an [**IRP\_MN\_EXECUTE\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/ff550868) request. + +A driver's *DpWmiXxx* routines can have any names chosen by the driver writer. + +Before calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), the driver must initialize a [**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) structure with entry points to its *DpWmiXxx* routines and information about its data blocks and event blocks. + +When the driver receives a WMI request: + +1. The driver calls **WmiSystemControl** with a pointer to its initialized **WMILIB\_CONTEXT** structure, a pointer to its device object, and a pointer to the IRP. + +2. WMI validates the IRP parameters and calls the driver's *DpWmiXxx* routine that processes the request. If the driver set no entry point in its **WMILIB\_CONTEXT** for an optional *DpWmiXxx* routine, WMI completes the IRP with default values and status. + +3. In its *DpWmiXxx* routine, the driver processes the request and writes any output to the caller-supplied buffer. For example, a driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine would write the requested instance(s) of the specified block to the buffer. + +4. In all *DpWmiXxx* routines except [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097), the driver calls [**WmiCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff565798) to complete the request, or returns STATUS\_PENDING to postpone completion, as for any IRP. + +5. WMI performs any necessary postprocessing, packages any output in an appropriate **WNODE\_*XXX*** structure, and passes the output and status to the data consumer. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Calling%20WmiSystemControl%20to%20Handle%20WMI%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-with-startio-routines.md b/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-with-startio-routines.md new file mode 100644 index 0000000000..d38ef44e52 --- /dev/null +++ b/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-with-startio-routines.md @@ -0,0 +1,45 @@ +--- +title: Cancel Routines in Drivers with StartIo Routines +author: windows-driver-content +description: Cancel Routines in Drivers with StartIo Routines +ms.assetid: 5098e4b9-d4db-44c2-acb3-a46878d6f1c4 +keywords: ["canceling IRPs, StartIo routines", "Cancel routines, StartIo routines", "StartIo routines, Cancel routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Cancel Routines in Drivers with StartIo Routines + + +## + + +The I/O manager maintains the **CurrentIrp** field in a device object only if IRPs are queued in the associated device queue object. That is, the field is valid only if the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. + +In a driver that has a *StartIo* routine, a typical [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine must do the following: + +1. Check whether the pointer for the input IRP matches the target device object's **CurrentIrp** address. + + If these pointers are equivalent, the *Cancel* routine calls [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550), passing **Irp->CancelIrql**, and returns control. + +2. If the canceled IRP is not the current IRP, check whether the input canceled IRP is in the device queue associated with the target device object by calling [**KeRemoveEntryDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553163) with the IRP's **Tail.Overlay.DeviceQueueEntry** pointer. + - If the IRP is in the device queue, calling **KeRemoveEntryDeviceQueue** removes it from the queue. The *Cancel* routine calls [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550), sets the IRP's I/O status block with STATUS\_CANCELLED for **Status** and zero for **Information**, calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the canceled IRP, and returns control. + + - If the IRP is not in the device queue, the *Cancel* routine calls **IoReleaseCancelSpinLock** and returns control. + +The driver's *Cancel* routine should call **KeRemoveEntryDeviceQueue** to test whether the IRP is in the device queue. This support routine either removes the given IRP from the device queue or does nothing except return **FALSE**, indicating that the given entry was not queued. A *Cancel* routine cannot assume that the input IRP is at any particular position in the device queue, so it cannot call [**KeRemoveDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553156) or [**KeRemoveByKeyDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553152) to compare the pointers to the returned IRP and input IRP. + +Drivers with *Cancel* routines can handle [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718) requests as well. See [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) for more information about **IRP\_MJ\_CLEANUP** requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Cancel%20Routines%20in%20Drivers%20with%20StartIo%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-without-startio-routines.md b/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-without-startio-routines.md new file mode 100644 index 0000000000..2b5b082532 --- /dev/null +++ b/windows-driver-docs-pr/kernel/cancel-routines-in-drivers-without-startio-routines.md @@ -0,0 +1,48 @@ +--- +title: Cancel Routines in Drivers without StartIo Routines +author: windows-driver-content +description: Cancel Routines in Drivers without StartIo Routines +ms.assetid: c6e1a05e-28ed-4f42-8678-55f01303b312 +keywords: ["canceling IRPs, StartIo routines", "Cancel routines, StartIo routines", "StartIo routines, Cancel routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Cancel Routines in Drivers without StartIo Routines + + +## + + +The I/O manager maintains the **CurrentIrp** field in a device object only if IRPs are queued in the associated device queue object. + +Drivers that do not have [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routines manage their own internal queues of IRPs. In such a driver, a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine can be called with an input IRP that is neither the **CurrentIrp** for the input target device object, nor an IRP in the driver's internal queue. The driver must maintain its own state about which IRP is currently being processed and should have a *Cancel* routine for each of its queues. The driver's internal queue should be an interlocked queue because its internal queue must be protected by an executive spin lock. + +When the driver's *Cancel* routine is called, it typically does the following: + +1. Calls [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550), passing **Irp->CancelIrql**. + +2. Acquires the spin lock that protects its interlocked queue and walks the queue to find an IRP with **Irp->Cancel** set to **TRUE**. + + - If it finds such an IRP in the interlocked queue, dequeues it, releases the spin lock protecting the queue, sets the IRP's I/O status block with w + + STATUS\_CANCELLED for **Status** and zero for **Information**, starts the next queued IRP, calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the canceled IRP, and returns control + + - If it does not find such an IRP, the *Cancel* routine releases any spin locks it is holding and returns control. + + The driver usually assumes that I/O processing for the input IRP has already begun if the IRP is not queued. + +Drivers with *Cancel* routines can handle [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718) requests as well. See [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) for more information about **IRP\_MJ\_CLEANUP** requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Cancel%20Routines%20in%20Drivers%20without%20StartIo%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/cancel-safe-irp-queues.md b/windows-driver-docs-pr/kernel/cancel-safe-irp-queues.md new file mode 100644 index 0000000000..c700eb3e06 --- /dev/null +++ b/windows-driver-docs-pr/kernel/cancel-safe-irp-queues.md @@ -0,0 +1,171 @@ +--- +title: Cancel-Safe IRP Queues +author: windows-driver-content +description: Cancel-Safe IRP Queues +ms.assetid: a759d1e0-120f-4db9-9b84-ff921f2f5ba4 +keywords: ["cancel-safe IRP queues WDK kernel", "callback routines WDK IRPs", "synchronization WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Cancel-Safe IRP Queues + + +## + + +Drivers that implement their own IRP queuing should use the *cancel-safe IRP queue* framework. Cancel-safe IRP queues split IRP handling into two parts: + +1. The driver provides a set of callback routines that implement standard operations on the driver's IRP queue. The provided operations include inserting and removing IRPs from the queue, and locking and unlocking the queue. See [Implementing the Cancel-Safe IRP Queue](#ddk-implementing-the-cancel-safe-irp-queue-kg). + +2. Whenever the driver needs to actually insert or remove an IRP from the queue, it uses the system-provided **IoCsq*Xxx*** routines. These routines handle all synchronization and IRP canceling logic for the driver. + +Drivers that use cancel-safe IRP queues do not implement [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routines to support IRP cancellation. + +The framework ensures that drivers insert and remove IRPs from their queue atomically. It also ensures that IRP cancellation is implemented correctly. Drivers that do not use the framework must manually lock and unlock the queue before performing any insertions and deletions. They must also avoid the race conditions that can result when implementing a *Cancel* routine. (For a description of the race conditions that can arise, see [Synchronizing IRP Cancellation](synchronizing-irp-cancellation.md).) + +The cancel-safe IRP queue framework is included with Windows XP and later versions of Windows. Drivers that must also work with Windows 2000 and Windows 98/Me can link to the Csq.lib library that is included in the Windows Driver Kit (WDK). The Csq.lib library provides an implementation of this framework. + +The **IoCsq*Xxx*** routines are declared in the Windows XP and later versions of Wdm.h and Ntddk.h. Drivers that must also work with Windows 2000 and Windows 98/Me must include Csq.h for the declarations. + +You can see a complete demonstration of how to use cancel-safe IRP queues in the \\src\\general\\cancel directory of the WDK. For more information about these queues, also see the [Flow of Control for Cancel-Safe IRP Queuing](http://go.microsoft.com/fwlink/p/?linkid=57844) white paper on the Windows Hardware Developer Central (WHDC) website. + +### Implementing the Cancel-Safe IRP Queue + +To implement a cancel-safe IRP queue, drivers must provide the following routines: + +- Either of the following routines to insert IRPs into the queue: [*CsqInsertIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542947) or [*CsqInsertIrpEx*](https://msdn.microsoft.com/library/windows/hardware/ff542956). *CsqInsertIrpEx* is an extended version of *CsqInsertIrp*; the queue is implemented using one or the other. + +- A [*CsqRemoveIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542968) routine that removes the specified IRP from the queue. + +- A [*CsqPeekNextIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542959) routine that returns a pointer to the next IRP following the specified IRP in the queue. This is where the system passes the *PeekContext* value that it receives from [**IoCsqRemoveNextIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549072). The driver can interpret that value in any way. + +- Both of the following routines to allow the system to lock and unlock the IRP queue: [*CsqAcquireLock*](https://msdn.microsoft.com/library/windows/hardware/ff542934) and [*CsqReleaseLock*](https://msdn.microsoft.com/library/windows/hardware/ff542965). + +- A [*CsqCompleteCanceledIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542940) routine that completes a canceled IRP. + +Pointers to the driver's routines are stored in the [**IO\_CSQ**](https://msdn.microsoft.com/library/windows/hardware/ff550560) structure that describes the queue. The driver allocates the storage for the **IO\_CSQ** structure. The **IO\_CSQ** structure is guaranteed to remain a fixed size, so a driver can safely embed the structure inside its device extension. + +The driver uses either [**IoCsqInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff549054) or [**IoCsqInitializeEx**](https://msdn.microsoft.com/library/windows/hardware/ff549060) to initialize the structure. Use **IoCsqInitialize** if the queue implements [*CsqInsertIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542947), or **IoCsqInitializeEx** if the queue implements *CsqInsertIrpEx*. + +Drivers need only provide the essential functionality in each callback routine. For example, only the *CsqAcquireLock* and *CsqReleaseLock* routines implement lock handling. The system automatically calls these routines to lock and unlock the queue as necessary. + +You can implement any type of IRP queuing mechanism in your driver, as long as the appropriate dispatch routines are provided. For example, the driver could implement the queue as a linked list, or as a priority queue. + +[*CsqInsertIrpEx*](https://msdn.microsoft.com/library/windows/hardware/ff542956) provides a more flexible interface to the queue than does [*CsqInsertIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542947). The driver can use its return value to indicate the result of the operation; if it returns an error code, the insertion failed. A *CsqInsertIrp* routine does not return a value, so there is no simple way to indicate that an insertion failed. Also, *CsqInsertIrpEx* takes an additional driver-defined *InsertContext* parameter that can be used to specify additional driver-specific information to be used by the queue implementation. + +Drivers can use *CsqInsertIrpEx* to implement more sophisticated IRP handling. For example, if there are no pending IRPs, the *CsqInsertIrpEx* routine can return an error code and the driver can process the IRP immediately. Similarly, if IRPs can no longer be queued, the *CsqInsertIrpEx* can return an error code to indicate that fact. + +The driver is insulated from all IRP cancellation handling. The system provides a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for IRPs in the queue. This routine calls [*CsqRemoveIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542968) to remove the IRP from the queue, and [*CsqCompleteCanceledIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542940) to complete the IRP cancellation. + +The following diagram illustrates the flow of control for IRP cancellation. + +![diagram illustrating the flow of control for irp cancellation](images/5cancelingirp.png) + +A basic implementation of [*CsqCompleteCanceledIrp*](https://msdn.microsoft.com/library/windows/hardware/ff542940) is as follows. + +``` +VOID CsqCompleteCanceledIrp(PIO_CSQ Csq, PIRP Irp) { + Irp->IoStatus.Status = STATUS_CANCELLED; + Irp->IoStatus.Information = 0; + + IoCompleteRequest(Irp, IO_NO_INCREMENT); +} +``` + +Drivers can use any of the operating system's synchronization primitives to implement their [*CsqAcquireLock*](https://msdn.microsoft.com/library/windows/hardware/ff542934) and [*CsqReleaseLock*](https://msdn.microsoft.com/library/windows/hardware/ff542965) routines. Available synchronization primitives include [spin locks](spin-locks.md) and [mutex objects](mutex-objects.md). + +Here is an example of how a driver can implement locking using spin locks. + +``` +/* + The driver has previously initialized the SpinLock variable with + KeInitializeSpinLock. + */ + +VOID CsqAcquireLock(PIO_CSQ IoCsq, PKIRQL PIrql) +{ + KeAcquireSpinLock(SpinLock, PIrql); +} + +VOID CsqReleaseLock(PIO_CSQ IoCsq, KIRQL Irql) +{ + KeReleaseSpinLock(SpinLock, Irql); +} +``` + +The system passes a pointer to an IRQL variable to *CsqAcquireLock* and *CsqReleaseLock*. If the driver uses a spin lock to implement locking for the queue, the driver can use this variable to store the current IRQL when the queue is locked. + +Drivers are not required to use spin locks. For example, the driver could use a mutex to lock the queue. For a description of the synchronization techniques that are available to drivers, see [Synchronization Techniques](synchronization-techniques.md). + +### Using the Cancel-Safe IRP Queue + +Drivers use the following system routines when queuing and dequeuing IRPs: + +- Either of the following to insert an IRP into the queue: [**IoCsqInsertIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549066) or [**IoCsqInsertIrpEx**](https://msdn.microsoft.com/library/windows/hardware/ff549067). + +- [**IoCsqRemoveNextIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549072) to remove the next IRP in the queue. The driver can optionally specify a key value. + +The following diagram illustrates the flow of control for [**IoCsqRemoveNextIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549072). + +![diagram illustrating the flow of control for iocsqremovenextirp](images/4iocsqremovenextirp.png) + +- [**IoCsqRemoveIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549070) to remove the specified IRP from the queue. + +The following diagram illustrates the flow of control for [**IoCsqRemoveIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549070). + +![diagram illustrating the flow of control for iocsqremoveirp](images/3iocsqremoveirp.png) + +These routines, in turn, dispatch to driver-supplied routines. + +The [**IoCsqInsertIrpEx**](https://msdn.microsoft.com/library/windows/hardware/ff549067) routine provides access to the extended features of a *CsqInsertIrpEx* routine. It returns the status value that was returned by *CsqInsertIrpEx*. The caller can use this value to determine if the IRP was successfully queued or not. **IoCsqInsertIrpEx** also allows the caller to specify a value for the InsertContext parameter of *CsqInsertIrpEx*. + +Note that both **IoCsqInsertIrp** and **IoCsqInsertIrpEx** can be called on any cancel-safe queue, whether the queue has a *CsqInsertIrp* routine or a *CsqInsertIrpEx* routine. **IoCsqInsertIrp** behaves the same in either case. If **IoCsqInsertIrpEx** is passed a queue that has a *CsqInsertIrp* routine, it behaves identically to **IoCsqInsertIrp**. + +The following diagram illustrates the flow of control for [**IoCsqInsertIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549066). + +![diagram illustrating the flow of control for iocsqinsertirp](images/iocsqinsertirp.png) + +The following diagram illustrates the flow of control for [**IoCsqInsertIrpEx**](https://msdn.microsoft.com/library/windows/hardware/ff549067). + +![diagram illustrating the flow of control for iocsqinsertirpex](images/2iocsqinitializeex.png) + +There are several natural ways to use the **IoCsq*Xxx*** routines to queue and dequeue IRPs. For example, a driver could simply queue IRPs to be processed in the order in which they are received. The driver could queue an IRP as follows: + +``` + status = IoCsqInsertIrpEx(IoCsq, Irp, NULL, NULL); +``` + +If the driver is not required to distinguish between particular IRPs, it could then simply dequeue them in the order in which they were queued, as follows: + +``` + IoCsqRemoveNextIrp(IoCsq, NULL); +``` + +Alternatively, the driver could queue and dequeue specific IRPs. The routines use the opaque [**IO\_CSQ\_IRP\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff550567) structure to identify particular IRPs in the queue. The driver queues the IRP as follows: + +``` + IO_CSQ_IRP_CONTEXT ParticularIrpInQueue; + IoCsqInsertIrp(IoCsq, Irp, &ParticularIrpInQueue); +``` + +The driver can then dequeue the same IRP by using the **IO\_CSQ\_IRP\_CONTEXT** value. + +``` + IoCsqRemoveIrp(IoCsq, Irp, &ParticularIrpInQueue); +``` + +The driver might also be required to remove IRPs from the queue based on a particular criterion. For example, the driver might associate a priority with each IRP, such that higher priority IRPs get dequeued first. The driver might pass a *PeekContext* value to [**IoCsqRemoveNextIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549072), which the system passes back to the driver when it requests the next IRP in the queue. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Cancel-Safe%20IRP%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/canceling-a-wait-wake-irp.md b/windows-driver-docs-pr/kernel/canceling-a-wait-wake-irp.md new file mode 100644 index 0000000000..7064dabaa0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/canceling-a-wait-wake-irp.md @@ -0,0 +1,76 @@ +--- +title: Canceling a Wait/Wake IRP +author: windows-driver-content +description: Canceling a Wait/Wake IRP +ms.assetid: 08e1d11a-91a3-496a-b3ad-f99456e4ce1d +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "wait/wake IRPs WDK power management , canceling", "canceling wait/wake IRPs", "Cancel routines, wait/wake IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Canceling a Wait/Wake IRP + + +## + + +Only the driver that sent a wait/wake IRP can cancel that IRP. + +A driver might need to cancel a pending wait/wake IRP under the following circumstances: + +- The driver receives a PnP [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755), [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705), [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738), or [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request for the device. The driver should reissue the wait/wake IRP ([**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734)) after the device is restarted. + +- The system is going to sleep, but the device should not be enabled to wake the system. + + For example, the USB hub driver might send an **IRP\_MN\_WAIT\_WAKE** request at device start-up in case it later puts one of its input devices into a sleep state. While the system is in the working state, a wake signal from the device returns the device to the working state (but has no effect on the system power state). When the system prepares to shut down, the USB hub driver cancels this IRP if the device should not be allowed to awaken the system. + +- The system is entering a sleep state from which the device cannot awaken it. That is, it is entering a state less powered than the [**SystemWake**](systemwake.md) value specified in its [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. + +- The device is entering a power state from which it cannot respond to a wake-up signal. That is, it is entering a state less-powered than the [**DeviceWake**](devicewake.md) value specified in its **DEVICE\_CAPABILITIES** structure. + +To cancel a wait/wake IRP, the driver that sent the IRP calls [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338), passing the pointer to the IRP that was previously returned when the driver called **PoRequestPowerIrp**. + +A driver must not cancel a wait/wake IRP that it did not send. + +### Cancel Routines for Wait/Wake IRPs + +Many function and bus drivers should set [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routines for pending wait/wake IRPs; the following types of drivers must set such routines: + +- Drivers that change device settings to enable or disable wake-up. + +- Drivers that send [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) requests to drivers of parent devices. + +A [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine allows a driver to disable wake-up for its device and to clean up any data related to the pending wait/wake IRP. Drivers that request wait/wake IRPs for parent devices can cancel those IRPs as well. + +In its wait/wake *Cancel* routine, a driver should take the following steps: + +1. Call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to reset the *Cancel* routine for the IRP to **NULL**. + +2. Call [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550), passing the **CancelIRQL** specified in the IRP to release the cancel spin lock for the IRP. + +3. Reset any relevant fields in the device extension. For example, when a wait/wake IRP is pending, most drivers set a flag and keep a pointer to the IRP in the device extension. + + Note that it is possible for a driver to receive a wait/wake IRP while it is canceling another such IRP. The driver must check to see whether it already has an IRP under spin lock protection (or its equivalent). If so, the driver must carefully synchronize its handling to ensure that it cancels the correct IRP. For more information about using spin locks in *Cancel* routines, see [Canceling IRPs](canceling-irps.md). + +4. Change any required device settings. For example, a modem driver would disable the device's wake setting. + +5. Set **Irp->IoStatus.Status** to STATUS\_CANCELLED. + +6. Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the wait/wake IRP, specifying IO\_NO\_INCREMENT. + +7. If the driver previously requested a related **IRP\_MN\_WAIT\_WAKE** for a parent device, the driver should cancel that IRP from within its *Cancel* routine. The driver must release the cancel spin lock before it cancels the parent's IRP. + + For example, a driver that acts as a bus driver for a device and owns power policy driver for its parent should cancel a related wait/wake IRP that it earlier sent to its parent. Calling [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338) would invoke the parent's *Cancel* routine, and so on down the device stack. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Canceling%20a%20Wait/Wake%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/canceling-irps.md b/windows-driver-docs-pr/kernel/canceling-irps.md new file mode 100644 index 0000000000..937607514f --- /dev/null +++ b/windows-driver-docs-pr/kernel/canceling-irps.md @@ -0,0 +1,50 @@ +--- +title: Canceling IRPs +author: windows-driver-content +description: Canceling IRPs +ms.assetid: da199435-f6c3-44f4-b1ed-0280f39ee452 +keywords: ["IRPs WDK kernel , canceling", "canceling IRPs", "Cancel routines", "user-canceled I/O requests WDK kernel", "completing IRPs WDK kernel , canceling IRPs", "unprocessed IRP cancellations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Canceling IRPs + + +## + + +Drivers in which IRPs might remain queued for an indefinite interval (so a user could cancel a previously submitted I/O request) must have one or more [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routines to complete user-canceled I/O requests. For example, keyboard, mouse, parallel, serial, and sound device drivers (or drivers layered over them) and file system drivers should have *Cancel* routines. + +Drivers for Microsoft Windows XP and later operating systems can use [cancel-safe IRP queues](cancel-safe-irp-queues.md) rather than implement their own *Cancel* routines. + +To "cancel an IRP" means to complete the IRP as quickly as possible while still maintaining system integrity. For a general discussion of IRP completion, see [Completing IRPs](completing-irps.md). + +The cancellation process begins when either the system or a driver calls [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338). This routine is called for each IRP that is associated with the thread that has not yet fully completed. The system cancels unprocessed IRPs if the thread that initiated the I/O request exits. Drivers can cancel only IRPs that they have created (see [Creating IRPs for Lower-Level Drivers](creating-irps-for-lower-level-drivers.md).) + +If an IRP is not completed within 5 minutes, the I/O manager considers the IRP timed out. Such IRPs are disassociated from the thread, and an error is logged for the device that currently owns the IRP. You should ensure that any requests that might take a long time to complete in your driver are cancelable. To ensure that potentially long requests are cancelable, you can use [cancel-safe IRP queues](cancel-safe-irp-queues.md) or [Kernel-Mode Driver Framework](https://msdn.microsoft.com/library/windows/hardware/dn265580), which abstracts cancellation away from the driver developer. + +This section provides the following topics: + +[Introduction to Cancel Routines](introduction-to-cancel-routines.md) + +[Registering a Cancel Routine](registering-a-cancel-routine.md) + +[Synchronizing IRP Cancellation](synchronizing-irp-cancellation.md) + +[Implementing a Cancel Routine](implementing-a-cancel-routine.md) + +[Points to Consider When Canceling IRPs](points-to-consider-when-canceling-irps.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Canceling%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/changes-to-the-amount-of-physical-memory.md b/windows-driver-docs-pr/kernel/changes-to-the-amount-of-physical-memory.md new file mode 100644 index 0000000000..09c10053b2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/changes-to-the-amount-of-physical-memory.md @@ -0,0 +1,35 @@ +--- +title: Changes to the Amount of Physical Memory +author: windows-driver-content +description: Changes to the Amount of Physical Memory +ms.assetid: 5ab1d598-e702-4fc7-aab4-7b7726c3a552 +keywords: ["dynamic hardware partitioning WDK , physical memory", "hardware partitioning WDK dynamic , physical memory", "partitions WDK dynamic hardware , physical memory", "physical memory WDK dynamic hardware partitioning", "memory WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Changes to the Amount of Physical Memory + + +On a dynamically partitionable server, you can add memory modules to a hardware partition at any time. Therefore, do not make any assumptions about how much physical memory exists in a hardware partition. + +If a device driver uses the amount of physical memory in the hardware partition to determine the size of the memory buffers that it allocates, you must update the driver so that it will function correctly on a dynamically partitionable server when you dynamically add memory to the hardware partition. + +If a device driver is affected by changes to the amount of physical memory, it must register itself with the operating system to be notified when memory is added to the hardware partition. When the device driver is notified, it can respond as required to ensure safe and optimal operation. For more information about how a device driver can register itself with the operating system, see [Driver Notification](driver-notification.md). + +**Note**  Starting with Windows Server 2008, the size of the paged and nonpaged system memory pools do not change after the operating system has started. Therefore, if you add memory to the hardware partition, the amount of memory in these system memory pools does not change. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Changes%20to%20the%20Amount%20of%20Physical%20Memory%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/changes-to-the-number-of-processors.md b/windows-driver-docs-pr/kernel/changes-to-the-number-of-processors.md new file mode 100644 index 0000000000..6f2ee99f6b --- /dev/null +++ b/windows-driver-docs-pr/kernel/changes-to-the-number-of-processors.md @@ -0,0 +1,65 @@ +--- +title: Changes to the Number of Processors +author: windows-driver-content +description: Changes to the Number of Processors +ms.assetid: 9ced4b42-c83d-49da-8405-b95b0c0144fa +keywords: ["dynamic hardware partitioning WDK , changing number of processors", "hardware partitioning WDK dynamic , changing number of processors", "partitions WDK dynamic hardware , changing number of processors", "active processors WDK dynamic hardware partitioning", "processor count WDK dynamic hardware partitioning", "processor affinity WDK dynamic hardware paritioning", "per-processor data structures WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Changes to the Number of Processors + + +On a dynamically partitionable server, you can add a processor to a hardware partition at any time. Therefore, you should not make any assumptions about the number of active processors in a hardware partition, the processor affinity value, or the processor number that is assigned to each active processor. The bits that are set in the processor affinity value represent each of the currently active processors in the hardware partition. The particular bits that are set will change if you add a processor to the hardware partition. + +If any of the following statements are true for a device driver, you must update the driver so that it will function correctly on a dynamically partitionable server when a processor is dynamically added to a hardware partition: + +- The device driver uses the number of active processors in the hardware partition to determine the amount of resources that it uses, such as the amount of memory that it allocates, the number of threads that it creates, or the amount of other resources that it uses. In this situation, the device driver's resource allocation will be incorrect if a processor is dynamically added to the hardware partition. This could adversely affect the performance or behavior of the driver. + +- The device driver walks the bits of the processor affinity value. In this situation, the device driver might not work correctly if it cannot handle dynamic changes to the processor affinity value or cannot handle gaps in the sequence of bits that are set. + +- The device driver uses the bits in the processor affinity value to assign driver-allocated resources to specific processors. In this situation, the device driver's resource assignments will be incorrect if a processor is dynamically added to the hardware partition. This could adversely affect the performance or behavior of the driver. + +- The device driver allocates data structures for each active processor in the hardware partition. In this situation, the device driver could cause adverse behavior, data corruption, or a bug check to occur if it tries to access these data structures for a processor that was dynamically added to the hardware partition. + +- The device driver's dispatch routines use the processor number of the processor on which they are running to access data structures or other resources that are assigned to that particular processor. In this situation, the device driver's dispatch routines can cause adverse behavior, data corruption, or a bug check to occur if they try to access these resources for a processor that has been dynamically added to the hardware partition. + +- The device driver schedules its interrupt service routines (ISRs), deferred procedure calls (DPCs), or other threads on specific processors. In this situation, the device driver might stop functioning correctly if you add a processor to the hardware partition, and the device driver will be unable to fully use any new processors. + +- The device driver does not support resource rebalancing. In this situation, the device driver will be unable to use any new processors that are added to the hardware partition for handling interrupts. + +- The device driver uses a load balancing algorithm to distribute the processing of I/O requests across multiple processors. In this situation, the device driver might stop functioning correctly if you add a processor to the hardware partition, and the device driver will be unable to fully use any new processors. + +If a device driver is affected by changes to the number of active processors, it must register itself with the operating system to be notified when you add processors to the hardware partition. When the device driver is notified, it can respond as required for safe and optimal operation. For more information about how a device driver can register itself with the operating system, see [Driver Notification](driver-notification.md). + +To retrieve the current number of active processors in the hardware partition, device drivers should call the [**KeQueryActiveProcessorCount**](https://msdn.microsoft.com/library/windows/hardware/ff552985) function. To retrieve the current processor affinity value, device drivers can call either the [**KeQueryActiveProcessors**](https://msdn.microsoft.com/library/windows/hardware/ff553001) function or the **KeQueryActiveProcessorCount** function. + +**Note**  If a device driver allocates data structures for each active processor in the hardware partition and the device driver would fail if the memory allocation for the data structures for a new processor failed, the device driver can allocate enough of these data structures during driver initialization to handle the maximum number of processors that the operating system supports. In this situation, the device driver would not have to allocate new data structures when you add new processors to the hardware partition. However, unless the size of these data structures is fairly small, this can be an inefficient use of memory resources. A device driver can query the maximum number of processors that the operating system supports by calling the [**KeQueryMaximumProcessorCount**](https://msdn.microsoft.com/library/windows/hardware/ff553042) function. + +  + +**Important**  Device drivers should always update any saved value of the number of active processors and the processor affinity when it is notified that you added a processor to the hardware partition. + +  + +**Important**  A device driver should not count the number of set bits in the processor affinity value to determine the number of active processors in the hardware partition. We recommended that device drivers call the **KeQueryActiveProcessorCount** function for this purpose. This function returns both the number of active processors and the associated processor affinity value. + +  + +**Important**  Device drivers that are built for Windows Vista, Windows Server 2008 and later versions of Windows must not use the [**KeNumberProcessors**](https://msdn.microsoft.com/library/windows/hardware/ff552975) kernel variable to determine the number of active processors in the hardware partition. The **KeNumberProcessors** kernel variable is obsolete in Windows Vista with Service Pack 1 (SP1), Windows Server 2008, and later versions of Windows. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Changes%20to%20the%20Number%20of%20Processors%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/checking-flags-in-the-device-object.md b/windows-driver-docs-pr/kernel/checking-flags-in-the-device-object.md new file mode 100644 index 0000000000..95b9984886 --- /dev/null +++ b/windows-driver-docs-pr/kernel/checking-flags-in-the-device-object.md @@ -0,0 +1,38 @@ +--- +title: Checking Flags in the Device Object +author: windows-driver-content +description: Checking Flags in the Device Object +ms.assetid: f7bff7b8-bd30-4489-ab3f-ca5ad4d5c1ba +keywords: ["removable media WDK kernel , flag checking", "flags WDK removable media", "checking device object flags", "verifying device object flags"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Checking Flags in the Device Object + + +## + + +For each IRP requesting an I/O operation to/from removable media, a removable-media device driver must determine whether DO\_VERIFY\_VOLUME is already set in its **DeviceObject->Flags**. If this value is set, the driver must do the following: + +- For [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794), [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), and [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests, check whether SL\_OVERRIDE\_VERIFY\_VOLUME is set in the **Flags** member of the driver's [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure. If it is, continue the requested operation. + + Device control requests that return information about the logical structure of the underlying media have SL\_OVERRIDE\_VERIFY\_VOLUME set in the I/O stack location's **Flags** member when an IFS mounts or remounts a removable-media volume. + +- Otherwise, the driver must refuse to carry out I/O requests for the corresponding drive, device, or partition while DO\_VERIFY\_VOLUME is set in its **DeviceObject->Flags**. A removable media driver must fail IRPs sent to the corresponding device as described in the preceding subsection, repeating both Steps 3 and 4 for each IRP until the FSD clears DO\_VERIFY\_VOLUME in the removable-media driver's **DeviceObject->Flags**. + +If a removable-media device driver does not fail IRPs when DO\_VERIFY\_VOLUME is set and SL\_OVERRIDE\_VERIFY\_VOLUME is not set for the preceding transfer requests, the file system can neither maintain the integrity of cached file data nor cause the user to be prompted to remount the media that holds an open file. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Checking%20Flags%20in%20the%20Device%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/clfs-log-sequence-numbers.md b/windows-driver-docs-pr/kernel/clfs-log-sequence-numbers.md new file mode 100644 index 0000000000..a655be0397 --- /dev/null +++ b/windows-driver-docs-pr/kernel/clfs-log-sequence-numbers.md @@ -0,0 +1,84 @@ +--- +title: CLFS Log Sequence Numbers +author: windows-driver-content +description: CLFS Log Sequence Numbers +ms.assetid: 4637fa0c-2f19-4f0c-bf13-f4ccac2e7284 +keywords: ["Common Log File System WDK kernel , log sequence numbers", "CLFS WDK kernel , log sequence numbers", "log sequence numbers WDK CLFS", "LSNs WDK CLFS", "base LSNs WDK CLFS", "last LSNs WDK CLFS", "previous LSNs WDK CLFS", "undo-next LSNs WDK CLFS", "active stream portion WDK CLFS", "stream active portion WDK CLFS", "streams WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CLFS Log Sequence Numbers + + +## + + +In the Common Log File System (CLFS), each log record in a given stream is uniquely identified by a log sequence number (LSN). When you write a record to a stream, you get back an LSN that identifies that record for future reference. + +The LSNs created for a particular stream form a strictly increasing sequence. That is, the LSN assigned to a log record in a given stream is always greater than the LSNs assigned to log records previously written to that same stream. The following functions are available for comparing the LSNs of log records in a given stream. + +[**ClfsLsnNull**](https://msdn.microsoft.com/library/windows/hardware/ff541609) + +[**ClfsLsnEqual**](https://msdn.microsoft.com/library/windows/hardware/ff541590) + +[**ClfsLsnGreater**](https://msdn.microsoft.com/library/windows/hardware/ff541595) + +[**ClfsLsnLess**](https://msdn.microsoft.com/library/windows/hardware/ff541608) + +The constants CLFS\_LSN\_NULL and CLFS\_LSN\_INVALID are the lower and upper boundaries for all valid LSNs. Any valid LSN is greater than or equal to CLFS\_LSN\_NULL. Also, any valid LSN is strictly less than CLFS\_LSN\_INVALID. Note that CLFS\_LSN\_NULL is a valid LSN, whereas CLFS\_LSN\_INVALID is not a valid LSN. Even so, you can compare CLFS\_LSN\_INVALID to other LSNs by using the functions in the previous list. + +For each stream, CLFS keeps track of two special LSNs: the base LSN and the last LSN. Also, each individual log record has two special LSNs (the previous LSN and the undo-next LSN) that you can use to create chains of related log records. The following sections describe these special LSNs in detail. + +### Base LSN + +When a client writes the first record in a stream, CLFS sets the base LSN to the LSN of that first record. The base LSN remains unchanged until a client changes it. When the stream's clients no longer need the records prior to a certain point in the stream, they can update the base LSN by calling [**ClfsAdvanceLogBase**](https://msdn.microsoft.com/library/windows/hardware/ff540773) or [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770). For example, if the clients no longer need the first five log records, they can set the base LSN to the LSN of the sixth record. + +### Last LSN + +As clients write records to a stream, CLFS adjusts the last LSN so that it is always the LSN of the last record written. If the clients no longer need the records after a certain point in the stream, they can update the last LSN by calling [**ClfsSetEndOfLog**](https://msdn.microsoft.com/library/windows/hardware/ff541753). For example, if the clients no longer need any records written after the tenth record, they can truncate the stream by setting the last LSN to the LSN of the tenth record. + +### Active portion of a stream + +The *active portion* of a stream is the portion of a stream that begins with the record pointed to by the base LSN and ends with the record pointed to by the last LSN. The following diagram illustrates how the base LSN and last LSN delineate the active portion of a stream. + +![diagram illustrating the active portion of a clfs stream](images/clfsactivelog.gif) + +**Note**   If a stream has an archive tail, the active portion of the stream begins at the record pointed to by the base LSN or the archive tail, whichever is smaller. For more information about archiving, see [CLFS Support for Archiving](clfs-support-for-archiving.md). + +  + +### Previous LSN + +Suppose two active database transactions (transaction A and transaction B) are writing records to the same stream at the same time. Each time transaction A writes a record, it sets the record's previous LSN to the LSN of the previous log record written by transaction A. That forms a chain of log records, belonging to transaction A, that can be traversed in reverse order. The chain ends with the first log record written by transaction A, which has its previous LSN set to CLFS\_LSN\_INVALID. Similarly, transaction B creates its own chain of log records by setting the previous LSN of each log record it writes. + +The arrows in the following diagram illustrate how the previous LSN of a log record points to the previous record in a chain that belongs to a particular transaction. + +![diagram illustrating previous lsn pointers](images/clfsrecordchains.gif) + +### Undo-next LSN + +Suppose a transaction makes five updates to a data object in volatile memory, rolls back the fourth and fifth updates, and then makes a sixth update. As the transaction makes the updates, it writes log records 1, 2, 3, 4, 5, 5', 4', and 6. Log records 1 through 5 describe the changes made by updates 1 through 5. Record 5' describes the changes made during the rollback of update 5, and record 4' describes the changes made during the rollback of update 4. Finally, record 6 describes the changes made by update 6. Note that the numbers 1, 2, 3, 4, 5, 5', 4', and 6 are not the LSNs of the log records; they are just numbers used to name the log records for the purpose of this discussion. + +Log records 5' and 4', which describe rollbacks, are called compensation log records (CLRs). The transaction sets the undo-next LSN of each CLR to the predecessor (among the records written by the transaction) of the log record whose update was just rolled back (undone). In this example, the undo-next LSN of record 5' is the LSN of record 4, and the undo-next LSN of record 4' is the LSN of record 3. + +The ordinary log records (those that are not CLRs), have their undo-next LSNs set to the previous log record written by the transaction. That is, for an ordinary record, the undo-next LSN and previous LSN are the same. + +Now suppose there is a system failure and, during restart recovery, the entire transaction must be rolled back. The recovery code reads log record 6. The data in record 6 indicates that record 6 is an ordinary record (not a CLR), so the recovery code rolls back update 6. Then the recovery code inspects the undo-next LSN of record 6 and finds that it points to record 4'. The data in record 4' indicates that it is a CLR, so the recovery code does not roll back update 4'. Instead, it inspects the undo-next LSN of record 4' and finds that it points to record 3. Record 3 is not a CLR, so the recovery code rolls back update 3. Updates 5 and 4 are not rolled back during recovery because they were already rolled back during ordinary forward processing. Finally the recovery code rolls back updates 2 and 1. + +The arrows in the following diagram illustrate how the undo-next LSN provides a mechanism that recovery code can use to skip records whose updates have already been rolled back. + +![diagram illustrating previous lsn and undo-next lsn pointers](images/clfsundonext.gif) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20CLFS%20Log%20Sequence%20Numbers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/clfs-marshalling-areas.md b/windows-driver-docs-pr/kernel/clfs-marshalling-areas.md new file mode 100644 index 0000000000..685a4d772b --- /dev/null +++ b/windows-driver-docs-pr/kernel/clfs-marshalling-areas.md @@ -0,0 +1,42 @@ +--- +title: CLFS Marshalling Areas +author: windows-driver-content +description: CLFS Marshalling Areas +ms.assetid: 1153bcfd-43e9-43bd-b893-5ec044ea9584 +keywords: ["Common Log File System WDK kernel , marshalling areas", "CLFS WDK kernel , marshalling areas", "marshalling areas WDK CLFS", "log I/O buffers WDK CLFS", "maximum number of log I/O buffers WDK CLFS", "memory allocations WDK CLFS", "buffers WDK CLFS", "appending records WDK CLFS", "stable storage WDK CLFS", "volatile memory WDK CLFS", "storage WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CLFS Marshalling Areas + + +## + + +A Common Log File System (CLFS) client appends log records to a [*marshalling area*](clfs-terminology.md#kernel-clfs-term-marshalling-area) in volatile memory, and CLFS periodically writes those records to stable storage. A marshalling area is a collection of log I/O buffers, each of which can hold several log records. Log I/O buffers hold records that have recently been written to a stream (but possibly not flushed to stable storage) as well as records that have recently been read from the stream. + +You create a marshalling area by calling [**ClfsCreateMarshallingArea**](https://msdn.microsoft.com/library/windows/hardware/ff541520), at which time you must specify the size of the log I/O buffers that the marshalling area will use and whether those buffers will be in the paged or non-paged pool. All log I/O buffers in a marshalling area are the same size, and CLFS ensures that the size is a multiple of the sector size on the underlying stable storage medium. That is, CLFS takes your requested size and rounds it up as necessary to make your I/O buffers compatible with the stable storage medium. + +CLFS allocates and frees log I/O buffers as needed, but you have the option of setting the maximum number of I/O buffers that can be allocated at one time. You also have the option of providing your own buffer allocation and deallocation functions. + +To specify the maximum number of log I/O buffers that can be allocated at one time for writing log records, set the *cMaxWriteBuffers* parameter of the **ClfsCreateMarshallingArea** function. Limiting the number of buffers affects the frequency of flushes to stable storage; with fewer buffers, log records must be written to stable storage more often. If you do not need to control the flush frequency, set *cMaxWriteBuffers* to INFINITE (defined in Winbase.h). + +To specify the maximum number of log I/O buffers that can be allocated at one time for reading log records, set the *cMaxReadBuffers* parameter of the **ClfsCreateMarshallingArea** function. If you do not need to control the number of allocated read buffers, set *cMaxReadBuffers* to INFINITE. + +If you want to do your own memory allocation for log I/O buffers, set the *pfnAllocBuffer* and *pfnFreeBuffer* parameters of the **ClfsCreateMarshallingArea** function to point to your own allocation and deallocation functions. Then CLFS will call your functions to perform the actual memory allocation and deallocation whenever it needs to create or free log I/O buffers. + +In some cases, you might want to reserve space in a marshalling area ahead of time. For example, you might know that you are about to write a set of ten log records, and you want to be sure that there is enough space in the marshalling area for the entire set. To reserve space for the ten records, create a ten-element array that holds the sizes of the records, and then pass the array to the [**ClfsReserveAndAppendLog**](https://msdn.microsoft.com/library/windows/hardware/ff541723) function in the *rgcbReservation* parameter. **ClfsReserveAndAppendLog** is a multi-purpose function that reserves space in a marshalling area or appends log records to a stream or does both of those things atomically. By setting the parameters appropriately, you can call **ClfsReserveAndAppendLog** to reserve space for future use without actually appending any records to the stream. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20CLFS%20Marshalling%20Areas%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/clfs-stable-storage.md b/windows-driver-docs-pr/kernel/clfs-stable-storage.md new file mode 100644 index 0000000000..b2fcae497c --- /dev/null +++ b/windows-driver-docs-pr/kernel/clfs-stable-storage.md @@ -0,0 +1,76 @@ +--- +title: CLFS Stable Storage +author: windows-driver-content +description: CLFS Stable Storage +ms.assetid: d0ee4f22-9fba-47da-a9c9-eaf3a21feb36 +keywords: ["Common Log File System WDK kernel , stable storage", "CLFS WDK kernel , stable storage", "stable storage WDK CLFS", "storage WDK CLFS", "containers WDK CLFS", "logical containers WDK CLFS", "physical containers WDK CLFS", "log I/O blocks WDK CLFS", "blocks WDK CLFS", "block offsets WDK CLFS", "logs WDK CLFS", "physical logs WDK CLFS", "container identifiers WDK CLFS", "record sequence numbers WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CLFS Stable Storage + + +## + + +When you write a record to a Common Log File System (CLFS) stream, the record is placed in a log I/O block (in a marshalling area) in volatile memory. Periodically, CLFS flushes log I/O blocks from the marshalling area to stable storage such as a disk. On the stable storage device, the log consists of a set of containers, each of which is a contiguous extent on the physical medium. A collection of containers that forms the stable storage for a stream is called a *log*, or a *physical log*. + +The following figure illustrates a container. + +![diagram illustrating containers, blocks, and records](images/clfscontainers.gif) + +The preceding figure illustrates a container that holds three log I/O blocks. The first log I/O block contains three records, the second contains five records, and the third contains two records. As the figure suggests, the beginning of each log I/O block is always aligned with the beginning of a sector on the stable storage medium. Note that log I/O blocks on stable storage vary in size. + +CLFS uses a set of three numbers to locate a record in a log. + +- The *container identifier* identifies the container that holds the record. + +- The *block offset* gives the byte offset, within the container, of the beginning of the log I/O block that holds the record. + +- The *record sequence* number identifies the record within the log I/O block. + +The log sequence number (LSN) of a CLFS log record actually holds those three pieces of information: container identifier, block offset, and record sequence number. However, the LSNs given to log clients contain *logical container identifiers* that CLFS must map to physical container identifiers before it accesses the records on stable storage. + +CLFS uses logical container identifiers to give clients the view that log records are being written to an ongoing sequence of containers, when in fact, the physical containers are being recycled. + +Suppose a log has three containers, and a single client is writing CLFS records to the log. The following scenario shows how a container could be recycled. + +1. The client writes enough log records to fill all three containers. + +2. The client sets the log base (by calling [**ClfsAdvanceLogBase**](https://msdn.microsoft.com/library/windows/hardware/ff540773) or [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770).) to one of the records in container 2. By doing that, the client is saying that it no longer needs the records in container 1. + +3. The client writes another record to the log and gets back the LSN of the newly written record. The logical container identifier in that LSN is 4. When records are flushed to stable storage, records that the client sees in logical container 4 will go to physical container 1. + +The following figure illustrates the scenario; it shows how the client sequence of logical containers is mapped to physical containers on stable storage. + +![diagram illustrating logical and physical containers](images/clfslogicalcontainers.gif) + +The logical container identifier, block offset, and record sequence number are stored in an LSN in such a way that the LSNs for a particular stream always form a strictly increasing sequence. That is, the LSN (with logical container identifier) of a log record written to a stream is always greater than the LSNs of the log records previously written to that same stream. LSNs, then, serve a dual purpose: 1) they give the clients of a stream an ordered sequence of record identifiers, and 2) they provide CLFS with the location of records on stable storage. + +Given the LSN of a record, you can extract the logical container identifier, the block offset, and the record sequence number by calling the following functions. + +[**ClfsLsnContainer**](https://msdn.microsoft.com/library/windows/hardware/ff541573) + +[**ClfsLsnBlockOffset**](https://msdn.microsoft.com/library/windows/hardware/ff541569) + +[**ClfsLsnRecordSequence**](https://msdn.microsoft.com/library/windows/hardware/ff541615) + +The logical container identifier is a 32-bit number, so there are 2^32 possible logical container identifiers, and they are in the range 0x0 through 0xFFFFFFFF. A stream can have at most 2^32 logical containers. + +The block offset is stored in 23 bits of the LSN, but **ClfsLsnBlockOffset** returns a 32-bit number that is aligned with the sector size of the stable storage medium. The block offset is always a multiple of 512. Also, the block offset is aligned with the sector size of the stable storage medium. For example, if the sector size is 1024 bytes, the block offset will be a multiple of 1024. + +The record sequence number is a 9-bit number, so there are 2^9 (512) possible record sequence numbers, and they are in the range 0x0 through 0x1FF. A log I/O block can have at most 512 records. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20CLFS%20Stable%20Storage%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/clfs-support-for-archiving.md b/windows-driver-docs-pr/kernel/clfs-support-for-archiving.md new file mode 100644 index 0000000000..cbb568ce59 --- /dev/null +++ b/windows-driver-docs-pr/kernel/clfs-support-for-archiving.md @@ -0,0 +1,38 @@ +--- +title: CLFS Support for Archiving +author: windows-driver-content +description: CLFS Support for Archiving +ms.assetid: 5a07d7d2-4939-48f8-bd4c-855af61034fb +keywords: ["Common Log File System WDK kernel , archiving", "CLFS WDK kernel , archiving", "archiving WDK CLFS", "non-ephemeral logs WDK CLFS", "archive tail WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CLFS Support for Archiving + + +## + + +Common Log File System (CLFS) supports archiving for dedicated logs by maintaining an archive tail. When you call [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) to create a dedicated log, you can set the FILE\_ATTRIBUTE\_ARCHIVE flag of the *fFlagsAndAttributes* parameter to specify that CLFS should maintain an archive tail for the log. A log for which CLFS maintains an archive tail is called a *non-ephemeral log*. + +Suppose you are performing transactions on a database and each transaction has several updates that are described by log records. After a particular transaction has committed and been written to stable storage, you might not need the log records that describe that transaction any more. That is, the log records would not be needed during restart recovery in the event of a system failure. However, if the stable storage medium that holds the database fails and the database has not been recently archived on a different medium, the database updates could be lost. + +The preceding paragraph describes archiving database records, but in other scenarios you might want to archive log records. In either case, archiving is the responsibility of the clients (your software). You can keep track of the archiving you have done by setting the log's archive tail. The archive tail is the log sequence number (LSN) of the oldest record for which archiving has not yet been completed. + +A non-ephemeral log actually has two tails: one marked by the base LSN and one marked by the archive tail. You can position the two tails as you see fit by calling [**ClfsAdvanceLogBase**](https://msdn.microsoft.com/library/windows/hardware/ff540773) (or [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770)), and [**ClfsSetArchiveTail**](https://msdn.microsoft.com/library/windows/hardware/ff541744). Typically the base LSN points to the oldest record that would still be needed for transaction rollback or restart recovery, and the archive tail points to the oldest record for which archiving has not been performed. Note that the archive tail might be less than the base LSN or it might be greater than the base LSN. + +The base LSN and the archive tail are important when you call [**ClfsReadNextLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541690) repeatedly to read a chain of records linked by previous LSNs, undo-next LSNs, or user LSNs. **ClfsReadNextLogRecord** will not read a record whose LSN is less than both the archive tail and the base LSN. It will, however, read a record whose LSN is between the archive tail and the base LSN. For more information about following record chains, see [Reading Data Records from a CLFS Stream](reading-data-records-from-a-clfs-stream.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20CLFS%20Support%20for%20Archiving%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/clfs-terminology.md b/windows-driver-docs-pr/kernel/clfs-terminology.md new file mode 100644 index 0000000000..801191d1d6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/clfs-terminology.md @@ -0,0 +1,81 @@ +--- +title: CLFS Terminology +author: windows-driver-content +description: The following list gives definitions of key terms used in the Common Log File System (CLFS) documentation. +Robots: noindex, nofollow +ms.assetid: d8511c5a-0181-4c54-acdc-e8a5892bb620 +keywords: ["Common Log File System WDK kernel , terminology", "CLFS WDK kernel , terminology"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# CLFS Terminology + + +The following list gives definitions of key terms used in the Common Log File System (CLFS) documentation. These definitions apply during a discussion of CLFS, but might not apply otherwise. Many of these terms have general meanings or meanings in the context of other technologies that differ from the definitions given here. + +**container** +A contiguous extent on a physical disk or other stable storage medium. For example, a container could be a contiguous disk file. + +**sector** +The unit of atomic I/O on a physical storage medium. The size of a sector is a property of a particular storage device. For example, a hard disk might have a sector size of 512 bytes. + +**log** +A base file and a set of logically ordered containers. The base file holds metadata for the log, and the containers hold log records. All the containers are the same size. + +**client** +An application, driver, thread, or other unit of software that uses a CLFS log. + +**record** +The unit of data that a client can append to or read from a log. + +**stream** +An ordered subset of the records in a log. A log can have one or more streams. A client appends records to and reads records from a particular stream. You can compare the records in a given stream to determine the order in which they were written. You cannot compare records in different streams. A given stream can have several clients. For example, several threads could append records to a single stream. To a client, a stream appears as if it were the entire log. + +**dedicated log** +A log that can have only one stream. + +**multiplexed log** +A log that can have several streams. + +**log I/O block** +A buffer where CLFS collects a set of records that are atomically written to stable storage. + +**marshalling area** +A set of log I/O blocks, created, maintained, and scheduled by a CLFS client for gathering log records and writing them to stable storage. The log I/O blocks allocated in volatile memory for a particular marshalling area are all the same size. + +**Note**   Even though all the log I/O blocks (in volatile memory) for a particular marshalling area are the same size, the log I/O blocks that are written to stable storage (from that marshalling area) vary in size. For example, if a log I/O block is forced to stable storage before it is full, only the used portion of the block will be written to stable storage. + +  + +**log sequence number (LSN)** +An opaque structure that holds a value that uniquely identifies a log record in a given stream. When a client writes a record to a stream, it gets back an LSN that it can use to identify the record in the future. The LSNs that CLFS assigns to the records in a stream form an increasing sequence. That is, the LSN assigned to a record in a stream is always greater than the LSN assigned to the record previously written to that same stream. + +**Note**   Records across streams are not comparable. That is, you cannot compare the LSNs of two records in different streams to determine which record was written first. + +  + +**base LSN** +The LSN of the oldest record in a stream that is still needed by the stream's clients. The clients are responsible for updating the base LSN. + +**last LSN** +The LSN of the youngest record in a stream that is still needed by the stream's clients. Typically this is the record that was most recently written to the stream, but clients have the option of manually setting the last LSN to point to some earlier record in the stream. Manually setting the last LSN to an earlier record is called *truncating* the stream. + +**archive tail** +The LSN of the oldest record in a log for which archiving has not taken place. Not every log has an archive tail. A log that does not have an archive tail is called *ephemeral*, and a log that has an archive tail is called *non-ephemeral*. When a client specifies that a log has an archive tail, the client is responsible for updating the archive tail. + +**active portion of a stream** +The portion of a stream that is currently in use by its clients. The active portion begins with the record pointed to by the base LSN or the archive tail, whichever is smaller. The active portion ends with the record pointed to by the last LSN. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20CLFS%20Terminology%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/compiling-a-driver-s-mof-file.md b/windows-driver-docs-pr/kernel/compiling-a-driver-s-mof-file.md new file mode 100644 index 0000000000..eeb1ea4b9a --- /dev/null +++ b/windows-driver-docs-pr/kernel/compiling-a-driver-s-mof-file.md @@ -0,0 +1,65 @@ +--- +title: Compiling a Driver's MOF File +author: windows-driver-content +description: Compiling a Driver's MOF File +ms.assetid: 0a4ab163-3e2c-48e9-9659-756d35ad445f +keywords: ["WMI WDK kernel , publishing schema", "publishing WMI schema WDK", "schema publishing WDK WMI", "MOF files WDK WMI", "compiling MOF files"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Compiling a Driver's MOF File + + +## + + +To compile a MOF file that defines WMI data and event blocks, use the MOF compiler, called Mofcomp, that is included with the Microsoft Windows operating systems. Use the following syntax: + +``` + mofcomp -WMI -B:filename.bmf filename.mof +``` + +The following items appear in the preceding syntax: + +**-WMI** +Validates all classes in *filename.mof* for use with WMI. If any class definition is invalid, Mofcomp deletes the output file *filename.bmf*. If **-WMI** is omitted, you should run [Wmimofck](using-wmimofck-exe.md) on *filename.bmf* to validate the classes. A driver must either use the WMI switch or run Wmimofck to validate the MOF. Failure to do so can result in the MOF file not loading correctly into the WMI schema. + +**-B:***filename.bmf* +Requests that the compiler create a platform-independent binary version of the MOF file in *filename.bmf* without making any modifications to the CIMOM object repository. + +*filename.mof* +Specifies the name of the input MOF file. + +To learn more about how to use Mofcomp, open a Command Prompt window and type **mofcomp /?**. + +For more information about Mofcomp, see [MofComp](http://go.microsoft.com/fwlink/p/?linkid=51316) and other topics in the Windows SDK. + +To include the compiled MOF file as a resource in the driver's binary image, add the following line to the driver's resource script (RC) file: + +**MofResource MOFDATA** *filename.bmf* + +A driver specifies its MOF resource name in response to a registration request (an [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request with **Parameters.WMI.DataPath** set to WMIREGISTER): + +- If the driver is using the WMI library routines to handle WMI IRPs, it specifies the MOF resource name in its [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +- If the driver is handling WMI IRPs directly, it specifies the MOF resource name in the [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure that the driver passes to WMI. + +For more information about handling **IRP\_MN\_REGINFO** and **IRP\_MN\_REGINFO\_EX** requests, see [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +For more information about handling WMI IRPs using WMI iibrary routines, see [Handling WMI Requests](handling-wmi-requests.md). + +For more information about defining and including resources in executable files, see the Microsoft Windows SDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Compiling%20a%20Driver's%20MOF%20File%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/completing-irps-in-dispatch-routines.md b/windows-driver-docs-pr/kernel/completing-irps-in-dispatch-routines.md new file mode 100644 index 0000000000..bb6c26f4a4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/completing-irps-in-dispatch-routines.md @@ -0,0 +1,28 @@ +--- +title: Completing IRPs in Dispatch Routines +author: windows-driver-content +description: Completing IRPs in Dispatch Routines +ms.assetid: 279913cb-90f1-411f-a23a-38af4c99638d +--- + +# Completing IRPs in Dispatch Routines + + +## + + +This section describes completing IRPs in dispatch routines, and contains the following topics: + +[How to Complete an IRP in a Dispatch Routine](how-to-complete-an-irp-in-a-dispatch-routine.md) + +[When to Complete an IRP in a Dispatch Routine](when-to-complete-an-irp-in-a-dispatch-routine.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Completing%20IRPs%20in%20Dispatch%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/completing-irps.md b/windows-driver-docs-pr/kernel/completing-irps.md new file mode 100644 index 0000000000..f73cdea38d --- /dev/null +++ b/windows-driver-docs-pr/kernel/completing-irps.md @@ -0,0 +1,42 @@ +--- +title: Completing IRPs +author: windows-driver-content +description: Completing IRPs +ms.assetid: 4b4be95e-ebf5-4726-87fc-20c3e6c94f52 +keywords: ["IRPs WDK kernel , completing", "completing IRPs WDK kernel", "finished IRPs WDK kernel", "I/O WDK kernel , operation completed", "completing IRPs WDK kernel , about completing IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Completing IRPs + + +## + + +"Completing an IRP" is a shorthand phrase that means "allowing all members of the driver stack to complete an I/O operation." After the IRP has been completed, the I/O manager notifies the initiating application that the requested I/O operation has finished. + +When a driver has finished processing an IRP, it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) (typically from within a [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine). This causes the I/O manager to determine whether any higher-level drivers have set up [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines for the IRP. If so, each *IoCompletion* routine is called, in turn, until every layered driver in the chain has completed the IRP. + +When all drivers have completed the IRP, the I/O manager returns status to the original requester of the operation. Note that a higher-level driver that sets up a driver-created IRP must supply an *IoCompletion* routine to release the IRP it created. + +This section contains the following topics: + +[When to Complete an IRP](when-to-complete-an-irp.md) + +[Completing IRPs in Dispatch Routines](completing-irps-in-dispatch-routines.md) + +[Using IoCompletion Routines](using-iocompletion-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Completing%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/component-level-performance-management.md b/windows-driver-docs-pr/kernel/component-level-performance-management.md new file mode 100644 index 0000000000..b2602aae48 --- /dev/null +++ b/windows-driver-docs-pr/kernel/component-level-performance-management.md @@ -0,0 +1,55 @@ +--- +title: Component-Level Performance State Management +author: windows-driver-content +description: Starting with Windows 10, the power management framework (PoFx) enables a driver to define one or more sets of individually adjustable performance states for individual components within a device. +ms.assetid: D5341D6D-7C71-43CB-9C70-7E939B32C33F +--- + +# Component-Level Performance State Management + + +Starting with Windows 10, the power management framework (PoFx) enables a driver to define one or more sets of individually adjustable performance states for individual components within a device. The driver can use performance states to throttle a component's workload to provide just enough performance for its current needs. + +## Overview of Performance States + + +In Windows 8 and Windows 8.1, PoFx provides idle states (F-states) for component-level power savings by power and clock rail gating when a specific F-state is entered. This model saves power when a component is in an idle state (non-F0), but does not provide any mechanism for optimizing power usage or balancing it against performance needs when the component is active. Even though a component is active (in F0) and servicing a request, it may not require the full performance of the device. For example, a graphics card may need to only update a blinking cursor and this may not need full performance. + +Variable performance states address this issue by allowing the driver to throttle a device’s component to provide just enough performance for its current needs. In Windows 8 and Windows 8.1, if a component supports performance states, each driver must implement a proprietary performance state selection algorithm that is internal to the driver, and if needed, notify the platform extension plug-in (PEP) in a proprietary manner. The PEP is a software component that performs power management tasks that are specific to a particular product line of processor or System on a Chip (SoC) modules. Driver-specific proprietary performance state solutions have the disadvantage of being tightly coupled with the PEP, and cannot be easily debugged. + +Starting with Windows 10, PoFx provides an API for performance state management. This API has two main goals: + +- It provides a standard way for device drivers to notify the PEP about performance state changes so that the PEP may take the appropriate action. +- It provides a standard way for drivers to notify the OS of performance state changes for logging and analysis in Windows Performance Analyzer (WPA), without needing a custom plug-in for each driver. + +## Introduction to the PoFX API for Component-Level Performance States + + +PoFx enables a device to define the following types of performance states for each component: + +- A discrete number of states in the units of frequency (measured in Hz), bandwidth (measured in bits per second), or an opaque index number. +- A continuous distribution of states between a minimum and maximum value. + +Performance states are organized into sets and are registered on a per-component basis. Performance states within a set must increase monotonically. Most drivers are expected to define a single set of performance states per component. For example, a driver might define one set of performance states to control the clock frequency for a component. However, some drivers may need to define more than one performance state set to control multiple dimensions of performance states for a component. For example, a driver might define two sets of performance states to control the clock frequency and bus bandwidth. + +To register a device component for performance state management by PoFx, a driver follows these general steps: + +1. The driver registers the device components to be managed by PoFx. For more information, see [Component-Level Power Management](component-level-power-management.md). + +2. The driver registers support for performance states by calling [**PoFxRegisterComponentPerfStates**](https://msdn.microsoft.com/library/windows/hardware/dn939778). As part of the registration call, drivers can either define a given component’s performance state themselves or defer to the platform extension plug-in (PEP) to define them instead. + + Either the device driver or the PEP must hold knowledge of the performance states, including the number of performance state sets per component, the type of performance state (discrete or range-based), and the details of the values and count of the actual performance states. If the PEP does not support performance states, the driver may still register for performance state support with PoFx and notify the OS of performance state changes for logging and analysis in Windows Performance Analyzer (WPA). + + In either case, upon successful completion of [**PoFxRegisterComponentPerfStates**](https://msdn.microsoft.com/library/windows/hardware/dn939778), the driver has a [**PO\_FX\_COMPONENT\_PERF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn939832) structure that contains the registered performance state sets. + +3. When the driver decides a component should change performance states, it calls [**PoFxIssueComponentPerfStateChange**](https://msdn.microsoft.com/library/windows/hardware/dn939769) or [**PoFxIssueComponentPerfStateChangeMultiple**](https://msdn.microsoft.com/library/windows/hardware/dn939772). PoFx invokes the driver-provided [**ComponentPerfStateCallback**](https://msdn.microsoft.com/library/windows/hardware/dn939353) routine when the performance state change is complete. + +4. The driver is informed by the [**ComponentPerfStateCallback**](https://msdn.microsoft.com/library/windows/hardware/dn939353) routine whether the PEP succeeded or denied the performance state change. If the PEP succeeded the change, the driver then performs whatever work it needs to take to change the performance state from its perspective. If the PEP denied the change, the driver may choose to do nothing or retry the request again with the same or an alternate performance state. + +## Related topics +[Device Power Management Reference](https://msdn.microsoft.com/library/windows/hardware/hh450958) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Component-Level%20Performance%20State%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/component-level-power-management.md b/windows-driver-docs-pr/kernel/component-level-power-management.md new file mode 100644 index 0000000000..320b6ffa3a --- /dev/null +++ b/windows-driver-docs-pr/kernel/component-level-power-management.md @@ -0,0 +1,57 @@ +--- +title: Component-Level Power Management +author: windows-driver-content +description: Starting with Windows 8, the power management framework (PoFx) enables a driver to manage the power states of the individual components in a device. Component-level power management exists side-by-side with device-level power management. +ms.assetid: 77866143-FB10-4623-9923-368B23808715 +--- + +# Component-Level Power Management + + +Starting with Windows 8, the power management framework (PoFx) enables a driver to manage the power states of the individual components in a device. Component-level power management exists side-by-side with device-level power management. + +## Overview of Component-Level Power Management + + +Windows 7 and earlier versions of the operating system only provide support for device-level power management, which enables a driver to support D-states in a device. The Advanced Configuration and Power Interface (ACPI) specification defines [device power states](device-power-states.md) D0 (fully on) through D3 (fully off), and defines [system power states](system-power-states.md) S0 (fully on) through S5 (fully off). These versions of Windows do not provide mechanisms to independently manage the power supplied to the individual components in a device. In these versions of Windows, some drivers can implement custom power controls for components, but these controls typically add complexity to drivers, and might be feasible only if component power settings are controlled within the device. + +Starting with Windows 8, PoFx adds support for component-level power management. This enables a driver to support some number of component power states, F0, F1, and so on, where F0 is the fully on state. All components support the F0 state. The driver that is the power policy owner (PPO) for the components in a device is responsible for defining any additional, low-power Fx power states that a component might have. (Typically, the function driver for a device is the PPO.) This driver determines the number of low-power Fx states per component and the attributes of each Fx state. The Fx states that this driver defines might vary from component to component in the same device. + +PoFx provides a device driver interface (DDI) through which a driver can supply status and capabilities information about the components in a device. This information includes the current activity level of each component, the time required by the component to change from one power state to another, and the amount of latency that can be tolerated by clients of the device when the component wakes from a low-power state. In addition, PoFx obtains system-wide information about the power and clock domains to which the component belongs. (The devices in a particular power domain share a common power rail; the devices in a particular clock domain share a common clock signal.) + +Based on this information, PoFx makes intelligent decisions about when a component should enter a low-power state and which low-power state to enter. The decision process involves information from other components and other devices, and takes into account the dependencies between the devices and components in the various power and clock domains. + +## Introduction to the PoFX API for Component-Level Power Management + + +To register a device to be managed by PoFx, the driver calls the [**PoFxRegisterDevice**](https://msdn.microsoft.com/library/windows/hardware/hh439521) routine. The driver passes this routine a [**PO\_FX\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/hh439585) structure that, among other data, contains an array of [**PO\_FX\_COMPONENT**](https://msdn.microsoft.com/library/windows/hardware/hh439575) structures. Each element in this array describes the Fx power states of a component in the device and the attributes of each Fx state. (At minimum, a component that does not support component-level power management implements only the F0 state.) The attributes of a particular Fx power state in a particular component are described by a [**PO\_FX\_COMPONENT\_IDLE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh439581) structure, which contains the following values: + +- The transition latency, which is the time required to make a transition from this Fx state to the F0 (fully on) state. +- The residency requirement, which is the time that a component must spend in this Fx state to make a transition to the state worthwhile. +- The nominal power, which is the power that is consumed by the component in this Fx state. + +PoFx uses this information (in addition to other system-wide inputs and dependencies) to make intelligent decisions about which Fx power state a component should be in at any particular time. PoFx must balance two competing objectives. First, a component that is idle should be configured to consume as little power as possible. Second, a component must be prepared to switch from a low-power Fx state to F0 quickly enough to maintain the appearance of a device that is always on and always connected. + +Component-level power management can be performed only when a device is in the D0 (fully on) power state. When a device is in the D1 (almost on), D2 (almost off), or D3 power state, the device is inaccessible. When the device is in the D0 state, only components that the driver is actively using need to remain in the F0 state. Idle components can potentially switch to low-power Fx states to reduce power consumption. + +While a device is in the D0 power state, the driver follows a simple protocol to enable component-level power management. When the driver needs to access a component, the driver calls the [**PoFxActivateComponent**](https://msdn.microsoft.com/library/windows/hardware/hh406650) routine to request access to the component. If the component is in a low-power Fx state when this call occurs, PoFx initiates a transition to the F0 state and notifies the driver when this transition is complete. The driver can then access the component. When the driver no longer needs to access the component, the driver calls the [**PoFxIdleComponent**](https://msdn.microsoft.com/library/windows/hardware/hh406717) routine to notify PoFx. In response to this call, PoFx can potentially switch the component to a low-power Fx state. + +A component that is accessible is in the *active condition*. A component that is inaccessible is in the *idle condition*. To track the accessibility of the components in a device, PoFx maintains an activation reference count on each component. A **PoFxActivateComponent** call increments the count on the specified component by one, and a **PoFxIdleComponent** call decrements the count by one. + +If a **PoFxActivateComponent** call increments the count from zero to one, PoFx initiates a transition from the idle condition to the active condition, and notifies the driver when this transition completes. If a **PoFxActivateComponent** occurs when the component is already in the active condition, the component stays in the active condition and the driver receives no notification. + +If a **PoFxIdleComponent** call decrements the count from one to zero, PoFx initiates a transition from the active condition to the idle condition, and notifies the driver when this transition is complete. If a **PoFxIdleComponent** call decrements the count but the count remains nonzero, the component stays in the active condition and the driver receives no notification. + +The activation reference count conveniently handles situations in which two or more code paths in the same driver might need to concurrently access the same component in a device. By maintaining this count, PoFx enables the various parts of the driver to independently maintain access to the component without requiring the driver to centrally manage access to the component. + +The active/idle condition of a component is the only reliable means for a driver to determine whether a component is accessible. A component that is in the F0 power state but is in the idle condition might be about to switch to a low-power Fx state. + +A component that is in the active condition is always in the F0 state. The component cannot leave F0 until it enters the idle condition. A component that is in the idle condition might be in F0 or in a low-power Fx state. If a component is in a low-power Fx state when a **PoFxActivateComponent** call initiates a transition from the idle condition to the active condition, PoFx must first switch the component to F0 before the component can enter the active condition. + +## Related topics +[Device Power Management Reference](https://msdn.microsoft.com/library/windows/hardware/hh450958) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Component-Level%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/compute-pages-spanned.md b/windows-driver-docs-pr/kernel/compute-pages-spanned.md new file mode 100644 index 0000000000..ce3d7619bc --- /dev/null +++ b/windows-driver-docs-pr/kernel/compute-pages-spanned.md @@ -0,0 +1,42 @@ +--- +title: Windows kernel obsolete macros +author: windows-driver-content +description: This topic summarizes the following obsolete macros +ms.assetid: b102355e-f40b-438e-92ef-371814e0c074 +--- + +# Windows kernel obsolete macros + + +This topic summarizes the following obsolete macros: + + ++++ + + + + + + + + + + + + +
MacroDescription
COMPUTE_PAGES_SPANNED

Use [ADDRESS_AND_SIZE_TO_SPAN_PAGES](https://msdn.microsoft.com/library/windows/hardware/ff540562) instead.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20obsolete%20macros%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/configurable.md b/windows-driver-docs-pr/kernel/configurable.md new file mode 100644 index 0000000000..ce97de75bf --- /dev/null +++ b/windows-driver-docs-pr/kernel/configurable.md @@ -0,0 +1,54 @@ +--- +title: Configurable +author: windows-driver-content +description: Configurable +ms.assetid: 0dcdc2eb-0a27-4739-be9d-48a0382347cf +keywords: ["hardware-configurable devices WDK kernel", "software-configurable drivers WDK kernel", "configurable devices and drivers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Configurable + + +## + + +Today's peripheral devices must be *hardware-configurable*, and their drivers must be *software-configurable*. + +A device is hardware-configurable if it can accept different assignments of the system's hardware resources, such as I/O port numbers, without being physically modified. For example, if a set of hot-pluggable Plug and Play disks are connected in a redundant array of independent disks (RAID) configuration, a user can swap disks while the system is running. If a device is hardware-configurable, its drivers cannot contain hard-coded, system-dependent values for the device's hardware resources. + +A driver is software-configurable if: + +- It can receive and change its device's hardware resources dynamically. + + Drivers that support Plug and Play do not contain hard-coded values for a device's hardware resources, nor does the driver poll the device to determine its resource assignments. Instead, the system dynamically assigns resources to the device, and then supplies resource values to the driver. + +- It was written with no assumptions about other drivers that might reside above or below it in its driver stack. + + For example, the design of a lower-level device driver for a disk must be flexible enough to support multiple file systems that are implemented by multiple high-level file system drivers, possibly on a single computer. + + Additionally, if a computer has sufficient mass storage capacity, that same lower-level disk driver must not interfere with an intermediate driver's support for fault tolerance (implemented as mirrored partitions, stripe sets, or volume sets) within a file system. + +The PnP manager and each PnP hardware bus driver work together to provide an interface between the platform's hardware for a specific type of I/O bus and the system's software. The PnP manager builds a [device tree](device-tree.md), with nodes that represent all the devices on the system, including buses. For each device, the PnP manager maintains two lists: + +- A list of the [hardware resources](hardware-resources.md) that the device is capable of using. + +- A list of the hardware resources that are actually assigned to the device. + +Device drivers assist the PnP manager in creating these lists, which are maintained in the registry. As devices are added to and removed from the system, the PnP manager reassigns resources as necessary and updates the lists. + +The system's hardware abstraction layer (HAL) component, which is implemented as a dynamic-link library, is responsible for some of the hardware-level, platform-specific support that is needed by other system components, including kernel-mode drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Configurable%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/controllercontrol-routine-requirements.md b/windows-driver-docs-pr/kernel/controllercontrol-routine-requirements.md new file mode 100644 index 0000000000..3caec99775 --- /dev/null +++ b/windows-driver-docs-pr/kernel/controllercontrol-routine-requirements.md @@ -0,0 +1,68 @@ +--- +title: ControllerControl Routine Requirements +author: windows-driver-content +description: ControllerControl Routine Requirements +ms.assetid: b311c0b0-f7b1-4276-a165-5c658657b198 +keywords: ["controller objects WDK kernel , writing ControllerControl routines", "ControllerControl routines, writing", "ControllerControl routines, requirements"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ControllerControl Routine Requirements + + +## + + +As its name implies, a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine is associated with a controller object. When the *ControllerControl* routine executes, the hardware represented by the controller object is free and the controller extension generally is not being accessed by another driver routine unless the controller extension contains context that is shared with the driver's ISR. + +Usually, a *ControllerControl* routine does at least the following: + +1. Updates or initializes whatever context the driver maintains in the device extension of the target device object and in the controller extension + + If the driver uses DMA, its *ControllerControl* routine usually is responsible for determining whether a given transfer request must be split up into partial transfers due to any system-imposed or device-imposed limitations on the size of each DMA transfer. In these circumstances, the *ControllerControl* routine also is responsible for calling [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) if the driver has an *AdapterControl* routine. + + If the driver uses PIO, its *ControllerControl* routine also is responsible for [splitting transfer requests](splitting-dma-transfer-requests.md), if its hardware requires it, into partial-transfer ranges and for calling [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) with the MDL at **Irp->MdlAddress**. + +2. Programs its hardware for the requested I/O operation + + If the device or controller extension can be accessed from the ISR, the *ControllerControl* routine must use a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that is invoked by calling [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302). For more information, see [Using Critical Sections](using-critical-sections.md). + +If the driver has a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine, its *ControllerControl* routine also must check the **Irp->Cancel** field to determine whether the current IRP should be canceled, and do either of the following: + +If **Irp->Cancel** is set to **TRUE**, the *ControllerControl* routine must do the following: + +1. Set STATUS\_CANCELLED for **Status** and zero for **Information** in the I/O status block of the IRP. + +2. Call [**IoFreeController**](https://msdn.microsoft.com/library/windows/hardware/ff549104) to release the controller object so the next device operation can be started promptly. + +3. Call [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) or dequeue the next IRP if the driver manages its own queuing. + +4. Complete the canceled IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) and return control. + +If **Irp->Cancel** is not set to **TRUE**, the *ControllerControl* routine instead must do the following: + +1. Call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to reset the *Cancel* routine entry point for the IRP to **NULL**. Acquire the cancel spin lock for this call if the driver uses the I/O manager-supplied device queue in the device object. + +2. Program the hardware for the requested I/O operation, using a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that is invoked by calling [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302). For more information, see [Using Critical Sections](using-critical-sections.md) + +For more information about handling cancelable IRPs, see [Canceling IRPs](canceling-irps.md). + +For most interrupt-driven I/O operations except overlapped operations on different devices attached to the physical controller/adapter, a *ControllerControl* routine should return **KeepObject** because the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine completes the operation and the IRP. + +As soon as the I/O operation(s) to satisfy the current request are done, the routine that will complete the IRP should call **IoFreeController** and **IoStartNextPacket** so that the next request can be processed as quickly as possible. + +If the *ControllerControl* routine itself completes an IRP or if it can set up an operation, such as a disk seek, for one target device object (disk) that could be overlapped with an operation for another device object, the *ControllerControl* routine should return **DeallocateObject**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20ControllerControl%20Routine%20Requirements%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/controlling-device-access.md b/windows-driver-docs-pr/kernel/controlling-device-access.md new file mode 100644 index 0000000000..8cb286a66e --- /dev/null +++ b/windows-driver-docs-pr/kernel/controlling-device-access.md @@ -0,0 +1,70 @@ +--- +title: Controlling Device Access +author: windows-driver-content +description: Controlling Device Access +ms.assetid: b5e562ad-573b-4b0f-9d85-2410fda16e4e +keywords: ["device objects WDK kernel , security", "security WDK device objects", "device access controls WDK kernel", "non-WDM driver device access WDK kernel", "security descriptors WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Device Access + + +## + + +Access to a device is controlled by a security descriptor (and the ACL it contains). A security descriptor for a device object can be specified when the device object is created, or set in the registry. + +### Controlling Device Access for WDM Drivers + +When a WDM driver (other than certain bus drivers) creates a device object, the Plug and Play manager determines a security descriptor for the device. The order of operations is as follows. + +1. The PnP manager calls the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +2. The driver's *AddDevice* routine calls [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) to create the device object and attach it to the device object stack. + +3. The PnP manager updates the security descriptor for the newly-created device object. + +For a WDM driver, the PnP manager determines the security descriptor for the device object as follows. + +1. If the device has a security descriptor setting in the registry, it is applied to every object in the device stack. + +2. Otherwise, if the device's setup class has a security descriptor setting in the registry, it is applied to every object in the device stack. + +3. Otherwise, the PnP manager leaves the default security descriptor for each object unchanged. In this case, the default security descriptor for the stack is determined by the device type and device characteristics of the PDO. + +For most device types and characteristics, the default security descriptor gives full access (GENERIC\_ALL) to administrators, and read, write, and execute access (GENERIC\_READ | GENERIC\_WRITE | GENERIC\_EXECUTE) access to everyone else. + +For more information about how to set a security descriptor for a device or device setup class in the registry, see [Setting Device Object Properties in the Registry](setting-device-object-properties-in-the-registry.md). + +If a device is operated in raw mode, then the PnP manager cannot determine a security descriptor for the device object. In that case, the bus driver must provide a security descriptor; see below. + +### Controlling Device Access for WDM Bus Drivers + +A WDM bus driver must provide a security descriptor for the PDO of every device that can be operated in raw mode. Use [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) to create the device object with a security descriptor. + +If the bus driver does not operate a device in raw mode, then it is not required to supply a security descriptor. The PnP manager determines the security descriptor, as described above. The bus driver can supply a security descriptor if it must ensure that its PDOs have stricter security settings than the default descriptor. Any descriptor specified by the bus driver is overridden by settings in the registry. + +For more information about creating device objects, see [Creating a Device Object](creating-a-device-object.md). + +### Controlling Device Access for Non-WDM Drivers + +Non-WDM drivers must specify a default security descriptor and class GUID for any named device objects they create. + +Use the **IoCreateDeviceSecure** routine to create the named device object and to specify the default security descriptor and class GUID for that device. The security descriptor is specified in a subset of SDDL. For more information, see [SDDL for Device Objects](sddl-for-device-objects.md). + +The system overrides the default security descriptor with any security settings in the registry for the specified class GUID. The driver must specify its own unique GUID for the device. Use the GuidGen tool to generate a unique GUID. (GuidGen is included in the Microsoft Windows SDK.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Controlling%20Device%20Access%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/controlling-device-namespace-access.md b/windows-driver-docs-pr/kernel/controlling-device-namespace-access.md new file mode 100644 index 0000000000..4ef7d43ace --- /dev/null +++ b/windows-driver-docs-pr/kernel/controlling-device-namespace-access.md @@ -0,0 +1,50 @@ +--- +title: Controlling Device Namespace Access +author: windows-driver-content +description: Controlling Device Namespace Access +ms.assetid: e5312297-849f-4b4e-835d-0ce5295c7ce2 +keywords: ["device objects WDK kernel , security", "security WDK device objects", "device namespace access WDK kernel", "namespaces WDK device objects", "file open requests WDK device objects", "open requests WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Controlling Device Namespace Access + + +## + + +In the Windows Driver Model (WDM), every device object has an associated *namespace*. Names in the device's namespace are paths that begin with the device's name. For a device named "\\*Device*\\*DeviceName*", its namespace consists of any name of the form "\\*Device*\\*DeviceName*\\*FileName*". (For a file system, *FileName* is an actual name of a file on the file system.) + +A WDM driver receives open requests for all names in the device's namespace. The driver treats an open request for "\\*Device*\\*DeviceName*" as an open of the device object itself. If the driver implements support for open requests into the device's namespace, then it treats an open request for "\\*Device*\\*DeviceName*\\*FileName*" as an open of a "file" within the device object's namespace (where the notion of "file" for the device is driver-determined). + +Most drivers do not implement support for open operations into the device's namespace, but all drivers must provide security checks to prevent unauthorized access to the device's namespace. By default, security checks for file open requests within the device's namespace, (for example, "\\*Device*\\*DeviceName*\\*FileName*") are left entirely up to the driver—the device object ACL is not checked by the operating system. + +If a device object's FILE\_DEVICE\_SECURE\_OPEN characteristic is set, the system applies the device object's security descriptor to all file open requests in the device's namespace. Drivers can set FILE\_DEVICE\_SECURE\_OPEN when they create the device object with [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) or [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407). For WDM drivers, FILE\_DEVICE\_SECURE\_OPEN can also be set in the registry. It can also be set in the registry for device objects of non-WDM drivers that are created by **IoCreateDeviceSecure**. For more information about setting device object properties, such as the device characteristics, in the registry, see [Setting Device Object Properties in the Registry](setting-device-object-properties-in-the-registry.md). For more information about device characteristics, see [Specifying Device Characteristics](specifying-device-characteristics.md). + +Drivers for devices that do not support namespaces must use one of two methods to ensure that file open requests within the device's namespace are handled correctly: + +- The driver's device objects have the FILE\_DEVICE\_SECURE\_OPEN device characteristic set. The driver can then treat any open request into the device's namespace as an open request for the device object. + +- The driver can fail any [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) requests that specify an **IrpSp->FileObject->FileName** parameter whose length is nonzero. In this case, open requests for the device are subject to the system's ACL check, while all file open requests within the device's namespace are failed by the driver. (Drivers that support exclusive opens must use this option.) + +Drivers for devices that do support namespaces can also use two methods to secure file open requests into the device's namespace: + +- The driver's device objects have the FILE\_DEVICE\_SECURE\_OPEN device characteristic set. This ensures that the security settings for the device apply uniformly to the device's namespace. (The driver is responsible for implementing support for the namespace in its [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) routine.) + +- The driver checks any ACLs for the file name in its *DispatchCreate* routine. (Even in this case the driver should set the FILE\_DEVICE\_SECURE\_OPEN characteristic unless opens into the device's namespace can have weaker security settings than the device object.) + +The FILE\_DEVICE\_SECURE\_OPEN characteristic is checked at the top of the stack, so filter device objects must copy the **Characteristics** member of the next-lower device object after attaching. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Controlling%20Device%20Namespace%20Access%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/converting-an-ordinary-dpc-to-a-threaded-dpc.md b/windows-driver-docs-pr/kernel/converting-an-ordinary-dpc-to-a-threaded-dpc.md new file mode 100644 index 0000000000..43b0ef4b26 --- /dev/null +++ b/windows-driver-docs-pr/kernel/converting-an-ordinary-dpc-to-a-threaded-dpc.md @@ -0,0 +1,65 @@ +--- +title: Converting an Ordinary DPC to a Threaded DPC +author: windows-driver-content +description: Converting an Ordinary DPC to a Threaded DPC +ms.assetid: 89a7a408-e01b-4543-9775-5ef542d05b75 +keywords: ["threaded DPCs WDK kernel", "converting DPCs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Converting an Ordinary DPC to a Threaded DPC + + +## + + +Converting an ordinary DPC to a threaded DPC is straightforward. Simply replace the call to [**KeInitializeDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552130) (which initializes the DPC) with one to [**KeInitializeThreadedDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552166), and refer to the following table to replace the calls inside the DPC routine that acquire and release spin locks. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Ordinary DPC callCorresponding threaded DPC call

[KeAcquireSpinLockAtDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff551921)

[KeAcquireSpinLockForDpc](https://msdn.microsoft.com/library/windows/hardware/ff551923)

[KeReleaseSpinLockFromDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff553150)

[KeReleaseSpinLockForDpc](https://msdn.microsoft.com/library/windows/hardware/ff553148)

[KeAcquireInStackQueuedSpinLockAtDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff551908)

[KeAcquireInStackQueuedSpinLockForDpc](https://msdn.microsoft.com/library/windows/hardware/ff551912)

[KeReleaseInStackQueuedSpinLockFromDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff553137)

[KeReleaseInStackQueuedSpinLockForDpc](https://msdn.microsoft.com/library/windows/hardware/ff553133)

+ +  + +You do not need to change calls to other spin lock routines, such as [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) or [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Converting%20an%20Ordinary%20DPC%20to%20a%20Threaded%20DPC%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/counters.md b/windows-driver-docs-pr/kernel/counters.md new file mode 100644 index 0000000000..536dbce6b9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/counters.md @@ -0,0 +1,42 @@ +--- +title: Counters +author: windows-driver-content +description: Counters +ms.assetid: dd4cb793-64c4-4f66-b9cb-e97dd94fbb21 +keywords: ["synchronization WDK kernel , counters", "counters WDK kernel", "count values WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Counters + + +## + + +The system provides several driver support routines that return various count values. + +[**KeQuerySystemTime**](https://msdn.microsoft.com/library/windows/hardware/ff553068) + +[**KeQueryInterruptTime**](https://msdn.microsoft.com/library/windows/hardware/ff553025) + +[**KeQueryInterruptTimePrecise**](https://msdn.microsoft.com/library/windows/hardware/dn903729) + +[**KeQueryTickCount**](https://msdn.microsoft.com/library/windows/hardware/ff553071) + +[**KeQueryPerformanceCounter**](https://msdn.microsoft.com/library/windows/hardware/ff553053) + +[**KeQueryTimeIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff553075) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Counters%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-a-device-object.md b/windows-driver-docs-pr/kernel/creating-a-device-object.md new file mode 100644 index 0000000000..e5ecbf2a5b --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-a-device-object.md @@ -0,0 +1,76 @@ +--- +title: Creating a Device Object +author: windows-driver-content +description: Creating a Device Object +ms.assetid: 3eda8eb2-8a83-4753-a099-2531bfb9aeeb +keywords: ["device objects WDK kernel , creating", "non-WDM driver device objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Device Object + + +## + + +A monolithic driver must create a device object for each physical, logical, or virtual device for which it handles I/O requests. A driver that does not create a device object for a device does not receive any IRPs for the device. + +In some technology areas, a minidriver that is associated with a class driver or port driver does not have to create its own device objects. Instead, the class or port driver creates the device object, and receives all IRPs for the device. The class or port driver then uses a driver-specific method to pass the I/O request to the minidriver. See the documentation for your particular technology area to determine if Microsoft supplies a class or port driver that creates device objects on behalf of your driver. + +Drivers call either [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) or [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) to create their device objects. For more information about which routine to use, see the following sections. + +[Creating Device Objects for WDM Function and Filter Drivers](#creating-device-objects-for-wdm-function-and-filter-drivers) + +[Creating Device Objects for WDM Bus Drivers](#creating-device-objects-for-wdm-bus-drivers) + +[Creating Device Objects for Non-WDM Drivers](#creating-device-objects-for-non-wdm-drivers) + +When the driver creates a device object, it supplies the following information to **IoCreateDevice** or **IoCreateDeviceSecure**: + +- The size of the device's *device extension*. The device extension is a system-allocated storage area that the driver can use for device-specific storage. For more information, see [Device Extensions](device-extensions.md). + +- A system-defined constant, indicating the **DeviceType** represented by the device object. For more information, see [Specifying Device Types](specifying-device-types.md). + +- One or more ORed, system-defined constants that indicate the device characteristics for the device. For more information, see [Specifying Device Characteristics](specifying-device-characteristics.md). + +- A Boolean value, named *Exclusive*, that specifies whether a bit in the device object's **Flags** should be set with DO\_EXCLUSIVE, indicating the driver services an exclusive device, such as a video, serial, parallel, or sound device. WDM drivers must set *Exclusive* to **FALSE**. For more information, see [Specifying Exclusive Access to Device Objects](specifying-exclusive-access-to-device-objects.md). + +- A pointer to the driver object for the driver. A WDM function or filter driver receives a pointer to its driver object as a parameter to its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. All drivers receive a pointer to their driver object in their [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. The system uses this pointer to associate the driver with its device object. + +- An optional pointer to a null-terminated Unicode string (*DeviceName*) naming the device. WDM drivers, other than bus drivers, do not supply a device name; doing so bypasses the PnP manager's security features. For more information, see [Named Device Objects](named-device-objects.md). + +If the call to [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) or [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) succeeds, the I/O manager provides storage for the device object itself and for all other data structures associated with the device object, including the device extension, which it initializes with zeros. + +### Creating Device Objects for WDM Function and Filter Drivers + +WDM drivers, other than bus drivers, call **IoCreateDevice** to create their device objects. Most WDM drivers create their device objects from within their *AddDevice* routines. Some drivers, such as disk drivers that must respond to drive layout IOCTLs, call **IoCreateDevice** from a dispatch routine. + +Unless device type-specific sections of the Windows Driver Kit (WDK) documentation state otherwise, your driver should create its device objects in its *AddDevice* routine. For more information, see [Writing an AddDevice Routine](writing-an-adddevice-routine.md). + +### Creating Device Objects for WDM Bus Drivers + +A WDM bus driver creates a PDO when it is enumerating a new device in response to an [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) request, if the relation type is **BusRelations**. + +The following rules determine if a bus driver calls **IoCreateDevice** or **IoCreateDeviceSecure** to create a device object: + +- If a device can be used in [*raw mode*](https://msdn.microsoft.com/library/windows/hardware/ff556331#wdkgloss-raw-mode), then it must call **IoCreateDeviceSecure**. + +- If the device is not raw-mode capable, then the bus driver can use either **IoCreateDevice** or **IoCreateDeviceSecure**. **IoCreateDevice** can be used when the default system security for devices on the bus is adequate; **IoCreateDeviceSecure** can be used to specify a more stringent security descriptor. For more information, see [Controlling Device Access](controlling-device-access.md). + +### Creating Device Objects for Non-WDM Drivers + +A non-WDM driver uses **IoCreateDevice** to create unnamed device objects, and **IoCreateDeviceSecure** to create named device objects. Note the unnamed device objects of a non-WDM driver are not accessible from user mode, so the driver usually must create at least one named object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20a%20Device%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-a-resource-manager.md b/windows-driver-docs-pr/kernel/creating-a-resource-manager.md new file mode 100644 index 0000000000..e9de967fa6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-a-resource-manager.md @@ -0,0 +1,132 @@ +--- +title: Creating a Resource Manager +author: windows-driver-content +description: Creating a Resource Manager +ms.assetid: b2841d56-650a-487c-a002-2521cd1b461b +keywords: ["resource managers WDK KTM , creating resource managers", "enlistments WDK KTM , read-only enlistments", "read-only enlistments WDK KTM", "resource managers WDK KTM , volatile resource managers", "volatile resource managers WDK KTM", "resource managers WDK KTM , adding to a TPS", "transaction processing systems WDK KTM , adding resource managers", "TPS WDK KTM , adding resource managers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Resource Manager + + +[*Resource managers*](transaction-processing-terms.md#ktm-term-resource-manager) maintain each transaction's data and log the transaction's operations. If a transaction processing system (TPS) has multiple resource managers, each resource manager can participate in each transaction's commit, rollback, and recovery operations. + +Each resource manager must export an interface that transactional clients can use to access the database or other resource that the resource manager maintains. + +Typically, a kernel-mode resource manager must perform the following tasks in the listed order: + +1. Create a log stream. + + Resource managers can use the [Common Log File System](using-common-log-file-system.md) (CLFS), or some other logging capability, to maintain their log streams. A call to [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) creates a CLFS log stream. The resource manager must use the log stream to record any information that it requires to commit, roll back, or recover transactions. In addition, KTM uses the log stream to record any internal state changes that might be necessary to recover transactions. + +2. Create a transaction manager object. + + A call to [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430) creates a transaction manager object and connects the resource manager to an additional CLFS log stream that the resource manager specifies. + +3. Recover the transaction manager state. + + A call to [**ZwRecoverTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567079) reads the transaction manager object's log stream (which KTM maintains) and determines whether the TPS was shut down before all transactions were completed (for example, because the system crashed). KTM restores its internal state based on information in the log stream. + +4. Create a resource manager object. + + A call to [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427) creates a resource manager object and associates it with the previously created transaction manager object. + +5. Recover the resource manager state. + + A call to [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078) causes KTM to send the resource manager TRANSACTION\_NOTIFY\_RECOVER notifications for any transactions that were in progress the last time that the resource manager shut down. For information about how the resource manager should respond to these notifications, see [Handling Recovery Operations](handling-recovery-operations.md). + +6. Receive transactions from clients. + + Typically, a client creates a transaction object and uses the resource manager's client interface to pass the transaction object's GUID to the resource manager. For example, the resource manager might provide a *CreateDataObject* routine that is similar to the one that the [Understanding TPS Components](understanding-tps-components.md) topic describes. + +7. Enlist in each transaction. + + A call to [**ZwOpenTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567033) opens a handle to the transaction object, and then a call to [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) creates an enlistment for the transaction. The enlistment enables the resource manager to receive a specified set of [transaction notifications](transaction-notifications.md). + +8. Enable reception of transaction notifications. + + The resource manager can call [**ZwGetNotificationResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566467) to obtain notifications synchronously, or it can call [**TmEnableCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff564676) to register a *ResourceManagerNotification* callback routine that KTM calls whenever a notification is available. + +9. Service resource access requests from clients, but do not make the changes permanent. + + After a client has created a transaction object, it typically calls the resource manager's interface to access the resource manager's resource. For example, a resource manager for a database might receive requests to read from and write to the database. + + The resource manager must record the results of the read and write operations in a [CLFS log stream](using-log-streams-with-ktm.md) or other logging capability until it receives a notification that the transaction's operations will be committed, rolled back, or recovered. + +10. Commit or roll back client operations. + + Eventually, the resource manager receives a notification to begin committing or rolling back the operations that the client has performed. In response, the resource manager must either make the client operations permanent or discard them. For more information about how to handle commit and rollback notifications, see [Handling Transaction Operations](handling-transaction-operations.md). + + Occasionally, a resource manager might have to try to force KTM to quickly provide a commit or rollback notification, perhaps because the resource manager has determined that a device was surprise-removed. In such a case, the resource manager can call [**TmRequestOutcomeEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff564727). + +11. Close the enlistment object handle. + + After the resource manager has finished processing the transaction, it must call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the enlistment object's handle + +12. Close the resource manager object handle and the transaction manager object handle. + + Before the resource manager unloads, it must call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the resource manager object's handle and the transaction manager object's handle. + +Steps 1 through 5 must be performed in your resource manager's initialization code. For example, if your resource manager is a kernel-mode driver, the initialization code is the driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. + +Steps 6 through 11 are typically performed in code that responds to requests from transactional clients. + +Step 12 must be performed in your resource manager's final clean-up code, such as a kernel-mode driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine. + +## Creating a Read-Only Enlistment + + +A *read-only enlistment* is an enlistment that does not receive any notifications from KTM. A resource manager can make any enlistment read-only by calling [**ZwReadOnlyEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567074). This call causes KTM to stop delivering notifications to the resource manager. + +After your resource manager has called [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422), it can call **ZwReadOnlyEnlistment** at any time up to the point at which it would ordinarily call [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037). + +There are two reasons why you might want your resource manager to call **ZwReadOnlyEnlistment**. + +- Your resource manager has been participating in a transaction and, at some point before it receives a TRANSACTION\_NOTIFY\_COMMIT notification, the resource manager determines that it no longer has to participate in the transaction's commit operation. + + For example, when the resource manager receives a TRANSACTION\_NOTIFY\_PREPARE notification, it might determine that none of the transaction's operations have changed the resource manager's database. The resource manager can call **ZwReadOnlyEnlistment** instead of **ZwPrepareComplete** to remove itself from the transaction. + +- Your resource manager never participates in any transaction's commit operation. + + For example, your resource manager might monitor data that the client sends, without modifying any stored database. In this case, your resource manager might call **ZwReadOnlyEnlistment** immediately after it has called **ZwCreateEnlistment**. In addition, you might choose to make such a resource manager *volatile*, as described in the next section of this topic. + +After a resource manager has called **ZwReadOnlyEnlistment**, it can call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the enlistment handle. + +## Creating a Volatile-Resource Manager + + +A *volatile-resource manager* is a resource manager that does not maintain durable data. For example, you might create a volatile-resource manager to monitor data that the client sends, if the resource manager does not modify a durably stored database. Volatile-resource managers typically do not log transaction activity and therefore cannot perform recovery or rollback operations. + +A volatile-resource manager must set the RESOURCE\_MANAGER\_VOLATILE flag when it calls [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427). If this flag is set, KTM does not log any information about the resource manager in the log stream of the associated transaction manager object. + +Your resource manager can also set a TRANSACTION\_MANAGER\_VOLATILE flag when it calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430). If this flag is set, KTM does not create a log stream for the transaction manager object. In addition, any additional resource managers that are connected to the transaction manager object must also be volatile and set the RESOURCE\_MANAGER\_VOLATILE flag. + +## Adding a Resource Manager to an Existing TPS + + +If you have to add an additional resource manager to an existing TPS, you have two choices: + +- Your new resource manager calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430) to create its own transaction manager object. + + Use this choice if your resource manager does not communicate with other resource managers in the TPS. + +- Your new resource manager calls [**ZwOpenTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567035) to connect to an existing transaction manager object. + + Use this choice if your resource manager must communicate with other resource managers in the TPS. The resource manager that calls **ZwCreateTransactionManager** must share the transaction manager object's GUID, log stream name, or object name so that other resource managers can call **ZwOpenTransactionManager**. These other resource managers can call [**ZwQueryInformationTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567058) to obtain additional information about the transaction manager object. + +After you have added your resource manager to the TPS, clients that are aware of your resource manager can call the resource manager's client interface. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20a%20Resource%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-a-superior-transaction-manager.md b/windows-driver-docs-pr/kernel/creating-a-superior-transaction-manager.md new file mode 100644 index 0000000000..c1024ac61b --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-a-superior-transaction-manager.md @@ -0,0 +1,59 @@ +--- +title: Creating a Superior Transaction Manager +author: windows-driver-content +description: Creating a Superior Transaction Manager +ms.assetid: 6f6bf61a-fe53-47b5-9559-f76334969af8 +keywords: ["transaction managers WDK KTM", "superior transaction managers WDK KTM", "enlistments WDK KTM , superior enlistments", "superior enlistments WDK KTM", "enlistments WDK KTM , subordinate enlistments", "subordinate enlistments WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Superior Transaction Manager + + +In KTM, a *superior transaction manager* is a resource manager that creates superior enlistments for the transactions that it participates in. A *superior enlistment* is an enlistment that grants the resource manager the ability to coordinate the [commit operation](handling-commit-operations.md) for the enlistment's transaction. In other words, either a transactional client or the superior transaction manager can start the pre-prepare/prepare/commit sequence for the transaction. + +After a resource manager has created a superior enlistment for a transaction, KTM rejects all calls to [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) for the transaction. Therefore, transactional clients cannot commit such a transaction. Instead, the resource manager that created the superior enlistment must call [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044), [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039), and [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419). + +### When to Create a Superior Transaction Manager + +Suppose that you want to integrate a transaction processing system (TPS) component with KTM, but the component contains its own non-KTM transaction management capabilities that clients can call. In such a situation, you might have to create a superior transaction manager. + +For example, suppose that your component provides its own interfaces that clients use to create and commit transactions. Because your component's clients do not call KTM to create or commit transactions, your component must become a superior transaction manager when you integrate it into a KTM-based TPS. + +### How to Create a Superior Transaction Manager + +If you want your component to be a superior transaction manager, it must do the following: + +1. Call [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427) to register as a resource manager. + +2. Call [**ZwCreateTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566429) every time that a client of your component creates a transaction by using your component's client interface. + +3. Call [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422), setting the ENLISTMENT\_SUPERIOR flag, and specifying both the ENLISTMENT\_SUPERIOR\_RIGHTS and ENLISTMENT\_SUBORDINATE\_RIGHTS access flags. + +4. Call [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044), [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039), and [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419) when your component's client calls your component's client interface to commit the transaction. + +KTM permits only one superior enlistment per transaction. Other resource managers can create additional enlistments. These enlistments are called *subordinate enlistments* because they cannot initiate the commit operation. + +To roll back a superior enlistment, your superior transaction manager calls [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083). + +To recover a superior enlistment, your superior transaction manager calls [**ZwRecoverEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567075). + +When a superior transaction manager commits, rolls back, or recovers a transaction, KTM sends [transaction notifications](transaction-notifications.md) to all subordinate enlistments so that they can participate. + +A TPS that includes a superior transaction manager cannot use [single-phase commit operations](handling-commit-operations.md#single-phase-commit-operations). + +During a recovery operation, if KTM cannot determine the outcome of a transaction, it sends a TRANSACTION\_NOTIFY\_RECOVER\_QUERY notification to the superior transaction manager. In response, the superior transaction manager must call **ZwCommitEnlistment** if the transaction can be committed or **ZwRollbackEnlistment** if the transaction should be rolled back. If the superior transaction manager cannot determine the outcome of a transaction, it should not respond to the TRANSACTION\_NOTIFY\_RECOVER\_QUERY notification until it can determine an outcome. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20a%20Superior%20Transaction%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-a-transactional-client.md b/windows-driver-docs-pr/kernel/creating-a-transactional-client.md new file mode 100644 index 0000000000..d8ae4c65f0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-a-transactional-client.md @@ -0,0 +1,73 @@ +--- +title: Creating a Transactional Client +author: windows-driver-content +description: Creating a Transactional Client +ms.assetid: 75d4758b-dfba-431b-9bfa-9dcb98c2a7cc +keywords: ["transactional clients WDK KTM", "transactional clients WDK KTM , creating transactional clients"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating a Transactional Client + + +A [*transactional client*](transaction-processing-terms.md#ktm-term-transactional-client) is a transaction processing system (TPS) component that uses a resource manager's exported interface to access a resource, such as a database, that the resource manager supports. + +Typically, the client creates a transaction, performs a set of database operations, and then commits the transaction to make the operations permanent. If the client encounters an error, it can roll back the transaction to remove the transaction's operations instead of committing the transaction. + +Typically, a transactional client that uses kernel-mode KTM must perform the following tasks for each transaction: + +1. Create a transaction object. + + A call to [**ZwCreateTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566429) creates a transaction object, provides an object handle, and assigns an object identifier (a GUID) that the client can pass to the resource manager to identify the transaction. + +2. Obtain the transaction object's identifier. + + The client can call [**ZwQueryInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567057) to obtain the object identifier. + +3. Pass the transaction object's identifier to a resource manager. + + The client typically calls the resource manager's exported interface to open a communication path to the resource manager and to associate the path with the transaction. For example, the resource manager might provide a *CreateDataObject* routine that is similar to the one that the [Understanding TPS Components](understanding-tps-components.md) topic describes. + +4. Perform operations to be included in the transaction. + + Typically, the client calls the resource manager's interface to access the resource manager's resource. For example, the client of a database manager might read from and write to the database. + +5. Commit or roll back the transaction. + + If all the resource operations succeed, the client must call [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) to make the operations permanent. If an operation fails, the client must call [**ZwRollbackTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567086) instead of **ZwCommitTransaction**. For example, if the client of a database manager determines that one of a series of write operations failed, the client must call **ZwRollbackTransaction** so that none of the write operations become permanent. + + Clients can call **ZwCommitTransaction** and **ZwRollbackTransaction** either synchronously or asynchronously. If clients call these routines synchronously, the routines do not return until the commit or rollback operation is complete. + + For more information about how to commit and roll back transactions, see [Handling Transaction Operations](handling-transaction-operations.md). + +6. Close the transaction object handle. + + After the client has finished processing the transaction, it must call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the transaction object's handle + +A TPS might include more than one resource manager. If a client's transaction includes operations on multiple resources, such as two databases that two resource managers support, the client typically does the following: + +1. Creates a single transaction object for each transaction. + +2. Passes the transaction object's identifier to each resource manager. + +3. Performs operations on each database by calling each resource manager's interface. + +4. Commits the transaction if all operations completed without errors, or rolls back the transaction if an error was detected. + +If your TPS includes a *superior transaction manager*, transactional clients typically do not call KTM. For more information about superior transaction managers and their clients, see [Creating a Superior Transaction Manager](creating-a-superior-transaction-manager.md). + +Transactional clients can call [**ZwSetInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567104) to set transaction-specific information. For example, a client can set a time-out value for the transaction or supply a descriptive character string. Clients can call [**ZwQueryInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567057) to retrieve information about a transaction. For example, a client can call this routine to determine whether a transaction has been committed or rolled back. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20a%20Transactional%20Client%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-controller-objects-and-controller-extensions.md b/windows-driver-docs-pr/kernel/creating-controller-objects-and-controller-extensions.md new file mode 100644 index 0000000000..fd5d5e514c --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-controller-objects-and-controller-extensions.md @@ -0,0 +1,44 @@ +--- +title: Creating Controller Objects and Controller Extensions +author: windows-driver-content +description: Creating Controller Objects and Controller Extensions +ms.assetid: 1f5bfcbc-1d8e-4ace-9539-a25e226444a6 +keywords: ["controller objects WDK kernel , creating", "IoCreateController", "controller extensions WDK I/O", "extensions WDK controller objects", "controller objects WDK kernel , extensions"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating Controller Objects and Controller Extensions + + +## + + +If a driver uses a controller object, it must call [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395) after it has created device objects and its device is ready for I/O, typically after receiving a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. The following figure illustrates the call. + +![diagram illustrating a controller object](images/3ctlrobj.png) + +Every controller object has an associated controller extension. As the previous figure shows, the caller of **IoCreateController** determines the *Size* of the controller extension. Its structure and contents are driver-defined. + +In addition to whatever device-specific state information the driver maintains about the physical controller (or device with channels), the previous figure shows a representative set of driver-defined data for a controller extension. + +The *PtrToControllerObject* pointer, returned by **IoCreateController**, must be passed in the driver's calls to [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224) and [**IoFreeController**](https://msdn.microsoft.com/library/windows/hardware/ff549104), described in [Allocating Controller Objects for I/O Operations](allocating-controller-objects-for-i-o-operations.md). The driver must store the returned controller object pointer in the device extensions of its driver-created device objects or in another driver-accessible resident storage area (nonpaged pool, allocated by the driver). If the driver is unloaded, it also must pass the controller object pointer to [**IoDeleteController**](https://msdn.microsoft.com/library/windows/hardware/ff549078). + +Most drivers that set up controller objects find it convenient to store a pointer to the current target device object or device extension in the controller extension. Usually, such a driver stores the controller object pointer in every one of its device extensions so that it can use the *ControllerObject***->ControllerExtension** pointer to access driver-maintained, controller-specific state about I/O operations for every target device object. + +If the physical controller represented by a controller object generates interrupts, a driver also can use the controller extension as storage for *PtrToInterruptObject* pointers returned by [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371). For more information, see [Interrupt Service Routines](interrupt-service-routines.md). + +**IoCreateController** allocates resident storage for the controller object and extension, which it initializes with zeros. If it cannot allocate the memory, **IoCreateController** returns a **NULL** pointer. If this occurs, the driver must fail device startup and should return STATUS\_INSUFFICIENT\_RESOURCES. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20Controller%20Objects%20and%20Controller%20Extensions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-export-drivers.md b/windows-driver-docs-pr/kernel/creating-export-drivers.md new file mode 100644 index 0000000000..725d443ee3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-export-drivers.md @@ -0,0 +1,76 @@ +--- +title: Creating Export Drivers +author: windows-driver-content +description: Creating Export Drivers +ms.assetid: 60ce7d0d-0eab-4af6-890a-45ab206816aa +keywords: ["export drivers WDK kernel", "loading export drivers WDK kernel", "importing export driver functions", "module-definition files WDK kernel", ".def files", "def files", "kernel-mode drivers WDK , export drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating Export Drivers + + +## + + +Microsoft Windows drivers are typically defined as a pair of components, such as a port/miniport driver pair, or a class/miniclass driver pair. Typically, Microsoft provides a hardware-independent class or port driver, and a vendor supplies a hardware-dependent miniclass or miniport driver. + +Kernel-mode export drivers are especially well suited for implementing the part of a driver pair that is independent of underlying stack and hardware characteristics, because an export driver is a kernel-mode DLL that can be loaded by a variety of other hardware-specific or device-stack-specific components. Microsoft ships several drivers together with the Windows operating system that fall into this category. For example, the SCSI port driver, the tape class driver, the IDE controller driver are all system-supplied export drivers that are loaded by other drivers. + +An export driver is missing many of the characteristics of a complete kernel-mode driver. An export driver does not have a dispatch table, it does not have a place in the driver stack, and it does not have an entry in the service control manager's database that defines it as a system service. An export driver does have a [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine, but its **DriverEntry** routine is never called. (The routine is only a stub to satisfy the requirements of the build scripts.) + +Note that, while an export driver does not have a dispatch table, it can supply dispatch routines to a standard driver. The standard driver inserts the dispatch routines into its own dispatch table. + +Standard drivers can also function as export drivers. For a driver to function in both ways, it must be built as an export driver and loaded as a regular driver. + +### Building an Export Driver + +To build a driver as an export driver you must define several Build utility macros in the driver's Sources file. + +First, you must assign the appropriate value to the **TARGETTYPE** macro, as follows: + +``` +TARGETTYPE=EXPORT_DRIVER +``` + +You must also specify a module-definition (.def) file using the **DLLDEF** macro. For example: + +``` +DLLDEF="c:\project\driver.def" +``` + +The module-definition file provides the compiler and linker with a list of exported routines along with other information. For more information about module-definition files, see the Microsoft Visual C++ documentation. + +Many of the Build utility macros employed in building a user-mode DLL cannot be used when building a kernel-mode DLL. For instance, the entry point for a kernel-mode DLL is always [**DllInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff544049). You cannot specify the entry point using the **DLLENTRY** macro. + +The build process generates an export library with a .lib extension, and an export driver with a .sys extension. + +### Importing Functions from an Export Driver + +To import functions that are exported by an export driver, you should declare the functions using the DECLSPEC\_IMPORT macro, which is defined in Ntdef.h. For example: + +``` +DECLSPEC_IMPORT int LoadPrinterDriver (int arg1); +``` + +This macro resolves to a **\_\_declspec**(dllimport) storage class declaration on those platforms where required and to nothing on those platforms where not required. + +In the export driver, the function to be exported should be declared with the DECLSPEC\_EXPORT macro. This macro resolves to a **\_\_declspec**(dllexport) storage class declaration on those platforms where required and to nothing on those platforms where not required. If an export driver supplies a dispatch routine to a standard driver, that routine does not have to be exported. + +### Loading an Export Driver + +Export drivers must be installed in the %Windir%\\System32\\Drivers directory. Starting with Windows 2000, the operating system keeps a reference count that indicates the number of times that the export driver's functions have been imported by other drivers. The system decrements this count whenever one of the importing drivers unloads. When the reference count falls to zero, the system unloads the export driver. However, the export driver must contain the standard entry point and unload routines, [**DllInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff544049) and [**DllUnload**](https://msdn.microsoft.com/library/windows/hardware/ff544054), or the operating system will not activate this reference count mechanism. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20Export%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-ioctl-requests-in-drivers.md b/windows-driver-docs-pr/kernel/creating-ioctl-requests-in-drivers.md new file mode 100644 index 0000000000..2b9bf77e65 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-ioctl-requests-in-drivers.md @@ -0,0 +1,68 @@ +--- +title: Creating IOCTL Requests in Drivers +author: windows-driver-content +description: Creating IOCTL Requests in Drivers +ms.assetid: 155e2577-0e9a-4c0b-a25a-8516ce3de631 +keywords: ["I/O control codes WDK kernel , creating requests", "control codes WDK IOCTLs , creating requests", "IOCTLs WDK kernel , creating requests", "synchronization WDK IRPs", "embedded pointers WDK IOCTLs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating IOCTL Requests in Drivers + + +## + + +A class driver or other higher-level driver can allocate IRPs for I/O control requests and send them to the next-lower driver as follows: + +1. Allocate or reuse an I/O request packet ([**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694)) with the major function code [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766). You can use the [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) routine to specifically allocate an IOCTL IRP. You can also use general-purpose IRP creation and initialization routines, such as [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257), [**IoReuseIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549661), or [**IoInitializeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549315). For more information about IRP allocation, see [Creating IRPs for Lower-Level Drivers](creating-irps-for-lower-level-drivers.md). + +2. Set up the lower driver's I/O stack location for the IRP with the IOCTL\_*XXX* code and appropriate parameters. + +3. If the IOCTL request is to be completed asynchronously, call the [**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137) routine to initialize an event object as a notification event. The driver uses this event to wait for an I/O operation to be completed. + +4. Call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) with the IRP so that the upper driver can supply an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, if necessary, to do the following: + + - Determine how the lower driver handled a given request. + + - Reuse the IRP to send another request or dispose of the driver-created IRP, after the lower driver completes a requested operation. The driver cannot reuse IRPs that [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) created. For more information, see [Reusing IRPs](reusing-irps.md). + +5. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) to pass the request on to the lower driver. + +6. If [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) returns STATUS\_PENDING, call the [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) routine to put the current thread into a wait state. The driver sets the routine's *Object* parameter to the address of the event object that was initialized in the call to [**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137). + + **Note**  If the driver calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with its *Timeout* parameter set either to **NULL** or to the address of a variable that contains a nonzero value, the driver must be running at IRQL <= APC\_LEVEL in a nonarbitrary thread context. Otherwise, the driver must be running at IRQL <= DISPATCH\_LEVEL. + +   + + The event is signaled by its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine when the IOCTL request has completed. Once the event is signaled, the thread resumes execution. + + **Important**  If the driver allocates the event object as a local variable on the stack, the driver must call [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with its *WaitMode* parameter set to **KernelMode**. This parameter value prevents the stack from being paged out. + +   + +To avoid synchronization problems and possible access violations, parameters for I/O control codes rarely include embedded pointers. Except for certain SCSI requests, the buffers at *Irp*->**AssociatedIrp**.**SystemBuffer**, at *Irp*->**MdlAddress**, and at **Parameters**.**DeviceIoControl**.**Type3InputBuffer** in a driver's I/O stack location do not contain pointers to other data buffers, nor do they contain structures that contain pointers for system-defined I/O control codes. For more information about how data buffers are used with IRPs that contain I/O control codes, see [Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md). + +Nevertheless, a pair of class/port drivers that define internal I/O control codes can pass an embedded pointer to driver-allocated memory from the higher-level driver to the lower-level driver. Such a pair of class/port drivers is responsible for ensuring that the following is true: + +- Only one driver at a time can access the data. + +- Private data buffers are accessible in an arbitrary thread context by the port driver. + +Display drivers can call the GDI function [**EngDeviceIoControl**](https://msdn.microsoft.com/library/windows/hardware/ff564838) to send privately defined, device-specific I/O control requests, as well as system-defined public I/O control requests, through the system video port driver down to the corresponding adapter-specific [video miniport drivers](https://msdn.microsoft.com/library/windows/hardware/ff570509). + +Any user-mode component of a driver package can call [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) to send I/O control requests to a driver stack. The I/O manager creates an [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request and delivers it to the highest-level driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20IOCTL%20Requests%20in%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-irps-for-lower-level-drivers.md b/windows-driver-docs-pr/kernel/creating-irps-for-lower-level-drivers.md new file mode 100644 index 0000000000..c64e859382 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-irps-for-lower-level-drivers.md @@ -0,0 +1,76 @@ +--- +title: Creating IRPs for Lower-Level Drivers +author: windows-driver-content +description: Creating IRPs for Lower-Level Drivers +ms.assetid: 2d298eb1-6169-4742-80c1-200223a2d4fa +keywords: ["IRPs WDK kernel , creating", "asynchronous requests WDK IRPs", "IRPs WDK kernel , asynchronous requests"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating IRPs for Lower-Level Drivers + + +## + + +To allocate an IRP for an asynchronous request, which will be processed in an arbitrary thread context by lower drivers, a [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine can call one of the following support routines: + +- [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257), which allocates an IRP and a number of zero-initialized I/O stack locations + + The dispatch routine must set up the next-lower driver's I/O stack location for the newly allocated IRP, usually by copying (possibly modified) information from its own stack location in the original IRP. If a higher-level driver allocates an I/O stack location of its own for a newly-allocated IRP, the dispatch routine can set up per-request context information there for the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine to use. + +- [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310), which sets up the next-lower driver's I/O stack location for the caller, according to caller-specified parameters + + Higher-level drivers can call this routine to allocate IRPs for [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794), [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760), and [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807) requests. + + When an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine is called for such an IRP, it can check the I/O status block, and if necessary (or possible) set up the next-lower driver's I/O stack location in the IRP again and retry the request or reuse it. However, the *IoCompletion* routine has no local context storage for itself in the IRP, so the driver must maintain context about the original request elsewhere in resident memory. + +- [**IoMakeAssociatedIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549397), which allocates an IRP and a number of zero-initialized I/O stack locations, and associates the IRP with a *master* IRP. + + Intermediate drivers cannot call [**IoMakeAssociatedIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549397) to create IRPs for lower drivers. + + Any highest-level driver that calls **IoMakeAssociatedIrp** to create IRPs for lower drivers can return control to the I/O manager after sending its associated IRPs on and calling [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) for the original, master IRP. A highest-level driver can rely on the I/O manager to complete the master IRP when all associated IRPs have been completed by lower drivers. + + Drivers seldom set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for an associated IRP. If a highest-level driver calls [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) for an associated IRP it creates, the I/O manager does not complete the master IRP if the driver returns STATUS\_MORE\_PROCESSING\_REQUIRED from its *IoCompletion* routine. In these circumstances, the driver's *IoCompletion* routine must explicitly complete the master IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +If a driver allocates an I/O stack location of its own in a new IRP, the dispatch routine must call [**IoSetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550321) before it calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) to set up context in its own I/O stack location for the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. For more information, see [Processing IRPs in an Intermediate-Level Driver](processing-irps-in-an-intermediate-level-driver.md). + +The dispatch routine must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) with the original IRP, but not with any driver-allocated IRPs because the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine will free them. + +If the dispatch routine is allocating IRPs for partial transfers and the underlying device driver might control a removable-media device, the dispatch routine must set up the thread context in its newly allocated IRPs from the value at **Tail.Overlay.Thread** in the original IRP. + +An underlying driver for a removable-media device might call [**IoSetHardErrorOrVerifyDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549707), which references the pointer at **Irp->Tail.Overlay.Thread**, for a driver-allocated IRP. If the driver calls this support routine, the file system driver can send a dialog box to the appropriate user thread that prompts the user to cancel, retry, or fail an operation that the driver could not satisfy. See [Supporting Removable Media](supporting-removable-media.md) for more information. + +Dispatch routines must return STATUS\_PENDING after sending all driver-allocated IRPs on to lower drivers. + +A driver's [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine should free all driver-allocated IRPs with [**IoFreeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549113) before it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) for the original IRP. When it completes the original IRP, the *IoCompletion* routine must free all driver-allocated IRPs before it returns control. + +Each higher-level driver sets up any driver-allocated (and reused) IRPs for lower drivers in such a way that it is immaterial to the underlying device driver whether a given request comes from an intermediate driver or originates from any other source, such as a file system or user-mode application. + +Highest-level drivers can call [**IoMakeAssociatedIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549397) to allocate IRPs and set them up for a chain of lower drivers. The I/O manager automatically completes the original IRP when all its associated IRPs have been completed, as long as the driver does not call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) with the original IRP or with any of the associated IRPs it allocates. Highest-level drivers must not, however, allocate associated IRPs for any IRP that requests a buffered I/O operation. + +An intermediate-level driver cannot allocate IRPs for lower-level drivers by calling **IoMakeAssociatedIrp**. Any IRP an intermediate driver receives might already be an associated IRP, and a driver cannot associate another IRP with such an IRP. + +Instead, if an intermediate driver creates IRPs for lower drivers, it should call [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257), [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318), [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330), or [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310). However, **IoBuildSynchronousFsdRequest** can be called only in the following circumstances: + +- By a driver-created thread to build IRPs for read or write requests, because such a thread can wait in a nonarbitrary thread context (its own) on a dispatcher object, such as a driver-initialized *Event* passed to **IoBuildSynchronousFsdRequest** + +- In the system thread context during initialization or while unloading + +- To build IRPs for inherently synchronous operations, such as create, flush, shutdown, close, and device control requests + +However, a driver is more likely to call **IoBuildDeviceIoControlRequest** to allocate device control IRPs than **IoBuildSynchronousFsdRequest**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20IRPs%20for%20Lower-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-reliable-kernel-mode-drivers.md b/windows-driver-docs-pr/kernel/creating-reliable-kernel-mode-drivers.md new file mode 100644 index 0000000000..38ef9fecf6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-reliable-kernel-mode-drivers.md @@ -0,0 +1,110 @@ +--- +title: Creating Reliable Kernel-Mode Drivers +author: windows-driver-content +description: Creating Reliable Kernel-Mode Drivers +ms.assetid: 31bbf1fe-dc90-43e0-a53e-eca902ec343e +keywords: ["kernel-mode drivers WDK , reliability", "reliability WDK kernel", "reliability WDK kernel , about reliable drivers", "IRPs WDK kernel , reliability issues"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating Reliable Kernel-Mode Drivers + + +## + + +Drivers make up a significant percentage of the total code that executes in kernel mode. A kernel-mode driver is, in effect, a component of the operating system. Therefore, drivers that are reliable and secure contribute significantly to the overall trustworthiness of the operating system. To create a reliable kernel-mode driver, follow these guidelines: + +- Secure device objects properly. + + User access to a system's drivers and devices is controlled by security descriptors that the system assigns to device objects. Most often, the system sets device security parameters when a device is installed. For more information, see [Creating Secure Device Installations](https://msdn.microsoft.com/library/windows/hardware/ff540212). Sometimes it is appropriate for a driver to play a part in controlling access to its device. For more information, see [Securing Device Objects](securing-device-objects.md). + +- Validate device objects properly. + + If a driver creates multiple types of device objects, it must check which type it receives in each IRP. For more information, see [Failure to Validate Device Objects](failure-to-validate-device-objects.md). + +- Use "safe string" functions. + + When manipulating strings, a driver should use safe string functions instead of the string functions that are supplied with C/C++ language runtime libraries. For more information, see [Using Safe String Functions](using-safe-string-functions.md). + +- Validate object handles. + + Drivers that receive object handles as input must verify that the handles are valid, are accessible, and are of the type expected. For more information about using object handles, see the following topics: + + [Object Management](managing-kernel-objects.md) + + [Failure to Validate Object Handles](failure-to-validate-object-handles.md) + +- Support multiprocessors properly. + + Never assume that your driver will run only on single-processor systems. For information about programming techniques that you can use to ensure that your driver will function properly on multiprocessor systems, see the following topics: + + [Synchronization Techniques](synchronization-techniques.md) + + [Errors in a Multiprocessor Environment](errors-in-a-multiprocessor-environment.md) + +- Handle driver state properly. + + It is important to always verify that your driver is in the state you assume it to be in. For example, if the driver receives an IRP, is it already servicing an IRP of the same type? If the driver does not check for this situation, the first IRP could be lost. For more information, see [Failure to Check a Driver's State](failure-to-check-a-driver-s-state.md). + +- Validate IRP input values. + + It is essential, from both a reliability and a security perspective, to validate all values that are associated with an IRP, such as buffer addresses and lengths. The following topics provide information about validating IRP input values: + + [DispatchReadWrite Using Buffered I/O](dispatchreadwrite-using-buffered-i-o.md) + + [Errors in Buffered I/O](errors-in-buffered-i-o.md) + + [DispatchReadWrite Using Direct I/O](dispatchreadwrite-using-direct-i-o.md) + + [Errors in Direct I/O](errors-in-direct-i-o.md) + + [Security Issues for I/O Control Codes](security-issues-for-i-o-control-codes.md) + + [Errors in Referencing User-Space Addresses](errors-in-referencing-user-space-addresses.md) + +- Handle the I/O stack properly. + + When [passing IRPs down the driver stack](passing-irps-down-the-driver-stack.md), it is important for drivers to call [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) or [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) to set up the next driver's I/O stack location. Do not write code that directly copies one I/O stack location to the next. + +- Handle IRP completion operations properly. + + A driver must never complete an IRP with a status value of STATUS\_SUCCESS unless it actually supports and processes the IRP. For information about the correct ways to handle IRP completion operations, see [Completing IRPs](completing-irps.md). + +- Handle IRP cancellation operations properly. + + Cancel operations can be difficult to code properly because they typically execute asynchronously. Problems in the code that handles cancel operations can go unnoticed for a long time, because this code is typically not executed frequently in a running system. + + Be sure to read and understand all of the information supplied under [Canceling IRPs](canceling-irps.md). Pay special attention to [Synchronizing IRP Cancellation](synchronizing-irp-cancellation.md) and [Points to Consider When Canceling IRPs](points-to-consider-when-canceling-irps.md). + + One way to avoid the synchronization problems that are associated with cancel operations is to implement a [cancel-safe IRP queue](cancel-safe-irp-queues.md). A cancel-safe IRP queue is a driver-managed queue that was introduced for Windows XP and later operating system versions, but is also backward-compatible to earlier versions. + +- Handle IRP cleanup and close operations properly. + + Be sure that you understand the difference between [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718) and [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720) requests. Cleanup requests arrive after an application closes all handles on a file object, but sometimes before all I/O requests have completed. Close requests arrive after all I/O requests for the file object have been completed or canceled. For more information, see the following topics: + + [DispatchCreate, DispatchClose, and DispatchCreateClose Routines](dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md) + + [DispatchCleanup Routines](dispatchcleanup-routines.md) + + [Errors in Handling Cleanup and Close Operations](errors-in-handling-cleanup-and-close-operations.md) + +For more information about handling IRPs correctly, see [Additional Errors in Handling IRPs](additional-errors-in-handling-irps.md). + +### Using Driver Verifier + +[Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) is the most important tool you can use to ensure the reliability of your driver. Driver Verifier can check for a variety of common driver problems, including some of those discussed in this section. However, use of Driver Verifier does not replace careful, thoughtful software design. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20Reliable%20Kernel-Mode%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/creating-the-localized-mof-file.md b/windows-driver-docs-pr/kernel/creating-the-localized-mof-file.md new file mode 100644 index 0000000000..4b7260886b --- /dev/null +++ b/windows-driver-docs-pr/kernel/creating-the-localized-mof-file.md @@ -0,0 +1,66 @@ +--- +title: Creating the Localized MOF File +author: windows-driver-content +description: Creating the Localized MOF File +ms.assetid: 1cc99e43-b09a-445d-abb6-4a3d73b6d7ed +keywords: ["MOF files WDK WMI", "localizing MOF files", "property qualifiers WDK WMI", "amended classes WDK WMI", "multiple MOF files WDK WMI", "languages WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Creating the Localized MOF File + + +## + + +On Windows XP and later versions of the operating system, drivers localize a WMI schema by making an *amended* version of each class. An amended version of a class updates property qualifiers that depend on the locale. + +An amended version of a class has the same format as a class declaration, preceded by the **amendment** qualifier. The amended class declaration also includes a **locale(**0x*XXX***)** qualifier, where *XXX* specifies the locale identifier (LCID) for the locale. + +The amended declaration includes the modified property declarations. Each localized property qualifier has the **:amended** modifier attached to it. For example, the localized version of **Description("***a description string***")** would be **Description("***localized description string***"):amended**. + +Here is an example of a declaration of the basic class, followed by its amendment for American English. + +``` +[guid(xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx)] +class MyClass +{ + [key] sint32 KeyProp; + string Name; + uint64 Timestamp; +} + +[amendment, locale(0x409) + Description("Localized version of MyClass for American English"):amended] + +class MyClass +{ + [DisplayName("Key Property"):amended, + Description("The description of KeyProp"):amended] + sint32 KeyProp; + + [DisplayName("User Name"):amended, + Description("The description of Name"):amended] + string Name; +} +``` + +Only the properties that have been modified need to be included in the amended class. The class and property names cannot be localized. Only property qualifiers can be localized. + +Localized classes are organized in child namespaces of the namespace containing the original class. Classes for a given locale are found in the MS\_*XXX* child namespace, where *XXX* represents the hexadecimal LCID for that locale. For example, drivers are in the \\root\\wmi namespace by default. An amended class, localized for American English, is found in the \\root\\wmi\\MS\_409 namespace. + +For more information about WMI localization, see the [WMI international support](http://go.microsoft.com/fwlink/p/?linkid=8774) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Creating%20the%20Localized%20MOF%20File%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/critical-issues-for-device-drivers.md b/windows-driver-docs-pr/kernel/critical-issues-for-device-drivers.md new file mode 100644 index 0000000000..cb379cef9c --- /dev/null +++ b/windows-driver-docs-pr/kernel/critical-issues-for-device-drivers.md @@ -0,0 +1,33 @@ +--- +title: Critical Issues for Device Drivers +author: windows-driver-content +description: Critical Issues for Device Drivers +ms.assetid: af09c548-02f6-448e-bdd8-7521b4ed7c96 +keywords: ["dynamic hardware partitioning WDK , critical issues", "hardware partitioning WDK dynamic , critical issues", "partitions WDK dynamic hardware , critical issues", "dynamically partitionable servers WDK dynamic hardware partitioning", "servers WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Critical Issues for Device Drivers + + +When you develop device drivers, you should consider the following critical issues that are related to dynamic hardware partitioning: + +[Changes to the Number of Processors](changes-to-the-number-of-processors.md) + +[Changes to the Amount of Physical Memory](changes-to-the-amount-of-physical-memory.md) + +[Hot Replace of Partition Units](hot-replace-of-partition-units.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Critical%20Issues%20for%20Device%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/critical-regions-and-guarded-regions.md b/windows-driver-docs-pr/kernel/critical-regions-and-guarded-regions.md new file mode 100644 index 0000000000..f66e42ff9b --- /dev/null +++ b/windows-driver-docs-pr/kernel/critical-regions-and-guarded-regions.md @@ -0,0 +1,49 @@ +--- +title: Critical Regions and Guarded Regions +author: windows-driver-content +description: Critical Regions and Guarded Regions +ms.assetid: 3781498a-45e9-4f24-8fd2-830eed61298c +keywords: ["asynchronous procedure calls WDK kernel", "APCs WDK kernel", "critical regions WDK kernel", "guarded regions WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Critical Regions and Guarded Regions + + +A thread that is inside a *critical region* executes with user APCs and normal kernel APCs disabled. A thread inside a *guarded region* runs with all APCs disabled. + +### Critical Regions + +A driver can enter and exit a critical region as follows: + +- Call [**KeEnterCriticalRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552021) to enter a critical region. + +- Call [**KeLeaveCriticalRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552964) to exit a critical region. + +Each call to **KeEnterCriticalRegion** must have a matching call to **KeLeaveCriticalRegion**. + +### Guarded Regions + +A driver can enter and exit a guarded region as follows: + +- Call [**KeEnterGuardedRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552028) to enter a guarded region. + +- Call [**KeLeaveGuardedRegion**](https://msdn.microsoft.com/library/windows/hardware/ff552967) to leave a guarded region. + +Each call to **KeEnterGuardedRegion** must have a matching call to **KeLeaveGuardedRegion**. + +Drivers that were developed for Windows Server 2003 and later versions of Windows can use guarded regions to disable special kernel APCs. Drivers that were developed for earlier operating systems can disable special kernel APCs by raising the current IRQL to APC\_LEVEL by calling [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079). Use [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) to lower the current IRQL to the previous value. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Critical%20Regions%20and%20Guarded%20Regions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/d1latency--d2latency--and-d3latency.md b/windows-driver-docs-pr/kernel/d1latency--d2latency--and-d3latency.md new file mode 100644 index 0000000000..ab4a9c88cd --- /dev/null +++ b/windows-driver-docs-pr/kernel/d1latency--d2latency--and-d3latency.md @@ -0,0 +1,30 @@ +--- +title: D1Latency, D2Latency, and D3Latency +author: windows-driver-content +description: D1Latency, D2Latency, and D3Latency +ms.assetid: 6ad72b77-ec36-461c-8f4f-030d67e5a135 +keywords: ["D1Latency", "D2Latency", "D3Latency"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# D1Latency, D2Latency, and D3Latency + + +## + + +The **D1Latency**, **D2Latency**, and **D3Latency** members of [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) contain the approximate time, in 100-microsecond units, that the device requires to return to the D0 state from each of the sleeping states. A driver should specify a latency time of zero for any device power state that it does not support. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20D1Latency,%20D2Latency,%20and%20D3Latency%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/d3cold-capabilities-of-a-device.md b/windows-driver-docs-pr/kernel/d3cold-capabilities-of-a-device.md new file mode 100644 index 0000000000..729da7dbe5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/d3cold-capabilities-of-a-device.md @@ -0,0 +1,35 @@ +--- +title: D3cold Capabilities of a Device +author: windows-driver-content +description: Before the driver that is the power policy owner (PPO) for a device enables the device to enter D3cold (when the computer is to remain in S0), the driver must verify that the device will be responsive and continue to operate correctly after the device enters D3cold. +ms.assetid: 5A6CB076-7D97-48EC-B2BF-3204CD093B3E +--- + +# D3cold Capabilities of a Device + + +Before the driver that is the power policy owner (PPO) for a device enables the device to enter D3cold (when the computer is to remain in S0), the driver must verify that the device will be responsive and continue to operate correctly after the device enters D3cold. + +For a Plug and Play (PnP) device, the operating system typically gets information about the D3cold capabilities of the device from the parent bus driver. + +For example, if a device is attached to a PCI or PCI Express bus, the device's PCI configuration space contains a Power Management Register Block that indicates the capabilities of the device. Capability flags in this block specify the device power states from which the device can signal a power management event, or PME (the PCI term for a wake event). These states might include D3hot and D3cold. For more information about PCI power management, see the [PCI Bus Power Management Interface Specification](http://www.pcisig.com/specifications/conventional/pci_bus_power_management_interface/). + +If a device must be able to signal a wake event from any low-power Dx state that it enters, the device should not enter D3cold unless the device, parent bus controller, and hardware platform support signaling a wake event from D3cold. + +The KMDF driver for a device calls the [**WdfDeviceAssignS0IdleSettings**](https://msdn.microsoft.com/library/windows/hardware/ff545903) method to enable the device to idle in the lowest-powered device power state from which the device can signal a wake event. Starting with KMDF version 1.11, **WdfDeviceAssignS0IdleSettings** includes D3cold in the range of possible low-power Dx states. This method enables a device to idle in D3cold only if the device, the parent bus driver, and the ACPI system firmware support signaling wake events from D3cold. + +The WDM driver for a device must decide which low-power Dx state to move the device to when the device is idle. (In contrast, **WdfDeviceAssignS0IdleSettings** automatically selects this Dx state so that the driver does not have to.) If the device must be able to signal a wake event from any low-power Dx state that it enters, the driver can call the [*GetIdleWakeInfo*](https://msdn.microsoft.com/library/windows/hardware/hh967712) routine to determine the lowest-powered device power state from which the device can signal a wake event. To get this information, *GetIdleWakeInfo* queries the underlying bus driver and ACPI system firmware. Based on the information from *GetIdleWakeInfo*, the driver can call the [*SetD3ColdSupport*](https://msdn.microsoft.com/library/windows/hardware/hh967716) routine to enable or disable the device's transitions to D3cold. + +A device might not require the ability to signal a wake event from D3cold. The device might instead be required to make the transition from D3cold to D0 only in response to software-initiated actions. For example, the driver might need to wake the device if the driver receives an I/O request for the device. With few exceptions, the driver for such a device can enable the device to enter D3cold. A possible exception is a device that requires a large amount of time to make a transition from D3cold to D0. For example, a display device might contain a large amount of memory that needs to be saved before the device enters D3cold and restored after the device exits D3cold. + +For more information about ACPI support for D3cold, see [Firmware Requirements for D3cold](https://msdn.microsoft.com/library/windows/hardware/dn605829). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20D3cold%20Capabilities%20of%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dedicated-clfs-logs.md b/windows-driver-docs-pr/kernel/dedicated-clfs-logs.md new file mode 100644 index 0000000000..17e095db2b --- /dev/null +++ b/windows-driver-docs-pr/kernel/dedicated-clfs-logs.md @@ -0,0 +1,58 @@ +--- +title: Dedicated CLFS Logs +author: windows-driver-content +description: Dedicated CLFS Logs +ms.assetid: c6ca580c-b7f4-493a-8bd6-35d0aa932b1a +keywords: ["Common Log File System WDK kernel , dedicated logs", "CLFS WDK kernel , dedicated logs", "dedicated logs WDK CLFS", "stable storage WDK CLFS", "storage WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dedicated CLFS Logs + + +## + + +A Common Log File System (CLFS) log can be either dedicated or multiplexed. A *dedicated log* serves as stable storage for a single stream. A *multiplexed log* serves as stable storage for several streams. This topic discusses dedicated logs. For information about multiplexed logs, see [Multiplexed CLFS Logs](multiplexed-clfs-logs.md). + +To create a dedicated log, perform the following steps. + +1. Call [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) to obtain a pointer to a [**LOG\_FILE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff554316) structure. Set the *puszLogFileName* parameter to a string of the form "log:*<log name>*" where *<log name>* is a valid path on the underlying file system. For example, if you set *puszLogFileName* to "log:c:\\ClfsLogs\\myLog", the base log file myLog.blf would be created in the c:\\ClfsLogs directory. The c:\\ClfsLogs directory would also serve as the default location for containers that you add to the log later. + + **Note**  It is the form of the string passed in *puszLogFileName* that determines whether CLFS creates a dedicated or multiplexed log. If the string has a double colon (::) after the log name, then CLFS creates a multiplexed log. In the example given here, "log:c\\ClfsLogs\\myLog" has no double colon, so CLFS creates a dedicated log. + +   + + The **LOG\_FILE\_OBJECT** pointer returned by **ClfsCreateLogFile** represents an open instance of the dedicated log's one and only stream. + +2. Pass the **LOG\_FILE\_OBJECT** pointer you obtained from **ClfsCreateLogFile** to [**ClfsAddLogContainer**](https://msdn.microsoft.com/library/windows/hardware/ff540768) to create a container (contiguous physical extent) on stable storage that will hold log records. Specify the size of the container (which will be rounded up to a multiple of 512 kilobytes) by setting the *pcbContainer* parameter. Set the *puszContainerPath* parameter to specify a path name for the container. The path name can be absolute or relative to the directory that contains the base log file. + + You can create additional containers for your log by calling **ClfsAddLogContainer** again. Note that all containers for a given log must be the same size. As an alternative to calling **ClfsAddLogContainer** several times, you can call [**ClfsAddLogContainerSet**](https://msdn.microsoft.com/library/windows/hardware/ff540770) to create several containers simultaneously. + +3. Pass the **LOG\_FILE\_OBJECT** pointer you obtained from **ClfsCreateLogFile** to [**ClfsCreateMarshallingArea**](https://msdn.microsoft.com/library/windows/hardware/ff541520) to obtain a pointer to a marshalling area that you can use to read and write log records to your stream. Specify the size of the log I/O blocks that the marshalling area will use by setting the *cbMarshallingBuffer* parameter. There are several other parameters you can use to set various properties of the marshalling area. + + If you need additional marshalling areas, pass the same **LOG\_FILE\_OBJECT** pointer to **ClfsCreateMarshallingArea** again, once for each additional marshalling area that you need. + +Now that you have one or more marshalling areas associated with your stream, you can write records to those marshalling areas by calling the following functions. + +[**ClfsReserveAndAppendLog**](https://msdn.microsoft.com/library/windows/hardware/ff541723) + +[**ClfsReserveAndAppendLogAligned**](https://msdn.microsoft.com/library/windows/hardware/ff541726) + +[**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770) + +Each time you write a record, you get back a log sequence number (LSN) that identifies the record. The LSN assigned to a record is always greater than the LSN assigned to the previously written record, regardless of which marshalling area was used to write the record. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dedicated%20CLFS%20Logs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-a-callback-object.md b/windows-driver-docs-pr/kernel/defining-a-callback-object.md new file mode 100644 index 0000000000..ca6a25af8c --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-a-callback-object.md @@ -0,0 +1,40 @@ +--- +title: Defining a Callback Object +author: windows-driver-content +description: Defining a Callback Object +ms.assetid: 9717795b-dd62-4f17-b931-5ca2b1237e60 +keywords: ["callback objects WDK kernel", "registering callback notifications"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining a Callback Object + + +## + + +A driver can create a callback object, through which other drivers can request notification of conditions defined by the creating driver. The following figure shows the steps involved in defining a callback object. + +![diagram illustrating defining a callback object](images/3crt-cbk.png) + +Before creating the object, the driver calls [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804) to set its attributes. A callback object must have a name, which cannot match the name of a system-defined callback; it can have whatever other attributes its creator deems appropriate, typically OBJ\_CASE\_INSENSITIVE. Next the driver calls [**ExCreateCallback**](https://msdn.microsoft.com/library/windows/hardware/ff544560), passing a pointer to the initialized attributes and a location at which to receive a handle to the callback object. It also passes two Booleans, indicating whether the system should create the callback object if such a named object does not already exist, and whether the object should allow more than one registered callback routine. + +The driver defines the conditions for which it will call the registered callback routines. The conditions take the form of two arguments, each pointing to a parameter defined by the driver that creates the callback. You should document these conditions, along with the name of the callback object and the IRQL at which it requests notification, for clients of the driver. + +When the callback condition occurs, the driver calls [**ExNotifyCallback**](https://msdn.microsoft.com/library/windows/hardware/ff545489), passing its handle to the callback object and the two arguments. The system then calls all callback routines registered for the callback object, in the order in which they were registered, passing the two arguments and a pointer to the context supplied when the routine was registered. The driver must call **ExNotifyCallback** at IRQL <= DISPATCH\_LEVEL; the system calls the callback routines at the same IRQL at which the driver made this call. + +After all operations have been completed with the callback object, the driver that created the callback should call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) to decrement its reference count and ensure that the object is deleted. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20a%20Callback%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-and-exporting-new-guids.md b/windows-driver-docs-pr/kernel/defining-and-exporting-new-guids.md new file mode 100644 index 0000000000..bbbf09e585 --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-and-exporting-new-guids.md @@ -0,0 +1,97 @@ +--- +title: Defining and Exporting New GUIDs +author: windows-driver-content +description: Defining and Exporting New GUIDs +ms.assetid: a7deb283-7cab-4f3c-ad96-f8085222456e +keywords: ["globally unique identifiers WDK kernel", "GUIDs WDK kernel", "identifiers WDK GUIDs", "exporting GUIDs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining and Exporting New GUIDs + + +## + + +You define a new GUID for an item the driver exports to other system components, drivers, or applications. For example, you define a new GUID for a custom PnP event on one of its devices. To define and export a new GUID, you must do the following: + +1. Choose a symbolic name for the GUID. + + Choose a name that represents the purpose of the GUID. For example, the operating system uses such names as GUID\_BUS\_TYPE\_PCI and PARPORT\_WMI\_ALLOCATE\_FREE\_COUNTS\_GUID. + +2. Generate a value for the GUID using Uuidgen.exe or Guidgen.exe. When you install the Microsoft Windows SDK, Uuidgen.exe is automatically installed. Guidgen.exe is available from the [Microsoft Exchange Server GUID Generator](http://go.microsoft.com/fwlink/p/?linkid=121586) download page. + + These utilities generate a unique, formatted string that represents a 128-bit value. The "-s" switch on Uuidgen.exe outputs the GUID formatted as a C structure. + +3. Define the GUID in an appropriate header file. + + Use the **DEFINE\_GUID** macro (defined in Guiddef.h) to associate the GUID symbolic name with its value (see Example 1). + + **Example 1: Defining GUIDs in a GUID-Only Header File** + + ``` + : + + DEFINE_GUID( GUID_BUS_TYPE_PCMCIA, 0x09343630L, 0xaf9f, 0x11d0, + 0x92,0x9f, 0x00, 0xc0, 0x4f, 0xc3, 0x40, 0xb1 ); + DEFINE_GUID( GUID_BUS_TYPE_PCI, 0xc8ebdfb0L, 0xb510, 0x11d0, + 0x80,0xE9, 0x00, 0x00, 0xf8, 0x1e, 0x1b, 0x30 ); + + : + ``` + + If the GUID is defined in a header file that contains statements other than GUID definitions, you must take an extra step to ensure that the GUID is instantiated in drivers that include the header file. The **DEFINE\_GUID** statement must occur outside any **\#ifdef** statements that prevent multiple inclusion. Otherwise, if the header file is included in a precompiled header, the GUID will not be instantiated in drivers that use the header file. See Example 2 for a sample GUID definition in a mixed header file. + + **Example 2: Defining GUIDs in a Mixed Header File** + + ``` + #ifndef _NTDDSER_ // this ex. is from a serial driver .h file + #define _NTDDSER_ + + : + // Put other header file definitions here. + : + + #endif // _NTDDSER_ + + #ifdef DEFINE_GUID // Do not break compiles of drivers that + // include this header but that do not + // want the GUIDs. + // + // Put GUID definitions outside of the multiple inclusion + // protection. + + DEFINE_GUID(GUID_CLASS_COMPORT, 0x86e0d1e0L, 0x8089, 0x11d0, 0x9c, + 0xe4, 0x08, 0x00, 0x3e, 0x30, 0x1f, 0x73); + + DEFINE_GUID (GUID_SERENUM_BUS_ENUMERATOR, 0x4D36E978, 0xE325, + 0x11CE, 0xBF, 0xC1, 0x08, 0x00, 0x2B, 0xE1, 0x03, 0x18); + + : + #endif // DEFINE_GUID + ``` + + Putting a GUID definition outside statements that prevent multiple inclusion does not cause multiple instances of the GUID in a driver because **DEFINE\_GUID** defines the GUID as an EXTERN\_C variable. Multiple declarations of an EXTERN variable are allowed as long as the types match. + +4. When creating a GUID for a new [device setup class](https://msdn.microsoft.com/library/windows/hardware/ff541509) or [device interface class](https://msdn.microsoft.com/library/windows/hardware/ff541339), the following rules apply: + - Do not use a single GUID to identify both a device setup class and a device interface class. + + - When creating a symbolic name to associate with the GUID, use the following convention: + + For device setup classes, use the format GUID\_DEVCLASS\_*XXX*. + + For device interface classes, use the format GUID\_DEVINTERFACE\_*XXX*. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20and%20Exporting%20New%20GUIDs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-and-using-an-event-object.md b/windows-driver-docs-pr/kernel/defining-and-using-an-event-object.md new file mode 100644 index 0000000000..cd6ff2cf06 --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-and-using-an-event-object.md @@ -0,0 +1,76 @@ +--- +title: Defining and Using an Event Object +author: windows-driver-content +description: Defining and Using an Event Object +ms.assetid: 4b7807f0-bbea-4402-b028-9ac73724717f +keywords: ["event objects WDK kernel", "waiting on event objects", "synchronization events WDK kernel", "notification events WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining and Using an Event Object + + +## + + +Any driver that uses an event object must call [**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137), [**IoCreateNotificationEvent**](https://msdn.microsoft.com/library/windows/hardware/ff549039), or [**IoCreateSynchronizationEvent**](https://msdn.microsoft.com/library/windows/hardware/ff549045) before it waits on, sets, clears, or resets the event. The following figure illustrates how a driver with a thread can use an event object for synchronization. + +![diagram illustrating waiting for an event object](images/3evntobj.png) + +As the previous figure shows, such a driver must provide the storage for the event object, which must be resident. The driver can use the [device extension](device-extensions.md) of a driver-created device object, the controller extension if it uses a [controller object](using-controller-objects.md), or nonpaged pool allocated by the driver. + +When the driver calls **KeInitializeEvent**, it must pass a pointer to the driver's resident storage for the event object. In addition, the caller must specify the initial state (signaled or not signaled) for the event object. The caller also must specify the event type, which can be either of the following: + +- **SynchronizationEvent** + + When a *synchronization event* is set to the Signaled state, a single thread that is waiting for the event to be reset to Not-Signaled becomes eligible for execution and the event's state is automatically reset to Not-Signaled. + + This type of event is sometimes called an *autoclearing event*, because its Signaled state is automatically reset each time a wait is satisfied. + +- **NotificationEvent** + + When a *notification event* is set to the Signaled state, all threads that were waiting for the event to be reset to Not-Signaled become eligible for execution and the event remains in the Signaled state until an explicit reset to Not-Signaled occurs: that is, there is a call to [**KeClearEvent**](https://msdn.microsoft.com/library/windows/hardware/ff551980) or [**KeResetEvent**](https://msdn.microsoft.com/library/windows/hardware/ff553176) with the given *Event* pointer. + +Few device or intermediate drivers have a single driver-dedicated thread, let alone a set of threads that might synchronize their operations by waiting for an event that protects a shared resource. + +Most drivers that use event objects to wait for the completion of an I/O operation set the input *Type* to **NotificationEvent** when they call **KeInitializeEvent**. An event object set up for IRPs that a driver creates with [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330) or [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) is almost always initialized as a **NotificationEvent** because the caller will wait for the event for notification that its request has been satisfied by one or more lower-level drivers. + +After the driver has initialized itself, its driver-dedicated thread, if any, and other routines can synchronize their operations on the event. For example, a driver with a thread that manages the queuing of IRPs, such as the system floppy controller driver, might synchronize IRP processing on an event, as shown in the previous figure: + +1. The thread, which has dequeued an IRP for processing on the device, calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with a pointer to the driver-supplied storage for the initialized event object. + +2. Other driver routines carry out device the I/O operations necessary to satisfy the IRP and, when these operations are complete, the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine calls [**KeSetEvent**](https://msdn.microsoft.com/library/windows/hardware/ff553253) with a pointer to the event object, a driver-determined priority boost for the thread (*Increment*, as shown in the previous figure), and a Boolean *Wait* set to **FALSE**. Calling **KeSetEvent** sets the event object to the Signaled state, thereby changing the waiting thread's state to ready. + +3. The kernel dispatches the thread for execution as soon as a processor is available: that is, no other thread with a higher priority is currently in the ready state and there are no kernel-mode routines to be run at a higher IRQL. + + The thread now can complete the IRP if the *DpcForIsr* has not called **IoCompleteRequest** with the IRP already, and can dequeue another IRP to be processed on the device. + +Calling **KeSetEvent** with the *Wait* parameter set to **TRUE** indicates the caller's intention to immediately call a [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324) support routine on return from **KeSetEvent**. + +**Consider the following guidelines for setting the***Wait***parameter toKeSetEvent:** + +A pageable thread or pageable driver routine that runs at IRQL < DISPATCH\_LEVEL should never call **KeSetEvent** with the *Wait* parameter set to **TRUE**. Such a call causes a fatal page fault if the caller happens to be paged out between the calls to **KeSetEvent** and **KeWaitForSingleObject** or **KeWaitForMultipleObjects**. + +Any standard driver routine that runs at IRQL = DISPATCH\_LEVEL cannot wait for a nonzero interval on any dispatcher objects without bringing down the system. However, such a routine can call **KeSetEvent** while running at an IRQL less than or equal to DISPATCH\_LEVEL. + +For a summary of the IRQLs at which standard driver routines run, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +**KeResetEvent** returns the previous state of a given *Event*: whether it was set to Signaled or not when the call to **KeResetEvent** occurred. **KeClearEvent** simply sets the state of the given *Event* to Not-Signaled. + +**Consider the following guideline for when to call the preceding support routines:** + +For better performance, every driver should call **KeClearEvent** unless the caller needs the information returned by **KeResetEvent** to determine what to do next. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20and%20Using%20an%20Event%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-custom-error-types.md b/windows-driver-docs-pr/kernel/defining-custom-error-types.md new file mode 100644 index 0000000000..92fe82af4f --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-custom-error-types.md @@ -0,0 +1,145 @@ +--- +title: Defining Custom Error Types +author: windows-driver-content +description: Defining Custom Error Types +ms.assetid: 1106b520-8737-421b-bee5-841220862b78 +keywords: ["custom error messages WDK kernel", "custom error types WDK kernel", "IO_ERR_XXX values", "templates WDK errors", "headers WDK errors", "files WDK error logs", "text files WDK error logs", "compiling error message files", "LanguageNames directive", "SeverityNames directive", "FacilityNames directive"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining Custom Error Types + + +## + + +Drivers can specify their own error types and error messages. To define a custom error message, you must first define a new IO\_ERR\_*XXX* value to specify as the **ErrorCode** member of the error log entry. The Event Viewer uses the IO\_ERR\_*XXX* value to look up the driver's error message. + +To support custom error messages in your driver, follow these steps: + +1. Create a message text file that specifies the custom IO\_ERR\_*XXX* value and the corresponding error messages. For further information, see [Creating the Error Message Text File](#ddk-creating-the-error-message-text-file-kg). + +2. Compile the error message text file to a resource, and attach the resource to the driver image. For further information, see [Compiling the Error Message Text File](#ddk-compiling-the-error-message-text-file-kg). + +3. Register the driver image as containing error messages. For further information, see [Registering as a Source of Error Messages](registering-as-a-source-of-error-messages.md). + +### Creating the Error Message Text File + +The definition of a driver's custom IO\_ERR\_*XXX* values and matching error message templates are attached as a message table resource to the driver image. You can describe the messages for a driver in a message text file (which has an .mc file name extension). + +A message text file consists of two sections: a header section and a message section. The header section permits the declaration of symbolic names for numerical values, while the message section specifies the IO\_ERR\_*XXX* values and matching error message templates. + +For an example of a message text file, see the Serlog.mc file in the [Serial driver sample](http://go.microsoft.com/fwlink/p/?LinkId=617962) available on GitHub. + +### Header Section + +The header section must contain this line: + +``` +MessageIdTypedef=NTSTATUS +``` + +This ensures that the type of IO\_ERR\_*XXX* values generated by the Message Compiler is declared to be NTSTATUS. + +The other directives that appear in the header section define symbolic values that are used in place of numeric values in the message section. + +The **SeverityNames** and **FacilityNames** directives define symbolic values for the severity and facility fields of NTSTATUS values. The directives are of the form *keyword***= (** *values* **)**, where *values* consists of one or more statements of the form *name* **=** *value* **:** *header\_name*, separated by white space. The *name* parameter is the name you use the specify the numeric *value* in the message text file, while the *header\_name* is the name for this value declared in the C header file generated by the Message Compiler. The **:** *header\_name* clause is optional. + +Here is an example of a header declaration of symbolic names for severity codes: + +``` +SeverityNames = ( + Success = 0x0:STATUS_SEVERITY_SUCCESS + Informational = 0x1:STATUS_SEVERITY_INFORMATIONAL + Warning = 0x2:STATUS_SEVERITY_WARNING + Error = 0x3:STATUS_SEVERITY_ERROR +) +``` + +The **LanguageNames** directive defines symbolic values for locale IDs (LCID). The directive is of the form **LanguageNames = (** *values* **)**, where *values* consists of one or more statements of the form *language\_name* **=** *lcid* **:** *langfile*, separated by white space. The *language\_name* parameter is the name you use in place of *lcid* in the message text file, while the *filename* specifies a unique file name (without extension). When the Message Compiler generates the resource script from the message text file, it stores all of the string resources for this language in a file named *langfile*.*bin*. + +### Message Section + +Each message definition begins with the definition of the custom IO\_ERR\_*XXX* value that the driver uses to report this particular type of error. The IO\_ERR\_*XXX* value is defined by a series of *keyword* = *value* pairs. The possible keywords and their meaning are as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordValue

MessageId

Code field of the new IO_ERR_XXX value.

Severity

Severity field of the new IO_ERR_XXX value. The specified value must be one of the symbolic names defined by the SeverityNames header directive.

Facility

Facility field of the new IO_ERR_XXX value. The specified value must be one of the symbolic names defined by the FacilityNames header directive.

SymbolicName

The symbolic name for the new IO_ERR_XXX value. The Message Compiler generates a C header file that contains a #define declaration of the name as the corresponding NTSTATUS value. The driver uses that name when specifying the error type.

+ +  + +The first keyword must always be **MessageId**. + +The rest of the message definition consists of one or more localized versions of the error message. Each version is of the form: + +``` +Language=language_name +localized_message +``` + +The *language\_name* value, which must be one of the symbolic names defined by the **LanguageNames** header directive, specifies the language of the message text. The localized message text itself consists of a Unicode string. Any embedded strings of the form "%*n*" will be treated as templates that the Event Viewer will replace when the error is logged. The "%1" string is replaced with the name of the driver's device object, while "%2" through "%*n*" are replaced with any insertion strings provided by the driver. + +The message definition is terminated by a single period alone on a line. + +If you define custom error messages, you should not use insertion strings unless necessary. Insertion strings cannot be localized, so they should be used for strings that are language-independent, such as numbers or file names. Most drivers do not use insertion strings. + +### Compiling the Error Message Text File + +Use the Message Compiler (mc.exe) to compile your message text file into a resource script file (which has an .rc file name extension). A command of the form + +``` +mc filename.mc +``` + +causes the Message Compiler to generate the following files: + +- *filename*.h, a header file that contains declarations of each custom IO\_ERR\_*XXX* value in *filename*.*mc*. + +- *filename*.rc, a resource script. + +- One file for each language that appears in the message text file. Each of these files stores all of the error message string resources for one language. The file for each language is named *langfile*.*bin*, where *langfile* is the value specified for the language in the message text file's **LanguageNames** directive. + +More information about the Message Compiler can be found in the Microsoft Windows SDK. + +The Resource Compiler converts a resource script to a resource file that you can attach to your driver image. If you use the Build utility to build your driver, you can make sure that the resource script is converted to a resource file and attached to your driver image simply by including the name of the resource script in the SOURCES variable for the driver. For more information about the Resource Compiler, see the Windows SDK documentation. For information about using the Build utility to build your driver, see [Building a Driver](https://msdn.microsoft.com/windows-drivers/develop/building_a_driver). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20Custom%20Error%20Types%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-i-o-control-codes.md b/windows-driver-docs-pr/kernel/defining-i-o-control-codes.md new file mode 100644 index 0000000000..43ab8da09c --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-i-o-control-codes.md @@ -0,0 +1,129 @@ +--- +title: Defining I/O Control Codes +author: windows-driver-content +description: Defining I/O Control Codes +ms.assetid: 967b0199-e9a0-4c8d-9130-c81436c59ca3 +keywords: ["I/O control codes WDK kernel , defining", "control codes WDK IOCTLs , defining", "IOCTLs WDK kernel , defining", "CTL_CODE macro", "IOCTLs WDK user-mode", "user-mode components WDK IOCTLs", "I/O control codes WDK user-mode", "control codes WDK user-mode", "layouts WDK IOCTLs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining I/O Control Codes + + +## + + +When defining new IOCTLs, it is important to remember the following rules: + +- If a new IOCTL will be available to user-mode software components, the IOCTL must be used with [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests. User-mode components send **IRP\_MJ\_DEVICE\_CONTROL** requests by calling the [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216), which is a Win32 function. +- If a new IOCTL will be available only to kernel-mode driver components, the IOCTL must be used with [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests. Kernel-mode components create **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests by calling **IoBuildDeviceIoControlRequest**. For more information, see [Creating IOCTL Requests in Drivers](creating-ioctl-requests-in-drivers.md). + +An I/O control code is a 32-bit value that consists of several fields. The following figure illustrates the layout of I/O control codes. + +![diagram illustrating the i/o control code layout](images/ioctl-1.png) + +Use the system-supplied **CTL\_CODE** macro, which is defined in Wdm.h and Ntddk.h, to define new I/O control codes. The definition of a new IOCTL code, whether intended for use with **IRP\_MJ\_DEVICE\_CONTROL** or **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests, uses the following format: + +``` +#define IOCTL_Device_Function CTL_CODE(DeviceType, Function, Method, Access) +``` + +Choose a descriptive constant name for the IOCTL, of the form IOCTL\_*Device*\_*Function*, where *Device* indicates the type of device and *Function* indicates the operation. An example constant name is IOCTL\_VIDEO\_ENABLE\_CURSOR. + +Supply the following parameters to the **CTL\_CODE** macro: + +*DeviceType* +Identifies the device type. This value must match the value that is set in the **DeviceType** member of the driver's [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. (See [Specifying Device Types](specifying-device-types.md)). Values of less than 0x8000 are reserved for Microsoft. Values of 0x8000 and higher can be used by vendors. Note that the vendor-assigned values set the **Common** bit. + +*FunctionCode* +Identifies the function to be performed by the driver. Values of less than 0x800 are reserved for Microsoft. Values of 0x800 and higher can be used by vendors. Note that the vendor-assigned values set the **Custom** bit. + +*TransferType* +Indicates how the system will pass data between the caller of [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) (or [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318)) and the driver that handles the IRP. + +Use one of the following system-defined constants: + +METHOD\_BUFFERED +Specifies the [buffered I/O](methods-for-accessing-data-buffers.md) method, which is typically used for transferring small amounts of data per request. Most I/O control codes for device and intermediate drivers use this *TransferType* value. + +For information about how the system specifies data buffers for METHOD\_BUFFERED I/O control codes, see [Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md). + +For more information about buffered I/O, see [Using Buffered I/O](using-buffered-i-o.md). + +METHOD\_IN\_DIRECT or METHOD\_OUT\_DIRECT +Specifies the [direct I/O](methods-for-accessing-data-buffers.md) method, which is typically used for reading or writing large amounts of data, using DMA or PIO, that must be transferred quickly. + +Specify METHOD\_IN\_DIRECT if the caller of [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) or **IoBuildDeviceIoControlRequest** will pass data to the driver. + +Specify METHOD\_OUT\_DIRECT if the caller of [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) or **IoBuildDeviceIoControlRequest** will receive data from the driver. + +For information about how the system specifies data buffers for METHOD\_IN\_DIRECT and METHOD\_OUT\_DIRECT I/O control codes, see [Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md). + +For more information about direct I/O, see [Using Direct I/O](using-direct-i-o.md). + +METHOD\_NEITHER +Specifies [neither buffered nor direct I/O](using-neither-buffered-nor-direct-i-o.md). The I/O manager does not provide any system buffers or MDLs. The IRP supplies the user-mode virtual addresses of the input and output buffers that were specified to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) or **IoBuildDeviceIoControlRequest**, without validating or mapping them. + +For information about how the system specifies data buffers for METHOD\_NEITHER I/O control codes, see [Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md). + +This method can be used only if the driver can be guaranteed to be running in the context of the thread that originated the I/O control request. Only a highest-level kernel-mode driver is guaranteed to meet this condition, so METHOD\_NEITHER is seldom used for the I/O control codes that are passed to low-level device drivers. + +With this method, the highest-level driver must determine whether to set up buffered or direct access to user data on receipt of the request, possibly must lock down the user buffer, and must wrap its access to the user buffer in a structured exception handler (see [Handling Exceptions](handling-exceptions.md)). Otherwise, the originating user-mode caller might change the buffered data before the driver can use it, or the caller could be swapped out just as the driver is accessing the user buffer. + +For more information, see [Using Neither Buffered Nor Direct I/O](using-neither-buffered-nor-direct-i-o.md). + +*RequiredAccess* +Indicates the type of access that a caller must request when opening the file object that represents the device (see [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729)). The I/O manager will create IRPs and call the driver with a particular I/O control code only if the caller has requested the specified access rights. *RequiredAccess* is specified by using the following system-defined constants: + +FILE\_ANY\_ACCESS +The I/O manager sends the IRP for any caller that has a handle to the file object that represents the target device object. + +FILE\_READ\_DATA +The I/O manager sends the IRP only for a caller with read access rights, allowing the underlying device driver to transfer data from the device to system memory. + +FILE\_WRITE\_DATA +The I/O manager sends the IRP only for a caller with write access rights, allowing the underlying device driver to transfer data from system memory to its device. + +FILE\_READ\_DATA and FILE\_WRITE\_DATA can be ORed together if the caller must have both read and write access rights. + +Some system-defined I/O control codes have a *RequiredAccess* value of FILE\_ANY\_ACCESS, which allows the caller to send the particular IOCTL regardless of the access granted to the device. Examples include I/O control codes that are sent to drivers of [*exclusive devices*](https://msdn.microsoft.com/library/windows/hardware/ff556279#wdkgloss-exclusive-device). + +Other system-defined I/O control codes require the caller to have read access rights, write access rights, or both. For example, the following definition of the public I/O control code IOCTL\_DISK\_SET\_PARTITION\_INFO shows that this I/O request can be sent to a driver only if the caller has both read and write access rights: + +``` +#define IOCTL_DISK_SET_PARTITION_INFO\ + CTL_CODE(IOCTL_DISK_BASE, 0x008, METHOD_BUFFERED,\ + FILE_READ_DATA | FILE_WRITE_DATA) +``` + +**Note**   Before specifying FILE\_ANY\_ACCESS for a new IOCTL code, you must be absolutely certain that allowing unrestricted access to your device does not create a possible path for malicious users to compromise the system. + +  + +Drivers can use [**IoValidateDeviceIoControlAccess**](https://msdn.microsoft.com/library/windows/hardware/ff550418) to perform stricter access checking than that provided by an IOCTL's *RequiredAccess* bits. + +## Other useful macros + + +The following macros are useful for extracting the 16-bit *DeviceType* and 2-bit *TransferType* fields from an IOCTL code: + +``` +#define DEVICE_TYPE_FROM_CTL_CODE(ctrlCode) (((ULONG)(ctrlCode & 0xffff0000)) >> 16) +#define METHOD_FROM_CTL_CODE(ctrlCode) ((ULONG)(ctrlCode & 3)) +``` + +These macros are defined in Wdm.h and Ntddk.h. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20I/O%20Control%20Codes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-new-ntstatus-values.md b/windows-driver-docs-pr/kernel/defining-new-ntstatus-values.md new file mode 100644 index 0000000000..bc392e3cde --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-new-ntstatus-values.md @@ -0,0 +1,64 @@ +--- +title: Defining New NTSTATUS Values +author: windows-driver-content +description: Defining New NTSTATUS Values +ms.assetid: 44211ae4-6bfe-4931-b12c-e590c7aacd97 +keywords: ["NTSTATUS values WDK kernel", "custom NTSTATUS values WDK kernel", "IO_ERR_XXX values"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining New NTSTATUS Values + + +## + + +Drivers can define custom IO\_ERR\_*XXX* constants to use as **ErrorCode** values when logging errors. Pairs of drivers that are written together can also define custom STATUS\_*XXX* values for [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests. + +The following diagram shows the bit fields in a 32-bit NTSTATUS value. + +![diagram illustrating the bit fields in an ntstatus value](images/16ntstat.png) + +The **Sev** field shown in the preceding diagram indicates the severity code, which must be one of the following system-defined values: + +STATUS\_SEVERITY\_SUCCESS +Indicates a successful NTSTATUS value, such as STATUS\_SUCCESS, or the value IO\_ERR\_RETRY\_SUCCEEDED in error log packets. + +STATUS\_SEVERITY\_INFORMATIONAL +Indicates an informational NTSTATUS value, such as STATUS\_SERIAL\_MORE\_WRITES. + +STATUS\_SEVERITY\_WARNING +Indicates a warning NTSTATUS value, such as STATUS\_DEVICE\_PAPER\_EMPTY. + +STATUS\_SEVERITY\_ERROR +Indicates an error NTSTATUS value, such as STATUS\_INSUFFICIENT\_RESOURCES for a **FinalStatus** value or IO\_ERR\_CONFIGURATION\_ERROR for an **ErrorCode** value in error log packets. + +Most public IO\_ERR\_*XXX* constants belong to the STATUS\_SEVERITY\_ERROR category. + +The **Facility** code specifies the facility that generated the error. For new IO\_ERR\_*XXX* values, drivers specify the FACILITY\_IO\_ERROR\_CODE value for **Facility**. For custom STATUS\_*XXX* values, the meaning of different values for **Facility** is driver-defined. + +The **C** bit specifies if the value is customer-defined or Microsoft-defined. The bit is set for customer-defined values and clear for Microsoft-defined values. + +Drivers can define new IO\_ERR\_*XXX* values to identify custom error messages in the system event log. For a description of how to define the NTSTATUS values and the error messages that they identify, see [Defining Custom Error Types](defining-custom-error-types.md). + +Pairs of drivers can define driver-specific STATUS\_*XXX* values to communicate information about privately defined [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests from the lower to the higher driver of the pair. + +The class driver must map any private STATUS\_*XXX* value to a system-defined NTSTATUS value when it completes an IRP if an existing higher-level driver's [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine might be called for that IRP. + +For paired display and video miniport drivers, the video port driver does the mapping between public STATUS\_*XXX* values and the Win32-defined constants returned by video miniport drivers. For more information, see [Video Miniport Drivers in the Windows 2000 Display Driver Model](https://msdn.microsoft.com/library/windows/hardware/ff570509). + +Drivers cannot use custom NTSTATUS values for IRPs that can be received in user mode, because only the system-defined values can be translated into Win32 error codes. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20New%20NTSTATUS%20Values%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/defining-wmi-instance-names.md b/windows-driver-docs-pr/kernel/defining-wmi-instance-names.md new file mode 100644 index 0000000000..1b0f73c1f6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/defining-wmi-instance-names.md @@ -0,0 +1,56 @@ +--- +title: Defining WMI Instance Names +author: windows-driver-content +description: Defining WMI Instance Names +ms.assetid: 0f91710a-7bd2-462a-b677-6dd32160a861 +keywords: ["WMI WDK kernel , event blocks", "event blocks WDK WMI", "data blocks WDK WMI", "WMI WDK kernel , data blocks", "blocks WDK WMI", "dynamic instance names WDK WMI", "static instance names WDK WMI", "instance names WDK WMI", "WMI WDK kernel , instance names"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Defining WMI Instance Names + + +## + + +An *instance* of a WMI block contains data supplied by a particular physical device or software component. Just as a block's GUID uniquely identifies the block, an instance's name uniquely identifies that instance of a block. WMI client applications use instance names to associate the information returned in a data block with the device or component that supplied the data. WMI uses instance names to determine which device a request should be sent to. It is strongly recommended that drivers use their PDO when defining instance names. + +A driver can define instance names for a block in either of two ways: + +- The driver passes a list of *static instance names* to WMI when it registers the block. + + After the block is registered, both the driver and WMI specify an instance name by its index into this list. Static instance names can be based on the [*device instance ID*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-instance-id) of a driver's PDO, or a driver-defined base name; or the driver can define a list of instance name strings. Static instance names persist until the driver explicitly changes them by reregistering the block. + +- The driver generates *dynamic instance names* as instances are created. + + The driver indicates that it will generate dynamic instance names for a block when it registers the block. After the block is registered, both the driver and WMI pass dynamic instance names as strings in the buffer at **Parameters.WMI.Buffer**. + +A driver should generate dynamic instance names only if the number of instances or instance names of a data block change frequently at runtime. For example, a driver might use process IDs or the IP addresses of TCP/IP connections as instance names. Such instance names should be dynamic; if they were static, the driver would incur considerable overhead because it would have to call [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) to update the number and names of instances each time a change occurred. + +In most cases, static instance names are preferable to dynamic instance names for the following reasons: + +- Static instance names improve a driver's performance because the driver does not need to return instance name strings in response to WMI requests, as it must for dynamic instance names. + +- WMI can detect static instance name collisions at registration and automatically modify the instance names if necessary, so that all instance names are unique for a given block no matter how many drivers register the block. + + WMI cannot detect instance name collisions for dynamic instance names, so the driver is responsible for generating unique names using [**IoWMIAllocateInstanceIds**](https://msdn.microsoft.com/library/windows/hardware/ff550429). + +- A driver can use the WMI Library routines to handle IRPs for a block that uses static instance names, as long as the names are based on the driver's PDO or a driver-defined base name. + + A driver cannot use WMI Library routines to handle IRPs for a data block that uses dynamic instance names. + +A driver indicates whether a block uses static or dynamic instance names, and the type of static instance names, by setting or clearing WMIREG\_FLAG\_*XXX* in the [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) or [**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) structure it passes to WMI when it registers the block. For more information, see [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Defining%20WMI%20Instance%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/deleting-a-system-allocated-timer-object.md b/windows-driver-docs-pr/kernel/deleting-a-system-allocated-timer-object.md new file mode 100644 index 0000000000..9b3aa7d976 --- /dev/null +++ b/windows-driver-docs-pr/kernel/deleting-a-system-allocated-timer-object.md @@ -0,0 +1,58 @@ +--- +title: Deleting a System-Allocated Timer Object +author: windows-driver-content +description: Starting with Windows 8.1, the ExDeleteTimer routine deletes a timer object that was created by the ExAllocateTimer routine. +ms.assetid: 7D119448-3890-4E8F-BC79-7FEB3213B693 +keywords: ["ExXxxTimer routines", "ExAllocateTimer", "ExDeleteTimer", "ExSetTimer", "ExCancelTimer", "ExTimerCallback", "ExTimerDeleteCallback", "EX_TIMER"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Deleting a System-Allocated Timer Object + + +Starting with Windows 8.1, the [**ExDeleteTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265181) routine deletes a timer object that was created by the [**ExAllocateTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265179) routine. This timer object is a system-allocated [**EX\_TIMER**](https://msdn.microsoft.com/library/windows/hardware/dn265199) structure whose members are opaque to drivers. Before a timer object is deleted, **ExDeleteTimer** disables further timer operations on the object, and cancels or completes any pending operation on the object that might be in progress. + +After a driver calls **ExDeleteTimer**, this routine takes several steps to ensure that it can safely delete the timer object. First, **ExDeleteTimer** marks the timer object as disabled to prevent the driver from starting a new timer operation that uses the object. After the timer object is disabled, a call to the [**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) or [**ExCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265180) routine immediately returns **FALSE** and performs no operation. Also, a second call to **ExDeleteTimer** returns **FALSE** and performs no operation. + +Next, **ExDeleteTimer** checks whether a timer is still pending from a previous call to **ExDeleteTimer**. Disabling a timer object does not cancel a timer that was set before the object was disabled. In either of the following two cases, a timer that was previously set might expire after the timer object is disabled: + +- The timer is periodic. +- The timer is one-shot (or nonperiodic) and has not yet expired. + +A periodic timer can never expire more than once after the timer object is disabled. + +If your driver implements an [*ExTimerCallback*](https://msdn.microsoft.com/library/windows/hardware/dn265190) callback routine, the *Timer* parameter to this routine is guaranteed to always be a valid pointer to the timer object (an **EX\_TIMER** structure), even if the timer expires after the timer object is disabled. + +If no timer is pending, **ExDeleteTimer** deletes the timer object and returns without waiting. + +If a timer is pending when **ExDeleteTimer** is called, the *Cancel* and *Wait* parameter values that your driver supplies to this routine control the routine's behavior. The *Cancel* parameter tells **ExDeleteTimer** whether to try to cancel a pending timer. The *Wait* parameter tells **ExDeleteTimer** whether to wait to return until the timer object is deleted. + +If *Cancel* is **FALSE** (in which case, *Wait* must be **FALSE**) and a timer is pending, **ExDeleteTimer** lets the timer expire before the timer object is deleted. In this case, **ExDeleteTimer** marks the timer object to indicate that it is to be deleted after the pending timer expires (and any last callback to the *ExTimerCallback* routine finishes). Then **ExDeleteTimer** returns without waiting either for the timer to finish expiring or for the object to be deleted. + +If *Cancel* is **TRUE**, **ExDeleteTimer** tries to cancel a pending timer before it expires. **ExDeleteTimer** returns **TRUE** if it successfully cancels the timer. **ExDeleteTimer** returns **FALSE** if it cannot cancel the timer, which is the case for a one-shot timer that has already expired or is in the process of expiring. **ExDeleteTimer** also returns **FALSE** if the (one-shot or periodic) timer was canceled before the **ExDeleteTimer** call or if the timer was never set. + +If *Cancel* is **TRUE** and *Wait* is **FALSE**, **ExDeleteTimer** never blocks the calling thread. If the timer object cannot be immediately deleted, **ExDeleteTimer** marks the timer object to indicate that it is to be deleted after the pending timer finishes expiring, and returns immediately without waiting either for the timer to expire or for the object to be deleted. + +If *Cancel* and *Wait* are both **TRUE**, **ExDeleteTimer** blocks the calling thread if the timer object cannot be immediately deleted. **ExDeleteTimer** waits, if necessary, for the timer to finish expiring and for any callback to a driver-implemented *ExTimerCallback* routine to finish. Next, **ExDeleteTimer** deletes the timer object and calls the [*ExTimerDeleteCallback*](https://msdn.microsoft.com/library/windows/hardware/dn265192) routine, if the driver implements this routine. Finally, **ExDeleteTimer** returns. + +A driver can call **ExDeleteTimer** from the driver's *ExTimerCallback* routine, which runs at IRQL = DISPATCH\_LEVEL, but the driver must set the *Wait* parameter in this call to **FALSE**. + +As an option, a driver can implement an *ExTimerDeleteCallback* callback routine that runs after a timer object is deleted. Typically, an *ExTimerDeleteCallback* routine frees any system resources that the driver allocated to use with the timer object. + +**ExDeleteTimer** schedules a driver-implemented *ExTimerDeleteCallback* routine to run after the timer object is deleted, at which time the pointer to this object is no longer valid. If the *Wait* parameter is **TRUE** in the **ExDeleteTimer** call, the callback to the *ExTimerDeleteCallback* routine finishes before **ExDeleteTimer** returns. If *Wait* is **FALSE**, the *ExTimerDeleteCallback* routine might run before or after **ExDeleteTimer** returns. + +For more information, see [Ex*Xxx*Timer Routines and EX\_TIMER Objects](exxxxtimer-routines-and-ex-timer-objects.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Deleting%20a%20System-Allocated%20Timer%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/design-goals-for-kernel-mode-drivers.md b/windows-driver-docs-pr/kernel/design-goals-for-kernel-mode-drivers.md new file mode 100644 index 0000000000..84ce1c100c --- /dev/null +++ b/windows-driver-docs-pr/kernel/design-goals-for-kernel-mode-drivers.md @@ -0,0 +1,44 @@ +--- +title: Design Goals for Kernel-Mode Drivers +author: windows-driver-content +description: Design Goals for Kernel-Mode Drivers +ms.assetid: 2799556e-0359-4388-acf3-74d90eb86a0f +keywords: ["kernel-mode drivers WDK , design goals"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Design Goals for Kernel-Mode Drivers + + +## + + +Kernel-mode drivers share many of the design goals of the operating system, particularly those of the system I/O manager. Kernel-mode drivers are designed to be: + +- [Portable](portable.md) from one platform to another. + +- [Configurable](configurable.md) to various hardware and software platforms. + +- [Always preemptible and always interruptible](always-preemptible-and-always-interruptible.md). + +- [Multiprocessor-safe](multiprocessor-safe.md) on multiprocessor platforms. + +- [Object-based](object-based.md). + +- [Packet-driven I/O with reusable IRPs](packet-driven-i-o-with-reusable-irps.md). + +- Capable of [supporting asynchronous I/O](supporting-asynchronous-i-o.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Design%20Goals%20for%20Kernel-Mode%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/design-guidelines-for-starting-devices.md b/windows-driver-docs-pr/kernel/design-guidelines-for-starting-devices.md new file mode 100644 index 0000000000..49ccf2a4c9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/design-guidelines-for-starting-devices.md @@ -0,0 +1,28 @@ +--- +title: Design Guidelines for Starting Devices +author: windows-driver-content +description: Design Guidelines for Starting Devices +ms.assetid: fbdde107-f3a5-4713-a4ac-1c9bafa3c634 +--- + +# Design Guidelines for Starting Devices + + +## + + +- The PnP manager fails create requests for the device until the [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) IRP completes, indicating that all the drivers for the device have performed their start operations. + +- Because a [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine runs in the context of a system thread at IRQL PASSIVE\_LEVEL, any memory allocated with [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) for use exclusively during initialization can be from paged pool as long as the driver does not control the device that holds a system page file. Such a memory allocation must be released with [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) before the *DispatchPnP* routine returns control. + +- A WDM device driver's ISR should be capable of determining whether it has been called with a spurious interrupt even during device startup. On return from the call to [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371) in the code path that handles **IRP\_MN\_START\_DEVICE**, the ISR can be called immediately if interrupts are enabled on the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Design%20Guidelines%20for%20Starting%20Devices%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/designing-wmi-data-and-event-blocks.md b/windows-driver-docs-pr/kernel/designing-wmi-data-and-event-blocks.md new file mode 100644 index 0000000000..c3c639d46e --- /dev/null +++ b/windows-driver-docs-pr/kernel/designing-wmi-data-and-event-blocks.md @@ -0,0 +1,30 @@ +--- +title: Designing WMI Data and Event Blocks +author: windows-driver-content +description: Designing WMI Data and Event Blocks +ms.assetid: 3235accd-2bec-430e-ab00-1c5d0ef46045 +keywords: ["WMI WDK kernel , event blocks", "event blocks WDK WMI", "data blocks WDK WMI", "WMI WDK kernel , data blocks", "blocks WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Designing WMI Data and Event Blocks + + +## + + +For best performance and ease of use by WMI clients, a driver should support standard data blocks, and driver writers should follow certain guidelines in designing custom WMI data and event blocks. In particular, driver writers should be aware of performance tradeoffs in choosing static versus dynamic instance names for data blocks. The topics in this section discuss issues and guidelines for designing WMI data and event blocks. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Designing%20WMI%20Data%20and%20Event%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/detecting-an-idle-device.md b/windows-driver-docs-pr/kernel/detecting-an-idle-device.md new file mode 100644 index 0000000000..42cf6fa289 --- /dev/null +++ b/windows-driver-docs-pr/kernel/detecting-an-idle-device.md @@ -0,0 +1,34 @@ +--- +title: Detecting an Idle Device +author: windows-driver-content +description: Detecting an Idle Device +ms.assetid: 69de45de-6c27-4ada-bd5e-369da0bd612a +keywords: ["idle detection WDK power management", "power management WDK kernel , idle detection", "conserving power WDK kernel", "sleep power management WDK kernel", "asleep devices WDK power management", "detecting idle devices"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Detecting an Idle Device + + +## + + +The power policy owner for each device is responsible for determining when the device is idle and can be put to sleep to conserve power. The policy owner has two options for detecting an idle device: + +[Use Power Manager routines for idle detection](using-power-manager-routines-for-idle-detection.md) + +[Perform device-specific idle detection](performing-device-specific-idle-detection.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Detecting%20an%20Idle%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/detecting-code-that-can-be-pageable.md b/windows-driver-docs-pr/kernel/detecting-code-that-can-be-pageable.md new file mode 100644 index 0000000000..a61b22b8c2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/detecting-code-that-can-be-pageable.md @@ -0,0 +1,48 @@ +--- +title: Detecting Code That Can Be Pageable +author: windows-driver-content +description: Detecting Code That Can Be Pageable +ms.assetid: 5e8a021d-09c3-4e63-b5a8-7559c384ae3d +keywords: ["pageable drivers WDK kernel , code detection", "detecting pageable code"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Detecting Code That Can Be Pageable + + +## + + +To detect code that runs at IRQL >= DISPATCH\_LEVEL, use the [**PAGED\_CODE**](https://msdn.microsoft.com/library/windows/hardware/ff558773) macro. In debug mode, this macro generates a message if the code runs at IRQL >= DISPATCH\_LEVEL. Add the macro as the first statement in a routine to mark the whole routine as paged code, as the following example shows: + +``` +NTSTATUS +MyDriverXxx( + IN OUT PVOID ParseContext OPTIONAL, + OUT PHANDLE Handle + ) +{ + NTSTATUS Status; + + PAGED_CODE(); +. +. +. +} +``` + +To make sure that you are doing this correctly, run the [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) against your finished driver with the **Force IRQL Checking** option enabled. This option causes the system to automatically page out all pageable code every time that the driver raises IRQL to DISPATCH\_LEVEL or above. Using the Driver Verifier, you can quickly find any driver bugs in this area. Otherwise, these bugs will typically be found only by customers and they can frequently be very hard for you to reproduce. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Detecting%20Code%20That%20Can%20Be%20Pageable%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/determining-the-correct-device-power-state.md b/windows-driver-docs-pr/kernel/determining-the-correct-device-power-state.md new file mode 100644 index 0000000000..6a31cf54cb --- /dev/null +++ b/windows-driver-docs-pr/kernel/determining-the-correct-device-power-state.md @@ -0,0 +1,42 @@ +--- +title: Determining the Correct Device Power State +author: windows-driver-content +description: Determining the Correct Device Power State +ms.assetid: 4acefe93-1d7a-4c12-8701-03c2a8929591 +keywords: ["DEVICE_CAPABILITIES structure", "correct device power states WDK power management", "device power states WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining the Correct Device Power State + + +## + + +The power policy owner checks the [**DeviceState**](devicestate.md) array in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure to determine the valid range of device power states for each system power state. The array lists the highest device power state the underlying device can support for each system power state. + +When choosing a specific state from this range, consider the following: + +- Most devices enter the D0 state when the system enters the S0 state. + +- Most devices enter the D3 state when the system enters any sleeping state. However, a device that is enabled for wake-up might be required to enter D1 or D2 instead, if it supports such states. For further information, see [Reporting Device Power Capabilities](reporting-device-power-capabilities.md). + +- Special rules apply for the device that will hold the hibernation file. If the system IRP requests **PowerSystemHibernate**, the device that will hold the hibernation file must not power off. The power policy owner for such a device should request device power state D3 and save context, but the device's drivers must not power off the device. + +If the system IRP requests **PowerSystemShutdown**, the driver should check the POWER\_ACTION value at **Irp->Parameters.Power.ShutdownType** to determine the reason for the state change. For further information, see [System Power Actions](system-power-actions.md). + +The device power policy owner must send a device set-power IRP for each system set-power IRP, even if the device is already in the correct device power state. If the driver previously suspended device operations in response to a query-power IRP, the set-power IRP notifies it to stop queuing IRPs and return to normal operation for its current power state. The only exception occurs when the device is in the D3 state; in this case, the driver need not send an additional [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request for D3. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Determining%20the%20Correct%20Device%20Power%20State%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/determining-the-wdm-version.md b/windows-driver-docs-pr/kernel/determining-the-wdm-version.md new file mode 100644 index 0000000000..7b9f3a8794 --- /dev/null +++ b/windows-driver-docs-pr/kernel/determining-the-wdm-version.md @@ -0,0 +1,32 @@ +--- +title: Determining the WDM Version +author: windows-driver-content +description: Determining the WDM Version +ms.assetid: 7ed288d9-6447-4b08-baf2-e7b743654ebd +keywords: ["WDM drivers WDK kernel , versions", "versions WDK WDM", "compatibility WDK WDM", "cross-system compatibility WDK WDM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining the WDM Version + + +## + + +A cross-system WDM driver should use the [**IoIsWdmVersionAvailable**](https://msdn.microsoft.com/library/windows/hardware/ff549382) routine to determine which version of WDM is supported by the system on which it is running. The reference page for **IoIsWdmVersionAvailable** provides a list of WDM version numbers. + +For information about differences in WDM that drivers should handle, see [Differences in WDM Versions](differences-in-wdm-versions.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Determining%20the%20WDM%20Version%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/determining-when-to-send-a-wait-wake-irp.md b/windows-driver-docs-pr/kernel/determining-when-to-send-a-wait-wake-irp.md new file mode 100644 index 0000000000..28fadafcbb --- /dev/null +++ b/windows-driver-docs-pr/kernel/determining-when-to-send-a-wait-wake-irp.md @@ -0,0 +1,36 @@ +--- +title: Determining When to Send a Wait/Wake IRP +author: windows-driver-content +description: Determining When to Send a Wait/Wake IRP +ms.assetid: a56cfccc-b44b-4ec5-836b-3a9711ef5f1f +keywords: ["timing wait/wake IRPs WDK power management", "sending wait/wake IRPs", "wait/wake IRPs WDK power management , sending"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining When to Send a Wait/Wake IRP + + +## + + +The driver that owns device power policy sends wait/wake IRPs on behalf of its device. Such a driver must send a wait/wake IRP when one of the following occurs: + +- The driver is putting the device to sleep but the device must be able to wake up in response to an external wake-up signal. + +- The system is going to sleep and the device must be able to awaken it. + +The power policy owner should send the wait/wake IRP before any such conditions are imminent. It can send the IRP any time its device is in D0, but it must not send such an IRP while it is handling another set-power or query-power IRP. As a general rule, the driver should send the IRP during its handling of the Plug and Play manager's [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, after it has initialized and started the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Determining%20When%20to%20Send%20a%20Wait/Wake%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/determining-whether-a-device-can-wake-the-system.md b/windows-driver-docs-pr/kernel/determining-whether-a-device-can-wake-the-system.md new file mode 100644 index 0000000000..f782904701 --- /dev/null +++ b/windows-driver-docs-pr/kernel/determining-whether-a-device-can-wake-the-system.md @@ -0,0 +1,97 @@ +--- +title: Determining Whether a Device Can Wake the System +author: windows-driver-content +description: Determining Whether a Device Can Wake the System +ms.assetid: 59f23035-4169-4dd4-ac60-882c32efda2c +keywords: ["wait/wake IRPs WDK power management , devices with wake capability", "power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining Whether a Device Can Wake the System + + +## + + +Some devices, such as keyboards, modems, and network cards, can respond to external signals while in a device sleep state. As part of its power management technology, the operating system provides a way for such devices to wake a sleeping system, which can then restore its previous context. The software wake-up mechanism allows a system to awaken from any state except S5 (**PowerSystemShutdown**), depending on support in the system and device hardware and BIOS. A system in state S5 must always be rebooted. + +Although the operating system is designed to awaken from any of the intermediate sleep states, the exact wake-up capabilities vary from computer to computer and device to device. Not all computers support all system sleep states; therefore, the ability to wake from certain states is meaningless on some computers. + +Similarly, most devices neither support all device power states (D0 through D3) nor support wake-up from all the device power states that they do support. + +The sleep states that a device can enter, along with the states from which it supports wake up, are described at enumeration by the bus driver and are stored in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. The following table lists the members of this structure that are relevant to wait/wake support. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MemberDescription

[DeviceD1](deviced1-and-deviced2.md)

True if device supports state PowerDeviceD1.

[DeviceD2](deviced1-and-deviced2.md)

True if device supports state PowerDeviceD2.

[WakeFromD0](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md)

True if device can wake from PowerDeviceD0.

[WakeFromD1](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md)

True if device can wake from PowerDeviceD1.

[WakeFromD2](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md)

True if device can wake from PowerDeviceD2.

[WakeFromD3](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md)

True if device can wake from PowerDeviceD3.

[DeviceState](devicestate.md) [PowerSystemMaximum]

Specifies highest device power state that this device can support for each system power state, from PowerSystemUnspecified to PowerSystemShutdown.

[SystemWake](systemwake.md)

Specifies lowest system power state (S0 through S4) from which the system can be awakened.

[DeviceWake](devicewake.md)

Specifies lowest device power state (D0 through D3) from which the device can awaken.

+ +  + +The **DeviceWake** entry lists the lowest device power state from which the device can respond to a wake-up signal. The value PowerDeviceUnspecified indicates that the device cannot wake the system. The **SystemWake** entry lists the lowest system power state from which the system can be awakened. These values are based on the capabilities of the parent devnode and drivers should not change them. For more information, see [Reporting Device Power Capabilities](reporting-device-power-capabilities.md). + +In general, a device can wake the system if the following are true: + +- The device is in a power state equal to or more-powered than the **DeviceWake** value. + +- The system is in a power state equal to or more powered than the **SystemWake** value. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Determining%20Whether%20a%20Device%20Can%20Wake%20the%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/determining-whether-the-operating-system-is-running-in-safe-mode.md b/windows-driver-docs-pr/kernel/determining-whether-the-operating-system-is-running-in-safe-mode.md new file mode 100644 index 0000000000..af91e287ff --- /dev/null +++ b/windows-driver-docs-pr/kernel/determining-whether-the-operating-system-is-running-in-safe-mode.md @@ -0,0 +1,104 @@ +--- +title: Determining Whether the Operating System Is Running in Safe Mode +author: windows-driver-content +description: Determining Whether the Operating System Is Running in Safe Mode +ms.assetid: 5724a731-81a2-4c4e-a9e2-146859977e44 +keywords: ["Safe Mode WDK kernel", "operating system Safe Mode WDK kernel", "InitSafeBootMode", "preventing Safe Mode WDK kernel", "checking Safe Mode", "verifying Safe Mode", "startup Safe Mode WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Determining Whether the Operating System Is Running in Safe Mode + + +This topic describes how a device driver can determine whether the operating system that it is running on was started in Safe Mode. This topic also describes how to prevent a driver from operating in Safe Mode. + +The Microsoft Windows operating system kernel exports a pointer named **InitSafeBootMode**. **InitSafeBootMode** points to a ULONG variable that contains the Safe Mode settings that are currently in effect. A device driver can examine these settings to determine whether the operating system is running in Safe Mode. + +The following table lists the modes for values of the **InitSafeBootMode** variable. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueMode

0

The operating system is not in Safe Mode.

1

SAFEBOOT_MINIMAL

2

SAFEBOOT_NETWORK

3*

SAFEBOOT_DSREPAIR

+ +  + +**Note**  \* The value 3 applies to Windows domain controllers only. + +  + +To use the **InitSafeBootMode** variable, you must declare it in your driver, as the following code example shows. + +``` +extern PULONG InitSafeBootMode; +``` + +After you declare **InitSafeBootMode**, you can use the following code example to determine whether the operating system is running in Safe Mode. + +``` +if (*InitSafeBootMode > 0) { + // The operating system is in Safe Mode. + // Take appropriate action. + // +} +``` + +To prevent a driver from operating in Safe Mode, use the technique in the following list that matches your driver type: + +- **Function drivers** + + If your function driver has a service start type of SERVICE\_BOOT\_START, check the value of **InitSafeBootMode** in the function driver's *AddDevice* routine. If the system is in Safe Mode, return a failure status. + + **Note**   You must never return failure from the **DriverEntry** routine. + +   + +- **Filter drivers** + + If your filter driver starts during system startup, check the value of **InitSafeBootMode** in the filter driver's *AddDevice* routine. If the operating system is in Safe Mode, do the following: + + 1. Do not attach the filter device object to the device stack. + 2. Return success from the filter driver's *AddDevice* routine. +- **Other drivers** + + For drivers other than function or filter drivers, check the value of **InitSafeBootMode** in the driver's **DriverEntry** routine. If the operating system is in Safe Mode, return a failure status. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Determining%20Whether%20the%20Operating%20System%20Is%20Running%20in%20Safe%20Mode%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-configurations-and-layered-drivers.md b/windows-driver-docs-pr/kernel/device-configurations-and-layered-drivers.md new file mode 100644 index 0000000000..3756c89d26 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-configurations-and-layered-drivers.md @@ -0,0 +1,40 @@ +--- +title: Device Configurations and Layered Drivers +author: windows-driver-content +description: For the most common kinds of devices, the Windows Driver Kit (WDK) supplies a sample set of fully functional system drivers. +ms.assetid: 1baaac5a-8eea-42df-bad6-fe620ac32a6c +keywords: ["WDM drivers WDK kernel , configurations", "WDM drivers WDK kernel , layered drivers", "layered drivers WDK kernel", "driver layers WDK WDM", "replacing drivers", "reusable drivers WDK WDM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Configurations and Layered Drivers + + +For the most common kinds of devices, the Windows Driver Kit (WDK) supplies a sample set of fully functional system drivers. Individual sample drivers can be used as models when developing new drivers for similar kinds of devices. However, the system's drivers had an additional design requirement: to make it easy to develop new device drivers. Consequently, many of the system's drivers have a layered architecture so that certain drivers can be reused to support new drivers for similar devices. + +## + + +In most cases, the WDK-supplied reusable drivers are WDM drivers that support PnP and handle hardware-independent operations for a system-supplied device-specific lowest-level (PnP bus) driver. In some cases, such as the parallel port and SCSI port drivers, these reusable drivers provide support for higher-level, device-type-specific class drivers. Note that none of the system's reusable drivers precludes the development of new intermediate drivers to be added to a chain of existing drivers. + +Where a new (or replacement) driver fits in the chain of drivers for a device depends partly on the hardware configuration of devices in a given Windows platform, and partly on how much support a new driver can get from existing system drivers. + +## In this section + + +- [Sample Device and Driver Configuration](sample-device-and-driver-configuration.md) +- [Points to Consider When Adding Drivers](points-to-consider-when-adding-drivers.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Configurations%20and%20Layered%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-dedicated-threads.md b/windows-driver-docs-pr/kernel/device-dedicated-threads.md new file mode 100644 index 0000000000..08fee701c1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-dedicated-threads.md @@ -0,0 +1,38 @@ +--- +title: Device-Dedicated Threads +author: windows-driver-content +description: Device-Dedicated Threads +ms.assetid: 2e11e2c9-aefd-4b7b-8d80-7eb1da9f7cce +keywords: ["thread objects WDK kernel", "device-dedicated threads WDK kernel", "run-time priority inversions WDK kernel", "PsCreateSystemThread", "KeSetBasePriorityThread"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device-Dedicated Threads + + +## + + +The driver of a slow device or a device that is seldom used (like the floppy controller) can solve many "waiting" problems by creating a device-dedicated system thread. Additionally, most file system drivers use system worker threads and supply worker-thread callback routines. + +If a device driver has its own thread context or is running in a system-thread context, the device-dedicated thread or highest-level driver's worker-thread callback routine can synchronize operations on a dispatcher object, such as an [event object](event-objects.md) or [semaphore object](semaphore-objects.md), in a shared communication region of the driver's device extension. For example, a device-dedicated thread can wait for a shared dispatcher object, while the thread's device is not in use, by calling [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) for a semaphore. Until the device driver is called to carry out an I/O operation (at which point it sets the semaphore to the Signaled state), its waiting thread uses no CPU time. + +A driver can call [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932) to create a driver- or device-dedicated thread, and then call [**KeSetBasePriorityThread**](https://msdn.microsoft.com/library/windows/hardware/ff553246) to set the thread's base priority. The driver should specify a priority value that avoids *run-time priority inversions* in SMP machines. That is, setting the base priority of a driver-created thread too high can create delays in the execution of lower priority threads that submit I/O requests for that driver. + +Because thread objects are themselves a type of dispatcher object, a thread can wait for another thread to complete. To obtain the thread object pointer associated with a thread, a driver can call [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679), passing in the thread handle received from **PsCreateSystemThread**. + +A thread can call [**KeDelayExecutionThread**](https://msdn.microsoft.com/library/windows/hardware/ff551986) to wait for an interval that could be a full time slice or longer. The granularity of a **KeDelayExecutionThread** interval is around 10 milliseconds. Because **KeDelayExecutionThread** is a timer-driven routine, the granularity of its interval is slightly faster or slower than 10 milliseconds, depending on the platform. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device-Dedicated%20Threads%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-extensions.md b/windows-driver-docs-pr/kernel/device-extensions.md new file mode 100644 index 0000000000..018e20e134 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-extensions.md @@ -0,0 +1,69 @@ +--- +title: Device Extensions +author: windows-driver-content +description: Device Extensions +ms.assetid: 9ea59994-1112-4ae5-96a8-fa0670694b53 +keywords: ["device objects WDK kernel , device extensions", "device extensions WDK kernel", "extensions WDK device objects", "higher-level driver extensions WDK kernel", "lower-level driver extensions WDK kernel", "intermediate driver extensions WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Extensions + + +## + + +For most intermediate and lowest-level drivers, the device extension is the most important data structure associated with a device object. Its internal structure is driver-defined, and it is typically used to: + +- Maintain device state information. + +- Provide storage for any kernel-defined objects or other system resources, such as spin locks, used by the driver. + +- Hold any data the driver must have resident and in system space to carry out its I/O operations. + +Because most bus, function, and filter drivers (lowest-level and intermediate drivers) execute in an arbitrary thread context (that of whatever thread happens to be current), a device extension is each driver's primary place to maintain device state and all other device-specific data the driver needs. For example, any driver that implements a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine usually provides storage for the required kernel-defined timer and/or DPC objects in a device extension. + +Every driver that has an ISR must provide storage for a pointer to a set of kernel-defined interrupt objects, and most device drivers store this pointer in a device extension. Each driver determines the size of the device extension when it creates a device object, and each driver defines the contents and structure of its own device extensions. + +The I/O manager's [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) and [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) routines allocate memory for the device object and extension from the nonpaged memory pool. + +Every standard driver routine that receives an IRP also receives a pointer to a device object representing the target device for the requested I/O operation. These driver routines can access the corresponding device extension through this pointer. Usually, a *DeviceObject* pointer is also an input parameter to a lowest-level driver's ISR. + +The following figure shows a representative set of driver-defined data for the device extension of a lowest-level driver's device object. A higher-level driver would not provide storage for an interrupt object pointer returned by [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371) and passed to [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) and [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089). However, a higher-level driver would provide storage for the timer and DPC objects shown in the following figure if the driver has a *CustomTimerDpc* routine. A higher-level driver also might provide storage for an executive spin lock and interlocked work queue. + +![diagram illustrating an example device extension for a lowest-level driver](images/3devext.png) + +In addition to providing storage for an interrupt object pointer, a lowest-level device driver must supply storage for an interrupt spin lock if its ISR handles interrupts for two or more devices on different vectors or if it has more than one ISR. For more information about registering an ISR, see [Registering an ISR](registering-an-isr.md). + +Typically, drivers store pointers to their device objects in their device extensions, as shown in the figure. A driver might also keep a copy of the resource list for the device in the extension. + +A higher-level driver typically stores a pointer to the next-lower driver's device object in its device extension. A higher-level driver must pass a pointer to the next-lower driver's device object to [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336), after it has set up the next-lower driver's I/O stack location in an IRP, as explained in [Handling IRPs](handling-irps.md). + +Note also that any higher-level driver that allocates IRPs for lower-level drivers must specify how many stack locations the new IRPs should have. In particular, if a higher-level driver calls [**IoMakeAssociatedIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549397), [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257), or [**IoInitializeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549315), it must access the target device object of the next-lower-level driver to read its **StackSize** value, in order to supply the correct *StackSize* as an argument to these support routines. + +While a higher-level driver can read data from the next-lower-level driver's device object through the pointer returned by [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300), such a driver must follow these implementation guidelines: + +- Never attempt to write data to the lower driver's device object. + + The only exceptions to this guideline are file systems, which set and clear DO\_VERIFY\_VOLUME in the **Flags** of lower-level removable-media drivers' device objects. + +- Never attempt to access the lower driver's device extension for the following reasons: + + - There is no safe way to synchronize access to a single device extension between two drivers. + - A pair of drivers that implement such a backdoor communication scheme cannot be upgraded individually, cannot have an intermediate driver inserted between them without changing existing driver source, and cannot be recompiled and moved readily from one Windows platform to the next. + +To preserve their interoperability with lower-level drivers from one Windows platform or version to the next, higher-level drivers either must reuse the IRPs given them or must create new IRPs, and they must use [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) to communicate requests to lower-level drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Extensions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-level-thermal-management.md b/windows-driver-docs-pr/kernel/device-level-thermal-management.md new file mode 100644 index 0000000000..d2d50f50c5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-level-thermal-management.md @@ -0,0 +1,36 @@ +--- +title: Device-Level Thermal Management +author: windows-driver-content +description: Starting with Windows 8, Windows supports device-level thermal management for kernel-mode device drivers. +ms.assetid: C66E0050-04E8-4DCD-B989-94A97558C4CE +--- + +# Device-Level Thermal Management + + +Starting with Windows 8, Windows supports device-level thermal management for kernel-mode device drivers. Windows thermal management has these goals: + +- Prevent devices in a hardware platform from overheating, which can cause them to operate incorrectly or unreliably. +- Avoid making user-accessible surfaces on a computer case too hot to comfortably touch or hold. + +Similar to power management, thermal management must be implemented on a platform-wide basis by coordinating device-local thermal constraints in the context of global thermal conditions. By providing global coordination, the operating system can distribute cooling requirements across multiple devices in a way that minimizes interference with tasks that the user is performing. Thermal requirements can be balanced intelligently with other system requirements, such as power management and responsiveness to user actions. + +In contrast, a device driver that tries to manage thermal levels for its device locally, in isolation from the other devices in the platform, is more likely to make poor decisions that result in inefficient power usage and an unresponsive user interface (UI). + +To participate in global thermal management, a device driver implements a [GUID\_THERMAL\_COOLING\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh698265) driver interface. During system startup, a system-supplied driver, Acpi.sys, queries the device drivers in the system to determine which of them support this interface. A driver can receive an [**IRP\_MN\_QUERY\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff551687) request for this interface any time after the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine for the driver's device is called. In response to this request, the driver for a device that has thermal management capabilities can supply a pointer to a [**THERMAL\_COOLING\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/hh698275) structure. This structure contains pointers to a set of callback routines that are implemented by the driver. To manage thermal levels in the device, the operating system calls these routines directly. + +The two principal routines in this interface are [*ActiveCooling*](https://msdn.microsoft.com/library/windows/hardware/hh698235) and [*PassiveCooling*](https://msdn.microsoft.com/library/windows/hardware/hh698270). The driver's *ActiveCooling* routine engages or disengages active cooling in the device. For example, this routine might turn a fan on and off. The driver's *PassiveCooling* routine controls the degree to which the performance of the device must be throttled to maintain acceptable thermal levels. For example, this routine might be called to run the device at half speed to prevent it from overheating. + +By default, before the first call to the *ActiveCooling* routine, active cooling is disengaged (for example, the fan is turned off). Before the first call to the *PassiveCooling* routine, the driver configures the device to run at full performance, with no cooling restrictions. + +A driver can implement one or both of these routines, depending on the capabilities of the device hardware. For more information, see [Passive and Active Cooling Modes](passive-and-active-cooling-modes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device-Level%20Thermal%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-objects-and-device-stacks.md b/windows-driver-docs-pr/kernel/device-objects-and-device-stacks.md new file mode 100644 index 0000000000..c40408a6b8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-objects-and-device-stacks.md @@ -0,0 +1,48 @@ +--- +title: Device Objects and Device Stacks +author: windows-driver-content +description: Device Objects and Device Stacks +ms.assetid: 6bd56072-d9a5-463b-8aad-be37c8d1a6b0 +keywords: ["kernel-mode drivers WDK , device objects", "kernel-mode drivers WDK , device stacks", "device objects WDK kernel", "device stacks WDK kernel", "DO WDK kernel", "objects WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Objects and Device Stacks + + +## + + +This section discusses device objects and their arrangement in device stacks. It contains the following sections: + +[Introduction to Device Objects](introduction-to-device-objects.md) + +[WDM Device Objects and Device Stacks](wdm-device-objects-and-device-stacks.md) + +[Creating a Device Object](creating-a-device-object.md) + +[Initializing a Device Object](initializing-a-device-object.md) + +[Named Device Objects](named-device-objects.md) + +[Device Extensions](device-extensions.md) + +[Properties of Device Objects](properties-of-device-objects.md) + +[Securing Device Objects](securing-device-objects.md) + +[Points to Consider About Device Objects](points-to-consider-about-device-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Objects%20and%20Device%20Stacks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-power-states.md b/windows-driver-docs-pr/kernel/device-power-states.md new file mode 100644 index 0000000000..f0eebb7700 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-power-states.md @@ -0,0 +1,69 @@ +--- +title: Device Power States +author: windows-driver-content +description: Device Power States +ms.assetid: 2229f34c-9b88-4e3e-802e-f7be2c7ef168 +keywords: ["device power states WDK kernel", "power states WDK kernel", "states WDK power management", "Dx names WDK power management", "low power modes WDK kernel", "power saving modes WDK kernel", "continuous power WDK kernel", "delays WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Power States + + +## + + +A device power state describes the power state of a device in a computer, independently of the other devices in the computer. Device power states are named D0, D1, D2, and D3. D0 is the fully on state, and D1, D2, and D3 are low-power states. The state number is inversely related to power consumption: higher numbered states use less power. Starting with Windows 8, the D3 state is divided into two substates, D3hot and D3cold. + +Device power states are characterized by the following attributes: + +- Power consumption: How much power does the device use? + +- Device context: How much of its operational context does the device retain in this state? + +- Device driver behavior: What must the drivers for the device do to restore the device to the fully operational state? + +- Restore time: How long does it take to restore the device to the fully operational state? Most types of devices have modest restore times that differ little from one device class to the next. Only a few types of devices, such as GPUs, have very large hardware contexts that take significantly longer to restore. + +- Wake-up capability: Can the device request wake-up from this state? In general, if a device can request wake-up from a given power state (for example, D2), it can also request wake-up from any higher-powered state (D1). + +The exact definitions of the power states are device-specific. Not all devices define all the states; many devices define only the D0 and D3 states. See the Device Class Power Management Reference Specification to find out which device power states are defined for a specific device and what the operational requirements are for each state. (The reference specifications are available at the [ACPI / Power Management](http://go.microsoft.com/fwlink/p/?linkid=57185) website.) + +The power state of a device need not match the [system power state](system-power-states.md). For example, some devices can be in the off (D3) state even though the system is in the [system working state (S0)](system-working-state-s0.md). + +The power state of a device might seem to be unrelated to the power state of the device's parent bus. For example, a USB device might be in the D2 (selective suspend) state when its parent host controller is in the D3 state. These two states appear to be inconsistent only because the definitions of the Dx states are different on USB and on the bus (typically PCI or PCI Express) that the USB host controller is connected to. + +Note that some devices are capable of several different low power modes within a single device power state. Such a device can use these modes if its driver can automatically switch the device from one mode to another without changing the device power state. As a general rule, however, if there is no user-perceptible difference between the modes, the device should use only the lowest power mode. If a low power mode, such as a low-speed mode, adversely affects performance or is not transparent to software other than the device driver, the hardware should not automatically use it. See the Device Class Power Management Reference Specification for details. + +A driver or the power manager can request a device power state transition, and all drivers must be prepared to handle IRPs that request such transitions. For more information, see the following topics: + +[Sending IRP\_MN\_QUERY\_POWER or IRP\_MN\_SET\_POWER for Device Power States](sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md) + +[Handling IRP\_MN\_QUERY\_POWER for Device Power States](handling-irp-mn-query-power-for-device-power-states.md) + +[Handling IRP\_MN\_SET\_POWER for Device Power States](handling-irp-mn-set-power-for-device-power-states.md) + +## + + +Like the system, a device can transition from the working state (D0) to any low-power state (D1, D2, or D3) and from any low-power state to the working state. The following diagram is a state graph that shows the valid device power state transitions. + +![diagram illustrating the valid device power state transitions](images/dxpostates.png) + +This graph shows the subdivision of D3 into D3hot and D3cold. D3hot and D3cold are defined starting with Windows 8. All devices are required to support the D0 state and D3hot substate. The other states shown in the diagram are optional. + +In the preceding graph, the transition from D3hot to D3cold is the only direct transition between device low-power states. All other transitions between low-power states require an intermediate transition to D0, which allows the device driver to configure the device hardware, as required, either to enter the next low-power state or to stay in D0. However, a device exits D3hot and enters D3cold when power to the device is shut off, which requires no intervention from the device driver. This driver does any necessary configuration of the device hardware before the device enters D3hot; no additional configuration is required to prepare the device for the transition from D3hot to D3cold. For more information, see [Supporting D3cold in a Driver](supporting-d3cold-in-a-driver.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-sleeping-states.md b/windows-driver-docs-pr/kernel/device-sleeping-states.md new file mode 100644 index 0000000000..662841792f --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-sleeping-states.md @@ -0,0 +1,168 @@ +--- +title: Device Low-Power States +author: windows-driver-content +description: Device Low-Power States +ms.assetid: f594a63f-10ce-439d-abe3-d342555d98f0 +keywords: ["device power states WDK kernel", "device low-power states WDK power management", "sleep power management WDK kernel", "Dx names WDK power management", "asleep devices WDK power management", "lowest-powered device state WDK kernel", "highest-powered device low-power state WDK kernel", "intermediate sleeping state WDK kernel", "low power modes WDK kernel", "power saving modes WDK kernel", "continuous power WDK kernel", "delays WDK power management", "state transition delays WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Low-Power States + + +## + + +Device power states D1, D2, and D3 are the device low-power states. Starting with Windows 8, D3 is divided into two substates, [D3hot](#d3hot) and [D3cold](#d3cold). + +D1 and D2 are intermediate low-power states. Many classes of devices do not define these states. All devices must define D3hot. + +The following sections describe D1, D2, and D3: + +- [Device Power State D1](#d1) +- [Device Power State D2](#d2) +- [Device Power State D3](#d3) + +### Device Power State D1 + +Device power state D1 is the highest-powered device low-power state. It has the following characteristics: + +*Power consumption* +Consumption is less than in the D0 state but greater than or equal to that in the D2 state. Frequently, D1 is a clock-gated state in which the device receives just enough power to preserve the device's hardware context. Typically, the specification for a bus or device class that supports D1 describes this state in more detail. + +*Device context* +In general, device context is preserved by the hardware and need not be restored by the driver. The specification for a bus or device class that supports D1 typically provides detailed requirements for preserving this context. + +*Device driver behavior* +Drivers must save and restore or reinitialize any context lost by the hardware. Typically, however, devices lose little context upon entering this state. + +*Restore time* +In general, the time required to restore the device to D0 from D1 should be less than restoration from D2 to D0. + +*Wake-up capability* +A device in D1 might be able to request wake-up. To supply information about whether this state can support a wake signal, a bus driver uses the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure or, starting with Windows 8, the [GUID\_D3COLD\_SUPPORT\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) driver interface. + +Typically, devices that use D1 do so because resuming from this state does not require the driver to restore the device's full hardware context. To minimize the user's perception of delay, restoring a device to D0 from D1 should incur the least possible delay. Minimizing delay in the state transition is more important than reducing power consumption. + +### Device Power State D2 + +D2 is an intermediate device low-power state with the following characteristics: + +*Power consumption* +Consumption is less than or equal to that in the D1 state. + +*Device context* +In general, most device context is lost by the hardware. Frequently, this state preserves the part of the context that is used to signal wake events. The specification for a bus or device class that supports D2 typically provides detailed requirements for preserving this context. + +*Device driver behavior* +Device drivers must save and restore or reinitialize any context lost by the hardware. A typical device loses most context when it enters D2. + +*Restore time* +Restoring the device from D2 to D0 takes at least as long as restoring the device from D1 to D0. A graphics adapter that has a large frame buffer is an example of a device that has a large amount of hardware context to restore after a transition from D2 to D0. For such a device, the restore time from D2 might be much greater than the restore time from D1. + +*Wake-up capability* +A device in D2 might be able to request wake-up. To supply information about whether this state can support a wake signal, a bus driver uses the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure or, starting with Windows 8, the [GUID\_D3COLD\_SUPPORT\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) driver interface. + +Typically, drivers that support D2 do so because their devices cannot support wake from D3. For these devices, power consumption in the D2 state drops to the lowest level from which the device can recover in response to a wake signal. In contrast to the D1 state, which is implemented to reduce the delay perceived by the user, the goal in implementing the D2 state is to conserve power. As a result, the restore time from D2 to D0 typically exceeds that from D1 to D0. In the D2 state, for example, reduced power on the bus might cause a device to turn off some of its functionality, thus requiring additional time to restart and restore the device. + +Many classes of device do not define this state. + +### Device Power State D3 + +D3 is the lowest-powered device low-power state. All devices must support this state. + +Starting with Windows 8, the operating system subdivides D3 into two separate and distinct substates, D3hot and D3cold. Earlier versions of Windows define the D3 state, but not the D3hot and D3cold substates. However, all versions of the [PCI Bus Power Management Interface Specification](http://www.pcisig.com/specifications/conventional/) define separate D3hot and D3cold substates, and versions 4 and later of the [Advanced Configuration and Power Interface Specification](http://go.microsoft.com/fwlink/p/?linkid=57185) define D3hot and D3cold substates. + +Although versions of Windows before Windows 8 do not explicitly define the D3hot and D3cold substates of D3, these substates exist implicitly in these earlier versions of Windows. A device is implicitly in the D3hot substate if the device is explicitly in the D3 state, and the computer is in the S0 system power state. In D3hot, a device is connected to a power source (although the device might be configured to draw low current), and the presence of the device on the bus can be detected. A device is implicitly in the D3cold substate if it is explicitly in the D3 state, and the computer is in a low-power Sx state (a state other than S0). In this implicit D3cold substate, the device might receive a trickle current, but the device and the computer are effectively turned off until a wake event occurs. + +Starting with Windows 8, a device can enter and leave the D3cold substate while the computer remains in the S0 state. To support this new behavior, D3hot and D3cold must be explicitly defined as distinct substates of D3. + +D3hot is the only substate of D3 that the device can enter directly from D0. A device makes a transition from D0 to D3hot under software control by the device driver. In D3hot, the device can be detected on the bus that it connects to. The bus must remain in the D0 state while the device is in the D3hot substate. From D3hot, the device can either return to D0 or enter D3cold. D3cold can be entered only from D3hot. + +D3cold is a substate of D3 in which the device is physically connected to the bus but the presence of the device on the bus cannot be detected (that is, until the device is turned on again). In D3cold, one or both of the following is true: + +- The bus that the device connects to is in a low-power state. +- The device is in a low-power state in which the device does not respond when the bus driver tries to detect its presence on the bus. + +The transition from D3hot to D3cold occurs with no device driver interaction. Instead, the device driver indicates whether it is prepared for a D3cold transition before it initiates the transition from D0 to D3hot. Subsequently, a transition from D3hot to D3cold may or may not occur, depending on whether all of the conditions are right to enable this transition. + +Two such conditions are that all of the devices that use the same power source are in D3hot and are prepared for a D3cold transition. When the last of these devices enters D3hot, the parent bus driver or ACPI filter driver turns off the power source to these devices, which is to say that the devices enter D3cold. + +A device that is in D3cold can leave this substate only by entering D0. There is no direct transition from D3cold to D3hot. + +When the computer is in the S0 state and a device enters the D3hot substate, the device driver is typically unable to determine in advance whether the device's next transition will be to D3cold or D0. The one exception is when the computer is preparing to leave the S0 state. In this case, the next transition is to D3cold. + +The following sections describe D3hot and D3cold: + +- [D3hot substate](#d3hot) +- [D3cold substate](#d3cold) + +For more information, see [Supporting D3cold in a Driver](supporting-d3cold-in-a-driver.md). + +### D3hot substate + +D3hot has the following characteristics: + +*Power consumption* +Power is mostly removed from the device, but not from the computer as a whole. The computer, which is in the S0 state, might continue running in this state, or it might be preparing to move from S0 to a low-power Sx state. + +*Device context* +The device driver is solely responsible for restoring device context. The driver must preserve and then restore all device context or must reinitialize the device upon transition to the D0 state. + +*Device driver behavior* +The device driver is solely responsible for restoring device context, typically from the most recent working configuration. + +*Restore time* +Total restore time is the highest of any of the device power states, except for D3cold, but is typically not much greater than the restore time from D2. + +*Wake-up capability* +A device in the D3hot substate may or may not be able to request wake-up. To supply information about whether this substate can support a wake signal, a bus driver uses the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure or, starting with Windows 8, the [GUID\_D3COLD\_SUPPORT\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) driver interface. + +In D3hot, only minimal trickle current is available. Drivers and hardware must be prepared for the absence of power. The specification for a bus that supports D3hot typically provides detailed requirements for power sources that can be used in this state. To return the device to the working state, the device's drivers must be able to restore and reinitialize the device without depending on the BIOS to run any code in the option ROM that might be available for the device. + +The parent bus driver will not remove system power from the parent bus of any device that enters D3hot unless the computer as a whole transitions to the S0 state. + +All classes of device define the D3hot substate. + +### D3cold substate + +D3cold has the following characteristics: + +*Power consumption* +Power has been fully removed from the device and possibly from the entire system. The device may be able to draw current from side-band sources, depending on its construction. + +*Device context* +The device driver is solely responsible for restoring device context. The driver must preserve and then restore device context or must reinitialize the device upon transition to the D0 state. + +*Device driver behavior* +The device driver is solely responsible for restoring device context, typically from the most recent working configuration. + +*Restore time* +Total restore time is the highest of any of the device power states. + +*Wake-up capability* +In the D3cold substate, a device might be able to trigger a wake signal to wake a sleeping computer. This capability is reported in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure and, starting with Windows 8, by the [*GetIdleWakeInfo*](https://msdn.microsoft.com/library/windows/hardware/hh967712) routine in the [GUID\_D3COLD\_SUPPORT\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) driver interface. After the signal wakes the computer, the device driver initiates the device's transition from D3cold to D0. For more information, see the following remarks. + +Starting with Windows 8, a device in the D3cold substate might be able to trigger a wake signal to a computer that is in the S0 system power state. This capability is reported by the *GetIdleWakeInfo* routine. The **DEVICE\_CAPABILITIES** structure does not contain information about this capability. After the wake signal arrives, the device driver initiates the device's transition from D3cold to D0. In this case, the computer is awake when the signal arrives, and only the device needs to wake. + +In many existing hardware platforms, a device that is in a low-power Dx state can trigger a wake signal to wake a sleeping computer. However, the same device might not be able to trigger a wake signal if the computer is running in the S0 state. Thus, the driver for this device must not initiate the device's transition from D0 to a low-power Dx state when the computer is in the S0 state. Otherwise, after the device leaves D0, it will be unavailable until the computer leaves the S0 state. This device should leave the D0 state only when the computer is preparing to leave the S0 state. + +If a device that is in a low-power Dx state can trigger a wake signal to a computer that is running in the S0 state, the device is not required to remain in D0 when the computer is in S0. If the computer is in S0, and the device is in D0 but is idle, the driver can arm the device to trigger a wake signal, and then initiate the device's transition from D0 to this low-power Dx state. + +Some classes of device define the D3cold substate. + +For more information, see [Supporting D3cold in a Driver](supporting-d3cold-in-a-driver.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Low-Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-tree.md b/windows-driver-docs-pr/kernel/device-tree.md new file mode 100644 index 0000000000..15b966ad56 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-tree.md @@ -0,0 +1,48 @@ +--- +title: Device Tree +author: windows-driver-content +description: Device Tree +ms.assetid: 3220389a-06cc-4a43-8164-b785d1a16365 +keywords: ["devnodes WDK PnP", "nonpresent devices WDK", "PnP WDK kernel , device trees", "Plug and Play WDK kernel , device trees", "removal relations WDK PnP", "ejection relations WDK PnP", "device trees WDK PnP", "trees WDK PnP", "device nodes WDK PnP", "child devices WDK PnP", "hierarchy WDK PnP", "relationships WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Tree + + +## + + +The PnP manager maintains a device tree that keeps track of the devices in the system. The following figure shows the device tree for a sample system configuration. + +![sample pnp device tree](images/devtree.png) + +The device tree contains information about the devices present on the system. The PnP manager builds this tree when the machine boots, using information from drivers and other components, and updates the tree as devices are added or removed. + +Each node of the device tree is called a device node, or [*devnode*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-devnode). A devnode consists of the [*device objects*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-object) for the device's drivers, plus internal information maintained by the system. Therefore, there is a devnode for each [*device stack*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-stack). + +The PnP manager asks a bus driver for a list of its child devices using an [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) request. The bus driver determines its list of children according to its bus protocol. For example, the [Windows ACPI driver](acpi-driver.md), Acpi.sys, looks in the ACPI namespace, the PCI driver queries PCI configuration space, and a USB hub driver follows the USB bus protocol. + +The device tree is hierarchical, with devices on a bus represented as "children" of the bus adapter, controller or other *bus device*. (A bus device is any device to which other physical, logical, or virtual devices can be attached.) You can see the hierarchy of devices in the device tree using Device Manager and choosing the view option that allows you to view devices by connection. + +The hierarchy of the device tree reflects the structure in which the devices are attached in the machine. The PnP manager uses this hierarchy as it manages the devices. For example, if a user requests to unplug the USB controller from the machine represented by the previous figure, the PnP manager determines from the device tree that this action would result in three other devices also being unplugged (the USB hub, the joystick, and the camera). When the PnP manager queries the drivers for the USB controller to determine if it is safe to remove the controller, it also queries the drivers of the controller's descendants (the hub, joystick, and camera). + +The device tree is dynamic. As devices are added to, and removed from the machine, the PnP manager (together with drivers) maintains a current picture of the devices on the system. + +There are other relationships between devices on the machine besides the hierarchical relationships represented in the device tree. These include *removal relations* and *ejection relations*. See the reference page for [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) for more information. + +You cannot make any assumptions about the order in which the device tree is built, except that a bus device is configured before any of its child devices. For example, you should not assume that one device on a bus is configured before another device on the bus. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Tree%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-type-specific-i-o-requests.md b/windows-driver-docs-pr/kernel/device-type-specific-i-o-requests.md new file mode 100644 index 0000000000..483b7fc490 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-type-specific-i-o-requests.md @@ -0,0 +1,60 @@ +--- +title: Device Type-Specific I/O Requests +author: windows-driver-content +description: Device Type-Specific I/O Requests +ms.assetid: 33ea0b0a-db58-40b7-b6d3-e981acf44dfe +keywords: ["IRPs WDK kernel , device type-specific I/O requests", "device type-specific I/O requests WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Type-Specific I/O Requests + + +## + + +Device-specific sections of the Windows Driver Kit (WDK) provide information about device type-specific I/O requests handled by the system-supplied drivers for the most common kinds of devices. + +A new kernel-mode driver must handle the same set of I/O requests as a system-supplied driver if the new driver meets any of the following conditions: + +- The new driver replaces a system driver for the same type of device. + +- The new driver supports another device of a type already in the system. + +- The new driver is an intermediate (filter) driver, layered between two system-supplied drivers. + +Such a new driver must handle every **IRP\_MJ\_*XXX*** request that the system-supplied drivers handle. In most cases, a new device driver should also handle the same set of **IOCTL\_*XXX*** codes for [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests, even if the new driver must emulate the behavior of the corresponding system-supplied driver. Otherwise, the new driver might break user-mode applications that expect these kinds of requests to be honored. + +For information about the NTSTATUS values that drivers can set in the I/O status block of IRPs, as the return value for specific requests, see [Using NTSTATUS Values](using-ntstatus-values.md). For information about NTSTATUS values that can be specified in an error log packet, see [Logging Errors](logging-errors.md). Use this information to decide on the appropriate status values to be returned by new drivers for similar types of devices, or as an aid in determining the appropriate status values to be returned by the driver for a new type of device. + +For more information about various kinds of drivers and the requests that each is required to support, see the following: + +[Serial Devices and Drivers](https://msdn.microsoft.com/library/windows/hardware/ff547451) + +[System-Supplied Parallel Drivers](https://msdn.microsoft.com/library/windows/hardware/ff544814) + +[Storage Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566976) + +[HID Architecture](https://msdn.microsoft.com/library/windows/hardware/jj126193) + +[I/O Requests for USB Client Drivers](https://msdn.microsoft.com/library/windows/hardware/ff540134#km-ioctl) + +[The IEEE 1394 Driver Stack](https://msdn.microsoft.com/library/windows/hardware/ff538867) + +[Access Attribute Memory of a PCMCIA Device](https://msdn.microsoft.com/library/windows/hardware/ff536892) + +For all other types of drivers, consult the documentation for the appropriate driver type. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Type-Specific%20I/O%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/device-working-state-d0.md b/windows-driver-docs-pr/kernel/device-working-state-d0.md new file mode 100644 index 0000000000..3f35898fa4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/device-working-state-d0.md @@ -0,0 +1,55 @@ +--- +title: Device Working State D0 +author: windows-driver-content +description: Device Working State D0 +ms.assetid: 6b0ec03a-eaf1-4c96-aaae-dfe821583787 +keywords: ["device power states WDK kernel", "Dx names WDK power management", "device working state WDK power management", "continuous power WDK kernel", "delays WDK power management", "working states WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Device Working State D0 + + +## + + +In the D0 device power state, the device is fully on and operational. In this state, a device driver can interact with the device to perform I/O operations, and the device can generate interrupts. If the device has hardware registers that are mapped into memory or I/O address space, the driver can access these registers. + +Starting with Windows 8, a device driver can connect a [passive-level interrupt service routine](using-passive-level-interrupt-handling-routines.md) (ISR) to the interrupt from a device. The device can generate interrupts regardless of whether it is in D0. When in a low-power Dx state, the device can generate an interrupt that acts as a trigger to bring the device back to D0. The ISR is scheduled to run at IRQL = PASSIVE\_LEVEL after the device enters D0. In earlier versions of Windows, including Windows 7, a device must not generate interrupts when it is in a device power state other than D0. + +A transition from D0 to a low-power Dx state can occur only when the device driver, while acting as the power policy owner for the device, initiates the transition by calling the [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) routine. When the power manager responds to this call by sending a power IRP ([**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744)), the device driver, the bus driver, and the platform firmware (through the [Windows ACPI driver](acpi-driver.md), Acpi.sys) cooperatively handle this IRP to change the power state of the device. + +Device hardware typically monitors a set of internal events that can generate either run-time interrupts or wake signals, depending on how the device is configured. The driver implements one code path to respond to interrupts, and another to respond to wake events. The driver code can be simplified if the interrupt code path does not need to deal with wake events, and the wake code path does not need to deal with interrupts. As a best practice, the driver should configure the device to generate interrupts only when the device is in D0, and to generate wake signals only when the device is in a low-power Dx state. Typically, the driver configures the device to generate a wake signal just before the device exits D0, and configures the device to generate interrupts just after the device enters D0. + +Typically, a device enters the D0 state when its hardware reset signal is asserted. In fact, the specifications for buses such as PCI and PCI Express require this behavior. + +These are the characteristics of the D0 state: + +**Power consumption** +Highest level of continuous power consumption for the device. + +**Device context** +All context retained. + +**Device driver behavior** +Normal operation. + +**Restore time** +Not applicable. + +**Wake-up capability** +Not applicable. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Device%20Working%20State%20D0%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/deviced1-and-deviced2.md b/windows-driver-docs-pr/kernel/deviced1-and-deviced2.md new file mode 100644 index 0000000000..05d8ad9a4a --- /dev/null +++ b/windows-driver-docs-pr/kernel/deviced1-and-deviced2.md @@ -0,0 +1,30 @@ +--- +title: DeviceD1 and DeviceD2 +author: windows-driver-content +description: DeviceD1 and DeviceD2 +ms.assetid: 88e9e1bf-c797-4e00-b540-1b2f8d48300a +keywords: ["DeviceD1", "DeviceD2"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DeviceD1 and DeviceD2 + + +## + + +The **DeviceD1** and **DeviceD2** members of [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) indicate whether the device hardware supports these device power states. Each is a single bit, which is set if the device supports the state and is clear if the device does not support the state. The operating system assumes that all devices support the D0 and D3 [device power states](device-power-states.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DeviceD1%20and%20DeviceD2%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/devicestate.md b/windows-driver-docs-pr/kernel/devicestate.md new file mode 100644 index 0000000000..b164429899 --- /dev/null +++ b/windows-driver-docs-pr/kernel/devicestate.md @@ -0,0 +1,122 @@ +--- +title: DeviceState +author: windows-driver-content +description: DeviceState +ms.assetid: 4cf650ea-cccf-411c-809f-0a01e2ceb067 +keywords: ["DeviceState"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DeviceState + + +## + + +The **DeviceState** member of [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) is an array of [**DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff543160) values that are indexed by [**SYSTEM\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff564565) values ranging from **PowerSystemWorking** to **PowerSystemShutdown**. Each element of the array contains the maximum (highest-powered) device power state that the device can support for the system power state denoted by the index, or **PowerDeviceUnspecified** if the system power state is not supported. + +For example, on a system that supports only S0, S4, and S5 [system power states](system-power-states.md), the **DeviceState** array for a device that supports only the D0 and D3 states contains the values shown in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DeviceState elementValue

DeviceState[PowerSystemWorking]

PowerDeviceD0

DeviceState[PowerSystemSleeping1]

PowerDeviceUnspecified

DeviceState[PowerSystemSleeping2]

PowerDeviceUnspecified

DeviceState[PowerSystemSleeping3]

PowerDeviceUnspecified

DeviceState[PowerSystemHibernate]

PowerDeviceD3

DeviceState[PowerSystemShutdown]

PowerDeviceD3

+ +  + +On a system that supports all of the system power states, the following table lists the values that the array would contain for a device that must be in the D2 state or lower whenever the system goes to any intermediate sleep state and in the D3 state when the system hibernates. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DeviceState elementValue

DeviceState[PowerSystemWorking]

PowerDeviceD0

DeviceState[PowerSystemSleeping1]

PowerDeviceD2

DeviceState[PowerSystemSleeping2]

PowerDeviceD2

DeviceState[PowerSystemSleeping3]

PowerDeviceD2

DeviceState[PowerSystemHibernate]

PowerDeviceD3

DeviceState[PowerSystemShutdown]

PowerDeviceD3

+ +  + +Note that the entries in the **DeviceState** array signify the highest device power state that the device can support for the corresponding system power state. In the preceding example, the device could be in state D3 for any system power state, state D2 for system power states **PowerSystemWorking** through **PowerSystemSleeping3**, and state D1 for system state **PowerSystemWorking**. + +The bus driver or ACPI filter sets these values based on the capabilities of the parent device node. + +As a general rule, higher-level drivers should not change these values. However, in the rare circumstances in which such a change is necessary, a driver can specify a lower (less-powered) state than the bus driver or ACPI filter originally returned. For example, assume that **DeviceState**\[**PowerSystemSleeping1**\] maps to **PowerDeviceD2**, as in the table above. A driver can change this value to **PowerDeviceD3**, but not to **PowerDeviceD1** or **PowerDeviceD0**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DeviceState%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/devicewake.md b/windows-driver-docs-pr/kernel/devicewake.md new file mode 100644 index 0000000000..399cfa72d1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/devicewake.md @@ -0,0 +1,48 @@ +--- +title: DeviceWake +author: windows-driver-content +description: DeviceWake +ms.assetid: 3b82c095-1ee7-41e9-991e-ac0bcf959024 +keywords: ["DeviceWake"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DeviceWake + + +## + + +The **DeviceWake** member of [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) contains the lowest (least-powered) device power state from which the device can signal a wake event, or **PowerDeviceUnspecified** if the device cannot wake in response to an external signal. + +The bus driver sets this value. A higher-level driver can change the value to a higher-powered state. For example, if the bus driver sets **DeviceWake** to D3 but a driver further up the device stack supports wake-up only from D2, the higher-level driver can change the value to D2. + +Note that if a driver changes **DeviceWake**, it might also have to change [**SystemWake**](systemwake.md) to avoid conflicts with the system-to-device mappings in the **DeviceState** array. For example, assume that the bus driver sets the following: + +- **DeviceState**\[**PowerSystemSleeping1**\] = **PowerDeviceD1** + +- **DeviceState**\[**PowerSystemSleeping2**\] = **PowerDeviceD3** + +- **DeviceWake** = **PowerDeviceD3** + +- **SystemWake** = **PowerSystemSleeping2** + +If a higher-level driver determines that its device cannot wake the system from D3, but only from D2 or higher, it can change **DeviceWake** to D2. However, this change causes the mapping from S2 to D3 to be impossible. Remember that the **DeviceState** array lists the highest device power state a device can support for a given system power state. If the system power state in the example is **PowerSystemSleeping2**, the device power state cannot be **PowerDeviceD2**. To eliminate this problem, the driver must also change **SystemWake** to **PowerSystemSleeping1**. The same is true for the **WakeFromD***x* and **DeviceD***x* settings. A driver must ensure that any changes it makes to **SystemWake** or **DeviceWake** do not conflict with the **WakeFromD***x* and **DeviceD***x* values. The values of *WakeFromDx* and **DeviceD***x* reflect hardware characteristics that a driver cannot change. + +If both the **SystemWake** and **DeviceWake** members are nonzero (that is, not **PowerSystemUnspecified**), then the device and its drivers support wake-up on this system. + +On non-ACPI hardware, the **DeviceWake** member contains zero (**PowerSystemUnspecified**). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DeviceWake%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/differences-in-wdm-versions.md b/windows-driver-docs-pr/kernel/differences-in-wdm-versions.md new file mode 100644 index 0000000000..94272e7ab8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/differences-in-wdm-versions.md @@ -0,0 +1,70 @@ +--- +title: Differences in WDM Versions +author: windows-driver-content +description: Differences in WDM Versions +ms.assetid: 735b01c4-4eff-4c8e-ab60-3813d1830112 +keywords: ["WDM drivers WDK kernel , versions", "versions WDK WDM", "compatibility WDK WDM", "cross-system compatibility WDK WDM", "Plug and Play WDK WDM", "driver support routines WDK WDM", "power management WDK WDM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Differences in WDM Versions + + +## + + +The simplest way to ensure cross-system compatibility is to write a driver that uses only features that are supported by the lowest-numbered version of WDM. However, this is not always possible. Sometimes, drivers require additional code to take advantage of the features that are available in later versions of WDM, or to compensate for differences between Windows operating systems. + +### WDM Differences in Driver Support Routines + +The Windows Driver Kit (WDK) reference page for each [driver support routine](https://msdn.microsoft.com/library/windows/hardware/ff544200) indicates if the routine is restricted to specific versions of WDM, or if its behavior is different on different operating system versions. Before using any driver support routine in a cross-system driver, be sure to understand any version-specific restrictions or behaviors. + +### WDM Differences in Plug and Play + +The following Plug and Play I/O request packet (IRP) is supported only in Windows 2000 and later versions of the NT-based operating system (WDM version 1.10 and later): + +[**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) + +In addition, the following IRPs work differently on Windows 98/Me from how they work on the NT-based operating system: + +[**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) and [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) + +[**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) + +### WDM Differences in Power Management + +The following power management functions and I/O requests differ in operation between the Windows 98/Me operating system and the NT-based operating system: + +[**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) + +[**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) + +[**PoRegisterDeviceForIdleDetection**](https://msdn.microsoft.com/library/windows/hardware/ff559721) + +[**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) + +[**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) + +When completing power IRPs, drivers on Windows 98/Me must complete power IRPs at IRQL = PASSIVE\_LEVEL, while drivers on the NT-based operating system can complete such IRPs at IRQL = PASSIVE\_LEVEL or IRQL = DISPATCH\_LEVEL. + +The DO\_POWER\_PAGABLE flag in the [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure is used differently on the Windows 98/Me operating system than on the NT-based operating system. + +### WDM Differences in Kernel-Mode Driver Operation + +Kernel-mode WDM drivers for Windows 98/Me must follow certain guidelines for using floating-point operations, MMX, 3DNOW!, or Intel's SSE extensions. For more information, see [Using Floating Point or MMX in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md). + +Windows 98/Me provides a fixed number of worker threads that might not be adequate for some drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Differences%20in%20WDM%20Versions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/disabling-apcs.md b/windows-driver-docs-pr/kernel/disabling-apcs.md new file mode 100644 index 0000000000..c76e14afe0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/disabling-apcs.md @@ -0,0 +1,49 @@ +--- +title: Disabling APCs +author: windows-driver-content +description: Disabling APCs +ms.assetid: 0578df31-1467-4bad-ba62-081d61278deb +keywords: ["asynchronous procedure calls WDK kernel", "APCs WDK kernel", "disabling APCs", "critical regions WDK kernel", "guarded regions WDK kernel", "raising current IRQLs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Disabling APCs + + +The system provides three mechanisms to disable APCs for the current thread: + +- **Critical regions.** When a thread is inside a critical region, its user APCs and normal kernel APCs are not executed. Special kernel APCs are still executed. For more information about these APC types, see [Types of APCs](types-of-apcs.md). + +- **Guarded regions.** When a thread is inside a guarded region, none of its APCs are executed. + +- **Raising the current IRQL to APC\_LEVEL or higher.** A thread that is executing at IRQL >= APC\_LEVEL executes with all APCs disabled. + +Note that these settings apply to the current thread and do not affect the behavior of any other thread. + +Some driver support routines must be called with particular kinds of APCs disabled. For example, routines that acquire an executive resource (such as [**ExAcquireResourceSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544363)) must be called with normal kernel APCs disabled. Other routines must be called with particular kinds of APCs enabled. For example, any routine that relies on an I/O completion routine (such as [**IoVolumeDeviceToDosName**](https://msdn.microsoft.com/library/windows/hardware/ff550422)) must be called with special kernel APCs enabled. The documentation for each routine specifies if the routine has any particular restrictions on the state of APC execution. + +A driver can explicitly enter a critical or guarded region by calling the appropriate routine. For more information, see [Critical Regions and Guarded Regions](critical-regions-and-guarded-regions.md). A driver can also explicitly raise the current IRQL to APC\_LEVEL by calling [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079). The driver must subsequently lower the IRQL to its original value by calling [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968). Using a guarded region is faster than raising and lowering the current IRQL, but guarded regions are only available in Windows Server 2003 and later versions of Windows. + +The following mutex operations have the same effect as entering or leaving a critical or guarded region or raising or lowering the current IRQL: + +- Holding a mutex object implicitly places the holder within a critical region. + +- Holding a guarded mutex implicitly places the holder within a guarded region. + +- Holding a fast mutex implicitly raises the current IRQL to APC\_LEVEL. + +For more information about mutex objects, see [Mutex Objects](mutex-objects.md). For more information about fast and guarded mutexes, see [Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Disabling%20APCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatch-internal-devicecontrol-in-class-port-drivers.md b/windows-driver-docs-pr/kernel/dispatch-internal-devicecontrol-in-class-port-drivers.md new file mode 100644 index 0000000000..39c52ea382 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatch-internal-devicecontrol-in-class-port-drivers.md @@ -0,0 +1,46 @@ +--- +title: Dispatch(Internal)DeviceControl in Class/Port Drivers +author: windows-driver-content +description: Dispatch(Internal)DeviceControl in Class/Port Drivers +ms.assetid: 94f6050d-c47e-4fb2-8b7f-afadcf12e0b8 +keywords: ["dispatch routines WDK kernel , DispatchDeviceControl routine", "dispatch DispatchDeviceControl routine", "IRP_MJ_DEVICE_CONTROL I/O function code", "device control dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dispatch(Internal)DeviceControl in Class/Port Drivers + + +## + + +The higher-level driver of a class/port pair can sometimes complete IRPs in its [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine. For example a class driver could, during initialization, gather and store information about the features of the underlying device, which might be sought in a subsequent [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request, and thus save processing time by satisfying the request without passing it on to the underlying device driver. A class driver might also be designed to check the IRP's parameters and send only requests with valid parameters to the port driver. + +Closely coupled class/port drivers also can define a set of driver-specific or device-specific internal I/O control codes that the class driver can use for [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests to the port driver. + +For example, the *DispatchCreateClose* routines in the system keyboard and mouse class drivers send system-defined internal device control requests to enable or disable keyboard and mouse interrupts to the underlying port drivers. These system class drivers set up **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests for an underlying port driver. Any new keyboard or mouse port driver that interoperates with these system class drivers also must support these public internal device control requests. + +The system parallel class/port driver model has similar features. New parallel class drivers can get support from the system parallel port driver by setting up IRPs for **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests with public IOCTL\_PARALLEL\_PORT\_*XXX* control codes. You can replace the system parallel port driver, but any new driver also must support this set of public internal device control requests. + +For more information about these public internal device control requests, see device-specific documentation in the Windows Driver Kit (WDK). For information about how to define private I/O control codes, see [Using I/O Control Codes](using-i-o-control-codes.md). + +For a closely coupled pair of port/class drivers, the class driver might handle the processing of certain device control requests without passing them on to the port driver. In a new class/port driver pair, the class driver's *DispatchDeviceControl* routine can do either of the following: + +- Check the validity of the parameters in its own I/O stack location, set the I/O status block if it finds any parameter errors, and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with a *PriorityBoost* of IO\_NO\_INCREMENT; otherwise, call [**IoGetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549266) copy its own I/O stack location into the port driver's, and pass the IRP on with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +- Or, do nothing more than set up the port driver's I/O stack location in the IRP without checking parameters and pass it on to the port driver for processing. + +SCSI class drivers have special requirements for handling device control requests. For more information about these requirements, see [Storage Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566976). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dispatch%28Internal%29DeviceControl%20in%20Class/Port%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatch-routine-functionality.md b/windows-driver-docs-pr/kernel/dispatch-routine-functionality.md new file mode 100644 index 0000000000..c82a67dd70 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatch-routine-functionality.md @@ -0,0 +1,36 @@ +--- +title: Dispatch Routine Functionality +author: windows-driver-content +description: Dispatch Routine Functionality +ms.assetid: cfc191af-2b65-465b-972e-9617a8f7d8b7 +--- + +# Dispatch Routine Functionality + + +## + + +The required functionality of a particular dispatch routine varies, depending on the I/O function code it handles, on the individual driver's position in a chain of drivers, and on the type of underlying physical device. + +Most dispatch routines process incoming I/O request packets (IRPs) as follows: + +1. Check the driver's I/O stack location in the IRP to determine what to do and check the parameters, if any, for validity. + + Whether a driver must check its I/O stack location to determine what to do and to check parameters depends on the given **IRP\_MJ\_***XXX*, as well as on whether that driver set up a separate Dispatch routine for each **IRP\_MJ\_***XXX* that the driver handles. + +2. Satisfy the request and complete the IRP if possible; otherwise, pass it on for further processing by lower-level drivers or by other device driver routines. + + Whether a driver must pass on an IRP for further processing depends on the validity of the parameters, if any, as well as on the **IRP\_MJ\_***XXX* and on the driver's level, if any, in a chain of layered drivers. + +For more information about IRPs, see [Handling IRPs](handling-irps.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dispatch%20Routine%20Functionality%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatch-routines-and-irqls.md b/windows-driver-docs-pr/kernel/dispatch-routines-and-irqls.md new file mode 100644 index 0000000000..2d498b73cb --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatch-routines-and-irqls.md @@ -0,0 +1,44 @@ +--- +title: Dispatch Routines and IRQLs +author: windows-driver-content +description: Dispatch Routines and IRQLs +ms.assetid: fe64e0f7-3906-470a-86c5-03460e652eed +keywords: ["dispatch routines WDK kernel , IRQLs", "IRQLs WDK dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dispatch Routines and IRQLs + + +## + + +Most drivers' dispatch routines are called in an arbitrary thread context at IRQL = PASSIVE\_LEVEL, with the following exceptions: + +- Any highest-level driver's dispatch routines are called in the context of the thread that originated the I/O request, which is commonly a user-mode application thread. + + In other words, the dispatch routines of file system drivers and other highest-level drivers are called in a nonarbitrary thread context at IRQL = PASSIVE\_LEVEL. + +- The [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034), and [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routines of lowest-level device drivers, and of intermediate drivers layered above them in the system paging path, can be called at IRQL = APC\_LEVEL and in an arbitrary thread context. + + The *DispatchRead* and/or *DispatchWrite* routines, and any other routine that also processes read and/or write requests in such a lowest-level device or intermediate driver, must be resident at all times. These driver routines can neither be pageable nor be part of a driver's pageable-image section; they must not access any pageable memory. Furthermore, they should not be dependent on any blocking calls (such as [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with a nonzero time-out). + +- The [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine of drivers in the hibernation and/or paging paths can be called at IRQL = DISPATCH\_LEVEL. The [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routines of such drivers must be prepared to handle PnP [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841) requests. + +- The *DispatchPower* routine of drivers that require inrush power at start-up can be called at IRQL = DISPATCH\_LEVEL. + +For additional information, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dispatch%20Routines%20and%20IRQLs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchcleanup-routines.md b/windows-driver-docs-pr/kernel/dispatchcleanup-routines.md new file mode 100644 index 0000000000..c358b46293 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchcleanup-routines.md @@ -0,0 +1,42 @@ +--- +title: DispatchCleanup Routines +author: windows-driver-content +description: DispatchCleanup Routines +ms.assetid: 1ba001b8-92e0-453f-b9f6-6099cedf6439 +keywords: ["dispatch routines WDK kernel , DispatchCleanup routine", "DispatchCleanup routine", "IRP_MJ_CLEANUP I/O function code", "deallocating resources WDK kernel", "unmapping hardware memory", "unmapping user-mode memory", "unlocking user-mode memory", "cleaning up resources WDK kernel", "spin locks WDK kernel", "cleanup dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchCleanup Routines + + +## + + +A driver's [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) routine handles IRPs for the [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718) I/O function code. + +Drivers can use a *DispatchCleanup* routine to perform any cleanup operations that are needed after all of the handles to a file object have been closed. Note that *DispatchCleanup* is called in the process context of the process that closed the final handle; this process might be different from the process that initially opened the handle. (Typically this difference happens because another process uses the **DuplicateHandle** user-mode routine to duplicate the processes handles.) Drivers that must perform cleanup in the original process context can use the [**PsSetCreateProcessNotifyRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff559951) routine to register a callback routine for that purpose, but keep in mind that such callbacks are a limited system resource. + +In general, a *DispatchCleanup* routine must process an **IRP\_MJ\_CLEANUP** request by doing the following for every IRP that is currently in the device queue (or in the driver's internal queue of IRPs), for the target device object, and is associated with the file object: + +- Call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to set the [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine pointer to **NULL**. + +- Cancel every IRP that is currently in the queue for the target device object, if the file object that is specified in the driver's I/O stack location of the queued IRP matches the file object that was received in the I/O stack location of the **IRP\_MJ\_CLEANUP** request. + +- Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP, and return STATUS\_SUCCESS. + +While processing an **IRP\_MJ\_CLEANUP** request, a driver can receive additional requests, such as [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819). Therefore, a driver that must deallocate resources must also synchronize execution of its *DispatchCleanup* routine with other dispatch routines, such as [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) and [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchCleanup%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md b/windows-driver-docs-pr/kernel/dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md new file mode 100644 index 0000000000..55e037f038 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md @@ -0,0 +1,36 @@ +--- +title: DispatchCreate, DispatchClose, and DispatchCreateClose Routines +author: windows-driver-content +description: DispatchCreate, DispatchClose, and DispatchCreateClose Routines +ms.assetid: 5c1c0036-71b1-4410-b157-f9ebe3b6ecfc +keywords: ["dispatch routines WDK kernel , DispatchCreate routine", "dispatch routines WDK kernel , DispatchClose routine", "dispatch routines WDK kernel , DispatchCreateClose routine", "DispatchCreateClose routine", "DispatchClose routine", "DispatchCreate routine", "IRP_MJ_CREATE I/O function code", "IRP_MJ_CLOSE I/O function code", "create dispatch routines WDK kernel", "close dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchCreate, DispatchClose, and DispatchCreateClose Routines + + +## + + +A driver's [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) and [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routines handle IRPs with I/O function codes of [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) and [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720), respectively. Alternatively, a combined [*DispatchCreateClose*](https://msdn.microsoft.com/library/windows/hardware/ff543270) routine can handle IRPs for both of these I/O function codes. + +A create request can originate either from a user-mode subsystem's attempt to get a handle to a file object representing a device (possibly on behalf of an application or subsystem-level driver) or in a higher-level driver's call to [**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198) or [**IoAttachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548294). + +A reciprocal close request originates from a user-mode subsystem's close of the file object handle associated with the driver's device object. + +Each of these requests is inherently synchronous. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchCreate,%20DispatchClose,%20and%20DispatchCreateClose%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchdevicecontrol-and-dispatchinternaldevicecontrol-routines.md b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-and-dispatchinternaldevicecontrol-routines.md new file mode 100644 index 0000000000..5fa8dfd5d3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-and-dispatchinternaldevicecontrol-routines.md @@ -0,0 +1,44 @@ +--- +title: DispatchDeviceControl and DispatchInternalDeviceControl Routines +author: windows-driver-content +description: DispatchDeviceControl and DispatchInternalDeviceControl Routines +ms.assetid: 0bf8868e-bc5a-4fa7-9ff6-270f7a7bc850 +keywords: ["dispatch routines WDK kernel , DispatchDeviceControl routine", "dispatch routines WDK kernel , DispatchInternalDeviceControl routine", "DispatchDeviceControl routine", "DispatchInternalDeviceControl routine", "IRP_MJ_DEVICE_CONTROL I/O function code", "IRP_MJ_INTERNAL_DEVICE_CONTROL I/O function code", "internal device control dispatch routines WDK kernel", "device control dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchDeviceControl and DispatchInternalDeviceControl Routines + + +## + + +A driver's [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) and [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routines handle IRPs with I/O function codes of [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766), respectively. + +For every common type of peripheral device, the system defines a set of I/O control codes for **IRP\_MJ\_DEVICE\_CONTROL** requests. New drivers for each type of device must support these requests. In most cases, these public I/O control codes for each type of device are not exported to user-mode applications. + +Some of these system-defined I/O control codes are used by higher-level drivers that create IRPs for the underlying device driver by calling [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318). Others are used by Win32 components to communicate with an underlying device driver by calling the Win32 function [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) (described in Microsoft Windows SDK documentation) which, in turn, calls a system service. The I/O manager sets up an IRP, and stores the major function code **IRP\_MJ\_DEVICE\_CONTROL** and the given I/O control code in the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure at **Parameters.DeviceIoControl.IoControlCode**. Then, the I/O manager calls the *DispatchDeviceControl* routine of the highest-level driver in the chain. + +For certain system-supplied drivers designed to interoperate with and support new drivers, the operating system also defines a set of I/O control codes for **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests. In most cases, these public I/O control codes allow add-on higher-level drivers to interoperate with an underlying device driver. + +As an example, the system-supplied parallel drivers support a set of internal I/O control codes that vendor-supplied drivers send in **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests. For more information, see [Internal Device Control Requests for Parallel Ports](https://msdn.microsoft.com/library/windows/hardware/ff543963) and [Internal Device Control Requests for Parallel Devices](https://msdn.microsoft.com/library/windows/hardware/ff543959). + +Almost all operations requested through system-defined I/O control codes use buffered I/O, because this type of request seldom requires the transfer of large amounts of data. That is, even drivers that set up their device objects for direct I/O are sent IRPs for device control requests with data to be transferred into or out of the buffer at **Irp->AssociatedIrp.SystemBuffer** (except for certain types of highest-level device drivers with closely coupled Win32 multimedia drivers). + +In addition, a driver can define a set of private I/O control codes that other drivers can use to communicate with it. New public I/O control codes can be added to the system only with the cooperation of Microsoft Corporation, because public I/O control codes are built into the operating system itself. + +For specific information about the set of public I/O control codes that different kinds of drivers must support and about defining private I/O control codes, see the device-specific reference sections of the Windows Driver Kit (WDK). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchDeviceControl%20and%20DispatchInternalDeviceControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-higher-level-drivers.md b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-higher-level-drivers.md new file mode 100644 index 0000000000..435a559aa1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-higher-level-drivers.md @@ -0,0 +1,49 @@ +--- +title: DispatchDeviceControl in Higher-Level Drivers +author: windows-driver-content +description: DispatchDeviceControl in Higher-Level Drivers +ms.assetid: baff49c4-8764-4b65-84f4-ce5e10d51ed2 +keywords: ["dispatch routines WDK kernel , DispatchDeviceControl routine", "dispatch DispatchDeviceControl routine", "IRP_MJ_DEVICE_CONTROL I/O function code", "device control dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchDeviceControl in Higher-Level Drivers + + +## + + +Usually, the [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine of a higher-level driver simply sets up the I/O stack location for the next-lower-level driver and passes the IRP on with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). The *DispatchDeviceControl* routine seldom checks the validity of parameters in the input IRP because the underlying device driver is assumed to have better information about how to handle each device-type-specific I/O control request. + +A possible exception to this general rule is the *DispatchDeviceControl* routine in the class driver of a class/port driver pair. For more information about handling device control requests in paired class/port drivers, see [Dispatch(Internal)DeviceControl in Class/Port Drivers](dispatch-internal-devicecontrol-in-class-port-drivers.md). + +Any new higher-level driver that is not closely associated with a particular device driver should simply set up the [I/O stack location](i-o-stack-locations.md) for the next-lower-level driver and pass the [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request on for further processing. + +A device control request is usually handled synchronously. That is, a higher-level driver's *DispatchDeviceControl* routine can frequently return control to the system as follows: + +``` + : : + return IoCallDriver(DeviceObject->NextDeviceObject, Irp); +``` + +However, a higher-level driver cannot use the preceding technique if a lower driver might return STATUS\_PENDING for such a request. In that case, the higher-level driver should call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) to register an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. When the *IoCompletion* routine is called, it can check the I/O status block to determine whether the IRP is still pending. If it is, the *IoCompletion* routine might retry the request or, possibly, call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) before it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) and returns STATUS\_PENDING. A higher-level driver must not complete an IRP with STATUS\_PENDING unless it has called **IoMarkIrpPending** for that IRP first. + +If the underlying device driver must process much data transferred from the device before it completes the request, then a higher-level driver might handle such a device control request asynchronously. That is, the higher-level driver might call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) to register an *IoCompletion* routine, pass the IRP on to lower drivers, and return control from its own *DispatchDeviceControl* routine. + +Almost all system-defined I/O control codes require the underlying device driver to transfer only modest amounts of data, usually much less than a PAGE\_SIZE amount. As a general rule, higher-level drivers should handle these requests synchronously, as shown in the preceding code fragment, because the lower drivers return control so quickly. That is, the overhead of calling the higher-level driver's *IoCompletion* routine does not compensate for whatever additional IRP processing that driver can get done in such a short interval. + +A higher-level driver that allocates IRPs with [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) for an underlying device driver can handle these device control requests synchronously. The higher-level driver can wait for an optional event object to be passed to **IoBuildDeviceIoControlRequest** and associated with the driver-allocated IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchDeviceControl%20in%20Higher-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-lowest-level-drivers.md b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-lowest-level-drivers.md new file mode 100644 index 0000000000..d99c7a2182 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchdevicecontrol-in-lowest-level-drivers.md @@ -0,0 +1,64 @@ +--- +title: DispatchDeviceControl in Lowest-Level Drivers +author: windows-driver-content +description: DispatchDeviceControl in Lowest-Level Drivers +ms.assetid: 51caacd3-c9e0-450e-9060-f308ab46b5a0 +keywords: ["dispatch routines WDK kernel , DispatchDeviceControl routine", "dispatch DispatchDeviceControl routine", "IRP_MJ_DEVICE_CONTROL I/O function code", "device control dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchDeviceControl in Lowest-Level Drivers + + +## + + +An [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request for a lowest-level driver requires that the driver either change the state of its device or provide information about the state of its device. Because most kinds of drivers are required to handle a number of I/O control codes, their [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routines usually contain a **switch** statement somewhat like the following: + +``` + : : +switch (irpSp->Parameters.DeviceIoControl.IoControlCode) +{ + case IOCTL_DeviceType_XXX: + case IOCTL_DeviceType_YYY: + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < + (sizeof(IOCTL_XXXYYY_STRUCTURE))) + { + status = STATUS_BUFFER_TOO_SMALL; + break; + } else { + IoMarkIrpPending(Irp); + : : // pass IRP on for further processing + case ... + : : +``` + +As this code fragment shows, a *DispatchDeviceControl* routine also checks parameters, sometimes on each I/O control code that the driver must support, sometimes on groups of these I/O control codes. + +Consider the following implementation guidelines for device drivers' *DispatchDeviceControl* routines: + +- *DispatchDeviceControl* must check the parameters for validity, and immediately complete IRPs with parameter errors, as described in [Completing IRPs](completing-irps.md). + +- Grouping I/O control codes in a **case** statement (where practical) when testing for valid parameters is economical in terms of driver performance and size and in code maintenance. As the preceding code fragment suggests, I/O control codes that use a common structure are natural candidates for such a **case** group. + +- Switching first on any I/O control codes for which the *DispatchDeviceControl* routine can satisfy and complete the IRP improves performance because the driver can return control faster. + +- Switching later on I/O control codes that specify infrequently requested operations also can improve the driver's performance in processing **IRP\_MJ\_DEVICE\_CONTROL** requests. + +- For better performance, every lowest-level device driver's *DispatchDeviceControl* routine should satisfy any device control request that it can, without queuing the IRP to other driver routines. + +If the *DispatchDeviceControl* routine can complete the IRP, it should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with a *PriorityBoost* of IO\_NO\_INCREMENT. If the *DispatchDeviceControl* routine must queue the IRP for further processing, it must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) and return STATUS\_PENDING. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchDeviceControl%20in%20Lowest-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchflushbuffers-routines.md b/windows-driver-docs-pr/kernel/dispatchflushbuffers-routines.md new file mode 100644 index 0000000000..7206d7f24e --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchflushbuffers-routines.md @@ -0,0 +1,30 @@ +--- +title: DispatchFlushBuffers Routines +author: windows-driver-content +description: DispatchFlushBuffers Routines +ms.assetid: 091ce55c-e867-4ba4-aa25-5c20af45d9c2 +keywords: ["dispatch routines WDK kernel , DispatchFlushBuffers routine", "DispatchFlushBuffers routine", "IRP_MJ_FLUSH_BUFFERS I/O function code", "flush buffers dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchFlushBuffers Routines + + +## + + +A driver's [*DispatchFlushBuffers*](https://msdn.microsoft.com/library/windows/hardware/ff543314) routine handles IRPs for the [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760) I/O function code. Driver support for this I/O function code is optional, but all file system and filter drivers that maintain internal data buffers must handle it to preserve changes to file data or metadata across system shutdowns. This request is sent by the I/O manager and other operating system components, as well as other kernel-mode drivers, when buffered data needs to be flushed to disk. For example, it is sent when a user-mode application calls [**FlushFileBuffers**](https://msdn.microsoft.com/library/windows/desktop/aa364439). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchFlushBuffers%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchpnp-routines.md b/windows-driver-docs-pr/kernel/dispatchpnp-routines.md new file mode 100644 index 0000000000..1a811ab625 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchpnp-routines.md @@ -0,0 +1,72 @@ +--- +title: DispatchPnP Routines +author: windows-driver-content +description: DispatchPnP Routines +ms.assetid: 909d99ac-5bd3-4b12-bfb4-79713cf2a156 +keywords: ["dispatch routines WDK kernel , DispatchPnP routine", "DispatchPnP routine", "PnP dispatch routines WDK kernel", "IRPs WDK kernel , Plug and Play dispatch routines", "Plug and Play dispatch routines WDK kernel", "IRP_MJ_PNP I/O function code"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchPnP Routines + + +## + + +A driver's [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine supports [Plug and Play](implementing-plug-and-play.md) by handling IRPs for the [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) I/O function code. Associated with the **IRP\_MJ\_PNP** function code are several minor I/O function codes (see [Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807)), some of which all drivers must handle and some of which can be optionally handled. The PnP manager uses these minor function codes to direct drivers to start, stop, and remove devices and to query drivers about their devices. + +All drivers for a device must have the opportunity to handle PnP IRPs for the device, except in a few cases where a function or filter driver is allowed to fail the IRP. + +Each driver's *DispatchPnP* routine must follow these rules: + +- A function or filter driver must pass PnP IRPs down to the next driver in the device stack, unless the function or filter driver handles the IRP and encounters a failure (due to insufficient resources, for example). + + All drivers for a device must have the opportunity to handle PnP IRPs for the device unless one of the drivers encounters an error. The PnP manager sends IRPs to the top driver in a device stack. Function and filter drivers pass the IRP down to the next driver, and the parent bus driver completes the IRP. See [Passing PnP IRPs Down the Device Stack](passing-pnp-irps-down-the-device-stack.md) for more information. + + A driver can fail an IRP if it tries to handle the IRP and encounters an error (such as insufficient resources). If a driver receives an IRP with a code it does not handle, the driver must not fail the IRP. It must pass such an IRP down to the next driver without modifying the IRP's status. + +- A driver must handle certain PnP IRPs and may optionally handle others. + + Each PnP driver is required to handle certain IRPs, such as [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738), and can optionally handle others. See [Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807) for information about which IRPs are required and optional for each kind of driver (function drivers, filter drivers, and bus drivers). + + A driver can fail a required PnP IRP with an appropriate error status, but a driver must not return STATUS\_NOT\_SUPPORTED for such an IRP. + +- If a driver handles a PnP IRP successfully, the driver sets the IRP status to success. It does not depend on another driver in the stack to set the status. + + A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS to inform the PnP manager that the driver handled the IRP successfully. For some IRPs, a non-bus driver might be able to rely on its parent bus driver to set the status to success. However, this is a risky practice. For consistency and robustness, a driver must set the IRP status to success for each PnP IRP it handles successfully. + +- If a driver fails an IRP, the driver completes the IRP with an error status and does not pass the IRP down to the next driver. + + To fail an IRP like [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725), a driver sets **Irp->IoStatus.Status** to STATUS\_UNSUCCESSFUL. Additional error status values for other IRPs include STATUS\_INSUFFICIENT\_RESOURCES and STATUS\_INVALID\_DEVICE\_STATE. + + Drivers do not set STATUS\_NOT\_SUPPORTED for IRPs that they handle. This is the initial status set by the PnP manager. If an IRP is completed with this status, it means that no drivers in the stack handled the IRP; all drivers just passed the IRP to the next driver. + +- A driver must handle a PnP IRP in its dispatch routine (on the IRP's way down the device stack), in an [**IoCompletion**](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine (on the IRP's way back up the device stack), or both, as specified in the reference page for the IRP. + + Some PnP IRPs, such as [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738), must be handled first by the driver at the top of the device stack and then by each next-lower driver. Others, such as [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749), must be handled first by the parent bus driver. Still others, such as [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664), can be handled both on the way down the device stack and the way back up. See [Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807) for the rules that apply to each PnP IRP. See [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md) For information about handling PnP IRPs that must be processed first by the parent bus driver. + +- A driver must add information to an IRP on the IRP's way down the device stack and modify or remove information on the IRP's way back up. + + When returning information in response to a PnP query IRP, a driver must follow this convention to enable orderly information passing by the layered drivers for a device. + +- Except where explicitly documented, a driver must not depend on PnP IRPs being sent in any particular order. + +- When a driver sends a PnP IRP, it must send the IRP to the top driver in the device stack. + + Most PnP IRPs are sent by the PnP manager, but some can be sent by drivers (for example, [**IRP\_MN\_QUERY\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff551687)). A driver must send a PnP IRP to the driver at the top of the device stack. Call [**IoGetAttachedDeviceReference**](https://msdn.microsoft.com/library/windows/hardware/ff549145) to get a pointer to the device object for the driver at the top of the device stack. + +You should test your drivers with a checked build of the operating system. The checked build of the system verifies whether a driver follows many of the PnP rules listed above. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchPnP%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchpower-routines.md b/windows-driver-docs-pr/kernel/dispatchpower-routines.md new file mode 100644 index 0000000000..d8d74b7378 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchpower-routines.md @@ -0,0 +1,56 @@ +--- +title: DispatchPower Routines +author: windows-driver-content +description: DispatchPower Routines +ms.assetid: e385064f-cbdb-432f-951a-743217891333 +keywords: ["dispatch routines WDK kernel , DispatchPower routine", "DispatchPower routine", "power management WDK kernel , dispatch routines", "IRP_MJ_POWER I/O function code", "removable device power dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchPower Routines + + +## + + +A driver's [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine supports [power management](implementing-power-management.md) by handling IRPs for the [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) I/O function code. Associated with the **IRP\_MJ\_POWER** function code are several minor I/O function codes for Power Management. The power manager uses these minor function codes to direct drivers to change power states, to wait for and respond to system wake-up events, and to query drivers about their devices. + +Each driver's *DispatchPower* routine performs the following tasks: + +- Handle the IRP if possible. + +- Pass the IRP to the next lower driver in the device stack, using [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654). + +- If a bus driver, perform the requested power operation on the device and complete the IRP. + +All drivers for a device must have the opportunity to handle power IRPs for the device, except in a few cases where a function or filter driver is allowed to fail the IRP. Most function and filter drivers either perform some processing or set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for each power IRP, then pass the IRP down to the next lower driver without completing it. Eventually the IRP reaches the bus driver, which physically changes the power state of the device if required and completes the IRP. + +When the IRP has been completed, the I/O manager calls any *IoCompletion* routines set by drivers as the IRP traveled down the device stack. Whether a driver needs to set a completion routine depends upon the type of IRP and the driver's individual requirements. + +Power IRPs that power up a device must be handled first by the lowest driver in the device stack (the underlying bus driver) and then by each successive driver up the stack. Power IRPs that power down a device must be handled first by the driver at the top of the device stack and then by each successive driver going down the stack. + +### Special Handling for Removable Devices + +In their *DispatchPower* routines, drivers of removable devices should check to see whether the device is still present. If the device has been removed, the driver should not pass the IRP down to the next lower driver. Instead, the driver should do the following: + +- Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to begin processing the next power IRP. + +- Set **Irp->IoStatus.Status** to STATUS\_DELETE\_PENDING. + +- Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), specifying IO\_NO\_INCREMENT, to complete the IRP. + +- Return STATUS\_DELETE\_PENDING. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchPower%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchqueryinformation-routines.md b/windows-driver-docs-pr/kernel/dispatchqueryinformation-routines.md new file mode 100644 index 0000000000..89fe084df8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchqueryinformation-routines.md @@ -0,0 +1,30 @@ +--- +title: DispatchQueryInformation Routines +author: windows-driver-content +description: DispatchQueryInformation Routines +ms.assetid: dfcb8ad0-ae95-4dd7-b4c8-a2f3ad4b12ef +keywords: ["dispatch routines WDK kernel , DispatchQueryInformation routine", "DispatchQueryInformation routine", "IRP_MJ_QUERY_INFORMATION I/O function code", "query information dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchQueryInformation Routines + + +## + + +A driver's [*DispatchQueryInformation*](https://msdn.microsoft.com/library/windows/hardware/ff543364) routine handles IRPs for the [**IRP\_MJ\_QUERY\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff550788) I/O function code. Driver support for this I/O function code is optional, and typically appears in higher-level or file system drivers. This request is sent by the I/O manager and other operating system components, as well as other kernel-mode drivers. For example, it is sent when a user-mode application calls [**GetFileInformationByHandle**](https://msdn.microsoft.com/library/windows/desktop/aa364952), and when a kernel-mode component calls [**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchQueryInformation%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchread--dispatchwrite--and-dispatchreadwrite-routines.md b/windows-driver-docs-pr/kernel/dispatchread--dispatchwrite--and-dispatchreadwrite-routines.md new file mode 100644 index 0000000000..5dd7a83193 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchread--dispatchwrite--and-dispatchreadwrite-routines.md @@ -0,0 +1,48 @@ +--- +title: DispatchRead, DispatchWrite, and DispatchReadWrite Routines +author: windows-driver-content +description: DispatchRead, DispatchWrite, and DispatchReadWrite Routines +ms.assetid: 2982939a-4afb-4b21-9a96-0ac758f0fb6c +keywords: ["DispatchRead routine", "DispatchWrite routine", "DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchWrite routine", "dispatch routines WDK kernel , DispatchRead routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchRead, DispatchWrite, and DispatchReadWrite Routines + + +## + + +A driver's [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) and [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) routines handle IRPs with I/O function codes of [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), respectively. Alternatively, a combined [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine can handle IRPs for both of these I/O function codes. + +Every driver of a device from which data can be transferred to the system must have a *DispatchRead* routine. Every driver of a device to which data can be transferred from the system must have a *DispatchWrite* routine. Any driver that transfers data in both directions can have a combined *DispatchReadWrite* routine. + +Lower-level drivers handle **IRP\_MJ\_READ** and **IRP\_MJ\_WRITE** requests asynchronously. Therefore, *DispatchRead* and/or *DispatchWrite* routines in highest-level drivers must pass these requests on for further processing, provided that the request has valid parameters in that driver's I/O stack location of the IRP. + +Whether a driver sets up its device objects for buffered or direct I/O affects how it handles transfer requests. In particular, a driver that uses direct I/O to do DMA operations might need to split up large transfer requests into a sequence of smaller transfer operations in order to satisfy an **IRP\_MJ\_READ** or **IRP\_MJ\_WRITE** request. For more information, see [Input/Output Techniques](i-o-programming-techniques.md). + +The following subsections discuss some of the design and implementation considerations for *DispatchReadWrite* routines in lowest-level device drivers that use buffered I/O and direct I/O, as well as in higher-level drivers layered above them: + +[Handling Transfers Asynchronously](handling-transfers-asynchronously.md) + +[DispatchReadWrite Using Buffered I/O](dispatchreadwrite-using-buffered-i-o.md) + +[DispatchReadWrite Using Direct I/O](dispatchreadwrite-using-direct-i-o.md) + +[DispatchReadWrite in Higher-Level Drivers](dispatchreadwrite-in-higher-level-drivers.md) + +[Summary of Read/Write Dispatch Routines](summary-of-read-write-dispatch-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchRead,%20DispatchWrite,%20and%20DispatchReadWrite%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchreadwrite-in-higher-level-drivers.md b/windows-driver-docs-pr/kernel/dispatchreadwrite-in-higher-level-drivers.md new file mode 100644 index 0000000000..6982c47c1d --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchreadwrite-in-higher-level-drivers.md @@ -0,0 +1,40 @@ +--- +title: DispatchReadWrite in Higher-Level Drivers +author: windows-driver-content +description: DispatchReadWrite in Higher-Level Drivers +ms.assetid: d8406115-c62e-4362-8d2c-77d0414c4104 +keywords: ["DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchReadWrite in Higher-Level Drivers + + +## + + +Except for file system drivers, a higher-level driver usually does not have any internal driver queues for IRPs. Such a driver's [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine can pass IRPs with valid parameters on to lower drivers, possibly after setting up its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, as described in [Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md). + +However, a SCSI class driver's *DispatchReadWrite* routine is responsible for splitting up large transfer requests, if necessary, before it sends an IRP with the major function code [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) to the SCSI port/miniport driver pair. For more information, see [Storage Class Driver's SplitTransferRequest Routine](https://msdn.microsoft.com/library/windows/hardware/ff566965). + +If a higher-level driver allocates one or more IRPs, which it sets up for the next-lower driver in its *DispatchReadWrite* routine, to request some number of partial transfers, the *DispatchReadWrite* routine must call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) with each driver-allocated IRP. The driver must register its *IoCompletion* routine to track how much data is transferred in each partial-transfer operation so that the *IoCompletion* routine can release all driver-allocated IRPs and, eventually, complete the original request. + +If the underlying driver controls a removable-media device, any IRPs allocated by the higher-level driver must have a thread context. To set up a thread context, the allocating driver must set the **Irp->Tail.Overlay**.Thread in each newly allocated IRP from the same value in the incoming transfer IRP. For more information, see [Supporting Removable Media](supporting-removable-media.md). + +If the underlying device driver returns an IRP for a partial transfer with an error, the *IoCompletion* routine can either retry the partial-transfer request or complete the original IRP with its I/O status block set with the returned error, after freeing any IRPs and memory the higher-level driver has allocated. + +If a higher-level driver's *DispatchReadWrite* routine allocates memory for partial-transfer operations and its allocation will be accessed by the driver's *IoCompletion* routine (or by the underlying device driver), the *DispatchReadWrite* routine must allocate that memory from nonpaged pool. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchReadWrite%20in%20Higher-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchreadwrite-using-buffered-i-o.md b/windows-driver-docs-pr/kernel/dispatchreadwrite-using-buffered-i-o.md new file mode 100644 index 0000000000..5323ac25e3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchreadwrite-using-buffered-i-o.md @@ -0,0 +1,50 @@ +--- +title: DispatchReadWrite Using Buffered I/O +author: windows-driver-content +description: DispatchReadWrite Using Buffered I/O +ms.assetid: bb8ce47d-5722-4050-9492-bec154744597 +keywords: ["DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines", "buffered I/O WDK kernel", "I/O WDK kernel , buffered"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchReadWrite Using Buffered I/O + + +## + + +Any lowest-level device driver that sets up its device objects for buffered I/O satisfies a read request by returning data transferred from its device into a locked down system-space buffer at **Irp->AssociatedIrp.SystemBuffer**. It satisfies a write request by transferring data from the same buffer out to its device. + +Consequently, the *DispatchReadWrite* routine of such a device driver usually does the following on receipt of a transfer request: + +1. Calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) and determines the direction of the transfer request. + +2. Checks the validity of the parameters for the request. + + - For a read request, the routine usually checks the driver's *IoStackLocation*->**Parameters.Read.Length** value to determine whether the buffer is large enough to receive data transferred from the device. + + For example, the system keyboard class driver processes read requests that come only from the Win32 user input thread. This driver defines a structure, KEYBOARD\_INPUT\_DATA, in which to store keystrokes from the device and, at any given moment, holds some number of these structures in an internal ring buffer in order to satisfy read requests as they come in. + + - For a write request, the routine usually checks the value at **Parameters.Write.Length**, and checks the data at **Irp->AssociatedIrp.SystemBuffer** for validity if necessary: that is, if its device accepts only structured data packets containing members with defined value ranges. + +3. If any parameters are invalid, the *DispatchReadWrite* routine completes the IRP immediately, as already described in [Completing IRPs](completing-irps.md). Otherwise, the routine passes the IRP on for further processing by other driver routines, as described in [Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md). + +Lowest-level device drivers that use buffered I/O usually must satisfy a transfer request by reading or writing data of a size specified by that the originator of the request. Such a driver is likely to define a structure for data coming in from or being sent to its device and is likely to buffer structured data internally, as the system keyboard class driver does. + +Drivers that buffer data internally should support [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760) requests, and can also support [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807) requests. + +The highest-level driver in a chain is usually responsible for checking the input IRP's parameters before passing a read/write request on to lower drivers. Consequently, many lower-level drivers can assume that their I/O stack locations in a read/write IRP have valid parameters. If a lowest-level driver in a chain is aware of device-specific constraints on data transfers, that driver is required to check the validity of the parameters in its I/O stack location. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchReadWrite%20Using%20Buffered%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchreadwrite-using-direct-i-o.md b/windows-driver-docs-pr/kernel/dispatchreadwrite-using-direct-i-o.md new file mode 100644 index 0000000000..ab2d54a240 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchreadwrite-using-direct-i-o.md @@ -0,0 +1,42 @@ +--- +title: DispatchReadWrite Using Direct I/O +author: windows-driver-content +description: DispatchReadWrite Using Direct I/O +ms.assetid: 5174fe1f-aee5-4c8a-87a1-7f185ed4e242 +keywords: ["DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines", "direct I/O WDK kernel", "I/O WDK kernel , direct I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchReadWrite Using Direct I/O + + +## + + +Any lower-level device driver that sets up its device objects for direct I/O satisfies a read request by returning data transferred from its device to system physical memory, which is described by the MDL at **Irp->MdlAddress**. It satisfies a write request by transferring data from system physical memory out to its device. + +Lower-level drivers must handle read/write requests asynchronously. Therefore, every lower-level driver's [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine must pass [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) IRPs with valid parameters on to other driver routines, as described in [Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md). + +For read/write IRPs sent to lower-level drivers, the paged physical memory described by the MDL at **Irp->MdlAddress** has already been probed for the correct access rights to carry out the requested transfer and has already been locked down by the highest-level driver in the chain or by the I/O manager. Any intermediate or lowest-level driver that sets up its device objects for direct I/O should not call [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) because this has already been done. A lowest-level driver calls [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559). (Drivers for Windows 98 call [**MmGetSystemAddressForMdl**](https://msdn.microsoft.com/library/windows/hardware/ff554556) instead. Drivers for Windows Me, Windows 2000 and later versions of Windows should use **MmGetSystemAddressForMdlSafe**.) + +Any intermediate or lowest-level device driver's *DispatchReadWrite* routine should validate the parameters in its I/O stack location of read/write IRPs if it cannot trust a higher-level driver to pass down only IRPs with valid parameters. If the *DispatchReadWrite* routine finds a parameter error, it should complete the IRP with an appropriate error STATUS\_*XXX* value as already described in [Completing IRPs](completing-irps.md). If parameters are valid, an intermediate driver's *DispatchReadWrite* routine must pass the request on for further processing, according to the guidelines in [DispatchReadWrite in Higher-Level Drivers](dispatchreadwrite-in-higher-level-drivers.md). + +A lowest-level device driver's *DispatchReadWrite* routine must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) with the transfer request, pass the IRP on for further processing by other driver routines, and return STATUS\_PENDING, as described in [Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md). + +Note that a device driver's *DispatchReadWrite* routine can control the order in which IRPs are queued to its device for faster I/O throughput by calling [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) with a driver-determined *Key* value. Another routine in the driver dequeues the IRP later, determines whether the requested length must be split into partial-transfer operations, and programs the device to transfer data. + +In general, a device driver that must split up large transfer requests to suit the limitations of its device should postpone these operations until just before setting up the device for a given transfer request. Such a device driver's *DispatchReadWrite* routine should not check the I/O stack location of incoming IRPs for any device-specific transfer constraints, nor attempt to calculate partial-transfer ranges, when the driver can postpone these checks until just before its [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) (or other driver routine) programs the device for a transfer operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchReadWrite%20Using%20Direct%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchsetinformation-routines.md b/windows-driver-docs-pr/kernel/dispatchsetinformation-routines.md new file mode 100644 index 0000000000..3ff7fd3dba --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchsetinformation-routines.md @@ -0,0 +1,30 @@ +--- +title: DispatchSetInformation Routines +author: windows-driver-content +description: DispatchSetInformation Routines +ms.assetid: 9fb56504-32a7-47b0-b731-df1dc74ce861 +keywords: ["dispatch routines WDK kernel , DispatchSetInformation routine", "DispatchSetInformation routine", "set information dispatch routines WDK kernel", "IRP_MJ_SET_INFORMATION I/O function code"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchSetInformation Routines + + +## + + +A driver's [*DispatchSetInformation*](https://msdn.microsoft.com/library/windows/hardware/ff543399) routine handles IRPs for the [**IRP\_MJ\_SET\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff550799) I/O function code. Driver support for this I/O function code is optional, and typically appears in higher-level or file system drivers. This request is sent by the I/O manager and other operating system components, as well as other kernel-mode drivers. For example, it is sent when a user-mode application calls [**SetEndOfFile**](https://msdn.microsoft.com/library/windows/desktop/aa365531), and when a kernel-mode component calls [**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchSetInformation%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchshutdown-routines.md b/windows-driver-docs-pr/kernel/dispatchshutdown-routines.md new file mode 100644 index 0000000000..aa96dcbde8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchshutdown-routines.md @@ -0,0 +1,30 @@ +--- +title: DispatchShutdown Routines +author: windows-driver-content +description: DispatchShutdown Routines +ms.assetid: e0d4ed56-a614-4dc8-9bb2-abfe38f05946 +keywords: ["IRP_MJ_SHUTDOWN I/O function code", "dispatch routines WDK kernel , DispatchShutdown routine", "DispatchShutdown routine", "shutdown dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchShutdown Routines + + +## + + +A driver's [*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) routine handles IRPs for the [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807) I/O function code. Drivers of mass-storage devices that have internal caches for data must handle this request. Drivers of mass-storage devices and intermediate drivers layered over them also must handle this request if an underlying driver maintains internal buffers for data. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchShutdown%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dispatchsystemcontrol-routines.md b/windows-driver-docs-pr/kernel/dispatchsystemcontrol-routines.md new file mode 100644 index 0000000000..37618da34a --- /dev/null +++ b/windows-driver-docs-pr/kernel/dispatchsystemcontrol-routines.md @@ -0,0 +1,34 @@ +--- +title: DispatchSystemControl Routines +author: windows-driver-content +description: DispatchSystemControl Routines +ms.assetid: b885a4a3-a9b6-423c-83bb-ee502724b0d0 +keywords: ["dispatch routines WDK kernel , DispatchSystemControl routine", "system control dispatch routines WDK kernel", "IRP_MJ_SYSTEM_CONTROL I/O function code", "DispatchSystemControl routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DispatchSystemControl Routines + + +## + + +A driver's [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine handles IRPs for the [**IRP\_MJ\_SYSTEM\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550813) I/O function code. + +All drivers must provide a *DispatchSystemControl* routine. The purpose of this routine is to provide support for Windows Management Instrumentation (WMI). Regardless of whether a driver supports WMI, this routine must pass the IRP to the next-lower driver. + +To learn how to implement a *DispatchSystemControl* routine, and how to support WMI in general, see [Windows Management Instrumentation](implementing-wmi.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DispatchSystemControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/distinguishing-fast-startup-from-wake-from-hibernation.md b/windows-driver-docs-pr/kernel/distinguishing-fast-startup-from-wake-from-hibernation.md new file mode 100644 index 0000000000..84299306f3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/distinguishing-fast-startup-from-wake-from-hibernation.md @@ -0,0 +1,41 @@ +--- +title: Distinguishing Fast Startup from Wake-from-Hibernation +author: windows-driver-content +description: Starting with Windows 8, a fast startup mode is available to start a computer in less time than is typically required for a traditional, cold startup. +ms.assetid: 1768F739-619A-441F-B270-029DD1F72953 +--- + +# Distinguishing Fast Startup from Wake-from-Hibernation + + +Starting with Windows 8, a fast startup mode is available to start a computer in less time than is typically required for a traditional, cold startup. A fast startup is a hybrid combination of a cold startup and a wake-from-hibernation startup. Frequently, kernel-mode device drivers need to distinguish fast startups from wake-from-hibernation so that that their devices behave as users expect. To make this distinction, drivers can use information that is available in [system power IRPs](power-irps-for-the-system.md). + +During a cold startup, the boot loader constructs a kernel memory image by loading the sections of the Windows kernel file into memory and linking them. Next, the kernel configures core system functions, enumerates the devices attached to the computer, and loads drivers for them. + +In contrast, a fast startup simply loads the hibernation file (Hiberfil.sys) into memory to restore the previously saved image of the Windows kernel and loaded drivers. A fast startup tends to take significantly less time than a cold startup. + +To prepare for a fast startup, Windows performs a hybrid shutdown sequence that combines elements of a full shutdown sequence and a prepare-for-hibernation sequence. First, as in a full shutdown, Windows closes all applications and logs off all user sessions. At this stage, the system state is similar to that of a computer that has just started up—no applications are running, but the Windows kernel is loaded and the system session is running. Next, the power manager sends system power IRPs to device drivers to tell them to prepare their devices to enter hibernation. Finally, Windows saves the kernel memory image (including the loaded kernel-mode drivers) in Hiberfil.sys and shuts down the computer. + +By default, Windows 8 uses a fast startup in place of a cold startup. Users can typically ignore the differences between fast and cold startups, but, to meet users' expectations, fast startups should behave the same as cold startups. In particular, the devices attached to the computer should be configured the same for a fast startup as they would be for a cold startup. + +If the driver for a device configures the device differently depending on whether a cold startup or a wake-from-hibernation occurred, this driver should, after a fast startup, configure the device as though a cold startup (instead of a wake-from-hibernation) occurred. For example, the system-supplied NDIS driver disables miniport wake capabilities on a fast startup but not on a wake-from-hibernation. + +To distinguish a fast startup from a wake-from-hibernation, a driver can inspect the information in the system set-power ([**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744)) IRP that informs the driver that the computer has entered the S0 (working) state. The driver's [I/O stack location](https://msdn.microsoft.com/library/windows/hardware/ff550659) in this IRP contains a **Power** member, which is a structure that contains power-related information. Starting with Windows Vista, the **Power** member structure contains a **SystemPowerStateContext** member, which is a [**SYSTEM\_POWER\_STATE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/jj835780) structure that contains information about the previous system power states. This information is encoded in bit fields in the **SYSTEM\_POWER\_STATE\_CONTEXT** structure. + +Most of the bit fields in the **SYSTEM\_POWER\_STATE\_CONTEXT** structure are reserved for system use and are opaque to drivers. However, this structure contains two bit fields, **TargetSystemState** and **EffectiveSystemState**, that can be read by drivers to determine whether a fast startup or a wake-from-hibernation occurred. + +The **TargetSystemState** and **EffectiveSystemState** bit fields are set to [**SYSTEM\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff564565) enumeration values. If **TargetSystemState** = **PowerSystemHibernate** and **EffectiveSystemState** = **PowerSystemHibernate**, a wake-from-hibernation occurred. However, if **TargetSystemState** = **PowerSystemHibernate** and **EffectiveSystemState** = **PowerSystemShutdown**, a fast startup occurred. + +The **TargetSystemState** bit field specifies the last system power state transition for which the driver received a system power IRP before the computer shut down or entered hibernation. The **EffectiveSystemState** bit field indicates the effective previous system power state of the device, as perceived by the user. The **TargetSystemState** and **EffectiveSystemState** values might not match if, for example, the driver received notification of a pending system transition to the hibernation state, but a hybrid shutdown subsequently occurred. + +For more information, see [**SYSTEM\_POWER\_STATE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/jj835780). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Distinguishing%20Fast%20Startup%20from%20Wake-from-Hibernation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dma-programming-techniques.md b/windows-driver-docs-pr/kernel/dma-programming-techniques.md new file mode 100644 index 0000000000..88159daa0e --- /dev/null +++ b/windows-driver-docs-pr/kernel/dma-programming-techniques.md @@ -0,0 +1,31 @@ +--- +title: DMA Programming Techniques +author: windows-driver-content +description: DMA Programming Techniques +ms.assetid: bdd8ffa4-8f09-41ed-b0f8-8edabbe65393 +--- + +# DMA Programming Techniques + + +Direct Memory Access (DMA) is one of the most basic hardware techniques for transferring memory-based data between the central processor (CPU) and a particular device. Computer systems use a DMA controller which is an intermediate device that handles the memory transfer, allowing the CPU to do other things. + +Drivers can use the DMA controller to transfer memory-based data directly. The following topics discuss DMA issues related to I/O programming. + +Drivers can use adapter objects to control DMA. For more information about adapter objects, see [Adapter Objects and DMA](adapter-objects-and-dma.md). + +When a driver is transferring data between system memory and its device, data can be cached in one or more processor caches and/or in the system DMA controller's cache. For more information about DMA and caches, see [Flushing Cached Data during DMA Operations](flushing-cached-data-during-dma-operations.md). + +If you need to split up your DMA operations into smaller chunks, see [Splitting DMA Transfer Requests](splitting-dma-transfer-requests.md). + +Version 3 of the DMA operations interface is available starting with Windows 8. For more information about this interface, see [Version 3 of the DMA Operations Interface](version-3-of-the-dma-operations-interface.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DMA%20Programming%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dpc-objects-and-dpcs.md b/windows-driver-docs-pr/kernel/dpc-objects-and-dpcs.md new file mode 100644 index 0000000000..c78eecea4c --- /dev/null +++ b/windows-driver-docs-pr/kernel/dpc-objects-and-dpcs.md @@ -0,0 +1,50 @@ +--- +title: DPC Objects and DPCs +author: windows-driver-content +description: DPC Objects and DPCs +ms.assetid: 962e6b38-afed-4711-a556-ed9cbc139a1a +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel", "interrupt service routines WDK kernel , DPCs", "ISRs WDK kernel , DPCs", "DPC objects WDK kernel", "objects WDK DPC"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DPC Objects and DPCs + + +## + + +This section contains the following topics: + +[Introduction to DPC Objects](introduction-to-dpc-objects.md) + +[Introduction to DPCs](introduction-to-dpcs.md) + +[Which Type of DPC Should You Use?](which-type-of-dpc-should-you-use-.md) + +[Registering and Queuing a DpcForIsr Routine](registering-and-queuing-a-dpcforisr-routine.md) + +[Registering and Queuing a CustomDpc Routine](registering-and-queuing-a-customdpc-routine.md) + +[Handling Overlapped I/O Operations](handling-overlapped-i-o-operations.md) + +[Threaded DPCs](threaded-dpcs.md) + +[Writing DPC Routines](writing-dpc-routines.md) + +[Guidelines for Writing DPC Routines](guidelines-for-writing-dpc-routines.md) + +[Organization of DPC Queues](organization-of-dpc-queues.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DPC%20Objects%20and%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-defined-wmi-data-items.md b/windows-driver-docs-pr/kernel/driver-defined-wmi-data-items.md new file mode 100644 index 0000000000..53721b425d --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-defined-wmi-data-items.md @@ -0,0 +1,128 @@ +--- +title: Driver-Defined WMI Data Items +author: windows-driver-content +description: Driver-Defined WMI Data Items +ms.assetid: 97b64571-95ff-4d61-9fa0-5690e9f29345 +keywords: ["data types WDK WMI", "embedded classes WDK WMI", "data items WDK WMI", "WMI WDK kernel , driver-defined data items", "driver-defined data items WDK WMI", "classes WDK WMI", "WMI WDK kernel , classes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver-Defined WMI Data Items + + +## + + +A data item in a class definition of WMI data or event block can be one of the following: + +- A basic data type such as a string or an unsigned integer. + +- An embedded class. An embedded class is used only as a data item in another class definition and is not exposed as a data block or event block. + +- A fixed-length or variable-length array of a basic data type or embedded class. + +When sending a data block to WMI, a driver must align the start of the block on an 8-byte boundary. All subsequent data items in the block must be aligned on the corresponding alignment for the data type. A **boolean** or **uint8** should be aligned on a 1-byte boundary. A **sint16**, **uint16**, or **string** item should be aligned on a 2-byte boundary, and so on. Arrays should be aligned based upon the base type of the array. An array of bytes should be aligned on a byte boundary, an array of uint64 should be aligned on an 8-byte boundary, and so on. An embedded class should be aligned based upon the natural alignment of the embedded class which is defined to be the largest element within the embedded class. For example, if an embedded class has a **uint64**, the class should be aligned on an 8-byte boundary. WMI data item alignment follows the same conventions as the **/Zp8** switch on the Microsoft C compiler. + +A driver writer does not necessarily have to define data items in a block other than the required items **InstanceName** and **Active**. For example, an empty event block can serve as notification that an event occurred, without additional data. Or a data block might simply enumerate instance names in response to an [**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) request. + +The following table lists the MOF data types that can be used to define items in a WMI data or event block. For more information about MOF data types, see the Microsoft Windows SDK. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data typeData formatAlignment (in bytes)

string

A USHORT specifying the string length in bytes, followed by the Unicode string data. The string data may optionally include a terminating 0 followed by padding. If so, the string length must include the terminating 0 and padding. Drivers can use the MaxLen qualifier to specify the maximum length in characters of the string. Drivers that specify a maximum string length can use a fixed size buffer to hold the string. If the string is strictly smaller than the size of the buffer, then the driver can pad the rest of the string with zeros.

2

boolean

A one-byte value where 0 is FALSE and any nonzero value is TRUE

1

sint8

Signed 8-bit integer

1

uint8

Unsigned 8-bit integer

1

sint16

Signed 16-bit integer

2

uint16

Unsigned 16-bit integer

2

sint32

Signed 32-bit integer

4

uint32

Unsigned 32-bit integer

4

sint64

Signed 64-bit integer

8

uint64

Unsigned 64-bit integer

8

datetime

A fixed-length 25-character Unicode string that specifies an absolute date or time interval. A datetime value has the following format:

+

yyyymmddhhmmss.mmmmmmsutc

+

where:

+

yyyy is the 4-digit year

+

mm is the 2-digit month

+

dd is the 2-digit day of the month

+

hh is the hour according to a 24-hour clock

+

mm is the minute

+

ss is the seconds

+

mmmmmm is the number of microseconds

+

s is a plus sign (+) or minus sign (-), indicating whether utc is a positive or negative offset from Universal Time Coordinates; or a colon (:), indicating that the datetime value is an interval.

+

utc is the offset in minutes from Universal Time Coordinates. If utc is zero (000), the datetime value is an interval.

+

Values must be zero-padded. Fields that are not significant can be filled with asterisks (*).

2

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver-Defined%20WMI%20Data%20Items%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-entry-points-in-driver-objects.md b/windows-driver-docs-pr/kernel/driver-entry-points-in-driver-objects.md new file mode 100644 index 0000000000..a48e247b45 --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-entry-points-in-driver-objects.md @@ -0,0 +1,64 @@ +--- +title: Driver Entry Points in Driver Objects +author: windows-driver-content +description: Driver Entry Points in Driver Objects +ms.assetid: f004c2b3-8435-4c25-82e9-aff3911dc316 +keywords: ["driver objects WDK kernel", "standard driver routines WDK kernel , driver objects", "driver routines WDK kernel , driver objects", "routines WDK kernel , driver objects", "objects WDK driver objects", "entry points WDK kernel", "driver entry points WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver Entry Points in Driver Objects + + +## + + +A kernel-mode driver must specify the following entry points in its driver object: + +- At least one dispatch routine's entry point, in order to get IRPs requesting PnP, power, and I/O operations. + +- The entry point of its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, at **DriverObject -> DriverExtension -> AddDevice**. + +- The entry point of its [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, if it manages its own queue of IRPs. + +- If the driver can be loaded and/or replaced dynamically, an [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) entry point in order to free any system resources, such as system objects or memory, that the driver has allocated. (Drivers that cannot be replaced while the system is running, such as a keyboard driver, need not supply an *Unload* routine.) + +These requirements do not apply to some miniport drivers, for which the corresponding class or port driver defines the entry points in the driver object. See the device-type-specific documentation for details. + +The I/O manager maintains information about driver-created device objects in the corresponding driver object. + +When a driver is loaded, its [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine is called with a pointer to the driver object. When a driver's **DriverEntry** routine is called, it sets *Dispatch*, *StartIo* (if any), and *Unload* (if any) entry points directly in the driver object as follows: + +``` +DriverObject->MajorFunction[IRP_MJ_xxx] = DDDispatchXxx; + : : +DriverObject->MajorFunction[IRP_MJ_yyy] = DDDispatchYyy; + : : +DriverObject->DriverStartIo = DDStartIo; +DriverObject->DriverUnload = DDUnload; + : : +``` + +The **DriverEntry** routine also sets the entry point of its *AddDevice* routine, in the **DriverExtension** of its driver object, as follows: + +``` +DriverObject->DriverExtension->AddDevice = DDAddDevice; +``` + +A **DriverEntry** or optional [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routine also can use a field in the driver object (not shown in the [driver object illustration](introduction-to-driver-objects.md#driver-object-illustration)) to get information from and/or set information in the configuration manager's registry database. For more information, see [Registry Keys for Drivers](https://msdn.microsoft.com/library/windows/hardware/ff549538). + +The I/O manager exports no support routines to manipulate driver objects, which are [**DRIVER\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff544174) structures. Driver objects are used by the I/O manager to keep track of currently loaded drivers. Some members of a driver object are used only by the I/O manager. Others members are also used by driver writers; for example, you must know certain member names to define *AddDevice*, *Dispatch*, *StartIo*, and *Unload* entry points. You should neither attempt to use undocumented members within a **DRIVER\_OBJECT** structure, nor make assumptions about the locations of any driver object members that are named in this documentation. Otherwise, you cannot maintain the portability of a driver from one Windows platform to another. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20Entry%20Points%20in%20Driver%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-managed-irp-queues.md b/windows-driver-docs-pr/kernel/driver-managed-irp-queues.md new file mode 100644 index 0000000000..ab1bb4a08b --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-managed-irp-queues.md @@ -0,0 +1,56 @@ +--- +title: Driver-Managed IRP Queues +author: windows-driver-content +description: Driver-Managed IRP Queues +ms.assetid: b701e4aa-96ba-44af-96a5-b6cecf075bac +keywords: ["device queues WDK IRPs , objects", "IRPs WDK kernel , queuing", "queuing IRPs", "dequeuing IRPs", "internal IRP queues WDK kernel", "cancel-safe IRP queues WDK kernel", "driver-managed IRP queues WDK kernel", "supplemental IRP queues WDK kernel", "interlocked IRP queues WDK kernel", "device queues WDK IRPs", "device queues WDK IRPs , about device queues"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver-Managed IRP Queues + + +## + + +Except for file system drivers, the I/O manager associates a device queue object (for queuing IRPs) with each device object that a driver creates. + +Most device drivers call the I/O manager's support routines to use the associated device queue, which holds IRPs whenever device I/O requests for a target device object come in faster than the driver can process them to completion. With this technique, IRPs are queued to a driver-supplied [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. + +For good performance, most intermediate drivers simply pass IRPs on to lower drivers as fast as they come in, so intermediate drivers almost never use the device queues associated with their respective device objects. + +However, you can design a driver to manage internal queues of IRPs by explicitly setting up one or more device queues, interlocked queues, or cancel-safe queues. This approach can be particularly useful if the driver controls a device that overlaps I/O operations. For such a device, it can be difficult to manage concurrent processing of two or more IRPs for the same target device object using only a single queue. + +The simplest way to build an internal queue is to use the cancel-safe IRP queue framework. You can implement the queuing mechanism of your choice in your driver. You can then use [**IoCsqInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff549054) to register a set of callback routines that handle IRP insertion and deletion, as well as locking and unlocking your queue. The cancel-safe IRP queue framework provides the [**IoCsqInsertIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549066), [**IoCsqRemoveIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549070), and [**IoCsqRemoveNextIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549072) routines that automatically use the callback routines to safely insert and remove IRPs from the driver's queue. The system also uses your callback routines to safely remove any IRPs that are canceled. + +You also might opt to set up supplemental queues for IRPs in the driver of a device controller for a set of heterogeneous physical devices. For example, the SCSI port driver uses device queue objects for internal queues. This driver both has a *StartIo* routine and sets up device queue objects as supplemental queues, in addition to the device queue associated with the device object it creates to represent an HBA. The SCSI port driver uses its supplemental device queues to hold IRPs bound for particular logical units on the HBA-controlled SCSI bus(es). + +The system floppy controller driver is an example of a driver that has no *StartIo* routine and uses an interlocked queue. This driver sets up a doubly linked interlocked queue into which and from which the driver and its device-dedicated thread insert and remove IRPs. + +The Kernel defines the device queue object type. The executive support component provides routines for inserting and removing IRPs in interlocked queues. Drivers for Windows XP and later versions of Windows can use [cancel-safe IRP queues](cancel-safe-irp-queues.md) to handle IRP queuing. + +The following sections explain how to use device queues, interlocked queues, and cancel-safe queues: + +[Setting up and Using Device Queues](setting-up-and-using-device-queues.md) + +[Managing Device Queues](managing-device-queues.md) + +[Setting Up and Using Interlocked Queues](setting-up-and-using-interlocked-queues.md) + +[Managing Interlocked Queues with a Driver-Created Thread](managing-interlocked-queues-with-a-driver-created-thread.md) + +[Cancel-Safe IRP Queues](cancel-safe-irp-queues.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver-Managed%20IRP%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-notification.md b/windows-driver-docs-pr/kernel/driver-notification.md new file mode 100644 index 0000000000..2a7a69ae09 --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-notification.md @@ -0,0 +1,35 @@ +--- +title: Driver Notification +author: windows-driver-content +description: Driver Notification +ms.assetid: 331ec25e-409a-4bfa-8da7-d8c26cd6910b +keywords: ["dynamic hardware partitioning WDK , driver notification", "hardware partitioning WDK dynamic , driver notification", "partitioning WDK dynamic hardware , driver notification", "driver notification WDK dynamic hardware partitioning", "notification WDK dynamic hardware partitioning , driver"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver Notification + + +This section discusses the ways that the operating system can notify a device driver when you dynamically add a processor or memory module to a hardware partition. + +This section includes the following topics: + +[Introduction to Driver Notification](introduction-to-driver-notification.md) + +[Synchronous Driver Notification](synchronous-driver-notification.md) + +[Asynchronous Driver Notification](asynchronous-driver-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-programming-techniques.md b/windows-driver-docs-pr/kernel/driver-programming-techniques.md new file mode 100644 index 0000000000..811abccaa2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-programming-techniques.md @@ -0,0 +1,35 @@ +--- +title: Driver Programming Techniques +author: windows-driver-content +description: Driver Programming Techniques +ms.assetid: ddad49ab-fe3c-4959-8a29-a850380b978f +--- + +# Driver Programming Techniques + + +Programming drivers in the kernel mode of Windows requires techniques that sometimes differ significantly from those of ordinary user-mode programming. While the fundamentals of programming may never change, the world of the kernel is very different. + +This section includes the following topics: + +[Using Nt and Zw Versions of the Native System Services Routines](using-nt-and-zw-versions-of-the-native-system-services-routines.md) + +[Synchronization Techniques](synchronization-techniques.md) + +[Using Common Log File System](using-common-log-file-system.md) + +[Using Kernel Transaction Manager](using-kernel-transaction-manager.md) + +[Dynamic Hardware Partitioning Techniques](dynamic-hardware-partitioning-techniques.md) + +[Miscellaneous Driver Programming Techniques](miscellaneous-driver-programming-techniques.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20Programming%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-role-in-power-management.md b/windows-driver-docs-pr/kernel/driver-role-in-power-management.md new file mode 100644 index 0000000000..47c85c167d --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-role-in-power-management.md @@ -0,0 +1,44 @@ +--- +title: Driver Role in Power Management +author: windows-driver-content +description: Driver Role in Power Management +ms.assetid: 24b55880-e767-4f18-977e-c4a93332b909 +keywords: ["power management WDK kernel , driver roles in", "system power states WDK kernel , driver roles", "device power states WDK kernel", "driver power support roles WDk kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver Role in Power Management + + +## + + +Drivers support power management in two ways: + +1. Drivers respond to system-wide power requests issued by the power manager. + +2. Drivers manage power and performance states for their individual devices. + +Every driver must have a [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine to handle [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) requests. The *DispatchPower* routine must inspect each power IRP and either handle it or pass it down to the next-lower driver. + +For a device to participate in power management, every driver in the device stack for the device must respond to or pass power IRPs appropriately. Failure of a single driver to act correctly can cause power management to be disabled across the entire system. + +One driver for each device [manages power policy](managing-device-power-policy.md) for its device. That driver can send power IRPs to its own device stack to perform power operations on its device. The power policy manager is responsible for issuing device power IRPs that correspond to system power IRPs. + +In addition, drivers might perform certain power tasks, such as powering on a device at start-up or powering off a device at removal, without receiving a power IRP. These are considered implicit power requests. + +For more information, see [Power Management Responsibilities for Drivers](power-management-responsibilities-for-drivers.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20Role%20in%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-thread-context.md b/windows-driver-docs-pr/kernel/driver-thread-context.md new file mode 100644 index 0000000000..9525e3764d --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-thread-context.md @@ -0,0 +1,44 @@ +--- +title: Driver Thread Context +author: windows-driver-content +description: Driver Thread Context +ms.assetid: 8795811d-a5f6-4f90-9fa0-edd4b37fd269 +keywords: ["driver thread context WDK kernel", "thread context WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Driver Thread Context + + +## + + +As shown in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure, a file system is a two-part driver: + +1. A file system driver (FSD), which executes in the context of a user-mode thread that calls an I/O system service + + The I/O manager sends the corresponding IRP to the FSD. If the FSD sets up a completion routine for an IRP, its completion routine is not necessarily called in the original user-mode thread's context. + +2. A set of file system threads, and possibly an *FSP (file system process)* + + An FSD can create a set of driver-dedicated system threads, but most FSDs use system worker threads in order to get work done without tying up user-mode threads that make I/O requests. Any FSD might set up its own process address space in which its driver-dedicated threads execute, but the system-supplied FSDs avoid this practice to conserve system memory. + +File systems generally use system worker threads to set up and manage internal work queues of IRPs that they send to one or more lower-level drivers, possibly for different devices. + +While the lowest-level driver shown in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure processes each IRP in stages through a set of discrete, driver-supplied routines, it does not use system threads as the file system does. A lowest-level driver does not need its own thread context unless setting up its device for I/O is such a protracted process that it has a noticeable effect on system performance. Few lowest-level or intermediate drivers need to set up their own driver-dedicated or device-dedicated system threads, and those that do pay a performance penalty caused by context switches to their threads. + +Most kernel-mode drivers, like the physical device driver in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure, execute in an arbitrary thread context: that of whatever thread happens to be current when they are called to process an IRP. Consequently, drivers usually maintain state about their I/O operations and the devices they service in a driver-defined part of their device objects, called a *device extension*. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20Thread%20Context%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driver-x64-restrictions.md b/windows-driver-docs-pr/kernel/driver-x64-restrictions.md new file mode 100644 index 0000000000..90ef2dfb9a --- /dev/null +++ b/windows-driver-docs-pr/kernel/driver-x64-restrictions.md @@ -0,0 +1,37 @@ +--- +title: Driver x64 Restrictions +author: windows-driver-content +description: Driver x64 Restrictions +ms.assetid: 717ca559-93aa-48d6-8347-bfdf223f1aa4 +--- + +# Driver x64 Restrictions + + +On x64-based systems, kernel code and certain kernel data structures are protected from modification. Any driver that attempts to modify such code or data will cause the system to bug check (with the CRITICAL\_STRUCTURE\_CORRUPTION bug check). + +Drivers for x64-based systems must avoid operations that might trigger this bug check. In particular, drivers must not: + +- Attempt to modify kernel code at run time. + +- Implement and use their own stacks. + +- Modify hardware dispatch tables, such as the interrupt dispatch table (IDT) or global descriptor table (GDT). + +- Modify undocumented kernel data structures. + +Even though the preceding operations will not trigger a bug check on x86-based or Itanium-based systems, drivers should not perform any of these operations on any platform. These operations might not work in future versions of the Microsoft Windows operating system. + +For more information about modifying kernel code and data structures, see the [Patching Policy for x64-based Systems](http://go.microsoft.com/fwlink/p/?linkid=50719) white paper and the [64-Bit Patching FAQ](http://go.microsoft.com/fwlink/p/?linkid=69534) on the Windows Hardware Developer Central (WHDC) website. + +For general information about programming with a 64-bit compiler, see [64-Bit Programming with Visual C++](http://go.microsoft.com/fwlink/p/?linkid=165521). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Driver%20x64%20Restrictions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driverentry-return-values.md b/windows-driver-docs-pr/kernel/driverentry-return-values.md new file mode 100644 index 0000000000..26a77ebd2c --- /dev/null +++ b/windows-driver-docs-pr/kernel/driverentry-return-values.md @@ -0,0 +1,40 @@ +--- +title: DriverEntry Return Values +author: windows-driver-content +description: DriverEntry Return Values +ms.assetid: 052be2ea-375a-4495-931e-8b66972125a5 +keywords: ["DriverEntry WDK kernel , return values", "return values WDK DriverEntry routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DriverEntry Return Values + + +## + + +A [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine returns an [NTSTATUS value](ntstatus-values.md), either STATUS\_SUCCESS or an appropriate error status. + +The **DriverEntry** routine should postpone any call to [**IoRegisterDriverReinitialization**](https://msdn.microsoft.com/library/windows/hardware/ff549511) until just before it returns STATUS\_SUCCESS. It must not make this call unless it will return STATUS\_SUCCESS. + +If a **DriverEntry** routine returns an NTSTATUS value that is not a success or informational value, such as STATUS\_SUCCESS, the driver for that **DriverEntry** routine is not loaded. + +A **DriverEntry** routine that will fail initialization must free any system objects, system resources, and registry resources it has already set up before it returns control. It should reset the driver's dispatch entry points in the driver object for [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760) and [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807) to **NULL** if the driver supports these requests. + +If a driver will fail initialization, the **DriverEntry** routine also should log an error before returning control. See [Logging Errors](logging-errors.md). + +Note that a driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine is not called if a driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine returns a failure status. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DriverEntry%20Return%20Values%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driverentry-s-optional-responsibilities.md b/windows-driver-docs-pr/kernel/driverentry-s-optional-responsibilities.md new file mode 100644 index 0000000000..e70dca314b --- /dev/null +++ b/windows-driver-docs-pr/kernel/driverentry-s-optional-responsibilities.md @@ -0,0 +1,62 @@ +--- +title: DriverEntry's Optional Responsibilities +author: windows-driver-content +description: DriverEntry's Optional Responsibilities +ms.assetid: 859282f7-6b40-47a8-b845-cdb7c26585dd +keywords: ["DriverEntry WDK kernel , optional responsibilities", "claiming hardware resources", "executive worker threads WDK kernel", "worker threads WDK kernel", "system-space memory allocations WDK kernel", "system resource storage WDK kernel", "storing system resources", "hardware resource claiming WDK kernel", "resource claiming WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DriverEntry's Optional Responsibilities + + +## + + +Depending on the position of a particular driver in a chain of layered drivers, the nature of the underlying device, and the design of the driver, a [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine also can be responsible for the following: + +- Calling [**IoAllocateDriverObjectExtension**](https://msdn.microsoft.com/library/windows/hardware/ff548233) to create and initialize a driver object extension, if the driver requires storage for data on a driver-wide basis. The driver object extension is a driver-specific data structure. For example, a driver might use its driver object extension to store a registry path or other global information. + +- Calling [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932) to create executive worker threads, if the driver is a highest-level driver (such as a file system driver) that uses such threads. In this case, the driver must also have a callback routine of type WORKER\_THREAD\_ROUTINE, which takes a single input PVOID *Parameter*. + +- Registering a [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routine. (See [Writing a Reinitialize Routine](writing-a-reinitialize-routine.md).) + +- Handling class-specific initialization requirements that differ from those discussed here, such as those that a device-specific miniport or miniclass driver working in tandem with a port or class driver might have. See the device-type specific documentation in the Windows Driver Kit (WDK) for details. + +### Providing Storage for System Resources + +Per-device objects should be allocated in the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine or in the Dispatch routine that handles the PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, not in **DriverEntry**. + +However, a driver might need to allocate additional system-space memory for other driver-wide uses. If so, the **DriverEntry** routine can call one (or more) of the following routines: + +- **IoAllocateDriverObjectExtension**, to create a context area associated with the driver object + +- [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) for paged or nonpaged system-space memory + +- [**MmAllocateNonCachedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554479) or [**MmAllocateContiguousMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554460) for cache-aligned nonpaged system-space memory (used for I/O buffers) + +Every **DriverEntry** routine is run in the context of a system thread at IRQL = PASSIVE\_LEVEL. Therefore, any memory allocated with **ExAllocatePoolWithTag** for use exclusively during initialization can be from paged pool, as long as the driver does not control the device that holds the system page file. The allocated memory must be released with [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) before **DriverEntry** returns control. However, a driver that sets a *Reinitialize* routine can pass a pointer to this memory when it calls [**IoRegisterDriverReinitialization**](https://msdn.microsoft.com/library/windows/hardware/ff549511), thus making the driver's *Reinitialize* routine responsible for freeing the memory allocation. + +### Claiming Hardware Resources + +Older, non-PnP drivers claimed resources from the registry. PnP drivers, on the other hand, neither claim device resources from nor directly write resource requirements to the registry. Instead, these drivers report requirements in response to certain PnP IRPs, as part of the PnP manager's enumeration process. A PnP driver receives its allocated resources in a PnP **IRP\_MN\_START\_DEVICE** request. + +Drivers that do not interact directly with the PnP manager, such as certain miniport drivers, might have different reporting requirements imposed by a class or port driver that does interact with the PnP manager. Such requirements are specific to the device class. For device-specific and class-specific details, see the documentation for the relevant device class in the Windows Driver Kit (WDK). + +### Using the Registry + +A **DriverEntry** routine might use the registry to get some of the information it needs to initialize the driver, or it might set information in the registry for other drivers or protected subsystems to use. The nature of the information depends on the type of device. Drivers can access the registry using **Zw*Xxx*** and **Rtl*Xxx*** routines. The **DriverEntry** routine's *RegistryPath* parameter points to a counted Unicode string that specifies a path to the driver's registry key, **\\Registry\\Machine\\System\\CurrentControlSet\\Services\\*DriverName***. The routine should save a copy of the string, not the pointer itself, since the pointer is no longer valid after **DriverEntry** returns. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DriverEntry's%20Optional%20Responsibilities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/driverentry-s-required-responsibilities.md b/windows-driver-docs-pr/kernel/driverentry-s-required-responsibilities.md new file mode 100644 index 0000000000..f39d34808d --- /dev/null +++ b/windows-driver-docs-pr/kernel/driverentry-s-required-responsibilities.md @@ -0,0 +1,52 @@ +--- +title: DriverEntry's Required Responsibilities +author: windows-driver-content +description: DriverEntry's Required Responsibilities +ms.assetid: 6e997875-e7b7-43e2-8398-f0574f3a5816 +keywords: ["DriverEntry WDK kernel , required responsibilities"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# DriverEntry's Required Responsibilities + + +## + + +The required, ordered responsibilities of a [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine are as follows: + +1. Supply entry points for the driver's standard routines. + + The driver stores entry points for many of its standard routines in the driver object or driver extension. Such entry points include those for the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, dispatch routines, [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, and [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine. For example, a driver would set the entry points for its *AddDevice*, [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341), and [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routines with statements like the following (*Xxx* is a placeholder for a vendor-supplied prefix identifying the driver): + + ``` + : + DriverObject->DriverExtension->AddDevice = XxxAddDevice; + DriverObject->MajorFunction[IRP_MJ_PNP] = XxxDispatchPnp; + DriverObject->MajorFunction[IRP_MJ_POWER] = XxxDispatchPower; + : + ``` + + Additional standard routines, such as ISRs or [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines, are specified by calling system support routines. For more information, see the descriptions of individual [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842). + +2. Create and/or initialize various driver-wide objects, types, or resources the driver uses. Note that most standard routines use objects on a per-device basis, so drivers should set up such objects in their *AddDevice* routines or after receiving an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. + + If the driver has a device-dedicated thread or waits on any kernel-defined dispatcher objects, the **DriverEntry** routine might initialize [kernel dispatcher objects](kernel-dispatcher-objects.md). (Depending on how the driver uses the object(s), it might instead perform this task in its *AddDevice* routine or after receiving an **IRP\_MN\_START\_DEVICE** request.) + +3. Free any memory that it allocated and is no longer required. + +4. Return NTSTATUS indicating whether the driver successfully loaded and can accept and process requests from the PnP manager to configure, add, and start its devices. (See [DriverEntry Return Values](driverentry-return-values.md).) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20DriverEntry's%20Required%20Responsibilities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-architecture.md b/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-architecture.md new file mode 100644 index 0000000000..a93080f6ee --- /dev/null +++ b/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-architecture.md @@ -0,0 +1,39 @@ +--- +title: Dynamic Hardware Partitioning Architecture +author: windows-driver-content +description: Dynamic Hardware Partitioning Architecture +ms.assetid: 1b6a1dc5-ec32-4bb9-acaf-14db284b4a0e +keywords: ["dynamic hardware partitioning WDK , architecture", "hardware partitioning WDK dynamic , architecture", "partitions WDK dynamic hardware , architecture", "architecture WDK dynamic hardware partitioning", "dynamically partitionable servers WDK", "servers WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dynamic Hardware Partitioning Architecture + + +A hardware partitionable server can be configured into one or more isolated hardware partitions. A hardware partition consists of one or more partition units. A partition unit can be a processor, a memory module, or an I/O host bridge. + +The following figure shows an example of a hardware partitionable server. + +![diagram illustrating a hardware partitionable server](images/dhparch.gif) + +In the previous figure, the server has a total of 12 partition units: four memory modules, four processor modules, and four I/O host bridge modules. Each of these partition units is assigned to one of three hardware partitions. Each hardware partition is completely isolated from the other hardware partitions. The service processor is responsible for the configuration of the hardware partitions. It controls the mapping of the partition units to the hardware partitions and creates isolation between the hardware partitions. + +Starting with Windows Server 2008, each partition unit is considered a Plug and Play (PnP) device. Because these devices are PnP, you can add them after the operating system has started. + +For more information about how a device driver can register itself with the operating system to receive notification when partition units are dynamically added to the hardware partition, see [Driver Notification](driver-notification.md). + +For more information about how an application can register itself with the operating system to receive notification when partition units are dynamically added to the hardware partition, see [Application Notification](application-notification.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dynamic%20Hardware%20Partitioning%20Architecture%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-techniques.md b/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-techniques.md new file mode 100644 index 0000000000..ea30b01857 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dynamic-hardware-partitioning-techniques.md @@ -0,0 +1,39 @@ +--- +title: Dynamic Hardware Partitioning Techniques +author: windows-driver-content +description: Dynamic Hardware Partitioning Techniques +ms.assetid: 6a99e848-a0db-40e1-81b4-fd73a0e1c321 +keywords: ["dynamic hardware partitioning WDK", "hardware partitioning WDK dynamic", "partitions WDK dynamic hardware"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Dynamic Hardware Partitioning Techniques + + +Changing the hardware configuration of a server while the server is running is known as *dynamic hardware partitioning*. If you want to run your device drivers on servers that support dynamic hardware partitioning, your drivers must support dynamic changes to the hardware configuration of the server. + +This section includes the following topics: + +[Introduction to Dynamic Hardware Partitioning](introduction-to-dynamic-hardware-partitioning.md) + +[Dynamic Hardware Partitioning Architecture](dynamic-hardware-partitioning-architecture.md) + +[Critical Issues for Device Drivers](critical-issues-for-device-drivers.md) + +[Driver Notification](driver-notification.md) + +[Application Notification](application-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dynamic%20Hardware%20Partitioning%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/dynamically-configuring-msi-x.md b/windows-driver-docs-pr/kernel/dynamically-configuring-msi-x.md new file mode 100644 index 0000000000..6c28a1e766 --- /dev/null +++ b/windows-driver-docs-pr/kernel/dynamically-configuring-msi-x.md @@ -0,0 +1,31 @@ +--- +title: Dynamically Configuring MSI-X +author: windows-driver-content +description: Dynamically Configuring MSI-X +ms.assetid: 53051239-e00f-41e8-b95d-9618693e696d +--- + +# Dynamically Configuring MSI-X + + +Windows Vista Service Pack 1 (SP1), Windows Server 2008, and later operating systems support dynamically modifying the properties of MSI-X interrupt messages. (The PCI 3.0 specification defined MSI-X.) The PCI bus driver exposes the [GUID\_MSIX\_TABLE\_CONFIG\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/ff546563) interface to allow drivers for PCI devices to modify the settings in the bus hardware interrupt table. + +Drivers use the interface by sending an [**IRP\_MN\_QUERY\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff551687) request to the bus driver, with the *InterfaceType* parameter equal to GUID\_MSIX\_TABLE\_CONFIG\_INTERFACE. The bus driver supplies a pointer to a [**PCI\_MSIX\_TABLE\_CONFIG\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff558787) structure, which supplies pointers to three routines that modify the interrupt table: + +- [*SetTableEntry*](https://msdn.microsoft.com/library/windows/hardware/gg604857) assigns a message ID to the hardware table entry. + +- [*MaskTableEntry*](https://msdn.microsoft.com/library/windows/hardware/gg604852) masks the interrupt corresponding to a hardware table entry. + +- [*UnmaskTableEntry*](https://msdn.microsoft.com/library/windows/hardware/gg604859) unmasks the interrupt corresponding to a hardware table entry. + +By default, the interrupt table is configured so that the first entry has message ID zero, the second entry has message ID one, and so on. If the number of table entries exceeds the number of messages, each additional table entry is assigned message ID zero. (The message ID is the index for the interrupt's entry in the **MessageInfo** member of the [**IO\_INTERRUPT\_MESSAGE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff550576) structure that describes the driver's message-signaled interrupts. The [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) routine supplies a pointer to this structure.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Dynamically%20Configuring%20MSI-X%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/enabling-device-wake-up.md b/windows-driver-docs-pr/kernel/enabling-device-wake-up.md new file mode 100644 index 0000000000..3da016c824 --- /dev/null +++ b/windows-driver-docs-pr/kernel/enabling-device-wake-up.md @@ -0,0 +1,34 @@ +--- +title: Enabling Device Wake-Up +author: windows-driver-content +description: Enabling Device Wake-Up +ms.assetid: 1c3b9ebc-cc77-4562-9c57-56f2c9a69772 +keywords: ["IRPs WDK power management", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "IRP_MJ_POWER", "DEVICE_CAPABILITIES structure", "restoring power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling Device Wake-Up + + +## + + +If a device supports wake-up, its power policy owner must be able to enable and disable wake-up for the device. A driver enables wake up by sending an [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) request with minor function code [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) and disables wake-up by canceling a previously sent **IRP\_MN\_WAIT\_WAKE**. A device can have only one **IRP\_MN\_WAIT\_WAKE** request pending at a time. + +To determine whether its device supports wake-up, the device power states from which it can signal wake-up, and the system power states from which the device can wake the system, a driver checks the **SystemWake**, **DeviceWake**, and **WakeFromD***x* members in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. + +For more information about enabling, disabling, and responding to wake-up signals in a driver, see [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Enabling%20Device%20Wake-Up%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/enabling-message-signaled-interrupts-in-the-registry.md b/windows-driver-docs-pr/kernel/enabling-message-signaled-interrupts-in-the-registry.md new file mode 100644 index 0000000000..003347528b --- /dev/null +++ b/windows-driver-docs-pr/kernel/enabling-message-signaled-interrupts-in-the-registry.md @@ -0,0 +1,45 @@ +--- +title: Enabling Message-Signaled Interrupts in the Registry +author: windows-driver-content +description: Enabling Message-Signaled Interrupts in the Registry +ms.assetid: 802ad994-51e7-4aef-a0f0-865dfaf4e6ce +keywords: ["message-signaled interrupts WDK kernel , enabling", "enabling message-signaled interrupts WDK kernel", "MSIs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enabling Message-Signaled Interrupts in the Registry + + +To receive message-signaled interrupts (MSIs), a driver's INF file must enable MSIs in the registry during installation. Use the **Interrupt Management\\MessageSignaledInterruptProperties** subkey of the device's hardware key to enable MSI support. + +The **MSISupported** entry of **Interrupt Management\\MessageSignaledInterruptProperties** is a REG\_DWORD value that determines whether the device supports MSIs. Set **MSISupported** to 1 to enable MSI support. + +You can also use the registry to specify the maximum number of MSIs to allocate for their device. The **MessageNumberLimit** entry of **Interrupt Management\\MessageSignaledInterruptProperties** is a REG\_DWORD value that specifies the maximum number of MSIs to allocate. For PCI 2.2, **MessageNumberLimit** must be 1, 2, 4, 8, or 16. For PCI 3.0, **MessageNumberLimit** can be any number up to 2,048. + +Use an [**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320) in your driver's INF file to set registry keys under the device's hardware key. For more information, see [**INF DDInstall.HW Section**](https://msdn.microsoft.com/library/windows/hardware/ff547330). + +The following code example shows how to set the **MSISupported** entry under **Interrupt Management\\MessageSignaledInterruptProperties** for the device. Note that you must first create the **Interrupt Management** and **Interrupt Management\\MessageSignaledInterruptProperties** keys before you can set the **MSISupported** entry. + +``` +[mydevice.HW] +AddReg = mydevice_addreg + +[mydevice_addreg] +HKR,Interrupt Management,,0x00000010 +HKR,Interrupt Management\MessageSignaledInterruptProperties,,0x00000010 +HKR,Interrupt Management\MessageSignaledInterruptProperties,MSISupported,0x00010001,1 +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Enabling%20Message-Signaled%20Interrupts%20in%20the%20Registry%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/enabling-transitions-to-d3cold.md b/windows-driver-docs-pr/kernel/enabling-transitions-to-d3cold.md new file mode 100644 index 0000000000..6d83ab4c2f --- /dev/null +++ b/windows-driver-docs-pr/kernel/enabling-transitions-to-d3cold.md @@ -0,0 +1,40 @@ +--- +title: Enabling Transitions to D3cold +author: windows-driver-content +description: All versions of Windows enable a device to be in D3cold while the computer is sleeping (in one of the system low-power states, S1 through S4). +ms.assetid: C2C6166D-8269-4FCE-81A8-B350626052D4 +--- + +# Enabling Transitions to D3cold + + +All versions of Windows enable a device to be in D3cold while the computer is sleeping (in one of the system low-power states, S1 through S4). Before the computer exits S0, the function drivers, bus drivers, and filter drivers work together to move the device to D3hot. When the computer enters the low-power Sx state, this transition has the side effect of moving the device from D3hot to D3cold. + +Starting with Windows 8, a device can enter and exit D3cold while the computer remains in S0. The driver that is the power policy owner (PPO) for a device can enable and disable these transitions to D3cold. A driver should not enable its device to enter D3cold unless the device can, if required, wake from D3cold, and then resume normal operation after the transition to D0. + +When a device enters D3, it initially enters the D3hot substate of D3. From D3hot, the device can enter either D0 or D3cold. In response to a wake event or I/O request, the device enters D0 from D3hot. Otherwise, the device might remain in D3hot, or it might move from D3hot to D3cold. For more information about these transitions, see the device power state [diagram](device-power-states.md#power-state-diagram) in [Device Power States](device-power-states.md). + +The driver does not initiate the device's transition from D3hot to D3cold. Instead, this transition occurs when all the other devices that share a common power source with this device are in D3hot and are prepared to enter D3cold. When the last of these devices enters D3hot, the underlying bus drivers and system firmware remove the power source and the devices enter D3cold in unison. + +The PPO driver for a device tells the operating system whether to enable the device's transition from D3hot to D3cold. The driver can supply this information in the INF file that installs the device, or the driver can call the [*SetD3ColdSupport*](https://msdn.microsoft.com/library/windows/hardware/hh967716) routine at run time to dynamically enable or disable the device's transitions to D3cold. For more information, see [Using the GUID\_D3COLD\_SUPPORT\_INTERFACE Driver Interface](using-guid-d3cold-support-interface.md). + +By enabling a device to enter D3cold, a driver guarantees the following behavior: + +- The device can tolerate a transition from D3hot to D3cold when the computer is to remain in S0. +- The device will work properly when it returns to D0 from D3cold. + +A device that fails to meet either requirement might, after entering D3cold, be unavailable until the computer is restarted or enters a sleeping state. If the device must be able to signal a wake event from any low-power Dx state that it enters, entry to D3cold must not be enabled unless the driver is certain that the device's wake signal will work in D3cold. + +Putting a device in D3cold doesn't necessarily mean that all sources of power to the device have been removed; it means only that the sources of power that allow communication to the device through the bus are gone. The device might still be able to draw enough power to signal a wake event to the processor. For example, an Ethernet network interface card (NIC) whose main power source is removed might draw power from the Ethernet cable. + +Because D3cold is a state where the bus cannot be used to communicate with the device, a driver can't put its device into D3cold directly. Instead, the driver first calls the [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) routine to request a D3 power IRP (an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request with target state = **PowerDeviceD3**) to move the device from D0 to D3hot. After entering D3hot, the device may or may not move from D3hot to D3cold. The device enters D3cold only when power to the bus is removed, which occurs if the parent bus driver turns off the bus or if the system firmware turns off power to a section of the hardware platform. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Enabling%20Transitions%20to%20D3cold%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/end-user-i-o-requests-and-file-objects.md b/windows-driver-docs-pr/kernel/end-user-i-o-requests-and-file-objects.md new file mode 100644 index 0000000000..cfe90c3b71 --- /dev/null +++ b/windows-driver-docs-pr/kernel/end-user-i-o-requests-and-file-objects.md @@ -0,0 +1,52 @@ +--- +title: End-User I/O Requests and File Objects +author: windows-driver-content +description: End-User I/O Requests and File Objects +ms.assetid: 69524f41-32c4-4a62-b666-6eb2e4657877 +keywords: ["IRPs WDK kernel , end-user I/O requests", "end-user I/O requests WDK kernel", "I/O requests WDK kernel", "named file objects WDK kernel", "file objects WDK kernel", "protected subsystems WDK kernel", "subsystem I/O requests WDK kernel", "user I/O requests WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# End-User I/O Requests and File Objects + + +## + + +Kernel-mode drivers are hidden from end users by a protected subsystem that implements an already familiar programming interface, such as Windows or POSIX. Devices are visible to user-mode code, which includes protected subsystems, only as named file objects controlled by the I/O manager. + +The following figure illustrates this relationship between an end user, a subsystem, and the I/O manager. + +![diagram illustrating file objects representing files, volumes, and devices](images/2grsover.png) + +A protected subsystem, such as the Win32 subsystem, passes I/O requests to the appropriate kernel-mode driver through the I/O system services. The subsystem shown in the previous figure depends on support from the display, video adapter, keyboard, and mouse device drivers. + +A protected subsystem insulates its end users and applications from having to know anything about kernel-mode components, including drivers. In turn, the I/O manager insulates protected subsystems from having to know anything about machine-specific device configurations or about drivers' implementations. + +The I/O manager's layered approach also insulates most drivers from having to know anything about the following: + +- Whether an I/O request originated in any particular protected subsystem, such as Win32 or POSIX + +- Whether a given protected subsystem has particular kinds of user-mode drivers + +- What any protected subsystem's I/O model and interface to drivers is + +The I/O manager supplies drivers with a single I/O model, a set of kernel-mode support routines that drivers can use to carry out I/O operations, and a consistent interface between the originator of an I/O request and the drivers that must respond to it. + +As shown in the previous figure, a subsystem and its native applications can access a driver's device or a file on a mass-storage device only through file object handles supplied by the I/O manager. To open such a file object or to obtain a handle for I/O to a device or a data file, a subsystem calls the I/O system services with a request to open a named file. The named file can have a subsystem-specific alias (symbolic link) to the kernel-mode name for the file object. + +The I/O manager, which exports these system services, is then responsible for locating or creating the file object that represents the device or data file and for locating the appropriate driver(s). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20End-User%20I/O%20Requests%20and%20File%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/enlistment-objects.md b/windows-driver-docs-pr/kernel/enlistment-objects.md new file mode 100644 index 0000000000..24b7467eb9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/enlistment-objects.md @@ -0,0 +1,37 @@ +--- +title: Enlistment Objects +author: windows-driver-content +description: Enlistment Objects +ms.assetid: 80e61475-4bb7-4eaa-b9f1-ff95eac9bc77 +keywords: ["enlistments WDK KTM", "enlistments WDK KTM , objects", "resource managers WDK KTM , creating enlistments", "Kernel Transaction Manager WDK , enlistments", "KTM WDK , enlistments", "enlistment objects WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Enlistment Objects + + +An *enlistment object* represents a resource manager's [*enlistment*](transaction-processing-terms.md#ktm-term-enlistment) to a transaction. Before a resource manager can receive notifications about a transaction's events, the resource manager must call [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) to create an enlistment to the transaction. + +KTM provides a set of [enlistment object routines](https://msdn.microsoft.com/library/windows/hardware/ff544270) that kernel-mode resource managers can call. KTM also provides a similar set of user-mode routines that user-mode applications can call. For more information about the user-mode routines, see the Microsoft Windows SDK. + +KTM creates an enlistment object when a resource manager calls **ZwCreateEnlistment** to enlist in a transaction that the resource manager has received (typically from a transactional client). + +[TPS components](understanding-tps-components.md) can call [**ZwOpenEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567008) to open additional handles to an enlistment object. But most TPS designs do not require additional open handles. + +Resource managers close their handles to enlistment objects by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). If the last handle is closed before the associated transaction object has been committed, KTM sends TRANSACTION\_NOTIFY\_ROLLBACK notifications to all the resource managers that have an enlistment for the transaction. + +The operating system deletes the object after the last handle is closed and KTM has released all its references to the object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Enlistment%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/eprocess.md b/windows-driver-docs-pr/kernel/eprocess.md new file mode 100644 index 0000000000..b8f0c14057 --- /dev/null +++ b/windows-driver-docs-pr/kernel/eprocess.md @@ -0,0 +1,323 @@ +--- +title: Windows kernel opaque structures +author: windows-driver-content +description: Windows kernel opaque structures +ms.assetid: 4053d82e-78ae-4945-ad5b-44ba41229a5d +--- + +# Windows kernel opaque structures + + +The following table contains Windows kernel opaque structures: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Opaque StructureDescription
EPROCESS

The EPROCESS structure is an opaque structure that serves as the process object for a process.

+

Some routines, such as [PsGetProcessCreateTimeQuadPart](https://msdn.microsoft.com/library/windows/hardware/ff559939), use EPROCESS to identify the process to operate on. Drivers can use the [PsGetCurrentProcess](https://msdn.microsoft.com/library/windows/hardware/ff559933) routine to obtain a pointer to the process object for the current process and can use the [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679) routine to obtain a pointer to the process object that is associated with the specified handle. The [PsInitialSystemProcess](https://msdn.microsoft.com/library/windows/hardware/ff559943) global variable points to the process object for the system process.

+

Note that a process object is an Object Manager object. Drivers should use Object Manager routines such as [ObReferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff558678) and [ObDereferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff557724) to maintain the object's reference count.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

ETHREAD

The ETHREAD structure is an opaque structure that serves as the thread object for a thread.

+

Some routines, such as [PsIsSystemThread](https://msdn.microsoft.com/library/windows/hardware/ff559945), use ETHREAD to identify the thread to operate on. Drivers can use the [PsGetCurrentThread](https://msdn.microsoft.com/library/windows/hardware/ff559936) routine to obtain a pointer to the thread object for the current thread and can use the [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679) routine to obtain a pointer to the thread object that is associated with the specified handle.

+

Note that a thread object is an Object Manager object. Drivers should use Object Manager routines such as [ObReferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff558678) and [ObDereferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff557724) to maintain the object's reference count.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

EX_RUNDOWN_REF

The EX_RUNDOWN_REF structure is an opaque system structure that contains information about the status of run-down protection for an associated shared object.

+
typedef struct _EX_RUNDOWN_REF {
+  
+  ...  // opaque
+  
+} EX_RUNDOWN_REF, *PEX_RUNDOWN_REF;
+

The run-down protection routines all take a pointer to an EX_RUNDOWN_REF structure as their first parameter. These routines are listed at the bottom of this page.

+

For more information, see [Run-Down Protection](run-down-protection.md).

+

Header: Wdm.h. Include Wdm.h.

EX_TIMER

The EX_TIMER structure is an opaque structure that is used by the operating system to represent an EX_TIMER timer object.

+
typedef struct _EX_TIMER *PEX_TIMER;
+

All members of this structure are opaque to drivers.

+

The following ExXxxTimer routines require a pointer to a system-allocated EX_TIMER structure as an input parameter:

+
    +
  • [ExSetTimer](https://msdn.microsoft.com/library/windows/hardware/dn265188)
  • +
  • [ExCancelTimer](https://msdn.microsoft.com/library/windows/hardware/dn265180)
  • +
  • [ExDeleteTimer](https://msdn.microsoft.com/library/windows/hardware/dn265181)
  • +
+

EX_TIMER-based timer objects are created by the operating system. To get such a timer object, your driver calls the [ExAllocateTimer](https://msdn.microsoft.com/library/windows/hardware/dn265179) routine. When this object is no longer needed, the driver is responsible for deleting the object by calling ExDeleteTimer.

+

For more information, see [ExXxxTimer Routines and EX_TIMER Objects](exxxxtimer-routines-and-ex-timer-objects.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

FAST_MUTEX

A FAST_MUTEX structure is an opaque data structure that represents a fast mutex.

+

A FAST_MUTEX structure is initialized by the [ExInitializeFastMutex](https://msdn.microsoft.com/library/windows/hardware/ff545293) routine.

+

For more information about fast mutexes, see [Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_CSQ

The IO_CSQ structure is an opaque structure used to specify the driver's cancel-safe IRP queue routines. Do not set the members of this structure directly. Use [IoCsqInitialize](https://msdn.microsoft.com/library/windows/hardware/ff549054) or [IoCsqInitializeEx](https://msdn.microsoft.com/library/windows/hardware/ff549060) to initialize this structure.

+

For an overview of how to use cancel-safe IRP queues, see [Cancel-Safe IRP Queues](cancel-safe-irp-queues.md).

+

Available on Microsoft Windows XP and later versions of the Windows operating system.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_CSQ_IRP_CONTEXT

The IO_CSQ_IRP_CONTEXT structure is an opaque data structure used to specify the IRP context for an IRP in the driver's cancel-safe IRP queue. It is used as a key by the [IoCsqInsertIrp](https://msdn.microsoft.com/library/windows/hardware/ff549066), [IoCsqInsertIrpEx](https://msdn.microsoft.com/library/windows/hardware/ff549067), and [IoCsqRemoveIrp](https://msdn.microsoft.com/library/windows/hardware/ff549070) routines to identify particular IRPs in the queue.

+

For an overview of how to use cancel-safe IRP queues, see [Cancel-Safe IRP Queues](cancel-safe-irp-queues.md).

+

Available on Microsoft Windows XP and later versions of the Windows operating system.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

IO_WORKITEM

The IO_WORKITEM structure is an opaque structure that describes a work item for a system worker thread.

+

A driver can allocate a work item by calling [IoAllocateWorkItem](https://msdn.microsoft.com/library/windows/hardware/ff548276). Alternatively, a driver can allocate its own buffer, and then call [IoInitializeWorkItem](https://msdn.microsoft.com/library/windows/hardware/ff549349) to initialize that buffer as a work item.

+

Any work item that is allocated by IoAllocateWorkItem must be freed by [IoFreeWorkItem](https://msdn.microsoft.com/library/windows/hardware/ff549133). Any memory that is initialized by IoInitializeWorkItem must be uninitialized by [IoUninitializeWorkItem](https://msdn.microsoft.com/library/windows/hardware/ff550392) before it can be freed.

+

For more information about work items, see [System Worker Threads](system-worker-threads.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KBUGCHECK_CALLBACK_RECORD

The KBUGCHECK_CALLBACK_RECORD structure is an opaque structure that is used by the [KeRegisterBugCheckCallback](https://msdn.microsoft.com/library/windows/hardware/ff553105) and [KeDeregisterBugCheckCallback](https://msdn.microsoft.com/library/windows/hardware/ff551992) routines.

+

The KBUGCHECK_CALLBACK_RECORD structure is used for bookkeeping by the [KeRegisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff553110) and [KeDeregisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff552003) routines.

+

The structure must be allocated in resident memory, such as nonpaged pool. Use the [KeInitializeCallbackRecord](https://msdn.microsoft.com/library/windows/hardware/ff552109) routine to initialize the structure before using it.

+

Header: Ntddk.h. Include: Ntddk.h.

KBUGCHECK_REASON_CALLBACK_RECORD

The KBUGCHECK_REASON_CALLBACK_RECORD structure is an opaque structure that is used by the [KeRegisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff553110) and [KeDeregisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff552003) routines.

+

The KBUGCHECK_REASON_CALLBACK_RECORD structure is used for bookkeeping by the [KeRegisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff553110) and [KeDeregisterBugCheckReasonCallback](https://msdn.microsoft.com/library/windows/hardware/ff552003) routines.

+

The structure must be allocated in resident memory, such as nonpaged pool. Use the [KeInitializeCallbackRecord](https://msdn.microsoft.com/library/windows/hardware/ff552109) routine to initialize the structure before using it.

+

Available on Microsoft Windows XP with Service Pack 1 (SP1), Windows Server 2003, and later versions of the Windows operating system.

+

Header: Ntddk.h. Include: Ntddk.h.

KDPC

The KDPC structure is an opaque structure that represents a DPC object. Do not set the members of this structure directly. See [DPC Objects and DPCs](dpc-objects-and-dpcs.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KFLOATING_SAVE

The KFLOATING_SAVE structure is an opaque structure that describes the floating-point state that the [KeSaveFloatingPointState](https://msdn.microsoft.com/library/windows/hardware/ff553243) routine saved.

+

Use [KeRestoreFloatingPointState](https://msdn.microsoft.com/library/windows/hardware/ff553185) to restore the floating-point state.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KGUARDED_MUTEX

The KGUARDED_MUTEX structure is an opaque structure that represents a guarded mutex.

+

Use KeInitializeGuardedMutex to initialize a KGUARDED_MUTEX structure as a guarded mutex.

+

Guarded mutexes must be allocated from non-paged pool.

+

For more information about guarded mutexes, see [Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KINTERRUPT

A KINTERRUPT structure is an opaque structure that represents an interrupt to the system.

+

[IoConnectInterruptEx](https://msdn.microsoft.com/library/windows/hardware/ff548378) provides a pointer to the KINTERRUPT structure for the interrupt when the driver registers an [InterruptService](https://msdn.microsoft.com/library/windows/hardware/ff547958) or [InterruptMessageService](https://msdn.microsoft.com/library/windows/hardware/ff547940) routine. The driver uses this pointer when acquiring or releasing the interrupt spin lock for the interrupt. The driver also uses this pointer when unregistering an InterruptService routine.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KLOCK_QUEUE_HANDLE

The KLOCK_QUEUE_HANDLE structure is an opaque structure that describes a queued spin lock. The driver allocates the KLOCK_QUEUE_HANDLE structure, and passes it to [KeAcquireInStackQueuedSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff551899) and [KeAcquireInStackQueuedSpinLockAtDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff551908) to acquire the queued spin lock. Those routines initialize the structure to represent the queued spin lock. The driver passes the structure to [KeReleaseInStackQueuedSpinLock](https://msdn.microsoft.com/library/windows/hardware/ff553130) and [KeReleaseInStackQueuedSpinLockFromDpcLevel](https://msdn.microsoft.com/library/windows/hardware/ff553137) when releasing the spin lock.

+

For more information, see [Queued Spin Locks](queued-spin-locks.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

KTIMER

The KTIMER structure is an opaque structure that represents a timer object. Do not set the members of this structure directly. For more information, see [Timer Objects and DPCs](timer-objects-and-dpcs.md).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

LOOKASIDE_LIST_EX

The LOOKASIDE_LIST_EX structure describes a lookaside list.

+
typedef struct _LOOKASIDE_LIST_EX {
+  ...  // opaque
+} LOOKASIDE_LIST_EX, *PLOOKASIDE_LIST_EX;
+

A lookaside list is a pool of fixed-size buffers that the driver can manage locally to reduce the number of calls to system allocation routines and, thereby, to improve performance. The buffers are of uniform size and are stored as entries in the lookaside list.

+

Drivers should treat the LOOKASIDE_LIST_EX structure as opaque. Drivers that access structure members or that have dependencies on the locations of these members might not remain portable and interoperable with other drivers.

+

The following See Also section contains a list of the routines that use this structure.

+

For more information about lookaside lists, see [Using Lookaside Lists](using-lookaside-lists.md).

+

On 64-bit platforms, this structure must be 16-byte aligned.

+

Supported starting with Windows Vista.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

NPAGED_LOOKASIDE_LIST

The NPAGED_LOOKASIDE_LIST structure is an opaque structure that describes a lookaside list of fixed-size buffers allocated from nonpaged pool. The system creates new entries and destroys unused entries on the list as necessary. For fixed-size buffers, using a lookaside list is quicker than allocating memory directly.

+

Use [ExInitializeNPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff545301) to initialize the lookaside list. Use [ExAllocateFromNPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544388) to allocate a buffer from the list, and [ExFreeToNPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544601) to return a buffer to the list.

+

Drivers must always explicitly free any lookaside lists they create before unloading. It is a serious programming error to do otherwise. Use [ExDeleteNPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544566) to free the list.

+

Drivers can also use lookaside lists for paged pool. Starting with Windows 2000, a PAGED_LOOKASIDE_LIST structure describes a lookaside list that contains paged buffers. Starting with Windows Vista, a LOOKASIDE_LIST_EX structure can describe a lookaside list that contains either paged or nonpaged buffers. For more information, see [Using Lookaside Lists](using-lookaside-lists.md).

+

On 64-bit platforms, this structure must be 16-byte aligned.

+

Supported starting with Windows 2000.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

OBJECT_TYPE

OBJECT_TYPE is an opaque structure that specifies the object type of a handle. For more information, see [ObReferenceObjectByHandle](https://msdn.microsoft.com/library/windows/hardware/ff558679).

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

PAGED_LOOKASIDE_LIST

The PAGED_LOOKASIDE_LIST structure is an opaque structure that describes a lookaside list of fixed-size buffers allocated from paged pool. The system creates new entries and destroys unused entries on the list as necessary. For fixed-size buffers, using a lookaside list is quicker than allocating memory directly.

+

Use [ExInitializePagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff545309) to initialize the lookaside list. Use [ExAllocateFromPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544393) to allocate a buffer from the list, and [ExFreeToPagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544605) to return a buffer to the list.

+

Drivers must always explicitly free any lookaside lists they create before unloading. It is a serious programming error to do otherwise. Use [ExDeletePagedLookasideList](https://msdn.microsoft.com/library/windows/hardware/ff544570) to free the list.

+

Drivers can also use lookaside lists for nonpaged pool. Starting with Windows 2000, an NPAGED_LOOKASIDE_LIST structure describes a lookaside list that contains nonpaged buffers. Starting with Windows Vista, a LOOKASIDE_LIST_EX structure can describe a lookaside list that contains either paged or nonpaged buffers. For more information, see [Using Lookaside Lists](using-lookaside-lists.md).

+

On 64-bit platforms, this structure must be 16-byte aligned.

+

Supported starting with Windows 2000.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

RTL_BITMAP

The RTL_BITMAP structure is an opaque structure that describes a bitmap.

+
typedef struct _RTL_BITMAP {
+  // opaque
+} RTL_BITMAP, *PRTL_BITMAP;
+

Do not directly access the members of this structure. Drivers that have dependencies on member locations or that access member values directly might not remain compatible with future versions of the Windows operating system.

+

The RTL_BITMAP structure serves as a header for a general-purpose, one-dimensional bitmap of arbitrary length. A driver can use such a bitmap as an economical way to keep track of a set of reusable items. For example, a file system can use bitmaps to track which clusters and sectors on a hard disk have already been allocated to hold file data.

+

For a list of the RtlXxx routines that use RTL_BITMAP structures, see the following See Also section. The caller of these RtlXxx routines is responsible for allocating the storage for the RTL_BITMAP structure and for the buffer that contains the bitmap. This buffer must begin on a four-byte boundary in memory and must be a multiple of four bytes in length. The bitmap begins at the start of the buffer but can contain any number of bits that will fit in the allocated buffer.

+

Before supplying an RTL_BITMAP structure as a parameter to an RtlXxx routine, call the [RtlInitializeBitMap](https://msdn.microsoft.com/library/windows/hardware/ff561925) routine to initialize the structure. The input parameters to this routine are a pointer to a buffer that contains the bitmap, and the size, in bits, of the bitmap. RtlInitializeBitMap does not change the contents of this buffer.

+

If the caller allocates the storage for the RTL_BITMAP structure and bitmap in paged memory, the caller must be running at IRQL <= APC_LEVEL when it passes a pointer to this structure as a parameter to any of the RtlXxx routines that are listed in the See Also section. If the caller allocates the storage from nonpaged memory (or, equivalently, from paged memory that is locked), the caller can be running at any IRQL when it calls the RtlXxx routine.

+

Supported in Windows 2000 and later versions of Windows.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

RTL_RUN_ONCE

The RTL_RUN_ONCE structure is an opaque structure that stores the information for a one-time initialization.

+

Drivers must initialize this structure by calling the [RtlRunOnceInitialize](https://msdn.microsoft.com/library/windows/hardware/ff562767) routine before passing it to any other RtlRunOnceXxx routines.

+

Available only on Windows Vista and later versions of the Windows operating system.

+

Header: Ntddk.h. Include: Ntddk.h.

SECURITY_SUBJECT_CONTEXT

The SECURITY_SUBJECT_CONTEXT structure is an opaque structure that represents the security context within which a particular operation is taking place.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

SLIST_HEADER

An SLIST_HEADER structure is an opaque structure that serves as the header for a sequenced singly linked list. For more information, see [Singly and Doubly Linked Lists](singly-and-doubly-linked-lists.md).

+

On 64-bit platforms, SLIST_HEADER structures must be 16-byte aligned.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

XSTATE_SAVE

The XSTATE_SAVE structure is an opaque structure that describes the extended processor state information that a kernel-mode driver saves and restores.

+
typedef struct _XSTATE_SAVE {
+  ...  // opaque
+} XSTATE_SAVE, *PXSTATE_SAVE;
+

All members are opaque.

+

This structure is used by the [KeSaveExtendedProcessorState](https://msdn.microsoft.com/library/windows/hardware/ff553238) and [KeRestoreExtendedProcessorState](https://msdn.microsoft.com/library/windows/hardware/ff553182) routines.

+

Supported in Windows 7 and later versions of the Windows operating system.

+

Header: Wdm.h. Include: Wdm.h, Ntddk.h, Ntifs.h.

+ +  + +## Related topics +[**BugCheckDumpIoCallback**](https://msdn.microsoft.com/library/windows/hardware/ff540677) +[**BugCheckSecondaryDumpDataCallback**](https://msdn.microsoft.com/library/windows/hardware/ff540679) +[**ExAcquireFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff544337) +[**ExAcquireFastMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff544340) +[**ExAllocateFromLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544381) +[**ExAllocateFromNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544388) +[**ExAllocateFromPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544393) +[**ExAllocateTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265179) +[**ExDeletePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544570) +[**ExFreeToPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544605) +[**ExInitializePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545309) +[**ExCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265180) +[**ExDeleteLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544563) +[**ExDeleteNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544566) +[**ExDeleteTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265181) +[**ExFlushLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544587) +[**ExFreeToLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544597) +[**ExFreeToNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544601) +[**ExInitializeLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff545298) +[**ExInitializeNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545301) +[**ExInitializeSListHead**](https://msdn.microsoft.com/library/windows/hardware/ff545321) +[**ExInterlockedFlushSList**](https://msdn.microsoft.com/library/windows/hardware/ff545379) +[**ExInterlockedPopEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545414) +[**ExInterlockedPushEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545422) +[**ExQueryDepthSList**](https://msdn.microsoft.com/library/windows/hardware/ff545502) +[**ExReleaseFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff545549) +[**ExReleaseFastMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff545567) +[**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) +[**ExTryToAcquireFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff545647) +[*ExTimerCallback*](https://msdn.microsoft.com/library/windows/hardware/dn265190) +[**IoAllocateWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff548276) +[**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) +[**IoCsqInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff549054) +[**IoCsqInitializeEx**](https://msdn.microsoft.com/library/windows/hardware/ff549060) +[**IoCsqInsertIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549066) +[**IoCsqInsertIrpEx**](https://msdn.microsoft.com/library/windows/hardware/ff549067) +[**IoCsqRemoveIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549070) +[**IoDisconnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff549093) +[**IoFreeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549133) +[**IoInitializeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549349) +[**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) +[**IoUninitializeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff550392) +[**KeAcquireGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff551892) +[**KeAcquireGuardedMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff551894) +[**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) +[**KeAcquireInStackQueuedSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551908) +[**KeAcquireInterruptSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551914) +[**KeCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/ff551970) +[**KeInitializeCallbackRecord**](https://msdn.microsoft.com/library/windows/hardware/ff552109) +[**KeInitializeGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff552144) +[**KeInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff552168) +[**KeInitializeTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff552173) +[**KeReadStateTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553099) +[**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182) +[**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) +[**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) +[**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292) +[**KeDeregisterBugCheckCallback**](https://msdn.microsoft.com/library/windows/hardware/ff551992) +[**KeDeregisterBugCheckReasonCallback**](https://msdn.microsoft.com/library/windows/hardware/ff552003) +[**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185) +[**KeRegisterBugCheckCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553105) +[**KeRegisterBugCheckReasonCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553110) +[**KeReleaseGuardedMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff553125) +[**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) +[**KeReleaseInStackQueuedSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553137) +[**KeReleaseInterruptSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553139) +[**KeRestoreFloatingPointState**](https://msdn.microsoft.com/library/windows/hardware/ff553185) +[**KeSaveFloatingPointState**](https://msdn.microsoft.com/library/windows/hardware/ff553243) +[**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) +[*LookasideListAllocateEx*](https://msdn.microsoft.com/library/windows/hardware/ff554322) +[*LookasideListFreeEx*](https://msdn.microsoft.com/library/windows/hardware/ff554324) +[**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) +[**PsGetCurrentProcess**](https://msdn.microsoft.com/library/windows/hardware/ff559933) +[**PsGetProcessCreateTimeQuadPart**](https://msdn.microsoft.com/library/windows/hardware/ff559939) +[**PsInitialSystemProcess**](https://msdn.microsoft.com/library/windows/hardware/ff559943) +[**PsIsSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559945) +[**RtlRunOnceBeginInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff562759) +[**RtlRunOnceComplete**](https://msdn.microsoft.com/library/windows/hardware/ff562763) +[**RtlRunOnceExecuteOnce**](https://msdn.microsoft.com/library/windows/hardware/ff562765) +[**RtlRunOnceInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff562767) +[*RunOnceInitialization*](https://msdn.microsoft.com/library/windows/hardware/ff563635) +[Run-Down Protection](run-down-protection.md) +[**SeAccessCheck**](https://msdn.microsoft.com/library/windows/hardware/ff563674) +[**SeAssignSecurity**](https://msdn.microsoft.com/library/windows/hardware/ff563676) +[**SeAssignSecurityEx**](https://msdn.microsoft.com/library/windows/hardware/ff563679) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20opaque%20structures%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/eresource-structures.md b/windows-driver-docs-pr/kernel/eresource-structures.md new file mode 100644 index 0000000000..c08f25ac6e --- /dev/null +++ b/windows-driver-docs-pr/kernel/eresource-structures.md @@ -0,0 +1,34 @@ +--- +title: ERESOURCE Structures +author: windows-driver-content +description: ERESOURCE Structures +ms.assetid: 202b2ef1-bbe4-4ffd-a82b-21f19c145e8d +keywords: ["synchronization WDK kernel , ERESOURCE structures", "locking WDK kernel", "read/write locking WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ERESOURCE Structures + + +## + + +You can use the ERESOURCE structures to implement read/writer locking in your driver. The system provides a set of routines to manipulate the ERESOURCE structures, which are documented in this section. + +This section contains the following topic: + +[Introduction to ERESOURCE Routines](introduction-to-eresource-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20ERESOURCE%20Structures%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/errors-in-a-multiprocessor-environment.md b/windows-driver-docs-pr/kernel/errors-in-a-multiprocessor-environment.md new file mode 100644 index 0000000000..cef484bfdd --- /dev/null +++ b/windows-driver-docs-pr/kernel/errors-in-a-multiprocessor-environment.md @@ -0,0 +1,74 @@ +--- +title: Errors in a Multiprocessor Environment +author: windows-driver-content +description: Errors in a Multiprocessor Environment +ms.assetid: 8a76b8d6-14d8-4709-8b15-e8b6b5094a1b +keywords: ["reliability WDK kernel , race conditions", "race conditions WDK kernel", "reliability WDK kernel , multiprocessor environment errors", "multiprocessor environment errors WDK kernel", "locking WDK kernel", "multiple I/O request handling WDK kernel", "I/O requests WDK kernel", "thread conflicts WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Errors in a Multiprocessor Environment + + +## + + +On the NT-based operating system, drivers are multithreaded; they can receive multiple I/O requests from different threads at the same time. In designing a driver, you must assume that it will be run on an SMP system and take the appropriate measures to ensure data integrity. + +Specifically, whenever a driver changes global or file object data, it must use a lock or an interlocked sequence to prevent race conditions. + +### Encountering a race condition when referencing global or file object-specific data + +In the following code snippet, a race condition could occur when the driver accesses the global data at **Data.LpcInfo**: + +``` + PLPC_INFO pLpcInfo = &Data.LpcInfo; //Pointer to global data + ... + ... + // This saved pointer may be overwritten by another thread. + pLpcInfo->LpcPortName.Buffer = ExAllocatePool( + PagedPool, + arg->PortName.Length); + +``` + +Multiple threads entering this code as a result of an IOCTL call could cause a memory leak as the pointer is overwritten. To avoid this problem, the driver should use the **ExInterlocked*Xxx*** routines or some type of lock when it changes the global data. The driver's requirements determine the acceptable types of locks. For further information, see [Spin Locks](spin-locks.md), [Kernel Dispatcher Objects](kernel-dispatcher-objects.md), and [**ExAcquireResourceSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544363). + +The following example attempts to reallocate a file-specific buffer (**Endpoint->LocalAddress**) to hold the endpoint address: + +``` + Endpoint = FileObject->FsContext; + + if ( Endpoint->LocalAddress != NULL && + Endpoint->LocalAddressLength < + ListenEndpoint->LocalAddressLength ) { + + FREE_POOL (Endpoint->LocalAddress, + LOCAL_ADDRESS_POOL_TAG + ); + Endpoint->LocalAddress = NULL; + } + + if ( Endpoint->LocalAddress == NULL ) { + Endpoint->LocalAddress = + ALLOCATE_POOL (NonPagedPool, + ListenEndpoint->LocalAddressLength, + LOCAL_ADDRESS_POOL_TAG); + } +``` + +In this example, a race condition could occur with accesses to the file object. Because the driver does not hold any locks, two requests for the same file object can enter this function. The result might be references to freed memory, multiple attempts to free the same memory, or memory leaks. To avoid these errors, the two **if** statements should be enclosed in a spin lock. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Errors%20in%20a%20Multiprocessor%20Environment%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/errors-in-buffered-i-o.md b/windows-driver-docs-pr/kernel/errors-in-buffered-i-o.md new file mode 100644 index 0000000000..3e18d74ce9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/errors-in-buffered-i-o.md @@ -0,0 +1,36 @@ +--- +title: Errors in Buffered I/O +author: windows-driver-content +description: Errors in Buffered I/O +ms.assetid: e9f51710-5c76-46df-9d4d-b30a56d9274f +keywords: ["reliability WDK kernel , buffered I/O errors", "I/O WDK kernel , buffered I/O", "buffered I/O WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Errors in Buffered I/O + + +## + + +The following topics describe some common problems that occur in drivers that perform buffered I/O operations: + +[Failure to Check the Size of Buffers](failure-to-check-the-size-of-buffers.md) + +[Failure to Initialize Output Buffers](failure-to-initialize-output-buffers.md) + +[Failure to Validate Variable-length Buffers](failure-to-validate-variable-length-buffers.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Errors%20in%20Buffered%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/errors-in-direct-i-o.md b/windows-driver-docs-pr/kernel/errors-in-direct-i-o.md new file mode 100644 index 0000000000..76c3846ed4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/errors-in-direct-i-o.md @@ -0,0 +1,64 @@ +--- +title: Errors in Direct I/O +author: windows-driver-content +description: Errors in Direct I/O +ms.assetid: 9efc2875-3402-4e2e-871b-3cc1d8f45360 +keywords: ["reliability WDK kernel , direct I/O", "direct I/O WDK kernel", "I/O WDK kernel , direct I/O", "zero-length buffers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Errors in Direct I/O + + +## + + +The most common direct I/O problem is failing to handle zero-length buffers correctly. Because the I/O manager does not create MDLs for zero-length transfers, a zero-length buffer results in a **NULL** value at **Irp->MdlAddress**. + +To map the address space, drivers should use [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559), which returns **NULL** if mapping fails, as it will if a driver passes a **NULL** **MdlAddress**. Drivers should always check for a **NULL** return before attempting to use the returned address. + +Direct I/O involves double-mapping the user's address space to a system address buffer, so that two different virtual addresses have the same physical address. Double-mapping has the following consequences, which can sometimes cause problems for drivers: + +- The offset into the virtual page of the user's address becomes the offset into the system page. + + Access beyond the end of these system buffers may go unnoticed for long periods of time depending on the page granularity of the mapping. Unless a caller's buffer is allocated near the end of a page, data written beyond the end of the buffer will nevertheless appear in the buffer, and the caller will be unaware that any error has occurred. If the end of the buffer coincides with the end of a page, the system virtual addresses beyond the end could point to anything or could be invalid. Such problems can be extremely difficult to find. + +- If the calling process has another thread that modifies the user's mapping of the memory, the contents of the system buffer will change when the user's memory mapping changes. + + In this situation, using the system buffer to store scratch data can cause problems. Two fetches from the same memory location might yield different values. + + The following code snippet receives a string in a direct I/O request, then tries to convert that string to uppercase characters: + + ``` + PWCHAR PortName = NULL; + + PortName = (PWCHAR)MmGetSystemAddressForMdlSafe(irp->MdlAddress, NormalPagePriority); + + // + // Null-terminate the PortName so that RtlInitUnicodeString will not + // be invalid. + // + PortName[Size / sizeof(WCHAR) - 1] = UNICODE_NULL; + + RtlInitUnicodeString(&AdapterName, PortName); + ``` + + Because the buffer might not be correctly formed, the code attempts to force a Unicode **NULL** as the last buffer character. However, if the underlying physical memory is doubly mapped to both a user- and a kernel-mode address, another thread in the process can overwrite the buffer as soon as this write operation completes. + + Conversely, if the **NULL** is not present, then the call to **RtlInitUnicodeString** can exceed the range of the buffer and possibly cause a bug check if it falls outside the system mapping. + +If a driver creates and maps its own MDL, it should ensure that it accesses the MDL only with the method for which it has probed. That is, when the driver calls [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664), it specifies an access method (**IoReadAccess**, **IoWriteAccess**, or **IoModifyAccess**). If the driver specifies **IoReadAccess**, it must not later attempt to write to the system buffer made available by [**MmGetSystemAddressForMdl**](https://msdn.microsoft.com/library/windows/hardware/ff554556) or [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Errors%20in%20Direct%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/errors-in-handling-cleanup-and-close-operations.md b/windows-driver-docs-pr/kernel/errors-in-handling-cleanup-and-close-operations.md new file mode 100644 index 0000000000..5c31ba2898 --- /dev/null +++ b/windows-driver-docs-pr/kernel/errors-in-handling-cleanup-and-close-operations.md @@ -0,0 +1,32 @@ +--- +title: Errors in Handling Cleanup and Close Operations +author: windows-driver-content +description: Errors in Handling Cleanup and Close Operations +ms.assetid: 9d449974-99b1-4d38-9bbb-54938d67c23a +keywords: ["reliability WDK kernel , errors", "DispatchClose", "DispatchCleanup", "cleanup errors WDK kernel", "close errors WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Errors in Handling Cleanup and Close Operations + + +## + + +Some drivers fail to distinguish the tasks required in [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) and [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routines. The I/O manager calls a driver's *DispatchCleanup* routine when the last handle to a file object is closed. The *DispatchClose* routine is called when the last reference is released from the file object. A driver should not attempt to free resources in its *DispatchCleanup* routine that are attached to a file object or might be used by other *Dispatch*Xxx routines. + +When calling dispatch routines, the I/O manager holds a reference to the file object for normal I/O calls. As a result, a driver can receive I/O requests for a file object after its *DispatchCleanup* routine has been called but before its *DispatchClose* routine is called. For example, a user-mode caller might close the file handle while an I/O manager request is in progress from another thread. If the driver has deleted or freed necessary resources before the I/O manager calls its *DispatchClose* routine, invalid pointer references and other problems could occur. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Errors%20in%20Handling%20Cleanup%20and%20Close%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/errors-in-referencing-user-space-addresses.md b/windows-driver-docs-pr/kernel/errors-in-referencing-user-space-addresses.md new file mode 100644 index 0000000000..3db90086d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/errors-in-referencing-user-space-addresses.md @@ -0,0 +1,102 @@ +--- +title: Errors in Referencing User-Space Addresses +author: windows-driver-content +description: Errors in Referencing User-Space Addresses +ms.assetid: 87944805-e4ba-431e-b673-b0125dc9ec24 +keywords: ["reliability WDK kernel , user-space addresses", "user-space address referencing WDK kernel", "referencing user-space address", "embedded pointers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Errors in Referencing User-Space Addresses + + +## + + +Any driver, whether supporting IRPs or fast I/O operations, should validate any address in user space before trying to use it. The I/O manager does not validate such addresses, nor does it validate pointers that are embedded in buffers passed to drivers. + +### Failure to Validate Addresses Passed in METHOD\_NEITHER IOCTLs and FSCTLs + +The I/O manager does no validation whatsoever for METHOD\_NEITHER IOCTLs and FSCTLs. To ensure that user-space addresses are valid, the driver must use the [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) and [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) routines, enclosing all buffer references in **try/except** blocks. + +In the following example, the driver assumes that the value passed in the **Type3InputBuffer** represents a valid address. + +``` + case IOCTL_GET_HANDLER: + { + PULONG EntryPoint; + + EntryPoint = + IrpSp->Parameters.DeviceIoControl.Type3InputBuffer; + *EntryPoint = (ULONG)DriverEntryPoint; + ... + } +``` + +The following code avoids this problem: + +``` + case IOCTL_GET_HANDLER: + { + PULONG_PTR EntryPoint; + + EntryPoint = + IrpSp->Parameters.DeviceIoControl.Type3InputBuffer; + + try + { + if (Irp->RequestorMode != KernelMode) + { + ProbeForWrite(EntryPoint, + sizeof(ULONG_PTR), + TYPE_ALIGNMENT(ULONG_PTR)); + } + *EntryPoint = (ULONG_PTR)DriverEntryPoint; + } + except(EXCEPTION_EXECUTE_HANDLER) + { + ... + } + ... + } +``` + +Note also that the correct code casts **DriverEntryPoint** to a ULONG\_PTR, instead of a ULONG. This change allows for use in a 64-bit Windows environment. + +### Failure to validate pointers embedded in buffered I/O requests + +Often drivers embed pointers within buffered requests, as in the following example: + +``` + struct ret_buf + { + void *arg; // Pointer embedded in request + int rval; + }; + + pBuf = Irp->AssociatedIrp.SystemBuffer; + ... + arg = pBuf->arg; // Fetch the embedded pointer + ... + // If the arg pointer is not valid, the following + // statement can corrupt the system: + RtlMoveMemory(arg, &info, sizeof(info)); +``` + +In this example, the driver should validate the embedded pointer by using the **Probe*Xxx*** routines enclosed in a **try/except** block in the same way as for the METHOD\_NEITHER IOCTLs described earlier. Although embedding a pointer allows a driver to return extra information, a driver can more efficiently achieve the same result by using a relative offset or a variable length buffer. + +For more information about using **try/except** blocks to handle invalid addresses, see [Handling Exceptions](handling-exceptions.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Errors%20in%20Referencing%20User-Space%20Addresses%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/event-objects.md b/windows-driver-docs-pr/kernel/event-objects.md new file mode 100644 index 0000000000..111020e2c1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/event-objects.md @@ -0,0 +1,36 @@ +--- +title: Event Objects +author: windows-driver-content +description: Event Objects +ms.assetid: da9df4a2-26cf-4861-80ca-1790ca059e45 +keywords: ["kernel dispatcher objects WDK , event objects", "dispatcher objects WDK kernel , event objects", "event objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Event Objects + + +## + + +A driver can use an event object to wait while the next-lower driver processes an IRP set up by the waiting driver. Drivers that have driver-created threads or driver dispatch routines that wait for the completion of a synchronous I/O request also can use an event object to synchronize operations between their threads and/or other driver routines. + +This section contains the following topics: + +[Defining and Using an Event Object](defining-and-using-an-event-object.md) + +[Standard Event Objects](standard-event-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Event%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/example-i-o-request---an-overview.md b/windows-driver-docs-pr/kernel/example-i-o-request---an-overview.md new file mode 100644 index 0000000000..de93fab564 --- /dev/null +++ b/windows-driver-docs-pr/kernel/example-i-o-request---an-overview.md @@ -0,0 +1,54 @@ +--- +title: Example I/O Request - An Overview +author: windows-driver-content +description: Example I/O Request - An Overview +ms.assetid: ffc9030e-4b03-4899-88a0-ed6ffd79fd58 +keywords: ["opening file objects", "named file objects WDK kernel", "file objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Example I/O Request - An Overview + + +## + + +The following figure shows an overview of what happens when a subsystem opens a file object representing a data file on behalf of an application. + +![diagram illustrating opening a file object](images/2opendev.png) + +1. The subsystem calls an I/O system service to open a named file. + +2. The I/O manager calls the object manager to look up the named file and to help it resolve any symbolic links for the file object. It also calls the security reference monitor to check that the subsystem has the correct access rights to open that file object. + +3. If the volume is not yet mounted, the I/O manager suspends the open request temporarily and calls one or more file systems until one of them recognizes the file object as something it has stored on one of the mass-storage devices the file system uses. When the file system has mounted the volume, the I/O manager resumes the request. + +4. The I/O manager allocates memory for and initializes an IRP for the open request. To drivers, an open is equivalent to a "create" request. + +5. The I/O manager calls the file system driver, passing it the IRP. The file system driver accesses its I/O stack location in the IRP to determine what operation it must carry out, checks parameters, determines if the requested file is in cache, and, if not, sets up the next-lower driver's I/O stack location in the IRP. + +6. Both drivers process the IRP and complete the requested I/O operation, calling kernel-mode support routines supplied by the I/O manager and by other system components (not shown in the previous figure). + +7. The drivers return the IRP to the I/O manager with the I/O status block set in the IRP to indicate whether the requested operation succeeded or why it failed. + +8. The I/O manager gets the I/O status from the IRP, so it can return status information through the protected subsystem to the original caller. + +9. The I/O manager frees the completed IRP. + +10. The I/O manager returns a handle for the file object to the subsystem if the open operation was successful. If there was an error, it returns appropriate status to the subsystem. + +After a subsystem successfully opens a file object that represents a data file, a device, or a volume, the subsystem uses the returned handle to identify the file object in subsequent requests for device I/O operations (usually read, write, or device I/O control requests). To make such a request, the subsystem calls I/O system services. The I/O manager routes these requests as IRPs sent to appropriate drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Example%20I/O%20Request%20-%20An%20Overview%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/example-i-o-request---the-details.md b/windows-driver-docs-pr/kernel/example-i-o-request---the-details.md new file mode 100644 index 0000000000..469e92ded3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/example-i-o-request---the-details.md @@ -0,0 +1,66 @@ +--- +title: Example I/O Request - The Details +author: windows-driver-content +description: Example I/O Request - The Details +ms.assetid: 480db6a1-2a13-4f1a-87ff-c3bd37aa79be +keywords: ["I/O stack locations WDK kernel", "layered driver IRP processing WDK kernel", "stack locations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Example I/O Request - The Details + + +## + + +The figure illustrating opening a file object shows an IRP with two I/O stack locations, but an IRP can have any number of I/O stack locations, depending on how many layered drivers will handle a given request. + +The following figure illustrates in more detail how the drivers in the [Opening a File Object](example-i-o-request---an-overview.md) figure use I/O support routines (**Io*Xxx*** routines) to process the IRP for a read or write request. + +![diagram illustrating processing irps in layered drivers](images/2girpeg.png) + +1. The I/O manager calls the file system driver (FSD) with the IRP it has allocated for the subsystem's read/write request. The FSD accesses its I/O stack location in the IRP to determine what operation it should carry out. + +2. The FSD can break the original request into smaller requests (possibly for more than one device driver) by calling an I/O support routine ([**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257)) one or more times to allocate additional IRPs. The additional IRPs are returned to the FSD with zero-filled I/O stack location(s) for lower-level driver(s). At its discretion, the FSD can reuse the original IRP, rather than allocating additional IRPs as shown in the previous figure, by setting up the next-lower driver's I/O stack location in the original IRP and passing it on to lower drivers. + +3. For each driver-allocated IRP, the FSD in the previous figure calls an I/O support routine to register an FSD-supplied completion routine; in the completion routine, the FSD can determine whether lower drivers satisfied the request and can free each driver-allocated IRP when lower drivers have completed it. The I/O manager will call the FSD-supplied completion routine whether each driver-allocated IRP was completed successfully, completed with an error status, or canceled. A higher-level driver is responsible for freeing any IRPs it allocates and sets up on its own behalf for lower-level drivers. The I/O manager frees the IRPs that it allocates after all drivers have completed them. + + Next, the FSD calls an I/O support routine ([**IoGetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549266)) to access the next-lower-level driver's I/O stack location in order to set up the request for the next-lower driver. (In the previous figure, the next lower driver happens to be the lowest-level driver.) The FSD then calls an I/O support routine ([**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336)) to pass that IRP on to the next-lower driver. + +4. When it is called with the IRP, the lowest-level driver checks its I/O stack location to determine what operation (indicated by the **IRP\_MJ\_*XXX*** function code) it should carry out on the target device. The target device is represented by the device object in its designated I/O stack location and is passed with the IRP to the driver. The lowest-level driver can assume that the I/O manager has routed the IRP to an entry point that the driver defined for the **IRP\_MJ\_*XXX*** operation (here [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819)) and that the higher-level driver has checked the validity of other parameters for the request. + + If there were no higher-level driver, the lowest-level driver would check whether the input parameters for an **IRP\_MJ\_*XXX*** operation are valid. If they are, the driver usually calls I/O support routines to tell the I/O manager that a device operation is pending on the IRP and to either queue the IRP or pass it on to another driver-supplied routine that accesses the target device (here, a physical or logical device: the disk or a partition on the disk). + +5. The I/O manager determines whether the driver is already busy processing another IRP for the target device, queues the IRP if it is, and returns. Otherwise, the I/O manager routes the IRP to a driver-supplied routine that starts the I/O operation on its device. (At this stage, both drivers in the previous figure and the I/O manager return control.) + +6. When the device interrupts, the driver's interrupt service routine (ISR) does only as much work as it must to stop the device from interrupting and to save necessary context about the operation. The ISR then calls an I/O support routine ([**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657)) with the IRP to queue a driver-supplied DPC (Deferred Procedure Call) routine to complete the requested operation at a lower hardware priority than the ISR. + +7. When the driver's DPC gets control, it uses the context (passed in the ISR's call to [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657)) to complete the I/O operation. The DPC calls a support routine to dequeue the next IRP (if any) and to pass that IRP on to the driver-supplied routine that starts I/O operations on the device (see Step 5). The DPC then sets status about the just-completed operation in the IRP's I/O status block and returns it to the I/O manager with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +8. The I/O manager zeros the lowest-level driver's I/O stack location in the IRP and calls the file system's registered completion routine (see Step 3) with the FSD-allocated IRP. This completion routine checks the I/O status block to determine whether to retry the request or to update any internal state maintained about the original request and to free its driver-allocated IRP. The file system can collect status information for all driver-allocated IRPs it sends to lower-level drivers so that it can set I/O status and complete the original IRP. When the file system has completed the original IRP, the I/O manager returns and NTSTATUS value to the original requester (the subsystem's native function) of the I/O operation. + +Like the file system driver shown in the [Processing IRPs in Layered Drivers](#ddk-example-i-o-request---the-details-kg) figure, any new driver that is added to a chain of existing drivers can do all of the following: + +- Set its own completion routine into an IRP. The [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine checks the I/O status block to determine whether lower drivers completed the IRP successfully, canceled the IRP, and/or completed it with an error. The completion routine can also update any IRP-specific state the driver might have saved, release any operation-specific resources the driver might have allocated, and so forth, before completing the IRP. In addition, the completion routine can postpone IRP completion (by informing the I/O manager that more processing is required on the IRP), and can send another request to the next-lower-level driver before allowing the IRP to complete. + +- Set up the next-lower-level driver's I/O stack location in the IRPs it allocates and send requests to the next-lower-level driver. + +- Pass any incoming requests on to lower drivers by setting up the next-lower driver's I/O stack location in each IRP and calling [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). (Note that for IRPs with major function code [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784), drivers must use [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654).) + +Each driver-created device object represents a physical, logical, or virtual device for which a particular driver carries out I/O requests. For detailed information about creating and setting up a device object, see [Device Objects and Device Stacks](device-objects-and-device-stacks.md). + +As the [Processing IRPs in Layered Drivers](#ddk-example-i-o-request---the-details-kg) figure also shows, most drivers process each IRP in stages through a driver-supplied set of system-defined *standard routines*, but drivers at different levels in a chain necessarily have different standard routines. For example, only lowest-level drivers handle interrupts from a physical device, so only a lowest-level driver would have an ISR and a DPC that completes interrupt-driven I/O operations. On the other hand, because such a driver knows that I/O is complete when it receives an interrupt from its device, it has no need for a completion routine. Only a higher-level driver would have one or more completion routines like the FSD in this figure. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Example%20I/O%20Request%20-%20The%20Details%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/example-wdm-device-objects.md b/windows-driver-docs-pr/kernel/example-wdm-device-objects.md new file mode 100644 index 0000000000..f6ee9c69e3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/example-wdm-device-objects.md @@ -0,0 +1,42 @@ +--- +title: Example WDM Device Objects +author: windows-driver-content +description: Example WDM Device Objects +ms.assetid: 8da56415-5018-468c-99c7-3969e5c00285 +keywords: ["device objects WDK kernel , examples", "mouse WDK kernel", "keyboards WDK kernel", "functional device objects WDK kernel", "FDO WDK kernel", "physical device objects WDK kernel", "PDOs WDK kernel", "filter DOs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Example WDM Device Objects + + +## + + +The following figure illustrates the device objects that represent the keyboard and mouse devices shown previously in the figure illustrating [Keyboard and Mouse Hardware Configurations](sample-device-and-driver-configuration.md#keyboard-and-mouse-hardware-configurations). The keyboard and mouse drivers shown in the figure illustrating [Keyboard and Mouse Driver Layers](sample-device-and-driver-configuration.md#keyboard-and-mouse-driver-layers) create these device objects by calling an I/O support routine ([**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397)). + +![keyboard and mouse device objects](images/2sampdos.png) + +For the keyboard and mouse devices, both their respective port and class drivers create device objects. The port driver creates a physical device object (PDO) to represent the physical port. Each class driver creates its own functional device object (FDO) to represent the keyboard or mouse device as a target for I/O requests. + +Each class driver calls an I/O support routine to get a pointer to the next-lower-level driver's device object, so the class driver can chain itself above that driver, which is the port driver. Then the class driver can send I/O requests down to the port driver for the target PDO representing its physical device. + +An optional filter driver added to the configuration would create a filter device object (filter DO). Like the class driver, an optional filter driver chains itself to the next-lower driver in the device stack and sends I/O requests for the target PDO down to the next-lower driver. + +As shown previously in the [Keyboard and Mouse Driver Layers](sample-device-and-driver-configuration.md#keyboard-and-mouse-driver-layers) figure, each port driver is a bus (lowest-level) driver, so every port driver of a device that generates interrupts must set up interrupt object(s) and register an ISR. + +A dual-device port driver, like the i8042 driver for the keyboard and auxiliary device controller shown in the [Keyboard and Mouse Hardware Configurations](sample-device-and-driver-configuration.md#keyboard-and-mouse-hardware-configurations) figure, must set up device-specific [*interrupt objects*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-interrupt-object) if each device uses a different interrupt vector. When writing such a driver, you can either implement separate ISRs for each device or implement a single ISR for both devices. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Example%20WDM%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/example-wdm-device-stack.md b/windows-driver-docs-pr/kernel/example-wdm-device-stack.md new file mode 100644 index 0000000000..9f835ba15d --- /dev/null +++ b/windows-driver-docs-pr/kernel/example-wdm-device-stack.md @@ -0,0 +1,76 @@ +--- +title: Example WDM Device Stack +author: windows-driver-content +description: Example WDM Device Stack +ms.assetid: 1128e098-9ef4-4bc3-aa09-74df3142fb11 +keywords: ["device stacks WDK kernel , examples", "joystick WDK device stacks", "functional device objects WDK kernel", "FDO WDK kernel", "physical device objects WDK kernel", "PDOs WDK kernel", "filter DOs WDK kernel", "USB hub device stacks WDK kernel", "USB host controller device stacks WDK kernel", "PCI bus device stacks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Example WDM Device Stack + + +## + + +This section describes the device objects created by a possible set of drivers for USB hardware to illustrate WDM device objects and how they are layered. + +The following figure shows the device objects that are created by the sample drivers described in [WDM Driver Layers: An Example](wdm-driver-layers---an-example.md). + +![diagram illustrating sample wdm device object layers for a usb joystick](images/joydobj.png) + +Starting at the bottom of this figure, the device objects in the sample device stacks include: + +1. A PDO and an FDO for the PCI bus. + + The root bus driver enumerates the internal system bus (the root bus) and creates a PDO for each device it finds. One of these PDOs is for the PCI bus. (The PDO and FDO for the root bus are not shown in the figure.) + + The PnP manager identifies the PCI driver as the function driver for the PCI bus, loads the driver (if it is not already loaded), and passes the PDO to the PCI driver. In its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, the PCI driver creates an FDO for the PCI bus ([**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397)) and attaches the FDO to the device stack ([**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300)) for the PCI bus. The PCI driver creates and attaches this FDO as part of its responsibilities as the function driver for the PCI bus. + + There are no filter drivers for the PCI bus in this example. + +2. A PDO and an FDO for the USB host controller. + + The PnP manager directs the PCI driver to start its device ([**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749)) and then queries the PCI driver for its children ([**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) with relation type of **BusRelations**). In response, the PCI driver enumerates the devices on its bus. In this example, the PCI driver finds a USB host controller and creates a PDO for that device. The wide arrow in the figure indicates that the USB host controller is a "child" of the PCI bus. The PCI driver creates PDOs for its child devices as part of its responsibilities as the bus driver for the PCI bus. + + The PnP manager identifies the USB host controller miniclass/class driver pair as the function driver for the USB host controller and loads the driver pair. The PnP manager calls the driver pair at the appropriate time to create and attach an FDO for the USB host controller. + + There are no filter drivers for the USB host controller in this example. + +3. A PDO and an FDO for the USB hub. + + The USB host controller enumerates its bus, locates the USB hub in the sole port, and creates a PDO for the hub. The USB hub driver creates and attaches an FDO for the hub. + + There are no filter drivers for the USB hub in this example. + +4. A PDO, an FDO, and two filter DOs for the joystick device. + + The USB hub driver enumerates its bus, locates a HID device (the joystick), and creates a PDO for the joystick. + + In this example, a lower-level filter driver has been set up in the registry for joystick devices, so the PnP manager loads the filter driver. The filter driver determines that it is relevant to the device and creates and attaches a filter DO to the device stack. + + The PnP manager determines that the function driver for the joystick device is the HID class/miniclass driver pair and loads those drivers. The driver pair consists of a miniclass driver linked to a class driver DLL; together they act as one function driver for the device. The class/miniclass driver pair creates one device object, the FDO, and attaches it to the device stack. + + An upper-level filter driver creates and attaches a filter DO to the device stack, in a manner similar to the lower-level filter. + +Note that the PDO created by the parent bus driver is always at the bottom of the device stack for a particular device. When drivers handle PnP or power IRPs, they must pass each IRP all the way down the device stack to the PDO and its associated bus driver. + +The following figure shows the same device stacks as the previous figure, but emphasizes which device objects are created and managed by which drivers. + +![diagram illustrating sample device object layers from the driver perspective](images/joydobj2.png) + +A bus driver spans more than one device stack. A bus driver creates the FDO for its bus adapter/controller and creates a PDO for each of its child devices. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Example%20WDM%20Device%20Stack%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/extended-example--defining-a--64bit--field.md b/windows-driver-docs-pr/kernel/extended-example--defining-a--64bit--field.md new file mode 100644 index 0000000000..b43db3d11b --- /dev/null +++ b/windows-driver-docs-pr/kernel/extended-example--defining-a--64bit--field.md @@ -0,0 +1,221 @@ +--- +title: Extended Example Defining a "64Bit" Field +author: windows-driver-content +description: Shows how to modify a 32-bit driver for 64-bit by adding a "64Bit" field to the IOCTL control code. +ms.assetid: 642b67eb-880c-4057-b5de-c89ef8e8601e +keywords: ["32-bit I/O support WDK 64-bit , 64Bit field defined", "64Bit field defined WDK kernel", "bitfields WDK 64-bit", "separate control codes WDK 64-bit", "control codes WDK 64-bit", "file system control codes WDK 64-bit", "FSCTL WDK 64-bit", "I/O control codes WDK kernel , 32-bit I/O in 64-bit drivers", "IOCTLs WDK kernel , 32-bit I/O in 64-bit drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extended Example: Defining a "64Bit" Field + + +## + + +The following example shows how to modify a 32-bit driver for 64-bit by adding a "64Bit" field to the IOCTL control code. Note that this example shows only the portions of the driver code that need to be modified. + +### Original Driver Code + +The following is the 32-bit version of the driver: + +### Header File + +``` +#define REGISTER_FUNCTION 0 // Define the IOCTL function code + +#define IOCTL_REGISTER CTL_CODE(FILE_DEVICE_UNKNOWN, \ + REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) + +typedef struct _IOCTL_PARAMETERS { + PVOID Addr; + SIZE_T Length; + HANDLE Handle; +} IOCTL_PARAMETERS, *PIOCTL_PARAMETERS; +``` + +### DeviceControl Dispatch Routine + +``` +NTSTATUS +TestdrvDeviceControl( + IN PDEVICE_OBJECT DeviceObject, + IN PIRP Irp + ) +{ + PIO_STACK_LOCATION irpSp; + NTSTATUS status; + PIOCTL_PARAMETERS params; + IOCTL_PARAMETERS LocalParam; + PIOCTL_PARAMETERS_32 params32; + + // + // Get a pointer to the current parameters for this request. The + // information is contained in the current stack location. + // + irpSp = IoGetCurrentIrpStackLocation(Irp); + // + // Case on the device control code + // + switch (irpSp->Parameters.DeviceIoControl.IoControlCode) { + case IOCTL_REGISTER: + params = (PIOCTL_PARAMETERS) + (Irp->AssociatedIrp.SystemBuffer); + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < + sizeof(IOCTL_PARAMETERS)) { + status = STATUS_INVALID_PARAMETER; + } else { + RtlCopyMemory(&LocalParam, params, + sizeof(IOCTL_PARAMETERS)); + /* Handle the ioctl here */ + status = STATUS_SUCCESS; + } + Irp->IoStatus.Information = 0; + break; + // + // Unrecognized device control request + // + default: + Irp->IoStatus.Information = 0; + status = STATUS_INVALID_PARAMETER; + break; + } + // + // If status is pending, mark the IRP pending and start the + // request in a cancelable state. Otherwise, complete the IRP. + // + Irp->IoStatus.Status = status; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + return(status); +} +``` + +### Driver Code With Thunking Support + +The following is the 64-bit version of the driver: + +### Header File + +``` +#define REGISTER_FUNCTION 0 // Define the IOCTL function code + +#ifdef _WIN64 +#define CLIENT_64BIT 0x800 +#define REGISTER_FUNCTION 0 +#define IOCTL_REGISTER CTL_CODE(FILE_DEVICE_UNKNOWN, \ + CLIENT_64BIT|REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) +#else +#define IOCTL_REGISTER CTL_CODE(FILE_DEVICE_UNKNOWN, \ + REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) +#endif + +typedef struct _IOCTL_PARAMETERS { + PVOID Addr; + SIZE_T Length; + HANDLE Handle; +} IOCTL_PARAMETERS, *PIOCTL_PARAMETERS; +``` + +### DeviceControl Dispatch Routine + +``` +#ifdef _WIN64 +#define IOCTL_REGISTER_32 CTL_CODE(FILE_DEVICE_UNKNOWN, \ + REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) + #endif + +... + +#ifdef _WIN64 +typedef struct _IOCTL_PARAMETERS_32 { + VOID*POINTER_32 Addr; + INT32 Length; + VOID*POINTER_32 Handle; +} IOCTL_PARAMETERS_32, *PIOCTL_PARAMETERS_32; + #endif + +... + +NTSTATUS +TestdrvDeviceControl( + IN PDEVICE_OBJECT DeviceObject, + IN PIRP Irp + ) +{ + PIO_STACK_LOCATION irpSp; + NTSTATUS status; + PIOCTL_PARAMETERS params; + IOCTL_PARAMETERS LocalParam; + PIOCTL_PARAMETERS_32 params32; + + // + // Get a pointer to the current parameters for this request. The + // information is contained in the current stack location. + // + irpSp = IoGetCurrentIrpStackLocation(Irp); + // + // Case on the device control code + // + switch (irpSp->Parameters.DeviceIoControl.IoControlCode) { +#ifdef _WIN64 + case IOCTL_REGISTER_32: + params32 = (PIOCTL_PARAMETERS_32) + (Irp->AssociatedIrp.SystemBuffer); + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < + sizeof(IOCTL_PARAMETERS_32)) { + status = STATUS_INVALID_PARAMETER; + } else { + LocalParam.Addr = params32->Addr; + LocalParam.Handle = params32->Handle; + LocalParam.Length = params32->Length; + /* Handle the ioctl here */ + status = STATUS_SUCCESS; + Irp->IoStatus.Information = 0; + } + break; + #endif + case IOCTL_REGISTER: + params = (PIOCTL_PARAMETERS) + (Irp->AssociatedIrp.SystemBuffer); + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < + sizeof(IOCTL_PARAMETERS)) { + status = STATUS_INVALID_PARAMETER; + } else { + RtlCopyMemory(&LocalParam, params, + sizeof(IOCTL_PARAMETERS)); + /* Handle the ioctl here */ + status = STATUS_SUCCESS; + } + Irp->IoStatus.Information = 0; + break; + // + // Unrecognized device control request + // + default: + Irp->IoStatus.Information = 0; + status = STATUS_INVALID_PARAMETER; + break; + } + // + // If status is pending, mark the IRP pending and start the + // request in a cancelable state. Otherwise, complete the IRP. + // + Irp->IoStatus.Status = status; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + return(status); +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Extended%20Example:%20Defining%20a%20%2264Bit%22%20Field%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/extended-example--using-iois32bitprocess.md b/windows-driver-docs-pr/kernel/extended-example--using-iois32bitprocess.md new file mode 100644 index 0000000000..f50236e818 --- /dev/null +++ b/windows-driver-docs-pr/kernel/extended-example--using-iois32bitprocess.md @@ -0,0 +1,141 @@ +--- +title: Extended Example Using IoIs32bitProcess +author: windows-driver-content +description: Extended Example Using IoIs32bitProcess +ms.assetid: bb73d16c-9f9f-41ff-ac0b-8af31c6f55f4 +keywords: ["32-bit I/O support WDK 64-bit , IoIs32bitProcess", "IoIs32bitProcess"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extended Example: Using IoIs32bitProcess + + +## + + +The following example shows how to modify a 32-bit driver for 64-bit by adding a call to [**IoIs32bitProcess**](https://msdn.microsoft.com/library/windows/hardware/ff549372). Note that this example shows only the portions of the driver code that need to be modified. + +### Original Driver Code + +``` +typedef struct _TESTDRV_EVENT_BUFFER { + HANDLE Handle; + ULONG Key; +} TESTDRV_EVENT_BUFFER, *PTESTDRV_EVENT_BUFFER; + +NTSTATUS +TestdrvFsControl ( + IN PTESTDRV_DEVICE_OBJECT TestdrvDeviceObject, + IN PIRP Irp + ) +{ + + ... + + InputBufferLength = + IrpSp->Parameters.FileSystemControl.InputBufferLength; + + + if (InputBufferLength < sizeof(TESTDRV_EVENT_BUFFER)) { + + DebugTrace(0, Dbg, "System buffer size is too small\n", 0); + + FsRtlCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return STATUS_INVALID_PARAMETER; + } + + Buffer = Irp->AssociatedIrp.SystemBuffer; + + // start using the event buffer + + ... + +} +``` + +### Driver Code With Thunking Support + +``` +typedef struct _TESTDRV_EVENT_BUFFER { + HANDLE Handle; + ULONG Key; +} TESTDRV_EVENT_BUFFER, *PTESTDRV_EVENT_BUFFER; + +// +// Define a 32-bit thunking structure +// + + #if defined(_WIN64) +typedef struct _TESTDRV_EVENT_BUFFER32 { + UINT32 Handle; + ULONG Key; +} TESTDRV_EVENT_BUFFER32, *PTESTDRV_EVENT_BUFFER32; +#endif + +// +// Intercept the input buffer as a 32-bit structure and thunk it to + // 64-bit +NTSTATUS +TestdrvFsControl ( + IN PTESTDRV_DEVICE_OBJECT TestdrvDeviceObject, + IN PIRP Irp + ) +{ + TESTDRV_EVENT_BUFFER LocalBuffer; + + ... + + InputBufferLength = + IrpSp->Parameters.FileSystemControl.InputBufferLength; + +#if defined(_WIN64) + if (IoIs32bitProcess(Irp)) { + PTESTDRV_EVENT_BUFFER32 Buffer32; + + if (InputBufferLength < sizeof(TESTDRV_EVENT_BUFFER32)) { + DebugTrace(0, Dbg, "Irp32 : System buffer size is too + small\n", 0); + + FsRtlCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return STATUS_INVALID_PARAMETER; + } + Buffer = &LocalBuffer; + Buffer32 = Irp->AssociatedIrp.SystemBuffer; + Buffer->Handle = (HANDLE)Buffer32->Handle; + Buffer->Key = Buffer32->Key; + } + else { +#endif + if (InputBufferLength < sizeof(TESTDRV_EVENT_BUFFER)) { + + DebugTrace(0, Dbg, "System buffer size is too small\n", 0); + + FsRtlCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return STATUS_INVALID_PARAMETER; + } + + Buffer = Irp->AssociatedIrp.SystemBuffer; +#if defined(_WIN64) + } +#endif + + // start using the Event Buffer + + ... + +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Extended%20Example:%20Using%20IoIs32bitProcess%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/exxxxtimer-routines-and-ex-timer-objects.md b/windows-driver-docs-pr/kernel/exxxxtimer-routines-and-ex-timer-objects.md new file mode 100644 index 0000000000..c66b3d4a2b --- /dev/null +++ b/windows-driver-docs-pr/kernel/exxxxtimer-routines-and-ex-timer-objects.md @@ -0,0 +1,49 @@ +--- +title: ExXxxTimer Routines and EX_TIMER Objects +author: windows-driver-content +description: Starting with Windows 8.1, a comprehensive set of ExXxxTimer routines is available to manage timers. +ms.assetid: 5F2622F5-4D1A-48F4-9FF5-27DEC6109266 +keywords: ["timers WDK kernel", "timer objects WDK kernel", "timer objects WDK kernel , about timer objects", "kernel dispatcher objects WDK , timer objects", "dispatcher objects WDK kernel , timer objects", "high-resolution timers WDK kernel", "no-wake timers WDK kernel", "EX_TIMER", "ExXxxTimer routines", "ExAllocateTimer", "ExDeleteTimer", "ExSetTimer", "ExCancelTimer", "ExTimerCallback"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# ExXxxTimer Routines and EX\_TIMER Objects + + +Starting with Windows 8.1, a comprehensive set of **Ex*Xxx*Timer** routines is available to manage timers. These routines use timer objects that are based on the [**EX\_TIMER**](https://msdn.microsoft.com/library/windows/hardware/dn265199) structure. The **Ex*Xxx*Timer** routines are replacements for the **Ke*Xxx*Timer** routines, which are available starting with Windows 2000. Drivers intended to run only on Windows 8.1 and later versions of Windows can use the **Ex*Xxx*Timer** routines instead of the **Ke*Xxx*Timer** routines. Windows 8.1 and later versions of Windows continue to support the **Ke*Xxx*Timer** routines. + +The **Ex*Xxx*Timer** routines have all the important capabilities that are provided by the **Ke*Xxx*Timer** routines. In addition, the **Ex*Xxx*Timer** routines support two timer types, *high-resolution timers* and *no-wake timers*, that are not supported by the **Ke*Xxx*Timer** routines. High-resolution timers are timers whose expiration times can be specified with higher accuracy than those of timers whose accuracy is limited by the default resolution of the system clock. No-wake timers are timers that avoid unnecessarily waking processors from low-power states. For more information, see the following topics: + +[High-Resolution Timers](high-resolution-timers.md) +[No-Wake Timers](no-wake-timers.md) +Starting with Windows 8.1, the following **Ex*Xxx*Timer** routines are available: + +[**ExAllocateTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265179) +[**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) +[**ExCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265180) +[**ExDeleteTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265181) +The **ExSetTimer** routine can be used instead of the [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) or [**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292) routine. The **ExCancelTimer** routine can be used instead of the [**KeCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/ff551970) routine. + +The **ExAllocateTimer** and **ExDeleteTimer** routines have no direct **Ke*Xxx*Timer** counterparts. These two routines allocate and free a timer object. This timer object is a system-allocated [**EX\_TIMER**](https://msdn.microsoft.com/library/windows/hardware/dn265199) structure whose members are opaque to drivers. In contrast, the timer object used by the **Ke*Xxx*Timer** routines is a driver-allocated [**KTIMER**](https://msdn.microsoft.com/library/windows/hardware/ff554250) structure. The driver calls the [**KeInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff552168) or [**KeInitializeTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff552173) routine to initialize this object. **ExAllocateTimer** initializes the timer objects that it allocates. For more information about **ExDeleteTimer**, see [Deleting a System-Allocated Timer Object](deleting-a-system-allocated-timer-object.md). + +**EX\_TIMER** and **KTIMER** structures are waitable objects. After a driver calls **ExSetTimer**, **KeSetTimer**, or **KeSetTimerEx** to set a timer, the driver can call a routine such as [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324) to wait for the timer to expire. The timer object is signaled when the timer expires. As an option, a driver can supply a pointer to a driver-implemented [*ExTimerCallback*](https://msdn.microsoft.com/library/windows/hardware/dn265190) or [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) callback routine that the operating system calls after the timer expires. + +The **Ke*Xxx*Timer** routines have two capabilities that are not provided by the **Ex*Xxx*Timer** routines, but these capabilities are not needed by most drivers. + +First, the **KTIMER** structure used as a timer object by the **Ke*Xxx*Timer** routines is driver-allocated. The driver can preallocate this object to ensure that the object is available even in circumstances in which resources are constrained and memory allocations can fail. In contrast, a call to **ExAllocateTimer** to allocate a timer object might fail in a resource-constrained environment. However, few drivers need to be designed to operate in environments in which memory allocations fail, and most drivers benefit from the convenience of an **ExAllocateTimer** routine that both allocates and initializes a timer object. + +Second, there is no **Ex*Xxx*Timer** equivalent of the [**KeReadStateTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553099) routine, which indicates whether a timer object is in the signaled state. However, this routine is rarely used. If necessary, a driver that uses the **Ex*Xxx*Timer** routines can check whether a timer object is in the signaled state by reading a Boolean value that is set by the *ExTimerCallback* callback routine that the driver supplies to the **ExAllocateTimer** routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20ExXxxTimer%20Routines%20and%20EX_TIMER%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failing-a-system-query-power-irp-in-a-filter-or-function-driver.md b/windows-driver-docs-pr/kernel/failing-a-system-query-power-irp-in-a-filter-or-function-driver.md new file mode 100644 index 0000000000..8de26083c9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/failing-a-system-query-power-irp-in-a-filter-or-function-driver.md @@ -0,0 +1,44 @@ +--- +title: Failing a System Query-Power IRP in a Filter or Function Driver +author: windows-driver-content +description: Failing a System Query-Power IRP in a Filter or Function Driver +ms.assetid: 7c4ceb8e-94f4-4ff7-9d45-1094e9a861fd +keywords: ["query-power IRPs WDK power management", "filter drivers WDK power management", "function drivers WDK power management", "failing query-power IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failing a System Query-Power IRP in a Filter or Function Driver + + +## + + +A filter or function driver (that is not the power policy owner for a device) can fail an [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) request if either of the following is true: + +- The device is enabled for wake-up and the requested system power state is less powered than the value of [**SystemWake**](systemwake.md), which specifies the least-powered state from which the device can wake the system. For example, a device that can wake the system from S2 but not from S3 would fail a query for S3 but succeed a query for S2. + +- Entering a device power state that corresponds to the requested state would force the driver to abandon an operation that would lose data, such as an open modem connection. A driver rarely will fail a query for this reason; under most circumstances, the application handles such cases. + +To fail an **IRP\_MN\_QUERY\_POWER** request for a system power state, a driver should take the following steps: + +1. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to indicate that the driver is prepared to handle the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only) + +2. Set **Irp->IoStatus.Status** to a failure status and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), specifying IO\_NO\_INCREMENT. Do not pass the IRP further down the device stack. + +3. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to release the previously acquired lock. + +4. Return a failure status from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failing%20a%20System%20Query-Power%20IRP%20in%20a%20Filter%20or%20Function%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-check-a-driver-s-state.md b/windows-driver-docs-pr/kernel/failure-to-check-a-driver-s-state.md new file mode 100644 index 0000000000..8a45ae9d34 --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-check-a-driver-s-state.md @@ -0,0 +1,43 @@ +--- +title: Failure to Check a Driver's State +author: windows-driver-content +description: Failure to Check a Driver's State +ms.assetid: 963f79f6-2282-41bd-9cf4-bd5bc02a510e +keywords: ["reliability WDK kernel , driver state checking", "checking driver states", "driver state checking", "verifying driver states", "correct device states WDK kernel", "device states WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Check a Driver's State + + +## + + +In the following example, the driver uses the **ASSERT** macro to check for the correct device state in the checked build, but does not check device state in the free build: + +``` + case IOCTL_WAIT_FOR_EVENT: + + ASSERT((!Extension->WaitEventIrp)); + Extension->WaitEventIrp = Irp; + IoMarkIrpPending(Irp); + status = STATUS_PENDING; +``` + +In the checked build, if the driver already holds the IRP pending, the system will assert. In the free build, however, the driver does not check for this error. Two calls to the same IOCTL cause the driver to lose track of an IRP. + +On a multiprocessor system, this code fragment might cause additional problems. Assume that on entry this routine has ownership of (the right to manipulate) this IRP. When the routine saves the **Irp** pointer in the global structure at **Extension->WaitEventIrp**, another thread can get the IRP address from that global structure and perform operations on the IRP. To prevent this problem, the driver should mark the IRP pending before it saves the IRP and should include both the call to [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) and the assignment in an interlocked sequence. A [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for the IRP might also be necessary. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Check%20a%20Driver's%20State%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-check-the-size-of-buffers.md b/windows-driver-docs-pr/kernel/failure-to-check-the-size-of-buffers.md new file mode 100644 index 0000000000..8a48e61ab8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-check-the-size-of-buffers.md @@ -0,0 +1,85 @@ +--- +title: Failure to Check the Size of Buffers +author: windows-driver-content +description: Failure to Check the Size of Buffers +ms.assetid: e9d9a5d9-19a5-4a1d-95f9-df2021c51c41 +keywords: ["buffer size WDK kernel", "input buffers WDK kernel", "output buffers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Check the Size of Buffers + + +## + + +When handling IOCTLs and FSCTLs that implement buffered I/O, a driver should always check the sizes of the input and output buffers to ensure that the buffers can hold all the requested data. If the request specifies FILE\_ANY\_ACCESS, as most driver IOCTLs and FSCTLs do, any caller that has a handle to the device has access to buffered IOCTL or FSCTL requests for that device, and could read or write data beyond the end of the buffer. + +### Input Buffer Size + +For example, assume that the following code appears in a routine that is called from a *Dispatch* routine, and that the driver has not validated the buffer sizes passed in the IRP: + +``` + switch (ControlCode) + ... + ... + case IOCTL_NEW_ADDRESS:{ + tNEW_ADDRESS *pNewAddress = + pIrp->AssociatedIrp.SystemBuffer; + + pDeviceContext->Addr = RtlUlongByteSwap (pNewAddress->Address); +``` + +The example does not check the buffer sizes before the assignment statement (highlighted). As a result, the **pNewAddress->Address** reference in the next line can fault if the input buffer is not big enough to contain a tNEW\_ADDRESS structure. + +The following code checks the buffer sizes, avoiding the potential problem: + +``` + case IOCTL_NEW_ADDRESS: { + tNEW_ADDRESS *pNewAddress = + pIrp->AssociatedIrp.SystemBuffer; + + if (pIrpSp->Parameters.DeviceIoControl.InputBufferLength >= + sizeof(tNEW_ADDRESS)) { + pDeviceContext->Addr = RtlUlongByteSwap (pNewAddress->Address); +``` + +Code to handle other buffered I/O, such as WMI requests that use variable size buffers, can have similar errors. + +### Output Buffer Size + +Output buffer problems are similar to input buffer problems. They can easily corrupt pool, and user-mode callers may be unaware that any error has occurred. + +In the following example, the driver fails to check the size of the **SystemBuffer**: + +``` + case IOCTL_GET_INFO: { + + Info = Irp->AssociatedIrp.SystemBuffer; + + Info->NumIF = NumIF; + ... + ... + Irp->IoStatus.Information = + NumIF*sizeof(GET_INFO_ITEM)+sizeof(ULONG); + Irp->IoStatus.Status = ntStatus; + } +``` + +Assuming that the **NumIF** field of the system buffer specifies the number of input items, this example can set **IoStatus.Information** to a value larger than the output buffer and thus return too much information to the user-mode code. If an application is improperly coded, and calls with too small an output buffer, the preceding code could corrupt the pool by writing beyond the end of the system buffer. + +Remember that the I/O manager assumes that the value in the **Information** field is valid. If a caller passes in a valid kernel-mode address for the output buffer and a size of zero bytes, serious problems can occur if the driver does not check the output buffer size and thus find the error. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Check%20the%20Size%20of%20Buffers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-initialize-output-buffers.md b/windows-driver-docs-pr/kernel/failure-to-initialize-output-buffers.md new file mode 100644 index 0000000000..f629956db2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-initialize-output-buffers.md @@ -0,0 +1,64 @@ +--- +title: Failure to Initialize Output Buffers +author: windows-driver-content +description: Failure to Initialize Output Buffers +ms.assetid: 8c038a94-8506-44e3-ac7f-82b58d791124 +keywords: ["output buffers WDK kernel", "initializing output buffers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Initialize Output Buffers + + +## + + +Drivers should initialize all output buffers with zeros before returning them to the caller. Failing to initialize a buffer can result in garbage data in any uninitialized bytes. + +In the following example, a driver returns garbage in unused bytes. + +``` + case IOCTL_GET_NAME: { + ... + ... + outputBufferLength = + ioStack->Parameters.DeviceIoControl.OutputBufferLength; + outputBuffer = (PGET_NAME) Irp->AssociatedIrp.SystemBuffer; + + if (outputBufferLength >= sizeof(GET_NAME)) { + length = outputBufferLength - sizeof(GET_NAME); + + ntStatus = IoGetDeviceProperty( + DeviceExtension->PhysicalDeviceObject, + DevicePropertyDriverKeyName, + length, + outputBuffer->DriverKeyName, + &length); + + outputBuffer->ActualLength = + length + sizeof(GET_NAME); + + Irp->IoStatus.Information = outputBufferLength; + + } else { + ntStatus = STATUS_BUFFER_TOO_SMALL; + } +``` + +Setting **IoStatus.Information** to the output buffer size causes the whole output buffer to be returned to the caller. The I/O manager does not initialize the data beyond the size of the input buffer—the input and output buffers overlap for a buffered request. Because the system support routine [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) does not write the entire buffer, this IOCTL returns uninitialized data to the caller. + +Some drivers use the **Information** field to return codes that provide extra details about I/O requests. Before doing so, such drivers should check the IRP flags to ensure that IRP\_INPUT\_OPERATION is not set. When this flag is not set, the IOCTL or FSCTL does not have an output buffer, so the **Information** field need not supply a buffer size. In this case. the driver can safely use the **Information** field to return its own code. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Initialize%20Output%20Buffers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-validate-device-objects.md b/windows-driver-docs-pr/kernel/failure-to-validate-device-objects.md new file mode 100644 index 0000000000..87ec332f27 --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-validate-device-objects.md @@ -0,0 +1,34 @@ +--- +title: Failure to Validate Device Objects +author: windows-driver-content +description: Failure to Validate Device Objects +ms.assetid: aa4abc20-0b87-44d7-8987-a5b2be397bb1 +keywords: ["reliability WDK kernel , device object validations", "device objects WDK kernel , validation failures", "validation failures WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Validate Device Objects + + +## + + +Many drivers create more than one kind of device object by calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397). Some drivers create control device objects in their **DriverEntry** routines to allow applications to communicate with the driver, even before the driver creates an FDO. For example, file system drivers create device objects to handle file system notifications when they register themselves as file systems with **IoRegisterFileSystem**. + +A driver should be ready for [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) requests for any device object it creates. After completing the request with a success status, the driver should expect to receive any user-accessible I/O requests on the created file object. Consequently, any driver that creates more than one device object must check which device object each I/O request specifies. + +For example, suppose a driver creates overall control device objects in [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113), and then creates another set of device objects in its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. Suppose the *AddDevice* routine initializes the device extension with information about lower-level drivers, but the control device objects do not contain this information. In this case, all dispatch routines must be careful to check each device object that they receive. Otherwise, the driver might crash when trying to use device extension information. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Validate%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-validate-object-handles.md b/windows-driver-docs-pr/kernel/failure-to-validate-object-handles.md new file mode 100644 index 0000000000..9bebf3fafb --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-validate-object-handles.md @@ -0,0 +1,85 @@ +--- +title: Failure to Validate Object Handles +author: windows-driver-content +description: Failure to Validate Object Handles +ms.assetid: 67d52ca8-4e86-4fe2-a541-f7a0e4040b93 +keywords: ["reliability WDK kernel , object handle validation", "validation failures WDK kernel", "object handles WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Validate Object Handles + + +## + + +Some drivers must manipulate objects passed to them by callers or must handle two file objects at the same time. For example, a modem driver might receive a handle to an event object, or a network driver might receive handles to two different file objects. The driver must validate these handles. Because they are passed by a caller, and not through the I/O manager, the I/O manager cannot perform any validation checks. + +For example, in the following code snippet, the driver has been passed the handle **AscInfo->AddressHandle**, but has not validated it before calling [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679): + +``` + // + // This handle is embedded in a buffered request. + // + status = ObReferenceObjectByHandle( + AscInfo->AddressHandle, + 0, + NULL, + KernelMode, + &fileObject, + NULL); + + if (NT_SUCCESS(status)) { + if ( (fileObject->DeviceObject == DeviceObject) && + (fileObject->FsContext2 == TRANSPORT_SOCK) ) { +``` + +Although the call to **ObReferenceObjectByHandle** succeeds, the code fails to ensure that the returned pointer references a file object; it trusts the caller to pass in the correct information. + +Even if all the parameters for the call to **ObReferenceObjectByHandle** are correct, and the call succeeds, a driver can still get unexpected results if the file object is not intended for its driver. In the following code fragment, the driver assumes that a successful call returns a pointer to the file object it expected: + +``` + status = ObReferenceObjectByHandle ( + AcpInfo->Handle, + 0L, + DesiredAccess, + *IoFileObjectType, + Irp->RequestorMode, + (PVOID *)&AcpEndpointFileObject, + NULL); + + if ( !NT_SUCCESS(status) ) { + goto complete; + } + AcpEndpoint = AcpEndpointFileObject->FsContext; + + if ( AcpEndpoint->Type != BlockTypeEndpoint ) +``` + +Although **ObReferenceObjectByHandle** returns a pointer to a file object, the driver has no guarantee that the pointer references the file object it expected. In this case, the driver should validate the pointer before accessing the driver-specific data at **AcpEndpointFileObject->FsContext**. + +To avoid such problems, a driver should check for valid data, as follows: + +- Check the object type to make sure it is what the driver expects. + +- Ensure that the requested access is appropriate for the object type and required tasks. If your driver performs a fast file copy, for instance, make sure the handle has read access. + +- Be sure to specify the correct access mode (**UserMode** or **KernelMode**) and that the access mode is compatible with the access requested. + +- If the driver expects a handle to a file object that the driver itself created, validate the handle against the device object or driver. However, be careful not to break filters that send I/O requests for strange devices. + +- If your driver supports multiple kinds of file objects (such as the control channels, address objects, and connections of TDI drivers or Volume, Directory, and File objects of file systems), make sure you have a way to differentiate them. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Validate%20Object%20Handles%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/failure-to-validate-variable-length-buffers.md b/windows-driver-docs-pr/kernel/failure-to-validate-variable-length-buffers.md new file mode 100644 index 0000000000..942c68a77e --- /dev/null +++ b/windows-driver-docs-pr/kernel/failure-to-validate-variable-length-buffers.md @@ -0,0 +1,94 @@ +--- +title: Failure to Validate Variable-Length Buffers +author: windows-driver-content +description: Failure to Validate Variable-Length Buffers +ms.assetid: 0cc4be22-8197-421a-a5a6-2e7b89a79a38 +keywords: ["input buffers WDK kernel", "variable-length input buffers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Failure to Validate Variable-Length Buffers + + +## + + +Drivers often accept input buffers with fixed headers and trailing variable length data, as in the following example: + +``` + typedef struct _WAIT_FOR_BUFFER { + LARGE_INTEGER Timeout; + ULONG NameLength; + BOOLEAN TimeoutSpecified; + WCHAR Name[1]; + } WAIT_FOR_BUFFER, *PWAIT_FOR_BUFFER; + + if (InputBufferLength < sizeof(WAIT_FOR_BUFFER)) { + IoCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return( STATUS_INVALID_PARAMETER ); + } + + WaitBuffer = Irp->AssociatedIrp.SystemBuffer; + + if (FIELD_OFFSET(WAIT_FOR_BUFFER, Name[0]) + + WaitBuffer->NameLength > InputBufferLength) { + IoCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return( STATUS_INVALID_PARAMETER ); + } +``` + +If **WaitBuffer->NameLength** is a very large ULONG value, adding it to the offset could cause an integer overflow. Instead, a driver should subtract the offset from the **InputBufferLength**, and compare the result with **WaitBuffer->NameLength**, as in the following example: + +``` + if (InputBufferLength < sizeof(WAIT_FOR_BUFFER)) { + IoCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + Return( STATUS_INVALID_PARAMETER ); + } + + WaitBuffer = Irp->AssociatedIrp.SystemBuffer; + + if ((InputBufferLength - + FIELD_OFFSET(WAIT_FOR_BUFFER, Name[0]) > + WaitBuffer->NameLength) { + IoCompleteRequest( Irp, STATUS_INVALID_PARAMETER ); + return( STATUS_INVALID_PARAMETER ); + } +``` + +The subtraction above cannot underflow because the first **if** statement ensures that the **InputBufferLength** is greater than or equal to the size of **WAIT\_FOR\_BUFFER**. + +The following shows a more complicated overflow problem: + +``` + case IOCTL_SET_VALUE: + dwSize = sizeof(SET_VALUE); + + if (inputBufferLength < dwSize) { + ntStatus = STATUS_BUFFER_TOO_SMALL; + break; + } + + dwSize = FIELD_OFFSET(SET_VALUE, pInfo[0]) + + pSetValue->NumEntries * sizeof(SET_VALUE_INFO); + + if (inputBufferLength < dwSize) { + ntStatus = STATUS_BUFFER_TOO_SMALL; + break; + } +``` + +In this example, an integer overflow can occur during multiplication. If the size of the **SET\_VALUE\_INFO** structure is a multiple of 2, a **NumEntries** value such as 0x80000000 results in an overflow, when the bits are shifted left during multiplication. However, the buffer size will nevertheless pass the validation test, because the overflow causes **dwSize** to appear quite small. To avoid this problem, subtract the lengths as in the previous example, divide by **sizeof**(**SET\_VALUE\_INFO**), and compare the result with **NumEntries**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Failure%20to%20Validate%20Variable-Length%20Buffers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/fast-mutexes-and-guarded-mutexes.md b/windows-driver-docs-pr/kernel/fast-mutexes-and-guarded-mutexes.md new file mode 100644 index 0000000000..d770b8075f --- /dev/null +++ b/windows-driver-docs-pr/kernel/fast-mutexes-and-guarded-mutexes.md @@ -0,0 +1,75 @@ +--- +title: Fast Mutexes and Guarded Mutexes +author: windows-driver-content +description: Fast Mutexes and Guarded Mutexes +ms.assetid: 8c8014bf-6b81-4039-ae93-d4cedd6d6fed +keywords: ["synchronization WDK kernel , fast mutexes", "synchronization WDK kernel , guarded mutexes", "guarded mutexes WDK kernel", "fast mutexes WDK kernel", "mutexes WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Fast Mutexes and Guarded Mutexes + + +Starting with Windows 2000, drivers can use *fast mutexes* if they require a low-overhead form of mutual exclusion for code that runs at IRQL <= APC\_LEVEL. A fast mutex can protect a code path that must be entered by only one thread at a time. To enter the protected code path, the thread *acquires* the mutex. If another thread has already acquired the mutex, execution of the current thread is suspended until the mutex is released. To exit the protected code path, the thread *releases* the mutex. + +Starting with Windows Server 2003, drivers can also use *guarded mutexes*. Guarded mutexes are drop-in replacements for fast mutexes but provide better performance. Like a fast mutex, a guarded mutex can protect a code path that must be entered by only one thread at a time. However, code that uses guarded mutexes runs more quickly than code that uses fast mutexes. + +In versions of Windows before Windows 8, guarded mutexes are implemented differently from fast mutexes. A code path that is protected by a fast mutex runs at IRQL = APC\_LEVEL. A code path that is protected by a guarded mutex runs at IRQL <= APC\_LEVEL but with all APCs disabled. In these earlier versions of Windows, acquisition of a guarded mutex is a faster operation than acquisition of a fast mutex. However, these two types of mutex behave identically and are subject to the same restrictions. In particular, kernel routines that are illegal to call at IRQL = APC\_LEVEL should not be called from a code path that is protected by either a fast mutex or a guarded mutex. + +Starting with Windows 8, guarded mutexes are implemented as fast mutexes. In a code path that is protected by a guarded mutex or a fast mutex, [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) treats calls to kernel routines as occurring at IRQL = APC\_LEVEL. As in earlier versions of Windows, calls that are illegal at APC\_LEVEL are illegal in a code path that is protected by a guarded mutex or a fast mutex. + +### Fast Mutexes + +A fast mutex is represented by a [**FAST\_MUTEX**](https://msdn.microsoft.com/library/windows/hardware/ff545715) structure. The driver allocates its own storage for a **FAST\_MUTEX** structure and then calls the [**ExInitializeFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff545293) routine to initialize the structure. + +A thread acquires a fast mutex by doing one of the following: + +- Calling the [**ExAcquireFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff544337) routine. If the mutex has already been acquired by another thread, execution of the calling thread is suspended until the mutex becomes available. + +- Calling the [**ExTryToAcquireFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff545647) routine to try to acquire the fast mutex without suspending the current thread. The routine returns immediately, regardless of whether the mutex has been acquired. **ExTryToAcquireFastMutex** returns **TRUE** if it successfully acquired the mutex for the caller; otherwise, it returns **FALSE**. + +A thread calls [**ExReleaseFastMutex**](https://msdn.microsoft.com/library/windows/hardware/ff545549) to release a fast mutex that was acquired by either **ExAcquireFastMutex** or **ExTryToAcquireFastMutex**. + +A code path that is protected by a fast mutex runs at IRQL = APC\_LEVEL. **ExAcquireFastMutex** and **ExTryToAcquireFastMutex** raise the current IRQL to APC\_LEVEL, and **ExReleaseFastMutex** restores the original IRQL. Thus, all APCs are disabled while the thread holds a fast mutex. + +If a code path is guaranteed to always run at APC\_LEVEL, the driver can instead call [**ExAcquireFastMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff544340) and [**ExReleaseFastMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff545567) to acquire and release a fast mutex. These routines do not change the current IRQL and can be used safely only when the current IRQL is APC\_LEVEL. + +Fast mutexes cannot be acquired recursively. If a thread that is already holding a fast mutex tries to acquire it, that thread will deadlock. Fast mutexes can be used only in code that runs at IRQL <= APC\_LEVEL. + +### Guarded Mutexes + +Guarded mutexes, which are available starting with Windows Server 2003, perform the same function as fast mutexes but with higher performance. + +Starting with Windows 8, guarded mutexes and fast mutexes are implemented identically. + +In versions of Windows before Windows 8, guarded mutexes are implemented differently from fast mutexes. Acquiring a fast mutex raises the current IRQL to APC\_LEVEL, while acquiring a guarded mutex enters a guarded region, which is a faster operation. For more information about guarded regions, see [Critical Regions and Guarded Regions](critical-regions-and-guarded-regions.md). + +A guarded mutex is represented by a [**KGUARDED\_MUTEX**](https://msdn.microsoft.com/library/windows/hardware/ff554235) structure. The driver allocates its own storage for a **KGUARDED\_MUTEX** structure and then calls the [**KeInitializeGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff552144) routine to initialize the structure. + +A thread acquires a guarded mutex by doing one of the following: + +- Calling [**KeAcquireGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff551892). If the mutex has already been acquired by another thread, execution of the calling thread is suspended until the mutex becomes available. + +- Calling [**KeTryToAcquireGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553307) to try to acquire the guarded mutex without suspending the current thread. The routine returns immediately, regardless of whether the mutex has been acquired. **KeTryToAcquireGuardedMutex** returns **TRUE** if it successfully acquired the mutex for the caller; otherwise, it returns **FALSE**. + +A thread calls [**KeReleaseGuardedMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553124) to release a guarded mutex that was acquired by either **KeAcquireGuardedMutex** or **KeTryToAcquireGuardedMutex**. + +A thread that holds a guarded mutex implicitly runs inside a guarded region. **KeAcquireGuardedMutex** and **KeTryToAcquireGuardedMutex** enter the guarded region, while **KeReleaseGuardedMutex** exits it. All APCs are disabled while the thread holds a guarded mutex. + +If a code path is guaranteed to run with all APCs disabled, the driver can instead use [**KeAcquireGuardedMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff551894) and [**KeReleaseGuardedMutexUnsafe**](https://msdn.microsoft.com/library/windows/hardware/ff553125) to acquire and release the guarded mutex. These routines do not enter or exit a guarded region and can be used only inside an already-existing guarded region or at IRQL = APC\_LEVEL. + +Guarded mutexes cannot be acquired recursively. If a thread that is already holding a guarded mutex tries to acquire it, that thread will deadlock. Guarded mutexes can be used only in code that runs at IRQL <= APC\_LEVEL. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Fast%20Mutexes%20and%20Guarded%20Mutexes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/fast-startup-from-a-low-power-state.md b/windows-driver-docs-pr/kernel/fast-startup-from-a-low-power-state.md new file mode 100644 index 0000000000..a06abac6bf --- /dev/null +++ b/windows-driver-docs-pr/kernel/fast-startup-from-a-low-power-state.md @@ -0,0 +1,57 @@ +--- +title: Fast Startup from a Low-Power State +author: windows-driver-content +description: Fast Startup from a Low-Power State +ms.assetid: 1091571c-2e30-4ad5-b4b9-0f8633e68288 +--- + +# Fast Startup from a Low-Power State + + +To achieve a fast startup from a low-power state, a driver for a leaf-node device should handle an S0 power IRP (that is, an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) IRP for the S0 system power state). Devices that are leaf nodes in the device hierarchy have no child devices. Because a leaf-node device has no dependencies on child devices, the functional driver for the device can reinitialize the device as a background task to avoid causing unnecessary delays to the operating system or to other drivers. In contrast, bus drivers have dependencies that require additional synchronization logic to coordinate power-on sequences with their child devices. + +Use the following steps to achieve fast startup of a leaf-node device from a low-power state: + +1. Set a completion routine for the S0 power IRP. + +2. Send the S0 power IRP down the device stack. + +3. Complete the S0 power IRP immediately instead of waiting until the D0 power IRP is completed. When the completion routine for the S0 power IRP runs, do the following: + + 1. Request a D0 power IRP (that is, an **IRP\_MN\_SET\_POWER** IRP for the D0 device power state). + + 2. Return STATUS\_SUCCESS to the completion routine for the S0 power IRP. + +4. The driver should queue any I/O requests that it receives but defer handling any of these requests until it finishes processing the D0 power IRP. + +5. When the completion routine for the D0 power IRP runs, initialize the device, but limit this routine to what is required to make the device ready to use. + +6. After the previous steps are completed, your driver can begin to handle I/O requests, including any I/O requests that might already be queued. + +**Note**   The preceding steps do not apply to the handling of power IRPs for any power state other than PowerSystemWorking (S0). These steps specifically apply to the handling of power IRPs for transitions from a low-power state to the power-on (S0) state. + +  + +A system startup is complete after all devices have completed their S0 power IRPs. These devices are not required, at the completion of system startup, to have completed their D0 power IRPs or to be fully functioning. The kernel power manager has a limited set of IRP dispatch queues and must use these queues to notify all devices in the system of the return to the S0 state. Drivers that fail to quickly complete their S0 power IRPs prevent drivers for other devices from receiving their S0 power IRPs. Thus, poorly designed drivers impair overall system startup performance by causing driver operations that should be performed concurrently to be performed serially. + +After a driver completes its S0 power IRP, it might receive I/O requests from applications that have opened handles to the device. Drivers must never fail these I/O requests because doing so might cause applications to stop responding and to produce time-out error messages. Instead, drivers must queue I/O requests until the device is ready to process them. + +A bus driver can achieve a fast startup from a low-power state by using a technique similar to that just described for the driver of a leaf-node device. A bus driver must meet an additional requirement, which is to ensure that any requests from child devices to enter the D0 state are marked as pending and are not completed by the bus driver until the bus device has entered the D0 state. + +For example, when the bus driver for a USB hub receives an S0 power IRP, the driver requests a D0 power IRP and completes the S0 power IRP after receiving the requested D0 power IRP. However, after the S0 power IRP is completed, the hub's child devices are likely to start receiving their S0 power IRPs and requesting D0 power IRPs. The bus driver should prevent the child devices from entering D0 until the hub device enters D0. Therefore, the bus driver should mark all D0 power IRPs from child devices as pending and wait to complete these IRPs until the bus driver finishes handling the D0 power IRP for the hub and the hub device is fully initialized. + +For more information about power IRPs, see the following topics: + +[Handling IRP\_MN\_SET\_POWER for System Power States](handling-irp-mn-set-power-for-system-power-states.md) + +[Handling IRP\_MN\_SET\_POWER for Device Power States](handling-irp-mn-set-power-for-device-power-states.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Fast%20Startup%20from%20a%20Low-Power%20State%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/file-backed-and-page-file-backed-sections.md b/windows-driver-docs-pr/kernel/file-backed-and-page-file-backed-sections.md new file mode 100644 index 0000000000..bb315bc420 --- /dev/null +++ b/windows-driver-docs-pr/kernel/file-backed-and-page-file-backed-sections.md @@ -0,0 +1,36 @@ +--- +title: File-Backed and Page-File-Backed Sections +author: windows-driver-content +description: File-Backed and Page-File-Backed Sections +ms.assetid: 5967678a-cbc3-4db0-86d8-14ffc79f610e +keywords: ["file-backed sections WDK kernel", "page-file-backed sections WDK kernel", "backed memory sections WDK kernel", "paged file backups WDK kernel", "temporarily shared data WDK kernel", "permanently shared data WDK kernel", "memory sections WDK kernel", "section objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# File-Backed and Page-File-Backed Sections + + +## + + +All memory sections are supported ("backed") by disk files that can contain, either temporarily or permanently, the data to be shared. When you create a section, you can identify a specific data file to which the section will be backed. Such sections are called *file-backed* sections. If you do not identify a backing file, the section is backed by the system's paging file and the section is called a *page-file-backed* section. The data in file-backed sections can be permanently written to disk. Data in page-file-backed sections is never permanently written to disk. + +A *file-backed* section reflects the contents of an actual file on disk; in other words, it is a memory-mapped file. Any access to memory locations within a given file-backed section corresponds to accesses to locations in the associated file. If a process maps the view as read-only, any data that is read from the view is transparently read from the file. Similarly, if the process maps the view as read/write, any data that is read from the view or written to the view is transparently read from or written to the file. In either case, the view's virtual memory does not use any space in the page files. A file-backed section can also be mapped as copy-on-write. In that case, the view's data is read from the file, but any data written to the view is not written to the file; instead it is discarded after the final view is unmapped and the last handle to the section is closed. + +A page-file-backed section is backed by the page files instead of by any explicit file on the disk. Any changes that are made to a page-file-backed section are automatically discarded after the section object is destroyed. Page-file-backed sections can be used as shared memory segments between two processes. + +Any section, file-backed or not, can be shared between two processes. The same physical memory address range is mapped to a virtual memory address range within each process (though not necessarily to the same virtual address). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20File-Backed%20and%20Page-File-Backed%20Sections%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/filter-drivers.md b/windows-driver-docs-pr/kernel/filter-drivers.md new file mode 100644 index 0000000000..b02d40e04c --- /dev/null +++ b/windows-driver-docs-pr/kernel/filter-drivers.md @@ -0,0 +1,54 @@ +--- +title: Filter Drivers +author: windows-driver-content +description: Filter Drivers +ms.assetid: 4def5503-bb0e-4bae-b048-4c8d25d62020 +keywords: ["filter drivers WDK WDM", "bus filter drivers WDK WDM", "lower-level filter drivers WDK WDM", "upper-level filter drivers WDK WDM", "WDM filter drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Filter Drivers + + +## + + +Filter drivers are optional drivers that add value to or modify the behavior of a device. A filter driver can service one or more devices. + +### Bus Filter Drivers + +*Bus filter drivers* typically add value to a bus and are supplied by Microsoft or a system OEM (see the [Possible Driver Layers](types-of-wdm-drivers.md#possible-driver-layers) figure). Bus filter drivers are optional. There can be any number of bus filter drivers for a bus. + +A bus filter driver could, for example, implement proprietary enhancements to standard bus hardware. + +For devices described by an ACPI BIOS, the power manager inserts a Microsoft-supplied *ACPI filter* (bus filter driver) above the bus driver for each such device. The ACPI filter carries out device power policy and powers on and off devices. The ACPI filter is transparent to other drivers and is not present on non-ACPI machines. + +### Lower-Level Filter Drivers + +*Lower-level filter drivers* typically modify the behavior of device hardware (see the [Possible Driver Layers](types-of-wdm-drivers.md#possible-driver-layers) figure). They are typically supplied by IHVs and are optional. There can be any number of lower-level filter drivers for a device. + +A lower-level *device* filter driver monitors and/or modifies I/O requests to a particular device. Typically, such filters redefine hardware behavior to match expected specifications. + +A lower-level *class* filter driver monitors and/or modifies I/O requests for a class of devices. For example, a lower-level class filter driver for mouse devices could provide acceleration, performing a nonlinear conversion of mouse movement data. + +### Upper-Level Filter Drivers + +*Upper-level filter drivers* typically provide added-value features for a device (see the [Possible Driver Layers](types-of-wdm-drivers.md#possible-driver-layers) figure). Such drivers are usually provided by IHVs and are optional. There can be any number of upper-level filter drivers for a device. + +An upper-level *device* filter driver adds value for a particular device. For example, an upper-level device filter driver for a keyboard could enforce additional security checks. + +An upper-level *class* filter driver adds value for all devices of a particular class. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Filter%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/filtering-registry-calls.md b/windows-driver-docs-pr/kernel/filtering-registry-calls.md new file mode 100644 index 0000000000..fc1e523a09 --- /dev/null +++ b/windows-driver-docs-pr/kernel/filtering-registry-calls.md @@ -0,0 +1,65 @@ +--- +title: Filtering Registry Calls +author: windows-driver-content +description: Filtering Registry Calls +ms.assetid: 6b35c3a0-4ece-4101-b348-e71f5cccf0c8 +keywords: ["filtering registry calls WDK kernel", "registry filtering drivers WDK kernel", "RegistryCallback", "filtering registry calls WDK kernel , about filtering registry calls", "registry filtering drivers WDK kernel , about filtering registry calls"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Filtering Registry Calls + + +A *registry filtering driver* is any kernel-mode driver that filters registry calls, such as the driver component of an antivirus software package. The configuration manager, which implements the registry, allows registry filtering drivers to filter any thread's calls to registry functions. Filtering of registry calls was first supported in Microsoft Windows XP. + +On Windows XP, a registry filtering driver can call [**CmRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541918) to register a [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine and [**CmUnRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541928) to unregister the callback routine. The *RegistryCallback* routine receives notifications of each registry operation before the configuration manager processes the operation. A set of **REG\_*XXX*\_KEY\_INFORMATION** data structures contain information about each registry operation. The *RegistryCallback* routine can block a registry operation. The callback routine also receives notifications when the configuration manager has finished creating or opening a registry key. + +Windows Server 2003 provides additional completion notifications. + +Windows Vista provides the following additional registry filtering capabilities: + +- Registry filtering drivers can be layered in a driver stack, and each driver in the stack can filter a registry operation. + +- The **CmRegisterCallback** routine is replaced by the [**CmRegisterCallbackEx**](https://msdn.microsoft.com/library/windows/hardware/ff541921) routine. + +- Drivers can completely process a registry operation (or redirect the requested operation to a different operation) and prevent the configuration manager from handling the operation. + +- Drivers can assign context information to individual registry operations or key objects. + +- Drivers can modify a registry operation's output parameters and return value. + +- Additional members have been added to all **REG\_*XXX*\_KEY\_INFORMATION** data structures. + +- Drivers receive notifications of additional registry operations. + +For a list of the registry operations that a driver can filter on each version of Windows, see [**REG\_NOTIFY\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff560950). + +To learn more about filtering registry calls, see the following topics: + +[Registering for Notifications](registering-for-notifications.md) + +[Handling Notifications](handling-notifications.md) + +[Supporting Layered Registry Filtering Drivers](supporting-layered-registry-filtering-drivers.md) + +[Specifying Context Information](specifying-context-information.md) + +[Obtaining Additional Registry Information](obtaining-additional-registry-information.md) + +[Invalid Key Object Pointers in Registry Notifications](invalid-key-object-pointers-in-registry-notifications.md) + +[Filtering Registry Operations on Application Hives](filtering-registry-operations-on-application-hives.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Filtering%20Registry%20Calls%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/filtering-registry-operations-on-application-hives.md b/windows-driver-docs-pr/kernel/filtering-registry-operations-on-application-hives.md new file mode 100644 index 0000000000..1806f175e7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/filtering-registry-operations-on-application-hives.md @@ -0,0 +1,31 @@ +--- +title: Filtering Registry Operations on Application Hives +author: windows-driver-content +description: Initial support for application hives was introduced in Windows Vista. +ms.assetid: A8D06E25-7CC6-476A-AB55-DAFE19954347 +--- + +# Filtering Registry Operations on Application Hives + + +Initial support for application hives was introduced in Windows Vista. Starting with Windows 8, improved support for application hives is available, and wider use of application hives is expected. Thus, registry filter drivers developed for these versions of Windows, and particularly for Windows 8 and later, must be aware of registry operations on application hives. These drivers should handle such operations efficiently to avoid negatively impacting the user experience. + +Application hives are registry hives loaded by user-mode applications to store application-specific state data. An application calls the [**RegLoadAppKey**](https://msdn.microsoft.com/library/windows/desktop/ms724886) function to load an application hive. + +In contrast to other types of registry hives, application hives are loaded under the \\REGISTRY\\A registry path name instead of under \\REGISTRY\\MACHINE or \\REGISTRY\\USER. The \\REGISTRY\\A path name is special in that there is no way to traverse this path, and an attempt to open a key under \\REGISTRY\\A will fail with error status STATUS\_ACCESS\_DENIED. The only way an application can access a key in an application hive is to use the handle to the root key of the application hive. The application gets this handle from the **RegLoadAppKey** call that loads the hive. + +An application does not need to explicitly unload an application hive. The operating system automatically unloads the application hive after all of the handles to the hive are closed. + +An application hive does not support setting security descriptors on the keys in the hive. Instead, there is one security descriptor for the entire hive. An attempt to set a security descriptor on a key in an application hive will fail with error status STATUS\_ACCESS\_DENIED. In contrast to other types of registry hives, for which each key is secured with its own security descriptor, the security of an application hive is based on the hive file's security descriptor. Thus, an entity that is successful in loading the hive can modify the entire hive. + +A registry filter driver receives calls to its [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine for registry operations on application hives. These calls do not distinguish between registry operations on application hives and operations on other types of registry hives. Registry filter drivers that handle create-key and open-key operations (which are indicated by the **RegNtPreOpenKey**, **RegNtPreOpenKeyEx**, **RegNtPreCreateKey**, and **RegNtPreCreateKeyEx** notification values) must correctly handle the following special situation. When an application hive is loaded, the last step in the loading process is the opening of the root key of the hive by the registry manager. The registry manager issues this open-key operation with an absolute path to the key, which means that the path name string in the **CompleteName** member of the [**REG\_CREATE\_KEY\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560920), [**REG\_CREATE\_KEY\_INFORMATION\_V1**](https://msdn.microsoft.com/library/windows/hardware/ff560922), [**REG\_OPEN\_KEY\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560957), or [**REG\_OPEN\_KEY\_INFORMATION\_V1**](https://msdn.microsoft.com/library/windows/hardware/ff560959) structure will start with "\\REGISTRY\\A\\". Only the registry manager can use an absolute path to open an application hive. If a registry filter driver tries to open an application hive in this way (for example, by calling the [**ZwOpenKey**](https://msdn.microsoft.com/library/windows/hardware/ff567014) routine), the operation will fail with error status STATUS\_ACCESS\_DENIED. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Filtering%20Registry%20Operations%20on%20Application%20Hives%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/floating-point-support-for-64-bit-drivers.md b/windows-driver-docs-pr/kernel/floating-point-support-for-64-bit-drivers.md new file mode 100644 index 0000000000..2de0c16c6f --- /dev/null +++ b/windows-driver-docs-pr/kernel/floating-point-support-for-64-bit-drivers.md @@ -0,0 +1,139 @@ +--- +title: Using extended processor features in Windows drivers +author: windows-driver-content +description: Windows drivers for x86 and x64 systems that use extended processor features must wrap floating point calculations between calls to KeSaveExtendedProcessorState and KeRestoreExtendedProcessorState in order to avoid errors in concurrent applications that might be using the registers. +ms.assetid: a42e86cf-47a2-44ed-8bf1-7407633af8b7 +keywords: ["floating point WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using extended processor features in Windows drivers + + +**Last updated** + +- July 2016 + +Windows drivers for x86 and x64 systems that use extended processor features must wrap floating point calculations between calls to [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) and [**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182) in order to avoid errors in concurrent applications that might be using the registers. + +## Legacy MMX/x87 Registers + + +These registers correspond to the XSTATE\_MASK\_LEGACY\_FLOATING\_POINT mask and are unavailable to drivers for x64 systems. For more information on these registers see [Using Floating Point in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md). + +## SSE Registers + + +These registers correspond to the XSTATE\_MASK\_LEGACY\_SSE flag and are used by the x64 compiler for floating point operations. Drivers for x86 systems that use these registers must save them before use by passing the XSTATE\_MASK\_LEGACY or XSTATE\_MASK\_LEGACY\_SSE flag in the [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) call and when finished, restore them with [**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182). This is unnecessary on x64 systems, but not harmful. For more information about these registers see [Using Floating Point in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md). + +## AVX Registers + + +These registers correspond to the XSTATE\_MASK\_GSSE or XSTATE\_MASK\_AVX masks. New x86 processors, such as the Intel Sandy Bridge (formerly Gesher) processor, support the AVX instructions and register set (YMM0-YMM15). In Windows 7 with Service Pack 1 (SP1), Windows Server 2008 R2, and newer versions of Windows, both x86 and x64 versions of the operating system preserve the AVX registers across thread (and process) switches. To use the AVX registers in kernel mode, drivers (x86 and x64) must explicitly save and restore the AVX registers. AVX registers cannot be used in an interrupt service routine, and arithmetic exceptions are turned off by default. + +``` +include ksamd64.inc + + subttl "Set YMM State." +;++ +; +; Routine Description: +; +; This routine loads the first four YMM registers with the state supplied. +; +; Arguments; +; +; rcx - Supplies a pointer to the values we want to load. +; +; Return Value: +; +; None +; +;-- + +LEAF_ENTRY SetYmmValues, _TEXT$00 + + vmovdqa ymm0, ymmword ptr[rcx + 0] + vmovdqa ymm1, ymmword ptr[rcx + 32] + vmovdqa ymm2, ymmword ptr[rcx + 64] + vmovdqa ymm3, ymmword ptr[rcx + 96] + + ret + +LEAF_END SetYmmValues, _TEXT$00 + + end +``` + +``` +typedef DECLSPEC_ALIGN(32) struct _YMM_REGISTERS { + ULONG64 Ymm4Registers[16]; +} YMM_REGISTERS, *PYMM_REGISTERS; + +VOID +FASTCALL +SetYmmValues( + __in PYMM_REGISTERS YmmRegisterValues + ); + +NTSTATUS +DriverEntry ( + __in PDRIVER_OBJECT DriverObject, + __in PUNICODE_STRING RegistryPath + ) +{ + + NTSTATUS Status; + XSTATE_SAVE SaveState; + ULONG64 EnabledFeatures; + + // + // Load the first 4 YMM registers as 4 vectors of 4 64-bit integers. + // + + YMM_REGISTERS RegisterValues = { 0, 1, 2, 3, // YMM0 + 4, 5, 6, 7, // YMM1 + 8, 9, 10, 11, // YMM2 + 12, 13, 14, 15 }; // YMM3 + + // + // Check to see if AVX is available. Bail if it is not. + // + + EnabledFeatures = RtlGetEnabledExtendedFeatures(-1); + if ((EnabledFeatures & XSTATE_MASK_GSSE) == 0) { + Status = STATUS_FAILED_DRIVER_ENTRY; + goto exit; + } + + Status = KeSaveExtendedProcessorState(XSTATE_MASK_GSSE, &SaveState); + + if (!NT_SUCCESS(Status)) { + goto exit; + } + + __try { + SetYmmValues(&RegisterValues); + } + __finally { + KeRestoreExtendedProcessorState(&SaveState); + } + +exit: + return Status; +} +``` + +## Related topics +[**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) +[**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182) +[Using Floating Point in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20extended%20processor%20features%20in%20Windows%20drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/flushing-cached-data-during-dma-operations.md b/windows-driver-docs-pr/kernel/flushing-cached-data-during-dma-operations.md new file mode 100644 index 0000000000..0a589eaccb --- /dev/null +++ b/windows-driver-docs-pr/kernel/flushing-cached-data-during-dma-operations.md @@ -0,0 +1,60 @@ +--- +title: Flushing Cached Data during DMA Operations +author: windows-driver-content +description: Flushing Cached Data during DMA Operations +ms.assetid: 1b984b47-82cc-46b9-acad-73c5ed63e246 +keywords: ["DMA transfers WDK kernel , data integrity", "KeFlushIoBuffers", "FlushAdapterBuffers", "flushing cached data"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Flushing Cached Data during DMA Operations + + +## + + +In some platforms, the processor and system DMA controller (or bus-master DMA adapters) exhibit cache coherency anomalies. The following guidelines enable drivers that use version 1 or 2 of the DMA operations interface (see [**DMA\_OPERATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff544071)) to maintain coherent cache states across all supported processor architectures, including architectures that do not contain hardware to automatically enforce cache coherency. + +**Note**  The guidelines in this topic apply only to drivers that use versions 1 and 2 of the DMA operations interface. Drivers that use version 3 of this interface must follow a different set of guidelines. For more information, see [Version 3 of the DMA Operations Interface](version-3-of-the-dma-operations-interface.md). + +  + +**To maintain data integrity during DMA operations, lowest-level drivers must follow these guidelines** + +1. Call [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) before beginning a transfer operation to maintain consistency between data that might be cached in the processor and the data in memory. + + If a driver calls [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575) with the *CacheEnabled* parameter set to **TRUE**, the driver must call **KeFlushIoBuffers** before beginning a transfer operation to/from its buffer. + +2. Call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) at the end of each device transfer operation to be sure any remainder bytes in the system DMA controller's buffers have been written into memory or to the subordinate device. + + Or, call **FlushAdapterBuffers** at the end of each transfer operation for a given IRP to be sure all data has been read into system memory or written out to a bus-master DMA device. + +The following figure shows why it is important to flush the processor cache before a read or write operation using DMA if the host processor and DMA controller do not automatically maintain cache coherency. + +![diagram illustrating read and write operations using dma](images/16cchdma.png) + +An asynchronous DMA read or write operation accesses data in memory, not in the processor cache. Unless this cache has been flushed by calling **KeFlushIoBuffers** just before a read, the data transferred into system memory by the DMA operation could be overwritten with stale data if the processor cache is flushed later. Unless the processor cache has been flushed by calling **KeFlushIoBuffers** just before a write, the data in this cache might be more up-to-date than the copy in memory. + +**KeFlushIoBuffers** does nothing if the processor and DMA controller can be relied on to maintain cache coherency, so calls to this support routine have almost no overhead in such a platform. + +As also shown in the previous figure, DMA controllers, which are represented by adapter objects, can have internal buffers. Such a DMA controller can transfer cached data in fixed-size chunks, usually eight or more bytes at a time. Moreover, these DMA controllers can wait until their internal buffers are full before each transfer operation. + +Consider the case of a lowest-level driver that uses subordinate DMA to read data in variable-sized chunks or in fixed-size chunks that are not an integral multiple of a system DMA controller's cache size. Unless this driver calls **FlushAdapterBuffers** at the end of each device transfer, it cannot be sure when every byte the driver requested actually will be transferred. + +The driver of a bus-master DMA device also should call **FlushAdapterBuffers** at the end of each transfer operation for an IRP to be sure that all data has been transferred into system memory or out to the device. + +**FlushAdapterBuffers** returns a Boolean, value that indicates whether the requested flush operation was successful. A driver can use this value to determine how to set the I/O status block when completing an IRP for a DMA read or write operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Flushing%20Cached%20Data%20during%20DMA%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/flushing-cached-data-during-pio-operations.md b/windows-driver-docs-pr/kernel/flushing-cached-data-during-pio-operations.md new file mode 100644 index 0000000000..a13e469fbe --- /dev/null +++ b/windows-driver-docs-pr/kernel/flushing-cached-data-during-pio-operations.md @@ -0,0 +1,39 @@ +--- +title: Flushing Cached Data during PIO Operations +author: windows-driver-content +description: Flushing Cached Data during PIO Operations +ms.assetid: 8b15f1c4-d3c9-4d61-be37-ee1593f9d5e5 +keywords: ["flushing cached data", "KeFlushIoBuffers", "PIO transfer operations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Flushing Cached Data during PIO Operations + + +## + + +On some platforms, the instruction and data caches in the processor exhibit cache coherency anomalies during PIO read operations. + +**Note**   To maintain data integrity during their read operations, drivers that use PIO must follow this guideline: +Call [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) at the end of each read operation. + +For example, a driver making a PIO transfer from its device to system memory should call **KeFlushIoBuffers** at the end of each device transfer operation. As another example, a driver that reads a sequence of device registers into system memory should call **KeFlushIoBuffers** at the end of the sequence. Otherwise, such a driver might attempt to access data that is still in the processor's data cache, rather than in system memory, on some platforms. + +  + +**KeFlushIoBuffers** does nothing if the processor can be relied on to maintain cache coherency, so calls to this support routine have almost no overhead in such a platform. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Flushing%20Cached%20Data%20during%20PIO%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/function-drivers.md b/windows-driver-docs-pr/kernel/function-drivers.md new file mode 100644 index 0000000000..1d7f1df01c --- /dev/null +++ b/windows-driver-docs-pr/kernel/function-drivers.md @@ -0,0 +1,36 @@ +--- +title: Function Drivers +author: windows-driver-content +description: Function Drivers +ms.assetid: a6ac329b-ffb0-4bd3-9d54-195fa025d532 +keywords: ["function drivers WDK WDM", "raw mode WDK WDM", "WDM function drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Function Drivers + + +## + + +A *function driver* is the main driver for a device (see the [Possible Driver Layers](types-of-wdm-drivers.md#possible-driver-layers) figure). A function driver is typically written by the device vendor and is required (unless the device is being used in [*raw mode*](https://msdn.microsoft.com/library/windows/hardware/ff556331#wdkgloss-raw-mode)). The PnP manager loads at most one function driver for a device. A function driver can service one or more devices. + +A function driver provides the operational interface for its device. Typically the function driver handles reads and writes to the device and manages device power policy. + +The function driver for a device can be implemented as a driver/minidriver pair, such as a port/miniport driver pair or a class/miniclass driver pair. In such driver pairs, the minidriver is linked to the second driver, which is a DLL. + +If a device is being driven in raw mode, it has no function driver and no upper or lower-level filter drivers. All raw-mode I/O is done by the bus driver and optional bus filter drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Function%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/general-i-o-programming-techniques.md b/windows-driver-docs-pr/kernel/general-i-o-programming-techniques.md new file mode 100644 index 0000000000..f8efac89b9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/general-i-o-programming-techniques.md @@ -0,0 +1,31 @@ +--- +title: General I/O Programming Techniques +author: windows-driver-content +description: General I/O Programming Techniques +ms.assetid: c310829f-e102-4a96-aa3e-39136b8a641b +--- + +# General I/O Programming Techniques + + +One of the most important techniques in I/O programming is one that you should avoid: forcing the operating system to wait for your device. Almost everyone has had the experience of seeing Microsoft Windows "freeze up". Sometimes the freeze is due to a crash, but other times the system is simply waiting for a device to respond. + +There are two basic programming techniques for dealing with waiting for a device: *synchronous* and *asynchronous*. Synchronous programming waits for the device and should be avoided. Asynchronous programming uses other techniques (such as waiting for interrupt requests). For more information about synchronous and asynchronous programming, see the following topics: + +[Synchronous I/O Programming](synchronous-i-o-programming.md) + +[Asynchronous I/O Programming](asynchronous-i-o-programming.md) + +Microsoft Vista has a new policy for dealing with problems with synchronous programming. For more information about this new policy, see [Restricting Waits in Windows Vista](restricting-waits-in-vista.md) for more information. + +In earlier device driver programming, a driver would need to repeatedly request information from a driver until the answer was provided. This technique is called polling and should almost never be used. The best way to handle the problem of polling is to use hardware interrupts. For more information about hardware interrupts, see [Servicing Interrupts](servicing-interrupts.md). For more information on polling and why you should not use it, see [Avoid Device Polling](avoid-polling-devices.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20General%20I/O%20Programming%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/general-techniques-for-testing-wmi-driver-support.md b/windows-driver-docs-pr/kernel/general-techniques-for-testing-wmi-driver-support.md new file mode 100644 index 0000000000..c5803e8ef3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/general-techniques-for-testing-wmi-driver-support.md @@ -0,0 +1,67 @@ +--- +title: General Techniques for Testing WMI Driver Support +author: windows-driver-content +description: General Techniques for Testing WMI Driver Support +ms.assetid: 4d1a9198-2cc7-491d-a803-80f846882a6e +keywords: ["WMI WDK kernel , testing", "testing WMI support WDK kernel", "WMI WDM provider logs WDK", "errors WDK WMI", "provider logs WDK WMI", "events WDK WMI", "WMI WDK kernel , errors"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# General Techniques for Testing WMI Driver Support + + +## + + +### WMI Client Tools + +There are several tools you can use to test WMI support in your driver. + +Wbemtest +The operating system includes the Wbemtest tool, which provides a GUI you can use to query for WMI classes and class instances, change property values, execute methods, and receive event notifications. Connect to the "root\\wmi" namespace to test your driver's support. + +Wmic +Microsoft Windows XP and later operating systems include the Wmic tool, which provides a command shell you can use to issue WMI-related commands to test your driver. + +Wmimofck +The **wmimofck** command can be used to check the syntax of your binary MOF files. You can also use the **wmimofck -t** command to generate a VBScript file. You can use this script to test your driver's handling of WMI class instance queries. The **wmimofck -w** command generates webpages that can test querying and setting classes, executing methods, and receiving events. Note that the webpages do not support executing methods that use complex parameters or return values (such as an array of embedded classes). In such cases you can use Wbemtest instead. See [Using wmimofck.exe](using-wmimofck-exe.md) for more information about Wmimofck. + +You can also test your driver's WMI support by writing a custom WMI client application, using the WMI user-mode API. + +For more information about this user-mode API, which allows applications to provide or consume WMI information, refer to the Windows Management Instrumentation information in the Microsoft Windows SDK documentation. + +A WMI client application performs the following tasks to test a driver: + +- Connects to WMI. + + To connect to WMI, the application can call the Component Object Model (COM) function, **CoCreateInstance**, to retrieve a pointer to the **IWbemLocator** interface. The application then calls the **IWbemLocator::ConnectServer** method to connect to WMI. From this call, the application receives a pointer to the **IWbemServices** interface. + +- Accesses information in the driver. + + To access information and to register for events, the application uses the methods of the **IWbemServices** interface. + +### WMI IRPs and the System Event Log + +WMI errors that occur strictly in kernel-mode are logged to the system event log. You can use the Event Viewer to examine the system event log. (See [Logging Errors](logging-errors.md) for more information.) + +The two main sources of such errors are malformed replies to WMI requests and incorrect parameters to event notifications. For example, if the driver returns a malformed [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) data structure in response to an [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request, the system will log that to the system event log. The system would also log an invalid call to [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) and [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807) to issue a WMI event notification. + +### WMI WDM Provider Log + +WMI errors that occur while being handled by the WMI WDM provider (Wmiprov.dll) are logged to the log file for the WMI WDM Provider, Wmiprov.log. This is a text file can be found in %windir%\\system32\\wbem\\logs\\wmiprov.log. Errors, such as a bad or missing MOF resource for the driver, are logged here. In the case of a bad MOF resource, the file %windir%\\system32\\mofcomp.log might have additional information related to the error. + +In versions of Windows earlier than Windows Vista, you can change the logging settings for all WMI providers by using the Wmimgmt.msc application. (In Windows 98/Me, use Wbemcntl instead.) You can disable or reenable logging, change the directory where WMI log files are kept, as well as set the maximum size for such files. For more information, see [WMI Log Files](https://msdn.microsoft.com/library/aa394564). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20General%20Techniques%20for%20Testing%20WMI%20Driver%20Support%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/getting-an-adapter-object.md b/windows-driver-docs-pr/kernel/getting-an-adapter-object.md new file mode 100644 index 0000000000..f06a388dfb --- /dev/null +++ b/windows-driver-docs-pr/kernel/getting-an-adapter-object.md @@ -0,0 +1,74 @@ +--- +title: Getting an Adapter Object +author: windows-driver-content +description: Getting an Adapter Object +ms.assetid: 2af4ac28-b3c0-4e46-afb1-9c6897c67f03 +keywords: ["adapter objects WDK kernel , getting", "DEVICE_DESCRIPTION", "DMA_OPERATIONS", "DMA transfers WDK kernel , adapter objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Getting an Adapter Object + + +## + + +At device start-up, a driver that uses system or bus-master DMA calls [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) to get a pointer to an adapter object and to determine the maximum number of map registers available for each transfer operation. When a driver calls **IoGetDmaAdapter**, the I/O manager, in turn, calls the HAL to get the necessary platform-specific information. + +A driver must supply certain information in a system-defined [**DEVICE\_DESCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/ff543107) structure in its call to **IoGetDmaAdapter**. Drivers must use [**RtlZeroMemory**](https://msdn.microsoft.com/library/windows/hardware/ff563610) to initialize the **DEVICE\_DESCRIPTION** structure with zeros before setting values in it. + +The required data includes information about the features of the driver's device, such as whether the device is a bus master, if it has scatter/gather capabilities, and how many bytes of data the device can transfer at a time (**MaximumLength**). + +The required device description data also includes platform-specific information, such as the platform-specific and system-assigned number of the bus that a driver of a bus-master device controls. A driver can obtain this information by calling [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203). + +The **DEVICE\_DESCRIPTION** structure includes some fields that might be irrelevant to some DMA devices or drivers. For example, the **BusNumber** field is not used in WDM drivers. Each driver should supply values for the relevant structure members and should set the values for all other members to zero. + +The driver of a subordinate device should not pass **TRUE** in the **ScatterGather** field unless the device is capable of waiting for the system DMA controller to be reprogrammed when a request must be broken up into two or more DMA operations. + +**IoGetDmaAdapter** returns both a pointer to an adapter object and a platform-specific or device-specific value indicating how many map registers are available with the adapter object for each DMA transfer operation. + +The returned adapter object contains three fields that are accessible to drivers: + +- Version number (**Version**) + +- Size (**Size**) + +- Pointer to a [**DMA\_OPERATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff544071) structure (**DmaOperations**) + +The **DMA\_OPERATIONS** structure comprises a table of pointers to functions the driver must use to perform DMA operations on its device. The functions are accessible only through the pointers in this data structure; a driver cannot call them directly by name. (Note that these routines replace **Hal*Xxx*** routines supported in previous versions of Windows NT. To ensure compatibility for legacy drivers, the Wdm.h and Ntddk.h header files supply macros with the obsolete names, but new drivers should always call the functions through the data structure.) + +The number of map registers can vary from device to device and from platform to platform. Generally, the HAL assigns a number of map registers according to the following criteria: + +- If possible, the HAL returns a value that is one more than the number of map registers needed to transfer **MaximumLength** bytes, as specified in the driver's call to **IoGetDmaAdapter**. + +- Otherwise, the HAL returns a lesser value that is as large as possible for the particular platform. + +In other words, the HAL usually gives each driver enough map registers to maximize DMA throughput for its device, but the HAL can return a lesser value on some Windows platforms. There is no guarantee that a driver will get the number of map registers it requests, so drivers should always check the returned value. + +Any DMA device driver must provide storage for the adapter object pointer and *NumberOfMapRegisters* value returned by **IoGetDmaAdapter**. This pointer is a required parameter to the system-supplied support routines used for DMA. Because many of these support routines must be called at IRQL = DISPATCH\_LEVEL, the driver-allocated storage must be resident. Most DMA drivers provide the necessary storage in a [device extension](device-extensions.md). However, the storage can be in a controller extension if the driver also uses a [controller object](using-controller-objects.md) or in nonpaged pool that is allocated by the driver. See [Allocating System-Space Memory](allocating-system-space-memory.md) and [Managing Hardware Priorities](managing-hardware-priorities.md) for more information. + +When the driver has completed all DMA operations, it calls [**PutDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff559965) to free the adapter object. + +The following sections ([Using System DMA](using-system-dma.md) and [Using Bus-Master DMA](using-bus-master-dma.md)) describe how monolithic drivers of DMA devices use support routines to satisfy transfer requests. These sections assume that the driver has the following: + +- A standard [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, rather than setting up and managing an internal queue of IRPs + +- An internal routine to split transfer requests for which an insufficient number of map registers is available + +- No device-specific DMA constraints + +In other words, these sections describe the simplest possible technique for drivers' DMA operations, but individual drivers do not necessarily use exactly the same techniques. For any driver of a DMA device, which driver routines should split up large DMA transfer requests depends on the driver model (class/port or monolithic), on the device's features, and on any device-specific DMA constraints that driver must handle. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Getting%20an%20Adapter%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/guidelines-for-writing-adddevice-routines.md b/windows-driver-docs-pr/kernel/guidelines-for-writing-adddevice-routines.md new file mode 100644 index 0000000000..4d3c955d39 --- /dev/null +++ b/windows-driver-docs-pr/kernel/guidelines-for-writing-adddevice-routines.md @@ -0,0 +1,52 @@ +--- +title: Guidelines for Writing AddDevice Routines +author: windows-driver-content +description: Guidelines for Writing AddDevice Routines +ms.assetid: 8df36af5-158c-4c14-9fc2-2c3f997c2098 +keywords: ["AddDevice routines WDK kernel , design guidelines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Guidelines for Writing AddDevice Routines + + +## + + +Consider the following design guidelines when writing an [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine: + +- If a filter driver determines its *AddDevice* routine was called for a device it does not need to service, the filter driver must return STATUS\_SUCCESS to allow the rest of the device stack to be loaded for the device. The filter driver does not create a device object nor attach it to the device stack; the filter driver just returns success and allows the rest of the drivers to be added to the stack. + +- A driver must provide storage, usually in the device extension of a device object, for any kernel-defined objects and executive spin locks it uses. A driver also must provide storage for pointers to certain objects obtained from the I/O manager or other system components. + + You might decide to allocate additional system-space memory for the driver's needs, such as for long-term I/O buffers or a lookaside list. If so, an *AddDevice* routine can call the following routines: + + [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) for paged or nonpaged system-space memory + + [**ExInitializePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545309) or [**ExInitializeNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545301) to initialize a paged or nonpaged lookaside list + +- If the driver has a device-dedicated thread or waits on any kernel-defined dispatcher objects, the *AddDevice* routine might initialize [kernel dispatcher objects](kernel-dispatcher-objects.md). + +- If the driver uses any executive spin locks or provides the storage for an interrupt spin lock, the *AddDevice* routine might initialize these spin locks. See [Spin Locks](spin-locks.md) for more information. + +- Tighten file-open security when calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397). + + Specify the FILE\_DEVICE\_SECURE\_OPEN characteristic on the call to **IoCreateDevice**. This characteristic is supported on Windows NT 4.0 SP5 and later. It directs the I/O manager to perform security checks against the device object for all open requests. Vendors should specify this characteristic on calls to **IoCreateDevice** if the FILE\_DEVICE\_SECURE\_OPEN characteristic is not set in the device's class-installer INF or the device's INF and the drivers do not perform their own security checks on opens. (For more information, see [Controlling Device Namespace Access](controlling-device-namespace-access.md).) + + If a driver sets the FILE\_DEVICE\_SECURE\_OPEN characteristic when it calls **IoCreateDevice**, the I/O manager applies the security descriptor of the device object to any relative opens or trailing-filename opens. For example, if FILE\_DEVICE\_SECURE\_OPEN is set for \\Device\\foo, and if \\Device\\foo can only be opened by the administrator, then \\Device\\foo\\abc can also be opened by the administrator. The I/O manager, however, prevents a normal user from opening \\Device\\foo and \\Device\\foo\\abc. + + If one driver for a device sets this characteristic, the PnP manager propagates it to all the device objects for the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Guidelines%20for%20Writing%20AddDevice%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/guidelines-for-writing-dispatch-internal-devicecontrol-routines.md b/windows-driver-docs-pr/kernel/guidelines-for-writing-dispatch-internal-devicecontrol-routines.md new file mode 100644 index 0000000000..64c8d75606 --- /dev/null +++ b/windows-driver-docs-pr/kernel/guidelines-for-writing-dispatch-internal-devicecontrol-routines.md @@ -0,0 +1,58 @@ +--- +title: Guidelines for Writing Dispatch(Internal)DeviceControl Routines +author: windows-driver-content +description: Guidelines for Writing Dispatch(Internal)DeviceControl Routines +ms.assetid: e64ab28e-2904-41c2-a262-405bc129b9bb +keywords: ["dispatch routines WDK kernel , DispatchDeviceControl routine", "dispatch routines WDK kernel , DispatchInternalDeviceControl routine", "DispatchDeviceControl routine", "DispatchInternalDeviceControl routine", "IRP_MJ_DEVICE_CONTROL I/O function code", "IRP_MJ_INTERNAL_DEVICE_CONTROL I/O function code", "internal device control dispatch routines WDK kernel", "device control dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Guidelines for Writing Dispatch(Internal)DeviceControl Routines + + +## + + +Keep the following points in mind when writing a [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) or [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routine: + +At a minimum, a higher-level driver must copy the parameters for an [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) request from its own I/O stack location in the IRP to the next-lower-level driver's I/O stack location. Then, it must call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) with a pointer to the next-lower driver's device object and the IRP. + +The higher-level driver should propagate the status value returned by **IoCallDriver** or set it in the returned IRP's I/O status block when it returns control for a request that lower drivers handle synchronously. + +The underlying device driver must process device control requests unless it has a closely coupled class driver that completes a subset of these requests on its behalf. A device driver's *DispatchDeviceControl* routine usually begins processing these requests by turning on the **Parameters.DeviceIoControl.IoControlCode** in its I/O stack location of each IRP. + +A lower-level device driver should check the parameters passed in with the request and fail the IRP with an appropriate error if any parameter is invalid. The most common check on the validity of parameters to these requests has the form: + +``` + if (Irp->Parameters.DeviceIoControl.InputBufferLength < + (sizeof(IOCTL_SPECIFIC_STRUCTURE))) { + status = STATUS_XXX; +``` + +or +``` + if (Irp->Parameters.DeviceIoControl.OutputBufferLength < + (sizeof(IOCTL_SPECIFIC_STRUCTURE))) { + status = STATUS_XXX; +``` + +where the status value set is one of STATUS\_BUFFER\_TOO\_SMALL or STATUS\_INVALID\_PARAMETER. +Every device driver's *DispatchDeviceControl* or *DispatchInternalDeviceControl* routine must handle the receipt of an unrecognized I/O control code by setting the I/O status block with an appropriate NTSTATUS value, setting its **Information** field to zero, and completing the IRP with a *PriorityBoost* of IO\_NO\_INCREMENT. + +The particular I/O control codes a device driver handles must include any device-type-specific, system-defined I/O control codes for the same type of device. See the device-specific sections of the Windows Driver Kit (WDK) for more information about the system requirements for each type of device and the corresponding (Windows SDK) header files, each beginning with the prefix *ntdd*, for declarations of the system-defined structures for these I/O control codes. + +The class driver of a closely coupled class/port driver pair can process and complete a subset of device control requests without passing them on to the underlying port driver. However, such a class driver must pass on all valid device control requests that require a change of state for the device and those that require the return of volatile information about the device, such as its current baud rate, volume, or video mode. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Guidelines%20for%20Writing%20Dispatch%28Internal%29DeviceControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/guidelines-for-writing-dpc-routines.md b/windows-driver-docs-pr/kernel/guidelines-for-writing-dpc-routines.md new file mode 100644 index 0000000000..e4967538d1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/guidelines-for-writing-dpc-routines.md @@ -0,0 +1,68 @@ +--- +title: Guidelines for Writing DPC Routines +author: windows-driver-content +description: Guidelines for Writing DPC Routines +ms.assetid: 570219be-d152-4826-855a-737bbed67ffd +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel", "DpcForIsr", "CustomDpc"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Guidelines for Writing DPC Routines + + +## + + +Keep the following points in mind when writing a [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine: + +- A *DpcForIsr* or *CustomDpc* routine must synchronize its access to a physical device, and to any shared state information or resources that the driver maintains, with the driver's other routines that access the same device or memory locations. + + If a *DpcForIsr* or *CustomDpc* routine shares the device or state with an ISR, it must call [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302), supplying the address of a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that programs the device or accesses the shared state. For more information, see [Using Critical Sections](using-critical-sections.md). + + If a *DpcForIsr* or *CustomDpc* routine shares state or resources, such as an interlocked queue or a timer object, with routines other than an ISR, it must protect the shared state or resources with a driver-initialized executive spin lock. For more information, see [Spin Locks](spin-locks.md). + +- *DpcForIsr* and *CustomDpc* routines run at IRQL = DISPATCH\_LEVEL, which restricts the set of support routines they can call. + + For example, *DpcForIsr* and *CustomDpc* routines can neither access nor allocate pageable memory, and they cannot wait for [kernel dispatcher objects](kernel-dispatcher-objects.md) to be set to the signaled state. On the other hand, they can acquire and release a driver's executive spin lock with [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921) and [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150), which run faster than **KeAcquireSpinLock** and **KeReleaseSpinLock**. + + Although a DPC routine cannot make blocking calls, it can queue a work item to run in a [system worker thread](system-worker-threads.md) that runs at IRQL = PASSIVE\_LEVEL. The work item can make blocking calls that wait on dispatcher objects. To queue a work item, a *DpcForIsr* routine typically calls a routine such as [**IoQueueWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549466), and a *CustomDpc* routine typically calls the [**ExQueueWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff540216) routine. + +- *DpcForIsr* and *CustomDpc* routines are typically responsible for starting the next I/O operation on the device. + + For lowest-level physical device drivers that use direct I/O, this responsibility can include using a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine to program the device to transfer more data in order to satisfy the current IRP before the driver calls [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358). + +- *DpcForIsr* and *CustomDpc* routines should run only for brief periods, and should delegate as much processing as possible to worker threads. + + While a DPC routine runs on a processor, all threads are prevented from running on the same processor. Other DPC routines that are queued and ready to run can be blocked from executing until the current DPC routine is finished. To avoid degrading system responsiveness, a typical DPC routine should run for no more than 100 microseconds each time it is called. If a task requires longer than 100 microseconds and must execute at IRQL = DISPATCH\_LEVEL, the DPC routine should end after 100 microseconds and schedule one or more [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routines to complete the task at a later time. For more information about *CustomTimerDpc* routines, see [Timer Objects and DPCs](timer-objects-and-dpcs.md). + + A DPC routine should perform only tasks that must run at DISPATCH\_LEVEL, and then delegate any remaining interrupt-related work to threads that run at IRQL = PASSIVE\_LEVEL. For example, a DPC routine can queue a work item to run in a [system worker thread](system-worker-threads.md). + + DPC routines that call the [**KeStallExecutionProcessor**](https://msdn.microsoft.com/library/windows/hardware/ff553295) routine to delay execution must not specify delays of more than 100 microseconds. + + Use the performance analysis tools in the WDK to evaluate the execution times of DPC routines. For an example that uses the [Tracelog](https://msdn.microsoft.com/library/windows/hardware/ff552994) tool to monitor DPC execution times, see [Example 15: Measuring DPC/ISR Time](https://msdn.microsoft.com/library/windows/hardware/ff545764). + +- If the driver uses DMA and its [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine returns **KeepObject** or **DeallocateObjectKeepRegisters** (thereby retaining the system DMA controller channel or bus-master adapter for additional transfer operations), the *DpcForIsr* or *CustomDpc* routine is responsible for releasing the adapter object or map registers with [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) or [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) before it completes the current IRP and returns control. + +- If a lowest-level physical device driver sets up a [controller object](using-controller-objects.md) to synchronize I/O operations through the controller to attached devices, its *DpcForIsr* or *CustomDpc* routine is responsible for releasing the controller object using [**IoFreeController**](https://msdn.microsoft.com/library/windows/hardware/ff549104) before it completes the current IRP and returns control. + +- *DpcForIsr* and *CustomDpc* routines are generally responsible for logging any device errors that occurred during the processing of a given request, retrying the current request if necessary and possible, and for setting the I/O status block and calling [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) for the current IRP. + +- If the driver and device support overlapped I/O operations, the driver must follow the rules for [handling overlapped I/O operations](handling-overlapped-i-o-operations.md). + +- The *DpcForIsr* or *CustomDpc* routine of any driver usually completes the I/O processing only for a subset of the public I/O control codes that the driver must support. In particular, the DPC routine completes operations for device control requests with the following characteristics: + - Requests that change the state of the physical device + - Requests that require the return of inherently volatile information about the physical device + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Guidelines%20for%20Writing%20DPC%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/guidelines-for-writing-pnp-notification-callback-routines.md b/windows-driver-docs-pr/kernel/guidelines-for-writing-pnp-notification-callback-routines.md new file mode 100644 index 0000000000..cef1b92b23 --- /dev/null +++ b/windows-driver-docs-pr/kernel/guidelines-for-writing-pnp-notification-callback-routines.md @@ -0,0 +1,48 @@ +--- +title: Guidelines for Writing PnP Notification Callback Routines +author: windows-driver-content +description: Guidelines for Writing PnP Notification Callback Routines +ms.assetid: 2153b4c2-f60f-4ac9-8eee-66c5f3a9f414 +keywords: ["notifications WDK PnP , callback routines", "callback routines WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Guidelines for Writing PnP Notification Callback Routines + + +## + + +The PnP manager calls notification callback routines at IRQL = PASSIVE\_LEVEL. + +To ensure smooth operation of the PnP subsystem, a PnP notification callback routine must follow these guidelines: + +1. A notification callback routine must not block. + +2. A notification callback routine must not call, or cause a call to, synchronous routines that generate PnP events or any routine that blocks waiting for device installation or removal. + + Calling such routines during a notification callback can cause a system deadlock. + + For example, a driver must not call [**IoReportTargetDeviceChange**](https://msdn.microsoft.com/library/windows/hardware/ff549625) in a notification callback routine. Call [**IoReportTargetDeviceChangeAsynchronous**](https://msdn.microsoft.com/library/windows/hardware/ff549634) instead. + +3. A notification callback routine should return success for any events it does not explicitly fail. + + When a driver registers for notification on an event category, the PnP manager notifies the driver of all events in that category, present and future. If a driver returns an error status for events it does not handle, the driver risks failing a new query event by mistake. + + A driver correctly returns an error status when, for example, the driver fails a query notification to veto the event being proposed. + +4. A notification callback routine should be paged code. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Guidelines%20for%20Writing%20PnP%20Notification%20Callback%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-guid-target-device-query-remove-event.md b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-query-remove-event.md new file mode 100644 index 0000000000..bb64f90fac --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-query-remove-event.md @@ -0,0 +1,46 @@ +--- +title: Handling a GUID_TARGET_DEVICE_QUERY_REMOVE Event +author: windows-driver-content +description: Handling a GUID_TARGET_DEVICE_QUERY_REMOVE Event +ms.assetid: f3e867c5-f7b8-40d2-a6cc-c5cb82e0b59b +keywords: ["notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification", "GUID_TARGET_DEVICE_QUERY_REMOVE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a GUID\_TARGET\_DEVICE\_QUERY\_REMOVE Event + + +## + + +Before the PnP manager sends an [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) IRP to the drivers for a device, it calls any notification callback routines that registered for **EventCategoryTargetDeviceChange** on the device. The PnP manager specifies a *NotificationStructure*.**Event** of GUID\_TARGET\_DEVICE\_QUERY\_REMOVE. + +In response to such a notification, the callback routine determines whether the device can be removed without disrupting the system. + +If the device should not be removed, the callback routine returns STATUS\_UNSUCCESSFUL. In response to this status, the PnP manager aborts query-remove processing and the device will not be removed. + +If the device can be removed, the callback routine should perform any appropriate operations to prepare for device removal, such as closing any handles open on the device (if possible). If handles remain open on the device, the PnP manager cannot remove the device, and the PnP manager aborts query-remove processing. + +When successfully handling a GUID\_TARGET\_DEVICE\_QUERY\_REMOVE event, a notification callback routine should: + +- Close any open handles to the device. + +- If the driver has an outstanding reference on the file object, dereference the file object. + +- Remain registered for future **EventCategoryTargetDeviceChange** notifications. This is important because the impending remove operation might be canceled. + +Closing a handle to a device does not cancel a driver's registration for PnP target device change notification. The PnP manager can still call the driver's notification callback routine, but in such calls the file object in the *NotificationStructure* is not valid. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20GUID_TARGET_DEVICE_QUERY_REMOVE%20Event%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-cancelled-event.md b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-cancelled-event.md new file mode 100644 index 0000000000..c91b408590 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-cancelled-event.md @@ -0,0 +1,42 @@ +--- +title: Handling a GUID_TARGET_DEVICE_REMOVE_CANCELLED Event +author: windows-driver-content +description: Handling a GUID_TARGET_DEVICE_REMOVE_CANCELLED Event +ms.assetid: 19fe012b-3ed0-4356-999b-79b1d08dfbd6 +keywords: ["notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification", "GUID_TARGET_DEVICE_REMOVE_CANCELLED"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED Event + + +## + + +If an [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) request fails, the PnP manager sends an [**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550823) IRP to the drivers for the device. After the cancel-remove IRP completes successfully, the PnP manager calls any notification callback routines that registered for **EventCategoryTargetDeviceChange** on the device. The PnP manager specifies a *NotificationStructure*.**Event** of GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED. + +When handling a GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED event, a notification callback routine should: + +- Reregister for target device notification. + + Because the driver closed the previous registration handle in response to the query-remove notification, the driver must open a new handle. The driver must: + + 1. Remove the old registration with [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398). + + 2. Open a new handle to the device. + + 3. Reregister for notification on the new handle with **IoRegisterPlugPlayNotification**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20GUID_TARGET_DEVICE_REMOVE_CANCELLED%20Event%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-complete-event.md b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-complete-event.md new file mode 100644 index 0000000000..7ef9c02fd7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-guid-target-device-remove-complete-event.md @@ -0,0 +1,42 @@ +--- +title: Handling a GUID_TARGET_DEVICE_REMOVE_COMPLETE Event +author: windows-driver-content +description: Handling a GUID_TARGET_DEVICE_REMOVE_COMPLETE Event +ms.assetid: 7f20faae-b5ef-4a64-9150-bff14b04aaa4 +keywords: ["notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification", "GUID_TARGET_DEVICE_REMOVE_COMPLETE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE Event + + +## + + +Before the PnP manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) IRP to the drivers for a device, the PnP manager calls any kernel-mode notification callback routines that registered for **EventCategoryTargetDeviceChange** on the device. The PnP manager specifies a *NotificationStructure*.**Event** of GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE. + +When handling a GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE event, a notification callback routine should: + +- Remove notification registration on the device. + + The device has been removed, so the driver calls [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) to remove the notification registration. + + The device may still be physically present on the machine, but all device objects have been deleted and the device is not available for use. + +- Perform surprise-remove processing if the driver did not receive a previous query-remove notification. + + If a device is surprise-removed, the PnP manager sends registered drivers a remove-complete notification without a prior query-remove notification. In this case a driver has to perform any necessary cleanup, such as closing any handles to the device and removing any outstanding references to the file object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20GUID_TARGET_DEVICE_REMOVE_COMPLETE%20Event%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-bus-driver.md b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-bus-driver.md new file mode 100644 index 0000000000..d480ff025b --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-bus-driver.md @@ -0,0 +1,36 @@ +--- +title: Handling a System Query-Power IRP in a Bus Driver +author: windows-driver-content +description: Handling a System Query-Power IRP in a Bus Driver +ms.assetid: d42c268e-d57d-41a6-8e61-67c651082106 +keywords: ["query-power IRPs WDK power management", "bus drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Query-Power IRP in a Bus Driver + + +## + + +When a system query-power request reaches a bus driver (that is not the power policy owner for a device), the driver ensures that it can support a device power state that corresponds to the queried system power state and, if wake-up is enabled, that the queried system power state would not prevent its device from waking the system. + +In Windows 7 and Windows Vista, the bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS if the driver can change to the specified power state or sets a failure status if the driver cannot. + +In Windows Server 2003, Windows XP, and Windows 2000, the bus driver first calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) and then sets **Irp->IoStatus.Status** to STATUS\_SUCCESS if the driver can change to the specified power state or sets a failure status if the driver cannot. + +After the bus driver completes the IRP, the power manager calls [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines set by other drivers as they passed the IRP down the stack. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Query-Power%20IRP%20in%20a%20Bus%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-device-power-policy-owner.md b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-device-power-policy-owner.md new file mode 100644 index 0000000000..1843d81504 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-device-power-policy-owner.md @@ -0,0 +1,70 @@ +--- +title: Handling a System Query-Power IRP in a Device Power Policy Owner +author: windows-driver-content +description: Handling a System Query-Power IRP in a Device Power Policy Owner +ms.assetid: 680e3be2-63d9-4d79-a7c0-422e852e9347 +keywords: ["query-power IRPs WDK power management", "device power policy owners WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Query-Power IRP in a Device Power Policy Owner + + +## + + +When a device power policy owner receives an [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) for a system power state, it responds by passing down the query and, in an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, sending an **IRP\_MN\_QUERY\_POWER** for a device power state. When all drivers in the stack have completed the device query, the device power policy owner completes the system query. + +A device power policy owner should take the following steps in its [DispatchPower routine](dispatchpower-routines.md) to respond to a system query: + +1. Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP, to ensure that the driver does not receive a PnP [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, beginning with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP and return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), call **IoCompleteRequest** to complete the IRP, and return the failure status. + +2. Ensure that the driver can support the queried system power state, as described in [Failing a System Query-Power IRP in a Filter or Function Driver](failing-a-system-query-power-irp-in-a-filter-or-function-driver.md). If not, complete the IRP with a failure status as described in that section. + + However, a driver must not fail a query for S4 (**PowerSystemHibernate**) if its device is enabled for wake-up but it cannot wake the system from the hibernate state. In this case, the power policy owner for the driver (which sent the [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766)) must cancel the wait/wake IRP and succeed the system query. For more information, see [Canceling a Wait/Wake IRP](canceling-a-wait-wake-irp.md). + +3. If the driver can support the queried system power state, call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422). + +4. Set up the IRP stack location for the next-lower driver by calling [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387). + +5. Set an *IoCompletion* routine in the system query power IRP. + +6. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000), to pass the IRP to the next-lower driver. + +7. Return STATUS\_PENDING. + +The [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine should do the following: + +1. Check **Irp->IoStatus.Status** to ensure that lower drivers have completed the IRP successfully. If a lower driver has specified a non-success NTSTATUS value, the *IoCompletion* routine should return the NTSTATUS value. + +2. If lower drivers have successfully completed the IRP, call [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send a device query-power IRP for a device power state that is valid for the queried system power state. If necessary, consult the DEVICE\_STATE array in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure to determine which device power states are valid for the queried system power state. + +3. Specify a callback routine (*CompletionFunction* parameter) in the call to **PoRequestPowerIrp** and pass the system IRP in the *Context* area. + +4. Return STATUS\_MORE\_PROCESSING\_REQUIRED so that the driver can finish processing the system query IRP in the callback routine. + +After the IRP has been completed and all *IoCompletion* routines set during IRP processing have been run, the power manager, through the I/O manager, calls the power policy manager's callback routine (the *CompletionFunction* parameter to **PoRequestPowerIrp**). The callback routine, in turn, must do the following: + +1. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only.) + +2. Complete the system query-power IRP (call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with the status returned for the device query-power IRP. + +3. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to free the previously acquired lock. + +Remember that the device power policy owner not only sends the device query but also must handle it on its way down the device stack. For more information, see [Handling IRP\_MN\_QUERY\_POWER for Device Power States](handling-irp-mn-query-power-for-device-power-states.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Query-Power%20IRP%20in%20a%20Device%20Power%20Policy%20Owner%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-filter-or-function-driver.md b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-filter-or-function-driver.md new file mode 100644 index 0000000000..d6220d6d17 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-query-power-irp-in-a-filter-or-function-driver.md @@ -0,0 +1,46 @@ +--- +title: Handling a System Query-Power IRP in a Filter or Function Driver +author: windows-driver-content +description: Handling a System Query-Power IRP in a Filter or Function Driver +ms.assetid: 81d921d5-6db8-4858-b86e-1484781faba5 +keywords: ["query-power IRPs WDK power management", "filter drivers WDK power management", "function drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Query-Power IRP in a Filter or Function Driver + + +## + + +A filter or function driver (that is not the power policy owner for a device) should pass a system query-power IRP to the next-lower driver, in the following steps: + +1. Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP, to ensure that the driver does not receive a PnP [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, beginning with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP and return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), call **IoCompleteRequest** to complete the IRP, and return the failure status. + +2. Determine whether it should fail the query. For guidelines, see [Failing a System Query-Power IRP in a Filter or Function Driver](failing-a-system-query-power-irp-in-a-filter-or-function-driver.md) and complete processing as described in that section. + +3. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776). (Windows Server 2003, Windows XP, and Windows 2000 only) + +4. Set the IRP stack location ([**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) or [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387)). The driver can set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine in the IRP, but doing so is rarely necessary. + +5. Call **IoCallDriver** (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP to the next-lower driver. + +6. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560). However, if the driver set an *IoCompletion* routine for the IRP, make this call from the *IoCompletion* routine instead. + +7. Return STATUS\_PENDING from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Query-Power%20IRP%20in%20a%20Filter%20or%20Function%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-bus-driver.md b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-bus-driver.md new file mode 100644 index 0000000000..7b70cad0a3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-bus-driver.md @@ -0,0 +1,38 @@ +--- +title: Handling a System Set-Power IRP in a Bus Driver +author: windows-driver-content +description: Handling a System Set-Power IRP in a Bus Driver +ms.assetid: e88344bd-4223-4cd5-9428-201d46c6dbb4 +keywords: ["set-power IRPs WDK power management", "bus drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Set-Power IRP in a Bus Driver + + +## + + +When a bus driver receives a system set-power IRP, it must take the following steps: + +1. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only.) + +2. Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. The driver cannot fail a system set-power IRP. + +3. Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), specifying IO\_NO\_INCREMENT, to complete the IRP. + +The bus driver does not change device power settings until it receives a power IRP that requests a device power state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Set-Power%20IRP%20in%20a%20Bus%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-device-power-policy-owner.md b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-device-power-policy-owner.md new file mode 100644 index 0000000000..f26b78c383 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-device-power-policy-owner.md @@ -0,0 +1,52 @@ +--- +title: Handling a System Set-Power IRP in a Device Power Policy Owner +author: windows-driver-content +description: Handling a System Set-Power IRP in a Device Power Policy Owner +ms.assetid: f6206455-142b-4f3f-ae5a-d8e79386bce3 +keywords: ["set-power IRPs WDK power management", "device power policy owners WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Set-Power IRP in a Device Power Policy Owner + + +## + + +In response to a system set-power IRP, the [power policy owner](managing-device-power-policy.md) for a device stack is responsible for putting its device stack into an appropriate device power state. + +As a general rule, when a device power policy owner receives an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) for a system power state, it should respond by passing the system set-power IRP down the device stack. A device power policy owner should also respond by sending down the device stack **IRP\_MN\_SET\_POWER** for a corresponding device power state in an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. After all drivers in the stack have completed the device set-power IRP, the device power policy owner completes the system set-power IRP. + +However, to improve system resume performance, device power owners for devices that do not have child devices should use a different approach to reduce the time it takes a system to return to [working state S0](system-working-state-s0.md) from a [sleeping state](system-sleeping-states.md). In this case, in response to a system set-power IRP that returns a system to working state S0, device power policy owners should perform the following sequence of operations: + +1. After receiving an **IRP\_MN\_SET\_POWER** IRP for the S0 system power state in the driver's [DispatchPower routine](dispatchpower-routines.md), set an *IoCompletion* routine for the IRP and pass the IRP down the stack. + +2. In the *IoCompletion* routine set in step (1), request an **IRP\_MN\_SET\_POWER** IRP for the corresponding device power state and then immediately complete the system set-power IRP. The driver should not wait for device set-power IRPs to complete before it completes the system set-power IRP. The *IoCompletion* routine is executed after all lower-level drivers have completed the system set-power IRP and the system set-power IRP is passed back to the driver's functional device object (FDO). + +3. Perform any required device-specific initialization. + +4. Complete the device set-power IRP that was sent in step (2). + +5. Process I/O requests that were queued when the device was in a [device sleeping state](device-sleeping-states.md). + +The kernel power manager has a limited set of IRP dispatch queues, and must quickly notify all devices in the system of the return to the system working state S0. Drivers that fail to complete the system set-power IRP as quickly as possible prevent other devices from getting their system set-power IRP, which can adversely affect overall system performance during system power-state transitions. + +For more detail on handling system set-power IRPs, see the following: + +[Determining the Correct Device Power State](determining-the-correct-device-power-state.md) + +[Sending a Device Set-Power IRP in Response to a System Set-Power IRP](sending-a-device-set-power-irp-in-response-to-a-system-set-power-irp.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Set-Power%20IRP%20in%20a%20Device%20Power%20Policy%20Owner%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-filter-driver.md b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-filter-driver.md new file mode 100644 index 0000000000..df30e6a1d9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-system-set-power-irp-in-a-filter-driver.md @@ -0,0 +1,44 @@ +--- +title: Handling a System Set-Power IRP in a Filter Driver +author: windows-driver-content +description: Handling a System Set-Power IRP in a Filter Driver +ms.assetid: a6e364fc-f173-47ce-b36b-84f802cefcc3 +keywords: ["set-power IRPs WDK power management", "filter drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a System Set-Power IRP in a Filter Driver + + +## + + +All filter drivers and any function driver that does not own power policy for its device stack should simply pass the system set-power IRP to the next-lower driver, in the following steps: + +1. Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP, to ensure that the driver does not receive a PnP [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, beginning with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP and return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should first call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), call **IoCompleteRequest** to complete the IRP, and then return the failure status. + +2. Call **PoStartNextPowerIrp** to start the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only.) + +3. Set the IRP stack location ([**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) or [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387)). The driver can set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine in the IRP, but doing so is rarely necessary. + +4. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP to the next-lower driver. + +5. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560). However, if the driver set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for the IRP, make this call from the *IoCompletion* routine instead. + +6. Return STATUS\_PENDING from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20System%20Set-Power%20IRP%20in%20a%20Filter%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-bus-driver--pdo-.md b/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-bus-driver--pdo-.md new file mode 100644 index 0000000000..6159c8ba32 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-bus-driver--pdo-.md @@ -0,0 +1,62 @@ +--- +title: Handling a Wait/Wake IRP in a Bus Driver (PDO) +author: windows-driver-content +description: Handling a Wait/Wake IRP in a Bus Driver (PDO) +ms.assetid: 9583b935-26e1-49c6-827d-932762af114d +keywords: ["receiving wait/wake IRPs", "wait/wake IRPs WDK power management , receiving", "bus drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a Wait/Wake IRP in a Bus Driver (PDO) + + +## + + +Like other power IRPs, each wait/wake IRP must be passed all the way down the device stack to the bus driver (PDO), which is ultimately responsible for completing the IRP. Upon receiving the IRP, the bus driver can either fail it immediately or hold it pending for later completion. The following are the steps the bus driver must take: + +1. Inspect the value at **Irp->Parameters.WaitWake.PowerState**. If the device supports wake-up, but not from the specified [**SystemWake**](systemwake.md) state or not from the current device power state, the driver should fail the IRP as follows: + + - Set STATUS\_INVALID\_DEVICE\_STATE in **Irp->IoStatus.Status**. + + - Complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)), specifying a priority boost of IO\_NO\_INCREMENT. + + - Return the status set in **Irp->IoStatus.Status** from the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +2. Check whether a wait/wake IRP is already pending for the PDO. If so, set **Irp->IoStatus.Status** to STATUS\_DEVICE\_BUSY, increment the driver's internal count of wait/wake IRPs, and complete the IRP as described in the previous step. + + Only one wait/wake IRP can be pending for a PDO. + +3. If the device supports wake-up from the specified system power state and no wait/wake IRP is already pending, call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) to indicate to the I/O manager that the IRP will be completed or canceled later. Do not set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +4. Set the device hardware to enable wake-up. + + The specific mechanism by which a bus driver enables its hardware for wake-up is device-dependent. For a PCI device, Pci.sys is responsible for setting the PME-enable bit because this driver owns the PME register. For other devices, refer to the device-class-specific documentation. + +5. If the PDO is the child of an FDO, [request a wait/wake IRP](sending-a-wait-wake-irp.md) for the FDO, making sure to set a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for the current IRP (the IRP that it holds pending). Do not attempt to pass on or reuse the current IRP. + +6. Return STATUS\_PENDING from the *DispatchPower* routine. + +7. When a wake-up signal arrives, call **IoCompleteRequest** to complete the pending wait/wake IRP, setting **Irp-IoStatus.Status** to STATUS\_SUCCESS, and specifying a priority boost of IO\_NO\_INCREMENT. + +### For Devices That Do Not Support Wake-Up + +If the device does not support wake-up, the bus driver (PDO) should proceed as follows: + +1. Complete the wait/wake IRP by calling **IoCompleteRequest**, specifying IO\_NO\_INCREMENT. + +2. Return from the *DispatchPower* routine, passing the value at **Irp->IoStatus.Status** as its return value. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20Wait/Wake%20IRP%20in%20a%20Bus%20Driver%20%28PDO%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-function--fdo--or-filter-driver--filter-.md b/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-function--fdo--or-filter-driver--filter-.md new file mode 100644 index 0000000000..4e16e93b2a --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-a-wait-wake-irp-in-a-function--fdo--or-filter-driver--filter-.md @@ -0,0 +1,66 @@ +--- +title: Handling a Wait/Wake IRP in a Function (FDO) or Filter Driver (Filter DO) +author: windows-driver-content +description: Handling a Wait/Wake IRP in a Function (FDO) or Filter Driver (Filter DO) +ms.assetid: 752b6c3c-f42a-469d-8a43-0778ecbe4541 +keywords: ["receiving wait/wake IRPs", "wait/wake IRPs WDK power management , receiving", "function drivers WDK power management", "FDOs WDK power management", "filter DOs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling a Wait/Wake IRP in a Function (FDO) or Filter Driver (Filter DO) + + +## + + +When a driver that creates an FDO or filter DO receives an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) request for the associated PDO, it can either simply pass the IRP down to the next-lower driver or take certain actions before passing down the IRP. + +### For Devices That Support Wake-Up + +Upon receiving a wait/wake IRP, a function or filter driver should take the following steps: + +1. Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP, to ensure that the driver does not receive a PnP [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the wait/wake IRP. + + If [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204) returns a failure status, the driver should not continue processing the IRP. Instead, it completes the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)), and return the failure status. + +2. Inspect the value at **Irp->Parameters.WaitWake.PowerState** and compare the current device power state with **DeviceState**\[SystemWake\] in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. + + If the device supports wake-up, but not from the specified [SystemWake](systemwake.md) state or not from the current device power state, the driver should fail the IRP as follows: + + - Set STATUS\_INVALID\_DEVICE\_STATE in **Irp->IoStatus.Status**. + - Complete the IRP (**IoCompleteRequest**), specifying a priority boost of IO\_NO\_INCREMENT. + - Return the status set in **Irp->IoStatus.Status** from the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +3. Otherwise, set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for the IRP using [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). The *IoCompletion* routine should perform whatever tasks the driver requires to return the device to the working state. + + The *IoCompletion* routine will also be called if the IRP is canceled. + +4. Save any information the driver might need in its *IoCompletion* routine. + +5. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 003, Windows XP, and Windows 2000), to pass the wait/wake IRP to the next-lower driver. + +6. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to release the previously acquired lock. + +7. Return STATUS\_PENDING from the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. The driver must not change the value in **Irp->IoStatus.Status** while it holds the IRP. + +### For Devices That Do Not Support Wake-Up + +If a function or filter driver receives a wait/wake IRP for a device that does not support wake-up, the driver should fail the IRP as follows: + +1. Complete the IRP (**IoCompleteRequest**), specifying a priority boost of IO\_NO\_INCREMENT. + +2. Return the status set in **Irp->IoStatus.Status** from the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20a%20Wait/Wake%20IRP%20in%20a%20Function%20%28FDO%29%20or%20Filter%20Driver%20%28Filter%20DO%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-remove-device-request.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-remove-device-request.md new file mode 100644 index 0000000000..fd484a443a --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-remove-device-request.md @@ -0,0 +1,58 @@ +--- +title: Handling an IRP_MN_CANCEL_REMOVE_DEVICE Request +author: windows-driver-content +description: Handling an IRP_MN_CANCEL_REMOVE_DEVICE Request +ms.assetid: 3382c47d-6ac8-409e-b558-ad2f2ae83715 +keywords: ["IRP_MN_CANCEL_REMOVE_DEVICE", "spurious cancel-remove requests WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_CANCEL\_REMOVE\_DEVICE Request + + +## + + +In response to an [**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550823) request, the drivers for a device must return the device to the state it was in prior to receiving the **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request. Typically, drivers return the device to the started state. + +In addition to sending an **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** to a device, the PnP manager sends the IRP to the device's removal relations, if any. The PnP manager also sends a cancel-remove IRP to the device's children. + +The PnP manager calls any **EventCategoryTargetDeviceChange** notification callbacks after the **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** request completes. Such callbacks were registered on the device by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). The PnP manager also calls any user-mode components that registered for such notification by calling **RegisterDeviceNotification**. + +An **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** request must be handled first by the parent bus driver for a device and then by each higher driver in the device stack. A driver handles remove IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +A driver handles an **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** request with a procedure such as the following in its *DispatchPnP* routine: + +1. In a function or filter driver, postpone restarting the device until lower drivers have completed their restart operations. + + A function or filter driver sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, passes the **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** down the device stack, and postpones its restart operations until all lower drivers have finished with the IRP. (See [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md).) + +2. After lower drivers finish, return the device to its previous PnP state. + + The drivers return the device to the state it was in prior to receiving the **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request. Typically, drivers return the device to the started state. Exact operations depend on the device and the driver. + + If the device was previously enabled for wake-up, the device power policy owner (typically the function driver) should send an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) request to reenable wake-up. See [Power Management](implementing-power-management.md) for details. + +3. Set **Irp->IoStatus.Status** to STATUS\_SUCCESS and complete the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + As with any PnP IRP, a bus driver completes the IRP. + + A function or filter driver also completes the IRP, in this case because the driver's *IoCompletion* routine interrupted completion processing by returning STATUS\_MORE\_PROCESSING\_REQUIRED. + + Drivers must succeed this IRP. If any driver fails this IRP, the device is left in an inconsistent state. + +A driver might receive a spurious cancel-remove request when the device is started and active. This can occur, for example, if the driver (or a driver higher in the device stack) failed an **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request. When a device is started and active, a driver simply succeeds a spurious cancel-remove request for the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_CANCEL_REMOVE_DEVICE%20Request%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-2000-and-later-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-2000-and-later-.md new file mode 100644 index 0000000000..5f3afd415f --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-2000-and-later-.md @@ -0,0 +1,62 @@ +--- +title: Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 2000 and later) +author: windows-driver-content +description: Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 2000 and later) +ms.assetid: 2e5e835f-d327-4bde-bdfd-8a71a47b0ac0 +keywords: ["IRP_MN_CANCEL_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_CANCEL\_STOP\_DEVICE Request (Windows 2000 and later) + + +## + + +An [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826) request must be handled first by the parent bus driver for a device and then by each next higher driver in the device stack. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +In response to an **IRP\_MN\_CANCEL\_STOP\_DEVICE** request, a driver must return the device to its started state and resume normal operation. Drivers must succeed a cancel-stop IRP. + +A driver handles an **IRP\_MN\_CANCEL\_STOP\_DEVICE** request with a procedure such as the following: + +1. Postpone restarting the device until lower drivers have completed their restart operations. (See [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md).) + +2. After lower drivers finish, return the device to its started state. + + Exact operations depend on the device and the driver. + +3. Start IRPs in the IRP-holding queue. + + If the driver was holding requests while the device was in the stop-pending state, clear the HOLD\_NEW\_REQUESTS flag and start the IRPs in the IRP-holding queue. See [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md) for more information. + +4. Complete the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + - In a function or filter driver: + + The driver's [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine returned STATUS\_MORE\_PROCESSING\_REQUIRED, as described in [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md), so the driver's *DispatchPnP* routine must call **IoCompleteRequest** to resume I/O completion processing. + + The driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS, calls **IoCompleteRequest** with a priority boost of IO\_NO\_INCREMENT, and returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + Drivers must not fail this operation. If a driver fails the restart IRP, the device is in an inconsistent state and will not operate properly. + + - In a parent bus driver: + + The driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS and calls **IoCompleteRequest** specifying a priority boost of IO\_NO\_INCREMENT. The bus driver returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + A bus driver must not fail this operation. If a driver fails the restart IRP, the device is in an inconsistent state and will not operate properly. + +A driver might receive a spurious cancel-stop request when the device is started and active. This can occur, for example, if the driver (or a driver higher in the device stack) failed an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request. When a device is started and active, drivers can safely succeed spurious cancel-stop requests for the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_CANCEL_STOP_DEVICE%20Request%20%28Windows%202000%20and%20later%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-98-me-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-98-me-.md new file mode 100644 index 0000000000..ff97dc5cd7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-cancel-stop-device-request--windows-98-me-.md @@ -0,0 +1,60 @@ +--- +title: Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 98/Me) +author: windows-driver-content +description: Handling an IRP_MN_CANCEL_STOP_DEVICE Request (Windows 98/Me) +ms.assetid: 04365c65-a68a-48fc-9f7a-bb005518be5b +keywords: ["IRP_MN_CANCEL_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_CANCEL\_STOP\_DEVICE Request (Windows 98/Me) + + +## + + +An [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826) request must be handled first by the parent bus driver for a device and then by each next higher driver in the device stack. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +In response to an **IRP\_MN\_CANCEL\_STOP\_DEVICE** request, a driver must return the device to its started state and resume normal operation. Drivers must succeed a cancel-stop IRP. + +A driver handles an **IRP\_MN\_CANCEL\_STOP\_DEVICE** request with a procedure such as the following: + +1. Postpone restarting the device until lower drivers have completed their restart operations. (See [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md).) + +2. After lower drivers finish, return the device to its started state. + + Exact operations depend on the device and the driver. + +3. Restart I/O. + +4. Complete the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + - In a function or filter driver: + + The driver's *IoCompletion* routine returned STATUS\_MORE\_PROCESSING\_REQUIRED, as described in [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md), so the driver's *DispatchPnP* routine must call **IoCompleteRequest** to resume I/O completion processing. + + The driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS, calls **IoCompleteRequest** with a priority boost of IO\_NO\_INCREMENT, and returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + Drivers must not fail this operation. If a driver fails the restart IRP, the device is in an inconsistent state and will not operate properly. + + - In a parent bus driver: + + The driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS and calls **IoCompleteRequest** specifying a priority boost of IO\_NO\_INCREMENT. The bus driver returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + A bus driver must not fail this operation. If a driver fails the restart IRP, the device is in an inconsistent state and will not operate properly. + +A driver might receive a spurious cancel-stop request when the device is started and active. This can occur, for example, if the driver (or a driver higher in the device stack) failed an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request. When a device is started and active, drivers can safely succeed spurious cancel-stop requests for the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_CANCEL_STOP_DEVICE%20Request%20%28Windows%2098/Me%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-remove-device-request.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-remove-device-request.md new file mode 100644 index 0000000000..63abcc269c --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-remove-device-request.md @@ -0,0 +1,104 @@ +--- +title: Handling an IRP_MN_QUERY_REMOVE_DEVICE Request +author: windows-driver-content +description: Handling an IRP_MN_QUERY_REMOVE_DEVICE Request +ms.assetid: 30177e51-5312-4a24-972e-0c1c2d183d18 +keywords: ["IRP_MN_QUERY_REMOVE_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_QUERY\_REMOVE\_DEVICE Request + + +## + + +The PnP manager sends this IRP to inform drivers that a device is about to be removed from the machine and to ask whether the device can be removed without disrupting the machine. It also sends this IRP when a user requests to update drivers for the device. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +It does the following before sending this IRP to the drivers for a device: + +- Notifies all user-mode applications that registered for notification on the device (or a related device). + + This includes applications that registered for notification on the device, on one of the device's descendants (child device, child of child, and so forth), or on one of the device's removal relations. An application registers for such notification by calling **RegisterDeviceNotification**. + + In response to this notification, an application either prepares for device removal (closes handles to the device) or fails the query. + +- Notifies all kernel-mode drivers that registered for notification on the device (or a related device). + + This includes drivers that registered for notification on the device, on one of the device's descendants, or on one of the device's removal relations. A driver registers for this notification by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) with an event category of **EventCategoryTargetDeviceChange**. + + In response to this notification, a driver either prepares for device removal (closes handles to the device) or fails the query. + +- Sends [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) IRPs to the drivers for the device's descendants. + +- (Windows 2000 and later systems) If a file system is mounted on the device, the PnP manager sends a query-remove request to the file system and any file system filters. If there are open handles to the device, the file system typically fails the query-remove request. If not, the file system typically locks the volume to prevent future creates from succeeding. If a mounted file system does not support a query-remove request, the PnP manager fails the query-remove request for the device. + +If all of the above steps succeed, the PnP manager sends the **IRP\_MN\_QUERY\_REMOVE\_DEVICE** to the drivers for the device. + +An **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request is handled first by the top driver in the device stack and then by each next lower driver. A driver handles remove IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +In response to an **IRP\_MN\_QUERY\_REMOVE\_DEVICE**, a driver must do the following: + +1. Determine whether the device can be removed from the machine without disrupting operation. + + A driver must fail a query-remove IRP if any of the following are true: + + - If removing the device could result in losing data. + + - If a component has an open handle to the device. (This is an issue on Windows 98/Me only. Windows 2000 and later versions of Windows track open handles and fail the query if there are open handles after the **IRP\_MN\_QUERY\_REMOVE\_DEVICE** completes.) + + - If a driver has been notified (through an [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841) IRP) that the device is in the path for a paging, crash dump, or hibernation file. + + - If the driver has an outstanding interface reference against the device. That is, the driver provided an interface in response to an [**IRP\_MN\_QUERY\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff551687) request and the interface has not been dereferenced. + +2. If the device cannot be removed, fail the query-remove IRP. + + Set **Irp->IoStatus.Status** to an appropriate error status (typically STATUS\_UNSUCCESSFUL), call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with IO\_NO\_INCREMENT, and return from the driver's *DispatchPnP* routine. Do not pass the IRP to the next lower driver. + +3. If the driver previously sent an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) request to enable the device for wake-up, cancel the wait-wake IRP. + +4. Record the previous PnP state of the device. + + A driver should record the PnP state that the device was in when the driver received the [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) request because the driver must return the device to that state if the query is canceled ([**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550823)). The previous state is typically "started", which is the state that the device enters when the driver successfully completes an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. + + However, other previous states are possible. For example, the user might have disabled the device through Device Manager. Or, in response to an **IRP\_MN\_QUERY\_CAPABILITIES** request, the parent bus driver (or a filter driver on the bus driver) might have reported that the device's hardware is disabled. In either case, the driver for the disabled device can receive an **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request before it receives an **IRP\_MN\_START\_DEVICE** request. + +5. Finish the IRP: + + In a function or filter driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + - Propagate the status from **IoCallDriver** as the return status from the *DispatchPnP* routine. + + - Do not complete the IRP. + + In a bus driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with IO\_NO\_INCREMENT. + + - Return from the *DispatchPnP* routine. + +If any driver in the device stack fails an **IRP\_MN\_QUERY\_REMOVE\_DEVICE**, the PnP manager sends an **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** to the device stack. This prevents drivers from requiring an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for a query-remove IRP to detect whether a lower driver failed the IRP. + +Once a driver succeeds an **IRP\_MN\_QUERY\_REMOVE\_DEVICE** and it considers the device to be in the remove-pending state, the driver must fail any subsequent create requests for the device. The driver processes all other IRPs as usual, until the driver receives an **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** or an **IRP\_MN\_REMOVE\_DEVICE**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_QUERY_REMOVE_DEVICE%20Request%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-2000-and-later-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-2000-and-later-.md new file mode 100644 index 0000000000..ab1192c09f --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-2000-and-later-.md @@ -0,0 +1,109 @@ +--- +title: Handling an IRP_MN_QUERY_STOP_DEVICE Request (Windows 2000 and later) +author: windows-driver-content +description: Handling an IRP_MN_QUERY_STOP_DEVICE Request (Windows 2000 and later) +ms.assetid: 668a920c-aadb-405a-9a1d-091982ca2c04 +keywords: ["IRP_MN_QUERY_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_QUERY\_STOP\_DEVICE Request (Windows 2000 and later) + + +## + + +An [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request is handled first by the top driver in the device stack and then by each next lower driver. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +In response to an **IRP\_MN\_QUERY\_STOP\_DEVICE**, a driver must do the following: + +1. Determine whether the device can be stopped, and its hardware resources released, without adverse affects. + + A driver must fail a query-stop IRP if any of the following are true: + + - A driver has been notified (through [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841)) that the device is in the path of a paging, hibernation, or crash dump file. + + - The device's hardware resources cannot be released. + + A driver might fail a query-stop IRP if the following is true: + + - The driver must not drop I/O requests and does not have a mechanism for queuing IRPs. + + While the device is in the stopped state, a driver must hold IRPs that require access to the device. If a driver does not queue IRPs, it must not allow the device to be stopped and thus must fail a query-stop IRP. + + The exception to this rule is a device that is allowed to drop I/O. The drivers for such a device can succeed query-stop and stop requests without queuing IRPs. + +2. If the device cannot be stopped, fail the query-stop IRP. + + Set **Irp->IoStatus.Status** to an appropriate error status, call **IoCompleteRequest** with IO\_NO\_INCREMENT, and return from the driver's *DispatchPnP* routine. Do not pass the IRP to the next lower driver. + +3. If the device can be stopped and the driver queues IRPs, set the HOLD\_NEW\_REQUESTS flag in the device extension so subsequent IRPs will be queued (see [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md)). + + Alternatively, the drivers for a device can defer completely pausing the device until the drivers receive the subsequent [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request. Such drivers, however, must queue any requests that would prevent them from immediately succeeding the stop IRP when it arrives. Until the device is restarted, such drivers must queue requests such as the following: + + - [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841) requests (for example, to put a paging file on the device). + + - Requests for isochronous transfers. + + - Create requests that would prevent the drivers from succeeding a stop IRP. + +4. If the device cannot have an IRP in progress fail, ensure that any outstanding requests that were passed to other driver routines and to lower drivers have completed. + + One way that a driver can achieve this is to use a reference count and an event to ensure that all requests have been completed: + + - In its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, the driver defines an I/O reference count in the device extension and initializes the count to one. + + - Also in its *AddDevice* routine, the driver creates an event with [**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137) and initializes the event to the Not-Signaled state with [**KeClearEvent**](https://msdn.microsoft.com/library/windows/hardware/ff551980). + - Each time it processes an IRP, the driver increments the reference count with [**InterlockedIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff547910). + + - Each time it completes a request, the driver decrements the reference count with [**InterlockedDecrement**](https://msdn.microsoft.com/library/windows/hardware/ff547871). + + The driver decrements the reference count in the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, if the request has one, or right after the call to [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) if the driver uses no *IoCompletion* routine for the request. + + - When the driver receives an **IRP\_MN\_QUERY\_STOP\_DEVICE**, it decrements the reference count with **InterlockedDecrement**. If there are no outstanding requests, this reduces the reference count to zero. + + - When the reference count reaches zero, the driver sets the event with [**KeSetEvent**](https://msdn.microsoft.com/library/windows/hardware/ff553253) signaling that the query-stop code can continue. + + As an alternative to the above procedure, a driver can serialize the **IRP\_MN\_QUERY\_STOP\_DEVICE** IRP behind any IRPs in progress. + +5. Perform any other steps required to put the device in the stop-pending state. + + After a driver succeeds a query-stop IRP, it must be ready to succeed an **IRP\_MN\_STOP\_DEVICE**. + +6. Finish the IRP. + + In a function or filter driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + - Propagate the status from **IoCallDriver** as the return status from the *DispatchPnP* routine. + + - Do not complete the IRP. + + In a bus driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + If, however, the devices on the bus use hardware resources, reevaluate the resource requirements of the bus and the child devices. If any of the requirements have changed, return STATUS\_RESOURCE\_REQUIREMENTS\_CHANGED instead of STATUS\_SUCCESS. This status indicates success but requests that the PnP manager requery your resources before sending the stop IRP. + + - Complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with IO\_NO\_INCREMENT. + + - Return from the *DispatchPnP* routine. + +If any driver in the device stack fails the **IRP\_MN\_QUERY\_STOP\_DEVICE**, the PnP manager sends an [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826) to the device stack. This prevents drivers from requiring an *IoCompletion* routine for a query-stop IRP to detect whether a lower driver failed the IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_QUERY_STOP_DEVICE%20Request%20%28Windows%202000%20and%20later%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-98-me-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-98-me-.md new file mode 100644 index 0000000000..b07376d1d0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-query-stop-device-request--windows-98-me-.md @@ -0,0 +1,110 @@ +--- +title: Handling an IRP_MN_QUERY_STOP_DEVICE Request (Windows 98/Me) +author: windows-driver-content +description: Handling an IRP_MN_QUERY_STOP_DEVICE Request (Windows 98/Me) +ms.assetid: 2a12af98-c5ed-4a24-b957-b363683cc491 +keywords: ["IRP_MN_QUERY_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_QUERY\_STOP\_DEVICE Request (Windows 98/Me) + + +## + + +An [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request is handled first by the top driver in the device stack and then by each next lower driver. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +In response to an **IRP\_MN\_QUERY\_STOP\_DEVICE**, a driver must do the following: + +1. Determine whether the device can be stopped without adverse affects. + + A driver must fail a query-stop IRP if any of the following are true: + + - A driver has been notified (through [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841)) that the device is in the path of a paging, hibernation, or crash dump file. + + - The device's hardware resources cannot be released. + + - There are open handles to the device. + + A driver might fail a query-stop IRP if the following is true: + + - The driver must not drop I/O requests. + +2. If the device cannot be stopped, fail the query-stop IRP. + + Set **Irp->IoStatus.Status** to an appropriate error status, call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with IO\_NO\_INCREMENT, and return from the driver's [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. Do not pass the IRP to the next lower driver. + +3. If the device can be stopped, call [**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700) and [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) to disable and deregister any user-mode interfaces. Then start failing any incoming I/O requests that require access to the device. + + Alternatively, the drivers for a device can defer completely pausing the device until the drivers receive the subsequent **IRP\_MN\_STOP\_DEVICE** request. Such drivers, however, should disable and deregister their user-mode interfaces while handling the query-stop request to prevent the opening of any additional handles to the device. + + Furthermore, such drivers must fail any requests that would prevent them from immediately succeeding the stop IRP when it arrives. Until the device is restarted, such drivers must fail requests such as the following: + + - **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** requests (for example, to put a paging file on the device). + + - Requests for isochronous transfers. + + - Create requests that would prevent the drivers from succeeding a stop IRP. + +4. If the device cannot allow an IRP in progress to fail, ensure that any outstanding requests that were passed to other driver routines and to lower drivers have completed. + + One way that a driver can achieve this is to use a reference count and an event to ensure that all requests have been completed: + + - In its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, the driver defines an I/O reference count in the device extension and initializes the count to one. + + - Also in its *AddDevice* routine, the driver creates an event with [**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137) and initializes the event to the Not-Signaled state with [**KeClearEvent**](https://msdn.microsoft.com/library/windows/hardware/ff551980). + + - Each time it processes an IRP, the driver increments the reference count with [**InterlockedIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff547910). + + - Each time it completes a request, the driver decrements the reference count with [**InterlockedDecrement**](https://msdn.microsoft.com/library/windows/hardware/ff547871). + + The driver decrements the reference count in the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, if the request has one, or immediately after the call to [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) if the driver uses no *IoCompletion* routine for the request. + + - When the driver receives an **IRP\_MN\_QUERY\_STOP\_DEVICE**, it decrements the reference count with **InterlockedDecrement**. If there are no outstanding requests, this reduces the reference count to zero. + + - When the reference count reaches zero, the driver sets the event with [**KeSetEvent**](https://msdn.microsoft.com/library/windows/hardware/ff553253) signaling that the query-stop code can continue. + + As an alternative to the above procedure, a driver can serialize the **IRP\_MN\_QUERY\_STOP\_DEVICE** IRP behind any IRPs in progress. + +5. Perform any other steps required to put the device in the stop-pending state. + + After a driver succeeds a query-stop IRP, it must be ready to succeed an **IRP\_MN\_STOP\_DEVICE**. + +6. Finish the IRP. + + In a function or filter driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + - Propagate the status from **IoCallDriver** as the return status from the *DispatchPnP* routine. + + - Do not complete the IRP. + + In a bus driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + If, however, the devices on the bus use hardware resources, reevaluate the resource requirements of the bus and the child devices. If any of the requirements have changed, return STATUS\_RESOURCE\_REQUIREMENTS\_CHANGED instead of STATUS\_SUCCESS. This status indicates success but requests that the PnP manager requery your resources before sending the stop IRP. + + - Complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with IO\_NO\_INCREMENT. + + - Return from the *DispatchPnP* routine. + +If any driver in the device stack fails the **IRP\_MN\_QUERY\_STOP\_DEVICE**, the PnP manager sends an [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826) to the device stack. This prevents drivers from requiring an *IoCompletion* routine for a query-stop IRP to detect whether a lower driver failed the IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_QUERY_STOP_DEVICE%20Request%20%28Windows%2098/Me%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-remove-device-request.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-remove-device-request.md new file mode 100644 index 0000000000..62df65e5fb --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-remove-device-request.md @@ -0,0 +1,54 @@ +--- +title: Handling an IRP_MN_REMOVE_DEVICE Request +author: windows-driver-content +description: Handling an IRP_MN_REMOVE_DEVICE Request +ms.assetid: 1e0c8b41-5375-41dd-80eb-e48c0f513e01 +keywords: ["IRP_MN_REMOVE_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_REMOVE\_DEVICE Request + + +## + + +The PnP manager uses this IRP to direct drivers to remove a device's software representation (device objects, and so forth). The PnP manager sends this IRP when a device has been removed in an orderly fashion (for example, initiated by a user in the Unplug or Eject Hardware program), by surprise (a user pulls the device from its slot without prior warning), or when the user requests to update drivers. + +On Windows 2000 and later systems, the PnP manager sends this IRP when Device Manager disables the device. On Windows 98/Me, the PnP manager sends stop IRPs instead. See [Stopping a Device](stopping-a-device.md) for details. + +The PnP manager does the following before sending this IRP to the drivers for a device: + +- Sends **IRP\_MN\_REMOVE\_DEVICE** requests to the device's children, if any. + +- Notifies any user-mode components and kernel-mode drivers that registered for notification that the device is being removed. The PnP manager calls any user-mode components that registered for target device notification on a handle to the device and calls any kernel-mode drivers that registered for **EventCategoryTargetDeviceChange**. + +- (On Windows 2000 and later systems) If a file system is mounted on the device, the PnP manager sends a remove request to the file system and any file system filters. In response, a file system typically dismounts the volume. + +The top driver in a device stack handles a remove IRP and passes it to the next lower driver. The parent bus driver for a device is the last driver to perform its remove-device operations. A driver handles remove IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +Before a driver returns success for an **IRP\_MN\_REMOVE\_DEVICE** request, it must ensure that all resources for the device have been released. This IRP could be the last call before the driver is unloaded. + +Removing one device can create the need to remove a series of other devices. The PnP manager coordinates the removal of the additional device objects from the top level down to the root-device level. + +This section describes: + +[Removing a Device in a Function Driver](removing-a-device-in-a-function-driver.md) + +[Removing a Device in a Filter Driver](removing-a-device-in-a-filter-driver.md) + +[Removing a Device in a Bus Driver](removing-a-device-in-a-bus-driver.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_REMOVE_DEVICE%20Request%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-2000-and-later-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-2000-and-later-.md new file mode 100644 index 0000000000..14328c609e --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-2000-and-later-.md @@ -0,0 +1,54 @@ +--- +title: Handling an IRP_MN_STOP_DEVICE Request (Windows 2000 and later) +author: windows-driver-content +description: Handling an IRP_MN_STOP_DEVICE Request (Windows 2000 and later) +ms.assetid: 5e91748c-d03a-48f7-a9cc-df2801d8a555 +keywords: ["IRP_MN_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_STOP\_DEVICE Request (Windows 2000 and later) + + +## + + +An [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request is handled first by the top driver in the device stack and then by each next lower driver. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +A driver handles an **IRP\_MN\_STOP\_DEVICE** request with a procedure such as the following: + +1. Ensure that the device is paused. + + If a driver did not completely pause the device in response to the [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request, it must do so now. Set a HOLD\_NEW\_REQUESTS flag in the device extension and perform any other necessary operations to pause the device. + + The device might lose power during the resource-rebalance operation and thus might lose device state. Drivers for the device should save any device state information and restore it when they receive the subsequent [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. + +2. Release the hardware resources for the device. + + In a function driver, the exact operations depend on the device and the driver but can include disconnecting an interrupt with [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089), freeing physical address ranges with [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387), and freeing I/O ports. + + If a filter or bus driver acquired any hardware resources for the device, that driver must release the resources in response to an **IRP\_MN\_STOP\_DEVICE** request. + +3. Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + +4. Pass the IRP to the next lower driver or complete the IRP. + + - In a function or filter driver, set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355), pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336), and return the status from **IoCallDriver** as the return status from the *DispatchPnP* routine. Do not complete the IRP. + + - In a bus driver, complete the IRP using [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with IO\_NO\_INCREMENT and return from the *DispatchPnP* routine. + +While the device is stopped to rebalance resources, a driver cannot start any IRPs that access the device. A driver must queue such IRPs, as described in [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md), or fail them if the driver does not implement an IRP-holding queue and must not drop I/O requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_STOP_DEVICE%20Request%20%28Windows%202000%20and%20later%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-98-me-.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-98-me-.md new file mode 100644 index 0000000000..7817b52007 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-stop-device-request--windows-98-me-.md @@ -0,0 +1,56 @@ +--- +title: Handling an IRP_MN_STOP_DEVICE Request (Windows 98/Me) +author: windows-driver-content +description: Handling an IRP_MN_STOP_DEVICE Request (Windows 98/Me) +ms.assetid: 8e44561a-f494-48ce-ab61-aa47cd4e1c64 +keywords: ["IRP_MN_STOP_DEVICE"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_STOP\_DEVICE Request (Windows 98/Me) + + +## + + +On Windows 98/Me, the PnP manager usually sends an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request after a successful query-stop. However, if the device stack previously failed an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, the PnP manager sends an **IRP\_MN\_STOP\_DEVICE** request without a preceding query. + +An **IRP\_MN\_STOP\_DEVICE** request is handled first by the top driver in the device stack and then by each next lower driver. A driver handles stop IRPs in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +A driver handles an **IRP\_MN\_STOP\_DEVICE** request with a procedure such as the following: + +1. Ensure that the device is paused. + + If a driver did not completely pause the device in response to an [**IRP\_MN\_QUERY\_STOP**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request, it must do so now. + + The device might lose power while it is stopped and thus might lose device state. Drivers for the device should save any device state information and restore it when they receive the subsequent **IRP\_MN\_START\_DEVICE** request. + +2. Release the hardware resources for the device. + + In a function driver, the exact operations depend on the device and the driver but can include disconnecting an interrupt with [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089), freeing physical address ranges with [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387), and freeing I/O ports. + + If a filter or bus driver acquired any hardware resources for the device, that driver must release the resources in response to an **IRP\_MN\_STOP\_DEVICE** request. + +3. Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + +4. Pass the IRP to the next lower driver or complete the IRP. + + - In a function or filter driver, set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355), pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336), and return the status from **IoCallDriver** as the return status from the *DispatchPnP* routine. Do not complete the IRP. + + - In a bus driver, complete the IRP using [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with IO\_NO\_INCREMENT and return from the *DispatchPnP* routine. + +A driver cannot start any IRPs that access the device while the device is stopped. A driver must fail such IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_STOP_DEVICE%20Request%20%28Windows%2098/Me%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-an-irp-mn-surprise-removal-request.md b/windows-driver-docs-pr/kernel/handling-an-irp-mn-surprise-removal-request.md new file mode 100644 index 0000000000..82c6e3c22d --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-an-irp-mn-surprise-removal-request.md @@ -0,0 +1,116 @@ +--- +title: Handling an IRP_MN_SURPRISE_REMOVAL Request +author: windows-driver-content +description: Handling an IRP_MN_SURPRISE_REMOVAL Request +ms.assetid: 39a90617-40ad-4c10-95d3-2b618d66d70e +keywords: ["surprise removals WDK PnP", "IRP_MN_SURPRISE_REMOVAL"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling an IRP\_MN\_SURPRISE\_REMOVAL Request + + +## + + +The Windows 2000 and later PnP manager sends this IRP to notify drivers that a device is no longer available for I/O operations and has probably been unexpectedly removed from the machine ("surprise removal"). + +The PnP manager sends an [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request for the following reasons: + +- If the bus has hot-plug notification, it notifies the device's parent bus driver that the device has disappeared. The bus driver calls [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353). In response, the PnP manager queries the bus driver for its children ([**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) for **BusRelations**). The PnP manager determines that the device is not in the new list of children and initiates its surprise-removal operations for the device. + +- The bus is enumerated for another reason and the surprise-removed device is not included in the list of children. The PnP manager initiates its surprise removal operations. + +- The function driver for the device determines that the device is no longer present (because, for example, its requests repeatedly time out). The bus might be enumerable but it does not have hot-plug notification. In this case, the function driver calls [**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361). In response, the PnP manager sends an [**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff551698) request to the device stack. The function driver sets the PNP\_DEVICE\_FAILED flag in the [**PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff559618) bitmask indicating that the device has failed. + +- The driver stack successfully completes an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request but then fails a subsequent [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. In such cases, the device is probably still connected. + +All PnP drivers must handle this IRP and must set **Irp->IoStatus.Status** to STATUS\_SUCCESS. A driver for a PnP device must be prepared to handle **IRP\_MN\_SURPRISE\_REMOVAL** at any time after the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine is called. Proper handling of the IRP enables the drivers and the PnP manager to: + +1. Disable the device, in case it is still connected. + + If the driver stack successfully completed an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request but then, for some reason, failed a subsequent [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, the device must be disabled. + +2. Release hardware resources assigned to the device and make them available to another device. + + As soon as a device is no longer available, its hardware resources should be freed. The PnP manager can then reassign the resources to another device, including the same device, which a user might hot-plug back into the machine. + +3. Minimize the risk of data loss and system disruption. + + Devices that support hot-plugging and their drivers should be designed to handle surprise removal. Users expect to be able to remove devices that support hot-plugging at any time. + +The PnP manager sends an **IRP\_MN\_SURPRISE\_REMOVAL** at IRQL = PASSIVE\_LEVEL in the context of a system thread. + +The PnP manager sends this IRP to drivers before notifying user-mode applications and other kernel-mode components. After the IRP completes, the PnP manager sends an **EventCategoryTargetDeviceChange** notification with GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE to kernel-mode components that registered for such notification on the device. + +The **IRP\_MN\_SURPRISE\_REMOVAL** IRP is handled first by the top driver in the device stack and then by each next lower driver. + +In response to **IRP\_MN\_SURPRISE\_REMOVAL**, a driver must do the following, in the listed order: + +1. Determine if the device has been removed. + + The driver must always attempt to determine if the device is still connected. If it is, the driver must attempt to stop the device and disable it. + +2. Release the device's hardware resources (interrupts, I/O ports, memory registers, and DMA channels). + +3. In a parent bus driver, power down the bus slot if the driver is capable of doing so. Call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager. For additional information, see [Power Management](implementing-power-management.md). + +4. Prevent any new I/O operations on the device. + + A driver should process subsequent [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718), [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720), [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784), and [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) requests, but the driver must prevent any new I/O operations. A driver must fail any subsequent IRPs that the driver would have handled if the device were present, besides close, clean-up, and PnP IRPs. + + A driver can set a bit in the device extension to indicate that the device has been surprise-removed. The driver's dispatch routines should check this bit. + +5. Fail outstanding I/O requests on the device. + +6. Continue to pass down any IRPs that the driver does not handle for the device. + +7. Disable device interfaces with [**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700). + +8. Clean up any device-specific allocations, memory, events, or other system resources. + + A driver could postpone such clean-up until it receives the subsequent [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request, but if a legacy component has an open handle that cannot be closed, the remove IRP will never be sent. + +9. Leave the device object attached to the device stack. + + Do not detach and delete the device object until the subsequent **IRP\_MN\_REMOVE\_DEVICE** request. + +10. Finish the IRP. + + In a function or filter driver: + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + - Propagate the status from **IoCallDriver** as the return status from the [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + + - Do not complete the IRP. + + In a bus driver (that is handling this IRP for a child PDO): + + - Set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with IO\_NO\_INCREMENT. + + - Return from the *DispatchPnP* routine. + +After this IRP succeeds and all open handles to the device are closed, the PnP manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request to the device stack. In response to the remove IRP, drivers detach their device objects from the stack and delete them. If a legacy component has a handle open to the device and it leaves the handle open despite I/O failures, the PnP manager never sends the remove IRP. + +All drivers should handle this IRP and should note that the device has been physically removed from the machine. Some drivers, however, will not cause adverse results if they do not handle the IRP. For example, a device that consumes no system hardware resources and resides on a protocol-based bus, such as USB or 1394, cannot tie up hardware resources because it does not consume any. There is no risk of drivers attempting to access the device after it has been removed because the function and filter drivers access the device only through the parent bus driver. Because the bus supports removal notification, the parent bus driver is notified when the device disappears and the bus driver fails all subsequent attempts to access the device. + +On Windows 98/Me, the PnP manager does not send this IRP. If a user removes a device without first using the appropriate user interface, the PnP manager sends only an **IRP\_MN\_REMOVE\_DEVICE** request to the drivers for the device. All WDM drivers must handle both **IRP\_MN\_SURPRISE\_REMOVAL** and **IRP\_MN\_REMOVE\_DEVICE**. The code for **IRP\_MN\_REMOVE\_DEVICE** should check whether the driver received a prior surprise-remove IRP and should handle both cases. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20an%20IRP_MN_SURPRISE_REMOVAL%20Request%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-commit-operations.md b/windows-driver-docs-pr/kernel/handling-commit-operations.md new file mode 100644 index 0000000000..d72979f3ba --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-commit-operations.md @@ -0,0 +1,119 @@ +--- +title: Handling Commit Operations +author: windows-driver-content +description: Handling Commit Operations +ms.assetid: 4885476e-ce68-4674-b8a5-8a317f33cd5b +keywords: ["transactions WDK KTM , committing transactions", "committing transactions WDK KTM", "resource managers WDK KTM , committing transactions", "single-phase commit WDK KTM , multi-phase commit WDK KTM", "pre-prepare phase WDK KTM", "prepare phase WDK KTM", "commit phase WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Commit Operations + + +There are two types of commit operations: *single-phase commit* and *multi-phase commit*. A single-phase commit operation consists of a single notification that resource managers must respond to, while a multi-phase commit operation includes additional notifications for preparation steps. + +A single-phase commit operation is simpler to implement. It is appropriate for transaction processing systems (TPSs) that have one of the following characteristics: + +- A single resource manager. + +- Multiple resource managers, all but one of which are [read-only](creating-a-resource-manager.md#kernel-creating-a-read-only-enlistment) and do not participate in the commit operation. + +A multi-phase commit operation is necessary if multiple resource managers participate in the commit operation. + +### Single-Phase Commit Operations + +If you want your TPS to support single-phase commit operations, one (and only one) resource manager must register to receive TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT [notifications](transaction-notifications.md) for its enlistments. All other resource managers must be [read-only](creating-a-resource-manager.md#kernel-creating-a-read-only-enlistment). + +A TPS that includes a [superior transaction manager](creating-a-superior-transaction-manager.md) cannot use single-phase commit. + +If a resource manager has registered to receive TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT notifications, KTM sends this kind of notification when a transactional client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420). + +When the resource manager receives a TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT notification for a transaction, it can either commit the transaction or reject single-phase commit. + +To commit the transaction, the resource manager must do the following: + +1. Flush any data that it is holding in a non-permanent cache (in-memory storage), such as the [CLFS marshalling area](clfs-marshalling-areas.md) for a [CLFS log stream](using-log-streams-with-ktm.md). + + The resource manager must move the data from the cache to a durable storage medium. For example, a resource manager that is using CLFS can call [**ClfsFlushBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff541544). + +2. Make all data changes permanent and public (that is, visible outside the resource manager's scope). + +3. Call [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418). + +After calling **ZwCommitComplete**, the resource manager should call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the enlistment handle. + +To reject a single-phase commit operation for the transaction, the resource manager can call [**ZwSinglePhaseReject**](https://msdn.microsoft.com/library/windows/hardware/ff567113). If the resource manager calls **ZwSinglePhaseReject**, KTM immediately changes the commit operation from single-phase to multi-phase. + +If other resource managers enlist in the same transaction, they must be [read-only](creating-a-resource-manager.md#kernel-creating-a-read-only-enlistment). However, they must register to receive the TRANSACTION\_NOTIFY\_RM\_DISCONNECTED notification, which they receive if the resource manager that is handling the single-phase commit operation closes the enlistment handle without indicating that it has committed or rolled back the transaction. + +### Multi-Phase Commit Operations + +A multi-phase commit operation begins when one of the following events happens: + +- A transactional client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420), and no resource managers have registered to receive TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT notifications. + +- A resource manager calls [**ZwSinglePhaseReject**](https://msdn.microsoft.com/library/windows/hardware/ff567113) after it has received a TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT notification. + +- A [superior transaction manager](creating-a-superior-transaction-manager.md) calls [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044). + +Multi-phase commit operations consist of three sequential phases: *pre-prepare*, *prepare*, and *commit*. + +**Pre-Prepare Phase** + +The pre-prepare phase (also known as *phase zero*) of the commit operation begins when KTM sends a TRANSACTION\_NOTIFY\_PREPREPARE notification to all resource managers. KTM sends this notification if no resource managers support a single-phase commit operation for the transaction, or if a superior transaction manager calls [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044). + +When each resource manager receives the TRANSACTION\_NOTIFY\_PREPREPARE notification, it must do the following: + +1. Flush any data that it is holding in a non-permanent cache (in-memory storage), such as the [CLFS marshalling area](clfs-marshalling-areas.md) for a [CLFS log stream](using-log-streams-with-ktm.md). + + The resource manager must move the data from the cache to a durable storage medium. For example, a resource manager that is using CLFS can call [**ClfsFlushBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff541544). + +2. Call [**ZwPrePrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567040). + +After a resource manager has called **ZwPreprepareComplete**, it can continue to receive and service client requests. But the resource manager must treat all data modifications as cache pass-through operations that are immediately written to a durable storage medium. + +If a resource manager encounters an error while it is processing a TRANSACTION\_NOTIFY\_PREPREPARE notification, it should call [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083) to roll back the transaction. + +**Prepare Phase** + +The prepare phase (also known as *phase one*) of the commit operation begins when KTM sends a TRANSACTION\_NOTIFY\_PREPARE notification to all resource managers. KTM sends this notification after TRANSACTION\_NOTIFY\_PREPREPARE if no resource managers support single-phase commit or if a superior transaction manager calls [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039). + +When each resource manager receives the TRANSACTION\_NOTIFY\_PREPARE notification, it must do the following: + +1. Stop servicing client requests and report any client subsequent requests as client errors. + +2. Make sure that all data has been moved to durable storage. + +3. Call [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037). + +If a resource manager encounters an error while it is processing a TRANSACTION\_NOTIFY\_PREPARE notification, it should call [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083) to roll back the transaction. However, the resource manager cannot roll back the transaction after it has called **ZwPrepareComplete**. + +**Commit Phase** + +The commit phase (also known as *phase two*) of the commit operation begins when KTM sends a TRANSACTION\_NOTIFY\_COMMIT notification to all resource managers. KTM sends this notification after TRANSACTION\_NOTIFY\_PREPARE if no resource managers support single-phase commit or if a superior transaction manager calls [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419). + +When each resource manager receives the TRANSACTION\_NOTIFY\_COMMIT notification, it must do the following: + +1. Make all data changes permanent and public (that is, visible to other transactions). + + Typically, a resource manager makes changes permanent and public by copying the transaction's saved data from the log stream to the database's public, permanent storage. For more information about how to use log streams, see [Using Log Streams with KTM](using-log-streams-with-ktm.md). + +2. Call [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418). + +After the resource manager calls **ZwCommitComplete**, it should call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the enlistment handle. + +If a resource manager encounters an error while it is processing a TRANSACTION\_NOTIFY\_COMMIT notification, it should shut itself down. The next time that the operating system reloads the resource manager, the resource manager's [recovery process](handling-recovery-operations.md) should restore the transaction to a state that was known to be good before the error occurred. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Commit%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-device-interface-change-events.md b/windows-driver-docs-pr/kernel/handling-device-interface-change-events.md new file mode 100644 index 0000000000..2b915ab2e3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-device-interface-change-events.md @@ -0,0 +1,44 @@ +--- +title: Handling Device Interface Change Events +author: windows-driver-content +description: Handling Device Interface Change Events +ms.assetid: 8966ca72-41d6-42bb-84a9-8f907a514338 +keywords: ["notifications WDK PnP , device interface changes", "EventCategoryDeviceInterfaceChange notification", "device interface change notifications WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Device Interface Change Events + + +## + + +When a driver or a user-mode component enables or disables a device interface instance, the PnP manager calls all notification callback routines that are registered for **EventCategoryDeviceInterfaceChange** events on the device interface class. To indicate the reason for the notification, the PnP manager sets the **Event** member of the callback routine's *NotificationStructure* parameter to GUID\_DEVICE\_INTERFACE\_ARRIVAL or GUID\_DEVICE\_INTERFACE\_REMOVAL. + +When handling a GUID\_DEVICE\_INTERFACE\_ARRIVAL event, a notification callback routine should: + +- Perform driver-defined tasks for handling the new interface. + + Typically, a notification callback routine directly opens the device in the context of the callback. However, if opening the device can cause subsequent PnP events to occur (for example, the enumeration of child devices), the callback routine should instead queue a worker routine to open the device; otherwise, a deadlock can occur. + + A callback routine might enable an interface of its own in response to the availability of the new interface. + +When handling a GUID\_DEVICE\_INTERFACE\_REMOVAL event, a notification callback routine should: + +- Undo whatever operations it performed when the interface was enabled. + +When the device is removed, the driver should close the file handle that it opened during the GUID\_DEVICE\_INTERFACE\_ARRIVAL event callback. For an orderly device removal, the driver should close the file handle during the GUID\_TARGET\_DEVICE\_QUERY\_REMOVE event callback. For a surprise removal, the driver should close the file handle during the GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE event callback. Do not close the file handle during the GUID\_DEVICE\_INTERFACE\_REMOVAL event callback. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Device%20Interface%20Change%20Events%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-device-power-down-irps.md b/windows-driver-docs-pr/kernel/handling-device-power-down-irps.md new file mode 100644 index 0000000000..5c8a118d97 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-device-power-down-irps.md @@ -0,0 +1,76 @@ +--- +title: Handling Device Power-Down IRPs +author: windows-driver-content +description: Handling Device Power-Down IRPs +ms.assetid: 2f4591d6-5bd0-45db-b02d-cf9dd59c3888 +keywords: ["set-power IRPs WDK kernel", "device set power IRPs WDK kernel", "power IRPs WDK kernel , device changes", "power-down IRPs WDK kernel", "context information WDK power management", "shutdown power management WDK kernel", "off power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Device Power-Down IRPs + + +## + + +A device power-down IRP specifies the minor function code [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) and a device power state (**PowerDeviceD0**, **PowerDeviceD1**, **PowerDeviceD2**, or **PowerDeviceD3**) that is less-powered or equal to the current device power state. Drivers must handle the power-down IRP as the IRP travels down the device stack. Higher-level drivers must handle the IRP before lower-level drivers. Drivers that have no device-specific tasks to perform should promptly pass the IRP to the next-lower driver. + +The following figure shows the steps involved in handling such an IRP. + +![diagram illustrating handling a device power-down request](images/devd3.png) + +If the IRP specifies **PowerDeviceD3**, the function driver should typically perform the following tasks: + +- Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP, to ensure that the driver does not receive a PnP [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, beginning with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP and then return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should call **IoCompleteRequest** to complete the IRP, then call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP, and then return the failure status. + +- Perform any device-specific tasks that must be done before device power is removed, such as closing the device, completing or flushing any pending I/O, disabling interrupts, [queuing subsequent incoming IRPs](queuing-i-o-requests-while-a-device-is-sleeping.md), and saving device context from which to restore or reinitialize the device. + + The driver should not cause a long delay (for example, a delay that a user might find unreasonable for this type of device) while handling the IRP. + + The driver should queue any incoming I/O requests until the device has returned to the working state. + +- Possibly check the value at **Parameters.Power.ShutdownType**. If a system set-power IRP is active, the **ShutdownType** provides information about the system IRP. For more information about this value, see [System Power Actions](system-power-actions.md). + + Drivers of devices on the hibernate path must inspect this value. If the **ShutdownType** is **PowerActionHibernate**, the driver should save any context required to restore the device but should not power down the device. + +- Change the physical power state of the device if the driver is capable of doing so and if the change is appropriate. + +- Call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager of the new device power state. + +- Call [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) to set up the stack location for the next-lower driver. + +- Set an *IoCompletion* routine that calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) that indicates that the driver is ready to handle the next power IRP. This step is not required in Windows 7 and Windows Vista. + +- Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or call [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP to the next-lower driver. The IRP must be passed all the way down to the bus driver, which completes the IRP. + +- Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to release the previously acquired lock. + +- Return STATUS\_PENDING. + +Drivers must save any device context information and set the new power state before forwarding the IRP. The context information should contain, at minimum, the requested new power state. It should also include any additional information the driver will need upon power-up. After the IRP has been completed and the device has been powered off, the driver can no longer access the device and device context is not available. + +Each driver must pass the IRP to the next-lower driver. When the IRP reaches the bus driver, the bus driver powers off the device (if it is capable of this), calls [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to inform the power manager, and completes the IRP. + +However, if the bus driver services the hibernation device, it should check whether the value of **ShutdownType** in the IRP is PowerSystemHibernate. If so, the bus driver should call **PoSetPowerState** to report PowerDeviceD3 but should not power down the device. The device will power down after the hibernate file is saved, along with the rest of the system. + +After all of its child devices power down, a bus driver might choose to power down its bus also. Such behavior is device-dependent. + +If the IRP specifies any other state (D0, D1 or D2), required driver actions are device-dependent. Typically, devices that support these states can quickly return to the working state when an I/O request arrives. A driver for such a device must complete any pending I/O requests, queue any new requests, and save all necessary context before forwarding the IRP to the next-lower driver. When the IRP reaches the bus driver, it sets the hardware in the requested state. A driver cannot access the device while it is asleep. + +Under some circumstances, a function or filter driver might receive a device power IRP specifying PowerDeviceD0 when the device is already in the D0 state. The driver should handle this IRP as it would any other set-power IRP: complete pending I/O requests, queue incoming I/O requests, set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, and pass the IRP down to the next-lower driver. A driver must not, however, change the device's hardware settings. When the bus driver receives the IRP, it should simply complete the IRP. When the IRP completes, function and filter drivers can handle any queued requests. Queuing I/O until the IRP completes eliminates any possibility of lower drivers attempting to change device registers while a higher driver attempts I/O. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Device%20Power-Down%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-device-power-up-irps.md b/windows-driver-docs-pr/kernel/handling-device-power-up-irps.md new file mode 100644 index 0000000000..a6c0e4bca5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-device-power-up-irps.md @@ -0,0 +1,60 @@ +--- +title: Handling Device Power-Up IRPs +author: windows-driver-content +description: Handling Device Power-Up IRPs +ms.assetid: 8fcfd324-97f9-4fd0-8fa1-87685c6b5ec3 +keywords: ["set-power IRPs WDK kernel", "device set power IRPs WDK kernel", "power IRPs WDK kernel , device changes", "power-up IRPs WDK kernel", "startup power management WDK kernel", "restoring power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Device Power-Up IRPs + + +## + + +Device power-up IRPs specify [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) and a device power state that requires more power than the current device power state. Typically, a power-up IRP specifies the device working state **PowerDeviceD0**. + +Requests to power up a device must be handled first by the underlying bus driver for the device, and then by each successive driver going back up the stack. + +The following figure shows the steps involved in handling a power-up IRP. + +![diagram illustrating handling a device power-up request](images/devd0.png) + +When handling an **IRP\_MN\_SET\_POWER** request for power-up, a function or filter driver must: + +- Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204) to ensure that the driver does not receive an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power-up IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, beginning with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP and then return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should call **IoCompleteRequest** to complete the IRP, then call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP, and then return the failure status. + +- Call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) to mark the IRP pending. + +- Call [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) to set the IRP stack location. A driver must not call **IoSkipCurrentIrpStackLocation** if it sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +- Call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) to set a power-up *IoCompletion* routine. + + When handling a device power-up IRP, the driver should set an *IoCompletion* routine to restore context, release the remove lock, and perform other required tasks after the IRP is complete and the device powers on. The driver should not restore context before the IRP has completed. For more information, see [IoCompletion Routines for Device Power IRPs](iocompletion-routines-for-device-power-irps.md). + +- Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP to the next-lower driver. The IRP must travel all the way down the device stack to the bus driver. Only the bus driver is allowed to complete the IRP. + +- Return STATUS\_PENDING. + +When the bus driver receives the IRP, it should first check to ensure the device is still present and has not been removed or replaced while asleep. If the device is no longer present, the bus driver should call [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) on the parent device to notify the Plug and Play manager that the device has disappeared. In this situation, the bus driver can fail the device power-up IRP. + +If the device is still present, the bus driver then performs the tasks required to return the device to an operating condition, calls [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to inform the power manager of the new device power state, and completes the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)). If drivers have queued I/O while the device was sleeping, or if the device requires inrush power, the bus driver applies power to the device. Otherwise, the bus driver applies power as soon as it has to communicate with the device. + +For a list of best practices to achieve fast startup times from power-off, standby, and hibernation states, see [Improving System Startup Performance](improving-system-startup-performance.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Device%20Power-Up%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-exceptions.md b/windows-driver-docs-pr/kernel/handling-exceptions.md new file mode 100644 index 0000000000..6b83e22d3f --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-exceptions.md @@ -0,0 +1,92 @@ +--- +title: Handling Exceptions +author: windows-driver-content +description: Handling Exceptions +ms.assetid: 20040d86-5088-48ec-a5b9-54760d143871 +keywords: ["structured exception handling WDK kernel", "exceptions WDK kernel", "access violations WDK kernel", "hardware-defined exceptions WDK kernel", "software-defined exceptions WDK kernel", "errors WDK kernel", "guard-page violations WDK kernel", "page-read errors WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Exceptions + + +## + + +The operating system uses [structured exception handling](https://msdn.microsoft.com/library/windows/hardware/ff556336#wdkgloss-structured-exception-handling) to signal certain kinds of errors. A routine called by a driver can raise an exception that the driver must handle. + +The system traps the following general kinds of exceptions: + +1. Hardware-defined faults or traps, such as, + + - Access violations (see below) + - Data-type misalignments (such as a 16-bit entity aligned on an odd-byte boundary) + - Illegal and privileged instructions + - Invalid lock sequences (attempting to execute an invalid sequence of instructions within an interlocked section of code) + - Integer divides by zero and overflows + - Floating-point divides by zero, overflows, underflows, and reserved operands + - Breakpoints and single step execution (to support debuggers) + +2. System software-defined exceptions, such as, + + - Guard-page violations (attempting to load or store data from or to a location within a guard page) + - Page-read errors (attempting to read a page into memory and encountering a concurrent I/O error) + +An *access violation* is an attempt to perform an operation on a page that is not permitted under the current page protection settings. Access violations occur in the following situations: + +- An invalid read or write operation, such as writing to a read-only page. + +- To access memory beyond the limit of the current program's address space (known as a length violation). + +- To access a page that is currently resident but dedicated to the use of a system component. For example, user-mode code is not allowed access a page that the kernel is using. + +If an operation might cause an exception, the driver should enclose the operation in a **try/except** block. Accesses of locations in user-mode are typical causes of exceptions. For example, the [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) routine checks that the driver can actually write to a user-mode buffer. If it cannot, the routine raises a STATUS\_ACCESS\_VIOLATION exception. In the following code example, the driver calls **ProbeForWrite** in a **try/except** so that it can handle the resulting exception, if one should occur. + +``` +try { + ... + ProbeForWrite(Buffer, BufferSize, BufferAlignment); + + /* Note that any access (not just the probe, which must come first, + * by the way) to Buffer must also be within a try-except. + */ + ... +} except (EXCEPTION_EXECUTE_HANDLER) { + /* Error handling code */ + ... +} +``` + +Drivers must handle any raised exceptions. An exception that is not handled causes the system to bug check. The driver that causes the exception to be raised must handle it: a lower-level driver cannot rely on a higher-level driver to handle the exception. + +Drivers can directly raise an exception, by using the [**ExRaiseAccessViolation**](https://msdn.microsoft.com/library/windows/hardware/ff545509), [**ExRaiseDatatypeMisalignment**](https://msdn.microsoft.com/library/windows/hardware/ff545524), or [**ExRaiseStatus**](https://msdn.microsoft.com/library/windows/hardware/ff545529) routines. The driver must handle any exceptions that these routines raise. + +The following is a partial list of routines that, at least in certain situations, can raise an exception: + +- [**MmMapLockedPages**](https://msdn.microsoft.com/library/windows/hardware/ff554622) + +- [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) + +- [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) + +- [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) + +Memory accesses to user-mode buffers can also cause access violations. For more information, see [Errors in Referencing User-Space Addresses](errors-in-referencing-user-space-addresses.md). + +Note that structured exception handling is distinct from C++ exceptions. The kernel does not support C++ exceptions. + +For more information about structured exception handling, see the Microsoft Windows SDK, and the Visual Studio documentation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Exceptions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-hardware-profile-change-events.md b/windows-driver-docs-pr/kernel/handling-hardware-profile-change-events.md new file mode 100644 index 0000000000..8788bf6728 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-hardware-profile-change-events.md @@ -0,0 +1,42 @@ +--- +title: Handling Hardware Profile Change Events +author: windows-driver-content +description: Handling Hardware Profile Change Events +ms.assetid: ddb0f740-9b31-4ede-be84-c1f6eb60fb1a +keywords: ["notifications WDK PnP , hardware profile changes", "hardware profile change notifications WDK PnP", "EventCategoryHardwareProfileChange notification", "profile change notifications WDK PnP", "machine hardware profile change notifications WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Hardware Profile Change Events + + +## + + +At specific times during a hardware profile change, the PnP manager calls notification callback routines that registered for **EventCategoryHardwareProfileChange**: + +- Before there is a change in the machine's hardware profile, the PnP manager calls registered notification callback routines and specifies a *NotificationStructure*.**Event** of GUID\_HWPROFILE\_QUERY\_CHANGE. + +- After the machine's hardware profile change is complete, the PnP manager calls registered notification callback routines and specifies a *NotificationStructure*.**Event** of GUID\_HWPROFILE\_CHANGE\_COMPLETE. + +- If the machine's hardware profile change is canceled, the PnP manager calls registered notification callback routines and specifies a *NotificationStructure*.**Event** of GUID\_HWPROFILE\_CHANGE\_CANCELLED. + +For a GUID\_HWPROFILE\_QUERY\_CHANGE event the PnP manager calls user-mode callback routines and then calls kernel-mode callback routines. In response to a GUID\_HWPROFILE\_QUERY\_CHANGE event, a driver's notification callback routine typically just returns STATUS\_SUCCESS. + +For a GUID\_HWPROFILE\_CHANGE\_COMPLETE event the PnP manager calls kernel-mode callback routines and then calls user-mode callback routines. In response to such an event, a driver's callback routine might refresh its hardware-profile-specific settings. + +For a GUID\_HWPROFILE\_CHANGE\_CANCELLED event the PnP manager calls kernel-mode callback routines and then user-mode routines. In response to such an event, a driver's callback routine typically just returns STATUS\_SUCCESS. If the driver performed any operations in response to the GUID\_HWPROFILE\_QUERY\_CHANGE event, the driver would undo those operations in response to the cancellation event. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Hardware%20Profile%20Change%20Events%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-device-power-states.md b/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-device-power-states.md new file mode 100644 index 0000000000..3652686f21 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-device-power-states.md @@ -0,0 +1,78 @@ +--- +title: Handling IRP_MN_QUERY_POWER for Device Power States +author: windows-driver-content +description: Handling IRP_MN_QUERY_POWER for Device Power States +ms.assetid: 902619bc-068a-4613-b99d-78a243f7fee6 +keywords: ["IRP_MN_QUERY_POWER", "device power states WDK kernel", "query-power IRPs WDK power management", "power IRPs WDK kernel , device queries", "querying power state", "queuing IRPs", "device query power IRPs WDK kernel", "dispatch routines WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRP\_MN\_QUERY\_POWER for Device Power States + + +## + + +A device query-power IRP queries about a change of state for a single device and is sent to all of the drivers in the stack for the device. Such an IRP specifies **DevicePowerState** in the **Power.Type** member of the I/O stack location. + +Drivers handle query-power IRPs as they travel down the stack. + +A function or filter driver can fail an [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) request if any of the following is true: + +- The device is enabled for wake-up and the requested power state is below the state from which the device can wake the system. For example, a device that can wake the system from D2 but not from D3 would fail a query for D3 but succeed a query for D2. + +- Entering the requested state would force the driver to abandon an operation that would lose data, such as an open modem connection. A driver rarely will fail a query for this reason; under most circumstances, the application handles such cases. + +To fail an [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) request, a driver takes the following steps: + +1. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to indicate that the driver is prepared to handle the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only.) + +2. Set **Irp->IoStatus.Status** to a failure status and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), specifying IO\_NO\_INCREMENT. The driver does not pass the IRP further down the device stack. + +3. Return an error status from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +If the driver succeeds the query-power IRP, it must not start any operations or take any other action that would prevent its successful completion of a subsequent **IRP\_MN\_SET\_POWER** request to the queried power state. + +A driver that succeeds the IRP must prepare for a set-power IRP for the queried state and pass down the query IRP, as follows: + +1. Finish any outstanding I/O operations. + +2. Queue incoming I/O requests. + +3. Avoid starting any other new activities that would interfere with a transition to the specified power state. However, the driver should not save device context or take other steps toward shutdown. + +4. Call **IoCopyCurrentIrpStackLocationToNext** to set the IRP stack location for the next-lower driver. + +5. Set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. In the *IoCompletion* routine, call **PoStartNextPowerIrp** (Windows Server 2003, Windows XP, and Windows 2000 only) to indicate the driver's readiness to handle the next power IRP. + +6. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (in Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000) to pass the query IRP to the next-lower driver. Do not complete the IRP. + +7. Return STATUS\_PENDING. The driver must not change the value at **Irp->IoStatus.Status**. + +When the query-power IRP reaches the bus driver, the bus driver calls **PoStartNextPowerIrp** (Windows Server 2003, Windows XP, and Windows 2000 only) and sets **Irp->IoStatus.Status** to STATUS\_SUCCESS if the driver can change to the specified power state or sets a failure status if it cannot. The bus driver then calls **IoCompleteRequest**, specifying IO\_NO\_INCREMENT. + +The drivers in a typical device stack handle a device query-power IRP as follows: + +- Most filter drivers should simply pass the IRP to the next-lower driver (see [Passing Power IRPs](passing-power-irps.md)) and return STATUS\_PENDING. Some filter drivers, however, might first need to perform device-specific tasks, such as queuing incoming IRPs or saving device power state. + +- A function driver performs device-specific tasks (such as, completing pending I/O requests, queuing incoming I/O requests, saving device context, or changing device power), sets an *IoCompletion* routine, and passes the device power IRP to the next-lower driver (see [Passing Power IRPs](passing-power-irps.md)). It returns STATUS\_PENDING from its *DispatchPower* routine. + +- The bus driver calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) (Windows Server 2003, Windows XP, and Windows 2000 only) to start the next power IRP. It then completes the IRP, specifying IO\_NO\_INCREMENT. If the driver cannot complete the IRP immediately, it calls [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422), returns STATUS\_PENDING from its *DispatchPower* routine, and completes the IRP later. + +Even if the target device is already in the queried power state, each function or filter driver must queue I/O and pass the IRP down to the next-lower driver. The IRP must travel all the way down the device stack to the bus driver, which completes it. + +While handling an **IRP\_MN\_QUERY\_POWER** request, a driver should return from the *DispatchPower* routine as quickly as possible. A driver must not wait in its *DispatchPower* routine for a kernel event signaled by code that handles the same IRP. Because power IRPs are synchronized throughout the system, a deadlock might occur. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRP_MN_QUERY_POWER%20for%20Device%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-system-power-states.md b/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-system-power-states.md new file mode 100644 index 0000000000..bb171b2ac8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irp-mn-query-power-for-system-power-states.md @@ -0,0 +1,56 @@ +--- +title: Handling IRP_MN_QUERY_POWER for System Power States +author: windows-driver-content +description: Handling IRP_MN_QUERY_POWER for System Power States +ms.assetid: 1904a1cb-a220-41cc-8894-5f90919e7383 +keywords: ["IRP_MN_QUERY_POWER", "system power states WDK kernel , IRP_MN_QUERY_POWER", "query-power IRPs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRP\_MN\_QUERY\_POWER for System Power States + + +## + + +The power manager sends a power IRP with the minor IRP code [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) and **SystemPowerState** in **Parameters.Power.Type** to determine whether it can safely change to a specified system power state (S1-S5) and to allow drivers to prepare for such a change. + +Whenever possible, the power manager queries before sending an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) that requests a lower (less powered) state. However, in cases of a failing battery or imminent loss of power, the power manager sends the set-power IRP without querying first. The power manager never sends a query before sending an IRP to set the system in the working state (S0). + +For information about how a power policy owner for a device handles system query-power requests, see [Handling a System Query-Power IRP in a Device Power Policy Owner](handling-a-system-query-power-irp-in-a-device-power-policy-owner.md). + +For information about how drivers (that are not the power policy owner for a device) handle system query-power requests, see the following: + +[Handling a System Query-Power IRP in a Filter or Function Driver](handling-a-system-query-power-irp-in-a-filter-or-function-driver.md) + +[Failing a System Query-Power IRP in a Filter or Function Driver](failing-a-system-query-power-irp-in-a-filter-or-function-driver.md) + +[Handling a System Query-Power IRP in a Bus Driver](handling-a-system-query-power-irp-in-a-bus-driver.md) + +Note that a driver must never send a device **IRP\_MN\_SET\_POWER** request in response to a system query; it requests such an IRP only after it receives a system set-power request. + +Because the power manager sends the system query IRP to each device stack on the system, it is possible that a driver for one device might fail the query while drivers for other devices complete it successfully. Beginning with Windows Vista, a change to the system power state to a sleep state is a critical power state change. Even if a driver fails a system query-power IRP, the power manager in Windows Vista might still change the system power state to a sleep state. It is also possible that a battery might expire while a query is active, requiring an immediate shutdown. Consequently, after a query IRP, drivers must be prepared to receive any of the following power IRPs: + +- An **IRP\_MN\_SET\_POWER** to the queried state + +- An **IRP\_MN\_SET\_POWER** to a different power state + +- An **IRP\_MN\_SET\_POWER** to the current power state + +- An **IRP\_MN\_QUERY\_POWER** to any state + +Usually, however, a driver receives a system set-power IRP following a system query IRP. Regardless, a driver must be ready to change the system power state even if the driver fails a query-power IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRP_MN_QUERY_POWER%20for%20System%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md b/windows-driver-docs-pr/kernel/handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md new file mode 100644 index 0000000000..63c3032f7c --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md @@ -0,0 +1,64 @@ +--- +title: Handling IRP_MN_REGINFO and IRP_MN_REGINFO_EX to Register Blocks +author: windows-driver-content +description: Handling IRP_MN_REGINFO and IRP_MN_REGINFO_EX to Register Blocks +ms.assetid: 2c17fc63-3c33-4d03-8c46-8d56242556d1 +keywords: ["WMI WDK kernel , registering with WMI", "registering WMI data providers", "data providers WDK WMI", "driver registrations WDK WMI", "event blocks WDK WMI", "blocks WDK WMI", "IRP_MN_REGINFO", "IRP_MN_REGINFO_EX", "registering blocks"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRP\_MN\_REGINFO and IRP\_MN\_REGINFO\_EX to Register Blocks + + +## + + +On Windows 98 and Windows 2000, the system sends the [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) request to a driver to allow a driver to register its WMI classes. On Windows XP and later, the system sends the [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request instead. Most drivers can handle these requests by using [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to provide a callback routine. See [Using the WMI Library to Register Blocks](using-the-wmi-library-to-register-blocks.md) for details. + +A driver must handle **IRP\_MN\_REGINFO** or **IRP\_MN\_REGINFO\_EX** requests to register blocks that use dynamic instance names or that use a list of driver-defined static instance names; it cannot call **WmiSystemControl** to register such blocks. A driver can optionally handle this request to register blocks that use static instance names based on the PDO or a driver-defined base name string. + +In this case, the driver: + +1. Fills in a [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure at **Parameters.WMI.Buffer** that specifies: + + - The number of bytes of all registration data supplied by the driver, including data supplied on behalf of another driver. + + - The driver's registry path. + + - The name of the driver's MOF resource. + + - The number of blocks to register. + + - An array of [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structures, one for each block. + +2. For each block, the driver fills in a **WMIREGGUID** structure that specifies: + + - The GUID that represents the block. + + - Flags that provide information about instance names and other characteristics of the block, such as whether the block is expensive to collect. For more information, see [WMI Registration Flags](wmi-registration-flags.md). + + If the block is being registered with static instance names, the driver sets one of the following members to specify static instance name data for the block: + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_LIST, it sets **InstanceNameList** to an offset to a list of static instance name strings. WMI specifies instances in subsequent requests by index into this list. + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_BASENAME, it sets **BaseNameOffset** to an offset to a base name string. WMI uses this string to generate static instance names for the block. + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_PDO, it sets **Pdo** to the PDO passed to the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. WMI uses the device instance path of the PDO to generate static instance names for the block. When handling an **IRP\_MN\_REGINFO\_EX** request, drivers must call the [**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) routine on the physical device object passed in **Pdo**. (The system will automatically call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) to dereference the object; the driver must not do so.) + + The driver writes instance name strings or a base name string at the offset indicated by **InstanceNameList** or **BaseName**, respectively. + +3. If the driver is registering blocks on behalf of another driver (as a class driver might on behalf of a miniclass driver), the driver fills in another [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure and list of [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structures with registration information for the other driver's blocks, and sets **NextWmiRegInfo** in the first **WMIREGINFO** to the offset in bytes from the beginning of the first **WMIREGINFO** to the beginning of the second **WMIREGINFO** structure. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRP_MN_REGINFO%20and%20IRP_MN_REGINFO_EX%20to%20Register%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-device-power-states.md b/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-device-power-states.md new file mode 100644 index 0000000000..83544da884 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-device-power-states.md @@ -0,0 +1,58 @@ +--- +title: Handling IRP_MN_SET_POWER for Device Power States +author: windows-driver-content +description: Handling IRP_MN_SET_POWER for Device Power States +ms.assetid: b4a19995-7933-41f7-b951-15ce0e4627da +keywords: ["IRP_MN_SET_POWER", "device power states WDK kernel", "set-power IRPs WDK kernel", "DispatchPower routine", "passing IRPs down device stack WDK", "device set power IRPs WDK kernel", "power IRPs WDK kernel , device changes", "dispatch routines WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRP\_MN\_SET\_POWER for Device Power States + + +## + + +A device set-power IRP requests a change of state for a single device and is sent to all the drivers in the stack for the device. Such an IRP specifies **DevicePowerState** in the **Power.Type** member of the I/O stack location. + +Drivers handle power-down IRPs as they travel down the stack. For power-up IRPs, drivers set [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines as the IRPs travel down the stack, and then handle the IRPs in the *IoCompletion* routines as the IRPs travel back up the stack. The drivers in a typical device stack handle a device set-power IRP as follows: + +- Most filter drivers should simply call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422), pass the IRP to the next-lower driver (see [Passing Power IRPs](passing-power-irps.md)), and return STATUS\_PENDING from the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. Some filter drivers, however, might first need to perform device-specific tasks, such as queuing incoming IRPs or saving device power state. + +- A function driver calls **IoMarkIrpPending**, performs device-specific tasks (such as completing pending I/O requests, queuing incoming I/O requests, saving device context, or changing device power), sets an *IoCompletion* routine if necessary, and passes the device power IRP to the next-lower driver (see [Passing Power IRPs](passing-power-irps.md)). It returns STATUS\_PENDING from its *DispatchPower* routine. + +- The bus driver changes device power if it is capable of doing so and then calls [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager of the new device power state. In Windows Server 2003, Windows XP, and Windows 2000 only, the driver must also call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP after it sets the power state. The driver then completes the IRP, specifying IO\_NO\_INCREMENT. If the driver cannot complete the IRP immediately, it calls [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422), returns STATUS\_PENDING from its *DispatchPower* routine, and completes the IRP later. + +Even if the target device is already in the requested power state, each function or filter driver must pass the IRP down to the next-lower driver. Every set-power IRP must travel all the way down the device stack to the bus driver, which completes it. + +Function and filter drivers that are located above a bus driver must not fail a device set power IRP. The bus driver can fail a device power-up IRP if the device is removed or in the process of being removed. + +Each driver (function, filter, and bus driver) in a driver stack must call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to inform the power manager of a change in the power state of its corresponding device object. + +Like other driver tasks associated with device power-up and power-down, the call to **PoSetPowerState** must occur after the device powers on (if the new state is D0) or before the device powers off (if the new state is any other state). + +Each driver should keep track of the power state of its device. The power manager does not supply this information to drivers. + +While handling an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request for a device power state, a driver should return from the *DispatchPower* routine as quickly as possible. A driver must not wait in its *DispatchPower* routine for a kernel event signaled by code that handles the same IRP. Because power IRPs are synchronized throughout the system, a deadlock might occur. + +To ensure the highest level of system performance, especially for multimedia applications, a driver should perform time-consuming operations at an interrupt request level (IRQL) equal to PASSIVE\_LEVEL. To perform operations at IRQL= PASSIVE\_LEVEL, a driver can use a [dedicated thread](device-dedicated-threads.md) or a [system worker thread](system-worker-threads.md). For guidelines on optimizing driver performance for multimedia platforms, see the [Streaming Media Devices Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff568270). + +The exact steps a driver must take to handle a power IRP depend upon whether the device is powering up or down, as described in the following sections: + +[Handling Device Power-Down IRPs](handling-device-power-down-irps.md) + +[Handling Device Power-Up IRPs](handling-device-power-up-irps.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRP_MN_SET_POWER%20for%20Device%20Power%20States%20%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-system-power-states.md b/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-system-power-states.md new file mode 100644 index 0000000000..767e9bd3a6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irp-mn-set-power-for-system-power-states.md @@ -0,0 +1,54 @@ +--- +title: Handling IRP_MN_SET_POWER for System Power States +author: windows-driver-content +description: Handling IRP_MN_SET_POWER for System Power States +ms.assetid: 21e8e8a7-ca77-445b-a49e-28a53f431a26 +keywords: ["IRP_MN_SET_POWER", "system power states WDK kernel , IRP_MN_SET_POWER", "set-power IRPs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRP\_MN\_SET\_POWER for System Power States + + +## + + +The power manager sends a power IRP that specifies the minor code [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) and a system power state for one of the following reasons: + +- To change the system power state. + +- To reaffirm the current power state after a failed [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) request. + +Through the I/O manager, the power manager sends the IRP to the top driver in the device stack at each PnP device node. The IRP notifies all drivers in the stack of the correct system power state. + +To ensure an orderly start-up, the power manager sequences system power-up IRPs so that parent devices have the opportunity to power up before their children do. The power manager does not query before sending a system power-up IRP. + +Similarly, to ensure that the computer sleeps or shuts down in an orderly way, the power manager sends system IRPs that specify sleep, hibernation, or shutdown in a defined sequence, so that devices farther from the root power down before devices nearer the root. Whenever possible, the power manager queries before sending such an IRP. For more information, see [Handling IRP\_MN\_QUERY\_POWER for System Power States](handling-irp-mn-query-power-for-system-power-states.md). + +The system power IRP is not a direct request to change power state — it is a notification. A driver must not change the power state of its device as a direct response to the *system* power IRP; a driver changes its device's power state only in response to a *device* power IRP. (The device power policy owner sends the device power IRP; see [Handling a System Set-Power IRP in a Device Power Policy Owner](handling-a-system-set-power-irp-in-a-device-power-policy-owner.md).) + +Even if the device is already in a device power state that is valid for the requested system power state, each driver must nevertheless pass the system set-power IRP to the next-lower driver, until it reaches the bus driver. Only the bus driver is allowed to complete this IRP. + +How a driver handles this IRP depends upon its role in the device stack, as described in the following sections: + +[Handling a System Set-Power IRP in a Device Power Policy Owner](handling-a-system-set-power-irp-in-a-device-power-policy-owner.md) + +[Handling a System Set-Power IRP in a Bus Driver](handling-a-system-set-power-irp-in-a-bus-driver.md) + +[Handling a System Set-Power IRP in a Filter Driver](handling-a-system-set-power-irp-in-a-filter-driver.md) + +A driver cannot fail an **IRP\_MN\_SET\_POWER** request to set the system power state. The power manager ignores any failure status returned for this IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRP_MN_SET_POWER%20for%20System%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-irps.md b/windows-driver-docs-pr/kernel/handling-irps.md new file mode 100644 index 0000000000..ef031bafe7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-irps.md @@ -0,0 +1,62 @@ +--- +title: Handling IRPs +author: windows-driver-content +description: Handling IRPs +ms.assetid: 5fb6d2b9-17ee-4e76-95e9-dd5a7d1e79de +keywords: ["kernel-mode drivers WDK , IRPs", "IRPs WDK kernel", "I/O request packets WDK kernel See IRPs WDK kernel", "IRP WDK See IRPs WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling IRPs + + +## + + +This section describes how kernel-mode drivers handle *I/O request packets* (IRPs). It contains the following sections: + +[Overview of the Windows I/O Model](overview-of-the-windows-i-o-model.md) + +[End-User I/O Requests and File Objects](end-user-i-o-requests-and-file-objects.md) + +[The Life of an I/O Request](the-life-of-an-i-o-request.md) + +[I/O Stack Locations](i-o-stack-locations.md) + +[I/O Status Blocks](i-o-status-blocks.md) + +[Passing IRPs down the Driver Stack](passing-irps-down-the-driver-stack.md) + +[Creating IRPs for Lower-Level Drivers](creating-irps-for-lower-level-drivers.md) + +[Queuing and Dequeuing IRPs](queuing-and-dequeuing-irps.md) + +[Completing IRPs](completing-irps.md) + +[Canceling IRPs](canceling-irps.md) + +[Reusing IRPs](reusing-irps.md) + +[Device Type-Specific I/O Requests](device-type-specific-i-o-requests.md) + +[Using I/O Control Codes](using-i-o-control-codes.md) + +[Using IRP Priority Hints](using-irp-priority-hints.md) + +[IRP Major Function Codes](irp-major-function-codes.md) + +[IRP Processing Examples](irp-processing-examples.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-notifications.md b/windows-driver-docs-pr/kernel/handling-notifications.md new file mode 100644 index 0000000000..7e9630cdc1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-notifications.md @@ -0,0 +1,80 @@ +--- +title: Handling Notifications +author: windows-driver-content +description: Handling Notifications +ms.assetid: ace7f59d-fe9f-4810-91db-2cf20c9591cf +keywords: ["filtering registry calls WDK kernel , notification options", "registry filtering drivers WDK kernel , notification options", "notifications WDK filter registry call", "filtering registry calls WDK kernel , monitoring calls", "registry filtering drivers WDK kernel , monitoring calls", "filtering registry calls WDK kernel , blocking calls", "registry filtering drivers WDK kernel , blocking calls", "filtering registry calls WDK kernel , modifying calls", "registry filtering drivers WDK kernel , modifying calls", "blocking calls WDK filter registry call", "monitoring registry calls"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Notifications + + +The [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine receives a pointer to a **REG\_*XXX*\_KEY\_INFORMATION** structure that contains information about the registry operation that is occurring. + +The *RegistryCallback* routine can monitor, block, or modify a registry operation. + +### Monitoring Registry Calls + +If a registry filtering driver is monitoring registry operations, its *RegistryCallback* routine can update counters or perform other bookkeeping operations and then return STATUS\_SUCCESS. Whenever a *RegistryCallback* routine returns STATUS\_SUCCESS, the configuration manager continues performing the registry operation. + +Monitoring registry calls is supported in Windows XP and later versions of Windows. + +### Blocking Registry Calls + +A registry filtering driver can block registry operations if its *RegistryCallback* routine returns a status value for which [NT\_SUCCESS](using-ntstatus-values.md)(*status*) equals **FALSE** (that is, a non-success NTSTATUS value). When the configuration manager receives a non-success return value, it immediately returns to the calling thread with the driver-specified status value. Therefore, a registry filtering driver can use pre-notifications to prevent registry operations from being processed. + +If a *RegistryCallback* routine returns a status value for which NT\_SUCCESS(*status*) equals **FALSE** for a pre-notification, the operation's post-notification callback does not occur. + +Blocking registry calls is supported in Windows XP and later versions of Windows. For Windows Vista and later, the driver can modify the values that the registry operation returns to the calling thread. These values are contained in the **REG\_*XXX*\_KEY\_INFORMATION** structures for Windows Vista and later. + +### Modifying Registry Calls + +A registry filtering driver can modify a registry operation's output parameters or return value. Additionally, the driver can completely process a registry operation instead of allowing the registry to handle the operation. + +When a registry filtering driver's *RegistryCallback* routine receives a post-notification, it can: + +- Modify the output parameters that its **REG\_*XXX*\_KEY\_INFORMATION** structure contains and then return STATUS\_SUCCESS. The configuration manager returns the modified output parameters to the calling thread. + + Modifying output parameters is supported in Windows Vista and later. + +- Modify the registry operation's return value by providing a status value for the **ReturnStatus** member of the [**REG\_POST\_OPERATION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560971) structure and then returning STATUS\_CALLBACK\_BYPASS. The configuration manager returns the specified return value to the calling thread. + + **Note**  If the driver changes a status code from success to failure, it might have to deallocate objects that the configuration manager allocated. Alternatively, if the driver changes a status code from failure to success, it might have to provide appropriate output parameters. + +   + + Modifying return values is supported in Windows Vista and later. + +When a registry filtering driver's *RegistryCallback* routine receives a pre-notification, the routine can handle the registry operation itself and then return STATUS\_CALLBACK\_BYPASS. When the registry receives STATUS\_CALLBACK\_BYPASS from the driver, it just returns STATUS\_SUCCESS to the calling thread and does not process the operation. The driver preempts the registry operation and must completely handle it, and the driver must be careful to return valid output values in the **REG\_*XXX*\_KEY\_INFORMATION** structure. + +Drivers can preempt registry operations in Windows Vista and later. + +If a *RegistryCallback* routine returns STATUS\_CALLBACK\_BYPASS for a pre-notification, the operation's post-notification callback does not occur. + +**Note**  Several registry system calls are not documented because they are rarely used, and, when they are used, it is usually to achieve some unconventional result in the registry. Modifying the operations performed by these calls is difficult and error-prone. Driver developers are discouraged from trying to modify the following registry system calls: +- **NtRestoreKey** +- **NtSaveKey** +- **NtSaveKeyEx** +- **NtLoadKeyEx** +- **NtUnloadKey2** +- **NtUnloadKeyEx** +- **NtReplaceKey** +- **NtRenameKey** +- **NtSetInformationKey** + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Notifications%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-overlapped-i-o-operations.md b/windows-driver-docs-pr/kernel/handling-overlapped-i-o-operations.md new file mode 100644 index 0000000000..dba1a7d84d --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-overlapped-i-o-operations.md @@ -0,0 +1,40 @@ +--- +title: Handling Overlapped I/O Operations +author: windows-driver-content +description: Handling Overlapped I/O Operations +ms.assetid: d13a9fa2-9f68-4c35-af79-dd3f8cec2805 +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel", "DpcForIsr", "CustomDpc", "overlapped I/O WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Overlapped I/O Operations + + +## + + +The [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine of a driver that overlaps operations on its device cannot rely on a one-to-one correspondence between requests input to the [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine and the ISR's calls to [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) or [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185). Such a driver's *DpcForIsr* or *CustomDpc* cannot necessarily use the input pointers to the IRP and ISR-supplied context, or the **CurrentIrp** pointer in the target device object, to complete only that IRP. + +At any given moment, the same DPC object cannot be queued twice. If an ISR calls **IoRequestDpc** or **KeInsertQueueDpc** more than once before the corresponding *DpcForIsr* or *CustomDpc* executes, the DPC routine runs only once when the IRQL on a processor falls below DISPATCH\_LEVEL. On the other hand, if the ISR calls **IoRequestDpc** or **KeInsertQueueDpc** while the corresponding *DpcForIsr* or *CustomDpc* is running on another processor, the DPC routine can run on two processors concurrently. + +Therefore, any driver that overlaps interrupt-driven I/O operations on its device must have the following: + +- A *DpcForIsr* or *CustomDpc* routine that can complete some driver-maintained count of outstanding requests each time it is called + +- An ISR that never overwrites the context information that it passes to a *DpcForIsr* or *CustomDpc* routine, until that routine has used the context information and completed the IRP to which the context information belongs + +- A *SynchCritSection* routine that accesses the ISR's context area on behalf of the *DpcForIsr* or *CustomDpc* routine + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Overlapped%20I/O%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-power-irps.md b/windows-driver-docs-pr/kernel/handling-power-irps.md new file mode 100644 index 0000000000..e33e1de46b --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-power-irps.md @@ -0,0 +1,46 @@ +--- +title: Handling Power IRPs +author: windows-driver-content +description: Handling Power IRPs +ms.assetid: 0fe4f27a-101d-41af-8f00-fb36da5dc793 +keywords: ["power management WDK kernel , IRPs", "IRPs WDK power management", "power IRPs WDK kernel , about power IRPs", "IRP_MJ_POWER", "IRP_MN_QUERY_POWER", "IRP_MN_SET_POWER", "IRP_MN_WAIT_WAKE", "IRP_MN_POWER_SEQUENCE", "power states WDK kernel", "states WDK power management", "change power states WDK kernel", "conserving power WDK kernel", "sleep power management WDK kernel", "querying power state", "asleep devices WDK power management", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Power IRPs + + +## + + +Drivers handle power IRPs in a [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. All power management requests have the major IRP code [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) and one of the following minor codes: + +[**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) — Queries to determine whether changing power state is feasible + +[**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) — Requests a change from one power state to another + +[**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) — Requests that a device be enabled to wake itself or the system + +[**IRP\_MN\_POWER\_SEQUENCE**](https://msdn.microsoft.com/library/windows/hardware/ff551644) — Requests information to optimize power restoration to a particular device + +Support for **IRP\_MN\_SET\_POWER** and **IRP\_MN\_QUERY\_POWER** is required. All drivers must be prepared to handle these IRPs. + +Support for **IRP\_MN\_WAIT\_WAKE** is required for all drivers in the device stack for any device that can awaken in response to an external signal. A driver sends this IRP to enable the device for wake-up. + +Support for **IRP\_MN\_POWER\_SEQUENCE** is optional. This IRP provides an optimization for devices that take a long time to restore power. + +A power IRP can specify a system power operation or a device power operation. [Power IRPs for the system](power-irps-for-the-system.md) and [power IRPs for individual devices](power-irps-for-individual-devices.md) take slightly different paths through a device stack, as explained in the following sections. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Power%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-recovery-operations.md b/windows-driver-docs-pr/kernel/handling-recovery-operations.md new file mode 100644 index 0000000000..b699edd227 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-recovery-operations.md @@ -0,0 +1,69 @@ +--- +title: Handling Recovery Operations +author: windows-driver-content +description: Handling Recovery Operations +ms.assetid: 35149bb9-fd48-44d3-a9fd-0e631aa0e853 +keywords: ["transactions WDK KTM , recovering transactions", "recovering transactions WDK KTM", "transaction processing systems WDK KTM , recovering transactions", "TPS WDK KTM , recovering transactions", "log streams WDK KTM , recovering transactions", "virtual clock values WDK KTM , recovering transactions"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Recovery Operations + + +In a *recovery* operation, a transaction processing system (TPS) tries to recover its state from the information that is in [log streams](using-log-streams-with-ktm.md). After a recovery operation is complete, all transactions should be in a committed or rolled back state, and all resource data should be in a known good state. + +Sometimes a TPS stops before all its transactions have finished. For example, the operating system might crash. Therefore, resource managers must initiate recovery operations whenever they start to run. The recovery operation tries to determine whether any transactions are incomplete. If incomplete transactions are found in the log, the recovery operation tries to commit or roll back those transactions. + +For a KTM-based TPS, each recovery operation consists of two steps. The first step involves recovering information from the transaction manager object's log stream. The second step involves recovering information from the resource manager's log stream. + +A TPS can recover to the end of all log streams or, if its resource managers maintain [virtual clock values](using-virtual-clock-values.md), it can recover up to a specified clock value. + +### Recovering Information from a Transaction Manager Object's Log Stream + +Immediately after a resource manager calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430) or [**ZwOpenTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567035), it must call [**ZwRecoverTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567079). The **ZwRecoverTransactionManager** routine reads the log stream that belongs to the transaction manager object. This routine reconstructs the state of the transaction manager object (including all transactions, enlistments, and resource managers) from the recovery information that is in the log stream, beginning at the last [restart area](reading-restart-records-from-a-clfs-stream.md) that KTM created and ending at the stream's end. + +To recover from the last restart area up to a specified virtual clock value, the resource manager can call [**ZwRollforwardTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567089) instead of **ZwRecoverTransactionManager**. + +### Recovering Information from a Resource Manager's Log Stream + +Immediately after a resource manager calls [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427) or [**ZwOpenResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567026), it must call [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078). The **ZwRecoverResourceManager** routine tries to recover the transactions that are associated with each of the resource manager's enlistments. + +When a resource manager calls **ZwRecoverResourceManager**, KTM sends TRANSACTION\_NOTIFY\_RECOVER [notifications](transaction-notifications.md) for each of the resource manager's enlistments. The resource manager must call [**ZwRecoverEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567075) every time that it receives one of the TRANSACTION\_NOTIFY\_RECOVER notifications. + +When the resource manager calls **ZwRecoverEnlistment**, KTM sends one of the following notifications: + +- TRANSACTION\_NOTIFY\_COMMIT + + The resource manager must use information in its log stream to commit the transaction and then must call [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418). + +- TRANSACTION\_NOTIFY\_ROLLBACK + + The resource manager must use information in its log stream to roll back the transaction and then must call [**ZwRollbackComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567081). + +- TRANSACTION\_NOTIFY\_INDOUBT + + KTM has not determined the state of the transaction and will send a commit or rollback notification later. + +Typically, KTM sends a TRANSACTION\_NOTIFY\_COMMIT notification if it determines that all resource managers called [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037) before the TPS stopped and restarted. KTM sends a TRANSACTION\_NOTIFY\_ROLLBACK notification if it determines that one or more resource managers did not call **ZwPrepareComplete**. + +After KTM has sent a TRANSACTION\_NOTIFY\_RECOVER notification for each enlistment, it sends a TRANSACTION\_NOTIFY\_LAST\_RECOVER notification. + +If your resource manager called **ZwRollforwardTransactionManager** instead of **ZwRecoverTransactionManager**, it must recover only up to the virtual clock value that it specified to **ZwRollforwardTransactionManager**. + +Resource managers can call [**ZwSetInformationEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567094) to set customized recovery information. KTM saves this information and writes it to the log stream, but KTM does not try to interpret the information. The resource manager can retrieve the recovery information at any time by calling [**ZwQueryInformationEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567051). + +[Superior transaction managers](creating-a-superior-transaction-manager.md) sometimes receive TRANSACTION\_NOTIFY\_RECOVER\_QUERY notifications during a recover operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Recovery%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-rollback-operations.md b/windows-driver-docs-pr/kernel/handling-rollback-operations.md new file mode 100644 index 0000000000..cd77951281 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-rollback-operations.md @@ -0,0 +1,47 @@ +--- +title: Handling Rollback Operations +author: windows-driver-content +description: Handling Rollback Operations +ms.assetid: d36bfac8-47dc-4fcd-a6e2-feb27d244630 +keywords: ["transactions WDK KTM , rolling back transactions", "rolling back transactions WDK KTM", "resource managers WDK KTM , rolling backing transactions", "transactional clients WDK KTM , rolling back transactions"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Rollback Operations + + +A resource manager, a transactional client, or KTM can roll back a transaction if it determines that the transaction must not be committed (typically because an error has been detected). + +To roll back a transaction, a resource manager can call [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083). After the resource manager has called [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) to enlist in a transaction, it can roll back the transaction at any time before it calls [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037). + +Transactional clients can roll back their transactions by calling [**ZwRollbackTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567086). After a transactional client has called [**ZwCreateTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566429) to create a transaction, it can roll back the transaction at any time before it calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420). + +In addition, a transactional client can set a time-out value for a transaction by calling [**ZwSetInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567104). KTM rolls back the transaction if it has not been committed by the specified amount of time. + +When a call to **ZwRollbackEnlistment** or **ZwRollbackTransaction** is made, or when a time-out value is exceeded, KTM sends a TRANSACTION\_NOTIFY\_ROLLBACK [notification](transaction-notifications.md) to all resource managers. + +When each resource manager receives a TRANSACTION\_NOTIFY\_ROLLBACK notification, it must do the following: + +1. Restore the transaction's data to the state that it was in before the resource manager enlisted in the transaction. + + Typically, a resource manager restores the transaction's data by copying the transaction's saved initial data from the log stream to the database's public, permanent storage. For more information about how to use log streams, see [Using Log Streams with KTM](using-log-streams-with-ktm.md). + +2. Call [**ZwRollbackComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567081). + +After calling **ZwRollbackComplete**, the resource manager should call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the enlistment handle. + +If a resource manager initiated the rollback operation, it must use its client interface to inform the client that the transaction failed. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Rollback%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-stop-irps--windows-2000-and-later-.md b/windows-driver-docs-pr/kernel/handling-stop-irps--windows-2000-and-later-.md new file mode 100644 index 0000000000..a465e67b39 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-stop-irps--windows-2000-and-later-.md @@ -0,0 +1,40 @@ +--- +title: Handling Stop IRPs (Windows 2000 and Later) +author: windows-driver-content +description: Handling Stop IRPs (Windows 2000 and Later) +ms.assetid: 5148ca15-07f0-4a93-aa65-45b13184184b +keywords: ["stop IRPs WDK PnP", "IRPs WDK PnP", "I/O request packets WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Stop IRPs (Windows 2000 and Later) + + +## + + +Drivers that run only on Windows 2000 and later versions of Windows (WDM versions 0x10 and greater) receive stop IRPs only when the PnP manager rebalances resources. The following sections describe techniques such drivers should use in handling stop IRPs: + +[Handling an IRP\_MN\_QUERY\_STOP\_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-query-stop-device-request--windows-2000-and-later-.md) + +[Handling an IRP\_MN\_STOP\_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-stop-device-request--windows-2000-and-later-.md) + +[Handling an IRP\_MN\_CANCEL\_STOP\_DEVICE Request (Windows 2000 and later)](handling-an-irp-mn-cancel-stop-device-request--windows-2000-and-later-.md) + +[Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md) + +WDM drivers that also run on Windows 98/Me must handle these IRPs differently. See [Handling Stop IRPs (Windows 98/Me)](handling-stop-irps--windows-98-me-.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Stop%20IRPs%20%28Windows%202000%20and%20Later%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-stop-irps--windows-98-me-.md b/windows-driver-docs-pr/kernel/handling-stop-irps--windows-98-me-.md new file mode 100644 index 0000000000..39bcdc8771 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-stop-irps--windows-98-me-.md @@ -0,0 +1,46 @@ +--- +title: Handling Stop IRPs (Windows 98/Me) +author: windows-driver-content +description: Handling Stop IRPs (Windows 98/Me) +ms.assetid: 98eefb69-e321-4cc5-8b4d-79335cd8b06e +keywords: ["stop IRPs WDK PnP", "IRPs WDK PnP", "I/O request packets WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Stop IRPs (Windows 98/Me) + + +## + + +On Windows 98/Me, the PnP manager can send stop IRPs for the following reasons: + +- To pause the device while rebalancing resources + +- To stop the device when Device Manager disables it + +- To stop the device after a failed [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request + +A driver cannot determine from the IRP why it was sent. Consequently, WDM drivers that run on Windows 98/Me must handle all stop IRPs as if the device were being disabled. In short, this means that such drivers fail incoming I/O requests rather than queuing them (as on Windows 2000 and later). + +The following topics provide step-by-step details on handling each of the stop IRPs: + +[Handling an IRP\_MN\_QUERY\_STOP\_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-query-stop-device-request--windows-98-me-.md) + +[Handling an IRP\_MN\_STOP\_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-stop-device-request--windows-98-me-.md) + +[Handling an IRP\_MN\_CANCEL\_STOP\_DEVICE Request (Windows 98/Me)](handling-an-irp-mn-cancel-stop-device-request--windows-98-me-.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Stop%20IRPs%20%28Windows%2098/Me%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-system-power-state-requests.md b/windows-driver-docs-pr/kernel/handling-system-power-state-requests.md new file mode 100644 index 0000000000..34560f5938 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-system-power-state-requests.md @@ -0,0 +1,44 @@ +--- +title: Handling System Power State Requests +author: windows-driver-content +description: Handling System Power State Requests +ms.assetid: c4547b72-107e-4335-a7bd-081376962da0 +keywords: ["power states WDK kernel", "power management WDK kernel , power state requests", "system power states WDK kernel , power state requests", "requests WDK power management", "IRPs WDK power management", "I/O request packets WDK power management", "power requests WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling System Power State Requests + + +## + + +All drivers must be able to respond to system power state requests if the system is to sleep, hibernate, and wake successfully. A driver for a device changes the [device power state](device-power-states.md) for the device in response to system power state requests. + +If any driver does not support system power management, individual devices can sleep and wake, but the power manager cannot put the system as a whole into a sleeping state. + +The following topics cover details of handling system power state requests: + +[System Power States](system-power-states.md) + +[System Power Policy](system-power-policy.md) + +[Preventing System Power State Changes](preventing-system-power-state-changes.md) + +[Handling IRP\_MN\_QUERY\_POWER for System Power States](handling-irp-mn-query-power-for-system-power-states.md) + +[Handling IRP\_MN\_SET\_POWER for System Power States](handling-irp-mn-set-power-for-system-power-states.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20System%20Power%20State%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-transaction-operations.md b/windows-driver-docs-pr/kernel/handling-transaction-operations.md new file mode 100644 index 0000000000..16159afaf5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-transaction-operations.md @@ -0,0 +1,41 @@ +--- +title: Handling Transaction Operations +author: windows-driver-content +description: Handling Transaction Operations +ms.assetid: 9b82e9d6-3db2-4806-a087-1c9622dc04e2 +keywords: ["transactions WDK KTM , handling operations", "handling transaction operations WDK KTM", "transactions WDK KTM , committing transactions", "committing transactions WDK KTM", "transactions WDK KTM , rolling back transactions", "rolling back transactions WDK KTM", "transactions WDK KTM , recovering transactions", "recovering transactions WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Transaction Operations + + +Resource managers must handle three transaction operations: *commit*, *rollback*, and *recovery*. + +To *commit a transaction*, a resource manager makes all changes to a transaction's data permanent and visible to other transactions. + +To *roll back a transaction*, a resource manager removes all changes to a transaction's data. The resource manager must restore the data to the state that it was in before the transaction was created. + +To *recover a transaction*, a resource manager restores a transaction's data to a known good state after a system crash or another unexpected event. + +This section contains the following topics: + +[Handling Commit Operations](handling-commit-operations.md) + +[Handling Rollback Operations](handling-rollback-operations.md) + +[Handling Recovery Operations](handling-recovery-operations.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Transaction%20Operations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-transfers-asynchronously.md b/windows-driver-docs-pr/kernel/handling-transfers-asynchronously.md new file mode 100644 index 0000000000..96e19f645e --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-transfers-asynchronously.md @@ -0,0 +1,40 @@ +--- +title: Handling Transfers Asynchronously +author: windows-driver-content +description: Handling Transfers Asynchronously +ms.assetid: 84b231bd-54ff-4312-8e6c-cfc33e72b8cc +keywords: ["DispatchRead routine", "DispatchWrite routine", "DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchWrite routine", "dispatch routines WDK kernel , DispatchRead routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines", "asynchronous transfers WDK kernel", "data transfers WDK kernel , asynchronous", "transferring data WDK kernel , asynchronous"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Transfers Asynchronously + + +## + + +Except for highest-level drivers, all drivers handle [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests asynchronously. The *DispatchRead* and *DispatchWrite* routines in even a highest-level driver cannot wait for lower-level drivers to finish processing an asynchronous read or write request; they must pass such a request on to lower drivers and return STATUS\_PENDING. + +Similarly, a lowest-level device driver's *DispatchReadWrite* routine must pass the transfer request on to other driver routines that process device I/O requests and then return STATUS\_PENDING. + +A higher-level driver sometimes must set up partial-transfer IRPs and pass them on to lower drivers. The higher-level driver can complete the original read/write IRP only when its partial-transfer requests have been completed by the lower drivers. + +For example, a SCSI class driver's *DispatchReadWrite* routine is required to split large transfer requests that exceed the underlying HBA's transfer capabilities into a set of partial-transfer requests. The class driver must set up the parameters in its partial-transfer IRPs so that the SCSI port/miniport drivers can satisfy each partial-transfer request in a single DMA operation. + +Other device drivers that use DMA or PIO also might need to split up large transfer requests for themselves. + +For more information about using DMA and PIO, see [Input/Output Techniques](i-o-programming-techniques.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Transfers%20Asynchronously%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-unsupported-or-unrecognized-power-irps.md b/windows-driver-docs-pr/kernel/handling-unsupported-or-unrecognized-power-irps.md new file mode 100644 index 0000000000..028ade438a --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-unsupported-or-unrecognized-power-irps.md @@ -0,0 +1,38 @@ +--- +title: Handling Unsupported or Unrecognized Power IRPs +author: windows-driver-content +description: Handling Unsupported or Unrecognized Power IRPs +ms.assetid: 0664389c-f746-4025-969f-8c3b07139026 +keywords: ["power IRPs WDK kernel , unsupported", "unsupported power IRPs WDK kernel", "unrecognized power IRPs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling Unsupported or Unrecognized Power IRPs + + +## + + +If a driver does not support a particular power IRP, it must nevertheless pass the IRP down the device stack to the next-lower driver. A driver further down the stack might be prepared to handle the IRP and must have the opportunity to do so. + +To pass an unsupported or unrecognized power IRP, a driver should call the following routines in the sequence that is described in [Passing Power IRPs](passing-power-irps.md): + +- In Windows 7 and Windows Vista, call [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +- In Windows Server 2003, Windows XP, and Windows 2000, call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), **IoSkipCurrentIrpStackLocation**, and [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654). + +The driver should not change anything in the IRP before passing the IRP down a device stack. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20Unsupported%20or%20Unrecognized%20Power%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/handling-wmi-requests.md b/windows-driver-docs-pr/kernel/handling-wmi-requests.md new file mode 100644 index 0000000000..abef49b444 --- /dev/null +++ b/windows-driver-docs-pr/kernel/handling-wmi-requests.md @@ -0,0 +1,50 @@ +--- +title: Handling WMI Requests +author: windows-driver-content +description: Handling WMI Requests +ms.assetid: d95b736c-045d-4888-8bab-b0a6201f8830 +keywords: ["WMI WDK kernel , requests", "requests WDK WMI", "IRPs WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Handling WMI Requests + + +## + + +All drivers must set a dispatch table entry point for a [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine to handle WMI requests. If a driver [registers as a WMI data provider](registering-as-a-wmi-data-provider.md), it must handle all WMI requests. Otherwise, the driver must forward all WMI requests to the next lower driver. + +All WMI IRPs have the major code [**IRP\_MJ\_SYSTEM\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550813) and a one of the following minor codes: + +- [**IRP\_MN\_REGINFO**](irp-mn-reginfo.md), [**IRP\_MN\_REGINFO\_EX**](irp-mn-reginfo-ex.md)—Queries or updates a driver's registration information after the driver has called [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). + +- [**IRP\_MN\_QUERY\_ALL\_DATA**](irp-mn-query-all-data.md), [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](irp-mn-query-single-instance.md)—Queries for all instances or a single instance of a given data block. + +- [**IRP\_MN\_CHANGE\_SINGLE\_ITEM**](irp-mn-change-single-item.md), [**IRP\_MN\_CHANGE\_SINGLE\_INSTANCE**](irp-mn-change-single-instance.md)—Requests the driver to change a single item or multiple items in an instance of a data block. + +- [**IRP\_MN\_ENABLE\_COLLECTION**](irp-mn-enable-collection.md), [**IRP\_MN\_DISABLE\_COLLECTION**](irp-mn-disable-collection.md)—Requests the driver to start accumulating data for a block that the driver registered as expensive to collect, or to stop accumulating data for such a block. + +- [**IRP\_MN\_ENABLE\_EVENTS**](irp-mn-enable-events.md), [**IRP\_MN\_DISABLE\_EVENTS**](irp-mn-disable-events.md)—Requests the driver to start sending notification of a given event if the event occurs while it is enabled, or to stop sending notification of such an event. + +- [**IRP\_MN\_EXECUTE\_METHOD**](irp-mn-execute-method.md)—Requests the driver to execute a method associated with a data block. + +The WMI kernel-mode component sends WMI IRPs any time following a driver's successful registration as a WMI data provider, typically when a user-mode data consumer has requested WMI information for a driver's device. If a driver registers as a WMI data provider by calling [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480), it must handle each subsequent WMI request in one of the following ways: + +- Call the kernel-mode WMI library routine [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834). A driver can call **WmiSystemControl** to handle requests concerning only blocks that do not use dynamic instance names, and that base static instance names on a single base name string or the [*device instance ID*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-instance-id) of a PDO. For more information, see [Calling WmiSystemControl to Handle WMI IRPs](calling-wmisystemcontrol-to-handle-wmi-irps.md). + +- In its [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine, process and complete any such request tagged with the pointer to its device object that the driver passed in its call to **IoWMIRegistrationControl**, and forward other [**IRP\_MJ\_SYSTEM\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550813) requests to the next lower driver. For more information, see [Processing WMI IRPs in a DispatchSystemControl Routine](processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md). + +For a list of the WMI minor IRPs, see [WMI Minor IRPs](wmi-minor-irps.md).  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Handling%20WMI%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/hardware-resources.md b/windows-driver-docs-pr/kernel/hardware-resources.md new file mode 100644 index 0000000000..c3dbce892c --- /dev/null +++ b/windows-driver-docs-pr/kernel/hardware-resources.md @@ -0,0 +1,74 @@ +--- +title: Hardware Resources +author: windows-driver-content +description: Hardware Resources +ms.assetid: c7a6997b-34f9-4dd9-b384-2321a8b5ce54 +keywords: ["resource descriptors WDK PnP", "PnP WDK kernel , hardware resources", "Plug and Play WDK kernel , hardware resources", "resource requirements lists WDK PnP", "resource lists WDK PnP", "assigned resources WDK PnP", "requirements lists WDK PnP", "registry WDK PnP", "logical configurations WDK PnP", "boot configurations WDK PnP", "forced configurations WDK PnP", "filtered configurations WDK PnP", "override configurations WDK PnP", "configuration types WDK PnP", "allocated configurations WDK PnP", "basic configurations WDK PnP", "Hardware Resources"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hardware Resources + + +## + + +Hardware resources are the assignable, addressable bus paths that allow peripheral devices and system processors to communicate with each other. Hardware resources typically include I/O port addresses, interrupt vectors, and blocks of bus-relative memory addresses. + +Before the system can communicate with a [*device instance*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-instance), the PnP manager must assign hardware resources to the device instance based on knowledge of which resources are available and which ones the device instance is capable of using. Resources are assigned to each device node in the [device tree](device-tree.md) (assuming that the represented device needs resources and those resources are available). The PnP manager keeps track of hardware resources using lists, which it associates with device nodes. It uses two types of lists: + +*Resource Requirements List* +Devices are typically designed to operate within ranges of resource assignments. For instance, a device might require only one interrupt vector, but it might be able to use any one of a range of vectors. For each device instance, the PnP manager maintains a *resource requirements list* that specifies all of the ranges of hardware resources in which the device can operate. The list's name stems from the fact that the PnP manager is required to choose resources from this list when assigning them to the device. + +Kernel-mode code specifies resource requirements lists using [**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) structures (either as input to system routines or in response to IRPs). User-mode code specifies resource requirements lists using [PnP configuration manager structures](https://msdn.microsoft.com/library/windows/hardware/ff549718) as input to [PnP configuration manager functions](https://msdn.microsoft.com/library/windows/hardware/ff549713). + +*Resource List* +When the PnP manager assigns resources to a device, it keeps track of these assignments by creating a list of assigned resources for each device instance. These lists could be called *resource assignment lists*, but that name is typically shorted to *resource lists*. The PnP manager can change resource list contents as devices are added to or removed from a system and resources are subsequently reallocated. (Resources can also be assigned by a PnP BIOS. Also, installation software—using INF files or user input—can force the PnP manager to assign specific resources to a device.) + +Kernel-mode code specifies resource lists by using [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) structures (either as input to system routines or in response to IRPs). User-mode code specifies resource lists using [PnP configuration manager structures](https://msdn.microsoft.com/library/windows/hardware/ff549718) as input to [PnP configuration manager functions](https://msdn.microsoft.com/library/windows/hardware/ff549713). + +The PnP manager stores resource requirements lists and resource lists in the registry, where they can be viewed by using Regedit.exe. Drivers can access these lists indirectly through [Plug and Play routines](https://msdn.microsoft.com/library/windows/hardware/ff558809) and [Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807). User-mode applications can use [PnP configuration manager functions](https://msdn.microsoft.com/library/windows/hardware/ff549713). (Drivers and applications must not directly access these lists using registry functions because the storage format is subject to change in a future release.) + +### Logical Configurations + +Both resource requirements lists and resource lists contain one or more *logical configurations*. Each logical configuration identifies either a range of acceptable resources, or a set of specific resources for a specific [*device instance*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-instance). Additionally, each logical configuration for a device instance belongs to one of the *logical configuration types*. Configuration types are listed below. Several logical configurations, of the same or different types, might be assigned to each device instance. + +### Logical Configuration Types for Resource Requirements Lists + +*Basic Configuration* +A resource requirements list identifying resource ranges supplied by a Plug and Play device. A driver should return this list when it receives the [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff551715) IRP. (The basic configuration for a non-PnP device can be described in an INF file. In this case, device installation software reads the INF file and calls [PnP configuration manager functions](https://msdn.microsoft.com/library/windows/hardware/ff549713) to create a requirements list.) + +*Filtered Configuration* +A resource requirements list that has been supplied to a driver stack, possibly modified, then returned by the driver stack, in response to the [**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550874) IRP. The PnP manager uses the resulting filtered configuration as the basis for allocating resources. + +*Override Configuration* +A resource requirements list that overrides basic configurations. Typically, a device installer creates an override configuration if the device's INF file includes an [**INF DDInstall.LogConfigOverride section**](https://msdn.microsoft.com/library/windows/hardware/ff547339). An override configuration is not removed if its device is physically removed from the system. + +### Logical Configuration Types for Resource Lists + +*Boot Configuration* +A resource list identifying the resources assigned to a device instance when the system is booted. (For PnP devices, this is the configuration supplied by the BIOS; for non-PnP devices, these resources might be selected by jumpers on the card.) A driver should return this resource list when it receives the [**IRP\_MN\_QUERY\_RESOURCES**](https://msdn.microsoft.com/library/windows/hardware/ff551710) IRP. (A boot configuration can be partially empty if the BIOS cannot determine all resources used by a device.) The PnP manager can modify this list if a device is removed or restarted. For non-PnP devices, this configuration type can be used instead of a forced configuration, in which case it has a lower configuration priority than an equivalent forced configuration. Only one boot configuration can exist for each device instance. + +*Forced Configuration* +A resource list identifying resources that a device instance must use. A forced configuration prevents the PnP manager from assigning other resources to the device instance. A device installer might create a forced configuration based on information that is either contained in an INF or received from a user. A forced configuration is not removed if its device is physically removed from the system. Only one forced configuration can exist for each device instance. + +*Allocated Configuration* +A resource list identifying resources currently in use by a device instance. Only one allocated configuration can exist for each device instance. + +Device drivers are responsible for determining a PnP-compatible device's basic configuration, filtered configuration, and boot configuration, and for returning that information in response to IRPs sent by the PnP manager. (For more information, see [Adding a PnP Device to a Running System](adding-a-pnp-device-to-a-running-system.md).) Driver installation software can create override configurations, forced configurations, and, for non-PnP devices, boot configurations. The PnP manager maintains each device instance's allocated configuration. + +A priority is assigned to each configuration when it is created. If the PnP manager finds that a device instance has been assigned several logical configurations of the same type, it attempts to use the one with the highest priority first. If that configuration results in resource conflicts, it tries the configuration with the next lower priority. (For a list of configuration priorities, see [**CM\_Add\_Empty\_Log\_Conf**](https://msdn.microsoft.com/library/windows/hardware/ff537921).) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Hardware%20Resources%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/hiding-devices-from-device-manager.md b/windows-driver-docs-pr/kernel/hiding-devices-from-device-manager.md new file mode 100644 index 0000000000..ee6675137e --- /dev/null +++ b/windows-driver-docs-pr/kernel/hiding-devices-from-device-manager.md @@ -0,0 +1,69 @@ +--- +title: Hiding Devices from Device Manager +author: windows-driver-content +description: Hiding Devices from Device Manager +ms.assetid: dd362ae1-ab14-44ee-982e-f972454c2623 +keywords: ["Device Manager WDK , hidden devices", "devices WDK , hiding from Device Manager", "hidden devices WDK", "hiding devices WDK", "NoDisplayClass value WDK device installations"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hiding Devices from Device Manager + + +By default, Device Manager shows the state of every device on a computer. In some situations, you might want to prevent certain devices from appearing in Device Manager. For example, a motherboard might have a CardBus controller with a slot that is not user-accessible. Because the user cannot use the slot, you do not want Device Manager to display any information about the device. + +To hide a device in Device Manager, you can mark the device as a *hidden device*. Typically, Device Manager does not display hidden devices. (Note, however, that users can override this setting and display all devices within Device Manager, even hidden ones. For more information about how to override this setting, see [Viewing Hidden Devices](https://msdn.microsoft.com/library/windows/hardware/ff553955).) + +There are two ways to mark your device as hidden: within the device's driver or by using the ACPI BIOS. + +### Hiding Devices from Within a Driver + +Drivers have two ways to mark a driver as hidden: + +- A function driver or function filter driver can ask the operating system to hide a successfully started device by responding to the [**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff551698) IRP. When the IRP arrives, the driver must set the PNP\_DEVICE\_DONT\_DISPLAY\_UI bit in **IoStatus.Information** to **TRUE** in the driver's dispatch routine. + +- On Windows XP and later versions of the Windows operating systems, a bus driver or bus filter driver can hide any device, started or otherwise, by responding to the [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) IRP. When the IRP arrives, the driver must set the **Parameters.DeviceCapabilities.NoDisplayInUI** member to **TRUE** in the driver's dispatch routine. In some cases, a bus filter driver might have to set this bit in a completion routine. This extra step is required when the underlying bus driver's dispatch routine incorrectly clears all capability fields that other drivers set. + +### Hiding Devices By Using the ACPI BIOS + +You can mark a device as hidden in the ACPI BIOS. The BIOS can expose a \_STA method for the device. The \_STA method returns a bitmask. Bit 2 (mask 0x4) specifies whether Device Manager should make the device visible by default. This bit should be 1 if the device should be made visible and 0 otherwise. + +For example, the following code example shows how a USB controller on the root bus would be hidden. + +``` +Device(PCI0) // Root PCI bus +_HID *PNP0A03 +... + Device(UCTL) // USB controller + _ADR 0xddddffff // dddd = device, ffff = function + _STA 0xB // Device present, but not shown +``` + +In Microsoft Windows 2000, you can hide only started, working devices. In Windows XP and later versions of Windows, you can also hide broken devices. Bit 3 (mask 0x8) that is returned by the \_STA method indicates whether a device is working properly. This bit is 1 if the device is working properly and is 0 otherwise. For example, the following code example shows how a BIOS would indicate a USB controller is broken and should be hidden: + +``` +Device(PCI0) // Root PCI bus +_HID *PNP0A03 +... + Device(UCTL) // USB controller + _ADR 0xddddffff // dddd = device, ffff = function + _STA 0x3 // Present, but broken and not shown +``` + +**Note**   The "decoding" bit (0x2) does not have any relevance for devices that are described through \_ADR methods. The previous code examples also work without the decoding bit set. BIOS writers must track the decoding state only for devices that are described through \_HID methods. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Hiding%20Devices%20from%20Device%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/high-resolution-timers.md b/windows-driver-docs-pr/kernel/high-resolution-timers.md new file mode 100644 index 0000000000..bbc0978aed --- /dev/null +++ b/windows-driver-docs-pr/kernel/high-resolution-timers.md @@ -0,0 +1,61 @@ +--- +title: High-Resolution Timers +author: windows-driver-content +description: Starting with Windows 8.1, drivers can use the ExXxxTimer routines to manage high-resolution timers. +ms.assetid: B8F2B28C-A02B-4015-B392-3D30BC0229B8 +keywords: ["high-resolution timers", "timer accuracy", "timer resolution", "system clock granularity", "EX_TIMER_HIGH_RESOLUTION", "ExXxxTimer routines", "ExQueryTimerResolution", "ExSetTimerResolution"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# High-Resolution Timers + + +Starting with Windows 8.1, drivers can use the [**Ex*Xxx*Timer**](exxxxtimer-routines-and-ex-timer-objects.md) routines to manage high-resolution timers. The accuracy of a high-resolution timer is limited only by the maximum supported resolution of the system clock. In contrast, timers that are limited to the default system clock resolution are significantly less accurate. + +However, high-resolution timers require system clock interrupts to—at least, temporarily—occur at a higher rate, which tends to increase power consumption. Thus, drivers should use high-resolution timers only when timer accuracy is essential, and use default-resolution timers in all other cases. + +To create a high-resolution timer, a WDM driver calls the [**ExAllocateTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265179) routine and sets the EX\_TIMER\_HIGH\_RESOLUTION flag in the *Attributes* parameter. When the driver calls the [**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) routine to set the high-resolution timer, the operating system increases the resolution of the system clock, as necessary, so that the times at which the timer expires more precisely correspond to the nominal expiration times specified in the *DueTime* and *Period* parameters. + +A Kernel-Mode Driver Framework (KMDF) driver can call the [**WdfTimerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff550050) method to create a high-resolution timer. In this call, the driver passes a pointer to a [**WDF\_TIMER\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff552519) structure as a parameter. To create a high-resolution timer, the driver sets the **UseHighResolutionTimer** member of this structure to **TRUE**. This member is a part of the structure starting with Windows 8.1 and KMDF version 1.13. + +## Controlling timer accuracy + + +For example, for Windows running on an x86 processor, the default interval between system clock ticks is typically about 15 milliseconds, and the minimum interval between system clock ticks is about 1 millisecond. Thus, the expiration time of a default-resolution timer (which **ExAllocateTimer** creates if the EX\_TIMER\_HIGH\_RESOLUTION flag is not set) can be controlled only to within about 15 milliseconds, but the expiration time of a high-resolution timer can be controlled to within a millisecond. + +If a driver specifies a relative expiration time for a default-resolution timer, the timer can expire up to about 15 milliseconds earlier or later than the specified expiration time. If a driver specifies a relative expiration time for a high-resolution timer, the timer can expire as late as about a millisecond after the specified expiration time but it never expires early. For more information about the relationship between system clock resolution and timer accuracy, see [Timer Accuracy](timer-accuracy.md). + +If no high-resolution timers are set, the operating system typically runs the system clock at its default rate. However, if one or more high-resolution timers are set, the operating system might need to run the system clock at its maximum rate for at least a part of the time before these timers expire. + +To avoid unnecessarily increasing power consumption, the operating system runs the system clock at its maximum rate only when necessary to satisfy the timing requirements of high-resolution timers. For example, if a high-resolution timer is periodic, and its period spans several default system clock ticks, the operating system might run the system clock at its maximum rate only in the part of the timer period that immediately precedes each expiration. For the rest of the timer period, the system clock runs at its default rate. + +To prevent excessive power consumption, drivers should avoid setting the period of a long-running high-resolution timer to a value that is less than the default interval between system clock ticks. Otherwise, the operating system is forced to continously run the system clock at its maximum rate. + +Starting with Windows 8, a driver can call the [**ExQueryTimerResolution**](https://msdn.microsoft.com/library/windows/hardware/dn275969) routine to get the range of timer resolutions that are supported by the system clock. + +## Comparison to ExSetTimerResolution + + +Starting with Windows 2000, a driver can call the [**ExSetTimerResolution**](calling-exsettimerresolution-while-processing-a-power-irp.md) routine to change the time interval between successive system clock interrupts. For example, a driver can call this routine to change the system clock from its default rate to its maximum rate to improve timer accuracy. However, using **ExSetTimerResolution** has several disadvantages compared to using high-resolution timers created by **ExAllocateTimer**. + +First, after calling **ExSetTimerResolution** to temporarily increase the system clock rate, a driver must call **ExSetTimerResolution** a second time to restore the system clock to its default rate. Otherwise, the system clock timer continuously generates interrupts at the maximum rate, which might cause excessive power consumption. + +Second, a driver that uses the **ExSetTimerResolution** routine cannot optimize its temporary use of higher system clock rates as effectively as the operating system does for high-resolution timers. Thus, the system clock spends more time running at the maximum rate than is strictly necessary. + +Third, if multiple drivers concurrently use **ExSetTimerResolution** to improve timer accuracy, the system clock might run at its maximum rate for long periods. In contrast, the operating system globally coordinates the operation of multiple high-resolution timers so that the system clock runs at the maximum rate only when necessary to meet the timing requirements of these timers. + +Finally, using **ExSetTimerResolution** is inherently less accurate than using a high-resolution timer. After a driver calls **ExSetTimerResolution** to increase the system clock to its maximum rate, which is typically about a tick per millisecond, the driver might call a routine such as [**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292) to set the timer. If, in this call, the driver specifies a relative expiration time, the timer can expire up to about a millisecond earlier than or later than the specified expiration time. However, if a relative expiration time is specified for a high-resolution timer, the timer can expire up to about a millisecond later than the specified expiration time but it never expires early. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20High-Resolution%20Timers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/holding-incoming-irps-when-a-device-is-paused.md b/windows-driver-docs-pr/kernel/holding-incoming-irps-when-a-device-is-paused.md new file mode 100644 index 0000000000..3eda1f128d --- /dev/null +++ b/windows-driver-docs-pr/kernel/holding-incoming-irps-when-a-device-is-paused.md @@ -0,0 +1,54 @@ +--- +title: Holding Incoming IRPs When A Device Is Paused +author: windows-driver-content +description: Holding Incoming IRPs When A Device Is Paused +ms.assetid: 4964e06b-f1b9-4421-89d1-ad79ce7d7307 +keywords: ["holding IRPs", "IRPs WDK PnP", "I/O request packets WDK PnP", "pausing PnP devices"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Holding Incoming IRPs When A Device Is Paused + + +## + + +The drivers for a device must pause the device when its resources are being rebalanced. During resource rebalancing, some drivers pause the device in response to an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) request and other drivers delay pausing the device until they receive the [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request. In either case, the device must be paused when the **IRP\_MN\_STOP\_DEVICE** succeeds. + +The drivers must finish any IRPs in progress on the device and refrain from starting any new IRPs that require access to the device. + +To hold IRPs while a device is paused, a driver implements a procedure such as the following: + +1. In its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, define a flag in the device extension with a name like HOLD\_NEW\_REQUESTS. Clear the flag. + +2. Create a FIFO queue for holding IRPs. + + If the driver already queues IRPs, it can reuse the same queue because the driver is required to finish any outstanding requests before pausing the device. + + If the driver does not already have an IRP queue, it must create one in its *AddDevice* routine. What kind of queue it creates depends on how the driver flushes the queue. A driver might use an interlocked, doubly linked list and the **ExInterlocked*Xxx*List** routines. + +3. In its *DispatchPnP* code for **IRP\_MN\_QUERY\_STOP\_DEVICE** (or **IRP\_MN\_STOP\_DEVICE**), finish any outstanding requests and set the HOLD\_NEW\_REQUESTS flag. + +4. In a dispatch routine that accesses the device, such as [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) or [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), check whether the HOLD\_NEW\_REQUESTS flag is set. If so, the driver must mark the IRP pending and queue it. + + The driver's *DispatchPnP* routine must continue to process PnP IRPs rather than hold them and the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine must continue to process power IRPs. + +5. In *DispatchPnP*, in response to a start or cancel-stop IRP, clear the HOLD\_NEW\_REQUESTS flag and start the IRPs in the IRP-holding queue. + + These actions are probably the last steps for processing these PnP IRPs. For example, in response to a start IRP, the driver must first perform any operations to start the device and then it can start the IRPs in the IRP-holding queue. + + Errors in processing IRPs from the IRP-holding queue do not affect the status returned for the start or cancel-stop IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Holding%20Incoming%20IRPs%20When%20A%20Device%20Is%20Paused%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/hot-replace-of-partition-units.md b/windows-driver-docs-pr/kernel/hot-replace-of-partition-units.md new file mode 100644 index 0000000000..3607806320 --- /dev/null +++ b/windows-driver-docs-pr/kernel/hot-replace-of-partition-units.md @@ -0,0 +1,35 @@ +--- +title: Hot Replace of Partition Units +author: windows-driver-content +description: Hot Replace of Partition Units +ms.assetid: 6d50dc7d-6c3b-41e5-b6eb-aead9833dd1e +keywords: ["dynamic hardware partitioning WDK , hot replace", "hardware partitioning WDK dynamic , hot replace", "partitioning WDK dynamic hardware , hot replace", "hot replace WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hot Replace of Partition Units + + +On a dynamically partitionable server, you can dynamically replace partition units in a hardware partition at any time. This is known as a hot replace operation. When you replace a partition unit, the operating system puts the hardware partition into a pseudo S4 sleep state. To put the hardware partition into this special sleep state, the operating system sends an S4 *set power* power management request to all the device drivers in the system. However, unlike a typical S4 power state, the operating system does not write out the state of the system to a hibernation file. + +A device driver must support this pseudo S4 sleep state by correctly handling the *query power* and *set power* power management requests. A device driver should never reject a *query power* request. When a device driver receives an S4 *set power* power management request, it must transition its devices into a D3 device power state and stop all I/O operations. This includes any direct memory access (DMA) transfers that are currently in progress. By putting the driver's devices into a low power state, disabling interrupts, and halting all I/O operations that are in progress, the replace operation can continue without affecting the device driver. + +While a device driver's devices are in the D3 power state, the device driver should queue any new I/O requests that it receives. A device driver should use an I/O time-out period for the I/O requests that it processes. This time-out period must be long enough so that the I/O requests will not time out if they are stopped or queued during the replacement of a partition unit. When the operating system resumes from the pseudo S4 sleep state, the device driver can resume processing any stopped or queued I/O requests. + +For more information about how to implement support for power management in a device driver, see [Power Management](implementing-power-management.md). + +A device driver must not bind itself to a uniquely identifiable instance of system hardware such as a specific processor. Otherwise, the driver might fail if the partition unit that contains that hardware is replaced in the hardware partition. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Hot%20Replace%20of%20Partition%20Units%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/how-drivers-identify-32-bit-callers.md b/windows-driver-docs-pr/kernel/how-drivers-identify-32-bit-callers.md new file mode 100644 index 0000000000..6b8dabaab0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/how-drivers-identify-32-bit-callers.md @@ -0,0 +1,36 @@ +--- +title: How Drivers Identify 32-Bit Callers +author: windows-driver-content +description: How Drivers Identify 32-Bit Callers +ms.assetid: 9bfe9024-60f1-41ad-a034-160caaaa7801 +keywords: ["32-bit I/O support WDK 64-bit , identifying 32-bit callers", "identifying 32-bit callers", "32-bit caller identifications WDK 64-bit", "file system control codes WDK 64-bit", "FSCTL WDK 64-bit", "control codes WDK 64-bit", "I/O control codes WDK kernel , 32-bit I/O in 64-bit drivers", "IOCTLs WDK kernel , 32-bit I/O in 64-bit drivers", "caller identifications WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# How Drivers Identify 32-Bit Callers + + +## + + +There are two ways for drivers to determine whether the originator of an IOCTL or FSCTL request is a 32-bit or 64-bit application. The first is for the application to identify itself. The second is for the driver to determine on its own whether the application is 32-bit or 64-bit. + +The first technique involves defining a "64Bit" field in the IOCTL or FSCTL control code. This field contains a single bit, which is set only for 64-bit callers. Thus 64-bit callers identify themselves by using a separate set of 64-bit control codes in which this bit is set. 32-bit callers use a similar set of control codes in which this bit is not set. + +The second technique permits 32- and 64-bit applications to continue using the same IOCTL or FSCTL codes. Instead, the driver determines whether the user-mode process is 32- or 64-bit by calling [**IoIs32bitProcess**](https://msdn.microsoft.com/library/windows/hardware/ff549372). + +The first technique is more efficient, because the driver checks a bit flag instead of calling a kernel-mode routine. However, the second technique requires no changes to user-mode code. Which technique you should use depends on the requirements of your driver and the applications that send I/O requests to it. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20How%20Drivers%20Identify%2032-Bit%20Callers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/how-to-complete-an-irp-in-a-dispatch-routine.md b/windows-driver-docs-pr/kernel/how-to-complete-an-irp-in-a-dispatch-routine.md new file mode 100644 index 0000000000..5bde3214ac --- /dev/null +++ b/windows-driver-docs-pr/kernel/how-to-complete-an-irp-in-a-dispatch-routine.md @@ -0,0 +1,54 @@ +--- +title: How to Complete an IRP in a Dispatch Routine +author: windows-driver-content +description: How to Complete an IRP in a Dispatch Routine +ms.assetid: b29da791-e768-4f67-8e85-6cfbeca97220 +keywords: ["completing IRPs WDK kernel , dispatch routines", "dispatch routines WDK kernel , completing IRPs", "status information WDK IRPs", "I/O status blocks WDK kernel", "status blocks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# How to Complete an IRP in a Dispatch Routine + + +## + + +If an input IRP can be completed immediately, a dispatch routine does the following: + +1. Sets the **Status** and **Information** members of the IRP's I/O status block with appropriate values, in general: + + - The dispatch routine sets **Status** either to STATUS\_SUCCESS or to an appropriate error (STATUS\_*XXX*), which can be the value returned by a call to a support routine or, for certain synchronous requests, by a lower driver. + + If a lower-level driver returns STATUS\_PENDING, a higher-level driver should not call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) for the IRP, with one exception: The higher-level driver can use an event to synchronize between its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine and its dispatch routine, in which case the *IoCompletion* routine signals the event and returns STATUS\_MORE\_PROCESSING\_REQUIRED. The dispatch routine waits for the event and then calls **IoCompleteRequest** to complete the IRP. + + - It sets **Information** to the number of bytes successfully transferred if a request to transfer data, such as a read or write request, was satisfied. + + - It sets **Information** to a value that varies according to the specific request for other IRPs that it completes with STATUS\_SUCCESS. + + - It sets **Information** to a value that varies according to the specific request for IRPs that it completes with a warning STATUS\_*XXX*. For example, it would set **Information** to the number of bytes transferred for such a warning as STATUS\_BUFFER\_OVERFLOW. + + - Usually, it sets **Information** to zero for requests that it completes with an error STATUS\_*XXX*. + +2. Calls **IoCompleteRequest** with the IRP and with *PriorityBoost* = IO\_NO\_INCREMENT. + +3. Returns the appropriate STATUS\_*XXX* that it already set in the I/O status block. Note that a call to **IoCompleteRequest** makes the given IRP inaccessible by the caller, so the return value from a dispatch routine cannot be set from the I/O status block of an already completed IRP. + +**Follow this implementation guideline for calling IoCompleteRequest with an IRP:** + +Always release any spin lock(s) the driver is holding before calling **IoCompleteRequest**. + +It takes an indeterminate amount of time to complete an IRP, particularly in a chain of layered drivers. Moreover, a deadlock can occur if a higher-level driver's *IoCompletion* routine sends an IRP back down to a lower driver that is holding a spin lock. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20How%20to%20Complete%20an%20IRP%20in%20a%20Dispatch%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/i-o-programming-techniques.md b/windows-driver-docs-pr/kernel/i-o-programming-techniques.md new file mode 100644 index 0000000000..66842a5bf2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/i-o-programming-techniques.md @@ -0,0 +1,42 @@ +--- +title: I/O Programming Techniques +author: windows-driver-content +description: I/O Programming Techniques +ms.assetid: 642746ba-d94e-4ffb-ba58-bb8a5650bea3 +keywords: ["I/O WDK kernel", "kernel-mode drivers WDK , I/O techniques", "IO WDK See I/O WDK", "transferring data WDK kernel", "data transfers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# I/O Programming Techniques + + +## + + +This section describes programming techniques that can be used to work with objects managed by the I/O manager. The following technology areas are discussed: + +[General I/O Programming Techniques](general-i-o-programming-techniques.md) + +[Methods for Accessing Data Buffers](methods-for-accessing-data-buffers.md) + +[DMA Programming Techniques](dma-programming-techniques.md) + +[PIO Programming Techniques](pio-techniques.md) + +[Legacy I/O Programming](legacy-i-o-programming.md) + +For architectural information on the I/O manager, see [Windows I/O Manager](windows-kernel-mode-i-o-manager.md). For reference information on I/O manager, see [I/O Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff551797). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20I/O%20Programming%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/i-o-stack-locations.md b/windows-driver-docs-pr/kernel/i-o-stack-locations.md new file mode 100644 index 0000000000..c73782a00d --- /dev/null +++ b/windows-driver-docs-pr/kernel/i-o-stack-locations.md @@ -0,0 +1,86 @@ +--- +title: I/O Stack Locations +author: windows-driver-content +description: I/O Stack Locations +ms.assetid: 62c8ee00-c7cb-4aa1-90ab-b8bedbd818ee +keywords: ["IRPs WDK kernel , I/O stack locations", "I/O stack locations WDK kernel", "stack locations WDK kernel", "layered driver I/O stack locations WDK kernel", "IRPs WDK kernel , contents", "IO_STACK_LOCATION structure"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# I/O Stack Locations + + +## + + +The I/O manager gives each driver in a chain of layered drivers an I/O stack location for every IRP that it sets up. Each I/O stack location consists of an [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure. + +The I/O manager creates an array of I/O stack locations for each IRP, with an array element corresponding to each driver in a chain of layered drivers. Each driver owns one of the stack locations in the packet and calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) to obtain driver-specific information about the I/O operation. + +Each driver in such a chain is responsible for calling [**IoGetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549266), then setting up the next-lower driver's I/O stack location. Any higher-level driver's I/O stack location can also be used to store context about an operation so that the driver's [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine can perform its cleanup operations. + +The [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure shows two I/O stack locations in the original IRP because it shows two drivers, a file system driver and a mass-storage device driver. The driver-allocated IRPs in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure do not have a stack location for the FSD that created them. Any higher-level driver that allocates IRPs for lower-level drivers also determines how many I/O stack locations the new IRPs should have, according to the **StackSize** value of the next-lower driver's device object. + +The following figure shows the contents of the IRP in more detail. + +![diagram illustrating the contents of i/o stack location in an irp](images/2irpios.png) + +As shown in the figure, each driver-specific I/O stack location in an IRP contains the following general information: + +- The major function code (**IRP\_MJ\_*XXX***), indicating the basic operation the driver should carry out + +- For some major function codes handled by FSDs, higher-level SCSI drivers, and all PnP drivers, a minor function code (**IRP\_MN\_*XXX***), indicating which subcase of the basic operation the driver should carry out + +- A set of operation-specific arguments, such as the length and starting location of a buffer into which or from which the driver transfers data + +- A pointer to the driver-created device object, representing the target (physical, logical, or virtual) device for the requested operation + +- A pointer to the file object, representing an open file, device, directory, or volume + + A file system driver accesses the file object through its I/O stack location in IRPs. Other drivers usually ignore the file object. + +The set of IRP major and minor function codes that a particular driver handles can be device-type-specific. However, lowest-level drivers and intermediate drivers (including PnP function and filter drivers) usually handle the following set of basic requests: + +- [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) — open the target device object, indicating that it is present and available for I/O operations + +- [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) — transfer data from the device + +- [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) — transfer data to the device + +- [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) — set up (or reset) the device, according to a system-defined, device-type-specific I/O control code (IOCTL) + +- [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720) — close the target device object + +- [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) — perform a Plug and Play operation on the device. An **IRP\_MJ\_PNP** request is sent by the PnP manager through the I/O manager. + +- [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) — perform a power operation on the device. An **IRP\_MJ\_POWER** request is sent by the power manager through the I/O manager. + +For more information about the major IRP function codes that drivers are required to handle, see [IRP Major Function Codes](https://msdn.microsoft.com/library/windows/hardware/ff550710). + +In general, the I/O manager sends IRPs with at least two I/O stack locations to mass-storage device drivers because a file system is layered over other drivers for mass-storage devices. The I/O manager sends IRPs with a single stack location to any driver that has no other driver layered above it. + +However, the I/O manager provides support for adding a new driver to any chain of existing drivers in the system. For example, an intermediate [*mirror driver*](https://msdn.microsoft.com/library/windows/hardware/ff556308#wdkgloss-mirror-driver) that backs up data on a given disk partition might be inserted between a pair of drivers, such as the file system driver and lowest-level driver shown in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure. When this new driver attaches itself to the device stack, the I/O manager adjusts the number of I/O stack locations in all IRPs it sends to the file system, mirror, and lowest-level drivers. Every IRP that the file system in the [Processing IRPs in Layered Drivers](example-i-o-request---the-details.md#ddk-example-i-o-request---the-details-kg) figure allocated would also contain another I/O stack location for such a new mirror driver. + +Note that this support for adding new drivers to an existing chain implies certain restrictions on any particular driver's access to the I/O stack locations in IRPs: + +- A higher-level driver in a chain of layered drivers can safely access only its own and the next-lower-level driver's I/O stack locations in any IRP. Such a driver must set up the I/O stack location for the next-lower-level driver in IRPs. However, when designing such a higher-level driver, you cannot predict when (or whether) a new driver will be added to the existing chain just below your driver. + + Therefore, you should assume that any subsequently added driver will handle the same IRP major function codes (**IRP\_MJ\_*XXX***) as the displaced next-lower-level driver did. + +- The lowest-level driver in a chain of layered drivers can safely access only its own I/O stack location in any IRP. When designing such a driver, you cannot predict when (or whether) a new driver will be added to the existing chain above your device driver. + + In designing a lowest-level driver, assume that the driver can continue to process IRPs using the information passed in its own I/O stack location, whatever the originating source of a given IRP and however many drivers are layered above it. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20I/O%20Stack%20Locations%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/i-o-status-blocks.md b/windows-driver-docs-pr/kernel/i-o-status-blocks.md new file mode 100644 index 0000000000..3f75b27041 --- /dev/null +++ b/windows-driver-docs-pr/kernel/i-o-status-blocks.md @@ -0,0 +1,38 @@ +--- +title: I/O Status Blocks +author: windows-driver-content +description: I/O Status Blocks +ms.assetid: 59147bd1-6cd7-4fbe-b7bc-52e09ab88576 +keywords: ["IRPs WDK kernel , I/O status blocks", "I/O status blocks WDK kernel", "status blocks WDK kernel", "IO_STATUS_BLOCK structure", "status information WDK IRPs", "IRPs WDK kernel , status information"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# I/O Status Blocks + + +## + + +An I/O status block, which consists of an [**IO\_STATUS\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/ff550671) structure, is a part of each [**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694). An I/O status block serves two purposes: + +- It provides a higher-level driver's [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine a way of determining whether the service worked when the IRP is completed. + +- It provides more information about why the service either worked or did not work. + +Upon completion of a IRP, the **Status** field indicates whether the drivers that processed the IRP actually satisfied the request or failed the IRP with an error status. The **Information** field supplies the caller with more information about what actually occurred. For example, it contains the number of bytes actually transferred after a read or write operation. + +For more information, see [Setting the I/O Status Block in an IRP](processing-irps-in-a-lowest-level-driver.md#ddk-setting-the-i-o-status-block-in-an-irp-kg). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20I/O%20Status%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/images/16cchdma.png b/windows-driver-docs-pr/kernel/images/16cchdma.png new file mode 100644 index 0000000000..85ceb791c5 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/16cchdma.png differ diff --git a/windows-driver-docs-pr/kernel/images/16ispnlk.png b/windows-driver-docs-pr/kernel/images/16ispnlk.png new file mode 100644 index 0000000000..359ded4bdd Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/16ispnlk.png differ diff --git a/windows-driver-docs-pr/kernel/images/16ntstat.png b/windows-driver-docs-pr/kernel/images/16ntstat.png new file mode 100644 index 0000000000..c419f172fe Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/16ntstat.png differ diff --git a/windows-driver-docs-pr/kernel/images/16vrtmem.gif b/windows-driver-docs-pr/kernel/images/16vrtmem.gif new file mode 100644 index 0000000000..6b8890c420 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/16vrtmem.gif differ diff --git a/windows-driver-docs-pr/kernel/images/1drvlyrs.png b/windows-driver-docs-pr/kernel/images/1drvlyrs.png new file mode 100644 index 0000000000..5198457483 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/1drvlyrs.png differ diff --git a/windows-driver-docs-pr/kernel/images/24drvobj.png b/windows-driver-docs-pr/kernel/images/24drvobj.png new file mode 100644 index 0000000000..11863b1675 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/24drvobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/2girpeg.png b/windows-driver-docs-pr/kernel/images/2girpeg.png new file mode 100644 index 0000000000..0688178492 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2girpeg.png differ diff --git a/windows-driver-docs-pr/kernel/images/2grsover.png b/windows-driver-docs-pr/kernel/images/2grsover.png new file mode 100644 index 0000000000..1dab72a984 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2grsover.png differ diff --git a/windows-driver-docs-pr/kernel/images/2iocsqinitializeex.png b/windows-driver-docs-pr/kernel/images/2iocsqinitializeex.png new file mode 100644 index 0000000000..0f22ece71a Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2iocsqinitializeex.png differ diff --git a/windows-driver-docs-pr/kernel/images/2irpios.png b/windows-driver-docs-pr/kernel/images/2irpios.png new file mode 100644 index 0000000000..76e07e5a8a Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2irpios.png differ diff --git a/windows-driver-docs-pr/kernel/images/2kbdmuhw.png b/windows-driver-docs-pr/kernel/images/2kbdmuhw.png new file mode 100644 index 0000000000..fdaf29684a Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2kbdmuhw.png differ diff --git a/windows-driver-docs-pr/kernel/images/2opendev.png b/windows-driver-docs-pr/kernel/images/2opendev.png new file mode 100644 index 0000000000..91585a3411 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2opendev.png differ diff --git a/windows-driver-docs-pr/kernel/images/2sampdos.png b/windows-driver-docs-pr/kernel/images/2sampdos.png new file mode 100644 index 0000000000..b7c5a42b5f Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2sampdos.png differ diff --git a/windows-driver-docs-pr/kernel/images/2samplyr.png b/windows-driver-docs-pr/kernel/images/2samplyr.png new file mode 100644 index 0000000000..17bdd2224f Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/2samplyr.png differ diff --git a/windows-driver-docs-pr/kernel/images/3addrspc.png b/windows-driver-docs-pr/kernel/images/3addrspc.png new file mode 100644 index 0000000000..43bcfd80fe Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3addrspc.png differ diff --git a/windows-driver-docs-pr/kernel/images/3crt-cbk.png b/windows-driver-docs-pr/kernel/images/3crt-cbk.png new file mode 100644 index 0000000000..07a9ddda1f Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3crt-cbk.png differ diff --git a/windows-driver-docs-pr/kernel/images/3cstmdpc.png b/windows-driver-docs-pr/kernel/images/3cstmdpc.png new file mode 100644 index 0000000000..5526442085 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3cstmdpc.png differ diff --git a/windows-driver-docs-pr/kernel/images/3ctlaloc.png b/windows-driver-docs-pr/kernel/images/3ctlaloc.png new file mode 100644 index 0000000000..f39ddd3a4d Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3ctlaloc.png differ diff --git a/windows-driver-docs-pr/kernel/images/3ctlrobj.png b/windows-driver-docs-pr/kernel/images/3ctlrobj.png new file mode 100644 index 0000000000..21cbc2757d Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3ctlrobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/3devext.png b/windows-driver-docs-pr/kernel/images/3devext.png new file mode 100644 index 0000000000..98d8275c24 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3devext.png differ diff --git a/windows-driver-docs-pr/kernel/images/3devobj.png b/windows-driver-docs-pr/kernel/images/3devobj.png new file mode 100644 index 0000000000..4a445a21f7 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3devobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/3devqobj.png b/windows-driver-docs-pr/kernel/images/3devqobj.png new file mode 100644 index 0000000000..78965aaa41 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3devqobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/3dmabus.png b/windows-driver-docs-pr/kernel/images/3dmabus.png new file mode 100644 index 0000000000..13bc8fa982 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3dmabus.png differ diff --git a/windows-driver-docs-pr/kernel/images/3dmapreg.png b/windows-driver-docs-pr/kernel/images/3dmapreg.png new file mode 100644 index 0000000000..1bbcc8e2cb Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3dmapreg.png differ diff --git a/windows-driver-docs-pr/kernel/images/3dmaptsf.png b/windows-driver-docs-pr/kernel/images/3dmaptsf.png new file mode 100644 index 0000000000..b96ff1e0c1 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3dmaptsf.png differ diff --git a/windows-driver-docs-pr/kernel/images/3dpcisr.png b/windows-driver-docs-pr/kernel/images/3dpcisr.png new file mode 100644 index 0000000000..c4123a337e Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3dpcisr.png differ diff --git a/windows-driver-docs-pr/kernel/images/3evntobj.png b/windows-driver-docs-pr/kernel/images/3evntobj.png new file mode 100644 index 0000000000..980148fc9e Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3evntobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/3halcbff.png b/windows-driver-docs-pr/kernel/images/3halcbff.png new file mode 100644 index 0000000000..a17818ce14 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3halcbff.png differ diff --git a/windows-driver-docs-pr/kernel/images/3hlsysbf.png b/windows-driver-docs-pr/kernel/images/3hlsysbf.png new file mode 100644 index 0000000000..181c92d84c Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3hlsysbf.png differ diff --git a/windows-driver-docs-pr/kernel/images/3intlokq.png b/windows-driver-docs-pr/kernel/images/3intlokq.png new file mode 100644 index 0000000000..bf12947e8d Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3intlokq.png differ diff --git a/windows-driver-docs-pr/kernel/images/3iocsqremoveirp.png b/windows-driver-docs-pr/kernel/images/3iocsqremoveirp.png new file mode 100644 index 0000000000..863b3024a6 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3iocsqremoveirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/3iotmer.png b/windows-driver-docs-pr/kernel/images/3iotmer.png new file mode 100644 index 0000000000..c91c9c8234 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3iotmer.png differ diff --git a/windows-driver-docs-pr/kernel/images/3ketimer.png b/windows-driver-docs-pr/kernel/images/3ketimer.png new file mode 100644 index 0000000000..e2de737740 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3ketimer.png differ diff --git a/windows-driver-docs-pr/kernel/images/3ketmdpc.png b/windows-driver-docs-pr/kernel/images/3ketmdpc.png new file mode 100644 index 0000000000..bdf9a7b088 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3ketmdpc.png differ diff --git a/windows-driver-docs-pr/kernel/images/3mdlbffr.png b/windows-driver-docs-pr/kernel/images/3mdlbffr.png new file mode 100644 index 0000000000..66181a1637 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3mdlbffr.png differ diff --git a/windows-driver-docs-pr/kernel/images/3mdldrct.png b/windows-driver-docs-pr/kernel/images/3mdldrct.png new file mode 100644 index 0000000000..2d7ea31676 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3mdldrct.png differ diff --git a/windows-driver-docs-pr/kernel/images/3mdlpio.png b/windows-driver-docs-pr/kernel/images/3mdlpio.png new file mode 100644 index 0000000000..d3b5aa6c45 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3mdlpio.png differ diff --git a/windows-driver-docs-pr/kernel/images/3mutxobj.png b/windows-driver-docs-pr/kernel/images/3mutxobj.png new file mode 100644 index 0000000000..19fce16087 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3mutxobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/3reg-cbk.png b/windows-driver-docs-pr/kernel/images/3reg-cbk.png new file mode 100644 index 0000000000..04f1a5a377 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3reg-cbk.png differ diff --git a/windows-driver-docs-pr/kernel/images/3semobj.png b/windows-driver-docs-pr/kernel/images/3semobj.png new file mode 100644 index 0000000000..0f7aaca0fd Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/3semobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/4hiddirp.png b/windows-driver-docs-pr/kernel/images/4hiddirp.png new file mode 100644 index 0000000000..8064b4336f Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/4hiddirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/4iocsqremovenextirp.png b/windows-driver-docs-pr/kernel/images/4iocsqremovenextirp.png new file mode 100644 index 0000000000..6e6bb94477 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/4iocsqremovenextirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/4loddirp.png b/windows-driver-docs-pr/kernel/images/4loddirp.png new file mode 100644 index 0000000000..c292fc66a7 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/4loddirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/4snxtpak.png b/windows-driver-docs-pr/kernel/images/4snxtpak.png new file mode 100644 index 0000000000..fc31e8150b Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/4snxtpak.png differ diff --git a/windows-driver-docs-pr/kernel/images/4strtpak.png b/windows-driver-docs-pr/kernel/images/4strtpak.png new file mode 100644 index 0000000000..c7884e521d Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/4strtpak.png differ diff --git a/windows-driver-docs-pr/kernel/images/5cancelingirp.png b/windows-driver-docs-pr/kernel/images/5cancelingirp.png new file mode 100644 index 0000000000..c5816ff416 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/5cancelingirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/addstart.png b/windows-driver-docs-pr/kernel/images/addstart.png new file mode 100644 index 0000000000..4762e6ec72 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/addstart.png differ diff --git a/windows-driver-docs-pr/kernel/images/clfsactivelog.gif b/windows-driver-docs-pr/kernel/images/clfsactivelog.gif new file mode 100644 index 0000000000..ad0a0c8b4c Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/clfsactivelog.gif differ diff --git a/windows-driver-docs-pr/kernel/images/clfscontainers.gif b/windows-driver-docs-pr/kernel/images/clfscontainers.gif new file mode 100644 index 0000000000..8547334d45 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/clfscontainers.gif differ diff --git a/windows-driver-docs-pr/kernel/images/clfslogicalcontainers.gif b/windows-driver-docs-pr/kernel/images/clfslogicalcontainers.gif new file mode 100644 index 0000000000..4559d58087 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/clfslogicalcontainers.gif differ diff --git a/windows-driver-docs-pr/kernel/images/clfsrecordchains.gif b/windows-driver-docs-pr/kernel/images/clfsrecordchains.gif new file mode 100644 index 0000000000..259a174c20 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/clfsrecordchains.gif differ diff --git a/windows-driver-docs-pr/kernel/images/clfsundonext.gif b/windows-driver-docs-pr/kernel/images/clfsundonext.gif new file mode 100644 index 0000000000..129be87d35 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/clfsundonext.gif differ diff --git a/windows-driver-docs-pr/kernel/images/comp-waitwake.png b/windows-driver-docs-pr/kernel/images/comp-waitwake.png new file mode 100644 index 0000000000..887c782d64 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/comp-waitwake.png differ diff --git a/windows-driver-docs-pr/kernel/images/credvnd.png b/windows-driver-docs-pr/kernel/images/credvnd.png new file mode 100644 index 0000000000..ff28218c29 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/credvnd.png differ diff --git a/windows-driver-docs-pr/kernel/images/d0-comp.png b/windows-driver-docs-pr/kernel/images/d0-comp.png new file mode 100644 index 0000000000..557f6a1e03 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/d0-comp.png differ diff --git a/windows-driver-docs-pr/kernel/images/delay1.png b/windows-driver-docs-pr/kernel/images/delay1.png new file mode 100644 index 0000000000..4eb8ff53c5 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/delay1.png differ diff --git a/windows-driver-docs-pr/kernel/images/delay2.png b/windows-driver-docs-pr/kernel/images/delay2.png new file mode 100644 index 0000000000..28e2b0272c Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/delay2.png differ diff --git a/windows-driver-docs-pr/kernel/images/devd0.png b/windows-driver-docs-pr/kernel/images/devd0.png new file mode 100644 index 0000000000..642c8fa39a Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/devd0.png differ diff --git a/windows-driver-docs-pr/kernel/images/devd3.png b/windows-driver-docs-pr/kernel/images/devd3.png new file mode 100644 index 0000000000..4f17235bbf Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/devd3.png differ diff --git a/windows-driver-docs-pr/kernel/images/devpoirp.png b/windows-driver-docs-pr/kernel/images/devpoirp.png new file mode 100644 index 0000000000..032cb5d4e4 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/devpoirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/devtree.png b/windows-driver-docs-pr/kernel/images/devtree.png new file mode 100644 index 0000000000..7aa7a9455c Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/devtree.png differ diff --git a/windows-driver-docs-pr/kernel/images/dhparch.gif b/windows-driver-docs-pr/kernel/images/dhparch.gif new file mode 100644 index 0000000000..29e43645b0 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/dhparch.gif differ diff --git a/windows-driver-docs-pr/kernel/images/drvlyr.png b/windows-driver-docs-pr/kernel/images/drvlyr.png new file mode 100644 index 0000000000..3c81863844 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/drvlyr.png differ diff --git a/windows-driver-docs-pr/kernel/images/dxpostates.png b/windows-driver-docs-pr/kernel/images/dxpostates.png new file mode 100644 index 0000000000..01b7c33937 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/dxpostates.png differ diff --git a/windows-driver-docs-pr/kernel/images/errorlogentry.png b/windows-driver-docs-pr/kernel/images/errorlogentry.png new file mode 100644 index 0000000000..3de92922a3 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/errorlogentry.png differ diff --git a/windows-driver-docs-pr/kernel/images/event-properties.png b/windows-driver-docs-pr/kernel/images/event-properties.png new file mode 100644 index 0000000000..0c0ae26d7d Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/event-properties.png differ diff --git a/windows-driver-docs-pr/kernel/images/event-viewer.png b/windows-driver-docs-pr/kernel/images/event-viewer.png new file mode 100644 index 0000000000..09683e9434 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/event-viewer.png differ diff --git a/windows-driver-docs-pr/kernel/images/finddrv.png b/windows-driver-docs-pr/kernel/images/finddrv.png new file mode 100644 index 0000000000..4af587f62c Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/finddrv.png differ diff --git a/windows-driver-docs-pr/kernel/images/hotplug.png b/windows-driver-docs-pr/kernel/images/hotplug.png new file mode 100644 index 0000000000..a5fd78a85e Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/hotplug.png differ diff --git a/windows-driver-docs-pr/kernel/images/iocsqinsertirp.png b/windows-driver-docs-pr/kernel/images/iocsqinsertirp.png new file mode 100644 index 0000000000..25951b0f03 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/iocsqinsertirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/ioctl-1.png b/windows-driver-docs-pr/kernel/images/ioctl-1.png new file mode 100644 index 0000000000..b1cff3fcdc Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/ioctl-1.png differ diff --git a/windows-driver-docs-pr/kernel/images/joydobj.png b/windows-driver-docs-pr/kernel/images/joydobj.png new file mode 100644 index 0000000000..afb567853b Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/joydobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/joydobj2.png b/windows-driver-docs-pr/kernel/images/joydobj2.png new file mode 100644 index 0000000000..ed99139b32 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/joydobj2.png differ diff --git a/windows-driver-docs-pr/kernel/images/ntarch.png b/windows-driver-docs-pr/kernel/images/ntarch.png new file mode 100644 index 0000000000..3d7e52f112 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/ntarch.png differ diff --git a/windows-driver-docs-pr/kernel/images/objlyr.png b/windows-driver-docs-pr/kernel/images/objlyr.png new file mode 100644 index 0000000000..237d0101d7 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/objlyr.png differ diff --git a/windows-driver-docs-pr/kernel/images/passirp.png b/windows-driver-docs-pr/kernel/images/passirp.png new file mode 100644 index 0000000000..fbe7c9f8d4 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/passirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/passirpvista.png b/windows-driver-docs-pr/kernel/images/passirpvista.png new file mode 100644 index 0000000000..8b3ecc61d7 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/passirpvista.png differ diff --git a/windows-driver-docs-pr/kernel/images/passpnp.png b/windows-driver-docs-pr/kernel/images/passpnp.png new file mode 100644 index 0000000000..639c1b06cd Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/passpnp.png differ diff --git a/windows-driver-docs-pr/kernel/images/pnp-states.png b/windows-driver-docs-pr/kernel/images/pnp-states.png new file mode 100644 index 0000000000..8bfea0388e Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/pnp-states.png differ diff --git a/windows-driver-docs-pr/kernel/images/pnpcomp.png b/windows-driver-docs-pr/kernel/images/pnpcomp.png new file mode 100644 index 0000000000..302696f995 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/pnpcomp.png differ diff --git a/windows-driver-docs-pr/kernel/images/power-comp.png b/windows-driver-docs-pr/kernel/images/power-comp.png new file mode 100644 index 0000000000..771f7230ec Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/power-comp.png differ diff --git a/windows-driver-docs-pr/kernel/images/qdrstaks.png b/windows-driver-docs-pr/kernel/images/qdrstaks.png new file mode 100644 index 0000000000..9e645b93ad Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/qdrstaks.png differ diff --git a/windows-driver-docs-pr/kernel/images/rem-irps.png b/windows-driver-docs-pr/kernel/images/rem-irps.png new file mode 100644 index 0000000000..911ccc77b1 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/rem-irps.png differ diff --git a/windows-driver-docs-pr/kernel/images/s2dirp.png b/windows-driver-docs-pr/kernel/images/s2dirp.png new file mode 100644 index 0000000000..2d1aeebc5a Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/s2dirp.png differ diff --git a/windows-driver-docs-pr/kernel/images/send-waitwake.png b/windows-driver-docs-pr/kernel/images/send-waitwake.png new file mode 100644 index 0000000000..df36c092c2 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/send-waitwake.png differ diff --git a/windows-driver-docs-pr/kernel/images/stop-irps.png b/windows-driver-docs-pr/kernel/images/stop-irps.png new file mode 100644 index 0000000000..28970388a3 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/stop-irps.png differ diff --git a/windows-driver-docs-pr/kernel/images/sysstate.png b/windows-driver-docs-pr/kernel/images/sysstate.png new file mode 100644 index 0000000000..3d1bdbb949 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/sysstate.png differ diff --git a/windows-driver-docs-pr/kernel/images/usbjoydr.png b/windows-driver-docs-pr/kernel/images/usbjoydr.png new file mode 100644 index 0000000000..97999793b0 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/usbjoydr.png differ diff --git a/windows-driver-docs-pr/kernel/images/usbjoyhw.png b/windows-driver-docs-pr/kernel/images/usbjoyhw.png new file mode 100644 index 0000000000..4bd4886fd9 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/usbjoyhw.png differ diff --git a/windows-driver-docs-pr/kernel/images/wmi1a.png b/windows-driver-docs-pr/kernel/images/wmi1a.png new file mode 100644 index 0000000000..904d1bc483 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wmi1a.png differ diff --git a/windows-driver-docs-pr/kernel/images/wnode-all-data.png b/windows-driver-docs-pr/kernel/images/wnode-all-data.png new file mode 100644 index 0000000000..43a2e49fa5 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wnode-all-data.png differ diff --git a/windows-driver-docs-pr/kernel/images/wnode-single-instance.png b/windows-driver-docs-pr/kernel/images/wnode-single-instance.png new file mode 100644 index 0000000000..8fcf2d0876 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wnode-single-instance.png differ diff --git a/windows-driver-docs-pr/kernel/images/wwcascade.png b/windows-driver-docs-pr/kernel/images/wwcascade.png new file mode 100644 index 0000000000..928393e8b1 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wwcascade.png differ diff --git a/windows-driver-docs-pr/kernel/images/wwdobj.png b/windows-driver-docs-pr/kernel/images/wwdobj.png new file mode 100644 index 0000000000..5be3810986 Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wwdobj.png differ diff --git a/windows-driver-docs-pr/kernel/images/wwhw.png b/windows-driver-docs-pr/kernel/images/wwhw.png new file mode 100644 index 0000000000..773a38e2aa Binary files /dev/null and b/windows-driver-docs-pr/kernel/images/wwhw.png differ diff --git a/windows-driver-docs-pr/kernel/implementing-a-cancel-routine.md b/windows-driver-docs-pr/kernel/implementing-a-cancel-routine.md new file mode 100644 index 0000000000..b0d6ce7a07 --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-a-cancel-routine.md @@ -0,0 +1,54 @@ +--- +title: Implementing a Cancel Routine +author: windows-driver-content +description: Implementing a Cancel Routine +ms.assetid: 243b623b-317c-4084-a753-940c91c4cc50 +keywords: ["canceling IRPs, guidelines", "Cancel routines, guidelines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing a Cancel Routine + + +## + + +The I/O manager calls a driver-supplied [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine with an input IRP to be canceled and a *DeviceObject* pointer that represents the target device for the I/O request. + +The IRP could be one that the driver's [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine has queued just as the current Win32 application is being closed by the user. The IRP also could be one that a higher-level driver explicitly canceled, depending on the nature of the underlying device. + +When the *Cancel* routine is called, the input IRP might already be the **CurrentIrp** in the target device object or might already be in the device queue associated with the target device object if the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. If the driver has no *StartIo* routine, the IRP might be in a driver-managed internal queue of IRPs when its *Cancel* routine is called. In any case, before the I/O manager calls the *Cancel* routine for the incoming IRP, the I/O manager sets the **Cancel** member in this IRP to **TRUE** and sets the **CancelRoutine** member in the IRP to **NULL**. + +The *Cancel* routine for a master IRP that has associated IRPs is responsible for calling [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338) to cancel those associated IRPs. + +All *Cancel* routines must follow these guidelines: + +- Call [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550) to release the system's cancel spin lock. + +- Set the I/O status block's **Status** member to STATUS\_CANCELLED, and set its **Information** member to zero. + +- Complete the specified IRP by calling [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +- Because a *Cancel* routine is always called with the system cancel spin lock held, this routine must not call [**IoAcquireCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff548196) unless it calls **IoReleaseCancelSpinLock** first. + +- A *Cancel* routine cannot be holding the system cancel spin lock when it returns control. That is, every *Cancel* routine must call **IoReleaseCancelSpinLock** at least once before it returns control. + +- If it calls **IoAcquireCancelSpinLock**, a *Cancel* routine must make the reciprocal call to **IoReleaseCancelSpinLock** as quickly as possible. + +- Never call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with an IRP while holding a spin lock. Attempting to complete an IRP while holding a spin lock can cause deadlocks. + +For more information about implementing a *Cancel* routine, see the [I/O Completion/Cancellation Guidelines](http://go.microsoft.com/fwlink/p/?linkid=51436) white paper on the Microsoft Windows Hardware Developer Central (WHDC) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20a%20Cancel%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-an-iocompletion-routine.md b/windows-driver-docs-pr/kernel/implementing-an-iocompletion-routine.md new file mode 100644 index 0000000000..076ec18c5e --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-an-iocompletion-routine.md @@ -0,0 +1,93 @@ +--- +title: Implementing an IoCompletion Routine +author: windows-driver-content +description: Implementing an IoCompletion Routine +ms.assetid: 669860b1-5e85-4b28-a9b1-1ccf8c689b7a +keywords: ["IoCompletion routines", "IoCompleteRequest routine", "priority boosts WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing an IoCompletion Routine + + +## + + +On entry, an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine receives a *Context* pointer. When a dispatch routine calls [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679), it can supply a *Context* pointer. This pointer can reference whatever driver-determined context information the *IoCompletion* routine requires to process an IRP. Note that the context area cannot be pageable because the *IoCompletion* routine can be called at IRQL = DISPATCH\_LEVEL. + +**Consider the following implementation guidelines for IoCompletion routines:** + +- An *IoCompletion* routine can check the IRP's [I/O status block](i-o-status-blocks.md) to determine the result of the I/O operation. + +- If the input IRP was allocated by the dispatch routine using [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) or [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310), the *IoCompletion* routine must call [**IoFreeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549113) to release that IRP, preferably before it completes the original IRP. + + - The *IoCompletion* routine must release any per-IRP resources the dispatch routine allocated for the driver-allocated IRP, preferably before it frees the corresponding IRP. + + For example, if the dispatch routine allocates an MDL with [**IoAllocateMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548263) and calls [**IoBuildPartialMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548324) for a partial-transfer IRP it allocates, the *IoCompletion* routine must release the MDL with [**IoFreeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff549126). If it allocates resources to maintain state about the original IRP, it must free those resources, preferably before it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the original IRP and definitely before it returns control. + + In general, before freeing or completing an IRP, the *IoCompletion* routine should free any per-IRP resources allocated by the Dispatch routine. Otherwise, the driver must maintain state about the resources to be freed before its *IoCompletion* routine returns control from completing the original request. + + - If the *IoCompletion* routine cannot complete the original IRP with STATUS\_SUCCESS, it must set the I/O status block in the original IRP to the value returned in the driver-allocated IRP that caused the *IoCompletion* routine to fail the original request. + + - If the *IoCompletion* routine will complete the original request with STATUS\_PENDING, it must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) with the original IRP before it calls **IoCompleteRequest**. + + - If the *IoCompletion* routine must fail the original IRP with an error STATUS\_*XXX*, it can [log an error](logging-errors.md). However, it is the responsibility of the underlying device driver to log any device I/O errors that occur, so *IoCompletion* routines usually do not log errors. + + - When the *IoCompletion* routine has processed and freed the driver-allocated IRP, the routine must return control with STATUS\_MORE\_PROCESSING\_REQUIRED. + + Returning STATUS\_MORE\_PROCESSING\_REQUIRED from the *IoCompletion* routine forestalls the I/O manager's completion processing for a driver-allocated and freed IRP. A second call to **IoCompleteRequest** causes the I/O manager to resume calling the IRP's completion routines, starting with the completion routine immediately above the routine that returned STATUS\_MORE\_PROCESSING\_REQUIRED. + +- If the *IoCompletion* routine reuses an incoming IRP to send one or more requests to lower drivers, or if the routine retries failed operations, it should update whatever context the *IoCompletion* routine maintains about each reuse or retry of the IRP. Then it can set up the next-lower driver's I/O stack location again, call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) with its own entry point, and call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) for the IRP. + + - The *IoCompletion* routine should not call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) at each reuse or retry of the IRP. + + The dispatch routine already marked the original IRP as pending. Until all drivers in the chain complete the original IRP with **IoCompleteRequest**, it remains pending. + + - Before retrying a request, the *IoCompletion* routine should reset the I/O status block with STATUS\_SUCCESS for **Status** and zero for **Information**, possibly after saving the returned error information. + + For each retry, the *IoCompletion* routine usually decrements a retry count set up by the Dispatch routine. Typically, the *IoCompletion* routine must call **IoCompleteRequest** to fail the IRP when some limited number of retries have failed. + + - The *IoCompletion* routine must return STATUS\_MORE\_PROCESSING\_REQUIRED after it calls [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) and [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) with an IRP that is being reused or retried. + + Returning STATUS\_MORE\_PROCESSING\_REQUIRED from the *IoCompletion* routine forestalls the I/O manager's completion processing of a reused or retried IRP. + + - If the *IoCompletion* routine cannot complete the original IRP with STATUS\_SUCCESS, it must leave the I/O status block as returned by lower drivers for the reuse or retry operation that causes the *IoCompletion* routine to fail the IRP. + + - If the *IoCompletion* routine will complete the original request with STATUS\_PENDING, it must call **IoMarkIrpPending** with the original IRP before it calls **IoCompleteRequest**. + - If the *IoCompletion* routine must fail the original IRP with an error STATUS\_*XXX*, it can [log an error](logging-errors.md). However, it is the responsibility of the underlying device driver to log any device I/O errors that occur, so *IoCompletion* routines usually do not log errors. + +- Any driver that sets an *IoCompletion* routine in an IRP and then passes the IRP down to a lower driver should check the **IRP->PendingReturned** flag in the *IoCompletion* routine. If the flag is set, the *IoCompletion* routine must call **IoMarkIrpPending** with the IRP. Note, however, that a driver that passes down the IRP and then waits on an event should not mark the IRP pending. Instead, its *IoCompletion* routine should signal the event and return STATUS\_MORE\_PROCESSING\_REQUIRED. + +- The *IoCompletion* routine must release any resources the dispatch routine allocated for processing the original IRP, preferably before the *IoCompletion* routine calls **IoCompleteRequest** with the original IRP and definitely before the *IoCompletion* routine returns control from completing the original IRP. + +If any higher-level driver has set its *IoCompletion* routine in the original IRP, that driver's *IoCompletion* routine is not called until the *IoCompletion* routines of all lower-level drivers have been called. + +### Supplying a Priority Boost in Calls to IoCompleteRequest + +If a lowest-level device driver can complete an IRP in its dispatch routine, it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with a *PriorityBoost* of IO\_NO\_INCREMENT. No run-time priority increase is needed because the driver can assume that the original requester did not wait for its I/O operation to be completed. + +Otherwise, the lowest-level driver supplies a system-defined and device-type-specific value that boosts the requester's run-time priority to compensate for the time the requester waited on its device I/O request. See Wdm.h or Ntddk.h for the boost values. + +Higher-level drivers apply the same *PriorityBoost* as their respective underlying device drivers when they call **IoCompleteRequest**. + +### Effect of Calling IoCompleteRequest + +When a driver calls **IoCompleteRequest**, the I/O manager fills that driver's I/O stack location with zeros before calling the next higher-level driver, if any, that has set up an *IoCompletion* routine to be called for the IRP. + +A higher-level driver's *IoCompletion* routine can check only the IRP's I/O status block to determine how all lower drivers handled the request. + +The caller of **IoCompleteRequest** must not attempt to access the just-completed IRP. Such an attempt is a programming error that causes a system crash. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20an%20IoCompletion%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-custom-wmi-blocks.md b/windows-driver-docs-pr/kernel/implementing-custom-wmi-blocks.md new file mode 100644 index 0000000000..aedeca25ab --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-custom-wmi-blocks.md @@ -0,0 +1,66 @@ +--- +title: Implementing Custom WMI Blocks +author: windows-driver-content +description: Implementing Custom WMI Blocks +ms.assetid: c596924f-9f82-4ca7-b0f0-afc596d7bf99 +keywords: ["WMI WDK kernel , event blocks", "event blocks WDK WMI", "data blocks WDK WMI", "WMI WDK kernel , data blocks", "blocks WDK WMI", "custom blocks WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing Custom WMI Blocks + + +## + + +A driver can implement *custom blocks* that expose device-specific instrumentation. For example, a driver for a disk drive that can report temperature might implement a custom event block that notifies WMI clients when the drive's temperature increases beyond a safe threshold. + +To implement a custom block, a driver: + +- Defines a class in its MOF file, compiles the MOF file into a resource, and includes the resource in the driver, as described in [Publishing a WMI Schema](publishing-a-wmi-schema.md). + +- Registers the block with WMI along with the other standard and custom blocks supported by the driver, as described in [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +- Handles all WMI requests that specify the driver's device object pointer at **Parameters.WMI.ProviderId** and the GUID of the standard block at **Parameters.WMI.DataPath**, as described in [Handling WMI Requests](handling-wmi-requests.md). + +Drivers cannot control the order in which binary MOF files are loaded. The only guarantee is that wmicore.mof is loaded before any driver-specific MOF file. Therefore, custom WMI classes must only inherit from either classes in the same MOF file, or in wmicore.mof. + +To improve performance and ease of use of custom WMI data blocks, consider the following guidelines: + +- Put data items that are operationally grouped together in the same data block. + + For example, an i8042 port controller might maintain state information about both the keyboard and mouse ports. Rather than a single large data block containing all mouse and keyboard information, a driver might define one data block for the mouse port and another data block for the keyboard port. + +- Put frequently used data items in separate data blocks, particularly if they would otherwise be grouped with items that are infrequently used. + + For example, a driver might expose CPU utilization in a data block with a single item, so a WMI client could track CPU utilization without incurring the overhead of retrieving additional data items in the block. A WMI client cannot query for a single data item, so to obtain one item it must query for an entire instance of a data block. + +- Use event blocks to notify WMI clients of exceptional events, not as an alternative to error logging. + + Only a limited number of events can be queued at one time, and if the queue is full events will be lost. Also, the timing of delivery of events to WMI clients cannot be guaranteed. + +- Limit event blocks to a maximum size of 1K bytes. + + Event items should be defined as small data types, because there is a registry-defined size limit (initially, 1K) for the entire [**WNODE\_EVENT\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566373) structure that contains the generated event. For large notifications, a driver can send a [**WNODE\_EVENT\_REFERENCE**](https://msdn.microsoft.com/library/windows/hardware/ff566374) structure that specifies a single instance of a data block, which WMI then queries to obtain the actual event. However, this increases the time lag between the occurrence of the event and the notification. + +- Place fixed-size data items at the beginning of a data block, followed by any variable-size data items. + + For example, a data block that has three DWORD data items and one variable-length string should put the three DWORDs first, followed by the string. Placing fixed-size data items at the beginning of a block permits WMI clients to extract them more easily. + +- Consider which types of system users you'd like to access your driver's data blocks. The system provides a default security descriptor for all WMI class GUIDs. If necessary, you can provide alternate security descriptors within the device's INF file. For more information, see [Creating Secure Device Installations](https://msdn.microsoft.com/library/windows/hardware/ff540212). + +WMI does not support versioning, so a driver writer must define a new MOF class and generate a new GUID to revise an existing custom block. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20Custom%20WMI%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-dynamic-mof-data.md b/windows-driver-docs-pr/kernel/implementing-dynamic-mof-data.md new file mode 100644 index 0000000000..1b84b3ecc8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-dynamic-mof-data.md @@ -0,0 +1,42 @@ +--- +title: Implementing Dynamic MOF Data +author: windows-driver-content +description: Implementing Dynamic MOF Data +ms.assetid: 408c0f64-6257-4ece-bb4d-b1850f8ae3c6 +keywords: ["WMI WDK kernel , publishing schema", "publishing WMI schema WDK", "schema publishing WDK WMI", "MOF files WDK WMI", "dyanmic MOF data WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing Dynamic MOF Data + + +## + + +A driver's schema can be published dynamically by including binary MOF data in the driver's binary and returning selected schema information at runtime. To supply dynamic MOF data, a driver should follow these steps: + +1. Compile the MOF file as described in [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md). + +2. Use wmimofck.exe to create a .x file which will contain a hexadecimal dump of the .bmf file created by the MOF compiler. + +3. Use **\#include** to include the hex data created in step 2 with the driver's source. + +4. Register as supporting MSWmi\_MofData\_GUID, which is a GUID defined in wmidata.h. + +5. Return selected binary data to WMI in response to both the [**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) or [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) requests for MSWmi\_MofData\_GUID. + +For more information about the wmimofck utility see [Using wmimofck.exe](using-wmimofck-exe.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20Dynamic%20MOF%20Data%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-plug-and-play.md b/windows-driver-docs-pr/kernel/implementing-plug-and-play.md new file mode 100644 index 0000000000..970920fe9b --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-plug-and-play.md @@ -0,0 +1,46 @@ +--- +title: Implementing Plug and Play +author: windows-driver-content +description: Implementing Plug and Play +ms.assetid: ebd3aaa2-a701-41f3-88ff-2a6bdf7bd7cb +keywords: ["PnP WDK kernel", "Plug and Play WDK kernel", "kernel-mode drivers WDK , Plug and Play", "hardware configuration changes WDK PnP", "resource allocations WDK PnP", "hardware resource allocations WDK PnP", "automatic resource allocations WDK PnP", "dynamic resource allocations WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing Plug and Play + + +## + + +This section describes Plug and Play (PnP) concepts and operating system components, and explains how to support PnP capabilities of device hardware in kernel-mode drivers. The section contains the following topics: + +[Introduction to Plug and Play](introduction-to-plug-and-play.md) + +[Adding a PnP Device to a Running System](adding-a-pnp-device-to-a-running-system.md) + +[Passing PnP IRPs Down the Device Stack](passing-pnp-irps-down-the-device-stack.md) + +[Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md) + +[Starting a Device](starting-a-device.md) + +[Stopping a Device](stopping-a-device.md) + +[Removing a Device](removing-a-device.md) + +[Using PnP Notification](using-pnp-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20Plug%20and%20Play%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-power-management.md b/windows-driver-docs-pr/kernel/implementing-power-management.md new file mode 100644 index 0000000000..d877ac0d53 --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-power-management.md @@ -0,0 +1,47 @@ +--- +title: Power Management for Windows Drivers +author: windows-driver-content +description: Kernel-mode drivers should manage their hardware devices so that they are turned on and available for use when needed, but operate in a low-power mode and generate no unnecessary system activity when they are not being used. +ms.assetid: ed422428-8a87-4a2d-830d-e156ef949b13 +keywords: ["power management WDK kernel", "kernel-mode drivers WDK , power management", "energy WDK power management", "startup power management WDK kernel", "shutdown power management WDK kernel", "device power management WDK kernel", "restoring power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power Management for Windows Drivers + + +Kernel-mode drivers should manage their hardware devices so that they are turned on and available for use when needed, but operate in a low-power mode and generate no unnecessary system activity when they are not being used. The [*power manager*](power-manager.md) is the Windows kernel component that is responsible for coordinating the power states of the devices in the hardware platform. + +## + + +The power manager instructs drivers when to prepare their devices to enter a low-power mode, and drivers receive notification from the power manager when their devices are turned back on. Drivers are responsible for reporting their power capabilities to the power manager. Drivers have the option of detecting when their devices are idle (and can be switched to a low-power mode) or relying on the power manager for such detection. + +## In this section + + +- [Introduction to Power Management](introduction-to-power-management.md) +- [Kernel-Mode Power Management Components](kernel-mode-power-management-components.md) +- [Power Management Responsibilities for Drivers](power-management-responsibilities-for-drivers.md) +- [Rules for Handling Power IRPs](rules-for-handling-power-irps.md) +- [Managing Power for Individual Devices](managing-power-for-individual-devices.md) +- [Handling System Power State Requests](handling-system-power-state-requests.md) +- [Overview of the Power Management Framework](overview-of-the-power-management-framework.md) +- [Platform Extension Plug-ins (PEPs)](platform-extension-plug-ins--peps-.md) +- [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md) +- [Improving System Startup Performance](improving-system-startup-performance.md) +- [Device-Level Thermal Management](device-level-thermal-management.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20Management%20for%20Windows%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/implementing-wmi.md b/windows-driver-docs-pr/kernel/implementing-wmi.md new file mode 100644 index 0000000000..e51730ba87 --- /dev/null +++ b/windows-driver-docs-pr/kernel/implementing-wmi.md @@ -0,0 +1,62 @@ +--- +title: Implementing WMI +author: windows-driver-content +description: Implementing WMI +ms.assetid: 5c2ed322-0fc9-4004-9a5f-f4d3c6a59fe9 +keywords: ["WMI WDK kernel", "Windows Management Instrumentation WDK kernel", "extensions WDK WMI", "measurement data WDK WMI", "instrumentation data WDK WMI", "user-mode WMI WDK", "WMI WDK user-mode", "Windows Management Instrumentation WDK user-mode", "kernel-mode drivers WDK , WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Implementing WMI + + +## + + +This section describes kernel-mode Windows Management Instrumentation (WMI) extensions to WDM. When you add these extensions to your kernel-mode driver, your driver becomes a WMI provider. A WMI provider makes measurement and instrumentation data available to WMI consumers, such as user-mode applications. + +For more information about the user-mode WMI API, refer to [Windows Management Instrumentation](http://msdn.microsoft.com/library/aa394582(VS.85).aspx) in the Windows SDK. + +If you are implementing a KMDF-based driver, refer to [Supporting WMI in Framework-Based Drivers](https://msdn.microsoft.com/library/windows/hardware/ff544711). + +This section includes the following information about kernel-mode WMI: + +[Introduction to WMI](introduction-to-wmi.md) + +[WMI Architecture](wmi-architecture.md) + +[WMI Requirements for WDM Drivers](wmi-requirements-for-wdm-drivers.md) + +[MOF Syntax for WMI Data and Event Blocks](mof-syntax-for-wmi-data-and-event-blocks.md) + +[Designing WMI Data and Event Blocks](designing-wmi-data-and-event-blocks.md) + +[Publishing a WMI Schema](publishing-a-wmi-schema.md) + +[Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md) + +[Handling WMI Requests](handling-wmi-requests.md) + +[Sending WMI Events](sending-wmi-events.md) + +[WMI Property Sheets](wmi-property-sheets.md) + +[Using wmimofck.exe](using-wmimofck-exe.md) + +[WMI Event Tracing](wmi-event-tracing.md) + +[Testing and Troubleshooting WMI Driver Support](testing-and-troubleshooting-wmi-driver-support.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Implementing%20WMI%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/importing-kernel-mode-safe-string-functions.md b/windows-driver-docs-pr/kernel/importing-kernel-mode-safe-string-functions.md new file mode 100644 index 0000000000..d527be70b3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/importing-kernel-mode-safe-string-functions.md @@ -0,0 +1,79 @@ +--- +title: Importing Kernel-Mode Safe String Functions +author: windows-driver-content +description: Importing Kernel-Mode Safe String Functions +ms.assetid: f1cee7e0-151b-4e03-bf4d-400f328083fa +keywords: ["importing safe string functions", "inline safe string function versions WDK kernel", "library safe string function versions WDK kernel", "byte-counted functions WDK kernel", "character-counted functions WDK kernel", "safe string functions WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Importing Kernel-Mode Safe String Functions + + +## + + +Starting with Windows XP, the kernel-mode safe string library is available as a collection of inline functions that are defined in the Ntstrsafe.h header file. + +### To use the kernel-mode safe string functions + +Include the header file, as shown. + +``` +#include +``` + +You can make available only the byte-counted or only the character-counted safe string functions. + +### To allow only byte-counted functions + +Include the following line in your code before including the Ntstrsafe.h header file. + +``` +#define NTSTRSAFE_NO_CCH_FUNCTIONS +``` + +### To allow only character-counted functions + +Include the following line in your code before including the Ntstrsafe.h header file. + +``` +#define NTSTRSAFE_NO_CB_FUNCTIONS +``` + +You can define either NTSTRSAFE\_NO\_CB\_FUNCTIONS or NTSTRSAFE\_NO\_CCH\_FUNCTIONS, but not both. + +You can make the [**UNICODE\_STRING**](https://msdn.microsoft.com/library/windows/hardware/ff564879) structure functions unavailable. + +### To make UNICODE\_STRING structure functions unavailable + +Include the following line in your code before including the Ntstrsafe.h header file. + +``` +#define NTSTRSAFE_NO_UNICODE_STRING_FUNCTIONS +``` + +The maximum number of characters that any ANSI or Unicode string can contain is NTSTRSAFE\_MAX\_CCH. The maximum number of characters that a **UNICODE\_STRING** structure can contain is NTSTRSAFE\_UNICODE\_STRING\_MAX\_CCH. These constants are defined in Ntstrsafe.h. + +Your driver can assign smaller values to NTSTRSAFE\_MAX\_CCH and NTSTRSAFE\_UNICODE\_STRING\_MAX\_CCH by including the following lines in your code before including Ntstrsafe.h. + +``` +#define NTSTRSAFE_MAX_CCH +#define NTSTRSAFE_UNICODE_STRING_MAX_CCH +``` + +Directives in Ntstrsafe.h verify that your new values are not larger than the default values. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Importing%20Kernel-Mode%20Safe%20String%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/importing-safe-integer-functions.md b/windows-driver-docs-pr/kernel/importing-safe-integer-functions.md new file mode 100644 index 0000000000..c1f3832250 --- /dev/null +++ b/windows-driver-docs-pr/kernel/importing-safe-integer-functions.md @@ -0,0 +1,32 @@ +--- +title: Importing Kernel-Mode Safe Integer Functions +author: windows-driver-content +description: The kernel-mode safe integer functions are available as inline code that is contained in ntintsafe.h or in a library that you link your code to. +ms.assetid: C6696C4E-952A-4162-B2BE-F262496FFBD2 +--- + +# Importing Kernel-Mode Safe Integer Functions + + +The kernel-mode safe integer functions are available as inline code that is contained in ntintsafe.h or in a library that you link your code to. This header file is available in the Windows Driver Kit (WDK). + +It is important to note that you must use arithmetic operations on unsigned values. To use a signed value, you must use a conversion function to first convert the signed value to an unsigned value safely before using the arithmetic function. + +## To use the inline versions of the kernel-mode safe integer functions + + +Include the header file, as shown. + +```ManagedCPlusPlus +#include +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Importing%20Kernel-Mode%20Safe%20Integer%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/improving-system-startup-performance.md b/windows-driver-docs-pr/kernel/improving-system-startup-performance.md new file mode 100644 index 0000000000..b92da3fc02 --- /dev/null +++ b/windows-driver-docs-pr/kernel/improving-system-startup-performance.md @@ -0,0 +1,47 @@ +--- +title: Improving System Startup Performance +author: windows-driver-content +description: Improving System Startup Performance +ms.assetid: 9fce451c-73b3-4e3b-875d-319aaa8765ff +--- + +# Improving System Startup Performance + + +One of the features that computer users most frequently request is fast startup times from power-off, standby, and hibernation states. To reduce the startup time, Windows uses a number of techniques, which include the following: + +- Remove, from the list of startup operations, processes and services that can be deferred until after startup completes. + +- Prefetch memory pages according to the pattern of requests to load these pages in previous system startups. + +- Overlap device initialization with the disk I/O operations that are required to load the operating system. + +- Enable device initializations to be performed in parallel instead of sequentially. + +A kernel-mode driver should take the following steps to improve the performance of the startup process: + +- When a computer starts up from a power-off state (cold startup), the device driver should do only what is required to initialize the device and defer all other device operations until startup is complete. Limit your driver's initialization code to the operations that are required to make the device ready to use. + +- When a computer starts up from the standby or hibernation state (warm startup), a driver that must be initialized before startup completes should use high-priority worker threads and critical queue work items to offload any small tasks that it requires. Otherwise, the driver thread might be starved for processor time by unrelated threads, and startup will be delayed. + +- During a warm startup from standby or hibernation, a driver's DPC routine, or initialization code that runs at DISPATCH\_LEVEL, should avoid long execution times that block other drivers from running. For more information, see [Sharing Processor Resources During Startup from a Low-Power State](sharing-processor-resources-during-startup-from-a-low-power-state.md). + +- During a warm startup from standby or hibernation, a functional device driver should complete an S0 set-power IRP immediately, and then request a D0 set-power IRP. If your driver promptly completes the S0 set-power IRP, the operating system can finish startup while your driver reinitializes the device as a background task. For more information, see [Fast Startup from a Low-Power State](fast-startup-from-a-low-power-state.md). + +- A device driver should not hold a spin lock for more than a brief time, especially during a cold startup from a power-off state. Otherwise, other device initializations cannot occur in parallel. + +This section includes the following topics: + +[Sharing Processor Resources During Startup from a Low-Power State](sharing-processor-resources-during-startup-from-a-low-power-state.md) + +[Fast Startup from a Low-Power State](fast-startup-from-a-low-power-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Improving%20System%20Startup%20Performance%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/including-guids-in-driver-code.md b/windows-driver-docs-pr/kernel/including-guids-in-driver-code.md new file mode 100644 index 0000000000..4625011d61 --- /dev/null +++ b/windows-driver-docs-pr/kernel/including-guids-in-driver-code.md @@ -0,0 +1,55 @@ +--- +title: Including GUIDs in Driver Code +author: windows-driver-content +description: Including GUIDs in Driver Code +ms.assetid: 9235f9e6-9c40-4c4b-a98b-99e6b46a11ce +keywords: ["globally unique identifiers WDK kernel", "GUIDs WDK kernel", "identifiers WDK GUIDs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Including GUIDs in Driver Code + + +## + + +To use GUIDs in a kernel-mode driver, you must do two things: + +1. Include the Initguid.h header file that redefines the **DEFINE\_GUID** macro. + + The Initguid.h header file redefines the **DEFINE\_GUID** macro to instantiate GUIDs (versus just declaring an EXTERN reference). Include this header file in the driver source file where the GUIDs should be instantiated. (User-mode applications include Objbase.h before including header files containing GUID definitions.) + +2. Include the header file(s) that define the GUIDs. + + After the statement to include Initguid.h, you include the header files containing the GUID definitions. A driver might include more than one header file that contains GUID definitions, including system-supplied header files and third-party header files. + +The following code excerpt shows the sequence of statements for including GUIDs: + +``` +: +// include system headers here such as wdm.h + +#include + +// include system and driver-specific header files here that contain +// GUID definitions + +... + +``` + +Put the above statements in one module of the driver; typically the main module. When the above statements are present, the driver refers to a GUID using its symbolic name. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Including%20GUIDs%20in%20Driver%20Code%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/index.md b/windows-driver-docs-pr/kernel/index.md new file mode 100644 index 0000000000..b4e08956cf --- /dev/null +++ b/windows-driver-docs-pr/kernel/index.md @@ -0,0 +1,42 @@ +--- +title: Kernel-Mode Driver Architecture Design Guide +author: windows-driver-content +description: Kernel-Mode Driver Architecture Design Guide +ms.assetid: 21c199f3-abc3-4607-a674-eb84b6c3c25a +keywords: ["kernel-mode drivers WDK , architecture", "kernel-mode drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Driver Architecture Design Guide + + +## + + +This section includes general concepts to help you understand kernel-mode programming and describes specific techniques of kernel programming. This section is divided into four parts: + +- [Introduction to Windows Drivers](introduction-to-windows-drivers.md) provides a general overview of Windows components, lists the types of device drivers used in Windows, discusses the goals of Windows device drivers, and discusses generic sample device drivers included in the kit. + +- [Kernel-Mode Managers and Libraries](kernel-mode-managers-and-libraries.md) lists the primary kernel-mode components of the Windows operating system. + +- [Writing WDM Drivers](writing-wdm-drivers.md) provides information needed to write drivers using the Windows Driver Model (WDM). + +- [Driver Programming Techniques](driver-programming-techniques.md) describes techniques that you can use to program Windows kernel-mode device drivers. + + **Note**  For information about programming interfaces that your driver can implement or call, see [Kernel-Mode Driver Reference](https://msdn.microsoft.com/library/windows/hardware/ff553217). + +   + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel-Mode%20Driver%20Architecture%20Design%20Guide%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/industry-initiatives-for-power-management.md b/windows-driver-docs-pr/kernel/industry-initiatives-for-power-management.md new file mode 100644 index 0000000000..b3cf8169a7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/industry-initiatives-for-power-management.md @@ -0,0 +1,34 @@ +--- +title: Industry Initiatives for Power Management +author: windows-driver-content +description: Industry Initiatives for Power Management +ms.assetid: 81754a9b-67ec-47a6-bd18-5da10a1f18f5 +keywords: ["power management WDK kernel , industry initiatives", "Advanced Configuration and Power Interface Specification WDK", "Device Class Power Management Reference Specification WDK", "hardware WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Industry Initiatives for Power Management + + +## + + +The OnNow initiative defines hardware and software support required for power management. + +The *Advanced Configuration and Power Interface Specification*, part of the OnNow initiative, defines a hardware-level interface that enables operating systems to implement power management in a consistent, platform-independent way. + +A *Device Class Power Management Reference Specification* is available for each common device class, such as audio or communications devices. Each of these specifications defines power management requirements for a class of device. Driver writers should refer to these specifications, available through the [ACPI / Power Management](http://go.microsoft.com/fwlink/p/?linkid=57185) website, for device-specific details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Industry%20Initiatives%20for%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/initializing-a-device-object.md b/windows-driver-docs-pr/kernel/initializing-a-device-object.md new file mode 100644 index 0000000000..aa932aff18 --- /dev/null +++ b/windows-driver-docs-pr/kernel/initializing-a-device-object.md @@ -0,0 +1,54 @@ +--- +title: Initializing a Device Object +author: windows-driver-content +description: Initializing a Device Object +ms.assetid: 97820c62-aade-4ae7-92a6-7490d0ad5697 +keywords: ["device objects WDK kernel , initializing", "initializing device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Initializing a Device Object + + +## + + +After [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) returns, giving the caller a pointer to a *DeviceObject* that contains a pointer to the [*device extension*](device-extensions.md), drivers must set up certain fields in the device objects for their respective physical, logical, and/or virtual devices. + +**IoCreateDevice** sets the **StackSize** field of a newly created device object to one. A lowest-level driver can ignore this field. When a higher-level driver calls [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300) to attach itself to the next-lower driver, that routine automatically sets the **StackSize** field in the device object to that of the next-lower driver's device object plus one. For some device types, however, the higher-level driver might need to set the **StackSize** field to a greater value, as noted in the device-specific documentation. Setting the stack size ensures that IRPs sent to the higher-level driver will contain a driver-specific I/O stack location, plus the correct number of I/O stack locations for all lower-level drivers in the chain. + +**IoCreateDevice** sets the **AlignmentRequirement** field of a newly created device object to the processor's data cache line size minus one, to ensure that buffers used in direct I/O are aligned correctly. After **IoCreateDevice** returns, lowest-level physical device drivers must do the following: + +1. Subtract one from the alignment requirement of the device. + +2. Compare the result of step 1 with the current value of the device object's **AlignmentRequirement**. + +3. If the device's alignment requirement is greater, set **AlignmentRequirement** to the result of step 1. Otherwise, leave the **AlignmentRequirement** value as set by **IoCreateDevice**. + +After any higher-level driver chains itself over another driver by calling [**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198), the higher-level driver must set the **AlignmentRequirement** field of its newly created device object to that of the next-lower-level driver's device object. As a general rule, a higher-level driver should not change this value. If a higher-level driver calls [**IoAttachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548294) or [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300), those routines automatically set the **AlignmentRequirement** field in the device object to that of the lower-level driver's device object. + +[**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198) returns pointers both to the lower-level driver's device object and to the associated file object. Only an FSD (or, possibly, another highest-level driver) can use the returned file object pointer. An intermediate driver that calls **IoGetDeviceObjectPointer** should save this file object pointer so it can be dereferenced by calling [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) when the driver is unloaded. + +After an FSD mounts the volume containing the file object that represents a lower driver's device object, an intermediate driver cannot chain itself between the file system and the lower driver by calling **IoAttachDevice** or **IoAttachDeviceToDeviceStack**. Additionally, an FSD can set the **SectorSize** member of the device object based on the geometry of the underlying volume hardware when a mount occurs. For more information, see [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147). + +An intermediate or lowest-level driver also sets a bit in the device object's **Flags** by ORing it either with DO\_DIRECT\_IO or with DO\_BUFFERED\_IO in every device object it creates. Highest-level drivers of logical or virtual devices can avoid setting **Flags** for either buffered or direct I/O if the driver writer decides the additional work involved will pay off in better driver performance. An intermediate driver must set up the **Flags** field of its device object to match that of the next-lower driver's device object. + +Setting up a device object **Flags** field with DO\_DIRECT\_IO or DO\_BUFFERED\_IO determines how the I/O manager passes access to user buffers in all data transfer requests subsequently sent to the driver. + +The driver can then set any other device-dependent values in the device object. For example, non-WDM drivers for removable-media devices must OR the device object's **Flags** member with DO\_VERIFY\_VOLUME if they detect (or suspect) a change in media during I/O operations. (See [Supporting Removable Media](supporting-removable-media.md) for more information.) Drivers of devices that require inrush power must OR the **Flags** member with DO\_POWER\_INRUSH, and drivers of devices that are not on the system paging path must OR the **Flags** member with DO\_POWER\_PAGABLE. Function and filter drivers must clear the DO\_DEVICE\_INITIALIZING flag. + +After initializing the device object, a driver can also initialize any Kernel-defined objects and other system-defined data structures for which it has provided storage in the device extension. Precisely when a driver performs these tasks depends on its device, the type of the object, and/or the nature of the data. In general, any objects or data structures that can persist through PnP start and stop requests can be initialized in the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. Those that require resource information provided with a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, or that might require changes when the device is stopped and/or restarted, should be initialized when the driver handles the **IRP\_MN\_START\_DEVICE** request. For more information about *AddDevice* routines, see [Writing an AddDevice Routine](writing-an-adddevice-routine.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Initializing%20a%20Device%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/initializing-spin-locks.md b/windows-driver-docs-pr/kernel/initializing-spin-locks.md new file mode 100644 index 0000000000..abbb7282e6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/initializing-spin-locks.md @@ -0,0 +1,42 @@ +--- +title: Initializing Spin Locks +author: windows-driver-content +description: Initializing Spin Locks +ms.assetid: 7ed27e43-4406-4e64-b2c9-42b8a883efdb +keywords: ["initializing spin locks", "spin locks WDK kernel", "KeInitializeSpinLock", "executive spin locks WDK kernel", "interrupt spin locks WDK kernel", "queued spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Initializing Spin Locks + + +## + + +Before calling any support routine that requires access to a caller-supplied executive spin lock, a driver must call [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160) to initialize the corresponding executive spin lock. Support routines that require an initialized executive spin lock include the following: + +- [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) and, subsequently, [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145) + +- [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921) and, subsequently, [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150) + +- [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) and, subsequently, [**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) + +- [**KeAcquireInStackQueuedSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551908) and, subsequently, [**KeReleaseInStackQueuedSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553137) + +- An **ExInterlocked*Xxx*** routine + +Before calling [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371) and [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302), a lowest-level driver must call [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160) to initialize an interrupt spin lock for which it provides storage. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Initializing%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/interrupt-affinity-and-priority.md b/windows-driver-docs-pr/kernel/interrupt-affinity-and-priority.md new file mode 100644 index 0000000000..7c4248a944 --- /dev/null +++ b/windows-driver-docs-pr/kernel/interrupt-affinity-and-priority.md @@ -0,0 +1,117 @@ +--- +title: Interrupt Affinity +author: windows-driver-content +description: Interrupt Affinity +ms.assetid: e36a52d0-3a94-4017-b4a1-0b41f737523c +keywords: ["interrupt service routines WDK kernel , affinity", "ISRs WDK kernel , affinity", "affinity policy WDK interrupts", "IRQ_DEVICE_POLICY", "processor affinity WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interrupt Affinity + + +The *affinity* of an interrupt is the set of processors that can service the interrupt. Each device has an *affinity policy*. The operating system uses the affinity policy to compute the affinity for that device's interrupts. The affinity policy can be specified in the device's INF file or registry settings. + +Starting with Windows Vista, administrators can use the registry to set an affinity policy for an interrupt. + +Administrators can set the following entries under the **\\Interrupt Management\\Affinity Policy** registry key: + +- **DevicePolicy** is a REG\_DWORD value that specifies an affinity policy. Each possible setting corresponds to a [**IRQ\_DEVICE\_POLICY**](https://msdn.microsoft.com/library/windows/hardware/ff551783) value. + +- **AssignmentSetOverride** is a REG\_BINARY value that specifies a [**KAFFINITY**](https://msdn.microsoft.com/library/windows/hardware/ff551830) mask. If **DevicePolicy** is 0x04 (**IrqPolicySpecifiedProcessors**), then this mask specifies a set of processors to assign the device's interrupts to. + +The following table lists the [**IRQ\_DEVICE\_POLICY**](https://msdn.microsoft.com/library/windows/hardware/ff551783) values, and the corresponding registry setting for **DevicePolicy**. For more information about the meaning of each value, see [**IRQ\_DEVICE\_POLICY**](https://msdn.microsoft.com/library/windows/hardware/ff551783). + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IRQ_DEVICE_POLICY valueNumeric value in registry

IrqPolicyMachineDefault

0x00

IrqPolicyAllCloseProcessors

0x01

IrqPolicyOneCloseProcessor

0x02

IrqPolicyAllProcessorsInMachine

0x03

IrqPolicySpecifiedProcessors

0x04

IrqPolicySpreadMessagesAcrossAllProcessors

0x05

+ +  + +A driver's INF file can provide default settings for the registry values. Here is an example of how to set the **DevicePolicy** value to **IrqPolicyOneCloseProcessor** in the INF file. For more information, see [**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320). + +``` +[install-section-name.HW] +AddReg=add-registry-section + +[add-registry-section] +HKR, "Interrupt Management\Affinity Policy", DevicePolicy, 0x00010001, 2 +``` + +The system makes the registry settings available to the device's driver when it sends the [**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550874) IRP to the driver. The operating system provides an [**IO\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff550598) structure for each interrupt with the **Type** member set to **CmResourceTypeInterrupt**. For a message-signaled interrupt, the CM\_RESOURCE\_INTERRUPT\_MESSAGE bit of the **Flags** member is set; otherwise, it is clear. The **u.Interrupt** member describes the settings for the interrupt. + +The following table gives the correspondence between registry settings and members of **u.Interrupt**. + + ++++ + + + + + + + + + + + + + + + + +
Registry ValueMember of u.Interrupt

DevicePolicy

AffinityPolicy

AssignmentSetOverride

TargetedProcessors

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Interrupt%20Affinity%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/interrupt-service-routines.md b/windows-driver-docs-pr/kernel/interrupt-service-routines.md new file mode 100644 index 0000000000..25a0bbd96d --- /dev/null +++ b/windows-driver-docs-pr/kernel/interrupt-service-routines.md @@ -0,0 +1,43 @@ +--- +title: Interrupt Service Routines +author: windows-driver-content +description: Interrupt Service Routines +ms.assetid: d72a15be-772f-4cd4-a304-10981056d735 +keywords: ["interrupt service routines WDK kernel", "InterruptService", "ISRs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Interrupt Service Routines + + +This section contains the following sections: + +[Introduction to Interrupt Service Routines](introduction-to-interrupt-service-routines.md) + +[Using Message-Signaled Interrupts](using-message-signaled-interrupts.md) + +[Registering an ISR](registering-an-isr.md) + +[Removing an ISR](removing-an-isr.md) + +[Interrupt Affinity and Priority](interrupt-affinity-and-priority.md) + +[Providing ISR Context Information](providing-isr-context-information.md) + +[Writing an ISR](writing-an-isr.md) + +[Synchronizing Access to Device Data](synchronizing-access-to-device-data.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Interrupt%20Service%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-adapter-objects.md b/windows-driver-docs-pr/kernel/introduction-to-adapter-objects.md new file mode 100644 index 0000000000..b74ef70e84 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-adapter-objects.md @@ -0,0 +1,50 @@ +--- +title: Introduction to Adapter Objects +author: windows-driver-content +description: Introduction to Adapter Objects +ms.assetid: a1a0d516-dee0-484a-b971-c7a595fef155 +keywords: ["AdapterControl routines, about AdapterControl routines", "DMA transfers WDK kernel , adapter objects", "adapter objects WDK kernel , about adapter objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Adapter Objects + + +## + + +Any driver that uses direct I/O and DMA must create an adapter object. The adapter object represents either a DMA controller channel or port, or a bus-master device. + +Two kinds of lowest-level drivers must use adapter objects: + +- Drivers for devices that use the system DMA controller. Such devices are called *subordinate devices* and are said to "use system (or *subordinate*) DMA." + +- Drivers for devices that are bus-master adapters. Such devices arbitrate with the system for use of the I/O bus, and thus use bus-master DMA. + +Drivers provide storage, usually in a device extension, for a pointer to the adapter object. + +To carry out DMA transfers, drivers of devices that use either of these DMA methods usually have an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine and call system-supplied support routines that manipulate adapter objects. (Drivers that do not require *AdapterControl* routines include those that [use scatter/gather DMA](using-scatter-gather-dma.md) and those that [use common-buffer, bus-master DMA](using-common-buffer-bus-master-dma.md).) + +As part of device start-up operations, drivers that handle DMA operations call the I/O manager, which in turn calls the platform-specific HAL to create a set of adapter objects. On any Windows platform, the set of adapter objects usually includes an adapter object for: + +- Each system DMA controller channel or port to which a subordinate device is attached. + +- Each bus-master DMA device in the machine. + +(For SCSI devices capable of bus-master DMA, the SCSI port driver sets up adapter objects for HBA-specific SCSI miniport drivers. The miniport driver's [*HwScsiFindAdapter*](https://msdn.microsoft.com/library/windows/hardware/ff557300) routine supplies the port driver with adapter-specific data.) + +See [Using System DMA](using-system-dma.md) and [Using Bus-Master DMA](using-bus-master-dma.md) for more information about when and how drivers use adapter objects and *AdapterControl* routines. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Adapter%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-application-notification.md b/windows-driver-docs-pr/kernel/introduction-to-application-notification.md new file mode 100644 index 0000000000..aec858608e --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-application-notification.md @@ -0,0 +1,41 @@ +--- +title: Introduction to Application Notification +author: windows-driver-content +description: Introduction to Application Notification +ms.assetid: c115eb29-8bd2-40f7-b979-cff386bdc9aa +--- + +# Introduction to Application Notification + + +Starting with Windows Server 2008, processors and memory modules are considered Plug and Play (PnP) devices. Therefore, the operating system uses the PnP notification mechanism for application notification. The PnP notification mechanism sends WM\_DEVICECHANGE window messages to user-mode applications to notify the applications about changes to the hardware in the hardware partition. + +When a new processor or memory module is added to the hardware partition, the operating system sends this notification to user-mode applications after the operating system has started the new processor or memory device. In the case of a new processor, the operating system does not send this message to user-mode applications until after it has started scheduling threads on the new processor. + +**Note**   All PnP notifications are asynchronous. Therefore, these notifications might not be received by a user-mode application until sometime after the operating system has started the processor or memory module. + +  + +When a user-mode application receives this notification, it can adjust some or all of the following items accordingly: + +- Per processor memory allocations + +- The number of threads in the thread pools of the application + +- Memory buffer allocations + +- Load balancing algorithms + +A user-mode application can get the amount of physical memory that is in the hardware partition by calling the [GlobalMemoryStatusEx](http://go.microsoft.com/fwlink/p/?linkid=97891) function. For more information about the **GlobalMemoryStatusEx** function, see the Microsoft Windows SDK documentation. + +A user-mode application must register itself with the operating system to receive application notification. For more information, see [Registering for Application Notification](registering-for-application-notification.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Application%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-cancel-routines.md b/windows-driver-docs-pr/kernel/introduction-to-cancel-routines.md new file mode 100644 index 0000000000..554540cc14 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-cancel-routines.md @@ -0,0 +1,48 @@ +--- +title: Introduction to Cancel Routines +author: windows-driver-content +description: Introduction to Cancel Routines +ms.assetid: 99f7f045-2b2f-4fb3-ac1c-99ab76fa46ad +keywords: ["canceling IRPs, about canceling IRPs", "Cancel routines, about Cancel routines", "associated IRP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Cancel Routines + + +## + + +Any driver in which IRPs can be held in a pending state for an indefinite interval must have one or more [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routines. For example, a keyboard driver might wait indefinitely for a user to press a key. Conversely, if a driver will never queue more IRPs than it can complete in five minutes, it probably does not need a *Cancel* routine. + +Suppose a user-mode thread makes an I/O request, which is queued by a highest-level device driver's dispatch routine, and the requesting thread is terminated while the IRP is queued. IRPs queued on behalf of a terminated thread should be canceled. Consequently, the driver must set a driver-supplied *Cancel* routine in each IRP that it queues. + +A driver that creates associated IRPs must cancel them when the master IRP is canceled. Because associated IRPs are not associated with a requesting thread, the master IRP's *Cancel* routine is responsible for canceling any associated IRPs when the master IRP is canceled. + +The number of *Cancel* routines any driver has depends on the driver's design. In general, a driver should have a *Cancel* routine for each stage in its I/O processing at which an IRP might be held in a pending state for an indefinite interval. Such pending IRPs are said to be *held in a cancelable state*. + +Consider the following design guidelines: + +- The highest-level driver in a chain of layered drivers must have at least one *Cancel* routine if it queues IRPs or otherwise holds IRPs in a cancelable state. It can have more than one *Cancel* routine, if necessary. + +- Lower-level drivers in which IRPs can be held in a cancelable state for relatively long intervals also should have one or more *Cancel* routines. + +- If a driver manages its own internal queues of IRPs, it should have a separate *Cancel* routine for each of its queues. + +Some highest-level drivers for interactive devices, such as keyboard, mouse, sound, parallel class and serial drivers, must have *Cancel* routines. Some lower-level drivers, such as a parallel port driver that holds IRPs queued for some number of higher-level class drivers for relatively long intervals, also should have *Cancel* routines. + +Mass-storage device drivers, along with intermediate drivers layered over them, are unlikely to have *Cancel* routines. It is the responsibility of a file system driver to handle the cancellation of file I/O requests, while the IRPs input to lower-level mass-storage drivers are usually processed to completion too quickly to be cancelable. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Cancel%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-controller-objects.md b/windows-driver-docs-pr/kernel/introduction-to-controller-objects.md new file mode 100644 index 0000000000..d89305691f --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-controller-objects.md @@ -0,0 +1,64 @@ +--- +title: Introduction to Controller Objects +author: windows-driver-content +description: Introduction to Controller Objects +ms.assetid: a46732a7-1e60-41d5-96e9-d5284c000af1 +keywords: ["controller objects WDK kernel , about controller objects", "ControllerControl routines, about ControllerControl routines", "overlapped I/O WDK kernel", "I/O WDK kernel , overlaps"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Controller Objects + + +## + + +As its name suggests, a controller object usually represents a physical device controller with attached devices. A lowest-level non-WDM driver for a set of similar devices coordinated by a physical controller can create a controller object and use it to synchronize I/O operations between the attached devices. The driver implements a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine and calls the I/O manager's controller object support routines. + +**Note**   Use of controller objects is not supported in WDM drivers. + +  + +Generally, drivers use controller objects to synchronize operations to attached devices if the following criteria hold: + +- The controller does not carry out long operations without interrupting, so the driver does not need to create a device-dedicated thread or use system worker threads. + +- The devices connected to the controller are similar. That is, they are not devices with entirely different physical properties or operational functionality, such as the keyboard and mouse devices that can be connected to the keyboard and auxiliary device controller. + +- The driver is designed to be monolithic: single-layered in relation to the device controller and attached physical devices, rather than being designed as a port driver (for the controller) with one or more class drivers (for attached devices) layered over the port driver. + +Drivers of devices with I/O channels and a set of logical device objects also might use a controller object to synchronize their I/O operations between or among the channels of such a device. + +A controller object has no name and thus is not the target of I/O requests. It is simply a synchronization mechanism to serialize I/O from a set of device objects. Because a controller object has no name, it is invisible to user-mode protected subsystems, which cannot make device I/O requests without getting a handle for the file object that represents the target device object. A controller object is also invisible to higher-level drivers, which cannot attach their own device objects to a controller object. In other words, neither the I/O manager nor a higher-level driver can set up an IRP requesting I/O on a device represented by a controller object. I/O requests are always issued to device objects. Only the driver can use the controller object. + +### Synchronization and Overlapped I/O + +Monolithic drivers of physical devices with features like those of the "AT" disk controller are not required to use a controller object to synchronize their device I/O operations. For example, a driver writer could try something like the following synchronization technique instead of using a controller object: + +- Set up named device objects to represent the devices that are targets for I/O requests. + +- Maintain state information (perhaps a set of Device Busy flags in each device extension or in a single device extension) indicating which device object is the target of the current I/O operation. + +- Carry out I/O operations for the currently busy device object and requeue incoming IRPs for other device objects until the current IRP is completed. + +The preceding synchronization technique serializes IRP processing for all of the driver's target device objects. Note that it also forces the driver to complete the current IRP before its [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine can begin processing the next IRP, which unfortunately decreases driver performance. + +If certain device operations can be overlapped, using a controller object can increase a driver's I/O throughput, because this synchronization technique allows the driver to determine whether it can overlap operations just before it sets up the physical device. For example, a disk controller might allow the driver to overlap seeks on one disk with read/write operations on another disk. + +Moreover, using a controller object is a relatively easy way to synchronize I/O operations for more than one target device object through a single physical device, such as an "AT" disk controller. Using a controller object allows a monolithic driver to synchronize I/O operations across a set of named device objects without having to maintain state about every device and the device controller in one or more device extensions, and without having to requeue IRPs. + +However, some devices that are designed to overlap I/O operations, such as full-duplex serial controllers or bus-master adapters, generally have drivers that set up internal queues for IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Controller%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-device-objects.md b/windows-driver-docs-pr/kernel/introduction-to-device-objects.md new file mode 100644 index 0000000000..610439640f --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-device-objects.md @@ -0,0 +1,54 @@ +--- +title: Introduction to Device Objects +author: windows-driver-content +description: Introduction to Device Objects +ms.assetid: 310a2344-f3bc-4a7a-8e1e-63232ecd4cbe +keywords: ["device objects WDK kernel , about device objects", "multiple device objects WDK kernel", "device stacks WDK kernel , about device stacks", "device extensions WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Device Objects + + +## + + +The operating system represents devices by *device objects*. One or more device objects are associated with each device. Device objects serve as the target of all operations on the device. + +Kernel-mode drivers must create at least one device object for each device, with the following exceptions: + +- Minidrivers that have an associated class or port driver do not have to create their own device objects. The class or port driver creates the device objects, and dispatches operations to the minidriver. + +- Drivers that are part of device type-specific subsystems, such as NDIS miniport drivers, have their device objects created by the subsystem. + +See the documentation for your particular device type to determine if your driver creates its own device objects. + +Some device objects do not represent physical devices. A software-only driver, which handles I/O requests but does not pass those requests to hardware, still must create a device object to represent the target of its operations. + +For more information about how your driver can create device objects, see [Creating a Device Object](creating-a-device-object.md). + +Devices are usually represented by multiple device objects, one for each driver in the driver stack that handles I/O requests for the device. The device objects for a device are organized into a *device stack*. Whenever an operation is performed on a device, the system passes an [**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694) data structure to the driver for the top device object in the device stack. Each driver either handles the IRP or passes it to the driver that is associated with the next-lower device object in the device stack. For more information about device stacks, see [WDM Device Objects and Device Stacks](wdm-device-objects-and-device-stacks.md). For more information about IRPs, see [Handling IRPs](handling-irps.md). + +Device objects are represented by [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structures, which are managed by the object manager. The object manager provides the same capabilities for device objects that it does for other system objects. In particular, a device object can be named, and a named device object can have handles opened on it. For more information about named device objects, see [Named Device Objects](named-device-objects.md). + +The system provides dedicated storage for each device object, called the device extension, which the driver can use for device-specific storage. The device extension is created and freed by the system along with the device object. For more information, see [Device Extensions](device-extensions.md). + +The following figure illustrates the relationship between device objects and the I/O manager. + +![diagram illustrating a device object](images/3devobj.png) + +The figure shows the members of the **DEVICE\_OBJECT** structure that are of interest to a driver writer. For more information about these members, see [Creating a Device Object](creating-a-device-object.md), [Initializing a Device Object](initializing-a-device-object.md), and [Properties of Device Objects](properties-of-device-objects.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-dpc-objects.md b/windows-driver-docs-pr/kernel/introduction-to-dpc-objects.md new file mode 100644 index 0000000000..98b540e71d --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-dpc-objects.md @@ -0,0 +1,30 @@ +--- +title: Introduction to DPC Objects +author: windows-driver-content +description: Introduction to DPC Objects +ms.assetid: ae8758f5-0e23-4db2-9eac-aab31d98247b +--- + +# Introduction to DPC Objects + + +## + + +Because ISRs must execute as quickly as possible, drivers must usually postpone the completion of servicing an interrupt until after the ISR returns. Therefore, the system provides support for *deferred procedure calls* (DPCs), which can be queued from ISRs and which are executed at a later time and at a lower IRQL than the ISR. + +Each DPC is associated with a system-defined *DPC object*. The system supplies one DPC object for each device object. The system initializes this DPC object when a driver registers a DPC routine known as the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine. A driver can create additional DPC objects if more than one DPC is needed. These extra DPCs are known as [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routines. + +DPC object contents should not be directly referenced by drivers. The object's structure is not documented. Drivers do not have access to the system-supplied DPC object assigned to each device object. Drivers allocate storage for extra DPCs, but the contents of these DPC objects should only be referenced by system routines. + +DPC objects and DPCs can also be used with timers. For more information, see [Timer Objects and DPCs](timer-objects-and-dpcs.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20DPC%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-dpcs.md b/windows-driver-docs-pr/kernel/introduction-to-dpcs.md new file mode 100644 index 0000000000..7271498d9b --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-dpcs.md @@ -0,0 +1,42 @@ +--- +title: Introduction to DPCs +author: windows-driver-content +description: Introduction to DPCs +ms.assetid: 10e8d0e7-c04a-4dca-853c-74c911f59341 +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to DPCs + + +## + + +Any driver that has an ISR typically also has at least one [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine to complete processing of interrupt-driven I/O operations. A typical lowest-level driver's *DpcForIsr* or *CustomDpc* routine does the following: + +- Finishes handling an I/O operation that the ISR began processing. + +- Dequeues the next IRP so that the driver can begin processing it. + +- Completes the current IRP, if possible. + +Sometimes the current IRP cannot be completed because several data transfers are required, or a recoverable error was detected. In these cases, the *DpcForIsr* or *CustomDpc* routine typically reprograms the device for either another transfer or a retry of the last operation. + +A *DpcForIsr* or *CustomDpc* routine is called in an arbitrary DPC context at IRQL DISPATCH\_LEVEL. Running at DISPATCH\_LEVEL restricts the set of support routines a *DpcForIsr* or *CustomDpc* routine can call. See [Managing Hardware Priorities](managing-hardware-priorities.md) for more information. + +DPC objects and DPCs can also be used with timers. For more information, see [Timer Objects and DPCs](timer-objects-and-dpcs.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-driver-notification.md b/windows-driver-docs-pr/kernel/introduction-to-driver-notification.md new file mode 100644 index 0000000000..d71fd4e897 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-driver-notification.md @@ -0,0 +1,134 @@ +--- +title: Introduction to Driver Notification +author: windows-driver-content +description: Introduction to Driver Notification +ms.assetid: c0c09480-628a-4f12-b6a3-881cc3e12fd5 +keywords: ["driver notification WDK dynamic hardware partitioning , synchronous", "driver notification WDK dynamic hardware partitioning , asynchronous", "driver notification WDK dynamic hardware partitioning , memory notification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Driver Notification + + +Starting with Windows Server 2008, the operating system can notify a device driver when a processor or memory module is dynamically added to a hardware partition. There are several different notifications that occur at different stages of the process of a hot add operation. Each of these notifications uses a different notification method to notify the device driver about the event. You can use one or more of these notification methods to have the operating system notify your driver when a hot add operation occurs. Your driver can then respond as required for safe and optimal operation. + +The following table identifies the different notification methods and whether they apply to processors, memory, or both processors and memory. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Notification methodFor processorsFor memory

Synchronous driver notification

X

Asynchronous driver notification

X

X

Memory notification event

X

Resource rebalancing

X

+ +  + +``` + +``` + +### Synchronous Driver Notification + +With [Synchronous Driver Notification](synchronous-driver-notification.md), the operating system synchronously notifies device drivers that a new processor has been added to the hardware partition. This is the first notification that a device driver receives about a change to the number of processors. + +When a new processor is added to the hardware partition, the operating system sends this notification to device drivers after the operating system has started the new processor, but before the operating system begins scheduling threads on the processor. When a device driver receives this notification, it can allocate any per processor data structures and assign any other per processor resources to the new processor. This prepares the device driver to run its dispatch routines, interrupt service routines (ISRs), deferred procedure calls (DPCs), and any other driver threads on the new processor. + +A device driver must register itself with the operating system to receive synchronous driver notification. For more information, see [Registering for Synchronous Driver Notification](registering-for-synchronous-driver-notification.md). + +This notification method is only applicable to processors. There is no synchronous notification mechanism for memory. + +### Asynchronous Driver Notification + +With [Asynchronous Driver Notification](asynchronous-driver-notification.md), the operating system asynchronously notifies device drivers that a new processor or memory module has been added to the hardware partition. Starting with Windows Server 2008, processors and memory modules are considered Plug and Play (PnP) devices. Therefore, the operating system uses the PnP notification mechanism for asynchronous driver notification. + +When a new processor or memory module is added to the hardware partition, the operating system sends this notification to device drivers after the operating system has started the new processor or memory device. In the case of a new processor, the operating system does not send this notification to device drivers until after it has started scheduling threads on the new processor. + +**Note**   All PnP notifications are asynchronous. Therefore, these notifications might not be received by a device driver until sometime after the operating system has started the processor or memory module. + +  + +When a device driver receives this notification, it can adjust some or all of the following items accordingly: + +- Memory buffer and other resource allocations + +- Assignment of resources to specific processors + +- Scheduling of DPCs and other threads on specific processors + +- Load balancing algorithms + +**Important**   When you add a new processor to a hardware partition, the operating system does not send the PnP notification until after the new processor has been started and the operating system has begun scheduling threads on it. If a device driver must perform certain tasks before the operating system begins scheduling threads on the new processor, such as allocating a per processor data structure, you must use the synchronous notification method for the driver. + +  + +A device driver must register itself with the operating system to receive asynchronous driver notification. For more information, see [Registering for Asynchronous Driver Notification](registering-for-asynchronous-driver-notification.md). + +### Memory Notification Event + +With the memory notification event method, you can have your device driver schedule a thread that waits for the operating system to set the **\\KernelObjects\\HighMemoryCondition** event object. The operating system sets this event object when the amount of free physical memory exceeds a certain value. This event notifies any threads that are waiting on the event object that a significant amount of physical memory is currently available in the system. This event could be an indication that you dynamically added a new memory module to the system. When the operating system sets this event object, your device driver can respond to the event by allocating additional memory buffers. + +For more information about the **\\KernelObjects\\HighMemoryCondition** event object, see [Standard Event Objects](standard-event-objects.md). + +**Important**  If the operating system sets the **\\KernelObjects\\HighMemoryCondition** event object, the event only provides an indication that you might have dynamically added a new memory module to the hardware partition. There are other situations that can cause the operating system to set this event object. Therefore, starting with Windows Server 2008, we do not recommend that device drivers use this notification method. Instead, device drivers should use the asynchronous driver notification method. + +  + +This method is only applicable to memory. There is no corresponding notification mechanism for processors. + +### Resource Rebalance + +Starting with Windows Server 2008, when you add a new processor to a hardware partition, the operating system initiates a system-wide resource rebalance. Whether a device will participate in such a resource rebalance is determined by the setting of the [**DEVPKEY\_Device\_DHP\_Rebalance\_Policy**](https://msdn.microsoft.com/library/windows/hardware/ff542423) device property for the device. The default behavior for devices in the Network Adapter (Class = Net) [device setup class](https://msdn.microsoft.com/library/windows/hardware/ff541509) is that they will not participate in resource rebalancing when a new processor is dynamically added to the system. The default behavior for devices in all other device setup classes is that they will participate in resource rebalancing when a new processor is dynamically added to the system. + +If a device is a Plug and Play (PnP) device and it participates in such a resource rebalance, the operating system sends [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725), [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755), and [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) PnP IRPs to the driver for the device during the resource rebalancing operation. These PnP requests notify the driver that a hardware change has occurred in the hardware partition. A device driver should support resource rebalancing by correctly handling the **IRP\_MN\_QUERY\_STOP\_DEVICE** and **IRP\_MN\_STOP\_DEVICE** PnP requests. A device driver should never reject a **IRP\_MN\_QUERY\_STOP\_DEVICE** PnP request. + +These PnP requests enable a device driver to fully use the new set of active processors in the hardware partition after you add a new processor. Specifically, a device driver that supports resource rebalancing uses the PnP requests that it receives during the resource rebalance to disconnect its interrupt service routines (ISRs) and reconnect them with the updated processor affinity value. This enables the device driver to use all the currently active processors in the hardware partition, including any new processors, for handling interrupt requests. + +Device drivers should queue all I/O requests during resource rebalancing. + +For more information about resource rebalancing, see [Stopping a Device to Rebalance Resources](stopping-a-device-to-rebalance-resources.md). + +This method is only applicable to processors. The operating system does not initiate a system-wide resource rebalance when you add a new memory module to a hardware partition. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-driver-objects.md b/windows-driver-docs-pr/kernel/introduction-to-driver-objects.md new file mode 100644 index 0000000000..d84c88517a --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-driver-objects.md @@ -0,0 +1,45 @@ +--- +title: Introduction to Driver Objects +author: windows-driver-content +description: Introduction to Driver Objects +ms.assetid: 497ee2dc-671d-408e-b228-16dc24532375 +keywords: ["driver objects WDK kernel", "standard driver routines WDK kernel , driver objects", "driver routines WDK kernel , driver objects", "routines WDK kernel , driver objects", "objects WDK driver objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Driver Objects + + +## + + +The I/O manager creates a *driver object* for each driver that has been installed and loaded. Driver objects are defined using [**DRIVER\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff544174) structures. + +When the I/O manager calls a driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine, it supplies the address of the driver's driver object. The driver object contains storage for entry points to many of a driver's standard routines. The driver is responsible for filling in these entry points. + +## + + +The following figure illustrates a driver object, with the set of system-defined standard routines that lowest-level and higher-level drivers can or must have. + +Each standard routine with an asterisk beside its name receives an I/O request packet (IRP) as input. Each of these standard routines also receives a pointer to the target device object for the I/O request. + +![diagram illustrating a driver object](images/24drvobj.png) + +The I/O manager defines the driver object type and uses driver objects to register and track information about the loaded images of drivers. Note that the dispatch entry points (**DDDispatch***Xxx* through **DDDispatch***Yyy*) in the driver object correspond to the major function codes (**IRP\_MJ\_*XXX***) that are passed in the I/O stack locations of IRPs. + +The I/O manager routes each IRP first to a driver-supplied dispatch routine. A lowest-level driver's dispatch routine usually calls an I/O support routine ([**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370)) to queue (or pass on) each IRP that has valid arguments to the driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. The *StartIo* routine starts the requested I/O operation on a particular device. Higher-level drivers usually do not have *StartIo* routines, but they can. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Driver%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-dynamic-hardware-partitioning.md b/windows-driver-docs-pr/kernel/introduction-to-dynamic-hardware-partitioning.md new file mode 100644 index 0000000000..cd4671b8f6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-dynamic-hardware-partitioning.md @@ -0,0 +1,102 @@ +--- +title: Introduction to Dynamic Hardware Partitioning +author: windows-driver-content +description: Introduction to Dynamic Hardware Partitioning +ms.assetid: 0d909c64-17c4-4f0e-85b7-4e0a6a92eeee +keywords: ["dynamic hardware partitioning WDK , about dynamic hardware partitioning", "hardware partitioning WDK dynamic , about dynamic hardware partitioning", "partitions WDK dynamic hardware , about dynamic hardware partitioning", "hardware partitionable servers WDK", "partition units WDK dynamic hardware partitions", "statically partitionable servers WDK dynamic hardware partitioning", "dynamically partitionable servers WDK dynamic hardware partitioning", "hot add WDK dynamic hardware partitioning", "hot remove WDK dynamic hardware partitioning", "hot replace WDK dynamic hardware partitioning", "servers WDK dynamic hardware partitioning", "hardware partitions WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Dynamic Hardware Partitioning + + +A *hardware partitionable server* is a server that can be configured into one or more isolated *hardware partitions*. Each hardware partition runs an independent instance of the operating system. You can assign each of the server's hardware resources to each of the various hardware partitions in whatever configuration is appropriate for the server's application. The hardware resources that are assigned to a particular hardware partition are isolated from the other hardware partitions in the server. + +A hardware partition consists of one or more *partition units*. A partition unit is the smallest unit of hardware that you can assign to a hardware partition. A partition unit can be a processor, a memory module, or an I/O host bridge. Typically, processors and memory modules are plugged into sockets that can be powered on or off independently. + +A hardware partitionable server can be one of two types: *statically partitionable* or *dynamically partitionable*. On a statically partitionable server, you cannot change the configuration of partition units that are assigned to each hardware partition while the server is running. To change the configuration, you must shut down and restart the server computer. Microsoft Windows Server 2000 and later versions of the Windows Server operating system support statically partitionable servers. + +On a dynamically partitionable server, you can change the configuration of the partition units that are assigned to each hardware partition while the server is running. This is known as *dynamic hardware partitioning*. If the operating system that is running on a hardware partition supports dynamic hardware partitioning, you can add, replace, or remove partition units without restarting the operating system. Depending on the capabilities of the operating system, you can perform one or more of the following dynamic hardware partitioning operations: + +*Hot add* +Adding a partition unit to a running hardware partition. + +*Hot remove* +Removing a partition unit from a running hardware partition. + +*Hot replace* +Replacing a partition unit with an identical replacement partition unit that is already present in the server computer. A hot replace operation is a single operation that differs from a hot remove operation followed by a hot add operation. + +Windows Server 2003 with Service Pack 1 (SP1) supports hot add operations for memory modules on x86-based, x64-based, and Itanium-based servers. Windows Server 2003 SP1 does not support hot remove or hot replace operations. + +Starting with Windows Server 2008, the operating system supports hot add operations for processors, memory modules, and I/O host bridges, and hot replace operations for processors and memory modules on x64-based and Itanium-based server computers. The operating system also supports hot add operations for memory modules on x86-based server computers. The operating system does not support hot remove operations. + +The following table summarizes the dynamic hardware partitioning support that is included in each version of Windows Server. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Windows Server 2003 with SP1Windows Server 2008 and later versions of Windows Server on x86-based serversWindows Server 2008 and later versions of Windows Server on x64-based and Itanium-based servers

hot add

memory modules

memory modules

processors, +memory modules, +I/O host bridges

hot remove

hot replace

processors, +memory modules
+ +  + +We suggest that you consider the following guidelines when you develop your device drivers: + +- You should understand dynamic hardware partitioning because certain assumptions about the hardware configuration of a server computer are not valid on dynamically partitionable servers. Device drivers that are not designed to accommodate dynamic hardware partitioning could cause data corruption or cause the operating system to generate a bug check if they are run on a dynamically partitionable server. + +- You should consider the [critical issues](critical-issues-for-device-drivers.md) that are identified for dynamic hardware partitioning, even if you are not developing device drivers for server computers. + +- You should review and update all the device drivers that you are developing for servers that run Windows Server 2008 and later versions of Windows Server. Device drivers can register with the operating system to be notified of changes to the hardware configuration. When the device drivers are notified about a change to the hardware configuration, they can respond to the change as required for safe and optimal operation. This ensures that the drivers function correctly on dynamically partitionable servers. + +Drivers that you develop for Windows XP and later versions of Windows that correctly participate in [resource rebalancing](stopping-a-device-to-rebalance-resources.md) and do not make any assumptions about the number of processors, the processor affinity mask, or the amount of physical memory, will continue to operate correctly on a dynamically partitionable server. + +Most existing user-mode applications should continue to run on dynamically partitionable servers without any modification. However, if an application allocates threads for each processor or performs memory allocations that are based on how much physical memory is available, the application can register with the operating system to be notified of changes to the hardware configuration. When the application is notified about a change to the hardware configuration, it can adjust its resource allocation accordingly. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Dynamic%20Hardware%20Partitioning%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-eresource-routines.md b/windows-driver-docs-pr/kernel/introduction-to-eresource-routines.md new file mode 100644 index 0000000000..40733e49db --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-eresource-routines.md @@ -0,0 +1,64 @@ +--- +title: Introduction to ERESOURCE Routines +author: windows-driver-content +description: Introduction to ERESOURCE Routines +ms.assetid: 5c7759db-aeb5-47f3-8adc-ddedb74b5cb4 +keywords: ["ERESOURCE structures", "exclusive waiters WDK kernel", "shared waiters WDK kernel", "exclusive/shared synchronization WDK kernel", "synchronization WDK kernel , exclusive/shared", "waiters WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to ERESOURCE Routines + + +## + + +The system provides routines to acquire and release ERESOURCE structures, as well as to examine their current state. + +### Acquiring and Releasing an ERESOURCE Structure + +Drivers can use the ERESOURCE structures to implement *exclusive/shared synchronization*. Exclusive/shared synchronization works as follows: + +- Any number of threads can acquire an ERESOURCE as shared. + +- Only one thread can acquire an ERESOURCE exclusively. The ERESOURCE can only be acquired exclusively if no threads have already acquired it as shared. + +A thread that cannot currently acquire an ERESOURCE can optionally be put in a wait state until the ERESOURCE can be acquired. The system maintains two lists of threads that are waiting for an ERESOURCE: a list of *exclusive waiters* and a list of *shared waiters*. + +A typical use for exclusive/shared synchronization is to implement a read/write lock. A read/write lock allows several threads to perform a read operation, but only one thread can write at a time. This can be implemented directly in terms of acquiring an ERESOURCE. + +A driver allocates the storage for an ERESOURCE and initializes it with [**ExInitializeResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff545317). The system maintains a list of all ERESOURCE structures in use. When the driver no longer requires a particular ERESOURCE, it must call [**ExDeleteResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff544578) to delete it from the system's list. The driver can also reuse an ERESOURCE by calling [**ExReinitializeResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff545542). + +Drivers can perform the following basic operations on an ERESOURCE: + +- Acquire an ERESOURCE as shared with [**ExAcquireResourceSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544363). This routine acquires the resource only if the resource has not been acquired exclusively and there are no exclusive waiters. + +- Acquire an ERESOURCE exclusively with [**ExAcquireResourceExclusiveLite**](https://msdn.microsoft.com/library/windows/hardware/ff544351). This routine acquires the resource as long as it has not been acquired either exclusively or as shared. + +- Convert an exclusive acquisition to a shared acquisition with [**ExConvertExclusiveToSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544558). + +- Release an acquired resource with [**ExReleaseResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff545597). + +The *Wait* parameter of [**ExAcquireResourceSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544363) and [**ExAcquireResourceExclusiveLite**](https://msdn.microsoft.com/library/windows/hardware/ff544351) determines whether the current thread waits for the ERESOURCE to be acquired. If you specify a value of **FALSE** and the ERESOURCE cannot be acquired, then the routine returns **FALSE**. If you specify a value of **TRUE**, then the current thread is put on the appropriate wait list for the ERESOURCE. + +### Examining the State of an ERESOURCE Structure + +A driver can also determine the current state of an ERESOURCE, as follows: + +- Use [**ExIsResourceAcquiredLite**](https://msdn.microsoft.com/library/windows/hardware/ff545466) or [**ExIsResourceAcquiredSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff545477) to determine if the ERESOURCE has already been acquired as either shared or exclusive. Use [**ExIsResourceAcquiredExclusiveLite**](https://msdn.microsoft.com/library/windows/hardware/ff545458) to check whether the ERESOURCE has been specifically acquired exclusively. + +- Use [**ExGetSharedWaiterCount**](https://msdn.microsoft.com/library/windows/hardware/ff545290) to determine the number of shared waiters for the ERESOURCE, and use [**ExGetExclusiveWaiterCount**](https://msdn.microsoft.com/library/windows/hardware/ff544618) to determine the number of exclusive waiters for the ERESOURCE. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20ERESOURCE%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-i-o-control-codes.md b/windows-driver-docs-pr/kernel/introduction-to-i-o-control-codes.md new file mode 100644 index 0000000000..699e07e122 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-i-o-control-codes.md @@ -0,0 +1,40 @@ +--- +title: Introduction to I/O Control Codes +author: windows-driver-content +description: Introduction to I/O Control Codes +ms.assetid: 8b9e09ef-56f9-42b9-9b65-04bc380f3a1e +keywords: ["I/O control codes WDK kernel , about I/O control codes", "control codes WDK IOCTLs , about I/O control codes", "IOCTLs WDK kernel , about I/O control codes", "private IOCTLs WDK kernel", "public IOCTLs WDK kernel", "IOCTLs WDK user-mode", "user-mode components WDK IOCTLs", "I/O control codes WDK user-mode", "control codes WDK user-mode"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to I/O Control Codes + + +## + + +I/O control codes (IOCTLs) are used for communication between user-mode applications and drivers, or for communication internally among drivers in a stack. I/O control codes are sent using IRPs. + +User-mode applications send IOCTLs to drivers by calling [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216), which is described in Microsoft Windows SDK documentation. Calls to **DeviceIoControl** cause the I/O manager to create an [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) request and send it to the topmost driver. + +Additionally, upper-level drivers can send IOCTLs to lower-level drivers by creating and sending **IRP\_MJ\_DEVICE\_CONTROL** or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests. Drivers process these requests in [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) and [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routines. (User-mode applications cannot send **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests.) + +Some IOCTLs are "public" and some are "private". Public IOCTLs are typically system-defined and documented by Microsoft, in either the Windows Driver Kit (WDK) or the Windows SDK. They might be sent by means of a user-mode component's calls to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216), or they might be sent from one kernel-mode driver to another, using **IRP\_MJ\_DEVICE\_CONTROL** or **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests. Examples of public IOCTLs include [SCSI Port I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff565367) and [I8042prt Mouse Internal Device Control Requests](https://msdn.microsoft.com/library/windows/hardware/ff539982). + +Private IOCTLs, on the other hand, are meant to be used exclusively by a vendor's software components to communicate with each other. Private IOCTLs are typically defined in a vendor-supplied header file and are not publicly documented. Like public IOCTLs, they might be sent by means of a user-mode component's calls to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216), or they might be sent from one kernel-mode driver to another, using **IRP\_MJ\_DEVICE\_CONTROL** or **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests. + +There is no difference between the coding of public and private IOCTLs. There are, however, differences in the internal codes that can be used in vendor-defined IOCTLs, compared with those that are used for system-defined IOCTLs. If the available public IOCTLs do not fit your needs, you can define new private IOCTLs that your software components can use to communicate with one another. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20I/O%20Control%20Codes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-interrupt-service-routines.md b/windows-driver-docs-pr/kernel/introduction-to-interrupt-service-routines.md new file mode 100644 index 0000000000..123ea0c6e7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-interrupt-service-routines.md @@ -0,0 +1,37 @@ +--- +title: Introduction to Interrupt Service Routines +author: windows-driver-content +description: Introduction to Interrupt Service Routines +ms.assetid: e83eb873-7cdf-4faf-9a6e-cc5954ebf1d6 +keywords: ["interrupt service routines WDK kernel , about ISRs", "ISRs WDK kernel , about interrupt service routines", "InterruptService", "line-based interrupts WDK kernel", "interrupt lines WDK kernel", "message-signaled interrupts WDK kernel", "InterruptMessageService"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Interrupt Service Routines + + +A driver of a physical device that receives interrupts registers one or more interrupt service routines (ISR) to service the interrupts. The system calls the ISR each time it receives that interrupt. + +Devices for ports and buses prior to PCI 2.2 generate *line-based interrupts*. A device generates the interrupt by sending an electrical signal on a dedicated pin known as an *interrupt line*. Versions of Microsoft Windows prior to Windows Vista only support line-based interrupts. + +Beginning with PCI 2.2, PCI devices can generate *message-signaled interrupts*. A device generates a message-signaled interrupt by writing a data value to a particular address. Windows Vista and later operating systems support both line-based and message-signaled interrupts. + +The system supports two different types of ISRs: + +- The driver can register an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine to handle line-based or message-signaled interrupts. (This is the only type available prior to Windows Vista.) The system passes a driver-supplied context value. + +- The driver can register an [*InterruptMessageService*](https://msdn.microsoft.com/library/windows/hardware/ff547940) routine to handle message-signaled interrupts. The system passes both a driver-supplied context value and the message ID of the interrupt message. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Interrupt%20Service%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-kernel-dispatcher-objects.md b/windows-driver-docs-pr/kernel/introduction-to-kernel-dispatcher-objects.md new file mode 100644 index 0000000000..aebdd1f3f6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-kernel-dispatcher-objects.md @@ -0,0 +1,82 @@ +--- +title: Introduction to Kernel Dispatcher Objects +author: windows-driver-content +description: Introduction to Kernel Dispatcher Objects +ms.assetid: acf7b19a-55a3-4d9b-87ff-ca4df9ed3a45 +keywords: ["kernel dispatcher objects WDK , about kernel dispatcher objects", "dispatcher objects WDK kernel , about kernel dispatcher objects", "wait states WDK kernel", "Signaled state WDK kernel", "Not-Signaled state WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Kernel Dispatcher Objects + + +## + + +The kernel defines a set of object types called *kernel dispatcher objects*, or just *dispatcher objects*. Dispatcher objects include timer objects, event objects, semaphore objects, mutex objects, and thread objects. + +Drivers can use dispatcher objects as synchronization mechanisms within a nonarbitrary thread context while executing at IRQL PASSIVE\_LEVEL. + +### Dispatcher Object States + +Every kernel-defined dispatcher object type has a state that is either set to Signaled or set to Not-Signaled. + +A group of threads can synchronize their operations if one or more threads call [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350), [**KeWaitForMutexObject**](https://msdn.microsoft.com/library/windows/hardware/ff553344), or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324). These functions take dispatcher object pointers as input and wait until another routine or thread sets one or more dispatcher objects to the Signaled state. + +When a thread calls the **KeWaitForSingleObject** to wait for a dispatcher object (or **KeWaitForMutexObject** for a mutex), the thread is put into a *wait* state until the dispatcher object is set to the Signaled state. A thread can call **KeWaitForMultipleObjects** to wait either for any, or for all, of a set of dispatcher objects to be set to Signaled. + +Whenever a dispatcher object is set to the Signaled state, the kernel changes the state of any thread waiting for that object to *ready*. (Synchronization timers and synchronization events are exceptions to this rule; when a synchronization event or timer is signaled, only one waiting thread is set to the ready state. For more information, see [Timer Objects and DPCs](timer-objects-and-dpcs.md) and [Event Objects](event-objects.md).) A thread in the ready state will be scheduled to run according to its current run-time [thread priority](thread-priorities.md) and the current availability of processors for any thread with that priority. + +### When Can Drivers Wait for Dispatcher Objects? + +In general, drivers can wait for dispatcher objects to be set only if at least one of the following circumstances is true: + +- The driver is executing in a nonarbitrary thread context. + + That is, you can identify the thread that will enter a wait state. In practice, the only driver routines that execute in a nonarbitrary thread context are the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113), [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521), [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022), and [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routines of any driver, plus the dispatch routines of highest-level drivers. All these routines are called directly by the system. + +- The driver is performing a completely synchronous I/O request. + + That is, no driver queues any operations while handling the I/O request, and no driver returns until the driver below it has finished handling the request. + +Additionally, a driver cannot enter a wait state if it is executing at or above IRQL = DISPATCH\_LEVEL. + +Based on these limitations, you must use the following rules: + +- The **DriverEntry**, *AddDevice*, *Reinitialize*, and *Unload* routines of any driver can wait for dispatcher objects. + +- The dispatch routines of a highest-level driver can wait for dispatcher objects. + +- The dispatch routines of lower-level drivers can wait for dispatch objects, if the I/O operation is synchronous, such as create, flush, shutdown, and close operations, some device I/O control operations, and some PnP and power operations. + +- The dispatch routines of lower-level drivers cannot wait for a dispatcher object for the completion of asynchronous I/O operations. + +- A driver routine that is executing at or above IRQL DISPATCH\_LEVEL must not wait for a dispatcher object to be set to the Signaled state. + +- A driver must not attempt to wait for a dispatcher object to be set to the Signaled state for the completion of a transfer operation to or from a paging device. + +- Driver dispatch routines servicing read/write requests generally cannot wait for a dispatcher object to be set to the Signaled state. + +- A dispatch routine for a device I/O control request can wait for a dispatcher object to be set to the Signaled state only if the transfer type for the I/O control code is METHOD\_BUFFERED. + +- SCSI miniport drivers should not use kernel dispatcher objects. SCSI miniport drivers should call only [SCSI Port Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff565375). + +Every other standard driver routine executes in an arbitrary thread context: that of whatever thread happens to be current when the driver routine is called to process a queued operation or to handle a device interrupt. Moreover, most standard driver routines are run at a raised IRQL, either at DISPATCH\_LEVEL, or for device drivers, at DIRQL. + +If necessary, a driver can create a device-dedicated thread, which can wait for the driver's other routines (except an ISR or [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine) to set a dispatcher object to the Signaled state and reset to the Not-Signaled state. + +As a general guideline, if you expect that your new device driver will often need to stall for longer than 50 microseconds while it waits for device-state changes during I/O operations, consider implementing a driver with a device-dedicated thread. If the device driver is also a highest-level driver, consider using [system worker threads](system-worker-threads.md) and implementing one or more worker-thread callback routines. See [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932) and [Managing Interlocked Queues with a Driver-Created Thread](managing-interlocked-queues-with-a-driver-created-thread.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Kernel%20Dispatcher%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-ktm.md b/windows-driver-docs-pr/kernel/introduction-to-ktm.md new file mode 100644 index 0000000000..861d94d750 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-ktm.md @@ -0,0 +1,43 @@ +--- +title: Introduction to KTM +author: windows-driver-content +description: Introduction to KTM +ms.assetid: e34e19b7-58f9-474a-8819-b7099bfe4726 +keywords: ["Kernel Transaction Manager WDK , about Kernel Transaction Manager", "KTM WDK , about KTM", "transaction processing systems WDK KTM", "TPS WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to KTM + + +The Kernel transaction manager (KTM) is a transaction management service that enables you to create a transaction processing system (TPS) in user mode or kernel mode (or both). + +KTM is a kernel-mode service of the Microsoft Windows operating system. KTM is available on Windows Vista and later versions of Windows. + +KTM provides both user-mode and kernel-mode interfaces. This documentation describes the kernel-mode interfaces of KTM. For information about the Microsoft Win32 user-mode interfaces, see the Microsoft Windows SDK. + +For more information about transaction theory, see the book titled *Transaction Processing: Concepts and Techniques* by Jim Gray and Andreas Reuter. + +This section includes the following topics: + +[When to Use Kernel-Mode KTM](when-to-use-kernel-mode-ktm.md) + +[Transaction Processing Terms](transaction-processing-terms.md) + +[Understanding TPS Components](understanding-tps-components.md) + +[Additional Transactional Interfaces](additional-transactional-interfaces.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20KTM%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-message-signaled-interrupts.md b/windows-driver-docs-pr/kernel/introduction-to-message-signaled-interrupts.md new file mode 100644 index 0000000000..76d1d62ec2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-message-signaled-interrupts.md @@ -0,0 +1,51 @@ +--- +title: Introduction to Message-Signaled Interrupts +author: windows-driver-content +description: Introduction to Message-Signaled Interrupts +ms.assetid: 035207a1-762d-463e-822e-64ac4833afa4 +keywords: ["message-signaled interrupts WDK kernel", "MSIs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Message-Signaled Interrupts + + +Message-signaled interrupts (MSIs) were introduced in the PCI 2.2 specification as an alternative to line-based interrupts. Instead of using a dedicated pin to trigger interrupts, devices that use MSIs trigger an interrupt by writing a value to a particular memory address. PCI 3.0 defines an extended form of MSI, called *MSI-X*, that enables greater programmability. Windows Vista and later versions of Windows support MSI and MSI-X. A single device can support both MSI and MSI-X. For such a device, the operating system will automatically use MSI-X. + +An *interrupt message* is a particular value that a device writes to a particular address to trigger an interrupt. Unlike line-based interrupts, message-signaled interrupts have edge semantics. The device sends a message but does not receive any hardware acknowledgment that the interrupt was received. + +For PCI 2.2, a message consists of an address and a partially opaque 16-bit value. Each device is assigned a single address. To send multiple messages, the device can use the lower 4 bits of the message value to distinguish messages. Therefore, for PCI 2.2, devices can support up to 16 messages. + +For PCI 3.0, a message consists of an address and an opaque 32-bit value. Each different message has its own unique address. Unlike for PCI 2.2, the device does not modify the value. For PCI 3.0, a device can support up to 2,048 different messages. Devices that support PCI 3.0 MSI-X feature a dynamically programmable hardware table that contains entries for each of the interrupt sources in the device. Each entry in this table can be programmed with one of the messages that are allocated to a device, and can be independently masked. Drivers can change the programming of an interrupt message into a table entry and whether an entry has been masked. For more information, see [Dynamically Configuring MSI-X](dynamically-configuring-msi-x.md). + +Drivers can register a single [*InterruptMessageService*](https://msdn.microsoft.com/library/windows/hardware/ff547940) routine that handles all possible messages or individual [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routines for each message. + +Drivers can handle MSIs that a device sends as follows: + +1. During driver installation, enable MSIs in the registry. You can also use the registry to specify the number of messages to allocate for the device. For more information, see [Enabling Message-Signaled Interrupts in the Registry](enabling-message-signaled-interrupts-in-the-registry.md). + +2. Optionally, increase the number of interrupt messages and save some per-message settings by responding to an [**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550874) request. For more information, see [Using Interrupt Resource Descriptors](using-interrupt-resource-descriptors.md). + +3. In the driver's dispatch routine for [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749), call [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) to register an *InterruptService* or *InterruptMessageService* routine to service the device's interrupts. Use the CONNECT\_FULLY\_SPECIFIED version of **IoConnectInterruptEx** to register an *InterruptService* routine for a specific message or the CONNECT\_MESSAGE\_BASED version of **IoConnectInterruptEx** to register a single *InterruptMessageService* routine for all messages. For more information, see [Using the CONNECT\_MESSAGE\_BASED Version of IoConnectInterruptEx](using-the-connect-message-based-version-of-ioconnectinterruptex.md) and [Using the CONNECT\_FULLY\_SPECIFIED Version of IoConnectInterruptEx](using-the-connect-fully-specified-version-of-ioconnectinterruptex.md). + +4. After the driver no longer intends to service interrupts from the device, call [**IoDisconnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff549093) (after disabling the device's interrupts) to remove any registered interrupt service routines. + +Drivers that are designed to use multiple messages should check that the expected number of messages is allocated. If the Plug and Play (PnP) manager cannot allocate the requested number of messages, it instead allocates exactly one message to the device. Drivers can check the number of messages that are actually allocated in one of the following ways: + +- The PnP manager reports the number of allocated messages in its list of raw resource descriptors. For more information, see [Using Interrupt Resource Descriptors](using-interrupt-resource-descriptors.md). + +- When **IoConnectInterruptEx** returns, it sets *Parameters*->**MessageBased.ConnectContext.InterruptMessageTable->MessageCount** to the number of allocated messages. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Message-Signaled%20Interrupts%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-ms-dos-device-names.md b/windows-driver-docs-pr/kernel/introduction-to-ms-dos-device-names.md new file mode 100644 index 0000000000..3cb58d80c1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-ms-dos-device-names.md @@ -0,0 +1,69 @@ +--- +title: Introduction to MS-DOS Device Names +author: windows-driver-content +description: Introduction to MS-DOS Device Names +ms.assetid: 44b2f871-56e1-46d3-aab4-c38f498d089d +keywords: ["MS-DOS device names WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to MS-DOS Device Names + + +## + + +A named device object that is created by a non-WDM driver typically has an MS-DOS device name. An MS-DOS device name is a symbolic link in the object manager with a name of the form **\\DosDevices\\***DosDeviceName*. + +An example of a device with an MS-DOS device name is the serial port, COM1. It has the MS-DOS device name **\\DosDevices\\COM1**. Likewise, the C drive has the name **\\DosDevices\\C:**. + +WDM drivers do not usually supply MS-DOS device names for their devices. Instead, WDM drivers use the [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) routine to register a device interface. The device interface specifies devices by their capabilities, rather than by a particular naming convention. For more information, see [Device Interface Classes](https://msdn.microsoft.com/library/windows/hardware/ff541339). + +Drivers are required to supply an MS-DOS device name only if the device is required to have a specific well-known MS-DOS device name to work with user-mode programs. + +A driver supplies an MS-DOS device name for a device object by using the [**IoCreateSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549043) routine to create a symbolic link to the device. For example, the following code example creates a symbolic link from **\\DosDevices\\***DosDeviceName* to **\\Device\\***DeviceName*. + +``` +UNICODE_STRING DeviceName; +UNICODE_STRING DosDeviceName; +NTSTATUS status; + +RtlInitUnicodeString(&DeviceName, L"\\Device\\DeviceName"); +RtlInitUnicodeString(&DosDeviceName, L"\\DosDevices\\DosDeviceName"); +status = IoCreateSymbolicLink(&DosDeviceName, &DeviceName); +if (!NT_SUCCESS(status)) { + /* Symbolic link creation failed. Handle error appropriately. */ +} +``` + +Note that the system supports multiple versions of the **\\DosDevices** directory. Make sure that your driver creates its symbolic links in the version that you intend. For more information, see [Local and Global MS-DOS Device Names](local-and-global-ms-dos-device-names.md). + +To access the **DosDevices** namespace from user mode, specify **\\\\.\\** when you open a file name. You can open a corresponding device in user mode by calling **CreateFile()**. + +For example, the following code example opens the \\\\DosDevices\\\\*DosDeviceName* device in user mode. + +``` +file = CreateFileW(L"\\\\.\\DosDeviceName", + GENERIC READ | GENERIC WRITE, + 0, + NULL, + OPEN_EXISTING, + 0, + NULL); +``` + +A symbolic link can also be created from a user-mode application by using the user-mode **DefineDosDevice** routine. For more information, see the Microsoft Windows SDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20MS-DOS%20Device%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-mutex-objects.md b/windows-driver-docs-pr/kernel/introduction-to-mutex-objects.md new file mode 100644 index 0000000000..cb933a40a3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-mutex-objects.md @@ -0,0 +1,71 @@ +--- +title: Introduction to Mutex Objects +author: windows-driver-content +description: Introduction to Mutex Objects +ms.assetid: c35b4341-09dd-411d-b933-6c762fecd23c +keywords: ["kernel dispatcher objects WDK , mutex objects", "dispatcher objects WDK kernel , mutex objects", "mutex objects WDK kernel", "mutually exclusive access WDK kernel", "waiting on mutex objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Mutex Objects + + +As its name suggests, a mutex object is a synchronization mechanism designed to ensure mutually exclusive access to a single resource that is shared among a set of kernel-mode threads. Only highest-level drivers, such as file system drivers (FSDs) that use executive worker threads, are likely to use a mutex object. + +Possibly, a highest-level driver with driver-created threads or worker-thread callback routines might use a mutex object. However, any driver with pageable threads or worker-thread callback routines must manage the acquisitions of, waits on, and releases of its mutex objects very carefully. + +Mutex objects have built-in features that provide system (kernel-mode only) threads mutually exclusive, deadlock-free access to shared resources in SMP machines. The kernel assigns ownership of a mutex to a single thread at a time. + +Acquiring ownership of a mutex prevents the delivery of normal kernel-mode asynchronous procedure calls (APCs). The thread will not be preempted by an APC unless the kernel issues an APC\_LEVEL software interrupt to run a special kernel APC, such as the I/O manager's IRP completion routine that returns results to the original requester of an I/O operation + +A thread can acquire ownership of a mutex object that it already owns (recursive ownership), but a recursively acquired mutex object is not set to the Signaled state until the thread releases its ownership completely. Such a thread must explicitly release the mutex as many times as it acquired ownership before another thread can acquire the mutex. + +The kernel never permits a thread that owns a mutex to cause a transition to user mode without first releasing the mutex and setting it to the Signaled state. If any FSD-created or driver-created thread that owns a mutex attempts to return control to the I/O manager before releasing ownership of the mutex, the kernel brings down the system. + +Any driver that uses a mutex object must call [**KeInitializeMutex**](https://msdn.microsoft.com/library/windows/hardware/ff552147) once before it waits on or releases its mutex object. The following figure illustrates how two system threads might use a mutex object. + +![diagram illustrating waiting for a mutex object](images/3mutxobj.png) + +As the previous figure shows, a driver that uses a mutex object must provide the storage for the mutex object, which must be resident. The driver can use the [device extension](device-extensions.md) of a driver-created device object, the controller extension if it uses a [controller object](using-controller-objects.md), or nonpaged pool that is allocated by the driver. + +When a driver calls **KeInitializeMutex** (typically from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine), it must pass a pointer to the driver's storage for the mutex object, which the kernel initializes to the Signaled state. + +After such a highest-level driver has initialized, it can manage mutually exclusive access to a shared resource as shown in the previous figure. For example, a driver's dispatch routines for inherently synchronous operations and threads might use a mutex to protect a driver-created queue for IRPs. + +Because **KeInitializeMutex**always sets the initial state of a mutex object to Signaled (as the previous figure shows): + +1. A dispatch routine's initial call to [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with the *Mutex* pointer puts the current thread immediately into the ready state, gives the thread ownership of the mutex, and resets the mutex state to Not-Signaled. As soon as the dispatch routine resumes running, it can safely insert an IRP into the mutex-protected queue. + +2. When a second thread (another dispatch routine, driver-supplied worker-thread callback routine, or driver-created thread) calls **KeWaitForSingleObject** with the *Mutex* pointer, the second thread is put into the wait state. + +3. When the dispatch routine finishes queuing the IRP as described in step 1, it calls [**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) with the *Mutex* pointer and a Boolean *Wait* value, which indicates whether it intends to call **KeWaitForSingleObject** (or [**KeWaitForMutexObject**](https://msdn.microsoft.com/library/windows/hardware/ff553344)) with the *Mutex* as soon as **KeReleaseMutex** returns control. + +4. Assuming the dispatch routine released its ownership of the mutex in step 3 (*Wait* set to **FALSE**), the mutex is set to the Signaled state by **KeReleaseMutex**. The mutex currently has no owner, so the kernel determines whether another thread is waiting for that mutex. If so, the kernel makes the second thread (see step 2) the mutex owner, possibly boosts the thread's priority to the lowest real-time priority value, and changes its state to ready. + +5. The kernel dispatches the second thread for execution as soon as a processor is available: that is, when no other thread with a higher priority is currently in the ready state and there are no kernel-mode routines to be run at a higher IRQL. The second thread (a dispatch routine queuing an IRP or the driver's worker-thread callback routine or driver-created thread dequeuing an IRP) can now safely access the mutex-protected queue of IRPs until it calls **KeReleaseMutex**. + +If a thread acquires ownership of a mutex object recursively, that thread must explicitly call **KeReleaseMutex** as many times as it waited on the mutex in order to set the mutex object to the Signaled state. For example, if a thread calls **KeWaitForSingleObject** and then **KeWaitForMutexObject** with the same *Mutex* pointer, it must call **KeReleaseMutex** twice when it acquires the mutex in order to set that mutex object to the Signaled state. + +Calling **KeReleaseMutex** with the *Wait* parameter set to **TRUE** indicates the caller's intention to immediately call a **KeWait*Xxx*** support routine on return from **KeReleaseMutex**. + +**Consider the following guidelines for setting the Wait parameter to KeReleaseMutex:** + +A pageable thread or pageable driver routine that runs at IRQL PASSIVE\_LEVEL should never call **KeReleaseMutex** with the *Wait* parameter set to **TRUE**. Such a call causes a fatal page fault if the caller happens to be paged out between the calls to **KeReleaseMutex** and **KeWait*Xxx*Object**(s). + +Any standard driver routine that runs at an IRQL greater than PASSIVE\_LEVEL cannot wait for a nonzero interval on any dispatcher objects without bringing down the system. However, such a routine can call **KeReleaseMutex** if it owns the mutex while running at an IRQL less than or equal to DISPATCH\_LEVEL. + +For a summary of the IRQLs at which standard driver routines run, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Mutex%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-plug-and-play.md b/windows-driver-docs-pr/kernel/introduction-to-plug-and-play.md new file mode 100644 index 0000000000..38c2acd777 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-plug-and-play.md @@ -0,0 +1,72 @@ +--- +title: Introduction to Plug and Play +author: windows-driver-content +description: Introduction to Plug and Play +ms.assetid: 2ad9663b-ea47-4f7a-a382-53de3719214b +keywords: ["PnP WDK kernel , about Plug and Play", "Plug and Play WDK kernel , about Plug and Play"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Plug and Play + + +## + + +Plug and Play (PnP) is a combination of hardware and software support that enables a computer system to recognize and adapt to hardware configuration changes with little or no intervention by a user. A user can add devices to, and remove devices from, a computer system without having to do awkward and confusing manual configuration, and without having knowledge of intricate computer hardware. For example, a user can dock a portable computer and use the docking station keyboard, mouse, and monitor without making manual configuration changes. + +PnP requires support from device hardware, system software, and drivers. Initiatives in the hardware industry define standards (such as the PnP ISA definition and the PC Card standard) for easy identification of add-in boards and basic system components. This Windows Driver Kit (WDK) documentation focuses on the system software support for PnP and how drivers use that support to implement PnP. + +The system software support for PnP, together with PnP drivers provides the following: + +- Automatic and dynamic recognition of installed hardware + + The system software recognizes hardware during initial system installation, recognizes PnP hardware changes that occur between system boots, and responds to run-time hardware events such as docking or undocking and device insertion or removal. + +- Hardware resource allocation (and reallocation) + + The PnP manager determines the hardware resources requested by each device (for example, input/output ports \[I/O\], interrupt requests \[IRQs\], direct memory access \[DMA\] channels, and memory locations) and assigns hardware resources appropriately. The PnP manager reconfigures resource assignments when necessary, such as when a new device is added to the system that requires resources already in use. + + Drivers for PnP devices do not assign resources; instead, the requested resources for a device are identified when the device is enumerated. The PnP manager retrieves the requirements for each device during resource allocation. Resources are not dynamically configurable for legacy devices, so the PnP manager assigns resources to legacy devices first. + +- Loading of appropriate drivers + + The PnP manager determines which drivers are required to support each device and loads those drivers. + +- A programming interface for drivers to interact with the PnP system + + The interface includes [I/O manager routines](https://msdn.microsoft.com/library/windows/hardware/ff551797), [Plug and Play minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807), required [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842), and information in the registry. + +- Mechanisms for drivers and applications to learn of changes in the hardware environment and take appropriate actions + + PnP enables drivers and user-mode code to register for, and be notified of, certain hardware events. + +PnP drivers are an important part of PnP support. For a driver to qualify as PnP it must provide the required PnP entry points, handle the required PnP IRPs, and follow PnP guidelines. + +This section contains the following additional topics: + +[PnP Components](pnp-components.md) + +[Levels of Support for PnP](levels-of-support-for-pnp.md) + +[PnP Driver Design Guidelines](pnp-driver-design-guidelines.md) + +[Device Tree](device-tree.md) + +[Hardware Resources](hardware-resources.md) + +[State Transitions for PnP Devices](state-transitions-for-pnp-devices.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Plug%20and%20Play%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-power-management.md b/windows-driver-docs-pr/kernel/introduction-to-power-management.md new file mode 100644 index 0000000000..92e46b3740 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-power-management.md @@ -0,0 +1,66 @@ +--- +title: Introduction to Power Management +author: windows-driver-content +description: Introduction to Power Management +ms.assetid: d0cac254-d723-45f3-bef6-eb1d64b5d656 +keywords: ["power management WDK kernel , about power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Power Management + + +## + + +Microsoft Windows supports a power management architecture that provides a comprehensive approach to system and device power management. This power management architecture is designed to meet ever-increasing user requirements, which include: + +- Customers are demanding that their computers be automatically available at all times, even when turned off. For example, network administrators want to manage computers late at night, and home users want to use their computer to receive faxes. Users with computers hidden away under desks want to be able to turn them by pressing a button on the keyboard or monitor. + +- Customers want to decrease the amount of power and total energy that a PC uses, whether the power comes from an electrical wall outlet or a battery. + +To meet these ever-increasing user requirements, Windows must be able to manage the power that is used by any device in the system, including add-in boards such as graphics cards, network adapters, modems, and sound cards. To effectively manage power, the PC software, hardware, and Windows must work together in a framework that enables every device to be power managed in a consistent manner. + +A PC configuration that takes full advantage of the Windows power management architecture, provides the following advantages to users: + +- Energy savings and extended battery life. + + Reducing system power consumption results in lower energy costs and longer battery life. + +- Minimal startup and shutdown delays. + + If a working state is not required, the system power state can be changed from the working state to a sleep state and, subsequently, quickly changed back to a working state as required. This allows the system to be responsive to the user, yet energy can be conserved during the time period that a working state is not required. + +- Quiet operation. + + In many cases the full capabilities of a system might not be required. Powering down devices that are not being used can reduce noise. This capability is important in situations where near-silent operation is highly desirable, such as in Media Center PCs. + +In systems that support power management, the computer and its peripheral devices are maintained at the lowest feasible power level to accomplish the tasks at hand. Drivers cooperate with the operating system to manage power for their devices. If all drivers support power management, the operating system can manage power consumption on a system-wide basis, thus conserving power, shutting down and resuming quickly, and waking up when required. + +This integrated approach to power management—involving the operating system, system hardware, device drivers, and device hardware—results in the following: + +- More intelligent power management decisions. At each level, the best-informed component directs power usage. + +- Greater reliability. Better power management decisions reduce the chance of ill-timed shutdowns and loss of data. + +- Platform independence. The operating system manages power in a controlled, uniform way across different hardware platforms, allowing maximum conservation of power on various devices. + +- Better device integration. Device drivers that conform to industry-wide specifications ensure maximum conservation regardless of the hardware platform. + +Combined, these advantages result in greater power conservation and more efficient usage than has previously been possible. + +The industry-wide OnNow initiative defines the hardware and software requirements for power management. For more information, see [Industry Initiatives for Power Management](industry-initiatives-for-power-management.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-spin-locks.md b/windows-driver-docs-pr/kernel/introduction-to-spin-locks.md new file mode 100644 index 0000000000..3bb7db1482 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-spin-locks.md @@ -0,0 +1,60 @@ +--- +title: Introduction to Spin Locks +author: windows-driver-content +description: Introduction to Spin Locks +ms.assetid: a37c0db4-ff9c-4958-a9f4-62b671458d03 +keywords: ["KSPIN_LOCK", "executive spin locks WDK kernel", "interrupt spin locks WDK kernel", "queued spin locks WDK kernel", "spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Spin Locks + + +## + + +Spin locks are kernel-defined, kernel-mode-only synchronization mechanisms, exported as an opaque type: KSPIN\_LOCK. A spin lock can be used to protect shared data or resources from simultaneous access by routines that can execute concurrently and at IRQL >= DISPATCH\_LEVEL in SMP machines. + +Many components use spin locks, including drivers. Any kind of driver might use one or more *executive spin locks*. For example, most file systems use an interlocked work queue in the file system driver's (FSD's) device extension to store IRPs that are processed both by the file system's worker-thread callback routines and by the FSD. An interlocked work queue is protected by an executive spin lock, which resolves contention among the FSD trying to insert IRPs into the queue and any threads simultaneously trying to remove IRPs. As another example, the system floppy controller driver uses two executive spin locks. One executive spin lock protects an interlocked work queue shared with this driver's device-dedicated thread; the other protects a timer object shared by three driver routines. + +Drivers for Microsoft Windows XP and later versions of Windows can use [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) and [**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) to acquire and release the spin lock as a *queued spin lock*. Queued spin locks provide better performance than ordinary spin locks for high contention locks on multiprocessor machines. For more information, see [Queued Spin Locks](queued-spin-locks.md). Drivers for Windows 2000 can use [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) and [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145) to acquire and release a spin lock as an ordinary spin lock. + +To synchronize access to simple data structures, drivers can use any of the **ExInterlocked*Xxx*** routines to ensure atomic access to the data structure. Drivers that use these routines do not need to acquire or release the spin lock explicitly. + +Every driver that has an ISR uses an *interrupt spin lock* to protect any data or hardware shared between its ISR and its [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines that are usually called from its [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routines. An interrupt spin lock is associated with the set of interrupt objects created when the driver calls [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371), as described in Registering an ISR. + +**Follow these guidelines for using spin locks in drivers:** + +- Provide the storage for any data or resource protected by a spin lock and for the corresponding spin lock in resident system-space memory (nonpaged pool, as shown in the [Virtual Memory Spaces and Physical Memory](overview-of-windows-memory-space.md) figure). A driver must provide the storage for any executive spin locks it uses. However, a device driver need not provide the storage for an interrupt spin lock unless it has a multivector ISR or has more than one ISR, as described in Registering an ISR. + +- Call [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160) to initialize each spin lock for which the driver provides storage before using it to synchronize access to the shared data or resource it protects. + +- Call every support routine that uses a spin lock at an appropriate IRQL, generally at <= DISPATCH\_LEVEL for executive spin locks or at <= DIRQL for an interrupt spin lock associated with the driver's interrupt objects. + +- Implement routines to execute as quickly as possible while they hold a spin lock. No routine should hold a spin lock for longer than 25 microseconds. + +- Never implement routines that do any of the following while holding a spin lock: + + - Cause hardware exceptions or raise software exceptions. + + - Attempt to access pageable memory. + + - Make a recursive call that would cause a deadlock or could cause a spin lock to be held for longer than 25 microseconds. + + - Attempt to acquire another spin lock if doing so might cause a deadlock. + + - Call an external routine that violates any of the preceding rules. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-standard-driver-routines.md b/windows-driver-docs-pr/kernel/introduction-to-standard-driver-routines.md new file mode 100644 index 0000000000..57651acf8c --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-standard-driver-routines.md @@ -0,0 +1,145 @@ +--- +title: Introduction to Standard Driver Routines +author: windows-driver-content +description: Introduction to Standard Driver Routines +ms.assetid: 91aaca02-a571-4058-b5af-98277fcbcf9d +keywords: ["standard driver routines WDK kernel , about standard driver routines", "driver routines WDK kernel , about standard driver routines", "routines WDK kernel , about standard driver routines", "IRPs WDK kernel , standard driver routines", "required standard routines WDK kernel", "optional standard routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Standard Driver Routines + + +## + + +Each kernel-mode driver is constructed around a set of system-defined, [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842). Kernel-mode drivers process *I/O request packets* (IRPs) within these standard routines by calling system-supplied driver support routines. + +All drivers, regardless of their level in a chain of attached drivers, must have a basic set of standard routines in order to process IRPs. Whether a driver must implement additional standard routines depends on whether the driver controls a physical device or is layered over a physical device driver, as well as on the nature of the underlying physical device. Lowest-level drivers that control physical devices have more required routines than higher-level drivers, which typically pass IRPs to a lower driver for processing. + +Standard driver routines can be divided into two groups: those that each kernel-mode driver must have, and those that are optional, depending on the driver type and location in the [*device stack*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-stack). + +This section describes required standard routines. Other sections describe the optional routines. + +Following are two tables. The first table lists required standard routines. The second lists most of the optional routines. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Required standard driver routinesPurposeWhere described

DriverEntry

Initializes the driver and its driver object.

[Writing a DriverEntry Routine](writing-a-driverentry-routine.md)

AddDevice

Initializes devices and creates device objects.

[Writing an AddDevice Routine](writing-an-adddevice-routine.md)

Dispatch Routines

Receive and process IRPs.

[Writing Dispatch Routines](writing-dispatch-routines.md)

Unload

Release system resources acquired by the driver.

[Writing an Unload Routine](writing-an-unload-routine.md)

+ +  + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Optional standard driver routinesPurposeWhere described

Reinitialize

Completes driver initialization if DriverEntry cannot.

[Writing a Reinitialize Routine](writing-a-reinitialize-routine.md)

StartIo

Starts an I/O operation on a physical device.

[Writing a StartIo Routine](writing-a-startio-routine.md)

Interrupt Service Routine

Saves the state of a device when it interrupts.

[Writing an ISR](writing-an-isr.md)

Deferred Procedure Calls

Completes the processing of a device interrupt after an ISR saves the device state.

[DPC Objects and DPCs](dpc-objects-and-dpcs.md)

SynchCritSection

Synchronizes access to driver data.

[Using Critical Sections](using-critical-sections.md)

AdapterControl

Initiates DMA operations.

[Adapter Objects and DMA](adapter-objects-and-dma.md)

IoCompletion

Completes a driver's processing of an IRP.

[Completing IRPs](completing-irps.md)

Cancel

Cancels a driver's processing of an IRP.

[Canceling IRPs](canceling-irps.md)

CustomTimerDpc, IoTimer

Timing and synchronizing events.

[Synchronization Techniques](synchronization-techniques.md)

+ +  + +The current IRP and target device object are input parameters to many standard routines. Every driver processes each IRP in stages through its set of standard routines. + +By convention, the system-supplied drivers prepend an identifying, driver-specific or device-specific prefix to the name of every standard routine except **DriverEntry**. As an example, this documentation uses "DD", as shown in the [driver object illustration](introduction-to-driver-objects.md#driver-object-illustration). Following this convention makes it easier to debug and maintain drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Standard%20Driver%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-synchcritsection-routines.md b/windows-driver-docs-pr/kernel/introduction-to-synchcritsection-routines.md new file mode 100644 index 0000000000..a25799c6ef --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-synchcritsection-routines.md @@ -0,0 +1,38 @@ +--- +title: Introduction to SynchCritSection Routines +author: windows-driver-content +description: Introduction to SynchCritSection Routines +ms.assetid: 747f314a-9c7c-427f-bc23-4c6869853852 +keywords: ["SynchCritSection", "critical section routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to SynchCritSection Routines + + +## + + +*Critical sections* are sections of code that require exclusive access to hardware resources or driver data. That is, the code must not be interrupted by other code that can reference the same resources or data, and the resources or data must not be referenced by more than one processor at a time. + +Critical sections should be confined to ISRs and [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines. The system calls these routines only after raising the current processor's IRQL to the device's [*DIRQL*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-interrupt-request-level--dirql-) value and acquiring a spin lock. After a *SynchCritSection* routine returns, the system releases the spin lock and lowers the processor's IRQL. + +Raising the processor's IRQL to the device's DIRQL value prevents the current processor from being interrupted, except by a higher-priority device. Acquiring a spin lock prevents other processors from executing any critical section code associated with that spin lock. (This spin lock is sometimes called an *interrupt spin lock*.) + +A device driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routines frequently must access some of the same [hardware resources](hardware-resources.md) (such as device registers or other bus-relative memory) or driver-maintained data as the driver's ISR. Depending on the driver's device or design, its dispatch, [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504), [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049), or timer routines also might access hardware resources or driver-maintained data. + +To call any non-ISR critical section, a driver must use the [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) routine. This routine accepts the address of a *SynchCritSection* routine as input, along with driver-defined context information and an interrupt object pointer. The system uses the interrupt object pointer to determine the DIRQL and spin lock to use with the *SynchCritSection* routine. (The driver previously supplied these values, using the [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371) function's *SpinLock* and *SynchronizeIrql* parameters.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20SynchCritSection%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-the-common-log-file-system.md b/windows-driver-docs-pr/kernel/introduction-to-the-common-log-file-system.md new file mode 100644 index 0000000000..42dfedd6b0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-the-common-log-file-system.md @@ -0,0 +1,58 @@ +--- +title: Introduction to the Common Log File System +author: windows-driver-content +description: Introduction to the Common Log File System +ms.assetid: 2185d834-81f3-4bf9-afa6-897c1515f8b5 +keywords: ["Common Log File System WDK kernel , about Common Log File System", "CLFS WDK kernel , about Common Log File System", "logging service WDK CLFS", "Common Log File System WDK user-mode", "CLFS WDK user-mode", "logs WDK CLFS", "multiplexed logs WDK CLFS", "dedicated logs WDK CLFS", "log sequence numbers WDK CLFS", "LSNs WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to the Common Log File System + + +## + + +The Common Log File System (CLFS) is a general-purpose logging service that can be used by software [*clients*](clfs-terminology.md#kernel-clfs-term-client) running in user-mode or kernel-mode. This documentation discusses the CLFS interface for kernel-mode clients. For information about the user-mode interface, see Common Log File System in the Microsoft Windows SDK. + +CLFS encapsulates all the functionality of the Algorithm for Recovery and Isolation Exploiting Semantics (ARIES). However, the CLFS device driver interface (DDI) is not limited to supporting ARIES; it is well suited to a variety of logging scenarios. + +The primary job of any high-performance transactional log is to allow log clients to accurately repeat history. CLFS does this by marshalling client log records into memory buffers, forcing them to stable storage, and reading records back on request. It is important to note that after a record makes it to stable storage and the storage media is intact, CLFS will be able to read the record across system failures. + +CLFS supports dedicated logs and multiplexed logs. A dedicated log has a single [*stream*](clfs-terminology.md#kernel-clfs-term-stream) of log records that is used by all of the log's clients. A multiplexed log (also called a common log) has several streams. Each stream has its own clients and its own memory buffers for marshalling log records, but the records from all those buffers are multiplexed into a single queue and flushed to a single log on stable storage. Multiplexing allows the I/O operations of several streams to be consolidated. + +When a client writes a record to a stream, it gets back a log sequence number (LSN) that identifies the log record for future reference. The LSNs assigned to the records that are written to a particular stream form an increasing sequence. That is, the LSN assigned to a record that is written to a stream is always greater than the LSN assigned to the previous record written to that same stream. + +CLFS provides several services in addition to marshalling, flushing, and retrieving log records. The following list describes some of those additional services. + +- Space for a set of related log records can be reserved ahead of time. This means that a client can proceed with a transaction knowing that CLFS will be able to append to the log all of the records that describe the transaction. + +- CLFS maintains a header for each log record. Clients can set certain fields in the header to create chains of linked records that you can later traverse in reverse order. + +- CLFS flushes log records to stable storage according to its policy, but also allows clients to force a set of log records to stable storage. + +- CLFS maintains metadata for a log and also for each stream of a multiplexed log. Clients can view metadata and set certain portions of the metadata. + +- For each stream, CLFS maintains a base LSN and a last LSN that a client can use to delineate the active portion of the stream. + +- For dedicated logs, CLFS maintains (at the client's request) an archive tail that the client can use to keep track of the portion of the log that has been archived. + +Certain features of CLFS (for example, the previous LSN and undo-next LSN fields of a record header) can be best understood by studying ARIES. For more information about ARIES, see the following papers. + +- C. Mohan, Don Haderle, Bruce Lindsay, Hamid Pirahesh, Peter Schwarz, *ARIES: A Transaction Recovery Method Supporting Fine-Granularity Locking and Partial Rollbacks Using Write-Ahead Logging*. + +- C. Mohan, *Repeating History Beyond ARIES*. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20the%20Common%20Log%20File%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-thread-objects.md b/windows-driver-docs-pr/kernel/introduction-to-thread-objects.md new file mode 100644 index 0000000000..fec7cef6c5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-thread-objects.md @@ -0,0 +1,54 @@ +--- +title: Introduction to Thread Objects +author: windows-driver-content +description: Introduction to Thread Objects +ms.assetid: c41dd20e-07c1-432f-b012-ecc45fe44413 +keywords: ["thread objects WDK kernel", "system-process threads WDK kernel", "device-dedicated threads WDK kernel", "system worker threads WDK kernel", "worker threads WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Thread Objects + + +## + + +A user-mode thread object represents a path of execution within the current process. Every user-mode thread object is implemented through the use of an embedded kernel-mode thread object. + +A kernel-mode thread object is an instance of a kernel-defined dispatcher object type. The thread that it represents is the basic schedulable entity in the operating system. + +A thread object: + +- Is dispatched for execution by the kernel. + +- Has the following properties at any given moment: + + - [*dispatch state*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-dispatch-state) + + - [*priority*](https://msdn.microsoft.com/library/windows/hardware/ff556325#wdkgloss-priority) + + - [*context*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-context) + + - Execution mode (kernel or user) + + - [*affinity*](https://msdn.microsoft.com/library/windows/hardware/ff556270#wdkgloss-affinity) + +- Is "owned by" a process object but can attach itself to another process's address space. + +Usually, most drivers execute in the context of the currently running thread, that is, in an arbitrary thread context. While a file system driver can create an independent process for its own device-dedicated threads, file systems usually avoid setting up a driver-created process and threads in order to conserve system memory and to avoid the overhead of context switches. + +FSs (and other drivers) can set up device-dedicated (system-process) threads and/or FSs can use system worker threads if they need a driver-specific thread context in which to execute. Drivers use the kernel-mode **Ps*Xxx*** routines to create processes and/or device-dedicated threads. FSs call **Ex*Xxx*** routines to use system worker threads. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Thread%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-threaded-dpcs.md b/windows-driver-docs-pr/kernel/introduction-to-threaded-dpcs.md new file mode 100644 index 0000000000..e30de79283 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-threaded-dpcs.md @@ -0,0 +1,44 @@ +--- +title: Introduction to Threaded DPCs +author: windows-driver-content +description: Introduction to Threaded DPCs +ms.assetid: 891a8a52-83ff-400a-9477-8edca1b9a83c +keywords: ["threaded DPCs WDK kernel", "real-time threads WDK kernel", "preempted DPCs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Threaded DPCs + + +## + + +Threaded DPCs are available in Windows Vista and later versions of Windows. + +A *threaded DPC* is a DPC that the system executes at IRQL = PASSIVE\_LEVEL. Threaded DPCs are enabled by default, but you can disable them by setting the **HKLM\\System\\CCS\\Control\\SessionManager\\Kernel\\ThreadDpcEnable** registry key to zero. When threaded DPCs are disabled, they execute as ordinary DPCs. + +An ordinary DPC preempts the execution of all threads, and cannot be preempted by a thread or by another DPC. If the system has a large number of ordinary DPCs queued, or if one of those DPCs runs for a long time, every thread will remain paused for an arbitrarily long time. Thus, each ordinary DPC increases system latency, which can hurt the performance of time-sensitive applications, such as audio or video playback. + +Conversely, a threaded DPC can be preempted by an ordinary DPC, but not by other threads. Therefore, you should use threaded DPCs rather than ordinary DPCs—unless a particular DPC must not be preempted, not even by another DPC. + +The system represents threaded DPCs (and ordinary DPCs) as [**KDPC**](https://msdn.microsoft.com/library/windows/hardware/ff551882) structures. To initialize a **KDPC** structure for a threaded DPC, call the [**KeInitializeThreadedDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552166) routine, and pass it a [*CustomThreadedDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542976) routine that performs the action of the DPC. + +Because a *CustomThreadedDpc* routine can execute at either PASSIVE\_LEVEL or DISPATCH\_LEVEL, you must ensure that your *CustomThreadedDpc* routine correctly synchronizes at both IRQLs. For more information about how to do so, see [Synchronization and Threaded DPCs](synchronization-and-threaded-dpcs.md). + +In addition, you must ensure that your *CustomThreadedDpc* routine obeys all the restrictions for DISPATCH\_LEVEL code. If threaded DPCs are enabled, they run at IRQL = PASSIVE\_LEVEL but are still subject to the same restrictions as ordinary DPCs. All of the code that executes in a threaded DPC—including all functions that are called by the *CustomThreadedDpc* routine—must conform to the restrictions of the DPC environment. For example, code must not block on passive-level synchronization objects, such as [KEVENT objects](defining-and-using-an-event-object.md). Most existing device stacks, such as networking, storage, and USB, do not support threaded DPC processing, and they might try to block if they detect that they are called at PASSIVE\_LEVEL. For similar reasons, the [Kernel-Mode Driver Framework](https://msdn.microsoft.com/library/windows/hardware/ff544296) (KMDF) does not support threaded DPC processing, and KMDF drivers should not try to use threaded DPCs. For more information about the DPC environment, see [Writing DPC Routines](writing-dpc-routines.md). + +To add a threaded DPC to the DPC queue, call [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185). To remove a threaded DPC from the queue before it executes, call [**KeRemoveQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553169). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Threaded%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-wdm.md b/windows-driver-docs-pr/kernel/introduction-to-wdm.md new file mode 100644 index 0000000000..923b5fa65f --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-wdm.md @@ -0,0 +1,60 @@ +--- +title: Introduction to WDM +author: windows-driver-content +description: To allow driver developers to write device drivers that are source-code compatible across all Microsoft Windows operating systems, the Windows Driver Model (WDM) was introduced. Kernel-mode drivers that follow WDM rules are called WDM drivers. +ms.assetid: 00225ec6-fe56-4cbc-b94d-2ba5f28c0bb9 +keywords: ["WDM WDK kernel", "Windows Driver Model WDK kernel", "WDM drivers WDK kernel", "Wdm.h", "Ntddk.h", "WDM drivers WDK kernel , about WDM drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to WDM + + +To allow driver developers to write device drivers that are source-code compatible across all Microsoft Windows operating systems, the *Windows Driver Model* (WDM) was introduced. Kernel-mode drivers that follow WDM rules are called *WDM drivers*. + +## + + +All WDM drivers must do the following: + +- Include Wdm.h, not Ntddk.h. (Note that Wdm.h is a subset of Ntddk.h.) + +- Be designed as a bus driver, a function driver, or a filter driver, as described in [Types of WDM Drivers](types-of-wdm-drivers.md). + +- Create device objects as described in [WDM Device Objects and Device Stacks](wdm-device-objects-and-device-stacks.md). + +- Support [Plug and Play (PnP)](implementing-plug-and-play.md). + +- Support [power management](implementing-power-management.md). + +- Support [Windows Management Instrumentation](implementing-wmi.md) (WMI). + +### Does the WDK Cover Non-WDM Drivers? + +The Windows Driver Kit (WDK) emphasizes the development of WDM drivers for kernel mode, but the WDK also includes information that is pertinent to kernel-mode drivers that do not follow WDM rules. This information allows you to maintain existing non-WDM drivers and to write new drivers that interface with these existing drivers. + +### Should You Always Write a WDM Driver? + +If you are writing new kernel-mode drivers, they should be WDM drivers, *unless* you are writing a driver that will be inserted into a stack of non-WDM drivers. Please read the documentation for device type-specific Microsoft-supplied drivers to determine how new drivers must interface with Microsoft-supplied drivers. For more device type-specific information, see [Device and Driver Technologies](https://msdn.microsoft.com/library/windows/hardware/ff557557).) + +**Note**  All new driver stacks should consist of WDM drivers. + +  + +There are cross-platform issues to consider, whether you are developing WDM or non-WDM drivers. For more information, see [Writing Drivers for Different Versions of Windows](https://msdn.microsoft.com/library/windows/hardware/ff554887). + +If you are writing a new WDM driver, you should also consider using the [Kernel-Mode Driver Framework](https://msdn.microsoft.com/library/windows/hardware/dn265580) (KMDF). KMDF provides interfaces that are simpler to use than WDM interfaces. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20WDM%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-windows-drivers.md b/windows-driver-docs-pr/kernel/introduction-to-windows-drivers.md new file mode 100644 index 0000000000..3343f41542 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-windows-drivers.md @@ -0,0 +1,38 @@ +--- +title: Introduction to Windows Drivers +author: windows-driver-content +description: Introduction to Windows Drivers +ms.assetid: 01a4b74d-df09-4cf3-ae4b-a86c62ba1763 +keywords: ["kernel-mode drivers WDK , about Windows drivers", "Windows drivers WDK", "drivers WDK , about Windows drivers", "drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to Windows Drivers + + +## + + +This section introduces design concepts for Microsoft Windows drivers. It contains the following topics: + +[Overview of Windows Components](overview-of-windows-components.md) + +[Types of Windows Drivers](types-of-windows-drivers.md) + +[Design Goals for Kernel-Mode Drivers](design-goals-for-kernel-mode-drivers.md) + +[Sample Kernel-Mode Drivers](sample-kernel-mode-drivers.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20Windows%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/introduction-to-wmi.md b/windows-driver-docs-pr/kernel/introduction-to-wmi.md new file mode 100644 index 0000000000..0d6e05eb46 --- /dev/null +++ b/windows-driver-docs-pr/kernel/introduction-to-wmi.md @@ -0,0 +1,40 @@ +--- +title: Introduction to WMI +author: windows-driver-content +description: Introduction to WMI +ms.assetid: 9ee0ecbb-05fc-42ab-8bad-7c647f30c82c +keywords: ["WMI WDK kernel , about Windows Management Instrumentation"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to WMI + + +## + + +By making your driver a WMI provider, you can: + +- Make custom data available to WMI consumers. + +- Permit WMI consumers to configure a device through a standard interface rather than a custom control panel application. + +- Notify WMI consumers of driver-defined events without requiring the consumer to poll or send IRPs. + +- Reduce driver overhead by collecting and sending only requested data to a single destination. + +- Annotate data and event blocks with descriptive driver-defined class names and optional descriptions that WMI clients can then enumerate and display to users. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Introduction%20to%20WMI%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/invalid-key-object-pointers-in-registry-notifications.md b/windows-driver-docs-pr/kernel/invalid-key-object-pointers-in-registry-notifications.md new file mode 100644 index 0000000000..a8db852a0d --- /dev/null +++ b/windows-driver-docs-pr/kernel/invalid-key-object-pointers-in-registry-notifications.md @@ -0,0 +1,43 @@ +--- +title: Invalid Key Object Pointers in Registry Notifications +author: windows-driver-content +description: Invalid Key Object Pointers in Registry Notifications +ms.assetid: 96709c34-63a7-4b4e-8588-c7e8b41b5dea +--- + +# Invalid Key Object Pointers in Registry Notifications + + +To avoid fatal errors and possible memory corruption, a registry filtering driver must not try to access a key object by using an invalid object pointer. This topic lists the circumstances in which the **Object** member of a registry callback notification structure might contain an undefined, non-**NULL** value. + +In a registry filtering driver, the second parameter of the [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine is a [**REG\_NOTIFY\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff560950) enumeration value. This value indicates which type of registry callback notification structure the third parameter of the *RegistryCallback* routine points to. The notification structure contains information about the registry operation. The type of this structure varies according to the registry operation that is being performed. + +Many of the notification structure types contain an **Object** member that points to a key object. In some cases, the **Object** member can contain a value that is non-**NULL**, but is not a pointer to a valid key object. + +### Key Object Value is Undefined + +If the second parameter in a call to the *RegistryCallback* routine of a registry filtering driver is a **REG\_NOTIFY\_CLASS** enumeration value of **RegNtPostCreateKeyEx** or **RegNtPostOpenKeyEx**, the third parameter is a pointer to a [**REG\_POST\_OPERATION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560971) structure. The **Object** member of this structure is valid only if the **Status** member of the structure is set to STATUS\_SUCCESS. Any other **Status** value, including a nonzero status code for which the **NT\_SUCCESS** macro evaluates to **TRUE**, indicates that the value of the **Object** member is undefined. + +### Key Object Value is Not in a Valid State + +If the second parameter in a registry callback is one of the following **REG\_NOTIFY\_CLASS** enumeration values, the **Object** member of the registry callback notification structure points to a key object that is being destroyed and whose reference count is zero: + +- **RegNtPreKeyHandleClose** ([**REG\_KEY\_HANDLE\_CLOSE\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560943) structure) + +- **RegNtPostKeyHandleClose** ([**REG\_POST\_OPERATION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560971) structure) + +- **RegNtCallbackObjectContextCleanup** ([**REG\_CALLBACK\_CONTEXT\_CLEANUP\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560919) structure) + +Because the **Object** member points to a key object that is not in a valid state, the registry filtering driver must not pass the **Object** pointer value as a parameter to a [Windows driver support routine](https://msdn.microsoft.com/library/windows/hardware/ff558686) (for example, **ObReferenceObjectByPointer**). + +However, during a [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) call to handle a **RegNtPreKeyHandleClose** or **RegNtPostKeyHandleClose** notification, a registry filter driver can call a [configuration manager routine](https://msdn.microsoft.com/library/windows/hardware/ff542038) (for example, [**CmGetBoundTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff541905)) that takes a registry object as a parameter. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Invalid%20Key%20Object%20Pointers%20in%20Registry%20Notifications%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ioacquireremovelockex.md b/windows-driver-docs-pr/kernel/ioacquireremovelockex.md new file mode 100644 index 0000000000..c5e8b5ea57 --- /dev/null +++ b/windows-driver-docs-pr/kernel/ioacquireremovelockex.md @@ -0,0 +1,55 @@ +--- +title: Windows kernel routines reserved for system use +author: windows-driver-content +description: Windows kernel routines reserved for system use +ms.assetid: 78b0562a-903a-467d-9bf0-f5499ae47063 +--- + +# Windows kernel routines reserved for system use + + +The following routines are reserved for system use: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
RoutineDescription
IoAcquireRemoveLockEx

See [IoAcquireRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff548204).

IoInitializeRemoveLockEx

Use [IoInitializeRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff549324) instead.

IoReleaseRemoveLockAndWaitEx

See [IoReleaseRemoveLockAndWait](https://msdn.microsoft.com/library/windows/hardware/ff549567).

IoReleaseRemoveLockEx

See [IoReleaseRemoveLock](https://msdn.microsoft.com/library/windows/hardware/ff549560).

+ +  + +## Related topics +[**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204) +[**IoInitializeRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549324) +[**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) +[**IoReleaseRemoveLockAndWait**](https://msdn.microsoft.com/library/windows/hardware/ff549567) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20routines%20reserved%20for%20system%20use%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/iocompletion-routines-for-device-power-irps.md b/windows-driver-docs-pr/kernel/iocompletion-routines-for-device-power-irps.md new file mode 100644 index 0000000000..06e1c49f6f --- /dev/null +++ b/windows-driver-docs-pr/kernel/iocompletion-routines-for-device-power-irps.md @@ -0,0 +1,52 @@ +--- +title: IoCompletion Routines for Device Power IRPs +author: windows-driver-content +description: IoCompletion Routines for Device Power IRPs +ms.assetid: c275fcba-5fa9-427c-8d7e-2339563985e4 +keywords: ["IoCompletion routines", "power IRPs WDK kernel , device changes", "state transitions WDK power management", "device state transitions WDK power management", "working state returns WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# IoCompletion Routines for Device Power IRPs + + +## + + +After the bus driver completes the IRP, the I/O manager calls the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines registered by higher-level drivers as they passed the IRP down the stack. + +Whenever a device enters the D0 state, each of its drivers should set an *IoCompletion* routine that performs most of the tasks required to return it to the working state. Drivers should set an *IoCompletion* routine for any transition to the D0 state, whether the device is returning from a sleeping state or entering D0 at system start-up. The following figure shows the tasks such an *IoCompletion* routine should perform. + +![diagram illustrating the device power-up iocompletion routine](images/d0-comp.png) + +These tasks include: + +- Restoring device power state or reinitializing the device, as required, and preparing to handle any I/O queued by drivers while the device was not in the working state + +- Calling [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager that the device is in the D0 power state. + +- Calling [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to receive the next power IRP, if the driver did not originally send the current power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only). + +- Freeing memory allocated for the device context. + +- Calling [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to free the lock that the driver acquired in its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine when it received the IRP. + +- Returning STATUS\_SUCCESS. + +The bus driver does not power up the device until it or higher drivers must communicate with the device. + +When its device enters a sleeping state, a driver should set an *IoCompletion* routine that calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) (Windows Server 2003, Windows XP, and Windows 2000 only) and releases the remove lock. Remember that a driver cannot access its device while the device is in a sleeping state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IoCompletion%20Routines%20for%20Device%20Power%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/iocompletion-routines-for-wait-wake-irps.md b/windows-driver-docs-pr/kernel/iocompletion-routines-for-wait-wake-irps.md new file mode 100644 index 0000000000..6a504f05ab --- /dev/null +++ b/windows-driver-docs-pr/kernel/iocompletion-routines-for-wait-wake-irps.md @@ -0,0 +1,44 @@ +--- +title: IoCompletion Routines for Wait/Wake IRPs +author: windows-driver-content +description: IoCompletion Routines for Wait/Wake IRPs +ms.assetid: 61239398-2d37-4163-8128-7a4a0916a262 +keywords: ["receiving wait/wake IRPs", "wait/wake IRPs WDK power management , receiving", "IoCompletion routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# IoCompletion Routines for Wait/Wake IRPs + + +## + + +The I/O manager calls a driver's wait/wake [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine after the next-lower driver in the device stack has completed the wait/wake IRP. Each function and filter (FDO) driver that handles a wait/wake IRP should set an *IoCompletion* routine for the IRP. + +Each function or filter driver sets an *IoCompletion* routine as it handles the wait/wake IRP on its way down the device stack. The device power policy owner, which sends the IRP, might therefore have an *IoCompletion* routine in addition to a callback routine. Keep in mind that the callback routine is invoked after the *IoCompletion* routine and that the two have different requirements. For more information, see [Wait/Wake Callback Routines](wait-wake-callback-routines.md). + +The actions required in a wait/wake *IoCompletion* routine depend on the device and the type of driver. The following are some actions a driver might need to perform in its wait/wake *IoCompletion* routine: + +1. Reset any relevant fields in the device extension. For example, when a wait/wake IRP is pending, most drivers set a flag and keep a pointer to the IRP in the device extension. + +2. Reset the [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine, if any, for the IRP by calling [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674), specifying a **NULL** pointer for the routine. + +3. Call **IoCompleteRequest**, specifying IO\_NO\_INCREMENT, to complete the IRP. + +As each successive driver completes the IRP, the I/O manager passes control to the *IoCompletion* routine of the next-higher driver going back up the stack. + +After calling the *IoCompletion* routines set by drivers as they passed the wait/wake IRP down the device stack, the I/O manager calls the callback routine passed to [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) by the driver that sent the IRP. For further information, see [Wait/Wake Callback Routines](wait-wake-callback-routines.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IoCompletion%20Routines%20for%20Wait/Wake%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/iotimer-routines.md b/windows-driver-docs-pr/kernel/iotimer-routines.md new file mode 100644 index 0000000000..1e31dc818c --- /dev/null +++ b/windows-driver-docs-pr/kernel/iotimer-routines.md @@ -0,0 +1,40 @@ +--- +title: IoTimer Routines +author: windows-driver-content +description: IoTimer Routines +ms.assetid: bc69c7b5-ce63-435e-b5b4-0d65ee153d31 +keywords: ["synchronization WDK kernel , timers", "IoTimer", "device time-outs WDK kernel", "time-outs WDK kernel", "timing operations WDK kernel", "timeout device I/O operations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# IoTimer Routines + + +## + + +Drivers that need to be called periodically to determine if a device operation has timed out, to update some driver-defined variable (such as a counter), or to time any operation for which small time intervals are not required, can use an [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine. An *IoTimer* routine is actually a DPC routine, associated with a device object, that the I/O manager calls once per second. A driver can have an *IoTimer* routine for each device object that it creates. + +In general, a driver should use an *IoTimer* routine to time operations that require regular one-second intervals. To time operations that require variable intervals or intervals shorter than once per second, a driver should allocate a timer object. For more information, see [Timer Objects and DPCs](timer-objects-and-dpcs.md). + +This section contains the following topics: + +[Registering and Enabling an IoTimer Routine](registering-and-enabling-an-iotimer-routine.md) + +[Providing IoTimer Context Information](providing-iotimer-context-information.md) + +[Using an IoTimer Routine](using-an-iotimer-routine.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IoTimer%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-major-function-codes.md b/windows-driver-docs-pr/kernel/irp-major-function-codes.md new file mode 100644 index 0000000000..c2cfd2ab59 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-major-function-codes.md @@ -0,0 +1,71 @@ +--- +title: IRP Major Function Codes +author: windows-driver-content +description: IRP Major Function Codes +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 11c5b1a9-74c0-47fb-8cce-a008ece9efae +--- + +# IRP Major Function Codes + + +## + + +Each driver-specific I/O stack location ([**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659)) for every [**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694) contains a major function code (**IRP\_MJ\_*XXX***), which tells the driver what operation it or the underlying device driver should carry out to satisfy the I/O request. Each kernel-mode driver must provide [*dispatch routines*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-dispatch-routine) for the major function codes that it must support. + +The specific operations a driver carries out for a given **IRP\_MJ\_*XXX*** code depend somewhat on the underlying device, particularly for [**IRP\_MJ\_DEVICE\_CONTROL**](irp-mj-device-control.md) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](irp-mj-internal-device-control.md) requests. For example, the requests sent to a keyboard driver are necessarily somewhat different from those sent to a disk driver. However, the I/O manager defines the parameters and I/O stack location contents for each system-defined major function code. + +Every higher-level driver must set up the appropriate I/O stack location in IRPs for the next-lower-level driver and call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336), either with each input IRP, or with a driver-created IRP (if the higher-level driver holds on to the input IRP). Consequently, every intermediate driver must supply a dispatch routine for each major function code that the underlying device driver handles. Otherwise, a new intermediate driver will "break the chain" whenever an application or still higher-level driver attempts to send an I/O request down to the underlying device driver. + +File system drivers also handle a required subset of system-defined **IRP\_MJ\_*XXX*** function codes, some with subordinate **IRP\_MN\_*XXX*** function codes. + +Drivers handle IRPs set with some or all of the following major function codes: + +[**IRP\_MJ\_CLEANUP**](irp-mj-cleanup.md) + +[**IRP\_MJ\_CLOSE**](irp-mj-close.md) + +[**IRP\_MJ\_CREATE**](irp-mj-create.md) + +[**IRP\_MJ\_DEVICE\_CONTROL**](irp-mj-device-control.md) + +[**IRP\_MJ\_FILE\_SYSTEM\_CONTROL**](irp-mj-file-system-control.md) + +[**IRP\_MJ\_FLUSH\_BUFFERS**](irp-mj-flush-buffers.md) + +[**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](irp-mj-internal-device-control.md) + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) + +[**IRP\_MJ\_POWER**](irp-mj-power.md) + +[**IRP\_MJ\_QUERY\_INFORMATION**](irp-mj-query-information.md) + +[**IRP\_MJ\_READ**](irp-mj-read.md) + +[**IRP\_MJ\_SET\_INFORMATION**](irp-mj-set-information.md) + +[**IRP\_MJ\_SHUTDOWN**](irp-mj-shutdown.md) + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) + +[**IRP\_MJ\_WRITE**](irp-mj-write.md) + +The input and output parameters described in this section are the function-specific parameters in the IRP. + +For more information about IRPs, see [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP%20Major%20Function%20Codes%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-cleanup.md b/windows-driver-docs-pr/kernel/irp-mj-cleanup.md new file mode 100644 index 0000000000..d25b942d41 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-cleanup.md @@ -0,0 +1,79 @@ +--- +title: IRP\_MJ\_CLEANUP +author: windows-driver-content +description: Drivers that maintain process-specific context information must handle cleanup requests in DispatchCleanup routines. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 097f5f1d-3e88-4db0-bb79-db2267bdaf38 +keywords: + - IRP_MJ_CLEANUP Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_CLEANUP + + +Drivers that maintain process-specific context information must handle cleanup requests in [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) routines. + +When Sent +--------- + +Receipt of this request indicates that the last handle for a file object that is associated with the target device object has been closed (but, due to outstanding I/O requests, might not have been released). + +## Input Parameters + + +None + +## Output Parameters + + +None + +Operation +--------- + +This IRP is sent in the context of the process that closed the file object handle. Therefore, the driver should release process-specific resources, such as user memory, that the driver previously locked or mapped. + +If the driver's device objects were set up as exclusive, so that only a single thread can use the device at a time, the driver must complete every IRP that is currently queued to the target device object and set STATUS\_CANCELLED in each IRP's I/O status block. + +Otherwise, the driver must cancel and complete only the currently queued IRPs that are associated with the file object handle that is being released. (A pointer to the file object is located in the **FileObject** member of the driver's [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) of the IRP.) After canceling these queued IRPs, the driver completes the cleanup IRP and sets STATUS\_SUCCESS in its I/O status block. + +For more information about handling this request, see [DispatchCleanup Routines](https://msdn.microsoft.com/library/windows/hardware/ff543242). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) + +[**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) + +[**IRP\_MJ\_CLOSE**](irp-mj-close.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_CLEANUP%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-close.md b/windows-driver-docs-pr/kernel/irp-mj-close.md new file mode 100644 index 0000000000..0b2f1e4a9e --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-close.md @@ -0,0 +1,77 @@ +--- +title: IRP\_MJ\_CLOSE +author: windows-driver-content +description: Every driver must handle close requests in a DispatchClose routine, with the possible exception of a driver whose device cannot be disabled or removed from the machine without bringing down the system. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 109819a8-3787-448d-a766-5d53dbcf55f4 +keywords: + - IRP_MJ_CLOSE Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_CLOSE + + +Every driver must handle close requests in a [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routine, with the possible exception of a driver whose device cannot be disabled or removed from the machine without bringing down the system. A disk driver whose device holds the system page file is an example of such a driver. Note that the driver of such a device also cannot be unloaded dynamically. + +When Sent +--------- + +Receipt of this request indicates that the last handle of the file object that is associated with the target device object has been closed and released. All outstanding I/O requests have been completed or canceled. + +## Input Parameters + + +None + +## Output Parameters + + +None + +Operation +--------- + +Many device and intermediate drivers merely set STATUS\_SUCCESS in the I/O status block of the IRP and complete the close request. However, what a given driver does on receipt of a close request depends on the driver's design. In general, a driver should undo whatever actions it takes on receipt of the [**IRP\_MJ\_CREATE**](irp-mj-create.md) request. Device drivers whose device objects are exclusive, such as a serial driver, also can reset the hardware on receipt of a close request. + +The **IRP\_MJ\_CLOSE** request is not necessarily sent in the context of the process that closed the file object handle. If the driver must release process-specific resources, such as user memory, that the driver previously locked or mapped, it must do so in response to an [**IRP\_MJ\_CLEANUP**](irp-mj-cleanup.md) request. + +The **IRP\_MJ\_CLOSE** request will always be sent at PASSIVE\_LEVEL. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) + +[**IRP\_MJ\_CLEANUP**](irp-mj-cleanup.md) + +[**IRP\_MJ\_CREATE**](irp-mj-create.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_CLOSE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-create.md b/windows-driver-docs-pr/kernel/irp-mj-create.md new file mode 100644 index 0000000000..6ddc6486db --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-create.md @@ -0,0 +1,81 @@ +--- +title: IRP\_MJ\_CREATE +author: windows-driver-content +description: Every kernel-mode driver must handle IRP\_MJ\_CREATE requests in a DispatchCreate or DispatchCreateClose routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 2947f8dc-2e7d-401e-8014-6140cac6905f +keywords: + - IRP_MJ_CREATE Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_CREATE + + +Every kernel-mode driver must handle **IRP\_MJ\_CREATE** requests in a [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) or [*DispatchCreateClose*](https://msdn.microsoft.com/library/windows/hardware/ff543270) routine. + +When Sent +--------- + +The operating system sends an **IRP\_MJ\_CREATE** request to open a handle to a file object or device object. For example, when a driver calls [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424), the operating system sends an **IRP\_MJ\_CREATE** request to perform the actual open operation. + +## Input Parameters + + +The **Parameters.Create.SecurityContext** member points to an [**IO\_SECURITY\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff550613) structure that describes the security context for the request. The **Parameters.Create.SecurityContext->DesiredAccess** member is an access mask that specifies the access rights that are being requested by the caller. + +The **Parameters.Create.Options** member is a ULONG value that describes the options that are used when opening the handle. The high 8 bits correspond to the value of the *CreateDisposition* parameter of **ZwCreateFile**, and the low 24 bits correspond to the value of the *CreateOptions* parameter of **ZwCreateFile**. + +The **Parameters.Create.ShareAccess** member is a USHORT value that describes the type of share access. This value corresponds to the value of the *ShareAccess* parameter of **ZwCreateFile**. + +The **Parameters.Create.FileAttributes** and **Parameters.Create.EaLength** members are reserved for use by file systems and file system filter drivers. For more information, see the [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff548630) topic in the Installable File System (IFS) documentation. + +## Output Parameters + + +None + +Operation +--------- + +Most device and intermediate drivers set STATUS\_SUCCESS in the I/O status block of the IRP and complete the create request, but drivers can optionally use their [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) routine to reserve resources for any subsequent I/O requests for that handle. For example, the system serial driver maps its paged-out code and allocates any resources that are necessary to handle subsequent I/O requests for the user-mode thread that is attempting to open the device for input and output. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) + +[*DispatchCreateClose*](https://msdn.microsoft.com/library/windows/hardware/ff543270) + +[**IO\_SECURITY\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff550613) + +[**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_CREATE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-device-control.md b/windows-driver-docs-pr/kernel/irp-mj-device-control.md new file mode 100644 index 0000000000..066f7cb3a2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-device-control.md @@ -0,0 +1,79 @@ +--- +title: IRP\_MJ\_DEVICE\_CONTROL +author: windows-driver-content +description: Every driver whose device objects belong to a particular device type (see Specifying Device Types) is required to support this request in a DispatchDeviceControl routine, if a set of system-defined I/O control codes (IOCTLs) exists for the type. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: c6436b34-22bd-4e65-bfb0-b2c4d9962e29 +keywords: + - IRP_MJ_DEVICE_CONTROL Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_DEVICE\_CONTROL + + +Every driver whose device objects belong to a particular device type (see [Specifying Device Types](https://msdn.microsoft.com/library/windows/hardware/ff563821)) is required to support this request in a [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine, if a set of system-defined I/O control codes ([*IOCTLs*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-ioctl)) exists for the type. + +Higher-level drivers usually pass these requests on to an underlying device driver. Each device driver in a driver stack is assumed to support this request, along with a set of device type-specific, public or private IOCTLs. For more information about IOCTLs for specific device types, see device type-specific documentation in the Microsoft Windows Driver Kit (WDK). + +When Sent +--------- + +Any time following the successful completion of a create request. + +## Input Parameters + + +The I/O control code is contained at **Parameters.DeviceIoControl.IoControlCode** in the driver's I/O stack location of the IRP. + +Other input parameters depend on the I/O control code's value. For more information, see [Buffer Descriptions for I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff540663). + +## Output Parameters + + +Output parameters depend on the I/O control code's value. For more information, see [Buffer Descriptions for I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff540663). + +Operation +--------- + +A driver receives this I/O control code because user-mode thread has called the Microsoft Win32 [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) function, or a higher-level kernel-mode driver has set up the request. Possibly, a user-mode driver has called **DeviceIoControl**, passing in a driver-defined (also called *private*) I/O control code, to request device- or driver-specific support from a closely coupled, kernel-mode device driver. + +On receipt of a device I/O control request, a higher-level driver usually passes the IRP on to the next-lower driver. However, there are some exceptions to this practice. For example, a class driver that has stored configuration information obtained from the underlying port driver might complete certain IOCTL\_*XXX* requests without passing the IRP down to the corresponding port driver. + +On receipt of a device I/O control request, a device driver examines the I/O control code to determine how to satisfy the request. For most public I/O control codes, device drivers transfer a small amount of data to or from the buffer at **Irp->AssociatedIrp.SystemBuffer**. + +For general information about I/O control codes for **IRP\_MJ\_DEVICE\_CONTROL** or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](irp-mj-internal-device-control.md) requests, see [Using I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff565406). See also [Device Type-Specific I/O Requests](https://msdn.microsoft.com/library/windows/hardware/ff543205). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_DEVICE_CONTROL%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-file-system-control.md b/windows-driver-docs-pr/kernel/irp-mj-file-system-control.md new file mode 100644 index 0000000000..0bf84aa52d --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-file-system-control.md @@ -0,0 +1,44 @@ +--- +title: IRP\_MJ\_FILE\_SYSTEM\_CONTROL +author: windows-driver-content +description: Only file system drivers process IRP\_MJ\_FILE\_SYSTEM\_CONTROL requests. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 695ed61b-7082-44be-ae82-ddc3e4a0b8d0 +keywords: + - IRP_MJ_FILE_SYSTEM_CONTROL Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_FILE\_SYSTEM\_CONTROL + + +Only file system drivers process **IRP\_MJ\_FILE\_SYSTEM\_CONTROL** requests. For more information about the use of this IRP major function code by file system drivers, see [**IRP\_MJ\_FILE\_SYSTEM\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff548670). For more information about file system drivers, see [File System Drivers](https://msdn.microsoft.com/library/windows/hardware/ff540376). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_FILE_SYSTEM_CONTROL%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-flush-buffers.md b/windows-driver-docs-pr/kernel/irp-mj-flush-buffers.md new file mode 100644 index 0000000000..7aa26261ee --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-flush-buffers.md @@ -0,0 +1,69 @@ +--- +title: IRP\_MJ\_FLUSH\_BUFFERS +author: windows-driver-content +description: Drivers of devices with internal caches for data and drivers that maintain internal buffers for data must handle this request in a DispatchFlushBuffers routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: c1023999-0c80-4c09-a9ea-a9422184bba7 +keywords: + - IRP_MJ_FLUSH_BUFFERS Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_FLUSH\_BUFFERS + + +Drivers of devices with internal caches for data and drivers that maintain internal buffers for data must handle this request in a [*DispatchFlushBuffers*](https://msdn.microsoft.com/library/windows/hardware/ff543314) routine. + +When Sent +--------- + +Receipt of a flush request indicates that the driver should flush the device's cache or its internal buffer, or, possibly, should discard the data in its internal buffer. + +## Input Parameters + + +None + +## Output Parameters + + +None + +Operation +--------- + +The driver transfers any data currently cached in the device or held in the driver's internal buffers before completing the flush request. The driver of an input-only device that buffers data internally might simply discard the currently buffered device data before completing the flush IRP, depending on the nature of its device. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchFlushBuffers*](https://msdn.microsoft.com/library/windows/hardware/ff543314) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_FLUSH_BUFFERS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-internal-device-control.md b/windows-driver-docs-pr/kernel/irp-mj-internal-device-control.md new file mode 100644 index 0000000000..8eb9dcd860 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-internal-device-control.md @@ -0,0 +1,83 @@ +--- +title: IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL +author: windows-driver-content +description: In general, any replacement for an existing driver that supports internal device control requests should handle this request in a DispatchInternalDeviceControl routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: fb3d4534-9c6f-4956-b702-5752f9798600 +keywords: + - IRP_MJ_INTERNAL_DEVICE_CONTROL Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL + + +In general, any replacement for an existing driver that supports internal device control requests should handle this request in a [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routine. Such a driver must support at least the same set of internal I/O control codes as the driver it replaces. Otherwise, existing higher-level drivers might not work with the new driver. + +Drivers that replace certain lower-level system drivers are required to handle this request. For example, a replacement for the system parallel port driver must continue to support existing parallel class drivers. Note that certain system drivers that handle this request cannot be replaced, in particular, the system-supplied SCSI and video port drivers. + +When Sent +--------- + +Any time after the successful completion of a create request. + +## Input Parameters + + +The I/O control code is contained at **Parameters.DeviceIoControl.IoControlCode** in the I/O stack location of the IRP. + +Other input parameters depend on the I/O control code's value. For more information, see [Buffer Descriptions for I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff540663). + +## Output Parameters + + +Output parameters depend on the I/O control code's value. For more information, see [Buffer Descriptions for I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff540663). + +Operation +--------- + +Drivers receive **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests when another driver calls either [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) or [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) to create a request. + +This I/O control code has been defined for communication between paired and layered kernel-mode drivers, such as one or more class drivers layered over a port driver. The higher-level driver sets up IRPs with device- or driver-specific I/O control codes, requesting support from the next-lower driver. + +The requested operation is device- or driver-specific. + +For general information about I/O control codes for [**IRP\_MJ\_DEVICE\_CONTROL**](irp-mj-device-control.md) or **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** requests, see [Using I/O Control Codes](https://msdn.microsoft.com/library/windows/hardware/ff565406). See also [Device Type-Specific I/O Requests](https://msdn.microsoft.com/library/windows/hardware/ff543205). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) + +[**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) + +[**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_INTERNAL_DEVICE_CONTROL%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-pnp.md b/windows-driver-docs-pr/kernel/irp-mj-pnp.md new file mode 100644 index 0000000000..233aff0b26 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-pnp.md @@ -0,0 +1,69 @@ +--- +title: IRP\_MJ\_PNP +author: windows-driver-content +description: All drivers must be prepared to service IRP\_MJ\_PNP requests in a DispatchPnP routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: db838761-b838-44fd-bc77-c9d55d2c4a41 +keywords: + - IRP_MJ_PNP Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_PNP + + +All drivers must be prepared to service **IRP\_MJ\_PNP** requests in a [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + +When Sent +--------- + +The PnP manager sends **IRP\_MJ\_PNP** requests during enumeration, resource rebalancing, and any other time Plug and Play activity occurs on the system. Drivers can also send certain **IRP\_MJ\_PNP** requests, depending on the minor function code. + +## Input Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. Every **IRP\_MJ\_PNP** request specifies a minor function code that identifies the requested PnP action. + +## Output Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. + +Operation +--------- + +See [Plug and Play Minor IRPs](plug-and-play-minor-irps.md) for detailed information about **IRP\_MJ\_PNP** requests. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_PNP%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-power.md b/windows-driver-docs-pr/kernel/irp-mj-power.md new file mode 100644 index 0000000000..1163dc5199 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-power.md @@ -0,0 +1,71 @@ +--- +title: IRP\_MJ\_POWER +author: windows-driver-content +description: All drivers must be prepared to service IRP\_MJ\_POWER requests in a DispatchPower routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: ca53ceef-2755-49d3-aab9-0d12a0e51e75 +keywords: + - IRP_MJ_POWER Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_POWER + + +All drivers must be prepared to service **IRP\_MJ\_POWER** requests in a [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +When Sent +--------- + +The power manager or a driver can send **IRP\_MJ\_POWER** requests at any time the operating system is running. + +## Input Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. Every **IRP\_MJ\_POWER** request specifies a minor function code that identifies the requested power action. + +## Output Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. + +Operation +--------- + +In addition to the usual rules that govern the processing of IRPs, **IRP\_MJ\_POWER** IRPs have the following special requirement: A driver that receives a power IRP must not change the major and minor function codes in any I/O stack locations in the IRP that have been set by the power manager or by higher-level drivers. The power manager relies on these function codes remaining unchanged until the IRP is completed. Violations of this rule can cause problems that are difficult to debug. For example, the operating system might stop responding, or "hang." + +See [Power Management Minor IRPs](power-management-minor-irps.md) for detailed information about **IRP\_MJ\_POWER** requests. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_POWER%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-query-information.md b/windows-driver-docs-pr/kernel/irp-mj-query-information.md new file mode 100644 index 0000000000..f964e84735 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-query-information.md @@ -0,0 +1,73 @@ +--- +title: IRP\_MJ\_QUERY\_INFORMATION +author: windows-driver-content +description: Drivers can optionally handle an IRP\_MJ\_QUERY\_INFORMATION request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 317f82b1-88d3-4618-9282-140eca2178b5 +keywords: + - IRP_MJ_QUERY_INFORMATION Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_QUERY\_INFORMATION + + +Drivers can optionally handle an **IRP\_MJ\_QUERY\_INFORMATION** request. + +When Sent +--------- + +The operating system sends an **IRP\_MJ\_QUERY\_INFORMATION** request to obtain metadata about a file or file handle. For example, when a driver calls [**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052), the operating system sends an **IRP\_MJ\_QUERY\_INFORMATION** request. + +## Input Parameters + + +The **Parameters.QueryFile.FileInformationClass** member is a **FILE\_INFORMATION\_CLASS** constant that specifies the type of metadata to provide. For more information about the types of metadata, see the *FileInformationClass* parameter of the [**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052) routine. + +The **Parameters.QueryFile.Length** member specifies the length of the buffer that the **AssociatedIrp.SystemBuffer** member points to. + +## Output Parameters + + +The **AssociatedIrp.SystemBuffer** member points to the buffer where the driver supplies the requested information. The value of **Parameters.QueryFile.FileInformationClass** determines the format of the metadata (a **FILE\_*XXX*\_INFORMATION** structure) to return. For more information about the formats of metadata, see the [**FILE\_INFORMATION\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff728840) enumeration. + +Operation +--------- + +Drivers are not required to handle this request, and drivers that do are not required to handle every possible value of **Parameters.QueryFile.FileInformationClass**. The driver's dispatch routine should return an error code such as STATUS\_INVALID\_DEVICE\_REQUEST for any values that it does not handle. + +Not all of the possible values of [**FILE\_INFORMATION\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff728840) can occur. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_QUERY_INFORMATION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-read.md b/windows-driver-docs-pr/kernel/irp-mj-read.md new file mode 100644 index 0000000000..38469c5508 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-read.md @@ -0,0 +1,87 @@ +--- +title: IRP\_MJ\_READ +author: windows-driver-content +description: Every device driver that transfers data from its device to the system must handle read requests in a DispatchRead or DispatchReadWrite routine, as must any higher-level driver layered over such a device driver. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 5ae4c6c5-d8f2-4dc5-8cfd-ecb751fc88be +keywords: + - IRP_MJ_READ Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_READ + + +Every device driver that transfers data from its device to the system must handle read requests in a [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) or [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine, as must any higher-level driver layered over such a device driver. + +When Sent +--------- + +Any time following the successful completion of a create request. + +Possibly, a user-mode application or Win32 component with a handle for the file object representing the target device object has requested a data transfer from the device. Possibly, a higher-level driver has created and set up the read IRP. + +## Input Parameters + + +The driver's I/O stack location in the IRP indicates how many bytes to transfer at **Parameters.Read.Length**. + +Some drivers use the value at **Parameters.Read.Key** to sort incoming read requests into a driver-determined order in the device queue or in a driver-managed internal queue of IRPs. + +Certain types of drivers also use the value at **Parameters.Read.ByteOffset**, which indicates the starting offset for the transfer operation. For example, see the [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff549327) topic in the Installable File System (IFS) documentation. + +## Output Parameters + + +Depending on whether the underlying device driver sets up the target device object's **Flags** with DO\_BUFFERED\_IO or with DO\_DIRECT\_IO, data is transferred into one of the following: + +- The buffer at **Irp->AssociatedIrp.SystemBuffer** if the driver uses buffered I/O. + +- The buffer described by the MDL at **Irp->MdlAddress** if the underlying device driver uses direct I/O (DMA or PIO). + +Operation +--------- + +On receipt of a read request, a higher-level driver sets up the I/O stack location in the IRP for the next-lower driver, or it creates and sets up additional IRPs for one or more lower drivers. It can set up its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, which is optional for the input IRP but required for driver-created IRPs, by calling [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). Then, the driver passes the request on to the next-lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +On receipt of a read request, a device driver transfers data from its device to system memory. The device driver sets the **Information** field of the I/O status block to the number of bytes transferred when it completes the IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) + +[*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) + +[**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) + +[**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_READ%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-set-information.md b/windows-driver-docs-pr/kernel/irp-mj-set-information.md new file mode 100644 index 0000000000..ac1d361f53 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-set-information.md @@ -0,0 +1,75 @@ +--- +title: IRP\_MJ\_SET\_INFORMATION +author: windows-driver-content +description: Device drivers can optionally handle an IRP\_MJ\_SET\_INFORMATION request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 1bcca676-2926-4d0f-9c0f-c6ea56481153 +keywords: + - IRP_MJ_SET_INFORMATION Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_SET\_INFORMATION + + +Device drivers can optionally handle an **IRP\_MJ\_SET\_INFORMATION** request. + +When Sent +--------- + +The operating system sends an **IRP\_MJ\_SET\_INFORMATION** request to set metadata about a file or file handle. For example, when a driver calls [**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096), the operating system sends an **IRP\_MJ\_SET\_INFORMATION** request. + +## Input Parameters + + +The **Parameters.SetFile.FileInformationClass** member is a **FILE\_INFORMATION\_CLASS** constant that specifies the type of metadata to set. For more information about the types of metadata, see the *FileInformationClass* parameter of [**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096). + +The **Parameters.SetFile.Length** member specifies the length of the buffer that the **AssociatedIrp.SystemBuffer** member points to. + +**AssociatedIrp.SystemBuffer** points to the buffer that contains the new information setting. The value of **Parameters.SetFile.FileInformationClass** determines the format of the data (a **FILE\_*XXX*\_INFORMATION** structure) to return. For more information about the formats of metadata, see the [**FILE\_INFORMATION\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff728840) enumeration. + +## Output Parameters + + +None + +Operation +--------- + +Drivers are not required to handle this request, and drivers that do are not required to handle every possible value of **Parameters.SetFile.FileInformationClass**. The driver's dispatch routine should return an error code such as STATUS\_INVALID\_DEVICE\_REQUEST for any values that it does not handle. + +Not all of the possible values of [**FILE\_INFORMATION\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff728840) can occur. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_SET_INFORMATION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-shutdown.md b/windows-driver-docs-pr/kernel/irp-mj-shutdown.md new file mode 100644 index 0000000000..9883a278a8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-shutdown.md @@ -0,0 +1,77 @@ +--- +title: IRP\_MJ\_SHUTDOWN +author: windows-driver-content +description: Drivers of mass-storage devices that have internal caches for data must handle this request in a DispatchShutdown routine. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: af0b01b5-5f81-42da-aa4b-433bd422a51f +keywords: + - IRP_MJ_SHUTDOWN Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_SHUTDOWN + + +Drivers of mass-storage devices that have internal caches for data must handle this request in a [*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) routine. Drivers of mass-storage devices and intermediate drivers layered over them also must handle this request if an underlying driver maintains internal buffers for data. + +When Sent +--------- + +Receipt of a shutdown request indicates that a file system driver is sending notice that the system is being shut down. + +One or more file system drivers can send such a lower-level driver more than one shutdown request when a user logs off or when the system is being shut down for some other reason. + +## Input Parameters + + +None + +## Output Parameters + + +None + +Operation +--------- + +The driver must complete the transfer of any data currently cached in the device or held in the driver's internal buffers before completing the shutdown request. + +A driver does not receive an **IRP\_MJ\_SHUTDOWN** request for a device object unless it registers to do so with either [**IoRegisterShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549541) or [**IoRegisterLastChanceShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549518). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) + +[**IoRegisterLastChanceShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549518) + +[**IoRegisterShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549541) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_SHUTDOWN%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-system-control.md b/windows-driver-docs-pr/kernel/irp-mj-system-control.md new file mode 100644 index 0000000000..9206bcf001 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-system-control.md @@ -0,0 +1,73 @@ +--- +title: IRP\_MJ\_SYSTEM\_CONTROL +author: windows-driver-content +description: All drivers must provide a DispatchSystemControl routine that handles IRP\_MJ\_SYSTEM\_CONTROL requests, which are sent by the kernel-mode component of Windows Management Instrumentation (WMI). +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 1b4dfc87-3f74-4e33-9dbb-72d4f72480fc +keywords: + - IRP_MJ_SYSTEM_CONTROL Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_SYSTEM\_CONTROL + + +All drivers must provide a [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine that handles **IRP\_MJ\_SYSTEM\_CONTROL** requests, which are sent by the kernel-mode component of [Windows Management Instrumentation](https://msdn.microsoft.com/library/windows/hardware/ff547139) (WMI). + +When Sent +--------- + +The WMI kernel-mode component can send an **IRP\_MJ\_SYSTEM\_CONTROL** request any time following a driver's successful registration as a supplier of WMI data. WMI IRPs typically are sent when a user-mode data consumer has requested WMI data. + +## Input Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. Every **IRP\_MJ\_SYSTEM\_CONTROL** request specifies a minor function code that identifies the requested WMI action. + +## Output Parameters + + +Depends on the value at **MinorFunction** in the current I/O stack location of the IRP. + +Operation +--------- + +All drivers must support **IRP\_MJ\_SYSTEM\_CONTROL** requests by supplying a [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine. + +Drivers that support [Windows Management Instrumentation](https://msdn.microsoft.com/library/windows/hardware/ff547139) (WMI) must handle **IRP\_MJ\_SYSTEM\_CONTROL** requests by processing the minor function codes associated with this major function code. For information about the WMI minor function codes, see [WMI Minor IRPs](wmi-minor-irps.md). + +Drivers that do not support WMI by [registering as a WMI data provider](https://msdn.microsoft.com/library/windows/hardware/ff560870) must pass **IRP\_MJ\_SYSTEM\_CONTROL** requests to the next lower driver. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_SYSTEM_CONTROL%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mj-write.md b/windows-driver-docs-pr/kernel/irp-mj-write.md new file mode 100644 index 0000000000..a51fa29922 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mj-write.md @@ -0,0 +1,91 @@ +--- +title: IRP\_MJ\_WRITE +author: windows-driver-content +description: Every device driver that transfers data from the system to its device must handle write requests in a DispatchWrite or DispatchReadWrite routine, as must any higher-level driver layered over such a device driver. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: d0db505e-2b3c-4b69-83ef-1a52e37e5d1a +keywords: + - IRP_MJ_WRITE Kernel-Mode Driver Architecture +--- + +# IRP\_MJ\_WRITE + + +Every device driver that transfers data from the system to its device must handle write requests in a [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) or [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine, as must any higher-level driver layered over such a device driver. + +When Sent +--------- + +Any time following the successful completion of a create request. + +Possibly, a user-mode application or Win32 component with a handle for the file object representing the target device object has requested a data transfer to the device. Possibly, a higher-level driver has created and set up the write IRP. + +## Input Parameters + + +The driver's I/O stack location in the IRP indicates how many bytes to transfer at **Parameters.Write.Length**. + +Some drivers use the value at **Parameters.Write.Key** to sort incoming write requests into a driver-determined order in the device queue or in a driver-managed internal queue of IRPs. + +Certain types of drivers also use the value at **Parameters.Write.ByteOffset**, which indicates the starting offset for the transfer operation. For example, see the [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff549427) topic in the Installable File System (IFS) documentation. + +Depending on whether the underlying device driver sets up the target device object's **Flags** with DO\_BUFFERED\_IO or with DO\_DIRECT\_IO, data is transferred from one of the following: + +- The buffer at **Irp->AssociatedIrp.SystemBuffer**, if the driver uses buffered I/O + +- The buffer described by the MDL at **Irp->MdlAddress**, if the underlying device driver uses direct I/O (DMA or PIO) + +## Output Parameters + + +None + +Operation +--------- + +On receipt of a write request, a higher-level driver sets up the I/O stack location in the IRP for the next-lower driver, or it creates and sets up additional IRPs for one or more lower drivers. It can set up its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, which is optional for the input IRP but required for driver-created IRPs, by calling [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). Then, the driver passes the request on to the next-lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +On receipt of a write request, a device driver transfers data from system memory to its device. The device driver sets the **Information** field of the I/O status block to the number of bytes transferred when it completes the IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) + +[*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) + +[**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) + +[*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) + +[**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MJ_WRITE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-cancel-remove-device.md b/windows-driver-docs-pr/kernel/irp-mn-cancel-remove-device.md new file mode 100644 index 0000000000..47756b4c24 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-cancel-remove-device.md @@ -0,0 +1,96 @@ +--- +title: IRP\_MN\_CANCEL\_REMOVE\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 5cadb1e2-7011-42a5-8e41-6473069b25a6 +keywords: + - IRP_MN_CANCEL_REMOVE_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_CANCEL\_REMOVE\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to inform the drivers for a device that the device will not be removed. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver must set **Irp->IoStatus.Status** to STATUS\_SUCCESS for this IRP. If a driver fails this IRP, the device is left in an inconsistent state. + +Operation +--------- + +This IRP must be handled first by the parent bus driver for a device and then by each higher driver in the device stack. + +In response to this IRP, drivers return the device to the state it was in prior to receiving the **IRP\_MN\_QUERY\_REMOVE\_DEVICE** request. + +If the device is already started when the driver receives this IRP, the driver simply sets status to success and passes the IRP to the next driver (or completes the IRP if the driver is a bus driver). For such a cancel-remove IRP, a function or filter driver need not set a completion routine. The device may not be in the remove-pending state, because, for example, the driver failed the previous **IRP\_MN\_QUERY\_REMOVE\_DEVICE**. + +The PnP manager calls any **EventCategoryTargetDeviceChange** notification callbacks with GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED after the **IRP\_MN\_CANCEL\_REMOVE\_DEVICE** request completes. Such callbacks were registered on the device by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). The PnP manager also calls any user-mode components that registered for notification on the device by calling **RegisterDeviceNotification**. + +If a file system is mounted on the device, it must undo any operations it did in response to the query-remove notification. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for detailed information about handling remove IRPs and for the general rules for handling all [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) + +[**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_CANCEL_REMOVE_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-cancel-stop-device.md b/windows-driver-docs-pr/kernel/irp-mn-cancel-stop-device.md new file mode 100644 index 0000000000..c17f00c41d --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-cancel-stop-device.md @@ -0,0 +1,90 @@ +--- +title: IRP\_MN\_CANCEL\_STOP\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 7047c266-84b4-4260-ad75-d56c87c8c9ef +keywords: + - IRP_MN_CANCEL_STOP_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_CANCEL\_STOP\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP, at some point after an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md), to inform the drivers for a device that the device will not be disabled (Windows 98/Me only) or stopped for resource reconfiguration. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver must set **Irp->IoStatus.Status** to STATUS\_SUCCESS for this IRP. If a driver fails this IRP, the device is left in an inconsistent state. + +Operation +--------- + +This IRP must be handled first by the parent bus driver for a device and then by each higher driver in the device stack. + +In response to this IRP, drivers return the device to the started state. Drivers start any IRPs that were held while the device was in the stop-pending state. + +If the device is already in an active state when the driver receives this IRP, a function or filter driver simply sets status to success and passes the IRP to the next driver. The parent bus driver completes the IRP. For such a cancel-stop IRP, a function or filter driver need not set a completion routine. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for detailed information about handling stop IRPs and for the general rules for handling all [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_CANCEL_STOP_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-change-single-instance.md b/windows-driver-docs-pr/kernel/irp-mn-change-single-instance.md new file mode 100644 index 0000000000..0f1aef23ad --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-change-single-instance.md @@ -0,0 +1,136 @@ +--- +title: IRP\_MN\_CHANGE\_SINGLE\_INSTANCE +author: windows-driver-content +description: All drivers that support WMI must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 180d40a4-b300-4801-b9da-9239500ca15f +keywords: + - IRP_MN_CHANGE_SINGLE_INSTANCE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_CHANGE\_SINGLE\_INSTANCE + + +All drivers that support WMI must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_CHANGE\_SINGLE\_INSTANCE** request, WMI in turn calls that driver's [*DpWmiSetDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544104) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to change all data items in a single instance of a data block. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is found in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block associated with the instance to be changed. + +**Parameters.WMI.BufferSize** indicates the size of the nonpaged buffer at **Parameters.WMI.Buffer**. + +**Parameters.WMI.Buffer** points to a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure that identifies the instance and specifies new data values. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_INSTANCE\_NOT\_FOUND + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_WMI\_READ\_ONLY + +STATUS\_WMI\_SET\_FAILURE + +On success, the driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiSetDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544104) routine, or returns STATUS\_WMI\_READ\_ONLY if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_CHANGE\_SINGLE\_INSTANCE** request itself, it does so only if the device object pointer at **Parameters.WMI.ProviderId** matches the pointer passed by the driver in its call to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +If the driver handles the request, it must first check the GUID at **Parameters.WMI.DataPath** to determine whether it identifies a data block supported by the driver. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the data block, it must check the received [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure at **Parameters.WMI.Buffer** for the instance name, as follows: + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is set in **WnodeHeader.Flags**, the driver uses **InstanceIndex** as an index into the driver's list of static instance names for that block. WMI obtains the index from registration data provided by the driver when it registered the block. + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is clear in **WnodeHeader.Flags,** the driver uses the offset at **OffsetInstanceName** to locate the instance name string in the input [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377). **OffsetInstanceName** is the offset in bytes from the beginning of the structure to a USHORT-sized length of the instance name string in bytes (not characters), including the terminating null if present, followed by the instance name string in Unicode. + +The driver is responsible for validating all input values. Specifically, the driver must do the following if it handles the IRP request itself: + +- For static names, verify that the **InstanceIndex** member of the [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure is within the range of instance indexes supported by the driver for the data block. + +- For dynamic names, verify that the instance name string identifies a data block instance supported by the driver. + +- Verify that the **DataBlockOffset** and **SizeDataBlock** members of the **WNODE\_SINGLE\_INSTANCE** structure describe a valid-sized data block, including any padding that exists between data items, and that the contents of the buffer are valid for the data block. + +- Verify that the specified data block is one for which the driver allows caller-initiated modifications. In other words, the driver should not allow modifications to data blocks that you intended to be read-only. + +Do not assume the thread context is that of the initiating user-mode application — a higher-level driver might have changed it. + +If the driver cannot locate the specified instance, it must fail the IRP and return STATUS\_WMI\_INSTANCE\_NOT\_FOUND. If the instance has a dynamic instance name, this status indicates that the driver does not support the instance. WMI can therefore continue to query other data providers, and return an appropriate error to the data consumer if another provider finds the instance but cannot handle the request for some other reason. + +If the driver locates the instance and can handle the request, it sets the writable data items in the instance to the values in the [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure, leaving any read-only items unchanged. If the entire data block is read-only, the driver should fail the IRP and return STATUS\_WMI\_READ\_ONLY. + +If the instance is valid but the driver cannot handle the request, it can return any appropriate error status. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiSetDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544104) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_CHANGE_SINGLE_INSTANCE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-change-single-item.md b/windows-driver-docs-pr/kernel/irp-mn-change-single-item.md new file mode 100644 index 0000000000..e466f61a47 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-change-single-item.md @@ -0,0 +1,142 @@ +--- +title: IRP\_MN\_CHANGE\_SINGLE\_ITEM +author: windows-driver-content +description: All drivers that support WMI must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 9839ebb2-31a9-4cb0-adbf-1882583849fc +keywords: + - IRP_MN_CHANGE_SINGLE_ITEM Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_CHANGE\_SINGLE\_ITEM + + +All drivers that support WMI must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_CHANGE\_SINGLE\_ITEM** request, WMI in turn calls that driver's [*DpWmiSetDataItem*](https://msdn.microsoft.com/library/windows/hardware/ff544108) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to change a single data item in a single instance of a data block. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block to be set. + +**Parameters.WMI.BufferSize** indicates the size of the nonpaged buffer at **Parameters.WMI.Buffer**. + +**Parameters.WMI.Buffer**, points to a [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) structure that identifies the instance of the data block, the ID of the item to set, and a new data value. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_INSTANCE\_NOT\_FOUND + +STATUS\_WMI\_ITEMID\_NOT\_FOUND + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_WMI\_READ\_ONLY + +STATUS\_WMI\_SET\_FAILURE + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiSetDataItem*](https://msdn.microsoft.com/library/windows/hardware/ff544108) routine, or returns STATUS\_WMI\_READ\_ONLY if the driver does not define the routine. + +If a driver handles **IRP\_MN\_CHANGE\_SINGLE\_ITEM** requests itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Do not implement support for **IRP\_MN\_CHANGE\_SINGLE\_ITEM** unless you are sure that a system-supplied user-mode component requires this capability. + +Before handling a request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID that the driver supports. If it does not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the data block, it must check the input [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) structure that **Parameters.WMI.Buffer** points to for the instance name, as follows: + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is set in **WnodeHeader.Flags**, the driver uses **InstanceIndex** as an index into the driver's list of static instance names for that block. WMI obtains the index from registration data provided by the driver when it registered the block. + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is clear in **WnodeHeader.Flags,** the driver uses the offset at **OffsetInstanceName** to locate the instance name string in the input [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) structure. **OffsetInstanceName** is the offset in bytes from the beginning of the structure to a USHORT-sized length of the instance name string in bytes (not characters). This length includes the NULL terminator if present, followed by the instance name string in Unicode. + +The driver is responsible for validating all input values. Specifically, the driver must do the following if it handles the IRP request itself: + +- For static names, verify that the **InstanceIndex** member of the WNODE\_SINGLE\_ITEM structure is within the range of instance indexes supported by the driver for the data block. + +- For dynamic names, verify that the instance name string identifies a data block instance supported by the driver. + +- Verify that the **ItemId** member of the [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) structure is within the range of item identifiers supported by the driver for the data block. + +- Verify that the **DataBlockOffset** and **SizeDataItem** members of the **WNODE\_SINGLE\_ITEM** structure describe a valid-sized data block, and that the contents of the buffer are valid for the data item. + +- Verify that the specified data item is one for which the driver allows caller-initiated modifications. In other words, the driver should not allow modifications to data items that you intended to be read-only. + +Do not assume the thread context is that of the initiating user-mode application—a higher-level driver might have changed it. + +If the driver cannot locate the specified instance, it must fail the IRP and return STATUS\_WMI\_INSTANCE\_NOT\_FOUND. For an instance with a dynamic instance name, this status indicates that the driver does not support the instance. WMI can therefore continue to query other data providers, and return an appropriate error to the data consumer if another provider finds the instance but cannot handle the request for some other reason. + +If the driver locates the instance and can handle the request, it sets the data item in the instance to the value in the [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378). If the data item is read-only, the driver leaves the item unchanged, fails the IRP, and returns STATUS\_WMI\_READ\_ONLY. + +If the instance is valid but the driver cannot handle the request, it can return any appropriate error status. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiSetDataItem*](https://msdn.microsoft.com/library/windows/hardware/ff544108) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_CHANGE_SINGLE_ITEM%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-device-enumerated.md b/windows-driver-docs-pr/kernel/irp-mn-device-enumerated.md new file mode 100644 index 0000000000..838540119d --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-device-enumerated.md @@ -0,0 +1,87 @@ +--- +title: IRP\_MN\_DEVICE\_ENUMERATED +author: windows-driver-content +description: The PnP manager uses this I/O request packet (IRP) to notify bus drivers that a device object exists and that it has been fully enumerated by the plug and play manager. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 50ECF6E1-4FC6-4EEA-BACF-EBAD0329DA2E +keywords: + - IRP_MN_DEVICE_ENUMERATED Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_DEVICE\_ENUMERATED + + +The PnP manager uses this I/O request packet (IRP) to notify bus drivers that a device object exists and that it has been fully enumerated by the plug and play manager. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP just before user mode is notified with GUID\_DEVICE\_ENUMERATED. This IRP allows drivers to provide a preprocess routine for IRP\_MN\_DEVICE\_ENUMERATED, such as filling in additional device properties. This IRP primarily allows drivers to set device properties for the physical device object (PDO) by using [**IoSetDevicePropertyData**](https://msdn.microsoft.com/library/windows/hardware/ff549704). + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver that handles this IRP sets [Irp->IoStatus.Status](https://msdn.microsoft.com/library/windows/hardware/ff551825) to STATUS\_SUCCESS or an appropriate error status. + +Operation +--------- + +The **IRP\_MN\_DEVICE\_ENUMERATED** IRP is sent to the bus driver's PDO to indicate that the bus driver PDO exists. + +## Sending the IRP + + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Wdm.h
+ +## See also + + +[Plug and Play Minor IRPs](plug-and-play-minor-irps.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_DEVICE_ENUMERATED%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-device-usage-notification.md b/windows-driver-docs-pr/kernel/irp-mn-device-usage-notification.md new file mode 100644 index 0000000000..700e1a4c5f --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-device-usage-notification.md @@ -0,0 +1,200 @@ +--- +title: IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION +author: windows-driver-content +description: System components send this IRP to ask the drivers for a device whether the device can support a special file. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: d8287ba2-ac0a-4407-b587-a5aa5b3617a2 +keywords: + - IRP_MN_DEVICE_USAGE_NOTIFICATION Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION + + +System components send this IRP to ask the drivers for a device whether the device can support a *special file*. Special files include paging files, dump files, and hibernation files. If all the drivers for the device succeed the IRP, the system creates the special file. The system also sends this IRP to inform drivers that a special file has been removed from the device. + +Function drivers must handle this IRP if their device can contain a paging file, dump file, or hibernation file. Filter drivers must handle this IRP if the function driver they are filtering handles the IRP. Bus drivers must handle this IRP for their adapter or controller (bus FDO) and for their child devices (child PDOs). + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The system sends this IRP when it is creating or deleting a paging file, dump file, or hibernation file. If a device has a power management relationship that falls outside of the conventional parent-child relationship, the driver can send this IRP to propagate device usage information to another device stack. For more information, see the description of the **PowerRelations** request in [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](irp-mn-query-device-relations.md). + +System components and drivers send this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.UsageNotification.InPath** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure is a BOOLEAN. When this parameter is **TRUE**, the system is creating a paging, crash dump, or hibernation file on the device. When **InPath** is **FALSE**, such a file has been removed from the device. + +**Parameters.UsageNotification.Type** is an enum indicating the kind of file. This parameter has one of the following values: **DeviceUsageTypePaging**, **DeviceUsageTypeDumpFile**, or **DeviceUsageTypeHibernation**. + +## Output Parameters + + +None + +## I/O Status Block + + +Drivers set **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +Drivers do not modify the **Irp->IoStatus.Information** field; it remains at zero, as set by the component sending the IRP. + +Operation +--------- + +A driver handles this IRP on the IRP's way down the device stack and on the IRP's way back up the stack. + +A driver responds to this IRP with a procedure like the following: + +- If **Parameters.UsageNotification.InPath** is **TRUE**, determine whether the device supports the special file. + + A driver should test for the specific **Parameters.UsageNotification.Type**(s) that the driver can support. Additional notification types might be added in the future. + + See further information below describing the actions required to support each notification type. + + If **Parameters.UsageNotification.InPath** is **TRUE** and the driver cannot support the special file on the device, the driver must complete the IRP with a failure status. + +- If the device supports the special file: + + 1. Take appropriate actions to reflect that the device now contains, or no longer contains, a special file. + + A driver typically increments or decrements a counter. For example, if **Parameters.UsageNotification.Type** is **DeviceUsageTypePaging** and **Parameters.UsageNotification.InPath** is **TRUE**, increment a count of the number of paging files on the device. Certain driver dispatch routines must check the counter(s). + + A device that contains a special file should not be disabled. A driver can call [**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361), requesting the PnP manager to re-query for the device's PnP device state information. In response to the resulting [**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](irp-mn-query-pnp-device-state.md) IRP, the driver should set the PNP\_DEVICE\_NOT\_DISABLEABLE flag. + + If **InPath** is **FALSE**, a driver sets the DO\_POWER\_PAGABLE bit in its device object for the device. + + 2. Propagate the device usage information to any related devices that require the information. + + As part of its handling of an **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP, a driver might be required to pass the information to one or more other device stacks. Such a driver creates a new **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP (or IRPs) and sends them to the appropriate device stack (or stacks). The driver must wait for completion of any device-usage-notification IRP(s) that it sends before the driver finishes processing the device-usage IRP that it received. + + How to identify the related devices is device- and driver-specific. Typically, a driver sends the IRP to other drivers to which it would send I/O requests for the file. When a bus driver handles this request for a child device, it must send a usage notification IRP to the device stack for the device's parent. + + For example, when ftdisk is running a five-disk stripe set, it propagates paging notifications to each of these five disks, since each of these devices can be required to handle paging file operations. + + 3. In a function or filter driver, set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + + 4. In a function or filter driver, set **Irp->IoStatus.Status** to STATUS\_SUCCESS, set up the next stack location, and pass the IRP to the next lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). Do not complete the IRP. + + In a bus driver that is handling the IRP for a child PDO: set **Irp->IoStatus.Status** and complete the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)). + + 5. During IRP completion processing: + + If an *IoCompletion* routine detects that a lower driver has failed the IRP, the function or filter driver must undo any operations it performed in response to the IRP and propagate the error. If the function or filter driver propagated the usage information to any other device stacks, the driver must send another usage IRP to those stacks to notify them of the failure. + + If status is STATUS\_SUCCESS and **InPath** is **TRUE**, clear the DO\_POWER\_PAGABLE bit. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Supporting Paging, Crash Dump, and Hibernation Files on a Device** + +When any of a driver's special file counts is nonzero, the driver must support the presence of the special file(s) on its device (or a descendant device). + +For a **DeviceUsageTypePaging** file created on its device, a driver must do the following: + +- Lock code in memory for its [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034), [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287), and [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routines. + +- Clear the DO\_POWER\_PAGABLE bit in its device object for the device (on the IRP's way up the device stack). + +- Fail **IRP\_MN\_QUERY\_STOP\_DEVICE** and **IRP\_MN\_QUERY\_REMOVE\_DEVICE** requests for the device. + +For a **DeviceUsageTypeDumpFile** file on its device, a driver must do the following: + +- Lock code in memory for its *DispatchRead*, *DispatchWrite*, *DispatchDeviceControl*, and *DispatchPower* routines. + +- Do not take the device out of the D0 state. + + Do not register the device for idle detection ([**PoRegisterDeviceForIdleDetection**](https://msdn.microsoft.com/library/windows/hardware/ff559721)). If the device is already registered, cancel the registration. If the driver performs its own idle detection for the device, suspend such detection. + +- Clear the DO\_POWER\_PAGABLE bit in its device object for the device (on the IRP's way up the device stack). + +- Fail [**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) and [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) requests for the device. + +For a **DeviceUsageTypeHibernation** file on its device, a driver must do the following: + +- Lock code in memory for its *DispatchRead*, *DispatchWrite*, *DispatchDeviceControl*, and *DispatchPower* routines. + +- Ensure the device is in the D0 state when the driver receives an S4 system power IRP indicating that the system is about to hibernate. + +- Do not power down the device in response to a D3 set-power IRP that is part of an S4 hibernate action. See [System Power Actions](https://msdn.microsoft.com/library/windows/hardware/ff564553) for more information. + + Upon receipt of such a D3 set-power IRP, perform all tasks required to put the device in the D3 state except for powering off the device and notifying the power manager ([**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765)). The device must retain power until the hibernation file has been written. + +- Clear the DO\_POWER\_PAGABLE bit in its device object for the device (on the IRP's way up the device stack). + +- Fail [**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) and [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) requests for the device. + +See [Power Management](https://msdn.microsoft.com/library/windows/hardware/ff547131) for more information about device power states, power IRPs, and supporting power management in drivers. + +**Sending This IRP** + +A driver can send an **IRP\_MN\_DEVICE\_USAGE\_INFORMATION** IRP, but only to propagate device usage information to another device stack. A driver is never the initial source of device usage information. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) + +[*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) + +[*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) + +[*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) + +[**IoAdjustPagingPathCount**](https://msdn.microsoft.com/library/windows/hardware/ff548209) + +[**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) + +[**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) + +[**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) + +[**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](irp-mn-query-device-relations.md) + +[**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](irp-mn-query-pnp-device-state.md) + +[**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) + +[**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) + +[**PoRegisterDeviceForIdleDetection**](https://msdn.microsoft.com/library/windows/hardware/ff559721) + +[**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_DEVICE_USAGE_NOTIFICATION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-disable-collection.md b/windows-driver-docs-pr/kernel/irp-mn-disable-collection.md new file mode 100644 index 0000000000..fbe6c93d4f --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-disable-collection.md @@ -0,0 +1,112 @@ +--- +title: IRP\_MN\_DISABLE\_COLLECTION +author: windows-driver-content +description: Any WMI driver that registers one or more of its data blocks as expensive to collect must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: de375d56-880e-4534-acab-8d0685f45ebe +keywords: + - IRP_MN_DISABLE_COLLECTION Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_DISABLE\_COLLECTION + + +Any WMI driver that registers one or more of its data blocks as expensive to collect must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_DISABLE\_COLLECTION** request, WMI in turn calls that driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to request the driver to stop accumulating data for a data block that the driver registered as expensive to collect and for which data collection has been enabled. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block for which data accumulation should be stopped. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_INVALID\_DEVICE\_REQUEST + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +A driver registers a data block as expensive to collect by setting WMIREG\_FLAG\_EXPENSIVE in the **Flags** member of the [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) or [**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) structure that the driver passes to WMI when it registers or updates the data block. A driver need not accumulate data for such a block until it receives an explicit request to enable collection. + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine, or returns STATUS\_SUCCESS if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_DISABLE\_COLLECTION** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling the request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID that the driver supports. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. If the data block is valid but was not registered with WMIREG\_FLAG\_EXPENSIVE, the driver can return STATUS\_SUCCESS and take no further action. + +It is unnecessary for the driver to check whether data collection is already disabled because WMI sends a single disable request for the data block when the last data consumer disables collection for that block. WMI will not send another disable request without an intervening request to enable. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**IRP\_MN\_ENABLE\_COLLECTION**](irp-mn-enable-collection.md) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) + +[**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_DISABLE_COLLECTION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-disable-events.md b/windows-driver-docs-pr/kernel/irp-mn-disable-events.md new file mode 100644 index 0000000000..c845e1167a --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-disable-events.md @@ -0,0 +1,112 @@ +--- +title: IRP\_MN\_DISABLE\_EVENTS +author: windows-driver-content +description: Any WMI driver that registers one or more event blocks must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 3187643b-27d7-4a6d-8fbe-4f8eb6c251ed +keywords: + - IRP_MN_DISABLE_EVENTS Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_DISABLE\_EVENTS + + +Any WMI driver that registers one or more event blocks must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_DISABLE\_EVENTS** request, WMI in turn calls that driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to inform the driver that a data consumer has requested no further notification of an event. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the event block to disable. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_INVALID\_DEVICE\_REQUEST + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine, or returns STATUS\_SUCCESS if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_DISABLE\_EVENTS** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling a request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID the driver supports. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the event block, it disables the event for all instances of that block. + +It is unnecessary for the driver to check whether events are already disabled for the event block because WMI sends a single disable request for that event block when the last data consumer disables the event. WMI will not send another disable request without an intervening request to enable. + +For details about defining event blocks, see [Designing WMI Data and Event Blocks](https://msdn.microsoft.com/library/windows/hardware/ff543036). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**IRP\_MN\_ENABLE\_EVENTS**](irp-mn-enable-events.md) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_DISABLE_EVENTS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-eject.md b/windows-driver-docs-pr/kernel/irp-mn-eject.md new file mode 100644 index 0000000000..57b3330dc0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-eject.md @@ -0,0 +1,94 @@ +--- +title: IRP\_MN\_EJECT +author: windows-driver-content +description: Bus drivers typically handle this request for their child devices (child PDOs) that support device ejection. Function and filter drivers do not receive this request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 2807eeca-c614-469a-baeb-3d2d65416c57 +keywords: + - IRP_MN_EJECT Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_EJECT + + +Bus drivers typically handle this request for their child devices (child PDOs) that support device ejection. Function and filter drivers do not receive this request. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to direct the appropriate driver or drivers to eject the device from its slot. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a bus driver sets **Irp->IoStatus.Information** to zero. + +If a bus driver does not handle this IRP, it leaves **Irp->IoStatus.Status** as is and completes the IRP. + +Operation +--------- + +For the device to be ejected, the device must be in the D3 device power state (off) and must be unlocked (if the device supports locking). + +Any driver that returns success for this IRP must wait until the device has been ejected before completing the IRP. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Instead, see the reference page for the [**IoRequestDeviceEject**](https://msdn.microsoft.com/library/windows/hardware/ff549647) routine. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IoRequestDeviceEject**](https://msdn.microsoft.com/library/windows/hardware/ff549647) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_EJECT%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-enable-collection.md b/windows-driver-docs-pr/kernel/irp-mn-enable-collection.md new file mode 100644 index 0000000000..98a54a12a6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-enable-collection.md @@ -0,0 +1,114 @@ +--- +title: IRP\_MN\_ENABLE\_COLLECTION +author: windows-driver-content +description: Any WMI driver that registers one or more of its data blocks as potentially time-consuming, or expensive, to collect must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: dc6c3ceb-a992-4e7b-ab25-d91c00af655a +keywords: + - IRP_MN_ENABLE_COLLECTION Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_ENABLE\_COLLECTION + + +Any WMI driver that registers one or more of its data blocks as potentially time-consuming, or *expensive*, to collect must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_ENABLE\_COLLECTION** request, WMI in turn calls that driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to request the driver to start accumulating data for a data block that the driver registered as expensive to collect. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block for which data is accumulated. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_INVALID\_DEVICE\_REQUEST + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +A driver registers a data block as expensive to collect by setting WMIREG\_FLAG\_EXPENSIVE in the **Flags** member of the [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) or [**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) structure. The driver passes these structures to WMI when it registers or updates the data block. A driver need not accumulate data for such a block until it receives an explicit request to start data collection. + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine, or returns STATUS\_SUCCESS if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_ENABLE\_COLLECTION** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling a request, the driver should make sure that **Parameters.WMI.DataPath** points to a GUID that the driver supports. If it does not, the driver should fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. If the data block is valid but was not registered with WMIREG\_FLAG\_EXPENSIVE, the driver can return STATUS\_SUCCESS and take no further action. + +If the block is valid and was registered with WMIREG\_FLAG\_EXPENSIVE, the driver enables data collection for all instances of that data block. + +It is unnecessary for the driver to check whether data collection is already enabled for the data block. WMI sends only a single request to enable a data block after the first data consumer enables the block. WMI will not send another request to enable without an intervening disable request. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**IRP\_MN\_DISABLE\_COLLECTION**](irp-mn-disable-collection.md) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_ENABLE_COLLECTION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-enable-events.md b/windows-driver-docs-pr/kernel/irp-mn-enable-events.md new file mode 100644 index 0000000000..56b245bef3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-enable-events.md @@ -0,0 +1,122 @@ +--- +title: IRP\_MN\_ENABLE\_EVENTS +author: windows-driver-content +description: Any WMI driver that registers one or more event blocks must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 35b95ba0-efd0-420a-abe0-664fc6311d02 +keywords: + - IRP_MN_ENABLE_EVENTS Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_ENABLE\_EVENTS + + +Any WMI driver that registers one or more event blocks must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_ENABLE\_EVENTS** request, WMI in turn calls that driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to inform the driver that a data consumer has requested notification of an event. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the event block to enable. + +**Parameters.WMI.BufferSize** indicates the size of the nonpaged buffer at **Parameters.WMI.Buffer**, which must be greater than or equal to the **sizeof**(**WNODE\_HEADER**). A driver that does not register trace blocks (WMIREG\_FLAG\_TRACED\_GUID) can ignore this parameter. + +**Parameters.WMI.Buffer** points to a **WNODE\_HEADER** that indicates whether the event should be traced (WMI\_FLAGS\_TRACED\_GUID) and provides a handle to the system logger. A driver that does not register trace blocks (WMIREG\_FLAG\_TRACED\_GUID) can ignore this parameter. + +## Output Parameters + + +None. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_INVALID\_DEVICE\_REQUEST + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) routine, or returns STATUS\_SUCCESS if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_ENABLE\_EVENTS** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before the driver handles the request, it should determine whether **Parameters.WMI.DataPath** points to a GUID that the driver supports. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the event block, it enables the event for all instances of that data block. + +It is unnecessary for the driver to check whether events are already enabled for the event block because WMI sends a single request to enable for the event block when the first data consumer enables the event. WMI will not send another request to enable without an intervening disable request. + +A driver that registers trace blocks (WMIREG\_FLAG\_TRACED\_GUID) must also determine whether to send the event to WMI or to the system logger for tracing. If tracing is requested, **Parameters.WMI.Buffer** points to a [**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) structure in which **Flags** is set with WNODE\_FLAG\_TRACED\_GUID and **HistoricalContext** contains a handle to the logger. + +For details about defining event blocks, sending events, and tracing, see [Windows Management Instrumentation](https://msdn.microsoft.com/library/windows/hardware/ff547139). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiFunctionControl*](https://msdn.microsoft.com/library/windows/hardware/ff544094) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**IRP\_MN\_DISABLE\_EVENTS**](irp-mn-disable-events.md) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_EVENT\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566373) + +[**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_ENABLE_EVENTS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-execute-method.md b/windows-driver-docs-pr/kernel/irp-mn-execute-method.md new file mode 100644 index 0000000000..5b670fafb6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-execute-method.md @@ -0,0 +1,158 @@ +--- +title: IRP\_MN\_EXECUTE\_METHOD +author: windows-driver-content +description: All drivers that support methods within data blocks must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: cc42340e-4a7c-475c-b44d-2127e8a0d7dc +keywords: + - IRP_MN_EXECUTE_METHOD Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_EXECUTE\_METHOD + + +All drivers that support methods within data blocks must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_EXECUTE\_METHOD** request, WMI in turn calls that driver's [*DpWmiExecuteMethod*](https://msdn.microsoft.com/library/windows/hardware/ff544090) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to execute a method associated with a data block. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +WMI will send an [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](irp-mn-query-single-instance.md) prior to sending an **IRP\_MN\_EXECUTE\_METHOD**. If a driver supports **IRP\_MN\_EXECUTE\_METHOD** it must have a **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** handler for the same data block whose method is being executed. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block associated with the method to execute. + +**Parameters.WMI.BufferSize** indicates the size of the nonpaged buffer at **Parameters.WMI.Buffer** which must be >= **sizeof**(**WNODE\_METHOD\_ITEM**) plus the size of any output data for the method. + +**Parameters.WMI.Buffer** points to a [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) structure in which **MethodID** indicates the identifier of the method to execute and **DataBlockOffset** indicates the offset in bytes from the beginning of the structure to the first byte of input data, if any. **Parameters.WMI.Buffer->SizeDataBlock** indicates the size in bytes of the input **WNODE\_METHOD\_ITEM** including input data, or zero if there is no input. + +## Output Parameters + + +If the driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI fills in the [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) with data returned by the driver's [*DpWmiExecuteMethod*](https://msdn.microsoft.com/library/windows/hardware/ff544090) routine. + +Otherwise, the driver fills in the **WNODE\_METHOD\_ITEM** structure that **Parameters.WMI.Buffer** points to as follows: + +- Updates **WnodeHeader.BufferSize** with the size of the output **WNODE\_METHOD\_ITEM**, including any output data. + +- Updates **SizeDataBlock** with the size of the output data, or zero if there is no output data. + +- Checks **Parameters.WMI.Buffersize** to determine whether the buffer is large enough to receive the output **WNODE\_METHOD\_ITEM** including any output data. If the buffer is not large enough, the driver fills in the needed size in a [**WNODE\_TOO\_SMALL**](https://msdn.microsoft.com/library/windows/hardware/ff566379) structure pointed to by **Parameters.WMI.Buffer**. If the buffer is smaller than **sizeof**(**WNODE\_TOO\_SMALL**), the driver fails the IRP and returns STATUS\_BUFFER\_TOO\_SMALL. + +- Writes output data, if any, over input data starting at **DataBlockOffset**. The driver must not change the input value of **DataBlockOffset**. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_BUFFER\_TOO\_SMALL + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_WMI\_INSTANCE\_NOT\_FOUND + +STATUS\_WMI\_ITEMID\_NOT\_FOUND + +On success, a driver sets **Irp->IoStatus.Information** to the number of bytes written to the buffer at **Parameters.WMI.Buffer**. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiExecuteMethod*](https://msdn.microsoft.com/library/windows/hardware/ff544090) routine, or returns STATUS\_INVALID\_DEVICE\_REQUEST if the driver does not define the routine. + +If a driver handles an **IRP\_MN\_EXECUTE\_METHOD** request itself, it must do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +The driver is responsible for validating all input values. Specifically, the driver must do the following if it handles the IRP request itself: + +- For static names, verify that the **InstanceIndex** member of the [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) structure is within the range of instance indexes supported by the driver for the data block. + +- For dynamic names, verify that the instance name string identifies a data block instance supported by the driver. + +- Verify that the **MethodId** member of the [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) structure is within the range of method identifiers supported by the driver for the data block, and that the caller is allowed to execute the method. + +- Verify that the **DataBlockOffset** and **SizeDataBlock** members of the [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) structure describe a buffer that is large enough to contain the specified method's parameters, and that the parameters are valid for the method. + +- Verify that **Parameters.WMI.Buffersize** specifies a buffer that is large enough to receive the **WNODE\_METHOD\_ITEM** structure after it has been updated with output data. + +Do not assume the thread context is that of the initiating user-mode application — a higher-level driver might have changed it. + +Before handling the request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID supported by the driver. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the data block, it checks the input [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) at **Parameters.WMI.Buffer** for the instance name, as follows: + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is set in **WnodeHeader.Flags**, the driver uses **InstanceIndex** as an index into the driver's list of static instance names for that block. WMI obtains the index from registration data that was provided by the driver when it registered the block. + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is clear in **WnodeHeader.Flags,** the driver uses the offset at **OffsetInstanceName** to locate the instance name string in the input **WNODE\_METHOD\_ITEM**. **OffsetInstanceName** is the offset in bytes from the beginning of the structure to a USHORT which is the length of the instance name string in bytes (not characters), including the terminating null if present, followed by the instance name string in Unicode. + +If the driver cannot locate the specified instance, it must fail the IRP and return STATUS\_WMI\_INSTANCE\_NOT\_FOUND. For an instance with a dynamic instance name, this status indicates that the driver does not support the instance. WMI can therefore continue to query other data providers, and return an appropriate error to the data consumer if another provider finds the instance but cannot handle the request for some other reason. + +The driver then checks the method ID in the input **WNODE\_METHOD\_ITEM** to determine whether it is a valid method for that data block. If not, the driver fails the IRP and returns STATUS\_WMI\_ITEMID\_NOT\_FOUND. + +If the method generates output, the driver should check the size of the output buffer in **Parameters.WMI.BufferSize** before performing any operation that might have side effects or that should not be performed twice. For example, if a method returns the values of a group of counters and then resets the counters, the driver should check the buffer size (and fail the IRP if the buffer is too small) before resetting the counters. This ensures that WMI can safely resend the request with a larger buffer. + +If the instance and method ID are valid and the buffer is adequate in size, the driver executes the method. If **SizeDataBlock** in the input **WNODE\_METHOD\_ITEM** is nonzero, the driver uses the data starting at **DataBlockOffset** as input for the method. + +If the method generates output, the driver writes the output data to the buffer starting at **DataBlockOffset** and sets **SizeDataBlock** in the output **WNODE\_METHOD\_ITEM** to the number of bytes of output data. If the method has no output data, the driver sets **SizeDataBlock** to zero. The driver must not change the input value of **DataBlockOffset**. + +If the instance is valid but the driver cannot handle the request, it can return any appropriate error status. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiExecuteMethod*](https://msdn.microsoft.com/library/windows/hardware/ff544090) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_EXECUTE_METHOD%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-filter-resource-requirements.md b/windows-driver-docs-pr/kernel/irp-mn-filter-resource-requirements.md new file mode 100644 index 0000000000..60ea20b45c --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-filter-resource-requirements.md @@ -0,0 +1,124 @@ +--- +title: IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS +author: windows-driver-content +description: The PnP manager sends this IRP to a device stack so the function driver can adjust the resources required by the device, if appropriate.The function driver typically handles this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: f43dc60e-de88-4af0-ad83-3ce3a414d880 +keywords: + - IRP_MN_FILTER_RESOURCE_REQUIREMENTS Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS + + +The PnP manager sends this IRP to a device stack so the function driver can adjust the resources required by the device, if appropriate. + +The function driver typically handles this IRP. + +The parent bus driver (and bus filter drivers) should not handle this request for a child PDO; instead, such a driver should report resource requirements in response to an [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) request. + +Upper and lower-filter drivers do not handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP when it is preparing to allocate resource(s) to a device. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of an arbitrary thread. + +## Input Parameters + + +**Irp->IoStatus.Information** points to an [**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) containing the hardware resource requirements for the device. The pointer is **NULL** if the device consumes no hardware resources. + +**Parameters.FilterResourceRequirements.IoResourceRequirementList** also points to an **IO\_RESOURCE\_REQUIREMENTS\_LIST**, but the function driver should use the list in the **IoStatus** block. + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +If a function driver handles this IRP, it handles it on the IRP's way back up the stack. If the function driver handles the IRP successfully, it sets **Irp->IoStatus.Status** to STATUS\_SUCCESS and sets **Irp->IoStatus.Information** to a pointer to an [**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) containing the filtered resource requirements. See the "Operation" section below for more information about setting the filtered resource list. If a function driver encounters an error when handling this IRP, it sets the error in **Irp->IoStatus.Status**. If a function driver does not handle this IRP, it uses [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) to pass the IRP down the stack unchanged. + +Upper and lower-filter drivers do not handle this IRP. Such a driver calls **IoSkipCurrentIrpStackLocation**, passes the IRP down to the next driver, must not modify **Irp->IoStatus**, and must not complete the IRP. + +The parent bus driver does not handle this IRP. It leaves **Irp->IoStatus** as is and completes the IRP. + +Operation +--------- + +The PnP manager sends an [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) request to the parent bus driver for the device, before the function driver has attached its device object to the device stack. To give the function driver an opportunity to modify the device's resource requirements, if appropriate, the PnP manager later sends an **IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS** request to the full device stack. The PnP manager sends this IRP before it allocates hardware resources to the device during initial device configuration. The PnP manager might also send this IRP during resource rebalancing. + +When the PnP manager sends this IRP, it supplies the driver stack with a resource requirements list, which drivers can modify and return. The PnP manager supplies one of the following types of resource requirements list (listed in order of priority): + +- Forced configuration (modified from a resource list to a resource requirements list) + +- Override configuration + +- Basic configuration + +- Boot configuration (modified from a resource list to a resource requirements list) + +If a function driver handles this IRP, it must set a completion routine and handle the IRP on its way back up the device stack. See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for information about handling a PnP IRP on its way back up the device stack. + +If the function driver is not changing the size of the current list pointed to by **Irp->IoStatus.Information**, the driver can modify the list in place. If the driver needs to change the size of the requirements list, the driver must allocate a new [**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) list from paged memory and free the previous list. The PnP manager frees the returned structure when it is no longer needed. + +A function driver must preserve the order of resources in the list pointed to by **Irp->IoStatus.Information** and must not alter resource tags that it does not handle. The driver must take care to adjust the requirements list in a way that the device's parent bus supports. If a function driver adds a new resource to the requirements list, and that resource is assigned to the device, the function driver should filter that resource out of the [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) before passing the start IRP down to the bus driver. + +If the function driver for the device does not handle this IRP, the PnP manager uses the resource requirements as specified by the parent bus driver in response to the [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) request. + +A function driver must be prepared to handle this IRP for a device at any time after the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine has been called for the device. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) + +[**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) + +[**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) + +[**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_FILTER_RESOURCE_REQUIREMENTS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-power-sequence.md b/windows-driver-docs-pr/kernel/irp-mn-power-sequence.md new file mode 100644 index 0000000000..7bfe391b48 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-power-sequence.md @@ -0,0 +1,96 @@ +--- +title: IRP\_MN\_POWER\_SEQUENCE +author: windows-driver-content +description: This IRP returns the power sequence values for a device. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: f00c0021-a909-4d76-9114-6710e1aa4307 +keywords: + - IRP_MN_POWER_SEQUENCE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_POWER\_SEQUENCE + + +This IRP returns the power sequence values for a device. + +Major Code +---------- + +[**IRP\_MJ\_POWER**](irp-mj-power.md) +When Sent +--------- + +A driver sends this IRP as an optimization to determine whether its device actually entered a specific power state. Support for this IRP is optional. + +To send this IRP, a driver must call [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) to allocate the IRP, specifying the major IRP code [**IRP\_MJ\_POWER**](irp-mj-power.md) and minor IRP code **IRP\_MN\_POWER\_SEQUENCE**. The driver must then call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP to the next lower driver. The power manager cannot send this IRP. + +Senders of this IRP must be running at IRQL <= DISPATCH\_LEVEL. + +## Input Parameters + + +None. + +## Output Parameters + + +**Parameters.PowerSequence** points to a **POWER\_SEQUENCE** structure with the following members: + +**SequenceD1** +Number of times the device has been in power state D1 or lower. + +**SequenceD2** +Number of times the device has been in power state D2 or lower. + +**SequenceD3** +Number of times the device has been in power state D3. + +The sequence values track the minimum number of times a device has been in the corresponding power state or a lower power state. + +The bus driver increments the values in **SequenceD1**, **SequenceD2**, and **SequenceD3** at least each time the device enters in the corresponding power state or a lower power state. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS to indicate that it has returned the requested information, or to STATUS\_NOT\_IMPLEMENTED to indicate that it does not support this IRP. + +Operation +--------- + +This IRP returns the power sequence values for a device. Bus drivers can optionally handle it; function and filter drivers can optionally send it. + +For a device that takes a long time to change state, this IRP provides a useful optimization. Every time the device changes its power state, its bus driver increments the sequence value for that power state. The bus driver initializes the sequence values at boot time and continually increments them thereafter; they need not be reset to zero. + +A device policy owner can send this IRP once to get the sequence values before shutting off the device and once again to get new values when restoring power to the device. By comparing the two sets of values, the driver can determine whether the device actually entered the lower-powered state. If the device did not lose power, the driver can avoid a time-consuming reinitialization when the device returns to the D0 state. + +For example, if the device takes a long time to restore power upon reaching the D2 state, the driver can store the **SequenceD2** value before it sets the device state to D2 or lower. Later, when power is being restored to the device, the driver can compare the new **SequenceD2** value with its stored value to determine whether the device state actually dropped below D2. If the values match, the device did not actually enter power state D2 or a lower state, and the driver can avoid reinitializing the device. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_POWER_SEQUENCE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-all-data.md b/windows-driver-docs-pr/kernel/irp-mn-query-all-data.md new file mode 100644 index 0000000000..1a423ca616 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-all-data.md @@ -0,0 +1,134 @@ +--- +title: IRP\_MN\_QUERY\_ALL\_DATA +author: windows-driver-content +description: All drivers that support WMI must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 9d4e1c2e-73ad-4fc3-99e6-391a64edfa5c +keywords: + - IRP_MN_QUERY_ALL_DATA Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_ALL\_DATA + + +All drivers that support WMI must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_QUERY\_ALL\_DATA** request, WMI in turn calls that driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to query for all instances of a given data block. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** in the driver's I/O stack location in the IRP points to the device object of the driver that should respond to the request. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block. + +**Parameters.WMI.BufferSize** indicates the maximum size of the nonpaged buffer at **Parameters.WMI.Buffer**, which receives output data from the request. The buffer size must be greater than or equal to **sizeof**(**WNODE\_ALL\_DATA**) plus the sizes of instance names and data for all instances to be returned. + +## Output Parameters + + +If the driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI fills in a **WNODE\_ALL\_DATA** by calling the driver's *DpWmiQueryDataBlock* routine once for each block registered by the driver. + +Otherwise, the driver fills in a [**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) structure at **Parameters.WMI.Buffer** as follows: + +- Sets **WnodeHeader.BufferSize** to the number of bytes of the entire **WNODE\_ALL\_DATA** to be returned, sets **WnodeHeader.Timestamp** to the value returned by **KeQuerySystemTime**, and sets **WnodeHeader.Flags** as appropriate for the data to be returned. + +- Sets **InstanceCount** to the number of instances to be returned. + +- If the block uses dynamic instance names, sets **OffsetInstanceNameOffsets** to the offset in bytes from the beginning of the **WNODE\_ALL\_DATA** to where an array of ULONG offsets begins. Each element in this array is the offset from the **WNODE\_ALL\_DATA** to where each dynamic instance name is stored. Each dynamic instance name is stored as a counted Unicode string where the count is a USHORT followed by the Unicode string. The count does not include any terminating null character that may be part of the Unicode string. If the Unicode string does include a terminating null character, this null character must still fit within the size established in **WNodeHeader.BufferSize**. + +- If all instances are the same size: + - Sets WNODE\_FLAG\_FIXED\_INSTANCE\_SIZE in **WnodeHeader.Flags** and sets **FixedInstanceSize** to that size, in bytes. + - Writes instance data starting at **DataBlockOffset**, with padding so that each instance is aligned to an 8-byte boundary. For example, if **FixedInstanceSize** is 6, the driver adds 2 bytes of padding between instances. +- If instances vary in size: + - Clears WNODE\_FLAG\_FIXED\_INSTANCE\_SIZE in **WnodeHeader.Flags** and writes an array of **InstanceCount** **OFFSETINSTANCEDATAANDLENGTH** structures starting at **OffsetInstanceDataAndLength**. Each **OFFSETINSTANCEDATAANDLENGTH** structure specifies the offset in bytes from the beginning of the **WNODE\_ALL\_DATA** structure to the beginning of the data for each instance, and the length of the data. **DataBlockOffset** is not used. + + - Writes instance data following the last element of the **OffsetInstanceDataAndLength** array, plus padding so that each instance is aligned to an 8-byte boundary. + +If the buffer at **Parameters.WMI.Buffer** is too small to receive all of the data, a driver fills in the needed size in a [**WNODE\_TOO\_SMALL**](https://msdn.microsoft.com/library/windows/hardware/ff566379) structure at **Parameters.WMI.Buffer**. If the buffer is smaller than **sizeof**(**WNODE\_TOO\_SMALL**), the driver fails the IRP and returns STATUS\_BUFFER\_TOO\_SMALL. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_BUFFER\_TOO\_SMALL + +STATUS\_WMI\_GUID\_NOT\_FOUND + +On success, a driver sets **Irp->IoStatus.Information** to the number of bytes written to the buffer at **Parameters.WMI.Buffer**. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine. + +If a driver handles an **IRP\_MN\_QUERY\_ALL\_DATA** request, it should do so only if **Parameters.WMI.ProviderId** points to the same device object that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling the request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID that the driver supports. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +If the driver supports the data block, it must do the following: + +- Verify that **Parameters.WMI.BufferSize** specifies a buffer that is large enough to receive all the data that the driver will return. + +- Fill in a [**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) structure at **Parameters.WMI.Buffer** with data for all instances of that data block. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**KeQuerySystemTime**](https://msdn.microsoft.com/library/windows/hardware/ff553068) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_ALL_DATA%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-bus-information.md b/windows-driver-docs-pr/kernel/irp-mn-query-bus-information.md new file mode 100644 index 0000000000..d11d00cf36 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-bus-information.md @@ -0,0 +1,119 @@ +--- +title: IRP\_MN\_QUERY\_BUS\_INFORMATION +author: windows-driver-content +description: The PnP manager uses this IRP to request the type and instance number of a device's parent bus.Bus drivers should handle this request for their child devices (PDOs). Function and filter drivers do not handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: a7ea1a81-7f03-41c7-8861-a2e1813c15cf +keywords: + - IRP_MN_QUERY_BUS_INFORMATION Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_BUS\_INFORMATION + + +The PnP manager uses this IRP to request the type and instance number of a device's parent bus. + +Bus drivers should handle this request for their child devices (PDOs). Function and filter drivers do not handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP when a device is enumerated. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +None + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a bus driver sets **Irp->IoStatus.Information** to a pointer to a completed [**PNP\_BUS\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff559608) structure. (See the "Operation" section for more information.) On an error, the bus driver sets **Irp->IoStatus.Information** to zero. + +Function and filter drivers do not handle this IRP. + +Operation +--------- + +The information returned in response to this IRP is available to the function and filter drivers for devices on the bus. Function and filter drivers can call [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) to request a **DevicePropertyBusTypeGuid**, **DevicePropertyLegacyBusType**, or **DevicePropertyBusNumber**. Function and filter drivers that support devices on more than one bus can use this information to determine on which bus a particular device resides. + +If a bus driver returns information in response to this IRP, it allocates a **PNP\_BUS\_INFORMATION** structure from paged memory. The PnP manager frees the structure when it is no longer needed. + +A **PNP\_BUS\_INFORMATION** structure has the following format: + +``` +typedef struct _PNP_BUS_INFORMATION { + GUID BusTypeGuid; + INTERFACE_TYPE LegacyBusType; + ULONG BusNumber; +} PNP_BUS_INFORMATION, *PPNP_BUS_INFORMATION; +``` + +The members of the structure are defined as follows: + +**BusTypeGuid** +A bus driver sets **BusTypeGuid** to the GUID for the type of the bus on which the device resides. GUIDs for standard bus types are listed in Wdmguid.h. Driver writers should generate GUIDs for other bus types using Uuidgen. + +**LegacyBusType** +A PnP bus driver sets **LegacyBusType** to the [**INTERFACE\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff547839) of the parent bus. The interface types are defined in Wdm.h. Some buses have a specific **INTERFACE\_TYPE** value, such as **PCMCIABus**, **PCIBus**, or **PNPISABus**. For other buses, especially newer buses like USB, the bus driver sets this member to **PNPBus**. + +The **LegacyBusType** specifies the interface used to communicate with the device. This may or may not correspond to the type of the parent bus. For example, the interface for a CardBus card that is plugged into a PCI CardBus controller is **PCIBus**. However, the interface for a PCMCIA card on a PCI CardBus controller is **PCMCIABus**. + +**BusNumber** +A bus driver sets **BusNumber** to a number distinguishing the bus from other buses of the same type on the computer. The bus-numbering scheme is bus-specific. Bus numbers may be virtual, but must match any numbering used by legacy interfaces such as [**IoReportResourceUsage**](https://msdn.microsoft.com/library/windows/hardware/ff549616). + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Call [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) to get information about the bus to which a device is attached. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_BUS_INFORMATION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-capabilities.md b/windows-driver-docs-pr/kernel/irp-mn-query-capabilities.md new file mode 100644 index 0000000000..7bca5545ea --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-capabilities.md @@ -0,0 +1,116 @@ +--- +title: IRP\_MN\_QUERY\_CAPABILITIES +author: windows-driver-content +description: The PnP manager sends this IRP to get the capabilities of a device, such as whether the device can be locked or ejected.Function and filter drivers can handle this request if they alter the capabilities supported by the bus driver. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 3c968a46-5bfb-4579-b09a-ad6bce4d9e3b +keywords: + - IRP_MN_QUERY_CAPABILITIES Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_CAPABILITIES + + +The PnP manager sends this IRP to get the capabilities of a device, such as whether the device can be locked or ejected. + +Function and filter drivers can handle this request if they alter the capabilities supported by the bus driver. Bus drivers must handle this request for their child devices. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to the bus driver for a device immediately after the device is enumerated. The PnP manager sends this IRP again after all the drivers for a device have started the device. A driver can send this IRP to get the capabilities for a device. + +The PnP manager and drivers send this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.DeviceCapabilities.Capabilities** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure points to a [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure containing information about the capabilities of the device. + +## Output Parameters + + +**Parameters.DeviceCapabilities.Capabilities** points to the **DEVICE\_CAPABILITIES** structure that reflects any modifications made by the drivers that handle the IRP. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_UNSUCCESSFUL. + +If a function or filter driver does not handle this IRP, it calls [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and passes the IRP down to the next driver. Such a driver must not modify **Irp->IoStatus.Status** and must not complete the IRP. + +A bus driver sets **Irp->IoStatus.Status** and completes the IRP. + +Operation +--------- + +When a device is enumerated, but before the function and filter drivers are loaded for the device, the PnP manager sends an **IRP\_MN\_QUERY\_CAPABILITIES** request to the parent bus driver for the device. The bus driver must set any relevant values in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure and return it to the PnP manager. + +After the device stack is built and drivers have started the device, the PnP manager sends this IRP again to be handled first by the driver at the top of the device stack and then by each lower driver in the stack. Function and filter drivers can set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine and handle this IRP on its way back up the device stack. + +Drivers should add capabilities before they pass the IRP to the next lower driver. + +Drivers should remove capabilities after all lower drivers have finished with the IRP. A driver does not typically remove capabilities that have been set by other drivers, but it might do so if it has special information about the capabilities of the device in a certain configuration. See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for information about postponing IRP processing until lower drivers have finished. + +After a device is enumerated and its drivers are loaded, its capabilities should not change. A device's capabilities might change if the device is removed and re-enumerated. + +When handling an **IRP\_MN\_QUERY\_CAPABILITIES** IRP, the driver that is the power policy manager for the device should set an *IoCompletion* routine and copy the device power capabilities, such as the S-to-D power state mappings, on the IRP's way back up the device stack. To determine the power capabilities of a child device, the parent bus driver creates another query-capabilities IRP and sends the IRP to its parent driver. See [Reporting Device Power Capabilities](https://msdn.microsoft.com/library/windows/hardware/ff561058) for more information. + +If a driver handles this IRP, it should check the **DEVICE\_CAPABILITIES** **Version** value. If that value is not a version that the driver supports, the driver should fail the IRP. If the version is supported, the driver should check the **Size** field. A driver should set only those fields that are within the bounds of the capabilities structure that it received as input. + +Drivers that handle this IRP can set some **DEVICE\_CAPABILITIES** fields but must not set the **Size** and **Version** fields. These fields are only set by the component that sent the IRP. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +A bus driver sends this IRP to the parent device stack when it handles an **IRP\_MN\_QUERY\_CAPABILITIES** request for one of its child devices. Also, a driver might send this IRP to get the device capabilities for one of its devices. A single driver in the stack has only part of the capabilities information for the device; sending an IRP to the device stack enables it to gather the full picture, including modifications by any filter drivers, and so forth. + +See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Allocate a [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure from paged pool, and initialize it to zeros by calling [**RtlZeroMemory**](https://msdn.microsoft.com/library/windows/hardware/ff563610). Initialize the **Size** to **sizeof**(**DEVICE\_CAPABILITIES**), the **Version** to 1, and **Address** and **UINumber** to -1. + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to **IRP\_MN\_QUERY\_CAPABILITIES**, and set **Parameters.DeviceCapabilities** to a pointer to the allocated **DEVICE\_CAPABILITIES** structure. + +- Initialize **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +- Deallocate the IRP and the **DEVICE\_CAPABILITIES** structure when they are no longer needed. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_CAPABILITIES%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-device-relations.md b/windows-driver-docs-pr/kernel/irp-mn-query-device-relations.md new file mode 100644 index 0000000000..927c4de716 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-device-relations.md @@ -0,0 +1,263 @@ +--- +title: IRP\_MN\_QUERY\_DEVICE\_RELATIONS +author: windows-driver-content +description: The PnP manager sends this request to determine certain relationships among devices. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 32437c5a-ad92-433c-8255-83775751a44d +keywords: + - IRP_MN_QUERY_DEVICE_RELATIONS Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_DEVICE\_RELATIONS + + +The PnP manager sends this request to determine certain relationships among devices. The following types of drivers handle this request: + +- Bus drivers must handle **BusRelations** requests for their adapter or controller (bus FDO). Filter drivers might handle **BusRelations** requests. + +- Bus drivers must handle **TargetDeviceRelation** requests for their child devices (child PDOs). + +- Function and filter drivers might handle **RemovalRelations** and **PowerRelations** requests. + +- Bus drivers might handle **EjectionRelations** requests for their child devices (child PDOs). + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to gather information about devices with a relationship to the specified device. + +The PnP manager queries a device's **BusRelations** (child devices) when the device is enumerated and at other times while the device is active, such as when a driver calls the [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) routine to indicate that a child device has arrived or departed. + +The PnP manager queries a device's **RemovalRelations** before it removes a device's drivers. The PnP manager queries for **RemovalRelations** and **EjectionRelations** before it ejects a device. + +The PnP manager queries a device's **TargetDeviceRelation** when a driver or user-mode application registers for PnP notification of an **EventCategoryTargetDeviceChange** on the device. The PnP manager queries for the device that is associated with a particular file object. **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** is the only PnP IRP that has a valid file object parameter. A driver can query a device stack for **TargetDeviceRelation**. A driver does not need to supply a file object when sending its **TargetDeviceRelation** query. + +The PnP manager queries a device's **PowerRelations** when the driver for the device calls **IoInvalidateDeviceRelations** to indicate that the set of devices with which this device has an implicit power management relationship has changed. **PowerRelations** requests are supported starting with Windows 7. + +For **BusRelations**, **RemovalRelations**, **EjectionRelations**, and **PowerRelations** requests, the PnP manager sends **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** at IRQL = PASSIVE\_LEVEL in the context of a system thread. + +For **TargetDeviceRelation** requests, the PnP manager sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.QueryDeviceRelations.Type** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure specifies the type of relations that are being queried. Possible values include **BusRelations**, **EjectionRelations**, **RemovalRelations**, **TargetDeviceRelation**, and **PowerRelations**. + +The **FileObject** member of the current **IO\_STACK\_LOCATION** structure points to a valid file object only if **Parameters.QueryDeviceRelations.Type** is **TargetDeviceRelation**. + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to a failure status such as STATUS\_INSUFFICIENT\_RESOURCES. + +On success, a driver sets **Irp->IoStatus.Information** to a PDEVICE\_RELATIONS pointer that points to the requested relations information. The **DEVICE\_RELATIONS** structure is defined as follows: + +``` +typedef struct _DEVICE_RELATIONS { + ULONG Count; + PDEVICE_OBJECT Objects[1]; // variable length +} DEVICE_RELATIONS, *PDEVICE_RELATIONS; +``` + +Operation +--------- + +If a driver returns relations in response to this **IRP\_MN\_QUERY\_DEVICE\_RELATIONS**, the driver allocates a **DEVICE\_RELATIONS** structure from paged memory that contains a count and the appropriate number of device object pointers. The PnP manager frees the structure when it is no longer needed. If a driver replaces a **DEVICE\_RELATIONS** structure that another driver allocated, the driver must free the previous structure. + +A driver must reference the PDO of any device that it reports in this IRP ([**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678)). The PnP manager removes the reference when appropriate. + +A function or filter driver should be prepared to handle this IRP for a device any time after its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine has completed for the device. Bus drivers should be prepared to handle a query for **BusRelations** immediately after a device is enumerated. + +For the general rules about handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md) see [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125). + +The following subsections describe the specific actions for handling the various queries. + +**BusRelations Request** + +When the PnP manager queries for the bus relations (child devices) of an adapter or controller, the bus driver must return a list of pointers to the PDOs of any devices physically present on the bus. The bus driver reports all devices, regardless of whether they have been started. The bus driver might need to power up its bus device to determine which children are present. + +**Warning**   A device object cannot be passed to any routine that takes a PDO as an argument until the PnP manager creates a device node ([*devnode*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-devnode)) for that object. (If the driver does pass a device object, the system will bug check with [**Bug Check 0xCA: PNP\_DETECTED\_FATAL\_ERROR**](https://msdn.microsoft.com/library/windows/hardware/ff560209).) The PnP manager creates the devnode in response to the **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** request. The driver can safely assume that the PDO's devnode has been created when it receives an [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) request. + +  + +The bus driver that responds to this IRP is the function driver for the bus adapter or controller, not the parent bus driver for the bus that the adapter or controller is connected to. Function drivers for non-bus devices do not handle this query. Such drivers just pass the IRP to the next lower driver. (See the following figure.) Filter drivers typically do not handle this query. + +On Windows Vista and later operating systems, we recommend that drivers always pend the **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** IRP and complete its processing later. This order enables the system to process bus relation queries asynchronously. (On operating systems before Windows Vista, drivers can safely return STATUS\_PENDING from their dispatch routines, but the PnP manager does not overlap the bus relation query with any other operation.) + +The following diagram shows how drivers handle a query for bus relations. + +![diagram illustrating drivers handling a query for bus relations](images/qdrstaks.png) + +In the example shown in the figure, the PnP manager sends an **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** for **BusRelations** to the drivers for the USB hub device. The PnP manager is requesting a list of the hub device's children. + +1. As with all PnP IRPs, the PnP manager sends the IRP to the top driver in the device stack for the device. + +2. An optional filter driver might be the top driver in the stack. A filter driver typically does not handle this IRP; it passes the IRP down the stack. A filter driver might handle this IRP, for example, if the driver exposes a non-enumerable device on the bus. + +3. The USB hub bus driver handles the IRP. + + The USB hub bus driver: + + - Creates a PDO for any child device that does not already have one. + + - Marks the PDO inactive for any device that is no longer present on the bus. The bus driver does not delete such PDOs.For more information about when to delete the PDOs, see [Removing a Device](https://msdn.microsoft.com/library/windows/hardware/ff561046). + + - Reports any child devices that are present on the bus. + + For each child device, the bus driver references the PDO and puts a pointer to the PDO in the DEVICE\_RELATIONS structure. + + There are two PDOs in this example: one for the joystick device and one for the keyboard device. + + The bus driver should check whether another driver already created a DEVICE\_RELATIONS structure for this IRP. If so, the bus driver must add to the existing information. + + If there is no child device present on the bus, the driver sets the count to zero in the DEVICE\_RELATIONS structure and returns success. + + - Sets the appropriate values in the I/O status block and passes the IRP to the next lower driver. The bus driver for the adapter or controller does not complete the IRP. + +4. An optional lower filter, if present, typically does not handle this IRP. Such a filter driver passes the IRP down the stack. If a lower-filter driver handles this IRP, it can add PDO(s) to the list of child devices but it must not delete any PDOs created by other drivers. + +5. The parent bus driver does not handle this IRP, unless it is the only driver in the device stack (the device is in raw mode). As with all PnP IRPs, the parent bus driver completes the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + If there are one or more bus filter drivers in the device stack, such drivers might handle the IRP on its way down to the bus driver and/or on the IRP's way back up the device stack (if there are [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines). According to the PnP IRP rules, such a driver can add PDOs to the IRP on its way down the stack and/or modify the relations list on the IRP's way back up the stack (in *IoCompletion* routines). + +**EjectionRelations Request** + +A driver returns pointers to PDOs of any devices that might be physically removed from the system when the specified device is ejected. Do not report the PDOs of children of the device; the PnP manager always requests that child devices be removed before their parent device. + +The PnP manager sends an [**IRP\_MN\_EJECT**](irp-mn-eject.md) IRP to a device that is being ejected. The driver for such a device also receive a remove IRP. The device's ejection relations receive an [**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) IRP (not an **IRP\_MN\_EJECT** IRP). + +Only a parent bus driver can respond to an **EjectionRelations** query for one of its child devices. Function and filter drivers must pass it to the next lower driver in the device stack. If a bus driver receives this IRP as the function driver for its adapter or controller, the bus driver is performing the tasks of a function driver and must pass the IRP to the next lower driver. + +**PowerRelations Request** + +Starting with Windows 7, the **PowerRelations** query enables a driver to specify a power management relationship outside of the conventional relationship between a parent bus that supports PnP enumeration and an enumerated child device on the bus. For example, if a bus driver cannot enumerate a child device on the bus, or if a device is a child of more than one bus, the **PowerRelations** query can describe the child device's power relations with the bus or buses. + +The PnP manager issues a **PowerRelations** query for a device when the driver for the device calls the [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) routine and specifies a *Type* parameter value of **PowerRelations**. + +In response to this query, the driver for the target device (that is, the device that is the target for the query) supplies a **DEVICE\_RELATIONS** structure that contains pointers to the PDOs of any other devices that must be turned on by the power manager before the target device is turned on. Conversely, these other devices must be turned off only after the target device is turned off. The power manager uses the information from the query to guarantee that these devices are turned on and off in the correct order. + +This ordering guarantee applies only to global system sleep state transitions, which include transitions to and from the S1, S2, S3 (*sleep*), S4 (*hibernate*), and S5 (*shutdown*) system power states. The **PowerRelations** ordering guarantee does not apply if the target device or any other device whose PDO is supplied for the **PowerRelations** query performs transitions to and from low-power Dx device power states while the system stays in the S0 (*running*) system state. + +If the target device is on the device path for a special file (such as the paging file, hibernate file, or crash dump file), the driver for the target device must perform an additional step when it handles an [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](irp-mn-device-usage-notification.md) IRP in which **InPath** is **TRUE**. This driver must ensure that the devices whose PDOs are supplied for the **PowerRelations** query can also support being in the device path for the special file. To confirm this support, the driver for the target device must first send the **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP to each of these devices, and this IRP must specify the same **UsageNotification.Type** as the target device. Only if all the devices that receive this IRP complete the IRP with a success status code can the driver for the target device complete its **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP successfully. Otherwise, this driver must complete this IRP with a failure status code. + +When this same driver handles an **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP for which **InPath** is **FALSE**, the driver must send the **IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION** IRP to the same set of dependent devices as for the case in which **InPath** is **TRUE**. However, the driver should never complete this IRP with a failure status code when **InPath** is **FALSE**. + +The driver that responds to the **PowerRelations** query should register for target device change notifications on all devices whose PDOs are supplied for the **PowerRelations** query. To register for these notifications, the driver can call the [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) routine and specify an *EventCategory* parameter value of **EventCategoryTargetDeviceChange**. + +**RemovalRelations Request** + +A driver returns pointers to PDOs of any devices whose drivers must be removed when the drivers for the specified device are removed. Do not report the PDOs of children of the device; the PnP manager already requests the removal of child devices before removing a device. + +The order in which removal relations are removed is undefined. + +Any driver in the device stack can handle this type of relations query. A function or filter driver handles the IRP before passing it to the next lower driver. A bus driver handles the IRP and then completes it. + +**TargetDeviceRelation Request** + +The **TargetDeviceRelation** query enables the PnP manager to query a non-PnP device stack for the PDO in the PnP device stack that controls the hardware. + +In general, drivers forward the **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** IRP down their stack until the IRP reaches the bottom of a particular device stack. A driver at the bottom of a non-PnP stack then forwards or re-issues the IRP to the relevant PnP stack. For example, the PnP manager might send a **TargetDeviceRelation** query to the device object at the top of the file system stack, which is a non-PnP stack. Each device object in the file system stack would pass the query to the device object below it until the query reached the device object at the bottom of the stack. The lowest device object in the stack would forward or re-issue the **TargetDeviceRelation** query to the device object at the top of the PnP storage volume stack, and then the query would be passed down to the PDO at the bottom of the storage volume stack. + +The following list summarizes the situations in which you can safely acquire a pointer to the PDO at the bottom of a PnP device stack: + +- Device object in a PnP + + A device object that is in a PnP device stack learns about the stack's PDO when the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine for the device is called. The driver can safely cache the pointer to the PDO if the use of the pointer is properly synchronized with incoming [**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) messages by using the [remove lock routines](https://msdn.microsoft.com/library/windows/hardware/ff561042). + +- Device object in a non-PnP stack, not at bottom of stack + + For a device object that is not at the bottom of a non-PnP stack, a driver can send a **TargetDeviceRelation** query to obtain a pointer to the PDO at the bottom of the corresponding PnP device stack. + +- File object for the device + + Given a file object for the device, a driver can call [**IoGetRelatedDeviceObject**](https://msdn.microsoft.com/library/windows/hardware/ff549277) to get the device object and then follow the instructions in the preceding list item. + +- Handle to the device object + + Given a handle to the device object, a driver can call [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) to get the file object for the device and then follow the instructions in the preceding list item. + +A parent bus driver must handle a **TargetDeviceRelation** relations query for its child devices. The bus driver references the child device's PDO with [**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) and returns a pointer to the PDO in the **DEVICE\_RELATIONS** structure. There is only one PDO pointer in the structure for this relation type. The PnP manager removes the reference to the PDO when the driver or application unregisters for notification on the device. + +Only a parent bus driver responds to a **TargetDeviceRelation** query. Function and filter drivers must pass it to the next lower driver in the device stack. If a bus driver receives this IRP as the function driver for its adapter or controller, the bus driver is performing the tasks of a function driver and must pass the IRP to the next lower driver. + +If a driver is not in a PDO-based stack, the driver sends a new target-device-relation query IRP to the device object associated with the file handle on which the driver performs I/O. + +**Sending This IRP** + +Drivers must not send **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** to request **BusRelations**. Drivers are not restricted from sending this IRP for **RemovalRelations** or **EjectionRelations**, but it is not likely that a driver would do so. + +Drivers can query a device stack for **TargetDeviceRelation**. See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to **IRP\_MN\_QUERY\_DEVICE\_RELATIONS**, set **Parameters.QueryDeviceRelations.Type** to **TargetDeviceRelation**, and set **Irp->FileObject** to a valid file object. + +- Initialize **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +If a driver sent this IRP to get the PDO to report in response to an **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** for **TargetDeviceRelation** that the driver received, then the driver reports the PDO and frees the returned relations structure when the IRP completes. If a driver initiated this IRP for another reason, the driver frees the relations structure when the IRP completes and dereferences the PDO when it is no longer needed. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) + +[**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) + +[**IoGetRelatedDeviceObject**](https://msdn.microsoft.com/library/windows/hardware/ff549277) + +[**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) + +[**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) + +[**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](irp-mn-device-usage-notification.md) + +[**IRP\_MN\_EJECT**](irp-mn-eject.md) + +[**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) + +[**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) + +[**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) + +[**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) + +[**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_DEVICE_RELATIONS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-device-text.md b/windows-driver-docs-pr/kernel/irp-mn-query-device-text.md new file mode 100644 index 0000000000..c0fef7c924 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-device-text.md @@ -0,0 +1,97 @@ +--- +title: IRP\_MN\_QUERY\_DEVICE\_TEXT +author: windows-driver-content +description: The PnP manager uses this IRP to get a device's description or location information.Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 07661709-8929-4567-a05f-96d995862ee6 +keywords: + - IRP_MN_QUERY_DEVICE_TEXT Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_DEVICE\_TEXT + + +The PnP manager uses this IRP to get a device's description or location information. + +Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends two of these IRPs when a device is enumerated: one to query the device description and one to query the location information. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.QueryDeviceText.DeviceTextType** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure is a **DEVICE\_TEXT\_TYPE** value specifying which string is requested. Possible values for **DEVICE\_TEXT\_TYPE** include **DeviceTextDescription** and **DeviceTextLocationInformation**. + +**Parameters.QueryDeviceText.LocaleId** is an LCID specifying the locale for the requested text. + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a bus driver sets **Irp->IoStatus.Information** to a pointer to a driver-allocated block of memory containing a WCHAR buffer with the requested information. On an error, the bus driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +Bus drivers are strongly encouraged to return device descriptions for their child devices. This string is displayed in the **Found New Hardware** pop-up window if no INF match is found for the device. + +Bus drivers are also encouraged to return **LocationInformation** for their child devices, but this information is optional. The format of this string depends on the bus. The Device manager displays this string in the general properties tab for the device. Vendors should choose a string that conveys useful information to users and support personnel. For example, for PCI, the string contains the bus, device, and function. For PC Card, the string contains the slot. + +If a bus driver returns information in response to this IRP, it allocates a NULL-terminated Unicode string from paged memory. The PnP manager frees the string when it is no longer needed. + +If a device does not provide description or location information, the device's parent bus driver completes the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) without modifying **Irp->IoStatus.Status** or **Irp->IoStatus.Information**. + +Function and filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to **Irp->IoStatus**. + +Drivers for buses that support different text strings for different locales should be able to handle a request for a language that is not explicitly supported by the device. In such a situation, the bus driver should return the closest match for the locale or should fallback and return some appropriate supported locale string. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_DEVICE_TEXT%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-id.md b/windows-driver-docs-pr/kernel/irp-mn-query-id.md new file mode 100644 index 0000000000..0a5b1f30c7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-id.md @@ -0,0 +1,174 @@ +--- +title: IRP\_MN\_QUERY\_ID +author: windows-driver-content +description: Bus drivers must handle requests for BusQueryDeviceID for their child devices (child PDOs). Bus drivers can handle requests for BusQueryHardwareIDs, BusQueryCompatibleIDs, and BusQueryInstanceID for their child devices. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 3135cb30-a696-4201-8dfc-cdc1a29fe52b +keywords: + - IRP_MN_QUERY_ID Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_ID + + +Bus drivers must handle requests for **BusQueryDeviceID** for their child devices (child PDOs). Bus drivers can handle requests for **BusQueryHardwareIDs**, **BusQueryCompatibleIDs**, and **BusQueryInstanceID** for their child devices. + +Beginning with Windows 7, bus drivers must also handle requests for BusQueryContainerID for their child PDOs. + +For more information about these identifiers (IDs), see [Device Identification Strings](https://msdn.microsoft.com/library/windows/hardware/ff541224). + +**Note**  Function drivers and filter drivers do not handle this IRP. + +  + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP when a device is enumerated. A driver might send this IRP to retrieve the instance ID for one of its devices. + +The PnP manager and drivers send this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.QueryId.IdType** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure specifies the kind of ID(s) requested. Possible values include BusQueryDeviceID, BusQueryHardwareIDs, BusQueryCompatibleIDs, BusQueryInstanceID, and BusQueryContainerID. The following ID type is reserved: BusQueryDeviceSerialNumber. + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a driver sets **Irp->IoStatus.Information** to a WCHAR pointer that points to the requested information. On error, a driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +If a driver returns ID(s) in response to this IRP, it allocates a WCHAR structure from paged pool to contain the ID(s). The PnP manager frees the structure when it is no longer needed. + +A driver returns one of the following: + +- A REG\_SZ string in response to a BusQueryDeviceID, BusQueryInstanceID, or, BusQueryContainerID request. + +- A REG\_MULTI\_SZ string in response to a BusQueryHardwareIDs or BusQueryCompatibleIDs request. + +If a driver returns an ID with an illegal character, the system will bug check. Characters with the following values are illegal in an ID for this IRP: + +- Less than or equal to 0x20 (' ') + +- Greater than 0x7F + +- Equal to 0x2C (',') + +A driver must conform to the following length restrictions for IDs: + +- Each hardware ID or compatible ID that a driver returns in this IRP must be less than MAX\_DEVICE\_ID\_LEN characters long. This constant currently has a value of 200 as defined in sdk\\inc\\cfgmgr32.h. + +- The container ID that a driver returns in this IRP must be formatted as a globally unique identifier (GUID), and must be MAX\_GUID\_STRING\_LEN characters, which includes the null terminator. + +- If a bus driver supplies globally unique instance IDs for its child devices (that is, the driver sets [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095)**.UniqueID** for the devices), then the combination of device ID plus instance ID must be less than (MAX\_DEVICE\_ID\_LEN - 1) characters. The operating system requires the additional character for a path separator. + +- If a bus driver does not supply globally unique instance IDs for its child devices, then the combination of device ID plus instance ID must be less than (MAX\_DEVICE\_ID\_LEN - 28). The value of this equation is currently 172. + +Bus drivers should be prepared to handle this IRP for a child device immediately after the device is enumerated. + +**Specifying BusQueryDeviceID and BusQueryInstanceID** + +The values a bus driver supplies for BusQueryDeviceID and BusQueryInstanceID allow the operating system to differentiate a device from other devices on the computer. The operating system uses the device ID and instance ID that are returned in the **IRP\_MN\_QUERY\_ID** IRP and the unique ID field that are returned in the [**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) IRP to locate registry information for the device. + +For **BusQueryDeviceID**, a bus driver supplies the device's [*device ID*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-id). A device ID should contain the most-specific description of the device possible, incorporating the name of the enumerator and strings identifying the manufacturer, device, revision, packager, and packaged product, where possible. For example, the PCI bus driver responds with device IDs of the form PCI\\VEN\_xxxx&DEV\_xxxx&SUBSYS\_xxxxxxxx&REV\_xx, encoding all five of the items mentioned above. However, a device ID should not contain enough information to differentiate between two identical devices. This information should be encoded in the instance ID. + +For BusQueryInstanceID, a bus driver should supply a string that contains the [*instance ID*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-instance-id) for the device. Setup and bus drivers use the instance ID, with other information, to differentiate between two identical devices on the computer. The instance ID is either unique across the whole computer or just unique on the device's parent bus. + +If an instance ID is only unique on the bus, the bus driver specifies that string for BusQueryInstanceID but also specifies a **UniqueID** value of **FALSE** in response to an [**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) request for the device. If **UniqueID** is **FALSE**, the PnP manager enhances the instance ID by adding information about the device's parent and thus makes the ID unique on the computer. In this case the bus driver should not take extra steps to make its devices' instance IDs globally unique; just return the appropriate capabilities information and the operating system takes care of it. + +If a bus driver can supply a globally unique ID for each child device, such as a serial number, the bus driver specifies those strings for BusQueryInstanceID and specifies a **UniqueID** value of **TRUE** in response to an [**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) request for each device. + +**Specifying BusQueryHardwareIDs and BusQueryCompatibleIDs** + +The values a bus driver supplies for BusQueryHardwareIDs and BusQueryCompatibleIDs allow Setup to locate the appropriate drivers for the bus's child device. + +A bus driver responds to each of these requests with a REG\_MULTI\_SZ list of IDs that describe the device. The maximum length, in characters, of a list of IDs, including the two NULL characters that terminate the list, is REGSTR\_VAL\_MAX\_HCID\_LEN. + +When returning more than one [*hardware ID*](https://msdn.microsoft.com/library/windows/hardware/ff556288#wdkgloss-hardware-id) and/or more than one [*compatible ID*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-compatible-id), a bus driver should list the IDs in the order of most-specific to most-general to facilitate choosing the best driver match for the device. The first entry in the hardware IDs list is the most-specific description of the device and, as such, it is usually identical to the device ID. + +Setup checks the IDs against the IDs listed in INF files for possible matches. Setup first scans the hardware IDs list, then the compatible IDs list. Earlier entries are treated as more specific descriptions of the device, and later entries as more general (and thus less optimal) matches for the device. If no match is found in the list of hardware IDs, Setup might prompt the user for installation media before moving on to the list of compatible IDs. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Specifying BusQueryContainerIDs** + +Beginning with Windows 7, a bus driver should supply a string for BusQueryContainerID that contains the [container ID](https://msdn.microsoft.com/library/windows/hardware/ff540024) for the device. The container ID allows the operating system to group all functional devices from a single removable physical device. For example, all functional devices from a removable multifunction device have the same container ID. For more information about reporting container IDs in special cases, such as a volume device that may span multiple disks in multiple containers but does not belong to any container, see [Overview of Container IDs](https://msdn.microsoft.com/library/windows/hardware/ff549447). + +A removable physical device is defined as a child device that the bus driver specifies a **Removable** capability of **TRUE** in response to an [**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) request. For more information about the **Removable** value, see [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095). + +The bus driver creates a container ID based on a bus-specific unique ID that the device provides. For more information, see [How Container IDs are Generated](https://msdn.microsoft.com/library/windows/hardware/ff546193). + +The driver must fail the IRP request and set **IoStatus.Status** to STATUS\_NOT\_SUPPORTED if any of the following are true: + +- The device does not support a bus-specific unique ID that the bus driver can use to generate a container ID. + +- The bus driver had previously specified a **Removable** capability of **FALSE** in response to an [**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) request for the device. + +**Sending This IRP** + +Typically, only the PnP manager sends this IRP. + +To get the hardware IDs or compatible IDs for a device, call [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) instead of sending this IRP. + +A driver might send this IRP to retrieve the instance ID for one of its devices. For example, consider a multifunction PnP ISA device whose functions do not operate independently. The PnP manager enumerates the functions as separate devices, but the driver for such a device might be required to associate one or more of the functions. Because PnP ISA guarantees a unique instance ID, the driver for such a multifunction device can use the instance IDs to locate functions that reside on the same device. The driver for such a device must also get the device's enumerator name by calling [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203), to confirm that the device is a PnP ISA device. + +See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to IRP\_MN\_QUERY\_ID, and set **Parameters.QueryId.IdType** to **BusQueryInstanceID**. + +- Set **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +In addition to sending the query ID IRP, the driver must call [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) to get the **DevicePropertyEnumeratorName** for the device. + +After the IRP completes and the driver is finished with the ID, the driver must free the ID structure returned by the driver(s) that handled the query IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[Device Identification Strings](https://msdn.microsoft.com/library/windows/hardware/ff541224) + +[**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_ID%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-interface.md b/windows-driver-docs-pr/kernel/irp-mn-query-interface.md new file mode 100644 index 0000000000..f5e5aa3254 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-interface.md @@ -0,0 +1,165 @@ +--- +title: IRP\_MN\_QUERY\_INTERFACE +author: windows-driver-content +description: The IRP\_MN\_QUERY\_INTERFACE request enables a driver to export a direct-call interface to other drivers.A bus driver that exports an interface must handle this request for its child devices (child PDOs). +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: ae1dab46-c387-4e5f-9368-451e625ddbc1 +keywords: + - IRP_MN_QUERY_INTERFACE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_INTERFACE + + +The **IRP\_MN\_QUERY\_INTERFACE** request enables a driver to export a direct-call interface to other drivers. + +A bus driver that exports an interface must handle this request for its child devices (child PDOs). Function and filter can optionally handle this request. + +An "interface" in this context consists of one or more routines, and possibly data, exported by a driver or set of drivers. An interface has a structure that describes its contents and a GUID that identifies its type. + +For example, the PCMCIA bus driver exports an interface of type GUID\_PCMCIA\_INTERFACE\_STANDARD that contains routines for operations such as getting the write-protect condition of a PCMCIA memory card. The function driver for such a memory card can send an **IRP\_MN\_QUERY\_INTERFACE** request to the parent PCMCIA bus driver to get pointers to the PCMCIA interface routines. + +This section describes the query-interface IRP as a general mechanism. Drivers that expose an interface should provide additional information about their specific interface. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +A driver or system component sends this IRP to get information about an interface exported by a driver for a device. + +A driver or system component sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +A driver can receive this IRP at any time after the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine has been called for the device. The device might or might not be started when this IRP is sent (that is, you cannot assume that the driver has successfully completed an [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) request for the device). + +## Input Parameters + + +The **Parameters.QueryInterface** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure is itself a structure, which describes the interface being requested. The structure contains the following information: + +``` +CONST GUID *InterfaceType; +USHORT Size; +USHORT Version; +PINTERFACE Interface; +PVOID InterfaceSpecificData +``` + +The members of the structure are defined as follows: + +**InterfaceType** +Points to a GUID that identifies the interface being requested. The GUID can be for a system-defined interface, such as GUID\_BUS\_INTERFACE\_STANDARD, or a custom interface. The GUIDs for system-defined interfaces are listed in Wdmguid.h. GUIDs for custom interfaces should be generated with Uuidgen. + +**Size** +Specifies the size of the interface being requested. Drivers that handle this IRP must not return an [**INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff547825) structure larger than **Size** bytes. + +**Version** +Specifies the version of the interface being requested. + +If a driver supports more than one version of an interface, the driver returns the closest supported version without exceeding the requested version. The component that sent the IRP should examine the returned **Interface.Version** field and determine what to do based on that value. + +**Interface** +Points to a structure in which to return the requested interface. This structure must contain an [**INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff547825) structure as its first member. The component sending the IRP allocates this structure from paged memory. + +A driver that exports an interface defines a new structure type containing the **INTERFACE** structure, plus members for routines and/or data in the interface. (The driver also defines a GUID for the interface, as described in the **InterfaceType** member, above.) + +A driver that exports an interface defines the execution environment for each routine in the interface, including the IRQL at which the routine can be called, and so forth. + +**InterfaceSpecificData** +Specifies additional information about the interface being requested. + +For some interfaces, the component sending the IRP specifies additional information in this field. Typically, this field is **NULL** and the **InterfaceType** and **Version** are sufficient to identify the interface being requested. + +## Output Parameters + + +On success, a driver fills in the members of the **Parameters.QueryInterface.Interface** structure. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a bus driver sets **Irp->IoStatus.Information** to zero. + +If a function or filter driver does not handle this IRP, it calls [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and passes the IRP down to the next driver. Such a driver must not modify **Irp->IoStatus.Status** and must not complete the IRP. + +If a bus driver does not export the requested interface and therefore does not handle this IRP for a child PDO, the bus driver leaves **Irp->IoStatus.Status** as is and completes the IRP. + +Operation +--------- + +A driver handles this IRP if the parameters specify an interface the driver supports. + +A driver must not queue this IRP if the IRP requests an interface that the driver does not support. A driver must check **Parameters.QueryInterface.InterfaceType** in its [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure. If the interface is not one the driver supports, the driver must pass the IRP to the next lower driver in the device stack without blocking. + +Each interface must provide **InterfaceReference** and **InterfaceDereference** routines, and the driver that exports the interface must supply the addresses of these routines in the [**INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff547825) structure. Before a driver returns an interface in response to the IRP, it must increment the interface's reference count by calling its **InterfaceReference** routine. When the driver that requested the interface has finished using it, that driver must decrement the reference count by calling the interface's **InterfaceDereference** routine. + +If the driver that sends the IRP (driver *x*) later passes the interface to another driver (driver *y*) then driver *x* must increment the interface's reference count and driver *y* must decrement it. + +A driver that handles this IRP should avoid passing the IRP to another device stack to get the requested interface. Such a design would create dependencies between the device stacks that are difficult to manage. For example, the device represented by the second device stack cannot be removed until the appropriate driver in the first stack dereferences the interface. + +Interfaces can be bus-specific or bus-independent. Bus-specific interfaces are defined in the header files for those buses. The system defines a bus-independent interface, [**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707), for exporting standard bus interfaces. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +This IRP is used specifically to pass routine entry points between layered kernel-mode drivers for a device. Do not confuse the interfaces exposed by this IRP with [*device interfaces*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-interface). A device interface is used primarily for exposing a path to a device for use by user-mode components or other kernel components. For more information about device interfaces, see [Device Interface Classes](https://msdn.microsoft.com/library/windows/hardware/ff541339). + +**Sending This IRP** + +See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Allocate an [**INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff547825) structure from paged pool and initialize it to zeros. If the interface will be called at IRQL >= DISPATCH\_LEVEL, based on the interface contract, the caller can copy the contents to memory that is allocated from nonpaged pool. + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to **IRP\_MN\_QUERY\_INTERFACE**, and set the appropriate values in **Parameters.QueryInterface**. + +- Initialize **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +- Deallocate the IRP and the **INTERFACE** structure when they are no longer needed. + +- Use the interface routines and context parameter as described in the specification for the interface. + +- Decrement the reference count using the [*InterfaceDereference*](https://msdn.microsoft.com/library/windows/hardware/ff547829) routine when the interface is no longer needed. Do not call any interface routines after dereferencing the interface. + +A driver typically sends this IRP to the top of the device stack in which the driver is attached. If a driver sends this IRP to a different device stack, the driver must register for target device notification on the other device if the other device is not an ancestor of the device that the driver is servicing. Such a driver calls [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) with an *EventCategory* of **EventCategoryTargetDeviceChange**. When the driver receives notification of type GUID\_TARGET\_DEVICE\_QUERY\_REMOVE, the driver must dereference the interface. The driver can requery for the interface if it receives a subsequent GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED notification. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707) + +[**INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff547825) + +[**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_INTERFACE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-legacy-bus-information.md b/windows-driver-docs-pr/kernel/irp-mn-query-legacy-bus-information.md new file mode 100644 index 0000000000..9f6ba3a6e7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-legacy-bus-information.md @@ -0,0 +1,48 @@ +--- +title: IRP\_MN\_QUERY\_LEGACY\_BUS\_INFORMATION +author: windows-driver-content +description: This IRP is reserved for system use. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 223a5c7a-9bba-457e-9004-94446c7ebb63 +keywords: + - IRP_MN_QUERY_LEGACY_BUS_INFORMATION Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_LEGACY\_BUS\_INFORMATION + + +This IRP is reserved for system use. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_LEGACY_BUS_INFORMATION%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-pnp-device-state.md b/windows-driver-docs-pr/kernel/irp-mn-query-pnp-device-state.md new file mode 100644 index 0000000000..859e7d1896 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-pnp-device-state.md @@ -0,0 +1,162 @@ +--- +title: IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE +author: windows-driver-content +description: Function, filter, and bus drivers can handle this request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 24362a20-9e9d-4566-bc95-ce52b91056af +keywords: + - IRP_MN_QUERY_PNP_DEVICE_STATE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE + + +Function, filter, and bus drivers can handle this request. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP after the drivers for a device return success from the [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) request sent when a device is first started. This IRP is not sent on a start after a stop for resource rebalancing. The PnP manager also sends this IRP when a driver for the device calls [**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361). + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of an arbitrary thread. + +## Input Parameters + + +None + +## Output Parameters + + +Returned in I/O status block. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_UNSUCCESSFUL. + +On success, a driver sets **Irp->IoStatus.Information** to a [**PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff559618) bitmask. + +The PNP\_DEVICE\_STATE type is a bitmask that describes the PnP state of a device. A driver returns a value of this type in response to an **IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE** request. + +``` syntax +typedef ULONG PNP_DEVICE_STATE, *PPNP_DEVICE_STATE; +``` + +The flag bits in a PNP\_DEVICE\_STATE value are defined as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Flag bitDescription
PNP_DEVICE_DISABLED

The device is physically present but is disabled in hardware.

PNP_DEVICE_DONT_DISPLAY_IN_UI

Do not display the device in the user interface. Set for a device that is physically present but not usable in the current configuration, such as a game port on a laptop that is not usable when the laptop is undocked. (Also see the NoDisplayInUI flag in the [DEVICE_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure.)

PNP_DEVICE_FAILED

The device is present but not functioning properly.

+

When both this flag and PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED are set, the device must be stopped before the PnP manager assigns new hardware resources (nonstop rebalance is not supported for the device).

PNP_DEVICE_NOT_DISABLEABLE

The device is required when the computer starts. Such a device must not be disabled.

+

A driver sets this bit for a device that is required for proper system operation. For example, if a driver receives notification that a device is in the paging path ([IRP_MN_DEVICE_USAGE_NOTIFICATION](irp-mn-device-usage-notification.md) for DeviceUsageTypePaging), the driver calls [IoInvalidateDeviceState](https://msdn.microsoft.com/library/windows/hardware/ff549361) and sets this flag in the resulting IRP_MN_QUERY_PNP_DEVICE_STATE request.

+

If this bit is set for a device, the PnP manager propagates this setting to the device's parent device, its parent's parent device, and so forth.

+

If this bit is set for a root-enumerated device, the device cannot be disabled or uninstalled.

PNP_DEVICE_REMOVED

The device has been physically removed.

PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED

The resource requirements for the device have changed.

+

Typically, a bus driver sets this flag when it has determined that it must expand its resource requirements in order to enumerate a new child device.

PNP_DEVICE_DISCONNECTED

The device driver is loaded, but this driver has detected that the device is no longer connected to the computer. Typically, this flag is used for function drivers that communicate with wireless devices. For example, the flag is set when the device moves out of range, and is cleared after the device moves back into range and re-connects.

+

A bus driver does not typically set this flag. The bus driver should instead stop enumerating the child device if the device is no longer connected. This flag is used only if the function driver manages the connection.

+

The sole purpose of this flag is to let clients know whether the device is connected. Setting the flag does not affect whether the driver is loaded.

+ +  + +The PnP manager queries a device's PNP\_DEVICE\_STATE right after starting the device by sending an **IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE** request to the device stack. In response to this IRP, the drivers for the device set the appropriate flags in PNP\_DEVICE\_STATE. + +If any of the state characteristics change after the initial query, a driver notifies the PnP manager by calling [**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361). In response to a call to **IoInvalidateDeviceState**, the PnP manager queries the device's PNP\_DEVICE\_STATE again. + +If a device is marked PNP\_DEVICE\_NOT\_DISABLEABLE, the debugger displays a DNUF\_NOT\_DISABLEABLE user flag for the devnode. The debugger also displays a **DisableableDepends** value that counts the number of reasons why the device cannot be disabled. This value is the sum of X+Y, where X is one if the device cannot be disabled and Y is the count of the device's child devices that cannot be disabled. + +If a function or filter driver does not handle this IRP, it calls [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355), does not set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, and passes the IRP down to the next driver. Such a driver must not modify **Irp->IoStatus** and must not complete the IRP. + +If a bus driver does not handle this IRP, it leaves **Irp->IoStatus.Status** as is and completes the IRP. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then by each next lower driver in the stack. + +A driver handles this IRP if it has information about the PnP state of a device. A driver can set or clear the flags in the PNP\_DEVICE\_STATE bitmask. If another driver has set a PNP\_DEVICE\_STATE in **Irp->IoStatus.Information**, a driver must take care to modify the flags in that bitmask rather than overwrite the whole structure. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361) + +[**PNP\_DEVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff559618) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_PNP_DEVICE_STATE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-power.md b/windows-driver-docs-pr/kernel/irp-mn-query-power.md new file mode 100644 index 0000000000..9b0d06d543 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-power.md @@ -0,0 +1,128 @@ +--- +title: IRP\_MN\_QUERY\_POWER +author: windows-driver-content +description: This IRP queries a device to determine whether the system power state or the device power state can be changed. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: fc4c5364-2160-4525-889a-96785a3c7a07 +keywords: + - IRP_MN_QUERY_POWER Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_POWER + + +This IRP queries a device to determine whether the system power state or the device power state can be changed. + +Major Code +---------- + +[**IRP\_MJ\_POWER**](irp-mj-power.md) +When Sent +--------- + +The power manager or a device power policy owner sends this IRP to determine whether it can change the system or device power state, typically to go to sleep. A driver must call [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to allocate and send this IRP. + +The power manager sends this IRP at IRQL = PASSIVE\_LEVEL to device stacks that set the DO\_POWER\_PAGABLE flag in the PDO. + +The power manager can send the IRP at IRQL = DISPATCH\_LEVEL if the DO\_POWER\_INRUSH flag is set. Such drivers cannot directly or indirectly access any paged code or data. + +## Input Parameters + + +**Parameters.Power.Type** specifies the type of power state being set, either **SystemPowerState** or **DevicePowerState**. + +**Parameters.Power.State** specifies the power state itself, as follows: + +- If **Parameters.Power.Type** is **SystemPowerState**, the value is an enumerator of the [**SYSTEM\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff564565) type. + +- If **Parameters.Power.Type** is **DevicePowerState**, the value is an enumerator of the [**DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff543160) type. + +**Parameters.Power.ShutdownType** specifies additional information about the requested transition. Possible values are enumerators of the **POWER\_ACTION** type. + +## Output Parameters + + +None. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS to indicate that the device can enter the requested state. A driver sets any appropriate failure status to indicate that it cannot enter the requested state. + +Operation +--------- + +The parameters for **IRP\_MN\_QUERY\_POWER** are identical to those for [**IRP\_MN\_SET\_POWER**](irp-mn-set-power.md). Rather than notifying drivers of an irrevocable change to the power state, however, **IRP\_MN\_QUERY\_POWER** queries whether the system or a device can enter a particular power state. + +A driver must not change the power state of its device in response to an **IRP\_MN\_QUERY\_POWER** request. + +After a driver receives an **IRP\_MN\_QUERY\_POWER** request on Windows Server 2003, Windows XP, and Windows 2000, a driver must call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), as described in [Calling **PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff540724). Beginning with Windows Vista, calling **PoStartNextPowerIrp** is not required and such a call performs no power management operation. + +**IRP\_MN\_QUERY\_POWER for a System Power State** + +The power manager sends this IRP to ensure that it can change the system power state without disrupting work, such as dropping network connections. + +Whenever possible, the power manager queries before sending **IRP\_MN\_SET\_POWER** to request a system sleep state or a normal system shutdown. However, under some critical conditions (such as the user pressing the **Power Off** button or a battery expiring), the power manager might send an **IRP\_MN\_SET\_POWER** request without first sending a query power request. The power manager queries only for sleep states; it never queries before returning to the working state. + +When a driver receives a system power query IRP, it should fail the IRP if it cannot support any of the device states that are valid for the queried system state. For more information, see [**DeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff543087). Otherwise, the driver should pass the IRP to the next lower driver. The bus driver completes the IRP. + +Beginning with Windows Vista, transition to a system sleep state is considered a critical operation. Although a driver might fail a system query-power IRP, the power manager might still change the system power state to a sleep state. After a driver receives a system query-power IRP, the driver should always be prepared for a subsequent change in the system power state. + +When a device power policy owner receives a system power query IRP, it should set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine in the IRP before passing it down. In the *IoCompletion* routine, it should send an **IRP\_MN\_QUERY\_POWER** for a device state that is valid for the queried system state. For more information, see [Handling a System Query-Power IRP in a Device Power Policy Owner](https://msdn.microsoft.com/library/windows/hardware/ff546725). + +When the IRP specifies **PowerSystemShutdown** (S5), the value at **Parameters.Power.ShutdownType** provides a reason for the shutdown. The **ShutdownType** tells the driver whether the system is resetting (**PowerActionShutdownReset**) or powering off indefinitely to reboot later (**PowerActionShutdownOff**). For drivers of most devices, the difference is inconsequential. However, for certain devices, such as a video streaming device that performs DMA, a driver might opt to power down its device when the system is resetting, thus stopping any ongoing I/O. + +On Microsoft Windows 2000 and later systems, the value at **ShutdownType** can also be **PowerActionShutdown**. In this case, the driver cannot tell what type of shutdown is requested and should therefore proceed as for a reset. + +If a driver fails an **IRP\_MN\_QUERY\_POWER** request for a system power state, the power manager typically responds by issuing an **IRP\_MN\_SET\_POWER** IRP. Usually, this IRP will reaffirm the current system state. However, it is possible that drivers might receive an **IRP\_MN\_SET\_POWER** to the queried state or to some other intermediate state. Drivers should be prepared to handle these situations. + +**IRP\_MN\_QUERY\_POWER for a Device Power State** + +A device power policy owner sends this IRP to its stack in response to a system **IRP\_MN\_QUERY\_POWER** request. + +If a driver can put its device in the requested device state, it sets **IoStatus.Status** to STATUS\_SUCCESS and passes the IRP down to the next lower driver, and so forth until the IRP reaches the bus driver. If any driver in the stack must fail the IRP, that driver should complete the IRP immediately by calling **IoCompleteRequest** and returning a failure status. Drivers that fail the IRP do not pass it further down the stack. + +By returning STATUS\_SUCCESS, the driver guarantees that it will not start any operation that would change its ability to set the requested power state. The driver should queue any IRPs that require such operations until it completes a set-power IRP that returns the device to an acceptable power state. + +On Windows 2000 and later systems, when the IRP specifies **PowerDeviceD1**, **PowerDeviceD2**, or **PowerDeviceD3**, the value at **Parameters.Power.ShutdownType** provides information about the current system power IRP, if a system power IRP is active. In this case, the value at **ShutdownType** indicates the currently requested system power state, or **PowerActionNone** if a system request is not outstanding. On Windows 98/Me, this field always contains **PowerActionNone** when the IRP requests a device power state. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_QUERY\_POWER**](irp-mn-query-power.md) + +[**IRP\_MN\_SET\_POWER**](irp-mn-set-power.md) + +[**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) + +[**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_POWER%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-remove-device.md b/windows-driver-docs-pr/kernel/irp-mn-query-remove-device.md new file mode 100644 index 0000000000..e65ed553dc --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-remove-device.md @@ -0,0 +1,92 @@ +--- +title: IRP\_MN\_QUERY\_REMOVE\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 95ec9ed8-014f-4d01-bed7-3aeb29cd9e73 +keywords: + - IRP_MN_QUERY_REMOVE_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_REMOVE\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to inform drivers that a device is about to be removed from the computer and to query whether the device can be removed without disrupting the computer. The PnP manager also sends this IRP if a user requests to update driver(s) for the device. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_UNSUCCESSFUL. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then passed down to each lower driver in the stack. + +In response to this IRP, drivers indicate whether the device can be removed without disrupting the computer. + +For more information about handling this IRP, see [Handling an IRP\_MN\_QUERY\_REMOVE\_DEVICE Request](https://msdn.microsoft.com/library/windows/hardware/ff546674). For general information about supporting device removal, see [Removing a Device](https://msdn.microsoft.com/library/windows/hardware/ff561046). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](irp-mn-cancel-remove-device.md) + +[**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](irp-mn-device-usage-notification.md) + +[**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_REMOVE_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-resource-requirements.md b/windows-driver-docs-pr/kernel/irp-mn-query-resource-requirements.md new file mode 100644 index 0000000000..03f0059bf4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-resource-requirements.md @@ -0,0 +1,96 @@ +--- +title: IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS +author: windows-driver-content +description: The PnP manager uses this IRP to get a device's resource requirements list.Bus drivers must handle this request for their child devices that require hardware resources. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 5a77f8d6-2b6b-4eff-8d48-e7942976ec52 +keywords: + - IRP_MN_QUERY_RESOURCE_REQUIREMENTS Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS + + +The PnP manager uses this IRP to get a device's resource requirements list. + +Bus drivers must handle this request for their child devices that require hardware resources. Bus filter drivers can handle this request. Function and filter drivers do not handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP when a device is enumerated, prior to allocating resources to a device, and when a driver reports that its device's resource requirements have changed. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +None + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A driver that handles this IRP sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or an appropriate error status. + +On success, a driver sets **Irp->IoStatus.Information** to a pointer to an [**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) that contains the requested information. On an error, the driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +If a bus driver returns a resource requirements list in response to this IRP, it allocates an **IO\_RESOURCE\_REQUIREMENTS\_LIST** from paged memory. The PnP manager frees the buffer when it is no longer needed. + +If a device requires no hardware resources, the device's bus driver completes the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) without modifying **Irp->IoStatus.Status** or **Irp->IoStatus.Information**. + +If a bus filter driver handles this IRP, it modifies the resource requirements list created by the bus driver. A bus filter driver modifies the list on the IRP's way back up the device stack. A bus filter driver must preserve the order of resources in the resource requirements list and must not alter resource tags that it does not handle. If a bus filter driver changes the size of the resource requirements list, the driver must allocate a new structure from paged memory and free the previous structure. If a bus filter driver adds a new resource requirement to the list and the resource is assigned to the device, the driver must filter the new resource out of the [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) IRP so it is not passed to the bus driver. + +Function and non-bus filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to **Irp->IoStatus**. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IO\_RESOURCE\_REQUIREMENTS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff550609) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_RESOURCE_REQUIREMENTS%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-resources.md b/windows-driver-docs-pr/kernel/irp-mn-query-resources.md new file mode 100644 index 0000000000..48e5144151 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-resources.md @@ -0,0 +1,98 @@ +--- +title: IRP\_MN\_QUERY\_RESOURCES +author: windows-driver-content +description: The PnP manager uses this IRP to get a device's boot configuration resources.Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: b9a6f06b-07d9-4539-bd41-21cdccdc4b25 +keywords: + - IRP_MN_QUERY_RESOURCES Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_RESOURCES + + +The PnP manager uses this IRP to get a device's boot configuration resources. + +Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP when a device is enumerated. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +None + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A bus driver that handles this IRP sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a bus driver sets **Irp->IoStatus.Information** to a pointer to a [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) that contains the requested information. On an error, the bus driver sets **Irp->IoStatus.Information** to zero. + +Operation +--------- + +If a bus driver returns a resource list in response to this IRP, it allocates a [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) from paged memory. The PnP manager frees the buffer when it is no longer needed. + +If a device requires no hardware resources, the device's parent bus driver completes the IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) without modifying **Irp->IoStatus.Status** or **Irp->IoStatus.Information**. + +Function and filter drivers do not receive this IRP. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Drivers can call [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) to get the boot configuration for a device, in both raw and translated forms. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) + +[**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_RESOURCES%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-single-instance.md b/windows-driver-docs-pr/kernel/irp-mn-query-single-instance.md new file mode 100644 index 0000000000..08e9a1f1f2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-single-instance.md @@ -0,0 +1,142 @@ +--- +title: IRP\_MN\_QUERY\_SINGLE\_INSTANCE +author: windows-driver-content +description: All drivers that support WMI must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 104b6b3e-aa5d-437f-8236-02e4abb1ba46 +keywords: + - IRP_MN_QUERY_SINGLE_INSTANCE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_SINGLE\_INSTANCE + + +All drivers that support WMI must handle this IRP. A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** request, WMI in turn calls that driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine. + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +WMI sends this IRP to query for a single instance of a given data block. + +WMI sends an **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** prior to sending an [**IRP\_MN\_EXECUTE\_METHOD**](irp-mn-execute-method.md). If a driver supports **IRP\_MN\_EXECUTE\_METHOD**, it must have an **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** handler for the same data block whose method is being executed. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** points to a GUID that identifies the data block to query. + +**Parameters.WMI.BufferSize** indicates the maximum size of the nonpaged buffer at **Parameters.WMI.Buffer**, which points to a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure that identifies the instance to query. + +## Output Parameters + + +If the driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI fills in a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure with data provided by the driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine. + +Otherwise, the driver fills in the **WNODE\_SINGLE\_INSTANCE** structure at **Parameters.WMI.Buffer** as follows: + +- Updates **WnodeHeader.BufferSize** with the size, in bytes, of the output **WNODE\_SINGLE\_INSTANCE** structure, including instance data. This value should include the length of the instance name (padded such that the instance data begins on a quad word boundary), even if the class being queried registered static instance names and the driver writer is not explicitly supplying the name when servicing this IRP. + +- Sets **SizeDataBlock** to the size, in bytes, of the instance data. If static instance names are in use, this value should not include the size of the instance name. + +- Writes the instance data to **Parameters.WMI.Buffer** starting at **DataBlockOffset**. The driver must not change the input value of **DataBlockOffset**. + +If the buffer at **Parameters.WMI.Buffer** is too small to receive all of the data, the driver fills in the needed size in a [**WNODE\_TOO\_SMALL**](https://msdn.microsoft.com/library/windows/hardware/ff566379) structure at **Parameters.WMI.Buffer**. If the buffer is smaller than **sizeof**(**WNODE\_TOO\_SMALL**), the driver fails the IRP and returns STATUS\_BUFFER\_TOO\_SMALL. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_BUFFER\_TOO\_SMALL + +STATUS\_WMI\_GUID\_NOT\_FOUND + +STATUS\_WMI\_INSTANCE\_NOT\_FOUND + +On success, a driver sets **Irp->IoStatus.Information** to the value entered into **WnodeHeader.BufferSize**. This value includes the length of the static instance name. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), **WmiSystemControl** calls the driver's [*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) routine. + +If a driver handles an **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed in its call to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next lower driver in the device stack. + +Before handling the request, the driver must determine whether **Parameters.WMI.DataPath** points to a GUID that the driver supports. If not, the driver must fail the IRP and return STATUS\_WMI\_GUID\_NOT\_FOUND. + +The driver is responsible for validating all input values. Specifically, the driver must do the following if it handles the IRP request itself: + +- For static names, verify that the **InstanceIndex** member of the [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure is within the range of instance indexes supported by the driver for the data block. + +- For dynamic names, verify that the instance name string identifies a data block instance supported by the driver. + +- Verify that **Parameters.WMI.BufferSize** specifies a buffer that is large enough to receive all the data that the driver will return. + +If the driver supports the data block, it checks the input [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) at **Parameters.WMI.Buffer** for the instance name, as follows: + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is set in **WnodeHeader.Flags**, the driver uses **InstanceIndex** as an index into the driver's list of static instance names for that block. WMI obtains the index from registration data provided by the driver when it registered the block. + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is clear in **WnodeHeader.Flags**, the driver uses the offset at **OffsetInstanceName** to locate the instance name string in the input **WNODE\_SINGLE\_INSTANCE**. **OffsetInstanceName** is the offset, in bytes, from the beginning of the structure to a USHORT, which is the length of the instance name string in bytes (not characters), including the terminating null if present, followed by the instance name string in Unicode. + +If the driver cannot locate the specified instance, it must fail the IRP and return STATUS\_WMI\_INSTANCE\_NOT\_FOUND. For an instance with a dynamic instance name, this status indicates that the driver does not support the instance. WMI can therefore continue to query other data providers, and return an appropriate error to the data consumer if another provider finds the instance but cannot handle the request for some other reason. + +If the driver locates the instance and can handle the request, it fills in the **WNODE\_SINGLE\_INSTANCE** structure at **Parameters.WMI.Buffer** with data for the instance. + +If the instance is valid but the driver cannot handle the request, it can return any appropriate error status. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiQueryDataBlock*](https://msdn.microsoft.com/library/windows/hardware/ff544096) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_SINGLE_INSTANCE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-query-stop-device.md b/windows-driver-docs-pr/kernel/irp-mn-query-stop-device.md new file mode 100644 index 0000000000..5531d67cf7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-query-stop-device.md @@ -0,0 +1,100 @@ +--- +title: IRP\_MN\_QUERY\_STOP\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 22f58964-23a0-4307-a748-9c1620e30871 +keywords: + - IRP_MN_QUERY_STOP_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_QUERY\_STOP\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to query whether a device can be stopped to rebalance resources. + +On Windows 98/Me, the PnP manager also sends this IRP when a device is being disabled. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. If a driver cannot stop the device, the driver sets **Irp->IoStatus.Status** to STATUS\_UNSUCCESSFUL. + +A bus driver can set **Irp->IoStatus.Status** to STATUS\_RESOURCE\_REQUIREMENTS\_CHANGED to indicate success for the IRP but also to request that the PnP manager requery the resource requirements for the device before sending the stop IRP. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then passed down to each lower driver in the stack. + +In response to this IRP, Windows 2000 and later drivers indicate whether it is safe to stop the device for resource rebalancing. + +On Windows 98/Me, this IRP is sent not only during resource rebalancing, but also when a device is being disabled. Because a driver cannot distinguish these two situations, it should proceed as if the device were being disabled. If there are any open handles to the device, the driver should fail this IRP. If no handles are open, the driver should proceed as described in [Handling an IRP\_MN\_QUERY\_STOP\_DEVICE Request (Windows 98/Me)](https://msdn.microsoft.com/library/windows/hardware/ff546684). + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play Minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_CANCEL\_STOP\_DEVICE**](irp-mn-cancel-stop-device.md) + +[**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](irp-mn-device-usage-notification.md) + +[**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) + +[**IRP\_MN\_STOP\_DEVICE**](irp-mn-stop-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_QUERY_STOP_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-read-config.md b/windows-driver-docs-pr/kernel/irp-mn-read-config.md new file mode 100644 index 0000000000..24d8321aff --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-read-config.md @@ -0,0 +1,181 @@ +--- +title: IRP\_MN\_READ\_CONFIG +author: windows-driver-content +description: Bus drivers for buses with configuration space must handle this request for their child devices (child PDOs). Filter and function drivers do not handle this request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: cbc5b959-0aae-4c86-b490-296965a7f158 +keywords: + - IRP_MN_READ_CONFIG Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_READ\_CONFIG + + +Bus drivers for buses with configuration space must handle this request for their child devices (child PDOs). Filter and function drivers do not handle this request. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +A driver or other system component sends this IRP to read the configuration space of a device's parent bus. + +A driver or other system component sends this IRP at IRQL < DISPATCH\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.ReadWriteConfig** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure is itself a structure containing the following information: + +``` +ULONG WhichSpace; +PVOID Buffer; +ULONG Offset; +ULONG Length +``` + +The members of the structure can be interpreted differently by different bus drivers, but the members are typically defined as follows: + +**WhichSpace** +Specifies which memory area to access. This parameter can take the following values: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueBusMeaning

PCI_WHICHSPACE_CONFIG

PCI

PCI configuration space.

PCI_WHICHSPACE_ROM

PCI

Read-only memory.

PCCARD_COMMON_MEMORY

+

PCCARD_COMMON_MEMORY_INDIRECT

PCMCIA

Main PCCARD memory.

PCCARD_ATTRIBUTE_MEMORY

+

PCCARD_ATTRIBUTE_MEMORY_INDIRECT

PCMCIA

PCMCIA attribute (configuration) space.

PCCARD_PCI_CONFIGURATION_SPACE

PCMCIA

PCI configuration space.

+ +  + +The PCI\_*XXX* values are defined in Wdm.h. The PCCARD\_*XXX* values are defined in Ntddpcm.h. + +**Buffer** +Points to a buffer in which to return the requested information. The component sending the IRP allocates this structure from paged memory. The format of the buffer is bus-specific. + +**Offset** +Specifies an offset into the configuration space. + +**Length** +Specifies the number of bytes to read. + +## Output Parameters + + +On success, a bus driver fills the buffer at **Parameters.ReadWriteConfig.Buffer** with the requested data. + +## I/O Status Block + + +A bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_INVALID\_PARAMETER\_*n*, STATUS\_NO\_SUCH\_DEVICE, or STATUS\_DEVICE\_NOT\_READY. + +On success, a bus driver sets **Irp->IoStatus.Information** to the number of bytes returned. + +If a bus driver is unable to complete this request immediately it can mark the IRP pending, return STATUS\_PENDING, and complete the IRP at a later time. + +Operation +--------- + +A bus driver handles this IRP for its child devices (child PDOs). + +Function and filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to **Irp->IoStatus**.Status and they do not set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +A bus driver that handles this request should check the WhichSpace parameter to ensure that it contains a value that the driver supports. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Typically, a function driver sends this IRP to the top driver in the device stack to which it is attached and the IRP is handled by the parent bus driver. + +See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Allocate a buffer from a paged pool and initialize it to zeros. + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to **IRP\_MN\_READ\_CONFIG**, and set the appropriate values in **Parameters.ReadWriteConfig**. + +- Initialize **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +- Deallocate the IRP and the buffer when they are no longer needed. + +Drivers must send this IRP from IRQL < DISPATCH\_LEVEL. + +A driver can access a bus's configuration space at DISPATCH\_LEVEL through a bus interface routine, if the parent bus driver supports such an interface. To get a bus interface, a driver sends an [**IRP\_MN\_QUERY\_INTERFACE**](irp-mn-query-interface.md) request to the device stack in which the driver is attached. The driver then calls the appropriate routine returned in the interface. + +For example, to read configuration space from DISPATCH\_LEVEL, a driver can call **IRP\_MN\_QUERY\_INTERFACE** during driver initialization to get the [**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707) interface from the parent bus driver. The driver sends the query IRP from IRQL PASSIVE\_LEVEL. Later, from code at IRQL DISPATCH\_LEVEL, the driver calls the appropriate routine returned in the interface, such as the **Interface.GetBusData** routine. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_QUERY\_INTERFACE**](irp-mn-query-interface.md) + +[**IRP\_MN\_WRITE\_CONFIG**](irp-mn-write-config.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_READ_CONFIG%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-reginfo-ex.md b/windows-driver-docs-pr/kernel/irp-mn-reginfo-ex.md new file mode 100644 index 0000000000..4c5b9ad2b3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-reginfo-ex.md @@ -0,0 +1,166 @@ +--- +title: IRP\_MN\_REGINFO\_EX +author: windows-driver-content +description: WMI sends this IRP to query or update a driver's registration information after the driver has called IoWMIRegistrationControl. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 2fdfd3b1-102d-4adb-af95-363201764bd5 +keywords: + - IRP_MN_REGINFO_EX Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_REGINFO\_EX + + +WMI sends this IRP to query or update a driver's registration information after the driver has called [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle an **IRP\_MN\_REGINFO\_EX** request, WMI in turn calls that driver's [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +On Microsoft Windows XP and later operating systems, drivers that support WMI must handle this IRP. Drivers that support Microsoft Windows 98 and Windows 2000 must also handle [**IRP\_MN\_REGINFO**](irp-mn-reginfo.md). + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +On Windows XP and later, WMI sends this IRP to query or update a driver's registration information after the driver has called [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). On Windows 98 and Windows 2000, WMI sends the **IRP\_MN\_REGINFO** request instead. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** is set to **WMIREGISTER** to query registration information or **WMIUPDATE** to update it. + +**Parameters.WMI.BufferSize** indicates the maximum size of the nonpaged buffer at **Parameters.WMI.Buffer**. The size must be greater than or equal to the total of (**sizeof**(WMIREGINFO) + (*GuidCount* \* **sizeof**(WMIREGGUID)), where *GuidCount* is the number of data blocks and event blocks being registered by the driver, plus space for static instance names, if any. + +## Output Parameters + + +If the driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI gets registration information for a driver's data blocks by calling its *DpWmiQueryReginfo* routine. + +Otherwise, the driver fills in a [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure at **Parameters.WMI.Buffer** as follows: + +- Sets **BufferSize** to the size in bytes of the **WMIREGINFO** structure plus associated registration data. + +- If the driver handles WMI requests on behalf of another driver, sets **NextWmiRegInfo** to the offset in bytes from the beginning of this **WMIREGINFO** to the beginning of another **WMIREGINFO** structure that contains registration information from the other driver. + +- Sets **RegistryPath** to the registry path that was passed to the driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. + +- If **Parameters.WMI.Datapath** is set to **WMIREGISTER**, sets **MofResourceName** to the offset from the beginning of this **WMIREGINFO** to a counted Unicode string that contains the name of the driver's MOF resource in its image file. + +- Sets **GuidCount** to the number of data blocks and event blocks to register or update. + +- Writes an array of [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structures, one for each data block or event block exposed by the driver, at **WmiRegGuid**. + +The driver fills in each **WMIREGGUID** structure as follows: + +- Sets **Guid** to the GUID that identifies the block. + +- Sets **Flags** to provide information about instance names and other characteristics of the block. For example, if a block is being registered with static instance names, the driver sets **Flags** with the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* flag. + +If the block is being registered with static instance names, the driver: + +- Sets **InstanceCount** to the number of instances. + +- Sets one of the following members to an offset in bytes to static instance name data for the block: + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_LIST, it sets **InstanceNameList** to an offset to a list of static instance name strings. WMI specifies instances in subsequent requests by index into this list. + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_BASENAME, it sets **BaseNameOffset** to an offset to a base name string. WMI uses this string to generate static instance names for the block. + + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_PDO, it sets **Pdo** to an offset to a pointer to the PDO passed to the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. WMI uses the device instance path of the PDO to generate static instance names for the block. Drivers must call [**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) on the physical device object passed in **Pdo**. The system will automatically call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) to dereference the object; the driver must not do so. (Drivers that use [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle IRPs do not need to call **ObReferenceObject**. WMI automatically does so before calling the driver's [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine.) + +- Writes the instance name strings, the base name string, or a pointer to the PDO at the offset indicated by **InstanceNameList**, **BaseName**, or **Pdo**, respectively. + +If the driver handles WMI registration on behalf of another driver (such as a miniclass or miniport driver), it fills in another **WMIREGINFO** structure with the other driver's registration information and writes it at **NextWmiRegInfo** in the previous structure. + +If the buffer at **Parameters.WMI.Buffer** is too small to receive all of the data, a driver writes the needed size in bytes as a ULONG to **Parameters.WMI.Buffer** and fails the IRP and returns STATUS\_BUFFER\_TOO\_SMALL. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_BUFFER\_TOO\_SMALL + +On success, a driver sets **Irp->IoStatus.Information** to the number of bytes written to the buffer at **Parameters.WMI.Buffer**. + +Operation +--------- + +If a driver handles an **IRP\_MN\_REGINFO\_EX** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling the request, the driver must check **Parameters.WMI.DataPath** to determine whether WMI is querying registration information (**WMIREGISTER**) or requesting an update (**WMIUPDATE**). + +WMI sends this IRP with WMIREGISTER after a driver calls **IoWMIRegistrationControl** with WMIREG\_ACTION\_REGISTER or WMIREG\_ACTION\_REREGISTER. In response, a driver should fill in the buffer at **Parameters.WMI.Buffer** with the following: + +- A [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure that indicates the driver's registry path, the name of its MOF resource, and the number of blocks to register. + +- One[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structure for each block to register. If a block is to be registered with static instance names, the driver sets the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* flag in the **WMIREGGUID** structure for that block. + +- Any strings WMI needs to generate static instance names. + +WMI sends this IRP with **WMIUPDATE** after a driver calls **IoWmiRegistrationControl** with WMIREG\_ACTION\_UPDATE\_GUIDS. In response, a driver should fill in the buffer at **Parameters.WMI.Buffer** with a WMIREGINFO structure as follows: + +- To remove a block, the driver sets WMIREG\_FLAG\_REMOVE\_GUID in its **WMIREGGUID** structure. + +- To add or update a block (for example, to change its static instance names), the driver clears WMIREG\_FLAG\_REMOVE\_GUID and provides new or updated registration values for the block. + +- To register a new or existing block with static instance names, the driver sets the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* and supplies any strings WMI needs to generate static instance names. + +A driver can use the same **WMIREGINFO** structures to remove, add, or update blocks as it used initially to register all of its blocks, changing only the flags and data for the blocks to be updated. If a **WMIREGGUID** in such a **WMIREGINFO** structure matches exactly the **WMIREGGUID** passed by the driver when it first registered that block, WMI skips the processing involved in updating the block. + +WMI does not send an **IRP\_MN\_REGINFO\_EX** request after a driver calls [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) with WMIREG\_ACTION\_DEREGISTER, because WMI requires no further information from the driver. A driver typically deregisters its blocks in response to an [**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) request. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) + +[**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**IRP\_MN\_REGINFO**](irp-mn-reginfo.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_REGINFO_EX%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-reginfo.md b/windows-driver-docs-pr/kernel/irp-mn-reginfo.md new file mode 100644 index 0000000000..e70ffeba0d --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-reginfo.md @@ -0,0 +1,162 @@ +--- +title: IRP\_MN\_REGINFO +author: windows-driver-content +description: Drivers that support WMI on Microsoft Windows 98 and Microsoft Windows 2000 must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: db93b64b-a2e4-429d-850e-921fb438467c +keywords: + - IRP_MN_REGINFO Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_REGINFO + + +Drivers that support WMI on Microsoft Windows 98 and Microsoft Windows 2000 must handle this IRP. (Drivers that support Windows XP as well must also handle the [**IRP\_MN\_REGINFO\_EX**](irp-mn-reginfo-ex.md) IRP.) A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +Major Code +---------- + +[**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) +When Sent +--------- + +On Windows 98 and Windows 2000, WMI sends this IRP to query or update a driver's registration information after the driver has called [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). On Windows XP and later, WMI sends the **IRP\_MN\_REGINFO\_EX** request instead. + +WMI sends this IRP at IRQL = PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +**Parameters.WMI.ProviderId** points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP. + +**Parameters.WMI.DataPath** is set to **WMIREGISTER** to query registration information or **WMIUPDATE** to update it. + +**Parameters.WMI.BufferSize** indicates the maximum size of the nonpaged buffer at **Parameters.WMI.Buffer**. The size must be greater than or equal to the total of (**sizeof**(**WMIREGINFO**) + (*GuidCount* \* **sizeof**(**WMIREGGUID**)), where *GuidCount* is the number of data blocks and event blocks being registered by the driver, plus space for static instance names, if any. + +## Output Parameters + + +If the driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI gets registration information for a driver's data blocks by calling its [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +Otherwise, the driver fills in a [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure at **Parameters.WMI.Buffer** as follows: + +- Sets **BufferSize** to the size in bytes of the **WMIREGINFO** structure plus associated registration data. + +- If the driver handles WMI requests on behalf of another driver, sets **NextWmiRegInfo** to the offset in bytes from the beginning of this **WMIREGINFO** to the beginning of another **WMIREGINFO** structure that contains registration information from the other driver. + +- Sets **RegistryPath** to the registry path that was passed to the driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. + +- If **Parameters.WMI.Datapath** is set to **WMIREGISTER**, sets **MofResourceName** to the offset from the beginning of this **WMIREGINFO** to a counted Unicode string that contains the name of the driver's MOF resource in its image file. + +- Sets **GuidCount** to the number of data blocks and event blocks to register or update. + +- Writes an array of [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structures, one for each data block or event block exposed by the driver, at **WmiRegGuid**. + +The driver fills in each **WMIREGGUID** structure as follows: + +- Sets **Guid** to the GUID that identifies the block. + +- Sets **Flags** to provide information about instance names and other characteristics of the block. For example, if a block is being registered with static instance names, the driver sets **Flags** with the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* flag. + +If the block is being registered with static instance names, the driver: + +- Sets **InstanceCount** to the number of instances. + +- Sets one of the following members to an offset in bytes to static instance name data for the block: + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_LIST, it sets **InstanceNameList** to an offset to a list of static instance name strings. WMI specifies instances in subsequent requests by index into this list. + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_BASENAME, it sets **BaseNameOffset** to an offset to a base name string. WMI uses this string to generate static instance names for the block. + - If the driver sets **Flags** with WMIREG\_FLAG\_INSTANCE\_PDO, it sets **Pdo** to an offset to a pointer to the PDO passed to the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. WMI uses the device instance path of the PDO to generate static instance names for the block. +- Writes the instance name strings, the base name string, or a pointer to the PDO at the offset indicated by **InstanceNameList**, **BaseName**, or **Pdo**, respectively. + +If the driver handles WMI registration on behalf of another driver (such as a miniclass or miniport driver), it fills in another WMIREGINFO structure with the other driver's registration information and writes it at **NextWmiRegInfo** in the previous structure. + +If the buffer at **Parameters.WMI.Buffer** is too small to receive all of the data, a driver writes the needed size in bytes as a ULONG to **Parameters.WMI.Buffer** and fails the IRP and returns STATUS\_BUFFER\_TOO\_SMALL. + +## I/O Status Block + + +If the driver handles the IRP by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), WMI sets **Irp->IoStatus.Status** and **Irp->IoStatus.Information** in the I/O status block. + +Otherwise, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as the following: + +STATUS\_BUFFER\_TOO\_SMALL + +On success, a driver sets **Irp->IoStatus.Information** to the number of bytes written to the buffer at **Parameters.WMI.Buffer**. + +Operation +--------- + +A driver can handle WMI IRPs either by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) or by handling the IRP itself, as described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +If a driver handles WMI IRPs by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), that routine calls the driver's [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +If a driver handles an **IRP\_MN\_REGINFO** request itself, it should do so only if **Parameters.WMI.ProviderId** points to the same device object as the pointer that the driver passed to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the request to the next-lower driver. + +Before handling the request, the driver must check **Parameters.WMI.DataPath** to determine whether WMI is querying registration information (**WMIREGISTER**) or requesting an update (**WMIUPDATE**). + +WMI sends this IRP with WMIREGISTER after a driver calls **IoWMIRegistrationControl** with WMIREG\_ACTION\_REGISTER or WMIREG\_ACTION\_REREGISTER. In response, a driver should fill in the buffer at **Parameters.WMI.Buffer** with the following: + +- A [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) structure that indicates the driver's registry path, the name of its MOF resource, and the number of blocks to register. + +- One[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structure for each block to register. If a block is to be registered with static instance names, the driver sets the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* flag in the **WMIREGGUID** structure for that block. + +- Any strings WMI needs to generate static instance names. + +WMI sends this IRP with **WMIUPDATE** after a driver calls **IoWmiRegistrationControl** with WMIREG\_ACTION\_UPDATE\_GUIDS. In response, a driver should fill in the buffer at **Parameters.WMI.Buffer** with a WMIREGINFO structure as follows: + +- To remove a block, the driver sets WMIREG\_FLAG\_REMOVE\_GUID in its **WMIREGGUID** structure. + +- To add or update a block (for example, to change its static instance names), the driver clears WMIREG\_FLAG\_REMOVE\_GUID and provides new or updated registration values for the block. + +- To register a new or existing block with static instance names, the driver sets the appropriate WMIREG\_FLAG\_INSTANCE\_*XXX* and supplies any strings WMI needs to generate static instance names. + +A driver can use the same **WMIREGINFO** structures to remove, add, or update blocks as it used initially to register all of its blocks, changing only the flags and data for the blocks to be updated. If a **WMIREGGUID** in such a **WMIREGINFO** structure matches exactly the **WMIREGGUID** passed by the driver when it first registered that block, WMI skips the processing involved in updating the block. + +WMI does not send an **IRP\_MN\_REGINFO** request after a driver calls [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) with WMIREG\_ACTION\_DEREGISTER, because WMI requires no further information from the driver. A driver typically deregisters its blocks in response to an [**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) request. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) + +[**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) + +[**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) + +[**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) + +[**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) + +[**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) + +[**IRP\_MN\_REGINFO\_EX**](irp-mn-reginfo-ex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_REGINFO%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-remove-device.md b/windows-driver-docs-pr/kernel/irp-mn-remove-device.md new file mode 100644 index 0000000000..554d502bc5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-remove-device.md @@ -0,0 +1,102 @@ +--- +title: IRP\_MN\_REMOVE\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 0d733cbd-2da8-48a5-afc6-e1e6b8f507a1 +keywords: + - IRP_MN_REMOVE_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_REMOVE\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager uses this IRP to direct drivers to remove a device's software representation (device objects, and so forth). The PnP manager sends this IRP when a device has been removed in an orderly fashion (for example, initiated by a user in the Unplug or Eject Hardware program), by surprise (a user pulls the device from its slot without prior warning), or when the user requests to update driver(s). + +On Windows 2000 and later systems, the PnP manager also sends this IRP if one of the drivers in the device stack fails an [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) request for the device. + +For an orderly device removal, the PnP manager sends an [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) prior to the remove IRP. In this case, the device is in the remove-pending state when the remove IRP arrives. For a surprise device removal on Microsoft Windows 2000 or later, the PnP manager sends an [**IRP\_MN\_SURPRISE\_REMOVAL**](irp-mn-surprise-removal.md) prior to the remove IRP. In this case, the device is in the surprise-removed state when the remove IRP arrives. Drivers can also receive a remove IRP before a device is started. In this case, the device is in the non-started state when the IRP arrives. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver must set **Irp->IoStatus.Status** to STATUS\_SUCCESS. Drivers must not fail this IRP. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then by each lower driver in the stack. + +In response to this IRP, drivers perform such tasks as powering down the device, removing the device's software representation (device objects, and so forth), and releasing any resources for the device. + +For more information about handling this IRP, see [Handling an IRP\_MN\_REMOVE\_DEVICE Request](https://msdn.microsoft.com/library/windows/hardware/ff546687). For general information about supporting device removal, see [Removing a Device](https://msdn.microsoft.com/library/windows/hardware/ff561046). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +If a bus driver detects that one (or more) of its child devices (child PDOs) has been physically removed from the computer, the bus driver calls [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) to report the change to the PnP manager. The PnP manager then sends remove IRPs for any devices that have disappeared. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353) + +[**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) + +[**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](irp-mn-cancel-remove-device.md) + +[**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) + +[**IRP\_MN\_SURPRISE\_REMOVAL**](irp-mn-surprise-removal.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_REMOVE_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-set-lock.md b/windows-driver-docs-pr/kernel/irp-mn-set-lock.md new file mode 100644 index 0000000000..6f6d63be1e --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-set-lock.md @@ -0,0 +1,87 @@ +--- +title: IRP\_MN\_SET\_LOCK +author: windows-driver-content +description: Bus drivers must handle this IRP for their child devices (child PDOs) that support device locking. Function and filter drivers do not handle this request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: d4e09527-f817-4eb5-b0f5-7584de8888b1 +keywords: + - IRP_MN_SET_LOCK Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_SET\_LOCK + + +Bus drivers must handle this IRP for their child devices (child PDOs) that support device locking. Function and filter drivers do not handle this request. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to direct driver(s) to lock the device and prevent device eject, or to unlock the device. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +The **Parameters.SetLock.Lock** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure is a BOOLEAN value specifying whether to lock (TRUE) or unlock (FALSE) the device. + +## Output Parameters + + +None + +## I/O Status Block + + +A bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status. + +On success, a driver sets **Irp->IoStatus.Information** to zero. + +If a bus driver does not handle this IRP, it leaves **Irp->IoStatus.Status** as is and completes the IRP. + +Function and filter drivers do not handle this IRP. Such drivers call [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP down to the next driver. Function and filter drivers do not set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, do not modify **Irp->IoStatus**, and must not complete the IRP. + +Operation +--------- + +If a driver returns success for this IRP, it ensures that the device has been locked or unlocked before completing the IRP. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_SET_LOCK%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-set-power.md b/windows-driver-docs-pr/kernel/irp-mn-set-power.md new file mode 100644 index 0000000000..465d1c0591 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-set-power.md @@ -0,0 +1,190 @@ +--- +title: IRP\_MN\_SET\_POWER +author: windows-driver-content +description: This IRP notifies a driver of a change to the system power state or sets the device power state for a device. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 1294183a-bd0b-4ead-bd64-669d5b3725ce +keywords: + - IRP_MN_SET_POWER Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_SET\_POWER + + +This IRP notifies a driver of a change to the system power state or sets the device power state for a device. + +Major Code +---------- + +[**IRP\_MJ\_POWER**](irp-mj-power.md) +When Sent +--------- + +Either the system power manager or a device power policy owner can send this IRP. + +The power manager sends this IRP to notify drivers of a change to the system power state. If a driver has registered its device for idle detection, the power manager sends this IRP to change the power state of an idle device. + +A driver that owns power policy sends this IRP to set the device power state for its device. A driver must call [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send this IRP. + +The power manager sends this IRP at IRQL = PASSIVE\_LEVEL to device stacks that set the DO\_POWER\_PAGABLE flag in the PDO. Drivers in such stacks can touch paged code or data to complete the request. + +The power manager can send the IRP at IRQL = DISPATCH\_LEVEL if the DO\_POWER\_INRUSH flag is set. Such drivers cannot directly or indirectly access any paged code or data. + +## Input Parameters + + +The **Parameters.Power.Type** member specifies the type of power state being set, either **SystemPowerState** or **DevicePowerState**. + +The **Parameters.Power.State** member specifies the power state itself, as follows: + +- If **Parameters.Power.Type** is **SystemPowerState**, the value is an enumerator of the [**SYSTEM\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff564565) type. + +- If **Parameters.Power.Type** is **DevicePowerState**, the value is an enumerator of the [**DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff543160) type. + +The **Parameters.Power.ShutdownType** member specifies additional information about the requested transition. The possible values for this member are **POWER\_ACTION** enumeration values. For more information, see [System Power Actions](https://msdn.microsoft.com/library/windows/hardware/ff564553). + +Starting with Windows Vista, the **Parameters.Power.SystemPowerStateContext** member is a read-only, partially opaque [**SYSTEM\_POWER\_STATE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/jj835780) structure that contains information about the previous system power states of a computer. If **Parameters.Power.Type** is **SystemPowerState** and **Parameters.Power.State** is **PowerSystemWorking**, two flag bits in this structure indicate whether a fast startup or a wake-from-hibernation caused the computer to enter the S0 (working) system state. For more information, see [Distinguishing Fast Startup from Wake-from-Hibernation](https://msdn.microsoft.com/library/windows/hardware/jj835779). + +## Output Parameters + + +**Parameters.Power.SystemContext** is reserved for system use. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS to indicate that the device has entered the requested state. + +A driver must not fail a request to set the system power state. + +Function and filter drivers that are located above a bus driver must not fail a request to set a device power state. The bus driver can fail a device power-up request if the device is removed or in the process of being removed. + +Operation +--------- + +The power manager or a driver can request an **IRP\_MN\_SET\_POWER** IRP. The power manager sends this IRP for one of the following reasons: + +- To notify drivers of a change to the system power state + +- To change the power state of a device for which the power manager is performing idle detection + +A driver that owns device power policy sends **IRP\_MN\_SET\_POWER** to change the power state of its device. + +At any given time, the system allows only one such IRP to be active for each device object. + +Each driver must pass each power IRP down to the next-lower driver by calling [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (starting with Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (Windows Server 2003, Windows XP, and Windows 2000). The **PoCallDriver** interface is similar to that of **IoCallDriver**, except that the power management subsystem might delay the IRP before passing it on to the next driver. For example, delays can occur on a **PowerDeviceD0** request if the device requires inrush current and therefore must be powered up serially with another such device. + +After a driver receives an **IRP\_MN\_SET\_POWER** request on Windows Server 2003, Windows XP, or Windows 2000, a driver must call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), as described in [Calling PoStartNextPowerIrp](https://msdn.microsoft.com/library/windows/hardware/ff540724). Beginning with Windows Vista, calling **PoStartNextPowerIrp** is not required, and such a call performs no power management operation. + +**IRP\_MN\_SET\_POWER for System Power States** + +Only the system power manager can send a system set-power IRP. + +A driver must not fail a request to set the system power state. + +Whenever possible, the power manager sends [**IRP\_MN\_QUERY\_POWER**](irp-mn-query-power.md) before sending **IRP\_MN\_SET\_POWER** to request a system sleep state. However, under some conditions (such as the user pressing the **Power Off** button or a battery expiring), the power manager might issue **IRP\_MN\_SET\_POWER** without first querying. The power manager queries only for sleep states; it never queries before powering up. + +The **IRP\_MN\_SET\_POWER** request is sent to the top driver in the device stack for a device. The top driver passes the IRP down to the next lower driver and so forth until the IRP reaches the bus driver, which must complete the IRP. + +A filter driver typically does not need to act on a system set-power IRP, other than to pass it on. + +The device power policy owner, however, sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine before passing down the IRP. In the *IoCompletion* routine, it sends an **IRP\_MN\_SET\_POWER** request for a device power IRP. For more information, see [Handling a System Set-Power IRP in a Device Power Policy Owner](https://msdn.microsoft.com/library/windows/hardware/ff546749). + +A system set-power IRP informs drivers that a change to the system power state is imminent and the drivers must prepare for it. However, a driver should not change the power state of its device until it receives an **IRP\_MN\_SET\_POWER** for a *device* power state. + +The value at **Parameters.Power.ShutdownType** provides additional information about the pending actions. When the IRP specifies **PowerSystemShutdown** (S5), a driver can determine whether the system is resetting (**PowerActionShutdownReset**) or powering off indefinitely to reboot later (**PowerActionShutdownOff**). For drivers of most devices, the difference is inconsequential. However, for certain devices, such as video streaming devices, a driver might power off the device in order to stop I/O when the system is resetting. + +On Windows 2000 and later versions of the operating system, the value at **ShutdownType** can also be **PowerActionShutdown**. In this case, the driver cannot tell what type of shutdown is requested and should therefore proceed as for a reset. + +**Device Power States** + +Function and filter drivers that are located above a bus driver must not fail a request to set a device power state. The bus driver can fail a device power-up request if the device is removed or in the process of being removed. + +A driver must set the device into the requested state before completing the IRP. + +When the IRP requests a transition to a lower power state, drivers must handle the IRP as it travels down the device stack, saving any context the driver will need to restore the device to the working state. After a bus driver receives an IRP, the driver: + +- Saves any context the driver will need to restore the device to the working state. + +- Sets the device to the requested power state. + +- Calls [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager. + +- Calls **PoStartNextPowerIrp** to start the next power IRP (Windows Server 2003, Windows XP, and Windows 2000 only). + +- Completes the device power IRP. + +The driver must complete this IRP in a timely manner. In general, drivers should avoid any delay that a typical user would find noticeably slow. For example, a driver could delay a system state change to flush cached disk or network data, but should not keep a network connection alive or format a tape. For more information, see [Passing Power IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558785). + +On Windows 2000 and later versions of the operating system, if the IRP specifies **PowerDeviceD1**, **PowerDeviceD2**, or **PowerDeviceD3**, and a system set-power IRP is active, the value at **Parameters.Power.ShutdownType** provides information about the system IRP. + +Drivers of devices on the hibernate path should inspect this value. If the IRP requests **PowerDeviceD3** and **ShutdownType** is **PowerActionHibernate**, such a driver should save any context required to restore the device, but should not power down the device; the device will enter the D3 state when the machine loses power. + +On Windows 2000 and later versions of the operating system, drivers should not rely on the value at **ShutdownType** if the requested power state is **PowerDeviceD0**. + +On Windows 98/Me, if the IRP requests a device power state, the **ShutdownType** is always **PowerActionNone**. + +The driver that determines when to power down a device varies depending on the device class. + +The driver that determines when to power up a device is almost always a driver that accesses the device registers. The driver must verify that the device is in the D0 state before accessing the device's hardware registers. If the device is not in the D0 state, the driver must call **PoRequestPowerIrp** to send an IRP to power up the device. A driver cannot access its device unless the device is in the D0 state. + +When a driver receives a set-power IRP for device state D0, it sets an *IoCompletion* routine and passes the IRP to the next lower driver. + +When the IRP reaches the bus driver, that driver applies (or resets) power to the device, calls **PoStartNextPowerIrp** (Windows Server 2003, Windows XP, and Windows 2000 only), and calls **PoSetPowerState** to inform the power manager of the new power state for the device. + +After the bus driver completes the power-up IRP, function and filter drivers handle the IRP in their *IoCompletion* routines as it travels back up the device stack. In the *IoCompletion* routine, each driver restores or reinitializes its device context and performs any other required start-up tasks. + +For more information, see [Handling IRP\_MN\_SET\_POWER for Device Power States](https://msdn.microsoft.com/library/windows/hardware/ff546885). + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff543160) + +[**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) + +[**IRP\_MN\_QUERY\_POWER**](irp-mn-query-power.md) + +[**IRP\_MN\_SET\_POWER**](irp-mn-set-power.md) + +[**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) + +[**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) + +[**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) + +[**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) + +[**SYSTEM\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff564565) + +[**SYSTEM\_POWER\_STATE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/jj835780) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_SET_POWER%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-start-device.md b/windows-driver-docs-pr/kernel/irp-mn-start-device.md new file mode 100644 index 0000000000..ffefc49a4b --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-start-device.md @@ -0,0 +1,98 @@ +--- +title: IRP\_MN\_START\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 0aac1346-b5c7-4dcc-ab86-03e8fd151505 +keywords: + - IRP_MN_START_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_START\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP after it has assigned hardware resources, if any, to the device. The device may have been recently enumerated and is being started for the first time, or the device may be restarting after being stopped for resource rebalancing. + +Sometimes the PnP manager sends an **IRP\_MN\_START\_DEVICE** to a device that is already started, supplying a different set of resources than the device is currently using. A driver initiates this action by calling [**IoInvalidateDeviceState**](https://msdn.microsoft.com/library/windows/hardware/ff549361) and responding to the subsequent [**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](irp-mn-query-pnp-device-state.md) request with the PNP\_RESOURCE\_REQUIREMENTS\_CHANGED flag set. A bus driver might use this mechanism, for example, to open a new aperture on a PCI-to-PCI bridge. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +The **Parameters.StartDevice.AllocatedResources** member of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure points to a [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) describing the hardware resources that the PnP manager assigned to the device. This list contains the resources in raw form. Use the raw resources to program the device. + +**Parameters.StartDevice.AllocatedResourcesTranslated** points to a [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) describing the hardware resources that the PnP manager assigned to the device. This list contains the resources in translated form. Use the translated resources to connect the interrupt vector, map I/O space, and map memory. + +## Output Parameters + + +None + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_UNSUCCESSFUL or STATUS\_INSUFFICIENT\_RESOURCES. + +If a driver requires some time to run its start operations for a device, it can mark the IRP pending and return STATUS\_PENDING. + +Operation +--------- + +This IRP must be handled first by the parent bus driver for a device and then by each higher driver in the device stack. + +In response to this IRP, drivers start a device for the first time or restart a device that was stopped. The exact operations required to start a device vary from device to device, but can include powering on the device, performing device-specific initialization, and connecting the interrupt. + +A driver can typically handle this IRP in the same way whether it is starting a device for the first time or restarting a device after an [**IRP\_MN\_STOP\_DEVICE**](irp-mn-stop-device.md), except if a driver needs to restore device state on a restart after a stop. + +On Windows Vista and later operating systems, we recommend that drivers always pend the **IRP\_MN\_START\_DEVICE** IRP and complete its processing later. This order enables the system to process device restarts asynchronously. (On operating systems before Windows Vista, drivers can return STATUS\_PENDING from their dispatch routines, but the PnP manager does not overlap the device restart with any other operation.) + +For more information about handling a start IRP, see [Starting a Device](https://msdn.microsoft.com/library/windows/hardware/ff563849). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_STOP\_DEVICE**](irp-mn-stop-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_START_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-stop-device.md b/windows-driver-docs-pr/kernel/irp-mn-stop-device.md new file mode 100644 index 0000000000..258230ae65 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-stop-device.md @@ -0,0 +1,104 @@ +--- +title: IRP\_MN\_STOP\_DEVICE +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: a5c81db0-e753-4d91-97e4-c58ea05f5ce8 +keywords: + - IRP_MN_STOP_DEVICE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_STOP\_DEVICE + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to stop a device so it can reconfigure the device's hardware resources. + +On Windows 2000 and later systems, the PnP manager sends this IRP only if a prior [**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) completed successfully. + +On Windows 98/Me, the PnP manager also sends this IRP when a device is being disabled and when a device stack has failed an **IRP\_MN\_START\_DEVICE** request. In cases of failed start, the PnP manager sends this IRP without a preceding [**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) request. + +The PnP manager sends this IRP at IRQL PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver must set **Irp->IoStatus.Status** to STATUS\_SUCCESS. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then passed down to each lower driver in the stack. + +In response to this IRP, Windows 2000 and later drivers stop the device and release any hardware resources being used by the device, such as I/O ports and interrupts. + +On Windows 2000 and later, a stop IRP is used solely to free a device's hardware resources so they can be reconfigured. Once the resources are reconfigured, the device is restarted. A stop IRP is not a precursor to a remove IRP. See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for more information about the order in which PnP IRPs are sent to devices. + +On Windows 98/Me, a stop IRP is also used after a failed start and when a device is being disabled. WDM drivers that run on these operating systems should stop the device, fail any incoming I/O, and disable and deregister any user-mode interfaces. + +A driver must not fail this IRP. If a driver cannot release the device's hardware resources, it must fail the preceding query-stop IRP. + +See [Stopping a Device](https://msdn.microsoft.com/library/windows/hardware/ff563868) for detailed information about handling stop IRPs. + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) + +[**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) + +[**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700) + +[**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_STOP_DEVICE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-surprise-removal.md b/windows-driver-docs-pr/kernel/irp-mn-surprise-removal.md new file mode 100644 index 0000000000..8d999d61dc --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-surprise-removal.md @@ -0,0 +1,92 @@ +--- +title: IRP\_MN\_SURPRISE\_REMOVAL +author: windows-driver-content +description: All PnP drivers must handle this IRP. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 19d6847c-6b64-4552-b8b8-fef1d9b13fc7 +keywords: + - IRP_MN_SURPRISE_REMOVAL Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_SURPRISE\_REMOVAL + + +All PnP drivers must handle this IRP. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +The PnP manager sends this IRP to notify the drivers for a device that the device is no longer available for I/O operations. This IRP is sent on Windows 2000 and later systems only. + +The PnP manager sends this IRP before notifying user-mode applications or other kernel-mode components. After this IRP completes, the PnP manager notifies registered applications and drivers that the device has been removed. + +The device can be in any PnP state when the PnP manager sends this IRP. + +On Windows 98/Windows Me, the PnP manager does not send this IRP. + +The PnP manager sends this IRP at IRQL = PASSIVE\_LEVEL in the context of a system thread. + +## Input Parameters + + +None + +## Output Parameters + + +None + +## I/O Status Block + + +A driver must set **Irp->IoStatus.Status** to STATUS\_SUCCESS. A driver must not fail this IRP. + +Operation +--------- + +This IRP is handled first by the driver at the top of the device stack and then passed down to each lower driver in the stack. + +For more information about this IRP, see [Handling an IRP\_MN\_SURPRISE\_REMOVAL Request](https://msdn.microsoft.com/library/windows/hardware/ff546699). For additional information about supporting device removal, see [Removing a Device](https://msdn.microsoft.com/library/windows/hardware/ff561046). + +**Sending This IRP** + +Reserved for system use. Drivers must not send this IRP. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_SURPRISE_REMOVAL%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-wait-wake.md b/windows-driver-docs-pr/kernel/irp-mn-wait-wake.md new file mode 100644 index 0000000000..5317d5ad59 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-wait-wake.md @@ -0,0 +1,126 @@ +--- +title: IRP\_MN\_WAIT\_WAKE +author: windows-driver-content +description: This IRP enables a driver to awaken a sleeping system or to awaken a sleeping device. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: b79fd057-bf95-457e-882a-42221789e6e6 +keywords: + - IRP_MN_WAIT_WAKE Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_WAIT\_WAKE + + +This IRP enables a driver to awaken a sleeping system or to awaken a sleeping device. + +Major Code +---------- + +[**IRP\_MJ\_POWER**](irp-mj-power.md) +When Sent +--------- + +A driver that owns power policy targets this IRP to its PDO to enable its device to awaken in response to an external event, such as an incoming phone call. A driver must call [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send this IRP. + +As a general rule, a driver should send this IRP as soon as it determines that its device should be enabled for wake-up. Consequently, drivers for most such devices send this IRP after powering on their devices and before completing the [**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) request. + +However, a driver can send the IRP any time the device is in the working state (**PowerDeviceD0**). The device stack must not be in transition; that is, a driver should not send an **IRP\_MN\_WAIT\_WAKE** while any other power IRP is active in its device stack. + +A wait/wake IRP does not change the power state of the device or of the system. It simply enables a wake-up signal from the device. When the wake-up signal arrives, the policy owner must call **PoRequestPowerIrp** to send a set-power IRP to return its device to D0. + +The driver must be running at IRQL = PASSIVE\_LEVEL to send this IRP. However, the IRP can be completed at IRQL = DISPATCH\_LEVEL. + +## Input Parameters + + +**Parameters.WaitWake.PowerState** contains the lowest (least-powered) system power state from which the device should be allowed to awaken the system. + +## Output Parameters + + +None. + +## I/O Status Block + + +A driver sets **Irp->IoStatus.Status** to one of the following: + +STATUS\_PENDING +The driver received the IRP and is waiting for the device to signal wake-up. + +STATUS\_INVALID\_DEVICE\_STATE +The device is in a less-powered state than the **DeviceWake** state specified in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure for the device, or the device cannot awaken the system from the **SystemWake** state passed in the IRP. + +STATUS\_NOT\_SUPPORTED +The device does not support wake-up. + +STATUS\_DEVICE\_BUSY +An **IRP\_MN\_WAIT\_WAKE** request is already pending and must be completed or canceled before another IRP\_MN\_WAIT\_WAKE request can be issued. + +STATUS\_SUCCESS +The device has signaled a wake event. + +STATUS\_CANCELLED +The IRP has been canceled. + +If a driver must fail this IRP, it completes the IRP immediately and does not pass the IRP to the next-lower driver. + +Operation +--------- + +A driver sends **IRP\_MN\_WAIT\_WAKE** for either of two reasons: + +1. To enable its device to awaken a sleeping system in response to an external wake-up signal. + +2. To enable its device to awaken from a device sleep state in response to an external wake-up signal. + +The IRP must be passed down the device stack to the bus driver for the device, which calls [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) and returns STATUS\_PENDING from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. The IRP remains pending until a wake-up signal occurs or until the driver that sent the IRP cancels it. + +Only one wait/wake IRP can be held pending for a PDO at any given time. If a driver already holds a wait/wake IRP for a PDO, it must fail any additional such IRPs with STATUS\_DEVICE\_BUSY. A driver that enumerates more than one child PDO can have a wait/wake IRP pending for each such PDO. + +Each driver sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine as the IRP travels down the device stack. When the device signals a wake-up event, the bus driver services the wake-up signal and completes the IRP, returning STATUS\_SUCCESS. The I/O manager then calls the *IoCompletion* routine of the next higher driver, and so on up the device stack. + +When a driver sends a wait/wake IRP, it should specify a callback routine in the **PoRequestPowerIrp** call. In the callback routine, the driver typically services the device. For example, the power policy owner for the device must call **PoRequestPowerIrp** to send an [**IRP\_MN\_SET\_POWER**](irp-mn-set-power.md) for device state D0. + +A driver that acts as the bus driver for one device and the policy owner for a parent device requests an **IRP\_MN\_WAIT\_WAKE** IRP for the parent's device stack when it receives a **IRP\_MN\_WAIT\_WAKE** request from a child PDO. If the driver enumerates more than one child PDO, it should request only one wait/wake IRP for the parent's device stack no matter how many child PDOs send wait/wake requests. Instead, such a driver should keep an internal count of wait/wake IRPs, incrementing the count each time it receives a request and decrementing the count each time it completes a request. If the count is nonzero after it has completed a wait/wake IRP, the driver should send another wait/wake IRP to its device stack to "rearm" itself for wake-up. For more information, see [Understanding the Path of Wait/Wake IRPs through a Device Tree](https://msdn.microsoft.com/library/windows/hardware/ff564867). + +To cancel an **IRP\_MN\_WAIT\_WAKE**, a driver calls [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338). Only the driver that originated the IRP can cancel it. A driver cancels a pending **IRP\_MN\_WAIT\_WAKE** when any of the following occurs: + +- The driver receives a PnP IRP that stops or removes the device. + +- The system is going to sleep and the device wake signal must not awaken it. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_WAIT_WAKE%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-mn-write-config.md b/windows-driver-docs-pr/kernel/irp-mn-write-config.md new file mode 100644 index 0000000000..f3c5140266 --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-mn-write-config.md @@ -0,0 +1,131 @@ +--- +title: IRP\_MN\_WRITE\_CONFIG +author: windows-driver-content +description: Bus drivers for buses with configuration space must handle this request for their child devices (child PDOs). Function and filter drivers do not handle this request. +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: d57c30b8-83bd-41c9-906d-b8c95f8ca54e +keywords: + - IRP_MN_WRITE_CONFIG Kernel-Mode Driver Architecture +--- + +# IRP\_MN\_WRITE\_CONFIG + + +Bus drivers for buses with configuration space must handle this request for their child devices (child PDOs). Function and filter drivers do not handle this request. + +Major Code +---------- + +[**IRP\_MJ\_PNP**](irp-mj-pnp.md) +When Sent +--------- + +A driver or other system component sends this IRP to write data to the configuration space of a device's parent bus. + +A driver or other system component sends this IRP at IRQL < DISPATCH\_LEVEL in an arbitrary thread context. + +## Input Parameters + + +**Parameters.ReadWriteConfig** is a structure containing the following information: + +``` +ULONG WhichSpace; +PVOID Buffer; +ULONG Offset; +ULONG Length +``` + +The members of the structure can be interpreted differently by different bus drivers, but the members are typically defined as follows: + +**WhichSpace** +Specifies the configuration space. For information about values that can be specified for **WhichSpace**, see [**IRP\_MN\_READ\_CONFIG**](irp-mn-read-config.md). + +**Buffer** +Points to a buffer that contains the data to be written. The format of the buffer is bus-specific. + +**Offset** +Specifies an offset into the configuration space. + +**Length** +Specifies the number of bytes to be written. + +## Output Parameters + + +Returned in the I/O status block. + +## I/O Status Block + + +A bus driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS or to an appropriate error status such as STATUS\_INVALID\_PARAMETER\_*n*, STATUS\_NO\_SUCH\_DEVICE, or STATUS\_DEVICE\_NOT\_READY. + +On success, a bus driver sets **Irp->IoStatus.Information** to the number of bytes written. + +If a bus driver is unable to complete this request immediately, it can mark the IRP pending, return STATUS\_PENDING, and complete the IRP at a later time. + +Operation +--------- + +A bus driver handles this IRP for its child devices (child PDOs). + +Function and filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to **Irp->IoStatus.Status** and do not set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for the general rules for handling [Plug and Play minor IRPs](plug-and-play-minor-irps.md). + +**Sending This IRP** + +Typically, a function driver sends this IRP to the device stack to which it is attached and the IRP is handled by the parent bus driver. + +See [Handling IRPs](https://msdn.microsoft.com/library/windows/hardware/ff546847) for information about sending IRPs. The following steps apply specifically to this IRP: + +- Allocate a buffer from paged pool and initialize it with the data to be written. + +- Set the values in the next I/O stack location of the IRP: set **MajorFunction** to [**IRP\_MJ\_PNP**](irp-mj-pnp.md), set **MinorFunction** to **IRP\_MN\_WRITE\_CONFIG**, and set the appropriate values in **Parameters.ReadWriteConfig**. + +- Initialize **IoStatus.Status** to STATUS\_NOT\_SUPPORTED. + +- Deallocate the IRP and the buffer when they are no longer needed. + +Drivers must send this IRP from IRQL < DISPATCH\_LEVEL. + +A driver can access a bus's configuration space at DISPATCH\_LEVEL through a bus interface routine, if the parent bus driver exports such an interface. To get a bus interface, a driver sends an [**IRP\_MN\_QUERY\_INTERFACE**](irp-mn-query-interface.md) request to its parent bus driver. The driver then calls the appropriate routine returned in the interface. + +For example, to write configuration space from DISPATCH\_LEVEL a driver can call **IRP\_MN\_QUERY\_INTERFACE** during driver initialization to get the [**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707) interface from the parent bus driver. The driver sends the query IRP from IRQL PASSIVE\_LEVEL. Later, from code at IRQL DISPATCH\_LEVEL, the driver calls the appropriate routine returned in the interface, such as the **Interface.SetBusData** routine. + +Requirements +------------ + + ++++ + + + + + + +

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
+ +## See also + + +[**IRP\_MN\_QUERY\_INTERFACE**](irp-mn-query-interface.md) + +[**IRP\_MN\_READ\_CONFIG**](irp-mn-read-config.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP_MN_WRITE_CONFIG%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/irp-processing-examples.md b/windows-driver-docs-pr/kernel/irp-processing-examples.md new file mode 100644 index 0000000000..728f5c31cd --- /dev/null +++ b/windows-driver-docs-pr/kernel/irp-processing-examples.md @@ -0,0 +1,40 @@ +--- +title: IRP Processing Examples +author: windows-driver-content +description: IRP Processing Examples +ms.assetid: 1bf555c7-87fd-43c2-ab74-aa6f9133f808 +keywords: ["IRPs WDK kernel , processing examples"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# IRP Processing Examples + + +## + + +The following sections describe how IRPs might be processed in two prototype drivers. One is a prototype of a lowest-level driver for a mass storage device. The other is a prototype for an intermediate-level [*mirror driver*](https://msdn.microsoft.com/library/windows/hardware/ff556308#wdkgloss-mirror-driver), which would exist above the lowest-level driver in a stack of storage drivers. (A mirror driver duplicates all write requests to multiple driver, and alternates read requests among the duplicate drives.) + +[Processing IRPs in a Lowest-Level Driver](processing-irps-in-a-lowest-level-driver.md) + +[Processing IRPs in an Intermediate-Level Driver](processing-irps-in-an-intermediate-level-driver.md) + +You can also find more information in the following Microsoft Knowledge Base articles: + +[Article 320275: Different ways of handling IRPs – cheat sheet (Part 1 of 2)](https://go.microsoft.com/fwlink/?linkid=834615) + +[Article 326315: Different ways of handling IRPs – cheat sheet (Part 2 of 2)](https://go.microsoft.com/fwlink/?linkid=834616) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20IRP%20Processing%20Examples%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/isolating-pageable-code.md b/windows-driver-docs-pr/kernel/isolating-pageable-code.md new file mode 100644 index 0000000000..c816c8a1a4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/isolating-pageable-code.md @@ -0,0 +1,79 @@ +--- +title: Isolating Pageable Code +author: windows-driver-content +description: Isolating Pageable Code +ms.assetid: 86189154-606a-4df8-b3a9-040bbaffaa2f +keywords: ["pageable drivers WDK kernel , isolating code", "isolating pageable code", "spin locks WDK memory"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Isolating Pageable Code + + +## + + +A routine that uses a spin lock cannot be paged. However, in some cases you can isolate the operations that require a spin lock in a separate routine that will not be included in the pageable section. + +For example, consider the following fragment: + +``` +// PAGED_CODE(); + +KeInitializeEvent( &event, NotificationEvent, FALSE ); +irp = IoBuildDeviceIoControlRequest( IRP_MJ_DEVICE_CONTROL, + DeviceObject, + (PVOID) NULL, + 0, + (PVOID) NULL, + 0, + FALSE, + &event, + &ioStatus ); +if (irp) { + irpSp = IoGetNextIrpStackLocation( irp ); + irpSp->MajorFunction = IRP_MJ_FILE_SYSTEM_CONTROL; + irpSp->MinorFunction = IRP_MN_LOAD_FILE_SYSTEM; + status = IoCallDriver( DeviceObject, irp ); + if (status == STATUS_PENDING) { + (VOID) KeWaitForSingleObject( &event, + Executive, + KernelMode, + FALSE, + (PLARGE_INTEGER) NULL ); + } +} + +SPINLOCKUSE ! +KeAcquireSpinLock( &IopDatabaseLock, &irql ); +// Code inside spin lock ... + +DeviceObject->ReferenceCount--; + +if (!DeviceObject->ReferenceCount && !DeviceObject->AttachedDevice) { + //Unload the driver + . + . + . +} else { + KeReleaseSpinLock( &IopDatabaseLock, irql ); +} +``` + +The preceding routine could be made pageable (saving about 160 bytes) by moving the few lines of code that reference a spin lock into a separate routine. + +In addition, remember that driver code must not be marked as pageable if it calls any **Ke*Xxx*** support routines, such as [**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) or [**KeReleaseSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff553143), in which the *Wait* parameter is set to **TRUE**. Such a call returns with IRQL at DISPATCH\_LEVEL. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Isolating%20Pageable%20Code%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/kernel-dispatcher-objects.md b/windows-driver-docs-pr/kernel/kernel-dispatcher-objects.md new file mode 100644 index 0000000000..597bf4a4da --- /dev/null +++ b/windows-driver-docs-pr/kernel/kernel-dispatcher-objects.md @@ -0,0 +1,44 @@ +--- +title: Kernel Dispatcher Objects +author: windows-driver-content +description: Kernel Dispatcher Objects +ms.assetid: 884270d2-c102-46b0-a920-b93da580fd0e +keywords: ["kernel dispatcher objects WDK", "dispatcher objects WDK kernel", "synchronization WDK kernel , dispatcher objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel Dispatcher Objects + + +## + + +This section includes the following topics: + +[Introduction to Kernel Dispatcher Objects](introduction-to-kernel-dispatcher-objects.md) + +[Timer Objects and DPCs](timer-objects-and-dpcs.md) + +[Event Objects](event-objects.md) + +[Semaphore Objects](semaphore-objects.md) + +[Mutex Objects](mutex-objects.md) + +[Thread Objects](thread-objects.md) + +[Waits and APCs](waits-and-apcs.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel%20Dispatcher%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/kernel-macros--global-variables--and-opaque-structures.md b/windows-driver-docs-pr/kernel/kernel-macros--global-variables--and-opaque-structures.md new file mode 100644 index 0000000000..0f8f9a7129 --- /dev/null +++ b/windows-driver-docs-pr/kernel/kernel-macros--global-variables--and-opaque-structures.md @@ -0,0 +1,27 @@ +--- +title: Kernel Macros, Global Variables, and Opaque Structures +author: windows-driver-content +description: This section describes macros, global variables, and opaque structures. +ms.assetid: DD8860B7-C918-4121-8C22-83E96FC3E740 +--- + +# Kernel Macros, Global Variables, and Opaque Structures + + +This section describes macros, global variables, and opaque structures. It contains the following topics: + +[Windows kernel global variables](mm64bitphysicaladdress.md) + +[Windows kernel macros](mm-bad-pointer.md) + +[Windows kernel opaque structures](eprocess.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel%20Macros,%20Global%20Variables,%20and%20Opaque%20Structures%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/kernel-mode-driver-components.md b/windows-driver-docs-pr/kernel/kernel-mode-driver-components.md new file mode 100644 index 0000000000..7ec472b427 --- /dev/null +++ b/windows-driver-docs-pr/kernel/kernel-mode-driver-components.md @@ -0,0 +1,50 @@ +--- +title: Kernel-Mode Driver Components +author: windows-driver-content +description: Kernel-Mode Driver Components +ms.assetid: 79be2948-cc74-4f0b-8ffa-1e57f44d7b0c +keywords: ["kernel-mode drivers WDK , components", "kernel-mode drivers WDK , standard driver routines", "standard driver routines WDK kernel", "driver routines WDK kernel", "routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Driver Components + + +## + + +This section introduces the standard routines contained in kernel-mode drivers. Some of these *standard driver routines* are required; others are optional. The section also introduces *driver objects*, which contain pointers to each driver's standard routines. + +Some drivers interact with a system-supplied port driver or class driver that defines much of the driver's required functionality. For example, a SCSI miniport driver primarily interacts with the SCSI port driver. For such drivers, see the class-specific documentation for details of required and optional driver support. + +This section includes: + +[Introduction to Standard Driver Routines](introduction-to-standard-driver-routines.md) + +[Standard Driver Routine Requirements](standard-driver-routine-requirements.md) + +[Introduction to Driver Objects](introduction-to-driver-objects.md) + +[Writing a DriverEntry Routine](writing-a-driverentry-routine.md) + +[Writing a Reinitialize Routine](writing-a-reinitialize-routine.md) + +[Writing an AddDevice Routine](writing-an-adddevice-routine.md) + +[Writing Dispatch Routines](writing-dispatch-routines.md) + +[Writing an Unload Routine](writing-an-unload-routine.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel-Mode%20Driver%20Components%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/kernel-mode-managers-and-libraries.md b/windows-driver-docs-pr/kernel/kernel-mode-managers-and-libraries.md new file mode 100644 index 0000000000..ed049583a5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/kernel-mode-managers-and-libraries.md @@ -0,0 +1,55 @@ +--- +title: Kernel-Mode Managers and Libraries +author: windows-driver-content +description: Kernel-Mode Managers and Libraries +ms.assetid: 6361224b-ab7c-411f-91b5-48bf51ee634d +--- + +# Kernel-Mode Managers and Libraries + + +Windows has several components that export routines device drivers can call. The following topics discuss these components and provide links to further information about them and the routines they export: + +[Windows Kernel-Mode Object Manager](windows-kernel-mode-object-manager.md) + +[Windows Kernel-Mode Memory Manager](windows-kernel-mode-memory-manager.md) + +[Windows Kernel-Mode Process and Thread Manager](windows-kernel-mode-process-and-thread-manager.md) + +[Windows Kernel-Mode I/O Manager](windows-kernel-mode-i-o-manager.md) + +[Windows Kernel-Mode Plug and Play Manager](windows-kernel-mode-plug-and-play-manager.md) + +[Windows Kernel-Mode Power Manager](windows-kernel-mode-power-manager.md) + +[Windows Kernel-Mode Configuration Manager](windows-kernel-mode-configuration-manager.md) + +[Windows Kernel-Mode Kernel Transaction Manager](windows-kernel-mode-kernel-transaction-manager.md) + +[Windows Kernel-Mode Security Reference Monitor](windows-kernel-mode-security-reference-monitor.md) + +[Windows Kernel-Mode Kernel Library](windows-kernel-mode-kernel-library.md) + +[Windows Kernel-Mode Executive Support Library](windows-kernel-mode-executive-support-library.md) + +[Windows Kernel-Mode Run-Time Library](windows-kernel-mode-run-time-library.md) + +[Windows Kernel-Mode Safe String Library](windows-kernel-mode-safe-string-library.md) + +[Windows Kernel-Mode DMA Library](windows-kernel-mode-dma-library.md) + +[Windows Kernel-Mode HAL Library](windows-kernel-mode-hal-library.md) + +[Windows Kernel-Mode CLFS Library](windows-kernel-mode-clfs-library.md) + +[Windows Kernel-Mode WMI Library](windows-kernel-mode-wmi-library.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel-Mode%20Managers%20and%20Libraries%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/kernel-mode-power-management-components.md b/windows-driver-docs-pr/kernel/kernel-mode-power-management-components.md new file mode 100644 index 0000000000..3b3c9b97c2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/kernel-mode-power-management-components.md @@ -0,0 +1,38 @@ +--- +title: Kernel-Mode Power Management Components +author: windows-driver-content +description: Kernel-Mode Power Management Components +ms.assetid: 50587345-9a02-4b27-99af-a40cd73154f1 +keywords: ["power management WDK kernel , components"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Kernel-Mode Power Management Components + + +## + + +The following topics provide a brief introduction to the kernel-mode components that perform power management in Windows. + +## In this section + + +- [ACPI BIOS](acpi-bios.md) +- [Acpi.sys: The Windows ACPI Driver](acpi-driver.md) +- [Power Manager](power-manager.md) +- [Driver Role in Power Management](driver-role-in-power-management.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Kernel-Mode%20Power%20Management%20Components%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ktm-objects.md b/windows-driver-docs-pr/kernel/ktm-objects.md new file mode 100644 index 0000000000..dfd8bf2366 --- /dev/null +++ b/windows-driver-docs-pr/kernel/ktm-objects.md @@ -0,0 +1,59 @@ +--- +title: KTM Objects +author: windows-driver-content +description: KTM Objects +ms.assetid: 927a417b-35f5-49b8-85f3-7e6b1f5c0225 +keywords: ["Kernel Transaction Manager WDK , objects", "KTM WDK , objects", "objects WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# KTM Objects + + +The Kernel Transaction Manager (KTM) defines the following four object types: + +- [Transaction manager objects](transaction-manager-objects.md), which KTM uses to maintain memory-resident information about a [*log stream*](transaction-processing-terms.md#ktm-term-log-stream) for a [*transaction processing system*](transaction-processing-terms.md#ktm-term-transaction-processing-system) (TPS). + +- [Resource manager objects](resource-manager-objects.md), which represent the [*resource managers*](transaction-processing-terms.md#ktm-term-resource-manager) within a TPS. + +- [Transaction objects](transaction-objects.md), which represent the transactions that [*transactional clients*](transaction-processing-terms.md#ktm-term-transactional-client) create. + +- [Enlistment objects](enlistment-objects.md), which represent [*enlistments*](transaction-processing-terms.md#ktm-term-enlistment) that provide connections between transactions and resource managers. + +These four object types all have the following characteristics: + +- To create an object and obtain an object handle, [TPS components](understanding-tps-components.md) can call a *create* routine. + +- To obtain additional object handles to an existing object, TPS components can call an *open* routine. + +- To obtain information about an object, TPS components can call a *query* routine. + +- To close an object handle, TPS components call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). + +KTM assigns an identifier GUID to each object. For transaction objects, this identifier GUID is also known as a *unit of work (UOW) identifier* that clients can specify. TPS components can use the identifier GUIDs to track objects. A TPS component that creates an object can pass the object's identifier GUID to another component so that the latter component can open a handle to the object. + +Any TPS component that uses KTM can call [**ZwEnumerateTransactionObject**](https://msdn.microsoft.com/library/windows/hardware/ff566450) to enumerate KTM objects, but most components do not have to call this routine. + +This section contains the following topics: + +[Transaction Manager Objects](transaction-manager-objects.md) + +[Resource Manager Objects](resource-manager-objects.md) + +[Transaction Objects](transaction-objects.md) + +[Enlistment Objects](enlistment-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20KTM%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/legacy-i-o-programming.md b/windows-driver-docs-pr/kernel/legacy-i-o-programming.md new file mode 100644 index 0000000000..7cb0f40503 --- /dev/null +++ b/windows-driver-docs-pr/kernel/legacy-i-o-programming.md @@ -0,0 +1,25 @@ +--- +title: Legacy I/O Programming +author: windows-driver-content +description: Legacy I/O Programming +ms.assetid: 9ab9fef0-7939-40dd-9b56-9c6f5902f36a +--- + +# Legacy I/O Programming + + +The following I/O programming techniques are not recommended for Microsoft Windows 2000 and later versions of Windows but are provided for legacy drivers: + +[Accessing Device Configuration Space](accessing-device-configuration-space.md) + +[Using Controller Objects](using-controller-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Legacy%20I/O%20Programming%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/levels-of-support-for-pnp.md b/windows-driver-docs-pr/kernel/levels-of-support-for-pnp.md new file mode 100644 index 0000000000..dd72feb779 --- /dev/null +++ b/windows-driver-docs-pr/kernel/levels-of-support-for-pnp.md @@ -0,0 +1,67 @@ +--- +title: Levels of Support for PnP +author: windows-driver-content +description: Levels of Support for PnP +ms.assetid: 33e0b4c6-858c-4822-ba49-38eb87a5923d +keywords: ["PnP WDK kernel , device support", "Plug and Play WDK kernel , device support", "full PnP WDK kernel", "partial PnP WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Levels of Support for PnP + + +## + + +The extent to which a device supports PnP depends on the PnP support in both the device hardware and the device drivers (see the following table). + + +++++ + + + + + + + + + + + + + + + + + + + +
PnP driverNon-PnP driver

PnP Device

Full PnP

No PnP

Non-PnP Device

Possible partial PnP

No PnP

+ +  + +Any device that supports PnP should have PnP support in its drivers. + +A non-PnP device can have some PnP capability if it is driven by a PnP driver. For example, an ISA sound card or an EISA network card can be manually installed and then a PnP driver can treat the card like a PnP device. + +If a driver does not support PnP, its devices behave as non-PnP devices regardless of any hardware PnP support. A non-PnP driver can constrain the PnP and power management capabilities of the whole system. + +*Legacy drivers* (that is, drivers written before the operating system supported PnP) continue to work as they did previously, without any PnP capability. New drivers should include PnP support. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Levels%20of%20Support%20for%20PnP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/libraries-and-headers.md b/windows-driver-docs-pr/kernel/libraries-and-headers.md new file mode 100644 index 0000000000..959d60fc00 --- /dev/null +++ b/windows-driver-docs-pr/kernel/libraries-and-headers.md @@ -0,0 +1,37 @@ +--- +title: Libraries and Headers +author: windows-driver-content +description: Libraries and Headers +ms.assetid: 0d4d0273-775f-4cbb-8b7f-63b22f3ccdae +--- + +# Libraries and Headers + + +Kernel-mode drivers use the native system services routines by calling the **Nt** and **Zw** entry points in the Ntoskrnl.exe dynamic link library (DLL). This DLL contains the actual implementations of these routines. To access these entry points, a driver statically links to the Ntoskrnl.lib library, which is available in the Windows Driver Kit (WDK). The routines that are implemented in Ntoskrnl.lib are stubs that dynamically link to the entry points in Ntoskrnl.exe at run time. + +The WDK documentation describes some, but not all, of the **Zw** entry points in Ntoskrnl.exe. For descriptions of the **Zw** routines that can be called by drivers, see [ZwXxx Routines](https://msdn.microsoft.com/library/windows/hardware/ff567122). + +Most of the documented **Zw** routines are defined in the Wdm.h header file in the WDK, but a few are defined in other header files, such as Ntddk.h and Ntifs.h. + +Typically, user-mode applications do not call the **Nt** and **Zw** routines. Instead, an application might call a Win32 routine, such as [CreateFile](http://go.microsoft.com/fwlink/p/?linkid=152795), which then calls a native system services routine, such as [NtCreateFile](http://go.microsoft.com/fwlink/p/?linkid=157250) or [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424), to perform the requested operation. However, a user-mode application might directly call an **Nt** or **Zw** routine to perform an operation that is not supported by the Win32 routines. + +User-mode applications use the native system services routines by calling the entry points in the Ntdll.dll dynamic link library. These entry points convert calls to **Nt** and **Zw** routines into system calls that are trapped to kernel mode. To access these entry points, a user-mode application statically links to the Ntdll.lib library, which is available in the WDK. The routines that are implemented in Ntdll.lib are stubs that dynamically link to the entry points in Ntdll.dll at run time. + +The Windows SDK documentation describes some, but not all, of the **Nt** entry points in Ntdll.lib. Most of the documented **Nt** routines are defined in the Winternl.h header file in the Windows SDK. This documentation makes little mention of the **Zw** entry points, and no header files in the Windows SDK contain definitions of **Zw** routines. + +With a couple of minor exceptions, each entry point in Ntdll.dll for an **Nt** routine has a matching entry point for a **Zw** routine. The documentation for the WDK and Windows SDK recommends that application developers avoid calling undocumented **Nt** entry points, and warns that the **Zw** entry points might disappear from Ntdll.dll in a future version of Windows. Application developers who call the **Zw** routines from user mode should be prepared for this occurrence. + +For descriptions of the **Nt** routines that can be called by applications, see [Winternl](http://go.microsoft.com/fwlink/p/?linkid=157253), [Files](http://go.microsoft.com/fwlink/p/?linkid=157254), and [Miscellaneous Low-Level Client Support](http://go.microsoft.com/fwlink/p/?linkid=157255). Some reference pages for **Nt** routines in the Windows SDK documentation label the routines as "deprecated" and advise readers to use the equivalent Win32 routines instead of the deprecated **Nt** routines. + +A user-mode application cannot call the entry points in Ntoskrnl.exe, and a kernel-mode driver cannot call the entry points in Ntdll.dll. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Libraries%20and%20Headers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/life-cycle-of-an-object.md b/windows-driver-docs-pr/kernel/life-cycle-of-an-object.md new file mode 100644 index 0000000000..02f3e89fd7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/life-cycle-of-an-object.md @@ -0,0 +1,72 @@ +--- +title: Life Cycle of an Object +author: windows-driver-content +description: Life Cycle of an Object +ms.assetid: e81bfce6-27c4-4916-adc8-9c014d02bee7 +keywords: ["object life cycles WDK kernel", "life cycles WDK objects", "referencing objects", "object reference counts WDK kernel", "temporary objects WDK kernel", "permanent objects WDK kernel", "reference counts WDK objects", "freed objects WDK kernel", "object temporary status WDK kernel", "object permanent status WDK kernel", "automatic object deletions WDK kernel", "object tracking WDK kernel", "open object handles WDK kernel", "counting references WDK objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Life Cycle of an Object + + +## + + +This topic describes the "life cycle" of an object, that is, how objects are referenced and tracked by the object manager. This topic also describes how to make objects temporary or permanent. + +### Object Reference Count + +The object manager maintains a count of the number of references to an object. When an object is created, the object manager sets the object's reference count to one. Once that counter falls to zero, the object is freed. + +Drivers must ensure that the object manager has an accurate reference count for any objects they manipulate. An object that is released prematurely can cause the system to crash. An object whose reference count is mistakenly high will never be freed. + +Objects can be referenced either by handle, or by pointer. In addition to the reference count, the object manager maintains a count of the number of open handles to an object. Each routine that opens a handle increases both the object reference count and the object handle count by one. Each call to such a routine must be matched with a corresponding call to [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). For more information, see [Object Handles](object-handles.md). + +Within kernel mode, objects can be referenced by a pointer to the object. Routines that return pointers to objects, such as [**IoGetAttachedDeviceReference**](https://msdn.microsoft.com/library/windows/hardware/ff549145), increase the reference count by one. Once the driver is done using the pointer, it must call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) to decrease the reference count by one. + +The following routines all increase the reference count of an object by one: + +[**ExCreateCallback**](https://msdn.microsoft.com/library/windows/hardware/ff544560) + +[**IoGetAttachedDeviceReference**](https://msdn.microsoft.com/library/windows/hardware/ff549145) + +[**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198) + +[**IoWMIOpenBlock**](https://msdn.microsoft.com/library/windows/hardware/ff550453) + +[**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) + +[**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) + +[**ObReferenceObjectByPointer**](https://msdn.microsoft.com/library/windows/hardware/ff558686) + +Each call that is made to any of the preceding routines must be matched with a corresponding call to **ObDereferenceObject**. + +The **ObReferenceObject** and **ObReferenceObjectByPointer** routines are provided so that drivers can increase the reference count of a known object pointer by one. **ObReferenceObject** simply increases the reference count. **ObReferenceObjectByPointer** does an access check before increasing the reference count. + +The **ObReferenceObjectByHandle** routine receives an object handle and supplies a pointer to the underlying object. It too increases the reference count by one. + +### Temporary and Permanent Objects + +Most objects are *temporary*; they exist as long as they are in use, and then they are freed by the object manager. Objects can be created that are *permanent*. If an object is permanent, the object manager itself holds a reference to the object. Thus, its reference count remains greater than zero, and the object is not freed when it is no longer in use. + +A temporary object can be accessed by name only as long as its handle count is nonzero. Once the handle count decrements to zero, the object's name is removed from the object manager's namespace. Such objects can still be accessed by pointer as long as their reference count remains greater than zero. Permanent objects can be accessed by name as long as they exist. + +An object can be made permanent at the time of its creation by specifying the OBJ\_PERMANENT attribute in the [**OBJECT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff557749) structure for the object. For more information, see [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804). + +To make a permanent object temporary, use the [**ZwMakeTemporaryObject**](https://msdn.microsoft.com/library/windows/hardware/ff566477) routine. This routine causes an object to be automatically deleted once it is no longer in use. (If the object has no open handles, the object's name is immediately removed from the object manager's namespace. The object itself remains until the reference count falls to zero.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Life%20Cycle%20of%20an%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/local-and-global-ms-dos-device-names.md b/windows-driver-docs-pr/kernel/local-and-global-ms-dos-device-names.md new file mode 100644 index 0000000000..7ee5545149 --- /dev/null +++ b/windows-driver-docs-pr/kernel/local-and-global-ms-dos-device-names.md @@ -0,0 +1,84 @@ +--- +title: Local and Global MS-DOS Device Names +author: windows-driver-content +description: Local and Global MS-DOS Device Names +ms.assetid: bfb7e41c-0f80-4cb9-b036-d1b44473f9fb +keywords: ["MS-DOS device names WDK kernel", "local MS-DOS device names WDK kernel", "global MS-DOS device names WDK kernel", "DosDevices contexts WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Local and Global MS-DOS Device Names + + +## + + +The Microsoft Windows 2000 and later versions of the Windows NT-based operating system maintain multiple versions of the **DosDevices** directory. + +On these operating systems, there is one *global* **\\DosDevices** directory and multiple *local* **\\DosDevices** directories. The global **\\DosDevices** directory holds the MS-DOS device names that are visible system-wide. A local **\\DosDevices** directory holds MS-DOS device names that are visible only in a particular *local* **DosDevices** *context*. + +The local **DosDevices** contexts are as follows. + +- On Windows XP and later, each logon session has its own local **DosDevices** context. System threads, and any thread that is running as the LocalSystem user, do not run in a local **DosDevices** context. + +- On Windows 2000, each terminal server session has its own local **DosDevices** context. Any thread that is running as part of the console session does not run in a local **DosDevices** context. + +Each thread has a current **DosDevices** context, which can change over the lifetime of a thread. A thread that does not run in a local **DosDevices** context is said to run in the *global* **DosDevices** *context*. Thus, the system account runs in the global **DosDevices** context. + +If a thread is currently running in a local **DosDevices** context, any MS-DOS device names that it creates are created only in the local **DosDevices** directory. Thus, threads that are running in a local **DosDevices** context cannot affect the MS-DOS device names that are visible to threads that are running in another local **DosDevices** context or in the global **DosDevices** context. For example, if a user on Windows XP or later mounts a network drive as **X:**, this does not affect the meaning of **X:** for any other user, or for the system as a whole. + +On Windows XP and later, when the object manager looks up a name in **\\DosDevices**, it first searches the local **\\DosDevices** directory, and then the global **\\DosDevices** directory. If the name exists in both places, the local name shadows the global name. + +On Windows 2000, whenever a new terminal server session is initiated, the system builds local \\**DosDevices** directory by copying the global **\\DosDevices** directory. Any subsequent changes to the global directory are not propagated to the local directory. + +A driver that must create its MS-DOS device names in the global **\\DosDevices** directory can do so by creating its symbolic links in a standard driver routine that is guaranteed to run in a system thread context, such as **DriverEntry**. Alternatively, the global **\\DosDevices** directory is available as **\\DosDevices\\Global**; drivers can use a name of the **\\DosDevices\\Global\\***DosDeviceName* to specify a name in the global directory. + +Note that **\\DosDevices\\Global** does not exist on platforms that do not support local and global versions of **\\DosDevices**, such as Windows 98/Me. The following code example creates a global symbolic link that works on Windows 98/Me as well as Windows 2000 and later operating systems: + +``` +UNICODE_STRING deviceName; // Already initialized. +UNICODE_STRING symbolicLinkName; // Initializing below. +NTSTATUS status; + +if (IoIsWdmVersionAvailable(1, 0x10)) { + // We're on Windows 2000 or later, so we use \DosDevices\Global. + + RtlInitUnicodeString(&symbolicLinkName, L"\\DosDevices\\Global\\SymbolicLinkName"); + +} else { + // Windows 98/Me. We just use DosDevices. + + RtlInitUnicodeString(&symbolicLinkName, L"\\DosDevices\\SymbolicLinkName"); +} + +status = IoCreateSymbolicLink(&symbolicLinkName, &deviceName); +if (!NT_SUCCESS(status)) { + /* Symbolic link creation failed. Handle error appropriately. */ +} +``` + +A driver can create MS-DOS device names in a local **\\DosDevices** directories by creating the symbolic link in response to an IOCTL. When a thread in a particular local **DosDevices** context sends the IOCTL, the driver's *DispatchDeviceControl* is called from within the current thread context. + +For more information about the context in which a standard driver routine runs, see [Dispatch Routines and IRQLs](dispatch-routines-and-irqls.md). + +The system distinguishes local **\\DosDevices** directories as follows: + +- On Windows XP and later, local **\\DosDevices** directories are identified by the **AuthenticationID** for the logon session's access token. For more information about the **AuthenticationID**, see the description of the **TOKEN\_STATISTICS** structure in the Microsoft Windows SDK documentation. + +- On Windows 2000, local **\\DosDevices** directories are identified by the **SessionId** for the terminal server session. For more information about the **SessionId**, see the description of the **WTS\_SESSION\_INFO** structure in the Windows SDK documentation. + +Windows NT 4.0 Terminal Server Edition supports local \\**DosDevices** directories in the exact same manner as Windows 2000. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Local%20and%20Global%20MS-DOS%20Device%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/localizing-mof-files.md b/windows-driver-docs-pr/kernel/localizing-mof-files.md new file mode 100644 index 0000000000..1e849847cc --- /dev/null +++ b/windows-driver-docs-pr/kernel/localizing-mof-files.md @@ -0,0 +1,30 @@ +--- +title: Localizing MOF Files +author: windows-driver-content +description: Localizing MOF Files +ms.assetid: 9ca27901-04aa-47b4-a2a7-aee071f7312a +keywords: ["MOF files WDK WMI", "localizing MOF files"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Localizing MOF Files + + +## + + +Since WMI property qualifiers are often displayable strings, Windows XP and later versions of the operating system provide a mechanism for localizing these qualifiers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Localizing%20MOF%20Files%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/locking-pageable-code-or-data.md b/windows-driver-docs-pr/kernel/locking-pageable-code-or-data.md new file mode 100644 index 0000000000..df5416640d --- /dev/null +++ b/windows-driver-docs-pr/kernel/locking-pageable-code-or-data.md @@ -0,0 +1,108 @@ +--- +title: Locking Pageable Code or Data +author: windows-driver-content +description: Locking Pageable Code or Data +ms.assetid: b99b6af3-b4b1-4fd6-ac73-27c1068183a4 +keywords: ["pageable drivers WDK kernel , locking code or data", "locking WDK pageable drivers", "restoring pageable status", "resident code WDK pageable drivers", "isolating pageable code", "PAGE keyword WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Locking Pageable Code or Data + + +## + + +Certain kernel-mode drivers, such as the serial and parallel drivers, do not have to be memory-resident unless the devices they manage are open. However, as long as there is an active connection or port, some part of the driver code that manages that port must be resident to service the device. When the port or connection is not being used, the driver code is not required. In contrast, a driver for a disk that contains system code, application code, or the system paging file must always be memory-resident because the driver constantly transfers data between its device and the system. + +A driver for a sporadically used device (such as a modem) can free system space when the device it manages is not active. If you place in a single section the code that must be resident to service an active device, and if your driver locks the code in memory while the device is being used, this section can be designated as pageable. When the driver's device is opened, the operating system brings the pageable section into memory and the driver locks it there until no longer needed. + +The system CD audio driver code uses this technique. Code for the driver is grouped into pageable sections according to the manufacturer of CD device. Certain brands might never be present on a given system. Also, even if a CD-ROM exists on a system, it might be accessed infrequently, so grouping code into pageable sections by CD type makes sure that code for devices that do not exist on a particular computer will never be loaded. However, when the device is accessed, the system loads the code for the appropriate CD device. Then the driver calls the [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601) routine, as described below, to lock its code into memory while its device is being used. + +To isolate the pageable code into a named section, mark it with the following compiler directive: + +**\#pragma alloc\_text(PAGE*Xxx***, *RoutineName***)** + +The name of a pageable code section must start with the four letters "PAGE" and can be followed by up to four characters (represented here as ***Xxx***) to uniquely identify the section. The first four letters of the section name (that is, "PAGE") must be capitalized. The *RoutineName* identifies an entry point to be included in the pageable section. + +The shortest valid name for a pageable code section in a driver file is simply PAGE. For example, the pragma directive in the following code example identifies `RdrCreateConnection` as an entry point in a pageable code section named PAGE. + +``` +#ifdef ALLOC_PRAGMA +#pragma alloc_text(PAGE, RdrCreateConnection) +#endif +``` + +To make pageable driver code resident and locked in memory, a driver calls [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601), passing an address (typically the entry point of a driver routine) that is in the pageable code section. **MmLockPagableCodeSection** locks in the whole contents of the section that contains the routine referenced in the call. In other words, this call makes every routine associated with the same PAGE*Xxx* identifier resident and locked in memory. + +**MmLockPagableCodeSection** returns a handle to be used when unlocking the section (by calling the [**MmUnlockPagableImageSection**](https://msdn.microsoft.com/library/windows/hardware/ff556377) routine) or when the driver must lock the section from additional locations in its code. + +A driver can also treat seldom-used data as pageable so that it, too, can be paged out until the device it supports is active. For example, the system mixer driver uses pageable data. The mixer device has no asynchronous I/O associated with it, so this driver can make its data pageable. + +The name of a pageable data section must start with the four letters "PAGE" and can be followed by up to four characters to uniquely identify the section. The first four letters of the section name (that is, "PAGE") must be capitalized. + +Avoid assigning identical names to code and data sections. To make source code more readable, driver developers typically assign the name PAGE to the pageable code section because this name is short and it might appear in numerous alloc\_text pragma directives. Longer names are then assigned to any pageable data sections (for example, PAGEDATA for data\_seg, PAGEBSS for bss\_seg, and so on) that the driver might require. + +For example, the first two pragma directives in the following code example define two pageable data sections, PAGEDATA and PAGEBSS. PAGEDATA is declared using the data\_seg pragma directive and contains initialized data. PAGEBSS is declared using the bss\_seg pragma directive and contains uninitialized data. + +``` +#pragma data_seg("PAGEDATA") +#pragma bss_seg("PAGEBSS") + +INT Variable1 = 1; +INT Variable2; + +CHAR Array1[64*1024] = { 0 }; +CHAR Array2[64*1024]; + +#pragma data_seg() +#pragma bss_seg() +``` + +In this code example, `Variable1` and `Array1` are explicitly initialized and are therefore placed in the PAGEDATA section. `Variable2` and `Array2` are implicitly zero-initialized and are placed in the PAGEBSS section. + +Implicitly initializing global variables to zero reduces the size of the on-disk executable file and is preferred over explicit initialization to zero. Explicit zero-initialization should be avoided except in cases where it is required in order to place a variable in a specific data section. + +To make a data section memory-resident and lock it in memory, a driver calls [**MmLockPagableDataSection**](https://msdn.microsoft.com/library/windows/hardware/ff554607), passing a data item that appears in the pageable data section. **MmLockPagableDataSection** returns a handle to be used in subsequent locking or unlocking requests. + +To restore a locked section's pageable status, call [**MmUnlockPagableImageSection**](https://msdn.microsoft.com/library/windows/hardware/ff556377), passing the handle value returned by [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601) or [**MmLockPagableDataSection**](https://msdn.microsoft.com/library/windows/hardware/ff554607), as appropriate. A driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine must call **MmUnlockPagableImageSection** to release each handle it has obtained for lockable code and data sections. + +Locking a section is an expensive operation because the memory manager must search its loaded module list before locking the pages into memory. If a driver locks a section from many locations in its code, it should use the more efficient [**MmLockPagableSectionByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff554610) after its initial call to **MmLockPagable*Xxx*Section**. + +The handle passed to **MmLockPagableSectionByHandle** is the handle returned by the earlier call to **MmLockPagableCodeSection** or **MmLockPagableDataSection**. + +The memory manager maintains a count for each section handle and increments this count every time that a driver calls **MmLockPagable*Xxx*** for that section. A call to **MmUnlockPagableImageSection** decrements the count. While the counter for any section handle is nonzero, that section remains locked in memory. + +The handle to a section is valid as long as its driver is loaded. Therefore, a driver should call **MmLockPagable*Xxx*Section** only one time. If the driver requires additional locking calls, it should use **MmLockPagableSectionByHandle**. + +If a driver calls any **MmLockPagable*Xxx*** routine for a section that is already locked, the memory manager increments the reference count for the section. If the section is paged out when the lock routine is called, the memory manager pages in the section and sets its reference count to one. + +Using this technique minimizes the driver's effect on system resources. When the driver runs, it can lock into memory the code and data that must be resident. When there are no outstanding I/O requests for its device, (that is, when the device is closed or if the device was never opened), the driver can unlock the same code or data, making it available to be paged out. + +However, after a driver has connected interrupts, any driver code that can be called during interrupt processing always must be memory resident. While some device drivers can be made pageable or locked into memory on demand, some core set of such a driver's code and data must be permanently resident in system space. + +Consider the following implementation guidelines for locking a code or data section. + +- The primary use of the **Mm(Un)Lock*Xxx*** routines is to enable normally nonpaged code or data to be made pageable and brought in as nonpaged code or data. Drivers such as the serial driver and the parallel driver are good examples: if there are no open handles to a device such a driver manages, parts of code are not needed and can remain paged out. The redirector and server are also good examples of drivers that can use this technique. When there are no active connections, both of these components can be paged out. + +- The whole pageable section is locked into memory. + +- One section for code and one for data per driver is efficient. Many named, pageable sections are generally inefficient. + +- Keep purely pageable sections and paged but locked-on-demand sections separate. + +- Remember that **MmLockPagableCodeSection** and **MmLockPagableDataSection** should not be frequently called. These routines can cause heavy I/O activity when the memory manager loads the section. If a driver must lock a section from several locations in its code, it should use **MmLockPagableSectionByHandle**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Locking%20Pageable%20Code%20or%20Data%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/logging-errors.md b/windows-driver-docs-pr/kernel/logging-errors.md new file mode 100644 index 0000000000..d289bcaf76 --- /dev/null +++ b/windows-driver-docs-pr/kernel/logging-errors.md @@ -0,0 +1,40 @@ +--- +title: Logging Errors +author: windows-driver-content +description: Logging Errors +ms.assetid: 02d77bdf-f94d-47c6-8824-d5643cf4a89c +keywords: ["errors WDK kernel", "logs WDK kernel", "logging errors WDK kernel", "log files WDK kernel", "messages WDK error logs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Logging Errors + + +## + + +Drivers, like most Microsoft Windows system components, can log errors to the system event log. The errors are visible in the Event Viewer. + +![screen shot of the event viewer main window](images/event-viewer.png) + +This section includes the following topics: + +[Writing to the System Event Log](writing-to-the-system-event-log.md) + +[Defining Custom Error Types](defining-custom-error-types.md) + +[Registering as a Source of Error Messages](registering-as-a-source-of-error-messages.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Logging%20Errors%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/maintaining-cache-coherency.md b/windows-driver-docs-pr/kernel/maintaining-cache-coherency.md new file mode 100644 index 0000000000..5923d9a139 --- /dev/null +++ b/windows-driver-docs-pr/kernel/maintaining-cache-coherency.md @@ -0,0 +1,33 @@ +--- +title: Maintaining Cache Coherency +author: windows-driver-content +description: Maintaining Cache Coherency +ms.assetid: 70b4b313-ce33-4562-aa0d-127a91706409 +keywords: ["I/O WDK kernel , cache coherency", "cache coherency WDK kernel", "integrity WDK I/O", "data transfers WDK kernel , cache coherency", "transferring data WDK kernel , cache coherency", "memory management WDK kernel , cache coherency", "processor cache WDK I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Maintaining Cache Coherency + + +When a driver is transferring data between system memory and its device, data can be cached in one or more processor caches and/or in the system DMA controller's cache. Drivers that use DMA or PIO to service read/write IRPs or any device I/O control request that requires a DMA or PIO data transfer operation should ensure the integrity of possibly cached data during transfer operations. This section explains how to do so. + +This section contains the following topics: + +[Flushing Cached Data during DMA Operations](flushing-cached-data-during-dma-operations.md) + +[Flushing Cached Data during PIO Operations](flushing-cached-data-during-pio-operations.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Maintaining%20Cache%20Coherency%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/making-an-isr-active-or-inactive.md b/windows-driver-docs-pr/kernel/making-an-isr-active-or-inactive.md new file mode 100644 index 0000000000..580531487b --- /dev/null +++ b/windows-driver-docs-pr/kernel/making-an-isr-active-or-inactive.md @@ -0,0 +1,35 @@ +--- +title: Making an ISR Active or Inactive +author: windows-driver-content +description: Starting with Windows 8, a driver can call the IoReportInterruptActive or IoReportInterruptInactive routine to make a registered interrupt service routine (ISR) active or inactive. +ms.assetid: 788D9341-D1F8-4126-8C30-AA49DE27F4BB +--- + +# Making an ISR Active or Inactive + + +Starting with Windows 8, a driver can call the [**IoReportInterruptActive**](https://msdn.microsoft.com/library/windows/hardware/jj158875) or [**IoReportInterruptInactive**](https://msdn.microsoft.com/library/windows/hardware/jj158876) routine to make a registered interrupt service routine (ISR) active or inactive. + +To register an ISR, and to connect the ISR to an interrupt or a set of interrupts, the driver calls the [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) routine. After the ISR is registered, the driver can use **IoReportInterruptActive** and **IoReportInterruptInactive** to perform lightweight (or "soft") connect and disconnect operations that leave the ISR's registration unchanged. **IoReportInterruptInactive** disables calls to the ISR by soft-disconnecting the associated interrupt or interrupts. **IoReportInterruptActive** soft-connects these interrupts to enable calls to the ISR. + +For example, a driver might call **IoReportInterruptInactive** to soft-disconnect a set of interrupts before a device exits the D0 power state, and call **IoReportInterruptActive** to soft-connect these interrupts after the device reenters D0. In principle, a driver might instead call [**IoDisconnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff549093) before the device exits D0, and call **IoConnectInterruptEx** after the device reenters D0. However, **IoReportInterrupt*Xxx*** calls are faster than than **IoConnectInterruptEx** and **IoDisconnectInterruptEx** calls. In contrast to **IoConnectInterruptEx** and **IoDisconnectInterruptEx** calls, which might fail for a variety of reasons (for example, insufficient system resources), **IoReportInterrupt*Xxx*** calls rarely, if ever, fail. Additionally, the **IoReportInterrupt*Xxx*** routines can be called at IRQL <= DISPATCH\_LEVEL, whereas **IoConnectInterruptEx** and **IoDisconnectInterruptEx** can be called only at PASSIVE\_LEVEL. + +By default, the ISR is active (and calls to the ISR are enabled) after **IoConnectInterruptEx** successfully registers the ISR. + +Calls to **IoReportInterruptInactive** and **IoReportInterruptActive** are optional. If a driver never calls these routines, the registered ISR stays active until the driver calls the [**IoDisconnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff549093) routine to unregister the ISR. + +The driver should configure the device to issue interrupts only when the ISR for these interrupts is active. Failure to prevent a device from issuing interrupts when the ISR is inactive might cause system instability. For example, if a device shares a level-triggered interrupt line with other devices, and the device issues interrupt requests when the ISR is inactive, the ISRs for the other devices on the line will not acknowledge the interrupt and the interrupt will continue to fire. Before calling **IoReportInterruptInactive**, the driver should configure the device to stop issuing interrupts. After calling **IoReportInterruptActive**, the driver should configure the device to start issuing interrupts. + +To unregister an ISR, a driver can call **IoDisconnectInterruptEx** regardless of whether the ISR is currently active or inactive. + +An **IoReportInterruptActive** call that occurs when the ISR is already active has no effect, but is not treated as an error. Similarly, an **IoReportInterruptInactive** call that occurs when the ISR is already inactive has no effect, but is not treated as an error. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Making%20an%20ISR%20Active%20or%20Inactive%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/making-driver-code-or-data-pageable.md b/windows-driver-docs-pr/kernel/making-driver-code-or-data-pageable.md new file mode 100644 index 0000000000..8331673c80 --- /dev/null +++ b/windows-driver-docs-pr/kernel/making-driver-code-or-data-pageable.md @@ -0,0 +1,40 @@ +--- +title: Making Driver Code or Data Pageable +author: windows-driver-content +description: Making Driver Code or Data Pageable +ms.assetid: c4ffd222-8ea5-48df-9c79-7d68e5462b3e +keywords: ["memory management WDK kernel , pageable drivers", "pageable drivers WDK kernel , setting up"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Making Driver Code or Data Pageable + + +## + + +To make a driver routine pageable, you must make sure that it runs at IRQL < DISPATCH\_LEVEL and that it does not acquire any spin locks. + +This section contains the following topics: + +[Detecting Code That Can Be Pageable](detecting-code-that-can-be-pageable.md) + +[Isolating Pageable Code](isolating-pageable-code.md) + +[Locking Pageable Code or Data](locking-pageable-code-or-data.md) + +[Paging an Entire Driver](paging-an-entire-driver.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Making%20Driver%20Code%20or%20Data%20Pageable%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/making-drivers-pageable.md b/windows-driver-docs-pr/kernel/making-drivers-pageable.md new file mode 100644 index 0000000000..e9c43192f2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/making-drivers-pageable.md @@ -0,0 +1,44 @@ +--- +title: Making Drivers Pageable +author: windows-driver-content +description: Making Drivers Pageable +ms.assetid: 0b3c1e00-2416-4534-9934-bb05f91c7482 +keywords: ["memory management WDK kernel , pageable drivers", "pageable drivers WDK kernel", "pageable drivers WDK kernel , about pageable drivers", "paged out drivers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Making Drivers Pageable + + +## + + +By default, the linker assigns names such as ".text" and ".data" to the code and data sections of a driver image file. When the driver is loaded, the I/O manager makes these sections nonpaged. A nonpaged section is always memory-resident. + +A driver developer has the option to make designated parts of a driver pageable so that Windows can move these parts to the paging file when they are not in use. To make a code or data section pageable, the driver developer assigns a name that begins with "PAGE" to the section. The I/O manager checks the names of the sections when it loads a driver. If a section name begins with "PAGE", the I/O manager makes the section pageable. + +Code that runs at IRQL >= DISPATCH\_LEVEL must be memory-resident. That is, this code must be either in a nonpageable segment, or in a pageable segment that is locked in memory. If code that is running at IRQL >= DISPATCH\_LEVEL causes a page fault, a bug check occurs. Drivers can use the [**PAGED\_CODE**](https://msdn.microsoft.com/library/windows/hardware/ff558773) macro to verify that pageable functions are called only at appropriate IRQLs. + +If a code or data section is pageable, the driver can lock the section in memory by calling the [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601) or [**MmLockPagableDataSection**](https://msdn.microsoft.com/library/windows/hardware/ff554607) routine. The section remains locked until the driver calls the [**MmUnlockPagableImageSection**](https://msdn.microsoft.com/library/windows/hardware/ff556377) routine to unlock it. While the pageable section is locked, it behaves the same as a nonpaged section. + +For information about how to assign names to code and data sections, see [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601) and [**MmLockPagableDataSection**](https://msdn.microsoft.com/library/windows/hardware/ff554607). + +This section includes the following topics: + +[When Should Code and Data Be Pageable?](when-should-code-and-data-be-pageable-.md) + +[Making Driver Code or Data Pageable](making-driver-code-or-data-pageable.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Making%20Drivers%20Pageable%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-device-performance-states.md b/windows-driver-docs-pr/kernel/managing-device-performance-states.md new file mode 100644 index 0000000000..7df2e2a8a2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-device-performance-states.md @@ -0,0 +1,84 @@ +--- +title: Managing Device Performance States +author: windows-driver-content +description: Managing Device Performance States +ms.assetid: 5a4cc09a-e86e-4e5a-98b2-0351b253b5b6 +keywords: ["power management WDK kernel , device performance states", "device performance states WDK power management", "performance states WDK power management", "custom power settings WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Device Performance States + + +Windows Vista features an enhanced power management infrastructure that makes it possible for driver stacks to better manage the power policy of their devices. Drivers can register to be notified when system-defined power settings change or when system power events occur. A device power policy owner can use these notifications to appropriately adjust the power usage of its devices. In addition, you can create custom power settings that provide access to device-specific power and performance features, which can be tightly-integrated into system power policy. The following are the two primary approaches to integrate device performance states and power-saving behaviors with system power policy. + +[Creating Custom Power Settings for a Device](#creating-custom-power-settings-for-a-device) + +[Registering to be Notified of a Change to the Active Power Scheme, Power Scheme Personality, or Power Source](#registering-to-be-notified-of-a-change-to-the-active-power-scheme) + +### Creating Custom Power Settings for a Device + +You can define custom power settings that can be used to configure device performance states or power-saving behaviors. Information about the custom power settings is saved and managed by the power manager. Other components in the system—such as device drivers, services, or applications—can register to be notified when the value of a custom power setting changes. In general, devices that have the capability to tradeoff performance with power consumption should have corresponding custom power settings. Creating custom power settings is the most flexible approach to tightly integrate power consumption with system power policy and provides the following additional benefits: + +- A custom user interface is not required to make custom power settings accessible to a user. All power settings, including custom power settings, are presented to the user on the **Advanced Settings** page of the **Power Options** Control Panel. + +- Users and system administrators can easily script the configuration of custom power settings by using Powercfg.exe, the power management command-line tool. + +- Optionally, a system administrator can create an administrative template (.ADM) file that enables group policy-based configuration of new power settings. + +An individual power setting contains all of the information that is required to uniquely identify, name, describe, and provide values for the power setting. Each power setting is defined with a GUID, a setting name, a description, and default settings for AC and DC power schemes. A custom power setting can be created statically for a device, by using an [**INF AddPowerSetting directive**](https://msdn.microsoft.com/library/windows/hardware/ff546313), or dynamically, by calling the Win32 power management functions that are included in the power management reference that is provided with Microsoft Windows SDK documentation. + +Drivers call [**PoRegisterPowerSettingCallback**](https://msdn.microsoft.com/library/windows/hardware/ff559727) to register a callback routine that the power manager calls to notify the driver of a change to a power setting. When the setting changes, the power manager calls the callback routine and passes the new setting value. Drivers can then take the action that is appropriate for the power setting. Each setting is identified by the GUID of the power setting. The system-defined GUIDs for power settings are defined in Wdm.h and Ntpoapi.h. + +For example, to be notified when monitor power is turned on or off, a driver calls **PoRegisterPowerSettingCallback**, supplying the GUID that identifies the monitor power setting (GUID\_MONITOR\_POWER\_ON) and a pointer to the callback routine that the power manager calls when the value of the monitor power setting changes. + +### Registering to be Notified of a Change to the Active Power Scheme, Power Scheme Personality, or Power Source + +The personality of the active power scheme conveys the user's intent for the overall power saving behavior of the system. Every power scheme, including custom schemes, have a personality that indicates the overall intention of the scheme. This enables additional custom power schemes to be created while still providing all of the benefits of knowing the intent of the scheme. Windows Vista includes the following three system-defined power schemes and their corresponding personalities. + +**Maximum power savings** +Reduces performance to minimize power consumption. + +**Automatic (balanced)** +Lets the system choose the best power state level based on overall power consumption. + +**Maximum performance** +Provides maximum performance regardless of power consumption. + +The power source can be either an AC or a DC power source. + +A device power policy owner can use information about the active power scheme, power scheme personality, and power source to adjust device power policy. For example, a device power policy owner might aggressively power down a device if the power scheme personality changes to **Maximum Power Savings**. However, if the power scheme personality changes to **Maximum Performance**, the device power policy owner might maintain the performance level of its devices rather than reduce power consumption, and possibly leave the device powered at all times to ensure the highest level of performance. + +A driver can register to be notified when a change occurs to the active power scheme, the power scheme personality, or the power source. A driver calls **PoRegisterPowerSettingCallback** to register the callback routine that the power manager calls to notify the driver of such a change, as follows: + +- To register for notification of change to the active power scheme, supply the GUID that represents the setting for the power scheme (GUID\_ACTIVE\_POWERSCHEME). The power manager will then call the callback routine whenever the active power scheme changes, even if the personality of the new power scheme is the same as the previous power scheme. + +- To register for notification of a change to the power scheme personality, supply the GUID that represents the setting for the power scheme personality (GUID\_POWERSCHEME\_PERSONALITY). The power manager will then call the callback routine whenever the active power scheme changes and the personality of the new power scheme is different from the personality of the previous power scheme. + +- To register for notification of a change to the power source, supply the GUID that represents the setting for the power source (GUID\_ACDC\_POWER\_SOURCE). The power manager will then call the callback routine whenever the power source setting changes. + +When the active power scheme changes or the power scheme personality changes, the power manager calls the callback routine and passes the GUID that represents the new power scheme or power scheme personality. Drivers can then take the action that is appropriate for the change. + +The active power scheme setting and the power scheme personality setting use the following GUIDs to identify their respective values: + +- GUID\_MAX\_POWER\_SAVINGS, which corresponds to the **Maximum Power Savings** power scheme and its corresponding personality. + +- GUID\_MIN\_POWER\_SAVINGS, which corresponds to the **Maximum Performance** power scheme and its corresponding personality. + +- GUID\_TYPICAL\_POWER\_SAVINGS, which corresponds to the **Automatic (Balanced)** power scheme and its corresponding personality. + +When the power source changes, the power manager calls the callback routine and passes the GUID that represents the power source setting and the value of the power source setting that indicates whether the computer is being powered by an AC power source, a DC power source, or a short-term DC power source. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Device%20Performance%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-device-power-policy.md b/windows-driver-docs-pr/kernel/managing-device-power-policy.md new file mode 100644 index 0000000000..97b1becbc2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-device-power-policy.md @@ -0,0 +1,62 @@ +--- +title: Managing Device Power Policy +author: windows-driver-content +description: Managing Device Power Policy +ms.assetid: f6f9ab40-4d51-4181-ac11-ff7af42370af +keywords: ["device power policy WDK kernel", "power policy WDK kernel", "device power policy owners WDK kernel", "function drivers WDK power management", "device power states WDK kernel", "initial device power state WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Device Power Policy + + +## + + +Just as the power manager maintains and administers power policy for the system, one driver in the device stack for each device maintains and administers power policy for the device. This driver is the *device power policy owner* for the device. + +The device power policy owner is the driver that has the most information about the device usage and power state. It need not physically be able to set the device registers to power the device on and off, but it must be able to determine when the device is in use, when it is idle, and when it should change power state. + +Typically, the function driver for a device is its power policy owner, although for some devices another driver or system component might assume this role. For more information about the types of drivers involved in power management, see [Types of WDM Drivers](types-of-wdm-drivers.md). + +Some drivers act as the function driver for one device (creating an FDO) and the bus driver (creating a PDO) for an enumerated child device. In its Dispatch routines for power and PnP IRPs, such a driver must distinguish its handling of IRPs sent to the FDO and those sent to the PDO. + +For example, the driver for a SCSI adapter might perform the roles of function driver (creating an FDO) for the adapter itself and bus driver (creating a PDO) for the disks attached to the adapter. In its capacity as function driver/policy owner for the SCSI adapter, this driver receives system IRPs and requests device IRPs for the SCSI adapter. In its capacity as bus driver for the disks, it handles and completes device IRPs that specify the disk PDOs it creates. Just because the driver owns power policy for one device (FDO) does not mean that it owns power policy for the child device (PDO). + +The device power policy owner is responsible for the following: + +- Setting the initial power state of the device to D0 by calling [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) as it handles the Plug and Play manager's [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. + + Devices should power on as needed; for example, a device must power on to handle an I/O request. The device power policy owner is responsible for determining when its device is needed, ensuring that device power is on, and setting the correct device power state. The typical device should be powered on by the time the PnP start-device IRP has completed. + + As a general rule, most devices should be powered off when not in use, even when the system is in the working state. + +- Sending a device power request in response to a system power request by calling [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734). + + For example, when the policy owner receives a system set-power IRP, it sends a device set-power IRP. Most devices enter D3 when the system enters any sleeping state. The **DeviceState** array in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure lists the highest-powered state the device can maintain for each system power state. (See [Reporting Device Power Capabilities](reporting-device-power-capabilities.md).) + +- Detecting when the device is idle and putting it to sleep to conserve energy. + + Either the power manager or the device policy owner can detect an idle device and send a device power IRP to change its state. For more information, see [Detecting an Idle Device](detecting-an-idle-device.md). + +- Returning its device to the working state when required. + + When an I/O request arrives for a sleeping device, the device's drivers should return it to the working state. + +- Enabling and disabling wake-up for its device when requested. + + The device power policy owner sends and cancels wait/wake IRPs, as described in [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Device%20Power%20Policy%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-device-queues.md b/windows-driver-docs-pr/kernel/managing-device-queues.md new file mode 100644 index 0000000000..426c41707a --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-device-queues.md @@ -0,0 +1,86 @@ +--- +title: Managing Device Queues +author: windows-driver-content +description: Managing Device Queues +ms.assetid: 8b7d39f8-0449-4e9b-a54c-fe60ee60842c +keywords: ["device queues WDK IRPs , managing", "supplemental IRP queues WDK kernel", "StartIo routines, supplemental device queues"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Device Queues + + +## + + +The I/O manager usually (except for FSDs) creates an associated device queue object when a driver calls [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397). It also provides [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) and [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358), which drivers can call to have the I/O manager insert IRPs into the associated device queue or call their [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routines. + +Consequently, it is rarely necessary (or particularly useful) for a driver to set up its own device queue objects for IRPs. Likely candidates are drivers, such as the SCSI port driver, that must coordinate incoming IRPs from some number of closely coupled class drivers for heterogeneous devices that are serviced through a single controller or bus adapter. + +In other words, a driver for a disk array controller is more likely to use a driver-created controller object than to set up supplemental device queue object(s), while a driver for an add-on bus adapter and of a set of class drivers is slightly more likely to use supplemental device queues. + +### Using Supplemental Device Queues with a StartIo Routine + +By calling **IoStartPacket** and **IoStartNextPacket**, a driver's Dispatch and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) (or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972)) routines synchronize calls to its *StartIo* routine using the device queue that the I/O manager created when the driver created the device object. For a port driver with a *StartIo* routine, **IoStartPacket** and **IoStartNextPacket** insert and remove IRPs in the device queue for the port driver's shared device controller/adapter. If the port driver also sets up supplemental device queues to hold requests coming in from closely coupled higher-level class drivers, it must "sort" incoming IRPs into its supplemental device queues, usually in its *StartIo* routine. + +The port driver must determine which supplemental device queue each IRP belongs in before trying to insert that IRP into the appropriate queue. A pointer to the target device object is passed with the IRP to the driver's Dispatch routine. The driver should save the pointer for use in "sorting" the incoming IRPs. Note that the device object pointer passed to the *StartIo* routine is the driver's own device object, which represents the device controller/adapter, so it cannot be used for this purpose. + +After queuing any IRPs, the driver programs its shared controller/adapter to carry out the request. Thus, the port driver can process incoming requests for all devices on a first-come, first-served basis until a call to [**KeInsertDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff552180) puts an IRP into a particular class driver's device queue. + +By using its own device queue for all IRPs to be processed through its *StartIo* routine, the underlying port driver serializes operations through the shared device (or bus) controller/adapter to all attached devices. By sometimes holding IRPs for each supported device in a separate device queue, this port driver inhibits the processing of IRPs for an already busy device while increasing I/O throughput for every other device that does I/O through its shared hardware. + +In response to the call to **IoStartPacket** from the port driver's Dispatch routine, the I/O manager either calls that driver's *StartIo* routine immediately or puts the IRP into the device queue associated with the device object for the port driver's shared controller/adapter. + +The port driver must maintain its own state information about each of the heterogeneous devices that it services through the shared device controller/adapter. + +**Keep in mind the following when designing class/port drivers with supplemental device queues:** + +- A driver cannot easily get a pointer to a device object created by any driver layered above itself, except for the device object at the top of its device stack. + + By design, the I/O manager does not provide a support routine for getting such a pointer. Moreover, the order in which drivers are loaded makes it impossible for lower drivers to get pointers for higher-level drivers' device objects, which have not yet been created when any lower-level driver is adding its device. + + Although **IoGetAttachedDeviceReference** returns a pointer to the highest-level device object in a driver's stack, a driver should use this pointer only to designate a target for I/O requests to its stack. A driver should not attempt to read or write the device object. + +- A driver cannot use a pointer to a device object created by any driver layered above itself, except to send requests to the top of its own device stack. + + There is no way to synchronize access to a single device object (and its device extension) between two drivers in a multiprocessor-safe manner. Neither driver can make any assumptions about what I/O processing the other driver is currently doing. + +Even for closely coupled class/port drivers, each class driver should use the pointer to the port driver's device object(s) only to pass on IRPs using **IoCallDriver**. The underlying port driver must maintain its own state, probably in the port driver's device extension, about requests that it processes for any closely coupled class driver(s)' device(s). + +### Managing Supplemental Device Queues Across Driver Routines + +Any port driver that queues IRPs in supplemental device queues for a closely coupled set of class drivers also must handle the following situation efficiently: + +1. Its Dispatch routines have inserted IRPs for a particular device in the driver-created device queue for that device. + +2. IRPs for other devices continue to come in, to be queued to the driver's *StartIo* routine with **IoStartPacket**, and to be processed through the shared device controller. + +3. The device controller does not become idle, but each IRP held in the driver-created device queue also must be queued to the driver's *StartIo* routine as soon as possible. + +Consequently, the port driver's *DpcForIsr* routine must attempt to transfer an IRP from the driver's internal device queue for a particular device into the device queue for the shared adapter/controller whenever the port driver completes an IRP, as follows: + +1. The *DpcForIsr* routine calls **IoStartNextPacket** to have the *StartIo* routine begin processing the next IRP queued to the shared device controller. + +2. The *DpcForIsr* routine calls [**KeRemoveDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553156) to dequeue the next IRP (if any) that it is holding in its internal device queue for the device on whose behalf it is about to complete an IRP. + +3. If **KeRemoveDeviceQueue** returns a non-NULL pointer, the *DpcForIsr* routine calls **IoStartPacket** with the just dequeued IRP to have it queued to the shared device controller/adapter. Otherwise, the call to **KeRemoveDeviceQueue** simply resets the state of the device queue object to Not-Busy, and the *DpcForIsr* routine omits the call to **IoStartPacket**. + +4. Then, the *DpcForIsr* routine calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the input IRP for which the port driver has just completed I/O processing, either by setting the I/O status block with an error or by satisfying the I/O request. + +Note that the preceding sequence implies that the *DpcForIsr* routine also must determine the device for which it is completing the current (input) IRP in order to manage internal queuing of IRPs efficiently. + +If the port driver attempts to wait until its shared controller/adapter is idle before dequeuing IRPs held in its supplemental device queues, the driver might starve a device for which there was heavy I/O demand while it promptly serviced every other device for which the current I/O demand was actually much lighter. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Device%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-hardware-priorities.md b/windows-driver-docs-pr/kernel/managing-hardware-priorities.md new file mode 100644 index 0000000000..33c0847e3b --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-hardware-priorities.md @@ -0,0 +1,106 @@ +--- +title: Managing Hardware Priorities +author: windows-driver-content +description: Managing Hardware Priorities +ms.assetid: c27eb357-49d7-4f50-9554-643b70ca33dc +keywords: ["prioritizing criteria WDK kernel", "hardware priorities WDK kernel", "IRQL levels WDK kernel", "PASSIVE_LEVEL WDK", "APC_LEVEL WDK", "DISPATCH_LEVEL WDK", "DIRQL WDK", "interrupt service routines WDK kernel , hardware priorities", "ISRs WDK kernel , hardware priorities"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Hardware Priorities + + +## + + +The IRQL at which a driver routine executes determines which kernel-mode driver support routines it can call. For example, some driver support routines require that the caller be running at IRQL = DISPATCH\_LEVEL. Others cannot be called safely if the caller is running at any IRQL higher than PASSIVE\_LEVEL. + +Following is a list of IRQLs at which the most commonly implemented standard driver routines are called. The IRQLs are listed from lowest to highest priority. + +**PASSIVE\_LEVEL** +**Interrupts Masked Off** — None. + +**Driver Routines Called at** PASSIVE\_LEVEL — [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113), [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521), [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022), [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routines, most dispatch routines, driver-created threads, worker-thread callbacks. + +**APC\_LEVEL** +**Interrupts Masked Off** — APC\_LEVEL interrupts are masked off. + +**Driver Routines Called at** APC\_LEVEL — Some dispatch routines (see [Dispatch Routines and IRQLs](dispatch-routines-and-irqls.md)). + +**DISPATCH\_LEVEL** +**Interrupts Masked Off** — DISPATCH\_LEVEL and APC\_LEVEL interrupts are masked off. Device, clock, and power failure interrupts can occur. + +**Driver Routines Called at** DISPATCH\_LEVEL — [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858), [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504), [*AdapterListControl*](https://msdn.microsoft.com/library/windows/hardware/ff540513), [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049), [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381), [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) (while holding the cancel spin lock), [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079), [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983), [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routines. + +**DIRQL** +**Interrupts Masked Off** — All interrupts at IRQL<= DIRQL of driver's interrupt object. Device interrupts with a higher DIRQL value can occur, along with clock and power failure interrupts. + +Driver Routines Called at DIRQL — [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958), [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines. + +The only difference between APC\_LEVEL and PASSIVE\_LEVEL is that a process executing at APC\_LEVEL cannot get APC interrupts. But both IRQLs imply a thread context and both imply that the code can be paged out. + +Lowest-level drivers process IRPs while running at one of three IRQLs: + +- PASSIVE\_LEVEL, with no interrupts masked off on the processor, in the driver's Dispatch routine(s) + + **DriverEntry**, *AddDevice*, *Reinitialize*, and *Unload* routines also are run at PASSIVE\_LEVEL, as are any driver-created system threads. + +- DISPATCH\_LEVEL, with DISPATCH\_LEVEL and APC\_LEVEL interrupts masked off on the processor, in the *StartIo* routine + + *AdapterControl*, *AdapterListControl*, *ControllerControl*, *IoTimer*, *Cancel* (while it holds the cancel spin lock), and *CustomTimerDpc* routines also are run at DISPATCH\_LEVEL, as are *DpcForIsr* and *CustomDpc* routines. + +- Device IRQL (DIRQL), with all interrupts at less than or equal to the *SynchronizeIrql* of the driver's interrupt object(s) masked off on the processor, in the ISR and *SynchCritSection* routines + +Most higher-level drivers process IRPs while running at either of two IRQLs: + +- PASSIVE\_LEVEL, with no interrupts masked off on the processor, in the driver's dispatch routines + + **DriverEntry**, *Reinitialize*, *AddDevice*, and *Unload* routines also are run at PASSIVE\_LEVEL, as are any driver-created system threads or worker-thread callback routines or file system drivers. + +- DISPATCH\_LEVEL, with DISPATCH\_LEVEL and APC\_LEVEL interrupts masked off on the processor, in the driver's *IoCompletion* routine(s) + + *IoTimer*, *Cancel*, and *CustomTimerDpc* routines also are run at DISPATCH\_LEVEL. + +In some circumstances, intermediate and lowest-level drivers of mass-storage devices are called at IRQL APC\_LEVEL. In particular, this can occur at a page fault for which a file system driver sends an [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) request to lower drivers. + +Most standard driver routines are run at an IRQL that allows them simply to call the appropriate support routines. For example, a device driver must call [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) while running at IRQL DISPATCH\_LEVEL. Since most device drivers call these routines from a *StartIo* routine, usually they are running at DISPATCH\_LEVEL already. + +Note that a device driver that has no *StartIo* routine because it sets up and manages its own queues of IRPs is not necessarily running at DISPATCH\_LEVEL IRQL when it should call **AllocateAdapterChannel**. Such a driver must nest its call to **AllocateAdapterChannel** between calls to [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079) and [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) so that it runs at the required IRQL when it calls **AllocateAdapterChannel** and restores the original IRQL when the calling routine regains control. + +When calling driver support routines, be aware of the following. + +- Calling [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079) with an input *NewIrql* value that is less than the current IRQL causes a fatal error. Calling [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) except to restore the original IRQL (that is, after a call to **KeRaiseIrql**) also causes a fatal error. + +- While running at IRQL >= DISPATCH\_LEVEL, calling [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324) for kernel-defined dispatcher objects to wait for a nonzero interval causes a fatal error. + +- The only driver routines that can safely wait for events, semaphores, mutexes, or timers to be set to the signaled state are those that run in a nonarbitrary thread context at IRQL PASSIVE\_LEVEL, such as driver-created threads, the **DriverEntry** and *Reinitialize* routines, or dispatch routines for inherently synchronous I/O operations (such as most device I/O control requests). + +- Even while running at IRQL PASSIVE\_LEVEL, pageable driver code must not call [**KeSetEvent**](https://msdn.microsoft.com/library/windows/hardware/ff553253), [**KeReleaseSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff553143), or [**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) with the input *Wait* parameter set to **TRUE**. Such a call can cause a fatal page fault. + +- Any routine that is running at greater than IRQL APC\_LEVEL can neither allocate memory from paged pool nor access memory in paged pool safely. If a routine running at IRQL greater than APC\_LEVEL causes a page fault, it is a fatal error. + +- A driver must be running at IRQL DISPATCH\_LEVEL when it calls [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921) and [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150). + + A driver can be running at IRQL <= DISPATCH\_LEVEL when it calls **KeAcquireSpinLock** but it must release that spin lock by calling **KeReleaseSpinLock**. In other words, it is a programming error to release a spin lock acquired with **KeAcquireSpinLock** by calling **KeReleaseSpinLockFromDpcLevel**. + + A driver must not call **KeAcquireSpinLockAtDpcLevel**, **KeReleaseSpinLockFromDpcLevel**, **KeAcquireSpinLock**, or **KeReleaseSpinLock** while running at IRQL > DISPATCH\_LEVEL. + +- Calling a support routine that uses a spin lock, such as an **ExInterlocked*Xxx*** routine, raises IRQL on the current processor either to DISPATCH\_LEVEL or to DIRQL if the caller is not already running at a raised IRQL. + +- Driver code that runs at IRQL > PASSIVE\_LEVEL should execute as quickly as possible. The higher the IRQL at which a routine runs, the more important it is for good overall performance to tune that routine to execute as quickly as possible. For example, any driver that calls **KeRaiseIrql** should make the reciprocal call to **KeLowerIrql** as soon as it can. + +For more information about determining priorities, see the [Scheduling, Thread Context, and IRQL](http://go.microsoft.com/fwlink/p/?linkid=59757) white paper that is available on the Microsoft Windows Hardware Developer Central (WHDC) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Hardware%20Priorities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-input-output-for-drivers.md b/windows-driver-docs-pr/kernel/managing-input-output-for-drivers.md new file mode 100644 index 0000000000..225d927c7d --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-input-output-for-drivers.md @@ -0,0 +1,27 @@ +--- +title: Managing Input/Output for Drivers +author: windows-driver-content +description: Managing Input/Output for Drivers +ms.assetid: 09f23775-8c98-4344-9f68-43297ef50849 +--- + +# Managing Input/Output for Drivers + + +This section includes the following topics: + +[Handling IRPs](handling-irps.md) + +[I/O Programming Techniques](i-o-programming-techniques.md) + +[Servicing Interrupts](servicing-interrupts.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Input/Output%20for%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-interlocked-queues-with-a-driver-created-thread.md b/windows-driver-docs-pr/kernel/managing-interlocked-queues-with-a-driver-created-thread.md new file mode 100644 index 0000000000..4443a4f9d1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-interlocked-queues-with-a-driver-created-thread.md @@ -0,0 +1,62 @@ +--- +title: Managing Interlocked Queues with a Driver-Created Thread +author: windows-driver-content +description: Managing Interlocked Queues with a Driver-Created Thread +ms.assetid: e2712d52-e98a-4450-b010-9278db3a7a1e +keywords: ["interlocked IRP queues WDK kernel", "driver-created threads WDK IRPs", "doubly linked IRPs WDK kernel", "driver-dedicated threads WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Interlocked Queues with a Driver-Created Thread + + +## + + +New drivers should use the [cancel-safe IRP queue](cancel-safe-irp-queues.md) framework in preference to the methods outlined in this section. + +Like the system floppy controller driver, a driver with a device-dedicated thread, rather than a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, usually manages its own queuing of IRPs in a doubly linked interlocked queue. The driver's thread pulls IRPs from its interlocked queue when there is work to be done on the device. + +In general, the driver must manage synchronization with its thread to any resources shared between the thread and other driver routines. The driver also must have some way to notify its driver-created thread that IRPs are queued. Usually, the thread waits on a dispatcher object, stored in the device extension, until the driver's Dispatch routines set the dispatcher object to the Signaled state after inserting an IRP into the interlocked queue. + +When the driver's Dispatch routines are called, each checks the parameters in the I/O stack location of the input IRP and, if they are valid, queues the request for further processing. For each IRP queued to a driver-dedicated thread, the dispatch routine should set up whatever context its thread needs to process that IRP before it calls **ExInterlockedInsert*Xxx*List**. The driver's I/O stack location in each IRP gives the driver's thread access to the device extension of the target device object, where the driver can share context information with its thread, as the thread removes each IRP from the queue. + +A driver that queue cancelable IRPs must implement a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine. Since IRPs are canceled asynchronously, you must ensure that your driver avoids the race conditions that can result. See [Synchronizing IRP Cancellation](synchronizing-irp-cancellation.md) For more information about race conditions associated with canceling IRPs and techniques to avoid them. + +Any driver-created thread runs at IRQL = PASSIVE\_LEVEL and at a base run-time priority previously set when the driver called [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932). The thread's call to [**ExInterlockedRemoveHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff545427) temporarily raises the IRQL to DISPATCH\_LEVEL on the current processor while the IRP is being removed from the driver's internal queue. The original IRQL is restored to PASSIVE\_LEVEL on return from this call. + +**Any driver thread (or driver-supplied worker-thread callback) must carefully manage the IRQLs at which it runs. For example, consider the following:** + +- Because system threads generally run at IRQL = PASSIVE\_LEVEL, it is possible for a driver thread to wait for kernel-defined dispatcher objects to be set to the signaled state. + + For example, a device-dedicated thread might wait for other drivers to satisfy an event and complete some number of partial-transfer IRPs that the thread sets up with [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330). + +- However, such a device-dedicated thread must raise IRQL on the current processor before it calls certain support routines. + + For example, if a driver uses DMA, its device-dedicated thread must nest its calls to [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) and [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) between calls to [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079) and [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) because these routines and certain other support routines for DMA operations must be called at IRQL = DISPATCH\_LEVEL. + + Remember that [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routines are run at DISPATCH\_LEVEL, so drivers that use DMA need not make calls to the **Ke*Xxx*Irql** routines from their *StartIo* routines. + +- A driver-created thread can access pageable memory because it runs in a nonarbitrary thread context (its own) at IRQL = PASSIVE\_LEVEL, but many other standard driver routines run at IRQL >= DISPATCH\_LEVEL. If a driver-created thread allocates memory that can be accessed by such a routine, it must allocate the memory from nonpaged pool. For example, if a device-dedicated thread allocates any buffer that will be accessed later by the driver's ISR or [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928), [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504), [*AdapterListControl*](https://msdn.microsoft.com/library/windows/hardware/ff540513), [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049), [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079), [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972), [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381), [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983), or, in a higher-level driver, [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, the thread-allocated memory cannot be pageable. + +- If the driver maintains shared state information or resources in a device extension, a driver thread (like a *StartIo* routine) must synchronize its access to a physical device and to the shared data with the driver's other routines that access the same device, memory location, or resources. + + If the thread shares the device or state with the ISR, it must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine to program the device or to access the shared state. See [Using Critical Sections](using-critical-sections.md). + + If the thread shares state or resources with routines other than the ISR, the driver must protect the shared state or resources with a driver-initialized executive spin lock for which the driver provides the storage. For more information, see [Spin Locks](spin-locks.md). + +For more information about the design tradeoffs of a using a driver thread for a slow device, see [Polling a Device](avoid-polling-devices.md). See also [Managing Hardware Priorities](managing-hardware-priorities.md). For specific information about IRQLs for particular support routines, see the routine's reference page. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Interlocked%20Queues%20with%20a%20Driver-Created%20Thread%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-kernel-objects.md b/windows-driver-docs-pr/kernel/managing-kernel-objects.md new file mode 100644 index 0000000000..85dbfa4f5b --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-kernel-objects.md @@ -0,0 +1,60 @@ +--- +title: Managing Kernel Objects +author: windows-driver-content +description: Managing Kernel Objects +ms.assetid: d45aca94-67b7-444d-8585-713ec982e3bc +keywords: ["kernel-mode drivers WDK , object management", "object manager WDK kernel", "object management WDK kernel", "referencing objects", "object names WDK user-mode", "object management WDK user-mode", "kernel-mode objects WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Kernel Objects + + +## + + +The Windows Object Manager controls *objects* that are part of the kernel-mode operating system. An object is a collection of data that the operating system manages. + +Typical kernel-mode objects include the following objects: + +- Device objects (See [Device Objects and Device Stacks](device-objects-and-device-stacks.md).) + +- File objects. + +- Symbolic links. + +- Registry keys. + +- Threads and processes. + +- Kernel dispatcher objects, such as event objects and mutex objects. (See [Kernel Dispatcher Objects](kernel-dispatcher-objects.md).) + +- Callback objects. (See [Callback Objects](callback-objects.md).) + +- Section objects. (See [Section Objects and Views](section-objects-and-views.md).) + +Kernel-mode objects enable you to manipulate objects in partnership with the object manager without damaging the portions of the objects that the operating system needs. This principle is called *encapsulation* and is one of the core concepts of object-orientated programming. (Because kernel-mode objects do not provide other aspects of object-orientation, kernel-mode programming is typically referred to as [*object-based*](object-based.md).) Kernel-mode objects do not follow the same rules as objects in C++ or Microsoft COM. + +Kernel-mode objects can be referenced by pointers. An object may have an object name. For more information about object names, see [Object Names](object-names.md). + +User-mode programmers can reference objects only through indirection, using a *handle*. If an object has a name, you can use it to obtain the handle in user mode. For more information about handles, see [Object Handles](object-handles.md). + +Kernel-mode objects have a very specific life-cycle. For more information about object life-cycles, see [Life Cycle of an Object](life-cycle-of-an-object.md). + +Object security is a prime concern for kernel-mode programming. For more information on object security, see [Object Security](object-security.md). + +The kernel-mode environment stores objects in a virtual directory system, also known as the object namespace. This allows objects to be accessed in a hierarchical way with parent and child objects. This namespace is similar to a file system set of directories but does not exactly correspond to a particular file system on your computer. For more information about object directories, see [Object Directories](object-directories.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Kernel%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-memory-for-drivers.md b/windows-driver-docs-pr/kernel/managing-memory-for-drivers.md new file mode 100644 index 0000000000..07ee678d35 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-memory-for-drivers.md @@ -0,0 +1,52 @@ +--- +title: Memory Management for Windows Drivers +author: windows-driver-content +description: Kernel-mode drivers allocate memory for purposes such as storing internal data, buffering data during I/O operations, and sharing memory with other kernel-mode and user-mode components. +ms.assetid: e030a37c-26ab-4177-9980-4336928975e1 +keywords: ["memory management WDK kernel", "available space WDK kernel", "free space WDK kernel", "space WDK See memory WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Memory Management for Windows Drivers + + +Kernel-mode drivers allocate memory for purposes such as storing internal data, buffering data during I/O operations, and sharing memory with other kernel-mode and user-mode components. Driver developers should understand memory management in Windows so that they use allocated memory correctly and efficiently. Windows manages virtual and physical memory, and divides memory into separate user and system address spaces. A driver can specify whether allocated memory supports capabilities such as demand paging, data caching, and instruction execution. + +## + + +The *memory manager* is the kernel component that performs the memory management operations in Windows. For more information, see [Windows Kernel-Mode Memory Manager](windows-kernel-mode-memory-manager.md). + +The memory manager implements a number of kernel-mode support routines that drivers call to allocate and manage memory. For more information, see [Memory Allocation and Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff554422). + +The memory-management capabilities of kernel-mode drivers are different from those of user-mode applications. For more information about memory management for applications, see [Memory Management](https://msdn.microsoft.com/library/windows/desktop/aa366779). + +## In this section + + +- [Overview of Windows Memory Space](overview-of-windows-memory-space.md) +- [Allocating System-Space Memory](allocating-system-space-memory.md) +- [Map Registers](map-registers.md) +- [Mapping Bus-Relative Addresses to Virtual Addresses](mapping-bus-relative-addresses-to-virtual-addresses.md) +- [Using the Kernel Stack](using-the-kernel-stack.md) +- [Using Lookaside Lists](using-lookaside-lists.md) +- [Making Drivers Pageable](making-drivers-pageable.md) +- [Accessing Read-Only System Memory](accessing-read-only-system-memory.md) +- [Accessing User-Space Memory](accessing-user-space-memory.md) +- [No-Execute (NX) Nonpaged Pool](no-execute-nonpaged-pool.md) +- [Section Objects and Views](section-objects-and-views.md) +- [Using MDLs](using-mdls.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Memory%20Management%20for%20Windows%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-memory-sections.md b/windows-driver-docs-pr/kernel/managing-memory-sections.md new file mode 100644 index 0000000000..9e09e0c0c4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-memory-sections.md @@ -0,0 +1,38 @@ +--- +title: Managing Memory Sections +author: windows-driver-content +description: Managing Memory Sections +ms.assetid: 620ba31d-596f-493a-b97f-65a27d50cc9a +keywords: ["memory sections WDK kernel", "section objects WDK kernel", "views WDK memory section", "mapping section views"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Memory Sections + + +## + + +A driver can create a section object by calling [**ZwCreateSection**](https://msdn.microsoft.com/library/windows/hardware/ff566428), which returns a handle to the section object. Use the *FileHandle* parameter to specify the backing file, or **NULL** if the section is not file-backed. Additional handles to the section object can be opened by using [**ZwOpenSection**](https://msdn.microsoft.com/library/windows/hardware/ff567029). + +To make the data that belongs to a section object accessible within the current process' address space, a view of the section must be mapped. Drivers can map a view of a section into the current process' address space by using the [**ZwMapViewOfSection**](https://msdn.microsoft.com/library/windows/hardware/ff566481) routine. The *SectionOffset* parameter specifies the byte offset where the view begins within the section, and the *ViewSize* specifies the number of bytes to be mapped. + +The *Protect* parameter specifies the allowed operations on the view. Specify PAGE\_READONLY for a read-only view, PAGE\_READWRITE for a read/write view, and PAGE\_WRITECOPY for a copy-on-write view. + +No physical memory is allocated for a view until the virtual memory range is accessed. The first access of the memory range causes a page fault; the system then allocates a page to hold that memory location. If the section is file-backed, the system reads the contents of the file that corresponds to that page and copies it into memory. (Note that unused section objects and views do use some paged and nonpaged pool for bookkeeping purposes.) + +After a driver is no longer using a view, it unmaps it by making a call to [**ZwUnmapViewOfSection**](https://msdn.microsoft.com/library/windows/hardware/ff567119). After the driver is no longer using the section object, it closes the section handle with [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). Note that after the view is mapped and no other views are going to be mapped, it is safe to immediately call **ZwClose** on the section handle; the view (and section object) continue to exist until the view is unmapped. This is the recommended practice because it reduces the risk of the driver failing to close the handle. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Memory%20Sections%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/managing-power-for-individual-devices.md b/windows-driver-docs-pr/kernel/managing-power-for-individual-devices.md new file mode 100644 index 0000000000..47fac0ee88 --- /dev/null +++ b/windows-driver-docs-pr/kernel/managing-power-for-individual-devices.md @@ -0,0 +1,48 @@ +--- +title: Managing Power for Individual Devices +author: windows-driver-content +description: Managing Power for Individual Devices +ms.assetid: 95c7e900-5d51-4eb7-8780-1c40befa3599 +keywords: ["power management WDK kernel , device management", "device power management WDK kernel", "system power states WDK kernel", "conserving power WDK kernel", "change power states WDK kernel", "IRPs WDK power management", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Managing Power for Individual Devices + + +## + + +Drivers manage power for their devices by responding to [system power state](system-power-states.md) changes, detecting and shutting down idle devices, and powering up devices when they are needed. + +This section covers the following topics related to device power management: + +[Device Power States](device-power-states.md) + +[Detecting an Idle Device](detecting-an-idle-device.md) + +[Managing Device Power Policy](managing-device-power-policy.md) + +[Handling IRP\_MN\_SET\_POWER for Device Power States](handling-irp-mn-set-power-for-device-power-states.md) + +[Handling IRP\_MN\_QUERY\_POWER for Device Power States](handling-irp-mn-query-power-for-device-power-states.md) + +[Sending IRP\_MN\_QUERY\_POWER or IRP\_MN\_SET\_POWER for Device Power States](sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md) + +[Detecting an Idle Device](detecting-an-idle-device.md) + +[Supporting D3cold in a Driver](supporting-d3cold-in-a-driver.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Managing%20Power%20for%20Individual%20Devices%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/map-registers.md b/windows-driver-docs-pr/kernel/map-registers.md new file mode 100644 index 0000000000..36279694ac --- /dev/null +++ b/windows-driver-docs-pr/kernel/map-registers.md @@ -0,0 +1,74 @@ +--- +title: Map Registers +author: windows-driver-content +description: Map Registers +ms.assetid: 0404f487-7a4f-43be-bbe0-b7da2087b8aa +keywords: ["memory management WDK kernel , map registers", "map registers WDK kernel", "virtual address space mappings WDK kernel", "logical address space mappings WDK kernel", "physical address space mappings WDK kernel", "mapping memory", "address space mappings WDK kernel", "scatter/gather capabilities WDK kernel", "translating address space WDK kernel", "memory management WDK kernel , mapping addresses"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Map Registers + + +## + + +Drivers that perform DMA use three different address spaces, as shown in the following figure. + +![diagram illustrating logical, physical, and virtual address mappings](images/3addrspc.png) + +On any Windows platform, a driver has access to the full virtual address space supported by the processor. On a 32-bit processor, the virtual address space represents four gigabytes. The CPU translates addresses in the virtual address space to addresses in the system's physical address space by using a page table. Each page table entry (PTE) maps one page of virtual memory to a page of physical memory, resulting in a paging operation when necessary. An MDL (memory descriptor list) provides a similar mapping for a buffer associated with driver DMA operations. + +Devices vary in their ability to access the system's full virtual address space. A device uses addresses in logical (device) address space. Each HAL uses *map registers* to translate a device or logical address to a physical address (a location in physical RAM). For the device hardware, map registers perform the same function that the MDL (and page table) performs for the software (drivers): they translate addresses to physical memory. + +Because these address spaces are separately addressed, a driver cannot use a pointer in virtual address space to address a location in physical memory, and vice versa. The driver must first translate the virtual address to a physical address. Similarly, a device cannot use a logical address to directly access physical memory. The device must first translate the address. + +A HAL must set up adapter objects that support DMA for a wide variety of DMA devices and I/O buses on different computers. For example, most ISA DMA controllers, subordinate devices, and bus-master devices have insufficient address lines to access the full four-gigabyte system physical address space of a 32-bit processor (or the 64-gigabyte system physical address of an x86 processor running in 36-bit PAE mode). By contrast, PCI DMA devices generally have more than enough address lines to access the full system physical address space in 32-bit processors. Therefore, every HAL provides mappings between the *logical address* ranges that DMA devices can access and *physical address* ranges of each computer. + +Each adapter object is associated with one or more map registers, depending on the amount of data to be transferred and the amount of available memory. During DMA transfers, the HAL uses each map register to alias a device-accessible logical page to a page of physical memory in the CPU. In effect, map registers provide scatter/gather support for drivers that use DMA, regardless of whether their devices have scatter/gather capabilities. + +### + +The following figure illustrates such a physical-to-logical address mapping for the driver of an ISA DMA device that does not have scatter/gather capabilities. + +![address mapping for a sample isa dma device](images/3dmapreg.png) + +The previous figure shows the following types of mappings: + +1. Each map register maps a range of physical addresses (pointed to by solid lines) to low-order logical addresses (dotted lines) for an ISA DMA device. + + Here, three map registers are used to alias three paged ranges of data in system physical memory to three page-sized ranges of low-order logical addresses for an ISA DMA device. + +2. The ISA device uses the mapped logical addresses to access system memory during DMA operations. + + For a comparable PCI DMA device, three map registers would also be used for three page-sized ranges of data. However, the mapped logical address ranges would not necessarily be identical to the corresponding physical address ranges, so a PCI device would also use logical addresses to access system memory. + +3. Each entry in the MDL maps a location in virtual address space to a physical address. + +Note the correspondence between a map register and a virtual-to-physical entry in the MDL: + +- Each map register and each virtual entry in an MDL maps at most a full physical page of data for a DMA transfer operation. + +- Each map register and each virtual entry in an MDL might map less than a full page of data. For example, the initial virtual entry in an MDL can map to an offset from the physical page boundary, as shown earlier in the [Physical, Logical, and Virtual Address Mappings](#physical-logical-and-virtual-address-mappings) figure. + +- Each map register and each virtual entry in an MDL maps, at a minimum, one byte. + +In an IRP requesting a read or write operation, each virtual entry in the opaque-to-drivers MDL at **Irp->MdlAddress** represents a page boundary in the system physical memory for a user buffer. Similarly, each additional map register needed for a single DMA transfer represents a page boundary in the device-accessible logical address range aliased to system physical memory. + +On every Windows platform, each adapter object has an associated set of one or more map registers located at a platform-specific (and opaque-to-drivers) base address. From a driver's point of view, the map register base shown in the figure illustrating [address mapping for a sample ISA DMA device](#address-mapping-for-a-sample-isa-dma-device) is a handle for a set of map registers that could be hardware registers in a chip, in a system DMA controller, or in a bus-master adapter, or could even be HAL-created virtual registers in system memory. + +The number of map registers available with an adapter object can vary for different devices and Windows platforms. For example, the HAL can make more map registers available to drivers that use system DMA on some platforms than on other platforms because the DMA controllers on different Windows platforms have different capabilities. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Map%20Registers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mapping-bus-relative-addresses-to-virtual-addresses.md b/windows-driver-docs-pr/kernel/mapping-bus-relative-addresses-to-virtual-addresses.md new file mode 100644 index 0000000000..124142c028 --- /dev/null +++ b/windows-driver-docs-pr/kernel/mapping-bus-relative-addresses-to-virtual-addresses.md @@ -0,0 +1,54 @@ +--- +title: Mapping Bus-Relative Addresses to Virtual Addresses +author: windows-driver-content +description: Mapping Bus-Relative Addresses to Virtual Addresses +ms.assetid: 16496465-8a30-4250-9d64-afd36a788ae2 +keywords: ["virtual address space mappings WDK kernel", "physical address space mappings WDK kernel", "mapping memory", "address space mappings WDK kernel", "translating address space WDK kernel", "memory management WDK kernel , mapping addresses", "bus-relative memory space WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Mapping Bus-Relative Addresses to Virtual Addresses + + +## + + +Some processors implement separate memory and I/O address spaces, while other processors do not. Because of these differences in hardware platforms, the mechanism drivers use to access I/O- or memory-resident device resources differs from platform to platform. + +A driver requests device I/O and memory resources in response to the PnP manager's [**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff551715) IRP. Depending on the hardware architecture, the HAL can assign I/O resources in I/O space or in memory space, and can assign memory resources in I/O space or in memory space. + +If the HAL uses bus-relative memory space to access device resources (such as device registers), a driver must map I/O space into virtual memory so that it can access these resources. The driver can determine whether the resources are I/O- or memory-resident by inspecting the translated resources passed to the driver by the PnP manager at device startup. If the HAL uses I/O space, no mapping is required. + +Specifically, when a driver receives an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, it should examine the structures at **IrpSp->Parameters.StartDevice.AllocatedResources** and **IrpSp->Parameters.StartDevice.AllocatedResourcesTranslated**, which describe the raw (bus-relative) and translated resources, respectively, that the PnP manager has assigned to the device. Drivers should save a copy of each resource list in the device extension as an aid to debugging. + +The resource lists are paired [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) structures, in which each element of the raw list corresponds to the same element of the translated list. For example, if **AllocatedResources.List**\[0\] describes a raw I/O port range, **AllocatedResourcesTranslated.List**\[0\] describes the same range after translation. Each translated resource includes a physical address and the type of the resource. + +If a driver is assigned a translated memory resource (**CmResourceTypeMemory**), it must call [**MmMapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff554618) to map the physical address into a virtual address through which it can access device registers. For a driver to operate in a platform-independent manner, it should check every returned, translated resource and map it, if necessary. + +**A kernel-mode driver should take the following steps, in response to an IRP\_MN\_START\_DEVICE request, to ensure access to all device resources** + +1. Copy **IrpSp->Parameters.StartDevice.AllocatedResources** to the device extension. + +2. Copy **IrpSp->Parameters.StartDevice.AllocatedResourcesTranslated** to the device extension. + +3. In a loop, inspect each descriptor element in **AllocatedResourcesTranslated**. If the descriptor resource type is **CmResourceTypeMemory**, call **MmMapIoSpace**, passing the physical address and length of the translated resource. + +When the driver receives an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) or [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request from the PnP manager, it must release the mappings by calling [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387) in a similar loop. The driver should also call **MmUnmapIoSpace** if it must fail the **IRP\_MN\_START\_DEVICE** request. + +The raw resource type indicates which HAL access routine a driver should call (**READ\_REGISTER\_*XXX***, **WRITE\_REGISTER\_*XXX***, **READ\_PORT\_*XXX***, **WRITE\_PORT\_*XXX***). Most drivers do not have to check the raw resource list to determine which of these routines to use, because the driver itself requested the resource or the driver writer knows the required type given the nature of the device hardware. + +For a resource in I/O space (**CmResourceTypePort**, **CmResourceTypeInterrupt**, **CmResourceTypeDma**), the driver should use the low-order 32 bits of the returned physical address to access the device resource, for example, through the HAL's read and write **READ\_REGISTER\_*XXX***, **WRITE\_REGISTER\_*XXX***, **READ\_PORT\_*XXX***, and **WRITE\_PORT\_*XXX*** routines. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Mapping%20Bus-Relative%20Addresses%20to%20Virtual%20Addresses%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/methods-for-accessing-data-buffers.md b/windows-driver-docs-pr/kernel/methods-for-accessing-data-buffers.md new file mode 100644 index 0000000000..4e5a1bb160 --- /dev/null +++ b/windows-driver-docs-pr/kernel/methods-for-accessing-data-buffers.md @@ -0,0 +1,48 @@ +--- +title: Methods for Accessing Data Buffers +author: windows-driver-content +description: Methods for Accessing Data Buffers +ms.assetid: f95a0aec-65f9-44c9-8ae5-11bb4d832752 +keywords: ["I/O WDK kernel , data buffers", "data buffers WDK I/O", "buffers WDK I/O", "buffers WDK I/O , accessing", "data buffers WDK I/O , accessing", "data transfers WDK kernel , data buffer access", "transferring data WDK kernel , data buffer access"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Methods for Accessing Data Buffers + + +One of the primary responsibilities of driver stacks is transferring data between user-mode applications and a system's devices. The operating system provides the following three methods for accessing data buffers: + +*Buffered I/O* +The operating system creates a nonpaged system buffer, equal in size to the application's buffer. For write operations, the I/O manager copies user data into the system buffer before calling the driver stack. For read operations, the I/O manager copies data from the system buffer into the application's buffer after the driver stack completes the requested operation. + +For more information, see [Using Buffered I/O](using-buffered-i-o.md). + +*Direct I/O* +The operating system locks the application's buffer in memory. It then creates a memory descriptor list (MDL) that identifies the locked memory pages, and passes the MDL to the driver stack. Drivers access the locked pages through the MDL. + +For more information, see [Using Direct I/O](using-direct-i-o.md). + +*Neither Buffered Nor Direct I/O* +The operating system passes the application buffer's virtual starting address and size to the driver stack. The buffer is only accessible from drivers that execute in the application's thread context. + +For more information, see [Using Neither Buffered Nor Direct I/O](using-neither-buffered-nor-direct-i-o.md). + +For [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests, drivers specify the I/O method by using flags in each [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. For more information, see [Initializing a Device Object](initializing-a-device-object.md). + +For [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests, the I/O method is determined by the *TransferType* value that is contained in each IOCTL value. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +All drivers in a driver stack must use the same buffer access method for each request, except possibly for the highest-level driver (which can use the "neither" method, regardless of the method used by lower drivers). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Methods%20for%20Accessing%20Data%20Buffers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/miscellaneous-driver-programming-techniques.md b/windows-driver-docs-pr/kernel/miscellaneous-driver-programming-techniques.md new file mode 100644 index 0000000000..97da44163d --- /dev/null +++ b/windows-driver-docs-pr/kernel/miscellaneous-driver-programming-techniques.md @@ -0,0 +1,72 @@ +--- +title: Miscellaneous Driver Programming Techniques +author: windows-driver-content +description: Miscellaneous Driver Programming Techniques +ms.assetid: 6afdaecb-62f8-4909-8117-6242cd5b3765 +keywords: ["driver programming techniques WDK kernel", "kernel-mode drivers WDK , driver programming techniques"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Miscellaneous Driver Programming Techniques + + +## + + +This section contains various topics of interest to driver writers. It includes the following sections: + +[NTSTATUS Values](ntstatus-values.md) + +[Singly and Doubly Linked Lists](singly-and-doubly-linked-lists.md) + +[Handling Exceptions](handling-exceptions.md) + +[Logging Errors](logging-errors.md) + +[Writing a Bug Check Callback Routine](writing-a-bug-check-callback-routine.md) + +[Using Safe String Functions](using-safe-string-functions.md) + +[Using Safe Integer Functions](ntintsafe-design-guide.md) + +[Determining Whether the Operating System Is Running in Safe Mode](determining-whether-the-operating-system-is-running-in-safe-mode.md) + +[Using GUIDs in Drivers](using-guids-in-drivers.md) + +[Using Floating Point or MMX in a WDM Driver](using-floating-point-or-mmx-in-a-wdm-driver.md) + +[Using Files In A Driver](using-files-in-a-driver.md) + +[Using the Registry in a Driver](using-the-registry-in-a-driver.md) + +[Supporting Removable Media](supporting-removable-media.md) + +[Creating Export Drivers](creating-export-drivers.md) + +[Creating Reliable Kernel-Mode Drivers](creating-reliable-kernel-mode-drivers.md) + +[Hiding Devices from Device Manager](hiding-devices-from-device-manager.md) + +[Filtering Registry Calls](filtering-registry-calls.md) + +[Object Reference Tracing with Tags](object-reference-tracing-with-tags.md) + +[Programming Issues for 64-Bit Drivers](programming-issues-for-64-bit-drivers.md) + +[Obsolete and Reserved Kernel Programming Interfaces](obsolete-and-reserved-kernel-programming-interfaces.md) + +[Kernel Macros, Global Variables, and Opaque Structures](kernel-macros--global-variables--and-opaque-structures.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Miscellaneous%20Driver%20Programming%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mm-bad-pointer.md b/windows-driver-docs-pr/kernel/mm-bad-pointer.md new file mode 100644 index 0000000000..752b64fbb5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/mm-bad-pointer.md @@ -0,0 +1,632 @@ +--- +title: Windows kernel macros +author: windows-driver-content +description: Windows kernel macros +ms.assetid: 91366400-3307-4F13-A839-50BA85B7F73E +--- + +# Windows kernel macros + + +The following table contains Windows kernel macros: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MacroDeclared inDescription
ADDRESS_AND_SIZE_TO_SPAN_PAGES

Wdm.h

The ADDRESS_AND_SIZE_TO_SPAN_PAGES macro returns the number of pages spanned by the virtual range defined by a virtual address and the size in bytes of a transfer request.

+

Va [in]

+

PVOID

+

Pointer to the virtual address that is the base of the range.

+

Size [in]

+

ULONG

+

Specifies the size in bytes of the transfer request.

+

Return value

+

ULONG

+

ADDRESS_AND_SIZE_TO_SPAN_PAGES returns the number of pages spanned by the virtual range starting at Va.

+

Drivers that make DMA transfers call ADDRESS_AND_SIZE_TO_SPAN_PAGES to determine whether a transfer request must be split into a sequence of device DMA operations.

+

A driver can use the system-defined constant PAGE_SIZE to determine whether the number of bytes to be transferred is less than the virtual memory page size of the current platform.

+

Callers of ADDRESS_AND_SIZE_TO_SPAN_PAGES can be running at any IRQL. The caller must ensure that the specified parameters do not cause memory overflow.

+

Available starting with Windows 2000.

BYTE_OFFSET

Wdm.h

The BYTE_OFFSET macro takes a virtual address and returns the byte offset of that address within the page.

+

Va [in]

+

PVOID

+

Pointer to the virtual address.

+

Return value

+

ULONG

+

BYTE_OFFSET returns the offset portion of the virtual address.

+

Available starting with Windows 2000.

+

IRQL: Any level

BYTES_TO_PAGES

Wdm.h

The BYTES_TO_PAGES macro takes the size in bytes of the transfer request and calculates the number of pages required to contain the bytes.

+

Size [in]

+

ULONG

+

Specifies the size in bytes of the transfer request.

+

Return value

+

ULONG

+

BYTES_TO_PAGES returns the number of pages required to contain the specified number of bytes.

+

The system-defined constant PAGE_SIZE can be used to determine whether a given length in bytes for a transfer is less than the virtual memory page size of the current platform.

+

Available starting with Windows 2000.

+

IRQL: Any level

CONTAINING_RECORD

Ntdef.h

The CONTAINING_RECORD macro returns the base address of an instance of a structure given the type of the structure and the address of a field within the containing structure.

+

Address [in]

+

PCHAR

+

A pointer to a field in an instance of a structure of type Type.

+

Type [in]

+

TYPE

+

The name of the type of the structure whose base address is to be returned.

+

Field [in]

+

PCHAR

+

The name of the field pointed to by Address and which is contained in a structure of type Type.

+

Return value

+

PCHAR

+

Returns the address of the base of the structure containing Field.

+

Called to determine the base address of a structure whose type is known when the caller has a pointer to a field inside such a structure. This macro is useful for symbolically accessing other fields in a structure of known type.

+

Available starting with Windows 2000.

+

IRQL: Any level

IoSkipCurrentIrpStackLocation

Wdm.h

The IoSkipCurrentIrpStackLocation macro modifies the system's [IO_STACK_LOCATION](https://msdn.microsoft.com/library/windows/hardware/ff550659) array pointer, so that when the current driver calls the next-lower driver, that driver receives the same IO_STACK_LOCATION structure that the current driver received.

+

Irp [in, out]

+

PIRP

+

A pointer to the IRP.

+

Return value

+

VOID

+

When your driver sends an IRP to the next-lower driver, your driver can call IoSkipCurrentIrpStackLocation if you do not intend to provide an [IoCompletion](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine (the address of which is stored in the driver's [IO_STACK_LOCATION](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure). If you call IoSkipCurrentIrpStackLocation before calling [IoCallDriver](https://msdn.microsoft.com/library/windows/hardware/ff548336), the next-lower driver receives the same IO_STACK_LOCATION that your driver received.

+

If you intend to provide an IoCompletion routine for the IRP, your driver should call [IoCopyCurrentIrpStackLocationToNext](https://msdn.microsoft.com/library/windows/hardware/ff548387) instead of IoSkipCurrentIrpStackLocation. If a badly written driver makes the mistake of calling IoSkipCurrentIrpStackLocation and then setting a completion routine, this driver might overwrite a completion routine set by the driver below it.

+

If the driver has pended an IRP, the driver should not be calling IoSkipCurrentIrpStackLocation before it passes the IRP to the next lower driver. If the driver calls IoSkipCurrentIrpStackLocation on a pended IRP before passing it to the next lower driver, the SL_PENDING_RETURNED flag is still set in the Control member of the I/O stack location for the next driver. Because the next driver owns that stack location and might modify it, it could potentially clear the pending flag. This situation might cause the operating system to issue a bug check or the processing of the IRP to never be completed.

+

Instead, a driver that has pended an IRP should call IoCopyCurrentIrpStackLocationToNext to set up a new stack location for the next lower driver before it calls IoCallDriver.

+

If your driver calls IoSkipCurrentIrpStackLocation, be careful not to modify the IO_STACK_LOCATION structure in a way that could unintentionally affect the lower driver or the system's behavior with respect to that driver. Examples include modifying the IO_STACK_LOCATION structure's Parameters union or calling [IoMarkIrpPending](https://msdn.microsoft.com/library/windows/hardware/ff549422).

+

Available starting with Windows 2000.

+

IRQL: Any level

KeInitializeCallbackRecord

Wdm.h

The KeInitializeCallbackRecord macro initializes a [KBUGCHECK_CALLBACK_RECORD](https://msdn.microsoft.com/library/windows/hardware/ff551853) or [KBUGCHECK_REASON_CALLBACK_RECORD](https://msdn.microsoft.com/library/windows/hardware/ff551873) structure.

+

CallbackRecord [in]

+

PKBUGCHECK_CALLBACK_RECORD

+

Pointer to either a KBUGCHECK_CALLBACK_RECORD or a KBUGCHECK_REASON_CALLBACK_RECORD structure. The structure must be in resident memory, such as nonpaged pool.

+

Return value

+

VOID

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

MM_BAD_POINTER

Wdm.h

Your driver can use the MM_BAD_POINTER macro as a bad pointer value to assign to a pointer variable that is either uninitialized or no longer valid. An attempt to access the memory location pointed to by this invalid pointer variable will cause a bug check.

+

On many hardware platforms, address 0 (frequently represented as named constant NULL) is an invalid address, but driver developers should not assume that address 0 is universally invalid across all platforms. Setting uninitialized or invalid pointer variables to address 0 might not always guarantee that inappropriate accesses through these pointers will be detected.

+

In contrast, the value MM_BAD_POINTER is guaranteed to be an invalid address on every platform on which a driver runs.

+

On platforms on which address 0 is an invalid address, a driver that accesses address 0 at IRQL < DISPATCH_LEVEL causes an exception (access violation) that can be inadvertently caught by a try/except statement. Thus, the driver's exception handling code might mask the invalid access and prevent it from being detected during debugging. However, an access of the MM_BAD_POINTER address is guaranteed to cause a bug check, which cannot be masked by an exception handler.

+

The following code example shows how to assign the value MM_BAD_POINTER to a pointer variable named ptr. The Ntdef.h header file defines the PUCHAR type to be a pointer to an unsigned char.

+
+``` +PUCHAR ptr = (PUCHAR)MM_BAD_POINTER; // Now *ptr is guaranteed to fault. +``` +
+

After ptr is set to MM_BAD_POINTER, an attempt to access the memory location pointed to by ptr will cause a bug check.

+

In fact, MM_BAD_POINTER is the base address of an entire page of invalid addresses. Therefore, any access of an address in the range MM_BAD_POINTER to (MM_BAD_POINTER + PAGE_SIZE - 1) will cause a bug check.

+

Starting with Windows 8.1, the MM_BAD_POINTER macro is defined in the Wdm.h header file. However, driver code that uses this macro definition can run in previous versions of Windows starting with Windows Vista.

+

Starting with Windows Vista, the [MmBadPointer](https://msdn.microsoft.com/library/windows/hardware/ff554494) global variable is available as a pointer to a pointer value that is guaranteed to be an invalid address. However, starting with Windows 8.1, the use of MmBadPointer is deprecated, and you should update your drivers to use the MM_BAD_POINTER macro instead.

+Available starting with Windows 8.1. Compatible with previous versions of Windows starting with Windows Vista.
MmGetMdlByteCount

Wdm.h

The MmGetMdlByteCount macro returns the length, in bytes, of the buffer described by the specified MDL.

+

Mdl [in]

+

PMDL

+

A pointer to an [MDL](https://msdn.microsoft.com/library/windows/hardware/ff554414) structure that describes the layout of a virtual memory buffer in physical memory. For more information, see [Using MDLs](using-mdls.md).

+

Return value

+

ULONG

+

MmGetMdlByteCount returns the length, in bytes, of the buffer described by Mdl.

+

Callers of MmGetMdlByteCount can be running at any IRQL. Usually, callers are running at IRQL <= DISPATCH_LEVEL.

+

Available starting with Windows 2000.

+

IRQL: Any level

MmGetMdlByteOffset

Wdm.h

The MmGetMdlByteOffset macro returns the byte offset within the initial page of the buffer described by the given MDL.

+

Mdl [in]

+

PMDL

+

Pointer to an MDL.

+

Return value

+

ULONG

+

MmGetMdlByteOffset returns the offset in bytes.

+

Callers of MmGetMdlByteOffset can be running at any IRQL. Usually, callers are running at IRQL <= DISPATCH_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

MmGetMdlPfnArray

Wdm.h

The MmGetMdlPfnArray macro returns a pointer to the beginning of the array of physical page numbers that are associated with a memory descriptor list (MDL).

+

Mdl [in]

+

PMDL

+

A pointer to an MDL.

+

Return value

+

PPFN_NUMBER

+

A pointer to the beginning of the array of physical page numbers associated with the MDL. The number of entries in the array is ADDRESS_AND_SIZE_TO_SPAN_PAGES(MmGetMdlVirtualAddress(Mdl), MmGetMdlByteCount(Mdl)). Each array element is an integer value of type PFN_NUMBER, which is defined in Wdm.h as follows:

+
+``` +typedef ULONG PFN_NUMBER, *PPFN_NUMBER; +``` +
+
+Note  Changing the contents of the array can cause subtle system problems that are difficult to diagnose. We recommend that you do not read or change the contents of this array. +
+
+  +
+

For pageable memory, the contents of the array are valid only for a buffer locked with [MmProbeAndLockPages](https://msdn.microsoft.com/library/windows/hardware/ff554664). For nonpaged pool, the contents of the array are valid only for an MDL updated with [MmBuildMdlForNonPagedPool](https://msdn.microsoft.com/library/windows/hardware/ff554498), [MmAllocatePagesForMdlEx](https://msdn.microsoft.com/library/windows/hardware/ff554489), or [MmAllocatePagesForMdl](https://msdn.microsoft.com/library/windows/hardware/ff554482).

+

For more information about MDLs, see [Using MDLs](using-mdls.md).

+

Available starting with Windows 2000.

+

IRQL: Any level

MmGetMdlVirtualAddress

Wdm.h

The MmGetMdlVirtualAddress macro returns the base virtual address of a buffer described by an MDL.

+

Mdl [in]

+

PMDL

+

Pointer to an MDL that describes the buffer for which to return the initial virtual address.

+

Return value

+

PVOID

+

MmGetMdlVirtualAddress returns the starting virtual address of the MDL.

+

MmGetMdlVirtualAddress returns a virtual address that is not necessarily valid in the current thread context. Lower-level drivers should not attempt to use the returned virtual address to access memory, particularly user memory space.

+

The returned address, used as an index to a physical address entry in the MDL, can be input to [MapTransfer](https://msdn.microsoft.com/library/windows/hardware/ff554402).

+

Callers of MmGetMdlVirtualAddress can be running at any IRQL. Usually, the caller is running at IRQL = DISPATCH_LEVEL because this routine is commonly called to obtain the CurrentVa parameter to MapTransfer.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

MmGetSystemAddressForMdlSafe

Wdm.h

The MmGetSystemAddressForMdlSafe macro returns a nonpaged system-space virtual address for the buffer that the specified MDL describes.

+

Mdl [in]

+

PMDL

+

Pointer to a buffer whose corresponding base virtual address is to be mapped.

+

Priority [in]

+

MM_PAGE_PRIORITY

+

Specifies an MM_PAGE_PRIORITY value that indicates the importance of success under low available PTE conditions. Specify a priority value of LowPagePriority, NormalPagePriority, or HighPagePriority. Starting with Windows 8, the specified priority value can be bitwise-ORed with the MdlMappingNoWrite or MdlMappingNoExecute flags.

+
    +
  • LowPagePriority indicates that the mapping request can fail if the system is fairly low on resources. An example of this situation is a noncritical network connection where the driver can handle the mapping failure.

  • +
  • NormalPagePriority indicates that the mapping request can fail if the system is very low on resources. An example of this situation is a noncritical local file system request.

  • +
  • HighPagePriority indicates that the mapping request must not fail unless the system is completely out of resources. An example of this situation is the paging file path in a driver.

  • +
  • MdlMappingNoWrite indicates that the mapped physical pages are to be configured as no-write (read only) memory. Starting with Windows 8, this flag bit can be bitwise-ORed with the MM_PAGE_PRIORITY value to specify memory in which writes are disabled.

  • +
  • MdlMappingNoExecute indicates that the mapped physical pages are to be configured as no-execute memory. Starting with Windows 8, this flag bit can be bitwise-ORed with the MM_PAGE_PRIORITY value to specify memory in which instruction execution is disabled. As a best practice, drivers written for Windows 8 and later versions of Windows should always specify no-execute memory unless executable memory is explicitly required.

  • +
  • Return value

    +

    PVOID

    +

    MmGetSystemAddressForMdlSafe returns the base system-space virtual address that maps the physical pages that the specified MDL describes. If the pages are not already mapped to system address space and the attempt to map them fails, NULL is returned.

  • +
+

This routine maps the physical pages that are described by the specified MDL into system address space, if they are not already mapped to system address space.

+

Drivers of programmed-I/O (PIO) devices call this routine to map a user-mode buffer, which is described by the MDL at Irp->MdlAddress and which is already mapped to a user-mode virtual address range, to a range in system address space.

+

On entry to this routine, the specified MDL must describe physical pages that are locked down. A locked-down MDL can be built by using the [MmProbeAndLockPages](https://msdn.microsoft.com/library/windows/hardware/ff554664), [MmBuildMdlForNonPagedPool](https://msdn.microsoft.com/library/windows/hardware/ff554498), [IoBuildPartialMdl](https://msdn.microsoft.com/library/windows/hardware/ff548324), or [MmAllocatePagesForMdlEx](https://msdn.microsoft.com/library/windows/hardware/ff554489) routine.

+

When the system-address-space mapping that is returned by MmGetSystemAddressForMdlSafe is no longer needed, it must be released. The steps that are required to release the mapping depend on how the MDL was built. These are the four possible cases:

+
    +
  • If the MDL was built by a call to the MmProbeAndLockPages routine, it is not necessary to explicitly release the system-address-space mapping. Instead, a call to the [MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381) routine releases the mapping, if one was allocated.

  • +
  • If the MDL was built by a call to the MmBuildMdlForNonPagedPool routine, MmGetSystemAddressForMdlSafe reuses the existing system-address-space mapping instead of creating a new one. In this case, no cleanup is required (that is, unlocking and unmapping are not necessary).

  • +
  • If the MDL was built by a call to the IoBuildPartialMdl routine, the driver must call either the [MmPrepareMdlForReuse](https://msdn.microsoft.com/library/windows/hardware/ff554660) routine or the [IoFreeMdl](https://msdn.microsoft.com/library/windows/hardware/ff549126) routine to release the system-address-space mapping.

  • +
  • If the MDL was built by a call to the MmAllocatePagesForMdlEx routine, the driver must call the MmUnmapLockedPages routine to release the system-address-space mapping. If MmGetSystemAddressForMdlSafe is called more than one time for an MDL, subsequent MmGetSystemAddressForMdlSafe calls simply return the mapping that was created by the first call. One call to MmUnmapLockedPages is sufficient to release this mapping.

  • +
+

Starting with Windows 7 and Windows Server 2008 R2, it is not necessary to explicitly call MmUnmapLockedPages for an MDL that was created by MmAllocatePagesForMdlEx. Instead, a call to the [MmFreePagesFromMdl](https://msdn.microsoft.com/library/windows/hardware/ff554521) routine releases the system-address-space mapping, if one was allocated.

+

To create a new system-address-space mapping, MmGetSystemAddressForMdlSafe calls MmMapLockedPagesSpecifyCache with the CacheType parameter set to MmCached. A driver that requires a cache type other than MmCached should call MmMapLockedPagesSpecifyCache directly instead of calling MmGetSystemAddressForMdlSafe. For more information about the CacheType parameter, see [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629).

+

In a call to MmMapLockedPagesSpecifyCache, the specified cache type is used only if the pages that are described by the MDL do not already have a cache type associated with them. However, in nearly all cases, the pages already have an associated cache type, and this cache type is used by the new mapping. An exception to this rule is for pages that are allocated by MmAllocatePagesForMdl, which sets the cache type to MmCached regardless of the original cache type of the pages.

+

Only one thread at a time can safely call MmGetSystemAddressForMdlSafe for a particular MDL because this routine assumes that the calling thread owns the MDL. However, MmGetSystemAddressForMdlSafe can be called more than one time for the same MDL either by making all calls from the same thread or, if the calls are from multiple threads, by explicitly synchronizing the calls.

+

If a driver must split a request into smaller requests, the driver can allocate additional MDLs, or the driver can use the IoBuildPartialMdl routine.

+

The returned base address has the same offset as the virtual address in the MDL.

+

Windows 98 does not support MmGetSystemAddressForMdlSafe. Use [MmGetSystemAddressForMdl](https://msdn.microsoft.com/library/windows/hardware/ff554556) instead.

+

Because this macro calls [MmMapLockedPagesSpecifyCache](https://msdn.microsoft.com/library/windows/hardware/ff554629), using it may require linking to NtosKrnl.lib.

+

Available starting with Windows 2000.

+

IRQL <= DISPATCH_LEVEL

MmInitializeMdl

Wdm.h

The MmInitializeMdl macro initializes the header of an MDL.

+

MemoryDescriptorList [in]

+

PMDL

+

A pointer to the buffer to initialize as an MDL. For more information, see the following section.

+

BaseVa [in]

+

PVOID

+

A pointer to the base virtual address of a buffer.

+

Length [in]

+

SIZE_T

+

Specifies the length, in bytes, of the buffer to be described by the MDL. This routine supports a maximum buffer length of MAXULONG bytes.

+

Return value

+

VOID

+

The buffer that MemoryDescriptorList points to must be allocated in nonpaged memory. The size, in bytes, of this buffer must be at least sizeof(MDL) + sizeof(PFN_NUMBER)*ADDRESS_AND_SIZE_TO_SPAN_PAGES(BaseVa, Length).

+

Available in Windows 2000 and later versions of Windows.

+

IRQL <= DISPATCH_LEVEL

MmPrepareMdlForReuse

Wdm.h

The MmPrepareMdlForReuse macro releases the resources that are associated with a partial MDL so that the MDL can be reused.

+

Mdl [in]

+

PMDL

+

A pointer to a partial MDL that is to be prepared for reuse.

+

Return value

+

VOID

+

This macro is used by drivers that repeatedly use the same allocated MDL for the TargetMdl parameter in calls to the [IoBuildPartialMdl](https://msdn.microsoft.com/library/windows/hardware/ff548324) routine. If, in a call to MmPrepareMdlForReuse, the specified partial MDL has an associated mapping to system address space, MmPrepareMdlForReuse releases the mapping so that the MDL can be reused.

+

MmPrepareMdlForReuse accepts only partial MDLs that are built by IoBuildPartialMdl. If MmPrepareMdlForReuse receives an MDL that is mapped to the system address space but was not built by IoBuildPartialMdl, MmPrepareMdlForReuse does not release the mapping, and, in checked builds, causes an assertion to fail.

+

For more information about partial MDLs, see [Using MDLs](using-mdls.md).

+

Available in Windows 2000 and later versions of Windows.

+

IRQL <= DISPATCH_LEVEL

PAGE_ALIGN

Wdm.h

The PAGE_ALIGN macro returns a page-aligned virtual address for a given virtual address.

+

Va [in]

+

PVOID

+

Pointer to the virtual address.

+

Return value

+

PVOID

+

PAGE_ALIGN returns a pointer to the page-aligned virtual address.

+

Available starting with Windows 2000.

+

IRQL: Any level

PAGED_CODE

Wdm.h

The PAGED_CODE macro ensures that the calling thread is running at an IRQL that is low enough to permit paging.

+

Return value

+

VOID

+

If the IRQL > APC_LEVEL, the PAGED_CODE macro causes the system to ASSERT.

+

A call to this macro should be made at the beginning of every driver routine that either contains pageable code or accesses pageable code.

+

The PAGED_CODE macro checks the IRQL only at the point at which the driver code executes the macro. If the code subsequently raises the IRQL, the macro will not detect this change. Driver developers should use [Static Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff552808) and [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) to detect when the IRQL is raised improperly during the execution of a driver routine.

+

The PAGED_CODE macro works only in checked builds.

+

Available starting with Windows 2000.

PAGED_CODE_LOCKED

Wdm.h

The PAGED_CODE_LOCKED macro asserts that the currently running code section is pageable and must have been locked into memory before it was run.

+

Return value

+

VOID

+

Pageable code must obey certain restrictions (such as IRQL <= APC_LEVEL), unless it is locked into place. A pageable routine that must be locked into place to work correctly should begin with a call to PAGED_CODE_LOCKED.

+

For more information about locking a code section into place, see [Locking Pageable Code or Data](locking-pageable-code-or-data.md).

PoSetDeviceBusy

Wdm.h

The PoSetDeviceBusy macro notifies the [power manager](power-manager.md) that the device associated with IdlePointer is busy.

+

IdlePointer [in, out]

+

PULONG

+

Specifies a non-NULL idle pointer that was previously returned by [PoRegisterDeviceForIdleDetection](https://msdn.microsoft.com/library/windows/hardware/ff559721). Note that PoRegisterDeviceForIdleDetection might return a NULL pointer. A caller of PoSetDeviceBusy must verify that the pointer is non-NULL before passing it to PoSetDeviceBusy.

+

Return value

+

VOID

+
+Note   The [PoSetDeviceBusyEx](https://msdn.microsoft.com/library/windows/hardware/ff559759) routine is a direct replacement for the PoSetDeviceBusy macro. If you are writing new driver code for Windows Vista with Service Pack 1 (SP1) and later versions of Windows, call PoSetDeviceBusyEx instead of PoSetDeviceBusy. +
+
+  +
+

A driver uses PoSetDeviceBusy along with PoRegisterDeviceForIdleDetection to enable system idle detection for its device. If a device that is registered for idle detection becomes idle, the power manager sends an [IRP_MN_SET_POWER](https://msdn.microsoft.com/library/windows/hardware/ff551744) request to put the device in a requested sleep state.

+

PoSetDeviceBusy reports that the device is busy, so that the power manager can restart its idle countdown. If the device is not powered up, PoSetDeviceBusy does not change its state. That is, it does not cause the system to send a power-on request.

+

A driver should call PoSetDeviceBusy on every I/O request.

+

Available starting with Windows 2000.

+

IRQL: Any level

READ_REGISTER_BUFFER_ULONG64

Wdm.h

The READ_REGISTER_BUFFER_ULONG64 macro reads a number of ULONG64 values from the specified register address into a buffer.

+

Register [in]

+

PULONG64

+

Pointer to the register, which must be a mapped range in memory space.

+

Buffer [out]

+

PULONG64

+

Pointer to a buffer that an array of ULONG64 values is read into.

+

Count [in]

+

ULONG

+

Specifies the number of ULONG64 values to be read into the buffer.

+

Return value

+

VOID

+

The size of the Buffer buffer must be large enough to contain at least the specified number of ULONG64 values.

+

Callers of the READ_REGISTER_BUFFER_ULONG64 macro can be running at any IRQL, assuming that the Buffer buffer is resident and the Register register is resident, mapped device memory.

+

Available only in 64-bit versions of Windows.

+

IRQL: Any level

READ_REGISTER_ULONG64

Wdm.h

The READ_REGISTER_ULONG64 macro reads a ULONG64 value from the specified register address.

+

volatile *Register [in]

+

ULONG64

+

Pointer to the register address, which must be a mapped range in memory space.

+

Return value

+

ULONG64

+

READ_REGISTER_ULONG64 returns the ULONG64 value that is read from the specified register address.

+

Callers of the READ_REGISTER_ULONG64 macro can be running at any IRQL, assuming the Register address is resident, mapped device memory.

+

Available only in 64-bit versions of Windows.

+

IRQL: Any level

ROUND_TO_PAGES

Wdm.h

The ROUND_TO_PAGES macro takes a size in bytes and rounds it up to the next full page.

+

Size [in]

+

ULONG_PTR

+

Specifies the size in bytes to round up to a page multiple.

+

Return value

+

ULONG_PTR

+

ROUND_TO_PAGES returns the input size rounded up to a multiple of the virtual memory page size for the current platform.

+

Callers of ROUND_TO_PAGES can be running at any IRQL. The caller must ensure that the supplied parameter cannot cause memory overflow.

+

IRQL: Any level

RtlEqualLuid

Wdm.h

+

+

+

Return value

+

+

Available starting with Windows 2000.

+

IRQL: Any level

RtlInitEmptyAnsiString

Wdm.h

The RtlInitEmptyAnsiString macro initializes an empty counted ANSI string.

+

DestinationString [out]

+

PANSI_STRING

+

Pointer to the [ANSI_STRING](https://msdn.microsoft.com/library/windows/hardware/ff540605) structure to be initialized.

+

Buffer [in]

+

PCHAR

+

Pointer to a caller-allocated buffer to be used to contain a WCHAR string.

+

BufferSize [in]

+

USHORT

+

Length, in bytes, of the buffer that Buffer points to.

+

Return value

+

VOID

+

The members of the structure that the DestinationString parameter points to are initialized as follows.

+
    +
  • Length. Zero.

  • +
  • MaximumLength. BufferSize.

  • +
  • Buffer. SourceString.

  • +
+

To initialize a non-empty counted Unicode string, call [RtlInitAnsiString](https://msdn.microsoft.com/library/windows/hardware/ff561918).

+

Available in Microsoft Windows XP and later versions of Windows.

+

IRQL: Any level

RtlInitEmptyUnicodeString

Wdm.h

The RtlInitEmptyUnicodeString macro initializes an empty counted Unicode string.

+

DestinationString [out]

+

PUNICODE_STRING

+

Pointer to the [UNICODE_STRING](https://msdn.microsoft.com/library/windows/hardware/ff564879) structure to be initialized.

+

Buffer [in]

+

PWCHAR

+

Pointer to a caller-allocated buffer to be used to contain a WCHAR string.

+

BufferSize [in]

+

USHORT

+

Length, in bytes, of the buffer that Buffer points to.

+

Return value

+

VOID

+

The members of the structure that the DestinationString parameters points to are initialized as follows.

+
    +
  • Length. Zero.

  • +
  • MaximumLength. BufferSize.

  • +
  • Buffer. SourceString.

  • +
+

To initialize a non-empty counted Unicode string, call [RtlInitUnicodeString](https://msdn.microsoft.com/library/windows/hardware/ff561934).

+

Available starting with Windows XP.

+

IRQL: Any level

RtlIsZeroLuid

Ntddk.h

The RtlIsZeroLuid macro determines if the specified LUID is the zero LUID.

+

L1 [in]

+

PLUID

+

Specifies the [LUID](https://msdn.microsoft.com/library/windows/hardware/ff554334) to check.

+

Return value

+

BOOLEAN

+

RtlIsZeroLuid returns TRUE if L1 is zero, and returns FALSE otherwise.

+

IRQL: Any level

RtlRetrieveUlong

Wdm.h

The RtlRetrieveUlong macro retrieves a ULONG value from the source address, avoiding alignment faults. The destination address is assumed to be aligned.

+

DestinationAddress [out]

+

PULONG

+

Pointer to a ULONG-aligned location in which to store the ULONG value.

+

SourceAddress [in]

+

PULONG

+

Pointer to a location from which to retrieve the ULONG value.

+

Return value

+

VOID

+

Callers of RtlRetrieveUlong can be running at any IRQL if the given addresses are in nonpaged pool. Otherwise, the caller must be running at IRQL <= APC_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

RtlRetrieveUshort

Wdm.h

The RtlRetrieveUshort macro retrieves a USHORT value from the source address, avoiding alignment faults.

+

DestinationAddress [out]

+

PUSHORT

+

Pointer to a USHORT-aligned location in which to store the value.

+

SourceAddress [in]

+

PUSHORT

+

Pointer to a location from which to retrieve the value.

+

Return value

+

VOID

+

Callers of RtlRetrieveUshort can be running at any IRQL if the given addresses are in nonpaged pool. Otherwise, the caller must be running at IRQL <= APC_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

RtlStoreUlong

Wdm.h

The RtlStoreUlong macro stores a ULONG value at a particular address, avoiding alignment faults.

+

Address [out]

+

PULONG

+

A pointer to a location in which to store the specified ULONG value.

+

Value [in]

+

ULONG

+

Specifies a ULONG value to be stored.

+

Return value

+

VOID

+

The caller can be running at any IRQL if Address points to nonpaged pool. Otherwise, the caller must be running at IRQL <= APC_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

RtlStoreUlonglong

Wdm.h

The RtlStoreUlonglong macro stores a specified ULONGLONG value at a specified memory address, avoiding memory alignment faults.

+

Address [out]

+

PULONGLONG

+

A pointer to a location in which to store the specified ULONGLONG value.

+

Value [in]

+

ULONGLONG

+

The ULONGLONG value to be stored.

+

Return value

+

VOID

+

RtlStoreUlonglong avoids memory alignment faults. If the address specified by Address is not aligned to the storage requirements of a ULONGLONG, RtlStoreUlonglong stores the bytes of Value beginning at the memory location (PUCHAR)Address.

+

RtlStoreUlonglong runs at any IRQL if Address points to nonpaged pool; otherwise, it must run at IRQL <= APC_LEVEL.

+

Available starting with Windows 2000.

+

IRQL: Any level

RtlStoreUlongPtr

Wdm.h

The RtlStoreUlongPtr macro stores a specified ULONG_PTR value at a specified memory location, avoiding memory alignment faults.

+

Address [out]

+

PULONG_PTR

+

A pointer to a location in which to store the ULONG_PTR value.

+

Value [in]

+

ULONG_PTR

+

Specifies the ULONG_PTR value to be stored.

+

Return value

+

VOID

+

RtlStoreUlongPtr avoids memory alignment faults. If the value of Address is not aligned to the storage requirements of a ULONG_PTR, RtlStoreUlongPtr stores the bytes of Value beginning at the memory location (PUCHAR)Address.

+

RtlStoreUlongPtr runs at any IRQL if Address points to nonpaged pool; otherwise it must run at IRQL <= APC_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

RtlStoreUshort

Wdm.h

The RtlStoreUshort macro stores a USHORT value at a particular address, avoiding alignment faults.

+

Address [out]

+

PUSHORT

+

A pointer to a location in which to store the specified USHORT value.

+

Value [in]

+

USHORT

+

Specifies a USHORT value to be stored.

+

Return value

+

VOID

+

The caller can be running at any IRQL if Address points to nonpaged pool. Otherwise, the caller must be running at IRQL <= APC_LEVEL.

+

Available in Windows 2000 and later versions of Windows.

+

IRQL: Any level

WRITE_REGISTER_BUFFER_ULONG64

Wdm.h

The WRITE_REGISTER_BUFFER_ULONG64 macro writes a number of ULONG64 values from a buffer to the specified register.

+

Register [in]

+

PULONG64

+

Pointer to the register, which must be a mapped range in memory space.

+

Buffer [in]

+

PULONG64

+

Pointer to a buffer that an array of ULONG64 values is to be written to.

+

Count [in]

+

ULONG

+

Specifies the number of ULONG64 values to be written to the register.

+

Return value

+

VOID

+

The size of the Buffer buffer must be large enough to contain at least the specified number of ULONG64 values.

+

Callers of the WRITE_REGISTER_BUFFER_ULONG64 macro can be running at any IRQL, assuming that the Buffer buffer is resident and the Register register is resident, mapped device memory.

+

Available only in 64-bit versions of Windows.

+

IRQL: Any level

WRITE_REGISTER_ULONG64

Wdm.h

The WRITE_REGISTER_ULONG64 macro writes a ULONG64 value to the specified address.

+

volatile *Register [in]

+

ULONG64

+

Pointer to the register, which must be a mapped range in memory space.

+

Value [in]

+

ULONG64

+

Specifies a ULONG64 value to write to the register.

+

Return value

+

VOID

+

Callers of the WRITE_REGISTER_ULONG64 macro can be running at any IRQL, assuming the Register register is resident, mapped device memory.

+

Available only in 64-bit versions of Windows.

+

IRQL: Any level

ZwCurrentProcess

Wdm.h

The ZwCurrentProcess macro returns a handle to the current process.

+

Return value

+

HANDLE

+

ZwCurrentProcess returns a special handle value that represents the current process.

+

The returned value is not a true handle, but it is a special value that always represents the current process.

+

NtCurrentProcess and ZwCurrentProcess are two versions of the same Windows Native System Services routine. The NtCurrentProcess routine in the Windows kernel is not directly accessible to kernel-mode drivers. However, kernel-mode drivers can access this routine indirectly by calling ZwCurrentProcess.

+

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see [Using Nt and Zw Versions of the Native System Services Routines](using-nt-and-zw-versions-of-the-native-system-services-routines.md).

+

All supported operating systems.

+

IRQL: Any level

ZwCurrentThread

Wdm.h

The ZwCurrentThread macro returns a handle to the current thread.

+

Return value

+

HANDLE

+

ZwCurrentThread returns a special handle value that represents the current thread.

+

The returned value is not a true handle, but it is a special value that always represents the current thread.

+

NtCurrentThread and ZwCurrentThread are two versions of the same Windows Native System Services routine. The NtCurrentThread routine in the Windows kernel is not directly accessible to kernel-mode drivers. However, kernel-mode drivers can access this routine indirectly by calling the ZwCurrentThread routine.

+

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see [Using Nt and Zw Versions of the Native System Services Routines](using-nt-and-zw-versions-of-the-native-system-services-routines.md).

+

All supported operating systems.

+

IRQL: Any level

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20macros%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mm64bitphysicaladdress.md b/windows-driver-docs-pr/kernel/mm64bitphysicaladdress.md new file mode 100644 index 0000000000..cd3b4abb9c --- /dev/null +++ b/windows-driver-docs-pr/kernel/mm64bitphysicaladdress.md @@ -0,0 +1,77 @@ +--- +title: Windows kernel global variables +author: windows-driver-content +description: Kernel global variables. +ms.assetid: 1ea5c4e3-ed70-449c-a49e-b1e3c892e981 +--- + +# Windows kernel global variables + + +Kernel global variables. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDeclarationDescription
Mm64BitPhysicalAddressPBOOLEAN Mm64BitPhysicalAddress +

Declared in Wdm.h

Specifies whether the hardware and operating system support 64-bit physical addresses. Points to a value that is TRUE if the hardware and operating system support 64-bit physical addresses, and is FALSE otherwise.

+

For more information about how to use this variable in your driver, see [Performing DMA in 64-Bit Windows](performing-dma-in-64-bit-windows.md).

MmBadPointerPVOID MmBadPointer; +

Declared in Wdm.h

A pointer to a memory location that is guaranteed to be invalid.

+
+Note  Starting with Windows 8.1, MmBadPointer is deprecated. Drivers should use the [MM_BAD_POINTER](mm-bad-pointer.md) macro instead. +
+
+  +
+

The operating system generates a bug check if the memory address that is specified by the MmBadPointer variable is accessed.

+

You can use MmBadPointer to debug your driver code. Set any uninitialized pointer variables to MmBadPointer to find the first time that your code tries to dereference an invalid pointer.

+

All addresses within PAGE_SIZE of MmBadPointer are guaranteed to be invalid. For example, if Address is a pointer and if MmBadPointer <= Address < MmBadPointer + PAGE_SIZE, attempts to access *Address causes the operating system to generate a bug check. MmBadPointer + PAGE_SIZE is not guaranteed to be invalid.

PsInitialSystemProcessPEPROCESS PsInitialSystemProcess; +

Declared in Ntddk.h

Points to the [EPROCESS](eprocess.md) structure for the system process.

NLS_MB_CODE_PAGE_TAGextern BOOLEAN NLS_MB_CODE_PAGE_TAG;

Specifies whether a code page is a single-byte or multibyte code page.

+

NLS_MB_CODE_PAGE_TAG is TRUE for multibyte code pages and FALSE for single-byte code pages.

+

NLS_MB_CODE_PAGE_TAG is reserved for system use. From user mode, call [GetCPInfoEx](http://go.microsoft.com/fwlink/p/?linkid=121902) instead.

+

When possible, your application should use Unicode instead of code pages.

+ +  + +## Related topics +[**EPROCESS**](eprocess.md) +[GetCPInfoEx](http://go.microsoft.com/fwlink/p/?linkid=121902) +[**MM\_BAD\_POINTER**](mm-bad-pointer.md) +[Performing DMA in 64-Bit Windows](performing-dma-in-64-bit-windows.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20global%20variables%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mmcreatemdl.md b/windows-driver-docs-pr/kernel/mmcreatemdl.md new file mode 100644 index 0000000000..11d072fa61 --- /dev/null +++ b/windows-driver-docs-pr/kernel/mmcreatemdl.md @@ -0,0 +1,206 @@ +--- +title: Windows kernel obsolete routines +author: windows-driver-content +description: Windows kernel obsolete routines +ms.assetid: 876f48be-1d8f-4c65-bc84-e35c31919c47 +--- + +# Windows kernel obsolete routines + + +The following obsolete routines are exported to support existing binaries: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Obsolete routineDescription
ExAcquireResourceExclusive

Use [ExAcquireResourceExclusiveLite](https://msdn.microsoft.com/library/windows/hardware/ff544351) instead.

ExAcquireResourceShared

Use [ExAcquireResourceSharedLite](https://msdn.microsoft.com/library/windows/hardware/ff544363) instead.

ExAllocateFromZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExConvertExclusiveToShared

Use [ExConvertExclusiveToSharedLite](https://msdn.microsoft.com/library/windows/hardware/ff544558) instead.

ExDeleteResource

Use [ExDeleteResourceLite](https://msdn.microsoft.com/library/windows/hardware/ff544578) instead.

ExExtendZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExFreeToZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExInitializeResource

Use [ExInitializeResourceLite](https://msdn.microsoft.com/library/windows/hardware/ff545317) instead.

ExInitializeWorkItem

Use [IoAllocateWorkItem](https://msdn.microsoft.com/library/windows/hardware/ff548276) instead.

ExInitializeZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExInterlockedAllocateFromZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExInterlockedDecrementLong

Use [InterlockedDecrement](https://msdn.microsoft.com/library/windows/hardware/ff547871) instead.

ExInterlockedExchangeAddLargeInteger

For more information about atomically adding two 64-bit numbers, see [InterlockedExchangeAdd64](http://go.microsoft.com/fwlink/p/?linkid=71056).

ExInterlockedExchangeUlong

Use [InterlockedExchange](https://msdn.microsoft.com/library/windows/hardware/ff547892) instead.

ExInterlockedExtendZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExInterlockedFreeToZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExInterlockedIncrementLong

Use [InterlockedIncrement](https://msdn.microsoft.com/library/windows/hardware/ff547910) instead.

ExIsFullZone

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExIsObjectInFirstZoneSegment

Use lookaside lists instead. For more information, see [Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667).

ExIsResourceAcquired

Use [ExIsResourceAcquiredLite](https://msdn.microsoft.com/library/windows/hardware/ff545466) instead.

ExIsResourceAcquiredExclusive

Use [ExIsResourceAcquiredExclusiveLite](https://msdn.microsoft.com/library/windows/hardware/ff545458) instead.

ExIsResourceAcquiredShared

Use [ExIsResourceAcquiredSharedLite](https://msdn.microsoft.com/library/windows/hardware/ff545477) instead.

ExReleaseResource

Use [ExReleaseResourceLite](https://msdn.microsoft.com/library/windows/hardware/ff545597) instead.

ExReleaseResourceForThread

Use [ExReleaseResourceForThreadLite](https://msdn.microsoft.com/library/windows/hardware/ff545585) instead.

IoAllocateAdapterChannel

Use [AllocateAdapterChannel](https://msdn.microsoft.com/library/windows/hardware/ff540573) instead.

IoAssignResources

Drivers of PnP devices are assigned resources by the PnP manager, which passes resource lists with each [IRP_MN_START_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. Drivers that must support a legacy device that cannot be enumerated by the PnP manager should use [IoReportDetectedDevice](https://msdn.microsoft.com/library/windows/hardware/ff549597) and [IoReportResourceForDetection](https://msdn.microsoft.com/library/windows/hardware/ff549608) instead.

IoAttachDeviceByPointer

Use [IoAttachDeviceToDeviceStack](https://msdn.microsoft.com/library/windows/hardware/ff548300) instead.

IoFlushAdapterBuffers

Use [FlushAdapterBuffers](https://msdn.microsoft.com/library/windows/hardware/ff545917) instead.

IoFreeAdapterChannel

Use [FreeAdapterChannel](https://msdn.microsoft.com/library/windows/hardware/ff546507) instead.

IoFreeMapRegisters

Use [FreeMapRegisters](https://msdn.microsoft.com/library/windows/hardware/ff546513) instead.

IoMapTransfer

Use [MapTransfer](https://msdn.microsoft.com/library/windows/hardware/ff554402) instead.

IoQueryDeviceDescription

This routine retrieves hardware configuration information about a given bus, controller or peripheral object, or any combination of these three types from the \Registry\Machine\Hardware\Description tree. Drivers that require hardware configuration information should use [IoGetDeviceProperty](https://msdn.microsoft.com/library/windows/hardware/ff549203) instead.

IoReportResourceUsage

This routine claims hardware resources, such as an interrupt vector, device memory range or a particular DMA controller channel in the \Registry\Machine\Hardware\ResourceMap tree, so that a subsequently loaded driver cannot attempt to use the same resources. If a new driver must support a legacy device that is not PnP-enumerable, the driver should call [IoReportResourceForDetection](https://msdn.microsoft.com/library/windows/hardware/ff549608) to claim resources for the device.

KeGetDcacheFillSize

Drivers should call [GetDmaAlignment](https://msdn.microsoft.com/library/windows/hardware/ff546530) instead.

MmCreateMdl

Use [IoAllocateMdl](https://msdn.microsoft.com/library/windows/hardware/ff548263) instead.

MmIsNonPagedSystemAddressValid
+ +  + +## Related topics +[**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) +[Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff540667) +[**ExAcquireResourceExclusiveLite**](https://msdn.microsoft.com/library/windows/hardware/ff544351) +[**ExAcquireResourceSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544363) +[**ExConvertExclusiveToSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff544558) +[**ExDeleteResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff544578) +[**ExInitializeResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff545317) +[**ExIsResourceAcquiredExclusiveLite**](https://msdn.microsoft.com/library/windows/hardware/ff545458) +[**ExIsResourceAcquiredSharedLite**](https://msdn.microsoft.com/library/windows/hardware/ff545477) +[**ExReleaseResourceForThreadLite**](https://msdn.microsoft.com/library/windows/hardware/ff545585) +[**ExReleaseResourceLite**](https://msdn.microsoft.com/library/windows/hardware/ff545597) +[**InterlockedDecrement**](https://msdn.microsoft.com/library/windows/hardware/ff547871) +[**InterlockedExchange**](https://msdn.microsoft.com/library/windows/hardware/ff547892) +[**InterlockedIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff547910) +[**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) +[**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) +[**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) +[**GetDmaAlignment**](https://msdn.microsoft.com/library/windows/hardware/ff546530) +[InterlockedExchangeAdd64](http://go.microsoft.com/fwlink/p/?linkid=71056) +[**IoAllocateMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548263) +[**IoAllocateWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff548276) +[**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300) +[**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) +[**IoReportDetectedDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549597) +[**IoReportResourceForDetection**](https://msdn.microsoft.com/library/windows/hardware/ff549608) +[**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) +[**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20obsolete%20routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mof-syntax-for-wmi-data-and-event-blocks.md b/windows-driver-docs-pr/kernel/mof-syntax-for-wmi-data-and-event-blocks.md new file mode 100644 index 0000000000..19c3baf26c --- /dev/null +++ b/windows-driver-docs-pr/kernel/mof-syntax-for-wmi-data-and-event-blocks.md @@ -0,0 +1,63 @@ +--- +title: MOF Syntax for WMI Data and Event Blocks +author: windows-driver-content +description: MOF Syntax for WMI Data and Event Blocks +ms.assetid: 247037b7-d62e-4f74-8fa4-57e74f6c412f +keywords: ["WMI WDK kernel , event blocks", "event blocks WDK WMI", "data blocks WDK WMI", "WMI WDK kernel , data blocks", "blocks WDK WMI", "MOF files WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# MOF Syntax for WMI Data and Event Blocks + + +## + + +A driver's WMI schema describes its data blocks, which define the information that a driver can provide and the methods it can execute in response to WMI requests. A driver's schema also describes its event blocks, which are data blocks that the driver sends to WMI when a driver-determined event occurs for which a WMI client user has requested notification. + +A driver writer defines a driver's schema in Managed Object Format (MOF). MOF is a compiled language created by the Desktop Management Task force (DMTF) and based on Interface Definition language (IDL). A driver's MOF file contains a MOF class definition for each data block and event block the driver exposes to WMI. + +A MOF class definition for a WMI data block follows this syntax: + +**\[***Required and optional class qualifiers***\]** + +**class***ClassName* : *OptionalBaseClass* +**{** +**\[key, read\]** +**string InstanceName;** +**\[read\]** +**boolean Active;** +**\[** *Required and optional property qualifiers* **\]** +*datatype itemname1***;** +**\[** *Required and optional property qualifiers* **\]** +*datatype itemnameN***;** +**};** +The following topics describe the syntax elements shown above: + +[WMI Class Qualifiers](wmi-class-qualifiers.md) + +[WMI Class Names and Base Classes](wmi-class-names-and-base-classes.md) + +[Required Items in WMI Classes](required-items-in-wmi-classes.md) + +[WMI Property Qualifiers](wmi-property-qualifiers.md) + +[Driver-Defined WMI Data Items](driver-defined-wmi-data-items.md) + +[WMI Class Examples](wmi-class-examples.md) + +For a general discussion of MOF syntax as it pertains to WMI clients and other kinds of applications, see the Microsoft Windows SDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20MOF%20Syntax%20for%20WMI%20Data%20and%20Event%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ms-dos-device-names.md b/windows-driver-docs-pr/kernel/ms-dos-device-names.md new file mode 100644 index 0000000000..29b158f8a3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/ms-dos-device-names.md @@ -0,0 +1,34 @@ +--- +title: MS-DOS Device Names +author: windows-driver-content +description: MS-DOS Device Names +ms.assetid: 9be6da8f-0641-4a67-9443-8e2056335bef +keywords: ["device objects WDK kernel , named", "named device objects WDK kernel", "device names WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# MS-DOS Device Names + + +## + + +This section contains the following subsections: + +[Introduction to MS-DOS Device Names](introduction-to-ms-dos-device-names.md) + +[Local and Global MS-DOS Device Names](local-and-global-ms-dos-device-names.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20MS-DOS%20Device%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/multiple-binary-opt-in-pool-nx-optin-auto.md b/windows-driver-docs-pr/kernel/multiple-binary-opt-in-pool-nx-optin-auto.md new file mode 100644 index 0000000000..519442fd80 --- /dev/null +++ b/windows-driver-docs-pr/kernel/multiple-binary-opt-in-pool-nx-optin-auto.md @@ -0,0 +1,32 @@ +--- +title: Multiple Binary Opt-In POOL_NX_OPTIN_AUTO +author: windows-driver-content +description: If you are a hardware vendor who supplies different driver binaries for different versions of Windows, you can use the POOL_NX_OPTIN_AUTO opt-in mechanism. +ms.assetid: 5E6759E3-3AF8-4427-BDD0-DB64B3D480A1 +--- + +# Multiple Binary Opt-In: POOL\_NX\_OPTIN\_AUTO + + +If you are a hardware vendor who supplies different driver binaries for different versions of Windows, you can use the POOL\_NX\_OPTIN\_AUTO opt-in mechanism. This porting aid builds a separate driver binary for Windows 8 and for each earlier version of Windows that your driver supports. + +To use this opt-in mechanism, define POOL\_NX\_OPTIN\_AUTO=1 for all source files that you want to opt-in. To do this, include the following preprocessor definition in the appropriate property page for your driver project: + +`C_DEFINES=$(C_DEFINES) -DPOOL_NX_OPTIN_AUTO=1` + +For most drivers, this definition is sufficient to enable the opt-in mechanism to create a different binary for each version of Windows that you support. + +## Implementation details + + +The POOL\_NX\_OPTIN\_AUTO definition redefines the **NonPagedPool** constant name to **NonPagedPoolNx**. The redefined pool type is still a compile-time constant. The macro that converts instances of the **NonPagedPool** constant name to **NonPagedPoolNx** also converts instances of **NonPagedPoolCacheAligned** to **NonPagedPoolNxCacheAligned.** + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Multiple%20Binary%20Opt-In:%20POOL_NX_OPTIN_AUTO%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/multiplexed-clfs-logs.md b/windows-driver-docs-pr/kernel/multiplexed-clfs-logs.md new file mode 100644 index 0000000000..8b03b4de77 --- /dev/null +++ b/windows-driver-docs-pr/kernel/multiplexed-clfs-logs.md @@ -0,0 +1,72 @@ +--- +title: Multiplexed CLFS Logs +author: windows-driver-content +description: Multiplexed CLFS Logs +ms.assetid: bbea9bdc-8bb8-4455-89c4-4735bad85ba0 +keywords: ["Common Log File System WDK kernel , multiplexed logs", "CLFS WDK kernel , multiplexed logs", "multiplexed logs WDK CLFS", "stable storage WDK CLFS", "storage WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Multiplexed CLFS Logs + + +## + + +A *multiplexed log* serves as stable storage for several streams. A *dedicated log* serves as stable storage for a single stream. This topic discusses multiplexed logs. For information about dedicated logs, see [Dedicated CLFS Logs](dedicated-clfs-logs.md). + +Each stream of a multiplexed log provides its clients with the illusion that their stream is the entire log. A client, in this context, is a driver, a thread, or some other unit of software that writes to and reads from a Common Log File System (CLFS) log. It is possible for a single stream to have several clients. Each client would have its own [**LOG\_FILE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff554316) structure, which represents an open instance of the stream. + +Consider the case of a multiplexed log that has two streams, each of which has one client. You can use the following procedure to create the log, the streams, and the client marshalling areas. + +1. On behalf of client 1, call [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) to obtain a pointer to a **LOG\_FILE\_OBJECT** structure. Set the *puszLogFileName* parameter to a string of the form "log:<log name>::<stream name>" where <log name> is a valid path on the underlying file system, and <stream name> is the name that you have chosen to give to the stream that will be used by client 1. For example, you could set *puszLogFileName* to "log:c:\\ClfsLogs\\myLog::Stream1". In that case, CLFS would create the base log file myLog.blf in the c:\\ClfsLogs directory, and Stream1 would be the name of the stream used by client 1. + + **Note**  It is the form of the string passed in *puszLogFileName* that determines whether CLFS creates a dedicated or multiplexed log. If the string has a double colon (::) after the path name, then CLFS creates a multiplexed log. + +   + +2. On behalf of client 2, call [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) to obtain a pointer to a **LOG\_FILE\_OBJECT** structure. Set the *puszLogFileName* parameter to a string of the form "log:<log name>::<stream name>" where <log name> is the same path name you used for client 1, and <stream name> is the name that you have chosen to give to the stream that will be used by client 2. For example, you could set *puszLogFileName* to "log:c:\\ClfsLogs\\myLog::Stream2". + +3. Pass one of the **LOG\_FILE\_OBJECT** pointers you obtained from **ClfsCreateLogFile** to [**ClfsAddLogContainer**](https://msdn.microsoft.com/library/windows/hardware/ff540768) to create a container (contiguous physical extent) on stable storage that will hold log records. Specify the size of the container (which will be rounded up to a multiple of 1 megabyte) by setting the *pcbContainer* parameter. Set the *puszContainerPath* parameter to specify a path name for the container. The path name can be absolute or relative to the directory that contains the base log file. + + You can create additional containers for your log by calling **ClfsAddLogContainer** again. Note that all containers for a given log must be the same size. As an alternative to calling **ClfsAddLogContainer** several times, you can call [**ClfsAddLogContainerSet**](https://msdn.microsoft.com/library/windows/hardware/ff540770) to create several containers simultaneously. Note that your set of containers will serve as stable storage for log records written by both client 1 and client 2. + +4. Pass the **LOG\_FILE\_OBJECT** pointer you obtained on behalf of client 1 to [**ClfsCreateMarshallingArea**](https://msdn.microsoft.com/library/windows/hardware/ff541520) to obtain a pointer to a marshalling area that client 1 can use to read and write log records. Specify the size of the log I/O blocks that the marshalling area will use by setting the *cbMarshallingBuffer* parameter. There are several other parameters you can use to set various properties of the marshalling area. + + If client 1 needs additional marshalling areas, pass the same **LOG\_FILE\_OBJECT** pointer to **ClfsCreateMarshallingArea** again, once for each additional marshalling area that client 1 needs. + +5. Pass the **LOG\_FILE\_OBJECT** pointer you obtained on behalf of client 2 to **ClfsCreateMarshallingArea** to obtain a marshalling area that client 2 can use to read and write log records. Specify the size of the log I/O blocks that the marshalling area will use by setting the *cbMarshallingBuffer* parameter. + + **Note**  There are several other parameters you can use to set various properties of the marshalling area. + +   + + If client 2 needs additional marshalling areas, pass the same **LOG\_FILE\_OBJECT** pointer to **ClfsCreateMarshallingArea** again, once for each additional marshalling area that client 2 needs. + +Now that clients 1 and 2 each have a **LOG\_FILE\_OBJECT** and one or more marshalling areas, they can each write records to their own streams (by way of the marshalling areas associated with those streams) by calling the following functions. + +[**ClfsReserveAndAppendLog**](https://msdn.microsoft.com/library/windows/hardware/ff541723) + +[**ClfsReserveAndAppendLogAligned**](https://msdn.microsoft.com/library/windows/hardware/ff541726) + +[**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770) + +All log records written by clients 1 and 2 go to the same log; that is, to the same set of physical containers on stable storage. CLFS multiplexes the log records written by the two clients and keeps track of which records belong to each stream. + +As client 1 writes records to its stream, it gets back an increasing sequence of log sequence numbers (LSNs) that identify those records. Similarly, client 2 gets its own sequence of LSNs. The LSNs that belong to a particular stream can be compared to determine the order in which the corresponding records were written. However, an LSN that belongs to one stream cannot be compared to an LSN that belongs to another stream. + +CLFS maintains a base LSN and a last LSN for every stream, including streams that share a multiplexed log. Each stream has an active portion that begins with the record pointed to by the base LSN and ends with the record pointed to by the last LSN. Note that a container in a multiplexed log on stable storage cannot be recycled until the base LSNs of all the log's streams have advanced beyond any records stored in that container. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Multiplexed%20CLFS%20Logs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/multiprocessor-safe.md b/windows-driver-docs-pr/kernel/multiprocessor-safe.md new file mode 100644 index 0000000000..339c59fe17 --- /dev/null +++ b/windows-driver-docs-pr/kernel/multiprocessor-safe.md @@ -0,0 +1,62 @@ +--- +title: Multiprocessor-Safe +author: windows-driver-content +description: Multiprocessor-Safe +ms.assetid: 58c51f3e-98c4-4aa0-ad4d-cd9225f78141 +keywords: ["multiprocessor safe WDK kernel", "symmetric multiprocessor platforms WDK kernel", "SMP WDK kernel", "spin locks WDK kernel", "synchronization WDK kernel , multiprocessor safe", "symmetric platforms WDK kernel", "locking WDK kernel", "deadlocks WDK kernel", "critical section routines WDK kernel", "shared data protections WDK kernel", "dispatcher objects WDK kernel , multiprocessor safe", "kernel dispatcher objects WDK , multiprocessor safe"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Multiprocessor-Safe + + +## + + +The Microsoft Windows NT-based operating system is designed to run uniformly on uniprocessor and symmetric multiprocessor (SMP) platforms, and kernel-mode drivers should be designed to do likewise. + +In any Windows multiprocessor platform, the following conditions exist: + +- All CPUs are identical, and either all or none of the processors must have identical coprocessors. + +- All CPUs share memory and have uniform access to memory. + +- In a *symmetric* platform, every CPU can access memory, take an interrupt, and access I/O control registers. (By contrast, in an *asymmetric* multiprocessor machine, one CPU takes all interrupts for a set of subordinate CPUs.) + +To run safely on an SMP platform, an operating system must guarantee that code that executes on one processor does not simultaneously access and modify data that another processor is accessing and modifying. For example, if a lowest-level driver's ISR is handling a device interrupt on one processor, it must have exclusive access to device registers or critical, driver-defined data, in case its device interrupts simultaneously on another processor. + +Furthermore, drivers' I/O operations that are serialized in a uniprocessor machine can be overlapped in an SMP machine. That is, a driver's routine that processes incoming I/O requests can be executing on one processor while another routine that communicates with the device executes concurrently on another processor. Whether kernel-mode drivers are executing on a uniprocessor or symmetric multiprocessor machine, they must synchronize access to any driver-defined data or system-provided resources that are shared among driver routines, and synchronize access to the physical device, if any. + +The Windows NT kernel component exports a synchronization mechanism, called a [spin lock](spin-locks.md), that drivers can use to protect shared data (or device registers) from simultaneous access by one or more routines that are running concurrently on a symmetric multiprocessor platform. The kernel enforces two policies regarding the use of spin locks: + +- Only one routine can hold a particular spin lock at any given moment. Before accessing shared data, each routine that must reference the data must first attempt to acquire the data's spin lock. To access the same data, another routine must acquire the spin lock, but the spin lock cannot be acquired until the current holder releases it. + +- The kernel assigns an IRQL value to each spin lock in the system. A kernel-mode routine can acquire a particular spin lock only when the routine is run at the spin lock's assigned IRQL. + +These policies prevent a driver routine that usually runs at a lower IRQL but currently holds a spin lock from being preempted by a higher-priority driver routine that is trying to acquire the same spin lock. Thus, a deadlock is avoided. + +The IRQL that is assigned to a spin lock is generally that of the highest-IRQL routine that can acquire the spin lock. + +For example, a lowest-level driver's ISR frequently shares a state area with the driver's DPC routine. The DPC routine calls a driver-supplied [*critical section*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-critical-section) routine to access the shared area. The spin lock that protects the shared area has an IRQL equal to the DIRQL at which the device interrupts. As long as the critical-section routine holds the spin lock and accesses the shared area at DIRQL, the ISR cannot be run in either a uniprocessor or SMP machine. + +- The ISR cannot be run in a uniprocessor machine because the device interrupt is masked, as described in [Always Preemptible and Always Interruptible](always-preemptible-and-always-interruptible.md). + +- In an SMP machine, the ISR cannot acquire the spin lock that protects the shared data while the critical-section routine holds the spin lock and accesses the shared data at DIRQL. + +A set of kernel-mode threads can synchronize access to shared data or resources by waiting for one of the kernel's dispatcher objects: an event, mutex, semaphore, timer, or another thread. However, most drivers do not set up their own threads because they have better performance when they avoid thread-context switches. Whenever time-critical kernel-mode support routines and drivers run at IRQL = DISPATCH\_LEVEL or at DIRQL, they must use the kernel's spin locks to synchronize access to shared data or resources. + +For more information, see [Spin Locks](spin-locks.md), [Managing Hardware Priorities](managing-hardware-priorities.md), and [Kernel Dispatcher Objects](kernel-dispatcher-objects.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Multiprocessor-Safe%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/mutex-objects.md b/windows-driver-docs-pr/kernel/mutex-objects.md new file mode 100644 index 0000000000..51a61ccce3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/mutex-objects.md @@ -0,0 +1,28 @@ +--- +title: Mutex Objects +author: windows-driver-content +description: Mutex Objects +ms.assetid: e2142b6d-f460-4f80-be0f-e00b5d43731c +--- + +# Mutex Objects + + +## + + +This section includes the following topics: + +[Introduction to Mutex Objects](introduction-to-mutex-objects.md) + +[Alternatives to Mutex Objects](alternatives-to-mutex-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Mutex%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/named-device-objects.md b/windows-driver-docs-pr/kernel/named-device-objects.md new file mode 100644 index 0000000000..b21e423f1f --- /dev/null +++ b/windows-driver-docs-pr/kernel/named-device-objects.md @@ -0,0 +1,40 @@ +--- +title: Named Device Objects +author: windows-driver-content +description: Named Device Objects +ms.assetid: 4e24f0c1-57b2-4e06-a7f5-9a93d365ac8c +keywords: ["device objects WDK kernel , named", "named device objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Named Device Objects + + +## + + +A device object, like all object manager objects, can be named or unnamed. When a user-mode application makes an I/O request, it specifies the target of the operation by name. The object manager resolves the name to determine the destination of the I/O request. + +A driver can specify a name for a device object when it calls [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) or [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) to create the device object. For more information about when and how to name a device object, see [NT Device Names](nt-device-names.md). + +A named device object can also have an MS-DOS device name, which is a symbolic link created by [**IoCreateSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549043) or [**IoCreateUnprotectedSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549050). WDM drivers do not in general require an MS-DOS device name. For more information, see [MS-DOS Device Names](ms-dos-device-names.md). + +This section contains the following subsections: + +[NT Device Names](nt-device-names.md) + +[MS-DOS Device Names](ms-dos-device-names.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Named%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/no-execute-nonpaged-pool.md b/windows-driver-docs-pr/kernel/no-execute-nonpaged-pool.md new file mode 100644 index 0000000000..830b969143 --- /dev/null +++ b/windows-driver-docs-pr/kernel/no-execute-nonpaged-pool.md @@ -0,0 +1,30 @@ +--- +title: No-Execute (NX) Nonpaged Pool +author: windows-driver-content +description: As a best practice, drivers for Windows 8 and later versions of Windows should allocate most or all of their nonpaged memory from the no-execute (NX) nonpaged pool. +ms.assetid: E5BF34F6-ABA0-4EC7-B740-CC83EF8438CF +--- + +# No-Execute (NX) Nonpaged Pool + + +As a best practice, drivers for Windows 8 and later versions of Windows should allocate most or all of their nonpaged memory from the no-execute (NX) nonpaged pool. By allocating memory from NX nonpaged pool, a kernel-mode driver improves security by preventing malicious software from executing instructions in this memory. + +Starting with Windows 8, kernel-mode drivers can allocate memory from a pool of NX nonpaged memory. This pool is managed by a general-purpose, kernel-mode memory allocator that operates similarly to the user-mode Win32 heap allocator. The memory in this pool is NX and nonpaged. The x86, x64, and ARM processor architectures enable memory pages to be designated as NX to prevent the execution of instructions in these pages. Typically, a kernel-mode driver uses memory allocated from nonpaged pool to store data, and does not require the ability to execute instructions in this memory. + +## Support for Legacy Drivers + + +In Windows 7 and earlier versions of Windows, all memory allocated from the nonpaged pool is executable. To encourage porting of these drivers to use NX nonpaged pool in Windows 8 and later versions of Windows, Microsoft provides several opt-in mechanisms to enable developers to update their drivers with minimal effort. For more information, see [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md). + +For backward compatibility, driver binaries that run on Windows 7 and earlier versions of Windows, and that allocate memory from the executable nonpaged pool, will run on Windows 8 and later versions of Windows without modification. However, these drivers do not take advantage of the improved security of the NX nonpaged pool. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20No-Execute%20%28NX%29%20Nonpaged%20Pool%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/no-wake-timers.md b/windows-driver-docs-pr/kernel/no-wake-timers.md new file mode 100644 index 0000000000..7611ed8b52 --- /dev/null +++ b/windows-driver-docs-pr/kernel/no-wake-timers.md @@ -0,0 +1,46 @@ +--- +title: No-Wake Timers +author: windows-driver-content +description: Starting with Windows 8.1, drivers can use no-wake timers to avoid unnecessarily waking a processor from a low-power state. +ms.assetid: 04CD107B-F196-4FF8-A423-C43CAA9A7EBD +keywords: ["No-wake timers", "ExXxxTimer routines", "EX_TIMER_NO_WAKE", "EX_TIMER_UNLIMITED_TOLERANCE", "coalescable timers", "timer coalescing", "KeSetCoalescableTimer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# No-Wake Timers + + +Starting with Windows 8.1, drivers can use no-wake timers to avoid unnecessarily waking a processor from a low-power state. By keeping the processor in a low-power state, a no-wake timer reduces power consumption and extends the time that a tablet or other mobile computer can run on a battery charge. + +A timer can expire only when the processor is in an active, running state. If a timer reaches its expiration time when the processor is in a low-power state, and the timer needs to expire immediately, the timer must wake the processor. However, when a no-wake timer reaches its expiration time and the processor is in a low-power state, this timer waits to expire until the processor wakes for some reason other than the timer. As an option, a driver can specify a maximum delay tolerance for a no-wake timer so that if the processor does not wake (for some other reason) within the maximum delay tolerance after the timer's expiration time, the timer wakes the processor. + +A driver can use a no-wake timer to initiate noncritical operations that need to be performed only when the processor is in an active state. For example, a driver might use a no-wake timer to periodically flush accumulated status information from a memory buffer to a file. This status information describes processing work that the driver performs only when the processor is active. When the processor is in a low-power state, no status information is generated, and there is no need to wake the processor. + +To create a no-wake timer, a WDM driver calls the [**ExAllocateTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265179) routine. In this call, the driver sets the EX\_TIMER\_NO\_WAKE flag bit in the *Attributes* parameter. + +To set a no-wake timer to expire at some due time, the driver calls the [**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) routine. In this call, the driver can specify how long the no-wake timer should wait after it reaches its expiration time before the timer wakes the processor. The driver writes this tolerable-delay time to the **NoWakeTolerance** member in the [**EXT\_SET\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn265196) structure that the driver passes as an input parameter to the **ExSetTimer** routine. If the driver sets the **NoWakeTolerance** member to the special value EX\_TIMER\_UNLIMITED\_TOLERANCE, the timer never wakes the processor and, thus, cannot expire until the processor wakes for some other reason. + +A Kernel-Mode Driver Framework (KMDF) driver or User-Mode Driver Framework (UMDF) driver can call the [**WdfTimerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff550050) method to create a no-wake timer. In this call, the driver passes a pointer to a [**WDF\_TIMER\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff552519) structure as a parameter. To create a no-wake timer that never wakes the processor, the driver sets the **TolerableDelay** member of this structure to the **TolerableDelayUnlimited** constant. This constant is supported starting with Windows 8.1 and KMDF version 1.13 or UMDF 2.0. + +## Comparison to coalescable timers + + +The [**KeSetCoalescableTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553249) routine was introduced in Windows 7. This routine enables a driver to specify how much tolerance to allow in the expiration time of a timer. Frequently, the operating system can use this information to coalesce two or more timer interrupts into a single interrupt. If the expiration times of multiple timers are close enough to each other that their tolerance windows overlap, a single timer interrupt in the region of overlap can satisfy the timing requirements of all of these timers. + +The chief benefit of timer coalescing is that it extends the time that the processor can stay in a low-power state between timer expirations. Thus, drivers use timer coalescing and no-wake timers for similar purposes. + +However, coalesceable timers behave differently from no-wake timers. In particular, the tolerable delay specified for a no-wake timer applies only when the processor is in a low-power state, whereas the tolerance specified for the expiration of a coalescable timer applies regardless of whether the processor is in a low-power state. For a coalescable timer, a driver can increase the amount of tolerance in the expiration time to reduce the likelihood that the timer wakes the processor, but increasing the tolerance has the side effect of decreasing the accuracy of the timer when the processor is active. In contrast, the tolerable delay specified for a no-wake timer does not affect the accuracy of the timer when the processor is active. For many drivers, no-wake timers might be a better way to reduce power consumption. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20No-Wake%20Timers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/non-pnp-driver-s-unload-routine.md b/windows-driver-docs-pr/kernel/non-pnp-driver-s-unload-routine.md new file mode 100644 index 0000000000..1d3ba62d1a --- /dev/null +++ b/windows-driver-docs-pr/kernel/non-pnp-driver-s-unload-routine.md @@ -0,0 +1,38 @@ +--- +title: Non-PnP Driver's Unload Routine +author: windows-driver-content +description: Non-PnP Driver's Unload Routine +ms.assetid: 5917648f-1e7e-4b39-9aa6-d6cdaac7a2cd +keywords: ["Unload routines WDK kernel , non-PnP drivers", "non-PnP Unload routine WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Non-PnP Driver's Unload Routine + + +## + + +Earlier drivers and high-level file system drivers, which do not handle PnP device-removal requests, must release resources, delete device objects, and detach from the device stack in their [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routines. + +If it has not done so already, the first thing a legacy device driver should do in its *Unload* routine is to disable interrupts from the device. Otherwise, its ISR might be called to handle a device interrupt while the *Unload* routine is releasing resources in the device extension that the ISR needs to handle the interrupt. Even if its ISR runs successfully in these circumstances, the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine that the ISR queues, and possibly other driver routines that run at IRQL >= DISPATCH\_LEVEL, will execute before the *Unload* routine regains control, thereby increasing the likelihood that the *Unload* routine has deleted a resource that another driver routine references. See [Managing Hardware Priorities](managing-hardware-priorities.md) for more information. + +After disabling interrupts, file system and legacy drivers must release resources and objects. For details, see the following two sections: + +[Releasing Driver-Allocated Resources](releasing-driver-allocated-resources.md) + +[Releasing Device and Controller Objects](releasing-device-and-controller-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Non-PnP%20Driver's%20Unload%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/notifying-the-file-system-of-possible-media-changes.md b/windows-driver-docs-pr/kernel/notifying-the-file-system-of-possible-media-changes.md new file mode 100644 index 0000000000..6a6e399df6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/notifying-the-file-system-of-possible-media-changes.md @@ -0,0 +1,52 @@ +--- +title: Notifying the File System of Possible Media Changes +author: windows-driver-content +description: Notifying the File System of Possible Media Changes +ms.assetid: b1956370-ec9c-4a43-90a8-12705d28e314 +keywords: ["removable media WDK kernel , notifying of media changes", "notifications WDK removable media", "media change notifications WDK removable media"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Notifying the File System of Possible Media Changes + + +## + + +A removable-media device driver must ensure that the media is not changed for the device represented by the **DeviceObject** (input to every driver routine that is sent an IRP) whenever the driver processes an IRP that requests a transfer to/from the media or a device I/O control operation that affects the media. The best possible time to check for changed media is just after the transition from a no-media-present state to a media-present state if the physical device always notifies the driver about these state changes. + +If its physical device indicates that the state of the media might have changed before the driver begins an I/O operation or during an operation, the driver must do the following: + +1. Ensure that the volume is mounted by checking the VPB\_MOUNTED flag in the [*VPB*](https://msdn.microsoft.com/library/windows/hardware/ff556344#wdkgloss-vpb). (If the volume is not mounted, the driver must not set the DO\_VERIFY\_VOLUME bit. The driver should set **IoStatus.Status** to STATUS\_IO\_DEVICE\_ERROR, set **IoStatus.Information** to zero, and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the IRP.) + +2. Set the **Flags** in the **DeviceObject** by ORing **Flags** with DO\_VERIFY\_VOLUME. + +3. Set the **IoStatus** block in the IRP to the following: + - **Status** set to STATUS\_VERIFY\_REQUIRED + - **Information** set to zero + +4. Before completing any IRP with an **IoStatus** block in which the **Status** field is not set to STATUS\_SUCCESS, the driver must call [**IoIsErrorUserInduced**](https://msdn.microsoft.com/library/windows/hardware/ff549375), which returns a Boolean **TRUE** for any of the following **Status** values: + + - STATUS\_VERIFY\_REQUIRED + - STATUS\_NO\_MEDIA\_IN\_DEVICE + - STATUS\_WRONG\_VOLUME + - STATUS\_UNRECOGNIZED\_MEDIA + - STATUS\_MEDIA\_WRITE\_PROTECTED + - STATUS\_IO\_TIMEOUT + - STATUS\_DEVICE\_NOT\_READY + + If **IoIsErrorUserInduced** returns **TRUE**, the driver must call [**IoSetHardErrorOrVerifyDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549707) so the FSD can open a dialog box to the user, who can then choose to supply the correct media, retry the original request, or cancel the requested operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Notifying%20the%20File%20System%20of%20Possible%20Media%20Changes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/nt-device-names.md b/windows-driver-docs-pr/kernel/nt-device-names.md new file mode 100644 index 0000000000..cf48c51e2b --- /dev/null +++ b/windows-driver-docs-pr/kernel/nt-device-names.md @@ -0,0 +1,46 @@ +--- +title: NT Device Names +author: windows-driver-content +description: NT Device Names +ms.assetid: dfcc7338-7c4d-4b4c-9a13-c76bfe82f5a9 +keywords: ["NT device names WDK kernel", "device objects WDK kernel , named", "named device objects WDK kernel", "device names WDK kernel", "non-WDM driver device names WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NT Device Names + + +## + + +A named device object has a name of the form **\\Device\\***DeviceName*. This is known as the *NT device name* of the device object. + +### Device Names for WDM Drivers + +WDM drivers do not name their device objects directly. Instead, the system imposes a uniform naming scheme that ensures that device names do not conflict between drivers. The naming scheme for WDM drivers is as follows. + +- The PDO for a device is named. The bus driver requests named PDOs for the devices it enumerates. The bus driver specifies the FILE\_AUTOGENERATED\_DEVICE\_NAME device characteristic when it creates the device object. For more information, see [Specifying Device Characteristics](specifying-device-characteristics.md). The system then automatically generates the device name. + +- FDOs and filter DOs are not named. Function and filter drivers do not request a name when creating the device object. + +Any I/O request to a named device object automatically goes to the top object in that device object's stack. Thus, only the PDO is required to be named. User-mode applications do not refer to WDM device objects by name; instead, applications access the device object through its [*device interface*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-interface). For more information, see [Device Interface Classes](https://msdn.microsoft.com/library/windows/hardware/ff541339). + +Driver writers must not name more than one object in a device stack. The operating system checks security settings based on the named object. If two different objects are named and have different security descriptors, the I/O requests that are sent to the object with the weaker security descriptor can reach the device object with the stronger security descriptor. + +### Device Names for non-WDM Drivers + +A non-WDM driver must explicitly specify a name for any named device objects. The driver must create at least one named device object in the **\\Device** object directory to receive I/O requests. The driver specifies the device name as the *DeviceName* parameter to [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) when creating the device object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NT%20Device%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ntintsafe-design-guide.md b/windows-driver-docs-pr/kernel/ntintsafe-design-guide.md new file mode 100644 index 0000000000..d27998c66d --- /dev/null +++ b/windows-driver-docs-pr/kernel/ntintsafe-design-guide.md @@ -0,0 +1,38 @@ +--- +title: Using Safe Integer Functions +author: windows-driver-content +description: The ntintsafe library provides a set of C functions that perform safe integer arithmetic operations with bounds checking to prevent overflows and underflows in kernel-mode code. +ms.assetid: AFB7A078-814D-49EF-ABF9-2C621590F43B +--- + +# Using Safe Integer Functions + + +One way to minimize security problems is to prevent integer overflows and underflows. Integer overflows occur when the result of an arithmetic operation is larger than the memory space of the data type that is set to receive it. This results in the truncation of the integer and an incorrect result. An underflow occurs when an operation, usually subtraction, gives an incorrect result. Casting between two data types can also cause incorrect results due to truncation of a result that does not fit the new memory space. + +The ntintsafe library provides a set of C functions that perform safe integer arithmetic operations with bounds checking to prevent overflows and underflows in kernel-mode code. These functions correspond to the Windows IntSafe functions that are used by application code. You use these functions to calculate an index or buffer size, or to compute some other form of bounds check. The functions are optimized for speed. + +Safe integer functions offer the following advantages: + +- The size of the destination buffer is always provided to the function to ensure that the function does not write past the end of the buffer. +- Buffers are guaranteed to be null-terminated, even if the operation truncates the intended result. +- All functions return an NTSTATUS, with only one possible success code (STATUS\_SUCCESS) and one possible error condition (STATUS\_INTEGER\_OVERFLOW). + +The ntintsafe library has two categories of functions: + +- **Conversion functions**—These functions perform conversions between two data types. +- **Arithmetic functions**—These functions perform addition, subtraction, and multiplication operations for each data type. There are no division operations because there are no overflow conditions. + +[Summary of Kernel-Mode Safe Integer Functions](summary-of-safe-integer-functions.md) + +[Importing Kernel-Mode Safe Integer Functions](importing-safe-integer-functions.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Safe%20Integer%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ntstatus-values.md b/windows-driver-docs-pr/kernel/ntstatus-values.md new file mode 100644 index 0000000000..635ac0eaf3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/ntstatus-values.md @@ -0,0 +1,34 @@ +--- +title: NTSTATUS Values +author: windows-driver-content +description: NTSTATUS Values +ms.assetid: 7792201b-63bb-4db5-803d-2af02893d505 +keywords: ["standard driver routines WDK kernel , NTSTATUS values"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NTSTATUS Values + + +## + + +This section discusses how to use the NTSTATUS values that are returned by system routines, as well as when and how you can define your own custom NTSTATUS values for use by your driver. + +[Using NTSTATUS Values](using-ntstatus-values.md) + +[Defining New NTSTATUS Values](defining-new-ntstatus-values.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NTSTATUS%20Values%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/ntxxx-routines.md b/windows-driver-docs-pr/kernel/ntxxx-routines.md new file mode 100644 index 0000000000..b269d7d303 --- /dev/null +++ b/windows-driver-docs-pr/kernel/ntxxx-routines.md @@ -0,0 +1,438 @@ +--- +title: NtXxx Routines +author: windows-driver-content +description: NtXxx Routines +ms.assetid: 71db6fa6-d1f8-4aed-9de1-bba1f6cee1ce +--- + +# NtXxx Routines + + +This section describes the **Nt*Xxx*** versions of the Windows Native System Services routines. Most native system services routines have two versions, one of which has a name begins with the prefix **Nt**; the other version has a name that begins with the prefix **Zw**. For example, calls to [**NtCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff556465) and [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424) perform similar operations and are, in fact, serviced by the same kernel-mode system routine. + +For calls from kernel-mode drivers, the **Nt*Xxx*** and **Zw*Xxx*** versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the **Nt*Xxx*** and **Zw*Xxx*** versions of a routine, see [Using Nt and Zw Versions of the Native System Services Routines](using-nt-and-zw-versions-of-the-native-system-services-routines.md). + +The following table summarizes the **Nt*Xxx*** and **Zw*Xxx*** versions of the routines: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NtXxxZwXxx

NtAllocateLocallyUniqueId

[ZwAllocateLocallyUniqueId](https://msdn.microsoft.com/library/windows/hardware/ff566415)

NtAllocateVirtualMemory

[ZwAllocateVirtualMemory](https://msdn.microsoft.com/library/windows/hardware/ff566416)

NtClose

[ZwClose](https://msdn.microsoft.com/library/windows/hardware/ff566417)

NtCommitComplete

[ZwCommitComplete](https://msdn.microsoft.com/library/windows/hardware/ff566418)

NtCommitEnlistment

[ZwCommitEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff566419)

NtCommitTransaction

[ZwCommitTransaction](https://msdn.microsoft.com/library/windows/hardware/ff566420)

NtCreateDirectoryObject

[ZwCreateDirectoryObject](https://msdn.microsoft.com/library/windows/hardware/ff566421)

NtCreateEnlistment

[ZwCreateEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff566422)

NtCreateEvent

[ZwCreateEvent](https://msdn.microsoft.com/library/windows/hardware/ff566423)

NtCreateFile

[ZwCreateFile](https://msdn.microsoft.com/library/windows/hardware/ff566424)

NtCreateKey

[ZwCreateKey](https://msdn.microsoft.com/library/windows/hardware/ff566425)

NtCreateResourceManager

[ZwCreateResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff566427)

NtCreateSection

[ZwCreateSection](https://msdn.microsoft.com/library/windows/hardware/ff566428)

NtCreateTransaction

[ZwCreateTransaction](https://msdn.microsoft.com/library/windows/hardware/ff566429)

NtCreateTransactionManager

[ZwCreateTransactionManager](https://msdn.microsoft.com/library/windows/hardware/ff566430)

NtCurrentProcess

[ZwCurrentProcess](https://msdn.microsoft.com/library/windows/hardware/ff566431)

NtCurrentThread

[ZwCurrentThread](https://msdn.microsoft.com/library/windows/hardware/ff566434)

NtDeleteFile

[ZwDeleteFile](https://msdn.microsoft.com/library/windows/hardware/ff566435)

NtDeleteKey

[ZwDeleteKey](https://msdn.microsoft.com/library/windows/hardware/ff566437)

NtDeleteValueKey

[ZwDeleteValueKey](https://msdn.microsoft.com/library/windows/hardware/ff566439)

NtDeviceIoControlFile

[ZwDeviceIoControlFile](https://msdn.microsoft.com/library/windows/hardware/ff566441)

NtDuplicateObject

[ZwDuplicateObject](https://msdn.microsoft.com/library/windows/hardware/ff566445)

NtDuplicateToken

[ZwDuplicateToken](https://msdn.microsoft.com/library/windows/hardware/ff566446)

NtEnumerateKey

[ZwEnumerateKey](https://msdn.microsoft.com/library/windows/hardware/ff566447)

NtEnumerateTransactionObject

[ZwEnumerateTransactionObject](https://msdn.microsoft.com/library/windows/hardware/ff566450)

NtEnumerateValueKey

[ZwEnumerateValueKey](https://msdn.microsoft.com/library/windows/hardware/ff566453)

NtFlushBuffersFile

[ZwFlushBuffersFile](https://msdn.microsoft.com/library/windows/hardware/ff566454)

NtFlushBuffersFileEx

[ZwFlushBuffersFileEx](https://msdn.microsoft.com/library/windows/hardware/hh967720)

NtFlushKey

[ZwFlushKey](https://msdn.microsoft.com/library/windows/hardware/ff566457)

NtFlushVirtualMemory

[ZwFlushVirtualMemory](https://msdn.microsoft.com/library/windows/hardware/ff566458)

NtFreeVirtualMemory

[ZwFreeVirtualMemory](https://msdn.microsoft.com/library/windows/hardware/ff566460)

NtFsControlFile

[ZwFsControlFile](https://msdn.microsoft.com/library/windows/hardware/ff566462)

NtGetNotificationResourceManager

[ZwGetNotificationResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff566467)

NtLoadDriver

[ZwLoadDriver](https://msdn.microsoft.com/library/windows/hardware/ff566470)

NtLockFile

[ZwLockFile](https://msdn.microsoft.com/library/windows/hardware/ff566474)

NtMakeTemporaryObject

[ZwMakeTemporaryObject](https://msdn.microsoft.com/library/windows/hardware/ff566477)

NtMapViewOfSection

[ZwMapViewOfSection](https://msdn.microsoft.com/library/windows/hardware/ff566481)

NtNotifyChangeKey

[ZwNotifyChangeKey](https://msdn.microsoft.com/library/windows/hardware/ff566488)

NtOpenDirectoryObject

[ZwOpenDirectoryObject](https://msdn.microsoft.com/library/windows/hardware/ff566492)

NtOpenEnlistment

[ZwOpenEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567008)

NtOpenEvent

[ZwOpenEvent](https://msdn.microsoft.com/library/windows/hardware/ff567009)

NtOpenFile

[ZwOpenFile](https://msdn.microsoft.com/library/windows/hardware/ff567011)

NtOpenKey

[ZwOpenKey](https://msdn.microsoft.com/library/windows/hardware/ff567014)

NtOpenProcess

[ZwOpenProcess](https://msdn.microsoft.com/library/windows/hardware/ff567022)

NtOpenProcessTokenEx

[ZwOpenProcessTokenEx](https://msdn.microsoft.com/library/windows/hardware/ff567024)

NtOpenResourceManager

[ZwOpenResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff567026)

NtOpenSection

[ZwOpenSection](https://msdn.microsoft.com/library/windows/hardware/ff567029)

NtOpenSymbolicLinkObject

[ZwOpenSymbolicLinkObject](https://msdn.microsoft.com/library/windows/hardware/ff567030)

NtOpenThreadTokenEx

[ZwOpenThreadTokenEx](https://msdn.microsoft.com/library/windows/hardware/ff567032)

NtOpenTransaction

[ZwOpenTransaction](https://msdn.microsoft.com/library/windows/hardware/ff567033)

NtOpenTransactionManager

[ZwOpenTransactionManager](https://msdn.microsoft.com/library/windows/hardware/ff567035)

NtPowerInformation

[ZwPowerInformation](https://msdn.microsoft.com/library/windows/hardware/dn957454)

NtPrepareComplete

[ZwPrepareComplete](https://msdn.microsoft.com/library/windows/hardware/ff567037)

NtPrepareEnlistment

[ZwPrepareEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567039)

NtPrePrepareComplete

[ZwPrePrepareComplete](https://msdn.microsoft.com/library/windows/hardware/ff567040)

NtPrePrepareEnlistment

[ZwPrePrepareEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567044)

NtQueryDirectoryFile

[ZwQueryDirectoryFile](https://msdn.microsoft.com/library/windows/hardware/ff567047)

NtQueryFullAttributesFile

[ZwQueryFullAttributesFile](https://msdn.microsoft.com/library/windows/hardware/ff567049)

NtQueryInformationEnlistment

[ZwQueryInformationEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567051)

NtQueryInformationFile

[ZwQueryInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567052)

NtQueryInformationResourceManager

[ZwQueryInformationResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff567054)

NtQueryInformationToken

[ZwQueryInformationToken](https://msdn.microsoft.com/library/windows/hardware/ff567055)

NtQueryInformationTransaction

[ZwQueryInformationTransaction](https://msdn.microsoft.com/library/windows/hardware/ff567057)

NtQueryInformationTransactionManager

[ZwQueryInformationTransactionManager](https://msdn.microsoft.com/library/windows/hardware/ff567058)

NtQueryKey

[ZwQueryKey](https://msdn.microsoft.com/library/windows/hardware/ff567060)

NtQueryObject

[ZwQueryObject](https://msdn.microsoft.com/library/windows/hardware/ff567062)

NtQueryQuotaInformationFile

[ZwQueryQuotaInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567064)

NtQuerySecurityObject

[ZwQuerySecurityObject](https://msdn.microsoft.com/library/windows/hardware/ff567066)

NtQuerySecurityObject

[ZwQuerySymbolicLinkObject](https://msdn.microsoft.com/library/windows/hardware/ff567068)

NtQueryValueKey

[ZwQueryValueKey](https://msdn.microsoft.com/library/windows/hardware/ff567069)

NtQueryVirtualMemory

[ZwQueryVirtualMemory](https://msdn.microsoft.com/library/windows/hardware/dn957455)

NtQueryVolumeInformationFile

[ZwQueryVolumeInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567070)

NtReadFile

[ZwReadFile](https://msdn.microsoft.com/library/windows/hardware/ff567072)

NtReadOnlyEnlistment

[ZwReadOnlyEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567074)

NtReadOnlyEnlistment

[ZwRecoverEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567075)

NtRecoverResourceManager

[ZwRecoverResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff567078)

NtRecoverTransactionManager

[ZwRecoverTransactionManager](https://msdn.microsoft.com/library/windows/hardware/ff567079)

NtRollbackComplete

[ZwRollbackComplete](https://msdn.microsoft.com/library/windows/hardware/ff567081)

NtRollbackEnlistment

[ZwRollbackEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567083)

NtRollbackTransaction

[ZwRollbackTransaction](https://msdn.microsoft.com/library/windows/hardware/ff567086)

NtRollforwardTransactionManager

[ZwRollforwardTransactionManager](https://msdn.microsoft.com/library/windows/hardware/ff567089)

NtSetEvent

[ZwSetEvent](https://msdn.microsoft.com/library/windows/hardware/ff567092)

NtSetInformationEnlistment

[ZwSetInformationEnlistment](https://msdn.microsoft.com/library/windows/hardware/ff567094)

NtSetInformationFile

[ZwSetInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567096)

NtSetInformationResourceManager

[ZwSetInformationResourceManager](https://msdn.microsoft.com/library/windows/hardware/ff567098)

NtSetInformationThread

[ZwSetInformationThread](https://msdn.microsoft.com/library/windows/hardware/ff567101)

NtSetInformationToken

[ZwSetInformationToken](https://msdn.microsoft.com/library/windows/hardware/ff567102)

NtSetInformationTransaction

[ZwSetInformationTransaction](https://msdn.microsoft.com/library/windows/hardware/ff567104)

NtSetQuotaInformationFile

[ZwSetQuotaInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567105)

NtSetSecurityObject

[ZwSetSecurityObject](https://msdn.microsoft.com/library/windows/hardware/ff567106)

NtSetValueKey

[ZwSetValueKey](https://msdn.microsoft.com/library/windows/hardware/ff567109)

NtSetVolumeInformationFile

[ZwSetVolumeInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567112)

NtSinglePhaseReject

[ZwSinglePhaseReject](https://msdn.microsoft.com/library/windows/hardware/ff567113)

NtTerminateProcess

[ZwTerminateProcess](https://msdn.microsoft.com/library/windows/hardware/ff567115)

NtUnloadDriver

[ZwUnloadDriver](https://msdn.microsoft.com/library/windows/hardware/ff567117)

NtUnlockFile

[ZwUnlockFile](https://msdn.microsoft.com/library/windows/hardware/ff567118)

NtUnmapViewOfSection

[ZwUnmapViewOfSection](https://msdn.microsoft.com/library/windows/hardware/ff567119)

NtWaitForSingleObject

[ZwWaitForSingleObject](https://msdn.microsoft.com/library/windows/hardware/ff567120)

NtWriteFile

[ZwWriteFile](https://msdn.microsoft.com/library/windows/hardware/ff567121)

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NtXxx%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/nx-and-execute-pool-types.md b/windows-driver-docs-pr/kernel/nx-and-execute-pool-types.md new file mode 100644 index 0000000000..d637289d83 --- /dev/null +++ b/windows-driver-docs-pr/kernel/nx-and-execute-pool-types.md @@ -0,0 +1,33 @@ +--- +title: NX and Execute Pool Types +author: windows-driver-content +description: To indicate whether memory allocated from a nonpaged pool should be no-execute (NX), you can use two new pool types starting with Windows 8. +ms.assetid: 954AC53F-270D-4149-AE5D-6BEA7EFAA761 +--- + +# NX and Execute Pool Types + + +To indicate whether memory allocated from a nonpaged pool should be no-execute (NX), you can use two new pool types starting with Windows 8. These pool types are designated by the following [**POOL\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff559707) enumeration values: + +**NonPagedPoolNx** +NX nonpaged pool. Instructions cannot be executed in memory allocated from this pool. + +**NonPagedPoolExecute** +Executable nonpaged pool. Instruction execution is enabled in memory allocated from this pool. + +Most drivers use allocated memory only to store data, and do not execute instructions in this memory. If you build your driver to run on Windows 8 and later versions of Windows, allocate **NonPagedPoolNx** memory from the NX nonpaged pool whenever possible. Only drivers that need to execute instructions from nonpaged memory should allocate **NonPagedPoolExecute** memory from the executable nonpaged pool. + +For existing drivers that are built for Windows 7 and earlier versions of Windows, when you use the **NonPagedPool** pool type your driver allocates memory from the executable pool. The **NonPagedPool** constant name has the same value as the **NonPagedPoolExecute** constant name that is defined starting with Windows 8. Therefore, these constants refer to the same pool type. + +If a driver written for Windows 7 or an earlier version of Windows is built for Windows 8 or a later version of Windows, instances of the **NonPagedPool** pool type should be replaced by either **NonPagedPoolNx** or **NonPagedPoolExecute**. The driver developer either can explicitly perform this replacement, or can implicitly perform the replacement by using one of the opt-in mechanisms that is provided to aid developers in porting their drivers to Windows 8. For more information, see [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NX%20and%20Execute%20Pool%20Types%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/nx-pool-compatibility-issues.md b/windows-driver-docs-pr/kernel/nx-pool-compatibility-issues.md new file mode 100644 index 0000000000..a6be427fbc --- /dev/null +++ b/windows-driver-docs-pr/kernel/nx-pool-compatibility-issues.md @@ -0,0 +1,54 @@ +--- +title: NX Pool Compatibility Issues +author: windows-driver-content +description: When you use the NX nonpaged pool in driver binaries for Windows 8, you will find compatibility issues if you run these binaries on earlier versions of Windows. +ms.assetid: 652AE9A2-D733-4EC2-9D49-B95DDABE42B1 +--- + +# NX Pool Compatibility Issues + + +When you use the NX nonpaged pool in driver binaries for Windows 8, you will find compatibility issues if you run these binaries on earlier versions of Windows. + +Windows 8 is the first version of Windows to support the NX nonpaged pool. However, a large number of existing kernel-mode driver binaries are available for Windows 7 and earlier versions of Windows that run on the x86, x64, and IA64 processor architectures. To allocate nonpaged memory, these drivers use the executable nonpaged pool instead the NX nonpaged pool. For backward compatibility, kernel-mode driver binaries that run on Windows 7, and on some earlier versions of Windows, and that allocate memory from the nonpaged pool, will run on Windows 8 without modification. However, these drivers do not take advantage of the availability of NX nonpaged pool in Windows 8. + +## Running Existing Driver Binaries on Windows 8 + + +A driver binary that is built for Windows 7 (or possibly for an earlier version of Windows), and that uses the **NonPagedPool** pool type, is not prevented from running on Windows 8. To enable backward compatibility, the **NonPagedPoolExecute** constant is defined to have the same value as the **NonPagedPool** constant in the [**POOL\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff559707) enumeration. Thus, in any version of Windows in which this driver runs, the memory that the driver allocates from nonpaged pool is always executable. + +Windows 8 is the first version of Windows to support the ARM architecture. Thus, there are no driver binaries for ARM that are built for earlier versions of Windows and that require backward compatibility. Instead, all drivers written for Windows on ARM are expected to specify **NonPagedPoolNx** instead of **NonPagedPoolExecute** in their nonpaged pool allocations unless they explicitly require executable memory. + +If a driver is ported to ARM from x86, x64, or IA64, the [POOL\_NX\_OPTIN\_AUTO](multiple-binary-opt-in-pool-nx-optin-auto.md) opt-in mechanism is automatically applied during the driver build process. This opt-in mechanism uses the preprocessor to replace, by default, all instances of the **NonPagedPool** constant name with **NonPagedPoolNx**. If necessary, you can use the [POOL\_NX\_OPTOUT](selective-opt-out-pool-nx-optout.md) opt-out mechanism to overrride this opt-in mechanism on a per-file basis. + +## Other Compatibility Issues + + +The **NonPagedPoolNx** pool type is supported starting with Windows 8. Do not use this pool type in drivers for earlier versions of Windows. The pool allocators in these earlier versions of Windows do not operate correctly when the driver requests an allocation with a **NonPagedPoolNx** pool type. + +In versions of Windows before Windows 8, the **NonPagedPoolExecute** pool type can be freely used as a substitute for the **NonPagedPool** pool type. The [**POOL\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff559707) enumeration defines **NonPagedPool** and **NonPagedPoolExecute** to have the same value. + +## NX Pool Type Porting Guidelines + + +When you port your driver code to Windows 8 or later from an earlier version of Windows, there are several ways to add support for the **NonPagedPoolNx** and **NonPagedPoolExecute** pool types. From the following list, choose the approach that best fits your requirements: + +- If your driver is not intended to run on a version of Windows earlier than Windows 8, replace most or all instances of **NonPagedPool** with **NonPagedPoolNx**. Only rarely should the developer replace an instance of **NonPagedPool** with **NonPagedPoolExecute.** + +- If your driver source code targets both Windows 8 and earlier versions of Windows, and you ship a different driver binary for each version, use the POOL\_NX\_OPTIN\_AUTO opt-in mechanism. This approach does not require replacing the instances of **NonPagedPool** in the driver source. For more information, see [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md). + +- If your driver source code targets both Windows 8 and earlier versions of Windows, and you ship a single driver binary to run on all supported versions, use the POOL\_NX\_OPTIN opt-in mechanism. This approach does not require replacing the instances of **NonPagedPool** in the driver source. For more information, see [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md). + +By using one of these three approaches, most drivers can be ported quickly and with little effort. + +Avoid simply replacing all instances of **NonPagedPool** in your driver code with **NonPagedPoolExecute**. Use the **NonPagedPoolExecute** pool type only for pool allocations that must be executable (for example, to run code produced by a just-in-time, or JIT, compiler). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NX%20Pool%20Compatibility%20Issues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/nx-pool-opt-in-mechanisms.md b/windows-driver-docs-pr/kernel/nx-pool-opt-in-mechanisms.md new file mode 100644 index 0000000000..d6813109c0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/nx-pool-opt-in-mechanisms.md @@ -0,0 +1,61 @@ +--- +title: NX Pool Opt-In Mechanisms +author: windows-driver-content +description: To port kernel-mode driver code to Windows 8 from earlier versions of Windows, you should use the NonPagedPoolNx type of memory pool as a best practice. +ms.assetid: 9C868569-14EC-4915-8553-FD2D94C5A855 +--- + +# NX Pool Opt-In Mechanisms + + +To port kernel-mode driver code to Windows 8 from earlier versions of Windows, you should use the **NonPagedPoolNx** type of memory pool as a best practice. You can use one of several porting aids to easily "opt in" to use the **NonPagedPoolNx** pool type by default. + +These porting aids use one or both of the following techniques to enable the driver to use NX nonpaged pool: + +- Use a `#define` preprocessor statement to create a globally defined macro name. + +- Call an inline function from the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. + +For most kernel-mode driver code, these porting aids enable developers to update their drivers with minimal effort. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[Single Binary Opt-In: POOL_NX_OPTIN](single-binary-opt-in-pool-nx-optin.md)

To build a single driver binary that runs both in Windows 8 and in earlier versions of Windows, use the POOL_NX_OPTIN opt-in mechanism. This is a porting aid for third-party hardware vendors who supply a single driver binary to support multiple Windows versions.

[Multiple Binary Opt-In: POOL_NX_OPTIN_AUTO](multiple-binary-opt-in-pool-nx-optin-auto.md)

If you are a hardware vendor who supplies different driver binaries for different versions of Windows, you can use the POOL_NX_OPTIN_AUTO opt-in mechanism. This porting aid builds a separate driver binary for Windows 8 and for each earlier version of Windows that your driver supports.

[Selective Opt-Out: POOL_NX_OPTOUT](selective-opt-out-pool-nx-optout.md)

You can globally enable one of the no-execute (NX) pool opt-in mechanisms for a set of driver source files, and then override this opt-in mechanism for one or more selected source files with POOL_NX_OPTOUT. This allows the selected source files to continue to use executable nonpaged memory. You can use the POOL_NX_OPTOUT opt-out mechanism with either the POOL_NX_OPTIN or the POOL_NX_OPTIN_AUTO opt-in mechanism.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20NX%20Pool%20Opt-In%20Mechanisms%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-based.md b/windows-driver-docs-pr/kernel/object-based.md new file mode 100644 index 0000000000..cfac75c2ed --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-based.md @@ -0,0 +1,71 @@ +--- +title: Object-Based +author: windows-driver-content +description: Object-Based +ms.assetid: 53024912-5e6e-4738-81b5-dacc59c22c3f +keywords: ["object-based drivers WDK kernel", "object opacity WDK kernel", "opacity WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object-Based + + +## + + +The Microsoft Windows NT-based operating system is object-based. Various components in the executive define one or more object types. Each component exports kernel-mode support routines that manipulate instances of its object types. No component can directly access another component's objects. To use another component's objects, a component must call the exported support routines. + +This design allows the operating system to be both portable and flexible. For example, it is possible for a future release of the operating system to contain a recoded kernel component that defines the same object types, but with entirely different internal structures. If this hypothetical recoded version of the kernel exports a set of support routines that have the same names and parameters as the existing set, the internal changes would have no effect on the portability of any other executive component in the existing system. + +Likewise, to remain portable and configurable, drivers must communicate with the operating system and with each other by using only the support routines and other interfaces that are described in the WDK. + +Like the operating system, drivers are also object-based. For example: + +- [*File objects*](https://msdn.microsoft.com/library/windows/hardware/ff556280#wdkgloss-file-object) represent a user-mode application's connection to a device. + +- [*Device objects*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-object) represent each driver's logical, virtual, or physical devices. + +- [*Driver objects*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-driver-object) represent each driver's load image. + +The I/O manager defines the structure and interfaces for file objects, device objects, and driver objects. + +Like any other executive component, drivers use objects by calling kernel-mode support routines that the I/O manager and other system components export. Kernel-mode support routines generally have names that identify the specific object that each routine manipulates and the operation that each routine performs on that object. These support routine names have the following form: + +*PrefixOperationObject* + +where + +*Prefix* +Identifies the kernel-mode component that exports the support routine and, usually, the component that defined the object type. Most prefixes have two letters. + +*Operation* +Describes what is done to the object. + +*Object* +Identifies the type of object. + +For example, the I/O manager's [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) routine creates a device object to represent a physical, logical, or virtual device as the target of I/O requests. + +One system component can export routines that call another component's support routines. This can reduce the number of calls that a driver must make. The I/O manager, in particular, exports certain routines that make it easier to develop drivers. For example, [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378), which lowest-level drivers call to register their [*ISRs*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-interrupt-service-routine--isr-), calls the kernel support routines for [*interrupt objects*](https://msdn.microsoft.com/library/windows/hardware/ff556290#wdkgloss-interrupt-object). + +### Object Opacity + +Some system-defined objects are *opaque*: only the defining system component is aware of such an object's internal structure and can directly access all of the data that an object contains. The system component that defines an opaque object exports support routines that drivers and other kernel-mode components can call to manipulate that object. Drivers never access opaque object structures directly. + +**Note**   To maintain driver portability, drivers must use the system-supplied support routines to manipulate system-defined objects. The defining system component can change the internal structure of its object types at any time. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object-Based%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-directories.md b/windows-driver-docs-pr/kernel/object-directories.md new file mode 100644 index 0000000000..ba43204a6d --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-directories.md @@ -0,0 +1,54 @@ +--- +title: Object Directories +author: windows-driver-content +description: Object Directories +ms.assetid: b0e0d077-6736-4a54-b1eb-a30962442942 +keywords: ["object directories WDK kernel", "named objects WDK kernel", "directories WDK objects", "top-level object directories WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Directories + + +## + + +An *object directory* is a named object that is used solely to contain other named objects. For example, the **\\Device** object directory contains the named device objects created by drivers. + +Do not confuse object directories with file system directories. Object directories exist only within the object manager, and do not correspond to any directory on disk. (File system directories are, in fact, represented as file objects.) + +The following is a list of the top-level object directories that contain objects drivers might create or use: + +- **\\Callbacks** + + The system creates standard callback objects in this directory. For more information, see [Using a System-Defined Callback Object](using-a-system-defined-callback-object.md). + +- **\\Device** + + Drivers create named device objects in this directory. For more information, see [Named Device Objects](named-device-objects.md). + +- **\\KernelObjects** + + The system creates standard event objects in this directory. For more information, see [Standard Event Objects](standard-event-objects.md). + +- **\\DosDevices** + + This directory stores the MS-DOS device name of a device as a symbolic link to the corresponding device object. For more information, see [MS-DOS Device Names](ms-dos-device-names.md). + +The system creates other top-level directories, but they are reserved for system use. + +Drivers can create new object directories by calling the [**ZwCreateDirectoryObject**](https://msdn.microsoft.com/library/windows/hardware/ff566421) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object%20Directories%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-handles.md b/windows-driver-docs-pr/kernel/object-handles.md new file mode 100644 index 0000000000..e9bab86919 --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-handles.md @@ -0,0 +1,117 @@ +--- +title: Object Handles +author: windows-driver-content +description: Object Handles +ms.assetid: deeeb3c0-54e4-4727-ac43-6da79be515d7 +keywords: ["object handles WDK user-mode", "object handles WDK kernel", "handles WDK user-mode", "handles WDK kernel", "private object handles WDK", "shared object handles WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Handles + + +## + + +Drivers and user-mode components access most system-defined objects through *handles*. Handles are represented by the HANDLE opaque data type. (Note that handles are not used to access [device objects](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-object) or [driver objects](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-driver-object).) + +For most object types, the kernel-mode routine that creates or opens the object provides a handle to the caller. The caller then uses that handle in subsequent operations on the object. + +Here is a list of object types that drivers typically use, and the routines that provide handles to objects of that type. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Object typeCorresponding create/open routine

File

[IoCreateFile](https://msdn.microsoft.com/library/windows/hardware/ff548418), [ZwCreateFile](https://msdn.microsoft.com/library/windows/hardware/ff566424), [ZwOpenFile](https://msdn.microsoft.com/library/windows/hardware/ff567011)

Registry keys

[IoOpenDeviceInterfaceRegistryKey](https://msdn.microsoft.com/library/windows/hardware/ff549433), [IoOpenDeviceRegistryKey](https://msdn.microsoft.com/library/windows/hardware/ff549443), [ZwCreateKey](https://msdn.microsoft.com/library/windows/hardware/ff566425), [ZwOpenKey](https://msdn.microsoft.com/library/windows/hardware/ff567014)

Threads

[PsCreateSystemThread](https://msdn.microsoft.com/library/windows/hardware/ff559932)

Events

[IoCreateSynchronizationEvent](https://msdn.microsoft.com/library/windows/hardware/ff549045), [IoCreateNotificationEvent](https://msdn.microsoft.com/library/windows/hardware/ff549039)

Symbolic links

[ZwOpenSymbolicLinkObject](https://msdn.microsoft.com/library/windows/hardware/ff567030)

Directory objects

[ZwCreateDirectoryObject](https://msdn.microsoft.com/library/windows/hardware/ff566421)

Section objects

[ZwOpenSection](https://msdn.microsoft.com/library/windows/hardware/ff567029)

+ +  + +When the driver no longer requires access to the object, it calls the [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) routine to close the handle. This works for all of the object types listed in the table above. + +Most of the routines that provide handles take an [**OBJECT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff557749) structure as a parameter. This structure can be used to specify attributes for the handle. + +Drivers can specify the following handle attributes: + +- OBJ\_KERNEL\_HANDLE + + The handle can only be accessed from kernel mode. + +- OBJ\_INHERIT + + Any children of the current process receive a copy of the handle when they are created. + +- OBJ\_FORCE\_ACCESS\_CHECK + + This attribute specifies that the system performs all access checks on the handle. By default, the system bypasses all access checks on handles created in kernel mode. + +Use the [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804) routine to set these attributes in an **OBJECT\_ATTRIBUTES** structure. + +For information about validating object handles, see [Failure to Validate Object Handles](failure-to-validate-object-handles.md). + +### Private Object Handles + +Whenever a driver creates an object handle for its private use, the driver must specify the OBJ\_KERNEL\_HANDLE attribute. This ensures that the handle is inaccessible to user-mode applications. + +### Shared Object Handles + +A driver that shares object handles between kernel mode and user mode must be carefully written to avoid accidentally creating security holes. Here are some guidelines: + +1. Create handles in kernel mode and pass them to user mode, instead of the other way around. Handles created by a user-mode component and passed to the driver should not be trusted. + +2. If the driver must manipulate handles on behalf of user-mode applications, use the OBJ\_FORCE\_ACCESS\_CHECK attribute to verify that the application has the necessary access. + +3. Use [**ObReferenceObjectByPointer**](https://msdn.microsoft.com/library/windows/hardware/ff558686) to keep a kernel-mode reference on a shared handle. Otherwise, if a user-mode component closes the handle, the reference count goes to zero, and if the driver then tries to use or close the handle the system will crash. + +If a user-mode application creates an event object, a driver can safely wait for that event to be signaled, but only if the application passes a handle to the event object to the driver through an IOCTL. The driver must handle the IOCTL in the context of the process that created the event and must validate that the handle is an event handle by calling [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object%20Handles%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-names.md b/windows-driver-docs-pr/kernel/object-names.md new file mode 100644 index 0000000000..98b1c1d66e --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-names.md @@ -0,0 +1,85 @@ +--- +title: Object Names +author: windows-driver-content +description: Object Names +ms.assetid: b30e7475-7f94-4993-b373-8e4a8b1bcb4c +keywords: ["object names WDK kernel", "named objects WDK kernel", "unnamed objects WDK kernel", "object names WDK user-mode", "object handles WDK user-mode", "object handles WDK kernel", "handles WDK user-mode", "handles WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Names + + +## + + +Kernel-mode objects are either named or unnamed. The *object name* is a Unicode string that both user-mode and kernel-mode components can use to refer to the object. For example, **\\KernelObjects\\LowMemoryCondition** is the name of the standard event object that signals when the amount of free memory in the system is low. + +Both user-mode and kernel-mode components use the object name to open a handle to an object. All subsequent operations are performed by using the handle. + +If an object is unnamed, a user-mode component cannot open a handle to it. Kernel-mode components can refer to an unnamed object by either a pointer or a handle. + +Named objects are organized into a hierarchy. Each object is named relative to a parent object. Each component of the object's name begins with a backslash character. For example, **\\KernelObjects** is the parent object for **\\KernelObjects\\LowMemoryCondition**. + +Only some types of objects can have child objects. The following are some examples: + +- Object directories have child objects. The object manager uses object directories to organize objects. For example **\\KernelObjects** is an object directory that holds standard event objects. Object directories do not correspond to actual directories on a disk. For more information, see [Object Directories](object-directories.md). + +- Device objects for disk drives have child objects that correspond to files on the disk. + +- File objects that represent directories have child objects corresponding to files within the directory. + +- Device objects for WDM drivers have their own namespace that can be used in a driver-defined fashion. For more information, see [Controlling Device Namespace Access](controlling-device-namespace-access.md). + +Files have object names that are relative to **\\DosDevices**. For example, the file C:\\Directory\\File can be specified as **\\DosDevices\\C:\\***Directory\\File*. + +For example, the components of the object name can be described as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Object NameDescription

\DosDevices

Object directory.

\DosDevices\C:

Device object representing the C: drive.

\DosDevices\C:\ Directory

File object representing the directory named C:\Directory.

\DosDevices\C:\ Directory \ File

File object representing the file named C:\Directory\File.

+ +  + +Drivers that create named objects do so in specific object directories. For more information, see [Object Directories](object-directories.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object%20Names%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-reference-tracing-with-tags.md b/windows-driver-docs-pr/kernel/object-reference-tracing-with-tags.md new file mode 100644 index 0000000000..7c6279e47f --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-reference-tracing-with-tags.md @@ -0,0 +1,106 @@ +--- +title: Object Reference Tracing with Tags +author: windows-driver-content +description: Object Reference Tracing with Tags +ms.assetid: f6c3d7b2-09b1-4055-b066-cce8831efab2 +keywords: ["object referencing with tags WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Reference Tracing with Tags + + +[Kernel objects](managing-kernel-objects.md) are primitive data objects that the Windows kernel implements in system memory to represent the various parts of the computing environment that are managed by the operating system. Kernel objects represent features such as devices, drivers, files, registry keys, events, semaphores, processes, and threads. + +Most kernel objects are not permanent. To prevent a nonpermanent kernel object from being deleted while a kernel-mode driver uses the object, the driver can obtain a counted reference to the object. When the driver no longer needs the object, the driver releases its reference to the object. + +If a driver does not release all its references to an object, the object's reference count never decrements to zero and the object is never deleted. Therefore, the system resources that are used by the object (for example, system memory) are *leaked*. That is, they cannot be used until the next time that the operating system starts. + +Another type of reference error occurs if a driver *under references* an object. In this case, the driver releases more references to an object than the driver actually holds. This error can cause the object to be deleted prematurely, while other clients are still trying to access the object. + +Leaks and under-references of kernel objects can be difficult bugs to track down. For example, a process object or a device object might have tens of thousands of references. It can be difficult to identify the source of an object reference bug in these circumstances. + +In Windows 7 and later versions of Windows, object references can be tagged to make these bugs easier to find. The following routines associate tags with the acquisition and release of references to kernel objects: + +[**ObDereferenceObjectDeferDeleteWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff557732) + +[**ObDereferenceObjectWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff557734) + +[**ObReferenceObjectByHandleWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff558683) + +[**ObReferenceObjectByPointerWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff558688) + +[**ObReferenceObjectWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff558690) + +For example, **ObReferenceObjectWithTag** and **ObDereferenceObjectWithTag**, which are available in Windows 7 and later versions of Windows, are enhanced versions of the [**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) and [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) routines, which are available in Windows 2000 and later versions of Windows. These enhanced routines enable you to supply a four-byte, custom tag value as an input parameter. The tag value for each call is added to an [object reference trace](http://go.microsoft.com/fwlink/p/?linkid=153590) that can be accessed by the [Windows debugging tools](http://go.microsoft.com/fwlink/p/?linkid=153599). **ObReferenceObject** and **ObDereferenceObject** do not enable the caller to specify custom tags, but, in Windows 7 and later versions of Windows, these routines add default tags (with tag value "Dflt") to the trace. Therefore, a call to **ObReferenceObject** or **ObDereferenceObject** has the same effect as a call to **ObReferenceObjectWithTag** or **ObDereferenceObjectWithTag** that specifies a tag value of "Dflt". (In your program, this tag value is represented as 0x746c6644 or 'tlfD'.) + +To track down a potential object leak or under-reference, identify a set of associated **ObReferenceObject*Xxx*WithTag** and **ObDereferenceObject*Xxx*WithTag** calls in your driver that increment and decrement the reference count of a particular object. Choose a common tag value (for example, "Lky8") to use for all the calls in this set. After your driver is finished using the object, the number of decrements should match the number of increments exactly. If these numbers do not match, your driver has an object reference bug. The debugger can compare the number of increments and decrements for each tag value and tell you if they do not match. With this capability, you can quickly pinpoint the source of the reference-count mismatch. + +To view an object reference trace in the Windows debugging tools, use the [!obtrace](http://go.microsoft.com/fwlink/p/?linkid=153600) kernel-mode debugger extension. In Windows 7 and later versions of Windows, the [!obtrace](http://go.microsoft.com/fwlink/p/?linkid=153600) extension can display object reference tags, if object reference tracing is enabled. By default, object reference tracing is disabled. Use the [Global Flags Editor](http://go.microsoft.com/fwlink/p/?linkid=153601) (Gflags) to enable object reference tracing. For more information about Gflags, see [Configuring Object Reference Tracing](http://go.microsoft.com/fwlink/p/?linkid=153602). + +After object reference tracing is enabled, the output that is produced by the [!obtrace](http://go.microsoft.com/fwlink/p/?linkid=153600) extension includes a "Tag" column, as the following example shows: + +``` +0: kd> !obtrace 0x8a226130 +Object: 8a226130 + Image: leakyapp.exe +Sequence (+/-) Tag Stack +-------- ----- ---- -------------------------------------------- + 36 +1 Dflt nt!ObCreateObject+1c4 + nt!NtCreateEvent+93 + nt!KiFastCallEntry+12a + + 37 +1 Dflt nt!ObpCreateHandle+1c1 + nt!ObInsertObjectEx+d8 + nt!ObInsertObject+1e + nt!NtCreateEvent+ba + nt!KiFastCallEntry+12a + + 38 -1 Dflt nt!ObfDereferenceObjectWithTag+22 + nt!ObInsertObject+1e + nt!NtCreateEvent+ba + nt!KiFastCallEntry+12a + + 39 +1 Lky8 nt!ObReferenceObjectByHandleWithTag+254 + leakydrv!LeakyCtlDeviceControl+6c + nt!IofCallDriver+63 + nt!IopSynchronousServiceTail+1f8 + nt!IopXxxControlFile+6aa + nt!NtDeviceIoControlFile+2a + nt!KiFastCallEntry+12a + + 3a -1 Dflt nt!ObfDereferenceObjectWithTag+22 + nt!ObpCloseHandle+7f + nt!NtClose+4e + nt!KiFastCallEntry+12a + +-------- ----- ---- -------------------------------------------- +References: 3, Dereferences 2 +Tag: Lky8 References: 1 Dereferences: 0 Over reference by: 1 +``` + +The last line in this example indicates that the reference and dereference counts that are associated with the "Lky8" tag do not match and that the result of this mismatch is an over-reference by one (that is, a leak). + +If the result were instead an under-reference, the last line of the [!obtrace](http://go.microsoft.com/fwlink/p/?linkid=153600) output might be as follows: + +``` +Tag: Lky8 References: 1 Dereferences: 2 Under reference by: 1 +``` + +By default, the operating system conserves memory by deleting the object reference trace for an object after the object is freed. To track down an under-reference requires that the trace remain stored in memory even after the object is freed. For this purpose, the Gflags tool provides a "Permanent" option, which preserves the trace in memory while the computer shuts down and starts again. + +Object reference tracing, without tags, was introduced in Windows XP. Because the trace did not include tags, developers had to use less convenient techniques to identify object reference bugs. The debugger could track the references of groups of objects, which the developer selected by object type. The only way that the developer could identify the various sources of object references and dereferences was to compare their call stacks. Although the previous [!obtrace](http://go.microsoft.com/fwlink/p/?linkid=153600) example contains only five stacks, certain types of object, such as a process ([**EPROCESS**](eprocess.md)) object, might be referenced and dereferenced many thousands of times. With thousands of stacks to inspect, it might be difficult to identify the source of an object leak or under-reference without using tags. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object%20Reference%20Tracing%20with%20Tags%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/object-security.md b/windows-driver-docs-pr/kernel/object-security.md new file mode 100644 index 0000000000..1897af81ad --- /dev/null +++ b/windows-driver-docs-pr/kernel/object-security.md @@ -0,0 +1,33 @@ +--- +title: Object Security +author: windows-driver-content +description: Object Security +ms.assetid: 50c174d3-31cd-4e58-9702-64d69e76e977 +keywords: ["object security WDK kernel", "security WDK objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Object Security + + +This section contains the following subsections: + +[Access Rights](access-rights.md) + +[Security Descriptors](security-descriptors.md) + +[Privileges](privileges.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Object%20Security%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/obsolete-and-reserved-kernel-programming-interfaces.md b/windows-driver-docs-pr/kernel/obsolete-and-reserved-kernel-programming-interfaces.md new file mode 100644 index 0000000000..d54db70c17 --- /dev/null +++ b/windows-driver-docs-pr/kernel/obsolete-and-reserved-kernel-programming-interfaces.md @@ -0,0 +1,29 @@ +--- +title: Obsolete and Reserved Kernel Programming Interfaces +author: windows-driver-content +description: This section includes various obsolete and reserved programming interfaces. +ms.assetid: B7805233-C1EB-4764-889E-2A6775389ADF +--- + +# Obsolete and Reserved Kernel Programming Interfaces + + +This section includes various obsolete and reserved programming interfaces. It includes the following topics: + +[Windows kernel obsolete macros](compute-pages-spanned.md) + +[Windows kernel obsolete routines](mmcreatemdl.md) + +[Windows kernel routines reserved for system use](ioacquireremovelockex.md) + +[Windows kernel run-time library obsolete routines](rtlenlargedintegermultiply.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Obsolete%20and%20Reserved%20Kernel%20Programming%20Interfaces%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/obtaining-additional-registry-information.md b/windows-driver-docs-pr/kernel/obtaining-additional-registry-information.md new file mode 100644 index 0000000000..3200d6d17f --- /dev/null +++ b/windows-driver-docs-pr/kernel/obtaining-additional-registry-information.md @@ -0,0 +1,39 @@ +--- +title: Obtaining Additional Registry Information +author: windows-driver-content +description: Obtaining Additional Registry Information +ms.assetid: 989acf63-3bb1-4d9a-a7a8-3eea1e2bc68a +keywords: ["filtering registry calls WDK kernel , additional information to obtain", "registry filtering drivers WDK kernel , additional information to obtain"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Obtaining Additional Registry Information + + +Registry filtering drivers that run on Windows Vista and later operating system versions can obtain the following additional information about registry operations: + +- Object identifiers and names + + The [**CmCallbackGetKeyObjectIDEx**](https://msdn.microsoft.com/library/windows/hardware/jj215789) routine retrieves the registry key identifier and object name that are associated with a specified registry key object. + +- Transaction objects + + The [**CmGetBoundTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff541905) routine returns a pointer to the transaction object that represents the [transaction](using-kernel-transaction-manager.md), if any, that is associated with a registry key object. + +- Version information + + The [**CmGetCallbackVersion**](https://msdn.microsoft.com/library/windows/hardware/ff541912) routine retrieves the major and minor version numbers for the current version of the configuration manager's registry callback feature. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Obtaining%20Additional%20Registry%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/obtaining-configuration-information-from-other-driver-stacks.md b/windows-driver-docs-pr/kernel/obtaining-configuration-information-from-other-driver-stacks.md new file mode 100644 index 0000000000..c9ee727051 --- /dev/null +++ b/windows-driver-docs-pr/kernel/obtaining-configuration-information-from-other-driver-stacks.md @@ -0,0 +1,38 @@ +--- +title: Obtaining Configuration Information from Other Driver Stacks +author: windows-driver-content +description: Obtaining Configuration Information from Other Driver Stacks +ms.assetid: ca0f3d51-24c6-44df-828f-6aeb2565c1ae +keywords: ["I/O WDK kernel , device configuration space", "device configuration space WDK I/O", "configuration space WDK I/O", "space WDK I/O", "driver stacks WDK configuration info", "BUS_INTERFACE_STANDARD"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Obtaining Configuration Information from Other Driver Stacks + + +## + + +At times you need to obtain information from the configuration space of a device whose driver is on a stack other than the one that your driver is on. For instance, suppose you want to set a bit in the configuration space of a PCI-to-PCI bridge and you do not have a pointer to the PDO of the bridge. Although the operating system enumerates PCI-to-PCI bridges and creates a PDO for every bridge on the system, it does not register device interfaces for these devices. Therefore, you cannot use the device interface mechanism to access the configuration space of these bridges. For more information about device interfaces see [Introduction to Device Interfaces](https://msdn.microsoft.com/library/windows/hardware/ff549460). + +In Windows NT 4.0, drivers could access the configuration space of such devices using the [**HalGetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff546599) and [**HalSetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff546628) routines. In Windows 2000 and later versions of Windows, this is no longer the case. + +Windows 2000 and later versions of Windows do not allow drivers to access hardware belonging to other driver stacks. A filter driver can be written to provide the functionality needed. If you wish to access bridge hardware, for instance, you must design a filter driver that implements the required operations on the bridge's configuration space. You must also provide an INF file that specifies the bridge hardware's possible hardware IDs, so the PnP manager can load the filter driver onto the bridge's driver stack when it detects the device ID of the bridge. + +Alternatively, you can install a filter programmatically using **SetupDi*Xxx*** functions in the co-installer for your device. + +The filter driver can then access the bridge using the [**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707) interface. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Obtaining%20Configuration%20Information%20from%20Other%20Driver%20Stacks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---dispatch-level.md b/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---dispatch-level.md new file mode 100644 index 0000000000..58569cf27f --- /dev/null +++ b/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---dispatch-level.md @@ -0,0 +1,149 @@ +--- +title: Obtaining Device Configuration Information at IRQL DISPATCH_LEVEL +author: windows-driver-content +description: Obtaining Device Configuration Information at IRQL DISPATCH_LEVEL +ms.assetid: e168a12b-f32e-4b8d-8768-dc622b37b421 +keywords: ["I/O WDK kernel , device configuration space", "device configuration space WDK I/O", "configuration space WDK I/O", "space WDK I/O", "DISPATCH_LEVEL WDK", "BUS_INTERFACE_STANDARD", "driver stacks WDK configuration info"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Obtaining Device Configuration Information at IRQL = DISPATCH\_LEVEL + + +## + + +The method illustrated in the [Obtaining Device Configuration Information at IRQL = PASSIVE\_LEVEL](obtaining-device-configuration-information-at-irql---passive-level.md) section makes use of I/O request packets (IRPs) and therefore is only valid for drivers running at IRQL = PASSIVE\_LEVEL. Drivers running at IRQL = DISPATCH\_LEVEL must use a bus interface to obtain device configuration space data. To obtain this data, you can use a bus-specific interface or the system-supplied bus-independent bus interface, [**BUS\_INTERFACE\_STANDARD**](https://msdn.microsoft.com/library/windows/hardware/ff540707). + +It is preferable to use **BUS\_INTERFACE\_STANDARD** where possible, because a bus number is not required to retrieve configuration information when using **BUS\_INTERFACE\_STANDARD**, whereas drivers must often identify the bus number when retrieving bus-specific interfaces. Bus numbers for some buses, such as PCI, can change dynamically. Therefore, drivers should not depend on the bus number to access the PCI ports directly. Doing so might lead to system failure. + +Three steps are required when accessing the configuration space of a PCI device at IRQL = DISPATCH\_LEVEL: + +1. Send an [**IRP\_MN\_QUERY\_INTERFACE**](https://msdn.microsoft.com/library/windows/hardware/ff551687) request at IRQL = PASSIVE\_LEVEL to get the direct-call interface structure (**BUS\_INTERFACE\_STANDARD**) from the PCI bus driver. Store this in a nonpaged pool memory (typically in a device extension). + +2. Call the **BUS\_INTERFACE\_STANDARD** interface routines, [*SetBusData*](https://msdn.microsoft.com/library/windows/hardware/gg604856) and [*GetBusData*](https://msdn.microsoft.com/library/windows/hardware/gg604850), to access the PCI configuration space at IRQL = DISPATCH\_LEVEL. + +3. Dereference the interface. The PCI bus driver takes a reference count on the interface before it returns, so the driver that accesses the interface must dereference it, once it is no longer needed. + +The following code sample demonstrates how to implement these three steps: + +``` +NTSTATUS +GetPCIBusInterfaceStandard( + IN PDEVICE_OBJECT DeviceObject, + OUT PBUS_INTERFACE_STANDARD BusInterfaceStandard + ) +/*++ +Routine Description: + This routine gets the bus interface standard information from the PDO. +Arguments: + DeviceObject - Device object to query for this information. + BusInterface - Supplies a pointer to the retrieved information. +Return Value: + NT status. +--*/ +{ + KEVENT event; + NTSTATUS status; + PIRP irp; + IO_STATUS_BLOCK ioStatusBlock; + PIO_STACK_LOCATION irpStack; + PDEVICE_OBJECT targetObject; + + Bus_KdPrint(("GetPciBusInterfaceStandard entered.\n")); + KeInitializeEvent(&event, NotificationEvent, FALSE); + targetObject = IoGetAttachedDeviceReference(DeviceObject); + irp = IoBuildSynchronousFsdRequest(IRP_MJ_PNP, + targetObject, + NULL, + 0, + NULL, + &event, + &ioStatusBlock); + if (irp == NULL) { + status = STATUS_INSUFFICIENT_RESOURCES; + goto End; + } + irpStack = IoGetNextIrpStackLocation( irp ); + irpStack->MinorFunction = IRP_MN_QUERY_INTERFACE; + irpStack->Parameters.QueryInterface.InterfaceType = (LPGUID)&GUID_BUS_INTERFACE_STANDARD; + irpStack->Parameters.QueryInterface.Size = sizeof(BUS_INTERFACE_STANDARD); + irpStack->Parameters.QueryInterface.Version = 1; + irpStack->Parameters.QueryInterface.Interface = (PINTERFACE)BusInterfaceStandard; + irpStack->Parameters.QueryInterface.InterfaceSpecificData = NULL; + + // Initialize the status to error in case the bus driver does not + // set it correctly. + irp->IoStatus.Status = STATUS_NOT_SUPPORTED; + status = IoCallDriver(targetObject, irp); + if (status == STATUS_PENDING) { + KeWaitForSingleObject(&event, Executive, KernelMode, FALSE, NULL); + status = ioStatusBlock.Status; + } +End: + // Done with reference + ObDereferenceObject(targetObject); + return status; +} +``` + +The following code snippet shows how to use the [*GetBusData*](https://msdn.microsoft.com/library/windows/hardware/gg604850) interface routine to get the configuration space data (step 2). + +``` + bytes = busInterfaceStandard.GetBusData( + busInterfaceStandard.Context, + PCI_WHICHSPACE_CONFIG, + Buffer + Offset, + Length); +``` + +When the driver is done with the interface, it can use code similar to the following snippet to dereference the interface (step 3). Drivers must not call interface routines after dereferencing the interface. + +``` + (busInterfaceStandard.InterfaceDereference)( + (PVOID)busInterfaceStandard.Context); +``` + +The interface synchronizes the caller's access to the bus hardware with the PCI bus driver's access. The driver writer need not worry about creating spin locks to avoid contending with the PCI bus driver for access to bus hardware. + +Note, that if all that is needed are bus, function, and device numbers, it is usually unnecessary to resort to a bus interface to obtain this information. This data can be retrieved indirectly by passing the PDO of the target device to the [**IoGetDeviceProperty**](https://msdn.microsoft.com/library/windows/hardware/ff549203) function as follows: + +``` + ULONG propertyAddress, length; + USHORT FunctionNumber, DeviceNumber; + + // Get the BusNumber. Be warned that bus numbers may be + // dynamic and therefore subject to change unpredictably!!! + IoGetDeviceProperty(PhysicalDeviceObject, + DevicePropertyBusNumber, + sizeof(ULONG), + (PVOID)&BusNumber, + &length); + + // Get the DevicePropertyAddress + IoGetDeviceProperty(PhysicalDeviceObject, + DevicePropertyAddress, + sizeof(ULONG), + (PVOID)&propertyAddress, + &length); + + // For PCI, the DevicePropertyAddress has device number + // in the high word and the function number in the low word. + FunctionNumber = (USHORT)((propertyAddress) & 0x0000FFFF); + DeviceNumber = (USHORT)(((propertyAddress) >> 16) & 0x0000FFFF); +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Obtaining%20Device%20Configuration%20Information%20at%20IRQL%20=%20DISPATCH_LEVEL%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---passive-level.md b/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---passive-level.md new file mode 100644 index 0000000000..d8c64e0180 --- /dev/null +++ b/windows-driver-docs-pr/kernel/obtaining-device-configuration-information-at-irql---passive-level.md @@ -0,0 +1,89 @@ +--- +title: Obtaining Device Configuration Information at IRQL PASSIVE_LEVEL +author: windows-driver-content +description: Obtaining Device Configuration Information at IRQL PASSIVE_LEVEL +ms.assetid: 672fb3d8-6e64-425b-a035-8f8ecfd624f1 +keywords: ["I/O WDK kernel , device configuration space", "device configuration space WDK I/O", "configuration space WDK I/O", "space WDK I/O", "PASSIVE_LEVEL WDK", "driver stacks WDK configuration info"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Obtaining Device Configuration Information at IRQL = PASSIVE\_LEVEL + + +## + + +To access device configuration space at IRQL = PASSIVE\_LEVEL, you must use [**IRP\_MN\_READ\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff551727) and [**IRP\_MN\_WRITE\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff551769). You indicate in the IRP stack which configuration space you wish to access and where the I/O buffer is. See the description of the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure for further details. + +The following code sample demonstrates how to access a device's configuration space. + +``` +NTSTATUS +ReadWriteConfigSpace( + IN PDEVICE_OBJECT DeviceObject, + IN ULONG ReadOrWrite, // 0 for read, 1 for write + IN PVOID Buffer, + IN ULONG Offset, + IN ULONG Length + ) +{ + KEVENT event; + NTSTATUS status; + PIRP irp; + IO_STATUS_BLOCK ioStatusBlock; + PIO_STACK_LOCATION irpStack; + PDEVICE_OBJECT targetObject; + + PAGED_CODE(); + KeInitializeEvent(&event, NotificationEvent, FALSE); + targetObject = IoGetAttachedDeviceReference(DeviceObject); + irp = IoBuildSynchronousFsdRequest(IRP_MJ_PNP, + targetObject, + NULL, + 0, + NULL, + &event, + &ioStatusBlock); + if (irp == NULL) { + status = STATUS_INSUFFICIENT_RESOURCES; + goto End; + } + irpStack = IoGetNextIrpStackLocation(irp); + if (ReadOrWrite == 0) { + irpStack->MinorFunction = IRP_MN_READ_CONFIG; + } else { + irpStack->MinorFunction = IRP_MN_WRITE_CONFIG; + } + irpStack->Parameters.ReadWriteConfig.WhichSpace = PCI_WHICHSPACE_CONFIG; + irpStack->Parameters.ReadWriteConfig.Buffer = Buffer; + irpStack->Parameters.ReadWriteConfig.Offset = Offset; + irpStack->Parameters.ReadWriteConfig.Length = Length; + + // Initialize the status to error in case the bus driver does not + // set it correctly. + irp->IoStatus.Status = STATUS_NOT_SUPPORTED; + status = IoCallDriver(targetObject, irp); + if (status == STATUS_PENDING) { + KeWaitForSingleObject(&event, Executive, KernelMode, FALSE, NULL); + status = ioStatusBlock.Status; + } +End: + // Done with reference + ObDereferenceObject(targetObject); + return status; +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Obtaining%20Device%20Configuration%20Information%20at%20IRQL%20=%20PASSIVE_LEVEL%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/opening-a-handle-to-a-file.md b/windows-driver-docs-pr/kernel/opening-a-handle-to-a-file.md new file mode 100644 index 0000000000..e7238e783f --- /dev/null +++ b/windows-driver-docs-pr/kernel/opening-a-handle-to-a-file.md @@ -0,0 +1,81 @@ +--- +title: Opening a Handle to a File +author: windows-driver-content +description: Opening a Handle to a File +ms.assetid: 9378282a-ee29-44b6-b206-602eee94ec3b +keywords: ["files WDK kernel", "file objects WDK kernel", "objects WDK file objects", "file handles WDK kernel", "handle to file WDK kernel", "opening handle to file"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Opening a Handle to a File + + +## + + +To open a handle to a file, perform the following steps: + +1. Create an [**OBJECT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff557749) structure, and call the [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804) macro to initialize the structure. You specify the file's object name as the *ObjectName* parameter to **InitializeObjectAttributes**. + +2. Open a handle to the file by passing the **OBJECT\_ATTRIBUTES** structure to [**IoCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff548418), [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424), or [**ZwOpenFile**](https://msdn.microsoft.com/library/windows/hardware/ff567011). + + If the file does not exist, **IoCreateFile** and **ZwCreateFile** will create it, whereas **ZwOpenFile** will return STATUS\_OBJECT\_NAME\_NOT\_FOUND. + +Note that drivers almost always use **ZwCreateFile** or **ZwOpenFile** rather than **IoCreateFile**. + +When you call **IoCreateFile**, **ZwCreateFile**, or **ZwOpenFile**, the Windows executive creates a new file object to represent the file, and it provides an open handle to the object. This file object persists until you close all the open handles to it. + +Whichever routine you call, you must pass the access rights you need as the *DesiredAccess* parameter. These rights must cover all the operations that your driver will perform. The following table lists these operations and the corresponding access right to request. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationRequired access right

Read from the file.

FILE_READ_DATA or GENERIC_READ

Write to the file.

FILE_WRITE_DATA or GENERIC_WRITE

Write only to the end of the file.

FILE_APPEND_DATA

Read the file's metadata, such as the file's creation time.

FILE_READ_ATTRIBUTES or GENERIC_READ

Write the file's metadata, such as the file's creation time.

FILE_WRITE_ATTRIBUTES or GENERIC_WRITE

+ +  + +For more information about the values available for *DesiredAccess*, see [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Opening%20a%20Handle%20to%20a%20File%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/opening-a-handle-to-a-registry-key-object.md b/windows-driver-docs-pr/kernel/opening-a-handle-to-a-registry-key-object.md new file mode 100644 index 0000000000..777253f3ef --- /dev/null +++ b/windows-driver-docs-pr/kernel/opening-a-handle-to-a-registry-key-object.md @@ -0,0 +1,83 @@ +--- +title: Opening a Handle to a Registry-Key Object +author: windows-driver-content +description: Opening a Handle to a Registry-Key Object +ms.assetid: 451e36a1-1cc2-469e-9f54-c02fef7b1666 +keywords: ["registry WDK kernel , object routines", "driver registry information WDK kernel , object routines", "object routines WDK kernel", "registry-key objects WDK kernel", "opening handle to registry-key object", "handle to registry-key object WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Opening a Handle to a Registry-Key Object + + +## + + +To open a handle to a registry-key object, carry out the following two-step process: + +1. Create an [**OBJECT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff557749) structure, and initialize it by calling [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804). You specify the name of the key to manipulate as the *ObjectName* parameter to **InitializeObjectAttributes**. + + If you pass **NULL** as the *RootDirectory* parameter to **InitializeObjectAttributes**, *ObjectName* must be the full path of the registry key, beginning with **\\Registry**. Otherwise, *RootDirectory* must be an open handle to a key, and *ObjectName* is the path that is relative to that key. + +2. Open a handle to the key object by calling [**ZwCreateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566425) or [**ZwOpenKey**](https://msdn.microsoft.com/library/windows/hardware/ff567014), and pass the **OBJECT\_ATTRIBUTES** structure to it. If the key does not already exist, **ZwCreateKey** will create the key, whereas **ZwOpenKey** will return STATUS\_OBJECT\_NAME\_NOT\_FOUND. + +You pass a *DesiredAccess* parameter to **ZwCreateKey** or **ZwOpenKey** that contains the access rights you are requesting. You must specify the access rights that permit the operations your driver will perform. The following table lists the operations you can perform and the corresponding access rights to request. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationRequired access right

Get a registry-key value.

KEY_QUERY_VALUE or KEY_READ

Set a registry-key value.

KEY_SET_VALUE or KEY_WRITE

Loop through all of the subkeys of a key.

KEY_ENUMERATE_SUB_KEYS or KEY_READ

Create a subkey.

KEY_CREATE_SUB_KEY or KEY_WRITE

Delete a key.

DELETE

+ +  + +For more information about the available values for the *DesiredAccess* parameter, see [**ZwCreateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566425). + +You can also call [**IoOpenDeviceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549443) and [**IoOpenDeviceInterfaceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549433) to open handles to those registry keys that are device specific and device-interface specific, respectively. For more information, see [Plug and Play Registry Routines](plug-and-play-registry-routines.md). + +**Note**  For calls to **ZwCreateKey**, **ZwOpenKey**, **IoOpenDeviceRegistryKey**, and **IoOpenDeviceInterfaceRegistryKey**, the generic access rights, GENERIC\_READ and GENERIC\_WRITE, are equivalent in meaning to the key-specific access rights, KEY\_READ and KEY\_WRITE, respectively, and can be used as substitutes for these key-specific access rights. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Opening%20a%20Handle%20to%20a%20Registry-Key%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/optional-dispatch-routines.md b/windows-driver-docs-pr/kernel/optional-dispatch-routines.md new file mode 100644 index 0000000000..bef0096473 --- /dev/null +++ b/windows-driver-docs-pr/kernel/optional-dispatch-routines.md @@ -0,0 +1,56 @@ +--- +title: Optional Dispatch Routines +author: windows-driver-content +description: Optional Dispatch Routines +ms.assetid: 38a3fcc9-237d-432d-85db-1594697c96a5 +keywords: ["dispatch routines WDK kernel , optional", "optional dispatch routines WDK kernel", "mass storage devices WDK dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Optional Dispatch Routines + + +## + + +Drivers might include the following dispatch routines: + +- [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) + + [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718) indicates that the last handle for a file object that is associated with the target device object is being closed. Outstanding I/O requests for the file object might still exist. Drivers can implement a *DispatchCleanup* routine to perform cleanup that is not specific to any particular file handle. Drivers can also use their [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routine for the same purpose. + +- [*DispatchQueryInformation*](https://msdn.microsoft.com/library/windows/hardware/ff543364), [*DispatchSetInformation*](https://msdn.microsoft.com/library/windows/hardware/ff543399) + + Some highest-level drivers might have to process [**IRP\_MJ\_QUERY\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff550788) and [**IRP\_MJ\_SET\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff550799) IRPs. Such requests indicate that a user-mode application, kernel-mode component, or driver has requested information about the length of the file object (representing the driver's device object) for which the user-mode requester has a handle, or that the user-mode requester is attempting to set an end-of-file on that file object. + + Parallel class and serial device drivers handle these requests by setting the [**FILE\_STANDARD\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff545855) or [**FILE\_POSITION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff545848) length or position to zero. Other highest-level device drivers should support these requests, particularly if a user-mode application or kernel-mode driver might call C runtime functions to manipulate the file object. File system drivers must support these requests more fully than these highest-level device drivers. + +- [*DispatchFlushBuffers*](https://msdn.microsoft.com/library/windows/hardware/ff543314) + + A driver that caches data in a device or buffers data internally in driver-allocated memory might receive [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760). Receipt of this request indicates that the driver should write its buffered data or flush the cached data out to the device, or should discard buffered or cached data that was read from the device. + + For example, the system keyboard and mouse class drivers, which have internal ring buffers for input data from their devices, support the flush request. Drivers of mass-storage devices and drivers layered above them also support this request. + +- [*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) + + Any driver that is likely to be called before the system shuts down must handle [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807). The *DispatchShutdown* routine should do whatever driver-determined cleanup is necessary before the power manager sends a system set-power IRP to shut down the system. A driver can call [**IoRegisterShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549541) or [**IoRegisterLastChanceShutdownNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549518) to register for shutdown notification. + +Drivers for mass-storage devices and intermediate drivers layered over them can rely on a highest-level file system driver to send them shutdown IRPs when the system is about to shut down. That is, the FSD is responsible for making sure that any cached file data is written out to peripheral devices, calling underlying drivers to flush data from their device caches or buffers (if any), and so forth before the system is shut down. + +The driver of a mass-storage device that caches data internally must provide *DispatchShutdown* and *DispatchFlushBuffers* routines. If a mass-storage driver buffers data in memory but its device has no internal cache, it also must provide *DispatchShutdown* and *DispatchFlushBuffers* routines. + +Any intermediate driver layered above a driver that handles [**IRP\_MJ\_FLUSH\_BUFFERS**](https://msdn.microsoft.com/library/windows/hardware/ff550760) and [**IRP\_MJ\_SHUTDOWN**](https://msdn.microsoft.com/library/windows/hardware/ff550807) requests also provide *DispatchShutdown* and *DispatchFlushBuffers* routines. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Optional%20Dispatch%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/organization-of-dpc-queues.md b/windows-driver-docs-pr/kernel/organization-of-dpc-queues.md new file mode 100644 index 0000000000..3b39d9115d --- /dev/null +++ b/windows-driver-docs-pr/kernel/organization-of-dpc-queues.md @@ -0,0 +1,39 @@ +--- +title: Organization of DPC Queues +author: windows-driver-content +description: Organization of DPC Queues +ms.assetid: df176a6d-d7a7-4d8b-ab1b-fd7f5b89fcbe +keywords: ["DPC queues WDK kernel", "queues WDK DPC"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Organization of DPC Queues + + +The system provides one DPC queue for each processor. Drivers can control which queue the system assigns a DPC to, the location of the DPC within the queue, and when the queue is processed. + +DPCs that are assigned to a particular processor's queue are run on that processor. By default, when the driver calls [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185) or [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657), the DPC is queued on the currently active processor. Drivers can specify the processor queue by calling [**KeSetTargetProcessorDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553278) before calling **KeInsertQueueDpc** or **IoRequestDpc**. + +On Windows Vista and later versions of Windows, the system also has one threaded DPC queue for each processor. Drivers can use **KeSetTargetProcessorDpc** to specify the processor queue for threaded DPCs. + +The [**KeSetImportanceDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553259) routine controls where a DPC is placed within the queue. Typically, the DPC is placed at the end of the queue; but if the driver first calls **KeSetImportanceDpc** with the *Importance* parameter equal to **HighImportance**, the DPC is placed at the beginning of the queue. + +For ordinary (non-threaded) DPCs, **KeSetImportanceDpc** also determines whether **KeInsertQueueDpc** or **IoRequestDpc** will immediately begin processing the DPC queue. The following list describes the rules for processing the queue: + +- Processing of the DPC queue begins immediately if the DPC is assigned to the current processor and *Importance* is not equal to **LowImportance**, or if *Importance* is equal to **LowImportance** and the DPC queue depth of the current processor exceeds a system-defined limit or the DPC request rate has fallen below a system-defined minimum. Otherwise, processing of the DPC is deferred until the appropriate queue depth and rate requirements are met. + +- Processing of the DPC queue begins immediately on the target processor if the DPC is assigned to a processor that is different than the current processor and *Importance* equals **MediumHighImportance** or **HighImportance**, or if the DPC queue depth of the target processor exceeds a system-defined limit. Otherwise, processing of the DPC is deferred until the appropriate queue depth and rate requirements are met. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Organization%20of%20DPC%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/other-standard-driver-routines.md b/windows-driver-docs-pr/kernel/other-standard-driver-routines.md new file mode 100644 index 0000000000..fa0871d1f2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/other-standard-driver-routines.md @@ -0,0 +1,34 @@ +--- +title: Other Standard Driver Routines +author: windows-driver-content +description: Other Standard Driver Routines +ms.assetid: 3dada9cc-7239-47de-8940-bc4cef8be4ca +keywords: ["driver objects WDK kernel", "standard driver routines WDK kernel , driver objects", "driver routines WDK kernel , driver objects", "routines WDK kernel , driver objects", "objects WDK driver objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Other Standard Driver Routines + + +## + + +As the [driver object illustration](introduction-to-driver-objects.md#driver-object-illustration) shows, kernel-mode drivers have other standard routines along with those for which they set entry points in their respective driver objects. Most standard driver routines and some of the configuration-dependent objects they use are defined by the I/O manager. The ISR, *SynchCritSection* routine, and those shown in the Driver Object figure with names containing the word "custom" are defined by the NT kernel. + +Most drivers use the [device extension](device-extensions.md) of each device object they create to maintain device-specific state about their I/O operations and to store pointers to any system resources that they must allocate in order to have other standard routines. For example, the **DDCustomTimerDpc** routine shown in the Driver Object figure requires the driver to supply storage for kernel-defined timer and DPC objects. + +The set of standard driver routines for lowest-level drivers shown on the left in the [driver object illustration](introduction-to-driver-objects.md#driver-object-illustration) is necessarily different from the set for higher-level drivers. Some of the routines shown in this figure are device-dependent or configuration-dependent requirements. Others are optional: you may choose to implement such a routine depending on the nature or configuration of the driver's devices, on the driver's design, and on the driver's position in a chain of layered drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Other%20Standard%20Driver%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-the-power-management-framework.md b/windows-driver-docs-pr/kernel/overview-of-the-power-management-framework.md new file mode 100644 index 0000000000..590a877fa1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-the-power-management-framework.md @@ -0,0 +1,51 @@ +--- +title: Overview of the Power Management Framework +author: windows-driver-content +description: Starting with Windows 8, the run-time power management framework (PoFx) supports power and clock management at the component (or subdevice) level. +ms.assetid: 9F2D8ACD-44D5-46E0-9FC7-1B38B99450FF +--- + +# Overview of the Power Management Framework + + +Starting with Windows 8, the run-time power management framework (PoFx) supports power and clock management at the component (or subdevice) level. A device driver registers with PoFx to independently manage power usage in the individual components in a device. PoFx provides the fine-grained control necessary to extend the time that a Windows portable computer, tablet, phone, or other mobile device can run on a battery charge. PoFx reduces power usage in a way that maintains the appearance of a mobile device that is always on and always connected. + +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 example, an audio device might have separate components for playback and recording whose power states can be managed independently of each other. If the playback component is being used, but the recording component is idle, the recording component can be switched to a low-power state without interfering with the activity of the playback component. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + +
TopicDescription

[Component-Level Power Management](component-level-power-management.md)

Starting with Windows 8, the power management framework (PoFx) enables a driver to manage the power states of the individual components in a device. Component-level power management exists side-by-side with device-level power management.

[Component-Level Performance State Management](component-level-performance-management.md)

Starting with Windows 10, the power management framework (PoFx) enables a driver to define one or more sets of individually adjustable performance states for individual components within a device. The driver can use performance states to throttle a component's workload to provide just enough performance for its current needs.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20the%20Power%20Management%20Framework%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-the-windows-i-o-model.md b/windows-driver-docs-pr/kernel/overview-of-the-windows-i-o-model.md new file mode 100644 index 0000000000..467e70e26a --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-the-windows-i-o-model.md @@ -0,0 +1,40 @@ +--- +title: Overview of the Windows I/O Model +author: windows-driver-content +description: Overview of the Windows I/O Model +ms.assetid: 17a012b7-946e-4f42-8d80-e270bc26de06 +keywords: ["IRPs WDK kernel , about Windows I/O model", "Windows I/O model WDK", "I/O WDK kernel , model"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of the Windows I/O Model + + +## + + +Every operating system has an implicit or explicit I/O model for handling the flow of data to and from peripheral devices. One feature of the Microsoft Windows I/O model is its support for asynchronous I/O. In addition, the I/O model has the following general features: + +- The I/O manager presents a consistent interface to all kernel-mode drivers, including lowest-level, intermediate, and file system drivers. All I/O requests to drivers are sent as I/O request packets (IRPs). + +- I/O operations are layered. The I/O manager exports I/O system services, which user-mode protected subsystems call to carry out I/O operations on behalf of their applications and/or end users. The I/O manager intercepts these calls, sets up one or more IRPs, and routes them through possibly layered drivers to physical devices. + +- The I/O manager defines a set of standard routines, some required and others optional, that drivers can support. All drivers follow a relatively consistent implementation model, given the differences among peripheral devices and the differing functionality required of bus, function, filter, and file system drivers. + +- Like the operating system itself, drivers are object-based. Drivers, their devices, and system hardware are represented as objects. The I/O manager and other operating system components export kernel-mode support routines that drivers can call to get work done by manipulating the appropriate objects. + +In addition to using IRPs to convey traditional I/O requests, the I/O manager works with the PnP and power managers to send IRPs containing PnP and power requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20the%20Windows%20I/O%20Model%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-wait-wake-irp-completion.md b/windows-driver-docs-pr/kernel/overview-of-wait-wake-irp-completion.md new file mode 100644 index 0000000000..509a2f7ebf --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-wait-wake-irp-completion.md @@ -0,0 +1,44 @@ +--- +title: Overview of Wait/Wake IRP Completion +author: windows-driver-content +description: Overview of Wait/Wake IRP Completion +ms.assetid: a5e09fda-f722-4335-8576-7b058b2f7a21 +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "wait/wake IRPs WDK power management , completing"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of Wait/Wake IRP Completion + + +## + + +A wait/wake IRP completes when a wake-up signal arrives. The wake-up signal is device-specific but is generally a normal service event for the device. For example, an incoming ring might cause a sleeping modem to awaken. + +The following figure shows the steps in completing a wait/wake IRP. + +![steps for completing a wait/wake irp](images/comp-waitwake.png) + +When the signal occurs, control re-enters the bus driver at the point where the bus detects that the device has awakened. The bus driver services the event as required and calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) IRP for its PDO. + +The I/O manager then calls the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine set by the next-higher driver in the device stack. In the *IoCompletion* routine, that driver services the wake-up signal as necessary and calls **IoCompleteRequest** to complete the IRP. The I/O manager continues to call *IoCompletion* routines working back up the device stack until all drivers have completed the IRP. + +In its *IoCompletion* routine, any driver that enumerates more than one child device (creates more than one PDO) and has received wait/wake requests from more than one such device must send itself a wait/wake IRP to re-arm itself for wait/wake on another child. For details, see [Understanding the Path of Wait/Wake IRPs through a Device Tree](understanding-the-path-of-wait-wake-irps-through-a-device-tree.md). + +After calling *IoCompletion* routines set by drivers as they passed the IRP down the stack, the I/O manager invokes the callback routine set by the power policy owner when it requested the wait/wake IRP. In the callback routine, the policy owner should return its device to the working state and complete a pending wait/wake IRP for its child's PDO, if any. + +Completing the child's IRP causes the I/O manager to call *IoCompletion* routines set by drivers in the child's device stack, and so on. Eventually, the policy owner that started the original wait/wake IRP on the devnode determines that its device asserted the wake-up signal, and all the pending wait/wake IRPs will be complete. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20Wait/Wake%20IRP%20Completion%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-wait-wake-operation.md b/windows-driver-docs-pr/kernel/overview-of-wait-wake-operation.md new file mode 100644 index 0000000000..b6e038d89d --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-wait-wake-operation.md @@ -0,0 +1,56 @@ +--- +title: Overview of Wait/Wake Operation +author: windows-driver-content +description: Overview of Wait/Wake Operation +ms.assetid: 63453f7e-f656-4efc-bb44-9e2cb0232270 +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "wait/wake IRPs WDK power management , about wait/wake IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of Wait/Wake Operation + + +## + + +The operating system's wake-up mechanism works as shown in the following figure. + +![diagram illustrating an overview of irp\-mn\-wait\-wake processing](images/send-waitwake.png) + +1. While the system and device are in the working state, the power policy owner for a device determines that its device should be enabled ("armed") for wake-up. The power policy owner requests a power IRP ([**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) with minor code [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766)) to be sent to its PDO to inform all drivers in its device stack. In the request, the policy owner specifies a callback routine (not the same as an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine). + +2. The power manager, through the I/O manager, sends the IRP to the top of the device stack. + +3. Drivers set *IoCompletion* routines and pass the IRP down until it reaches the bus driver. + +4. The bus driver enables wake-up on the physical device, if it can, and marks the IRP pending. If necessary, it also requests a wait/wake IRP for its parent. + +5. Sometime later, an external wake-up signal arrives. + +6. The bus driver completes the **IRP\_MN\_WAIT\_WAKE**. + +7. I/O manager calls *IoCompletion* routines that were set as drivers passed the IRP down the stack. + +8. I/O manager calls the callback routine set by the policy owner when it requested the IRP. + +The **IRP\_MN\_WAIT\_WAKE** request does not change the power state of the device or the system. It merely enables wake-up on the device so that later, if the device enters an appropriate sleep state, an external signal will cause the device (and possibly the system) to awaken. + +When a wake-up signal arrives, the drivers' behavior is the same whether the device wakes the system or only itself. If the device is enabled for wake-up and the system is in a sleep state from which the device can awaken it, the device will awaken the system. If the device is enabled for wake-up and the system is in the working state, only the device will awaken. + +Because computers and devices vary in design, particularly with respect to power planes, the supported system and device power states -- and thus the states that can support wait/wake -- are not the same on all hardware configurations. Therefore, any driver that owns power policy for its device and every bus driver must pay careful attention to the capabilities of the individual configuration on which it is running. For further information, see [Determining Whether a Device Can Wake the System](determining-whether-a-device-can-wake-the-system.md). + +For further details on wait/wake operations, see [Understanding the Path of Wait/Wake IRPs through a Device Tree](understanding-the-path-of-wait-wake-irps-through-a-device-tree.md) and [Overview of Wait/Wake IRP Completion](overview-of-wait-wake-irp-completion.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20Wait/Wake%20Operation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-windows-components.md b/windows-driver-docs-pr/kernel/overview-of-windows-components.md new file mode 100644 index 0000000000..0a5bc29072 --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-windows-components.md @@ -0,0 +1,40 @@ +--- +title: Overview of Windows Components +author: windows-driver-content +description: Overview of Windows Components +ms.assetid: b941197d-732c-4b9a-8367-46beb14c33cf +keywords: ["Windows components WDK", "Windows NT components WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of Windows Components + + +## + + +The following figure shows the major internal components of the Windows operating system. + +![diagram illustrating an overview of windows components](images/ntarch.png) + +As the figure shows, the Windows operating system includes both user-mode and kernel-mode components. For more information about Windows user and kernel modes, see [User Mode and Kernel Mode](https://msdn.microsoft.com/library/windows/hardware/ff554836). + +Drivers call routines that are exported by various kernel components. For example, to create a device object, you would call the [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) routine which is exported by the I/O manager. For a list of kernel-mode routines that drivers can call, see [Driver Support Routines](https://msdn.microsoft.com/library/windows/hardware/ff544200). + +In addition, drivers must respond to specific calls from the operating system and can respond to other system calls. For a list of kernel mode routines that drivers may need to support, see [Standard Driver Routines](https://msdn.microsoft.com/library/windows/hardware/ff563842). + +Not all kernel-mode components are pictured in the figure above. For a list of kernel mode components, see [Kernel-Mode Managers and Libraries](kernel-mode-managers-and-libraries.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20Windows%20Components%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/overview-of-windows-memory-space.md b/windows-driver-docs-pr/kernel/overview-of-windows-memory-space.md new file mode 100644 index 0000000000..a366eef0c6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/overview-of-windows-memory-space.md @@ -0,0 +1,38 @@ +--- +title: Overview of Windows Memory Space +author: windows-driver-content +description: Overview of Windows Memory Space +ms.assetid: b49a35c2-6da6-4239-a67b-542d42a5c9e4 +keywords: ["memory management WDK kernel , about memory space", "memory space WDK kernel", "physical memory WDK kernel", "virtual memory WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Overview of Windows Memory Space + + +## + + +The following figure illustrates the NT-based operating system's virtual memory spaces and their relationship to system physical memory. + +![diagram illustrating virtual memory spaces and physical memory](images/16vrtmem.gif) + +As this figure shows, virtual memory is backed by paged physical memory, and a virtual address range can be backed by discontiguous physical memory pages. User-space virtual memory and system-space memory allocated from paged pool are always *pageable*. Any user-space code or data can be paged out to secondary storage at any time, even while the process is executing. + +Note that any noncurrent process's virtual addresses are not visible, so its memory space is inaccessible. + +For an extensive discussion of memory management, see the *Inside Microsoft Windows Internals* book from Microsoft Press. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Overview%20of%20Windows%20Memory%20Space%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/packet-driven-i-o-with-reusable-irps.md b/windows-driver-docs-pr/kernel/packet-driven-i-o-with-reusable-irps.md new file mode 100644 index 0000000000..18eaf7e70e --- /dev/null +++ b/windows-driver-docs-pr/kernel/packet-driven-i-o-with-reusable-irps.md @@ -0,0 +1,54 @@ +--- +title: Packet-Driven I/O with Reusable IRPs +author: windows-driver-content +description: Packet-Driven I/O with Reusable IRPs +ms.assetid: ff315b61-9fa3-4a20-bc3e-82db0ea3cde7 +keywords: ["I/O stack locations WDK kernel", "packet-driven I/O WDK kernel", "reusing IRPs WDK kernel", "headers WDK kernel", "I/O manager communication WDK kernel", "I/O status blocks WDK kernel", "status blocks WDK kernel", "stack locations WDK kernel", "IRPs WDK kernel , reusing"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Packet-Driven I/O with Reusable IRPs + + +## + + +The I/O manager, Plug and Play manager, and power manager use *I/O request packets* (IRPs) to communicate with kernel-mode drivers, and to allow drivers to communicate with each other. + +The I/O manager performs the following steps: + +- Accepts I/O requests, which usually originate from user-mode applications. + +- Creates IRPs to represent the I/O requests. + +- Routes the IRPs to the appropriate drivers. + +- Tracks the IRPs until they are completed. + +- Returns the status to the original requester of each I/O operation. + +An IRP might be routed to more than one driver. For example, a request to open a file on a disk might go first to a file system driver, through an intermediate mirror driver, and ultimately to a disk driver and, possibly, to a PnP hardware bus driver. This set of drivers is known as a *driver stack*. + +Therefore, each IRP has a *fixed part*, plus one driver-specific *I/O stack location* for each driver that controls the device: + +- In the fixed part (or *header*), the I/O manager maintains information about the original request, such as the caller's thread ID and parameters, the address of the device object on which a file is open, and so forth. The fixed part also contains an *I/O status block*, in which drivers set information about the status of the requested I/O operation. + +- In the highest-level driver's I/O stack location, the I/O manager, Plug and Play manager, or power manager sets driver-specific parameters, such as the function code of the requested operation and the context that the corresponding driver uses to determine what it should do. In turn, each driver sets up the I/O stack location of the next-lower driver in the driver stack. + +As each driver processes an IRP, it can access its I/O stack location in the IRP, thereby reusing the IRP at each stage of the driver's operations. In addition, higher-level drivers can create (or reuse) IRPs to send requests down to even lower-level drivers. + +For a detailed discussion of IRPs, see [Handling IRPs](handling-irps.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Packet-Driven%20I/O%20with%20Reusable%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/paging-an-entire-driver.md b/windows-driver-docs-pr/kernel/paging-an-entire-driver.md new file mode 100644 index 0000000000..ade6c2d348 --- /dev/null +++ b/windows-driver-docs-pr/kernel/paging-an-entire-driver.md @@ -0,0 +1,46 @@ +--- +title: Paging an Entire Driver +author: windows-driver-content +description: Paging an Entire Driver +ms.assetid: d861160f-e429-4ff3-9ca6-4fce4d5d6c1b +keywords: ["pageable drivers WDK kernel , paging entire drivers", "paging entire drivers WDK", "reference counts WDK pageable drivers", "overriding pageable or nonpageable attributes WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Paging an Entire Driver + + +## + + +A driver that uses the **MmLockPagable*Xxx*** support routines and specifies paged and discardable sections consists of nonpaged sections, paged sections, and an INIT section that is discarded after driver initialization. + +After a device driver connects interrupts for the devices it manages, the driver's interrupt handling path must be resident in system space. The interrupt-handling code must be part of the driver section that cannot be paged out, in case an interrupt occurs. + +Two additional memory manager routines, [**MmPageEntireDriver**](https://msdn.microsoft.com/library/windows/hardware/ff554650) and [**MmResetDriverPaging**](https://msdn.microsoft.com/library/windows/hardware/ff554680), can be used to override the pageable or nonpageable attributes of all sections that make up a driver image. These routines enable a driver to be paged out in its entirety when the device it manages is not being used and cannot generate interrupts. + +Examples of system drivers that are completely pageable are the win32k.sys driver, the serial driver, the mailslot driver, the beep driver and the null driver. + +A serial driver is typically used intermittently. Until a port it manages is opened, a serial driver can be paged out completely. As soon as a port is opened, the parts of the serial driver that must be memory-resident must be brought into nonpaged system space. Other parts of the driver can remain pageable. + +A driver that can be completely paged out should call **MmPageEntireDriver** during driver initialization before interrupts are connected. + +When a device managed by a paged-out driver receives an open request, the driver is paged in. Then, the driver must call [**MmResetDriverPaging**](https://msdn.microsoft.com/library/windows/hardware/ff554680) before it connects to interrupts. Calling **MmResetDriverPaging** causes the memory manager to treat the driver's sections according to the attributes acquired during compilation and linkage. Any section that is nonpaged, such as a text section, will be paged into nonpaged system memory; pageable sections will be paged in as they are referenced. + +Such a driver must keep a reference count of open handles to its devices. The driver increments the count at each open request for any device and decrements the count at each close request. When the count reaches zero, the driver should disconnect interrupts and then call **MmPageEntireDriver**. If a driver manages more than one device, the count must be zero for all such devices before the driver can call **MmPageEntireDriver**. + +It is the driver's responsibility to do whatever synchronization is necessary when changing the reference count, and to prevent the reference count from changing while the pageable state of the driver is changing. That is, in SMP computers, the driver must make sure that **MmPageEntireDriver** cannot be in progress on one processor, while on another processor, an open call is causing interrupts to be connected and the reference count to be incremented. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Paging%20an%20Entire%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/passing-irps-down-the-driver-stack.md b/windows-driver-docs-pr/kernel/passing-irps-down-the-driver-stack.md new file mode 100644 index 0000000000..8fa59d6625 --- /dev/null +++ b/windows-driver-docs-pr/kernel/passing-irps-down-the-driver-stack.md @@ -0,0 +1,71 @@ +--- +title: Passing IRPs down the Driver Stack +author: windows-driver-content +description: Passing IRPs down the Driver Stack +ms.assetid: 69d912c5-83cf-4651-b379-de6baea8ddd0 +keywords: ["IRPs WDK kernel , passing down stack", "passing IRPs down driver stack WDK", "transferring IRPs down driver stack", "I/O stack locations WDK kernel", "stack locations WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Passing IRPs down the Driver Stack + + +## + + +When a driver's dispatch routine receives an IRP, it must call [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) so that it can check its own I/O stack location and determine that any parameters are valid. If the driver cannot satisfy and complete the request itself, it can do one of the following: + +- Pass the IRP on for further processing by lower-level drivers. + +- Create one or more new IRPs and pass them down to lower-level drivers. + +### A higher-level driver should pass an I/O request on to a next-lower driver as follows: + +1. If the driver will pass the input IRP on to the next lower-level driver, the dispatch routine should call [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) or [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) to set up the I/O stack location of the next-lower driver. + + If the driver calls [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) to allocate one or more additional IRPs for lower drivers, the dispatch routine must initialize the next-lower driver's I/O stack location by following the steps that are described in [Processing IRPs in an Intermediate-Level Driver](processing-irps-in-an-intermediate-level-driver.md). + + The dispatch routine can modify some of the parameters in the next-lower driver's I/O stack location for certain requests. For example, a higher-level driver might modify the parameters for a large transfer request when the underlying device has a known limit in transfer capacity, and reuse the IRP to send partial-transfer requests to the underlying device driver. + +2. Call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). + + If the dispatch routine is passing a received IRP to the next-lower driver, setting an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine is optional but useful, because the routine can perform such tasks as determining how lower drivers completed the request, reusing the IRP for partial transfers, updating whatever state the driver maintains if it tracks IRPs, and retrying a request that was returned with an error. + + If the dispatch routine has allocated new IRPs, setting an *IoCompletion* routine is required because the routine must release each IRP after lower drivers have completed it. + + For more information about *IoCompletion* routines, see [Completing IRPs](completing-irps.md). + +3. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) with each IRP to be processed by lower drivers. + +4. Return an appropriate NTSTATUS value, such as: + - STATUS\_PENDING + + The driver usually returns STATUS\_PENDING if the input IRP is an asynchronous request, such as [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819). + + - The result of the call to **IoCallDriver** + + The driver frequently returns the result of the call to **IoCallDriver** if the input IRP is a synchronous request, such as [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729). + +### A lowest-level device driver passes any IRP that it cannot complete in its dispatch routine on to other driver routines as follows: + +1. Call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) with the input IRP. + +2. Call [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) to pass on or queue the IRP to the driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, unless the driver manages its own internal IRP queuing, as described in [Driver-Managed IRP Queues](driver-managed-irp-queues.md). + + If the driver does not have a *StartIo* routine but handles cancelable IRPs, it must either register a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine or implement a [cancel-safe IRP queue](cancel-safe-irp-queues.md). For more information about *Cancel* routines, see [Canceling IRPs](canceling-irps.md). + +3. Return STATUS\_PENDING. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Passing%20IRPs%20down%20the%20Driver%20Stack%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/passing-pnp-irps-down-the-device-stack.md b/windows-driver-docs-pr/kernel/passing-pnp-irps-down-the-device-stack.md new file mode 100644 index 0000000000..6e0c319a1d --- /dev/null +++ b/windows-driver-docs-pr/kernel/passing-pnp-irps-down-the-device-stack.md @@ -0,0 +1,58 @@ +--- +title: Passing PnP IRPs Down the Device Stack +author: windows-driver-content +description: Passing PnP IRPs Down the Device Stack +ms.assetid: 339ef4b4-1b4f-42ac-ab57-c53b83120f0d +keywords: ["PnP WDK kernel , passing IRPs down device stack", "Plug and Play WDK kernel , passing IRPs down device stack", "IRPs WDK PnP", "I/O request packets WDK PnP", "passing IRPs down device stack WDK", "IoCompletion routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Passing PnP IRPs Down the Device Stack + + +## + + +The PnP manager uses IRPs to direct drivers to start, stop, and remove devices and to query drivers about their devices. All PnP IRPs have the major function code [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772), and all PnP drivers must provide a [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine to service this function code. The PnP manager initializes **Irp->IoStatus.Status** to STATUS\_NOT\_SUPPORTED when it sends an IRP. For more information, see [DispatchPnP Routines](dispatchpnp-routines.md). + +For a list of PnP minor IRPs, see [Plug and Play Minor IRPs](plug-and-play-minor-irps.md). + +All drivers for a device must have the opportunity to respond to a PnP IRP unless a driver in the stack fails the IRP. (See the following figure.) + +![diagram illustrating passing a plug and play irp down the device stack](images/passpnp.png) + +No single driver for a device can assume that it is the only driver that will respond to a PnP IRP. Consider, for example, a function driver that responds to an [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) request and completes the IRP without passing it to the next-lower driver. None of the capabilities supported by lower drivers, such as a unique instance ID or power management capabilities supported by the parent bus driver, is reported. + +A PnP IRP travels back up the device stack when the parent bus driver calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) and the I/O manager calls any [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines registered by the function driver or filter drivers. + +A function or filter driver must do the following when it receives a PnP IRP: + +- If the driver performs actions in response to the IRP: + 1. Perform the appropriate actions. + 2. Set **Irp->IoStatus.Status** to an appropriate status, such as STATUS\_SUCCESS. Set **Irp->IoStatus.Information**, if appropriate for the IRP. + 3. Set up the next stack location with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) or [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387). Call the latter routine if you set an *IoCompletion* routine. + 4. Set an *IoCompletion* routine, if necessary. + 5. Do not complete the IRP. (Do not call **IoCompleteRequest**.) The parent bus driver will complete the IRP. +- If the driver does not perform actions for this IRP, it simply prepares to pass the IRP to the next driver: + 1. Call **IoSkipCurrentIrpStackLocation** to remove its stack location from the IRP. + 2. Do not set any fields in **Irp->IoStatus**. + 3. Do not set an *IoCompletion* routine. + 4. Do not complete the IRP. (Do not call **IoCompleteRequest**.) The parent bus driver will complete the IRP. + +If a function or filter driver did not fail the IRP, it passes the IRP to the next-lower driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). A driver has a pointer to the next-lower driver; that pointer was returned from the [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300) call in the higher driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +The parent bus driver completes the IRP after performing any tasks to respond to the IRP. After the bus driver calls **IoCompleteRequest**, the I/O manager calls any *IoCompletion* routines registered by the function or filter drivers for the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Passing%20PnP%20IRPs%20Down%20the%20Device%20Stack%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/passing-power-irps.md b/windows-driver-docs-pr/kernel/passing-power-irps.md new file mode 100644 index 0000000000..49d967196d --- /dev/null +++ b/windows-driver-docs-pr/kernel/passing-power-irps.md @@ -0,0 +1,90 @@ +--- +title: Passing Power IRPs +author: windows-driver-content +description: Passing Power IRPs +ms.assetid: 01473eb0-ae60-4a95-9ae7-97b2b982d3d1 +keywords: ["power IRPs WDK kernel , passing", "passing IRPs down device stack WDK", "DispatchPower routine", "dispatch routines WDK power management", "PoStartNextPowerIrp"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Passing Power IRPs + + +## + + +Power IRPs must be passed all the way down the device stack to the PDO to ensure that power transitions are managed cleanly. Drivers handle an IRP that reduces device power as the IRP travels down the device stack. Drivers handle an IRP that applies device power in [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines as the IRP travels back up the device stack. + +The following figure shows the steps that drivers need to take to pass a power IRP down a device stack in Windows 7 and Windows Vista. + +![diagram illustrating passing down a power irp in windows vista](images/passirpvista.png) + +As the previous figure shows, in Windows 7 and Windows Vista, a driver must do the following: + +1. Call [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) if setting an *IoCompletion* routine, or [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) if not setting an *IoCompletion* routine. + + These two routines set the IRP stack location for the next-lower driver. Copying the current stack location ensures that the IRP stack pointer is set to the correct location when the *IoCompletion* routine runs. + + If a badly written driver makes the mistake of calling **IoSkipCurrentIrpStackLocation** and then setting a completion routine, this driver might overwrite a completion routine set by the driver below it. + +2. Call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) to set an *IoCompletion* routine, if a complete routine is required. + +3. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) to pass the IRP to the next-lower driver in the stack. + +The following figure shows the steps that drivers need to take to pass a power IRP down a device stack in Windows Server 2003, Windows XP, and Windows 2000. + +![passing down a power irp (windows server 2003, windows xp, and windows 2000)](images/passirp.png) + +As the previous figure shows, a driver must do the following: + +1. Depending on the type of driver, possibly call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776). For more information, see [Calling PoStartNextPowerIrp](calling-postartnextpowerirp.md). + +2. Call [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) if setting an *IoCompletion* routine, or [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) if not setting an *IoCompletion* routine. + + These two routines set the IRP stack location for the next-lower driver. Copying the current stack location ensures that the IRP stack pointer is set to the correct location when the *IoCompletion* routine runs. + +3. Call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) to set an *IoCompletion* routine. In the *IoCompletion* routine, most drivers [call PoStartNextPowerIrp](calling-postartnextpowerirp.md) to indicate that it is ready to handle the next power IRP. + +4. Call [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) to pass the IRP to the next-lower driver in the stack. + + Drivers must use **PoCallDriver**, rather than **IoCallDriver** (as for other IRPs) to ensure that the system synchronizes power IRPs properly. For more information, see [Calling IoCallDriver vs. Calling PoCallDriver](calling-iocalldriver-versus-calling-pocalldriver.md). + +Remember that *IoCompletion* routines can be called at IRQL = DISPATCH\_LEVEL. Therefore, if a driver requires additional processing at IRQL = PASSIVE\_LEVEL after lower-level drivers have finished with the IRP, the driver's completion routine should queue a work item and then return STATUS\_MORE\_PROCESSING\_REQUIRED. The worker thread must complete the IRP. + +In Windows 98/Me, drivers must complete power IRPs at IRQL = PASSIVE\_LEVEL. + +### Do Not Change the Function Codes in a Power IRP + +In addition to the usual rules that govern the processing of IRPs, [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) IRPs have the following special requirement: A driver that receives a power IRP must not change the major and minor function codes in any I/O stack locations in the IRP that have been set by the power manager or by higher-level drivers. The power manager relies on these function codes remaining unchanged until the IRP is completed. Violations of this rule can cause problems that are difficult to debug. For example, the operating system might stop responding, or "hang." + +### Do Not Block While Handling a Power IRP + +Drivers must not cause long delays while handling power IRPs. + +When passing down a power IRP, a driver should return from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine as soon as possible after calling **IoCallDriver** (in Windows 7 and Windows Vista) or **PoCallDriver** (in Windows Server 2003, Windows XP, and Windows 2000). A driver must not wait for a kernel event or otherwise delay before returning. If a driver cannot handle a power IRP in a brief time, it should return STATUS\_PENDING and queue all incoming IRPs until the power IRP completes. (Note that this behavior is different from that of PnP IRPs and [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routines, which are allowed to block.) + +If the driver must wait for a power action by another driver further down the device stack, it should return STATUS\_PENDING from its *DispatchPower* routine and set an *IoCompletion* routine for the power IRP. The driver can perform whatever tasks it requires in the *IoCompletion* routine, and then call **PoStartNextPowerIrp** (Windows Server 2003, Windows XP, and Windows 2000 only) and [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +For example, the power policy owner for a device typically sends a device power IRP while holding a system power IRP in order to set the device power state appropriate for the requested system power state. + +In this situation, the power policy owner should set an *IoCompletion* routine in the system power IRP, pass the system power IRP to the next-lower driver, and return STATUS\_PENDING from its *DispatchPower* routine. + +In the *IoCompletion* routine, it calls **PoRequestPowerIrp** to send the device power IRP, passing a pointer to a callback routine in the request. The *IoCompletion* routine should return STATUS\_MORE\_PROCESSING\_REQUIRED. + +Finally, the driver passes down the system IRP from the callback routine. The driver must not wait for a kernel event in its *DispatchPower* routine and signal with the *IoCompletion* routine for the IRP it is currently handling; a system deadlock might occur. For more information, see [Handling a System Set-Power IRP in a Device Power Policy Owner](handling-a-system-set-power-irp-in-a-device-power-policy-owner.md). + +In a similar situation, when the system is going to sleep, a power policy owner might need to complete some pending I/O before it sends the device IRP to power down its device. Instead of signaling an event when the I/O completes and waiting in its *DispatchPower* routine, the driver should queue a work item and return STATUS\_PENDING from the *DispatchPower* routine. In the worker thread, it waits for I/O to complete and then sends the device power IRP. For more information, see [**IoAllocateWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff548276). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Passing%20Power%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/passive-and-active-cooling-modes.md b/windows-driver-docs-pr/kernel/passive-and-active-cooling-modes.md new file mode 100644 index 0000000000..d78fbd9a2a --- /dev/null +++ b/windows-driver-docs-pr/kernel/passive-and-active-cooling-modes.md @@ -0,0 +1,35 @@ +--- +title: Passive and Active Cooling Modes +author: windows-driver-content +description: Starting with Windows 8, devices that have thermal management capabilities can expose these capabilities to the operating system through the GUID_THERMAL_COOLING_INTERFACE driver interface. +ms.assetid: 4AB70ED3-E71A-45EE-818D-7DCDE0FFBCB3 +--- + +# Passive and Active Cooling Modes + + +Starting with Windows 8, devices that have thermal management capabilities can expose these capabilities to the operating system through the [GUID\_THERMAL\_COOLING\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh698265) driver interface. The two principal driver-implemented callback routines in this interface are [*PassiveCooling*](https://msdn.microsoft.com/library/windows/hardware/hh698270) and [*ActiveCooling*](https://msdn.microsoft.com/library/windows/hardware/hh698235). A driver that has passive-cooling capabilities implements the *PassiveCooling* routine. A driver that has active-cooling capabilities implements the *ActiveCooling* routine. In response to changes in computer usage or environmental conditions, the operating system calls one (or possibly both) of these routines to manage thermal levels dynamically in the hardware platform. + +The Advanced Configuration and Power Interface (ACPI) enables the vendor for a hardware platform to partition the platform into regions called thermal zones. Sensor devices track the temperature in each thermal zone. When a thermal zone starts to overheat, the operating system can take actions to cool down the devices in the zone. These actions can be categorized as either passive cooling or active cooling. + +To perform passive cooling, the operating system throttles one or more devices in the thermal zone to reduce the heat generated by these devices. Throttling might involve reducing the frequency of the clock that drives a device, lowering the voltage supplied to the device, or turning off a part of the device. As a rule, throttling limits device performance. + +To perform active cooling, the operating system turns on a cooling device, such as a fan. Passive cooling decreases the power consumed by the devices in a thermal zone; active cooling increases power consumption. + +In the design of a hardware platform, the decision to use passive cooling or active cooling is based on the physical characteristics of the hardware platform, the power source for the platform, and how the platform will be used. + +Active cooling might be more straightforward to implement, but has several potential drawbacks. The addition of active cooling devices (for example, fans) might increase the cost and size of the hardware platform. The power required to run an active cooling device might reduce the time that a battery-powered platform can operate on a battery charge. Fan noise might be undesirable in some applications, and fans require ventilation. + +Passive cooling is the only cooling mode available to many mobile devices. In particular, handheld computing platforms are likely to have closed cases and run on batteries. These platforms typically contain devices that can throttle performance to reduce heat generation. These devices include processors, graphics processing units (GPUs), battery chargers, and display backlights. + +Handheld computing platforms typically use System on a Chip (SoC) chips that contain processors and GPUs, and the SoC hardware vendors supply the thermal management software for these devices. However, peripheral devices, such as battery chargers and display backlights, are external to SoC chips. The vendors for these devices must supply device drivers, and these drivers must provide any thermal management support that might be required for the devices. A relatively simple way for a device driver to support thermal management is to implement the GUID\_THERMAL\_COOLING\_INTERFACE driver interface. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Passive%20and%20Active%20Cooling%20Modes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/performing-device-specific-idle-detection.md b/windows-driver-docs-pr/kernel/performing-device-specific-idle-detection.md new file mode 100644 index 0000000000..9455f4be78 --- /dev/null +++ b/windows-driver-docs-pr/kernel/performing-device-specific-idle-detection.md @@ -0,0 +1,32 @@ +--- +title: Performing Device-Specific Idle Detection +author: windows-driver-content +description: Performing Device-Specific Idle Detection +ms.assetid: 1a4e3b66-f1dc-4dc8-af8b-ed8138270c3c +keywords: ["idle detection WDK power management", "device-specific idle detection WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Performing Device-Specific Idle Detection + + +## + + +Instead of using the power manager's idle detection routines, a driver can perform its own idle detection based on device-specific criteria. + +Such a driver should put its idle device in the lowest possible sleep state that is valid for the current system power state. To do so, the driver requests a power IRP ([**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734)) with minor IRP code [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744), specifying the device power state to which the device should transition. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Performing%20Device-Specific%20Idle%20Detection%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/performing-dma-in-64-bit-windows.md b/windows-driver-docs-pr/kernel/performing-dma-in-64-bit-windows.md new file mode 100644 index 0000000000..2a0b18a300 --- /dev/null +++ b/windows-driver-docs-pr/kernel/performing-dma-in-64-bit-windows.md @@ -0,0 +1,46 @@ +--- +title: Performing DMA in 64-Bit Windows +author: windows-driver-content +description: Performing DMA in 64-Bit Windows +ms.assetid: 3ef00c05-356d-488a-8422-503d8132344d +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows", "DMA transfers WDK kernel , 64-bit Windows", "double-buffering WDK 64-bit", "Direct Memory Access WDK kernel", "polymorphism WDK 64-bit", "data structures WDK 64-bit", "unsigned operations WDK 64-bit", "signed operations WDK 64-bit", "pointer arithmetic WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Performing DMA in 64-Bit Windows + + +## + + +Adding 64-bit addressing support to your driver can significantly improve overall system performance. This is particularly important for device drivers that perform direct memory access (DMA). In 64-bit Microsoft Windows, device drivers that perform DMA but do not support 64-bit addressing are double-buffered, which results in lower relative performance. + +Although double-buffering usually has a relatively small impact (single percentage points) on 8 GB systems, this is enough to impact I/O-intensive tasks, such as database activity. As the amount of physical memory increases, this negative performance impact increases as well. + +To support 64-bit DMA, drivers should observe the following guidelines: + +1. Use **PHYSICAL\_ADDRESS** structures for physical address calculations. + +2. Treat the entire 64-bit address as a valid physical address. For example, drivers should not call [**MmGetPhysicalAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554547) on a locked buffer, discard the high 32 bits, and pass the truncated address to a 32-bit component adapter. This results in corrupted memory, lost I/O, and system failure. + +3. Use the high-performance scatter/gather routines ([**GetScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff546531) and [**PutScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff559967)) that were added in Windows 2000. + +4. Check the value of the [**Mm64BitPhysicalAddress**](mm64bitphysicaladdress.md) global system variable. If it is **TRUE**, the system supports 64-bit physical addressing. + +5. Set the **Dma64BitAddresses** member of the [**DEVICE\_DESCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/ff543107) structure to **TRUE** to indicate that your driver supports 64-bit DMA addresses. + +The DMA routines in 32-bit Windows are 64-bit-ready. If your device driver uses these routines correctly, your DMA code should work without modification on 64-bit Windows. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Performing%20DMA%20in%2064-Bit%20Windows%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/pio-techniques.md b/windows-driver-docs-pr/kernel/pio-techniques.md new file mode 100644 index 0000000000..56878a03d6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/pio-techniques.md @@ -0,0 +1,23 @@ +--- +title: PIO Techniques +author: windows-driver-content +description: PIO Techniques +ms.assetid: bd673e43-c864-416b-b0d0-23c4ba1b870c +--- + +# PIO Techniques + + +On some computer hardware architectures, the transfer of data from the CPU (central processing unit) to devices is done by Programmed Input/Output (PIO). Using PIO requires that the CPU wait for the data to be transferred, which can become very inefficient. This technology has been replaced in most instances by Direct Memory Access (DMA) because DMA can assign the transfer of the data to a hardware controller, letting the CPU perform other tasks. + +For information on using caches with PIO, see [Flushing Cached Data during PIO Operations](flushing-cached-data-during-pio-operations.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PIO%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/platform-extension-plug-ins--peps-.md b/windows-driver-docs-pr/kernel/platform-extension-plug-ins--peps-.md new file mode 100644 index 0000000000..4481a4792c --- /dev/null +++ b/windows-driver-docs-pr/kernel/platform-extension-plug-ins--peps-.md @@ -0,0 +1,49 @@ +--- +title: Platform Extension Plug-ins (PEPs) +author: windows-driver-content +description: Starting with Windows 10, the run-time power management framework (PoFx) supports platform extension plug-ins (PEPs) for enhanced device component management. +ms.assetid: F7C23715-FFA7-43D3-A420-892236A8AF8F +--- + +# Platform Extension Plug-ins (PEPs) + + +Starting with Windows 10, the run-time power management framework (PoFx) supports platform extension plug-ins (PEPs) for enhanced device component management. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + +
TopicDescription

[Using PEPs for ACPI services](using-peps-for-acpi-services.md)

This topic provides information about using platform extension plug-ins (PEPs) for ACPI services.

[Platform Performance Thresholds](platform-performance-thresholds.md)

There are two types of performance thresholds – static thresholds which remain fixed for the platform and dynamic thresholds that change at runtime. This topic describes the static performance thresholds of the platform and the allowed range for the dynamic threshold.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Platform%20Extension%20Plug-ins%20%28PEPs%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/platform-performance-thresholds.md b/windows-driver-docs-pr/kernel/platform-performance-thresholds.md new file mode 100644 index 0000000000..bcc21d9245 --- /dev/null +++ b/windows-driver-docs-pr/kernel/platform-performance-thresholds.md @@ -0,0 +1,46 @@ +--- +title: Platform Performance Thresholds +author: windows-driver-content +description: There are two types of performance thresholds - static thresholds which remain fixed for the platform and dynamic thresholds that change at runtime. +ms.assetid: 4FB3AFEF-1560-4683-9D57-3029DAA50FE8 +--- + +# Platform Performance Thresholds + + +There are two types of performance thresholds: static thresholds which remain fixed for the platform and dynamic thresholds that change at runtime. This topic describes the static performance thresholds of the platform and the allowed range for the dynamic threshold. + +The static performance thresholds have the following definitions: + +*Highest performance* +The absolute maximum performance an individual processor may reach, assuming ideal conditions. This performance level may not be sustainable for long durations, and may only be achievable if other platform components are in a specific state (for example, it may require other processors be in an idle state). + +*Nominal performance* +The maximum sustained performance level of the processor, assuming ideal environmental conditions (i.e. optimal ambient temperature, the processor is not already hot due to prior activity, available current is not restricted due to a low/cold battery). All processors are expected to be able to sustain continuous activity at their nominal performance simultaneously for at least one second. + +*Lowest Nonlinear Performance* +The lowest performance level at which nonlinear power saving is achieved as performance is scaled. For example, due to the combined effects of voltage and frequency scaling better than liner power saving can be achieved by running at a lower performance state. Above this threshold, lower performance levels should be more energy efficient than higher performance levels. + +*Lowest Performance* +The absolute lowest performance level of the platform. Selecting a performance level lower than the lowest nonlinear performance level may be equivalent from an efficiency perspective or may actually cause an efficiency penalty, but should reduce the instantaneous power consumption of the processor. + +**Note**  All static performance levels do not need to be distinct. A platform's nominal performance level may also be its highest performance level, for example. + +  + +The platform may optionally also express a dynamic performance threshold, the *Guaranteed Performance* threshold. If present, this represents the maximum sustained performance level of a processor, taking into account all known external constraints (power budgeting, thermal constraints, power source, etc.). All processors are expected to be able to sustain their guaranteed performance levels simultaneously for at least one second. The guaranteed performance level is required to fall in the range \[Lowest Performance, Nominal performance\], inclusive. + +## Heterogeneous Performance Thresholds + + +The PEP must use the same performance scale for all processors in the system. On platforms with heterogeneous processors, the performance characteristics of all processors may not be identical. In this case, the PEP must synthesize a performance scale that adjusts for differences in processors, such that any two processors running the same workload at the same performance level will complete in approximately the same time. The PEP should expose different capabilities for different classes of processors, so as to accurately reflect the performance characteristics of each processor. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Platform%20Performance%20Thresholds%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/plug-and-play-minor-irps.md b/windows-driver-docs-pr/kernel/plug-and-play-minor-irps.md new file mode 100644 index 0000000000..357237d17f --- /dev/null +++ b/windows-driver-docs-pr/kernel/plug-and-play-minor-irps.md @@ -0,0 +1,85 @@ +--- +title: Plug and Play Minor IRPs +author: windows-driver-content +description: Plug and Play Minor IRPs +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: eeb7dafd-fb44-4fb7-b5f0-314059ee0093 +--- + +# Plug and Play Minor IRPs + + +## + + +This section describes the PnP IRPs that are sent to drivers. All PnP IRPs have the major function code [**IRP\_MJ\_PNP**](irp-mj-pnp.md) and a minor function code indicating the particular PnP request. + +This section provides reference information for the individual IRPs. See [Plug and Play](https://msdn.microsoft.com/library/windows/hardware/ff547125) for a description of the order in which the IRPs are sent, a discussion of how to handle IRPs in [DispatchPnP routines](https://msdn.microsoft.com/library/windows/hardware/ff543348), and a general discussion of PnP concepts and terminology. + +For each IRP and each kind of driver, a driver is either required to handle the IRP, can optionally handle the IRP, or must not handle the IRP. Consult the table below to identify which IRPs your driver will handle and then consult the reference pages for information about the individual IRPs. The IRPs are listed in functional order in the table and in alphabetical order in the IRP reference pages. + +If an IRP is marked "No" in the table for a particular driver, that driver must not handle the IRP. The driver must pass the IRP to the next driver in the device stack as described in the reference page for the IRP. + +The PnP manager sends these IRPs. PnP drivers can send some of these IRPs, but only those so noted in this section. + +The following are the minor function codes for PnP IRPs, and the driver types that handle them: + +PnP IRP minor function code | Function or filter driver for nonbus device | Function driver for bus device (for bus FDO) | Bus driver or bus filter driver (for child PDOs) +--------------------------- | ------------------------------------------- | -------------------------------------------- | ------------------------------------------------ +[**IRP\_MN\_START\_DEVICE**](irp-mn-start-device.md) | Required | Required | Required +[**IRP\_MN\_QUERY\_STOP\_DEVICE**](irp-mn-query-stop-device.md) | Required | Required | Required +[**IRP\_MN\_STOP\_DEVICE**](irp-mn-stop-device.md) | Required | Required | Required +[**IRP\_MN\_CANCEL\_STOP\_DEVICE**](irp-mn-cancel-stop-device.md) | Required | Required | Required +[**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](irp-mn-query-remove-device.md) | Required | Required | Required +[**IRP\_MN\_REMOVE\_DEVICE**](irp-mn-remove-device.md) | Required | Required | Required +[**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](irp-mn-cancel-remove-device.md) | Required | Required | Required +[**IRP\_MN\_SURPRISE\_REMOVAL**](irp-mn-surprise-removal.md) | Required | Required | Required +[**IRP\_MN\_QUERY\_CAPABILITIES**](irp-mn-query-capabilities.md) | Optional | Optional Required +[**IRP\_MN\_QUERY\_PNP\_DEVICE\_STATE**](irp-mn-query-pnp-device-state.md) | Optional | Optional | Optional +[**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](irp-mn-filter-resource-requirements.md) | Optional (1) | Optional (1) | No +[**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](irp-mn-device-usage-notification.md) | Required (1) | Required (1) | Required (1) +[**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](irp-mn-query-device-relations.md) | +- **BusRelations** | Optional (1) | Required | No (2) +- **EjectionRelations** | No | No | Optional +- **RemovalRelations** | Optional | Optional | No +- **TargetDeviceRelation** | No | No | Required +[**IRP\_MN\_QUERY\_RESOURCES**](irp-mn-query-resources.md) | No | No | Required (1) +[**IRP\_MN\_QUERY\_RESOURCE\_REQUIREMENTS**](irp-mn-query-resource-requirements.md) | No | No | Required (1) +[**IRP\_MN\_QUERY\_ID**](irp-mn-query-id.md) | +- **BusQueryDeviceID** | No | No | Required +- **BusQueryHardwareIDs** | No | No | Optional +- **BusQueryCompatibleIDs** | No | NoOptional +- **BusQueryInstanceID** | No | No | Optional +- **BusQueryContainerID** | No | No | Required (3) +[**IRP\_MN\_QUERY\_DEVICE\_TEXT**](irp-mn-query-device-text.md) | No | No | Required (1) +[**IRP\_MN\_QUERY\_BUS\_INFORMATION**](irp-mn-query-bus-information.md) | No | No | Required (1) +[**IRP\_MN\_QUERY\_INTERFACE**](irp-mn-query-interface.md) | Optional | Optional | Required (1) +[**IRP\_MN\_READ\_CONFIG**](irp-mn-read-config.md) | No | No | Required (1) +[**IRP\_MN\_WRITE\_CONFIG**](irp-mn-write-config.md) | No | No | Required (1) +[**IRP\_MN\_DEVICE\_ENUMERATED**](irp-mn-device-enumerated.md) | No | No | Required (1) +[**IRP\_MN\_SET\_LOCK**](irp-mn-set-lock.md) | No | No | Required (1) + + + + +(1) Required or optional in certain situations. See the reference page for the IRP for more details. + +(2) Bus filter drivers might handle a query for **BusRelations**. + +(3) Supported in Windows 7 and later versions of Windows. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Plug%20and%20Play%20Minor%20IRPs%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/plug-and-play-registry-routines.md b/windows-driver-docs-pr/kernel/plug-and-play-registry-routines.md new file mode 100644 index 0000000000..e8a8a3279d --- /dev/null +++ b/windows-driver-docs-pr/kernel/plug-and-play-registry-routines.md @@ -0,0 +1,73 @@ +--- +title: Plug and Play Registry Routines +author: windows-driver-content +description: Plug and Play Registry Routines +ms.assetid: d526af4e-8b33-46fb-9af9-b0d9b9f1913a +keywords: ["registry WDK kernel , Plug and Play", "driver registry information WDK kernel , Plug and Play", "Plug and Play WDK kernel , registry routines", "hardware keys WDK kernel", "software keys WDK kernel", "IoOpenDeviceRegistryKey", "IoOpenDeviceInterfaceRegistryKey", "PnP WDK kernel , registry routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Plug and Play Registry Routines + + +The Plug and Play manager associates certain registry keys with a driver, its devices, and its device interface instances. Drivers can use these keys to store persistent properties associated with the driver, or with particular devices or device interface instances. + +Drivers must never access these keys directly. Future versions of Windows may store the information at a different location in the registry, or outside the registry entirely. Drivers must not directly access any keys in the following trees: + +- HKLM\\SYSTEM\\CurrentControlSet\\Control\\Class + +- HKLM\\SYSTEM\\CurrentControlSet\\Control\\DeviceClasses + +- HKLM\\SYSTEM\\CurrentControlSet\\Enum + +- HKLM\\SYSTEM\\CurrentControlSet\\Hardware Profiles + +Instead, drivers use the [**IoOpenDeviceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549443) and [**IoOpenDeviceInterfaceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549433) routines to access its PnP keys. + +The PnP manager assigns one key for the driver, known as the driver's software key, and a key for each device, known as the device's hardware key. The **IoOpenDeviceRegistryKey** routine can be used to open either key. The value of the *DevInstKeyType* parameter determines which key to open. Specify PLUGPLAY\_REGKEY\_DRIVER to open a software key, or PLUGPLAY\_REGKEY\_DEVICE to a hardware key. The *DeviceObject* parameter specifies the device or driver. (The driver can also access its hardware and software keys relative to the current hardware profile, by ANDing PLUGPLAY\_REGKEY\_CURRENT\_HWPROFILE to *DevInstKeyType*.) + +**IoOpenDeviceInterfaceRegistryKey** opens the key associated with a particular device interface instance. The instance is identified by its name, which is a [**UNICODE\_STRING**](https://msdn.microsoft.com/library/windows/hardware/ff564879) returned by [**IoGetDeviceInterfaces**](https://msdn.microsoft.com/library/windows/hardware/ff549186), [**IoGetDeviceInterfaceAlias**](https://msdn.microsoft.com/library/windows/hardware/ff549180), or [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506). The string is passed as the *SymbolicLinkValue* parameter to **IoOpenDeviceInterfaceRegistryKey**. + +These keys can also be set in an INF file, or by using the **SetupDi*Xxx*** routines. For more information, see [Registry Keys for Drivers](https://msdn.microsoft.com/library/windows/hardware/ff549538). + +Both [**IoOpenDeviceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549443) and [**IoOpenDeviceInterfaceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549433) provide an open key handle, with access rights as specified by the *DesiredAccess* parameter. The driver subsequently uses the **Zw*Xxx*** registry routines, such as [**ZwQueryValueKey**](https://msdn.microsoft.com/library/windows/hardware/ff567069) and [**ZwSetValueKey**](https://msdn.microsoft.com/library/windows/hardware/ff567109), to access and manipulate the key. After the driver is no longer using the handle, the driver closes the handle by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). For more information, see [Using a Handle to a Registry-Key Object](using-a-handle-to-a-registry-key-object.md). + +The following code sample demonstrates using **IoOpenDeviceRegistryKey** and **ZwSetValueKey** to set the data associated with the value named "Value" under the device's hardware key. + +``` +PDEVICE_OBJECT pDeviceObject; // A pointer to the PDO for the device. +HANDLE handle; +UNICODE_STRING ValueName; +ULONG Value = 109; // This is the value we're setting the key to. +NTSTATUS status; + +RtlInitUnicodeString(&ValueName, L"Value"); + +status = IoOpenDeviceRegistryKey(pDeviceObject, PLUGPLAY_REGKEY_DEVICE, KEY_READ, &handle); + +if (NTSUCCESS(status)) { + status = ZwSetValueKey(handle, ValueName, 0, REG_DWORD, &Value, sizeof(ULONG)); + if (NTSUCCESS(status) { + ZwClose(handle); + } else { + // Handle error. + } + // Handle error. +} +``` + +Note that access to a registry key can be restricted, so a call to [**IoOpenDeviceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549443) and [**IoOpenDeviceInterfaceRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff549433) should specify the minimum rights necessary for *DesiredAccess*. If the driver requests an access right that is not allowed, either routine returns STATUS\_ACCESS\_DENIED. In particular, drivers should not specify KEY\_ALL\_ACCESS. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Plug%20and%20Play%20Registry%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/pnp-components.md b/windows-driver-docs-pr/kernel/pnp-components.md new file mode 100644 index 0000000000..5c16cb0a88 --- /dev/null +++ b/windows-driver-docs-pr/kernel/pnp-components.md @@ -0,0 +1,40 @@ +--- +title: PnP Components +author: windows-driver-content +description: PnP Components +ms.assetid: 33612da4-1ddb-40cf-a8a2-838f85b52cd6 +keywords: ["PnP WDK kernel , components", "Plug and Play WDK kernel , components", "software components WDK PnP", "PnP drivers WDK kernel", "user-mode PnP manager WDK", "kernel-mode PnP manager WDK", "PnP managers WDK", "PnP components WDK user-mode"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PnP Components + + +## + + +The following figure shows the components that work together to support PnP. + +![diagram illustrating plug and play software components](images/pnpcomp.png) + +The PnP manager has two parts: the kernel-mode PnP manager and the user-mode PnP manager. The kernel-mode PnP manager interacts with operating system components and drivers to configure, manage, and maintain devices. The user-mode PnP manager interacts with user-mode setup components, such as Class Installers, to configure and install devices. The user-mode PnP manager also interacts with applications to, for example, register an application for notification of device changes and notify the application when a device event occurs. + +PnP drivers support the physical, logical, and virtual devices on a machine. The term "PnP driver" refers to any Windows driver that supports the interfaces described in this section. While most PnP drivers are also WDM drivers and thus source-compatible across Windows platforms, a few drivers support PnP without fully implementing WDM. + +All drivers should support PnP and power management. If a single driver does not support PnP and power management, it constrains the PnP and power management support of the system as a whole. + +See [Device Installation Overview](https://msdn.microsoft.com/library/windows/hardware/ff549455) for information about device and driver setup, including (INF) files, CAT files, and the registry. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PnP%20Components%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/pnp-driver-design-guidelines.md b/windows-driver-docs-pr/kernel/pnp-driver-design-guidelines.md new file mode 100644 index 0000000000..a7a8b4840c --- /dev/null +++ b/windows-driver-docs-pr/kernel/pnp-driver-design-guidelines.md @@ -0,0 +1,56 @@ +--- +title: PnP Driver Design Guidelines +author: windows-driver-content +description: PnP Driver Design Guidelines +ms.assetid: 4e4a6a8e-3c7f-4561-bbe1-a8c06fe22d0a +keywords: ["PnP WDK kernel , design guidelines", "Plug and Play WDK kernel , design guidelines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PnP Driver Design Guidelines + + +## + + +Plug and Play provides: + +- Automatic and dynamic recognition of installed hardware + +- Hardware resource allocation (and reallocation) + +- Loading of appropriate drivers + +- An interface for drivers to interact with the PnP system + +- Mechanisms for drivers and applications to learn of changes in the hardware environment + +To support PnP, a driver must follow these guidelines: + +- It must contain a [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + + This dispatch routine must handle [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) requests and associated minor function codes. For more information, see [DispatchPnP Routines](dispatchpnp-routines.md). + +- It must not search for hardware. + + The PnP manager is responsible for determining the presence of hardware devices. When the PnP manager detects a device, it notifies the driver by calling its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. Hardware can be detected when the system is booted, or any time that a user adds a device to, or removes one from, a running system. + +- It must not allocate hardware resources. + + A PnP driver must provide the PnP manager with lists of resources that a device can potentially use. The PnP manager is responsible for assigning resources to each device, and notifying the driver of each device's assignments when it sends an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. The driver must thus be capable of working with various configurations of hardware resources. + +Some drivers are insulated from the details of the PnP and power management by system-supplied port or class drivers. For example, a SCSI port driver insulates a SCSI miniport driver from many of the details of the power and PnP systems, so a SCSI miniport driver does not need to handle power and PnP IRPs directly. For such drivers, see the driver-specific documentation for details of the required PnP support. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PnP%20Driver%20Design%20Guidelines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/pnp-driver-s-unload-routine.md b/windows-driver-docs-pr/kernel/pnp-driver-s-unload-routine.md new file mode 100644 index 0000000000..0ae82f87f7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/pnp-driver-s-unload-routine.md @@ -0,0 +1,38 @@ +--- +title: PnP Driver's Unload Routine +author: windows-driver-content +description: PnP Driver's Unload Routine +ms.assetid: 71b30a84-d3c7-4674-94a6-b99f83567183 +keywords: ["Unload routines WDK kernel , PnP drivers", "PnP Unload routine WDK kernel", "Plug and Play Unload routine WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PnP Driver's Unload Routine + + +## + + +A PnP driver must have an [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine that removes any driver-specific resources, such as memory, threads, and events, that are created by the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine. If there are no driver-specific resources to remove, the driver must still have an *Unload* routine but it can simply return. + +A driver's *Unload* routine can be called at any time after all the driver's devices have been removed. The PnP manager calls a driver's *Unload* routine in the context of a system thread at IRQL = PASSIVE\_LEVEL. + +PnP drivers free device-specific resources and device objects in response to PnP device-removal IRPs. The PnP manager sends these IRPs on behalf of each PnP device it enumerates as well as any root-enumerated legacy devices a driver reports using [**IoReportDetectedDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549597). + +Consequently, the *Unload* routines of PnP drivers are usually simple, often consisting only of a **return** statement. However, if the driver allocated any driver-wide resources in its **DriverEntry** routine, it must deallocate those resources in its *Unload* routine unless it has already done so. In general, the process of unloading a PnP driver is a synchronous operation. + +The I/O manager frees the driver object and any driver object extension that the driver allocated using [**IoAllocateDriverObjectExtension**](https://msdn.microsoft.com/library/windows/hardware/ff548233). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PnP%20Driver's%20Unload%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/pnp-notification-overview.md b/windows-driver-docs-pr/kernel/pnp-notification-overview.md new file mode 100644 index 0000000000..082dde8490 --- /dev/null +++ b/windows-driver-docs-pr/kernel/pnp-notification-overview.md @@ -0,0 +1,99 @@ +--- +title: PnP Notification Overview +author: windows-driver-content +description: PnP Notification Overview +ms.assetid: 134a1ea1-78c2-4bab-b5e9-ae21901772ea +keywords: ["PnP WDK kernel , notifications", "Plug and Play WDK kernel , notifications", "notifications WDK PnP , about notifications", "event notifications WDK PnP", "EventCategoryDeviceInterfaceChange notification", "EventCategoryTargetDeviceChange notification", "EventCategoryHardwareProfileChange notification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PnP Notification Overview + + +## + + +The PnP manager provides a mechanism for drivers and applications to be notified when certain events occur on a specific device or on the system in general. A driver can register for notification of the following categories of events: + +- **EventCategoryDeviceInterfaceChange** + + When a driver registers for this category of events on a device interface, the PnP manager notifies the driver of the following events: + + GUID\_DEVICE\_INTERFACE\_ARRIVAL + Indicates that a device interface of the specified class has been enabled. For example, a user added a new disk to the machine and the volume manager enabled a new volume (a device interface of the class "volume"). + + GUID\_DEVICE\_INTERFACE\_REMOVAL + Indicates that a device interface of the specified class has been disabled. + + See [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) and related routines for more information about device interfaces. + +- **EventCategoryTargetDeviceChange** + + When a driver registers for this category of events on a device, the PnP manager notifies the driver when the following events occur on the device: + + GUID\_TARGET\_DEVICE\_QUERY\_REMOVE + Indicates that the PnP manager is about to remove the drivers for the device. Several actions can cause this event, including: a user has requested to remove the specified device from the machine or a user has issued an update-driver request for the device. This notification requests the drivers for the device to either approve or veto the impending remove operation. + + GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE + Indicates that the specified device has been removed from the machine or that a user is changing the driver(s) for the device. + + GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED + Indicates that an impending remove operation on the specified device has been canceled. + + GUID\_*XXX* (custom events) + Indicates that a custom event has occurred on the specified device. + + A driver writer can define a custom event for a device. When the driver (or another related component) notifies the PnP manager that the custom event has occurred, the PnP manager notifies any components that registered for target device change notifications on the device. + + Unlike registering for device interface changes, which can be considered a "passive" interest in the interface, registering for target device changes indicates an "active" interest in a device. + +- **EventCategoryHardwareProfileChange** + + This category includes the following events: + + GUID\_HWPROFILE\_QUERY\_CHANGE + Indicates that a user has requested to change the hardware profile of the machine. The PnP manager uses this notification to ask registered components whether it can change the hardware profile without disrupting system operation. Registered components typically succeed these query requests. + + GUID\_HWPROFILE\_CHANGE\_COMPLETE + Indicates that the hardware profile of the machine has changed. If a driver maintains profile-specific settings, such a driver should refresh those settings after a hardware profile change. + + GUID\_HWPROFILE\_CHANGE\_CANCELLED + Indicates that an impending hardware profile change has been canceled. + +PnP notification works as follows for kernel-mode components: + +1. A driver registers for notification on a category of events by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). + + A PnP notification callback routine remains registered until the driver explicitly removes the registration. + +2. The PnP manager calls the driver's callback routine when an event in the registered category occurs. + +3. The driver removes the callback registration by calling [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398). + +Drivers must not generate a synchronous event or wait for an asynchronous event to occur during the processing of a close. + +For further information about PnP notification, see the following sections: + +[Guidelines for Writing PnP Notification Callback Routines](guidelines-for-writing-pnp-notification-callback-routines.md) + +[Using PnP Device Interface Change Notification](using-pnp-device-interface-change-notification.md) + +[Using PnP Target Device Change Notification](using-pnp-target-device-change-notification.md) + +[Using PnP Hardware Profile Change Notification](using-pnp-hardware-profile-change-notification.md) + +[Using PnP Custom Notification](using-pnp-custom-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PnP%20Notification%20Overview%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/points-to-consider-about-device-objects.md b/windows-driver-docs-pr/kernel/points-to-consider-about-device-objects.md new file mode 100644 index 0000000000..2a0985973d --- /dev/null +++ b/windows-driver-docs-pr/kernel/points-to-consider-about-device-objects.md @@ -0,0 +1,44 @@ +--- +title: Points to Consider About Device Objects +author: windows-driver-content +description: Points to Consider About Device Objects +ms.assetid: 4c54340b-3b4c-4c67-b28d-fac769e4feb7 +keywords: ["device objects WDK kernel , design considerations"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Points to Consider About Device Objects + + +## + + +Keep the following points in mind when designing a kernel-mode driver: + +- Except for certain file system drivers, all I/O operations are always sent to the top device object of a device stack. + +- Device stacks are identified using the name of the named device object in the stack, or by using an alias for that name, such as a symbolic link or a device interface. For WDM function drivers, the named device object is created by the bus driver for the device. Non-WDM drivers must create their own named device objects. + +- A lowest-level driver, such as a PnP hardware bus driver, creates a physical device object (PDO) for each device it controls. An intermediate driver, such as a PnP function driver, creates a functional device object (FDO). + + A WDM driver creates device objects in its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, which is called by the PnP manager after device enumeration. + +- For most lowest-level and intermediate drivers, the device extension of each device object is each driver's primary (and frequently only) global data storage area. Many drivers maintain device state and all other device-specific data and resources a driver requires in the driver-defined device extension of each driver-created device object. + + (Additionally, the driver-specific [I/O stack location](i-o-stack-locations.md) associated with an IRP can be considered an operation-specific local storage area for some kinds of data.) + +For more information about the device objects a specific driver must create, see the device-type-specific documentation in the Windows Driver Kit (WDK). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Points%20to%20Consider%20About%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/points-to-consider-about-user-i-o-requests.md b/windows-driver-docs-pr/kernel/points-to-consider-about-user-i-o-requests.md new file mode 100644 index 0000000000..3821403a0d --- /dev/null +++ b/windows-driver-docs-pr/kernel/points-to-consider-about-user-i-o-requests.md @@ -0,0 +1,48 @@ +--- +title: Points to Consider about User I/O Requests +author: windows-driver-content +description: Points to Consider about User I/O Requests +ms.assetid: e8143055-4ad7-4e39-a2f2-64d9e79d33a0 +keywords: ["device-specific I/O control codes WDK kernel", "private I/O control codes WDK kernel", "layered driver IRP processing WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Points to Consider about User I/O Requests + + +## + + +Keep the following points in mind when designing a kernel-mode driver: + +- Drivers can be layered, and more than one driver can process a single I/O request (IRP). + +- A driver cannot make any assumptions about which other drivers will be in the device stack. Therefore, each driver should be prepared to receive requests from any other driver and should handle all potential error cases. + +- Drivers communicate the success or failure of a requested I/O operation in the I/O status block of the IRP. The I/O manager communicates the success or failure of a requested I/O operation to a user-mode requester. + +- Drivers need not and should not be designed to provide application-specific support. A protected subsystem or its subsystem-specific, user-mode drivers supply this kind of support. There is one exception to this rule: an MS-DOS application that relies on an application-dedicated device can require a kernel-mode driver to control the device and a closely coupled Win32 user-mode virtual device driver (VDD). For more information about VDDs, see the Virtual Device Drivers documentation in the Windows Driver Development Kit (DDK). (The DDK preceded the Windows Driver Kit \[WDK\].) + +- A new driver must handle the same set of **IRP\_MJ\_*XXX*** as any system-supplied driver it replaces. The I/O manager returns STATUS\_INVALID\_DEVICE\_REQUEST for a given I/O request to a target device if its driver does not define an entry point for that **IRP\_MJ\_*XXX***. A device driver also must handle the same I/O control codes for [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests as any system-supplied driver it replaces. In other words, a new device driver must not "break applications" by implementing less functionality than an existing driver for the same type of device. + +- A new intermediate driver inserted into a chain of existing drivers should recognize the same set of **IRP\_MJ\_*XXX*** as the driver it displaces. The new driver can simply pass on IRPs for those requests that it does not process to the next-lower-level driver. However, a new intermediate driver must not "break the chain" for drivers above and below it by neglecting to define an entry point for an **IRP\_MJ\_*XXX*** request that the newly displaced, next-lower-level driver does handle. + +- A lowest-level driver can access only its own I/O stack location in any IRP that it is sent. A higher-level driver can access only its own and the next-lower-level driver's I/O stack locations in any IRP that it is sent. + +- Every driver communicates information to higher-level drivers (and ultimately, to user-mode applications via the I/O manager) only in the I/O status blocks of IRPs because the I/O manager zeros the corresponding I/O stack location as each driver in a chain completes an IRP. Any new driver that attempts to implement back-door communication with a particular higher (or lower) driver compromises its portability and its interoperability with other drivers from one Windows platform or version to the next. + +- A pair of drivers can define a set of device-specific (also called *private*) I/O control codes for [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests that the higher of the pair can send down to the lower of the pair. However, such a pair of drivers must follow all of the preceding guidelines if they are to remain portable and interoperable with other drivers from one Windows platform or version to another. If you design a pair of drivers with a private interface, consider the set of I/O control codes to be defined carefully. Make them as generally useful as possible and design your paired drivers to follow the preceding guidelines, so that you (or someone else) can reuse, replace, or displace either or both of your new drivers easily as they migrate from one Windows platform or version to another. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Points%20to%20Consider%20about%20User%20I/O%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/points-to-consider-for-startio-routines.md b/windows-driver-docs-pr/kernel/points-to-consider-for-startio-routines.md new file mode 100644 index 0000000000..f0b9bf5507 --- /dev/null +++ b/windows-driver-docs-pr/kernel/points-to-consider-for-startio-routines.md @@ -0,0 +1,54 @@ +--- +title: Points to Consider for StartIo Routines +author: windows-driver-content +description: Points to Consider for StartIo Routines +ms.assetid: 389240d0-682f-48b3-940f-c107e9f60155 +keywords: ["StartIo routines, about StartIo routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Points to Consider for StartIo Routines + + +## + + +Keep the following points in mind when implementing a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine: + +- A *StartIo* routine must synchronize its access to a physical device and to any shared state information or resources that the driver maintains in the device extension with the driver's other routines that access the same device, memory location, or resources. + + If the *StartIo* routine shares the device or state with the ISR, it must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine to program the device or to access the shared state. For more information, see [Using Critical Sections](using-critical-sections.md). + + If the *StartIo* routine shares state or resources with routines other than the ISR, it must protect the shared state or resources with a driver-initialized executive spin lock for which the driver provides the storage. For more information, see [Spin Locks](spin-locks.md). + +- If a monolithic non-WDM device driver sets up a controller object, its *StartIo* routine can use the controller object to synchronize operations through a shared physical device with attached (similar) devices. + + See [Controller Objects](using-controller-objects.md) for more information. + +- Unless a closely coupled higher-level driver presplits large DMA transfer requests for its underlying device driver, the underlying device driver's *StartIo* routine must split large transfer requests into partial-transfer ranges and the driver must carry out a sequence of partial-transfer device operations. Each partial transfer must be sized to suit the capabilities of the hardware: either the capabilities of the driver's device or, for a subordinate DMA device, the capabilities of the system DMA controller, whichever has stricter constraints. + + See [Adapter Objects and DMA](adapter-objects-and-dma.md) for more information about using system or bus-master DMA. + +- The *StartIo* routine of a driver that uses DMA must synchronize transfers using an [adapter object](adapter-objects-and-dma.md). + +- A *StartIo* routine is run at IRQL = DISPATCH\_LEVEL, which restricts the set of support routines it can call. + + For example, a *StartIo* routine can neither access nor allocate pageable memory, and it cannot wait for a dispatcher object to be set to the signaled state. On the other hand, a *StartIo* routine can acquire and release a driver-allocated executive spin lock with [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921) and [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150), which run faster than [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) and [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145). + + See [Managing Hardware Priorities](managing-hardware-priorities.md) and [Spin Locks](spin-locks.md) for more information. + +- If the driver holds IRPs in a cancelable state, its *StartIo* routine must check whether the input IRP has already been canceled before it begins any processing for that request on its device. For more information, see [Canceling IRPs](canceling-irps.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Points%20to%20Consider%20for%20StartIo%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/points-to-consider-when-adding-drivers.md b/windows-driver-docs-pr/kernel/points-to-consider-when-adding-drivers.md new file mode 100644 index 0000000000..56bf5a0f04 --- /dev/null +++ b/windows-driver-docs-pr/kernel/points-to-consider-when-adding-drivers.md @@ -0,0 +1,36 @@ +--- +title: Points to Consider When Adding Drivers +author: windows-driver-content +description: Points to Consider When Adding Drivers +ms.assetid: bcbaa842-03b6-4311-9b93-1a4af165020b +keywords: ["WDM drivers WDK kernel , configurations", "WDM drivers WDK kernel , layered drivers", "layered drivers WDK kernel", "driver layers WDK WDM", "replacing drivers", "adding kernel-mode drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Points to Consider When Adding Drivers + + +## + + +Keep the following points in mind when designing a kernel-mode driver: + +- The system-supplied SCSI and video port drivers cannot be replaced. + +- A replacement lowest-level driver must implement the same functionality as the driver it replaces. For example, a replacement keyboard or mouse port driver must use the system-defined interface between itself and a system-supplied class driver that it reuses, and vice versa. + +- A new intermediate driver, inserted between any pair of system-supplied drivers, must interoperate with those drivers so that the functionality of the upper and lower drivers is not reduced. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Points%20to%20Consider%20When%20Adding%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/points-to-consider-when-canceling-irps.md b/windows-driver-docs-pr/kernel/points-to-consider-when-canceling-irps.md new file mode 100644 index 0000000000..a6e7a0a569 --- /dev/null +++ b/windows-driver-docs-pr/kernel/points-to-consider-when-canceling-irps.md @@ -0,0 +1,90 @@ +--- +title: Points to Consider When Canceling IRPs +author: windows-driver-content +description: Points to Consider When Canceling IRPs +ms.assetid: 16a47033-7147-43a2-a9f8-a215f7e90ff1 +keywords: ["canceling IRPs, guidelines", "Cancel routines, guidelines", "cancelable IRPs WDK kernel", "current states WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Points to Consider When Canceling IRPs + + +## + + +This section discusses guidelines for implementing a *Cancel* routine and handling cancelable IRPs. For more information about handling cancelable IRPs, see the [Flow of Control for Cancel-Safe IRP Queuing](http://go.microsoft.com/fwlink/p/?linkid=57844) white paper on the Microsoft Windows Hardware Developer Central (WHDC) website. + +### General Guidelines for All Cancel Routines + +The I/O manager holds the cancel spin lock any time it calls a driver's *Cancel* routine. Consequently, every *Cancel* routine must: + +- Call [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550) before it returns control. + +- Not call [**IoAcquireCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff548196) unless it calls **IoReleaseCancelSpinLock** first. + +- Make a reciprocal call to **IoReleaseCancelSpinLock** for each call it makes to **IoAcquireCancelSpinLock**. + +Each time the *Cancel* routine calls **IoReleaseCancelSpinLock**, it must pass the IRQL returned by the most recent call to **IoAcquireCancelSpinLock**. When releasing the spin lock acquired by the I/O manager (and held when the *Cancel* routine was called), the *Cancel* routine must pass **Irp->CancelIrql**. + +A driver must not call outside routines (such as **IoCompleteRequest**) while holding a spin lock because a deadlock can result. + +### Using the Queue Defined by the I/O Manager + +Unless a driver manages its own internal queues of IRPs, its *Cancel* routine is called with an incoming IRP that could be either of the following: + +- The **CurrentIrp** in the input target device object + +- An entry in the device queue associated with the target device object + +Unless a driver manages its own internal queues of IRPs, its *Cancel* routine should call [**KeRemoveEntryDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553163) with the input IRP to test whether it is an entry in the device queue associated with the target device object. The driver's *Cancel* routine *cannot* call **KeRemoveDeviceQueue** or **KeRemoveByKeyDeviceQueue** because it cannot assume that the given IRP is at any particular position in the device queue. + +### Current State of the Input IRP + +If a *Cancel* routine is called with an IRP for which the driver has already started I/O processing and the request will be completed soon, the *Cancel* routine should release the system cancel spin lock and return control. + +If the current state of the input IRP is Pending, a *Cancel* routine must do the following: + +1. Set the input IRP's I/O status block with STATUS\_CANCELLED for **Status** and zero for **Information**. + +2. Release any spin locks it is holding, including the system cancel spin lock. + +3. Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the given IRP. + +### Holding IRPs in a Cancelable State + +Any driver routine that holds an IRP in a cancelable state must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) and must call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to set its entry point for the *Cancel* routine in the IRP. Only then can that driver routine call additional support routines such as **IoStartPacket**, **IoAllocateController**, or an **ExInterlockedInsert..List** routine. + +Any driver routine that subsequently processes cancelable IRPs must check whether an IRP has already been canceled before it begins operations to satisfy the request. The routine must call **IoSetCancelRoutine** to reset its entry point for the *Cancel* routine to **NULL** in the IRP. Only then can that routine begin its I/O processing for the input IRP. + +A routine might have to reset the entry point for a *Cancel* routine in an IRP if it, too, passes IRPs on for further processing by other driver routines and those IRPs might be held in a cancelable state. + +Any higher-level driver that holds an IRP in a cancelable state must reset its *Cancel* entry point to **NULL** before it passes the IRP on to the next-lower driver with **IoCallDriver**. + +### Canceling an IRP + +Any higher-level driver can call [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338) with an IRP that it has allocated and passed on for further processing by lower-level drivers. However, such a driver cannot assume that the given IRP will be completed with STATUS\_CANCELLED by lower drivers. + +### Synchronization + +A driver can (or must, depending on its design) maintain additional state information in its device extension to track the cancelable status of IRPs. If this state is shared by driver routines running at IRQL <= DISPATCH\_LEVEL, the shared data should be protected with a driver-allocated and initialized spin lock. + +The driver should manage its acquisitions and releases of the system cancel spin lock and its own spin locks carefully. It should hold the system cancel spin lock for the shortest possible intervals. Before accessing a cancelable IRP, such a driver should always check the return value of [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to determine whether the *Cancel* routine is already running (or is about to run); if so, it should let the *Cancel* routine complete the IRP. + +If a device driver maintains state information about cancelable IRPs that various driver routines share with its ISR, these other routines must synchronize access to the shared state with the ISR. Only a driver-supplied *SynchCritSection* routine can access state information that is shared with the ISR in a multiprocessor-safe way. + +For more information, see [Synchronization Techniques](synchronization-techniques.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Points%20to%20Consider%20When%20Canceling%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/portable.md b/windows-driver-docs-pr/kernel/portable.md new file mode 100644 index 0000000000..249b5e3ae5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/portable.md @@ -0,0 +1,60 @@ +--- +title: Portable +author: windows-driver-content +description: Portable +ms.assetid: 3ce16503-e375-44c1-82a7-796286c1a253 +keywords: ["portable drivers WDK kernel", "platform-dependent definitions WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Portable + + +## + + +All drivers must be portable across all Windows-supported hardware platforms. To achieve cross-platform portability, driver writers should: + +- Code in C (no assembly language). + +- Interact with Windows by only using the programming interfaces and headers that are supplied in the WDK. + +### Coding Drivers in C + +All kernel-mode drivers should be written in C so that they can be recompiled with a system-compatible C compiler, relinked, and run on different Microsoft Windows platforms without rewriting or replacing any code. Most operating system components are coded entirely in C, with only small pieces of the HAL and kernel components written in assembly language, so that the operating system is readily portable across hardware platforms. You cannot use many C++ language constructs in kernel-mode drivers, so you should carefully evaluate using such constructs. For more information about issues that arise when drivers include C++ features, see the [C++ for Kernel Mode Drivers: Pros and Cons](http://go.microsoft.com/fwlink/p/?linkid=56294) white paper on the Windows Hardware Developer Central (WHDC) website. + +Drivers should not rely on the features of any particular system-compatible C compiler or C support library if those features are not guaranteed to be supported by other system-compatible compilers. In general, driver code should conform to the ANSI C standard and not depend on anything that this standard describes as "implementation-defined." + +To write portable drivers, it is best to avoid: + +- Dependencies on data types that can vary in size or layout from one platform to another. + +- Calling any standard C runtime library function that maintains state. + +- Calling any standard C runtime library function for which the operating system provides an alternative support routine. + +### Using WDK-Supplied Interfaces + +Each Windows NT executive component exports a set of kernel-mode [driver support routines](https://msdn.microsoft.com/library/windows/hardware/ff544200) that drivers and all other kernel-mode components call. If the underlying implementation of a support routine changes over time, its callers remain portable because the interface to the defining component does not change. + +The WDK supplies a set of header files that define system-specific data types and constants that drivers (and all other kernel-mode components) use to help maintain portability from one platform to another. All kernel-mode drivers include one of the master WDK kernel-mode header files, Wdm.h or Ntddk.h. The master header files pull in not only system-supplied headers that define the basic kernel-mode types, but also appropriate selections from any processor-architecture-specific headers when a driver is compiled with the corresponding compiler directive. + +Some drivers, such as [SCSI miniport drivers](https://msdn.microsoft.com/library/windows/hardware/ff565309), [NDIS drivers](https://msdn.microsoft.com/library/windows/hardware/ff556938), and [video miniport drivers](https://msdn.microsoft.com/library/windows/hardware/ff570509), include other system-supplied header files. + +If a driver requires platform-dependent definitions, it is best to isolate those definitions within **\#ifdef** statements, so that each driver can be compiled and linked for the appropriate hardware platform. However, you can almost always avoid implementing any platform-specific, conditionally compiled code in a driver by using the support routines, macros, constants, and types that the WDK master header files provide. + +Kernel-mode drivers can use kernel-mode **Rtl*Xxx*** routines that are documented in the WDK. Kernel-mode drivers cannot call user-mode **Rtl*Xxx*** routines. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Portable%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/porting-issues-checklist.md b/windows-driver-docs-pr/kernel/porting-issues-checklist.md new file mode 100644 index 0000000000..18de56cb70 --- /dev/null +++ b/windows-driver-docs-pr/kernel/porting-issues-checklist.md @@ -0,0 +1,340 @@ +--- +title: Porting Issues Checklist +author: windows-driver-content +description: Porting Issues Checklist +ms.assetid: 6ab26321-85b8-4a5b-8ca5-af6cbf56ccd6 +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Porting Issues Checklist + + +## + + +### General + +- Use the new 64-bit-safe Windows data types. + + The new 64-bit-safe data types, described earlier in this document, are defined in Basetsd.h. This header file is included in Ntdef.h, which is included in Ntddk.h, Wdm.h, and Ntifs.h. + +- Use the platform compiler macros carefully. + + The following assumption is no longer valid: + + ``` + #ifdef _WIN32 // 32-bit Windows code + ... + #else // 16-bit Windows code + ... + #endif + ``` + + However, the 64-bit compiler defines \_WIN32 for backward compatibility. + + Also, the following assumption is no longer valid: + + ``` + #ifdef _WIN16 // 16-bit Windows code + ... + #else // 32-bit Windows code + ... + #endif + ``` + + In this case, the else clause can represent \_WIN32 or \_WIN64. + +- Use the proper format specifiers with **printf** and **wsprintf**. + + Use **%p** to print pointers in hexadecimal. This is the best choice for printing pointers. + + **Note**   A future version of Visual C++ will support **%I** to print polymorphic data. It will treat values as 64 bits in 64-bit Windows and 32 bits in 32-bit Windows. Visual C++ will also support **%I64** to print values that are 64 bits. + +   + + + +- Know your address space. + + Do not blindly assume, for example, that if an address is a kernel address, its high-order bit must be set. To obtain the lowest system address, use the **MM\_LOWEST\_SYSTEM\_ADDRESS** macro. + +### Pointer Arithmetic + +- Be careful when performing unsigned and signed operations. + + Consider the following: + + ``` + ULONG x; + LONG y; + LONG *pVar1; + LONG *pVar2; + + pVar2 = pVar1 + y * (x - 1); + ``` + + The problem arises because *x* is unsigned, which makes the entire expression unsigned. This works fine unless *y* is negative. In this case, *y* is converted to an unsigned value, the expression is evaluated using 32-bit precision, scaled, and added to *pVar1*. On 64-bit Windows, this 32-bit unsigned negative number becomes a large 64-bit positive number, which gives the wrong result. To fix this problem, declare *x* as a signed value or explicitly typecast it to **LONG** in the expression. + +- Be careful when using hexadecimal constants and unsigned values. + + The following assertion is not true on 64-bit systems: + + ``` + ~((UINT64)(PAGE_SIZE-1)) == (UINT64)~(PAGE_SIZE-1) + PAGE_SIZE = 0x1000UL // Unsigned long - 32 bits + PAGE_SIZE - 1 = 0x00000fff + ``` + + LHS expression: + + ``` + // Unsigned expansion(UINT64)(PAGE_SIZE -1 ) = 0x0000000000000fff + ~((UINT64)(PAGE_SIZE -1 )) = 0xfffffffffffff000 + ``` + + RHS expression: + + ``` + ~(PAGE_SIZE-1) = 0xfffff000 + (UINT64)(~(PAGE_SIZE - 1)) = 0x00000000fffff000 + ``` + + Hence: + + ``` + ~((UINT64)(PAGE_SIZE-1)) != (UINT64)(~(PAGE_SIZE-1)) + ``` + +- Be careful with NOT operations. + + Consider the following: + + ``` + UINT_PTR a; ULONG b; + a = a & ~(b - 1); + ``` + + The problem is that ~(b−1) produces 0x0000 0000 *xxxx xxxx* and not 0xFFFF FFFF *xxxx xxxx*. The compiler will not detect this. To fix this, change the code as follows: + + ``` + a = a & ~((UINT_PTR)b - 1); + ``` + +- Be careful when computing buffer sizes. + + Consider the following: + + ``` + len = ptr2 - ptr1 + /* len could be greater than 2**32 */ + ``` + + Cast pointers to **PCHAR** for pointer arithmetic. + + **Note**   If *len* is declared **INT** or **ULONG**, this will generate a compiler warning. Buffer sizes, even when computed correctly, may still exceed the capacity of **ULONG**. + +   + +- Avoid using computed or hard-coded pointer offsets. + + When working with structures, use the [**FIELD\_OFFSET**](https://msdn.microsoft.com/library/windows/hardware/ff545727) macro wherever possible to determine the offset of structure members. + +- Avoid using hard-coded pointer or handle values. + + Do not pass hard-coded pointers or handles such as (HANDLE)0xFFFFFFFF to routines such as **ZwCreateSection**. Instead, use constants, such as INVALID\_HANDLE\_VALUE, that can be defined to have the appropriate value for each platform. + +- Be aware that in 64-bit Windows, 0xFFFFFFFF is not the same as -1. + + For example: + + ``` + DWORD index = 0; + CHAR *p; + + // if (p[index-1] == '0') causes access violation on 64-bit Windows! + ``` + + On 32-bit machines: + + ``` + p[index-1] == p[0xffffffff] == p[-1] + ``` + + On 64-bit machines: + + ``` + p[index-1] == p[0x00000000ffffffff] != p[-1] + ``` + + This problem can be avoided by changing the type of *index* from **DWORD** to **DWORD\_PTR**. + +### Polymorphism + +- Be careful with polymorphic interfaces. + + Do not create functions that accept parameters of type **DWORD** (or other fixed-precision types) for polymorphic data. If the data can be a pointer or an integral value, the parameter type should be **UINT\_PTR** or **PVOID**, not **DWORD**. + + For example, do not create a function that accepts an array of exception parameters typed as **DWORD** values. The array should be an array of **DWORD\_PTR** values. Therefore, the array elements can hold addresses or 32-bit integral values. The general rule is that if the original type is **DWORD** and it needs to be pointer width, convert it to a **DWORD\_PTR** value. That is why there are corresponding pointer-precision types for the native Win32 types. If you have code that uses **DWORD**, **ULONG**, or other 32-bit types in a polymorphic way (that is, you really want the parameter or structure member to hold an address), use **UINT\_PTR** in place of the current type. + +- Be careful when calling functions that have pointer OUT parameters. + + Do not do this: + + ``` + void GetBufferAddress(OUT PULONG *ptr); + { + *ptr=0x1000100010001000; + } + void foo() + { + ULONG bufAddress; + // + // This call causes memory corruption. + // + GetBufferAddress((PULONG *)&bufAddress); + } + ``` + + Typecasting *bufAddress* to (**PULONG** \*) prevents a compiler error. However, *GetBufferAddress* will write a 64-bit value into the memory location at *&bufAddress*. Because *bufAddress* is only a 32-bit value, the 32 bits immediately following *bufAddress* will get overwritten. This is a very subtle, hard-to-find bug. + +- Do not cast pointers to **INT**, **LONG**, **ULONG**, or **DWORD**. + + If you must cast a pointer to test some bits, set or clear bits, or otherwise manipulate its contents, use the **UINT**\_**PTR** or **INT**\_**PTR** type. These types are integral types that scale to the size of a pointer for both 32-bit and 64-bit Windows (for example, **ULONG** for 32-bit Windows and **\_int64** for 64-bit Windows). For example, assume you are porting the following code: + + ``` + ImageBase = (PVOID)((ULONG)ImageBase | 1); + ``` + + As a part of the porting process, you would change the code as follows: + + ``` + ImageBase = (PVOID)((ULONG_PTR)ImageBase | 1); + ``` + + Use **UINT**\_**PTR** and **INT**\_**PTR** where appropriate (and if you are uncertain whether they are required, there is no harm in using them just in case). Do not cast your pointers to the types **ULONG**, **LONG**, **INT**, **UINT**, or **DWORD**. + + **Note**  **HANDLE** is defined as a **void \***, so typecasting a **HANDLE** value to a **ULONG** value to test, set, or clear the low two bits is a programming error. + +   + +- Use **PtrToLong** and **PtrToUlong** to truncate pointers. + + If you must truncate a pointer to a 32-bit value, use the **PtrToLong** or **PtrToUlong** function (defined in *Basetsd.h*). This function disables the pointer truncation warning for the duration of the call. + + Use these functions carefully. After you truncate a pointer variable using one of these functions, never cast the resulting **LONG** or **ULONG** back to a pointer. These functions truncate the upper 32 bits of an address, which are usually needed to access the memory originally referenced by pointer. Using these functions without careful consideration will result in fragile code. + +### Data Structures and Structure Alignment + +- Carefully examine all uses of data structure pointers. + + The following are common trouble areas: + + - Data structures that are stored on disk or exchanged with 32-bit processes. + - Explicit and implicit unions with pointers. + - Security descriptors. + + + +- Use the [**FIELD\_OFFSET**](https://msdn.microsoft.com/library/windows/hardware/ff545727) macro. + + For example: + + ``` + struct xx { + DWORD NumberOfPointers; + PVOID Pointers[1]; + }; + + ``` + + The following allocation is incorrect in 64-bit Windows because the compiler will pad the structure with an additional 4 bytes to make the 8-byte alignment requirement: + + ``` + malloc(sizeof(DWORD)+100*sizeof(PVOID)); + + ``` + + Here is how to do it correctly: + + ``` + malloc(FIELD_OFFSET(struct xx, Pointers) +100*sizeof(PVOID)); + ``` + +- Use the **TYPE\_ALIGNMENT** macro. + + The **TYPE\_ALIGNMENT** macro returns the alignment requirement for a given data type on the current platform. For example: + + ``` + TYPE_ALIGNMENT(KFLOATING_SAVE) == 4 on x86, 8 on Itanium + TYPE_ALIGNMENT(UCHAR) == 1 everywhere + ``` + + As an example, code such as this: + + ``` + ProbeForRead(UserBuffer, UserBufferLength, sizeof(ULONG)); + ``` + + becomes more portable when changed to: + + ``` + ProbeForRead(UserBuffer, UserBufferLength, TYPE_ALIGNMENT(ULONG)); + ``` + +- Watch for data type changes in public kernel structures. + + For example, the **Information** field in the IO\_STATUS\_BLOCK structure is now of type **ULONG\_PTR**. + +- Be cautious when using structure packing directives. + + On 64-bit Windows, if a data structure is misaligned, routines that manipulate the structure, such as [**RtlCopyMemory**](https://msdn.microsoft.com/library/windows/hardware/ff561808) and **memcpy**, will not fault. Instead, they will raise an exception. For example: + + ``` + #pragma pack (1) /* also set by /Zp switch */ + struct Buffer { + ULONG size; + void *ptr; + }; + + void SetPointer(void *p) { + struct Buffer s; + s.ptr = p; /* will cause alignment fault */ + ... + } + ``` + + You could use the **UNALIGNED** macro to fix this: + + ``` + void SetPointer(void *p) { + struct Buffer s; + *(UNALIGNED void *)&s.ptr = p; + } + ``` + + Unfortunately, using the **UNALIGNED** macro is very expensive on Itanium-based processors. A better solution is to put 64-bit values and pointers at the beginning of the structure. + + **Note**  If possible, avoid using different packing levels in the same header file. + +   + +### Additional Information + +- [Supporting 32-Bit I/O in Your 64-Bit Driver](supporting-32-bit-i-o-in-your-64-bit-driver.md) + +- [Getting Ready for 64-bit Windows](https://msdn.microsoft.com/library/windows/desktop/aa384198) (user-mode application porting guide) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Porting%20Issues%20Checklist%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/porting-your-driver-to-64-bit-windows.md b/windows-driver-docs-pr/kernel/porting-your-driver-to-64-bit-windows.md new file mode 100644 index 0000000000..9cb5065da7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/porting-your-driver-to-64-bit-windows.md @@ -0,0 +1,36 @@ +--- +title: Porting Your Driver to 64-Bit Windows +author: windows-driver-content +description: Porting Your Driver to 64-Bit Windows +ms.assetid: f06e6aae-fc44-481c-a277-1c266d6e6d7b +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows", "thunking WDK", "WOW64 thunking layer WDK", "converting parameters to fixed-precision types"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Porting Your Driver to 64-Bit Windows + + +## + + +The 64-bit version of Windows is designed to make it possible for developers to use a single source-code base for their 32-bit and 64-bit Windows applications. To a large extent, this is also true for 32-bit and 64-bit Windows drivers. + +For user-mode applications, 64-bit Windows includes a Windows on Windows (WOW64) *thunking layer* that enables 32-bit applications to execute (with some performance degradation) on 64-bit versions of Windows. It does this by intercepting 32-bit function calls and converting pointer-precision parameter types to fixed-precision types as appropriate before making the transition to the 64-bit kernel. This conversion process is called *thunking*. + +**Note**  This thunking is only done for 32-bit *applications*; 32-bit *drivers* are not supported on 64-bit versions of Windows. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Porting%20Your%20Driver%20to%2064-Bit%20Windows%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/postponing-pnp-irp-processing-until-lower-drivers-finish.md b/windows-driver-docs-pr/kernel/postponing-pnp-irp-processing-until-lower-drivers-finish.md new file mode 100644 index 0000000000..0b0846a076 --- /dev/null +++ b/windows-driver-docs-pr/kernel/postponing-pnp-irp-processing-until-lower-drivers-finish.md @@ -0,0 +1,90 @@ +--- +title: Postponing PnP IRP Processing Until Lower Drivers Finish +author: windows-driver-content +description: Postponing PnP IRP Processing Until Lower Drivers Finish +ms.assetid: 5bd9f3aa-30d5-4c45-afec-3e5ae0264f4a +keywords: ["PnP WDK kernel , postponing IRP processing", "Plug and Play WDK kernel , postponing IRP processing", "IRPs WDK PnP", "I/O request packets WDK PnP", "postponing IRP processing WDK PnP", "delaying IRP processing WDK PnP", "DispatchPnP routine", "IoCompletion routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Postponing PnP IRP Processing Until Lower Drivers Finish + + +## + + +Some PnP and power IRPs must be processed first by the parent bus driver for a device and then by each next-higher driver in the device stack. For example, the parent bus driver must be the first driver to perform its start operations for a device ([**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749)), followed by each next-higher driver. For such an IRP, function and filter drivers must set an I/O completion routine, pass the IRP to the next-lower driver, and postpone any activities to process the IRP until the lower drivers have finished with the IRP. + +An [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine can be called at IRQL DISPATCH\_LEVEL, but a function or filter driver might need to process the IRP at IRQL = PASSIVE\_LEVEL. To return to PASSIVE\_LEVEL from an *IoCompletion* routine, a driver can use a kernel event. The driver registers an *IoCompletion* routine that sets a kernel-mode event and then the driver waits on the event in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. When the event is set, lower drivers have completed the IRP and the driver is allowed to process the IRP. + +Note that a driver must not use this technique to wait for lower drivers to finish a power IRP ([**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784)). Waiting on an event in the [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine that is set in the *IoCompletion* routine can cause a deadlock. See [Passing Power IRPs](passing-power-irps.md) for more information. + +The following two figures show an example of how a driver waits for lower drivers to complete a PnP IRP. The example shows what the function and bus drivers must do, plus how they interact with the PnP manager and the I/O manager. + +![diagram illustrating postponing plug and play irp handling, part 1](images/delay1.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. The PnP manager calls the I/O manager to send an IRP to the top driver in the device stack. + +2. The I/O manager calls the *DispatchPnP* routine of the top driver. In this example, there are only two drivers in the device stack (the function driver and the parent bus driver) and the function driver is the top driver. + +3. The function driver declares and initializes a kernel-mode event, sets up the stack location for the next-lower driver, and sets an *IoCompletion* routine for this IRP. + + The function driver can use [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387) to set up the stack location. + + In the call to [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679), the function driver sets *InvokeOnSuccess*, *InvokeOnError*, and *InvokeOnCancel* to **TRUE** and passes the kernel-mode event as part of the context parameter. + +4. The function driver passes the IRP down the device stack with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) before performing any operations to handle the IRP. + +5. The I/O manager sends the IRP to the next-lower driver in the device stack by calling that driver's *DispatchPnP* routine. + +6. The next-lower driver in this example is the lowest driver in the device stack, the parent bus driver. The bus driver performs its operations to start the device. The bus driver sets **Irp->IoStatus.Status**, sets **Irp->IoStatus.Information** if relevant to this IRP, and completes the IRP by calling [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + If the bus driver calls other driver routines or sends I/O to the device in order to start it, the bus driver does not complete the PnP IRP in its *DispatchPnP* routine. Instead, it must mark the IRP pending with [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) and return STATUS\_PENDING from its *DispatchPnP* routine. The driver later calls **IoCompleteRequest** from another driver routine, possibly a DPC routine. + +The following figure shows the second part of the example, where the higher drivers in the device stack resume their postponed IRP processing. + +![diagram illustrating postponing plug and play irp handling, part 2](images/delay2.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. When the bus driver calls **IoCompleteRequest**, the I/O manager examines the stack locations of the higher drivers and calls any *IoCompletion* routines it finds. In this example, the I/O manager locates and calls the *IoCompletion* routine for the next-higher driver, the function driver. + +2. The function driver's *IoCompletion* routine sets the kernel-mode event supplied in the context parameter and returns STATUS\_MORE\_PROCESSING\_REQUIRED. + + The IoCompletion routine must return STATUS\_MORE\_PROCESSING\_REQUIRED to prevent the I/O manager from calling *IoCompletion* routines set by higher drivers at this time. The *IoCompletion* routine uses this status to forestall completion so its driver's *DispatchPnP* routine can regain control. The I/O manager will resume calling higher drivers' *IoCompletion* routines for this IRP when this driver's *DispatchPnP* routine completes the IRP. + +3. The I/O manager stops completing the IRP and returns control to the routine that called **IoCompleteRequest**, which in this example is the bus driver's *DispatchPnP* routine. + +4. The bus driver returns from its *DispatchPnP* routine with status indicating the result of its IRP processing: either STATUS\_SUCCESS or an error status. + +5. **IoCallDriver** returns control to its caller, which in this example is the function driver's *DispatchPnP* routine. + +6. The function driver's *DispatchPnP* routine resumes processing the IRP. + + If **IoCallDriver** returns STATUS\_PENDING, the *DispatchPnP* routine has resumed execution before its *IoCompletion* routine has been called. The *DispatchPnP* routine, therefore, must wait for the kernel event to be signaled by its *IoCompletion* routine. This ensures that the *DispatchPnP* routine will not continue processing the IRP until all lower drivers have completed it. + + If **Irp->IoStatus.Status** is set to an error, a lower driver has failed the IRP and the function driver must not continue handling the IRP (except for any necessary cleanup). + +7. Once lower drivers have successfully completed the IRP, the function driver processes the IRP. + + For IRPs being handled first by the parent bus driver, the bus driver typically sets a successful status in **Irp->IoStatus.Status** and optionally sets a value in **Irp->IoStatus.Information**. Function and filter drivers leave the values in **IoStatus** as is unless they fail the IRP. + + The function driver's *DispatchPnP* routine calls **IoCompleteRequest** to complete the IRP. The I/O manager resumes I/O completion processing. In this example, there are no filter drivers above the function driver, and thus no more *IoCompletion* routines to call. When **IoCompleteRequest** returns control to the function driver *DispatchPnP* routine, the *DispatchPnP* routine returns status. + +For some IRPs, if a function or filter driver fails the IRP on its way back up the device stack, the PnP manager informs the lower drivers. For example, if a function or filter driver fails an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749), the PnP manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) to the device stack. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Postponing%20PnP%20IRP%20Processing%20Until%20Lower%20Drivers%20Finish%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-irps-for-individual-devices.md b/windows-driver-docs-pr/kernel/power-irps-for-individual-devices.md new file mode 100644 index 0000000000..f623bd8bc4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-irps-for-individual-devices.md @@ -0,0 +1,78 @@ +--- +title: Power IRPs for Individual Devices +author: windows-driver-content +description: Power IRPs for Individual Devices +ms.assetid: a8d5db12-8f6b-4c65-9814-0bc3e476dd1c +keywords: ["power IRPs WDK kernel , devices", "device power IRPs WDK kernel", "power sequence values WDK kernel", "working state returns WDK power management", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power IRPs for Individual Devices + + +## + + +A *device power IRP* specifies major IRP code [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784), one of the minor power IRP codes listed below, and the value **DevicePowerState** in the **Power.Type** member. + +[**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) + +[**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) + +[**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) + +[**IRP\_MN\_POWER\_SEQUENCE**](https://msdn.microsoft.com/library/windows/hardware/ff551644) + +All drivers in a device stack receive such IRPs; normally, only the device power policy manager can send these IRPs. However, the power manager can send a device power IRP when performing idle detection on behalf of a device, as explained in [Using Power Manager Routines for Idle Detection](using-power-manager-routines-for-idle-detection.md). + +A driver sends a device power IRP for any of the following reasons: + +- To query or change the device power state in response to a system power IRP + +- To put the device in a sleep state to conserve power + +- To return the device to the working state after it has been asleep + +- To enable the device to awaken in response to an external signal + +- To get a power sequence value when powering up a device + +The following figure shows the sequence of steps that occur to send, forward, and complete a device power IRP. + +![diagram illustrating the path of a device power irp](images/devpoirp.png) + +As the previous figure shows, a device power IRP is sent, forwarded, and completed in the following steps: + +1. The device power policy owner calls [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to allocate a device power IRP, specifying the PDO that is the target of the IRP and a callback routine to be invoked when the IRP is complete. + +2. The power manager allocates a device power IRP and sends it to the top driver in the device stack for the target PDO. + +3. The driver performs the following actions: + + - Sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine if one is necessary. + + - Calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) (Windows Server 2003, Windows XP, and Windows 2000) if a completion routine is not used. Beginning with Windows Vista, this call is not required and such a call performs no power management operation. + + - Calls [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (Windows 7 and Windows Vista) or calls [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (Windows Server 2003, Windows XP, and Windows 2000) to pass the IRP down to the next-lower driver. + + Each driver in the stack does this until the IRP reaches the bus driver. If a driver must fail the IRP, it should do so immediately and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +4. The bus driver, which maintains the device PDO, performs the requested action, and then calls **IoCompleteRequest** to complete the IRP. A bus driver can fail a device power-up IRP if a device is removed or in the process of being removed. + +5. The I/O manager calls *IoCompletion* routines that were set by drivers as they passed the IRP down the stack. After all the *IoCompletion* routines have been called, the callback routine is run. + +For more information about device power IRPs, see [Managing Power for Individual Devices](managing-power-for-individual-devices.md) and [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md). For details on the power sequence IRP, see [**IRP\_MN\_POWER\_SEQUENCE**](https://msdn.microsoft.com/library/windows/hardware/ff551644). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20IRPs%20for%20Individual%20Devices%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-irps-for-the-system.md b/windows-driver-docs-pr/kernel/power-irps-for-the-system.md new file mode 100644 index 0000000000..ec56c81108 --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-irps-for-the-system.md @@ -0,0 +1,68 @@ +--- +title: Power IRPs for the System +author: windows-driver-content +description: Power IRPs for the System +ms.assetid: a37e8dda-af7a-4f28-bf04-908a74bb5b2f +keywords: ["power IRPs WDK kernel , system", "system power IRPs WDK kernel", "IRP_MJ_POWER", "IRP_MN_SET_POWER", "IRP_MN_QUERY_POWER", "inrush power WDK kernel", "system inrush power WDK kernel", "change power states WDK kernel", "reaffirming power states", "idle time-outs WDK power management", "expired batteries WDK power management", "battery expirations WDK power management", "user-requested power changes WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power IRPs for the System + + +## + + +A *system power IRP* specifies major IRP code [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784), one of the minor power IRP codes listed below, and the value **SystemPowerState** in the **Power.Type** member of the IRP stack. Only the power manager can send such an IRP; a driver cannot send a system power IRP. + +The power manager sends a system power IRP for one of the following reasons: + +- To change the system power state in response to an idle time-out, a change in system activity, a user request, or an expiring battery ([**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744)) + +- To query devices to determine whether the system can go to sleep ([**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699)) + +- To reaffirm the current system power state after a query (**IRP\_MN\_SET\_POWER**) + +The power manager sends **IRP\_MN\_QUERY\_POWER** and **IRP\_MN\_SET\_POWER** requests on behalf of the system. A driver can fail an **IRP\_MN\_QUERY\_POWER** request but cannot fail **IRP\_MN\_SET\_POWER**. + +For example, to change the system power state, the power manager sends a system power IRP to the top driver in the stack at each device node of the device tree. The following figure shows how drivers within a single device stack handle a system power IRP. + +![diagram illustrating the path of a system power irp](images/s2dirp.png) + +As the previous figure shows: + +1. The power manager calls the I/O manager to send a system power IRP to each leaf node in the device tree. + +2. Drivers handle the IRP if possible, set [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines if necessary, and call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (Windows 7 and Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (Windows Server 2003, Windows XP, and Windows 2000) to forward the IRP down the stack. If a driver must fail the IRP, the driver does so immediately and completes the IRP. Drivers can fail **IRP\_MN\_QUERY\_POWER** IRPs, but must not fail **IRP\_MN\_SET\_POWER** IRPs that set the system power state. + +3. When the driver that owns power policy for the device receives the IRP, that driver sets an *IoCompletion* routine for the system IRP and then forwards the IRP. + +4. Any other drivers in the stack handle the IRP if possible, set *IoCompletion* routines if necessary, and forward the IRP to the next-lower driver, as in step 2. + +5. Eventually, the bus driver receives and completes the system IRP. + +6. The I/O manager calls any *IoCompletion* routines that were set as drivers passed the system IRP down the device stack. + +7. In its *IoCompletion* routine, the device power policy owner calls [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send a device power IRP, specifying a device power state that is valid for the system power state in the system IRP. The driver sets a callback routine to be invoked when the device power IRP completes. + + If necessary, the driver consults the **DeviceState** member in its cached copy of the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure (see [Reporting Device Power Capabilities](reporting-device-power-capabilities.md)) to determine which device power states correspond to the system power state in the IRP. + +8. After the device IRP is complete and any device IRP completion routines have run, the power policy owner's callback routine is invoked. In the callback routine, the driver copies its returned status into the system IRP. In Windows Server 2003, Windows XP, and Windows 2000, the callback calls [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP. However, in Windows 7 and Windows Vista, calling **PoStartNextPowerIrp** is not required and such a call performs no power management operation. Finally, the callback calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the system IRP. + +For further information, see [Handling System Power State Requests](handling-system-power-state-requests.md). + +Because some devices require an inrush of current when they power on, system inrush power IRPs are handled synchronously and serially throughout the system. Only one such IRP can be active at a time. For further information, see [Calling IoCallDriver vs. Calling PoCallDriver](calling-iocalldriver-versus-calling-pocalldriver.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20IRPs%20for%20the%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-management-minor-irps.md b/windows-driver-docs-pr/kernel/power-management-minor-irps.md new file mode 100644 index 0000000000..91c52fe1e9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-management-minor-irps.md @@ -0,0 +1,39 @@ +--- +title: Power Management Minor IRPs +author: windows-driver-content +description: Power Management Minor IRPs +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 8af0609f-168b-4455-aae8-1a3c9e40ed47 +--- + +# Power Management Minor IRPs + + +## + + +All power IRPs have the major code [**IRP\_MJ\_POWER**](irp-mj-power.md) and one of the following minor codes, indicating a specific power management request: + +[**IRP\_MN\_POWER\_SEQUENCE**](irp-mn-power-sequence.md) + +[**IRP\_MN\_QUERY\_POWER**](irp-mn-query-power.md) + +[**IRP\_MN\_SET\_POWER**](irp-mn-set-power.md) + +[**IRP\_MN\_WAIT\_WAKE**](irp-mn-wait-wake.md) + +This section provides reference information for the individual IRPs in alphabetical order. For more information about when the IRPs are sent and how drivers should handle them, see [Power Management](https://msdn.microsoft.com/library/windows/hardware/ff547131). The Power Management section also includes a general introduction to power management and terminology. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20Management%20Minor%20IRPs%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-management-responsibilities-for-drivers.md b/windows-driver-docs-pr/kernel/power-management-responsibilities-for-drivers.md new file mode 100644 index 0000000000..28837d0e6f --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-management-responsibilities-for-drivers.md @@ -0,0 +1,48 @@ +--- +title: Power Management Responsibilities for Drivers +author: windows-driver-content +description: Power Management Responsibilities for Drivers +ms.assetid: c42a5b95-76f3-4975-b452-4858bbbe532e +keywords: ["power management WDK kernel , driver responsibilities", "driver power responsibilities WDk kernel", "conserving power WDK kernel", "power management WDK kernel , power states", "power states WDK kernel", "states WDK power management", "system power states WDK kernel , power management", "device power states WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power Management Responsibilities for Drivers + + +## + + +Drivers that support power management are responsible for: + +[Reporting device power capabilities](reporting-device-power-capabilities.md) during PnP enumeration. + +[Setting device object flags for power management](setting-device-object-flags-for-power-management.md). + +[Handling power IRPs](handling-power-irps.md) sent by the power manager or a driver. + +[Powering up a device](powering-up-a-device.md) as soon as needed after system start-up or idle shutdown. + +[Powering down a device](powering-down-a-device.md) at system shutdown time or putting it to sleep when idle. + +[Enabling device wake-up](enabling-device-wake-up.md), if the device supports wake-up capabilities. + +[Managing device performance states](managing-device-performance-states.md), if the device supports decreasing performance or features to reduce power consumption. + +Not every driver in every device stack performs all of these tasks. Typically, the bus driver reports capabilities, sets flags, and manipulates the physical device, and the device power policy manager (usually the function driver) issues requests to put the device to sleep and to enable wake-up. + +With few exceptions, drivers power on and power off their devices, and they enable devices for wake-up in response to power IRPs, that is, IRPs with the major code [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784). Power IRPs can be sent by the power manager and, in some cases, by a driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20Management%20Responsibilities%20for%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-manager.md b/windows-driver-docs-pr/kernel/power-manager.md new file mode 100644 index 0000000000..da97d06e53 --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-manager.md @@ -0,0 +1,46 @@ +--- +title: Power Manager +author: windows-driver-content +description: Power Manager +ms.assetid: f7727368-6edd-427b-9fb3-02f80538807b +keywords: ["power manager WDK kernel", "usage manager WDK power management", "power IRPs WDK kernel , power manager", "system-wide power policy WDK kernel", "power policy WDK kernel", "sleep power management WDK kernel", "hibernation power management WDK kernel", "shutdown power management WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power Manager + + +## + + +The power manager is responsible for managing power usage for the system. It administers the system-wide power policy and tracks the path of power IRPs through the system. + +The power manager requests power operations by sending [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) requests to drivers. A request can specify a new power state or can query whether a change in power state is feasible. + +When sleep, hibernation, or shutdown is required, the power manager requests the appropriate power action by sending an **IRP\_MJ\_POWER** request to each leaf node in the device tree. The power manager considers the following in determining whether the system should sleep, hibernate, or shut down: + +- System activity level + +- System battery level + +- Shutdown, hibernate, or sleep requests from applications + +- User actions, such as pressing the power button + +- Control panel settings + +For more information, see [Windows Kernel-Mode Power Manager](windows-kernel-mode-power-manager.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/power-states.md b/windows-driver-docs-pr/kernel/power-states.md new file mode 100644 index 0000000000..7d28cffe39 --- /dev/null +++ b/windows-driver-docs-pr/kernel/power-states.md @@ -0,0 +1,36 @@ +--- +title: Power States +author: windows-driver-content +description: Power States +ms.assetid: 33043903-9db6-4c51-b33c-921ade237ccf +keywords: ["power management WDK kernel , power states", "power states WDK kernel", "states WDK power management", "system power states WDK kernel", "device power states WDK kernel", "power consumption levels WDK kernel", "consumption levels WDK power management", "computing activity WDK power management", "physical device objects WDK power management", "PDOs WDK power management", "functional device objects WDK power management", "FDOs WDK power management", "filter DOs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Power States + + +## + + +A power state indicates the level of power consumption—and thus the extent of computing activity—by the system or by a single device. The power manager sets the power state of the system as a whole. Device drivers set the power state of their individual devices. + +The ACPI specification defines two sets of discrete power states: *system power states* and *device power states*. Each power state has a unique name. + +[System power states](system-power-states.md) are named S*x*, where *x* is a state number between 0 and 5. [Device power states](device-power-states.md) are named D*x*, where *x* is a state number between 0 and 3. The state number is inversely related to power consumption: higher numbered states use less power. States S0 and D0 are the highest-powered, most functional, fully on states. States S5 and D3 are the lowest-powered states and have the longest wake-up latency. + +These clearly defined power states allow many devices from various manufacturers to work together consistently and predictably. For example, when the power manager sets the system in state S3, it can rely upon drivers that support power management not only to put their devices in the corresponding device power state but also to return to the working state in a predictable fashion. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/powering-down-a-device.md b/windows-driver-docs-pr/kernel/powering-down-a-device.md new file mode 100644 index 0000000000..d0786007ee --- /dev/null +++ b/windows-driver-docs-pr/kernel/powering-down-a-device.md @@ -0,0 +1,40 @@ +--- +title: Powering Down a Device +author: windows-driver-content +description: Powering Down a Device +ms.assetid: d2525e15-9590-4fc0-955c-ca3540c13375 +keywords: ["device power downs WDK kernel", "powering down devices WDK kernel", "IRP_MN_REMOVE_DEVICE", "turning off devices WDK power management", "automatic power downs WDK kernel", "shutdown power management WDK kernel", "off power WDK kernel", "IRPs WDK power management", "surprise removals WDK power management", "device removals WDK power management", "removing devices", "I/O WDK power management", "unexpected device removal WDK power management", "idle detection WDK power management", "conserving power WDK kernel", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Powering Down a Device + + +## + + +Unless a device is enabled for wake-up, its drivers power it off when the system shuts down. Devices must always be powered off upon removal or surprise removal. + +When a device is removed, the Plug and Play manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request to the device stack. In response to this IRP, the drivers for the device should ensure that the device powers down. Powering down the device is an implicit part of removal handling; the device power policy owner is not required to send an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) for **PowerDeviceD3**. + +As drivers handle the **IRP\_MN\_REMOVE\_DEVICE** request, they wait for pending I/O to complete, perform any necessary removal processing, call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to notify the power manager that the device is in state D3, and delete the device objects they created for this device. Typically, the bus driver turns off power to the device. + +If a device is unexpectedly removed from a Windows 2000 or later operating system, the Plug and Play manager sends an [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request to the top of the corresponding device stack. In response to this IRP, the drivers for the device should perform surprise removal processing, as described in [Handling an IRP\_MN\_SURPRISE\_REMOVAL Request](handling-an-irp-mn-surprise-removal-request.md). + +At system shutdown, the power manager sends an **IRP\_MN\_SET\_POWER** for a system power state (either S4 or S5). When the device power policy owner receives this IRP, it should send an **IRP\_MN\_SET\_POWER** for **PowerDeviceD3** so that lower drivers can finish their work and power down the device. + +A driver can optionally perform idle detection for its device, or can request that the power manager perform idle detection, so that the device can be powered down when not in use. For further information, see [Detecting an Idle Device](detecting-an-idle-device.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Powering%20Down%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/powering-up-a-device.md b/windows-driver-docs-pr/kernel/powering-up-a-device.md new file mode 100644 index 0000000000..5b205d6555 --- /dev/null +++ b/windows-driver-docs-pr/kernel/powering-up-a-device.md @@ -0,0 +1,32 @@ +--- +title: Powering Up a Device +author: windows-driver-content +description: Powering Up a Device +ms.assetid: 115cc904-922d-447e-b221-cb3e489dd08d +keywords: ["I/O WDK power management", "device power ups WDK kernel", "powering up devices WDK kernel", "IRP_MN_SET_POWER", "working state returns WDK power management", "turning on devices WDK power management", "automatic power ups WDK kernel", "on power WDK kernel", "IRPs WDK power management", "startup power management WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Powering Up a Device + + +## + + +When a bus driver handles a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request for one of its child devices, it should power on the device and call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to report the device power state to the power manager. Powering on the device is an implicit part of device start-up. The device power policy owner does not send an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request for **PowerDeviceD0**, so drivers should not expect to receive these IRPs at start-up. + +When a device has been powered down to conserve power, its drivers should power it up when an I/O request arrives. In this case, the device power policy owner must send an **IRP\_MN\_SET\_POWER** to return the device to the working state. When the IRP completes, the drivers for the device stop queuing I/O and begin to process requests off the queue. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Powering%20Up%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/preventing-errors-and-deadlocks-while-using-spin-locks.md b/windows-driver-docs-pr/kernel/preventing-errors-and-deadlocks-while-using-spin-locks.md new file mode 100644 index 0000000000..d28d3a3d26 --- /dev/null +++ b/windows-driver-docs-pr/kernel/preventing-errors-and-deadlocks-while-using-spin-locks.md @@ -0,0 +1,62 @@ +--- +title: Preventing Errors and Deadlocks While Using Spin Locks +author: windows-driver-content +description: Preventing Errors and Deadlocks While Using Spin Locks +ms.assetid: 1df563e6-7ad2-4684-9778-ffa1b845ac31 +keywords: ["deadlocks WDK kernel", "recursion WDK kernel", "nested spin lock acquisitions WDK kernel", "pageable data locking WDK kernel", "spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Preventing Errors and Deadlocks While Using Spin Locks + + +## + + +While a driver routine holds a spin lock, it cannot cause a hardware exception or raise a software exception without bringing down the system. In other words, a driver's ISR and any *SynchCritSection* routine that the driver supplies in a call to [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) must not cause a fault or trap, such as a page fault or an arithmetic exception, and cannot raise a software exception. A routine that calls [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) or [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) also cannot cause a hardware exception or raise a software exception until it has released its executive spin lock and is no longer running at IRQL = DISPATCH\_LEVEL. + +### Pageable Data and Support Routines + +While holding a spin lock, drivers must not call routines that access pageable data. Remember that drivers can call certain support routines that access pageable data if and only if their calls occur while executing at an IRQL strictly less than DISPATCH\_LEVEL. This IRQL restriction precludes calling these support routines while holding a spin lock. For IRQL requirements for any specific support routine, see the routine's reference page. + +### Recursion + +Attempting to acquire a spin lock recursively is guaranteed to cause a deadlock: the holding instantiation of a recursive routine cannot release the spin lock while a second instantiation spins, trying to acquire the same spin lock. + +The following guidelines describe how you use spin locks with recursive routines: + +- The recursive routine must not call itself while holding a spin lock, or must not attempt to acquire the same spin lock on subsequent calls. + +- While the recursive routine holds a spin lock, another driver routine must not call the recursive routine if recursion might cause a deadlock or could cause the caller to hold the spin lock for longer than 25 microseconds. + +For more information about recursive driver routines, see [Using the Kernel Stack](using-the-kernel-stack.md). + +### Nested Spin Lock Acquisitions + +Attempting to acquire a second spin lock while holding another spin lock also can cause deadlocks or poor driver performance. + +The following guidelines describe how drivers should hold spin locks: + +- The driver must not call a support routine that uses a spin lock unless a deadlock cannot occur. + +- Even if a deadlock cannot occur, the driver should not call a support routine that uses a spin lock unless alternate coding techniques cannot provide comparable driver performance and functionality. + +- If a driver makes nested calls to acquire spin locks, it must always acquire the spin locks in the same order each time they are acquired. This order helps avoid deadlocks. + +In general, avoid using nested spin locks to protect overlapping subsets or discrete sets of shared data and resources. Consider what can happen if a driver uses two executive spin locks to protect discrete resources, such as a pair of timer objects that might be set individually and collectively by various driver routines. The driver would deadlock intermittently in an SMP machine, whenever either of two routines, each holding one spin lock, tried to acquire the other spin lock. + +For more information about acquiring nested spin locks, see the [Locks, Deadlocks, and Synchronization](http://go.microsoft.com/fwlink/p/?linkid=57456 ) article in the MSDN Library. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Preventing%20Errors%20and%20Deadlocks%20While%20Using%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/preventing-system-power-state-changes.md b/windows-driver-docs-pr/kernel/preventing-system-power-state-changes.md new file mode 100644 index 0000000000..8a526b3a61 --- /dev/null +++ b/windows-driver-docs-pr/kernel/preventing-system-power-state-changes.md @@ -0,0 +1,38 @@ +--- +title: Preventing System Power State Changes +author: windows-driver-content +description: Preventing System Power State Changes +ms.assetid: a744dfe7-d756-45c3-8fdf-7a403f6cde36 +keywords: ["system power states WDK kernel , preventing changes", "state transitions WDK power management", "PoRegisterSystemState", "PoSetSystemState", "PoUnregisterSystemState", "working states WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Preventing System Power State Changes + + +## + + +Although drivers cannot directly set system power policy, the power manager provides three routines through which a driver can prevent system transitions out of the working state: [**PoSetSystemState**](https://msdn.microsoft.com/library/windows/hardware/ff559768), [**PoRegisterSystemState**](https://msdn.microsoft.com/library/windows/hardware/ff559731), and [**PoUnregisterSystemState**](https://msdn.microsoft.com/library/windows/hardware/ff559794). + +By calling **PoRegisterSystemState** or **PoSetSystemState**, a driver can notify the power manager that a user is present or that the driver requires use of the system or display. + +**PoRegisterSystemState** allows a driver to register a continuous busy state. It returns a handle through which the driver can later change its settings. As long as the state registration is in effect, the power manager does not attempt to put the system to sleep. The driver cancels the state registration by calling **PoUnregisterSystemState**. + +With **PoSetSystemState**, a driver notifies the power manager of the same conditions (user present, system required, display required), but this setting is not continuous. It has the effect of restarting any idle count downs associated with the specified conditions. + +Using these routines, a driver can forestall many, but not all, transitions out of the working state. The power manager always shuts down the system when loss of power is imminent or when a user explicitly requests shutdown. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Preventing%20System%20Power%20State%20Changes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/previousmode.md b/windows-driver-docs-pr/kernel/previousmode.md new file mode 100644 index 0000000000..9d0866dcba --- /dev/null +++ b/windows-driver-docs-pr/kernel/previousmode.md @@ -0,0 +1,41 @@ +--- +title: PreviousMode +author: windows-driver-content +description: PreviousMode +ms.assetid: 1251cca9-604c-48c0-a136-21dd1fe4fa72 +keywords: ["PreviousMode", "RequestorMode"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PreviousMode + + +When a user-mode application calls the **Nt** or **Zw** version of a native system services routine, the system call mechanism traps the calling thread to kernel mode. To indicate that the parameter values originated in user mode, the trap handler for the system call sets the **PreviousMode** field in the [thread object](introduction-to-thread-objects.md) of the caller to **UserMode**. The native system services routine checks the **PreviousMode** field of the calling thread to determine whether the parameters are from a user-mode source. + +If a kernel-mode driver calls a native system services routine and passes parameter values to the routine that are from a kernel-mode source, the driver must make sure that the **PreviousMode** field in the current thread object is set to **KernelMode**. + +A kernel-mode driver can run in the context of an arbitrary thread, and the **PreviousMode** field of this thread might be set to **UserMode**. In this situation, a kernel-mode driver can call the **Zw** version of a native system services routine to inform the routine that the parameter values are from a trusted, kernel-mode source. The **Zw** call goes to a thin wrapper function that overrides the **PreviousMode** value in the current thread object. The wrapper function sets **PreviousMode** to **KernelMode** and calls the **Nt** version of the routine. On return from the **Nt** version of the routine, the wrapper function restores the original **PreviousMode** value of the thread object and returns. + +A kernel-mode driver can directly call the **Nt** version of a native system services routine. When a kernel-mode driver processes an I/O request that can originate either in user mode or in kernel mode, the driver can call the **Nt** version of the routine so that the **PreviousMode** value of the current thread remains unaltered during the call. The **Nt*Xxx*** routine checks the calling thread's **PreviousMode** value to determine whether the parameter values are from a user-mode application or a kernel-mode component, and treats them accordingly. + +An error can occur if a kernel-mode driver calls an **Nt*Xxx*** routine and the **PreviousMode** value in the current thread object does not accurately indicate whether the parameter values are from a user-mode or a kernel-mode source. + +For example, assume that a kernel-mode driver is running in the context of an arbitrary thread, and that the **PreviousMode** value for this thread is set to **UserMode**. If the driver passes a kernel-mode file handle to the [**NtClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) routine, this routine checks the **PreviousMode** value and decides that the handle must be a user-mode handle. When **NtClose** does not find the handle in the user-mode handle table, it returns the STATUS\_INVALID\_HANDLE error code. Meanwhile, the driver leaks the kernel-mode handle, which was never closed. + +For another example, if the parameters for an **Nt*Xxx*** routine include an input or output buffer, and if **PreviousMode** = **UserMode**, the routine calls the [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) or [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) routine to validate the buffer. If the buffer was allocated in system memory instead of in user-mode memory, the **ProbeFor*Xxx*** routine raises an exception, and the **Nt*Xxx*** routine returns the STATUS\_ACCESS\_VIOLATION error code. + +If it is necessary, a driver can call the [**ExGetPreviousMode**](https://msdn.microsoft.com/library/windows/hardware/ff545288) routine to get the **PreviousMode** value from the current thread object. Or, the driver can read the **RequestorMode** field from the [**IRP**](https://msdn.microsoft.com/library/windows/hardware/ff550694) structure that describes the requested I/O operation. The **RequestorMode** field contains a copy of the **PreviousMode** value from the thread that requested the operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20PreviousMode%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/privileges.md b/windows-driver-docs-pr/kernel/privileges.md new file mode 100644 index 0000000000..98e4c232fb --- /dev/null +++ b/windows-driver-docs-pr/kernel/privileges.md @@ -0,0 +1,62 @@ +--- +title: Privileges +author: windows-driver-content +description: Privileges +ms.assetid: 15deec90-73a3-4443-90b7-de4ec9673169 +keywords: ["privileges WDK objects", "process privileges WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Privileges + + +A *privilege* is a right that is associated with a process, rather than an object. A typical example of a privilege is **SeBackupPrivilege**, which confers on a process the right to back up files on a disk. + +A few routines check the privilege of the current process before completing an operation. If a driver routine is executed by the system process, then the operation always succeeds, but if the driver routine is executed by a user process that does not have the required privilege, then the operation can fail. + +The following table lists some examples of privileges and routines that can require them to succeed. + + ++++ + + + + + + + + + + + + + + + + + + + + +
PrivilegeRoutine that can require privilege

SeManageVolumePrivilege

[ZwSetInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567096) with FileInformationClass = FileValidDataLengthInformation

SeTakeOwnershipPrivilege

[SeAccessCheck](https://msdn.microsoft.com/library/windows/hardware/ff563674)

SeSecurityPrivilege

[SeAccessCheck](https://msdn.microsoft.com/library/windows/hardware/ff563674)

+ +  + +Most system routines do not perform any privilege checks. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Privileges%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-a-synchronous-driver-notification.md b/windows-driver-docs-pr/kernel/processing-a-synchronous-driver-notification.md new file mode 100644 index 0000000000..fc5584f555 --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-a-synchronous-driver-notification.md @@ -0,0 +1,143 @@ +--- +title: Processing a Synchronous Driver Notification +author: windows-driver-content +description: Processing a Synchronous Driver Notification +ms.assetid: 84e4e05f-1383-4f5f-8fc0-20cd508afa3c +keywords: ["driver notification WDK dynamic hardware partitioning , processing", "synchronous driver notification WDK dynamic hardware partitioning , processing", "registering for driver notification WDK dynamic hardware partitioning , synchronous"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing a Synchronous Driver Notification + + +When the operating system calls a registered callback function, it passes a pointer to a [**KE\_PROCESSOR\_CHANGE\_NOTIFY\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff554229) structure in the *ChangeContext* parameter and a pointer to a variable that contains an NTSTATUS code in the *OperationStatus* parameter. The **KE\_PROCESSOR\_CHANGE\_NOTIFY\_CONTEXT** structure contains the state of the processor add operation, the processor number of the new processor that is being added, and an NTSTATUS code that is associated with the indicated state. + +When a new processor is added to the hardware partition, the operating system calls the registered callback function two times. The operating system first calls the callback function with the **KeProcessorAddStartNotify** state before it starts the new processor. If the operating system successfully adds the new processor, it calls the callback function a second time with the **KeProcessorAddCompleteNotify** state. Otherwise, it calls the callback function a second time with the **KeProcessorAddFailureNotify** state. + +If the KE\_PROCESSOR\_CHANGE\_ADD\_EXISTING flag was specified when the device driver registered the callback function, the callback function is also called immediately for each active processor that currently exists in the hardware partition. Typically, the callback function will not have to distinguish between when it is called for an existing processor and when it is called for a new processor. For more information about when the operating system calls a registered callback function, see the description of the [**KeRegisterProcessorChangeCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553120) function. + +The following code example shows an implementation of a callback function that processes synchronous driver notifications: + +``` +// Synchronous notification callback function +VOID + SyncProcessorCallback( + IN PVOID CallbackContext, + IN PKE_PROCESSOR_CHANGE_NOTIFICATION_CONTEXT ChangeContext, + IN PNTSTATUS OperationStatus + ) +{ + PNTSTATUS CallbackStatus; + ULONG ProcessorNumber; + ULONG ProcessorCount; + KAFFINITY ActiveProcessors; + + // The CallbackContext contains a pointer to a + // variable that contains an NTSTATUS code. This + // is used to pass back any error status to the + // caller of KeRegisterProcessorChangeCallback. + CallbackStatus = + (PNTSTATUS) + CallbackContext; + + // Get the processor number of the new processor + ProcessorNumber = + ChangeContext->NtNumber; + + // Switch on the state of the add operation + switch (ChangeContext->State) + { + // Before the operating system has added the new processor + case KeProcessorAddStartNotify: + + // Allocate any per-processor data + // structures for the new processor. + ... + + // Assign any other per-processor resources + // to the new processor. + ... + + // Perform any other necessary preparation + // for execution of the driver code + // on the new processor. + ... + + // If an error occurs such that continuing + // to add the processor would be fatal + // (for example, an allocation failure of a + // per-processor data structure), set the + // status to an appropriate NTSTATUS code. + if (...) + { + // This returns the status to the operating system. + *OperationStatus = STATUS_INSUFFICIENT_RESOURCES; + + // This returns the status to the caller of the + // KeRegisterProcessorChangeCallback function. + *CallbackStatus = STATUS_INSUFFICIENT_RESOURCES; + } + + break; + + // The operating system has successfully added the new processor + case KeProcessorAddCompleteNotify: + + // + // The following can be performed either here or + // in an asynchronous notification callback function. + // + + // Get the current processor count and affinity + ProcessorCount = + KeQueryActiveProcessorCount( + &ActiveProcessors + ); + + // Adjust any resource allocations that are based + // on the number of processors. + ... + + // Adjust the assignment of resources that are + // assigned to specific processors. + ... + + // Begin scheduling any per-processor threads + // on the new processor. + ... + + // Adjust the scheduling of DPCs and other threads + ... + + // Adjust any load balancing algorithms + ... + + break; + + // The operating system has failed to add the new processor + case KeProcessorAddFailureNotify: + + // Clean up and free any per-processor + // resources that were allocated for the + // specified processor during the + // KeProcessorAddStartNotify state. + ... + + break; + } +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20a%20Synchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-an-application-notification.md b/windows-driver-docs-pr/kernel/processing-an-application-notification.md new file mode 100644 index 0000000000..4efb012237 --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-an-application-notification.md @@ -0,0 +1,255 @@ +--- +title: Processing an Application Notification +author: windows-driver-content +description: Processing an Application Notification +ms.assetid: 475d8e37-5d31-4989-92ce-3c4a7c09d292 +keywords: ["dynamic hardware partitioning WDK , application notification", "hardware partitioning WDK dynamic , application notification", "partitions WDK dynamic hardware , application notification", "application notification WDK dynamic hardware partitioning , registering", "notification WDK dynamic hardware partitioning , application", "registering for application notifications WDK dynamic hardware partitioning", "processing application notifications WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing an Application Notification + + +How a user-mode application processes WM\_DEVICECHANGE messages depends on whether the application is based purely on the Win32 API or whether it is based on the Microsoft Foundation Class (MFC) library. + +### Win32 applications + +Win32-based applications process the messages that are sent to the application's window(s) by implementing a *Window Procedure*. For more information about window procedures, see the [Window Procedures](http://go.microsoft.com/fwlink/p/?linkid=96748) topic in the Microsoft Windows SDK documentation. + +The following code example shows how to process WM\_DEVICECHANGE messages in a Win32-based application: + +``` +// Prototype for the function that handles the +// processing of WM_DEVICECHANGE messages. +LRESULT +OnDeviceChange( + WPARAM wParam, + LPARAM lParam + ); + +// The application's message processing function +// for the window that receives the WM_DEVICECHANGE +// messages. +LRESULT CALLBACK +WindowProc( + HWND hWnd, + UINT uMsg, + WPARAM wParam, + LPARAM lParam + ) +{ + switch (uMsg) + { + . + . // Cases for other messages + . + // Device change message + case WM_DEVICECHANGE: + OnDeviceChange(wParam, lParam); + break; + . + . // Cases for other messages + . + // Catchall for all messages that are + // not handled by the application. + default: + return DefWindowProc( + hWnd, + uMsg, + wParam, + lParam + ); + } + + return 0; +} + +// The function that handles the processing +// of WM_DEVICECHANGE messages. +LRESULT +OnDeviceChange( + WPARAM wParam, + LPARAM lParam + ) +{ + PDEV_BROADCAST_HDR devHdr; + PDEV_BROADCAST_DEVICEINTERFACE devInterface; + HANDLE ProcessHandle; + DWORD_PTR ProcessAffinityMask; + DWORD_PTR SystemAffinityMask; + DWORD_PTR ChangedAffinityMask; + MEMORYSTATUSEX MemoryStatus; + + // Check whether the message is a device arrival message + if (wParam == DBT_DEVICEARRIVAL) + { + // Get a pointer to the structure header + devHdr = (PDEV_BROADCAST_HDR)lParam; + + // Check whether the message is about a device interface + if (devHdr->dbch_devicetype == DBT_DEVTYP_DEVICEINTERFACE) + { + // Get a pointer to the device interface structure + devInterface = (PDEV_BROADCAST_INTERFACE)devHdr; + + // Check whether this is a message about a processor + if (IsEqualGUID( + devInterface->dbcc_classguid, + GUID_DEVICE_PROCESSOR + )) + { + // Get a handle to the current process + ProcessHandle = + GetCurrentProcess(); + + // Get the current process and system affinity masks + GetProcessAffinityMask( + ProcessHandle, + &ProcessAffinityMask, + &SystemAffinityMask + ); + + // Get a mask of any change to the set of processors + ChangedAffinityMask = + ProcessAffinityMask ^ SystemAffinityMask; + + // Perform any per processor memory allocation + // for any new processors + ... + + // Set the process affinity mask to use all the + // active processors in the hardware partition. + SetProcessAffinityMask( + ProcessHandle, + SystemAffinityMask + ); + + // Adjust the number of threads in any thread + // pools as needed for optimal performance. + ... + } + + // Check whether this is a message about memory + else if (IsEqualGUID( + devInterface->dbcc_classguid, + GUID_DEVICE_MEMORY + )) + { + // Get the current memory status + GlobalMemoryStatusEx(&MemoryStatus); + + // Note: MemoryStatus.ullTotalPhys contains + // the amount of physical memory in the + // hardware partition. + + // Adjust the memory buffer allocations + // as needed for optimal performance. + ... + } + } + } + + return 0; +} +``` + +### MFC applications + +The MFC framework processes the messages that are sent to an MFC-based application's window(s). An MFC-based application must implement an [OnDeviceChange](http://go.microsoft.com/fwlink/p/?linkid=97894) member function for the application's window class that receives the WM\_DEVICECHANGE messages. + +The following code example shows how to implement an **OnDeviceChange** member function in an MFC-based application: + +``` +afx_msg BOOL +CAppWnd::OnDeviceChange( + UINT nEventType, + DWORD_PTR dwData + ) +{ + PDEV_BROADCAST_HDR devHdr; + PDEV_BROADCAST_DEVICEINTERFACE devInterface; + HANDLE ProcessHandle; + DWORD_PTR ProcessAffinityMask; + DWORD_PTR SystemAffinityMask; + DWORD_PTR ChangedAffinityMask; + MEMORYSTATUSEX MemoryStatus; + + if (nEventType == DBT_DEVICEARRIVAL) + { + devHdr = (PDEV_BROADCAST_HDR)dwData; + + if (devHdr->dbch_devicetype == DBT_DEVTYP_DEVICEINTERFACE) + { + devInterface = (PDEV_BROADCAST_INTERFACE)devHdr; + + if (IsEqualGUID( + devInterface->dbcc_classguid, + GUID_DEVICE_PROCESSOR + )) + { + // Get a handle to the current process + ProcessHandle = + GetCurrentProcess(); + + // Get the current process and system affinity masks + GetProcessAffinityMask( + ProcessHandle, + &ProcessAffinityMask, + &SystemAffinityMask + ); + + // Get a mask of any change to the set of processors + ChangedAffinityMask = + ProcessAffinityMask ^ SystemAffinityMask; + + // Perform any per processor memory allocation + // for the new processors + ... + + // Set the process affinity mask to use all the + // active processors in the hardware partition. + SetProcessAffinityMask( + ProcessHandle, + SystemAffinityMask + ); + + // Adjust the number of threads in any thread + // pools as needed for optimal performance. + ... + } + else if (IsEqualGUID( + devInterface->dbcc_classguid, + GUID_DEVICE_MEMORY + )) + { + // Get the current memory status + GlobalMemoryStatusEx(&MemoryStatus); + + // Note: MemoryStatus.ullTotalPhys contains + // the amount of physical memory in the + // hardware partition. + + // Adjust the memory buffer allocations + // as needed for optimal performance. + ... + } + } + } + + return TRUE; +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20an%20Application%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-an-asynchronous-driver-notification.md b/windows-driver-docs-pr/kernel/processing-an-asynchronous-driver-notification.md new file mode 100644 index 0000000000..d83de2867d --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-an-asynchronous-driver-notification.md @@ -0,0 +1,115 @@ +--- +title: Processing an Asynchronous Driver Notification +author: windows-driver-content +description: Processing an Asynchronous Driver Notification +ms.assetid: 7e7ed971-5891-4b91-909a-1e140b764fed +keywords: ["driver notification WDK dynamic hardware partitioning , processing", "asynchronous driver notification WDK dynamic hardware partitioning , processing", "registering for driver notification WDK dynamic hardware partitioning , asynchronous"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing an Asynchronous Driver Notification + + +When the operating system calls a registered callback function, it passes a pointer to a [**DEVICE\_INTERFACE\_CHANGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff543134) structure in the *NotificationStructure* parameter. + +The following code example shows an implementation of a callback function that processes asynchronous driver notifications for processors: + +``` +// Asynchronous processor notification callback function +NTSTATUS + AsyncProcessorCallback( + IN PVOID NotificationStructure, + IN PVOID Context + ) +{ + PDEVICE_INTERFACE_CHANGE_NOTIFICATION Notification; + ULONG ProcessorCount; + KAFFINITY ActiveProcessors; + + Notification = + (PDEVICE_INTERFACE_CHANGE_NOTIFICATION) + NotificationStructure; + + // Verify that this notification is about a processor + // that is being added to the hardware partition. + if (IsEqualGUID( + &Notification->Event, + &GUID_DEVICE_INTERFACE_ARRIVAL + )) + { + // Get the current processor count and affinity + ProcessorCount = + KeQueryActiveProcessorCount( + &ActiveProcessors + ); + + // Adjust any resource allocations that are based + // on the number of processors. + ... + + // Adjust the assignment of resources that are + // assigned to specific processors. + ... + + // Begin scheduling any per processor threads + // on the new processor. + ... + + // Adjust the scheduling of DPCs and other threads + ... + + // Adjust any load balancing algorithms + ... + } + + // Always return success status + return STATUS_SUCCESS; +} +``` + +The following code example shows an implementation of a callback function that processes asynchronous driver notifications for memory: + +``` +// Asynchronous memory notification callback function +NTSTATUS + AsyncMemoryCallback( + IN PVOID NotificationStructure, + IN PVOID Context + ) +{ + PDEVICE_INTERFACE_CHANGE_NOTIFICATION Notification; + + Notification = + (PDEVICE_INTERFACE_CHANGE_NOTIFICATION) + NotificationStructure; + + // Verify that this notification is about memory + // that is being added to the hardware partition. + if (IsEqualGUID( + &Notification->Event, + &GUID_DEVICE_INTERFACE_ARRIVAL + )) + { + // Increase the size of any memory buffers + // for optimal performance of the driver. + ... + } + + // Always return success status + return STATUS_SUCCESS; +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20an%20Asynchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-irps-in-a-lowest-level-driver.md b/windows-driver-docs-pr/kernel/processing-irps-in-a-lowest-level-driver.md new file mode 100644 index 0000000000..c38c7728de --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-irps-in-a-lowest-level-driver.md @@ -0,0 +1,108 @@ +--- +title: Processing IRPs in a Lowest-Level Driver +author: windows-driver-content +description: Processing IRPs in a Lowest-Level Driver +ms.assetid: 9b8c2586-d47b-49ab-bf65-a298af36304c +keywords: ["IRPs WDK kernel , processing examples", "IRPs WDK kernel , I/O status blocks", "I/O status blocks WDK kernel", "status blocks WDK kernel", "IoStartNextPacket", "IoCompleteRequest", "IoRequestDpc", "AllocateAdapterChannel", "MapTransfer", "IoStartPacket", "IoMarkIrpPending", "IoGetCurrentIrpStackLocation"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing IRPs in a Lowest-Level Driver + + +## + + +Lowest-level physical drivers have certain standard routines that higher-level drivers do not need. The set of standard routines for lowest-level drivers also varies according to the following criteria: + +- The nature of the device each driver controls + +- Whether the driver sets up its device objects for direct or buffered I/O + +- The design of the individual driver + +To illustrate the roles of the standard driver routines, the following figure shows the path a sample IRP might take as it is processed by a lowest-level mass-storage device driver. The driver in the figure has the following characteristics: + +- The device generates interrupts at the end of each I/O operation, so this driver has ISR and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routines. + +- The driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, rather than setting up internal queues for IRPs and managing its own queuing. + +- The driver uses system DMA, so it sets its device objects' **Flags** for direct I/O, and has an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine. + +![diagram illustrating an irp path through lowest-level driver routines](images/4loddirp.png) + +As this figure shows, the I/O manager creates an IRP and sends it to the driver's dispatch routine for the given major function code. Assuming the function code is either [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) or [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), the dispatch routine is **DDDispatchReadWrite**. + +### Calling IoGetCurrentIrpStackLocation + +Any driver routine that requires IRP parameters must call [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) to obtain the driver's [I/O stack location](i-o-stack-locations.md). Such routines include dispatch routines that handle more than one major I/O function code (**IRP\_MJ\_*XXX***), handle a function that supports minor functions (**IRP\_MN\_*XXX***), or handle device I/O control requests ([**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and/or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766)), along with every other driver routine that processes an IRP. + +This driver's I/O stack location is the lowest one, with an indefinite number of higher-level drivers' I/O stack locations shown shaded. For simplicity, calls to **IoGetCurrentIrpStackLocation** from the [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381), *StartIo*, *AdapterControl*, and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routines are not shown in the previous figure. + +### Calling IoMarkIrpPending and IoStartPacket + +The sample driver does not complete the IRP in its dispatch routine, but instead processes the IRP in its *StartIo* routine. Before it can do so, the dispatch routine calls [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) to indicate that the IRP is not yet completed. Then it calls [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) to queue the IRP for further processing by the driver's *StartIo* routine. The dispatch routine also returns the NTSTATUS value STATUS\_PENDING. + +The following figure illustrates the call to **IoStartPacket**. + +![diagram illustrating a call to iostartpacket](images/4strtpak.png) + +If the driver is busy processing another IRP on the device, **IoStartPacket** inserts the IRP into the device queue associated with the device object. The driver can optionally supply a *Key* value as a parameter to **IoStartPacket** to impose a driver-determined order on IRPs in the device queue. + +If the driver is not busy and the device queue is empty, the I/O manager immediately calls its *StartIo* routine, passing the input IRP. + +For mass-storage devices, the lowest-level driver does not need to supply a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine when it calls **IoStartPacket** for two reasons: + +1. A file system layered over such a driver typically handles the cancellation of file I/O requests. + +2. Mass-storage device drivers process IRPs quickly. + +Usually, the highest-level driver in a chain of layered drivers handles the cancellation of IRPs. + +### Calling AllocateAdapterChannel and MapTransfer + +Assuming the *StartIo* routine, shown in the figure illustrating an IRP path through lowest-level driver routines, determines that the transfer request can be done by a single DMA operation, the *StartIo* routine calls [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) with the entry point of the driver's *AdapterControl* routine and the IRP. + +When the system DMA controller is available, the I/O manager calls the driver's *AdapterControl* routine to set up the transfer operation. The *AdapterControl* routine calls [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) to set up the system DMA controller. Then the driver programs its device for the DMA operation and returns. (For more information about using DMA and adapter objects, see [Input/Output Techniques](i-o-programming-techniques.md).) + +### Calling IoRequestDpc from the Driver's ISR + +When the device interrupts to indicate its transfer operation is complete, the driver's ISR stops the device from generating interrupts and calls [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657), as shown in the figure illustrating an IRP path through lowest-level driver routines. + +This call queues the driver's *DpcForIsr* routine to complete as much of the transfer operation as possible at a lower hardware priority (IRQL). + +### Calling IoStartNextPacket and IoCompleteRequest + +When the *DpcForIsr* routine has finished processing the transfer, it calls [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) promptly so that the driver's *StartIo* routine will be called with the next IRP in the device queue, if any are queued. The *DpcForIsr* routine also sets the just-completed IRP's I/O status block and then calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) for the IRP. + +The following figure illustrates this driver's calls to **IoStartNextPacket** and **IoCompleteRequest**. + +![calling iostartnextpacket and iocompleterequest](images/4snxtpak.png) + +Drivers should call **IoStartNextPacket** or [**IoStartNextPacketByKey**](https://msdn.microsoft.com/library/windows/hardware/ff550363) to begin the next requested I/O operation as soon as possible, preferably before they call **IoCompleteRequest**. + +If any IRPs are queued for the device, **IoStartNextPacket** calls [**KeRemoveDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553156) to remove the next IRP from the queue. The I/O manager then calls the driver's *StartIo* routine, passing the dequeued IRP. If no IRPs are currently in the device queue, **IoStartNextPacket** merely returns to the caller. + +### Setting the I/O Status Block in an IRP + +Every lowest-level driver must set the IRP's [I/O status block](i-o-status-blocks.md) before calling [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). (In the previous figure, the second shaded area denotes the status block.) The I/O status block supplies information to higher-level drivers and, ultimately, to the original requester of the I/O operation. Any higher-level driver layered above the driver in the previous figure might have set up an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine that reads the I/O status block set by this driver. Higher-level drivers usually do not modify the I/O status block in an IRP that has been completed by a device driver, unless the higher-level driver is retrying the IRP, in which case it reinitializes the I/O status block. + +Every higher-level driver that completes an IRP without sending it on to the next lower driver also must set the I/O status block in that IRP before calling **IoCompleteRequest**. For good overall I/O throughput, a higher-level driver should check the parameters in its own I/O stack location of each IRP and, if the parameters are invalid, should set the I/O status block and complete the request itself. Whenever possible, a driver should avoid passing an invalid request on to lower drivers in the chain. + +Assuming the transfer operation in the previous figure is successful, the *DpcForIsr* routine, shown in the figure illustrating an IRP path through lowest-level driver routines, sets STATUS\_SUCCESS in **Status** and the number of bytes transferred in **Information** for the IRP's I/O status block. + +Many of the standard driver routines also return NTSTATUS-type values. For more information about NTSTATUS constants like STATUS\_SUCCESS, see [Logging Errors](logging-errors.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20IRPs%20in%20a%20Lowest-Level%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-irps-in-an-intermediate-level-driver.md b/windows-driver-docs-pr/kernel/processing-irps-in-an-intermediate-level-driver.md new file mode 100644 index 0000000000..bf47a751ad --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-irps-in-an-intermediate-level-driver.md @@ -0,0 +1,86 @@ +--- +title: Processing IRPs in an Intermediate-Level Driver +author: windows-driver-content +description: Processing IRPs in an Intermediate-Level Driver +ms.assetid: 7606ab1b-68af-4d27-8668-7662969b85b8 +keywords: ["IRPs WDK kernel , processing examples", "IoCompletion routines", "IoSetCompletionRoutine", "mirror drivers WDK IRPs", "allocating IRPs", "IoCallDriver"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing IRPs in an Intermediate-Level Driver + + +## + + +Higher-level drivers have a different set of standard routines than lowest-level device drivers, with an overlapping subset of standard routines common to both types of drivers. + +The set of routines for intermediate and highest-level drivers also varies according to the following criteria: + +- The nature of the underlying physical device + +- Whether an underlying device driver sets up device objects for direct or buffered I/O + +- The design of the individual higher-level driver + +The following figure illustrates the path an IRP might take through the standard routines of an intermediate [*mirror driver*](https://msdn.microsoft.com/library/windows/hardware/ff556308#wdkgloss-mirror-driver) layered somewhere over the lowest-level device driver described in the previous section. + +The driver shown in the following figure has the following characteristics: + +- The driver is layered over more than one physical device and possibly over more than one device driver. + +- The driver sometimes allocates additional IRPs for lower-level drivers, depending on the requested operation in the input IRP. + +- The driver has at least one file system driver layered above it, and that file system driver might be layered over other intermediate drivers at a higher level than this one. + +### + +![diagram illustrating an irp path through intermediate driver routines](images/4hiddirp.png) + +As the figure shows, the I/O manager creates an IRP and sends it to the driver's dispatch routine for the given major function code. Assuming the function code is [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), the dispatch routine is **DDDispatchWrite**. The intermediate driver's I/O stack location is shown in the middle, with an indefinite number of I/O stack locations for higher- and lower-level drivers shown shaded. + +### Allocating IRPs + +The mirror driver's purpose is to send write requests to several physical devices, and to send read requests alternately to the drivers of these devices. For write requests, the driver creates duplicate IRPs for each device on which the data is to be written, assuming the parameters in the input IRP are valid. + +The previous figure shows a call to [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) but higher-level drivers can call other support routines to allocate IRPs for lower-level drivers. See [Creating IRPs for Lower-Level Drivers](creating-irps-for-lower-level-drivers.md). + +When the dispatch routine calls **IoAllocateIrp**, it specifies the number of I/O stack locations needed for the IRP. The driver must specify a stack location for each lower driver in the chain, getting the appropriate value from the device objects of each driver just below the mirror driver. Optionally, the driver can add one to this value when it calls **IoAllocateIrp** to get a stack location of its own for each IRP it allocates, as the driver in the previous figure does. + +This intermediate driver's dispatch routine calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) (not shown) with the original IRP, to check parameters. + +It calls [**IoSetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550321) because it allocated its own stack location in each newly created IRP and [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) to create a context for itself that it uses later in the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +Next, it calls [**IoGetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549266) with each newly created IRP so that it can set up the next lower-level drivers' I/O stack locations in the IRPs it allocated. The mirror driver's dispatch routine copies the IRP function codes and parameters (pointer to the transfer buffer, length in bytes to be transferred for **IRP\_MJ\_WRITE**) into the I/O stack locations for the next-lower drivers. These drivers, in turn, will set up the I/O stack locations for the drivers just below them, if any. + +### Calling IoSetCompletionRoutine and IoCallDriver + +The dispatch routine in the previous figure calls [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) for each IRP it allocated. Because the driver in the previous figure must dispose of the IRPs it allocated, this driver sets its *IoCompletion* routine to be called when lower drivers complete its IRPs, whether the I/O operation completed successfully, failed, or was canceled. + +Because the driver in the previous figure mirrors in parallel, it passes both IRPs that it allocated on to the next-lower-level drivers by calling [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) twice, once for each target device object representing a mirrored partition. + +### Processing IRPs in the Driver's IoCompletion Routine + +When either set of lower-level drivers completes the requested operation, the I/O manager calls the intermediate mirror driver's *IoCompletion* routine. The mirror driver maintains a count in its own I/O stack location for the original IRP, to track when the lower drivers have completed all the duplicate IRPs. + +Assuming that the I/O status block indicates that one set of lower drivers has completed the duplicate IRP shown in the [previous figure](#irp-path-through-intermediate-driver-routines), the mirror driver's *IoCompletion* routine decrements its count but cannot complete the original IRP until it decrements the count to zero. If the decremented count is not yet zero, the *IoCompletion* routine calls [**IoFreeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549113) with the first-returned IRP (DupIRP1 in the previous figure) that the driver allocated and returns STATUS\_MORE\_PROCESSING\_REQUIRED. + +When the mirror driver's *IoCompletion* routine is called again with the DupIRP2 shown in the previous figure, the *IoCompletion* routine decrements the count in the original IRP and determines that both sets of lower-level drivers have carried out the requested operations. + +Assuming the I/O status block in DupIRP2 also is set with STATUS\_SUCCESS, the *IoCompletion* routine copies the I/O status block from DupIRP2 into the original IRP and frees DupIRP2. It calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the original IRP and returns STATUS\_MORE\_PROCESSING\_REQUIRED. Returning this status prevents the I/O manager from attempting any further completion processing on DupIRP2; because the IRP is not associated with a thread, its completion processing should end with the driver that created it. + +If either set of lower-level drivers does not complete the mirror driver's IRPs successfully, the mirror driver's *IoCompletion* routine should log an error and attempt appropriate mirrored-data recovery. For more information, see [Logging Errors](logging-errors.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20IRPs%20in%20an%20Intermediate-Level%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md b/windows-driver-docs-pr/kernel/processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md new file mode 100644 index 0000000000..eb6b2e1355 --- /dev/null +++ b/windows-driver-docs-pr/kernel/processing-wmi-irps-in-a-dispatchsystemcontrol-routine.md @@ -0,0 +1,68 @@ +--- +title: Processing WMI IRPs in a DispatchSystemControl Routine +author: windows-driver-content +description: Processing WMI IRPs in a DispatchSystemControl Routine +ms.assetid: 9f1fc209-ee32-4270-87e5-e360ca5eca17 +keywords: ["WMI WDK kernel , requests", "requests WDK WMI", "IRPs WDK WMI", "DispatchSystemControl routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Processing WMI IRPs in a DispatchSystemControl Routine + + +## + + +A driver that handles WMI IRPs in its [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine must handle such an IRP only if the device object pointer at **Parameters.WMI.ProviderId** matches the pointer passed by the driver in its call to [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). Otherwise, the driver must forward the IRP to the next lower driver. + +If the driver handles the request, it must: + +Check the GUID at **Parameters.WMI.DataPath** to determine whether it represents a data block supported by the driver and, if not, fail the IRP with STATUS\_WMI\_GUID\_NOT\_FOUND. + +A driver should check the input **WNODE\_*XXX*** structure at **Parameters.WMI.Buffer** for the instance name when handling any of the following requests: + +[**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) +[**IRP\_MN\_CHANGE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff550831) +[**IRP\_MN\_CHANGE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff550836) +[**IRP\_MN\_EXECUTE\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/ff550868) +The driver should check for the instance name as follows: + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is set in **WnodeHeader.Flags**, use **InstanceIndex** as an index into the driver's list of static instance names for that block. + +- If WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES is clear in **WnodeHeader.Flags**, use **OffsetInstanceName** as an offset to the instance name string in the input **WNODE\_*XXX*** structure. **OffsetInstanceName** is the offset in bytes from the beginning of the structure to a USHORT that indicates the length of the instance name string in bytes (not characters), including the NUL terminator if present, followed by the string itself in Unicode. + +If the driver cannot locate the instance specified by **InstanceIndex** or **OffsetInstanceName**, it must fail the IRP with STATUS\_WMI\_INSTANCE\_NOT\_FOUND. + +For an [**IRP\_MN\_EXECUTE\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/ff550868) request, check **MethodID** in the input [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) and, if the method is not valid for that data block, fail the IRP with STATUS\_WMI\_ITEMID\_NOT\_FOUND. + +If the request generates output, a driver should check the size of the buffer at **Parameters.WMI.BufferSize** when handling any of the following requests: + +[**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) +[**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) +[**IRP\_MN\_EXECUTE\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/ff550868) +If the buffer is too small to receive the output, but at least **sizeof**(**WNODE\_TOO\_SMALL**), the driver should succeed the IRP and write a [**WNODE\_TOO\_SMALL**](https://msdn.microsoft.com/library/windows/hardware/ff566379) structure to the buffer at **Parameters.WMI.Buffer**. If the buffer is smaller than **sizeof**(**WNODE\_TOO\_SMALL**), the driver fails the IRP with an NTSTATUS code of STATUS\_BUFFER\_TOO\_SMALL. + +If the request generates output and the buffer size is adequate, write the following output to the buffer at **Parameters.WMI.Buffer**: +- For an **IRP\_MN\_QUERY\_ALL\_DATA** request, the driver writes a [**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) structure that contains data for all instances of the specified data block. +- For an **IRP\_MN\_QUERY\_SINGLE\_INSTANCE** request, the driver writes a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure that contains data for the specified instance of a data block. +- For an **IRP\_MN\_EXECUTE\_METHOD** if the method generates output, the driver writes the method output in driver-determined format following the input [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) in the buffer (overwriting input data, if any). + +Set **Irp->IoStatus.Information** to the number of bytes written to the buffer at **Parameters.WMI.Buffer** and **Irp->IoStatus.Status** to STATUS\_SUCCESS. + +Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the IRP. + +For more information, see [WMI WNODE\_*XXX* Structures](wmi-wnode-xxx-structures.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Processing%20WMI%20IRPs%20in%20a%20DispatchSystemControl%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/programming-a-device-for-an-i-o-operation.md b/windows-driver-docs-pr/kernel/programming-a-device-for-an-i-o-operation.md new file mode 100644 index 0000000000..bb92f45384 --- /dev/null +++ b/windows-driver-docs-pr/kernel/programming-a-device-for-an-i-o-operation.md @@ -0,0 +1,42 @@ +--- +title: Programming a Device for an I/O Operation +author: windows-driver-content +description: Programming a Device for an I/O Operation +ms.assetid: 952b07d8-81e3-40ec-8acd-be1143a7d2a2 +keywords: ["critical section routines WDK kernel", "I/O WDK kernel , device programming"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Programming a Device for an I/O Operation + + +## + + +Use the following general guidelines for designing, writing, and calling [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines that program a device for I/O operations: + +- A *SynchCritSection* routine that programs the device for I/O operations must return control as quickly as possible. + + For this reason, the *SynchCritSection* routine should do only what is necessary to set up the device for I/O. Therefore, the driver should perform all IRP preprocessing, initializing state information for other driver routines, and acquiring hardware resources before it calls the *SynchCritSection* routine. + +- A device driver can have multiple *SynchCritSection* routines to program the device. + + For example, the driver of a device for which setting up a read request differs markedly from setting up certain device control requests might have separate *SynchCritSection* routines to program its device for each type of request. + +- Every *SynchCritSection* routine must return control as quickly as possible, because running any *SynchCritSection* routine prevents the driver's ISR from executing. + + You should not write a single, large, general-purpose *SynchCritSection* routine with a **switch** statement or many nested **if..then..else** statements to determine what operations it will carry out or what state information to update. On the other hand, you should avoid writing numerous *SynchCritSection* routines that program only a single device register. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Programming%20a%20Device%20for%20an%20I/O%20Operation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/programming-issues-for-64-bit-drivers.md b/windows-driver-docs-pr/kernel/programming-issues-for-64-bit-drivers.md new file mode 100644 index 0000000000..51ec4754f7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/programming-issues-for-64-bit-drivers.md @@ -0,0 +1,38 @@ +--- +title: Programming Issues for 64-Bit Drivers +author: windows-driver-content +description: Programming Issues for 64-Bit Drivers +ms.assetid: 36794bd3-1d44-4edf-b789-a4da4165ea60 +keywords: ["64-bit WDK kernel", "kernel-mode drivers WDK , 64-bit issues", "Win32 applications WDK 64-bit", "user-mode applications WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Programming Issues for 64-Bit Drivers + + +## + + +This section discusses issues you need to be concerned about when developing drivers for 64-bit processing environments. It includes the following sections: + +[Porting Your Driver to 64-Bit Windows](porting-your-driver-to-64-bit-windows.md) + +[Supporting 32-Bit I/O in Your 64-Bit Driver](supporting-32-bit-i-o-in-your-64-bit-driver.md) + +[Driver x64 Restrictions](driver-x64-restrictions.md) + +For information about programming with a 64-bit compiler, see [64-Bit Programming with Visual C++](http://go.microsoft.com/fwlink/p/?linkid=165521). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Programming%20Issues%20for%2064-Bit%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/properties-of-device-objects.md b/windows-driver-docs-pr/kernel/properties-of-device-objects.md new file mode 100644 index 0000000000..b60a96c773 --- /dev/null +++ b/windows-driver-docs-pr/kernel/properties-of-device-objects.md @@ -0,0 +1,42 @@ +--- +title: Properties of Device Objects +author: windows-driver-content +description: Properties of Device Objects +ms.assetid: 6cd31263-e725-4a62-bec9-f40feb0b66cc +keywords: ["device objects WDK kernel , properties", "properties WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Properties of Device Objects + + +## + + +Each device object has certain properties that describe the device and how the device object interacts with the system. The device object properties include: + +- Device type. Specifies the device's type of hardware. For more information about device types, see [Specifying Device Types](specifying-device-types.md). + +- Device characteristics. Specifies flags that provide additional information about the device. For more information, see [Specifying Device Characteristics](specifying-device-characteristics.md). + +- Exclusive access. Specifies whether the device object represents an *exclusive device*. If the device is exclusive, only one handle can be open for the device object at a time. (If the underlying device supports overlapped I/O, multiple threads of the same process can send requests through a single handle.) For more information, see [Specifying Exclusive Access to Device Objects](specifying-exclusive-access-to-device-objects.md). + +- Security descriptor. Device objects have a security descriptor that controls access to the device. For more information, see [Securing Device Objects](securing-device-objects.md). + +For each of these properties, a default value can be set when the device object is created. For more information about creating device objects, see [Creating a Device Object](creating-a-device-object.md). + +Values for device object properties can also be set in the registry. See [Setting Device Object Properties in the Registry](setting-device-object-properties-in-the-registry.md) for more information. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Properties%20of%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/providing-customtimerdpc-context-information.md b/windows-driver-docs-pr/kernel/providing-customtimerdpc-context-information.md new file mode 100644 index 0000000000..3d27bc1b7d --- /dev/null +++ b/windows-driver-docs-pr/kernel/providing-customtimerdpc-context-information.md @@ -0,0 +1,38 @@ +--- +title: Providing CustomTimerDpc Context Information +author: windows-driver-content +description: Providing CustomTimerDpc Context Information +ms.assetid: b4d711fb-63d4-45c6-8054-f934741ce340 +keywords: ["timer objects WDK kernel , CustomTimerDpc routines", "CustomTimerDpc", "DeferredContext routine", "context information WDK synchronization", "timer objects WDK kernel , context information"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Providing CustomTimerDpc Context Information + + +## + + +The *DeferredContext* pointer passed to [**KeInitializeDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552130) points to a context area where other driver routines, and the *CustomTimerDpc* routine itself, can maintain state. The kernel passes the *DeferredContext* pointer in every call to the DPC routine. + +Unlike an *IoTimer* routine, a *CustomTimerDpc* has no particular associations with a driver-created device object. However, a driver can associate a *CustomTimerDpc* routine with a driver-created device object by including a pointer to the device object in its context area. + +The context area must be in resident, driver-allocated memory. Usually, this context area is in a device extension, but it can also be in nonpaged pool. If the driver uses a controller object, it can be in a controller extension. The contents of the context area are driver-determined. + +If a *CustomTimerDpc* routine shares context information with the driver's ISR, the *CustomTimerDpc* routine must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a *SynchCritSection* routine that accesses the shared context. For more information, see [Using Critical Sections](using-critical-sections.md). + +If the *CustomTimerDpc* shares the context information with other non-ISR driver routines, the area at *DeferredContext* must be protected by an executive spin lock. For more information, see [Spin Locks](spin-locks.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Providing%20CustomTimerDpc%20Context%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/providing-iotimer-context-information.md b/windows-driver-docs-pr/kernel/providing-iotimer-context-information.md new file mode 100644 index 0000000000..be0cc91f95 --- /dev/null +++ b/windows-driver-docs-pr/kernel/providing-iotimer-context-information.md @@ -0,0 +1,38 @@ +--- +title: Providing IoTimer Context Information +author: windows-driver-content +description: Providing IoTimer Context Information +ms.assetid: a92a7c3d-1602-430b-8ae1-c79bfc9ac7f9 +keywords: ["IoTimer", "IoInitializeTimer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Providing IoTimer Context Information + + +## + + +The *Context* pointer passed to [**IoInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff549344) identifies a context area where other driver routines, and the [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine itself, can maintain state about timed operations. The I/O manager passes the *Context* pointer whenever it calls the *IoTimer* routine. + +Because an *IoTimer* routine is run at IRQL = DISPATCH\_LEVEL, its context area must be in resident, system-space memory. Most drivers that have *IoTimer* routines use the [device extension](device-extensions.md) of the associated device object as a *Context*-accessible area, but the context can instead be in a controller extension if the driver uses a [controller object](using-controller-objects.md) or in nonpaged pool allocated by the driver. + +**Follow these guidelines for an** *IoTimer***routine's context area:** + +- If the *IoTimer* routine shares its context area with the driver's ISR, it must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that accesses the context area in a multiprocessor-safe manner. For more information, see [Using Critical Sections](using-critical-sections.md). + +- If the *IoTimer* routine does not share its context area with an ISR, but does share it with another driver routine, the driver must protect the shared context area with an initialized executive spin lock, in order to access the context information in a multiprocessor-safe manner. For more information, see [Spin Locks](spin-locks.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Providing%20IoTimer%20Context%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/providing-isr-context-information.md b/windows-driver-docs-pr/kernel/providing-isr-context-information.md new file mode 100644 index 0000000000..701c3685c9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/providing-isr-context-information.md @@ -0,0 +1,36 @@ +--- +title: Providing ISR Context Information +author: windows-driver-content +description: Providing ISR Context Information +ms.assetid: 216c3111-3638-4410-a720-ff3d65a1eadd +keywords: ["interrupt service routines WDK kernel , context information", "ISRs WDK kernel , context information", "interrupt objects WDK kernel , context information", "context information WDK interrupts", "pointers WDK interrupts"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Providing ISR Context Information + + +## + + +On entry, an ISR receives a pointer to whatever context area the driver set up when it called [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) to register the routine. + +Most drivers set the context pointer to the device object that represents the physical device that generates interrupts, or to that device object's device extension. In the device extension, the driver can store state information for the driver's ISR and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine, the latter of which usually does almost all of the I/O processing to satisfy each request that caused the device to interrupt. + +Typically, drivers use the device extension to store pointers to each of the device's interrupt objects (returned from calls to **IoConnectInterruptEx**). Drivers also typically store information in the device extension that allows an ISR to determine if an interrupt was issued by a device the ISR supports. + +(Alternatively, interrupt object pointers can be stored in nonpaged pool that the driver allocates.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Providing%20ISR%20Context%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/providing-storage-for-spin-locks-and-protected-data.md b/windows-driver-docs-pr/kernel/providing-storage-for-spin-locks-and-protected-data.md new file mode 100644 index 0000000000..92ee8b9906 --- /dev/null +++ b/windows-driver-docs-pr/kernel/providing-storage-for-spin-locks-and-protected-data.md @@ -0,0 +1,50 @@ +--- +title: Providing Storage for Spin Locks and Protected Data +author: windows-driver-content +description: Providing Storage for Spin Locks and Protected Data +ms.assetid: bde18474-10c3-4d9a-b120-6cbd5fc675cc +keywords: ["storage WDK spin locks", "storing spin-lock-protected data", "spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Providing Storage for Spin Locks and Protected Data + + +## + + +As part of device start-up, a driver must allocate resident storage for any spin-lock-protected data or resources and for corresponding spin locks in one of the following places: + +- The device extension of a device object that the driver sets up by calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) + +- The controller extension of a controller object that the driver sets up by calling [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395) + +- Nonpaged, system-space memory that the driver obtains by calling [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) + +Attempting to access pageable data while holding a spin lock causes a fatal page fault if that page is not present. Referencing a spin lock that is invalid (because it was stored in pageable memory and is currently paged out) also causes a fatal page fault. + +A driver must provide the storage for each of the following kinds of executive spin lock it might use: + +- Any spin lock that the driver explicitly acquires and releases using any of the **Ke*Xxx*** spin lock routines. + +- Any spin lock used as a parameter to any of the **ExInterlocked*Xxx*** routines. + +While a driver can make calls to the **ExInterlocked*Xxx*** routines from its ISR or [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines, it cannot use any of the **Ke*Xxx*** routines to acquire and release spin locks at any IRQL greater than DISPATCH\_LEVEL. Consequently, any driver that reuses a spin lock between calls to the **Ke*Xxx*SpinLock** and **ExInterlocked*Xxx*** routines must make every call while running at IRQL <= DISPATCH\_LEVEL. + +A driver can pass the same spin lock to **ExInterlockedInsertHeadList** as it does to another **ExInterlocked*Xxx*** routine, as long as both routines use the spin lock at the same IRQL. For more information about how spin lock usage affects performance, see [Using Spin Locks: An Example](using-spin-locks--an-example.md). + +In addition to the storage for its executive spin locks, a device driver must provide the storage for another spin lock to be associated with its interrupt objects if it has a multivector ISR or more than one ISR. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Providing%20Storage%20for%20Spin%20Locks%20and%20Protected%20Data%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/publishing-a-wmi-schema.md b/windows-driver-docs-pr/kernel/publishing-a-wmi-schema.md new file mode 100644 index 0000000000..81d13fd4a7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/publishing-a-wmi-schema.md @@ -0,0 +1,38 @@ +--- +title: Publishing a WMI Schema +author: windows-driver-content +description: Publishing a WMI Schema +ms.assetid: db2b8086-71e4-4532-a0ae-75983691a5a6 +keywords: ["WMI WDK kernel , publishing schema", "publishing WMI schema WDK", "schema publishing WDK WMI", "MOF files WDK WMI", "binary MOF WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Publishing a WMI Schema + + +## + + +To publish a WMI schema, a driver writer first creates a text file in Managed Object Format (MOF) language that contains a class definition for each data block and event block in the schema, as described in [MOF Syntax for WMI Data and Event Blocks](mof-syntax-for-wmi-data-and-event-blocks.md). + +A driver writer can then publish a driver's WMI schema in one of the following ways: + +- Compile the MOF file and include it as a resource in the driver's binary image. For more information, see [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md). + +- Include the compiled MOF file as a resource in a different file, such as a DLL, and add the registry value **MofImagePath** with a path to the file that contains the MOF under the driver's Service key. A schema published in this way can be updated without recompiling the driver. For more information, see [Setting the MofImagePath Registry Value](setting-the-mofimagepath-registry-value.md). + +- Include binary data within the driver and return it when WMI requests it. A schema published in this way can be changed dynamically at runtime. For more information, see [Implementing Dynamic MOF Data](implementing-dynamic-mof-data.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Publishing%20a%20WMI%20Schema%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/queued-spin-locks.md b/windows-driver-docs-pr/kernel/queued-spin-locks.md new file mode 100644 index 0000000000..96f50d2cad --- /dev/null +++ b/windows-driver-docs-pr/kernel/queued-spin-locks.md @@ -0,0 +1,38 @@ +--- +title: Queued Spin Locks +author: windows-driver-content +description: Queued Spin Locks +ms.assetid: 7ccec366-5436-4e69-9fb7-f0090cf2adcb +keywords: ["queued spin locks WDK kernel", "first-come first-served spin locks WDK kernel", "KeAcquireInStackQueuedSpinLock"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Queued Spin Locks + + +## + + +*Queued spin locks* are a variant of spin locks that are more efficient for high contention locks on multiprocessor machines. On multiprocessor machines, using queued spin locks guarantees that processors acquire the spin lock on a first-come first-served basis. Drivers for Windows XP and later versions of Windows should use queued spin locks instead of ordinary spin locks. + +The driver supplies storage for the spin lock, and initializes it with [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160). The driver uses [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) to acquire the queued spin lock, and [**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) to release it. + +The driver allocates a [**KLOCK\_QUEUE\_HANDLE**](https://msdn.microsoft.com/library/windows/hardware/ff554247) structure that it passes by pointer to **KeAcquireInStackQueuedSpinLock**. The driver passes the same structure by pointer to **KeReleaseInStackQueuedSpinLock** when it releases the spin lock. Drivers should normally allocate the structure on the stack each time they acquire the lock. + +Drivers must not mix calls to the queued spin lock routines and the ordinary **Ke*Xxx*SpinLock** routines on the same spin lock. + +If the driver is already at IRQL = DISPATCH\_LEVEL, it can call [**KeAcquireInStackQueuedSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551908) and [**KeReleaseInStackQueuedSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553137) instead. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Queued%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/queuing-and-dequeuing-irps.md b/windows-driver-docs-pr/kernel/queuing-and-dequeuing-irps.md new file mode 100644 index 0000000000..e1d4cf8cea --- /dev/null +++ b/windows-driver-docs-pr/kernel/queuing-and-dequeuing-irps.md @@ -0,0 +1,74 @@ +--- +title: Queuing and Dequeuing IRPs +author: windows-driver-content +description: Queuing and Dequeuing IRPs +ms.assetid: 736107bf-4790-4562-8785-c37fbbed03d3 +keywords: ["IRPs WDK kernel , queuing", "queuing IRPs", "dequeuing IRPs", "multiple I/O request handling WDK kernel", "internal IRP queues WDK kernel", "synchronization WDK IRPs", "starting I/O operations", "I/O WDK kernel , operation starting", "StartIo routines", "cancel-safe IRP queues WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Queuing and Dequeuing IRPs + + +## + + +Because the I/O manager supports asynchronous I/O within a multitasking and multithreaded system, I/O requests to a device can come in faster than its driver can process them to completion, particularly in multiprocessor machines. Consequently, IRPs bound to any particular device must be queued in the driver when its device is already busy processing another IRP. + +Therefore, a lowest-level driver requires one of the following: + +- A [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, which the I/O manager calls to start I/O operations for IRPs the driver has queued to a system-supplied IRP queue (see [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370)). + +- An internal IRP queuing and dequeuing mechanism, which the driver uses to manage IRPs that come in faster than it can satisfy them. Drivers can use device queues, interlocked queues, or cancel-safe queues. For more information, see [Driver-Managed IRP Queues](driver-managed-irp-queues.md). + +Only a lowest-level device driver that can satisfy and complete every possible IRP in its dispatch routines needs no *StartIo* routine and no driver-managed queues for IRPs. + +Higher-level drivers almost never have *StartIo* routines. Most intermediate drivers have neither *StartIo* routines nor internal queues; an intermediate driver can usually pass IRPs with valid parameters on from its dispatch routines and do whatever postprocessing is required for any IRP in its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine. + +The following describes, in general, some of the design considerations for determining whether to implement a *StartIo* routine with or without internal, driver-managed queues for IRPs. + +### StartIo Routines in Drivers + +For computer peripheral devices capable of handling only one device I/O operation at a time, device drivers can implement *StartIo* routines. For these drivers, the I/O manager provides [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) and [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) routines to queue and dequeue IRPs to and from a system-supplied IRP queue. + +For more information about *StartIo* routines, see [Writing a StartIo Routine](writing-a-startio-routine.md). + +### Internal Queues for IRPs in Drivers + +If a device can support more than one concurrent I/O operation, its lowest-level device driver must set up internal request queues and manage its own queuing of IRPs. For example, the system serial driver maintains separate queues for read, write, purge, and wait operations on its devices because it supports full-duplex serial devices. + +A higher-level driver that sends requests to some number of underlying device drivers also might maintain internal queues of IRPs. For example, file system drivers almost always have internal queues for IRPs. + +For more information, see [Driver-Managed IRP Queues](driver-managed-irp-queues.md). + +### Internal Queue Synchronization + +Drivers with device-dedicated threads and highest-level drivers that use executive worker threads (including most file system drivers) usually set up their own queue for IRPs. The queue is shared by the driver thread or driver-supplied worker-thread callback and by other driver routines that process IRPs. + +A driver that implements its own queue structure must ensure that access to the queue is synchronized, and that canceled IRPs are removed from the queue. To make this task simpler for driver writers, cancel-safe IRP queues provide a standard framework you can use when implementing an IRP queue. See [Cancel-Safe IRP Queues](cancel-safe-irp-queues.md) for more information. This is the preferred method for implementing an IRP queue. + +Drivers can also implement all IRP queue synchronization and cancel logic explicitly. For example, a driver could use an interlocked queue. The driver's dispatch routines insert IRPs into the interlocked queue and a driver-created thread or the driver's worker-thread callback removes them by calling the **ExInterlocked*Xxx*List** support routines. + +For example, the system floppy controller driver uses an interlocked queue. Its device-dedicated thread handles the same processing of IRPs that is done by other device drivers' *StartIo* routines and some of the same processing of IRPs that is done by other device drivers' [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routines. + +### Internal Queues with StartIo Routines in Drivers + +A driver that manages its own internal queues can also have a *StartIo* routine, but need not. Most lowest-level device drivers either have a *StartIo* routine or manage their own queuing of IRPs, but not both. + +An exception to this is the SCSI port driver, which has a *StartIo* routine and manages internal queues of IRPs. The I/O manager queues IRPs to the port driver's *StartIo* routine in the device queue associated with the driver-created device object that represents a SCSI HBA. The SCSI port driver also sets up and manages device queues for IRPs to each target device (corresponding to a SCSI logical unit) on any HBA-driven SCSI bus in the machine. + +The SCSI port driver uses its supplemental device queues to hold IRPs sent down from the SCSI class drivers in LU-specific queues whenever any device on a SCSI bus is particularly busy. In effect, this driver's supplemental, LU-specific device queues allow the SCSI port driver to serialize operations for heterogeneous SCSI devices through an HBA while keeping each device on that HBA's SCSI buses as busy as possible. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Queuing%20and%20Dequeuing%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/queuing-i-o-requests-while-a-device-is-sleeping.md b/windows-driver-docs-pr/kernel/queuing-i-o-requests-while-a-device-is-sleeping.md new file mode 100644 index 0000000000..0a4d015197 --- /dev/null +++ b/windows-driver-docs-pr/kernel/queuing-i-o-requests-while-a-device-is-sleeping.md @@ -0,0 +1,32 @@ +--- +title: Queuing I/O Requests While a Device Is Sleeping +author: windows-driver-content +description: Queuing I/O Requests While a Device Is Sleeping +ms.assetid: 8cc0cea0-e5be-4705-ad4d-13a44d536469 +keywords: ["I/O WDK power management", "queuing I/O requests", "sleep power management WDK kernel", "asleep devices WDK power management", "queuing IRPs", "power IRPs WDK kernel , queuing I/O requests", "working state returns WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Queuing I/O Requests While a Device Is Sleeping + + +## + + +While a device is asleep, its drivers should queue any I/O requests directed to the device. The [**IoAllocateWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff548276), [**IoQueueWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549466), and [**IoFreeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549133) support routines provide one way of queuing IRPs for delayed processing. For an example, see the queuing mechanism described for PnP drivers in [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md). + +A driver can access its device only when the device is in the Working (D0) state. A driver cannot touch any device registers when the device is in a sleep state; the device must first be returned to the Working state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Queuing%20I/O%20Requests%20While%20a%20Device%20Is%20Sleeping%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/reader-writer-spin-locks.md b/windows-driver-docs-pr/kernel/reader-writer-spin-locks.md new file mode 100644 index 0000000000..938ab53b39 --- /dev/null +++ b/windows-driver-docs-pr/kernel/reader-writer-spin-locks.md @@ -0,0 +1,45 @@ +--- +title: Reader/Writer Spin Locks +author: windows-driver-content +description: Starting with Windows Vista with Service Pack 1 (SP1), a set of related routines use spin locks to support synchronized access to data structures that are shared by readers and writers. +ms.assetid: E2853F35-590E-4EF5-8647-1261BC4B8D15 +--- + +# Reader/Writer Spin Locks + + +Starting with Windows Vista with Service Pack 1 (SP1), a set of related routines use spin locks to support synchronized access to data structures that are shared by readers and writers. A thread that requires only read access to a data structure can use a spin lock to share this structure with other reader threads. A thread that needs to write to a shared data structure must use the spin lock to obtain exclusive access to the data structure before it can write to this structure. + +If a reader thread needs to acquire a spin lock for shared access, and the lock is already held for exclusive access by a writer thread, the reader must first wait for the writer to release the lock. Similarly, if a writer thread needs to acquire a spin lock for exclusive access, and the lock is already held for shared access by one or more reader threads, the writer thread must wait for all of these reader threads to release the lock. While the writer waits, no new reader threads can acquire the lock. Instead, a reader that needs to acquire the lock that the writer is waiting for must first wait for the writer to acquire and release the lock. + +A thread can switch roles between reader and writer. A thread that already holds a spin lock for shared access can try to convert the access mode of the spin lock from shared mode to exclusive mode. This attempt succeeds if no readers already hold the spin lock for shared access, and if no writer is already waiting to acquire the spin lock for exclusive access. + +Recursive acquisition of a spin lock causes deadlock and is not allowed. + +The following is a list of the routines that are available to manage reader/writer spin locks starting with Windows Vista with SP1. + +| Routine name | Description | +|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| +| [**ExAcquireSpinLockExclusive**](https://msdn.microsoft.com/library/windows/hardware/hh451007) | Acquires a spin lock for exclusive access by the caller, and raises the IRQL to DISPATCH\_LEVEL. | +| [**ExAcquireSpinLockExclusiveAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/hh451009) | Acquires a spin lock for exclusive access by a caller that is already running at IRQL >= DISPATCH\_LEVEL. | +| [**ExAcquireSpinLockShared**](https://msdn.microsoft.com/library/windows/hardware/hh451053) | Acquires a spin lock for shared access by the caller, and raises the IRQL to DISPATCH\_LEVEL. | +| [**ExAcquireSpinLockSharedAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/hh451055) | Acquires a spin lock for shared access by a caller that is already running at IRQL >= DISPATCH\_LEVEL. | +| [**ExReleaseSpinLockExclusive**](https://msdn.microsoft.com/library/windows/hardware/hh451061) | Releases a spin lock that the caller acquired for exclusive access, and restores the original IRQL. | +| [**ExReleaseSpinLockExclusiveFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/hh451058) | Releases a spin lock that the caller acquired for exclusive access, and does not lower the IRQL. | +| [**ExReleaseSpinLockShared**](https://msdn.microsoft.com/library/windows/hardware/hh451067) | Releases a spin lock that the caller acquired for shared access, and restores the original IRQL. | +| [**ExReleaseSpinLockSharedFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/hh451064) | Releases a spin lock that the caller acquired for shared access, and does not lower the IRQL. | +| [**ExTryConvertSharedSpinLockExclusive**](https://msdn.microsoft.com/library/windows/hardware/hh451070) | Tries to convert the access state of a spin lock that the caller already holds for shared access to exclusive access. | + +  + +The reader/writer spin lock routines all take, as their first parameter, a pointer to a spin lock, which is an **EX\_SPIN\_LOCK** structure. This structure is opaque to drivers. A driver should allocate the storage for the spin lock from nonpaged system memory, and initialize the lock to zero. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Reader/Writer%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/reading-data-records-from-a-clfs-stream.md b/windows-driver-docs-pr/kernel/reading-data-records-from-a-clfs-stream.md new file mode 100644 index 0000000000..85e7c5e66c --- /dev/null +++ b/windows-driver-docs-pr/kernel/reading-data-records-from-a-clfs-stream.md @@ -0,0 +1,271 @@ +--- +title: Reading Data Records from a CLFS Stream +author: windows-driver-content +description: Reading Data Records from a CLFS Stream +ms.assetid: 46e583c5-9f12-4f05-8f11-683ac428313a +keywords: ["Common Log File System WDK kernel , data records", "CLFS WDK kernel , data records", "data records WDK CLFS", "reading data records", "read forward WDK CLFS", "forward reading WDK CLFS", "read backward WDK CLFS", "backward reading WDK CLFS", "previous LSNs WDK CLFS", "undo-next LSNs WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading Data Records from a CLFS Stream + + +There are two types of records in a Common Log File System (CLFS) stream: data records and restart records. This topic explains how to read a sequence of data records from a stream. For information about how to read restart records, see [Reading Restart Records from a CLFS Stream](reading-restart-records-from-a-clfs-stream.md). + +There are several variations on reading a sequence of data records from a stream. You can read forward in the stream from a specified record or you can read backward along a chain of linked records. + +For all variations on reading a sequence of data records, complete the following steps. + +1. Call [**ClfsReadLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541682) to obtain a read context and the first data record in the sequence. + +2. Pass the read context you obtained in step 1 to [**ClfsReadNextLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541690) repeatedly to obtain the remaining data records in the sequence. + +**Caution**  Read contexts are not thread-safe. Clients are responsible for serializing access to read contexts. + +  + +The following subtopics discuss the details of reading the different types of record sequences and chains. + +### Reading forward from a specified data record + +To read forward in a CLSF stream (starting at the data record of your choice), you must create a read context that has its mode set to **ClfsContextForward**. To create a read context and read the first record (in the set that you have chosen to read), call **ClfsReadLogRecord** as shown in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

Supply a pointer to a marshalling area.

plsnFirst

Supply the LSN of the first record you want to read. This must be the LSN of a data record, not a restart record.

peContextMode

Supply the value ClfsContextForward.

ppvReadBuffer

Receive your record data.

pcbReadBuffer

Receive the size of your record data.

peRecordType

Receive the record type. This value is a set of flags that indicate various features of the record. The record is a data record, so the value you receive should have the ClfsDataRecord flag set and the ClfsRestartRecord flag clear.

plsnUndoNext

Receive the undo-next LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnPrevious

Receive the previous LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

ppvReadContext

Receive a pointer to an opaque read context. Use the read context to read subsequent records.

+ +  + +After you have obtained the read context and the first record, you can obtain subsequent records in the stream by calling **ClfsReadNextLogRecord** repeatedly. When there are no more data records in the stream, **ClfsReadNextLogRecord** returns STATUS\_END\_OF\_FILE. The following table shows how to set and interpret the parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvReadContext

Supply a pointer to the read context you received from ClfsReadLogRecord.

ppvBuffer

Receive your record data.

pcbBuffer

Receive the size of your record data.

peRecordType

Supply the value of ClfsDataRecord.

plsnUndoNext

Receive the undo-next LSN field of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnPrevious

Receive the previous-LSN field of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnRecord

Receive the LSN of the data record that was read.

+ +  + +### Reading a chain of data records linked by the previous LSN + +When you write a data record to a CLFS stream, you can set the previous LSN of the data record to the LSN of any record that you previously wrote to the stream. By setting the previous LSN, you can create a chain of related records that can later be traversed in reverse order. For example, suppose you are performing a database transaction and you must write several CLFS log records to describe the updates made by the transaction. Each time you write a log record that describes a transaction update, you could set the previous LSN of the record to the LSN of the previous log record that describes an update made by the same transaction. + +Suppose you have written a chain of data records that are linked by their previous LSNs. To read the chain of records, you must create a read context that has its mode set to **ClfsContextPrevious**. To create a read context and read the first record in the chain, call **ClfsReadLogRecord** as shown in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

Supply a pointer to a marshalling area.

plsnFirst

Supply the LSN of the first record in the chain. This must be the LSN of a data record, not a restart record.

peContextMode

Supply the value of ClfsContextPrevious.

ppvReadBuffer

Receive your record data.

pcbReadBuffer

Receive the size of your record data.

peRecordType

Receive the record type. This value is a set of flags that indicate various features of the record. The record is a data record, so the value you receive should have the ClfsDataRecord flag set and the ClfsRestartRecord flag clear.

plsnUndoNext

Receive the undo-next LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnPrevious

Receive the previous LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

ppvReadContext

Receive a pointer to an opaque read context. Use the read context to read the previous records in the chain.

+ +  + +After you have the read context and the first record, you can read the remaining records in the chain by calling **ClfsReadNextLogRecord** repeatedly. The following table shows how to set and interpret the parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvReadContext

Supply a pointer to the read context you received from ClfsReadLogRecord.

ppvBuffer

Receive your record data.

pcbBuffer

Receive the size of your record data.

peRecordType

Supply the value of ClfsDataRecord.

plsnUndoNext

Receive the undo-next LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnPrevious

Receive the previous LSN of the data record. You do not need this value to continue reading the chain, so you can ignore it.

plsnRecord

Receive the LSN of the data record that was read.

+ +  + +As you make repeated calls to **ClfsReadNextLogRecord**, your sequence of calls will end in one of the following ways. + +- Eventually you will read a data record that has its previous LSN set to CLFS\_LSN\_INVALID. The next time you call **ClfsReadNextLogRecord**, it will return STATUS\_END\_OF\_FILE. + +- Eventually you will read a data record that has a previous LSN that is less than both the base LSN of the stream and the [*archive tail*](clfs-terminology.md#kernel-clfs-term-archive-tail) of the stream. The next time you call **ClfsReadNextLogRecord**, it will return STATUS\_LOG\_START\_OF\_LOG. + +### Reading a chain of data records linked by the undo-next LSN + +When you write a data record to a CLFS stream, you can set the undo-next LSN of the data record to the LSN of any record that you previously wrote to the stream. By setting the undo-next LSN, you can create a chain of related records that can be traversed in reverse order. For more information about creating and interpreting undo-next chains, see [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md). + +Suppose you have written a chain of data records that are linked by their undo-next LSNs. To read the chain of records, you must call [**ClfsReadLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541682) to create a read context that has its mode set to **ClfsContextUndoNext**. After that, the process is identical to reading a chain linked by previous LSNs (described previously in this topic). + +### Reading a chain of data records linked by the user LSN + +In addition to chains linked by previous LSNs and undo-next LSNs, you can create chains linked by your own LSNs that you embed in your record data. + +Suppose you have written a chain of data records that are linked by LSNs you have stored in the record data itself. To read the chain of records, you must create a read context that has its mode set to either **ClfsContextPrevious** or **ClfsContextUndoNext**. Create your read context and obtain the most recently written record in the chain by calling [**ClfsReadLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541682). Then call [**ClfsReadNextLogRecord**](https://msdn.microsoft.com/library/windows/hardware/ff541690) repeatedly to obtain the previous records in the chain. Each time you call **ClfsReadNextLogRecord**, set the *plsnUser* parameter to the LSN of the previous record in your chain. The LSN you supply in *plsnUser* overrides any values stored in the current record's previous-LSN or undo-next LSN fields. + +Note that you can only move backward in the stream when you call **ClfsReadNextLogRecord** to read a record chain. The LSN you supply in *plsnUser* must be less than the LSN of the current record in the chain. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Reading%20Data%20Records%20from%20a%20CLFS%20Stream%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/reading-restart-records-from-a-clfs-stream.md b/windows-driver-docs-pr/kernel/reading-restart-records-from-a-clfs-stream.md new file mode 100644 index 0000000000..2ef8633bc6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/reading-restart-records-from-a-clfs-stream.md @@ -0,0 +1,38 @@ +--- +title: Reading Restart Records from a CLFS Stream +author: windows-driver-content +description: Reading Restart Records from a CLFS Stream +ms.assetid: 310545f6-d10d-481e-829d-287b045b98cd +keywords: ["Common Log File System WDK kernel , restart records", "CLFS WDK kernel , restart records", "restart records WDK CLFS", "reading restart records"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reading Restart Records from a CLFS Stream + + +## + + +To read all of the restart records in a Common Log File System (CLFS) stream (in reverse order), use the following procedure. + +1. Call [**ClfsReadRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541709) to obtain a read context and the restart record that was most recently written to the stream. + +2. Pass the read context you obtained in step 1 to [**ClfsReadPreviousRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541699) repeatedly to obtain the remaining restart records in the log. + +**Note**  When you call [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770) to write a restart record to a stream, CLFS automatically sets the previous LSN of that record to the LSN of the previous restart record in the stream. Those previous LSNs form the chain that is followed by repeated calls to **ClfsReadPreviousRestartArea**. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Reading%20Restart%20Records%20from%20a%20CLFS%20Stream%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/receiving-a-wait-wake-irp.md b/windows-driver-docs-pr/kernel/receiving-a-wait-wake-irp.md new file mode 100644 index 0000000000..b9ab9eb7d2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/receiving-a-wait-wake-irp.md @@ -0,0 +1,32 @@ +--- +title: Receiving a Wait/Wake IRP +author: windows-driver-content +description: Receiving a Wait/Wake IRP +ms.assetid: 88fa7189-4897-484a-9cf4-b35e56e99d61 +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "receiving wait/wake IRPs", "wait/wake IRPs WDK power management , receiving"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Receiving a Wait/Wake IRP + + +## + + +All PnP drivers must be prepared to receive power IRPs with minor IRP code [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766). How a driver handles a wait/wake IRP depends on its position in the device stack, the type of device(s) it controls, and the specific states from which its device supports wake-up. + +The topics in this section provide guidelines for handling this IRP based on the type of driver and its level of wait/wake support. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Receiving%20a%20Wait/Wake%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-a-cancel-routine.md b/windows-driver-docs-pr/kernel/registering-a-cancel-routine.md new file mode 100644 index 0000000000..8f948ef87c --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-a-cancel-routine.md @@ -0,0 +1,42 @@ +--- +title: Registering a Cancel Routine +author: windows-driver-content +description: Registering a Cancel Routine +ms.assetid: ebc63fb6-bf4d-4de3-9232-08d810c2f730 +keywords: ["canceling IRPs, registering Cancel routines", "Cancel routines, registering", "registering Cancel routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering a Cancel Routine + + +## + + +If a device driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, its dispatch routines can register a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine by supplying its address as input to [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370). + +If a driver does not have a *StartIo* routine, its dispatch routines must do the following before queuing an IRP for further processing by other driver routines: + +1. Call [**IoAcquireCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff548196). + +2. Call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) with the input IRP and the entry point for a driver-supplied *Cancel* routine. + +3. Call [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550). + +For information about the cancel spin lock, see [Using the System's Cancel Spin Lock](using-the-system-s-cancel-spin-lock.md). + +Drivers that manage their own queues of IRPs, rather than using the I/O manager-supplied device queue, do not need to acquire the cancel spin lock when calling **IoSetCancelRoutine**. However, these drivers should check the *Cancel* routine pointer that **IoSetCancelRoutine** returns to determine whether the *Cancel* routine has already started. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20a%20Cancel%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-an-iocompletion-routine.md b/windows-driver-docs-pr/kernel/registering-an-iocompletion-routine.md new file mode 100644 index 0000000000..aa8adb8fc6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-an-iocompletion-routine.md @@ -0,0 +1,74 @@ +--- +title: Registering an IoCompletion Routine +author: windows-driver-content +description: Registering an IoCompletion Routine +ms.assetid: 413d8463-b2ce-44b6-846c-f853b5cd580e +keywords: ["IoCompletion routines", "registering IoCompletion routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering an IoCompletion Routine + + +## + + +To register an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, a dispatch routine calls [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679), supplying the *IoCompletion* routine's address and the IRP that it will subsequently pass on to lower drivers using [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +When it calls **IoSetCompletionRoutine**, the dispatch routine specifies the circumstances in which the I/O manager should call the specified *IoCompletion* routine. You can choose to have the *IoCompletion* routine called if a lower level driver completes the IRP successfully (*InvokeOnSuccess*), completes the IRP with an error status value (*InvokeOnError*), or cancels the IRP (*InvokeOnCancel*), in any combination. + +The purpose of an *IoCompletion* routine is to monitor what lower-level drivers did with the IRP and to do additional completion processing, if necessary. Specifically, the most common uses for a driver's *IoCompletion* routines are the following: + +- To dispose of an IRP that the driver allocated with [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) or [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310) + + Any higher-level driver that allocates an IRP using either of these support routines must supply an *IoCompletion* routine for that IRP. The *IoCompletion* routine must call [**IoFreeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549113) to dispose of driver-allocated IRPs. + +- To reuse an incoming IRP to request that lower drivers complete some number of operations, such as partial transfers, until the original request can be satisfied and completed by the *IoCompletion* routine + +- To retry a request that a lower driver completed with an error + + Highest-level drivers, such as file systems, are more likely to have *IoCompletion* routines that attempt to retry requests than are intermediate drivers, except possibly class drivers layered above a closely coupled port driver. However, any intermediate driver use *IoCompletion* routines to retry requests. + +While a highest-level or intermediate driver's [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine is most likely to process IRPs that require an *IoCompletion* routine, any dispatch routine in any driver that passes IRPs on to lower drivers can register an *IoCompletion* routine. + +For driver-allocated IRPs and reused IRPs, the dispatch routine must call **IoSetCompletionRoutine** with the following Boolean parameters: + +- *InvokeOnSuccess* set to **TRUE** + +- *InvokeOnError* set to **TRUE** + +- *InvokeOnCancel* set to **TRUE** if any lower driver in the chain might handle cancelable IRPs + + Usually, *InvokeOnCancel* is set to **TRUE**, regardless of whether an IRP might be returned with STATUS\_CANCELLED, to ensure that the *IoCompletion* routine frees each driver-allocated IRP or checks the completion status of each reuse of an IRP. + +A dispatch routine that allocates IRPs for lower drivers using **IoAllocateIrp** or [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310)must set an *IoCompletion* routine for each driver-allocated IRP. + +- The dispatch routine must set up state about both the original IRP and its allocated IRP(s) for the *IoCompletion* routine to use. At a minimum, the *IoCompletion* routine needs access to the original IRP and a count of how many additional IRPs were allocated. + +- The dispatch routine should call **IoSetCompletionRoutine** with all *InvokeOnXxx* parameters set to **TRUE** for the IRP(s) it allocates. + +A dispatch routine that reuses IRPs for a sequence of operations, or that retries I/O operation, must call **IoSetCompletionRoutine** for each IRP that will be reused or retried. + +- The dispatch routine must save the original IRP's state information, for subsequent use by the *IoCompletion* routine. + + For example, a [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine must save the relevant transfer parameters of an input IRP for the *IoCompletion* routine before setting up a partial transfer for the next-lower driver in that IRP. Saving the parameters is particularly important if the *DispatchReadWrite* routine modifies any parameters that the *IoCompletion* routine needs to determine when the original request has been satisfied. + +- If the *IoCompletion* routine can retry the request, the dispatch routine must set up a driver-determined upper limit for the number of retries its *IoCompletion* routine should attempt before it completes the original IRP with an error. + +- If an IRP is to be reused, the dispatch routine should call **IoSetCompletionRoutine** with all *InvokeOnXxx* parameters set to **TRUE**. + +- For an asynchronous request, the dispatch routine of any intermediate driver must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) for the original IRP. It must then return STATUS\_PENDING after it has sent the IRP on to lower drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20an%20IoCompletion%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-an-isr.md b/windows-driver-docs-pr/kernel/registering-an-isr.md new file mode 100644 index 0000000000..de71cc6f18 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-an-isr.md @@ -0,0 +1,37 @@ +--- +title: Registering an ISR +author: windows-driver-content +description: Registering an ISR +ms.assetid: 903e5664-2193-4456-b133-bb979d700bdf +keywords: ["interrupt service routines WDK kernel , registering ISRs", "interrupt objects WDK kernel , registering ISRs", "ISRs WDK kernel , registering ISRs", "registering ISRs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering an ISR + + +Drivers use the [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) routine to register an ISR for an interrupt. **IoConnectInterruptEx** is part of Windows Vista and later operating systems. **IoConnectInterruptEx** takes a single *Parameters* parameter, which is a pointer to an [**IO\_CONNECT\_INTERRUPT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff550541) structure. For Windows Server 2003, Windows XP, and Windows 2000, drivers can use the Iointex.lib library that is included in the Windows Driver Kit (WDK). + +On Windows Vista and later, **IoConnectInterruptEx** provides several different methods for registering an ISR. The value specified for *Parameters*->**Version** determines the method, as follows: + +- Use CONNECT\_LINE\_BASED to register an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine for all of a device's line-based interrupts. (Devices usually have at most one line-based interrupt.) The system automatically detects any line-based interrupts assigned to the device. For more information, see [Using the CONNECT\_LINE\_BASED Version of IoConnectInterruptEx](using-the-connect-line-based-version-of-ioconnectinterruptex.md). + +- Use CONNECT\_MESSAGE\_BASED to register an [*InterruptMessageService*](https://msdn.microsoft.com/library/windows/hardware/ff547940) routine for all of a device's message-signaled interrupts. You can also specify a fallback [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine—if the device only has line-based interrupts, **IoConnectInterruptEx** registers the *InterruptService* routine instead. The system automatically detects any message-signaled interrupts assigned to the device. For more information, see [Using the CONNECT\_MESSAGE\_BASED Version of IoConnectInterruptEx](using-the-connect-message-based-version-of-ioconnectinterruptex.md). + +- Use CONNECT\_FULLY\_SPECIFIED to register an *InterruptService* routine for each interrupt separately. You can use this to specify an *InterruptService* routine for either a line-based or a message-signaled interrupt, but you must manually specify the interrupt using information passed by the PnP manager. For more information, see [Using the CONNECT\_FULLY\_SPECIFIED Version of IoConnectInterruptEx](using-the-connect-fully-specified-version-of-ioconnectinterruptex.md). + +On operating systems prior to Windows Vista, you can only use CONNECT\_FULLY\_SPECIFIED. If you specify CONNECT\_LINE\_BASED or CONNECT\_MESSAGE\_BASED, **IoConnectInterruptEx** returns an error. You can use this behavior to determine if you are running on Windows Vista or an earlier system. For more information, see [Using IoConnectInterruptEx Prior to Windows Vista](using-ioconnectinterruptex-prior-to-windows-vista.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20an%20ISR%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-and-enabling-an-iotimer-routine.md b/windows-driver-docs-pr/kernel/registering-and-enabling-an-iotimer-routine.md new file mode 100644 index 0000000000..be3e32f773 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-and-enabling-an-iotimer-routine.md @@ -0,0 +1,42 @@ +--- +title: Registering and Enabling an IoTimer Routine +author: windows-driver-content +description: Registering and Enabling an IoTimer Routine +ms.assetid: d06a6430-5098-492a-8114-d6f390083718 +keywords: ["IoTimer", "IoInitializeTimer", "IoStartTimer", "registering IoTimer routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering and Enabling an IoTimer Routine + + +## + + +Any driver can register an [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine, after it creates one or more device objects, by calling [**IoInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff549344). The driver can then start the timer by calling [**IoStartTimer**](https://msdn.microsoft.com/library/windows/hardware/ff550373). The following figure illustrates these calls. + +![diagram illustrating using an iotimer routine](images/3iotmer.png) + +After calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) to create device objects, a driver can call **IoInitializeTimer** with the entry point of its *IoTimer* routine, along with pointers to a driver-created device object and a context area in which the driver maintains whatever context its *IoTimer* routine uses. The I/O manager associates the device object with a kernel-allocated timer object and sets up the timer object to time out every second. + +After the driver calls **IoStartTimer**, its *IoTimer* routine is called once per second until the driver calls [**IoStopTimer**](https://msdn.microsoft.com/library/windows/hardware/ff550377). A driver can reenable calls to its *IoTimer* routine with **IoStartTimer**. (Frequently, when a driver calls **IoStartTimer**, it supplies the device object pointer obtained from the I/O stack location of the current IRP.) + +On entry, the *IoTimer* routine is passed the device object pointer*,* along with the context pointer that the driver supplied when it called **IoInitializeTimer**. + +Drivers must not call **IoStopTimer** from within an *IoTimer* routine. + +The I/O manager unregisters the timer routine for a specified device object and frees its associated context when the driver calls [**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20and%20Enabling%20an%20IoTimer%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-and-queuing-a-customdpc-routine.md b/windows-driver-docs-pr/kernel/registering-and-queuing-a-customdpc-routine.md new file mode 100644 index 0000000000..92a79785b6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-and-queuing-a-customdpc-routine.md @@ -0,0 +1,48 @@ +--- +title: Registering and Queuing a CustomDpc Routine +author: windows-driver-content +description: Registering and Queuing a CustomDpc Routine +ms.assetid: 7c35f8f8-a6dc-43b1-9120-701227d7b4c5 +keywords: ["CustomDpc", "registering CustomDpc routine", "queuing CustomDpc routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering and Queuing a CustomDpc Routine + + +## + + +A driver registers a [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine for a device object by calling [**KeInitializeDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552130) after it has created the device object. The driver can make this call from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, or from [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) code that handles [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) requests. + +Just before the driver's ISR returns control, it can call [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185) to queue the *CustomDpc* routine for execution. The following figure illustrates calls to these routines. + +![diagram illustrating using a dpc object for a customdpc routine](images/3cstmdpc.png) + +As the previous figure shows, a driver that has a *CustomDpc* routine must provide the storage for a DPC object. Because the driver must pass a pointer to the DPC object from its ISR, the storage must be in resident, system-space memory. Most drivers with *CustomDpc* routines provide storage for their DPC objects in the device extension, but the storage can be in a controller extension if the driver uses a [controller object](using-controller-objects.md) or in nonpaged pool allocated by the driver. + +When the driver calls **KeInitializeDpc**, it must pass the entry point for its *CustomDpc* routine, along with pointers to the driver-allocated storage for the DPC object and to a driver-defined context area, which is passed to the *CustomDpc* routine when it is called. Because the context area must be accessible at IRQL = DISPATCH\_LEVEL, it also must be in resident memory. + +Unlike a *DpcForIsr* routine, a *CustomDpc* routine is not associated with a device object. Nevertheless, drivers typically include pointers to the target device object and current IRP in the context information supplied to the *CustomDpc* routine. Like a *DpcForIsr* routine, the *CustomDpc* routine uses this information to complete an interrupt-driven I/O operation at a lower IRQL than the ISR. + +As the previous figure shows, the ISR passes pointers to the DPC object and to two additional parameters, which are driver-defined, to [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185). If all processors in the machine currently have code running at an IRQL greater than or equal to DISPATCH\_LEVEL, the DPC object is queued until the IRQL falls below DISPATCH\_LEVEL on a processor. Then, the kernel dequeues the DPC object and the driver's *CustomDpc* routine is run on the processor at IRQL DISPATCH\_LEVEL. + +Only a single instantiation of any one DPC object can be queued at any given moment. Thus if an ISR calls **KeInsertQueueDpc** more than once with the same *Dpc* pointer before the driver's *CustomDpc* routine is run, the *CustomDpc* routine runs only once after IRQL falls below DISPATCH\_LEVEL on a processor. + +A *CustomDpc* routine is responsible for doing whatever is necessary to complete the I/O operation that caused the interrupt. + +The ISR and *CustomDpc* routines can be run concurrently on an SMP machine. Therefore, when writing *CustomDpc* routines, follow the guidelines set out in the previous section, [Registering and Queuing a DpcForIsr Routine](registering-and-queuing-a-dpcforisr-routine.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20and%20Queuing%20a%20CustomDpc%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-and-queuing-a-customtimerdpc-routine.md b/windows-driver-docs-pr/kernel/registering-and-queuing-a-customtimerdpc-routine.md new file mode 100644 index 0000000000..5f6e9a0000 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-and-queuing-a-customtimerdpc-routine.md @@ -0,0 +1,64 @@ +--- +title: Registering and Queuing a CustomTimerDpc Routine +author: windows-driver-content +description: Registering and Queuing a CustomTimerDpc Routine +ms.assetid: 884bff8e-8437-44fb-acc0-f535d64ce900 +keywords: ["timer objects WDK kernel , CustomTimerDpc routines", "CustomTimerDpc", "queuing timer objects", "registering timer objects", "KeSetTimer", "KeSetTimerEx", "KeInitializeTimer", "KeInitializeTimerEx", "invoking CustomTimerDpc routine repeatedly", "repeatedly invoke CustomTimerDpc routine", "DueTime values", "timer expirations WDK kernel", "expired timers WDK kernel", "timer objects WDK kernel , queuing", "timer objects WDK kernel , registering", "timer objects WDK kernel , expirations"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering and Queuing a CustomTimerDpc Routine + + +## + + +A driver can register a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine by calling the following routines, usually from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine: + +1. [**KeInitializeDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552130) to register its routine + +2. [**KeInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff552168) or [**KeInitializeTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff552173) to set up a timer object + +Subsequently, the driver can call [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) or [**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292) to specify an expiration time and to add the timer object to the system's timer queue. When the expiration time is reached, the system dequeues the timer object and calls the *CustomTimerDpc* routine. The following figure illustrates these calls. + +![diagram illustrating using timer and dpc objects for a customtimerdpc routine](images/3ketmdpc.png) + +As the previous figure shows, the driver must supply storage for both a DPC object and a timer object. Most drivers provide the storage for these objects in a [device extension](device-extensions.md) or in other driver-allocated, resident memory. + +In the call to **KeSetTimer**, the driver passes pointers to the *Dpc* and *Timer* objects, along with a *DueTime* expressed in units of 100 nanoseconds, as shown in the previous figure. A positive value for *DueTime* specifies an *absolute expiration time* (since January 1, 1601) at which the *CustomTimerDpc* routine should be called. A negative value for *DueTime* specifies a *relative expiration time*. + +Because an absolute timer expires at a specific system time, the wait duration of an absolute timer is not affected if the system time changes before the timer expires. On the other hand, a relative timer always expires after the specified number of time units elapses, regardless of changes to the absolute system time. + +To invoke a *CustomTimerDpc* routine repeatedly, use **KeSetTimerEx** to set the timer and specify a recurring interval in the *Period* parameter. **KeSetTimerEx** is just like **KeSetTimer** except for this additional parameter. + +As shown in the previous figure, the call to **KeSetTimer** or **KeSetTimerEx** queues the timer object for a specified interval as follows: + +1. When the *DueTime* expires, the timer object is dequeued and set to the Signaled state. + +2. If every processor in the machine is currently running code at an IRQL greater than or equal to DISPATCH\_LEVEL, the DPC object associated with the timer object is put in a DPC queue. Otherwise, the *CustomTimerDpc* routine is called. + +3. If the DPC object was already in the queue when the *DueTime* interval expired, the *CustomTimerDpc* routine is called as soon as the IRQL on any processor in the machine falls below DISPATCH\_LEVEL. + + **Note**  The *CustomTimerDpc* routine, like all DPC routines, is called at IRQL = DISPATCH\_LEVEL. While a DPC routine runs, all threads are prevented from running on the same processor. Driver developers should carefully design their *CustomTimerDpc* routines to run for as brief a time as possible. + +   + +The smallest time interval that can be specified to **KeSetTimer** and **KeSetTimerEx** is approximately ten milliseconds, so a driver can use a *CustomTimerDpc* routine when timing smaller intervals than an [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine, which is run once per second, can handle. + +Only one instantiation of a particular timer object can be queued at any moment. Calling **KeSetTimer** or **KeSetTimerEx** again with the same *Timer* object pointer cancels the queued timer object and resets it. + +Setting up a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine is exactly like setting up a [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine, with an additional step to initialize the timer object. In fact, their prototypes are identical, but *CustomTimerDpc* routine cannot use the two *SystemArgument* pointers declared in its prototype. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20and%20Queuing%20a%20CustomTimerDpc%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-and-queuing-a-dpcforisr-routine.md b/windows-driver-docs-pr/kernel/registering-and-queuing-a-dpcforisr-routine.md new file mode 100644 index 0000000000..dcc42059a2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-and-queuing-a-dpcforisr-routine.md @@ -0,0 +1,54 @@ +--- +title: Registering and Queuing a DpcForIsr Routine +author: windows-driver-content +description: Registering and Queuing a DpcForIsr Routine +ms.assetid: 32253573-842e-40bc-9616-8d1ccd7afa29 +keywords: ["DpcForIsr", "registering DpcForIsr routine", "queuing DpcForIsr routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering and Queuing a DpcForIsr Routine + + +## + + +A driver registers a [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine for a device object by calling [**IoInitializeDpcRequest**](https://msdn.microsoft.com/library/windows/hardware/ff549307) after it has created the device object. The driver can make this call from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, or from [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) code that handles [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) requests. + +To queue the *DpcForIsr* routine for execution, the driver's ISR calls [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) just before it returns. The following figure illustrates calls to these routines. + +![diagram illustrating using a dpc object for a dpcforisr routine](images/3dpcisr.png) + +As the previous figure shows, calling **IoInitializeDpcRequest** associates a DPC object with a driver-supplied *DpcForIsr* routine and a driver-created device object. The I/O manager allocates memory for the DPC object and calls [**KeInitializeDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552130) on the driver's behalf. + +When the ISR is called to handle a device interrupt at DIRQL, it should return control to the system as soon as possible for better overall system and driver performance. Usually, an ISR merely clears the interrupt, gathers whatever context information the *DpcForIsr* routine needs to complete the operation that caused the interrupt, calls [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657), and returns. + +When the ISR calls **IoRequestDpc**, it passes a pointer to the device object, a pointer to the *DeviceObject*->**CurrentIrp**, and a pointer to a driver-determined context. The I/O manager calls [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185) on the driver's behalf, which queues the DPC object. When IRQL falls below DISPATCH\_LEVEL on a processor, the kernel dequeues the DPC object and runs the driver's *DpcForIsr* routine on that processor at IRQL DISPATCH\_LEVEL. + +The *DpcForIsr* routine is responsible for doing whatever is necessary to complete the I/O requested in the current IRP. On entry, the routine receives a pointer to the DPC object, along with pointers to the device object, IRP, and context area, which were passed in the ISR's call to **IoRequestDpc**. The context area must be in resident memory, and is usually in the device extension. Alternatively, it can be in nonpaged pool allocated by the driver, or in a controller extension if the driver uses a [controller object](using-controller-objects.md). + +Because ISR and *DpcForIsr* routines can run concurrently on SMP machines, you must follow these guidelines: + +- The ISR must call **IoRequestDpc** just before it returns control. Otherwise, the *DpcForIsr* routine might be run on another processor before the ISR has finished setting up the context area for the *DpcForIsr* routine. + +- The *DpcForIsr* routine and any other driver routine that shares a context area with the ISR must call [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302), specifying a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that accesses the shared context area in a multiprocessor-safe manner. + +- If a driver uses the device extension to maintain context about its device I/O operations, the *DpcForIsr* routine should never call [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) for the input device object (nor dequeue an IRP for the input device object, if the driver manages its own IRP queuing) until just before it calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + Otherwise, the driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) (or queue-management routines) might start another I/O operation that overwrites the shared context area before the *DpcForIsr* routine can complete the current operation. This is because the ISR can be called again if the device interrupts while or before the *DpcForIsr* routine executes (assuming interrupts are still enabled). + +Even on a uniprocessor machine, the ISR could be called again if the device interrupts while or before the *DpcForIsr* routine is run. If this occurs, the *DpcForIsr* routine is run only once. In other words, there is no one-to-one correspondence between an ISR's calls to **IoRequestDpc** and instantiations of the *DpcForIsr* routine if a driver overlaps I/O operations for its target device objects. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20and%20Queuing%20a%20DpcForIsr%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-as-a-source-of-error-messages.md b/windows-driver-docs-pr/kernel/registering-as-a-source-of-error-messages.md new file mode 100644 index 0000000000..b6df62c06f --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-as-a-source-of-error-messages.md @@ -0,0 +1,38 @@ +--- +title: Registering as a Source of Error Messages +author: windows-driver-content +description: Registering as a Source of Error Messages +ms.assetid: 5428950c-9c28-411a-9ec0-b029ad311a00 +keywords: ["source registration WDK errors", "errors WDK kernel", "registering error message sources", "registry WDK error logs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering as a Source of Error Messages + + +## + + +Drivers register the source of error messages in the registry. Drivers must set two keys under **HKEY\_LOCAL\_MACHINE\\System\\CurrentControlSet\\Services\\EventLog\\System\\***DriverName*: + +**EventMessageFile** (REG\_EXPAND\_SZ) +A list of error message sources separated by semicolons. If the driver uses standard error types, this list must include iologmsg.dll. If the driver uses error messages attached to the driver image, this must include the name of the driver image. + +**TypesSupported** (REG\_DWORD) +A bitmask of the possible severity levels that can be logged. Drivers typically set this to 7 to indicate they may log all severity levels. + +For a description of how to set these registry keys from the driver's INF file, see [**Registering for Event Logging**](https://msdn.microsoft.com/library/windows/hardware/ff546326). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20as%20a%20Source%20of%20Error%20Messages%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-as-a-wmi-data-provider.md b/windows-driver-docs-pr/kernel/registering-as-a-wmi-data-provider.md new file mode 100644 index 0000000000..7fe37eee57 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-as-a-wmi-data-provider.md @@ -0,0 +1,36 @@ +--- +title: Registering as a WMI Data Provider +author: windows-driver-content +description: Registering as a WMI Data Provider +ms.assetid: a08fed24-20b6-46aa-9a52-7a22f0e89ce4 +keywords: ["WMI WDK kernel , registering with WMI", "registering WMI data providers", "data providers WDK WMI", "driver registrations WDK WMI", "event blocks WDK WMI", "blocks WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering as a WMI Data Provider + + +## + + +A driver that supports WMI must register as a WMI data provider to make its data and event blocks available to WMI clients. A driver typically registers with WMI when starting its device, after the device has been initialized to the point that the driver can handle WMI IRPs. During the registration process, the driver passes WMI a pointer to its device object and information about the data and event blocks it supports. + +A driver registers with WMI in two phases: + +1. The driver calls [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) with the action WMIREG\_ACTION\_REGISTER and a pointer to the device object passed to the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +2. The driver handles the [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request that WMI sends in response to the driver's **IoWMIRegistrationControl** call. The **Parameters.WMI.DataPath** member of the IRP is set to WMIREGISTER and **Parameters.WMI.ProviderId** is set to the driver's device object pointer. The driver supplies WMI with registration information about its data and event blocks, either by using the WMI Library as described in [Using the WMI Library to Register Blocks](using-the-wmi-library-to-register-blocks.md), or by handling the **IRP\_MN\_REGINFO** or **IRP\_MN\_REGINFO\_EX** requests as described in [Handling IRP\_MN\_REGINFO and IRP\_MN\_REGINFO\_EX to Register Blocks](handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20as%20a%20WMI%20Data%20Provider%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-application-notification.md b/windows-driver-docs-pr/kernel/registering-for-application-notification.md new file mode 100644 index 0000000000..349e2b02b0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-application-notification.md @@ -0,0 +1,109 @@ +--- +title: Registering for Application Notification +author: windows-driver-content +description: Registering for Application Notification +ms.assetid: e8f76014-6068-4012-96c6-88ea2bbd9bbf +keywords: ["dynamic hardware partitioning WDK , application notification", "hardware partitioning WDK dynamic , application notification", "partitions WDK dynamic hardware , application notification", "application notification WDK dynamic hardware partitioning , registering", "notification WDK dynamic hardware partitioning , application", "registering for application notifications WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Application Notification + + +A user-mode application calls the [RegisterDeviceNotification](http://go.microsoft.com/fwlink/p/?linkid=97892) function to register itself to be notified when a processor or memory module is dynamically added to the hardware partition. An application calls the **RegisterDeviceNotification** function two times, one time to register for notification of processor events and a second time to register for notification of memory events. The application specifies one of the following GUIDs when it registers for notification of these events: + +GUID\_DEVICE\_PROCESSOR +Registers the application to be notified when a processor is dynamically added to the hardware partition. + +GUID\_DEVICE\_MEMORY +Registers the application to be notified when memory is dynamically added to the hardware partition. + +These GUIDs are defined in the header file, Poclass.h. + +The following code example shows how to register for both notifications: + +``` +HWND hWnd; +DEV_BROADCAST_DEVICEINTERFACE ProcessorFilter; +DEV_BROADCAST_DEVICEINTERFACE MemoryFilter; +HDEVNOTIFY ProcessorNotifyHandle; +HDEVNOTIFY MemoryNotifyHandle; + +// The following example assumes that hWnd already +// contains a handle to the application window that +// is to receive the WM_DEVICECHANGE messages. + +// Initialize the filter for processor event notification +ZeroMemory( + &ProcessorFilter, + sizeof(ProcessorFilter) + ); +ProcessorFilter.dbcc_size = + sizeof(DEV_BROADCAST_DEVICEINTERFACE); +ProcessorFilter.dbcc_devicetype = + DBT_DEVTYP_DEVICEINTERFACE; +ProcessorFilter.dbcc_classguid = + GUID_DEVICE_PROCESSOR; + +// Register the application window to receive +// WM_DEVICECHANGE messages for processor events. +ProcessorNotifyHandle = + RegisterDeviceNotification( + hWnd, + &ProcessorFilter, + DEVICE_NOTIFY_WINDOW_HANDLE + ); + +// Initialize the filter for memory event notification +ZeroMemory( + &MemoryFilter, + sizeof(MemoryFilter) + ); +MemoryFilter.dbcc_size = + sizeof(DEV_BROADCAST_DEVICEINTERFACE); +MemoryFilter.dbcc_devicetype = + DBT_DEVTYP_DEVICEINTERFACE; +MemoryFilter.dbcc_classguid = + GUID_DEVICE_MEMORY; + +// Register the application's window to receive +// WM_DEVICECHANGE messages for memory events. +MemoryNotifyHandle = + RegisterDeviceNotification( + hWnd, + &MemoryFilter, + DEVICE_NOTIFY_WINDOW_HANDLE + ); +``` + +**Note**   If an application only has to be notified about processors, it does not have to register for notification of memory events. Similarly, if an application only has to be notified about memory, it does not have to register for notification of processor events. + +  + +When an application no longer has to receive notification of processor or memory events, it can unregister the window from receiving WM\_DEVICECHANGE messages for these events by calling the [UnregisterDeviceNotification](http://go.microsoft.com/fwlink/p/?linkid=97893) function. The following code example shows how to unregister for the application notifications: + +``` +// Unregister the application window from receiving +// WM_DEVICECHANGE messages for processor events. +UnregisterDeviceNotification(ProcessorNotifyHandle); + +// Unregister the application window from receiving +// WM_DEVICECHANGE messages for memory events. +UnregisterDeviceNotification(MemoryNotifyHandle); +``` + +For more information about the **RegisterDeviceNotification** and **UnregisterDeviceNotification** functions, see the Microsoft Windows SDK documentation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Application%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-asynchronous-driver-notification.md b/windows-driver-docs-pr/kernel/registering-for-asynchronous-driver-notification.md new file mode 100644 index 0000000000..343bbb2f7f --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-asynchronous-driver-notification.md @@ -0,0 +1,102 @@ +--- +title: Registering for Asynchronous Driver Notification +author: windows-driver-content +description: Registering for Asynchronous Driver Notification +ms.assetid: e1f97a65-7c82-4d7b-97ec-0293fc69fd8c +keywords: ["driver notification WDK dynamic hardware partitioning , registering", "asynchronous notification WDK dynamic hardware partitioning", "notification WDK dynamic hardware partitioning , registering", "asynchronous driver notification WDK dynamic hardware partitioning , registering", "registering for driver notifications WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Asynchronous Driver Notification + + +To use asynchronous driver notification, a device driver implements callback functions that the operating system calls when you dynamically add a processor or memory module to the hardware partition. The following code example shows prototypes for such callback functions: + +``` +// Prototypes for the asynchronous +// notification callback functions +NTSTATUS + AsyncProcessorCallback( + IN PVOID NotificationStructure, + IN PVOID Context + ); + +NTSTATUS + AsyncMemoryCallback( + IN PVOID NotificationStructure, + IN PVOID Context + ); +``` + +A device driver registers for asynchronous notification by calling the [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) function, one time for each of the device driver's callback functions, specifying a pointer to one of the following GUIDs for the *EventCategoryData* parameter: + +GUID\_DEVICE\_PROCESSOR +Register to be notified when a processor is dynamically added to the hardware partition. + +GUID\_DEVICE\_MEMORY +Register to be notified when memory is dynamically added to the hardware partition. + +These GUIDs are defined in the header file, Poclass.h. + +The following code example shows how to register for both notifications: + +``` +PVOID ProcessorNotificationEntry; +PVOID MemoryNotificationEntry; +NTSTATUS Status; + +Status = + IoRegisterPlugPlayNotification( + EventCategoryDeviceInterfaceChange, + 0, + &GUID_DEVICE_PROCESSOR, + DriverObject, + AsyncProcessorCallback, + NULL, + &ProcessorNotificationEntry + ); + +Status = + IoRegisterPlugPlayNotification( + EventCategoryDeviceInterfaceChange, + 0, + &GUID_DEVICE_MEMORY, + DriverObject, + AsyncMemoryCallback, + NULL, + &MemoryNotificationEntry + ); +``` + +**Note**   If a device driver only has to be notified about processors, it does not have to implement a callback function for memory or register for notification about memory. Similarly, if a device driver only has to be notified about memory, it does not have to implement a callback function for processors or register for notification about processors. + +  + +When a device driver must stop receiving asynchronous driver notifications, such as when it is being unloaded, it must unregister each callback function by calling the [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) function. The following code example shows how to unregister the callback functions: + +``` +// Unregister for asynchronous notifications +Status = + IoUnregisterPlugPlayNotification( + ProcessorNotificationEntry + ); + +Status = + IoUnregisterPlugPlayNotification( + MemoryNotificationEntry + ); +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Asynchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-device-interface-change-notification.md b/windows-driver-docs-pr/kernel/registering-for-device-interface-change-notification.md new file mode 100644 index 0000000000..22f206fa3c --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-device-interface-change-notification.md @@ -0,0 +1,50 @@ +--- +title: Registering for Device Interface Change Notification +author: windows-driver-content +description: Registering for Device Interface Change Notification +ms.assetid: 680e4c5c-dac6-41b1-b754-aee782145ed0 +keywords: ["notifications WDK PnP , device interface changes", "EventCategoryDeviceInterfaceChange notification", "device interface change notifications WDK PnP", "registering device interface change notifications", "IoRegisterPlugPlayNotification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Device Interface Change Notification + + +## + + +A driver registers for notification of device interface arrival and removal events by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). + +The following information applies to calling this routine for device interface change notification: + +- Specify an *EventCategory* of **EventCategoryDeviceInterfaceChange**. + +- *EventCategoryData* must point to the GUID for a device interface class. + + The GUID for a interface class is typically defined in a header file with the structures, constants, and so forth, for the interface. + +- Specify an *EventCategoryFlags* of PNPNOTIFY\_DEVICE\_INTERFACE\_INCLUDE\_EXISTING\_INTERFACES. + + This flag directs the PnP manager to register the *CallbackRoutine* for future device interface arrivals and departures of the specified class and to call the *CallbackRoutine* immediately for any relevant device interfaces that are already active. + + A driver can call [**IoGetDeviceInterfaces**](https://msdn.microsoft.com/library/windows/hardware/ff549186) to get a list of existing interfaces of a specific class and then register its callback routine without this flag, but using the flag is easier and avoids a potential timing issue. + +- Specify a driver-defined *Context*, if appropriate, that the PnP manager will pass to the callback routine. + +A driver that opens a handle to a device in response to a device interface arrival notification should register for **EventCategoryTargetDeviceChange** events on the device. (See [Using PnP Target Device Change Notification](using-pnp-target-device-change-notification.md).) + +A driver cancels notification registration by calling [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) with the *NotificationEntry* returned by **IoRegisterPlugPlayNotification**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Device%20Interface%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-hardware-profile-change-notification.md b/windows-driver-docs-pr/kernel/registering-for-hardware-profile-change-notification.md new file mode 100644 index 0000000000..7d6e9b05eb --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-hardware-profile-change-notification.md @@ -0,0 +1,40 @@ +--- +title: Registering for Hardware Profile Change Notification +author: windows-driver-content +description: Registering for Hardware Profile Change Notification +ms.assetid: 3aaa09f7-ac63-4b56-917a-74cf344f6dd3 +keywords: ["notifications WDK PnP , hardware profile changes", "hardware profile change notifications WDK PnP", "EventCategoryHardwareProfileChange notification", "profile change notifications WDK PnP", "registering hardware profile change notifications", "machine hardware profile change notifications WDK PnP", "IoRegisterPlugPlayNotification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Hardware Profile Change Notification + + +## + + +A driver registers for notification of hardware profile changes by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). + +The following information applies to calling this routine for hardware profile change notification: + +- Specify an *EventCategory* of **EventCategoryHardwareProfileChange**. + +- *EventCategoryData* must be **NULL**. + +- Specify a driver-defined *Context*, if appropriate, that the PnP manager will pass to the callback routine. + +A driver removes notification registration by calling [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) with the *NotificationEntry* returned by **IoRegisterPlugPlayNotification**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Hardware%20Profile%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-notifications.md b/windows-driver-docs-pr/kernel/registering-for-notifications.md new file mode 100644 index 0000000000..a6ff9e9e68 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-notifications.md @@ -0,0 +1,33 @@ +--- +title: Registering for Notifications +author: windows-driver-content +description: Registering for Notifications +ms.assetid: 06109726-77e8-49de-9486-4fa2a5aceb1c +keywords: ["filtering registry calls WDK kernel , registering for notifications", "registry filtering drivers WDK kernel , registering for notifications", "registering filter registry call notifications", "pre-notification option WDK filter registry call", "post-notification option WDK filter registry call", "notifications WDK filter registry call"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Notifications + + +To filter registry calls, your kernel-mode registry filtering driver must first call [**CmRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541918) or [**CmRegisterCallbackEx**](https://msdn.microsoft.com/library/windows/hardware/ff541921) to register a [**RegistryCallback**](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine. (For Windows Vista and later operating system versions, drivers should use **CmRegisterCallbackEx** instead of **CmRegisterCallback**.) + +After your driver has registered a *RegistryCallback* routine, the configuration manager calls the routine each time that a thread attempts to perform a registry operation. Threads that perform registry operations can be from user-mode applications that call the user-mode registry routines (**RegCreateKeyEx**, **RegOpenKeyEx**, and so on) and from drivers that call the kernel-mode registry routines ([**ZwCreateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566425), [**ZwOpenKey**](https://msdn.microsoft.com/library/windows/hardware/ff567014), and so on). + +For most operations, your driver can receive notification before the configuration manager processes the registry operation (a *pre-notification*) or immediately after the operation completes (but before the configuration manager returns to the caller—a *post-notification*). For a list of the types of notifications that your driver can receive, see [**REG\_NOTIFY\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff560950). + +After a driver has called **CmRegisterCallback** or **CmRegisterCallbackEx**, the driver will receive notifications until it calls [**CmUnRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541928) or is unloaded. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Notifications%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-synchronous-driver-notification.md b/windows-driver-docs-pr/kernel/registering-for-synchronous-driver-notification.md new file mode 100644 index 0000000000..c3c513ba72 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-synchronous-driver-notification.md @@ -0,0 +1,105 @@ +--- +title: Registering for Synchronous Driver Notification +author: windows-driver-content +description: Registering for Synchronous Driver Notification +ms.assetid: 852a2b69-c71f-4127-946e-8179954d504c +keywords: ["driver notification WDK dynamic hardware partitioning , registering", "synchronous notification WDK dynamic hardware partitioning , registering", "notification WDK dynamic hardware partitioning , registering", "synchronous driver notification WDK dynamic hardware partitioning , registering", "registering for driver notifications WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Synchronous Driver Notification + + +To use synchronous driver notification, a device driver implements a callback function that the operating system calls when you dynamically add a new processor to the hardware partition. The following code example is a prototype for such a callback function: + +``` +// Prototype for the synchronous +// notification callback function +VOID + SyncProcessorCallback( + IN PVOID CallbackContext, + IN PKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT ChangeContext, + IN PNTSTATUS OperationStatus + ); +``` + +A device driver registers for synchronous driver notification by calling the [**KeRegisterProcessorChangeCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553120) function. A device driver typically calls the **KeRegisterProcessorChangeCallback** function from within its [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) function. If the device driver specifies the KE\_PROCESSOR\_CHANGE\_ADD\_EXISTING flag, the callback function is immediately called for each active processor that currently exists in the hardware partition, in addition to being called when a new processor is added to the hardware partition. The following code example shows how to register for the synchronous driver notifications: + +``` +PVOID CallbackRegistrationHandle; +NTSTATUS CallbackStatus = STATUS_SUCCESS; + +// The driver's DriverEntry routine +NTSTATUS DriverEntry( + PDRIVER_OBJECT DriverObject, + PUNICODE_STRING RegistryPath + ) +{ + ... + + // Register the callback function + CallbackRegistrationHandle = + KeRegisterProcessorChangeCallback( + SyncProcessorCallback, + &CallbackStatus, + KE_PROCESSOR_CHANGE_ADD_EXISTING + ); + + // Check the result + if (CallbackRegistrationHandle == NULL) + { + // Perform any necessary cleanup + ... + + // Check the callback status + if (CallbackStatus != STATUS_SUCCESS) + { + // Return the error status from the callback function + return CallbackStatus; + } + else + { + // Return a generic error status + return STATUS_UNSUCCESSFUL; + } + } + + ... + + return STATUS_SUCCESS; +} +``` + +When a device driver must stop receiving synchronous driver notifications, such as when it is being unloaded, it must unregister the callback function by calling the [**KeDeregisterProcessorChangeCallback**](https://msdn.microsoft.com/library/windows/hardware/ff552015) function. A device driver typically calls the **KeDeregisterProcessorChangeCallback** function from within its [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) function. The following code example shows how to unregister the callback function: + +``` +// The driver's Unload routine +VOID + Unload( + IN PDRIVER_OBJECT DriverObject + ); +{ + ... + + // Unregister the callback function + KeDeregisterProcessorChangeCallback( + CallbackRegistrationHandle + ); + + ... +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Synchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registering-for-target-device-change-notification.md b/windows-driver-docs-pr/kernel/registering-for-target-device-change-notification.md new file mode 100644 index 0000000000..e39fb4edde --- /dev/null +++ b/windows-driver-docs-pr/kernel/registering-for-target-device-change-notification.md @@ -0,0 +1,50 @@ +--- +title: Registering for Target Device Change Notification +author: windows-driver-content +description: Registering for Target Device Change Notification +ms.assetid: 5f7a9c44-c9a4-4ff8-a97d-ad2462b86af0 +keywords: ["notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification", "registering target device change notifications", "IoRegisterPlugPlayNotification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registering for Target Device Change Notification + + +## + + +A driver registers for notification of PnP target device change events by calling [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526). + +The following information applies to calling this routine for target device change notification: + +- Specify an *EventCategory* of **EventCategoryTargetDeviceChange**. + +- *EventCategoryData* must point to the file object for the device on which notification is requested. + + If the driver's callback routine requires access to the file object, the driver should take out a reference on the file object before calling **IoRegisterPlugPlayNotification**. + + If the driver's callback routine does not require access to the file object, the driver does not need to reference the object. + + After the file object is closed, the driver continues to receive notifications for the device until the driver removes its notification registration. This design allows the driver to receive notification of GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED events, for example. + +- Specify a driver-defined *Context* that the PnP manager will pass to the callback routine. + + A driver might use the *Context* parameter to maintain information about the current state of the file object (for example, has it been closed/deleted). + + A driver might also use the *Context* to store the path it used to originally open the device. A driver can use this path to reopen the device after a canceled remove operation. (See [Handling a GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED Event](handling-a-guid-target-device-remove-cancelled-event.md) for more information.) + +A driver removes a notification registration by calling [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) with the *NotificationEntry* returned by **IoRegisterPlugPlayNotification**. If the driver took out a reference on the file object when it registered for notification and that reference is still outstanding, the driver must release the reference after it removes the registration. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registering%20for%20Target%20Device%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registry-key-object-routines.md b/windows-driver-docs-pr/kernel/registry-key-object-routines.md new file mode 100644 index 0000000000..b9a0415a55 --- /dev/null +++ b/windows-driver-docs-pr/kernel/registry-key-object-routines.md @@ -0,0 +1,73 @@ +--- +title: Registry Key Object Routines +author: windows-driver-content +description: Registry Key Object Routines +ms.assetid: 9db6ff0d-8371-41bc-82c4-1bb56f5430f2 +keywords: ["registry WDK kernel , object routines", "driver registry information WDK kernel , object routines", "object routines WDK kernel", "registry-key objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registry Key Object Routines + + +## + + +The Windows executive represents registry keys as executive objects that are managed by the object manager. (For more information about the object manager, see [Object Management](managing-kernel-objects.md).) In particular, every key has an object name, and you can open a handle to a key. + +User-mode applications access keys relative to global handles, such as HKEY\_LOCAL\_MACHINE or HKEY\_CURRENT\_USER. However, these handles are not available to kernel-mode code. Instead, you refer to a key by its object name. The root for all registry keys is the **\\Registry** object. The global handles correspond to descendants of the **\\Registry** object, as shown in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
User-mode handleCorresponding object name

HKEY_LOCAL_MACHINE

\Registry\Machine

HKEY_USERS

\Registry\User

HKEY_CLASSES_ROOT

No kernel-mode equivalent

HKEY_CURRENT_USER

No simple kernel-mode equivalent, but see [Registry Run-Time Library Routines](registry-run-time-library-routines.md)

+ +  + +A driver can manipulate a registry-key object by performing the following steps: + +1. Open a handle to the registry-key object. For more information, see [Opening a Handle to a Registry-Key Object](opening-a-handle-to-a-registry-key-object.md). + +2. Perform the intended operations by calling the appropriate **Zw*Xxx*Key** routines. For information about how to do so, see [Using a Handle to a Registry-Key Object](using-a-handle-to-a-registry-key-object.md). + +3. Close the handle by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registry%20Key%20Object%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/registry-run-time-library-routines.md b/windows-driver-docs-pr/kernel/registry-run-time-library-routines.md new file mode 100644 index 0000000000..c8c7c1809c --- /dev/null +++ b/windows-driver-docs-pr/kernel/registry-run-time-library-routines.md @@ -0,0 +1,89 @@ +--- +title: Registry Run-Time Library Routines +author: windows-driver-content +description: Registry Run-Time Library Routines +ms.assetid: 53e55969-3c8e-44ab-8ba7-6abb0ddbfc24 +keywords: ["registry WDK kernel , run-time library routines", "driver registry information WDK kernel , run-time library routines", "run-time library routines WDK kernel", "RtlXxxRegistryYyy routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Registry Run-Time Library Routines + + +## + + +To manipulate registry entries, drivers can call the **Rtl*Xxx*Registry*Xxx*** routines, which provide a simpler interface than the **Zw*Xxx*Key** routines. When doing so, the driver is not required to open and close handles; instead, the driver refers to keys by name. + +You pass *RelativeTo* and *Path* parameters to each **Rtl*Xxx*Registry*Xxx*** routine. If *RelativeTo* is RTL\_REGISTRY\_ABSOLUTE, *Path* specifies the full path of the key, beginning with the **\\Registry** root. If *RelativeTo* is RTL\_REGISTRY\_HANDLE, *Path* is actually an open handle. Additional RTL\_REGISTRY\_*XXX* values for *RelativeTo* specify the paths of common roots for the key; in these cases, *Path* specifies the path relative to that root. For example, RTL\_REGISTRY\_USER requires that *Path* be relative to the current user's registry settings. (This value is equivalent to specifying HKEY\_CURRENT\_USER in a user-mode application.) For a description of all the RTL\_REGISTRY\_*XXX* values, see [**RtlCheckRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff561754). + +The following table list the operations that drivers can perform by calling the **Rtl*Xxx*Registry*Xxx*** routines. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationRtlXxxRegistryXxx routine to call

Create a registry key

[RtlCreateRegistryKey](https://msdn.microsoft.com/library/windows/hardware/ff561822)

Check whether a registry key exists

[RtlCheckRegistryKey](https://msdn.microsoft.com/library/windows/hardware/ff561754)

Examine one or more registry-key values

[RtlQueryRegistryValues](https://msdn.microsoft.com/library/windows/hardware/ff562046)

Write a registry-key value

[RtlWriteRegistryValue](https://msdn.microsoft.com/library/windows/hardware/ff563034)

Delete a registry-key value

[RtlDeleteRegistryValue](https://msdn.microsoft.com/library/windows/hardware/ff561829)

+ +  + +The following code example illustrates how to set *ValueName* for **\\Registry\\Machine\\System\\***KeyName* to a ULONG value of 0xFF. Compare this example with the corresponding one in the [Registry Key Object Routines](registry-key-object-routines.md) section. + +``` +NTSTATUS status; +ULONG data = 0xFF; + +status = RtlWriteRegistryValue(RTL_REGISTRY_ABSOLUTE, + (PWCSTR)L"\\Registry\\Machine\\System\\KeyName", + (PWCSTR)L"ValueName", + REG_DWORD, + &data, + sizeof(ULONG)); +``` + +Although you write fewer lines of code when using the **Rtl*Xxx*Registry*Xxx*** routines instead of the **Zw*Xxx*Key** routines, the latter ones are necessary for performing certain operations. For example, no **Rtl*Xxx*Registry*Xxx*** routine exists that corresponds to [**ZwEnumerateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566447). + +If you perform multiple operations on the same key, the **Zw*Xxx*Key** routines are more efficient—you can use the same open handle for each operation. In contrast, the **Rtl*Xxx*Registry*Xxx*** routines open and close a new handle for each operation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Registry%20Run-Time%20Library%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/releasing-device-and-controller-objects.md b/windows-driver-docs-pr/kernel/releasing-device-and-controller-objects.md new file mode 100644 index 0000000000..0b09ceacac --- /dev/null +++ b/windows-driver-docs-pr/kernel/releasing-device-and-controller-objects.md @@ -0,0 +1,38 @@ +--- +title: Releasing Device and Controller Objects +author: windows-driver-content +description: Releasing Device and Controller Objects +ms.assetid: 35404401-d3a8-4257-b1a3-b16ebe42b181 +keywords: ["Unload routines WDK kernel , non-PnP drivers", "non-PnP Unload routine WDK kernel", "releasing devices", "releasing controller objects", "device releases WDK kernel", "controller objects WDK kernel , releasing"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Releasing Device and Controller Objects + + +## + + +Before a driver deletes a device or controller object, it must release its references to external resources, such as pointers to other drivers' objects and/or to interrupt objects, that it stored in the corresponding device or controller extension. It can then call [**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083) for each device object that the driver created. A non-WDM driver that previously called [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395) must also call [**IoDeleteController**](https://msdn.microsoft.com/library/windows/hardware/ff549078). + +Any Kernel-defined object for which the driver provides storage in a device extension is automatically freed when the [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine calls **IoDeleteDevice** with the corresponding device object. In general, any object that the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) or [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routine set up by calling **KeInitialize*Xxx*** can be freed by a call to **IoDeleteDevice** if the driver provided storage for that object in its device extension. For example, if a driver has a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine and has provided storage for the necessary DPC and timer objects in its device extension, the call to **IoDeleteDevice** releases these system resources. + +Similarly, any Kernel-defined object for which the driver provides storage in a controller extension is automatically freed when the *Unload* routine calls **IoDeleteController** with the corresponding controller object. + +If the **DriverEntry** or *Reinitialize* routine called [**IoGetConfigurationInformation**](https://msdn.microsoft.com/library/windows/hardware/ff549157) to increment the count for a particular type of device, the *Unload* routine also must call **IoGetConfigurationInformation** and decrement the count for its devices in the I/O manager's global configuration information structure as it deletes the corresponding device objects. + +Before it returns control, an *Unload* routine also is responsible for freeing any other driver-allocated resources that have not yet been freed by other driver routines. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Releasing%20Device%20and%20Controller%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/releasing-driver-allocated-resources.md b/windows-driver-docs-pr/kernel/releasing-driver-allocated-resources.md new file mode 100644 index 0000000000..31c04dfb19 --- /dev/null +++ b/windows-driver-docs-pr/kernel/releasing-driver-allocated-resources.md @@ -0,0 +1,70 @@ +--- +title: Releasing Driver-Allocated Resources +author: windows-driver-content +description: Releasing Driver-Allocated Resources +ms.assetid: b286b4b0-54f2-4798-a77b-c08743502552 +keywords: ["Unload routines WDK kernel , non-PnP drivers", "non-PnP Unload routine WDK kernel", "releasing driver-allocated resources", "driver-allocated resource releases WDK kernel", "resource releasing WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Releasing Driver-Allocated Resources + + +## + + +The specifics of how a driver uses the registry, sets up system objects and resources in its device extensions, controller extension, or driver-allocated nonpaged pool varies from driver to driver. However, any [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine must release the resources a driver is using in stages. + +Any driver's *Unload* routine must ensure that no other driver routine is currently using or might shortly be using a particular resource before it releases that resource. + +In general, an *Unload* routine releases all driver-allocated resources in the following stages: + +1. If the driver has not already done so, disable interrupts on any physical devices, if possible, and then call [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089) as soon as interrupts are disabled. + +2. Ensure that no other driver routine can reference the resources that the *Unload* routine intends to release. + + For example, an *Unload* routine must call [**IoStopTimer**](https://msdn.microsoft.com/library/windows/hardware/ff550377) if the driver's [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine is currently enabled for a particular device object. It must ensure that no thread is waiting for any of the driver's dispatcher objects and that its timer objects are not queued for calls to its [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routines before it frees the storage for its dispatcher objects. It must call [**KeRemoveQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553169) if it has a [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine that the ISR might have queued, and so on. + + If the driver called [**IoQueueWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549466), it must ensure that the work item has completed. **IoQueueWorkItem** takes out a reference on the associated device object; the driver cannot be unloaded if any such references remain. + + If the driver called [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932), the *Unload* routine also must cause the driver-created thread to be run so that the thread itself can call [**PsTerminateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559959) before the driver is unloaded. A driver cannot release a driver-created system thread by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) with the *ThreadHandle* returned by **PsCreateSystemThread**. + +3. Release any device-specific resources that the driver allocated. Doing so might involve calling the following system support routines: + - [**IoDeleteSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549085) if the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) or [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routine called [**IoCreateSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549043) or [**IoCreateUnprotectedSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff549050), and [**IoDeassignArcName**](https://msdn.microsoft.com/library/windows/hardware/ff549076) if the driver called [**IoAssignArcName**](https://msdn.microsoft.com/library/windows/hardware/ff548282). + + - [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) if **DriverEntry** or any other driver routine called [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) and the driver has not yet released the allocated memory. + + - [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387) if the **DriverEntry** or *Reinitialize* routine called [**MmMapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff554618). + + - [**MmFreeNonCachedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554516) if the **DriverEntry** or *Reinitialize* routine called [**MmAllocateNonCachedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554479). + + - [**MmFreeContiguousMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554503) if the **DriverEntry** or *Reinitialize* routine called [**MmAllocateContiguousMemory**](https://msdn.microsoft.com/library/windows/hardware/ff554460). + + - [**FreeCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff546511) if the **DriverEntry** or *Reinitialize* routine called [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575). + + - [**IoAssignResources**](https://msdn.microsoft.com/library/windows/hardware/ff548285) or [**IoReportResourceUsage**](https://msdn.microsoft.com/library/windows/hardware/ff549616) if the **DriverEntry** or *Reinitialize* routine called one of these support routines or [**HalAssignSlotResources**](https://msdn.microsoft.com/library/windows/hardware/ff546580) to claim hardware resources in the configuration registry for itself and/or for its physical devices individually. + +4. Release system objects and resources that the **DriverEntry** or *Reinitialize* routine set up in the device extension of the device objects or in the controller extension of the controller object (if it created one). In particular, the driver must do the following before it attempts to delete the device object ([**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083)) or controller object ([**IoDeleteController**](https://msdn.microsoft.com/library/windows/hardware/ff549078)): + - Call [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089) to free the interrupt object pointer stored in the corresponding device or controller extension. + - Call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) with the pointer to the next-lower driver's file object if it called [**IoGetDeviceObjectPointer**](https://msdn.microsoft.com/library/windows/hardware/ff549198) and stored this pointer in a device or controller extension. + - Call [**IoDetachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549087) with the pointer to the lower driver's device object if it called [**IoAttachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548294) or [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300) and stored this pointer in a device or controller extension. + +5. Free the hardware resources that the **DriverEntry** or *Reinitialize* routine claimed for the driver's physical devices, if any, in the registry under the **\\Registry\\Machine\\Hardware\\ResourceMap** tree. + +6. Remove any names for its devices that the **DriverEntry** or *Reinitialize* routine stored in the registry under the **\\Registry..\\DeviceMap** tree, as well. + +After the driver has released device, system, and hardware resources, it can delete its device and controller objects, as described in the following section. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Releasing%20Driver-Allocated%20Resources%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/removing-a-device-in-a-bus-driver.md b/windows-driver-docs-pr/kernel/removing-a-device-in-a-bus-driver.md new file mode 100644 index 0000000000..2e5bf4fa11 --- /dev/null +++ b/windows-driver-docs-pr/kernel/removing-a-device-in-a-bus-driver.md @@ -0,0 +1,76 @@ +--- +title: Removing a Device in a Bus Driver +author: windows-driver-content +description: Removing a Device in a Bus Driver +ms.assetid: f3961c29-02e1-41f0-bb7f-784bcdb57eb0 +keywords: ["bus drivers WDK PnP", "DispatchPnP routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Removing a Device in a Bus Driver + + +## + + +When removing a child device (child PDO), the parent bus driver must undo any operations it performed to add and start the device. + +A bus driver removes a child device with a procedure such as the following in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine: + +1. Has the driver handled a previous [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request for this PDO? + + If so, perform any remaining clean-up and skip to step 4. + + A driver typically maintains a flag in the device extension that indicates whether the driver has handled an **IRP\_MN\_SURPRISE\_REMOVAL** request for the device. + +2. Complete any requests queued in the driver. + +3. Remove power from the device, if the bus driver is capable of doing so, and notify the power manager by calling [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765). + + The bus driver powers down the child device, if possible, and notifies the power manager of the device's change in power state. The bus driver does this in response to the [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request; the device's power policy owner does not send an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request when the device is being removed. For additional information, see [Power Management](implementing-power-management.md). + +4. If the bus driver reported this device in its most recent response to an [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) request for **BusRelations**, the device is still physically present on the machine. In this case, the bus driver: + + - Retains the PDO for the device until the device has been physically removed. + + - Sets **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Completes the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + - Returns from the [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine. + + The bus driver must continue to report this device in subsequent enumerations (**IRP\_MN\_QUERY\_DEVICE\_RELATIONS** for **BusRelations**) until the device is physically removed. The PnP manager keeps track of whether an enumerated device has been added and started. + +5. If the device was not included in the bus driver's most recent response to an **IRP\_MN\_QUERY\_DEVICE\_RELATIONS** request for **BusRelations**, the bus driver considers the device to be physically removed from the machine. In this case, the bus driver does the following: + + - Cleans up device-specific allocations, memory, events, and so forth. + + - Sets **Irp->IoStatus.Status** to STATUS\_SUCCESS. + + - Completes the IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + + - Frees the PDO with [**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083). + + The bus driver must delete the PDO if the driver omitted the device from its most recent **BusRelations** list. If a user plugs the device into the machine again, the bus driver must create a new PDO in response to the next **BusRelations** query. If a bus driver reuses the same PDO for a new instance of a device, the machine will not operate properly. + + - Returns from the *DispatchPnP* routine. + +If the device is still present when the PnP manager sends the **IRP\_MN\_REMOVE\_DEVICE** request, the bus driver retains the PDO. If, at some later time, the device is physically removed from the bus, the PnP manager sends another **IRP\_MN\_REMOVE\_DEVICE**. Upon receipt of the subsequent remove IRP, the bus driver deletes the PDO for the device. + +A bus driver must be able to handle an **IRP\_MN\_REMOVE\_DEVICE** for a device it has already removed and whose PDO is marked for deletion. In response to such an IRP, the bus driver can succeed the IRP or return STATUS\_NO\_SUCH\_DEVICE. The PDO for the device has not yet been deleted in this case, despite the bus driver's previous call to **IoDeleteDevice**, because some component still has a reference to the object. Therefore, the bus driver can access the PDO while handling the second remove IRP. The bus driver must not call **IoDeleteDevice** a second time for the PDO; the I/O system deletes the PDO when its reference count reaches zero. + +A bus driver does not remove its data structures for a child device until it receives an **IRP\_MN\_REMOVE\_DEVICE** request for the device. A bus driver might detect that a device has been removed and call [**IoInvalidateDeviceRelations**](https://msdn.microsoft.com/library/windows/hardware/ff549353), but it must not delete the device's PDO until the PnP manager sends an **IRP\_MN\_REMOVE\_DEVICE** request. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Removing%20a%20Device%20in%20a%20Bus%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/removing-a-device-in-a-filter-driver.md b/windows-driver-docs-pr/kernel/removing-a-device-in-a-filter-driver.md new file mode 100644 index 0000000000..b254bb444b --- /dev/null +++ b/windows-driver-docs-pr/kernel/removing-a-device-in-a-filter-driver.md @@ -0,0 +1,30 @@ +--- +title: Removing a Device in a Filter Driver +author: windows-driver-content +description: Removing a Device in a Filter Driver +ms.assetid: f1166240-446d-4f37-871b-baf687e25735 +keywords: ["filter drivers WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Removing a Device in a Filter Driver + + +## + + +When removing a device, a filter driver must undo any operations it performed to add and start the device. A filter driver follows essentially the same procedure as a function driver when removing a device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Removing%20a%20Device%20in%20a%20Filter%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/removing-a-device-in-a-function-driver.md b/windows-driver-docs-pr/kernel/removing-a-device-in-a-function-driver.md new file mode 100644 index 0000000000..ca2e690125 --- /dev/null +++ b/windows-driver-docs-pr/kernel/removing-a-device-in-a-function-driver.md @@ -0,0 +1,82 @@ +--- +title: Removing a Device in a Function Driver +author: windows-driver-content +description: Removing a Device in a Function Driver +ms.assetid: 46a75647-e72a-4194-be9d-070e3ac95650 +keywords: ["function drivers WDK PnP", "DispatchPnP routine"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Removing a Device in a Function Driver + + +## + + +When removing a device, a function driver must undo any operations it performed to add and start the device. This discussion includes function drivers for peripheral devices and function drivers for bus devices. + +A function driver removes a device using a procedure such as the following in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine: + +1. Is this a function driver for a bus device? + + If so, possibly delete any outstanding child PDOs for devices on the bus. + + If the bus driver handled a previous [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request for the child device, but the driver has not yet received the subsequent [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request, the bus driver leaves the child PDO intact. At some later time, when all handles to the child device are closed, the PnP manager will send the remove IRP for the child device and the bus driver deletes the child PDO at that time. + + If the bus driver handled a previous **IRP\_MN\_REMOVE\_DEVICE** request for the device, and there has been no subsequent **IRP\_MN\_SURPRISE\_REMOVAL** request, then the bus driver deletes the child PDO. In this case, the PnP manager ensures that any function and filter drivers have been removed from the child device (FDO and filter DOs have been deleted) before it sends a remove IRP to the parent bus device. The child PDO might still be present, so the bus driver must delete the child PDO before it removes the bus device. + +2. Has the driver already handled a previous **IRP\_MN\_SURPRISE\_REMOVAL** request for this FDO? + + If so, perform any remaining clean-up and skip to step 8, [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + A driver typically maintains a flag in the device extension that indicates whether the driver has handled an **IRP\_MN\_SURPRISE\_REMOVAL** request for the device. + +3. If the driver previously enabled the device for wake-up, cancel the [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) request. + +4. Ensure that the device is inactive. + + If the device is not already inactive in response to a prior **IRP\_MN\_QUERY\_REMOVE\_DEVICE**, the driver must mark the device as not accepting new requests and must complete any requests queued in this driver. The driver must fail any outstanding requests that require access to the device. + + A driver can use the **Io*Xxx*RemoveLock*Xxx*** routines to count outstanding I/O and to set an event indicating that remove processing can continue. + +5. Perform any power-down operations. + + Each driver for the device performs its power-down operations, if any, when it receives the **IRP\_MN\_REMOVE\_DEVICE** request. The power policy owner for the device, typically the function driver, does not send a separate [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request to set the device power state to D3. The parent bus driver typically powers down the slot and notifies the power manager with [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) when the bus driver gets the remove IRP. For additional information, see [Power Management](implementing-power-management.md). + +6. Disable any device interfaces by calling [**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700). + +7. Free any hardware resources for the device in use by the driver. + + The exact operations depend on the device and the driver but can include disconnecting an interrupt with [**IoDisconnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff549089), freeing physical address ranges with [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387), and freeing I/O ports. + +8. Pass the **IRP\_MN\_REMOVE\_DEVICE** request down to the next driver. + + Set up the IRP stack location for the next lower driver with [**IoSkipCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff550355) and pass the IRP to the next driver with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + + A driver is not required to wait for underlying drivers to finish their remove operations before continuing with its remove activities. + +9. Remove the device object from the device stack with [**IoDetachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549087). + + Specify a pointer to the next lower device object as the *TargetDevice* parameter. The driver receives such a pointer from the call to [**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300) in the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +10. Clean up any device-specific allocations, memory, events, and so forth. + +11. Free the FDO with [**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083). + +12. Return from the [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine, propagating the return status from **IoCallDriver**. + +A function driver does not specify an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for a remove IRP, nor does it complete the IRP. Remove IRPs are completed by the parent bus driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Removing%20a%20Device%20in%20a%20Function%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/removing-a-device.md b/windows-driver-docs-pr/kernel/removing-a-device.md new file mode 100644 index 0000000000..0c1cf69e8a --- /dev/null +++ b/windows-driver-docs-pr/kernel/removing-a-device.md @@ -0,0 +1,44 @@ +--- +title: Removing a Device +author: windows-driver-content +description: Removing a Device +ms.assetid: 8184987f-5c46-4dd6-aad2-3c32b14205fd +keywords: ["PnP WDK kernel , removing devices", "Plug and Play WDK kernel , removing devices", "removing devices", "notifications WDK PnP , removing devices", "IRPs WDK PnP", "I/O request packets WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Removing a Device + + +## + + +The PnP manager directs drivers to remove their device objects for a device when the device has been, or is being, physically removed from the machine. The PnP manager also sends a *remove* IRP when a user requests to update the drivers for a device and, on Windows 2000 and later, when the device is disabled or fails to start. + +The following sections describe when the PnP manager issues *remove* IRPs and what drivers must do to respond to those IRPs. This section covers the following topics: + +[Understanding When Remove IRPs Are Issued](understanding-when-remove-irps-are-issued.md) + +[Handling an IRP\_MN\_QUERY\_REMOVE\_DEVICE Request](handling-an-irp-mn-query-remove-device-request.md) + +[Handling an IRP\_MN\_REMOVE\_DEVICE Request](handling-an-irp-mn-remove-device-request.md) + +[Handling an IRP\_MN\_CANCEL\_REMOVE\_DEVICE Request](handling-an-irp-mn-cancel-remove-device-request.md) + +[Handling an IRP\_MN\_SURPRISE\_REMOVAL Request](handling-an-irp-mn-surprise-removal-request.md) + +[Using Remove Locks](using-remove-locks.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Removing%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/removing-an-isr.md b/windows-driver-docs-pr/kernel/removing-an-isr.md new file mode 100644 index 0000000000..02d86c5e62 --- /dev/null +++ b/windows-driver-docs-pr/kernel/removing-an-isr.md @@ -0,0 +1,29 @@ +--- +title: Removing an ISR +author: windows-driver-content +description: Removing an ISR +ms.assetid: 23d84edb-763f-4383-b05c-832b4249b604 +keywords: ["interrupt service routines WDK kernel , removing ISRs", "interrupt objects WDK kernel , removing ISRs", "ISRs WDK kernel , removing ISRs", "removing ISRs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Removing an ISR + + +Drivers can remove an ISR that is registered with [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) by calling [**IoDisconnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff549093). **IoDisconectInterruptEx** takes a single *Parameters* parameter, which is a pointer to an [**IO\_DISCONNECT\_INTERRUPT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff550569) structure. The values that are used for the members of the structure depend on the version that is used to register the ISR. + +The driver must save certain information when it registers the ISR to later remove it. For the CONNECT\_LINE\_BASED and CONNECT\_FULLY\_SPECIFIED versions, the driver must save the value that is supplied in the **LineBased.InterruptObject** or **FullySpecified.InterruptObject** member of [**IO\_CONNECT\_INTERRUPT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff550541). For the CONNECT\_MESSAGE\_BASED version, the driver must save the values supplied in the **Version** and **MessageBased.ConnectionContext** members of **IO\_CONNECT\_INTERRUPT\_PARAMETERS**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Removing%20an%20ISR%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/reporting-device-power-capabilities.md b/windows-driver-docs-pr/kernel/reporting-device-power-capabilities.md new file mode 100644 index 0000000000..69b576b3e0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/reporting-device-power-capabilities.md @@ -0,0 +1,48 @@ +--- +title: Reporting Device Power Capabilities +author: windows-driver-content +description: Reporting Device Power Capabilities +ms.assetid: 67a504d0-2c41-4c74-a912-4f0771885f7d +keywords: ["reporting device power capabilities", "device power capabilities WDK kernel", "DEVICE_CAPABILITIES structure", "query-capabilities IRPs WDK power management", "IRPs WDK power management", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reporting Device Power Capabilities + + +## + + +During enumeration, drivers report device-specific information in response to a PnP [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) request. Along with other such information, drivers report a device's power management capabilities in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. Typically, the bus driver fills in this structure. + +Higher-level drivers should set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for the query-capabilities IRP so that they can make a local copy of the structure and ensure that it contains appropriate values. As a general rule, higher-level drivers should not change these values. However, if a change is necessary, a driver can further restrict device capabilities but cannot add to them. In other words, a driver can make the rules more restrictive but cannot loosen them. + +After the IRP is complete and all drivers' completion routines have been run, the structure is cached and a driver cannot change its contents. + +The following members of the **DEVICE\_CAPABILITIES** structure pertain to power management: + +[DeviceD1 and DeviceD2](deviced1-and-deviced2.md) + +[WakeFromD0, WakeFromD1, WakeFromD2, and WakeFromD3](wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md) + +[DeviceState](devicestate.md) + +[SystemWake](systemwake.md) + +[DeviceWake](devicewake.md) + +[D1Latency, D2Latency, and D3Latency](d1latency--d2latency--and-d3latency.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Reporting%20Device%20Power%20Capabilities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/required-dispatch-routines.md b/windows-driver-docs-pr/kernel/required-dispatch-routines.md new file mode 100644 index 0000000000..e88eb37ccf --- /dev/null +++ b/windows-driver-docs-pr/kernel/required-dispatch-routines.md @@ -0,0 +1,70 @@ +--- +title: Required Dispatch Routines +author: windows-driver-content +description: Required Dispatch Routines +ms.assetid: 9b760ac7-7f31-47ad-bf84-7d79c6b24ebd +keywords: ["dispatch routines WDK kernel , required", "required dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Required Dispatch Routines + + +## + + +Most drivers must handle the following *Dispatch* routines: + +- [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) + + [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) indicates a request involving PnP device recognition, hardware configuration, or resource allocation. Such requests are typically sent to a device driver from the PnP manager or from a closely coupled higher-level driver. + +- [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) + + [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) indicates a request pertaining to the power state of either the device or the system. Such requests are sent to the device driver by either the power manager or a closely coupled higher-level driver. + +- [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) + + [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) indicates either that a user-mode protected subsystem, possibly on behalf of an application or subsystem-specific driver, has requested a handle for the file object associated with the target device object, or that a higher-level driver is connecting or attaching its device object to the target device object. + +- [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) + + [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720) indicates that the last handle of the file object that was associated the target device object has been closed and released. All I/O requests have been completed or canceled, so there are no outstanding references to the file object pointer. + +- [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) + + [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) indicates an I/O request to transfer data from the underlying physical device to the system. + +- [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) + + [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) indicates an I/O request to transfer data from the system to the underlying physical device. + +- [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) + + [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) indicates a request that contains a system-defined, device-type-specific I/O control code specifying a device type-specific operation. Higher-level drivers pass these IRPs on to their underlying device drivers, which typically process the request by accessing the device. + +- [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) + + [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) indicates a request sent to the device driver, in most cases from a closely coupled higher-level driver, usually with a privately defined, driver-specific and device-type-specific or device-specific I/O control code requesting a device-type-specific or device-specific operation. + + Only certain kinds of drivers are required to handle system-defined internal device I/O control requests, including certain SCSI drivers, keyboard or mouse device drivers, and parallel drivers that interoperate with system-supplied drivers. + +- [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) + + [**IRP\_MJ\_SYSTEM\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550813) is used to specify WMI requests to drivers. For more information about WMI, see [Windows Management Instrumentation](implementing-wmi.md). + +The dispatch routines that a driver must provide vary according to the type and functionality of the underlying physical device. For device-type-specific information about IRP major function codes that drivers must handle, see the device-type specific documentation in the Windows Driver Kit (WDK). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Required%20Dispatch%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/required-items-in-wmi-classes.md b/windows-driver-docs-pr/kernel/required-items-in-wmi-classes.md new file mode 100644 index 0000000000..2cef363902 --- /dev/null +++ b/windows-driver-docs-pr/kernel/required-items-in-wmi-classes.md @@ -0,0 +1,48 @@ +--- +title: Required Items in WMI Classes +author: windows-driver-content +description: Required Items in WMI Classes +ms.assetid: c978d8d0-5281-481a-b1e5-fd9a57d583d5 +keywords: ["classes WDK WMI", "WMI WDK kernel , classes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Required Items in WMI Classes + + +## + + +All class definitions except embedded classes must include the items **InstanceName** and **Active**, which must appear exactly as shown: + +``` +//WMI class definition +[ + //Class qualifiers +] +ClassName : BaseClassName +{ + [key, read] + string InstanceName; + [read] + boolean Active; + + // Driver-defined data items +} +``` + +The **InstanceName** and **Active** items are required and used internally by WMI. The MOF class definitions of a driver's data and event blocks must include these items, but the driver must not set these items when responding to a query for the data block or sending an event, because they are not part of the driver's data block. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Required%20Items%20in%20WMI%20Classes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/required-support-for-device-power-states.md b/windows-driver-docs-pr/kernel/required-support-for-device-power-states.md new file mode 100644 index 0000000000..ca5c9ceec2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/required-support-for-device-power-states.md @@ -0,0 +1,48 @@ +--- +title: Required Support for Device Power States +author: windows-driver-content +description: Required Support for Device Power States +ms.assetid: f7218f2a-d4ad-4b9a-af90-057801e714a2 +keywords: ["continuous power WDK kernel", "delays WDK power management", "device power states WDK kernel", "hardware WDK power management", "legacy power management WDK kernel", "class drivers WDK power management", "port drivers WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Required Support for Device Power States + + +## + + +Consult the relevant Device Class Power Management Reference Specification to find out which device power states are defined for the class of device with which you are working with and what the operational requirements are for each state. These specifications are available at the [ACPI / Power Management](http://go.microsoft.com/fwlink/p/?linkid=57185) website. + +Legacy devices and other devices for which no power management specification exists should follow the Default Device Class Power Management Specification. The default specification requires: + +- Support for the D0 and D3 states. + +- A driver that saves and restores or reinitializes device context when the device is powered on. + +- A driver that manages the device power policy. + +Class and port drivers supplied with the system and by independent hardware vendors (IHVs) typically support power management. If you are writing a minidriver that links to such a driver, check the relevant class or port driver documentation in the Windows Driver Kit (WDK) to find out the extent of power management support required in the minidriver. The following general guidelines apply: + +- A network adapter driver must conform to the Network Driver Interface Specification 6.00 (NDIS 6.0) (Windows Vista) or to NDIS 5.0 (Windows Server 2003, Windows XP, and Windows 2000). In addition, the driver must conform to the power management requirements for the device setup class of the driver and the Windows version of the driver. + +- Streaming drivers use the power management interfaces in the streaming class driver to handle device power states D0 and D3. To handle device power states D1 and D2, these drivers must use the power management interfaces described in this section. + +- The SCSI port driver manages most of the PnP and power management requirements for the miniport. SCSI miniport drivers must support PnP and power management interfaces along with related routines such as [**HwScsiAdapterControl**](https://msdn.microsoft.com/library/windows/hardware/ff557274). + +- The video port driver manages most of the PnP and power management requirements for the miniport. Video miniport drivers must support miniport-specific routines, which are described elsewhere in the WDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Required%20Support%20for%20Device%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/resource-manager-objects.md b/windows-driver-docs-pr/kernel/resource-manager-objects.md new file mode 100644 index 0000000000..6957979e7d --- /dev/null +++ b/windows-driver-docs-pr/kernel/resource-manager-objects.md @@ -0,0 +1,37 @@ +--- +title: Resource Manager Objects +author: windows-driver-content +description: Resource Manager Objects +ms.assetid: b44f2035-ee9f-453b-b12d-89ca36a8b280 +keywords: ["resource managers WDK KTM , objects", "resource managers WDK KTM", "resource managers WDK KTM , routines", "Kernel Transaction Manager WDK , resource managers", "KTM WDK , resource managers", "resource manager objects WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Resource Manager Objects + + +*Resource manager objects* represent resource managers. Each resource manager must call [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427) to register itself to KTM. + +KTM provides a set of [resource manager object routines](https://msdn.microsoft.com/library/windows/hardware/ff561098) that kernel-mode resource managers can call. KTM also provides a similar set of user-mode routines that user-mode applications can call. For more information about the user-mode routines, see the Microsoft Windows SDK. + +KTM creates a resource manager object when a resource manager calls **ZwCreateResourceManager**. + +[TPS components](understanding-tps-components.md) can call [**ZwOpenResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567026) to open additional handles to a resource manager object. But most TPS designs do not require additional open handles. + +Resource managers close their handles to resource manager objects by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). If the last handle is closed, and if the resource manager still has enlistments to transactions that have not been committed, KTM sends TRANSACTION\_NOTIFY\_ROLLBACK notifications to all resource managers for the transactions that are associated with those enlistments. + +The operating system deletes the object after the last handle is closed and KTM has released all its references to the object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Resource%20Manager%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/responding-to-check-verify-requests-from-the-file-system.md b/windows-driver-docs-pr/kernel/responding-to-check-verify-requests-from-the-file-system.md new file mode 100644 index 0000000000..afa78aac6c --- /dev/null +++ b/windows-driver-docs-pr/kernel/responding-to-check-verify-requests-from-the-file-system.md @@ -0,0 +1,70 @@ +--- +title: Responding to Check-Verify Requests from the File System +author: windows-driver-content +description: Responding to Check-Verify Requests from the File System +ms.assetid: 227e65d6-d746-4b16-978d-4d42be9aeb2c +keywords: ["removable media WDK kernel , check-verify requests", "check-verify requests WDK removable media", "media change requests WDK removable media", "checking removable media changes", "verifying removable media changes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Responding to Check-Verify Requests from the File System + + +## + + +At its discretion, the file system can send an IRP to the device driver's Dispatch entry point for [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests with **Parameters.DeviceIoControl.IoControlCode** in the I/O stack location set to the following: + +IOCTL\_*XXX*\_CHECK\_VERIFY +where *XXX* is the type of device, such as DISK, TAPE, or CDROM. + +The type DISK includes both unpartitionable (floppy) and partitionable removable-media devices. + +If the underlying device driver determines that the media has not changed, the driver should complete the IRP, returning the **IoStatus** block with the following values: + + ++++ + + + + + + + + + + +

Status

Set to STATUS_SUCCESS

Information

Set to zero

+ +  + +In addition, if the device type is DISK or CDROM and the caller specified an output buffer, the driver returns the media change count in the buffer at **Irp->AssociatedIrp.SystemBuffer** and sets **Irp->IoStatus.Information** to **sizeof**(ULONG). By returning this count, the driver gives the caller an opportunity to determine whether the media has changed from its perspective. + +If the underlying device driver determines that the media has changed, it takes a different action depending on whether the volume is mounted. If the volume is mounted (the VPB\_MOUNTED flag is set in the VPB), the driver should do the following: + +1. Set the **Flags** in the **DeviceObject** by ORing **Flags** with DO\_VERIFY\_VOLUME. + +2. Set the **IoStatus** block in the IRP to the following: + - **Status** set to STATUS\_VERIFY\_REQUIRED + - **Information** set to zero + +3. Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the input IRP. + +If the volume is not mounted, the driver must not set the DO\_VERIFY\_VOLUME bit. The driver should set **IoStatus.Status** to STATUS\_IO\_DEVICE\_ERROR, set **IoStatus.Information** to zero, and call **IoCompleteRequest** with the IRP. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Responding%20to%20Check-Verify%20Requests%20from%20the%20File%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/restricting-waits-in-vista.md b/windows-driver-docs-pr/kernel/restricting-waits-in-vista.md new file mode 100644 index 0000000000..9737e0d45f --- /dev/null +++ b/windows-driver-docs-pr/kernel/restricting-waits-in-vista.md @@ -0,0 +1,25 @@ +--- +title: Restricting Waits in Vista +author: windows-driver-content +description: Restricting Waits in Vista +ms.assetid: edcc25d0-bcf6-48f0-832e-3f911bd42142 +--- + +# Restricting Waits in Vista + + +Because many device driver developers use [Synchronous I/O Programming Techniques](synchronous-i-o-programming.md), Windows can slow down or "freeze up" while a device is taking time to respond. To reduce this problem, the I/O Manager in Vista will stop execution of programs that are "stuck" waiting for a device to respond after a few moments. + +**Note**   It is strongly recommended that [Synchronous I/O Programming Techniques](synchronous-i-o-programming.md) are avoided in your device driver. If Vista stops execution of your driver code because your driver is waiting for a device, your device may be left in an unknown state. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Restricting%20Waits%20in%20Vista%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/reusing-irps.md b/windows-driver-docs-pr/kernel/reusing-irps.md new file mode 100644 index 0000000000..e70a9c8fda --- /dev/null +++ b/windows-driver-docs-pr/kernel/reusing-irps.md @@ -0,0 +1,40 @@ +--- +title: Reusing IRPs +author: windows-driver-content +description: Reusing IRPs +ms.assetid: 19b09cf8-b88d-4808-9af0-038d3d02dceb +keywords: ["IRPs WDK kernel , reusing", "reusing IRPs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Reusing IRPs + + +## + + +Under certain circumstances, drivers can *reuse* IRPs. The driver can allocate a pool of memory buffers that it uses to hold IRPs as they need to be created. + +Drivers must not attempt to reuse IRPs issued by the I/O manager. In particular, drivers should not attempt to reuse IRPs created by the [**IoMakeAssociatedIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549397), [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330), [**IoBuildAsynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548310), or [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318) routines. + +Drivers can safely reuse IRPs that they have created, as follows: + +1. If a driver allocates an IRP as raw memory (for example, by calling [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520)), and then initializes it with [**IoInitializeIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549315), then it can safely call **IoInitializeIrp** or [**IoReuseIrp**](https://msdn.microsoft.com/library/windows/hardware/ff549661) to reinitialize the memory buffer. + +2. On Microsoft Windows 2000 and later operating systems, drivers that create an IRP with [**IoAllocateIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548257) can reuse the IRP by calling **IoReuseIrp**. + +3. If a driver allocates an IRP by calling **IoAllocateIrp** with the *ChargeQuota* parameter set to **FALSE**, then it can safely use **IoInitializeIrp** to reinitialize the IRP. Drivers that must work on Windows 98/Me can use this method as a work-around. Drivers designed strictly for Windows 2000 and later operating systems should use the previous method. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Reusing%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/rtlenlargedintegermultiply.md b/windows-driver-docs-pr/kernel/rtlenlargedintegermultiply.md new file mode 100644 index 0000000000..8e4e6827df --- /dev/null +++ b/windows-driver-docs-pr/kernel/rtlenlargedintegermultiply.md @@ -0,0 +1,150 @@ +--- +title: Windows kernel run-time library obsolete routines +author: windows-driver-content +description: Windows kernel run-time library obsolete routines +ms.assetid: cd9aa441-a7f2-42b1-8319-611bf53c995d +--- + +# Windows kernel run-time library obsolete routines + + +The following run-time library obsolete routines are exported to support existing driver binaries: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Obsolete routineDescription
RtlEnlargedIntegerMultiply

For better performance, use the [RtlLongMult](https://msdn.microsoft.com/library/windows/hardware/hh451490) routine if the result will fit into a 32-bit signed integer. Otherwise, use the compiler support for 64-bit integer operations.

RtlEnlargedUnsignedDivide

For better performance, use the compiler support for 64-bit integer operations.

RtlEnlargedUnsignedMultiply

For better performance, use the [RtlULongMult](https://msdn.microsoft.com/library/windows/hardware/hh451490) routine if the result will fit into a 32-bit unsigned integer. Otherwise, use the compiler support for 64-bit integer operations.

RtlExtendedIntegerMultiply

For better performance, use the compiler support for 64-bit integer operations.

RtlExtendedLargeIntegerDivide

For better performance, use the compiler support for 64-bit integer operations.

RtlExtendedMagicDivide

For better performance, use the compiler support for 64-bit integer operations.

RtlFillBytes

Fills a caller-supplied buffer with the given unsigned character. Use [RtlFillMemory](https://msdn.microsoft.com/library/windows/hardware/ff561870) instead.

RtlLargeIntegerAdd

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerAnd

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerArithmeticShift

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerDivide

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerEqualTo

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerEqualToZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerGreaterOrEqualToZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerGreaterThan

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerGreaterThanOrEqualTo

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerGreaterThanZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerLessOrEqualToZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerLessThan

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerLessThanOrEqualTo

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerLessThanZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerNegate

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerNotEqualTo

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerNotEqualToZero

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerShiftLeft

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerShiftRight

For better performance, use the compiler support for 64-bit integer operations.

RtlLargeIntegerSubtract

For better performance, use the compiler support for 64-bit integer operations.

RtlZeroBytes

Fills a block of memory with zeros, given a pointer to the block and the length, in bytes, to be filled. For better performance, use [RtlZeroMemory](https://msdn.microsoft.com/library/windows/hardware/ff563610).

+ +  + +## Related topics +[**RtlFillMemory**](https://msdn.microsoft.com/library/windows/hardware/ff561870) +[**RtlLongMult**](https://msdn.microsoft.com/library/windows/hardware/hh451490) +[**RtlZeroMemory**](https://msdn.microsoft.com/library/windows/hardware/ff563610) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20kernel%20run-time%20library%20obsolete%20routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/rules-for-handling-power-irps.md b/windows-driver-docs-pr/kernel/rules-for-handling-power-irps.md new file mode 100644 index 0000000000..5252cd6fac --- /dev/null +++ b/windows-driver-docs-pr/kernel/rules-for-handling-power-irps.md @@ -0,0 +1,44 @@ +--- +title: Rules for Handling Power IRPs +author: windows-driver-content +description: Rules for Handling Power IRPs +ms.assetid: ea4a1c57-6184-4160-bf23-b86e3e403388 +keywords: ["power management WDK kernel , IRPs", "IRPs WDK power management", "power IRPs WDK kernel", "power IRPs WDK kernel , rules", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Rules for Handling Power IRPs + + +## + + +Drivers that support power management must conform to certain rules pertaining to: + +* [Calling IoCallDriver versus calling PoCallDriver](calling-iocalldriver-versus-calling-pocalldriver.md) to pass power IRPs + +* [Calling PoStartNextPowerIrp](calling-postartnextpowerirp.md) to start the next power IRP + +* [Passing power IRPs](passing-power-irps.md) down to the next-lower driver + +* [Queuing I/O requests while a device is sleeping](queuing-i-o-requests-while-a-device-is-sleeping.md) + +* [Handling unsupported or unrecognized power IRPs](handling-unsupported-or-unrecognized-power-irps.md) + +* [Calling ExSetTimerResolution while processing a power IRP](calling-exsettimerresolution-while-processing-a-power-irp.md) + +The sections that follow describe how drivers should perform these tasks. + +For a list of power management IRPs, see [Power Management Minor IRPs](power-management-minor-irps.md). + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Rules%20for%20Handling%20Power%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/rules-for-implementing-dispatchcreate--dispatchclose--and-dispatchcrea.md b/windows-driver-docs-pr/kernel/rules-for-implementing-dispatchcreate--dispatchclose--and-dispatchcrea.md new file mode 100644 index 0000000000..4476430015 --- /dev/null +++ b/windows-driver-docs-pr/kernel/rules-for-implementing-dispatchcreate--dispatchclose--and-dispatchcrea.md @@ -0,0 +1,41 @@ +--- +title: Rules for Implementing DispatchCreate, DispatchClose, and DispatchCreateClose Routines +author: windows-driver-content +description: Rules for Implementing DispatchCreate, DispatchClose, and DispatchCreateClose Routines +ms.assetid: 4ce37675-92a6-41c2-b386-6570c989e56c +keywords: ["dispatch routines WDK kernel , DispatchCreate routine", "dispatch routines WDK kernel , DispatchClose routine", "dispatch routines WDK kernel , DispatchCreateClose routine", "DispatchCreateClose routine", "DispatchClose routine", "DispatchCreate routine", "IRP_MJ_CREATE I/O function code", "IRP_MJ_CLOSE I/O function code", "create dispatch routines WDK kernel", "close dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Rules for Implementing DispatchCreate, DispatchClose, and DispatchCreateClose Routines + + +## + + +Keep the following points in mind when implementing *DispatchCreate*, *DispatchClose*, and *DispatchCreateClose* routines: + +- At a minimum, the routine must do the following: + 1. Set the **Status** field of the input IRP's I/O status block with an appropriate NTSTATUS, usually STATUS\_SUCCESS. + 2. Set the **Information** field of the input IRP's I/O status block to zero. + 3. Call **IoCompleteRequest** with the IRP and a *PriorityBoost* of IO\_NO\_INCREMENT. + 4. Return the NTSTATUS that it set in the **Status** field of the IRP's I/O status block. +- In a highest-level or intermediate driver, the routine might have to do additional work to process a create or close request, depending on the nature of its device or of the underlying device, and on the design of the driver. + +- For a create request to open a file object that represents a logical or physical device, a highest-level driver should check the **FileObject.FileName** in the I/O stack location and complete the IRP with STATUS\_SUCCESS if the Unicode string at **FileName** has a zero length. Otherwise, it should complete the IRP with STATUS\_INVALID\_PARAMETER. + +- The routines of lowest-level drivers are called only when the next-higher-level driver calls **IoAttachDeviceToDeviceStack**, **IoGetDeviceObjectPointer**, or **IoAttachDevice**. The lowest-level driver in a chain of layered drivers frequently does only the minimum required processing of a create or close request. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Rules%20for%20Implementing%20DispatchCreate,%20DispatchClose,%20and%20DispatchCreateClose%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/run-down-protection.md b/windows-driver-docs-pr/kernel/run-down-protection.md new file mode 100644 index 0000000000..43f9a5c876 --- /dev/null +++ b/windows-driver-docs-pr/kernel/run-down-protection.md @@ -0,0 +1,72 @@ +--- +title: Run-Down Protection +author: windows-driver-content +description: Starting with Windows XP, run-down protection is available to kernel-mode drivers. Drivers can use run-down protection to safely access objects in shared system memory that are created and deleted by another kernel-mode driver. +ms.assetid: AF451636-DBA0-4905-9723-73EE7AA9483E +--- + +# Run-Down Protection + + +Starting with Windows XP, run-down protection is available to kernel-mode drivers. Drivers can use run-down protection to safely access objects in shared system memory that are created and deleted by another kernel-mode driver. + +An object is said to be *run down* if all outstanding accesses of the object are finished and no new requests to access the object will be granted. For example, a shared object might need to be run down so that it can be deleted and replaced with a new object. + +The driver that owns the shared object can enable other drivers to acquire and release run-down protection on the object. When run-down protection is in effect, a driver other than the owner can access the object without risk that the owner will delete the object before the access completes. Before the access starts, the accessing driver requests run-down protection on the object. For a long-lived object, this request is nearly always granted. After the access finishes, the accessing driver releases its previously acquired run-down protection on the object. + +## Primary run-down protection routines + + +To start sharing an object, the driver that owns the object calls the [**ExInitializeRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569373) routine to initialize run-down protection on the object. After this call, other drivers that access the object can acquire and release run-down protection on the object. + +A driver that accesses the shared object calls the [**ExAcquireRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569371) routine to request run-down protection on the object. After the access is finished, this driver calls the [**ExReleaseRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569375) routine to release run-down protection on the object. + +If the owning driver determines that the shared object must be deleted, this driver waits to delete the object until all outstanding accesses of the object are finished. + +In preparation to delete the shared object, the owning driver calls the [**ExWaitForRundownProtectionRelease**](https://msdn.microsoft.com/library/windows/hardware/jj569378) routine to wait for the object to run down. During this call, **ExWaitForRundownProtectionRelease** waits for all previously granted instances of run-down protection on the object to be released, but prevents new requests for run-down protection on the object from being granted. After the last protected access finishes and all instances of run-down protection are released, **ExWaitForRundownProtectionRelease** returns, and the owning driver can safely delete the object. + +**ExWaitForRundownProtectionRelease** blocks the execution of the calling driver thread until all drivers that hold run-down protection on the shared object release this protection. To prevent **ExWaitForRundownProtectionRelease** from blocking execution for excessively long periods, drivers threads that access the shared object should avoid being suspended while they hold run-down protection on the object. For this reason, accessing drivers should call **ExAcquireRundownProtection** and **ExReleaseRundownProtection** within a critical region or guarded region, or while running at IRQL = APC\_LEVEL. + +## Uses for run-down protection + + +Run-down protection is particularly useful for providing access to a shared object that is nearly always available but might occasionally need to be deleted and replaced. Drivers that access data or that call routines in this object must not try to access the object after it is deleted. Otherwise, these invalid accesses might cause unpredictable behavior, data corruption, or even system failure. + +For example, an antivirus driver typically stays loaded in memory when the operating system is running. Occasionally, this driver might need to be unloaded and replaced with an updated release of the driver. Other drivers send I/O requests to the antivirus driver to access the data and routines in this driver. Before sending an I/O request, a kernel component, such as a file system filter manager, can acquire run-down protection to guard against premature unloading of the antivirus driver while it handles the I/O request. After the I/O request completes, run-down protection can be released. + +Run-down protection does not serialize accesses to a shared object. If two or more accessing drivers can simultaneously hold run-down protection on an object, and accesses to the object must be serialized, some other mechanism, such as a mutual-exclusion lock, must be used to serialize the accesses. + +## The EX\_RUNDOWN\_REF structure + + +An [**EX\_RUNDOWN\_REF**](https://msdn.microsoft.com/library/windows/hardware/jj569379) structure tracks the status of run-down protection on a shared object. This structure is opaque to drivers. The system-supplied run-down protection routines use this structure to count the number of instances of run-down protection that are currently in effect on the object. These routines also use this structure to track whether the object is run down or is in the process of being run down. + +To start sharing an object, the driver that owns the object calls **ExInitializeRundownProtection** to initialize the **EX\_RUNDOWN\_REF** structure associated with the object. After initialization, the owning driver can make this structure available to other drivers that require access to the object. The accessing drivers pass this structure as a parameter to the **ExAcquireRundownProtection** and **ExReleaseRundownProtection** calls that acquire and release run-down protection on the object. The owning driver passes this structure as a parameter to the **ExWaitForRundownProtectionRelease** call that waits for the object to run down so that it can be safely deleted. + +## Comparison to locks + + +Run-down protection is one of several ways to guarantee safe access to a shared object. Another approach is to use a mutual-exclusion software lock. If a driver requires access to an object that is currently locked by another driver, the first driver must wait for the second driver to release the lock. However, acquiring and releasing locks can become a performance bottleneck, and locks can consume large amounts of memory. If used incorrectly, locks might cause drivers that compete for the same shared objects to become deadlocked. Efforts to detect and avoid deadlocks typically require the diversion of substantial computing resources. + +In contrast to locks, run-down protection has relatively lightweight processing time and memory requirements. A simple reference count is associated with the object to ensure that deletion of the object is deferred until all outstanding accesses of the object are completed. With this approach, atomic, interlocked hardware instructions can be used instead of mutual-exclusion software locks to guarantee safe access to an object. Calls to acquire and release run-down protection are typically very fast. The benefits of using a lightweight mechanism, such as run-down protection, can be significant for a shared object that has a long life and is shared among many drivers. + +## Other run-down protection routines + + +Several other run-down protection routines are available, in addition to those that were mentioned previously. These additional routines might used by some drivers. + +The [**ExReInitializeRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569374) routine enables a previously used [**EX\_RUNDOWN\_REF**](https://msdn.microsoft.com/library/windows/hardware/jj569379) structure to be associated with a new object, and initializes run-down protection on this object. + +The [**ExRundownCompleted**](https://msdn.microsoft.com/library/windows/hardware/jj569377) routine updates the **EX\_RUNDOWN\_REF** structure to indicate that the run down of the associated object has completed. + +The [**ExAcquireRundownProtectionEx**](https://msdn.microsoft.com/library/windows/hardware/jj569372) and [**ExReleaseRundownProtectionEx**](https://msdn.microsoft.com/library/windows/hardware/jj569376) routines are similar to [**ExAcquireRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569371) and [**ExReleaseRundownProtection**](https://msdn.microsoft.com/library/windows/hardware/jj569375). These four routines increment or decrement the count of the instances of run-down protection that are in effect on a shared object. Whereas **ExAcquireRundownProtection** and **ExReleaseRundownProtection** increment and decrement this count by one, **ExAcquireRundownProtectionEx** and **ExReleaseRundownProtectionEx** increment and decrement the count by arbitrary amounts. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Run-Down%20Protection%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sample-device-and-driver-configuration.md b/windows-driver-docs-pr/kernel/sample-device-and-driver-configuration.md new file mode 100644 index 0000000000..b357d61db9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/sample-device-and-driver-configuration.md @@ -0,0 +1,52 @@ +--- +title: Sample Device and Driver Configuration +author: windows-driver-content +description: Sample Device and Driver Configuration +ms.assetid: 803262b2-0882-46d0-9c4f-63e59eb4beaa +keywords: ["WDM drivers WDK kernel , configurations", "WDM drivers WDK kernel , layered drivers", "layered drivers WDK kernel", "driver layers WDK WDM", "keyboards WDK kernel", "mouse WDK kernel", "hardware configurations WDK kernel", "intermediate drivers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sample Device and Driver Configuration + + +## + + +This section illustrates the relationship between the hardware and driver configurations, using the keyboard and mouse devices as an example. Configurations differ for other devices. For complete information about any device configuration, see the device-specific documentation in the Windows Driver Kit (WDK). + +### + +The following figure shows two possible hardware configurations for the keyboard and mouse devices: + +- Each connected directly somewhere on the system bus + +- Both connected through a keyboard and auxiliary device controller + +![diagram illustrating keyboard and mouse hardware configurations](images/2kbdmuhw.png) + +### + +The following figure illustrates the corresponding layered drivers for I/O operations on the devices shown in the previous figure. + +![keyboard and mouse driver layers](images/2samplyr.png) + +Note that drivers of keyboard and mouse devices, whatever the hardware configuration, can use the system's keyboard class and mouse class drivers to handle hardware-independent operations. These are called [*class drivers*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-class-driver) because each supplies system-required but hardware-independent support for a particular class of device. + +A corresponding [*port driver*](https://msdn.microsoft.com/library/windows/hardware/ff556325#wdkgloss-port-driver) implements the device-specific support to carry out required I/O operations on each physical device. The system's (i8042) keyboard and auxiliary device port driver for x86-based platforms manages device-specific operations for both mouse and keyboard. In a hardware configuration where each device is separately connected, as shown in the figure illustrating the keyboard and mouse hardware configurations, each system class driver can be layered over separate device-specific port drivers, or a single driver for each device could be implemented as a separate, monolithic (lowest-level) driver. + +A new intermediate driver, such as a PnP filter driver, could be added to the configuration in the figure illustrating the keyboard and mouse driver layers. For example, a filter driver added above the keyboard class driver might filter keyboard input in a platform-specific manner before passing it through the I/O services to the subsystem that requested it. Such a filter driver must recognize the same IRPs and IOCTLs as the keyboard class driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sample%20Device%20and%20Driver%20Configuration%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sample-kernel-mode-drivers.md b/windows-driver-docs-pr/kernel/sample-kernel-mode-drivers.md new file mode 100644 index 0000000000..3904aaa6bb --- /dev/null +++ b/windows-driver-docs-pr/kernel/sample-kernel-mode-drivers.md @@ -0,0 +1,47 @@ +--- +title: Sample Kernel-Mode Drivers +author: windows-driver-content +description: Sample Kernel-Mode Drivers +ms.assetid: 09d08e07-e991-458f-aedf-018a0dd20af5 +keywords: ["kernel-mode drivers WDK , samples", "sample drivers WDK kernel-mode"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sample Kernel-Mode Drivers + + +## + + +The WDK provides various sample kernel-mode drivers. After you have installed the WDK, the src\\general subdirectory contains sample driver code that is applicable to all kernel-mode drivers. These samples include the following: + +**toaster** +Provides sample code for a set of drivers that conform to the [Windows Driver Model](windows-driver-model.md) (WDM). This sample also includes sample installation software. + +**ioctl** +Demonstrates how drivers should support I/O control codes. + +**event** +Demonstrates techniques that kernel-mode drivers can use to notify applications of hardware events, if the application requests notification. One technique uses [event objects](event-objects.md) and the other relies on [queuing](queuing-and-dequeuing-irps.md) the notification request until an event occurs. + +**cancel** +Demonstrates the use of [cancel-safe IRP queues](cancel-safe-irp-queues.md). + +**tracedrv** +Shows how to use [WPP software tracing](https://msdn.microsoft.com/library/windows/hardware/ff556204). + +Other subdirectories of the \\src directory contain sample code for kernel-mode drivers for various types of hardware. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sample%20Kernel-Mode%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sddl-for-device-objects.md b/windows-driver-docs-pr/kernel/sddl-for-device-objects.md new file mode 100644 index 0000000000..ecd89ee462 --- /dev/null +++ b/windows-driver-docs-pr/kernel/sddl-for-device-objects.md @@ -0,0 +1,335 @@ +--- +title: SDDL for Device Objects +author: windows-driver-content +description: SDDL for Device Objects +ms.assetid: c0e4432a-4429-4ecd-a2e5-f93a9e3caf48 +keywords: ["device objects WDK kernel , security", "security WDK device objects", "Security Descriptor Definition Language WDK device objects", "SDDL WDK device objects", "IoCreateDeviceSecure", "security descriptors WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SDDL for Device Objects + + +## + + +The Security Descriptor Definition Language (SDDL) is used to represent security descriptors. Security for device objects can be specified by an SDDL string that is [placed in an INF file](https://msdn.microsoft.com/library/windows/hardware/ff540212) or passed to [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407). The [Security Descriptor Definition Language](https://msdn.microsoft.com/library/windows/desktop/aa379567) is fully documented in the Microsoft Windows SDK documentation. + +While INF files support the full range of SDDL, only a subset of the language is supported by the **IoCreateDeviceSecure** routine. This subset is defined here. + +SDDL strings for device objects are of the form "D:P" followed by one or more expressions of the form "(A;;*Access*;;;*SID*)". The *SID* value specifies a security identifier that determines to whom the *Access* value applies (for example, a user or group). The *Access* value specifies the access rights allowed for the SID. The *Access* and *SID* values are as follows. + +**Note**  When using SDDL for device objects, your driver must link against Wdmsec.lib. + +  + +*Access* +Specifies an [**ACCESS\_MASK**](access-mask.md) value that determines the allowed access. This value can be written either as a hexadecimal value in the form "0x*hex*", or as a sequence of two-letter symbolic codes that represent access rights. + +The following codes can be used to specify generic access rights. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
CodeGeneric access right

GA

GENERIC_ALL

GR

GENERIC_READ

GW

GENERIC_WRITE

GX

GENERIC_EXECUTE

+ +  + +The following codes can be used to specify specific access rights. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
CodeSpecific access right

RC

READ_CONTROL

SD

DELETE

WD

WRITE_DAC

WO

WRITE_OWNER

+ +  + +Note that GENERIC\_ALL grants all the rights listed in the above two tables, including the ability to change the ACL. + +*SID* +Specifies the SID that is granted the specified access. SIDs represent accounts, aliases, groups, users, or computers. + +The following SIDs represent *accounts* on the machine. + + ++++ + + + + + + + + + + + + + + + + + + + + +
SIDDescription

SY

System

+

Represents the operating system itself, including its user-mode components.

LS

Local Service

+

A predefined account for local services (which also belongs to Authenticated and World). This SID is available starting with Windows XP.

NS

Network Service

+

A predefined account for network services (which also belongs to Authenticated and World). This SID is available starting with Windows XP.

+ +  + +The following SIDs represent *groups* on the machine. + + ++++ + + + + + + + + + + + + + + + + + + + + +
SIDDescription

BA

Administrators

+

The built-in Administrators group on the machine.

BU

Built-in User Group

+

Group covering all local user accounts, and users on the domain.

BG

Built-in Guest Group

+

Group covering users logging in using the local or domain guest account.

+ +  + +The following SIDs describe the extent to which a user has been authenticated. + + ++++ + + + + + + + + + + + + + + + + +
SIDDescription

AU

Authenticated Users

+

Any user recognized by the local machine or by a domain. Note that users logged in using the Builtin Guest account are not authenticated. However, members of the Guests group with individual accounts on the machine or the domain are authenticated.

AN

Anonymous Logged-on User

+

Any user logged on without an identity, such as an anonymous network session. Note that users logging in using the Builtin Guest account are neither authenticated nor anonymous. This SID is available starting with Windows XP.

+ +  + +The following SIDs describe how the user logged into the machine. + + ++++ + + + + + + + + + + + + + + + + + + + + +
SIDDescription

IU

Interactive Users

+

Users who initially logged onto the machine "interactively", such as local logons and Remote Desktops logons.

NU

Network Logon User

+

Users accessing the machine remotely, without interactive desktop access (for example, file sharing or RPC calls).

WD

World

+

Before Windows XP, this SID covered every session, whether authenticated users, anonymous users, or the Builtin Guest account.

+

Starting with Windows XP, this SID does not cover anonymous logon sessions; it covers only authenticated users and the Builtin Guest account.

+

Note that untrusted or "restricted" code is also not covered by the World SID. For more information, see the description of the Restricted Code (RC) SID in the following table.

+ +  + +The following SIDs deserve special mention. + + ++++ + + + + + + + + + + + + + + + + +
SIDDescription

RC

Restricted Code

+

This SID is used to control access by untrusted code. ACL validation against tokens with RC consists of two checks, one against the token's normal list of SIDs (containing WD for instance), and one against a second list (typically containing RC and a subset of the original token SIDs). Access is granted only if a token passes both tests. As such, RC actually works in combination with other SIDs.

+

Any ACL that specifies RC must also specify WD. When RC is paired with WD in an ACL, a superset of Everyone including untrusted code is described.

+

Untrusted code might be code launched using the Run As option in Explorer. By default, World does not cover untrusted code.

UD

User-Mode Drivers

+

This SID grants access to user-mode drivers. Currently, this SID covers only drivers that are written for the User-Mode Driver Framework (UMDF). This SID is available starting with Windows 8.

+

In earlier versions of Windows, which do not recognize the "UD" abbreviation, you must specify the fully qualified form of this SID (S-1-5-84-0-0-0-0-0) to grant access to UMDF drivers. For more information, see [Controlling Device Access](https://msdn.microsoft.com/library/windows/hardware/hh439567) in the User-Mode Driver Framework documentation.

+ +  + +### SDDL Examples For Device Objects + +This section describes the predefined SDDL strings found in Wdmsec.h. You can also use these as templates to define new SDDL strings for device objects. + +SDDL\_DEVOBJ\_KERNEL\_ONLY + +**"D:P"** + +SDDL\_DEVOBJ\_KERNEL\_ONLY is the "empty" ACL. User-mode code (including processes running as system) cannot open the device. + +A PnP bus driver could use this descriptor when creating a PDO. The INF file could then specify looser security settings for the device. By specifying this descriptor, the bus driver would ensure that no attempt to open the device before the INF was processed would succeed. + +Similarly, a non-WDM driver could use this descriptor to make its device objects inaccessible until the appropriate user-mode program (such as an installer) sets the final security descriptor in the registry. + +In all of these cases, the default is tight security, loosened as necessary. + +SDDL\_DEVOBJ\_SYS\_ALL + +**"D:P(A;;GA;;;SY)"** + +SDDL\_DEVOBJ\_SYS\_ALL is similar to SDDL\_DEVOBJ\_KERNEL\_ONLY, except that in addition to kernel-mode code, user-mode code running as System is also allowed to open the device for any access. + +A legacy driver might use this ACL to start with tight security settings, and let its service open the device up at run time to individual users by using the **SetFileSecurity** user-mode function. In this case, the service would have to be running as System. + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_ALL + +**"D:P(A;;GA;;;SY)(A;;GA;;;BA)"** + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_ALL allows the kernel, system, and administrator complete control over the device. No other users may access the device. + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_RWX\_WORLD\_R + +**"D:P(A;;GA;;;SY)(A;;GRGWGX;;;BA)(A;;GR;;;WD)"** + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_RWX\_WORLD\_R allows the kernel and system complete control over the device. By default the administrator can access the entire device, but cannot change the ACL (the administrator must take control of the device first.) + +Everyone (the World SID) is given read access. Untrusted code cannot access the device (untrusted code might be code launched using the Run As option in Explorer. By default, World does not cover Restricted code.) + +Also note that traversal access is not granted to normal users. As such, this might not be an appropriate descriptor for a device with a namespace. + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_RWX\_WORLD\_R\_RES\_R + +**"D:P(A;;GA;;;SY)(A;;GRGWGX;;;BA)(A;;GR;;;WD)(A;;GR;;;RC)"** + +SDDL\_DEVOBJ\_SYS\_ALL\_ADM\_RWX\_WORLD\_R\_RES\_R allows the kernel and system complete control over the device. By default the administrator can access the entire device, but cannot change the ACL (the administrator must take control of the device first.) + +Everyone (the World SID) is given read access. In addition, untrusted code is also allowed to access code. Untrusted code might be code launched using the Run As option in Explorer. By default, World does not cover Restricted code. + +Also note that traversal access is not granted to normal users. As such, this might not be an appropriate descriptor for a device with a namespace. + +  + +Note that the above SDDL strings do not include any inheritance modifiers. As such, they are only appropriate for device objects and should not be used for files or registry keys. For more information about specifying inheritance using SDDL, see the Microsoft Windows SDK documentation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20SDDL%20for%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/section-objects-and-views.md b/windows-driver-docs-pr/kernel/section-objects-and-views.md new file mode 100644 index 0000000000..fc8b104184 --- /dev/null +++ b/windows-driver-docs-pr/kernel/section-objects-and-views.md @@ -0,0 +1,40 @@ +--- +title: Section Objects and Views +author: windows-driver-content +description: Section Objects and Views +ms.assetid: 9c60b761-6326-4d1a-b884-cc2acee4bedd +keywords: ["memory management WDK kernel , section objects", "memory management WDK kernel , shared memory", "shared memory WDK kernel", "section objects WDK kernel", "memory sections WDK kernel", "sharing memory address space", "views WDK memory section"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Section Objects and Views + + +## + + +A *section object* represents a section of memory that can be shared. A process can use a section object to share parts of its memory address space (memory sections) with other processes. Section objects also provide the mechanism by which a process can map a file into its memory address space. + +Each memory section has one or more corresponding *views*. A view of a section is a part of the section that is actually visible to a process. The act of creating a view for a section is known as *mapping* a view of the section. Each process that is manipulating the contents of a section has its own view; a process can also have multiple views (to the same or different sections). + +This section contains the following topics: + +[File-Backed and Page-File-Backed Sections](file-backed-and-page-file-backed-sections.md) + +[Managing Memory Sections](managing-memory-sections.md) + +[Security Issues for Section Objects and Views](security-issues-for-section-objects-and-views.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Section%20Objects%20and%20Views%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/securing-device-objects.md b/windows-driver-docs-pr/kernel/securing-device-objects.md new file mode 100644 index 0000000000..44a194ba68 --- /dev/null +++ b/windows-driver-docs-pr/kernel/securing-device-objects.md @@ -0,0 +1,42 @@ +--- +title: Securing Device Objects +author: windows-driver-content +description: Securing Device Objects +ms.assetid: 41e86924-e1bf-4ac6-9d7b-3799ed0d796c +keywords: ["access rights WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Securing Device Objects + + +## + + +This section documents how to secure a driver's device objects from unauthorized access. It contains the following sections: + +[Controlling Device Access](controlling-device-access.md) + +[Controlling Device Namespace Access](controlling-device-namespace-access.md) + +[SDDL for Device Objects](sddl-for-device-objects.md) + +There are two aspects of a device object that must be secured: + +- Access to the device itself. This is documented in [Controlling Device Access](controlling-device-access.md). + +- Access to the device's namespace. This is documented in [Controlling Device Namespace Access](controlling-device-namespace-access.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Securing%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/security-descriptors.md b/windows-driver-docs-pr/kernel/security-descriptors.md new file mode 100644 index 0000000000..3780739e7b --- /dev/null +++ b/windows-driver-docs-pr/kernel/security-descriptors.md @@ -0,0 +1,49 @@ +--- +title: Security Descriptors +author: windows-driver-content +description: Security Descriptors +ms.assetid: a5edd5e8-6fc7-4ab0-aebc-f0cd8e9299b6 +keywords: ["security descriptors WDK objects", "system ACL WDK objects", "SACL WDK objects", "discretionary ACL WDK objects", "DACL WDK objects", "access control lists WDK objects", "ACL WDK objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security Descriptors + + +Every object has a *security descriptor*, which contains the security settings for an object. In kernel-mode, the opaque [**SECURITY\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff563689) data type represents a security descriptor. + +Information in a security descriptor is stored in *access control lists* (ACLs). An access control list is made up of a series of *access control entries* (ACEs). + +A security descriptor has two separate ACLs: + +- A *system ACL* (SACL), which determines which operations on an object are logged. + +- A *discretionary ACL* (DACL), which determines which users can perform particular operations on the object. + +Typically, a driver developer is only concerned with discretionary ACLs. For more information about system ACLs, see the Microsoft Windows SDK. + +For a discretionary ACL, each ACE contains three pieces of information: + +- A *security identifier* (SID). The security identifier determines who the ACE applies to. A SID can represent a single user, or a group of users. For example, the World SID represents the set of all users. + +- A set of access rights. For a description of access rights, see [Access Rights](access-rights.md). + +- Whether the set of access rights is granted, or denied. + +For a driver, the most important security descriptors are those for the driver's device objects. For more information, see [Securing Device Objects](securing-device-objects.md). + +For more information about security descriptors in general, see the Windows SDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Security%20Descriptors%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/security-issues-for-i-o-control-codes.md b/windows-driver-docs-pr/kernel/security-issues-for-i-o-control-codes.md new file mode 100644 index 0000000000..3a88b0110a --- /dev/null +++ b/windows-driver-docs-pr/kernel/security-issues-for-i-o-control-codes.md @@ -0,0 +1,52 @@ +--- +title: Security Issues for I/O Control Codes +author: windows-driver-content +description: Security Issues for I/O Control Codes +ms.assetid: cab8aed2-7185-4622-9a8f-bc8eab3c8c59 +keywords: ["I/O control codes WDK kernel , security", "control codes WDK IOCTLs , security", "IOCTLs WDK kernel , security", "security WDK IOCTLs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security Issues for I/O Control Codes + + +## + + +Secure processing of IRPs that contain I/O control codes depends on defining IOCTL codes properly and on carefully examining parameters that the driver receives with the IRP. + +When defining new IOCTL codes, use the following rules: + +- Always specify a *FunctionCode* value that is equal to or greater than 0x800. + +- Always specify a *RequiredAccess* value. The I/O manager does not send IOCTLs if the caller has insufficient access rights. + +- Do not define IOCTL codes that allow callers to read or write nonspecific areas of kernel memory. + +When processing IOCTL codes within a driver, use the following rules: + +- Whenever a driver's dispatch routines test received IOCTL codes, they must always test the entire 32-bit value. + +- Drivers can use [**IoValidateDeviceIoControlAccess**](https://msdn.microsoft.com/library/windows/hardware/ff550418) to dynamically perform stricter access checking than that specified by the *RequiredAccess* value in the definition of the I/O control code. + +- Never read or write more data than the buffer that is pointed to by **Irp->AssociatedIrp.SystemBuffer** can contain. Therefore, always check **Parameters.DeviceIoControl.InputBufferLength** or **Parameters.DeviceIoControl.OutputBufferLength** in the [**IO\_STACK\_LOCATION**](https://msdn.microsoft.com/library/windows/hardware/ff550659) structure to determine buffer limits. + +- Always zero driver-allocated buffers that will contain data intended for an application that originated an IOCTL request. That way, you will not accidentally copy sensitive data to the application. + +- For METHOD\_IN\_DIRECT and METHOD\_OUT\_DIRECT transfers, follow the rules above. Additionally, check for a **NULL** return value from [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559), which indicates that mapping failed or that a zero-length buffer was supplied. + +- For METHOD\_NEITHER transfers, follow the rules that are provided in [Using Neither Buffered Nor Direct I/O](using-neither-buffered-nor-direct-i-o.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Security%20Issues%20for%20I/O%20Control%20Codes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/security-issues-for-section-objects-and-views.md b/windows-driver-docs-pr/kernel/security-issues-for-section-objects-and-views.md new file mode 100644 index 0000000000..637c37152b --- /dev/null +++ b/windows-driver-docs-pr/kernel/security-issues-for-section-objects-and-views.md @@ -0,0 +1,56 @@ +--- +title: Security Issues for Section Objects and Views +author: windows-driver-content +description: Security Issues for Section Objects and Views +ms.assetid: a2044ea1-c90c-4487-850b-d07ac55aea6d +keywords: ["memory sections WDK kernel", "section objects WDK kernel", "views WDK memory section", "security WDK memory section", "protocols WDK memory section"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Security Issues for Section Objects and Views + + +## + + +Drivers that create sections and views that are not to be shared with user mode must use the following protocol when they are working with sections and views: + +- The driver must use a kernel handle when it is opening a handle to the section object. Drivers can make sure that a handle is a kernel handle by either creating it in the system process, or specifying the OBJ\_KERNEL\_HANDLE attribute for the handle. For more information, see [Object Handles](object-handles.md). + +- The view must be mapped only from a system thread. (Otherwise, the view is accessible from the process whose context it is created in.) A driver can make sure that the view is mapped from the system process by using a system worker thread to perform the mapping operation. For more information, see [System Worker Threads](system-worker-threads.md) and [Driver Thread Context](driver-thread-context.md). + +Drivers that share a view with a user-mode process must use the following protocol when they are working with sections and views: + +- The driver, not the user-mode process, must create the section object and map the views. + +- As mentioned earlier, the driver must use a kernel handle when it is opening a handle to the section object. Drivers can make sure that a handle is a kernel handle by either creating it in the system process, or specifying the OBJ\_KERNEL\_HANDLE attribute for the handle. For more information, see [Object Handles](object-handles.md). + +- The view is mapped in the thread context of the process that shares the view. A highest-level driver can guarantee the view is mapped in the current process context by performing the mapping operation in a dispatch routine, such [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287). Dispatch routines of lower-level drivers run in an arbitrary thread context, and thus cannot safely map a view in a dispatch routine. For more information, see [Driver Thread Context](driver-thread-context.md). + +- All memory accesses to the view within the driver must be protected by **try**-**except** blocks. A malicious user-mode application could unmap the view or change the protection state of the view. Either would cause a system crash unless protected by a **try**-**except** block. For more information, see [Handling Exceptions](handling-exceptions.md). + +The driver must also validate the contents of the view as necessary. The driver writer cannot assume that only a trusted user-mode component will have access to the view. + +A driver that must share a section object with a user-mode application (that must be able to create its own views) must use the following protocol: + +- The driver, not the user-mode process, must create the section object. Drivers must never use a handle that was passed from user mode. + +- Before passing the handle to user mode, the driver must call [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) to obtain a reference to the section object. This prevents a malicious application from deleting the section object by closing the handle. The object reference should be stored in the driver's device extension. + +- After the driver is no longer using the section object, it must call [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724) to release the object reference. + +On systems that run Microsoft Windows Server 2003 with Service Pack 1 (SP1) and later versions, only kernel-mode drivers can open \\**Device**\\**PhysicalMemory**. However, drivers can decide to give a handle to a user application. To prevent security issues, only user applications that the driver trusts should be given access to \\**Device**\\**PhysicalMemory**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Security%20Issues%20for%20Section%20Objects%20and%20Views%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/selective-opt-out-pool-nx-optout.md b/windows-driver-docs-pr/kernel/selective-opt-out-pool-nx-optout.md new file mode 100644 index 0000000000..52b213c16a --- /dev/null +++ b/windows-driver-docs-pr/kernel/selective-opt-out-pool-nx-optout.md @@ -0,0 +1,29 @@ +--- +title: Selective Opt-Out POOL_NX_OPTOUT +author: windows-driver-content +description: You can globally enable one of the no-execute (NX) pool opt-in mechanisms for a set of driver source files, and then override this opt-in mechanism for one or more selected source files with POOL_NX_OPTOUT. +ms.assetid: 15AA7CFA-5BEC-4E45-B222-0DE2D620E099 +--- + +# Selective Opt-Out: POOL\_NX\_OPTOUT + + +You can globally enable one of the no-execute (NX) pool opt-in mechanisms for a set of driver source files, and then override this opt-in mechanism for one or more selected source files with POOL\_NX\_OPTOUT. This allows the selected source files to continue to use executable nonpaged memory. You can use the POOL\_NX\_OPTOUT opt-out mechanism with either the POOL\_NX\_OPTIN or the POOL\_NX\_OPTIN\_AUTO opt-in mechanism. For more information, see [NX Pool Opt-In Mechanisms](nx-pool-opt-in-mechanisms.md). + +To use the POOL\_NX\_OUTPUT opt-out mechanism to override the opt-in mechanism in a selected source file, add the following definition to this file: + +`#define POOL_NX_OPTOUT 1` + +This definition overrides the global opt-in settings in the selected file, and prevents instances of the **NonPagedPool** constant name from being replaced. Insert this definition into the file before the first instance of **NonPagedPool** in the file. + +An alternative to using the POOL\_NX\_OPTOUT opt-out mechanism in a source file is to explicitly replace each instance of **NonPagedPool** in the file with **NonPagedPoolExecute**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Selective%20Opt-Out:%20POOL_NX_OPTOUT%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/semaphore-objects.md b/windows-driver-docs-pr/kernel/semaphore-objects.md new file mode 100644 index 0000000000..7d48b5c17d --- /dev/null +++ b/windows-driver-docs-pr/kernel/semaphore-objects.md @@ -0,0 +1,78 @@ +--- +title: Semaphore Objects +author: windows-driver-content +description: Semaphore Objects +ms.assetid: e6703c39-3b47-4d3b-86e7-bf2bf37af493 +keywords: ["kernel dispatcher objects WDK , semaphore objects", "dispatcher objects WDK kernel , semaphore objects", "semaphore objects WDK kernel", "KeInitializeSemaphore", "waiting on semaphore objects", "KeReleaseSemaphore", "counting semaphores WDK kernel", "binary semaphores WDK kernel", "wait states WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Semaphore Objects + + +## + + +Any driver can use a semaphore object to synchronize operations between its driver-created threads and other driver routines. For example, a driver-dedicated thread might put itself into a wait state when there are no outstanding I/O requests for the driver, and the driver's dispatch routines might set the semaphore to the Signaled state just after they queue an IRP. + +The dispatch routines of highest-level drivers, which are run in the context of the thread requesting an I/O operation, might use a semaphore to protect a resource shared among the dispatch routines. Lower-level driver dispatch routines for synchronous I/O operations also might use a semaphore to protect a resource shared among that subset of dispatch routines or with a driver-created thread. + +Any driver that uses a semaphore object must call [**KeInitializeSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff552150) before it waits on or releases the semaphore. The following figure illustrates how a driver with a thread can use a semaphore object. + +![diagram illustrating waiting for a semaphore object](images/3semobj.png) + +As the previous figure shows, such a driver must provide the storage for the semaphore object, which should be resident. The driver can use the [device extension](device-extensions.md) of a driver-created device object, the controller extension if it uses a [controller object](using-controller-objects.md), or nonpaged pool allocated by the driver. + +When the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine calls **KeInitializeSemaphore**, it must pass a pointer to the driver's resident storage for the semaphore object. In addition, the caller must specify a *Count* for the semaphore object, as shown in the previous figure, that determines its initial state (nonzero for Signaled). + +The caller also must specify a *Limit* for the semaphore, which can be either of the following: + +- **Limit = 1** + + When this semaphore is set to the Signaled state, a single thread waiting for the semaphore to be reset to the Not-Signaled state becomes eligible for execution and can access whatever resource is protected by the semaphore. + + This type of semaphore is also called a *binary semaphore* because a thread either has or does not have exclusive access to the semaphore-protected resource. + +- **Limit > 1** + + When this semaphore is set to the Signaled state, some number of threads waiting for the semaphore object to be set to the Not-Signaled state become eligible for execution and can access whatever resource is protected by the semaphore. + + This type of semaphore is called a *counting semaphore* because the routine that sets the semaphore to the Signaled state also specifies how many waiting threads can have their states changed from waiting to ready. The number of such waiting threads can be the *Limit* set when the semaphore was initialized or some number less than this preset *Limit*. + +Few device or intermediate drivers have a single driver-created thread; even fewer have a set of threads that might wait for a semaphore to be acquired or released. Few system-supplied drivers use semaphore objects, and, of those that do, even fewer use a binary semaphore. Although a binary semaphore might seem to be similar in functionality to a [mutex object](mutex-objects.md), a binary semaphore does not provide the built-in protection against deadlocks that a mutex object has for system threads running in SMP machines. + +After a driver with an initialized semaphore is loaded, it can synchronize operations on the semaphore that protects a shared resource. For example, a driver with a device-dedicated thread that manages the queuing of IRPs, such as the system floppy controller driver, might synchronize IRP queuing on a semaphore, as shown in the previous figure: + +1. The thread calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with a pointer to the driver-supplied storage for the initialized semaphore object to put itself into a wait state. + +2. IRPs begin to come in that require device I/O operations. The driver's dispatch routines insert each such IRP into an interlocked queue under spin-lock control and call [**KeReleaseSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff553143) with a pointer to the semaphore object, a driver-determined priority boost for the thread (*Increment*, as shown in the previous figure), an *Adjustment* of 1 that is added to the semaphore's Count as each IRP is queued, and a Boolean *Wait* set to **FALSE**. A nonzero semaphore Count sets the semaphore object to the Signaled state, thereby changing the waiting thread's state to ready. + +3. The kernel dispatches the thread for execution as soon as a processor is available: that is, no other thread with a higher priority is currently in the ready state and there are no kernel-mode routines to be run at a higher IRQL. + + The thread removes an IRP from the interlocked queue under spin-lock control, passes it on to other driver routines for further processing, and calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) again. If the semaphore is still set to the Signaled state (that is, its Count remains nonzero, indicating that more IRPs are in the driver's interlocked queue), the kernel again changes the thread's state from waiting to ready. + + By using a counting semaphore in this manner, such a driver thread "knows" there is an IRP to be removed from the interlocked queue whenever that thread is run. + +Calling [**KeReleaseSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff553143) with the *Wait* parameter set to **TRUE** indicates the caller's intention to immediately call a **KeWait*Xxx*Object**(s) support routine on return from **KeReleaseSemaphore**. + +Consider the following guidelines for setting the *Wait* parameter to KeReleaseSemaphore: + +A pageable thread or pageable driver routine that runs at IRQL PASSIVE\_LEVEL should never call **KeReleaseSemaphore** with the *Wait* parameter set to **TRUE**. Such a call causes a fatal page fault if the caller happens to be paged out between the calls to **KeReleaseSemaphore** and **KeWait*Xxx*Object**(s). + +Any standard driver routine that runs at an IRQL greater than PASSIVE\_LEVEL cannot wait for a nonzero interval on any dispatcher objects without bringing down the system; see [Kernel Dispatcher Objects](kernel-dispatcher-objects.md) for details. However, such a routine can call **KeReleaseSemaphore** while running at an IRQL less than or equal to DISPATCH\_LEVEL. + +For a summary of the IRQLs at which standard driver routines run, see [Managing Hardware Priorities](managing-hardware-priorities.md). For IRQL requirements of a specific support routine, see the routine's reference page. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Semaphore%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-a-device-set-power-irp-in-response-to-a-system-set-power-irp.md b/windows-driver-docs-pr/kernel/sending-a-device-set-power-irp-in-response-to-a-system-set-power-irp.md new file mode 100644 index 0000000000..86b63087cd --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-a-device-set-power-irp-in-response-to-a-system-set-power-irp.md @@ -0,0 +1,68 @@ +--- +title: Sending a Device Set-Power IRP in Response to a System Set-Power IRP +author: windows-driver-content +description: Sending a Device Set-Power IRP in Response to a System Set-Power IRP +ms.assetid: b2029292-d770-4095-8bd7-9358b282216c +keywords: ["sending set-power IRPs", "set-power IRPs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending a Device Set-Power IRP in Response to a System Set-Power IRP + + +## + + +The device power policy owner should take the following steps to respond to a system set-power IRP: + +1. Call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204), passing the current IRP as the *Tag* parameter, to ensure that the driver does not receive a Plug and Play [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while handling the power IRP. + + If **IoAcquireRemoveLock** returns a failure status, the driver should not continue processing the IRP. Instead, starting with Windows Vista, the driver should call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to complete the request and then return the failure status. In Windows Server 2003, Windows XP, and Windows 2000, the driver should first call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776), call **IoCompleteRequest** to complete the IRP, and then return the failure status. + +2. Set up the IRP stack location for the next-lower driver by calling [**IoCopyCurrentIrpStackLocationToNext**](https://msdn.microsoft.com/library/windows/hardware/ff548387). + +3. Set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine in the system set-power IRP. + +4. Call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) to mark the system set-power IRP as pending. + +5. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) (starting with Windows Vista) or [**PoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff559654) (in Windows Server 2003, Windows XP, and Windows 2000) to pass the system set-power IRP to the next-lower driver. + +6. Return STATUS\_PENDING from its [*DispatchPower*](https://msdn.microsoft.com/library/windows/hardware/ff543354) routine. + +In the *IoCompletion* routine (see Step 3 in the preceding list), the device power policy owner sends a device set-power IRP as follows: + +1. Inspect the system set-power IRP to get the requested system power state. Choose an appropriate device power state for that system power state. For further information, see [Determining the Correct Device Power State](determining-the-correct-device-power-state.md). + +2. Call [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) for the device power state determined in Step 1. The power policy owner must send the device set-power request even if the device is already in that state. + +3. Specify a power-completion callback routine (*CompletionFunction*) in the call to **PoRequestPowerIrp** and pass the system set-power IRP in the *Context* buffer. + +4. Return STATUS\_MORE\_PROCESSING\_REQUIRED from the *IoCompletion* routine, so that the driver can finish processing the system set-power IRP in the power-completion callback routine. + +Remember that the device power policy owner not only sends the device set-power IRP but also must handle this IRP as it travels through the device stack. Consequently, a device power policy owner might have not only a power-completion callback routine associated with the device set-power IRP and an *IoCompletion* routine for the system set-power IRP, but also an *IoCompletion* routine for the device set-power IRP. For further information, see [Handling IRP\_MN\_SET\_POWER for Device Power States](handling-irp-mn-set-power-for-device-power-states.md). + +After the I/O manager calls all the *IoCompletion* routines that were set as the device set-power IRP traveled down the device stack, the I/O manager calls the power-completion callback routine. By this time, all drivers in the stack have completed the device set-power IRP and the device power transition is complete. + +The power-completion callback routine must do the following: + +1. Call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776) to start the next power IRP. (Windows Server 2003, Windows XP, and Windows 2000 only.) + +2. Complete the system set-power IRP ([**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343)) with the status returned for the device set-power IRP. + +3. Call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) to free the previously acquired lock. + +4. Return the status with which the set-power IRPs completed. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20a%20Device%20Set-Power%20IRP%20in%20Response%20to%20a%20System%20Set-Power%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-a-wait-wake-irp.md b/windows-driver-docs-pr/kernel/sending-a-wait-wake-irp.md new file mode 100644 index 0000000000..359f6f4018 --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-a-wait-wake-irp.md @@ -0,0 +1,42 @@ +--- +title: Sending a Wait/Wake IRP +author: windows-driver-content +description: Sending a Wait/Wake IRP +ms.assetid: ed582644-af51-4841-be59-6a3deb6d9de5 +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "wait/wake IRPs WDK power management , sending", "sending wait/wake IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending a Wait/Wake IRP + + +## + + +The minor power IRP code [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) provides for waking a device or waking the system. Drivers of devices that can wake themselves or the system send **IRP\_MN\_WAIT\_WAKE** requests. The system sends **IRP\_MN\_WAIT\_WAKE** requests only to devices that always wake the system, such as the power-on switch. + +A driver sends an **IRP\_MN\_WAIT\_WAKE** request for one of two reasons: + +1. Its device must be able to return to the working state from a sleep state in response to an external wake-up signal. + + For example, a modem's driver might send it a wait/wake IRP before setting it in power state D1 to conserve energy. The wait/wake IRP enables the modem to respond to an incoming call. + +2. Its device must be able to wake the system in response to a wake-up signal. + + When the system goes to sleep, the modem might remain in state D1 with an **IRP\_MN\_WAIT\_WAKE** pending. In this case, an incoming call would wake the system as well as the modem. + +Whether a device is prepared to wake itself or the system, the actions its drivers must take are the same. The primary difference lies in how the device and system hardware respond to the initial wake-up signal. Driver behavior is the same in either case. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20a%20Wait/Wake%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-an-event-with-iowmiwriteevent.md b/windows-driver-docs-pr/kernel/sending-an-event-with-iowmiwriteevent.md new file mode 100644 index 0000000000..6d05f504fe --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-an-event-with-iowmiwriteevent.md @@ -0,0 +1,70 @@ +--- +title: Sending an Event with IoWMIWriteEvent +author: windows-driver-content +description: Sending an Event with IoWMIWriteEvent +ms.assetid: 77c1041a-340c-4c59-a30a-e946adf60a95 +keywords: ["WMI WDK kernel , event tracking", "events WDK WMI", "tracing WDK WMI", "sending WMI events", "event blocks WDK WMI", "notifications WDK WMI", "IoWMIWriteEvent", "dynamic instance names WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending an Event with IoWMIWriteEvent + + +## + + +A driver can call [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) to send any event. The event can consist of a single item, a single instance, or all instances of a data block, and it can use dynamic instance names. + +Unlike **WNODE\_*XXX*** structures passed with query or change requests, which are allocated and partially initialized by WMI, the driver must allocate and initialize all members of the **WNODE\_*XXX*** structure that contains an event. + +A driver must send an event only after WMI has sent an [**IRP\_MN\_ENABLE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550859) request to enable the event. Then, when the event's trigger condition occurs, the driver: + +1. Allocates a buffer from nonpaged pool to contain the **WNODE\_*XXX*** structure needed for the event, including space for variable data, if any. + + Depending on the event, the driver might allocate a [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378), a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377), or a [**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) for the event. The size of the **WNODE\_*XXX*** plus variable data must not exceed the registry-defined limit of 1K. + +2. Initializes all members of the **WNODE\_*XXX*** structure, including **WnodeHeader.Flags**: + + - The driver sets the **WNODE\_FLAG\_EVENT\_ITEM** flag to indicate that the structure is an event. + + - The driver sets one of the following flags to indicate the type of **WNODE\_*XXX*** structure: + + **WNODE\_FLAG\_ALL\_DATA** + + **WNODE\_FLAG\_SINGLE\_INSTANCE** + + **WNODE\_FLAG\_SINGLE\_ITEM** + + - The driver sets or clears the following flags to indicate whether the block uses static or dynamic instance names: + + **WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES** + + **WNODE\_FLAG\_PDO\_INSTANCE\_NAMES** + + - The driver might set additional flags depending on the event. + +3. Casts a pointer to the **WNODE\_*XXX*** to a PWNODE\_EVENT\_ITEM. + +4. Calls **IoWMIWriteEvent** with the pointer. + + If **IoWMIWriteEvent** completes successfully, WMI releases the driver-allocated memory for the event. + +After [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) returns, the driver resumes monitoring the event's trigger condition and sending the event each time its trigger condition occurs, until WMI sends an [**IRP\_MN\_DISABLE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550851) request to disable that event. + +If the size of an event exceeds the registry-defined maximum of 1K (not recommended) the driver should call **IoWmiWriteEvent** with an initialized [**WNODE\_EVENT\_REFERENCE**](https://msdn.microsoft.com/library/windows/hardware/ff566374) that specifies the event's GUID, its size, and its instance index (for static instance names) or name (for dynamic instance names). WMI will use the information in the **WNODE\_EVENT\_REFERENCE** to query for the event. + +A driver can send an events that does not use dynamic instance names and that consists of a single instance by calling the WMI library routine [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807). The driver does not need to allocate and initialize a **WNODE\_*XXX*** structure for a **WmiFireEvent** call. WMI packages the driver's event data in a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) and delivers it to data consumers. For more information about sending events with **WmiFireEvent**, see [Sending an Event with WmiFireEvent](sending-an-event-with-wmifireevent.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20an%20Event%20with%20IoWMIWriteEvent%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-an-event-with-wmifireevent.md b/windows-driver-docs-pr/kernel/sending-an-event-with-wmifireevent.md new file mode 100644 index 0000000000..551f00817f --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-an-event-with-wmifireevent.md @@ -0,0 +1,52 @@ +--- +title: Sending an Event with WmiFireEvent +author: windows-driver-content +description: Sending an Event with WmiFireEvent +ms.assetid: f9cf8491-0f5a-4d83-849f-3edb77488092 +keywords: ["WMI WDK kernel , event tracking", "events WDK WMI", "tracing WDK WMI", "sending WMI events", "event blocks WDK WMI", "notifications WDK WMI", "WmiFireEvent", "dynamic instance names WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending an Event with WmiFireEvent + + +## + + +A driver can call [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807) to send events that do not use dynamic instance names, and that base static instance names on a single base name string or the device instance ID of a PDO. + +The event must be a single instance of a block—that is, a driver cannot call **WmiFireEvent** to send an event that consists of a single item or multiple instances. To send such events, a driver must call [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520), as described in [Sending an Event with IoWMIWriteEvent](sending-an-event-with-iowmiwriteevent.md). + +A driver should not send events until WMI has enabled the event. After the event has been enabled, when the event's trigger condition occurs, the driver: + +1. Allocates a buffer from the nonpaged pool and writes the event data to the buffer. If the event has no data, the driver can skip this step. + +2. Calls [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807) with the following parameters: + + - A pointer to the driver's device object + + - A pointer to the GUID that represents the event block + + - If the event block has multiple instances, the index of the instance + + - If data is to be sent with the event, the number of bytes of data, or 0 if none + + - If data is to be sent with the event, a pointer to the driver-allocated buffer that contains the data, or **NULL** if none + + The driver must allocate all parameters passed to **WmiFireEvent**, including the event data buffer, from nonpaged pool. WMI releases the driver-allocated memory without further intervention by the driver. + +After **WmiFireEvent** returns, the driver resumes monitoring the event's trigger condition and sends the event each time its trigger condition occurs until WMI disables that event. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20an%20Event%20with%20WmiFireEvent%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md b/windows-driver-docs-pr/kernel/sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md new file mode 100644 index 0000000000..6b3f118d5b --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md @@ -0,0 +1,78 @@ +--- +title: Sending IRP_MN_QUERY_POWER or IRP_MN_SET_POWER for Device Power States +author: windows-driver-content +description: Sending IRP_MN_QUERY_POWER or IRP_MN_SET_POWER for Device Power States +ms.assetid: 58f65138-abb9-4bb8-bf9b-14f17347e309 +keywords: ["IRP_MN_SET_POWER", "IRP_MN_QUERY_POWER", "device power states WDK kernel", "query-power IRPs WDK power management", "power IRPs WDK kernel , device queries", "querying power state", "queuing IRPs", "device query power IRPs WDK kernel", "sending power state IRPs", "set-power IRPs WDK kernel", "device set power IRPs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending IRP\_MN\_QUERY\_POWER or IRP\_MN\_SET\_POWER for Device Power States + + +## + + +A device power policy owner sends a device query-power IRP ([**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699)) to determine whether lower drivers can accommodate a change in device power state, and a device set-power IRP ([**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744)) to change the device power state. (This driver can also send a wait/wake IRP to enable its device to awaken in response to an external signal; see [Supporting Devices that Have Wake-Up Capabilities](supporting-devices-that-have-wake-up-capabilities.md) for details.) + +The driver should send an [**IRP\_MN\_QUERY\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551699) request when either of the following is true: + +- The driver receives a system query-power IRP. + +- The driver is preparing to put an idle device in a sleep state, so must query lower drivers to find out whether doing so is feasible. + +The driver should send an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request when any of the following is true: + +- The driver has determined that the device is idle and can be put to sleep. + +- The device is sleeping and must re-enter the working state to handle waiting I/O. + +- The driver receives a system set-power IRP. + +A driver must not allocate its own power IRP; the power manager provides the [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) routine for this purpose. As [Rules for Handling Power IRPs](rules-for-handling-power-irps.md) explains, **PoRequestPowerIrp** allocates and sends the IRP, and in combination with **IoCallDriver** (in Windows 7 and Windows Vista), or **PoCallDriver** (in Windows Server 2003, Windows XP, and Windows 2000), ensures that all power requests are properly synchronized. Callers of **PoRequestPowerIrp** must be running at IRQL <= DISPATCH\_LEVEL. + +The following is the prototype for this routine: + +``` +NTSTATUS +PoRequestPowerIrp ( + IN PDEVICE_OBJECT DeviceObject, + IN UCHAR MinorFunction, + IN POWER_STATE PowerState, + IN PREQUEST_POWER_COMPLETE CompletionFunction, + IN PVOID Context, + OUT PIRP *Irp OPTIONAL + ); +``` + +To send the IRP, the driver calls **PoRequestPowerIrp**, specifying a pointer to the target device object in *DeviceObject*, the minor IRP code IRP\_MN\_SET\_POWER or IRP\_MN\_QUERY\_POWER in *MinorFunction*, the value **DevicePowerState** in the *PowerState***.Type**, and a device power state in *PowerState***.State**. In Windows 98/Me, *DeviceObject* must specify the PDO of the underlying device; in Windows 2000 and later versions of Windows, this value can point to either the PDO or an FDO of a driver in the same device stack. + +If the driver must perform additional tasks after all other drivers have completed the IRP, it should pass a pointer to a power completion function in *CompletionFunction*. The I/O manager calls the *CompletionFunction* after calling all the *IoCompletion* routines set by drivers as they passed the IRP down the stack. + +Whenever a device power policy owner sends a device power query IRP, it should subsequently send a device set-power IRP from the callback routine (*CompletionFunction*) that it specified in the call to **PoRequestPowerIrp**. If the query succeeded, the set-power IRP specifies the queried power state. If the query failed, the set-power IRP re-asserts the current device power state. Re-asserting the current state is important because drivers queue I/O in response to the query; the policy owner must send the set-power IRP to notify drivers in its device stack to begin processing queued I/O requests. + +Keep in mind that the policy owner for a device not only sends the device power IRP but also handles the IRP as it is passed down the device stack. Therefore, such a driver often sets an *IoCompletion* routine (with [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679)) as part of its IRP-handling code, particularly when the device is powering up. The *IoCompletion* routine is called in sequence with *IoCompletion* routines set by other drivers and before the *CompletionFunction*. For further information, see [IoCompletion Routines for Device Power IRPs](iocompletion-routines-for-device-power-irps.md). + +Because the IRP has been completed by all drivers when the *CompletionFunction* is called, the *CompletionFunction* must not call **IoCallDriver**, **PoCallDriver**, or **PoStartNextPowerIrp** with the IRP it originated. (It might, however, call these routines for a different power IRP.) Instead, this routine performs any additional actions required by the driver that originated the IRP. If the driver sent the device IRP in response to a system IRP, the *CompletionFunction* might complete the system IRP. For further information, see [Handling a System Set-Power IRP in a Device Power Policy Owner](handling-a-system-set-power-irp-in-a-device-power-policy-owner.md). + +In response to the call to **PoRequestPowerIrp**, the power manager allocates a power IRP and sends it to the top of the device stack for the device. The power manager returns a pointer to the allocated IRP. + +If no errors occur, **PoRequestPowerIrp** returns STATUS\_PENDING. This status means that the IRP has been sent successfully and is pending completion. The call fails if the power manager cannot allocate the IRP or if the caller has specified an invalid minor power IRP code. + +Requests to power up a device must be handled first by the underlying bus driver for the device and then by each successively higher driver in the stack. Therefore, when sending a **PowerDeviceD0** request, the driver must ensure that its *CompletionFunction* performs required tasks after the IRP is complete and the device is powered on. + +When powering off a device (**PowerDeviceD3**), each driver in the device stack must save all of its necessary context and do any necessary clean-up before sending the IRP to the next-lower driver. The extent of the context information and clean-up depends on the type of driver. A function driver must save hardware context; a filter driver might need to save its own software context. A *CompletionFunction* set in this situation can take actions associated with a completed power IRP, but the driver cannot access the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20IRP_MN_QUERY_POWER%20or%20IRP_MN_SET_POWER%20for%20Device%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sending-wmi-events.md b/windows-driver-docs-pr/kernel/sending-wmi-events.md new file mode 100644 index 0000000000..833deef49a --- /dev/null +++ b/windows-driver-docs-pr/kernel/sending-wmi-events.md @@ -0,0 +1,42 @@ +--- +title: Sending WMI Events +author: windows-driver-content +description: Sending WMI Events +ms.assetid: 0d5e62f1-b84e-42b7-be40-8665f0b58ba8 +keywords: ["WMI WDK kernel , event tracking", "events WDK WMI", "tracing WDK WMI", "sending WMI events", "event blocks WDK WMI", "notifications WDK WMI", "dynamic instance names WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Sending WMI Events + + +## + + +A driver can use WMI events to notify user-mode applications of events without requiring the applications to poll or send IRPs. A driver should use WMI events to notify WMI clients of exceptional conditions, not as an alternative to error logging. A driver should support any standard event blocks defined for its device type in Wmicore.mof, and might define and register additional custom event blocks to support device-specific notifications. + +An event block is simply a data block that derives from the abstract base class **WMIEvent**. An event block can contain any of the same data as a data block, or it can be empty—that is, an event block need not contain any driver-defined data items. If an event block does contain data, the total size of the **WNODE\_*XXX*** plus the data should not exceed the registry-defined limit of 1 kilobyte. In general, smaller events result in better system performance and more timely notification. For information about defining blocks, see [MOF Syntax for WMI Data and Event Blocks](mof-syntax-for-wmi-data-and-event-blocks.md) and [Designing WMI Data and Event Blocks](designing-wmi-data-and-event-blocks.md). + +A driver indicates support for an event by registering the corresponding event block with WMIREG\_FLAG\_EVENT\_ONLY\_GUID set in the block's [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structure. For information about registering blocks, see [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +When a WMI client user requests notification of an event, WMI sends an [**IRP\_MN\_ENABLE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550859) request to the driver, which alerts the driver to begin monitoring the event's driver-determined trigger condition. Then, when the trigger condition occurs, the driver sends the event to WMI, which delivers it to all data consumers that have registered for the event. + +A driver sends an event to WMI in one of the following ways: + +- Call the kernel-mode WMI library routine [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807). A driver can call **WmiFireEvent** to send only events that do not use dynamic instance names, and that base static instance names on a single base name string or the device instance ID of a PDO. Furthermore, the event must be a single instance—that is, a driver cannot call **WmiFireEvent** to send an event that consists of a single item or multiple instances. For more information, see [Sending an Event with WmiFireEvent](sending-an-event-with-wmifireevent.md). + +- Call the kernel-mode routine [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) with a pointer to a driver-allocated and initialized **WNODE\_*XXX*** structure that contains the event's data. For more information, see [Sending an Event with IoWMIWriteEvent](sending-an-event-with-iowmiwriteevent.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sending%20WMI%20Events%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/separate-dispatchcreate-and-dispatchclose-routines.md b/windows-driver-docs-pr/kernel/separate-dispatchcreate-and-dispatchclose-routines.md new file mode 100644 index 0000000000..89dbc0e89a --- /dev/null +++ b/windows-driver-docs-pr/kernel/separate-dispatchcreate-and-dispatchclose-routines.md @@ -0,0 +1,44 @@ +--- +title: Separate DispatchCreate and DispatchClose Routines +author: windows-driver-content +description: Separate DispatchCreate and DispatchClose Routines +ms.assetid: b2e05555-c70d-4293-8622-51eea92091b1 +keywords: ["dispatch routines WDK kernel , DispatchCreate routine", "dispatch routines WDK kernel , DispatchClose routine", "DispatchClose routine", "DispatchCreate routine", "IRP_MJ_CREATE I/O function code", "IRP_MJ_CLOSE I/O function code", "create dispatch routines WDK kernel", "close dispatch routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Separate DispatchCreate and DispatchClose Routines + + +## + + +A driver's *Dispatch* routines for [**IRP\_MJ\_CREATE**](https://msdn.microsoft.com/library/windows/hardware/ff550729) and [**IRP\_MJ\_CLOSE**](https://msdn.microsoft.com/library/windows/hardware/ff550720) requests might do nothing more than complete the input IRP with STATUS\_SUCCESS. For more information, see [Completing IRPs](completing-irps.md). + +Another driver's *Dispatch* routines for **IRP\_MJ\_CREATE** and **IRP\_MJ\_CLOSE** requests might do more work, depending on the underlying device driver or on the underlying device. Consider the following scenarios: + +- On receipt of a create request, a class driver might initialize an internal queue and send an [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) request down to the corresponding port driver requesting device configuration information or exclusive access to a controller port. + +- Receipt of **IRP\_MJ\_CLOSE** indicates that the last reference to the file object that is associated with the target device object has been removed. This implies that all handles to the file object has been closed and all outstanding I/O requests have been completed or canceled. + +- On receipt of a create request, a driver of an infrequently used device might call [**MmLockPagableCodeSection**](https://msdn.microsoft.com/library/windows/hardware/ff554601) to make resident some of the driver routines that process other **IRP\_MJ\_*XXX*** requests. On receipt of a reciprocal close request, the driver might call [**MmUnlockPagableImageSection**](https://msdn.microsoft.com/library/windows/hardware/ff556377) to conserve system memory by having its pageable-image section paged out when all file object handles for such a driver's device object(s) are closed. + +Some drivers handle **IRP\_MJ\_CLOSE** requests only for symmetry because, after their device objects have been opened by a protected subsystem or higher-level driver, the lower-level drivers' device objects are not closed until the system itself is shut down. For example, keyboard and mouse drivers set up device objects representing physical devices that must be functional while the system is running, so these drivers might have minimal [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routines for symmetry, or they might have combined [*DispatchCreateClose*](https://msdn.microsoft.com/library/windows/hardware/ff543270) routines. + +If the device controlled by a lower-level driver must be available for the system to continue running, the driver's *DispatchClose* routine generally will not be called. For example, some of the system disk drivers have no *DispatchClose* routine, but these drivers usually have [*DispatchFlushBuffers*](https://msdn.microsoft.com/library/windows/hardware/ff543314) and [*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) routines to complete any outstanding file I/O operations before the system is shut down. + +While you can implement separate [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) and *DispatchClose* routines, drivers sometimes have [a single DispatchCreateClose routine](a-single-dispatchcreateclose-routine.md) for handling both create and close requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Separate%20DispatchCreate%20and%20DispatchClose%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/servicing-interrupts.md b/windows-driver-docs-pr/kernel/servicing-interrupts.md new file mode 100644 index 0000000000..8dc500108d --- /dev/null +++ b/windows-driver-docs-pr/kernel/servicing-interrupts.md @@ -0,0 +1,38 @@ +--- +title: Servicing Interrupts +author: windows-driver-content +description: Servicing Interrupts +ms.assetid: c4567d35-c4ec-4bde-8d10-e613de787bf7 +keywords: ["kernel-mode drivers WDK , servicing interrupts", "servicing interrupts WDK kernel", "device interrupts WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Servicing Interrupts + + +## + + +This section contains the following sections: + +[Interrupt Service Routines](interrupt-service-routines.md) + +[DPC Objects and DPCs](dpc-objects-and-dpcs.md) + +[Using Critical Sections](using-critical-sections.md) + +[Managing Hardware Priorities](managing-hardware-priorities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Servicing%20Interrupts%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-device-object-flags-for-power-management.md b/windows-driver-docs-pr/kernel/setting-device-object-flags-for-power-management.md new file mode 100644 index 0000000000..dade8ed044 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-device-object-flags-for-power-management.md @@ -0,0 +1,47 @@ +--- +title: Setting Device Object Flags for Power Management +author: windows-driver-content +description: Setting Device Object Flags for Power Management +ms.assetid: 58d1a3a2-c8ea-446c-b1d6-ed00411d1d75 +keywords: ["DO_POWER_PAGABLE", "DO_POWER_INRUSH", "device object flags WDK power management", "object flags WDK power management", "flags WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Device Object Flags for Power Management + + +## + + +In its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, each driver creates a device object (filter device object (DO), functional device object (FDO), or physical device object (PDO)) and sets the DO\_*XXX* flags in the device object to describe the device attributes and driver configuration. The following device object flags pertain to power management. + +| Flag | Description | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| DO\_POWER\_INRUSH | Indicates that the current drawn by the device surges when the device is first turned on. This surge or "inrush" lasts for a short period, after which the current drawn by the device falls to a lower operating level. | +| DO\_POWER\_PAGABLE | Indicates that the driver is pageable. Starting with Windows 2000, drivers that can be paged must set the DO\_POWER\_PAGABLE flag. The power manager calls such drivers at IRQL = PASSIVE\_LEVEL. For more information about pageable drivers, see [Making Drivers Pageable](making-drivers-pageable.md). | + +  + +The device object flags are typically set by the bus driver when it creates the PDO for the device. However, some function drivers might need to alter the values of these flags as part of their *AddDevice* routines. Starting with Windows Vista, the operating system does not require that all device objects within a device stack have the same power-related flags set. However, in Windows Server 2003, Windows XP, and Windows 2000, all the device objects in a device stack should have the same power-related flags set. + +Starting with Windows 2000, drivers of devices that are in the paging path must not set the DO\_POWER\_PAGABLE flag. A driver is in the "paging path" if it participates in I/O operations on the paging file. Drivers that do not set this flag must be callable at IRQL = DISPATCH\_LEVEL. For more information, see [Constraints on Dispatch Routines](https://msdn.microsoft.com/library/windows/hardware/ff539309). + +In general, drivers should not alter the bus driver's value for the DO\_POWER\_PAGABLE flag, and a driver must never set this flag if a lower-level driver has cleared it. When handling transitions involving [PnP paging requests](https://msdn.microsoft.com/library/windows/hardware/ff554992) (typically in response to an [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) with [**IRP\_MN\_DEVICE\_USAGE\_NOTIFICATION**](https://msdn.microsoft.com/library/windows/hardware/ff550841) request), a storage driver must carefully sequence its setting and clearing of the flag. + +Drivers for devices that require an inrush of power at start-up must set the DO\_POWER\_INRUSH flag in the device object before clearing the DO\_DEVICE\_INITIALIZING flag. Only one driver in the device stack, typically the bus driver (PDO), needs to set the DO\_POWER\_INRUSH flag for the device. The flag notifies the power manager that such devices must be powered up one at a time, in sequence with other such devices, to avoid overloading the power supply. The power manager ensures that only one power inrush IRP is active anywhere in the system at any given time. + +Starting with Windows Vista, drivers can set both the DO\_POWER\_PAGABLE flag and the DO\_POWER\_INRUSH flag. In Windows Server 2003, Windows XP, and Windows 2000, drivers cannot set both the DO\_POWER\_PAGABLE flag and the DO\_POWER\_INRUSH flag. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Device%20Object%20Flags%20for%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-device-object-properties-in-the-registry.md b/windows-driver-docs-pr/kernel/setting-device-object-properties-in-the-registry.md new file mode 100644 index 0000000000..528deee4b9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-device-object-properties-in-the-registry.md @@ -0,0 +1,44 @@ +--- +title: Setting Device Object Properties in the Registry +author: windows-driver-content +description: Setting Device Object Properties in the Registry +ms.assetid: a2cfe098-0d5d-42fb-bbdc-25376ce50a9b +keywords: ["device objects WDK kernel , registry", "registry WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Device Object Properties in the Registry + + +## + + +Properties of device objects can be set in the registry as follows: + +- For WDM drivers, properties can be set for each model of a device, or for a whole device setup class. (For more information about device setup classes, see [Device Setup Classes](https://msdn.microsoft.com/library/windows/hardware/ff541509).) + +- For non-WDM drivers, properties can be set for a named device object's device setup class. The driver specifies the device setup class when it creates the device object with **IoCreateDeviceSecure**. For more information about how to specify a device setup class, see [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407). + +Any settings in the registry override the properties supplied when the driver created the device object. + +Registry settings are specified by an INF file that is used during device installation, or they can be specified after installation by an application that calls the [device installation functions](https://msdn.microsoft.com/library/windows/hardware/ff541299). + +This section contains the following subsections: + +[Setting Device Object Registry Properties During Installation](setting-device-object-registry-properties-during-installation.md) + +[Setting Device Object Registry Properties After Installation](setting-device-object-registry-properties-after-installation.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Device%20Object%20Properties%20in%20the%20Registry%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-after-installation.md b/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-after-installation.md new file mode 100644 index 0000000000..99e9434860 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-after-installation.md @@ -0,0 +1,77 @@ +--- +title: Setting Device Object Registry Properties After Installation +author: windows-driver-content +description: Setting Device Object Registry Properties After Installation +ms.assetid: e9415497-f61e-49ba-9376-9255e51e72a8 +keywords: ["device objects WDK kernel , registry", "registry WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Device Object Registry Properties After Installation + + +## + + +A user-mode program can use the [device installation functions](https://msdn.microsoft.com/library/windows/hardware/ff541299) to get or set the registry settings for the properties of a driver's device object. Normally these functions are used by installation software, but they can be used by any user-mode program. (The program must be executed by a user that has Administrator access.) + +The [**SetupDiGetDeviceRegistryProperty**](https://msdn.microsoft.com/library/windows/hardware/ff551967) and [**SetupDiSetDeviceRegistryProperty**](https://msdn.microsoft.com/library/windows/hardware/ff552169) functions get and set the registry key for each specified property. The *Property* parameter specifies the property to get or set. The *PropertyBuffer* points to the destination buffer (when getting the property) or source buffer (when setting the property) for the property. + +The correspondence between values for the *Property* parameter and actual properties is as follows. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value for Property parameterDevice object property

SPDRP_CHARACTERISTICS

Device characteristics

SPDRP_DEVTYPE

Device type

SPDRP_EXCLUSIVE

Exclusive

SPDRP_SECURITY

Security descriptor as a [SECURITY_DESCRIPTOR](https://msdn.microsoft.com/library/windows/hardware/ff563689) structure

SPDRP_SECURITY_SDS

Security descriptor as an SDDL string

+ +  + +Note that two different ways are provided to get or set the security descriptor. You can specify the SPDRP\_SECURITY value to treat the security descriptor as a **SECURITY\_DESCRIPTOR** structure, or SPDRP\_SECURITY\_SDS to treat the security descriptor as an SDDL string. For more information about SDDL strings, see [SDDL for Device Objects](sddl-for-device-objects.md). + +For Windows XP and later operating systems, programs can also get and set the property values for a device setup class. Use the [**SetupDiGetClassRegistryProperty**](https://msdn.microsoft.com/library/windows/hardware/ff551097) and [**SetupDiSetClassRegistryProperty**](https://msdn.microsoft.com/library/windows/hardware/ff552135) functions to get and set the property values for a device setup class. + +For more information about using the **SetupDi*Xxx*** functions, see [Using Device Installation Functions](https://msdn.microsoft.com/library/windows/hardware/ff553567). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Device%20Object%20Registry%20Properties%20After%20Installation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-during-installation.md b/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-during-installation.md new file mode 100644 index 0000000000..c4a4b520c8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-device-object-registry-properties-during-installation.md @@ -0,0 +1,75 @@ +--- +title: Setting Device Object Registry Properties During Installation +author: windows-driver-content +description: Setting Device Object Registry Properties During Installation +ms.assetid: 29d40398-09b9-4e64-aa47-da229066bffd +keywords: ["device objects WDK kernel , registry", "registry WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Device Object Registry Properties During Installation + + +## + + +To set device object properties during installation, you must provide an INF file that specifies the properties. You can specify device object properties for either a device, or a device setup class. + +These are specified as follows. + +- For an individual device, properties are set in the *add-registry-section* for the device. The INF **AddReg** directive within the device's *DDInstall*.HW section specifies the *add-registry-section* for the device. + +- For a device setup class, properties are set in the *add-registry-section* for the device setup class. The INF **AddReg** directive within the **ClassInstall32** section for the class specifies the *add-registry-section* for the class. + +Within an *add-registry-section*, the following keywords can be used to specify the individual device object property to set. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDevice object property

DeviceType

Device type

DeviceCharacteristics

Device characteristics

Exclusive

Exclusive

Security

Security descriptor

+ +  + +For more information about using these keywords, see [**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320). + +The settings can be set by a user-mode component by using the device installation functions. For more information, see [Setting Device Object Registry Properties After Installation](setting-device-object-registry-properties-after-installation.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Device%20Object%20Registry%20Properties%20During%20Installation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-the-mofimagepath-registry-value.md b/windows-driver-docs-pr/kernel/setting-the-mofimagepath-registry-value.md new file mode 100644 index 0000000000..378f67d2d6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-the-mofimagepath-registry-value.md @@ -0,0 +1,58 @@ +--- +title: Setting the MofImagePath Registry Value +author: windows-driver-content +description: Setting the MofImagePath Registry Value +ms.assetid: b8c43cd3-d4f4-4f1e-b692-8005d845d64a +keywords: ["WMI WDK kernel , publishing schema", "publishing WMI schema WDK", "schema publishing WDK WMI", "MOF files WDK WMI", "MofImagePath"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting the MofImagePath Registry Value + + +## + + +A driver's schema can be published by including a compiled MOF resource in a separate file, such as a DLL, and setting **MofImagePath** in the registry to the path of that file. A schema published in this way can be updated without recompiling the driver. + +To publish a driver's schema in a separate file: + +1. Compile the MOF file as described in [Compiling a Driver's MOF File](compiling-a-driver-s-mof-file.md). + +2. Include the compiled MOF file as a resource in a file such as a DLL. + +3. Add the **MofImagePath** registry value under the driver's Services key. For example, the following shows the registry value for a driver named *DriverName*: + + ``` + HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services + \DriverName + MofImagePath "\SystemRoot\System32\Drivers\DriverNameMof.dll" + ``` + +You can set this key in the driver's INF file, as follows: + +``` +; This is the Services section for the driver +[Driver_service_install_section] +AddReg=Driver_AddReg + +; This is the Services AddReg section declared above. +[Driver_AddReg] +HKR,,MofImagePath,,DriverMof.dll +``` + +See [**INF DDInstall.Services Section**](https://msdn.microsoft.com/library/windows/hardware/ff547349) and [**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20the%20MofImagePath%20Registry%20Value%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-a-transfer-operation.md b/windows-driver-docs-pr/kernel/setting-up-a-transfer-operation.md new file mode 100644 index 0000000000..3dccedec9f --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-a-transfer-operation.md @@ -0,0 +1,92 @@ +--- +title: Setting Up a Transfer Operation +author: windows-driver-content +description: Setting Up a Transfer Operation +ms.assetid: cabac16d-b946-4b96-af2c-5fd0a0d848da +keywords: ["bus-master DMA WDK kernel", "DMA transfers WDK kernel , bus-master DMA", "adapter objects WDK kernel , bus-master DMA", "logical address ranges WDK DMA", "addresses WDK DMA", "transfer operations WDK DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up a Transfer Operation + + +## + + +When [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) transfers control to a driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, it has allocated a set of map registers. However, the driver must map system physical memory for the current IRP's transfer request to the bus-master adapter's logical address range, as follows: + +1. Call [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) with the MDL at **Irp->MdlAddress** to get an index for the system physical address where the transfer should start. + + The return value is a required parameter (*CurrentVa*) to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402). + +2. Call **MapTransfer** to map the system physical address ranges for the IRP's buffer to the bus-master adapter's logical address range. + +The driver can then set up the adapter for the transfer operation. The following figure shows the steps involved in setting up the transfer. + +![diagram illustrating setting up a transfer operation](images/3dmabus.png) + +As the previous figure shows, a driver's *AdapterControl* routine sets up a bus-master DMA operation as follows: + +1. The *AdapterControl* routine gets the address at which to start the transfer. For the initial transfer required to satisfy an IRP, the *AdapterControl* routine calls [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539), passing a pointer to the MDL at **Irp->MdlAddress**, which describes the buffer for this DMA transfer. + + **MmGetMdlVirtualAddress** returns a virtual address that the driver can use as an index for the system physical address where the transfer should start. + + If the IRP requires more than one transfer operation, the driver calculates an updated starting address, as described later in this section. + +2. The *AdapterControl* routine saves the address returned by **MmGetMdlVirtualAddress** or calculated in Step 1. This address is a required parameter (*CurrentVa*) to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402). + +3. The *AdapterControl* routine calls **MapTransfer**, which returns a logical address at which the driver can program the bus-master adapter to begin the transfer operation. In the call to **MapTransfer**, the driver supplies the following parameters: + - The adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) + + - A pointer to the MDL at **Irp->MdlAddress** for the current IRP + + - The *MapRegisterBase* handle passed to the driver's *AdapterControl* routine by **AllocateAdapterChannel** (see [Allocating the Bus-Master Adapter Object](allocating-the-bus-master-adapter-object.md)) + + - The value returned by **MmGetMdlVirtualAddress** if this is the first call to **MapTransfer** for the current IRP + + Otherwise, the driver supplies an updated *CurrentVa* value, indicating the next physical-to-logical mapping to be done. (How to calculate an updated *CurrentVa* is described later in this section.) + + - A pointer to a variable (*Length*), which indicates the number of bytes for this transfer + + If the driver has enough map registers to transfer all the requested data in a single DMA operation and has no device-specific constraints on its DMA operations, the *Length* can be set to the value of **Length** in the driver's I/O stack location of the IRP. At most, the input length in bytes can be (PAGE\_SIZE \* the *NumberOfMapRegisters* returned by **IoGetDmaAdapter**). Otherwise, the driver must split up the request, as explained in [Splitting Transfer Requests](splitting-dma-transfer-requests.md), and must update the value of *Length* in subsequent calls to **MapTransfer** for the current IRP. + + - A Boolean value (*WriteToDevice*), indicating the direction of the transfer operation (TRUE to transfer data from memory to the device) + +4. The *AdapterControl* routine sets up the device for the DMA operation. + +5. The *AdapterControl* routine returns **DeallocateObjectKeepRegisters**. + +If the driver must call **MapTransfer** more than once to satisfy the current IRP, it supplies the same adapter object pointer, *Mdl* pointer, *MapRegisterBase* handle, and transfer direction in every call to **MapTransfer**. However, the driver must supply updated *CurrentVa* and *Length* values in its second and subsequent calls to **MapTransfer**. Use the following formulas to calculate these values: + +- *CurrentVa* = *CurrentVa* + (*Length* requested in preceding call to **MapTransfer**) + +- *Length* = Minimum (remaining **Length** to be transferred, (PAGE\_SIZE \* *NumberOfMapRegisters* returned by **IoGetDmaAdapter**)) + +The context information each driver should maintain about its DMA transfers depends on the needs of its particular device. Typical context might include the current virtual address in the MDL (*CurrentVa*), the number of bytes transferred so far, the number of bytes remaining to transfer, and possibly a pointer to the current IRP. + +For drivers of devices with scatter/gather capabilities, the *Length* parameter to **MapTransfer** is both an input and output parameter. On return from **MapTransfer**, it indicates how many bytes of data the system has mapped. That is, the return value of *Length*, in combination with the returned logical address, indicates the range of logical addresses the bus-master adapter can use for this piece of the transfer in this DMA operation. + +**Note**   Since *Length* is overwritten by **MapTransfer**, follow this implementation guideline: +Never pass a pointer to the **Length** in the driver's I/O stack location of an IRP as the *Length* parameter to **MapTransfer** if your device supports scatter/gather. + +Doing this could destroy the value in the current IRP, making it impossible to determine whether the driver has transferred all the requested data. + +  + +At the end of each DMA operation, the driver must call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) with a valid adapter object pointer and the *MapRegisterBase* handle to be sure that all the data has been transferred, and to release the physical-to-logical mappings for the current DMA operation. If the driver must set up additional DMA operations to satisfy the current IRP, it must call **FlushAdapterBuffers** after each transfer operation is complete. + +When all the requested transfer is complete or the driver must return an error status for the IRP, the driver should call [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) immediately after its last call to **FlushAdapterBuffers** in order to get the best possible throughput for the bus-master adapter. In its call to **FreeMapRegisters**, the driver must pass the adapter object pointer that it passed in the preceding call to **AllocateAdapterChannel**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20a%20Transfer%20Operation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-adaptercontrol-routines.md b/windows-driver-docs-pr/kernel/setting-up-adaptercontrol-routines.md new file mode 100644 index 0000000000..37a3dc9e8c --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-adaptercontrol-routines.md @@ -0,0 +1,38 @@ +--- +title: Setting Up AdapterControl Routines +author: windows-driver-content +description: Setting Up AdapterControl Routines +ms.assetid: 0d2add25-711a-4e5d-8409-b7ce60b08858 +keywords: ["AdapterControl routines, setting up", "AdapterControl routines, writing", "adapter objects WDK kernel , writing AdapterControl routines", "DMA transfers WDK kernel , writing AdapterControl routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up AdapterControl Routines + + +## + + +A driver's dispatch routine for a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request must do the following for an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine: + +1. Set up the adapter object for the device's DMA capabilities by filling in a [**DEVICE\_DESCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/ff543107) structure and calling [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220). + +2. Save the adapter object pointer and *NumberOfMapRegisters* returned by **IoGetDmaAdapter**. + + The platform-specific maximum *NumberOfMapRegisters* returned by **IoGetDmaAdapter** or the transfer capabilities of the driver's device, whichever is more restrictive, determines whether the driver must split up a given transfer request and carry out more than one DMA operation on its device to satisfy that IRP. + +The returned adapter object pointer, the entry point of the driver's *AdapterControl* routine, the *DeviceObject* pointer representing the target device for the current IRP, a *Context* pointer to an area already set up for the *AdapterControl* routine, and a *NumberOfMapRegisters* value, which can be less than the maximum possible number for smaller transfer requests, must be passed in calls to [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573). Usually, a driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) (or possibly [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049)) routine sets up the area at *Context* before it calls **AllocateAdapterChannel**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20AdapterControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-and-using-device-queues.md b/windows-driver-docs-pr/kernel/setting-up-and-using-device-queues.md new file mode 100644 index 0000000000..0e9899af70 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-and-using-device-queues.md @@ -0,0 +1,61 @@ +--- +title: Setting Up and Using Device Queues +author: windows-driver-content +description: Setting Up and Using Device Queues +ms.assetid: 5221ffc0-0cb4-498b-9be2-4d240b5f2744 +keywords: ["device queues WDK IRPs , setting up", "device queues WDK IRPs , objects", "inserting IRPs in queue", "storing device queue objects", "supplemental IRP queues WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up and Using Device Queues + + +## + + +A driver sets up a device queue object by calling [**KeInitializeDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff552126) at driver or device initialization. After starting its device(s), the driver inserts IRPs into this queue by calling [**KeInsertDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff552180) or [**KeInsertByKeyDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff552178). The following figure illustrates these calls. + +![diagram illustrating using a device queue object](images/3devqobj.png) + +As this figure shows, the driver must provide the storage for a device queue object, which must be resident. Drivers that set up a device queue object usually provide the necessary storage in the [device extension](device-extensions.md) of a driver-created device object, but the storage can be in a controller extension if the driver uses a [controller object](using-controller-objects.md) or in nonpaged pool allocated by the driver. + +If the driver provides storage for the device queue object in a device extension, it calls **KeInitializeDeviceQueue** after creating the device object and before starting the device. In other words, the driver can initialize the queue from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine or when it handles a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. In the call to **KeInitializeDeviceQueue**, the driver passes a pointer to the storage it provides for the device queue object. + +After starting its device(s), the driver can insert an IRP into its device queue by calling **KeInsertDeviceQueue**, which places the IRP at the tail of the queue, or **KeInsertByKeyDeviceQueue**, which places the IRP into the queue according to a driver-determined *SortKey* value, as shown in the previous figure. + +Each of these support routines returns a Boolean value indicating whether the IRP was inserted into the queue. Each of these calls also sets the state of the device queue object to Busy if the queue is currently empty (Not-Busy). However, if the queue is empty (Not-Busy), neither **KeInsert*Xxx*DeviceQueue** routine inserts the IRP into the queue. Instead, it sets the state of the device queue object to Busy and returns **FALSE**. Because the IRP has not been queued, the driver must pass it on to another driver routine for further processing. + +**When setting up supplemental device queues, follow this implementation guideline:** + +When a call to **KeInsert*Xxx*DeviceQueue** returns **FALSE**, the caller must pass the IRP it attempted to queue on for further processing to another driver routine. +However, the call to **KeInsert*Xxx*DeviceQueue** changes the state of the device queue object to Busy, so the next IRP to come in is inserted in the queue unless the driver calls **KeRemove*Xxx*DeviceQueue** first. + +When the device queue object's state is set to Busy, the driver can dequeue an IRP for further processing or reset the state to Not-Busy by calling one of the following support routines: + +- [**KeRemoveDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553156) to remove the IRP at the head of the queue + +- [**KeRemoveByKeyDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553152) to remove an IRP chosen according to a driver-determined *SortKey* value + +- [**KeRemoveEntryDeviceQueue**](https://msdn.microsoft.com/library/windows/hardware/ff553163) to remove a particular IRP in the queue or to determine whether a particular IRP is in the queue + + **KeRemoveEntryDeviceQueue** returns a Boolean indicating whether the IRP was in the device queue. + +Calling any of these routines to remove an entry from a device queue that is empty but Busy changes the queue state to Not-Busy. + +Each device queue object is protected by a built-in executive spin lock (not shown in the [Using a Device Queue Object](#ddk-setting-up-and-using-device-queues-kg) figure). As a result, a driver can insert IRPs into the queue and remove them in a multiprocessor-safe manner from any driver routine running at less than or equal to IRQL = DISPATCH\_LEVEL. Because of this IRQL restriction, a driver cannot call any **Ke*Xxx*DeviceQueue** routine from its ISR or [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines, which run at DIRQL. + +See [Managing Hardware Priorities](managing-hardware-priorities.md) and [Spin Locks](spin-locks.md) for more information. For IRQL requirements for a specific support routine, see the routine's reference page. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20and%20Using%20Device%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-and-using-interlocked-queues.md b/windows-driver-docs-pr/kernel/setting-up-and-using-interlocked-queues.md new file mode 100644 index 0000000000..0689b43993 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-and-using-interlocked-queues.md @@ -0,0 +1,64 @@ +--- +title: Setting Up and Using Interlocked Queues +author: windows-driver-content +description: Setting Up and Using Interlocked Queues +ms.assetid: af44a4c0-5aa7-40aa-b511-df95c9bfe9bb +keywords: ["interlocked IRP queues WDK kernel", "doubly linked IRPs WDK kernel", "driver-dedicated threads WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up and Using Interlocked Queues + + +## + + +New drivers should use the [cancel-safe IRP queue](cancel-safe-irp-queues.md) framework in preference to the methods outlined in this section. + +Drivers with device-dedicated threads or drivers that use executive worker threads, such as most system FSDs, are the most likely types of drivers to manage their own run-time internal queuing of IRPs in an interlocked queue. All PnP drivers, including WDM drivers, also must queue certain IRPs internally while making PnP and power state transitions. + +Usually, these drivers set up a doubly linked interlocked queue; every IRP contains a member of type [**LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff554296), which a driver can use to doubly link IRPs that it is currently holding. A driver cannot requeue IRPs for retries if it sets up a singly linked interlocked queue. + +### + +A driver must set up its interlocked queue at device initialization. The following figure illustrates a doubly linked interlocked queue, the support routines a driver must call to set up such a queue, and a set of **ExInterlocked*Xxx*** routines a driver can call to insert IRPs into and remove IRPs from the queue. + +![diagram illustrating using an interlocked queue](images/3intlokq.png) + +As this figure shows, a driver must provide the storage for the queue itself and for the following in order to set up a doubly linked interlocked queue: + +- An executive spin lock, which the driver must call [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160) to initialize. Usually, a driver initializes the spin lock when it sets up the device extension(s) for its device object(s) in its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +- The list head for the queue, which the driver must initialize by calling [**InitializeListHead**](https://msdn.microsoft.com/library/windows/hardware/ff547799). + +Most drivers that use doubly linked interlocked queues provide the necessary storage in the device extension of a driver-created device object. The queue and executive spin lock can instead be in a controller extension (if the driver uses a [controller object](using-controller-objects.md)) or in nonpaged pool allocated by the driver. + +While the driver is accepting I/O requests, it can insert an IRP into its queue by calling either of the following support routines if the *ListHead* is of type **LIST\_ENTRY**, as shown in the previous figure: + +[**ExInterlockedInsertTailList**](https://msdn.microsoft.com/library/windows/hardware/ff545402) to place the IRP at the end of the queue + +[**ExInterlockedInsertHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff545397) to place the IRP at the front of the queue. Drivers usually call this routine only when they must retry a particular request. + +The driver must pass pointers to the IRP (*ListEntry*), as well the *ListHead* and executive spin lock (*Lock*) pointers that it previously initialized, to each of these **ExInterlockedInsert*Xxx*List** routines. Only pointers to the *ListHead* and *Lock* are required when the driver dequeues an IRP by calling [**ExInterlockedRemoveHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff545427). To prevent deadlocks, the driver must not be holding an ExecutiveSpinLock that it passes to any **ExInterlocked*Xxx*** routine. + +Because an interlocked queue is protected by the executive spin lock, the driver can insert IRPs into its doubly linked queue and remove them in a multiprocessor-safe manner from any driver routine running at less than or equal to IRQL = DISPATCH\_LEVEL. + +A queue with a ListHead of type **LIST\_ENTRY**, as shown in the previous figure, is a doubly linked list. One with a ListHead of type [**SLIST\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff563810) is a sequenced, singly linked list. A driver initializes the ListHead for a sequenced singly linked interlocked queue by calling [**ExInitializeSListHead**](https://msdn.microsoft.com/library/windows/hardware/ff545321). + +A driver that never retries I/O operations can use [**ExInterlockedPushEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545422) and [**ExInterlockedPopEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545414) to manage its queuing of IRPs internally in a sequenced, singly linked interlocked queue. Any driver that uses this type of interlocked queue also must provide resident storage for a ListHead of type **SLIST\_HEADER** and for an ExecutiveSpinLock, as shown in the [previous figure](#ddk-using-an-interlocked-queue-kg). It must initialize the spin lock and set up its queue before calling **ExInterlockedPushEntrySList** to insert the initial entry into its queue. + +For more information, see [Managing Hardware Priorities](managing-hardware-priorities.md) and [Spin Locks](spin-locks.md). For IRQL requirements for a specific support routine, see the routine's reference page. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20and%20Using%20Interlocked%20Queues%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-controllercontrolroutines.md b/windows-driver-docs-pr/kernel/setting-up-controllercontrolroutines.md new file mode 100644 index 0000000000..1bbe6f11a9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-controllercontrolroutines.md @@ -0,0 +1,38 @@ +--- +title: Setting Up ControllerControl Routines +author: windows-driver-content +description: Setting Up ControllerControl Routines +ms.assetid: 007247c1-b51e-4677-9a46-78ff9f1c8996 +keywords: ["controller objects WDK kernel , writing ControllerControl routines", "ControllerControl routines, writing", "ControllerControl routines, setting up"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up ControllerControl Routines + + +## + + +A driver's [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine must do the following when it receives an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request, to set up a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine: + +1. Call [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395) to set up the controller object, specifying the driver-determined *Size* for the controller extension, which the system allocates from nonpaged pool and initializes with zeros. + +2. Save the *ControllerObject* pointer returned by **IoCreateController**, usually in the device extension of each device object representing a physical or logical device that is controlled by the hardware represented by the controller object. + +3. Set up and/or initialize the driver-determined contents of the *ControllerObject***->ControllerExtension**. + +The returned *ControllerObject* pointer, the entry point of the driver's *ControllerControl* routine, the *DeviceObject* pointer representing the target device for the current IRP, and a *Context* pointer to an area already set up for the *ControllerControl* routine must be passed in the driver's calls to [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224). Usually, a driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine sets up the area at *Context* before it calls **IoAllocateController**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20ControllerControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-irps-in-intermediate-drivers.md b/windows-driver-docs-pr/kernel/setting-up-irps-in-intermediate-drivers.md new file mode 100644 index 0000000000..e056badff4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-irps-in-intermediate-drivers.md @@ -0,0 +1,38 @@ +--- +title: Setting up IRPs in Intermediate Drivers +author: windows-driver-content +description: Setting up IRPs in Intermediate Drivers +ms.assetid: 0d04a951-a68e-4fa1-bdc6-dd92ec49deae +keywords: ["removable media WDK kernel , intermediate driver IRPs", "intermediate driver IRPs WDK removable media"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting up IRPs in Intermediate Drivers + + +## + + +Any intermediate driver layered between a file system driver and a removable-media device driver must set up the next-lower-level driver's I/O stack location in IRPs. From incoming [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794), [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819), and [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests, the intermediate driver must copy its own I/O stack location **Flags** into the next-lower-level driver's I/O stack location when it sets up the I/O stack location for the lower driver. + +If the intermediate driver allocates new IRPs for lower-level removable-media drivers, it must set up those IRPs as follows: + +- For transfer requests, it must set up the thread context in each driver-allocated IRP from the value at **Tail.Overlay.Thread** in the original IRP. + +- For **IRP\_MJ\_READ**, **IRP\_MJ\_WRITE**, and **IRP\_MJ\_DEVICE\_CONTROL** requests, it must copy the I/O stack location **Flags** from the original IRP to each driver-allocated IRP. + +Otherwise, the file system can neither maintain the integrity of cached file data nor cause the user to be prompted to remount the media that holds an open file. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20up%20IRPs%20in%20Intermediate%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-common-buffer-dma.md b/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-common-buffer-dma.md new file mode 100644 index 0000000000..120846fae6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-common-buffer-dma.md @@ -0,0 +1,48 @@ +--- +title: Setting Up the System DMA Controller for Common-Buffer DMA +author: windows-driver-content +description: Setting Up the System DMA Controller for Common-Buffer DMA +ms.assetid: 279776e0-dead-4763-9aae-33950837c27c +keywords: ["system DMA WDK kernel , common buffer", "common buffer DMA WDK kernel", "DMA transfers WDK kernel , common buffer", "AllocateAdapterChannel", "MapTransfer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up the System DMA Controller for Common-Buffer DMA + + +## + + +When **AllocateAdapterChannel** transfers control to a driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, the driver "owns" the system DMA controller and a set of map registers. Then, the driver must call [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) to set up the system DMA controller to use the driver-allocated common buffer before the driver sets up its device for the transfer operation. + +The driver supplies the following parameters to **MapTransfer**: + +- The adapter object pointer returned by **IoGetDmaAdapter** + +- A pointer to the MDL describing the driver-allocated common buffer + +- The *MapRegisterBase* handle passed to the driver's *AdapterControl* routine by **AllocateAdapterChannel** + +- A pointer to a variable (*Length*) indicating the size in bytes of the driver-allocated common buffer + +- A Boolean value, indicating the direction of the transfer operation (TRUE for a requested transfer from system memory to the device) + +**MapTransfer** returns a logical address, which drivers that use system DMA must ignore. When **MapTransfer** returns control, the driver should set up its device for the DMA operation. The driver calls **MapTransfer** only once but continues to copy data between its common buffer and a locked-down user buffer until the requested transfer is done. + +The driver can call [**ReadDmaCounter**](https://msdn.microsoft.com/library/windows/hardware/ff560782) to determine how many bytes currently remain to be transferred in the common buffer; the driver can then continue to fill its common buffer with user data or copy data from its common buffer to the user buffer, depending on the direction of the DMA operation. + +When the transfer is complete or if the driver must return an error status for the IRP, the driver calls [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) to ensure that any data cached in the system DMA controller is read into system memory or written out to the device. Then the driver should call [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) promptly to release the system DMA controller for use by any driver (including itself). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20the%20System%20DMA%20Controller%20for%20Common-Buffer%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-packet-based-dma.md b/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-packet-based-dma.md new file mode 100644 index 0000000000..cc292748e1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/setting-up-the-system-dma-controller-for-packet-based-dma.md @@ -0,0 +1,82 @@ +--- +title: Setting Up the System DMA Controller for Packet-Based DMA +author: windows-driver-content +description: Setting Up the System DMA Controller for Packet-Based DMA +ms.assetid: 3a646169-1ea3-4844-b771-d08f4ddec460 +keywords: ["system DMA WDK kernel , packet-based", "packet-based DMA WDK kernel", "DMA transfers WDK kernel , packet-based", "AllocateAdapterChannel", "MapTransfer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Setting Up the System DMA Controller for Packet-Based DMA + + +## + + +When [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) transfers control to a driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, the driver "owns" the system DMA controller and a set of map registers. Then, the driver must set up the DMA controller for a transfer operation, as shown in the following figure. + +![diagram illustrating programming the system dma controller](images/3dmaptsf.png) + +If the driver has a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) passes a pointer to **DeviceObject->CurrentIrp** in the *PIrp* parameter to the *AdapterControl* routine. If, however, the driver manages its own queue of IRPs, the driver should include a pointer to the current IRP as part of the context it passes to *AdapterControl*. + +As the previous figure shows, the driver's *AdapterControl* routine sets up the DMA transfer, as follows: + +1. The *AdapterControl* routine gets the address at which to start the transfer. For the initial transfer required to satisfy an IRP, the *AdapterControl* routine calls [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539), passing a pointer to the MDL at **Irp->MdlAddress**, which describes the buffer for this DMA transfer. + + **MmGetMdlVirtualAddress** returns a virtual address that the driver can use as an index for the system physical address where the transfer should start. + + If the IRP requires more than one transfer operation, the driver calculates an updated starting address, as described later in this section. + +2. The *AdapterControl* routine saves the address returned by **MmGetMdlVirtualAddress** or calculated in step 1. This address is a required parameter (*CurrentVa*) to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402). + +3. The *AdapterControl* routine calls **MapTransfer** to set up the system DMA controller, supplying the following parameters: + + - The adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) + + - A pointer (*Mdl*) to the MDL at **Irp->MdlAddress** for the current IRP + + - The *MapRegisterBase* handle passed to the driver's *AdapterControl* routine by **AllocateAdapterChannel** + + - The value (*CurrentVa*) returned by **MmGetMdlVirtualAddress** if this is the first call to **MapTransfer** for the IRP + + Otherwise, the driver supplies an updated *CurrentVa* value, indicating where in the buffer the next transfer operation should start. + + - A pointer to a variable (*Length*) indicating the number of bytes for this transfer + + If the driver can transfer all the requested data with a single call to **MapTransfer** and has no device-specific constraints on its DMA operations, *Length* can be set to the value of **Length** in the driver's I/O stack location of the IRP. At most, the length in bytes can be (PAGE\_SIZE \* the *NumberOfMapRegisters* returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220)). Otherwise, the driver must split up the request, as explained in [Splitting Transfer Requests](splitting-dma-transfer-requests.md), and must update the value of *Length* in subsequent calls to **MapTransfer** for the current IRP. + + - A Boolean value (*WriteToDevice*), indicating the direction of the transfer operation (TRUE to transfer data from system memory to the device) + + **MapTransfer** returns a logical address. Drivers that use system DMA must ignore this value. + +4. The *AdapterControl* routine sets up the device for the DMA operation. + +5. The *AdapterControl* routine returns **KeepObject**. + +When the device indicates that its current DMA operation has completed, the driver should call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917), usually from the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine. + +The *DpcForIsr* routine or another driver routine that completes a DMA operation calls **FlushAdapterBuffers** to ensure that any data cached in the system DMA controller is read into system memory or written out to the device. The same routine also must call **MapTransfer** again if it is necessary to reprogram the system DMA controller to transfer more data for the current IRP. Similarly, it must call **FlushAdapterBuffers** again following each transfer operation. + +If a driver must call **MapTransfer** more than once for the current IRP, it supplies the same adapter object pointer, *Mdl* pointer, *MapRegisterBase* handle, and transfer direction in every call. However, the driver must update the *CurrentVa* and *Length* parameters before it makes the second and any subsequent calls to **MapTransfer**. To calculate an updated value for each of these parameters, use the following formulas: + +- *CurrentVa* = *CurrentVa* + (*Length* requested in the preceding call to **MapTransfer**) + +- *Length* = Minimum (remaining **Length** to be transferred, (PAGE\_SIZE \* *NumberOfMapRegisters* returned by **IoGetDmaAdapter**)) + +The context information each driver should maintain about its DMA transfers depends on the needs of its particular device. Typical context might include the current virtual address in the MDL (*CurrentVa*), the number of bytes transferred so far, the number of bytes remaining to transfer, possibly a pointer to the current IRP, and any other information the driver writer deems useful. + +When the requested transfer is complete, or if the driver must return an error status for the IRP, the driver should call [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) promptly to release the system DMA controller for other drivers and this driver to use. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Setting%20Up%20the%20System%20DMA%20Controller%20for%20Packet-Based%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/sharing-processor-resources-during-startup-from-a-low-power-state.md b/windows-driver-docs-pr/kernel/sharing-processor-resources-during-startup-from-a-low-power-state.md new file mode 100644 index 0000000000..1931c08476 --- /dev/null +++ b/windows-driver-docs-pr/kernel/sharing-processor-resources-during-startup-from-a-low-power-state.md @@ -0,0 +1,37 @@ +--- +title: Sharing Processor Resources During Startup from a Low-Power State +author: windows-driver-content +description: Sharing Processor Resources During Startup from a Low-Power State +ms.assetid: 2b2e6a1b-7c2d-4f38-9407-a417b75daa6a +--- + +# Sharing Processor Resources During Startup from a Low-Power State + + +When a computer is started from a standby or hibernation state (warm startup), drivers should avoid using processor resources for longer than is necessary. Most importantly, deferred procedure call (DPC) routines and code that executes at IRQL >= DISPATCH\_LEVEL should keep their execution times to a minimum. Drivers use DPC routines to help to initialize devices. Drivers might need to run initialization code at DISPATCH\_LEVEL as part of a port-miniport interface contract. + +While a DPC routine runs, other threads of lower priority are blocked from running on the same processor. In addition, other DPC routines that are queued and ready to run might be blocked until the current DPC is finished. To enable other threads to run expediently, a typical DPC routine should run for no more than 100 microseconds. + +A DPC routine that runs for too long during system startup can delay the initialization of other devices. This delay makes the device initialization phase longer and delays startup completion by the operating system. + +Use the following best practices to design your DPC routines: + +- A single DPC routine should not execute for more than 100 microseconds. + +- DPC routines that call the [**KeStallExecutionProcessor**](https://msdn.microsoft.com/library/windows/hardware/ff553295) routine to delay execution must not specify delays of more than 100 microseconds. + +- If a task requires longer than 100 microseconds and executes at DISPATCH\_LEVEL, the DPC routine should end after 100 microseconds and schedule one or more DPC timer routines to complete the task at a later time. + +- Use the performance analysis tools that are documented in the WDK to evaluate the execution times of DPC routines. + +For more information about performance analysis tools, see [Measuring System Resume Performance on Windows Vista](http://go.microsoft.com/fwlink/p/?linkid=69964). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Sharing%20Processor%20Resources%20During%20Startup%20from%20a%20Low-Power%20State%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/single-binary-opt-in-pool-nx-optin.md b/windows-driver-docs-pr/kernel/single-binary-opt-in-pool-nx-optin.md new file mode 100644 index 0000000000..2df2076445 --- /dev/null +++ b/windows-driver-docs-pr/kernel/single-binary-opt-in-pool-nx-optin.md @@ -0,0 +1,47 @@ +--- +title: Single Binary Opt-In POOL_NX_OPTIN +author: windows-driver-content +description: To build a single driver binary that runs both in Windows 8 and in earlier versions of Windows, use the POOL_NX_OPTIN opt-in mechanism. +ms.assetid: BE9D3C85-0212-4206-A59B-4D53FB842C39 +--- + +# Single Binary Opt-In: POOL\_NX\_OPTIN + + +To build a single driver binary that runs both in Windows 8 and in earlier versions of Windows, use the POOL\_NX\_OPTIN opt-in mechanism. This is a porting aid for third-party hardware vendors who supply a single driver binary to support multiple Windows versions. + +To use this opt-in mechanism, do the following: + +- Define POOL\_NX\_OPTIN = 1 for all source files that you want to opt-in. To do this, include the following preprocessor definition in the appropriate property page for your driver project: + + `C_DEFINES=$(C_DEFINES) -DPOOL_NX_OPTIN=1` + +- In your [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) (or equivalent) routine, include the following function call: + + `ExInitializeDriverRuntime(DrvRtPoolNxOptIn);` + + This call must occur before the driver makes any allocations that use the **NonPagedPool** pool type or makes any calls to the [**ExInitializeNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545301) routine. **ExInitializeDriverRuntime** is a force inline function and can be called on Windows 8 or earlier versions of Windows. + +For most drivers, these two tasks are sufficient to enable the opt-in mechanism for the single driver binary. + +## Implementation details + + +POOL\_NX\_OPTIN works by replacing **NonPagedPool** with a global [**POOL\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff559707) variable, `ExDefaultNonPagedPoolType`, which is initialized either to **NonPagedPoolNx** (for Windows 8 and later versions of Windows) or to **NonPagedPoolExecute** (for earlier versions of Windows). This opt-in mechanism enables your kernel-mode driver to run both on Windows 8, with the enhanced protection of NX pool, and on earlier versions of Windows, which do not support NX pool. The macro that converts instances of the **NonPagedPool** constant name to **NonPagedPoolNx** also converts instances of **NonPagedPoolCacheAligned** to **NonPagedPoolNxCacheAligned**. + +## Support for static libraries (.lib projects) + + +You can use the POOL\_NX\_OPTIN opt-in mechanism for a .lib project, but projects that link to the .lib generally must also use POOL\_NX\_OPTIN. At a minimum, the project that implements the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine must contain the following function call: + +`ExInitializeDriverRuntime(DrvRtPoolNxOptIn);` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Single%20Binary%20Opt-In:%20POOL_NX_OPTIN%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/singly-and-doubly-linked-lists.md b/windows-driver-docs-pr/kernel/singly-and-doubly-linked-lists.md new file mode 100644 index 0000000000..abd393a547 --- /dev/null +++ b/windows-driver-docs-pr/kernel/singly-and-doubly-linked-lists.md @@ -0,0 +1,200 @@ +--- +title: Singly and Doubly Linked Lists +author: windows-driver-content +description: Singly and Doubly Linked Lists +ms.assetid: 3a305f54-7866-4163-a3e4-e078d1927adc +keywords: ["singly linked lists WDK kernel", "doubly linked lists WDK kernel", "sequenced singly linked lists WDK kernel", "SINGLE_LIST_ENTRY", "LIST_ENTRY"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Singly and Doubly Linked Lists + + +## + + +### Singly Linked Lists + +The operating system provides built-in support for singly linked lists that use [**SINGLE\_LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff563799) structures. A singly linked list consists of a list head plus some number of list entries. (The number of list entries is zero if the list is empty.) Each list entry is represented as a **SINGLE\_LIST\_ENTRY** structure. The list head is also represented as a **SINGLE\_LIST\_ENTRY** structure. + +Each **SINGLE\_LIST\_ENTRY** structure contains a **Next** member that points to another **SINGLE\_LIST\_ENTRY** structure. In the **SINGLE\_LIST\_ENTRY** structure that represents the list head, the **Next** member points to the first entry in the list, or is NULL if the list is empty. In the **SINGLE\_LIST\_ENTRY** structure that represents an entry in the list, the **Next** member points to the next entry of the list, or is NULL if this entry is the last in the list. + +The routines that manipulate a singly linked list take a pointer to a [**SINGLE\_LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff563799) that represents the list head. They update the **Next** pointer so that it points to the first entry of the list after the operation. + +Suppose that the *ListHead* variable is a pointer to the **SINGLE\_LIST\_ENTRY** structure that represents the list head. A driver manipulates *ListHead* as follows: + +- To initialize the list as empty, set *ListHead***->Next** to be **NULL**. + +- To add a new entry to the list, allocate a **SINGLE\_LIST\_ENTRY** to represent the new entry, and then call [**PushEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff559964) to add the entry to beginning of the list. + +- Pop the first entry off the list by using [**PopEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff559712). + +A **SINGLE\_LIST\_ENTRY**, by itself, only has a **Next** member. To store your own data in the lists, embed the **SINGLE\_LIST\_ENTRY** as a member of the structure that describes the list entry, as follows. + +``` +typedef struct { + // driver-defined members + . + . + . + SINGLE_LIST_ENTRY SingleListEntry; + + // other driver-defined members + . + . + . +} XXX_ENTRY; +``` + +To add a new entry to the list, allocate an **XXX\_ENTRY** structure, and then pass a pointer to the **SingleListEntry** member to [**PushEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff559964). To convert a pointer to the **SINGLE\_LIST\_ENTRY** back to an **XXX\_ENTRY**, use [**CONTAINING\_RECORD**](https://msdn.microsoft.com/library/windows/hardware/ff542043). Here is an example of routines that insert and remove driver-defined entries from a singly linked list. + +``` +typedef struct { + PVOID DriverData1; + SINGLE_LIST_ENTRY SingleListEntry; + ULONG DriverData2; +} XXX_ENTRY, *PXXX_ENTRY; + +void +PushXxxEntry(PSINGLE_LIST_ENTRY ListHead, PXXX_ENTRY Entry) +{ + PushEntryList(ListHead, &(Entry->SingleListEntry)); +} + +PXXX_ENTRY +PopXxxEntry(PSINGLE_LIST_ENTRY ListHead) +{ + PSINGLE_LIST_ENTRY SingleListEntry; + SingleListEntry = PopEntryList(ListHead); + return CONTAINING_RECORD(SingleListEntry, XXX_ENTRY, SingleListEntry); +} +``` + +The system also provides atomic versions of the list operations, [**ExInterlockedPopEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff545408) and [**ExInterlockedPushEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff545418). Each takes an additional spin lock parameter. The routine acquires the spin lock before it updates the list, and then the routine releases the spin lock after the operation is completed. While the lock is held, interrupts are disabled. Each operation on the list must use the same spin lock to ensure that each such operation on the list is synchronized with every other operation. You must use the spin lock only with these **ExInterlocked*Xxx*List** routines. Do not use the spin lock for any other purpose. Drivers can use the same lock for multiple lists, but this behavior increases lock contention so drivers should avoid it. + +For example, the **ExInterlockedPopEntryList** and **ExInterlockedPushEntryList** routines can support sharing of a singly linked list by a driver thread running at IRQL = PASSIVE\_LEVEL and an ISR running at DIRQL. These routines disable interrupts when the spin lock is held. Thus, the ISR and driver thread can safely use the same spin lock in their calls to these **ExInterlocked*Xxx*List** routines without risking a deadlock. + +Do not mix calls to the atomic and non-atomic versions of the list operations on the same list. If the atomic and non-atomic versions are run simultaneously on the same list, the data structure might become corrupted and the computer might stop responding or bug check (that is, *crash*). (You cannot acquire the spin lock while calling the non-atomic routine as an alternative to mixing calls to atomic and non-atomic versions of list operations. Using the spin lock in this fashion is not supported and might still cause list corruption.) + +The system also provides an alternative implementation of atomic singly linked lists that is more efficient. For more information, see [Sequenced Singly Linked Lists](#sequenced-singly-linked-lists). + +### Doubly Linked Lists + +The operating system provides built-in support for doubly linked lists that use [**LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff554296) structures. A doubly linked list consists of a list head plus some number of list entries. (The number of list entries is zero if the list is empty.) Each list entry is represented as a **LIST\_ENTRY** structure. The list head is also represented as a **LIST\_ENTRY** structure. + +Each **LIST\_ENTRY** structure contains an **Flink** member and a **Blink** member. Both members are pointers to **LIST\_ENTRY** structures. + +In the **LIST\_ENTRY** structure that represents the list head, the **Flink** member points to the first entry in the list and the **Blink** member points to the last entry in the list. If the list is empty, then **Flink** and **Blink** of the list head point to the list head itself. + +In the **LIST\_ENTRY** structure that represents an entry in the list, the **Flink** member points to the next entry in the list, and the **Blink** member points to the previous entry in the list. (If the entry is the last one in the list, **Flink** points to the list head. Similarly, if the entry is the first one in the list, **Blink** points to the list head.) + +(While these rules may seem surprising at first glance, they allow the list insertion and removal operations to implemented with no conditional code branches.) + +The routines that manipulate a doubly linked list take a pointer to a [**LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff554296) that represents the list head. These routines update the **Flink** and **Blink** members in the list head so that these members point to the first and last entries in the resulting list. + +Suppose that the *ListHead* variable is a pointer to the **LIST\_ENTRY** structure that represents the list head. A driver manipulates *ListHead* as follows: + +- To initialize the list as empty, use [**InitializeListHead**](https://msdn.microsoft.com/library/windows/hardware/ff547799), which initializes *ListHead***->Flink** and *ListHead***->Blink** to point to *ListHead*. + +- To insert a new entry at the head of the list, allocate a **LIST\_ENTRY** to represent the new entry, and then call [**InsertHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff547820) to insert the entry at the beginning of the list. + +- To append a new entry to the tail of the list, allocate a **LIST\_ENTRY** to represent the new entry, and then call [**InsertTailList**](https://msdn.microsoft.com/library/windows/hardware/ff547823) to insert the entry at the end of the list. + +- To remove the first entry from the list, use [**RemoveHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff561032). This returns a pointer to the removed entry from the list, or to *ListHead* if the list is empty. + +- To remove the last entry from the list, use [**RemoveTailList**](https://msdn.microsoft.com/library/windows/hardware/ff561036). This returns a pointer to the removed entry from the list, or to *ListHead* if the list is empty. + +- To remove a specified entry from the list, use [**RemoveEntryList**](https://msdn.microsoft.com/library/windows/hardware/ff561029). + +- To check to see if a list is empty, use [**IsListEmpty**](https://msdn.microsoft.com/library/windows/hardware/ff551789). + +- To append a list to the tail of another list, use [**AppendTailList**](https://msdn.microsoft.com/library/windows/hardware/jj673018). + +A [**LIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff554296), by itself, only has **Blink** and **Flink** members. To store your own data in the lists, embed the **LIST\_ENTRY** as a member of the structure that describes the list entry, as follows. + +``` +typedef struct { + // driver-defined members + . + . + . + LIST_ENTRY ListEntry; + + // other driver-defined members. + . + . + . +} XXX_ENTRY; +``` + +To add a new entry to a list, allocate an **XXX\_ENTRY** structure, and then pass a pointer to the **ListEntry** member to **InsertHeadList** or **InsertTailList**. To convert a pointer to a **LIST\_ENTRY** back to an **XXX\_ENTRY**, use [**CONTAINING\_RECORD**](https://msdn.microsoft.com/library/windows/hardware/ff542043). For an example of this technique, using singly linked lists, see Singly Linked Lists above. + +The system also provides atomic versions of the list operations, [**ExInterlockedInsertHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff545397), [**ExInterlockedInsertTailList**](https://msdn.microsoft.com/library/windows/hardware/ff545402), and [**ExInterlockedRemoveHeadList**](https://msdn.microsoft.com/library/windows/hardware/ff545427). (Note that there is no atomic version of **RemoveTailList** or **RemoveEntryList**.) Each routine takes an additional spin lock parameter. The routine acquires the spin lock before updating the list and then releases the spin lock after the operation is completed. While the lock is held, interrupts are disabled. Each operation on the list must use the same spin lock to ensure that each such operation on the list is synchronized with every other. You must use the spin lock only with these **ExInterlocked*Xxx*List** routines. Do not use the spin lock for any other purpose. Drivers can use the same lock for multiple lists, but this behavior increases lock contention so drivers should avoid it. + +For example, the **ExInterlockedInsertHeadList**, **ExInterlockedInsertTailList**, and **ExInterlockedRemoveHeadList** routines can support sharing of a doubly linked list by a driver thread running at IRQL = PASSIVE\_LEVEL and an ISR running at DIRQL. These routines disable interrupts when the spin lock is held. Thus, the ISR and driver thread can safely use the same spin lock in their calls to these **ExInterlocked*Xxx*List** routines without risking a deadlock. + +Do not mix calls to the atomic and non-atomic versions of the list operations on the same list. If the atomic and non-atomic versions are run simultaneously on the same list, the data structure might become corrupt and the computer might stop responding or bug check (that is, *crash*). (You cannot work acquire the spin lock while calling the non-atomic routine to avoid mixing calls to atomic and non-atomic versions of the list operations. Using the spin lock in this fashion is not supported and might still cause list corruption.) + +### Sequenced Singly Linked Lists + +A sequenced singly linked list is an implementation of singly linked lists that supports atomic operations. It is more efficient for atomic operations than the implementation of singly linked lists described in [Singly Linked Lists](#singly-linked-lists). + +An [**SLIST\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff563810) structure is used to describe the head of a sequenced singly linked list, while [**SLIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff563805) is used to describe an entry in the list. + +A driver manipulates the list as follows: + +- To initialize an **SLIST\_HEADER** structure, use [**ExInitializeSListHead**](https://msdn.microsoft.com/library/windows/hardware/ff545321). + +- To add a new entry to the list, allocate a **SLIST\_ENTRY** to represent the new entry, and then call [**ExInterlockedPushEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545422) to add the entry to the beginning of the list. + +- Pop the first entry off the list by using [**ExInterlockedPopEntrySList**](https://msdn.microsoft.com/library/windows/hardware/ff545414). + +- To clear the list completely, use [**ExInterlockedFlushSList**](https://msdn.microsoft.com/library/windows/hardware/ff545379). + +- To determine the number of entries in the list, use [**ExQueryDepthSList**](https://msdn.microsoft.com/library/windows/hardware/ff545502). + +A [**SLIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff563805), by itself, only has a **Next** member. To store your own data in the lists, embed the **SLIST\_ENTRY** as a member of the structure that describes the list entry, as follows. + +``` +typedef struct +{ + // driver-defined members + . + . + . + SLIST_ENTRY SListEntry; + // other driver-defined members + . + . + . + +} XXX_ENTRY; +``` + +To add a new entry to the list, allocate an **XXX\_ENTRY** structure, and then pass a pointer to the **SListEntry** member to **ExInterlockedPushEntrySList**. To convert a pointer to the **SLIST\_ENTRY** back to an **XXX\_ENTRY**, use [**CONTAINING\_RECORD**](https://msdn.microsoft.com/library/windows/hardware/ff542043). For an example of this technique, using non-sequenced singly linked lists, see [Singly Linked Lists](#singly-linked-lists). + +**Warning**   For 64-bit Microsoft Windows operating systems, [**SLIST\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff563805) structures must be 16-byte aligned. + +  + +Windows XP and later versions of Windows provide optimized versions of the sequenced singly linked list functions that are not available in Windows 2000. If your driver uses these functions and also must run with Windows 2000, the driver must define the \_WIN2K\_COMPAT\_SLIST\_USAGE flag, as follows: + +``` +#define _WIN2K_COMPAT_SLIST_USAGE +``` + +For x86-based processors, this flag causes the compiler to use versions of the sequenced singly linked list functions that are compatible with Windows 2000. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Singly%20and%20Doubly%20Linked%20Lists%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/specifying-context-information.md b/windows-driver-docs-pr/kernel/specifying-context-information.md new file mode 100644 index 0000000000..cacc075d61 --- /dev/null +++ b/windows-driver-docs-pr/kernel/specifying-context-information.md @@ -0,0 +1,47 @@ +--- +title: Specifying Context Information +author: windows-driver-content +description: Specifying Context Information +ms.assetid: 7133529f-5a6c-4df1-8d03-1c79c0d98fa9 +keywords: ["filtering registry calls WDK kernel , context information", "registry filtering drivers WDK kernel , context information", "context information", "context information WDK filter registry call"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specifying Context Information + + +The configuration manager provides several ways for registry filtering drivers to assign context information to registry operations. A registry filtering driver can: + +- Assign context information to the [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine. + + When your driver calls [**CmRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541918) or [**CmRegisterCallbackEx**](https://msdn.microsoft.com/library/windows/hardware/ff541921) to register for notification of a registry operation, the driver can specify a driver-defined context value. The configuration manager passes this context value to the driver's *RegistryCallback* routine each time that the configuration manager calls the routine. + + This context information is supported starting with Windows XP. + +- Assign context information to a registry operation. + + Drivers can store operation-specific context information in the **CallContext** member of each **REG\_*XXX*\_KEY\_INFORMATION** structure that the driver's *RegistryCallback* routine receives. If your driver receives both a pre-notification and a post-notification for a registry operation, the [**REG\_POST\_OPERATION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560971) structure contains a pointer to the appropriate pre-notification structure. When a *RegistryCallback* routine receives a **REG\_POST\_OPERATION\_INFORMATION** structure, the **CallContext** member of that structure matches the **CallContext** member of the pre-notification structure. + + The **CallContext** member of these structures is available starting with Windows Vista. + +- Assign context information to a registry key object. + + A [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine can assign context information to a particular registry key object. If the *RegistryCallback* routine calls [**CmSetCallbackObjectContext**](https://msdn.microsoft.com/library/windows/hardware/ff541924) to assign context information to a key object, subsequent pre-notifications and post-notifications for all operations on the object will include the context value in the **ObjectContext** member of each **REG\_*XXX*\_KEY\_INFORMATION** structure. If a driver provides multiple *RegistryCallback* routines, the driver can assign different context information for each routine, for a single registry key object. + + If a driver has called **CmSetCallbackObjectContext**, the driver's *RegistryCallback* routine will receive a **RegNtCallbackObjectContextCleanup** notification after the key object's handle has been closed. In response to this notification, the routine should release any resources that it allocated for the object's context. When the *Argument1* parameter to the *RegistryCallback* routine is **RegNtCallbackObjectContextCleanup**, the *Argument2* parameter is a pointer to a [**REG\_CALLBACK\_CONTEXT\_CLEANUP\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff560919) structure that contains a pointer to the context. + + The **CmSetCallbackObjectContext** routine and **RegNtCallbackObjectContextCleanup** notification are available starting with Windows Vista. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Specifying%20Context%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/specifying-device-characteristics.md b/windows-driver-docs-pr/kernel/specifying-device-characteristics.md new file mode 100644 index 0000000000..4c3dd89888 --- /dev/null +++ b/windows-driver-docs-pr/kernel/specifying-device-characteristics.md @@ -0,0 +1,60 @@ +--- +title: Specifying Device Characteristics +author: windows-driver-content +description: Specifying Device Characteristics +ms.assetid: 8b73ed62-d611-4515-b9d0-8e0a37555a1a +keywords: ["device objects WDK kernel , device characteristics", "device characteristics WDK device objects", "flags WDK device objects", "device stacks WDK kernel , device characteristics"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specifying Device Characteristics + + +## + + +Each device object can have one or more device characteristics. Device characteristics are stored as flags in the **Characteristics** member of the device object's [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. + +Most drivers specify only the FILE\_DEVICE\_SECURE\_OPEN characteristic. This ensures that the same security settings are applied to any open request into the device's namespace. For more information, see [Controlling Device Namespace Access](controlling-device-namespace-access.md). + +The FILE\_AUTOGENERATED\_DEVICE\_NAME is only used for PDOs. The FILE\_FLOPPY\_DISKETTE, FILE\_REMOVABLE\_MEDIA, and FILE\_WRITE\_ONCE\_MEDIA characteristics are specific to storage devices. For a description of the possible device characteristic flags, see the description of the **Characteristics** member of [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147). + +Certain device characteristics, such as FILE\_AUTOGENERATED\_DEVICE\_NAME, only apply to individual device objects. Drivers can specify a setting for the device characteristics for individual device objects when they create the device object by calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) or [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407). + +The following characteristics apply to the entire device stack: + +FILE\_DEVICE\_SECURE\_OPEN + +FILE\_FLOPPY\_DISKETTE + +FILE\_READ\_ONLY\_DEVICE + +FILE\_REMOVABLE\_MEDIA + +FILE\_WRITE\_ONCE\_MEDIA + +Drivers can set device characteristics that apply to the entire device stack by calling **IoCreateDevice** or **IoCreateDeviceSecure**. Alternatively, device characteristics that apply to the entire device stack can be set in the registry, for either the device or for the device's setup class. (For more information, see [Setting Device Object Properties in the Registry](setting-device-object-properties-in-the-registry.md).) + +The PnP manager determines the registry setting for device characteristics as follows. + +- If a value is specified for the individual device, the PnP manager uses that value; + +- Otherwise, if a value is specified for the device setup class, the PnP manager uses that value; + +- Otherwise, the PnP manager uses a value of zero as the registry setting. + +If a device characteristic that applies to the entire device stack is set in the registry, or if it is set for any FDO or filter DO in the stack, then the PnP manager sets it for every device object in the stack. (If the device is [*raw mode*](https://msdn.microsoft.com/library/windows/hardware/ff556331#wdkgloss-raw-mode) capable, and thus does not have an FDO, then the PnP manager uses the PDO instead.) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Specifying%20Device%20Characteristics%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/specifying-device-types.md b/windows-driver-docs-pr/kernel/specifying-device-types.md new file mode 100644 index 0000000000..ba3e1647df --- /dev/null +++ b/windows-driver-docs-pr/kernel/specifying-device-types.md @@ -0,0 +1,105 @@ +--- +title: Specifying Device Types +author: windows-driver-content +description: Specifying Device Types +ms.assetid: 32e179f9-ab11-4360-b2fd-4276c6b6b3a0 +keywords: ["device objects WDK kernel , device types", "device types WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specifying Device Types + + +## + + +Each device object has a *device type*, which is stored in the **DeviceType** member of its [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. The device type represents the type of underlying hardware for the driver. + +Every kernel-mode driver that creates a device object must specify an appropriate device type value when calling [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397). The **IoCreateDevice** routine uses the supplied device type to initialize the **DeviceType** member of the **DEVICE\_OBJECT** structure. + +The system defines the following device type values, listed in alphabetical order: + +``` +#define FILE_DEVICE_8042_PORT 0x00000027 +#define FILE_DEVICE_ACPI 0x00000032 +#define FILE_DEVICE_BATTERY 0x00000029 +#define FILE_DEVICE_BEEP 0x00000001 +#define FILE_DEVICE_BUS_EXTENDER 0x0000002a +#define FILE_DEVICE_CD_ROM 0x00000002 +#define FILE_DEVICE_CD_ROM_FILE_SYSTEM 0x00000003 +#define FILE_DEVICE_CHANGER 0x00000030 +#define FILE_DEVICE_CONTROLLER 0x00000004 +#define FILE_DEVICE_DATALINK 0x00000005 +#define FILE_DEVICE_DFS 0x00000006 +#define FILE_DEVICE_DFS_FILE_SYSTEM 0x00000035 +#define FILE_DEVICE_DFS_VOLUME 0x00000036 +#define FILE_DEVICE_DISK 0x00000007 +#define FILE_DEVICE_DISK_FILE_SYSTEM 0x00000008 +#define FILE_DEVICE_DVD 0x00000033 +#define FILE_DEVICE_FILE_SYSTEM 0x00000009 +#define FILE_DEVICE_FIPS 0x0000003a +#define FILE_DEVICE_FULLSCREEN_VIDEO 0x00000034 +#define FILE_DEVICE_INPORT_PORT 0x0000000a +#define FILE_DEVICE_KEYBOARD 0x0000000b +#define FILE_DEVICE_KS 0x0000002f +#define FILE_DEVICE_KSEC 0x00000039 +#define FILE_DEVICE_MAILSLOT 0x0000000c +#define FILE_DEVICE_MASS_STORAGE 0x0000002d +#define FILE_DEVICE_MIDI_IN 0x0000000d +#define FILE_DEVICE_MIDI_OUT 0x0000000e +#define FILE_DEVICE_MODEM 0x0000002b +#define FILE_DEVICE_MOUSE 0x0000000f +#define FILE_DEVICE_MULTI_UNC_PROVIDER 0x00000010 +#define FILE_DEVICE_NAMED_PIPE 0x00000011 +#define FILE_DEVICE_NETWORK 0x00000012 +#define FILE_DEVICE_NETWORK_BROWSER 0x00000013 +#define FILE_DEVICE_NETWORK_FILE_SYSTEM 0x00000014 +#define FILE_DEVICE_NETWORK_REDIRECTOR 0x00000028 +#define FILE_DEVICE_NULL 0x00000015 +#define FILE_DEVICE_PARALLEL_PORT 0x00000016 +#define FILE_DEVICE_PHYSICAL_NETCARD 0x00000017 +#define FILE_DEVICE_PRINTER 0x00000018 +#define FILE_DEVICE_SCANNER 0x00000019 +#define FILE_DEVICE_SCREEN 0x0000001c +#define FILE_DEVICE_SERENUM 0x00000037 +#define FILE_DEVICE_SERIAL_MOUSE_PORT 0x0000001a +#define FILE_DEVICE_SERIAL_PORT 0x0000001b +#define FILE_DEVICE_SMARTCARD 0x00000031 +#define FILE_DEVICE_SMB 0x0000002e +#define FILE_DEVICE_SOUND 0x0000001d +#define FILE_DEVICE_STREAMS 0x0000001e +#define FILE_DEVICE_TAPE 0x0000001f +#define FILE_DEVICE_TAPE_FILE_SYSTEM 0x00000020 +#define FILE_DEVICE_TERMSRV 0x00000038 +#define FILE_DEVICE_TRANSPORT 0x00000021 +#define FILE_DEVICE_UNKNOWN 0x00000022 +#define FILE_DEVICE_VDM 0x0000002c +#define FILE_DEVICE_VIDEO 0x00000023 +#define FILE_DEVICE_VIRTUAL_DISK 0x00000024 +#define FILE_DEVICE_WAVE_IN 0x00000025 +#define FILE_DEVICE_WAVE_OUT 0x00000026 +``` + +These constants are defined in Ntddk.h and Wdm.h. Check these files to see whether additional device types have been defined. + +The FILE\_DEVICE\_DISK specification covers disk partitions and any object that appears as a disk. + +Intermediate drivers usually specify device types that represent the underlying device. For example, the system-supplied fault-tolerant disk driver, *ftdisk*, creates device objects of type FILE\_DEVICE\_DISK; it does not define new device types for the mirror sets, stripe sets, and volume sets it manages. + +FILE\_DEVICE\_*XXX* values in the range of 0 through 32767 are reserved for Microsoft. All driver writers must use these system-defined constants for devices belonging to the system-defined device types. + +If a type of hardware does not match any of the defined types, specify a value of either FILE\_DEVICE\_UNKNOWN, or a value within the range of 32768 through 65535. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Specifying%20Device%20Types%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/specifying-exclusive-access-to-device-objects.md b/windows-driver-docs-pr/kernel/specifying-exclusive-access-to-device-objects.md new file mode 100644 index 0000000000..4bdcd0f576 --- /dev/null +++ b/windows-driver-docs-pr/kernel/specifying-exclusive-access-to-device-objects.md @@ -0,0 +1,36 @@ +--- +title: Specifying Exclusive Access to Device Objects +author: windows-driver-content +description: Specifying Exclusive Access to Device Objects +ms.assetid: b492251b-55b0-4323-a508-b395bb3da0ef +keywords: ["exclusive access WDK device objects", "device objects WDK kernel , exclusive access", "single access WDK device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Specifying Exclusive Access to Device Objects + + +## + + +If exclusive access to a device is enabled, only one handle to the device can be open at a time. For the I/O manager to enforce exclusive access to the device, the exclusive property must be set for the named device object in the device stack. + +For a WDM device stack that has a both a PDO and an FDO, the exclusive property can be set only by the INF file, by using an [**INF AddReg directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320). The PDO is the named object in the stack, but the bus driver (not the function driver itself) creates the PDO, on behalf of the function driver. The only way to direct the bus driver to set the exclusive flag for the PDO is by the class or device INF files. (The call to the [**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397) routine creates the FDO; setting the exclusive flag for the FDO has no effect.) + +Drivers whose device objects are not stacked, such as non-WDM drivers and devices that operate in raw mode, can use the [**IoCreateDeviceSecure**](https://msdn.microsoft.com/library/windows/hardware/ff548407) routine to set the exclusive property for their named device object. + +The I/O manager enforces exclusivity on a per name basis on named device objects, regardless of the trailing name. For example, suppose the device object has the name "\\Device\\DeviceName". Then, the I/O manager enforces exclusivity for a request to open "\\Device\\DeviceName\\*Filename1*" followed by "\\Device\\DeviceName\\*Filename2*". If two objects in the device stack are named (which is not recommended), the I/O manager allows a single handle to be opened for each object. In such a situation, drivers must enforce exclusivity themselves within their [*DispatchCreate*](https://msdn.microsoft.com/library/windows/hardware/ff543266) routines. The I/O manager also does not enforce exclusivity for opens relative to another file handle. For more information about file open requests in the device's namespace, see [Controlling Device Namespace Access](controlling-device-namespace-access.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Specifying%20Exclusive%20Access%20to%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/spin-locks.md b/windows-driver-docs-pr/kernel/spin-locks.md new file mode 100644 index 0000000000..e2c05803ae --- /dev/null +++ b/windows-driver-docs-pr/kernel/spin-locks.md @@ -0,0 +1,46 @@ +--- +title: Spin Locks +author: windows-driver-content +description: Spin Locks +ms.assetid: 0585fc2a-0d0b-434d-92b3-da07a9385444 +keywords: ["synchronization WDK kernel , spin locks", "locking WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Spin Locks + + +## + + +This section contains the following topics: + +[Introduction to Spin Locks](introduction-to-spin-locks.md) + +[Providing Storage for Spin Locks and Protected Data](providing-storage-for-spin-locks-and-protected-data.md) + +[Initializing Spin Locks](initializing-spin-locks.md) + +[Calling Support Routines That Use Spin Locks](calling-support-routines-that-use-spin-locks.md) + +[Using Spin Locks: An Example](using-spin-locks--an-example.md) + +[Preventing Errors and Deadlocks While Using Spin Locks](preventing-errors-and-deadlocks-while-using-spin-locks.md) + +[Queued Spin Locks](queued-spin-locks.md) + +[Reader/Writer Spin Locks](reader-writer-spin-locks.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Spin%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/splitting-dma-transfer-requests.md b/windows-driver-docs-pr/kernel/splitting-dma-transfer-requests.md new file mode 100644 index 0000000000..b9e6b9eae9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/splitting-dma-transfer-requests.md @@ -0,0 +1,82 @@ +--- +title: Splitting DMA Transfer Requests +author: windows-driver-content +description: Splitting DMA Transfer Requests +ms.assetid: 7d5b1649-1021-4876-a9c0-e6b156785ef2 +keywords: ["I/O WDK kernel , splitting transfer requests", "splitting transfer requests", "transfer request splitting WDK kernel", "data transfers WDK kernel , splitting requests", "transferring data WDK kernel , splitting requests"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Splitting DMA Transfer Requests + + +## + + +Any driver might need to split up a transfer request and carry out more than one DMA transfer operation to satisfy a given IRP, depending on the following: + +- The number of [map registers](map-registers.md) returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) + +- The bytes of data to be transferred, contained in the **Length** member of the driver's I/O stack location for the IRP + +- The number of page boundaries, in system physical memory, for the buffer into which or from which the driver is to transfer data + +- Device-specific constraints on the driver's DMA operations. For example, the system "AT" disk driver must split up transfer requests for more than 256 sectors due to the disk controller's limitations. + +A driver can determine the number of map registers needed to transfer all the data specified by an IRP as follows: + +1. Call [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539), passing a pointer to the MDL at **Irp->MdlAddress**, to get the starting virtual address for the buffer. Note that a driver must not attempt to access memory using this virtual address. The value returned by **MmGetMdlVirtualAddress** is an index into the MDL, not necessarily a valid address. + +2. Pass the returned index and the value of **Length** in the driver's I/O stack location of the IRP to the [**ADDRESS\_AND\_SIZE\_TO\_SPAN\_PAGES**](https://msdn.microsoft.com/library/windows/hardware/ff540562) macro. + +If the value returned by **ADDRESS\_AND\_SIZE\_TO\_SPAN\_PAGES** is greater than the *NumberOfMapRegisters* value returned by **IoGetDmaAdapter**, the driver cannot transfer all requested data for this IRP in a single DMA operation. Instead, it must do the following: + +1. Split the buffer into pieces that are sized to suit the number of available map registers (and any device-specific DMA constraints). + +2. Carry out as many DMA operations as it takes to satisfy the transfer request. + +For example, suppose **ADDRESS\_AND\_SIZE\_TO\_SPAN\_PAGES** indicates that twelve map registers are needed to satisfy a transfer request, but the *NumberOfMapRegisters* value returned by **IoGetDmaAdapter** is only five. (Assume no device-specific DMA constraints.) In this case, the driver must carry out three DMA transfer operations, calling [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) three times to transfer all the data requested by the IRP. + +The system's DMA device drivers use various techniques to split up a DMA transfer when there are not enough map registers to satisfy an IRP with a single I/O operation. One technique to use is the following: + +1. Call [**IoAllocateMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548263) to allocate an MDL describing a portion of the user buffer. + +2. Call [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) to lock down that portion of the user buffer. + +3. Transfer the data for that portion of the buffer. + +4. Call [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) and do either of the following: + - If the MDL that the driver allocated in step 1 is large enough for the next piece of the transfer, call [**MmPrepareMdlForReuse**](https://msdn.microsoft.com/library/windows/hardware/ff554660) and repeat steps 2 through 4. + - Otherwise, call [**IoFreeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff549126) and repeat steps 1 through 4. + +5. Call [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) and [**IoFreeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff549126) when all the data has been transferred. + +If a highest-level driver cannot lock down the entire user buffer with [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) in a machine with limited memory, it can do the following: + +1. Call [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330) to allocate a partial-transfer IRP and lock down a portion of the user buffer. The locked-down area is usually either a multiple of **PAGE\_SIZE** or is sized to suit the underlying device's transfer capacity. + +2. Call [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) for the partial-transfer IRP, and call [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) to wait for an event object that the driver set up to be associated with its partial-transfer IRP, if lower drivers return STATUS\_PENDING. + +3. When it regains control, repeat steps 1 and 2 until all the data has been transferred, and, then, complete the original IRP. + +When a storage class driver splits up large transfer requests for underlying SCSI port/miniport drivers, it allocates an additional IRP for each piece of the transfer request. It registers an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for each driver-allocated IRP, to track the status of the full transfer request and to free the driver-allocated IRPs. Then it sends these IRPs on to the port driver using [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336). + +Other class/port drivers can use this technique only if the class driver can determine how many map registers are available to the port driver. The port driver must store this configuration information in the registry for the paired class driver, or the paired drivers must define a private interface, using internal device I/O control requests, to pass configuration information about the number of available map registers from the port driver to the class driver. + +A monolithic driver (that is, a driver not part of a class/port pair) for a DMA device must split up large transfer requests for itself. Such drivers usually split a large request into pieces and carry out a sequence of DMA operations in order to satisfy the IRP. + +If a transfer request is too large for the underlying device driver to handle, a higher-level driver can call [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) and [**IoBuildPartialMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548324), then set up a sequence of partial-transfer IRPs for underlying device drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Splitting%20DMA%20Transfer%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/standard-driver-routine-requirements.md b/windows-driver-docs-pr/kernel/standard-driver-routine-requirements.md new file mode 100644 index 0000000000..750c7df7ad --- /dev/null +++ b/windows-driver-docs-pr/kernel/standard-driver-routine-requirements.md @@ -0,0 +1,44 @@ +--- +title: Standard Driver Routine Requirements +author: windows-driver-content +description: Standard Driver Routine Requirements +ms.assetid: 49b382ad-c282-41d2-b8b3-68eca4e12b9c +keywords: ["standard driver routines WDK kernel , requirements", "driver routines WDK kernel , requirements", "routines WDK kernel , requirements"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Standard Driver Routine Requirements + + +## + + +Keep the following points in mind when designing a kernel-mode driver: + +- Each driver must have a [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine, which initializes driver-wide data structures and resources. The I/O manager calls the **DriverEntry** routine when it loads the driver. + +- Every driver must have at least one dispatch routine that receives and processes I/O request packets (IRPs). Each driver must place a dispatch routine's entry point in its [**DRIVER\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff544174) structure, for each [IRP major function code](https://msdn.microsoft.com/library/windows/hardware/ff550710) that the driver can receive. A driver can have a separate dispatch routine for each IRP major function code, or it can have one or more dispatch routines that handle several function codes. + +- Every WDM driver must have an [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine. The driver must place the *Unload* routine's entry point in the driver's driver object. The responsibilities of a [PnP driver's Unload routine](pnp-driver-s-unload-routine.md) are minimal, but a [non-PnP driver's unload routine](non-pnp-driver-s-unload-routine.md) is responsible for releasing any system resources that the driver is using. + +- Every WDM driver must have an [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine and define its entry point in the [*driver extension*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-driver-extension) of the driver object. An *AddDevice* routine is responsible for creating and initializing device objects for each PnP device the driver controls. + +- A driver can have a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, which the I/O manager calls to start I/O operations for IRPs the driver has queued to a system-supplied IRP queue. Any driver that does not have a *StartIo* routine must either set up and manage internal queues for the IRPs it receives, or it must complete every IRP within its dispatch routines. Higher-level drivers might not have a *StartIo* routine, if they simply pass IRPs to lower-level drivers directly from their dispatch routines. + +- Certain miniport drivers are exceptions to the preceding requirements. See the device-type-specific documentation in the Windows Driver Kit (WDK) for information about the requirements for miniport drivers. + +- Whether a driver has any other kind of standard routine depends on its functionality and on how that driver fits into the system (for example, whether it interoperates with system-supplied drivers). See the device-type specific documentation in the WDK for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Standard%20Driver%20Routine%20Requirements%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/standard-event-objects.md b/windows-driver-docs-pr/kernel/standard-event-objects.md new file mode 100644 index 0000000000..fc9d953a85 --- /dev/null +++ b/windows-driver-docs-pr/kernel/standard-event-objects.md @@ -0,0 +1,65 @@ +--- +title: Standard Event Objects +author: windows-driver-content +description: Standard Event Objects +ms.assetid: 3c34c485-28b1-45d5-9e79-05dd2b26015e +keywords: ["event objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Standard Event Objects + + +## + + +The system provides several standard event objects. Drivers can use these event objects to be notified by the system whenever certain conditions occur. The following list contains the standard event objects: + +**\\KernelObjects\\HighMemoryCondition** +This event is set whenever the amount of free physical memory exceeds a system-defined amount. Drivers can wait for this event to be set as a signal to aggressively allocate memory. + +**\\KernelObjects\\LowMemoryCondition** +This event is set whenever the amount of free physical memory falls below a system-defined amount. Drivers that have allocated large amounts of memory can wait for this event to be set as a signal to free unused memory. + +For Microsoft Windows Server 2003 and later versions of Windows, drivers can also use the following additional standard event objects: + +**\\KernelObjects\\HighPagedPoolCondition** +This event is set whenever the amount of free paged pool exceeds a system-defined amount. Drivers can wait for this event to be set as a signal to aggressively allocate memory from paged pool. + +**\\KernelObjects\\LowPagedPoolCondition** +This event is set whenever the amount of free paged pool falls below a system-defined amount. Drivers that have allocated large amounts of memory can wait for this event to be set as a signal to free unused memory from paged pool. + +**\\KernelObjects\\HighNonPagedPoolCondition** +This event is set whenever the amount of free nonpaged pool exceeds a system-defined amount. Drivers can wait for this event to be set as a signal to aggressively allocate memory from nonpaged pool. + +**\\KernelObjects\\LowNonPagedPoolCondition** +This event is set whenever the amount of free nonpaged pool falls below a system-defined amount. Drivers that have allocated large amounts of memory can wait for this event to be set as a signal to free unused memory from nonpaged pool. + +For Windows Vista and later versions of Windows, drivers can also use the following additional standard event objects: + +**\\KernelObjects\\LowCommitCondition** +This event is set when the operating system's [*commit charge*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-commit-charge) is low, relative to the [*current commit limit*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-current-commit-limit). In other words, memory usage is low and a lot of space is available in physical memory or paging files. + +**\\KernelObjects\\HighCommitCondition** +This event is set when the operating system's commit charge is high, relative to the current commit limit. In other words, memory usage is high and very little space is available in physical memory or paging files, but the operating system might be able to increase the size of its paging files. + +**\\KernelObjects\\MaximumCommitCondition** +This event is set when the operating system's commit charge is near the [*maximum commit limit*](https://msdn.microsoft.com/library/windows/hardware/ff556308#wdkgloss-maximum-commit-limit). In other words, memory usage is very high, very little space is available in physical memory or paging files, and the operating system cannot increase the size of its paging files. (A system administrator can always increase the size or number of paging files, without restarting the computer, if sufficient storage resources exist.) + +Each of these events are notification events. They remain set as long as the triggering condition remains true. + +To open a handle to any of these events, use the [**IoCreateNotificationEvent**](https://msdn.microsoft.com/library/windows/hardware/ff549039) routine. A driver that waits for any of these events should create a dedicated thread to do the waiting. The thread can wait for one or more of these events by calling either [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) or [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Standard%20Event%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/starting-a-device-in-a-bus-driver.md b/windows-driver-docs-pr/kernel/starting-a-device-in-a-bus-driver.md new file mode 100644 index 0000000000..3f50a9b8fa --- /dev/null +++ b/windows-driver-docs-pr/kernel/starting-a-device-in-a-bus-driver.md @@ -0,0 +1,44 @@ +--- +title: Starting a Device in a Bus Driver +author: windows-driver-content +description: Starting a Device in a Bus Driver +ms.assetid: 1babeabb-1866-4ca5-b5a3-380c246596e5 +keywords: ["bus drivers WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Starting a Device in a Bus Driver + + +## + + +A bus driver starts a child device (child [*PDO*](https://msdn.microsoft.com/library/windows/hardware/ff556325#wdkgloss-pdo)) with a procedure such as the following in its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine: + +1. Start the device. + + The exact steps vary from device to device. + + For example, the PCI bus driver programs its mapping registers to enable requests on the PCI bus. The PnP ISA bus driver enables the PnP ISA card so the function driver can access it. + +2. Complete the IRP. + + If the bus driver's start operations were successful, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS and calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) specifying a priority boost of IO\_NO\_INCREMENT. The bus driver returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + If the bus driver encounters an error during its start operations, the driver sets an error status in the IRP, calls **IoCompleteRequest** with IO\_NO\_INCREMENT, and returns the error from its *DispatchPnP* routine. + +If a bus driver requires some time to start the device, it can mark the IRP as pending and return STATUS\_PENDING. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Starting%20a%20Device%20in%20a%20Bus%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/starting-a-device-in-a-filter-driver.md b/windows-driver-docs-pr/kernel/starting-a-device-in-a-filter-driver.md new file mode 100644 index 0000000000..1390538597 --- /dev/null +++ b/windows-driver-docs-pr/kernel/starting-a-device-in-a-filter-driver.md @@ -0,0 +1,32 @@ +--- +title: Starting a Device in a Filter Driver +author: windows-driver-content +description: Starting a Device in a Filter Driver +ms.assetid: d7c527b6-a5fb-4c4f-a8bc-29f961d31125 +keywords: ["filter drivers WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Starting a Device in a Filter Driver + + +## + + +An upper-level filter driver might augment any of the start activities of the function driver. + +A lower-level filter typically augments the features of the device and might participate in starting the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Starting%20a%20Device%20in%20a%20Filter%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/starting-a-device-in-a-function-driver.md b/windows-driver-docs-pr/kernel/starting-a-device-in-a-function-driver.md new file mode 100644 index 0000000000..9f49e92897 --- /dev/null +++ b/windows-driver-docs-pr/kernel/starting-a-device-in-a-function-driver.md @@ -0,0 +1,80 @@ +--- +title: Starting a Device in a Function Driver +author: windows-driver-content +description: Starting a Device in a Function Driver +ms.assetid: 148a3128-9cb1-4a2c-a62e-45199476d968 +keywords: ["function drivers WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Starting a Device in a Function Driver + + +## + + +A function driver sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, passes an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request down the device stack, and postpones its start operations until all lower drivers have finished with the IRP. See [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md) for detailed information about using a kernel event and an *IoCompletion* routine to postpone IRP processing. + +When its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine regains control after all lower drivers have finished with the IRP, the function driver performs its tasks for starting the device. A function driver starts the device with a procedure like the following: + +1. If a lower driver failed the IRP ([**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) returned an error), do not continue processing the IRP. Do any necessary cleanup and return from the *DispatchPnP* routine (go to the last step in this list). + +2. If lower drivers processed the IRP successfully, start the device. + + The exact steps to start a device vary from device to device. Such steps might include mapping I/O space, initializing hardware registers, setting the device in the D0 power state, and connecting the interrupt with [**IoConnectInterrupt**](https://msdn.microsoft.com/library/windows/hardware/ff548371). If the driver is restarting a device after an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request, the driver might have device state to restore. + + The device must be powered on before any drivers can access it. See [Powering Up a Device](powering-up-a-device.md) for more information. + + If the device should be enabled for wake-up, its power policy owner (usually the function driver) should send a wait/wake IRP after it powers up the device and before it completes the **IRP\_MN\_START\_DEVICE** request. For details, see [Sending a Wait/Wake IRP](sending-a-wait-wake-irp.md). + +3. Start IRPs in the IRP-holding queue. + + Clear the driver-defined HOLD\_NEW\_REQUESTS flag and start the IRPs in the IRP-holding queue. Drivers should do this when starting a device for the first time and when restarting a device after a query-stop or stop IRP. See [Holding Incoming IRPs When A Device Is Paused](holding-incoming-irps-when-a-device-is-paused.md) for more information. + +4. \[Optional\] Enable interfaces for the device by calling [**IoSetDeviceInterfaceState**](https://msdn.microsoft.com/library/windows/hardware/ff549700). + + Enable the interfaces, if any, that the driver previously registered in its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine (or in an INF or by another component such as a co-installer). + + On Windows 2000 and later versions of Windows, the PnP manager does not send notification of device-interface arrivals until the **IRP\_MN\_START\_DEVICE** IRP completes, indicating that all the drivers for the device have completed their start operations. The PnP manager also fails any create requests that arrive before all the drivers for the device complete the start IRP. + +5. Complete the IRP. + + The function driver's *IoCompletion* routine returned STATUS\_MORE\_PROCESSING\_REQUIRED, as described in [Postponing PnP IRP Processing Until Lower Drivers Finish](postponing-pnp-irp-processing-until-lower-drivers-finish.md), so the function driver's *DispatchPnP* routine must call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) to resume I/O completion processing. + + If the function driver's start operations were successful, the driver sets **Irp->IoStatus.Status** to STATUS\_SUCCESS, calls **IoCompleteRequest** with a priority boost of IO\_NO\_INCREMENT, and returns STATUS\_SUCCESS from its *DispatchPnP* routine. + + If the function driver encounters an error during its start operations, the driver sets an error status in the IRP, calls **IoCompleteRequest** with IO\_NO\_INCREMENT, and returns the error from its *DispatchPnP* routine. + + If a lower driver failed the IRP (**IoCallDriver** returned an error), the function driver calls **IoCompleteRequest** with IO\_NO\_INCREMENT and returns the **IoCallDriver** error from its *DispatchPnP* routine. The function driver does not set **Irp->IoStatus.Status** in this case because the status has already been set by the lower driver that failed the IRP. + +When a function driver receives an **IRP\_MN\_START\_DEVICE** request, it should examine the structures at **IrpSp->Parameters.StartDevice.AllocatedResources** and **IrpSp->Parameters.StartDevice.AllocatedResourcesTranslated**, which describe the raw and translated resources, respectively, that the PnP manager has assigned to the device. Drivers should save a copy of each resource list in the device extension as a debugging aid. + +The resource lists are paired [**CM\_RESOURCE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff541994) structures, in which each element of the raw list corresponds to the same element of the translated list. For example, if **AllocatedResources.List**\[0\] describes a raw I/O port range, then **AllocatedResourcesTranslated.List**\[0\] describes the same range after translation. Each translated resource includes a physical address and the type of the resource. + +If a driver is assigned a translated memory resource (**CmResourceTypeMemory**), it must call [**MmMapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff554618) to map the physical address into a virtual address through which it can access device registers. For a driver to operate in a platform independent manner, it should check each returned, translated resource and map it, if necessary. + +A function driver should do the following in response to an **IRP\_MN\_START\_DEVICE** to ensure access to all device resources: + +1. Copy **IrpSp->Parameters.StartDevice.AllocatedResources** to the device extension. + +2. Copy **IrpSp->Parameters.StartDevice.AllocatedResourcesTranslated** to the device extension. + +3. In a loop, inspect each descriptor element in **AllocatedResourcesTranslated**. If the descriptor resource type is **CmResourceTypeMemory**, call **MmMapIoSpace**, passing the physical address and length of the translated resource. + +When the driver receives an **IRP\_MN\_STOP\_DEVICE**, **IRP\_MN\_REMOVE\_DEVICE**, or **IRP\_MN\_SURPRISE\_REMOVAL** request, it must release the mappings by calling [**MmUnmapIoSpace**](https://msdn.microsoft.com/library/windows/hardware/ff556387) in a similar loop. The driver should also call **MmUnmapIoSpace** if it must fail the **IRP\_MN\_START\_DEVICE** request. + +See [Mapping Bus-Relative Addresses to Virtual Addresses](mapping-bus-relative-addresses-to-virtual-addresses.md) for more information. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Starting%20a%20Device%20in%20a%20Function%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/starting-a-device.md b/windows-driver-docs-pr/kernel/starting-a-device.md new file mode 100644 index 0000000000..2132016ac7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/starting-a-device.md @@ -0,0 +1,46 @@ +--- +title: Starting a Device +author: windows-driver-content +description: Starting a Device +ms.assetid: c52588cf-04c8-420d-a68e-a8754a65d546 +keywords: ["PnP WDK kernel , starting devices", "Plug and Play WDK kernel , starting devices", "starting PnP devices", "DispatchPnP routine", "IoCompletion routine", "failed starts WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Starting a Device + + +## + + +The PnP manager sends an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request to drivers either to start a newly enumerated device or to restart an existing device that was stopped for resource rebalancing. + +Function and filter drivers must set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine, pass the **IRP\_MN\_START\_DEVICE** request down the device stack, and postpone their start operations until all lower drivers have finished with the IRP. The parent bus driver, the bottom driver in the device stack, must be the first driver to perform its start operations on a device before the device is accessed by other drivers. + +To ensure proper sequencing of start operations, the PnP manager on Windows 2000 and later versions of Windows postpones exposing device interfaces and blocks create requests for the device until the start IRP succeeds. + +If a driver for a device fails the **IRP\_MN\_START\_DEVICE** request, the PnP manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request to the device stack (on Windows 2000 and later versions of Windows). In response to this IRP, the drivers for the device undo their start operations (if they succeeded the start IRP), undo their [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) operations, and detach from the device stack. The PnP manager marks such a device "failed start." + +This section covers the following topics: + +[Starting a Device in a Function Driver](starting-a-device-in-a-function-driver.md) + +[Starting a Device in a Filter Driver](starting-a-device-in-a-filter-driver.md) + +[Starting a Device in a Bus Driver](starting-a-device-in-a-bus-driver.md) + +[Design Guidelines for Starting Devices](design-guidelines-for-starting-devices.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Starting%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/startio-routines-in-higher-level-drivers.md b/windows-driver-docs-pr/kernel/startio-routines-in-higher-level-drivers.md new file mode 100644 index 0000000000..4860a5d6e0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/startio-routines-in-higher-level-drivers.md @@ -0,0 +1,48 @@ +--- +title: StartIo Routines in Higher-Level Drivers +author: windows-driver-content +description: StartIo Routines in Higher-Level Drivers +ms.assetid: 8b0e3bef-4a73-4cf8-b71a-6aedf451d648 +keywords: ["StartIo routines, higher-level drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# StartIo Routines in Higher-Level Drivers + + +## + + +Any higher-level driver can have a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine. However, such a driver is unlikely to be interoperable with existing lower-level drivers and is likely to exhibit poor performance characteristics. + +A *StartIo* routine in a higher-level driver has the following effects: + +- Incoming IRPs can be queued by calling [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) from the driver's *Dispatch*Xxx routine(s) and [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) from its [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine(s), thereby causing IRPs to be processed one at a time through the *StartIo* routine. + +- The driver's I/O throughput could become noticeably slower during periods of heavy I/O demand, because its *StartIo* routine can become a bottleneck. + +- The driver's *StartIo* routine calls [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) with each IRP at IRQL = DISPATCH\_LEVEL, thereby causing all lower-level drivers' dispatch routines also to run at IRQL = DISPATCH\_LEVEL. This restricts the set of support routines that lower drivers can call in their dispatch routines. Because most driver writers assume their drivers' dispatch routines run at IRQL < DISPATCH\_LEVEL, the higher-level driver is unlikely to be interoperable with many existing lower-level drivers. + +- The *StartIo* routine reduces overall system throughput because it and the dispatch routines of all lower-level drivers in its chain are run at IRQL = DISPATCH\_LEVEL. + + For more information about the IRQLs at which standard driver routines are run, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +None of the system-supplied higher-level drivers has a *StartIo* routine, because it can slow IRP processing for the driver itself, for all drivers above and below it, and for the system overall. + +Most higher-level drivers simply send IRPs to lower-level drivers from their dispatch routines and do any necessary clean-up processing in their *IoCompletion* routines. + +However, higher-level drivers can set up internal queues for IRPs that request particular kinds of operations, or set up internal queues to hold IRPs bound for a set of heterogeneous underlying devices like the SCSI port driver. For more information, see [Queuing and Dequeuing IRPs](queuing-and-dequeuing-irps.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20StartIo%20Routines%20in%20Higher-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/startio-routines-in-lowest-level-drivers.md b/windows-driver-docs-pr/kernel/startio-routines-in-lowest-level-drivers.md new file mode 100644 index 0000000000..c745057785 --- /dev/null +++ b/windows-driver-docs-pr/kernel/startio-routines-in-lowest-level-drivers.md @@ -0,0 +1,130 @@ +--- +title: StartIo Routines in Lowest-Level Drivers +author: windows-driver-content +description: StartIo Routines in Lowest-Level Drivers +ms.assetid: f79f8929-bcf4-46a2-bf0e-0f8fb0720dd9 +keywords: ["StartIo routines, lowest-level drivers", "I/O control requests WDK kernel", "buffered I/O WDK kernel", "direct I/O WDK kernel", "synchronization WDK IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# StartIo Routines in Lowest-Level Drivers + + +## + + +The I/O manager's call to a driver's dispatch routine is the first stage in satisfying a device I/O request. The [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine is the second stage. Every device driver with a *StartIo* routine is likely to call [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) from its [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) and [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) routines, and usually for a subset of the I/O control codes it supports in its [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine. The **IoStartPacket** routine adds the IRP to the device's system-supplied device queue or, if the queue is empty, immediately calls the driver's *StartIo* routine to process the IRP. + +You can assume that when a driver's *StartIo* routine is called, the target device is not busy. This is because the I/O manager calls *StartIo* under two circumstances; either one of the driver's dispatch routines has just called **IoStartPacket** and the device queue was empty, or the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine is completing another request and has just called [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) to dequeue the next IRP. + +Before the *StartIo* routine in a highest-level device driver is called, that driver's dispatch routine should have probed and locked down the user buffer, if necessary, to set up valid mapped buffer addresses in the IRP queued to its *StartIo* routine. If a highest-level device driver sets up its device objects for direct I/O (or for neither buffered nor direct I/O), the driver cannot defer locking down a user buffer to its *StartIo* routine; every *StartIo* routine is called in an arbitrary thread context at IRQL = DISPATCH\_LEVEL. + +**Note**   Any buffer memory to be accessed by a driver's *StartIo* routine must be locked down or allocated from resident, system-space memory and must be accessible in an arbitrary thread context. + +  + +In general, any lower-level device driver's *StartIo* routine is responsible for calling [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) with the input IRP and then doing whatever request-specific processing is necessary to start the I/O operation on its device. Request-specific processing can include the following: + +- Setting up or updating any state information about the current request that the driver maintains. The state information might be stored in the device extension of the target device object or elsewhere in nonpaged pool allocated by the driver. + + For example, if a device driver maintains an InterruptExpected Boolean for the current transfer operation, its *StartIo* routine might set this variable to **TRUE**. If the driver maintains a time-out counter for the current operation, its *StartIo* routine might set up this value, or the *StartIo* routine might queue the driver's [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine. + + If the *StartIo* routine shares access to state information or [hardware resources](hardware-resources.md) with other driver routines, the state information or resource must be protected by a spin lock. (See [Spin Locks](spin-locks.md).) + + If the *StartIo* routine shares access to state information or resources with the driver's [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine, *StartIo* must use [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine that accesses the state or resource information. (See [Using Critical Sections](using-critical-sections.md).) + +- Assigning a sequence number to the IRP in case the driver must log a device I/O error while processing the IRP. + + See [Logging Errors](logging-errors.md) for more information. + +- If necessary, translating the parameters in the driver's I/O stack location into device-specific values. + + For example, a disk driver might need to calculate the starting sector or byte offset to the physical disk address for a transfer operation, and whether the requested length of the transfer will cross a particular sector boundary or exceed the transfer capacity of its physical device. + +- If the driver controls a removable-media device, checking for media changes before programming the device for I/O and notifying its overlying file system if the media has changed. + + For more information, see [Supporting Removable Media](supporting-removable-media.md). + +- If the device uses DMA, checking whether the requested **Length** (number of bytes to be transferred, found in the driver's I/O stack location of the IRP) should be split into partial-transfer operations, as explained in [Input/Output Techniques](i-o-programming-techniques.md), assuming a closely coupled higher-level driver does not presplit large transfers for the device driver. + + The *StartIo* routine of such a device driver also can be responsible for calling [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) and, if the driver uses packet-based DMA, for calling [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) with the driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine. + + See [Adapter Objects and DMA](adapter-objects-and-dma.md), and [Maintaining Cache Coherency](maintaining-cache-coherency.md), for additional details. + +- If the device uses PIO, mapping the base virtual address of the buffer, described in the IRP at **Irp->MdlAddress**, to a system-space address with [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559). + + For read requests, the device driver's *StartIo* routine can be responsible for calling [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) before PIO operations begin. See [Maintaining Cache Coherency](maintaining-cache-coherency.md) for more information. + +- If a non-WDM driver uses a controller object, calling [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224) to register its [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine. + +- If the driver handles cancelable IRPs, checking whether the input IRP has already been canceled. + +- If an input IRP can be canceled before it is processed to completion, the *StartIo* routine must call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) with the IRP and the entry point of the driver's [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine. The *StartIo* routine must acquire the cancel spin lock for its call to **IoSetCancelRoutine**. Alternatively, a driver can use [**IoSetStartIoAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff550330) to set the *NonCancelable* attribute for the *StartIo* routine to **TRUE**. This prevents the system from trying to cancel an IRP that has been passed to *StartIo* by a call to [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370). + +As a general rule, a driver that uses buffered I/O has a simpler *StartIo* routine than one that uses direct I/O. Drivers that use buffered I/O transfer small amounts of data for each transfer request, while those that use direct I/O (whether DMA or PIO) transfer large amounts of data to or from locked-down buffers that can span physical page boundaries in system memory. + +Higher-level drivers layered above physical device drivers usually set up their device objects to match those of their respective device drivers. However, a highest-level driver, particularly a file system driver, can set up device objects for neither direct nor buffered I/O. + +Drivers that set up their device objects for buffered I/O can rely on the I/O manager to pass valid buffers in all IRPs it sends to the driver. Lower-level drivers that set up device objects for direct I/O can rely on the highest-level driver in their chain to pass valid buffers in all IRPs sent through any intermediate drivers to the underlying lower-level device driver. + +### Using Buffered I/O in StartIo Routines + +If a driver's [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034), or [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine determines that a request is valid and calls [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370), the I/O manager calls the driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine to process the IRP immediately if the device queue is empty. If the queue is not empty, **IoStartPacket** queues the IRP. Eventually, a call to [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) from the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine causes the I/O manager to dequeue the IRP and call the driver's *StartIo* routine. + +The *StartIo* routine calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) and determines which operation must be performed to satisfy the request. It preprocesses the IRP in any way necessary before programming the physical device to carry out the I/O request. + +If access to the physical device (or the device extension) must be synchronized with an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine, the *StartIo* routine must call a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine to perform the necessary device programming. For more information, see [Using Critical Sections](using-critical-sections.md). + +A physical device driver that uses buffered I/O transfers data either to or from a system-space buffer, allocated by the I/O manager, that the driver finds in each IRP at **Irp->AssociatedIrp.SystemBuffer**. + +### Using Direct I/O in StartIo Routines + +If a driver's [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034), or [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine determines that a request is valid and calls [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370), the I/O manager calls the driver's *StartIo* routine to process the IRP immediately if the device queue is empty. If the queue is not empty, **IoStartPacket** queues the IRP. Eventually, a call to [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) from the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine causes the I/O manager to dequeue the IRP and call the driver's *StartIo* routine. + +The *StartIo* routine calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174) and determines which operation must be performed to satisfy the request. It preprocesses the IRP in any way necessary, such as splitting up a large DMA transfer request into partial-transfer ranges and saving state about the **Length** of an incoming transfer request that must be split. Then it programs the physical device to carry out the I/O request. + +If access to the physical device (or the device extension) must be synchronized with the driver's ISR, the *StartIo* routine must use a driver-supplied *SynchCritSection* routine to perform the necessary programming. For more information, see [Using Critical Sections](using-critical-sections.md). + +Any driver that uses direct I/O either reads data into or writes data from a locked-down buffer, described by a memory descriptor list (MDL), that the driver finds in the IRP at **Irp->MdlAddress**. Such a driver commonly uses buffered I/O for device control requests. For more information, see [Handling I/O Control Requests in StartIo Routines](#ddk-handling-i-o-control-requests-in-startio-routines-kg). + +The MDL type is an opaque type that drivers do not access directly. Instead, drivers that use PIO remap user-space buffers by calling [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) with **Irp->MdlAddress** as a parameter. Drivers that use DMA also pass **Irp->MdlAddress** to support routines during their transfer operations to have the buffer addresses remapped to logical ranges for their devices. + +Unless a closely coupled higher-level driver splits up large DMA transfer requests for the underlying device driver, a lowest-level device driver's *StartIo* routine must split up each transfer request that is larger than its device can manage in a single transfer operation. Drivers that use system DMA are required to split transfer requests that are too large for the system DMA controller or for their devices to handle in a single transfer operation. + +If the device is a subordinate DMA device, its driver must synchronize transfers through a system DMA controller with a driver-allocated adapter object, representing the DMA channel, and a driver-supplied [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine. The driver of a bus-master DMA device also must use a driver-allocated adapter object to synchronize its transfers and must supply an *AdapterControl* routine if it uses the system's packet-based DMA support, or an [*AdapterListControl*](https://msdn.microsoft.com/library/windows/hardware/ff540513) routine if it uses the system's scatter/gather support. + +Depending on the driver's design, it might synchronize transfer and device control operations on a physical device with a controller object and supply a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine. + +See [Adapter Objects and DMA](adapter-objects-and-dma.md) and [Controller Objects](using-controller-objects.md) for more information. + +### Handling I/O Control Requests in StartIo Routines + +In general, only a subset of device I/O control requests are passed on from a driver's [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) or [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routine for further processing by the driver's *StartIo* routine. The driver's *StartIo* routine only has to handle valid device control requests that require device state changes or return volatile information about the current device state. + +Each new driver must support the same set of public I/O control codes as all other drivers for the same kind of device. The system defines public, device-type-specific I/O control codes for [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests as buffered requests. + +Consequently, physical device drivers make data transfers to or from a system-space buffer that each driver finds in the IRP at **Irp->AssociatedIrp.SystemBuffer** for device control requests. Even drivers that set up their device objects for direct I/O use buffered I/O to satisfy device control requests with public I/O control codes. + +The definition of each I/O control code determines whether data transferred for that request is buffered. Any privately defined I/O control codes for driver-specific [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests between paired drivers can define a code with method buffered, method direct, or method neither. As a general rule, any privately defined I/O control code should be defined with method neither if a closely coupled higher-level driver must allocate a buffer for that request. + +### Programming the Device for I/O Operations + +Usually, the *StartIo* routine in a lowest-level device driver must synchronize access to any memory or device registers it shares with the driver's ISR by using [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine. The driver's *StartIo* routine uses the *SynchCritSection* routine to actually program the physical device for I/O at DIRQL. For more information, see [Using Critical Sections](using-critical-sections.md). + +Before calling **KeSynchronizeExecution**, the *StartIo* routine must do any preprocessing necessary for the request. Preprocessing might include calculating an initial partial-transfer range and saving any state information about the original request for other driver routines. + +If a device driver uses DMA, its *StartIo* routine usually calls [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) with a driver-supplied [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine. In these circumstances, the *StartIo* routine postpones the responsibility for programming the physical device to the *AdapterControl* routine. It, in turn, can call **KeSynchronizeExecution** to have a driver-supplied *SynchCritSection* routine program the device for a DMA transfer. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20StartIo%20Routines%20in%20Lowest-Level%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/state-transitions-for-pnp-devices.md b/windows-driver-docs-pr/kernel/state-transitions-for-pnp-devices.md new file mode 100644 index 0000000000..cfac613fe5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/state-transitions-for-pnp-devices.md @@ -0,0 +1,50 @@ +--- +title: State Transitions for PnP Devices +author: windows-driver-content +description: State Transitions for PnP Devices +ms.assetid: 31969515-899b-407e-ab73-f6f7f36adb85 +keywords: ["PnP WDK kernel , state transitions", "Plug and Play WDK kernel , state transitions", "state transitions WDK PnP", "device states WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# State Transitions for PnP Devices + + +## + + +On a PnP system, a device transitions through various PnP states as it is configured, started, possibly stopped to rebalance resources, and possibly removed. This section provides an overview of the PnP device states. The overview is a road map for much of the PnP support required in a driver. Other parts of this documentation describe each state transition in detail. + +The following figure shows the PnP states for a device and how a device transitions from one state to another. + +![diagram illustrating device states from the plug and play perspective](images/pnp-states.png) + +Starting at the top left of the previous figure, a PnP device is physically present in the system because either the user just inserted the device or the device was present at boot time. The device is not yet known to the system software. + +To begin software configuration for the device, the PnP manager and the parent bus driver enumerate the device. The PnP manager, possibly with help from user-mode components, identifies the drivers for the device, including the function driver and any optional filter drivers. The PnP manager calls the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine of each driver if the driver is not yet loaded. For more information about reporting and enumerating a PnP device, see [Adding a PnP Device to a Running System](adding-a-pnp-device-to-a-running-system.md). + +Once a driver is initialized, it must be ready to initialize its devices. The PnP manager calls a driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine for each device the driver controls. + +When a driver receives an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request from the PnP manager, the driver starts the device and is ready to process I/O requests for the device. For information about handling an **IRP\_MN\_START\_DEVICE** request, see [Starting a Device](starting-a-device.md). + +If the PnP manager must reconfigure the hardware resources of an active device, it sends [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) and [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) requests to the device's drivers. After it reconfigures the hardware resources, the PnP manager directs the drivers to restart the device by sending an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. For information about handling stop IRPs, see [Stopping a Device](stopping-a-device.md). (The drivers for a boot-configured device can receive **IRP\_MN\_QUERY\_STOP\_DEVICE** and **IRP\_MN\_STOP\_DEVICE** requests before the device has been started, although this step is not shown in the previous figure.) + +On Windows 98/Me, the PnP manager also sends **IRP\_MN\_QUERY\_STOP\_DEVICE** and **IRP\_MN\_STOP\_DEVICE** requests when a device is being disabled. Drivers on these systems also receive an **IRP\_MN\_STOP\_DEVICE** request after a failed start. + +When a PnP device is being physically removed from the system or has already been removed, the PnP manager sends various remove IRPs to the device's drivers, directing them to remove the device's software representation (device objects, and so forth). For information about handling remove IRPs, see [Removing a Device](removing-a-device.md). + +At some point after all of a driver's devices have been removed, the PnP manager calls the driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine and unloads the driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20State%20Transitions%20for%20PnP%20Devices%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/stopping-a-device-after-a-failed-start--windows-98-me-.md b/windows-driver-docs-pr/kernel/stopping-a-device-after-a-failed-start--windows-98-me-.md new file mode 100644 index 0000000000..9f36765216 --- /dev/null +++ b/windows-driver-docs-pr/kernel/stopping-a-device-after-a-failed-start--windows-98-me-.md @@ -0,0 +1,32 @@ +--- +title: Stopping a Device after a Failed Start (Windows 98/Me) +author: windows-driver-content +description: Stopping a Device after a Failed Start (Windows 98/Me) +ms.assetid: 373a1797-6479-4b99-b577-c74494f1774c +keywords: ["failed starts WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stopping a Device after a Failed Start (Windows 98/Me) + + +## + + +On Windows 98/Me, the PnP manager issues an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) request without a preceding query when the drivers for a device fail an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. (On Windows 2000 and later, the PnP manager sends remove IRPs in this situation. See [Understanding When Remove IRPs Are Issued](understanding-when-remove-irps-are-issued.md).) + +In response to the stop IRP, drivers release the device's hardware resources (such as its I/O ports), disable and deregister any user-mode interfaces, and fail any incoming I/O requests that require access to the device. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Stopping%20a%20Device%20after%20a%20Failed%20Start%20%28Windows%2098/Me%29%20%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/stopping-a-device-to-disable-it--windows-98-me-.md b/windows-driver-docs-pr/kernel/stopping-a-device-to-disable-it--windows-98-me-.md new file mode 100644 index 0000000000..1f1d09fb4f --- /dev/null +++ b/windows-driver-docs-pr/kernel/stopping-a-device-to-disable-it--windows-98-me-.md @@ -0,0 +1,50 @@ +--- +title: Stopping a Device to Disable It (Windows 98/Me) +author: windows-driver-content +description: Stopping a Device to Disable It (Windows 98/Me) +ms.assetid: 2fc42fe4-ad29-4a51-9560-74b568bcd129 +keywords: ["disabling PnP devices"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stopping a Device to Disable It (Windows 98/Me) + + +## + + +On Windows 98/Me, the PnP manager issues stop IRPs when Device Manager disables the device. (Windows 2000 and later versions of Windows issue [remove IRPs](removing-a-device.md) in this situation). + +The PnP manager sends the stop IRPs in the following sequence: + +1. The PnP manager issues an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) to ask whether the drivers for a device can stop the device. + + If all the drivers in the device stack return STATUS\_SUCCESS, the drivers have put the device into a state (stop-pending) from which the device can be quickly stopped. + + The PnP manager queries as many device stacks as necessary to disable the device. + +2. If the **IRP\_MN\_QUERY\_STOP\_DEVICE** succeeds, the PnP manager issues an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) to stop the device. + + The PnP manager sends the stop IRP only if the previous query-stop IRP for the device completed successfully. In response to the stop IRP, drivers release the device's hardware resources (such as its I/O ports) and fail any IRPs that require access to the device. + +3. If the **IRP\_MN\_QUERY\_STOP\_DEVICE** fails, the PnP manager sends an [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826) to cancel the query. + + In response to an **IRP\_MN\_CANCEL\_STOP\_DEVICE**, the drivers for a device return the device to the started state and resume processing I/O requests for the device. + + The PnP manager cancels the query-stop for a device stack if one driver in the stack failed the request. When the PnP manager cancels the query-stop on just one device stack, it sends the **IRP\_MN\_CANCEL\_STOP\_DEVICE** request because any drivers attached above the driver that failed the query have the device in the stop-pending state. When the **IRP\_MN\_CANCEL\_STOP\_DEVICE** succeeds, drivers have returned the device to the started state. + +When a device is being disabled, its drivers cannot queue incoming IRPs because there is no guarantee when the device might be reenabled. Consequently, data might be lost. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Stopping%20a%20Device%20to%20Disable%20It%20%28Windows%2098/Me%29%20%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/stopping-a-device-to-rebalance-resources.md b/windows-driver-docs-pr/kernel/stopping-a-device-to-rebalance-resources.md new file mode 100644 index 0000000000..c0c216415a --- /dev/null +++ b/windows-driver-docs-pr/kernel/stopping-a-device-to-rebalance-resources.md @@ -0,0 +1,58 @@ +--- +title: Stopping a Device to Rebalance Resources +author: windows-driver-content +description: Stopping a Device to Rebalance Resources +ms.assetid: eed28d41-8a9d-4b9e-90d7-ea4ddeeaad2d +keywords: ["rebalancing resources WDK PnP", "resource rebalancing WDK PnP", "pausing PnP devices"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stopping a Device to Rebalance Resources + + +## + + +The following figure shows the sequence of IRPs involved in stopping and restarting a device to rebalance resources. + +![diagram illustrating stopping a device to rebalance resources](images/stop-irps.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. The PnP manager issues an [**IRP\_MN\_QUERY\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551725) to ask whether the drivers for a device can stop the device and release its hardware resources. + + If all the drivers in the device stack return STATUS\_SUCCESS, the drivers have put the device into a state (stop-pending) from which the device can be quickly stopped. + + The PnP manager queries as many device stacks as necessary to rebalance the required resources. + +2. The PnP manager issues an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) to stop the device. + + On Windows 2000 and later versions of Windows, the PnP manager sends a stop IRP only if a previous query-stop IRP for the device completed successfully. In response to a stop IRP, drivers release the device's hardware resources (such as its I/O ports) and hold any IRPs that require access to the device. + +3. After successfully rebalancing resources, the PnP manager issues [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) requests to restart any devices that it stopped during the rebalance. + +4. Otherwise, the PnP manager cancels a query-stop IRP by sending an [**IRP\_MN\_CANCEL\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550826). + + In response to an **IRP\_MN\_CANCEL\_STOP\_DEVICE**, the drivers for a device return the device to the started state and resume processing I/O requests for the device. + + The PnP manager cancels the query-stop for a device stack if one driver in the stack failed the request or if the overall rebalance operation failed and it is canceling all its query-stop requests. When the PnP manager cancels the query-stop on just one device stack, it sends the **IRP\_MN\_CANCEL\_STOP\_DEVICE** request because any drivers attached above the driver that failed the query have the device in the stop-pending state. When the **IRP\_MN\_CANCEL\_STOP\_DEVICE** succeeds, drivers have returned the device to the started state. + +5. If a driver fails to restart the device after rebalancing resources, the PnP manager sends remove IRPs to the device stack (on Windows 2000 and later versions of Windows). + + The PnP manager first sends an [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) request. Then it sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request, but only after all open handles to the device are closed. + +Rebalancing the hardware resources of a PnP device must be transparent to applications and end users. Users might experience a temporary delay in operation, but data must not be lost. You must take that into consideration when you handle stop IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Stopping%20a%20Device%20to%20Rebalance%20Resources%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/stopping-a-device.md b/windows-driver-docs-pr/kernel/stopping-a-device.md new file mode 100644 index 0000000000..4b95c05840 --- /dev/null +++ b/windows-driver-docs-pr/kernel/stopping-a-device.md @@ -0,0 +1,48 @@ +--- +title: Stopping a Device +author: windows-driver-content +description: Stopping a Device +ms.assetid: 65a47e7b-aabd-4b55-8fa6-c3482da1cc84 +keywords: ["PnP WDK kernel , stopping devices", "Plug and Play WDK kernel , stopping devices", "stopping PnP devices", "stop IRPs WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Stopping a Device + + +## + + +The PnP manager directs drivers to stop a device in the following situations: + +- To rebalance the hardware resources being used by the device. Rebalancing is typically necessary when a new device is enumerated that requires a resource already in use. + +- To disable the device in response to a Device Manager request (Windows 98/Me only). Windows 2000 and later versions of Windows send remove IRPs in this situation; see [Understanding When Remove IRPs Are Issued](understanding-when-remove-irps-are-issued.md). + +- After a failed [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request (Windows 98/Me only) + +This section covers the following topics: + +[Stopping a Device to Rebalance Resources](stopping-a-device-to-rebalance-resources.md) + +[Stopping a Device to Disable It (Windows 98/Me)](stopping-a-device-to-disable-it--windows-98-me-.md) + +[Stopping a Device after a Failed Start (Windows 98/Me)](stopping-a-device-after-a-failed-start--windows-98-me-.md) + +[Handling Stop IRPs (Windows 2000 and Later)](handling-stop-irps--windows-2000-and-later-.md) + +[Handling Stop IRPs (Windows 98/Me)](handling-stop-irps--windows-98-me-.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Stopping%20a%20Device%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/storage-requirements-for-adaptercontrol-routines.md b/windows-driver-docs-pr/kernel/storage-requirements-for-adaptercontrol-routines.md new file mode 100644 index 0000000000..5b651dd856 --- /dev/null +++ b/windows-driver-docs-pr/kernel/storage-requirements-for-adaptercontrol-routines.md @@ -0,0 +1,38 @@ +--- +title: Storage Requirements for AdapterControl Routines +author: windows-driver-content +description: Storage Requirements for AdapterControl Routines +ms.assetid: 5e5711df-9acd-4ac5-b6b2-4e90299afb24 +keywords: ["AdapterControl routines, storage", "AdapterControl routines, writing", "adapter objects WDK kernel , writing AdapterControl routines", "DMA transfers WDK kernel , writing AdapterControl routines", "storage WDK DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Storage Requirements for AdapterControl Routines + + +## + + +If it has an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, a driver must provide resident storage for the following: + +- Context information to be used in its DMA operations + +- An adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) + +- A ULONG-type variable to hold the system-determined maximum *NumberOfMapRegisters* available for any given DMA transfer request + +The driver can provide the necessary storage in a device extension, in a controller extension, or in nonpaged pool allocated by the driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Storage%20Requirements%20for%20AdapterControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/storage-requirements-for-controllercontrol-routines.md b/windows-driver-docs-pr/kernel/storage-requirements-for-controllercontrol-routines.md new file mode 100644 index 0000000000..93b98623fd --- /dev/null +++ b/windows-driver-docs-pr/kernel/storage-requirements-for-controllercontrol-routines.md @@ -0,0 +1,36 @@ +--- +title: Storage Requirements for ControllerControl Routines +author: windows-driver-content +description: Storage Requirements for ControllerControl Routines +ms.assetid: 1ee69144-5f52-4d61-ad30-02e8fbe1f91e +keywords: ["controller objects WDK kernel , writing ControllerControl routines", "ControllerControl routines, writing", "ControllerControl routines, storage", "storage WDK controller objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Storage Requirements for ControllerControl Routines + + +## + + +If it has a *ControllerControl* routine, a non-WDM driver must provide resident storage for a *ControllerObject* pointer returned by [**IoCreateController**](https://msdn.microsoft.com/library/windows/hardware/ff548395). + +A driver can provide the necessary storage in a device extension or in nonpaged pool allocated by the driver. Usually, drivers that use controller objects store the *ControllerObject* pointer in the device extension of each device object that represents a physical or logical device controlled by the hardware represented by the controller object. + +The driver writer determines the size and internal structure of the *ControllerObject*->**ControllerExtension**. + +A controller object, which cannot be given a name, cannot be the target of an I/O request. The hardware it represents usually controls a set of homogeneous devices that are the actual targets of I/O requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Storage%20Requirements%20for%20ControllerControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/summary-of-kernel-mode-safe-string-functions.md b/windows-driver-docs-pr/kernel/summary-of-kernel-mode-safe-string-functions.md new file mode 100644 index 0000000000..e2511ea435 --- /dev/null +++ b/windows-driver-docs-pr/kernel/summary-of-kernel-mode-safe-string-functions.md @@ -0,0 +1,365 @@ +--- +title: Summary of Kernel-Mode Safe String Functions +author: windows-driver-content +description: Summary of Kernel-Mode Safe String Functions +ms.assetid: 71b67d88-2a9a-4c9d-b64c-5fd7fe7e5cda +keywords: ["safe string functions WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Summary of Kernel-Mode Safe String Functions + + +## + + +The following table summarizes the safe string functions that are available to kernel-mode drivers, and it indicates the C/C++ language runtime library functions that they replace. If a function's name contains **Cb**, the function treats strings as byte-counted. If a function's name contains **Cch**, the function treats strings as character-counted. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionsPurposeReplaces

+
+
[RtlStringCbCat](https://msdn.microsoft.com/library/windows/hardware/ff562795)
+
+
+
[RtlStringCbCatEx](https://msdn.microsoft.com/library/windows/hardware/ff562799)
+
+
+
[RtlStringCchCat](https://msdn.microsoft.com/library/windows/hardware/ff562834)
+
+
+
[RtlStringCchCatEx](https://msdn.microsoft.com/library/windows/hardware/ff562835)
+
+
+
[RtlUnicodeStringCat](https://msdn.microsoft.com/library/windows/hardware/ff562898)
+
+
+
[RtlUnicodeStringCatEx](https://msdn.microsoft.com/library/windows/hardware/ff562899)
+
+
+
[RtlUnicodeStringCatString](https://msdn.microsoft.com/library/windows/hardware/ff562901)
+
+
+
[RtlUnicodeStringCatStringEx](https://msdn.microsoft.com/library/windows/hardware/ff562902)
+
+
+
[RtlUnicodeStringCbCatStringN](https://msdn.microsoft.com/library/windows/hardware/ff562908)
+
+
+
[RtlUnicodeStringCbCatStringNEx](https://msdn.microsoft.com/library/windows/hardware/ff562910)
+
+
+
[RtlUnicodeStringCchCatStringN](https://msdn.microsoft.com/library/windows/hardware/ff562924)
+
+
+
[RtlUnicodeStringCchCatStringNEx](https://msdn.microsoft.com/library/windows/hardware/ff562927)
+
+
+

Concatenate two strings.

+
+
strcat
+
+
+
wcscat
+
+
+

+
+
[RtlStringCbCatN](https://msdn.microsoft.com/library/windows/hardware/ff562801)
+
+
+
[RtlStringCbCatNEx](https://msdn.microsoft.com/library/windows/hardware/ff562802)
+
+
+
[RtlStringCchCatN](https://msdn.microsoft.com/library/windows/hardware/ff562836)
+
+
+
[RtlStringCchCatNEx](https://msdn.microsoft.com/library/windows/hardware/ff562837)
+
+
+
[RtlUnicodeStringCbCatN](https://msdn.microsoft.com/library/windows/hardware/ff562905)
+
+
+
[RtlUnicodeStringCbCatNEx](https://msdn.microsoft.com/library/windows/hardware/ff562906)
+
+
+
[RtlUnicodeStringCchCatN](https://msdn.microsoft.com/library/windows/hardware/ff562921)
+
+
+
[RtlUnicodeStringCchCatNEx](https://msdn.microsoft.com/library/windows/hardware/ff562923)
+
+
+

Concatenate two byte-counted strings, while limiting the size of the appended string.

+
+
strncat
+
+
+
wcsncat
+
+
+

+
+
[RtlStringCbCopy](https://msdn.microsoft.com/library/windows/hardware/ff562805)
+
+
+
[RtlStringCbCopyEx](https://msdn.microsoft.com/library/windows/hardware/ff562807)
+
+
+
[RtlStringCbCopyUnicodeString](https://msdn.microsoft.com/library/windows/hardware/ff562815)
+
+
+
[RtlStringCbCopyUnicodeStringEx](https://msdn.microsoft.com/library/windows/hardware/ff562817)
+
+
+
[RtlStringCchCopy](https://msdn.microsoft.com/library/windows/hardware/ff562841)
+
+
+
[RtlStringCchCopyEx](https://msdn.microsoft.com/library/windows/hardware/ff562843)
+
+
+
[RtlStringCchCopyUnicodeString](https://msdn.microsoft.com/library/windows/hardware/ff562851)
+
+
+
[RtlStringCchCopyUnicodeStringEx](https://msdn.microsoft.com/library/windows/hardware/ff562852)
+
+
+
[RtlUnicodeStringCopy](https://msdn.microsoft.com/library/windows/hardware/ff562942)
+
+
+
[RtlUnicodeStringCopyEx](https://msdn.microsoft.com/library/windows/hardware/ff562946)
+
+
+
[RtlUnicodeStringCopyString](https://msdn.microsoft.com/library/windows/hardware/ff562948)
+
+
+
[RtlUnicodeStringCopyStringEx](https://msdn.microsoft.com/library/windows/hardware/ff562950)
+
+
+

Copy a string into a buffer.

+
+
strcpy
+
+
+
wcscpy
+
+
+

+
+
[RtlStringCbCopyN](https://msdn.microsoft.com/library/windows/hardware/ff562811)
+
+
+
[RtlStringCbCopyNEx](https://msdn.microsoft.com/library/windows/hardware/ff562813)
+
+
+
[RtlStringCchCopyN](https://msdn.microsoft.com/library/windows/hardware/ff562846)
+
+
+
[RtlStringCchCopyNEx](https://msdn.microsoft.com/library/windows/hardware/ff562849)
+
+
+
[RtlUnicodeStringCbCopyN](https://msdn.microsoft.com/library/windows/hardware/ff562913)
+
+
+
[RtlUnicodeStringCbCopyNEx](https://msdn.microsoft.com/library/windows/hardware/ff562915)
+
+
+
[RtlUnicodeStringCchCopyN](https://msdn.microsoft.com/library/windows/hardware/ff562928)
+
+
+
[RtlUnicodeStringCchCopyNEx](https://msdn.microsoft.com/library/windows/hardware/ff562931)
+
+
+
[RtlUnicodeStringCbCopyStringN](https://msdn.microsoft.com/library/windows/hardware/ff562918)
+
+
+
[RtlUnicodeStringCbCopyStringNEx](https://msdn.microsoft.com/library/windows/hardware/ff562919)
+
+
+
[RtlUnicodeStringCchCopyStringN](https://msdn.microsoft.com/library/windows/hardware/ff562934)
+
+
+
[RtlUnicodeStringCchCopyStringNEx](https://msdn.microsoft.com/library/windows/hardware/ff562938)
+
+
+

Copy a string into a buffer, while limiting the size of the copied string.

+
+
strncpy
+
+
+
wcsncpy
+
+
+

+
+
[RtlStringCbLength](https://msdn.microsoft.com/library/windows/hardware/ff562820)
+
+
+
[RtlStringCchLength](https://msdn.microsoft.com/library/windows/hardware/ff562856)
+
+
+
[RtlUnalignedStringCbLength](https://msdn.microsoft.com/library/windows/hardware/ff562895)
+
+
+
[RtlUnalignedStringCchLength](https://msdn.microsoft.com/library/windows/hardware/ff562897)
+
+
+

Determine the length of a supplied string.

+
+
strlen
+
+
+
wcslen
+
+
+

+
+
[RtlStringCbPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562824)
+
+
+
[RtlStringCbPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562828)
+
+
+
[RtlStringCchPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562859)
+
+
+
[RtlStringCchPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562864)
+
+
+
[RtlUnicodeStringPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562961)
+
+
+
[RtlUnicodeStringPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562964)
+
+
+

Create a formatted text string that is based on a format string and a set of additional function arguments.

+
+
sprintf
+
+
+
swprintf
+
+
+
_snprintf
+
+
+
_snwprintf
+
+
+

+
+
[RtlStringCbVPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562831)
+
+
+
[RtlStringCbVPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562832)
+
+
+
[RtlStringCchVPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562865)
+
+
+
[RtlStringCchVPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562868)
+
+
+
[RtlUnicodeStringVPrintf](https://msdn.microsoft.com/library/windows/hardware/ff562983)
+
+
+
[RtlUnicodeStringVPrintfEx](https://msdn.microsoft.com/library/windows/hardware/ff562988)
+
+
+

Create a formatted text string that is based on a format string and one additional function argument.

+
+
vsprintf
+
+
+
vswprintf
+
+
+
_vsnprintf
+
+
+
_vsnwprintf
+
+
+

+
+
[RtlUnicodeStringInit](https://msdn.microsoft.com/library/windows/hardware/ff562954)
+
+
+
[RtlUnicodeStringInitEx](https://msdn.microsoft.com/library/windows/hardware/ff562958)
+
+
+
[RtlUnicodeStringValidate](https://msdn.microsoft.com/library/windows/hardware/ff562977)
+
+
+
[RtlUnicodeStringValidateEx](https://msdn.microsoft.com/library/windows/hardware/ff562982)
+
+
+

Initialize or validate a [UNICODE_STRING](https://msdn.microsoft.com/library/windows/hardware/ff564879) structure.

None

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Summary%20of%20Kernel-Mode%20Safe%20String%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/summary-of-read-write-dispatch-routines.md b/windows-driver-docs-pr/kernel/summary-of-read-write-dispatch-routines.md new file mode 100644 index 0000000000..bc3dccb225 --- /dev/null +++ b/windows-driver-docs-pr/kernel/summary-of-read-write-dispatch-routines.md @@ -0,0 +1,52 @@ +--- +title: Summary of Read/Write Dispatch Routines +author: windows-driver-content +description: Summary of Read/Write Dispatch Routines +ms.assetid: 2ab1cde7-89e8-449f-b2a0-12aa0762ebf3 +keywords: ["DispatchRead routine", "DispatchWrite routine", "DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchReadWrite routine", "dispatch routines WDK kernel , DispatchWrite routine", "dispatch routines WDK kernel , DispatchRead routine", "read/write dispatch routines WDK kernel", "IRP_MJ_WRITE I/O function codes", "IRP_MJ_READ I/O function codes", "data transfers WDK kernel , read/write dispatch routines", "transferring data WDK kernel , read/write dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Summary of Read/Write Dispatch Routines + + +## + + +Keep the following points in mind when implementing a [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376), [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034), or [*DispatchReadWrite*](https://msdn.microsoft.com/library/windows/hardware/ff543381) routine: + +- It is the responsibility of the highest-level driver in a chain of layered drivers to check the parameters of incoming read/write IRPs for validity before setting up the next-lower-level driver's I/O stack location in an IRP. + +- Intermediate and lowest-level drivers generally can rely on the highest-level driver in their chain to pass down transfer requests with valid parameters. However, any driver can perform sanity checks on the parameters in its I/O stack location of an IRP, and each device driver should check the parameters for conditions that might violate any restrictions imposed by its device. + +- If a *DispatchReadWrite* routine completes an IRP with an error, it should set the I/O stack location **Status** member with an appropriate NTSTATUS-type value, set the **Information** member to zero, and call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the IRP and a *PriorityBoost* of IO\_NO\_INCREMENT. + +- If a driver uses buffered I/O, it might need to define a structure to contain data to be transferred and might need to buffer some number of these structures internally. + +- If a driver uses direct I/O, it might need to check whether the MDL at **Irp->MdlAddress** describes a buffer containing too much data (or too many page breaks) for the underlying device to handle in a single transfer operation. If so, the driver must split up the original transfer request into a sequence of smaller transfer operations. + + A closely coupled class driver might split up such a request in its *DispatchReadWrite* routine for its underlying port driver. SCSI class drivers, particularly for mass-storage devices, are required to do this. For more information about requirements for SCSI drivers, see [Storage Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566976). + +- A lower-level device driver's *DispatchReadWrite* routine should postpone splitting a large transfer request into partial transfers until another driver routine dequeues the IRP to set up the device for the transfer. + +- If a lower-level device driver queues a read/write IRP for further processing by its own routines, it must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422) before it queues the IRP. The *DispatchReadWrite* routine also must return control with STATUS\_PENDING in these circumstances. + +- If the *DispatchReadWrite* routine passes an IRP on to lower drivers, it must set up the I/O stack location for the next-lower driver in the IRP. Whether the higher-level driver also sets an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine in the IRP before passing it on with [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) depends on the design of the driver and of those layered under it. + + However, a higher-level driver must call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) before it calls [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) if it allocates any resources, such as IRPs or memory. Its *IoCompletion* routine must free any driver-allocated resources when lower drivers have completed the request but before the *IoCompletion* routine calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the original IRP. + +- If a higher-level driver allocates IRPs for lower drivers that might include an underlying removable-media device driver, the allocating driver must establish the thread context in each IRP it allocates. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Summary%20of%20Read/Write%20Dispatch%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/summary-of-safe-integer-functions.md b/windows-driver-docs-pr/kernel/summary-of-safe-integer-functions.md new file mode 100644 index 0000000000..1a5a4fafba --- /dev/null +++ b/windows-driver-docs-pr/kernel/summary-of-safe-integer-functions.md @@ -0,0 +1,788 @@ +--- +title: Summary of Kernel-Mode Safe Integer Functions +author: windows-driver-content +description: The following table summarizes the safe integer functions that are available to kernel-mode drivers. +ms.assetid: 3DC016FA-5434-4581-9FBB-F6A8B54AB97B +--- + +# Summary of Kernel-Mode Safe Integer Functions + + +The following table summarizes the safe integer functions that are available to kernel-mode drivers. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionsPurpose

+
+
[RtlDWordPtrAdd](https://msdn.microsoft.com/library/windows/hardware/hh439701)
+
+
+
[RtlInt8Add](https://msdn.microsoft.com/library/windows/hardware/hh439716)
+
+
+
[RtlIntAdd](https://msdn.microsoft.com/library/windows/hardware/hh451198)
+
+
+
[RtlIntPtrAdd](https://msdn.microsoft.com/library/windows/hardware/hh451210)
+
+
+
[RtlLongLongAdd](https://msdn.microsoft.com/library/windows/hardware/hh451363)
+
+
+
[RtlLongPtrAdd](https://msdn.microsoft.com/library/windows/hardware/hh451428)
+
+
+
[RtlPtrdiffTAdd](https://msdn.microsoft.com/library/windows/hardware/hh463987)
+
+
+
[RtlShortAdd](https://msdn.microsoft.com/library/windows/hardware/hh463990)
+
+
+
[RtlSizeTAdd](https://msdn.microsoft.com/library/windows/hardware/hh464041)
+
+
+
[RtlSSIZETAdd](https://msdn.microsoft.com/library/windows/hardware/hh464048)
+
+
+
[RtlUInt8Add](https://msdn.microsoft.com/library/windows/hardware/hh464054)
+
+
+
[RtlUIntAdd](https://msdn.microsoft.com/library/windows/hardware/hh464066)
+
+
+
[RtlUIntPtrAdd](https://msdn.microsoft.com/library/windows/hardware/hh464072)
+
+
+
[RtlULongAdd](https://msdn.microsoft.com/library/windows/hardware/hh451458)
+
+
+
[RtlULongLongAdd](https://msdn.microsoft.com/library/windows/hardware/hh451459)
+
+
+
[RtlULongPtrAdd](https://msdn.microsoft.com/library/windows/hardware/hh451493)
+
+
+
[RtlUShortAdd](https://msdn.microsoft.com/library/windows/hardware/hh451543)
+
+
+

Addition Functions

+
+
[RtlDWordPtrMult](https://msdn.microsoft.com/library/windows/hardware/hh439705)
+
+
+
[RtlInt8Mult](https://msdn.microsoft.com/library/windows/hardware/hh439722)
+
+
+
[RtlIntMult](https://msdn.microsoft.com/library/windows/hardware/hh451203)
+
+
+
[RtlIntPtrMult](https://msdn.microsoft.com/library/windows/hardware/hh451216)
+
+
+
[RtlLongLongMult](https://msdn.microsoft.com/library/windows/hardware/hh451369)
+
+
+
[RtlLongMult](https://msdn.microsoft.com/library/windows/hardware/hh451424)
+
+
+
[RtlLongPtrMult](https://msdn.microsoft.com/library/windows/hardware/hh451432)
+
+
+
[RtlPtrdiffTMult](https://msdn.microsoft.com/library/windows/hardware/hh463988)
+
+
+
[RtlShortMult](https://msdn.microsoft.com/library/windows/hardware/hh463991)
+
+
+
[RtlSSIZETMult](https://msdn.microsoft.com/library/windows/hardware/hh464050)
+
+
+
[RtlUInt8Mult](https://msdn.microsoft.com/library/windows/hardware/hh464056)
+
+
+
[RtlSizeTMult](https://msdn.microsoft.com/library/windows/hardware/hh464043)
+
+
+
[RtlULongMult](https://msdn.microsoft.com/library/windows/hardware/hh451490)
+
+
+
[RtlULongLongMult](https://msdn.microsoft.com/library/windows/hardware/hh451460)
+
+
+
[RtlUIntPtrMult](https://msdn.microsoft.com/library/windows/hardware/hh464075)
+
+
+
[RtlUIntMult](https://msdn.microsoft.com/library/windows/hardware/hh464069)
+
+
+
[RtlULongPtrMult](https://msdn.microsoft.com/library/windows/hardware/hh451494)
+
+
+
[RtlUShortMult](https://msdn.microsoft.com/library/windows/hardware/hh451544)
+
+
+

Multiplication Functions

+
+
[RtlShortSub](https://msdn.microsoft.com/library/windows/hardware/hh463992)
+
+
+
[RtlUShortSub](https://msdn.microsoft.com/library/windows/hardware/hh451545)
+
+
+
[RtlULongPtrSub](https://msdn.microsoft.com/library/windows/hardware/hh451495)
+
+
+
[RtlULongLongSub](https://msdn.microsoft.com/library/windows/hardware/hh451461)
+
+
+
[RtlULongSub](https://msdn.microsoft.com/library/windows/hardware/hh451522)
+
+
+
[RtlUInt8Sub](https://msdn.microsoft.com/library/windows/hardware/hh464058)
+
+
+
[RtlUIntPtrSub](https://msdn.microsoft.com/library/windows/hardware/hh464077)
+
+
+
[RtlUIntSub](https://msdn.microsoft.com/library/windows/hardware/hh464116)
+
+
+
[RtlSSIZETSub](https://msdn.microsoft.com/library/windows/hardware/hh464052)
+
+
+
[RtlSizeTSub](https://msdn.microsoft.com/library/windows/hardware/hh464045)
+
+
+
[RtlDWordPtrSub](https://msdn.microsoft.com/library/windows/hardware/hh439710)
+
+
+
[RtlInt8Sub](https://msdn.microsoft.com/library/windows/hardware/hh439730)
+
+
+
[RtlPtrdiffTSub](https://msdn.microsoft.com/library/windows/hardware/hh463989)
+
+
+
[RtlLongSub](https://msdn.microsoft.com/library/windows/hardware/hh463913)
+
+
+
[RtlIntSub](https://msdn.microsoft.com/library/windows/hardware/hh451318)
+
+
+
[RtlLongLongSub](https://msdn.microsoft.com/library/windows/hardware/hh451373)
+
+
+
[RtlIntPtrSub](https://msdn.microsoft.com/library/windows/hardware/hh451223)
+
+
+
[RtlLongPtrSub](https://msdn.microsoft.com/library/windows/hardware/hh451436)
+
+
+

Subtraction Functions

+
+
[RtlUShortToShort](https://msdn.microsoft.com/library/windows/hardware/hh451548)
+
+
+
[RtlLongPtrToShort](https://msdn.microsoft.com/library/windows/hardware/hh406733)
+
+
+
[RtlLongToShort](https://msdn.microsoft.com/library/windows/hardware/hh463929)
+
+
+
[RtlLongLongToShort](https://msdn.microsoft.com/library/windows/hardware/hh451395)
+
+
+
[RtlULongLongToShort](https://msdn.microsoft.com/library/windows/hardware/hh451471)
+
+
+
[RtlULongToShort](https://msdn.microsoft.com/library/windows/hardware/hh451534)
+
+
+
[RtlUIntPtrToShort](https://msdn.microsoft.com/library/windows/hardware/hh464105)
+
+
+
[RtlULongPtrToShort](https://msdn.microsoft.com/library/windows/hardware/hh451507)
+
+
+
[RtlUIntToShort](https://msdn.microsoft.com/library/windows/hardware/hh451453)
+
+
+
[RtlIntPtrToShort](https://msdn.microsoft.com/library/windows/hardware/hh451274)
+
+
+
[RtlIntToShort](https://msdn.microsoft.com/library/windows/hardware/hh451329)
+
+
+

Conversion to Short

+
+
[RtlLongPtrToChar](https://msdn.microsoft.com/library/windows/hardware/hh451441)
+
+
+
[RtlLongLongToChar](https://msdn.microsoft.com/library/windows/hardware/hh451377)
+
+
+
[RtlUInt8ToChar](https://msdn.microsoft.com/library/windows/hardware/hh464061)
+
+
+
[RtlULongToChar](https://msdn.microsoft.com/library/windows/hardware/hh451525)
+
+
+
[RtlLongToChar](https://msdn.microsoft.com/library/windows/hardware/hh463917)
+
+
+
[RtlULongLongToChar](https://msdn.microsoft.com/library/windows/hardware/hh451462)
+
+
+
[RtlUIntToChar](https://msdn.microsoft.com/library/windows/hardware/hh464122)
+
+
+
[RtlIntToChar](https://msdn.microsoft.com/library/windows/hardware/hh451322)
+
+
+
[RtlIntPtrToChar](https://msdn.microsoft.com/library/windows/hardware/hh451229)
+
+
+
[RtlULongPtrToChar](https://msdn.microsoft.com/library/windows/hardware/hh451496)
+
+
+
[RtlShortToChar](https://msdn.microsoft.com/library/windows/hardware/hh463995)
+
+
+
[RtlUShortToChar](https://msdn.microsoft.com/library/windows/hardware/hh451546)
+
+
+
[RtlByteToChar](https://msdn.microsoft.com/library/windows/hardware/hh439690)
+
+
+
[RtlUIntPtrToChar](https://msdn.microsoft.com/library/windows/hardware/hh464081)
+
+
+

Conversion to Char

+
+
[RtlIntPtrToInt](https://msdn.microsoft.com/library/windows/hardware/hh451233)
+
+
+
[RtlLongLongToInt](https://msdn.microsoft.com/library/windows/hardware/hh451381)
+
+
+
[RtlLongPtrToInt](https://msdn.microsoft.com/library/windows/hardware/hh451446)
+
+
+
[RtlULongLongToInt](https://msdn.microsoft.com/library/windows/hardware/hh451463)
+
+
+
[RtlULongPtrToInt](https://msdn.microsoft.com/library/windows/hardware/hh451498)
+
+
+
[RtlLongToInt](https://msdn.microsoft.com/library/windows/hardware/hh463920)
+
+
+
[RtlULongToInt](https://msdn.microsoft.com/library/windows/hardware/hh451528)
+
+
+
[RtlUIntToInt](https://msdn.microsoft.com/library/windows/hardware/hh464123)
+
+
+
[RtlUIntPtrToInt](https://msdn.microsoft.com/library/windows/hardware/hh464085)
+
+
+

Conversion to Int

+
+
[RtlUInt8ToInt8](https://msdn.microsoft.com/library/windows/hardware/hh464064)
+
+
+
[RtlLongLongToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451384)
+
+
+
[RtlLongPtrToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451450)
+
+
+
[RtlULongPtrToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451500)
+
+
+
[RtlLongToInt8](https://msdn.microsoft.com/library/windows/hardware/hh463923)
+
+
+
[RtlULongLongToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451464)
+
+
+
[RtlULongToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451529)
+
+
+
[RtlIntToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451326)
+
+
+
[RtlIntPtrToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451241)
+
+
+
[RtlUIntToInt8](https://msdn.microsoft.com/library/windows/hardware/hh464124)
+
+
+
[RtlByteToInt8](https://msdn.microsoft.com/library/windows/hardware/hh439696)
+
+
+
[RtlUIntPtrToInt8](https://msdn.microsoft.com/library/windows/hardware/hh464093)
+
+
+
[RtlUShortToInt8](https://msdn.microsoft.com/library/windows/hardware/hh451547)
+
+
+
[RtlShortToInt8](https://msdn.microsoft.com/library/windows/hardware/hh464006)
+
+
+

Conversion to Int8

+
+
[RtlUIntPtrToInt16](https://msdn.microsoft.com/library/windows/hardware/hh464090)
+
+
+

Conversion to Int16

+
+
[RtlLongLongToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451387)
+
+
+
[RtlLongPtrToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh406726)
+
+
+
[RtlLongToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh463926)
+
+
+
[RtlULongToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451531)
+
+
+
[RtlULongPtrToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451502)
+
+
+
[RtlUIntPtrToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh464098)
+
+
+
[RtlUIntToIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh464125)
+
+
+

Conversion to IntPtr

+
+
[RtlULongToLong](https://msdn.microsoft.com/library/windows/hardware/hh451532)
+
+
+
[RtlIntPtrToLong](https://msdn.microsoft.com/library/windows/hardware/hh451246)
+
+
+
[RtlLongLongToLong](https://msdn.microsoft.com/library/windows/hardware/hh451389)
+
+
+
[RtlUIntPtrToLong](https://msdn.microsoft.com/library/windows/hardware/hh464100)
+
+
+
[RtlLongPtrToLong](https://msdn.microsoft.com/library/windows/hardware/hh406730)
+
+
+
[RtlUIntToLong](https://msdn.microsoft.com/library/windows/hardware/hh451451)
+
+
+
[RtlULongLongToLong](https://msdn.microsoft.com/library/windows/hardware/hh451466)
+
+
+
[RtlULongPtrToLong](https://msdn.microsoft.com/library/windows/hardware/hh451504)
+
+
+

Conversion to Long

+
+
[RtlIntPtrToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451249)
+
+
+
[RtlULongToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451533)
+
+
+
[RtlLongLongToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451393)
+
+
+
[RtlUIntPtrToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh464104)
+
+
+
[RtlULongLongToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451470)
+
+
+
[RtlUIntToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451452)
+
+
+
[RtlULongPtrToLongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451506)
+
+
+

Conversion to LongPtr

+
+
[RtlULongLongToLongLong](https://msdn.microsoft.com/library/windows/hardware/hh451468)
+
+
+
[RtlULongPtrToLongLong](https://msdn.microsoft.com/library/windows/hardware/hh451505)
+
+
+
[RtlUIntPtrToLongLong](https://msdn.microsoft.com/library/windows/hardware/hh464101)
+
+
+

Conversion to LongLong

+
+
[RtlIntPtrToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451313)
+
+
+
[RtlInt8ToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451195)
+
+
+
[RtlULongToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451539)
+
+
+
[RtlIntToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451357)
+
+
+
[RtlLongLongToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451420)
+
+
+
[RtlLongPtrToUShort](https://msdn.microsoft.com/library/windows/hardware/hh463910)
+
+
+
[RtlLongToUShort](https://msdn.microsoft.com/library/windows/hardware/hh463959)
+
+
+
[RtlShortToUShort](https://msdn.microsoft.com/library/windows/hardware/hh464039)
+
+
+
[RtlUIntPtrToUShort](https://msdn.microsoft.com/library/windows/hardware/hh464114)
+
+
+
[RtlUIntToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451457)
+
+
+
[RtlULongLongToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451488)
+
+
+
[RtlULongPtrToUShort](https://msdn.microsoft.com/library/windows/hardware/hh451519)
+
+
+

Conversion to UShort

+
+
[RtlUShortToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451549)
+
+
+
[RtlInt8ToUChar](https://msdn.microsoft.com/library/windows/hardware/hh439736)
+
+
+
[RtlIntPtrToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451278)
+
+
+
[RtlIntToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451334)
+
+
+
[RtlLongLongToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451400)
+
+
+
[RtlLongPtrToUChar](https://msdn.microsoft.com/library/windows/hardware/hh463882)
+
+
+
[RtlLongToUChar](https://msdn.microsoft.com/library/windows/hardware/hh463932)
+
+
+
[RtlShortToUChar](https://msdn.microsoft.com/library/windows/hardware/hh464011)
+
+
+
[RtlUIntPtrToUChar](https://msdn.microsoft.com/library/windows/hardware/hh464106)
+
+
+
[RtlUIntToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451454)
+
+
+
[RtlULongLongToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451473)
+
+
+
[RtlULongPtrToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451508)
+
+
+
[RtlULongToUChar](https://msdn.microsoft.com/library/windows/hardware/hh451535)
+
+
+

Conversion to UChar

+
+
[RtlInt8ToUInt](https://msdn.microsoft.com/library/windows/hardware/hh439742)
+
+
+
[RtlULongToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451536)
+
+
+
[RtlLongLongToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451404)
+
+
+
[RtlIntPtrToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451282)
+
+
+
[RtlShortToUInt](https://msdn.microsoft.com/library/windows/hardware/hh464014)
+
+
+
[RtlLongPtrToUInt](https://msdn.microsoft.com/library/windows/hardware/hh463887)
+
+
+
[RtlLongToUInt](https://msdn.microsoft.com/library/windows/hardware/hh463935)
+
+
+
[RtlUIntPtrToUInt](https://msdn.microsoft.com/library/windows/hardware/hh464107)
+
+
+
[RtlIntToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451338)
+
+
+
[RtlULongLongToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451475)
+
+
+
[RtlULongPtrToUInt](https://msdn.microsoft.com/library/windows/hardware/hh451510)
+
+
+

Conversion to Uint

+
+
[RtlUShortToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451551)
+
+
+
[RtlInt8ToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh439747)
+
+
+
[RtlLongLongToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451408)
+
+
+
[RtlIntToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451342)
+
+
+
[RtlIntPtrToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451287)
+
+
+
[RtlLongPtrToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh463892)
+
+
+
[RtlShortToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh464018)
+
+
+
[RtlLongToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh463939)
+
+
+
[RtlUIntPtrToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh464110)
+
+
+
[RtlUIntToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451456)
+
+
+
[RtlULongLongToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451477)
+
+
+
[RtlULongPtrToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451512)
+
+
+
[RtlULongToUInt8](https://msdn.microsoft.com/library/windows/hardware/hh451537)
+
+
+

Conversion to Uint8

+
+
[RtlUIntPtrToUInt16](https://msdn.microsoft.com/library/windows/hardware/hh464090)
+
+
+

Conversion to Uint16

+
+
[RtlULongToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451538)
+
+
+
[RtlLongToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh463941)
+
+
+
[RtlShortToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh464022)
+
+
+
[RtlInt8ToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh439752)
+
+
+
[RtlIntPtrToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451293)
+
+
+
[RtlLongPtrToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh463896)
+
+
+
[RtlULongLongToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451479)
+
+
+
[RtlULongPtrToUIntPtr](https://msdn.microsoft.com/library/windows/hardware/hh451514)
+
+
+

Conversion to UintPtr

+
+
[RtlULongPtrToULong](https://msdn.microsoft.com/library/windows/hardware/hh451516)
+
+
+
[RtlInt8ToULong](https://msdn.microsoft.com/library/windows/hardware/hh439758)
+
+
+
[RtlIntPtrToULong](https://msdn.microsoft.com/library/windows/hardware/hh451298)
+
+
+
[RtlIntToULong](https://msdn.microsoft.com/library/windows/hardware/hh451347)
+
+
+
[RtlLongLongToULong](https://msdn.microsoft.com/library/windows/hardware/hh451412)
+
+
+
[RtlLongPtrToULong](https://msdn.microsoft.com/library/windows/hardware/hh463900)
+
+
+
[RtlLongToULong](https://msdn.microsoft.com/library/windows/hardware/hh463945)
+
+
+
[RtlShortToULong](https://msdn.microsoft.com/library/windows/hardware/hh464027)
+
+
+
[RtlUIntPtrToULong](https://msdn.microsoft.com/library/windows/hardware/hh464112)
+
+
+
[RtlULongLongToULong](https://msdn.microsoft.com/library/windows/hardware/hh451482)
+
+
+

Conversion to ULong

+
+
[RtlShortToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh464031)
+
+
+
[RtlInt8ToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh439763)
+
+
+
[RtlIntToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh451352)
+
+
+
[RtlLongLongToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh451416)
+
+
+
[RtlIntPtrToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh451304)
+
+
+
[RtlLongPtrToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh463904)
+
+
+
[RtlLongToULongLong](https://msdn.microsoft.com/library/windows/hardware/hh463949)
+
+
+

Conversion to ULongLong

+
+
[RtlULongLongToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451485)
+
+
+
[RtlIntPtrToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh451308)
+
+
+
[RtlLongPtrToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh463907)
+
+
+
[RtlInt8ToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh439769)
+
+
+
[RtlLongToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh463953)
+
+
+
[RtlShortToULongPtr](https://msdn.microsoft.com/library/windows/hardware/hh464035)
+
+
+

Conversion to ULongPtr

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Summary%20of%20Kernel-Mode%20Safe%20Integer%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/support-for-power-management.md b/windows-driver-docs-pr/kernel/support-for-power-management.md new file mode 100644 index 0000000000..79ba917af5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/support-for-power-management.md @@ -0,0 +1,40 @@ +--- +title: Support for Power Management +author: windows-driver-content +description: Support for Power Management +ms.assetid: 77e8be50-9623-4085-8d38-44db676a9a1f +keywords: ["power management WDK kernel , support requirements", "power management WDK kernel , about power management", "PnP WDK power management", "Plug and Play WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Support for Power Management + + +## + + +To support power management, drivers must also support [Plug and Play](implementing-plug-and-play.md) (PnP). Driver support for PnP is required because many power management operations are associated with installing and removing devices, and the PnP manager notifies drivers of these events by means of PnP IRPs. Additionally, drivers report device support for power management in response to PnP queries for device capabilities. + +Power management works on two levels: one applies to individual devices and the other to the system as a whole. + +The power manager, part of the operating system kernel, manages the power level of the entire system. If all drivers in the system support power management, the power manager can manage power consumption on a system-wide basis, utilizing not only the fully on and fully off states, but also various intermediate system sleep states. + +Legacy drivers that were written before the operating system supported power management continue to work as they did previously. However, systems that include legacy drivers cannot enter any of the intermediate system sleep states; they can operate only in the fully on or fully off states as before. + +Device power management applies to individual devices. A driver that supports power management can turn its device on when it is needed and off when it is not in use. Devices that have the hardware capability can enter intermediate device power states. The presence of legacy drivers in the system does not affect the ability of newer drivers to manage power for their devices. + +Beginning with Windows Vista, the operating system also supports driver performance states. Drivers that support device performance states can choose to tradeoff performance or features with a reduction in power consumption. Windows Vista provides a framework for devices to retrieve their power settings and information about the system power state. This mechanism is extendable, allowing driver vendors to define and install new custom power settings for their device. For more information, see [System Power Policy](system-power-policy.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Support%20for%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-32-bit-i-o-in-your-64-bit-driver.md b/windows-driver-docs-pr/kernel/supporting-32-bit-i-o-in-your-64-bit-driver.md new file mode 100644 index 0000000000..31ab6afe9b --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-32-bit-i-o-in-your-64-bit-driver.md @@ -0,0 +1,44 @@ +--- +title: Supporting 32-Bit I/O in Your 64-Bit Driver +author: windows-driver-content +description: Supporting 32-Bit I/O in Your 64-Bit Driver +ms.assetid: c024c74e-0b83-4f86-8370-8269cbf69c9a +keywords: ["32-bit I/O support WDK 64-bit", "64-bit WDK kernel , 32-bit I/O support", "thunking WDK", "WOW64 thunking layer WDK", "converting parameters to fixed-precision types", "32-bit I/O support WDK 64-bit , about 32-bit I/O support in 64-bit", "control codes WDK 64-bit", "I/O control codes WDK kernel , 32-bit I/O in 64-bit drivers", "IOCTLs WDK kernel , 32-bit I/O in 64-bit drivers", "file system control codes WDK 64-bit", "FSCTL WDK 64-bit", "buffer pointers WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting 32-Bit I/O in Your 64-Bit Driver + + +## + + +Windows on Windows (WOW64) enables Microsoft Win32 user-mode applications to run on 64-bit Windows. It does this by intercepting Win32 function calls and converting parameters from pointer-precision types to fixed-precision types as appropriate before making the transition to the 64-bit kernel. This conversion, which is called *thunking*, is done automatically for all Win32 functions, with one important exception: the data buffers passed to [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216). The contents of these buffers, which are pointed to by the *InputBuffer* and *OutputBuffer* parameters, are not thunked, because their structure is driver-specific. + +**Note**   Although the buffer *contents* are not thunked, the buffer *pointers* are converted into 64-bit pointers. + +  + +User-mode applications call [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) to send an I/O request directly to a specified kernel-mode driver. This request contains an I/O control code (IOCTL) or file system control code (FSCTL) and pointers to input and output data buffers. The format of these data buffers is specific to the IOCTL or FSCTL, which in turn is defined by the kernel-mode driver. Because the buffer format is arbitrary, and because it is known to the driver and not WOW64, the task of thunking the data is left to the driver. + +Your 64-bit driver must support 32-bit I/O if all of the following are true: + +- The driver exposes an IOCTL (or FSCTL) to user-mode applications. + +- At least one of the I/O buffers used by the IOCTL contains pointer-precision data types. + +- Your IOCTL code cannot easily be rewritten to eliminate the use of pointer-precision buffer data types. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%2032-Bit%20I/O%20in%20Your%2064-Bit%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-asynchronous-i-o.md b/windows-driver-docs-pr/kernel/supporting-asynchronous-i-o.md new file mode 100644 index 0000000000..0cb871a2ee --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-asynchronous-i-o.md @@ -0,0 +1,40 @@ +--- +title: Supporting Asynchronous I/O +author: windows-driver-content +description: Supporting Asynchronous I/O +ms.assetid: b4baf1a9-6156-4bbf-b4d9-7205924c637f +keywords: ["asynchronous I/O WDK kernel", "I/O WDK kernel , asynchronous mode", "status information WDK I/O requests"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting Asynchronous I/O + + +## + + +The I/O manager provides asynchronous I/O support so that the originator of an I/O request (usually a user-mode application but sometimes another driver) can continue executing, rather than wait for its I/O request to be completed. Asynchronous I/O support improves both the overall system throughput and the performance of any code that makes an I/O request. + +With asynchronous I/O support, kernel-mode drivers do not necessarily process I/O requests in the same order in which they were sent to the I/O manager. The I/O manager, or a higher-level driver, can reorder I/O requests as they are received. A driver can split a large data transfer request into smaller transfer requests. Moreover, a driver can overlap I/O request processing, particularly in a symmetric multiprocessor platform, as mentioned in [Multiprocessor-Safe](multiprocessor-safe.md). + +Furthermore, a kernel-mode driver's processing of an individual I/O request is not necessarily serialized. That is, a driver does not necessarily process each IRP to completion before it starts processing the next incoming I/O request. + +When a driver receives an IRP, it responds by carrying out as much IRP-specific processing as it can. If the driver supports asynchronous IRP processing, it can send an IRP to the next driver, if necessary, and begin processing the next IRP without waiting for the first one to be completed. The driver can register a "completion routine," which the I/O manager calls when another driver has finished processing an IRP. Drivers provide a status value in the IRP's I/O status block, which other drivers can access to determine the status of an I/O request. + +Drivers can maintain state information about their current I/O operations in a special part of their device objects, called a [device extension](device-extensions.md). + +For more information, see [Handling IRPs](handling-irps.md) and [Input/Output Techniques](i-o-programming-techniques.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20Asynchronous%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-d3cold-in-a-driver.md b/windows-driver-docs-pr/kernel/supporting-d3cold-in-a-driver.md new file mode 100644 index 0000000000..98007dc0d3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-d3cold-in-a-driver.md @@ -0,0 +1,71 @@ +--- +title: Supporting D3cold in a Driver +author: windows-driver-content +description: Starting with Windows 8, the D3 (off) device power state is divided into two distinct substates, D3hot and D3cold. +ms.assetid: D085820E-EDAC-4353-8500-207F77D9CC1F +--- + +# Supporting D3cold in a Driver + + +Starting with Windows 8, the D3 (off) device power state is divided into two distinct substates, D3hot and D3cold. D3 is the lowest-powered device power state, and D3cold is the lowest-powered substate of D3. Moving idle devices to the D3cold substate can reduce power consumption and extend the time that a mobile hardware platform can run on a battery charge. + +In D3hot, the device is mostly turned off. However, the device is not disconnected from its main power source, and the parent bus controller can detect the presence of the device on the bus. In D3cold, the main power source is removed from the device, and the bus controller cannot detect the presence of the device. For more information, see the descriptions of D3hot and D3cold in [Device Low-Power States](device-sleeping-states.md). + +In earlier versions of Windows, the D3 device power state is implicitly divided into D3hot and D3cold substates, but a device cannot enter D3cold unless the computer is preparing to exit the S0 system power state and enter one of the sleeping states, S1 through S4. The low-power Dx states that a device can enter when the computer is to remain in S0 are limited to D1 through D3hot. + +Windows 8 is the first version of Windows to support device-power-state transitions to the D3cold substate when the computer is in S0 and is not preparing to enter a sleeping state. A device that supports D3cold in this way helps to save power in the following ways: + +- The device consumes less power in D3cold than in any other low-power Dx state. +- If this device shares a bus with other devices, and all these devices support D3cold, then after all the devices on the bus enter D3cold, the bus controller can enter a low-power Dx state. +- If this device shares a power source with other devices, and all these devices support D3cold, then when the last of these devices enters D3hot, the power source can be removed, at which time these devices all enter D3cold in unison. + +Conversely, a device that cannot idle in D3cold can prevent other devices from entering D3cold or other low-power Dx states. + +The following topics contain more information about supporting D3cold in a device driver. + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[Enabling Transitions to D3cold](enabling-transitions-to-d3cold.md)

All versions of Windows enable a device to be in D3cold while the computer is sleeping (in one of the system low-power states, S1 through S4). Before the computer exits S0, the function drivers, bus drivers, and filter drivers work together to move the device to D3hot. When the computer enters the low-power Sx state, this transition has the side effect of moving the device from D3hot to D3cold.

[D3cold Capabilities of a Device](d3cold-capabilities-of-a-device.md)

Before the driver that is the power policy owner (PPO) for a device enables the device to enter D3cold (when the computer is to remain in S0), the driver must verify that the device will be responsive and continue to operate correctly after the device enters D3cold.

[Using the GUID_D3COLD_SUPPORT_INTERFACE Driver Interface](using-guid-d3cold-support-interface.md)

Starting with Windows 8, drivers can call the routines in the [GUID_D3COLD_SUPPORT_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) interface to determine the D3cold capabilities of devices and to enable these devices to use D3cold. The two primary routines in this interface are [SetD3ColdSupport](https://msdn.microsoft.com/library/windows/hardware/hh967716) and [GetIdleWakeInfo](https://msdn.microsoft.com/library/windows/hardware/hh967712).

[Surprise Wake-Up](surprise-wake-up.md)

A surprise wake-up is an unexpected transition to D0. After a device enters D3cold, it might experience a surprise wake-up as a side effect when the driver for another device on the same power rail requests a transition from D3cold to D0. The driver for the first device must receive notification of the surprise wake-up to prevent the device from remaining in an uninitialized D0 state.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20D3cold%20in%20a%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-devices-that-have-wake-up-capabilities.md b/windows-driver-docs-pr/kernel/supporting-devices-that-have-wake-up-capabilities.md new file mode 100644 index 0000000000..4610ec5e72 --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-devices-that-have-wake-up-capabilities.md @@ -0,0 +1,40 @@ +--- +title: Supporting Devices that Have Wake-Up Capabilities +author: windows-driver-content +description: Supporting Devices that Have Wake-Up Capabilities +ms.assetid: 70b9d0af-c3d7-44dc-b11a-3274391508c5 +keywords: ["power management WDK kernel , wake-up capabilities", "external wake signals WDK", "awakening devices", "wake-up capabilities WDK power management", "device wake ups WDK power management", "IRP_MN_WAIT_WAKE", "restoring power WDK kernel", "IRPs WDK power management", "wait/wake IRPs WDK power management", "I/O request packets WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting Devices that Have Wake-Up Capabilities + + +## + + +Drivers for devices that can respond to external wake signals must be able to handle [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) requests (*wait/wake IRPs*). The power policy owner for such a device must be able to send an **IRP\_MN\_WAIT\_WAKE** request. + +Typically, whatever causes the device to assert the wake signal is also a normal service event for the device. For example, user input, which might cause a keyboard to wake up the system, is a normal event for the keyboard and its drivers. + +The first topic of this section, [Overview of Wait/Wake Operation](overview-of-wait-wake-operation.md), contains information useful in writing any driver. The following additional topics provide detailed information about handling and sending wait/wake IRPs: + +[Receiving a Wait/Wake IRP](receiving-a-wait-wake-irp.md) + +[Sending a Wait/Wake IRP](sending-a-wait-wake-irp.md) + +[Canceling a Wait/Wake IRP](canceling-a-wait-wake-irp.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20Devices%20that%20Have%20Wake-Up%20Capabilities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-layered-registry-filtering-drivers.md b/windows-driver-docs-pr/kernel/supporting-layered-registry-filtering-drivers.md new file mode 100644 index 0000000000..50bbcf678d --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-layered-registry-filtering-drivers.md @@ -0,0 +1,31 @@ +--- +title: Supporting Layered Registry Filtering Drivers +author: windows-driver-content +description: Supporting Layered Registry Filtering Drivers +ms.assetid: 5adeecdb-c26e-4502-87b4-bfb02a4aaba8 +keywords: ["filtering registry calls WDK kernel , layered", "registry filtering drivers WDK kernel , layered", "layered registry filtering drivers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting Layered Registry Filtering Drivers + + +Windows Vista and later operating system versions support a layered stack of registry filtering drivers. Each driver in the stack can participate in filtering registry operations by registering a [*RegistryCallback*](https://msdn.microsoft.com/library/windows/hardware/ff560903) routine. Each registry filtering driver is assigned an *altitude*, and drivers can register only one *RegistryCallback* routine for each altitude. When your driver calls [**CmRegisterCallbackEx**](https://msdn.microsoft.com/library/windows/hardware/ff541921), the driver specifies its altitude. For more information about altitudes, see [Load Order Groups and Altitudes for Minifilter Drivers](https://msdn.microsoft.com/library/windows/hardware/ff549689). + +When a thread makes a registry call, the configuration manager calls each *RegistryCallback* routine, in order, from the highest altitude to the lowest, until all drivers have been called or a *RegistryCallback* routine returns a status value for which [NT\_SUCCESS](using-ntstatus-values.md)(*status*) equals **FALSE**. Therefore, if a higher-level driver blocks or modifies a registry operation, the lower-level drivers are not called. (If a driver modifies an operation by calling a different registry function, the configuration manager does not restart at the top of the filter stack.) + +Registry filtering drivers that were written before Windows Vista and therefore do not have an altitude assignment are inserted near the top of the Windows Vista filter stack, in the order that they call [**CmRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff541918). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20Layered%20Registry%20Filtering%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-removable-media.md b/windows-driver-docs-pr/kernel/supporting-removable-media.md new file mode 100644 index 0000000000..b8f508e5d9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-removable-media.md @@ -0,0 +1,40 @@ +--- +title: Supporting Removable Media +author: windows-driver-content +description: Supporting Removable Media +ms.assetid: f70c404c-8a38-4f53-8681-6efb52b30656 +keywords: ["removable media WDK kernel", "removable media WDK kernel , about removable-media devices", "IRPs WDK kernel , removable media", "kernel-mode drivers WDK , removable media"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting Removable Media + + +## + + +File systems and removable-media device drivers share the responsibility for ensuring that the correct media is mounted when a file is opened on a removable-media device and that the correct media remains mounted during operations that access the media. Any intermediate driver layered between a file system and a removable-media device driver also shares this responsibility. + +Drivers that work with removable-media devices therefore should be capable of doing one or more of the following: + +[Responding to check-verify requests from the file system](responding-to-check-verify-requests-from-the-file-system.md) + +[Notifying the file system of possible media changes](notifying-the-file-system-of-possible-media-changes.md) + +[Checking flags in the device object](checking-flags-in-the-device-object.md) + +[Setting up IRPs in intermediate drivers](setting-up-irps-in-intermediate-drivers.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20Removable%20Media%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/supporting-standard-wmi-blocks.md b/windows-driver-docs-pr/kernel/supporting-standard-wmi-blocks.md new file mode 100644 index 0000000000..43fb4312ef --- /dev/null +++ b/windows-driver-docs-pr/kernel/supporting-standard-wmi-blocks.md @@ -0,0 +1,40 @@ +--- +title: Supporting Standard WMI Blocks +author: windows-driver-content +description: Supporting Standard WMI Blocks +ms.assetid: ddec3afb-8274-4eff-93ef-b0a07fd7c13a +keywords: ["WMI WDK kernel , event blocks", "event blocks WDK WMI", "data blocks WDK WMI", "WMI WDK kernel , data blocks", "blocks WDK WMI", "standard blocks WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Supporting Standard WMI Blocks + + +## + + +Each driver should support any *standard blocks* defined for drivers of its type. Standard blocks provide WMI clients with consistent data for all devices of a given type, regardless of vendor. + +To support a standard block, a driver: + +- Registers the block with WMI, along with the other standard and custom blocks supported by the driver, as described in [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +- Handles all WMI requests that specify the driver's device object pointer at **Parameters.WMI.ProviderId** and the GUID of the standard block at **Parameters.WMI.DataPath**, as described in [Handling WMI Requests](handling-wmi-requests.md). + +MOF classes for standard blocks are published in system-supplied MOF files. A driver must not redefine a standard block in its own MOF file, because doing so would duplicate the block in the WMI database. + +Currently, class definitions of standard blocks are published in the file wmicore.mof, which is included in the Windows Driver Kit (WDK). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Supporting%20Standard%20WMI%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/surprise-wake-up.md b/windows-driver-docs-pr/kernel/surprise-wake-up.md new file mode 100644 index 0000000000..48d89e2684 --- /dev/null +++ b/windows-driver-docs-pr/kernel/surprise-wake-up.md @@ -0,0 +1,42 @@ +--- +title: Surprise Wake-Up +author: windows-driver-content +description: A surprise wake-up is an unexpected transition to D0. +ms.assetid: 07D3EC05-A1C9-40C5-90FC-E25B5A66B064 +--- + +# Surprise Wake-Up + + +A surprise wake-up is an unexpected transition to D0. After a device enters D3cold, it might experience a surprise wake-up as a side effect when the driver for another device on the same power rail requests a transition from D3cold to D0. The driver for the first device must receive notification of the surprise wake-up to prevent the device from remaining in an uninitialized D0 state. + +When a device moves from D3hot to D3cold, it probably does so because the power source that it shares with some number of other devices was turned off. Some time after these devices enter D3cold, the driver for one of the devices might request a transition to D0. In response to this request, the parent bus driver or ACPI filter driver turns on the power source, and all the devices that share the power source enter their default, power-on hardware states. + +The only device driver that expects this power state change is the driver that requested the change. The drivers for the other devices must receive notification of this change so that they can properly initialize their devices to operate in D0. Only a driver that can receive this notification should enable its device to enter D3cold. Otherwise, the driver will not know when the device enters D0. + +When a device is turned on, it enters a default, uninitialized hardware state. For example, the [PCI Express Base 3.0 Specification](http://www.pcisig.com/specifications/pciexpress/specifications/) defines a *D0 uninitialized* state that a device enters when it first receives power. The definition of this state is specific to PCI and PCI Express devices, but devices that connect to other buses are designed to enter similar hardware states when they are turned on. + +In the case of a PCI or PCI Express device that implements multiple functions, these device functions probably share the same power rail. However, each function might have a separate driver and the drivers for these functions are unlikely to communicate directly with each other. When the driver for one of these functions requests a power state change from D3cold to D0, the drivers for the other functions do not expect this change. When these other functions receive power, their drivers must be notified so that they can configure the functions to operate correctly in D0. + +A bus driver detects when power to a child device is being turned on. If this device's function driver did not request a transition to D0, the bus driver prompts the device driver to send itself a D0 power IRP (an [**IRP\_MN\_SET\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff551744) request with target state = **PowerDeviceD0**) to initialize the device to operate in D0. From this initialized D0 state, the device driver can then initiate the device's transition to D3hot. Device drivers can receive notifications of surprise transitions to D0 from bus drivers in the following ways: + +- Device drivers that directly or indirectly register themselves as clients of the [run-time power management framework](overview-of-the-power-management-framework.md) (PoFx) receive notification callbacks. +- Drivers for devices that arm their devices for wake have their pending [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) requests completed by the bus drivers. + +Starting with Windows 8, a device's function driver, acting as the power policy owner, can register itself as a client of PoFx. When the bus driver notifies PoFx that the device experienced a surprise transition to D0, PoFx helps the device to move to an initialized D0 state, and then to D3hot. First, PoFx calls the driver's [*DevicePowerRequiredCallback*](https://msdn.microsoft.com/library/windows/hardware/hh450949) routine to prompt the device driver to send a D0 power IRP down the device stack. Next, PoFx calls the driver's [*DevicePowerNotRequiredCallback*](https://msdn.microsoft.com/library/windows/hardware/hh450946) routine to notify the device driver that the device is not required to stay in the D0 state. + +Starting with Kernel-Mode Driver Framework (KMDF) version 1.11, the KMDF driver for a single-component device can indirectly register itself with PoFx by calling the [**WdfDeviceWdmAssignPowerFrameworkSettings**](https://msdn.microsoft.com/library/windows/hardware/hh451097) method. In this call, the driver supplies pointers to callback routines that notify the driver of surprise transitions to D0. For more information, see [Supporting Functional Power States](https://msdn.microsoft.com/library/windows/hardware/hh451017). + +A driver that does not register its device with PoFx can still be notified of a surprise transition to D0 if the device is armed for wake. When the bus drivers turn on the power to the device, they complete the driver's **IRP\_MN\_WAIT\_WAKE** request. In response, the driver initializes its device to operate in D0. The device is likely to be idle, in which case the driver, after some time, will move this device to D3hot. + +A function driver that does not register with PoFx and that does not arm its device for wake receives no notification of a surprise transition from D3cold to D0. The device might spend large amounts of time in an uninitialized D0 state. In this state, all of the components in the device are typically turned on. To reduce power consumption by idle devices, drivers should enable entry to D3cold only if they can receive notifications of surprise transitions to D0. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Surprise%20Wake-Up%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronization-and-threaded-dpcs.md b/windows-driver-docs-pr/kernel/synchronization-and-threaded-dpcs.md new file mode 100644 index 0000000000..792673f397 --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronization-and-threaded-dpcs.md @@ -0,0 +1,46 @@ +--- +title: Synchronization and Threaded DPCs +author: windows-driver-content +description: Synchronization and Threaded DPCs +ms.assetid: b4f2c77b-226c-4229-bcbb-5eebabdc28a4 +keywords: ["threaded DPCs WDK kernel", "synchronization WDK kernel , interrupts", "queued spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronization and Threaded DPCs + + +## + + +To synchronize access to a memory location that is accessed from both inside and outside a [*CustomThreadedDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542976) routine, a driver can use ordinary spin locks or queued spin locks. When doing so, the driver must obey certain rules to correctly synchronize at IRQL= PASSIVE\_LEVEL and at IRQL = DISPATCH\_LEVEL, because a *CustomThreadedDpc* routine can execute at both IRQLs. + +For an ordinary spin lock, the following rules apply: + +- To acquire and release the spin lock, the driver can call [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) and [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145) from both inside and outside the *CustomThreadedDpc* routine. + +- The driver can call [**KeAcquireSpinLockForDpc**](https://msdn.microsoft.com/library/windows/hardware/ff551923) and [**KeReleaseSpinLockForDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553148) from inside the *CustomThreadedDpc* routine. Note that the *CustomThreadedDpc* routine must not call [**KeAcquireSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551921) or [**KeReleaseSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553150), because these routines can safely be called only at IRQL = DISPATCH\_LEVEL. + +The rules for queued spin locks are similar: + +- To acquire and release the spin lock, the driver can call [**KeAcquireInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551899) and [**KeReleaseInStackQueuedSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553130) from both inside and outside the *CustomThreadedDpc* routine. + +- The driver can call [**KeAcquireInStackQueuedSpinLockForDpc**](https://msdn.microsoft.com/library/windows/hardware/ff551912) and [**KeReleaseInStackQueuedSpinLockForDpc**](https://msdn.microsoft.com/library/windows/hardware/ff553133) from inside the *CustomThreadedDpc* routine. Note that the *CustomThreadedDpc* routine must not call [**KeAcquireInStackQueuedSpinLockAtDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff551908) or [**KeReleaseInStackQueuedSpinLockFromDpcLevel**](https://msdn.microsoft.com/library/windows/hardware/ff553137), because these routines can safely be called only at IRQL = DISPATCH\_LEVEL. + +Because **KeAcquireSpinLockForDpc** and **KeAcquireInStackQueuedSpinLockForDpc** do not reset the IRQL when called at DISPATCH\_LEVEL, they execute faster than **KeAcquireSpinLock** and **KeAcquireInStackQueuedSpinLock**, respectively. + +For more information about spin locks, see [Spin Locks](spin-locks.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronization%20and%20Threaded%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronization-techniques.md b/windows-driver-docs-pr/kernel/synchronization-techniques.md new file mode 100644 index 0000000000..240b8d08bb --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronization-techniques.md @@ -0,0 +1,48 @@ +--- +title: Synchronization Techniques +author: windows-driver-content +description: Synchronization Techniques +ms.assetid: dfee2240-44df-43bc-8804-271203480664 +keywords: ["synchronization WDK kernel", "kernel-mode drivers WDK , synchronization", "thread synchronization WDK kernel", "simultaneous access protection WDK kernel", "data integrity WDK kernel", "integrity WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronization Techniques + + +## + + +This section provides information about the techniques you can use to synchronize driver activities in a multiprocessor-safe manner. The following topics are discussed: + +[Kernel Dispatcher Objects](kernel-dispatcher-objects.md) + +[Callback Objects](callback-objects.md) + +[Spin Locks](spin-locks.md) + +[Fast Mutexes and Guarded Mutexes](fast-mutexes-and-guarded-mutexes.md) + +[ERESOURCE Structures](eresource-structures.md) + +[Additional Timers and Counters](additional-timers-and-counters.md) + +[Asynchronous Procedure Calls](asynchronous-procedure-calls.md) + +[Acquire and Release Semantics](acquire-and-release-semantics.md) + +[Run-Down Protection](run-down-protection.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronization%20Techniques%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronizing-access-to-device-data.md b/windows-driver-docs-pr/kernel/synchronizing-access-to-device-data.md new file mode 100644 index 0000000000..8932050990 --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronizing-access-to-device-data.md @@ -0,0 +1,46 @@ +--- +title: Synchronizing Access to Device Data +author: windows-driver-content +description: Synchronizing Access to Device Data +ms.assetid: aaed8006-6773-4d20-b3a0-b48131f728c6 +keywords: ["interrupt service routines WDK kernel , synchronization", "ISRs WDK kernel , synchronization", "interrupt objects WDK kernel , synchronization", "synchronization WDK kernel , interrupts", "single interrupt vectors WDK kernel", "critical section routines WDK kernel", "interrupt spin locks WDK kernel", "spin locks WDK kernel", "synchronization WDK kernel , device data access", "SynchCritSection", "SynchronizeIrql", "SpinLock parameter"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronizing Access to Device Data + + +## + + +Typically, a driver's [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) or [*InterruptMessageService*](https://msdn.microsoft.com/library/windows/hardware/ff547940) routines (ISRs) must share access to driver data and hardware resources with other driver routines. Since ISRs execute in an interrupt context at an elevated IRQL, and since a system might have multiple processors, it is important to synchronize access to shared data and resources so that each routine can be guaranteed to temporarily have exclusive access to this shared information, without interruption. + +The system supports this synchronization by executing the ISR within an *interrupt critical section*. An interrupt has an assigned spin lock, the *interrupt spin lock*, and IRQL, the *interrupt synchronization IRQL*. The system guarantees this code executing within the critical section exclusive access to shared information, by raising the processor's IRQL to the interrupt synchronization IRQL and acquiring the interrupt spin lock before executing the code. The system always enters the interrupt's critical section before executing its ISR. Different interrupts can share the same critical section by sharing their interrupt spin lock and synchronization IRQL. + +Drivers can implement code that runs in the interrupt's critical section by supplying a [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine. When the driver uses [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call the *SynchCritSection* routine, the system automatically enters the critical section for the interrupt specified by the *Interrupt* parameter. + +Raising the processor's IRQL to the interrupt's synchronization IRQL prevents the current processor from being interrupted, except by an interrupt with a higher synchronization IRQL. Acquiring a spin lock prevents other processors from executing any critical section code associated with that spin lock. + +The system assigns the interrupt spin lock and synchronization IRQL for the interrupt when the driver calls [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378). In most instances, the driver can allow the system to determine both values: + +- If the driver uses the CONNECT\_LINE\_BASED or CONNECT\_MESSAGE\_BASED versions of **IoConnectInterruptEx**, and specifies a **NULL** spin lock, the system will allocate a spin lock to be shared across all of the device's interrupts. The system also determines the value for the synchronization IRQL (drivers can optionally specify a higher value). All of the driver's interrupts will share the same critical section. + +- If the driver uses the CONNECT\_FULLY\_SPECIFIED version of **IoConnectInterruptEx** and has only a single interrupt vector, the driver can specify a **NULL** spin lock. The system will allocate a spin lock for only that particular interrupt, which will have its own critical section. + +A driver must allocate its own spin lock only when using the CONNECT\_FULLY\_SPECIFIED version of **IoConnectInterruptEx** and when it has multiple interrupt vectors that must share the same critical section. A driver can specify its own spin lock and synchronization IRQL by using the **SpinLock** and **SynchronizeIrql** members of **IO\_CONNECT\_INTERRUPT\_PARAMETERS**. For more information, see [**IO\_CONNECT\_INTERRUPT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff550541). + +For information about writing and entering critical sections, see [Using Critical Sections](using-critical-sections.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronizing%20Access%20to%20Device%20Data%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-driver-routines-that-process-irps.md b/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-driver-routines-that-process-irps.md new file mode 100644 index 0000000000..929b101a5e --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-driver-routines-that-process-irps.md @@ -0,0 +1,48 @@ +--- +title: Synchronizing Cancellation in Driver Routines that Process IRPs +author: windows-driver-content +description: Synchronizing Cancellation in Driver Routines that Process IRPs +ms.assetid: 0b252ebd-b9d5-4747-9a27-c1ecffdbae18 +--- + +# Synchronizing Cancellation in Driver Routines that Process IRPs + + +## + + +Any driver routine that dequeues or is called with an IRP that is held in a cancelable state, including a driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine, must do the following: + +1. Call [**IoAcquireCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff548196). + +2. Check to make sure that **Irp** equals **DeviceObject->CurrentIrp**. If not, call [**IoReleaseCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff549550) and return control. + + If the two are not the same, the **CurrentIrp** might have been canceled between the time that [**IoStartPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550370) released the cancel spin lock and this routine acquired it. + +3. Call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) with a **NULL** *CancelRoutine* pointer to remove the IRP from the cancelable state. + +4. Check the **Irp->Cancel** field to determine whether to cancel the IRP or to begin processing the I/O request. + + If **Irp->Cancel** is set to **TRUE**, do the following: + + - Call **IoReleaseCancelSpinLock**. + - Set **Irp->IoStatus.Status** to STATUS\_CANCELLED. + - Set **Irp->IoStatus.Information** to 0. + - Call [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) (in a *StartIo* routine) to start the next packet. + - Call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with a priority boost of IO\_NO\_INCREMENT to complete the IRP. + + If **Irp->Cancel** is set to **FALSE**, call **IoReleaseCancelSpinLock** and start the requested processing the I/O request or pass the IRP to the next lower driver, as appropriate. + +Drivers that manage their own queues of IRPs, rather than using the I/O manager-supplied device queue, do not need to acquire the cancel spin lock when calling **IoSetCancelRoutine**. However, these drivers should check the [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine pointer that **IoSetCancelRoutine** returns to determine whether the cancel routine has already started. + +In any driver that handles cancelable IRPs, every driver routine that processes an IRP before the underlying device has been programmed for the requested I/O operation should check the cancelable state of all incoming IRPs. Specifically, a highest-level device driver with both *StartIo* and [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routines should process incoming IRPs in both these driver routines as already described. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronizing%20Cancellation%20in%20Driver%20Routines%20that%20Process%20IRPs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-higher-level-drivers-without-cancel-rout.md b/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-higher-level-drivers-without-cancel-rout.md new file mode 100644 index 0000000000..75b6f569d4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronizing-cancellation-in-higher-level-drivers-without-cancel-rout.md @@ -0,0 +1,30 @@ +--- +title: Synchronizing Cancellation in Higher-Level Drivers without Cancel Routines +author: windows-driver-content +description: Synchronizing Cancellation in Higher-Level Drivers without Cancel Routines +ms.assetid: 741d504e-7e61-4f60-a8cf-e4ea92f0654e +--- + +# Synchronizing Cancellation in Higher-Level Drivers without Cancel Routines + + +## + + +A higher-level driver can make no assumptions about whether or how existing lower-level drivers handle cancelable IRPs. As soon as any higher-level driver calls [**IoCallDriver**](https://msdn.microsoft.com/library/windows/hardware/ff548336) for an IRP, it no longer owns that IRP and it can neither ascertain nor control processing of the IRP by lower-level drivers. + +However, any higher-level driver can set an [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routine for an IRP by calling [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679) before it calls **IoCallDriver**. The higher-level driver can determine whether any pending IRP is canceled in a lower driver by calling **IoSetCompletionRoutine** with the *InvokeOnCancel* parameter set to **TRUE** before it passes the IRP on to lower drivers. Doing so ensures that the driver's *IoCompletion* routine will be called whether the IRP is canceled or completed. + +A higher-level driver can call [**IoCancelIrp**](https://msdn.microsoft.com/library/windows/hardware/ff548338) with any pending IRP that the driver has allocated. However, making this call does not ensure that the driver-allocated IRP will be completed with its I/O status block set to STATUS\_CANCELLED; another thread might already be completing the IRP. To check whether the IRP was canceled, the higher-level driver must call **IoSetCompletionRoutine** with the *InvokeOnCancel* parameter set to **TRUE** before passing the IRP on to the next lower driver. See [Completing IRPs](completing-irps.md) for more information about completion routines. + +A higher-level driver must not call **IoCancelIrp** with an IRP that it did not allocate. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronizing%20Cancellation%20in%20Higher-Level%20Drivers%20without%20Cancel%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronizing-irp-cancellation.md b/windows-driver-docs-pr/kernel/synchronizing-irp-cancellation.md new file mode 100644 index 0000000000..73d10b0f9c --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronizing-irp-cancellation.md @@ -0,0 +1,58 @@ +--- +title: Synchronizing IRP Cancellation +author: windows-driver-content +description: Synchronizing IRP Cancellation +ms.assetid: a110c6ad-794d-4b8a-a89d-bceb08ea82b8 +keywords: ["canceling IRPs, synchronization", "Cancel routines, synchronization", "synchronization WDK IRPs", "cancelable IRPs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronizing IRP Cancellation + + +## + + +From a driver's perspective, an IRP can be canceled at any time. IRP cancellation occurs asynchronously; therefore, drivers must be able to handle a number of potential race conditions, created if the IRP is canceled at any of the following points: + +- After a driver routine is called, but before it queues an IRP. + +- After a driver routine is called, but before it tries to process an IRP. For example, an IRP might be canceled after a driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine is called, but before the *StartIo* routine removes the IRP from the device queue. + +- After the driver routine dequeues the IRP, but before it starts the requested I/O. + +Note that after a driver queues an IRP and releases any spin locks that protect the queue, another thread can access and change the IRP. When the original thread resumes—even as soon as the next line of code—the IRP might have already been canceled or otherwise changed. + +Driver can use the cancel-safe IRP queue framework to implement IRP queuing. The system then registers a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for the driver that automatically handles synchronization to safely cancel IRPs. See [Cancel-Safe IRP Queues](cancel-safe-irp-queues.md) for more information. Otherwise, drivers must implement their own synchronization. + +The following members of an IRP contain information about cancellation: + +- **Irp->Cancel** indicates whether an IRP is being canceled or should be canceled. + +- **Irp->CancelRoutine** indicates whether an IRP is cancelable. If this member contains a pointer to a cancel routine, then the IRP is cancelable. If this member is **NULL**, then the IRP is not cancelable. If this member is **NULL**, but **Irp->Cancel** is set, that indicates that the cancel routine is running and the IRP is in the process of being canceled. + +If a driver handles cancelable IRPs, it is responsible for setting the appropriate *Cancel* routine in each IRP that it holds in a cancelable state. + +This section includes the following topics on synchronizing IRP cancellation. + +[Using the System's Cancel Spin Lock](using-the-system-s-cancel-spin-lock.md) + +[Synchronizing Cancellation in Driver Routines that Process IRPs](synchronizing-cancellation-in-driver-routines-that-process-irps.md) + +[Synchronizing Cancellation in Higher-Level Drivers without Cancel Routines](synchronizing-cancellation-in-higher-level-drivers-without-cancel-rout.md) + +[Using a Driver-Supplied Spin Lock](using-a-driver-supplied-spin-lock.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronizing%20IRP%20Cancellation%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronous-driver-notification.md b/windows-driver-docs-pr/kernel/synchronous-driver-notification.md new file mode 100644 index 0000000000..bc2b27446b --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronous-driver-notification.md @@ -0,0 +1,33 @@ +--- +title: Synchronous Driver Notification +author: windows-driver-content +description: Synchronous Driver Notification +ms.assetid: d40053d7-730a-4e08-a91a-41dccef22fbd +keywords: ["driver notification WDK dynamic hardware partitioning , synchronous", "synchronous notification WDK dynamic hardware partitioning", "notification WDK dynamic hardware partitioning , synchronous", "synchronous driver notification WDK dynamic hardware partitioning"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Synchronous Driver Notification + + +This section discusses synchronous driver notification when a new processor is dynamically added to a hardware partition. + +This section includes the following topics: + +[Registering for Synchronous Driver Notification](registering-for-synchronous-driver-notification.md) + +[Processing a Synchronous Driver Notification](processing-a-synchronous-driver-notification.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronous%20Driver%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/synchronous-i-o-programming.md b/windows-driver-docs-pr/kernel/synchronous-i-o-programming.md new file mode 100644 index 0000000000..beb8d8cb6c --- /dev/null +++ b/windows-driver-docs-pr/kernel/synchronous-i-o-programming.md @@ -0,0 +1,25 @@ +--- +title: Synchronous I/O Programming +author: windows-driver-content +description: Synchronous I/O Programming +ms.assetid: ef021dd2-bd1d-4fb0-853f-014c62bda76b +--- + +# Synchronous I/O Programming + + +Synchronous programming simply waits for a call to return. This is fast and efficient from the programmer's point of view but in an environment like Windows where many programs are running at once, it can cause problems. Whenever possible, use [Asynchronous I/O Programming Techniques](asynchronous-i-o-programming.md). + +**Note**  For driver developers using Microsoft Vista, this is not as serious a problem. For more information about synchronous programming in Vista, see [Restricting Waits in Vista](restricting-waits-in-vista.md). + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Synchronous%20I/O%20Programming%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-power-actions.md b/windows-driver-docs-pr/kernel/system-power-actions.md new file mode 100644 index 0000000000..6ba0915c82 --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-power-actions.md @@ -0,0 +1,77 @@ +--- +title: System Power Actions +author: windows-driver-content +description: System Power Actions +ms.assetid: e8ab99d4-c18d-4ba8-bfe8-8eebb881c384 +keywords: ["system power actions WDK power management", "system power states WDK kernel , power actions", "power actions WDK power management", "POWER_ACTION"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Power Actions + + +## + + +When the power manager sends an IRP to set or query the system power state, it specifies a system power state along with an additional parameter that gives information about the power state change. This parameter, passed at **Irp->Parameters.Power.ShutdownType**, is an enumerator of the POWER\_ACTION type. The enumerator characterizes the system power state request, as shown in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
POWER_ACTION enumeratorSystem power state requested

PowerActionNone

S0 or no system power IRP active

PowerActionSleep

S1, S2, or S3

PowerActionHibernate

S4

PowerActionShutdown (Microsoft Windows 2000 and later systems only)

S5

PowerActionShutdownReset

S5

PowerActionShutdownOff

S5

+ +  + +When a driver receives a system query or set-power IRP for S5, it can check **ShutdownType** For more information about the requested shutdown. A driver can use this information to optimize its shutdown sequence when the machine is resetting instead of shutting off power indefinitely. Drivers of most devices retain power when the system resets. However, for certain devices, such as a video streaming device that performs direct memory access (DMA), a driver might choose to power down its device when the system is resetting, thus stopping any ongoing I/O. + +When a device power policy owner sends a *device* power IRP to its device stack in response to a system power IRP, drivers can use the **ShutdownType** parameter to get information about the current *system* power IRP. In this case, the value of **ShutdownType** indicates the currently requested system power state, or it is **PowerActionNone** if a system request is not outstanding. Drivers should not, however, rely on this information if the device IRP requests state D0. + +In Windows 98/Me, this member always contains **PowerActionNone** when the IRP requests a device power state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Power%20Actions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-power-policy.md b/windows-driver-docs-pr/kernel/system-power-policy.md new file mode 100644 index 0000000000..dce7fcf17f --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-power-policy.md @@ -0,0 +1,38 @@ +--- +title: System Power Policy +author: windows-driver-content +description: System Power Policy +ms.assetid: 98b1a777-3ac1-40c2-a902-cb5326c20621 +keywords: ["system-wide power policy WDK kernel", "power policy WDK kernel", "power supply WDK kernel", "system power policy WDK kernel", "AC power WDK kernel", "DC power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Power Policy + + +## + + +In its role as system power policy manager, the power manager keeps track of system activity, determines the appropriate system power state, and sends [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784) requests to query or change the system power state. It also provides interfaces through which applications can read and write power policy settings (see the Microsoft Windows SDK). + +The power manager maintains two separate power policies — one for AC (wall current) and one for DC (battery or UPS) — and automatically switches between these two policies depending on the current power source. Typically, AC power policy emphasizes performance over conservation, while DC power policy emphasizes conservation over performance. To find out when the system changes from one policy to the other, a driver can register for notification with the system's \\Callback\\PowerState callback object. For further information, see [**ExCreateCallback**](https://msdn.microsoft.com/library/windows/hardware/ff544560) and [Callback Objects](callback-objects.md). + +Computers that comply with the APCI specification automatically switch from AC to battery power, and from one battery to another, as each such power source goes off line. If the computer hardware allows the operating system to select the power source, the power manager tracks which battery is the least charged but still functional and selects it to power the computer. + +As soon as AC power becomes available, the computer hardware automatically starts to charge a battery. If the hardware allows the operating system to select which battery to charge, the power manager selects the least discharged battery for recharging; this increases the chances that the system will have at least one well-charged battery at all times. + +Regardless of any other settings, the power manager carries out the DC power policy for a critical battery if a battery that is rechargeable or supplies system power reports the hardware condition "critical" and is in the discharging state for two seconds or longer. Power policy in this situation typically requires a transition to the hibernate or shutdown state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Power%20Policy%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-power-states.md b/windows-driver-docs-pr/kernel/system-power-states.md new file mode 100644 index 0000000000..3aced3a532 --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-power-states.md @@ -0,0 +1,46 @@ +--- +title: System Power States +author: windows-driver-content +description: System Power States +ms.assetid: bb30bc89-d1f2-4cb3-bcfb-fb76c69dba27 +keywords: ["system power states WDK kernel , about system power states", "state transitions WDK power management", "Sx names WDK power management", "software resumption WDK power management", "resumption WDK power management", "hardware latency WDK power management", "system hardware context WDK power management", "hardware context WDK power management", "context WDK power management", "waking states WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Power States + + +## + + +System power states describe the power consumption of the system as a whole. The operating system supports six system power states, referred to as S0 (fully on and operational) through S5 (power off). Each state is characterized by the following: + +- Power consumption: how much power does the computer use? + +- Software resumption: from what point does the operating system restart? + +- Hardware latency: how long does it take to return the computer to the working state? + +- System hardware context (such as the content of volatile processor registers, memory caches, and RAM): how much system hardware context is retained? Must the operating system reboot to return to the working state? + +State S0 is the working state. States S1, S2, S3, and S4 are sleeping states, in which the computer appears off because of reduced power consumption but retains enough context to return to the working state without restarting the operating system. State S5 is the shutdown or off state. + +A system is *waking* when it is in transition from the shutdown state (S5) or any sleeping state (S1-S4) to the working state (S0), and it is going to sleep when it is in transition from the working state to any sleep state or the shutdown state. The following figure shows the possible system power state transitions. + +![diagram illustrating the possible system power state transitions](images/sysstate.png) + +As the previous figure shows, the system cannot enter one sleep state directly from another; it must always enter the working state before entering any sleep state. For example, a system cannot transition from state S2 to S4, nor from state S4 to S2. It must first return to S0, from which it can enter the next sleep state. Because a system in an intermediate sleep state has already lost some operating context, it must return to the working state to restore that context before it can make an additional state transition. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Power%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-shutdown-state-s5.md b/windows-driver-docs-pr/kernel/system-shutdown-state-s5.md new file mode 100644 index 0000000000..a10bf97a51 --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-shutdown-state-s5.md @@ -0,0 +1,46 @@ +--- +title: System Shutdown State S5 +author: windows-driver-content +description: System Shutdown State S5 +ms.assetid: c08d688d-c31a-4d57-a343-406edfa35e8f +keywords: ["S5 WDK power management", "system shutdown states WDK power management", "software resumption WDK power management", "resumption WDK power management", "hardware latency WDK power management", "system hardware context WDK power management", "hardware context WDK power management", "context WDK power management", "latency WDK power management", "system power states WDK kernel , shutdown state", "shutdown states WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Shutdown State S5 + + +## + + +In the S5, or shutdown, state, the machine has no memory state and is not performing any computational tasks. + +The only difference between states S4 and S5 is that the computer can restart from the hibernate file in state S4, while restarting from state S5 requires rebooting the system. + +State S5 has the following characteristics: + +**Power consumption** +Off, except for trickle current to devices such as the power button. + +**Software resumption** +Boot is required upon awakening. + +**Hardware latency** +Long and undefined. Only physical interaction, such as the user pressing the ON switch, returns the system to the working state. The BIOS can also awaken from a resume timer if the system is so configured. + +**System hardware context** +None retained. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Shutdown%20State%20S5%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-sleeping-states.md b/windows-driver-docs-pr/kernel/system-sleeping-states.md new file mode 100644 index 0000000000..e2d457561d --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-sleeping-states.md @@ -0,0 +1,102 @@ +--- +title: System Sleeping States +author: windows-driver-content +description: System Sleeping States +ms.assetid: 2fd883b5-4e89-4ce9-b75a-b821348ac860 +keywords: ["system power states WDK kernel , sleeping states", "system sleeping states WDK power management", "sleeping states WDK power management", "S1 WDK power management", "S2 WDK power management", "S3 WDK power management", "S4 WDK power management", "software resumption WDK power management", "resumption WDK power management", "hardware latency WDK power management", "system hardware context WDK power management", "hardware context WDK power management", "context WDK power management", "latency WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Sleeping States + + +## + + +States S1, S2, S3, and S4 are the sleeping states. A system in one of these states is not performing any computational tasks and appears to be off. Unlike a system in the shutdown state (S5), however, a sleeping system retains memory state, either in the hardware or on disk. The operating system need not be rebooted to return the computer to the working state. + +Some devices can wake the system from a sleeping state when certain events occur, such as an incoming call to a modem. In addition, on some computers, an external indicator tells the user that the system is merely sleeping. + +With each successive sleep state, from S1 to S4, more of the computer is shut down. All ACPI-compliant computers shut off their processor clocks at S1 and lose system hardware context at S4 (unless a hibernate file is written before shutdown), as listed in the sections below. Details of the intermediate sleep states can vary depending on how the manufacturer has designed the machine. For example, on some machines certain chips on the motherboard might lose power at S3, while on others such chips retain power until S4. Furthermore, some devices might be able to wake the system only from S1 and not from deeper sleep states. + +### System Power State S1 + +System power state S1 is a sleeping state with the following characteristics: + +**Power consumption** +Less consumption than in S0 and greater than in the other sleep states. Processor clock is off and bus clocks are stopped. + +**Software resumption** +Control restarts where it left off. + +**Hardware latency** +Typically no more than two seconds. + +**System hardware context** +All context retained and maintained by hardware. + +### System Power State S2 + +System power state S2 is similar to S1 except that the CPU context and contents of the system cache are lost because the processor loses power. State S2 has the following characteristics: + +**Power consumption** +Less consumption than in state S1 and greater than in S3. Processor is off. Bus clocks are stopped; some buses might lose power. + +**Software resumption** +After wake-up, control starts from the processor's reset vector. + +**Hardware latency** +Two seconds or more; greater than or equal to the latency for S1. + +**System hardware context** +CPU context and system cache contents are lost. + +### System Power State S3 + +System power state S3 is a sleeping state with the following characteristics: + +**Power consumption** +Less consumption than in state S2. Processor is off and some chips on the motherboard also might be off. + +**Software resumption** +After the wake-up event, control starts from the processor's reset vector. + +**Hardware latency** +Almost indistinguishable from S2. + +**System hardware context** +Only system memory is retained. CPU context, cache contents, and chipset context are lost. + +### System Power State S4 + +System power state S4, the hibernate state, is the lowest-powered sleeping state and has the longest wake-up latency. To reduce power consumption to a minimum, the hardware powers off all devices. Operating system context, however, is maintained in a hibernate file (an image of memory) that the system writes to disk before entering the S4 state. Upon restart, the loader reads this file and jumps to the system's previous, prehibernation location. + +If a computer in state S1, S2, or S3 loses all AC or battery power, it loses system hardware context and therefore must reboot to return to S0. A computer in state S4, however, can restart from its previous location even after it loses battery or AC power because operating system context is retained in the hibernate file. A computer in the hibernate state uses no power (with the possible exception of trickle current). + +State S4 has the following characteristics: + +**Power consumption** +Off, except for trickle current to the power button and similar devices. + +**Software resumption** +System restarts from the saved hibernate file. If the hibernate file cannot be loaded, rebooting is required. Reconfiguring the hardware while the system is in the S4 state might result in changes that prevent the hibernate file from loading correctly. + +**Hardware latency** +Long and undefined. Only physical interaction returns the system to the working state. Such interaction might include the user pressing the ON switch or, if the appropriate hardware is present and wake-up is enabled, an incoming ring for the modem or activity on a LAN. The machine can also awaken from a resume timer if the hardware supports it. + +**System hardware context** +None retained in hardware. The system writes an image of memory in the hibernate file before powering down. When the operating system is loaded, it reads this file and jumps to its previous location. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Sleeping%20States%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-wide-overview-of-power-management.md b/windows-driver-docs-pr/kernel/system-wide-overview-of-power-management.md new file mode 100644 index 0000000000..f935455e13 --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-wide-overview-of-power-management.md @@ -0,0 +1,44 @@ +--- +title: System-Wide Overview of Power Management +author: windows-driver-content +description: System-Wide Overview of Power Management +ms.assetid: 16313152-3fe2-49d7-8cf1-b369e39e4130 +keywords: ["power management WDK kernel , about power management", "power management WDK kernel , system-wide overview", "software WDK power management", "Control Panel WDK power management", "system-wide power policy WDK kernel", "power policy WDK kernel", "conserving power WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System-Wide Overview of Power Management + + +## + + +Power management requires support from system and device hardware and from system software and drivers. Required hardware support is covered in the industry specifications, as described in the previous section. This topic covers the software support—specifically, what drivers must do to conform to operating system requirements and to manage power as appropriate for their devices. + +The following figure shows a system-wide overview of power management. + +![diagram illustrating a system-wide overview of power management](images/power-comp.png) + +Applications and users can affect power management decisions through Control Panel and by calling power management routines. Users can use Control Panel to set system and device power options, including custom power settings. Control Panel notifies the power manager and drivers of changes to the active power policy and associated power settings. Beginning with Windows Vista, the power manager notifies a driver by calling the [**power setting callback**](https://msdn.microsoft.com/library/windows/hardware/ff559727) that a driver registers to receive notifications. In Windows Server 2003, Windows XP, and Windows 2000, this notification is performed through WMI. + +The power manager administers the system-wide *power policy*, the rules that govern the system's power usage. (For more information, see [System Power Policy](system-power-policy.md).) Using information from Control Panel and APIs, the power manager can determine when applications are using, or might need to use, various devices, so that it can adjust the system's power policy appropriately. + +The power manager also provides an interface for drivers, comprising [power management support routines](https://msdn.microsoft.com/library/windows/hardware/ff559835), [power management minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff559822), and required driver entry points. + +When the power manager requests a change to the system power state, drivers respond by putting their devices in an appropriate device power state. In addition, drivers can perform idle detection for their devices and put unused devices in a sleep state. Bus-specific mechanisms report device power capabilities, set and report device status, and change device power. Exactly how and when device power is changed depends on the type of device and the capabilities of the device hardware. + +Although ACPI hardware realizes the greatest power savings, the hardware need not be ACPI-compliant for power management in drivers to be effective. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System-Wide%20Overview%20of%20Power%20Management%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-worker-threads.md b/windows-driver-docs-pr/kernel/system-worker-threads.md new file mode 100644 index 0000000000..bb338de254 --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-worker-threads.md @@ -0,0 +1,63 @@ +--- +title: System Worker Threads +author: windows-driver-content +description: System Worker Threads +ms.assetid: 01ae1c1b-0cb0-4b9b-bd74-341b7c289fd4 +keywords: ["executive worker threads WDK kernel", "work items WDK kernel", "thread objects WDK kernel", "WorkItem", "WorkItemEx", "worker threads WDK kernel", "worker-thread callback routines WDK kernel", "callback routines WDK worker threads"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Worker Threads + + +## + + +A driver that requires delayed processing can use a [*work item*](https://msdn.microsoft.com/library/windows/hardware/ff556347#wdkgloss-work-item), which contains a pointer to a driver callback routine that performs the actual processing. The driver queues the work item, and a *system worker thread* removes the work item from the queue and runs the driver's callback routine. The system maintains a pool of these system worker threads, which are system threads that each process one work item at a time. + +The driver associates a [*WorkItem*](https://msdn.microsoft.com/library/windows/hardware/ff566380) callback routine with the work item. When the system worker thread processes the work item, it calls the associated *WorkItem* routine. In Windows Vista and later versions of Windows, a driver can instead associate a [*WorkItemEx*](https://msdn.microsoft.com/library/windows/hardware/ff566381) routine with a work item. *WorkItemEx* takes parameters that are different from the parameters that *WorkItem* takes. + +*WorkItem* and *WorkItemEx* routines run in a system thread context. If a driver dispatch routine can run in a user-mode thread context, that routine can call a *WorkItem* or *WorkItemEx* routine to perform any operations that require a system thread context. + +To use a work item, a driver performs the following steps: + +1. Allocate and initialize a new work item. + + The system uses an [**IO\_WORKITEM**](https://msdn.microsoft.com/library/windows/hardware/ff550679) structure to hold a work item. To allocate a new **IO\_WORKITEM** structure and initialize it as a work item, the driver can call [**IoAllocateWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff548276). In Windows Vista and later versions of Windows, the driver can alternatively allocate its own **IO\_WORKITEM** structure, and call [**IoInitializeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549349) to initialize the structure as a work item. (The driver should call [**IoSizeofWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff550352) to determine the number of bytes that are necessary to hold a work item.) + +2. Associate a callback routine with the work item, and queue the work item so that it will be processed by a system worker thread. + + To associate a *WorkItem* routine with the work item and queue the work item, the driver should call [**IoQueueWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549466). To instead associate a *WorkItemEx* routine with the work item and queue the work item, the driver should call [**IoQueueWorkItemEx**](https://msdn.microsoft.com/library/windows/hardware/ff549474). + +3. After the work item is no longer required, free it. + + A work item that was allocated by **IoAllocateWorkItem** should be freed by [**IoFreeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff549133). A work item that was initialized by **IoInitializeWorkItem** must be uninitialized by [**IoUninitializeWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff550392) before it can be freed. + + The work item can only be uninitialized or freed when the work item is not currently queued. The system dequeues the work item before it calls the work item's callback routine, so **IoFreeWorkItem** and **IoUninitializeWorkItem** can be called from within the callback. + +A DPC that needs to initiate a processing task that requires lengthy processing or that makes a blocking call should delegate the processing of that task to one or more work items. While a DPC runs, all threads are prevented from running. Additionally, a DPC, which runs at IRQL = DISPATCH\_LEVEL, must not make blocking calls. However, the system worker thread that processes a work item runs at IRQL = PASSIVE\_LEVEL. Thus, the work item can contain blocking calls. For example, a system worker thread can wait on a dispatcher object. + +Because the pool of system worker threads is a limited resource, *WorkItem* and *WorkItemEx* routines can be used only for operations that take a short period of time. If one of these routines runs for too long (if it contains an indefinite loop, for example) or waits for too long, the system can deadlock. Therefore, if a driver requires long periods of delayed processing, it should instead call [**PsCreateSystemThread**](https://msdn.microsoft.com/library/windows/hardware/ff559932) to create its own system thread. + +Do not call **IoQueueWorkItem** or **IoQueueWorkItemEx** to queue a work item that is already in the queue. In checked builds, this error causes a bug check. In retail builds, the error is not detected but can cause corruption of system data structures. If your driver queues the same work item each time a particular driver routine runs, you can use the following technique to avoid queuing the work item a second time if it is already in the queue: + +- The driver maintains a list of tasks for the worker routine. +- This task list is available in the context that is supplied to the worker routine. The worker routine and any driver routines that modify the task list synchronize their access to the list. +- Each time the worker routine runs, it performs all the tasks in the list, and removes each task from the list as the task is completed. +- When a new task arrives, the driver adds this task to the list. The driver queues the work item only if the task list was previously empty. + +The system worker thread removes the work item from the queue before it calls the worker thread. Thus, a driver thread can safely queue the work item again as soon as the worker thread starts to run. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Worker%20Threads%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/system-working-state-s0.md b/windows-driver-docs-pr/kernel/system-working-state-s0.md new file mode 100644 index 0000000000..03f963af7d --- /dev/null +++ b/windows-driver-docs-pr/kernel/system-working-state-s0.md @@ -0,0 +1,42 @@ +--- +title: System Working State S0 +author: windows-driver-content +description: System Working State S0 +ms.assetid: 93ab0943-a4cc-4ef0-a250-1c63b2c915d5 +keywords: ["system power states WDK kernel , working states", "system working states WDK power management", "S0 WDK power management", "working states WDK power management", "software resumption WDK power management", "resumption WDK power management", "hardware latency WDK power management", "system hardware context WDK power management", "hardware context WDK power management", "context WDK power management", "latency WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# System Working State S0 + + +## + + +System power state S0, the system working state, has the following characteristics: + +**Power consumption** +Maximum. However, the power state of individual devices can change dynamically as power conservation takes place on a per-device basis. Unused devices can be powered down and powered up as needed. + +**Software resumption** +Not applicable. + +**Hardware latency** +None. + +**System hardware context** +All context is retained. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20System%20Working%20State%20S0%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/systemwake.md b/windows-driver-docs-pr/kernel/systemwake.md new file mode 100644 index 0000000000..a4032b2bc9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/systemwake.md @@ -0,0 +1,38 @@ +--- +title: SystemWake +author: windows-driver-content +description: SystemWake +ms.assetid: 77390637-bb92-4634-a407-9a409a8a8acd +keywords: ["SystemWake"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SystemWake + + +## + + +The **SystemWake** member of [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) contains the lowest (least-powered) system power state from which the device can wake the system, or **PowerSystemUnspecified** if the device cannot wake the system. + +The bus driver sets this value at when it enumerates the device. A higher-level driver can change the value to a higher-powered state but cannot change it to a lower-powered state. For example, if the bus driver sets **SystemWake** to S3 but a driver further up the device stack supports wake-up only from S2, the higher-level driver can change the value to S2. If a driver changes **SystemWake**, it might also have to change [**DeviceWake**](devicewake.md), as explained in the next section. + +Drivers rarely need to propagate changed values back down the device stack. Because changes make the device capabilities more restrictive, lower drivers do not see requests that they cannot handle. In the previous example, a higher-level driver fails any request to wake the system from a lower-powered state than S2, so lower drivers never see such a request. However, if a lower driver must be aware of any changes, it can send a PnP [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) to its own device stack during its processing of an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749). + +If both the **SystemWake** and **DeviceWake** members are nonzero (that is, not **PowerSystemUnspecified**), then the device and its drivers support wake-up on this system. + +On non-ACPI hardware, this member always contains zero (**PowerSystemUnspecified**). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20SystemWake%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/technique-1--defining-a--64bit--field.md b/windows-driver-docs-pr/kernel/technique-1--defining-a--64bit--field.md new file mode 100644 index 0000000000..c83988088e --- /dev/null +++ b/windows-driver-docs-pr/kernel/technique-1--defining-a--64bit--field.md @@ -0,0 +1,115 @@ +--- +title: Technique 1 Defining a "64Bit" Field +author: windows-driver-content +description: Defining a "64Bit" Field for drivers +ms.assetid: 6498e66c-145e-4f7e-a065-cbd781e142cc +keywords: ["32-bit I/O support WDK 64-bit , 64Bit field defined", "64Bit field defined WDK kernel", "bitfields WDK 64-bit", "separate control codes WDK 64-bit", "control codes WDK 64-bit", "file system control codes WDK 64-bit", "FSCTL WDK 64-bit", "I/O control codes WDK kernel , 32-bit I/O in 64-bit drivers", "IOCTLs WDK kernel , 32-bit I/O in 64-bit drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Technique 1: Defining a "64Bit" Field + + +## + + +The "64Bit" field is defined in the IOCTL or FSCTL control code. This field contains a bit flag that is always set for 64-bit callers, but is always clear for 32-bit. Which bit in the control code is chosen as the "64Bit" field is driver-specific, but it must be a bit that is never set for 32-bit callers. A good choice for most drivers is the most significant bit (MSB) in the Function field. + +For example, the IOCTL (FSCTL) control codes used in 32-bit drivers contain four bitfields: + + ++++++ + + + + + + + + + + + + + + + + +
Device typeAccessFunctionMethod

16 bits

2 bits

12 bits

2 bits

+ +  + +As long as none of the existing driver-defined control codes set the MSB in the Function field, these control codes can continue to be used by 32-bit user-mode applications. + +To accommodate 64-bit callers, the driver defines a Function field that is shorter by one bit. This bit is redefined as a "64Bit" field: + + +++++++ + + + + + + + + + + + + + + + + + + +
Device typeAccess64BitFunctionMethod

16 bits

2 bits

1 bit

11 bits

2 bits

+ +  + +The following code example shows how to define a "64Bit" field in a driver header file: + +``` +#define REGISTER_FUNCTION 0 // Define the IOCTL function code + +#ifdef _WIN64 +#define CLIENT_64BIT 0x800 +#define REGISTER_FUNCTION 0 +#define IOCTL_REGISTER CTL_CODE(FILE_DEVICE_UNKNOWN, \ + CLIENT_64BIT|REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) +#else +#define IOCTL_REGISTER CTL_CODE(FILE_DEVICE_UNKNOWN, \ + REGISTER_FUNCTION, METHOD_BUFFERED, FILE_ANY_ACCESS) +#endif + +typedef struct _IOCTL_PARAMETERS { + PVOID Addr; + SIZE_T Length; + HANDLE Handle; +} IOCTL_PARAMETERS, *PIOCTL_PARAMETERS; +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Technique%201:%20Defining%20a%20%2264Bit%22%20Field%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/technique-2--using-iois32bitprocess.md b/windows-driver-docs-pr/kernel/technique-2--using-iois32bitprocess.md new file mode 100644 index 0000000000..d2ff15afd1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/technique-2--using-iois32bitprocess.md @@ -0,0 +1,108 @@ +--- +title: Technique 2 Using IoIs32bitProcess +author: windows-driver-content +description: Technique 2 Using IoIs32bitProcess +ms.assetid: 41e9c0e6-59dd-4e01-9c82-5aba40d8b97f +keywords: ["32-bit I/O support WDK 64-bit , IoIs32bitProcess", "IoIs32bitProcess"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Technique 2: Using IoIs32bitProcess + + +## + + +In cases where it is not practical to define separate IOCTL or FSCTL control codes for I/O requests from 32-bit and 64-bit applications, it is left to the driver to determine which type of application sent the I/O request. The 64-bit version of Microsoft Windows introduces a new kernel-mode routine, [**IoIs32bitProcess**](https://msdn.microsoft.com/library/windows/hardware/ff549372), that detects whether the current I/O request originated in a 32-bit user-mode process. Its prototype is: + +``` +BOOLEAN + IoIs32bitProcess( + _In_opt_ PIRP Irp // NULL for fast I/O call, IRP otherwise + ); +``` + +**IoIs32bitProcess** returns **TRUE** if the originator of the current I/O request is a 32-bit user-mode application. + +The following code sample shows how to use **IoIs32bitProcess**: + +``` +typedef void * POINTER_32 PVOID32; + +typedef struct _IOCTL_PARAMETERS +{ + PVOID Addr; + SIZE_T Length; + HANDLE Handle; +} IOCTL_PARAMETERS, *PIOCTL_PARAMETERS; + +typedef struct _IOCTL_PARAMETERS_32 +{ + PVOID32 Addr; + INT32 Length; + PVOID32 Handle; +} IOCTL_PARAMETERS_32, *PIOCTL_PARAMETERS_32; + +... + +IOCTL_PARAMETERS LocalParam; + +if (IoIs32bitProcess(Irp)) +{ + /* 32-bit process IOCTL */ + PIOCTL_PARAMETERS_32 params32; + + params32 = (PIOCTL_PARAMETERS_32)(Irp->AssociatedIrp.SystemBuffer); + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < sizeof(IOCTL_PARAMETERS_32)) + { + status = STATUS_INVALID_PARAMETER; + } + else + { + LocalParam.Addr = Ptr32ToPtr(params32->Addr); + LocalParam.Handle = Handle32ToHandle(params32->Handle); + LocalParam.Length = params32->Length; + + /* Handle the IOCTL here. */ + ... + + status = STATUS_SUCCESS; + Irp->IoStatus.Information = 0; + } +} +else +{ + /* 64-bit process IOCTL */ + PIOCTL_PARAMETERS params; + + params = (PIOCTL_PARAMETERS)(Irp->AssociatedIrp.SystemBuffer); + if (irpSp->Parameters.DeviceIoControl.InputBufferLength < sizeof(IOCTL_PARAMETERS)) + { + status = STATUS_INVALID_PARAMETER; + } + else + { + RtlCopyMemory(&LocalParam, params, sizeof(IOCTL_PARAMETERS)); + + /* Handle the IOCTL here. */ + ... + + status = STATUS_SUCCESS; + } + Irp->IoStatus.Information = 0; +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Technique%202:%20Using%20IoIs32bitProcess%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/testing-and-troubleshooting-wmi-driver-support.md b/windows-driver-docs-pr/kernel/testing-and-troubleshooting-wmi-driver-support.md new file mode 100644 index 0000000000..8717da5b8d --- /dev/null +++ b/windows-driver-docs-pr/kernel/testing-and-troubleshooting-wmi-driver-support.md @@ -0,0 +1,30 @@ +--- +title: Testing and Troubleshooting WMI Driver Support +author: windows-driver-content +description: Testing and Troubleshooting WMI Driver Support +ms.assetid: 702f2ad7-d3bb-4268-a0c8-fe6756e840e3 +--- + +# Testing and Troubleshooting WMI Driver Support + + +## + + +This section discusses techniques for testing your driver, and troubleshooting any problems that might occur. + +See the following topics: + +[General Techniques for Testing WMI Driver Support](general-techniques-for-testing-wmi-driver-support.md) + +[Troubleshooting Specific WMI Problems](troubleshooting-specific-wmi-problems.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Testing%20and%20Troubleshooting%20WMI%20Driver%20Support%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/the-life-of-an-i-o-request.md b/windows-driver-docs-pr/kernel/the-life-of-an-i-o-request.md new file mode 100644 index 0000000000..5a475d33c3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/the-life-of-an-i-o-request.md @@ -0,0 +1,38 @@ +--- +title: The Life of an I/O Request +author: windows-driver-content +description: The Life of an I/O Request +ms.assetid: 3198e96c-3794-4736-b7e8-d2704abf1aca +keywords: ["IRPs WDK kernel , I/O request process", "I/O requests WDK kernel", "protected subsystems WDK kernel", "subsystem I/O request process WDK kernel", "user I/O requests WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The Life of an I/O Request + + +## + + +This section describes the path taken by an IRP from creation by the operating system to its completion by the set of drivers responsible for controlling the target device. The section contains the following topics: + +[Example I/O Request – An Overview](example-i-o-request---an-overview.md) + +[Example I/O Request – The Details](example-i-o-request---the-details.md) + +[Driver Thread Context](driver-thread-context.md) + +[Points to Consider about User I/O Requests](points-to-consider-about-user-i-o-requests.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20The%20Life%20of%20an%20I/O%20Request%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/the-new-data-types.md b/windows-driver-docs-pr/kernel/the-new-data-types.md new file mode 100644 index 0000000000..702c761e0e --- /dev/null +++ b/windows-driver-docs-pr/kernel/the-new-data-types.md @@ -0,0 +1,204 @@ +--- +title: The New Data Types +author: windows-driver-content +description: The New Data Types +ms.assetid: 13a0d51e-0a9a-471f-8427-d4a7a7eb6459 +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows", "data types WDK 64-bit", "fixed-precision integer types WDK 64-bit", "pointer-precision integer types WDK 64-bit", "specific-precision pointer types WDK 64-bit", "converting data types", "64-bit WDK kernel , data types"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# The New Data Types + + +## + + +There are three classes of new data types: fixed-precision integer types, pointer-precision integer types, and specific-precision pointer types. These types were added to the Windows environment (specifically, to Basetsd.h) to allow developers to prepare for 64-bit Windows well before its introduction. These new types were derived from the basic C-language integer and long types, so they work in existing code. Therefore, use these data types in your code now, test your code on 32-bit Windows, and use the 64-bit compiler to find and fix portability problems in advance, so your driver can be ready when 64-bit Windows is available for testing. + +In addition, adopting these new data types will make your code more robust. To use these data types, you must scan your code for potentially unsafe pointer usage, polymorphism, and data definitions. To be safe, use the new types. For example, when a variable is of type **ULONG\_PTR**, it is clear that it will be used for casting pointers for arithmetic operations or polymorphism. It is not possible to indicate such usage directly by using the native Win32 data types. You can do this by using derived type naming or Hungarian notation, but both techniques are prone to errors. + +### Fixed-Precision Integer Types + +Fixed-precision data types are the same length for 32-bit and 64-bit programming. To help you remember this, their precision is part of the name of the data type. The following are the fixed-precision data types. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinition

DWORD32

32-bit unsigned integer

DWORD64

64-bit unsigned integer

INT32

32-bit signed integer

INT64

64-bit signed integer

LONG32

32-bit signed integer

LONG64

64-bit signed integer

UINT32

Unsigned INT32

UINT64

Unsigned INT64

ULONG32

Unsigned LONG32

ULONG64

Unsigned LONG64

+ +  + +### Pointer-Precision Integer Types + +As the pointer precision changes (that is, as it becomes 32 bits when compiled for 32-bit platforms, 64 bits when compiled for 64-bit platforms), these data types reflect the precision accordingly. Therefore, it is safe to cast a pointer to one of these types when performing pointer arithmetic; if the pointer precision is 64 bits, the type is 64 bits. The count types also reflect the maximum size to which a pointer can refer. The following are the pointer-precision and count types. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDefinition

DWORD_PTR

Unsigned long type for pointer precision.

HALF_PTR

Signed integral type for half-pointer precision (16 bits on 32-bit systems, 32 bits on 64-bit systems).

INT_PTR

Signed integral type for pointer precision.

LONG_PTR

Signed long type for pointer precision.

SIZE_T

The maximum number of bytes to which a pointer can refer. Use this type for a count that must span the full range of a pointer.

SSIZE_T

Signed SIZE_T.

UHALF_PTR

Unsigned HALF_PTR.

UINT_PTR

Unsigned INT_PTR.

ULONG_PTR

Unsigned LONG_PTR.

+ +  + +### Fixed-Precision Pointer Types + +There are also new pointer types that explicitly size the pointer. Be cautious when using these pointer types in 64-bit code: If you declare the pointer using a 32-bit type, the system creates the pointer by truncating a 64-bit pointer. + + ++++ + + + + + + + + + + + + + + + + +
TypeDefinition

POINTER_32

A 32-bit pointer. On a 32-bit system, this is a native pointer. On a 64-bit system, this is a truncated 64-bit pointer.

POINTER_64

A 64-bit pointer. On a 64-bit system, this is a native pointer. On a 32-bit system, this is a sign-extended 32-bit pointer.

+

Note that it is not safe to assume the state of the high pointer bit.

+ +  + +### Helper Functions + +The following inline functions (defined in Basetsd.h) can help you safely convert values from one type to another: + +``` +unsigned long HandleToUlong( const void *h ) +long HandleToLong( const void *h ) +void * LongToHandle( const long h ) +unsigned long PtrToUlong( const void *p ) +unsigned int PtrToUint( const void *p ) +unsigned short PtrToUshort( const void *p ) +long PtrToLong( const void *p ) +int PtrToInt( const void *p ) +short PtrToShort( const void *p ) +void * IntToPtr( const int i ) +void * UIntToPtr( const unsigned int ui ) +void * LongToPtr( const long l ) +void * ULongToPtr( const unsigned long ul ) +``` + +**Warning**  **IntToPtr** sign-extends the **int** value, **UIntToPtr** zero-extends the unsigned **int** value, **LongToPtr** sign-extends the **long** value, and **ULongToPtr** zero-extends the **unsigned long** value. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20The%20New%20Data%20Types%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/thread-objects.md b/windows-driver-docs-pr/kernel/thread-objects.md new file mode 100644 index 0000000000..01f74f0c8c --- /dev/null +++ b/windows-driver-docs-pr/kernel/thread-objects.md @@ -0,0 +1,38 @@ +--- +title: Thread Objects +author: windows-driver-content +description: Thread Objects +ms.assetid: 698de86b-1790-42d5-a482-82e4431ce7af +keywords: ["kernel dispatcher objects WDK , thread objects", "dispatcher objects WDK kernel , thread objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Thread Objects + + +## + + +This section contains the following topics: + +[Introduction to Thread Objects](introduction-to-thread-objects.md) + +[Thread Priorities](thread-priorities.md) + +[Device-Dedicated Threads](device-dedicated-threads.md) + +[System Worker Threads](system-worker-threads.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Thread%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/thread-priorities.md b/windows-driver-docs-pr/kernel/thread-priorities.md new file mode 100644 index 0000000000..c251cba417 --- /dev/null +++ b/windows-driver-docs-pr/kernel/thread-priorities.md @@ -0,0 +1,36 @@ +--- +title: Thread Priorities +author: windows-driver-content +description: Thread Priorities +ms.assetid: 87a9641c-0569-45c1-acb8-adf5856dc60d +keywords: ["thread objects WDK kernel", "thread priorities WDK kernel", "priorities WDK threads"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Thread Priorities + + +## + + +Some drivers create their own driver- or device-dedicated system threads and set their thread's base priority to the lowest real-time priority value. Other highest-level drivers, particularly file system drivers, use system worker threads with a base priority that is usually set to the highest variable priority value. The kernel schedules a thread with the lowest real-time priority to run ahead of every thread with a variable priority, which includes almost every user-mode thread in the system. + +Most standard driver routines are run in an arbitrary thread context, ahead of all threads that are currently in the ready state. + +Threads, whatever their respective run-time priorities, are run at IRQL = PASSIVE\_LEVEL. Many standard driver routines are run at an IRQL > PASSIVE\_LEVEL, such as DISPATCH\_LEVEL or DIRQL. + +For more information about thread priorities, see the [Scheduling, Thread Context, and IRQL](http://go.microsoft.com/fwlink/p/?linkid=59757) white paper that is available on the Microsoft Windows Hardware Developer Central (WHDC) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Thread%20Priorities%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/threaded-dpcs.md b/windows-driver-docs-pr/kernel/threaded-dpcs.md new file mode 100644 index 0000000000..d835c72e0c --- /dev/null +++ b/windows-driver-docs-pr/kernel/threaded-dpcs.md @@ -0,0 +1,36 @@ +--- +title: Threaded DPCs +author: windows-driver-content +description: Threaded DPCs +ms.assetid: 41f5ffcc-ffa9-45e4-8fe1-278b00ff04da +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Threaded DPCs + + +## + + +This section contains the following topics about threaded deferred procedure calls (DPCs): + +[Introduction to Threaded DPCs](introduction-to-threaded-dpcs.md) + +[Synchronization and Threaded DPCs](synchronization-and-threaded-dpcs.md) + +[Converting an Ordinary DPC to a Threaded DPC](converting-an-ordinary-dpc-to-a-threaded-dpc.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Threaded%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/timer-accuracy.md b/windows-driver-docs-pr/kernel/timer-accuracy.md new file mode 100644 index 0000000000..9ee20a148e --- /dev/null +++ b/windows-driver-docs-pr/kernel/timer-accuracy.md @@ -0,0 +1,31 @@ +--- +title: Timer Accuracy +author: windows-driver-content +description: A system timer routine typically enables the caller to specify either an absolute or a relative expiration time for a timer. +ms.assetid: CA29DC02-1AEA-4A13-B2D6-8C8052E21EDB +--- + +# Timer Accuracy + + +A system timer routine typically enables the caller to specify either an absolute or a relative expiration time for a timer. For example, see [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350), [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286), or [**KeDelayExecutionThread**](https://msdn.microsoft.com/library/windows/hardware/ff551986). The accuracy with which the operating system can measure expiration times is limited by the granularity of the system clock. + +The system time is updated on every tick of the system clock, and is accurate only to the latest tick. If the caller specifies an absolute expiration time, the expiration of the timer is detected during processing of the first system clock tick that occurs after the specified time. Thus, the timer can expire as much as one system clock period later than the specified absolute expiration time. If a timer interval, or relative expiration time, is instead specified, the expiration can occur up to a period earlier than or a period later than the specified time, depending on where exactly the start and end times of this interval fall between system clock ticks. Regardless of whether an absolute or a relative time is specified, the timer expiration might not be detected until even later if interrupt processing for the system clock is delayed by interrupt processing for other devices. + +When the caller specifies a relative expiration time, the timer routine adds the current system clock time to the specified relative expiration time to calculate the absolute expiration time to use for the timer. Because the system time is accurate only to the latest tick of the system clock, the calculated expiration time can be up to a system clock period earlier than the expiration time expected by the caller. If a specified relative expiration time is close to or smaller than the system clock period, the timer might expire immediately, with no delay. + +A possible way to more accurately support shorter expiration times is to decrease the time between system clock ticks, but doing so is likely to increase power consumption. In addition, reducing the system clock period might not reliably achieve a finer system clock granularity unless interrupt processing for the other devices in the platform can be guaranteed not to delay the processing of system clock interrupts. + +Starting with Windows 8, [**KeDelayExecutionThread**](https://msdn.microsoft.com/library/windows/hardware/ff551986) uses a more precise technique to calculate the absolute expiration time from a caller-specified relative expiration time. First, to obtain a more precise estimate of the current system time, the routine uses the system performance counter to measure the time elapsed since the last system clock tick. Next, the routine adds this more precise estimate of the system time to the relative expiration time to calculate the absolute expiration time. The absolute expiration time calculated by this technique is accurate to within a microsecond. As a result, the timer will not expire before the specified relative expiration time elapses. The timer can still expire up to a system clock period later than the specified time, and might expire even later if processing of the system clock interrupt is delayed by interrupt processing for other devices. + +If the system time changes before a timer expires, a relative timer is not affected but the system adjusts each absolute timer. A relative timer always expires after the specified number of time units elapse, regardless of the absolute system time. An absolute timer expires at a specific system time, so a change in the system time changes the wait duration of an absolute timer. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Timer%20Accuracy%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/timer-objects-and-dpcs.md b/windows-driver-docs-pr/kernel/timer-objects-and-dpcs.md new file mode 100644 index 0000000000..b84eb714c6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/timer-objects-and-dpcs.md @@ -0,0 +1,49 @@ +--- +title: KeXxxTimer Routines, KTIMER Objects, and DPCs +author: windows-driver-content +description: Starting with Windows 2000, a set of KeXxxTimer routines is available to manage timers. +ms.assetid: b58487de-6e9e-45f4-acb8-9233c8718ee2 +keywords: ["timers WDK kernel", "timer objects WDK kernel", "timer objects WDK kernel , about timer objects", "deferred procedure calls WDK kernel", "DPCs WDK kernel", "kernel dispatcher objects WDK , timer objects", "dispatcher objects WDK kernel , timer objects", "notification timers WDK kernel", "synchronization timers WDK kernel", "KTIMER", "KeXxxTimer routines", "KeInitializeTimer", "KeInitializeTimerEx", "KeSetTimer", "KeSetTimerEx", "CustomTimerDpc", "timeout intervals WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# KeXxxTimer Routines, KTIMER Objects, and DPCs + + +Starting with Windows 2000, a set of **Ke*Xxx*Timer** routines is available to manage timers. These routines use timer objects that are based on the [**KTIMER**](https://msdn.microsoft.com/library/windows/hardware/ff554250) structure. To create a timer object, a driver first allocates storage for a **KTIMER** structure. Then the driver calls a routine such as [**KeInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff552168) or [**KeInitializeTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff552173) to initialize this structure. + +## + + +A timer can be set to expire just once, or to expire repeatedly after a given interval. [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) always sets a timer that will expire just once. [**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292) accepts an optional *Period* parameter, which specifies a recurring timer interval. + +An optional [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine (a type of deferred procedure call) can be associated with either a notification timer or a synchronization timer. This routine executes when the specified time interval expires. For more information, see [Using Timer Objects](using-timer-objects.md). + +A timer can be a *notification timer* or a *synchronization timer*. + +- When a notification timer is signaled, all waiting threads have their wait satisfied. The state of the timer remains signaled until it is explicitly reset. + +- When a synchronization timer expires, its state is set to Signaled until a single waiting thread is released. Then the timer is reset to the Not-Signaled state. + +**KeInitializeTimer** always creates notification timers. **KeInitializeTimerEx** accepts a *Type* parameter, which can be **NotificationTimer** or **SynchronizationTimer**. + +The following topics provide more information about timer objects and DPCs: + +[Using Timer Objects](using-timer-objects.md) +[Timer Accuracy](timer-accuracy.md) +[Registering and Queuing a CustomTimerDpc Routine](registering-and-queuing-a-customtimerdpc-routine.md) +[Providing CustomTimerDpc Context Information](providing-customtimerdpc-context-information.md) +[Using a CustomTimerDpc Routine](using-a-customtimerdpc-routine.md) +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20KeXxxTimer%20Routines,%20KTIMER%20Objects,%20and%20DPCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/timer-objects.md b/windows-driver-docs-pr/kernel/timer-objects.md new file mode 100644 index 0000000000..f9c7dd26bb --- /dev/null +++ b/windows-driver-docs-pr/kernel/timer-objects.md @@ -0,0 +1,27 @@ +--- +title: Timer Objects +author: windows-driver-content +description: Any driver can use a timer object within a nonarbitrary thread context to time-out operations in the driver's other routines, or to schedule operations to be performed periodically. +ms.assetid: A4844F19-3BEC-48C0-A5BF-E17CCEEC1601 +--- + +# Timer Objects + + +Any driver can use a timer object within a nonarbitrary thread context to time-out operations in the driver's other routines, or to schedule operations to be performed periodically. Starting with Windows 2000, timer objects based on the [**KTIMER**](https://msdn.microsoft.com/library/windows/hardware/ff554250) structure are available to use with [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) and the other **Ke*Xxx*Timer** routines. Starting with Windows 8.1, timer objects based on the [**EX\_TIMER**](https://msdn.microsoft.com/library/windows/hardware/dn265199) structure are available to use with [**ExSetTimer**](https://msdn.microsoft.com/library/windows/hardware/dn265188) and the other **Ex*Xxx*Timer** routines. Timer objects based on the **KTIMER** and **EX\_TIMER** structures are [kernel dispatcher objects](kernel-dispatcher-objects.md) that are signaled when a timer expires. Timer expiration can be periodic or one-shot (nonperiodic). + +This section contains the following topics: + +- [KeXxxTimer Routines, KTIMER Objects, and DPCs](timer-objects-and-dpcs.md) + +- [ExXxxTimer Routines and EX\_TIMER Objects](exxxxtimer-routines-and-ex-timer-objects.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Timer%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/transaction-manager-objects.md b/windows-driver-docs-pr/kernel/transaction-manager-objects.md new file mode 100644 index 0000000000..c0a9cf7ecf --- /dev/null +++ b/windows-driver-docs-pr/kernel/transaction-manager-objects.md @@ -0,0 +1,39 @@ +--- +title: Transaction Manager Objects +author: windows-driver-content +description: Transaction Manager Objects +ms.assetid: af53cda4-e2ab-47df-9311-a4da2a2ee08d +keywords: ["log streams WDK KTM , creating", "virtual clock values WDK KTM , in transaction manager objects", "Kernel Transaction Manager WDK , transaction managers", "transaction manager objects WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Transaction Manager Objects + + +The main purpose of the *transaction manager object* is to create and maintain a [Common Log File System](using-common-log-file-system.md) (CLFS) log stream that KTM uses to record status information about transactions. + +The transaction manager object also contains a [virtual clock value](using-virtual-clock-values.md) that KTM maintains and uses to sequence information in the object's log stream. + +KTM provides a set of [transaction manager object routines](https://msdn.microsoft.com/library/windows/hardware/ff564807) that kernel-mode [TPS components](understanding-tps-components.md) can call. KTM also provides a similar set of user-mode routines that user-mode applications can call. For more information about the user-mode routines, see the Microsoft Windows SDK. + +KTM creates a transaction manager object when a resource manager calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430). Typically, each resource manager in a TPS creates a transaction manager object. But you can also design a TPS in which several resource managers share a single transaction manager object. + +TPS components can open additional handles to an existing transaction manager object by calling [**ZwOpenTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567035). For example, if your TPS has several resource managers that share a single transaction manager object, one resource manager calls **ZwCreateTransactionManager** and then passes the object GUID to the other resource managers so that they can call **ZwOpenTransactionManager**. + +Resource managers close their handles to transaction manager objects by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). + +The operating system deletes the object after the last handle is closed and KTM has released all its references to the object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Transaction%20Manager%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/transaction-notifications.md b/windows-driver-docs-pr/kernel/transaction-notifications.md new file mode 100644 index 0000000000..b03028c721 --- /dev/null +++ b/windows-driver-docs-pr/kernel/transaction-notifications.md @@ -0,0 +1,217 @@ +--- +title: Transaction Notifications +author: windows-driver-content +description: Transaction Notifications +ms.assetid: 62169b56-e70f-4d32-a051-a7fd947dbc64 +keywords: ["notifications WDK KTM", "transactions WDK KTM , notifications", "resource managers WDK KTM , notifications", "Kernel Transaction Manager WDK , notifications", "KTM WDK , notifications", "superior transaction managers WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Transaction Notifications + + +KTM provides a notification queue for each resource manager. KTM delivers notifications to a resource manager by putting them in the resource manager's queue. + +A resource manager can retrieve notifications from its queue either synchronously or asynchronously. + +- To retrieve notifications synchronously, the resource manager can repeatedly call [**ZwGetNotificationResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566467). + +- To receive notifications asynchronously, the resource manager can call [**TmEnableCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff564676) to set up a callback routine. KTM calls the callback routine every time that it puts a notification in the resource manager's queue. + +When a resource manager calls [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) to create an enlistment for a transaction, the resource manager specifies the types of notifications that it should receive. Resource managers receive only notifications that they register to receive. + +The notification constants are defined in Ktmtypes.h. Notification constant names have a format of TRANSACTION\_NOTIFY\_*Xxx*. + +The rest of this topic lists all the notification constants that Ktmtypes.h defines and divides them into three groups: + +- Notifications that resource managers can receive + +- Notifications that superior transaction managers can receive + +- Notification constants that are defined but currently not used + +### Notifications for Resource Managers + +All resource managers must register to receive TRANSACTION\_NOTIFY\_PREPREPARE, TRANSACTION\_NOTIFY\_PREPARE, and TRANSACTION\_NOTIFY\_COMMIT notifications, even if they subsequently call [**ZwReadOnlyEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567074) to mark an enlistment as read-only. + +Resource managers can support TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT, but they must also support the multi-phase pre-prepare, prepare, and commit notifications. + +The following list contains all the notifications that resource managers can receive: + +TRANSACTION\_NOTIFY\_PREPREPARE +**When sent**: A client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) and no resource manager supports single-phase commit, or if a [superior transaction manager](creating-a-superior-transaction-manager.md) calls [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044). + +**Received by**: Resource managers. + +**Recipient's required action**: Perform pre-prepare operations and then call [**ZwPrePrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567040). (For more information about pre-prepare operations, see [Handling Commit Operations](handling-commit-operations.md).) + +**Restrictions:** The resource manager must also support TRANSACTION\_NOTIFY\_PREPARE and TRANSACTION\_NOTIFY\_COMMIT. + +TRANSACTION\_NOTIFY\_PREPARE +**When sent**: After TRANSACTION\_NOTIFY\_PREPREPARE if a client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) and no resource manager supports single-phase commit, or if a superior transaction manager calls [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039). + +**Received by**: Resource managers. + +**Recipient's required action:** Perform prepare operations and then call [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037). (For more information about prepare operations, see [Handling Commit Operations](handling-commit-operations.md).) + +**Restrictions:** The resource manager must also support TRANSACTION\_NOTIFY\_PREPREPARE and TRANSACTION\_NOTIFY\_COMMIT. + +TRANSACTION\_NOTIFY\_COMMIT +**When sent**: After TRANSACTION\_NOTIFY\_PREPARE if a client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) and no resource manager supports single-phase commit, or if a superior transaction manager calls [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419). + +**Received by**: Resource managers. + +**Recipient's required action**: Perform commit operations and then call [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418). (For more information about commit operations, see [Handling Commit Operations](handling-commit-operations.md).) + +**Restrictions:** The resource manager must also support TRANSACTION\_NOTIFY\_PREPREPARE and TRANSACTION\_NOTIFY\_PREPARE. + +TRANSACTION\_NOTIFY\_SINGLE\_PHASE\_COMMIT +**When sent**: A client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) and a resource manager supports single-phase commit operations. + +**Received by**: Resource managers. + +**Recipient's required action**: Either commit the transaction or call [**ZwSinglePhaseReject**](https://msdn.microsoft.com/library/windows/hardware/ff567113). (For more information about single-phase commit operations, see [Handling Commit Operations](handling-commit-operations.md).) + +**Restrictions:** The resource manager must also support TRANSACTION\_NOTIFY\_PREPREPARE, TRANSACTION\_NOTIFY\_PREPARE, and TRANSACTION\_NOTIFY\_COMMIT. + +TRANSACTION\_NOTIFY\_ROLLBACK +**When sent**: A client calls [**ZwRollbackTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567086), a superior transaction manager calls [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083), or KTM detects an error (such as a failed write to the log stream). + +**Received by**: Both resource managers and superior transaction managers. + +**Recipient's required action**: Perform any operations that are needed to roll back the transaction's data, and then call [**ZwRollbackComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567081). (For more information about rollback operations, see [Handling Rollback Operations](handling-rollback-operations.md).) + +**Restrictions:** All resource managers and superior transaction managers must support TRANSACTION\_NOTIFY\_ROLLBACK. + +TRANSACTION\_NOTIFY\_RECOVER +**When sent**: A resource manager calls [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078). + +**Received by**: Resource managers. + +**Recipient's required action**: The resource manager must call [**ZwRecoverEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567075). (For more information about recovery operations, see [Handling Recovery Operations](handling-recovery-operations.md).) + +**Restrictions:** None. + +TRANSACTION\_NOTIFY\_LAST\_RECOVER +**When sent**: After KTM has sent the last TRANSACTION\_NOTIFY\_RECOVER for a resource manager's enlistments. + +**Received by**: Resource managers. + +**Recipient's required action**: End the recovery operation. (For more information about recovery operations, see [Handling Recovery Operations](handling-recovery-operations.md).) + +**Restrictions:** None. + +TRANSACTION\_NOTIFY\_INDOUBT +**When sent**: After a resource manager calls [**ZwRecoverEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567075), if KTM cannot determine whether the transaction should be committed or rolled back (typically because the TPS has a superior transaction manager that is unavailable). + +Received by: Resource managers. + +**Recipient's required action**: Do nothing until KTM sends TRANSACTION\_NOTIFY\_COMMIT or TRANSACTION\_NOTIFY\_ROLLBACK. + +**Restrictions:** None. + +TRANSACTION\_NOTIFY\_RM\_DISCONNECTED +**When sent**: The resource manager that is handling a single-phase commit operation closes the enlistment handle without indicating that it has committed or rolled back the transaction. + +**Received by**: Resource managers and superior transaction managers that have enlistments for the transaction. + +**Recipient's required action**: Transaction-specific cleanup operations. Typically, this notification is useful to read-only resource managers. + +**Restrictions:** None. + +### Notifications for Superior Transaction Managers + +[Superior transaction managers](creating-a-superior-transaction-manager.md) can receive the following notifications: + +TRANSACTION\_NOTIFY\_ROLLBACK +See earlier description. + +TRANSACTION\_NOTIFY\_RM\_DISCONNECTED +See earlier description. + +TRANSACTION\_NOTIFY\_PREPREPARE\_COMPLETE +**When sent**: After all resource managers have received TRANSACTION\_NOTIFY\_PREPREPARE and responded by calling [**ZwPrePrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567040). + +**Received by**: Superior transaction managers. + +**Recipient's required action**: The superior transaction manager should call [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039). + +TRANSACTION\_NOTIFY\_PREPARE\_COMPLETE +**When sent**: After all resource managers have received TRANSACTION\_NOTIFY\_PREPARE and responded by calling [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037). + +**Received by**: Superior transaction managers. + +**Recipient's required action**: The superior transaction manager should call [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419). + +TRANSACTION\_NOTIFY\_COMMIT\_COMPLETE +**When sent**: After all resource managers have received TRANSACTION\_NOTIFY\_COMMIT and responded by calling [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418). + +**Received by**: Superior transaction managers. + +**Recipient's required action**: Transaction cleanup operations. + +TRANSACTION\_NOTIFY\_ROLLBACK\_COMPLETE +**When sent**: After all resource managers have received TRANSACTION\_NOTIFY\_ROLLBACK and responded by calling [**ZwRollbackComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567081). + +**Received by**: Superior transaction managers. + +**Recipient's required action**: Transaction cleanup operations. + +TRANSACTION\_NOTIFY\_RECOVER\_QUERY +**When sent**: A superior transaction manager calls [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078). + +**Received by**: Superior transaction managers. + +**Recipient's required action**: The superior transaction manager must call either [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419) or [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083) for the enlistment. + +TRANSACTION\_NOTIFY\_COMMIT\_REQUEST +**When sent**: A client calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420). If a superior transaction manager has registered for this notification for an enlistment, KTM sends TRANSACTION\_NOTIFY\_COMMIT\_REQUEST to the superior transaction manager **instead of** sending TRANSACTION\_NOTIFY\_COMMIT to the resource managers. + +**Received by**: Superior transaction managers. + +**Recipient's required action**: The superior transaction manager calls [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419). + +TRANSACTION\_NOTIFY\_REQUEST\_OUTCOME +**When sent**: A resource manager calls [**TmRequestOutcomeEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff564727) while the transaction is in its prepared state. + +**Received by**: Superior transaction managers. + +**Recipient's required action**: The superior transaction manager must call [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419) or [**ZwRollbackEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567083). + +### Unused Notifications + +The following notifications are defined in Ktmtypes.h, but KTM currently does not support them: + +TRANSACTION\_NOTIFY\_DELEGATE\_COMMIT + +TRANSACTION\_NOTIFY\_ENLIST\_MASK + +TRANSACTION\_NOTIFY\_ENLIST\_PREPREPARE + +TRANSACTION\_NOTIFY\_MARSHAL + +TRANSACTION\_NOTIFY\_PROMOTE + +TRANSACTION\_NOTIFY\_PROMOTE\_NEW + +TRANSACTION\_NOTIFY\_PROPAGATE\_PULL + +TRANSACTION\_NOTIFY\_PROPAGATE\_PUSH + +TRANSACTION\_NOTIFY\_TM\_ONLINE + +TRANSACTION\_NOTIFY\_COMMIT\_FINALIZE + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Transaction%20Notifications%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/transaction-objects.md b/windows-driver-docs-pr/kernel/transaction-objects.md new file mode 100644 index 0000000000..2e02a000ff --- /dev/null +++ b/windows-driver-docs-pr/kernel/transaction-objects.md @@ -0,0 +1,37 @@ +--- +title: Transaction Objects +author: windows-driver-content +description: Transaction Objects +ms.assetid: 124105bd-70be-49b1-8ea4-af6ba1f3cf16 +keywords: ["transactions WDK KTM , objects", "transactions WDK KTM", "transactional clients WDK KTM , creating transactions", "Kernel Transaction Manager WDK , transactions", "KTM WDK , transactions", "transaction objects WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Transaction Objects + + +*Transaction objects* represent transactions. A transactional client creates a transaction, performs some work, and the either commits or rolls back the transaction. + +KTM provides a set of [transaction object routines](https://msdn.microsoft.com/library/windows/hardware/ff564831) that kernel-mode transactional clients can call. KTM also provides a similar set of user-mode routines that user-mode applications can call. For more information about the user-mode routines, see the Microsoft Windows SDK. + +KTM creates a transaction object when a client calls [**ZwCreateTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566429). The client can call either [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) or [**ZwRollbackTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567086) to commit or roll back the transaction. + +[TPS components](understanding-tps-components.md) can call [**ZwOpenTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567033) to open additional handles to a transaction object. + +Clients close their handles to transaction objects by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). If the last handle is closed before the transaction object has been committed, KTM sends TRANSACTION\_NOTIFY\_ROLLBACK notifications to all resource managers that have an enlistment for the transaction. + +The operating system deletes the object after the last handle is closed and KTM has released all its references to the object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Transaction%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/transaction-processing-terms.md b/windows-driver-docs-pr/kernel/transaction-processing-terms.md new file mode 100644 index 0000000000..30afc5fa8c --- /dev/null +++ b/windows-driver-docs-pr/kernel/transaction-processing-terms.md @@ -0,0 +1,89 @@ +--- +title: Transaction Processing Terms +author: windows-driver-content +description: Before you begin to use KTM, you should know the definitions of the following terms transaction, resource manager, transactional client, transaction manager, log stream, enlistment, and transaction processing system. +Robots: noindex, nofollow +ms.assetid: c8a8806f-a228-4d02-9995-c8cf45e57935 +keywords: ["Kernel Transaction Manager WDK , terminology", "KTM WDK , terminology", "transactions WDK KTM , definition", "resource managers WDK KTM , definition", "transactional clients WDK KTM , definition", "transaction managers WDK KTM , definition", "log streams WDK KTM , definition", "enlistments WDK KTM , definition", "transaction processing systems WDK KTM , definition", "TPS WDK KTM , definition", "transactions WDK KTM , terminology", "transaction managers WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Transaction Processing Terms + + +Before you begin to use KTM, you should know the definitions of the following terms: [transaction](#ktm-term-transaction), [resource manager](#ktm-term-resource-manager), [transactional client](#ktm-term-transactional-client), [transaction manager](#ktm-term-transaction-manager), [log stream](#ktm-term-log-stream), [enlistment](#ktm-term-enlistment), and [transaction processing system](#ktm-term-transaction-processing-system). + +**transaction** +A *transaction* is a collection of data operations. All the operations must succeed for the transaction to succeed. If all the operations succeed, the transaction can be *committed* (that is, its results can be made permanent and public). If any operation fails, the transaction must be *rolled back*, (that is, all changes must be removed so that the data is in the same state that it was in before the transaction's operations began). + +A transaction's operations are *atomic*, *consistent*, *isolated*, and *durable* (ACID). + +- They are atomic because they must be committed or rolled back as a whole. + +- They are consistent because the operations always produce an accurate result, whether they are committed or rolled back. + +- They are isolated because each transaction's results are not visible to other transactions until the transaction's operations have been committed or rolled back. + +- They are durable because, after the transaction's operations have been committed or rolled back, the results of the operations are permanent. + +An example of a transaction is the set of operations that must be performed when you use an automatic teller machine (ATM) to transfer money from your checking account to your savings account. The debit from your checking account and the credit to your savings account must appear to be a single, atomic operation. + +An operation that is part of a transaction is also known as a *transacted operation*. + +**resource manager** +A *resource manager* is a software component that manages data resources that can be updated by transacted operations. For example, if you are designing a database system, you might provide a resource manager that stores and retrieves the database's data. A simple [transaction processing system](#ktm-term-transaction-processing-system) (TPS) might have only one resource manager. + +A resource manager typically also provides a public interface that transactional clients can call to access the resource manager's data. For example, the resource manager for a database might provide a set of functions that clients can call to read from and write to the database. + +A more complex TPS can have multiple resource managers, each of which manages a separate database or other resource while participating in the system's transactions. + +For more information about resource managers, see [Creating a Resource Manager](creating-a-resource-manager.md). + +In some cases, one resource manager is *superior* to the other resource managers and can initiate commit operations. In KTM, such resource managers are called [superior transaction managers](creating-a-superior-transaction-manager.md). + +**transactional client** +A *transactional client* is a software component that accesses a database that a resource manager supports, typically by calling functions that the resource manager exports. The client is responsible for creating transactions, performing a set of operations that a resource manager supports, and then informing the transaction manager (KTM) that the transaction should be either committed or rolled back. + +For more information about transactional clients, see [Creating a Transactional Client](creating-a-transactional-client.md). + +**transaction manager** +A *transaction manager*, such as KTM, provides the infrastructure that enables transactional clients and resource managers to communicate with each other. It also tracks the state of each transaction (but not the data that clients and resource managers handle). + +The transaction manager can also coordinate recovery operations after a system crash. + +The transaction manager has no knowledge of the data or operations that make up a transaction. The data and operations are controlled by the clients and resource managers. + +KTM provides functions that transactional clients can call. These functions enable clients to create, commit, and roll back transactions. + +KTM also provides functions that resource managers can call. These functions enable resource managers to enlist in transactions so that they can receive notifications about transactions. After a resource manager enlists in a transaction, it can receive a notification when a transactional client is ready to commit or roll back the transaction, or when a recovery operation occurs. + +**log stream** +A *log stream* is a recorded history of the events that have happened to transactions. KTM maintains a log stream by using the [Common Log File System](using-common-log-file-system.md) (CLFS). KTM records state changes for each transaction so that it can support rollback and recovery operations when they are necessary. + +Resource managers must also use a log stream to record data and operations. + +A rollback operation requires KTM and resource managers to restore a transaction and all data to an initial state. KTM and resource managers record the initial state of each transaction in the log streams so that they can fetch it during a rollback operation. + +Recovery operations occur after a system crash. When the operating system subsequently restarts, KTM and resource managers can use log stream contents to rebuild a transaction's state to the state that it was in before the crash. + +For more information about log streams in KTM, see [Using Log Streams with KTM](using-log-streams-with-ktm.md). + +**enlistment** +An *enlistment* is an association between a resource manager and a transaction. KTM provides a set of functions that resource managers call to create and manage enlistments. After a resource manager creates an enlistment, KTM sends notifications to the resource manager when the transaction's state changes. + +**transaction processing system** +A *transaction processing system* (TPS) is a collection of a transaction manager, one or more resource managers, one or more log streams, and one or more transactional clients that access the resource managers' resources. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Transaction%20Processing%20Terms%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/troubleshooting-specific-wmi-problems.md b/windows-driver-docs-pr/kernel/troubleshooting-specific-wmi-problems.md new file mode 100644 index 0000000000..5ce06bf1e0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/troubleshooting-specific-wmi-problems.md @@ -0,0 +1,82 @@ +--- +title: Troubleshooting Specific WMI Problems +author: windows-driver-content +description: Troubleshooting Specific WMI Problems +ms.assetid: 966191e7-aec4-4eff-b975-99a6d3eb8d02 +keywords: ["WMI WDK kernel , troubleshooting", "troubleshooting WMI problems WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Troubleshooting Specific WMI Problems + + +## + + +### Driver's WMI Classes Do Not Appear in the \\root\\wmi Namespace + +1. Use [wmimofck](using-wmimofck-exe.md)driver.bmf to check if the binary MOF file format is correct. Additional error messages may be found in mofcomp.log. + +2. Check the [system event log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-irps-and-the-system-event-log-kg) to see if the driver is returning a malformed [**WMIREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565832) data structure in response to the registration request. + +3. Check that the driver is returning the correct values for **RegistryPath** and **MofResourceName** within the **WMIREGINFO** structure. + +4. If the driver provides its MOF data in a separate file, check that the [MofImagePath](setting-the-mofimagepath-registry-value.md) registry value for the driver is set correctly. + +5. Check the [WMI WDM provider log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-wdm-provider-log-kg) for errors. + +6. Use [Mofcomp](compiling-a-driver-s-mof-file.md) to recompile and reload your MOF text file. For example, the command **mofcomp -N:root/wmi driver.mof** will try to recompile and reload any MOF data in the driver.mof file. Check to see what error messages Mofcomp generates in mofcomp.log. (Note that if your MOF file uses preprocessor directives such as **\#define**, you will need to use the already-preprocessed MOF file, and not the original source file. + + **Warning**  If this operation succeeds, it actually registers the new WMI class data with the system. You will need to delete these classes (by using Wbemtest, for example) to test if your driver's MOF data is being read correctly. + +   + +7. If the previous step succeeds, then the most likely problem is that the members of **WMIREGINFO**, such as **MofResourceName**, are specified incorrectly. Alternatively, the problem could be that your MOF file specifies a class derived from a base class that does not exist. + +8. If the driver is using dynamic MOF data (see [Implementing Dynamic MOF Data](implementing-dynamic-mof-data.md)), check that the driver is receiving WMI IRP requests for the MSWmi\_MofData\_GUID GUID and that it is completing the IRP successfully and with no error logged. + +### Driver's WMI Properties or Methods Cannot Be Accessed + +1. Use **wmimofck driver.bmf** to check if the binary MOF file format is correct. For more information, see [Using wmimofck.exe](using-wmimofck-exe.md). + +2. Check the system event log for errors. For more information, see [WMI IRPs and the System Event Log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-irps-and-the-system-event-log-kg). + +3. Check the [WMI WDM Provider Log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-wdm-provider-log-kg) for errors. + +4. Make sure the driver receives a WMI IRP whenever you use Wbemtest to query the driver's classes. If not, then check that the specified GUID in the MOF file matches the GUID the driver is expecting. Also check that the driver is receiving the WMI registration request, that it is succeeding, and the driver is registering the right GUIDs. + +5. If the driver receives the IRP, ensure that the IRP is completed successfully, and that the driver is returning the right type of **WNODE\_*XXX*** structure. + +6. If Wbemtest returns an error, click the **More Information** button and check the **Description** property for a description of the error. + +7. For methods, check that your driver supports handling the [**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) and [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) requests for the method's GUID. WMI will always perform one of those two requests before executing a method. + +### Driver's WMI Events Are Not Being Received + +1. Check the [system event log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-irps-and-the-system-event-log-kg) for errors. For example, if the driver specifies a static event name when calling [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) but the driver did not register any static event names, this would produce an entry in the system event log. + +2. Check the [WMI WDM provider log](general-techniques-for-testing-wmi-driver-support.md#ddk-wmi-wdm-provider-log-kg) for errors. + +3. If the driver is sending an event reference, the driver should receive an [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) request immediately after sending the event reference. If the driver does not receive the IRP, the [**WNODE\_EVENT\_REFERENCE**](https://msdn.microsoft.com/library/windows/hardware/ff566374) structure may have been malformed. If the driver receives the IRP, it should be completing it with status STATUS\_SUCCESS. + +4. If the driver uses [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) to send the event or event reference, make sure the event structure (either [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) or **WNODE\_EVENT\_REFERENCE**) is filled out correctly. In particular, if the event GUID is registered for static instance names, make sure that the correct instance index and provider ID are provided. If the event GUID is registered for dynamic instance names, make sure the instance name is included when the event is sent. If using the **WNODE\_EVENT\_REFERENCE** structure to specify the event, check that **Wnode.Guid** matches **TargetGuid**. + +5. If the driver uses [**WmiFireEvent**](https://msdn.microsoft.com/library/windows/hardware/ff565807) to send the event, make sure the correct value is passed for the *Guid* and *InstanceIndex* parameters. + +### Changes in Security Settings for WMI Requests Do Not Take Effect + +- Unload and reload the WMI WDM Provider. For WMI data blocks registered with the WMIREG\_FLAG\_EXPENSIVE flag, the provider keeps a handle open to the data block as long as there are consumers for that block. The new security settings will not take effect until the provider closes the handle. Unloading and reloading the provider makes sure the handle has been closed. (For more information about the WMIREG\_FLAG\_EXPENSIVE flag, see [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827).) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Troubleshooting%20Specific%20WMI%20Problems%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/types-of-apcs.md b/windows-driver-docs-pr/kernel/types-of-apcs.md new file mode 100644 index 0000000000..e799b585a2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/types-of-apcs.md @@ -0,0 +1,35 @@ +--- +title: Types of APCs +author: windows-driver-content +description: Types of APCs +ms.assetid: 74ed953c-1b2a-40b9-9df3-16869b198b38 +keywords: ["asynchronous procedure calls WDK kernel", "APCs WDK kernel", "user APCs WDK kernel", "normal kernel APCs WDK kernel", "special kernel APCs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Types of APCs + + +An asynchronous procedure call (APC) is a function that executes asynchronously. APCs are similar to deferred procedure calls (DPCs), but unlike DPCs, APCs execute within the context of a particular thread. Drivers (other than file systems and file-system filter drivers) do not use APCs directly, but other parts of the operating system do, so you need to be aware of how APCs work. + +The Windows operating system uses three kinds of APCs: + +- *User APCs* run strictly in user mode and only when the current thread is in an alertable wait state. The operating system uses user APCs to implement mechanisms such as overlapped I/O and the **QueueUserApc** Win32 routine. + +- *Normal kernel APCs* run in kernel mode at IRQL = PASSIVE\_LEVEL. A normal kernel APC preempts all user-mode code, including user APCs. Normal kernel APCs are generally used by file systems and file-system filter drivers. + +- *Special kernel APCs* run in kernel mode at IRQL = APC\_LEVEL. A special kernel APC preempts user-mode code and kernel-mode code that executes at IRQL = PASSIVE\_LEVEL, including both user APCs and normal kernel APCs. The operating system uses special kernel APCs to handle operations such as I/O request completion. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Types%20of%20APCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/types-of-wdm-device-objects.md b/windows-driver-docs-pr/kernel/types-of-wdm-device-objects.md new file mode 100644 index 0000000000..ff7579488c --- /dev/null +++ b/windows-driver-docs-pr/kernel/types-of-wdm-device-objects.md @@ -0,0 +1,40 @@ +--- +title: Types of WDM Device Objects +author: windows-driver-content +description: Types of WDM Device Objects +ms.assetid: 89cc888d-3097-4637-96d2-6b9c59878d2f +keywords: ["functional device objects WDK kernel", "FDO WDK kernel", "physical device objects WDK kernel", "PDOs WDK kernel", "device objects WDK kernel , types", "filter DOs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Types of WDM Device Objects + + +## + + +There are three kinds of WDM device objects: + +1. Physical Device Object (PDO) – represents a device on a bus to a [bus driver](bus-drivers.md). + +2. Functional Device Object (FDO) – represents a device to a [function driver](function-drivers.md). + +3. Filter Device Object (filter DO) – represents a device to a [filter driver](filter-drivers.md). + +The three kinds of device objects are all of the type [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147), but are used differently and can have different device extensions. + +A driver adds itself to the stack of drivers that handle I/O for a device by creating a device object ([**IoCreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548397)) and attaching it to the device stack ([**IoAttachDeviceToDeviceStack**](https://msdn.microsoft.com/library/windows/hardware/ff548300)). **IoAttachDeviceToDeviceStack** determines the current top of the device stack and attaches the new device object to the top of the device stack. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Types%20of%20WDM%20Device%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/types-of-wdm-drivers.md b/windows-driver-docs-pr/kernel/types-of-wdm-drivers.md new file mode 100644 index 0000000000..b2165db526 --- /dev/null +++ b/windows-driver-docs-pr/kernel/types-of-wdm-drivers.md @@ -0,0 +1,68 @@ +--- +title: Types of WDM Drivers +author: windows-driver-content +description: There are three kinds of WDM drivers bus drivers, function drivers, and filter drivers. +ms.assetid: 86acc77e-816e-46c8-b63c-2bb10920acd6 +keywords: ["WDM drivers WDK kernel , types", "WDM drivers WDK kernel , layered drivers", "layered drivers WDK kernel", "driver layers WDK WDM", "bus drivers WDK WDM", "function drivers WDK WDM", "filter drivers WDK WDM", "WDM bus drivers WDK", "WDM function drivers WDK", "WDM filter drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Types of WDM Drivers + + +There are three kinds of WDM drivers: bus drivers, function drivers, and filter drivers. + +## + + +- A [bus driver](bus-drivers.md) drives an individual I/O bus device and provides per-slot functionality that is device-independent. Bus drivers also detect and report child devices that are connected to the bus. +- A [function driver](function-drivers.md) drives an individual device. +- A [filter driver](filter-drivers.md) filters I/O requests for a device, a class of devices, or a bus. + +In this context, a *bus* is any device to which other physical, logical, or virtual devices are attached; a bus includes traditional buses such as SCSI and PCI, as well as parallel ports, serial ports, and i8042 ports. + +It is important for driver developers to understand the different kinds of WDM drivers and to know which kind of driver they are writing. For example, whether a driver handles each [Plug and Play](implementing-plug-and-play.md) IRP and how to handle such IRPs depends on what kind of driver is being written (bus driver, function driver, or filter driver). + +### + +The following figure shows the relationship between the bus driver, function driver, and filter drivers for a device. + +![diagram illustrating possible driver layers](images/drvlyr.png) + +Each device typically has a bus driver for the parent I/O bus, a function driver for the device, and zero or more filter drivers for the device. A driver design that requires many filter drivers does not yield optimal performance. + +The drivers in the previous figure are the following: + +1. A *bus driver* services a bus controller, adapter, or bridge. Bus drivers are required drivers; there is one bus driver for each type of bus on a machine. Microsoft provides bus drivers for most common buses. IHVs and OEMs can provide other bus drivers. + +2. A *bus filter driver* typically adds value to a bus and is supplied by Microsoft or a system OEM. There can be any number of bus filter drivers for a bus. + +3. *Lower-level filter drivers* typically modify the behavior of device hardware. They are optional and are typically supplied by IHVs. There can be any number of lower-level filter drivers for a device. + +4. A *function driver* is the main driver for a device. A function driver is typically written by the device vendor and is required (unless the device is being used in [*raw mode*](https://msdn.microsoft.com/library/windows/hardware/ff556331#wdkgloss-raw-mode)). + +5. *Upper-level filter drivers* typically provide added-value features for a device. They are optional and are typically provided by IHVs. + +The following topics describe the three general types of WDM drivers—bus drivers, function drivers, filter drivers—in detail. Also included is an example of WDM driver layering that uses sample USB drivers. + +## In this section + + +- [Bus Drivers](bus-drivers.md) +- [Function Drivers](function-drivers.md) +- [Filter Drivers](filter-drivers.md) +- [WDM Driver Layers: An Example](wdm-driver-layers---an-example.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Types%20of%20WDM%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/types-of-windows-drivers.md b/windows-driver-docs-pr/kernel/types-of-windows-drivers.md new file mode 100644 index 0000000000..17d2b97288 --- /dev/null +++ b/windows-driver-docs-pr/kernel/types-of-windows-drivers.md @@ -0,0 +1,76 @@ +--- +title: Types of Windows Drivers +author: windows-driver-content +description: Types of Windows Drivers +ms.assetid: e6696c6b-2d3c-473c-9f46-576fe0c40496 +keywords: ["Windows drivers WDK , types", "drivers WDK , types", "kernel-mode drivers WDK , types", "highest-level drivers WDK", "intermediate drivers WDK kernel", "lowest-level drivers WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Types of Windows Drivers + + +## + + +There are two basic types of Microsoft Windows drivers: + +- *User-mode drivers* execute in user mode, and they typically provide an interface between a Win32 application and kernel-mode drivers or other operating system components. + + For example, in Windows Vista, all printer drivers execute in user mode. For more information about printer driver components, see [Introduction to Printing](https://msdn.microsoft.com/library/windows/hardware/ff551767). + +- *Kernel-mode drivers* execute in kernel mode as part of the executive, which consists of kernel-mode operating system components that manage I/O, Plug and Play memory, processes and threads, security, and so on. Kernel-mode drivers are typically layered. Generally, higher-level drivers typically receive data from applications, filter the data, and pass it to a lower-level driver that supports device functionality. + + Some kernel-mode drivers are also *WDM drivers*, which conform to the [Windows Driver Model](windows-driver-model.md) (WDM). All WDM drivers support Plug and Play, and power management. WDM drivers are source-compatible (but not binary-compatible) across Windows 98/Me and Windows 2000 and later operating systems. + + Like the operating system itself, kernel-mode drivers are implemented as discrete, modular components that have a well-defined set of required functionalities. All kernel-mode drivers supply a set of system-defined [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842). + +The following figure divides kernel-mode drivers into several types. + +![diagram illustrating types of kernel-mode drivers](images/1drvlyrs.png) + +As shown in the figure, there are three basic types of kernel-mode drivers in a driver stack: highest-level, intermediate, and lowest-level. Each type differs only slightly in structure but greatly in functionality: + +1. *Highest-level drivers*. Highest-level drivers include file system drivers (FSDs) that support file systems, such as: + + - NTFS + + - File allocation table (FAT) + + - CD-ROM file system (CDFS) + + Highest-level drivers always depend on support from underlying lower-level drivers, such as intermediate-level function drivers and lowest-level hardware bus drivers. + +2. *Intermediate drivers*, such as a virtual disk, mirror, or device-type-specific [*class driver*](https://msdn.microsoft.com/library/windows/hardware/ff556274#wdkgloss-class-driver). Intermediate drivers depend on support from underlying lower-level drivers. Intermediate drivers are subdivided further as follows: + + - [*Function drivers*](function-drivers.md) control specific peripheral devices on an I/O bus. + + - [*Filter drivers*](filter-drivers.md) insert themselves above or below function drivers. + + - *Software bus drivers* present a set of child devices to which still higher-level class, function, or filter drivers can attach themselves. + + For example, a driver that controls a multifunction adapter with an on-board set of heterogeneous devices is a software bus driver. + + - Any system-supplied *class driver* that exports a system-defined class/miniclass interface is, in effect, an intermediate driver with one or more linked *miniclass drivers* (sometimes called *minidrivers*). Each linked class/minidriver pair provides functionality that is equivalent to that of a function driver or a software bus driver. + +3. *Lowest-level drivers* control an I/O bus to which peripheral devices are connected. Lowest-level drivers do not depend on lower-level drivers. + + - Hardware [*bus drivers*](bus-drivers.md) are system-supplied and usually control dynamically configurable I/O buses. + + Hardware bus drivers work with the Plug and Play manager to configure and reconfigure system hardware resources, for all child devices that are connected to the I/O buses that the driver controls. These hardware resources include mappings for device memory and interrupt requests (IRQs). (Hardware bus drivers subsume some of the functionality that the HAL component provided in releases of the Windows NT-based operating system earlier than Windows 2000.) + + - [*Legacy drivers*](https://msdn.microsoft.com/library/windows/hardware/ff556305#wdkgloss-legacy-driver) that directly control a physical device are lowest-level drivers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Types%20of%20Windows%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/understanding-the-path-of-wait-wake-irps-through-a-device-tree.md b/windows-driver-docs-pr/kernel/understanding-the-path-of-wait-wake-irps-through-a-device-tree.md new file mode 100644 index 0000000000..ddd44a69c4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/understanding-the-path-of-wait-wake-irps-through-a-device-tree.md @@ -0,0 +1,100 @@ +--- +title: Understanding the Path of Wait/Wake IRPs through a Device Tree +author: windows-driver-content +description: Understanding the Path of Wait/Wake IRPs through a Device Tree +ms.assetid: 35118367-d20b-45c9-a296-656028339c59 +keywords: ["wait/wake IRPs WDK power management , device tree path", "bus drivers WDK power management", "USB WDK power management", "function drivers WDK power management", "FDOs WDK power management", "filter DOs WDK power management", "physical device objects WDK power management", "PDOs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Understanding the Path of Wait/Wake IRPs through a Device Tree + + +## + + +Within a single device stack, the power policy owner sends a wait/wake IRP and all drivers handle the wait/wake IRP, as outlined in [Overview of Wait/Wake Operation](overview-of-wait-wake-operation.md) and detailed in [Sending a Wait/Wake IRP](sending-a-wait-wake-irp.md) and [Receiving a Wait/Wake IRP](receiving-a-wait-wake-irp.md), respectively. + +Within a branch of the [device tree](device-tree.md) (which comprises a leaf devnode and the devnodes of its parents, grandparents, and so forth), drivers must cooperate to ensure that a wait/wake IRP reaches a driver that can enable all the necessary hardware for wake-up. + +On ACPI computers, ACPI is responsible for enabling the system-specific General Purpose Event (GPE) register associated with the wake-up signal from each leaf device. Consequently, drivers must request and forward wait/wake IRPs until one reaches either an ACPI filter driver (inserted in the device stack at start-up) or the underlying [Windows ACPI driver](acpi-driver.md), Acpi.sys. In response, ACPI enables the register, holds the IRP pending until the signal arrives, and then completes the IRP. Because ACPI can respond to the wake-up signal, it does not forward the IRP to a lower driver. + +ACPI filter drivers, like the underlying ACPI driver itself, are transparent to other drivers. To provide maximum flexibility in hardware design, the exact position of an ACPI filter driver in any device stack is device- and system-specific. In designing a driver, you cannot make any assumptions about the presence or position of an ACPI filter in the device stack. + +Keep in mind that drivers that enumerate children create a PDO for each child device and an FDO for the parent device. The driver thus acts as the bus driver for a child device and the function driver/policy owner for a parent device. Therefore, whenever a bus driver receives a wait/wake IRP for a child PDO, it should request another wait/wake IRP for its parent PDO. + +### + +The following figure shows a sample configuration in which such a situation occurs. + +![diagram illustrating a sample usb configuration](images/wwhw.png) + +In the sample configuration, the keyboard and modem are children of the USB hub, which in turn is a child of the USB host controller, which is enumerated by the PCI bus. The following figure shows the device stacks for the keyboard in the sample configuration. + +![diagram illustrating device stacks for the sample usb keyboard configuration](images/wwdobj.png) + +As the previous figure shows, reading from the bottom up: + +1. The [Windows ACPI driver](acpi-driver.md), Acpi.sys, creates the PDO for PCI. + +2. The PCI driver creates the PCI FDO and the USB host controller PDO and owns policy for the PCI device stack. + +3. The USB host controller driver (a host port/miniport driver pair) creates the USB Host Controller FDO and the USB Hub PDO. It owns policy for the USB host controller device stack. Note that Acpi.sys creates a filter DO in this stack as well. + +4. The USB hub driver creates the USB Hub FDO and the keyboard PDO. This driver owns power policy for the USB hub device stack. + +5. The function driver for the keyboard is the USB HID class driver/minidriver pair. This driver creates the FDO for the keyboard and owns its power policy. Because the keyboard has no child devices, this driver creates no PDOs. + +Note that each device stack might include additional optional filter DOs that are not shown. + +To allow keyboard input to awaken the system, the policy owner for the keyboard requests an **IRP\_MN\_WAIT\_WAKE** for its PDO. That IRP sets off a chain of other wait/wake IRPs, as shown in the following figure. + +![wait/wake irp requests for sample usb configuration](images/wwcascade.png) + +When a bus driver receives an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) targeted to a PDO it created, it must request another **IRP\_MN\_WAIT\_WAKE** for the device stack for which it owns power policy and created an FDO. + +As the previous figure shows: + +1. The keyboard driver calls [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send a wait/wake IRP (IRP1) to its PDO. + + The power manager allocates the IRP and sends it through the I/O manager to the top of the device stack for the keyboard. Drivers set [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines and pass the IRP down the stack until it reaches the keyboard PDO. The USB hub driver, which acts as the bus driver for the keyboard, holds IRP1 pending. + +2. Because the USB hub driver cannot wake the system when the wake-up signal arrives, the USB hub driver must call **PoRequestPowerIrp** to request a wait/wake IRP (IRP2) for the USB hub device stack. + + The power manager sends this IRP to the top of the USB hub device stack. The drivers in this stack set *IoCompletion* routines and pass the IRP down to the USB host controller driver (which acts as the bus driver for the USB hub). The USB host controller driver holds IRP2 pending until the keyboard signals a wake event. + +3. Similarly, the USB host controller driver cannot wake the system, so the USB host controller driver calls **PoRequestPowerIrp** to send a wait/wake IRP (IRP3) to the USB host controller device stack. + + The power manager sends this IRP to the top of the USB host controller device stack, where drivers set *IoCompletion* routines and pass the IRP down to the PCI driver (which acts as the bus driver for the USB hub). The PCI driver holds IRP3 pending until the keyboard signals a wake event. + +4. The PCI driver cannot wake the system, so the PCI driver calls **PoRequestPowerIrp** to send a wait/wake IRP (IRP4) to the PCI device stack. Its parent is the root device, for which ACPI is the bus driver. + + The power manager sends the IRP to the top of the PCI bus device stack; its drivers set completion routines and pass the IRP down to the [Windows ACPI driver](acpi-driver.md), Acpi.sys. + +5. Acpi.sys can wake the system, so it does not send a wait/wake IRP to any other PDO. Acpi.sys holds IRP4 pending until a wake signal arrives. + +When the keyboard asserts the wake-up signal, Acpi.sys intercepts it. ACPI, however, cannot determine that the keyboard asserted the signal, only that the signal came through the root device. Acpi.sys then completes IRP4, and the I/O manager calls *IoCompletion* routines traveling back up the PCI device stack. When IRP4 is complete and all *IoCompletion* routines have run, the PCI driver's callback routine is invoked. In its callback routine, the PCI driver determines that the signal came through the USB host controller. The PCI driver then completes IRP3. The same sequence occurs through the USB host controller stack and the USB hub stack, until the keyboard driver receives IRP1. At this point, the keyboard driver can service the wake-up event, as necessary. + +Each time a driver sends a wait/wake IRP to a parent PDO, it must set a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for its own IRP. Setting a *Cancel* routine gives the driver an opportunity to cancel the new IRP if the IRP that triggered it is canceled. In the USB example, if the keyboard driver cancels its wait/wake IRP (thus disabling keyboard wake-up), the USB hub, USB host controller, and PCI drivers must cancel the IRPs that they sent as a consequence of the keyboard IRP. For more information, see [Cancel Routines for Wait/Wake IRPs](canceling-a-wait-wake-irp.md#ddk-cancel-routines-for-wait-wake-irps-kg). + +Although a parent driver might enumerate more than one child that can be enabled for wait/wake, only one wait/wake IRP can be pending for a PDO. In such cases, the parent driver should make sure that it keeps a wait/wake IRP pending whenever any of its devices is enabled for wake-up. To do so, the driver increments an internal counter each time it receives a wait/wake IRP. Each time the driver completes a wait/wake IRP, it decrements the count and, if the resulting value is nonzero, sends another wait/wake IRP to its device stack. + +For example, in the USB configuration shown previously in the [Sample USB Configuration](#sample-usb-configuration) figure, the USB hub enumerates two devices, a keyboard and a modem. When the USB hub driver receives a wait/wake IRP for the keyboard PDO, it increments a count of wait/wake IRPs before requesting an IRP for its own PDO. If the modem's policy owner later enables wake-up for the modem, the USB hub driver pends the new IRP for the modem PDO and increments its wait/wake reference count. However, because the USB hub PDO cannot have two simultaneously pending wait/wake IRPs, the USB hub driver does not request a new wait/wake IRP for the USB hub PDO. + +When a wake-up signal arrives from either the keyboard or modem, the USB hub driver determines which device signaled, completes the corresponding IRP, and decrements its reference count. Because both devices were enabled for wake-up (and thus its reference count is nonzero), it must send its own device stack another wait/wake IRP to "rearm" its own PDO for wake-up. (The same is true of the USB host controller and PCI driver.) + +A driver does not, however, send itself an IRP to reenable wait/wake on the same device on which a wake-up signal just arrived. Only the device power policy manager can do that. Reenabling wait/wake is not automatic. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Understanding%20the%20Path%20of%20Wait/Wake%20IRPs%20through%20a%20Device%20Tree%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/understanding-tps-components.md b/windows-driver-docs-pr/kernel/understanding-tps-components.md new file mode 100644 index 0000000000..54fae2cf74 --- /dev/null +++ b/windows-driver-docs-pr/kernel/understanding-tps-components.md @@ -0,0 +1,163 @@ +--- +title: Understanding TPS Components +author: windows-driver-content +description: Understanding TPS Components +ms.assetid: 4bc962fa-8c05-4b0f-b634-9c0f435907b7 +keywords: ["transaction processing systems WDK KTM , components", "TPS WDK KTM , components", "transaction processing systems WDK KTM , scenarios", "TPS WDK KTM , scenarios", "resource managers WDK KTM , in a TPS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Understanding TPS Components + + +Any [*transaction processing system*](transaction-processing-terms.md#ktm-term-transaction-processing-system) (TPS) that uses the Kernel Transaction Manager (KTM) and the [Common Log File System](using-common-log-file-system.md) (CLFS) should contain the following important components: + +- A [*transaction manager*](transaction-processing-terms.md#ktm-term-transaction-manager) (KTM) + + KTM tracks the state of each transaction and coordinates recovery operations after a system crash. + +- One or more [*resource managers*](transaction-processing-terms.md#ktm-term-resource-manager) + + Resource managers, which you provide, manage the data that is associated with each transaction. + +- One or more CLFS [*log streams*](transaction-processing-terms.md#ktm-term-log-stream) + + The transaction manager and resource managers use CLFS log streams to record information that can be used to commit, roll back, or recover a transaction. + +- One or more [*transactional clients*](transaction-processing-terms.md#ktm-term-transactional-client) + + Typically, each transactional client of your TPS can create a transaction, perform operations on data within the context of the transaction, and then initiate either a commit or rollback operation for the transaction. + +This topic introduces you to a [simple TPS](#simple-tps) with one resource manager, a more complex TPS that contains [multiple resource managers](#multiple-resource-managers-in-a-tps), and some [other TPS scenarios](#other-tps-scenarios). + +The [Using KTM](using-ktm.md) section provides detailed information about how to use KTM to create TPS components. + +### Simple TPS + +A simple TPS might consist of KTM, one resource manager, and CLFS. Transactional clients can communicate with the resource manager by an interface that the resource manager provides. + +For example, suppose that you want to create a database management system. You want your system's clients to access the database by opening a handle to a database object, performing read and write operations on the object, and then closing the object handle. + +Now suppose that you want sets of read and write operations to occur atomically so that other users of the system see only the final result. You can achieve that goal by designing a TPS that enables clients to bind sets of database operations to a transaction. + +Your system should include a resource manager that manages the data in the database in response to read and write requests from clients. This resource manager could export an application programming interface (API) that enables clients to associate a transaction with a set of read and write operations. + +When your resource manager is loaded, it must register itself with KTM by calling [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430) and [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427). Then, the resource manager can participate in transactions. + +You might want your resource manager to support a set of functions that enable clients to create data objects, read and write data that is associated with the data objects, and close the data objects. The following pseudocode shows an example code sequence from a client. + +``` +CreateDataObject (IN TransactionID, OUT DataHandle); +ReadData (IN DataHandle, OUT Data); +WriteData (IN DataHandle, IN Data); +WriteData (IN DataHandle, IN Data); +WriteData (IN DataHandle, IN Data); +CloseDataObject (IN DataHandle); +``` + +Before a client can call your resource manager's *CreateDataObject* routine, the client must create a transaction object by calling KTM's [**ZwCreateTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566429) routine and obtain the transaction object's identifier by calling [**ZwQueryInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567057). + +When the client calls your resource manager's *CreateDataObject* routine, the client passes the transaction object's identifier to the resource manager. The resource manager can call [**ZwOpenTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567033) to obtain a handle to the transaction object, and then it can call [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) to register its participation in the transaction. + +At this point, the client can start performing operations on the data object. Because the client provided a transaction identifier when it created the data object, the resource manager can assign all the read and write operations to the transaction. + +Your resource manager must record all the results of data operations that the client specifies without making the results permanent. Typically, the resource manager uses CLFS to record the operation results in a transaction log stream. + +When the client has finished calling the resource manager to perform transactional operations, it calls KTM's [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) routine. At this point, KTM [notifies](transaction-notifications.md) the resource manager that it should make the operations permanent. The resource manager then moves the operation results from the log stream to the data's permanent storage medium. Finally, the resource manager calls [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418) to inform KTM that the commit operation is complete. + +What happens if your resource manager reports an error for one of the client's calls to *ReadData* or *WriteData*? The client can call [**ZwRollbackTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567086) to roll back the transaction. As a result of that call, KTM notifies the resource manager that it should restore the data to its original state. Then, the client can either create a new transaction for the same operations, or it can choose to not continue. + +The following pseudocode shows an example of a more detailed sequence of a client's transactional operations. + +``` + ZwCreateTransaction (&TransactionHandle, ...); + ZwQueryInformationTransaction (TransactionHandle, ...); + CreateDataObject (TransactionID, &DataHandle); + Status = ReadData (DataHandle, &Data1); + if (Status == Error) goto ErrorRollback; + Status = WriteData (DataHandle, Data2); + if (Status == Error) goto ErrorRollback; + Status = WriteData (DataHandle, Data3); + if (Status == Error) goto ErrorRollback; + Status = WriteData (DataHandle, Data4); + if (Status == Error) goto ErrorRollback; + ZwCommitTransaction (TransactionHandle, ...); + goto Leave; +ErrorRollback: + ZwRollbackTransaction (TransactionHandle, ...); +Leave: + ZwClose (TransactionHandle); + return; +``` + +What happens if the system crashes after the transaction is created but before it is committed or rolled back? Every time that your resource manager loads, it should call [**ZwRecoverTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567079) and [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078). Calling **ZwRecoverTransactionManager** causes KTM to open its log stream and read the transaction history. Calling **ZwRecoverResourceManager** causes KTM to notify the resource manager of any enlisted transactions that were in progress before the crash and which transactions the resource manager must therefore recover. + +If a transactional client called [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420) for a transaction before the crash, and began to handle commit operations for the transaction, the resource manager must be able to restore the transaction's state to the point immediately prior to the crash. If the client was not ready to commit the transaction before the crash, the resource manager can discard the data and roll back the transaction. + +For more information about how to write transactional clients, see [Creating a Transactional Client](creating-a-transactional-client.md). + +For more information about how to write resource managers, see [Creating a Resource Manager](creating-a-resource-manager.md). + +### Multiple Resource Managers in a TPS + +Now suppose that your TPS enables clients to modify information in two separate databases within a single transaction, so that the transaction succeeds only if the modifications of both databases succeed. + +In this case, your TPS can have two resource managers, one for each database. Each resource manager can export an API that clients can use to access the resource manager's database. + +The following pseudocode shows how a client might create a single transaction that contains operations on two databases that two resource managers support. + +In this example, the client reads data from the first database and writes it to the second database. Then, the client reads data from the second database and writes it to the first database. (The first resource manager exports functions that begin with **Rm1**, and the second resource manager exports functions that begin with **Rm2**.) + +``` + ZwCreateTransaction (&TransactionHandle, ...); + ZwQueryInformationTransaction (TransactionHandle, ...); + Rm1CreateDataObject (TransactionID, &Rm1DataHandle); + Rm2CreateDataObject (TransactionID, &Rm2DataHandle); + Status = Rm1ReadData (Rm1DataHandle, &Rm1Data); + if (Status == Error) goto ErrorRollback; + Status = Rm2WriteData (Rm2DataHandle, Rm1Data); + if (Status == Error) goto ErrorRollback; + Status = Rm2ReadData (Rm2DataHandle, &Rm2Data); + if (Status == Error) goto ErrorRollback; + Status = Rm1WriteData (Rm1DataHandle, Rm2Data); + if (Status == Error) goto ErrorRollback; + ZwCommitTransaction (TransactionHandle, ...); + goto Leave; +ErrorRollback: + ZwRollbackTransaction (TransactionHandle, ...); +Leave: + ZwClose (TransactionHandle); + return; +``` + +Because the client passes the same transaction identifier to both resource managers, both resource managers can call [**ZwOpenTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567033) and [**ZwCreateEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566422) to enlist in the transaction. When the client eventually calls [**ZwCommitTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff566420), KTM [notifies](transaction-notifications.md) each resource manager that the manager should make the operations permanent, and each resource manager calls [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418) when it has finished. + +### Other TPS Scenarios + +KTM supports other TPS scenarios. For example, the following scenarios describe components that a TPS might contain: + +- One resource manager that manages multiple databases. + + The resource manager's API could enable clients to open and access more than one database at a time, and the client could combine accesses to multiple databases in a single transaction. + +- One resource manager with an API that clients call, and additional resource managers with APIs that the first resource manager calls. + + The client communicates only with the first resource manager. When that resource manager processes requests from a client, it can access the additional resource managers, as needed, to process the client's requests. For example, a resource manager manages a client-accessible database that requires backup or data verification operations from a second resource manager that is not available to clients. + +- An existing client and resource manager that do not use KTM, integrated with an additional set of resource managers that do use KTM. + + In this case, you typically have to modify the existing resource manager so that it becomes a [superior transaction manager](creating-a-superior-transaction-manager.md) that communicates with KTM. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Understanding%20TPS%20Components%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/understanding-when-remove-irps-are-issued.md b/windows-driver-docs-pr/kernel/understanding-when-remove-irps-are-issued.md new file mode 100644 index 0000000000..9a790c90af --- /dev/null +++ b/windows-driver-docs-pr/kernel/understanding-when-remove-irps-are-issued.md @@ -0,0 +1,90 @@ +--- +title: Understanding When Remove IRPs Are Issued +author: windows-driver-content +description: Understanding When Remove IRPs Are Issued +ms.assetid: e92e30ce-ca0d-4f00-b54a-778bafba15b3 +keywords: ["remove IRPs WDK PnP", "IRPs WDK PnP", "I/O request packets WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Understanding When Remove IRPs Are Issued + + +## + + +The following figure shows the typical sequence of IRPs involved in removing the drivers for a device. + +![diagram illustrating typical remove irp transitions](images/rem-irps.png) + +The following notes correspond to the circled numbers in the previous figure: + +1. Query remove + + The PnP manager issues an [**IRP\_MN\_QUERY\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551705) to ask whether a device can be removed without disrupting the machine. It also sends this IRP when a user requests to update driver(s) for the device and (on Windows 2000 and later) when Device Manager disables the device. (On Windows 98/Me, the PnP manager sends stop IRPs in this situation; see [Stopping a Device](stopping-a-device.md) for details.) + + If all drivers in the device stack return STATUS\_SUCCESS, the drivers have put the device into the remove-pending state. In this state, the drivers must not start any operations that prevent the device from being removed. + + In this "clean" removal case, the PnP manager sends a query-remove IRP before it sends a remove IRP. See step 5 for a description of "surprise" removal. + + Although it is not shown in the above diagram, a bus driver might receive an **IRP\_MN\_QUERY\_REMOVE\_DEVICE** for a device that is not started. This can happen if a user requests to dynamically remove a device that is physically present on the machine but is disabled. + +2. Remove after successful query + + The PnP manager issues an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) to remove the drivers for a device. + + Drivers must succeed this request. The drivers for the device perform any necessary clean-up, detach from the device stack, and delete the FDO and any filter DOs. The parent bus driver retains the PDO until the user physically removes the device from the machine. + + Note that drivers might receive an [**IRP\_MN\_STOP\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551755) prior to a remove IRP, but it is not required. On Windows 2000 and later, **IRP\_MN\_STOP\_DEVICE** is used only to pause a device for resource rebalancing; it is not a step toward removal. If a user removes the device hardware while the device is stopped, the PnP manager sends a remove IRP at some point after the stop IRP, but a stop is not a prerequisite for a remove. + +3. Reenumerate the device + + If the device is reenumerated after drivers have deleted their device objects, the PnP manager calls the drivers' [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routines and issues an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) to reinstate the device. (Also see the [Device States from the PnP Perspective](state-transitions-for-pnp-devices.md#ddk-state-transitions-for-pnp-devices-kg) figure.) + +4. Cancel a query remove + + The PnP manager issues an [**IRP\_MN\_CANCEL\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff550823) to cancel a query-remove request. + + In response to an **IRP\_MN\_CANCEL\_REMOVE\_DEVICE**, the drivers return the device to its started state. + +5. Surprise remove (Windows 2000 and later versions of Windows) + + On Windows 2000 and later systems, if a user unplugs a device from the machine without using the Unplug or Eject Hardware program, the PnP manager sends an [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) IRP. + + This case is called "surprise" removal because the drivers receive no advance warning. + + In response to an **IRP\_MN\_SURPRISE\_REMOVAL** IRP, the drivers for the device fail any outstanding I/O and release the hardware resources used by the device. The drivers must ensure that no components attempt to access the device because it is no longer present. + + All drivers must handle an **IRP\_MN\_SURPRISE\_REMOVAL** IRP and must set status to STATUS\_SUCCESS. + + An **IRP\_MN\_SURPRISE\_REMOVAL** cannot be canceled. + +6. Remove after surprise remove (Windows 2000 and later versions of Windows) + + When all open handles to the device are closed, the PnP manager sends an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request to the drivers for the device. Each driver detaches from the device stack and deletes its device object. + +7. Surprise remove (Windows 98/Me) + + On Windows 98/Me, a driver does not receive an [**IRP\_MN\_SURPRISE\_REMOVAL**](https://msdn.microsoft.com/library/windows/hardware/ff551760) when a device is removed without warning. The PnP manager sends only an **IRP\_MN\_REMOVE\_DEVICE**. WDM drivers must have code to handle both an **IRP\_MN\_SURPRISE\_REMOVAL** followed by an **IRP\_MN\_REMOVE\_DEVICE** (the Windows 2000 and later behavior for surprise removal) and an **IRP\_MN\_REMOVE\_DEVICE** without a prior surprise-remove IRP (the Windows 98/Me behavior). + +8. Remove after a failed start (Windows 2000 and later) + + If one of the drivers for a device fails an **IRP\_MN\_START\_DEVICE**, the PnP manager sends an **IRP\_MN\_REMOVE\_DEVICE** request to the device stack. Such a remove IRP ensures that all drivers for the device are notified that the device was not successfully started. In response to the **IRP\_MN\_REMOVE\_DEVICE** IRP, the drivers for the device undo their start operations (if they succeeded the start IRP) and undo their *AddDevice* operations. The PnP manager marks such a device as "failed start." + + This behavior applies to Windows 2000 and later platforms only. On Windows 98/Me, the PnP manager sends an **IRP\_MN\_STOP\_DEVICE** in response to a failed start. + +A driver for a PnP device can receive an **IRP\_MN\_SURPRISE\_REMOVAL** in more situations than those shown in the figure illustrating typical remove IRP transitions. For example, a user could insert a PC Card into the machine and then remove it before the device is started. In that case, the PnP manager issues a surprise-remove IRP after the drivers' *AddDevice* routines are called but before issuing the **IRP\_MN\_START\_DEVICE** request. A driver for a PnP device must be prepared to handle remove IRPs at any time after the driver's *AddDevice* routine is called. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Understanding%20When%20Remove%20IRPs%20Are%20Issued%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/unload-routine-environment.md b/windows-driver-docs-pr/kernel/unload-routine-environment.md new file mode 100644 index 0000000000..01ef539d31 --- /dev/null +++ b/windows-driver-docs-pr/kernel/unload-routine-environment.md @@ -0,0 +1,44 @@ +--- +title: Unload Routine Environment +author: windows-driver-content +description: Unload Routine Environment +ms.assetid: 4acf66f1-7b97-494e-9f84-14292e971542 +keywords: ["Unload routines WDK kernel , environment"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Unload Routine Environment + + +## + + +The operating system unloads a driver when the driver is being replaced or when all of the devices that the driver services have been removed. The PnP manager calls a PnP driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine if the driver has no more device objects after it handles an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request. + +At the start of the unloading sequence, the I/O manager or PnP manager marks the driver object and its device objects as "Unload Pending". After a driver has been marked as "Unload Pending", no additional drivers can attach to that driver, nor can any additional references be made to the driver's device objects. The driver can complete outstanding IRPs, but the system will not send any new IRPs to the driver. + +The I/O manager calls a driver's *Unload* routine when all of the following are true: + +- No references remain to any of the device objects the driver has created. In other words, no files associated with the underlying device can be open, nor can any IRPs be outstanding for any of the driver's device objects. + +- No other drivers remain attached to this driver. + +- The driver has called [**IoUnregisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff550398) to unregister all PnP notifications for which it previously registered. + +Note that the *Unload* routine is not called if a driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine returns a failure status. In this case, the I/O manager simply frees the memory space taken up by the driver. + +Neither the PnP manager nor the I/O manager calls *Unload* routines at system shutdown time. A driver that must perform shutdown processing should register a [*DispatchShutdown*](https://msdn.microsoft.com/library/windows/hardware/ff543405) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Unload%20Routine%20Environment%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/unload-routine-functionality.md b/windows-driver-docs-pr/kernel/unload-routine-functionality.md new file mode 100644 index 0000000000..ba49252eb6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/unload-routine-functionality.md @@ -0,0 +1,34 @@ +--- +title: Unload Routine Functionality +author: windows-driver-content +description: Unload Routine Functionality +ms.assetid: a36b4687-df1d-498f-b9f3-d13ae2a9a3cd +keywords: ["Unload routines WDK kernel , functionality"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Unload Routine Functionality + + +## + + +The responsibilities of a driver's [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine depend on whether the driver supports PnP or not. + +Just as the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routines of PnP drivers are usually simple, so are their *Unload* routines, as described in [A PnP Driver's Unload Routine](pnp-driver-s-unload-routine.md). + +A non-PnP driver's *Unload* routine must free device objects and release driver-allocated resources. In short, it must undo the work performed by its corresponding **DriverEntry** and [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routines in initializing the driver, its devices, and its resources. See [A Non-PnP Driver's Unload Routine](non-pnp-driver-s-unload-routine.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Unload%20Routine%20Functionality%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/updating-wmi-registration-information.md b/windows-driver-docs-pr/kernel/updating-wmi-registration-information.md new file mode 100644 index 0000000000..9a463192d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/updating-wmi-registration-information.md @@ -0,0 +1,52 @@ +--- +title: Updating WMI Registration Information +author: windows-driver-content +description: Updating WMI Registration Information +ms.assetid: d24688e5-bb50-4bce-a4d4-4a3bf886f86d +keywords: ["WMI WDK kernel , registering with WMI", "registering WMI data providers", "data providers WDK WMI", "driver registrations WDK WMI", "event blocks WDK WMI", "blocks WDK WMI", "registering blocks", "updating WMI registration information"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Updating WMI Registration Information + + +## + + +After its initial registration with WMI, a driver changes its registration information by calling [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) with one of the following actions: + +- WMIREG\_ACTION\_REREGISTER to replace all registration information previously supplied by the driver with new information. + + In response, WMI sends either an [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) request or an [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request to the driver, with **Parameters.WMI.DataPath** set to WMIREGISTER. (On Windows 98 and Windows 2000, the system sends the **IRP\_MN\_REGINFO** request. On Windows XP and later, the system sends the **IRP\_MN\_REGINFO\_EX** request.) + + The driver supplies WMI with new registration information for all blocks it supports, as described in [Using the WMI Library to Register Blocks](using-the-wmi-library-to-register-blocks.md) and [Handling IRP\_MN\_REGINFO and IRP\_MN\_REGINFO\_EX to Register Blocks](handling-irp-mn-reginfo-and-irp-mn-reginfo-ex-to-register-blocks.md). + +- WMIREG\_ACTION\_UPDATE\_GUIDS to add or remove support for blocks or to change the static instance names of registered blocks. + + In response, WMI sends an [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) request to the driver, with **Parameters.Wmi.DataPath** set to WMIUPDATE. + + The driver supplies WMI with an updated registration information in which: + + - The driver sets WMIREG\_FLAG\_REMOVE\_GUID to remove support for that block. + + - The driver clears WMIREG\_FLAG\_REMOVE\_GUID to add a new block or update an existing block. + + - The driver sets or clears WMIREG\_FLAG\_INSTANCE\_*XXX* and supplies any necessary instance name information to change a block's static instance names or change it to use dynamic instance names. + +- WMIREG\_ACTION\_DEREGISTER to instruct WMI that the driver will no longer provide WMI information. + + WMI does not send an **IRP\_MN\_REGINFO** or **IRP\_MN\_REGINFO\_EX** request in response to this call, because it requires no further information from the driver. A driver typically deregisters its blocks in response to an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request. Note that the deregister call will block until all WMI IRPs to the device have been completed. If a driver queues WMI IRPs, it must cancel them before calling [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480) to deregister. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Updating%20WMI%20Registration%20Information%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-customtimerdpc-routine.md b/windows-driver-docs-pr/kernel/using-a-customtimerdpc-routine.md new file mode 100644 index 0000000000..317302579f --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-customtimerdpc-routine.md @@ -0,0 +1,64 @@ +--- +title: Using a CustomTimerDpc Routine +author: windows-driver-content +description: Using a CustomTimerDpc Routine +ms.assetid: e95d01a2-4d13-40d2-aeb0-44c45e4a49f5 +keywords: ["timer objects WDK kernel , CustomTimerDpc routines", "CustomTimerDpc", "disabling timer objects", "timer objects WDK kernel , disabling", "periodic timers WDK kernel", "queuing timer objects", "timer objects WDK kernel , expirations", "timer expirations WDK kernel", "expired timers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a CustomTimerDpc Routine + + +## + + +To disable a previously set timer object, a driver calls [**KeCancelTimer**](https://msdn.microsoft.com/library/windows/hardware/ff551970). This routine removes the timer object from the system's timer queue. Generally, the timer object is not set to the signaled state and the *CustomTimerDpc* routine is not queued for execution. However, if the timer is about to expire when **KeCancelTimer** is called, expiration might occur before **KeCancelTimer** has a chance to access the time queue, in which case signaling and DPC queuing will occur. + +Recalling [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) or [**KeSetTimerEx**](https://msdn.microsoft.com/library/windows/hardware/ff553292), with previously specified *Timer* and *Dpc* pointers, before the previously specified interval expires, has the following effects: + +- The kernel removes the timer object from the timer queue, without setting the object to the signaled state or queuing the *CustomTimerDpc* routine. + +- The kernel reinserts the timer object in the timer queue, using the new *DueTime* value. + +Using the same timer object for different purposes can cause race conditions or serious driver errors. For example, assume that a driver specifies a single timer object both to set up a call to a *CustomTimerDpc* routine and to set up waits in a driver-dedicated thread. Whenever the driver-dedicated thread calls **KeSetTimer**, **KeSetTimerEx**, or **KeCancelTimer** for the common timer object, the thread would cancel calls to the *CustomTimerDpc* routine, if the timer object was already queued for a *CustomTimerDpc* call. + +If a driver has *CustomTimerDpc* routines, and also waits on timer objects in a nonarbitrary thread context, it should: + +- Never use a thread-context-sensitive timer object in a nonarbitrary thread context, or vice versa. + +- Allocate a separate timer object for each *CustomTimerDpc* routine. Each set of driver threads or driver routines that are called in a nonarbitrary thread context should have its own set of "waitable" timer objects. + +If you use a *CustomTimerDpc* routine, choose carefully the interval the driver passes in calls to **KeSetTimer** or **KeSetTimerEx**. In addition, consider all possible effects of a call to **KeCancelTimer** with the same timer object from any driver routine that makes this call, particularly on SMP platforms. + +Keep in mind the following fact about *CustomTimerDpc* routines: + +Only one instantiation of a DPC object representing a particular DPC routine can be queued for execution at any given moment. + +If a second driver routine calls **KeSetTimer** or **KeSetTimerEx** to run the same *CustomTimerDpc* routine before the interval specified by the first caller expires, the *CustomTimerDpc* routine is run only after the interval specified by the second caller expires. In these circumstances, the *CustomTimerDpc* does none of the work for which the first routine called **KeSetTimer** or **KeSetTimerEx**. + +For drivers that have *CustomTimerDpc* routines and use periodic timers: + +A driver cannot deallocate a periodic timer from a DPC routine. Drivers can deallocate only nonperiodic timers from a DPC routine. + +Consider the following a design guideline for drivers that have both *CustomDpc* and *CustomTimerDpc* routines: + +To prevent race conditions, never pass the same *Dpc* pointer to **KeSetTimer** or **KeSetTimerEx** and [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185). + +In other words, suppose a driver's *StartIo* routine calls **KeSetTimer** or **KeSetTimerEx** to queue a *CustomTimerDpc* routine, and the driver's ISR calls **KeInsertQueueDpc** simultaneously from another processor with the same *Dpc* pointer. That DPC routine will be run when IRQL on a processor falls below DISPATCH\_LEVEL or the timer interval expires, whichever comes first. Whichever does come first, some essential work for the *StartIo* or ISR would simply be dropped by the DPC routine. + +In addition, a DPC used by two standard driver routines with very different functionality would have poorer performance characteristics than separate *CustomTimerDpc* and *CustomDpc* routines. The DPC would have to determine which operations to carry out, depending on the conditions that caused the *StartIo* routine or ISR to queue it. Testing for these conditions in the DPC would use additional CPU cycles. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20CustomTimerDpc%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-driver-defined-callback-object.md b/windows-driver-docs-pr/kernel/using-a-driver-defined-callback-object.md new file mode 100644 index 0000000000..fc376d496f --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-driver-defined-callback-object.md @@ -0,0 +1,54 @@ +--- +title: Using a Driver-Defined Callback Object +author: windows-driver-content +description: Using a Driver-Defined Callback Object +ms.assetid: b3b32534-0641-4818-9384-65fd45f689e8 +keywords: ["callback objects WDK kernel", "driver-defined callback objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Driver-Defined Callback Object + + +## + + +To use a callback object defined by another driver, a driver opens the object, then registers a routine to be called when the callback is triggered, as shown in the following figure. The driver requesting notification must know the name of the callback object and must understand the semantics of the arguments passed to the callback routine. + +![diagram illustrating registration for callback notification](images/3reg-cbk.png) + +Before it can open the object, the driver must call [**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804) to create an attribute block, specifying the name of the object. After it has a pointer to an attribute block, it calls [**ExCreateCallback**](https://msdn.microsoft.com/library/windows/hardware/ff544560), passing the attribute pointer, a location in which to receive a handle to the callback, and **FALSE** for the *Create* parameter, indicating that it requires an existing callback object. + +The driver can then call [**ExRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff545534) with the returned handle to register its callback routine. + +The callback routine has the following prototype: + +``` +typedef VOID (*PCALLBACK_FUNCTION ) ( + IN PVOID CallbackContext, + IN PVOID Argument1, + IN PVOID Argument2 + ); +``` + +The *CallbackContext* parameter is the context pointer to be passed to the callback routine each time it is called. Typically, this parameter is a pointer to a block of context data, which the caller should allocate from nonpaged pool if the routine can be called at DISPATCH\_LEVEL. The two arguments are defined by the component that created the callback. Typically, the arguments provide information about the conditions that triggered the callback. + +When the creator of the callback triggers notification, the system calls the registered routine, passing a pointer to the context and the two arguments. Values for the arguments are supplied by the component that created the callback. The callback routine is called at the same IRQL at which the creating driver triggered notification, which is always IRQL <= DISPATCH\_LEVEL. + +In its callback routine, a driver can perform whatever tasks it requires for the current conditions. + +When the driver no longer requires notification, it should call [**ExUnregisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff545649) to remove its routine from the list of registered callbacks and to remove its reference to the callback object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20Driver-Defined%20Callback%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-driver-supplied-spin-lock.md b/windows-driver-docs-pr/kernel/using-a-driver-supplied-spin-lock.md new file mode 100644 index 0000000000..a6b7384ee8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-driver-supplied-spin-lock.md @@ -0,0 +1,204 @@ +--- +title: Using a Driver-Supplied Spin Lock +author: windows-driver-content +description: Using a Driver-Supplied Spin Lock +ms.assetid: e81d5c93-47d6-407c-80a2-b2d55f9eb717 +keywords: ["spin locks WDK kernel", "driver-supplied spin locks WDK kernel", "global cancel spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Driver-Supplied Spin Lock + + +## + + +Drivers that manage their own queues of IRPs can use a driver-supplied spin lock, instead of the system cancel spin lock, to synchronize access to the queues. You can improve performance by avoiding use of the cancel spin lock except when absolutely necessary. Because the system has only one cancel spin lock, a driver might sometimes have to wait for that spin lock to become available. Using a driver-supplied spin lock eliminates this potential delay and makes the cancel spin lock available for the I/O manager and other drivers. Although the system still acquires the cancel spin lock when it calls the driver's [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine, a driver can use its own spin lock to protect its queue of IRPs. + +Even if a driver does not queue pending IRPs, but retains ownership in some other way, that driver must set a *Cancel* routine for the IRP and must use a spin lock to protect the IRP pointer. For example, suppose a driver marks an IRP pending, then passes the IRP pointer as context to an [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine. The driver must set a *Cancel* routine that cancels the timer and must use the same spin lock in both the *Cancel* routine and the timer callback when accessing the IRP. + +Any driver that queues its own IRPs and uses its own spin lock must do the following: + +- Create a spin lock to protect the queue. + +- Set and clear the *Cancel* routine only while holding this spin lock. + +- If the *Cancel* routine starts running while the driver is dequeuing an IRP, allow the *Cancel* routine to complete the IRP. + +- Acquire the lock that protects the queue in the *Cancel* routine. + +To create the spin lock, the driver calls [**KeInitializeSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff552160). In the following example, the driver saves the spin lock in a **DEVICE\_CONTEXT** structure along with the queue it has created: + +``` +typedef struct { + LIST_ENTRYirpQueue; + KSPIN_LOCK irpQueueSpinLock; + ... +} DEVICE_CONTEXT; + +VOID InitDeviceContext(DEVICE_CONTEXT *deviceContext) +{ + InitializeListHead(&deviceContext->irpQueue); + KeInitializeSpinLock(&deviceContext->irpQueueSpinLock); +} +``` + +To queue an IRP, the driver acquires the spin lock, calls [**InsertTailList**](https://msdn.microsoft.com/library/windows/hardware/ff547823), and then marks the IRP pending, as in the following example: + +``` +NTSTATUS QueueIrp(DEVICE_CONTEXT *deviceContext, PIRP Irp) +{ + PDRIVER_CANCEL oldCancelRoutine; + KIRQL oldIrql; + NTSTATUS status; + + KeAcquireSpinLock(&deviceContext->irpQueueSpinLock, &oldIrql); + + // Queue the IRP and call IoMarkIrpPending to indicate + // that the IRP may complete on a different thread. + // N.B. It is okay to call these inside the spin lock + // because they are macros, not functions. + IoMarkIrpPending(Irp); + InsertTailList(&deviceContext->irpQueue, &Irp->Tail.Overlay.ListEntry); + + // Must set a Cancel routine before checking the Cancel flag. + oldCancelRoutine = IoSetCancelRoutine(Irp, IrpCancelRoutine); + ASSERT(oldCancelRoutine == NULL); + + if (Irp->Cancel) { + // The IRP was canceled. Check whether our cancel routine was called. + oldCancelRoutine = IoSetCancelRoutine(Irp, NULL); + if (oldCancelRoutine) { + // The cancel routine was NOT called. + // So dequeue the IRP now and complete it after releasing the spin lock. + RemoveEntryList(&Irp->Tail.Overlay.ListEntry); + // Drop the lock before completing the request. + KeReleaseSpinLock(&deviceContext->irpQueueSpinLock, oldIrql); + Irp->IoStatus.Status = STATUS_CANCELLED; + Irp->IoStatus.Information = 0; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + return STATUS_PENDING; + + } else { + // The Cancel routine WAS called. + // As soon as we drop our spin lock, it will dequeue and complete the IRP. + // So leave the IRP in the queue and otherwise do not touch it. + // Return pending since we are not completing the IRP here. + + } + } + + KeReleaseSpinLock(&deviceContext->irpQueueSpinLock, oldIrql); + + // Because the driver called IoMarkIrpPending while it held the IRP, + // it must return STATUS_PENDING from its dispatch routine. + return STATUS_PENDING; +} +``` + +As the example shows, the driver holds its spin lock while it sets and clears the *Cancel* routine. The sample queuing routine contains two calls to [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674). + +The first call sets the *Cancel* routine for the IRP. However, because the IRP might have been canceled while the queuing routine is running, the driver must check the **Cancel** member of the IRP. + +- If **Cancel** is set, then cancellation has been requested, and the driver must make a second call to **IoSetCancelRoutine** to see whether the previously set *Cancel* routine was called. + +- If the IRP has been canceled but the *Cancel* routine has not yet been called, then the current routine dequeues the IRP and completes it with STATUS\_CANCELLED. + +- If the IRP has been canceled and the *Cancel* routine has already been called, then the current return marks the IRP pending and returns STATUS\_PENDING. The *Cancel* routine will complete the IRP. + +The following example shows how to remove an IRP from the previously created queue: + +``` +PIRP DequeueIrp(DEVICE_CONTEXT *deviceContext) +{ + KIRQL oldIrql; + PIRP nextIrp = NULL; + + KeAcquireSpinLock(&deviceContext->irpQueueSpinLock, &oldIrql); + + while (!nextIrp && !IsListEmpty(&deviceContext->irpQueue)) { + PDRIVER_CANCEL oldCancelRoutine; + PLIST_ENTRY listEntry = RemoveHeadList(&deviceContext->irpQueue); + + // Get the next IRP off the queue. + nextIrp = CONTAINING_RECORD(listEntry, IRP, Tail.Overlay.ListEntry); + + // Clear the IRP's cancel routine. + oldCancelRoutine = IoSetCancelRoutine(nextIrp, NULL); + + // IoCancelIrp() could have just been called on this IRP. What interests us + // is not whether IoCancelIrp() was called (nextIrp->Cancel flag set), but + // whether IoCancelIrp() called (or is about to call) our Cancel routine. + // For that, check the result of the test-and-set macro IoSetCancelRoutine. + if (oldCancelRoutine) { + // Cancel routine not called for this IRP. Return this IRP. + ASSERT(oldCancelRoutine == IrpCancelRoutine); + } else { + // This IRP was just canceled and the cancel routine was (or will be) + // called. The Cancel routine will complete this IRP as soon as we + // drop the spin lock, so do not do anything with the IRP. + // Also, the Cancel routine will try to dequeue the IRP, so make + // the IRP's ListEntry point to itself. + ASSERT(nextIrp->Cancel); + InitializeListHead(&nextIrp->Tail.Overlay.ListEntry); + nextIrp = NULL; + } + } + + KeReleaseSpinLock(&deviceContext->irpQueueSpinLock, oldIrql); + + return nextIrp; +} +``` + +In the example, the driver acquires the associated spin lock before it accesses the queue. While holding the spin lock, it checks that the queue is not empty and gets the next IRP off the queue. Then it calls **IoSetCancelRoutine** to reset the *Cancel* routine for the IRP. Because the IRP could be canceled while the driver dequeues the IRP and resets the *Cancel* routine, the driver must check the value returned by **IoSetCancelRoutine**. If **IoSetCancelRoutine** returns **NULL**, which indicates that the *Cancel* routine either has been or will soon be called, then the dequeuing routine lets the *Cancel* routine complete the IRP. It then releases the lock that protects the queue and returns. + +Note the use of [**InitializeListHead**](https://msdn.microsoft.com/library/windows/hardware/ff547799) in the preceding routine. The driver could requeue the IRP, so that the *Cancel* routine can dequeue it, but it is simpler to call **InitializeListHead**, which reinitializes the IRP's **ListEntry** field so that it points to the IRP itself. Using the self-referencing pointer is important because the structure of the list could change before the *Cancel* routine acquires the spin lock. And if the list structure changes, possibly making the original value of **ListEntry** invalid, the *Cancel* routine could corrupt the list when it dequeues the IRP. But if **ListEntry** points to the IRP itself, then the *Cancel* routine will always use the correct IRP. + +The *Cancel* routine, in turn, simply does the following: + +``` +VOID IrpCancelRoutine(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp) +{ + DEVICE_CONTEXT *deviceContext = DeviceObject->DeviceExtension; + KIRQL oldIrql; + + // Release the global cancel spin lock. + // Do this while not holding any other spin locks so that we exit at the right IRQL. + IoReleaseCancelSpinLock(Irp->CancelIrql); + + // Dequeue and complete the IRP. + // The enqueue and dequeue functions synchronize properly so that if this cancel routine is called, + // the dequeue is safe and only the cancel routine will complete the IRP. Hold the spin lock for the IRP + // queue while we do this. + + KeAcquireSpinLock(&deviceContext->irpQueueSpinLock, &oldIrql); + + RemoveEntryList(&Irp->Tail.Overlay.ListEntry); + + KeReleaseSpinLock(&deviceContext->irpQueueSpinLock, oldIrql); + + // Complete the IRP. This is a call outside the driver, so all spin locks must be released by this point. + Irp->IoStatus.Status = STATUS_CANCELLED; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + return; +} +``` + +The I/O manager always acquires the global cancel spin lock before it calls a *Cancel* routine, so the first task of the *Cancel* routine is to release this spin lock. It then acquires the spin lock that protects the driver's queue of IRPs, removes the current IRP from the queue, releases its spin lock, completes the IRP with STATUS\_CANCELLED and no priority boost, and returns. + +For more information about canceling spin locks, see the [Cancel Logic in Windows Drivers](http://go.microsoft.com/fwlink/p/?linkid=59531) white paper on the Microsoft Windows Hardware Developer Central (WHDC) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20Driver-Supplied%20Spin%20Lock%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-file-handle.md b/windows-driver-docs-pr/kernel/using-a-file-handle.md new file mode 100644 index 0000000000..66af6276da --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-file-handle.md @@ -0,0 +1,71 @@ +--- +title: Using a File Handle +author: windows-driver-content +description: Using a File Handle +ms.assetid: f5a4d3f6-b74f-411e-9fa9-a41d83152fd7 +keywords: ["files WDK kernel", "file objects WDK kernel", "objects WDK file objects", "file handles WDK kernel", "handle to file WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a File Handle + + +## + + +The following table lists the operations that drivers can perform on a file handle and the corresponding routines that carry out those operations. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OperationRoutine to call

Read data from the file.

[ZwReadFile](https://msdn.microsoft.com/library/windows/hardware/ff567072)

Write data to the file.

[ZwWriteFile](https://msdn.microsoft.com/library/windows/hardware/ff567121)

Read metadata for the file or file handle.

[ZwQueryInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567052)

Write metadata for the file or file handle.

[ZwSetInformationFile](https://msdn.microsoft.com/library/windows/hardware/ff567096)

+ +  + +To indicate where in the file to begin reading or writing data, you pass a *ByteOffset* parameter to **ZwReadFile** or **ZwWriteFile**, respectively. + +If you opened the handle with FILE\_APPEND\_DATA access, all data is written to the end of the file, and the *ByteOffset* parameter is ignored. + +Under certain conditions, the I/O manager maintains a current file-position pointer for the file. You can begin a read or write operation at that position by specifying **NULL** for *ByteOffset*. For more information about when the current file-position pointer exists, see [Using the Current File Position](using-the-current-file-position.md) later in this section. + +To examine or change information about a file, call [**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052) or [**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096), respectively. You specify the particular type of information as the *FileInformationClass* parameter to each routine. For example, setting *FileInformationClass* to **FileBasicInformation** allows you to examine or change a [**FILE\_BASIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff545762) structure, which contains members for the file-creation time and the last-access time, among others. For information about all the possible values for *FileInformationClass*, see [**FILE\_INFORMATION\_CLASS**](https://msdn.microsoft.com/library/windows/hardware/ff728840). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20File%20Handle%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-handle-to-a-registry-key-object.md b/windows-driver-docs-pr/kernel/using-a-handle-to-a-registry-key-object.md new file mode 100644 index 0000000000..65c4c6ae43 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-handle-to-a-registry-key-object.md @@ -0,0 +1,183 @@ +--- +title: Using a Handle to a Registry-Key Object +author: windows-driver-content +description: Using a Handle to a Registry-Key Object +ms.assetid: 25982249-31dc-4542-9ebb-139991619b40 +keywords: ["handle to registry-key object WDK kernel", "registry WDK kernel , object routines", "driver registry information WDK kernel , object routines", "object routines WDK kernel", "registry-key objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a Handle to a Registry-Key Object + + +## + + +The following table lists the operations that drivers can perform on an open key as well as the appropriate routines to call. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationRoutine to call

Examine the key's properties, such as its name or the number of its subkeys.

[ZwQueryKey](https://msdn.microsoft.com/library/windows/hardware/ff567060)

Iterate through the key's subkeys, examining the properties of each one.

[ZwEnumerateKey](https://msdn.microsoft.com/library/windows/hardware/ff566447)

Examine the properties of a key value, including the value's data.

[ZwQueryValueKey](https://msdn.microsoft.com/library/windows/hardware/ff567069)

Iterate through a key's values, examining the properties of each one.

[ZwEnumerateValueKey](https://msdn.microsoft.com/library/windows/hardware/ff566453)

Set the data for a value associated with a key.

[ZwSetValueKey](https://msdn.microsoft.com/library/windows/hardware/ff567109)

Delete a key.

[ZwDeleteKey](https://msdn.microsoft.com/library/windows/hardware/ff566437)

Delete a key value.

[ZwDeleteValueKey](https://msdn.microsoft.com/library/windows/hardware/ff566439)

+ +  + +Once the driver has finished its manipulations, it must call [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417) to close the handle—unless it has already called **ZwDeleteKey** to delete the key. (Once a key is deleted, all the open handles to it become invalid, so the driver must not close the handle in this case.) + +The following code example illustrates how to open a handle for a key named **\\Registry\\Machine\\Software\\***MyCompany*\\*MyApp*, then retrieve key data and close the handle. + +``` +// +// Get the frame location from the registry key +// HKLM\SOFTWARE\MyCompany\MyApp. +// For example: "FrameLocation"="X:\\MyApp\\Frames" +// +HANDLE handleRegKey = NULL; +for (int n = 0; n < 1; n++) +{ + NTSTATUS status = NULL; + UNICODE_STRING RegistryKeyName; + OBJECT_ATTRIBUTES ObjectAttributes; + + RtlInitUnicodeString(&RegistryKeyName, L"\\Registry\\Machine\\Software\\MyCompany\\MyApp"); + InitializeObjectAttributes(&ObjectAttributes, + &RegistryKeyName, + OBJ_CASE_INSENSITIVE | OBJ_KERNEL_HANDLE, + NULL, // handle + NULL); + status = ZwOpenKey(&handleRegKey, KEY_READ, &ObjectAttributes); + + // If the driver cannot open the key, the driver cannot continue. + // In this situation, the driver was probably set up incorrectly + // and worst case, the driver cannot stream. + if( NT_SUCCESS(status) == FALSE ) + { + break; + } + // The driver obtained the registry key. + PKEY_VALUE_FULL_INFORMATION pKeyInfo = NULL; + UNICODE_STRING ValueName; + ULONG ulKeyInfoSize = 0; + ULONG ulKeyInfoSizeNeeded = 0; + + // The driver requires the following value. + RtlInitUnicodeString(&ValueName, L"FrameLocation"); + + // Determine the required size of keyInfo. + status = ZwQueryValueKey( handleRegKey, + &ValueName, + KeyValueFullInformation, + pKeyInfo, + ulKeyInfoSize, + &ulKeyInfoSizeNeeded ); + + // The driver expects one of the following errors. + if( (status == STATUS_BUFFER_TOO_SMALL) || (status == STATUS_BUFFER_OVERFLOW) ) + { + // Allocate the memory required for the key. + ulKeyInfoSize = ulKeyInfoSizeNeeded; + pKeyInfo = (PKEY_VALUE_FULL_INFORMATION) ExAllocatePoolWithTag( NonPagedPool, ulKeyInfoSizeNeeded, g_ulTag); + if( NULL == pKeyInfo ) + { + break; + } + RtlZeroMemory( pKeyInfo, ulKeyInfoSize ); + + // Get the key data. + status = ZwQueryValueKey( handleRegKey, + &ValueName, + KeyValueFullInformation, + pKeyInfo, + ulKeyInfoSize, + &ulKeyInfoSizeNeeded ); + if( (status != STATUS_SUCCESS) || (ulKeyInfoSizeNeeded != ulKeyInfoSize) || (NULL == pKeyInfo) ) + { + break; + } + + // Fill in the frame location if it has not been filled in already. + if ( NULL == m_szwFramePath ) + { + m_ulFramePathLength = pKeyInfo->DataLength; + ULONG_PTR pSrc = NULL; + + pSrc = (ULONG_PTR) ( (PBYTE) pKeyInfo + pKeyInfo->DataOffset); + + m_szwFramePath = (LPWSTR) ExAllocatePoolWithTag( NonPagedPool, m_ulFramePathLength, g_ulTag); + if ( NULL == m_szwFramePath ) + { + m_ulFramePathLength = 0; + break; + } + + // Copy the frame path. + RtlCopyMemory(m_szwFramePath, (PVOID) pSrc, m_ulFramePathLength); + } + // The driver is done with the pKeyInfo. + xFreePoolWithTag(pKeyInfo, g_ulTag); + + } // if( (status == STATUS_BUFFER_TOO_SMALL) || (status == STATUS_BUFFER_OVERFLOW) ) +} // Get the Frame location from the registry key. + +// All done with the registry. +if (NULL != handleRegKey) +{ + ZwClose(handleRegKey); +} +``` + +The system caches key changes in memory and writes them to disk every few seconds. To force a key change to disk, call [**ZwFlushKey**](https://msdn.microsoft.com/library/windows/hardware/ff566457). + +To manipulate the registry through a simpler interface, drivers can also call the **Rtl*Xxx*Registry*Xxx*** routines. For more information, see [Registry Run-Time Library Routines](registry-run-time-library-routines.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20Handle%20to%20a%20Registry-Key%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-a-system-defined-callback-object.md b/windows-driver-docs-pr/kernel/using-a-system-defined-callback-object.md new file mode 100644 index 0000000000..ef138dfe3c --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-a-system-defined-callback-object.md @@ -0,0 +1,54 @@ +--- +title: Using a System-Defined Callback Object +author: windows-driver-content +description: Using a System-Defined Callback Object +ms.assetid: 1f1a2fc1-e698-41f7-84e4-9db091def690 +keywords: ["callback objects WDK kernel", "system-defined callback objects WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using a System-Defined Callback Object + + +## + + +The system defines three callback objects for driver use: + +**\\Callback\\SetSystemTime** + +**\\Callback\\PowerState** + +**\\Callback\\ProcessorAdd** + +Drivers that use the system time (for example, file system drivers) might register for the **\\Callback\\SetSystemTime** callback object. This callback provides for notification when the system time changes. + +The **\\Callback\\PowerState** callback object provides for notification when one of the following occurs: + +- The system switches from AC to DC power or vice versa. + +- The system power policy changes as the result of a user or application request. + +- A transition to a system sleep or shutdown state is imminent. A driver can request notification so that it can lock code into memory in anticipation of shutdown. Callback routines will be notified before the power manager sends the system set-power IRP. + +The **\\Callback\\ProcessorAdd** callback provides notification when a new processor is added to the system. + +To use a system-defined callback, a driver initializes an attribute block ([**InitializeObjectAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff547804)) with the callback's name, then opens the callback object ([**ExCreateCallback**](https://msdn.microsoft.com/library/windows/hardware/ff544560)), just as for a driver-defined callback. The driver should not request that the callback object be created. + +With the handle returned by **ExCreateCallback**, the driver calls [**ExRegisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff545534) to register a notification routine, passing a pointer to an arbitrary context and a pointer to its routine. A driver can register its callback routine any time. When the specified condition occurs, the system calls the registered callback routine at IRQL<=DISPATCH\_LEVEL. + +When the driver no longer requires notification, it should call [**ExUnregisterCallback**](https://msdn.microsoft.com/library/windows/hardware/ff545649) to delete its callback routine from the list of registered callbacks and to remove its reference to the callback object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20a%20System-Defined%20Callback%20Object%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-an-iotimer-routine.md b/windows-driver-docs-pr/kernel/using-an-iotimer-routine.md new file mode 100644 index 0000000000..5da64958d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-an-iotimer-routine.md @@ -0,0 +1,60 @@ +--- +title: Using an IoTimer Routine +author: windows-driver-content +description: Using an IoTimer Routine +ms.assetid: 9de2d2ec-31c5-4a60-96bf-5da067d2d9db +keywords: ["IoTimer"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using an IoTimer Routine + + +## + + +While the timer for the associated device object is enabled, the [*IoTimer*](https://msdn.microsoft.com/library/windows/hardware/ff550381) routine is called approximately once per second. However, because the intervals at which each *IoTimer* routine is called depend on the resolution of the system clock, do not assume that an *IoTimer* routine will be called precisely on a one-second boundary. + +**Note**  An *IoTimer* routine, like all DPC routines, is called at IRQL = DISPATCH\_LEVEL. While a DPC routine runs, all threads are prevented from running on the same processor. Driver developers should carefully design their *IoTimer* routines to run for as brief a time as possible. + +  + +Perhaps the most common use for an *IoTimer* routine is to time out device I/O operations for an IRP. Consider the following scenario for using an *IoTimer* routine as a running timer within a device driver: + +1. When it starts the device, the driver initializes a timer counter in the device extension to -1, indicating no current device I/O operations, and calls [**IoStartTimer**](https://msdn.microsoft.com/library/windows/hardware/ff550373) just before it returns STATUS\_SUCCESS. + + Each time the *IoTimer* routine is called, it checks whether the timer counter is -1, and, if so, returns control. + +2. The driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine initializes the timer counter in the device extension to an upper limit, plus an additional second in case the *IoTimer* routine has just been run. It then uses [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) to call a *SynchCritSection\_1* routine, which programs the physical device for the operation requested by the current IRP. + +3. The driver's ISR resets the timer counter to -1 before queuing the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine or a [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine. + +4. Each time the *IoTimer* routine is called, it checks whether the timer counter has been reset by the ISR to -1, and, if so, returns control. If not, the *IoTimer* routine uses **KeSynchronizeExecution** to call a *SynchCritSection\_2* routine, which adjusts the timer counter by some driver-determined number of seconds. + +5. The *SynchCritSection\_2* routine returns **TRUE** to the *IoTimer* routine as long as the current request has not yet timed out. If the timer counter goes to zero, the *SynchCritSection\_2* routine resets the timer counter to a driver-determined reset-timeout value, sets a reset-expected flag for itself (and for the *DpcForIsr*) in its context area, attempts to reset the device, and returns **TRUE**. + + The *SynchCritSection\_2* routine will be called again if its reset operation also times out on the device, when it returns **FALSE**. If its reset succeeds, the *DpcForIsr* routine determines that the device has been reset from the reset-expected flag and retries the request, repeating the actions of the *StartIo* routine as described in Step 2. + +6. If the *SynchCritSection\_2* routine returns **FALSE**, the *IoTimer* routine assumes the physical device is in an unknown state because an attempt to reset it has already failed. In these circumstances, the *IoTimer* routine queues a *CustomDpc* routine and returns. This *CustomDpc* routine logs a device I/O error, calls [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358), fails the current IRP, and returns. + +If this device driver's ISR resets the shared timer counter to -1, as described in Step 3, the driver's *DpcForIsr* routine completes the interrupt-driven I/O processing of the current IRP. The reset timer counter indicates that this device I/O operation has not timed out, so the *IoTimer* routine does not need to change the timer counter. + +Under most circumstances, the preceding *SynchCritSection\_2* routine simply decrements the timer counter. The *SynchCritSection\_2* routine attempts to reset the device only if the current I/O operation has timed out, which is indicated when the timer counter goes to zero. And only if an attempt to reset the device has already failed does the *SynchCritSection\_2* routine return **FALSE** to the *IoTimer* routine. + +Consequently, both the preceding *IoTimer* routine and its helper *SynchCritSection\_2* routine take very little time to execute under normal circumstances. By using an *IoTimer* routine in this manner, a device driver ensures that each valid device I/O request can be retried, if necessary, and that a *CustomDpc* routine will fail an IRP only if an uncorrectable hardware failure prevents the IRP from being satisfied. Moreover, the driver provides this functionality at very little cost in execution time. + +The simplicity of the preceding scenario depends on a device that does only one operation at a time and on a driver that does not normally overlap I/O operations. A driver that carries out overlapped device I/O operations, or a higher-level driver that uses an *IoTimer* routine to time out a set of driver-allocated IRPs sent to more than one chain of lower drivers, would have more complex timeout scenarios to manage. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20an%20IoTimer%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-buffered-i-o.md b/windows-driver-docs-pr/kernel/using-buffered-i-o.md new file mode 100644 index 0000000000..ed0c12d659 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-buffered-i-o.md @@ -0,0 +1,64 @@ +--- +title: Using Buffered I/O +author: windows-driver-content +description: Using Buffered I/O +ms.assetid: 69291156-babb-465a-9e80-1766f075768b +keywords: ["buffered I/O WDK kernel", "buffers WDK I/O , buffered I/O", "data buffers WDK I/O , buffered I/O", "nonpaged system buffers WDK I/O", "I/O control codes WDK kernel , buffered I/O", "I/O WDK kernel , buffered I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Buffered I/O + + +## + + +A driver that services an interactive or slow device, or one that usually transfers relatively small amounts of data at a time, should use the [buffered I/O](methods-for-accessing-data-buffers.md) transfer method. Using buffered I/O for small, interactive transfers improves overall physical memory usage, because the memory manager does not need to lock down a full physical page for each transfer, as it does for drivers that request direct I/O. Generally, video, keyboard, mouse, serial, and parallel drivers request buffered I/O. + +The I/O manager determines that an I/O operation is using buffered I/O as follows: + +- For [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests, DO\_BUFFERED\_IO is set in the **Flags** member of the [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. For more information, see [Initializing a Device Object](initializing-a-device-object.md). + +- For [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests, the IOCTL code's value contains METHOD\_BUFFERED as the *TransferType* value in the IOCTL value. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +The following figure illustrates how the I/O manager sets up an **IRP\_MJ\_READ** request for a transfer operation that uses buffered I/O. + +![diagram illustrating a buffered i/o for user buffers](images/3mdlbffr.png) + +The figure shows an overview of how drivers can use the **SystemBuffer** pointer in the IRP to transfer data for a read request, when a driver has ORed the device object's **Flags** with DO\_BUFFERED\_IO: + +1. Some range of user-space virtual addresses represents the current thread's buffer, and that buffer's contents might be stored somewhere within a range of page-based physical addresses (dark shading in the previous figure). + +2. The I/O manager services the current thread's read request, for which the thread passes a range of user-space virtual addresses representing a buffer. + +3. The I/O manager checks the user-supplied buffer for accessibility and calls [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) to create a nonpaged system-space buffer (**SystemBuffer**) the size of the user-supplied buffer. + +4. The I/O manager provides access to the newly allocated **SystemBuffer** in the IRP it sends to the driver. + + If the figure showed a write request, the I/O manager would copy data from the user buffer into the system buffer before it sent the IRP to the driver. + +5. For the read request shown in the previous figure, the driver reads data from the device into the system-space buffer. The memory for this buffer is nonpaged and the driver can safely access the buffer without first locking it. When the read request has been satisfied, the driver calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the IRP. + +6. When the original thread is again active, the I/O manager copies the read-in data from the system buffer into the user buffer. It also calls [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590) to release the system buffer. + +After the I/O manager has created a system-space buffer for the driver, the requesting user-mode thread can be swapped out and its physical memory can be reused by another thread, possibly by a thread belonging to another process. However, the system-space virtual address range supplied in the IRP remains valid until the driver calls [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with the IRP. + +Drivers that transfer large amounts of data at a time, in particular, drivers that do multipage transfers, should not attempt to use buffered I/O. As the system runs, nonpaged pool can become fragmented so that the I/O manager cannot allocate large, contiguous system-space buffers to send in IRPs for such a driver. + +Typically, a driver uses buffered I/O for some types of IRPs, such as [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) requests, even if it also uses [direct I/O](methods-for-accessing-data-buffers.md). Drivers that use direct I/O typically only do so for [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests, and possibly driver-defined [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests that require large data transfers. + +Every **IRP\_MJ\_DEVICE\_CONTROL** and **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** request includes an I/O control code. If the I/O control code indicates that the IRP must be supported by using buffered I/O, the I/O manager uses a single system buffer to represent the user application's input and output buffers. A driver that supports such an I/O control code must read input data (if any) from the buffer and then supply output data (if any) by overwriting the input data. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Buffered%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-bus-master-dma.md b/windows-driver-docs-pr/kernel/using-bus-master-dma.md new file mode 100644 index 0000000000..fa3578eb31 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-bus-master-dma.md @@ -0,0 +1,36 @@ +--- +title: Using Bus-Master DMA +author: windows-driver-content +description: Using Bus-Master DMA +ms.assetid: 08357a55-aec2-4454-923f-6daaf1583a25 +keywords: ["AdapterControl routines, bus-master DMA", "bus-master DMA WDK kernel", "DMA transfers WDK kernel , bus-master DMA", "adapter objects WDK kernel , bus-master DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Bus-Master DMA + + +## + + +Drivers of bus-master DMA devices can use the following kinds of system-supplied DMA support: + +- Packet-based DMA if the bus-master adapter allows the driver to determine when a DMA transfer operation is done and/or when to begin another transfer operation for a given IRP. See [Using Packet-Based Bus-Master DMA](using-packet-based-bus-master-dma.md) for details. + +- Common-buffer DMA (also called *continuous DMA*) if the bus-master adapter does not provide a way for the driver to determine readily when a transfer operation will begin or when a transfer is complete, or if a single buffer area is used continuously or repeatedly for DMA transfers. See [Using Common-Buffer Bus-Master DMA](using-common-buffer-bus-master-dma.md) for details. + +Depending on the nature of the bus-master adapter, some drivers use packet-based DMA exclusively, some use common-buffer DMA exclusively, and some use both. For example, the driver of a bus-master adapter that uses a mailbox scheme to communicate status information and commands might use a common buffer for the mailboxes shared between the driver and its adapter, together with packet-based DMA for data transfers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Bus-Master%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-common-buffer-bus-master-dma.md b/windows-driver-docs-pr/kernel/using-common-buffer-bus-master-dma.md new file mode 100644 index 0000000000..1a0c6c3e69 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-common-buffer-bus-master-dma.md @@ -0,0 +1,60 @@ +--- +title: Using Common-Buffer Bus-Master DMA +author: windows-driver-content +description: Using Common-Buffer Bus-Master DMA +ms.assetid: 55b5d819-e257-4863-b02a-5eeb83f72c65 +keywords: ["continuous DMA WDK kernel", "common buffer DMA WDK kernel", "DMA transfers WDK kernel , common buffer", "bus-master DMA WDK kernel", "DMA transfers WDK kernel , bus-master DMA", "adapter objects WDK kernel , bus-master DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Common-Buffer Bus-Master DMA + + +## + + +As described in [Using Bus-Master DMA](using-bus-master-dma.md), some drivers for bus-master DMA devices use common-buffer DMA exclusively, and some use common-buffer DMA in combination with packet-based DMA. + +Use common-buffer DMA economically. Setting up a common buffer can tie up some (or all, depending on the size of the requested buffer) of the map registers associated with the adapter object that represents the bus-master adapter. + +Setting up common-buffer areas economically, such as by using **PAGE\_SIZE** chunks or a single allocation, leaves more map registers available for packet-based DMA operations. It also leaves more system memory free for other purposes, which produces better overall driver and system performance. + +To set up a common buffer for bus-master DMA, a bus-master DMA device driver must call [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575) with the adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220). Typically, a driver makes this call from its [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine for [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) requests. A driver should allocate a common buffer only if it will use the buffer repeatedly for its DMA operations while the driver remains loaded. The following diagram illustrates such a call to **AllocateCommonBuffer**. + +![diagram illustrating the allocation of a common buffer for bus-master dma](images/3halcbff.png) + +The requested size for the buffer, shown in the previous diagram as LengthForBuffer, determines how many map registers must be used to provide a virtual-to-logical mapping for the common buffer. Use the [**BYTES\_TO\_PAGES**](https://msdn.microsoft.com/library/windows/hardware/ff540709) macro to determine the maximum number of pages needed (**BYTES\_TO\_PAGES** (*LengthForBuffer*)). This value cannot be greater than the *NumberOfMapRegisters* returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220). + +In addition, the caller must supply the following: + +- A Boolean value that indicates whether caching should be enabled + + **Note** This value is ignored. The operating system determines whether to enable cached memory in the common buffer that is to be allocated. That decision is based on the processor architecture and device bus. + + On computers with x86-based, x64-based, and Itanium-based processors, cached memory is enabled. + + On computers with ARM or ARM 64-based processors, the operating system does not automatically enable cached memory for all devices. The system relies on the ACPI_CCA method for each device to determine whether the device is cache-coherent. + +- A pointer to a driver-defined variable that will contain the device-accessible base *Logical Address* for the buffer (BufferLogicalAddress in the previous diagram) on return from **AllocateCommonBuffer** + +If the call succeeds, **AllocateCommonBuffer** returns a driver-accessible base virtual address for the buffer (BufferVirtualAddress in the previous diagram), which the driver must save in its device extension, controller extension, or other driver-accessible resident storage area (nonpaged pool allocated by the driver). + +**AllocateCommonBuffer** returns **NULL** if it cannot allocate memory for the buffer. If the returned base virtual address is **NULL**, the driver either must use the system's packet-based DMA support exclusively or the driver must fail the **IRP\_MN\_START\_DEVICE** request, returning STATUS\_INSUFFICIENT\_RESOURCES. + +Otherwise, the driver can use the allocated common buffer as a driver- and adapter-accessible storage area for DMA transfers. + +When the PnP manager sends an IRP that stops or removes the device, the driver must call [**FreeCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff546511) to release each common buffer it has allocated. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Common-Buffer%20Bus-Master%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-common-buffer-system-dma.md b/windows-driver-docs-pr/kernel/using-common-buffer-system-dma.md new file mode 100644 index 0000000000..406750fe3f --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-common-buffer-system-dma.md @@ -0,0 +1,68 @@ +--- +title: Using Common-Buffer System DMA +author: windows-driver-content +description: Using Common-Buffer System DMA +ms.assetid: ee060aa4-2db4-4bd2-b107-b71acced97fd +keywords: ["system DMA WDK kernel , common buffer", "common buffer DMA WDK kernel", "DMA transfers WDK kernel , common buffer", "AllocateCommonBuffer", "auto-initialize mode WDK DMA", "continuous DMA WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Common-Buffer System DMA + + +## + + +A driver that uses a system DMA controller's auto-initialize mode must allocate memory for a buffer into which or from which DMA transfers can be carried out. The driver calls [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575) to get this buffer, typically from the [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine that handles an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. The following figure shows how a driver allocates the buffer and maps its virtual address range to system physical memory. + +![diagram illustrating how a driver allocates a common buffer for system dma](images/3hlsysbf.png) + +As the previous figure shows, a driver takes the following steps to allocate a buffer for system DMA: + +1. The driver calls [**AllocateCommonBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff540575), passing a pointer to the adapter object that was returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220), along with the length in bytes requested for its buffer. To use memory economically, the input *Length* value for the buffer should either be less than or equal to PAGE\_SIZE or should be an integral multiple of PAGE\_SIZE. + +2. If **AllocateCommonBuffer** returns a **NULL** pointer, the driver should free any system resources it has already claimed and return STATUS\_INSUFFICIENT\_RESOURCES in response to the **IRP\_MN\_START\_DEVICE** request. + + Otherwise, **AllocateCommonBuffer** allocates the requested amount of memory in system virtual address space and returns two different types of pointers to that buffer: + + - The *LogicalAddress* of the buffer (BufferLogicalAddress in the previous figure), for which the driver must provide storage but which it should ignore thereafter + + - The virtual address of the buffer (BufferVirtualAddress in the previous figure), which the driver also must store so that it can build an MDL describing its buffer for DMA operations + + The driver should store these pointers in the device extension or other driver-allocated resident memory. + +3. The driver calls [**IoAllocateMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548263) to allocate an MDL for the buffer. The driver passes the *VirtualAddress* of the buffer returned by **AllocateCommonBuffer** and the *Length* of its buffer to allocate an MDL. + +4. The driver calls [**MmBuildMdlForNonPagedPool**](https://msdn.microsoft.com/library/windows/hardware/ff554498) with the pointer returned by **IoAllocateMdl** to map the virtual address range for its resident buffer to system physical memory. + +After allocating a common buffer and mapping its virtual address range, the driver of a subordinate device can begin to process an IRP that requests a DMA transfer. To do so, the driver calls the following general sequence of support routines: + +1. At the driver writer's discretion, [**RtlMoveMemory**](https://msdn.microsoft.com/library/windows/hardware/ff562030) to copy data from a locked-down user buffer into the driver-allocated common buffer for a transfer to the device + +2. **AllocateAdapterChannel** when the driver is ready to program its device for DMA and needs the system DMA controller + +3. [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402), with the MDL that describes the driver-allocated common buffer, to set up the system DMA controller for the transfer operation + + Note that the driver calls **MapTransfer** only once to set up the system DMA controller to use its common buffer. During a transfer, the driver can call [**ReadDmaCounter**](https://msdn.microsoft.com/library/windows/hardware/ff560782) to determine how many bytes remain to be transferred, and if necessary, call **RtlMoveMemory** to copy more data to or from a user buffer. + +4. [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) when the driver has completed its DMA transfer to/from the subordinate device + +5. [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) as soon as all the requested data has been transferred or if the driver must fail the IRP because of a device I/O error + +The adapter object pointer returned by **IoGetDmaAdapter** is a required parameter to each of these support routines except **RtlMoveMemory**. + +Individual drivers call this sequence of support routines at different points, depending on how each driver is implemented to service its device. For example, one driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine might make the call to **AllocateAdapterChannel**, another driver might make this call from a routine that removes IRPs from a driver-created interlocked queue, and still another driver might make this call when its subordinate DMA device indicates it is ready to transfer data. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Common-Buffer%20System%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-common-log-file-system.md b/windows-driver-docs-pr/kernel/using-common-log-file-system.md new file mode 100644 index 0000000000..1fb8018181 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-common-log-file-system.md @@ -0,0 +1,51 @@ +--- +title: Using Common Log File System +author: windows-driver-content +description: Using Common Log File System +ms.assetid: a9685648-b08c-48ca-b020-e683068f2ea2 +keywords: ["Common Log File System WDK kernel", "CLFS WDK kernel", "logging service WDK CLFS", "transactional logs WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Common Log File System + + +This section describes the Common Log File System (CLFS). It contains the following topics. + +[Introduction to the Common Log File System](introduction-to-the-common-log-file-system.md) + +[CLFS Terminology](clfs-terminology.md) + +[CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md) + +[CLFS Marshalling Areas](clfs-marshalling-areas.md) + +[Writing Data Records to a CLFS Stream](writing-data-records-to-a-clfs-stream.md) + +[Writing Restart Records to a CLFS Stream](writing-restart-records-to-a-clfs-stream.md) + +[Reading Data Records from a CLFS Stream](reading-data-records-from-a-clfs-stream.md) + +[Reading Restart Records from a CLFS Stream](reading-restart-records-from-a-clfs-stream.md) + +[CLFS Stable Storage](clfs-stable-storage.md) + +[Dedicated CLFS Logs](dedicated-clfs-logs.md) + +[Multiplexed CLFS Logs](multiplexed-clfs-logs.md) + +[CLFS Support for Archiving](clfs-support-for-archiving.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Common%20Log%20File%20System%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-controller-objects.md b/windows-driver-docs-pr/kernel/using-controller-objects.md new file mode 100644 index 0000000000..df688fea72 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-controller-objects.md @@ -0,0 +1,38 @@ +--- +title: Using Controller Objects +author: windows-driver-content +description: Using Controller Objects +ms.assetid: 74b6685a-018f-4cb1-9332-424631aad85c +keywords: ["I/O WDK kernel , controller objects", "controller objects WDK kernel", "ControllerControl routines", "objects WDK controller objects", "physical device controllers WDK I/O", "device controllers WDK I/O", "synchronization"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Controller Objects + + +## + + +This section describes the use of controller objects and [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routines. It contains the following topics: + +[Introduction to Controller Objects](introduction-to-controller-objects.md) + +[Creating Controller Objects and Controller Extensions](creating-controller-objects-and-controller-extensions.md) + +[Allocating Controller Objects for I/O Operations](allocating-controller-objects-for-i-o-operations.md) + +[Writing ControllerControl Routines](writing-controllercontrolroutines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Controller%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-critical-sections.md b/windows-driver-docs-pr/kernel/using-critical-sections.md new file mode 100644 index 0000000000..40cd15ef0d --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-critical-sections.md @@ -0,0 +1,36 @@ +--- +title: Using Critical Sections +author: windows-driver-content +description: Using Critical Sections +ms.assetid: 439ba7ef-6473-40ca-9daa-a8c61d789d97 +keywords: ["interrupt service routines WDK kernel , critical sections", "ISRs WDK kernel , critical sections", "InterruptService", "synchronization WDK kernel , interrupts"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Critical Sections + + +## + + +Any driver that contains an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine will most likely require one or more critical sections to synchronize access to hardware resources or driver data among the ISR and other routines. + +This section includes the following topics: + +[Introduction to SynchCritSection Routines](introduction-to-synchcritsection-routines.md) + +[Writing SynchCritSection Routines](writing-synchcritsection-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Critical%20Sections%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-custom-wmi-events.md b/windows-driver-docs-pr/kernel/using-custom-wmi-events.md new file mode 100644 index 0000000000..9ba08a7151 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-custom-wmi-events.md @@ -0,0 +1,66 @@ +--- +title: Using Custom WMI Events +author: windows-driver-content +description: Using Custom WMI Events +ms.assetid: 00354e0b-a652-44e9-8b2b-fd755cc05fec +keywords: ["WMI WDK kernel , event tracking", "events WDK WMI", "tracing WDK WMI", "sending WMI events", "event blocks WDK WMI", "notifications WDK WMI", "event consumer providers WDK WMI", "custom events WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Custom WMI Events + + +## + + +Some classes of drivers are required to support certain WMI event classes. Drivers can also design their own custom WMI event classes. Custom WMI events offer a way for a driver to pass data back to a user-mode component. A user-mode component receives WMI events through WMI COM interfaces. + +An application can receive event notifications as follows: + +- Use the **CoCreateInstance** routine to get a pointer to an **IWbemLocator** object. + +- Use the **IWbemLocator** pointer to connect to the WMI server process. The **IWBemLocator::ConnectServer** method call provides you with a pointer to an **IWbemServices** object. + +- Use the **IWbemServices** object to query for the event types you are interested in. The **IWbemServices::ExecNotificationQuery** method allows you to specify an event query in the WMI Query Language (WQL). + +- An application can also register to receive WMI events asynchronously, by implementing the **IWbemObjectSink** interface. The application uses the **IWbemServices::ExecNotificationQueryAsync** method to register for asynchronous notification of events. When matching events occur, the system uses the **IWbemObjectSink::Indicate** method to notify the application of the events that have occurred. + +You can also implement a user-mode WMI *event consumer provider*. This is a user-mode component that WMI can automatically load when events of a specified type occur. + +- Include an instance of the **\_\_EventConsumerProviderRegistration** WMI class in the MOF data for your user-mode component. + +- Implement the **IWbemUnboundObjectSink** interface for each WMI event class you want to receive notifications of. + +- Implement the **IWbemEventConsumerProvider** interface to specify the event classes the component receives notifications of, and the associated **IWbemUnboundObjectSink** implementations. + +- Implement the **IWbemProviderInit** interface that initializes your component as an event consumer. + +More information about receiving WMI events and the **IWbemXxx** COM interfaces can be found in the Microsoft Windows SDK documentation. + +WMI events are not the only way to notify user-mode applications when particular situations occur. A driver could implement an IOCTL that an application could use to poll for notification. The driver and application could share a notification event object (see [Event Objects](event-objects.md)) to signal that a particular situation has occurred. + +WMI events have some advantages over these other methods: + +- If user-mode applications poll for events faster than the driver can respond, then the driver may have many IOCTLs pending. + +- You can ameliorate the previous problem by using a notification event object to notify a user-mode application, but notification events can only signal that an event has occurred. The application must still use an IOCTL to get any additional data. The next two issues still apply. + +- If multiple applications poll the driver for events, the driver would need to maintain state to determine which applications had received which events. + +- Some drivers, such as SCSI miniport and NDIS miniport drivers, cannot receive IOCTLs. + +WMI events do have the disadvantage that the user-mode code you must provide is considerably more complicated than that for the other methods. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Custom%20WMI%20Events%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-direct-i-o-with-dma.md b/windows-driver-docs-pr/kernel/using-direct-i-o-with-dma.md new file mode 100644 index 0000000000..35af8a63f9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-direct-i-o-with-dma.md @@ -0,0 +1,50 @@ +--- +title: Using Direct I/O with DMA +author: windows-driver-content +description: Using Direct I/O with DMA +ms.assetid: 0e609613-9023-4f35-a9c5-d68c8b676cfe +keywords: ["direct I/O WDK kernel", "buffers WDK I/O , direct I/O", "data buffers WDK I/O , direct I/O", "I/O WDK kernel , direct I/O", "DMA transfers WDK kernel , direct I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Direct I/O with DMA + + +## + + +The following figure illustrates how the I/O manager sets up an [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) request for a DMA transfer operation that uses direct I/O. + +![diagram illustrating direct i/o on user buffers for devices that use dma](images/3mdldrct.png) + +The previous figure illustrates how drivers can use the IRP's **MdlAddress** to transfer data for a read request. The driver in the figure uses packet-based system or bus-master DMA, and has ORed the device object's **Flags** with DO\_DIRECT\_IO. + +1. Some range of user-space virtual addresses represents the current thread's buffer, and that buffer's contents might actually be stored on some number of physically discontiguous pages (dark shading in the previous figure). The I/O manager creates an MDL to describe this buffer. An MDL is an opaque data structure, defined by the memory manager, that maps a particular virtual address range to one or more page-based physical address ranges. For more information, see [Using MDLs](using-mdls.md). + +2. The I/O manager services the current thread's read request, for which the thread passes a range of user-space virtual addresses that represent a buffer. + +3. The I/O manager or file system driver (FSD) checks the user-supplied buffer for accessibility and calls [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) with the previously created MDL. **MmProbeAndLockPages** also fills in the corresponding physical address range in the MDL. + + As the previous figure shows, an MDL for a virtual range can have several corresponding page-based physical address entries, and the virtual range for a buffer might begin and end at some byte offset from the start of the first and last pages described by an MDL. + +4. The I/O manager provides a pointer to the MDL (**MdlAddress**) in an IRP that requests a transfer operation. Until the I/O manager or file system calls [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) after the driver completes the IRP, the physical pages described in the MDL remain locked down and assigned to the buffer. However, the virtual addresses in such an MDL can become invisible (and invalid), even before the IRP is sent to the device driver or to any intermediate driver that might be layered above the device driver. + +5. If the driver uses packet-based system or bus-master DMA, its [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine calls [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) with the IRP's **MdlAddress** pointer to get the base virtual address for the MDL's page-based entries. + +6. The *AdapterControl* routine then calls [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) with the base address returned by **MmGetMdlVirtualAddress**, to read data from the device directly into physical memory. (For more information, see [Adapter Objects and DMA](adapter-objects-and-dma.md).) + +Drivers should always check buffer lengths. Note that the I/O manager does not create an MDL for a zero-length buffer. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Direct%20I/O%20with%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-direct-i-o-with-pio.md b/windows-driver-docs-pr/kernel/using-direct-i-o-with-pio.md new file mode 100644 index 0000000000..b16c151d60 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-direct-i-o-with-pio.md @@ -0,0 +1,52 @@ +--- +title: Using Direct I/O with PIO +author: windows-driver-content +description: Using Direct I/O with PIO +ms.assetid: 84d36567-c8c6-4576-91a0-829c8819de4d +keywords: ["direct I/O WDK kernel", "buffers WDK I/O , direct I/O", "data buffers WDK I/O , direct I/O", "I/O WDK kernel , direct I/O", "PIO transfer operations WDK kernel", "programmed I/O transfers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Direct I/O with PIO + + +## + + +A driver that uses programmed I/O (PIO) rather than DMA must doubly map user-space buffers into a system-space address range. The following figure illustrates how the I/O manager sets up an [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) request for a PIO transfer operation that uses direct I/O. + +![diagram illustrating direct i/o for devices that use pio](images/3mdlpio.png) + +The figure shows how a device that uses PIO handles the same task. + +1. Some range of user-space virtual addresses represents the current thread's buffer, and that buffer's contents might actually be stored on some number of physically discontiguous pages. If the buffer length is nonzero, the I/O manager creates an MDL to describe this buffer. + +2. The I/O manager services the current thread's read request, for which the thread passes a range of user-space virtual addresses representing a buffer. + +3. The I/O manager or FSD checks the user-supplied buffer for accessibility. If the I/O manager has created an MDL, it calls [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) with an MDL, which specifies the range of virtual addresses for the user buffer. **MmProbeAndLockPages** also fills in the corresponding physical address range in the MDL. + +4. The I/O manager provides a pointer to the MDL (**MdlAddress**) in an IRP that requests a transfer operation. Until the I/O manager or file system calls [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) after the driver completes the IRP, the physical pages described in the MDL remain locked down and assigned to the buffer. However, the virtual addresses in such an MDL can become invisible (and invalid), even before the IRP is sent to the device driver or to any intermediate driver that might be layered above the device driver. + +5. If the driver requires system (virtual) addresses, the driver calls [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) with the IRP's **MdlAddress** pointer to doubly map the user-space virtual addresses in the MDL to a system-space address range. In the figure above, AliasBuff represents the MDL that describes the doubly-mapped addresses. + +6. The driver uses the system-space virtual address range from the doubly mapped MDL (AliasBuff) to read data into memory. + +When the driver completes the IRP by calling [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), the I/O manager or file system releases the MDL's doubly mapped system-space range if the driver called **MmGetSystemAddressForMdlSafe**. The I/O manager or file system unlocks the pages described in the MDL, and disposes of the MDL and IRP on the driver's behalf. For better performance, drivers should avoid doubly mapping MDL physical addresses to system space, as described in step 3, unless they must use virtual addresses. Doing so uses system page-table entries unnecessarily and can decrease both driver performance and scalability. In addition, the system might crash if it runs out of page-table entries, because most older drivers cannot handle this situation. + +The current user thread's buffers and the thread itself are guaranteed to be resident in physical memory only while that thread is current. For the thread shown in the previous figure, its user buffer's contents could be paged out to secondary storage while another process's threads are run. When another process's thread is run, the system physical memory for the requesting thread's buffer can be overwritten unless the memory manager has locked down and preserved the corresponding physical pages that contain the original thread's buffer. + +However, the original thread's virtual addresses for its buffer do not remain visible while another thread is current, even if the memory manager preserves the buffer's physical pages. Consequently, drivers cannot use a virtual address returned by [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) to access memory. Callers of this routine must pass its results to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) (along with the IRP's **MdlAddress** pointer) in order to transfer data using packet-based system or bus-master DMA. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Direct%20I/O%20with%20PIO%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-direct-i-o.md b/windows-driver-docs-pr/kernel/using-direct-i-o.md new file mode 100644 index 0000000000..e8a1d9c0bc --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-direct-i-o.md @@ -0,0 +1,48 @@ +--- +title: Using Direct I/O +author: windows-driver-content +description: Using Direct I/O +ms.assetid: e40b4657-833f-404c-8472-2e33564129a5 +keywords: ["direct I/O WDK kernel", "buffers WDK I/O , direct I/O", "data buffers WDK I/O , direct I/O", "I/O WDK kernel , direct I/O"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Direct I/O + + +## + + +Drivers for devices that can transfer large amounts of data at a time should use direct I/O for those transfers. Using direct I/O for large transfers improves a driver's performance, both by reducing its interrupt overhead and by eliminating the memory allocation and copying operations inherent in buffered I/O. + +Generally, mass-storage device drivers request direct I/O for transfer requests, including lowest-level drivers that use direct memory access (DMA) or programmed I/O (PIO), as well as any intermediate drivers chained above them. + +The I/O manager determines that an I/O operation is using direct I/O as follows: + +- For [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests, DO\_DIRECT\_IO is set in the **Flags** member of the [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. For more information, see [Initializing a Device Object](initializing-a-device-object.md). + +- For [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests, the IOCTL code's value contains METHOD\_IN\_DIRECT or METHOD\_OUT\_DIRECT as the *TransferType* value in the IOCTL value. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +Drivers that use direct I/O will sometimes also use buffered I/O to handle some IRPs. In particular, drivers typically use buffered I/O for some I/O control codes for **IRP\_MJ\_DEVICE\_CONTROL** requests that require data transfers, regardless of whether the driver uses direct I/O for read and write operations. + +Setting up a direct I/O transfer varies slightly, depending on whether DMA or PIO is being used. For more information, see: + +[Using Direct I/O with DMA](using-direct-i-o-with-dma.md) + +[Using Direct I/O with PIO](using-direct-i-o-with-pio.md) + +Drivers must take steps to maintain cache coherency during DMA and PIO transfers. For more information, see [Maintaining Cache Coherency](maintaining-cache-coherency.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Direct%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-files-in-a-driver.md b/windows-driver-docs-pr/kernel/using-files-in-a-driver.md new file mode 100644 index 0000000000..d5e19b1987 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-files-in-a-driver.md @@ -0,0 +1,46 @@ +--- +title: Using Files In A Driver +author: windows-driver-content +description: Using Files In A Driver +ms.assetid: 721bf336-1d1d-4677-843d-8af04c6f434d +keywords: ["files WDK kernel", "file objects WDK kernel", "objects WDK file objects", "file handles WDK kernel", "handle to file WDK kernel", "reading data from files", "writing data to files", "reading metadata for file", "writing metadata for file", "driver file objects WDK kernel", "multiple file objects WDK kernel", "kernel-mode drivers WDK , files"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Files In A Driver + + +## + + +The Microsoft Windows executive represents files by *file objects*, which are executive objects that are managed by the object manager. (Directories are also represented by file objects.) + +Kernel-mode components refer to a file by its object name, which is **\\DosDevices** concatenated to the file's full path. (On Microsoft Windows 2000 and later versions of the operating system, **\\??** is equivalent to **\\DosDevices**.) For example, the object name of the C:\\WINDOWS\\example.txt file is **\\DosDevices\\C:\\WINDOWS\\example.txt**. You use the object name to open a handle to a file. For more information about object names, see [Object Names](object-names.md). + +### To use a file + +1. Open a handle to the file. + + For more information, see [Opening a Handle to a File](opening-a-handle-to-a-file.md). + +2. Perform the intended operations by calling the appropriate **Zw*Xxx*File** routines. + + For more information, see [Using a File Handle](using-a-file-handle.md). + +3. Close the handle by calling [**ZwClose**](https://msdn.microsoft.com/library/windows/hardware/ff566417). + +Every time that you open a handle to a file, the Windows executive creates a file object that represents the file, and it returns an open handle to that object. Therefore, multiple file objects can exist for a single file. (Because a user-mode application can copy a handle, multiple handles can also exist for the same file object.) After all the open handles to a file object are closed, the Windows executive deletes the file object. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Files%20In%20A%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-floating-point-or-mmx-in-a-wdm-driver.md b/windows-driver-docs-pr/kernel/using-floating-point-or-mmx-in-a-wdm-driver.md new file mode 100644 index 0000000000..58afced72b --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-floating-point-or-mmx-in-a-wdm-driver.md @@ -0,0 +1,100 @@ +--- +title: Using Floating Point in a WDM Driver +author: windows-driver-content +description: Kernel-mode WDM drivers for Windows must follow certain guidelines when using floating-point operations. These differ between x86 and x64 systems. By default, Windows turns off arithmetic exceptions for both systems. +ms.assetid: 73414084-4054-466a-b64c-5c81b224be92 +keywords: ["floating point WDK kernel", "floating-point unit WDK kernel", "FPU WDK kernel", "KeSaveFloatingPointState", "KeRestoreFloatingPointState", "WDM drivers WDK kernel , floating-point operations", "MMX WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Floating Point in a WDM Driver + + +**Last updated** + +- July 2016 + +Kernel-mode WDM drivers for Windows must follow certain guidelines when using floating-point operations. These differ between x86 and x64 systems. By default, Windows turns off arithmetic exceptions for both systems. + +## x86 systems + + +Kernel-mode WDM drivers for x86 systems must wrap the use of floating point calculations between calls to [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) and [**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182). The floating point operations must be placed in a non-inline subroutine to make sure that floating point calculations are not performed before checking the return value of **KeSaveExtendedProcessorState** due to compiler reordering. + +The compiler makes use of MMX/x87 also known as the floating-point unit (FPU) registers for such calculations, which can be concurrently used by a user-mode application. Failure to save these registers before using them, or failure to restore them when finished, may cause calculation errors in applications. + +Drivers for x86 systems can call [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) and perform floating point calculations at IRQL <= DISPATCH\_LEVEL. Floating-point operations are not supported in interrupt service routines (ISRs) on x86 systems. + +## x64 systems + + +The 64-bit compiler does not use the MMX/x87 registers for floating point operations. Instead, it uses the SSE registers. x64 kernel mode code is not allowed to access the MMX/x87 registers. The compiler also takes care of properly saving and restoring the SSE state, therefore, calls to [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) and [**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182) are unnecessary and floating point operations can be used in ISRs. Use of other extended processor features such as AVX, requires saving and restoring extended state. For more information see [Using extended processor features in Windows drivers](floating-point-support-for-64-bit-drivers.md). + +## Example + + +The following example shows how a WDM driver should wrap its FPU access: + +``` +__declspec(noinline) +VOID +DoFloatingPointCalculation( + VOID + ) +{ + double Duration; + LARGE_INTEGER Frequency; + + Duration = 1000000.0; + DbgPrint("%I64x\n", *(LONGLONG*)&Duration); + KeQueryPerformanceCounter(&Frequency); + Duration /= (double)Frequency.QuadPart; + DbgPrint("%I64x\n", *(LONGLONG*)&Duration); +} + +NTSTATUS +DriverEntry( + _In_ PDRIVER_OBJECT DriverObject, + _In_ PUNICODE_STRING RegistryPath + ) +{ + + XSTATE_SAVE SaveState; + NTSTATUS Status; + + Status = KeSaveExtendedProcessorState(XSTATE_MASK_LEGACY, &SaveState); + if (!NT_SUCCESS(Status)) { + goto exit; + } + + __try { + DoFloatingPointCalculation(); + } + __finally { + KeRestoreExtendedProcessorState(&SaveState); + } + +exit: + return Status; +} +``` + +In the example, the assignment to the floating-point variable occurs between calls to [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238) and [**KeRestoreExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553182). Because any assignment to a floating-point variable uses the FPU, drivers must ensure that **KeSaveExtendedProcessorState** has returned without error before initializing such a variable. + +The preceding calls are unnecessary on an x64 system and harmless when the XSTATE\_MASK\_LEGACY flag is specified. Therefore, there is no need to change the code when compiling the driver for an x64 system. + +On x86-based systems, the FPU is reset to its default state by a call to FNINIT, upon return from [**KeSaveExtendedProcessorState**](https://msdn.microsoft.com/library/windows/hardware/ff553238). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Floating%20Point%20in%20a%20WDM%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-guid-d3cold-support-interface.md b/windows-driver-docs-pr/kernel/using-guid-d3cold-support-interface.md new file mode 100644 index 0000000000..9eca153de5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-guid-d3cold-support-interface.md @@ -0,0 +1,44 @@ +--- +title: Using the GUID_D3COLD_SUPPORT_INTERFACE Driver Interface +author: windows-driver-content +description: Starting with Windows 8, drivers can call the routines in the GUID_D3COLD_SUPPORT_INTERFACE interface to determine the D3cold capabilities of devices and to enable these devices to use D3cold. +ms.assetid: 525637E8-B16F-4038-A78D-A47064E36449 +--- + +# Using the GUID\_D3COLD\_SUPPORT\_INTERFACE Driver Interface + + +Starting with Windows 8, drivers can call the routines in the [GUID\_D3COLD\_SUPPORT\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh967714) interface to determine the D3cold capabilities of devices and to enable these devices to use D3cold. The two primary routines in this interface are [*SetD3ColdSupport*](https://msdn.microsoft.com/library/windows/hardware/hh967716) and [*GetIdleWakeInfo*](https://msdn.microsoft.com/library/windows/hardware/hh967712). + +A driver calls the *SetD3ColdSupport* routine to dynamically enable and disable a device's transitions to D3cold that can occur when the computer is in S0. If the device must be able to signal a wake event from any low-power Dx state that the device enters, the driver should enable the device to enter D3cold only if the device can signal wake events from D3cold. Otherwise, after the device enters D3cold, it might be unavailable until the computer leaves the S0 state. + +By default, before the first call to the *SetD3ColdSupport* routine, D3hot-to-D3cold transitions are disabled. To change this default so that D3hot-to-D3cold transitions are enabled before the first *SetD3ColdSupport* call, the driver package for the device can include the following two lines in the DDInstall.HW section of the INF file that installs the driver: + +```Text +Include = machine.inf +Needs = PciD3ColdSupported +``` + +The *GetIdleWakeInfo* routine enables the driver for a device to discover the device power states from which the device can signal a wake event when the computer is in a particular system power state. The caller to this routine specifies a system power state as an input parameter, and, as an output parameter, the routine reports the lowest-powered device power state from which the device can signal a wait event when the computer is in the specified system power state. For example, the *GetIdleWakeInfo* routine can tell the driver whether the device can signal a wake event from D3cold when the computer is in S0. + +The *GetIdleWakeInfo* routine supplies more complete device-wake information than is available from the [**IRP\_MN\_QUERY\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff551664) request. This request, which all versions of Windows support, supplies a [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure that describes the capabilities of a device. The **DeviceWake** member of this structure contains a subset of the information that is available from the *GetIdleWakeInfo* routine. This member indicates the lowest-powered device power state from which a device can signal a wait event. The information in this member is guaranteed to be accurate only if the computer is in the system low-power state that is indicated by the **SystemWake** member of the structure. If **SystemWake** = **PowerSystemSleeping3**, the information in **DeviceWake** is known to be valid for S3, might frequently be valid for S1 and S2, and might even be valid for S0. + +However, as a best practice, a driver should not assume that the information in the **DeviceWake** method is valid for any system power state other than the state indicated by **SystemWake**. For some devices, the lowest Dx state from which a device can signal a wake event varies according to whether the computer is in working state S0 or in a low-power state (S1, S2, S3, or S4). For other devices, the buses to which the devices are connected can handle wake signals when the computer is in S0, but the devices cannot. Only the *GetIdleWakeInfo* routine can accurately describe the device-wake capabilities of these devices. + +For example, the [PCI Express Base 3.0 Specification](http://www.pcisig.com/specifications/pciexpress/specifications/) defines two separate mechanisms to signal wake events—one mechanism is used when the PCI Express link (bus) is turned on, and the other is used when the link is turned off. When the link is turned on, the device sends a stream of PM\_PME Transaction Layer Packets (TLPs) to signal that the device should move from a low-power Dx state to D0. When the link is turned off, the device requests that the link be turned on so that the device can send PM\_PME TLPs. To request that the link be turned on, the device either asserts its WAKE\# signal (for the more common device form factor) or uses the "beaconing" mechanism (less common). + +The PCI Express specification requires that all devices that advertise the ability to signal power management events (PMEs) from D3cold implement both of these device-wake mechanisms, but a driver developer might need to enable a device that does not correctly implement these mechanisms. + +If the device can correctly deliver PM\_PME TLPs when the link is turned on, the driver can enable the device to enter D3hot when the computer is in S0. If the device can correctly assert its WAKE\# signal to turn the link on and then use PM\_PME TLPs to initiate the transition to D0, the driver can enable the device to enter D3cold when the computer is in S0. + +However, the driver should not enable the device to enter either D3hot or D3cold if the system firmware (the BIOS) can't guarantee that the PCI Express device-wake mechanisms are correctly handled by the hardware platform. A driver can call the [*GetIdleWakeInfo*](https://msdn.microsoft.com/library/windows/hardware/hh967712) routine to discover whether the firmware claims support for these mechanisms. If a driver uses Kernel-Mode Driver Framework (KMDF) 1.11 or later, a convenient alternative to calling *GetIdleWakeInfo* is to allow the [**WdfDeviceAssignS0IdleSettings**](https://msdn.microsoft.com/library/windows/hardware/ff545903) method to enable the device to idle in the lowest-powered Dx state from which the device can signal a wake event. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20GUID_D3COLD_SUPPORT_INTERFACE%20Driver%20Interface%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-guids-in-drivers.md b/windows-driver-docs-pr/kernel/using-guids-in-drivers.md new file mode 100644 index 0000000000..5de4373ba4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-guids-in-drivers.md @@ -0,0 +1,38 @@ +--- +title: Using GUIDs in Drivers +author: windows-driver-content +description: Using GUIDs in Drivers +ms.assetid: b70a2f64-dd7b-4d76-a4cf-dcb60ce0585c +keywords: ["globally unique identifiers WDK kernel", "GUIDs WDK kernel", "identifiers WDK GUIDs", "header files WDK GUIDs", "kernel-mode drivers WDK , GUIDs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using GUIDs in Drivers + + +## + + +Drivers and other system components use *globally unique identifiers* (GUIDs) to identify a variety of items. System components define GUIDs for items such as [device setup classes](https://msdn.microsoft.com/library/windows/hardware/ff541509), PnP events, WMI events, and still image events. Driver writers can create GUIDs for items such as [device interface classes](https://msdn.microsoft.com/library/windows/hardware/ff541339), custom PnP events, and custom WMI events. Drivers and applications include header files that define the GUIDs that they use. + +This section includes the following topics: + +[Defining and Exporting New GUIDs](defining-and-exporting-new-guids.md) + +[Including GUIDs in Driver Code](including-guids-in-driver-code.md) + +For information about using GUIDs in user-mode applications, see Microsoft Windows SDK documentation. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20GUIDs%20in%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-i-o-control-codes.md b/windows-driver-docs-pr/kernel/using-i-o-control-codes.md new file mode 100644 index 0000000000..f12444684d --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-i-o-control-codes.md @@ -0,0 +1,40 @@ +--- +title: Using I/O Control Codes +author: windows-driver-content +description: Using I/O Control Codes +ms.assetid: 3f124ee7-bfd9-417f-ae7a-849d02a1b97a +keywords: ["IRPs WDK kernel , I/O control codes", "I/O control codes WDK kernel", "control codes WDK IOCTLs", "IOCTLs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using I/O Control Codes + + +## + + +This section contains the following topics: + +[Introduction to I/O Control Codes](introduction-to-i-o-control-codes.md) + +[Creating IOCTL Requests in Drivers](creating-ioctl-requests-in-drivers.md) + +[Defining I/O Control Codes](defining-i-o-control-codes.md) + +[Buffer Descriptions for I/O Control Codes](buffer-descriptions-for-i-o-control-codes.md) + +[Security Issues for I/O Control Codes](security-issues-for-i-o-control-codes.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20I/O%20Control%20Codes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-interrupt-resource-descriptors.md b/windows-driver-docs-pr/kernel/using-interrupt-resource-descriptors.md new file mode 100644 index 0000000000..10382780d4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-interrupt-resource-descriptors.md @@ -0,0 +1,35 @@ +--- +title: Using Interrupt Resource Descriptors +author: windows-driver-content +description: Using Interrupt Resource Descriptors +ms.assetid: 0e9aa9a1-c1aa-42e1-9c0b-a91a2424ad1a +--- + +# Using Interrupt Resource Descriptors + + +The Plug and Play (PnP) manager assigns interrupt messages to a device using two passes. First, the PnP manager sends an [**IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS**](https://msdn.microsoft.com/library/windows/hardware/ff550874) request to the driver with a list of hardware resources, including interrupt messages, that it intends to assign to the device. The driver can modify this list to change the number of interrupt messages, as well as some per-message settings. Then, after the PnP manager actually assigns the resources, it sends an [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request and supplies a complete list of the hardware resources, including interrupt messages, assigned to the driver's device. + +The **IRP\_MN\_FILTER\_RESOURCE\_REQUIREMENTS** request supplies a list of [**IO\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff550598) structures. If the device has an MSI (message-signaled interrupt) capability structure as defined in the PCI 2.2 specification, the PnP manager supplies a single interrupt message descriptor. If the device has an MSI-X capability structure as defined in the PCI 3.0 specification, the PnP manager supplies one structure for each interrupt message. Interrupt message descriptors have **Type** = **CmResourceTypeInterrupt** and **Flags** = CM\_RESOURCE\_INTERRUPT\_LATCHED | CM\_RESOURCE\_INTERRUPT\_MESSAGE. Drivers can also change settings such as the interrupt affinity by changing the **u.Interrupt** members of the structure. Note that when using MSI, interrupts all have same affinity, while when using MSI-X they can have different affinities. For more information, see [Interrupt Affinity and Priority](interrupt-affinity-and-priority.md). + +For MSI, as defined in PCI 2.2, **u.Interrupt.MaximumVector** - **u.Interrupt.MinimumVector** + 1 is the number of interrupt messages allocated for the device. Drivers can change the number of interrupt messages by modifying **u.Interrupt.MinimumVector**. For MSI interrupt messages, **u.Interrupt.MaximumVector** is always CM\_RESOURCE\_INTERRUPT\_MESSAGE\_TOKEN. To allocate *MessageCount* interrupt messages, set **u.Interrupt.MinimumVector** to equal CM\_RESOURCE\_INTERRUPT\_MESSAGE\_TOKEN - *MessageCount* + 1. + +For MSI-X, as defined in PCI 3.0, drivers can change the number of interrupt messages allocated by adding or removing entries from the list. Note that interrupt message resources added this way must not be subsequently removed in response to the [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request. For MSI-X, the PnP manager supplies one descriptor per message interrupt, and the **u.Interrupt.MinimumVector** and **u.Interrupt.MaximumVector** members of this descriptor are both set to CM\_RESOURCE\_INTERRUPT\_MESSAGE\_TOKEN. + +Once the Plug and Play manager has assigned all hardware resources for the device, including interrupt messages, it sends the **IRP\_MN\_START\_DEVICE** request to the driver. This request supplies two lists of [**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) structures, one each for raw and translated resources. For interrupt messages, the PnP manager supplies one structure for each allocated memory address with **Type** = **CmResourceTypeInterrupt** and **Flags** = CM\_RESOURCE\_INTERRUPT\_LATCHED | CM\_RESOURCE\_INTERRUPT\_MESSAGE. + +Note that when using MSI, the driver only receives one interrupt resource descriptor, since all messages share the same address. The **MessageCount** member of **u.InterruptMessage.Raw** can be used to determine the number of messages assigned. When using MSI-X, the driver receives a separate resource descriptor for each interrupt message. + +In Windows 8, the operating system does not support resource requests for more than 2048 interrupt messages per device function. In Windows 7 and Windows Vista, the operating system does not support resource requests for more than 910 interrupt messages per device function. If the device driver exceeds this limit, the device might fail to start. To enable a driver to operate in a computer that contains many logical processors, the driver should avoid requesting more than one interrupt per processor. + +During system rebalancing of interrupt resources, the PnP manager might ask a driver to select a preferred set of alternate interrupt resources from a resource requirements list. However, the PnP manager cannot always assign to a driver the resources that the driver prefers. The driver must therefore tolerate, without failures, the assignment of any set of alternate interrupt resources from the resource requirements list. For example, the device might be assigned a smaller number of message interrupts than the driver requested. In the worst case, the driver must be prepared to operate the device with just one line-based interrupt. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Interrupt%20Resource%20Descriptors%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-iocompletion-routines.md b/windows-driver-docs-pr/kernel/using-iocompletion-routines.md new file mode 100644 index 0000000000..d79bf29309 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-iocompletion-routines.md @@ -0,0 +1,42 @@ +--- +title: Using IoCompletion Routines +author: windows-driver-content +description: Using IoCompletion Routines +ms.assetid: 07a6e930-eef0-4408-9f71-55a827aa558e +keywords: ["IoCompletion routines", "completing IRPs WDK kernel , IoCompletion routines", "completing IRPs WDK kernel , dispatch routines", "dispatch routines WDK kernel , completing IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using IoCompletion Routines + + +## + + +Higher-level drivers that monitor on an IRP-specific basis how lower-level drivers carried out particular requests can have one or more [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines. Higher-level drivers that allocate IRPs to send requests to lower drivers must have an *IoCompletion* routine. + +A highest-level or intermediate driver's [*DispatchRead*](https://msdn.microsoft.com/library/windows/hardware/ff543376) or [*DispatchWrite*](https://msdn.microsoft.com/library/windows/hardware/ff544034) routine is most likely to set an *IoCompletion* routine for an IRP, because lower-level drivers must handle transfer requests asynchronously. + +The lowest-level driver in a driver stack cannot register *IoCompletion* routines. + +Drivers generally do not register *IoCompletion* routines for IRPs associated with synchronous I/O operations. For instance, a higher-level driver's [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine can allocate an IRP using [**IoBuildDeviceIoControlRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548318). In this case, the dispatch routine typically does not register an *IoCompletion* routine, because device control requests are generally handled synchronously. Instead, the driver can allocate and initialize an event object, and its *DispatchDeviceControl* routine can wait for an event to be initialized when it sends on driver-allocated IRPs. Usually, a higher-level driver does not register an *IoCompletion* routine for an IRP allocated with [**IoBuildSynchronousFsdRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548330), for the same reason. + +This section contains the following topics: + +[Registering an IoCompletion Routine](registering-an-iocompletion-routine.md) + +[Implementing an IoCompletion Routine](implementing-an-iocompletion-routine.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20IoCompletion%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-ioconnectinterruptex-prior-to-windows-vista.md b/windows-driver-docs-pr/kernel/using-ioconnectinterruptex-prior-to-windows-vista.md new file mode 100644 index 0000000000..27317f713e --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-ioconnectinterruptex-prior-to-windows-vista.md @@ -0,0 +1,65 @@ +--- +title: Using IoConnectInterruptEx Prior to Windows Vista +author: windows-driver-content +description: Using IoConnectInterruptEx Prior to Windows Vista +ms.assetid: a08b2869-93f8-440b-9fbe-068604c6007d +keywords: ["IoConnectInterruptEx", "iointex.h", "line-based interrupts WDK kernel", "message-signaled interrupts WDK kernel", "CONNECT_LINE_BASED", "CONNECT_MESSAGE_BASED", "CONNECT_FULLY_SPECIFIED"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using IoConnectInterruptEx Prior to Windows Vista + + +A driver for Windows 2000, Windows XP, or Windows Server 2003 can link to the Iointex.lib library to use [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) on those versions of the operating system. + +To use **IoConnectInterruptEx** in such a driver, include Iointex.h in the source code for your driver, immediately following Wdm.h or Ntddk.h. The Iointex.h header declares a prototype for the routine. When you build your driver, make sure that it is statically linked to Iointex.lib. + +For operating systems prior to Windows Vista, the version of **IoConnectInterruptEx** provided by Iointex.lib only supports the CONNECT\_FULLY\_SPECIFIED version of the routine. If any other version is specified, the routine returns an NTSTATUS error code, and sets *Parameters*->**Version** to CONNECT\_FULLY\_SPECIFIED. + +Using this behavior, you can write your driver so that it uses CONNECT\_LINE\_BASED or CONNECT\_MESSAGE\_BASED on Windows Vista, and CONNECT\_FULLY\_SPECIFIED on earlier operating systems. First call **IoConnectInterruptEx** with *Parameters*->**Version** equal to CONNECT\_LINE\_BASED or CONNECT\_MESSAGE\_BASED. If the return value is an error code and *Parameters*->**Version** != CONNECT\_FULLY\_SPECIFIED, then retry the operation with *Parameters*->**Version** set to CONNECT\_FULLY\_SPECIFIED. + +The following code example illustrates the technique: + +``` +IO_CONNECT_INTERRUPT_PARAMETERS params; + +// deviceExtension is a pointer to the driver's device extension. +// deviceExtension->MessageUsed is a BOOLEAN. + +RtlZeroMemory( ¶ms, sizeof(IO_CONNECT_INTERRUPT_PARAMETERS) ); +params.Version = CONNECT_MESSAGE_BASED; + +// Set members of params.MessageBased here. + +status = IoConnectInterruptEx(¶ms); + +if ( NT_SUCCESS(status) ) { + // Operation succeeded. We are running on Windows Vista. + devExt->MessageUsed = TRUE; // We save this for posterity. +} else { + // Check to see if we are running on an operating system prior to Windows Vista. + if (params.Version == CONNECT_FULLY_SPECIFIED) { + devExt->MessageUsed = FALSE; // We're not using message-signaled interrupts. + + // Set members of params.FullySpecified here. + + status = IoConnectInterruptEx(¶ms); + } else { + // Other error. + } +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20IoConnectInterruptEx%20Prior%20to%20Windows%20Vista%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-irp-priority-hints.md b/windows-driver-docs-pr/kernel/using-irp-priority-hints.md new file mode 100644 index 0000000000..63e3333565 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-irp-priority-hints.md @@ -0,0 +1,23 @@ +--- +title: Using IRP Priority Hints +author: windows-driver-content +description: Using IRP Priority Hints +ms.assetid: c34afff2-32f2-451b-ab16-ff048d5c3204 +--- + +# Using IRP Priority Hints + + +An *IRP priority hint* is an [**IO\_PRIORITY\_HINT**](https://msdn.microsoft.com/library/windows/hardware/ff550594) value that is associated with an IRP. IRP priority hints provide a simple hinting mechanism to indicate the relative importance of IRPs. A driver can use the priority hint for an IRP when choosing the order that the IRP is processed. IRP priority hints are available on Windows Vista and later operating systems. + +For more information about IRP priority hints, see the [I/O Prioritization in Windows Vista](http://go.microsoft.com/fwlink/p/?linkid=67877) white paper on the Windows Hardware Developer Central (WHDC) website. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20IRP%20Priority%20Hints%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-kernel-transaction-manager.md b/windows-driver-docs-pr/kernel/using-kernel-transaction-manager.md new file mode 100644 index 0000000000..3a4c0c74f6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-kernel-transaction-manager.md @@ -0,0 +1,38 @@ +--- +title: Using Kernel Transaction Manager +author: windows-driver-content +description: Using Kernel Transaction Manager +ms.assetid: b558ace9-b416-4572-ac94-58a083c9d33b +keywords: ["Kernel Transaction Manager WDK", "KTM WDK", "transactions WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Kernel Transaction Manager + + +## + + +This section describes the kernel-mode interfaces of the kernel transaction manager (KTM). It contains the following topics: + +[Introduction to KTM](introduction-to-ktm.md) + +[KTM Objects](ktm-objects.md) + +[Using KTM](using-ktm.md) + +For information about the routines, structures, and enumerations that KTM supports, see the [Kernel Transaction Manager Reference](https://msdn.microsoft.com/library/windows/hardware/ff553232). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Kernel%20Transaction%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-ktm.md b/windows-driver-docs-pr/kernel/using-ktm.md new file mode 100644 index 0000000000..28a2b11070 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-ktm.md @@ -0,0 +1,45 @@ +--- +title: Using KTM +author: windows-driver-content +description: Using KTM +ms.assetid: 79a3ec0b-7a88-43ae-843f-10c7df92def4 +keywords: ["Kernel Transaction Manager WDK , creating transaction processing systems", "KTM WDK , creating transaction processing systems", "transaction processing systems WDK KTM , creating transaction processing systems", "TPS WDK KTM , creating TPSs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using KTM + + +You can use the Kernel Transaction Manager (KTM) and the [Common Log File System](using-common-log-file-system.md) (CLFS) to create a [*transaction processing system*](transaction-processing-terms.md#ktm-term-transaction-processing-system) (TPS). + +This section includes the following topics: + +[Creating a Resource Manager](creating-a-resource-manager.md) + +[Creating a Transactional Client](creating-a-transactional-client.md) + +[Creating a Superior Transaction Manager](creating-a-superior-transaction-manager.md) + +[Handling Transaction Operations](handling-transaction-operations.md) + +[Transaction Notifications](transaction-notifications.md) + +[Using Log Streams with KTM](using-log-streams-with-ktm.md) + +[Using Virtual Clock Values](using-virtual-clock-values.md) + +[Using Tm*Xxx* Routines](using-tmxxx-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20KTM%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-log-streams-with-ktm.md b/windows-driver-docs-pr/kernel/using-log-streams-with-ktm.md new file mode 100644 index 0000000000..5cdf331dd9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-log-streams-with-ktm.md @@ -0,0 +1,67 @@ +--- +title: Using Log Streams with KTM +author: windows-driver-content +description: Using Log Streams with KTM +ms.assetid: d7ad0e16-d1f2-4c41-b647-95b5445c2708 +keywords: ["log streams WDK KTM", "Kernel Transaction Manager WDK , log streams", "KTM WDK , log streams", "Common Log File System WDK kernel , KTM log streams", "CLFS WDK kernel , KTM log streams", "transaction managers WDK KTM , log streams", "resource managers WDK KTM , log streams"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Log Streams with KTM + + +KTM-based transaction processing systems (TPSs) should log transaction activity by using the [Common Log File System](using-common-log-file-system.md) (CLFS). KTM creates a log stream for each transaction manager object. Each resource manager should create its own log stream. + +### Creating Log Streams for Transaction Manager Objects + +When your resource manager calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430), you must specify the name of a CLFS log stream. If the specified stream does not exist, KTM creates it. If the stream already exists, **ZwCreateTransactionManager** reopens it. KTM assigns this log stream to the transaction manager object. + +KTM uses the transaction manager object's log stream to record internal state information about the transaction manager object and all resource manager objects, transaction objects, and enlistment objects that are associated with the transaction manager object. If transactional operations are interrupted before they are complete, KTM can use the information in the log to determine whether to commit or roll back the transactions. + +KTM does not record the transaction data that resource managers receive from or send to clients. Resource managers must use their own log streams to record this information. + +Resource managers can call [**ZwQueryInformationTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567058) to obtain information about a transaction manager object's log stream, such as the log stream's path name or the GUID that KTM assigns to the stream. + +### Creating Log Streams for Resource Managers + +In its initialization code, each resource manager should call [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792) to create its own log stream. Each resource manager should use its stream to record all the information about transactions that it requires to commit, roll back, or recover the transaction's data. + +KTM and all resource managers of a TPS can use a single log file, but each TPS component must use a different stream within the log file. For information about how to specify individual streams within a log file, see [**ClfsCreateLogFile**](https://msdn.microsoft.com/library/windows/hardware/ff540792). + +Periodically, KTM creates a [restart area](reading-restart-records-from-a-clfs-stream.md) in the transaction manager's log stream. When KTM performs a recovery operation, it reads the last restart area to recover the state of objects that were open before the system shut down. Similarly, your resource manager should periodically create restart areas in its log stream. For example, your resource manager might create a restart area every time that a transactional operation is completed. + +For more information about restart areas in CLFS log streams, see [Reading Restart Records from a CLFS Stream](reading-restart-records-from-a-clfs-stream.md). Also, see the [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770), [**ClfsReadRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541709), and [**ClfsReadPreviousRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541699) routines. + +### Using Log Streams for Recovery + +After your resource manager calls **ZwCreateTransactionManager**, it must call [**ZwRecoverTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567079). The **ZwRecoverTransactionManager** routine reads the transaction manager object's log stream to recover the state of the TPS to a known good point. If the computer shut down properly—or did not shut down—after the resource manager was last loaded, the log stream contains minimal information. If a system crash has occurred, the log stream contains enough recovery information to restore all the transactions to a known state. + +After your resource manager calls [**ZwCreateResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff566427), it must call [**ZwRecoverResourceManager**](https://msdn.microsoft.com/library/windows/hardware/ff567078). The **ZwRecoverResourceManager** routine tries to recover the transactions that are associated with each of the resource manager's enlistments. For more information about how to recover a resource manager's transactions, see [Handling Recovery Operations](handling-recovery-operations.md). + +### Storing Transaction Data + +Resource managers that use CLFS log streams should store transaction data in [CLFS marshalling areas](clfs-marshalling-areas.md). CLFS periodically moves the data from the log stream's marshalling area to a permanent storage medium. To log an operation that modifies data, a resource manager might do the following: + +1. Copy the original data, before the write operation modifies it, to the marshalling area. + +2. Perform the operation on a copy of the data without modifying the database's permanent storage medium. + +3. Copy the new data to the marshalling area. + +If the resource manager receives a rollback notification, it can restore the original data from the log stream. If it receives a commit notification, the resource manager can copy the modified data from the log stream to the database's permanent storage medium. + +Resource managers can also use the [**ZwSetInformationEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567094) routine to store recovery information in an enlistment object. KTM saves this information in its log stream and reads it from the log stream during recovery operations. Therefore, a resource manager can obtain this recovery information at any time by calling [**ZwQueryInformationEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567051). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Log%20Streams%20with%20KTM%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-lookaside-lists.md b/windows-driver-docs-pr/kernel/using-lookaside-lists.md new file mode 100644 index 0000000000..92d888f0fe --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-lookaside-lists.md @@ -0,0 +1,96 @@ +--- +title: Using Lookaside Lists +author: windows-driver-content +description: Using Lookaside Lists +ms.assetid: 07a75b8b-04b9-48ea-bda4-53889dd661a9 +keywords: ["memory management WDK kernel , lookaside lists", "lookaside lists WDK kernel", "fixed-size buffer allocations WDK kernel", "ExXxxLookasideList routines WDK", "entries WDK lookaside", "nonpaged lookaside lists WDK kernel", "paged lookaside lists WDK kernel", "Allocate routine WDK memory", "Free routine WDK memory"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Lookaside Lists + + +## + + +Drivers that must allocate fixed-size buffers dynamically to perform on-demand I/O operations can use the **Ex*Xxx*LookasideListEx** or **Ex*Xxx*LookasideList** support routines. After such a driver initializes its lookaside list, the operating system will hold some number of dynamically allocated buffers of the given size in the driver's lookaside list, effectively reserving a set of reusable, fixed-size buffers for the driver. The format and contents of a driver's fixed-size buffers (also known as *entries*) in its lookaside list are driver-determined. + +For example, storage class drivers that must set up SCSI request blocks (SRBs) for the underlying SCSI port/miniport drivers use lookaside lists. Such a class driver allocates buffers for SRBs on an as-needed basis from its lookaside list and releases each SRB buffer back to the lookaside list for the lookaside list to reuse whenever an SRB is returned to the class driver in a completed IRP. Because a storage class driver cannot predetermine how many SRBs it has to use at any time because I/O demand on the driver increases and falls, a lookaside list is a convenient and economical way to manage the allocation and deallocation of buffers for fixed-size SRBs in such a driver. + +The operating system maintains state about all paged and nonpaged lookaside lists that are currently being used, dynamically tracking the demand for allocations and deallocations of entries in all lists, and available system pool for new entries. When demand for allocations is high, the operating system increases the number of entries it holds in each lookaside list. When demand falls again, it frees surplus lookaside entries back to system pool. + +Lookaside lists are thread-safe. A lookaside list has built-in synchronization to enable multiple, concurrently running threads in a driver to share a lookaside list. These threads can safely allocate buffers from the shared lookaside list and free these buffers to the list without requiring the driver to explicitly synchronize these operations. However, to avoid possible leaks and data corruption, a set of threads that share a lookaside list must explictly synchronize the initialization and deletion of the list. + +## Lookaside list interfaces + + +Starting with Windows Vista, the [**LOOKASIDE\_LIST\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff554329) structure describes a lookaside list that can contain either paged or nonpaged buffers. If a driver provides custom *Allocate* and *Free* routines for this lookaside list, these routines receive a private context as an input parameter. A driver can use this context to collect private data for the lookaside list. For example, the context might be used to count the number of list entries that are dynamically allocated and freed by the list. For a code example that shows how to use a context in this way, see [**ExInitializeLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff545298). + +The following system-supplied routines support lookaside lists that are described by a **LOOKASIDE\_LIST\_EX** structure: + +[**ExAllocateFromLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544381) + +[**ExDeleteLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544563) + +[**ExFlushLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544587) + +[**ExFreeToLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff544597) + +[**ExInitializeLookasideListEx**](https://msdn.microsoft.com/library/windows/hardware/ff545298) + +Starting with Windows 2000, the [**PAGED\_LOOKASIDE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff558775) structure describes a lookaside list that contains paged buffers. If a driver provides custom *Allocate* and *Free* routines for this lookaside list, these routines do not receive a private context as an input parameter. For this reason, if your driver is intended to run only on Windows Vista and later versions of Windows, consider using the **LOOKASIDE\_LIST\_EX** structure instead of the **PAGED\_LOOKASIDE\_LIST** structure for your lookaside lists. The following system-supplied routines support lookaside lists that are described by a **PAGED\_LOOKASIDE\_LIST** structure: + +[**ExAllocateFromPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544393) + +[**ExDeletePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544570) + +[**ExFreeToPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544605) + +[**ExInitializePagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545309) + +Starting with Windows 2000, the [**NPAGED\_LOOKASIDE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff556431) structure describes a lookaside list that contains nonpaged buffers. If a driver provides custom *Allocate* and *Free* routines for this lookaside list, these routines do not receive a private context as an input parameter. Again, if your driver is intended to run only on Windows Vista and later versions of Windows, consider using the **LOOKASIDE\_LIST\_EX** structure instead of the **NPAGED\_LOOKASIDE\_LIST** structure for your lookaside lists. The following system-supplied routines support lookaside lists that are described by an **NPAGED\_LOOKASIDE\_LIST** structure: + +[**ExAllocateFromNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544388) + +[**ExDeleteNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544566) + +[**ExFreeToNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff544601) + +[**ExInitializeNPagedLookasideList**](https://msdn.microsoft.com/library/windows/hardware/ff545301) + +## Implementation guidelines + + +To implement a lookaside list that uses a **LOOKASIDE\_LIST\_EX** structure, follow these design guidelines: + +- Call **ExInitializeLookasideListEx** to set up a lookaside list. In this call, specify whether the entries in the lookaside list are to be paged or nonpaged buffers. Use nonpaged buffers if the driver itself or any underlying driver to which it passes its lookaside list entries might access these entries at IRQL >= DISPATCH\_LEVEL. Use paged buffers only if accesses to the driver's lookaside list entries always occur at IRQL <= APC\_LEVEL. + +- The **LOOKASIDE\_LIST\_EX** structure for the lookaside list must always reside in nonpaged system memory regardless of whether the entries in the list are paged or nonpaged. + +- For better performance, pass **NULL** pointers for the *Allocate* and *Free* parameters to **ExInitializeLookasideListEx** unless the allocation and deallocation routines must do more than merely allocate and free memory for lookaside list entries. For example, these routines might record information about the driver's usage of dynamically allocated buffers. + +- A driver-supplied *Allocate* routine can pass the input parameters (*PoolType*, *Tag*, and *Size*) that it receives directly to the [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) or [**ExAllocatePoolWithQuotaTag**](https://msdn.microsoft.com/library/windows/hardware/ff544513) routine to allocate a new buffer. + +- For every call to **ExAllocateFromLookasideListEx**, make the reciprocal call to **ExFreeToLookasideListEx** as soon as possible whenever a previously allocated entry is no longer being used. + +Supplying *Allocate* and *Free* routines that do nothing more than call [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) and [**ExFreePool**](https://msdn.microsoft.com/library/windows/hardware/ff544590), respectively, wastes processor cycles. **ExAllocateFromLookasideListEx** makes the necessary calls to **ExAllocatePoolWithTag** and **ExFreePool** automatically when a driver passes **NULL** *Allocate* and *Free* pointers to **ExInitializeLookasideListEx**. + +Any driver-supplied *Allocate* routine must not allocate memory for an entry from paged pool to be held in a nonpaged lookaside list or vice versa. It must also allocate fixed-size entries, because any subsequent driver call to **ExAllocateFromLookasideListEx** returns the first entry currently held in the lookaside list unless the list is empty. That is, a call to **ExAllocateFromLookasideListEx** causes a call to the driver-supplied *Allocate* routine only if the given lookaside list is currently empty. Therefore, at each call to **ExAllocateFromLookasideListEx**, the returned entry will be exactly the size that the driver needs only if all entries in the lookaside list are of a fixed size. A driver-supplied *Allocate* routine should also not change the *Tag* value that the driver originally passed to **ExInitializeLookasideListEx**, because changes in the pool-tag value would make debugging and tracking the driver's memory usage more difficult. + +Calls to **ExFreeToLookasideListEx** store previously allocated entries in the lookaside list unless the list is already *full* (that is, the list contains the system-determined maximum number of entries). For better performance, a driver should make a reciprocal call to **ExFreeToLookasideListEx** as quickly as it can for every call that it makes to **ExAllocateFromLookasideListEx**. When a driver frees entries back to its lookaside list quickly, that driver's next call to **ExAllocateFromLookasideListEx** is far less likely to incur the performance penalty of dynamically allocating memory for a new entry. + +Similar guidelines apply to a lookaside list that uses a **PAGED\_LOOKASIDE\_LIST** or **NPAGED\_LOOKASIDE\_LIST** structure. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Lookaside%20Lists%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-mdls.md b/windows-driver-docs-pr/kernel/using-mdls.md new file mode 100644 index 0000000000..42983569ff --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-mdls.md @@ -0,0 +1,86 @@ +--- +title: Using MDLs +author: windows-driver-content +description: Using MDLs +ms.assetid: 60652eb8-cfdb-4591-88ff-cf9dc4b9743d +keywords: ["memory management WDK kernel ,"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using MDLs + + +An I/O buffer that spans a range of contiguous virtual memory addresses can be spread over several physical pages, and these pages can be discontiguous. The operating system uses a *memory descriptor list* (MDL) to describe the physical page layout for a virtual memory buffer. + +An MDL consists of an [**MDL**](https://msdn.microsoft.com/library/windows/hardware/ff554414) structure that is followed by an array of data that describes the physical memory in which the I/O buffer resides. The size of an MDL varies according to the characteristics of the I/O buffer that the MDL describes. System routines are available to calculate the required size of an MDL and to allocate and free the MDL. + +An MDL structure is semi-opaque. Your driver should directly access only the **Next** and **MdlFlags** members of this structure. For a code example that uses these two members, see the following Example section. + +The remaining members of an MDL are opaque. Do not access the opaque members of an MDL directly. Instead, use the following macros, which the operating system provides to perform basic operations on the structure: + +[**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) returns the virtual memory address of the I/O buffer that is described by the MDL. + +[**MmGetMdlByteCount**](https://msdn.microsoft.com/library/windows/hardware/ff554530) returns the size, in bytes, of the I/O buffer. + +[**MmGetMdlByteOffset**](https://msdn.microsoft.com/library/windows/hardware/ff554533) returns the offset within a physical page of the beginning of the I/O buffer. + +You can allocate an MDL with the [**IoAllocateMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548263) routine. To free the MDL, use the [**IoFreeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff549126) routine. Alternatively, you can allocate a block of nonpaged memory and then format this block of memory as an MDL by calling the [**MmInitializeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff554568) routine. + +Neither **IoAllocateMdl** nor **MmInitializeMdl** initializes the data array that immediately follows the MDL structure. For an MDL that resides in a driver-allocated block of nonpaged memory, use [**MmBuildMdlForNonPagedPool**](https://msdn.microsoft.com/library/windows/hardware/ff554498) to initialize this array to describe the physical memory in which the I/O buffer resides. + +For pageable memory, the correspondence between virtual and physical memory is temporary, so the data array that follows the MDL structure is valid only under certain circumstances. Call [**MmProbeAndLockPages**](https://msdn.microsoft.com/library/windows/hardware/ff554664) to lock the pageable memory into place and to initialize this data array for the current layout. The memory will not be paged out until the caller uses the [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) routine, at which point the contents of the data array are no longer valid. + +The [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) routine maps the physical pages that are described by the specified MDL to a virtual address in system address space, if they are not already mapped to system address space. This virtual address is useful for drivers that might have to look at the pages to perform I/O, because the original virtual address might be a user address that can be used only in its original context and can be deleted at any time. + +Note that when you build a partial MDL by using the [**IoBuildPartialMdl**](https://msdn.microsoft.com/library/windows/hardware/ff548324) routine, the caller should use **MmGetMdlVirtualAddress** instead of the **MmGetSystemAddressForMdlSafe** routine when determining the virtual address to pass in. **IoBuildPartialMdl** uses the address that **MmGetMdlVirtualAddress** returns from the source MDL to determine the offset for the target MDL. If the addresses are different (for example, when the first address is a user address), passing the address that **MmGetSystemAddressForMdlSafe** returns can cause data corruption or a bug check. + +When a driver calls **IoAllocateMdl**, it can associate an IRP with the newly allocated MDL by specifying a pointer to the IRP as the *Irp* parameter of **IoAllocateMdl**. An IRP can have one or more MDLs associated with it. If the IRP has a single MDL associated with it, the IRP's **MdlAddress** member points to that MDL. If the IRP has multiple MDLs associated with it, **MdlAddress** points to the first MDL in a linked list of MDLs that are associated with the IRP, known as an *MDL chain*. The MDLs are linked by their **Next** members. The **Next** member of the last MDL in the chain is set to **NULL**. + +If, when the driver calls **IoAllocateMdl**, it specifies **FALSE** for the *SecondaryBuffer* parameter, the IRP's **MdlAddress** member is set to point to the new MDL. If *SecondaryBuffer* is **TRUE**, the routine inserts the new MDL at the end of the MDL chain. + +When the IRP is completed, the system unlocks and frees all the MDLs that are associated with the IRP. The system unlocks the MDLs before it queues the I/O completion routine and frees them after the I/O completion routine executes. + +Drivers can traverse the MDL chain by using the **Next** member of each MDL to access the next MDL in the chain. Drivers can manually insert MDLs into the chain by updating the **Next** members. + +MDL chains are typically used to manage an array of buffers that are associated with a single I/O request. (For example, a network driver could use one buffer for each IP packet in a network operation.) Each buffer in the array has its own MDL in the chain. When the driver completes the request, it combines the buffers into a single large buffer. The system then automatically cleans up all the allocated MDLs for the request. + +The [I/O manager](windows-kernel-mode-i-o-manager.md) is a frequent source of I/O requests. When the I/O manager completes an I/O request, the I/O manager frees the IRP and frees any MDLs that are attached to the IRP. Some of these MDLs might have been attached to the IRP by drivers that are located beneath the I/O manager in the device stack. Similarly, if your driver is the source of an I/O request, your driver must clean up the IRP and any MDLs that are attached to the IRP when the I/O request completes. + +### Example + +The following code example is a driver-implemented function that frees an MDL chain from an IRP: + +``` +VOID MyFreeMdl(PMDL Mdl) +{ + PMDL currentMdl, nextMdl; + + for (currentMdl = Mdl; currentMdl != NULL; currentMdl = nextMdl) + { + nextMdl = currentMdl->Next; + if (currentMdl->MdlFlags & MDL_PAGES_LOCKED) + { + MmUnlockPages(currentMdl); + } + IoFreeMdl(currentMdl); + } +} +``` + +If the physical pages that are described by an MDL in the chain are locked, the example function calls the [**MmUnlockPages**](https://msdn.microsoft.com/library/windows/hardware/ff556381) routine to unlock the pages before it calls [**IoFreeMdl**](https://msdn.microsoft.com/library/windows/hardware/ff549126) to free the MDL. However, the example function does not need to explicitly unmap the pages before it calls **IoFreeMdl**. Instead, **IoFreeMdl** automatically unmaps the pages when it frees the MDL. + +For a summary of the system routines that allocate, free, and manage MDLs, see [Address Mappings and MDLs](https://msdn.microsoft.com/library/windows/hardware/ff540568). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20MDLs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-message-signaled-interrupts.md b/windows-driver-docs-pr/kernel/using-message-signaled-interrupts.md new file mode 100644 index 0000000000..5781f8b865 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-message-signaled-interrupts.md @@ -0,0 +1,35 @@ +--- +title: Using Message-Signaled Interrupts +author: windows-driver-content +description: Using Message-Signaled Interrupts +ms.assetid: 5e1f8648-378f-4d5b-b936-4396d13cf002 +keywords: ["message-signaled interrupts WDK kernel , filtering", "filtering message-signaled interrupts WDK kernel", "MSIs WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Message-Signaled Interrupts + + +This section contains the following topics: + +[Introduction to Message-Signaled Interrupts](introduction-to-message-signaled-interrupts.md) + +[Enabling Message-Signaled Interrupts in the Registry](enabling-message-signaled-interrupts-in-the-registry.md) + +[Using Interrupt Resource Descriptors](using-interrupt-resource-descriptors.md) + +[Dynamically Configuring MSI-X](dynamically-configuring-msi-x.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Message-Signaled%20Interrupts%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-neither-buffered-nor-direct-i-o.md b/windows-driver-docs-pr/kernel/using-neither-buffered-nor-direct-i-o.md new file mode 100644 index 0000000000..515f4eeb44 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-neither-buffered-nor-direct-i-o.md @@ -0,0 +1,49 @@ +--- +title: Using Neither Buffered Nor Direct I/O +author: windows-driver-content +description: Using Neither Buffered Nor Direct I/O +ms.assetid: e85af2e0-e532-47ca-918e-087e7aff859e +keywords: ["buffers WDK I/O , neither buffered nor direct I/O", "data buffers WDK I/O , neither buffered nor direct I/O", "neither buffered nor direct I/O WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Neither Buffered Nor Direct I/O + + +## + + +If a driver is using neither buffered nor direct I/O, then the I/O manager passes the original user-space virtual addresses in IRPs that it sends to the driver. To access these buffers safely, the driver must be executing in the context of the calling thread. Typically, therefore, only highest-level drivers, such as FSDs, can use this method for accessing buffers. + +An intermediate or lowest-level driver cannot always meet this condition. For example, if a requesting thread waits on the completion of an I/O request or if a higher-level driver is layered over the intermediate or lowest-level driver, then the lower-level driver's routines are unlikely to be called in the context of the requesting thread. + +The I/O manager determines that an I/O operation is using neither buffered nor direct I/O as follows: + +- For [**IRP\_MJ\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff550794) and [**IRP\_MJ\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/ff550819) requests, neither DO\_BUFFERED\_IO nor DO\_DIRECT\_IO are set in the **Flags** member of the [**DEVICE\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure. For more information, see [Initializing a Device Object](initializing-a-device-object.md). + +- For [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) and [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests, the IOCTL code's value contains METHOD\_NEITHER as the *TransferType* value in the IOCTL value. For more information, see [Defining I/O Control Codes](defining-i-o-control-codes.md). + +When a driver receives an IRP that specifies an I/O operation using neither buffered nor direct I/O, it must do the following: + +1. Check the validity of the user buffer's address range and check whether the appropriate read or write access is permitted, using the [**ProbeForRead**](https://msdn.microsoft.com/library/windows/hardware/ff559876) and [**ProbeForWrite**](https://msdn.microsoft.com/library/windows/hardware/ff559879) support routines. The driver must enclose its accesses to the buffer's address range within a driver-supplied exception handler, so that a user thread cannot change the access rights for the buffer while the driver is accessing memory. If the probe raises an exception, the driver should return an error. The driver must call these routines within the context of the thread that made the I/O request; therefore, only a higher-level driver can perform this task. + +2. Manage buffers and memory operations in one of the following ways: + - Carry out its own double-buffering operations, as the I/O manager does for drivers that use buffered I/O. For more information, see [Using Buffered I/O](using-buffered-i-o.md). + - Create its own MDLs and lock down the buffer by calling the memory manager's support routines, as the I/O manager does for drivers that use direct I/O. For more information, see [Using Direct I/O](using-direct-i-o.md). + - Perform all necessary operations on the user buffer directly in the context of the calling thread. The driver must wrap its access to the buffer within a driver-supplied exception handler, in case a user thread changes either the access rights for the buffer or the data in the buffer while the driver is accessing memory. For more information, see [Handling Exceptions](handling-exceptions.md). + +In effect, the driver must choose on a per-IRP basis whether to do buffered I/O, direct I/O, or I/O in the context of the calling thread, and it must handle any exceptions that might occur in a user-mode thread context. The driver must manage its own user buffer accesses, double-buffering operations, and memory mappings, as necessary, instead of letting the I/O manager handle these operations for the driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Neither%20Buffered%20Nor%20Direct%20I/O%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines.md b/windows-driver-docs-pr/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines.md new file mode 100644 index 0000000000..e83d5444e9 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines.md @@ -0,0 +1,49 @@ +--- +title: Using Nt and Zw Versions of the Native System Services Routines +author: windows-driver-content +description: Using Nt and Zw Versions of the Native System Services Routines +ms.assetid: 89627ddb-621d-4d27-acd6-16308689165d +keywords: ["Native System Services API WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Nt and Zw Versions of the Native System Services Routines + + +The Windows native operating system services API is implemented as a set of routines that run in kernel mode. These routines have names that begin with the prefix **Nt** or **Zw**. Kernel-mode drivers can call these routines directly. User-mode applications can access these routines by using system calls. + +With a few exceptions, each native system services routine has two slightly different versions that have similar names but different prefixes. For example, calls to [NtCreateFile](http://go.microsoft.com/fwlink/p/?linkid=157250) and [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424) perform similar operations and are, in fact, serviced by the same kernel-mode system routine. For system calls from user mode, the **Nt** and **Zw** versions of a routine behave identically. For calls from a kernel-mode driver, the **Nt** and **Zw** versions of a routine differ in how they handle the parameter values that the caller passes to the routine. + +A kernel-mode driver calls the **Zw** version of a native system services routine to inform the routine that the parameters come from a trusted, kernel-mode source. In this case, the routine assumes that it can safely use the parameters without first validating them. However, if the parameters might be from either a user-mode source or a kernel-mode source, the driver instead calls the **Nt** version of the routine, which determines, based on the history of the calling thread, whether the parameters originated in user mode or kernel mode. For more information about how the routine distinguishes user-mode parameters from kernel-mode parameters, see [**PreviousMode**](previousmode.md). + +When a user-mode application calls the **Nt** or **Zw** version of a native system services routine, the routine always treats the parameters that it receives as values that come from a user-mode source that is not trusted. The routine thoroughly validates the parameter values before it uses the parameters. In particular, the routine probes any caller-supplied buffers to verify that the buffers are located in valid user-mode memory and are aligned properly. + +Native system services routines make additional assumptions about the parameters that they receive. If a routine receives a pointer to a buffer that was allocated by a kernel-mode driver, the routine assumes that the buffer was allocated in system memory, not in user-mode memory. If the routine receives a handle that was opened by a user-mode application, the routine looks for the handle in the user-mode handle table, not in the kernel-mode handle table. + +In a few instances, the meaning of a parameter value differs more significantly between calls from user mode and from kernel mode. For example, the [**ZwNotifyChangeKey**](https://msdn.microsoft.com/library/windows/hardware/ff566488) routine (or its **NtNotifyChangeKey** counterpart) has a pair of input parameters, *ApcRoutine* and *ApcContext*, that mean different things, depending on whether the parameters are from a user-mode or kernel-mode source. For a call from user mode, *ApcRoutine* points to an APC routine and *ApcContext* points to a context value that the operating system supplies when it calls the APC routine. For a call from kernel mode, *ApcRoutine* points to a [**WORK\_QUEUE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff557304) structure, and *ApcContext* specifies the type of work queue item that is described by the **WORK\_QUEUE\_ITEM** structure. + +This section includes the following topics: + +[**PreviousMode**](previousmode.md) + +[Libraries and Headers](libraries-and-headers.md) + +[What Does the Zw Prefix Mean?](what-does-the-zw-prefix-mean-.md) + +[Specifying Access Rights](access-mask.md) + +[NtXxx Routines](ntxxx-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Nt%20and%20Zw%20Versions%20of%20the%20Native%20System%20Services%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-ntstatus-values.md b/windows-driver-docs-pr/kernel/using-ntstatus-values.md new file mode 100644 index 0000000000..b7f73dde51 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-ntstatus-values.md @@ -0,0 +1,54 @@ +--- +title: Using NTSTATUS Values +author: windows-driver-content +description: Using NTSTATUS Values +ms.assetid: fe823930-e3ff-4c95-a640-bb6470c95d1d +keywords: ["NTSTATUS values WDK kernel", "driver support routines WDK kernel", "return values WDK kernel", "testing return values WDK NTSTATUS values", "success values WDK NTSTATUS values", "informational values WDK NTSTATUS values", "warnings WDK NTSTATUS values", "error values WDK NTSTATUS values", "status information WDK NTSTATUS values", "checking return values"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using NTSTATUS Values + + +## + + +Many kernel-mode [standard driver routines](https://msdn.microsoft.com/library/windows/hardware/ff563842) and [driver support routines](https://msdn.microsoft.com/library/windows/hardware/ff563889) use the NTSTATUS type for return values. Additionally, drivers provide an NTSTATUS-typed value in an IRP's [**IO\_STATUS\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/ff550671) structure when [completing IRPs](completing-irps.md). The NTSTATUS type is defined in Ntdef.h, and system-supplied status codes are defined in Ntstatus.h. (Vendors can also define private status codes, although they rarely need to. For more information, see [Defining New NTSTATUS Values](defining-new-ntstatus-values.md).) + +NTSTATUS values are divided into four types: success values, informational values, warnings, and error values. + +Numerous values are assigned to each type. A common mistake, when testing for a successful return from a routine, is to compare the routine's return value with STATUS\_SUCCESS. This comparison checks for only one of several success values. + +When testing a return value, you should use one of the following system-supplied macros (defined in Ntdef.h): + +NT\_SUCCESS(*Status*) +Evaluates to **TRUE** if the return value specified by *Status* is a success type (0 − 0x3FFFFFFF) or an informational type (0x40000000 − 0x7FFFFFFF). + +NT\_INFORMATION(*Status*) +Evaluates to **TRUE** if the return value specified by *Status* is an informational type (0x40000000 − 0x7FFFFFFF). + +NT\_WARNING(*Status*) +Evaluates to **TRUE** if the return value specified by *Status* is a warning type (0x80000000 − 0xBFFFFFFF). + +NT\_ERROR(*Status*) +Evaluates to **TRUE** if the return value specified by *Status* is an error type (0xC0000000 - 0xFFFFFFFF). + +For example, suppose a driver calls [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) to register a device interface. If the driver checks the return value using the NT\_SUCCESS macro, the macro will evaluate to **TRUE** if the routine returns STATUS\_SUCCESS, which indicates no errors, or if it returns the informational status STATUS\_OBJECT\_NAME\_EXISTS, which indicates that the device interface is already registered. + +As another example, suppose a driver calls [**ZwEnumerateKey**](https://msdn.microsoft.com/library/windows/hardware/ff566447) to enumerate the subkeys of a specified registry key. If the NT\_SUCCESS macro evaluates to **FALSE**, it might be because the routine returned STATUS\_INVALID\_PARAMETER, which is an error code, or because the routine returned STATUS\_NO\_MORE\_ENTRIES, which is a warning code. + +As a final example, suppose a driver sends an IRP that causes a lower-level driver to read information from a device. If the requesting driver specifies a buffer that is too small to receive any information, the lower-level driver might respond by returning STATUS\_BUFFER\_TOO\_SMALL, which is an error code. If the first driver specifies a buffer that can receive some, but not all, of the requested information, the lower-level driver might respond by supplying as much data as possible and then returning STATUS\_BUFFER\_OVERFLOW, which is a warning code. Note that if the first driver tests the status value using NT\_SUCCESS or NT\_ERROR incorrectly, it might inadvertently drop some of the information received. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20NTSTATUS%20Values%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-packet-based-bus-master-dma.md b/windows-driver-docs-pr/kernel/using-packet-based-bus-master-dma.md new file mode 100644 index 0000000000..271b6a1b4b --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-packet-based-bus-master-dma.md @@ -0,0 +1,50 @@ +--- +title: Using Packet-Based Bus-Master DMA +author: windows-driver-content +description: Using Packet-Based Bus-Master DMA +ms.assetid: 57b37103-8ae0-4c54-b613-55b1a629d9ae +keywords: ["bus-master DMA WDK kernel", "DMA transfers WDK kernel , bus-master DMA", "adapter objects WDK kernel , bus-master DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Packet-Based Bus-Master DMA + + +## + + +To use packet-based DMA, drivers of bus-master DMA devices call the following general sequence of support routines as they process an IRP requesting a DMA transfer: + +- [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) just before attempting to allocate map registers for a transfer request (for more information, see [Maintaining Cache Coherency](maintaining-cache-coherency.md)) + +- [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) when the driver is ready to program the bus-master adapter for DMA + +- [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) to get an index into the MDL, required as an initial parameter to [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402), and **MapTransfer** to make the system physical memory that backs the IRP's buffer device-accessible + + Note that any driver might need to carry out more than one transfer operation in order to satisfy the current IRP, as explained in [Splitting Transfer Requests](splitting-dma-transfer-requests.md). Drivers of devices that do not have scatter/gather capabilities can call **MapTransfer** once per transfer operation. Drivers of devices that have scatter/gather capabilities can call **MapTransfer** more than once to set up each transfer operation. Alternatively, these drivers can use the system's built-in scatter/gather support, described in [Using Scatter/Gather DMA](using-scatter-gather-dma.md). + +- [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) at the end of each DMA transfer operation to/from the target device, in order to determine whether all the requested data has been completely transferred + +- [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) as soon as all DMA operations for the current IRP are done, because all the requested data has been completely transferred or because the driver must fail the IRP due to a device or bus I/O error + +The adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) is a required parameter to **AllocateAdapterChannel**, **MapTransfer**, **FlushAdapterBuffers**, and **FreeMapRegisters**. Note that in versions of Windows NT prior to Windows 2000, bus-master devices could pass a **NULL** adapter object pointer to **MapTransfer** and **FlushAdapterBuffers**. In Windows 2000 and later, drivers can no longer do so. + +**KeFlushIoBuffers** and **MmGetMdlVirtualAddress** require a pointer to the MDL at **Irp->MdlAddress**. + +Individual drivers call this sequence of support routines at different points, depending on how each driver is implemented to service its device. For example, one driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine might make the call to **AllocateAdapterChannel**, while another driver might make this call from a routine that removes IRPs from a driver-created interlocked queue or device queue. + +Instead of using the routines described in this section, any driver that uses packet-based DMA can use support routines intended to streamline scatter/gather DMA, regardless of whether its device has built-in scatter/gather support. See [Using Scatter/Gather DMA](using-scatter-gather-dma.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Packet-Based%20Bus-Master%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-packet-based-system-dma.md b/windows-driver-docs-pr/kernel/using-packet-based-system-dma.md new file mode 100644 index 0000000000..7eb10dae6a --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-packet-based-system-dma.md @@ -0,0 +1,52 @@ +--- +title: Using Packet-Based System DMA +author: windows-driver-content +description: Using Packet-Based System DMA +ms.assetid: 5d175193-4a28-49fd-80b5-18f116232c6e +keywords: ["system DMA WDK kernel , packet-based", "packet-based DMA WDK kernel", "DMA transfers WDK kernel , packet-based"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Packet-Based System DMA + + +## + + +Drivers of subordinate devices that use packet-based DMA call the following general sequence of support routines as they process an IRP requesting a DMA transfer: + +- [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) just before attempting to allocate the system DMA controller (for more information, see [Maintaining Cache Coherency](maintaining-cache-coherency.md)) + +- [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573) when the driver is ready to program its device for DMA and needs the system DMA controller + + **AllocateAdapterChannel**, in turn, calls the driver's [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine. + +- [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) to get an index into the MDL, required as an parameter in the initial call to **MapTransfer** + +- [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) to program the system DMA controller for the transfer operation + + A driver might need to call **MapTransfer** more than once to transfer all the requested data, as explained in [Splitting Transfer Requests](splitting-dma-transfer-requests.md). + +- [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) just after each DMA transfer operation to/from the subordinate device + + If a driver must call **MapTransfer** more than once to transfer all the requested data, it must call **FlushAdapterBuffers** as many times as it calls **MapTransfer**. + +- [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) either as soon as all the requested data has been transferred or if the driver fails the IRP because of a device I/O error + +The adapter object pointer returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) is a required parameter to each of these routines except **KeFlushIoBuffers** and **MmGetMdlVirtualAddress**, which require the pointer to the MDL passed at **Irp->MdlAddress**. + +Individual drivers call this sequence of support routines at different points, depending on how each driver is implemented to service its device. For example, one driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine might make the call to **AllocateAdapterChannel**, another driver might make this call from a routine that removes IRPs from a driver-created interlocked queue, and still another driver might make this call when its subordinate DMA device indicates it is ready to transfer data. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Packet-Based%20System%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-passive-level-interrupt-handling-routines.md b/windows-driver-docs-pr/kernel/using-passive-level-interrupt-handling-routines.md new file mode 100644 index 0000000000..146ba0a383 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-passive-level-interrupt-handling-routines.md @@ -0,0 +1,67 @@ +--- +title: Using Passive-Level Interrupt Service Routines +author: windows-driver-content +description: Starting with Windows 8, a driver can use the IoConnectInterruptEx routine to register a passive-level InterruptService routine (ISR). +ms.assetid: 122BDE14-1552-4F7B-88D3-030423713E00 +--- + +# Using Passive-Level Interrupt Service Routines + + +Starting with Windows 8, a driver can use the [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) routine to register a passive-level [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine (ISR). When the associated interrupt occurs, the kernel's interrupt trap handler schedules this routine to run at IRQL = PASSIVE\_LEVEL. An ISR might need to run at passive level if it can access the hardware registers of a device only through I/O requests. A passive-level ISR can synchrononously send an I/O request to a device and block until the request completes. + +## Registering a Passive-Level ISR + + +The input parameter to **IoConnectInterruptEx** is a pointer to an [**IO\_CONNECT\_INTERRUPT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff550541) structure. To register a passive-level ISR, set the **Version** member of this structure to either CONNECT\_FULLY\_SPECIFIED or CONNECT\_LINE\_BASED. If **Version** = CONNECT\_FULLY\_SPECIFIED, set the **Irql** member to PASSIVE\_LEVEL, the **SynchronizeIrql** member to PASSIVE\_LEVEL, and the **SpinLock** member to **NULL**. If **Version** = CONNECT\_LINE\_BASED, set **SynchronizeIrql** = PASSIVE\_LEVEL and **SpinLock** = **NULL**. + +If the interrupt object specifies a passive-level ISR, the [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) routine uses a kernel synchronization event object instead of a spin lock to synchronize execution of the [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine with the ISR. + +This event object is allocated by the **IoConnectInterruptEx** routine in the call that registers the passive-level ISR. The caller must not supply a spin lock in this call. (That is, the caller must set the **SpinLock** member of the **IO\_CONNECT\_INTERRUPT\_PARAMETERS** structure to NULL if the ISR is to run at passive level.) Otherwise, **IoConnectInterruptEx** fails and returns error status STATUS\_INVALID\_PARAMETER. + +The [**KeAcquireInterruptSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551914) and [**KeReleaseInterruptSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553139) routines cause a bug check if the ISR for the supplied interrupt object runs at IRQL = PASSIVE\_LEVEL. + +## Devices that Require Passive-Level Interrupt Handling + + +For a memory-mapped device that signals a level-triggered interrupt request, the device's ISR is typically called at DIRQL from within the kernel's interrupt trap handler. The ISR manipulates the hardware registers in the device to turn off the interrupt. + +However, an ISR might need to run at IRQL = PASSIVE\_LEVEL if the associated device signals a level-triggered interrupt request but the device's hardware registers cannot be accessed directly from an ISR that is called at DIRQL from within the kernel's interrupt trap handler. For example, the device registers might not be memory-mapped, or the ISR might be temporarily blocked during a register access. + +Starting with Windows 8, a driver can register a passive-level ISR. When the interrupt occurs, the kernel's interrupt trap handler schedules the ISR to run at IRQL = PASSIVE\_LEVEL. Before the handler returns, it must silence the interrupt in the interrupt controller (or [GPIO controller](https://msdn.microsoft.com/library/windows/hardware/hh439512)). If a device signals an edge-triggered interrupt, the handler clears the interrupt in the interrupt controller. If the device signals a level-triggered interrupt, the handler temporarily masks the interrupt in the interrupt controller; after the ISR runs, the kernel unmasks the interrupt. + +## An Example + + +An example of a device that might require a passive-level ISR is a sensor device that is connected to a low-power serial bus, such as I²C. Starting with Windows 8, support for I²C and for other [simple peripheral buses](https://msdn.microsoft.com/library/windows/hardware/hh450903) (SPBs) is provided by the [SPB framework extension](https://msdn.microsoft.com/library/windows/hardware/hh406203) (SpbCx). + +To access the registers of the I²C-connected sensor device, the sensor driver sends the sensor device an I/O request, which is jointly handled by SpbCx and by the controller driver for the bus. To perform the requested operation, the SPB controller must transfer data serially over the bus. This transfer is relatively slow and cannot be performed within the time constraints of an ISR that runs at DIRQL. However, a passive-level ISR can send the I/O request synchronously and then block until the request completes. + +The passive-level ISR in this example might be blocked for a longer time if the I²C bus controller is turned off when the ISR sends the I/O request to the interrupting device. In this case, the controller must complete the transition to the D0 power state before it can transfer the data over the bus. + +In contrast to a bus such as PCI, the I²C bus in this example provides no bus-specific means to convey interrupt requests from peripheral devices to the processor. Instead, the sensor device might signal an interrupt to a pin on a GPIO controller device, which then relays the interrupt request to the processor. For more information, see [GPIO Interrupts](https://msdn.microsoft.com/library/windows/hardware/hh406467). + +Typically, the hardware registers of a GPIO controller are memory-mapped and can be accessed at DIRQL by the kernel's interrupt trap handler. When the sensor device causes an interrupt, the handler must silence the interrupt by manipulating the interrupt bits in the GPIO controller's registers. + +For a level-triggered interrupt, the kernel's interrupt trap handler masks the interrupt request at the GPIO pin, and then schedules the sensor device's ISR to run at passive level. The ISR must clear the interrupt request from the sensor device. After the ISR returns, the kernel unmasks the interrupt request at the GPIO pin. + +For an edge-triggered interrupt, the kernel's trap handler clears the interrupt request at the GPIO pin, and then schedules the sensor device's ISR to run at passive level. + +## Worker Routines + + +In the call to **IoConnectInterruptEx**, a driver has the option to split the processing of the interrupt between a passive-level ISR and a worker routine. As a general rule, the ISR should do the initial processing of the interrupt (for example, silence a level-triggered interrupt), and defer additional processing to the worker. Although both the ISR and worker run at passive level, the ISR runs at a relatively high priority and might delay other high-priority tasks. These tasks might include passive-level ISRs for new interrupts. + +In rare cases, an interrupt might require so little processing that the passive-level ISR can perform all of the processing for the interrupt, and no worker routine is required. + +For information about using passive-level ISRs in KMDF drivers, see [Supporting Passive-Level Interrupts](https://msdn.microsoft.com/library/windows/hardware/hh451035). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Passive-Level%20Interrupt%20Service%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-peps-for-acpi-services.md b/windows-driver-docs-pr/kernel/using-peps-for-acpi-services.md new file mode 100644 index 0000000000..0bab6f2412 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-peps-for-acpi-services.md @@ -0,0 +1,45 @@ +--- +title: Using PEPs for ACPI services +author: windows-driver-content +description: This topic provides information about using platform extension plug-ins (PEPs) for ACPI services. +ms.assetid: 80ED3B80-A1FF-4A41-BA88-EC1C832C4639 +--- + +# Using PEPs for ACPI services + + +This topic provides information about using platform extension plug-ins (PEPs) for ACPI services. + +PEPs provide dynamic, runtime ACPI methods. The static tables (FADT, MADT, DBG2, etc.) must be implemented in the ACPI firmware, as well as the DSDT/SSDT device hierarchy. + +PEPs are intended to be used for off-SoC power management methods. Since they are installable binaries, they can be updated on-the-fly as opposed to ACPI firmware which requires a firmware flash. This means you could improve your power management code on platforms that you’ve already shipped by posting an updated driver on Windows Update. Power management was the original intent for PEPs, but they can be used to provide or override any arbitrary ACPI runtime method. + +PEPs play no role in the construction of the ACPI namespace hierarchy because the namespace hierarchy must be provided in the firmware DSDT. When the ACPI driver evaluates a method at runtime, it will check against the PEP’s implemented methods for the device in question, and, if present, it will execute the PEP and ignore the firmware’s version. However, the device itself must be defined in the firmware. + +Providing power management using PEPs can be much easier to debug than code written for the ACPI firmware because of the tools available. Tools for debugging ACPI firmware are unfamiliar to most and tool options are limited. In contrast, PEPs are developed as Windows drivers so developers can use whatever development and debugging tools they are most comfortable with. + +When using a PEP in place of an ACPI service, no special action or operation is needed in order to claim the role of the service. When a method is implemented in the PEP, Windows will use it automatically. If a firmware version of the same method on the same device is provided, it will be ignored. + +PEPs are loaded very early so that their services are available for the device driver. Additionally, the abstraction layer through Windows is designed to be transparent to device drivers. The driver should expect to be able to interact with its ACPI methods as if a PEP weren't in use. + +When using PEP for both device power management (DPM) and ACPI services, it's advisable to use separate PEP handles, but this is only a matter of preference. When sharing the handle DPM and ACPI state can be tracked easily for a device because the handle is the same. However, handle lifetime management is a little more complicated. The PEP will need to provide reference counting for the handle to make sure it is only deleted after both DPM and ACPI services have been torn down for that handle (i.e., both [**PEP\_DPM\_UNREGISTER\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/mt186742) and [**PEP\_NOTIFY\_ACPI\_UNREGISTER\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/mt186758) have been received on that handle). When different handles are used, DPM and ACPI state will be tracked separately, but handle lifetime management is simpler. In this case, the handle can be destroyed when the corresponding unregister notification is sent. + +To simplify the process of working with ACPI resources, the power management framework (PoFx) provides the PEP\_REQUEST\_COMMON\_ACPI\_CONVERT\_TO\_BIOS\_RESOURCES helper routine to convert ACPI resources to BIOS resources. + +PEPs are responsible for scheduling work that cannot be performed synchronously in response to an ACPI notification from PoFx but the method used is determined by the PEP developer. Typically, the PEP will queue the work on some internal queue and then start a worker thread if needed. It is also possible that the work needs to wait for some external event (e.g. device interrupt) and will be processed in the context of that event. Once the work is done, a PEP can request PoFx to query for work by invoking [**PEP\_KERNEL\_INFORMATION\_STRUCT\_V3**](https://msdn.microsoft.com/library/windows/hardware/mt186747)->[*RequestWorker*](https://msdn.microsoft.com/library/windows/hardware/mt186884)(). In response, PoFx will send a [**PEP\_DPM\_WORK notification**](https://msdn.microsoft.com/library/windows/hardware/mt186743) for PEPs that implement the DPM notification handler ([*AcceptDeviceNotification*](https://msdn.microsoft.com/library/windows/hardware/mt186626)) or a [**PEP\_NOTIFY\_ACPI\_WORK notification**](https://msdn.microsoft.com/library/windows/hardware/mt188089) for PEPs that implement the ACPI-only notification handler ([*AcceptAcpiNotification*](https://msdn.microsoft.com/library/windows/hardware/mt186625)). + +## Related topics +[ACPI system description tables](https://msdn.microsoft.com/library/Dn495660.aspx) +[**PEP\_DPM\_UNREGISTER\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/mt186742) +[**PEP\_NOTIFY\_ACPI\_UNREGISTER\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/mt186758) +[**PEP\_KERNEL\_INFORMATION\_STRUCT\_V3**](https://msdn.microsoft.com/library/windows/hardware/mt186747) +[**PEP\_DPM\_WORK**](https://msdn.microsoft.com/library/windows/hardware/mt186743) +[**PEP\_NOTIFY\_ACPI\_WORK**](https://msdn.microsoft.com/library/windows/hardware/mt188089) +[*RequestWorker*](https://msdn.microsoft.com/library/windows/hardware/mt186884) +[*AcceptDeviceNotification*](https://msdn.microsoft.com/library/windows/hardware/mt186626) +[ACPI notifications](https://msdn.microsoft.com/library/windows/hardware/mt186628) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PEPs%20for%20ACPI%20services%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-pnp-custom-notification.md b/windows-driver-docs-pr/kernel/using-pnp-custom-notification.md new file mode 100644 index 0000000000..d94c55b9be --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-pnp-custom-notification.md @@ -0,0 +1,58 @@ +--- +title: Using PnP Custom Notification +author: windows-driver-content +description: Using PnP Custom Notification +ms.assetid: de5562f8-07a8-4f4e-ac49-58c789bd9fde +keywords: ["notifications WDK PnP , custom", "custom notifications WDK PnP", "notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PnP Custom Notification + + +## + + +A driver can use the target device change notification mechanism to be notified of custom events on a device. + +The programmer that defines the custom event must do the following: + +1. Define a new GUID for the custom event. + + Generate the GUID with **Uuidgen** or **Guidgen** (which are included in the Microsoft Windows SDK). Publish the GUID in an appropriate header file and documentation. + +2. Write code to trigger the custom event. + + In kernel mode, a driver calls [**IoReportTargetDeviceChange**](https://msdn.microsoft.com/library/windows/hardware/ff549625) with the custom GUID and a pointer to the PDO for the device. Custom events can only be triggered from kernel mode. + +A driver writer uses custom notification with a procedure like the following: + +1. The driver (or application) registers for notification of the custom event. + + In kernel mode, a driver calls [**IoRegisterPlugPlayNotification**](https://msdn.microsoft.com/library/windows/hardware/ff549526) and registers for an **EventCategoryTargetDeviceChange** on the device. + + In user mode, an application registers using **RegisterDeviceNotification**. See the Windows SDK for further information. + +2. A kernel-mode component triggers the custom event. + +3. The PnP manager calls notification routines registered on the device. + + The PnP manager calls the registered user-mode callback routines and then calls the kernel-mode callback routines. + +4. When user-mode notification is complete, the kernel-mode driver notification callback routine(s) respond to the custom event. + + See [Guidelines for Writing PnP Notification Callback Routines](guidelines-for-writing-pnp-notification-callback-routines.md) for general guidelines for notification callback routines. In addition to those guidelines, a custom notification callback routine must not open a handle to a device from within the callback routine thread. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PnP%20Custom%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-pnp-device-interface-change-notification.md b/windows-driver-docs-pr/kernel/using-pnp-device-interface-change-notification.md new file mode 100644 index 0000000000..1f4d1d7d25 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-pnp-device-interface-change-notification.md @@ -0,0 +1,38 @@ +--- +title: Using PnP Device Interface Change Notification +author: windows-driver-content +description: Using PnP Device Interface Change Notification +ms.assetid: 2ed3518a-601f-4e9b-b375-a9fb62c937a9 +keywords: ["notifications WDK PnP , device interface changes", "EventCategoryDeviceInterfaceChange notification", "device interface change notifications WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PnP Device Interface Change Notification + + +## + + +A driver registers for **EventCategoryDeviceInterfaceChange** notification so the driver can be notified when device interfaces of a particular class arrive (are enabled) or are removed (disabled) on the machine. For example, a composite battery driver might register for notification of device interfaces of class battery so it can provide information to the operating system about total available battery power. + +The following subsections discuss how to register for device interface change notification and how to handle device interface change events in a PnP notification callback routine: + +[Registering for Device Interface Change Notification](registering-for-device-interface-change-notification.md) + +[Handling Device Interface Change Events](handling-device-interface-change-events.md) + +See [**IoRegisterDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff549506) and related routines For information about device interfaces. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PnP%20Device%20Interface%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-pnp-hardware-profile-change-notification.md b/windows-driver-docs-pr/kernel/using-pnp-hardware-profile-change-notification.md new file mode 100644 index 0000000000..8411c0ba79 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-pnp-hardware-profile-change-notification.md @@ -0,0 +1,36 @@ +--- +title: Using PnP Hardware Profile Change Notification +author: windows-driver-content +description: Using PnP Hardware Profile Change Notification +ms.assetid: 341464e4-507d-43da-88a2-5bfecd2dd02a +keywords: ["notifications WDK PnP , hardware profile changes", "hardware profile change notifications WDK PnP", "EventCategoryHardwareProfileChange notification", "profile change notifications WDK PnP", "machine hardware profile change notifications WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PnP Hardware Profile Change Notification + + +## + + +A driver registers for **EventCategoryHardwareProfileChange** notification so the driver can be notified when the machine transitions from one hardware profile to another. For example, a driver can use this mechanism to be notified when a laptop is docked or undocked. + +The following subsections discuss how to register for hardware profile change notification and how to handle hardware profile change events in a PnP notification callback routine: + +[Registering for Hardware Profile Change Notification](registering-for-hardware-profile-change-notification.md) + +[Handling Hardware Profile Change Events](handling-hardware-profile-change-events.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PnP%20Hardware%20Profile%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-pnp-notification.md b/windows-driver-docs-pr/kernel/using-pnp-notification.md new file mode 100644 index 0000000000..db8dc7c82f --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-pnp-notification.md @@ -0,0 +1,32 @@ +--- +title: Using PnP Notification +author: windows-driver-content +description: Using PnP Notification +ms.assetid: cc6c9106-37b3-473c-bbd2-89701d698fdf +keywords: ["notifications WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PnP Notification + + +## + + +In a PnP environment, drivers and applications need to react to changes in the configuration of devices on the machine. For example, an application needs to know when a device of interest has been added to the machine and a driver needs to know when a change occurs on a particular device. + +The PnP manager provides a mechanism for drivers and applications to be notified when certain PnP events occur. This section describes how to use PnP notification in kernel-mode code. Writers of user-mode applications should see the Microsoft Windows SDK documentation For information about the **RegisterDeviceNotification** function and related functions. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PnP%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-pnp-target-device-change-notification.md b/windows-driver-docs-pr/kernel/using-pnp-target-device-change-notification.md new file mode 100644 index 0000000000..a9285df036 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-pnp-target-device-change-notification.md @@ -0,0 +1,42 @@ +--- +title: Using PnP Target Device Change Notification +author: windows-driver-content +description: Using PnP Target Device Change Notification +ms.assetid: a56bda5c-e398-442d-bc90-2e63f8f7e6bf +keywords: ["notifications WDK PnP , target device changes", "target device change notifications WDK PnP", "EventCategoryTargetDeviceChange notification"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using PnP Target Device Change Notification + + +## + + +A driver registers for **EventCategoryTargetDeviceChange** notification on a device so the driver can be notified when the device is about to be removed. For example, if a driver opens a handle to a device, the driver should register for **EventCategoryTargetDeviceChange** notification on the device so the driver can close its handle when the PnP manager needs to remove the device. + +Drivers can also use **EventCategoryTargetDeviceChange** notification for custom notification. (See [Using PnP Custom Notification](using-pnp-custom-notification.md).) + +The following subsections discuss how to register for target device change notification and how to handle target device change events in a PnP notification callback routine: + +[Registering for Target Device Change Notification](registering-for-target-device-change-notification.md) + +[Handling a GUID\_TARGET\_DEVICE\_QUERY\_REMOVE Event](handling-a-guid-target-device-query-remove-event.md) + +[Handling a GUID\_TARGET\_DEVICE\_REMOVE\_COMPLETE Event](handling-a-guid-target-device-remove-complete-event.md) + +[Handling a GUID\_TARGET\_DEVICE\_REMOVE\_CANCELLED Event](handling-a-guid-target-device-remove-cancelled-event.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20PnP%20Target%20Device%20Change%20Notification%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-power-manager-routines-for-idle-detection.md b/windows-driver-docs-pr/kernel/using-power-manager-routines-for-idle-detection.md new file mode 100644 index 0000000000..6dce56df98 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-power-manager-routines-for-idle-detection.md @@ -0,0 +1,52 @@ +--- +title: Using Power Manager Routines for Idle Detection +author: windows-driver-content +description: Using Power Manager Routines for Idle Detection +ms.assetid: 6a89b2eb-d987-4722-b521-9df93153d957 +keywords: ["idle detection WDK power management", "PoRegisterDeviceForIdleDetection", "PoSetDeviceBusy", "power manager WDK kernel", "idle time-outs WDK power management", "time-outs WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Power Manager Routines for Idle Detection + + +## + + +The power manager provides support for idle detection through the [**PoRegisterDeviceForIdleDetection**](https://msdn.microsoft.com/library/windows/hardware/ff559721) and [**PoSetDeviceBusy**](https://msdn.microsoft.com/library/windows/hardware/ff559755) routines. + +To enable idle detection for its device, a device power policy owner calls **PoRegisterDeviceForIdleDetection** and specifies: + +- The idle time-out value to apply when the system optimizes for performance. + +- The idle time-out value to apply when the system optimizes for conservation. + +- The device power state to which the device should transition when idle. + +**PoRegisterDeviceForIdleDetection** returns a pointer to an idle counter, which the driver uses later to disable idle detection. Callers of **PoRegisterDeviceForIdleDetection** must be running at IRQL < DISPATCH\_LEVEL. + +A driver can register its device for idle detection any time after the device has been started and is ready to handle device power IRPs. For example, a driver might enable idle detection as part of its *IoCompletion* routine for a PnP start-device IRP. + +The time-out values for any given device should be proportional to the device's power-up latency and based on observed device behavior. For devices of certain types, a driver can specify conservation and performance time-out values of -1 to use the standard power policy time-outs for the device class. See the device-specific documentation for details. + +When the device is in use, the driver must call [**PoSetDeviceBusy**](https://msdn.microsoft.com/library/windows/hardware/ff559755), passing the pointer returned by **PoRegisterDeviceForIdleDetection**. **PoSetDeviceBusy** resets the idle counter, thus restarting the idle countdown for the device. The driver should call **PoSetDeviceBusy** on every I/O operation. + +To determine whether the device is idle, the power manager compares the value of the idle counter with the driver-specified idle time-out value for the current system power policy (either conservation or performance). See the Microsoft Windows SDK for functions pertaining to the system power policy. + +When the device satisfies the time-out value, the power manager sends a device set-power IRP, specifying the device power state that the driver passed in its call to **PoRegisterDeviceForIdleDetection**. The power manager does not send a query IRP before sending the set-power IRP. The drivers in the stack handle the set-power IRP as they would handle any other; they must complete it in a timely manner and they cannot fail it. (See [Handling Device Power-Down IRPs](handling-device-power-down-irps.md).) + +When the driver no longer requires idle detection or is not prepared to handle device power-down IRPs, it should call **PoRegisterDeviceForIdleDetection** again, passing zero for both time-out values. Setting the time-outs to zero disables idle detection for both conservation (battery) and performance (AC) power policies. The driver can quickly reenable idle detection; it simply calls **PoRegisterDeviceForIdleDetection** with nonzero time-out values. Once the driver has registered the device, it can enable and disable idle detection by changing the time-out values, even if the device has been powered down and reawakened. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Power%20Manager%20Routines%20for%20Idle%20Detection%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-remove-locks.md b/windows-driver-docs-pr/kernel/using-remove-locks.md new file mode 100644 index 0000000000..e4f02f49ea --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-remove-locks.md @@ -0,0 +1,48 @@ +--- +title: Using Remove Locks +author: windows-driver-content +description: Using Remove Locks +ms.assetid: 78ca7fe5-ceed-4752-bf1b-d13309097cd8 +keywords: ["remove locks WDK PnP", "lock routines WDK PnP"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Remove Locks + + +## + + +The [remove lock routines](https://msdn.microsoft.com/library/windows/hardware/ff561042) provide a way to track the number of outstanding I/O operations on a device, and to determine when it is safe to detach and delete a driver's device object. The system provides these routines to driver writers as an alternative to implementing their own tracking mechanism. + +A driver can use this mechanism for two purposes: + +1. To ensure that the driver's [*DispatchPnP*](https://msdn.microsoft.com/library/windows/hardware/ff543341) routine will not complete an [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738) request while the lock is held (for example, while another driver routine is accessing the device). + +2. To count the number of reasons why the driver should not delete its device object, and to set an event when that count goes to zero. + +To initialize a remove lock, a driver should allocate an **IO\_REMOVE\_LOCK** structure in its [device extension](device-extensions.md) and then call [**IoInitializeRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549324). A driver typically calls **IoInitializeRemoveLock** in its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine, when the driver initializes the rest of the device extension for a device object. + +Your driver must call [**IoAcquireRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff548204) each time it starts an I/O operation. The driver must call [**IoReleaseRemoveLock**](https://msdn.microsoft.com/library/windows/hardware/ff549560) each time it finishes an I/O operation. A driver can acquire the lock more than once. The remove lock routines maintain a count of the outstanding acquisitions of the lock. Each call to **IoAcquireRemoveLock** increments the count, and **IoReleaseRemoveLock** decrements the count. + +Your driver should also call **IoAcquireRemoveLock** when it passes out a reference to its code (for timers, DPCs, callbacks, and so on). The driver then must call **IoReleaseRemoveLock** when the event has returned. + +In its dispatch code for [**IRP\_MN\_REMOVE\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551738), the driver must acquire the lock once more and then call [**IoReleaseRemoveLockAndWait**](https://msdn.microsoft.com/library/windows/hardware/ff549567). This routine does not return until all outstanding acquisitions of the lock have been released. To allow queued I/O operations to complete, each driver should call **IoReleaseRemoveLockAndWait** *after* it passes the **IRP\_MN\_REMOVE\_DEVICE** request to the next-lower driver, and *before* it releases memory, calls [**IoDetachDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549087), or calls [**IoDeleteDevice**](https://msdn.microsoft.com/library/windows/hardware/ff549083). After **IoReleaseRemoveLockAndWait** has been called for a particular remove lock, all subsequent calls to **IoAcquireRemoveLock** for the same remove lock will fail. + +After **IoReleaseRemoveLockAndWait** returns, the driver should consider the device to be in a state in which it is ready to be removed and cannot perform I/O operations. Therefore, the driver must not call **IoInitializeRemoveLock** to re-initialize the remove lock. Violation of this rule while the driver is being verified by [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) will result in a bug check. + +Because a driver stores an **IO\_REMOVE\_LOCK** structure in the device extension of a device object, the remove lock is deleted when the driver deletes the device extension while processing an **IRP\_MN\_REMOVE\_DEVICE** request. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Remove%20Locks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-safe-string-functions.md b/windows-driver-docs-pr/kernel/using-safe-string-functions.md new file mode 100644 index 0000000000..ed44ead9f5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-safe-string-functions.md @@ -0,0 +1,64 @@ +--- +title: Using Safe String Functions +author: windows-driver-content +description: Using Safe String Functions +ms.assetid: a84008e8-e490-4640-a734-ef55cfbdfea3 +keywords: ["safe string functions WDK", "string manipulation functions WDK", "buffers WDK safe string functions"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Safe String Functions + + +## + + +Many system security problems are caused by poor buffer handling and the resulting buffer overruns. Poor buffer handling is often associated with string manipulation operations. The standard string manipulation functions that are supplied by C/C++ language runtime libraries (**strcat**, **strcpy**, **sprintf**, and so on) do not prevent writing beyond the end of buffers. + +Two new sets of string manipulation functions, called *safe string functions*, provide additional processing for proper buffer handling in your code. These safe string functions are available in the Windows Driver Kit (WDK) and for Microsoft Windows XP SP1 and later versions of the Driver Development Kit (DDK) and Windows SDK. They are intended to replace their built-in C/C++ counterparts and similar routines that are supplied by Windows. + +One set of safe string functions are for use in kernel-mode code. These functions are prototyped in a header file named Ntstrsafe.h. This header file and an associated library are available in the WDK. + +The other set of safe string functions are for use in user-mode applications. A corresponding header file, Strsafe.h, contains prototypes for these functions. That file and an associated library are available in the Windows SDK. For more information about Strsafe.h, see [Using the Strsafe.h Functions](http://go.microsoft.com/fwlink/p/?linkid=165522). + +The set of kernel-mode safe string functions consists of the following two subsets: + +- [Safe string functions for Unicode and ANSI characters](https://msdn.microsoft.com/library/windows/hardware/ff563642) + + Each of these functions is available in a W-suffixed version that supports double-byte Unicode characters and an A-suffixed version that supports single-byte ANSI characters. For example, [**RtlStringCbCatN**](https://msdn.microsoft.com/library/windows/hardware/ff562801), which concatenates two strings and limits the length of the appended string, is available as **RtlStringCbCatNW** and **RtlStringCbCatNA**. + +- [Safe string functions for UNICODE\_STRING structures](https://msdn.microsoft.com/library/windows/hardware/ff563644) + + Each of these functions accepts a [**UNICODE\_STRING**](https://msdn.microsoft.com/library/windows/hardware/ff564879) structure as an input or output parameter or both. For example, [**RtlStringCbCopyUnicodeString**](https://msdn.microsoft.com/library/windows/hardware/ff562815) accepts the structure as an input parameter, [**RtlUnicodeStringCopyString**](https://msdn.microsoft.com/library/windows/hardware/ff562948) accepts the structure as an output parameter, and [**RtlUnicodeStringCopy**](https://msdn.microsoft.com/library/windows/hardware/ff562942) accepts the structure as both an input and output parameter. + +The kernel-mode safe string functions provide the following features: + +- Each safe string function receives the size of the destination buffer as input. The function can thus ensure that it does not write past the end of the buffer. + +- The Unicode and ANSI string functions terminate all output strings with a NULL character, even if the operation truncates the intended result. + +- All safe string functions return an NTSTATUS value, with only one possible success code (STATUS\_SUCCESS). + +- Most safe string functions are available in both a byte-counted and a character-counted version. For example, [**RtlStringCbCat**](https://msdn.microsoft.com/library/windows/hardware/ff562795) concatenates two byte-counted strings and [**RtlStringCchCat**](https://msdn.microsoft.com/library/windows/hardware/ff562834) concatenates two character-counted strings. + +- Most safe string functions are available in an extended, Ex-suffixed version that provides additional functionality. For example, [**RtlStringCbCatEx**](https://msdn.microsoft.com/library/windows/hardware/ff562799) extends the functionality of [**RtlStringCbCat**](https://msdn.microsoft.com/library/windows/hardware/ff562795). + +This section includes the following topics: + +[Summary of Kernel-Mode Safe String Functions](summary-of-kernel-mode-safe-string-functions.md) + +[Importing Kernel-Mode Safe String Functions](importing-kernel-mode-safe-string-functions.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Safe%20String%20Functions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-scatter-gather-dma.md b/windows-driver-docs-pr/kernel/using-scatter-gather-dma.md new file mode 100644 index 0000000000..dc870256a6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-scatter-gather-dma.md @@ -0,0 +1,86 @@ +--- +title: Using Scatter/Gather DMA +author: windows-driver-content +description: Using Scatter/Gather DMA +ms.assetid: dacc618f-d4d4-4c3c-a18c-baeef779e931 +keywords: ["AdapterListControl routine", "scatter/gather DMA WDK I/O", "PutScatterGatherList", "GetScatterGatherList", "DMA transfers WDK kernel , scatter/gather DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Scatter/Gather DMA + + +## + + +Drivers that perform system or bus-master, packet-based DMA can use support routines designed especially for scatter/gather DMA. Instead of calling the sequence of routines outlined in [Using Packet-Based System DMA](using-packet-based-system-dma.md) and [Packet-Based Bus-Master DMA](using-packet-based-bus-master-dma.md), a driver can use [**GetScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff546531) and [**PutScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff559967). + +A device does not need to have built-in scatter/gather support for its driver to use these routines. + +Drivers that use packet-based DMA call the following general sequence of support routines for scatter/gather operations: + +1. [**MmGetMdlVirtualAddress**](https://msdn.microsoft.com/library/windows/hardware/ff554539) to get an index into the MDL, required as a parameter in the call to **GetScatterGatherList** + +2. [**GetScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff546531) when the driver is ready to program its device for DMA and needs the system DMA controller or bus-master adapter + + **GetScatterGatherList** allocates the system DMA controller or bus-master adapter, determines how many map registers are required and allocates them, fills in the scatter/gather list, and calls the driver's [*AdapterListControl*](https://msdn.microsoft.com/library/windows/hardware/ff540513) routine when the DMA controller or adapter and map registers are available. + +3. [**PutScatterGatherList**](https://msdn.microsoft.com/library/windows/hardware/ff559967) as soon as all the requested data has been transferred or the driver fails the IRP because of a device I/O error + + **PutScatterGatherList** flushes the adapter buffers, frees the map registers, and frees the scatter/gather list. The driver must call **PutScatterGatherList** before it can access the data in the buffer. + +The adapter object pointer returned by **IoGetDmaAdapter** is a required parameter to each of these routines except **MmGetMdlVirtualAddress**, which requires a pointer to the MDL at *Irp*->**MdlAddress**. + +The **GetScatterGatherList** routine includes calls to **AllocateAdapterChannel** and **MapTransfer**, so the driver does not have to make these calls. The routine takes the following as parameters: + +- A pointer to the [**DMA\_ADAPTER**](https://msdn.microsoft.com/library/windows/hardware/ff544062) structure returned by [**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) + +- A pointer to the target device object for the DMA operation + +- A pointer to the MDL that describes the buffer at *Irp*->**MdlAddress** + +- A pointer to the current virtual address in the buffer described by the Mdl + +- The number of bytes to be mapped + +- A pointer to an [*AdapterListControl*](https://msdn.microsoft.com/library/windows/hardware/ff540513) routine that performs the transfer + +- A pointer to a driver-defined context area to be passed to the *AdapterListControl* routine + +- A Boolean value: **TRUE** for a transfer to the device; **FALSE** otherwise + +After determining the number of map registers required, allocating the adapter channel and map registers, filling in the scatter/gather list and preparing for the transfer, **GetScatterGatherList** calls the driver-supplied *AdapterListControl* routine. The *AdapterListControl* routine is run in an arbitrary thread context at IRQL = DISPATCH\_LEVEL. + +The *AdapterListControl* routine a driver supplies in calls to **GetScatterGatherList** differs from the [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine passed to **AllocateAdapterChannel** in the following important respects: + +- The *AdapterListControl* routine has no return value, whereas the *AdapterControl* routine returns an [**IO\_ALLOCATION\_ACTION**](https://msdn.microsoft.com/library/windows/hardware/ff550534). + +- Rather than a pointer to the *MapRegisterBase* for the system-allocated map registers, the third parameter to an *AdapterListControl* routine instead points to a [**SCATTER\_GATHER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff563664) structure through which the driver can perform DMA. + +- The *AdapterListControl* routine performs a subset of the tasks required in an *AdapterControl* routine. + + The *AdapterListControl* routine does not call **AllocateAdapterChannel** or **MapTransfer**. Its only responsibilities are to save the input scatter/gather list pointer, set up its device, and use the scatter/gather list to perform DMA. + +The scatter/gather list structure includes a **SCATTER\_GATHER\_ELEMENT** array and the number of elements in the array. Each element of the array provides the length and starting physical address of a physically contiguous scatter/gather region. A driver uses the length and address in data transfers. + +A driver can use **GetScatterGatherList** regardless of whether its device supports scatter/gather DMA. For a device that does not support scatter/gather DMA, the scatter/gather list will contain only one element. + +Using the scatter/gather routines can improve performance over calling **AllocateAdapterChannel** (as previously described in [Using Packet-Based System DMA](using-packet-based-system-dma.md) and [Using Packet-Based Bus-Master DMA](using-packet-based-bus-master-dma.md)). Unlike calls to **AllocateAdapterChannel**, more than one call to **GetScatterGatherList** can be queued for a device object at any one time. A driver can call **GetScatterGatherList** again for another DMA operation on the same driver object before its *AdapterListControl* routine has completed execution. + +On return from the driver-supplied *AdapterListControl* routine, **GetScatterGatherList** keeps the map registers but frees the DMA adapter structure. + +When the driver has satisfied the current IRP's transfer request or must fail the IRP due to a device or bus I/O error, it must call **PutScatterGatherList** before it can access the transferred data in the buffer. **PutScatterGatherList** flushes the adapter buffers and frees the map registers and scatter/gather list. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Scatter/Gather%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-spin-locks--an-example.md b/windows-driver-docs-pr/kernel/using-spin-locks--an-example.md new file mode 100644 index 0000000000..bef5ef763d --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-spin-locks--an-example.md @@ -0,0 +1,66 @@ +--- +title: Using Spin Locks An Example +author: windows-driver-content +description: Using Spin Locks An Example +ms.assetid: 0f3cd7fe-d3e6-4024-9b2f-7140c6ddd1ea +keywords: ["spin locks WDK kernel", "interrupt spin locks WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Spin Locks: An Example + + +## + + +Minimizing the time that a driver holds spin locks can significantly improve both the performance of the driver and of the system overall. For example, consider the following figure, which shows how an interrupt spin lock protects device-specific data that must be shared between an ISR and the [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) and [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routines in an SMP machine. + +![diagram illustrating using an interrupt spin lock](images/16ispnlk.png) + +1. While the driver's ISR runs at DIRQL on one processor, its *StartIo* routine runs at DISPATCH\_LEVEL on a second processor. The kernel interrupt handler holds the InterruptSpinLock for the driver's ISR, which accesses protected, device-specific data, such as state or pointers to device registers (SynchronizeContext), in the driver's device extension. The *StartIo* routine, which is ready to access SynchronizeContext, calls [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302), passing a pointer to the associated interrupt objects, the shared SynchronizeContext, and the driver's [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine (AccessDevice in the previous figure). + + Until the ISR returns, thereby releasing the driver's InterruptSpinLock, **KeSynchronizeExecution***spins* on the second processor, preventing AccessDevice from touching SynchronizeContext. However, **KeSynchronizeExecution** also raises IRQL on the second processor to the SynchronizeIrql of the interrupt objects, thereby preventing another device interrupt from occurring on that processor so that AccessDevice can be run at DIRQL as soon as the ISR returns. However, higher DIRQL interrupts for other devices, clock interrupts, and power-fail interrupts can still occur on either processor. + +2. When the ISR queues the driver's *DpcForIsr* and returns, AccessDevice runs on the second processor at the SynchronizeIrql of the associated interrupt objects and accesses SynchronizeContext. Meanwhile, the *DpcForIsr* is run on another processor at DISPATCH\_LEVEL IRQL. The *DpcForIsr* also is ready to access SynchronizeContext, so it calls **KeSynchronizeExecution** using the same parameters that the *StartIo* routine did in Step 1. + + When **KeSynchronizeExecution** acquires the spin lock and runs AccessDevice on behalf of the *StartIo* routine, the driver-supplied synchronization routine AccessDevice is given exclusive access to SynchronizeContext. Because AccessDevice runs at the SynchronizeIrql, the driver's ISR cannot acquire the spin lock and access the same area until the spin lock is released, even if the device interrupts on another processor while AccessDevice is executing. + +3. AccessDevice returns, releasing the spin lock. The *StartIo* routine resumes running at DISPATCH\_LEVEL on the second processor. **KeSynchronizeExecution** now runs AccessDevice on the third processor, so it can access SynchronizeContext on behalf of the *DpcForIsr*. However, if a device interrupt had occurred before the *DpcForIsr* called **KeSynchronizeExecution** in Step 2, the ISR might run on another processor before **KeSynchronizeExecution** could acquire the spin lock and run AccessDevice on the third processor. + +As the previous figure shows, while a routine running on one processor holds a spin lock, every other routine trying to acquire that spin lock gets no work done. Each routine trying to acquire an already held spin lock simply spins on its current processor until the holder releases the spin lock. When a spin lock is released, one and only one routine can acquire it; every other routine currently trying to acquire the same spin lock will continue to spin. + +The holder of any spin lock runs at a raised IRQL: either at DISPATCH\_LEVEL for an executive spin lock, or at a DIRQL for an interrupt spin lock. Callers of [**KeAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff551917) and **KeAcquireInStackQueuedSpinLock** run at DISPATCH\_LEVEL until they call [**KeReleaseSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff553145) or **KeReleaseInStackQueuedSpinLock** to release the lock. Callers of [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) automatically raise IRQL on the current processor to the SynchronizeIrql of the interrupt objects until the caller-supplied *SynchCritSection* routine exits and **KeSynchronizeExecution** returns control. For more information, see [Calling Support Routines That Use Spin Locks](calling-support-routines-that-use-spin-locks.md). + +**Keep in mind the following fact about using spin locks:** + +All code that runs at a lower IRQL cannot get any work done on the set of processors occupied by a spin-lock holder and by other routines trying to acquire the same spin lock. + +Consequently, minimizing the time a driver holds spin locks results in significantly better driver performance and contributes significantly to better overall system performance. + +As the previous figure shows, the kernel interrupt handler executes routines running at the same IRQL in a multiprocessor machine on a first-come, first-served basis. The kernel also does the following: + +- When a driver routine calls **KeSynchronizeExecution**, the kernel causes the driver's *SynchCritSection* routine to run on the same processor from which the call to **KeSynchronizeExecution** occurred (see Steps 1 and 3). + +- When a driver's ISR queues its *DpcForIsr*, the kernel causes the DPC to run on the first available processor on which IRQL falls below DISPATCH\_LEVEL. This is not necessarily the same processor from which the [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) call occurred (see Step 2). + +A driver's interrupt-driven I/O operations might tend to be serialized in a uniprocessor machine, but the same operations can be truly asynchronous in an SMP machine. As the previous figure shows, a driver's ISR could run on CPU4 in an SMP machine before its *DpcForIsr* begins processing an IRP for which the ISR has already handled a device interrupt on CPU1. + +In other words, you should not assume that an interrupt spin lock can protect operation-specific data that the ISR saves when it runs on one processor from being overwritten by the ISR when a device interrupt occurs on another processor before the *DpcForIsr* or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine runs. + +Although a driver could try to serialize all interrupt-driven I/O operations to preserve data collected by the ISR, that driver would not run much faster in an SMP machine than in a uniprocessor machine. To get the best possible driver performance while remaining portable across uniprocessor and multiprocessor platforms, drivers should use some other technique to save operation-specific data obtained by the ISR for subsequent processing by the *DpcForIsr*. + +For example, an ISR can save operation-specific data in the IRP it passes to the *DpcForIsr*. A refinement of this technique is to implement a *DpcForIsr* that consults an ISR-augmented count, processes the count's number of IRPs using ISR-supplied data, and resets the count to zero before returning. Of course, the count must be protected by the driver's interrupt spin lock because its ISR and a *SynchCritSection* would maintain its value dynamically. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Spin%20Locks:%20An%20Example%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-system-dma.md b/windows-driver-docs-pr/kernel/using-system-dma.md new file mode 100644 index 0000000000..a68950b046 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-system-dma.md @@ -0,0 +1,36 @@ +--- +title: Using System DMA +author: windows-driver-content +description: Using System DMA +ms.assetid: 8d478365-a6c8-4488-9f75-53a822d1daa2 +keywords: ["AdapterControl routines, system DMA", "system DMA WDK kernel", "adapter objects WDK kernel , system DMA", "DMA transfers WDK kernel , system DMA", "slave devices WDK DMA", "system DMA WDK kernel , about system DMA"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using System DMA + + +## + + +Drivers of subordinate DMA devices use one of the following types of system-provided DMA support: + +- Packet-based DMA, if the driver need not use a system DMA controller's auto-initialize mode. See [Using Packet-Based System DMA](using-packet-based-system-dma.md). + +- Common-buffer DMA, if the driver does use the auto-initialize mode. See [Using Common-Buffer System DMA](using-common-buffer-system-dma.md). + +In addition, any driver that uses packet-based DMA can use support routines intended to streamline scatter/gather DMA, regardless of whether its device has built-in scatter/gather support. See [Using Scatter/Gather DMA](using-scatter-gather-dma.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20System%20DMA%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-connect-fully-specified-version-of-ioconnectinterruptex.md b/windows-driver-docs-pr/kernel/using-the-connect-fully-specified-version-of-ioconnectinterruptex.md new file mode 100644 index 0000000000..4f9da83c49 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-connect-fully-specified-version-of-ioconnectinterruptex.md @@ -0,0 +1,136 @@ +--- +title: Using the CONNECT_FULLY_SPECIFIED Version of IoConnectInterruptEx +author: windows-driver-content +description: Using the CONNECT_FULLY_SPECIFIED Version of IoConnectInterruptEx +ms.assetid: 5b75c32e-77e5-4761-b709-fedb8e33b57a +keywords: ["IoConnectInterruptEx", "CONNECT_FULLY_SPECIFIED", "manual interrupt detections WDK kernel", "line-based interrupts WDK kernel", "message-signaled interrupts WDK kernel", "FullySpecified"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the CONNECT\_FULLY\_SPECIFIED Version of IoConnectInterruptEx + + +A driver can use the CONNECT\_FULLY\_SPECIFIED version of [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) to register an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine for a specific interrupt. A driver can use the CONNECT\_FULLY\_SPECIFIED version starting with Windows Vista. By linking to the Iointex.lib library, the driver can use the CONNECT\_FULLY\_SPECIFIED version in Windows 2000, Windows XP, and Windows Server 2003. For more information, see [Using IoConnectInterruptEx Prior to Windows Vista](using-ioconnectinterruptex-prior-to-windows-vista.md). + +The driver specifies a value of CONNECT\_FULLY\_SPECIFIED for *Parameters***->Version** and uses the members of *Parameters***->FullySpecified** to specify the other parameters of the operation: + +- *Parameters***->FullySpecified.PhysicalDeviceObject** specifies the PDO for the device that the ISR services. + +- *Parameters*->**FullySpecified.ServiceRoutine** points to the *InterruptService* routine, while *Parameters*->**FullySpecified**.**ServiceContext** specifies the value that the system passes as the *ServiceContext* parameter to *InterruptService*. The driver can use this to pass context information. For more information about passing context information, see [Providing ISR Context Information](providing-isr-context-information.md). + +- The driver provides a pointer to a PKINTERRUPT variable in *Parameters***->FullySpecified.InterruptObject**. The **IoConnectInterruptEx** routine sets this variable to point to the interrupt object for the interrupt, which can be used when [removing the ISR](removing-an-isr.md). + +- Drivers can optionally specify a spin lock in *Parameters***->FullySpecified.SpinLock** for the system to use when synchronizing with the ISR. Most drivers can just specify **NULL** to enable the system to allocate a spin lock on behalf of the driver. For more information about synchronizing with an ISR, see [Synchronizing Access to Device Data](synchronizing-access-to-device-data.md). + +The driver must specify the key properties of the interrupt in other members of *Parameters***->FullySpecified**. The system provides the necessary information in the array of [**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) structures when it sends the [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) IRP to the driver. + +The system provides for each interrupt a **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** structure with **Type** member equal to **CmResourceTypeInterrupt**. For a message-signaled interrupt, the CM\_RESOURCE\_INTERRUPT\_MESSAGE bit of the **Flags** member is set; otherwise, it is cleared. + +The **u.Interrupt** member of **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** contains the description of a line-based interrupt, while the **u.MessageInterrupt.Translated** member contains the description of a message-signaled interrupt. The following table indicates where, in the **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** structure, to find the information required to set the members of *Parameters*->**FullySpecified** for both types of interrupt. For more information, see the code example that follows the table. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MemberLine-based interruptMessage-signaled interrupt

ShareVector

ShareDisposition

ShareDisposition

Vector

u.Interrupt.Vector

u.MessageInterrupt.Translated.Vector

Irql

u.Interrupt.Level

u.MessageInterrupt.Translated.Level

InterruptMode

Flags & CM_RESOURCE_INTERRUPT_LATCHED

Flags & CM_RESOURCE_INTERRUPT_LATCHED

ProcessorEnableMask

u.Interrupt.Affinity

u.MessageInterrupt.Translated.Affinity

+ +  + +A driver will only receive **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** structures for message-signaled interrupts on Windows Vista and later versions of Windows. + +The following code example demonstrates how to register an *InterruptService* routine using CONNECT\_FULLY\_SPECIFIED. + +``` +IO_CONNECT_INTERRUPT_PARAMETERS params; + +// deviceExtension is a pointer to the driver's device extension. +// deviceExtension->IntObj is a PKINTERRUPT. +// deviceInterruptService is a pointer to the driver's InterruptService routine. +// IntResource is a CM_PARTIAL_RESOURCE_DESCRIPTOR structure of either type CmResourceTypeInterrupt or CmResourceTypeMessageInterrupt. +// PhysicalDeviceObject is a pointer to the device's PDO. +// ServiceContext is a pointer to driver-specified context for the ISR. + +RtlZeroMemory( ¶ms, sizeof(IO_CONNECT_INTERRUPT_PARAMETERS) ); +params.Version = CONNECT_FULLY_SPECIFIED; +params.FullySpecified.PhysicalDeviceObject = PhysicalDeviceObject; +params.FullySpecified.InterruptObject = &devExt->IntObj; +params.FullySpecified.ServiceRoutine = deviceInterruptService; +params.FullySpecified.ServiceContext = ServiceContext; +params.FullySpecified.FloatingSave = FALSE; +params.FullySpecified.SpinLock = NULL; + +if (IntResource->Flags & CM_RESOURCE_INTERRUPT_MESSAGE) { + // The resource is for a message-signaled interrupt. Use the u.MessageInterrupt.Translated member of IntResource. + + params.FullySpecified.Vector = IntResource->u.MessageInterrupt.Translated.Vector; + params.FullySpecified.Irql = (KIRQL)IntResource->u.MessageInterrupt.Translated.Level; + params.FullySpecified.SynchronizeIrql = (KIRQL)IntResource->u.MessageInterrupt.Translated.Level; + params.FullySpecified.ProcessorEnableMask = IntResource->u.MessageInterrupt.Translated.Affinity; +} else { + // The resource is for a line-based interrupt. Use the u.Interrupt member of IntResource. + + params.FullySpecified.Vector = IntResource->u.Interrupt.Vector; + params.FullySpecified.Irql = (KIRQL)IntResource->u.Interrupt.Level; + params.FullySpecified.SynchronizeIrql = (KIRQL)IntResource->u.Interrupt.Level; + params.FullySpecified.ProcessorEnableMask = IntResource->u.Interrupt.Affinity; +} + +params.FullySpecified.InterruptMode = (IntResource->Flags & CM_RESOURCE_INTERRUPT_LATCHED ? Latched : LevelSensitive); +params.FullySpecified.ShareVector = (BOOLEAN)(IntResource->ShareDisposition == CmResourceShareShared); + +status = IoConnectInterruptEx(¶ms); + +if (!NT_SUCCESS(status)) { + ... +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20CONNECT_FULLY_SPECIFIED%20Version%20of%20IoConnectInterruptEx%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-connect-line-based-version-of-ioconnectinterruptex.md b/windows-driver-docs-pr/kernel/using-the-connect-line-based-version-of-ioconnectinterruptex.md new file mode 100644 index 0000000000..280f2d09f1 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-connect-line-based-version-of-ioconnectinterruptex.md @@ -0,0 +1,70 @@ +--- +title: Using the CONNECT_LINE_BASED Version of IoConnectInterruptEx +author: windows-driver-content +description: Using the CONNECT_LINE_BASED Version of IoConnectInterruptEx +ms.assetid: 245be266-f76c-43f6-9ea7-2dc853b1d5e2 +keywords: ["IoConnectInterruptEx", "CONNECT_LINE_BASED", "line-based interrupts WDK kernel", "automatic interrupt detections WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the CONNECT\_LINE\_BASED Version of IoConnectInterruptEx + + +For Windows Vista and later operating systems, a driver can use the CONNECT\_LINE\_BASED version of [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) to register an [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958) routine for the driver's line-based interrupts. (Driver for earlier operating systems can use the CONNECT\_FULLY\_SPECIFIED version of **IoConnectInterruptEx**.) + +**Note**   You can use this method only for drivers that register a single interrupt service routine (ISR) for all of its line-based interrupts. If the driver can receive multiple interrupts, it must use the CONNECT\_FULLY\_SPECIFIED version of **IoConnectInterruptEx**. + +  + +The driver specifies a value of CONNECT\_LINE\_BASED for *Parameters*->**Version** and uses the members of *Parameters*->**LineBased** to specify the other parameters of the operation: + +- *Parameters*->**LineBased.PhysicalDeviceObject** specifies the physical device object (PDO) for the device that the ISR services. The system uses the device object to automatically identify the device's line-based interrupts. + +- *Parameters*->**LineBased.ServiceRoutine** points to the *InterruptService* routine, while *Parameters*->**LineBased**.**ServiceContext** specifies the value that the system passes as the *ServiceContext* parameter to *InterruptService*. The driver can use this to pass context information. For more information about passing context information, see [Providing ISR Context Information](providing-isr-context-information.md). + +- The driver provides a pointer to a PKINTERRUPT variable in *Parameters***->LineBased.InterruptObject**. **IoConnectInterruptEx** sets this variable to point to the interrupt object for the interrupt, which can be used when removing the ISR. For more information, see [Removing an ISR](removing-an-isr.md). + +- Drivers can optionally specify a spin lock in *Parameters***->LineBased.SpinLock** for the system to use when synchronizing with the ISR. Most drivers can just specify **NULL** to enable the system to allocate a spin lock on behalf of the driver. For more information about synchronizing with an ISR, see [Synchronizing Access to Device Data](synchronizing-access-to-device-data.md). + +The following code example demonstrates how to register an *InterruptService* routine using CONNECT\_LINE\_BASED: + +``` +IO_CONNECT_INTERRUPT_PARAMETERS params; + +// deviceExtension is a pointer to the driver's device extension. +// deviceExtension->IntObj is a PKINTERRUPT. +// deviceInterruptService is a pointer to the driver's InterruptService routine. +// PhysicalDeviceObject is a pointer to the device's PDO. +// ServiceContext is a pointer to driver-specified context for the ISR. + +RtlZeroMemory( ¶ms, sizeof(IO_CONNECT_INTERRUPT_PARAMETERS) ); +params.Version = CONNECT_LINE_BASED; +params.LineBased.PhysicalDeviceObject = PhysicalDeviceObject; +params.LineBased.InterruptObject = &deviceExtension->IntObj; +params.LineBased.ServiceRoutine = deviceInterruptService; +params.LineBased.ServiceContext = ServiceContext; +params.LineBased.SpinLock = NULL; +params.LineBased.SynchronizeIrql = 0; +params.LineBased.FloatingSave = FALSE; + +status = IoConnectInterruptEx(¶ms); + +if (!NT_SUCCESS(status)) { + // Operation failed. Handle error. + ... +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20CONNECT_LINE_BASED%20Version%20of%20IoConnectInterruptEx%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-connect-message-based-version-of-ioconnectinterruptex.md b/windows-driver-docs-pr/kernel/using-the-connect-message-based-version-of-ioconnectinterruptex.md new file mode 100644 index 0000000000..25be020970 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-connect-message-based-version-of-ioconnectinterruptex.md @@ -0,0 +1,71 @@ +--- +title: Using the CONNECT_MESSAGE_BASED Version of IoConnectInterruptEx +author: windows-driver-content +description: Using the CONNECT_MESSAGE_BASED Version of IoConnectInterruptEx +ms.assetid: 8e06c6aa-85de-4ed2-ac0d-0179201d1272 +keywords: ["IoConnectInterruptEx", "CONNECT_MESSAGE_BASED", "message-signaled interrupts WDK kernel", "automatic interrupt detections WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the CONNECT\_MESSAGE\_BASED Version of IoConnectInterruptEx + + +For Windows Vista and later operating systems, a driver can use the CONNECT\_MESSAGE\_BASED version of [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378) to register an ISR for the driver's message-signaled interrupts. The driver specifies a value of CONNECT\_MESSAGE\_BASED for *Parameters*->**Version**, and uses the members of *Parameters*->**MessageBased** to specify the other parameters of the operation. + +- *Parameters***->MessageBased.PhysicalDeviceObject** specifies the PDO for the device that the ISR services. The system uses the device object to automatically identify the device's message-signaled interrupts. + +- *Parameters***->MessageBased.MessageServiceRoutine** points to the [*InterruptMessageService*](https://msdn.microsoft.com/library/windows/hardware/ff547940) routine, while *Parameters***->MessageBased.ServiceContext** specifies the value that the system passes as the *ServiceContext* parameter to *InterruptMessageService*. The driver can use this to pass context information. For more information about passing context information, see [Providing ISR Context Information](providing-isr-context-information.md). + +- The driver can also specify a fallback *InterruptMessageService* routine in *Parameters***->MessageBased.FallBackServiceRoutine**. If the device has line-based interrupts, but no message-signaled interrupts, the system will instead register the *InterruptMessageService* routine to service the line-based interrupts. In this case, the system passes *Parameters***->MessageBased.ServiceContext** as the *ServiceContext* parameter to [*InterruptService*](https://msdn.microsoft.com/library/windows/hardware/ff547958). **IoConnectInterruptEx** updates *Parameters***->Version** to CONNECT\_LINE\_BASED if it registered the fallback routine. + +- *Parameters***->MessageBased.ConnectionContext** points to a variable that receives a pointer to either a [**IO\_INTERRUPT\_MESSAGE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff550576) (for *InterruptMessageService*) structure or a [**KINTERRUPT**](https://msdn.microsoft.com/library/windows/hardware/ff554237) structure (for *InterruptService*). The driver can use the received pointer to remove the ISR. For more information, see [Removing an ISR](removing-an-isr.md). + +- Drivers can optionally specify a spin lock in *Parameters***->MessageBased.SpinLock** for the system to use when synchronizing with the ISR. Most drivers can just specify **NULL** to enable the system to allocate a spin lock on behalf of the driver. For more information about synchronizing with an ISR, see [Synchronizing Access to Device Data](synchronizing-access-to-device-data.md). + +The following code example demonstrates how to register an *InterruptMessageService* routine by using CONNECT\_MESSAGE\_BASED. + +``` +IO_CONNECT_INTERRUPT_PARAMETERS params; + +// deviceExtension is a pointer to the driver's device extension. +// deviceExtension->IntInfo is a PVOID. +// deviceExtension->IntType is a ULONG. +// deviceInterruptService is a pointer to the driver's InterruptService routine. +// deviceInterruptMessageService is a pointer to the driver's InterruptMessageService routine. +// PhysicalDeviceObject is a pointer to the device's PDO. +// ServiceContext is a pointer to driver-specified context for the ISR. + +RtlZeroMemory( ¶ms, sizeof(IO_CONNECT_INTERRUPT_PARAMETERS) ); +params.Version = CONNECT_MESSAGE_BASED; +params.MessageBased.PhysicalDeviceObject = PhysicalDeviceObject; +params.MessageBased.MessageServiceRoutine = deviceInterruptMessageService; +params.MessageBased.ServiceContext = ServiceContext; +params.MessageBased.SpinLock = NULL; +params.MessageBased.SynchronizeIrql = 0; +params.MessageBased.FloatingSave = FALSE; +params.MessageBased.FallBackServiceRoutine = deviceInterruptService; + +status = IoConnectInterruptEx(¶ms); + +if (NT_SUCCESS(status)) { + // We record the type of ISR registered. + devExt->IsrType = params.Version; +} else { + // Operation failed. Handle error. + ... +} +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20CONNECT_MESSAGE_BASED%20Version%20of%20IoConnectInterruptEx%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-current-file-position.md b/windows-driver-docs-pr/kernel/using-the-current-file-position.md new file mode 100644 index 0000000000..768c5792bc --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-current-file-position.md @@ -0,0 +1,38 @@ +--- +title: Using the Current File Position +author: windows-driver-content +description: Using the Current File Position +ms.assetid: d342d973-8fff-4d00-a275-114012c17727 +keywords: ["files WDK kernel", "file objects WDK kernel", "objects WDK file objects", "file handles WDK kernel", "handle to file WDK kernel", "current file positions WDK kernel", "file positions WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Current File Position + + +## + + +When you create or open a file, you can cause the I/O manager to create a current file-position pointer that is associated with the file handle. Once you have done so, you can read and write data to the current file position, and the I/O manager will automatically update the position by the number of bytes that were read or written. + +By default, the I/O manager does not maintain a current file-position pointer. This default provides efficiency—because correctly maintaining the current file position requires the I/O manager to synchronize every read and write operation on the file object. + +To create a handle that has an associated current file-position pointer, specify the SYNCHRONIZE access right in the *DesiredAccess* parameter to [**ZwCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff566424), [**IoCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff548418), or [**ZwOpenFile**](https://msdn.microsoft.com/library/windows/hardware/ff567011), and either FILE\_SYNCHRONOUS\_IO\_ALERT or FILE\_SYNCHRONOUS\_IO\_NONALERT in the *CreateOptions* or *OpenOptions* parameter. Be sure that you do not also specify the FILE\_APPEND\_DATA access right. + +[**ZwReadFile**](https://msdn.microsoft.com/library/windows/hardware/ff567072) and [**ZwWriteFile**](https://msdn.microsoft.com/library/windows/hardware/ff567121) automatically update the current file-position pointer so that it points just beyond the data affected by the operation. For example, if you read 20 bytes starting at byte offset 101, **ZwReadFile** will update the current file position to 121. + +You can examine or change the current file position by calling [**ZwQueryInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567052) or [**ZwSetInformationFile**](https://msdn.microsoft.com/library/windows/hardware/ff567096), respectively. In either case, set the *FileInformationClass* parameter to **FilePositionInformation**. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20Current%20File%20Position%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-kernel-stack.md b/windows-driver-docs-pr/kernel/using-the-kernel-stack.md new file mode 100644 index 0000000000..f1177c28e8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-kernel-stack.md @@ -0,0 +1,44 @@ +--- +title: Using the Kernel Stack +author: windows-driver-content +description: Using the Kernel Stack +ms.assetid: f1df01f4-f156-4267-a4a0-c548e16c02ea +keywords: ["memory management WDK kernel , kernel stack", "kernel-mode stack space WDK", "kernel stack space WDK"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Kernel Stack + + +## + + +The size of the kernel-mode stack is limited to approximately three pages. Therefore, when passing data to internal routines, drivers cannot pass large amounts of data on the kernel stack. + +To avoid running out of kernel-mode stack space, use the following design guidelines: + +- Avoid making deeply nested calls from one internal driver routine to another, if each routine passes data on the kernel stack. + +- Make sure that you limit the number of recursive calls that can occur, if you design a driver that has a recursive routine. + +In other words, the call-tree structure of a driver should be relatively flat. You can call the [**IoGetStackLimits**](https://msdn.microsoft.com/library/windows/hardware/ff549299) and [**IoGetRemainingStackSize**](https://msdn.microsoft.com/library/windows/hardware/ff549286) routines to determine the kernel stack space that is available. Note that the size of the kernel-mode stack can vary among different hardware platforms and different versions of the operating system. + +Running out of kernel stack space causes a fatal system error. Therefore, it is better for a driver to [allocate system-space memory](allocating-system-space-memory.md) than to run out of kernel stack space. However, nonpaged pool is also a limited system resource. + +Drivers of devices that use DMA can buffer data to be transferred, if necessary, either by calling [**ExAllocatePoolWithTag**](https://msdn.microsoft.com/library/windows/hardware/ff544520) for a **NonPagedPool**-type buffer or, for some drivers, by using common-buffer DMA. For more information, see [Using Common-Buffer System DMA](using-common-buffer-system-dma.md) and [Using Common-Buffer Bus-Master DMA](using-common-buffer-bus-master-dma.md). + +Generally, the kernel-mode stack cannot be paged; it is guaranteed to be resident in memory. However, Windows occasionally pages the kernel stacks of inactive threads. For help in guaranteeing that these kernel stacks are not paged during a debugging session, see [Disable paging of kernel stacks](https://msdn.microsoft.com/library/windows/hardware/ff541920). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20Kernel%20Stack%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-maptransferex-routine.md b/windows-driver-docs-pr/kernel/using-the-maptransferex-routine.md new file mode 100644 index 0000000000..5b9ca4e9e4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-maptransferex-routine.md @@ -0,0 +1,76 @@ +--- +title: Using the MapTransferEx Routine +author: windows-driver-content +description: The MapTransferEx routine initializes a set of previously allocated DMA resources and starts a DMA transfer. +ms.assetid: 79D3DDB2-B134-43B2-A6CC-94035C793047 +--- + +# Using the MapTransferEx Routine + + +The [**MapTransferEx**](https://msdn.microsoft.com/library/windows/hardware/hh406521) routine initializes a set of previously allocated DMA resources and starts a DMA transfer. This routine is available in version 3 of the DMA operations interface. Version 3 of this interface is supported starting with Windows 8. For more information about the DMA operations interface, see [**DMA\_OPERATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff544071). + +## Comparison of MapTransferEx to MapTransfer + + +**MapTransferEx** is an improved version of the [**MapTransfer**](https://msdn.microsoft.com/library/windows/hardware/ff554402) routine. **MapTransfer** is available in all versions of the DMA operations interface, starting with version 1 in Windows 2000. One call to **MapTransfer** can map one contiguous block of physical memory from an MDL. However, the data buffer for a complex DMA transfer might be described by an MDL chain, and each MDL in the chain might describe several blocks of physically contiguous memory. To use **MapTransfer** to transfer such a buffer, a driver must make many calls to **MapTransfer**. Typically, these calls are made inside a pair of nested loops. The inner loop iterates from one block of contiguous physical memory to the next in each MDL, and the outer loop iterates from one MDL to the next in the MDL chain. + +In contrast, one call to **MapTransferEx** can transfer the entire data buffer for a complex DMA transfer. The following three **MapTransferEx** parameters describe the buffer memory to use for the transfer. + + ++++ + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
Mdl

A pointer to the first MDL in a chain of one or more MDLs. For more information about MDL chains, see [Using MDLs](using-mdls.md).

Offset

The byte offset of the buffer from start of the memory that is described by the MDL chain.

Length

A pointer to a location that contains the length, in bytes, of the data buffer.

+ +  + +At the start of a **MapTransferEx** call, the **MapTransferEx** routine advances through the MDL chain to find the start of the buffer. The start of the buffer is specified by the *Offset* parameter. Next, working from the start of the buffer to the end, **MapTransferEx** constructs a scatter/gather list in which each buffer fragment in the list is a physically contiguous block of memory from the MDL chain. To construct this list, **MapTransferEx** steps from one physically contiguous block of memory to the next within each MDL, and from one MDL to the next in the MDL chain. List construction finishes when the total amount of buffer memory described by the scatter/gather list equals the number of bytes specified by the \**Length* input parameter. The ordering of the buffer fragments in the resulting scatter/gather list matches the ordering of the physically contiguous blocks in the MDL chain. + +## Multiple calls to MapTransferEx + + +**MapTransferEx** might not always be able to transfer an entire DMA data buffer in one call. The following list describes some of the conditions that might require **MapTransferEx** to be called more than once to complete the transfer: + +- The DMA adapter requires map registers, and the number of map registers assigned to the adapter is not sufficient to describe the entire buffer. +- The storage allocated by the driver to contain the scatter/gather list is not large enough to contain the scatter/gather list for the entire buffer. +- The transfer uses a system DMA controller that limits the number of buffer fragments that can be specified in a hardware scatter/gather list. + +In all of these cases, **MapTransferEx** maps as much of the data buffer as it can in one call, and tells the driver how much of the buffer was mapped by the call. The preceding list does not include other conditions, such as platform-specific cache behavior, that might require more than one call to **MapTransferEx** to complete a transfer. Future hardware platforms might impose additional constraints on DMA transfer length. For these reasons, driver developers should design their drivers to correctly handle the case in which **MapTransferEx** cannot map an entire DMA data buffer in one call. + +Before calling **MapTransferEx**, the caller sets the \**Length* parameter to the number of bytes in the DMA data buffer that still need to be mapped. Before returning, **MapTransferEx** sets \**Length* to the number of bytes in the buffer that were actually mapped by the call. When a **MapTransferEx** call cannot map the entire buffer length, as specified by the \**Length* input value, the output value of \**Length* is less than its input value. If a DMA transfer requires two or more **MapTransferEx** calls, the calling driver must obtain the \**Length* output value from one call before it can specify the \**Length* input value for the next call. + +For example, if a **MapTransferEx** call can transfer only X bytes to or from a buffer for which *Offset* = B and \**Length* = N (on input), then, on return, \**Length* = X. For the next call to **MapTransferEx**, the driver should set *Offset* = B + X and \**Length* = N - X. In both calls, the same MDL chain is used without modification. + +If the caller specifies a [*DmaCompletionRoutine*](https://msdn.microsoft.com/library/windows/hardware/hh450991), **MapTransferEx** writes the \**Length* output value before it schedules the *DmaCompletionRoutine* to run. This behavior ensures that the updated \**Length* value is always available before the *DmaCompletionRoutine* runs. For example, if a DMA transfer requires two **MapTransferEx** calls, the *DmaCompletionRoutine* that the first call schedules can obtain the \**Length* output value from the first call. The routine can then use this value to calculate the \**Length* input value for the second call. Typically, the *Length* parameter points to a location in the \**CompletionContext* value that is supplied to the *DmaCompletionRoutine* as a parameter. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20MapTransferEx%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-registry-in-a-driver.md b/windows-driver-docs-pr/kernel/using-the-registry-in-a-driver.md new file mode 100644 index 0000000000..a14cc9563a --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-registry-in-a-driver.md @@ -0,0 +1,44 @@ +--- +title: Using the Registry in a Driver +author: windows-driver-content +description: Using the Registry in a Driver +ms.assetid: 69d2d491-3cc1-4fd0-a1c9-0cc8e73e69b2 +keywords: ["registry WDK kernel", "driver registry information WDK kernel", "storage WDK registry", "storing registry information", "registry WDK kernel , about registry in drivers", "driver registry information WDK kernel , about registry in drivers", "manipulating registry entries WDK kernel", "keys WDK kernel registry", "subkeys WDK kernel registry", "kernel-mode drivers WDK , registry"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the Registry in a Driver + + +## + + +Drivers, like other system components, rely on the registry to store configuration information. The system itself uses the registry to store information about devices and drivers, and a driver can store additional information there for its own use. + +The Microsoft Windows executive provides the following two sets of routines for manipulating the registry: + +[Registry Key Object Routines](registry-key-object-routines.md) + +[Registry Run-Time Library Routines](registry-run-time-library-routines.md) + +[Plug and Play Registry Routines](plug-and-play-registry-routines.md) + +For additional information about the registry, see: + +[**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320) + +[Registry Keys for Drivers](https://msdn.microsoft.com/library/windows/hardware/ff549538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20Registry%20in%20a%20Driver%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-system-s-cancel-spin-lock.md b/windows-driver-docs-pr/kernel/using-the-system-s-cancel-spin-lock.md new file mode 100644 index 0000000000..1f5097c189 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-system-s-cancel-spin-lock.md @@ -0,0 +1,42 @@ +--- +title: Using the System's Cancel Spin Lock +author: windows-driver-content +description: Using the System's Cancel Spin Lock +ms.assetid: dd3cf1e7-8ecc-4721-9160-86bf928687e4 +keywords: ["cancel spin locks WDK kernel", "spin locks WDK kernel", "system cancel spin locks WDK kernel", "STATUS_CANCELLED"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the System's Cancel Spin Lock + + +## + + +The system provides a single *cancel spin lock*, which is acquired or released when certain system routines are called. + +Driver routines that change the state of cancelable IRPs, including all routines that might complete an IRP with STATUS\_CANCELLED, must acquire and release the system cancel spin lock according to the guidelines in this section. + +In drivers that use the I/O manager-supplied device queue, any driver routine other than the *Cancel* routine that changes the cancelable state of an IRP must first call [**IoAcquireCancelSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff548196) to acquire the system cancel spin lock. + +Acquiring the cancel spin lock ensures that only the caller can change the cancelable state of that IRP. While the caller holds the spin lock, the I/O manager cannot call the driver's *Cancel* routine for that IRP. Likewise, another driver routine, such as a *DispatchCleanup* routine, cannot simultaneously try to change the cancelable state of that IRP. + +In drivers that manage their own queues of IRPs and use driver-supplied spin locks to synchronize queue access, the driver routines do not need to acquire the cancel spin lock before calling [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674). However, these drivers should check the *Cancel* routine pointer that **IoSetCancelRoutine** returns to determine whether the *Cancel* routine has already started. See [Using a Driver-Supplied Spin Lock](using-a-driver-supplied-spin-lock.md) for details. + +Any driver routine that calls **IoAcquireCancelSpinLock** must call **IoReleaseCancelSpinLock** as soon as possible. + +A driver must never call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343) with an IRP while holding a spin lock. Attempting to complete an IRP while holding a spin lock can cause a deadlock. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20System's%20Cancel%20Spin%20Lock%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-the-wmi-library-to-register-blocks.md b/windows-driver-docs-pr/kernel/using-the-wmi-library-to-register-blocks.md new file mode 100644 index 0000000000..b794583354 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-the-wmi-library-to-register-blocks.md @@ -0,0 +1,38 @@ +--- +title: Using the WMI Library to Register Blocks +author: windows-driver-content +description: Using the WMI Library to Register Blocks +ms.assetid: 1f4b773d-ca24-47f5-87e8-84c98dad9267 +keywords: ["WMI WDK kernel , registering with WMI", "registering WMI data providers", "data providers WDK WMI", "driver registrations WDK WMI", "event blocks WDK WMI", "blocks WDK WMI", "IRP_MN_REGINFO", "IRP_MN_REGINFO_EX", "registering blocks"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using the WMI Library to Register Blocks + + +## + + +A driver can use the WMI Library to handle [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) and [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) requests if it is registering blocks that do not use dynamic instance names, or that use static instance names based on a PDO or driver-defined base name string. In this case, the driver: + +1. Calls [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834) with a pointer to the driver's device object, a pointer to a [**WMILIB\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff565813) structure, and a pointer to the IRP + + The **WMILIB\_CONTEXT** structure indicates the number of blocks to register (**GuidCount**) and points to a list of [**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) structures (**GuidList**) that specify the GUID, the number of instances, and registration flags that pertain to the corresponding block. It also defines entry points for the driver's required and optional *DpWmiXxx* callback routines. + +2. When WMI calls the driver's [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine, the driver specifies the driver's registry path, its MOF resource name, registration flags that pertain to all of its blocks, and information that WMI uses to name instances of the driver's data blocks, which could be either a pointer to the physical device object passed to the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine or a string on which to base static instance names. + +A driver must initialize entry points for its *DpWmiXxx* callback routines in the **WMILIB\_CONTEXT** structure before calling **WmiSystemControl**, but can postpone initialization of **GuidCount** and **GuidList** in the **WMILIB\_CONTEXT** structure until WMI calls the driver's *DpWmiQueryReginfo* routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20the%20WMI%20Library%20to%20Register%20Blocks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-timer-objects.md b/windows-driver-docs-pr/kernel/using-timer-objects.md new file mode 100644 index 0000000000..c327c720b3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-timer-objects.md @@ -0,0 +1,58 @@ +--- +title: Using Timer Objects +author: windows-driver-content +description: Using Timer Objects +ms.assetid: b3ee9d92-87b9-47b7-ab13-11e42bec7997 +keywords: ["timer objects WDK kernel , waiting on", "waiting on timer objects", "notification timers WDK kernel", "KeDelayExecutionThread", "KeWaitForSingleObject", "KeInitializeTimer", "KeSetTimer", "DueTime values"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Timer Objects + + +## + + +The following figure illustrates the use of a notification timer to set up a timeout interval for an operation and then wait while other driver routines process an I/O request. + +![diagram illustrating waiting for a timer object](images/3ketimer.png) + +As the previous figure shows, a driver must provide storage for the timer object, which must be initialized by a call to [**KeInitializeTimer**](https://msdn.microsoft.com/library/windows/hardware/ff552168) with a pointer to this storage. A driver typically makes this call from its [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. + +Within the context of a particular thread, such as a driver-created thread or a thread requesting a synchronous I/O operation, the driver can wait for its timer object as shown in the previous figure: + +1. The thread calls [**KeSetTimer**](https://msdn.microsoft.com/library/windows/hardware/ff553286) with a pointer to the timer object and a given *DueTime* value, expressed in units of 100 nanoseconds. A positive value for *DueTime* specifies an absolute time at which the timer object should be removed from the kernel's timer queue and set to the Signaled state. A negative value for *DueTime* specifies an interval relative to the current system time. + + Note that the thread (or driver routine running in a system thread) passes a **NULL** pointer for the DPC object (shown previously in the figure illustrating [using timer and DPC objects for a CustomTimerDpc routine](registering-and-queuing-a-customtimerdpc-routine.md)) when it calls **KeSetTimer** if it waits on the timer object instead of queuing a [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine. + +2. The thread calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) with a pointer to the timer object, which puts the thread into a wait state while the timer object is in the kernel's timer queue. + +3. The given *DueTime* expires. + +4. The kernel dequeues the timer object, sets it to the Signaled state, and changes the thread's state from waiting to ready. + +5. The kernel dispatches the thread for execution as soon as a processor is available: that is, no other thread with a higher priority is currently in the ready state and there are no kernel-mode routines to be run at a higher IRQL. + +Driver routines that run at IRQL >= DISPATCH\_LEVEL can time out requests by using a timer object with an associated DPC object to queue a driver-supplied [*CustomTimerDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542983) routine. Only driver routines that run within a nonarbitrary thread context can wait for a nonzero interval on a timer object, as shown in the previous figure. + +Like every other thread, a driver-created thread is represented by a kernel thread object, which is also a dispatcher object. Consequently, a driver need not have its driver-created thread use a timer object to voluntarily put itself into a wait state for a given interval. Instead, the thread can call [**KeDelayExecutionThread**](https://msdn.microsoft.com/library/windows/hardware/ff551986) with a caller-supplied interval. For more information about this technique, see [Polling a Device](avoid-polling-devices.md). + +[**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113), [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022), and [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routines also run in a system thread context, so drivers can call **KeWaitForSingleObject** with a driver-initialized timer object or **KeDelayExecutionThread** while they are initializing or unloading. A device driver can call [**KeStallExecutionProcessor**](https://msdn.microsoft.com/library/windows/hardware/ff553295) for a very short interval (preferably something less than 50 microseconds) if it must wait for the device to update state during its initialization. + +However, higher-level drivers generally use another synchronization mechanism in their [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) and [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routines instead of using a timer object. Higher-level drivers should always be designed to layer themselves over any lower-level driver of a particular type or types of device. Therefore, a higher-level driver tends to become slow to load if it waits on a timer object or calls **KeDelayExecutionThread** because such a driver must wait for an interval long enough to accommodate the slowest possible device supporting it. Note also that a "safe" but minimum interval for such a wait is very difficult to determine. + +Similarly, PnP drivers should not wait for other actions to occur, but instead should use the PnP manager's [notification](using-pnp-notification.md) mechanism. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Timer%20Objects%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-tmxxx-routines.md b/windows-driver-docs-pr/kernel/using-tmxxx-routines.md new file mode 100644 index 0000000000..bf47adab95 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-tmxxx-routines.md @@ -0,0 +1,60 @@ +--- +title: Using TmXxx Routines +author: windows-driver-content +description: Using TmXxx Routines +ms.assetid: 8bc763e9-e67c-4810-9901-e5dc1a1cfd0c +keywords: ["Kernel Transaction Manager WDK , TmXxx routines", "KTM WDK , TmXxx routines", "TmXxx routines WDK KTM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using TmXxx Routines + + +Most [KTM routines](https://msdn.microsoft.com/library/windows/hardware/ff553232) use a naming format of **Zw*Xxx***. These routines are handle-based. That is, at least one of their input or output parameters is a handle to a KTM object. + +KTM also provides a smaller number of routines that use a naming format of **Tm*Xxx***. These routines are pointer-based. At least one of their input or output parameters is a pointer to a KTM object. + +Some **Tm*Xxx*** routines duplicate **Zw*Xxx*** routines. Other **Tm*Xxx*** routines do not have **Zw*Xxx*** equivalents. + +In most cases, you should use the **Zw*Xxx*** routines. But you should use **Tm*Xxx*** routines in the following situations: + +- Your resource manager uses the [**ResourceManagerNotification**](https://msdn.microsoft.com/library/windows/hardware/ff561077) callback routine, which provides a pointer to an enlistment object instead of a handle. + + You can pass the enlistment object pointer to the enlistment object's **Tm*Xxx*** routines. + +- Your transaction processing system (TPS) component performs many rapid calls to KTM, which potentially causes system performance to be too slow. + + In this case, your component can call [**ObReferenceObjectByHandle**](https://msdn.microsoft.com/library/windows/hardware/ff558679) to convert each KTM object handle to a pointer, save the pointer, and then pass the pointer to **Tm*Xxx*** routines. This conversion eliminates the need for KTM to convert each handle to a pointer internally every time that a **Zw*Xxx*** routine is called. + + Each call to **ObReferenceObectByHandle** should include an access mask that contains appropriate KTM-defined flags. These flags are described on the reference pages for KTM's create and open routines. + + When your component has finished using the KTM object, it must dereference the object by calling either [**ObDereferenceObjectDeferDelete**](https://msdn.microsoft.com/library/windows/hardware/ff557728) or [**ObDereferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff557724). + + - You must use **ObDereferenceObjectDeferDelete** if your component, or any other component in your driver stack, is holding any system-provided locks, such as spin locks, mutex objects, or fast mutexes. + + - You can use **ObDereferenceObject** if you are sure that no component on your driver stack holds system-provided locks. + + Deadlocks can occur if your component calls **ObDereferenceObject** while holding locks, because KTM might also be holding locks for the object namespace. Also, your component can call [**TmGetTransactionId**](https://msdn.microsoft.com/library/windows/hardware/ff564679) to quickly obtain a transaction's identifier more efficiently than calling [**ZwQueryInformationTransaction**](https://msdn.microsoft.com/library/windows/hardware/ff567057). + +- You must have a capability that a **Zw*Xxx*** routine does not provide. + + Specifically, a resource manager can call the following routines: + + - [**TmEnableCallbacks**](https://msdn.microsoft.com/library/windows/hardware/ff564676) to enable asynchronous delivery of notifications by a callback routine. + - [**TmReferenceEnlistmentKey**](https://msdn.microsoft.com/library/windows/hardware/ff564726) and [**TmDereferenceEnlistmentKey**](https://msdn.microsoft.com/library/windows/hardware/ff564671) to increment or decrement an enlistment object's key reference count. + - [**TmRequestOutcomeEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff564727) to request an immediate commit or rollback notification for an enlistment. + - [**TmIsTransactionActive**](https://msdn.microsoft.com/library/windows/hardware/ff564681) to determine whether a transaction is in its active state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20TmXxx%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-virtual-clock-values.md b/windows-driver-docs-pr/kernel/using-virtual-clock-values.md new file mode 100644 index 0000000000..23fdc74409 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-virtual-clock-values.md @@ -0,0 +1,59 @@ +--- +title: Using Virtual Clock Values +author: windows-driver-content +description: Using Virtual Clock Values +ms.assetid: de01b0f1-86b1-4e7d-af22-84dbbe3a3f83 +keywords: ["virtual clock values WDK KTM", "Kernel Transaction Manager WDK , virtual clock values", "KTM WDK , virtual clock values", "transactions WDK KTM , virtual clock values"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Virtual Clock Values + + +KTM provides a virtual clock for each transaction manager object. When a resource manager calls [**ZwCreateTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff566430), KTM sets the object's virtual clock value to 1. KTM increments the virtual clock value every time that a commit operation begins. Whenever KTM writes to its log stream, it includes the current virtual clock value in the log record. + +When a resource manager calls [**ZwRecoverTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567079), KTM reads log stream records up to the end of the stream, and it sets the transaction manager object's virtual clock value to the last value that it finds in the object's log stream. + +When a resource manager calls [**ZwRollforwardTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567089), KTM reads log stream records up to the specified clock value, and it sets the transaction manager object's virtual clock value to the specified clock value. + +KTM enables resource managers and superior transaction managers to modify a transaction manager object's virtual clock value, but they typically do not have to modify the clock value. + +### When to Modify Virtual Clock Values + +Typically, your transaction processing system (TPS) does not have to modify virtual clock values unless the components in your TPS are trying to synchronize multiple log streams. + +For example, suppose that your TPS contains multiple resource managers that communicate with each other during pre-prepare/prepare/commit sequences. Also suppose that each resource manager creates a transaction manager object that has a unique log stream. To make sure that KTM restores the state of all resource managers to the same point in time during a recovery operation, these resource managers might use the following steps: + +- When one resource manager communicates with another, it passes the most recent virtual clock value that it has received from either KTM or yet another resource manager. + +- Whenever a resource manager calls a KTM routine that accepts a virtual clock value (see the following section in this topic), it passes the highest clock value that it has received from KTM or another resource manager. + +- Each resource manager writes virtual clock values into its log stream and uses those values when it performs rollback or recovery operations. + +These steps cause the virtual clock values that KTM stores for each transaction manager object to almost or exactly match. Therefore, when a recovery operation causes KTM to read its log streams, or when a rollback operation causes the resource managers to read their log streams, the recovery or rollback is based on synchronized log streams. + +### How to Modify Virtual Clock Values + +Resource managers can modify the virtual clock value by passing a new value to [**ZwPrePrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567040), [**ZwPrepareComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567037), [**ZwCommitComplete**](https://msdn.microsoft.com/library/windows/hardware/ff566418), [**ZwRollbackComplete**](https://msdn.microsoft.com/library/windows/hardware/ff567081), [**ZwReadOnlyEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567074), or [**ZwSinglePhaseReject**](https://msdn.microsoft.com/library/windows/hardware/ff567113). + +[Superior transaction managers](creating-a-superior-transaction-manager.md) can modify the virtual clock value by passing a new value to [**ZwPrePrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567044), [**ZwPrepareEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567039), [**ZwCommitEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff566419), or [**ZwReadOnlyEnlistment**](https://msdn.microsoft.com/library/windows/hardware/ff567074). + +In addition, a resource manager or superior transaction manager that uses a [**ResourceManagerNotification**](https://msdn.microsoft.com/library/windows/hardware/ff561077) callback routine can modify the virtual clock value that the callback routine receives. KTM then saves the updated value. + +If a resource manager or superior transaction manager passes a new clock value to KTM, KTM saves the new value only if it is greater than the current clock value. Otherwise, KTM keeps the current clock value. + +Resource managers and superior transaction managers can obtain a transaction manager object's virtual clock value by calling the [**ZwQueryInformationTransactionManager**](https://msdn.microsoft.com/library/windows/hardware/ff567058) routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Virtual%20Clock%20Values%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/using-wmimofck-exe.md b/windows-driver-docs-pr/kernel/using-wmimofck-exe.md new file mode 100644 index 0000000000..ab00646354 --- /dev/null +++ b/windows-driver-docs-pr/kernel/using-wmimofck-exe.md @@ -0,0 +1,52 @@ +--- +title: Using Wmimofck.exe +author: windows-driver-content +description: Using Wmimofck.exe +ms.assetid: cbf735c4-1c0d-4ff3-8a5c-b9d1de84bca4 +keywords: ["WMI WDK kernel , Wmimofck.exe utility", "Wmimofck.exe utility"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Using Wmimofck.exe + + +## + + +Included with the Windows Driver Kit (WDK) is the Wmimofck.exe utility. This application takes as input a binary MOF file (a .bmf file), which was generated by the [MOF compiler](compiling-a-driver-s-mof-file.md) (mofcomp.exe). Wmimofck.exe will check that the classes, properties, methods and events specified in the .bmf file are valid for WMI use. Wmimofck.exe is also capable of generating the following files: + +- C language header file (.h file) that can then be used to keep header file in sync with MOF definitions. + +- C language source file which contains stubs for WMI driver code. + +- Hex version of .bmf data which can be included in the driver source for supplying dynamic MOF data at runtime. + +- Test application templates in VBScript or HTML. + +To run the **wmimofck** utility, use the following syntax: + +**wmimofck** \[**-h***filename* \[**-m**\] \[**-u**\]\] \[**-c***filename*\] \[**-x***filename*\] \[**-t***filename*\] \[**-w***directory*\] \[*-yfilename*\] \[*-zfilename*\] + +If the **-h** parameter is specified, a C language header file is created that defines the GUIDs, data structures, and method indices specified in the MOF file. If the caller specifies the **-m** flag as well, then the header file will include structure definitions for the input and output of each WMI method. By default, *wmimofck* does not generate member definitions for WMI classes that contain variable length properties. If the caller specifies **-u**, then *wmimofck* will generate member definitions for every property that has a fixed size, including string properties that specify a **MaxLen** qualifier. If the **-t** parameter is specified, a VBScript program is created that will query all data blocks and properties specified in the MOF file. + +If the **-x** parameter is specified a text file is created that contains the text representation of the binary MOF data. This can be included in the source of the driver if the driver supports reporting the binary MOF via a WMI query rather than a resource on the driver image file. + +If the **-c** parameter is specified, a C language source file is generated that contains a template for implementing WMI code in a device driver. + +If the **-w** parameter is specified, a set of HTML files are generated that create a rudimentary UI that can be used to access the WMI data blocks. + +The **-y** and **-z** flags can only be used together. The **-y** specifies a file containing language-independent WMI class declarations, and **-z** specifies the class amendments for a particular language. The command *wmimofck localizedfile* **-y***mof* **-z***mfl* merges the *mof* and *mfl* files to form the complete localized version of MOF file. See [Building and Deploying the Localized MOF File](building-and-deploying-the-localized-mof-file.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Using%20Wmimofck.exe%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/version-3-of-the-dma-operations-interface.md b/windows-driver-docs-pr/kernel/version-3-of-the-dma-operations-interface.md new file mode 100644 index 0000000000..417dc8c20d --- /dev/null +++ b/windows-driver-docs-pr/kernel/version-3-of-the-dma-operations-interface.md @@ -0,0 +1,58 @@ +--- +title: Version 3 of the DMA Operations Interface +author: windows-driver-content +description: Version 3 of the DMA operations interface is available starting with Windows 8. +ms.assetid: EFB59930-7D58-4E6E-8242-66A326E239E5 +--- + +# Version 3 of the DMA Operations Interface + + +Version 3 of the DMA operations interface is available starting with Windows 8. The **DMA\_OPERATIONS** structure for this interface contains a number of new routines that are not defined in previous versions of this interface. For a list of the routines in version 3, see [**DMA\_OPERATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff544071). + +Although version 3 of the DMA operations interface is available across all Windows hardware platforms, this interface has many features to enable kernel-mode drivers to use the advanced capabilities of system DMA controllers in System on a Chip (SoC) integrated circuits. These capabilities typically include the ability to do scatter/gather DMA transfers. In contrast, previous versions of the DMA operations interface restrict scatter/gather DMA transfers to bus-master devices. The version-3 interface simplifies the management of scatter/gather lists and reduces the need for driver intervention during complex DMA transfers. + +To use version 3 of the DMA operations interface to perform a DMA transfer, a driver typically calls the following routines: + +[**IoGetDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff549220) +Allocates a DMA adapter object and returns a pointer to a [**DMA\_ADAPTER**](https://msdn.microsoft.com/library/windows/hardware/ff544062) structure that contains the DMA operations interface. + +[**GetDmaTransferInfo**](https://msdn.microsoft.com/library/windows/hardware/hh451125) +Provides a description of the resources that are required to perform the DMA transfer that is described by the caller. + +[**AllocateAdapterChannelEx**](https://msdn.microsoft.com/library/windows/hardware/hh406340) +Allocates the resources required for the DMA transfer and assigns these resources to the DMA adapter object. + +[**MapTransferEx**](https://msdn.microsoft.com/library/windows/hardware/hh406521) +Initializes the map registers and the scatter/gather buffer for the DMA transfer, and starts the transfer. + +[**FlushAdapterBuffersEx**](https://msdn.microsoft.com/library/windows/hardware/hh451102) +Performs any cache operations that might be required at the end of the DMA transfer. + +[**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) +Frees the DMA channel and map registers. + +[**PutDmaAdapter**](https://msdn.microsoft.com/library/windows/hardware/ff559965) +Releases the adapter object. + +These routines are used both for bus-master devices that use dedicated DMA controllers, and for subordinate devices that share a system DMA controller. For a step-by-step description of the calls that a driver makes during a typical DMA transfer, see [Basic Calling Pattern for Version-3 DMA Routines](basic-calling-pattern-for-version-3-dma-routines.md). + +**Note**   +In version 3 of the DMA operations interface, calls to the [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) routine are not required either before or after DMA transfers. The reason is that the following routines cover the need for flushing data caches on platforms that do not enforce cache coherency in hardware: + +- **MapTransferEx** ensures that processor data caches are flushed before write (memory-to-device) transfers. +- **FlushAdapterBuffersEx** ensures that caches are invalidated after read (device-to-memory) transfers. + +On an x86 or x64 processor, the **KeFlushIoBuffers** call performs no operations, and this call, while unnecessary, does not interfere with the operation of the hardware platform. On an ARM processor, calls to **KeFlushIoBuffers** during DMA transfers perform cache operations that are unnecessary and can degrade performance. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Version%203%20of%20the%20DMA%20Operations%20Interface%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wait-wake-callback-routines.md b/windows-driver-docs-pr/kernel/wait-wake-callback-routines.md new file mode 100644 index 0000000000..13e065ae1d --- /dev/null +++ b/windows-driver-docs-pr/kernel/wait-wake-callback-routines.md @@ -0,0 +1,48 @@ +--- +title: Wait/Wake Callback Routines +author: windows-driver-content +description: Wait/Wake Callback Routines +ms.assetid: 55749f14-37eb-45d9-8a2c-9ebf7fb3bc75 +keywords: ["sending wait/wake IRPs", "wait/wake IRPs WDK power management , sending", "callback routines WDK power management"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wait/Wake Callback Routines + + +## + + +When a driver requests a wait/wake IRP, it must specify a callback routine so that it can return the device to the working state (D0) when the wake-up event occurs. After the wake-up event occurs and all drivers have completed the IRP, the system calls the callback routine passed to [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734). + +Because this callback routine is set on behalf of the driver that originated the IRP—and not for a driver that is handling the IRP—it must not call [**PoStartNextPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559776); only the [*IoCompletion*](https://msdn.microsoft.com/library/windows/hardware/ff548354) routines set as drivers pass the IRP down the stack should start the next power IRP. Keep in mind that the policy owner not only sends the IRP but handles it, and it therefore might set an *IoCompletion* routine as it passes the IRP down the stack in addition to setting a callback routine when it requests the wait/wake IRP. + +The callback routine has the following responsibilities: + +1. If the driver controls more than one device, determine which of its devices signaled the wake-up. + +2. Service the event that caused the wake-up signal. + +3. Set the device that signaled the wake-up in the D0 state by calling [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734) to send a **PowerDeviceD0** request. The driver must also call [**PoSetPowerState**](https://msdn.microsoft.com/library/windows/hardware/ff559765) to inform the power manager of the new device power state. For more information, see [Sending IRP\_MN\_QUERY\_POWER or IRP\_MN\_SET\_POWER for Device Power States](sending-irp-mn-query-power-or-irp-mn-set-power-for-device-power-states.md). + +4. If the driver set a [*Cancel*](https://msdn.microsoft.com/library/windows/hardware/ff540742) routine for the IRP, call [**IoSetCancelRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549674) to reset the *Cancel* routine to **NULL**. + +5. If the driver owns power policy for more than one device, decrement its wait/wake reference count. If the count is nonzero, indicating that another device had previously sent a wait/wake IRP, request another wait/wake IRP (**PoRequestPowerIrp**) for its PDO. + + For example, a PCI device might have wait/wake enabled for both a modem and a Network Interface Card (NIC). If the NIC wakes the system (thus completing the IRP), the PCI FDO must send another wait/wake IRP to itself so that the modem will still be able to wake up. + +Because the driver that requested the wait/wake IRP controls power policy for its device stack, it is responsible for returning its device to the working state when the IRP completes. Although lower drivers might already have physically applied power to the device, the policy owner must call **PoRequestPowerIrp** to send an **IRP\_MN\_SET\_POWER** request for device power state D0. Only after all drivers in the device stack have handled this power-up IRP will the device be returned to the working state. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Wait/Wake%20Callback%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wait-wake-irp-requests.md b/windows-driver-docs-pr/kernel/wait-wake-irp-requests.md new file mode 100644 index 0000000000..b1732f47a2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wait-wake-irp-requests.md @@ -0,0 +1,40 @@ +--- +title: Wait/Wake IRP Requests +author: windows-driver-content +description: Wait/Wake IRP Requests +ms.assetid: c67d6dcb-f4a9-4df0-abb8-9d84fc44ec40 +keywords: ["sending wait/wake IRPs", "wake-up signal enabled WDK kernel", "wait/wake IRPs WDK power management , sending"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wait/Wake IRP Requests + + +## + + +To send an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766), a driver calls [**PoRequestPowerIrp**](https://msdn.microsoft.com/library/windows/hardware/ff559734), passing (among other parameters) a pointer to the target PDO, a system power state, and a pointer to a callback routine. + +The system power state specifies the least-powered state from which this IRP can wake the system. The value must be equal to or more powered than the [**SystemWake**](systemwake.md) state in the [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure. For example, if a driver passes **PowerSystemSleeping2** in the IRP, the associated IRP could cause the system to wake from states S0, S1, and S2. In such a case, the system must support S0 and S2 (the highest- and lowest-powered states in the range) but need not support S1. + +Every driver that requests a wait/wake IRP should specify a [callback routine](wait-wake-callback-routines.md), which is invoked after all other drivers have completed the IRP. In this routine, the driver can do whatever is necessary to return its device to the working state. + +In response to **PoRequestPowerIrp**, the power manager allocates a power IRP with minor code **IRP\_MN\_WAIT\_WAKE** and sends it to the top of the device stack for the target PDO. The caller is returned a pointer to the allocated IRP, which it can use later if it has to cancel the IRP. + +If no errors occur, **PoRequestPowerIrp** returns STATUS\_PENDING. This status means that the IRP has been sent successfully and is pending completion. + +A wait/wake IRP does not change the power state of the system or of a device. It simply enables a device's wake-up signal. The IRP remains pending until an external signal causes the system or device to awaken. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Wait/Wake%20IRP%20Requests%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/waits-and-apcs.md b/windows-driver-docs-pr/kernel/waits-and-apcs.md new file mode 100644 index 0000000000..0a7570b5d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/waits-and-apcs.md @@ -0,0 +1,85 @@ +--- +title: Waits and APCs +author: windows-driver-content +description: Waits and APCs +ms.assetid: b967beec-922c-4acf-a578-c476ce024fdb +keywords: ["kernel dispatcher objects WDK , alerts", "dispatcher objects WDK kernel , alerts", "APCs WDK kernel", "alerts WDK kernel", "kernel dispatcher objects WDK , APCs", "dispatcher objects WDK kernel , APCs", "Alertable parameter", "WaitMode parameter", "kernel dispatcher objects WDK , waiting for", "dispatcher objects WDK kernel , waiting for"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Waits and APCs + + +## + + +Threads that wait for a dispatcher object on behalf of a user-mode caller must be prepared for that wait to be interrupted, either by a user APC or by thread termination. When a thread calls [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350), [**KeWaitForMultipleObjects**](https://msdn.microsoft.com/library/windows/hardware/ff553324), [**KeWaitForMutexObject**](https://msdn.microsoft.com/library/windows/hardware/ff553344), or [**KeDelayExecutionThread**](https://msdn.microsoft.com/library/windows/hardware/ff551986), the operating system can place the thread in a wait state. Typically, the thread remains in the wait state until the operating system can complete the operation that the caller requests. However, if the caller specifies *WaitMode* = UserMode, the operating system might interrupt the wait. In that case, the routine exits with an NTSTATUS value of STATUS\_USER\_APC. + +Any driver that calls one of the preceding four routines with *WaitMode* = UserMode must be prepared to receive a return value of STATUS\_USER\_APC. The driver must complete its current operation with STATUS\_USER\_APC and return control to user mode. + +The exact situations in which the operating system interrupts the wait depends on the value of the *Alertable* parameter of the routine. If *Alertable* = **TRUE**, the wait is an alertable wait. Otherwise, the wait is a non-alertable wait. The operating system interrupts alertable waits only to deliver a user APC. The operating system interrupts both kinds of waits to terminate the thread. + +The following table explains the relationship between different parameter settings, waits, and user APC delivery. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersWait interrupted?User APC delivered?
Alertable = TRUE +WaitMode = UserMode

Yes

Yes

Alertable = TRUE +WaitMode = KernelMode

Yes

No

Alertable = FALSE +WaitMode = UserMode

Yes, for thread termination. No, for user APCs.

No

Alertable = FALSE +WaitMode = KernelMode

No

No

+ +  + +You can disable kernel APCs for a thread. If you do disable kernel APCs for a thread, both user APC delivery and thread termination for that thread are also disabled. For more information about how to disable APCs, see [Disabling APCs](disabling-apcs.md). + +Alerts, a seldom-used mechanism that are internal to the operating system, can also interrupt alertable wait states. An alert can interrupt a wait when *Alertable* = **TRUE**, regardless of the value of the *WaitMode* parameter. The waiting routine returns a value of STATUS\_ALERTED. + +Note that kernel APCs run preemptively, and do not cause **KeWaitFor*Xxx*** or **KeDelayExecutionThread** to return. The system interrupts and resumes the wait internally. Drivers are normally unaffected by this process, but it is possible for the driver to miss a dispatcher object signal for a transient condition, such as a call to [**KePulseEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552979). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Waits%20and%20APCs%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md b/windows-driver-docs-pr/kernel/wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md new file mode 100644 index 0000000000..aa269fb58e --- /dev/null +++ b/windows-driver-docs-pr/kernel/wakefromd0--wakefromd1--wakefromd2--and-wakefromd3.md @@ -0,0 +1,32 @@ +--- +title: WakeFromD0, WakeFromD1, WakeFromD2, and WakeFromD3 +author: windows-driver-content +description: WakeFromD0, WakeFromD1, WakeFromD2, and WakeFromD3 +ms.assetid: f01aaceb-babf-42da-bc4b-1a846c84a313 +keywords: ["WakeFromD0", "WakeFromD1", "WakeFromD2", "WakeFromD3"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WakeFromD0, WakeFromD1, WakeFromD2, and WakeFromD3 + + +## + + +Each of these [**DEVICE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff543095) structure members indicates whether the device can awaken in response to an external signal that arrives when the device is in the specified state. + +For a device that supports all four device power states (D0, D1, D2, D3) but can awaken only from states D0 and D1, the **WakeFromD0** and **WakeFromD1** bits are set, and the **WakeFromD2** and **WakeFromD3** bits are clear. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WakeFromD0,%20WakeFromD1,%20WakeFromD2,%20and%20WakeFromD3%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wdm-device-objects-and-device-stacks.md b/windows-driver-docs-pr/kernel/wdm-device-objects-and-device-stacks.md new file mode 100644 index 0000000000..29e3f3dbdc --- /dev/null +++ b/windows-driver-docs-pr/kernel/wdm-device-objects-and-device-stacks.md @@ -0,0 +1,38 @@ +--- +title: WDM Device Objects and Device Stacks +author: windows-driver-content +description: WDM Device Objects and Device Stacks +ms.assetid: 1ca151b4-40f8-43e4-a9f7-e754234609ce +keywords: ["stacks WDK , kernel-mode"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDM Device Objects and Device Stacks + + +## + + +This section describes the types of devices objects that are defined by WDM, and explains their arrangement in device stacks. It contains the following topics: + +[Types of WDM Device Objects](types-of-wdm-device-objects.md) + +[Example WDM Device Objects](example-wdm-device-objects.md) + +[When Are WDM Device Objects Created?](when-are-wdm-device-objects-created-.md) + +[Example WDM Device Stack](example-wdm-device-stack.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WDM%20Device%20Objects%20and%20Device%20Stacks%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wdm-driver-layers---an-example.md b/windows-driver-docs-pr/kernel/wdm-driver-layers---an-example.md new file mode 100644 index 0000000000..df3cadc0b0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wdm-driver-layers---an-example.md @@ -0,0 +1,62 @@ +--- +title: WDM Driver Layers An Example +author: windows-driver-content +description: WDM Driver Layers An Example +ms.assetid: 64eaa850-6394-4832-b11f-ce4db7f7c37d +keywords: ["WDM drivers WDK kernel , layered drivers", "layered drivers WDK kernel", "driver layers WDK WDM", "joysticks WDK WDM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDM Driver Layers: An Example + + +## + + +This section describes a possible set of WDM drivers for USB hardware to illustrate WDM driver layers. + +The following figure shows a sample PnP hardware configuration for a USB joystick. + +![diagram illustrating sample plug and play hardware for a usb joystick](images/usbjoyhw.png) + +In this figure, the USB joystick plugs into a port on a USB hub. The USB hub in this example resides on the USB Host Controller board and is plugged into the single port on the USB host controller board. The USB host controller plugs into a PCI bus. From a PnP perspective, the USB hub, the USB host controller, and the PCI bus are all bus devices because they each provide ports. The joystick is not a bus device. + +The following figure shows a sample set of drivers that might be loaded for the USB joystick hardware in the previous figure. + +![diagram illustrating sample plug and play driver layers for a usb joystick](images/usbjoydr.png) + +Starting at the bottom of the previous figure, the drivers in the sample stack include: + +- A PCI driver that drives the PCI bus. This is a PnP bus driver. The PCI bus driver is provided with the system by Microsoft. + +- The bus driver for the USB host controller is implemented as a class/miniclass driver pair. The USB host controller class and miniclass drivers are provided with the system by Microsoft. + +- The USB hub bus driver that drives the USB hub. The USB hub driver is provided with the system by Microsoft. + +- Three drivers for the joystick device; one of them is a class/miniclass pair. + + The function driver, the main driver for the joystick device, is the HID class driver/HID USB miniclass driver pair. (HID represents "Human Interface Device".) The HID USB miniclass driver supports the USB-specific semantics of HID devices, relying on the HID class driver DLL for general HID support. + + A function driver can be specific to a particular device, or, as in the case of HID, a function driver can service a group of devices. In this example, the HID class driver/HID USB miniclass driver pair services any HID-compliant device in the system on a USB bus. A HID class driver/HID 1394 miniclass driver pair would service any HID-compliant device on a 1394 bus. + + A function driver can be written by the device vendor or by Microsoft. In this example, the function driver (the HID class/HID USB miniclass driver pair) is written by Microsoft. + + There are two filter drivers for the joystick device in this example: an upper-level class filter that adds a macro button feature and a lower-level device filter that enables the joystick to emulate a mouse device. + + The upper-level filter is written by someone who needs to filter the joystick I/O and the lower-level filter driver is written by the joystick vendor. + +- The kernel-mode and user-mode HID clients and the application are not drivers but are shown for completeness. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WDM%20Driver%20Layers:%20%20An%20Example%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wdm-versions.md b/windows-driver-docs-pr/kernel/wdm-versions.md new file mode 100644 index 0000000000..d2685261e3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wdm-versions.md @@ -0,0 +1,33 @@ +--- +title: WDM Versions +author: windows-driver-content +description: Later versions of WDM generally support all the features available in earlier versions of WDM; that is, each new version of WDM is a superset of the previous WDM version. +ms.assetid: 89b24218-98d7-43da-9411-30b429f783df +keywords: ["WDM drivers WDK kernel , versions", "versions WDK WDM", "compatibility WDK WDM", "cross-system compatibility WDK WDM"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDM Versions + + +Although Microsoft Windows 2000 and later versions of the NT-based operating system, along with Windows 98 and Windows Me, all support various versions of WDM, incremental changes to WDM have resulted in later-released operating systems supporting additional WDM features that earlier releases do not support. Later versions of WDM generally support all the features available in earlier versions of WDM; that is, each new version of WDM is a superset of the previous WDM version. When possible, a cross-system driver should conform to the lowest WDM version on any operating system. + +## In this section + + +- [Determining the WDM Version](determining-the-wdm-version.md) +- [Differences in WDM Versions](differences-in-wdm-versions.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WDM%20Versions%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/what-does-the-zw-prefix-mean-.md b/windows-driver-docs-pr/kernel/what-does-the-zw-prefix-mean-.md new file mode 100644 index 0000000000..1601146f51 --- /dev/null +++ b/windows-driver-docs-pr/kernel/what-does-the-zw-prefix-mean-.md @@ -0,0 +1,92 @@ +--- +title: What Does the Zw Prefix Mean +author: windows-driver-content +description: What Does the Zw Prefix Mean +ms.assetid: 9529cce9-9c46-4906-854d-d0aef9118a90 +--- + +# What Does the Zw Prefix Mean? + + +The Windows native system services routines have names that begin with the prefixes **Nt** and **Zw**. The **Nt** prefix is an abbreviation of Windows NT, but the **Zw** prefix has no meaning. **Zw** was selected partly to avoid potential naming conflicts with other APIs, and partly to avoid using any potentially useful two-letter prefixes that might be needed in the future. + +Many of the [Windows driver support routines](https://msdn.microsoft.com/library/windows/hardware/ff544200) have names that begin with two- or three-letter prefixes. These prefixes indicate which kernel-mode system components implement the routines. The following table contains some examples. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixKernel componentExample routine

Cm

Configuration manager

[CmRegisterCallbackEx](https://msdn.microsoft.com/library/windows/hardware/ff541921)

Ex

Executive

[ExAllocatePool](https://msdn.microsoft.com/library/windows/hardware/ff544501)

Hal

Hardware abstraction layer

[HalGetAdapter](https://msdn.microsoft.com/library/windows/hardware/ff546596)

Io

I/O manager

[IoAllocateIrp](https://msdn.microsoft.com/library/windows/hardware/ff548257)

Ke

Kernel core

[KeSetEvent](https://msdn.microsoft.com/library/windows/hardware/ff553253)

Mm

Memory manager

[MmUnlockPages](https://msdn.microsoft.com/library/windows/hardware/ff556381)

Ob

Object manager

[ObReferenceObject](https://msdn.microsoft.com/library/windows/hardware/ff558678)

Po

Power manager

[PoSetPowerState](https://msdn.microsoft.com/library/windows/hardware/ff559765)

Tm

Transaction manager

[TmCommitTransaction](https://msdn.microsoft.com/library/windows/hardware/ff564665)

Nt and Zw

Native system services

[NtCreateFile](http://go.microsoft.com/fwlink/p/?linkid=157250) and [ZwCreateFile](https://msdn.microsoft.com/library/windows/hardware/ff566424)

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20What%20Does%20the%20Zw%20Prefix%20Mean?%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/what-s-changed.md b/windows-driver-docs-pr/kernel/what-s-changed.md new file mode 100644 index 0000000000..b44b5c447b --- /dev/null +++ b/windows-driver-docs-pr/kernel/what-s-changed.md @@ -0,0 +1,34 @@ +--- +title: What's Changed +author: windows-driver-content +description: What's Changed +ms.assetid: c7799406-d046-4261-8af7-7abbac18fa70 +keywords: ["64-bit WDK kernel , porting drivers to", "porting drivers to 64-bit Windows", "64-bit pointers WDK kernel", "integer size WDK 64-bit", "data types WDK 64-bit", "64-bit WDK kernel , what's changed"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# What's Changed + + +## + + +On 32-bit Windows, the integer, long, and pointer data types are all the same size—32 bits. This convenient uniformity in data type sizes has been a boon to clever C programmers, many of whom have come to take it for granted. + +On 64-bit Windows, however, this assumption of uniformity is no longer valid. Pointers are now 64 bits in length, but integer and long data types remain the same size as before—32 bits. This is because, while 64-bit pointers are needed to accommodate systems with as much as 16 TB of virtual memory, most data still fits comfortably into 32-bit integers. For most applications, changing the default integer size to 64 bits would only be a waste of space. + +On 32-bit Windows platforms, the operating system automatically fixes kernel-mode memory alignment faults and makes them invisible to the application. It does this for the calling process and any descendant processes. This feature, which often dramatically reduces performance, has not been implemented in 64-bit Windows. Thus, if your 32-bit driver contains misalignment bugs, you will need to fix them when porting to 64-bit Windows. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20What's%20Changed%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-are-wdm-device-objects-created-.md b/windows-driver-docs-pr/kernel/when-are-wdm-device-objects-created-.md new file mode 100644 index 0000000000..f81dbf69d8 --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-are-wdm-device-objects-created-.md @@ -0,0 +1,70 @@ +--- +title: When Are WDM Device Objects Created +author: windows-driver-content +description: When Are WDM Device Objects Created +ms.assetid: aeb8039d-2e5d-4700-a9e5-e5ee97c6b0b1 +keywords: ["device objects WDK kernel , when created", "layered device objects WDK kernel", "functional device objects WDK kernel", "FDO WDK kernel", "physical device objects WDK kernel", "PDOs WDK kernel", "filter DOs WDK kernel", "device stacks WDK kernel , device object layers possible", "attaching device objects"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When Are WDM Device Objects Created? + + +## + + +This section describes each kind of device object and mentions when each is created. + +The following figure shows the possible kinds of device objects that can be attached in a device stack, representing the drivers handling I/O requests for a device. + +![diagram illustrating possible device object layers for a device](images/objlyr.png) + +Starting at the bottom of this figure: + +- A bus driver creates a PDO for each device that it enumerates on its bus. + + A bus driver creates a PDO for a child device when it enumerates the device. A bus driver enumerates a device in response to an [**IRP\_MN\_QUERY\_DEVICE\_RELATIONS**](https://msdn.microsoft.com/library/windows/hardware/ff551670) request for **BusRelations** from the PnP manager. The bus driver creates a PDO for a child device if the device has been added to the bus since the last time the bus driver responded to a query-relations request for **BusRelations** (or if this is the first query-relations request since the machine was booted). + + A PDO represents the device to the bus driver, as well as to other kernel-mode system components such as the power manager, the PnP manager, and the I/O manager. + + Other drivers for a device attach device objects on top of the PDO, but the PDO is always at the bottom of the device stack. + +- Optional bus filter drivers create filter DOs for each device they filter. + + When the PnP manager detects a new device in a **BusRelations** list, it determines whether there are any bus filter drivers for the device. If so, for each such driver the PnP manager ensures it is loaded (calls [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) if necessary) and calls the driver's [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. If the bus filter driver filters operations for this device, the filter driver creates a device object and attaches it to the device stack in its *AddDevice* routine. If more than one bus filter driver exists and is relevant to this device, each such filter driver creates and attaches its own device object. + +- Optional, lower-level filter drivers create filter DOs for each device they filter. + + If an optional, lower-level filter driver exists for this device, the PnP manager ensures that such a driver is loaded after the bus driver and any bus filter drivers. The PnP manager calls the filter driver's *AddDevice* routine. In its *AddDevice* routine, the lower-level filter driver creates a filter DO for the device and attaches it to the device stack. If more than one lower-level filter driver exists, each such driver would create and attach its own filter DO. + +- The function driver creates an FDO for the device. + + The PnP manager ensures that the function driver for the device is loaded and calls the function driver's *AddDevice* routine. The function driver creates an FDO and attaches it to the device stack. + +- Optional, upper-level filter drivers create a filter DO for each device they filter. + + If any optional, upper-level filter drivers exist for the device, the PnP manager ensures they are loaded after the function driver and calls their *AddDevice* routines. Each such filter driver attaches its device object to the device stack. + +In summary, the device stack contains a device object for each driver that is involved in handling I/O to a particular device. The parent bus driver has a PDO, the function driver has an FDO, and each optional filter driver has a filter DO. + +Note that all devices, bus adapter/controller devices and nonbus devices, have a PDO and an FDO in their device stack. The PDO for a bus adapter/controller is created by the bus driver for the parent bus. For example, if a SCSI adapter plugs into a PCI bus, the PCI bus driver creates a PDO for the SCSI adapter. + +If a device is being used in raw mode, there are no function or filter drivers (no FDO or filter DOs). There is just a PDO for the parent bus driver and zero or more bus filter DOs. + +See [Creating a Device Object](creating-a-device-object.md) for information about which driver routines are responsible for creating and attaching device objects. + +The device stack plus some additional information constitutes the *devnode* for a device. The PnP manager maintains information in a device's devnode such as whether the device has been started and which drivers, if any, have registered for notification of changes on the device. The kernel debugger command **!devnode** displays information about a devnode. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20Are%20WDM%20Device%20Objects%20Created?%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-should-code-and-data-be-pageable-.md b/windows-driver-docs-pr/kernel/when-should-code-and-data-be-pageable-.md new file mode 100644 index 0000000000..abd57ee81b --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-should-code-and-data-be-pageable-.md @@ -0,0 +1,48 @@ +--- +title: When Should Code and Data Be Pageable +author: windows-driver-content +description: When Should Code and Data Be Pageable +ms.assetid: 2804f558-8c8c-43f4-b14e-8deaac9da286 +keywords: ["memory management WDK kernel , pageable drivers", "pageable drivers WDK kernel , when should be pageable", "locked-on-demand code WDK kernel", "spin locks WDK memory", "resident code WDK pageable drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When Should Code and Data Be Pageable? + + +## + + +You can make all or part of your driver pageable. Paging driver code can reduce the size of the driver's load image, thus freeing system space for other uses. It is most practical for drivers of sporadically used devices, such as modems and CD-ROMs, or for parts of drivers that are rarely called. + +Driver code that does any of the following must be memory-resident. That is, this code must be either in a nonpaged section, or in a paged section that is locked in memory when the code runs. + +- Runs at or above IRQL = DISPATCH\_LEVEL. + +- Acquires spin locks. + +- Calls any of the kernel's object support routines, such as [**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) or [**KeReleaseSemaphore**](https://msdn.microsoft.com/library/windows/hardware/ff553143), in which the *Wait* parameter is set to **TRUE**. If the kernel is called with *Wait* set to **TRUE**, the call returns with IRQL at DISPATCH\_LEVEL. + +Driver code must be running at IRQL < DISPATCH\_LEVEL when the code does anything that might cause a page fault. Code can cause a page fault if it does any of the following: + +- Accesses paged pool that is not locked in memory. + +- Calls a pageable routine. + +- Accesses unlocked user buffers in the context of the user thread. + +Typically, you should make a section paged if the total amount of all the pageable code (or data) is at least 4 kilobytes (KB). Whenever possible, you should isolate purely pageable code (or data) into a separate section from code (or data) that can sometimes be pageable but must sometimes be locked. For example, combining purely pageable code and locked-on-demand code causes more system space to be locked down for the combined section than is necessary. However, if a driver has less than 4 KB of possibly pageable code (or data), you might combine that code (or data) with locked-on-demand code (or data) into one section, saving system space. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20Should%20Code%20and%20Data%20Be%20Pageable?%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-to-check-the-driver-s-i-o-stack-location.md b/windows-driver-docs-pr/kernel/when-to-check-the-driver-s-i-o-stack-location.md new file mode 100644 index 0000000000..b7a386267d --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-to-check-the-driver-s-i-o-stack-location.md @@ -0,0 +1,46 @@ +--- +title: When to Check the Driver's I/O Stack Location +author: windows-driver-content +description: When to Check the Driver's I/O Stack Location +ms.assetid: ca084221-7b07-4db0-a987-9dd8a66d169c +keywords: ["dispatch routines WDK kernel , I/O stack locations", "I/O stack locations WDK dispatch routines", "driver I/O stack locations WDK dispatch routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When to Check the Driver's I/O Stack Location + + +## + + +A major I/O function code is set in the driver's [I/O stack location](i-o-stack-locations.md) for each incoming IRP. + +A driver's dispatch routine must check the driver's I/O stack location for the IRP to determine what to do if any of the following conditions hold: + +- The dispatch routine handles more than one major I/O function code. + +- The dispatch routine must handle a set of minor function codes for certain major function codes. IRPs with minor function codes include [**IRP\_MJ\_PNP**](https://msdn.microsoft.com/library/windows/hardware/ff550772) and [**IRP\_MJ\_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff550784), as well as certain IRPs that the SCSI port driver and file system drivers must handle. + +- The dispatch routine of a device driver or of a closely coupled higher-level driver handles [**IRP\_MJ\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550744) or [**IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff550766) requests, which have an associated set of I/O control codes. + +To get a pointer to a driver's I/O stack location, its dispatch routine calls [**IoGetCurrentIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549174). + +Higher-level drivers' dispatch routines always call **IoGetCurrentIrpStackLocation** and also call [**IoGetNextIrpStackLocation**](https://msdn.microsoft.com/library/windows/hardware/ff549266) to get a pointer to the next-lower driver's I/O stack location for IRPs that they set up for the next-lower driver, when [passing IRPs down the driver stack](passing-irps-down-the-driver-stack.md). + +The [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine or [*DispatchInternalDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543326) routine of a device driver, or possibly of its closely coupled class driver(s), must determine which I/O control code is set in the driver's I/O stack location at **Parameters.DeviceIoControl.IoControlCode** for each request. The I/O control code is contained in the driver's I/O stack location. + +In most cases, the *DispatchDeviceControl* or *DispatchInternalDeviceControl* routine of a higher-level driver simply passes an **IRP\_MJ\_DEVICE\_CONTROL** or **IRP\_MJ\_INTERNAL\_DEVICE\_CONTROL** request on to the next-lower driver, after setting up its stack location in the IRP. However, SCSI class drivers must check for certain [SCSI Port I/O control codes](https://msdn.microsoft.com/library/windows/hardware/ff565367) so that they can set up the SCSI port driver's I/O stack location correctly before passing on these requests. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20to%20Check%20the%20Driver's%20I/O%20Stack%20Location%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-to-complete-an-irp-in-a-dispatch-routine.md b/windows-driver-docs-pr/kernel/when-to-complete-an-irp-in-a-dispatch-routine.md new file mode 100644 index 0000000000..f7a69b2382 --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-to-complete-an-irp-in-a-dispatch-routine.md @@ -0,0 +1,58 @@ +--- +title: When to Complete an IRP in a Dispatch Routine +author: windows-driver-content +description: When to Complete an IRP in a Dispatch Routine +ms.assetid: 24159535-927f-490c-9472-05ea565b7ae5 +keywords: ["completing IRPs WDK kernel , dispatch routines", "dispatch routines WDK kernel , completing IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When to Complete an IRP in a Dispatch Routine + + +## + + +Usually, drivers do not complete IRPs in their dispatch routines unless the parameters for the given request are invalid or, in a device driver, unless the particular **IRP\_MJ\_*XXX*** requires no device I/O operations. + +Every driver in a chain of layered drivers can check the validity of parameters in its own I/O stack location, for each IRP received by the driver's dispatch routines. Completing IRPs with invalid parameters in the dispatch routine of the highest possible driver improves I/O throughput for any chain of drivers and for the system overall. + +A dispatch routine in a higher-level driver should either complete an IRP or pass it on for processing by lower drivers, according to the following guidelines: + +- If the dispatch routine determines that any parameters in its own I/O stack location are invalid, it should complete that IRP immediately with an appropriate error status, such as STATUS\_INVALID\_PARAMETER. + +- If the IRP contains the function code [**IRP\_MJ\_CLEANUP**](https://msdn.microsoft.com/library/windows/hardware/ff550718), the [*DispatchCleanup*](https://msdn.microsoft.com/library/windows/hardware/ff543233) routine must complete every IRP currently queued to the target device object, for the file object specified in the driver's I/O stack location, and complete the cleanup IRP. + + A cleanup request indicates that an application is being terminated or has closed a file handle for the file object that represents the driver's device object. When the *DispatchCleanup* routine returns, usually the driver's [*DispatchClose*](https://msdn.microsoft.com/library/windows/hardware/ff543255) routine is called next. + +- Otherwise, a higher-level driver can satisfy the request only by passing it on to the next-lower driver. + +A dispatch routine in a lowest-level driver should complete an IRP according to the following guidelines: + +- If the dispatch routine determines that any parameters in its own I/O stack location are invalid, or if the driver does not support the IRP, it should complete that IRP immediately with an appropriate error status. In such cases the driver must not complete the IRP with a status value of STATUS\_SUCCESS. + + Usually, any higher-level driver has already checked the parameters for a requested operation, but lowest-level device drivers should perform their own parameters checks as well. + +- If the IRP contains the function code **IRP\_MJ\_CLEANUP**, the *DispatchCleanup* routine must complete every IRP currently queued to the target device object, for the given file object in the driver's I/O stack location, and then complete the cleanup IRP. + + A cleanup request indicates that an application is being terminated or has closed a file handle for the file object that represents the driver's device object. When the *DispatchCleanup* routine returns, usually the driver's *DispatchClose* routine is called next. + +- If the request requires no device I/O operation, the dispatch routine should satisfy the request and complete the IRP. + + For example, a driver might save the current mode of its device in the device extension, particularly if it seldom changes device modes after initialization. Its [*DispatchDeviceControl*](https://msdn.microsoft.com/library/windows/hardware/ff543287) routine could then satisfy a request that queried the current device mode by returning this stored information. + +Otherwise, the dispatch routine must call [**IoMarkIrpPending**](https://msdn.microsoft.com/library/windows/hardware/ff549422), queue the IRP to other driver routines for further processing, and return STATUS\_PENDING. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20to%20Complete%20an%20IRP%20in%20a%20Dispatch%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-to-complete-an-irp.md b/windows-driver-docs-pr/kernel/when-to-complete-an-irp.md new file mode 100644 index 0000000000..1cd44c939b --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-to-complete-an-irp.md @@ -0,0 +1,42 @@ +--- +title: When to Complete an IRP +author: windows-driver-content +description: When to Complete an IRP +ms.assetid: 6986b24c-e7e5-43f2-861d-b84e4c131a8a +keywords: ["completing IRPs WDK kernel , when to complete"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When to Complete an IRP + + +## + + +A driver should initiate IRP completion when any of the following conditions is met: + +- The driver determines that IRP processing cannot progress because of invalid parameters or other conditions. + +- The driver is able to handle the requested I/O operation without passing the IRP down the driver stack, and the operation has finished. + +- The IRP is being canceled. (See [Canceling IRPs](canceling-irps.md).) + +If these conditions are not met, a driver's dispatch routine must pass the IRP down to the next-lower driver, or it must handle processing of the I/O request. If one of the conditions is met, the driver must call [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343). + +If a driver completes a request because processing cannot progress, or if it completes a request by handling the requested operation without actually accessing the device, it typically calls **IoCompleteRequest** from one of its dispatch routines. For more information, see [Completing IRPs in Dispatch Routines](completing-irps-in-dispatch-routines.md). + +If a driver must access a device to satisfy the request, it typically calls **IoCompleteRequest** from a [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) routine. These routines are discussed extensively in [Servicing Interrupts](servicing-interrupts.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20to%20Complete%20an%20IRP%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/when-to-use-kernel-mode-ktm.md b/windows-driver-docs-pr/kernel/when-to-use-kernel-mode-ktm.md new file mode 100644 index 0000000000..3c81bf74ee --- /dev/null +++ b/windows-driver-docs-pr/kernel/when-to-use-kernel-mode-ktm.md @@ -0,0 +1,33 @@ +--- +title: When to Use Kernel-Mode KTM +author: windows-driver-content +description: When to Use Kernel-Mode KTM +ms.assetid: deb3372d-19c4-4a17-b499-1da485e89276 +keywords: ["Kernel Transaction Manager WDK , when to use", "KTM WDK , when to use"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# When to Use Kernel-Mode KTM + + +You can use kernel-mode KTM with your kernel-mode component to support transacted operations in kernel mode, or to coordinate transacted operations between a kernel-mode component that uses kernel-mode KTM and a user-mode component that uses user-mode KTM. + +For example, you might use KTM in the following situations: + +- Your kernel-mode driver must open a file, modify the file's contents, and save the modified file, and it must prevent damage to the file if a write operation fails. If your driver performs these operations within a transaction, the driver does not have to copy and rename the old file, modify the new copy, delete the old file, and then rename the new copy. + +- You are designing a new data storage system that stores information in one or more databases. Components of your system will access the databases in kernel mode, or possibly in both user mode and kernel mode. Transactional clients of your system will encapsulate their database operations within transactions so that all modifications to all databases either succeed or fail as a unit. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20When%20to%20Use%20Kernel-Mode%20KTM%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/which-data-types-need-thunking.md b/windows-driver-docs-pr/kernel/which-data-types-need-thunking.md new file mode 100644 index 0000000000..bfade72089 --- /dev/null +++ b/windows-driver-docs-pr/kernel/which-data-types-need-thunking.md @@ -0,0 +1,99 @@ +--- +title: Which Data Types Need Thunking +author: windows-driver-content +description: Which Data Types Need Thunking +ms.assetid: af1d7986-7bf2-4587-b487-91658e7a3b19 +keywords: ["thunking WDK", "WOW64 thunking layer WDK", "32-bit I/O support WDK 64-bit , thunking", "data types WDK 64-bit", "pointer precision WDK 64-bit", "fixed-precision data types WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Which Data Types Need Thunking + + +## + + +The following table lists common data types that require thunking, along with their thunked equivalents. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Pointer-precision data type (before thunking)Equivalent 32-bit fixed-precision data type (after thunking)

HANDLE

VOID * POINTER_32

INT_PTR

INT32

LONG_PTR

LONG32

LPARAM

LONG32

PCHAR

Char * POINTER_32

PDWORD

DWORD * POINTER_32

PHANDLE

VOID ** POINTER_32

PULONG

ULONG * POINTER_32

PVOID

VOID * POINTER_32

PWORD

WORD * POINTER_32

SIZE_T

INT32

ULONG_PTR

ULONG32

UNICODE_STRING

UNICODE_STRING32

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Which%20Data%20Types%20Need%20Thunking%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/which-type-of-dpc-should-you-use-.md b/windows-driver-docs-pr/kernel/which-type-of-dpc-should-you-use-.md new file mode 100644 index 0000000000..51ac644413 --- /dev/null +++ b/windows-driver-docs-pr/kernel/which-type-of-dpc-should-you-use-.md @@ -0,0 +1,48 @@ +--- +title: Which Type of DPC Should You Use +author: windows-driver-content +description: Which Type of DPC Should You Use +ms.assetid: 7a8e6d75-5573-4a94-a895-fa2f70856807 +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel", "DpcForIsr", "CustomDpc"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Which Type of DPC Should You Use? + + +## + + +Depending on a driver's design, it can have any of the following: + +- A single [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) to complete all interrupt-driven I/O operations + +- A set of one or more [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routines. + +- Both a *DpcForIsr* and a set of operation-specific *CustomDpc* routines + +Whether a driver has a single *DpcForIsr* routine, a set of *CustomDpc* routines, or both, depends on the nature of its underlying device and the set of I/O requests it must support. + +Most lowest-level device drivers have a single *DpcForIsr* routine to complete I/O processing for each IRP that requires one or more operations on their respective devices. Using a single *DpcForIsr* to complete per-request, interrupt-driven I/O operations on a device that does one operation at a time is relatively easy. Such a driver's ISR need only call [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) for each interrupt-driven I/O operation. + +Few lowest-level drivers have *CustomDpc* routines unless their devices require more than one DPC to complete a varied set of interrupt-driven I/O operations. + +Using a single *DpcForIsr* to complete overlapped, interrupt-driven I/O operations on a device that can do concurrent operations is possible with careful design, but can be relatively difficult. In addition to or instead of queuing a *DpcForIsr*, an ISR can queue a set of operation-specific, driver-supplied *CustomDpc* routines by calling [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185). + +For example, consider some of the design challenges involved in writing a serial driver. As the driver of a full-duplex device, a serial driver cannot rely on a one-to-one correspondence between the order in which IRPs are queued to a *StartIo* routine and the sequence of interrupts from its device in a multitasking, multiprocessor system. Furthermore, serial drivers must handle timing out requests and asynchronous user-generated requests to cancel previously requested operations, to purge buffered data, and so forth. + +Consequently, a serial driver might maintain internal queues for the read, write, purge, and wait operations that user-mode COM port applications can request. It also could maintain reference counts or use some other tracking mechanism, such as a set of flags, for the IRPs in its internal queues. Its ISR would call **KeInsertQueueDpc** with any of a number of driver-allocated and initialized DPC objects, each associated with a driver-supplied *CustomDpc* routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Which%20Type%20of%20DPC%20Should%20You%20Use?%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/why-thunking-is-necessary.md b/windows-driver-docs-pr/kernel/why-thunking-is-necessary.md new file mode 100644 index 0000000000..3aa3bf713d --- /dev/null +++ b/windows-driver-docs-pr/kernel/why-thunking-is-necessary.md @@ -0,0 +1,104 @@ +--- +title: Why Thunking Is Necessary +author: windows-driver-content +description: Why Thunking Is Necessary +ms.assetid: ea73d355-56e8-4f56-b7e8-4dbddcd19124 +keywords: ["thunking WDK", "WOW64 thunking layer WDK", "32-bit I/O support WDK 64-bit , thunking", "buffer size WDK kernel", "DRIVER_DATA structure", "pointer precision WDK 64-bit", "fixed-precision data types WDK 64-bit"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Why Thunking Is Necessary + + +## + + +Kernel-mode drivers must validate the size of any I/O buffer passed in from a user-mode application. If a 32-bit application passes a buffer containing pointer-precision data types to a 64-bit driver, and no thunking takes place, the driver will expect the buffer to be larger than it actually is. This is because pointer precision is 32 bits on 32-bit Microsoft Windows and 64 bits on 64-bit Windows. For example, consider the following structure definition: + +``` +typedef struct _DRIVER_DATA +{ + HANDLE Event; + UNICODE_STRING ObjectName; +} DRIVER_DATA; +``` + +On 32-bit Windows, the size of the DRIVER\_DATA structure is 12 bytes. + +HANDLE **Event** +UNICODE\_STRING **ObjectName** +USHORT Length +USHORT Maximum Length +PWSTR Buffer +32 bits +(4 bytes) +16 bits +(2 bytes) +16 bits +(2 bytes) +32 bits +(4 bytes) +  + +On 64-bit Windows, the size of the DRIVER\_DATA structure is 24 bytes. (The 4 bytes of structure padding are required so that the **Buffer** member can be aligned on an 8-byte boundary.) + +HANDLE **Event** +UNICODE\_STRING **ObjectName** +USHORT Length +USHORT Maximum Length +Empty (Structure Padding) +PWSTR Buffer +64 bits +(8 bytes) +16 bits +(2 bytes) +16 bits +(2 bytes) +32 bits +(4 bytes) +64 bits +(8 bytes) +  + +If a 64-bit driver receives 12 bytes of DRIVER\_DATA when it expected 24 bytes, the size validation will fail. To prevent this, the driver must detect whether a DRIVER\_DATA structure was sent by a 32-bit application, and if so, thunk it appropriately before performing the validation. + +For example, a thunked version of the above DRIVER\_DATA structure could be defined as follows: + +``` +typedef struct _DRIVER_DATA32 +{ + VOID *POINTER_32 Event; + UNICODE_STRING32 ObjectName; +} DRIVER_DATA32; +``` + +Because it contains only fixed-precision data types, this new structure is the same size on 32-bit Windows and 64-bit Windows. + +POINTER\_32 **Event** +UNICODE\_STRING32 **ObjectName** +USHORT Length +USHORT Maximum Length +ULONG Buffer +32 bits +(4 bytes) +16 bits +(2 bytes) +16 bits +(2 bytes) +32 bits +(4 bytes) +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Why%20Thunking%20Is%20Necessary%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-driver-model.md b/windows-driver-docs-pr/kernel/windows-driver-model.md new file mode 100644 index 0000000000..ee2fe4f4fc --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-driver-model.md @@ -0,0 +1,66 @@ +--- +title: Windows Driver Model (WDM) +author: windows-driver-content +description: This section describes the Windows Driver Model (WDM), and discusses types of WDM drivers, device configuration, driver layering, and WDM versioning. +ms.assetid: 9e76c5a8-a19a-44cf-867a-b2246ea8eaf1 +keywords: ["kernel-mode drivers WDK , WDM drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Windows Driver Model (WDM) + + +This section describes the *Windows Driver Model* (WDM), and discusses types of WDM drivers, device configuration, driver layering, and WDM versioning. WDM simplifies the design of kernel-mode drivers that are written to run on multiple versions of the Windows operating system. + +## + + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[Introduction to WDM](introduction-to-wdm.md)

To allow driver developers to write device drivers that are source-code compatible across all Microsoft Windows operating systems, the Windows Driver Model (WDM) was introduced. Kernel-mode drivers that follow WDM rules are called WDM drivers.

[Types of WDM Drivers](types-of-wdm-drivers.md)

There are three kinds of WDM drivers: bus drivers, function drivers, and filter drivers.

[Device Configurations and Layered Drivers](device-configurations-and-layered-drivers.md)

For the most common kinds of devices, the Windows Driver Kit (WDK) supplies a sample set of fully functional system drivers. Individual sample drivers can be used as models when developing new drivers for similar kinds of devices. However, the system's drivers had an additional design requirement: to make it easy to develop new device drivers. Consequently, many of the system's drivers have a layered architecture so that certain drivers can be reused to support new drivers for similar devices.

[WDM Versions](wdm-versions.md)

Later versions of WDM generally support all the features available in earlier versions of WDM; that is, each new version of WDM is a superset of the previous WDM version. When possible, a cross-system driver should conform to the lowest WDM version on any operating system.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Driver%20Model%20%28WDM%29%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-clfs-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-clfs-library.md new file mode 100644 index 0000000000..8697e1ebeb --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-clfs-library.md @@ -0,0 +1,25 @@ +--- +title: Windows Kernel-Mode CLFS Library +author: windows-driver-content +description: Windows Kernel-Mode CLFS Library +ms.assetid: 4da3cb49-dc20-4713-813b-ff458c99ab90 +--- + +# Windows Kernel-Mode CLFS Library + + +Windows provides a transactional logging system for system files. This system is called the Common Log File System (CLFS). For more information about CLFS, see [Common Log File System](using-common-log-file-system.md). + +Routines that provide a direct interface for CLFS are prefixed with the letters "**Clfs**"; for a list of CLFS library routines, see [Common Log File System (CLFS) Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff541804). CLFS also provides a list of routines that you can implement to manage a CLFS; for more information on CLFS management, see [CLFS Management Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff541830). + +CLFS is a technology that is related to transacted file systems; for more information about transactions, see [Windows Kernel-Mode Transaction Manager](windows-kernel-mode-kernel-transaction-manager.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20CLFS%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-configuration-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-configuration-manager.md new file mode 100644 index 0000000000..94fac6614a --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-configuration-manager.md @@ -0,0 +1,27 @@ +--- +title: Windows Kernel-Mode Configuration Manager +author: windows-driver-content +description: Windows Kernel-Mode Configuration Manager +ms.assetid: 0499121b-6f0b-464f-b422-610122fb7d3b +--- + +# Windows Kernel-Mode Configuration Manager + + +In the earlier days of Microsoft Windows, applications and the operating system stored configuration values in "INI" (initialization) files. This provided a simple way to store state values that could be preserved from one Windows session to the next. However, as the Windows environment became more complex, a new system of storing persistent information about the operating system and applications was needed. The Windows Registry was created to store data about hardware and software. + +The Windows kernel-mode configuration manager manages the registry. If your driver needs to know about changes in the registry, it can use the routines of the configuration manager to do so by registering callbacks on specific registry data. Then, when the data in the registry changes, the callback is triggered and you can run code to process the callback information in your driver. + +Routines that provide a direct interface to the configuration manager are prefixed with the letters "**Cm**"; for example, **CmRegisterCallback**. For a list of configuration manager routines, see [Configuration Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff542038). + +In addition to directly calling the configuration manager, there are other ways you will want to work with the registry in your driver. For more information about using the registry in a driver, see [Using the Registry in a Driver](using-the-registry-in-a-driver.md) and [Registry Keys for Drivers](https://msdn.microsoft.com/library/windows/hardware/ff549538). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Configuration%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-dma-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-dma-library.md new file mode 100644 index 0000000000..412b85da70 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-dma-library.md @@ -0,0 +1,27 @@ +--- +title: Windows Kernel-Mode DMA Library +author: windows-driver-content +description: Windows Kernel-Mode DMA Library +ms.assetid: db6cc33a-474b-44a2-bd55-769ff31abae7 +--- + +# Windows Kernel-Mode DMA Library + + +To enhance performance, a device may need direct access to memory in a way that bypasses the central processing unit (CPU). This technology is called direct memory access (DMA). Windows provides a DMA library for device driver developers. + +For more information about DMA for drivers, see [DMA](https://msdn.microsoft.com/library/windows/hardware/ff544058). + +For a listing of DMA routines, see [Direct Memory Access (DMA) Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff544068). + +Note that DMA is a technology for communicating directly between device and memory and is not the same as [Device Memory Access](https://msdn.microsoft.com/library/windows/hardware/ff543138), which is a set of macros provided to read and write to I/O ports and CPU registers. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20DMA%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-executive-support-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-executive-support-library.md new file mode 100644 index 0000000000..2bd99569d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-executive-support-library.md @@ -0,0 +1,35 @@ +--- +title: Windows Kernel-Mode Executive Support Library +author: windows-driver-content +description: Windows Kernel-Mode Executive Support Library +ms.assetid: cfb8c6c0-9454-4dc6-98e8-c41cbf1c0cad +--- + +# Windows Kernel-Mode Executive Support Library + + +The Windows operating system uses the term *executive layer* to refer to kernel-mode components that provide a variety of services to device drivers, including: + +- Object management + +- Memory management + +- Process and thread management + +- Input/output management + +- Configuration management + +Each of the above managers provides direct interfaces to their individual technologies, as do several libraries. However, routines that are grouped together as a generic interface to the Executive Library are usually prefixed with "**Ex**", for example, **ExGetCurrentResourceThread**. For a list of executive library routines, see [Executive Library Support Routines](https://msdn.microsoft.com/library/windows/hardware/ff544582). + +Note that the executive layer components are part of Ntoskrnl.exe, but that drivers and the HAL are not part of the executive layer. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Executive%20Support%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-hal-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-hal-library.md new file mode 100644 index 0000000000..d9db392143 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-hal-library.md @@ -0,0 +1,23 @@ +--- +title: Windows Kernel-Mode HAL Library +author: windows-driver-content +description: Windows Kernel-Mode HAL Library +ms.assetid: 5cfdbf1b-b856-4a0c-9f56-3879482819aa +--- + +# Windows Kernel-Mode HAL Library + + +Windows runs on many different configurations of the personal computer. Each configuration requires a layer of software that interacts between the hardware and the rest of the operating system. Because this layer abstracts (hides) the low-level hardware details from drivers and the operating system, it is called the hardware abstraction layer (HAL). + +Developers are not encouraged to write their own HAL. If you need hardware access, the HAL library provides routines that can be used for that purpose. Routines that interface with the HAL directly are prefixed with the letters "**Hal**"; for a list of HAL routines, see [Hardware Abstraction Layer (HAL) Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff546644). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20HAL%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-i-o-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-i-o-manager.md new file mode 100644 index 0000000000..5c3c190611 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-i-o-manager.md @@ -0,0 +1,39 @@ +--- +title: Windows Kernel-Mode I/O Manager +author: windows-driver-content +description: Windows Kernel-Mode I/O Manager +ms.assetid: 8652f37d-0ece-4c08-9bce-499f0fedb0dd +--- + +# Windows Kernel-Mode I/O Manager + + +A computer consists of various devices that provide input and output (I/O) to and from the outside world. Typical devices are keyboards, mice, audio controllers, video controllers, disk drives, networking ports, and so on. Device drivers provide the software connection between the devices and the operating system. For this reason, I/O is very important to the device driver writer. + +The Windows kernel-mode I/O manager manages the communication between applications and the interfaces provided by device drivers. Because devices operate at speeds that may not match the operating system, the communication between the operating system and device drivers is primarily done through I/O request packets (IRPs). These packets are similar to network packets or Windows message packets. They are passed from operating system to specific drivers and from one driver to another. + +The Windows I/O system provides a layered driver model called stacks. Typically IRPs go from one driver to another in the same stack to facilitate communication. For example, a joystick driver would need to communicate to a USB hub, which in turn would need to communicate to a USB host controller, which would then need to communicate through a PCI bus to the rest of the computer hardware. The stack consists of joystick driver, USB hub, USB host controller, and the PCI bus. This communication is coordinated by having each driver in the stack send and receive IRPs. + +It cannot be stressed enough that your driver must send and receive IRPs on a timely basis for the whole stack to operate efficiently. If your driver is part of a stack and does not properly receive, handle, and pass on the information, your driver may cause system crashes. + +For more information about IRPs, see [Handling IRPs](handling-irps.md). + +For more information about driver stacks, see [Device Objects and Device Stacks](device-objects-and-device-stacks.md). + +For programming techiques related to I/O management, see [I/O Manager Programming Techniques](i-o-programming-techniques.md). + +Routines that provide a direct interface to the I/O manager are usually prefixed with the letters "**Io**"; for example, **IoCreateDevice**. For a list of I/O manager routines, see [I/O Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff551797). + +For lists of routines that relate to IRPS, see [IRPs](https://msdn.microsoft.com/library/windows/hardware/ff550701). + +The I/O manager has two subcomponents: the Plug and Play manager and power manager. They manage the I/O functionality for the technologies of Plug and Play and power management. For more information about Plug and Play management, see [Windows Kernel-Mode Plug and Play Manager](windows-kernel-mode-plug-and-play-manager.md) and for more information about power management, see [Windows Kernel-Mode Power Manager](windows-kernel-mode-power-manager.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20I/O%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-library.md new file mode 100644 index 0000000000..cc3f7fbd8e --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-library.md @@ -0,0 +1,27 @@ +--- +title: Windows Kernel-Mode Kernel Library +author: windows-driver-content +description: Windows Kernel-Mode Kernel Library +ms.assetid: e62264ee-5d52-4ae1-bd54-51e93c34762f +--- + +# Windows Kernel-Mode Kernel Library + + +The *kernel* of an operating system implements the core functionality that everything else in the operating system depends upon. The Microsoft Windows kernel provides basic low-level operations such as scheduling threads or routing hardware interrupts. It is the heart of the operating system and all tasks it performs must be fast and simple. + +Routines that provide a direct interface to the kernel library are usually prefixed with "**Ke**", for example, **KeGetCurrentThread**. For a list of kernel library routines, see [Kernel Library Support Routines](https://msdn.microsoft.com/library/windows/hardware/ff542078). + +**Note**  The term *microkernel* does not apply to the current kernel used in the Windows operating system. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Kernel%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-transaction-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-transaction-manager.md new file mode 100644 index 0000000000..67cffb2a23 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-kernel-transaction-manager.md @@ -0,0 +1,25 @@ +--- +title: Windows Kernel-Mode Kernel Transaction Manager +author: windows-driver-content +description: Windows Kernel-Mode Kernel Transaction Manager +ms.assetid: 43bf96ed-8be8-4670-a310-99cd7c7f9073 +--- + +# Windows Kernel-Mode Kernel Transaction Manager + + +When you are dealing with multiple reads and writes on one or more data stores, and the operations must all atomically succeed or fail to preserve the integrity of the data, you might want to group the operations together as a single transaction. If all of the operations within the transaction succeed, the transaction can be committed so that all the changes persist as an atomic unit. If a failure occurs, the transaction can be rolled back so that the data stores are restored to their original state. + +The kernel transaction manager (KTM) is the Windows kernel-mode component that implements transaction processing in kernel mode. KTM allows kernel mode components, such as drivers, to perform transactions. In addition, KTM is the platform on which user-mode [Transactional NTFS (TxF)](http://go.microsoft.com/fwlink/p/?linkid=131245) is based. + +For information about how to use KTM in kernel-mode components, see [Kernel Transaction Manager](using-kernel-transaction-manager.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Kernel%20Transaction%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-memory-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-memory-manager.md new file mode 100644 index 0000000000..af8695f1b7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-memory-manager.md @@ -0,0 +1,33 @@ +--- +title: Windows Kernel-Mode Memory Manager +author: windows-driver-content +description: Windows Kernel-Mode Memory Manager +ms.assetid: ab464d5b-7bad-494e-80cd-e32ca9e9fa8d +--- + +# Windows Kernel-Mode Memory Manager + + +The Windows kernel-mode memory manager component manages physical memory for the operating system. This memory is primarily in the form of random access memory (RAM). + +The memory manager manages memory by performing the following major tasks: + +- Managing the allocation and deallocation of memory virtually and dynamically. + +- Supporting the concepts of memory-mapped files, shared memory, and copy-on-write. + +For more detailed information about memory management for drivers, see [Memory Management for Windows Drivers](managing-memory-for-drivers.md). + +Routines that provide a direct interface to the memory manager are usually prefixed with the letters "**Mm**"; for example, **MmGetPhysicalAddress**. For a list of memory manager routines, see [Memory Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff554435). + +For lists of memory manager routines sorted by functionality, see [Memory Allocation and Buffer Management](https://msdn.microsoft.com/library/windows/hardware/ff554422). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Memory%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-object-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-object-manager.md new file mode 100644 index 0000000000..1999213808 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-object-manager.md @@ -0,0 +1,65 @@ +--- +title: Windows Kernel-Mode Object Manager +author: windows-driver-content +description: Windows Kernel-Mode Object Manager +ms.assetid: f10561a3-d831-4c13-9edf-be40fb1db403 +--- + +# Windows Kernel-Mode Object Manager + + +The Windows kernel-mode object manager component manages *objects*. Files, devices, synchronization mechanisms, registry keys, and so on, are all represented as objects in kernel mode. Each object has a *header* (containing information about the object such as its name, type, and location), and a *body* (containing data in a format determined by each type of object). + +Windows has more than 25 types of objects. A few of the types are: + +- Files + +- Devices + +- Threads + +- Processes + +- Events + +- Mutexes + +- Semaphores + +- Registry keys + +- Jobs + +- Sections + +- Access tokens + +- Symbolic links + +The object manager manages the objects in Windows by performing the following major tasks: + +- Managing the creation and destruction of objects. + +- Keeping an object namespace database for tracking object information. + +- Keeping track of resources assigned to each process. + +- Tracking access rights for specific objects to provide security. + +- Managing the lifetime of an object and determining when an object will be automatically destroyed to recycle resource space. + +For more information about objects in Windows, see [Device Objects and Device Stacks](device-objects-and-device-stacks.md). + +Routines that provide a direct interface to the object manager are usually prefixed with the letters "**Ob**"; for example, **ObGetObjectSecurity**. For a list of object manager routines, see [Object Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff557759). + +Note that Windows uses objects as an abstraction for resources. However, Windows is not object-oriented in the classical C++ meaning of the term. Windows is *object-based*. For more information on what object-based means for Windows, see [Object-Based](object-based.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Object%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-plug-and-play-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-plug-and-play-manager.md new file mode 100644 index 0000000000..ab14532a66 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-plug-and-play-manager.md @@ -0,0 +1,31 @@ +--- +title: Windows Kernel-Mode Plug and Play Manager +author: windows-driver-content +description: Windows Kernel-Mode Plug and Play Manager +ms.assetid: 43d06dbe-da66-4103-8be3-f27ff075a1b4 +--- + +# Windows Kernel-Mode Plug and Play Manager + + +Plug and Play (PnP) is a combination of hardware technology and software techniques that enables a PC to recognize when a device is added to the system. With PnP, the system configuration can change with little or no input from the user. For example, when a USB thumb drive is plugged in, Windows can detect the thumb drive and add it to the file system automatically. However, to do this, the hardware must follow certain requirements and so must the driver. + +For more information about PnP for drivers, see [Plug and Play](implementing-plug-and-play.md). + +The PnP manager is actually a subsystem of the I/O manager. For more information about the I/O manager, see [Windows Kernel-Mode I/O Manager](windows-kernel-mode-i-o-manager.md). + +For lists of PnP routines, see [Plug and Play Routines](https://msdn.microsoft.com/library/windows/hardware/ff558809). + +Note that there are no routines that provide a direct interface to the PnP manager; that is, there are no "**Pp**" routines. + +The Windows Driver Frameworks (WDF) provide a set of libraries to make PnP management much easier. For more information about WDF, see [Kernel-Mode Driver Framework Overview](https://msdn.microsoft.com/library/windows/hardware/ff544296). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Plug%20and%20Play%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-power-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-power-manager.md new file mode 100644 index 0000000000..981a5590e6 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-power-manager.md @@ -0,0 +1,47 @@ +--- +title: Windows Kernel-Mode Power Manager +author: windows-driver-content +description: Windows Kernel-Mode Power Manager +ms.assetid: 2d39e43a-63a6-4474-a1ed-c24b4526a3f5 +--- + +# Windows Kernel-Mode Power Manager + + +Windows uses power management technology to reduce power consumption for PCs in general and for battery-powered laptops in particular. For example, a Windows computer can be put in a sleep or hibernation state. A complex power management system for computer devices has evolved so that when the computer begins to shut down or go to lower power consumption, the attached devices can also be powered down in a proper manner so that no data is lost. But these devices need a warning that the power status in changing and they may also need to be part of a communications loop that tells the controlling device to wait until they can shut down down properly. + +The Windows kernel-mode power manager manages the orderly change in power status for all devices that support power state changes. This is often done through a complex stack of devices controlling other devices. Each controlling device is called a *node* and must have a driver that can handle the communication of power state changes up and down through a device stack. + +If you are writing a driver that can be affected by power-state changes, you must be able to process the following types of information in your driver code: + +- System activity level. + +- System battery level. + +- Current requests to shut down, sleep, or hibernate. + +- User actions such as pressing a power button. + +- Control panel settings, such as automatically shutting down at 10 percent battery power. + +The power manager handles these requests using IRPs. For more information about IRPs, see [Handling IRPs](handling-irps.md). + +The power manager works in combination with policy management to handle power management and coordinate power events, and then generates power management IRPs. The power manager collects requests to change the power state, decides which order the devices must have their power state changed, and then send the appropriate IRPs to tell the appropriate drivers to make the changes (which in turn may tell subdevices to make the change as well). The policy manager monitors activity in the system and integrates user status, application status, and device driver status into power policy. + +For more detailed information about power management, see [Power Management for Windows Drivers](implementing-power-management.md). + +The power manager is considered a subcomponent of the I/O manager. For more information, see [Windows I/O Manager](windows-kernel-mode-i-o-manager.md). + +Routines that provide a direct interface to the power manager are usually prefixed with "**Po**"; for example, **PoSetPowerState**. For a list of power manager routines, see [Power Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff559835). + +The Windows Driver Frameworks (WDF) provides a set of libraries to make power management much easier. For more information about WDF, see [Kernel-Mode Driver Framework Overview](https://msdn.microsoft.com/library/windows/hardware/ff544296). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Power%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-process-and-thread-manager.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-process-and-thread-manager.md new file mode 100644 index 0000000000..d6e794e663 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-process-and-thread-manager.md @@ -0,0 +1,42 @@ +--- +title: Windows Kernel-Mode Process and Thread Manager +author: windows-driver-content +description: Windows Kernel-Mode Process and Thread Manager +ms.assetid: 4053c73e-190d-4ffe-8db2-f531d120ba81 +--- + +# Windows Kernel-Mode Process and Thread Manager + + +A *process* is a software program that is currently running in Windows. Every process has an ID, a number that identifies it. A *thread* is an object that identifies which part of the program is running. Each thread has an ID, a number that identifies it. + +A process may have more than one thread. The purpose of a thread is to allocate processor time. On a machine with one processor, more than one thread can be allocated, but only one thread can run at a time. Each thread only runs a short time and then the execution is passed on to the next thread, giving the user the illusion that more than one thing is happening at once. On a machine with more than one processor, true multi-threading can take place. If an application has multiple threads, the threads can run simultaneously on different processors. + +The Windows kernel-mode process and thread manager handles the execution of all threads in a process. Whether you have one processor or more, great care must be taken in driver programming to make sure that all threads of your process are designed so that no matter what order the threads are handled, your driver will operate properly. + +If threads from different processes attempt to use the same resource at the same time, problems can occur. Windows provides several techniques to avoid this problem. The technique of making sure that threads from different processes do not touch the same resource is called *synchronization*. For more information about synchronization, see [Synchronization Techniques](synchronization-techniques.md). + +Routines that provide a direct interface to the process and thread manager are usually prefixed with the letters "**Ps**"; for example, **PsCreateSystemThread**. For a list of process and thread manager routines, see [Process and Thread Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff559917). For a list of routines that relate to processes, threads, and synchronization, see [Synchronization](https://msdn.microsoft.com/library/windows/hardware/ff564517). + +## Subsystem Processes + + +Starting in Windows 10, the Windows Subsystem for Linux (WSL) enables a user to run native Linux ELF64 binaries on Windows, alongside other Windows applications. For information about WSL architecture and the user-mode and kernel-mode components that are required to run the binaries, see the posts on the [Windows Subsystem for Linux](https://go.microsoft.com/fwlink/p/?linkid=838012) blog. + +One of the components is a *subsystem process* that hosts the unmodified user-mode Linux binary, such as /bin/bash. Subsystem processes do not contain data structures associated with Win32 processes, such as Process Environment Block (PEB) and Thread Environment Block (TEB). For a subsystem process, system calls and user mode exceptions are dispatched to a paired driver. + +Here are the changes to the [Process and Thread Manager Routines](https://msdn.microsoft.com/library/windows/hardware/ff559917) in order to support subsystem processes: + +- The WSL type is indicated by the **SubsystemInformationTypeWSL** value in the [**SUBSYSTEM\_INFORMATION\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/mt805892) enumeration. Drivers can call [**NtQueryInformationProcess**](https://msdn.microsoft.com/library/windows/desktop/ms684280) and [**NtQueryInformationThread**](https://msdn.microsoft.com/library/windows/desktop/ms684283) to determine the underlying subsystem. Those calls return **SubsystemInformationTypeWSL** for WSL. +- Other kernel mode drivers can get notified about subsystem process creation/deletion by registering their callback routine through the [**PsSetCreateProcessNotifyRoutineEx2**](https://msdn.microsoft.com/library/windows/hardware/mt805891) call. To get notifications about thread creation/deletion, drivers can call [**PsSetCreateThreadNotifyRoutineEx**](https://msdn.microsoft.com/library/windows/hardware/dn957857), and specify **PsCreateThreadNotifySubsystems** as the type of notification. +- The [**PS\_CREATE\_NOTIFY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff559960) structure has been extended to include a **IsSubsystemProcess** member that indicates a subsystem other than Win32. Other members such as **FileObject**, **ImageFileName**, **CommandLine** indicate additional information about the subsystem process. For information about the behavior of those members, see [**SUBSYSTEM\_INFORMATION\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/mt805892). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Process%20and%20Thread%20Manager%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-run-time-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-run-time-library.md new file mode 100644 index 0000000000..d33b0ab212 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-run-time-library.md @@ -0,0 +1,25 @@ +--- +title: Windows Kernel-Mode Run-Time Library +author: windows-driver-content +description: Windows Kernel-Mode Run-Time Library +ms.assetid: 9c968014-c529-43e1-a8a6-a307c90e4162 +--- + +# Windows Kernel-Mode Run-Time Library + + +Windows provides a set of common utility routines needed by various kernel-mode components. For example, [**RtlCheckRegistryKey**](https://msdn.microsoft.com/library/windows/hardware/ff561754) is used to see if a given key is in the registry. + +Most of the run-time library (RTL) routines are prefixed with the letters "**Rtl**"; for a list of the run-time library routines for the kernel, see [Run-Time Library (RTL) Routines](https://msdn.microsoft.com/library/windows/hardware/ff563638). + +There is also a different kernel-mode library specifically designed for safe string handling. For more information about the safe string library, see [Windows Kernel-Mode Safe String Library](windows-kernel-mode-safe-string-library.md). Note that safe string library routines are also usually prefixed by "**Rtl**" but are not part of the run-time library (RTL). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Run-Time%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-safe-string-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-safe-string-library.md new file mode 100644 index 0000000000..0a7406ffda --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-safe-string-library.md @@ -0,0 +1,27 @@ +--- +title: Windows Kernel-Mode Safe String Library +author: windows-driver-content +description: Windows Kernel-Mode Safe String Library +ms.assetid: a54cd20c-2c2d-462d-b9fc-112e99562e52 +--- + +# Windows Kernel-Mode Safe String Library + + +One of the major problems in software security is related to the vulnerability of working with strings. To provide greater security, Windows provides a safe string library. + +Safe string library routines are prefixed with the letters "**Rtl**"; for a list of all safe string library routines for the kernel, see [Safe String Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff563648). + +For more information about using safe strings, see [Using Safe String Functions](using-safe-string-functions.md). + +Note that there is also a separate run-time library for general C programming in the kernel that has string functionality as well. For more information about the run-time library (RTL), see [Windows Kernel-Mode Run-Time Library](windows-kernel-mode-run-time-library.md). Note that even though both libraries are prefixed with "**Rtl**" they are not the same library. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Safe%20String%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-security-reference-monitor.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-security-reference-monitor.md new file mode 100644 index 0000000000..db09cd46aa --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-security-reference-monitor.md @@ -0,0 +1,25 @@ +--- +title: Windows Kernel-Mode Security Reference Monitor +author: windows-driver-content +description: Windows Kernel-Mode Security Reference Monitor +ms.assetid: 80c63d9c-cb8e-47c0-8afd-ca78dbc43327 +--- + +# Windows Kernel-Mode Security Reference Monitor + + +An increasingly important aspect of operating systems is security. Before an action can take place, the operating system must be sure that the action is not a violation of system policy. For example, a device may or may not be accessible to all requests. When creating a driver, you may want to allow some requests to succeed or fail, depending on the permission of the entity making the request. + +Windows uses an access control list (ACL) to determine which objects have what security. The Windows kernel-mode security reference monitor provides routines for your driver to work with access control. For more information about the ACL, see [Access Control List](https://msdn.microsoft.com/library/windows/hardware/ff538821). + +Routines that provide a direct interface to the security reference monitor are prefixed with the letters "**Se**"; for example, **SeAccessCheck**. For a list of security reference monitor routines, see [Security Reference Monitor Routines](https://msdn.microsoft.com/library/windows/hardware/ff563711). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20Security%20Reference%20Monitor%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/windows-kernel-mode-wmi-library.md b/windows-driver-docs-pr/kernel/windows-kernel-mode-wmi-library.md new file mode 100644 index 0000000000..e5eebac2d7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/windows-kernel-mode-wmi-library.md @@ -0,0 +1,29 @@ +--- +title: Windows Kernel-Mode WMI Library +author: windows-driver-content +description: Windows Kernel-Mode WMI Library +ms.assetid: ca981f38-8f3b-48cc-969f-ce53b85bba20 +--- + +# Windows Kernel-Mode WMI Library + + +Windows provides a general mechanism for managing components. This system is called Windows Management Instrumentation (WMI). To satisify Windows Driver Model (WDM) requirements, you should implement WMI for your driver so that your driver can be managed by the system. + +For more information on WMI, see [Windows Management Instrumentation](implementing-wmi.md). + +Routines that provide a direct interface to the WMI library are prefixed with the letters "**Wmi**"; for a list of WMI routines, see [Windows Management Instrumentation (WMI) Library Routines](https://msdn.microsoft.com/library/windows/hardware/ff566359). + +For a list of WMI callbacks, see [WMI Library Callback Routines](https://msdn.microsoft.com/library/windows/hardware/ff566357). + +Communication with WMI is done with IRPs. For a list of routines that your driver can use to receive IRPs, see [WMI IRP Processing Routines](https://msdn.microsoft.com/library/windows/hardware/ff566353). For a list of routines that your driver can use to send WMI IRPs, see [WMI IRP Sending Routines](https://msdn.microsoft.com/library/windows/hardware/ff566355). For a list of IRPs that are used with WMI, see [WMI Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff566361). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Windows%20Kernel-Mode%20WMI%20Library%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-and-the-power-management-tab.md b/windows-driver-docs-pr/kernel/wmi-and-the-power-management-tab.md new file mode 100644 index 0000000000..1a65032cfc --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-and-the-power-management-tab.md @@ -0,0 +1,44 @@ +--- +title: WMI and the Power Management Tab +author: windows-driver-content +description: WMI and the Power Management Tab +ms.assetid: ff270fc0-806b-4014-ba9c-9c321a10c893 +keywords: ["WMI WDK kernel , property sheets", "property sheets WDK WMI", "device property sheets WDK WMI", "power management WDK WMI", "property pages WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI and the Power Management Tab + + +## + + +Drivers that support power management can automatically enable the **Power Management** tab for the device property sheet in Device Manager. If a driver handles the GUID\_POWER\_DEVICE\_ENABLE or GUID\_POWER\_DEVICE\_WAKE\_ENABLE WMI class GUIDs, Device Manager displays a **Power Management** tab on the device property sheet. Certain controls on the property page are enabled depending on which WMI class GUIDs the driver supports. + +The GUID\_POWER\_DEVICE\_*XXX* class GUIDs enable controls on the property page as follows: + +- GUID\_POWER\_DEVICE\_ENABLE + + Enables a check box to activate or deactivate power management for the device. The data block for the WMI class consists of a single BOOLEAN value that indicates whether power management is enabled. The meaning of the value is device-dependent. + +- GUID\_POWER\_DEVICE\_WAKE\_ENABLE + + Enables a check box to activate or deactivate sending wait/wake IRPs. When selected, the driver should send an [**IRP\_MN\_WAIT\_WAKE**](https://msdn.microsoft.com/library/windows/hardware/ff551766) request to its physical device object. This enables the device to wake the system in response to an external event. For example, when enabled for the keyboard class driver, the keyboard device will wake the system when a key is pressed. When the check box is not selected, the driver should cancel the **IRP\_MN\_WAIT\_WAKE** request. The data block for the WMI class consists of a single BOOLEAN value that indicates the current state of the check box. + +WMI query requests are sent for the GUID\_POWER\_DEVICE\_*XXX* WMI class GUIDs whenever the property sheet for the driver is opened in Device Manager. The WMI change requests are sent whenever one of the check box values on the **Power Management** tab changes. Users will expect the value they set to persist between driver loads and unloads, so drivers should store the current value of either property in the registry. + +The mouse or keyboard class sample drivers both handle the GUID\_POWER\_DEVICE\_WAKE\_ENABLE WMI class GUID. See \\src\\input\\kbdclass and \\src\\input\\mouclass in the Windows Driver Kit (WDK). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20and%20the%20Power%20Management%20Tab%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-architecture.md b/windows-driver-docs-pr/kernel/wmi-architecture.md new file mode 100644 index 0000000000..7796c4fa16 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-architecture.md @@ -0,0 +1,40 @@ +--- +title: WMI Architecture +author: windows-driver-content +description: WMI Architecture +ms.assetid: cdc8f318-1931-426e-bd9c-da7aa6a11036 +keywords: ["WMI WDK kernel , architecture"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Architecture + + +## + + +To support WMI, your driver registers as a WMI provider. A WMI provider is a Win32 dynamic-link library (DLL) that handles WMI requests and supplies WMI instrumentation data. See [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md) to learn how a driver registers as a WMI provider. + +After your driver is registered as a WMI provider, WMI consumers then request data or invoke methods exposed by providers. + +Query requests travel from user-mode consumers down to the WMI kernel-mode service, which in turn sends IRP requests to your driver. + +For instance, when a WMI client requests a given data block, the WMI kernel component sends a query request to the driver to retrieve or set data. The driver handles WMI requests as described in [Handling WMI Requests](handling-wmi-requests.md). + +The following figure shows this data flow: + +![diagram illustrating wmi architecture data flow](images/wmi1a.png) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Architecture%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-class-examples.md b/windows-driver-docs-pr/kernel/wmi-class-examples.md new file mode 100644 index 0000000000..4bb3f28e25 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-class-examples.md @@ -0,0 +1,128 @@ +--- +title: WMI Class Examples +author: windows-driver-content +description: WMI Class Examples +ms.assetid: 5b0ef39a-32bd-4f62-ad8f-fdab74409294 +keywords: ["classes WDK WMI", "WMI WDK kernel , classes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Class Examples + + +## + + +The following examples show class definitions from the schema of a serial port driver. Note that the **guid** values shown in these examples are placeholders. Each class definition must have a unique GUID generated by guidgen.exe or uuidgen.exe (which are included in the Microsoft Windows SDK). + +``` +// Standard class for reporting serial port information +// Class qualifiers +[WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"), +Dynamic, Provider("WMIProv"), +WmiExpense(1), +Locale("MS\\0x409"), +Description("Description of class"] + +//Class name +class Vendor_SerialInfo { + +//Required items + [key, read] + string InstanceName; + [read] + boolean Active; + +// Bytes sent on port +// Property qualifiers + [read, + WmiDataId(1), + WmiScale(0), + WmiComplexity(1), + WmiVolatility(1000)] + Description("Description of property")] +// Data item + uint64 BytesSent; + +// Bytes received on port + [read, + write, + WmiDataId(2), + WmiScale(0), + WmiVolatility(1000)] + uint64 BytesReceived; + +// Who owns the port + [read, + WmiDataId(4), + WmiScale(0), + WmiVolatility(60000)] + string Owner; + +// Status bit array + [read, write, + WmiDataId(3), + WmiScale(0)] + byte Status[16]; + +//The number of items in the XmitBufferSize array + [read, + WmiDataId(5), + WmiScale(0), + WmiComplexity(1), + WmiVolatility(1000)] + uint32 XmitDescriptorCount; + +//Array of XmitDescriptor classes + [read, + WmiDataId(6), + WmiSizeIs("XmitDescriptorCount"), + WmiScale(0), + WmiComplexity(1), + WmiVolatility(1000)] + Vendor_XmitDescriptor XmitBufferSize[]; +} +``` + +The following is the class definition for the embedded class shown in the previous example. Note that this class does not contain **InstanceName** or **Active** items. + +``` +// Example of an embedded class +[WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"), +class Vendor_XmitDescriptor { + [read, WmiDataId(1)] int32 DestinationIndex; + [read, WmiDataId(2)] int32 DestinationTarget; +} +``` + +The following is a class definition for an event block. The class is derived from **WmiEvent**. + +``` +// Example of an event + [WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"), + Dynamic, Provider("WMIProv"), + locale("MS\\0x409"), + Description("Serial Send Event"), + WmiExpense(1)] +class Vendor_SerialSendEvent : WMIEvent +{ +// Required items + [key, read] + string InstanceName; + [read] + boolean Active; +``` + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Class%20Examples%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-class-names-and-base-classes.md b/windows-driver-docs-pr/kernel/wmi-class-names-and-base-classes.md new file mode 100644 index 0000000000..0574307f93 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-class-names-and-base-classes.md @@ -0,0 +1,88 @@ +--- +title: WMI Class Names and Base Classes +author: windows-driver-content +description: WMI Class Names and Base Classes +ms.assetid: 6c3f74a3-e596-4694-8619-db38d67e030c +keywords: ["base classes WDK WMI", "names WDK WMI", "classes WDK WMI", "WMI WDK kernel , classes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Class Names and Base Classes + + +## + + +WMI class names are case-insensitive, must start with a letter, and cannot begin or end with an underscore. All remaining characters must be letters, digits, or underscores. + +WMI client applications can access a driver's WMI class names and display them to users. Descriptive class names can help make classes more intuitive to use. + +WMI class names must be unique within the WMI namespace. Consequently a driver's WMI class names cannot duplicate those defined by another driver. + +To help prevent name collisions, a driver writer can define a driver-specific base class and derive all of the driver's WMI classes from that base class. The class name and base class name together are more likely to yield a unique name. For example, the following shows an abstract base class for a serial driver's data blocks: + +``` +// Serial driver's base class for data blocks +[abstract] +class MSSerial { +} + +// Example class definition for a data block +[ + //Class qualifiers +] +class MSSerial_StandardSerialInformation : MSSerial +{ + //Data items +} +``` + +Device-specific custom data blocks should include the manufacturer, model, and type of driver or device in the base class name. For example: + +``` +[abstract] +class Adaptec1542 { +} + +class Adaptec1542_Bandwidth : Adaptec1542 { + //Data items +} + +class Adaptec1542_Speed : Adaptec1542 { + //Data items +} +``` + +WMI allows only one abstract base class in a given class hierarchy. Classes that define event blocks must derive from **WmiEvent**, which is an abstract base class, so the **abstract** qualifier cannot be used in a driver-defined base class for event blocks. Instead, derive a nonabstract base class from **WmiEvent**, then derive individual event classes from that base class. For example: + +``` +//Serial driver's base class for event blocks +class MSSerialEvent : WmiEvent +{ +} + +//Example class definition for an event block +[ + //Class qualifiers +] +class MSSerial_SendEvent : MSSerialEvent +{ + //Data items +} +``` + +For more information about defining base classes in MOF format, see the Microsoft Windows SDK. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Class%20Names%20and%20Base%20Classes%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-class-qualifiers.md b/windows-driver-docs-pr/kernel/wmi-class-qualifiers.md new file mode 100644 index 0000000000..4cb8de8c72 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-class-qualifiers.md @@ -0,0 +1,83 @@ +--- +title: WMI Class Qualifiers +author: windows-driver-content +description: WMI Class Qualifiers +ms.assetid: 62a00184-59b7-496d-b523-f4adb879d402 +keywords: ["class qualifiers WDK WMI", "MOF class qualifiers WDK WMI", "embedded classes WDK WMI", "dynamic MOF qualifiers WDK WMI", "static MOF qualifiers WDK WMI", "classes WDK WMI", "WMI WDK kernel , classes"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Class Qualifiers + + +## + + +The following table lists the required and optional MOF class qualifiers that can be used to describe a driver's WMI data blocks and event blocks. + +An *embedded class*, which is a class used solely as a data item in another class and not exposed as a WMI data block, requires only the **WMI** and **Guid** qualifiers. The other qualifiers are irrelevant to embedded classes and are ignored. For more information about embedded classes, see [Driver-defined WMI Data Items](driver-defined-wmi-data-items.md). + +**Dynamic** and **Static** are standard MOF qualifiers. For information about other standard MOF qualifiers, see the Microsoft Windows SDK. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
QualifierDescription

Dynamic

Indicates that the data provider supplies instances of the data block at run time, rather than providing instances of static data in the MOF file. All data and event blocks that a driver registers with WMI must be defined with the Dynamic qualifier.

Static

Indicates that the data provider supplies instances of static data in the MOF file, rather than supplying instances of the data block at run time. A driver does not register static data blocks with WMI, because the static data resides in the WMI database. Classes marked as Static in the MOF file should not be registered by the driver's [IRP_MN_REGINFO](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [IRP_MN_REGINFO_EX](https://msdn.microsoft.com/library/windows/hardware/ff551734) handlers.

Provider("WMIProv")

(Required) Indicates that the provider of the class is a WMI provider.

WMI

(Required) Indicates that the class is a WMI class.

Description("description-string")

(Optional) Specifies a description of the block for the locale specified by the Locale qualifier. If defined, WMI clients can display the description string to users. A driver writer can use Description to document a class.

Guid("guid-string")

(Required) Specifies the GUID, in string format, that uniquely identifies the block to WMI. A driver writer should generate a GUID for each data block in the driver's MOF file, using either guidgen.exe or uuidgen.exe (which are included in the Windows SDK). A driver passes this value in GUID format to WMI when the driver registers its blocks. WMI then uses the GUID to look up the block's definition in the driver's MOF resource.

Locale("MS\\locale-identifier")

(Optional) Specifies the language identifier and locale for the string specified by Description. For example, a locale-identifier of 0x409 specifies American English. A single MOF file can contain blocks with different locales, but typically all of the blocks in a MOF file have the same locale.

WmiExpense(expense-value)

(Optional) Specifies the average number of CPU cycles needed to collect data for the data block. For example, a WMI client might check a data block's WmiExpense value to determine how often to query for its data. If WmiExpense is omitted, expense-value is assumed to be 0. WmiExpense is unrelated to registering a data block as expensive to collect.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Class%20Qualifiers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-event-tracing.md b/windows-driver-docs-pr/kernel/wmi-event-tracing.md new file mode 100644 index 0000000000..2710cf8334 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-event-tracing.md @@ -0,0 +1,68 @@ +--- +title: WMI Event Tracing +author: windows-driver-content +description: WMI Event Tracing +ms.assetid: 72505a9a-830a-4529-ba73-31af0fedfeec +keywords: ["WMI WDK kernel , event tracking", "events WDK WMI", "tracing WDK WMI", "WMI WDK kernel , WDM drivers", "WDM drivers WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Event Tracing + + +## + + +This section describes the WMI extensions to WDM (supported by Windows 2000 and later) that kernel-mode drivers, as information providers, can use to provide information to information consumers. Drivers typically provide information that a consumer uses to determine the driver's configuration and resource usage. In addition to the WMI extensions to WDM, a user-mode API supports providers or consumers of WMI event information—see the Windows SDK for more information. + +The event tracing logger supports up to 32 instances. One of the instances is reserved for tracing the kernel. The logger supports tracing a high event rate. + +Trace events are defined in the same manner as other WMI events. WMI events are described in the MOF file. For more information about WMI event descriptions, see [MOF Syntax for WMI Data and Event Blocks](mof-syntax-for-wmi-data-and-event-blocks.md). + +The process by which kernel-mode drivers log information is integrated into the existing WMI infrastructure. To log trace events, a driver does the following: + +1. Register as a WMI provider by calling [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480). + +2. Mark events as traceable by setting WMIREG\_FLAG\_TRACED\_GUID in the **Flags** member of the [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structure that is passed when the driver registers events with WMI. + +3. Specify one event as the control event for overall enabling/disabling of a set of trace events by setting WMIREG\_FLAG\_TRACE\_CONTROL\_GUID in the **Flags** member of the **WMIREGGUID** structure that is passed when the driver registers events with WMI. + +4. Upon receiving a request from WMI to enable events where the GUID matches the trace control GUID, the driver should store the handle to the logger. The value will be needed when writing an event. For information about how to use this handle, see step 6. The logger handle value is contained in the **HistoricalContext** member of the [**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) portion of the WMI buffer that is part of the parameters in the enable events request. + +5. Decide whether the trace event will be sent to WMI event consumers or is targeted for the WMI event logger only. This will determine where the memory for the [**EVENT\_TRACE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff544329) structure should come from. This memory will eventually be passed to [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520). + + If the event is a log event only, the memory will not be deleted by WMI. In this case, the driver should pass in a buffer on the stack or should be reusing an allocated buffer for this purpose. For performance reasons, the driver should minimize any unnecessary calls to allocate or free memory. Failure to comply with this recommendation will compromise the integrity of the timing information contained in the log file. + + If the event is to be sent to both the logger and to WMI event consumers, then the memory must be allocated from a nonpaged pool. In this case the event will be sent to the logger and then forwarded to WMI to be sent to WMI event consumers who have requested notification of the event. The memory for the event will then be freed by WMI according to the behavior of **IoWMIWriteEvent**. + +6. After the memory for the [**EVENT\_TRACE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff544329) and any driver event data, if any, has been secured, the following information should be set: + + Set the **Size** member to the sizeof(**EVENT\_TRACE\_HEADER**) plus the size of any additional driver event data that will be appended on to the end of **EVENT\_TRACE\_HEADER**. + + Set the **Flags** member to WNODE\_FLAG\_TRACED\_GUID to have the event sent to the logger. If the event is to be sent to WMI event consumers as well, set the WNODE\_FLAG\_LOG\_WNODE. Note, it is not necessary to set WNODE\_FLAG\_TRACED\_GUID if setting WNODE\_FLAG\_LOG\_WNODE. If both are set, WNODE\_FLAG\_TRACED\_GUID will take precedence and the event will not be sent to WMI event consumers. + + Set the **Guid** or the **GuidPtr** member. If using **GuidPtr**, set WNODE\_FLAG\_USE\_GUID\_PTR in the **Flags** member. + + Optionally, specify a value for **TimeStamp**. If the driver does not specify a **TimeStamp** value the logger will fill this in. If the driver does not want the logger to set the time stamp then it should set WNODE\_FLAG\_USE\_TIMESTAMP in the **Flags** member. + + Set any of the following **EVENT\_TRACE\_HEADER** members that have meaning to the driver: **Class.Type**, **Class.Level**, and **Class.Version**. + + Finally cast the **EVENT\_TRACE\_HEADER** to a **WNODE\_HEADER** and set the **HistoricalContext** value of the **Wnode** to the logger handle that was saved in step 4 above. + +7. Call [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) with the pointer to the **EVENT\_TRACE\_HEADER** structure. + +The driver should continue logging trace events associated with the control GUID until the driver receives notification to disable event logging via an **IRP\_MN\_DISABLE\_EVENTS** request. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Event%20Tracing%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-generic-property-page-provider.md b/windows-driver-docs-pr/kernel/wmi-generic-property-page-provider.md new file mode 100644 index 0000000000..0f4524ea49 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-generic-property-page-provider.md @@ -0,0 +1,90 @@ +--- +title: WMI Generic Property Page Provider +author: windows-driver-content +description: WMI Generic Property Page Provider +ms.assetid: 44cfafdf-c8e2-4175-95e5-3c5d03dc206d +keywords: ["WMI WDK kernel , property sheets", "property sheets WDK WMI", "generic property page providers WDK WMI", "property pages WDK WMI", "property qualifiers WDK WMI", "device property sheets WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Generic Property Page Provider + + +## + + +On Windows XP and later operating systems, drivers can expose their WMI classes through the WMI generic property page provider. The provider uses each class declaration to create a simple property page for the class properties. + +### How Property Qualifiers Determine the Property Page + +The WMI generic property page provider uses a control appropriate for the data type of each property in the class. The following property qualifiers modify the type of control used: + +- **Write** + + A property with the **write** qualifier can be changed through the property page. Otherwise the property is read-only. + +- **Values** and **ValuesMap** + + The generic property page provider uses a list box to represent the possible values. + +- **Range** + + The generic property page provider validates that the data entered conforms to the specified range. + +- **DisplayName** + + The generic property page provider uses the value of this property qualifier as the label for the property. + +- **DisplayInHex** + + If present, the property value is displayed in hexadecimal. + +Driver writers should localize property qualifiers that are strings. See [Localizing MOF Files](localizing-mof-files.md) for details. + +### Enabling the Generic Property Page Provider + +Each device that exposes classes to be used by Wmiprop.dll must enable Wmiprop.dll as a co-installer. To do this, make the following addition to the co-installer *add-registry-section*: add a value entry for the class GUID under the **HKLM\\System\\CurrentControlSet\\Control\\CoDeviceInstallers** registry key. The value for the value entry is "WmiProp.dll, WmiPropCoInstaller". + +For example: + +``` +; This section is defined in the Co-installer section, as follows. +; [Co-installer] +; AddReg = CoInstaller_AddReg + +[CoInstaller_AddReg] +HKLM, System\CurrentControlSet\Control\CoDeviceInstallers, ClassGUID, + 0x00010000, "WmiProp.dll, WmiPropCoInstaller" +``` + +*ClassGUID* is the GUID for the WMI class. See [Registering a Class Co-installer](https://msdn.microsoft.com/library/windows/hardware/ff549801) for details. + +You must also specify the particular WMI classes to be exposed through the generic property provider. To do this, set the **WmiConfigClasses** value-entry to be a comma-separated list of the WMI classes in the *add-registry-section* of the device class or device hardware instance. + +``` +; the device class AddReg section. +[device_class_AddReg] +HKR,,"WmiConfigClasses",0x00000000,"class1,class2" + +; the device hardware instance AddReg section. +[device_hw_inst_AddReg] +HKR,,"WmiConfigClasses",0x00000000,"class3" +``` + +See [**INF AddReg Directive**](https://msdn.microsoft.com/library/windows/hardware/ff546320) for a description of an *add-registry-section* in INF files. + +Wmiprop.dll assumes only one instance of each class. Each class is represented by a tab on the property sheet. Use the **DisplayName** property qualifier to set the title text of the tab. A property page for a class only appears if there is currently an instance of the class. Therefore, if the device is removed or not started, the pages do not appear. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Generic%20Property%20Page%20Provider%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-minor-irps.md b/windows-driver-docs-pr/kernel/wmi-minor-irps.md new file mode 100644 index 0000000000..581a1b093f --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-minor-irps.md @@ -0,0 +1,61 @@ +--- +title: WMI Minor IRPs +author: windows-driver-content +description: WMI Minor IRPs +ms.author: windowsdriverdev +ms.date: 08/12/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +ms.assetid: 5788294f-2145-4381-9b06-3b138b2d26df +--- + +# WMI Minor IRPs + + +## + + +This section describes the [Windows Management Instrumentation](https://msdn.microsoft.com/library/windows/hardware/ff547139) IRPs that are part of the WMI extensions to WDM. All WMI IRPs use the major code [**IRP\_MJ\_SYSTEM\_CONTROL**](irp-mj-system-control.md) and a minor code that indicates the specific WMI request. The WMI kernel-mode component can send WMI IRPs any time following a driver's successful registration as a supplier of WMI data. WMI IRPs typically get sent when a user-mode data consumer has requested WMI data. + +All drivers must set a dispatch table entry point for a [*DispatchSystemControl*](https://msdn.microsoft.com/library/windows/hardware/ff543412) routine to handle WMI requests. + +If a driver registers as a WMI data provider by calling [**IoWMIRegistrationControl**](https://msdn.microsoft.com/library/windows/hardware/ff550480), it must handle WMI IRPs using one of the techniques described in [Handling WMI Requests](https://msdn.microsoft.com/library/windows/hardware/ff546968). + +Drivers that do not register as WMI data providers must forward all WMI requests to the next-lower driver. + +This section describes the following system-defined WMI minor function codes: + +[**IRP\_MN\_CHANGE\_SINGLE\_INSTANCE**](irp-mn-change-single-instance.md) + +[**IRP\_MN\_CHANGE\_SINGLE\_ITEM**](irp-mn-change-single-item.md) + +[**IRP\_MN\_DISABLE\_COLLECTION**](irp-mn-disable-collection.md) + +[**IRP\_MN\_DISABLE\_EVENTS**](irp-mn-disable-events.md) + +[**IRP\_MN\_ENABLE\_COLLECTION**](irp-mn-enable-collection.md) + +[**IRP\_MN\_ENABLE\_EVENTS**](irp-mn-enable-events.md) + +[**IRP\_MN\_EXECUTE\_METHOD**](irp-mn-execute-method.md) + +[**IRP\_MN\_QUERY\_ALL\_DATA**](irp-mn-query-all-data.md) + +[**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](irp-mn-query-single-instance.md) + +[**IRP\_MN\_REGINFO**](irp-mn-reginfo.md) + +[**IRP\_MN\_REGINFO\_EX**](irp-mn-reginfo-ex.md) + +If the driver receives an IRP containing any other IRP minor function code, it should forward the IRP to the next-lower driver. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Minor%20IRPs%20%20RELEASE:%20%288/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-property-qualifiers.md b/windows-driver-docs-pr/kernel/wmi-property-qualifiers.md new file mode 100644 index 0000000000..6648d7f468 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-property-qualifiers.md @@ -0,0 +1,129 @@ +--- +title: WMI Property Qualifiers +author: windows-driver-content +description: WMI Property Qualifiers +ms.assetid: e2d281b3-913c-43ad-921c-80dc8be09aa0 +keywords: ["MOF property qualifiers WDK WMI", "property qualifiers WDK WMI", "qualifiers WDK WMI", "standard MOF qualifiers WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Property Qualifiers + + +## + + +The following table lists the required and optional MOF property qualifiers that can be used to define items in a WMI data or event block. + +The following are standard MOF qualifiers: **key**, **read**, **write**, **ValueMap**, and **Values**. For more information about these and other standard MOF qualifiers, see [MOF Data Types](https://msdn.microsoft.com/library/aa392392). + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
QualifierDescription

key

Indicates that the data item is a key property that uniquely identifies each instance of the class. Only the InstanceName property can be declared a key.

read

Indicates that a WMI client can read the data item.

write

Indicates that a WMI client can set the data item.

BitMap

Specifies the bit positions of the corresponding string values that are specified in BitValues.

BitValues

Specifies a list of string values (flag names) that represent bits set in the data item. The bit position of a flag is defined by the corresponding position specified in BitMap.

DefineValues

Specifies an enumerated list that the WMI tool suite compiles into a corresponding list of #define statements.

DisplayInHex

Specifies that any WMI client that displays the property value should do so in hexadecimal.

DisplayName("string")

Specifies a caption that a WMI client can use to display as the property name.

MaxLen(uint)

For string properties, MaxLen specifies the maximum length of the string in characters. The uint value can be any 32-bit unsigned integer. If MaxLen is omitted, or uint is zero, then the length of the string is unlimited.

Values

Specifies a list of possible values for this data item. If the data item is an enumeration, ValueMap contains the index value that corresponds to the enumeration value specified in Values.

ValueMap

Specifies the integer values of the corresponding string values in Values.

WmiDataId(data-item-ID)

(Required) Identifies a data item within a data block. Data item IDs must be assigned to all items in a block except the required items InstanceName and Active. Data item IDs must be assigned in a contiguous series, starting with 1. An item's data ID determines the order in which the item appears in an instance of the data block; the order of items in the MOF class definition is irrelevant.

WmiMethodId(method-item-ID)

Identifies a method within a data block.

WmiSizeIs("data-item-name")

Specifies the name of another data item in this block that indicates the number of elements in the variable-length array at this data item. WmiSizeIs is valid only for data items that define arrays.

WmiScale(scale-factor)

Specifies the scaling factor, as a power of 10, that the driver uses when returning the value of this data item. For example, if scale-factor is 5, the value returned by the driver is multiplied by 10⁵. If WmiScale is omitted, scale-factor can be assumed to be 0.

WmiTimeStamp

Specifies that a 64-bit data item is a time stamp in units of 100 nanoseconds since 1/1/1601. WmiTimeStamp is valid only for 64-bit data items.

WmiComplexity(level)

Specifies an integer value that expresses the user complexity level of the data item. WMI clients can use that value to distinguish between data items that should be available to novice users and data items that should be restricted to more advanced users. Zero is the minimum value, and higher values indicate higher user complexity. WmiComplexity defaults to zero if not specified.

WmiVolatility(interval)

Specifies the interval, in milliseconds, between updates of this data item. For example, if a data item is updated once each second, interval would be 1000. A WMI client might check WmiVolatility to determine how often to query for a potentially new value. If WmiVolatility is omitted, interval is undefined.

WmiEventTrigger( " data-item-name")

Specifies the name of a data item in an event block that a WMI client can set to define the trigger value for the event. For example, if the event TooHot is qualified with WmiEventTrigger("TooHotTemperature"), a WMI client could set TooHotTemperature to instruct the driver to send the TooHot event when the device reached the user-specified value for TooHotTemperature. Typically a driver would define the trigger value. By exposing a WmiEventTrigger data item, the driver allows a client to control when a particular event is fired.

WmiEventRate("data-item-name")

Specifies the name of a data item in an event block that a WMI client can set to control the frequency at which this event will be sent. For example, if the data item TooHot is qualified with WmiEventRate("SendEventRate"), a WMI client user could set SendEventRate to instruct the driver to send TooHot at the user-specified interval.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Property%20Qualifiers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-property-sheets.md b/windows-driver-docs-pr/kernel/wmi-property-sheets.md new file mode 100644 index 0000000000..024a7f7bfd --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-property-sheets.md @@ -0,0 +1,34 @@ +--- +title: WMI Property Sheets +author: windows-driver-content +description: WMI Property Sheets +ms.assetid: cc521aff-362a-4064-adea-f6f3cf8a1c10 +keywords: ["WMI WDK kernel , property sheets", "property sheets WDK WMI", "device property sheets WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Property Sheets + + +## + + +A user-friendly driver allows users to control its settings through its **Device Manager** property sheet. See [Using Device Manager](https://msdn.microsoft.com/library/windows/hardware/ff553570) for a description of Device Manager. + +Drivers can automatically expose any WMI classes they implement on their property sheet by using the [WMI generic property page provider](wmi-generic-property-page-provider.md). + +Drivers can enable certain controls on the **Power Management** tab of the **Device Manager** property sheet by supporting certain particular WMI class GUIDs. See [WMI and the Power Management Tab](wmi-and-the-power-management-tab.md) for details. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Property%20Sheets%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-registration-flags.md b/windows-driver-docs-pr/kernel/wmi-registration-flags.md new file mode 100644 index 0000000000..633ac69229 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-registration-flags.md @@ -0,0 +1,56 @@ +--- +title: WMI Registration Flags +author: windows-driver-content +description: WMI Registration Flags +ms.assetid: 001d4840-0ed4-464d-8379-7bbd0afce28c +keywords: ["dynamic instance names WDK WMI", "static instance names WDK WMI", "registration flags WDK WMI", "flags WDK WMI", "WMI WDK kernel , registering with WMI", "registering WMI data providers", "data providers WDK WMI", "driver registrations WDK WMI", "event blocks WDK WMI", "blocks WDK WMI", "registering blocks"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Registration Flags + + +## + + +A driver indicates whether a block uses static or dynamic instance names and specifies other characteristics of the block by setting flags in the [**WMIGUIDREGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff565811) or [**WMIREGGUID**](https://msdn.microsoft.com/library/windows/hardware/ff565827) structure that it passes to WMI to register the block. + +A driver indicates that a block uses static instance names by setting one of the following flags: + +- WMIREG\_FLAG\_INSTANCE\_LIST indicates that the driver provides all instance names in a static list. + + A driver can set this flag only if it registers blocks by handling the [**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) requests, not by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834). The driver writes the instance name strings at the byte offset indicated by **InstanceNameList** in the block's **WMIREGGUID** structure. + +- WMIREG\_FLAG\_INSTANCE\_BASENAME instructs WMI to generate static instance names from a driver-defined base name string. + + A driver that handles an **IRP\_MN\_REGINFO** or **IRP\_MN\_REGINFO\_EX** request writes the base name string at the offset indicated by **BaseNameOffset** in the block's **WMIREGGUID** structure. + + A driver that calls **WmiSystemControl** specifies the base name string in the *InstanceName* parameter of its [**DpWmiQueryReginfo**](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +- WMIREG\_FLAG\_INSTANCE\_PDO instructs WMI to generate static instance names from the device instance ID of the driver's PDO. + + A driver that handles an **IRP\_MN\_REGINFO** or **IRP\_MN\_REGINFO\_EX** request writes a pointer to the PDO at the **Pdo** member of the block's **WMIREGGUID** structure. If the request is **IRP\_MN\_REGINFO\_EX**, the driver must increase the reference count on each PDO passed by calling the [**ObReferenceObject**](https://msdn.microsoft.com/library/windows/hardware/ff558678) routine. (The system will dereference each PDO later.) + + A driver that calls **WmiSystemControl** writes a pointer to the PDO in the *Pdo* parameter of its [*DpWmiQueryReginfo*](https://msdn.microsoft.com/library/windows/hardware/ff544097) routine. + +To indicate that a block uses dynamic instance names, the driver must not set any of the following flags: WMIREG\_FLAG\_INSTANCE\_LIST, WMIREG\_FLAG\_INSTANCE\_PDO, or WMIREG\_FLAG\_INSTANCE\_BASENAME. + +A driver indicates that a data block is expensive to collect by setting WMIREG\_FLAG\_EXPENSIVE. This instructs WMI to send an [**IRP\_MN\_ENABLE\_COLLECTION**](https://msdn.microsoft.com/library/windows/hardware/ff550857) request the first time a WMI client opens the data block and an [**IRP\_MN\_DISABLE\_COLLECTION**](https://msdn.microsoft.com/library/windows/hardware/ff550848) request when the last WMI client closes the block. The driver need not collect data for such a block until it receives an **IRP\_MN\_ENABLE\_COLLECTION** request. + +A driver indicates an event block by setting WMIREG\_FLAG\_EVENT\_ONLY\_GUID. This indicates that the block can be enabled or disabled as an event only, and cannot be queried or set. + +A driver instructs WMI to remove a previously registered block by setting WMIREG\_FLAG\_REMOVE\_GUID. This flag is valid only in response to a request to update registration information ([**IRP\_MN\_REGINFO**](https://msdn.microsoft.com/library/windows/hardware/ff551731) or [**IRP\_MN\_REGINFO\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff551734) with WMIUPDATE). For more information, see [Updating WMI Registration Information](updating-wmi-registration-information.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Registration%20Flags%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-requirements-for-wdm-drivers.md b/windows-driver-docs-pr/kernel/wmi-requirements-for-wdm-drivers.md new file mode 100644 index 0000000000..56bab3cd05 --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-requirements-for-wdm-drivers.md @@ -0,0 +1,38 @@ +--- +title: WMI Requirements for WDM Drivers +author: windows-driver-content +description: WMI Requirements for WDM Drivers +ms.assetid: 8290e570-acd9-4047-bd0b-c1c74847f243 +keywords: ["WMI WDK kernel , WDM drivers", "WDM drivers WDK WMI", "IRPs WDK WMI", "requests WDK WMI", "WMI WDK kernel , requests", "data providers WDK WMI"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI Requirements for WDM Drivers + + +## + + +A driver that handles IRPs registers with WMI as a *data provider*. System-supplied storage port drivers, class drivers, and NDIS protocol drivers fall into this category. For information about registering as a WMI data provider, see [Registering as a WMI Data Provider](registering-as-a-wmi-data-provider.md). + +A driver that does not handle IRPs should simply forward WMI requests to the next-lower driver in the driver stack. The next-lower driver then registers with WMI and handles WMI requests on the first driver's behalf. For instance, SCSI miniport drivers and NDIS miniport drivers can register as WMI providers and supply WMI data to their corresponding class drivers. + +A driver that supplies WMI data to a class or port driver must support the driver-type-specific WMI interfaces that are defined by the class or port driver. For example, a SCSI miniport driver must set **WmiDataProvider** to **TRUE** in the [**PORT\_CONFIGURATION\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff563900) structure and handle SRB\_FUNCTION\_WMI requests from the SCSI port driver. + +Similarly, a connection-oriented NDIS miniport driver that defines custom data blocks must support [OID\_GEN\_CO\_SUPPORTED\_GUIDS](https://msdn.microsoft.com/library/windows/hardware/ff569566); otherwise, NDIS maps those OIDs and status indications returned from OID\_GEN\_SUPPORTED\_LIST that are common and known to NDIS to GUIDs defined by NDIS. + +The following sections describe how to support WMI in a driver that handles IRPs. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20Requirements%20for%20WDM%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/wmi-wnode-xxx-structures.md b/windows-driver-docs-pr/kernel/wmi-wnode-xxx-structures.md new file mode 100644 index 0000000000..00d0bb175f --- /dev/null +++ b/windows-driver-docs-pr/kernel/wmi-wnode-xxx-structures.md @@ -0,0 +1,124 @@ +--- +title: WMI WNODE_XXX Structures +author: windows-driver-content +description: WMI WNODE_XXX Structures +ms.assetid: 9d059b9a-c129-42ba-8db6-53480003f56e +keywords: ["WMI WDK kernel , requests", "requests WDK WMI", "IRPs WDK WMI", "WNODE_XXX structures"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WMI WNODE\_XXX Structures + + +## + + +WMI uses a set of standard data structures called **WNODE\_*XXX*** to pass data between user-mode data consumers and kernel-mode data providers such as drivers. If a driver handles WMI requests by calling [**WmiSystemControl**](https://msdn.microsoft.com/library/windows/hardware/ff565834), the driver is not required to read or write **WNODE\_*XXX*** structures. Otherwise, the driver must interpret the input **WNODE\_*XXX*** at **Parameters.WMI.Buffer** and/or write an output **WNODE\_*XXX*** to that location. + +The following table lists WMI IRPs and their corresponding **WNODE\_*XXX*** structures. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WMI IRPRelated WNODE_XXX Structure

[IRP_MN_CHANGE_SINGLE_INSTANCE](https://msdn.microsoft.com/library/windows/hardware/ff550831)

[WNODE_SINGLE_INSTANCE](https://msdn.microsoft.com/library/windows/hardware/ff566377)

[IRP_MN_CHANGE_SINGLE_ITEM](https://msdn.microsoft.com/library/windows/hardware/ff550836)

[WNODE_SINGLE_ITEM](https://msdn.microsoft.com/library/windows/hardware/ff566378)

[IRP_MN_EXECUTE_METHOD](https://msdn.microsoft.com/library/windows/hardware/ff550868)

[WNODE_METHOD_ITEM](https://msdn.microsoft.com/library/windows/hardware/ff566376)

[IRP_MN_QUERY_ALL_DATA](https://msdn.microsoft.com/library/windows/hardware/ff551650)

[WNODE_ALL_DATA](https://msdn.microsoft.com/library/windows/hardware/ff566372)

[IRP_MN_QUERY_SINGLE_INSTANCE](https://msdn.microsoft.com/library/windows/hardware/ff551718)

[WNODE_SINGLE_INSTANCE](https://msdn.microsoft.com/library/windows/hardware/ff566377)

+ +  + +Two additional **WNODE\_*XXX*** structures, [**WNODE\_EVENT\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566373) and [**WNODE\_EVENT\_REFERENCE**](https://msdn.microsoft.com/library/windows/hardware/ff566374), are used to send notifications of enabled events. A driver that registers event blocks will, if an event is enabled and the event occurs, send notification of the event to WMI by calling [**IoWMIWriteEvent**](https://msdn.microsoft.com/library/windows/hardware/ff550520) and passing a **WNODE\_EVENT\_*XXX*** structure. For information about sending WMI events, see [Sending WMI Events](sending-wmi-events.md). + +Each **WNODE\_*XXX*** structure consists of the following: + +- An embedded [**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) structure that contains information common to all **WNODE\_*XXX*** including the size of the buffer, the GUID that represents the data block, and flags that indicate the type of **WNODE\_*XXX*** structure, whether it uses static or dynamic instance names, and other characteristics of the block. + +- The fixed members of the particular **WNODE\_*XXX*** structure, such as offsets to instance names and data. + +A **WNODE\_*XXX*** structure in an IRP buffer (**Parameters.WMI.Buffer**) is typically followed by variable data related to the request, such as dynamic instance names, static instance name strings, input for or output from a method, or data for one or more instances of a data block. The size of the buffer must therefore exceed **sizeof(WNODE\_*XXX*)** by the amount of variable data involved. + +Note that WMI does not perform type-checking on variable data supplied by a driver. The driver must align output data on an appropriate boundary in the output buffer so that a data consumer can parse the data correctly. In particular, each instance must start on an 8-byte boundary and each of its items must be aligned on a natural boundary according to the data block schema previously registered by the driver. Dynamic instance names can be aligned on a 2-byte boundary. + +The following figure shows a block diagram of an IRP buffer containing a [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) structure that a driver might return in response to an [**IRP\_MN\_QUERY\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff551718) request. + +![diagram illustrating an irp buffer containing a wnode\-single\-instance](images/wnode-single-instance.png) + +Starting at the top of the previous figure: + +- The [**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) structure at the beginning of the [**WNODE\_SINGLE\_INSTANCE**](https://msdn.microsoft.com/library/windows/hardware/ff566377) is contained in a **WnodeHeader** member. WMI fills in all members of the **WNODE\_HEADER** before sending the request. In the **WNODE\_HEADER**: + + - **WnodeHeader.Buffersize** indicates the size of the **WNODE\_SINGLE\_INSTANCE**, including data that follows the fixed members of the structure. (The value of **WnodeHeader.Buffersize** is typically less than **Parameters.WMI.Buffersize**, which indicates the size of the buffer allocated by WMI to receive output from the driver.) + - **WnodeHeader.Guid** contains the GUID that identifies the data block. + - In this example, **WnodeHeader.Flags** indicates that this structure is a **WNODE\_SINGLE\_INSTANCE** and that the data block uses static instance names. +- Because the data block uses static instance names, WMI sets **InstanceIndex** to the index of the instance in the list of static instance names passed by the driver when it registered the block. **OffsetInstanceNames** is not used. + +- WMI sets **DataBlockOffset** to indicate the offset from the beginning of the buffer to the first byte of instance data. (The driver must not change this value) Again because the data block uses static instance names, this offset indicates the same location as **VariableData**. If the data block used dynamic instance names, the instance names would start at **VariableData** and **DataBlockOffset** would specify a greater offset into the buffer. + +- The driver sets **SizeDataBlock** to the number of bytes of instance data being returned. + +- At **VariableData** (after instance name data, if present), the driver writes instance data for the requested instance in the output buffer. + +A driver reads and writes [**WNODE\_METHOD\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566376) and [**WNODE\_SINGLE\_ITEM**](https://msdn.microsoft.com/library/windows/hardware/ff566378) structures in much the same way as **WNODE\_SINGLE\_INSTANCE**. These structures resemble each other in that each has the fixed members **OffsetInstanceName**, **InstanceIndex**, **DataBlockOffset**, **SizeDataBlock** (or, in the case of **WNODE\_SINGLE\_ITEM**, **SizeDataItem**) and **VariableData**. **WNODE\_METHOD\_ITEM** includes a **MethodId** and **WNODE\_SINGLE\_ITEM** includes an **ItemId** which **WNODE\_SINGLE\_INSTANCE** lacks. + +[**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) differs from the preceding structures in that it is used to pass multiple instances of a data block, possibly including dynamic instance names and possibly of different sizes. + +The following figure shows a block diagram of an IRP buffer containing a **WNODE\_ALL\_DATA** that a driver might return in response to an [**IRP\_MN\_QUERY\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff551650) request. + +![diagram illustrating an irp buffer containing a wnode\-all\-data](images/wnode-all-data.png) + +Starting at the top of the previous figure: + +- As described in the previous figure, the [**WNODE\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566375) structure at the beginning of the [**WNODE\_ALL\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff566372) is contained in a **WnodeHeader** member. **WnodeHeader.Buffersize** and **WnodeHeader.Guid** indicate the size of the **WNODE\_ALL\_DATA** and the GUID of the data block, respectively. + + In this example, WMI sets **WnodeHeader.Flags** to indicate that this structure is a **WNODE\_ALL\_DATA** and that the data block was registered with dynamic instance names (that is, WMI clears WNODE\_FLAG\_STATIC\_INSTANCE\_NAMES and WNODE\_FLAG\_PDO\_INSTANCE\_NAMES). On output, the driver sets WNODE\_FLAG\_FIXED\_INSTANCE\_SIZE to indicate that all of the instances are the same size. + +- WMI sets **DataBlockOffset** to indicate the offset from the beginning of the buffer to the first byte of instance data. (The driver must not change this value). In this example, instance data follows the instance names at **OffsetInstanceNameOffsets**. + +- The driver sets **InstanceCount** to indicate the number of instances being returned. + +- **WNODE\_*XXX*** for data blocks that use dynamic instance names always contain the instance name strings. Because this example uses dynamic instance names, **OffsetInstanceNameOffsets** indicates the offset from the beginning of the buffer to an array of offsets to dynamic instance names in the buffer. + +- **FixedInstanceSize** indicates the number of bytes of data in each instance being returned by the driver. If instances of this data block were to vary in size, the driver would clear WNODE\_FLAG\_FIXED\_INSTANCE\_SIZE in **WnodeHeader.Flags** and set **OffsetInstanceDataAndLength** to an array of **OFFSETINSTANCEDATAANDLENGTH** structures, each specifying an offset to the data for one instance and the number of bytes in that instance instead of setting **FixedInstanceSize**. + +For more information about **WNODE\_*XXX*** structures, see [System Structures](https://msdn.microsoft.com/library/windows/hardware/ff564540). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20WMI%20WNODE_XXX%20Structures%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-a-bug-check-callback-routine.md b/windows-driver-docs-pr/kernel/writing-a-bug-check-callback-routine.md new file mode 100644 index 0000000000..4656575ba2 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-a-bug-check-callback-routine.md @@ -0,0 +1,58 @@ +--- +title: Writing a Bug Check Callback Routine +author: windows-driver-content +description: Writing a Bug Check Callback Routine +ms.assetid: 62aefe67-e197-4c45-b994-19bd7369dbc1 +keywords: ["bug check callback routines WDK kernel", "callback routines WDK bug checks", "registering callback routines", "KeRegisterBugCheckCallback", "BugCheckCallback"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing a Bug Check Callback Routine + + +## + + +Drivers can register callback routines that the system executes when it issues a bug check. + +On all NT-based operating systems, drivers can use the [**KeRegisterBugCheckCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553105) routine to register a [*BugCheckCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540674) routine, and [**KeDeregisterBugCheckCallback**](https://msdn.microsoft.com/library/windows/hardware/ff551992) to remove the routine. Drivers can use a *BugCheckCallback* routine to reset their device to a known state. + +Prior to Windows XP Service Pack 1 (SP1) and Windows Server 2003, drivers could also use *BugCheckCallback* to store data in the crash dump file: the system called each *BugCheckCallback* routine before writing the crash dump file, so any data written to the buffer that was passed to *BugCheckCallback* was stored in the crash dump file. + +In Windows XP SP1 and Windows Server 2003 and later, the system calls *BugCheckCallback*after the crash dump file is written. Instead, the system supports two additional types of bug check callback routines. A [*BugCheckSecondaryDumpDataCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540679) routine can be used to write secondary data to the crash dump file. A [*BugCheckDumpIoCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540677) routine can be used to copy the crash dump file to a device. + +In Windows Server 2008 and later versions of Windows, a driver can implement a [*BugCheckAddPagesCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540669) routine to add pages of driver-specific data to the crash dump file. Unlike a *BugCheckSecondaryDumpDataCallback* routine, which appends data to the secondary crash dump region, a *BugCheckAddPagesCallback* routine adds pages of data to the crash dump region. During debugging, crash dump data is easier to access than secondary crash dump data. + +Drivers use the [**KeRegisterBugCheckReasonCallback**](https://msdn.microsoft.com/library/windows/hardware/ff553110) and [**KeDeregisterBugCheckReasonCallback**](https://msdn.microsoft.com/library/windows/hardware/ff552003) routines to register these three types of *BugCheckXxxCallback* callback routines. + +A bug check callback routine executes at IRQL = HIGH\_LEVEL, which imposes strong restrictions on what it can do. + +A bug check callback routine cannot: + +- Allocate memory + +- Access pageable memory + +- Use any synchronization mechanisms + +- Call any routine that must execute at IRQL = DISPATCH\_LEVEL or below + +Bug check callback routines are guaranteed to run without interruption, so no synchronization is required. (If the bug check routine does use any synchronization mechanisms, the system will deadlock.) + +A driver's bug check callback routine can safely use the **READ\_PORT\_*XXX***, **READ\_REGISTER\_*XXX***, **WRITE\_PORT\_*XXX***, and **WRITE\_REGISTER\_*XXX*** routines to communicate with the driver's device. (For information about these routines, see [Hardware Abstraction Layer Routines](https://msdn.microsoft.com/library/windows/hardware/ff546644).) + +For more information about bug check callbacks, see [*BugCheckCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540674), [*BugCheckAddPagesCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540669), [*BugCheckDumpIoCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540677), [*BugCheckSecondaryDumpDataCallback*](https://msdn.microsoft.com/library/windows/hardware/ff540679), and [Reading Bug Check Callback Data](https://msdn.microsoft.com/library/windows/hardware/ff553558). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20a%20Bug%20Check%20Callback%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-a-driverentry-routine.md b/windows-driver-docs-pr/kernel/writing-a-driverentry-routine.md new file mode 100644 index 0000000000..e104bbd6c0 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-a-driverentry-routine.md @@ -0,0 +1,44 @@ +--- +title: Writing a DriverEntry Routine +author: windows-driver-content +description: Writing a DriverEntry Routine +ms.assetid: c33bc82b-6181-4e31-b272-aaadb2d9b058 +keywords: ["standard driver routines WDK kernel , DriverEntry routine", "driver routines WDK kernel , DriverEntry routine", "routines WDK kernel , DriverEntry routine", "DriverEntry WDK kernel", "DriverEntry WDK kernel , about DriverEntry routine", "driver initialization WDK kernel", "initializing drivers"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing a DriverEntry Routine + + +## + + +Each driver must have a [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine, which initializes driver-wide data structures and resources. The I/O manager calls the **DriverEntry** routine when it loads the driver. + +In a driver that supports Plug and Play (PnP), as all drivers should, the **DriverEntry** routine is responsible for *driver* initialization, while the [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine (and, possibly, the dispatch routine that handles a PnP [**IRP\_MN\_START\_DEVICE**](https://msdn.microsoft.com/library/windows/hardware/ff551749) request) is responsible for *device* initialization. Driver initialization includes exporting the driver's other entry points, initializing certain objects the driver uses, and setting up various per-driver system resources. (Non-PnP drivers have significantly different requirements, as described in the Driver Development Kit \[DDK\] for Microsoft Windows NT 4.0 and earlier.) + +**DriverEntry** routines are called in the context of a system thread at IRQL = PASSIVE\_LEVEL. + +A **DriverEntry** routine can be pageable and should be in an INIT segment so it will be discarded. Use an **alloc\_text** pragma directive, as illustrated in the sample drivers that are provided with the Windows Driver Kit (WDK). + +This section contains the following topics: + +[DriverEntry's Required Responsibilities](driverentry-s-required-responsibilities.md) + +[DriverEntry's Optional Responsibilities](driverentry-s-optional-responsibilities.md) + +[DriverEntry Return Values](driverentry-return-values.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20a%20DriverEntry%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-a-reinitialize-routine.md b/windows-driver-docs-pr/kernel/writing-a-reinitialize-routine.md new file mode 100644 index 0000000000..c013b828e5 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-a-reinitialize-routine.md @@ -0,0 +1,42 @@ +--- +title: Writing a Reinitialize Routine +author: windows-driver-content +description: Writing a Reinitialize Routine +ms.assetid: 47a7dd3f-e474-49c7-adf2-11f6e788c261 +keywords: ["standard driver routines WDK kernel , Reinitialize routine", "driver routines WDK kernel , Reinitialize routine", "routines WDK kernel , Reinitialize routine", "Reinitialize", "reinitializing drivers WDK", "driver reinitialization WDK kernel", "driver initialization WDK kernel", "initializing drivers WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing a Reinitialize Routine + + +## + + +Any driver that needs to initialize itself in stages can contain a [*Reinitialize*](https://msdn.microsoft.com/library/windows/hardware/ff561022) routine. A *Reinitialize* routine is called after the [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine has returned control and other drivers have initialized themselves. Typically, the *Reinitialize* routine performs tasks that must be done after another driver starts. + +For example, the system's keyboard class driver, **kbdclass**, supports both PnP and legacy keyboard ports. If a system includes one or more legacy ports that the PnP manager cannot detect, the keyboard class driver must nevertheless create a device object for each port and layer itself over lower-level drivers for the port. Consequently, the class driver has a *Reinitialize* routine to be called after its **DriverEntry** and [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routines have been called and other drivers have been loaded. The *Reinitialize* routine detects the port, creates a device object for it, and layers the driver over other lower-level drivers for the device. + +A driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine calls [**IoRegisterDriverReinitialization**](https://msdn.microsoft.com/library/windows/hardware/ff549511) to queue a *Reinitialize* routine for execution. The *Reinitialize* routine can also call **IoRegisterDriverReinitialization** itself, which causes the routine to be requeued. One of the parameters to *Reinitialize* indicates the number of times it has been called. + +The call to **IoRegisterDriverReinitialization** can include a pointer to driver-defined context data, which the system supplies as input to *Reinitialize*. If the *Reinitialize* routine uses the registry, the context data should include the *RegistryPath* pointer that was passed to the **DriverEntry** routine because this pointer is not an input parameter to the *Reinitialize* routine. + +The *Reinitialize* routine will not be called if **DriverEntry** does not return STATUS\_SUCCESS. + +Usually, a driver with a *Reinitialize* routine is a higher-level driver that controls both PnP and legacy devices. In addition to creating device objects for the devices that the PnP manager detects (and for which the PnP manager calls the driver's *AddDevice* routine), the driver must also create device objects for legacy devices that the PnP manager does not enumerate. The *Reinitialize* routine creates those device objects and layers the driver over the next-lower driver for the underlying device. + +If a driver has a *Reinitialize* routine, it initializes in the same basic steps described in [Writing a DriverEntry Routine](writing-a-driverentry-routine.md), and it also has the same basic requirements as its **DriverEntry** routine. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20a%20Reinitialize%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-a-startio-routine.md b/windows-driver-docs-pr/kernel/writing-a-startio-routine.md new file mode 100644 index 0000000000..84bb97dc88 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-a-startio-routine.md @@ -0,0 +1,44 @@ +--- +title: Writing a StartIo Routine +author: windows-driver-content +description: Writing a StartIo Routine +ms.assetid: b2a380ae-549c-4ca2-9c69-1e20c17ed2e6 +keywords: ["StartIo routines, about StartIo routines", "StartIo routines, writing", "starting I/O operations", "I/O operation starting WDK kernel", "IRPs WDK kernel , queuing", "queuing IRPs", "dequeuing IRPs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing a StartIo Routine + + +## + + +As its name suggests, a [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine is responsible for starting an I/O operation on the physical device. + +Most lowest-level drivers provide a *StartIo* routine and rely on the I/O manager to queue IRPs to a system-supplied device queue. Some lowest-level drivers are designed to set up and manage their own supplemental IRP queues, but even these usually also provide a *StartIo* routine. (For more information about supplemental queues, see [Setting up and Using Device Queues](setting-up-and-using-device-queues.md) and [Managing Device Queues](managing-device-queues.md).) + +Higher-level drivers, including FSDs and PnP function and filter drivers, seldom have a *StartIo* routine because it can hamper performance. Instead, most file system drivers set up and maintain internal queues of IRPs. Other higher-level drivers either have internal queues for IRPs or simply pass IRPs on to lower drivers from their dispatch routines. See [Driver-Managed IRP Queues](driver-managed-irp-queues.md) for more information. + +You can use the [**IoSetStartIoAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff550330) routine to set attributes that modify *StartIo* handling for your driver. + +This section contains the following topics: + +[StartIo Routines in Lowest-Level Drivers](startio-routines-in-lowest-level-drivers.md) + +[StartIo Routines in Higher-Level Drivers](startio-routines-in-higher-level-drivers.md) + +[Points to Consider for StartIo Routines](points-to-consider-for-startio-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20a%20StartIo%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-adaptercontrol-routines.md b/windows-driver-docs-pr/kernel/writing-adaptercontrol-routines.md new file mode 100644 index 0000000000..d38f74a1ff --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-adaptercontrol-routines.md @@ -0,0 +1,34 @@ +--- +title: Writing AdapterControl Routines +author: windows-driver-content +description: Writing AdapterControl Routines +ms.assetid: a5a7501f-ba4f-441e-be07-6a1b7fac9938 +keywords: ["AdapterControl routines, writing", "adapter objects WDK kernel , writing AdapterControl routines", "DMA transfers WDK kernel , writing AdapterControl routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing AdapterControl Routines + + +## + + +Most drivers of DMA devices have an [*AdapterControl*](https://msdn.microsoft.com/library/windows/hardware/ff540504) routine, which is responsible for initiating DMA operations. (Drivers that do not require *AdapterControl* routines include those that [use scatter/gather DMA](using-scatter-gather-dma.md) and those that [use common-buffer, bus-master DMA](using-common-buffer-bus-master-dma.md).) + +When a driver calls [**AllocateAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff540573), its *AdapterControl* routine is run immediately if the system DMA controller or bus-master adapter is available for a DMA operation, and if enough map registers are available. Otherwise, the *AdapterControl* routine is queued until these resources are available. + +If the driver's *AdapterControl* routine returns **KeepObject** or **DeallocateObjectKeepRegisters** (thereby retaining the system DMA controller channel or bus-master adapter for additional transfer operations), the driver's [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routine is responsible for releasing the adapter object or map registers by calling [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) or [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) before the DPC routine completes the current IRP and returns control. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20AdapterControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-an-adddevice-routine.md b/windows-driver-docs-pr/kernel/writing-an-adddevice-routine.md new file mode 100644 index 0000000000..d11abb659e --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-an-adddevice-routine.md @@ -0,0 +1,40 @@ +--- +title: Writing an AddDevice Routine +author: windows-driver-content +description: Writing an AddDevice Routine +ms.assetid: 93a272f4-888c-4cc8-b013-c6313c10a8d8 +keywords: ["standard driver routines WDK kernel , AddDevice routines", "driver routines WDK kernel , AddDevice routines", "routines WDK kernel , AddDevice routines", "AddDevice routines WDK kernel", "system-space memory allocations WDK kernel", "system resource storage WDK kernel", "storing system resources", "device objects WDK kernel , creating", "device initialization WDK kernel", "initializing devices", "AddDevice routines WDK kernel , about AddDevice routines"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing an AddDevice Routine + + +## + + +Any driver that supports PnP must have an [*AddDevice*](https://msdn.microsoft.com/library/windows/hardware/ff540521) routine. The *AddDevice* routine creates one or more device objects representing the physical, logical, or virtual devices for which the driver carries out I/O requests. It also attaches the device object to the device stack, so the device stack will contain a device object for each driver associated with the device. + +The PnP manager calls a driver's *AddDevice* routine for each device controlled by the driver. *AddDevice* routines are called during system initialization (when devices are first enumerated), and any time a new device is enumerated while the system is running. + +This section contains the following topics: + +[AddDevice Routines in Function or Filter Drivers](adddevice-routines-in-function-or-filter-drivers.md) + +[AddDevice Routines in Bus Drivers](adddevice-routines-in-bus-drivers.md) + +[Guidelines for Writing AddDevice Routines](guidelines-for-writing-adddevice-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20an%20AddDevice%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-an-isr.md b/windows-driver-docs-pr/kernel/writing-an-isr.md new file mode 100644 index 0000000000..95294cd921 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-an-isr.md @@ -0,0 +1,68 @@ +--- +title: Writing an ISR +author: windows-driver-content +description: Writing an ISR +ms.assetid: d696d683-e010-4a5c-ba2d-f536ab5f38b2 +keywords: ["interrupt service routines WDK kernel , writing", "ISRs WDK kernel , writing", "writing ISRs", "interrupt objects WDK kernel , writing ISRs", "I/O WDK kernel , interrupts"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing an ISR + + +## + + +Drivers for physical devices that generate interrupts must have at least one interrupt service routine (ISR). The ISR must do whatever is appropriate to the device to dismiss the interrupt, possibly including stopping the device from interrupting. Then, it should do only what is necessary to save state and queue a DPC to finish the I/O operation at a lower priority (IRQL) than that at which the ISR executes. + +A driver's ISR executes in an interrupt context, at some system-assigned [*DIRQL*](https://msdn.microsoft.com/library/windows/hardware/ff556277#wdkgloss-device-interrupt-request-level--dirql-), as specified by the *SynchronizeIrql* parameter to [**IoConnectInterruptEx**](https://msdn.microsoft.com/library/windows/hardware/ff548378). + +ISRs are interruptible. Another device with a higher system-assigned DIRQL can interrupt, or a high-IRQL system interrupt can occur, at any time. + +Before the system calls an ISR, it acquires the interrupt's spin lock so the ISR cannot simultaneously execute on another processor. After the ISR returns, the system releases the spin lock. + +Because an ISR runs at a relatively high IRQL, which masks off interrupts with an equivalent or lower IRQL on the current processor, it should return control as quickly as possible. Additionally, running an ISR at DIRQL restricts the set of support routines the ISR can call. For more information, see [Managing Hardware Priorities](managing-hardware-priorities.md). + +Typically, an ISR performs the following general steps: + +- If the device that caused the interrupt is not one supported by the ISR, the ISR immediately returns **FALSE**. + +- Otherwise, the ISR clears the interrupt if necessary, saving whatever device context is necessary, and queues a DPC to complete the I/O operation at a lower IRQL. See [DPC Objects and DPCs](dpc-objects-and-dpcs.md) for more information. The ISR must then return **TRUE**. + +Specifically, in drivers that do not overlap device I/O operations, the ISR should do the following: + +1. Determine whether the interrupt is spurious. If so, return **FALSE** immediately so the ISR of the device that interrupted will be called promptly. Otherwise, continue interrupt processing. + +2. Stop the device from interrupting, if necessary. + +3. Gather whatever context information the [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) (or [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972)) routine will need to complete I/O processing for the current operation. + +4. Store this context in an area accessible to the *DpcForIsr* or *CustomDpc* routine, usually in the device extension of the target device object for which processing the current I/O request caused the interrupt. + + If a driver overlaps I/O operations, the context information must include a count of outstanding requests the DPC routine is required to complete, along with whatever context the DPC routine needs to complete each request. If the ISR is called to handle another interrupt before the DPC has run, it must not overwrite the saved context for a request that has not yet been completed by the DPC. + +5. If the driver has a *DpcForIsr* routine, call [**IoRequestDpc**](https://msdn.microsoft.com/library/windows/hardware/ff549657) with pointers to the current IRP, the target device object, and the saved context. **IoRequestDpc** queues the *DpcForIsr* routine to be run as soon as IRQL falls below DISPATCH\_LEVEL on a processor. + + If the driver has a *CustomDpc* routine, call [**KeInsertQueueDpc**](https://msdn.microsoft.com/library/windows/hardware/ff552185) with a pointer to the DPC object (associated with the *CustomDpc* routine) and pointer(s) to any saved context the *CustomDpc* routine will need to complete the operation. Usually, the ISR also passes pointers to the current IRP and the target device object. The *CustomDpc* routine is run as soon as IRQL falls below DISPATCH\_LEVEL on a processor. + +6. Return **TRUE** to indicate that its device generated the interrupt. + +In general, an ISR does no actual I/O processing to satisfy an IRP. Instead, it stops its device from interrupting, sets up necessary state information, and queues the driver's *DpcForIsr* or *CustomDpc* to do whatever I/O processing is necessary to satisfy the current request that caused the device to interrupt. + +An ISR must run at DIRQL for the shortest possible interval. Following this guideline increases I/O throughput for every device in the machine because running at DIRQL masks off all interrupts to which the system has assigned a lesser or equal IRQL value. + +The *SynchronizeIrql* of the driver's interrupt objects, specified when the driver called **IoConnectInterrupt**, determines the DIRQL at which the driver's ISR executes. For more information, see [Synchronizing Access to Device Data](synchronizing-access-to-device-data.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20an%20ISR%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-an-unload-routine.md b/windows-driver-docs-pr/kernel/writing-an-unload-routine.md new file mode 100644 index 0000000000..772950ef0c --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-an-unload-routine.md @@ -0,0 +1,38 @@ +--- +title: Writing an Unload Routine +author: windows-driver-content +description: Writing an Unload Routine +ms.assetid: 578f3499-28fc-412b-bbb7-75f8023fa7c1 +keywords: ["standard driver routines WDK kernel , Unload routines", "driver routines WDK kernel , Unload routines", "routines WDK kernel , Unload routines", "Unload routines WDK kernel", "Unload routines WDK kernel , about Unload routines", "replacing drivers", "driver replacements WDK kernel", "unloading drivers", "reloading drivers WDK kernel", "driver unloading WDK kernel", "driver reloading WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing an Unload Routine + + +## + + +Any driver that can be replaced, or unloaded and reloaded, while the system is running must have an [*Unload*](https://msdn.microsoft.com/library/windows/hardware/ff564886) routine. All WDM drivers must have *Unload* routines. + +Although *Unload* routines are optional for non-WDM drivers, [Driver Verifier](https://msdn.microsoft.com/library/windows/hardware/ff545448) will fail any driver that does not provide an *Unload* routine. + +This section contains the following topics: + +[Unload Routine Environment](unload-routine-environment.md) + +[Unload Routine Functionality](unload-routine-functionality.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20an%20Unload%20Routine%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-controllercontrolroutines.md b/windows-driver-docs-pr/kernel/writing-controllercontrolroutines.md new file mode 100644 index 0000000000..d54aa495ae --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-controllercontrolroutines.md @@ -0,0 +1,38 @@ +--- +title: Writing ControllerControl Routines +author: windows-driver-content +description: Writing ControllerControl Routines +ms.assetid: 9330e0ff-c4bb-4aa6-985e-ef89791f74df +keywords: ["controller objects WDK kernel , writing ControllerControl routines", "ControllerControl routines, writing"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing ControllerControl Routines + + +## + + +Drivers that use a controller object must supply a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine to initiate I/O operations. + +A lowest-level device driver that must synchronize operations through a physical controller, such as an "AT" disk controller, to similar devices can have a *ControllerControl* routine. + +When a driver calls [**IoAllocateController**](https://msdn.microsoft.com/library/windows/hardware/ff548224), its *ControllerControl* routine is run immediately if the hardware represented by the controller object is available for an I/O operation. Otherwise, the *ControllerControl* routine is queued until the controller is free. + +**Note**  WDM drivers cannot use controller objects and *ControllerControl* routines. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20ControllerControl%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-data-records-to-a-clfs-stream.md b/windows-driver-docs-pr/kernel/writing-data-records-to-a-clfs-stream.md new file mode 100644 index 0000000000..af69eb37ae --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-data-records-to-a-clfs-stream.md @@ -0,0 +1,282 @@ +--- +title: Writing Data Records to a CLFS Stream +author: windows-driver-content +description: Writing Data Records to a CLFS Stream +ms.assetid: 22bd6d39-b777-4a62-85b1-3d03a7144f7a +keywords: ["Common Log File System WDK kernel , data records", "CLFS WDK kernel , data records", "data records WDK CLFS", "reserved space WDK CLFS", "aligned entries WDK CLFS", "writing data records", "buffers WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing Data Records to a CLFS Stream + + +## + + +There are two types of records in a Common Log File System (CLFS) stream: data records and restart records. This topic explains how to write data records to a stream. For information about how to write restart records, see [Writing Restart Records to a CLFS Stream](writing-restart-records-to-a-clfs-stream.md). + +Before you can write data records to a CLFS stream, you must create a marshalling area by calling [**ClfsCreateMarshallingArea**](https://msdn.microsoft.com/library/windows/hardware/ff541520). Then you can append records to the marshalling area (which is in volatile memory), and CLFS will periodically flush the records to stable storage. + +There are several variations on writing data records to a stream. For example, you can reserve space ahead of time and then write several records, or you can write records without reserving space. You can request that records you write to the marshalling area be immediately queued to stable storage, or you can let CLFS queue the records according to its policy. + +For all variations on writing data records, complete the following steps. + +1. Create an array of one or more [**CLFS\_WRITE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff541891) structures. Each write entry structure points to a buffer that you have filled with record data. + +2. Call [**ClfsReserveAndAppendLog**](https://msdn.microsoft.com/library/windows/hardware/ff541723) or [**ClfsReserveAndAppendLogAligned**](https://msdn.microsoft.com/library/windows/hardware/ff541726). + +The tables in the following subsections show how to set the parameters of **ClfsReserveAndAppendLog** for several variations on writing a record to a stream. + +### Writing a single data buffer to a stream + +Suppose you have a single data buffer that you want to write to a marshalling area. You are willing to let the record be flushed to stable storage according to CLFS policy, and you do not want the record to be part of any chain of records. The following table shows how to set the parameters when you call **ClfsReserveAndAppendLog**. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to a [CLFS_WRITE_ENTRY](https://msdn.microsoft.com/library/windows/hardware/ff541891) structure.

cWriteEntries

1

plsnUndoNext

CLFS_LSN_INVALID

plsnPrevious

CLFS_LSN_INVALID

cReserveRecords

0

rgcbReservation

NULL

fFlags

0

plsn

A pointer to a [CLFS_LSN](https://msdn.microsoft.com/library/windows/hardware/ff541824) structure. (This is an output parameter that receives the LSN of the record that is written.)

+ +  + +### Reserving space for a set of CLFS log records + +You can use **ClfsReserveAndAppendLog** to reserve space in a marshalling area for a set of log records without actually writing any of the records. The following table shows how to set the parameters to reserve record space. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

NULL

cWriteEntries

0

plsnUndoNext

CLFS_LSN_INVALID

plsnPrevious

CLFS_LSN_INVALID

cReserveRecords

The number of elements in the array pointed to by rgcbReservation.

rgcbReservation

A pointer to an array of LONGLONG-typed variables. Each element in the array is the size, in bytes, of a record for which space will be reserved. Note that this is this size of the data portion of the record; you do not have to include the size of headers or padding.

fFlags

0

plsn

NULL

+ +  + +**Note**   Another way to reserve space in a marshalling area is to call [**ClfsAlignReservedLog**](https://msdn.microsoft.com/library/windows/hardware/ff540779) followed by [**ClfsAllocReservedLog**](https://msdn.microsoft.com/library/windows/hardware/ff540782). + +  + +### Writing a record to reserved space + +Suppose you have already reserved space for three records whose sizes, in bytes, are 100, 200, and 300. The marshalling area has a reserved-record count of 3 and enough reserved space to hold the 600 bytes of record data, the record headers, and any padding required for alignment. + +Now suppose you want to write one of those records into the reserved space in the marshalling area. The available reserved space will be reduced, and the reserved-record count will be decremented from 3 to 2. The following table shows how to set the parameters when you call **ClfsReserveAndAppendLog**. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to an array of CLFS_WRITE_ENTRY structures.

cWriteEntries

The number of elements in the array pointed to by rgWriteEntries.

plsnUndoNext

CLFS_LSN_INVALID or the LSN of the previous record in the undo chain. For more information about the undo chain, see [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md).

plsnPrevious

CLFS_LSN_INVALID or the LSN of the previous log record in the previous-LSN chain. For more information about the previous-LSN chain, see [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md).

cReserveRecords

0

rgcbReservation

NULL

fFlags

CLFS_FLAG_USE_RESERVATION

plsn

A pointer to a CLFS_LSN structure. (This is an output parameter that receives the LSN of the record that is written.)

+ +  + +### Writing records with aligned entries + +Suppose you want to write a record that has three write entries. The write entries vary in size between 300 and 500 bytes, but you require that each write entry begins on a 512-byte boundary. The following table shows how to set the parameters of the **ClfsReserveAndAppendLogAligned** function. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameValue

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to an array of three CLFS_WRITE_ENTRY structures.

cWriteEntries

3

cbEntryAlignment

512

plsnUndoNext

CLFS_LSN_INVALID or the LSN of the previous record in the undo chain. For more information about the undo chain, see [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md).

plsnPrevious

CLFS_LSN_INVALID or the LSN of the previous log record in the previous-LSN chain. For more information about the previous-LSN chain, see [CLFS Log Sequence Numbers](clfs-log-sequence-numbers.md).

cReserveRecords

0

rgcbReservation

NULL

fFlags

Zero or some combination of flags that specify flush and reservation preferences.

plsn

A pointer to a CLFS_LSN structure. (This is an output parameter that receives the LSN of the record that is written.)

+ +  + +The preceding tables show only a few of the many variations on reserving record space and writing records to CLFS streams. As you think of other variations, keep the following point in mind: The actions performed by **ClfsReserveAndAppendLog** (or **ClfsReserveAndAppendLogAligned**) are atomic. For example, you can make a single call to **ClfsReserveAndAppendLog** that will reserve space for a record and write the record to the stream. The pair of actions (reserve, write) will either succeed as a whole or fail as a whole. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20Data%20Records%20to%20a%20CLFS%20Stream%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-dispatch-routines.md b/windows-driver-docs-pr/kernel/writing-dispatch-routines.md new file mode 100644 index 0000000000..d6c1b5eb28 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-dispatch-routines.md @@ -0,0 +1,66 @@ +--- +title: Writing Dispatch Routines +author: windows-driver-content +description: Writing Dispatch Routines +ms.assetid: 84eb9372-2ef7-4cc2-94af-97e3399e69e0 +keywords: ["dispatch routines WDK kernel", "standard driver routines WDK kernel , dispatch routines", "driver routines WDK kernel , dispatch routines", "routines WDK kernel , dispatch routines", "system-space memory allocations WDK kernel", "system resource storage WDK kernel", "storing system resources", "dispatch routines WDK kernel , about dispatch routines", "IRPs WDK kernel , dispatch routines", "multiple I/O function codes WDK kernel", "IRP major function codes WDK kernel", "major function codes WDK kernel", "function codes WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing Dispatch Routines + + +## + + +Processing any I/O request packet (IRP) begins in a dispatch routine that the driver registers to handle an [IRP major function code](https://msdn.microsoft.com/library/windows/hardware/ff550710) (**IRP\_MJ\_*XXX***). The driver's [**DriverEntry**](https://msdn.microsoft.com/library/windows/hardware/ff544113) routine exports entry points for dispatch routines in a dispatch table within the driver's [**DRIVER\_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff544174) structure. + +A driver can provide a separate dispatch routine for each major I/O function code that it handles. Alternatively, dispatch routines can be written to handle multiple I/O function codes. + +This section contains the following topics: + +[Dispatch Routine Functionality](dispatch-routine-functionality.md) + +[Required Dispatch Routines](required-dispatch-routines.md) + +[Optional Dispatch Routines](optional-dispatch-routines.md) + +[Dispatch Routines and IRQLs](dispatch-routines-and-irqls.md) + +[When to Check the Driver's I/O Stack Location](when-to-check-the-driver-s-i-o-stack-location.md) + +[DispatchCreate, DispatchClose, and DispatchCreateClose Routines](dispatchcreate--dispatchclose--and-dispatchcreateclose-routines.md) + +[DispatchCleanup Routines](dispatchcleanup-routines.md) + +[DispatchRead, DispatchWrite, and DispatchReadWrite Routines](dispatchread--dispatchwrite--and-dispatchreadwrite-routines.md) + +[DispatchDeviceControl and DispatchInternalDeviceControl Routines](dispatchdevicecontrol-and-dispatchinternaldevicecontrol-routines.md) + +[DispatchPnP Routines](dispatchpnp-routines.md) + +[DispatchPower Routines](dispatchpower-routines.md) + +[DispatchQueryInformation Routines](dispatchqueryinformation-routines.md) + +[DispatchSetInformation Routines](dispatchsetinformation-routines.md) + +[DispatchFlushBuffers Routines](dispatchflushbuffers-routines.md) + +[DispatchShutdown Routines](dispatchshutdown-routines.md) + +[DispatchSystemControl Routines](dispatchsystemcontrol-routines.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20Dispatch%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-dpc-routines.md b/windows-driver-docs-pr/kernel/writing-dpc-routines.md new file mode 100644 index 0000000000..1a44eef5d4 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-dpc-routines.md @@ -0,0 +1,68 @@ +--- +title: Writing DPC Routines +author: windows-driver-content +description: Writing DPC Routines +ms.assetid: a0b93b71-7ee3-4626-b0b8-5dd6e19fba0d +keywords: ["deferred procedure calls WDK kernel", "DPCs WDK kernel", "DpcForIsr", "CustomDpc"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing DPC Routines + + +## + + +The primary responsibilities of [*DpcForIsr*](https://msdn.microsoft.com/library/windows/hardware/ff544079) and [*CustomDpc*](https://msdn.microsoft.com/library/windows/hardware/ff542972) routines are ensuring that the next device I/O operation is started promptly and completing the current IRP. + +Additional work done by any *DpcForIsr* or *CustomDpc* routine depends on the driver's design and the nature of the device. For example, a *DpcForIsr* or *CustomDpc* routine also can do any of the following: + +- Retry an operation that has timed out or failed. + +- Call [**IoAllocateErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff548245), set up an error log packet to report a device I/O error, and call [**IoWriteErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff550527). + + For more information about handling I/O errors, see [Logging Errors](logging-errors.md). + +- If the driver uses [buffered I/O](methods-for-accessing-data-buffers.md), or if the IRP specifies a device control operation, transfer data read in from the device to the system buffer at **Irp->AssociatedIrp.SystemBuffer** before completing the IRP. + +- If the driver uses [direct I/O](methods-for-accessing-data-buffers.md) and must break large transfers into smaller pieces, save state about each just-completed partial-transfer operation, calculate the next partial-transfer range, and use a driver-supplied [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routine to program the device for the next partial-transfer operation. + + Even a driver that uses buffered I/O might have to split up a transfer request if its device has limited transfer capabilities. + +- If the driver uses packet-based DMA, call [**FlushAdapterBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff545917) after each device transfer operation, and call [**FreeAdapterChannel**](https://msdn.microsoft.com/library/windows/hardware/ff546507) or [**FreeMapRegisters**](https://msdn.microsoft.com/library/windows/hardware/ff546513) when a sequence of partial transfers is done and the full transfer request is satisfied. + + If a requested transfer is only partly satisfied by a single DMA operation, the *DpcForIsr* or *CustomDpc* routine is usually responsible for setting up one or more DMA operations until the IRP's specified number of bytes have been fully transferred. + + For more information about using DMA, see [Adapter Objects and DMA](adapter-objects-and-dma.md). + +- If the driver uses programmed I/O (PIO), call [**KeFlushIoBuffers**](https://msdn.microsoft.com/library/windows/hardware/ff552041) at the end of each transfer operation if the current IRP requests a read. + + If a requested transfer is only partly satisfied by a single PIO operation, the *DpcForIsr* or *CustomDpc* routine is usually responsible for setting up one or more transfer operations until the IRP's specified number of bytes have been fully transferred. + + For more information about using PIO, see [Using Direct I/O](using-direct-i-o.md). + +- If a non-WDM driver has a [*ControllerControl*](https://msdn.microsoft.com/library/windows/hardware/ff542049) routine, call [**IoFreeController**](https://msdn.microsoft.com/library/windows/hardware/ff549104) when a requested operation is complete. + +Note that a *DpcForIsr* or *CustomDpc* routine usually does most of the driver's device I/O processing to satisfy IRPs. These routines also share some of the responsibility for queuing IRPs to the device with the driver's dispatch routines. + +Consider the following a general design guidelines. + +- Any *DpcForIsr* or *CustomDpc* routine should call [**IoStartNextPacket**](https://msdn.microsoft.com/library/windows/hardware/ff550358) as soon as it can safely make this call: that is, without possibly causing a resource conflict or race condition with the driver's [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine or with any other routine the *StartIo* routine causes to run. + +- If a driver manages its own queuing of IRPs, its *DpcForIsr* or *CustomDpc* routine should notify the driver as soon as it is safe to dequeue the next IRP and to set up the device for the next request. + +A *DpcForIsr* or *CustomDpc* routine must call **IoStartNextPacket**, or otherwise notify the appropriate driver routine when device I/O processing for the next request can be started. Depending on the driver and its device, this can occur well before the *DpcForIsr* or *CustomDpc* routine completes the current IRP with [**IoCompleteRequest**](https://msdn.microsoft.com/library/windows/hardware/ff548343), or it can occur immediately before this routine completes the current IRP and returns control. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20DPC%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-restart-records-to-a-clfs-stream.md b/windows-driver-docs-pr/kernel/writing-restart-records-to-a-clfs-stream.md new file mode 100644 index 0000000000..7bef293675 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-restart-records-to-a-clfs-stream.md @@ -0,0 +1,34 @@ +--- +title: Writing Restart Records to a CLFS Stream +author: windows-driver-content +description: Writing Restart Records to a CLFS Stream +ms.assetid: ae341d7e-37b2-4880-948c-e78e29278c64 +keywords: ["Common Log File System WDK kernel , restart records", "CLFS WDK kernel , restart records", "restart records WDK CLFS", "checkpoints WDK CLFS"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing Restart Records to a CLFS Stream + + +## + + +There are two types of records in a Common Log File System (CLFS)stream: data records and restart records. This topic explains how to write restart records to a CLFS stream. For information about how to write data records, see [Writing Data Records to a CLFS Stream](writing-data-records-to-a-clfs-stream.md). + +Typically, restart records are written to a stream periodically to create checkpoints that help make recovery more efficient in the event of a system failure. Assume that you have already created a marshalling area and written several data records. You can then write a restart record by calling [**ClfsWriteRestartArea**](https://msdn.microsoft.com/library/windows/hardware/ff541770). By setting the *fFlags* parameter, you can specify whether the restart record is placed in the marshalling area's reserved space or in newly allocated space.When CLFS writes a restart record to a stream, it automatically sets the previous LSN of the record to the LSN of the previously written restart record for that stream. That forms a chain of restart records that can be traversed in reverse order. For information about reading the chain of restart records, see [Reading Restart Records from a CLFS Stream](reading-restart-records-from-a-clfs-stream.md). + +If you want to write a restart record to a stream and change the base LSN of the stream at the same time, set the *plsnBase* parameter of **ClfsWriteRestartArea** to the new base LSN. + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20Restart%20Records%20to%20a%20CLFS%20Stream%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-synchcritsection-routines.md b/windows-driver-docs-pr/kernel/writing-synchcritsection-routines.md new file mode 100644 index 0000000000..cbff164bc3 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-synchcritsection-routines.md @@ -0,0 +1,42 @@ +--- +title: Writing SynchCritSection Routines +author: windows-driver-content +description: Writing SynchCritSection Routines +ms.assetid: b02e230e-48f1-43dc-b5aa-368cd7b5436f +keywords: ["SynchCritSection", "critical section routines WDK kernel"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing SynchCritSection Routines + + +## + + +Drivers use their [*SynchCritSection*](https://msdn.microsoft.com/library/windows/hardware/ff563928) routines for either of two basic purposes: + +[Programming a device for an I/O operation](programming-a-device-for-an-i-o-operation.md) + +[Accessing shared state information](accessing-shared-state-information.md) + +Like an ISR, a *SynchCritSection* routine must execute as quickly as possible, doing only what is necessary to set up device registers or update context data, before returning. + +Because [**KeSynchronizeExecution**](https://msdn.microsoft.com/library/windows/hardware/ff553302) holds a device driver's interrupt spin lock while its *SynchCritSection* routine runs, the driver's ISR cannot execute until the *SynchCritSection* routine returns control. + +For any received IRP, a device driver should do as much I/O processing as possible either at IRQL PASSIVE\_LEVEL in its dispatch routines (or possibly [device-dedicated threads](device-dedicated-threads.md)), or at IRQL DISPATCH\_LEVEL in its [*StartIo*](https://msdn.microsoft.com/library/windows/hardware/ff563858) routine and DPC routines. + +For additional information about how critical sections are synchronized, see [Using Spin Locks: An Example](using-spin-locks--an-example.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20SynchCritSection%20Routines%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-to-the-system-event-log.md b/windows-driver-docs-pr/kernel/writing-to-the-system-event-log.md new file mode 100644 index 0000000000..05f6f2aedb --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-to-the-system-event-log.md @@ -0,0 +1,54 @@ +--- +title: Writing to the System Event Log +author: windows-driver-content +description: Writing to the System Event Log +ms.assetid: 19be8bb4-8736-4d1a-92e5-b63a5f04e254 +keywords: ["NTSTATUS values WDK kernel", "dump data WDK kernel", "predefined error codes WDK kernel", "system event logs WDK kernel", "property sheets WDK errors", "Event Viewer WDK kernel", "sample log entry property sheets WDK kernel", "log entries WDK kernel", "entries WDK error logs"] +ms.author: windowsdriverdev +ms.date: 06/16/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Writing to the System Event Log + + +## + + +Errors are specified by their NTSTATUS value. The system predefines particular NTSTATUS values that can be used by drivers, and driver writers can define additional errors. Note that only certain NTSTATUS values can be used when logging errors. + +Each NTSTATUS value that can be used when logging errors has an associated error message. For example, the parallel port driver uses the NTSTATUS value PAR\_INTERRUPT\_CONFLICT to represent hardware interrupt conflicts, with message text "Interrupt conflict detected for %1". + +The Event Viewer displays the message text in the **Description** text box on the log entry's property sheet. If the message text string contains "%1", the Event Viewer replaces it with the name of the device that logged the entry. The message text can contain additional parameters of the form "%2", "%3", and so on. When the driver logs the error, it can provide string values for those parameters. These string values are known as *insertion strings*. The Event Viewer will automatically insert them in place of the percent values. + +The driver can also include binary data in the log entry, known as *dump data*. The Event Viewer displays the dump data in the **Data** text box of the log entry's property sheet. + +You can bring up the property sheet for a log entry by double-clicking the entry in the Event Viewer. The following screen shot shows a sample log entry property sheet. + +![screen shot of an event property sheet](images/event-properties.png) + +Drivers use the [**IoAllocateErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff548245) routine to allocate an error log entry. Log entries consist of a variable-length [**IO\_ERROR\_LOG\_PACKET**](https://msdn.microsoft.com/library/windows/hardware/ff550571) header, followed by insertion strings. + +The following diagram shows the layout of an error log entry in memory. + +![diagram illustrating a layout of an error log packet in memory ](images/errorlogentry.png) + +The **ErrorCode** member of **IO\_ERROR\_LOG\_PACKET** specifies the NTSTATUS value of the error. The **DumpData** member specifies any dump data for the log entry. **DumpData** is a variable-sized array, whose size is specified by the **DumpDataSize** member. Drivers specify the beginning of the first insertion string with the **StringOffset** member, and the number of strings in the **NumberOfStrings** member. Each insertion string itself is a null-terminated Unicode string. + +Once the driver fills out the allocated error log entry, it writes the entry to the error log by using [**IoWriteErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff550527). **IoWriteErrorLogEntry** automatically frees the memory allocated for the log entry. Drivers can use [**IoFreeErrorLogEntry**](https://msdn.microsoft.com/library/windows/hardware/ff549107) to free any unused log entries. + +Predefined error codes (of the form IO\_ERR\_*XXX*) are defined in the ntiologc.h header file that is included with the Windows Driver Kit (WDK). The error message associated with each error code can be found in the comments for ntiologc.h, next to the error code's declaration. To use a predefined error code, the driver must register the system file, iologmsg.dll, as the source of the associated error messages. For further information, see [Registering as a Source of Error Messages](registering-as-a-source-of-error-messages.md). + +Drivers can also define their own custom error types, and associated error messages. For further information, see [Defining Custom Error Types](defining-custom-error-types.md). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20to%20the%20System%20Event%20Log%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/kernel/writing-wdm-drivers.md b/windows-driver-docs-pr/kernel/writing-wdm-drivers.md new file mode 100644 index 0000000000..29a3ed90a7 --- /dev/null +++ b/windows-driver-docs-pr/kernel/writing-wdm-drivers.md @@ -0,0 +1,39 @@ +--- +title: Writing WDM Drivers +author: windows-driver-content +description: Writing WDM Drivers +ms.assetid: 379305f0-3caa-4c8d-add5-17e8c83f2429 +--- + +# Writing WDM Drivers + + +This section discusses the Microsoft Windows Driver Model (WDM) architecture. This architecture started in Windows 2000 as an enhancement to previous Windows NT device drivers. + +**Note**  Drivers for versions of Windows NT-based operating systems before Windows 2000 are not supported, and you should update these drivers. The WDM architecture does not support drivers for non-Windows NT-based operating systems (such as Windows 98), and you should rewrite such drivers. + +  + +This section is divided into three parts: + +- [Windows Driver Model](windows-driver-model.md) describes the Windows Driver Model (WDM), including types of WDM drivers, device configuration, and WDM versioning. + +- [Device Objects and Device Stacks](device-objects-and-device-stacks.md) describes device objects and device stacks. The section includes information about physical device objects (PDOs), functional device objects (FDOs), and filter device objects (filter DOs). Drivers are often built from a set of device objects that work together. This set of device objects is called a *stack*. Stacks can help you understand the flow of information to and from a driver and how different parts of the driver communicate internally. + +- [Kernel-Mode Driver Components](kernel-mode-driver-components.md) describes which routines you must implement to have a functional driver and which routines are optional. + + A *device driver* is a set of software code that must integrate into the operating system. To complete this integration, you must write a set of handler routines in your driver that process calls from the operating system. These routines can be simple function calls, but many of them implement the processing of *I/O request packets* (IRPs), which facilitate communication between drivers and the operating system. + +**Note**  WDM drivers can also use the Windows Driver Frameworks (WDF) library to make some parts of a device driver easier to write. Specifically, kernel-mode drivers can use the Kernel-Mode Driver Framework (KMDF), which is part of WDF. For more information about KMDF for kernel-mode drivers, see [Kernel-Mode Driver Framework Overview](https://msdn.microsoft.com/library/windows/hardware/ff544296). Note that KMDF does not replace WDM. You must still understand many parts of WDM to write a KMDF driver. + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bkernel\kernel%5D:%20Writing%20WDM%20Drivers%20%20RELEASE:%20%286/14/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/mobilebroadband/allowstandarduserpinunlock.md b/windows-driver-docs-pr/mobilebroadband/allowstandarduserpinunlock.md index 4be35c06f5..655af5a5df 100644 --- a/windows-driver-docs-pr/mobilebroadband/allowstandarduserpinunlock.md +++ b/windows-driver-docs-pr/mobilebroadband/allowstandarduserpinunlock.md @@ -9,6 +9,9 @@ ms.prod: windows-hardware ms.technology: windows-devices --- +> [!IMPORTANT] +> Starting in Windows 10, version 1507, this element has been deprecated and may not be supported in future versions of Windows. + # AllowStandardUserPinUnlock @@ -17,7 +20,7 @@ The AllowStandardUserPinUnlock element specifies if standard users are allowed t ## Usage -``` syntax +```syntax text diff --git a/windows-driver-docs-pr/mobilebroadband/hardwareid.md b/windows-driver-docs-pr/mobilebroadband/hardwareid.md index 1e7a93d4e4..09cd445cc4 100644 --- a/windows-driver-docs-pr/mobilebroadband/hardwareid.md +++ b/windows-driver-docs-pr/mobilebroadband/hardwareid.md @@ -80,7 +80,7 @@ There are no child elements. - + ``` diff --git a/windows-driver-docs-pr/mobilebroadband/packageinfo-xml-schema-definition.md b/windows-driver-docs-pr/mobilebroadband/packageinfo-xml-schema-definition.md index c041327449..e3c960c14f 100644 --- a/windows-driver-docs-pr/mobilebroadband/packageinfo-xml-schema-definition.md +++ b/windows-driver-docs-pr/mobilebroadband/packageinfo-xml-schema-definition.md @@ -82,7 +82,7 @@ The following is a definition of the PackageInfo schema. - + diff --git a/windows-driver-docs-pr/mobilebroadband/planning-your-apn-database-submission.md b/windows-driver-docs-pr/mobilebroadband/planning-your-apn-database-submission.md index 476f2eb1f6..9370c984f4 100644 --- a/windows-driver-docs-pr/mobilebroadband/planning-your-apn-database-submission.md +++ b/windows-driver-docs-pr/mobilebroadband/planning-your-apn-database-submission.md @@ -37,7 +37,7 @@ COSA and the APN connectivity database are updated by using Windows Update. The The APN update spreadsheet is used to gather the required information so Microsoft can update the COSA or the APN database appropriately. This spreadsheet is included in your submission request to Microsoft. -Use the following link to download the latest APN update spreadsheet: +Use the following link to download the latest APN update spreadsheet: The following table explains each entry in the spreadsheet. @@ -47,13 +47,13 @@ The following table explains each entry in the spreadsheet. | Applicable profile | Column name | Description | Optional or Required | Notes | | --- | --- | --- | --- | --- | | APN database & COSA | Update Type | Describes whether the APN Database entry is new or modified. | Possible values:
  • **Add** – A new entry
  • **Change** – Update an existing entry
  • **Keep** – Do not change the entry
  • **Delete** – Delete the entry
| Required | | -| COSA only | Data Marketplace support | A true/false string describing whether the profile supported by the data marketplace. | Optional | Either "True" or "False". | +| COSA only | Data Marketplace support | A true/false string describing whether the profile is supported by the data marketplace. | Optional | If left blank, defaults to "false." | | APN database & COSA | Country/Region | The country or region for the APN entry. | Required | Microsoft may change this to match how Windows refers to a particular country or region. | | APN database & COSA | Operator | The name of the operator. You do not need to include the country or region in this field. | Required | Ensure you use the same spelling and capitalization each time you submit an update for your APN entries. | | APN database only | GSM Provider Name | A string of no more than 36 characters that should match the GSM provider name reported by your device. This column is case sensitive. | Optional | This entry is only supported on Windows 8.1 and versions of Windows 10 before 1703. | -| COSA only | SPN | An identifier string for the Service Provider Name (SPN) | Optional | | -| COSA only | PNN | An identifier string for Public Land Mobile Network (PLMN) Network Name | Optional | Identifier string for MVNO | -| COSA only | GID1 | An identifier for Group Identifier Level 1 (GID1) | Optional | Identifier string for MVNO | +| COSA only | SPN | An identifier string for the Service Provider Name (SPN) | Optional | Helps to identify the MO/MVNO's network. If left blank, defaults to empty string and does nothing. | +| COSA only | PNN | An identifier string for Public Land Mobile Network (PLMN) Network Name | Optional | Identifier string for MVNO. If left blank, defaults to empty string and does nothing. | +| COSA only | GID1 | An identifier for Group Identifier Level 1 (GID1) | Optional | Identifier string for MVNO. If left blank, defaults to empty string and does nothing. | | APN database & COSA | MCC | A 3-digit MCC value used for GSM IMSI submissions. | Required for GSM providers | | | APN database & COSA | MNC | A 2- or 3-digit MNC value used for GSM IMSI submissions. | Required for GSM providers | | | APN database & COSA | IMSI Range - Start | A 15-digit number that includes the MCC+MNC at the start of the number. The number should end in 00. | Optional | If this column and the **IMSI Range - End** column is left blank but the **MCC** and **MNC** columns are specified, the entire MCC+MNC range is covered. | @@ -65,12 +65,12 @@ The following table explains each entry in the spreadsheet. | APN database only | Cert Issuer Name | The Cert Issuer Name of your signing certificate used for operator XML provisioning. | Optional | If specified, you must also specify the Cert Subject Name and Carrier GUID. | | APN database only | Cert Subject Name | The Cert Subject Name of your signing certificate used for operator XML provisioning. | Optional | If specified, you must also specify the Cert Issuer Name and Carrier GUID. | | APN database only | Carrier GUID | The self-assigned GUID that is used in future operator XML provisioning packages. | Optional | If specified, you must also specify the Cert Subject Name and Cert Issuer Name. | -| APN database only | Account Experience URL | Used by Windows Connection Manager if the user does not have an active plan and tries to connect to your network. | Optional | Helps improve the plan acquisition experience. | +| APN database & COSA | Account Experience URL | Used by Windows Connection Manager if the user does not have an active plan and tries to connect to your network. | Optional | Helps improve the plan acquisition experience. | | APN database & COSA | Connection Information – Friendly Name | A name for this APN entry that is understandable and meaningful to subscribers. | Optional | Shows up in Windows Connection Manager in cases where Windows cannot automatically connect to the network. | -| APN database & COSA | Connection Information – Access String | For GSM networks, this is an APN such as data.contoso.com. For CDMA networks, this is an access string that includes a special dial code such as #777 or an Network Access Identifier such as example@contoso.com. | Required | The access string can be blank. | -| APN database & COSA | IP Type | A string specifying the network protocol of the connection. Available values are:
  • IPv4
  • IPv6
  • IPv4v6
  • IPv4v6xlat
| Optional | If a value is not specified, the default value is "IPv4". | -| COSA only | AlwaysOn | | Required | | -| COSA only | Purpose groups | A string specifying the purposes of the connection by a comma-separated list of GUIDs representing purpose values. | Optional | The following purpose values are available:
  • **Internet** - 3E5545D2-1137-4DC8-A198-33F1C657515F
  • **MMS** - 53E2C5D3-D13C-4068-AA38-9C48FF2E55A8
  • **IMS** - 474D66ED-0E4B-476B-A455-19BB1239ED13
  • **SUPL** - 6D42669F-52A9-408E-9493-1071DCC437BD
  • **Purchase** - 95522B2B-A6D1-4E40-960B-05E6D3F962AB
  • **Administrative** - 2FFD9261-C23C-4D27-8DCF-CDE4E14A3364
  • **Application** - 52D7654A-00A8-4140-806C-087D66705306
| +| APN database & COSA | Connection Information – Access String | For GSM networks, this is an APN such as data.contoso.com. For CDMA networks, this is an access string that includes a special dial code such as #777 or an Network Access Identifier such as example@contoso.com. | Required | | +| APN database & COSA | IP Type | A string specifying the network protocol of the connection. Available values are:
  • IPv4
  • IPv6
  • IPv4v6
| Optional | If left blank, defaults to "IPv4." | +| COSA only | AlwaysOn | Describes whether the connection is always on or not. | Required | If left blank, defaults to "true." | +| COSA only | Purpose groups | A string specifying the purposes of the connection by a comma-separated list of GUIDs representing purpose values. | Optional | The following purpose values are available:
  • **Internet** - 3E5545D2-1137-4DC8-A198-33F1C657515F
  • **MMS** - 53E2C5D3-D13C-4068-AA38-9C48FF2E55A8
  • **IMS** - 474D66ED-0E4B-476B-A455-19BB1239ED13
  • **SUPL** - 6D42669F-52A9-408E-9493-1071DCC437BD
  • **Purchase** - 95522B2B-A6D1-4E40-960B-05E6D3F962AB
  • **Administrative** - 2FFD9261-C23C-4D27-8DCF-CDE4E14A3364
  • **Application** - 52D7654A-00A8-4140-806C-087D66705306

If left blank, defaults to "Internet."

| | APN database & COSA | Connection Information – User Name | The user name used to connect to your APN. This column is case sensitive. | Optional | | | APN database & COSA | Connection Information - Password | The password used to connect to your APN. This column is case sensitive. | Optional | | | APN database only | Connection Information – Purchase Flag | Possible values:
  • **Y** – if the APN is provisioning or purchase
  • **N** – if the APN is not provisioning or purchase
| Required | If **Purchase Flag** column is **Y**, the **Connect Flag** column must be **N**. | diff --git a/windows-driver-docs-pr/mobilebroadband/softwareinfo-xml-schema-definition.md b/windows-driver-docs-pr/mobilebroadband/softwareinfo-xml-schema-definition.md index 2e3dd32453..6e78fa6661 100644 --- a/windows-driver-docs-pr/mobilebroadband/softwareinfo-xml-schema-definition.md +++ b/windows-driver-docs-pr/mobilebroadband/softwareinfo-xml-schema-definition.md @@ -183,7 +183,7 @@ The following is a definition of the SoftwareInfo schema. - + diff --git a/windows-driver-docs-pr/netcx-beta-prerelease.md b/windows-driver-docs-pr/netcx-beta-prerelease.md new file mode 100644 index 0000000000..e9f6530372 --- /dev/null +++ b/windows-driver-docs-pr/netcx-beta-prerelease.md @@ -0,0 +1,7 @@ +--- +title: NetAdapterCx beta and preview warning +--- +> [!WARNING] +> Some information relates to prereleased 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. +> +> NetAdapterCx is preview only in Windows 10, version 1703. \ No newline at end of file diff --git a/windows-driver-docs-pr/netcx/TOC.md b/windows-driver-docs-pr/netcx/TOC.md new file mode 100644 index 0000000000..1f2f1050e6 --- /dev/null +++ b/windows-driver-docs-pr/netcx/TOC.md @@ -0,0 +1,151 @@ +# [Network Adapter WDF Class Extension (Cx)](index.md) +## [Porting NDIS Miniport Drivers to NetAdapter Class Extension](porting-ndis-to-netadapter-cx.md) +## [Building a NetAdapterCx Client Driver](building-a-netadaptercx-client-driver.md) +## [Device Initialization](device-initialization.md) +## [Accessing Configuration Information](accessing-configuration-information.md) +## [Handling Control Requests](handling-control-requests.md) +## [Debugging NetAdapterCx Client Drivers](debugging-netadaptercx-client-drivers.md) +## [Transferring Network Data](transferring-network-data.md) +## [Configuring Power Management](configuring-power-management.md) +## [NDIS-WDF Function Equivalents](ndis-wdf-function-equivalents.md) +## [Summary of Objects](summary-of-objects.md) +## [Power-Up Sequence for an Network Adapter WDF Client Driver](power-up-sequence-for-ndis-wdf-client-driver.md) +## [Power-Down Sequence for an Network Adapter WDF Client Driver](power-down-sequence-for-ndis-wdf-client-driver.md) +## [Network Adapter WDF Class Extension (Cx) Limitations](class-extension--net--limitations.md) +## [EVT_NET_ADAPTER_CREATE_RXQUEUE](evt-net-adapter-create-rxqueue.md) +## [EVT_NET_ADAPTER_CREATE_TXQUEUE](evt-net-adapter-create-txqueue.md) +## [EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD](evt-net-adapter-preview-protocol-offload.md) +## [EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN](evt-net-adapter-preview-wake-pattern.md) +## [EVT_NET_ADAPTER_SET_CAPABILITIES](evt-net-adapter-set-capabilities.md) +## [EVT_NET_REQUEST_DEFAULT](evt-net-request-default.md) +## [EVT_NET_REQUEST_DEFAULT_METHOD](evt-net-request-default-method.md) +## [EVT_NET_REQUEST_DEFAULT_QUERY_DATA](evt-net-request-default-query-data.md) +## [EVT_NET_REQUEST_DEFAULT_SET_DATA](evt-net-request-default-set-data.md) +## [EVT_NET_REQUEST_METHOD](evt-net-request-method.md) +## [EVT_NET_REQUEST_QUERY_DATA](evt-net-request-query-data.md) +## [EVT_NET_REQUEST_SET_DATA](evt-net-request-set-data.md) +## [EVT_RXQUEUE_ADVANCE](evt-rxqueue-advance.md) +## [EVT_RXQUEUE_CANCEL](evt-rxqueue-cancel.md) +## [EVT_RXQUEUE_SET_NOTIFICATION_ENABLED](evt-rxqueue-set-notification-enabled.md) +## [EVT_TXQUEUE_ADVANCE](evt-txqueue-advance.md) +## [EVT_TXQUEUE_CANCEL](evt-txqueue-cancel.md) +## [EVT_TXQUEUE_SET_NOTIFICATION_ENABLED](evt-txqueue-set-notification-enabled.md) +## [NET_ADAPTER_AUTO_NEGOTIATION_FLAGS](net-adapter-auto-negotiation-flags.md) +## [NET_ADAPTER_CONFIG](net-adapter-config.md) +## [NET_ADAPTER_CONFIG_INIT method](net-adapter-config-init.md) +## [NET_ADAPTER_DATAPATH_CAPABILITIES](net-adapter-datapath-capabilities.md) +## [NET_ADAPTER_DATAPATH_CAPABILITIES_INIT method](net-adapter-datapath-capabilities-init.md) +## [NET_ADAPTER_DRIVER_TYPE](net-adapter-driver-type.md) +## [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) +## [NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS](net-adapter-link-layer-capabilities-init-no-physical-address.md) +## [NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT](net-adapter-link-layer-capabilities-init.md) +## [NET_ADAPTER_LINK_STATE](net-adapter-link-state.md) +## [NET_ADAPTER_LINK_STATE_INIT method](net-adapter-link-state-init.md) +## [NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED method](net-adapter-link-state-init-disconnected.md) +## [NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS](net-adapter-media-specific-wakeup-events-flags.md) +## [NET_ADAPTER_PAUSE_FUNCTIONS](net-adapter-pause-functions.md) +## [NET_ADAPTER_PHYSICAL_ADDRESS](net-adapter-physical-address.md) +## [NET_ADAPTER_PHYSICAL_ADDRESS_INIT method](net-adapter-physical-address-init.md) +## [NET_ADAPTER_POWER_CAPABILITIES](net-adapter-power-capabilities.md) +## [NET_ADAPTER_POWER_CAPABILITIES_INIT method](net-adapter-power-capabilities-init.md) +## [NET_ADAPTER_POWER_FLAGS](net-adapter-power-flags.md) +## [NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS](net-adapter-protocol-offloads-flags.md) +## [NET_ADAPTER_STATISTICS_FLAGS](net-adapter-statistics-flags.md) +## [NET_ADAPTER_WAKE_PATTERN_FLAGS](net-adapter-wake-pattern-flags.md) +## [NET_ADAPTER_WAKEUP_EVENTS_FLAGS](net-adapter-wakeup-events-flags.md) +## [NET_CONFIGURATION_QUERY_ULONG_FLAGS](net-configuration-query-ulong-flags.md) +## [NET_DRIVER_GLOBALS](net-driver-globals.md) +## [NET_PACKET](net-packet.md) +## [NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME](net-packet-declare-context-type-with-name.md) +## [NET_PACKET_FILTER_TYPES_FLAGS](net-packet-filter-types-flags.md) +## [NET_PACKET_FRAGMENT](net-packet-fragment.md) +## [NET_REQUEST_QUEUE_CONFIG](net-request-queue-config.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER method](net-request-queue-config-add-initialized-method-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER method](net-request-queue-config-add-initialized-query-data-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_SET_DATA_HANDLER method](net-request-queue-config-add-initialized-set-data-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER method](net-request-queue-config-add-method-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER method](net-request-queue-config-add-query-data-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER method](net-request-queue-config-add-set-data-handler.md) +## [NET_REQUEST_QUEUE_CONFIG_INIT method](net-request-queue-config-init.md) +## [NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL method](net-request-queue-config-init-default-parallel.md) +## [NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL method](net-request-queue-config-init-default-sequential.md) +## [NET_REQUEST_QUEUE_METHOD_HANDLER](net-request-queue-method-handler.md) +## [NET_REQUEST_QUEUE_METHOD_HANDLER_INIT method](net-request-queue-method-handler-init.md) +## [NET_REQUEST_QUEUE_QUERY_DATA_HANDLER](net-request-queue-query-data-handler.md) +## [NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT method](net-request-queue-query-data-handler-init.md) +## [NET_REQUEST_QUEUE_SET_DATA_HANDLER](net-request-queue-set-data-handler.md) +## [NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT method](net-request-queue-set-data-handler-init.md) +## [NET_REQUEST_QUEUE_TYPE](net-request-queue-type.md) +## [NET_RING_BUFFER](net-ring-buffer.md) +## [NET_RXQUEUE_CONFIG](net-rxqueue-config.md) +## [NET_RXQUEUE_CONFIG_INIT method](net-rxqueue-config-init.md) +## [NET_TXQUEUE_CONFIG](net-txqueue-config.md) +## [NET_TXQUEUE_CONFIG_INIT method](net-txqueue-config-init.md) +## [NetAdapterCreate method](netadaptercreate.md) +## [NetAdapterDeviceInitConfig method](netadapterdeviceinitconfig.md) +## [NetAdapterDriverWdmGetHandle method](netadapterdriverwdmgethandle.md) +## [NetAdapterGetNetLuid method](netadaptergetnetluid.md) +## [NetAdapterGetPowerSettings method](netadaptergetpowersettings.md) +## [NetAdapterOpenConfiguration method](netadapteropenconfiguration.md) +## [NetAdapterSetCurrentLinkState method](netadaptersetcurrentlinkstate.md) +## [NetAdapterSetDataPathCapabilities method](netadaptersetdatapathcapabilities.md) +## [NetAdapterSetLinkLayerCapabilities method](netadaptersetlinklayercapabilities.md) +## [NetAdapterSetLinkLayerMtuSize method](netadaptersetlinklayermtusize.md) +## [NetAdapterSetPowerCapabilities method](netadaptersetpowercapabilities.md) +## [NetAdapterWdmGetNdisHandle method](netadapterwdmgetndishandle.md) +## [NetConfigurationAssignBinary method](netconfigurationassignbinary.md) +## [NetConfigurationAssignMultiString method](netconfigurationassignmultistring.md) +## [NetConfigurationAssignUlong method](netconfigurationassignulong.md) +## [NetConfigurationAssignUnicodeString method](netconfigurationassignunicodestring.md) +## [NetConfigurationClose method](netconfigurationclose.md) +## [NetConfigurationOpenSubConfiguration method](netconfigurationopensubconfiguration.md) +## [NetConfigurationQueryBinary method](netconfigurationquerybinary.md) +## [NetConfigurationQueryMultiString method](netconfigurationquerymultistring.md) +## [NetConfigurationQueryNetworkAddress method](netconfigurationquerynetworkaddress.md) +## [NetConfigurationQueryString method](netconfigurationquerystring.md) +## [NetConfigurationQueryUlong method](netconfigurationqueryulong.md) +## [NetPacketGetTypedContext method](netpacketgettypedcontext.md) +## [NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents method](netpowersettingsgetenabledmediaspecificwakeupevents.md) +## [NetPowerSettingsGetEnabledProtocolOffloads method](netpowersettingsgetenabledprotocoloffloads.md) +## [NetPowerSettingsGetEnabledWakePatterns method](netpowersettingsgetenabledwakepatterns.md) +## [NetPowerSettingsGetEnabledWakeUpFlags method](netpowersettingsgetenabledwakeupflags.md) +## [NetPowerSettingsGetProtocolOffload method](netpowersettingsgetprotocoloffload.md) +## [NetPowerSettingsGetProtocolOffloadCount method](netpowersettingsgetprotocoloffloadcount.md) +## [NetPowerSettingsGetProtocolOffloadCountForType method](netpowersettingsgetprotocoloffloadcountfortype.md) +## [NetPowerSettingsGetWakePattern method](netpowersettingsgetwakepattern.md) +## [NetPowerSettingsGetWakePatternCount method](netpowersettingsgetwakepatterncount.md) +## [NetPowerSettingsGetWakePatternCountForType method](netpowersettingsgetwakepatterncountfortype.md) +## [NetPowerSettingsIsProtocolOffloadEnabled method](netpowersettingsisprotocoloffloadenabled.md) +## [NetPowerSettingsIsWakePatternEnabled method](netpowersettingsiswakepatternenabled.md) +## [NetRequestCompleteWithoutInformation method](netrequestcompletewithoutinformation.md) +## [NetRequestGetId method](netrequestgetid.md) +## [NetRequestGetPortNumber method](netrequestgetportnumber.md) +## [NetRequestGetSwitchId method](netrequestgetswitchid.md) +## [NetRequestGetType method](netrequestgettype.md) +## [NetRequestGetVPortId method](netrequestgetvportid.md) +## [NetRequestMethodComplete method](netrequestmethodcomplete.md) +## [NetRequestQueryDataComplete method](netrequestquerydatacomplete.md) +## [NetRequestQueueCreate method](netrequestqueuecreate.md) +## [NetRequestQueueGetAdapter method](netrequestqueuegetadapter.md) +## [NetRequestRetrieveInputOutputBuffer method](netrequestretrieveinputoutputbuffer.md) +## [NetRequestSetBytesNeeded method](netrequestsetbytesneeded.md) +## [NetRequestSetDataComplete method](netrequestsetdatacomplete.md) +## [NetRequestWdmGetNdisOidRequest method](netrequestwdmgetndisoidrequest.md) +## [NetRingBufferAdvanceNextPacket method](netringbufferadvancenextpacket.md) +## [NetRingBufferGetElementAtIndex method](netringbuffergetelementatindex.md) +## [NetRingBufferGetNextPacket method](netringbuffergetnextpacket.md) +## [NetRingBufferGetNumberOfElementsInRange method](netringbuffergetnumberofelementsinrange.md) +## [NetRingBufferGetPacketAtIndex method](netringbuffergetpacketatindex.md) +## [NetRingBufferIncrementIndex method](netringbufferincrementindex.md) +## [NetRingBufferReturnCompletedPackets method](netringbufferreturncompletedpackets.md) +## [NetRingBufferReturnCompletedPacketsThroughIndex method](netringbufferreturncompletedpacketsthroughindex.md) +## [NetRxQueueConfigureDmaAllocator](netrxqueueconfiguredmaallocator.md) +## [NetRxQueueCreate method](netrxqueuecreate.md) +## [NetRxQueueGetRingBuffer method](netrxqueuegetringbuffer.md) +## [NetRxQueueInitGetQueueId method](netrxqueueinitgetqueueid.md) +## [NetRxQueueNotifyMoreReceivedPacketsAvailable method](netrxqueuenotifymorereceivedpacketsavailable.md) +## [NetTxQueueCreate method](nettxqueuecreate.md) +## [NetTxQueueGetRingBuffer method](nettxqueuegetringbuffer.md) +## [NetTxQueueInitGetQueueId method](nettxqueueinitgetqueueid.md) +## [NetTxQueueNotifyMoreCompletedPacketsAvailable method](nettxqueuenotifymorecompletedpacketsavailable.md) + diff --git a/windows-driver-docs-pr/netcx/accessing-configuration-information.md b/windows-driver-docs-pr/netcx/accessing-configuration-information.md new file mode 100644 index 0000000000..3564faa725 --- /dev/null +++ b/windows-driver-docs-pr/netcx/accessing-configuration-information.md @@ -0,0 +1,39 @@ +--- +title: Accessing Configuration Information +--- + +# Accessing Configuration Information + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The NetAdapterCx class extension supports a set of functions that provide access to client driver registry parameters. + +Typically, the client driver reads configuration info from its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback function. + +Start by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) to get a handle to a configuration object. You can then query it: + +```cpp +NETCONFIGURATION configuration; + +status = NetAdapterOpenConfiguration(NetAdapter, WDF_NO_OBJECT_ATTRIBUTES, &configuration); +if (! NT_SUCCESS(status)) { + return status; +} + +status = NetConfigurationQueryUlong(configuration, NET_CONFIGURATION_QUERY_ULONG_NO_FLAGS, &SomeValue, &myvalue); + +NetConfigurationClose(configuration); +``` +There are `NetConfiguration*` functions for querying ULONG data, strings, multi-strings (similar to REG_MULTI_SZ), binary blobs, and software-configurable network addresses: + +* [**NetConfigurationAssignBinary**](netconfigurationassignbinary.md) +* [**NetConfigurationAssignMultiString**](netconfigurationassignmultistring.md) +* [**NetConfigurationAssignUlong**](netconfigurationassignulong.md) +* [**NetConfigurationAssignUnicodeString**](netconfigurationassignunicodestring.md) +* [**NetConfigurationClose**](netconfigurationclose.md) +* [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md) +* [**NetConfigurationQueryBinary**](netconfigurationquerybinary.md) +* [**NetConfigurationQueryMultiString**](netconfigurationquerymultistring.md) +* [**NetConfigurationQueryNetworkAddress**](netconfigurationquerynetworkaddress.md) +* [**NetConfigurationQueryString**](netconfigurationquerystring.md) +* [**NetConfigurationQueryUlong**](netconfigurationqueryulong.md) diff --git a/windows-driver-docs-pr/netcx/building-a-netadaptercx-client-driver.md b/windows-driver-docs-pr/netcx/building-a-netadaptercx-client-driver.md new file mode 100644 index 0000000000..7bc5d59da1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/building-a-netadaptercx-client-driver.md @@ -0,0 +1,23 @@ +--- +title: Building a NetAdapterCx Client Driver +--- + +# Building a NetAdapterCx Client Driver + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +To obtain the latest version of Visual Studio and the Windows Driver Kit (WDK), please visit the [Hardware Dev Center](https://developer.microsoft.com/windows/hardware/windows-driver-kit). + +Use the following steps to create a new NetAdapter client driver in Visual Studio: + +1. Open Microsoft Visual Studio. On the File menu, choose **New > Project**. +2. In the **New Project > Templates > Visual C++ > Windows Driver > WDF** dialog box, select **Kernel Mode Driver (KMDF) Template**. +3. To open the Driver Property Page dialog, choose **Project > Properties**. +4. In the **Configuration Properties > Driver Settings > Network Adapter Driver** dialog box, select the **Link to the Network Adapter Class Extension** dropdown and set to **Yes**. +5. In the **Configuration Properties > Driver Settings > Network Adapter Driver** dialog box, select **Network Adapter Major Version** and **Network Adapter Minor Version**. +6. Add the following header to every source file (or to your common/precompiled header): +```cpp +#include +``` + +To watch a video that shows how to create a new NetAdapter client driver in Visual Studio, see [Network Adapter Class Extension: Your First Driver](https://aka.ms/netadapter/video2). diff --git a/windows-driver-docs-pr/netcx/class-extension--net--limitations.md b/windows-driver-docs-pr/netcx/class-extension--net--limitations.md new file mode 100644 index 0000000000..0ef6050898 --- /dev/null +++ b/windows-driver-docs-pr/netcx/class-extension--net--limitations.md @@ -0,0 +1,16 @@ +--- +title: Network Adapter WDF Class Extension (Cx) Limitations +--- + +# Network Adapter WDF Class Extension (Cx) Limitations + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +This topic describes caveats you should be aware of when calling WDF functions from a NetAdapterCx client driver. + +|Function | Description | +|-|-| +| [**WdfDeviceInitAssignSDDLString**](https://msdn.microsoft.com/library/windows/hardware/ff546035) | By default [**NetAdapterDeviceInitConfig**](netadapterdeviceinitconfig.md) assigns `SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R` as the default SDDL. If you specify a more restrictive SDDL, the application might not be able to send query OIDs to the adapter. | +|[**WdfDeviceInitSetFileObjectConfig**](https://msdn.microsoft.com/library/windows/hardware/ff546107)| The client driver must not set **WdfFileObjectWdfCanUseFsContext** in the **FileObjectClass** member of [WDF_FILEOBJECT_CONFIG](https://msdn.microsoft.com/library/windows/hardware/ff551319). | +| [**WdfDeviceInitAssignName**](https://msdn.microsoft.com/library/windows/hardware/ff546029), [**WdfDeviceInitSetReleaseHardwareOrderOnFailure**](https://msdn.microsoft.com/library/windows/hardware/hh706196), [**WdfDeviceInitSetDeviceType**](https://msdn.microsoft.com/library/windows/hardware/ff546090), [**WdfDeviceInitSetCharacteristics**](https://msdn.microsoft.com/library/windows/hardware/ff546074), [**WdfDeviceInitSetIoType**](https://msdn.microsoft.com/library/windows/hardware/ff546128), [**WdfDeviceInitSetPowerPageable**](https://msdn.microsoft.com/library/windows/hardware/ff546766) | [**NetAdapterDeviceInitConfig**](netadapterdeviceinitconfig.md) calls these routines on behalf of the client driver. The client driver should not call these. +| [**WdfDeviceCreateDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff545935) | If the client driver calls [**WdfDeviceCreateDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff545935) with the **ReferenceString** parameter equal to **NULL**, NDIS intercepts I/O requests sent to the device interface. To avoid this behavior, specify any reference string. diff --git a/windows-driver-docs-pr/netcx/configuring-power-management.md b/windows-driver-docs-pr/netcx/configuring-power-management.md new file mode 100644 index 0000000000..777841bf34 --- /dev/null +++ b/windows-driver-docs-pr/netcx/configuring-power-management.md @@ -0,0 +1,85 @@ +--- +title: Configuring Power Management +--- + +# Configuring Power Management + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +This topic describes how to configure power management capabilities in a NetAdapterCx client driver. + +Because the client driver is a WDF driver, much of the implementation is the same as any other WDF driver, and then there are a few options specific to NetAdapterCx that you can add in. + +For details on the common WDF behaviors, see the following pages: + +* The client registers optional WDF event callbacks to receive notification of power transitions, as described in [Supporting PnP and Power Management in Function Drivers](../wdf/supporting-pnp-and-power-management-in-function-drivers.md). +* For info on registering PnP and power callback functions in a WDF client, see [Creating Device Objects in a Function Driver](../wdf/creating-device-objects-in-a-function-driver.md). +* For details on how your device can wake the system from a system-wide low-power state, see [Supporting System Wake-Up](../wdf/supporting-system-wake-up.md). + +## Setting power capabilities of the network adapter + +After configuring the standard WDF power management functionality, the next step is to call [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) to set the power capabilities of the network adapter. + +The following example shows how to initialize and configure a NETPOWERSETTINGS object, which the client typically does in its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) callback: + +```cpp +NET_ADAPTER_POWER_CAPABILITIES powerCaps; +NET_ADAPTER_POWER_CAPABILITIES_INIT(&powerCaps); + +powerCaps.Flags = NET_ADAPTER_POWER_WAKE_PACKET_INDICATION; + +powerCaps.SupportedMediaSpecificWakeUpEvents = NET_ADAPTER_WLAN_WAKE_ON_AP_ASSOCIATION_LOST; +powerCaps.SupportedProtocolOffloads = NET_ADAPTER_PROTOCOL_OFFLOAD_ARP | NET_ADAPTER_PROTOCOL_OFFLOAD_NS; +powerCaps.SupportedWakePatterns = NET_ADAPTER_WAKE_BITMAP_PATTERN; +powerCaps.SupportedWakeUpEvents = NET_ADAPTER_WAKE_ON_MEDIA_CONNECT | NET_ADAPTER_WAKE_ON_MEDIA_DISCONNECT; + +powerCaps.EvtAdapterPreviewWakePattern = EvtAdapterPreviewWakePattern; +powerCaps.EvtAdapterPreviewProtocolOffload = EvtAdapterPreviewProtocolOffload; + +NetAdapterSetPowerCapabilities(NetAdapter, &powerCaps); +``` + +The client can register [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) and [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) callback functions to accept or reject incoming protocol offloads and wake patterns. If you would like to register either of these optional callbacks, you must do so within [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md). + +## Programming Protocol Offload and Wake Patterns + +In its [*EvtDeviceArmWakeFromS0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) and [*EvtDeviceArmWakeFromSx*](https://msdn.microsoft.com/library/windows/hardware/ff540844) callback functions, the driver iterates through the enabled wake patterns and protocol offloads and programs them into the hardware. + +First retrieve a handle to the NETPOWERSETTINGS object that is associated with the adapter by calling [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md) from [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) or a related callback function. The following example shows how to iterate through the wake patterns: + +```cpp +NTSTATUS +EvtDeviceArmWakeFromS0( + WDFDEVICE Device +) +{ + + NETADAPTER adapter = GetDeviceContext(Device)->Adapter; + NETPOWERSETTINGS powerSettings = NetAdapterGetPowerSettings(adapter); + + ULONG wakeUpFlags = NetPowerSettingsGetEnabledWakeUpFlags(powerSettings); + + if (wakeUpFlags & NET_ADAPTER_WAKE_ON_MEDIA_DISCONNNECT) + { + // ... + } + + // Iterate through stored wake patterns and query which ones + // are enabled and should be programmed to hardware + + for (ULONG i = 0; i < NetPowerSettingsGetWakePatternCount(powerSettings); i++) + { + PNDIS_PM_WOL_PATTERN wakePattern = NetPowerSettingsGetWakePattern(powerSettings, i); + + if (NetPowerSettingsIsWakePatternEnabled(powerSettings, wakePattern)) + { + // ... + } + + } + + return STATUS_SUCCESS; +} +``` + +The client uses the same mechanism to iterate through protocol offloads, using [**NetPowerSettingsGetProtocolOffloadCount**](netpowersettingsgetprotocoloffloadcount.md), [**NetPowerSettingsGetProtocolOffload**](netpowersettingsgetprotocoloffload.md) and [**NetPowerSettingsIsProtocolOffloadEnabled**](netpowersettingsisprotocoloffloadenabled.md). diff --git a/windows-driver-docs-pr/netcx/debugging-netadaptercx-client-drivers.md b/windows-driver-docs-pr/netcx/debugging-netadaptercx-client-drivers.md new file mode 100644 index 0000000000..2096ea7f96 --- /dev/null +++ b/windows-driver-docs-pr/netcx/debugging-netadaptercx-client-drivers.md @@ -0,0 +1,24 @@ +--- +title: Debugging NetAdapterCx Client Drivers +--- + +# Debugging NetAdapterCx Client Drivers + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +You can use [Windows Driver Framework Extensions (Wdfkd.dll)](https://msdn.microsoft.com/library/windows/hardware/ff551876) commands to debug your client driver. In addition, [!ndiskd.netadapter](https://msdn.microsoft.com/library/windows/hardware/mt799821) will show networking-specific properties of your adapter. + +Also, you can use the `!ndiskd.netrb` debugger extension with the address of a [**NET_RING_BUFFER**](net-ring-buffer.md) structure to examine packets and fragments in a ring buffer. This command gives you additional information, such as the number of elements in the ring buffer, along with the number of packets owned by the OS and the number of packets owned by the client. + +You can use the following !ndiskd commands with a NetAdapterCx client driver: + +* [**!ndiskd.cxadapter**](https://msdn.microsoft.com/library/windows/hardware/mt808786) + * Given a NETADAPTER handle, show information about a NETADAPTER object. +* [**!ndiskd.netqueue**](https://msdn.microsoft.com/library/windows/hardware/mt808789) + * Given a NETTXQUEUE or NETRXQUEUE handle, show information about a data path queue. +* [**!ndiskd.netrb**](https://msdn.microsoft.com/library/windows/hardware/mt808790) + * Shows [**NET_RING_BUFFER**](net-ring-buffer.md) information. +* [**!ndiskd.netpacket**](https://msdn.microsoft.com/library/windows/hardware/mt808787) + * Shows information about a [**NET_PACKET**](net-packet.md). +* [**!ndiskd.netpacketfragment**](https://msdn.microsoft.com/library/windows/hardware/mt808788) + * Shows information about a [**NET_PACKET_FRAGMENT**](net-packet-fragment.md). diff --git a/windows-driver-docs-pr/netcx/device-initialization.md b/windows-driver-docs-pr/netcx/device-initialization.md new file mode 100644 index 0000000000..6318f31382 --- /dev/null +++ b/windows-driver-docs-pr/netcx/device-initialization.md @@ -0,0 +1,52 @@ +--- +title: Device Initialization +--- + +# Device Initialization + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +A NetAdapterCx driver registers its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback function when it calls [**WdfDriverCreate**](https://msdn.microsoft.com/library/windows/hardware/ff547175) from its [*DriverEntry*](https://msdn.microsoft.com/library/windows/hardware/ff540807) routine. + +## EVT_WDF_DRIVER_DEVICE_ADD + +In [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693), a NetAdapterCx client driver should do the following in order: + +1. Call [**NetAdapterDeviceInitConfig**](netadapterdeviceinitconfig.md). + + ```cpp + status = NetAdapterDeviceInitConfig(DeviceInit); + if (!NT_SUCCESS(status)) { + return status; + } + ``` + +2. Call [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926). + +3. Create the NETADAPTER object. This object represents your NIC, which is the endpoint for all networking I/O. To create the NETADAPTER object, the client typically calls [**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md), followed by [**NetAdapterCreate**](netadaptercreate.md): + + ```cpp + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attribs, MYDRIVER_ADAPTER_CONTEXT); + + NET_ADAPTER_CONFIG_INIT ( + &config, + EvtAdapterSetCapabilities, + EvtAdapterCreateTxQueue, + EvtAdapterCreateRxQueue); + + status = NetAdapterCreate(device, &attribs, &config, &adapter); + ``` + +You can have only one NETADAPTER per WDFDEVICE, with the WDFDEVICE being the parent object of the NETADAPTER. You can find the object hierarchy in [Summary of Objects](summary-of-objects.md). + +Optionally, you can add context space to the NETADAPTER object. Since you can set a context on any WDF object, you could add separate context space for the WDFDEVICE and the NETADAPTER objects. In the example in step 4, the client adds `MYDRIVER_ADAPTER_CONTEXT` to the NETADAPTER object. For more info, see [Framework Object Context Space](../wdf/framework-object-context-space.md). + +We recommend that you put device-related data in the context for your WDFDEVICE, and networking-related data into your NETADAPTER context. If you are porting an existing NDIS 6.x driver, you'll likely have a single MiniportAdapterContext that combines networking-related and device-related data into a single data structure. To simplify the porting process, just convert that entire structure to the WDFDEVICE context, and make the NETADAPTER's context a small structure that points to the WDFDEVICE's context. + +You'll provide 3 callbacks to [**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md) macro: + +* [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md) +* [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md) +* [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) + +For details on what to provide in your implementations of these callbacks, see the individual reference pages. diff --git a/windows-driver-docs-pr/netcx/evt-net-adapter-create-rxqueue.md b/windows-driver-docs-pr/netcx/evt-net-adapter-create-rxqueue.md new file mode 100644 index 0000000000..9a83e98a90 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-adapter-create-rxqueue.md @@ -0,0 +1,144 @@ +--- +title: EVT_NET_ADAPTER_CREATE_RXQUEUE callback function +topic_type: +- apiref +api_name: +- PFN_NET_ADAPTER_CREATE_RXQUEUE +api_location: +- netadapter.h +api_type: +- UserDefined +--- + +# EVT_NET_ADAPTER_CREATE_RXQUEUE callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver's implementation of the *EVT_NET_ADAPTER_CREATE_RXQUEUE* event callback function that sets up a receive queue. + +Syntax +------ + +```cpp +EVT_NET_ADAPTER_CREATE_RXQUEUE EvtNetAdapterCreateRxqueue; + +NTSTATUS EvtNetAdapterCreateRxqueue( + _In_    NETADAPTER       Adapter, + _Inout_ PNETRXQUEUE_INIT RxQueueInit +) +{ ... } + +typedef EVT_NET_ADAPTER_CREATE_RXQUEUE PFN_NET_ADAPTER_CREATE_RXQUEUE; +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*RxQueueInit* [in, out] +A pointer to a NetAdapterCx-allocated **NETRXQUEUE_INIT** structure. For more information, see the Remarks section. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +------- + +To register an *EVT_NET_ADAPTER_CREATE_RXQUEUE* callback function, the client driver must call [**NetAdapterCreate**](netadaptercreate.md). + +The **NETRXQUEUE_INIT** structure is an opaque structure that is defined and allocated by NetAdapterCx, similar to [WDFDEVICE_INIT](https://msdn.microsoft.com/library/windows/hardware/ff546951). + +In this callback, the client driver might call [**NetRxQueueInitGetQueueId**](netrxqueueinitgetqueueid.md) to retrieve the identifier of the receive queue to set up. + +Next, the client calls [**NetRxQueueCreate**](netrxqueuecreate.md) to allocate a queue. If the client provides a non-zero value in the **AllocationSize** member of the [**NET_RXQUEUE_CONFIG**](net-rxqueue-config.md) structure, [**NetRxQueueCreate**](netrxqueuecreate.md) allocates the receive buffers. The client should not use the buffers until after [**NetRxQueueCreate**](netrxqueuecreate.md) has returned. If [**NetRxQueueCreate**](netrxqueuecreate.md) fails, the *EVT_NET_ADAPTER_CREATE_RXQUEUE* callback function should return an error code. + +To retrieve the ring buffer associated with a given queue, call [**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md). + +Example +----- + +```cpp +NTSTATUS +EvtAdapterCreateRxQueue( + _In_ NETADAPTER netAdapter, + _Inout_ PNETRXQUEUE_INIT rxQueueInit) +{ + NTSTATUS status = STATUS_SUCCESS; + + NET_RXQUEUE_CONFIG rxConfig; + NET_RXQUEUE_CONFIG_INIT( + &rxConfig, + EvtRxQueueAdvance, + EvtRxQueueSetNotificationEnabled, + EvtRxQueueCancel); + + // Specify buffer size required per packet so the OS can preallocate + + rxConfig.AlignmentRequirement = 64; + rxConfig.AllocationSize = NIC_MAX_PACKET_SIZE + FRAME_CRC_SIZE + RSVD_BUF_SIZE; + + // Assign fixed size data type as per packet context + + NET_RXQUEUE_CONFIG_SET_DEFAULT_PACKET_CONTEXT_TYPE(&rxConfig, MY_RXQUEUE_PACKET_CONTEXT); + + NTSTATUS status = NetRxQueueCreate( + rxQueueInit, + &rxAttributes, + &rxConfig, + &adapter->RxQueue); + + // Specify that the OS use a WDFDMAENABLER to allocate the receive buffers + + status = NetRxQueueConfigureDmaAllocator( + adapter->RxQueue, + adapter->DmaEnabler); + + return status; +} +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetAdapter.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-adapter-create-txqueue.md b/windows-driver-docs-pr/netcx/evt-net-adapter-create-txqueue.md new file mode 100644 index 0000000000..f580794ff1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-adapter-create-txqueue.md @@ -0,0 +1,101 @@ +--- +title: EVT_NET_ADAPTER_CREATE_TXQUEUE callback function +topic_type: +- apiref +api_name: +- PFN_NET_ADAPTER_CREATE_TXQUEUE +api_location: +- netadapter.h +api_type: +- UserDefined +--- + +# EVT_NET_ADAPTER_CREATE_TXQUEUE callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver's implementation of the *EVT_NET_ADAPTER_CREATE_TXQUEUE* event callback function that sets up a transmit queue. + +Syntax +------ + +```cpp +EVT_NET_ADAPTER_CREATE_TXQUEUE EvtNetAdapterCreateTxqueue; + +NTSTATUS EvtNetAdapterCreateTxqueue( + _In_    NETADAPTER       Adapter, + _Inout_ PNETTXQUEUE_INIT TxQueueInit +) +{ ... } + +typedef EVT_NET_ADAPTER_CREATE_TXQUEUE PFN_NET_ADAPTER_CREATE_TXQUEUE; +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*TxQueueInit* [in, out] +A pointer to a NetAdapterCx-allocated **NETTXQUEUE_INIT** structure. For more information, see the Remarks section. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +------- + +To register an *EVT_NET_ADAPTER_CREATE_TXQUEUE* callback function, the client driver must call [**NetAdapterCreate**](netadaptercreate.md). + +The **NETTXQUEUE_INIT** structure is an opaque structure that is defined and allocated by NetAdapterCx, similar to [WDFDEVICE_INIT](https://msdn.microsoft.com/library/windows/hardware/ff546951). + +In this callback, the client driver typically calls [**NetTxQueueInitGetQueueId**](nettxqueueinitgetqueueid.md) with *NetTxQueueInit* to retrieve the identifier of the transmit queue to set up. + +Next, the client calls [**NetTxQueueCreate**](nettxqueuecreate.md) to allocate a queue. If [**NetTxQueueCreate**](nettxqueuecreate.md) fails, the *EVT_NET_ADAPTER_CREATE_TXQUEUE* callback function should return an error code. + +To retrieve the ring buffer associated with a given queue, call [**NetTxQueueGetRingBuffer**](nettxqueuegetringbuffer.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetAdapter.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-adapter-preview-protocol-offload.md b/windows-driver-docs-pr/netcx/evt-net-adapter-preview-protocol-offload.md new file mode 100644 index 0000000000..3d0d071f7a --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-adapter-preview-protocol-offload.md @@ -0,0 +1,117 @@ +--- +title: EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD callback function +topic_type: +- apiref +api_name: +- PFN_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD +api_location: +- netadapter.h +api_type: +- UserDefined +--- + +# EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implement this optional callback to reject protocol offloads that are not compatible with your hardware. + +Syntax +------ + +```cpp +EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD EvtNetAdapterPreviewProtocolOffload; + +NTSTATUS EvtNetAdapterPreviewProtocolOffload( + _In_ NETADAPTER                    Adapter, + _In_ NETPOWERSETTINGS              ExistingPowerSettings, + _In_ NDIS_PM_PROTOCOL_OFFLOAD_TYPE ProtocolOffloadType, + _In_ PNDIS_PM_PROTOCOL_OFFLOAD     ProtocolOffloadToBeAdded +) +{ ... } +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*ExistingPowerSettings* [in] +A handle to the net power settings object. + +*ProtocolOffloadType* [in] +An [**NDIS_PM_PROTOCOL_OFFLOAD_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff566765) enumeration value that specifies the type of protocol offload. + +*ProtocolOffloadToBeAdded* [in] +A pointer to a structure of type [**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) that specifies the protocol offload to accept or reject. + +Return value +------------ + +To accept the pattern, the callback function must return STATUS_SUCCESS. + +To reject the pattern, return STATUS_NDIS_PM_PROTOCOL_OFFLOAD_LIST_FULL. + + +Remarks +------- + +Drivers are not required to implement EvtNetAdapterPreviewProtocolOffload, as NetAdapter already blocks protocol offloads that are not compatible with the driver's [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md). However, if your hardware has additional limitations that cannot be expressed in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure, you can provide EvtNetAdapterPreviewProtocolOffload to enforce those additional limitations. + +Register your implementation of this callback function by setting the appropriate member of [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) and then calling [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) during [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md). + +In this callback, the driver typically iterates through the *ExistingPowerSettings* to determine whether to accept or reject *ProtocolOffloadToBeAdded*. + +The client driver can use the pointer to examine the [**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure, but should not retain it. NetAdapterCx will destroy the protocol offload structure once the driver's EvtNetAdapterPreviewProtocolOffload returns. + +For more info, see [Configuring Power Management](configuring-power-management.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-adapter-preview-wake-pattern.md b/windows-driver-docs-pr/netcx/evt-net-adapter-preview-wake-pattern.md new file mode 100644 index 0000000000..4958c75fa0 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-adapter-preview-wake-pattern.md @@ -0,0 +1,117 @@ +--- +title: EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN callback function +topic_type: +- apiref +api_name: +- PFN_NET_ADAPTER_PREVIEW_WAKE_PATTERN +api_location: +- netadapter.h +api_type: +- UserDefined +--- + +# EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implement this optional callback to reject wake patterns that are not compatible with your hardware. + +Syntax +------ + +```cpp +EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN EvtNetAdapterPreviewWakePattern; + +NTSTATUS EvtNetAdapterPreviewWakePattern( + _In_ NETADAPTER           Adapter, + _In_ NETPOWERSETTINGS     ExistingPowerSettings, + _In_ NDIS_PM_WOL_PACKET   WakePatternType, + _In_ PNDIS_PM_WOL_PATTERN PatternToBeAdded +) +{ ... } +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*ExistingPowerSettings* [in] +A handle to the net power settings object. + +*WakePatternType* [in] +An [**NDIS_PM_WOL_PACKET**](https://msdn.microsoft.com/library/windows/hardware/ff566766) enumeration value that specifies the type of the WOL packet. + +*PatternToBeAdded* [in] +A pointer to a structure of type [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) that specifies the wake-on-LAN (WOL) pattern to accept or reject. + +Return value +------------ + +To accept the pattern, the callback function must return STATUS_SUCCESS. + +To reject the pattern, return STATUS_NDIS_PM_WOL_PATTERN_LIST_FULL. + +Remarks +------- + +Drivers are not required to implement EvtNetAdapterPreviewWakePattern, as NetAdapter already blocks wake patterns that are not compatible with the driver's [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md). However, if your hardware has additional limitations that cannot be expressed in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure, you can provide EvtNetAdapterPreviewWakePattern to enforce those additional limitations. + +Register your implementation of this callback function by setting the appropriate member of [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) and then calling [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) during [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md). + +In this callback, the driver typically uses the NETPOWERSETTINGS handle it receives in the *ExistingPowerSettings* parameter to iterate through the enabled wake patterns to determine whether to accept or reject *PatternToBeAdded*. For an example, see [Configuring Power Management](configuring-power-management.md). + +The client driver can use the pointer to examine the [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure, but should not retain it. NetAdapterCx will destroy the wake pattern structure once the driver's EvtNetAdapterPreviewWakePattern returns. + +In its [*EvtDeviceArmWakeFromS0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) and [*EvtDeviceArmWakeFromSx*](https://msdn.microsoft.com/library/windows/hardware/ff540844) callback functions, the driver can iterate through the enabled wake patterns and protocol offloads to program them into the hardware. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-adapter-set-capabilities.md b/windows-driver-docs-pr/netcx/evt-net-adapter-set-capabilities.md new file mode 100644 index 0000000000..5fe273e544 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-adapter-set-capabilities.md @@ -0,0 +1,116 @@ +--- +title: EVT_NET_ADAPTER_SET_CAPABILITIES callback function +topic_type: +- apiref +api_name: +- PFN_NET_ADAPTER_SET_CAPABILITIES +api_location: +- netadapter.h +api_type: +- UserDefined +--- + +# EVT_NET_ADAPTER_SET_CAPABILITIES callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver's implementation of the *EVT_NET_ADAPTER_SET_CAPABILITIES* event callback function that sets the capabilities of the network adapter. + +Syntax +------ + +```cpp +EVT_NET_ADAPTER_SET_CAPABILITIES EvtNetAdapterSetCapabilities; + +NTSTATUS EvtNetAdapterSetCapabilities( + _In_ NETADAPTER Adapter +) +{ ... } +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. + +If this function returns an [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code, the device fails to initialize. + +Remarks +------- + +To register an *EVT_NET_ADAPTER_SET_CAPABILITIES* callback function, the client driver must call [**NetAdapterCreate**](netadaptercreate.md). + +NetAdapterCx calls *EVT_NET_ADAPTER_SET_CAPABILITIES* after [*EVT_WDF_DEVICE_PREPARE_HARDWARE*](https://msdn.microsoft.com/library/windows/hardware/ff540880) but before [*EVT_WDF_DEVICE_D0_ENTRY*](https://msdn.microsoft.com/library/windows/hardware/ff540848). + +NetAdapterCx calls *EVT_NET_ADAPTER_SET_CAPABILITIES* once per device start. + +In this function, the client typically sets the adapter's link and MAC capabilities, power capabilities and MTU size. To do so, it uses the following methods: + +* [**NetAdapterSetLinkLayerMtuSize**](netadaptersetlinklayermtusize.md) +* [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) +* [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +Optionally the client can also call: + +* [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md) +* [**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) + +To set an attribute that does not have equivalent NetAdapter functionality, for example to report offload capabilities, call [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) from [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md). Use [**NetAdapterWdmGetNdisHandle**](netadapterwdmgetndishandle.md) to get the NDIS handle. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) + +[**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-default-method.md b/windows-driver-docs-pr/netcx/evt-net-request-default-method.md new file mode 100644 index 0000000000..2e179629bc --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-default-method.md @@ -0,0 +1,111 @@ +--- +title: EVT_NET_REQUEST_DEFAULT_METHOD callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_DEFAULT_METHOD +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_DEFAULT_METHOD callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver as the default handler for object identifier (OID) requests of type method. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_DEFAULT_METHOD EvtNetRequestDefaultMethod; + +VOID EvtNetRequestDefaultMethod( + _In_  NETREQUESTQUEUE RequestQueue, + _In_  NETREQUEST      Request, + _In_  NDIS_OID        Oid, + _Out_ PVOID           InputOutputBuffer, + _In_  UINT            InputBufferLength, + _In_  UINT            OutputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_DEFAULT_METHOD PFN_NET_REQUEST_DEFAULT_METHOD; +``` + +Register your implementation of this callback function by setting the appropriate member of [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) and then calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a network request object. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*InputOutputBuffer* [out] +A pointer to a buffer into which the client driver or NetAdapterCx returns information for the specified request. + +*InputBufferLength* [in] +The length, in bytes, of the request's input buffer, if an input buffer is available. + +*OutputBufferLength* [in] +The length, in bytes, of the request's output buffer, if an output buffer is available. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +--- +To register an *EVT_NET_REQUEST_DEFAULT_METHOD* callback function, the client driver calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +NetAdapterCx calls the client driver's *EVT_NET_REQUEST_DEFAULT_METHOD* handler when it receives an OID method request for which the client driver has not provided a specialized *EVT_NET_REQUEST_METHOD* handler. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-default-query-data.md b/windows-driver-docs-pr/netcx/evt-net-request-default-query-data.md new file mode 100644 index 0000000000..900ec2e7ed --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-default-query-data.md @@ -0,0 +1,108 @@ +--- +title: EVT_NET_REQUEST_DEFAULT_QUERY_DATA callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_DEFAULT_QUERY_DATA +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_DEFAULT_QUERY_DATA callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver as the default handler for object identifier (OID) requests of type query data. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_DEFAULT_QUERY_DATA EvtNetRequestDefaultQueryData; + +void EvtNetRequestDefaultQueryData( + _In_  NETREQUESTQUEUE RequestQueue, + _In_  NETREQUEST      Request, + _In_  NDIS_OID        Oid, + _Out_ PVOID           OutputBuffer, + _In_  UINT            OutputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_DEFAULT_QUERY_DATA PFN_NET_REQUEST_DEFAULT_QUERY_DATA; +``` + +Register your implementation of this callback function by setting the appropriate member of [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) and then calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a network request object. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*OutputBuffer* [out] +A pointer to a caller-supplied buffer. + +*OutputBufferLength* [in] +The length, in bytes, of the request's output buffer, if an output buffer is available. + +Return value +------------ + +This callback function does not return a value. + +Remarks +--- +To register an *EVT_NET_REQUEST_DEFAULT_QUERY_DATA* callback function, the client driver calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +NetAdapterCx calls the client driver's *EVT_NET_REQUEST_DEFAULT_QUERY_DATA* handler when it receives an OID query data request for which the client driver has not provided a specialized *EVT_NET_REQUEST_QUERY_DATA* handler. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-default-set-data.md b/windows-driver-docs-pr/netcx/evt-net-request-default-set-data.md new file mode 100644 index 0000000000..7f5aa4c7ea --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-default-set-data.md @@ -0,0 +1,108 @@ +--- +title: EVT_NET_REQUEST_DEFAULT_SET_DATA callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_DEFAULT_SET_DATA +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_DEFAULT_SET_DATA callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver as the default handler for object identifier (OID) requests of type set data. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_DEFAULT_SET_DATA EvtNetRequestDefaultSetData; + +VOID EvtNetRequestDefaultSetData( + _In_ NETREQUESTQUEUE RequestQueue, + _In_ NETREQUEST      Request, + _In_ NDIS_OID        Oid, + _In_ PVOID           InputBuffer, + _In_ UINT            InputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_DEFAULT_SET_DATA PFN_NET_REQUEST_DEFAULT_SET_DATA; +``` + +Register your implementation of this callback function by setting the appropriate member of [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) and then calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a net request object. + +*Oid* [in] +Specifies the object identifier of the requested operation. The value is an OID_XXX code. + +*InputBuffer* [in] +A pointer to a caller-supplied buffer. + +*InputBufferLength* [in] +The size of the buffer pointed to by *InputBuffer*. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +--- +To register an *EVT_NET_REQUEST_DEFAULT_SET_DATA* callback function, the client driver calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +NetAdapterCx calls the client driver's *EVT_NET_REQUEST_DEFAULT_SET_DATA* handler when it receives an OID set data request for which the client driver has not provided a specialized *EVT_NET_REQUEST_SET_DATA* handler. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-default.md b/windows-driver-docs-pr/netcx/evt-net-request-default.md new file mode 100644 index 0000000000..93a3c44edf --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-default.md @@ -0,0 +1,92 @@ +--- +title: EVT_NET_REQUEST_DEFAULT callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_DEFAULT +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_DEFAULT callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver as the default handler for object identifier (OID) requests that are not query, set, or method requests. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_DEFAULT EvtNetRequestDefault; + +void EvtNetRequestDefault( + _In_    NETREQUESTQUEUE   RequestQueue, + _In_    NETREQUEST        Request, + _In_    NDIS_REQUEST_TYPE RequestType, + _In_    NDIS_OID          Oid, + _Inout_ PVOID             InputOutputBuffer, + _In_    UINT              InputBufferLength, + _In_    UINT              OutputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_DEFAULT PFN_NET_REQUEST_DEFAULT; +``` + +Register your implementation of this callback function by setting the appropriate member of [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) and then calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Parameters +---------- + +*RequestQueue* [in] +A handle to the net request queue object that is associated with the I/O request. + +*Request* [in] +A handle to a network request object. + +*RequestType* [in] +The request type as one of the [**NDIS_REQUEST_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff567250) enumeration values. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*InputOutputBuffer* [in, out] +A pointer to a buffer into which the client driver or NetAdapterCx returns information for the specified request. + +*InputBufferLength* [in] +The length, in bytes, of the request's input buffer, if an input buffer is available. + +*OutputBufferLength* [in] +The length, in bytes, of the request's output buffer, if an output buffer is available. + +Return value +------------ + +This callback function does not return a value. + +Remarks +------- + +To register an *EVT_NET_REQUEST_DEFAULT* callback function, the client driver calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +If NDIS_REQUEST_TYPE is not query, set, or method, NetAdapterCx calls the client driver's EVT_NET_REQUEST_DEFAULT handler with the request. If the client driver has not provided this callback, the request fails. + +The contents of the *InputOutputBuffer*, *InputBufferLength*, and *OutputBufferLength* parameters are specific to NDIS_REQUEST_TYPE. + +Requirements +------------ +_Target platform: Universal_ +_Minimum KMDF version: 1.21_ +_Minimum NetAdapterCx version: 1.0_ +_Header: Netrequestqueue.h_ +_IRQL: PASSIVE_LEVEL_ + +## See also + +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +[**NDIS_OID_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) diff --git a/windows-driver-docs-pr/netcx/evt-net-request-method.md b/windows-driver-docs-pr/netcx/evt-net-request-method.md new file mode 100644 index 0000000000..af268056be --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-method.md @@ -0,0 +1,105 @@ +--- +title: EVT_NET_REQUEST_METHOD callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_METHOD +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_METHOD callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to handle a specific OID method request. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_METHOD EvtNetRequestMethod; + +VOID EvtNetRequestMethod( + _In_  NETREQUESTQUEUE RequestQueue, + _In_  NETREQUEST      Request, + _Out_ PVOID           InputOutputBuffer, + _In_  UINT            InputBufferLength, + _In_  UINT            OutputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_METHOD PFN_NET_REQUEST_METHOD; +``` + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a network request object. + +*InputOutputBuffer* [out] +A pointer to a buffer into which the client driver or NetAdapterCx returns information for the specified request. + +*InputBufferLength* [in] +The length, in bytes, of the request's input buffer, if an input buffer is available. + +*OutputBufferLength* [in] +The length, in bytes, of the request's output buffer, if an output buffer is available. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +--- +Your client driver can provide one or more specialized handlers for specific OID method requests. In addition, it can also provide a generic *EVT_NET_REQUEST_DEFAULT_METHOD* callback function. + +To register an *EVT_NET_REQUEST_DEFAULT_METHOD* callback function, the client driver calls **NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER** or [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER**](net-request-queue-config-add-initialized-method-handler.md), and then calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-query-data.md b/windows-driver-docs-pr/netcx/evt-net-request-query-data.md new file mode 100644 index 0000000000..dba5fbe7b1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-query-data.md @@ -0,0 +1,102 @@ +--- +title: EVT_NET_REQUEST_QUERY_DATA callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_QUERY_DATA +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_QUERY_DATA callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to handle a specific OID query data request. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_QUERY_DATA EvtNetRequestQueryData; + +VOID EvtNetRequestQueryData( + _In_  NETREQUESTQUEUE RequestQueue, + _In_  NETREQUEST      Request, + _Out_ PVOID           OutputBuffer, + _In_  UINT            OutputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_QUERY_DATA PFN_NET_REQUEST_QUERY_DATA; +``` + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a network request object. + +*OutputBuffer* [out] +A pointer to a caller-supplied buffer. + +*OutputBufferLength* [in] +The length, in bytes, of the request's output buffer, if an output buffer is available. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +--- +Your client driver can provide one or more specialized handlers for specific OID query data requests. In addition, it can also provide a generic *EVT_NET_REQUEST_DEFAULT_QUERY_DATA* callback function. + +To register an *EVT_NET_REQUEST_DEFAULT_QUERY_DATA* callback function, the client driver calls **NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER** or [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER**](net-request-queue-config-add-initialized-query-data-handler.md), and then calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-net-request-set-data.md b/windows-driver-docs-pr/netcx/evt-net-request-set-data.md new file mode 100644 index 0000000000..303de47519 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-net-request-set-data.md @@ -0,0 +1,102 @@ +--- +title: EVT_NET_REQUEST_SET_DATA callback function +topic_type: +- apiref +api_name: +- PFN_NET_REQUEST_SET_DATA +api_location: +- netrequestqueue.h +api_type: +- UserDefined +--- + +# EVT_NET_REQUEST_SET_DATA callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to handle a specific OID set data request. + +Syntax +------ + +```cpp +EVT_NET_REQUEST_SET_DATA EvtNetRequestSetData; + +void EvtNetRequestSetData( + _In_ NETREQUESTQUEUE RequestQueue, + _In_ NETREQUEST      Request, + _In_ PVOID           InputBuffer, + _In_ UINT            InputBufferLength +) +{ ... } + +typedef EVT_NET_REQUEST_SET_DATA PFN_NET_REQUEST_SET_DATA; +``` + +Parameters +---------- + +*RequestQueue* [in] +A handle to a net request queue object. + +*Request* [in] +A handle to a network request object. + +*InputBuffer* [in] +A pointer to a caller-supplied buffer. + +*InputBufferLength* [in] +The length, in bytes, of the request's input buffer, if an input buffer is available. + +Return value +------------ + +This callback function does not return a value. + +Remarks +--- +Your client driver can provide one or more specialized handlers for specific OID query data requests. In addition, it can also provide a generic *EVT_NET_REQUEST_DEFAULT_SET_DATA* callback function. + +To register an *EVT_NET_REQUEST_DEFAULT_SET_DATA* callback function, the client driver calls **NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER** or [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_SET_DATA_HANDLER**](net-request-queue-config-add-initialized-set-data-handler.md), and then calls [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-rxqueue-advance.md b/windows-driver-docs-pr/netcx/evt-rxqueue-advance.md new file mode 100644 index 0000000000..eb0cc80897 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-rxqueue-advance.md @@ -0,0 +1,173 @@ +--- +title: EVT_RXQUEUE_ADVANCE callback function +topic_type: +- apiref +api_name: +- PFN_RXQUEUE_ADVANCE +api_location: +- netrxqueue.h +api_type: +- UserDefined +--- + +# EVT_RXQUEUE_ADVANCE callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to process receive packets provided by NetAdapterCx. + +Syntax +------ + +```cpp +EVT_RXQUEUE_ADVANCE EvtRxqueueAdvance; + +void EvtRxqueueAdvance( + _In_ NETRXQUEUE RxQueue +) +{ ... } + +typedef EVT_RXQUEUE_ADVANCE PFN_RXQUEUE_ADVANCE; +``` + +Register this callback function in [**NET_RXQUEUE_CONFIG_INIT**](net-rxqueue-config-init.md) before calling [**NetRxQueueCreate**](netrxqueuecreate.md). + +Parameters +---------- + +*RxQueue* [in] +A handle to a net receive queue. + +Return value +------------ + +This callback function does not return a value. + +Remarks +------- + +In this callback function, the client driver typically performs the following steps: + +1. Call [**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md) to retrieve the ring buffer handle associated with the receive queue. +2. Program packets returned by the OS to hardware. The window includes packets starting from **NextIndex** up until **EndIndex**. + 1. Iterate until **NextIndex** matches **EndIndex**, or the hardware stops accepting new descriptors. + 2. Call [**NetRingBufferGetPacketAtIndex**](netringbuffergetpacketatindex.md) to retrieve the packet at **NextIndex**. + 3. Free any resources associated with the packet that may have been allocated the last time the descriptor was handed to the OS. + 4. Program the packet to the associated hardware receive queue. + 5. Call [**NetRingBufferIncrementIndex**](NetRingBufferIncrementIndex.md) to advance **NextIndex**. This routine handles ring buffer wrap around. + + ```cpp + VOID + EvtRxQueueAdvance(NETRXQUEUE RxQueue) + { + // optional: retrieve queue's WDF context + MY_RX_QUEUE_CONTEXT *rxContext = GetRxQueueContext(RxQueue); + + // tip: store a reference to RingBuffer in the receive context to reduce + // calls out of driver. + NET_RING_BUFFER *ringBuffer = NetRxQueueGetRingBuffer(RxQueue); + + // move returned packet descriptors back to the hardware queue + while (ringBuffer->NextIndex != ringBuffer->EndIndex) + { + NET_PACKET *netPacket = + NetRingBufferGetPacketAtIndex(ringBuffer, ringBuffer->NextIndex); + + // optional: retrieve queue's packet context + MY_RX_PACKET_CONTEXT *packetContext = GetRxPacketContext(netPacket); + + // free resources associated with the packet + ... + + // program netPacket to hardware + ... + + // return the packet to the available descriptor queue + RingBuffer->NextIndex = + NetRingBufferIncrementIndex(ringBuffer, ringBuffer->NextIndex); + } + + // Indicate received packets (see below) + ... + } + ``` + +3. Return completed packets to the OS by incrementing **BeginIndex**. If the driver completes packets asynchronously in software (e.g. a USB bus completes receive requests asynchronously), use the **Completed** flag on the packet's [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) to track completion. + + ```cpp + while (ringBuffer->BeginIndex != ringBuffer->NextIndex) + { + NET_PACKET *netPacket = + NetRingBufferGetPacketAtIndex(ringBuffer, ringBuffer->BeginIndex); + + // optional: retrieve queue's packet context + MY_RX_PACKET_CONTEXT *packetContext = GetRxPacketContext(netPacket); + + // Optional: When an asynchronous send operation completes, update the + // Completed flag on the packet. In the Advance callback, return each + // packet starting at BeginIndex until a packet not marked as Completed + // is reached, or EndIndex is reached. Packets must be returned + // sequentially, so indication must stop as soon as the first + // non-Completed packet is reached. + // + // The Completed flag is not used by the OS, so the device is free to + // use this flag. + if (!netPacket->Data.Completed) + break; + + RingBuffer->BeginIndex = + NetRingBufferIncrementIndex(RingBuffer, RingBuffer->BeginIndex); + } + ``` + +NetAdapterCx serializes this callback function along with the receive queue's [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md) and [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) callback functions. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetRxQueue.h

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-rxqueue-cancel.md b/windows-driver-docs-pr/netcx/evt-rxqueue-cancel.md new file mode 100644 index 0000000000..ed96012bb4 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-rxqueue-cancel.md @@ -0,0 +1,101 @@ +--- +title: EVT_RXQUEUE_CANCEL callback function +topic_type: +- apiref +api_name: +- PFN_RXQUEUE_CANCEL +api_location: +- netrxqueue.h +api_type: +- UserDefined +--- + +# EVT_RXQUEUE_CANCEL callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to handle operations that must be performed before a receive queue is deleted. + +Syntax +------ + +```cpp +EVT_RXQUEUE_CANCEL EvtRxQueueCancel; + +void EvtRxQueueCancel( + _In_ NETRXQUEUE RxQueue +) +{ ... } + +typedef EVT_RXQUEUE_CANCEL PFN_RXQUEUE_CANCEL; +``` + +Register this callback function in [**NET_RXQUEUE_CONFIG_INIT**](net-rxqueue-config-init.md) before calling [**NetRxQueueCreate**](netrxqueuecreate.md). + +Parameters +---------- + +*RxQueue* [in] +A handle to a net receive queue. + +Return value +------------ + +This callback function does not return a value. + +Example +----- + +In its *EVT_RXQUEUE_CANCEL* callback function, the client must complete any outstanding receive packets. If the client does not return all packets, the operating system does not delete the queue, and NetAdapterCx stops calling the client's callbacks for the queue. To return packets, the client advances the ring buffer's **BeginIndex** and **NextIndex** indices to **EndIndex**. + +```cpp +VOID +EvtRxQueueCancel(NETRXQUEUE RxQueue) +{ + NET_RING_BUFFER *ringBuffer = NetRxQueueGetRingBuffer(RxQueue); + + ringBuffer->BeginIndex = ringBuffer->NextIndex = ringBuffer->EndIndex; +} +``` + +For additional example code demonstrating ring buffer usage, see [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md). + +Remarks +------- + +NetAdapterCx serializes this callback function along with the receive queue's [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) and [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) callback functions. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h

IRQL

PASSIVE_LEVEL

diff --git a/windows-driver-docs-pr/netcx/evt-rxqueue-set-notification-enabled.md b/windows-driver-docs-pr/netcx/evt-rxqueue-set-notification-enabled.md new file mode 100644 index 0000000000..580350297b --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-rxqueue-set-notification-enabled.md @@ -0,0 +1,164 @@ +--- +title: EVT_RXQUEUE_SET_NOTIFICATION_ENABLED callback function +topic_type: +- apiref +api_name: +- PFN_RXQUEUE_SET_NOTIFICATION_ENABLED +api_location: +- netrxqueue.h +api_type: +- UserDefined +--- + +# EVT_RXQUEUE_SET_NOTIFICATION_ENABLED callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to enable receive queue notification for the associated device. + +Syntax +------ + +```cpp +EVT_RXQUEUE_SET_NOTIFICATION_ENABLED EvtRxqueueSetNotificationEnabled; + +NTSTATUS EvtRxqueueSetNotificationEnabled( + _In_ NETRXQUEUE RxQueue, + _In_ BOOLEAN    NotificationEnabled +) +{ ... } + +typedef EVT_RXQUEUE_SET_NOTIFICATION_ENABLED PFN_RXQUEUE_SET_NOTIFICATION_ENABLED; +``` + +Register this callback function in [**NET_RXQUEUE_CONFIG_INIT**](net-rxqueue-config-init.md) before calling [**NetRxQueueCreate**](netrxqueuecreate.md). + +Parameters +---------- + +*RxQueue* [in] +A handle to a net receive queue. + +*NotificationEnabled* [in] +A value of **TRUE** requests that the client enable receive queue notification. A value of **FALSE** requests that the client disable receive queue notification. + +Return value +------------ + +If the operation is successful, the callback function returns STATUS_SUCCESS. Otherwise, return an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +------- + +For a PCI NIC, enabling receive queue notification typically means enabling the receive queue's hardware interrupt. When the hardware interrupt fires, the client calls [**NetRxQueueNotifyMoreReceivedPacketsAvailable**](netrxqueuenotifymorereceivedpacketsavailable.md) from its DPC. + +For example: +```cpp +NTSTATUS +EvtRxQueueSetNotificationEnabled( + _In_ NETRXQUEUE rxQueue, + _In_ BOOLEAN notificationEnabled) +{ + // optional: retrieve queue's WDF context + MY_RX_QUEUE_CONTEXT *rxContext = GetRxQueueContext(RxQueue); + + // If notificationEnabled is TRUE, enable receive queue's hardware interrupt + ... +} + +void +EvtInterruptDpc( + _In_ WDFINTERRUPT interrupt, + _In_ WDFOBJECT associatedObject) +{ + MY_INTERRUPT_CONTEXT *interruptContext = GetInterruptContext(interrupt); + + NetRxQueueNotifyMoreReceivedPacketsAvailable(interruptContext->RxQueue); +} +``` + +For a USB device, or any other queue with a software receive completion mechanism, the client driver should track in its own context whether the queue's notification is enabled. From the completion routine (triggered for example when a message becomes available in the USB continuous reader), call [**NetRxQueueNotifyMoreReceivedPacketsAvailable**](netrxqueuenotifymorereceivedpacketsavailable.md) if the notification is enabled. The following example shows how you might do this. + +```cpp +VOID +UsbEvtReaderCompletionRoutine( + _In_ WDFUSBPIPE pipe, + _In_ WDFMEMORY buffer, + _In_ size_t numBytesTransferred, + _In_ WDFCONTEXT context) +{ + UNREFERENCED_PARAMETER(pipe); + + PUSB_RCB_POOL pRcbPool = *((PUSB_RCB_POOL*) context); + PUSB_RCB pRcb = (PUSB_RCB) WdfMemoryGetBuffer(buffer, NULL); + + pRcb->DataOffsetCurrent = 0; + pRcb->DataWdfMemory = buffer; + pRcb->DataValidSize = numBytesTransferred; + + WdfObjectReference(pRcb->DataWdfMemory); + + ExInterlockedInsertTailList(&pRcbPool->ListHead, + &pRcb->Link, + &pRcbPool->ListSpinLock); + + if (InterlockedExchange(&pRcbPool->NotificationEnabled, FALSE) == TRUE) + { + NetRxQueueNotifyMoreReceivedPacketsAvailable(pRcbPool->RxQueue); + } + +} +``` + +NetAdapterCx serializes this callback function along with the receive queue's [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) and [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md) callback functions. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) + +[**NetRxQueueNotifyMoreReceivedPacketsAvailable**](netrxqueuenotifymorereceivedpacketsavailable.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-txqueue-advance.md b/windows-driver-docs-pr/netcx/evt-txqueue-advance.md new file mode 100644 index 0000000000..fae44c14f8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-txqueue-advance.md @@ -0,0 +1,128 @@ +--- +title: EVT_TXQUEUE_ADVANCE callback function +topic_type: +- apiref +api_name: +- PFN_TXQUEUE_ADVANCE +api_location: +- nettxqueue.h +api_type: +- UserDefined +--- + +# EVT_TXQUEUE_ADVANCE callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to process transmit packets provided by NetAdapterCx. + +Syntax +------ + +```cpp +EVT_TXQUEUE_ADVANCE EvtTxQueueAdvance; + +void EvtTxQueueAdvance( + _In_ NETTXQUEUE TxQueue +) +{ ... } + +typedef EVT_TXQUEUE_ADVANCE PFN_TXQUEUE_ADVANCE; +``` + +Register this callback function in [**NET_TXQUEUE_CONFIG_INIT**](net-txqueue-config-init.md) before calling [**NetTxQueueCreate**](nettxqueuecreate.md). + +Parameters +---------- + +*TxQueue* [in] +A handle to a net transmit queue. + +Return value +------------ + +This callback function does not return a value. + +Remarks +------- +In this callback, the client retrieves packets from the queue, programs the hardware to send the data, and returns any completed packets. + +To return packets, call [**NetRingBufferIncrementIndex**](NetRingBufferIncrementIndex.md), or use a helper macro such as [**NetRingBufferReturnCompletedPackets method**](netringbufferreturncompletedpackets.md). + +The following example retrieves incoming transmit packets from the queue and immediately completes them. + +```cpp +VOID +EvtTxQueueAdvance(NETTXQUEUE TxQueue) +{ + NET_RING_BUFFER *ringBuffer = NetTxQueueGetRingBuffer(TxQueue); + NET_PACKET *netPacket; + + // Retrieve pointer to packet at the NextIndex value of the ring buffer + + while ((netPacket = NetRingBufferGetNextPacket(ringBuffer)) != nullptr) + { + + // Transmit the data + + netPacket->Data.Completed = TRUE; + + // Increment NextIndex + + NetRingBufferAdvanceNextPacket(ringBuffer); + } + + NetRingBufferReturnCompletedPackets(ringBuffer); +} +``` + +NetAdapterCx serializes this callback function along with the queue's [*EVT_TXQUEUE_CANCEL*](evt-txqueue-cancel.md) and [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) callback functions. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetTxQueue.h

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NetTxQueueGetRingBuffer**](nettxqueuegetringbuffer.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-txqueue-cancel.md b/windows-driver-docs-pr/netcx/evt-txqueue-cancel.md new file mode 100644 index 0000000000..80c7fcd76c --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-txqueue-cancel.md @@ -0,0 +1,96 @@ +--- +title: EVT_TXQUEUE_CANCEL callback function +topic_type: +- apiref +api_name: +- PFN_TXQUEUE_CANCEL +api_location: +- nettxqueue.h +api_type: +- UserDefined +--- + +# EVT_TXQUEUE_CANCEL callback function + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to handle operations that must be performed before a transmit queue is deleted. + +Syntax +------ + +```cpp +EVT_TXQUEUE_CANCEL EvtTxqueueCancel; + +void EvtTxQueueCancel( + _In_ NETTXQUEUE TxQueue +) +{ ... } + +typedef EVT_TXQUEUE_CANCEL PFN_TXQUEUE_CANCEL; +``` + +Register this callback function in [**NET_TXQUEUE_CONFIG_INIT**](net-txqueue-config-init.md) before calling [**NetTxQueueCreate**](nettxqueuecreate.md). + +Parameters +---------- + +*TxQueue* [in] +A handle to a net transmit queue. + +Return value +------------ + +This callback function does not return a value. + +Remarks +------- + +In its *EVT_TXQUEUE_CANCEL* callback function, the client has an opportunity to complete any outstanding transmit packets. Unlike with [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md), the client is not required to do so. If the client leaves outstanding packets, NetAdapterCx calls the client's [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md), where the client processes them as part of its regular operation. + +If the hardware supports cancelling in-flight transmits, the client should also advance the ring buffer's **BeginIndex** past all cancelled packets. If the hardware does not support cancellation, this callback can return without taking action. + +NetAdapterCx serializes this callback function along with the receive queue's [*EVT_TXQUEUE_ADVANCE*](evt-rxqueue-advance.md) and [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) callback functions. + +For more info about ring buffer usage, see [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) and [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetTxQueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/evt-txqueue-set-notification-enabled.md b/windows-driver-docs-pr/netcx/evt-txqueue-set-notification-enabled.md new file mode 100644 index 0000000000..a6203b7eb4 --- /dev/null +++ b/windows-driver-docs-pr/netcx/evt-txqueue-set-notification-enabled.md @@ -0,0 +1,139 @@ +--- +title: EVT_TXQUEUE_SET_NOTIFICATION_ENABLED callback function +topic_type: +- apiref +api_name: +- PFN_TXQUEUE_SET_NOTIFICATION_ENABLED +api_location: +- nettxqueue.h +api_type: +- UserDefined +--- + +# EVT_TXQUEUE_SET_NOTIFICATION_ENABLED callback function + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Implemented by the client driver to perform client-specific processing when there are new packets received in the specified queue's ring buffer. + +Syntax +------ + +```cpp +EVT_TXQUEUE_SET_NOTIFICATION_ENABLED EvtTxqueueSetNotificationEnabled; + +NTSTATUS EvtTxqueueSetNotificationEnabled( + _In_ NETTXQUEUE TxQueue, + _In_ BOOLEAN    NotificationEnabled +) +{ ... } + +typedef EVT_TXQUEUE_SET_NOTIFICATION_ENABLED PFN_TXQUEUE_SET_NOTIFICATION_ENABLED; +``` + +Register your implementation of this callback function by setting the appropriate member of [**NET_TXQUEUE_CONFIG**](net-txqueue-config.md) and then calling [**NetTxQueueCreate**](nettxqueuecreate.md). + +Parameters +---------- + +*TxQueue* [in] +A handle to a net transmit queue. + +*NotificationEnabled* [in] +A value of **TRUE** requests that the client enable transmit queue notification. A value of **FALSE** requests that the client disable transmit queue notification. + +Return value +------------ + +If the operation is successful, the callback function must return STATUS_SUCCESS. Otherwise, it should return an appropriate [NTSTATUS](https://msdn.microsoft.com/library/windows/hardware/ff557697) error code. + +Remarks +------- + +For a PCI NIC, enabling transmit queue notification typically means enabling the transmit queue's hardware interrupt. When the hardware interrupt fires, the client calls [**NetTxQueueNotifyMoreCompletedPacketsAvailable**](nettxqueuenotifymorecompletedpacketsavailable.md) from its DPC. + +Similarly, for a PCI NIC, disabling queue notification means disabling the interrupt associated with the queue. + +For a device that has an asynchronous I/O model, the client typically uses an internal flag to track the enabled state. When an asynchronous operation completes, the completion handler checks this flag and calls [**NetTxQueueNotifyMoreCompletedPacketsAvailable**](nettxqueuenotifymorecompletedpacketsavailable.md) if it is set. + +If NetAdapterCx calls *EVT_TXQUEUE_SET_NOTIFICATION_ENABLED* with *NotificationEnabled* set to **FALSE**, the client must not call [**NetTxQueueNotifyMoreCompletedPacketsAvailable**](nettxqueuenotifymorecompletedpacketsavailable.md) until NetAdapterCx next calls this callback function with *NotificationEnabled* set to **TRUE**. + +For example: + +```cpp +NTSTATUS +EvtTxQueueSetNotificationEnabled( + _In_ NETTXQUEUE rxQueue, + _In_ BOOLEAN notificationEnabled) +{ + // optional: retrieve queue's WDF context + MY_TX_QUEUE_CONTEXT *txContext = GetTxQueueContext(TxQueue); + + // If notificationEnabled is TRUE, enable transmit queue's hardware interrupt + ... +} + +void +EvtInterruptDpc( + _In_ WDFINTERRUPT interrupt, + _In_ WDFOBJECT associatedObject) +{ + MY_INTERRUPT_CONTEXT *interruptContext = GetInterruptContext(interrupt); + + NetTxQueueNotifyMoreCompletedPacketsAvailable(interruptContext->TxQueue); +} +``` + +NetAdapterCx serializes this callback function along with the receive queue's [*EVT_TXQUEUE_ADVANCE*](evt-rxqueue-advance.md) and [*EVT_TXQUEUE_CANCEL*](evt-txqueue-cancel.md) callback functions. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetTxQueue.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) + +[**NetTxQueueNotifyMoreCompletedPacketsAvailable**](nettxqueuenotifymorecompletedpacketsavailable.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/handling-control-requests.md b/windows-driver-docs-pr/netcx/handling-control-requests.md new file mode 100644 index 0000000000..39041fcf9d --- /dev/null +++ b/windows-driver-docs-pr/netcx/handling-control-requests.md @@ -0,0 +1,113 @@ +--- +title: Handling Control Requests +--- + +# Handling Control Requests + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +In the NetAdapterCx model, the client driver receives most control requests as NETREQUEST objects, each of which represents an OID (object identifier) request. The client driver typically sets up one or two WDF queues (called NETREQUESTQUEUEs) to manage control requests. + +The NETREQUESTQUEUE object is the parent of each NETREQUEST that it manages. Because the queue is a child of the NETADAPTER object, WDF automatically deletes each queue and any associated requests when the adapter is deleted. + +To see all the default parent child relationships for NetAdapterCx, see [Summary of Objects](summary-of-objects.md). + +## Creating queue objects + +In the NetAdapterCx model, the client can use two types of queues for handling control requests (OIDs): +* Sequential queue for normal requests (OIDs). NetAdapterCx delivers requests to the client one at a time. +* Parallel queue for direct requests (OIDs). NetAdapterCx delivers requests in parallel. + +For more info on these dispatching methods, see [Dispatching Methods for I/O Requests](../wdf/dispatching-methods-for-i-o-requests.md). + +Call these methods to create queues: + +* [**NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL**](net-request-queue-config-init-default-sequential.md) +* [**NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL**](net-request-queue-config-init-default-parallel.md) + +## Registering handlers + +For each of the three main request types (query data, set data, and method), the client driver can provide a single default handler, or one or more OID-specific handlers. + +You can use both approaches in the same driver, providing custom handlers for some OIDs while using a default handler with a switch statement for the remainder. + +A client driver registers OID handlers in its [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) routine. + +Here are the control request handlers the client can provide: + +* [*EVT_NET_REQUEST_METHOD*](evt-net-request-method.md) +* [*EVT_NET_REQUEST_QUERY_DATA*](evt-net-request-query-data.md) +* [*EVT_NET_REQUEST_SET_DATA*](evt-net-request-set-data.md) +* [*EVT_NET_REQUEST_DEFAULT_METHOD*](evt-net-request-default-method.md) +* [*EVT_NET_REQUEST_DEFAULT_QUERY_DATA*](evt-net-request-default-query-data.md) +* [*EVT_NET_REQUEST_DEFAULT_SET_DATA*](evt-net-request-default-set-data.md) + +For each of the three main request types, the OID-specific handlers take precedence over the default handlers. If the client provides neither for a given OID, NetAdapterCx fails the request. + +For requests of type other than query data, set data, and method, the client driver can provide an [*EVT_NET_REQUEST_DEFAULT*](evt-net-request-default.md) event callback function. + +For example, if the protocol driver issues an OID request with `NDIS_REQUEST_TYPE = NdisRequestGeneric1`, NetAdapterCx calls [*EVT_NET_REQUEST_DEFAULT*](evt-net-request-default.md). NetAdapterCx fails the request if the client driver has not provided such a handler. + +The following diagram shows the typical flow: + +Drawing + +The following snippet shows how the client sets up default handlers: + +```cpp +NTSTATUS status; +NET_REQUEST_QUEUE_CONFIG config; +NETREQUESTQUEUE requestQueue; + +NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL(&config, NetAdapter); +config.EvtRequestDefaultQueryData = MyDefaultQueryData; +config.EvtRequestDefaultSetData = MyDefaultSetData; +config.EvtRequestDefaultMethod = MyDefaultMethod; + +config.EvtRequestDefault = MyDefault; +``` + +To add an OID-specific handlers, use these methods: + +* [**NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER**](net-request-queue-config-add-query-data-handler.md) +* [**NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER**](net-request-queue-config-add-set-data-handler.md) +* [**NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER**](net-request-queue-config-add-method-handler.md) + +The following example calls [**NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER**](net-request-queue-config-add-query-data-handler.md) with a pointer to the client's [*EVT_NET_REQUEST_QUERY_DATA*](evt-net-request-query-data.md) event callback function to register a handler for a specific OID: + +```cpp +NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER( + &config, OID_GEN_VENDOR_DESCRIPTION, + EvtQueryGenVendorDescription, sizeof(NIC_VENDOR_DESC)); +``` + +## Creating the queue + +Once you've set up each OID queue the way you like, call [**NetRequestQueueCreate**](netrequestqueuecreate.md) to create the queue: + +```cpp +status = NetRequestQueueCreate(&config, WDF_NO_OBJECT_ATTRIBUTES, NULL); + +if(!NT_SUCCESS(status)) +{ + return status; +} +``` + +NetAdapterCx can call the client driver's control request handlers as soon as [*EVT_WDF_DEVICE_PREPARE_HARDWARE*](https://msdn.microsoft.com/library/windows/hardware/ff540880) returns until the time it calls [*EVT_WDF_DEVICE_RELEASE_HARDWARE*](https://msdn.microsoft.com/library/windows/hardware/ff540890). + +## Completing Requests + +The client driver must complete each NETREQUEST that it receives. Otherwise, the control request is left in a pending state. If the request cannot be handled synchronously, the client driver must complete the pending NETREQUEST at a later time. Failure to complete a pending request can cause the client driver to become unresponsive when the device is powered down. + +If the original request did not contain a large enough buffer, call [**NetRequestSetBytesNeeded**](netrequestsetbytesneeded.md). To complete a control request and specify only completion status, call [**NetRequestCompleteWithoutInformation**](netrequestcompletewithoutinformation.md) from the OID handler, as shown in the following snippet: + +```cpp + NetRequestCompleteWithoutInformation(Request, STATUS_SUCCESS); +``` + +If the original request did contain a large enough buffer, the client driver calls [**NetRequestRetrieveInputOutputBuffer**](NetRequestRetrieveInputOutputBuffer.md) to retrieve the input/output buffer. Then the client transfers the data and completes the request using one of the following, depending on the request type: + +* [**NetRequestMethodComplete**](netrequestmethodcomplete.md) +* [**NetRequestQueryDataComplete**](netrequestquerydatacomplete.md) +* [**NetRequestSetDataComplete**](netrequestsetdatacomplete.md) diff --git a/windows-driver-docs-pr/netcx/images/architecture.PNG b/windows-driver-docs-pr/netcx/images/architecture.PNG new file mode 100644 index 0000000000..3a0c09cb88 Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/architecture.PNG differ diff --git a/windows-driver-docs-pr/netcx/images/netcx-adapter-object-model.png b/windows-driver-docs-pr/netcx/images/netcx-adapter-object-model.png new file mode 100644 index 0000000000..b356565154 Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/netcx-adapter-object-model.png differ diff --git a/windows-driver-docs-pr/netcx/images/netcx-adapter-request-handling-flow.png b/windows-driver-docs-pr/netcx/images/netcx-adapter-request-handling-flow.png new file mode 100644 index 0000000000..c261a23b2b Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/netcx-adapter-request-handling-flow.png differ diff --git a/windows-driver-docs-pr/netcx/images/powerdown.PNG b/windows-driver-docs-pr/netcx/images/powerdown.PNG new file mode 100644 index 0000000000..6e51fee2d0 Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/powerdown.PNG differ diff --git a/windows-driver-docs-pr/netcx/images/powerup.PNG b/windows-driver-docs-pr/netcx/images/powerup.PNG new file mode 100644 index 0000000000..d4e58cb6d8 Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/powerup.PNG differ diff --git a/windows-driver-docs-pr/netcx/images/using-the-ring-buffer.gif b/windows-driver-docs-pr/netcx/images/using-the-ring-buffer.gif new file mode 100644 index 0000000000..e9b5b00109 Binary files /dev/null and b/windows-driver-docs-pr/netcx/images/using-the-ring-buffer.gif differ diff --git a/windows-driver-docs-pr/netcx/index.md b/windows-driver-docs-pr/netcx/index.md new file mode 100644 index 0000000000..0ac77563bc --- /dev/null +++ b/windows-driver-docs-pr/netcx/index.md @@ -0,0 +1,41 @@ +--- +title: Network Adapter WDF Class Extension (Cx) +--- + +# Network Adapter WDF Class Extension (Cx) + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Starting in Windows 10 Creators Update (version 1703), the Windows Driver Kit (WDK) includes a class extension module (NetAdapterCx) that enables you to write a KMDF-based driver (called the client driver in this section) for a Network Interface Controller (NIC). NetAdapterCx gives you the power and flexibility of WDF and the networking performance of NDIS, and makes it easy to write a driver for your NIC. + +In previous versions of Windows, WDF and NDIS had individual advantages, but did not interoperate well. The only way to write a NIC driver was to write an NDIS miniport driver. To use WDF in an NDIS miniport driver, you had to write extra code in your driver, and even then, you only had access to a small subset of WDF functionality. + +With the NetAdapterCx model, conversely, you write a real WDF driver for your NIC. This means that your NetAdapterCx driver has access to full WDF functionality, as well as networking-specific APIs and I/O support from the NetAdapter class extension. As shown in the block diagram below, NetAdapterCx still works behind the scenes with NDIS, but it handles all the interaction with NDIS on your behalf. + +Drawing + +To watch a video that discusses the benefits of using NetAdapterCx, see [Network Adapter Class Extension: Overview](https://aka.ms/netadapter/video1). + +To learn how to port an NDIS 6.x miniport driver into a Windows Driver Framework (WDF) networking client driver, see [Porting NDIS Miniport Drivers to NetAdapter Class Extension](porting-ndis-to-netadapter-cx.md). + +To start working right away with driver samples on GitHub, clone our [NetAdapter-Cx-Driver-Samples](https://github.com/Microsoft/NetAdapter-Cx-Driver-Samples) repo. + +To see the source code for NetAdapterCx itself, or perform step-through debugging, see our [Network-Adapter-Class-Extension](https://github.com/Microsoft/Network-Adapter-Class-Extension) repo on GitHub. + +If you would like to work with Microsoft as you develop a NetAdapterCx client driver, or have feedback on the class extension, please send us an [email](mailto:netadapter@microsoft.com). + +To watch a video that discusses the future roadmap and collaboration opportunities, see [Network Adapter Class Extension: Roadmap and Collaboration](https://aka.ms/netadapter/video4). + +This section contains the following topics: + +* [Porting NDIS Miniport Drivers to NetAdapter Class Extension](porting-ndis-to-netadapter-cx.md) +* [Building a NetAdapterCx Client Driver](building-a-netadaptercx-client-driver.md) +* [Device Initialization](device-initialization.md) +* [Accessing Configuration Information](accessing-configuration-information.md) +* [Transferring Network Data](transferring-network-data.md) +* [Handling Control Requests](handling-control-requests.md) +* [Debugging NetAdapterCx Client Drivers](debugging-netadaptercx-client-drivers.md) +* [Configuring Power Management](configuring-power-management.md) +* [Summary of Objects](summary-of-objects.md) +* [Power-Up Sequence for an Network Adapter WDF Client Driver](power-up-sequence-for-ndis-wdf-client-driver.md) +* [Power-Down Sequence for an Network Adapter WDF Client Driver](power-down-sequence-for-ndis-wdf-client-driver.md) diff --git a/windows-driver-docs-pr/netcx/ndis-wdf-function-equivalents.md b/windows-driver-docs-pr/netcx/ndis-wdf-function-equivalents.md new file mode 100644 index 0000000000..a65cd4359f --- /dev/null +++ b/windows-driver-docs-pr/netcx/ndis-wdf-function-equivalents.md @@ -0,0 +1,21 @@ +--- +title: NDIS-WDF Function Equivalents +--- + +# NDIS-WDF Function Equivalents + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The following table lists NDIS functions and their WDF equivalents: + +|NDIS API Family|WDF Equivalent| +|-|-| +|[**NdisAllocateIoWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff561604)|[**WdfWorkItemCreate**](https://msdn.microsoft.com/library/windows/hardware/ff551201)| +|[**NdisAllocateTimerObject**](https://msdn.microsoft.com/library/windows/hardware/ff561618)|[**WdfTimerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff550050)| +|[**NdisAcquireSpinLock**](https://msdn.microsoft.com/library/windows/hardware/ff560699)|[**WdfSpinLockAcquire**](https://msdn.microsoft.com/library/windows/hardware/ff550040)| +|[**NdisInterlockedIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff562752)|[**InterlockedIncrement**](https://msdn.microsoft.com/library/windows/hardware/ff547910)| +|[**NdisInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff562732)|[**KeInitializeEvent**](https://msdn.microsoft.com/library/windows/hardware/ff552137)| +|[**NdisMInitializeScatterGatherDma**](https://msdn.microsoft.com/library/windows/hardware/ff553543)|[**WdfDmaEnablerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff546983)| +|[**NdisInitializeString**](https://msdn.microsoft.com/library/windows/hardware/ff562741)|[**WdfStringCreate**](https://msdn.microsoft.com/library/windows/hardware/ff550046)| +|[**NdisSystemActiveProcessorCount**](https://msdn.microsoft.com/library/windows/hardware/ff564577)|[**KeGetCurrentProcessorNumberEx**](https://msdn.microsoft.com/library/windows/hardware/ff552076) (kernel)| +|[**NdisWriteRegisterUchar**](https://msdn.microsoft.com/library/windows/hardware/ff564678)|[**WDF_WRITE_REGISTER_UCHAR**](https://msdn.microsoft.com/library/windows/hardware/dn265684)| diff --git a/windows-driver-docs-pr/netcx/net-adapter-auto-negotiation-flags.md b/windows-driver-docs-pr/netcx/net-adapter-auto-negotiation-flags.md new file mode 100644 index 0000000000..460798be6c --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-auto-negotiation-flags.md @@ -0,0 +1,78 @@ +--- +title: NET_ADAPTER_AUTO_NEGOTIATION_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_AUTO_NEGOTIATION_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_AUTO_NEGOTIATION_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies the auto-negotiation settings for the NIC driver. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_AUTO_NEGOTIATION_FLAGS { + NET_ADAPTER_AUTO_NEGOTIATION_NO_FLAGS                   = 0, + NET_ADAPTER_LINK_STATE_XMIT_LINK_SPEED_AUTO_NEGOTIATED  = NDIS_LINK_STATE_XMIT_LINK_SPEED_AUTO_NEGOTIATED, + NET_ADAPTER_LINK_STATE_RCV_LINK_SPEED_AUTO_NEGOTIATED   = NDIS_LINK_STATE_RCV_LINK_SPEED_AUTO_NEGOTIATED, + NET_ADAPTER_LINK_STATE_DUPLEX_AUTO_NEGOTIATED           = NDIS_LINK_STATE_DUPLEX_AUTO_NEGOTIATED, + NET_ADAPTER_LINK_STATE_PAUSE_FUNCTIONS_AUTO_NEGOTIATED  = NDIS_LINK_STATE_PAUSE_FUNCTIONS_AUTO_NEGOTIATED +} NET_ADAPTER_AUTO_NEGOTIATION_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_AUTO_NEGOTIATION_NO_FLAGS** +No flags are set. + +**NET_ADAPTER_LINK_STATE_XMIT_LINK_SPEED_AUTO_NEGOTIATED** +The adapter has auto-negotiated the transmit link speed with the link partner. + +**NET_ADAPTER_LINK_STATE_RCV_LINK_SPEED_AUTO_NEGOTIATED** +The adapter has auto-negotiated the receive link speed with the link partner. + +**NET_ADAPTER_LINK_STATE_DUPLEX_AUTO_NEGOTIATED** +The adapter has auto-negotiated the duplex state with the link partner. + +**NET_ADAPTER_LINK_STATE_PAUSE_FUNCTIONS_AUTO_NEGOTIATED** +The adapter has auto-negotiated the pause functions with the link partner. + +Remarks +--- +The **NET_ADAPTER_AUTO_NEGOTIATION_FLAGS** enumeration is used to specify auto-negotiation settings in the [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +An initialized [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure is an input to [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
diff --git a/windows-driver-docs-pr/netcx/net-adapter-config-init.md b/windows-driver-docs-pr/netcx/net-adapter-config-init.md new file mode 100644 index 0000000000..ddf14223d4 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-config-init.md @@ -0,0 +1,92 @@ +--- +title: NET_ADAPTER_CONFIG_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_CONFIG_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_CONFIG_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_ADAPTER_CONFIG](net-adapter-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_CONFIG_INIT( + _Out_ PNET_ADAPTER_CONFIG              AdapterConfig, + _In_  PFN_NET_ADAPTER_SET_CAPABILITIES EvtAdapterSetCapabilities, + _In_  PFN_NET_ADAPTER_CREATE_TXQUEUE   EvtAdapterCreateTxQueue, + _In_  PFN_NET_ADAPTER_CREATE_RXQUEUE   EvtAdapterCreateRxQueue, +); +``` + +Parameters +---------- + +*AdapterConfig* [out] +A pointer to the driver-allocated [**NET_ADAPTER_CONFIG**](net-adapter-config.md) structure. + +*EvtAdapterSetCapabilities* [in] +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) event callback. + +*EvtAdapterCreateTxQueue* [in] +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md) event callback. + +*EvtAdapterCreateRxQueue* [in] +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md) event callback. + +Return value +------------ + +This method does not return a value. + +Remarks +----- + +The client typically calls this method from its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) event callback function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-config.md b/windows-driver-docs-pr/netcx/net-adapter-config.md new file mode 100644 index 0000000000..ab6f690560 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-config.md @@ -0,0 +1,95 @@ +--- +title: NET_ADAPTER_CONFIG structure +topic_type: +- apiref +api_name: +- NET_ADAPTER_CONFIG +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_CONFIG structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the configuration options for a NetAdapterCx client driver. An initialized **NET_ADAPTER_CONFIG** structure is an input parameter to [**NetAdapterCreate**](netadaptercreate.md). + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_CONFIG { + ULONG Size; + NET_ADAPTER_DRIVER_TYPE Type; + PFN_NET_ADAPTER_SET_CAPABILITIES EvtAdapterSetCapabilities; + PFN_NET_ADAPTER_CREATE_TXQUEUE EvtAdapterCreateTxQueue; + PFN_NET_ADAPTER_CREATE_RXQUEUE EvtAdapterCreateRxQueue; + PWDF_OBJECT_ATTRIBUTES NetRequestObjectAttributes; + PWDF_OBJECT_ATTRIBUTES                    NetPowerSettingsObjectAttributes; +} NET_ADAPTER_CONFIG, *PNET_ADAPTER_CONFIG; +``` + +Members +------- + +**Size** +Size of the **NET_ADAPTER_CONFIG** structure. + +**Type** +A [**NET_ADAPTER_DRIVER_TYPE**](net-adapter-driver-type.md)-typed value indicating the type of driver that is creating the NetAdapter object. Currently, the only supported value is **NET_ADAPTER_DRIVER_TYPE_MINIPORT**. + +**EvtAdapterSetCapabilities** +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) event callback. + +**EvtAdapterCreateTxQueue** +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md) event callback. + +**EvtAdapterCreateRxQueue** +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md) event callback. + +**NetRequestObjectAttributes** +Optional WDF object attributes associated with the NETREQUEST objects, or NULL. If non-NULL, all NETREQUESTs created by the framework will have these attributes. + +**NetPowerSettingsObjectAttributes** +Optional WDF object attributes associated with the NETPOWERSETTINGS object, or NULL. + +Remarks +------- + +Call [**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md) to initialize this structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities-init.md b/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities-init.md new file mode 100644 index 0000000000..83baec7289 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities-init.md @@ -0,0 +1,81 @@ +--- +title: NET_ADAPTER_DATAPATH_CAPABILITIES_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_DATAPATH_CAPABILITIES_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_DATAPATH_CAPABILITIES_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [**NET_ADAPTER_DATAPATH_CAPABILITIES**](net-adapter-datapath-capabilities.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_DATAPATH_CAPABILITIES_INIT( + _Out_ PNET_ADAPTER_DATAPATH_CAPABILITIES DataPathCapabilities +); +``` + +Parameters +---------- + +*DataPathCapabilities* [out] +A pointer to the driver-allocated [**NET_ADAPTER_DATAPATH_CAPABILITIES**](net-adapter-datapath-capabilities.md) structure. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities.md b/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities.md new file mode 100644 index 0000000000..b8f063f2c0 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-datapath-capabilities.md @@ -0,0 +1,81 @@ +--- +title: NET_ADAPTER_DATAPATH_CAPABILITIES structure +topic_type: +- apiref +api_name: +- NET_ADAPTER_DATAPATH_CAPABILITIES +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_DATAPATH_CAPABILITIES structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the data path capabilities of the adapter. + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_DATAPATH_CAPABILITIES { + ULONG Size; + ULONG NumTxQueues; + ULONG NumRxQueues; +} NET_ADAPTER_DATAPATH_CAPABILITIES, *PNET_ADAPTER_DATAPATH_CAPABILITIES; +``` + +Members +------- + +**Size** +Size of this structure in bytes. + +**NumTxQueues** +Maximum number of transmit queues supported by the adapter. + +**NumRxQueues** +Maximum number of receive queues supported by the adapter. + +Remarks +------- + +The client driver passes an initialized **NET_ADAPTER_DATAPATH_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md). + +Call [**NET_ADAPTER_DATAPATH_CAPABILITIES_INIT**](net-adapter-datapath-capabilities-init.md) to initialize this structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-driver-type.md b/windows-driver-docs-pr/netcx/net-adapter-driver-type.md new file mode 100644 index 0000000000..fc2f5cc7ee --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-driver-type.md @@ -0,0 +1,79 @@ +--- +title: NET_ADAPTER_DRIVER_TYPE enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_DRIVER_TYPE +api_location: +- netadapterdriver.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_DRIVER_TYPE enumeration + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Identifies the type of network adapter driver. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_DRIVER_TYPE { + NET_ADAPTER_DRIVER_TYPE_INVALID   = 0, + NET_ADAPTER_DRIVER_TYPE_MINIPORT  = 1 +} NET_ADAPTER_DRIVER_TYPE; +``` + +Constants +--------- + +**NET_ADAPTER_DRIVER_TYPE_INVALID** +Not currently supported. + +**NET_ADAPTER_DRIVER_TYPE_MINIPORT** +In NetAdapterCx version 1.0, this is the only supported value. + +Remarks +------- + +The **NET_ADAPTER_DRIVER_TYPE** enumeration is used to specify adapter type in the [**NET_ADAPTER_CONFIG**](net-adapter-config.md) structure. + +An initialized **NET_ADAPTER_CONFIG** structure is an input parameter to [**NetAdapterCreate**](netadaptercreate.md). + +The **NET_ADAPTER_DRIVER_TYPE** enumeration is also used as input to [**NetAdapterDriverWdmGetHandle**](netadapterdriverwdmgethandle.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterdriver.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init-no-physical-address.md b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init-no-physical-address.md new file mode 100644 index 0000000000..66c786342b --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init-no-physical-address.md @@ -0,0 +1,92 @@ +--- +title: NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS method +topic_type: +- apiref +api_name: +- NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes a [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS( + _Out_ PNET_ADAPTER_LINK_LAYER_CAPABILITIES LinkLayerCapabilities, + _In_ NET_PACKET_FILTER_TYPES_FLAGS SupportedPacketFilters, + _In_ ULONG MaxMulticastListSize, + _In_ NET_ADAPTER_STATISTICS_FLAGS SupportedStatistics, + _In_ ULONG64 MaxTxLinkSpeed, + _In_ ULONG64 MaxRxLinkSpeed, + ) +``` + +Parameters +---------- + +*LinkLayerCapabilities* [out] +A pointer to the driver-allocated [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure that describes the link layer capabilities of the adapter. + +*SupportedPacketFilters* [in] +An enumeration of type [NET_PACKET_FILTER_TYPES_FLAGS](net-packet-filter-types-flags.md) that specifying packet filters the adapter supports. + +*MaxMulticastListSize* [in] +The multicast address list size for the adapter. + +*SupportedStatistics* [in] +A bitwise OR of [NET_ADAPTER_STATISTICS_FLAGS](net-adapter-statistics-flags.md)-typed flags specifying statistics the adapter supports. + +*MaxTxLinkSpeed* [in] +The maximum transmit link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +*MaxRxLinkSpeed* [in] +The maximum receive link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +Remarks +----- +**NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT** zeroes out the [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure and then sets all of its members except for **PhysicalAddress**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init.md b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init.md new file mode 100644 index 0000000000..de8a06d69f --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities-init.md @@ -0,0 +1,125 @@ +--- +title: NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes a [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT( + _Out_ PNET_ADAPTER_LINK_LAYER_CAPABILITIES LinkLayerCapabilities, + _In_ NET_PACKET_FILTER_TYPES_FLAGS SupportedPacketFilters, + _In_ ULONG MaxMulticastListSize, + _In_ NET_ADAPTER_STATISTICS_FLAGS SupportedStatistics, + _In_ ULONG64 MaxTxLinkSpeed, + _In_ ULONG64 MaxRxLinkSpeed, + _In_range_(1,NDIS_MAX_PHYS_ADDRESS_LENGTH) + USHORT PhysicalAddressLength, + _In_reads_bytes_(PhysicalAddressLength) + PUCHAR PermanentPhysicalAddress, + _In_reads_bytes_(PhysicalAddressLength) + PUCHAR CurrentPhysicalAddress + ) +``` + +Parameters +---------- + +*LinkLayerCapabilities* [out] +A pointer to the driver-allocated [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure that describes the link layer capabilities of the adapter. + +*SupportedPacketFilters* [in] +An enumeration of type [NET_PACKET_FILTER_TYPES_FLAGS](net-packet-filter-types-flags.md) that specifying packet filters the adapter supports. + +*MaxMulticastListSize* [in] +The multicast address list size for the adapter. + +*SupportedStatistics* [in] +A bitwise OR of [NET_ADAPTER_STATISTICS_FLAGS](net-adapter-statistics-flags.md)-typed flags specifying statistics the adapter supports. + +*MaxTxLinkSpeed* [in] +The maximum transmit link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +*MaxRxLinkSpeed* [in] +The maximum receive link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +*PhysicalAddressLength* [in] +The physical address length, in bytes. The physical address length is specific to the type of media. + +*PermanentPhysicalAddress* [in] +The permanent physical address. For example, the [**OID_802_3_PERMANENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569074) OID specifies the permanent physical address for IEEE 802.3 drivers. + +*CurrentPhysicalAddress* [in] +The current physical address. For example, the [**OID_802_3_CURRENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569069) OID specifies the current physical address for IEEE 802.3 drivers. + +Remarks +----- +**NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT** zeroes out the [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure and then sets all of its members. It calls [**NET_ADAPTER_PHYSICAL_ADDRESS_INIT**](net-adapter-physical-address-init.md) to set the **PhysicalAddress** member. + +Example +----- + +```cpp +NET_ADAPTER_LINK_LAYER_CAPABILITIES linkLayerCapabilities; +NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT( + &linkLayerCapabilities, + NIC_SUPPORTED_FILTERS, + NIC_MAX_MCAST_LIST, + NIC_SUPPORTED_STATISTICS, + maxXmitLinkSpeed, + maxRcvLinkSpeed, + ETH_LENGTH_OF_ADDRESS, + adapterContext->PermanentAddress, + adapterContext->CurrentAddress); +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities.md b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities.md new file mode 100644 index 0000000000..761b450300 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-layer-capabilities.md @@ -0,0 +1,89 @@ +--- +title: NET_ADAPTER_LINK_LAYER_CAPABILITIES structure +--- + +# NET_ADAPTER_LINK_LAYER_CAPABILITIES structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the link layer capabilities of the adapter. + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_LINK_LAYER_CAPABILITIES { + ULONG                         Size; + NET_PACKET_FILTER_TYPES_FLAGS SupportedPacketFilters; + ULONG                         MaxMulticastListSize; + NET_ADAPTER_PHYSICAL_ADDRESS  PhysicalAddress; + NET_ADAPTER_STATISTICS_FLAGS  SupportedStatistics; + ULONG64                       MaxTxLinkSpeed; + ULONG64                       MaxRxLinkSpeed; +} NET_ADAPTER_LINK_LAYER_CAPABILITIES, *PNET_ADAPTER_LINK_LAYER_CAPABILITIES; +``` + +Members +------- + +**Size** +Size of this structure in bytes. + +**SupportedPacketFilters** +Indicates the packet filters that the adapter supports. This value is a bitwise OR of [**NET_PACKET_FILTER_TYPES_FLAGS**](net-packet-filter-types-flags.md)-typed flags. + +**MaxMulticastListSize** +The multicast address list size for the adapter. + +**PhysicalAddress** +A [**NET_ADAPTER_PHYSICAL_ADDRESS**](net-adapter-physical-address.md) structure that specifies the physical address of the adapter. For example, a driver for an Ethernet device would provide its 6-byte MAC address. + +**SupportedStatistics** +The statistics that the adapter supports. This value is a bitwise OR of [**NET_ADAPTER_STATISTICS_FLAGS**](net-adapter-statistics-flags.md)-typed flags. + +**MaxTxLinkSpeed** +The maximum transmit link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +**MaxRxLinkSpeed** +The maximum receive link speed of the adapter in bits per second. For more information, see [**OID_GEN_MAX_LINK_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff569602). + +Remarks +------- + +The client driver passes an initialized **NET_ADAPTER_LINK_LAYER_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md). + +Call [**NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT_NO_PHYSICAL_ADDRESS**](net-adapter-link-layer-capabilities-init-no-physical-address.md) or [**NET_ADAPTER_LINK_LAYER_CAPABILITIES_INIT**](net-adapter-link-layer-capabilities-init.md) to initialize this structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-state-init-disconnected.md b/windows-driver-docs-pr/netcx/net-adapter-link-state-init-disconnected.md new file mode 100644 index 0000000000..8cbd5e63d7 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-state-init-disconnected.md @@ -0,0 +1,95 @@ +--- +title: NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED method +topic_type: +- apiref +api_name: +- NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes a [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure for an adapter that is disconnected from the network. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED( + _Out_ PNET_ADAPTER_LINK_STATE LinkState +); +``` + +Parameters +---------- + +*LinkState* [out] +A pointer to a driver-allocated [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +Call [**NET_ADAPTER_LINK_STATE_INIT**](net-adapter-link-state-init.md) or **NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED** to initialize a [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +An initialized **NET_ADAPTER_LINK_STATE** structure is an input parameter value to [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NET_ADAPTER_LINK_STATE_INIT**](net-adapter-link-state-init.md) + +[**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) + +[**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md) + + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-state-init.md b/windows-driver-docs-pr/netcx/net-adapter-link-state-init.md new file mode 100644 index 0000000000..07983f8fcc --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-state-init.md @@ -0,0 +1,112 @@ +--- +title: NET_ADAPTER_LINK_STATE_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_LINK_STATE_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_LINK_STATE_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes a [NET_ADAPTER_LINK_STATE](net-adapter-link-state.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_LINK_STATE_INIT( + _Out_ PNET_ADAPTER_LINK_STATE            LinkState, + _In_  ULONG64                            LinkSpeed, + _In_  NET_IF_MEDIA_CONNECT_STATE         MediaConnectState, + _In_  NET_IF_MEDIA_DUPLEX_STATE          MediaDuplexState, + _In_  NET_ADAPTER_PAUSE_FUNCTIONS        SupportedPauseFunctions, + _In_  NET_ADAPTER_AUTO_NEGOTIATION_FLAGS SupportedPauseFunctions +); +``` + +Parameters +---------- + +*LinkState* [out] +A pointer to a driver-allocated [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +*LinkSpeed* [in] +The link speed of the adapter in bits per second. + +*MediaConnectState* [in] +The media connect state for the network adapter. + +*MediaDuplexState* [in] +The media duplex state for the network adapter. + +*SupportedPauseFunctions* [in] +Support for the IEEE 802.3 pause frames. For more info, see [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923). + +*SupportedPauseFunctions* [in] +The auto-negotiation settings for the network adapter. For more info, see [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923). + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +Call **NET_ADAPTER_LINK_STATE_INIT** or [**NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED**](net-adapter-link-state-init-disconnected.md) to initialize a [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +An initialized **NET_ADAPTER_LINK_STATE** structure is an input parameter value to [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md) + +[**NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED**](net-adapter-link-state-init-disconnected.md) + +[**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-link-state.md b/windows-driver-docs-pr/netcx/net-adapter-link-state.md new file mode 100644 index 0000000000..74e0b202a3 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-link-state.md @@ -0,0 +1,108 @@ +--- +title: NET_ADAPTER_LINK_STATE structure +topic_type: +- apiref +api_name: +- NET_ADAPTER_LINK_STATE +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_LINK_STATE structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the link state of the adapter. + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_LINK_STATE { + ULONG Size; + ULONG64 TxLinkSpeed; + ULONG64 RxLinkSpeed; + NET_IF_MEDIA_CONNECT_STATE MediaConnectState; + NET_IF_MEDIA_DUPLEX_STATE MediaDuplexState; + NET_ADAPTER_PAUSE_FUNCTIONS SupportedPauseFunctions; + NET_ADAPTER_AUTO_NEGOTIATION_FLAGS AutoNegotiationFlags; +} NET_ADAPTER_LINK_STATE, *PNET_ADAPTER_LINK_STATE; +``` + +Members +------- + +**Size** +Size of the **NET_ADAPTER_LINK_STATE** structure. + +**TxLinkSpeed** +The current transmit link speed of the adapter in bits per second. + +**RxLinkSpeed** +The current receive link speed of the adapter in bits per second. + +**MediaConnectState** +The media connect state for the network adapter. + +**MediaDuplexState** +The media duplex state for the network adapter. + +**SupportedPauseFunctions** +Support for the IEEE 802.3 pause frames. For more info, see [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923). + +**AutoNegotiationFlags** +The auto-negotiation settings for the network adapter. For more info, see [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923). + +Remarks +------- + +Call [**NET_ADAPTER_LINK_STATE_INIT**](net-adapter-link-state-init.md) or [**NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED**](net-adapter-link-state-init-disconnected.md) to initialize this structure. + +An initialized **NET_ADAPTER_LINK_STATE** structure is an input parameter value to [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +## See also + +[**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NET_ADAPTER_LINK_STATE_INIT**](net-adapter-link-state-init.md) + +[**NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED**](net-adapter-link-state-init-disconnected.md) + +[**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-media-specific-wakeup-events-flags.md b/windows-driver-docs-pr/netcx/net-adapter-media-specific-wakeup-events-flags.md new file mode 100644 index 0000000000..2f56bc11fd --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-media-specific-wakeup-events-flags.md @@ -0,0 +1,103 @@ +--- +title: NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies the media-specific wake-up events that a network adapter supports. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS { + NET_ADAPTER_WLAN_WAKE_ON_NLO_DISCOVERY           = NDIS_WLAN_WAKE_ON_NLO_DISCOVERY_SUPPORTED, + NET_ADAPTER_WLAN_WAKE_ON_AP_ASSOCIATION_LOST     = NDIS_WLAN_WAKE_ON_AP_ASSOCIATION_LOST_SUPPORTED, + NET_ADAPTER_WLAN_WAKE_ON_GTK_HANDSHAKE_ERROR     = NDIS_WLAN_WAKE_ON_GTK_HANDSHAKE_ERROR_SUPPORTED, + NET_ADAPTER_WLAN_WAKE_ON_4WAY_HANDSHAKE_REQUEST  = NDIS_WLAN_WAKE_ON_4WAY_HANDSHAKE_REQUEST_SUPPORTED, + NET_ADAPTER_WWAN_WAKE_ON_REGISTER_STATE          = NDIS_WWAN_WAKE_ON_REGISTER_STATE_SUPPORTED, + NET_ADAPTER_WWAN_WAKE_ON_SMS_RECEIVE             = NDIS_WWAN_WAKE_ON_SMS_RECEIVE_SUPPORTED, + NET_ADAPTER_WWAN_WAKE_ON_USSD_RECEIVE            = NDIS_WWAN_WAKE_ON_USSD_RECEIVE_SUPPORTED, + NET_ADAPTER_WWAN_WAKE_ON_PACKET_STATE            = NDIS_WWAN_WAKE_ON_PACKET_STATE_SUPPORTED, + NET_ADAPTER_WWAN_WAKE_ON_UICC_CHANGE             = NDIS_WWAN_WAKE_ON_UICC_CHANGE_SUPPORTED +} NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_WLAN_WAKE_ON_NLO_DISCOVERY** +If this flag is set, the 802.11 network adapter can generate a wake-up event if it detects a service set identifier (SSID) that was specified through a network list offload (NLO). + +For more information about NLO, see [Wi-Fi Network List Offload](../network/wi-fi-network-list-offload.md). + +**NET_ADAPTER_WLAN_WAKE_ON_AP_ASSOCIATION_LOST** +If this flag is set, the 802.11 network adapter can generate a wake-up event if it disassociates with the access point (AP). + +**NET_ADAPTER_WLAN_WAKE_ON_GTK_HANDSHAKE_ERROR** +If this flag is set, the 802.11 network adapter can generate a wake-up event if it encounters an error during the IEEE 802.11i RSN group transient key (GTK) handshake with the AP. + + +**NET_ADAPTER_WLAN_WAKE_ON_4WAY_HANDSHAKE_REQUEST** +If this flag is set, the 802.11 network adapter can generate a wake-up event if it receives the first frame of the IEEE 802.11i RSN 4-way handshake with the AP. This handshake is performed when the adapter authenticates with the AP. + +**NET_ADAPTER_WWAN_WAKE_ON_REGISTER_STATE** +If this flag is set, the mobile broadband (MB) network adapter can generate a wake-up event if its registration state to the MB Service has changed. + +**NET_ADAPTER_WWAN_WAKE_ON_SMS_RECEIVE** +If this flag is set, the MB network adapter can generate a wake-up event if the MB Service has to be notified about the receipt of a Short Message Service (SMS) message. The adapter generates this wake-up event either after the completion of a previously issued OID_WWAN_SMS_READ query request, or the arrival of a new class-0 (flash/alert) message from the network provider as an event notification. + + +**NET_ADAPTER_WWAN_WAKE_ON_USSD_RECEIVE** +If this flag is set, the MB network adapter can generate a wake-up event if it receives an Unstructured Supplementary Service Data (USSD) message. + + +**NET_ADAPTER_WWAN_WAKE_ON_PACKET_STATE** +If this flag is set, the MB network adapter can generate a wake-up event when the Packet Service state of the Modem changes. + +**NET_ADAPTER_WWAN_WAKE_ON_UICC_CHANGE** +If this flag is set, the MB network adapter can generate a wake-up event when the UICC (SIM) is inserted or removed. + +Remarks +----- +The **NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS** enumeration is used to specify supported media-specific wake-up events in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +The [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure is used as input to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- +[**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) diff --git a/windows-driver-docs-pr/netcx/net-adapter-pause-functions.md b/windows-driver-docs-pr/netcx/net-adapter-pause-functions.md new file mode 100644 index 0000000000..6b38418dde --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-pause-functions.md @@ -0,0 +1,87 @@ +--- +title: NET_ADAPTER_PAUSE_FUNCTIONS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_PAUSE_FUNCTIONS, PNET_ADAPTER_PAUSE_FUNCTIONS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_PAUSE_FUNCTIONS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies a client driver's support for the IEEE 802.3 pause frames. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_PAUSE_FUNCTIONS { + NetAdapterPauseFunctionsUnsupported     = NdisPauseFunctionsUnsupported, + NetAdapterPauseFunctionsSendOnly        = NdisPauseFunctionsSendOnly, + NetAdapterPauseFunctionsReceiveOnly     = NdisPauseFunctionsReceiveOnly, + NetAdapterPauseFunctionsSendAndReceive  = NdisPauseFunctionsSendAndReceive, + NetAdapterPauseFunctionsUnknown         = NdisPauseFunctionsUnknown +} NET_ADAPTER_PAUSE_FUNCTIONS, *PNET_ADAPTER_PAUSE_FUNCTIONS; +``` + +Constants +--------- + +**NetAdapterPauseFunctionsUnsupported** +Indicates that the adapter or link partner does not support pause frames. + +**NetAdapterPauseFunctionsSendOnly** +Indicates that the adapter and link partner only support sending pause frames from the adapter to the link partner. + +**NetAdapterPauseFunctionsReceiveOnly** +Indicates that the adapter and link partner only support sending pause frames from the link partner to the adapter. + +**NetAdapterPauseFunctionsSendAndReceive** +Indicates that the adapter and link partner support sending and receiving pause frames in both transint and receive directions. + +**NetAdapterPauseFunctionsUnknown** +Indicates that pause frame negotiation is in progress. The pause frame support that the link partner provides is unknown. + +Remarks +--- +The **NET_ADAPTER_PAUSE_FUNCTIONS** enumeration is used to specify pause frame support in the [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure. + +An initialized [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure is an input to [**NetAdapterSetCurrentLinkState**](netadaptersetcurrentlinkstate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-physical-address-init.md b/windows-driver-docs-pr/netcx/net-adapter-physical-address-init.md new file mode 100644 index 0000000000..0f83a08dff --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-physical-address-init.md @@ -0,0 +1,93 @@ +--- +title: NET_ADAPTER_PHYSICAL_ADDRESS_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_PHYSICAL_ADDRESS_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_PHYSICAL_ADDRESS_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [**NET_ADAPTER_PHYSICAL_ADDRESS**](net-adapter-physical-address.md) structure. + +Syntax +------ + +```cpp +VOID NET_ADAPTER_PHYSICAL_ADDRESS_INIT( + _Out_ PNET_ADAPTER_PHYSICAL_ADDRESS PhysicalAddress, + _In_  USHORT                        Length, + _In_  PCUCHAR                       PermanentAddressBuffer, + _In_  PCUCHAR                       CurrentAddressBuffer +); +``` + +Parameters +---------- + +*PhysicalAddress* [out] +A pointer to the driver-allocated [**NET_ADAPTER_PHYSICAL_ADDRESS**](net-adapter-physical-address.md) structure. + +*Length* [in] +The number of bytes to copy from each address buffer parameter into the corresponding fields of the structure pointed to by *PhysicalAddress*. If this value is greater than NDIS_MAX_PHYS_ADDRESS_LENGTH, that value is used instead. + +*PermanentAddressBuffer* [in] +The permanent physical address. For example, the [**OID_802_3_PERMANENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569074) OID specifies the permanent physical address for IEEE 802.3 drivers. + +*CurrentAddressBuffer* [in] +The current physical address. For example, the [**OID_802_3_CURRENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569069) OID specifies the current physical address for IEEE 802.3 drivers. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + +[NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) + +[**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) + +[NET_ADAPTER_PHYSICAL_ADDRESS](net-adapter-physical-address.md) + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-physical-address.md b/windows-driver-docs-pr/netcx/net-adapter-physical-address.md new file mode 100644 index 0000000000..c46cde96dc --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-physical-address.md @@ -0,0 +1,74 @@ +--- +title: NET_ADAPTER_PHYSICAL_ADDRESS structure +topic_type: +- apiref +api_name: +- NET_ADAPTER_PHYSICAL_ADDRESS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_PHYSICAL_ADDRESS structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Call [NET_ADAPTER_PHYSICAL_ADDRESS_INIT](net-adapter-physical-address-init.md) to initialize this structure. + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_PHYSICAL_ADDRESS { + USHORT Length; + UCHAR PermanentAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]; + UCHAR CurrentAddress[NDIS_MAX_PHYS_ADDRESS_LENGTH]; +} NET_ADAPTER_PHYSICAL_ADDRESS, *PNET_ADAPTER_PHYSICAL_ADDRESS; +``` + +Members +------- + +**Length** +The physical address length, in bytes. The physical address length is specific to the type of media. + +**PermanentAddress** +The permanent physical address. For example, the [**OID_802_3_PERMANENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569074) OID specifies the permanent physical address for IEEE 802.3 drivers. + +**CurrentAddress** +The current physical address. For example, the [**OID_802_3_CURRENT_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff569069) OID specifies the current physical address for IEEE 802.3 drivers. + +Remarks +----- +The driver supplies a member of type [NET_ADAPTER_PHYSICAL_ADDRESS](net-adapter-physical-address.md) when it initializes a [NET_ADAPTER_LINK_LAYER_CAPABILITIES](net-adapter-link-layer-capabilities.md) structure to pass as an input parameter to [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- + +[**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) diff --git a/windows-driver-docs-pr/netcx/net-adapter-power-capabilities-init.md b/windows-driver-docs-pr/netcx/net-adapter-power-capabilities-init.md new file mode 100644 index 0000000000..dd4cc38eab --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-power-capabilities-init.md @@ -0,0 +1,85 @@ +--- +title: NET_ADAPTER_POWER_CAPABILITIES_INIT method +topic_type: +- apiref +api_name: +- NET_ADAPTER_POWER_CAPABILITIES_INIT +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_POWER_CAPABILITIES_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_ADAPTER_POWER_CAPABILITIES_INIT( + _Out_ PNET_ADAPTER_POWER_CAPABILITIES PowerCapabilities +); +``` + +Parameters +---------- + +*PowerCapabilities* [out] +A pointer to the driver-allocated [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +Return value +------------ + +This method does not return a value. + +Remarks +----- +The **NET_ADAPTER_POWER_CAPABILITIES_INIT** function zeros the specified **NET_ADAPTER_POWER_CAPABILITIES** structure and sets the structure's **Size** member. It also sets the structure's **ManageS0IdlePowerReferences** member to **WdfUseDefault**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netadapter.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-power-capabilities.md b/windows-driver-docs-pr/netcx/net-adapter-power-capabilities.md new file mode 100644 index 0000000000..6e30226e74 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-power-capabilities.md @@ -0,0 +1,132 @@ +--- +title: NET_ADAPTER_POWER_CAPABILITIES structure +--- + +# NET_ADAPTER_POWER_CAPABILITIES structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the power capabilities of the adapter. + +Syntax +------ + +```cpp +typedef struct _NET_ADAPTER_POWER_CAPABILITIES { + ULONG                                          Size; + NET_ADAPTER_POWER_FLAGS                        Flags; + NET_ADAPTER_WAKE_PATTERN_FLAGS                 SupportedWakePatterns; + ULONG                                          NumTotalWakePatterns; + ULONG                                          MaxWakePatternSize; + ULONG                                          MaxWakePatternOffset; + ULONG                                          MaxWakePacketSaveBuffer; + NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS            SupportedProtocolOffloads; + ULONG                                          NumArpOffloadIPv4Addresses; + ULONG                                          NumNSOffloadIPv6Addresses; + NET_ADAPTER_WAKEUP_EVENTS_FLAGS                SupportedWakeUpEvents; + NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS SupportedMediaSpecificWakeUpEvents; + PFN_NET_ADAPTER_PREVIEW_WAKE_PATTERN           EvtAdapterPreviewWakePattern; + PFN_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD       EvtAdapterPreviewProtocolOffload; + WDF_TRI_STATE                                  ManageS0IdlePowerReferences; +} NET_ADAPTER_POWER_CAPABILITIES, *PNET_ADAPTER_POWER_CAPABILITIES; +``` + +Members +------- + +**Size** +Size of this structure in bytes. + +**Flags** +Bitwise OR of [**NET_ADAPTER_POWER_FLAGS**](net-adapter-power-flags.md)-typed flags. + +**SupportedWakePatterns** +Bitwise OR of [**NET_ADAPTER_WAKE_PATTERN_FLAGS**](net-adapter-wake-pattern-flags.md)-typed flags that specify the wake-on-LAN (WOL) patterns that a network adapter supports. + +**NumTotalWakePatterns** +The total number of wake patterns that a network adapter supports. This is the sum of the number of supported wake protocol patterns and the number of supported wake bitmap patterns. + +**MaxWakePatternSize** +The maximum number of bytes that can be compared with a pattern. + +**MaxWakePatternOffset** +The number of bytes in a packet that can be examined, starting at the beginning of the MAC header. + +**MaxWakePacketSaveBuffer** +The number of bytes of a wake packet that the client can save to a buffer and indicate up the driver stack. This value must be less than or equal to the size, in bytes, of the maximum transmission unit (MTU) for the network media. + +**SupportedProtocolOffloads** +Bitwise OR of [**NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS**](net-adapter-protocol-offloads-flags.md)-typed flags that specify the protocol offload features that a network adapter supports. + +**NumArpOffloadIPv4Addresses** +The number of IPv4 addresses that the adapter supports for ARP offload. + +**NumNSOffloadIPv6Addresses** +The number of IPv6 NS offload requests that the adapter supports. This should be at least 2. + +**SupportedWakeUpEvents** +Bitwise OR of [**NET_ADAPTER_WAKEUP_EVENTS_FLAGS**](net-adapter-wakeup-events-flags.md)-typed flags that specify the media-independent wake-up events that a network adapter supports. + +**SupportedMediaSpecificWakeUpEvents** +Bitwise OR of [**NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS**](net-adapter-media-specific-wakeup-events-flags.md)-typed flags that specify the media-specific wake-up events that a network adapter supports. + +**EvtAdapterPreviewWakePattern** +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) event callback. + +**EvtAdapterPreviewProtocolOffload** +A pointer to the client's implementation of the [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) event callback. + +**ManageS0IdlePowerReferences** +A [**WDF_TRI_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff552533)-typed enumerator that indicates whether NetAdapterCx should manage power references for scenarios such as modern standby (AoAC). See more info in the **Remarks** section. This member can have one of the following values: + +**WdfTrue** - NetAdapterCx manages power references. The client driver must be the power policy owner to specify **WdfTrue**. +**WdfFalse** - NetAdapterCx does not manage power references. +**WdfUseDefault** : if driver is the power policy owner, then use **WdfTrue**, otherwise use **WdfFalse**. + +Remarks +------- + +The client driver passes an initialized **NET_ADAPTER_POWER_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Call [**NET_ADAPTER_POWER_CAPABILITIES_INIT**](net-adapter-power-capabilities-init.md) to initialize this structure. + +The client driver configures its S0-Idle policy like any other WDF driver, by calling [**WdfDeviceAssignS0IdleSettings**](https://msdn.microsoft.com/library/windows/hardware/ff545903). + + When power reference management is enabled via **ManageS0IdlePowerReferences**, NetAdapterCx manages power references that result in the WDFDEVICE being powered up/down as necessary. For example, the class extension acquires and releases power references so the device maintains power state as necessary to support modern standby (AoAC). Additionally, the client driver can set the **NET_ADAPTER_POWER_SELECTIVE_SUSPEND** flag in the [**NET_ADAPTER_POWER_FLAGS**](net-adapter-power-flags.md) enumeration to cause NetAdapterCx to manage power references for the data and control path. This will result in the device being powered down when it is idle. Note that the **NET_ADAPTER_POWER_SELECTIVE_SUSPEND** option results in improved power efficiency at the cost of some performance. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ + See Also +---- +[Power Policy Ownership](../wdf/power-policy-ownership.md) + + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-power-flags.md b/windows-driver-docs-pr/netcx/net-adapter-power-flags.md new file mode 100644 index 0000000000..a9cb618118 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-power-flags.md @@ -0,0 +1,79 @@ +--- +title: NET_ADAPTER_POWER_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_POWER_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_POWER_FLAGS enumeration + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies a client driver's power capabilities. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_POWER_FLAGS { + NET_ADAPTER_POWER_WAKE_PACKET_INDICATION  = NDIS_PM_WAKE_PACKET_INDICATION_SUPPORTED, + NET_ADAPTER_POWER_SELECTIVE_SUSPEND       = NDIS_PM_SELECTIVE_SUSPEND_SUPPORTED +} NET_ADAPTER_POWER_FLAGS; +``` + +Constants +--------- +**NET_ADAPTER_POWER_WAKE_PACKET_INDICATION** +If this flag is set, the network adapter must be able to save the received packet that caused the adapter to generate a wake-up event. + +If this flag is set, the client driver must be able to do the following with this packet after the network adapter transitions to a full-power state: + +* The client driver must be able to indicate the packet by calling [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598). +* The client driver must be able to issue an NDIS_STATUS_PM_WAKE_REASON status indication and must pass the packet with the indication. To indicate the received packet, the client calls [**NetAdapterWdmGetNdisHandle**](netadapterwdmgetndishandle.md) and then calls [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598). + +For more information about this power management capability, see [NDIS Wake Reason Status Indications](../network/ndis-wake-reason-status-indications.md). + +**NET_ADAPTER_POWER_SELECTIVE_SUSPEND** +Specifies that NetAdapterCx should suspend an idle network adapter by transitioning the adapter to a low-power state. + +Remarks +--- +The **NET_ADAPTER_POWER_FLAGS** enumeration is used to specify power capabilities in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +The client driver passes an initialized **NET_ADAPTER_POWER_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +## See also + +[**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) + +[**NDIS_PM_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) diff --git a/windows-driver-docs-pr/netcx/net-adapter-protocol-offloads-flags.md b/windows-driver-docs-pr/netcx/net-adapter-protocol-offloads-flags.md new file mode 100644 index 0000000000..b95d387df1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-protocol-offloads-flags.md @@ -0,0 +1,82 @@ +--- +title: NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies the low power protocol offload capabilities of a network adapter. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS { + NET_ADAPTER_PROTOCOL_OFFLOAD_ARP              = NDIS_PM_PROTOCOL_OFFLOAD_ARP_ENABLED, + NET_ADAPTER_PROTOCOL_OFFLOAD_NS               = NDIS_PM_PROTOCOL_OFFLOAD_NS_ENABLED, + NET_ADAPTER_PROTOCOL_OFFLOAD_80211_RSN_REKEY  = NDIS_PM_PROTOCOL_OFFLOAD_80211_RSN_REKEY_ENABLED +} NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_PROTOCOL_OFFLOAD_ARP** +If this bit is set, the overlying driver will request the network adapter to enable the ARP protocol offload capability. As soon as this protocol offload has been configured by a set request of [OID_PM_ADD_PROTOCOL_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/ff569763), the driver should enable the network adapter to respond to IPv4 ARP packets while it is in a low-power state. + +**NET_ADAPTER_PROTOCOL_OFFLOAD_NS** +If this bit is set, the overlying driver will request the network adapter to enable the IPv6 Neighbor Solicitation (NS) protocol offload capability. As soon as this protocol offload has been configured by a set request of [OID_PM_ADD_PROTOCOL_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/ff569763), the driver should enable the network adapter to respond to NS packets while it is in a low-power state. + +**NET_ADAPTER_PROTOCOL_OFFLOAD_80211_RSN_REKEY** +If this bit is set, the overlying driver will request the network adapter to enable the IEEE 802.11i Robust Security Network (RSN) protocol offload capability. As soon as this protocol offload has been configured by a set request of [OID_PM_ADD_PROTOCOL_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/ff569763), the driver should enable the network adapter to respond to RSN re-key requests packets while it is in a low power state. + +Remarks +--- +The **NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS** enumeration is used to specify protocol offload capabilities in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +The client driver passes an initialized **NET_ADAPTER_POWER_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- +[**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) + + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-statistics-flags.md b/windows-driver-docs-pr/netcx/net-adapter-statistics-flags.md new file mode 100644 index 0000000000..b38c73cac8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-statistics-flags.md @@ -0,0 +1,172 @@ +--- +title: NET_ADAPTER_STATISTICS_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_STATISTICS_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_STATISTICS_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies statistics that an adapter supports. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_STATISTICS_FLAGS { + NET_ADAPTER_STATISTICS_NO_FLAGS               = 0, + NET_ADAPTER_STATISTICS_XMIT_OK                = NDIS_STATISTICS_XMIT_OK_SUPPORTED, + NET_ADAPTER_STATISTICS_RCV_OK                 = NDIS_STATISTICS_RCV_OK_SUPPORTED, + NET_ADAPTER_STATISTICS_XMIT_ERROR             = NDIS_STATISTICS_XMIT_ERROR_SUPPORTED, + NET_ADAPTER_STATISTICS_RCV_ERROR              = NDIS_STATISTICS_RCV_ERROR_SUPPORTED, + NET_ADAPTER_STATISTICS_RCV_NO_BUFFER          = NDIS_STATISTICS_RCV_NO_BUFFER_SUPPORTED, + NET_ADAPTER_STATISTICS_DIRECTED_BYTES_XMIT    = NDIS_STATISTICS_DIRECTED_BYTES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_DIRECTED_FRAMES_XMIT   = NDIS_STATISTICS_DIRECTED_FRAMES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_MULTICAST_BYTES_XMIT   = NDIS_STATISTICS_MULTICAST_BYTES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_MULTICAST_FRAMES_XMIT  = NDIS_STATISTICS_MULTICAST_FRAMES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_BROADCAST_BYTES_XMIT   = NDIS_STATISTICS_BROADCAST_BYTES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_BROADCAST_FRAMES_XMIT  = NDIS_STATISTICS_BROADCAST_FRAMES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_DIRECTED_BYTES_RCV     = NDIS_STATISTICS_DIRECTED_BYTES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_DIRECTED_FRAMES_RCV    = NDIS_STATISTICS_DIRECTED_FRAMES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_MULTICAST_BYTES_RCV    = NDIS_STATISTICS_MULTICAST_BYTES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_MULTICAST_FRAMES_RCV   = NDIS_STATISTICS_MULTICAST_FRAMES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_BROADCAST_BYTES_RCV    = NDIS_STATISTICS_BROADCAST_BYTES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_BROADCAST_FRAMES_RCV   = NDIS_STATISTICS_BROADCAST_FRAMES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_RCV_CRC_ERROR          = NDIS_STATISTICS_RCV_CRC_ERROR_SUPPORTED, + NET_ADAPTER_STATISTICS_TRANSMIT_QUEUE_LENGTH  = NDIS_STATISTICS_TRANSMIT_QUEUE_LENGTH_SUPPORTED, + NET_ADAPTER_STATISTICS_BYTES_RCV              = NDIS_STATISTICS_BYTES_RCV_SUPPORTED, + NET_ADAPTER_STATISTICS_BYTES_XMIT             = NDIS_STATISTICS_BYTES_XMIT_SUPPORTED, + NET_ADAPTER_STATISTICS_RCV_DISCARDS           = NDIS_STATISTICS_RCV_DISCARDS_SUPPORTED, + NET_ADAPTER_STATISTICS_GEN_STATISTICS         = NDIS_STATISTICS_GEN_STATISTICS_SUPPORTED, + NET_ADAPTER_STATISTICS_XMIT_DISCARDS          = NDIS_STATISTICS_XMIT_DISCARDS_SUPPORTED +} NET_ADAPTER_STATISTICS_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_STATISTICS_NO_FLAGS** +No flags are set. + +**NET_ADAPTER_STATISTICS_XMIT_OK** +The client can handle OID_GEN_XMIT_OK. + +**NET_ADAPTER_STATISTICS_RCV_OK** +The client can handle OID_GEN_RCV_OK. + +**NET_ADAPTER_STATISTICS_XMIT_ERROR** +The data in the **ifOutErrors** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_RCV_ERROR** +The data in the **ifInErrors** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_RCV_NO_BUFFER** +The client can handle OID_GEN_RCV_NO_BUFFER. + +**NET_ADAPTER_STATISTICS_DIRECTED_BYTES_XMIT** +The data in the **ifHCOutUcastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_DIRECTED_FRAMES_XMIT** +The data in the **ifHCOutUcastPkts** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_MULTICAST_BYTES_XMIT** +The data in the **ifHCOutMulticastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_MULTICAST_FRAMES_XMIT** +The data in the **ifHCOutMulticastPkts** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_BROADCAST_BYTES_XMIT** +The data in the **ifHCOutBroadcastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_BROADCAST_FRAMES_XMIT** +The data in the **ifHCOutBroadcastPkts** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_DIRECTED_BYTES_RCV** +The data in the **ifHCInUcastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_DIRECTED_FRAMES_RCV** +The data in the **ifHCInUcastPkts** member is valid. + +**NET_ADAPTER_STATISTICS_MULTICAST_BYTES_RCV** +The data in the **ifHCInMulticastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_MULTICAST_FRAMES_RCV** +The data in the **ifHCInMulticastPkts** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_BROADCAST_BYTES_RCV** +The data in the **ifHCInBroadcastOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_BROADCAST_FRAMES_RCV** +The data in the **ifHCInBroadcastPkts** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_RCV_CRC_ERROR** +The client can handle OID_GEN_RCV_CRC_ERROR. + +**NET_ADAPTER_STATISTICS_TRANSMIT_QUEUE_LENGTH** +The client can handle OID_GEN_TRANSMIT_QUEUE_LENGTH. + +**NET_ADAPTER_STATISTICS_BYTES_RCV** +The data in the **ifHCInOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_BYTES_XMIT** +The data in the **ifHCOutOctets** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_RCV_DISCARDS** +The data in the **ifInDiscards** member of NDIS_STATISTICS_INFO is valid. + +**NET_ADAPTER_STATISTICS_GEN_STATISTICS** +The client can handle OID_GEN_STATISTICS. + +**NET_ADAPTER_STATISTICS_XMIT_DISCARDS** +The data in the **ifOutDiscards** member of NDIS_STATISTICS_INFO is valid. + +Remarks +----- +The **NET_ADAPTER_STATISTICS_FLAGS** enumeration is used to specify supported statistics in the [**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) structure. + +The client driver passes an initialized [**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) structure as an input parameter value to [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md). + +The client returns an NDIS_STATISTICS_INFO structure when handling an [**OID_GEN_STATISTICS**](https://msdn.microsoft.com/library/windows/hardware/ff569640) query. + + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- +[**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-wake-pattern-flags.md b/windows-driver-docs-pr/netcx/net-adapter-wake-pattern-flags.md new file mode 100644 index 0000000000..ed4e98d341 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-wake-pattern-flags.md @@ -0,0 +1,109 @@ +--- +title: NET_ADAPTER_WAKE_PATTERN_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_WAKE_PATTERN_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_WAKE_PATTERN_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies wake patterns that an adapter supports. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_WAKE_PATTERN_FLAGS { + NET_ADAPTER_WAKE_BITMAP_PATTERN            = NDIS_PM_WOL_BITMAP_PATTERN_ENABLED, + NET_ADAPTER_WAKE_MAGIC_PACKET              = NDIS_PM_WOL_MAGIC_PACKET_ENABLED, + NET_ADAPTER_WAKE_IPV4_TCP_SYN              = NDIS_PM_WOL_IPV4_TCP_SYN_ENABLED, + NET_ADAPTER_WAKE_IPV6_TCP_SYN              = NDIS_PM_WOL_IPV6_TCP_SYN_ENABLED, + NET_ADAPTER_WAKE_IPV4_DEST_ADDR_WILDCARD   = NDIS_PM_WOL_IPV4_DEST_ADDR_WILDCARD_ENABLED, + NET_ADAPTER_WAKE_IPV6_DEST_ADDR_WILDCARD   = NDIS_PM_WOL_IPV6_DEST_ADDR_WILDCARD_ENABLED, + NET_ADAPTER_WAKE_EAPOL_REQUEST_ID_MESSAGE  = NDIS_PM_WOL_EAPOL_REQUEST_ID_MESSAGE_ENABLED +} NET_ADAPTER_WAKE_PATTERN_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_WAKE_BITMAP_PATTERN** +If this flag is set, the network adapter is enabled to generate a wake-up event when it receives a packet that matches a configured bitmap pattern. + +**NET_ADAPTER_WAKE_MAGIC_PACKET** +If this flag is set, the network adapter is enabled to generate a wake-up event when it receives a WOL magic packet. A *magic packet* contains within its payload a string of six bytes with a value of 0xFF, followed immediately by 16 contiguous copies of the receiving network adapter's media access control (MAC) address. + +**NET_ADAPTER_WAKE_IPV4_TCP_SYN** +If this flag is set, the network adapter is enabled to generate a wake-up event when it receives an IPv4 TCP SYN packet. Remote hosts send TCP SYN packets to initiate a TCP connection to the local computer. + +**NET_ADAPTER_WAKE_IPV6_TCP_SYN** +If this flag is set, the network adapter is enabled to generate a wake-up event when it receives an IPv6 TCP SYN packet. + +**NET_ADAPTER_WAKE_IPV4_DEST_ADDR_WILDCARD** +If this flag is set, the network adapter must treat as wildcard values any zero-filled, or unspecified, values for IPv4 addresses and TCP/UDP ports in a WOL pattern. In this way, the wildcard value matches any IPv4 address and any port value of the incoming packet in the location specified by the WOL pattern. + +If this flag is set, the network adapter is enabled to generate a wake-up event if the following pattern-matching conditions are true: + +* Any value from the incoming packet in the location specified by the WOL pattern is a match, if the WOL pattern for that location contains a wildcard value. +* A value from the incoming packet in the location specified by the WOL pattern is a match if the WOL pattern for that location contains a nonzero value that equals the packet's value. + +> [!NOTE] +> Wildcard values that are enabled by this flag can include unspecified IPv4 source and destination addresses, as well as unspecified source and destination ports. + +**NET_ADAPTER_WAKE_IPV6_DEST_ADDR_WILDCARD** +If this flag is set, the network adapter must treat as wildcard values any zero-filled, or unspecified, values for IPv6 addresses and TCP/UDP ports in a WOL pattern. In this way, the wildcard value matches any IPv6 address and any port value of the incoming packet in the location specified by the WOL pattern. + +If this flag is set, the network adapter is enabled to generate a wake-up event if the following pattern-matching conditions are true: + +* Any value from the incoming packet in the location specified by the WOL pattern is a match, if the WOL pattern for that location contains a wildcard value. +* A value from the incoming packet in the location specified by the WOL pattern is a match if the WOL pattern for that location contains a nonzero value that equals the packet's value. + +> [!NOTE] +> Wildcard values that are enabled by this flag can include unspecified IPv6 source and destination addresses, as well as unspecified source and destination ports. + +**NET_ADAPTER_WAKE_EAPOL_REQUEST_ID_MESSAGE** +If this flag is set, the network adapter is enabled to generate a wake-up event when it receives an EAPOL request identifier message. + +Remarks +----- +The **NET_ADAPTER_WAKE_PATTERN_FLAGS** enumeration is used to specify supported statistics in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +The client driver passes an initialized [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure as an input parameter value to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- +[**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) + + + diff --git a/windows-driver-docs-pr/netcx/net-adapter-wakeup-events-flags.md b/windows-driver-docs-pr/netcx/net-adapter-wakeup-events-flags.md new file mode 100644 index 0000000000..1ca9e6fcd7 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-adapter-wakeup-events-flags.md @@ -0,0 +1,80 @@ +--- +title: NET_ADAPTER_WAKEUP_EVENTS_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_ADAPTER_WAKEUP_EVENTS_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_ADAPTER_WAKEUP_EVENTS_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies the media-independent wake-up events that a network adapter supports. + +Syntax +------ + +```cpp +typedef enum _NET_ADAPTER_WAKEUP_EVENTS_FLAGS { + NET_ADAPTER_WAKE_ON_MEDIA_CONNECT     = NDIS_PM_WAKE_ON_MEDIA_CONNECT_SUPPORTED, + NET_ADAPTER_WAKE_ON_MEDIA_DISCONNECT  = NDIS_PM_WAKE_ON_MEDIA_DISCONNECT_SUPPORTED +} NET_ADAPTER_WAKEUP_EVENTS_FLAGS; +``` + +Constants +--------- + +**NET_ADAPTER_WAKE_ON_MEDIA_CONNECT** +If this flag is set, the network adapter can generate a wake-up event when it becomes connected to the networking interface. + +**NET_ADAPTER_WAKE_ON_MEDIA_DISCONNECT** +If this flag is set, the network adapter can generate a wake-up event when it becomes disconnected to the networking interface. + +Remarks +------- +The **NET_ADAPTER_WAKEUP_EVENTS_FLAGS** enumeration is used to specify media-independent wake-up events in the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +The client driver passes an initialized **NET_ADAPTER_POWER_CAPABILITIES** structure as an input parameter value to [**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +## See also + +[**NDIS_PM_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-configuration-query-ulong-flags.md b/windows-driver-docs-pr/netcx/net-configuration-query-ulong-flags.md new file mode 100644 index 0000000000..5584f9efd7 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-configuration-query-ulong-flags.md @@ -0,0 +1,66 @@ +--- +title: NET_CONFIGURATION_QUERY_ULONG_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_CONFIGURATION_QUERY_ULONG_FLAGS +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NET_CONFIGURATION_QUERY_ULONG_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The **NET_CONFIGURATION_QUERY_ULONG_FLAGS** enumeration is used as an input parameter to the [**NetConfigurationQueryUlong**](netconfigurationqueryulong.md) method. + +Syntax +------ + +```cpp +typedef enum _NET_CONFIGURATION_QUERY_ULONG_FLAGS { + NET_CONFIGURATION_QUERY_ULONG_NO_FLAGS                     = = 0x00000000, + NET_CONFIGURATION_QUERY_ULONG_MAY_BE_STORED_AS_HEX_STRING  = = 0x00000001 +} NET_CONFIGURATION_QUERY_ULONG_FLAGS; +``` + +Constants +--------- + +**NET_CONFIGURATION_QUERY_ULONG_NO_FLAGS** +No flags are set. + +**NET_CONFIGURATION_QUERY_ULONG_MAY_BE_STORED_AS_HEX_STRING** +Specifies that the ULONG may be stored in the configuration database as a string in hex format. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h
+ +See Also +----- +[**NetConfigurationQueryUlong**](netconfigurationqueryulong.md) + + diff --git a/windows-driver-docs-pr/netcx/net-driver-globals.md b/windows-driver-docs-pr/netcx/net-driver-globals.md new file mode 100644 index 0000000000..1326d01a20 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-driver-globals.md @@ -0,0 +1,65 @@ +--- +title: NET_DRIVER_GLOBALS structure +topic_type: +- apiref +api_name: +- NET_DRIVER_GLOBALS +api_location: +- netadaptercxtypes.h +api_type: +- HeaderDef +--- + +# NET_DRIVER_GLOBALS structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Call NET_DRIVER_GLOBALS_INIT to initialize this structure. + +Syntax +------ + +```cpp +typedef struct _NET_DRIVER_GLOBALS { + ULONG Unused; +} NET_DRIVER_GLOBALS, *PNET_DRIVER_GLOBALS; +``` + +Members +------- + +**Unused** + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadaptercxtypes.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-packet-checksum.md b/windows-driver-docs-pr/netcx/net-packet-checksum.md new file mode 100644 index 0000000000..01e6343834 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet-checksum.md @@ -0,0 +1,92 @@ +--- +title: NET_PACKET_CHECKSUM structure +--- + +# NET_PACKET_CHECKSUM structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +A [**NET_PACKET**](net-packet.md) structure contains a member of type **NET_PACKET_CHECKSUM**. + +Syntax +------ + +```cpp +typedef struct _NET_PACKET_CHECKSUM +{ + UINT8 Layer2 : 2; + UINT8 Layer3 : 2; + UINT8 Layer4 : 2; + UINT8 Reserved : 2; +} NET_PACKET_CHECKSUM; +``` + +Members +------- + +**Layer2** +A bit field that specifies a flag from either **NET_PACKET_TX_CHECKSUM_ACTION** or **NET_PACKET_RX_CHECKSUM_EVALUATION**. Targets the checksum field in the packet's layer 2 header. + +**Layer3** +A bit field that specifies a flag from either **NET_PACKET_TX_CHECKSUM_ACTION** or **NET_PACKET_RX_CHECKSUM_EVALUATION**. Targets the checksum field in the packet's layer 3 header. + +**Layer4** +A bit field that specifies a flag from either **NET_PACKET_TX_CHECKSUM_ACTION** or **NET_PACKET_RX_CHECKSUM_EVALUATION**. Targets the checksum field in the packet's layer 4 header. + +**Reserved** +Reserved for system use. + +Remarks +----- +See more info in the description of the **Checksum** member of [**NET_PACKET**](net-packet.md). + +For a transmit queue, the client specifies flag values from the **NET_PACKET_TX_CHECKSUM_ACTION** enumeration: + +``` +typedef enum _NET_PACKET_TX_CHECKSUM_ACTION +{ + NET_PACKET_TX_CHECKSUM_PASSTHROUGH = 0, + NET_PACKET_TX_CHECKSUM_REQUIRED = 2, +} NET_PACKET_TX_CHECKSUM_ACTION; +``` + +For a receive queue, the client specifies flag values from the **NET_PACKET_RX_CHECKSUM_EVALUATION** enumeration. + +``` +typedef enum _NET_PACKET_RX_CHECKSUM_EVALUATION +{ + NET_PACKET_RX_CHECKSUM_NOT_CHECKED = 0, + NET_PACKET_RX_CHECKSUM_VALID = 1, + NET_PACKET_RX_CHECKSUM_INVALID = 2, +} NET_PACKET_RX_CHECKSUM_EVALUATION; +``` + +In a transmit queue, the client cross-references the **Checksum** member with the [**Layout**](net-packet-layout.md) member of [**NET_PACKET**](net-packet.md) in order to determine which hardware transmit checksum offloads need to be enabled. A **NET_PACKET_TX_CHECKSUM_ACTION** value of **NET_PACKET_TX_CHECKSUM_REQUIRED** means that the client should perform the checksum calculation for this layer. + +In a receive queue, the client converts its hardware packet descriptors' receive checksum offload fields into **NET_PACKET_RX_CHECKSUM_EVALUATION** values for each layer. **NET_PACKET_RX_CHECKSUM_VALID** indicates that the hardware determined that the checksum value is correct, while **NET_PACKET_RX_CHECKSUM_INVALID** means that it is incorrect. The default value is **NET_PACKET_RX_CHECKSUM_NOT_CHECKED**, which means that the checksum will be validated in software further up in the networking stack. The client should also fill out the [**Layout**](net-packet-layout.md) member of the [**NET_PACKET**](net-packet.md) structure. + +The client driver must use NDIS functionality to enable checksum offloads. For more information, see [**NDIS_TCP_IP_CHECKSUM_OFFLOAD**](https://msdn.microsoft.com/en-us/library/windows/hardware/ff567878). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpacket.h
diff --git a/windows-driver-docs-pr/netcx/net-packet-declare-context-type-with-name.md b/windows-driver-docs-pr/netcx/net-packet-declare-context-type-with-name.md new file mode 100644 index 0000000000..134c190d33 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet-declare-context-type-with-name.md @@ -0,0 +1,134 @@ +--- +title: NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME macro +topic_type: +- apiref +api_name: +- NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME macro + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME macro creates an accessor method with a specified name for a client driver's object-specific context space. + +Syntax +------ + +```cpp +void NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME( +   _contexttype, +   _castingfunction +); +``` + +Parameters +---------- + +*_contexttype* +The structure type name of a driver-defined structure that describes the contents of an object's context space. + +*_castingfunction* +A C-language routine name. The macro uses this name as the name for the accessor method that it creates for the object's context space. You can put any name you like here; the macro will create a new function with this name. + +Return value +------------ + +This macro does not return a value. + +Remarks +------- + +You can use NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME to define one context per packet. The per-packet context area is optional. + +You may find it helpful to store hardware-specific or bus-specific data in each packet. + +NetAdapter automatically zeros the context area when the packet is created. +The context area is not zeroed out if a packet is reused. +If you need to initialize the context areas before the data path starts, initialize them in your [*EvtNetAdapterCreateTxQueue*](evt-net-adapter-create-txqueue.md) handler after calling [**NetTxQueueCreate**](nettxqueuecreate.md); or in the [*EvtNetAdapterCreateRxQueue*](evt-net-adapter-create-rxqueue.md) handler after calling [**NetRxQueueCreate**](netrxqueuecreate.md). + +Example +------- + +To declare a context area, use the NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME macro after declaring a structure in a header file: +``` +typedef struct _MY_TX_PACKET_CONTEXT { + ULONG MyFlags; + VOID *MyDescriptor; +} MY_TX_PACKET_CONTEXT; + +NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME(MY_TX_PACKET_CONTEXT, GetMyTxPacketContext); +``` + +Then, when the client creates a queue, associate the packet context with the queue: +``` +NET_TXQUEUE_CONFIG txQueueConfig; +NET_TXQUEUE_CONFIG_INIT(&txQueueConfig, . . .); +NET_TXQUEUE_CONFIG_SET_DEFAULT_PACKET_CONTEXT_TYPE(&txQueueConfig, MY_TX_PACKET_CONTEXT); + +status = NetTxQueueCreate(. . ., &txQueueConfig, . . .); + +// Optional: Initialize the context area of each packet to a non-zero value. +NET_RING_BUFFER *ringBuffer = NetTxQueueGetRingBuffer(txQueue); +for (UINT i = 0; i < ringBuffer->NumberOfElements; i++) { + NET_PACKET *packet = NetRingBufferGetPacketAtIndex(ringBuffer, i); + MY_TX_PACKET_CONTEXT *context = GetMyTxPacketContext(packet); + context->MyFlags = 0x1234; +} +``` + +While the data path is in operation, you can use the accessor method to get the context area of any packet: +``` +NET_PACKET *packet = NetRingBufferGetNextPacket(ringBuffer); +MY_TX_PACKET_CONTEXT *context = GetMyTxPacketContext(packet); +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)
+ +## See also + + +[**NetPacketGetTypedContext**](netpacketgettypedcontext.md) + +[**WDF_DECLARE_CONTEXT_TYPE_WITH_NAME**](https://msdn.microsoft.com/library/windows/hardware/ff551252) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-packet-filter-types-flags.md b/windows-driver-docs-pr/netcx/net-packet-filter-types-flags.md new file mode 100644 index 0000000000..26671169fa --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet-filter-types-flags.md @@ -0,0 +1,85 @@ +--- +title: NET_PACKET_FILTER_TYPES_FLAGS enumeration +topic_type: +- apiref +api_name: +- NET_PACKET_FILTER_TYPES_FLAGS +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NET_PACKET_FILTER_TYPES_FLAGS enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies packet filters that control the types of packets the NIC completes on its receive path. + +Syntax +------ + +```cpp +typedef enum _NET_PACKET_FILTER_TYPES_FLAGS { + NET_PACKET_FILTER_TYPE_DIRECTED        = 0x00000001, + NET_PACKET_FILTER_TYPE_MULTICAST       = 0x00000002, + NET_PACKET_FILTER_TYPE_ALL_MULTICAST   = 0x00000004, + NET_PACKET_FILTER_TYPE_BROADCAST       = 0x00000008, + NET_PACKET_FILTER_TYPE_PROMISCUOUS     = 0x00000020, +} NET_PACKET_FILTER_TYPES_FLAGS; +``` + +Constants +--------- + +**NET_PACKET_FILTER_TYPE_DIRECTED** +The NIC should receive directed packets that contain a destination address equal to the station address of the NIC. + +**NET_PACKET_FILTER_TYPE_MULTICAST** +Multicast address packets contain a destination address equal to one of the addresses in the multicast address list. + +**NET_PACKET_FILTER_TYPE_ALL_MULTICAST** +All multicast address packets, not just the ones enumerated in the multicast address list. + +**NET_PACKET_FILTER_TYPE_BROADCAST** +Broadcast packets. + +**NET_PACKET_FILTER_TYPE_PROMISCUOUS** +Specifies all packets regardless of whether VLAN filtering is enabled or not and whether the VLAN identifier matches or not. + +Remarks +------- +The **NET_PACKET_FILTER_TYPES_FLAGS** enumeration is used to specify supported packet filters in the [**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) structure. + +The client driver passes an initialized [**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) structure as an input parameter value to [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md). + +For info about the data path, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h
+ +See Also +----- +[**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) +[**OID_GEN_CURRENT_PACKET_FILTER**](https://msdn.microsoft.com/library/windows/hardware/ff569575) diff --git a/windows-driver-docs-pr/netcx/net-packet-fragment.md b/windows-driver-docs-pr/netcx/net-packet-fragment.md new file mode 100644 index 0000000000..ddc322e317 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet-fragment.md @@ -0,0 +1,123 @@ +--- +title: NET_PACKET_FRAGMENT structure +--- + +# NET_PACKET_FRAGMENT structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Represents one contiguous buffer in memory. + +Syntax +------ + +```cpp +typedef struct _NET_PACKET_FRAGMENT { + ULONG_PTR         LastFragmentOfFrame :1; + ULONG_PTR         LastPacketOfChain :1; +#if _WIN64 + ULONG_PTR         Reserved :3; + ULONG_PTR         NextFragment_Reserved :59; +#else + ULONG_PTR         Reserved :1; + ULONG_PTR         NextFragment_Reserved :29; +#endif + PHYSICAL_ADDRESS DmaLogicalAddress; + PVOID             VirtualAddress; + UINT64            ValidLength :26; + UINT64            Capacity :26; + UINT64            Offset :10; + UINT64            Completed :1; + UINT64            Scratch :1; +} NET_PACKET_FRAGMENT, *PNET_PACKET_FRAGMENT; +``` + +Members +------- + +**LastFragmentOfFrame** +This bit field value specifies whether this is the last fragment in the current packet. If it is not set, use **NET_PACKET_FRAGMENT_GET_NEXT** to get the next fragment in the chain. + +**LastPacketOfChain** +Reserved. +Client drivers must not read or write to this value. + +**Reserved** +Reserved. +Client drivers must not read or write to this value. + +**NextFragment_Reserved** +Reserved. +Client drivers must not read or write to this value. + +**DmaLogicalAddress** +For receive queues, contains a mapped DMA address that can be used to program NIC hardware. + +For transmit queues, cast this value to an MDL pointer. + +Do not modify this value. + +**VirtualAddress** +Points to the start of the packet buffer. +This address is mapped into the system address space. + +For transmit queues, this value is read-only. + +**ValidLength** +Contains the length of packet payload. This value is less than or equal to the value of **Capacity**. + +For transmit queues, this value is read-only. + +**Capacity** +Contains the total length of the packet buffer. + +For transmit queues, this value is read-only. + +**Offset** +Contains the offset from the start of the `VirtualAddress` and `DmaLogicalAddress` to the start of the valid packet payload. This value is less than or equal to the value of **Capacity**. + +For transmit queues, this value is read-only. + +**Completed** +A bit field value that, when set for the first fragment of a [**NET_PACKET**](net-packet.md), specifies that this packet should be completed when the client calls [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md). + +Do not use this flag on fragments other than the first fragment of a packet. + +**Scratch** +A bit field value that the client may use for any purpose. When the [**NET_PACKET**](net-packet.md) is reused, this value is reset to zero. + +Remarks +------- + +The **NET_PACKET_FRAGMENT** structure is similar in concept to a memory descriptor list (MDL). + +A single [**NET_PACKET**](net-packet.md) structure contains references to one or more **NET_PACKET_FRAGMENT** structures. + +While each fragment is a virtually contiguous buffer of memory, a packet that contains more than one fragment is virtually discontiguous. + +The client driver should not unlink, append, or rearrange **NET_PACKET_FRAGMENT** structures within a [**NET_PACKET**](net-packet.md) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpacket.h
\ No newline at end of file diff --git a/windows-driver-docs-pr/netcx/net-packet-layout.md b/windows-driver-docs-pr/netcx/net-packet-layout.md new file mode 100644 index 0000000000..3cedee398b --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet-layout.md @@ -0,0 +1,111 @@ +--- +title: NET_PACKET_LAYOUT structure +--- + +# NET_PACKET_LAYOUT structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +A **NET_PACKET_LAYOUT** structure describes the start of each protocol header in a packet. + +Syntax +------ + +```cpp +typedef struct _NET_PACKET_LAYOUT +{ + UINT8 Layer2Type : 4; + UINT8 Layer3Type : 4; + UINT8 Layer4Type : 4; + UINT8 Reserved : 4; + UINT16 Layer2HeaderLength : 7; + UINT16 Layer3HeaderLength : 9; + UINT8 Layer4HeaderLength : 8; + +} NET_PACKET_LAYOUT; +``` + +Members +------- + +**Layer2Type** +An enumeration that specifies a flag from **NET_PACKET_LAYER2_TYPE**. + +```cpp +typedef enum _NET_PACKET_LAYER2_TYPE +{ + NET_PACKET_LAYER2_TYPE_UNSPECIFIED = 0, + NET_PACKET_LAYER2_TYPE_NULL = 1, + NET_PACKET_LAYER2_TYPE_ETHERNET = 2, +} NET_PACKET_LAYER2_TYPE; +``` + +**Layer3Type** +An enumeration that specifies a flag from **NET_PACKET_LAYER3_TYPE**. + +```cpp +typedef enum _NET_PACKET_LAYER3_TYPE +{ + NET_PACKET_LAYER3_TYPE_UNSPECIFIED = 0, + NET_PACKET_LAYER3_TYPE_IPV4_UNSPECIFIED_OPTIONS = 1, + NET_PACKET_LAYER3_TYPE_IPV4_WITH_OPTIONS = 2, + NET_PACKET_LAYER3_TYPE_IPV4_NO_OPTIONS = 3, + NET_PACKET_LAYER3_TYPE_IPV6_UNSPECIFIED_EXTENSIONS = 4, + NET_PACKET_LAYER3_TYPE_IPV6_WITH_EXTENSIONS = 5, + NET_PACKET_LAYER3_TYPE_IPV6_NO_EXTENSIONS = 6, +} NET_PACKET_LAYER3_TYPE; +``` + +**Layer4Type** +An enumeration that specifies a flag from **NET_PACKET_LAYER4_TYPE**. + +```cpp +typedef enum _NET_PACKET_LAYER4_TYPE +{ + NET_PACKET_LAYER4_TYPE_UNSPECIFIED = 0, + NET_PACKET_LAYER4_TYPE_TCP = 1, + NET_PACKET_LAYER4_TYPE_UDP = 2, + NET_PACKET_LAYER4_TYPE_IP_NOT_FRAGMENTED = 3, + NET_PACKET_LAYER4_TYPE_IP_FRAGMENT = 4, +} NET_PACKET_LAYER4_TYPE; +``` + +**Reserved** +Reserved for system use. + +**Layer2HeaderLength** +The length in bytes of the Layer 2 header, or zero if the Layer 2 length is unknown. + +**Layer3HeaderLength** +The length in bytes of the Layer 3 header, or zero if the Layer 3 length is unknown. + +**Layer4HeaderLength** +The length of the Layer 4 header, or zero if the Layer 4 length is unknown. + +Remarks +------- +See more info in the description of the **Layout** member of [**NET_PACKET**](net-packet.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpacket.h
diff --git a/windows-driver-docs-pr/netcx/net-packet.md b/windows-driver-docs-pr/netcx/net-packet.md new file mode 100644 index 0000000000..bd8b08a49c --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-packet.md @@ -0,0 +1,112 @@ +--- +title: NET_PACKET structure +--- + +# NET_PACKET structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Represents a single network packet. + +Syntax +------ + +```cpp +typedef struct _NET_PACKET { + NET_PACKET_FRAGMENT Data; + NET_PACKET_LAYOUT   Layout; + NET_PACKET_CHECKSUM Checksum; + UINT16              IgnoreThisPacket :1; + UINT16              AdvancedOffloadRequested :1; + UINT16              Reserved1 :14; + UINT32              Hash; + UINT32              Reserved2; + PVOID               Reserved3; +} NET_PACKET, *PNET_PACKET; +``` + +Members +------- + +**Data** + +A structure of type [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) that describes the first fragment of the packet payload. See the **LastFragmentOfFrame** member of the [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) structure to determine if this packet is associated with additional fragments. + +**Layout** +A structure of type [**NET_PACKET_LAYOUT**](net-packet-layout.md). + +* For transmit queues, if the host stack has enabled a task offload that uses a protocol header, specifies a read-only offset to each protocol field. For example, if TCP checksum offload is enabled, this member specifies the offset to the TCP header. Otherwise, this member is empty. + +* For receive queues, this member is reserved. + +**Checksum** +A structure of type [**NET_PACKET_CHECKSUM**](net-packet-checksum.md). + +* For transmit queues, this member is read-only and specifies whether the client driver should perform checksum offload. + +* For receive queues, if the NIC hardware performed a checksum validation, specifies the result of the validation. + +**IgnoreThisPacket** +* For receive queues, the client sets this bit to prevent the packet from being indicated to the host. +For example, if the hardware encountered a DMA error while writing bytes into this the data buffer for this packet, the client can set this bit to drop the partial packet. + +* For transmit queues, this bit is read-only. If set, it indicates that the client should not transmit the packet. + +**AdvancedOffloadRequested** +Reserved. +Do not read or write to this value. + +**Reserved1** +Reserved. +Do not read or write to this value. + +**Hash** +Reserved. +Do not read or write to this value. + +**Reserved2** +Reserved. +Do not read or write to this value. + +**Reserved3** +Reserved. +Do not read or write to this value. + +Remarks +------- +Each [**NET_PACKET**](net-packet.md) structure represents a single network frame. + +The **NET_PACKET** structure can be an element in a [**NET_RING_BUFFER**](net-ring-buffer.md) structure. + +You can optionally use [**NetRingBufferGetPacketAtIndex**](netringbuffergetpacketatindex.md) or [**NetRingBufferGetNextPacket**](netringbuffergetnextpacket.md) to obtain a **NET_PACKET** from a ring buffer. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpacket.h
+ + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-method-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-method-handler.md new file mode 100644 index 0000000000..00f3a862e7 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-method-handler.md @@ -0,0 +1,85 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided, pre-initialized custom request handler structure to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG         NetRequestQueueConfig, + _In_ PNET_REQUEST_QUEUE_METHOD_HANDLER MethodHandler +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the custom handler is being added. + +*MethodHandler* [in] +A pointer to a driver-allocated and initialized [**NET_REQUEST_QUEUE_METHOD_HANDLER**](net-request-queue-method-handler.md) structure. The client driver must call [**NET_REQUEST_QUEUE_METHOD_HANDLER_INIT**](net-request-queue-method-handler-init.md) method to initialize the custom handler before calling this function. + +Return value +------------ + +This method does not return a value. + +Remarks +------- +When the client driver has finished adding custom handlers, it registers them with NetAdapterCx by calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-query-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-query-data-handler.md new file mode 100644 index 0000000000..135ab5e750 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-query-data-handler.md @@ -0,0 +1,92 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided, pre-initialized query data handler to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG             NetRequestQueueConfig, + _In_ PNET_REQUEST_QUEUE_QUERY_DATA_HANDLER QueryDataHandler +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the query data handler is being added. + +*QueryDataHandler* [in] +A pointer to a driver-allocated and initialized [**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER**](net-request-queue-query-data-handler.md) structure. The client driver must call [**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT**](net-request-queue-query-data-handler-init.md) method to initialize the custom handler before calling this function. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) + +[**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER**](net-request-queue-query-data-handler.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-set-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-set-data-handler.md new file mode 100644 index 0000000000..8f6abcc8bb --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-initialized-set-data-handler.md @@ -0,0 +1,84 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_SET_DATA_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_SET_DATA_HANDLER method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided, pre-initialized custom request handler to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG           NetRequestQueueConfig, + _In_ PNET_REQUEST_QUEUE_SET_DATA_HANDLER SetDataHandler +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the custom handler is being added. + +*SetDataHandler* [in] +A pointer to a driver-allocated and initialized [**NET_REQUEST_QUEUE_SET_DATA_HANDLER**](net-request-queue-set-data-handler.md) structure. The client driver must call [**NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT**](net-request-queue-set-data-handler-init.md) method to initialize the custom handler before calling this function. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-method-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-method-handler.md new file mode 100644 index 0000000000..4be183aa49 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-method-handler.md @@ -0,0 +1,103 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided handler for a specific OID method request to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE +VOID +NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_ NDIS_OID Oid, + _In_ PFN_NET_REQUEST_METHOD EvtRequestMethod, + _In_ UINT MinimumInputLength, + _In_ UINT MinimumOutputLength +) +``` + +Parameters +---------- + +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the custom handler is being added. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*EvtRequestMethod* [in] +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_METHOD*](evt-net-request-method.md) event callback function. + +*MinimumInputLength* [in] +A UINT specifying the minimum input length for the request. + +*MinimumOutputLength* [in] +A UINT specifying the minimum output length for the request. + +Return value +------------ + +This method does not return a value. + +Remarks +------- +When the client driver has finished adding custom handlers, it registers them with NetAdapterCx by calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +This function has the same effect as the following call sequence: + +1. [**NET_REQUEST_QUEUE_METHOD_HANDLER_INIT**](net-request-queue-method-handler-init.md) +2. [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER**](net-request-queue-config-add-initialized-method-handler.md) + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-query-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-query-data-handler.md new file mode 100644 index 0000000000..4ddd1ca196 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-query-data-handler.md @@ -0,0 +1,99 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided handler for a specific OID query data request to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE +VOID +NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_ NDIS_OID Oid, + _In_ PFN_NET_REQUEST_QUERY_DATA EvtRequestQueryData, + _In_ UINT MinimumOutputLength +) +``` + +Parameters +---------- +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the custom handler is being added. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*EvtRequestQueryData* [in] +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_QUERY_DATA*](evt-net-request-query-data.md) event callback function. + +*MinimumOutputLength* [in] +A UINT specifying the minimum output length for the request. + +Return value +------------ + +This method does not return a value. + +Remarks +------- +When the client driver has finished adding custom handlers, it registers them with NetAdapterCx by calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +This function has the same effect as the following call sequence: + +1. [**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT**](net-request-queue-query-data-handler-init.md) +2. [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_QUERY_DATA_HANDLER**](net-request-queue-config-add-initialized-query-data-handler.md) + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-add-set-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-config-add-set-data-handler.md new file mode 100644 index 0000000000..f1e1ab7aa8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-add-set-data-handler.md @@ -0,0 +1,99 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Adds a caller-provided handler for a specific OID set data request to a [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +FORCEINLINE +VOID +NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER( + _In_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_ NDIS_OID Oid, + _In_ PFN_NET_REQUEST_SET_DATA EvtRequestSetData, + _In_ UINT MinimumInputLength, +) +``` + +Parameters +---------- +*NetRequestQueueConfig* [in] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to which the custom handler is being added. + +*Oid* [in] +The object identifier of the requested operation. The value is an OID_ *XXX* code. + +*EvtRequestSetData* [in] +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_SET_DATA*](evt-net-request-set-data.md) event callback function. + +*MinimumInputLength* [in] +A UINT specifying the minimum input length for the request. + +Return value +------------ + +This method does not return a value. + +Remarks +------- +When the client driver has finished adding custom handlers, it registers them with NetAdapterCx by calling [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +If the memory allocation for this method fails, the subsequent call to [**NetRequestQueueCreate**](netrequestqueuecreate.md) returns a failure code. + +This function has the same effect as the following call sequence: + +1. [**NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT**](net-request-queue-set-data-handler-init.md) +2. [**NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_SET_DATA_HANDLER**](net-request-queue-config-add-initialized-set-data-handler.md) + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-parallel.md b/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-parallel.md new file mode 100644 index 0000000000..9a3f83f776 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-parallel.md @@ -0,0 +1,78 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the caller-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to create a default direct request queue for direct control requests (OIDs). + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL( + _Out_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_  NETADAPTER                Adapter +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [out] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +*Adapter* [in] +The NDIS adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-sequential.md b/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-sequential.md new file mode 100644 index 0000000000..a40cf34ef9 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-init-default-sequential.md @@ -0,0 +1,78 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_ADD_INITIALIZED_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the caller-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure to create a default sequential request queue for normal control requests (OIDs). + +Syntax +------ + +```cpp +FORCEINLINE VOID NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL( + _Out_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_  NETADAPTER                Adapter +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [out] +A pointer to a driver-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +*Adapter* [in] +The NDIS adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config-init.md b/windows-driver-docs-pr/netcx/net-request-queue-config-init.md new file mode 100644 index 0000000000..4f1568dad8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config-init.md @@ -0,0 +1,84 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG_INIT method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG_INIT +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the caller-allocated [NET_REQUEST_QUEUE_CONFIG](net-request-queue-config.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_REQUEST_QUEUE_CONFIG_INIT( + _Out_ PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_  NETADAPTER                Adapter, + _In_  NET_REQUEST_QUEUE_TYPE    QueueType +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [out] +A pointer to the driver-allocated NET_REQUEST_QUEUE_CONFIG structure. + +*Adapter* [in] +The NDIS adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*QueueType* [in] +A [NET_REQUEST_QUEUE_TYPE](net-request-queue-type.md) enumeration that specifies the type of queue. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-config.md b/windows-driver-docs-pr/netcx/net-request-queue-config.md new file mode 100644 index 0000000000..b798aa65f4 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-config.md @@ -0,0 +1,122 @@ +--- +title: NET_REQUEST_QUEUE_CONFIG structure +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_CONFIG +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_CONFIG structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver must call [NET_REQUEST_QUEUE_CONFIG_INIT](net-request-queue-config-init.md) to initialize this structure. + +Syntax +------ + +```cpp +typedef struct _NET_REQUEST_QUEUE_CONFIG { + ULONG Size; + NETADAPTER Adapter; + NET_REQUEST_QUEUE_TYPE Type; + PFN_NET_REQUEST_DEFAULT_SET_DATA EvtRequestDefaultSetData; + PFN_NET_REQUEST_DEFAULT_QUERY_DATA EvtRequestDefaultQueryData; + PFN_NET_REQUEST_DEFAULT_METHOD EvtRequestDefaultMethod; + PFN_NET_REQUEST_DEFAULT EvtRequestDefault; + NET_REQUEST_QUEUE_ADD_HANDLER_ERROR AddHandlerError; + ULONG SizeOfSetDataHandler; + ULONG                                   SizeOfQueryDataHandler; + ULONG                                   SizeOfMethodHandler; + PNET_REQUEST_QUEUE_SET_DATA_HANDLER     SetDataHandlers; + PNET_REQUEST_QUEUE_QUERY_DATA_HANDLER   QueryDataHandlers; + PNET_REQUEST_QUEUE_METHOD_HANDLER       MethodHandlers; +} NET_REQUEST_QUEUE_CONFIG, *PNET_REQUEST_QUEUE_CONFIG; +``` + +Members +------- + +**Size** +Size of the structure. + +**Adapter** +The NDIS adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +**Type** +A [NET_REQUEST_QUEUE_TYPE](net-request-queue-type.md) enumeration that specifies the type of queue. + +**EvtRequestDefaultSetData** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_DEFAULT_SET_DATA*](evt-net-request-default-set-data.md) event callback function. + +**EvtRequestDefaultQueryData** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_DEFAULT_QUERY_DATA*](evt-net-request-default-query-data.md) event callback function. + +**EvtRequestDefaultMethod** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_DEFAULT_METHOD*](evt-net-request-default-method.md) event callback function. + +**EvtRequestDefault** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_DEFAULT*](evt-net-request-default.md) event callback function. + +**AddHandlerError** +A bit field tracking any errors encountered during Add custom handler operation. + +**SizeOfSetDataHandler** +A ULONG that specifies the size of the SetDataHandlers member. + +**SizeOfQueryDataHandler** +A ULONG that specifies the size of the QueryDataHandlers member. + +**SizeOfMethodHandler** +A ULONG that specifies the size of the MethodHandlers member. + +**SetDataHandlers** +Pointer to the first [**NET_REQUEST_QUEUE_SET_DATA_HANDLER**](net-request-queue-set-data-handler.md) structure of the custom set handler list. + +**QueryDataHandlers** +Pointer to the first [**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER**](net-request-queue-query-data-handler.md) structure of the custom query handler list. + +**MethodHandlers** +Pointer to the first [**NET_REQUEST_QUEUE_METHOD_HANDLER**](net-request-queue-method-handler.md) structure of the custom method handler list. + +Remarks +----- +The client driver passes an initialized [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure as an input parameter value to [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-method-handler-init.md b/windows-driver-docs-pr/netcx/net-request-queue-method-handler-init.md new file mode 100644 index 0000000000..a455e4e761 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-method-handler-init.md @@ -0,0 +1,92 @@ +--- +title: NET_REQUEST_QUEUE_METHOD_HANDLER_INIT method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_METHOD_HANDLER_INIT +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_METHOD_HANDLER_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_REQUEST_QUEUE_METHOD_HANDLER](net-request-queue-method-handler.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_REQUEST_QUEUE_METHOD_HANDLER_INIT( + _Out_ PNET_REQUEST_QUEUE_METHOD_HANDLER MethodHandler, + _In_  NDIS_OID                          Oid, + _In_  PFN_NET_REQUEST_METHOD            EvtRequestMethod, + _In_  UINT                              MinimumInputLength, + _In_  UINT                              MinimumOutputLength +); +``` + +Parameters +---------- + +*MethodHandler* [out] +A pointer to the driver-allocated [**NET_REQUEST_QUEUE_METHOD_HANDLER**](net-request-queue-method-handler.md) structure. + +*Oid* [in] +The NDIS_OID identifier for the request. + +*EvtRequestMethod* [in] +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_METHOD*](evt-net-request-method.md) event callback function. + +*MinimumInputLength* [in] +The needed minimum input length for the request. + +*MinimumOutputLength* [in] +The needed minimum output length for the request. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-method-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-method-handler.md new file mode 100644 index 0000000000..76de84c38a --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-method-handler.md @@ -0,0 +1,85 @@ +--- +title: NET_REQUEST_QUEUE_METHOD_HANDLER structure +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_METHOD_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_METHOD_HANDLER structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Reserved for internal use. Call [**NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER**](net-request-queue-config-add-method-handler.md) to add a caller-provided handler for a specific OID method request. + +Syntax +------ + +```cpp +typedef struct _NET_REQUEST_QUEUE_METHOD_HANDLER { + PNET_REQUEST_QUEUE_METHOD_HANDLER Next; + WDFMEMORY Memory; + NDIS_OID Oid; + PFN_NET_REQUEST_METHOD EvtRequestMethod; + UINT MinimumInputLength; + UINT MinimumOutputLength; +} NET_REQUEST_QUEUE_METHOD_HANDLER, *PNET_REQUEST_QUEUE_METHOD_HANDLER; +``` + +Members +------- + +**Next** +A pointer to the next custom handler. + +**Memory** +Reserved for internal use. + +**Oid** +Specifies the object identifier of the requested operation. The value is an OID_XXX code. + +**EvtRequestMethod** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_METHOD*](evt-net-request-method.md) event callback function. + +**MinimumInputLength** +Minimum input length needed by the client for this request. + +**MinimumOutputLength** +Minimum output length needed by the client for this request. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler-init.md b/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler-init.md new file mode 100644 index 0000000000..7c3806684f --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler-init.md @@ -0,0 +1,88 @@ +--- +title: NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_REQUEST_QUEUE_QUERY_DATA_HANDLER](net-request-queue-query-data-handler.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_REQUEST_QUEUE_QUERY_DATA_HANDLER_INIT( + _Out_ PNET_REQUEST_QUEUE_QUERY_DATA_HANDLER QueryDataHandler, + _In_  NDIS_OID                              Oid, + _In_  PFN_NET_REQUEST_QUERY_DATA            EvtRequestQueryData, + _In_  UINT                                  MinimumOutputLength +); +``` + +Parameters +---------- + +*QueryDataHandler* [out] +A pointer to the driver-allocated [**NET_REQUEST_QUEUE_QUERY_DATA_HANDLER**](net-request-queue-query-data-handler.md) structure. + +*Oid* [in] +The NDIS_OID identifier for the request. + +*EvtRequestQueryData* [in] +Pointer to the custom query request handler. + +*MinimumOutputLength* [in] +The needed minimum output length for the request. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler.md new file mode 100644 index 0000000000..9150629b94 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-query-data-handler.md @@ -0,0 +1,85 @@ +--- +title: NET_REQUEST_QUEUE_QUERY_DATA_HANDLER structure +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_QUERY_DATA_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_QUERY_DATA_HANDLER structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Reserved for internal use. Call [**NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER**](net-request-queue-config-add-query-data-handler.md) to add a caller-provided handler for a specific OID query data request. + +Syntax +------ + +```cpp +typedef struct _NET_REQUEST_QUEUE_QUERY_DATA_HANDLER { + PNET_REQUEST_QUEUE_QUERY_DATA_HANDLER Next; + WDFMEMORY   Memory; + NDIS_OID Oid; + PFN_NET_REQUEST_QUERY_DATA EvtRequestQueryData; + UINT MinimumInputLength; + UINT MinimumOutputLength; +} NET_REQUEST_QUEUE_QUERY_DATA_HANDLER, *PNET_REQUEST_QUEUE_QUERY_DATA_HANDLER; +``` + +Members +------- + +**Next** +A pointer to the next custom handler. + +**Memory** +Reserved for internal use. + +**Oid** +Specifies the object identifier of the requested operation. The value is an OID_XXX code. + +**EvtRequestQueryData** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_QUERY_DATA*](evt-net-request-query-data.md) event callback function. + +**MinimumInputLength** +Minimum input length needed by the client for this request. + +**MinimumOutputLength** +Minimum output length needed by the client for this request. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler-init.md b/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler-init.md new file mode 100644 index 0000000000..d592c26158 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler-init.md @@ -0,0 +1,88 @@ +--- +title: NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT method +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_REQUEST_QUEUE_SET_DATA_HANDLER](net-request-queue-set-data-handler.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_REQUEST_QUEUE_SET_DATA_HANDLER_INIT( + _Out_ PNET_REQUEST_QUEUE_SET_DATA_HANDLER SetDataHandler, + _In_  NDIS_OID                            Oid, + _In_  PFN_NET_REQUEST_SET_DATA            EvtRequestSetData, + _In_  UINT                                MinimumInputLength +); +``` + +Parameters +---------- + +*SetDataHandler* [out] +A pointer to the driver-allocated [**NET_REQUEST_QUEUE_SET_DATA_HANDLER**](net-request-queue-set-data-handler.md) structure. + +*Oid* [in] +The NDIS_OID identifier for the request. + +*EvtRequestSetData* [in] +Pointer to the custom set request handler. + +*MinimumInputLength* [in] +The needed minimum input length for the request. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrequestqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler.md b/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler.md new file mode 100644 index 0000000000..46d6617639 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-set-data-handler.md @@ -0,0 +1,85 @@ +--- +title: NET_REQUEST_QUEUE_SET_DATA_HANDLER structure +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_SET_DATA_HANDLER +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_SET_DATA_HANDLER structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Reserved for internal use. Call [**NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER**](net-request-queue-config-add-set-data-handler.md) to add a caller-provided handler for a specific OID set data request. + +Syntax +------ + +```cpp +typedef struct _NET_REQUEST_QUEUE_SET_DATA_HANDLER { + PNET_REQUEST_QUEUE_SET_DATA_HANDLER Next; + WDFMEMORY Memory; + NDIS_OID Oid; + PFN_NET_REQUEST_SET_DATA EvtRequestSetData; + UINT MinimumInputLength; + UINT MinimumOutputLength; +} NET_REQUEST_QUEUE_SET_DATA_HANDLER, *PNET_REQUEST_QUEUE_SET_DATA_HANDLER; +``` + +Members +------- + +**Next** +A pointer to the next custom handler. + +**Memory** +Reserved for internal use. + +**Oid** +Specifies the object identifier of the requested operation. The value is an OID_XXX code. + +**EvtRequestSetData** +Pointer to the client driver's implementation of a [*EVT_NET_REQUEST_SET_DATA*](evt-net-request-set-data.md) event callback function. + +**MinimumInputLength** +Minimum input length needed by the client for this request. + +**MinimumOutputLength** +Minimum output length needed by the client for this request. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-request-queue-type.md b/windows-driver-docs-pr/netcx/net-request-queue-type.md new file mode 100644 index 0000000000..30e0294d51 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-request-queue-type.md @@ -0,0 +1,80 @@ +--- +title: NET_REQUEST_QUEUE_TYPE enumeration +topic_type: +- apiref +api_name: +- NET_REQUEST_QUEUE_TYPE +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NET_REQUEST_QUEUE_TYPE enumeration + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies the type of queue. + +Syntax +------ + +```cpp +typedef enum _NET_REQUEST_QUEUE_TYPE { + NetRequestQueueTypeInvalid, + NetRequestQueueDefaultSequential, + NetRequestQueueDefaultParallel +} NET_REQUEST_QUEUE_TYPE; +``` + +Constants +--------- + +**NetRequestQueueTypeInvalid** +Not supported. + +**NetRequestQueueDefaultSequential** +Specifies that the queue supports sequential delivery (normal control requests, or OIDs). + +**NetRequestQueueDefaultParallel** +Specifies that the queue supports parallel dispatching (direct control requests, or OIDs). + + +Remarks +------- +The **NET_REQUEST_QUEUE_TYPE** enumeration is used to specify queue type in the [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +The client driver passes an initialized [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure as an input parameter value to [**NetRequestQueueCreate**](netrequestqueuecreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-ring-buffer.md b/windows-driver-docs-pr/netcx/net-ring-buffer.md new file mode 100644 index 0000000000..469d22fde3 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-ring-buffer.md @@ -0,0 +1,114 @@ +--- +title: NET_RING_BUFFER structure +topic_type: +- apiref +api_name: +- NET_RING_BUFFER +api_location: +- netringbuffer.h +api_type: +- HeaderDef +--- + +# NET_RING_BUFFER structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Specifies a buffer comprised of one or more [**NET_PACKET**](net-packet.md) structures. + +Syntax +------ + +```cpp +typedef struct _NET_RING_BUFFER { + UINT16                                              OSReserved1; + UINT16                                              ElementStride; + UINT32                                              NumberOfElements; + UINT32                                              ElementIndexMask; + UINT32                                              BeginIndex; + UINT32                                              NextIndex; + UINT32                                              EndIndex; + VOID                                                *NetAdapterScratch[2]; + VOID                                                *OSReserved2[3]; + _Field_size_(NumberOfElements * ElementStride) BYTE Buffer[]; +} NET_RING_BUFFER, *PNET_RING_BUFFER; +``` + +Members +------- + +**OSReserved1** +Reserved. +Client drivers must not read or write to this value. + +**ElementStride** +A read-only byte offset from the start of one **NET_PACKET** to the start of the next. Use `((BYTE*)p + ElementStride)` to obtain the address of the next element. + +**NumberOfElements** +A read-only value that indicates the number of packets in the ring buffer, which is always a power of two, and greater than one. + +**ElementIndexMask** +A read-only UINT32 mask that is defined as (**NumberOfElements**-1). The client can use this value to calculate an index that wraps around the ring buffer. Use the identity `(x % NumberofElements) == (x & ElementIndexMask)`. + +**BeginIndex** +Specifies the index of the first element owned by the client driver in the inclusive range [0, **NumberOfElements**-1]. +While a client driver can modify this value directly, it typically uses helper routines like [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md) instead. + +**NextIndex** +Specifies the index of the next element that needs processing. For optional use by the client driver. +While a client driver can modify this value directly, it typically calls [**NetRingBufferAdvanceNextPacket**](netringbufferadvancenextpacket.md) instead. + +**EndIndex** +Specifies the read-only index of the last element that is owned by the client driver in the inclusive range [0, **NumberOfElements**-1]. + +**NetAdapterScratch** +A pointer to a buffer that the client driver may use for any purpose. + +**OSReserved2** +Reserved. +Client drivers must not read or write to this value. + +**Buffer** +A byte array that contains the packets in the ring buffer. +Typically, a client driver calls [**NetRingBufferGetPacketAtIndex**](netringbuffergetpacketatindex.md) to access packets in the ring buffer. + +Remarks +------- + +The **NET_RING_BUFFER** is a generic ring buffer, optimized for efficient access from a single thread. +A **NET_RING_BUFFER** contains elements of type [**NET_PACKET**](net-packet.md). + +For more info about the ring buffer, see [Transferring Network Data](transferring-network-data.md#using-the-ring-buffer). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netringbuffer.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-rxqueue-config-init.md b/windows-driver-docs-pr/netcx/net-rxqueue-config-init.md new file mode 100644 index 0000000000..8a16fd36be --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-rxqueue-config-init.md @@ -0,0 +1,88 @@ +--- +title: NET_RXQUEUE_CONFIG_INIT method +topic_type: +- apiref +api_name: +- NET_RXQUEUE_CONFIG_INIT +api_location: +- netrxqueue.h +api_type: +- HeaderDef +--- + +# NET_RXQUEUE_CONFIG_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_RXQUEUE_CONFIG](net-rxqueue-config.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_RXQUEUE_CONFIG_INIT( + _Out_ PNET_RXQUEUE_CONFIG                  NetRxQueueConfig, + _In_  PFN_RXQUEUE_ADVANCE                  EvtRxQueueAdvance, + _In_  PFN_RXQUEUE_SET_NOTIFICATION_ENABLED EvtRxQueueSetNotificationEnabled, + _In_  PFN_RXQUEUE_CANCEL                   EvtRxQueueCancel +); +``` + +Parameters +---------- + +*NetRxQueueConfig* [out] +A pointer to the driver-allocated [**NET_RXQUEUE_CONFIG**](net-rxqueue-config.md) structure. + +*EvtRxQueueAdvance* [in] +A pointer to the driver's [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) callback function. + +*EvtRxQueueSetNotificationEnabled* [in] +A pointer to the driver's [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) callback function. + +*EvtRxQueueCancel* [in] +A pointer to the driver's [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md) callback function. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Netrxqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-rxqueue-config.md b/windows-driver-docs-pr/netcx/net-rxqueue-config.md new file mode 100644 index 0000000000..3cc6a16806 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-rxqueue-config.md @@ -0,0 +1,102 @@ +--- +title: NET_RXQUEUE_CONFIG structure +topic_type: +- apiref +api_name: +- NET_RXQUEUE_CONFIG +api_location: +- netrxqueue.h +api_type: +- HeaderDef +--- + +# NET_RXQUEUE_CONFIG structure + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Describes the configuration options for a NetAdapterCx client driver's receive queue. + +Syntax +------ + +```cpp +typedef struct _NET_RXQUEUE_CONFIG { + ULONG                                Size; + PFN_RXQUEUE_CANCEL                   EvtRxQueueCancel; + PFN_RXQUEUE_SET_NOTIFICATION_ENABLED EvtRxQueueSetNotificationEnabled; + PFN_RXQUEUE_ADVANCE                  EvtRxQueueAdvance; + PCNET_CONTEXT_TYPE_INFO              ContextTypeInfo; + ULONG                                AllocationSize; + ULONG                                AlignmentRequirement; +} NET_RXQUEUE_CONFIG, *PNET_RXQUEUE_CONFIG; +``` + +Members +------- + +**Size** +The size, in bytes, of this structure. + +**EvtRxQueueCancel** +A pointer to the client driver's [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md) event callback function. This callback function is required. + +**EvtRxQueueSetNotificationEnabled** +A pointer to the client driver's [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) event callback function. This callback function is required. + +**EvtRxQueueAdvance** +A pointer to the client driver's [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) event callback function. This callback function is required. + +**ContextTypeInfo** +A pointer to a [**WDF_OBJECT_CONTEXT_TYPE_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff552407) structure. + +**AllocationSize** +Size of each receive buffer. If non-zero, NetAdapterCx allocates receive buffers for each packet in the queue's ring buffer. If the client called [**NetRxQueueConfigureDmaAllocator**](netrxqueueconfiguredmaallocator.md), NetAdapterCx pre-maps virtual addresses in the receive buffers to fixed physical addresses. If zero, the client provides a receive buffer for each receive fragment. + +**AlignmentRequirement** +The alignment requirement, in bytes, for each receive buffer. This value must be one less than the alignment boundary. For example, specify 15 for a 16-byte alignment boundary. You can also use one of the FILE_Xxxx_ALIGNMENT constants that are defined in Wdm.h. If unspecified, **AlignmentRequirement** defaults to the value returned by [**WdfDeviceGetAlignmentRequirement**](https://msdn.microsoft.com/en-us/library/windows/hardware/ff545953) for the adapter's associated device object. + +Remarks +------- + +Call [**NET_RXQUEUE_CONFIG_INIT**](net-rxqueue-config-init.md) to initialize this structure. + +The **NET_RXQUEUE_CONFIG** structure is an input parameter to [**NetRxQueueCreate**](netrxqueuecreate.md). The client must use [**NET_RXQUEUE_CONFIG_INIT**](net-rxqueue-config-init.md) to initialize this structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h
+ +## See also + + +[**NetRxQueueConfigureDmaAllocator**](netrxqueueconfiguredmaallocator.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/net-txqueue-config-init.md b/windows-driver-docs-pr/netcx/net-txqueue-config-init.md new file mode 100644 index 0000000000..45926eee2e --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-txqueue-config-init.md @@ -0,0 +1,88 @@ +--- +title: NET_TXQUEUE_CONFIG_INIT method +topic_type: +- apiref +api_name: +- NET_TXQUEUE_CONFIG_INIT +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NET_TXQUEUE_CONFIG_INIT method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes the [NET_TXQUEUE_CONFIG](net-txqueue-config.md) structure. + +Syntax +------ + +```cpp +__inline +void NET_TXQUEUE_CONFIG_INIT( + _Out_ PNET_TXQUEUE_CONFIG                  NetTxQueueConfig, + _In_  PFN_TXQUEUE_ADVANCE                  EvtTxQueueAdvance, + _In_  PFN_TXQUEUE_SET_NOTIFICATION_ENABLED EvtTxQueueSetNotificationEnabled, + _In_  PFN_TXQUEUE_CANCEL                   EvtTxQueueCancel +); +``` + +Parameters +---------- + +*NetTxQueueConfig* [out] +A pointer to the driver-allocated [**NET_TXQUEUE_CONFIG**](net-txqueue-config.md) structure. + +*EvtTxQueueAdvance* [in] +A pointer to the driver's [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) callback function. + +*EvtTxQueueSetNotificationEnabled* [in] +A pointer to the driver's [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) callback function. + +*EvtTxQueueCancel* [in] +A pointer to the driver's [*EVT_TXQUEUE_CANCEL*](evt-txqueue-cancel.md) callback function. + +Return value +------------ + +This method does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Nettxqueue.h

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/net-txqueue-config.md b/windows-driver-docs-pr/netcx/net-txqueue-config.md new file mode 100644 index 0000000000..d51c789f22 --- /dev/null +++ b/windows-driver-docs-pr/netcx/net-txqueue-config.md @@ -0,0 +1,89 @@ +--- +title: NET_TXQUEUE_CONFIG structure +topic_type: +- apiref +api_name: +- NET_TXQUEUE_CONFIG +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NET_TXQUEUE_CONFIG structure + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Call [NET_TXQUEUE_CONFIG_INIT](net-txqueue-config-init.md) to initialize this structure. + +Syntax +------ + +```cpp +typedef struct _NET_TXQUEUE_CONFIG { + ULONG                                Size; + PFN_TXQUEUE_CANCEL                   EvtTxQueueCancel; + PFN_TXQUEUE_SET_NOTIFICATION_ENABLED EvtTxQueueSetNotificationEnabled; + PFN_TXQUEUE_ADVANCE                  EvtTxQueueAdvance; + PCNET_CONTEXT_TYPE_INFO              ContextTypeInfo; +} NET_TXQUEUE_CONFIG, *PNET_TXQUEUE_CONFIG; +``` + +Members +------- + +**Size** +The size, in bytes, of this structure. + +**EvtTxQueueCancel** +A pointer to the client driver's [*EVT_TXQUEUE_CANCEL*](evt-txqueue-cancel.md) event callback function. This callback function is required. + +**EvtTxQueueSetNotificationEnabled** +A pointer to the client driver's [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) event callback function. This callback function is required. + +**EvtTxQueueAdvance** +A pointer to the client driver's [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) event callback function. This callback function is required. + +**ContextTypeInfo** +A pointer to a [**WDF_OBJECT_CONTEXT_TYPE_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff552407) structure. + +Remarks +------- + +Call [**NET_TXQUEUE_CONFIG_INIT**](net-txqueue-config-init.md) to initialize this structure. + +The **NET_TXQUEUE_CONFIG** structure is an input parameter to [**NetTxQueueCreate**](nettxqueuecreate.md). The client must use [**NET_TXQUEUE_CONFIG_INIT**](net-txqueue-config-init.md) to initialize this structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Nettxqueue.h
+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptercreate.md b/windows-driver-docs-pr/netcx/netadaptercreate.md new file mode 100644 index 0000000000..e730c176d9 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptercreate.md @@ -0,0 +1,109 @@ +--- +title: NetAdapterCreate method +topic_type: +- apiref +api_name: +- NetAdapterCreate +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetAdapterCreate method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Creates a net adapter object. + +Syntax +------ + +```cpp +NTSTATUS NetAdapterCreate( + _In_     WDFDEVICE              Device, + _In_opt_ PWDF_OBJECT_ATTRIBUTES AdapterAttributes, + _In_     PNET_ADAPTER_CONFIG    Configuration, + _Out_    NETADAPTER             *Adapter +); +``` + +Parameters +---------- + +*Device* [in] +The WDFDEVICE object created by a prior call to [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926). + +*AdapterAttributes* [in, optional] +A pointer to a caller-allocated [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure. The structure’s ParentObject must be NULL. The parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Configuration* [in] +A pointer to a caller-allocated [**NET_ADAPTER_CONFIG**](net-adapter-config.md) structure. For info, see [**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md). + +*Adapter* [out] +A pointer to a location that receives a handle to the new NETADAPTER object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +After it has called [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926), the client typically calls **NetAdapterCreate** from within its [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) routine. + +The NETADAPTER object is a standard WDF object. The framework manages its deletion, which occurs when the parent WDFDEVICE is deleted. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadapterdeviceinitconfig.md b/windows-driver-docs-pr/netcx/netadapterdeviceinitconfig.md new file mode 100644 index 0000000000..c1352dc003 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadapterdeviceinitconfig.md @@ -0,0 +1,92 @@ +--- +title: NetAdapterDeviceInitConfig method +topic_type: +- apiref +api_name: +- NetAdapterDeviceInitConfig +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterDeviceInitConfig method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Initializes device initialization operations when the Plug and Play (PnP) manager reports the existence of a device. + +Syntax +------ + +```cpp +NTSTATUS NetAdapterDeviceInitConfig( + _Inout_ PWDFDEVICE_INIT DeviceInit +); +``` + +Parameters +---------- + +*DeviceInit* [in, out] +Pointer to a **WDFDEVICE_INIT** that the client received in its [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) routine. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +The client driver calls this method in its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback before it calls [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926). + +When a client driver calls **NetAdapterDeviceInitConfig**, the system-supplied NetAdapterCx.sys driver calls the following methods on behalf of the client. The client driver should not call these methods directly. Doing so may result in undefined behavior. + +- [**WdfDeviceInitSetReleaseHardwareOrderOnFailure**](https://msdn.microsoft.com/library/windows/hardware/hh706196) +- [**WdfDeviceInitSetDeviceType**](https://msdn.microsoft.com/library/windows/hardware/ff546090) +- [**WdfDeviceInitSetCharacteristics**](https://msdn.microsoft.com/library/windows/hardware/ff546074) +- [**WdfDeviceInitSetIoType**](https://msdn.microsoft.com/library/windows/hardware/ff546128) +- [**WdfDeviceInitSetPowerPageable**](https://msdn.microsoft.com/library/windows/hardware/ff546766) + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netadapterdriverwdmgethandle.md b/windows-driver-docs-pr/netcx/netadapterdriverwdmgethandle.md new file mode 100644 index 0000000000..059f77b8ea --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadapterdriverwdmgethandle.md @@ -0,0 +1,93 @@ +--- +title: NetAdapterDriverWdmGetHandle method +topic_type: +- apiref +api_name: +- NetAdapterDriverWdmGetHandle +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetAdapterDriverWdmGetHandle method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +A WDF client driver calls **NetAdapterDriverWdmGetHandle** to get a handle that can be used to call NDIS APIs. + +Syntax +------ + +```cpp +NDIS_HANDLE NetAdapterDriverWdmGetHandle( + _In_ WDFDRIVER               Driver, + _In_ NET_ADAPTER_DRIVER_TYPE Type +); +``` + +Parameters +---------- + +*Driver* [in] +A handle to the driver's framework driver object, obtained from a previous call to [**WdfDriverCreate**](https://msdn.microsoft.com/library/windows/hardware/ff547175). + +*Type* [in] +A [**NET_ADAPTER_DRIVER_TYPE**](net-adapter-driver-type.md) enumeration value that specifies the type of network adapter driver. + +Return value +------------ + +**NetAdapterDriverWdmGetHandle** returns a WDM handle to the client driver. The framework's verifier reports an error if no corresponding WDM handle exists. + +Remarks +------- + +The driver must have previously called [**NetAdapterCreate**](netadaptercreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptergetnetluid.md b/windows-driver-docs-pr/netcx/netadaptergetnetluid.md new file mode 100644 index 0000000000..d759c09a59 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptergetnetluid.md @@ -0,0 +1,85 @@ +--- +title: NetAdapterGetNetLuid method +topic_type: +- apiref +api_name: +- NetAdapterGetNetLuid +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterGetNetLuid method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the NET_LUID that is assigned to a network adapter. + +Syntax +------ + +```cpp +NET_LUID NetAdapterGetNetLuid( + _In_ NETADAPTER Adapter +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +Returns the NET_LUID for the specified NETADAPTER object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NET_LUID**](https://msdn.microsoft.com/library/windows/hardware/ff568747) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptergetpowersettings.md b/windows-driver-docs-pr/netcx/netadaptergetpowersettings.md new file mode 100644 index 0000000000..6c3da5eb70 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptergetpowersettings.md @@ -0,0 +1,81 @@ +--- +title: NetAdapterGetPowerSettings method +topic_type: +- apiref +api_name: +- NetAdapterGetPowerSettings +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetAdapterGetPowerSettings method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the NETPOWERSETTINGS that is associated with a net adapter. + +Syntax +------ + +```cpp +NETPOWERSETTINGS NetAdapterGetPowerSettings( + _In_ NETADAPTER Adapter +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +Returns the NETPOWERSETTINGS for the specified net adapter object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NetPowerSettingsGetEnabledWakePatterns**](netpowersettingsgetenabledwakepatterns.md) +[**NetPowerSettingsGetEnabledProtocolOffloads**](netpowersettingsgetenabledprotocoloffloads.md) +[**NetPowerSettingsGetEnabledWakeUpFlags**](netpowersettingsgetenabledwakeupflags.md) diff --git a/windows-driver-docs-pr/netcx/netadapteropenconfiguration.md b/windows-driver-docs-pr/netcx/netadapteropenconfiguration.md new file mode 100644 index 0000000000..edf49b7a8c --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadapteropenconfiguration.md @@ -0,0 +1,107 @@ +--- +title: NetAdapterOpenConfiguration method +topic_type: +- apiref +api_name: +- NetAdapterOpenConfiguration +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetAdapterOpenConfiguration method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Opens the adapter’s configuration database. + +Syntax +------ + +```cpp +NTSTATUS NetAdapterOpenConfiguration( + _In_     NETADAPTER             Adapter, + _In_opt_ PWDF_OBJECT_ATTRIBUTES ConfigurationAttributes, + _Out_    NETCONFIGURATION       *Configuration +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*ConfigurationAttributes* [in, optional] +A pointer to a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that contains driver-supplied attributes for the new configuration object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Configuration* [out] +A pointer to a location that receives a handle to the new adapter configuration object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +Typically, the client calls this method from its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback function. + +If the client provides a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400), it specifies **NULL** for **ParentObject**. The adapter configuration object is automatically parented to the adapter object. + +As a result, WDF automatically deletes the configuration object when the adapter is deleted. However, the client can manually delete a configuration object by calling [**WdfObjectDelete**](https://msdn.microsoft.com/library/windows/hardware/ff548734), typically from its [*EVT_WDF_OBJECT_CONTEXT_CLEANUP*](https://msdn.microsoft.com/library/windows/hardware/ff540840) callback function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetConfigurationClose**](netconfigurationclose.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptersetcurrentlinkstate.md b/windows-driver-docs-pr/netcx/netadaptersetcurrentlinkstate.md new file mode 100644 index 0000000000..66a11df366 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptersetcurrentlinkstate.md @@ -0,0 +1,96 @@ +--- +title: NetAdapterSetCurrentLinkState method +topic_type: +- apiref +api_name: +- NetAdapterSetCurrentLinkState +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterSetCurrentLinkState method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Set the current link state of the of the network adapter. + +Syntax +------ + +```cpp +VOID NetAdapterSetCurrentLinkState( + _In_ NETADAPTER              Adapter, + _In_ PNET_ADAPTER_LINK_STATE CurrentLinkState +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*CurrentLinkState* [in] +A pointer to an allocated and initialized [**NET_ADAPTER_LINK_STATE**](net-adapter-link-state.md) structure that describes the current link state of the adapter. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The client driver calls **NetAdapterSetCurrentLinkState** from its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) implementation, or later when it needs to change the current link state. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NET_ADAPTER_LINK_STATE_INIT**](net-adapter-link-state-init.md) + +[**NET_ADAPTER_LINK_STATE_INIT_DISCONNECTED**](net-adapter-link-state-init-disconnected.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptersetdatapathcapabilities.md b/windows-driver-docs-pr/netcx/netadaptersetdatapathcapabilities.md new file mode 100644 index 0000000000..41369544e5 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptersetdatapathcapabilities.md @@ -0,0 +1,98 @@ +--- +title: NetAdapterSetDataPathCapabilities method +topic_type: +- apiref +api_name: +- NetAdapterSetDataPathCapabilities +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterSetDataPathCapabilities method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Sets the data path capabilities of the network adapter. + +Syntax +------ + +```cpp +VOID NetAdapterSetDataPathCapabilities( + _In_ NETADAPTER                         Adapter, + _In_ PNET_ADAPTER_DATAPATH_CAPABILITIES DataPathCapabilities +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*DataPathCapabilities* [in] +A pointer to an allocated and initialized [**NET_ADAPTER_DATAPATH_CAPABILITIES**](net-adapter-datapath-capabilities.md) structure. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The client driver must call this method from its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) event callback routine. + +This method along with a few other set capability methods (see below) is the replacement for the [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) union that a (non-WDF) client of Ndis.sys sets by calling [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptersetlinklayercapabilities.md b/windows-driver-docs-pr/netcx/netadaptersetlinklayercapabilities.md new file mode 100644 index 0000000000..e415d8531d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptersetlinklayercapabilities.md @@ -0,0 +1,98 @@ +--- +title: NetAdapterSetLinkLayerCapabilities method +topic_type: +- apiref +api_name: +- NetAdapterSetLinkLayerCapabilities +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterSetLinkLayerCapabilities method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Sets the link layer capabilities of the network adapter. + +Syntax +------ + +```cpp +VOID NetAdapterSetLinkLayerCapabilities( + _In_ NETADAPTER                           Adapter, + _In_ PNET_ADAPTER_LINK_LAYER_CAPABILITIES LinkCapabilities +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*LinkCapabilities* [in] +A pointer to an allocated and initialized [**NET_ADAPTER_LINK_LAYER_CAPABILITIES**](net-adapter-link-layer-capabilities.md) structure. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The client driver calls this method from its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) event callback routine. + +This method along with a few other set capability methods (see below) is the replacement for the [**NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) union that a (non-WDF) client of Ndis.sys sets by calling [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) + +[**NetAdapterSetPowerCapabilities**](netadaptersetpowercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptersetlinklayermtusize.md b/windows-driver-docs-pr/netcx/netadaptersetlinklayermtusize.md new file mode 100644 index 0000000000..c2722314ad --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptersetlinklayermtusize.md @@ -0,0 +1,101 @@ +--- +title: NetAdapterSetLinkLayerMtuSize method +topic_type: +- apiref +api_name: +- NetAdapterSetLinkLayerMtuSize +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetAdapterSetLinkLayerMtuSize method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Sets the link layer maximum transfer unit size of the adapter. + +Syntax +------ + +```cpp +void NetAdapterSetLinkLayerMtuSize( + _In_ NETADAPTER Adapter, + _In_ ULONG      MtuSize +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*MtuSize* [in] +The new size of the adapter's MTU, in bytes. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The client driver first sets MTU size by calling **NetAdapterSetLinkLayerMtuSize** from its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) implementation. + +The client driver can change the MTU size after returning from [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) by calling this method again. Doing so causes all of the adapter's transmit (Tx) and receive (Rx) queues to be recreated. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadaptersetpowercapabilities.md b/windows-driver-docs-pr/netcx/netadaptersetpowercapabilities.md new file mode 100644 index 0000000000..8e894dca91 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadaptersetpowercapabilities.md @@ -0,0 +1,105 @@ +--- +title: NetAdapterSetPowerCapabilities method +topic_type: +- apiref +api_name: +- NetAdapterSetPowerCapabilities +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterSetPowerCapabilities method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Sets the power capabilities of the network adapter. + +Syntax +------ + +```cpp +void NetAdapterSetPowerCapabilities( + _In_ NETADAPTER                      Adapter, + _In_ PNET_ADAPTER_POWER_CAPABILITIES PowerCapabilities +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +*PowerCapabilities* [in] +A pointer to an allocated and initialized [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The client driver sets capabilities by calling the following methods from its [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) event callback routine. + +- [**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) +- [**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) +- **NetAdapterSetPowerCapabilities** + +Alternatively, the client can call **NetAdapterSetPowerCapabilities** at a later time, but it must not change the [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) and [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) event callback functions. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md) + +[**NetAdapterSetLinkLayerCapabilities**](netadaptersetlinklayercapabilities.md) +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netadapterwdmgetndishandle.md b/windows-driver-docs-pr/netcx/netadapterwdmgetndishandle.md new file mode 100644 index 0000000000..1a38a272f7 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netadapterwdmgetndishandle.md @@ -0,0 +1,84 @@ +--- +title: NetAdapterWdmGetNdisHandle method +topic_type: +- apiref +api_name: +- NetAdapterWdmGetNdisHandle +api_location: +- netadapter.h +api_type: +- HeaderDef +--- + +# NetAdapterWdmGetNdisHandle method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the NDIS adapter handle for a specified net adapter. + +Syntax +------ + +```cpp +NDIS_HANDLE NetAdapterWdmGetNdisHandle( + _In_ NETADAPTER Adapter +); +``` + +Parameters +---------- + +*Adapter* [in] +The network adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Return value +------------ + +Retrieves the NDIS_HANDLE for a specified NETADAPTER. + +Remarks +------- + +Client drivers that bypass NetAdapterCx and call NDIS DDIs directly call this method to retrieve the NDIS handle required by these DDIs. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapter.h (include Netadaptercx.h)

IRQL

Any level

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationassignbinary.md b/windows-driver-docs-pr/netcx/netconfigurationassignbinary.md new file mode 100644 index 0000000000..fb03a5cd9e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationassignbinary.md @@ -0,0 +1,96 @@ +--- +title: NetConfigurationAssignBinary method +topic_type: +- apiref +api_name: +- NetConfigurationAssignBinary +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationAssignBinary method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The **NetConfigurationAssignBinary** method writes caller-supplied binary data to a specified value name in the registry. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationAssignBinary( + _In_ NETCONFIGURATION Configuration, + _In_ PCUNICODE_STRING ValueName, + _In_ PVOID            Buffer, + _In_ ULONG            BufferLength +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name. + +*Buffer* [in] +A pointer to a buffer that contains driver-supplied data. + +*BufferLength* [in] +The length, in bytes, of the buffer that *Buffer* points to. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +--- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +If an entry of the same name as *ValueName* already exists under the opened registry key, **NetConfigurationAssignUlong** replaces its current value with the caller-supplied value. Otherwise, **NetConfigurationAssignUlong** adds a new value entry with the given name and supplied value to the registry. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationassignmultistring.md b/windows-driver-docs-pr/netcx/netconfigurationassignmultistring.md new file mode 100644 index 0000000000..759ee79b99 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationassignmultistring.md @@ -0,0 +1,92 @@ +--- +title: NetConfigurationAssignMultiString method +topic_type: +- apiref +api_name: +- NetConfigurationAssignMultiString +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationAssignMultiString method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The **NetConfigurationAssignMultiString** method assigns a set of strings to a specified value name in the registry. The strings are contained in a specified collection of framework string objects. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationAssignMultiString( + _In_ NETCONFIGURATION Configuration, + _In_ PCUNICODE_STRING ValueName, + _In_ WDFCOLLECTION    Collection +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name. + +*Collection* [in] +A handle to a framework collection object that represents a collection of framework string objects. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +----- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +If an entry of the same name as *ValueName* already exists under the opened registry key, **NetConfigurationAssignUlong** replaces its current value with the caller-supplied value. Otherwise, **NetConfigurationAssignUlong** adds a new value entry with the given name and supplied value to the registry. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationassignulong.md b/windows-driver-docs-pr/netcx/netconfigurationassignulong.md new file mode 100644 index 0000000000..1470ce25ad --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationassignulong.md @@ -0,0 +1,97 @@ +--- +title: NetConfigurationAssignUlong method +topic_type: +- apiref +api_name: +- NetConfigurationAssignUlong +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationAssignUlong method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The **NetConfigurationAssignUlong** method writes a caller-supplied unsigned long word value to a specified value name in the registry. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationAssignUlong( + _In_ NETCONFIGURATION Configuration, + _In_ PCUNICODE_STRING ValueName, + _In_ ULONG            Value +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name. + +*Value* [in] +A ULONG value that will be assigned to the value name that *ValueName* specifies. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +--- + +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +If an entry of the same name as *ValueName* already exists under the opened registry key, **NetConfigurationAssignUlong** replaces its current value with the caller-supplied value. Otherwise, **NetConfigurationAssignUlong** adds a new value entry with the given name and supplied value to the registry. + + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  +## See also + + +[**NdisWriteConfiguration **](https://msdn.microsoft.com/library/windows/hardware/ff564659) +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationassignunicodestring.md b/windows-driver-docs-pr/netcx/netconfigurationassignunicodestring.md new file mode 100644 index 0000000000..7c51f33c33 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationassignunicodestring.md @@ -0,0 +1,93 @@ +--- +title: NetConfigurationAssignUnicodeString method +topic_type: +- apiref +api_name: +- NetConfigurationAssignUnicodeString +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationAssignUnicodeString method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The **NetConfigurationAssignUnicodeString** method assigns a specified Unicode string to a specified value name in the registry. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationAssignUnicodeString( + _In_ NETCONFIGURATION Configuration, + _In_ PCUNICODE_STRING ValueName, + _In_ PCUNICODE_STRING Value +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name. + +*Value* [in] +A pointer to a UNICODE_STRING structure that contains the string to be assigned to the value name that *ValueName* specifies. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +--- + +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +If an entry of the same name as *ValueName* already exists under the opened registry key, **NetConfigurationAssignUlong** replaces its current value with the caller-supplied value. Otherwise, **NetConfigurationAssignUlong** adds a new value entry with the given name and supplied value to the registry. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationclose.md b/windows-driver-docs-pr/netcx/netconfigurationclose.md new file mode 100644 index 0000000000..91a58f184e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationclose.md @@ -0,0 +1,96 @@ +--- +title: NetConfigurationClose method +topic_type: +- apiref +api_name: +- NetConfigurationClose +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetConfigurationClose method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Releases the handle to the registry key that is associated with an adapter configuration object and then deletes the adapter configuration object. + +Syntax +------ + +```cpp +void NetConfigurationClose( + _In_ NETCONFIGURATION Configuration +); +``` + +Parameters +---------- + +*Configuration* [in] +A handle to an adapter configuration object opened in a prior call to [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +Return value +------------ + +This method does not return a value. + +Remarks +----- + +**NetConfigurationClose** is an alias of [**WdfObjectDelete**](https://msdn.microsoft.com/library/windows/hardware/ff548734). Because the configuration object, like all NetAdapterCx objects, is a WDF object, you can use [**WdfObjectDelete**](https://msdn.microsoft.com/library/windows/hardware/ff548734) interchangeably. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) + +[**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationopensubconfiguration.md b/windows-driver-docs-pr/netcx/netconfigurationopensubconfiguration.md new file mode 100644 index 0000000000..3f10b3505e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationopensubconfiguration.md @@ -0,0 +1,110 @@ +--- +title: NetConfigurationOpenSubConfiguration method +topic_type: +- apiref +api_name: +- NetConfigurationOpenSubConfiguration +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetConfigurationOpenSubConfiguration method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Opens a sub configuration of a specified adapter configuration object. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationOpenSubConfiguration( + _In_     NETCONFIGURATION       Configuration, + _In_     PCUNICODE_STRING       SubConfigurationName, + _In_opt_ PWDF_OBJECT_ATTRIBUTES SubConfigurationAttributes, + _Out_    NETCONFIGURATION       *SubConfiguration +); +``` + +Parameters +---------- + +*Configuration* [in] +A handle to an adapter configuration object opened in a prior call to [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or **NetConfigurationOpenSubConfiguration**. + +*SubConfigurationName* [in] +A pointer to a string specifying the name of the sub configuration to open. + +*SubConfigurationAttributes* [in, optional] +A pointer to a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that contains driver-supplied attributes for the new configuration object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*SubConfiguration* [out] +A pointer to a location that receives a handle to the new sub configuration object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +If the client provides a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400), it specifies **NULL** for **ParentObject**. By default, the sub configuration is parented to the existing adapter configuration object. + +The client driver closes the sub configuration by calling [**NetConfigurationClose**](netconfigurationclose.md) with either the sub configuration object or the parent adapter configuration object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) + +[**NetConfigurationClose**](netconfigurationclose.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationquerybinary.md b/windows-driver-docs-pr/netcx/netconfigurationquerybinary.md new file mode 100644 index 0000000000..2f0837bdb0 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationquerybinary.md @@ -0,0 +1,98 @@ +--- +title: NetConfigurationQueryBinary method +topic_type: +- apiref +api_name: +- NetConfigurationQueryBinary +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationQueryBinary method + +Retrieves the data that is currently assigned to a specified registry value, stores the data in a framework-allocated buffer, and creates a framework memory object to represent the buffer. + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationQueryBinary( + _In_   NETCONFIGURATION       Configuration, + _In_   PCUNICODE_STRING       ValueName, + _In_   POOL_TYPE              PoolType, + _In_opt_  PWDF_OBJECT_ATTRIBUTES MemoryAttributes, + _Out_  WDFMEMORY*             Memory +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name. + +*PoolType* [in] +A **POOL_TYPE**-typed value that specifies the type of memory to be allocated for the data buffer. + +*MemoryAttributes* [in, optional] +A pointer to a [WDF_OBJECT_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that contains object attributes for the new memory object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Memory* [out] +A pointer to a location that receives a handle to the new memory object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +----- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationquerymultistring.md b/windows-driver-docs-pr/netcx/netconfigurationquerymultistring.md new file mode 100644 index 0000000000..229869511d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationquerymultistring.md @@ -0,0 +1,101 @@ +--- +title: NetConfigurationQueryMultiString method +topic_type: +- apiref +api_name: +- NetConfigurationQueryMultiString +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetConfigurationQueryMultiString method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the MultiString-valued registry entry associated with a value name in the specified configuration object. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationQueryMultiString( + _In_     NETCONFIGURATION       Configuration, + _In_     PCUNICODE_STRING       ValueName, + _In_opt_ PWDF_OBJECT_ATTRIBUTES StringsAttributes, + _Inout_  WDFCOLLECTION          Collection +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a value name in the device's software key. + +*StringsAttributes* [in, optional] +A pointer to a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that contains driver-supplied attributes for the new WDFSTRING objects. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Collection* [in, out] +A handle to a driver-supplied collection object. If the method succeeds, contains a WDFSTRING object for each string assigned to *ValueName*. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. If the registry value is NULL, **NetConfigurationQueryMultiString** returns STATUS_OBJECT_NAME_NOT_FOUND. + +Remarks +------- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +By default, the strings are parented to the collection object. The client driver can change this by setting the **ParentObject** member of the [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationquerynetworkaddress.md b/windows-driver-docs-pr/netcx/netconfigurationquerynetworkaddress.md new file mode 100644 index 0000000000..f913ae83d0 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationquerynetworkaddress.md @@ -0,0 +1,108 @@ +--- +title: NetConfigurationQueryNetworkAddress method +topic_type: +- apiref +api_name: +- NetConfigurationQueryNetworkAddress +api_location: +- netconfiguration.h +api_type: +- HeaderDef +--- + +# NetConfigurationQueryNetworkAddress method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the software-configurable network address that was stored in the registry for a NIC. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationQueryNetworkAddress( + _In_  NETCONFIGURATION Configuration, + _In_  ULONG            BufferLength, + _Out_ PVOID            NetworkAddressBuffer, + _Out_ PULONG           ResultLength +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*BufferLength* [in] +The length, in bytes, of the buffer that *NetworkAddressBuffer* points to. + +*NetworkAddressBuffer* [out] +A pointer to a caller-allocated buffer that receives the requested network address as a byte array. + +*ResultLength* [out] +A caller-supplied location that, on return, contains the size, in bytes, of the information that the method stored in *NetworkAddressBuffer*. If the function's return value is STATUS_BUFFER_TOO_SMALL, this location receives the required buffer size. + +Return value +------------ +Returns one of the following status values: + +|Return Code|Description| +|---|---| +|STATUS_SUCCESS|The operation succeeded.| +|STATUS_BUFFER_TOO_SMALL|The supplied buffer is too small to receive the information.| + +Remarks +----- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +Typically, a **NetworkAddress** entry in the registry is stored as a string of hexadecimal digits. Optionally, an installer can store such an address as a string of paired digits, with each pair separated from the next by a hyphen. + +The **NetConfigurationQueryNetworkAddress** method searches the registry **Parameters** key for the keyword **NetworkAddress** and then converts the value of this string-type entry to a sequence of byte integers. **NetConfigurationQueryNetworkAddress** discards hyphens and converts each such pair into a single byte. + +The buffer remains valid for the lifetime of the NETCONFIGURATION object. + +Note that NDIS does not validate the network address. NDIS does not guarantee that this value is a valid address, that the value has the proper length, or even that the value is a network address. If the caller determines that the value is out of bounds, it should not use the value; instead, it should use the permanent medium access control (MAC) address or a default address. + +To support software configurable network addressing, use MSFT_NetAdapter WMI classes instead. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationquerystring.md b/windows-driver-docs-pr/netcx/netconfigurationquerystring.md new file mode 100644 index 0000000000..28b5f53d5f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationquerystring.md @@ -0,0 +1,102 @@ +--- +title: NetConfigurationQueryString method +topic_type: +- apiref +api_name: +- NetConfigurationQueryString +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetConfigurationQueryString method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the specified string value from the adapter configuration object and assigns the string to a specified framework string object. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationQueryString( + _In_     NETCONFIGURATION       Configuration, + _In_     PCUNICODE_STRING       ValueName, + _In_opt_ PWDF_OBJECT_ATTRIBUTES StringAttributes, + _Out_    WDFSTRING              *WdfString +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a name for string value. + +*StringAttributes* [in, optional] +A pointer to a [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that contains driver-supplied attributes for the new WDFSTRING object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*WdfString* [out] +A handle to a framework string object. NetAdapterCx will assign the registry value's string data to this object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +By default, the framework string object is parented to the collection object. The client driver can change this by setting the **ParentObject** member of the [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netconfigurationqueryulong.md b/windows-driver-docs-pr/netcx/netconfigurationqueryulong.md new file mode 100644 index 0000000000..e5b64e1112 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netconfigurationqueryulong.md @@ -0,0 +1,99 @@ +--- +title: NetConfigurationQueryUlong method +topic_type: +- apiref +api_name: +- NetConfigurationQueryUlong +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetConfigurationQueryUlong method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the specified unsigned long word (REG_DWORD) data from the adapter configuration object and copies the data to a specified location. + +Syntax +------ + +```cpp +NTSTATUS NetConfigurationQueryUlong( + _In_  NETCONFIGURATION                    Configuration, + _In_  NET_CONFIGURATION_QUERY_ULONG_FLAGS Flags, + _In_  PCUNICODE_STRING                    ValueName, + _Out_ PULONG                              Value +); +``` + +Parameters +---------- + +*Configuration* [in] +Handle to a NETCONFIGURATION object that represents an opened registry key. + +*Flags* [in] +A valid bitwise OR of [**NET_CONFIGURATION_QUERY_ULONG_FLAGS**](net-configuration-query-ulong-flags.md)-typed flags. + +*ValueName* [in] +A pointer to a **UNICODE_STRING** structure that contains a name for the ULONG value. + +*Value* [out] +A pointer to a location that receives the data that is assigned to the value that *ValueName* specifies. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +----- +The client driver obtains a handle to a NETCONFIGURATION object by calling [**NetAdapterOpenConfiguration**](netadapteropenconfiguration.md) or [**NetConfigurationOpenSubConfiguration**](netconfigurationopensubconfiguration.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netconfiguration.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netpacketgettypedcontext.md b/windows-driver-docs-pr/netcx/netpacketgettypedcontext.md new file mode 100644 index 0000000000..dbf4583705 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpacketgettypedcontext.md @@ -0,0 +1,94 @@ +--- +title: NetPacketGetTypedContext method +topic_type: +- apiref +api_name: +- NetPacketGetTypedContext +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPacketGetTypedContext method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Client drivers should not call this function directly. Instead, use [**NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME**](net-packet-declare-context-type-with-name.md). + +Syntax +------ + +```cpp +PVOID NetPacketGetTypedContext( + _In_ NET_PACKET              *NetPacket, + _In_ PCNET_CONTEXT_TYPE_INFO TypeInfo +); +``` + +Parameters +---------- + +*NetPacket* [in] +Reserved. + +*TypeInfo* [in] +Reserved. + +Return value +------------ + +Returns a pointer to the packet's context space. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NET_PACKET_DECLARE_CONTEXT_TYPE_WITH_NAME**](net-packet-declare-context-type-with-name.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetenabledmediaspecificwakeupevents.md b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledmediaspecificwakeupevents.md new file mode 100644 index 0000000000..5aa407083f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledmediaspecificwakeupevents.md @@ -0,0 +1,97 @@ +--- +title: NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves flags that specify currently enabled media-specific wake-up events that a network adapter supports. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the net adapter. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +A ULONG value that contains a bitwise **OR** of [**NET_ADAPTER_MEDIA_SPECIFIC_WAKEUP_EVENTS_FLAGS**](net-adapter-media-specific-wakeup-events-flags.md)-typed flags that correspond to events that the client driver reported in the **SupportedMediaSpecificWakeUpEvents** member of the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. The flags represent the media-specific wake-up events that the driver must enable in the hardware to arm the device for wake. + +For more information, see the **MediaSpecificWakeUpEvents** member of [**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759). + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetEnabledMediaSpecificWakeUpEvents** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetenabledprotocoloffloads.md b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledprotocoloffloads.md new file mode 100644 index 0000000000..eee4f6f2fb --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledprotocoloffloads.md @@ -0,0 +1,95 @@ +--- +title: NetPowerSettingsGetEnabledProtocolOffloads method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetEnabledProtocolOffloads +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetEnabledProtocolOffloads method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves flags that specify currently enabled low power protocol offloads that a network adapter supports. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetEnabledProtocolOffloads( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +A ULONG value that contains a bitwise **OR** of [**NET_ADAPTER_PROTOCOL_OFFLOADS_FLAGS**](net-adapter-protocol-offloads-flags.md)-typed flags that correspond to capabilities that the client driver reported in the **SupportedProtocolOffloads** member of the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. NDIS uses these flags to enable the low power protocol offload capabilities on a network adapter. For more information, see [**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759). + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetEnabledProtocolOffloads** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NetPowerSettingsGetEnabledProtocolOffloads**](netpowersettingsgetenabledprotocoloffloads.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakepatterns.md b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakepatterns.md new file mode 100644 index 0000000000..bdbff5adf8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakepatterns.md @@ -0,0 +1,87 @@ +--- +title: NetPowerSettingsGetEnabledWakePatterns method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetEnabledWakePatterns +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetEnabledWakePatterns method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves flags representing currently enabled wake pattern types that a network adapter supports. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetEnabledWakePatterns( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +A ULONG value that contains a bitwise **OR** of [**NET_ADAPTER_WAKE_PATTERN_FLAGS**](net-adapter-wake-pattern-flags.md)-typed flags that correspond to capabilities that the client driver reported in the **SupportedWakePacketPatterns** member of the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. NDIS uses these flags to enable the wake-on-LAN (WOL) patterns that a network adapter uses to wake the local computer from a low power state. For more information about WOL patterns, see [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768). + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetEnabledWakePatterns** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + +* [**NetPowerSettingsGetWakePatternCount**](netpowersettingsgetwakepatterncount.md) +* [**NDIS_PM_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) +* [**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) +* [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakeupflags.md b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakeupflags.md new file mode 100644 index 0000000000..e62fea24de --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetenabledwakeupflags.md @@ -0,0 +1,95 @@ +--- +title: NetPowerSettingsGetEnabledWakeUpFlags method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetEnabledWakeUpFlags +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetEnabledWakeUpFlags method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves flags that specify currently enabled media-independent wake-up events that a network adapter supports. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetEnabledWakeUpFlags( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +A ULONG value that contains a bitwise **OR** of [**NET_ADAPTER_WAKEUP_EVENTS_FLAGS**](net-adapter-wakeup-events-flags.md)-typed flags that correspond to wake-up events that the client driver reported in the **SupportedWakeUpEvents** member of the [**NET_ADAPTER_POWER_CAPABILITIES**](net-adapter-power-capabilities.md) structure. For more information, see the **WakeUpFlags** member of [**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759). + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetEnabledWakeUpFlags** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffload.md b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffload.md new file mode 100644 index 0000000000..1d985841aa --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffload.md @@ -0,0 +1,101 @@ +--- +title: NetPowerSettingsGetProtocolOffload method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetProtocolOffload +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetProtocolOffload method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves a structure that specifies parameters for a low power protocol offload to a network adapter. + +Syntax +------ + +```cpp +PNDIS_PM_PROTOCOL_OFFLOAD NetPowerSettingsGetProtocolOffload( + _In_ NETPOWERSETTINGS NetPowerSettings, + _In_ ULONG            Index +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*Index* [in] +A zero-based value that is used as an index into the protocol offload structures associated with the NETPOWERSETTINGS object. This value must be less than the value returned by [**NetPowerSettingsGetProtocolOffloadCount**](netpowersettingsgetprotocoloffloadcount.md). + +Return value +------------ + +Returns a pointer to the [**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure at the specified index, or **NULL** if the index value is invalid. + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetProtocolOffload** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) callback function. Otherwise, the call results in a system bugcheck. + +The client driver can use the pointer to examine the [**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure, but should not retain it. NetAdapterCx automatically releases the protocol offload structure during offload removal. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcount.md b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcount.md new file mode 100644 index 0000000000..a5c022828d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcount.md @@ -0,0 +1,97 @@ +--- +title: NetPowerSettingsGetProtocolOffloadCount method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetProtocolOffloadCount +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetProtocolOffloadCount method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the number of protocol offload structures associated with a NETPOWERSETTINGS object. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetProtocolOffloadCount( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +Returns the total number of enabled and disabled protocol offload structures associated with a NETPOWERSETTINGS object. + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetProtocolOffloadCount** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) callback function. Otherwise, the call results in a system bugcheck. + +To determine if a specific protocol offload is enabled, call [**NetPowerSettingsIsProtocolOffloadEnabled**](netpowersettingsisprotocoloffloadenabled.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcountfortype.md b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcountfortype.md new file mode 100644 index 0000000000..36208d16c9 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetprotocoloffloadcountfortype.md @@ -0,0 +1,101 @@ +--- +title: NetPowerSettingsGetProtocolOffloadCountForType method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetProtocolOffloadCountForType +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetProtocolOffloadCountForType method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the number of protocol offload structures in the NETPOWERSETTINGS object for the particular offload type. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetProtocolOffloadCountForType( + _In_ NETPOWERSETTINGS              NetPowerSettings, + _In_ NDIS_PM_PROTOCOL_OFFLOAD_TYPE ProtocolOffloadType +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*ProtocolOffloadType* [in] +An [**NDIS_PM_PROTOCOL_OFFLOAD_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff566765) value that contains the type of protocol offload to count. + +Return value +------------ + +Returns the total number of enabled and disabled protocol offloads in the NETPOWERSETTINGS object for the specified protocol offload type. + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetProtocolOffloadCountForType** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) callback function. Otherwise, the call results in a system bugcheck. + +To determine if a specific protocol offload is enabled, call [**NetPowerSettingsIsProtocolOffloadEnabled**](netpowersettingsisprotocoloffloadenabled.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PROTOCOL_OFFLOAD_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff566765) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetwakepattern.md b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepattern.md new file mode 100644 index 0000000000..1f5ced2411 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepattern.md @@ -0,0 +1,103 @@ +--- +title: NetPowerSettingsGetWakePattern method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetWakePattern +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetWakePattern method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the wake pattern structure at the specified index. + +Syntax +------ + +```cpp +PNDIS_PM_WOL_PATTERN NetPowerSettingsGetWakePattern( + _In_ NETPOWERSETTINGS NetPowerSettings, + _In_ ULONG            Index +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*Index* [in] +A zero-based value that is used as an index into the WoL patterns stored in the NETPOWERSETTINGS object. This value must be less than the value returned by [**NetPowerSettingsGetWakePatternCount**](netpowersettingsgetwakepatterncount.md). + +Return value +------------ + +Returns a pointer to the [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure at the specified index, or **NULL** if the index value is invalid. + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetWakePattern** during a power transition, typically [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844), or from [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) or [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md). Otherwise, the call results in a system bugcheck. + +The client can check if this pattern is enabled by calling [**NetPowerSettingsIsWakePatternEnabled**](netpowersettingsiswakepatternenabled.md). + +The client driver can use the pointer to examine the [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure, but should not retain it. NetAdapterCx automatically releases the pattern structure during WoL pattern removal. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncount.md b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncount.md new file mode 100644 index 0000000000..52985a611a --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncount.md @@ -0,0 +1,95 @@ +--- +title: NetPowerSettingsGetWakePatternCount method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetWakePatternCount +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetWakePatternCount method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the number of wake-on-LAN (WoL) patterns stored in a NETPOWERSETTINGS object. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetWakePatternCount( + _In_ NETPOWERSETTINGS NetPowerSettings +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the NETADAPTER. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +Return value +------------ + +Returns the total number of enabled and disabled WoL patterns stored in the NETPOWERSETTINGS object. + +Remarks +------- + +The client driver must only call **NetPowerSettingsGetWakePatternCount** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncountfortype.md b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncountfortype.md new file mode 100644 index 0000000000..b8a4c3fda1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsgetwakepatterncountfortype.md @@ -0,0 +1,101 @@ +--- +title: NetPowerSettingsGetWakePatternCountForType method +topic_type: +- apiref +api_name: +- NetPowerSettingsGetWakePatternCountForType +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsGetWakePatternCountForType method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the number of wake-on-LAN (WoL) patterns stored in the NETPOWERSETTINGS object for the specified wake pattern type. + +Syntax +------ + +```cpp +ULONG NetPowerSettingsGetWakePatternCountForType( + _In_ NETPOWERSETTINGS   NetPowerSettings, + _In_ NDIS_PM_WOL_PACKET WakePatternType +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the net adapter. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*WakePatternType* [in] +An [**NDIS_PM_WOL_PACKET**](https://msdn.microsoft.com/library/windows/hardware/ff566766) value that contains the type of wake pattern to count. + +Return value +------------ + +Returns the total number of enabled and disabled wake patterns stored in the NETPOWERSETTINGS object for the specified pattern type. + +Remarks +------- + +The client driver must only call [**NetPowerSettingsGetWakePatternCount**](netpowersettingsgetwakepatterncount.md) during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from its [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) callback function. Otherwise, the call results in a system bugcheck. + +To determine if a specific wake pattern is enabled, call [**NetPowerSettingsIsWakePatternEnabled**](netpowersettingsiswakepatternenabled.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsisprotocoloffloadenabled.md b/windows-driver-docs-pr/netcx/netpowersettingsisprotocoloffloadenabled.md new file mode 100644 index 0000000000..02a80a6321 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsisprotocoloffloadenabled.md @@ -0,0 +1,99 @@ +--- +title: NetPowerSettingsIsProtocolOffloadEnabled method +topic_type: +- apiref +api_name: +- NetPowerSettingsIsProtocolOffloadEnabled +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsIsProtocolOffloadEnabled method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Determines if a protocol offload is enabled. + +Syntax +------ + +```cpp +BOOLEAN NetPowerSettingsIsProtocolOffloadEnabled( + _In_ NETPOWERSETTINGS          NetPowerSettings, + _In_ PNDIS_PM_PROTOCOL_OFFLOAD NdisProtocolOffload +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the net adapter. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*NdisProtocolOffload* [in] +A pointer to a [**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure obtained by calling [**NetPowerSettingsGetProtocolOffload**](netpowersettingsgetprotocoloffload.md). + +Return value +------------ + +Returns **TRUE** if the protocol offload is enabled, and **FALSE** otherwise. + +Remarks +------- + +The client driver must only call **NetPowerSettingsIsProtocolOffloadEnabled** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_PROTOCOL_OFFLOAD*](evt-net-adapter-preview-protocol-offload.md) callback function. Otherwise, the call results in a system bugcheck. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_PROTOCOL_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netpowersettingsiswakepatternenabled.md b/windows-driver-docs-pr/netcx/netpowersettingsiswakepatternenabled.md new file mode 100644 index 0000000000..b83bc769fe --- /dev/null +++ b/windows-driver-docs-pr/netcx/netpowersettingsiswakepatternenabled.md @@ -0,0 +1,101 @@ +--- +title: NetPowerSettingsIsWakePatternEnabled method +topic_type: +- apiref +api_name: +- NetPowerSettingsIsWakePatternEnabled +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetPowerSettingsIsWakePatternEnabled method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Determines if a wake-on-LAN (WoL) pattern is enabled for a network adapter. + +Syntax +------ + +```cpp +BOOLEAN NetPowerSettingsIsWakePatternEnabled( + _In_ NETPOWERSETTINGS     NetPowerSettings, + _In_ PNDIS_PM_WOL_PATTERN NdisPmWolPattern +); +``` + +Parameters +---------- + +*NetPowerSettings* [in] +A handle to the NETPOWERSETTINGS object associated with the net adapter. To retrieve the handle, call [**NetAdapterGetPowerSettings**](netadaptergetpowersettings.md). + +*NdisPmWolPattern* [in] +A pointer to a [**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure obtained by calling [**NetPowerSettingsGetWakePattern**](netpowersettingsgetwakepattern.md). + +Return value +------------ + +Returns **TRUE** if the WoL pattern is enabled and the driver must enable it in its hardware, and **FALSE** otherwise. + +Remarks +------- + +The client driver must only call **NetPowerSettingsIsWakePatternEnabled** during a power transition, typically from its [*EVT_WDF_DEVICE_ARM_WAKE_FROM_SX*](https://msdn.microsoft.com/library/windows/hardware/ff540844) or [*EVT_WDF_DEVICE_ARM_WAKE_FROM_S0*](https://msdn.microsoft.com/library/windows/hardware/ff540843) callback function, or from the [*EVT_NET_ADAPTER_PREVIEW_WAKE_PATTERN*](evt-net-adapter-preview-wake-pattern.md) callback function. Otherwise, the call results in a system bugcheck. + +If the wake pattern is enabled, the driver programs its hardware to enable the pattern during a power down transition. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netpowersettings.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

DISPATCH_LEVEL

+ +## See also + + +[**NDIS_PM_WOL_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netrequestcompletewithoutinformation.md b/windows-driver-docs-pr/netcx/netrequestcompletewithoutinformation.md new file mode 100644 index 0000000000..6baebfc53e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestcompletewithoutinformation.md @@ -0,0 +1,86 @@ +--- +title: NetRequestCompleteWithoutInformation method +topic_type: +- apiref +api_name: +- NetRequestCompleteWithoutInformation +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestCompleteWithoutInformation method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Completes a NETREQUEST and supplies a completion status. + +Syntax +------ + +```cpp +VOID NetRequestCompleteWithoutInformation( + _In_ NETREQUEST Request, + _In_ NTSTATUS   CompletionStatus +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object that represents the control (OID) request that is being completed. + +*CompletionStatus* [in] +An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following: + +|Return code|Description| +|--|--| +|STATUS_SUCCESS|The driver successfully completed the request.| +|STATUS_CANCELLED|The driver canceled the request.| +|STATUS_UNSUCCESSFUL|The driver encountered an error while processing the request.| + +Remarks +----- +Typically, the client driver calls **NetRequestCompleteWithoutInformation** from one of its control request handler routines. Call this function when completing a request that does not require additional memory transfer. For more info, see [Handling Control Requests](handling-control-requests.md#completing-requests). + +After this method returns, the request handle is no longer valid. NetAdapterCx removes it from the NETQUEUE and deletes the NETREQUEST object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NetRequestMethodComplete**](netrequestmethodcomplete.md) +[**NetRequestQueryDataComplete**](netrequestquerydatacomplete.md) +[**NetRequestSetDataComplete**](netrequestsetdatacomplete.md) diff --git a/windows-driver-docs-pr/netcx/netrequestgetid.md b/windows-driver-docs-pr/netcx/netrequestgetid.md new file mode 100644 index 0000000000..68ed8358ae --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestgetid.md @@ -0,0 +1,78 @@ +--- +title: NetRequestGetId method +topic_type: +- apiref +api_name: +- NetRequestGetId +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestGetId method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the NDIS_OID identifier associated with the specified network request object. + +Syntax +------ + +```cpp +NDIS_OID NetRequestGetId( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Returns the object identifier for the network request object. The value is an OID_XXX code. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrequestgetportnumber.md b/windows-driver-docs-pr/netcx/netrequestgetportnumber.md new file mode 100644 index 0000000000..2662bbf64d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestgetportnumber.md @@ -0,0 +1,73 @@ +--- +title: NetRequestGetPortNumber method +topic_type: +- apiref +api_name: +- NetRequestGetPortNumber +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestGetPortNumber method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the port number for the network request object. + +Syntax +------ + +```cpp +NDIS_PORT_NUMBER NetRequestGetPortNumber( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Returns the port number corresponding to the network request object. If the port is unknown or default, returns zero. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NDIS_OID_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) diff --git a/windows-driver-docs-pr/netcx/netrequestgetswitchid.md b/windows-driver-docs-pr/netcx/netrequestgetswitchid.md new file mode 100644 index 0000000000..e7edec71e1 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestgetswitchid.md @@ -0,0 +1,73 @@ +--- +title: NetRequestGetSwitchId method +topic_type: +- apiref +api_name: +- NetRequestGetSwitchId +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestGetSwitchId method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the switch identifier for the net request. + +Syntax +------ + +```cpp +NDIS_NIC_SWITCH_ID NetRequestGetSwitchId( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Returns an NDIS_NIC_SWITCH_ID value that specifies a switch identifier. The switch identifier is an integer between zero and the number of switches that the network adapter supports. An NDIS_DEFAULT_SWITCH_ID value indicates the default network adapter switch. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NDIS_NIC_SWITCH_PARAMETERS **](https://msdn.microsoft.com/library/windows/hardware/hh451587) diff --git a/windows-driver-docs-pr/netcx/netrequestgettype.md b/windows-driver-docs-pr/netcx/netrequestgettype.md new file mode 100644 index 0000000000..55e29ca83f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestgettype.md @@ -0,0 +1,73 @@ +--- +title: NetRequestGetType method +topic_type: +- apiref +api_name: +- NetRequestGetType +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestGetType method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the request type in an OID request. + +Syntax +------ + +```cpp +NDIS_REQUEST_TYPE NetRequestGetType( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Returns a [**NDIS_REQUEST_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff567250) value that specifies the request type of the OID request. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NDIS_OID_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) diff --git a/windows-driver-docs-pr/netcx/netrequestgetvportid.md b/windows-driver-docs-pr/netcx/netrequestgetvportid.md new file mode 100644 index 0000000000..e668254e5c --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestgetvportid.md @@ -0,0 +1,73 @@ +--- +title: NetRequestGetVPortId method +topic_type: +- apiref +api_name: +- NetRequestGetVPortId +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestGetVPortId method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the VPortId for the NETREQUEST. + +Syntax +------ + +```cpp +NDIS_NIC_SWITCH_VPORT_ID NetRequestGetVPortId( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Returns an NDIS_NIC_SWITCH_VPORT_ID value that specifies the identifier associated with the net request object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NDIS_NIC_SWITCH_VPORT_PARAMETERS **](https://msdn.microsoft.com/library/windows/hardware/hh451597) diff --git a/windows-driver-docs-pr/netcx/netrequestmethodcomplete.md b/windows-driver-docs-pr/netcx/netrequestmethodcomplete.md new file mode 100644 index 0000000000..b57d802f85 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestmethodcomplete.md @@ -0,0 +1,94 @@ +--- +title: NetRequestMethodComplete method +topic_type: +- apiref +api_name: +- NetRequestMethodComplete +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestMethodComplete method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Completes a method (OID) request. + +Syntax +------ + +```cpp +VOID NetRequestMethodComplete( + _In_ NETREQUEST Request, + _In_ NTSTATUS   CompletionStatus, + _In_ UINT       BytesRead, + _In_ UINT       BytesWritten +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +*CompletionStatus* [in] +An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following: + +|Return code|Description| +|--|--| +|STATUS_SUCCESS|The driver successfully completed the request.| +|STATUS_CANCELLED|The driver canceled the request.| +|STATUS_UNSUCCESSFUL|The driver encountered an error while processing the request.| + +*BytesRead* [in] +The number of bytes that the client driver read from the request buffer. + +*BytesWritten* [in] +The number of bytes that the client driver wrote to the request buffer. + +Remarks +----- +Typically, the client driver calls **NetRequestMethodComplete** from one of its control request handler routines. For more info, see [Handling Control Requests](handling-control-requests.md#completing-requests). + +After this method returns, the request handle is no longer valid. NetAdapterCx removes it from the NETQUEUE and deletes the NETREQUEST object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NetRequestCompleteWithoutInformation**](netrequestcompletewithoutinformation.md) +[**NetRequestQueryDataComplete**](netrequestquerydatacomplete.md) +[**NetRequestSetDataComplete**](netrequestsetdatacomplete.md) diff --git a/windows-driver-docs-pr/netcx/netrequestquerydatacomplete.md b/windows-driver-docs-pr/netcx/netrequestquerydatacomplete.md new file mode 100644 index 0000000000..3b695f51ba --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestquerydatacomplete.md @@ -0,0 +1,90 @@ +--- +title: NetRequestQueryDataComplete method +topic_type: +- apiref +api_name: +- NetRequestQueryDataComplete +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestQueryDataComplete method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Completes a query data (OID) request. + +Syntax +------ + +```cpp +VOID NetRequestQueryDataComplete( + _In_ NETREQUEST Request, + _In_ NTSTATUS   CompletionStatus, + _In_ UINT       BytesWritten +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +*CompletionStatus* [in] +An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following: + +|Return code|Description| +|--|--| +|STATUS_SUCCESS|The driver successfully completed the request.| +|STATUS_CANCELLED|The driver canceled the request.| +|STATUS_UNSUCCESSFUL|The driver encountered an error while processing the request.| + +*BytesWritten* [in] +The number of bytes that the client driver wrote to the request buffer. + +Remarks +----- +Typically, the client driver calls **NetRequestQueryDataComplete** from one of its control request handler routines. For more info, see [Handling Control Requests](handling-control-requests.md#completing-requests). + +After this method returns, the request handle is no longer valid. NetAdapterCx removes it from the NETQUEUE and deletes the NETREQUEST object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NetRequestCompleteWithoutInformation**](netrequestcompletewithoutinformation.md) +[**NetRequestMethodComplete**](netrequestmethodcomplete.md) +[**NetRequestSetDataComplete**](netrequestsetdatacomplete.md) diff --git a/windows-driver-docs-pr/netcx/netrequestqueuecreate.md b/windows-driver-docs-pr/netcx/netrequestqueuecreate.md new file mode 100644 index 0000000000..bb7e0c5aa9 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestqueuecreate.md @@ -0,0 +1,134 @@ +--- +title: NetRequestQueueCreate method +topic_type: +- apiref +api_name: +- NetRequestQueueCreate +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetRequestQueueCreate method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Creates a net request queue object. + +Syntax +------ + +```cpp +NTSTATUS NetRequestQueueCreate( + _In_      PNET_REQUEST_QUEUE_CONFIG NetRequestQueueConfig, + _In_opt_  PWDF_OBJECT_ATTRIBUTES    QueueAttributes, + _Out_opt_ NETREQUESTQUEUE           *Queue +); +``` + +Parameters +---------- + +*NetRequestQueueConfig* [in] +A pointer to a caller-allocated [**NET_REQUEST_QUEUE_CONFIG**](net-request-queue-config.md) structure. + +*QueueAttributes* [in, optional] +An optional pointer to a caller-allocated [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure that specifies attributes for the net request queue object. + +*Queue* [out, optional] +An optional pointer to a location that receives a handle to the new net request queue object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +The client driver typically calls this method from its [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) routine after the client has called [**WdfDeviceCreate**](https://msdn.microsoft.com/library/windows/hardware/ff545926) and [**NetAdapterCreate**](netadaptercreate.md). + +The NETREQUESTQUEUE object represents an OID queue in the traditional NDIS model. + +Examples +-------- + +Typically, the client creates a queue for regular (sequential) OIDs, and may optionally also create a second queue for direct (parallel) OIDs. This example shows how to create a sequential queue. + +``` + NET_REQUEST_QUEUE_CONFIG config; + + // Initialize the Queue Config + NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL(&config, + AdapterContext->GetNetAdapter()); + + // + // Register default handlers as needed + // + config.EvtRequestDefaultSetData = EvtNetRequestSetData; + config.EvtRequestDefaultQueryData = EvtNetRequestQueryData; + config.EvtRequestDefaultMethod = EvtNetRequestMethod; + + // + // Add custom request handlers as needed + // + + + // + // Create the default NETREQUESTQUEUE + // + status = NetRequestQueueCreate(&config, + WDF_NO_OBJECT_ATTRIBUTES, + NULL); + +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + +[**NET_REQUEST_QUEUE_CONFIG_ADD_METHOD_HANDLER**](net-request-queue-config-add-method-handler.md) + +[**NET_REQUEST_QUEUE_CONFIG_ADD_QUERY_DATA_HANDLER**](net-request-queue-config-add-query-data-handler.md) + +[**NET_REQUEST_QUEUE_CONFIG_ADD_SET_DATA_HANDLER**](net-request-queue-config-add-set-data-handler.md) + +[**NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_PARALLEL**](net-request-queue-config-init-default-parallel.md) + +[**NET_REQUEST_QUEUE_CONFIG_INIT_DEFAULT_SEQUENTIAL**](net-request-queue-config-init-default-sequential.md) diff --git a/windows-driver-docs-pr/netcx/netrequestqueuegetadapter.md b/windows-driver-docs-pr/netcx/netrequestqueuegetadapter.md new file mode 100644 index 0000000000..fb440e62ff --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestqueuegetadapter.md @@ -0,0 +1,78 @@ +--- +title: NetRequestQueueGetAdapter method +topic_type: +- apiref +api_name: +- NetRequestQueueGetAdapter +api_location: +- netrequestqueue.h +api_type: +- HeaderDef +--- + +# NetRequestQueueGetAdapter method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the NETADAPTER object corresponding to the NETREQUESTQUEUE. + +Syntax +------ + +```cpp +NETADAPTER NetRequestQueueGetAdapter( + _In_ NETREQUESTQUEUE NetRequestQueue +); +``` + +Parameters +---------- + +*NetRequestQueue* [in] +A handle to a net request queue object. + +Return value +------------ + +Returns the NDIS adapter object that the client created in a prior call to [**NetAdapterCreate**](netadaptercreate.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequestqueue.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrequestretrieveinputoutputbuffer.md b/windows-driver-docs-pr/netcx/netrequestretrieveinputoutputbuffer.md new file mode 100644 index 0000000000..197b83c4be --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestretrieveinputoutputbuffer.md @@ -0,0 +1,98 @@ +--- +title: NetRequestRetrieveInputOutputBuffer method +topic_type: +- apiref +api_name: +- NetRequestRetrieveInputOutputBuffer +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestRetrieveInputOutputBuffer method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the input/output buffer associated with a NETREQUEST object. + +Syntax +------ + +```cpp +NTSTATUS NetRequestRetrieveInputOutputBuffer( + _In_    NETREQUEST Request, + _In_    UINT       MininumInputLengthRequired, + _In_    UINT       MininumOutputLengthRequired, + _Inout_ PVOID*     InputOutputBuffer, + _Out_   PUINT      InputBufferLength, + _Out_   PUINT      OutputBufferLength +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +*MininumInputLengthRequired* [in] +The minimum input length needed for *InputOutputBuffer*. If the buffer's *InputOutputBuffer* is less than the minimum required, this routine returns STATUS_BUFFER_TOO_SMALL. + +*MininumOutputLengthRequired* [in] +The minimum output length needed for *InputOutputBuffer*. If the buffer's *OutputBufferLength* is less than the minimum required, this routine returns STATUS_BUFFER_TOO_SMALL. + +*InputOutputBuffer* [in, out] +Address to a location that receives a pointer to the buffer. + +*InputBufferLength* [out] +Address to a location that receives the actual input length of *InputOutputBuffer*. + +*OutputBufferLength* [out] +Address to a location that receives the actual output length of *InputOutputBuffer*. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrequestsetbytesneeded.md b/windows-driver-docs-pr/netcx/netrequestsetbytesneeded.md new file mode 100644 index 0000000000..b562293445 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestsetbytesneeded.md @@ -0,0 +1,96 @@ +--- +title: NetRequestSetBytesNeeded method +topic_type: +- apiref +api_name: +- NetRequestSetBytesNeeded +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestSetBytesNeeded method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Sets the number of bytes needed to read or write for a control request (OID). + +Syntax +------ + +```cpp +VOID NetRequestSetBytesNeeded( + _In_ NETREQUEST Request, + _In_ UINT       BytesNeeded +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +*BytesNeeded* [in] +Number of bytes to be read or written. + +Remarks +--- +The client calls this routine if the I/O request fails due a smaller than expected InputOutputBuffer size. For example, to report that 8 bytes are required to support the requested OID: + +```cpp +status = STATUS_BUFFER_TOO_SMALL; +NetRequestSetBytesNeeded(Request, sizeof(ULONG64)); +``` + +Depending on the request type, *BytesNeeded* may mean space required perform a read operation or a write operation. + +After calling **NetRequestSetBytesNeeded**, the client calls one of the following methods, or [**NetRequestCompleteWithoutInformation**](netrequestcompletewithoutinformation.md): + + * [**NetRequestMethodComplete**](netrequestmethodcomplete.md) + * [**NetRequestQueryDataComplete**](netrequestquerydatacomplete.md) + * [**NetRequestSetDataComplete**](netrequestsetdatacomplete.md) + +For general info about control requests, see [Handling Control Requests](handling-control-requests.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrequestsetdatacomplete.md b/windows-driver-docs-pr/netcx/netrequestsetdatacomplete.md new file mode 100644 index 0000000000..a5c7133a15 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestsetdatacomplete.md @@ -0,0 +1,91 @@ +--- +title: NetRequestSetDataComplete method +topic_type: +- apiref +api_name: +- NetRequestSetDataComplete +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestSetDataComplete method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Completes a set data (OID) request. + +Syntax +------ + +```cpp +VOID NetRequestSetDataComplete( + _In_ NETREQUEST Request, + _In_ NTSTATUS   CompletionStatus, + _In_ UINT       BytesRead +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +*CompletionStatus* [in] +An NTSTATUS value that represents the completion status of the request. Valid status values include, but are not limited to, the following: + +|Return code|Description| +|--|--| +|STATUS_SUCCESS|The driver successfully completed the request.| +|STATUS_CANCELLED|The driver canceled the request.| +|STATUS_UNSUCCESSFUL|The driver encountered an error while processing the request.| + +*BytesRead* [in] +The number of bytes that the client driver read from the request buffer. + +Remarks +----- +Typically, the client driver calls **NetRequestSetDataComplete** from one of its control request handler routines. For more info, see [Handling Control Requests](handling-control-requests.md#completing-requests). + +After this method returns, the request handle is no longer valid. NetAdapterCx removes it from the NETQUEUE and deletes the NETREQUEST object. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +See Also +----- +[**NetRequestCompleteWithoutInformation**](netrequestcompletewithoutinformation.md) +[**NetRequestMethodComplete**](netrequestmethodcomplete.md) +[**NetRequestQueryDataComplete**](netrequestquerydatacomplete.md) + diff --git a/windows-driver-docs-pr/netcx/netrequestwdmgetndisoidrequest.md b/windows-driver-docs-pr/netcx/netrequestwdmgetndisoidrequest.md new file mode 100644 index 0000000000..b2836b3d32 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrequestwdmgetndisoidrequest.md @@ -0,0 +1,78 @@ +--- +title: NetRequestWdmGetNdisOidRequest method +topic_type: +- apiref +api_name: +- NetRequestWdmGetNdisOidRequest +api_location: +- netrequest.h +api_type: +- HeaderDef +--- + +# NetRequestWdmGetNdisOidRequest method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the traditional WDM [**NDIS_OID_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure for the NETREQUEST. + +Syntax +------ + +```cpp +PNDIS_OID_REQUEST NetRequestWdmGetNdisOidRequest( + _In_ NETREQUEST Request +); +``` + +Parameters +---------- + +*Request* [in] +A handle to a network request object. + +Return value +------------ + +Pointer to the [**NDIS_OID_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrequest.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbufferadvancenextpacket.md b/windows-driver-docs-pr/netcx/netringbufferadvancenextpacket.md new file mode 100644 index 0000000000..f854cbbb77 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbufferadvancenextpacket.md @@ -0,0 +1,97 @@ +--- +title: NetRingBufferAdvanceNextPacket method +topic_type: +- apiref +api_name: +- NetRingBufferAdvanceNextPacket +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NetRingBufferAdvanceNextPacket method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Increments the NextIndex value of the ring buffer and then returns a pointer to the packet at the new NextIndex value. + +Syntax +------ + +```cpp +__inline +NET_PACKET* NetRingBufferAdvanceNextPacket( + _In_ NET_RING_BUFFER *RingBuffer +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +Return value +------------ + +Returns **NULL** if the ring buffer's **NextIndex** equals its **EndIndex**, meaning there are no more unprocessed packets. +Otherwise, this routine returns a pointer to the [**NET_PACKET**](net-packet.md) at the new **NextIndex** value of the ring buffer. + +Remarks +----- + +Typically, your driver would use **NetRingBufferAdvanceNextPacket** in a loop to issue packets to hardware. + +For example: + +```cpp +NET_PACKET *nextPacket; +while (NULL != (nextPacket = NetRingBufferAdvanceNextPacket(ringBuffer))) { + ProgramPacketToMyHardware(nextPacket); +} +``` + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbuffergetelementatindex.md b/windows-driver-docs-pr/netcx/netringbuffergetelementatindex.md new file mode 100644 index 0000000000..44bac8e104 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbuffergetelementatindex.md @@ -0,0 +1,95 @@ +--- +title: NetRingBufferGetElementAtIndex method +topic_type: +- apiref +api_name: +- NetRingBufferGetElementAtIndex +api_location: +- netringbuffer.h +api_type: +- HeaderDef +--- + +# NetRingBufferGetElementAtIndex method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns the element at the specified index in the ring buffer. + +Syntax +------ + +```cpp +__inline +VOID* NetRingBufferGetElementAtIndex( + _In_ NET_RING_BUFFER *RingBuffer, + _In_ UINT32          Index +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +*Index* [in] +The element index, within the range [0, RingBuffer->NumberOfElements). + +Return value +------------ + +Returns the location of the specified element. + +Remarks +------- + +**NetRingBufferGetElementAtIndex** uses the ElementStride member of the ring buffer to index into the buffer and returns the location of the specified element. + +You'll need to cast the returned element to whatever data type your ring buffer elements use. + +**NetRingBufferGetElementAtIndex** is meant for generic use of ring buffers. Instead, a NetAdapterCx client driver typically calls [**NetRingBufferGetPacketAtIndex**](netringbuffergetpacketatindex.md). + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netringbuffer.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbuffergetnextpacket.md b/windows-driver-docs-pr/netcx/netringbuffergetnextpacket.md new file mode 100644 index 0000000000..9977fb0d38 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbuffergetnextpacket.md @@ -0,0 +1,103 @@ +--- +title: NetRingBufferGetNextPacket method +topic_type: +- apiref +api_name: +- NetRingBufferGetNextPacket +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NetRingBufferGetNextPacket method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns a pointer to the packet in a ring buffer at the ring buffer's **NextIndex** index value. + +Syntax +------ + +```cpp +NET_PACKET* NetRingBufferGetNextPacket( + _In_ NET_RING_BUFFER *RingBuffer +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +Return value +------------ + +Returns **NULL** if the ring buffer's **NextIndex** equals its **EndIndex**, meaning there are no more unprocessed packets. +Otherwise, this routine returns a pointer to the [**NET_PACKET**](net-packet.md) at the new **NextIndex** value of the ring buffer. + +Remarks +----- + +This routine is similar to [**NetRingBufferAdvanceNextPacket**](netringbufferadvancenextpacket.md). +The difference is that this routine does not modify the ring buffer's **NextIndex** field; the ring buffer is not modified. + +Typically, your driver would use **NetRingBufferGetNextPacket** to get the next packet to program into hardware. +Because **NetRingBufferGetNextPacket** does not increment **NextIndex**, you'll also eventually need to increment the index. +For example: + +```cpp +NET_PACKET *nextPacket; +while (NULL != (nextPacket = NetRingBufferGetNextPacket(ringBuffer))) { + if (!EnoughMemoryAvailableForPacket(nextPacket)) + break; + + ProgramPacketToMyHardware(nextPacket); + NetRingBufferAdvanceNextPacket(ringBuffer); +} +``` + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbuffergetnumberofelementsinrange.md b/windows-driver-docs-pr/netcx/netringbuffergetnumberofelementsinrange.md new file mode 100644 index 0000000000..4fc3a4937f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbuffergetnumberofelementsinrange.md @@ -0,0 +1,97 @@ +--- +title: NetRingBufferGetNumberOfElementsInRange method +topic_type: +- apiref +api_name: +- NetRingBufferGetNumberOfElementsInRange +api_location: +- netringbuffer.h +api_type: +- HeaderDef +--- + +# NetRingBufferGetNumberOfElementsInRange method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Calculates the number of elements contained in a range of the specified net ring buffer. + +Syntax +------ + +```cpp +__inline +UINT32 NetRingBufferGetNumberOfElementsInRange( + _In_ NET_RING_BUFFER *RingBuffer, + _In_ UINT32          StartIndex, + _In_ UINT32          EndIndex +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +*StartIndex* [in] +The inclusive start of the range to measure. + +*EndIndex* [in] +The exclusive end of the range to measure. + +Return value +------------ + +The number of elements in the given range. + +Remarks +------- + +For example, consider a net ring buffer containing a total of 8 elements. Index values for the elements are zero through 7. The number of elements in the range [1, 4) is 3. This is because the EndIndex value is not included, so the range includes elements at index values 1, 2, and 3. + +Similarly, the range [4, 1) includes elements at index values 4, 5, 6, 7, and 0 (looping back to the beginning of the ring), for a total of 5 elements. + +Finally, note that an empty range like [2, 2) returns zero elements. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netringbuffer.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbuffergetpacketatindex.md b/windows-driver-docs-pr/netcx/netringbuffergetpacketatindex.md new file mode 100644 index 0000000000..b86afe278f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbuffergetpacketatindex.md @@ -0,0 +1,89 @@ +--- +title: NetRingBufferGetPacketAtIndex method +topic_type: +- apiref +api_name: +- NetRingBufferGetPacketAtIndex +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NetRingBufferGetPacketAtIndex method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns a pointer to the net packet at the specified index value of the ring buffer. + +Syntax +------ + +```cpp +__inline +NET_PACKET* NetRingBufferGetPacketAtIndex( + _In_ NET_RING_BUFFER *RingBuffer, + _In_ UINT32          Index +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +*Index* [in] +The packet index, within the range [0, RingBuffer->NumberOfElements). + +Return value +------------ + +Returns a pointer to the net packet at the specified index value of the ring buffer. + +Remarks +----- + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbufferincrementindex.md b/windows-driver-docs-pr/netcx/netringbufferincrementindex.md new file mode 100644 index 0000000000..e54812547d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbufferincrementindex.md @@ -0,0 +1,95 @@ +--- +title: NetRingBufferIncrementIndex method +topic_type: +- apiref +api_name: +- NetRingBufferIncrementIndex +api_location: +- netringbuffer.h +api_type: +- HeaderDef +--- + +# NetRingBufferIncrementIndex method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns the next index value after the specified index value, wrapping around to the beginning of the ring buffer if necessary. + +Syntax +------ + +```cpp +UINT32 NetRingBufferIncrementIndex( + _In_ NET_RING_BUFFER *RingBuffer, + _In_ UINT32          Index +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +*Index* [in] +An index value to increment. + +Return value +------------ + +Returns the next index value after the specified index value, wrapping around to the beginning of the ring buffer if necessary. + +Remarks +------- + +This routine is equivalent to `Index++`, except it accounts for the wraparound of a ring buffer. + +For example, you can use this routine to return a packet to the operating system by incrementing **BeginIndex**: + +```cpp +NET_RING_BUFFER *ringBuffer = . . .; +ringBuffer->BeginIndex = NetRingBufferIncrementIndex(ringBuffer, ringBuffer->BeginIndex); +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netringbuffer.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbufferreturncompletedpackets.md b/windows-driver-docs-pr/netcx/netringbufferreturncompletedpackets.md new file mode 100644 index 0000000000..383b06809d --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbufferreturncompletedpackets.md @@ -0,0 +1,137 @@ +--- +title: NetRingBufferReturnCompletedPackets method +topic_type: +- apiref +api_name: +- NetRingBufferReturnCompletedPackets +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NetRingBufferReturnCompletedPackets method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns all packets that have the **Completed** flag set. + +Syntax +------ + +```cpp +void NetRingBufferReturnCompletedPackets( + _In_ NET_RING_BUFFER *RingBuffer +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +Return value +------------ + +This method does not return a value. + +Remarks +----- + +The NetAdapter data path requires packets to be completed in the order that they are given to your driver. +If your driver can complete some packets out of order, you can use **NetRingBufferReturnCompletedPackets** to simplify your completion path. + +To use this convenience function, first set the **Completed** flag on the first fragment of all packets with which your driver is finished, whether the packets were processed successfully or not. +Then, call **NetRingBufferReturnCompletedPackets** to batch the completion of all consecutive packets for which the first fragment has the **Completed** flag set. + +**NetRingBufferReturnCompletedPackets** completes packets by writing a new value to the **BeginIndex** of the ring buffer. + +If you always complete packets in order, it is more efficient to write to **BeginIndex** directly, rather than using the **Completed** flag with **NetRingBufferReturnCompletedPackets**. + +When you use **NetRingBufferReturnCompletedPackets**, it is most efficient to flag all finished packets and call the routine just once. + +Example +------- + +This example shows how a simple data path can complete packets if the hardware completes I/O requests in the order in which they were issued. +Note that this data path just writes to **BeginIndex** directly. + +```cpp +for (UINT i = ringBuffer->BeginIndex; + i != ringBuffer->EndIndex; + i = NetRingBufferIncrementIndex(ringBuffer, i)) +{ + NET_PACKET *packet = NetRingBufferGetPacketAtIndex(ringBuffer, i); + if (!MyHardwareIsDoneWithPacket(packet)) + break; + + // Complete the packet to the OS, simply by updating BeginIndex + ringBuffer->BeginIndex = i; +} +``` + +But suppose that your hardware or lower edge completes packets out of order. +Now you cannot just assign the index of the most recently completed packet to **BeginIndex**. +Instead, use the **Completed** flag with **NetRingBufferReturnCompletedPackets** to return packets safely. + +In this example, the lower edge returns a linked list of I/O completion blocks, and the list is not sorted in the order in which the I/O requests were issued. + +```cpp +void MyPacketCompletionCallback(MY_IO_REQUEST *io) +{ + while (io) { + NET_PACKET *packet = io->Packet; + packet->Data.Completed = TRUE; + + // Walk the linked list + io = io->Next; + } + + // Complete any packets to the OS. Updates BeginIndex for us. + NetRingBufferReturnCompletedPackets(ringBuffer); +} +``` + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netringbufferreturncompletedpacketsthroughindex.md b/windows-driver-docs-pr/netcx/netringbufferreturncompletedpacketsthroughindex.md new file mode 100644 index 0000000000..6cc7828e3e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netringbufferreturncompletedpacketsthroughindex.md @@ -0,0 +1,106 @@ +--- +title: NetRingBufferReturnCompletedPacketsThroughIndex method +topic_type: +- apiref +api_name: +- NetRingBufferReturnCompletedPacketsThroughIndex +api_location: +- netadapterpacket.h +api_type: +- HeaderDef +--- + +# NetRingBufferReturnCompletedPacketsThroughIndex method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Returns all packets that have the **Completed** flag set, up to a specified range. + +Syntax +------ + +```cpp +void NetRingBufferReturnCompletedPacketsThroughIndex( + _In_ NET_RING_BUFFER *RingBuffer, + _In_ UINT32          EndIndex +); +``` + +Parameters +---------- + +*RingBuffer* [in] +A pointer to a [**NET_RING_BUFFER**](net-ring-buffer.md). + +*EndIndex* [in] +The index of the last [**NET_PACKET**](net-packet.md) to be considered for completion. +This index is exclusive of the range, so the packet at this index value will not be completed. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +The NetAdapter data path requires packets to be completed in the order in which they are given to your driver. +If your driver can complete some packets out of order, you can use **NetRingBufferReturnCompletedPacketsThroughIndex** to simplify your completion path. + +To use this convenience function, first set the **Completed** flag on the first fragment of all packets with which your driver is finished, whether the packets were processed successfully or not. +Then, call **NetRingBufferReturnCompletedPacketsThroughIndex** to batch the completion of all consecutive packets for which the first fragment has the **Completed** flag set. + +**NetRingBufferReturnCompletedPacketsThroughIndex** completes packets by writing a new value to the **BeginIndex** of the ring buffer. + +If you always complete packets in order, it is more efficient to write to **BeginIndex** directly, rather than using the **Completed** flag with **NetRingBufferReturnCompletedPacketsThroughIndex**. + +Typically you would call **NetRingBufferReturnCompletedPacketsThroughIndex** once just before returning from [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) or [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md). +There's no advantage to calling **NetRingBufferReturnCompletedPacketsThroughIndex** more than once per Advance call; the API is designed for batching. + +The [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md) routine is similar, but examines all packets owned by your driver. +**NetRingBufferReturnCompletedPacketsThroughIndex** allows you to limit the search to a specific range of packets owned by your driver. +If you don't need to control the exact range of packets that are completed, you can use the simpler method [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md) instead of **NetRingBufferReturnCompletedPacketsThroughIndex**. + +For more info, see [Transferring Network Data](transferring-network-data.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netadapterpacket.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrxqueueconfiguredmaallocator.md b/windows-driver-docs-pr/netcx/netrxqueueconfiguredmaallocator.md new file mode 100644 index 0000000000..514322168e --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrxqueueconfiguredmaallocator.md @@ -0,0 +1,106 @@ +--- +title: NetRxQueueConfigureDmaAllocator method +topic_type: +- apiref +api_name: +- NetRxQueueConfigureDmaAllocator +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetRxQueueConfigureDmaAllocator method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Associates a WDFDMAENABLER object with a receive queue. + +Syntax +------ + +```cpp +NTSTATUS NetRxQueueConfigureDmaAllocator( + _In_ NETRXQUEUE    RxQueue, + _In_ WDFDMAENABLER Enabler +); +``` + +Parameters +---------- + +*RxQueue* [in] +The receive queue object that the client driver obtained from a previous call to [**NetRxQueueCreate**](netrxqueuecreate.md). + +*Enabler* [in] +A handle to a DMA enabler object that the client driver obtained from a previous call to [**WdfDmaEnablerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff546983). + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +The client driver can choose to let NetAdapterCx manage the receive buffer. To opt in: + + 1. Set the **AllocationSize** and **AlignmentRequirement** members of [**NET_RXQUEUE_CONFIG**](net-rxqueue-config.md). + 2. Call [**WdfDmaEnablerCreate**](https://msdn.microsoft.com/library/windows/hardware/ff546983), typically from the [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md) event callback function. + 3. Call **NetRxQueueConfigureDmaAllocator** with the initialized WDFDMAENABLER. + +NetAdapterCx uses the queue's DMA enabler to allocate pre-mapped buffers for each packet in the queue's [**NET_RING_BUFFER**](net-ring-buffer.md) structure, and updates the **VirtualAddress** and **DmaLogicalAddress** members of each [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) to point to each premapped buffer. + +The client driver retrieves a pointer to the ring buffer by calling [**NetTxQueueGetRingBuffer**](nettxqueuegetringbuffer.md) or [**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetRxQueue.h

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**NET_RXQUEUE_CONFIG**](net-rxqueue-config.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/netrxqueuecreate.md b/windows-driver-docs-pr/netcx/netrxqueuecreate.md new file mode 100644 index 0000000000..094922f6ea --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrxqueuecreate.md @@ -0,0 +1,103 @@ +--- +title: NetRxQueueCreate method +topic_type: +- apiref +api_name: +- NetRxQueueCreate +api_location: +- NetAdapterCxStub.lib +- NetAdapterCxStub.dll +api_type: +- LibDef +--- + +# NetRxQueueCreate method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Creates a net receive queue object. + +Syntax +------ + +```cpp +NTSTATUS NetRxQueueCreate( + _Inout_ PNETRXQUEUE_INIT       NetRxQueueInit, + _In_    PWDF_OBJECT_ATTRIBUTES RxQueueAttributes, + _In_    PNET_RXQUEUE_CONFIG    Configuration, + _Out_   NETRXQUEUE             *RxQueue +); +``` + +Parameters +---------- + +*NetRxQueueInit* [in, out] +A pointer to the **NETRXQUEUE_INIT** structure that the client driver received in [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md). + +*RxQueueAttributes* [in] +A pointer to caller-allocated [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure. The structure’s **ParentObject** must be NULL. The parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Configuration* [in] +A pointer to a caller-allocated [**NET_RXQUEUE_CONFIG**](net-rxqueue-config.md) structure. + +*RxQueue* [out] +A pointer to a location that receives a handle to the new net receive queue object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +The client calls **NetRxQueueCreate** from within its [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md) event callback function. For info on assigning context space to the new object, see [Framework Object Context Space](https://msdn.microsoft.com/windows/hardware/drivers/wdf/framework-object-context-space). + +The NETRXQUEUE object is a standard WDF object. The framework manages its deletion, which occurs when the parent WDFDEVICE is deleted. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

NetRxQueue.h (include Netadaptercx.h)

Library

NetAdapterCxStub.lib

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrxqueuegetringbuffer.md b/windows-driver-docs-pr/netcx/netrxqueuegetringbuffer.md new file mode 100644 index 0000000000..bfbed2dc9f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrxqueuegetringbuffer.md @@ -0,0 +1,78 @@ +--- +title: NetRxQueueGetRingBuffer method +topic_type: +- apiref +api_name: +- NetRxQueueGetRingBuffer +api_location: +- netrxqueue.h +api_type: +- HeaderDef +--- + +# NetRxQueueGetRingBuffer method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the net ring buffer for a specified net receive queue structure. + +Syntax +------ + +```cpp +PNET_RING_BUFFER NetRxQueueGetRingBuffer( + _In_ NETRXQUEUE NetRxQueue +); +``` + +Parameters +---------- + +*NetRxQueue* [in] +A handle to a net receive queue object. + +Return value +------------ + +Returns a pointer to the [**NET_RING_BUFFER**](net-ring-buffer.md) structure associated with a net receive queue structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrxqueueinitgetqueueid.md b/windows-driver-docs-pr/netcx/netrxqueueinitgetqueueid.md new file mode 100644 index 0000000000..59bc4a2ba9 --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrxqueueinitgetqueueid.md @@ -0,0 +1,84 @@ +--- +title: NetRxQueueInitGetQueueId method +topic_type: +- apiref +api_name: +- NetRxQueueInitGetQueueId +api_location: +- netrxqueue.h +api_type: +- HeaderDef +--- + +# NetRxQueueInitGetQueueId method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the identifier of the receive queue associated with a receive queue. + +Syntax +------ + +```cpp +ULONG NetRxQueueInitGetQueueId( + _In_ PNETRXQUEUE_INIT NetRxQueueInit +); +``` + +Parameters +---------- + +*NetRxQueueInit* [in] +A pointer to a NetAdapterCx-allocated **NETRXQUEUE_INIT** structure. For more information, see the Remarks section. + +Return value +------------ + +Returns a ULONG that identifies a receive queue. + +Remarks +--- +The client driver receives a pointer to a NETRXQUEUE_INIT structure in its [EVT_NET_ADAPTER_CREATE_RXQUEUE](evt-net-adapter-create-rxqueue.md) callback function. + +Starting with zero, NetAdapterCx assigns an unique identifier value for each queue that it creates. The client driver specifies the number of receive queues that the network adapter supports in the **NumRxQueues** member of the [NET_ADAPTER_DATAPATH_CAPABILITIES](net-adapter-datapath-capabilities.md) structure. The client driver passes this structure to [**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md). Identifier values range from zero to the value of **NumTxQueues** plus **NumRxQueues** minus one. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/netrxqueuenotifymorereceivedpacketsavailable.md b/windows-driver-docs-pr/netcx/netrxqueuenotifymorereceivedpacketsavailable.md new file mode 100644 index 0000000000..cc721b4a2f --- /dev/null +++ b/windows-driver-docs-pr/netcx/netrxqueuenotifymorereceivedpacketsavailable.md @@ -0,0 +1,94 @@ +--- +title: NetRxQueueNotifyMoreReceivedPacketsAvailable method +topic_type: +- apiref +api_name: +- NetRxQueueNotifyMoreReceivedPacketsAvailable +api_location: +- netrxqueue.h +api_type: +- HeaderDef +--- + +# NetRxQueueNotifyMoreReceivedPacketsAvailable method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver calls **NetRxQueueNotifyMoreReceivedPacketsAvailable** to resume queue operations after NetAdapterCx calls the client's [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) event callback routine. + +Syntax +------ + +```cpp +void NetRxQueueNotifyMoreReceivedPacketsAvailable( + _In_ NETRXQUEUE RxQueue +); +``` + +Parameters +---------- + +*RxQueue* [in] +A handle to a net receive queue object. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +After NetAdapterCx calls a client driver's [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) event callback routine with *NotificationEnabled* set to **TRUE**, the client enables the queue's hardware interrupt. When the device generates a hardware interrupt, the client typically calls **NetRxQueueNotifyMoreReceivedPacketsAvailable** from its [*EVT_WDF_INTERRUPT_DPC*](https://msdn.microsoft.com/library/windows/hardware/ff541721) callback function, after it completes a pending [**NET_PACKET**](net-packet.md) in the receive queue's [**NET_RING_BUFFER**](net-ring-buffer.md). + +The client should only call **NetRxQueueNotifyMoreReceivedPacketsAvailable** once per enabling of the notification. Do not call **NetRxQueueNotifyMoreReceivedPacketsAvailable** if NetAdapterCx calls [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) with *NotificationEnabled* set to **FALSE**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Netrxqueue.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) + +[*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/nettxqueuecreate.md b/windows-driver-docs-pr/netcx/nettxqueuecreate.md new file mode 100644 index 0000000000..22c70e196a --- /dev/null +++ b/windows-driver-docs-pr/netcx/nettxqueuecreate.md @@ -0,0 +1,99 @@ +--- +title: NetTxQueueCreate method +topic_type: +- apiref +api_name: +- NetTxQueueCreate +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NetTxQueueCreate method + + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Creates a net transmit queue object. + +Syntax +------ + +```cpp +NTSTATUS NetTxQueueCreate( + _Inout_ PNETTXQUEUE_INIT       NetTxQueueInit, + _In_    PWDF_OBJECT_ATTRIBUTES TxQueueAttributes, + _In_    PNET_TXQUEUE_CONFIG    Configuration, + _Out_   NETTXQUEUE             *TxQueue +); +``` + +Parameters +---------- + +*NetTxQueueInit* [in, out] +A pointer to the **NETTXQUEUE_INIT** structure that the client driver received in [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md). + +*TxQueueAttributes* [in] +A pointer to caller-allocated [**WDF_OBJECT_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff552400) structure. The structure’s **ParentObject** must be NULL. The parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. + +*Configuration* [in] +A pointer to a caller-allocated [**NET_TXQUEUE_CONFIG**](net-txqueue-config.md) structure. + +*TxQueue* [out] +A pointer to a location that receives a handle to the new net receive queue object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Remarks +------- + +The client calls **NetTxQueueCreate** from within its [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md) event callback function. For info on assigning context space to the new object, see [Framework Object Context Space](https://msdn.microsoft.com/windows/hardware/drivers/wdf/framework-object-context-space). + +The NETTXQUEUE object is a standard WDF object. The framework manages its deletion, which occurs when the parent WDFDEVICE is deleted. + + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Nettxqueue.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/nettxqueuegetringbuffer.md b/windows-driver-docs-pr/netcx/nettxqueuegetringbuffer.md new file mode 100644 index 0000000000..df1d026119 --- /dev/null +++ b/windows-driver-docs-pr/netcx/nettxqueuegetringbuffer.md @@ -0,0 +1,83 @@ +--- +title: NetTxQueueGetRingBuffer method +topic_type: +- apiref +api_name: +- NetTxQueueGetRingBuffer +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NetTxQueueGetRingBuffer method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the net ring buffer for a specified net transmit queue structure. + +Syntax +------ + +```cpp +PNET_RING_BUFFER NetTxQueueGetRingBuffer( + _In_ NETTXQUEUE NetTxQueue +); +``` + +Parameters +---------- + +*NetTxQueue* [in] +A handle to a net transmit queue object. + +Return value +------------ + +The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method may return an appropriate NTSTATUS error code. + +Return value +------------ + +Returns a pointer to the [**NET_RING_BUFFER**](net-ring-buffer.md) structure associated with a net transmit queue structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Nettxqueue.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/nettxqueueinitgetqueueid.md b/windows-driver-docs-pr/netcx/nettxqueueinitgetqueueid.md new file mode 100644 index 0000000000..620104c0d8 --- /dev/null +++ b/windows-driver-docs-pr/netcx/nettxqueueinitgetqueueid.md @@ -0,0 +1,84 @@ +--- +title: NetTxQueueInitGetQueueId method +topic_type: +- apiref +api_name: +- NetTxQueueInitGetQueueId +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NetTxQueueInitGetQueueId method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +Retrieves the identifier associated with a transmit queue. + +Syntax +------ + +```cpp +ULONG NetTxQueueInitGetQueueId( + _In_ PNETTXQUEUE_INIT NetTxQueueInit +); +``` + +Parameters +---------- + +*NetTxQueueInit* [in] +A pointer to a NetAdapterCx-allocated **NETTXQUEUE_INIT** structure. For more information, see the Remarks section. + +Return value +------------ + +Returns a ULONG that identifies a transmit queue. + +Remarks +----- +The client driver receives a pointer to a NETTXQUEUE_INIT structure in its [EVT_NET_ADAPTER_CREATE_TXQUEUE](evt-net-adapter-create-txqueue.md) callback function. + +Starting with zero, NetAdapterCx assigns an unique identifier value for each queue that it creates. The client driver specifies the number of transmit queues that the network adapter supports in the **NumTxQueues** member of the [NET_ADAPTER_DATAPATH_CAPABILITIES](net-adapter-datapath-capabilities.md) structure. The client driver passes this structure to [**NetAdapterSetDataPathCapabilities**](netadaptersetdatapathcapabilities.md). Identifier values range from zero to the value of **NumTxQueues** plus **NumRxQueues** minus one. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Nettxqueue.h (include Netadaptercx.h)

IRQL

PASSIVE_LEVEL

+ +  + +  + + + + + diff --git a/windows-driver-docs-pr/netcx/nettxqueuenotifymorecompletedpacketsavailable.md b/windows-driver-docs-pr/netcx/nettxqueuenotifymorecompletedpacketsavailable.md new file mode 100644 index 0000000000..fcac95b1c4 --- /dev/null +++ b/windows-driver-docs-pr/netcx/nettxqueuenotifymorecompletedpacketsavailable.md @@ -0,0 +1,93 @@ +--- +title: NetTxQueueNotifyMoreCompletedPacketsAvailable method +topic_type: +- apiref +api_name: +- NetTxQueueNotifyMoreCompletedPacketsAvailable +api_location: +- nettxqueue.h +api_type: +- HeaderDef +--- + +# NetTxQueueNotifyMoreCompletedPacketsAvailable method + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The client driver calls **NetTxQueueNotifyMoreCompletedPacketsAvailable** to resume queue operations after NetAdapterCx calls the client's [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) event callback routine. + +Syntax +------ + +```cpp +void NetTxQueueNotifyMoreCompletedPacketsAvailable( + _In_ NETTXQUEUE TxQueue +); +``` + +Parameters +---------- + +*TxQueue* [in] +A handle to a net transmit queue. + +Return value +------------ + +This method does not return a value. + +Remarks +------- + +After NetAdapterCx calls a client driver's [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) event callback routine with *NotificationEnabled* set to **TRUE**, the client enables the queue's hardware interrupt. When the device generates a hardware interrupt, the client typically calls **NetTxQueueNotifyMoreCompletedPacketsAvailable** from its [*EVT_WDF_INTERRUPT_DPC*](https://msdn.microsoft.com/library/windows/hardware/ff541721) callback function, after it completes a pending [**NET_PACKET**](net-packet.md) in the transmit queue's [**NET_RING_BUFFER**](net-ring-buffer.md). + +The client should only call **NetTxQueueNotifyMoreCompletedPacketsAvailable** once per enabling of the notification. Do not call **NetTxQueueNotifyMoreCompletedPacketsAvailable** if NetAdapterCx calls [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) with *NotificationEnabled* set to **FALSE**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Universal

Minimum KMDF version

1.21

Minimum NetAdapterCx version

1.0

Header

Nettxqueue.h (include Netadaptercx.h)

IRQL

<=DISPATCH_LEVEL

+ +## See also + + +[*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) + +[*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) + +  + +  + + + + + + diff --git a/windows-driver-docs-pr/netcx/porting-ndis-to-netadapter-cx.md b/windows-driver-docs-pr/netcx/porting-ndis-to-netadapter-cx.md new file mode 100644 index 0000000000..841a2249ac --- /dev/null +++ b/windows-driver-docs-pr/netcx/porting-ndis-to-netadapter-cx.md @@ -0,0 +1,179 @@ +# Porting NDIS miniport drivers to NetAdapter class extension + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +This page describes how to convert an NDIS 6.x miniport driver into a Windows Driver Framework (WDF) networking client driver. + +For general information about WDF, please review the [WDF Driver Development Guide](../wdf/index.md). + +## Compilation settings + +Open your existing NDIS miniport driver project in Visual Studio and use the following steps to convert it to a KMDF project. + +1. First, navigate to **Configuration Properties->Driver Settings->Driver Model** and verify that **Type of driver** is set to KMDF, and that **KMDF Version Major** and **KMDF Version Minor** are both empty. +2. In project properties, open **Driver Settings->Network Adapter Driver** and set **Link to the Network Adapter Class Extension** to **Yes**. + * If your converted driver will still call NDIS APIs, continue to link against `ndis.lib`. +3. Remove NDIS preprocessor macros, like NDIS650_MINIPORT=1. +4. Add the following headers to every source file (or to your common/precompiled header): +```cpp +#include +#include +#include +``` +5. Add [standard WDF decorations](../wdf/specifying-wdf-directives-in-inf-files.md) to your INF: + +```Inf +[Yourdriver.Wdf] +KmdfService = Yourdriverservice, Yourdriver.wdfsect + +[Yourdriver.wdfsect] +KmdfLibraryVersion = +``` + +6. Add new required networking keywords to the NT section of your INF. + +```cpp +[Device.NT] +CopyFiles=Drivers_Dir +; Existing network keywords +*IfType = 6 +*MediaType = 0 +*PhysicalMediaType = 14 +; New network keywords +*IfConnectorPresent = 0 ; BOOLEAN +*ConnectionType = 1 ; NET_IF_CONNECTION_TYPE +*DirectionType = 0 ; NET_IF_DIRECTION_TYPE +*AccessType = 2 ; NET_IF_ACCESS_TYPE +*HardwareLoopback = 0 ; BOOLEAN +``` + +## Driver initialization + +Remove the call to [**NdisMRegisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563654) from [*DriverEntry*](https://msdn.microsoft.com/library/windows/hardware/ff540807), and add the following: + +```cpp +WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd); +status = WdfDriverCreate(. . . ); +if (!NT_SUCCESS(status)) { + return status; +} +``` + +If it is set, remove the **WdfDriverInitNoDispatchOverride** flag from the call to [**WdfDriverCreate**](https://msdn.microsoft.com/library/windows/hardware/ff547175). + +*DriverUnload* is an optional routine for a WDF networking client driver, so you can remove it if you like. Do not call [**NdisMDeregisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563578) from *DriverUnload*. + +## Device initialization + +Next, you'll distribute code from *MiniportInitializeEx* into the appropriate WDF event callback handlers, several of which are optional. For details on the callback sequence, see [Power-Up Sequence for an Network Adapter WDF Client Driver](power-up-sequence-for-ndis-wdf-client-driver.md). + +For info on the callbacks you'll need to provide, see [Device Initialization](device-initialization.md). + +[*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md) is where the client calls the methods equivalent to [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672). However, instead of calling one routine with a generic [**NDIS_MINIPORT_ADAPTER_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565920) structure, the client driver calls different functions to set different types of capabilities. For more info, see the Remarks section of [*EVT_NET_ADAPTER_SET_CAPABILITIES*](evt-net-adapter-set-capabilities.md). + +## Creating queues to manage control requests + +Next, still in [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693), set up the object identifier (OID) path. The OID path is modeled like a WDF queue. But you'll be getting OIDs instead of WDFREQUESTs. + +There are two high level approaches you might take when porting this. The first option is to register a [*EVT_NET_REQUEST_DEFAULT*](evt-net-request-default.md) handler that receives OID requests in a very similar way to how a miniport driver receives requests from NDIS. This is the easiest port, since you'll likely just need to adjust a function signature from your old MINIPORT_OID_REQUEST handler. + +The other option is to break apart your OID handler's switch statement and provide a separate handler for each individual OID. You might choose this option if your device requires OID-specific functionality. + +If you used the [**Direct OID Request Interface in NDIS 6.1**](../network/direct-oid-request-interface-in-ndis-6-1.md), replace it with a parallel WDF queue. Similarly, the regular (serial) request interface in NDIS should become a sequential WDF queue. + +For info on registering handlers for OIDs, see [Handling Control Requests](handling-control-requests.md). + +## Reading configuration from the registry + +Next, replace calls to [**NdisOpenConfigurationEx**](https://msdn.microsoft.com/library/windows/hardware/ff563717) and related functions with the `NetConfiguration*` methods. The `NetConfiguration*` methods are similar to the `Ndis*Configuration*` functions, and you won't need to restructure your code. + +For more info, see [Accessing Configuration Information](accessing-configuration-information.md). + +## Receiving I/O control codes (IOTCLs) from user mode + +Read this section if your NDIS driver calls [**NdisRegisterDeviceEx**](https://msdn.microsoft.com/library/windows/hardware/ff564518), a routine used to create a control device object (CDO) to receive IOCTLs from user mode. + +Here are two ways to do this in your WDF networking client driver. + +The most straightforward port is to create a control device object by calling [**WdfControlDeviceInitAllocate**](https://msdn.microsoft.com/library/windows/hardware/ff545841) from the client's [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback. For more info, see [Using Control Device Objects](../wdf/using-control-device-objects.md). + +However, the recommended solution is to create a device interface, as described in [Using Device Interfaces](using-device-interfaces.md). + +## Finishing device initialization + +At this point in [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693), you can do anything else you'd like to initialize your device, like allocating interrupts. + +## Handling power state change notifications + +A WDF client driver does not receive [**OID_PNP_SET_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff569780) for power state changes. + +Instead, a WDF client registers optional callback functions to receive power state change notifications. For an overview, see [Supporting PnP and Power Management in Function Drivers](../wdf/supporting-pnp-and-power-management-in-function-drivers.md). + +Typically, the code in your [**OID_PNP_SET_POWER**](https://msdn.microsoft.com/library/windows/hardware/ff569780) handler moves to [*EVT_WDF_DEVICE_D0_EXIT*](https://msdn.microsoft.com/library/windows/hardware/ff540855) and [*EVT_WDF_DEVICE_D0_ENTRY*](https://msdn.microsoft.com/library/windows/hardware/ff540848). + +Because the WDF power state machine is slightly different, you might need to make minor modifications to the code. + +Specifically, in its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) callback function, an NDIS miniport driver performs one-time initialization tasks as well as work to bring the device to the D0 state. Then, it repeats the work to go to D0 in its [*OID_PNP_SET_POWER*](https://msdn.microsoft.com/library/windows/hardware/ff569780) handler. + +In contrast, a WDF client performs one-time initialization tasks in event callbacks before [**EVT_WDF_DEVICE_D0_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff540848), during which the device is in a low-power state. Then it does the work to go to D0 in [**EVT_WDF_DEVICE_D0_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff540848). + +To summarize, in WDF, you put your "go to D0" code in one place, instead of two. + +For details on the callback sequence, see [Power-Up Sequence for an Network Adapter WDF Client Driver](power-up-sequence-for-ndis-wdf-client-driver.md). + +## Querying and setting power management capabilities + +Similarly, a WDF client driver does not receive [**OID_PM_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff569768) to query or set power management hardware capabilities of the network adapter. + +Instead, the driver queries the necessary wake-on-LAN (WoL) configuration from the NETPOWERSETTINGS object. For more info, see [Configuring Power Management](configuring-power-management.md). + +The actual flags you get back have the same semantics as they do for an NDIS 6 miniport, so you don't need to make deep changes to the logic. The main difference is that you can now query these flags during the power-down sequence. See [Power-Down Sequence for an Network Adapter WDF Client Driver](power-down-sequence-for-ndis-wdf-client-driver.md). + +Once you've moved this code around, you can delete your OID handlers for [*OID_PNP_SET_POWER*](https://msdn.microsoft.com/library/windows/hardware/ff569780) and [*OID_PM_PARAMETERS*](https://msdn.microsoft.com/library/windows/hardware/ff569768). + +Because the NetAdapter framework keeps your device at D0 while the host uses the network interface, the client typically does not implement power logic; the default NetAdapter power behavior is sufficient. + +## Data path + +The data path programming model has changed significantly. Here are some key differences: + +* In the NetAdapter model, network traffic is no longer per adapter, as in NDIS, but rather per WDF queue. See [Creating I/O Queues](../wdf/creating-i-o-queues.md). +* Instead of NET_BUFFER_LIST and NET_BUFFER pools, NetAdapterCx introduces a ring buffer that is comprised of net packets, which map to NDIS as follows: + * A [**NET_PACKET**](net-packet.md) is similar to a NET_BUFFER_LIST + NET_BUFFER. + * A [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) is similar to a memory descriptor list (MDL). Each [**NET_PACKET**](net-packet.md) has one or more of these. + * For details on the replacement structures and how to use them, see [Transferring Network Data](transferring-network-data.md). +* In NDIS 6.x, the miniport needs to handle start and pause semantics. In the NetAdapterCx model, this is no longer the case. +* The [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) callback is similar to [**MINIPORT_RETURN_NET_BUFFER_LISTS**](https://msdn.microsoft.com/library/windows/hardware/ff559437) in NDIS 6.x. +* The [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) callback is similar to [**MINIPORT_SEND_NET_BUFFER_LISTS**](https://msdn.microsoft.com/library/windows/hardware/ff559440) in NDIS 6.x. + +## Device removal + +Device removal for a WDF NIC driver is the same as in any other WDF device driver, with no networking specific processing required. The network data path shuts down first, followed by the WDF device. For info about WDF shutdown, see [A User Unplugs a Device](../wdf/a-user-unplugs-a-device.md). + +Your *MiniportHaltEx* handler will likely be distributed between [*EVT_WDF_DEVICE_D0_EXIT*](https://msdn.microsoft.com/library/windows/hardware/ff540855) and [*EVT_WDF_DEVICE_RELEASE_HARDWARE*](https://msdn.microsoft.com/library/windows/hardware/ff540890). + +The WDF client does not need to delete the NetAdapter or any of the OID and datapath queues that it created. WDF deletes these objects automatically. + +You can delete *MiniportShutdownEx*, *MiniportResetEx* and *MiniportCheckForHangEx*. These callbacks are no longer supported. + +## NDIS-WDF function equivalents + +Most `NdisXxx` functions can be replaced with a WDF equivalent. In general, you should find that you need very little functionality that is imported from `NDIS.SYS`. + +For a list of function equivalents, see [NDIS-WDF Function Equivalents](ndis-wdf-function-equivalents.md). + +For functions with no WDF equivalent, the client can call [**NetAdapterWdmGetNdisHandle**](netadapterwdmgetndishandle.md) to retrieve an NDIS_HANDLE for use with NDIS functions. For example: + +```Management +NdisGetRssProcessorInformation(NetAdapterWdmGetNdisHandle(NetAdapter), . . .); +``` + +## Debugging + +See [Debugging NetAdapterCx Client Drivers](debugging-netadaptercx-client-drivers.md). + +The [!ndiskd.netadapter](../debugger/-ndiskd-netadapter.md) debugger extension shows similar results to what **!ndiskd.miniport** shows for an NDIS 6 driver. + +## Conclusion + +Using the steps in this topic, you should have a working driver that starts and stops your device. diff --git a/windows-driver-docs-pr/netcx/power-down-sequence-for-ndis-wdf-client-driver.md b/windows-driver-docs-pr/netcx/power-down-sequence-for-ndis-wdf-client-driver.md new file mode 100644 index 0000000000..bf48ae00b2 --- /dev/null +++ b/windows-driver-docs-pr/netcx/power-down-sequence-for-ndis-wdf-client-driver.md @@ -0,0 +1,15 @@ +--- +title: Power-Down Sequence for an Network Adapter WDF Client Driver +--- + +# Power-Down Sequence for an Network Adapter WDF Client Driver + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The following figure shows the order in which NetAdapterCx calls a client driver's event callback functions when powering down and removing the device. The sequence starts at the top of the figure with an operational device that is in the working power state (D0): + +![device enumeration and power-down sequence for NetAdapter client driver](images/powerdown.png) + +The broad horizontal lines mark the steps that are involved in powering down a device. The column on the left side of the figure describes the step, and the column on the right lists the event callbacks that accomplish it. + +As the figure shows, the power-down and removal sequence involves calling the corresponding "undo" callbacks in the reverse order in which the framework called the functions that are involved in making the device operational. The framework deletes the device object after it deletes the device object context area. diff --git a/windows-driver-docs-pr/netcx/power-up-sequence-for-ndis-wdf-client-driver.md b/windows-driver-docs-pr/netcx/power-up-sequence-for-ndis-wdf-client-driver.md new file mode 100644 index 0000000000..b8fad0a748 --- /dev/null +++ b/windows-driver-docs-pr/netcx/power-up-sequence-for-ndis-wdf-client-driver.md @@ -0,0 +1,16 @@ +--- +title: Power-Up Sequence for an Network Adapter WDF Client Driver +--- + +# Power-Up Sequence for an Network Adapter WDF Client Driver + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The following figure shows the order in which NetAdapterCx calls a client driver's event callback functions when bringing a device to the fully operational state, starting from the Device Arrived state at the bottom of the figure: + +![device enumeration and power-up sequence for NetAdapter client driver](images/powerup.png) + +The broad horizontal lines mark the steps that are involved in starting a device. The column on the left side of the figure describes the step, and the column on the right lists the event callbacks that accomplish it. + +At the bottom of the figure, the device is not present on the system. When the user inserts the device, the framework begins by calling the driver’s [*EvtDriverDeviceAdd*](https://msdn.microsoft.com/library/windows/hardware/ff541693) callback so that the driver can create a device object to represent the device. The framework continues calling the driver's callback routines by progressing up through the sequence until the device is operational. Remember that the framework invokes the event callbacks in bottom-up order as shown in the figure, so [*EvtDeviceFilterRemoveResourceRequirements*](https://msdn.microsoft.com/library/windows/hardware/ff540872) is called before [*EvtDeviceFilterAddResourceRequirements*](https://msdn.microsoft.com/library/windows/hardware/ff540870) and so on. If the device was stopped to rebalance resources or was physically present but in a low-power state, not all of the steps are required, as the figure shows. + diff --git a/windows-driver-docs-pr/netcx/summary-of-objects.md b/windows-driver-docs-pr/netcx/summary-of-objects.md new file mode 100644 index 0000000000..e70032e01b --- /dev/null +++ b/windows-driver-docs-pr/netcx/summary-of-objects.md @@ -0,0 +1,13 @@ +--- +title: Summary of Objects +--- + +# Summary of Objects + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +The following figure shows the default parent-child relationships for NetAdapterCx objects. Parent objects are at the top of the figure, so for example the NETADAPTER object is by default a child of the WDFDEVICE object. + +![summary of objs for NetAdapter client driver](images/netcx-adapter-object-model.png) + + diff --git a/windows-driver-docs-pr/netcx/transferring-network-data.md b/windows-driver-docs-pr/netcx/transferring-network-data.md new file mode 100644 index 0000000000..48ae26efaa --- /dev/null +++ b/windows-driver-docs-pr/netcx/transferring-network-data.md @@ -0,0 +1,124 @@ +--- +title: Transferring Network Data +--- + +# Transferring Network Data + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +To watch a video that introduces the data path model in NetAdapterCx, see [Network Adapter Class Extension: Data Path](https://aka.ms/netadapter/video3). + +In the NetAdapterCx model, network data requests are stored in WDF queues. Each queue is associated with a ring buffer, which contains a group of packets and pointers to indicate where in the ring to read and write next. + +## Creating transmit and receive queues + +When your client driver calls [**NET_ADAPTER_CONFIG_INIT**](net-adapter-config-init.md), typically from its [*EVT_WDF_DRIVER_DEVICE_ADD*](https://msdn.microsoft.com/library/windows/hardware/ff541693) event callback function, it provides two queue creation callbacks: [*EVT_NET_ADAPTER_CREATE_TXQUEUE*](evt-net-adapter-create-txqueue.md) and [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md). The client creates transmit and receive queues in these callbacks. + +For example, the client creates a transmit queue by calling [**NetTxQueueCreate**](nettxqueuecreate.md) as follows: + +```cpp +NTSTATUS +EvtAdapterCreateTxQueue(NETADAPTER Adapter, PNETTXQUEUE_INIT NetTxQueueInit) +{ + NETTXQUEUE txQueue; + + NET_TXQUEUE_CONFIG txQueueConfig; + NET_TXQUEUE_CONFIG_INIT(&txQueueConfig, + EvtTxQueueAdvance, + EvtTxQueueSetNotificationEnabled, + EvtTxQueueCancel); + + // Assign fixed size data type as per packet context + + NET_TXQUEUE_CONFIG_SET_DEFAULT_PACKET_CONTEXT_TYPE(&txConfig, MY_CONTEXT); + + NTSTATUS status = NetTxQueueCreate( + NetTxQueueInit, + WDF_NO_OBJECT_ATTRIBUTES, + &txQueueConfig, + &txQueue); + + return status; +} +``` + +To create a receive queue from [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md), use the same pattern to call [**NetRxQueueCreate**](netrxqueuecreate.md). For an example, see [*EVT_NET_ADAPTER_CREATE_RXQUEUE*](evt-net-adapter-create-rxqueue.md). + +The framework empties queues before transitioning to a low power state and deletes them before deleting the adapter. + +## Implementing queue callbacks + +When creating a transmit (Tx) queue, the client must provide pointers to all three of the following callback functions: + +* [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) +* [*EVT_TXQUEUE_SET_NOTIFICATION_ENABLED*](evt-txqueue-set-notification-enabled.md) +* [*EVT_TXQUEUE_CANCEL*](evt-txqueue-cancel.md) + +Similarly, when creating a receive (Rx) queue, the client must provide pointers to all three of the receive queue callbacks: + +* [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md) +* [*EVT_RXQUEUE_SET_NOTIFICATION_ENABLED*](evt-rxqueue-set-notification-enabled.md) +* [*EVT_RXQUEUE_CANCEL*](evt-rxqueue-cancel.md) + +See the above pages for details on what the client needs to do in each event callback function. + +## Using the ring buffer + +The [**NET_RING_BUFFER**](net-ring-buffer.md) is a circular buffer of one or more [**NET_PACKET**](net-packet.md) structures that is shared between NetAdapterCx and a client. + +Each element in a [**NET_RING_BUFFER**](net-ring-buffer.md) is owned by either the client driver or NetAdapterCx. The values of the index members control ownership. Specifically, the client driver owns every element from **BeginIndex** to **EndIndex - 1** inclusive. +For example, if **BeginIndex** is 2 and **EndIndex** is 5, the client driver owns three elements: the elements with index values 2, 3, and 4. +If **BeginIndex** is equal to **EndIndex**, the client driver does not own any elements. + +NetAdapterCx adds elements to the ring buffer by incrementing **EndIndex**. +A client driver returns ownership of the elements by incrementing **BeginIndex**. + +The client driver may optionally set **NextIndex** to the index of the next packet that it will submit to the hardware. + +![Using the ring buffer](images/using-the-ring-buffer.gif) + +In this model, the client has submitted packets with index values between **BeginIndex** and **NextIndex - 1** inclusive to hardware. Packets with index values between **NextIndex** and **EndIndex - 1** are owned by the client but have not yet been sent to hardware. If the value of **BeginIndex** is equal to the value of **NextIndex**, the client has not programmed any packets to hardware. + +After the hardware transmits or receives data, the client advances **BeginIndex** to transfer ownership of the packets to NetAdapterCx. If the client tracks packet completion using the **Completed** flag on **NET_PACKET_FRAGMENT**, the client can call [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md) to advance **BeginIndex** automatically through each completed packet. + +Because the ring buffer is circular, eventually the index values wrap around the end of the buffer and come back to the beginning. To handle wrap around when incrementing ring buffer indices, call [**NetRingBufferIncrementIndex**](NetRingBufferIncrementIndex.md). + +## Polling model + +The NetAdapter data path is a polling model. This polling model is implemented by calling the client driver's queue advance callbacks. For code examples, see [*EVT_TXQUEUE_ADVANCE*](evt-txqueue-advance.md) and [*EVT_RXQUEUE_ADVANCE*](evt-rxqueue-advance.md). + +## PCI Device Drivers + +Drivers for devices that use ring buffers at the hardware level (for example typical PCI NICs) typically manipulate the [**NET_RING_BUFFER**](net-ring-buffer.md) indices directly. + +Here is a typical sequence for a PCI device driver: + +1. Call [**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md) or [**NetTxQueueGetRingBuffer**](nettxqueuegetringbuffer.md) to retrieve the ring buffer. +2. Program packets to hardware by looping until the ring buffer's **NextIndex** equals **EndIndex**: + 1. Call [**NetRingBufferGetPacketAtIndex**](NetRingBufferGetPacketAtIndex.md) on **NextIndex**. + 2. Translate the **NET_PACKET** descriptor into the associated hardware packet descriptors. + 3. Call [**NetRingBufferIncrementIndex**](NetRingBufferIncrementIndex.md). +3. Complete packets by looping until **BeginIndex** equals **NextIndex** or until an incomplete packet is reached: + 1. Call [**NetRingBufferGetPacketAtIndex**](NetRingBufferGetPacketAtIndex.md) on **BeginIndex**. + 2. Detect if the associated hardware descriptors indicate completion. If not, terminate. + 3. Translate the hardware descriptor to the [**NET_PACKET**](net-packet.md). + 4. Call [**NetRingBufferIncrementIndex**](NetRingBufferIncrementIndex.md). + +## Device Drivers with Asynchronous I/O + +While a client driver that targets a device with an asynchronous I/O model such as USB can also modify the [**NET_RING_BUFFER**](net-ring-buffer.md) indices directly, we recommend instead using higher level routines to manage out of order completions: + +* [**NetRingBufferAdvanceNextPacket**](netringbufferadvancenextpacket.md) +* [**NetRingBufferGetNextPacket**](netringbuffergetnextpacket.md) +* [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md) + +Here is a typical sequence for a device driver with asynchronous I/O: + +1. Call [**NetRxQueueGetRingBuffer**](netrxqueuegetringbuffer.md) or [**NetTxQueueGetRingBuffer**](nettxqueuegetringbuffer.md) to retrieve the ring buffer. +2. Iterate on the packets in the ring buffer. Typically, do the following in a loop: + 1. Call [**NetRingBufferGetNextPacket**](netringbuffergetnextpacket.md). + 2. Program hardware to receive or transmit. This initiates the asynchronous I/O. + 3. Call [**NetRingBufferAdvanceNextPacket**](netringbufferadvancenextpacket.md). +3. Call [**NetRingBufferReturnCompletedPackets**](netringbufferreturncompletedpackets.md). + +As asynchronous I/O completions come in, the client sets the **Completed** flag of the associated [**NET_PACKET_FRAGMENT**](net-packet-fragment.md) to **TRUE**. This enables [**NetRingBufferReturnCompletedPackets**](NetRingBufferReturnCompletedPackets.md) to complete packets. diff --git a/windows-driver-docs-pr/netcx/using-device-interfaces.md b/windows-driver-docs-pr/netcx/using-device-interfaces.md new file mode 100644 index 0000000000..7bc944439c --- /dev/null +++ b/windows-driver-docs-pr/netcx/using-device-interfaces.md @@ -0,0 +1,24 @@ +--- +title: Using Device Interfaces +--- + +# Using Device Interfaces + +[!include[NetAdapterCx Beta Prerelease](../netcx-beta-prerelease.md)] + +To receive IOCTLs from user mode, the client driver calls [**WdfDeviceCreateDeviceInterface**](https://msdn.microsoft.com/library/windows/hardware/ff545935) with a reference string, as shown here: + +```cpp +DECLARE_CONST_UNICODE_STRING(c_RefString, L"MyRefString"); +status = WdfDeviceCreateDeviceInterface( + device, + &GUID_MY_DEVICE_INTERFACE, + &c_RefString); +if (!NT_SUCCESS(status)) { + return status; +} +``` + +When a user-mode application sends requests to a handle opened on a device interface with a reference string, your client driver receives the I/O requests. You can use [WDF queue objects](../wdf/framework-queue-objects.md) to handle the incoming I/O requests. If you do not provide a reference string, NDIS intercepts I/O requests sent to the device interface. + +For more info, see [Using WDF Device Interfaces](../wdf/using-device-interfaces.md). diff --git a/windows-driver-docs-pr/network/-ndis-status-dot11-wfd-group-operating-channel.md b/windows-driver-docs-pr/network/-ndis-status-dot11-wfd-group-operating-channel.md new file mode 100644 index 0000000000..0c7cd58663 --- /dev/null +++ b/windows-driver-docs-pr/network/-ndis-status-dot11-wfd-group-operating-channel.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_DOT11_WFD_GROUP_OPERATING_CHANNEL +author: windows-driver-content +ms.assetid: CAEFF142-3A87-4824-A0B1-73809B64BA85 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: +- NDIS_STATUS_DOT11_WFD_GROUP_OPERATING_CHANNEL Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_GROUP\_OPERATING\_CHANNEL + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The NDIS\_STATUS\_DOT11\_WFD\_GROUP\_OPERATING\_CHANNEL indication reports the current operating channel of a group. + +The data type for this indication is the [**DOT11\_WFD\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/hh406639) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_GROUP\_OPERATING\_CHANNEL indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_GROUP\_OPERATING\_CHANNEL. + +- **StatusBuffer** must be set to the address of a [**DOT11\_WFD\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/hh406639) structure. + +- **StatusBufferSize** must be set to **sizeof**(DOT11\_WFD\_CHANNEL). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8.

Header

Ndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20%20NDIS_STATUS_DOT11_WFD_GROUP_OPERATING_CHANNEL%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/-oid-dot11-wfd-connect-to-group-request.md b/windows-driver-docs-pr/network/-oid-dot11-wfd-connect-to-group-request.md new file mode 100644 index 0000000000..6694ea0f2e --- /dev/null +++ b/windows-driver-docs-pr/network/-oid-dot11-wfd-connect-to-group-request.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST object identifier (OID) requests that the miniport driver perform a connection operation to join a Wi-Fi Direct (WFD) group. +ms.assetid: 67B02FD9-1CB2-424D-989C-11A307070B93 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_CONNECT_TO_GROUP_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST object identifier (OID) requests that the miniport driver perform a connection operation to join a Wi-Fi Direct (WFD) group. The operation for this OID is identical to that of an [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) request for an Extensible Station (ExtSTA) port. For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +No data is associated with this OID. + +If the connection operation completes successfully, the miniport driver must transition to the WFD client operational (OP) state. The miniport driver must remain in the WFD client OP state until either a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) or set request of [OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST](oid-dot11-wfd-disconnect-from-group-request.md) is made. For more information about this state, see [Extensible Station Operating States](https://msdn.microsoft.com/library/windows/hardware/ff549883). + +When OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST is set, the miniport driver must fail the request by returning **NDIS\_STATUS\_POWER\_STATE\_INVALID** from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function if any of the following are true: + +- All of the PHYs specified through the ExtSTA *msDot11DesiredPhyList* MIB object are turned off through sets of [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). For more information about this MIB object, see [OID\_DOT11\_DESIRED\_PHY\_LIST](oid-dot11-desired-phy-list.md). + +- All of the PHYs specified through the ExtSTA *msDot11DesiredPhyList* MIB object are turned off through a hardware switch setting or proprietary software setting. + +- Additional criteria apply for the connection request to fail, as described in [General Connection Operation Guidelines](https://msdn.microsoft.com/library/windows/hardware/ff552458). + +When OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST is set, the miniport driver can do one of the following: + +- Wait for the connection operation to complete before completing the set request. + +- Initiate the connection operation and complete the set request. In this situation, the miniport driver must return **NDIS\_STATUS\_PENDING** from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the connection operation. After the reset operation has finished, the miniport driver completes the set request by calling [**NdisMRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) + +[OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) + +[OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST](oid-dot11-wfd-disconnect-from-group-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20%20OID_DOT11_WFD_CONNECT_TO_GROUP_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/-oid-dot11-wfd-group-join-parameters.md b/windows-driver-docs-pr/network/-oid-dot11-wfd-group-join-parameters.md new file mode 100644 index 0000000000..01a689d352 --- /dev/null +++ b/windows-driver-docs-pr/network/-oid-dot11-wfd-group-join-parameters.md @@ -0,0 +1,63 @@ +--- +title: OID\_DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS object identifier (OID) provides the parameters for a Wi-Fi Direct (WFD) client join request. +ms.assetid: 8BA9DC85-41DA-4021-BFBC-2C64A38146E9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_GROUP_JOIN_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS object identifier (OID) provides the parameters for a Wi-Fi Direct (WFD) client join request. + +The data type for this OID is the [**DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406655) structure. + +If **bInGroupFormation** == FALSE and **bWaitForWPSReady** == TRUE in the [**DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406655) structure, the wait time for the GO to set the Selected Registrar attribute may be up to several minutes. For exampe, in the invitation case, the GO waits for the user to enter a PIN at prompt. + +Depending on the parameters sent with this OID, the system may issue an [OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST](-oid-dot11-wfd-connect-to-group-request.md) resetting the port to cancel the connection request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406655) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20%20OID_DOT11_WFD_GROUP_JOIN_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/-oid-dot11-wfd-send-provision-discovery-request.md b/windows-driver-docs-pr/network/-oid-dot11-wfd-send-provision-discovery-request.md new file mode 100644 index 0000000000..d8155fc3f8 --- /dev/null +++ b/windows-driver-docs-pr/network/-oid-dot11-wfd-send-provision-discovery-request.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) device send a provision discovery request packet to a peer WFD device. +ms.assetid: 69490609-60CB-426F-8ED7-F8B35CDFCE2A +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) device send a provision discovery request packet to a peer WFD device. + +The data type for OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST is the [**DOT11\_SEND\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406556) structure. + +This OID is sent to the miniport as an **NdisRequestSetInformation** OID request type. + +After receiving this OID, the miniport must create and populate all the required Peer-to-Peer (P2P) attributes in the P2P Information Element (IE) before it sends the provision discovery request packet. + +After creating the packet for transmission, the miniport must complete the OID with status of **NDIS\_STATUS\_INDICATION\_REQUIRED**. The completion of the attempt to send the provision discovery request attempt must be indicated to the system with a [**NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439783) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE** indication once it has stopped the attempt to send the provision discovery request. This must occur in either case of success or failure. + +Miniport drivers should periodically attempt sending the Provision Discovery Request frame at intervals no longer than 50ms because a remote device may not be constantly available on its listen channel (or, operating channel in case of GO). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_SEND\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406556) + +[**NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439783) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20%20OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/TOC.md b/windows-driver-docs-pr/network/TOC.md index 130fe84463..21e080c115 100644 --- a/windows-driver-docs-pr/network/TOC.md +++ b/windows-driver-docs-pr/network/TOC.md @@ -26,54 +26,7 @@ ### [Packet Structures in Network Drivers](packet-structures-in-network-drivers.md) ### [Using Shared Memory in Network Drivers](using-shared-memory-in-network-drivers.md) ### [Asynchronous I/O and Completion Functions in Network Drivers](asynchronous-i-o-and-completion-functions-in-network-drivers.md) -### [NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) ### [Security Issues for Network Drivers](security-issues-for-network-drivers.md) -## [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) -### [Implementing an NDIS 6.40 Driver](implementing-an-ndis-6-40-driver.md) -### [Using NDIS 6.40 Data Structures](using-ndis-6-40-data-structures.md) -### [Compiling an NDIS 6.40 Driver](compiling-an-ndis-6-40-driver.md) -## [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) -### [Virtualized Networking Enhancements in NDIS 6.30](virtualized-networking-enhancements-in-ndis-6-30.md) -### [Power Management Enhancements in NDIS 6.30](power-management-enhancements-in-ndis-6-30.md) -### [Quality of Service (QoS) Support in NDIS 6.30](quality-of-service--qos--support-in-ndis-6-30.md) -### [Windows Filtering Platform Enhancements in NDIS 6.30](windows-filtering-platform-enhancements-in-ndis-6-30.md) -### [Scalable Networking Enhancements in NDIS 6.30](scalable-networking-enhancements-in-ndis-6-30.md) -### [Implementing an NDIS 6.30 Driver](implementing-an-ndis-6-30-driver.md) -### [Using NDIS 6.30 Data Structures](using-ndis-6-30-data-structures.md) -### [Compiling an NDIS 6.30 Driver](compiling-an-ndis-6-30-driver.md) -## [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) -### [Power Management Enhancements in NDIS 6.20](power-management-enhancements-in-ndis-6-20.md) -### [Virtual Machine Queue (VMQ) in NDIS 6.20](virtual-machine-queue--vmq--in-ndis-6-20.md) -### [Support for More than 64 Processors in NDIS 6.20](support-for-more-than-64-processors-in-ndis-6-20.md) -### [Receive Side Throttle in NDIS 6.20](receive-side-throttle-in-ndis-6-20.md) -### [Media Extensibility in NDIS 6.20](media-extensibility-in-ndis-6-20.md) -### [Implementing an NDIS 6.20 Driver](implementing-an-ndis-6-20-driver.md) -### [Using NDIS 6.20 Data Structures](using-ndis-6-20-data-structures.md) -### [Compiling an NDIS 6.20 Driver](compiling-an-ndis-6-20-driver.md) -## [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) -### [Header-Data Split in NDIS 6.1](header-data-split-in-ndis-6-1.md) -### [Direct OID Request Interface in NDIS 6.1](direct-oid-request-interface-in-ndis-6-1.md) -### [IPsec Task Offload Version 2 in NDIS 6.1](ipsec-task-offload-version-2-in-ndis-6-1.md) -### [NETDMA Updates in NDIS 6.1](netdma-updates-in-ndis-6-1.md) -### [Implementing an NDIS 6.1 Driver](implementing-an-ndis-6-1-driver.md) -### [Using NDIS 6.1 Data Structures](using-ndis-6-1-data-structures.md) -### [Compiling an NDIS 6.1 Driver](compiling-an-ndis-6-1-driver.md) -## [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) -### [NDIS 6.0 Design Objectives](ndis-6-0-design-objectives.md) -### [Enhanced Performance and Scalability](enhanced-performance-and-scalability.md) -#### [NET_BUFFER Data Packaging](net-buffer-data-packaging.md) -#### [Improved Send and Receive Paths](improved-send-and-receive-paths.md) -#### [Enhanced Run-time Reconfiguration Abilities](enhanced-run-time-reconfiguration-abilities.md) -#### [Receive Side Scaling Support](receive-scaling.md) -#### [New Scatter/Gather DMA Support](new-scatter-gather-dma-support.md) -#### [Faster filter drivers](filter-drivers.md) -#### [Full TCP Offload](full-tcp-offload.md) -### [Simplified Driver Model](simplified-driver-model.md) -#### [Easier Initialization](easier-initialization.md) -#### [Versioned Interfaces](versioned-interfaces.md) -#### [Simplified Reset Handling](simplified-reset-handling.md) -#### [NDIS Interface Information](ndis-interface-information.md) -#### [Easier-to-Write Filter Drivers](easier-to-write-filter-drivers.md) ## [Driver Stack Management](driver-stack-management.md) ### [NDIS Driver Stack](ndis-driver-stack.md) ### [Adapter States of a Miniport Driver](adapter-states-of-a-miniport-driver.md) @@ -88,7 +41,45 @@ ## [NET_BUFFER Architecture](net-buffer-architecture.md) ### [Network Data Structures](network-data-structures.md) #### [NET_BUFFER Structure](net-buffer-structure.md) +#### [NET_BUFFER Structure Macros](net-buffer-structure-macros.md) +##### [NET_BUFFER_CHECKSUM_BIAS](net-buffer-checksum-bias.md) +##### [NET_BUFFER_CURRENT_MDL](net-buffer-current-mdl.md) +##### [NET_BUFFER_CURRENT_MDL_OFFSET](net-buffer-current-mdl-offset.md) +##### [NET_BUFFER_DATA_LENGTH](net-buffer-data-length.md) +##### [NET_BUFFER_DATA_OFFSET](net-buffer-data-offset.md) +##### [NET_BUFFER_FIRST_MDL](net-buffer-first-mdl.md) +##### [NET_BUFFER_MINIPORT_RESERVED](net-buffer-miniport-reserved.md) +##### [NET_BUFFER_NEXT_NB](net-buffer-next-nb.md) +##### [NET_BUFFER_PROTOCOL_RESERVED](net-buffer-protocol-reserved.md) +##### [NET_BUFFER_SHARED_MEM_FLAGS](net-buffer-shared-mem-flags.md) +##### [NET_BUFFER_SHARED_MEM_HANDLE](net-buffer-shared-mem-handle.md) +##### [NET_BUFFER_SHARED_MEM_LENGTH](net-buffer-shared-mem-length.md) +##### [NET_BUFFER_SHARED_MEM_NEXT_SEGMENT](net-buffer-shared-mem-next-segment.md) +##### [NET_BUFFER_SHARED_MEM_OFFSET](net-buffer-shared-mem-offset.md) #### [NET_BUFFER_LIST Structure](net-buffer-list-structure.md) +#### [NET_BUFFER_LIST Structure Macros](net-buffer-list-structure-macros.md) +##### [NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO](ndis-nbl-add-media-specific-info.md) +##### [NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-add-media-specific-info-ex.md) +##### [NDIS_NBL_GET_MEDIA_SPECIFIC_INFO](ndis-nbl-get-media-specific-info.md) +##### [NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-get-media-specific-info-ex.md) +##### [NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO](ndis-nbl-remove-media-specific-info.md) +##### [NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-remove-media-specific-info-ex.md) +##### [NdisSetNetBufferListProtocolId](ndissetnetbufferlistprotocolid.md) +##### [NET_BUFFER_LIST_CONTEXT_DATA_SIZE](net-buffer-list-context-data-size.md) +##### [NET_BUFFER_LIST_CONTEXT_DATA_START](net-buffer-list-context-data-start.md) +##### [NET_BUFFER_LIST_FIRST_NB](net-buffer-list-first-nb.md) +##### [NET_BUFFER_LIST_FLAGS](net-buffer-list-flags.md) +##### [NET_BUFFER_LIST_MINIPORT_RESERVED](net-buffer-list-miniport-reserved.md) +##### [NET_BUFFER_LIST_NEXT_NBL](net-buffer-list-next-nbl.md) +##### [NET_BUFFER_LIST_INFO](net-buffer-list-info.md) +##### [NET_BUFFER_LIST_STATUS](net-buffer-list-status.md) +##### [NET_BUFFER_LIST_PROTOCOL_RESERVED](net-buffer-list-protocol-reserved.md) +##### [NET_BUFFER_LIST_RECEIVE_FILTER_ID](net-buffer-list-receive-filter-id.md) +#### [NET_BUFFER_LIST Flags Macros](net-buffer-list-flags-macros.md) +##### [NdisTestNblFlag](ndistestnblflag.md) +##### [NdisTestNblFlags](ndistestnblflags.md) +##### [NdisSetNblFlag](ndissetnblflag.md) +##### [NdisClearNblFlag](ndisclearnblflag.md) #### [NET_BUFFER_LIST_CONTEXT Structure](net-buffer-list-context-structure.md) ### [Retreat and Advance Operations](retreat-and-advance-operations.md) #### [Retreat Operations](retreat-operations.md) @@ -100,6 +91,9 @@ #### [Canceling a Send Operation](canceling-a-send-operation.md) #### [Receiving Network Data](receiving-network-data.md) #### [Looping Back NDIS Packets](looping-back-ndis-packets.md) +### [NDIS NET_BUFFER Send and Receive Macros](ndis-net-buffer-send-and-receive-macros.md) +#### [NDIS_SET_NET_BUFFER_LIST_CANCEL_ID](ndis-set-net-buffer-list-cancel-id.md) +#### [NDIS_GET_NET_BUFFER_LIST_CANCEL_ID](ndis-get-net-buffer-list-cancel-id.md) ### [Ethernet Send and Receive Operations](ethernet-send-and-receive-operations.md) #### [Sending Ethernet Frames](sending-ethernet-frames.md) #### [Indicating Received Ethernet Frames](indicating-received-ethernet-frames.md) @@ -108,124 +102,179 @@ #### [Cloned NET_BUFFER_LIST Structures](cloned-net-buffer-list-structures.md) #### [Fragmented NET_BUFFER_LIST Structures](fragmented-net-buffer-list-structures.md) #### [Reassembled NET_BUFFER_LIST Structures](reassembled-net-buffer-list-structures.md) +## [Introduction to NDIS PDPI](introduction-to-ndis-pdpi.md) +# [NDIS version guide](ndis-version-guide.md) +## [Overview of NDIS versions](overview-of-ndis-versions.md) +## [Introductions to NDIS 6.0 and later](introductions-to-ndis-6-0-and-later.md) +### [Introduction to NDIS 6.70](introduction-to-ndis-6-70.md) +### [Introduction to NDIS 6.60](introduction-to-ndis-6-60.md) +### [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md) +### [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) +#### [Implementing an NDIS 6.40 Driver](implementing-an-ndis-6-40-driver.md) +#### [Using NDIS 6.40 Data Structures](using-ndis-6-40-data-structures.md) +#### [Compiling an NDIS 6.40 Driver](compiling-an-ndis-6-40-driver.md) +### [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +#### [Virtualized Networking Enhancements in NDIS 6.30](virtualized-networking-enhancements-in-ndis-6-30.md) +#### [Power Management Enhancements in NDIS 6.30](power-management-enhancements-in-ndis-6-30.md) +#### [Quality of Service (QoS) Support in NDIS 6.30](quality-of-service--qos--support-in-ndis-6-30.md) +#### [Windows Filtering Platform Enhancements in NDIS 6.30](windows-filtering-platform-enhancements-in-ndis-6-30.md) +#### [Scalable Networking Enhancements in NDIS 6.30](scalable-networking-enhancements-in-ndis-6-30.md) +#### [Implementing an NDIS 6.30 Driver](implementing-an-ndis-6-30-driver.md) +#### [Using NDIS 6.30 Data Structures](using-ndis-6-30-data-structures.md) +#### [Compiling an NDIS 6.30 Driver](compiling-an-ndis-6-30-driver.md) +### [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +#### [Power Management Enhancements in NDIS 6.20](power-management-enhancements-in-ndis-6-20.md) +#### [Virtual Machine Queue (VMQ) in NDIS 6.20](virtual-machine-queue--vmq--in-ndis-6-20.md) +#### [Support for More than 64 Processors in NDIS 6.20](support-for-more-than-64-processors-in-ndis-6-20.md) +#### [Receive Side Throttle in NDIS 6.20](receive-side-throttle-in-ndis-6-20.md) +#### [Media Extensibility in NDIS 6.20](media-extensibility-in-ndis-6-20.md) +#### [Implementing an NDIS 6.20 Driver](implementing-an-ndis-6-20-driver.md) +#### [Using NDIS 6.20 Data Structures](using-ndis-6-20-data-structures.md) +#### [Compiling an NDIS 6.20 Driver](compiling-an-ndis-6-20-driver.md) +### [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +#### [Header-Data Split in NDIS 6.1](header-data-split-in-ndis-6-1.md) +#### [Direct OID Request Interface in NDIS 6.1](direct-oid-request-interface-in-ndis-6-1.md) +#### [IPsec Task Offload Version 2 in NDIS 6.1](ipsec-task-offload-version-2-in-ndis-6-1.md) +#### [NETDMA Updates in NDIS 6.1](netdma-updates-in-ndis-6-1.md) +#### [Implementing an NDIS 6.1 Driver](implementing-an-ndis-6-1-driver.md) +#### [Using NDIS 6.1 Data Structures](using-ndis-6-1-data-structures.md) +#### [Compiling an NDIS 6.1 Driver](compiling-an-ndis-6-1-driver.md) +### [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) +#### [NDIS 6.0 Design Objectives](ndis-6-0-design-objectives.md) +#### [Enhanced Performance and Scalability](enhanced-performance-and-scalability.md) +##### [NET_BUFFER Data Packaging](net-buffer-data-packaging.md) +##### [Improved Send and Receive Paths](improved-send-and-receive-paths.md) +##### [Enhanced Run-time Reconfiguration Abilities](enhanced-run-time-reconfiguration-abilities.md) +##### [Receive Side Scaling Support](receive-scaling.md) +##### [New Scatter/Gather DMA Support](new-scatter-gather-dma-support.md) +##### [Faster filter drivers](filter-drivers.md) +##### [Full TCP Offload](full-tcp-offload.md) +#### [Simplified Driver Model](simplified-driver-model.md) +##### [Easier Initialization](easier-initialization.md) +##### [Versioned Interfaces](versioned-interfaces.md) +##### [Simplified Reset Handling](simplified-reset-handling.md) +##### [NDIS Interface Information](ndis-interface-information.md) +##### [Easier-to-Write Filter Drivers](easier-to-write-filter-drivers.md) ## [Specifying NDIS Version Information](specifying-ndis-version-information.md) ### [Overview of NDIS Support for Header Versions](overview-of-ndis-support-for-header-versions.md) ### [Version Information Requirements for NDIS Drivers](version-information-requirements-for-ndis-drivers.md) ### [Version Information Requirements for NDIS](version-information-requirements-for-ndis.md) ### [Obtaining the NDIS Version](obtaining-the-ndis-version.md) ### [NDIS Object Version Issues for WMI](ndis-object-version-issues-for-wmi.md) -## [Introduction to NDIS PDPI](introduction-to-ndis-pdpi.md) -# [Porting NDIS Drivers to Newer NDIS Versions](porting-ndis-drivers-to-newer-ndis-versions.md) -## [Porting NDIS 6.x Drivers to NDIS 6.40](porting-ndis-6-x-drivers-to-ndis-6-40.md) -## [Porting NDIS 6.x Drivers to NDIS 6.30](porting-ndis-6-x-drivers-to-ndis-6-30.md) -### [NDIS 6.30 Backward Compatibility](ndis-6-30-backward-compatibility.md) -### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.30](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-30.md) -### [Summary of Changes Required to Port a Protocol or Filter Driver to NDIS 6.30](summary-of-changes-required-to-port-a-protocol-or-filter-driver-to-ndis-6-30.md) -### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.30](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-30.md) -## [Porting NDIS 6.x Drivers to NDIS 6.20](porting-ndis-6-x-drivers-to-ndis-6-20.md) -### [NDIS 6.20 Backward Compatibility](ndis-6-20-backward-compatibility.md) -### [NDIS 6.20 Updates to NDIS 6.1 Features](ndis-6-20-updates-to-ndis-6-1-features.md) -### [Obsolete Interfaces in NDIS 6.20](obsolete-interfaces-in-ndis-6-20.md) -### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.20](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-20.md) -### [Summary of Changes Required to Port a Protocol Driver to NDIS 6.20](summary-of-changes-required-to-port-a-protocol-driver-to-ndis-6-20.md) -### [Summary of Changes Required to Port a Filter Driver to NDIS 6.20](summary-of-changes-required-to-port-a-filter-driver-to-ndis-6-20.md) -### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.20](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-2.md) -## [Porting NDIS 5.x Drivers to NDIS 6.0](porting-ndis-5-x-drivers-to-ndis-6-0.md) -### [NDIS 6.0 Backward Compatibility](ndis-6-0-backward-compatibility.md) -### [Porting a Miniport Driver to NDIS 6.0](porting-a-miniport-driver-to-ndis-6-0.md) -#### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.0](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-0.md) -#### [Porting Miniport Driver Initialization to NDIS 6.0](porting-miniport-driver-initialization-to-ndis-6-0.md) -##### [Updating the DriverEntry Routine for an NDIS 6.0 Miniport Driver](updating-the-driverentry-routine-for-an-ndis-6-0-miniport-driver.md) -##### [Updating the NDIS 6.0 Miniport Driver Characteristics Structure](updating-the-ndis-6-0-miniport-driver-characteristics-structure.md) -##### [Registering Optional NDIS 6.0 Entry Points for Miniport Drivers](registering-optional-ndis-6-0-entry-points-for-miniport-drivers.md) -#### [Porting Miniport Driver Unload Operations to NDIS 6.0](porting-miniport-driver-unload-operations-to-ndis-6-0.md) -#### [Porting Miniport Adapter Initialization to NDIS 6.0](porting-miniport-adapter-initialization-to-ndis-6-0.md) -##### [Updating the MiniportInitialize Function for NDIS 6.0](updating-the-miniportinitialize-function-for-ndis-6-0.md) -##### [Setting the NDIS 6.0 Miniport Adapter Attributes](setting-the-ndis-6-0-miniport-adapter-attributes.md) -##### [Reading the Registry in an NDIS 6.0 Miniport Driver](reading-the-registry-in-an-ndis-6-0-miniport-driver.md) -##### [Allocating Memory in an NDIS 6.0 Miniport Driver](allocating-memory-in-an-ndis-6-0-miniport-driver.md) -##### [Updating Bus-Specific Configuration Space Access for NDIS 6.0](updating-bus-specific-configuration-space-access-for-ndis-6-0.md) -#### [Porting Miniport Adapter Halt Operations to NDIS 6.0](porting-miniport-adapter-halt-operations-to-ndis-6-0.md) -#### [Supporting NDIS 6.0 Miniport Adapter Pause and Restart Operations](supporting-ndis-6-0-miniport-adapter-pause-and-restart-operations.md) -#### [Porting Miniport Driver Send and Receive Operations to NDIS 6.0](porting-miniport-driver-send-and-receive-operations-to-ndis-6-0.md) -##### [Allocating Network Data Pools in an NDIS 6.0 Miniport Driver](allocating-network-data-pools-in-an-ndis-6-0-miniport-driver.md) -##### [Porting NDIS Miniport Driver Send Data Handling](porting-ndis-miniport-driver-send-data-handling.md) -##### [Porting NDIS Miniport Driver Receive Data Handling](porting-ndis-miniport-driver-receive-data-handling.md) -#### [Porting Miniport Driver DMA Operations to NDIS 6.0](porting-miniport-driver-dma-operations-to-ndis-6-0.md) -#### [Porting Miniport Driver Interrupt Operations to NDIS 6.0](porting-miniport-driver-interrupt-operations-to-ndis-6-0.md) -##### [Porting Interrupt Registration to NDIS 6.0](porting-interrupt-registration-to-ndis-6-0.md) -##### [Porting Interrupt Handling to NDIS 6.0](porting-interrupt-handling-to-ndis-6-0.md) -##### [Supporting Message Signaled Interrupts in NDIS 6.0](supporting-message-signaled-interrupts-in-ndis-6-0.md) -#### [Porting Miniport Driver OID Request Handling to NDIS 6.0](porting-miniport-driver-oid-request-handling-to-ndis-6-0.md) -#### [Porting Miniport Driver Status Indications to NDIS 6.0](porting-miniport-driver-status-indications-to-ndis-6-0.md) -#### [Porting Miniport Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-miniport-driver-plug-and-play-event-notification-handling-to-n.md) -#### [Porting Miniport Adapter Check for Hang and Reset Operations to NDIS 6.0](porting-miniport-adapter-check-for-hang-and-reset-operations-to-ndis-6.md) -#### [Porting Miniport Adapter Shutdown Operations to NDIS 6.0](porting-miniport-adapter-shutdown-operations-to-ndis-6-0.md) -### [Porting a Protocol Driver to NDIS 6.0](porting-a-protocol-driver-to-ndis-6-0.md) -#### [Summary of Changes Required to Port a Protocol Driver to NDIS 6.0](summary-of-changes-required-to-port-a-protocol-driver-to-ndis-6-0.md) -#### [Porting Protocol Driver Initialization to NDIS 6.0](porting-protocol-driver-initialization-to-ndis-6-0.md) -##### [Updating the DriverEntry Routine for an NDIS 6.0 Protocol Driver](updating-the-driverentry-routine-for-an-ndis-6-0-protocol-driver.md) -##### [Updating the NDIS 6.0 Protocol Driver characteristics Structure](updating-the-ndis-6-0-protocol-driver-characteristics-structure.md) -##### [Registering Optional NDIS 6.0 Protocol Driver Entry Points](registering-optional-ndis-6-0-protocol-driver-entry-points.md) -#### [Porting Protocol Driver Unload Operations to NDIS 6.0](porting-protocol-driver-unload-operations-to-ndis-6-0.md) -#### [Porting Protocol Binding Operations to NDIS 6.0](porting-protocol-binding-operations-to-ndis-6-0.md) -##### [Updating the ProtocolBindAdapter Function for an NDIS 6.0 Protocol Driver](updating-the-protocolbindadapter-function-for-an-ndis-6-0-protocol-dri.md) -##### [Opening an Adapter in an NDIS 6.0 Protocol Driver](opening-an-adapter-in-an-ndis-6-0-protocol-driver.md) -##### [Reading the Registry in an NDIS 6.0 Protocol Driver](reading-the-registry-in-an-ndis-6-0-protocol-driver.md) -##### [Allocating Memory in an NDIS 6.0 Protocol Driver](allocating-memory-in-an-ndis-6-0-protocol-driver.md) -#### [Porting Protocol Unbinding Operations to NDIS 6.0](porting-protocol-unbinding-operations-to-ndis-6-0.md) -#### [Supporting NDIS 6.0 Protocol Binding Pause and Restart Operations](supporting-ndis-6-0-protocol-binding-pause-and-restart-operations.md) -#### [Porting Protocol Driver Send and Receive Operations to NDIS 6.0](porting-protocol-driver-send-and-receive-operations-to-ndis-6-0.md) -##### [Allocating Network Data Pools in an NDIS 6.0 Protocol Driver](allocating-network-data-pools-in-an-ndis-6-0-protocol-driver.md) -##### [Porting NDIS Protocol Driver Send Data Handling](porting-ndis-protocol-driver-send-data-handling.md) -##### [Porting NDIS Protocol Driver Receive Data Handling](porting-ndis-protocol-driver-receive-data-handling.md) -#### [Porting Protocol Driver OID Request Handling to NDIS 6.0](porting-protocol-driver-oid-request-handling-to-ndis-6-0.md) -#### [Porting Protocol Driver Status Indication Handling to NDIS 6.0](porting-protocol-driver-status-indication-handling-to-ndis-6-0.md) -#### [Porting Protocol Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-protocol-driver-plug-and-play-event-notification-handling-to-n.md) -### [Porting an Intermediate Driver to NDIS 6.0](porting-an-intermediate-driver-to-ndis-6-0.md) -#### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.0](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-0.md) -#### [Porting Intermediate Driver Initialization to NDIS 6.0](porting-intermediate-driver-initialization-to-ndis-6-0.md) -#### [Porting Intermediate Driver Unload Operations to NDIS 6.0](porting-intermediate-driver-unload-operations-to-ndis-6-0.md) -#### [Porting Virtual Miniport Initialization to NDIS 6.0](porting-virtual-miniport-initialization-to-ndis-6-0.md) -#### [Porting Virtual Miniport Halt Operations to NDIS 6.0](porting-virtual-miniport-halt-operations-to-ndis-6-0.md) -#### [Supporting Pause and Restart Operations in an NDIS 6.0 Intermediate Driver](supporting-pause-and-restart-operations-in-an-ndis-6-0-intermediate-dr.md) -#### [Porting Intermediate Driver Send and Receive Operations to NDIS 6.0](porting-intermediate-driver-send-and-receive-operations-to-ndis-6-0.md) -#### [Porting Intermediate Driver OID Request Handling to NDIS 6.0](porting-intermediate-driver-oid-request-handling-to-ndis-6-0.md) -#### [Porting Intermediate Driver Status Indication Handling to NDIS 6.0](porting-intermediate-driver-status-indication-handling-to-ndis-6-0.md) -#### [Porting Intermediate Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-intermediate-driver-plug-and-play-event-notification-handling-.md) -### [Porting a CoNDIS 5.x Driver to CoNDIS 6.0](porting-a-condis-5-x-driver-to-condis-6-0.md) -#### [Summary of Changes Required to Port a CoNDIS Driver to CoNDIS 6.0](summary-of-changes-required-to-port-a-condis-driver-to-condis-6-0.md) -#### [Porting CoNDIS Driver Registration to CoNDIS 6.0](porting-condis-driver-registration-to-condis-6-0.md) -##### [Porting CoNDIS Miniport Driver Registration](porting-condis-miniport-driver-registration.md) -##### [Porting CoNDIS Client Registration](porting-condis-client-registration.md) -##### [Porting CoNDIS Call Manager Registration](porting-condis-call-manager-registration.md) -##### [Porting CoNDIS MCM Registration](porting-condis-mcm-registration.md) -#### [Porting Address Family Close Operations to CoNDIS 6.0](porting-address-family-close-operations-to-condis-6-0.md) -#### [Porting Send and Receive Operations to CoNDIS 6.0](porting-send-and-receive-operations-to-condis-6-0.md) -##### [Porting Miniport Driver Send and Receive Operations to CoNDIS 6.0](porting-miniport-driver-send-and-receive-operations-to-condis-6-0.md) -###### [Porting CoNDIS Miniport Driver Send Data Handling](porting-condis-miniport-driver-send-data-handling.md) -###### [Porting CoNDIS Miniport Driver Receive Data Handling](porting-condis-miniport-driver-receive-data-handling.md) -##### [Porting Protocol Driver Send and Receive Operations to CoNDIS 6.0](porting-protocol-driver-send-and-receive-operations-to-condis-6-0.md) -###### [Porting CoNDIS Protocol Driver Send Data Handling](porting-condis-protocol-driver-send-data-handling.md) -###### [Porting CoNDIS Protocol Driver Receive Data Handling](porting-condis-protocol-driver-receive-data-handling.md) -#### [Porting OID Request Operations to CoNDIS 6.0](porting-oid-request-operations-to-condis-6-0.md) -##### [Porting OID Requests for CoNDIS 6.0 Miniport Drivers](porting-oid-requests-for-condis-6-0-miniport-drivers.md) -##### [Porting Protocol Driver OID Request Handling to CoNDIS 6.0](porting-protocol-driver-oid-request-handling-to-condis-6-0.md) -##### [Porting MCM OID Request Handling to CoNDIS 6.0](porting-mcm-oid-request-handling-to-condis-6-0.md) -#### [Porting Status Indication Operations to CoNDIS 6.0](porting-status-indication-operations-to-condis-6-0.md) -##### [Porting Miniport Driver Status Indications to CoNDIS 6.0](porting-miniport-driver-status-indications-to-condis-6-0.md) -##### [Porting Protocol Driver Status Indication Handling to CoNDIS 6.0](porting-protocol-driver-status-indication-handling-to-condis-6-0.md) -### [Porting Task Offload Services to NDIS 6.0](porting-task-offload-services-to-ndis-6-0.md) -#### [NDIS 6.0 Task Offload Porting Issues](ndis-6-0-task-offload-porting-issues.md) -##### [NDIS 6.0 Support for Task Offload](ndis-6-0-support-for-task-offload.md) -##### [NDIS 6.0 Task Offload Backward Compatibility](ndis-6-0-task-offload-backward-compatibility.md) -##### [Summary of NDIS 6.0 Task Offload Porting Issues for Protocol Drivers](summary-of-ndis-6-0-task-offload-porting-issues-for-protocol-drivers.md) -##### [Summary of NDIS 6.0 Task Offload Porting Issues for Miniport Drivers](summary-of-ndis-6-0-task-offload-porting-issues-for-miniport-drivers.md) -##### [Summary of Task Offload Support in NDIS 6.0 Filter Drivers](summary-of-task-offload-support-in-ndis-6-0-filter-drivers.md) -#### [Offloading Checksum Tasks in NDIS 6.0](offloading-checksum-tasks-in-ndis-6-0.md) -#### [Offloading the Segmentation of Large TCP Packets in NDIS 6.0](offloading-the-segmentation-of-large-tcp-packets-in-ndis-6-0.md) -#### [Offloading Internet Protocol Security Tasks in NDIS 6.0](offloading-internet-protocol-security-tasks-in-ndis-6-0.md) -#### [Offloading TCP/IP Connections in NDIS 6.0](offloading-tcp-ip-connections-in-ndis-6-0.md) +## [Porting NDIS Drivers to Newer NDIS Versions](porting-ndis-drivers-to-newer-ndis-versions.md) +### [Porting NDIS 6.x drivers to NDIS 6.70](porting-ndis-6-x-drivers-to-ndis-6-70.md) +### [Porting NDIS 6.x drivers to NDIS 6.60](porting-ndis-6-x-drivers-to-ndis-6-60.md) +### [Porting NDIS 6.x drivers to NDIS 6.50](porting-ndis-6-x-drivers-to-ndis-6-50.md) +### [Porting NDIS 6.x Drivers to NDIS 6.40](porting-ndis-6-x-drivers-to-ndis-6-40.md) +### [Porting NDIS 6.x Drivers to NDIS 6.30](porting-ndis-6-x-drivers-to-ndis-6-30.md) +#### [NDIS 6.30 Backward Compatibility](ndis-6-30-backward-compatibility.md) +#### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.30](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-30.md) +#### [Summary of Changes Required to Port a Protocol or Filter Driver to NDIS 6.30](summary-of-changes-required-to-port-a-protocol-or-filter-driver-to-ndis-6-30.md) +#### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.30](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-30.md) +### [Porting NDIS 6.x Drivers to NDIS 6.20](porting-ndis-6-x-drivers-to-ndis-6-20.md) +#### [NDIS 6.20 Backward Compatibility](ndis-6-20-backward-compatibility.md) +#### [NDIS 6.20 Updates to NDIS 6.1 Features](ndis-6-20-updates-to-ndis-6-1-features.md) +#### [Obsolete Interfaces in NDIS 6.20](obsolete-interfaces-in-ndis-6-20.md) +#### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.20](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-20.md) +#### [Summary of Changes Required to Port a Protocol Driver to NDIS 6.20](summary-of-changes-required-to-port-a-protocol-driver-to-ndis-6-20.md) +#### [Summary of Changes Required to Port a Filter Driver to NDIS 6.20](summary-of-changes-required-to-port-a-filter-driver-to-ndis-6-20.md) +#### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.20](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-2.md) +### [Porting NDIS 5.x Drivers to NDIS 6.0](porting-ndis-5-x-drivers-to-ndis-6-0.md) +#### [NDIS 6.0 Backward Compatibility](ndis-6-0-backward-compatibility.md) +#### [Porting a Miniport Driver to NDIS 6.0](porting-a-miniport-driver-to-ndis-6-0.md) +##### [Summary of Changes Required to Port a Miniport Driver to NDIS 6.0](summary-of-changes-required-to-port-a-miniport-driver-to-ndis-6-0.md) +##### [Porting Miniport Driver Initialization to NDIS 6.0](porting-miniport-driver-initialization-to-ndis-6-0.md) +###### [Updating the DriverEntry Routine for an NDIS 6.0 Miniport Driver](updating-the-driverentry-routine-for-an-ndis-6-0-miniport-driver.md) +###### [Updating the NDIS 6.0 Miniport Driver Characteristics Structure](updating-the-ndis-6-0-miniport-driver-characteristics-structure.md) +###### [Registering Optional NDIS 6.0 Entry Points for Miniport Drivers](registering-optional-ndis-6-0-entry-points-for-miniport-drivers.md) +##### [Porting Miniport Driver Unload Operations to NDIS 6.0](porting-miniport-driver-unload-operations-to-ndis-6-0.md) +##### [Porting Miniport Adapter Initialization to NDIS 6.0](porting-miniport-adapter-initialization-to-ndis-6-0.md) +###### [Updating the MiniportInitialize Function for NDIS 6.0](updating-the-miniportinitialize-function-for-ndis-6-0.md) +###### [Setting the NDIS 6.0 Miniport Adapter Attributes](setting-the-ndis-6-0-miniport-adapter-attributes.md) +###### [Reading the Registry in an NDIS 6.0 Miniport Driver](reading-the-registry-in-an-ndis-6-0-miniport-driver.md) +###### [Allocating Memory in an NDIS 6.0 Miniport Driver](allocating-memory-in-an-ndis-6-0-miniport-driver.md) +###### [Updating Bus-Specific Configuration Space Access for NDIS 6.0](updating-bus-specific-configuration-space-access-for-ndis-6-0.md) +##### [Porting Miniport Adapter Halt Operations to NDIS 6.0](porting-miniport-adapter-halt-operations-to-ndis-6-0.md) +##### [Supporting NDIS 6.0 Miniport Adapter Pause and Restart Operations](supporting-ndis-6-0-miniport-adapter-pause-and-restart-operations.md) +##### [Porting Miniport Driver Send and Receive Operations to NDIS 6.0](porting-miniport-driver-send-and-receive-operations-to-ndis-6-0.md) +###### [Allocating Network Data Pools in an NDIS 6.0 Miniport Driver](allocating-network-data-pools-in-an-ndis-6-0-miniport-driver.md) +###### [Porting NDIS Miniport Driver Send Data Handling](porting-ndis-miniport-driver-send-data-handling.md) +###### [Porting NDIS Miniport Driver Receive Data Handling](porting-ndis-miniport-driver-receive-data-handling.md) +##### [Porting Miniport Driver DMA Operations to NDIS 6.0](porting-miniport-driver-dma-operations-to-ndis-6-0.md) +##### [Porting Miniport Driver Interrupt Operations to NDIS 6.0](porting-miniport-driver-interrupt-operations-to-ndis-6-0.md) +###### [Porting Interrupt Registration to NDIS 6.0](porting-interrupt-registration-to-ndis-6-0.md) +###### [Porting Interrupt Handling to NDIS 6.0](porting-interrupt-handling-to-ndis-6-0.md) +###### [Supporting Message Signaled Interrupts in NDIS 6.0](supporting-message-signaled-interrupts-in-ndis-6-0.md) +##### [Porting Miniport Driver OID Request Handling to NDIS 6.0](porting-miniport-driver-oid-request-handling-to-ndis-6-0.md) +##### [Porting Miniport Driver Status Indications to NDIS 6.0](porting-miniport-driver-status-indications-to-ndis-6-0.md) +##### [Porting Miniport Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-miniport-driver-plug-and-play-event-notification-handling-to-n.md) +##### [Porting Miniport Adapter Check for Hang and Reset Operations to NDIS 6.0](porting-miniport-adapter-check-for-hang-and-reset-operations-to-ndis-6.md) +##### [Porting Miniport Adapter Shutdown Operations to NDIS 6.0](porting-miniport-adapter-shutdown-operations-to-ndis-6-0.md) +#### [Porting a Protocol Driver to NDIS 6.0](porting-a-protocol-driver-to-ndis-6-0.md) +##### [Summary of Changes Required to Port a Protocol Driver to NDIS 6.0](summary-of-changes-required-to-port-a-protocol-driver-to-ndis-6-0.md) +##### [Porting Protocol Driver Initialization to NDIS 6.0](porting-protocol-driver-initialization-to-ndis-6-0.md) +###### [Updating the DriverEntry Routine for an NDIS 6.0 Protocol Driver](updating-the-driverentry-routine-for-an-ndis-6-0-protocol-driver.md) +###### [Updating the NDIS 6.0 Protocol Driver characteristics Structure](updating-the-ndis-6-0-protocol-driver-characteristics-structure.md) +###### [Registering Optional NDIS 6.0 Protocol Driver Entry Points](registering-optional-ndis-6-0-protocol-driver-entry-points.md) +##### [Porting Protocol Driver Unload Operations to NDIS 6.0](porting-protocol-driver-unload-operations-to-ndis-6-0.md) +##### [Porting Protocol Binding Operations to NDIS 6.0](porting-protocol-binding-operations-to-ndis-6-0.md) +###### [Updating the ProtocolBindAdapter Function for an NDIS 6.0 Protocol Driver](updating-the-protocolbindadapter-function-for-an-ndis-6-0-protocol-dri.md) +###### [Opening an Adapter in an NDIS 6.0 Protocol Driver](opening-an-adapter-in-an-ndis-6-0-protocol-driver.md) +###### [Reading the Registry in an NDIS 6.0 Protocol Driver](reading-the-registry-in-an-ndis-6-0-protocol-driver.md) +###### [Allocating Memory in an NDIS 6.0 Protocol Driver](allocating-memory-in-an-ndis-6-0-protocol-driver.md) +##### [Porting Protocol Unbinding Operations to NDIS 6.0](porting-protocol-unbinding-operations-to-ndis-6-0.md) +##### [Supporting NDIS 6.0 Protocol Binding Pause and Restart Operations](supporting-ndis-6-0-protocol-binding-pause-and-restart-operations.md) +##### [Porting Protocol Driver Send and Receive Operations to NDIS 6.0](porting-protocol-driver-send-and-receive-operations-to-ndis-6-0.md) +###### [Allocating Network Data Pools in an NDIS 6.0 Protocol Driver](allocating-network-data-pools-in-an-ndis-6-0-protocol-driver.md) +###### [Porting NDIS Protocol Driver Send Data Handling](porting-ndis-protocol-driver-send-data-handling.md) +###### [Porting NDIS Protocol Driver Receive Data Handling](porting-ndis-protocol-driver-receive-data-handling.md) +##### [Porting Protocol Driver OID Request Handling to NDIS 6.0](porting-protocol-driver-oid-request-handling-to-ndis-6-0.md) +##### [Porting Protocol Driver Status Indication Handling to NDIS 6.0](porting-protocol-driver-status-indication-handling-to-ndis-6-0.md) +##### [Porting Protocol Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-protocol-driver-plug-and-play-event-notification-handling-to-n.md) +#### [Porting an Intermediate Driver to NDIS 6.0](porting-an-intermediate-driver-to-ndis-6-0.md) +##### [Summary of Changes Required to Port an Intermediate Driver to NDIS 6.0](summary-of-changes-required-to-port-an-intermediate-driver-to-ndis-6-0.md) +##### [Porting Intermediate Driver Initialization to NDIS 6.0](porting-intermediate-driver-initialization-to-ndis-6-0.md) +##### [Porting Intermediate Driver Unload Operations to NDIS 6.0](porting-intermediate-driver-unload-operations-to-ndis-6-0.md) +##### [Porting Virtual Miniport Initialization to NDIS 6.0](porting-virtual-miniport-initialization-to-ndis-6-0.md) +##### [Porting Virtual Miniport Halt Operations to NDIS 6.0](porting-virtual-miniport-halt-operations-to-ndis-6-0.md) +##### [Supporting Pause and Restart Operations in an NDIS 6.0 Intermediate Driver](supporting-pause-and-restart-operations-in-an-ndis-6-0-intermediate-dr.md) +##### [Porting Intermediate Driver Send and Receive Operations to NDIS 6.0](porting-intermediate-driver-send-and-receive-operations-to-ndis-6-0.md) +##### [Porting Intermediate Driver OID Request Handling to NDIS 6.0](porting-intermediate-driver-oid-request-handling-to-ndis-6-0.md) +##### [Porting Intermediate Driver Status Indication Handling to NDIS 6.0](porting-intermediate-driver-status-indication-handling-to-ndis-6-0.md) +##### [Porting Intermediate Driver Plug and Play Event Notification Handling to NDIS 6.0](porting-intermediate-driver-plug-and-play-event-notification-handling-.md) +#### [Porting a CoNDIS 5.x Driver to CoNDIS 6.0](porting-a-condis-5-x-driver-to-condis-6-0.md) +##### [Summary of Changes Required to Port a CoNDIS Driver to CoNDIS 6.0](summary-of-changes-required-to-port-a-condis-driver-to-condis-6-0.md) +##### [Porting CoNDIS Driver Registration to CoNDIS 6.0](porting-condis-driver-registration-to-condis-6-0.md) +###### [Porting CoNDIS Miniport Driver Registration](porting-condis-miniport-driver-registration.md) +###### [Porting CoNDIS Client Registration](porting-condis-client-registration.md) +###### [Porting CoNDIS Call Manager Registration](porting-condis-call-manager-registration.md) +###### [Porting CoNDIS MCM Registration](porting-condis-mcm-registration.md) +##### [Porting Address Family Close Operations to CoNDIS 6.0](porting-address-family-close-operations-to-condis-6-0.md) +##### [Porting Send and Receive Operations to CoNDIS 6.0](porting-send-and-receive-operations-to-condis-6-0.md) +###### [Porting Miniport Driver Send and Receive Operations to CoNDIS 6.0](porting-miniport-driver-send-and-receive-operations-to-condis-6-0.md) +####### [Porting CoNDIS Miniport Driver Send Data Handling](porting-condis-miniport-driver-send-data-handling.md) +####### [Porting CoNDIS Miniport Driver Receive Data Handling](porting-condis-miniport-driver-receive-data-handling.md) +###### [Porting Protocol Driver Send and Receive Operations to CoNDIS 6.0](porting-protocol-driver-send-and-receive-operations-to-condis-6-0.md) +####### [Porting CoNDIS Protocol Driver Send Data Handling](porting-condis-protocol-driver-send-data-handling.md) +####### [Porting CoNDIS Protocol Driver Receive Data Handling](porting-condis-protocol-driver-receive-data-handling.md) +##### [Porting OID Request Operations to CoNDIS 6.0](porting-oid-request-operations-to-condis-6-0.md) +###### [Porting OID Requests for CoNDIS 6.0 Miniport Drivers](porting-oid-requests-for-condis-6-0-miniport-drivers.md) +###### [Porting Protocol Driver OID Request Handling to CoNDIS 6.0](porting-protocol-driver-oid-request-handling-to-condis-6-0.md) +###### [Porting MCM OID Request Handling to CoNDIS 6.0](porting-mcm-oid-request-handling-to-condis-6-0.md) +##### [Porting Status Indication Operations to CoNDIS 6.0](porting-status-indication-operations-to-condis-6-0.md) +###### [Porting Miniport Driver Status Indications to CoNDIS 6.0](porting-miniport-driver-status-indications-to-condis-6-0.md) +###### [Porting Protocol Driver Status Indication Handling to CoNDIS 6.0](porting-protocol-driver-status-indication-handling-to-condis-6-0.md) +#### [Porting Task Offload Services to NDIS 6.0](porting-task-offload-services-to-ndis-6-0.md) +##### [NDIS 6.0 Task Offload Porting Issues](ndis-6-0-task-offload-porting-issues.md) +###### [NDIS 6.0 Support for Task Offload](ndis-6-0-support-for-task-offload.md) +###### [NDIS 6.0 Task Offload Backward Compatibility](ndis-6-0-task-offload-backward-compatibility.md) +###### [Summary of NDIS 6.0 Task Offload Porting Issues for Protocol Drivers](summary-of-ndis-6-0-task-offload-porting-issues-for-protocol-drivers.md) +###### [Summary of NDIS 6.0 Task Offload Porting Issues for Miniport Drivers](summary-of-ndis-6-0-task-offload-porting-issues-for-miniport-drivers.md) +###### [Summary of Task Offload Support in NDIS 6.0 Filter Drivers](summary-of-task-offload-support-in-ndis-6-0-filter-drivers.md) +##### [Offloading Checksum Tasks in NDIS 6.0](offloading-checksum-tasks-in-ndis-6-0.md) +##### [Offloading the Segmentation of Large TCP Packets in NDIS 6.0](offloading-the-segmentation-of-large-tcp-packets-in-ndis-6-0.md) +##### [Offloading Internet Protocol Security Tasks in NDIS 6.0](offloading-internet-protocol-security-tasks-in-ndis-6-0.md) +##### [Offloading TCP/IP Connections in NDIS 6.0](offloading-tcp-ip-connections-in-ndis-6-0.md) # [NDIS Core Functionality](ndis-core-functionality2.md) ## [NDIS Miniport Drivers](ndis-miniport-drivers.md) ### [Roadmap for Developing NDIS Miniport Drivers](roadmap-for-developing-ndis-miniport-drivers.md) @@ -266,6 +315,14 @@ ##### [Handling Interrupts](handling-interrupts.md) ##### [Synchronizing with Interrupts](synchronizing-with-interrupts.md) ##### [Interrupt Moderation](interrupt-moderation.md) +#### [NDIS Interrupt and Synchronization Macros](ndis-interrupt-and-synchronization-macros.md) +##### [NDIS_CURRENT_PROCESSOR_NUMBER](ndis-current-processor-number.md) +##### [NDIS_CURRENT_IRQL](ndis-current-irql.md) +##### [NDIS_RAISE_IRQL_TO_DISPATCH](ndis-raise-irql-to-dispatch.md) +##### [NDIS_LOWER_IRQL](ndis-lower-irql.md) +##### [NDIS_INIT_MUTEX](ndis-init-mutex.md) +##### [NDIS_RELEASE_MUTEX](ndis-release-mutex.md) +##### [NDIS_WAIT_FOR_MUTEX](ndis-wait-for-mutex.md) #### [Miniport Adapter OID Requests](miniport-adapter-oid-requests.md) ##### [Miniport Adapter OID Request Serialization](miniport-adapter-oid-request-serialization.md) ##### [Handling OID Requests In a Miniport Adapter](handling-oid-requests-in-a-miniport-adapter.md) @@ -557,6 +614,13 @@ #### [Handling an Interface Object Query Request](handling-an-interface-object-query-request.md) #### [Handling an Interface Object Set Request](handling-an-interface-object-set-request.md) ### [Mapping of NDIS Network Interfaces to NDIS OIDs](mapping-of-ndis-network-interfaces-to-ndis-oids.md) +### [NDIS MDL Interface](ndis-mdl-interface.md) +#### [NDIS_MDL_LINKAGE](ndis-mdl-linkage.md) +#### [NDIS_MDL_TO_SPAN_PAGES](ndis-mdl-to-span-pages.md) +#### [NdisGetMdlPhysicalArraySize](ndisgetmdlphysicalarraysize.md) +#### [NdisGetNextMdl](ndisgetnextmdl.md) +#### [NdisQueryMdl](ndisquerymdl.md) +#### [NdisQueryMdlOffset](ndisquerymdloffset.md) ## [NDIS Ports](ndis-ports.md) ### [Overview of NDIS Ports](overview-of-ndis-ports.md) #### [Identifying an NDIS Port](identifying-an-ndis-port.md) @@ -630,6 +694,11 @@ #### [Obtaining the Current Parameter Settings of Low Power Protocol Offloads](obtaining-the-current-parameter-settings-of-low-power-protocol-offload.md) #### [Low Power for Wake on LAN](low-power-for-wake-on-lan.md) #### [Low Power on Media Disconnect](low-power-on-media-disconnect.md) +#### [Power Management Status Indications](power-management-status-indications.md) +##### [NDIS_STATUS_PM_CAPABILITIES_CHANGE](ndis-status-pm-capabilities-change.md) +##### [NDIS_STATUS_PM_HARDWARE_CAPABILITIES](ndis-status-pm-hardware-capabilities.md) +##### [NDIS_STATUS_PM_OFFLOAD_REJECTED](ndis-status-pm-offload-rejected.md) +##### [NDIS_STATUS_PM_WOL_PATTERN_REJECTED](ndis-status-pm-wol-pattern-rejected.md) ### [Power Management (NDIS 6.0 and NDIS 6.1)](power-management--ndis-6-0-and-ndis-6-1-.md) #### [Required and Optional OIDs for Power Management](required-and-optional-oids-for-power-management.md) #### [Device Power States for Network Adapters](device-power-states-for-network-adapters.md) @@ -761,6 +830,46 @@ ##### [Setting Up the Test System](setting-up-the-test-system.md) ##### [Running the Upgrade Test and Examining the Results](running-the-upgrade-test-and-examining-the-results.md) ###### [Examining the AnswerFile](examining-the-answerfile.md) +## [NDIS core functionality OIDs](ndis-core-functionality-oids.md) +### [NDIS general statistics OIDs](ndis-general-statistics-oids.md) +### [NDIS network interface OIDs](ndis-network-interface-oids.md) +## [NDIS core functionality status indications](ndis-core-functionality-status-indications.md) +### [NDIS General Status Indications](ndis-general-status-indications.md) +#### [NDIS_STATUS_MEDIA_CONNECT](ndis-status-media-connect.md) +#### [NDIS_STATUS_MEDIA_DISCONNECT](ndis-status-media-disconnect.md) +#### [NDIS_STATUS_RESET_START](ndis-status-reset-start.md) +#### [NDIS_STATUS_RESET_END](ndis-status-reset-end.md) +#### [NDIS_STATUS_MEDIA_BUSY](ndis-status-media-busy.md) +#### [NDIS_STATUS_MEDIA_SPECIFIC_INDICATION](ndis-status-media-specific-indication.md) +#### [NDIS_STATUS_LINK_SPEED_CHANGE](ndis-status-link-speed-change.md) +#### [NDIS_STATUS_LINK_STATE](ndis-status-link-state.md) +#### [NDIS_STATUS_PORT_STATE](ndis-status-port-state.md) +#### [NDIS_STATUS_OPER_STATUS](ndis-status-oper-status.md) +#### [NDIS_STATUS_NETWORK_CHANGE](ndis-status-network-change.md) +#### [NDIS_STATUS_PACKET_FILTER](ndis-status-packet-filter.md) +### [Receive Filter Status Indications](receive-filter-status-indications.md) +#### [NDIS_STATUS_RECEIVE_FILTER_CURRENT_CAPABILITIES](ndis-status-receive-filter-current-capabilities.md) +#### [NDIS_STATUS_RECEIVE_FILTER_HARDWARE_CAPABILITIES](ndis-status-receive-filter-hardware-capabilities.md) +### [NDIS QoS Status Indications](ndis-qos-status-indications.md) +#### [NDIS_STATUS_QOS_OPERATIONAL_PARAMETERS_CHANGE](ndis-status-qos-operational-parameters-change.md) +#### [NDIS_STATUS_QOS_REMOTE_PARAMETERS_CHANGE](ndis-status-qos-remote-parameters-change.md) +### [NDIS TCP/IP Offload Status Indications](ndis-tcp-ip-offload-status-indications.md) +#### [NDIS_STATUS_TASK_OFFLOAD_CURRENT_CONFIG](ndis-status-task-offload-current-config.md) +#### [NDIS_STATUS_TASK_OFFLOAD_HARDWARE_CAPABILITIES](ndis-status-task-offload-hardware-capabilities.md) +#### [NDIS_STATUS_OFFLOAD_ENCASPULATION_CHANGE](ndis-status-offload-encaspulation-change.md) +#### [NDIS_STATUS_TCP_CONNECTION_OFFLOAD_HARDWARE_CAPABILITIES](ndis-status-tcp-connection-offload-hardware-capabilities.md) +### [NDIS Wake Reason Status Indications](ndis-wake-reason-status-indications-ref.md) +#### [NDIS_STATUS_PM_WAKE_REASON](ndis-status-pm-wake-reason.md) +### [NDIS WAN Status Indications](ndis-wan-status-indications.md) +#### [NDIS_STATUS_WAN_LINE_UP](ndis-status-wan-line-up.md) +#### [NDIS_STATUS_WAN_LINE_DOWN](ndis-status-wan-line-down.md) +#### [NDIS_STATUS_WAN_FRAGMENT](ndis-status-wan-fragment.md) +#### [NDIS_STATUS_TAPI_INDICATION](ndis-status-tapi-indication.md) +#### [NDIS_STATUS_RING_STATUS](ndis-status-ring-status.md) +#### [NDIS_STATUS_WW_INDICATION](ndis-status-ww-indication.md) +#### [NDIS_STATUS_WAN_CO_FRAGMENT](ndis-status-wan-co-fragment.md) +#### [NDIS_STATUS_WAN_CO_LINKPARAMS](ndis-status-wan-co-linkparams.md) +#### [NDIS_STATUS_WAN_CO_MTULINKPARAMS](ndis-status-wan-co-mtulinkparams.md) # [Scalable Networking](scalable-networking2.md) ## [Header-Data Split](header-data-split.md) ### [Header-Data Split Overview](header-data-split-overview.md) @@ -768,6 +877,11 @@ #### [Where to Split Header and Data](where-to-split-header-and-data.md) #### [Cases Where Header-Data Split Is Not Used](cases-where-header-data-split-is-not-used.md) #### [Minimum Requirements for Supporting Header-Data Split](minimum-requirements-for-supporting-header-data-split.md) +#### [Header-Data Split Status Indications](header-data-split-status-indications.md) +##### [NDIS_STATUS_HD_SPLIT_CURRENT_CONFIG](ndis-status-hd-split-current-config.md) +#### [Header-Data Split Macros](header-data-split-macros.md) +##### [NET_BUFFER_LIST_NBL_FLAGS](net-buffer-list-nbl-flags.md) +##### [NET_BUFFER_DATA_PHYSICAL_ADDRESS](net-buffer-data-physical-address.md) ### [Initializing a Header-Data Split Provider](initializing-a-header-data-split-provider.md) ### [Splitting Ethernet Frames](splitting-ethernet-frames.md) #### [Splitting IPv4 Frames](splitting-ipv4-frames.md) @@ -783,6 +897,16 @@ #### [Allocating the Header Buffer](allocating-the-header-buffer.md) #### [Allocating Backfill for the Data Buffer](allocating-backfill-for-the-data-buffer.md) #### [Setting NET_BUFFER_LIST Information](setting-net-buffer-list-information.md) +### [Receive Side Scaling Macros](receive-scaling-macros.md) +#### [NET_BUFFER_LIST_SET_HASH_TYPE ](net-buffer-list-set-hash-type.md) +#### [NET_BUFFER_LIST_SET_HASH_FUNCTION](net-buffer-list-set-hash-function.md) +#### [NET_BUFFER_LIST_SET_HASH_VALUE](net-buffer-list-set-hash-value.md) +#### [NET_BUFFER_LIST_GET_HASH_TYPE ](net-buffer-list-get-hash-type.md) +#### [NET_BUFFER_LIST_GET_HASH_FUNCTION](net-buffer-list-get-hash-function.md) +#### [NET_BUFFER_LIST_GET_HASH_VALUE](net-buffer-list-get-hash-value.md) +#### [NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC](ndis-rss-hash-info-from-type-and-func.md) +#### [NDIS_RSS_HASH_TYPE_FROM_HASH_INFO](ndis-rss-hash-type-from-hash-info.md) +#### [NDIS_RSS_HASH_FUNC_FROM_HASH_INFO](ndis-rss-hash-func-from-hash-info.md) ### [Header-Data Split Administration and Configuration](header-data-split-administration-and-configuration.md) #### [Setting the Current Header-Data Split Configuration](setting-the-current-header-data-split-configuration.md) #### [Getting the Current Header-Data Split Configuration](getting-the-current-header-data-split-configuration.md) @@ -1043,6 +1167,8 @@ #### [Determining the Current Connection Offload Settings](determining-the-current-connection-offload-settings.md) #### [Using Registry Values to Enable and Disable Connection Offloading](using-registry-values-to-enable-and-disable-connection-offloading.md) #### [Offloading TCP/IP Connections](offloading-tcp-ip-connections.md) +### [PacketDirect Provider Interface (PDPI) Status Indications](packetdirect-provider-interface--pdpi--status-indications.md) +#### [NDIS_STATUS_PD_CURRENT_CONFIG](ndis-status-pd-current-config.md) # [Virtualized Networking](virtualized-networking.md) ## [Virtualized Networking Concepts and Terms](virtualized-networking-concepts-and-terms.md) ## [Overview of Virtualized Networking](overview-of-virtualized-networking.md) @@ -1064,6 +1190,9 @@ ##### [SR-IOV VF Data Path](sr-iov-vf-data-path.md) ##### [SR-IOV Synthetic Data Path](sr-iov-synthetic-data-path.md) ##### [SR-IOV VF Failover and Live Migration Support](sr-iov-vf-failover-and-live-migration-support.md) +#### [SR-IOV Macros](sr-iov-macros.md) +##### [NDIS_MAKE_RID](ndis-make-rid.md) +##### [NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID](net-buffer-list-receive-filter-vport-id.md) ### [Writing SR-IOV PF Miniport Drivers](writing-sr-iov-pf-miniport-drivers.md) #### [Initializing a PF Miniport Driver](initializing-a-pf-miniport-driver.md) ##### [Determining SR-IOV Capabilities](determining-sr-iov-capabilities.md) @@ -1193,6 +1322,19 @@ #### [Hyper-V Extensible Switch Control Path](hyper-v-extensible-switch-control-path.md) ##### [Hyper-V Extensible Switch Control Path for OID Requests](hyper-v-extensible-switch-control-path-for-oid-requests.md) ##### [Hyper-V Extensible Switch Control Path for NDIS Status Indications](hyper-v-extensible-switch-control-path-for-ndis-status-indications.md) +#### [Hyper-V Extensible Switch Macros](hyper-v-extensible-switch-macros.md) +##### [NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX](ndis-switch-port-destination-at-array-index.md) +##### [NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER](ndis-switch-port-property-custom-get-buffer.md) +##### [NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT](ndis-switch-port-property-enum-info-get-next.md) +##### [NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY](ndis-switch-port-property-enum-info-get-property.md) +##### [NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO](ndis-switch-port-property-enum-parameters-get-first-info.md) +##### [NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY](ndis-switch-port-property-parameters-get-property.md) +##### [NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER](ndis-switch-property-custom-get-buffer.md) +##### [NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_NEXT](ndis-switch-property-enum-info-get-next.md) +##### [NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY](ndis-switch-property-enum-info-get-property.md) +##### [NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO](ndis-switch-property-enum-parameters-get-first-info.md) +##### [NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY](ndis-switch-property-parameters-get-property.md) +##### [NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL](net-buffer-list-switch-forwarding-detail.md) #### [Hyper-V Extensible Switch Policies](hyper-v-extensible-switch-policies.md) ##### [Overview of Hyper-V Extensible Switch Policies](overview-of-hyper-v-extensible-switch-policies.md) ##### [Port Policies](port-policies.md) @@ -1254,6 +1396,14 @@ ##### [Enabling Hyper-V Extensible Switch Extensions](enabling-hyper-v-extensibility-switch-extensions.md) ##### [Disabling Hyper-V Extensible Switch Extensions](disabling-hyper-v-extensibility-switch-extensions.md) ##### [Reordering Hyper-V Extensible Switch Extensions](reordering-hyper-v-extensibility-switch-extensions.md) +### [Hyper-V Extensible Switch OIDs](hyper-v-extensible-switch-oids.md) +### [Hyper-V Extensible Switch Status Indications](hyper-v-extensible-switch-status-indications.md) +#### [NDIS_STATUS_SWITCH_NIC_STATUS](ndis-status-switch-nic-status.md) +#### [NDIS_STATUS_SWITCH_PORT_REMOVE_VF](ndis-status-switch-port-remove-vf.md) +### [VMQ Status Indications](virtual-machine-queue-status-indications.md) +#### [NDIS_STATUS_RECEIVE_QUEUE_STATE](ndis-status-receive-queue-state.md) +### [VMQ Macros](vmq-macros.md) +#### [NET_BUFFER_LIST_RECEIVE_QUEUE_ID](net-buffer-list-receive-queue-id.md) # [Wireless Networking](wireless-networking2.md) ## [WLAN Universal Windows driver model](wifi-universal-driver-model.md) ## [Cellular architecture and implementation](cellular-architecture-and-driver-model.md) @@ -1312,6 +1462,26 @@ ### [MB Network Blacklist Operations](mb-network-blacklist-operations.md) ### [MB LTE Attach Operations](mb-lte-attach-operations.md) ### [MB SAR Platform Support](mb-sar-platform-support.md) +### [MB NDIS Status Notifications](mb-ndis-status-notifications.md) +#### [NDIS_STATUS_WWAN_AUTH_RESPONSE](ndis-status-wwan-auth-response.md) +#### [NDIS_STATUS_WWAN_DEVICE_CAPS](ndis-status-wwan-device-caps.md) +#### [NDIS_STATUS_WWAN_DEVICE_CAPS_EX](ndis-status-wwan-device-caps-ex.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_EVENT](ndis-status-wwan-device-service-event.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_RESPONSE](ndis-status-wwan-device-service-response.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION](ndis-status-wwan-device-service-session.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_READ](ndis-status-wwan-device-service-session-read.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE](ndis-status-wwan-device-service-session-write-complete.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_SUBSCRIPTION](ndis-status-wwan-device-service-subscription.md) +#### [NDIS_STATUS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS](ndis-status-wwan-device-service-supported-commands.md) +#### [NDIS_STATUS_WWAN_DEVICE_SLOT_MAPPINGS](ndis-status-wwan-device-slot-mappings.md) +#### [NDIS_STATUS_WWAN_IP_ADDRESS_STATE](ndis-status-wwan-ip-address-state.md) +#### [NDIS_STATUS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS](ndis-status-wwan-preferred-multicarrier-providers.md) +#### [NDIS_STATUS_WWAN_PRESHUTDOWN_STATE](ndis-status-wwan-preshutdown-state.md) +#### [NDIS_STATUS_WWAN_SET_HOME_PROVIDER_COMPLETE](ndis-status-wwan-set-home-provider-complete.md) +#### [NDIS_STATUS_WWAN_SLOT_INFO_STATUS](ndis-status-wwan-slot-info-status.md) +#### [NDIS_STATUS_WWAN_SUPPORTED_DEVICE_SERVICES](ndis-status-wwan-supported-device-services.md) +#### [NDIS_STATUS_WWAN_SYS_CAPS](ndis-status-wwan-sys-caps.md) +#### [NDIS_STATUS_WWAN_USSD](ndis-status-wwan-ussd.md) ### [Supplemental MB Documentation](supplemental-mb-documentation.md) #### [HOST Shutdown Device Service](host-shutdown-device-service.md) #### [IHV Guidance for Implementing Multimode and Multicarrier Capable MB Devices](ihv-guidance-for-implementing-multimode-and-multicarrier-capable-mb-devices.md) @@ -1441,8 +1611,21 @@ ##### [General Status Indications](general-status-indications.md) ##### [Other Native 802.11 indications](native-802-11-status-indications2.md) ###### [General Native 802.11 Indications](general-native-802-11-indications.md) +###### [Extensible Access Point Indications](extensible-access-point-indications.md) ###### [Extensible Station Indications](extensible-station-indications.md) ###### [IHV-Specific Indications](ihv-specific-indications.md) +#### [Native 802.11 OIDs](native-802-11-oids.md) +##### [Native 802.11 OID terminology](native-802-11-oid-terminology.md) +##### [Native 802.11 Extensible AP OIDs](native-802-11-extensible-ap-oids.md) +###### [Native 802.11 Extensible AP MIB objects](native-802-11-extensible-ap-mib-objects.md) +##### [Native 802.11 Extensible Station OIDs](native-802-11-extensible-station-oids.md) +###### [Native 802.11 Extensible Station MIB objects](native-802-11-extensible-station-mib-objects.md) +##### [Native 802.11 Network Monitor OIDs](native-802-11-network-monitor-oids.md) +##### [Native 802.11 Operational OIDs](native-802-11-operational-oids.md) +###### [Native 802.11 Operational MIB objects](native-802-11-operational-mib-objects.md) +##### [Native 802.11 MIB OIDs](native-802-11-mib-oids.md) +###### [Native 802.11 IEEE MIB objects](native-802-11-ieee-mib-objects.md) +##### [Native 802.11 Virtual WiFi OIDs](native-802-11-virtual-wifi-oids.md) #### [Native 802.11 Statistics](native-802-11-statistics.md) ##### [Extensible Station MAC Statistics](extensible-station-mac-statistics.md) ##### [Extensible Station PHY Statistics](extensible-station-phy-statistics.md) @@ -1472,11 +1655,30 @@ ##### [INF File Settings for Virtual WiFi](inf-file-settings-for-virtual-wifi.md) ###### [The Lower Binding Interface for Virtual WiFi](the-lower-binding-interface-for-virtual-wifi.md) ###### [Specifying Virtual WiFi Bus Dependencies](specifying-virtual-wifi-bus-dependencies.md) +##### [Native 802.11 WFD Status Indications](native-802-11-wfd-status-indications.md) +###### [NDIS_STATUS_DOT11_WFD_DISCOVER_COMPLETE](ndis-status-dot11-wfd-discover-complete.md) +###### [NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_CONFIRMATION_SEND_COMPLETE](ndis-status-dot11-wfd-go-negotiation-confirmation-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_REQUEST_SEND_COMPLETE](ndis-status-dot11-wfd-go-negotiation-request-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_RESPONSE_SEND_COMPLETE](ndis-status-dot11-wfd-go-negotiation-response-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_GROUP_OPERATING_CHANNEL](-ndis-status-dot11-wfd-group-operating-channel.md) +###### [NDIS_STATUS_DOT11_WFD_INVITATION_REQUEST_SEND_COMPLETE](ndis-status-dot11-wfd-invitation-request-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_INVITATION_RESPONSE_SEND_COMPLETE](ndis-status-dot11-wfd-invitation-response-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_REQUEST_SEND_COMPLETE](ndis-status-dot11-wfd-provision-discovery-request-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_RESPONSE_SEND_COMPLETE](ndis-status-dot11-wfd-provision-discovery-response-send-complete.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_CONFIRMATION](ndis-status-dot11-wfd-received-go-negotiation-confirmation.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_REQUEST](ndis-status-dot11-wfd-received-go-negotiation-request.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_RESPONSE](ndis-status-dot11-wfd-received-go-negotiation-response.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_REQUEST](ndis-status-dot11-wfd-received-invitation-request.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_RESPONSE](ndis-status-dot11-wfd-received-invitation-response.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_REQUEST](ndis-status-dot11-wfd-received-provision-discovery-request.md) +###### [NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_RESPONSE](ndis-status-dot11-wfd-received-provision-discovery-response.md) ### [Native 802.11 IHV Extensions](native-802-11-ihv-extensions.md) #### [Overview of IHV Extensibility](overview-of-ihv-extensibility.md) #### [Installing Native 802.11 IHV Extensions](installing-native-802-11-ihv-extensions.md) #### [Native 802.11 IHV Extensions DLL](native-802-11-ihv-extensions-dll4.md) ##### [Native 802.11 IHV Extensions DLL Overview](native-802-11-ihv-extensions-dll-overview.md) +##### [Native 802.11 IHV Extensibility Functions](native-802-11-ihv-extensibility-functions.md) +##### [Native 802.11 IHV Handler Functions](native-802-11-ihv-handler-functions.md) ##### [Native 802.11 IHV Extensions DLL Implementation Guidelines](native-802-11-ihv-extensions-dll-implementation-guidelines.md) ##### [DLL Start/Stop Operations](dll-start-stop-operations.md) ###### [DLL Start Operations](dll-start-operations.md) @@ -1573,6 +1775,300 @@ #### [WDI TLV generator/parser XML semantics and syntax](wdi-tlv-generator-parser-xml-semantics.md) #### [WDI TLV versioning](wdi-tlv-versioning.md) #### [WDI TLV dumpers](wdi-tlv-dumpers.md) +### [WDI TLVs](wdi-miniport-driver-tlvs.md) +#### [WDI_TLV_ACCESS_NETWORK_TYPE](wdi-tlv-access-network-type.md) +#### [WDI_TLV_ACTION_FRAME_BODY](wdi-tlv-action-frame-body.md) +#### [WDI_TLV_ACTION_FRAME_DEVICE_CONTEXT](wdi-tlv-action-frame-device-context.md) +#### [WDI_TLV_ADAPTER_NLO_SCAN_MODE](wdi-tlv-adapter-nlo-scan-mode.md) +#### [WDI_TLV_ADAPTER_RESUME_REQUIRED](wdi-tlv-adapter-resume-required.md) +#### [WDI_TLV_ADDITIONAL_BEACON_IES](wdi-tlv-additional-beacon-ies.md) +#### [WDI_TLV_ADDITIONAL_IES](wdi-tlv-additional-ies.md) +#### [WDI_TLV_ADDITIONAL_PROBE_REQUEST_DEFAULT_IES](wdi-tlv-additional-probe-request-default-ies.md) +#### [WDI_TLV_ADDITIONAL_PROBE_RESPONSE_IES](wdi-tlv-additional-probe-response-ies.md) +#### [WDI_TLV_ALLOWED_BSSIDS_LIST](wdi-tlv-allowed-bssids-list.md) +#### [WDI_TLV_ANQP_ELEMENTS](wdi-tlv-anqp-elements.md) +#### [WDI_TLV_ANQP_QUERY_PARAMETERS](wdi-tlv-anqp-query-parameters.md) +#### [WDI_TLV_ANQP_QUERY_STATUS](wdi-tlv-anqp-query-status.md) +#### [WDI_TLV_AP_ATTRIBUTES](wdi-tlv-ap-attributes.md) +#### [WDI_TLV_AP_BAND_CHANNEL](wdi-tlv-ap-band-channel.md) +#### [WDI_TLV_AP_CAPABILITIES](wdi-tlv-ap-capabilities.md) +#### [WDI_TLV_ASSOCIATION_PARAMETERS_REQUESTED_TYPE](wdi-tlv-association-parameters-requested-type.md) +#### [WDI_TLV_ASSOCIATION_REQUEST_DEVICE_CONTEXT](wdi-tlv-association-request-device-context.md) +#### [WDI_TLV_ASSOCIATION_REQUEST_FRAME](wdi-tlv-association-request-frame.md) +#### [WDI_TLV_ASSOCIATION_REQUEST_IES](wdi-tlv-association-request-ies.md) +#### [WDI_TLV_ASSOCIATION_RESPONSE_FRAME](wdi-tlv-association-response-frame.md) +#### [WDI_TLV_ASSOCIATION_RESPONSE_IES](wdi-tlv-association-response-ies.md) +#### [WDI_TLV_ASSOCIATION_RESPONSE_PARAMETERS](wdi-tlv-association-response-parameters.md) +#### [WDI_TLV_ASSOCIATION_RESPONSE_RESULT_PARAMETERS](wdi-tlv-association-response-result-parameters.md) +#### [WDI_TLV_ASSOCIATION_RESULT](wdi-tlv-association-result.md) +#### [WDI_TLV_ASSOCIATION_RESULT_PARAMETERS](wdi-tlv-association-result-parameters.md) +#### [WDI_TLV_AUTH_ALGO_LIST](wdi-tlv-auth-algo-list.md) +#### [WDI_TLV_AUTHENTICATION_RESPONSE_FRAME](wdi-tlv-authentication-response-frame.md) +#### [WDI_TLV_BAND_CAPABILITIES](wdi-tlv-band-capabilities.md) +#### [WDI_TLV_BAND_CHANNEL](wdi-tlv-band-channel.md) +#### [WDI_TLV_BAND_ID_LIST](wdi-tlv-band-id-list.md) +#### [WDI_TLV_BAND_INFO](wdi-tlv-band-info.md) +#### [WDI_TLV_BANDID](wdi-tlv-bandid.md) +#### [WDI_TLV_BEACON_FRAME](wdi-tlv-beacon-frame.md) +#### [WDI_TLV_BEACON_IES](wdi-tlv-beacon-ies.md) +#### [WDI_TLV_BEACON_PROBE_RESPONSE](wdi-tlv-beacon-probe-response.md) +#### [WDI_TLV_BITMAP_PATTERN](wdi-tlv-bitmap-pattern.md) +#### [WDI_TLV_BITMAP_PATTERN_AND_MASK](wdi-tlv-bitmap-pattern-and-mask.md) +#### [WDI_TLV_BITMAP_PATTERN_MASK](wdi-tlv-bitmap-pattern-mask.md) +#### [WDI_TLV_BSS_ENTRY](wdi-tlv-bss-entry.md) +#### [WDI_TLV_BSS_ENTRY_AGE_INFO](wdi-tlv-bss-entry-age-info.md) +#### [WDI_TLV_BSS_ENTRY_CHANNEL_INFO](wdi-tlv-bss-entry-channel-info.md) +#### [WDI_TLV_BSS_ENTRY_DEVICE_CONTEXT](wdi-tlv-bss-entry-device-context.md) +#### [WDI_TLV_BSS_ENTRY_PHY_INFO](wdi-tlv-bss-entry-phy-info.md) +#### [WDI_TLV_BSS_ENTRY_SIGNAL_INFO](wdi-tlv-bss-entry-signal-info.md) +#### [WDI_TLV_BSS_SELECTION_PARAMETERS](wdi-tlv-bss-selection-parameters.md) +#### [WDI_TLV_BSSID](wdi-tlv-bssid.md) +#### [WDI_TLV_BSSID_INFO](wdi-tlv-bssid-info.md) +#### [WDI_TLV_CANCEL_PARAMETERS](wdi-tlv-cancel-parameters.md) +#### [WDI_TLV_CHANNEL_INFO_LIST](wdi-tlv-channel-info-list.md) +#### [WDI_TLV_CHANNEL_LIST](wdi-tlv-channel-list.md) +#### [WDI_TLV_CHANNEL_NUMBER](wdi-tlv-channel-number.md) +#### [WDI_TLV_CHANNEL_WIDTH_LIST](wdi-tlv-channel-width-list.md) +#### [WDI_TLV_CHECKSUM_OFFLOAD_CAPABILITIES](wdi-tlv-checksum-offload-capabilities.md) +#### [WDI_TLV_CHECKSUM_OFFLOAD_V4_RX_PARAMETERS](wdi-tlv-checksum-offload-v4-rx-parameters.md) +#### [WDI_TLV_CHECKSUM_OFFLOAD_V4_TX_PARAMETERS](wdi-tlv-checksum-offload-v4-tx-parameters.md) +#### [WDI_TLV_CHECKSUM_OFFLOAD_V6_RX_PARAMETERS](wdi-tlv-checksum-offload-v6-rx-parameters.md) +#### [WDI_TLV_CHECKSUM_OFFLOAD_V6_TX_PARAMETERS](wdi-tlv-checksum-offload-v6-tx-parameters.md) +#### [WDI_TLV_CIPHER_KEY_BIP_KEY](wdi-tlv-cipher-key-bip-key.md) +#### [WDI_TLV_CIPHER_KEY_CCMP_KEY](wdi-tlv-cipher-key-ccmp-key.md) +#### [WDI_TLV_CIPHER_KEY_GCMP_KEY](wdi-tlv-cipher-key-gcmp-key.md) +#### [WDI_TLV_CIPHER_KEY_ID](wdi-tlv-cipher-key-id.md) +#### [WDI_TLV_CIPHER_KEY_IHV_KEY](wdi-tlv-cipher-key-ihv-key.md) +#### [WDI_TLV_CIPHER_KEY_RECEIVE_SEQUENCE_COUNT](wdi-tlv-cipher-key-receive-sequence-count.md) +#### [WDI_TLV_CIPHER_KEY_TKIP_INFO](wdi-tlv-cipher-key-tkip-info.md) +#### [WDI_TLV_CIPHER_KEY_TKIP_KEY](wdi-tlv-cipher-key-tkip-key.md) +#### [WDI_TLV_CIPHER_KEY_TKIP_MIC](wdi-tlv-cipher-key-tkip-mic.md) +#### [WDI_TLV_CIPHER_KEY_TYPE_INFO](wdi-tlv-cipher-key-type-info.md) +#### [WDI_TLV_CIPHER_KEY_WEP_KEY](wdi-tlv-cipher-key-wep-key.md) +#### [WDI_TLV_COALESCING_FILTER_MATCH_COUNT](wdi-tlv-coalescing-filter-match-count.md) +#### [WDI_TLV_COMMUNICATION_CAPABILITIES](wdi-tlv-communication-capabilities.md) +#### [WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES](wdi-tlv-communication-configuration-attributes.md) +#### [WDI_TLV_CONFIGURED_MAC_ADDRESS](wdi-tlv-configured-mac-address.md) +#### [WDI_TLV_CONNECT_BSS_ENTRY](wdi-tlv-connect-bss-entry.md) +#### [WDI_TLV_CONNECT_PARAMETERS](wdi-tlv-connect-parameters.md) +#### [WDI_TLV_CONNECTION_QUALITY_PARAMETERS](wdi-tlv-connection-quality-parameters.md) +#### [WDI_TLV_CONNECTION_SETTINGS](wdi-tlv-connection-settings.md) +#### [WDI_TLV_COUNTRY_REGION_LIST](wdi-tlv-country-region-list.md) +#### [WDI_TLV_CREATE_PORT_MAC_ADDRESS](wdi-tlv-create-port-mac-address.md) +#### [WDI_TLV_CREATE_PORT_PARAMETERS](wdi-tlv-create-port-parameters.md) +#### [WDI_TLV_CURRENT_CHANNEL_PARAMETERS](wdi-tlv-current-channel-parameters.md) +#### [WDI_TLV_DATAPATH_ATTRIBUTES](wdi-tlv-datapath-attributes.md) +#### [WDI_TLV_DATAPATH_CAPABILITIES](wdi-tlv-datapath-capabilities.md) +#### [WDI_TLV_DEFAULT_TX_KEY_ID_PARAMETERS](wdi-tlv-default-tx-key-id-parameters.md) +#### [WDI_TLV_DELETE_CIPHER_KEY_INFO](wdi-tlv-delete-cipher-key-info.md) +#### [WDI_TLV_DELETE_PEER_STATE_PARAMETERS](wdi-tlv-delete-peer-state-parameters.md) +#### [WDI_TLV_DELETE_PORT_PARAMETERS](wdi-tlv-delete-port-parameters.md) +#### [WDI_TLV_DISALLOWED_BSSIDS_LIST](wdi-tlv-disallowed-bssids-list.md) +#### [WDI_TLV_DISASSOCIATION_INDICATION_PARAMETERS](wdi-tlv-disassociation-indication-parameters.md) +#### [WDI_TLV_DISASSOCIATION_PARAMETERS](wdi-tlv-disassociation-parameters.md) +#### [WDI_TLV_DISCONNECT_DEAUTH_FRAME](wdi-tlv-disconnect-deauth-frame.md) +#### [WDI_TLV_DISCONNECT_DISASSOCIATION_FRAME](wdi-tlv-disconnect-disassociation-frame.md) +#### [WDI_TLV_DISCONNECT_PARAMETERS](wdi-tlv-disconnect-parameters.md) +#### [WDI_TLV_DOT11_RESET_PARAMETERS](wdi-tlv-dot11-reset-parameters.md) +#### [WDI_TLV_ENABLE_WAKE_EVENTS](wdi-tlv-enable-wake-events.md) +#### [WDI_TLV_ETHERTYPE_ENCAP_TABLE](wdi-tlv-ethertype-encap-table.md) +#### [WDI_TLV_EXTRA_ASSOCIATION_REQUEST_IES](wdi-tlv-extra-association-request-ies.md) +#### [WDI_TLV_FIRMWARE_VERSION](wdi-tlv-firmware-version.md) +#### [WDI_TLV_FT_AUTH_REQUEST](wdi-tlv-ft-auth-request.md) +#### [WDI_TLV_FT_AUTH_RESPONSE](wdi-tlv-ft-auth-response.md) +#### [WDI_TLV_FT_FTE](wdi-tlv-ft-fte.md) +#### [WDI_TLV_FT_INITIAL_ASSOC_PARAMETERS](wdi-tlv-ft-initial-assoc-parameters.md) +#### [WDI_TLV_FT_MDE](wdi-tlv-ft-mde.md) +#### [WDI_TLV_FT_PMKR0NAME](wdi-tlv-ft-pmkr0name.md) +#### [WDI_TLV_FT_R0KHID](wdi-tlv-ft-r0khid.md) +#### [WDI_TLV_FT_R1KHID](wdi-tlv-ft-r1khid.md) +#### [WDI_TLV_FT_REASSOC_PARAMETERS](wdi-tlv-ft-reassoc-parameters.md) +#### [WDI_TLV_FT_RSNIE](wdi-tlv-ft-rsnie.md) +#### [WDI_TLV_FT_SNONCE](wdi-tlv-ft-snonce.md) +#### [WDI_TLV_GET_AUTO_POWER_SAVE](wdi-tlv-get-auto-power-save.md) +#### [WDI_TLV_HESSID](wdi-tlv-hessid.md) +#### [WDI_TLV_HESSID_INFO](wdi-tlv-hessid-info.md) +#### [WDI_TLV_HOTSPOT_DOMAIN_PARTNER](wdi-tlv-hotspot-domain-partner.md) +#### [WDI_TLV_HOTSPOT_INDICATION_ELEMENT](wdi-tlv-hotspot-indication-element.md) +#### [WDI_TLV_IHV_DATA](wdi-tlv-ihv-data.md) +#### [WDI_TLV_IHV_NON_WDI_OIDS_LIST](wdi-tlv-ihv-non-wdi-oids-list.md) +#### [WDI_TLV_IHV_TASK_DEVICE_CONTEXT](wdi-tlv-ihv-task-device-context.md) +#### [WDI_TLV_IHV_TASK_REQUEST_PARAMETERS](wdi-tlv-ihv-task-request-parameters.md) +#### [WDI_TLV_INCOMING_ASSOCIATION_REQUEST_INFO](wdi-tlv-incoming-association-request-info.md) +#### [WDI_TLV_INCOMING_ASSOCIATION_REQUEST_PARAMETERS](wdi-tlv-incoming-association-request-parameters.md) +#### [WDI_TLV_INDICATION_CAN_SUSTAIN_AP](wdi-tlv-indication-can-sustain-ap.md) +#### [WDI_TLV_INDICATION_STOP_AP](wdi-tlv-indication-stop-ap.md) +#### [WDI_TLV_INDICATION_WAKE_PACKET](wdi-tlv-indication-wake-packet.md) +#### [WDI_TLV_INDICATION_WAKE_PACKET_PATTERN_ID](wdi-tlv-indication-wake-packet-pattern-id.md) +#### [WDI_TLV_INDICATION_WAKE_REASON](wdi-tlv-indication-wake-reason.md) +#### [WDI_TLV_INTERFACE_ATTRIBUTES](wdi-tlv-interface-attributes.md) +#### [WDI_TLV_INTERFACE_CAPABILITIES](wdi-tlv-interface-capabilities.md) +#### [WDI_TLV_IPV4_CHECKSUM_OFFLOAD](wdi-tlv-ipv4-checksum-offload.md) +#### [WDI_TLV_IPV4_LSO_V2](wdi-tlv-ipv4-lso-v2.md) +#### [WDI_TLV_IPV6_CHECKSUM_OFFLOAD](wdi-tlv-ipv6-checksum-offload.md) +#### [WDI_TLV_IPV6_LSO_V2](wdi-tlv-ipv6-lso-v2.md) +#### [WDI_TLV_LINK_QUALITY_BAR_MAP](wdi-tlv-link-quality-bar-map.md) +#### [WDI_TLV_LINK_STATE_CHANGE_PARAMETERS](wdi-tlv-link-state-change-parameters.md) +#### [WDI_TLV_LOW_LATENCY_CONNECTION_QUALITY_PARAMETERS](wdi-tlv-low-latency-connection-quality-parameters.md) +#### [WDI_TLV_LSO_V1_CAPABILITIES](wdi-tlv-lso-v1-capabilities.md) +#### [WDI_TLV_LSO_V2_CAPABILITIES](wdi-tlv-lso-v2-capabilities.md) +#### [WDI_TLV_MAC_STATISTICS](wdi-tlv-mac-statistics.md) +#### [WDI_TLV_MULTICAST_CIPHER_ALGO_LIST](wdi-tlv-multicast-cipher-algo-list.md) +#### [WDI_TLV_MULTICAST_DATA_ALGORITHM_LIST](wdi-tlv-multicast-data-algorithm-list.md) +#### [WDI_TLV_MULTICAST_LIST](wdi-tlv-multicast-list.md) +#### [WDI_TLV_MULTICAST_MGMT_ALGORITHM_LIST](wdi-tlv-multicast-mgmt-algorithm-list.md) +#### [WDI_TLV_NEIGHBOR_REPORT_ENTRY](wdi-tlv-neighbor-report-entry.md) +#### [WDI_TLV_NETWORK_LIST_OFFLOAD_CONFIG](wdi-tlv-network-list-offload-config.md) +#### [WDI_TLV_NETWORK_LIST_OFFLOAD_PARAMETERS](wdi-tlv-network-list-offload-parameters.md) +#### [WDI_TLV_NETWORK_OFFLOAD_CHANNELS](wdi-tlv-network-offload-channels.md) +#### [WDI_TLV_NEXT_DIALOG_TOKEN](wdi-tlv-next-dialog-token.md) +#### [WDI_TLV_OPERATING_CLASS](wdi-tlv-operating-class.md) +#### [WDI_TLV_OPERATION_MODE](wdi-tlv-operation-mode.md) +#### [WDI_TLV_P2P_ACTION_FRAME_DEVICE_CONTEXT](wdi-tlv-p2p-action-frame-device-context.md) +#### [WDI_TLV_P2P_ACTION_FRAME_IES](wdi-tlv-p2p-action-frame-ies.md) +#### [WDI_TLV_P2P_ACTION_FRAME_RESPONSE_PARAMETERS](wdi-tlv-p2p-action-frame-response-parameters.md) +#### [WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY](wdi-tlv-p2p-advertised-prefix-entry.md) +#### [WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY](wdi-tlv-p2p-advertised-service-entry.md) +#### [WDI_TLV_P2P_ADVERTISED_SERVICES](wdi-tlv-p2p-advertised-services.md) +#### [WDI_TLV_P2P_ADVERTISEMENT_ID](wdi-tlv-p2p-advertisement-id.md) +#### [WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY](wdi-tlv-p2p-asp2-advertised-service-entry.md) +#### [WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY](wdi-tlv-p2p-asp2-service-information-discovery-entry.md) +#### [WDI_TLV_P2P_ATTRIBUTES](wdi-tlv-p2p-attributes.md) +#### [WDI_TLV_P2P_BACKGROUND_DISCOVER_MODE](wdi-tlv-p2p-background-discover-mode.md) +#### [WDI_TLV_P2P_CAPABILITIES](wdi-tlv-p2p-capabilities.md) +#### [WDI_TLV_P2P_CHANNEL_ENTRY_LIST](wdi-tlv-p2p-channel-entry-list.md) +#### [WDI_TLV_P2P_CHANNEL_INDICATE_REASON](wdi-tlv-p2p-channel-indicate-reason.md) +#### [WDI_TLV_P2P_CHANNEL_LIST_ATTRIBUTE](wdi-tlv-p2p-channel-list-attribute.md) +#### [WDI_TLV_P2P_CHANNEL_NUMBER](wdi-tlv-p2p-channel-number.md) +#### [WDI_TLV_P2P_CONFIG_METHODS](wdi-tlv-p2p-config-methods.md) +#### [WDI_TLV_P2P_DEVICE_ADDRESS](wdi-tlv-p2p-device-address.md) +#### [WDI_TLV_P2P_DEVICE_CAPABILITY](wdi-tlv-p2p-device-capability.md) +#### [WDI_TLV_P2P_DEVICE_FILTER_LIST](wdi-tlv-p2p-device-filter-list.md) +#### [WDI_TLV_P2P_DEVICE_INFO](wdi-tlv-p2p-device-info.md) +#### [WDI_TLV_P2P_DEVICE_INFO_PARAMETERS](wdi-tlv-p2p-device-info-parameters.md) +#### [WDI_TLV_P2P_DEVICE_NAME](wdi-tlv-p2p-device-name.md) +#### [WDI_TLV_P2P_DISCOVER_MODE](wdi-tlv-p2p-discover-mode.md) +#### [WDI_TLV_P2P_DISCOVERED_SERVICE_ENTRY](wdi-tlv-p2p-discovered-service-entry.md) +#### [WDI_TLV_P2P_DISCOVERY_CHANNEL_SETTINGS](wdi-tlv-p2p-discovery-channel-settings.md) +#### [WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY](wdi-tlv-p2p-go-internal-reset-policy.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_INFO](wdi-tlv-p2p-go-negotiation-confirmation-info.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_PARAMETERS](wdi-tlv-p2p-go-negotiation-confirmation-parameters.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_INFO](wdi-tlv-p2p-go-negotiation-request-info.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_PARAMETERS](wdi-tlv-p2p-go-negotiation-request-parameters.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_INFO](wdi-tlv-p2p-go-negotiation-response-info.md) +#### [WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_PARAMETERS](wdi-tlv-p2p-go-negotiation-response-parameters.md) +#### [WDI_TLV_P2P_GROUP_BSSID](wdi-tlv-p2p-group-bssid.md) +#### [WDI_TLV_P2P_GROUP_ID](wdi-tlv-p2p-group-id.md) +#### [WDI_TLV_P2P_GROUP_OWNER_CAPABILITY](wdi-tlv-p2p-group-owner-capability.md) +#### [WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL](wdi-tlv-p2p-include-listen-channel.md) +#### [WDI_TLV_P2P_INCOMING_FRAME_INFORMATION](wdi-tlv-p2p-incoming-frame-information.md) +#### [WDI_TLV_P2P_INCOMING_FRAME_PARAMETERS](wdi-tlv-p2p-incoming-frame-parameters.md) +#### [WDI_TLV_P2P_INSTANCE_NAME](wdi-tlv-p2p-instance-name.md) +#### [WDI_TLV_P2P_INSTANCE_NAME_HASH](wdi-tlv-p2p-instance-name-hash.md) +#### [WDI_TLV_P2P_INTERFACE_ADDRESS_LIST](wdi-tlv-p2p-interface-address-list.md) +#### [WDI_TLV_P2P_INVITATION_REQUEST_INFO](wdi-tlv-p2p-invitation-request-info.md) +#### [WDI_TLV_P2P_INVITATION_REQUEST_PARAMETERS](wdi-tlv-p2p-invitation-request-parameters.md) +#### [WDI_TLV_P2P_INVITATION_RESPONSE_INFO](wdi-tlv-p2p-invitation-response-info.md) +#### [WDI_TLV_P2P_INVITATION_RESPONSE_PARAMETERS](wdi-tlv-p2p-invitation-response-parameters.md) +#### [WDI_TLV_P2P_LISTEN_CHANNEL](wdi-tlv-p2p-listen-channel.md) +#### [WDI_TLV_P2P_LISTEN_DURATION](wdi-tlv-p2p-listen-duration.md) +#### [WDI_TLV_P2P_LISTEN_STATE](wdi-tlv-p2p-listen-state.md) +#### [WDI_TLV_P2P_PERSISTENT_GROUP_ID](wdi-tlv-p2p-persistent-group-id.md) +#### [WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_INFO](wdi-tlv-p2p-provision-discovery-request-info.md) +#### [WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_PARAMETERS](wdi-tlv-p2p-provision-discovery-request-parameters.md) +#### [WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_INFO](wdi-tlv-p2p-provision-discovery-response-info.md) +#### [WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_PARAMETERS](wdi-tlv-p2p-provision-discovery-response-parameters.md) +#### [WDI_TLV_P2P_PROVISION_SERVICE_ATTRIBUTES](wdi-tlv-p2p-provision-service-attributes.md) +#### [WDI_TLV_P2P_RESPONSE_FRAME_PARAMETERS](wdi-tlv-p2p-response-frame-parameters.md) +#### [WDI_TLV_P2P_SECONDARY_DEVICE_TYPE_LIST](wdi-tlv-p2p-secondary-device-type-list.md) +#### [WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT](wdi-tlv-p2p-send-action-frame-result.md) +#### [WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT_PARAMETERS](wdi-tlv-p2p-send-action-frame-result-parameters.md) +#### [WDI_TLV_P2P_SEND_ACTION_REQUEST_FRAME_PARAMETERS](wdi-tlv-p2p-send-action-request-frame-parameters.md) +#### [WDI_TLV_P2P_SEND_REQUEST_ACTION_FRAME_RESULT](wdi-tlv-p2p-send-request-action-frame-result.md) +#### [WDI_TLV_P2P_SEND_RESPONSE_ACTION_FRAME_RESULT](wdi-tlv-p2p-send-response-action-frame-result.md) +#### [WDI_TLV_P2P_SERVICE_INFORMATION](wdi-tlv-p2p-service-information.md) +#### [WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY](wdi-tlv-p2p-service-information-discovery-entry.md) +#### [WDI_TLV_P2P_SERVICE_INFORMATION_ENTRY](wdi-tlv-p2p-service-information-entry.md) +#### [WDI_TLV_P2P_SERVICE_NAME](wdi-tlv-p2p-service-name.md) +#### [WDI_TLV_P2P_SERVICE_NAME_HASH](wdi-tlv-p2p-service-name-hash.md) +#### [WDI_TLV_P2P_SERVICE_SESSION_INFO](wdi-tlv-p2p-service-session-info.md) +#### [WDI_TLV_P2P_SERVICE_STATUS](wdi-tlv-p2p-service-status.md) +#### [WDI_TLV_P2P_SERVICE_TRANSACTION_ID](wdi-tlv-p2p-service-transaction-id.md) +#### [WDI_TLV_P2P_SERVICE_TYPE](wdi-tlv-p2p-service-type.md) +#### [WDI_TLV_P2P_SERVICE_TYPE_HASH](wdi-tlv-p2p-service-type-hash.md) +#### [WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR](wdi-tlv-p2p-service-update-indicator.md) +#### [WDI_TLV_P2P_WPS_ENABLED](wdi-tlv-p2p-wps-enabled.md) +#### [WDI_TLV_PACKET_FILTER_PARAMETERS](wdi-tlv-packet-filter-parameters.md) +#### [WDI_TLV_PEER_MAC_ADDRESS](wdi-tlv-peer-mac-address.md) +#### [WDI_TLV_PHY_CAPABILITIES](wdi-tlv-phy-capabilities.md) +#### [WDI_TLV_PHY_DATA_RATE_LIST](wdi-tlv-phy-data-rate-list.md) +#### [WDI_TLV_PHY_INFO](wdi-tlv-phy-info.md) +#### [WDI_TLV_PHY_LIST](wdi-tlv-phy-list.md) +#### [WDI_TLV_PHY_STATISTICS](wdi-tlv-phy-statistics.md) +#### [WDI_TLV_PHY_SUPPORTED_RX_DATA_RATES_LIST](wdi-tlv-phy-supported-rx-data-rates-list.md) +#### [WDI_TLV_PHY_SUPPORTED_TX_DATA_RATES_LIST](wdi-tlv-phy-supported-tx-data-rates-list.md) +#### [WDI_TLV_PHY_TX_POWER_LEVEL_LIST](wdi-tlv-phy-tx-power-level-list.md) +#### [WDI_TLV_PHY_TYPE](wdi-tlv-phy-type.md) +#### [WDI_TLV_PHY_TYPE_LIST](wdi-tlv-phy-type-list.md) +#### [WDI_TLV_PHY_TYPE_LIST (unused)](wdi-tlv-phy-type-list--disabled.md) +#### [WDI_TLV_PLDR_SUPPORT](wdi-tlv-pldr-support.md) +#### [WDI_TLV_PM_CAPABILITIES](wdi-tlv-pm-capabilities.md) +#### [WDI_TLV_PM_PROTOCOL_OFFLOAD_80211RSN_REKEY](wdi-tlv-pm-protocol-offload-80211rsn-rekey.md) +#### [WDI_TLV_PM_PROTOCOL_OFFLOAD_GET](wdi-tlv-pm-protocol-offload-get.md) +#### [WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv4ARP](wdi-tlv-pm-protocol-offload-ipv4arp.md) +#### [WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv6NS](wdi-tlv-pm-protocol-offload-ipv6ns.md) +#### [WDI_TLV_PM_PROTOCOL_OFFLOAD_REMOVE](wdi-tlv-pm-protocol-offload-remove.md) +#### [WDI_TLV_PMKID](wdi-tlv-pmkid.md) +#### [WDI_TLV_PORT_ATTRIBUTES](wdi-tlv-port-attributes.md) +#### [WDI_TLV_POWER_MANAGMENT_CAPABILITIES](wdi-tlv-power-managment-capabilities.md) +#### [WDI_TLV_POWER_STATE](wdi-tlv-power-state.md) +#### [WDI_TLV_PRIVACY_EXEMPTION_ENTRY](wdi-tlv-privacy-exemption-entry.md) +#### [WDI_TLV_PROBE_RESPONSE_FRAME](wdi-tlv-probe-response-frame.md) +#### [WDI_TLV_RADIO_STATE](wdi-tlv-radio-state.md) +#### [WDI_TLV_RADIO_STATE_PARAMETERS](wdi-tlv-radio-state-parameters.md) +#### [WDI_TLV_RECEIVE_COALESCE_OFFLOAD_CAPABILITIES](wdi-tlv-receive-coalesce-offload-capabilities.md) +#### [WDI_TLV_RECEIVE_COALESCING_CAPABILITIES](wdi-tlv-receive-coalescing-capabilities.md) +#### [WDI_TLV_RECEIVE_COALESCING_CONFIG](wdi-tlv-receive-coalescing-config.md) +#### [WDI_TLV_RECEIVE_FILTER_FIELD](wdi-tlv-receive-filter-field.md) +#### [WDI_TLV_ROAMING_NEEDED_PARAMETERS](wdi-tlv-roaming-needed-parameters.md) +#### [WDI_TLV_SAFE_MODE_PARAMETERS](wdi-tlv-safe-mode-parameters.md) +#### [WDI_TLV_SCAN_DWELL_TIME](wdi-tlv-scan-dwell-time.md) +#### [WDI_TLV_SCAN_MODE](wdi-tlv-scan-mode.md) +#### [WDI_TLV_SEND_ACTION_FRAME_REQUEST_PARAMETERS](wdi-tlv-send-action-frame-request-parameters.md) +#### [WDI_TLV_SEND_ACTION_FRAME_RESPONSE_PARAMETERS](wdi-tlv-send-action-frame-response-parameters.md) +#### [WDI_TLV_SET_AUTO_POWER_SAVE](wdi-tlv-set-auto-power-save.md) +#### [WDI_TLV_SET_CIPHER_KEY_INFO](wdi-tlv-set-cipher-key-info.md) +#### [WDI_TLV_SET_CLEAR_RECEIVE_COALESCING](wdi-tlv-set-clear-receive-coalescing.md) +#### [WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V4_PARAMETERS](wdi-tlv-set-encapsulation-offload-v4-parameters.md) +#### [WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V6_PARAMETERS](wdi-tlv-set-encapsulation-offload-v6-parameters.md) +#### [WDI_TLV_SET_POWER_DX_REASON](wdi-tlv-set-power-dx-reason.md) +#### [WDI_TLV_SET_RECEIVE_COALESCING](wdi-tlv-set-receive-coalescing.md) +#### [WDI_TLV_SSID](wdi-tlv-ssid.md) +#### [WDI_TLV_SSID_LIST](wdi-tlv-ssid-list.md) +#### [WDI_TLV_SSID_OFFLOAD](wdi-tlv-ssid-offload.md) +#### [WDI_TLV_START_AP_PARAMETERS](wdi-tlv-start-ap-parameters.md) +#### [WDI_TLV_STATION_ATTRIBUTES](wdi-tlv-station-attributes.md) +#### [WDI_TLV_STATION_CAPABILITIES](wdi-tlv-station-capabilities.md) +#### [WDI_TLV_STATUS](wdi-tlv-status.md) +#### [WDI_TLV_SUPPORTED_GUIDS](wdi-tlv-supported-guids.md) +#### [WDI_TLV_TCP_OFFLOAD_CAPABILITIES](wdi-tlv-tcp-offload-capabilities.md) +#### [WDI_TLV_TCP_RSC_STATISTICS_PARAMETERS](wdi-tlv-tcp-rsc-statistics-parameters.md) +#### [WDI_TLV_TCP_SET_OFFLOAD_PARAMETERS](wdi-tlv-tcp-set-offload-parameters.md) +#### [WDI_TLV_TKIP_MIC_FAILURE_INFO](wdi-tlv-tkip-mic-failure-info.md) +#### [WDI_TLV_UNICAST_ALGORITHM_LIST](wdi-tlv-unicast-algorithm-list.md) +#### [WDI_TLV_UNICAST_CIPHER_ALGO_LIST](wdi-tlv-unicast-cipher-algo-list.md) +#### [WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD](wdi-tlv-unreachable-detection-threshold.md) +#### [WDI_TLV_VENDOR_SPECIFIC_IE](wdi-tlv-vendor-specific-ie.md) +#### [WDI_TLV_VIRTUALIZATION_ATTRIBUTES](wdi-tlv-virtualization-attributes.md) +#### [WDI_TLV_VIRTUALIZATION_CAPABILITIES](wdi-tlv-virtualization-capabilities.md) +#### [WDI_TLV_WAKE_PACKET_BITMAP_PATTERN](wdi-tlv-wake-packet-bitmap-pattern.md) +#### [WDI_TLV_WAKE_PACKET_BITMAP_PATTERN_ID](wdi-tlv-wake-packet-bitmap-pattern-id.md) +#### [WDI_TLV_WAKE_PACKET_EAPOL_REQUEST_ID_MESSAGE](wdi-tlv-wake-packet-eapol-request-id-message.md) +#### [WDI_TLV_WAKE_PACKET_IPv4_TCP_SYNC](wdi-tlv-wake-packet-ipv4-tcp-sync.md) +#### [WDI_TLV_WAKE_PACKET_IPv6_TCP_SYNC](wdi-tlv-wake-packet-ipv6-tcp-sync.md) +#### [WDI_TLV_WAKE_PACKET_MAGIC_PACKET](wdi-tlv-wake-packet-magic-packet.md) +#### [WDI_TLV_WAKE_PACKET_PATTERN_REMOVE](wdi-tlv-wake-packet-pattern-remove.md) +#### [WDI_TLV_WFD_ASSOCIATION_STATUS](wdi-tlv-wfd-association-status.md) ### [WDI USB Selective Suspend](wdi-usb-selective-suspend.md) #### [WDI NDIS idle detection](wdi-ndis-idle-detection.md) #### [WDI and WLAN Selective Suspend capability](wdi-and-wlan-selective-suspend-capability.md) @@ -1585,6 +2081,109 @@ #### [WDI Extended channel switch announcement (ECSA)](wdi-extended-channel-switch-announcement--ecsa-.md) #### [WDI IHV extensible types](wdi-ihv-extensible-types.md) #### [Develop and validate WDI drivers for Reset Recovery](wdi-develop-and-validate-wdi-drivers-for-reset-recovery.md) +### [WDI Task OIDs](wdi-miniport-driver-task-oids.md) +#### [OID_WDI_TASK_CHANGE_OPERATION_MODE](oid-wdi-task-change-operation-mode.md) +#### [OID_WDI_TASK_CLOSE](oid-wdi-task-close.md) +#### [OID_WDI_TASK_CONNECT](oid-wdi-task-connect.md) +#### [OID_WDI_TASK_CREATE_PORT](oid-wdi-task-create-port.md) +#### [OID_WDI_TASK_DELETE_PORT](oid-wdi-task-delete-port.md) +#### [OID_WDI_TASK_DISCONNECT](oid-wdi-task-disconnect.md) +#### [OID_WDI_TASK_DOT11_RESET](oid-wdi-task-dot11-reset.md) +#### [OID_WDI_TASK_IHV](oid-wdi-task-ihv.md) +#### [OID_WDI_TASK_OPEN](oid-wdi-task-open.md) +#### [OID_WDI_TASK_P2P_DISCOVER](oid-wdi-task-p2p-discover.md) +#### [OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME](oid-wdi-task-p2p-send-request-action-frame.md) +#### [OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME](oid-wdi-task-p2p-send-response-action-frame.md) +#### [OID_WDI_TASK_ROAM](oid-wdi-task-roam.md) +#### [OID_WDI_TASK_SCAN](oid-wdi-task-scan.md) +#### [OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE](oid-wdi-task-send-ap-association-response.md) +#### [OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME](oid-wdi-task-send-request-action-frame.md) +#### [OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME](oid-wdi-task-send-response-action-frame.md) +#### [OID_WDI_TASK_SET_RADIO_STATE](oid-wdi-task-set-radio-state.md) +#### [OID_WDI_TASK_START_AP](oid-wdi-task-start-ap.md) +#### [OID_WDI_TASK_STOP_AP](oid-wdi-task-stop-ap.md) +### [WDI Property OIDs](wdi-miniport-driver-property-oids.md) +#### [OID_WDI_ABORT_TASK](oid-wdi-abort-task.md) +#### [OID_WDI_GET_ADAPTER_CAPABILITIES](oid-wdi-get-adapter-capabilities.md) +#### [OID_WDI_GET_AUTO_POWER_SAVE](oid-wdi-get-auto-power-save.md) +#### [OID_WDI_GET_BSS_ENTRY_LIST](oid-wdi-get-bss-entry-list.md) +#### [OID_WDI_GET_NEXT_ACTION_FRAME_DIALOG_TOKEN](oid-wdi-get-next-action-frame-dialog-token.md) +#### [OID_WDI_GET_PM_PROTOCOL_OFFLOAD](oid-wdi-get-pm-protocol-offload.md) +#### [OID_WDI_GET_RECEIVE_COALESCING_MATCH_COUNT](oid-wdi-get-receive-coalescing-match-count.md) +#### [OID_WDI_GET_STATISTICS](oid-wdi-get-statistics.md) +#### [OID_WDI_IHV_REQUEST](oid-wdi-ihv-request.md) +#### [OID_WDI_SET_ADAPTER_CONFIGURATION](oid-wdi-set-adapter-configuration.md) +#### [OID_WDI_SET_ADD_CIPHER_KEYS](oid-wdi-set-add-cipher-keys.md) +#### [OID_WDI_SET_ADD_PM_PROTOCOL_OFFLOAD](oid-wdi-set-add-pm-protocol-offload.md) +#### [OID_WDI_SET_ADD_WOL_PATTERN](oid-wdi-set-add-wol-pattern.md) +#### [OID_WDI_SET_ADVERTISEMENT_INFORMATION](oid-wdi-set-advertisement-information.md) +#### [OID_WDI_SET_ASSOCIATION_PARAMETERS](oid-wdi-set-association-parameters.md) +#### [OID_WDI_SET_CLEAR_RECEIVE_COALESCING](oid-wdi-set-clear-receive-coalescing.md) +#### [OID_WDI_SET_CONNECTION_QUALITY](oid-wdi-set-connection-quality.md) +#### [OID_WDI_SET_DEFAULT_KEY_ID](oid-wdi-set-default-key-id.md) +#### [OID_WDI_SET_DELETE_CIPHER_KEYS](oid-wdi-set-delete-cipher-keys.md) +#### [OID_WDI_SET_ENCAPSULATION_OFFLOAD](oid-wdi-set-encapsulation-offload.md) +#### [OID_WDI_SET_END_DWELL_TIME](oid-wdi-set-end-dwell-time.md) +#### [OID_WDI_SET_FAST_BSS_TRANSITION_PARAMETERS](oid-wdi-set-fast-bss-transition-parameters.md) +#### [OID_WDI_SET_FLUSH_BSS_ENTRY](oid-wdi-set-flush-bss-entry.md) +#### [OID_WDI_SET_MULTICAST_LIST](oid-wdi-set-multicast-list.md) +#### [OID_WDI_SET_NEIGHBOR_REPORT_ENTRIES](oid-wdi-set-neighbor-report-entries.md) +#### [OID_WDI_SET_NETWORK_LIST_OFFLOAD](oid-wdi-set-network-list-offload.md) +#### [OID_WDI_SET_P2P_LISTEN_STATE](oid-wdi-set-p2p-listen-state.md) +#### [OID_WDI_SET_P2P_START_BACKGROUND_DISCOVERY](oid-wdi-set-p2p-start-background-discovery.md) +#### [OID_WDI_SET_P2P_STOP_BACKGROUND_DISCOVERY](oid-wdi-set-p2p-stop-background-discovery.md) +#### [OID_WDI_SET_P2P_WPS_ENABLED](oid-wdi-set-p2p-wps-enabled.md) +#### [OID_WDI_SET_POWER_STATE](oid-wdi-set-power-state.md) +#### [OID_WDI_SET_PRIVACY_EXEMPTION_LIST](oid-wdi-set-privacy-exemption-list.md) +#### [OID_WDI_SET_RECEIVE_COALESCING](oid-wdi-set-receive-coalescing.md) +#### [OID_WDI_SET_RECEIVE_PACKET_FILTER](oid-wdi-set-receive-packet-filter.md) +#### [OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD](oid-wdi-set-remove-pm-protocol-offload.md) +#### [OID_WDI_SET_REMOVE_WOL_PATTERN](oid-wdi-set-remove-wol-pattern.md) +#### [OID_WDI_SET_TCP_OFFLOAD_PARAMETERS](oid-wdi-set-tcp-offload-parameters.md) +#### [OID_WDI_TCP_RSC_STATISTICS](oid-wdi-tcp-rsc-statistics.md) +### [WDI Status Indications](wdi-miniport-driver-status-indications.md) +#### [NDIS_STATUS_WDI_INDICATION_ACTION_FRAME_RECEIVED](ndis-status-wdi-indication-action-frame-received.md) +#### [NDIS_STATUS_WDI_INDICATION_AP_ASSOCIATION_REQUEST_RECEIVED](ndis-status-wdi-indication-ap-association-request-received.md) +#### [NDIS_STATUS_WDI_INDICATION_ASSOCIATION_PARAMETERS_REQUEST](ndis-status-wdi-indication-association-parameters-request.md) +#### [NDIS_STATUS_WDI_INDICATION_ASSOCIATION_RESULT](ndis-status-wdi-indication-association-result.md) +#### [NDIS_STATUS_WDI_INDICATION_BSS_ENTRY_LIST](ndis-status-wdi-indication-bss-entry-list.md) +#### [NDIS_STATUS_WDI_INDICATION_CAN_SUSTAIN_AP](ndis-status-wdi-indication-can-sustain-ap.md) +#### [NDIS_STATUS_WDI_INDICATION_CHANGE_OPERATION_MODE_COMPLETE](ndis-status-wdi-indication-change-operation-mode-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_CLOSE_COMPLETE](ndis-status-wdi-indication-close-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_CONNECT_COMPLETE](ndis-status-wdi-indication-connect-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_CREATE_PORT_COMPLETE](ndis-status-wdi-indication-create-port-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_DELETE_PORT_COMPLETE](ndis-status-wdi-indication-delete-port-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_DISASSOCIATION](ndis-status-wdi-indication-disassociation.md) +#### [NDIS_STATUS_WDI_INDICATION_DISCONNECT_COMPLETE](ndis-status-wdi-indication-disconnect-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_DOT11_RESET_COMPLETE](ndis-status-wdi-indication-dot11-reset-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_FIRMWARE_STALLED](ndis-status-wdi-indication-firmware-stalled.md) +#### [NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED](ndis-status-wdi-indication-ft-assoc-params-needed.md) +#### [NDIS_STATUS_WDI_INDICATION_IHV_EVENT](ndis-status-wdi-indication-ihv-event.md) +#### [NDIS_STATUS_WDI_INDICATION_IHV_TASK_COMPLETE](ndis-status-wdi-indication-ihv-task-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST](ndis-status-wdi-indication-ihv-task-request.md) +#### [NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE](ndis-status-wdi-indication-link-state-change.md) +#### [NDIS_STATUS_WDI_INDICATION_NLO_DISCOVERY](ndis-status-wdi-indication-nlo-discovery.md) +#### [NDIS_STATUS_WDI_INDICATION_OPEN_COMPLETE](ndis-status-wdi-indication-open-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_ACTION_FRAME_RECEIVED](ndis-status-wdi-indication-p2p-action-frame-received.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_DISCOVERY_COMPLETE](ndis-status-wdi-indication-p2p-discovery-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_GROUP_OPERATING_CHANNEL](ndis-status-wdi-indication-p2p-group-operating-channel.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_OPERATING_CHANNEL_ATTRIBUTES](ndis-status-wdi-indication-p2p-operating-channel-attributes.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_SEND_REQUEST_ACTION_FRAME_COMPLETE](ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_P2P_SEND_RESPONSE_ACTION_FRAME_COMPLETE](ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_RADIO_STATUS](ndis-status-wdi-indication-radio-status.md) +#### [NDIS_STATUS_WDI_INDICATION_ROAM_COMPLETE](ndis-status-wdi-indication-roam-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_ROAMING_NEEDED](ndis-status-wdi-indication-roaming-needed.md) +#### [NDIS_STATUS_WDI_INDICATION_SCAN_COMPLETE](ndis-status-wdi-indication-scan-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_SEND_AP_ASSOCIATION_RESPONSE_COMPLETE](ndis-status-wdi-indication-send-ap-association-response-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_SEND_REQUEST_ACTION_FRAME_COMPLETE](ndis-status-wdi-indication-send-request-action-frame-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_SEND_RESPONSE_ACTION_FRAME_COMPLETE](ndis-status-wdi-indication-send-response-action-frame-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_SET_RADIO_STATE_COMPLETE](ndis-status-wdi-indication-set-radio-state-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_START_AP_COMPLETE](ndis-status-wdi-indication-start-ap-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_STOP_AP](ndis-status-wdi-indication-stop-ap.md) +#### [NDIS_STATUS_WDI_INDICATION_STOP_AP_COMPLETE](ndis-status-wdi-indication-stop-ap-complete.md) +#### [NDIS_STATUS_WDI_INDICATION_TASK_OFFLOAD_CURRENT_CONFIG](ndis-status-wdi-indication-task-offload-current-config.md) +#### [NDIS_STATUS_WDI_INDICATION_TKIP_MIC_FAILURE](ndis-status-wdi-indication-tkip-mic-failure.md) +#### [NDIS_STATUS_WDI_INDICATION_WAKE_REASON](ndis-status-wdi-indication-wake-reason.md) ### [Features not carried over in WDI](wdi-features-not-carried-over-in-wdi.md) ### [WDI doc change history](wdi-doc-change-history.md) ## [Wi-Fi Hotspot Offloading Guide](wi-fi-hotspot-offloading-guide.md) @@ -1592,6 +2191,49 @@ ### [Wi-Fi Hotspot Offloading Plugin](wi-fi-hotspot-offloading-plugin.md) ### [Wi-Fi Discovery Service](wi-fi-discovery-service.md) #### [Wi-Fi Hotspot Data Submission Format](wi-fi-hotspot-data-submission-format.md) +### [Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) +#### [Wi-Fi Hotspot Offloading Constants](wi-fi-hotspot-offloading-constants.md) +#### [Wi-Fi Hotspot Offloading Structures](wi-fi-hotspot-offloading-structures.md) +##### [HOTSPOT_HOST_HANDLERS](hotspot-host-handlers.md) +##### [HOTSPOT_PLUGIN_APIS](hotspot-plugin-apis.md) +##### [HS_CONNECTION_CONTEXT](hs-connection-context.md) +##### [HS_DEVICE_IDENTITY](hs-device-identity.md) +##### [HS_MAC_ADDRESS](hs-mac-address.md) +##### [HS_NETWORK_IDENTITY](hs-network-identity.md) +##### [HS_NETWORK_PROFILE](hs-network-profile.md) +##### [HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS](hs-plugin-cellular-exception-hosts.md) +##### [HS_PLUGIN_HOST_NAME](hs-plugin-host-name.md) +##### [HS_PLUGIN_PROFILE](hs-plugin-profile.md) +##### [HS_PLUGIN_SUPPORTED_SIMS](hs-plugin-supported-sims.md) +##### [HS_PLUGIN_VERSION](hs-plugin-version.md) +##### [HS_SIM_DATA](hs-sim-data.md) +##### [HS_SIM_IDENTITY](hs-sim-identity.md) +#### [Wi-Fi Hotspot Offloading Functions](wi-fi-hotspot-offloading-functions.md) +##### [HSPluginGetVersion](hsplugingetversion.md) +##### [HSPluginInitPlugin](hsplugininitplugin.md) +##### [HS_PLUGIN_CHECK_FOR_UPDATES](hs-plugin-check-for-updates.md) +##### [HS_PLUGIN_DEINIT](hs-plugin-deinit.md) +##### [HS_PLUGIN_DISCONNECT_FROM_NETWORK](hs-plugin-disconnect-from-network.md) +##### [HS_PLUGIN_IS_HOTSPOT_NETWORK](hs-plugin-is-hotspot-network.md) +##### [HS_PLUGIN_PRE_CONNECT_INIT](hs-plugin-pre-connect-init.md) +##### [HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS](hs-plugin-query-cellular-exception-hosts.md) +##### [HS_PLUGIN_QUERY_HIDDEN_NETWORK](hs-plugin-query-hidden-network.md) +##### [HS_PLUGIN_QUERY_SUPPORTED_SIMS](hs-plugin-query-supported-sims.md) +##### [HS_PLUGIN_RESET](hs-plugin-reset.md) +##### [HS_PLUGIN_SEND_KEEP_ALIVE](hs-plugin-send-keep-alive.md) +##### [HS_PLUGIN_START_POST_CONNECT_AUTH](hs-plugin-start-post-connect-auth.md) +##### [HS_PLUGIN_STOP_POST_CONNECT_AUTH](hs-plugin-stop-post-connect-auth.md) +##### [HS_HOST_ALLOCATE_MEMORY](hs-host-allocate-memory.md) +##### [HS_HOST_FREE_MEMORY](hs-host-free-memory.md) +##### [HS_HOST_POST_CONNECT_AUTH_COMPLETION](hs-host-post-connect-auth-completion.md) +##### [HS_HOST_SEND_KEEP_ALIVE_COMPLETION](hs-host-send-keep-alive-completion.md) +##### [HS_HOST_SEND_USER_MESSAGE](hs-host-send-user-message.md) +##### [HS_HOST_UPDATE_CONFIGURATION_COMPLETION](hs-host-update-configuration-completion.md) +#### [Wi-Fi Hotspot Offloading Enumerations](wi-fi-hotspot-offloading-enumerations.md) +##### [eHS_AUTHENTICATION_RESULT](ehs-authentication-result.md) +##### [eHS_NETWORK_STATE](ehs-network-state.md) +##### [eHS_UNLOAD_REASON](ehs-unload-reason.md) +##### [eHS_UPDATE_RESULT](ehs-update-result.md) # [Network Module Registrar](network-module-registrar2.md) ## [Introduction to the Network Module Registrar](introduction-to-the-network-module-registrar.md) ## [Network Module Registrar Definitions](nmr-definitions.md) @@ -1646,6 +2288,25 @@ ### [Registering an Extension Interface](registering-an-extension-interface.md) ### [Unregistering a Winsock Kernel Application](unregistering-a-winsock-kernel-application.md) ### [Resolving Host Names and IP Addresses](resolving-host-names-and-ip-addresses.md) +### [WSK Client Control Operations](wsk-client-control-operations.md) +#### [WSK_CACHE_SD](wsk-cache-sd.md) +#### [WSK_RELEASE_SD](wsk-release-sd.md) +#### [WSK_SET_STATIC_EVENT_CALLBACKS](wsk-set-static-event-callbacks.md) +#### [WSK_TDI_BEHAVIOR](wsk-tdi-behavior.md) +#### [WSK_TDI_DEVICENAME_MAPPING](wsk-tdi-devicename-mapping.md) +#### [WSK_TRANSPORT_LIST_CHANGE](wsk-transport-list-change.md) +#### [WSK_TRANSPORT_LIST_QUERY](wsk-transport-list-query.md) +### [WSK Socket IOCTL Operations](wsk-socket-ioctl-operations.md) +#### [SIO_WSK_QUERY_IDEAL_SEND_BACKLOG](sio-wsk-query-ideal-send-backlog.md) +#### [SIO_WSK_QUERY_INSPECT_ID](sio-wsk-query-inspect-id.md) +#### [SIO_WSK_QUERY_RECEIVE_BACKLOG](sio-wsk-query-receive-backlog.md) +#### [SIO_WSK_REGISTER_EXTENSION](sio-wsk-register-extension.md) +#### [SIO_WSK_SET_REMOTE_ADDRESS](sio-wsk-set-remote-address.md) +#### [SIO_WSK_SET_SENDTO_ADDRESS](sio-wsk-set-sendto-address.md) +#### [SIO_WSK_SET_TCP_SILENT_MODE](sio-wsk-set-tcp-silent-mode.md) +### [WSK Socket Options](wsk-socket-options.md) +#### [SO_WSK_EVENT_CALLBACK](so-wsk-event-callback.md) +#### [SO_WSK_SECURITY](so-wsk-security.md) ## [Winsock Kernel Programming Considerations](winsock-kernel-programming-considerations.md) ### [Porting TDI Drivers to Winsock Kernel](porting-tdi-drivers-to-winsock-kernel.md) ### [Sharing Transport Addresses](sharing-transport-addresses.md) @@ -1766,21 +2427,21 @@ ### [Remote NDIS INF Template](remote-ndis-inf-template.md) ### [Types of Remote NDIS Devices](types-of-remote-ndis-devices.md) ## [Remote NDIS Communication](remote-ndis-communication.md) -### [Remote NDIS Control Messages](remote-ndis-control-messages2.md) -#### [REMOTE_NDIS_INITIALIZE_MSG](remote-ndis-initialize-msg2.md) -#### [REMOTE_NDIS_INITIALIZE_CMPLT](remote-ndis-initialize-cmplt2.md) -#### [REMOTE_NDIS_HALT_MSG](remote-ndis-halt-msg2.md) -#### [REMOTE_NDIS_QUERY_MSG](remote-ndis-query-msg2.md) -#### [REMOTE_NDIS_QUERY_CMPLT](remote-ndis-query-cmplt2.md) -#### [REMOTE_NDIS_SET_MSG](remote-ndis-set-msg2.md) -#### [REMOTE_NDIS_SET_CMPLT](remote-ndis-set-cmplt2.md) -#### [REMOTE_NDIS_RESET_MSG](remote-ndis-reset-msg2.md) -#### [REMOTE_NDIS_RESET_CMPLT](remote-ndis-reset-cmplt2.md) -#### [REMOTE_NDIS_INDICATE_STATUS_MSG](remote-ndis-indicate-status-msg2.md) -#### [REMOTE_NDIS_KEEPALIVE_MSG](remote-ndis-keepalive-msg2.md) -#### [REMOTE_NDIS_KEEPALIVE_CMPLT](remote-ndis-keepalive-cmplt2.md) -### [Remote NDIS Data Message](remote-ndis-data-message2.md) -#### [REMOTE_NDIS_PACKET_MSG](remote-ndis-packet-msg2.md) +### [Remote NDIS Control Messages](remote-ndis-control-messages.md) +#### [REMOTE_NDIS_INITIALIZE_MSG](remote-ndis-initialize-msg.md) +#### [REMOTE_NDIS_INITIALIZE_CMPLT](remote-ndis-initialize-cmplt.md) +#### [REMOTE_NDIS_HALT_MSG](remote-ndis-halt-msg.md) +#### [REMOTE_NDIS_QUERY_MSG](remote-ndis-query-msg.md) +#### [REMOTE_NDIS_QUERY_CMPLT](remote-ndis-query-cmplt.md) +#### [REMOTE_NDIS_SET_MSG](remote-ndis-set-msg.md) +#### [REMOTE_NDIS_SET_CMPLT](remote-ndis-set-cmplt.md) +#### [REMOTE_NDIS_RESET_MSG](remote-ndis-reset-msg.md) +#### [REMOTE_NDIS_RESET_CMPLT](remote-ndis-reset-cmplt.md) +#### [REMOTE_NDIS_INDICATE_STATUS_MSG](remote-ndis-indicate-status-msg.md) +#### [REMOTE_NDIS_KEEPALIVE_MSG](remote-ndis-keepalive-msg.md) +#### [REMOTE_NDIS_KEEPALIVE_CMPLT](remote-ndis-keepalive-cmplt.md) +### [Remote NDIS Data Message](remote-ndis-data-message.md) +#### [REMOTE_NDIS_PACKET_MSG](remote-ndis-packet-msg.md) #### [Multipacket Messages](multipacket-messages.md) ### [Setting Device-Specific Parameters](setting-device-specific-parameters.md) ### [Example Connectionless (802.3) Initialization Sequence](example-connectionless--802-3--initialization-sequence.md) @@ -1814,4 +2475,494 @@ #### [Notification Endpoint Descriptor](notification-endpoint-descriptor.md) #### [Interface Descriptor for Data Class Interface](interface-descriptor-for-data-class-interface.md) #### [Data In Endpoint Descriptor](data-in-endpoint-descriptor.md) -#### [Data Out Endpoint Descriptor](data-out-endpoint-descriptor.md) \ No newline at end of file +#### [Data Out Endpoint Descriptor](data-out-endpoint-descriptor.md) +# [SDK Topics for Network Drivers](sdk-topics-for-network-drivers.md) +## [Mstcpip.h](mstcpip-h.md) +### [SIO_LOOPBACK_FAST_PATH control code](sio-loopback-fast-path.md) +### [SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT control code](sio-query-wfp-connection-redirect-context.md) +### [SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS control code](sio-query-wfp-connection-redirect-records.md) +### [SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS control code](sio-set-wfp-connection-redirect-records.md) +## [Ntddndis.h](ntddndis-h.md) +### [GUID_NDIS_GEN_PCI_DEVICE_CUSTOM_PROPERTIES](guid-ndis-gen-pci-device-custom-properties.md) +### [NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE ](ndis-declare-switch-net-buffer-list-context-type.md) +### [NDIS_ISOLATION_PARAMETERS](ndis-isolation-parameters-get-first-routing-domain-entry.md) +### [NDIS_MAKE_NET_LUID macro](ndis-make-net-luid.md) +### [NDIS_ROUTING_DOMAIN_ENTRY_GET_FIRST_ISOLATION_ENTRY macro](ndis-routing-domain-entry-get-first-isolation-entry.md) +### [NDIS_ROUTING_DOMAIN_ENTRY_GET_NEXT macro](ndis-routing-domain-entry-get-next.md) +### [NDIS_ROUTING_DOMAIN_ISOLATION_ENTRY_GET_NEXT macro](ndis-routing-domain-isolation-entry-get-next.md) +### [NDIS_STATUS_ISOLATION_PARAMETERS_CHANGE](ndis-status-isolation-parameters-change.md) +### [NDIS_STATUS_NIC_SWITCH_CURRENT_CAPABILITIES](ndis-status-nic-switch-current-capabilities.md) +### [NDIS_STATUS_NIC_SWITCH_HARDWARE_CAPABILITIES](ndis-status-nic-switch-hardware-capabilities.md) +### [NDIS_STATUS_RECEIVE_FILTER_QUEUE_ALLOCATION_STATE](ndis-status-receive-filter-queue-allocation-state.md) +### [NDIS_STATUS_RECEIVE_FILTER_QUEUE_PARAMETERS](ndis-status-receive-filter-queue-parameters.md) +### [NDIS_STATUS_WWAN_CONTEXT_STATE](ndis-status-wwan-context-state.md) +### [NDIS_STATUS_WWAN_HOME_PROVIDER](ndis-status-wwan-home-provider.md) +### [NDIS_STATUS_WWAN_PACKET_SERVICE](ndis-status-wwan-packet-service.md) +### [NDIS_STATUS_WWAN_PIN_INFO](ndis-status-wwan-pin-info.md) +### [NDIS_STATUS_WWAN_PIN_LIST](ndis-status-wwan-pin-list.md) +### [NDIS_STATUS_WWAN_PREFERRED_PROVIDERS](ndis-status-wwan-preferred-providers.md) +### [NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS](ndis-status-wwan-provisioned-contexts.md) +### [NDIS_STATUS_WWAN_RADIO_STATE](ndis-status-wwan-radio-state.md) +### [NDIS_STATUS_WWAN_READY_INFO](ndis-status-wwan-ready-info.md) +### [NDIS_STATUS_WWAN_REGISTER_STATE](ndis-status-wwan-register-state.md) +### [NDIS_STATUS_WWAN_SERVICE_ACTIVATION](ndis-status-wwan-service-activation.md) +### [NDIS_STATUS_WWAN_SIGNAL_STATE](ndis-status-wwan-signal-state.md) +### [NDIS_STATUS_WWAN_SMS_CONFIGURATION](ndis-status-wwan-sms-configuration.md) +### [NDIS_STATUS_WWAN_SMS_DELETE](ndis-status-wwan-sms-delete.md) +### [NDIS_STATUS_WWAN_SMS_RECEIVE](ndis-status-wwan-sms-receive.md) +### [NDIS_STATUS_WWAN_SMS_SEND](ndis-status-wwan-sms-send.md) +### [NDIS_STATUS_WWAN_SMS_STATUS](ndis-status-wwan-sms-status.md) +### [NDIS_STATUS_WWAN_VENDOR_SPECIFIC](ndis-status-wwan-vendor-specific.md) +### [NDIS_STATUS_WWAN_VISIBLE_PROVIDERS](ndis-status-wwan-visible-providers.md) +### [NDIS_SWITCH_NIC_AT_ARRAY_INDEX macro](ndis-switch-nic-at-array-index.md) +### [NDIS_SWITCH_PORT_AT_ARRAY_INDEX macro](ndis-switch-port-at-array-index.md) +### [NDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN_GET_FIRST_ISOLATION_ENTRY macro](ndis-switch-port-property-routing-domain-get-first-isolation-entry.md) +### [NET_BUFFER_LIST_COALESCED_SEG_COUNT macro](net-buffer-list-coalesced-seg-count.md) +### [NET_BUFFER_LIST_DUP_ACK_COUNT macro](net-buffer-list-dup-ack-count.md) +### [OID_802_3_ADD_MULTICAST_ADDRESS](oid-802-3-add-multicast-address.md) +### [OID_802_3_CURRENT_ADDRESS](oid-802-3-current-address.md) +### [OID_802_3_DELETE_MULTICAST_ADDRESS](oid-802-3-delete-multicast-address.md) +### [OID_802_3_MAC_OPTIONS](oid-802-3-mac-options.md) +### [OID_802_3_MAXIMUM_LIST_SIZE](oid-802-3-maximum-list-size.md) +### [OID_802_3_MULTICAST_LIST](oid-802-3-multicast-list.md) +### [OID_802_3_PERMANENT_ADDRESS](oid-802-3-permanent-address.md) +### [OID_GEN_ADMIN_STATUS](oid-gen-admin-status.md) +### [OID_GEN_ALIAS](oid-gen-alias.md) +### [OID_GEN_BROADCAST_BYTES_RCV](oid-gen-broadcast-bytes-rcv.md) +### [OID_GEN_BROADCAST_BYTES_XMIT](oid-gen-broadcast-bytes-xmit.md) +### [OID_GEN_BROADCAST_FRAMES_RCV](oid-gen-broadcast-frames-rcv.md) +### [OID_GEN_BROADCAST_FRAMES_XMIT](oid-gen-broadcast-frames-xmit.md) +### [OID_GEN_BYTES_RCV](oid-gen-bytes-rcv.md) +### [OID_GEN_BYTES_XMIT](oid-gen-bytes-xmit.md) +### [OID_GEN_CURRENT_LOOKAHEAD](oid-gen-current-lookahead.md) +### [OID_GEN_CURRENT_PACKET_FILTER](oid-gen-current-packet-filter.md) +### [OID_GEN_DEVICE_PROFILE](oid-gen-device-profile.md) +### [OID_GEN_DIRECTED_BYTES_RCV](oid-gen-directed-bytes-rcv.md) +### [OID_GEN_DIRECTED_BYTES_XMIT](oid-gen-directed-bytes-xmit.md) +### [OID_GEN_DIRECTED_FRAMES_RCV](oid-gen-directed-frames-rcv.md) +### [OID_GEN_DIRECTED_FRAMES_XMIT](oid-gen-directed-frames-xmit.md) +### [OID_GEN_DISCONTINUITY_TIME](oid-gen-discontinuity-time.md) +### [OID_GEN_DRIVER_VERSION](oid-gen-driver-version.md) +### [OID_GEN_ENUMERATE_PORTS](oid-gen-enumerate-ports.md) +### [OID_GEN_FRIENDLY_NAME](oid-gen-friendly-name.md) +### [OID_GEN_HARDWARE_STATUS](oid-gen-hardware-status.md) +### [OID_GEN_HD_SPLIT_CURRENT_CONFIG](oid-gen-hd-split-current-config.md) +### [OID_GEN_HD_SPLIT_PARAMETERS](oid-gen-hd-split-parameters.md) +### [OID_GEN_INIT_TIME_MS](oid-gen-init-time-ms.md) +### [OID_GEN_INTERFACE_INFO](oid-gen-interface-info.md) +### [OID_GEN_INTERRUPT_MODERATION](oid-gen-interrupt-moderation.md) +### [OID_GEN_ISOLATION_PARAMETERS](oid-gen-isolation-parameters.md) +### [OID_GEN_LAST_CHANGE](oid-gen-last-change.md) +### [OID_GEN_LINK_PARAMETERS](oid-gen-link-parameters.md) +### [OID_GEN_LINK_SPEED](oid-gen-link-speed.md) +### [OID_GEN_LINK_SPEED_EX](oid-gen-link-speed-ex.md) +### [OID_GEN_LINK_STATE](oid-gen-link-state.md) +### [OID_GEN_MAC_OPTIONS](oid-gen-mac-options.md) +### [OID_GEN_MACHINE_NAME](oid-gen-machine-name.md) +### [OID_GEN_MAX_LINK_SPEED](oid-gen-max-link-speed.md) +### [OID_GEN_MAXIMUM_FRAME_SIZE](oid-gen-maximum-frame-size.md) +### [OID_GEN_MAXIMUM_LOOKAHEAD](oid-gen-maximum-lookahead.md) +### [OID_GEN_MAXIMUM_SEND_PACKETS](oid-gen-maximum-send-packets.md) +### [OID_GEN_MAXIMUM_TOTAL_SIZE](oid-gen-maximum-total-size.md) +### [OID_GEN_MEDIA_CAPABILITIES](oid-gen-media-capabilities.md) +### [OID_GEN_MEDIA_CONNECT_STATUS](oid-gen-media-connect-status.md) +### [OID_GEN_MEDIA_CONNECT_STATUS_EX](oid-gen-media-connect-status-ex.md) +### [OID_GEN_MEDIA_DUPLEX_STATE](oid-gen-media-duplex-state.md) +### [OID_GEN_MEDIA_IN_USE](oid-gen-media-in-use.md) +### [OID_GEN_MEDIA_SENSE_COUNTS](oid-gen-media-sense-counts.md) +### [OID_GEN_MEDIA_SUPPORTED](oid-gen-media-supported.md) +### [OID_GEN_MINIPORT_RESTART_ATTRIBUTES](oid-gen-miniport-restart-attributes.md) +### [OID_GEN_MULTICAST_BYTES_RCV](oid-gen-multicast-bytes-rcv.md) +### [OID_GEN_MULTICAST_BYTES_XMIT](oid-gen-multicast-bytes-xmit.md) +### [OID_GEN_MULTICAST_FRAMES_RCV](oid-gen-multicast-frames-rcv.md) +### [OID_GEN_MULTICAST_FRAMES_XMIT](oid-gen-multicast-frames-xmit.md) +### [OID_GEN_NDIS_RESERVED_1](oid-gen-ndis-reserved-1.md) +### [OID_GEN_NDIS_RESERVED_2](oid-gen-ndis-reserved-2.md) +### [OID_GEN_NDIS_RESERVED_5](oid-gen-ndis-reserved-5.md) +### [OID_GEN_NETWORK_LAYER_ADDRESSES](oid-gen-network-layer-addresses.md) +### [OID_GEN_OPERATIONAL_STATUS](oid-gen-operational-status.md) +### [OID_GEN_PCI_DEVICE_CUSTOM_PROPERTIES](oid-gen-pci-device-custom-properties.md) +### [OID_GEN_PHYSICAL_MEDIUM](oid-gen-physical-medium.md) +### [OID_GEN_PHYSICAL_MEDIUM_EX](oid-gen-physical-medium-ex.md) +### [OID_GEN_PORT_AUTHENTICATION_PARAMETERS](oid-gen-port-authentication-parameters.md) +### [OID_GEN_PORT_STATE](oid-gen-port-state.md) +### [OID_GEN_PROMISCUOUS_MODE](oid-gen-promiscuous-mode.md) +### [OID_GEN_PROTOCOL_OPTIONS](oid-gen-protocol-options.md) +### [OID_GEN_RCV_CRC_ERROR](oid-gen-rcv-crc-error.md) +### [OID_GEN_RCV_DISCARDS](oid-gen-rcv-discards.md) +### [OID_GEN_RCV_ERROR](oid-gen-rcv-error.md) +### [OID_GEN_RCV_LINK_SPEED](oid-gen-rcv-link-speed.md) +### [OID_GEN_RCV_NO_BUFFER](oid-gen-rcv-no-buffer.md) +### [OID_GEN_RCV_OK](oid-gen-rcv-ok.md) +### [OID_GEN_RECEIVE_BLOCK_SIZE](oid-gen-receive-block-size.md) +### [OID_GEN_RECEIVE_BUFFER_SPACE](oid-gen-receive-buffer-space.md) +### [OID_GEN_RECEIVE_HASH](oid-gen-receive-hash.md) +### [OID_GEN_RECEIVE_SCALE_CAPABILITIES](oid-gen-receive-scale-capabilities.md) +### [OID_GEN_RECEIVE_SCALE_PARAMETERS](oid-gen-receive-scale-parameters.md) +### [OID_GEN_RESET_COUNTS](oid-gen-reset-counts.md) +### [OID_GEN_RNDIS_CONFIG_PARAMETER](oid-gen-rndis-config-parameter.md) +### [OID_GEN_STATISTICS](oid-gen-statistics.md) +### [OID_GEN_SUPPORTED_GUIDS](oid-gen-supported-guids.md) +### [OID_GEN_SUPPORTED_LIST](oid-gen-supported-list.md) +### [OID_GEN_SUPPORTED_PACKET_FILTERS](oid-gen-supported-packet-filters.md) +### [OID_GEN_TRANSMIT_BLOCK_SIZE](oid-gen-transmit-block-size.md) +### [OID_GEN_TRANSMIT_BUFFER_SPACE](oid-gen-transmit-buffer-space.md) +### [OID_GEN_TRANSMIT_QUEUE_LENGTH](oid-gen-transmit-queue-length.md) +### [OID_GEN_TRANSPORT_HEADER_OFFSET](oid-gen-transport-header-offset.md) +### [OID_GEN_UNKNOWN_PROTOS](oid-gen-unknown-protos.md) +### [OID_GEN_VENDOR_ID](oid-gen-vendor-id.md) +### [OID_GEN_VLAN_ID](oid-gen-vlan-id.md) +### [OID_GEN_XMIT_DISCARDS](oid-gen-xmit-discards.md) +### [OID_GEN_XMIT_ERROR](oid-gen-xmit-error.md) +### [OID_GEN_XMIT_LINK_SPEED](oid-gen-xmit-link-speed.md) +### [OID_GEN_XMIT_OK](oid-gen-xmit-ok.md) +### [OID_NDK_CONNECTIONS](oid-ndk-connections.md) +### [OID_NDK_LOCAL_ENDPOINTS](oid-ndk-local-endpoints.md) +### [OID_NDK_SET_STATE](oid-ndk-set-state.md) +### [OID_NDK_STATISTICS](oid-ndk-statistics.md) +### [OID_NIC_SWITCH_ALLOCATE_VF](oid-nic-switch-allocate-vf.md) +### [OID_NIC_SWITCH_CREATE_SWITCH](oid-nic-switch-create-switch.md) +### [OID_NIC_SWITCH_CREATE_VPORT](oid-nic-switch-create-vport.md) +### [OID_NIC_SWITCH_CURRENT_CAPABILITIES](oid-nic-switch-current-capabilities.md) +### [OID_NIC_SWITCH_DELETE_SWITCH](oid-nic-switch-delete-switch.md) +### [OID_NIC_SWITCH_DELETE_VPORT](oid-nic-switch-delete-vport.md) +### [OID_NIC_SWITCH_ENUM_SWITCHES](oid-nic-switch-enum-switches.md) +### [OID_NIC_SWITCH_ENUM_VFS](oid-nic-switch-enum-vfs.md) +### [OID_NIC_SWITCH_ENUM_VPORTS](oid-nic-switch-enum-vports.md) +### [OID_NIC_SWITCH_FREE_VF](oid-nic-switch-free-vf.md) +### [OID_NIC_SWITCH_HARDWARE_CAPABILITIES](oid-nic-switch-hardware-capabilities.md) +### [OID_NIC_SWITCH_PARAMETERS](oid-nic-switch-parameters.md) +### [OID_NIC_SWITCH_VF_PARAMETERS](oid-nic-switch-vf-parameters.md) +### [OID_NIC_SWITCH_VPORT_PARAMETERS](oid-nic-switch-vport-parameters.md) +### [OID_PACKET_COALESCING_FILTER_MATCH_COUNT](oid-packet-coalescing-filter-match-count.md) +### [OID_PD_CLOSE_PROVIDER](oid-pd-close-provider.md) +### [OID_PD_OPEN_PROVIDER](oid-pd-open-provider.md) +### [OID_PD_QUERY_CURRENT_CONFIG](oid-pd-query-current-config.md) +### [OID_PM_ADD_PROTOCOL_OFFLOAD](oid-pm-add-protocol-offload.md) +### [OID_PM_ADD_WOL_PATTERN](oid-pm-add-wol-pattern.md) +### [OID_PM_CURRENT_CAPABILITIES](oid-pm-current-capabilities.md) +### [OID_PM_GET_PROTOCOL_OFFLOAD](oid-pm-get-protocol-offload.md) +### [OID_PM_HARDWARE_CAPABILITIES](oid-pm-hardware-capabilities.md) +### [OID_PM_PARAMETERS](oid-pm-parameters.md) +### [OID_PM_PROTOCOL_OFFLOAD_LIST](oid-pm-protocol-offload-list.md) +### [OID_PM_REMOVE_PROTOCOL_OFFLOAD](oid-pm-remove-protocol-offload.md) +### [OID_PM_REMOVE_WOL_PATTERN](oid-pm-remove-wol-pattern.md) +### [OID_PM_WOL_PATTERN_LIST](oid-pm-wol-pattern-list.md) +### [OID_PNP_ADD_WAKE_UP_PATTERN](oid-pnp-add-wake-up-pattern.md) +### [OID_PNP_CAPABILITIES](oid-pnp-capabilities.md) +### [OID_PNP_ENABLE_WAKE_UP](oid-pnp-enable-wake-up.md) +### [OID_PNP_QUERY_POWER](oid-pnp-query-power.md) +### [OID_PNP_REMOVE_WAKE_UP_PATTERN](oid-pnp-remove-wake-up-pattern.md) +### [OID_PNP_SET_POWER](oid-pnp-set-power.md) +### [OID_PNP_WAKE_UP_ERROR](oid-pnp-wake-up-error.md) +### [OID_PNP_WAKE_UP_OK](oid-pnp-wake-up-ok.md) +### [OID_PNP_WAKE_UP_PATTERN_LIST](oid-pnp-wake-up-pattern-list.md) +### [OID_QOS_CURRENT_CAPABILITIES](oid-qos-current-capabilities.md) +### [OID_QOS_HARDWARE_CAPABILITIES](oid-qos-hardware-capabilities.md) +### [OID_QOS_OPERATIONAL_PARAMETERS](oid-qos-operational-parameters.md) +### [OID_QOS_PARAMETERS](oid-qos-parameters.md) +### [OID_QOS_REMOTE_PARAMETERS](oid-qos-remote-parameters.md) +### [OID_RECEIVE_FILTER_ALLOCATE_QUEUE](oid-receive-filter-allocate-queue.md) +### [OID_RECEIVE_FILTER_CLEAR_FILTER](oid-receive-filter-clear-filter.md) +### [OID_RECEIVE_FILTER_CURRENT_CAPABILITIES](oid-receive-filter-current-capabilities.md) +### [OID_RECEIVE_FILTER_ENUM_FILTERS](oid-receive-filter-enum-filters.md) +### [OID_RECEIVE_FILTER_ENUM_QUEUES](oid-receive-filter-enum-queues.md) +### [OID_RECEIVE_FILTER_FREE_QUEUE](oid-receive-filter-free-queue.md) +### [OID_RECEIVE_FILTER_GLOBAL_PARAMETERS](oid-receive-filter-global-parameters.md) +### [OID_RECEIVE_FILTER_HARDWARE_CAPABILITIES](oid-receive-filter-hardware-capabilities.md) +### [OID_RECEIVE_FILTER_MOVE_FILTER](oid-receive-filter-move-filter.md) +### [OID_RECEIVE_FILTER_PARAMETERS](oid-receive-filter-parameters.md) +### [OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE](oid-receive-filter-queue-allocation-complete.md) +### [OID_RECEIVE_FILTER_QUEUE_PARAMETERS](oid-receive-filter-queue-parameters.md) +### [OID_RECEIVE_FILTER_SET_FILTER](oid-receive-filter-set-filter.md) +### [OID_SRIOV_BAR_RESOURCES](oid-sriov-bar-resources.md) +### [OID_SRIOV_CURRENT_CAPABILITIES](oid-sriov-current-capabilities.md) +### [OID_SRIOV_HARDWARE_CAPABILITIES](oid-sriov-hardware-capabilities.md) +### [OID_SRIOV_PF_LUID](oid-sriov-pf-luid.md) +### [OID_SRIOV_PROBED_BARS](oid-sriov-probed-bars.md) +### [OID_SRIOV_READ_VF_CONFIG_BLOCK](oid-sriov-read-vf-config-block.md) +### [OID_SRIOV_READ_VF_CONFIG_SPACE](oid-sriov-read-vf-config-space.md) +### [OID_SRIOV_RESET_VF](oid-sriov-reset-vf.md) +### [OID_SRIOV_SET_VF_POWER_STATE](oid-sriov-set-vf-power-state.md) +### [OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK](oid-sriov-vf-invalidate-config-block.md) +### [OID_SRIOV_VF_SERIAL_NUMBER](oid-sriov-vf-serial-number.md) +### [OID_SRIOV_VF_VENDOR_DEVICE_ID](oid-sriov-vf-vendor-device-id.md) +### [OID_SRIOV_WRITE_VF_CONFIG_BLOCK](oid-sriov-write-vf-config-block.md) +### [OID_SRIOV_WRITE_VF_CONFIG_SPACE](oid-sriov-write-vf-config-space.md) +### [OID_SWITCH_FEATURE_STATUS_QUERY](oid-switch-feature-status-query.md) +### [OID_SWITCH_NIC_ARRAY](oid-switch-nic-array.md) +### [OID_SWITCH_NIC_CONNECT](oid-switch-nic-connect.md) +### [OID_SWITCH_NIC_CREATE](oid-switch-nic-create.md) +### [OID_SWITCH_NIC_DELETE](oid-switch-nic-delete.md) +### [OID_SWITCH_NIC_DISCONNECT](oid-switch-nic-disconnect.md) +### [OID_SWITCH_NIC_REQUEST](oid-switch-nic-request.md) +### [OID_SWITCH_NIC_RESTORE](oid-switch-nic-restore.md) +### [OID_SWITCH_NIC_RESTORE_COMPLETE](oid-switch-nic-restore-complete.md) +### [OID_SWITCH_NIC_SAVE](oid-switch-nic-save.md) +### [OID_SWITCH_NIC_SAVE_COMPLETE](oid-switch-nic-save-complete.md) +### [OID_SWITCH_NIC_UPDATED](oid-switch-nic-updated.md) +### [OID_SWITCH_PARAMETERS](oid-switch-parameters.md) +### [OID_SWITCH_PORT_ARRAY](oid-switch-port-array.md) +### [OID_SWITCH_PORT_CREATE](oid-switch-port-create.md) +### [OID_SWITCH_PORT_DELETE](oid-switch-port-delete.md) +### [OID_SWITCH_PORT_FEATURE_STATUS_QUERY](oid-switch-port-feature-status-query.md) +### [OID_SWITCH_PORT_PROPERTY_ADD](oid-switch-port-property-add.md) +### [OID_SWITCH_PORT_PROPERTY_DELETE](oid-switch-port-property-delete.md) +### [OID_SWITCH_PORT_PROPERTY_ENUM](oid-switch-port-property-enum.md) +### [OID_SWITCH_PORT_PROPERTY_UPDATE](oid-switch-port-property-update.md) +### [OID_SWITCH_PORT_TEARDOWN](oid-switch-port-teardown.md) +### [OID_SWITCH_PORT_UPDATED](oid-switch-port-updated.md) +### [OID_SWITCH_PROPERTY_ADD](oid-switch-property-add.md) +### [OID_SWITCH_PROPERTY_DELETE](oid-switch-property-delete.md) +### [OID_SWITCH_PROPERTY_ENUM](oid-switch-property-enum.md) +### [OID_SWITCH_PROPERTY_UPDATE](oid-switch-property-update.md) +### [OID_TCP_RSC_STATISTICS](oid-tcp-rsc-statistics.md) +### [OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA](oid-tcp-task-ipsec-offload-v2-add-sa.md) +### [OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA_EX](oid-tcp-task-ipsec-offload-v2-add-sa-ex.md) +### [OID_TCP_TASK_IPSEC_OFFLOAD_V2_DELETE_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) +### [OID_TCP_TASK_IPSEC_OFFLOAD_V2_UPDATE_SA](oid-tcp-task-ipsec-offload-v2-update-sa.md) +### [OID_WAN_CO_GET_COMP_INFO](oid-wan-co-get-comp-info.md) +### [OID_WAN_CO_GET_INFO](oid-wan-co-get-info.md) +### [OID_WAN_CO_GET_LINK_INFO](oid-wan-co-get-link-info.md) +### [OID_WAN_CO_GET_STATS_INFO](oid-wan-co-get-stats-info.md) +### [OID_WAN_CO_SET_COMP_INFO](oid-wan-co-set-comp-info.md) +### [OID_WAN_CO_SET_LINK_INFO](oid-wan-co-set-link-info.md) +### [OID_WWAN_AUTH_CHALLENGE](oid-wwan-auth-challenge.md) +### [OID_WWAN_CONNECT](oid-wwan-connect.md) +### [OID_WWAN_CREATE_MAC](oid-wwan-create-mac.md) +### [OID_WWAN_DELETE_MAC](oid-wwan-delete-mac.md) +### [OID_WWAN_DEVICE_CAPS](oid-wwan-device-caps.md) +### [OID_WWAN_DEVICE_CAPS_EX](oid-wwan-device-caps-ex.md) +### [OID_WWAN_DEVICE_SERVICE_COMMAND](oid-wwan-device-service-command.md) +### [OID_WWAN_DEVICE_SERVICE_SESSION](oid-wwan-device-service-session.md) +### [OID_WWAN_DEVICE_SERVICE_SESSION_WRITE](oid-wwan-device-service-session-write.md) +### [OID_WWAN_DEVICE_SERVICES](oid-wwan-device-services.md) +### [OID_WWAN_DEVICE_SLOT_MAPPING_INFO](oid-wwan-device-slot-mappings.md) +### [OID_WWAN_DRIVER_CAPS](oid-wwan-driver-caps.md) +### [OID_WWAN_ENUMERATE_DEVICE_SERVICE_COMMANDS](oid-wwan-enumerate-device-service-commands.md) +### [OID_WWAN_ENUMERATE_DEVICE_SERVICES](oid-wwan-enumerate-device-services.md) +### [OID_WWAN_HOME_PROVIDER](oid-wwan-home-provider.md) +### [OID_WWAN_NETWORK_IDLE_HINT](oid-wwan-network-idle-hint.md) +### [OID_WWAN_PACKET_SERVICE](oid-wwan-packet-service.md) +### [OID_WWAN_PIN](oid-wwan-pin.md) +### [OID_WWAN_PIN_EX](oid-wwan-pin-ex.md) +### [OID_WWAN_PIN_LIST](oid-wwan-pin-list.md) +### [OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS](oid-wwan-preferred-multicarrier-providers.md) +### [OID_WWAN_PREFERRED_PROVIDERS](oid-wwan-preferred-providers.md) +### [OID_WWAN_PRESHUTDOWN](oid-wwan-preshutdown.md) +### [OID_WWAN_PROVISIONED_CONTEXTS](oid-wwan-provisioned-contexts.md) +### [OID_WWAN_RADIO_STATE](oid-wwan-radio-state.md) +### [OID_WWAN_READY_INFO](oid-wwan-ready-info.md) +### [OID_WWAN_REGISTER_STATE](oid-wwan-register-state.md) +### [OID_WWAN_SERVICE_ACTIVATION](oid-wwan-service-activation.md) +### [OID_WWAN_SIGNAL_STATE](oid-wwan-signal-state.md) +### [OID_WWAN_SLOT_INFO](oid-wwan-slot-info-status.md) +### [OID_WWAN_SMS_CONFIGURATION](oid-wwan-sms-configuration.md) +### [OID_WWAN_SMS_DELETE](oid-wwan-sms-delete.md) +### [OID_WWAN_SMS_READ](oid-wwan-sms-read.md) +### [OID_WWAN_SMS_SEND](oid-wwan-sms-send.md) +### [OID_WWAN_SMS_STATUS](oid-wwan-sms-status.md) +### [OID_WWAN_SUBSCRIBE_DEVICE_SERVICE_EVENTS](oid-wwan-subscribe-device-service-events.md) +### [OID_WWAN_SYS_CAPS_INFO](oid-wwan-sys-caps.md) +### [OID_WWAN_USSD](oid-wwan-ussd.md) +### [OID_WWAN_VENDOR_SPECIFIC](oid-wwan-vendor-specific.md) +### [OID_WWAN_VISIBLE_PROVIDERS](oid-wwan-visible-providers.md) +## [Windot11.h](windot11-h.md) +### [DOT11_COUNTRY_OR_REGION_STRING](dot11-country-or-region-string.md) +### [DOT11_COUNTRY_STRING](dot11-country-string.md) +### [DOT11_PMKID_VALUE](dot11-pmkid-value.md) +### [NDIS_STATUS_DOT11_ASSOCIATION_COMPLETION](ndis-status-dot11-association-completion.md) +### [NDIS_STATUS_DOT11_ASSOCIATION_START](ndis-status-dot11-association-start.md) +### [NDIS_STATUS_DOT11_CAN_SUSTAIN_AP](ndis-status-dot11-can-sustain-ap.md) +### [NDIS_STATUS_DOT11_CONNECTION_COMPLETION](ndis-status-dot11-connection-completion.md) +### [NDIS_STATUS_DOT11_CONNECTION_START](ndis-status-dot11-connection-start.md) +### [NDIS_STATUS_DOT11_DISASSOCIATION](ndis-status-dot11-disassociation.md) +### [NDIS_STATUS_DOT11_INCOMING_ASSOC_COMPLETION](ndis-status-dot11-incoming-assoc-completion.md) +### [NDIS_STATUS_DOT11_INCOMING_ASSOC_REQUEST_RECEIVED](ndis-status-dot11-incoming-assoc-request-received.md) +### [NDIS_STATUS_DOT11_INCOMING_ASSOC_STARTED](ndis-status-dot11-incoming-assoc-started.md) +### [NDIS_STATUS_DOT11_LINK_QUALITY](ndis-status-dot11-link-quality.md) +### [NDIS_STATUS_DOT11_MPDU_MAX_LENGTH_CHANGED](ndis-status-dot11-mpdu-max-length-changed.md) +### [NDIS_STATUS_DOT11_PHY_FREQUENCY_ADOPTED](ndis-status-dot11-phy-frequency-adopted.md) +### [NDIS_STATUS_DOT11_PHY_STATE_CHANGED](ndis-status-dot11-phy-state-changed.md) +### [NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST](ndis-status-dot11-pmkid-candidate-list.md) +### [NDIS_STATUS_DOT11_ROAMING_COMPLETION](ndis-status-dot11-roaming-completion.md) +### [NDIS_STATUS_DOT11_ROAMING_START](ndis-status-dot11-roaming-start.md) +### [NDIS_STATUS_DOT11_SCAN_CONFIRM](ndis-status-dot11-scan-confirm.md) +### [NDIS_STATUS_DOT11_STOP_AP](ndis-status-dot11-stop-ap.md) +### [NDIS_STATUS_DOT11_TKIPMIC_FAILURE](ndis-status-dot11-tkipmic-failure.md) +### [OID_DOT11_ACTIVE_PHY_LIST](oid-dot11-active-phy-list.md) +### [OID_DOT11_ADDITIONAL_IE](oid-dot11-additional-ie.md) +### [OID_DOT11_ASSOCIATION_PARAMS](oid-dot11-association-params.md) +### [OID_DOT11_ATIM_WINDOW](oid-dot11-atim-window.md) +### [OID_DOT11_AUTO_CONFIG_ENABLED](oid-dot11-auto-config-enabled.md) +### [OID_DOT11_AVAILABLE_CHANNEL_LIST](oid-dot11-available-channel-list.md) +### [OID_DOT11_AVAILABLE_FREQUENCY_LIST](oid-dot11-available-frequency-list.md) +### [OID_DOT11_BEACON_PERIOD](oid-dot11-beacon-period.md) +### [OID_DOT11_CCA_MODE_SUPPORTED](oid-dot11-cca-mode-supported.md) +### [OID_DOT11_CCA_WATCHDOG_COUNT_MAX](oid-dot11-cca-watchdog-count-max.md) +### [OID_DOT11_CCA_WATCHDOG_COUNT_MIN](oid-dot11-cca-watchdog-count-min.md) +### [OID_DOT11_CCA_WATCHDOG_TIMER_MAX](oid-dot11-cca-watchdog-timer-max.md) +### [OID_DOT11_CCA_WATCHDOG_TIMER_MIN](oid-dot11-cca-watchdog-timer-min.md) +### [OID_DOT11_CF_POLLABLE](oid-dot11-cf-pollable.md) +### [OID_DOT11_CHANNEL_AGILITY_ENABLED](oid-dot11-channel-agility-enabled.md) +### [OID_DOT11_CHANNEL_AGILITY_PRESENT](oid-dot11-channel-agility-present.md) +### [OID_DOT11_CIPHER_DEFAULT_KEY](oid-dot11-cipher-default-key.md) +### [OID_DOT11_CIPHER_DEFAULT_KEY_ID](oid-dot11-cipher-default-key-id.md) +### [OID_DOT11_CIPHER_KEY_MAPPING_KEY](oid-dot11-cipher-key-mapping-key.md) +### [OID_DOT11_CONNECT_REQUEST](oid-dot11-connect-request.md) +### [OID_DOT11_COUNTRY_STRING](oid-dot11-country-string.md) +### [OID_DOT11_CREATE_MAC](oid-dot11-create-mac.md) +### [OID_DOT11_CURRENT_ADDRESS](oid-dot11-current-address.md) +### [OID_DOT11_CURRENT_CCA_MODE](oid-dot11-current-cca-mode.md) +### [OID_DOT11_CURRENT_CHANNEL](oid-dot11-current-channel.md) +### [OID_DOT11_CURRENT_CHANNEL_NUMBER](oid-dot11-current-channel-number.md) +### [OID_DOT11_CURRENT_DWELL_TIME](oid-dot11-current-dwell-time.md) +### [OID_DOT11_CURRENT_FREQUENCY](oid-dot11-current-frequency.md) +### [OID_DOT11_CURRENT_INDEX](oid-dot11-current-index.md) +### [OID_DOT11_CURRENT_OPERATION_MODE](oid-dot11-current-operation-mode.md) +### [OID_DOT11_CURRENT_OPTIONAL_CAPABILITY](oid-dot11-current-optional-capability.md) +### [OID_DOT11_CURRENT_PATTERN](oid-dot11-current-pattern.md) +### [OID_DOT11_CURRENT_PHY_ID](oid-dot11-current-phy-id.md) +### [OID_DOT11_CURRENT_REG_DOMAIN](oid-dot11-current-reg-domain.md) +### [OID_DOT11_CURRENT_SET](oid-dot11-current-set.md) +### [OID_DOT11_CURRENT_TX_POWER_LEVEL](oid-dot11-current-tx-power-level.md) +### [OID_DOT11_DATA_RATE_MAPPING_TABLE](oid-dot11-data-rate-mapping-table.md) +### [OID_DOT11_DELETE_MAC](oid-dot11-delete-mac.md) +### [OID_DOT11_DESIRED_BSS_TYPE](oid-dot11-desired-bss-type.md) +### [OID_DOT11_DESIRED_BSSID_LIST](oid-dot11-desired-bssid-list.md) +### [OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING](oid-dot11-desired-country-or-region-string.md) +### [OID_DOT11_DESIRED_PHY_LIST](oid-dot11-desired-phy-list.md) +### [OID_DOT11_DESIRED_SSID_LIST](oid-dot11-desired-ssid-list.md) +### [OID_DOT11_DISASSOCIATE_PEER_REQUEST](oid-dot11-disassociate-peer-request.md) +### [OID_DOT11_DISCONNECT_REQUEST](oid-dot11-disconnect-request.md) +### [OID_DOT11_DIVERSITY_SELECTION_RX](oid-dot11-diversity-selection-rx.md) +### [OID_DOT11_DIVERSITY_SUPPORT](oid-dot11-diversity-support.md) +### [OID_DOT11_DSSS_OFDM_OPTION_ENABLED](oid-dot11-dsss-ofdm-option-enabled.md) +### [OID_DOT11_DSSS_OFDM_OPTION_IMPLEMENTED](oid-dot11-dsss-ofdm-option-implemented.md) +### [OID_DOT11_DTIM_PERIOD](oid-dot11-dtim-period.md) +### [OID_DOT11_ED_THRESHOLD](oid-dot11-ed-threshold.md) +### [OID_DOT11_EHCC_CAPABILITY_ENABLED](oid-dot11-ehcc-capability-enabled.md) +### [OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED](oid-dot11-ehcc-capability-implemented.md) +### [OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX](oid-dot11-ehcc-number-of-channels-family-index.md) +### [OID_DOT11_EHCC_PRIME_RADIX](oid-dot11-ehcc-prime-radix.md) +### [OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md) +### [OID_DOT11_ENABLED_MULTICAST_CIPHER_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md) +### [OID_DOT11_ENABLED_UNICAST_CIPHER_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md) +### [OID_DOT11_ENUM_ASSOCIATION_INFO](oid-dot11-enum-association-info.md) +### [OID_DOT11_ENUM_BSS_LIST](oid-dot11-enum-bss-list.md) +### [OID_DOT11_ENUM_PEER_INFO](oid-dot11-enum-peer-info.md) +### [OID_DOT11_ERP_PBCC_OPTION_ENABLED](oid-dot11-erp-pbcc-option-enabled.md) +### [OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED](oid-dot11-erp-pbcc-option-implemented.md) +### [OID_DOT11_EXCLUDE_UNENCRYPTED](oid-dot11-exclude-unencrypted.md) +### [OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST](oid-dot11-excluded-mac-address-list.md) +### [OID_DOT11_EXTSTA_CAPABILITY](oid-dot11-extsta-capability.md) +### [OID_DOT11_FLUSH_BSS_LIST](oid-dot11-flush-bss-list.md) +### [OID_DOT11_FRAGMENTATION_THRESHOLD](oid-dot11-fragmentation-threshold.md) +### [OID_DOT11_FREQUENCY_BANDS_SUPPORTED](oid-dot11-frequency-bands-supported.md) +### [OID_DOT11_HARDWARE_PHY_STATE](oid-dot11-hardware-phy-state.md) +### [OID_DOT11_HIDDEN_NETWORK_ENABLED](oid-dot11-hidden-network-enabled.md) +### [OID_DOT11_HOP_ALGORITHM_ADOPTED](oid-dot11-hop-algorithm-adopted.md) +### [OID_DOT11_HOP_MODULUS](oid-dot11-hop-modulus.md) +### [OID_DOT11_HOP_OFFSET](oid-dot11-hop-offset.md) +### [OID_DOT11_HOP_TIME](oid-dot11-hop-time.md) +### [OID_DOT11_HOPPING_PATTERN](oid-dot11-hopping-pattern.md) +### [OID_DOT11_HR_CCA_MODE_SUPPORTED](oid-dot11-hr-cca-mode-supported.md) +### [OID_DOT11_IBSS_PARAMS](oid-dot11-ibss-params.md) +### [OID_DOT11_INCOMING_ASSOCIATION_DECISION](oid-dot11-incoming-association-decision.md) +### [OID_DOT11_LONG_RETRY_LIMIT](oid-dot11-long-retry-limit.md) +### [OID_DOT11_MAC_ADDRESS](oid-dot11-mac-address.md) +### [OID_DOT11_MAX_DWELL_TIME](oid-dot11-max-dwell-time.md) +### [OID_DOT11_MAX_RECEIVE_LIFETIME](oid-dot11-max-receive-lifetime.md) +### [OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME](oid-dot11-max-transmit-msdu-lifetime.md) +### [OID_DOT11_MAXIMUM_LIST_SIZE](oid-dot11-maximum-list-size.md) +### [OID_DOT11_MEDIA_STREAMING_ENABLED](oid-dot11-media-streaming-enabled.md) +### [OID_DOT11_MPDU_MAX_LENGTH](oid-dot11-mpdu-max-length.md) +### [OID_DOT11_MULTI_DOMAIN_CAPABILITY](oid-dot11-multi-domain-capability.md) +### [OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED](oid-dot11-multi-domain-capability-enabled.md) +### [OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md) +### [OID_DOT11_MULTICAST_LIST](oid-dot11-multicast-list.md) +### [OID_DOT11_NIC_POWER_STATE](oid-dot11-nic-power-state.md) +### [OID_DOT11_NIC_SPECIFIC_EXTENSION](oid-dot11-nic-specific-extension.md) +### [OID_DOT11_NUMBER_OF_HOPPING_SETS](oid-dot11-number-of-hopping-sets.md) +### [OID_DOT11_OFFLOAD_NETWORK_LIST](oid-dot11-offload-network-list.md) +### [OID_DOT11_OPERATION_MODE_CAPABILITY](oid-dot11-operation-mode-capability.md) +### [OID_DOT11_OPERATIONAL_RATE_SET](oid-dot11-operational-rate-set.md) +### [OID_DOT11_OPTIONAL_CAPABILITY](oid-dot11-optional-capability.md) +### [OID_DOT11_PBCC_OPTION_IMPLEMENTED](oid-dot11-pbcc-option-implemented.md) +### [OID_DOT11_PERMANENT_ADDRESS](oid-dot11-permanent-address.md) +### [OID_DOT11_PMKID_LIST](oid-dot11-pmkid-list.md) +### [OID_DOT11_PORT_STATE_NOTIFICATION](oid-dot11-port-state-notification.md) +### [OID_DOT11_POWER_MGMT_MODE_AUTO_ENABLED](oid-dot11-powermgmt-mode-auto-enabled.md) +### [OID_DOT11_POWER_MGMT_MODE_STATUS](oid-dot11-power-mgmt-mode-status.md) +### [OID_DOT11_POWER_MGMT_REQUEST](oid-dot11-power-mgmt-request.md) +### [OID_DOT11_PREFERRED_MAC](oid-dot11-preferred-mac.md) +### [OID_DOT11_PRIVACY_EXEMPTION_LIST](oid-dot11-privacy-exemption-list.md) +### [OID_DOT11_QOS_PARAMS](oid-dot11-qos-params.md) +### [OID_DOT11_RANDOM_TABLE_FLAG](oid-dot11-random-table-flag.md) +### [OID_DOT11_RECV_SENSITIVITY_LIST](oid-dot11-recv-sensitivity-list.md) +### [OID_DOT11_REG_DOMAINS_SUPPORT_VALUE](oid-dot11-reg-domains-support-value.md) +### [OID_DOT11_RESET_REQUEST](oid-dot11-reset-request.md) +### [OID_DOT11_RF_USAGE](oid-dot11-rf-usage.md) +### [OID_DOT11_RTS_THRESHOLD](oid-dot11-rts-threshold.md) +### [OID_DOT11_SAFE_MODE_ENABLED](oid-dot11-safe-mode-enabled.md) +### [OID_DOT11_SAFE_MODE_HT_ENABLED](oid-dot11-safe-mode-ht-enabled.md) +### [OID_DOT11_SCAN_REQUEST](oid-dot11-scan-request.md) +### [OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED](oid-dot11-short-preamble-option-implemented.md) +### [OID_DOT11_SHORT_RETRY_LIMIT](oid-dot11-short-retry-limit.md) +### [OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED](oid-dot11-short-slot-time-option-enabled.md) +### [OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED](oid-dot11-short-slot-time-option-implemented.md) +### [OID_DOT11_START_AP_REQUEST](oid-dot11-start-ap-request.md) +### [OID_DOT11_STATION_ID](oid-dot11-station-id.md) +### [OID_DOT11_STATISTICS](oid-dot11-statistics.md) +### [OID_DOT11_SUPPORTED_COUNTRY_OR_REGION_STRING](oid-dot11-supported-country-or-region-string.md) +### [OID_DOT11_SUPPORTED_DATA_RATES_VALUE](oid-dot11-supported-data-rates-value.md) +### [OID_DOT11_SUPPORTED_DSSS_CHANNEL_LIST](oid-dot11-supported-dsss-channel-list.md) +### [OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) +### [OID_DOT11_SUPPORTED_OFDM_FREQUENCY_LIST](oid-dot11-supported-ofdm-frequency-list.md) +### [OID_DOT11_SUPPORTED_PHY_TYPES](oid-dot11-supported-phy-types.md) +### [OID_DOT11_SUPPORTED_POWER_LEVELS](oid-dot11-supported-power-levels.md) +### [OID_DOT11_SUPPORTED_RX_ANTENNA](oid-dot11-supported-rx-antenna.md) +### [OID_DOT11_SUPPORTED_TX_ANTENNA](oid-dot11-supported-tx-antenna.md) +### [OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) +### [OID_DOT11_TEMP_TYPE](oid-dot11-temp-type.md) +### [OID_DOT11_TI_THRESHOLD](oid-dot11-ti-threshold.md) +### [OID_DOT11_UNICAST_USE_GROUP_ENABLED](oid-dot11-unicast-use-group-enabled.md) +### [OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD](oid-dot11-unreachable-detection-threshold.md) +### [OID_DOT11_VIRTUAL_STATION_CAPABILITY](oid-dot11-virtual-station-capability.md) +### [OID_DOT11_WFD_ADDITIONAL_IE](oid-dot11-wfd-additional-ie.md) +### [OID_DOT11_WFD_CONNECT_TO_GROUP_REQUEST](-oid-dot11-wfd-connect-to-group-request.md) +### [OID_DOT11_WFD_DESIRED_GROUP_ID](oid-dot11-wfd-desired-group-id.md) +### [OID_DOT11_WFD_DEVICE_CAPABILITY](oid-dot11-wfd-device-capability.md) +### [OID_DOT11_WFD_DEVICE_INFO](oid-dot11-wfd-device-info.md) +### [OID_DOT11_WFD_DEVICE_LISTEN_CHANNEL](oid-dot11-wfd-device-listen-channel.md) +### [OID_DOT11_WFD_DISCONNECT_FROM_GROUP_REQUEST](oid-dot11-wfd-disconnect-from-group-request.md) +### [OID_DOT11_WFD_DISCOVER_REQUEST](oid-dot11-wfd-discover-request.md) +### [OID_DOT11_WFD_ENUM_DEVICE_LIST](oid-dot11-wfd-enum-device-list.md) +### [OID_DOT11_WFD_FLUSH_DEVICE_LIST](oid-dot11-wfd-flush-device-list.md) +### [OID_DOT11_WFD_GET_DIALOG_TOKEN](oid-dot11-wfd-get-dialog-token.md) +### [OID_DOT11_WFD_GROUP_JOIN_PARAMETERS](-oid-dot11-wfd-group-join-parameters.md) +### [OID_DOT11_WFD_GROUP_OWNER_CAPABILITY](oid-dot11-wfd-group-owner-capability.md) +### [OID_DOT11_WFD_GROUP_START_PARAMETERS](oid-dot11-wfd-group-start-parameters.md) +### [OID_DOT11_WFD_LISTEN_STATE_DISCOVERABILITY](oid-dot11-wfd-listen-state-discoverability.md) +### [OID_DOT11_WFD_SECONDARY_DEVICE_TYPE_LIST](oid-dot11-wfd-secondary-device-type-list.md) +### [OID_DOT11_WFD_SEND_GO_NEGOTIATION_CONFIRMATION](oid-dot11-wfd-send-go-negotiation-confirmation.md) +### [OID_DOT11_WFD_SEND_GO_NEGOTIATION_REQUEST](oid-dot11-wfd-send-go-negotiation-request.md) +### [OID_DOT11_WFD_SEND_GO_NEGOTIATION_RESPONSE](oid-dot11-wfd-send-go-negotiation-response.md) +### [OID_DOT11_WFD_SEND_INVITATION_REQUEST](oid-dot11-wfd-send-invitation-request.md) +### [OID_DOT11_WFD_SEND_INVITATION_RESPONSE](oid-dot11-wfd-send-invitation-response.md) +### [OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_REQUEST](-oid-dot11-wfd-send-provision-discovery-request.md) +### [OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_RESPONSE](oid-dot11-wfd-send-provision-discovery-response.md) +### [OID_DOT11_WFD_START_GO_REQUEST](oid-dot11-wfd-start-go-request.md) +### [OID_DOT11_WFD_STOP_DISCOVERY](oid-dot11-wfd-stop-discovery.md) +### [OID_DOT11_WPS_ENABLED](oid-dot11-wps-enabled.md) +## [Ws2def.h](ws2def-h.md) +### [AF_INET](af-inet.md) +### [AF_INET6](af-inet6.md) +### [SIO_ADDRESS_LIST_CHANGE](sio-address-list-change.md) +### [SIO_ADDRESS_LIST_QUERY](sio-address-list-query.md) +### [SO_BROADCAST](so-broadcast.md) +### [SO_CONDITIONAL_ACCEPT](so-conditional-accept.md) +### [SO_EXCLUSIVEADDRUSE](so-exclusiveaddruse.md) +### [SO_KEEPALIVE](so-keepalive.md) +### [SO_RCVBUF](so-rcvbuf.md) +### [SO_REUSEADDR](so-reuseaddr.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/network/accessing-net-buffer-list-information-in-ipsec-offload-version-2.md b/windows-driver-docs-pr/network/accessing-net-buffer-list-information-in-ipsec-offload-version-2.md index d6d8036b66..65c0ff8cc4 100644 --- a/windows-driver-docs-pr/network/accessing-net-buffer-list-information-in-ipsec-offload-version-2.md +++ b/windows-driver-docs-pr/network/accessing-net-buffer-list-information-in-ipsec-offload-version-2.md @@ -1,6 +1,6 @@ --- title: Accessing NET_BUFFER_LIST information in IPsec Offload Version 2 -description: Accessing NET\_BUFFER\_LIST Information in IPsec Offload Version 2 +description: Accessing NET_BUFFER_LIST Information in IPsec Offload Version 2 ms.assetid: 0c27b594-2c61-4459-96df-1d7445100bc5 keywords: - IPsecOV2 WDK TCP/IP transport , NET_BUFFER_LIST information diff --git a/windows-driver-docs-pr/network/accessing-tcp-ip-offload-net-buffer-list-information.md b/windows-driver-docs-pr/network/accessing-tcp-ip-offload-net-buffer-list-information.md index d6f9a228a9..05b1b25ed3 100644 --- a/windows-driver-docs-pr/network/accessing-tcp-ip-offload-net-buffer-list-information.md +++ b/windows-driver-docs-pr/network/accessing-tcp-ip-offload-net-buffer-list-information.md @@ -1,6 +1,6 @@ --- -title: Accessing TCP/IP Offload NET\_BUFFER\_LIST Information -description: Accessing TCP/IP Offload NET\_BUFFER\_LIST Information +title: Accessing TCP/IP Offload NET_BUFFER_LIST Information +description: Accessing TCP/IP Offload NET_BUFFER_LIST Information ms.assetid: 555c9533-ab3f-43f0-9139-b1de33a6b1a7 keywords: - TCP/IP offload WDK networking , out-of-band data diff --git a/windows-driver-docs-pr/network/af-inet.md b/windows-driver-docs-pr/network/af-inet.md new file mode 100644 index 0000000000..eceab264be --- /dev/null +++ b/windows-driver-docs-pr/network/af-inet.md @@ -0,0 +1,157 @@ +--- +title: AF\_INET +author: windows-driver-content +description: AF\_INET +ms.assetid: 59e12f8d-02eb-413c-bc04-6b9b6e4adde6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -AF_INET Network Drivers Starting with Windows Vista +--- + +# AF\_INET + + +The AF\_INET address family is the address family for IPv4. + +### Socket Address Structure + +An IPv4 transport address is specified with the [**SOCKADDR\_IN**](https://msdn.microsoft.com/library/windows/hardware/ff570823) structure. + +### Socket Types + +IPv4 supports the following socket types: + +SOCK\_STREAM +Supports reliable connection-oriented byte stream communication. + +SOCK\_DGRAM +Supports unreliable connectionless datagram communication. + +SOCK\_RAW +Supports raw access to the transport protocol. + +A WSK application specifies a socket type when it calls the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149) function or the [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150) function to create a new socket. + +### Protocols + +The following IPv4 IPPROTO\_*XXX* protocol values of the IPPROTO enumeration are defined in the WSK header files: + +IPPROTO\_IP +Internet protocol options + +IPPROTO\_ICMP +Internet control message protocol + +IPPROTO\_IGMP +Internet group management protocol + +IPPROTO\_GGP +Gateway to gateway protocol + +IPPROTO\_IPV4 +IPv4 encapsulation + +IPPROTO\_ST +Stream protocol + +IPPROTO\_TCP +Transmission control protocol + +IPPROTO\_CBT +Core based trees protocol + +IPPROTO\_EGP +Exterior gateway protocol + +IPPROTO\_IGP +Private interior gateway protocol + +IPPROTO\_PUP +PARC universal packet protocol + +IPPROTO\_UDP +User datagram protocol + +IPPROTO\_IDP +Internet datagram protocol + +IPPROTO\_RDP +Reliable data protocol + +IPPROTO\_ND +Net disk protocol + +IPPROTO\_ICLFXBM +Wideband monitoring + +IPPROTO\_PIM +Protocol independent multicast + +IPPROTO\_PGM +Pragmatic general multicast + +IPPROTO\_L2TP +Level 2 tunneling protocol + +IPPROTO\_SCTP +Stream control transmission protocol + +IPPROTO\_RAW +Raw IP packets + +Additional protocols are supported through the use of raw sockets. + +A WSK application specifies a protocol when it calls the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149) function or the [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150) function to create a new socket. + +A WSK application also specifies a protocol (as the *Level* parameter) when it calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function to set or retrieve transport protocol level or network protocol level socket options. + +### Combinations + +IPv4 supports the following combinations of socket types and protocols for each WSK [socket category](https://msdn.microsoft.com/library/windows/hardware/ff571093): + +Basic Sockets +SOCK\_STREAM + IPPROTO\_TCP +SOCK\_DGRAM + IPPROTO\_UDP +SOCK\_RAW + IPPROTO\_*Xxx* +Listening Sockets +SOCK\_STREAM + IPPROTO\_TCP + +Datagram Sockets +SOCK\_DGRAM + IPPROTO\_UDP +SOCK\_RAW + IPPROTO\_*Xxx* +Connection-Oriented Sockets +SOCK\_STREAM + IPPROTO\_TCP + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20AF_INET%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/af-inet6.md b/windows-driver-docs-pr/network/af-inet6.md new file mode 100644 index 0000000000..bd2b74df21 --- /dev/null +++ b/windows-driver-docs-pr/network/af-inet6.md @@ -0,0 +1,181 @@ +--- +title: AF\_INET6 +author: windows-driver-content +description: AF\_INET6 +ms.assetid: 58d36a1e-cda2-42aa-9563-96df2f7319b2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -AF_INET6 Network Drivers Starting with Windows Vista +--- + +# AF\_INET6 + + +The AF\_INET6 address family is the address family for IPv6. + +### Socket Address Structure + +An IPv6 transport address is specified with the [**SOCKADDR\_IN6**](https://msdn.microsoft.com/library/windows/hardware/ff570824) structure. + +### Socket Types + +IPv6 supports the following socket types: + +SOCK\_STREAM +Supports reliable connection-oriented byte stream communication. + +SOCK\_DGRAM +Supports unreliable connectionless datagram communication. + +SOCK\_RAW +Supports raw access to the transport protocol. + +A WSK application specifies a socket type when it calls the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149) function or the [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150) function to create a new socket. + +### Protocols + +The following IPv6 IPPROTO\_*XXX* protocol values of the IPPROTO enumeration are defined in the WSK header files: + +IPPROTO\_HOPOPTS +IPv6 hop-by-hop options + +IPPROTO\_ICMP +Internet control message protocol + +IPPROTO\_IGMP +Internet group management protocol + +IPPROTO\_GGP +Gateway to gateway protocol + +IPPROTO\_IPV4 +IPv4 encapsulation + +IPPROTO\_ST +Stream protocol + +IPPROTO\_TCP +Transmission control protocol + +IPPROTO\_CBT +Core based trees protocol + +IPPROTO\_EGP +Exterior gateway protocol + +IPPROTO\_IGP +Private interior gateway protocol + +IPPROTO\_PUP +PARC universal packet protocol + +IPPROTO\_UDP +User datagram protocol + +IPPROTO\_IDP +Internet datagram protocol + +IPPROTO\_RDP +Reliable data protocol + +IPPROTO\_IPV6 +IPv6 header + +IPPROTO\_ROUTING +IPv6 routing header + +IPPROTO\_FRAGMENT +IPv6 fragmentation header + +IPPROTO\_ESP +Encapsulating security payload + +IPPROTO\_AH +Authentication header + +IPPROTO\_ICMPV6 +IPv6 Internet control message protocol + +IPPROTO\_NONE +IPv6 no next header + +IPPROTO\_DSTOPTS +IPv6 destination options + +IPPROTO\_ND +Net disk protocol + +IPPROTO\_ICLFXBM +Wideband monitoring + +IPPROTO\_PIM +Protocol independent multicast + +IPPROTO\_PGM +Pragmatic general multicast + +IPPROTO\_L2TP +Level 2 tunneling protocol + +IPPROTO\_SCTP +Stream control transmission protocol + +IPPROTO\_RAW +Raw IP packets + +Additional protocols are supported through the use of raw sockets. + +A WSK application specifies a protocol when it calls the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149) function or the [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150) function to create a new socket. + +A WSK application also specifies a protocol (as the *Level* parameter) when it calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function to set or retrieve transport protocol level or network protocol level socket options. + +### Combinations + +IPv6 supports the following combinations of socket types and protocols for each WSK [socket category](https://msdn.microsoft.com/library/windows/hardware/ff571093): + +Basic Sockets +SOCK\_STREAM + IPPROTO\_TCP +SOCK\_DGRAM + IPPROTO\_UDP +SOCK\_RAW + IPPROTO\_*Xxx* +Listening Sockets +SOCK\_STREAM + IPPROTO\_TCP + +Datagram Sockets +SOCK\_DGRAM + IPPROTO\_UDP +SOCK\_RAW + IPPROTO\_*Xxx* +Connection-Oriented Sockets +SOCK\_STREAM + IPPROTO\_TCP + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20AF_INET6%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/cellular-architecture-and-driver-model.md b/windows-driver-docs-pr/network/cellular-architecture-and-driver-model.md index a3f9af06e0..c1b9fe2ba8 100644 --- a/windows-driver-docs-pr/network/cellular-architecture-and-driver-model.md +++ b/windows-driver-docs-pr/network/cellular-architecture-and-driver-model.md @@ -14,16 +14,6 @@ ms.technology: windows-devices The cellular architecture for Windows 10 contains elements from both Windows 8.1 and Windows Phone 8.1. Below are the Windows 8.1 and Windows Phone 8.1 cellular architecture diagrams for comparison, along with the new Windows 10 architecture diagram and the cellular components that must be implemented. -## Windows 8.1 architecture: - - -![windows 8.1 cellular architecture](images/win81-cellular-architecture.png) - -## Windows Phone 8.1 architecture: - - -![windows phone 8.1 cellular architecture](images/winphone81-cellular-architecture.png) - ## Windows 10 architecture: @@ -42,6 +32,16 @@ For Windows 10 for desktop editions, the following is required. For Windows 10 Mobile, the following is required: - Implement an IHV RIL (Radio Interface Layer) and Mobile Broadband NDIS driver for your modem hardware. +## Windows 8.1 architecture: + + +![windows 8.1 cellular architecture](images/win81-cellular-architecture.png) + +## Windows Phone 8.1 architecture: + + +![windows phone 8.1 cellular architecture](images/winphone81-cellular-architecture.png) + ## Related topics diff --git a/windows-driver-docs-pr/network/cloned-net-buffer-list-structures.md b/windows-driver-docs-pr/network/cloned-net-buffer-list-structures.md index bfe4ab8755..e7a2880b0e 100644 --- a/windows-driver-docs-pr/network/cloned-net-buffer-list-structures.md +++ b/windows-driver-docs-pr/network/cloned-net-buffer-list-structures.md @@ -1,6 +1,6 @@ --- -title: Cloned NET\_BUFFER\_LIST Structures -description: Cloned NET\_BUFFER\_LIST Structures +title: Cloned NET_BUFFER_LIST Structures +description: Cloned NET_BUFFER_LIST Structures ms.assetid: efcf7d03-401e-46da-9ca3-8423af1e385a keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/derived-net-buffer-list-structures.md b/windows-driver-docs-pr/network/derived-net-buffer-list-structures.md index 57e87fb01a..2b3573ff9d 100644 --- a/windows-driver-docs-pr/network/derived-net-buffer-list-structures.md +++ b/windows-driver-docs-pr/network/derived-net-buffer-list-structures.md @@ -1,6 +1,6 @@ --- -title: Derived NET\_BUFFER\_LIST Structures -description: Derived NET\_BUFFER\_LIST Structures +title: Derived NET_BUFFER_LIST Structures +description: Derived NET_BUFFER_LIST Structures ms.assetid: 6660aef5-ba67-4f15-98b6-547fa753bc76 keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/determining-sr-iov-capabilities.md b/windows-driver-docs-pr/network/determining-sr-iov-capabilities.md index 4ea0af2862..8789d9757b 100644 --- a/windows-driver-docs-pr/network/determining-sr-iov-capabilities.md +++ b/windows-driver-docs-pr/network/determining-sr-iov-capabilities.md @@ -43,9 +43,8 @@ The miniport driver reports the SR-IOV hardware capabilities of the underlying n - NDIS\_SRIOV\_CAPS\_PF\_MINIPORT - **Note**  The miniport driver for a PCIe Virtual Function (VF) of the network adapter must only set the NDIS\_SRIOV\_CAPS\_VF\_MINIPORT flag. - -   + > [!NOTE] + > The miniport driver for a PCIe Virtual Function (VF) of the network adapter must set both the NDIS\_SRIOV\_CAPS\_VF\_MINIPORT flag and the NDIS\_SRIOV\_CAPS\_SRIOV\_SUPPORTED flag.   When NDIS calls the miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function, the driver registers the SR-IOV capabilities of the network adapter by following these steps: diff --git a/windows-driver-docs-pr/network/determining-the-rsc-capabilities-of-a-network-adapter.md b/windows-driver-docs-pr/network/determining-the-rsc-capabilities-of-a-network-adapter.md index 3ef26930e5..b2f690f2c7 100644 --- a/windows-driver-docs-pr/network/determining-the-rsc-capabilities-of-a-network-adapter.md +++ b/windows-driver-docs-pr/network/determining-the-rsc-capabilities-of-a-network-adapter.md @@ -1,6 +1,6 @@ --- title: Determining the RSC Capabilities of a Network Adapter -description: A receive segment coalescing (RSC)-capable miniport driver reports its RSC capability by means of the NDIS\_OFFLOAD structure that it passes to NdisMSetMiniportAttributes. +description: A receive segment coalescing (RSC)-capable miniport driver reports its RSC capability by means of the NDIS_OFFLOAD structure that it passes to NdisMSetMiniportAttributes. ms.assetid: 043A09F9-7D5D-4401-9645-19FDBD614659 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/dot11-country-or-region-string.md b/windows-driver-docs-pr/network/dot11-country-or-region-string.md new file mode 100644 index 0000000000..36cf750be3 --- /dev/null +++ b/windows-driver-docs-pr/network/dot11-country-or-region-string.md @@ -0,0 +1,87 @@ +--- +title: DOT11\_COUNTRY\_OR\_REGION\_STRING +author: windows-driver-content +description: Important  The Native 802.11 Wireless LAN interface is deprecated in Windows 10 and later. +ms.assetid: f8302c7d-de43-45e4-a03b-d1bf2b0a9fc1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -DOT11_COUNTRY_OR_REGION_STRING +--- + +# DOT11\_COUNTRY\_OR\_REGION\_STRING + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The **DOT11\_COUNTRY\_OR\_REGION\_STRING** array defines an 802.11 regulatory domain. For more information about country strings and regulatory domains, refer to the IEEE 802.11d-2001 standard. + +```ManagedCPlusPlus +typedef UCHAR DOT11_COUNTRY_OR_REGION_STRING[3]; +``` + +**DOT11\_COUNTRY\_OR\_REGION\_STRING** +A 3-byte string that identifies the country in which the 802.11 station is operating. + +**** + +Remarks +------- + +The first two bytes of the **DOT11\_COUNTRY\_OR\_REGION\_STRING** array are the country code as described in the ISO/IEC 3166-1 standard. The third byte must be one of the following: + +- An ASCII space character (0x20) if the regulations under which the 802.11 station is operating encompass all environments in the country. + +- An ASCII 'O' character (0x4F) if the regulations under which the 802.11 station is operating are for an outdoor environment only. + +- An ASCII 'I' character (0x49) if the regulations under which the 802.11 station is operating are for an indoor environment only. + +A **DOT11\_COUNTRY\_OR\_REGION\_STRING** array with a value of all zeros is used to specify a null country string. + +The PDOT11\_COUNTRY\_OR\_REGION\_STRING type is defined as a pointer to the DOT11\_COUNTRY\_OR\_REGION\_STRING type as follows: + +``` +typedef DOT11_COUNTRY_OR_REGION_STRING *PDOT11_COUNTRY_OR_REGION_STRING; +``` + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING](oid-dot11-desired-country-or-region-string.md) + +[OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING](oid-dot11-supported-country-or-region-string.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20DOT11_COUNTRY_OR_REGION_STRING%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/dot11-country-string.md b/windows-driver-docs-pr/network/dot11-country-string.md new file mode 100644 index 0000000000..f671b2be0e --- /dev/null +++ b/windows-driver-docs-pr/network/dot11-country-string.md @@ -0,0 +1,79 @@ +--- +title: DOT11\_COUNTRY\_STRING +author: windows-driver-content +description: Important  The Native 802.11 Wireless LAN interface is deprecated in Windows 10 and later. +ms.assetid: e04c31aa-4b1d-4368-ab72-763b45a1ac59 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -DOT11_COUNTRY_STRING +--- + +# DOT11\_COUNTRY\_STRING + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The **DOT11\_COUNTRY\_STRING** array defines an 802.11 regulatory domain. For more information about country strings and regulatory domains, refer to the IEEE 802.11d-2001 standard. + +```ManagedCPlusPlus +typedef UCHAR DOT11_COUNTRY_STRING[3]; +``` + +**DOT11\_COUNTRY\_STRING** +A 3-byte string that identifies the country in which the 802.11 station is operating. + +**** + +Remarks +------- + +The first two bytes of the **DOT11\_COUNTRY\_STRING** array are the country code as described in the ISO/IEC 3166-1 standard. The third byte must be one of the following: + +- An ASCII space character (0x20) if the regulations under which the 802.11 station is operating encompass all environments in the country. + +- An ASCII 'O' character (0x4F) if the regulations under which the 802.11 station is operating are for an outdoor environment only. + +- An ASCII 'I' character (0x49) if the regulations under which the 802.11 station is operating are for an indoor environment only. + +A **DOT11\_COUNTRY\_STRING** array with a value of all zeros is used to specify a null country string. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[OID\_DOT11\_COUNTRY\_STRING](oid-dot11-country-string.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20DOT11_COUNTRY_STRING%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/dot11-pmkid-value.md b/windows-driver-docs-pr/network/dot11-pmkid-value.md new file mode 100644 index 0000000000..7f45e30138 --- /dev/null +++ b/windows-driver-docs-pr/network/dot11-pmkid-value.md @@ -0,0 +1,73 @@ +--- +title: DOT11\_PMKID\_VALUE +author: windows-driver-content +description: Important  The Native 802.11 Wireless LAN interface is deprecated in Windows 10 and later. +ms.assetid: 8b23bb59-251a-4898-b929-b97ff6802744 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -DOT11_PMKID_VALUE +--- + +# DOT11\_PMKID\_VALUE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The **DOT11\_PMKID\_VALUE** array defines a pairwise master key identifier (PMKID). + +```ManagedCPlusPlus +typedef UCHAR DOT11_PMKID_VALUE[16]; +``` + +**DOT11\_PMKID\_VALUE** +The PMKID value. For more information about the format of the PMKID value, refer to Clause 8.5.1.2 of the IEEE 802.11i-2004 standard. + +**** + +Remarks +------- + +An 802.11 station that supports RSNA authentication algorithms uses PMKID values for pre-authentication when it connects to an infrastructure basic service set (BSS) network. + +For more information about the PMKID, refer to Clause 8.5.1.2 of the IEEE 802.11i-2004 standard. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[OID\_DOT11\_PMKID\_LIST](oid-dot11-pmkid-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20DOT11_PMKID_VALUE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ehs-authentication-result.md b/windows-driver-docs-pr/network/ehs-authentication-result.md new file mode 100644 index 0000000000..27c6cefb0e --- /dev/null +++ b/windows-driver-docs-pr/network/ehs-authentication-result.md @@ -0,0 +1,88 @@ +--- +title: eHS\_AUTHENTICATION\_RESULT enumeration +author: windows-driver-content +description: The eHS\_AUTHENTICATION\_RESULT enumeration indicates the result of authentication by the plugin after the PostConnectAuth request. +ms.assetid: a61ddc7c-8df8-410c-83df-9058e88bce51 +keywords: + - eHS_AUTHENTICATION_RESULT enumeration Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# eHS\_AUTHENTICATION\_RESULT enumeration + + +The **eHS\_AUTHENTICATION\_RESULT** enumeration indicates the result of authentication by the plugin after the PostConnectAuth request. + +Syntax +------ + +```ManagedCPlusPlus +typedef enum _eHS_AUTHENTICATION_RESULT { + HS_AUTHENTICATION_RESULT_SUCCESS         = 0, + HS_AUTHENTICATION_RESULT_FAILED_TIMEOUT  = 100, + HS_AUTHENTICATION_RESULT_FAILED_AUTH, + HS_AUTHENTICATION_RESULT_FAILED_CONNECT, + HS_AUTHENTICATION_RESULT_FAILED_OTHER, + HS_AUTHENTICATION_RESULT_MAX +} eHS_AUTHENTICATION_RESULT; +``` + +Constants +--------- + +**HS\_AUTHENTICATION\_RESULT\_SUCCESS** +Indicates the authentication was successful. + +**HS\_AUTHENTICATION\_RESULT\_FAILED\_TIMEOUT** +Indicates the authentication failed due to a timeout from the server/back end. + +**HS\_AUTHENTICATION\_RESULT\_FAILED\_AUTH** +Indicates the authentication failed due to incorrect credentials. + +**HS\_AUTHENTICATION\_RESULT\_FAILED\_CONNECT** +Indicates the authentication failed due to an inability to connect to the authentication server + +**HS\_AUTHENTICATION\_RESULT\_FAILED\_OTHER** +Indicates the authentication failed for some other reason. + +**HS\_AUTHENTICATION\_RESULT\_MAX** +Indicates an out-of-range value. + +Remarks +------- + +The plugin passes this enumeration value to the hotspot plugin host through the [**HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION**](hs-host-post-connect-auth-completion.md) function, which is used to inform the hotspot plugin host of the results of a call to [**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20eHS_AUTHENTICATION_RESULT%20enumeration%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ehs-network-state.md b/windows-driver-docs-pr/network/ehs-network-state.md new file mode 100644 index 0000000000..e7919830fb --- /dev/null +++ b/windows-driver-docs-pr/network/ehs-network-state.md @@ -0,0 +1,75 @@ +--- +title: eHS\_NETWORK\_STATE enumeration +author: windows-driver-content +description: The eHS\_NETWORK\_STATE enumeration indicates whether a network is a hotspot network. +ms.assetid: a833d226-e2cf-41f9-a926-5b1f6daa03af +keywords: + - eHS_NETWORK_STATE enumeration Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# eHS\_NETWORK\_STATE enumeration + + +The **eHS\_NETWORK\_STATE** enumeration indicates whether a network is a hotspot network. + +Syntax +------ + +```ManagedCPlusPlus +typedef enum _eHS_NETWORK_STATE { + HS_NETWORK_STATE_NOT_A_HOTSPOT, + HS_NETWORK_STATE_HOTSPOT_MANUAL_CONNECT, + HS_NETWORK_STATE_HOTSPOT_AUTO_CONNECT, + HS_NETWORK_STATE_MAX +} eHS_NETWORK_STATE; +``` + +Constants +--------- + +**HS\_NETWORK\_STATE\_NOT\_A\_HOTSPOT** +Indicates the network is not a hotspot network. + +**HS\_NETWORK\_STATE\_HOTSPOT\_MANUAL\_CONNECT** +Indicates the user can manually connect to the hotspot network. + +**HS\_NETWORK\_STATE\_HOTSPOT\_AUTO\_CONNECT** +Indicates the device can connect automatically to the hotspot network. + +**HS\_NETWORK\_STATE\_MAX** +Indicates an out-of-range value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20eHS_NETWORK_STATE%20enumeration%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ehs-unload-reason.md b/windows-driver-docs-pr/network/ehs-unload-reason.md new file mode 100644 index 0000000000..2c5005b550 --- /dev/null +++ b/windows-driver-docs-pr/network/ehs-unload-reason.md @@ -0,0 +1,160 @@ +--- +title: eHS\_UNLOAD\_REASON enumeration +author: windows-driver-content +description: The eHS\_UNLOAD\_REASON enumeration indicates the reason for the plugin to get unloaded. +ms.assetid: 1e658dd3-f66d-4803-ad3c-84bfa1890a86 +keywords: +- eHS_UNLOAD_REASON enumeration Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# eHS\_UNLOAD\_REASON enumeration + + +The **eHS\_UNLOAD\_REASON** enumeration indicates the reason for the plugin to get unloaded. + +Syntax +------ + +```ManagedCPlusPlus +typedef enum _eHS_UNLOAD_REASON { + HS_UNLOAD_REASON_NONE, + HS_UNLOAD_REASON_PLUGN_INIT_FAILED, + HS_UNLOAD_REASON_NO_NETWORKS_SUPPORTED, + HS_UNLOAD_REASON_NO_PROVIDE_NAME_ID, + HS_UNLOAD_REASON_ZERO_SIM_COUNT, + HS_UNLOAD_REASON_DISPLAY_FLAG_BUT_NO_DISPLAY_STRING_ID, + HS_UNLOAD_REASON_CUSTOM_REALM_FLAG_BUT_NO_REALM_STRING, + HS_UNLOAD_REASON_DUPLICATE_PLUGIN_LOADED, + HS_UNLOAD_REASON_RELOAD_REQUESTED_BY_PLUGIN, + HS_UNLOAD_REASON_EXCEPTION_DURING_PLUGIN_CALL, + HS_UNLOAD_REASON_EXCEPTION_IN_PLUGIN_HOST, + HS_UNLOAD_REASON_ASYNC_INITIALIZATION_FAILED, + HS_UNLOAD_REASON_UNSUPPORTED_AUTH_CAPABILITY_REQUESTED, + HS_UNLOAD_REASON_FAILED_TO_LOAD_PROVIDER_NAME_STRING, + HS_UNLOAD_REASON_FAILED_TO_LOAD_ADVANCED_PAGE_STRING, + HS_UNLOAD_REASON_FAILED_TO_LOAD_NETWORK_NAME_STRING, + HS_UNLOAD_REASON_FAILED_TO_CONFIGURE_HIDDEN_NETWORK, + HS_UNLOAD_REASON_HIDDEN_NETWORK_ALREADY_CONFIGURED, + HS_UNLOAD_REASON_FAILED_TO_QUERY_SIMS, + HS_UNLOAD_REASON_PLUGIN_REQUIRED_SIM_NOT_PRESENT, + HS_UNLOAD_REASON_SIM_CONFIG_CHANGED, + HS_UNLOAD_REASON_WIFI_SWITCHED_OFF_IN_OS, + HS_UNLOAD_REASON_MAX +} eHS_UNLOAD_REASON; +``` + +Constants +--------- + +**HS\_UNLOAD\_REASON\_NONE** +No specific reason for the unload operation. + +**HS\_UNLOAD\_REASON\_PLUGN\_INIT\_FAILED** +The plugin is being unloaded because it failed to initialize successfully. + +**HS\_UNLOAD\_REASON\_NO\_NETWORKS\_SUPPORTED** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure did not indicate a valid value for **dwNumNetworksSupported**. + +**HS\_UNLOAD\_REASON\_NO\_PROVIDE\_NAME\_ID** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure did not specify a string ID for **dwProviderNameStringID**. + +**HS\_UNLOAD\_REASON\_ZERO\_SIM\_COUNT** +The plugin is being unloaded because there are no SIM cards present. + +**HS\_UNLOAD\_REASON\_DISPLAY\_FLAG\_BUT\_NO\_DISPLAY\_STRING\_ID** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure requires HTTP or EAP SIM-based authentication but did not specify a value for **dwSupportedSIMCount.** + +**HS\_UNLOAD\_REASON\_CUSTOM\_REALM\_FLAG\_BUT\_NO\_REALM\_STRING** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure specified the **HS\_FLAG\_CAPABILITY\_NETWORK\_CUSTOM\_REALM** capability but did not provide a valid string for **szRealm**. + +**HS\_UNLOAD\_REASON\_DUPLICATE\_PLUGIN\_LOADED** +The plugin is being unloaded because another plugin is using the same DLL. + +**HS\_UNLOAD\_REASON\_RELOAD\_REQUESTED\_BY\_PLUGIN** +The plugin is being unloaded because the plugin requested to be unloaded and reloaded by specifying the **HS\_UPDATE\_RESULT\_ACTION\_RELOAD** action with the [**eHS\_UPDATE\_RESULT**](ehs-update-result.md) enumeration. + +**HS\_UNLOAD\_REASON\_EXCEPTION\_DURING\_PLUGIN\_CALL** +The plugin is being unloaded because the host process encountered an exception while in a call to the plugin. + +**HS\_UNLOAD\_REASON\_EXCEPTION\_IN\_PLUGIN\_HOST** +The plugin is being unloaded because the hotspot host encountered an exception. + +**HS\_UNLOAD\_REASON\_ASYNC\_INITIALIZATION\_FAILED** +The plugin is being unloaded because the hotspot service failed to register for notifications from the plugin. + +**HS\_UNLOAD\_REASON\_UNSUPPORTED\_AUTH\_CAPABILITY\_REQUESTED** +The plugin is being unloaded because none of the authentication capabilities requested by the plugin are available. + +**HS\_UNLOAD\_REASON\_FAILED\_TO\_LOAD\_PROVIDER\_NAME\_STRING** +The plugin is being unloaded because the hotspot service could not map the **dwProviderNameStringID** string ID provided in the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure to a valid string. + +**HS\_UNLOAD\_REASON\_FAILED\_TO\_LOAD\_ADVANCED\_PAGE\_STRING** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure specified an (optional) **dwAdvancedPageStringID** string ID but it did not map to a valid string. + +**HS\_UNLOAD\_REASON\_FAILED\_TO\_LOAD\_NETWORK\_NAME\_STRING** +The plugin is being unloaded because the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure specified an (optional) **dwGenericNetworkNameStringID** string ID, but it did not map to a valid string. + +**HS\_UNLOAD\_REASON\_FAILED\_TO\_CONFIGURE\_HIDDEN\_NETWORK** +The plugin is being unloaded because the plugin specified a hidden network (via the **HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_HIDDEN** capability), but the hotspot service was unable to configure the hidden network. + +**HS\_UNLOAD\_REASON\_HIDDEN\_NETWORK\_ALREADY\_CONFIGURED** +The plugin is being unloaded because the plugin specified a hidden network via the **HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_HIDDEN** capability but another plugin has already claimed the hidden network slot. + +**HS\_UNLOAD\_REASON\_FAILED\_TO\_QUERY\_SIMS** +The plugin is being unloaded because the call to [**HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS**](hs-plugin-query-supported-sims.md) failed. + +**HS\_UNLOAD\_REASON\_PLUGIN\_REQUIRED\_SIM\_NOT\_PRESENT** +The plugin is being unloaded because the SIMs required by the plugin are not present in the device. + +**HS\_UNLOAD\_REASON\_SIM\_CONFIG\_CHANGED** +The plugin is being unloaded because the SIM configuration changed, which requires the plugins to be unloaded and reloaded. + +**HS\_UNLOAD\_REASON\_WIFI\_SWITCHED\_OFF\_IN\_OS** +The plugin is being unloaded because Wi-Fi functionality was switched off in the OS. + +**HS\_UNLOAD\_REASON\_MAX** +Indicates an out-of-range value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +[**eHS\_UPDATE\_RESULT**](ehs-update-result.md) + +[**HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS**](hs-plugin-query-supported-sims.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20eHS_UNLOAD_REASON%20enumeration%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ehs-update-result.md b/windows-driver-docs-pr/network/ehs-update-result.md new file mode 100644 index 0000000000..82f7adb46f --- /dev/null +++ b/windows-driver-docs-pr/network/ehs-update-result.md @@ -0,0 +1,87 @@ +--- +title: eHS\_UPDATE\_RESULT enumeration +author: windows-driver-content +description: The eHS\_UPDATE\_RESULT enumeration indicates the result of a “check for updates” request. +ms.assetid: 7b9b8ddc-3101-466a-9640-b936f6d14de4 +keywords: +- eHS_UPDATE_RESULT enumeration Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# eHS\_UPDATE\_RESULT enumeration + + +The **eHS\_UPDATE\_RESULT** enumeration indicates the result of a “check for updates” request. + +Syntax +------ + +```ManagedCPlusPlus +typedef enum _eHS_UPDATE_RESULT { + HS_UPDATE_RESULT_SUCCESS, + HS_UPDATE_RESULT_ACTION_RECONNECT, + HS_UPDATE_RESULT_ACTION_RELOAD, + HS_UPDATE_RESULT_MAX +} eHS_UPDATE_RESULT; +``` + +Constants +--------- + +**HS\_UPDATE\_RESULT\_SUCCESS** +Indicates the update was successful. + +**HS\_UPDATE\_RESULT\_ACTION\_RECONNECT** +The result of the update request requires the service to disconnect and reconnect. + +**HS\_UPDATE\_RESULT\_ACTION\_RELOAD** +The result of the update request requires the service to unload and reload the plugin. + +**HS\_UPDATE\_RESULT\_MAX** +Indicates an out-of-range value. + +Remarks +------- + +The plugin passes this enumeration value to the hotspot plugin host through the [**HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION**](hs-host-update-configuration-completion.md) function, which is used to inform the hotspot plugin host of the results of a call to [**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION**](hs-host-update-configuration-completion.md) + +[**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20eHS_UPDATE_RESULT%20enumeration%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/enabling-and-disabling-ndk-functionality.md b/windows-driver-docs-pr/network/enabling-and-disabling-ndk-functionality.md index 90cc937d20..51013d1a9f 100644 --- a/windows-driver-docs-pr/network/enabling-and-disabling-ndk-functionality.md +++ b/windows-driver-docs-pr/network/enabling-and-disabling-ndk-functionality.md @@ -1,6 +1,6 @@ --- title: Enabling and Disabling NDK Functionality -description: To enable or disable NDK functionality, NDIS issues an OID\_NDK\_SET\_STATE OID request. An NDK-capable miniport driver must register support for this OID in its MiniportOidRequest function. +description: To enable or disable NDK functionality, NDIS issues an OID_NDK_SET_STATE OID request. An NDK-capable miniport driver must register support for this OID in its MiniportOidRequest function. ms.assetid: A72AD98E-FF84-48FF-B627-5534231244B0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/enabling-and-disabling-task-offload-services.md b/windows-driver-docs-pr/network/enabling-and-disabling-task-offload-services.md index 3c4dcb71e8..0c75ae0a5a 100644 --- a/windows-driver-docs-pr/network/enabling-and-disabling-task-offload-services.md +++ b/windows-driver-docs-pr/network/enabling-and-disabling-task-offload-services.md @@ -1,6 +1,6 @@ --- title: Enabling and Disabling Task Offload Services -description: A protocol driver can enable or disable task offload services for an underlying miniport adapter by issuing an OID\_OFFLOAD\_ENCAPSULATION OID set request. +description: A protocol driver can enable or disable task offload services for an underlying miniport adapter by issuing an OID_OFFLOAD_ENCAPSULATION OID set request. ms.assetid: cc803af4-d4ed-4b51-9e0e-77443e0eb023 keywords: - task offload WDK TCP/IP transport , enabling services diff --git a/windows-driver-docs-pr/network/enumeration-keywords.md b/windows-driver-docs-pr/network/enumeration-keywords.md index b2c0b09839..61b90bbf03 100644 --- a/windows-driver-docs-pr/network/enumeration-keywords.md +++ b/windows-driver-docs-pr/network/enumeration-keywords.md @@ -23,14 +23,14 @@ NDIS 6.0 and later versions of NDIS provide standardized enumeration keywords fo The following example shows an INF file definition for an enumeration keyword. ``` -HKR, Ndi\params\\, ParamDesc, 0, "%%" -HKR, Ndi\params\\, Type, 0, "enum" -HKR, Ndi\params\\, Default, 0, "3" -HKR, Ndi\params\\, Optional, 0, "0" -HKR, Ndi\params\\\enum, "0", 0, "%Disabled%" -HKR, Ndi\params\\\enum, "1", 0, "%Tx Enabled%" -HKR, Ndi\params\\\enum, "2", 0, "%Rx Enabled%" -HKR, Ndi\params\\\enum, "3", 0, "%Rx & Tx Enabled%" +HKR, Ndi\params\, ParamDesc, 0, "%%" +HKR, Ndi\params\, Type, 0, "enum" +HKR, Ndi\params\, Default, 0, "3" +HKR, Ndi\params\, Optional, 0, "0" +HKR, Ndi\params\\enum, "0", 0, "%Disabled%" +HKR, Ndi\params\\enum, "1", 0, "%Tx Enabled%" +HKR, Ndi\params\\enum, "2", 0, "%Rx Enabled%" +HKR, Ndi\params\\enum, "3", 0, "%Rx & Tx Enabled%" ``` The general enumeration keywords are: diff --git a/windows-driver-docs-pr/network/extensible-access-point-indications.md b/windows-driver-docs-pr/network/extensible-access-point-indications.md new file mode 100644 index 0000000000..6d8ba3f23a --- /dev/null +++ b/windows-driver-docs-pr/network/extensible-access-point-indications.md @@ -0,0 +1,40 @@ +--- +title: Extensible Access Point Indications +description: Extensible Access Point Indications +ms.assetid: 0339DD41-C4F4-4E09-B348-A15EFB101B45 +keywords: +- ExtAP status indications WDK Native 802.11 +- Extensible Access Point status indications WDK Native 802.11 +ms.author: windowsdriverdev +ms.date: 04/26/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Extensible Access Point Indications + + +**Important**  The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +When a miniport driver operates in Extensible Access Point (ExtAP) mode, it can make the following status indications that are specific to ExtAP mode: + +| Name | Description | +| --- | --- | +| [NDIS_STATUS_DOT11_CAN_SUSTAIN_AP](https://msdn.microsoft.com/library/windows/hardware/ff567323) | The driver makes this indication after the NIC stops an 802.11 access point (AP). | +| [NDIS_STATUS_DOT11_INCOMING_ASSOC_COMPLETION](https://msdn.microsoft.com/library/windows/hardware/ff567338) | The driver makes this indication after either a successful or failed incoming association request from a peer station. For more information about Association operations in ExtAP mode, see [Association Operation Guidelines for Extensible Access Point (ExtAP) Mode](association-operation-guidelines-for-extensible-access-point--extap--m.md). | +| [NDIS_STATUS_DOT11_INCOMING_ASSOC_REQUEST_RECEIVED](https://msdn.microsoft.com/library/windows/hardware/ff567339) | The driver makes this indication after the NIC receives an incoming association request frame from a peer station. For more information about Association operations in ExtAP mode, see [Association Operation Guidelines for Extensible Access Point (ExtAP) Mode](association-operation-guidelines-for-extensible-access-point--extap--m.md). | +| [NDIS_STATUS_DOT11_INCOMING_ASSOC_STARTED](https://msdn.microsoft.com/library/windows/hardware/ff567342) | The driver makes this indication when the NIC receives the first valid 802.11 authentication request from a peer station. For more information about Association operations in ExtAP mode, see [Association Operation Guidelines for Extensible Access Point (ExtAP) Mode](association-operation-guidelines-for-extensible-access-point--extap--m.md). | +| [NDIS_STATUS_DOT11_PHY_FREQUENCY_ADOPTED](https://msdn.microsoft.com/library/windows/hardware/ff567351) | The driver makes this indication after it has adopted a channel or frequency to communicate with a peer station.| +| [NDIS_STATUS_DOT11_STOP_AP](https://msdn.microsoft.com/library/windows/hardware/ff567366) | The driver makes this indication when the NIC cannot sustain 802.11 access point (AP) functionality on any of the available PHYs.| + +Additionally, a miniport driver operating in ExtAP mode can makethe following status indications: + +| Name | Description | +| --- | --- | +| [NDIS_STATUS_DOT11_DISASSOCIATION](https://msdn.microsoft.com/library/windows/hardware/ff567334) | The driver makes this indication after the 802.11 station completes a disassociation operation with an AP or peer station. For more information about this operation, see [Disassociation Operations](disassociation-operations.md). | +| [NDIS_STATUS_DOT11_LINK_QUALITY](https://msdn.microsoft.com/library/windows/hardware/ff567344) | The driver makes this indication whenever the 802.11 station determines the link quality for an association with an AP or peer station that has changed significantly. For more information about link quality and link quality indications, see [Link Quality Operations](link-quality-operations.md). | +| [NDIS_STATUS_DOT11_PHY_STATE_CHANGED](https://msdn.microsoft.com/library/windows/hardware/ff567354) | The driver makes this indication whenever the power state changes on a PHY that is supported by the 802.11 station. | +| [NDIS_STATUS_DOT11_TKIPMIC_FAILURE](https://msdn.microsoft.com/library/windows/hardware/ff567368) | The driver makes this indication whenever a received packet that has been successfully decrypted by the TKIP cipher algorithm fails the message integrity code (MIC) verification. | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/network/filling-in-an-ndis-guid-structure.md b/windows-driver-docs-pr/network/filling-in-an-ndis-guid-structure.md index 035ede4d72..e1211577e9 100644 --- a/windows-driver-docs-pr/network/filling-in-an-ndis-guid-structure.md +++ b/windows-driver-docs-pr/network/filling-in-an-ndis-guid-structure.md @@ -1,6 +1,6 @@ --- -title: Filling in an NDIS\_GUID Structure -description: Filling in an NDIS\_GUID Structure +title: Filling in an NDIS_GUID Structure +description: Filling in an NDIS_GUID Structure ms.assetid: 971f6f25-fd2b-4a1e-9378-6270a094f4ff keywords: - NDIS_GUID diff --git a/windows-driver-docs-pr/network/fin-wait-2-timer.md b/windows-driver-docs-pr/network/fin-wait-2-timer.md index 213cbaa26f..dc7c8a6653 100644 --- a/windows-driver-docs-pr/network/fin-wait-2-timer.md +++ b/windows-driver-docs-pr/network/fin-wait-2-timer.md @@ -1,6 +1,6 @@ --- -title: FIN\_WAIT\_2 Timer -description: FIN\_WAIT\_2 Timer +title: FIN_WAIT_2 Timer +description: FIN_WAIT_2 Timer ms.assetid: 912d30a7-5bd4-4460-8136-466f5ad84536 keywords: - timers WDK TCP chimney offload , FIN_WAIT_2 timers diff --git a/windows-driver-docs-pr/network/fragmented-net-buffer-list-structures.md b/windows-driver-docs-pr/network/fragmented-net-buffer-list-structures.md index df32fecc8b..877fe8965f 100644 --- a/windows-driver-docs-pr/network/fragmented-net-buffer-list-structures.md +++ b/windows-driver-docs-pr/network/fragmented-net-buffer-list-structures.md @@ -1,6 +1,6 @@ --- -title: Fragmented NET\_BUFFER\_LIST Structures -description: Fragmented NET\_BUFFER\_LIST Structures +title: Fragmented NET_BUFFER_LIST Structures +description: Fragmented NET_BUFFER_LIST Structures ms.assetid: a72bc0cf-8c92-4c3e-ad10-710e5b93c74c keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/guid-ndis-gen-pci-device-custom-properties.md b/windows-driver-docs-pr/network/guid-ndis-gen-pci-device-custom-properties.md new file mode 100644 index 0000000000..407c2fc7c6 --- /dev/null +++ b/windows-driver-docs-pr/network/guid-ndis-gen-pci-device-custom-properties.md @@ -0,0 +1,64 @@ +--- +title: GUID\_NDIS\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES +author: windows-driver-content +description: WMI clients can use the GUID\_NDIS\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES method GUID to determine the current link state. +ms.assetid: a02b9049-e521-41df-ab4d-41e334ef779e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -GUID_NDIS_GEN_PCI_DEVICE_CUSTOM_PROPERTIES Network Drivers Starting with Windows Vista +--- + +# GUID\_NDIS\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES + + +WMI clients can use the GUID\_NDIS\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES method GUID to determine the current link state. + +Remarks +------- + +NDIS handles this GUID and miniport drivers do not receive an OID query. + +When a WMI client issues a GUID\_NDIS\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES WMI method request, NDIS returns the PCI custom properties of a PCI device for the miniport adapter. The WMI method identifier should be NDIS\_WMI\_DEFAULT\_METHOD\_ID, and the WMI input buffer should contain an [**NDIS\_WMI\_METHOD\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff567903) structure. + +The data buffer that NDIS returns with this GUID contains an [**NDIS\_PCI\_DEVICE\_CUSTOM\_PROPERTIES**](https://msdn.microsoft.com/library/windows/hardware/ff566745) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PCI\_DEVICE\_CUSTOM\_PROPERTIES**](https://msdn.microsoft.com/library/windows/hardware/ff566745) + +[**NDIS\_WMI\_METHOD\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff567903) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20GUID_NDIS_GEN_PCI_DEVICE_CUSTOM_PROPERTIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/handling-an-oid-pnp-query-power-oid.md b/windows-driver-docs-pr/network/handling-an-oid-pnp-query-power-oid.md index c49de6f277..2c47b0a57b 100644 --- a/windows-driver-docs-pr/network/handling-an-oid-pnp-query-power-oid.md +++ b/windows-driver-docs-pr/network/handling-an-oid-pnp-query-power-oid.md @@ -1,6 +1,6 @@ --- -title: Handling an OID\_PNP\_QUERY\_POWER OID -description: Handling an OID\_PNP\_QUERY\_POWER OID +title: Handling an OID_PNP_QUERY_POWER OID +description: Handling an OID_PNP_QUERY_POWER OID ms.assetid: aec9393a-debb-41eb-a8a0-b3d1936d707b keywords: - OID_PNP_QUERY_POWER diff --git a/windows-driver-docs-pr/network/handling-an-oid-pnp-set-power-oid.md b/windows-driver-docs-pr/network/handling-an-oid-pnp-set-power-oid.md index 394c76c90a..77ef0fed47 100644 --- a/windows-driver-docs-pr/network/handling-an-oid-pnp-set-power-oid.md +++ b/windows-driver-docs-pr/network/handling-an-oid-pnp-set-power-oid.md @@ -1,6 +1,6 @@ --- -title: Handling an OID\_PNP\_SET\_POWER OID -description: Handling an OID\_PNP\_SET\_POWER OID +title: Handling an OID_PNP_SET_POWER OID +description: Handling an OID_PNP_SET_POWER OID ms.assetid: 6140c772-57ba-47d3-b294-a2e2b2e3ccc7 keywords: - OID_PNP_SET_POWER_OID diff --git a/windows-driver-docs-pr/network/handling-oid-nic-switch-allocate-vf-requests.md b/windows-driver-docs-pr/network/handling-oid-nic-switch-allocate-vf-requests.md index b63edc91b5..2fe1a44f22 100644 --- a/windows-driver-docs-pr/network/handling-oid-nic-switch-allocate-vf-requests.md +++ b/windows-driver-docs-pr/network/handling-oid-nic-switch-allocate-vf-requests.md @@ -1,6 +1,6 @@ --- -title: Handling OID\_NIC\_SWITCH\_ALLOCATE\_VF Requests -description: Handling OID\_NIC\_SWITCH\_ALLOCATE\_VF Requests +title: Handling OID_NIC_SWITCH_ALLOCATE_VF Requests +description: Handling OID_NIC_SWITCH_ALLOCATE_VF Requests ms.assetid: B48A19D5-A768-4614-961D-1BD00762B6D0 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/handling-oid-nic-switch-free-vf-requests.md b/windows-driver-docs-pr/network/handling-oid-nic-switch-free-vf-requests.md index 0ef8e64ac5..812a440e8a 100644 --- a/windows-driver-docs-pr/network/handling-oid-nic-switch-free-vf-requests.md +++ b/windows-driver-docs-pr/network/handling-oid-nic-switch-free-vf-requests.md @@ -1,6 +1,6 @@ --- -title: Handling OID\_NIC\_SWITCH\_FREE\_VF Requests -description: Handling OID\_NIC\_SWITCH\_FREE\_VF Requests +title: Handling OID_NIC_SWITCH_FREE_VF Requests +description: Handling OID_NIC_SWITCH_FREE_VF Requests ms.assetid: 56134421-6D3C-4A40-B7EE-FDB729D46DEB ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/handling-oid-pnp-xxx-queries-and-sets.md b/windows-driver-docs-pr/network/handling-oid-pnp-xxx-queries-and-sets.md index b6fe96a1d8..ff34c41620 100644 --- a/windows-driver-docs-pr/network/handling-oid-pnp-xxx-queries-and-sets.md +++ b/windows-driver-docs-pr/network/handling-oid-pnp-xxx-queries-and-sets.md @@ -1,6 +1,6 @@ --- -title: Handling OID\_PNP\_Xxx Queries and Sets -description: Handling OID\_PNP\_Xxx Queries and Sets +title: Handling OID_PNP_Xxx Queries and Sets +description: Handling OID_PNP_Xxx Queries and Sets ms.assetid: 2d5db7fb-2a27-4359-9d75-35939e72de69 keywords: - OID_PNP_Xxx diff --git a/windows-driver-docs-pr/network/handling-the-oid-nic-switch-create-switch-request.md b/windows-driver-docs-pr/network/handling-the-oid-nic-switch-create-switch-request.md index 4254e949d7..7e310ca89a 100644 --- a/windows-driver-docs-pr/network/handling-the-oid-nic-switch-create-switch-request.md +++ b/windows-driver-docs-pr/network/handling-the-oid-nic-switch-create-switch-request.md @@ -1,6 +1,6 @@ --- -title: Handling the OID\_NIC\_SWITCH\_CREATE\_SWITCH Request -description: Handling the OID\_NIC\_SWITCH\_CREATE\_SWITCH Request +title: Handling the OID_NIC_SWITCH_CREATE_SWITCH Request +description: Handling the OID_NIC_SWITCH_CREATE_SWITCH Request ms.assetid: 5C0BC300-8904-483A-A66B-8F5CFE0829B1 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-complete-request.md b/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-complete-request.md index 8c77984118..5013d066a6 100644 --- a/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-complete-request.md +++ b/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-complete-request.md @@ -1,6 +1,6 @@ --- -title: Handling the OID\_SWITCH\_NIC\_SAVE\_COMPLETE Request -description: Handling the OID\_SWITCH\_NIC\_SAVE\_COMPLETE Request +title: Handling the OID_SWITCH_NIC_SAVE_COMPLETE Request +description: Handling the OID_SWITCH_NIC_SAVE_COMPLETE Request ms.assetid: 5EE5F4ED-E0FC-458E-B9E1-23C20B3BC597 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-request.md b/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-request.md index ffcb6968a2..2789227e34 100644 --- a/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-request.md +++ b/windows-driver-docs-pr/network/handling-the-oid-switch-nic-save-request.md @@ -1,6 +1,6 @@ --- -title: Handling the OID\_SWITCH\_NIC\_SAVE Request -description: Handling the OID\_SWITCH\_NIC\_SAVE Request +title: Handling the OID_SWITCH_NIC_SAVE Request +description: Handling the OID_SWITCH_NIC_SAVE Request ms.assetid: 42D66822-6F7E-4772-A280-7823BC29FD71 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/header-data-split-macros.md b/windows-driver-docs-pr/network/header-data-split-macros.md new file mode 100644 index 0000000000..c7078e86bc --- /dev/null +++ b/windows-driver-docs-pr/network/header-data-split-macros.md @@ -0,0 +1,33 @@ +--- +title: Header-Data Split Macros +author: windows-driver-content +description: Header-Data Split Macros +ms.assetid: bc761c1f-e584-4a32-9e12-3430b49d88e1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Header-Data Split Macros + + +## + + +This section includes: + +[**NET\_BUFFER\_LIST\_NBL\_FLAGS**](net-buffer-list-nbl-flags.md) + +[**NET\_BUFFER\_DATA\_PHYSICAL\_ADDRESS**](net-buffer-data-physical-address.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Header-Data%20Split%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/header-data-split-status-indications.md b/windows-driver-docs-pr/network/header-data-split-status-indications.md new file mode 100644 index 0000000000..3027c241ba --- /dev/null +++ b/windows-driver-docs-pr/network/header-data-split-status-indications.md @@ -0,0 +1,31 @@ +--- +title: Header-Data Split Status Indications +author: windows-driver-content +description: Header-Data Split Status Indications +ms.assetid: bf066dc3-577e-4d7a-afa9-a4ee1a31594e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Header-Data Split Status Indications + + +## + + +This section includes: + +[**NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG**](ndis-status-hd-split-current-config.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Header-Data%20Split%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/host-shutdown-device-service.md b/windows-driver-docs-pr/network/host-shutdown-device-service.md index 0f1781a538..1ebcfe7bfc 100644 --- a/windows-driver-docs-pr/network/host-shutdown-device-service.md +++ b/windows-driver-docs-pr/network/host-shutdown-device-service.md @@ -1,6 +1,6 @@ --- title: HOST Shutdown Device Service -description: This topic provides guidelines for Mobile Broadband Interface Model (MBIM)-compliant devices to implement and report the described device service when queried by CID\_MBIM\_DEVICE\_SERVICES. +description: This topic provides guidelines for Mobile Broadband Interface Model (MBIM)-compliant devices to implement and report the described device service when queried by CID_MBIM_DEVICE_SERVICES. ms.assetid: 62BFC796-EDB2-489E-B487-65E2DD7C4256 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/hotspot-host-handlers.md b/windows-driver-docs-pr/network/hotspot-host-handlers.md new file mode 100644 index 0000000000..cec640fe2c --- /dev/null +++ b/windows-driver-docs-pr/network/hotspot-host-handlers.md @@ -0,0 +1,109 @@ +--- +title: HOTSPOT\_HOST\_HANDLERS structure +author: windows-driver-content +description: The HOTSPOT\_HOST\_HANDLERS structure contains the hotspot host handlers function table. +ms.assetid: b381e471-7713-401a-b3fa-eae1801b0e81 +keywords: +- HOTSPOT_HOST_HANDLERS structure Network Drivers Starting with Windows Vista +- PHOTSPOT_HOST_HANDLERS structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HOTSPOT\_HOST\_HANDLERS structure + + +The **HOTSPOT\_HOST\_HANDLERS** structure contains the hotspot host handlers function table. This function table is passed to the plugin when [**HSPluginInitPlugin**](hsplugininitplugin.md) is called to initialize it. The table contains functions that are called by the plugin to communicate with the hotspot host. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HOTSPOT_HOST_HANDLERS { + HS_HOST_ALLOCATE_MEMORY                          HSHostAllocateMemory; + HS_HOST_FREE_MEMORY                              HSHostFreeMemory; + HS_HOST_POST_CONNECT_AUTH_COMPLETION             HSHostPostConnectAuthCompletion; + HS_HOST_SEND_KEEP_ALIVE_COMPLETION               HSHostSendKeepAliveCompletion; + HS_HOST_UPDATE_CONFIGURATION_COMPLETION          HSHostUpdateConfigurationCompletion; + HS_HOST_SEND_USER_MESSAGE HSHostSendUserMessage; +} HOTSPOT_HOST_HANDLERS, *PHOTSPOT_HOST_HANDLERS; +``` + +Members +------- + +**HSHostAllocateMemory** +Optional memory management handler. + +Handle to the function that is called by the plugin to allocate any memory needed by the plugin. For more information, see [**HS\_HOST\_ALLOCATE\_MEMORY**](hs-host-allocate-memory.md). + +**HSHostFreeMemory** +Optional memory management handler. + +Handle to the function that is called by the plugin to free any memory that had been allocated earlier by the call to [**HS\_HOST\_ALLOCATE\_MEMORY**](hs-host-allocate-memory.md). For more information, see [**HS\_HOST\_FREE\_MEMORY**](hs-host-free-memory.md). + +**HSHostPostConnectAuthCompletion** +Required connection-process handler. + +Handle to the function that is called by the plugin to indicate the success or failure status resulting from the authentication attempt following a Wi-Fi connection setup at layer 2. For more information, see [**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md). + +**HSHostSendKeepAliveCompletion** +Optional periodic request. + +Handle to the function that is called by the plugin to indicate the success or failure status resulting from the Send Keep Alive request. For more information, see [**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md). + +**HSHostUpdateConfigurationCompletion** +Optional periodic request. + +Handle to the function that is called by the plugin to indicate the success or failure of a call to check for updates. For more information, see [**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md). + +**HSHostSendUserMessage** +Optional periodic request. + +Handle to the function that is called to communicate with the user. For more information see [**HS\_HOST\_SEND\_USER\_MESSAGE**](hs-host-send-user-message.md). + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HSPluginInitPlugin**](hsplugininitplugin.md) + +[**HS\_HOST\_ALLOCATE\_MEMORY**](hs-host-allocate-memory.md) + +[**HS\_HOST\_FREE\_MEMORY**](hs-host-free-memory.md) + +[**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md) + +[**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md) + +[**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md) + +[**HS\_HOST\_SEND\_USER\_MESSAGE**](hs-host-send-user-message.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HOTSPOT_HOST_HANDLERS%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hotspot-plugin-apis.md b/windows-driver-docs-pr/network/hotspot-plugin-apis.md new file mode 100644 index 0000000000..329d3647f0 --- /dev/null +++ b/windows-driver-docs-pr/network/hotspot-plugin-apis.md @@ -0,0 +1,151 @@ +--- +title: HOTSPOT\_PLUGIN\_APIS structure +author: windows-driver-content +description: The HOTSPOT\_PLUGIN\_APIS structure contains the Hotspot plugin APIs function table. +ms.assetid: eee56f84-2c7f-4218-b7ec-b4fc0181d767 +keywords: +- HOTSPOT_PLUGIN_APIS structure Network Drivers Starting with Windows Vista +- PHOTSPOT_PLUGIN_APIS structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HOTSPOT\_PLUGIN\_APIS structure + + +The **HOTSPOT\_PLUGIN\_APIS** structure contains the Hotspot plugin APIs function table. This function table is returned by the plugin when [**HSPluginInitPlugin**](hsplugininitplugin.md) is called to initialize the plugin. The table contains functions that are called by the hotspot host to communicate with the plugin. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HOTSPOT_PLUGIN_APIS { + HS_PLUGIN_QUERY_SUPPORTED_SIMS     HSPluginQuerySupportedSIMs; + HS_PLUGIN_QUERY_HIDDEN_NETWORK     HSPluginQueryCellularExceptionHosts; + HS_PLUGIN_IS_HOTSPOT_NETWORK       HSPluginIsHotspotNetwork; + HS_PLUGIN_PRE_CONNECT_INIT         HSPluginPreConnectInit; + HS_PLUGIN_START_POST_CONNECT_AUTH  HSPluginStartPostConnectAuth; + HS_PLUGIN_STOP_POST_CONNECT_AUTH   HSPluginStopPostConnectAuth; + HS_PLUGIN_DISCONNECT_FROM_NETWORK HSPluginDisconnectFromNetwork; + HS_PLUGIN_RESET                    HSPluginReset; + HS_PLUGIN_SEND_KEEP_ALIVE          HSPluginSendKeepAlive; + HS_PLUGIN_CHECK_FOR_UPDATES        HSPluginCheckForUpdates; + HS_PLUGIN_DEINIT                   HSPluginDeinit; +} HOTSPOT_PLUGIN_APIS, *PHOTSPOT_PLUGIN_APIS; +``` + +Members +------- + +**HSPluginQuerySupportedSIMs** +API called during plugin initialization. + +Called by the hotspot host to retrieve the list of SIMs that the plugin supports. It can be called to retrieve the complete list of supported SIMs, or just the SIMs for a specific network. For more information, see [**HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS**](hs-plugin-query-supported-sims.md). + +**HSPluginQueryCellularExceptionHosts** +API called during plugin initialization. + +Called by the hotspot host if the plugin has specified the **HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_HIDDEN** capability by way of the [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure. For more information, see [**HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK**](hs-plugin-query-hidden-network.md). + +**HSPluginIsHotspotNetwork** +API called while processing scan results. + +Called by the hotspot host to request the plugin to identify if the network passed in the *pHiddenNetworkIdentity* parameter is a hotspot network. For more information, see [**HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK**](hs-plugin-is-hotspot-network.md). + +**HSPluginPreConnectInit** +Connection-process API. + +Called by the hotspot host to notify the plugin to initialize its state when a connection is in progress. For more information, see [**HS\_PLUGIN\_PRE\_CONNECT\_INIT**](hs-plugin-pre-connect-init.md). + +**HSPluginStartPostConnectAuth** +Connection-process API. + +Called by the hotspot host to request the plugin to perform any post-connect authentication required to authenticate the device over the network. For more information, see [**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md). + +**HSPluginStopPostConnectAuth** +Connection-process API. + +Called by the hotspot host to notify the plugin to stop the authentication process. For more information, see [**HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH**](hs-plugin-stop-post-connect-auth.md). + +**HSPluginDisconnectFromNetwork** +Connection-process API. + +Called by the hotspot host to notify the plugin of disconnection from network. For more information, see [**HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK**](hs-plugin-disconnect-from-network.md). + +**HSPluginReset** +API to reset the plugin. If the plugin does not release any pending calls before returning from this call, the plugin will be unloaded. + +Called by the hotspot host to reset the plugin. For more information, see [**HS\_PLUGIN\_RESET**](hs-plugin-reset.md). + +**HSPluginSendKeepAlive** +API for plugin to do periodic updates. + +Called by the hotspot host to send a keep-alive message to the plugin. For more information, see [**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md). + +**HSPluginCheckForUpdates** +API for plugin to do periodic updates. + +Called by the hotspot host to check for updates. For more information, see [**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md). + +**HSPluginDeinit** +API called to de-initialize and clean up the plugin before unloading. + +Called by the hotspot host to notify the plugin that it is about to be unloaded. For more information, see [**HS\_PLUGIN\_DEINIT**](hs-plugin-deinit.md). + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HSPluginInitPlugin**](hsplugininitplugin.md) + +[**HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS**](hs-plugin-query-supported-sims.md) + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +[**HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK**](hs-plugin-query-hidden-network.md) + +[**HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK**](hs-plugin-is-hotspot-network.md) + +[**HS\_PLUGIN\_PRE\_CONNECT\_INIT**](hs-plugin-pre-connect-init.md) + +[**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md) + +[**HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH**](hs-plugin-stop-post-connect-auth.md) + +[**HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK**](hs-plugin-disconnect-from-network.md) + +[**HS\_PLUGIN\_RESET**](hs-plugin-reset.md) + +[**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md) + +[**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md) + +[**HS\_PLUGIN\_DEINIT**](hs-plugin-deinit.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HOTSPOT_PLUGIN_APIS%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-connection-context.md b/windows-driver-docs-pr/network/hs-connection-context.md new file mode 100644 index 0000000000..c1f9489064 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-connection-context.md @@ -0,0 +1,75 @@ +--- +title: HS\_CONNECTION\_CONTEXT structure +author: windows-driver-content +description: The HS\_CONNECTION\_CONTEXT structure contains the information required by the plugin for post connect authentication. +ms.assetid: 22b219fc-691b-4813-a523-a76de037e64d +keywords: +- HS_CONNECTION_CONTEXT structure Network Drivers Starting with Windows Vista +- PHS_CONNECTION_CONTEXT structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_CONNECTION\_CONTEXT structure + + +The **HS\_CONNECTION\_CONTEXT** structure contains the information required by the plugin for post connect authentication. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_CONNECTION_CONTEXT { + HS_MAC_ADDRESS  MacAddress; + HS_SIM_IDENTITY SIMIdentity; + WCHAR           pszPhoneNumber[HS_MAX_PHONE_NUMBER_LENGTH+1]; +} HS_CONNECTION_CONTEXT, *PHS_CONNECTION_CONTEXT; +``` + +Members +------- + +**MacAddress** +The [**HS\_MAC\_ADDRESS**](hs-mac-address.md) structure that contains the MAC address. + +**SIMIdentity** +The [**HS\_SIM\_IDENTITY**](hs-sim-identity.md) structure that contains information required for EAP-SIM/AKA authentication. + +**pszPhoneNumber** +Pointer to the phone number. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_MAC\_ADDRESS**](hs-mac-address.md) + +[**HS\_SIM\_IDENTITY**](hs-sim-identity.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_CONNECTION_CONTEXT%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-device-identity.md b/windows-driver-docs-pr/network/hs-device-identity.md new file mode 100644 index 0000000000..6309d6cef3 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-device-identity.md @@ -0,0 +1,76 @@ +--- +title: HS\_DEVICE\_IDENTITY structure +author: windows-driver-content +description: The HS\_DEVICE\_IDENTITY structure contains information about the device model and manufacturer. +ms.assetid: 4a679fb2-d5b1-4635-9422-a21a316b360c +keywords: +- HS_DEVICE_IDENTITY structure Network Drivers Starting with Windows Vista +- PHS_DEVICE_IDENTITY structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_DEVICE\_IDENTITY structure + + +The **HS\_DEVICE\_IDENTITY** structure contains information about the device model and manufacturer. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_DEVICE_IDENTITY { + DWORD dwSystemType; + WCHAR wszPhoneManufacturer[HS_CONST_MAX_DEVICE_INFO_LENGTH+1]; + WCHAR wszPhoneModelName[HS_CONST_MAX_DEVICE_INFO_LENGTH+1]; + WCHAR wszPhoneManufacturerModel[HS_CONST_MAX_DEVICE_INFO_LENGTH+1]; + WCHAR wszDeviceModel[HS_CONST_MAX_DEVICE_INFO_LENGTH+1]; +} HS_DEVICE_IDENTITY, *PHS_DEVICE_IDENTITY; +``` + +Members +------- + +**dwSystemType** +The type of SIM, whether GSM or CDMA. + +**wszPhoneManufacturer** +The phone manufacturer name. + +**wszPhoneModelName** +The phone model name. + +**wszPhoneManufacturerModel** +Another name for the phone manufacturer and model. + +**wszDeviceModel** +The device model name. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_DEVICE_IDENTITY%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-allocate-memory.md b/windows-driver-docs-pr/network/hs-host-allocate-memory.md new file mode 100644 index 0000000000..6172218d16 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-allocate-memory.md @@ -0,0 +1,76 @@ +--- +title: HS\_HOST\_ALLOCATE\_MEMORY function +author: windows-driver-content +description: The HS\_HOST\_ALLOCATE\_MEMORY function returns an amount of memory specified by the caller. +ms.assetid: afa59680-d85b-4be5-8642-152ff653a0b0 +keywords: +- (WINAPI HS_HOST_ALLOCATE_MEMORY) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_ALLOCATE\_MEMORY function + + +The **HS\_HOST\_ALLOCATE\_MEMORY** function returns an amount of memory specified by the caller. + +Syntax +------ + +```ManagedCPlusPlus + (WINAPI *HS_HOST_ALLOCATE_MEMORY)( + _In_  HANDLE                        hPluginContext, + _In_  DWORD                         dwByteCount, + _Out_ _bcount (dwByteCount) LPVOID* ppvBuffer +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*dwByteCount* \[in\] +The amount of memory to allocate. + +*ppvBuffer* \[out\] +Pointer to the buffer that contains the allocated memory. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_ALLOCATE_MEMORY%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-free-memory.md b/windows-driver-docs-pr/network/hs-host-free-memory.md new file mode 100644 index 0000000000..e1b3300865 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-free-memory.md @@ -0,0 +1,77 @@ +--- +title: HS\_HOST\_FREE\_MEMORY function +author: windows-driver-content +description: The HS\_HOST\_FREE\_MEMORY function frees any memory that was allocated earlier by a call to HS\_HOST\_ALLOCATE\_MEMORY. +ms.assetid: 2090ecf8-e1d5-4410-acbf-1b97f418e185 +keywords: +- typedef VOID (WINAPI HS_HOST_FREE_MEMORY) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_FREE\_MEMORY function + + +The **HS\_HOST\_FREE\_MEMORY** function frees any memory that was allocated earlier by a call to [**HS\_HOST\_ALLOCATE\_MEMORY**](hs-host-allocate-memory.md). + +Syntax +------ + +```ManagedCPlusPlus + typedef VOID (WINAPI *HS_HOST_FREE_MEMORY)( + _In_     HANDLE hPluginContext, + _In_opt_ LPVOID pvBuffer +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*pvBuffer* \[in, optional\] +Pointer to the memory buffer. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_HOST\_ALLOCATE\_MEMORY**](hs-host-allocate-memory.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_FREE_MEMORY%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-post-connect-auth-completion.md b/windows-driver-docs-pr/network/hs-host-post-connect-auth-completion.md new file mode 100644 index 0000000000..37c59d0724 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-post-connect-auth-completion.md @@ -0,0 +1,92 @@ +--- +title: HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION function +author: windows-driver-content +description: The HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION function indicates the success or failure of an authentication attempt following a Wi-Fi connection setup at layer 2. +ms.assetid: 2c69802b-968b-400c-b02c-c2d39fa51d5a +keywords: +- typedef DWORD (WINAPI HS_HOST_POST_CONNECT_AUTH_COMPLETION) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION function + + +The **HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION** function indicates the success or failure of an authentication attempt following a Wi-Fi connection setup at layer 2. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_HOST_POST_CONNECT_AUTH_COMPLETION)( + _In_     HANDLE                    hPluginContext, + _In_     DWORD                     dwConnectionId, + _In_     eHS_AUTHENTICATION_RESULT AuthResult, + _In_opt_ LPVOID                    pvReserved +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*dwConnectionId* \[in\] +Unique identifier for the network connection. + +*AuthResult* \[in\] +The [**eHS\_AUTHENTICATION\_RESULT**](ehs-authentication-result.md) enumeration value that indicates success or failure. + +*pvReserved* \[in, optional\] +Reserved for future use. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Remarks +------- + +The plugin must call this function to inform the host of the result of a previous call to [**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**eHS\_AUTHENTICATION\_RESULT**](ehs-authentication-result.md) + +[**HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH**](hs-plugin-start-post-connect-auth.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_POST_CONNECT_AUTH_COMPLETION%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-send-keep-alive-completion.md b/windows-driver-docs-pr/network/hs-host-send-keep-alive-completion.md new file mode 100644 index 0000000000..2439ef5666 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-send-keep-alive-completion.md @@ -0,0 +1,82 @@ +--- +title: HS\_HOST\_SEND\_KEEP\_ALIVE\_COMPLETION function +author: windows-driver-content +description: The HS\_HOST\_SEND\_KEEP\_ALIVE\_COMPLETION function indicates the success or failure of a request for a network send keep-alive message. +ms.assetid: 19fc1210-2c3a-46ca-96fb-dccafa9e9eef +keywords: +- typedef DWORD (WINAPI HS_HOST_SEND_KEEP_ALIVE_COMPLETION) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_SEND\_KEEP\_ALIVE\_COMPLETION function + + +The **HS\_HOST\_SEND\_KEEP\_ALIVE\_COMPLETION** function indicates the success or failure of a request for a network send keep-alive message. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_HOST_SEND_KEEP_ALIVE_COMPLETION)( + _In_ HANDLE hPluginContext, + _In_ DWORD  dwResult +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*dwResult* \[in\] +The result code. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Remarks +------- + +The plugin must call this function to inform the host of the result of a previous call to [**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_SEND\_KEEP\_ALIVE**](hs-plugin-send-keep-alive.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_SEND_KEEP_ALIVE_COMPLETION%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-send-user-message.md b/windows-driver-docs-pr/network/hs-host-send-user-message.md new file mode 100644 index 0000000000..34a04b2c1c --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-send-user-message.md @@ -0,0 +1,81 @@ +--- +title: HS\_HOST\_SEND\_USER\_MESSAGE function +author: windows-driver-content +description: The HS\_HOST\_SEND\_USER\_MESSAGE function is called to communicate with the user. The message content is contained in custom UI display strings that are passed to the hotspot offload service. +ms.assetid: c4ab1fda-18eb-44e4-aa64-f7b37b4147a3 +keywords: +- typedef DWORD (WINAPI HS_HOST_SEND_USER_MESSAGE) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_SEND\_USER\_MESSAGE function + + +The **HS\_HOST\_SEND\_USER\_MESSAGE** function is called to communicate with the user. The message content is contained in custom UI display strings that are passed to the hotspot offload service. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_HOST_SEND_USER_MESSAGE)( + _In_ HANDLE hPluginContext, + _In_ DWORD  dwConnectionId, + _In_ DWORD  dwStringID +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*dwConnectionId* \[in\] +Unique identifier for the network connection. + +*dwStringID* \[in\] +The string ID, used as an index into the string table where the message is stored. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Remarks +------- + +The hotspot plugin stores the messages in a string table. The plugin must pass the string IDs to the hotspot offload service to enable it to load the appropriate strings. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_SEND_USER_MESSAGE%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-host-update-configuration-completion.md b/windows-driver-docs-pr/network/hs-host-update-configuration-completion.md new file mode 100644 index 0000000000..fb627c16ed --- /dev/null +++ b/windows-driver-docs-pr/network/hs-host-update-configuration-completion.md @@ -0,0 +1,84 @@ +--- +title: HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION function +author: windows-driver-content +description: The HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION function indicates the success or failure of a request to check for updates. +ms.assetid: 7e9eda04-db8e-4181-90e3-8716a99429a8 +keywords: +- typedef DWORD (WINAPI HS_HOST_UPDATE_CONFIGURATION_COMPLETION) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION function + + +The **HS\_HOST\_UPDATE\_CONFIGURATION\_COMPLETION** function indicates the success or failure of a request to check for updates. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_HOST_UPDATE_CONFIGURATION_COMPLETION)( + _In_ HANDLE            hPluginContext, + _In_ eHS_UPDATE_RESULT UpdateResult +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +Context handle for the plugin making the call to this function. + +*UpdateResult* \[in\] +The [**eHS\_UPDATE\_RESULT**](ehs-update-result.md) enumeration value that indicates the result of the request to check for updates. + +Return value +------------ + +This function is called by the plugin to communicate with the host and does not return a value. + +Remarks +------- + +The plugin must call this function to inform the host of the result of a previous call to [**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**eHS\_UPDATE\_RESULT**](ehs-update-result.md) + +[**HS\_PLUGIN\_CHECK\_FOR\_UPDATES**](hs-plugin-check-for-updates.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_HOST_UPDATE_CONFIGURATION_COMPLETION%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-mac-address.md b/windows-driver-docs-pr/network/hs-mac-address.md new file mode 100644 index 0000000000..0733c84366 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-mac-address.md @@ -0,0 +1,60 @@ +--- +title: HS\_MAC\_ADDRESS structure +author: windows-driver-content +description: The HS\_MAC\_ADDRESS structure contains the host Media Access Control (MAC) address. +ms.assetid: 2d632ed4-4522-48ae-b23d-927517185d73 +keywords: +- HS_MAC_ADDRESS structure Network Drivers Starting with Windows Vista +- PHS_MAC_ADDRESS structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_MAC\_ADDRESS structure + + +The **HS\_MAC\_ADDRESS** structure contains the host Media Access Control (MAC) address. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_MAC_ADDRESS { + UCHAR ucHSMacAddress[6]; +} HS_MAC_ADDRESS, *PHS_MAC_ADDRESS; +``` + +Members +------- + +**ucHSMacAddress** +The MAC address. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_MAC_ADDRESS%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-network-identity.md b/windows-driver-docs-pr/network/hs-network-identity.md new file mode 100644 index 0000000000..f2484e427c --- /dev/null +++ b/windows-driver-docs-pr/network/hs-network-identity.md @@ -0,0 +1,68 @@ +--- +title: HS\_NETWORK\_IDENTITY structure +author: windows-driver-content +description: The HS\_NETWORK\_IDENTITY structure contains information that uniquely identifies a Wi-Fi network. +ms.assetid: 40d9720b-c122-4d19-8907-cfa2a05014e7 +keywords: +- HS_NETWORK_IDENTITY structure Network Drivers Starting with Windows Vista +- PHS_NETWORK_IDENTITY structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_NETWORK\_IDENTITY structure + + +The **HS\_NETWORK\_IDENTITY** structure contains information that uniquely identifies a Wi-Fi network. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_NETWORK_IDENTITY { + HS_SSID             Ssid; + HS_AUTH_ALGORITHM   hsAuthAlgo; + HS_CIPHER_ALGORITHM hsCipherAlgo; +} HS_NETWORK_IDENTITY, *PHS_NETWORK_IDENTITY; +``` + +Members +------- + +**Ssid** +The network SSID. + +**hsAuthAlgo** +The authentication algorithm used by the wireless network. + +**hsCipherAlgo** +The cipher algorithm used by the wireless network. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_NETWORK_IDENTITY%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-network-profile.md b/windows-driver-docs-pr/network/hs-network-profile.md new file mode 100644 index 0000000000..cdf8505184 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-network-profile.md @@ -0,0 +1,91 @@ +--- +title: HS\_NETWORK\_PROFILE structure +author: windows-driver-content +description: The HS\_NETWORK\_PROFILE structure is provided by the plugin and contains information required for connection to the target network. Each instance of the Network Profile is uniquely associated with a corresponding HS\_NETWORK\_IDENTITY structure. +ms.assetid: 55e8786c-d7b8-48f3-9e54-312183cf8fb3 +keywords: +- HS_NETWORK_PROFILE structure Network Drivers Starting with Windows Vista +- PHS_NETWORK_PROFILE structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_NETWORK\_PROFILE structure + + +The **HS\_NETWORK\_PROFILE** structure is provided by the plugin and contains information required for connection to the target network. Each instance of the Network Profile is uniquely associated with a corresponding [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_NETWORK_PROFILE { + DWORD  dwNetworkCapabilities; + USHORT usPriority; + DWORD  dwSupportedSIMCount; + DWORD  dmNumCellularExceptions; + DWORD  dwNetworkStringID; + DWORD  dwKeepAliveTimeMins; + WCHAR  szRealm[HS_CONST_MAX_REALM_LENGTH+1]; +} HS_NETWORK_PROFILE, *PHS_NETWORK_PROFILE; +``` + +Members +------- + +**dwNetworkCapabilities** +A subset of the possible **HS\_FLAG\_CAPABILITY\_NETWORK\_\*** values. For more information about hotspot host capabilities, see [**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md). + +**usPriority** +A unique priority value assigned to the associated network. It must be a value between 1 and 65000 (a hidden network must have a value of 1). A lower numeric value corresponds to a higher priority. + +**dwSupportedSIMCount** +Supported SIM count. This member is set for HTTP-based and EAP-SIM/AKA/AKA' authentication. + +**dmNumCellularExceptions** +Optional. Number of host connections over cellular only. + +**dwNetworkStringID** +Network name string ID. Maximum string size = MAX\_NETWORK\_DISPLAY\_NAME\_LENGTH. + +**dwKeepAliveTimeMins** +Optional. The time interval between network connection keep-alive messages. + +**szRealm** +Network-specific realm value. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +[**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_NETWORK_PROFILE%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-cellular-exception-hosts.md b/windows-driver-docs-pr/network/hs-plugin-cellular-exception-hosts.md new file mode 100644 index 0000000000..8a3e5ed52c --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-cellular-exception-hosts.md @@ -0,0 +1,79 @@ +--- +title: HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS structure +author: windows-driver-content +description: The HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS structure contains the list of hosts that the plugin requires to be connected over a cellular bearer only during the authentication process. +ms.assetid: cc7ad05b-d03b-463a-9d22-1982aee882e8 +keywords: +- HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS structure Network Drivers Starting with Windows Vista +- PHS_PLUGIN_CELLULAR_EXCEPTION_HOSTS structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS structure + + +The **HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS** structure contains the list of hosts that the plugin requires to be connected over a cellular bearer only during the authentication process. This is an optional capability that can be requested by the plugin. For more information, see [**HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS**](hs-plugin-query-cellular-exception-hosts.md). + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS { + DWORD               dwCount; + HS_PLUGIN_HOST_NAME pExceptions[*]; + HS_PLUGIN_HOST_NAME pExceptions[1]; +} HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS, *PHS_PLUGIN_CELLULAR_EXCEPTION_HOSTS; +``` + +Members +------- + +**dwCount** +The number of host names in the list pointed to by **pExceptions**. + +**pExceptions** +Used if MIDL is utilized. Unique, size is (dwCount). + +Pointer to the list of host names. + +**pExceptions** +Used if MIDL is not utilized. + +Pointer to the list of host names. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS**](hs-plugin-query-cellular-exception-hosts.md) + +[Microsoft Interface Definition Language](https://msdn.microsoft.com//library/windows/desktop/aa367091) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-check-for-updates.md b/windows-driver-docs-pr/network/hs-plugin-check-for-updates.md new file mode 100644 index 0000000000..b7f6a7a7b4 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-check-for-updates.md @@ -0,0 +1,74 @@ +--- +title: HS\_PLUGIN\_CHECK\_FOR\_UPDATES function +author: windows-driver-content +description: The HS\_PLUGIN\_CHECK\_FOR\_UPDATES function checks for configuration updates at the frequency specified in the dwProfileUpdateTimeDays member of the plugin’s HS\_PLUGIN\_PROFILE structure. +ms.assetid: 8db3c237-d61b-4dca-b3a5-2fdaeb683b15 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_CHECK_FOR_UPDATES) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_CHECK\_FOR\_UPDATES function + + +The **HS\_PLUGIN\_CHECK\_FOR\_UPDATES** function checks for configuration updates at the frequency specified in the **dwProfileUpdateTimeDays** member of the plugin’s [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_CHECK_FOR_UPDATES)( +   +); +``` + +Parameters +---------- + +This function has no parameters. + +** + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_CHECK_FOR_UPDATES%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-deinit.md b/windows-driver-docs-pr/network/hs-plugin-deinit.md new file mode 100644 index 0000000000..73e6569723 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-deinit.md @@ -0,0 +1,78 @@ +--- +title: HS\_PLUGIN\_DEINIT function +author: windows-driver-content +description: The HS\_PLUGIN\_DEINIT function is called by the host to notify the plugin that it will be unloaded. +ms.assetid: 3bb0ad85-91db-476e-b347-0fa8ed4ae24e +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_DEINIT) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_DEINIT function + + +The **HS\_PLUGIN\_DEINIT** function is called by the host to notify the plugin that it will be unloaded. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_DEINIT)( + _In_ eHS_UNLOAD_REASON UnloadReason +); +``` + +Parameters +---------- + +*UnloadReason* \[in\] +An [**eHS\_UNLOAD\_REASON**](ehs-unload-reason.md) enumeration value that indicates the reason for the unload. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +Upon receiving notification that it will be unloaded, the plugin should complete any current activity and save state, if required. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**eHS\_UNLOAD\_REASON**](ehs-unload-reason.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_DEINIT%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-disconnect-from-network.md b/windows-driver-docs-pr/network/hs-plugin-disconnect-from-network.md new file mode 100644 index 0000000000..eebd8837b0 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-disconnect-from-network.md @@ -0,0 +1,73 @@ +--- +title: HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK function +author: windows-driver-content +description: The HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK function notifies the plugin that the device will be disconnected from the network. +ms.assetid: 8a53c824-18f7-4000-b264-fe852595a9e3 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_DISCONNECT_FROM_NETWORK) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK function + + +The **HS\_PLUGIN\_DISCONNECT\_FROM\_NETWORK** function notifies the plugin that the device will be disconnected from the network. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_DISCONNECT_FROM_NETWORK)( + _In_ HS_NETWORK_IDENTITY *pNetworkIdentity +); +``` + +Parameters +---------- + +*\*pNetworkIdentity* \[in\] +Pointer to the [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure for the network from which the device is to be disconnected. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_DISCONNECT_FROM_NETWORK%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-host-name.md b/windows-driver-docs-pr/network/hs-plugin-host-name.md new file mode 100644 index 0000000000..cabdbff866 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-host-name.md @@ -0,0 +1,60 @@ +--- +title: HS\_PLUGIN\_HOST\_NAME structure +author: windows-driver-content +description: The HS\_PLUGIN\_HOST\_NAME structure contains the host name. +ms.assetid: 3995fff6-6992-4dd6-a94c-a27b2ee44436 +keywords: +- HS_PLUGIN_HOST_NAME structure Network Drivers Starting with Windows Vista +- PHS_PLUGIN_HOST_NAME structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_HOST\_NAME structure + + +The **HS\_PLUGIN\_HOST\_NAME** structure contains the host name. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_PLUGIN_HOST_NAME { + WHCAR pszHostName[HS_CONST_MAX_HOST_NAME_LENGTH+1]; +} HS_PLUGIN_HOST_NAME, *PHS_PLUGIN_HOST_NAME; +``` + +Members +------- + +**pszHostName** +Pointer to the host name. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_HOST_NAME%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-is-hotspot-network.md b/windows-driver-docs-pr/network/hs-plugin-is-hotspot-network.md new file mode 100644 index 0000000000..3eeb07419a --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-is-hotspot-network.md @@ -0,0 +1,85 @@ +--- +title: HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK function +author: windows-driver-content +description: The HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK function is called by the host to determine if a specified network is a hotspot network. +ms.assetid: 24a26ee0-9eb1-49fa-95da-40315a4aab3a +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_IS_HOTSPOT_NETWORK) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK function + + +The **HS\_PLUGIN\_IS\_HOTSPOT\_NETWORK** function is called by the host to determine if a specified network is a hotspot network. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_IS_HOTSPOT_NETWORK)( + _In_      HS_NETWORK_IDENTITY *pNetworkIdentity, + _Out_     eHS_NETWORK_STATE   *pNetworkState, + _Out_opt_ HS_NETWORK_PROFILE  *pNetworkProfile +); +``` + +Parameters +---------- + +*\*pNetworkIdentity* \[in\] +Pointer to the [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure for the network from which the device is to be disconnected. + +*\*pNetworkState* \[out\] +An [**eHS\_NETWORK\_STATE**](ehs-network-state.md) enumeration value that indicates the type of network. + +*\*pNetworkProfile* \[out, optional\] +Pointer to the [**HS\_NETWORK\_PROFILE**](hs-network-profile.md) structure for the network. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +[**eHS\_NETWORK\_STATE**](ehs-network-state.md) + +[**HS\_NETWORK\_PROFILE**](hs-network-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_IS_HOTSPOT_NETWORK%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-pre-connect-init.md b/windows-driver-docs-pr/network/hs-plugin-pre-connect-init.md new file mode 100644 index 0000000000..54b070ee0e --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-pre-connect-init.md @@ -0,0 +1,73 @@ +--- +title: HS\_PLUGIN\_PRE\_CONNECT\_INIT function +author: windows-driver-content +description: The HS\_PLUGIN\_PRE\_CONNECT\_INIT function is called to notify the plugin to initialize its state when a connection to a hotspot network is in progress. +ms.assetid: 799242a0-144f-4d3f-b48c-9e96a851d8c4 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_PRE_CONNECT_INIT) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_PRE\_CONNECT\_INIT function + + +The **HS\_PLUGIN\_PRE\_CONNECT\_INIT** function is called to notify the plugin to initialize its state when a connection to a hotspot network is in progress. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_PRE_CONNECT_INIT)( + _In_ HS_NETWORK_IDENTITY *pNetworkIdentity +); +``` + +Parameters +---------- + +*\*pNetworkIdentity* \[in\] +Pointer to the [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure for the target network. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_PRE_CONNECT_INIT%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-profile.md b/windows-driver-docs-pr/network/hs-plugin-profile.md new file mode 100644 index 0000000000..479ba94a09 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-profile.md @@ -0,0 +1,109 @@ +--- +title: HS\_PLUGIN\_PROFILE structure +author: windows-driver-content +description: The HS\_PLUGIN\_PROFILE structure provides information about the plugin. The members of this structure are set by the plugin during execution of the HSPluginInitPlugin function that is called by the host. +ms.assetid: 0c4f7088-737e-479a-b46e-a55e96719775 +keywords: +- HS_PLUGIN_PROFILE structure Network Drivers Starting with Windows Vista +- PHS_PLUGIN_PROFILE structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_PROFILE structure + + +The **HS\_PLUGIN\_PROFILE** structure provides information about the plugin. The members of this structure are set by the plugin during execution of the [**HSPluginInitPlugin**](hsplugininitplugin.md) function that is called by the host. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_PLUGIN_PROFILE { + DWORD dwPluginCapabilities; + DWORD dwNumNetworksSupported; + DWORD dwProviderNameStringID; + DWORD dwGenericNetworkNameStringID; + DWORD dwAdvancedPageStringID; + DWORD dwProfileUpdateTimeDays; + WCHAR szRealm[HS_CONST_MAX_REALM_LENGTH+1]; + DWORD dwSupportedSIMCount; +} HS_PLUGIN_PROFILE, *PHS_PLUGIN_PROFILE; +``` + +Members +------- + +**dwPluginCapabilities** +Required. + +A subset of the possible **HS\_FLAG\_CAPABILITY\_NETWORK\_\*** values. For more information about hotspot host capabilities, see [**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md). + +**dwNumNetworksSupported** +Required. + +Total number of networks supported by this plugin. + +**dwProviderNameStringID** +Required. + +The network provider name which is displayed to the user. Maximum string size = MAX\_PROVIDER\_NAME\_LENGTH. + +**dwGenericNetworkNameStringID** +Optional. + +Network name. Maximum string size = MAX\_NETWORK\_DISPLAY\_NAME\_LENGTH. + +**dwAdvancedPageStringID** +Optional. + +Maximum string size = HS\_CONST\_MAX\_ADVANCED\_PAGE\_STRING\_LENGTH. + +**dwProfileUpdateTimeDays** +Optional. + +Must be greater than or equal to HS\_CONST\_MIN\_PROFILE\_UPDATE\_TIME\_IN\_DAYS. + +**szRealm** +Required if HS\_FLAG\_CAPABILITIES\_NETWORK\_CUSTOM\_REALM is set. + +Network-specific realm value. + +**dwSupportedSIMCount** +The size of the list pointed to by **pSupported SIMs**. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HSPluginInitPlugin**](hsplugininitplugin.md) + +[**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_PROFILE%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-query-cellular-exception-hosts.md b/windows-driver-docs-pr/network/hs-plugin-query-cellular-exception-hosts.md new file mode 100644 index 0000000000..4e2581b591 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-query-cellular-exception-hosts.md @@ -0,0 +1,80 @@ +--- +title: HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS function +author: windows-driver-content +description: The HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS function queries the list of hosts that the plugin will need to connect to over cellular as part of its authentication process. +ms.assetid: 7f38f146-a637-4ec3-8610-ea4934c4a57a +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS function + + +The **HS\_PLUGIN\_QUERY\_CELLULAR\_EXCEPTION\_HOSTS** function queries the list of hosts that the plugin will need to connect to over cellular as part of its authentication process. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS)( + _Inout_ HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS *pExceptionsList +); +``` + +Parameters +---------- + +*\*pExceptionsList* \[in, out\] +The [**HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS**](hs-plugin-cellular-exception-hosts.md) structure that contains the list of cellular host names. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +This function is called only if the plugin sets the **dwNumCellularExceptions** field of its [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) to a value greater than zero. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_CELLULAR\_EXCEPTION\_HOSTS**](hs-plugin-cellular-exception-hosts.md) + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-query-hidden-network.md b/windows-driver-docs-pr/network/hs-plugin-query-hidden-network.md new file mode 100644 index 0000000000..21c7ca5252 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-query-hidden-network.md @@ -0,0 +1,92 @@ +--- +title: HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK function +author: windows-driver-content +description: The HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK function returns the network identity and network profile for a hidden network. +ms.assetid: edf5ddb0-22f6-4c24-a118-3915a1f2b0af +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_QUERY_HIDDEN_NETWORK) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK function + + +The **HS\_PLUGIN\_QUERY\_HIDDEN\_NETWORK** function returns the network identity and network profile for a hidden network. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_QUERY_HIDDEN_NETWORK)( + _Out_ HS_NETWORK_IDENTITY *pHiddenNetworkIdentity, + _Out_ HS_NETWORK_PROFILE  *pHiddenNetworkProfile +); +``` + +Parameters +---------- + +*\*pHiddenNetworkIdentity* \[out\] +The [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure that uniquely identifies the network. + +*\*pHiddenNetworkProfile* \[out\] +The [**HS\_NETWORK\_PROFILE**](hs-network-profile.md) structure that contains the network profile. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +The host calls this function only if the **dwPluginCapabilities** field of the associated plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure includes the **HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_HIDDEN** capability. + +The plugin must provide both the network identity and the network profile for the hidden Wi-Fi network. + +This network must have the highest priority (1) among all the hotspot networks. + +The hotspot offload service imposes a limitation of one hidden network for the life of the service. Therefore, in the case where there are multiple plugins installed, only the first plugin's request to specify a hidden network will be accepted. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +[**HS\_NETWORK\_PROFILE**](hs-network-profile.md) + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_QUERY_HIDDEN_NETWORK%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-query-supported-sims.md b/windows-driver-docs-pr/network/hs-plugin-query-supported-sims.md new file mode 100644 index 0000000000..07fb54223d --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-query-supported-sims.md @@ -0,0 +1,84 @@ +--- +title: HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS function +author: windows-driver-content +description: The HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS function returns the list of SIMs that the plugin supports. +ms.assetid: e1b41bb1-7f82-4298-b070-20cb557fa0fc +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_QUERY_SUPPORTED_SIMS) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS function + + +The **HS\_PLUGIN\_QUERY\_SUPPORTED\_SIMS** function returns the list of SIMs that the plugin supports. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_QUERY_SUPPORTED_SIMS)( + _In_opt_ HS_NETWORK_IDENTITY      *pNetworkIdentity, + _Inout_  HS_PLUGIN_SUPPORTED_SIMS *pSupportedSIMs +); +``` + +Parameters +---------- + +*\*pNetworkIdentity* \[in, optional\] +The [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure that uniquely identifies the network. + +*\*pSupportedSIMs* \[in, out\] +Pointer to an array of one or more [**HS\_PLUGIN\_SUPPORTED\_SIMS**](hs-plugin-supported-sims.md) structures that contains the list of supported SIMs. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +If the *pNetworkIdentity* parameter exists then only those SIM identities required for connecting to the specified network must be provided, otherwise the entire list of SIMs for connecting to all networks must be provided. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +[**HS\_PLUGIN\_SUPPORTED\_SIMS**](hs-plugin-supported-sims.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_QUERY_SUPPORTED_SIMS%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-reset.md b/windows-driver-docs-pr/network/hs-plugin-reset.md new file mode 100644 index 0000000000..6450c9f81d --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-reset.md @@ -0,0 +1,76 @@ +--- +title: HS\_PLUGIN\_RESET function +author: windows-driver-content +description: The HS\_PLUGIN\_RESET function is called by the host to notify the plugin that it must reset its state. +ms.assetid: 9f5683c9-b426-4802-85bd-c1ce770b9e46 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_RESET) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_RESET function + + +The **HS\_PLUGIN\_RESET** function is called by the host to notify the plugin that it must reset its state. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_RESET)( +   +); +``` + +Parameters +---------- + +This function has no parameters. + +** + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +The plugin should terminate all threads and stop any activities in progress. + +The plugin is unloaded if it fails to reset. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_RESET%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-send-keep-alive.md b/windows-driver-docs-pr/network/hs-plugin-send-keep-alive.md new file mode 100644 index 0000000000..0343ea16cc --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-send-keep-alive.md @@ -0,0 +1,74 @@ +--- +title: HS\_PLUGIN\_SEND\_KEEP\_ALIVE function +author: windows-driver-content +description: The HS\_PLUGIN\_SEND\_KEEP\_ALIVE function is called by the host to send a network connection keep-alive message. It will be called at the frequency specified in the dwKeepAliveTimeMins member of the plugin's HS\_PLUGIN\_PROFILE structure. +ms.assetid: 1db91146-03bb-4513-9c1b-f0dbd5c941f5 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_SEND_KEEP_ALIVE) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_SEND\_KEEP\_ALIVE function + + +The **HS\_PLUGIN\_SEND\_KEEP\_ALIVE** function is called by the host to send a network connection keep-alive message. It will be called at the frequency specified in the **dwKeepAliveTimeMins** member of the plugin's [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_SEND_KEEP_ALIVE)( +   +); +``` + +Parameters +---------- + +This function has no parameters. + +** + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_SEND_KEEP_ALIVE%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-start-post-connect-auth.md b/windows-driver-docs-pr/network/hs-plugin-start-post-connect-auth.md new file mode 100644 index 0000000000..bb504d1128 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-start-post-connect-auth.md @@ -0,0 +1,102 @@ +--- +title: HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH function +author: windows-driver-content +description: The HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH function is called to perform any post-connect authentication required to authenticate the device over the network. +ms.assetid: f52236fc-2afd-46e2-ae88-7c4fa10f8d59 +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_START_POST_CONNECT_AUTH) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH function + + +The **HS\_PLUGIN\_START\_POST\_CONNECT\_AUTH** function is called to perform any post-connect authentication required to authenticate the device over the network. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_START_POST_CONNECT_AUTH)( + _In_ DWORD                 dwConnectionId, + _In_ HS_CONNECTION_CONTEXT *pConnectContext, + _In_ HS_SIM_DATA           *pSIMData, + _In_ HS_NETWORK_IDENTITY   *pNetworkIdentity, + _In_ HS_NETWORK_PROFILE    *pNetworkProfile +); +``` + +Parameters +---------- + +*dwConnectionId* \[in\] +Unique identifier for the network connection. + +*\*pConnectContext* \[in\] +Pointer to a [**HS\_CONNECTION\_CONTEXT**](hs-connection-context.md) structure that contains the information required by the plugin for post-connect authentication. + +*\*pSIMData* \[in\] +Pointer to a [**HS\_SIM\_DATA**](hs-sim-data.md) structure that contains information from the SIM required by the plugin for post-connect authentication. + +*\*pNetworkIdentity* \[in\] +Pointer to the [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure for the network. + +*\*pNetworkProfile* \[in\] +Pointer to the [**HS\_NETWORK\_PROFILE**](hs-network-profile.md) structure that contains the network profile. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Remarks +------- + +After calling this function, the plugin must call the [**HS\_HOST\_POST\_CONNECT\_AUTH\_COMPLETION**](hs-host-post-connect-auth-completion.md) handler to inform the host of the status of the request. + +If the network uses EAP-SIM/AKA authentication, the plugin is not expected to perform any activity in this state. However, if the network requires HTTP-based authentication, the plugin must perform the appropriate authentication. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_CONNECTION\_CONTEXT**](hs-connection-context.md) + +[**HS\_SIM\_DATA**](hs-sim-data.md) + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +[**HS\_NETWORK\_PROFILE**](hs-network-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_START_POST_CONNECT_AUTH%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-stop-post-connect-auth.md b/windows-driver-docs-pr/network/hs-plugin-stop-post-connect-auth.md new file mode 100644 index 0000000000..d3504872a7 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-stop-post-connect-auth.md @@ -0,0 +1,73 @@ +--- +title: HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH function +author: windows-driver-content +description: The HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH function is called to notify the plugin to stop the authentication process. +ms.assetid: 2e4e01b1-e41a-41db-a3ca-6cc6b53b3a8b +keywords: +- typedef DWORD (WINAPI HS_PLUGIN_STOP_POST_CONNECT_AUTH) function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH function + + +The **HS\_PLUGIN\_STOP\_POST\_CONNECT\_AUTH** function is called to notify the plugin to stop the authentication process. + +Syntax +------ + +```ManagedCPlusPlus + typedef DWORD (WINAPI *HS_PLUGIN_STOP_POST_CONNECT_AUTH)( + _In_ HS_NETWORK_IDENTITY *pNetworkIdentity +); +``` + +Parameters +---------- + +*\*pNetworkIdentity* \[in\] +The [**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) structure that uniquely identifies the network. + +Return value +------------ + +This function is called by the host to communicate with the plugin and does not return a value. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_NETWORK\_IDENTITY**](hs-network-identity.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_STOP_POST_CONNECT_AUTH%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-supported-sims.md b/windows-driver-docs-pr/network/hs-plugin-supported-sims.md new file mode 100644 index 0000000000..3ff158d537 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-supported-sims.md @@ -0,0 +1,84 @@ +--- +title: HS\_PLUGIN\_SUPPORTED\_SIMS structure +author: windows-driver-content +description: The HS\_PLUGIN\_SUPPORTED\_SIMS structure contains the list of supported SIM configurations. This list must be supplied if the hotspot plugin requires HTTP or EAP authentication for any of its networks. +ms.assetid: 7ec8fb95-b227-4feb-882e-457a9ad6ec3e +keywords: +- HS_PLUGIN_SUPPORTED_SIMS structure Network Drivers Starting with Windows Vista +- PHS_PLUGIN_SUPPORTED_SIMS structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_SUPPORTED\_SIMS structure + + +The **HS\_PLUGIN\_SUPPORTED\_SIMS** structure contains the list of supported SIM configurations. This list must be supplied if the hotspot plugin requires HTTP or EAP authentication for any of its networks. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_PLUGIN_SUPPORTED_SIMS { + DWORD           dwCount; + HS_SIM_IDENTITY pSupportedSIMs[*]; + HS_SIM_IDENTITY pSupportedSIMs[1]; +} HS_PLUGIN_SUPPORTED_SIMS, *PHS_PLUGIN_SUPPORTED_SIMS; +``` + +Members +------- + +**dwCount** +The list size. + +**pSupportedSIMs** +Used if MIDL is utilized. Unique, size is (dwCount). + +An array of HS\_SIM\_IDENTITY structures that make up the list of supported SIM configurations. + +**pSupportedSIMs** +Used if MIDL is not utilized. + +An array of HS\_SIM\_IDENTITY structures that make up the list of supported SIM configurations. + +Remarks +------- + +In the **dwEapMethods** field of the [**HS\_SIM\_IDENTITY**](hs-sim-identity.md) structure for each SIM configuration, you must specify the EAP methods that it supports. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_SIM\_IDENTITY**](hs-sim-identity.md) + +[Microsoft Interface Definition Language](https://msdn.microsoft.com//library/windows/desktop/aa367091) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_SUPPORTED_SIMS%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-plugin-version.md b/windows-driver-docs-pr/network/hs-plugin-version.md new file mode 100644 index 0000000000..7db2adce00 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-plugin-version.md @@ -0,0 +1,64 @@ +--- +title: HS\_PLUGIN\_VERSION structure +author: windows-driver-content +description: The HS\_PLUGIN\_VERSION structure contains the minimum and maximum hotspot host versions supported by the plugin. +ms.assetid: ced24606-0379-4b13-831c-11de3ed6cd2b +keywords: +- HS_PLUGIN_VERSION structure Network Drivers Starting with Windows Vista +- PHS_PLUGIN_VERSION structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_PLUGIN\_VERSION structure + + +The **HS\_PLUGIN\_VERSION** structure contains the minimum and maximum hotspot host versions supported by the plugin. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_PLUGIN_VERSION { + DWORD dwVerMin; + DWORD dwVerMax; +} HS_PLUGIN_VERSION, *PHS_PLUGIN_VERSION; +``` + +Members +------- + +**dwVerMin** +The minimum hotspot host version supported by the plugin. + +**dwVerMax** +The maximum hotspot host version supported by the plugin. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_PLUGIN_VERSION%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-sim-data.md b/windows-driver-docs-pr/network/hs-sim-data.md new file mode 100644 index 0000000000..43e13307c8 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-sim-data.md @@ -0,0 +1,72 @@ +--- +title: HS\_SIM\_DATA structure +author: windows-driver-content +description: The HS\_SIM\_DATA structure contains information stored in the SIM card. +ms.assetid: 9e29a85e-e764-4841-b218-c63bba0ca9fa +keywords: +- HS_SIM_DATA structure Network Drivers Starting with Windows Vista +- PHS_SIM_DATA structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_SIM\_DATA structure + + +The **HS\_SIM\_DATA** structure contains information stored in the SIM card. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_SIM_DATA { + WCHAR wszICCID[HS_CONST_MAX_ICCID_LENGTH+1]; + WCHAR wszIMEI[HS_CONST_MAX_IMEI_LENGTH+1]; + WCHAR wszMEID_ME[HS_CONST_MAX_MEID_ME_LENGTH+1]; + WCHAR wszSF_EUIMID[HS_CONST_MAX_SF_EUIMID_LENGTH+1]; +} HS_SIM_DATA, *PHS_SIM_DATA; +``` + +Members +------- + +**wszICCID** +The Integrated Circuit Card Identifier (ICCID) stored in the SIM card. + +**wszIMEI** +The International Mobile Equipment Identity (IMEI) used to identify 3GPP phones. + +**wszMEID\_ME** +The Mobile Equipment Identifier (MEID) defined by 3GPP2. + +**wszSF\_EUIMID** +The Short Form Expanded User Identity Module Identifier (EUIMID) for a R-UIM or CSIM (CDMA SIM application) card. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_SIM_DATA%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hs-sim-identity.md b/windows-driver-docs-pr/network/hs-sim-identity.md new file mode 100644 index 0000000000..717e39d658 --- /dev/null +++ b/windows-driver-docs-pr/network/hs-sim-identity.md @@ -0,0 +1,93 @@ +--- +title: HS\_SIM\_IDENTITY structure +author: windows-driver-content +description: The HS\_SIM\_IDENTITY structure contains SIM identification information required for EAP-SIM or EAP-AKA authentication. +ms.assetid: b45fac33-79de-4006-9dcb-95725be11ec1 +keywords: +- HS_SIM_IDENTITY structure Network Drivers Starting with Windows Vista +- PHS_SIM_IDENTITY structure pointer Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HS\_SIM\_IDENTITY structure + + +The **HS\_SIM\_IDENTITY** structure contains SIM identification information required for EAP-SIM or EAP-AKA authentication. + +Syntax +------ + +```ManagedCPlusPlus +typedef struct _HS_SIM_IDENTITY { + eHS_SIM_TYPE SimType; + DWORD        dwMNC; + DWORD        dwMCC; + DWORD        dwNID; + DWORD        dwSID; + DWORD        dwEapMethods; +} HS_SIM_IDENTITY, *PHS_SIM_IDENTITY; +``` + +Members +------- + +**SimType** +The type of SIM, whether GSM or CDMA, or none. If the network is GSM, the **dwMNC** and **dwMCC** pair of fields will be defined, whereas for CDMA the **dwSID** and **dwNID** pair of fields must be defined. + +**dwMNC** +Used if the SIM is GSM type. + +The mobile network code (MNC) of the GSM network. + +**dwMCC** +Used if the SIM is GSM type. + +The mobile country code (MCC) of the GSM network. + +**dwNID** +Used if the SIM is CDMA type. + +The Network Identification Number (NID) of the CDMA network. + +**dwSID** +Used if the SIM is CDMA type. + +The System Identification Number (SID) of the CDMA network. + +**dwEapMethods** +The EAP authentication method. + +Requirements +------------ + + ++++ + + + + + + +

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[Extensible Authentication Protocol](https://msdn.microsoft.com/library/windows/desktop/aa363502) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HS_SIM_IDENTITY%20structure%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hsplugingetversion.md b/windows-driver-docs-pr/network/hsplugingetversion.md new file mode 100644 index 0000000000..8bec163638 --- /dev/null +++ b/windows-driver-docs-pr/network/hsplugingetversion.md @@ -0,0 +1,68 @@ +--- +title: HSPluginGetVersion function +author: windows-driver-content +description: The HSPluginGetVersion function is exported by the plugin DLL and is called to verify that the plugin version matches the host version. +ms.assetid: dfdd534c-43c0-4d96-b85b-de9c2830322d +keywords: +- HSPluginGetVersion function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HSPluginGetVersion function + + +The **HSPluginGetVersion** function is exported by the plugin DLL and is called to verify that the plugin version matches the host version. + +Syntax +------ + +```ManagedCPlusPlus +DWORD HSPluginGetVersion( + _Out_ HS_PLUGIN_VERSION *pHotspotPluginVersion +); +``` + +Parameters +---------- + +*\*pHotspotPluginVersion* \[out\] +A pointer to the [**HS\_PLUGIN\_VERSION**](hs-plugin-version.md) structure that contains version information for the plugin. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**HS\_PLUGIN\_VERSION**](hs-plugin-version.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HSPluginGetVersion%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hsplugininitplugin.md b/windows-driver-docs-pr/network/hsplugininitplugin.md new file mode 100644 index 0000000000..35f9fda1cb --- /dev/null +++ b/windows-driver-docs-pr/network/hsplugininitplugin.md @@ -0,0 +1,116 @@ +--- +title: HSPluginInitPlugin function +author: windows-driver-content +description: The HSPluginInitPlugin function is exported by the plugin DLL and is called to initialize the plugin. +ms.assetid: db51267c-4f38-47bd-bde2-7b27a93dd2a7 +keywords: +- HSPluginInitPlugin function Network Drivers Starting with Windows Vista +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# HSPluginInitPlugin function + + +The **HSPluginInitPlugin** function is exported by the plugin DLL and is called to initialize the plugin. + +Syntax +------ + +```ManagedCPlusPlus +DWORD HSPluginInitPlugin( + _In_  HANDLE                hPluginContext, + _In_  DWORD                 dwVerNumUsed, + _In_  DWORD                 dwHostCapabilities, + _In_  HS_DEVICE_IDENTITY    *pDeviceIdentity, + _In_  HOTSPOT_HOST_HANDLERS *pHotspotHostHandlers, + _Out_ HOTSPOT_PLUGIN_APIS   *pHotspotPluginAPIs, + _Out_ HS_PLUGIN_PROFILE     *pPluginProfile +); +``` + +Parameters +---------- + +*hPluginContext* \[in\] +A handle, provided by the host, that the plugin is required to save and then use when it needs to make a request to the host by way of the host handler functions. + +*dwVerNumUsed* \[in\] +The host's current version number. + +*dwHostCapabilities* \[in\] +Value that specifies the list of capabilities that the host can provide to the plugin. This value is the bitwise OR combination of the applicable capability flags. For more information about capability flags, see the **HS\_FLAG\_CAPABILITY\_\*** constants in [**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md). + +**Note**  If the host does not supply all the capabilities required by the plugin, the plugin will not be initialized. + +  + +*\*pDeviceIdentity* \[in\] +Pointer to a [**HS\_DEVICE\_IDENTITY**](hs-device-identity.md) structure that contains information about the device manufacturer and model. + +*\*pHotspotHostHandlers* \[in\] +Pointer to a [**HOTSPOT\_HOST\_HANDLERS**](hotspot-host-handlers.md) structure that contains the hotspot host handlers function table. This table contains pointers to functions that are called by the plugin to communicate with the hotspot host. + +*\*pHotspotPluginAPIs* \[out\] +Pointer to the [**HOTSPOT\_PLUGIN\_APIS**](hotspot-plugin-apis.md) structure that contains the hotspot plugin APIs function table. This table is returned by the plugin and contains pointers to functions that are called by the host to communicate with the plugin. + +*\*pPluginProfile* \[out\] +Pointer to a [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure, returned by the plugin, that provides information about the plugin. + +Remarks +------- + +During initialization, the host provides the following: + +- The plugin context handle +- The current version number +- A list of capabilities that the host can provide to the plugin +- A pointer to the host handler function table through which the plugin can communicate with the host + +The plugin returns a pointer to its own function table and a pointer to its [**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[**Wi-Fi Hotspot Offloading Constants**](wi-fi-hotspot-offloading-constants.md) + +[**HS\_DEVICE\_IDENTITY**](hs-device-identity.md) + +[**HOTSPOT\_HOST\_HANDLERS**](hotspot-host-handlers.md) + +[**HOTSPOT\_PLUGIN\_APIS**](hotspot-plugin-apis.md) + +[**HS\_PLUGIN\_PROFILE**](hs-plugin-profile.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20HSPluginInitPlugin%20function%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hyper-v-extensible-switch-macros.md b/windows-driver-docs-pr/network/hyper-v-extensible-switch-macros.md new file mode 100644 index 0000000000..daa96f6270 --- /dev/null +++ b/windows-driver-docs-pr/network/hyper-v-extensible-switch-macros.md @@ -0,0 +1,54 @@ +--- +title: Hyper-V Extensible Switch Macros +author: windows-driver-content +description: Hyper-V Extensible Switch Macros +ms.assetid: 6998518C-3989-46DD-BD69-3826994FD6A2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hyper-V Extensible Switch Macros + + +This section describes the following NDIS macros that can be used by a Hyper-V extensible switch extension: + +[**NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX**](https://msdn.microsoft.com/library/windows/hardware/hh598213) + +[**NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX**](https://msdn.microsoft.com/library/windows/hardware/hh598223) + +[**NDIS\_SWITCH\_PORT\_DESTINATION\_AT\_ARRAY\_INDEX**](ndis-switch-port-destination-at-array-index.md) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM\_GET\_BUFFER**](ndis-switch-port-property-custom-get-buffer.md) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_NEXT**](ndis-switch-port-property-enum-info-get-next.md) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY**](ndis-switch-port-property-enum-info-get-property.md) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO**](ndis-switch-port-property-enum-parameters-get-first-info.md) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS\_GET\_PROPERTY**](ndis-switch-port-property-parameters-get-property.md) + +[**NDIS\_SWITCH\_PROPERTY\_CUSTOM\_GET\_BUFFER**](ndis-switch-property-custom-get-buffer.md) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_NEXT**](ndis-switch-property-enum-info-get-next.md) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY**](ndis-switch-property-enum-info-get-property.md) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO**](ndis-switch-property-enum-parameters-get-first-info.md) + +[**NDIS\_SWITCH\_PROPERTY\_PARAMETERS\_GET\_PROPERTY**](ndis-switch-property-parameters-get-property.md) + +[**NET\_BUFFER\_LIST\_SWITCH\_FORWARDING\_DETAIL**](net-buffer-list-switch-forwarding-detail.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Hyper-V%20Extensible%20Switch%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hyper-v-extensible-switch-oids.md b/windows-driver-docs-pr/network/hyper-v-extensible-switch-oids.md new file mode 100644 index 0000000000..4bc225315b --- /dev/null +++ b/windows-driver-docs-pr/network/hyper-v-extensible-switch-oids.md @@ -0,0 +1,58 @@ +--- +title: Hyper-V Extensible Switch OIDs +description: This section describes Hyper-V Extensible Switch OIDs and their characteristics. +keywords: ["Hyper-V Extensible Switch OIDs", "Hyper-V Switch OIDs", "WDK Hyper-V Extensible Switch OIDs", "Hyper-V Extensible Switch object identifiers"] +ms.assetid: A97C5BF0-7319-4BEE-ABF7-12B11CEAF3DB" +ms.author: windowsdriverdev +ms.date: 04/24/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hyper-V Extensible Switch OIDs + +This section describes the Hyper-V extensible switch object identifiers (OIDs). These OIDs may be issued by either the extensible switch extension or a Hyper-V extensible switch extension. + +The following table defines the characteristics of the extensible switch OIDs. The following abbreviations are used to specify the OIDs' characteristics in the table. + +- Q +The OID is used only in query requests. +- S +The OID is used only in set requests. +- M +The OID is used only in method requests. These requests could be issued for set or query operations. +- P +The OID request is issued by the protocol edge of the extensible switch. The extension can inspect the results of the OID request to obtain information about the extensible switch, its ports, or virtual network adapters connected to the ports. +- E +The OID request is issued by an extension. + +| Name | Q | S | M | P | E | +|--- |---|---|---|---|---| +| [OID_SWITCH_FEATURE_STATUS_QUERY](https://msdn.microsoft.com/library/windows/hardware/hh598260) | | | X | X | | +| [OID_SWITCH_NIC_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598261) | X | | | | X | +| [OID_SWITCH_NIC_CONNECT](https://msdn.microsoft.com/library/windows/hardware/hh598262) | | X | | X | | +| [OID_SWITCH_NIC_CREATE](https://msdn.microsoft.com/library/windows/hardware/hh598263) | | X | | X | | +| [OID_SWITCH_NIC_DELETE](https://msdn.microsoft.com/library/windows/hardware/hh598264) | | X | | X | | +| [OID_SWITCH_NIC_DISCONNECT](https://msdn.microsoft.com/library/windows/hardware/hh598265) | | X | | X | | +| [OID_SWITCH_NIC_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh598266) | | | X | | X | +| [OID_SWITCH_NIC_RESTORE](https://msdn.microsoft.com/library/windows/hardware/hh598267) | | X | | X | | +| [OID_SWITCH_NIC_SAVE](https://msdn.microsoft.com/library/windows/hardware/hh598268) | X | | | X | | +| [OID_SWITCH_NIC_SAVE_COMPLETE](https://msdn.microsoft.com/library/windows/hardware/hh598269) | | X | | X | | +| [OID_SWITCH_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598270) | X | | | | X | +| [OID_SWITCH_PORT_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598271) | X | | | | X | +| [OID_SWITCH_PORT_CREATE](https://msdn.microsoft.com/library/windows/hardware/hh598272) | | X | | X | | +| [OID_SWITCH_PORT_DELETE](https://msdn.microsoft.com/library/windows/hardware/hh598273) | | X | | X | | +| [OID_SWITCH_PORT_FEATURE_STATUS_QUERY](https://msdn.microsoft.com/library/windows/hardware/hh598274) | | | X | X | | +| [OID_SWITCH_PORT_PROPERTY_ADD](https://msdn.microsoft.com/library/windows/hardware/hh598275) | | X | | X | | +| [OID_SWITCH_PORT_PROPERTY_DELETE](https://msdn.microsoft.com/library/windows/hardware/hh598276) | | X | | X | | +| [OID_SWITCH_PORT_PROPERTY_ENUM](https://msdn.microsoft.com/library/windows/hardware/hh598277) | | | X | | X | +| [OID_SWITCH_PORT_PROPERTY_UPDATE](https://msdn.microsoft.com/library/windows/hardware/hh598278) | | X | | X | | +| [OID_SWITCH_PORT_TEARDOWN](https://msdn.microsoft.com/library/windows/hardware/hh598279) | | X | | X | | +| [OID_SWITCH_PROPERTY_ADD](https://msdn.microsoft.com/library/windows/hardware/hh598280) | | X | | X | | +| [OID_SWITCH_PROPERTY_DELETE](https://msdn.microsoft.com/library/windows/hardware/hh598281) | | X | | X | | +| [OID_SWITCH_PROPERTY_ENUM](https://msdn.microsoft.com/library/windows/hardware/hh598282) | | | X | | X | +| [OID_SWITCH_PROPERTY_UPDATE](https://msdn.microsoft.com/library/windows/hardware/hh598283) | | X | | X | | + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/hyper-v-extensible-switch-status-indications.md b/windows-driver-docs-pr/network/hyper-v-extensible-switch-status-indications.md new file mode 100644 index 0000000000..795fd2470d --- /dev/null +++ b/windows-driver-docs-pr/network/hyper-v-extensible-switch-status-indications.md @@ -0,0 +1,31 @@ +--- +title: Hyper-V Extensible Switch Status Indications +author: windows-driver-content +description: Hyper-V Extensible Switch Status Indications +ms.assetid: ADF6622F-93E1-4A0D-AB54-A99F7D33EBA0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Hyper-V Extensible Switch Status Indications + + +This section describes the following NDIS status indications that can be issued or handled by a Hyper-V extensible switch extension: + +- [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](ndis-status-switch-nic-status.md) +- [**NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF**](ndis-status-switch-port-remove-vf.md) + +For more information on how extensions issue or handle extensible switch extension status indications, see [Hyper-V Extensible Switch Control Path for NDIS Status Indications](https://msdn.microsoft.com/library/windows/hardware/hh598165). + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Hyper-V%20Extensible%20Switch%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/hyper-v-extensible-switch.md b/windows-driver-docs-pr/network/hyper-v-extensible-switch.md index 8a2c64eeda..5d0b2e0280 100644 --- a/windows-driver-docs-pr/network/hyper-v-extensible-switch.md +++ b/windows-driver-docs-pr/network/hyper-v-extensible-switch.md @@ -23,6 +23,7 @@ This section includes the following topics that describe the Hyper-V extensible - [Hyper-V Extensible Switch Architecture](hyper-v-extensible-switch-architecture.md) - [Writing Hyper-V Extensible Switch Extensions](writing-hyper-v-extensible-switch-extensions.md) - [Installing Hyper-V Extensible Switch Extensions](installing-hyper-v-extensible-switch-extensions.md) +- [Hyper-V Extensible Switch OIDs](hyper-v-extensible-switch-oids.md)   diff --git a/windows-driver-docs-pr/network/images/NLO.png b/windows-driver-docs-pr/network/images/NLO.png new file mode 100644 index 0000000000..bbbbac6c92 Binary files /dev/null and b/windows-driver-docs-pr/network/images/NLO.png differ diff --git a/windows-driver-docs-pr/network/images/WiFiAutoPsm.png b/windows-driver-docs-pr/network/images/WiFiAutoPsm.png new file mode 100644 index 0000000000..089ed32f64 Binary files /dev/null and b/windows-driver-docs-pr/network/images/WiFiAutoPsm.png differ diff --git a/windows-driver-docs-pr/network/images/multi-SIM_5_systemCapabilityQuery.png b/windows-driver-docs-pr/network/images/multi-SIM_5_systemCapabilityQuery.png new file mode 100644 index 0000000000..d32c23d21c Binary files /dev/null and b/windows-driver-docs-pr/network/images/multi-SIM_5_systemCapabilityQuery.png differ diff --git a/windows-driver-docs-pr/network/images/multi-SIM_6_executorCapabilityQuery.png b/windows-driver-docs-pr/network/images/multi-SIM_6_executorCapabilityQuery.png new file mode 100644 index 0000000000..1506c7c3f1 Binary files /dev/null and b/windows-driver-docs-pr/network/images/multi-SIM_6_executorCapabilityQuery.png differ diff --git a/windows-driver-docs-pr/network/images/multi-SIM_7_slotMappingSet.png b/windows-driver-docs-pr/network/images/multi-SIM_7_slotMappingSet.png new file mode 100644 index 0000000000..47bd52db85 Binary files /dev/null and b/windows-driver-docs-pr/network/images/multi-SIM_7_slotMappingSet.png differ diff --git a/windows-driver-docs-pr/network/images/multi-SIM_8_slotMappingQuery.png b/windows-driver-docs-pr/network/images/multi-SIM_8_slotMappingQuery.png new file mode 100644 index 0000000000..ec25e2d591 Binary files /dev/null and b/windows-driver-docs-pr/network/images/multi-SIM_8_slotMappingQuery.png differ diff --git a/windows-driver-docs-pr/network/images/multi-SIM_9_slotStatusQuery.png b/windows-driver-docs-pr/network/images/multi-SIM_9_slotStatusQuery.png new file mode 100644 index 0000000000..e26b8a016c Binary files /dev/null and b/windows-driver-docs-pr/network/images/multi-SIM_9_slotStatusQuery.png differ diff --git a/windows-driver-docs-pr/network/images/wdi-d0-to-d3-not-armed.png b/windows-driver-docs-pr/network/images/wdi-d0-to-d3-not-armed.png new file mode 100644 index 0000000000..3c5444145b Binary files /dev/null and b/windows-driver-docs-pr/network/images/wdi-d0-to-d3-not-armed.png differ diff --git a/windows-driver-docs-pr/network/images/wdi-d0-to-dx-armed-to-wake.png b/windows-driver-docs-pr/network/images/wdi-d0-to-dx-armed-to-wake.png new file mode 100644 index 0000000000..46815c6911 Binary files /dev/null and b/windows-driver-docs-pr/network/images/wdi-d0-to-dx-armed-to-wake.png differ diff --git a/windows-driver-docs-pr/network/images/wdi-dx-to-d0-armed-to-wake.png b/windows-driver-docs-pr/network/images/wdi-dx-to-d0-armed-to-wake.png new file mode 100644 index 0000000000..4ae3b9f4e1 Binary files /dev/null and b/windows-driver-docs-pr/network/images/wdi-dx-to-d0-armed-to-wake.png differ diff --git a/windows-driver-docs-pr/network/images/wdi-dx-to-d0-not-armed.png b/windows-driver-docs-pr/network/images/wdi-dx-to-d0-not-armed.png new file mode 100644 index 0000000000..3a98ed816b Binary files /dev/null and b/windows-driver-docs-pr/network/images/wdi-dx-to-d0-not-armed.png differ diff --git a/windows-driver-docs-pr/network/images/wwansmsrecordretrieval.png b/windows-driver-docs-pr/network/images/wwansmsrecordretrieval.png new file mode 100644 index 0000000000..8e98f4f5eb Binary files /dev/null and b/windows-driver-docs-pr/network/images/wwansmsrecordretrieval.png differ diff --git a/windows-driver-docs-pr/network/implementing-ndkpi-callback-functions.md b/windows-driver-docs-pr/network/implementing-ndkpi-callback-functions.md index 3b992a6bff..fffc6a1b89 100644 --- a/windows-driver-docs-pr/network/implementing-ndkpi-callback-functions.md +++ b/windows-driver-docs-pr/network/implementing-ndkpi-callback-functions.md @@ -1,6 +1,6 @@ --- title: Implementing NDKPI Functions -description: An NDK-capable miniport driver must register entry points for all NDK\_FN\_XXX callback functions. All of the NDKPI provider callback functions are mandatory; none are optional. +description: An NDK-capable miniport driver must register entry points for all NDK_FN_XXX callback functions. All of the NDKPI provider callback functions are mandatory; none are optional. ms.assetid: 9A7D5F77-C26A-47B6-9F8E-ECB80D4FF384 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/initializing-a-vf-miniport-driver.md b/windows-driver-docs-pr/network/initializing-a-vf-miniport-driver.md index 6a2211a1c2..a75fd38f75 100644 --- a/windows-driver-docs-pr/network/initializing-a-vf-miniport-driver.md +++ b/windows-driver-docs-pr/network/initializing-a-vf-miniport-driver.md @@ -14,9 +14,8 @@ ms.technology: windows-devices This topic describes the guidelines for writing a [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function for the miniport driver for a PCI Express (PCIe) Virtual Function (VF). The VF is exposed by a network adapter that supports single root I/O virtualization (SR-IOV). -**Note**  These guidelines only apply to VF miniport drivers of the SR-IOV network adapter. For initialization guidelines for the miniport driver of a PCIe Physical Function (PF) of the adapter, see [Initializing a PF Miniport Driver](initializing-a-pf-miniport-driver.md). - -  +> [!NOTE] +> These guidelines only apply to VF miniport drivers of the SR-IOV network adapter. For initialization guidelines for the miniport driver of a PCIe Physical Function (PF) of the adapter, see [Initializing a PF Miniport Driver](initializing-a-pf-miniport-driver.md).  The VF miniport driver follows the same steps as any NDIS miniport driver when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. For more information about these steps, see [Initializing a Miniport Driver](initializing-a-miniport-driver.md). @@ -24,9 +23,8 @@ In addition to these steps, the VF miniport driver must follow these additional - The VF miniport driver calls the [**NdisGetHypervisorInfo**](https://msdn.microsoft.com/library/windows/hardware/ff562635) function to verify that it is running in the Hyper-V child partition. This function returns an [**NDIS\_HYPERVISOR\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff565708) structure which defines the partition type. If the partition type is reported as **NdisHypervisorPartitionMsHvChild**, the miniport driver is running in a Hyper-V child partition that is attached to the PF on the adapter. - **Note**  If the partition type is reported as **NdisHypervisorPartitionMsHvParent**, the miniport driver is running in the Hyper-V parent partition that is attached to the PF on the adapter. In this case, the miniport driver must not initialize as a VF driver. If possible, the driver must initialize as a PF driver as described in [Initialization Sequence for PF Miniport Drivers](initialization-sequence-for-pf-miniport-drivers.md). - -   + > [!NOTE] + > If the partition type is reported as **NdisHypervisorPartitionMsHvParent**, the miniport driver is running in the Hyper-V parent partition that is attached to the PF on the adapter. In this case, the miniport driver must not initialize as a VF driver. If possible, the driver must initialize as a PF driver as described in [Initialization Sequence for PF Miniport Drivers](initialization-sequence-for-pf-miniport-drivers.md).   - Unlike the PF miniport driver, the VF miniport driver must not be installed with the SR-IOV standardized keywords and must not attempt to read these keywords. For more information about these keywords, see [Standardized INF Keywords for SR-IOV](standardized-inf-keywords-for-sr-iov.md). @@ -38,9 +36,8 @@ In addition to these steps, the VF miniport driver must follow these additional 2. The miniport driver sets the NDIS\_SRIOV\_CAPS\_PF\_MINIPORT flag in the **SriovCapabilities** member to report SR-IOV capabilities. - **Note**  The VF miniport driver must only set the NDIS\_SRIOV\_CAPS\_VF\_MINIPORT flag. - -   + > [!NOTE] + > The VF miniport driver must set both the NDIS\_SRIOV\_CAPS\_VF\_MINIPORT flag and the NDIS\_SRIOV\_CAPS\_SRIOV\_SUPPORTED flag.   The VF miniport driver registers the SR-IOV capabilities of the network adapter by following these steps: diff --git a/windows-driver-docs-pr/network/introduction-to-ndis-6-40.md b/windows-driver-docs-pr/network/introduction-to-ndis-6-40.md index a9ab237279..fbfcb6dfc3 100644 --- a/windows-driver-docs-pr/network/introduction-to-ndis-6-40.md +++ b/windows-driver-docs-pr/network/introduction-to-ndis-6-40.md @@ -23,24 +23,23 @@ Windows 8.1 and Windows Server 2012 R2 introduce minor updates to the followi NDKPI 1.2 adds the following new elements to the NDKPI DDI: -- *NdkSendAndInvalidate* ([*NDK\_FN\_SEND\_AND\_INVALIDATE*](https://msdn.microsoft.com/library/windows/hardware/dn265507)) function -- *NdkGetCqResultsEx* ([*NDK\_FN\_GET\_CQ\_RESULTS\_EX*](https://msdn.microsoft.com/library/windows/hardware/dn265506)) function -- [**NDK\_RESULT\_EX**](https://msdn.microsoft.com/library/windows/hardware/dn265509) structure -- New request callback *Flags* value: **NDK\_OP\_FLAG\_DEFER** -- New [**NDK\_ADAPTER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh439851)**AdapterFlags** value: **NDK\_ADAPTER\_FLAG\_RDMA\_READ\_LOCAL\_INVALIDATE\_SUPPORTED** +- *NdkSendAndInvalidate* ([*NDK\_FN\_SEND\_AND\_INVALIDATE*](https://msdn.microsoft.com/library/windows/hardware/dn265507)) function +- *NdkGetCqResultsEx* ([*NDK\_FN\_GET\_CQ\_RESULTS\_EX*](https://msdn.microsoft.com/library/windows/hardware/dn265506)) function +- [**NDK\_RESULT\_EX**](https://msdn.microsoft.com/library/windows/hardware/dn265509) structure +- New request callback *Flags* value: **NDK\_OP\_FLAG\_DEFER** +- New [**NDK\_ADAPTER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh439851)**AdapterFlags** value: **NDK\_ADAPTER\_FLAG\_RDMA\_READ\_LOCAL\_INVALIDATE\_SUPPORTED** ### Native 802.11 Wireless LAN IEEE 802.11ac very-high throughput (VHT) PHY is now supported. The following DDI elements have been updated: -- [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) enumeration -- [OID\_DOT11\_CURRENT\_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) -- [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](https://msdn.microsoft.com/library/windows/hardware/ff569426) -- [OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569425) +- [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) enumeration +- [OID\_DOT11\_CURRENT\_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) +- [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](https://msdn.microsoft.com/library/windows/hardware/ff569426) +- [OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569425) ## Sample and Documentation Updates - The [Hyper-V Extensible Switch forwarding extension sample](http://go.microsoft.com/fwlink/p/?LinkId=617913) has been updated to implement Hybrid Forwarding. The following documentation sections have been added or significantly expanded: @@ -54,21 +53,11 @@ The following documentation sections have been added or significantly expanded: The NetDMA interface is not supported in Windows 8 and Windows Server 2012 and later. The documentation has now been updated to reflect this. -You should be familiar with earlier versions of NDIS 6.x before learning about NDIS 6.40. For more information about previous NDIS 6.x versions, see the following topics: - -[Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) - -[Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) - -[Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) - -[Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) - This section includes the following topics: -- [Implementing an NDIS 6.40 Driver](implementing-an-ndis-6-40-driver.md) -- [Using NDIS 6.40 Data Structures](using-ndis-6-40-data-structures.md) -- [Compiling an NDIS 6.40 Driver](compiling-an-ndis-6-40-driver.md) +- [Implementing an NDIS 6.40 Driver](implementing-an-ndis-6-40-driver.md) +- [Using NDIS 6.40 Data Structures](using-ndis-6-40-data-structures.md) +- [Compiling an NDIS 6.40 Driver](compiling-an-ndis-6-40-driver.md)   diff --git a/windows-driver-docs-pr/network/introduction-to-ndis-6-50.md b/windows-driver-docs-pr/network/introduction-to-ndis-6-50.md new file mode 100644 index 0000000000..55b072f32e --- /dev/null +++ b/windows-driver-docs-pr/network/introduction-to-ndis-6-50.md @@ -0,0 +1,93 @@ +--- +title: Introduction to NDIS 6.50 +description: This section introduces NDIS 6.50 and describes changes from NDIS 6.40. NDIS 6.50 is included in Windows 10, version 1507 and later. +ms.assetid: 8D2EA09D-3FA3-467B-861A-AA15C790FCD3 +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to NDIS 6.50 + +This topic introduces Network Driver Interface Specification (NDIS) 6.50 and describes its major design additions. NDIS 6.50 is included in Windows 10, version 1507 and later. + +NDIS 6.50 is a minor version update to NDIS 6.40. For more information about porting NDIS 6.x drivers to NDIS 6.50, see [Porting NDIS 6.x drivers to NDIS 6.50](porting-ndis-6-x-drivers-to-ndis-6-50.md). + +## Feature updates + +NDIS 6.50 is an incremental update to NDIS 6.40 and does not contain any major new features. + +## Implementing an NDIS 6.50 driver + +An NDIS 6.50 driver must follow the requirements that are defined in [Implementing an NDIS 6.40 driver](implementing-an-ndis-6-40-driver.md). + +In addition, an NDIS 6.50 driver must be compliant with the following requirements: + +- An NDIS 6.50 driver must report the correct NDIS version when it registers with NDIS. + + You must update the major and minor NDIS version number in the NDIS_Xxx_DRIVER_CHARACTERISTICS structure to support NDIS 6.50. The MajorNdisVersion member must contain 6 and the MinorNdisVersion member must contain 50. This requirement applies to miniport, protocol, and filter drivers. You must also update the version information for the compiler (see [Compiling an NDIS 6.50 driver](#compiling-an-ndis-650-driver)). + +- NDIS 6.50 miniport drivers for Windows 10, version 1507 and later must use the NDIS 6.50 versions of data structures. For more information, see [Using NDIS 6.50 data structures](#using-ndis-650-data-structures). + +## Compiling an NDIS 6.50 driver + +The WDK for Windows 10, version 1507 supports header versioning. Header versioning makes sure that NDIS 6.50 drivers use the appropriate NDIS 6.50 data structures at compile time. + +Add the following compiler settings to the Visual Studio project for your driver: + +- For a miniport driver, add ```NDIS650_MINIPORT=1```. +- For a filter or protocol driver, add ```NDIS650=1```. + +For information on building a driver with the Windows 10, version 1507 release of the WDK, see [Building a Driver](../develop/building-a-driver.md). + +## Using NDIS 6.50 data structures + +### New data structures + +The following data structures are new in NDIS 6.50. + +- [OID_WWAN_SYS_CAPS](https://msdn.microsoft.com/library/windows/hardware/mt799833) +- [OID_WWAN_DEVICE_CAPS_EX](https://msdn.microsoft.com/library/windows/hardware/mt799830) +- [OID_WWAN_SLOT_INFO_STATUS](https://msdn.microsoft.com/library/windows/hardware/mt799832) +- [OID_WWAN_NETWORK_IDLE_HINT](https://msdn.microsoft.com/library/windows/hardware/dn931089) +- [NDIS_STATUS_PD_CURRENT_CONFIG](https://msdn.microsoft.com/library/windows/hardware/dn931850) +- [NDIS_PD_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn931833) +- [NDIS_PD_CLOSE_PROVIDER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931834) +- [NDIS_PD_CONFIG](https://msdn.microsoft.com/library/windows/hardware/dn931835) +- [NDIS_PD_COUNTER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931836) +- [NDIS_PD_COUNTER_VALUE](https://msdn.microsoft.com/library/windows/hardware/dn931838) +- [NDIS_PD_FILTER_COUNTER](https://msdn.microsoft.com/library/windows/hardware/dn931839) +- [NDIS_PD_FILTER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931840) +- [NDIS_PD_ON_RSS_QUEUE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931841) +- [NDIS_PD_OPEN_PROVIDER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931842) +- [NDIS_PD_PROVIDER_DISPATCH](https://msdn.microsoft.com/library/windows/hardware/dn931843) +- [NDIS_PD_QUEUE](https://msdn.microsoft.com/library/windows/hardware/dn931844) +- [NDIS_PD_QUEUE_DISPATCH](https://msdn.microsoft.com/library/windows/hardware/dn931845) +- [NDIS_PD_QUEUE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn931846) +- [NDIS_PD_RECEIVE_QUEUE_COUNTER](https://msdn.microsoft.com/library/windows/hardware/dn931848) +- [NDIS_PD_TRANSMIT_QUEUE_COUNTER](https://msdn.microsoft.com/library/windows/hardware/dn931849) +- [PD_BUFFER](https://msdn.microsoft.com/library/windows/hardware/dn931863) +- [PD_BUFFER_8021Q_INFO](https://msdn.microsoft.com/library/windows/hardware/dn931864) +- [PD_BUFFER_VIRTUAL_SUBNET_INFO](https://msdn.microsoft.com/library/windows/hardware/dn931865) + +### Updated data structures + +The following data structures were updated in NDIS 6.50. + +- [NET_PNP_EVENT_NOTIFICATION](https://msdn.microsoft.com/library/windows/hardware/ff568752) +- [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) +- [NDIS_NET_BUFFER_LIST_INFO](https://msdn.microsoft.com/library/windows/hardware/ff566569) +- [NdisMGetDeviceProperty](https://msdn.microsoft.com/library/windows/hardware/ff563592) +- [NDIS_SWITCH_OPTIONAL_HANDLERS](https://msdn.microsoft.com/library/windows/hardware/hh598219) +- [NDIS_SWITCH_NIC_SAVE_STATE](https://msdn.microsoft.com/library/windows/hardware/hh598216) + +## NDIS 6.51 + +NDIS 6.51 is a very minor version update to NDIS 6.50. NDIS 6.51 is included in Windows 10, version 1511 and later. All information for NDIS 6.50 also applies to NDIS 6.51 with the following exceptions: + +- The MinorNdisVersion changes from 50 to 51 when registering your driver with NDIS. +- The compiler settings change from ```NDIS650_MINIPORT=1``` for miniport drivers and ```NDIS650=1``` for filter or protocol drivers, to ```NDIS651_MINIPORT=1``` and ```NDIS651=1``` respectively. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/introduction-to-ndis-6-60.md b/windows-driver-docs-pr/network/introduction-to-ndis-6-60.md new file mode 100644 index 0000000000..c7f37da7fa --- /dev/null +++ b/windows-driver-docs-pr/network/introduction-to-ndis-6-60.md @@ -0,0 +1,55 @@ +--- +title: Introduction to NDIS 6.60 +description: This section introduces NDIS 6.60 and describes changes from NDIS 6.50. NDIS 6.60 is included in Windows 10, version 1607 and Windows Server 2016 and later. +ms.assetid: AFDFD1CD-2E07-4A4F-82E2-5E6C5AABD5A3 +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to NDIS 6.60 + +This topic introduces Network Driver Interface Specification (NDIS) 6.60 and describes its major design additions. NDIS 6.60 is included in Windows 10, version 1607 and Windows Server 2016 and later. + +NDIS 6.60 is a minor version update to NDIS 6.50. For more information about porting NDIS 6.x drivers to NDIS 6.60, see [Porting NDIS 6.x drivers to NDIS 6.60](porting-ndis-6-x-drivers-to-ndis-6-60.md). + +## Feature updates + +NDIS 6.60 is an incremental update to NDIS 6.50 and does not contain any major new features. + +## Implementing an NDIS 6.60 driver + +An NDIS 6.60 driver must follow the requirements that are defined in [Implementing an NDIS 6.50 driver](introduction-to-ndis-6-50.md#implementing-an-ndis-650-driver). + +In addition, an NDIS 6.60 driver must be compliant with the following requirements: + +- An NDIS 6.60 driver must report the correct NDIS version when it registers with NDIS. + + You must update the major and minor NDIS version number in the NDIS_Xxx_DRIVER_CHARACTERISTICS structure to support NDIS 6.60. The MajorNdisVersion member must contain 6 and the MinorNdisVersion member must contain 60. This requirement applies to miniport, protocol, and filter drivers. You must also update the version information for the compiler (see [Compiling an NDIS 6.60 driver](#compiling-an-ndis-660-driver)). + +- NDIS 6.60 miniport drivers for Windows 10, version 1607 and Windows Server 2016 and later must use the NDIS 6.60 versions of data structures. For more information, see [Using NDIS 6.60 data structures](#using-ndis-660-data-structures). + +## Compiling an NDIS 6.60 driver + +The WDK for Windows 10, version 1607 supports header versioning. Header versioning makes sure that NDIS 6.60 drivers use the appropriate NDIS 6.60 data structures at compile time. + +Add the following compiler settings to the Visual Studio project for your driver: + +- For a miniport driver, add ```NDIS660_MINIPORT=1```. +- For a filter or protocol driver, add ```NDIS660=1```. + +For information on building a driver with the Windows 10, version 1607 release of the WDK, see [Building a Driver](../develop/building-a-driver.md). + +## Using NDIS 6.60 data structures + +### Updated data structures + +The following data structures were updated in NDIS 6.60. + +- [NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583) +- [NDIS_RECEIVE_SCALE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff567228) +- [NDIS_RECEIVE_SCALE_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff567220) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/introduction-to-ndis-6-70.md b/windows-driver-docs-pr/network/introduction-to-ndis-6-70.md new file mode 100644 index 0000000000..2db49f26ba --- /dev/null +++ b/windows-driver-docs-pr/network/introduction-to-ndis-6-70.md @@ -0,0 +1,82 @@ +--- +title: Introduction to NDIS 6.70 +description: This section introduces NDIS 6.70 and describes changes from NDIS 6.60. NDIS 6.70 is included in Windows 10, version 1703. +ms.assetid: D846EE68-2C84-40E0-91DE-2034F75D576F +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introduction to NDIS 6.70 + +This topic introduces Network Driver Interface Specification (NDIS) 6.70 and describes its major design additions. NDIS 6.70 is included in Windows 10, version 1703. + +NDIS 6.70 is a minor version update to NDIS 6.60 for miniport, protocol, filter, and intermediate drivers. For more information about porting NDIS 6.x drivers to NDIS 6.70, see [Porting NDIS 6.x drivers to NDIS 6.70](porting-ndis-6-x-drivers-to-ndis-6-70.md). + +## Feature updates + +### NetAdapterCx + +NDIS 6.70 includes a major new feature for NIC drivers, the Network Adapter WDF Class Extension, a.k.a. [NetAdapterCx](../netcx/index.md). NetAdapterCx is preview only in Windows 10, version 1703. The NetAdapterCx model enables NIC driver developers to harness the full functionality and simplified driver model of WDF, meaning NIC drivers are easier to write. + +### Other feature updates + +NDIS forms the core foundation for the network driver platform on Windows. For a list of other network driver features that were updated at the same time as NDIS 6.70, see the Windows 10, version 1703 section for Networking on [What's new in driver development](../what-s-new-in-driver-development.md). + +## Feature deprecations + +The following network driver features have been deprecated along with the release of NDIS 6.70: + +- [TCP Chimney Offload](ndis-tcp-chimney-offload.md) +- [IPsec Offload Version 2](ipsec-offload-version-2.md) + +## Implementing an NDIS 6.70 driver + +### NIC drivers + +For more information about implementing a NIC driver with the NetAdapterCx, see [NetAdapterCx](../netcx/index.md). + +### Miniport, protocol, filter, and intermediate drivers + +An NDIS 6.70 driver must follow the requirements that are defined in [Implementing an NDIS 6.60 driver](introduction-to-ndis-6-60.md#implementing-an-ndis-660-driver). + +In addition, an NDIS 6.70 driver must be compliant with the following requirements: + +- An NDIS 6.70 driver must report the correct NDIS version when it registers with NDIS. + + You must update the major and minor NDIS version number in the NDIS_Xxx_DRIVER_CHARACTERISTICS structure to support NDIS 6.70. The MajorNdisVersion member must contain 6 and the MinorNdisVersion member must contain 70. This requirement applies to miniport, protocol and filter drivers. You must also update the version information for the compiler (see [Compiling an NDIS 6.70 driver](#compiling-an-ndis-670-driver)). + +## Compiling an NDIS 6.70 driver + +### NIC drivers + +For more information about compiling a NIC driver with the NetAdapterCx, see [Porting NDIS miniport drivers to NetAdapter Class Extension (Compilation settings)](../netcx/porting-ndis-to-netadapter-cx.md#compilation-settings). + +### Miniport, protocol, and filter drivers + +The WDK for Windows 10, version 1703 supports header versioning. Header versioning makes sure that NDIS 6.70 drivers use the appropriate NDIS 6.70 data structures at compile time. + +Add the following compiler settings to the Visual Studio project for your driver: + +- For a miniport driver, add ```NDIS670_MINIPORT=1```. +- For a filter or protocol driver, add ```NDIS670=1```. + +For information on building a driver with the Windows 10, version 1703 release of the WDK, see [Building a Driver](../develop/building-a-driver.md). + +## Using NDIS 6.70 driver data structures + +### NIC drivers + +For more information about NetAdapterCx data structures, see [NetAdapterCx](../netcx/index.md). + +### Miniport, protocol, filter, and intermediate drivers + +#### New data structures + +The following data structures are new in NDIS 6.70. + +- [NDIS_STATUS_WWAN_DEVICE_CAPS_EX](https://msdn.microsoft.com/library/windows/hardware/mt782396) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/introduction-to-network-drivers.md b/windows-driver-docs-pr/network/introduction-to-network-drivers.md index aec36c477a..8c50e94d8c 100644 --- a/windows-driver-docs-pr/network/introduction-to-network-drivers.md +++ b/windows-driver-docs-pr/network/introduction-to-network-drivers.md @@ -17,20 +17,14 @@ ms.technology: windows-devices ## -This section discusses kernel-mode network drivers and includes the following topics: +This section discusses introductory concepts for kernel-mode network drivers and includes the following topics: - [Roadmap for Developing NDIS Drivers](roadmap-for-developing-ndis-drivers.md) - [Using the Network Driver Design Guide](using-the-network-driver-design-guide.md) - [Network Architecture for Kernel-Mode Drivers](network-architecture-for-kernel-mode-drivers.md) - [Network Driver Programming Considerations](network-driver-programming-considerations.md) -- [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) -- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) -- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) -- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) -- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) - [Driver Stack Management](driver-stack-management.md) - [NET\_BUFFER Architecture](net-buffer-architecture.md) -- [Specifying NDIS Version Information](specifying-ndis-version-information.md) - [Introduction to NDIS PDPI](introduction-to-ndis-pdpi.md)   diff --git a/windows-driver-docs-pr/network/introductions-to-ndis-6-0-and-later.md b/windows-driver-docs-pr/network/introductions-to-ndis-6-0-and-later.md new file mode 100644 index 0000000000..29754c1265 --- /dev/null +++ b/windows-driver-docs-pr/network/introductions-to-ndis-6-0-and-later.md @@ -0,0 +1,25 @@ +--- +title: Introductions to NDIS 6.0 and later +description: This section introduces each version of NDIS 6.X, starting with NDIS 6.0 +ms.assetid: 4DEB69E1-8843-4E42-A01B-9932A42226BA +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Introductions to NDIS 6.0 and later + +This section introduces each version of NDIS 6.*X*, starting with NDIS 6.0. + +- [Introduction to NDIS 6.70](introduction-to-ndis-6-70.md) +- [Introduction to NDIS 6.60](introduction-to-ndis-6-60.md) +- [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md) +- [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) +- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/issuing-oid-nic-switch-allocate-vf-requests.md b/windows-driver-docs-pr/network/issuing-oid-nic-switch-allocate-vf-requests.md index a027f55b03..dfaaf5f8e8 100644 --- a/windows-driver-docs-pr/network/issuing-oid-nic-switch-allocate-vf-requests.md +++ b/windows-driver-docs-pr/network/issuing-oid-nic-switch-allocate-vf-requests.md @@ -1,6 +1,6 @@ --- -title: Issuing OID\_NIC\_SWITCH\_ALLOCATE\_VF Requests -description: Issuing OID\_NIC\_SWITCH\_ALLOCATE\_VF Requests +title: Issuing OID_NIC_SWITCH_ALLOCATE_VF Requests +description: Issuing OID_NIC_SWITCH_ALLOCATE_VF Requests ms.assetid: 72285E72-DEC7-4578-9B6C-E616FECD6F41 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/issuing-oid-nic-switch-free-vf-requests.md b/windows-driver-docs-pr/network/issuing-oid-nic-switch-free-vf-requests.md index 712fe50c29..6de61a31b7 100644 --- a/windows-driver-docs-pr/network/issuing-oid-nic-switch-free-vf-requests.md +++ b/windows-driver-docs-pr/network/issuing-oid-nic-switch-free-vf-requests.md @@ -1,6 +1,6 @@ --- -title: Issuing OID\_NIC\_SWITCH\_FREE\_VF Requests -description: Issuing OID\_NIC\_SWITCH\_FREE\_VF Requests +title: Issuing OID_NIC_SWITCH_FREE_VF Requests +description: Issuing OID_NIC_SWITCH_FREE_VF Requests ms.assetid: D9A8548C-02D8-4537-9053-6B262004CBC4 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/mapping-a-net-luid-value-to-an-interface-index.md b/windows-driver-docs-pr/network/mapping-a-net-luid-value-to-an-interface-index.md index ff1c748803..25366e3435 100644 --- a/windows-driver-docs-pr/network/mapping-a-net-luid-value-to-an-interface-index.md +++ b/windows-driver-docs-pr/network/mapping-a-net-luid-value-to-an-interface-index.md @@ -1,6 +1,6 @@ --- -title: Mapping a NET\_LUID Value to an Interface Index -description: Mapping a NET\_LUID Value to an Interface Index +title: Mapping a NET_LUID Value to an Interface Index +description: Mapping a NET_LUID Value to an Interface Index ms.assetid: a535d886-186e-4abe-9ca0-ebef262614b3 keywords: - NDIS network interfaces WDK , NET_LUID diff --git a/windows-driver-docs-pr/network/mb-data-model.md b/windows-driver-docs-pr/network/mb-data-model.md index eba5d233e4..fb1594d866 100644 --- a/windows-driver-docs-pr/network/mb-data-model.md +++ b/windows-driver-docs-pr/network/mb-data-model.md @@ -22,408 +22,59 @@ In addition, MB miniport drivers must implement OID\_GEN\_PHYSICAL\_MEDIUM even The syntax and semantics of the MB OIDs listed in the following table are described in [MB Operational Semantics](mb-operational-semantics.md). The interactions between the MB Service and the MB miniport driver are described in [MB Operation Flowcharts](mb-operation-flowcharts.md). -### WWAN-Specific OIDs - -**OID** and **Corresponding Data Structure** - -**Set operation** - -**Query operation** - -**GSM/CDMA** - -Windows 7 -Windows 8 -Windows 7 -Windows 8 -[OID\_WWAN\_DRIVER\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569825) - -uses [**NDIS\_WWAN\_DRIVER\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567908) - -Not supported - -Not supported - -S - -S - -GSM, CDMA - -[OID\_WWAN\_DEVICE\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569824) has no corresponding structure - -Not supported - -Not supported - -A - -A - -GSM, CDMA - -[OID\_WWAN\_READY\_INFO](https://msdn.microsoft.com/library/windows/hardware/ff569833) has no corresponding structure - -Not supported - -Not supported - -A - -A - -GSM, CDMA - -[OID\_WWAN\_SERVICE\_ACTIVATION](https://msdn.microsoft.com/library/windows/hardware/ff569835)† - -uses [**NDIS\_WWAN\_SERVICE\_ACTIVATION**](https://msdn.microsoft.com/library/windows/hardware/ff567918) - -A - -A - -Not supported - -Not supported - -GSM, CDMA - -[OID\_WWAN\_RADIO\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569832) - -uses [**NDIS\_WWAN\_SET\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567925) - -A - -A - -A - -A -GSM, CDMA - -[OID\_WWAN\_PIN](https://msdn.microsoft.com/library/windows/hardware/ff569828) - -uses [**NDIS\_WWAN\_SET\_PIN**](https://msdn.microsoft.com/library/windows/hardware/ff567922) - -A - -Not supported - -A - -Not supported - -GSM, CDMA - -[OID\_WWAN\_PIN\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569829) has no corresponding structure - -Not supported - -Not supported - -A - -A - -GSM, CDMA - -[OID\_WWAN\_PIN\_EX](https://msdn.microsoft.com/library/windows/hardware/hh440095) - -uses [**NDIS\_WWAN\_SET\_PIN\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh439842) - -Not supported - -A - -Not supported - -A - -GSM, CDMA - -[OID\_WWAN\_HOME\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/ff569826) has no corresponding structure - -Not supported - -Not supported - -A - -A - -GSM, CDMA - -[OID\_WWAN\_PREFERRED\_PROVIDERS](https://msdn.microsoft.com/library/windows/hardware/ff569830)† - -uses [**NDIS\_WWAN\_SET\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567923) - -A - -A - -A - -A - -GSM only - -[OID\_WWAN\_VISIBLE\_PROVIDERS](https://msdn.microsoft.com/library/windows/hardware/ff569843) - -has no corresponding structure - -Not supported - -Not supported - -A - -A - -GSM - -[OID\_WWAN\_REGISTER\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569834) - -uses [**NDIS\_WWAN\_SET\_REGISTER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567926) - -A - -A - -A - -A - -CDMA - -[OID\_WWAN\_SIGNAL\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569836) - -uses [**NDIS\_WWAN\_SET\_SIGNAL\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567928) - -A - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_PACKET\_SERVICE](https://msdn.microsoft.com/library/windows/hardware/ff569827) - -uses [**NDIS\_WWAN\_SET\_PACKET\_SERVICE**](https://msdn.microsoft.com/library/windows/hardware/ff567921) - -A - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_PROVISIONED\_CONTEXTS](https://msdn.microsoft.com/library/windows/hardware/ff569831)†† - -uses [**NDIS\_WWAN\_SET\_PROVISIONED\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff567924) - -A - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_CONNECT](https://msdn.microsoft.com/library/windows/hardware/ff569823) - -uses [**NDIS\_WWAN\_SET\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567920) - -A - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_SMS\_CONFIGURATION](https://msdn.microsoft.com/library/windows/hardware/ff569837) - -uses [**NDIS\_WWAN\_SET\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567929) - -A - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_SMS\_READ](https://msdn.microsoft.com/library/windows/hardware/ff569839) - -uses [**NDIS\_WWAN\_SMS\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff567941) - -Not supported - -A - -A - -A - -GSM, CDMA - -[OID\_WWAN\_SMS\_SEND](https://msdn.microsoft.com/library/windows/hardware/ff569840) - -uses [**NDIS\_WWAN\_SMS\_SEND**](https://msdn.microsoft.com/library/windows/hardware/ff567943) - -A - -A - -Not supported - -Not supported - -GSM, CDMA - -[OID\_WWAN\_SMS\_DELETE](https://msdn.microsoft.com/library/windows/hardware/ff569838) - -uses [**NDIS\_WWAN\_SMS\_DELETE**](https://msdn.microsoft.com/library/windows/hardware/ff567938) - -A - -A - -Not supported - -Not supported - -GSM, CDMA - -[OID\_WWAN\_SMS\_STATUS](https://msdn.microsoft.com/library/windows/hardware/ff569841) - -uses [**NDIS\_WWAN\_SMS\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567945) - -Not supported - -Not supported - -A - -A - -GSM, CDMA - -[OID\_WWAN\_VENDOR\_SPECIFIC](https://msdn.microsoft.com/library/windows/hardware/ff569842)† uses a vendor-defined structure - -A - -A - -Not supported - -Not supported - -GSM, CDMA - -[OID\_WWAN\_DEVICE\_SERVICES](https://msdn.microsoft.com/library/windows/hardware/hh440093) has no corresponding structure - -Not supported - -Not supported - -Not supported - -A - -GSM, CDMA - -[OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS](https://msdn.microsoft.com/library/windows/hardware/hh440096) - -uses [**NDIS\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/hh439843) - -Not supported - -A - -Not supported - -Not supported - -GSM, CDMA - -[OID\_WWAN\_AUTH\_CHALLENGE](https://msdn.microsoft.com/library/windows/hardware/hh440092) - -uses [**NDIS\_WWAN\_AUTH\_CHALLENGE**](https://msdn.microsoft.com/library/windows/hardware/hh439833) - -Not supported - -Not supported - -Not supported - -A - -GSM, CDMA - -[OID\_WWAN\_USSD](https://msdn.microsoft.com/library/windows/hardware/hh440100) - -uses [**NDIS\_WWAN\_USSD\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439846) - -Not supported - -A - -Not supported - -Not supported - -GSM - -[OID\_WWAN\_DEVICE\_SERVICE\_COMMAND](https://msdn.microsoft.com/library/windows/hardware/hh440094) - -uses [**NDIS\_WWAN\_DEVICE\_SERVICE\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/hh439836) - -Not supported - -A - -Not supported - -A - -GSM, CDMA - -  - -**Note**  The following notes apply to the preceding table: -†represents optional OIDs that miniport drivers may support. Miniport drivers that do not support the optional OIDs must not return them in OID\_GEN\_SUPPORTED\_LIST. - -††represents miniport drivers that support GSM-based devices which can optionally support OID\_WWAN\_PROVISIONED\_CONTEXTS set and query operations. Miniport drivers that support CDMA-based devices can optionally support OID\_WWAN\_PROVISIONED\_CONTEXTS query operations for CDMA-based devices that report Simple IP (WWAN\_CTRL\_CAPS\_CDMA\_SIMPLE\_IP). - -Miniport drivers must support all non-optional OIDs. The MB Service may ignore any miniport driver that does not report all of the mandatory OIDs. - -"A" and "S" in the Set and Query operation columns in the preceding table reflect the nature of the transaction for completing the OID request: "A" stands for an asynchronous transaction and "S" for a synchronous transaction. - -The data structures in the preceding table correspond to set operation OIDs and to return data for synchronous query operation OIDs. - -The following OIDs share a common variable length list data structure called [**WWAN\_LIST\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff571208) in their corresponding data structures: -- OID\_WWAN\_READY\_INFO -- OID\_WWAN\_PREFERRED\_PROVIDERS -- OID\_WWAN\_VISIBLE\_PROVIDERS -- OID\_WWAN\_PROVISIONED\_CONTEXTS -- OID\_WWAN\_SMS\_READ - -  - -### WWAN-Specific Indications, Corresponding Data Structures, and OS Revisions +## WWAN-Specific OIDs + +| OID and Corresponding Data Structure | Set operation | | Query operation | | GSM/CDMA | +| --- | --- | --- | --- | --- |--- | +| | Windows 7 | Windows 8 | Windows 7 | Windows 8 | | +| [OID\_WWAN\_DRIVER\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569825) uses [**NDIS\_WWAN\_DRIVER\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567908) | Not supported | Not supported |S | S | GSM, CDMA | +| [OID\_WWAN\_DEVICE\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569824) has no corresponding structure | Not supported | Not supported | A | A | GSM, CDMA | +| [OID\_WWAN\_READY\_INFO](https://msdn.microsoft.com/library/windows/hardware/ff569833) has no corresponding structure | Not supported Not supported | A | A | GSM, CDMA | +| [OID\_WWAN\_SERVICE\_ACTIVATION](https://msdn.microsoft.com/library/windows/hardware/ff569835)† uses [**NDIS\_WWAN\_SERVICE\_ACTIVATION**](https://msdn.microsoft.com/library/windows/hardware/ff567918) | A | A | Not supported | Not supported | GSM, CDMA | +| [OID\_WWAN\_RADIO\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569832) uses [**NDIS\_WWAN\_SET\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567925) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_PIN](https://msdn.microsoft.com/library/windows/hardware/ff569828) uses [**NDIS\_WWAN\_SET\_PIN**](https://msdn.microsoft.com/library/windows/hardware/ff567922) | A | Not supported | A | Not supported | GSM, CDMA | +| [OID\_WWAN\_PIN\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569829) has no corresponding structure | Not supported | Not supported | A | A | GSM, CDMA | +| [OID\_WWAN\_PIN\_EX](https://msdn.microsoft.com/library/windows/hardware/hh440095) uses [**NDIS\_WWAN\_SET\_PIN\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh439842) | Not supported | A | Not supported | A | GSM, CDMA | +| [OID\_WWAN\_HOME\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/ff569826) has no corresponding structure | Not supported | Not supported | A | A | GSM, CDMA | +| [OID\_WWAN\_PREFERRED\_PROVIDERS](https://msdn.microsoft.com/library/windows/hardware/ff569830)† uses [**NDIS\_WWAN\_SET\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567923) | A | A | A | A | GSM only | +| [OID\_WWAN\_VISIBLE\_PROVIDERS](https://msdn.microsoft.com/library/windows/hardware/ff569843) has no corresponding structure | Not supported | Not supported | A | A | GSM | +| [OID\_WWAN\_REGISTER\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569834) uses [**NDIS\_WWAN\_SET\_REGISTER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567926) | A | A | A | A | CDMA | +| [OID\_WWAN\_SIGNAL\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569836) uses [**NDIS\_WWAN\_SET\_SIGNAL\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567928) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_PACKET\_SERVICE](https://msdn.microsoft.com/library/windows/hardware/ff569827) uses [**NDIS\_WWAN\_SET\_PACKET\_SERVICE**](https://msdn.microsoft.com/library/windows/hardware/ff567921) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_PROVISIONED\_CONTEXTS](https://msdn.microsoft.com/library/windows/hardware/ff569831)†† uses [**NDIS\_WWAN\_SET\_PROVISIONED\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff567924) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_CONNECT](https://msdn.microsoft.com/library/windows/hardware/ff569823) uses [**NDIS\_WWAN\_SET\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567920) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_SMS\_CONFIGURATION](https://msdn.microsoft.com/library/windows/hardware/ff569837) uses [**NDIS\_WWAN\_SET\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567929) | A | A | A | A | GSM, CDMA | +| [OID\_WWAN\_SMS\_READ](https://msdn.microsoft.com/library/windows/hardware/ff569839) uses [**NDIS\_WWAN\_SMS\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff567941) | Not supported | A | A | A |GSM, CDMA | +| [OID\_WWAN\_SMS\_SEND](https://msdn.microsoft.com/library/windows/hardware/ff569840) uses [**NDIS\_WWAN\_SMS\_SEND**](https://msdn.microsoft.com/library/windows/hardware/ff567943) | A | A | Not supported | Not supported | GSM, CDMA | +| [OID\_WWAN\_SMS\_DELETE](https://msdn.microsoft.com/library/windows/hardware/ff569838) uses [**NDIS\_WWAN\_SMS\_DELETE**](https://msdn.microsoft.com/library/windows/hardware/ff567938) | A | A | Not supported | Not supported | GSM, CDMA | +| [OID\_WWAN\_SMS\_STATUS](https://msdn.microsoft.com/library/windows/hardware/ff569841) uses [**NDIS\_WWAN\_SMS\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567945) | Not supported | Not supported | A | A | GSM, CDMA | +| [OID\_WWAN\_VENDOR\_SPECIFIC](https://msdn.microsoft.com/library/windows/hardware/ff569842)† uses a vendor-defined structure | A | A | Not supported | Not supported | GSM, CDMA | +| [OID\_WWAN\_DEVICE\_SERVICES](https://msdn.microsoft.com/library/windows/hardware/hh440093) has no corresponding structure | Not supported | Not supported | Not supported | A | GSM, CDMA | +| [OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS](https://msdn.microsoft.com/library/windows/hardware/hh440096) uses [**NDIS\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/hh439843) | Not supported | A | Not supported | Not supported | GSM, CDMA | +| [OID\_WWAN\_AUTH\_CHALLENGE](https://msdn.microsoft.com/library/windows/hardware/hh440092) uses [**NDIS\_WWAN\_AUTH\_CHALLENGE**](https://msdn.microsoft.com/library/windows/hardware/hh439833) | Not supported | Not supported | Not supported | A | GSM, CDMA | +| [OID\_WWAN\_USSD](https://msdn.microsoft.com/library/windows/hardware/hh440100) uses [**NDIS\_WWAN\_USSD\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439846) | Not supported | A | Not supported | Not supported | GSM | +| [OID\_WWAN\_DEVICE\_SERVICE\_COMMAND](https://msdn.microsoft.com/library/windows/hardware/hh440094) uses [**NDIS\_WWAN\_DEVICE\_SERVICE\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/hh439836) | Not supported | A | Not supported | A| GSM, CDMA | + +> [!NOTE]  +> The following notes apply to the preceding table: +> † represents optional OIDs that miniport drivers may support. Miniport drivers that do not support the optional OIDs must not return them in OID\_GEN\_SUPPORTED\_LIST. +> +> †† represents miniport drivers that support GSM-based devices which can optionally support OID\_WWAN\_PROVISIONED\_CONTEXTS set and query operations. Miniport drivers that support CDMA-based devices can optionally support OID\_WWAN\_PROVISIONED\_CONTEXTS query operations for CDMA-based devices that report Simple IP (WWAN\_CTRL\_CAPS\_CDMA\_SIMPLE\_IP). +> +> Miniport drivers must support all non-optional OIDs. The MB Service may ignore any miniport driver that does not report all of the mandatory OIDs. +> +> "A" and "S" in the Set and Query operation columns in the preceding table reflect the nature of the transaction for completing the OID request: "A" stands for an asynchronous transaction and "S" for a synchronous transaction. +> +> The data structures in the preceding table correspond to set operation OIDs and to return data for synchronous query operation OIDs. +> +> The following OIDs share a common variable length list data structure called [**WWAN\_LIST\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff571208) in their corresponding data structures: +> - OID\_WWAN\_READY\_INFO +> - OID\_WWAN\_PREFERRED\_PROVIDERS +> - OID\_WWAN\_VISIBLE\_PROVIDERS +> - OID\_WWAN\_PROVISIONED\_CONTEXTS +> - OID\_WWAN\_SMS\_READ  + +## WWAN-Specific Indications, Corresponding Data Structures, and OS Revisions @@ -600,14 +251,11 @@ The following OIDs share a common variable length list data structure called [**
-  - -**Note**  The following notes apply to the preceding table: -†represents optional indications that miniport drivers may support. Be aware that if a miniport driver supports an optional OID, the miniport driver should also support the corresponding indication. +> [!NOTE] +> The following notes apply to the preceding table: +> † represents optional indications that miniport drivers may support. Be aware that if a miniport driver supports an optional OID, the miniport driver should also support the corresponding indication.  -  - -### WWAN-Specific Indication Support for GSM, CDMA, and Unsolicited Indications +## WWAN-Specific Indication Support for GSM, CDMA, and Unsolicited Indications @@ -790,11 +438,9 @@ The following OIDs share a common variable length list data structure called [** -

N

- -  +  -### Multi-carrier Specific OIDs +## Multi-carrier Specific OIDs The following changes apply to NDIS 6.30 miniport drivers that support multi-carrier mode. If the miniport driver does not support multi-carrier mode then please refer to the preceding table. @@ -827,11 +473,9 @@ The following changes apply to NDIS 6.30 miniport drivers that support multi-car

GSM, CDMA

- - -  +  -### Multi-carrier Specific Indications, Corresponding Data Structures, and OS Revisions +## Multi-carrier Specific Indications, Corresponding Data Structures, and OS Revisions @@ -859,11 +503,9 @@ The following changes apply to NDIS 6.30 miniport drivers that support multi-car -

NDIS_WWAN_VISIBLE_PROVIDERS_REVISION_1. The VisibleListHeader.ElementType should be set to WwanStructProvider2 and the list should contain WWAN_PROVIDER2 structure.

- -  +  -### Multi-carrier Specific Indication Support for GSM, CDMA, and Unsolicited Indications +## Multi-carrier Specific Indication Support for GSM, CDMA, and Unsolicited Indications @@ -901,15 +543,4 @@ The following changes apply to NDIS 6.30 miniport drivers that support multi-car -

N

- -  - -  - -  - - - - - + \ No newline at end of file diff --git a/windows-driver-docs-pr/network/mb-lte-attach-operations.md b/windows-driver-docs-pr/network/mb-lte-attach-operations.md index cdadc60406..6bf6b075db 100644 --- a/windows-driver-docs-pr/network/mb-lte-attach-operations.md +++ b/windows-driver-docs-pr/network/mb-lte-attach-operations.md @@ -21,9 +21,9 @@ To establish a default EPS bearer with the network the device must request a PDP 3. The device does not specify a LTE attach APN and lets network assign one back to the device. 4. The device registered from a 2G/3G network to LTE and there was already at minimum one active PDP context. The network uses it as the LTE attach APN. -Today, all LTE attach APN information is provided by IHVs and OEMs directly in the modem for each provider for which it has configuration. However, it is not a fully scalable model for IHVs and OEMs to have all possible LTE attach APN settings for all operators around the globe. Starting in Windows 10 Version 1703, new interfaces are defined for both NDIS OIDs and MBIM Microsoft proprietary CIDs to support LTE attach APN configuration from the OS. Similar to how the OS receives traditional Internet APN configuration from users, enterprises, operators, and other sources, LTE attach APN management will also be part of Windows moving forward. +Today, all LTE attach APN information is provided by IHVs and OEMs directly in the modem for each provider for which it has configuration. However, it is not a fully scalable model for IHVs and OEMs to have all possible LTE attach APN settings for all operators around the globe. Starting in Windows 10, version 1703, new interfaces are defined for both NDIS OIDs and MBIM Microsoft proprietary CIDs to support LTE attach APN configuration from the OS. Similar to how the OS receives traditional Internet APN configuration from users, enterprises, operators, and other sources, LTE attach APN management will also be part of Windows moving forward. -Starting in Windows 10 Version 1703, if the underlying hardware supports LTE attach APN configuration from the OS then the user will be able to configure the LTE attach APN from Settings. Hardware that has default LTE attach APN configurations must also make its configuration available by the OS. +Starting in Windows 10, version 1703, if the underlying hardware supports LTE attach APN configuration from the OS then the user will be able to configure the LTE attach APN from Settings. Hardware that has default LTE attach APN configurations must also make its configuration available by the OS. This feature is supported by adding in two new OIDs and CIDs. For IHV partners that implement MBIM, only the CID version has to be supported. @@ -39,8 +39,8 @@ UUID Value = **3d01dcc5-fef5-4d05-0d3abef7058e9aaf** | CID | Command Code | Minimum OS Version | | --- | --- | --- | -| MBIM_CID_MS_LTE_ATTACH_CONFIG | 3 | Windows 10 Version 1703 | -| MBIM_CID_MS_LTE_ATTACH_STATUS | 4 | Windows 10 Version 1703 | +| MBIM_CID_MS_LTE_ATTACH_CONFIG | 3 | Windows 10, version 1703 | +| MBIM_CID_MS_LTE_ATTACH_STATUS | 4 | Windows 10, version 1703 | ### MBIM_CID_MS_LTE_ATTACH_CONFIG diff --git a/windows-driver-docs-pr/network/mb-multi-sim-operations.md b/windows-driver-docs-pr/network/mb-multi-sim-operations.md index fda44ba7ae..a1a86587a4 100644 --- a/windows-driver-docs-pr/network/mb-multi-sim-operations.md +++ b/windows-driver-docs-pr/network/mb-multi-sim-operations.md @@ -16,7 +16,7 @@ Traditionally, non-phone Windows devices have not been configured for multi-SIM Most typical multi-SIM phone devices have dual SIM slots but are limited to one primary SIM card supporting data while the other only supports voice features. Such a limitation does not exist in the non-phone PC model as all SIM cards are used for data connection. -While the framework defined in this specification can theoretically support an unbounded number of modems and SIM cards, Windows 10 Version 1703 and later supports only the dual-SIM/single-active scenario end to end. +While the framework defined in this specification can theoretically support an unbounded number of modems and SIM cards, Windows 10, version 1703 and later supports only the dual-SIM/single-active scenario end to end. ## NDIS Modem Interface Specification @@ -92,7 +92,7 @@ To query the status of a particular slot on the modem, the host uses [OID_WWAN_S ## Per-device and Per-executor Commands -With the addition of the executor concept to non-Windows Mobile devices in Windows 10 Version 1703 and later, OIDs are now split into two categories: per-device OIDs and per-executor OIDs. The table below explains which OIDs fall into which category. +With the addition of the executor concept to non-Windows Mobile devices in Windows 10, version 1703 and later, OIDs are now split into two categories: per-device OIDs and per-executor OIDs. The table below explains which OIDs fall into which category. | Per-device or Per-executor| OID name | | --- | --- | @@ -136,7 +136,7 @@ With the addition of the executor concept to non-Windows Mobile devices in Windo | | OID_WWAN_SLOT_INFO_STATUS | > [!NOTE] -> [OID_WWAN_RADIO_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569832) has been updated for Windows 10 Version 1703 as well. See OID_WWAN_RADIO_STATE for more information. +> [OID_WWAN_RADIO_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569832) has been updated for Windows 10, version 1703 as well. See OID_WWAN_RADIO_STATE for more information. ## MBIM Interface Update for Multi-SIM Operations @@ -166,10 +166,10 @@ The following CIDs are defined for **UUID_MS_BasicConnect**: | CID | Command Code | Minimum OS Version | | --- | --- | --- | -| MBIM_CID_MS_SYS_CAPS | 5 | Windows 10 Version 1703 | -| MBIM_CID_MS_DEVICE_CAPS_V2 | 6 | Windows 10 Version 1703 | -| MBIM_CID_MS_DEVICE_SLOT_MAPPINGS | 7 | Windows 10 Version 1703 | -| MBIM_CID_MS_SLOT_INFO_STATUS | 8 | Windows 10 Version 1703 | +| MBIM_CID_MS_SYS_CAPS | 5 | Windows 10, version 1703 | +| MBIM_CID_MS_DEVICE_CAPS_V2 | 6 | Windows 10, version 1703 | +| MBIM_CID_MS_DEVICE_SLOT_MAPPINGS | 7 | Windows 10, version 1703 | +| MBIM_CID_MS_SLOT_INFO_STATUS | 8 | Windows 10, version 1703 | All offsets in the CID sections below are calculated from the beginning of the InformationBuffer MBIM_COMMAND_MSG. diff --git a/windows-driver-docs-pr/network/mb-ndis-status-notifications.md b/windows-driver-docs-pr/network/mb-ndis-status-notifications.md new file mode 100644 index 0000000000..6c202969ba --- /dev/null +++ b/windows-driver-docs-pr/network/mb-ndis-status-notifications.md @@ -0,0 +1,100 @@ +--- +title: MB NDIS Status Notifications +author: windows-driver-content +description: MB NDIS Status Notifications +ms.assetid: 97538f74-f602-4d38-a5a8-e52eb3194fb9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# MB NDIS Status Notifications + + +This section NDIS status notifications for Mobile Broadband (MB) miniport drivers: + +[**NDIS\_STATUS\_WWAN\_AUTH\_RESPONSE**](ndis-status-wwan-auth-response.md) + +[**NDIS\_STATUS\_WWAN\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567843) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_CAPS**](ndis-status-wwan-device-caps.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_CAPS\_EX**](ndis-status-wwan-device-caps-ex.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT**](ndis-status-wwan-device-service-event.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE**](ndis-status-wwan-device-service-response.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION**](ndis-status-wwan-device-service-session.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_READ**](ndis-status-wwan-device-service-session-read.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](ndis-status-wwan-device-service-session-write-complete.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION**](ndis-status-wwan-device-service-subscription.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](ndis-status-wwan-device-service-supported-commands.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPINGS**](ndis-status-wwan-device-slot-mappings.md) + +[**NDIS\_STATUS\_WWAN\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/ff567848) + +[**NDIS\_STATUS\_WWAN\_PACKET\_SERVICE**](https://msdn.microsoft.com/library/windows/hardware/ff567850) + +[**NDIS\_STATUS\_WWAN\_PIN\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567851) + +[**NDIS\_STATUS\_WWAN\_PIN\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff567852) + +[**NDIS\_STATUS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](ndis-status-wwan-preferred-multicarrier-providers.md) + +[**NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567853) + +[**NDIS\_STATUS\_WWAN\_PRESHUTDOWN\_STATE**](ndis-status-wwan-preshutdown-state.md) + +[**NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS**](https://msdn.microsoft.com/library/windows/hardware/ff567854) + +[**NDIS\_STATUS\_WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567855) + +[**NDIS\_STATUS\_WWAN\_READY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567856) + +[**NDIS\_STATUS\_WWAN\_REGISTER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567857) + +[**NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION**](https://msdn.microsoft.com/library/windows/hardware/ff567858) + +[**NDIS\_STATUS\_WWAN\_SET\_HOME\_PROVIDER\_COMPLETE**](ndis-status-wwan-set-home-provider-complete.md) + +[**NDIS\_STATUS\_WWAN\_SIGNAL\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567859) + +[**NDIS\_STATUS\_WWAN\_SLOT\_INFO\_STATUS**](ndis-status-wwan-slot-info-status.md) + +[**NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567860) + +[**NDIS\_STATUS\_WWAN\_SMS\_DELETE**](https://msdn.microsoft.com/library/windows/hardware/ff567861) + +[**NDIS\_STATUS\_WWAN\_SMS\_RECEIVE**](https://msdn.microsoft.com/library/windows/hardware/ff567862) + +[**NDIS\_STATUS\_WWAN\_SMS\_SEND**](https://msdn.microsoft.com/library/windows/hardware/ff567863) + +[**NDIS\_STATUS\_WWAN\_SMS\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567864) + +[**NDIS\_STATUS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES**](ndis-status-wwan-supported-device-services.md) + +[**NDIS\_STATUS\_WWAN\_SYS\_CAPS**](ndis-status-wwan-sys-caps.md) + +[**NDIS\_STATUS\_WWAN\_USSD**](ndis-status-wwan-ussd.md) + +[**NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC**](https://msdn.microsoft.com/library/windows/hardware/ff567865) + +[**NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567866) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20MB%20NDIS%20Status%20Notifications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/mb-network-blacklist-operations.md b/windows-driver-docs-pr/network/mb-network-blacklist-operations.md index e96631670f..c98e68d889 100644 --- a/windows-driver-docs-pr/network/mb-network-blacklist-operations.md +++ b/windows-driver-docs-pr/network/mb-network-blacklist-operations.md @@ -10,7 +10,7 @@ ms.technology: windows-devices # MB Network Blacklist Operations -A device could be required to not register to a network under various scenarios, such as when a specific SIM card is inserted or if a device does not want to register to a specific network. To address these situations, Windows 10 Version 1703 is adding modem interfaces to enable the OS to configure blacklists for SIM cards and network providers. +A device could be required to not register to a network under various scenarios, such as when a specific SIM card is inserted or if a device does not want to register to a specific network. To address these situations, Windows 10, version 1703 is adding modem interfaces to enable the OS to configure blacklists for SIM cards and network providers. At any time, the OS can configure the MCC/MNC pair in the modem to specify the SIM or network to which the device is not allowed to register. The interface is flexible enough to allow two different lists, one for SIM providers, and another for network providers. If the device did not attempt registration because a particular SIM or network provider was blacklisted, the modem must report the registration status as denied. @@ -26,7 +26,7 @@ UUID Value = **3d01dcc5-fef5-4d05-0d3abef7058e9aaf** | CID | Command Code | Minimum OS Version | | --- | --- | --- | -| MBIM_CID_MS_NETWORK_BLACKLIST | 2 | Windows 10 Version 1703 | +| MBIM_CID_MS_NETWORK_BLACKLIST | 2 | Windows 10, version 1703 | ### MBIM_CID_MS_NETWORK_BLACKLIST diff --git a/windows-driver-docs-pr/network/mb-provisioned-context-operations.md b/windows-driver-docs-pr/network/mb-provisioned-context-operations.md index 1e5023f6c5..61dcfdbdee 100644 --- a/windows-driver-docs-pr/network/mb-provisioned-context-operations.md +++ b/windows-driver-docs-pr/network/mb-provisioned-context-operations.md @@ -15,13 +15,13 @@ Provisioning is vital for cellular-connectable devices because each mobile opera 1. APN configurations that are known to the OS because there are applications or clients above the OS that requires those connections. 2. APN configurations that are not made known to the OS because they are internally consumed by the modem for connections that are not leveraged by the OS and its clients. -Ideally, the modem should only store the APN configurations the OS does not have to know. However, IHV and OEM partners have traditionally provided the Internet and Purchase APNs, configurations known to the OS, in the modem as well. Before Windows 10 Version 1703’s release, Windows only read the Internet and Purchase APN configurations from the modem to establish Internet connections. Starting in Windows 10 Version 1703, there might be additional cases in which the modem’s APN configuration would have to be managed by Windows, especially if there are clients in the OS such as user settings or OMA-DM that want to change cellular configuration. This in turn could also affect the modem’s APN configuration. For example, there might be an IMS stack in the modem that is using the IMS APN for SMS over IMS. Typically, those connections are not exposed to the OS, but under certain scenarios the IMS APN configuration may have to be changed. This change could be done through the OS. In order to support this, starting in Windows 10 Version 1703 the OS can configure different types of APNs into the modem. +Ideally, the modem should only store the APN configurations the OS does not have to know. However, IHV and OEM partners have traditionally provided the Internet and Purchase APNs, configurations known to the OS, in the modem as well. Before Windows 10, version 1703’s release, Windows only read the Internet and Purchase APN configurations from the modem to establish Internet connections. Starting in Windows 10, version 1703, there might be additional cases in which the modem’s APN configuration would have to be managed by Windows, especially if there are clients in the OS such as user settings or OMA-DM that want to change cellular configuration. This in turn could also affect the modem’s APN configuration. For example, there might be an IMS stack in the modem that is using the IMS APN for SMS over IMS. Typically, those connections are not exposed to the OS, but under certain scenarios the IMS APN configuration may have to be changed. This change could be done through the OS. In order to support this, starting in Windows 10, version 1703 the OS can configure different types of APNs into the modem. -The USB forum’s MBIM 1.0 and Microsoft NDIS each have an existing CID and OID respectively to allow the OS to set and query the APN configurations in the modem. For MBIM 1.0 it does this through MBIM_CID_PROVISIONED_CONTEXT while for NDIS it does this through [OID_WWAN_PROVISIONED_CONTEXTS](https://msdn.microsoft.com/library/windows/hardware/ff569831). However, the existing CID and OID were not designed with clear guidance on how the modem is expected to behave in various situations such as a power cycle or SIM swap. Devices that want to support OS configuring and updating of modem-provisioned contexts going forward will have to implement the newer version of the CID and OID in Windows 10 Version 1703. To ensure backward compatibility, for IHVs/OEMs that want to support new hardware on OS versions older than 1703, they will have to continue to support the existing MBIM_CID_PROVISIONED_CONTEXT and OID_WWAN_PROVISIONED_CONTEXTS. Starting from Windows 10 Version 1703, if the device supports the new version of the CID and OID then the OS will only use the newer version of the command to query and set APN context configuration in the modem. +The USB forum’s MBIM 1.0 and Microsoft NDIS each have an existing CID and OID respectively to allow the OS to set and query the APN configurations in the modem. For MBIM 1.0 it does this through MBIM_CID_PROVISIONED_CONTEXT while for NDIS it does this through [OID_WWAN_PROVISIONED_CONTEXTS](https://msdn.microsoft.com/library/windows/hardware/ff569831). However, the existing CID and OID were not designed with clear guidance on how the modem is expected to behave in various situations such as a power cycle or SIM swap. Devices that want to support OS configuring and updating of modem-provisioned contexts going forward will have to implement the newer version of the CID and OID in Windows 10, version 1703. To ensure backward compatibility, for IHVs/OEMs that want to support new hardware on OS versions older than 1703, they will have to continue to support the existing MBIM_CID_PROVISIONED_CONTEXT and OID_WWAN_PROVISIONED_CONTEXTS. Starting from Windows 10, version 1703, if the device supports the new version of the CID and OID then the OS will only use the newer version of the command to query and set APN context configuration in the modem. ## MB Interface Update for Provisioned Context Operations -While MBIM has a command for retrieving and replacing contexts stored in the modem, it does not have a field to “disable” or “enable” a profile. Therefore, the existing MBIM_CID_PROVISIONED_CONTEXT must be updated for Windows 10 Version 1703 to include this capability. Because MBIM does not have a versioning mechanism, a new MSFT proprietary CID is defined as MBIM_CID_MS_PROVISIONED_CONTEXT_V2. +While MBIM has a command for retrieving and replacing contexts stored in the modem, it does not have a field to “disable” or “enable” a profile. Therefore, the existing MBIM_CID_PROVISIONED_CONTEXT must be updated for Windows 10, version 1703 to include this capability. Because MBIM does not have a versioning mechanism, a new MSFT proprietary CID is defined as MBIM_CID_MS_PROVISIONED_CONTEXT_V2. Service Name = **Basic Connect Extensions** @@ -31,13 +31,13 @@ UUID Value = **3d01dcc5-fef5-4d05-0d3abef7058e9aaf** | CID | Command Code | Minimum OS Version | | --- | --- | --- | -| MBIM_CID_MS_PROVISIONED_CONTEXT_V2 | 1 | Windows 10 Version 1703 | +| MBIM_CID_MS_PROVISIONED_CONTEXT_V2 | 1 | Windows 10, version 1703 | ### MBIM_CID_MS_PROVISIONED_CONTEXT_V2 #### Description -Although MBIM 1.0 has defined MBIM_CID_PROVISIONED_CONTEXT for the OS and its upper clients to manage provisioned contexts in the modem, Windows traditionally only queried the context in the modem but did not set it from the OS. Starting in Windows 10 Version 1703, there is increasing need for the OS to be able to configure the contexts in the modem. For example, if there is an IMS stack in the modem that is opaque to the OS, the OS should be able to specify the IMS APN that the modem should use. Because each modem IHV can have its own proprietary way to store contexts in the modem, it is impossible for the OS to manage profiles on the ContextId level the way MBIM_CID_PROVISIONED_CONTEXT might suggest. Instead, from the OS’s perspective it is more important to prescribe which context to use for each context type. Returning to the IMS example, regardless of how many existing provisioned contexts are in the modem, if the OS sets a context that has MBIM_CONTEXT_TYPE = IMS then all IMS traffic initiated by the modem should only be attempted on that context. +Although MBIM 1.0 has defined MBIM_CID_PROVISIONED_CONTEXT for the OS and its upper clients to manage provisioned contexts in the modem, Windows traditionally only queried the context in the modem but did not set it from the OS. Starting in Windows 10, version 1703, there is increasing need for the OS to be able to configure the contexts in the modem. For example, if there is an IMS stack in the modem that is opaque to the OS, the OS should be able to specify the IMS APN that the modem should use. Because each modem IHV can have its own proprietary way to store contexts in the modem, it is impossible for the OS to manage profiles on the ContextId level the way MBIM_CID_PROVISIONED_CONTEXT might suggest. Instead, from the OS’s perspective it is more important to prescribe which context to use for each context type. Returning to the IMS example, regardless of how many existing provisioned contexts are in the modem, if the OS sets a context that has MBIM_CONTEXT_TYPE = IMS then all IMS traffic initiated by the modem should only be attempted on that context. MBIM 1.0 specifies that MBIM_CID_PROVISIONED_CONTEXT can only call Query on contexts that match the Provider ID (MCC/MNC pair) of the inserted SIM card. For Set requests, MBIM_CID_PROVISIONED_CONTEXT can specify the Provider ID of the context that it wants to be stored. MBIM_CID_MS_PROVISIONED_CONTEXT_V2 specifies a similar but different behavior from MBIM 1.0. For each Query, the OS continues to expect the modem to only return contexts that match the Provider ID of the inserted SIM card. For Set, the command will no longer enable the OS to Set contexts that do not match the current Provider ID in the SIM card. It is expected that the Set request is to create a context for the current Provider ID of the presented SIM card. As an example, the user swaps from SIM 1 to SIM 2, then back to SIM 1. It is expected that during first SIM swap, the modem should resolve all its contexts before loading the context for SIM 2. When the user swaps back to SIM 1, SIM 1’s factory default configuration should be restored. It is not expected for the modem to save runtime configuration across SIM swaps. @@ -57,7 +57,7 @@ The new MBIM_CID_MS_PROVISONED_CONTEXT_V2 command is almost identical to MBIM 1. The MBIM_CONTEXT_IP_TYPE structure from MBIM 1.0 is only used for MBIM_CID_CONNECT. In MBIM_CID_MS_PROVISIONED_CONTEXT_V2, Microsoft has added the IP type as one of the parameters for each context. The modem should report MBIMContextIPTypeDefault if it is not configured for the given context. -In Windows 10 Version 1703, with new hardware that supports MBIM_CID_MS_PROVISIONED_CONTEXT_V2, the legacy MBIM_CID_PROVISIONED_CONTEXT will not be used from first party components. If there are other legacy client/OS components that send down MBIM_CID_PROVISIONED_CONTEXT, the modem is expected to return results as it did in versions of Windows earlier than Windows 10 Version 1703. +In Windows 10, version 1703, with new hardware that supports MBIM_CID_MS_PROVISIONED_CONTEXT_V2, the legacy MBIM_CID_PROVISIONED_CONTEXT will not be used from first party components. If there are other legacy client/OS components that send down MBIM_CID_PROVISIONED_CONTEXT, the modem is expected to return results as it did in versions of Windows earlier than Windows 10, version 1703. ##### Query diff --git a/windows-driver-docs-pr/network/mb-sar-platform-support.md b/windows-driver-docs-pr/network/mb-sar-platform-support.md index 53252907c6..f552a47861 100644 --- a/windows-driver-docs-pr/network/mb-sar-platform-support.md +++ b/windows-driver-docs-pr/network/mb-sar-platform-support.md @@ -10,13 +10,15 @@ ms.technology: windows-devices # MB SAR Platform Support +## Overview + Traditionally, OEMs have implemented proprietary solutions for Selective Absorption Rate (SAR). This requires the OEM to implement a device service command that is either only identified between their User Mode Driver (UMDF) and the modem or requires kernel mode components to directly interact with the modem. Some OEMs may even have a hybrid solution where they have both UMDF-modem and kernel mode-modem components. As radio radiation awareness has increased, standardizing the interface for OEM software components to pass through the SAR command to the modem introduces the following benefits: 1. OEMs can move toward user mode components and makes the system more stable, as errors in user mode are not fatal to the system compared to kernel mode. 2. Windows provides a platform standard interface and reduces the proprietary implementation from OEMs. 3. Services in the platform that want to take advantage of SAR can retrieve the information from the modem. -Starting in Windows 10 Version 1703, Windows supports passing through SAR configuration and modem transmission status. Windows will continue to leave the SAR business logic to IHVs and OEMs to use as a self-differentiating factor but will provide an interface to streamline the platform. Two new NDIS OIDs and two new MBIM CIDs have been defined to support this interface. Devices that want to take advantage of OS support must implement both commands. +Starting in Windows 10, version 1703, Windows supports passing through SAR configuration and modem transmission status. Windows will continue to leave the SAR business logic to IHVs and OEMs to use as a self-differentiating factor but will provide an interface to streamline the platform. Two new NDIS OIDs and two new MBIM CIDs have been defined to support this interface. Devices that want to take advantage of OS support must implement both commands. This feature is supported by adding in two new OIDs and CIDs. For IHV partners that implement MBIM, only the CID version needs to be supported. @@ -32,12 +34,12 @@ UUID Value = **68223D04-9F6C-4E0F-822D-28441FB72340** | CID | Minimum OS Version | | --- | --- | -| MBIM_CID_MS_SAR_CONFIG | Windows 10 Version 1703 | -| MBIM_CID_MS_TRANSMISSION_STATUS | Windows 10 Version 1703 | +| MBIM_CID_MS_SAR_CONFIG | Windows 10, version 1703 | +| MBIM_CID_MS_TRANSMISSION_STATUS | Windows 10, version 1703 | -### MBIM_CID_MS_SAR_CONFIG +## MBIM_CID_MS_SAR_CONFIG -#### Description +### Description This command sets or returns information about a MB device’s SAR back off mode and level. The MB device must act on the SAR back off command immediately by overwriting the current Transmit power limits and applying them to the transmitting antennas. If an antenna’s SAR configuration was not changed by the operating system, it should maintain its current setting. For example, if the operating system sets antenna 1 to be SAR back off index 1, then antenna 2’s configuration should be kept the same without any changes. @@ -45,32 +47,32 @@ It is expected for devices that support this command to implement Query so they After each Query or Set response, the modem should return a MBIM_MS_SAR_CONFIG structure that contains information for all antennas on the device associated with Mobile Broadband. -##### Query +#### Query The InformationBuffer on MBIM_COMMAND_MSG is not used. MBIM_MS_SAR_CONFIG is returned in the InformationBuffer of MBIM_COMMAND_DONE. -##### Set +#### Set The InformationBuffer on MBIM_COMMAND_MSG contains a MBIM_MS_SAR_CONFIG. MBIM_MS_SAR_CONFIG is returned in the InformationBuffer of MBIM_COMMAND_DONE. -##### Unsolicited Events +#### Unsolicited Events Not applicable. -#### Parameters +### Parameters | | Set | Query | Notification | | --- | --- | --- | --- | | Command | MBIM_MS_SET_SAR_CONFIG | Not applicable | Not applicable | | Response | MBIM_MS_SAR_CONFIG | MBIM_MS_SAR_CONFIG | Not applicable | -#### Data Structures +### Data Structures -##### Query +#### Query The InformationBuffer shall be NULL and InformationBufferLength shall be zero. -##### Set +#### Set The following MBIM_MS_SET_SAR_CONFIG structure shall be used in the InformationBuffer. @@ -102,10 +104,10 @@ MBIM_MS_SAR_CONFIG_STATE describes the possible states for SAR backoff for the a | Offset | Size | Field | Type | Description | | --- | --- | --- | --- | --- | -| 0 | 4 | SARAntennaIndex | UINT32 | An antenna index that corresponds to the SARBackOffIndex field in the MBIM_MS_SAR_CONFIG_STATE table. It corresponds to the antenna number and is left to OEM implementation to index each antenna on the device. If this value is set to 0xFFFFFFFFF, the SARBackOffIndex should be applied to all antennas. | -| 4 | 4 | SARBAckOffIndex | UINT32 | A back off index that corresponds to the back off table that is defined by OEM or modem vendor. The table has individual bands and associated back off parameters. | +| 0 | 4 | SARAntennaIndex | UINT32 | An antenna index that corresponds to the **SARBackOffIndex** field in this table. It corresponds to the antenna number and is left to OEM implementation to index each antenna on the device. Any index is valid for this value. If this value is set to **0xFFFFFFFF** in a *Set* command, the **SARBackOffIndex** should be applied to all antennas. If this value is set to **0xFFFFFFFF** in response, it indicates that **SARBackOffIndex** is applied to all antennas. | +| 4 | 4 | SARBAckOffIndex | UINT32 | A back off index that corresponds to the back off table that is defined by the OEM or modem vendor. The table has individual bands and associated back off parameters. | -##### Response +#### Response The following MBIM_MS_SAR_CONFIG structure shall be used in the InformationBuffer. MBIM_MS_SAR_CONFIG specifies the configuration for SAR. @@ -125,11 +127,11 @@ The following MBIM_MS_SAR_HARDWARE_WIFI_INTEGRATION structure is used in the pre | MBIMMsSARWifiHardwareIntegrated | 0 | Wi-Fi and Cellular modem SAR is integrated in the device. | | MBIMMsSARWifiHardwareNotIntegrated | 1 | Wi-Fi and Cellular modem SAR is not integrated in the device. | -##### Notification +#### Notification Not applicable. -#### Status Codes +### Status Codes | Error Code | Description | | --- | --- | @@ -140,9 +142,9 @@ Not applicable. | MBIM_STATUS_INVALID_PARAMETERS | The operation failed because of invalid parameters. | | MBIM_STATUS_OPERATION_NOT_ALLOWED | The operation failed because the operation is not allowed. | -### MBIM_CID_MS_TRANSMISSION_STATUS +## MBIM_CID_MS_TRANSMISSION_STATUS -#### Description +### Description This command is used to enable or disable the notification from the modem on transmit state. It is a per-executor command as each executor can have different channel transmit state. For example, a dual SIM modem might have one on LTE and the other on GSM. At the same time, it can be used to provide the transmit status of the modem. This notification could be used for clients that are interested in whether the modem is transmitting data or not. The modem should provide notification any time there is a start or end of TX traffic. If the duty cycle is too small and cannot be provided in real time to the host, then the TX state can be kept as active for a set time with a hysteresis timer before it sends an update of the state. As an example, it might be that there was a short burst of TX and the modem could not provide the start and end notification in time. The modem should send up notification when the TX traffic starts and should continue to monitor its TX traffic during the hysteresis timer. If no more TX traffic was generated within the timer’s timeframe, then it should report that TX traffic has ended. @@ -152,32 +154,32 @@ The Wi-Fi back off mechanism and command is out of scope of this specification. OEMs that use this command should be aware of the potential power impact as the modem may be sending up transmission-related notifications at all times, including reduced power states. The OS, by default, will not allow this notification to awake the AP during Modern Standby to improve power performance. -##### Query +#### Query The InformationBuffer on MBIM_COMMAND_MSG is not used. MBIM_MS_SET_TRANSMISSION_STATUS_INFO is returned in the InformationBuffer of MBIM_COMMAND_DONE. -##### Set +#### Set The InformationBuffer on MBIM_COMMAND_MSG contains MBIM_MS_SET_TRANSMISSION_STATUS. MBIM_MS_SET_TRANSIMISSION_STATUS _INFO is returned in the InformationBuffer of MBIM_COMMAND_DONE. -##### Unsolicited Events +#### Unsolicited Events Unsolicited events contain MBIM_MS_TRANSMISSION_STATUS_INFO and are sent when there is a change to the active over-the-air (OTA) channels. For example, if a modem started uploading packet data, it would be required to set up uplink channels when it uses the network data channel so that it can upload payloads. This would trigger the notification to be provided to the operating system. -#### Parameters +### Parameters | | Set | Query | Notification | | --- | --- | --- | --- | | Command | MBIM_MS_SET_TRANSMISSION_STATUS | Not applicable | Not applicable | | Response | MBIM_MS_TRANSMISSION_STATUS_INFO | MBIM_MS_TRANSMISSION_STATUS_INFO | MBIM_MS_TRANSMISSION_STATUS_INFO | -#### Data Structures +### Data Structures -##### Query +#### Query The InformationBuffer on MBIM_COMMAND_MSG is not used. MBIM_MS_TRANSMISSION_STATUS_INFO is returned in the InformationBuffer of MBIM_COMMAND_DONE. -##### Set +#### Set The following MBIM_MS_SET_TRANSMISSION_STATUS structure shall be used in the InformationBuffer. @@ -193,7 +195,7 @@ The following MBIM_MS_TRANSMISSION_STATUS_NOTIFICATION structure is used in the | MBIMMsTransmissionNotificationDisabled | 0 | Modem channel transmission status notification disabled. | | MBIMMsTransmissionNotificationEnabled | 1 | Modem channel transmission status notification enabled. | -##### Response +#### Response The following MBIM_MS_TRANSMISSION_STATUS_INFO structure is used for response. @@ -210,11 +212,11 @@ The following MBIM_MS_TRANSMISSION_STATUS structure is used in the preceding tab | MBIMMsTransmissionStateInactive | 0 | The modem was not actively transmitting data without any continuous lapse of transmission for the last HysteresisTimer value. | | MBIMMsTransmissionStateActive | 1 | The modem was actively transmitting data. | -##### Notification +#### Notification For more information, see the MBIM_MS_SET_TRANSMISSION_STATUS_INFO table. -#### Status Codes +### Status Codes | Error Code | Description | | --- | --- | diff --git a/windows-driver-docs-pr/network/mstcpip-h.md b/windows-driver-docs-pr/network/mstcpip-h.md new file mode 100644 index 0000000000..a98b7e6043 --- /dev/null +++ b/windows-driver-docs-pr/network/mstcpip-h.md @@ -0,0 +1,31 @@ +--- +title: Mstcpip.h +author: windows-driver-content +description: This section contains network driver topics for the Mstcpip.h header. +ms.assetid: 5623EB2D-CA8D-4176-922E-29B8C66AA2CF +keywords: +- Mstcpip.h network drivers +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Mstcpip.h + +This section contains network driver topics for the Mstcpip.h header. These topics may also be shared with the user mode applications that interact with network drivers. + +The Mstcpip.h header contains definitions for Microsoft-specific extensions to the core Winsock definitions. + +## In this section + +* [SIO_LOOPBACK_FAST_PATH control code](sio-loopback-fast-path.md) +* [SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT control code](sio-query-wfp-connection-redirect-context.md) +* [SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS control code](sio-query-wfp-connection-redirect-records.md) +* [SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS control code](sio-set-wfp-connection-redirect-records.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Mstcpip.h%20%20RELEASE:%20%288/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/native-802-11-extensible-ap-mib-objects.md b/windows-driver-docs-pr/network/native-802-11-extensible-ap-mib-objects.md new file mode 100644 index 0000000000..dbde1ad35e --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-extensible-ap-mib-objects.md @@ -0,0 +1,42 @@ +--- +title: Native 802.11 Extensible AP MIB objects +description: This section describes Native 802.11 Extensible AP MIB objects +keywords: ["Native 802.11 Extensible AP MIB objects", "Native 802.11 WLAN Extensible AP MIB objects", "WDK Native 802.11 Extensible AP MIB objects"] +ms.assetid: 6F80AF71-1CC0-44ED-AD91-DF8814190562 +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Extensible AP MIB objects + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +Some of the Extensible Access Point (ExtAP) object identifiers (OIDs) are used to reference Extensible AP management information base (MIB) objects. + +ExtAP objects are attributes of the IEEE 802.11 media access control (MAC) layer. The miniport driver must set these MIB objects to their default values whenever any of the following occur: + +- The miniport driver's [MiniportInitializeEx](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. +- A method request of [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11_RESET_REQUEST structure is **TRUE**. + +The following table lists the ExtAP OID name and the corresponding ExtAP MIB object name. For more information about an ExtAP MIB object, refer to the topic for the specific ExtAP OID. + +| ExtAP OID name | Extensible AP MIB object name | +|--- |--- | +| [OID_DOT11_ADDITIONAL_IE](https://msdn.microsoft.com/library/windows/hardware/ff569103) | msDot11AdditionalIEs | +| [OID_DOT11_AVAILABLE_CHANNEL_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569107) | msDot11AvailableChannelList | +| [OID_DOT11_AVAILABLE_FREQUENCY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569108) | msDot11AvailableFrequencyList | +| [OID_DOT11_WPS_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569436) | msDot11WpsEnabled | + +Unless an ExtAP MIB object defines a specific default value, the Native 802.11 miniport driver defines its own default value for the MIB object. + +>[!NOTE] +> When the miniport driver receives an [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) method request the miniport driver must reset an ExtAP MIB object to its default value under the following conditions: + - When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to **TRUE**. + - When MAC or PHY values are affected by the value of the **dot11ResetType** member. +> For more information, refer to the topic for the specific ExtAP OID. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-extensible-ap-oids.md b/windows-driver-docs-pr/network/native-802-11-extensible-ap-oids.md new file mode 100644 index 0000000000..5f91d61658 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-extensible-ap-oids.md @@ -0,0 +1,83 @@ +--- +title: Native 802.11 Extensible AP OIDs +description: This section describes Native 802.11 Extensible AP OIDs and their characteristics. +keywords: ["Native 802.11 Extensible AP OIDs", "Native 802.11 WLAN Extensible AP OIDs", "WDK Native 802.11 Extensible AP OIDs", "Native 802.11 Extensible AP object identifiers"] +ms.assetid: 53952D98-8C1D-4F73-A2C4-EE5D50FE93A0 +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Extensible AP OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 Extensible AP (access point) object identifiers (OIDs) are applicable only to miniport drivers that support the Native 802.11 Extensible AP operation mode. For more information about the ExtAP operation mode, see [Extensible Access Point Operation Mode](extensible-access-point-operation-mode.md). + +>[!NOTE] +> The Native 802.11 Extensible AP operation mode is available in Windows 7 and later versions of the Windows operating systems. + +In the following table, these abbreviations are used to specify the requirements for Native 802.11 Extensible AP (ExtAP) OID query (Q), and set (S), and NDIS 6.0 method (M) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning the status code NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- C +Indicates that support for the object is conditionally required for certain hardware or software functionality. If the 802.11 station supports the functionality, the miniport driver must support query or set requests for the object. Otherwise, the miniport driver must fail the set or query requests by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- O +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- X +Indicates that the specified state of a Native 802.11 operating mode supports a set request for the object. If the miniport driver is not in the specified state, the miniport driver must fail the set request by returning NDIS_STATUS_INVALID_STATE from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +OIDs that support query requests can be queried from any state of the miniport driver's operation mode. + +For more information about Native 802.11 operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). For more information about Native 802.11 operating states, see [Native 802.11 Operating States](native-802-11-operating-states.md). + +| Name of ExtAP OID | Q | S | ExtAP INIT | ExtAP OP | +|--- |---|---|--- |--- | +| [OID_DOT11_ADDITIONAL_IE](https://msdn.microsoft.com/library/windows/hardware/ff569103) | R | R | X | X | +| [OID_DOT11_AVAILABLE_CHANNEL_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569107) | C | | | | +| [OID_DOT11_AVAILABLE_FREQUENCY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569108) | C | | | | +| [OID_DOT11_DISASSOCIATE_PEER_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569146) | | R | | X | +| [OID_DOT11_ENUM_PEER_INFO](https://msdn.microsoft.com/library/windows/hardware/ff569361) | R | | | | +| [OID_DOT11_INCOMING_ASSOCIATION_DECISION](https://msdn.microsoft.com/library/windows/hardware/ff569379) | | R | | X | +| [OID_DOT11_START_AP_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569418) | | R | X | X | +| [OID_DOT11_WPS_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569436) | R | R | X | X | + +An 802.11 station running in the Native 802.11 Extensible AP operation mode must also support the OIDs in the following table. + +| Name of OID supported by ExtAP station | Q | S | M | ExtAP INIT | ExtAP OP | +|--- |---|---|---|--- |--- | +| [OID_DOT11_AUTO_CONFIG_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569106) | R | R | | X | | +| [OID_DOT11_BEACON_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569109) | R | R | | X | | +| [OID_DOT11_CIPHER_DEFAULT_KEY](https://msdn.microsoft.com/library/windows/hardware/ff569119) | | C | | X | X | +| [OID_DOT11_CIPHER_DEFAULT_KEY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569120) | C | C | | X | X | +| [OID_DOT11_CIPHER_KEY_MAPPING_KEY](https://msdn.microsoft.com/library/windows/hardware/ff569121) | | C | | X | X | +| [OID_DOT11_CURRENT_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) | C | C | | X | X | +| [OID_DOT11_CURRENT_FREQUENCY](https://msdn.microsoft.com/library/windows/hardware/ff569130) | C | C | | X | X | +| [OID_DOT11_CURRENT_OPERATION_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569132) | R | R | | X | | +| [OID_DOT11_CURRENT_PHY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569135) | R | R | | X | X | +| [OID_DOT11_DESIRED_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569144) | R | R | | X | | +| [OID_DOT11_DESIRED_SSID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569145) | R | R | | X | | +| [OID_DOT11_DTIM_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569152) | R | O | | | | +| [OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569356) | R | R | | X | | +| [OID_DOT11_ENABLED_MULTICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569357)| C | C | | X | | +| [OID_DOT11_ENABLED_UNICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569358) | C | C | | X | | +| [OID_DOT11_ENUM_BSS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569360) | | | R | | | +| [OID_DOT11_EXCLUDE_UNENCRYPTED](https://msdn.microsoft.com/library/windows/hardware/ff569365) | C | C | | X | | +| [OID_DOT11_FLUSH_BSS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569367) | | R | | X | X | +| [OID_DOT11_FRAGMENTATION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569368) | R | R | | X | X | +| [OID_DOT11_LONG_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569380) | R | R | | X | X | +| [OID_DOT11_NIC_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569392) | R | R | | X | | +| [OID_DOT11_OPERATIONAL_RATE_SET](https://msdn.microsoft.com/library/windows/hardware/ff569395) | R | R | | X | | +| [OID_DOT11_PORT_STATE_NOTIFICATION](https://msdn.microsoft.com/library/windows/hardware/ff569401) | | O | | X | X | +| [OID_DOT11_PRIVACY_EXEMPTION_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569404) | C | C | | X | | +| [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) | | | R | X | X | +| [OID_DOT11_RTS_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569411) | R | R | | X | X | +| [OID_DOT11_SCAN_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569413) | | R | | X | X | +| [OID_DOT11_SHORT_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569415) | R | R | | X | X | +| [OID_DOT11_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/ff569420) | R | | | | | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-extensible-station-mib-objects.md b/windows-driver-docs-pr/network/native-802-11-extensible-station-mib-objects.md new file mode 100644 index 0000000000..b0b573c85a --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-extensible-station-mib-objects.md @@ -0,0 +1,58 @@ +--- +title: Native 802.11 Extensible Station MIB objects +description: This section describes Native 802.11 Extensible Station MIB objects +keywords: ["Native 802.11 Extensible Station MIB objects", "Native 802.11 WLAN Extensible Station MIB objects", "WDK Native 802.11 Extensible Station MIB objects"] +ms.assetid: CAEB8DD4-9A81-4CF6-9C7D-6AD31CB466DE +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Extensible Station MIB objects + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +Some of the Extensible Station (ExtSTA) object identifiers (OIDs) are used to reference Extensible Station management information base (MIB) objects. + +ExtSTA objects are attributes of the IEEE 802.11 media access control (MAC) layer. The miniport driver must set these MIB objects to their default values whenever any of the following occur: + +- The miniport driver's [MiniportInitializeEx](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. +- A method request of [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11_RESET_REQUEST structure is **TRUE**. + +The following table lists the ExtSTA OID name and the corresponding ExtSTA MIB object name. For more information about an ExtSTA MIB object, refer to the topic for the specific ExtSTA OID. + +| ExtSTA OID name | Extensible Station MIB object name | +|--- |--- | +| [OID_DOT11_ACTIVE_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569102) | msDot11ActivePhyList | +| [OID_DOT11_AUTO_CONFIG_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569106) | msDot11AutoConfigEnabled | +| [OID_DOT11_CURRENT_PHY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569135) | msDot11msDot11CurrentPhyID | +| [OID_DOT11_DESIRED_BSSID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569141) | msDot11DesiredBSSIDList | +| [OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING](https://msdn.microsoft.com/library/windows/hardware/ff569143) | msDot11DesiredCountryOrRegionString | +| [OID_DOT11_DESIRED_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569144) | msDot11DesiredPhyList | +| [OID_DOT11_DESIRED_SSID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569145) | msDot11DesiredSSIDList | +| [OID_DOT11_HIDDEN_NETWORK_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569371) | msDot11HiddenNetworkEnabled | +| [OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569356) | msDot11EnabledAuthAlgo | +| [OID_DOT11_ENABLED_MULTICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569357)| msDot11EnabledMulticastCipherAlgo | +| [OID_DOT11_ENABLED_UNICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569358) | msDot11EnabledUnicastCipherAlgo | +| [OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569364) | msDot11ExcludedMacAddressList | +| [OID_DOT11_HARDWARE_PHY_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569370) | msDot11HardwarePHYState | +| [OID_DOT11_MEDIA_STREAMING_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569386) | msDot11MediaStreamingEnabled | +| [OID_DOT11_POWER_MGMT_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569402) | msDot11PowerSavingLevel | +| [OID_DOT11_PRIVACY_EXEMPTION_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569404) | msDot11PrivacyExemptionList | +| [OID_DOT11_QOS_PARAMS](https://msdn.microsoft.com/library/windows/hardware/ff569405) | msDot11QoSParams | +| [OID_DOT11_SAFE_MODE_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569412) | msDot11SafeModeEnabled | +| [OID_DOT11_UNICAST_USE_GROUP_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569433) | msDot11UnicastUseGroupEnabled | +| [OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569434) | msDot11UnreachableDetectionThreshold | + +Unless an ExtSTA MIB object defines a specific default value, the Native 802.11 miniport driver defines its own default value for the MIB object. + +>[!NOTE] +> When the miniport driver receives an [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) method request, the miniport driver must reset an ExtSTA MIB object to its default value under the following conditions: + - When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to **TRUE**. + - When MAC or PHY values are affected by the value of the **dot11ResetType** member. +> For more information, refer to the topic for the specific ExtSTA OID. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-extensible-station-oids.md b/windows-driver-docs-pr/network/native-802-11-extensible-station-oids.md new file mode 100644 index 0000000000..7d2053d7e7 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-extensible-station-oids.md @@ -0,0 +1,85 @@ +--- +title: Native 802.11 Extensible Station OIDs +description: This section describes Native 802.11 Extensible Station OIDs and their characteristics. +keywords: ["Native 802.11 Extensible Station OIDs", "Native 802.11 WLAN Extensible Station OIDs", "WDK Native 802.11 Extensible Station OIDs", "Native 802.11 Extensible Station object identifiers"] +ms.assetid: 34851A43-112C-40B7-BFB6-42E559BD3956 +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Extensible Station OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 Extensible Station (ExtSTA) object identifiers (OIDs) are applicable to miniport drivers that support the Native 802.11 ExtSTA operation mode. For more information about the ExtSTA operation mode, see [Extensible Station Operation Mode](extensible-station-operation-mode.md). + +In the following table, these abbreviations are used to specify the requirements for Native 802.11 ExtSTA OID query (Q), set (S), and NDIS 6.0 method (M) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- C +Indicates that support for the object is conditionally required for certain hardware or software functionality. If the 802.11 station supports the functionality, the miniport driver must support query or set requests for the object. Otherwise, the miniport driver must fail the set or query requests by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- O +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- X +Indicates that the specified state of a Native 802.11 operating mode supports a set request for the object. If the miniport driver is not in the specified state, the miniport driver must fail the set request by returning NDIS_STATUS_INVALID_STATE from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +OIDs that support query requests can be queried from any state of the miniport driver's operation mode. + +For more information about Native 802.11 operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). For more information about Native 802.11 operating states, see [Native 802.11 Operating States](native-802-11-operating-states.md). + +| Name | Q | S | M | ExtSTA INIT| ExtSTA OP| +|--- |---|---|---|--- |--- | +| [OID_DOT11_ACTIVE_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569102) | R | | | | | +| [OID_DOT11_ASSOCIATION_PARAMS](https://msdn.microsoft.com/library/windows/hardware/ff569104) | | R | | X | | +| [OID_DOT11_AUTO_CONFIG_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569106) | R | R | | X | | +| [OID_DOT11_CIPHER_DEFAULT_KEY](https://msdn.microsoft.com/library/windows/hardware/ff569119) | | C | | X | X | +| [OID_DOT11_CIPHER_DEFAULT_KEY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569120) | C | C | | X | X | +| [OID_DOT11_CIPHER_KEY_MAPPING_KEY](https://msdn.microsoft.com/library/windows/hardware/ff569121) | | R | | X | X | +| [OID_DOT11_CONNECT_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569122) | | R | | X | | +| [OID_DOT11_CURRENT_PHY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569135) | R | R | | X | X | +| [OID_DOT11_DESIRED_BSS_TYPE](https://msdn.microsoft.com/library/windows/hardware/ff569142) | R | R | | X | | +| [OID_DOT11_DESIRED_BSSID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569141) | R | R | | X | | +| [OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING](https://msdn.microsoft.com/library/windows/hardware/ff569143) | C | C | | X | | +| [OID_DOT11_DESIRED_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569144) | R | R | | X | | +| [OID_DOT11_DESIRED_SSID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569145) | R | R | | X | | +| [OID_DOT11_DISCONNECT_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569147) | | R | | | X | +| [OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569356) | R | R | | X | | +| [OID_DOT11_ENABLED_MULTICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569357)| C | C | | X | | +| [OID_DOT11_ENABLED_UNICAST_CARRIER_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/ff569358) | C | C | | X | | +| [OID_DOT11_ENUM_ASSOCIATION_INFO](https://msdn.microsoft.com/library/windows/hardware/ff569359) | R | | | | | +| [OID_DOT11_ENUM_BSS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569360) | | | R | | | +| [OID_DOT11_EXCLUDE_UNENCRYPTED](https://msdn.microsoft.com/library/windows/hardware/ff569365) | C | C | | X | | +| [OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569364) | R | R | | X | X | +| [OID_DOT11_EXTSTA_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569366) | O | | | | | +| [OID_DOT11_FLUSH_BSS_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569367) | | R | | X | | +| [OID_DOT11_HARDWARE_PHY_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569370) | O | | | | | +| [OID_DOT11_HIDDEN_NETWORK_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569371) | R | R | | X | | +| [OID_DOT11_IBSS_PARAMS](https://msdn.microsoft.com/library/windows/hardware/ff569378) | R | R | | X | | +| [OID_DOT11_MEDIA_STREAMING_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569386) | R | R | | X | X | +| [OID_DOT11_PMKID_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569400) | C | C | | X | X | +| [OID_DOT11_PORT_STATE_NOTIFICATION](https://msdn.microsoft.com/library/windows/hardware/ff569401) | | O | | | X | +| [OID_DOT11_POWER_MGMT_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569402) | R | R | | X | X | +| [OID_DOT11_PRIVACY_EXEMPTION_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569404) | C | C | | X | | +| [OID_DOT11_QOS_PARAMS](https://msdn.microsoft.com/library/windows/hardware/ff569405) | C | C | | X | | +| [OID_DOT11_SAFE_MODE_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569412) | R | R | | X | | +| [OID_DOT11_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/ff569420) | R | | | | | +| [OID_DOT11_SUPPORTED_COUNTRY_OR_REGION_STRING](https://msdn.microsoft.com/library/windows/hardware/ff569421) | O | | | | | +| [OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR](https://msdn.microsoft.com/library/windows/hardware/ff569424) | O | | | | | +| [OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR](https://msdn.microsoft.com/library/windows/hardware/ff569430) | O | | | | | +| [OID_DOT11_UNICAST_USE_GROUP_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569433) | C | C | | X | | +| [OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569434) | R | R | | X | X | + +Some of the ExtSTA OIDs are used to reference IEEE 802.11 management information base (MIB) objects. The following table lists the ExtSTA OID name, the corresponding IEEE 802.11 MIB object name, and the IEEE 802.11 standard that defines the MIB object. For more information about an MIB object, refer to Annex D of the specified IEEE 802.11 Standard. + +| ExtSTA OID name | IEEE 802.11 MIB object name | IEEE 802.11 standard | +|--- |--- |--- | +| [OID_DOT11_CIPHER_DEFAULT_KEY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569120) | dot11DefaultKeyID | IEEE 802.11-2012 | +| [OID_DOT11_DESIRED_BSS_TYPE](https://msdn.microsoft.com/library/windows/hardware/ff569142) | dot11DesiredBSSType | IEEE 802.11-2012 | +| [OID_DOT11_EXCLUDE_UNENCRYPTED](https://msdn.microsoft.com/library/windows/hardware/ff569365) | dot11ExcludeUnencrypted | IEEE 802.11-2012 | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-ieee-mib-objects.md b/windows-driver-docs-pr/network/native-802-11-ieee-mib-objects.md new file mode 100644 index 0000000000..dae6837f42 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-ieee-mib-objects.md @@ -0,0 +1,94 @@ +--- +title: Native 802.11 Operational MIB objects +description: This section describes Native 802.11 Operational MIB objects +keywords: ["Native 802.11 Operational MIB objects", "Native 802.11 WLAN Operational MIB objects", "WDK Native 802.11 Operational MIB objects"] +ms.assetid: 3D86500A-4D20-47D7-AD00-D0267B3CEB62 +ms.author: windowsdriverdev +ms.date: 04/26/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Operational MIB objects + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +Native 802.11 MIB OIDs are used to reference IEEE 802.11 management information base (MIB) objects. + +The following table lists the Native 802.11 IEEE OID name, the corresponding IEEE 802.11 MIB object name, and the IEEE 802.11 standard that defines the MIB object. For more information about a MIB object, refer to Annex D of the specified IEEE 802.11 standard. + +| Native 802.11 IEEE OID name | IEEE 802.11 MIB object name | IEEE 802.11 standard | +|--- |--- |--- | +| [OID_DOT11_BEACON_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569109) | dot11BeaconPeriod | IEEE 802.11-2012 | +| [OID_DOT11_CCA_MODE_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569110) | dot11CCAModeSupported | IEEE 802.11b-1999 | +| [OID_DOT11_CCA_WATCHDOG_COUNT_MAX](https://msdn.microsoft.com/library/windows/hardware/ff569112) | dot11CCAWatchdogCountMax | IEEE 802.11-2012 | +| [OID_DOT11_CCA_WATCHDOG_COUNT_MIN](https://msdn.microsoft.com/library/windows/hardware/ff569113) | dot11CCAWatchdogCountMin | IEEE 802.11-2012 | +| [OID_DOT11_CCA_WATCHDOG_TIMER_MAX](https://msdn.microsoft.com/library/windows/hardware/ff569114) | dot11CCAWatchdogTimerMax | IEEE 802.11-2012 | +| [OID_DOT11_CCA_WATCHDOG_TIMER_MIN](https://msdn.microsoft.com/library/windows/hardware/ff569115) | dot11CCAWatchdogTimerMin | IEEE 802.11-2012 | +| [OID_DOT11_CF_POLLABLE](https://msdn.microsoft.com/library/windows/hardware/ff569116) | dot11CFPollable | IEEE 802.11-2012 | +| [OID_DOT11_CHANNEL_AGILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569117) | dot11ChannelAgilityEnabled | IEEE 802.11-1999/Corrigendum 1-2001 | +| [OID_DOT11_CHANNEL_AGILITY_PRESENT](https://msdn.microsoft.com/library/windows/hardware/ff569118) | dot11ChannelAgilityPresent | IEEE 802.11-1999/Corrigendum 1-2001 | +| [OID_DOT11_COUNTRY_STRING](https://msdn.microsoft.com/library/windows/hardware/ff569123) | dot11CountryString | IEEE 802.11d-2001 | +| [OID_DOT11_CURRENT_CCA_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569126) | dot11CurrentCCAMode | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) | dot11CurrentChannel | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_CHANNEL_NUMBER](https://msdn.microsoft.com/library/windows/hardware/ff569128) | dot11CurrentChannelNumber | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_DWELL_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569129) | dot11CurrentDwellTime | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_FREQUENCY](https://msdn.microsoft.com/library/windows/hardware/ff569130) | dot11CurrentFrequency | IEEE 802.11a-1999 | +| [OID_DOT11_CURRENT_INDEX](https://msdn.microsoft.com/library/windows/hardware/ff569131) | dot11CurrentIndex | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_PATTERN](https://msdn.microsoft.com/library/windows/hardware/ff569134) | dot11CurrentPattern | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_REG_DOMAIN](https://msdn.microsoft.com/library/windows/hardware/ff569136) | dot11CurrentRegDomain | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_SET](https://msdn.microsoft.com/library/windows/hardware/ff569137) | dot11CurrentSet | IEEE 802.11-2012 | +| [OID_DOT11_CURRENT_TX_POWER_LEVEL](https://msdn.microsoft.com/library/windows/hardware/ff569138) | dot11CurrentTxPowerLevel | IEEE 802.11-2012 | +| [OID_DOT11_DIVERSITY_SELECTION_RX](https://msdn.microsoft.com/library/windows/hardware/ff569148) | dot11DiversitySelectionRx | IEEE 802.11-2012 | +| [OID_DOT11_DIVERSITY_SUPPORT](https://msdn.microsoft.com/library/windows/hardware/ff569149) | dot11DiversitySupport | IEEE 802.11-2012 | +| [OID_DOT11_DSS_OFDM_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569150) | dot11DSSSOFDMOptionEnabled | IEEE 802.11g-2003 | +| [OID_DOT11_DSS_OFDM_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569151) | dot11DSSSOFDMOptionImplemented | IEEE 802.11g-2003 | +| [OID_DOT11_DTIM_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569152) | dot11DTIMPeriod | IEEE 802.11-2012 | +| [OID_DOT11_ED_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569153) | dot11EDThreshold | IEEE 802.11-2012 | +| [OID_DOT11_EHCC_CAPABILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569154) | dot11EHCCCapabilityEnabled | IEEE 802.11d-2001 | +| [OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569155) | dot11EHCCCapabilityImplemented | IEEE 802.11d-2001 | +| [OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX](https://msdn.microsoft.com/library/windows/hardware/ff569156) | dot11EHCCNumberOfChannelsFamilyIndex | IEEE 802.11d-2001 | +| [OID_DOT11_EHCC_PRIME_RADIX](https://msdn.microsoft.com/library/windows/hardware/ff569355) | dot11EHCCPrimeRadix | IEEE 802.11d-2001 | +| [OID_DOT11_ERP_PBCC_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569362) | dot11ERPPBCCOptionEnabled | IEEE 802.11g-2003 | +| [OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569363) | dot11ERPPBCCOptionImplemented | IEEE 802.11g-2003 | +| [OID_DOT11_FRAGMENTATION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569368) | dot11FragmentationThreshold | IEEE 802.11-2012 | +| [OID_DOT11_FREQUENCY_BANDS_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569369) | dot11FrequencyBandsSupported | IEEE 802.11a-1999 | +| [OID_DOT11_HOP_ALGORITHM_ADOPTED](https://msdn.microsoft.com/library/windows/hardware/ff569373) | dot11HopAlgorithmAdopted | IEEE 802.11d-2001 | +| [OID_DOT11_HOP_MODULUS](https://msdn.microsoft.com/library/windows/hardware/ff569374) | dot11HopModulus | IEEE 802.11d-2001 | +| [OID_DOT11_HOP_OFFSET](https://msdn.microsoft.com/library/windows/hardware/ff569375) | dot11HopOffset | IEEE 802.11d-2001 | +| [OID_DOT11_HOP_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569376) | dot11HopTime | IEEE 802.11-2012 | +| [OID_DOT11_HOPPING_PATTERN](https://msdn.microsoft.com/library/windows/hardware/ff569372) | dot11HoppingPatternEntry | IEEE 802.11d-2001 | +| [OID_DOT11_HR_CCA_MODE_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569377) | dot11HRCCAModeSupported | IEEE 802.11-2012/Corrigendum 1-2001 | +| [OID_DOT11_LONG_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569380) | dot11LongRetryLimit | IEEE 802.11-2012 | +| [OID_DOT11_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/ff569381) | dot11MACAddress | IEEE 802.11-2012 | +| [OID_DOT11_MAX_DWELL_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569383) | dot11MaxDwellTime | IEEE 802.11-2012 | +| [OID_DOT11_MAX_RECEIVE_LIFETIME](https://msdn.microsoft.com/library/windows/hardware/ff569384) | dot11MaxReceiveLifetime | IEEE 802.11-2012 | +| [OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME](https://msdn.microsoft.com/library/windows/hardware/ff569385) | dot11MaxTransmitMSDULifetime | IEEE 802.11-2012 | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569389) | dot11MultiDomainCapabilityEntry | IEEE 802.11d-2001 | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569390) | dot11MultiDomainCapabilityEnabled | IEEE 802.11d-2001 | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569391) | dot11MultiDomainCapabilityImplemented | IEEE 802.11d-2001 | +| [OID_DOT11_NUMBER_OF_HOPPING_SETS](https://msdn.microsoft.com/library/windows/hardware/ff569394) | dot11NumberOfHoppingSets | IEEE 802.11d-2001 | +| [OID_DOT11_OPERATIONAL_RATE_SET](https://msdn.microsoft.com/library/windows/hardware/ff569395) | dot11OperationalRateSet | IEEE 802.11-2012 | +| [OID_DOT11_PBCC_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569398) | dot11PBCCOptionImplemented | IEEE 802.11b-1999 | +| [OID_DOT11_RANDOM_TABLE_FLAG](https://msdn.microsoft.com/library/windows/hardware/ff569406) | dot11RandomTableFlag | IEEE 802.11d-2001 | +| [OID_DOT11_REG_DOMAINS_SUPPORT_VALUE](https://msdn.microsoft.com/library/windows/hardware/ff569408) | dot11RegDomainsSupportEntry | IEEE 802.11-2012 | +| [OID_DOT11_RTS_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569411) | dot11RTSThreshold | IEEE 802.11-2012 | +| [OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569414) | dot11ShortPreambleOptionImplemented | IEEE 802.11b-1999 | +| [OID_DOT11_SHORT_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569415) | dot11ShortRetryLimit | IEEE 802.11-2012 | +| [OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569416) | dot11ShortSlotTimeOptionEnabled | IEEE 802.11g-2003 | +| [OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569417) | dot11ShortSlotTimeOptionImplemented | IEEE 802.11g-2003 | +| [OID_DOT11_STATION_ID](https://msdn.microsoft.com/library/windows/hardware/ff569419) | dot11StationID | IEEE 802.11-2012 | +| [OID_DOT11_TEMP_TYPE](https://msdn.microsoft.com/library/windows/hardware/ff569431) | dot11TempType | IEEE 802.11-2012 | +| [OID_DOT11_TI_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569432) | dot11TIThreshold | IEEE 802.11a-1999 | + +If the IEEE 802.11 standard that defines the IEEE 802.11 MIB object also defines a default value for the MIB object, the Native 802.11 miniport driver must use the specified default value. Otherwise, the Native 802.11 miniport driver defines its own default value for the MIB object. + +>[!NOTE] +> When the miniport driver receives an [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) method request, the miniport driver must reset an IEEE MIB object to its default value under the following conditions: + - When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to **TRUE**. + - When MAC or PHY values are affected by the value of the **dot11ResetType** member. +> For more information, refer to the topic for the specific Native 802.11 MIB OID. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-ihv-extensibility-functions.md b/windows-driver-docs-pr/network/native-802-11-ihv-extensibility-functions.md new file mode 100644 index 0000000000..379529ee75 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-ihv-extensibility-functions.md @@ -0,0 +1,79 @@ +--- +title: Native 802.11 IHV Extensibility functions +description: This section describes Native 802.11 IHV Extensibility functions for the Native 802.11 IHV Extensions DLL +keywords: ["Native 802.11 IVH Extensibility functions", "Native 802.11 IHV Extensions DLL Extensibility Functions", "WDK Native 802.11 IVH Extensibility functions"] +ms.assetid: 0E7CC153-5434-459D-9773-8CCAFBACD016 +ms.author: windowsdriverdev +ms.date: 04/27/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 IHV Extensibility functions + +> [!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 IHV Extensibility functions are provided by the operating system and are called by the IHV Extensions DLL to do the following: + +- Allocate and free buffers that are used within the Native 802.11 framework. +- Send packets, such as a packet defined by an authentication algorithm, through the IHV's wireless LAN (WLAN) adapter. +- Configure the IHV's WLAN adapter with various security settings for any authentication and cipher algorithms supported by the IHV Extensions DLL. +- Interface with the IHV UI Extensions DLL (if installed) to process event notifications. For example, the IHV Extensions DLL could notify the IHV UI Extensions DLL about the various stages involved in a basic service set (BSS) network connection. + +For more information about the IHV UI Extensions DLL, see [Native 802.11 IHV UI Extensions DLL](native-802-11-ihv-ui-extensions-dll2.md). + +> [!NOTE] +> The IHV Extensions DLL calls each Native 802.11 IHV Extensibility function through a function pointer associated with a member of the [DOT11EXT_APIS](https://msdn.microsoft.com/library/windows/hardware/ff547617) structure. When the operating system calls the [Dot11ExtIhvInitService](https://msdn.microsoft.com/library/windows/hardware/ff547470) IHV Handler function, it passes the list of pointers to the IHV Extensibility functions through the *pDot11ExtAPI* parameter. + +The following table lists the Native 802.11 IHV Extensibility Functions that can be called by the IHV Extensions DLL. Each IHV Extensibility function can only be called under these conditions. + + +- **Called After Service Initialization** +The IHV Extensibility function can only be called after the [Dot11ExtIhvInitService](https://msdn.microsoft.com/library/windows/hardware/ff547470) IHV Handler function has been called to initialize the IHV Extensions DLL. Also, the Extensions DLL cannot call the IHV Extensibility function after the [Dot11ExtIhvDeinitService](https://msdn.microsoft.com/library/windows/hardware/ff547457) IHV Handler function has been called. +- **Called after Adapter Initialization** +The IHV Extensibility function can only be called after the [Dot11ExtIhvInitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547469) IHV Handler function has been called to initialize the interface to the IHV's WLAN adapter. +The IHV Extensibility function requires a handle, which identifies the WLAN adapter. When *Dot11ExtIhvInitAdapter* is called, the IHV Extensions DLL is passed this handle through the *hDot11SvcHandle* parameter. +The Extensions DLL cannot call the IHV Extensibility function after the [Dot11ExtIhvDeinitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547452) IHV Handler function has been called. +- **Called after Pre-Association** +The IHV Extensibility function can only be called after the [Dot11ExtIhvPerformPreAssociate](https://msdn.microsoft.com/library/windows/hardware/ff547499) IHV Handler function has been called to initiate a pre-association operation with a basic service set (BSS) network. +The IHV Extensibility function requires a handle, which identifies the BSS network connection. When *Dot11ExtIhvPerformPreAssociate* is called, the IHV Extensions DLL is passed this handle through the *hConnection* parameter. +The Extensions DLL cannot call the IHV Extensibility function after the [Dot11ExtIhvDeinitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547452) or [Dot11ExtIhvAdapterReset](https://msdn.microsoft.com/library/windows/hardware/ff547434) IHV Handler functions have been called. +- **Called after Post-Association** +The IHV Extensibility function can only be called after the [Dot11ExtIhvPerformPostAssociate](https://msdn.microsoft.com/library/windows/hardware/ff547492) IHV Handler function has been called to initiate a post-association operation with a basic service set (BSS) network. +The IHV Extensibility function requires a handle, which identifies the security session with the BSS network connection. When *Dot11ExtIhvPerformPostAssociate* is called, the IHV Extensions DLL is passed this handle through the *hSecuritySessionID* parameter. +The Extensions DLL cannot call the IHV Extensibility function after the [Dot11ExtIhvDeinitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547452) or [Dot11ExtIhvAdapterReset](https://msdn.microsoft.com/library/windows/hardware/ff547434) IHV Handler functions have been called. + +| Function | Called after service initialization | Called after adapter initialization | Called after pre-association | Called after post-association | +| --- | --- | --- | --- | --- | +| [Dot11ExtAllocateBuffer](https://msdn.microsoft.com/library/windows/hardware/ff547419) | X | | | | +| [Dot11ExtFreeBuffer](https://msdn.microsoft.com/library/windows/hardware/ff547422) | X | | | | +| [Dot11ExtGetProfileCustomUserData](https://msdn.microsoft.com/library/windows/hardware/ff547430) | | | X | | +| [Dot11ExtNicSpecificExtension](https://msdn.microsoft.com/library/windows/hardware/ff547526) | | X | | | +| [Dot11ExtStartOneX](https://msdn.microsoft.com/library/windows/hardware/ff547610) | | | | X | +| [Dot11ExtStopOneX](https://msdn.microsoft.com/library/windows/hardware/ff547614) | | | | X | +| [Dot11ExtPostAssociateCompletion](https://msdn.microsoft.com/library/windows/hardware/ff547530) | | | | X | +| [Dot11ExtPreAssociateCompletion](https://msdn.microsoft.com/library/windows/hardware/ff547538) | | | X | | +| [Dot11ExtProcessOneXPacket](https://msdn.microsoft.com/library/windows/hardware/ff547541) | | | | X | +| [Dot11ExtQueryVirtualStationProperties](https://msdn.microsoft.com/library/windows/hardware/ff547544) | | X | | | +| [Dot11ExtReleaseVirtualStation](https://msdn.microsoft.com/library/windows/hardware/ff547549) | | X | | | +| [Dot11ExtRequestVirtualStation](https://msdn.microsoft.com/library/windows/hardware/ff547556) | | X | | | +| [Dot11ExtSendNotification](https://msdn.microsoft.com/library/windows/hardware/ff547560) | | X | | | +| [Dot11ExtSendUIRequest](https://msdn.microsoft.com/library/windows/hardware/ff547567) | | X | | | +| [Dot11ExtSetAuthAlgorithm](https://msdn.microsoft.com/library/windows/hardware/ff547571) | | X | | | +| [Dot11ExtSetCurrentProfile](https://msdn.microsoft.com/library/windows/hardware/ff547574) | | | X | | +| [Dot11ExtSetDefaultKey](https://msdn.microsoft.com/library/windows/hardware/ff547578) | | X | | | +| [Dot11ExtSetDefaultKeyId](https://msdn.microsoft.com/library/windows/hardware/ff547584)| | X | | | +| [Dot11ExtSetEtherTypeHandling](https://msdn.microsoft.com/library/windows/hardware/ff547587) | | X | | | +| [Dot11ExtSetExcludeUnencrypted](https://msdn.microsoft.com/library/windows/hardware/ff547589) | | X | | | +| [Dot11ExtSetKeyMappingKey](https://msdn.microsoft.com/library/windows/hardware/ff547597) | | X | | | +| [Dot11ExtSetMulticastCipherAlgorithm](https://msdn.microsoft.com/library/windows/hardware/ff547599) | | X | | | +| [Dot11ExtSetProfileCustomUserData](https://msdn.microsoft.com/library/windows/hardware/ff547603) | | X | | | +| [Dot11ExtSetUnicastCipherAlgorithm](https://msdn.microsoft.com/library/windows/hardware/ff547606) | | X | | | +| [Dot11ExtSetVirtualStationAPProperties](https://msdn.microsoft.com/library/windows/hardware/ff547609) | | | X | | + +For more information about IHV Handler functions, see [Native 802.11 IHV Handler Functions](native-802-11-ihv-handler-functions.md). + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-ihv-extensions-dll4.md b/windows-driver-docs-pr/network/native-802-11-ihv-extensions-dll4.md index 4baffe3f10..21a5c0c42f 100644 --- a/windows-driver-docs-pr/network/native-802-11-ihv-extensions-dll4.md +++ b/windows-driver-docs-pr/network/native-802-11-ihv-extensions-dll4.md @@ -24,6 +24,10 @@ This section discusses the IHV Extensions DLL and has the following topics: [Native 802.11 IHV Extensions DLL Overview](native-802-11-ihv-extensions-dll-overview.md) +[Native 802.11 IHV Extensibility functions](native-802-11-ihv-extensibility-functions.md) + +[Native 802.11 IHV Handler functions](native-802-11-ihv-handler-functions.md) + [Native 802.11 IHV Extensions DLL Implementation Guidelines](native-802-11-ihv-extensions-dll-implementation-guidelines.md) [DLL Start/Stop Operations](dll-start-stop-operations.md) diff --git a/windows-driver-docs-pr/network/native-802-11-ihv-handler-functions.md b/windows-driver-docs-pr/network/native-802-11-ihv-handler-functions.md new file mode 100644 index 0000000000..40a6be1b24 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-ihv-handler-functions.md @@ -0,0 +1,56 @@ +--- +title: Native 802.11 IHV Handler functions +description: This section describes Native 802.11 IHV Handler functions for the Native 802.11 IHV Extensions DLL +keywords: ["Native 802.11 IVH Handler functions", "Native 802.11 IHV Extensions DLL Handler Functions", "WDK Native 802.11 IVH Handler functions"] +ms.assetid: BF0DC1C7-48E1-487E-8F64-146BBA322F40 +ms.author: windowsdriverdev +ms.date: 04/27/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 IHV Handler functions + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 IHV Handler functions are provided by the IHV Extensions DLL and are called by the operating system to do the following: + +- Allocate and free buffers that are used within the Native 802.11 framework. +- Send packets, such as a packet defined by an authentication algorithm, through the IHV's wireless LAN (WLAN) adapter. +- Receive packets based on a specified list of IEEE EtherType values and privacy exemption rules. +- Configure the IHV's WLAN adapter with various security settings for any proprietary authentication and cipher algorithms. +- Interface with the IHV UI Extensions DLL (if installed) to process event notifications. For example, the IHV Extensions DLL could notify the UI Extensions DLL about the various stages involved in a basic service set (BSS) network connection. + +For more information about the IHV UI Extensions DLL, see [Native 802.11 IHV UI Extensions DLL](native-802-11-ihv-ui-extensions-dll2.md). + +> [!NOTE] +> With the exception of [Dot11ExtIhvGetVersionInfo](https://msdn.microsoft.com/library/windows/hardware/ff547464) and [Dot11ExtIhvInitService](https://msdn.microsoft.com/library/windows/hardware/ff547470), the operating system calls the IHV Handler functions through a function pointer associated with a member of the [DOT11EXT_IHV_HANDLERS](https://msdn.microsoft.com/library/windows/hardware/ff547625) structure. When the operating system calls the *Dot11ExtIhvInitService* IHV Handler function, the IHV Extensions DLL returns the list of pointers to the IHV Handler functions through the *pDot11IHVHandlers* parameter. + +This section describes the following Native 802.11 IHV Handler functions. + +- [Dot11ExtIhvAdapterReset](https://msdn.microsoft.com/library/windows/hardware/ff547434) +- [Dot11ExtIhvControl](https://msdn.microsoft.com/library/windows/hardware/ff547438) +- [Dot11ExtIhvCreateDiscoveryProfiles](https://msdn.microsoft.com/library/windows/hardware/ff547445) +- [Dot11ExtIhvDeinitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547452) +- [Dot11ExtIhvDeinitService](https://msdn.microsoft.com/library/windows/hardware/ff547457) +- [Dot11ExtIhvGetVersionInfo](https://msdn.microsoft.com/library/windows/hardware/ff547464) +- [Dot11ExtIhvInitAdapter](https://msdn.microsoft.com/library/windows/hardware/ff547469) +- [Dot11ExtIhvInitService](https://msdn.microsoft.com/library/windows/hardware/ff547470) +- [Dot11ExtIhvInitVirtualStation](https://msdn.microsoft.com/library/windows/hardware/ff547475) +- [Dot11ExtIhvIsUIRequestPending](https://msdn.microsoft.com/library/windows/hardware/ff547479) +- [Dot11ExtIhvOneXIndicateResult](https://msdn.microsoft.com/library/windows/hardware/ff547482) +- [Dot11ExtIhvPerformCapabilityMatch](https://msdn.microsoft.com/library/windows/hardware/ff547488) +- [Dot11ExtIhvPerformPostAssociate](https://msdn.microsoft.com/library/windows/hardware/ff547492) +- [Dot11ExtIhvPerformPreAssociate](https://msdn.microsoft.com/library/windows/hardware/ff547499) +- [Dot11ExtIhvProcessSessionChange](https://msdn.microsoft.com/library/windows/hardware/ff547501) +- [Dot11ExtIhvProcessUIResponse](https://msdn.microsoft.com/library/windows/hardware/ff547504) +- [Dot11ExtIhvQueryUIRequest](https://msdn.microsoft.com/library/windows/hardware/ff547507) +- [Dot11ExtIhvReceiveIndication](https://msdn.microsoft.com/library/windows/hardware/ff547512) +- [Dot11ExtIhvReceivePacket](https://msdn.microsoft.com/library/windows/hardware/ff547513) +- [Dot11ExtIhvSendPacketCompletion](https://msdn.microsoft.com/library/windows/hardware/ff547516) +- [Dot11ExtIhvStopPostAssociate](https://msdn.microsoft.com/library/windows/hardware/ff547521) +- [Dot11ExtIhvValidateProfile](https://msdn.microsoft.com/library/windows/hardware/ff547523) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-mib-oids.md b/windows-driver-docs-pr/network/native-802-11-mib-oids.md new file mode 100644 index 0000000000..eff88586ee --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-mib-oids.md @@ -0,0 +1,101 @@ +--- +title: Native 802.11 MIB OIDs +description: This section describes Native 802.11 MIB OIDs and their characteristics. +keywords: ["Native 802.11 MIB OIDs", "Native 802.11 WLAN MIB OIDs", "WDK Native 802.11 MIB OIDs", "Native 802.11 MIB object identifiers"] +ms.assetid: F1ADCBDB-5591-4CAF-9EDA-8B5FEDFE55B9 +ms.author: windowsdriverdev +ms.date: 04/26/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 MIB OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 management information base (MIB) object identifiers (OIDs) query and set the IEEE 802.11 MIB objects that are supported by the miniport driver. These objects are applicable to miniport drivers that support any of the Native 802.11 operation modes. For more information about the Native 802.11 operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). + +In the following table, these abbreviations are used to specify the requirements for Native 802.11 MIB OID query (Q) and set (S) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- C +Indicates that support for the object is conditionally required for certain hardware or software functionality. If the 802.11 station supports the functionality, the miniport driver must support query or set requests for the object. Otherwise, the miniport driver must fail the set or query requests by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- O +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- X +Indicates that the specified state of a Native 802.11 operating mode supports a set request for the object. If the miniport driver is not in the specified state, the miniport driver must fail the set request by returning NDIS_STATUS_INVALID_STATE from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +OIDs that support query requests can be queried from any state of the miniport driver's operation mode. + +For more information about Native 802.11 operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). For more information about Native 802.11 operating states, see [Native 802.11 Operating States](native-802-11-operating-states.md). + +| Name | Q | S | ExtSTA INIT | ExtSTA OP | +|--- |---|---|--- |--- | +| [OID_DOT11_BEACON_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569109) | R | O | X | | +| [OID_DOT11_CCA_MODE_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569110) | O | | | | +| [OID_DOT11_CCA_WATCHDOG_COUNT_MAX](https://msdn.microsoft.com/library/windows/hardware/ff569112) | O | | | | +| [OID_DOT11_CCA_WATCHDOG_COUNT_MIN](https://msdn.microsoft.com/library/windows/hardware/ff569113) | O | | | | +| [OID_DOT11_CCA_WATCHDOG_TIMER_MAX](https://msdn.microsoft.com/library/windows/hardware/ff569114) | O | | | | +| [OID_DOT11_CCA_WATCHDOG_TIMER_MIN](https://msdn.microsoft.com/library/windows/hardware/ff569115) | O | | | | +| [OID_DOT11_CF_POLLABLE](https://msdn.microsoft.com/library/windows/hardware/ff569116) | O | | | | +| [OID_DOT11_CHANNEL_AGILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569117) | O | | | | +| [OID_DOT11_CHANNEL_AGILITY_PRESENT](https://msdn.microsoft.com/library/windows/hardware/ff569118) | O | | | | +| [OID_DOT11_COUNTRY_STRING](https://msdn.microsoft.com/library/windows/hardware/ff569123) | C | | X | | +| [OID_DOT11_CURRENT_CCA_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569126) | O | | | | +| [OID_DOT11_CURRENT_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) | C | C | X | | +| [OID_DOT11_CURRENT_CHANNEL_NUMBER](https://msdn.microsoft.com/library/windows/hardware/ff569128) | O | | | | +| [OID_DOT11_CURRENT_DWELL_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569129) | O | | | | +| [OID_DOT11_CURRENT_FREQUENCY](https://msdn.microsoft.com/library/windows/hardware/ff569130) | C | C | X | | +| [OID_DOT11_CURRENT_INDEX](https://msdn.microsoft.com/library/windows/hardware/ff569131) | O | | | | +| [OID_DOT11_CURRENT_PATTERN](https://msdn.microsoft.com/library/windows/hardware/ff569134) | O | | | | +| [OID_DOT11_CURRENT_REG_DOMAIN](https://msdn.microsoft.com/library/windows/hardware/ff569136) | R | | | | +| [OID_DOT11_CURRENT_SET](https://msdn.microsoft.com/library/windows/hardware/ff569137) | O | | | | +| [OID_DOT11_CURRENT_TX_POWER_LEVEL](https://msdn.microsoft.com/library/windows/hardware/ff569138) | O | | | | +| [OID_DOT11_DIVERSITY_SELECTION_RX](https://msdn.microsoft.com/library/windows/hardware/ff569148) | O | | | | +| [OID_DOT11_DIVERSITY_SUPPORT](https://msdn.microsoft.com/library/windows/hardware/ff569149) | O | | | | +| [OID_DOT11_DSS_OFDM_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569150) | O | | | | +| [OID_DOT11_DSS_OFDM_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569151) | O | | | | +| [OID_DOT11_DTIM_PERIOD](https://msdn.microsoft.com/library/windows/hardware/ff569152) | R | O | | | +| [OID_DOT11_ED_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569153) | O | | | | +| [OID_DOT11_EHCC_CAPABILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569154) | O | | | | +| [OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569155) | O | | | | +| [OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX](https://msdn.microsoft.com/library/windows/hardware/ff569156) | O | | | | +| [OID_DOT11_EHCC_PRIME_RADIX](https://msdn.microsoft.com/library/windows/hardware/ff569355) | O | | | | +| [OID_DOT11_ERP_PBCC_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569362) | O | | | | +| [OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569363) | O | | | | +| [OID_DOT11_FRAGMENTATION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569368) | R | R | X | | +| [OID_DOT11_FREQUENCY_BANDS_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569369) | O | | | | +| [OID_DOT11_HOP_ALGORITHM_ADOPTED](https://msdn.microsoft.com/library/windows/hardware/ff569373) | O | | | | +| [OID_DOT11_HOP_MODULUS](https://msdn.microsoft.com/library/windows/hardware/ff569374) | O | | | | +| [OID_DOT11_HOP_OFFSET](https://msdn.microsoft.com/library/windows/hardware/ff569375) | O | | | | +| [OID_DOT11_HOP_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569376) | O | | | | +| [OID_DOT11_HOPPING_PATTERN](https://msdn.microsoft.com/library/windows/hardware/ff569372) | O | | | | +| [OID_DOT11_HR_CCA_MODE_SUPPORTED](https://msdn.microsoft.com/library/windows/hardware/ff569377) | O | | | | +| [OID_DOT11_LONG_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569380) | O | | | | +| [OID_DOT11_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/ff569381) | O | | | | +| [OID_DOT11_MAX_DWELL_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569383) | O | | | | +| [OID_DOT11_MAX_RECEIVE_LIFETIME](https://msdn.microsoft.com/library/windows/hardware/ff569384) | O | | | | +| [OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME](https://msdn.microsoft.com/library/windows/hardware/ff569385) | O | | | | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569389) | O | | | | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569390) | C | C | X | | +| [OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569391) | O | | | | +| [OID_DOT11_NUMBER_OF_HOPPING_SETS](https://msdn.microsoft.com/library/windows/hardware/ff569394) | C | | | | +| [OID_DOT11_OPERATIONAL_RATE_SET](https://msdn.microsoft.com/library/windows/hardware/ff569395) | R | R | X | | +| [OID_DOT11_PBCC_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569398) | O | | | | +| [OID_DOT11_RANDOM_TABLE_FLAG](https://msdn.microsoft.com/library/windows/hardware/ff569406) | C | | | | +| [OID_DOT11_REG_DOMAINS_SUPPORT_VALUE](https://msdn.microsoft.com/library/windows/hardware/ff569408) | R | | | | +| [OID_DOT11_RTS_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569411) | R | R | X | X | +| [OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569414) | O | | | | +| [OID_DOT11_SHORT_RETRY_LIMIT](https://msdn.microsoft.com/library/windows/hardware/ff569415) | O | | | | +| [OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED](https://msdn.microsoft.com/library/windows/hardware/ff569416) | O | | | | +| [OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED](https://msdn.microsoft.com/library/windows/hardware/ff569417) | O | | | | +| [OID_DOT11_STATION_ID](https://msdn.microsoft.com/library/windows/hardware/ff569419) | O | | | | +| [OID_DOT11_SUPPORTED_DSSS_CHANNEL_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569423) | O | | X | X | +| [OID_DOT11_SUPPORTED_OFDM_FREQUENCY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569425) | O | | X | X | +| [OID_DOT11_TEMP_TYPE](https://msdn.microsoft.com/library/windows/hardware/ff569431) | O | | | | +| [OID_DOT11_TI_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/ff569432) | O | | | | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-network-monitor-oids.md b/windows-driver-docs-pr/network/native-802-11-network-monitor-oids.md new file mode 100644 index 0000000000..745eb6c942 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-network-monitor-oids.md @@ -0,0 +1,36 @@ +--- +title: Native 802.11 Network Monitor OIDs +description: This section describes Native 802.11 Network Monitor OIDs and their characteristics. +keywords: ["Native 802.11 Network Monitor OIDs", "Native 802.11 WLAN Network Monitor OIDs", "WDK Native 802.11 Network Monitor OIDs", "Native 802.11 Network Monitor object identifiers"] +ms.assetid: 65B49544-04CE-49E0-98A2-47E8FF03A4AF +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Network Monitor OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +This section defines the Native 802.11 object identifiers (OIDs) that are valid for set or query requests when the miniport driver is operating in Network Monitor (NetMon) mode. For more information about the NetMon operation mode, see [Network Monitor Operation Mode](network-monitor-operation-mode.md). + +In the following table, these abbreviations are used to specify the requirements for Native 802.11 OID query (Q), set (S), and NDIS 6.0 method (M) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- C +Indicates that support for the object is conditionally required for certain hardware or software functionality. If the 802.11 station supports the functionality, the miniport driver must support query or set requests for the object. Otherwise, the miniport driver must fail the set or query requests by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +| Name | Q | S | +| --- |---|---| +| [OID_DOT11_CURRENT_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/ff569127) | C | C | +| [OID_DOT11_CURRENT_FREQUENCY](https://msdn.microsoft.com/library/windows/hardware/ff569130) | C | C | +| [OID_DOT11_CURRENT_OPERATION_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569132) | R | R | +| [OID_DOT11_CURRENT_PHY_ID](https://msdn.microsoft.com/library/windows/hardware/ff569135) | R | R | +| [OID_DOT11_DESIRED_PHY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569144) | R | R | +| [OID_DOT11_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/ff569420) | R | | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-oid-terminology.md b/windows-driver-docs-pr/network/native-802-11-oid-terminology.md new file mode 100644 index 0000000000..ff88026fa5 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-oid-terminology.md @@ -0,0 +1,36 @@ +--- +title: Native 802.11 OID terminology +description: This section describes terminology for Native 802.11 OIDs. +keywords: ["Native 802.11 OIDs", "Native 802.11 WLAN OIDs", "WDK Native 802.11 IDs", "Native 802.11 object identifiers", "Native 802.11 OID terminology", "Native 802.11 terminology"] +ms.assetid: F7F753B3-524A-4A90-9DFD-AFD40B167296 +ms.author: windowsdriverdev +ms.date: 04/24/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 OID terminology + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 OID documentation uses the following terms to indicate functionality implemented by the wireless LAN (WLAN) software and hardware: + +| Term | Meaning | +| --- | --- | +| Miniport driver | Functionality implemented by miniport driver only | +| Network interface card (NIC) | Functionality implemented by NIC hardware only | +| 802.11 Station | Functionality implemented by miniport driver or NIC firmware/hardware | + +The Native 802.11 interface defines scalar data types using the following reverse-Hungarian notation: + +| Prefix | Data type | +| --- | --- | +| b | BOOLEAN | +| u | ULONG | +| us | USHORT | +| uc | UCHAR | +| ull | ULONGLONG | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-oids.md b/windows-driver-docs-pr/network/native-802-11-oids.md new file mode 100644 index 0000000000..084881cc98 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-oids.md @@ -0,0 +1,40 @@ +--- +title: Native 802.11 OIDs +description: This section describes Native 802.11 OIDs and their characteristics. +keywords: ["Native 802.11 OIDs", "Native 802.11 WLAN OIDs", "WDK Native 802.11 IDs", "Native 802.11 object identifiers"] +ms.assetid: A0B31D4B-E7E1-44B1-BE00-26B2070FE58A +ms.author: windowsdriverdev +ms.date: 04/24/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 wireless LAN (WLAN) object identifiers (OIDs) are supported by versions 6.0 and later of the Network Driver Interface Specification (NDIS). Miniport drivers that support the Native 802.11 interface for IEEE 802.11 network interface cards (NICs) must support all mandatory Native 802.11 OIDs. For some OIDs, support is optional. + +In addition, miniport drivers that support the Native 802.11 interface must also support the mandatory NDIS general OIDS. For more information about these OIDs, see [General OIDs](https://msdn.microsoft.com/library/windows/hardware/ff552468). + +Native 802.11 OIDs are issued by the Windows operating system. Third-party drivers cannot issue them. + +A user-mode application or script can query the Native 802.11 OIDs indirectly by calling Microsoft Windows Management Instrumentation (WMI) methods. For more information, see [WMI Tasks: Networking](http://msdn.microsoft.com/library/windows/desktop/aa394595). Native 802.11 OIDs cannot be set in this way. + +The Native 802.11 OIDs are defined in Windot11.h. When building a driver that supports these OIDs, include Ndis.h. + +The Native 802.11 OIDs are described in the following sections: + +- [Native 802.11 Extensible AP OIDs](native-802-11-extensible-ap-oids.md) +- [Native 802.11 Extensible Station OIDs](native-802-11-extensible-station-oids.md) +- [Native 802.11 Network Monitor OIDs](native-802-11-network-monitor-oids.md) +- [Native 802.11 Operational OIDs](native-802-11-operational-oids.md) +- [Native 802.11 MIB OIDs](native-802-11-mib-oids.md) +- [Native 802.11 Virtual WiFi OIDs](native-802-11-virtual-wifi-oids.md) + +For an overview of the terms and naming conventions used throughout this section, see [Native 802.11 OID terminology](native-802-11-oid-terminology.md). + + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-operational-mib-objects.md b/windows-driver-docs-pr/network/native-802-11-operational-mib-objects.md new file mode 100644 index 0000000000..99b3656a4f --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-operational-mib-objects.md @@ -0,0 +1,35 @@ +--- +title: Native 802.11 Operational MIB objects +description: This section describes Native 802.11 Operational MIB objects +keywords: ["Native 802.11 Operational MIB objects", "Native 802.11 WLAN Operational MIB objects", "WDK Native 802.11 Operational MIB objects"] +ms.assetid: 6757B4C4-FC4E-476D-9F9E-A654A5609283 +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Operational MIB objects + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +Some of the Native 802.11 Operational object identifiers (OIDs) are used to reference Native 802.11 Operational management information base (MIB) objects. + +The following table lists the Native 802.11 Operational OID name and the corresponding Native 802.11 Operational MIB object name. For more information about a Native 802.11 Operational MIB object, refer to the topic for the specific Native 802.11 Operational OID. + +| Native 802.11 Operational OID name | Native 802.11 Operational MIB object name | +| --- | --- | +| [OID_DOT11_NIC_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569392) | msDot11NICPowerState | +| [OID_DOT11_SUPPORTED_PHY_TYPES](https://msdn.microsoft.com/library/windows/hardware/ff569426) | msDot11SupportedPhyTypes | + +Unless a Native 802.11 Operational MIB object defines a specific default value, the Native 802.11 miniport driver defines its own default value for the MIB object. + +>[!NOTE] +> When the miniport driver receives an [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) method request, the miniport driver must reset a Native 802.11 Operational MIB object to its default value under the following conditions: + - When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to **TRUE**. + - When MAC or PHY values are affected by the value of the **dot11ResetType** member. +> For more information, refer to the topic for the specific Native 802.11 Operational OID. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-operational-oids.md b/windows-driver-docs-pr/network/native-802-11-operational-oids.md new file mode 100644 index 0000000000..70b41cb023 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-operational-oids.md @@ -0,0 +1,59 @@ +--- +title: Native 802.11 Operational OIDs +description: This section describes Native 802.11 Operational OIDs and their characteristics. +keywords: ["Native 802.11 Operational OIDs", "Native 802.11 WLAN Operational OIDs", "WDK Native 802.11 Operational OIDs", "Native 802.11 Operational object identifiers"] +ms.assetid: F2443987-F018-49C3-844A-AEF665513A4E +ms.author: windowsdriverdev +ms.date: 04/25/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Operational OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 Operational object identifiers (OIDs) query and set the configuration and operation of the 802.11 station. These OIDs are applicable to miniport drivers that support any of the Native 802.11 operation modes. For more information about these operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). + +>[!NOTE] +> For the Windows Vista operating system, only the Extensible Station (ExtSTA) operation mode is supported. + +In the following table, these abbreviations are used to specify the requirements for Native 802.11 Operational OID query (Q), set (S), and NDIS 6.0 method (M) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- O +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- X +Indicates that the specified state of a Native 802.11 operating mode supports a set request for the object. If the miniport driver is not in the specified state, the miniport driver must fail the set request by returning NDIS_STATUS_INVALID_STATE from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +For more information about Native 802.11 operation modes, see [Native 802.11 Operation Modes](native-802-11-operation-modes.md). For more information about Native 802.11 operating states, see [Native 802.11 Operating States](native-802-11-operating-states.md). + +| Name | Q | S | M | ExtSTA INIT| ExtSTA OP| +|--- |---|---|---|--- |--- | +| [OID_DOT11_ATIM_WINDOW](https://msdn.microsoft.com/library/windows/hardware/ff569105) | O | O | | X | | +| [OID_DOT11_CURRENT_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/ff569125) | O | | | | | +| [OID_DOT11_CURRENT_OPERATION_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569132) | R | R | | X | | +| [OID_DOT11_CURRENT_OPTIONAL_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569133) | O | | | | | +| [OID_DOT11_DATA_RATE_MAPPING_TABLE](https://msdn.microsoft.com/library/windows/hardware/ff569139) | O | | | | | +| [OID_DOT11_MAXIMUM_LIST_SIZE](https://msdn.microsoft.com/library/windows/hardware/ff569382) | O | | | | | +| [OID_DOT11_MPDU_MAX_LENGTH](https://msdn.microsoft.com/library/windows/hardware/ff569387) | O | | | | | +| [OID_DOT11_MULTICAST_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569388) | R | R | | | | +| [OID_DOT11_NIC_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569392) | R | R | | X | | +| [OID_DOT11_NIC_SPECIFIC_EXTENSION](https://msdn.microsoft.com/library/windows/hardware/ff569393) | | | O | X | X | +| [OID_DOT11_OPERATION_MODE_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569396) | O | | | | | +| [OID_DOT11_OPTIONAL_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569397) | O | | | | | +| [OID_DOT11_PERMANENT_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/ff569399) | O | | | | | +| [OID_DOT11_RECV_SENSITIVITY_LIST](https://msdn.microsoft.com/library/windows/hardware/ff569407) | O | | | | | +| [OID_DOT11_RESET_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569409) | | | R | X | X | +| [OID_DOT11_RF_USAGE](https://msdn.microsoft.com/library/windows/hardware/ff569410) | O | | | | | +| [OID_DOT11_SCAN_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff569413) | | R | | X | X | +| [OID_DOT11_SUPPORTED_DATA_RATES_VALUE](https://msdn.microsoft.com/library/windows/hardware/ff569422) | O | | | | | +| [OID_DOT11_SUPPORTED_PHY_TYPES](https://msdn.microsoft.com/library/windows/hardware/ff569426) | O | | | | | +| [OID_DOT11_SUPPORTED_POWER_LEVELS](https://msdn.microsoft.com/library/windows/hardware/ff569427) | O | | | | | +| [OID_DOT11_SUPPORTED_RX_ANTENNA](https://msdn.microsoft.com/library/windows/hardware/ff569428) | O | | | | | +| [OID_DOT11_SUPPORTED_TX_ANTENNA](https://msdn.microsoft.com/library/windows/hardware/ff569429) | O | | | | | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-virtual-wifi-oids.md b/windows-driver-docs-pr/network/native-802-11-virtual-wifi-oids.md new file mode 100644 index 0000000000..3027648623 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-virtual-wifi-oids.md @@ -0,0 +1,36 @@ +--- +title: Native 802.11 Virtual WiFi OIDs +description: This section describes Native 802.11 Virtual WiFi OIDs and their characteristics. +keywords: ["Native 802.11 Virtual WiFi OIDs", "Native 802.11 WLAN Virtual WiFi OIDs", "WDK Native 802.11 Virtual WiFi OIDs", "Native 802.11 Virtual WiFi object identifiers"] +ms.assetid: B2D106FF-3FDF-4382-B76E-2C815917DD29 +ms.author: windowsdriverdev +ms.date: 04/26/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 Virtual WiFi OIDs + +>[!IMPORTANT] +> The [Native 802.11 Wireless LAN](native-802-11-wireless-lan4.md) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](wifi-universal-driver-model.md). + +The Native 802.11 Virtual Wireless Fidelity (Virtual WiFi) object identifiers (OIDs) are applicable only to miniport drivers that support the Native 802.11 Virtual WiFi operation mode. + +>[!NOTE] +>The Native 802.11 Virtual WiFi operation mode is available in Windows 7 and later versions of the Windows operating systems. + +In the following table, the R abbreviation specifies the requirements for Native 802.11 Extensible AP (ExtAP) OID query (Q), set (S), and NDIS 6.0 method (M) requests: + +- R +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- O +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its [MiniportOidRequest](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +| Name | Q | S | M | +|--- |---|---|---| +| [OID_DOT11_CREATE_MAC](https://msdn.microsoft.com/library/windows/hardware/ff569124) | | | R | +| [OID_DOT11_DELETE_MAC](https://msdn.microsoft.com/library/windows/hardware/ff569140) | | R | | +| [OID_DOT11_VIRTUAL_STATION_CAPABILITY](https://msdn.microsoft.com/library/windows/hardware/ff569435) | O | | | + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/native-802-11-wfd-status-indications.md b/windows-driver-docs-pr/network/native-802-11-wfd-status-indications.md new file mode 100644 index 0000000000..65f62331e6 --- /dev/null +++ b/windows-driver-docs-pr/network/native-802-11-wfd-status-indications.md @@ -0,0 +1,62 @@ +--- +title: Native 802.11 WFD Status Indications +author: windows-driver-content +description: This section lists NDIS status notifications for Wi-Fi Direct (WFD) miniport drivers +ms.assetid: D0D18181-06B2-4554-A4D3-75B7778BEB04 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Native 802.11 WFD Status Indications + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +This section lists NDIS status notifications for Wi-Fi Direct (WFD) miniport drivers: + +[**NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE**](ndis-status-dot11-wfd-discover-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE**](ndis-status-dot11-wfd-go-negotiation-confirmation-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE**](ndis-status-dot11-wfd-go-negotiation-request-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE**](ndis-status-dot11-wfd-go-negotiation-response-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_GROUP\_OPERATING\_CHANNEL**](-ndis-status-dot11-wfd-group-operating-channel.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE**](ndis-status-dot11-wfd-invitation-request-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE**](ndis-status-dot11-wfd-invitation-response-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE**](ndis-status-dot11-wfd-provision-discovery-request-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE**](ndis-status-dot11-wfd-provision-discovery-response-send-complete.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION**](ndis-status-dot11-wfd-received-go-negotiation-confirmation.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST**](ndis-status-dot11-wfd-received-go-negotiation-request.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE**](ndis-status-dot11-wfd-received-go-negotiation-response.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST**](ndis-status-dot11-wfd-received-invitation-request.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_RESPONSE**](ndis-status-dot11-wfd-received-invitation-response.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST**](ndis-status-dot11-wfd-received-provision-discovery-request.md) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE**](ndis-status-dot11-wfd-received-provision-discovery-response.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Native%20802.11%20WFD%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/native-802-11-wireless-lan4.md b/windows-driver-docs-pr/network/native-802-11-wireless-lan4.md index bf88083e6c..329def28bc 100644 --- a/windows-driver-docs-pr/network/native-802-11-wireless-lan4.md +++ b/windows-driver-docs-pr/network/native-802-11-wireless-lan4.md @@ -35,6 +35,8 @@ This section includes the following topics: [Native 802.11 IHV Extensions](native-802-11-ihv-extensions.md) +[Native 802.11 OIDs](native-802-11-oids.md) + [Wi-Fi Direct Miniport Initialization and Configuration](wi-fi-direct-miniport-initialization-and-configuration.md) [Wi-Fi Direct Protocol Implementation](wi-fi-direct-protocol-implementation.md) diff --git a/windows-driver-docs-pr/network/ndis-core-functionality-oids.md b/windows-driver-docs-pr/network/ndis-core-functionality-oids.md new file mode 100644 index 0000000000..12b02a974d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-core-functionality-oids.md @@ -0,0 +1,21 @@ +--- +title: NDIS core functionality OIDs +description: This section describes core functionality OIDs for all NDIS drivers +keywords: ["NDIS core functionality OIDs", "WDK NDIS core functionality OIDs", "WDK network core functionality OIDs"] +ms.assetid: 2DFDB362-1E34-4E1D-A549-F9909B068315 +ms.author: windows-driver-content +ms.date: 04/20/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS core functionality OIDs + +This section contains topics describing the following categories of OIDS that are part of NDIS core functionality. + +[NDIS general statistics OIDs](ndis-general-statistics-oids.md) + +[NDIS network interface OIDs](ndis-network-interface-oids.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/ndis-core-functionality-status-indications.md b/windows-driver-docs-pr/network/ndis-core-functionality-status-indications.md new file mode 100644 index 0000000000..1d57c59dc1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-core-functionality-status-indications.md @@ -0,0 +1,29 @@ +--- +title: NDIS core functionality status indications +description: This section describes core functionality status indications for all NDIS drivers +keywords: ["NDIS core functionality status indications", "WDK NDIS core functionality status indications", "WDK network core functionality status indications"] +ms.assetid: 6C4BC99E-38D0-4529-89CC-B526F9842E17 +ms.author: windows-driver-content +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS core functionality status indications + +This section contains topics describing the following categories of NDIS core functionality status indications. + +[NDIS General Status Indications](ndis-general-status-indications.md) + +[Receive Filter Status Indications](receive-filter-status-indications.md) + +[NDIS QoS Status Indications](ndis-qos-status-indications.md) + +[NDIS TCP/IP Offload Status Indications](ndis-tcp-ip-offload-status-indications.md) + +[NDIS Wake Reason Status Indications](ndis-wake-reason-status-indications-ref.md) + +[NDIS WAN Status Indications](ndis-wan-status-indications.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/ndis-core-functionality2.md b/windows-driver-docs-pr/network/ndis-core-functionality2.md index d2e7d5742a..87d871162c 100644 --- a/windows-driver-docs-pr/network/ndis-core-functionality2.md +++ b/windows-driver-docs-pr/network/ndis-core-functionality2.md @@ -43,6 +43,8 @@ This section includes: [Installing and Upgrading Network Components](installing-and-upgrading-network-components.md) +[NDIS core functionality OIDs](ndis-core-functionality-oids.md) +     diff --git a/windows-driver-docs-pr/network/ndis-current-irql.md b/windows-driver-docs-pr/network/ndis-current-irql.md new file mode 100644 index 0000000000..d4460b7e37 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-current-irql.md @@ -0,0 +1,87 @@ +--- +title: NDIS_CURRENT_IRQL macro +author: windows-driver-content +description: The NDIS_CURRENT_IRQL macro returns the current interrupt request level (IRQL). +ms.assetid: 002c751c-6106-47bc-ab11-610fbcd84ffa +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_CURRENT_IRQL macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_CURRENT\_IRQL macro + + +The NDIS\_CURRENT\_IRQL macro returns the current interrupt request level (IRQL). + +Syntax +------ + +```ManagedCPlusPlus +KIRQL NDIS_CURRENT_IRQL( +   None +); +``` + +Parameters +---------- + +*None* + +Return value +------------ + +NDIS\_CURRENT\_IRQL returns the current IRQL as a KIRQL-type value. + +Remarks +------- + +NDIS drivers should use the NDIS\_CURRENT\_IRQL macro to obtain the caller's current IRQL. + +This macro is an NDIS wrapper for the [**KeGetCurrentIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552054) routine + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

+ +## See also + + +[**KeGetCurrentIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552054) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_CURRENT_IRQL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-current-processor-number.md b/windows-driver-docs-pr/network/ndis-current-processor-number.md new file mode 100644 index 0000000000..8eec00b957 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-current-processor-number.md @@ -0,0 +1,91 @@ +--- +title: NDIS_CURRENT_PROCESSOR_NUMBER macro +author: windows-driver-content +description: The NDIS_CURRENT_PROCESSOR_NUMBER macro returns the system-assigned number of the current processor that the caller is running on. +ms.assetid: 83a9861c-f8c1-404b-baa3-c5e9f3d760bb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_CURRENT_PROCESSOR_NUMBER macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_CURRENT\_PROCESSOR\_NUMBER macro + + +The **NDIS\_CURRENT\_PROCESSOR\_NUMBER** macro returns the system-assigned number of the current processor that the caller is running on. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NDIS_CURRENT_PROCESSOR_NUMBER( +   None +); +``` + +Parameters +---------- + +*None* + +Return value +------------ + +NDIS\_CURRENT\_PROCESSOR\_NUMBER returns a ULONG value that represents the processor that the caller is currently running on. + +Remarks +------- + +An NDIS driver might call NDIS\_CURRENT\_PROCESSOR\_NUMBER if it maintains some per-processor data. + +The number of processors in a symmetric multiprocessor (SMP) computer is a zero-based value. + +The NDIS\_CURRENT\_PROCESSOR\_NUMBER wraps the [**KeGetCurrentProcessorNumber**](https://msdn.microsoft.com/library/windows/hardware/ff552063) routine. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and NDIS 6.1. For NDIS 6.20 and later, use [NdisCurrentProcessorIndex](https://msdn.microsoft.com/library/windows/hardware/ff561737) instead.

Header

Ndis.h (include Ndis.h)

IRQL

>= DISPATCH_LEVEL

+ +## See also + + +[**KeGetCurrentProcessorNumber**](https://msdn.microsoft.com/library/windows/hardware/ff552063) + +[**NdisCurrentProcessorIndex**](https://msdn.microsoft.com/library/windows/hardware/ff561737) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_CURRENT_PROCESSOR_NUMBER%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-declare-switch-net-buffer-list-context-type.md b/windows-driver-docs-pr/network/ndis-declare-switch-net-buffer-list-context-type.md new file mode 100644 index 0000000000..2c73493e10 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-declare-switch-net-buffer-list-context-type.md @@ -0,0 +1,86 @@ +--- +title: NDIS\_DECLARE\_SWITCH\_NET\_BUFFER\_LIST\_CONTEXT\_TYPE macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS\_DECLARE\_SWITCH\_NET\_BUFFER\_LIST\_CONTEXT\_TYPE macro to define the context type that is used by the SetNetBufferListSwitchContext and GetNetBufferListSwitchContext functions to attach and retrieve context from a NET\_BUFFER\_LIST structure. Extensions can define as many context types as they want within their driver. +ms.assetid: 1DADD5C2-10AD-409C-9382-D98FC8789E5A +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_DECLARE\_SWITCH\_NET\_BUFFER\_LIST\_CONTEXT\_TYPE macro + + +Hyper-V extensible switch extensions use the **NDIS\_DECLARE\_SWITCH\_NET\_BUFFER\_LIST\_CONTEXT\_TYPE** macro to define the context type that is used by the [*SetNetBufferListSwitchContext*](https://msdn.microsoft.com/library/windows/hardware/hh846223) and [*GetNetBufferListSwitchContext*](https://msdn.microsoft.com/library/windows/hardware/hh846190) functions to attach and retrieve context from a [NET\_BUFFER\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568412) structure. Extensions can define as many context types as they want within their driver. + +Syntax +------ + +```ManagedCPlusPlus + NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE( +  _ContextName ContextName, +  _ExtensionId ExtensionId +); +``` + +Parameters +---------- + +*ContextName* +An identifier for the context type. + +*ExtensionId* +A GUID that matches the extension ID. + +Return value +------------ + +None. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*SetNetBufferListSwitchContext*](https://msdn.microsoft.com/library/windows/hardware/hh846223) + +[*GetNetBufferListSwitchContext*](https://msdn.microsoft.com/library/windows/hardware/hh846190) + +[NET\_BUFFER\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568412) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-general-status-indications.md b/windows-driver-docs-pr/network/ndis-general-status-indications.md new file mode 100644 index 0000000000..8ef521af7d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-general-status-indications.md @@ -0,0 +1,53 @@ +--- +title: NDIS General Status Indications +author: windows-driver-content +description: NDIS General Status Indications +ms.assetid: 0ce19114-9861-4904-8222-1c229aa0008d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS General Status Indications + + +## + + +This section includes: + +[**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) + +[**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) + +[**NDIS\_STATUS\_RESET\_START**](ndis-status-reset-start.md) + +[**NDIS\_STATUS\_RESET\_END**](ndis-status-reset-end.md) + +[**NDIS\_STATUS\_MEDIA\_BUSY**](ndis-status-media-busy.md) + +[**NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION**](ndis-status-media-specific-indication.md) + +[**NDIS\_STATUS\_LINK\_SPEED\_CHANGE**](ndis-status-link-speed-change.md) + +[**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) + +[**NDIS\_STATUS\_PORT\_STATE**](ndis-status-port-state.md) + +[**NDIS\_STATUS\_OPER\_STATUS**](ndis-status-oper-status.md) + +[**NDIS\_STATUS\_NETWORK\_CHANGE**](ndis-status-network-change.md) + +[**NDIS\_STATUS\_PACKET\_FILTER**](ndis-status-packet-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20General%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-get-net-buffer-list-cancel-id.md b/windows-driver-docs-pr/network/ndis-get-net-buffer-list-cancel-id.md new file mode 100644 index 0000000000..35fb562062 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-get-net-buffer-list-cancel-id.md @@ -0,0 +1,90 @@ +--- +title: NDIS_GET_NET_BUFFER_LIST_CANCEL_ID macro +author: windows-driver-content +description: The NDIS_GET_NET_BUFFER_LIST_CANCEL_ID macro gets the cancellation identifier from a NET_BUFFER_LIST structure. +ms.assetid: ad302c12-24d9-4310-ac5a-dd295589fcbd +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_GET_NET_BUFFER_LIST_CANCEL_ID macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro + + +The NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro gets the cancellation identifier from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NDIS_GET_NET_BUFFER_LIST_CANCEL_ID( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID returns a ULONG value that is a cancellation identifier for the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Remarks +------- + +To cancel send requests, filter drivers call the [**NdisFCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561794) function. Other NDIS drivers call the [**NdisCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561623) function. + +Drivers can call the **NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID** macro to set a cancellation identifier in a NET\_BUFFER\_LIST structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NdisCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561623) + +[**NdisFCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561794) + +[**NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID**](ndis-set-net-buffer-list-cancel-id.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_GET_NET_BUFFER_LIST_CANCEL_ID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-init-mutex.md b/windows-driver-docs-pr/network/ndis-init-mutex.md new file mode 100644 index 0000000000..1be8ceede0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-init-mutex.md @@ -0,0 +1,98 @@ +--- +title: NDIS_INIT_MUTEX macro +author: windows-driver-content +description: The NDIS_INIT_MUTEX macro initializes a mutex object and sets it to a signaled state. +ms.assetid: d0d21732-e74d-42ac-a051-1f6a960092e1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_INIT_MUTEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_INIT\_MUTEX macro + + +The NDIS\_INIT\_MUTEX macro initializes a mutex object and sets it to a signaled state. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_INIT_MUTEX( +  PNDIS_MUTEX _Mutex_ +); +``` + +Parameters +---------- + +*\_Mutex\_* +A pointer to a caller-supplied NDIS\_MUTEX-type mutex object. NDIS\_MUTEX is a wrapper for KMUTEX. + +Return value +------------ + +None + +Remarks +------- + +NDIS network drivers should use the NDIS\_INIT\_MUTEX macro to initialize a mutex. + +The initial state of the mutex object is the signaled state. To acquire the mutex, call the [**NDIS\_WAIT\_FOR\_MUTEX**](ndis-wait-for-mutex.md) macro. To release the mutex, call the [**NDIS\_RELEASE\_MUTEX**](ndis-release-mutex.md) macro. + +A driver cannot wait for a nonzero time interval on a mutex object at a raised IRQL or in an *arbitrary thread context* (that is, the context of whatever thread is current when a driver function is called). + +Storage for a mutex object must reside in a driver context area or in a nonpaged pool that the caller allocated. + +The NDIS\_INIT\_MUTEX macro is an NDIS wrapper for the [**KeInitializeMutex**](https://msdn.microsoft.com/library/windows/hardware/ff552147) routine. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

+ +## See also + + +[**KeInitializeMutex**](https://msdn.microsoft.com/library/windows/hardware/ff552147) + +[**NDIS\_RELEASE\_MUTEX**](ndis-release-mutex.md) + +[**NDIS\_WAIT\_FOR\_MUTEX**](ndis-wait-for-mutex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_INIT_MUTEX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-intermediate-drivers.md b/windows-driver-docs-pr/network/ndis-intermediate-drivers.md index 0469773756..3e22374327 100644 --- a/windows-driver-docs-pr/network/ndis-intermediate-drivers.md +++ b/windows-driver-docs-pr/network/ndis-intermediate-drivers.md @@ -12,7 +12,7 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# Intermediat drivers +# Intermediate drivers ## diff --git a/windows-driver-docs-pr/network/ndis-interrupt-and-synchronization-macros.md b/windows-driver-docs-pr/network/ndis-interrupt-and-synchronization-macros.md new file mode 100644 index 0000000000..73f41d623f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-interrupt-and-synchronization-macros.md @@ -0,0 +1,43 @@ +--- +title: NDIS Interrupt and Synchronization Macros +author: windows-driver-content +description: NDIS Interrupt and Synchronization Macros +ms.assetid: ffe9d64d-eb0f-4376-bb94-65a11aeeea02 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS Interrupt and Synchronization Macros + + +## + + +This section includes: + +[**NDIS\_CURRENT\_PROCESSOR\_NUMBER**](ndis-current-processor-number.md) + +[**NDIS\_CURRENT\_IRQL**](ndis-current-irql.md) + +[**NDIS\_RAISE\_IRQL\_TO\_DISPATCH**](ndis-raise-irql-to-dispatch.md) + +[**NDIS\_LOWER\_IRQL**](ndis-lower-irql.md) + +[**NDIS\_INIT\_MUTEX**](ndis-init-mutex.md) + +[**NDIS\_RELEASE\_MUTEX**](ndis-release-mutex.md) + +[**NDIS\_WAIT\_FOR\_MUTEX**](ndis-wait-for-mutex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20Interrupt%20and%20Synchronization%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-isolation-parameters-get-first-routing-domain-entry.md b/windows-driver-docs-pr/network/ndis-isolation-parameters-get-first-routing-domain-entry.md new file mode 100644 index 0000000000..03b2720b60 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-isolation-parameters-get-first-routing-domain-entry.md @@ -0,0 +1,79 @@ +--- +title: NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY macro +author: windows-driver-content +description: The NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY macro is used to access the first NDIS\_ROUTING\_DOMAIN\_ENTRY that is specified by an NDIS\_ISOLATION\_PARAMETERS structure. +ms.assetid: 81BFFFAF-89D7-4C21-92C9-D17A92097877 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_ISOLATION_PARAMETERS_GET_FIRST_ROUTING_DOMAIN_ENTRY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY macro + + +The **NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY** macro is used to access the first [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) that is specified by an [**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_ROUTING_DOMAIN_ENTRY NDIS_ISOLATION_PARAMETERS_GET_FIRST_ROUTING_DOMAIN_ENTRY( +  PNDIS_ISOLATION_PARAMETERS _MultiTenancyInfo_ +); +``` + +Parameters +---------- + +*\_MultiTenancyInfo\_* +A pointer to an [**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) structure. + +Return value +------------ + +The **NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY** macro returns a pointer to the first [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) element in the array. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) + +[**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_ISOLATION_PARAMETERS_GET_FIRST_ROUTING_DOMAIN_ENTRY%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-lower-irql.md b/windows-driver-docs-pr/network/ndis-lower-irql.md new file mode 100644 index 0000000000..a06ebcfdaf --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-lower-irql.md @@ -0,0 +1,102 @@ +--- +title: NDIS_LOWER_IRQL macro +author: windows-driver-content +description: The NDIS_LOWER_IRQL macro sets the IRQL on the current processor to the specified value. +ms.assetid: fd6b57a1-cd6f-4d30-b2b6-0c9842706855 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: +- NDIS_LOWER_IRQL macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_LOWER\_IRQL macro + + +The NDIS\_LOWER\_IRQL macro sets the IRQL on the current processor to the specified value. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_LOWER_IRQL( +  KIRQL _OldIrql_, +  KIRQL _CurIrql_ +); +``` + +Parameters +---------- + +*\_OldIrql\_* +The original (that is, unraised) IRQL value from before the driver called the [**NDIS\_RAISE\_IRQL\_TO\_DISPATCH**](ndis-raise-irql-to-dispatch.md) macro. NDIS\_LOWER\_IRQL sets the IRQL to this value. + +*\_CurIrql\_* +The current IRQL value that is active before the call to NDIS\_LOWER\_IRQL. + +Return value +------------ + +None + +Remarks +------- + +NDIS network drivers should use the NDIS\_LOWER\_IRQL macro to restore the IRQL setting that existed before a call to the [**NDIS\_RAISE\_IRQL\_TO\_DISPATCH**](ndis-raise-irql-to-dispatch.md) macro. + +If the value that the *\_OldIrql\_* parameter specifies is not equal to the current IRQL, the NDIS\_LOWER\_IRQL macro attempts to lower the IRQL to the value that the *\_OldIrql\_* parameter specifies. + +It is a fatal error to call NDIS\_LOWER\_IRQL and use a value for *\_OldIrql\_* that was not returned from an immediately preceding call to the [**NDIS\_RAISE\_IRQL\_TO\_DISPATCH**](ndis-raise-irql-to-dispatch.md) macro. + +NDIS\_LOWER\_IRQL is an NDIS wrapper for the [**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) routine. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level (see Remarks section)

DDI compliance rules

[Irql_IrqlSetting_Function](https://msdn.microsoft.com/library/windows/hardware/ff547962)
+ +## See also + + +[**KeLowerIrql**](https://msdn.microsoft.com/library/windows/hardware/ff552968) + +[**NDIS\_RAISE\_IRQL\_TO\_DISPATCH**](ndis-raise-irql-to-dispatch.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_LOWER_IRQL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-make-net-luid.md b/windows-driver-docs-pr/network/ndis-make-net-luid.md new file mode 100644 index 0000000000..e607590ffe --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-make-net-luid.md @@ -0,0 +1,94 @@ +--- +title: NDIS\_MAKE\_NET\_LUID macro +author: windows-driver-content +description: The NDIS\_MAKE\_NET\_LUID macro builds a NET\_LUID value from an interface type and a NET\_LUID index. +ms.assetid: 57b04978-8f02-4d35-9e4a-0929cb79aabb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_MAKE_NET_LUID macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_MAKE\_NET\_LUID macro + + +The NDIS\_MAKE\_NET\_LUID macro builds a [**NET\_LUID**](https://msdn.microsoft.com/library/windows/hardware/ff568747) value from an interface type and a NET\_LUID index. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_MAKE_NET_LUID( +  PNET_LUID _pNetLuid, +  ULONG64   _IfType, +  ULONG64   _NetLuidIndex +); +``` + +Parameters +---------- + +*\_pNetLuid* +A pointer to a caller-supplied [**NET\_LUID**](https://msdn.microsoft.com/library/windows/hardware/ff568747) union. NDIS\_MAKE\_NET\_LUID returns the newly created NET\_LUID value in this variable. + +*\_IfType* +The Internet Assigned Numbers Authority (IANA) interface type. NDIS\_MAKE\_NET\_LUID writes the value at *\_IfType* to the **IfType** member of the NET\_LUID union that the caller provided at *\_pNetLuid* . For a list of interface types, see [NDIS Interface Types](https://msdn.microsoft.com/library/windows/hardware/ff565767). + +*\_NetLuidIndex* +A NET\_LUID index that the caller allocated with the [**NdisIfAllocateNetLuidIndex**](https://msdn.microsoft.com/library/windows/hardware/ff562695) function. NDIS\_MAKE\_NET\_LUID writes the value at *\_NetLuidIndex* to the **NetLuidIndex** member of the NET\_LUID union that the caller provided at *\_pNetLuid* . + +Return value +------------ + +None + +Remarks +------- + +NDIS network interface providers should use the NDIS\_MAKE\_NET\_LUID macro to build a [**NET\_LUID**](https://msdn.microsoft.com/library/windows/hardware/ff568747) value. The provider passes the resulting NET\_LUID value to the [**NdisIfRegisterInterface**](https://msdn.microsoft.com/library/windows/hardware/ff562715) function to register the interface with NDIS. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ntddndis.h)
+ +## See also + + +[**NdisIfAllocateNetLuidIndex**](https://msdn.microsoft.com/library/windows/hardware/ff562695) + +[**NdisIfRegisterInterface**](https://msdn.microsoft.com/library/windows/hardware/ff562715) + +[**NET\_LUID**](https://msdn.microsoft.com/library/windows/hardware/ff568747) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_MAKE_NET_LUID%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-make-rid.md b/windows-driver-docs-pr/network/ndis-make-rid.md new file mode 100644 index 0000000000..5fe7d22961 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-make-rid.md @@ -0,0 +1,97 @@ +--- +title: NDIS_MAKE_RID macro +author: windows-driver-content +description: The NDIS_MAKE_RID macro builds an NDIS_VF_RID value from PCI Express (PCIe) segment, bus, device, and function numbers. The miniport driver uses this value as a PCIe Requestor ID (RID) for a network adapter's PCIe Virtual Function (VF). +ms.assetid: 908F9DCE-D516-44CE-9FBC-0F2DE3F1A3B8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: +- NDIS_MAKE_RID macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_MAKE\_RID macro + + +The NDIS\_MAKE\_RID macro builds an NDIS\_VF\_RID value from PCI Express (PCIe) segment, bus, device, and function numbers. The miniport driver uses this value as a PCIe Requestor ID (RID) for a network adapter's PCIe Virtual Function (VF). + +Syntax +------ + +```ManagedCPlusPlus + NDIS_MAKE_RID( +  ULONG _Segment, +  ULONG _Bus, +  ULONG _Function +); +``` + +Parameters +---------- + +*\_Segment* +The PCIe segment number for the group of PCIe buses on which the device is attached. A PCIe segment is a set of PCIe buses that share configuration space. + +*\_Bus* +The PCIe bus number of the bus on which the network adapter is attached. + +*\_Function* +The function number of a logical device on the network adapter. + +Return value +------------ + +NDIS\_MAKE\_RID returns an NDIS\_VF\_RID value that is constructed from the parameters. + +Remarks +------- + +When it handles an OID request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](https://msdn.microsoft.com/library/windows/hardware/hh451814), the miniport driver for the PCIe Physical Function (PF) uses the NDIS\_MAKE\_RID macro to create a PCIe Requestor ID (RID) value for the VF. The driver retrieves the PCIe segment, bus, device, and function numbers for the VF by calling [**NdisMGetVirtualFunctionLocation**](https://msdn.microsoft.com/library/windows/hardware/hh451487). + +**Note**  If an independent hardware vendor (IHV) provides a virtual bus driver (VBD) as part of its SR-IOV [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840), its PF miniport driver must not call [**NdisMGetVirtualFunctionLocation**](https://msdn.microsoft.com/library/windows/hardware/hh451487). Instead, the driver must interface with the VBD through a private communication channel, and request that the VBD call [*GetLocation*](https://msdn.microsoft.com/library/windows/hardware/hh451128). This function is exposed from the [GUID\_PCI\_VIRTUALIZATION\_INTERFACE](https://msdn.microsoft.com/library/windows/hardware/hh451143) interface supported by the underlying PCI bus driver. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMGetVirtualFunctionLocation**](https://msdn.microsoft.com/library/windows/hardware/hh451487) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](https://msdn.microsoft.com/library/windows/hardware/hh451814) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_MAKE_RID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-mdl-interface.md b/windows-driver-docs-pr/network/ndis-mdl-interface.md new file mode 100644 index 0000000000..a02a0cf837 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-mdl-interface.md @@ -0,0 +1,41 @@ +--- +title: NDIS MDL Interface +author: windows-driver-content +description: NDIS MDL Interface +ms.assetid: d15cbda8-fda5-40e6-ab7f-120d2d26e7ef +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS MDL Interface + + +## + + +This section includes: + +[**NDIS\_MDL\_LINKAGE**](ndis-mdl-linkage.md) + +[**NDIS\_MDL\_TO\_SPAN\_PAGES**](ndis-mdl-to-span-pages.md) + +[**NdisGetMdlPhysicalArraySize**](ndisgetmdlphysicalarraysize.md) + +[**NdisGetNextMdl**](ndisgetnextmdl.md) + +[**NdisQueryMdl**](ndisquerymdl.md) + +[**NdisQueryMdlOffset**](ndisquerymdloffset.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20MDL%20Interface%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-mdl-linkage.md b/windows-driver-docs-pr/network/ndis-mdl-linkage.md new file mode 100644 index 0000000000..9bc1e59c88 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-mdl-linkage.md @@ -0,0 +1,86 @@ +--- +title: NDIS_MDL_LINKAGE macro +author: windows-driver-content +description: The NDIS_MDL_LINKAGE macro retrieves a pointer to the next MDL that is associated with the specified MDL. +ms.assetid: 3d5a91cb-cb26-49fb-b510-75fc95f7f46b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_MDL_LINKAGE macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_MDL\_LINKAGE macro + + +The **NDIS\_MDL\_LINKAGE** macro retrieves a pointer to the next MDL that is associated with the specified MDL. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_MDL_LINKAGE( +  PMDL _Mdl +); +``` + +Parameters +---------- + +*\_Mdl* +A pointer to an MDL. + +Return value +------------ + +**NDIS\_MDL\_LINKAGE** returns a pointer to an MDL or **NULL** if there is no next MDL. + +Remarks +------- + +The **NDIS\_MDL\_LINKAGE** macro provides an MDL-based version of the [**NDIS\_BUFFER\_LINKAGE**](https://msdn.microsoft.com/library/windows/hardware/ff556919) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

+ +## See also + + +[**NDIS\_BUFFER\_LINKAGE**](https://msdn.microsoft.com/library/windows/hardware/ff556919) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_MDL_LINKAGE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-mdl-to-span-pages.md b/windows-driver-docs-pr/network/ndis-mdl-to-span-pages.md new file mode 100644 index 0000000000..bbe4f3d20a --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-mdl-to-span-pages.md @@ -0,0 +1,86 @@ +--- +title: NDIS_MDL_TO_SPAN_PAGES macro +author: windows-driver-content +description: The NDIS_MDL_TO_SPAN_PAGES macro retrieves the number of physical pages of memory that are being used to back a given MDL. +ms.assetid: 8c9df989-4a5f-4ec1-9544-29b59517a502 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: +- NDIS_MDL_TO_SPAN_PAGES macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_MDL\_TO\_SPAN\_PAGES macro + + +The **NDIS\_MDL\_TO\_SPAN\_PAGES** macro retrieves the number of physical pages of memory that are being used to back a given MDL. + +Syntax +------ + +```ManagedCPlusPlus +int NDIS_MDL_TO_SPAN_PAGES( +  PMDL _Mdl +); +``` + +Parameters +---------- + +*\_Mdl* +A pointer to an MDL. + +Return value +------------ + +**NDIS\_MDL\_TO\_SPAN\_PAGES** returns the number of pages that are backing the virtual range for the MDL. + +Remarks +------- + +The **NDIS\_MDL\_TO\_SPAN\_PAGES** macro provides an MDL-based version of the [**NDIS\_BUFFER\_TO\_SPAN\_PAGES**](https://msdn.microsoft.com/library/windows/hardware/ff556922) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

+ +## See also + + +[**NDIS\_BUFFER\_TO\_SPAN\_PAGES**](https://msdn.microsoft.com/library/windows/hardware/ff556922) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_MDL_TO_SPAN_PAGES%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info-ex.md b/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info-ex.md new file mode 100644 index 0000000000..71f4a4b85f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info-ex.md @@ -0,0 +1,90 @@ +--- +title: NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX macro +author: windows-driver-content +description: The NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: eca59601-ea2a-4e22-b4f7-53b966f4a177 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO\_EX macro + + +The NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO\_EX macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX( +  PNET_BUFFER_LIST                     _NBL, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) structure to add to the linked list. + +Return value +------------ + +None + +Remarks +------- + +Any NDIS 6.20 or later driver can use NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO\_EX to add media-specific information to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO**](ndis-nbl-add-media-specific-info.md) + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info.md b/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info.md new file mode 100644 index 0000000000..d929b75215 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-add-media-specific-info.md @@ -0,0 +1,90 @@ +--- +title: NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO macro +author: windows-driver-content +description: The NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: fe6fd49f-90e6-49fd-a430-2cb2fb56c9c5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO macro + + +The **NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO** macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO( +  PNET_BUFFER_LIST                     _NBL, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) structure to add to the linked list. + +Return value +------------ + +None. + +Remarks +------- + +Any NDIS driver can use NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO to add media-specific information to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-add-media-specific-info-ex.md).

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_ADD\_MEDIA\_SPECIFIC\_INFO\_EX**](ndis-nbl-add-media-specific-info-ex.md) + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info-ex.md b/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info-ex.md new file mode 100644 index 0000000000..8a93bda785 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info-ex.md @@ -0,0 +1,96 @@ +--- +title: NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX macro +author: windows-driver-content +description: The NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX macro gets a media-specific information data structure from a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: 06dce06d-e7ce-466c-86d7-26fced4f5695 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO\_EX macro + + +The **NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO\_EX** macro gets a media-specific information data structure from a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX( +  PNET_BUFFER_LIST                     _NBL, +  ULONG                                _Tag, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_Tag* +A unique pre-assigned value that identifies the type of the media-specific information. + +New tags can be assigned in future system releases for new media types that require additional OOB data specific to a particular media type. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) structure. + +Return value +------------ + +None + +Remarks +------- + +Any NDIS 6.20 or later driver can use NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO\_EX to get media-specific information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. When this macro returns, the *\_MediaSpecificInfo* parameter contains a pointer to the first [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) structure in the media-specific information list that has a **Tag** member matching the value specified in the *\_Tag* parameter. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO**](ndis-nbl-get-media-specific-info.md) + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info.md b/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info.md new file mode 100644 index 0000000000..86785e5653 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-get-media-specific-info.md @@ -0,0 +1,96 @@ +--- +title: NDIS_NBL_GET_MEDIA_SPECIFIC_INFO macro +author: windows-driver-content +description: The NDIS_NBL_GET_MEDIA_SPECIFIC_INFO macro gets a media-specific information data structure from a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: 44054921-4ddc-4102-9840-bb069b59d2ae +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_NBL_GET_MEDIA_SPECIFIC_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO macro + + +The NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO macro gets a media-specific information data structure from a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_GET_MEDIA_SPECIFIC_INFO( +  PNET_BUFFER_LIST                     _NBL, +  ULONG                                _Tag, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_Tag* +A unique pre-assigned value that identifies the type of the media-specific information. This member is reserved for system use. + +New tags can be assigned in future system releases for new media types that require additional OOB data specific to a particular media type. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) structure. + +Return value +------------ + +None. + +Remarks +------- + +Any NDIS driver can use NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO to get media-specific information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. When this macro returns, the *\_MediaSpecificInfo* parameter contains a pointer to the first [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) structure in the media-specific information list that has a **Tag** member matching the value specified in the *\_Tag* parameter. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-get-media-specific-info-ex.md).

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_GET\_MEDIA\_SPECIFIC\_INFO\_EX**](ndis-nbl-get-media-specific-info-ex.md) + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_GET_MEDIA_SPECIFIC_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info-ex.md b/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info-ex.md new file mode 100644 index 0000000000..80f79323da --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info-ex.md @@ -0,0 +1,88 @@ +--- +title: NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX macro +author: windows-driver-content +description: The NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX macro removes a media-specific information data structure from a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: e03f2322-e40b-46ea-b9d4-e58c1e44a564 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: +- NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO\_EX macro + + +The **NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO\_EX** macro removes a media-specific information data structure from a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX( +  PNET_BUFFER_LIST                     _NBL, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) structure that has a **Tag** member that matches the **Tag** member of the information structure that should be removed. + +Return value +------------ + +None + +Remarks +------- + +Any NDIS 6.20 or later driver can use NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO\_EX to remove media-specific information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION\_EX**](https://msdn.microsoft.com/library/windows/hardware/ff566518) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info.md b/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info.md new file mode 100644 index 0000000000..c45e4e603d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-nbl-remove-media-specific-info.md @@ -0,0 +1,90 @@ +--- +title: NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO macro +author: windows-driver-content +description: The NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO macro removes a media-specific information data structure from a linked list of such structures that are associated with a NET_BUFFER_LIST structure. +ms.assetid: 70aeef03-208b-4d09-9e0a-dd3571367ae5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO macro + + +The NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO macro removes a media-specific information data structure from a linked list of such structures that are associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO( +  PNET_BUFFER_LIST                     _NBL, +  PNDIS_NBL_MEDIA_SPECIFIC_INFORMATION _MediaSpecificInfo +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_MediaSpecificInfo* +A pointer to an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) structure that has a **Tag** member matching the **Tag** member of the information structure that should be removed. + +Return value +------------ + +None. + +Remarks +------- + +Any NDIS driver can use NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO to remove an [**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) structure from a list of media-specific information. To specify the type information to remove, specify an NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION structure with a matching **Tag** member in the *\_MediaSpecificInfo* parameter. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-remove-media-specific-info-ex.md).

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NBL\_MEDIA\_SPECIFIC\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff566515) + +[**NDIS\_NBL\_REMOVE\_MEDIA\_SPECIFIC\_INFO\_EX**](ndis-nbl-remove-media-specific-info-ex.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-net-buffer-send-and-receive-macros.md b/windows-driver-docs-pr/network/ndis-net-buffer-send-and-receive-macros.md new file mode 100644 index 0000000000..ec75776c83 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-net-buffer-send-and-receive-macros.md @@ -0,0 +1,33 @@ +--- +title: NDIS NET_BUFFER Send and Receive Macros +author: windows-driver-content +description: NDIS NET_BUFFER Send and Receive Macros +ms.assetid: f1117ac8-a9f4-466a-b9f1-ae729a6c9acc +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS NET\_BUFFER Send and Receive Macros + + +## + + +This section includes: + +[**NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID**](ndis-set-net-buffer-list-cancel-id.md) + +[**NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID**](ndis-get-net-buffer-list-cancel-id.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20NET_BUFFER%20Send%20and%20Receive%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-network-interface-oids.md b/windows-driver-docs-pr/network/ndis-network-interface-oids.md new file mode 100644 index 0000000000..ab39c9ea64 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-network-interface-oids.md @@ -0,0 +1,44 @@ +--- +title: NDIS network interface OIDs +description: This section describes network interface OIDs for all NDIS drivers +keywords: ["NDIS network interface OIDs", "WDK NDIS network interface OIDs", "WDK network interface OIDs"] +ms.assetid: A66B5AC6-9EAF-4234-8614-0EBF179B3DDE +ms.author: windows-driver-content +ms.date: 04/20/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS network interface OIDs + +NDIS network interface object identifiers (OIDs) provide information about network interfaces to support the MIB ([RFC 2863](overview-of-ndis-network-interfaces.md)). + +NDIS interface providers must support these OIDs. Drivers that are not registered interface providers should not support the OIDs in this section. + +NDIS calls the [ProviderQueryObject](https://msdn.microsoft.com/library/windows/hardware/ff570399) function to make a query request for information from the interface provider. The *ObjectId* parameter of this function contains the object identifier. The interface provider registered *ProviderQueryObject* when it called the [NdisIfRegisterProvider](https://msdn.microsoft.com/library/windows/hardware/ff562716) function to register as an interface provider. + +The handle at the *ProviderIfContext* parameter of the *ProviderQueryObject* function identifies the network interface. This handle was provided to NDIS when the interface provider called the [NdisIfRegisterInterface](https://msdn.microsoft.com/library/windows/hardware/ff562715) function to register the interface. The *pOutputBuffer* parameter of the *ProviderQueryObject* function contains the result of the OID request. + +For more information about NDIS network interface OIDs, see [NDIS 6.0 Network Interfaces](ndis-network-interfaces2.md). + +This section describes the following NDIS network interface OIDs: + +- [OID_GEN_ALIAS](https://msdn.microsoft.com/library/windows/hardware/ff569438) +- [OID_GEN_ADMIN_STATUS](https://msdn.microsoft.com/library/windows/hardware/ff569437) +- [OID_GEN_OPERATIONAL_STATUS](https://msdn.microsoft.com/library/windows/hardware/ff569619) +- [OID_GEN_PROMISCUOUS_MODE](https://msdn.microsoft.com/library/windows/hardware/ff569625) +- [OID_GEN_XMIT_LINK_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569655) +- [OID_GEN_RCV_LINK_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569630) +- [OID_GEN_UNKNOWN_PROTOS](https://msdn.microsoft.com/library/windows/hardware/ff569648) +- [OID_GEN_DISCONTINUITY_TIME](https://msdn.microsoft.com/library/windows/hardware/ff569581) +- [OID_GEN_LAST_CHANGE](https://msdn.microsoft.com/library/windows/hardware/ff569591) +- [OID_GEN_INTERFACE_INFO](https://msdn.microsoft.com/library/windows/hardware/ff569589) +- [OID_GEN_MEDIA_CONNECT_STATUS_EX](https://msdn.microsoft.com/library/windows/hardware/ff569605) +- [OID_GEN_LINK_SPEED_EX](https://msdn.microsoft.com/library/windows/hardware/ff569594) +- [OID_GEN_MEDIA_DUPLEX_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569606) +- [OID_TUNNEL_INTERFACE_RELEASE_OID](https://msdn.microsoft.com/library/windows/hardware/dn155803) +- [OID_TUNNEL_INTERFACE_SET_OID](https://msdn.microsoft.com/library/windows/hardware/dn155804) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + diff --git a/windows-driver-docs-pr/network/ndis-object-version-issues-for-wmi.md b/windows-driver-docs-pr/network/ndis-object-version-issues-for-wmi.md index 3b3ce606c7..298da69b09 100644 --- a/windows-driver-docs-pr/network/ndis-object-version-issues-for-wmi.md +++ b/windows-driver-docs-pr/network/ndis-object-version-issues-for-wmi.md @@ -30,7 +30,7 @@ Many WMI objects contain the **MSNdis\_ObjectHeader** property, which is equival ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md) [Specifying NDIS Version Information](specifying-ndis-version-information.md) diff --git a/windows-driver-docs-pr/network/ndis-qos-status-indications.md b/windows-driver-docs-pr/network/ndis-qos-status-indications.md new file mode 100644 index 0000000000..e2baa9eb61 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-qos-status-indications.md @@ -0,0 +1,30 @@ +--- +title: NDIS QoS Status Indications +author: windows-driver-content +description: NDIS QoS Status Indications +ms.assetid: 5D1B6264-35C9-4887-A2D1-C8AED017CAFC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS QoS Status Indications + + +This section includes the reference topics of NDIS quality of service (QoS) status indications that are used by miniport drivers for the IEEE 802.1 Data Center Bridging (DCB) interface: + +[**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS**](ndis-status-qos-operational-parameters-change.md) + +[**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](ndis-status-qos-remote-parameters-change.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20QoS%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-raise-irql-to-dispatch.md b/windows-driver-docs-pr/network/ndis-raise-irql-to-dispatch.md new file mode 100644 index 0000000000..2d85900e49 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-raise-irql-to-dispatch.md @@ -0,0 +1,98 @@ +--- +title: NDIS_RAISE_IRQL_TO_DISPATCH macro +author: windows-driver-content +description: The NDIS_RAISE_IRQL_TO_DISPATCH macro raises the current IRQL to DISPATCH_LEVEL on the current processor. +ms.assetid: 37e78374-8ac1-4aa4-9a53-bce3a3411064 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_RAISE_IRQL_TO_DISPATCH macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_RAISE\_IRQL\_TO\_DISPATCH macro + + +The NDIS\_RAISE\_IRQL\_TO\_DISPATCH macro raises the current IRQL to DISPATCH\_LEVEL on the current processor. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_RAISE_IRQL_TO_DISPATCH( +  PKIRQL _pIrql_ +); +``` + +Parameters +---------- + +*\_pIrql\_* +A pointer to a KIRQL-type variable where NDIS\_RAISE\_IRQL\_TO\_DISPATCH stores the original (that is, unraised) IRQL value. You should use this original IRQL value in a subsequent call to the [**NDIS\_LOWER\_IRQL**](ndis-lower-irql.md) macro. + +Return value +------------ + +None + +Remarks +------- + +NDIS network drivers should use the NDIS\_RAISE\_IRQL\_TO\_DISPATCH macro to raise the current IRQL. + +If the current IRQL is greater than DISPATCH\_LEVEL, a bugcheck occurs. Otherwise, the macro sets the current IRQL to DISPATCH\_LEVEL. + +NDIS\_RAISE\_IRQL\_TO\_DISPATCH is an NDIS wrapper for the [**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079) routine. + +The caller should call the [**NDIS\_LOWER\_IRQL**](ndis-lower-irql.md) macro to restore the original IRQL as soon as possible. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

[Irql_IrqlSetting_Function](https://msdn.microsoft.com/library/windows/hardware/ff547962)
+ +## See also + + +[**KeRaiseIrql**](https://msdn.microsoft.com/library/windows/hardware/ff553079) + +[**NDIS\_LOWER\_IRQL**](ndis-lower-irql.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_RAISE_IRQL_TO_DISPATCH%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-release-mutex.md b/windows-driver-docs-pr/network/ndis-release-mutex.md new file mode 100644 index 0000000000..5029d8dcf4 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-release-mutex.md @@ -0,0 +1,100 @@ +--- +title: NDIS_RELEASE_MUTEX macro +author: windows-driver-content +description: The NDIS_RELEASE_MUTEX macro releases the specified mutex object. +ms.assetid: 0358f584-c1a2-4462-8294-09504eb18b17 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_RELEASE_MUTEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_RELEASE\_MUTEX macro + + +The NDIS\_RELEASE\_MUTEX macro releases the specified mutex object. + +Syntax +------ + +```ManagedCPlusPlus +LONG NDIS_RELEASE_MUTEX( +  PNDIS_MUTEX _Mutex_ +); +``` + +Parameters +---------- + +*\_Mutex\_* +A pointer to an initialized NDIS\_MUTEX-type mutex object. The caller initialized the mutex object in a prior call to the [**NDIS\_INIT\_MUTEX**](ndis-init-mutex.md) macro. NDIS\_MUTEX is a wrapper for the KMUTEX type. + +Return value +------------ + +NDIS\_RELEASE\_MUTEX returns a LONG value. If the return value is zero, the mutex object was released and is in the signaled state. If NDIS\_RELEASE MUTEX returns a nonzero value, the mutex is not in the signaled state. + +Remarks +------- + +NDIS network drivers should use the NDIS\_RELEASE\_MUTEX macro to release a mutex. + +Only the thread that is currently holding the mutex object can release it. Otherwise, a bugcheck occurs. A bugcheck also occurs if a driver attempts to release a mutex object that is in the signaled state. + +To acquire the mutex, call the [**NDIS\_WAIT\_FOR\_MUTEX**](ndis-wait-for-mutex.md) macro. If a mutex is acquired recursively, the holding thread must call NDIS\_RELEASE\_MUTEX the same number of times that it acquired the mutex to set it back to the signaled state. + +NDIS\_RELEASE\_MUTEX is an NDIS wrapper for the [**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) routine. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

DDI compliance rules

[Irql_Synch_Function](https://msdn.microsoft.com/library/windows/hardware/ff548015)
+ +## See also + + +[**KeReleaseMutex**](https://msdn.microsoft.com/library/windows/hardware/ff553140) + +[**NDIS\_INIT\_MUTEX**](ndis-init-mutex.md) + +[**NDIS\_WAIT\_FOR\_MUTEX**](ndis-wait-for-mutex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_RELEASE_MUTEX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-first-isolation-entry.md b/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-first-isolation-entry.md new file mode 100644 index 0000000000..75b8266bcd --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-first-isolation-entry.md @@ -0,0 +1,79 @@ +--- +title: NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_FIRST\_ISOLATION\_ENTRY macro +author: windows-driver-content +description: The NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_FIRST\_ISOLATION\_ENTRY macro is used to access the first NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY that is specified by an NDIS\_ROUTING\_DOMAIN\_ENTRY structure. +ms.assetid: 02000ABE-15CB-4893-8BF1-2B5D6C5767EC +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_ROUTING_DOMAIN_ENTRY_GET_FIRST_ISOLATION_ENTRY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_FIRST\_ISOLATION\_ENTRY macro + + +The **NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_FIRST\_ISOLATION\_ENTRY** macro is used to access the first [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) that is specified by an [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_ROUTING_DOMAIN_ISOLATION_ENTRY NDIS_ROUTING_DOMAIN_ENTRY_GET_FIRST_ISOLATION_ENTRY( +  PNDIS_ROUTING_DOMAIN_ENTRY _RoutingDomainEntry_ +); +``` + +Parameters +---------- + +*\_RoutingDomainEntry\_* +A pointer to an [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) structure. + +Return value +------------ + +The **NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_FIRST\_ISOLATION\_ENTRY** macro returns a pointer to the first [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) element in the array. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) + +[**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_ROUTING_DOMAIN_ENTRY_GET_FIRST_ISOLATION_ENTRY%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-next.md b/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-next.md new file mode 100644 index 0000000000..56f31c2cc0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-routing-domain-entry-get-next.md @@ -0,0 +1,81 @@ +--- +title: NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_NEXT macro +author: windows-driver-content +description: The NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_NEXT macro is used to access the next NDIS\_ROUTING\_DOMAIN\_ENTRY element that follows an NDIS\_ROUTING\_DOMAIN\_ENTRY structure in the array that is specified by an NDIS\_ISOLATION\_PARAMETERS structure. +ms.assetid: 134A6FBD-24BF-4401-9226-6706EE6D7CF2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_ROUTING_DOMAIN_ENTRY_GET_NEXT macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_NEXT macro + + +The **NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_NEXT** macro is used to access the next [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) element that follows an **NDIS\_ROUTING\_DOMAIN\_ENTRY** structure in the array that is specified by an [**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_ROUTING_DOMAIN_ENTRY NDIS_ROUTING_DOMAIN_ENTRY_GET_NEXT( +  PNDIS_ROUTING_DOMAIN_ENTRY _RoutingDomainEntry_ +); +``` + +Parameters +---------- + +*\_RoutingDomainEntry\_* +A pointer to an [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) structure. + +Return value +------------ + +The **NDIS\_ROUTING\_DOMAIN\_ENTRY\_GET\_NEXT** macro returns a pointer to the next [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) element in the array. If the *\_RoutingDomainEntry\_* parameter already points to the last element in the array, the macro returns **NULL**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) + +[**NDIS\_ISOLATION\_PARAMETERS\_GET\_FIRST\_ROUTING\_DOMAIN\_ENTRY**](ndis-isolation-parameters-get-first-routing-domain-entry.md) + +[**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_ROUTING_DOMAIN_ENTRY_GET_NEXT%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-routing-domain-isolation-entry-get-next.md b/windows-driver-docs-pr/network/ndis-routing-domain-isolation-entry-get-next.md new file mode 100644 index 0000000000..46c7fb3ee7 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-routing-domain-isolation-entry-get-next.md @@ -0,0 +1,79 @@ +--- +title: NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY\_GET\_NEXT macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY\_GET\_NEXT macro to access the next NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY element that follows an NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY structure in the array that is specified by an NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN structure. +ms.assetid: DFBBD989-08E5-48A3-9D03-C6F914753131 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_ROUTING_DOMAIN_ISOLATION_ENTRY_GET_NEXT macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY\_GET\_NEXT macro + + +Hyper-V extensible switch extensions use the **NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY\_GET\_NEXT** macro to access the next [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) element that follows an **NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY** structure in the array that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN**](https://msdn.microsoft.com/library/windows/hardware/dn383688) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_ROUTING_DOMAIN_ISOLATION_ENTRY NDIS_ROUTING_DOMAIN_ISOLATION_ENTRY_GET_NEXT( +  PNDIS_ROUTING_DOMAIN_ISOLATION_ENTRY _IsolationInfoEntry_ +); +``` + +Parameters +---------- + +*\_IsolationInfoEntry\_* +A pointer to an [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) structure. + +Return value +------------ + +The **NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY\_GET\_NEXT** macro returns a pointer to the next [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) element in the array. If the *\_IsolationInfoEntry\_* parameter already points to the last element in the array, the macro returns **NULL**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN**](https://msdn.microsoft.com/library/windows/hardware/dn383688) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_ROUTING_DOMAIN_ISOLATION_ENTRY_GET_NEXT%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-rss-hash-func-from-hash-info.md b/windows-driver-docs-pr/network/ndis-rss-hash-func-from-hash-info.md new file mode 100644 index 0000000000..fe2f8702af --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-rss-hash-func-from-hash-info.md @@ -0,0 +1,91 @@ +--- +title: NDIS_RSS_HASH_FUNC_FROM_HASH_INFO macro +author: windows-driver-content +description: The NDIS_RSS_HASH_FUNC_FROM_HASH_INFO macro gets the hash function from the hash information. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 003c5778-47da-434d-ad26-2608d160db7c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_RSS_HASH_FUNC_FROM_HASH_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO macro + + +The NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO macro gets the hash function from the hash information. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NDIS_RSS_HASH_FUNC_FROM_HASH_INFO( +  ULONG HashInformation +); +``` + +Parameters +---------- + +*HashInformation* +The hash information. + +Return value +------------ + +NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO returns the hash function from the specified hash information. For more information about the hash information, see [**NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC**](ndis-rss-hash-info-from-type-and-func.md). + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hashing function to calculate an RSS hash value. + +For more information about the hashing functions, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC**](ndis-rss-hash-info-from-type-and-func.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_RSS_HASH_FUNC_FROM_HASH_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-rss-hash-info-from-type-and-func.md b/windows-driver-docs-pr/network/ndis-rss-hash-info-from-type-and-func.md new file mode 100644 index 0000000000..9d6dd1f8ae --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-rss-hash-info-from-type-and-func.md @@ -0,0 +1,131 @@ +--- +title: NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC macro +author: windows-driver-content +description: The NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC macro combines a hash type and hash function into hash information and sets the HashInformation member in the NDIS_RECEIVE_SCALE_PARAMETERS structure. +ms.assetid: c29e3963-d8d0-459d-89ca-1d1a4cf4921f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC macro + + +The NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC macro combines a hash type and hash function into hash information and sets the **HashInformation** member in the NDIS\_RECEIVE\_SCALE\_PARAMETERS structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC( +  ULONG HashType, +  ULONG HashFunction +); +``` + +Parameters +---------- + +*HashType* +The hash type. + +The hash type is an OR value of valid combinations of the following flags: + +NDIS\_HASH\_IPV4 + +NDIS\_HASH\_TCP\_IPV4 + +NDIS\_HASH\_IPV6 + +NDIS\_HASH\_TCP\_IPV6 + +NDIS\_HASH\_IPV6\_EX + +NDIS\_HASH\_TCP\_IPV6\_EX + +For more information about hash types and the valid combinations of these flags, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +*HashFunction* +The hash function that is used. For more information, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +The hash function can be one of the following values: + +**NdisHashFunctionToeplitz** + +**NdisHashFunctionReserved1** + +**NdisHashFunctionReserved2** + +**NdisHashFunctionReserved3** + +Return value +------------ + +NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC returns the hash information that results from combining the specified hash type and hash function. + +## + + +Remarks +------- + +Use the [**NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO**](ndis-rss-hash-type-from-hash-info.md) and [**NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO**](ndis-rss-hash-func-from-hash-info.md) macros to get the hash type and hash function from the hash information. + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hash type to identify the portion of received network data that is used to calculate an RSS hash value. + +For more information about the hash type, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +A NIC (or its miniport driver) uses the RSS hashing function to calculate an RSS hash value. + +For more information about the hashing functions, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RECEIVE\_SCALE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567228) + +[**NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO**](ndis-rss-hash-func-from-hash-info.md) + +[**NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO**](ndis-rss-hash-type-from-hash-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_RSS_HASH_INFO_FROM_TYPE_AND_FUNC%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-rss-hash-type-from-hash-info.md b/windows-driver-docs-pr/network/ndis-rss-hash-type-from-hash-info.md new file mode 100644 index 0000000000..9d5107f681 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-rss-hash-type-from-hash-info.md @@ -0,0 +1,91 @@ +--- +title: NDIS_RSS_HASH_TYPE_FROM_HASH_INFO macro +author: windows-driver-content +description: The NDIS_RSS_HASH_TYPE_FROM_HASH_INFO macro gets the hash type from the hash information. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 927fd4bf-60fa-4779-a6ec-73e577b43a95 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_RSS_HASH_TYPE_FROM_HASH_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO macro + + +The NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO macro gets the hash type from the hash information. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NDIS_RSS_HASH_TYPE_FROM_HASH_INFO( +  ULONG HashInformation +); +``` + +Parameters +---------- + +*HashInformation* +The hash information. For more information about the hash information, see [**NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC**](ndis-rss-hash-info-from-type-and-func.md). + +Return value +------------ + +NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO returns the hash type from the specified hash information. For more information about the hash type, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hash type to identify the portion of received network data that is used to calculate an RSS hash value. + +For more information about the hash type, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC**](ndis-rss-hash-info-from-type-and-func.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_RSS_HASH_TYPE_FROM_HASH_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-set-net-buffer-list-cancel-id.md b/windows-driver-docs-pr/network/ndis-set-net-buffer-list-cancel-id.md new file mode 100644 index 0000000000..f25ee8990e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-set-net-buffer-list-cancel-id.md @@ -0,0 +1,98 @@ +--- +title: NDIS_SET_NET_BUFFER_LIST_CANCEL_ID macro +author: windows-driver-content +description: The NDIS_SET_NET_BUFFER_LIST_CANCEL_ID macro marks a NET_BUFFER_LIST structure with a cancellation identifier that a driver can later use to cancel the pending transmission of the associated data. +ms.assetid: bf68accb-5062-42e7-97e4-c2a3210f60b2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SET_NET_BUFFER_LIST_CANCEL_ID macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro + + +The NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro marks a NET\_BUFFER\_LIST structure with a cancellation identifier that a driver can later use to cancel the pending transmission of the associated data. + +Syntax +------ + +```ManagedCPlusPlus +VOID NDIS_SET_NET_BUFFER_LIST_CANCEL_ID( +  PNET_BUFFER_LIST _NBL, +  ULONG            _CancelId +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_CancelId* +A ULONG value that is a cancellation identifier for the NET\_BUFFER\_LIST structure. + +Return value +------------ + +None + +Remarks +------- + +An NDIS driver can call the NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro for each NET\_BUFFER\_LIST structure that it passes to lower-level drivers for transmission. The NDIS\_SET\_NET\_BUFFER\_LIST\_CANCEL\_ID macro marks the specified NET\_BUFFER\_LIST structure with a cancellation identifier. Drivers must call the [**NdisGeneratePartialCancelId**](https://msdn.microsoft.com/library/windows/hardware/ff562623) function to obtain a value that the driver must use as the high-order byte of a cancellation identifier. + +To cancel send requests, filter drivers call the [**NdisFCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561794) function. Other drivers call the [**NdisCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561623) function. + +Drivers can call the [**NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID**](ndis-get-net-buffer-list-cancel-id.md) macro to retrieve a cancellation identifier from a NET\_BUFFER\_LIST structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NdisCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561623) + +[**NdisFCancelSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff561794) + +[**NdisGeneratePartialCancelId**](https://msdn.microsoft.com/library/windows/hardware/ff562623) + +[**NDIS\_GET\_NET\_BUFFER\_LIST\_CANCEL\_ID**](ndis-get-net-buffer-list-cancel-id.md) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SET_NET_BUFFER_LIST_CANCEL_ID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-association-completion.md b/windows-driver-docs-pr/network/ndis-status-dot11-association-completion.md new file mode 100644 index 0000000000..20c3ceabc7 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-association-completion.md @@ -0,0 +1,82 @@ +--- +title: NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION +ms.assetid: 331aab73-af87-4241-80ac-d60420607270 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_ASSOCIATION_COMPLETION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION indication after an association operation completes. + +The miniport driver indicates the start of the association operation through the [NDIS\_STATUS\_DOT11\_ASSOCIATION\_START](ndis-status-dot11-association-start.md) indication. Every NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION indication. + +For more information about this association operation, see [Association Operations](https://msdn.microsoft.com/library/windows/hardware/ff543789). + +The data type for this indication is the [**DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547647) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION. + +- **StatusBuffer** must be set to the address of a DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS). + +After the miniport driver makes the NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION indication with the **uStatus** member set to DOT11\_ASSOCIATION\_STATUS\_SUCCESS, the miniport driver must do the following: + +- Be prepared to send and receive packets. If the 802.11 station performed the association operation within the context of either a connection or roaming operation, the miniport driver must be able to send or receive packets before it makes the [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) or [NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION](ndis-status-dot11-roaming-completion.md) indications. + +- Add an entry for the current association into its association information list. If the IEEE 802.11 **dot11DesiredBSSType** MIB object is set to **dot11\_BSS\_type\_infrastructure**, the miniport driver must remove the entry for the previous association from its association information list. + + For more information about the association information list, see [OID\_DOT11\_ENUM\_ASSOCIATION\_INFO](oid-dot11-enum-association-info.md). + +- Initialize the authentication algorithm (which is specified by the **AuthAlgo** member) and cipher algorithms (which are specified by the **UnicastCipher** and **MulticastCipher** members) for the association. + +- Delete all non-static default cipher keys. Non-static default cipher keys are created with the **bStatic** member of the DOT11\_CIPHER\_DEFAULT\_KEY\_VALUE structure set to **FALSE**. For more information about this structure, see [OID\_DOT11\_CIPHER\_DEFAULT\_KEY](oid-dot11-cipher-default-key.md). + +- Delete any non-static key-mapping keys for the AP or peer station identified by the **MacAddr** member. Non-static key-mapping keys are created with the **bStatic** member of the DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE structure set to **FALSE**. For more information about this structure, see [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md). + +For more information about the IEEE 802.11 **dot11DesiredBSSType** MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md) + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_ASSOCIATION_COMPLETION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-association-start.md b/windows-driver-docs-pr/network/ndis-status-dot11-association-start.md new file mode 100644 index 0000000000..953b6afd3b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-association-start.md @@ -0,0 +1,138 @@ +--- +title: NDIS\_STATUS\_DOT11\_ASSOCIATION\_START +author: windows-driver-content +description: A miniport driver must make an NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication before it initiates an association operation with either an access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS (IBSS) networks).Note  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use Wi-Fi Direct.� +ms.assetid: be5d3c95-3080-496f-83cd-1a7e329102ff +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_ASSOCIATION_START Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_ASSOCIATION\_START + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication before it initiates an association operation with either an access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS (IBSS) networks). + +**Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +  + +The miniport driver indicates the completion of the association operation through the [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication. Every NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION indication. + +For more information about the association operation, see [Association Operations](https://msdn.microsoft.com/library/windows/hardware/ff543789). + +The data type for this indication is the DOT11\_ASSOCIATION\_START\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_ASSOCIATION_START_PARAMETERS { + NDIS_OBJECT_HEADER Header; + DOT11_MAC_ADDRESS MacAddr; + DOT11_SSID SSID; + ULONG uIHVDataOffset; + ULONG uIHVDataSize; + } DOT11_ASSOCIATION_START_PARAMETERS, *PDOT11_ASSOCIATION_START_PARAMETERS; + +``` + +The DOT11\_ASSOCIATION\_START\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_ASSOCIATION\_START\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_ASSOCIATION\_START\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_ASSOCIATION\_START\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**MacAddr** +The media access control (MAC) address of the AP or peer station with which the 802.11 station attempted to associate. + +**Ssid** +The service set identifier (SSID) that the 802.11 station is attempting to associate with. + +If the **dot11DesiredBSSType** MIB object is set to **dot11\_BSS\_type\_independent**, the **Ssid** member must contain the same value that the **AdhocSSID** member used in the structures for previous [NDIS\_STATUS\_DOT11\_CONNECTION\_START](ndis-status-dot11-connection-start.md) and [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) indications. + +**uIHVDataOffset** +The offset of a block of data in a proprietary format that is defined by the IHV. The IHV can use this data block for any purpose that is related to the NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication. + +This offset is relative to the start of the buffer, which contains the DOT11\_ASSOCIATION\_ START\_PARAMETERS structure. + +If the miniport driver is not returning IHV data in the NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication, it must set **uIHVDataOffset** to zero. + +**uIHVDataSize** +The length of the block of data that is used by the IHV for the NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication. If the miniport driver is not returning IHV data in this indication, it must set **uIHVDataSize** to zero. + +The 802.11 station initiates an association operation when: + +- The 802.11 station is performing a connection operation. The miniport driver indicates the start of a connection operation by the [NDIS\_STATUS\_DOT11\_CONNECTION\_START](ndis-status-dot11-connection-start.md) indication. + + For more information about connection operations, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +- The 802.11 station is performing a roaming operation. The miniport driver indicates the start of a roaming operation by the [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) indication. + + For more information about the roaming operation, see [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +- A peer station in an IBSS network initiates an association with the 802.11 station. The IEEE 802.11 **dot11DesiredBSSType** MIB object must be set to **dot11\_BSS\_type\_independent**, and the 802.11 station must have joined the IBSS network in a previous connection or roaming operation. + + The 802.11 station can initiate this type of association operation outside of the scope of a connection or roaming operation. + + For more information about the **dot11DesiredBSSType** MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_ASSOCIATION\_START indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_ASSOCIATION\_START. + +- **StatusBuffer** must be set to the address of a DOT11\_ASSOCIATION\_START\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_ASSOCIATION\_START\_PARAMETERS). + +**Note**   +Before it initiates an association operation, the miniport driver must allocate all of the resources that it will need to make the corresponding [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_ASSOCIATION_START%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-can-sustain-ap.md b/windows-driver-docs-pr/network/ndis-status-dot11-can-sustain-ap.md new file mode 100644 index 0000000000..9b04407fc4 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-can-sustain-ap.md @@ -0,0 +1,87 @@ +--- +title: NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP +ms.assetid: da31f074-f2b3-4e06-80bf-1e4c442b6012 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_CAN_SUSTAIN_AP Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP status indication after the NIC stops an 802.11 access point (AP). + +The data type for this indication is the [**DOT11\_CAN\_SUSTAIN\_AP\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547671) structure. + +While the NIC is in the Extensible Station AP (ExtAP) mode, it could determine that it can no longer operate the AP on the current PHY. For example, if a PHY is operating in orthogonal frequency division multiplexing (OFDM) mode, radar signals might interfere with how the PHY changes frequency. + +If, because of these or similar circumstances, the NIC determines that it must stop AP operations, the miniport driver should perform the following operations: + +- Disassociate all peer stations from the AP. + +- Drop all pending frames. + +- Send all appropriate NDIS status indications to the operating system, which include [NDIS\_STATUS\_DOT11\_STOP\_AP](ndis-status-dot11-stop-ap.md). + +If the miniport driver receives an [OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) set request after it has indicated [NDIS\_STATUS\_DOT11\_STOP\_AP](ndis-status-dot11-stop-ap.md) but before it has indicated NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP, the driver should fail the OID request with a failure code of NDIS\_STATUS\_INVALID\_STATE. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure by using the *StatusIndication* parameter. When the driver makes this indication, it must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP. + +- **StatusBuffer** must be set to the address of a DOT11\_CAN\_SUSTAIN\_AP\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_CAN\_SUSTAIN\_AP\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_CAN\_SUSTAIN\_AP\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547671) + +[NDIS\_STATUS\_DOT11\_STOP\_AP](ndis-status-dot11-stop-ap.md) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_CAN_SUSTAIN_AP%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-connection-completion.md b/windows-driver-docs-pr/network/ndis-status-dot11-connection-completion.md new file mode 100644 index 0000000000..7ce3369b11 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-connection-completion.md @@ -0,0 +1,97 @@ +--- +title: NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION +author: windows-driver-content +description: A miniport driver must make an NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication after a connection operation completes. +ms.assetid: 85656517-28b4-4905-8f80-f83a0fde9028 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_CONNECTION_COMPLETION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication after a connection operation completes. + +The miniport driver indicates the start of the connection operation through the [NDIS\_STATUS\_DOT11\_CONNECTION\_START](ndis-status-dot11-connection-start.md) indication. Every NDIS\_STATUS\_DOT11\_CONNECTION\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication. + +For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +The data type for this indication is the DOT11\_CONNECTION\_COMPLETION\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_CONNECTION_COMPLETION_PARAMETERS { + NDIS_OBJECT_HEADER Header; + DOT11_ASSOC_STATUS uStatus; + } DOT11_CONNECTION_COMPLETION_PARAMETERS, *PDOT11_CONNECTION_COMPLETION_PARAMETERS; + +``` + +The DOT11\_CONNECTION\_COMPLETION\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_CONNECTION\_COMPLETION\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_CONNECTION\_COMPLETION\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_CONNECTION\_COMPLETION\_PARAMETER). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uStatus** +The completion status of the connection operation, as specified by a value defined for [**DOT11\_ASSOC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff547652). + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION. + +- **StatusBuffer** must be set to the address of a DOT11\_CONNECTION\_COMPLETION\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_CONNECTION\_COMPLETION\_PARAMETERS). + +The [NDIS\_STATUS\_DOT11\_CONNECTION\_START](ndis-status-dot11-connection-start.md) and NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indications define a connection operation that is performed by the 802.11 station. The miniport driver cannot make the NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication unless it has made an NDIS\_STATUS\_DOT11\_CONNECTION\_START indication at the beginning of the connection operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_CONNECTION_COMPLETION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-connection-start.md b/windows-driver-docs-pr/network/ndis-status-dot11-connection-start.md new file mode 100644 index 0000000000..378415fad3 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-connection-start.md @@ -0,0 +1,137 @@ +--- +title: NDIS\_STATUS\_DOT11\_CONNECTION\_START +author: windows-driver-content +description: A miniport driver must make an NDIS\_STATUS\_DOT11\_CONNECTION\_START indication after the set request of OID\_DOT11\_CONNECT\_REQUEST. +ms.assetid: 08602585-6ef9-4b9e-992f-5b16bd1855f0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_CONNECTION_START Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_CONNECTION\_START + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_CONNECTION\_START indication after the set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md). This indication defines the start of the connection operation, in which the 802.11 station attempts to connect to a basic service set (BSS) network. + +The miniport driver indicates the completion of the connection operation through the [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) indication. Every NDIS\_STATUS\_DOT11\_CONNECTION\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication. + +For more information about connection operations, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +The data type for this indication is the DOT11\_CONNECTION\_START\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_CONNECTION_START_PARAMETERS { + NDIS_OBJECT_HEADER Header; + DOT11_BSS_TYPE BSSType; + DOT11_MAC_ADDRESS AdhocBSSID; + DOT11_SSID AdhocSSID; + } DOT11_CONNECTION_START_PARAMETERS, *PDOT11_CONNECTION_START_PARAMETERS; + +``` + +The DOT11\_CONNECTION\_START\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_CONNECTION\_START\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_CONNECTION\_START\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_CONNECTION\_START\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**BssType** +The type of BSS network that the 802.11 station is connecting to. The data type for the **BssType** member is the [**DOT11\_BSS\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff547669) enumeration. + +The 802.11 station connects to a BSS type based on the setting of the IEEE 802.11 **dot11DesiredBssType** MIB object. For more information about this MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +**AdhocBSSID** +If **BssType** is set to **dot11\_BSS\_type\_independent**, the **AdhocBSSID** member contains the BSS identifier (BSSID) of the IBSS network that the 802.11 station will join or start. + +**Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +  + +If **BssType** is set to **dot11\_BSS\_type\_infrastructure**, the miniport driver must fill **AdhocBSSID** with zeros. + +For more information about the data type for this member, see [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681). + +**AdhocSSID** +If **BssType** is set to **dot11\_BSS\_type\_independent**, the **AdhocSSID** member contains the service set identifier (SSID) of the IBSS network that the 802.11 station will join or start. + +**Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +  + +If **BssType** is set to **dot11\_BSS\_type\_infrastructure**, the miniport driver must fill **AdhocSSID** with zeros. + +For more information about the data type for this member, see [**DOT11\_SSID**](https://msdn.microsoft.com/library/windows/hardware/ff548773). + +After the set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is made, the 802.11 station begins the connection operation by using the BSS parameters that were previously configured through set requests of Native 802.11 OIDs. The miniport driver begins the connection operation by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_CONNECTION\_START. + +- **StatusBuffer** must be set to the address of a DOT11\_CONNECTION\_START\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_CONNECTION\_START\_PARAMETERS). + +After the 802.11 station connects to a BSS network or has failed to connect to any BSS network, the miniport driver indicates the completion of the connection operation through an [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) indication. + +After the 802.11 station starts the connection operation, the miniport driver must complete the connection operation by making an [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) indication before it makes the following indications: + +- [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) + +- [NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION](ndis-status-dot11-roaming-completion.md) + +After the miniport driver makes the NDIS\_STATUS\_DOT11\_CONNECTION\_START indication, it cannot make another NDIS\_STATUS\_DOT11\_CONNECTION\_START indication until: + +- The miniport driver returns to the Extensible Station (ExtSTA) INIT mode through a set request of either [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) or [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +- A set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is made. + +Before it initiates a connection operation, the miniport driver must allocate all of the resources that it will need to make the corresponding [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) indication. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_CONNECTION_START%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-disassociation.md b/windows-driver-docs-pr/network/ndis-status-dot11-disassociation.md new file mode 100644 index 0000000000..29e2193398 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-disassociation.md @@ -0,0 +1,74 @@ +--- +title: NDIS\_STATUS\_DOT11\_DISASSOCIATION +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_DISASSOCIATION +ms.assetid: 5945f733-6b06-430a-863f-4ba82cff2dbe +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_DISASSOCIATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_DISASSOCIATION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_DISASSOCIATION indication if the 802.11 station performs a disassociation operation with either an access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS (IBSS) networks). For more information about disassociation operations, see [Disassociation Operations](https://msdn.microsoft.com/library/windows/hardware/ff546439). + +The data type for this indication is the [**DOT11\_DISASSOCIATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547682) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_DISASSOCIATION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_DISASSOCIATION. + +- **StatusBuffer** must be set to the address of a DOT11\_DISASSOCIATION\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_DISASSOCIATION\_PARAMETERS). + +The miniport driver can make the NDIS\_STATUS\_DOT11\_DISASSOCIATION indication only after it has completed an association operation with an AP or peer station that is identified by the **MacAddr** member. The miniport driver indicates the completion of an association operation through the [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication. For more information about the association operation, see [Association Operations](https://msdn.microsoft.com/library/windows/hardware/ff543789). + +After the miniport driver makes the NDIS\_STATUS\_DOT11\_DISASSOCIATION indication and if the IEEE 802.11 **dot11DesiredBssType** MIB object is set to **dot11\_BSS\_type\_infrastucture**, the 802.11 station must do the following: + +- If the **uReason** member was set to DOT11\_DISASSOC\_REASON\_OS, the 802.11 station must not attempt to roam or associate with any AP in the BSS. The miniport driver must transition to the ExtSTA INIT operation mode. The 802.11 station must also wait until the next set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) before attempting an association operation. + +- If the **uReason** member was not set to DOT11\_DISASSOC\_REASON\_OS, the 802.11 station must attempt to roam to other APs within the basic service set (BSS) that the station was previously associated with. + + For more information about the roaming operation, see [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +For more information about the **dot11DesiredBssType** MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_DISASSOCIATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-completion.md b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-completion.md new file mode 100644 index 0000000000..2a9fb602a6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-completion.md @@ -0,0 +1,77 @@ +--- +title: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION +ms.assetid: 4238212d-b4e8-4e65-8b09-4ccc2c0e5569 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_INCOMING_ASSOC_COMPLETION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION status indication after the following events: + +- The NIC successfully sends an association response frame to a peer station on an infrastructure BSS that originally sent an association request. + +- The association is successful and the NIC successfully sends the corresponding association response frame to the peer station that originally requested the association. + +- The association fails, regardless of whether the response is sent successfully or not. The failure can be because the NIC or operating system reject the association request or because of a failure not related to the 802.11 framework. + +The data type for this indication is the [**DOT11\_INCOMING\_ASSOC\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548650) structure. + +The NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION status indication marks the end of an *association indication block*, which denotes the time between NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED and NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION indications when a NIC is operating in ExtAP OP mode. Every NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION indication. + +A peer station cannot have multiple overlapping incoming association indication blocks. Incoming association indication blocks for different peer stations can overlap. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When the driver makes this indication, it must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION.\] + +- **StatusBuffer** must be set to the address of a DOT11\_INCOMING\_ASSOC\_COMPLETION\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_INCOMING\_ASSOC\_COMPLETION\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INCOMING\_ASSOC\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548650) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_INCOMING_ASSOC_COMPLETION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-request-received.md b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-request-received.md new file mode 100644 index 0000000000..a72a2ea008 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-request-received.md @@ -0,0 +1,71 @@ +--- +title: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED +ms.assetid: 03210984-acf8-40b7-8414-1b984cef9dc7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_INCOMING_ASSOC_REQUEST_RECEIVED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED status indication after the NIC receives an incoming association request frame from a peer station on an infrastructure BSS. + +The data type for this indication is the [**DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548655) structure. + +The NIC should validate the association request and determine whether to accept the request, following IEEE 802.11 standards. The NIC can also use its own proprietary logic to examine proprietary fields in the request. The miniport driver should issue this indication after it and the NIC have validated the association request and have accepted the request based on their own internal logic. When the operating system receives this indication, it assumes that the NIC has accepted the association request. + +If the association request packet is not valid, or if the NIC decides to reject the request, the NIC should send an association response packet that rejects the request and should not present this indication to the operating system. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED. + +- **StatusBuffer** must be set to the address of a DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED\_PARAMETERS) + AssociationRequest\_Frame\_size. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INCOMING\_ASSOC\_REQUEST\_RECEIVED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548655) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_INCOMING_ASSOC_REQUEST_RECEIVED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-started.md b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-started.md new file mode 100644 index 0000000000..8584492982 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-incoming-assoc-started.md @@ -0,0 +1,79 @@ +--- +title: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED +ms.assetid: 57fd84ea-9f74-40d9-9ce9-1193edd021c9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_INCOMING_ASSOC_STARTED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED status indication when the NIC receives the first valid 802.11 authentication request from a peer station on an infrastructure BSS. + +A miniport driver can also make this indication when it receives a valid re-association request packet from a peer station that is in an authenticated (class 2) state. + +The data type for this indication is the [**DOT11\_INCOMING\_ASSOC\_STARTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548663) structure. + +The miniport driver must not make this indication when the received association request is not valid, or if the peer station's association state is not valid. + +This indication marks the beginning of an *association indication block*, which denotes the time between NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED and NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION indications when a NIC is operating in ExtAP OP mode. Every NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_COMPLETION indication. + +A peer station cannot have multiple overlapping incoming association indication blocks. Incoming association indication blocks for different peer stations can overlap. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When the driver makes this indication, it must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_INCOMING\_ASSOC\_STARTED. + +- **StatusBuffer** must be set to the address of a DOT11\_INCOMING\_ASSOC\_STARTED\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_INCOMING\_ASSOC\_STARTED\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INCOMING\_ASSOC\_STARTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548663) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_INCOMING_ASSOC_STARTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-link-quality.md b/windows-driver-docs-pr/network/ndis-status-dot11-link-quality.md new file mode 100644 index 0000000000..96d32f1c04 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-link-quality.md @@ -0,0 +1,133 @@ +--- +title: NDIS\_STATUS\_DOT11\_LINK\_QUALITY +author: windows-driver-content +description: A miniport driver makes the NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication whenever the link quality of the association with an access point (AP) or peer station changes. +ms.assetid: 911397fd-e898-4970-9a1b-7baf57e16687 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_LINK_QUALITY Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_LINK\_QUALITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver makes the NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication whenever the link quality of the association with an access point (AP) or peer station changes. + +The data type for this indication is the DOT11\_LINK\_QUALITY\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_LINK_QUALITY_PARAMETERS { + NDIS_OBJECT_HEADER Header; + ULONG uLinkQualityListSize; + ULONG uLinkQualityListOffset; + } DOT11_LINK_QUALITY_PARAMETERS, *PDOT11_LINK_QUALITY_PARAMETERS; + +``` + +The DOT11\_LINK\_QUALITY\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_LINK\_QUALITY\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_LINK\_QUALITY\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_LINK\_QUALITY\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uLinkQualityListSize** +The number of entries in the link quality list. + +**uLinkQualityListOffset** +The offset of the link quality list. Each entry in the list specifies an association to an AP or peer station whose link quality has changed. + +This offset is relative to the start of the buffer that contains the DOT11\_LINK\_QUALITY\_PARAMETERS structure. + +Each entry in the link quality list is formatted as a DOT11\_LINK\_QUALITY\_ENTRY structure: + +``` syntax +typedef struct DOT11_LINK_QUALITY_ENTRY { DOT11_MAC_ADDRESS PeerMacAddr; + UCHAR + ucLinkQuality; } DOT11_LINK_QUALITY_ENTRY, *PDOT11_LINK_QUALITY_ENTRY; +``` + +The DOT11\_LINK\_QUALITY\_ENTRY structure contains the following members: + +**PeerMacAddr** +The media access control (MAC) address of the AP or peer station with which the link quality has changed. This member is formatted as a [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +**ucLinkQuality** +The link quality of the association, specified by a value within the range from 0 through 100. + +The miniport driver must follow these guidelines when making the NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication: + +- After the 802.11 station successfully associates with an AP or peer station, the miniport driver must make an NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication shortly after it makes the [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication. The miniport driver makes this NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication after it has determined the initial link quality of the association. + +- The miniport driver makes the Native 802.11 NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication whenever the 802.11 station determines that the link quality to an associated AP or peer station has changed significantly since the last NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication. + + The determination for making this indication is specific to the implementation by the independent hardware vendor (IHV). However, the miniport driver should implement some threshold mechanism to avoid making frequent indications. + +- Following each NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication, the miniport driver must save the current link quality for each associated AP or peer station specified within the link quality list. + +- If the 802.11 station is connected to an independent basic service set (IBSS) network, the miniport driver can include entries in the link quality list for every associated peer station whose link quality has changed significantly since the last NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication. + + **Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +   + + If the 802.11 station is connected to an infrastructure BSS network, the link quality list must only contain an entry for the AP with which the 802.11 station is associated. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_LINK\_QUALITY indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_LINK\_QUALITY. + +- **StatusBuffer** must be set to the address of a DOT11\_LINK\_QUALITY\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_LINK\_QUALITY\_PARAMETERS) plus the values of the **uLinkQualityListSize** and **uLinkQualityListOffset** members. + +For more information about link quality and link quality indications, see [Link Quality Operations](https://msdn.microsoft.com/library/windows/hardware/ff557056). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_LINK_QUALITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-mpdu-max-length-changed.md b/windows-driver-docs-pr/network/ndis-status-dot11-mpdu-max-length-changed.md new file mode 100644 index 0000000000..fc99b7b6c5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-mpdu-max-length-changed.md @@ -0,0 +1,104 @@ +--- +title: NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED +author: windows-driver-content +description: A miniport driver must make an NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED indication after the maximum media access control (MAC) protocol data unit (MPDU) frame size is changed for a PHY on the 802.11 station. +ms.assetid: 208e2a28-84c6-4c0f-85b1-fd572412ab19 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_MPDU_MAX_LENGTH_CHANGED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED indication after the maximum media access control (MAC) protocol data unit (MPDU) frame size is changed for a PHY on the 802.11 station. + +The data type for this indication is the DOT11\_MPDU\_MAX\_LENGTH\_INDICATION structure: + +```ManagedCPlusPlus + typedef struct _DOT11_MPDU_MAX_LENGTH_INDICATION { + NDIS_OBJECT_HEADER Header; + ULONG uPhyId; + ULONG uMPDUMaxLength; + } DOT11_MPDU_MAX_LENGTH_INDICATION, *PDOT11_MPDU_MAX_LENGTH_INDICATION; + +``` + +The DOT11\_MPDU\_MAX\_LENGTH\_INDICATION structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_MPDU\_MAX\_LENGTH\_INDICATION structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_MPDU\_MAX\_LENGTH\_INDICATION\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_MPDU\_MAX\_LENGTH\_INDICATION). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uPhyId** +The identifier (ID) of the PHY on which the maximum MPDU length was changed. The PHY ID is the index within the list of supported PHYs that are returned by the driver through a query of [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +The **uPhyId** member is applicable only for miniport drivers that operate in Extensible Station (ExtSTA) mode. + +**uMPDUMaxLength** +The new maximum length for MPDU frames that are supported by the PHY that is identified by the **uPhyId** member. + +The **uMPDUMaxLength** member is applicable only for miniport drivers that operate in Extensible Station (ExtSTA) mode. For more information about the ExtSTA operation mode, see [Extensible Station Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff549887). + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. + +When making this indication, the miniport driver must set the members of the NDIS\_STATUS\_INDICATION structure to the following values: + +**StatusCode** +This member must be set to NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED. + +**StatusBuffer** +This memer must be set to the address of a DOT11\_MPDU\_MAX\_LENGTH\_INDICATION structure. + +**StatusBufferSize** +This member must be set to sizeof(DOT11\_MPDU\_MAX\_LENGTH\_INDICATION). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_MPDU_MAX_LENGTH_CHANGED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-phy-frequency-adopted.md b/windows-driver-docs-pr/network/ndis-status-dot11-phy-frequency-adopted.md new file mode 100644 index 0000000000..2e2d190039 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-phy-frequency-adopted.md @@ -0,0 +1,77 @@ +--- +title: NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED +ms.assetid: f723fa8d-702c-48dd-9a66-7532cc476257 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_PHY_FREQUENCY_ADOPTED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED status indication after it has adopted a channel or frequency to communicate with a peer station on an infrastructure BSS. This indication must be made any time the NIC adopts a new channel or frequency or has started an AP. + +The data type for this indication is the [**DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548735) structure. + +The NIC should treat the available operating channels or frequencies returned by [OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST](oid-dot11-available-channel-list.md) and [OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST](oid-dot11-available-frequency-list.md) as suggestions. The NIC is free to adopt its own channel or frequency that meets the local regulatory domain. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When the driver makes this indication, it must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_PHY\_FREQUENCY\_ADOPTED. + +- **StatusBuffer** must be set to the address of a DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548735) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST](oid-dot11-available-channel-list.md) + +[OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST](oid-dot11-available-frequency-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_PHY_FREQUENCY_ADOPTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-phy-state-changed.md b/windows-driver-docs-pr/network/ndis-status-dot11-phy-state-changed.md new file mode 100644 index 0000000000..1c9b86c52c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-phy-state-changed.md @@ -0,0 +1,107 @@ +--- +title: NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED +author: windows-driver-content +description: A miniport driver must make the NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED indication whenever the hardware or software power state of a PHY changes on the 802.11 station. +ms.assetid: 276fb352-f355-4047-adce-ef9e51b5c1b7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_PHY_STATE_CHANGED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make the NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED indication whenever the hardware or software power state of a PHY changes on the 802.11 station. + +The data type for this indication is the DOT11\_PHY\_STATE\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_PHY_STATE_PARAMETERS { + NDIS_OBJECT_HEADER Header; + ULONG uPhyId; + BOOLEAN bHardwarePhyState; + BOOLEAN bSoftwarePhyState; + } DOT11_PHY_STATE_PARAMETERS, *PDOT11_PHY_STATE_PARAMETERS; + +``` + +The DOT11\_PHY\_STATE\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_PHY\_STATE\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_PHY\_STATE\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_PHY\_STATE\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uPhyId** +The PHY identifier (ID) of the PHY whose state has changed. + +The PHY ID is an index into the table of supported PHYs that are specified by the Native 802.11 Operational **msDot11SupportedPhyTypes** MIB object. For more information about PHY IDs and the **msDot11SupportedPhyTypes** MIB object, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +If the **uPhyId** member is set to DOT11\_PHY\_ID\_ANY, the NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED indication applies to all PHYs in the **msDot11SupportedPhyTypes** MIB object. + +**bHardwarePhyState** +A Boolean value that specifies the hardware power state of the PHY that is referenced by **uPhyId**. If **TRUE**, the hardware power state is enabled. If **FALSE**, the hardware power state is disabled. + +For more information about the PHY's hardware power state, see [OID\_DOT11\_HARDWARE\_PHY\_STATE](oid-dot11-hardware-phy-state.md). + +**bSoftwarePhyState** +A Boolean value that specifies the software power state of the PHY that is referenced by **uPhyId**. If **TRUE**, the software power state is enabled. If **FALSE**, the software power state is disabled. + +For more information about the PHY's software power state, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED. + +- **StatusBuffer** must be set to the address of a DOT11\_PHY\_STATE\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_PHY\_STATE\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_PHY_STATE_CHANGED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-pmkid-candidate-list.md b/windows-driver-docs-pr/network/ndis-status-dot11-pmkid-candidate-list.md new file mode 100644 index 0000000000..9d52ae7da9 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-pmkid-candidate-list.md @@ -0,0 +1,157 @@ +--- +title: NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST +author: windows-driver-content +description: A miniport driver uses the NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication to request pairwise master key identifiers (PMKIDs) for basic service set (BSS) identifiers (BSSIDs) that the 802.11 station can potentially roam to. +ms.assetid: 5c0376f3-71e3-4fa6-89e5-6580fc85cfa8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver uses the NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication to request pairwise master key identifiers (PMKIDs) for basic service set (BSS) identifiers (BSSIDs) that the 802.11 station can potentially roam to. When roaming, the 802.11 station uses the PMKID value to pre-authenticate with an access point (AP). + +The data type for this indication is the DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_PMKID_CANDIDATE_LIST_PARAMETERS { + NDIS_OBJECT_HEADER Header; + ULONG uCandidateListSize; + ULONG uCandidateListOffset; + } DOT11_PMKID_CANDIDATE_LIST_PARAMETERS, *PDOT11_PMKID_CANDIDATE_LIST_PARAMETERS; + +``` + +The DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uCandidateListSize** +The size, in bytes, of the list of BSSID candidates for PMKIDs. + +**uCandidateListOffset** +The offset of the BSSID candidate list. + +This offset is relative to the start of the buffer that contains the DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS structure. + +Each entry in the BSSID candidate list is formatted as a DOT11\_BSSID\_CANDIDATE structure: + +``` syntax +typedef struct DOT11_BSSID_CANDIDATE { + DOT11_MAC_ADDRESS BSSID; + ULONG uFlags; + } DOT11_BSSID_CANDIDATE, *PDOT11_BSSID_CANDIDATE; +``` + +The DOT11\_BSSID\_CANDIDATE structure contains the following members: + +**BSSID** +The BSSID of the AP for which the miniport driver is requesting a PMKID. + +BSSID candidates that are specified by the **BSSID** member must: + +- Be in the service set identifier (SSID) that the 802.11 station is currently associated with. + +- Match an entry in the desired BSSID list that is defined by the Extensible Station (ExtSTA) **msDot11DesiredBSSIDList** MIB object. For more information about this MIB object, see [OID\_DOT11\_DESIRED\_BSSID\_LIST](oid-dot11-desired-bssid-list.md). + +- Be a member of the SSID with which the 802.11 station is currently associated and authenticated with. + +**Note**  The miniport can only request a PMKID for the AP with which the 802.11 station is currently associated. + +  + +**uFlags** +A bitmask that specifies pre-authentication attributes of the BSSID candidates. This bitmask is defined as follows: + +DOT11\_PMKID\_CANDIDATE\_PREAUTH\_ENABLED +The BSSID candidate supports pre-authentication. The BSSID candidate advertises its support for pre-authentication by setting the Pre-authentication Subfield of the RSN Capabilities field to one in the 802.11 Beacon and Probe Response frames that the BSSID candidate transmits. + +If the DOT11\_PMKID\_CANDIDATE\_PREAUTH\_ENABLED bit is set, the 802.1X supplicant will initiate the 802.1X pre-authentication with the specified BSSID candidate. + +If the DOT11\_PMKID\_CANDIDATE\_PREAUTH\_ENABLED bit is not set, pre-authentication cannot be performed with the BSSID candidate. However, the 802.1X supplicant can update the driver's PMKID cache by using the PMK from a prior association with the BSSID candidate. + +Pre-authentication applies to infrastructure networks that support Robust Security Network Association (RSNA) authentication. For more information about RSNA authentication, refer to Clause 8.4.6 of the IEEE 802.11i-2004 standard. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST. + +- **StatusBuffer** must be set to the address of a DOT11\_LINK\_QUALITY\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_PMKID\_CANDIDATE\_LIST\_PARAMETERS) plus the values of the **uCandidateListSize** and **uCandidateListoffset** members. + +The miniport driver can make the NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication only if: + +- The IEEE 802.11 **dot11DesiredBSSType** MIB object is set to **dot11\_BSS\_type\_infrastructure**. For more information about this MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +- The 802.11 station has associated with a BSS that supports RSNA authentication. + +When it makes the NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication, the miniport driver must do the following: + +- Order the PMKID candidate list from most preferred to least preferred. + + The miniport driver can use any criteria to define the preference order. For example, the miniport driver can order the PMKID candidate list based on RSSI strength. + +- Set the number of entries in the PMKID candidate list to a value less than or equal to the value of **uPMKIDCacheSize**, which the driver returned when [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md) was previously queried. + +- Be associated with an RSNA-capable AP and have transferred cipher keys to the 802.11 station through set requests of [OID\_DOT11\_CIPHER\_DEFAULT\_KEY](oid-dot11-cipher-default-key.md) or [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md). + +**Note**  The miniport must make an NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication within one minute after it has completed the association with the AP and the cipher keys have been transferred to the 802.11 station. + +  + +While the 802.11 station is associated with the AP, the miniport driver may generate additional NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indications if the BSSID candidate list changes. The driver should keep the frequency of these indications to a minimum. For example, the driver should not make an NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST indication if only one new entry was added to its BSSID candidate list. Instead, it must make the indication after the number of new entries inserted into its BSSID candidate list reaches a driver-specific threshold. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-roaming-completion.md b/windows-driver-docs-pr/network/ndis-status-dot11-roaming-completion.md new file mode 100644 index 0000000000..89ae32b599 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-roaming-completion.md @@ -0,0 +1,68 @@ +--- +title: NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION +ms.assetid: 7effcce4-e557-4255-92d4-8a1c0b3bda61 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_ROAMING_COMPLETION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver makes an NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indication after the 802.11 station completes a roaming operation. + +The miniport driver indicates the start of the roaming operation through the [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) indication. Every NDIS\_STATUS\_DOT11\_ROAMING\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indication. + +For more information about the roaming operation, see [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +The data type for this indication is the [**DOT11\_ROAMING\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548762) structure. + +The [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) and NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indications define a roaming operation that is performed by the 802.11 station. The miniport driver cannot make the NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indication unless it has made an NDIS\_STATUS\_DOT11\_ROAMING\_START indication at the beginning of the roaming operation. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION. + +- **StatusBuffer** must be set to the address of a DOT11\_ROAMING\_COMPLETION\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_ROAMING\_COMPLETION\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_ROAMING_COMPLETION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-roaming-start.md b/windows-driver-docs-pr/network/ndis-status-dot11-roaming-start.md new file mode 100644 index 0000000000..c8400f851f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-roaming-start.md @@ -0,0 +1,70 @@ +--- +title: NDIS\_STATUS\_DOT11\_ROAMING\_START +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_ROAMING\_START +ms.assetid: ff8f5d8f-b094-4f9b-bf5d-e92c2d5650f2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_ROAMING_START Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_ROAMING\_START + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver makes an NDIS\_STATUS\_DOT11\_ROAMING\_START indication before the 802.11 station begins a roaming operation. + +The miniport driver indicates the completion of the roaming operation through the [NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION](ndis-status-dot11-roaming-completion.md) indication. Every NDIS\_STATUS\_DOT11\_ROAMING\_START indication made by the driver must have a corresponding NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION indication. + +For more information about the roaming operation, see [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +The data type for this indication is the [**DOT11\_ROAMING\_START\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548764) structure: + +The miniport driver can make the NDIS\_STATUS\_DOT11\_ROAMING\_START indication only after it has completed a connection operation with a BSS network. For more information about connection operations, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +Before it initiates a roaming operation, the miniport driver must allocate all of the resources that it will need to make the corresponding [NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION](ndis-status-dot11-roaming-completion.md) indication. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_ROAMING\_START indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_ROAMING\_START. + +- **StatusBuffer** must be set to the address of a DOT11\_ROAMING\_START\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_ROAMING\_START\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_ROAMING_START%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-scan-confirm.md b/windows-driver-docs-pr/network/ndis-status-dot11-scan-confirm.md new file mode 100644 index 0000000000..b815d673a3 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-scan-confirm.md @@ -0,0 +1,60 @@ +--- +title: NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM +ms.assetid: 065055c1-8fa5-46ac-827b-47e79670d10f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_SCAN_CONFIRM Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM indication after the 802.11 station completes an explicit scan operation that is initiated through a set request of [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM. + +- **StatusBuffer** must be set to the address of a ULONG variable, which stores the appropriate NDIS\_STATUS\_xxxx code for the result of the scan operation. + +- **StatusBufferSize** must be set to sizeof(ULONG). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_SCAN_CONFIRM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-stop-ap.md b/windows-driver-docs-pr/network/ndis-status-dot11-stop-ap.md new file mode 100644 index 0000000000..3074cdc34e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-stop-ap.md @@ -0,0 +1,87 @@ +--- +title: NDIS\_STATUS\_DOT11\_STOP\_AP +author: windows-driver-content +description: NDIS\_STATUS\_DOT11\_STOP\_AP +ms.assetid: b35e6280-72cd-470b-a3c3-31136f8961cf +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_STOP_AP Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_STOP\_AP + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_STOP\_AP status indication when the NIC cannot sustain 802.11 access point (AP) functionality on any of the available PHYs. The driver should send this indication only after the NIC has stopped any APs that are operating on the available PHYs. + +The data type for this indication is the [**DOT11\_STOP\_AP\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548783) structure. + +While the NIC is in the Extensible Station AP (ExtAP) mode, it could determine that it can no longer operate the AP on the current PHY. For example, if a PHY is operating in orthogonal frequency division multiplexing (OFDM) mode, radar signals might interfere with how the PHY changes frequency. + +If, because of these or similar circumstances, the NIC determines that it must stop AP operations, the miniport driver should perform the following operations: + +- Disassociate all peer stations from the AP. + +- Drop all pending frames. + +- Send all appropriate NDIS status indications to the operating system, which includes NDIS\_STATUS\_DOT11\_STOP\_AP. + +After the miniport driver has performed these actions, it must send an [NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP](ndis-status-dot11-can-sustain-ap.md) status indication to indicate that it is ready to receive an [OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) request to start the AP again. + +If the miniport driver receives an [OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) set request after it has indicated NDIS\_STATUS\_DOT11\_STOP\_AP but before it has indicated [NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP](ndis-status-dot11-can-sustain-ap.md), the driver should fail the OID request with a failure code of NDIS\_STATUS\_INVALID\_STATE. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_STOP\_AP indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure by using the *StatusIndication* parameter. When the driver makes this indication, it must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_STOP\_AP. + +- **StatusBuffer** must be set to the address of a DOT11\_STOP\_AP\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_STOP\_AP\_PARAMETERS). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_STOP\_AP\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548783) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_STOP_AP%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-tkipmic-failure.md b/windows-driver-docs-pr/network/ndis-status-dot11-tkipmic-failure.md new file mode 100644 index 0000000000..abc5f879ee --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-tkipmic-failure.md @@ -0,0 +1,105 @@ +--- +title: NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE +author: windows-driver-content +description: A miniport driver uses the NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE indication whenever a received packet, successfully decrypted by the TKIP cipher algorithm, fails the message integrity code (MIC) verification. +ms.assetid: bd1b010f-e5d0-4d51-917f-3a6065c932f6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_DOT11_TKIPMIC_FAILURE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver uses the NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE indication whenever a received packet, successfully decrypted by the TKIP cipher algorithm, fails the message integrity code (MIC) verification. + +The data type for this indication is the DOT11\_TKIPMIC\_FAILURE\_PARAMETERS structure: + +```ManagedCPlusPlus + typedef struct DOT11_TKIPMIC_FAILURE_PARAMETERS { + NDIS_OBJECT_HEADER Header; + BOOLEAN bDefaultKeyFailure; + ULONG uKeyIndex; + DOT11_MAC_ADDRESS PeerMac; + } DOT11_TKIPMIC_FAILURE_PARAMETERS, *PDOT11_TKIPMIC_FAILURE_PARAMETERS; + +``` + +The DOT11\_TKIPMIC\_FAILURE\_PARAMETERS structure contains the following members: + +**Header** +The type, revision, and size of the DOT11\_TKIPMIC\_FAILURE\_PARAMETERS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_TKIPMIC\_FAILURE\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_TKIPMIC\_FAILURE\_PARAMETERS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**bDefaultKeyFailure** +A Boolean value that indicates which cipher key type detected the TKIP-MIC failure occurred. If **TRUE**, the TKIP-MIC failure was detected through a default cipher key. For more information about default cipher keys, see [OID\_DOT11\_CIPHER\_DEFAULT\_KEY](oid-dot11-cipher-default-key.md). + +If **FALSE**, the TKIP-MIC failure was detected through a key mapping cipher key. For more information about key mapping cipher keys, see [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md). + +**uKeyIndex** +The index of the cipher key in the default key array. The value of **uKeyIndex** must be from 0 through 3. + +The **uKeyIndex** member is valid only if the **bDefaultKeyFailure** member is **TRUE**. The miniport driver must set **uKeyIndex** to zero if **bDefaultKeyFailure** is **FALSE**. + +**PeerMac** +The media access control (MAC) address of the access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS (IBSS) networks) that transmitted the packet that failed MIC verification. If the NIC is in Extensible Access Point (ExtAP) mode, this member contains the MAC address of the associated peer station that transmitted the packet that failed MIC verification. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the driver must set the following members of the NDIS\_STATUS\_INDICATION structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_TKIPMIC\_FAILURE. + +- **StatusBuffer** must be set to the address of a DOT11\_TKIPMIC\_FAILURE\_PARAMETERS structure. + +- **StatusBufferSize** must be set to sizeof(DOT11\_TKIPMIC\_FAILURE\_PARAMETERS). + +The operating system will consume this indication and determine whether and how TKIP countermeasures are invoked. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systemss.

Header

Windot11.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_TKIPMIC_FAILURE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-discover-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-discover-complete.md new file mode 100644 index 0000000000..fa9391f5a5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-discover-complete.md @@ -0,0 +1,75 @@ +--- +title: NDIS_STATUS_DOT11_WFD_DISCOVER_COMPLETE +author: windows-driver-content +description: NDIS_STATUS_DOT11_WFD_DISCOVER_COMPLETE +ms.assetid: 82836F84-BA52-4705-B077-E19D03321E24 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_DISCOVER_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +A miniport driver must make an NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE indication after a Wi-Fi Direct (WFD) device discovery operation completes. A discover operation is initiated by an [OID\_DOT11\_WFD\_DISCOVER\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451795) request. + +The data type for this indication is the [**DOT11\_WFD\_DISCOVER\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464148) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_WFD\_DISCOVER\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464148) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_WFD\_DISCOVER\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464148) and the size of the list of discovered devices. + +The discover completion indication must not include more than **DOT11\_WFD\_DISCOVER\_COMPLETE\_MAX\_LIST\_SIZE** entries. If more devices were recently discovered, the miniport should populate the completion structure to the maximum list size and use the **uTotalNumOfEntries** member of [**DOT11\_WFD\_DISCOVER\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464148) to specify the total number of discovered devices. The system may query for the full list later by issuing [OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](https://msdn.microsoft.com/library/windows/hardware/hh451796). + +The miniport must include both WFD devices and legacy networks in the list of reported devices. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_WFD\_DISCOVER\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464148) + +[OID\_DOT11\_WFD\_DISCOVER\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451795) + +[OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](https://msdn.microsoft.com/library/windows/hardware/hh451796) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_DISCOVER_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-confirmation-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-confirmation-send-complete.md new file mode 100644 index 0000000000..61d896e729 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-confirmation-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_CONFIRMATION_SEND_COMPLETE +author: windows-driver-content +ms.assetid: F7812F92-B1B3-41BE-9656-64882891CB1C +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_CONFIRMATION_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of a Group Owner (GO) negotiation confirmation transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE indication. A GO negotiation confirmation is initiated by an [OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_COMFIRMATION](https://msdn.microsoft.com/library/windows/hardware/hh451803) OID. + +The data type for this indication is the [**DOT11\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/jj879310) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/jj879310) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/jj879310) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/jj879310) + +[OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_COMFIRMATION](https://msdn.microsoft.com/library/windows/hardware/hh451803) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_CONFIRMATION_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-request-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-request-send-complete.md new file mode 100644 index 0000000000..8fddce04a5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-request-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_REQUEST_SEND_COMPLETE +author: windows-driver-content +ms.assetid: 050B9065-8ADD-488F-8A2C-7CA5F64DC61A +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_REQUEST_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of a Group Owner (GO) negotiation request transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE indication. A GO negotiation request is initiated by an [OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451804) OID. + +The data type for this indication is the [**DOT11\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464142) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464142) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464142) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464142) + +[OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451804) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_REQUEST_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-response-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-response-send-complete.md new file mode 100644 index 0000000000..24e3decfc6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-go-negotiation-response-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_RESPONSE_SEND_COMPLETE +author: windows-driver-content +ms.assetid: C919BACF-A8E5-4D97-BDC9-DCBFF914C3C8 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_RESPONSE_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of a Group Owner (GO) negotiation response transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE indication. A GO negotiation response is initiated by an [OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451805) OID. + +The data type for this indication is the [**DOT11\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406475) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406475) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406475) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406475) + +[OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451805) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_GO_NEGOTIATION_RESPONSE_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-request-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-request-send-complete.md new file mode 100644 index 0000000000..bb90fd0a6d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-request-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_INVITATION_REQUEST_SEND_COMPLETE +author: windows-driver-content +ms.assetid: 8BAD2F9D-F518-43DF-A7DE-95E707EAB5D5 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_INVITATION_REQUEST_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of an invitation request transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE indication. An invitation request is initiated by an [OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451806) OID. + +The data type for this indication is the [**DOT11\_INVITATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406484) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_INVITATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406484) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_INVITATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406484) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INVITATION\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406484) + +[OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh451806) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_INVITATION_REQUEST_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-response-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-response-send-complete.md new file mode 100644 index 0000000000..b086790a94 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-invitation-response-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_INVITATION_RESPONSE_SEND_COMPLETE +author: windows-driver-content +ms.assetid: 0603C386-8EFD-475E-B82E-F35D2B5DFC0F +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_INVITATION_RESPONSE_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of an invitation response transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE indication. An invitation response is initiated by an [OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) OID. + +The data type for this indication is the [**DOT11\_INVITATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406488) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_INVITATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406488) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_INVITATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406488) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INVITATION\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406488) + +[OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_INVITATION_RESPONSE_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-request-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-request-send-complete.md new file mode 100644 index 0000000000..d31225fee6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-request-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_REQUEST_SEND_COMPLETE +author: windows-driver-content +ms.assetid: CC33C6B0-BD64-421C-B357-8154EF0962CC +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_REQUEST_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of a provision discovery request transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE indication. A provision discovery request is initiated by an [OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh464156) OID. + +The data type for this indication is the [**DOT11\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406512) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406512) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406512) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406512) + +[OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh464156) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_REQUEST_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-response-send-complete.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-response-send-complete.md new file mode 100644 index 0000000000..7317013328 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-provision-discovery-response-send-complete.md @@ -0,0 +1,69 @@ +--- +title: NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_RESPONSE_SEND_COMPLETE +author: windows-driver-content +ms.assetid: D3A4CD1B-51E0-4BA8-8D49-B0FD5D72F48F +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_RESPONSE_SEND_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of a provision discovery reponse transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE indication. A provision discovery response is initiated by an [OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451808) OID. + +The data type for this indication is the [**DOT11\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406515) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to [NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_REQUEST\_SEND\_COMPLETE](ndis-status-dot11-wfd-provision-discovery-request-send-complete.md). + +- **StatusBuffer** must be set to the address of a [**DOT11\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406515) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406515) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406515) + +[OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451808) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_PROVISION_DISCOVERY_RESPONSE_SEND_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-confirmation.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-confirmation.md new file mode 100644 index 0000000000..94f93b2826 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-confirmation.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_CONFIRMATION +author: windows-driver-content +ms.assetid: D5FF9BDD-D359-40A1-9076-518296ECE3A4 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_CONFIRMATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of a Group Owner (GO) negotiation confirmation packet from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406518) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406518) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406518) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406518) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_CONFIRMATION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-request.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-request.md new file mode 100644 index 0000000000..7ad5246757 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-request.md @@ -0,0 +1,71 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_REQUEST +author: windows-driver-content +ms.assetid: FBDEC5E5-EE4D-4F22-923B-D9DB7035095E +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_REQUEST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of a Group Owner (GO) negotiation request from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406519) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406519) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406519) and the size of the list of returned Information Elements (IEs). + +After receiving the status indication, the system will determine the appropriate response for the GO negotiation request. The system may then send [OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) OID to the driver for creation and transmission of the GO negotiation response. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406519) + +[OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_REQUEST%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-response.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-response.md new file mode 100644 index 0000000000..4771f44ad9 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-go-negotiation-response.md @@ -0,0 +1,71 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_RESPONSE +author: windows-driver-content +ms.assetid: BBC795A2-719E-4519-BBA3-0E9B557771FB +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_RESPONSE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of a Group Owner (GO) negotiation response from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406524) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406524) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406524) and the size of the list of returned Information Elements (IEs). + +After receiving the status indication, the system will determine the appropriate reply for the GO negotiation reply. The system may then send [OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION](https://msdn.microsoft.com/library/windows/hardware/hh451807) OID to the driver for creation and transmission of the GO negotiation confirmation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406524) + +[OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION](https://msdn.microsoft.com/library/windows/hardware/hh451807) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_GO_NEGOTIATION_RESPONSE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-request.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-request.md new file mode 100644 index 0000000000..4044efb6ce --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-request.md @@ -0,0 +1,71 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_REQUEST +author: windows-driver-content +ms.assetid: F279D2A3-3381-4579-AFAE-B4F37D9DF814 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_REQUEST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of an invitation request from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406528) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406528) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406528) and the size of the list of returned Information Elements (IEs). + +After receiving the status indication, the system will determine the appropriate response for the invitation discovery request. The system may then send [OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) OID to the driver for creation and transmission of the invitation response. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406528) + +[OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451807) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_REQUEST%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-response.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-response.md new file mode 100644 index 0000000000..dc877eb6ae --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-invitation-response.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_RESPONSE +author: windows-driver-content +ms.assetid: CF205FCF-64AD-410A-AB69-695677277D19 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_RESPONSE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of an invitation response from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_RESPONSE indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464143) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_RESPONSE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_RESPONSE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464143) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464143) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh464143) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_INVITATION_RESPONSE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-request.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-request.md new file mode 100644 index 0000000000..b21cd8cc00 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-request.md @@ -0,0 +1,71 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_REQUEST +author: windows-driver-content +ms.assetid: AC3A4E34-C4AA-4604-ABBC-73CDBD6C0704 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_REQUEST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of a provision discovery request transmission is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406531) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406531) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406531) and the size of the list of returned Information Elements (IEs). + +After receiving the status indication, the system will determine the appropriate response for the provision discovery request. The system may then send [OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451808) OID to the driver for creation and transmission of the provision discovery response. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406531) + +[OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh451808) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_REQUEST%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-response.md b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-response.md new file mode 100644 index 0000000000..4411d17071 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-dot11-wfd-received-provision-discovery-response.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_RESPONSE +author: windows-driver-content +ms.assetid: 38D5F0C8-7F8B-488F-BDCD-26B0580A9824 +description: +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_RESPONSE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The status of the reception of a provision discovery response transmission from a peer Wi-Fi Direct (WFD) device is reported with an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE indication. + +The data type for this indication is the [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406535) structure. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make an NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **StatusCode** must be set to NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE. + +- **StatusBuffer** must be set to the address of a [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406535) structure. + +- **StatusBufferSize** must be set to the total of both the size of [**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406535) and the size of the list of returned Information Elements (IEs). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**DOT11\_RECEIVED\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406535) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_DOT11_WFD_RECEIVED_PROVISION_DISCOVERY_RESPONSE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-hd-split-current-config.md b/windows-driver-docs-pr/network/ndis-status-hd-split-current-config.md new file mode 100644 index 0000000000..961d1b1a34 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-hd-split-current-config.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_HD_SPLIT_CURRENT_CONFIG +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_HD_SPLIT_CURRENT_CONFIG status indication to notify NDIS and overlying drivers that there has been a change in the header-data split configuration of a miniport adapter. +ms.assetid: 6605d888-bcbe-4898-aa25-4a4352fc50de +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_HD_SPLIT_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG + + +Miniport drivers use the NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG status indication to notify NDIS and overlying drivers that there has been a change in the header-data split configuration of a miniport adapter. + +Remarks +------- + +When a miniport driver receives an [OID\_GEN\_HD\_SPLIT\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569587) set request, the driver must use the contents of the [**NDIS\_HD\_SPLIT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565701) structure to update the current configuration of the miniport adapter. After the update, the miniport driver must report the changes with the NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG status indication. The status indication ensures that all of the overlying drivers are updated with the new information. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains an [**NDIS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff565696) structure. This structure specifies the current header-data split configuration of a miniport adapter. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff565696) + +[**NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG**](ndis-status-hd-split-current-config.md) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_GEN\_HD\_SPLIT\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569587) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_HD_SPLIT_CURRENT_CONFIG%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-isolation-parameters-change.md b/windows-driver-docs-pr/network/ndis-status-isolation-parameters-change.md new file mode 100644 index 0000000000..0da4e87944 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-isolation-parameters-change.md @@ -0,0 +1,56 @@ +--- +title: NDIS\_STATUS\_ISOLATION\_PARAMETERS\_CHANGE +author: windows-driver-content +description: A VM network adapter miniport driver generates an NDIS\_STATUS\_ISOLATION\_PARAMETERS\_CHANGE status indication whenever the routing domain configuration is updated on the network adapter's port. +ms.assetid: 4F3916B6-F52D-4B99-8F1C-A4A5BA9B307B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_ISOLATION_PARAMETERS_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_ISOLATION\_PARAMETERS\_CHANGE + + +A VM network adapter miniport driver generates an **NDIS\_STATUS\_ISOLATION\_PARAMETERS\_CHANGE** status indication whenever the routing domain configuration is updated on the network adapter's port. This triggers the TCP layer to re-query the multi-tenancy configuration by issuing an [OID\_GEN\_ISOLATION\_PARAMETERS](oid-gen-isolation-parameters.md) OID. This status indication does not have a status buffer. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_GEN\_ISOLATION\_PARAMETERS](oid-gen-isolation-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_ISOLATION_PARAMETERS_CHANGE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-link-speed-change.md b/windows-driver-docs-pr/network/ndis-status-link-speed-change.md new file mode 100644 index 0000000000..bedf9fbb77 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-link-speed-change.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_LINK_SPEED_CHANGE +author: windows-driver-content +description: The NDIS_STATUS_LINK_SPEED_CHANGE status indicates a link speed change. +ms.assetid: 084e43c9-598c-4c30-8004-2d1876a1cddd +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_LINK_SPEED_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_LINK\_SPEED\_CHANGE + + +The NDIS\_STATUS\_LINK\_SPEED\_CHANGE status indicates a link speed change. + +Remarks +------- + +NDIS translates NDIS\_STATUS\_LINK\_SPEED\_CHANGE status indications to [**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) status indications for overlying NDIS 6.0 drivers. When NDIS receives an NDIS\_STATUS\_LINK\_SPEED\_CHANGE status, NDIS issues an OID query request of [OID\_GEN\_LINK\_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569593). NDIS uses the results of the OID\_GEN\_LINK\_SPEED query to issue an NDIS\_STATUS\_LINK\_STATE status to overlying NDIS 6.0 drivers. + +The NDIS 5.*x* or earlier miniport driver supplies a DWORD-type value at the *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function. For more information about NDIS\_STATUS\_LINK\_SPEED\_CHANGE, see [OID\_IRDA\_RATE\_SNIFF](https://msdn.microsoft.com/library/windows/hardware/ff560287). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported in NDIS 6.0 and later (use [NDIS_STATUS_LINK_STATE](ndis-status-link-state.md) instead). Supported only for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +[OID\_GEN\_LINK\_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569593) + +[OID\_IRDA\_RATE\_SNIFF](https://msdn.microsoft.com/library/windows/hardware/ff560287) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_LINK_SPEED_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-link-state.md b/windows-driver-docs-pr/network/ndis-status-link-state.md new file mode 100644 index 0000000000..e683122dfa --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-link-state.md @@ -0,0 +1,90 @@ +--- +title: NDIS_STATUS_LINK_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_LINK_STATE status indication to notify NDIS and overlying drivers that there has been a change in the physical characteristics of a medium. +ms.assetid: e9953fe5-68d2-47e5-aceb-b35289500262 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_LINK_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_LINK\_STATE + + +Miniport drivers use the NDIS\_STATUS\_LINK\_STATE status indication to notify NDIS and overlying drivers that there has been a change in the physical characteristics of a medium. + +Remarks +------- + +Overlying drivers should not use the [OID\_GEN\_LINK\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569595) OID to determine the link state. Instead, use the NDIS\_STATUS\_LINK\_STATE status indication for link state updates. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains the [**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) structure. This structure specifies the physical state of the medium. + +Miniport drivers should avoid sending the NDIS\_STATUS\_LINK\_STATE status indication if there have been no changes in the physical state of the medium. However, avoiding this status indication is not a requirement. + +If a miniport adapter transitions to a low power state, NDIS 6.0 and later miniport drivers should indicate a connection status of **MediaConnectStateUnknown**. When the miniport adapter transitions back to the working power state, the miniport driver should indicate a status of **MediaConnectStateConnected** after the link has been re-established. NDIS 6.30 miniport drivers should indicate **MediaConnectStateUnknown** during a low power transition only when a wake on link change and selective suspend are disabled. In other words, a miniport driver must indicate a connection state of **MediaConnectStateUnknown** during a low power transition, if it is impossible to detect and wake on a connection state change from a low power state. + +NDIS might not pass a status indication to overlying drivers if there are no changes in the link state as specified in the previously indicated link state. However, this behavior is not guaranteed. Overlying drivers that receive this status indication must determine which characteristics of the medium, if any, have changed. + +If an overlying driver is an NDIS 5.*x* or earlier protocol driver, NDIS translates the NDIS\_STATUS\_LINK\_STATE status indication to appropriate NDIS 5.1 status indications. NDIS indicates link speed changes with the [**NDIS\_STATUS\_LINK\_SPEED\_CHANGE**](ndis-status-link-speed-change.md) status indication. NDIS indicates changes in the connection state with [**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) and [**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) status indications. + +NDIS also translates the NDIS 5.*x* miniport driver status for overlying NDIS 6.0 and later drivers. NDIS uses status indications or media state changes that NDIS identified in an NDIS 5.*x* OID query to create NDIS\_STATUS\_LINK\_STATE status indications. NDIS performs the following translations: + +- The [**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) status indication is translated to **MediaConnectStateConnected** in the [**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) structure. + +- The [**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) status indication is translated to **MediaConnectStateDisconnected** in the [**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) structure. + +- The [**NDIS\_STATUS\_LINK\_SPEED\_CHANGE**](ndis-status-link-speed-change.md) status indication and the [OID\_GEN\_LINK\_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569593) OID are used to generate the link speed status. + +For more information about link status, see [OID\_GEN\_LINK\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569595). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_LINK\_SPEED\_CHANGE**](ndis-status-link-speed-change.md) + +[**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) + +[**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) + +[OID\_GEN\_LINK\_SPEED](https://msdn.microsoft.com/library/windows/hardware/ff569593) + +[OID\_GEN\_LINK\_STATE](https://msdn.microsoft.com/library/windows/hardware/ff569595) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_LINK_STATE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-media-busy.md b/windows-driver-docs-pr/network/ndis-status-media-busy.md new file mode 100644 index 0000000000..9cc1975db0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-media-busy.md @@ -0,0 +1,58 @@ +--- +title: NDIS_STATUS_MEDIA_BUSY +author: windows-driver-content +description: The NDIS_STATUS_MEDIA_BUSY status indicates that the IRDA media is busy. +ms.assetid: 3b38987a-78f1-4036-8d48-c8792d273fdf +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_MEDIA_BUSY Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_MEDIA\_BUSY + + +The NDIS\_STATUS\_MEDIA\_BUSY status indicates that the IRDA media is busy. + +Remarks +------- + +For more information about NDIS\_STATUS\_MEDIA\_BUSY, see [OID\_IRDA\_MEDIA\_BUSY](https://msdn.microsoft.com/library/windows/hardware/ff560284). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported in NDIS 6.0 and later. Supported only for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_IRDA\_MEDIA\_BUSY](https://msdn.microsoft.com/library/windows/hardware/ff560284) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_MEDIA_BUSY%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-media-connect.md b/windows-driver-docs-pr/network/ndis-status-media-connect.md new file mode 100644 index 0000000000..0363b4e5fd --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-media-connect.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_MEDIA_CONNECT +author: windows-driver-content +description: The NDIS_STATUS_MEDIA_CONNECT status indicates that the status of a device's network connection has changed from disconnected to connected. +ms.assetid: de03d265-c8bf-4b7d-bfff-f583fcf08904 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_MEDIA_CONNECT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_MEDIA\_CONNECT + + +The NDIS\_STATUS\_MEDIA\_CONNECT status indicates that the status of a device's network connection has changed from disconnected to connected. For example, a device connects when it comes within range of an access point (for a wireless device) or when the user connects the device's network cable. + +Remarks +------- + +NDIS translates NDIS\_STATUS\_MEDIA\_CONNECT status indications to [**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) status indications for overlying NDIS 6.0 drivers. + +NDIS 5.*x* and earlier miniport drivers indicate an [**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) status when a miniport driver determines that the network connection has been lost. When the connection is restored, the driver indicates an NDIS\_STATUS\_MEDIA\_CONNECT status. + +For more information about NDIS\_STATUS\_MEDIA\_CONNECT, see [Indicating Connection Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546856) and [Media Status Indications for 802.11 Networks](https://msdn.microsoft.com/library/windows/hardware/ff549301). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported in NDIS 6.0 and later (use [NDIS_STATUS_LINK_STATE](ndis-status-link-state.md) instead). Supported only for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) + +[**NDIS\_STATUS\_MEDIA\_DISCONNECT**](ndis-status-media-disconnect.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_MEDIA_CONNECT%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-media-disconnect.md b/windows-driver-docs-pr/network/ndis-status-media-disconnect.md new file mode 100644 index 0000000000..5efe3ce8c6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-media-disconnect.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_MEDIA_DISCONNECT +author: windows-driver-content +description: The NDIS_STATUS_MEDIA_DISCONNECT status indicates that the status of a network connection has changed from connected to disconnected. +ms.assetid: 490853ca-c849-4b2b-9639-4be670616101 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_MEDIA_DISCONNECT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_MEDIA\_DISCONNECT + + +The NDIS\_STATUS\_MEDIA\_DISCONNECT status indicates that the status of a network connection has changed from connected to disconnected. For example, the network device loses the connection because it is out of range (for a wireless device), or the user unplugs the device's network cable. + +Remarks +------- + +NDIS translates NDIS\_STATUS\_MEDIA\_DISCONNECT status indications to [**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) status indications for overlying NDIS 6.0 drivers. + +NDIS 5.*x* and earlier miniport drivers indicate an [**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) status when the connection is restored. + +For more information about NDIS\_STATUS\_MEDIA\_DISCONNECT, see [Indicating Connection Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546856) and [Media Status Indications for 802.11 Networks](https://msdn.microsoft.com/library/windows/hardware/ff549301). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported in NDIS 6.0 and later (use [NDIS_STATUS_LINK_STATE](ndis-status-link-state.md) instead). Supported only for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_LINK\_STATE**](ndis-status-link-state.md) + +[**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_MEDIA_DISCONNECT%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-media-specific-indication.md b/windows-driver-docs-pr/network/ndis-status-media-specific-indication.md new file mode 100644 index 0000000000..109b684d25 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-media-specific-indication.md @@ -0,0 +1,60 @@ +--- +title: NDIS_STATUS_MEDIA_SPECIFIC_INDICATION +author: windows-driver-content +description: The NDIS_STATUS_MEDIA_SPECIFIC_INDICATION status indicates a media-specific status. +ms.assetid: 983ffff1-5157-46ae-b4ce-31ee1aa55955 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_MEDIA_SPECIFIC_INDICATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION + + +The NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION status indicates a media-specific status. + +Remarks +------- + +Miniport drivers make media-specific status indications by calling the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function with the **StatusCode** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure set to NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION. The **StatusBuffer** member of this structure points to a driver-allocated buffer. The buffer contains data in a format that is specific to the status indication that is identified in the **StatusCode** member. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_MEDIA_SPECIFIC_INDICATION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-network-change.md b/windows-driver-docs-pr/network/ndis-status-network-change.md new file mode 100644 index 0000000000..748c09eb5f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-network-change.md @@ -0,0 +1,83 @@ +--- +title: NDIS_STATUS_NETWORK_CHANGE +author: windows-driver-content +description: The NDIS_STATUS_NETWORK_CHANGE status indicates a network change to allow overlying drivers to initiate renegotiation of network addresses. +ms.assetid: feb6bb71-7147-43dd-b09d-cb41404164eb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_NETWORK_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_NETWORK\_CHANGE + + +The NDIS\_STATUS\_NETWORK\_CHANGE status indicates a network change to allow overlying drivers to initiate renegotiation of network addresses. + +Remarks +------- + +NDIS miniport drivers can generate this status indication to request the overlying protocol drivers to renegotiate layer three addresses. + +NDIS generates NDIS\_STATUS\_NETWORK\_CHANGE status indications for the older 802.1X wireless miniport drivers that emulate 802.3. These miniport drivers report a media type of **NdisMedium802\_3** and a physical media type of **NdisPhysicalMediumWirelessLan**. When such a miniport driver generates an [**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) status indication and the associated miniport adapter is in a connected state, NDIS generates an NDIS\_STATUS\_NETWORK\_CHANGE status indication for the miniport adapter. + +NDIS 6.0 and later miniport drivers should generate the NDIS\_STATUS\_NETWORK\_CHANGE status indication only after they are ready to handle network data. For example, in native 802.11, this status indication is generated after authentication is completed successfully and full layer two connectivity is achieved. + +**Note**  Although the media-connected state is not precisely defined, this state can be loosely defined as - the state in which the miniport adapter is able to transmit and receive network data. Media-connected is not directly related to link authentication status. The native WiFi 802.3 interface is unable to send or receive packets until after the link is authenticated. In this case, the media-connected state is coincident with the link-authenticated state in native 802.11. + +  + +NDIS supplies one of the following NDIS\_NETWORK\_CHANGE\_TYPE values in the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure: + +**NdisPossibleNetworkChange** +The miniport driver detected that there might be a network change. In this case, the overlying protocols must detect the network change, if any, and renegotiate the addresses if necessary. + +NDIS also uses this value when it generates NDIS\_STATUS\_NETWORK\_CHANGE status indications for older 802.1X wireless miniport drivers that emulate 802.3. However, NDIS uses **NdisNetworkChangeFromMediaConnect** instead of **NdisPossibleNetworkChange** when it translates the same event for Windows Management Instrumentation (WMI). + +**NdisDefinitelyNetworkChange** +The miniport driver detected that there is a network change, so the overlying protocols must renegotiate the addresses. + +**NdisNetworkChangeFromMediaConnect** +An older 802.1X wireless miniport driver that emulates 802.3 generated an [**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) status indication when it was in a connected state. This value is used in the WMI event notification for [GUID\_NDIS\_STATUS\_NETWORK\_CHANGE](https://msdn.microsoft.com/library/windows/hardware/ff553595). **NdisNetworkChangeFromMediaConnect** is not used in the NDIS\_STATUS\_NETWORK\_CHANGE status indication. + +The **StatusBufferSize** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure is set to sizeof(NDIS\_NETWORK\_CHANGE\_TYPE). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_MEDIA\_CONNECT**](ndis-status-media-connect.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_NETWORK_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-nic-switch-current-capabilities.md b/windows-driver-docs-pr/network/ndis-status-nic-switch-current-capabilities.md new file mode 100644 index 0000000000..b9170fd872 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-nic-switch-current-capabilities.md @@ -0,0 +1,84 @@ +--- +title: NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: The NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES status indicates to NDIS and overlying drivers that the currently enabled hardware capabilities of the NIC switch in a network adapter have changed. +ms.assetid: 8F5DF045-4993-45E6-A5B9-502B695E3C62 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_NIC_SWITCH_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES + + +The **NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES** status indicates to NDIS and overlying drivers that the currently enabled hardware capabilities of the NIC switch in a network adapter have changed. + +The status indication is made by the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). The PF miniport driver runs in the management operating system of the Hyper-V parent partition. + +Remarks +------- + +The PF miniport driver must issue an **NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES** status indication whenever it detects a change to the currently enabled hardware capabilities of the NIC switch on the network adapter. These capabilities could change when one of the following conditions is true: + +- The currently enabled NIC switch hardware capabilities are changed through a management application developed by the independent hardware vendor (IHV). + +- The currently enabled NIC switch hardware capabilities change for one or more network adapters that belong to a load balancing failover (LBFO) team managed by a MUX intermediate driver. For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +When the PF miniport driver issues the **NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES** status indication, it must follow these steps: + +1. The miniport driver initializes an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure with the currently enabled hardware capabilities of the network adapter's NIC switch. +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure in the following way: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES**. + + - The **StatusBuffer** member must be set to the pointer to a [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure. This structure contains the currently enabled hardware capabilities of the NIC switch. + + - The **StatusBufferSize** member must be set to sizeof([**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583)). + +3. The PF miniport driver issues the status notification by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +Overlying drivers can use the **NDIS\_STATUS\_NIC\_SWITCH\_CURRENT\_CAPABILITIES** status indication to determine the currently enabled NIC switch capabilities on the network adapter. Alternatively, these drivers can also issue OID query requests of [OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES](oid-nic-switch-current-capabilities.md) to obtain these capabilities at any time. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES](oid-nic-switch-current-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_NIC_SWITCH_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-nic-switch-hardware-capabilities.md b/windows-driver-docs-pr/network/ndis-status-nic-switch-hardware-capabilities.md new file mode 100644 index 0000000000..8a4c4931ab --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-nic-switch-hardware-capabilities.md @@ -0,0 +1,84 @@ +--- +title: NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: The NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES status indicates to NDIS and overlying drivers that the hardware capabilities of the NIC switch in a network adapter have changed. +ms.assetid: 21B326EC-22CC-4E41-895F-457971202C0B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_NIC_SWITCH_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES + + +The **NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES** status indicates to NDIS and overlying drivers that the hardware capabilities of the NIC switch in a network adapter have changed. These capabilities include the hardware capabilities that are currently disabled by INF file settings or through the **Advanced** properties page. + +The status indication is made by the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). The PF miniport driver runs in the management operating system of the Hyper-V parent partition. + +Remarks +------- + +The PF miniport driver must issue an **NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES** status indication whenever it detects a change to the hardware capabilities of the NIC switch on the network adapter. These capabilities could change when one of the following conditions is true: + +- The NIC switch hardware capabilities are enabled or disabled through a management application developed by the independent hardware vendor (IHV). + +- The NIC switch hardware capabilities change for one or more network adapters that belong to a load balancing failover (LBFO) team managed by a MUX intermediate driver. For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +When the PF miniport driver issues the **NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES** status indication, it must follow these steps: + +1. The miniport driver initializes an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure with the hardware capabilities of the network adapter's NIC switch. +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure in the following way: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES**. + + - The **StatusBuffer** member must be set to the pointer to a [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure. This structure contains the hardware capabilities of the NIC switch. + + - The **StatusBufferSize** member must be set to sizeof([**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583)). + +3. The PF miniport driver issues the status notification by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +Overlying drivers can use the **NDIS\_STATUS\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES** status indication to determine the currently enabled NIC switch capabilities on the network adapter. Alternatively, these drivers can also issue OID query requests of [OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES](oid-nic-switch-hardware-capabilities.md) to obtain these capabilities at any time. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES](oid-nic-switch-hardware-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_NIC_SWITCH_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-offload-encaspulation-change.md b/windows-driver-docs-pr/network/ndis-status-offload-encaspulation-change.md new file mode 100644 index 0000000000..e08f98a58c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-offload-encaspulation-change.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_OFFLOAD_ENCASPULATION_CHANGE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_OFFLOAD_ENCASPULATION_CHANGE status indication to notify NDIS and overlying drivers that there has been change in the encapsulation settings. +ms.assetid: 2db2a42e-85a2-41a6-b6ab-13b493057648 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_OFFLOAD_ENCASPULATION_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_OFFLOAD\_ENCASPULATION\_CHANGE + + +Miniport drivers use the NDIS\_STATUS\_OFFLOAD\_ENCASPULATION\_CHANGE status indication to notify NDIS and overlying drivers that there has been change in the encapsulation settings. + +Remarks +------- + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains an [**NDIS\_OFFLOAD\_ENCAPSULATION**](https://msdn.microsoft.com/library/windows/hardware/ff566702) structure. NDIS\_OFFLOAD\_ENCAPSULATION specifies the encapsulation settings. + +For more information about encapsulation settings, see [OID\_OFFLOAD\_ENCAPSULATION](https://msdn.microsoft.com/library/windows/hardware/ff569762). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OFFLOAD\_ENCAPSULATION**](https://msdn.microsoft.com/library/windows/hardware/ff566702) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_OFFLOAD\_ENCAPSULATION](https://msdn.microsoft.com/library/windows/hardware/ff569762) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_OFFLOAD_ENCASPULATION_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-oper-status.md b/windows-driver-docs-pr/network/ndis-status-oper-status.md new file mode 100644 index 0000000000..586237ac9b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-oper-status.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_OPER_STATUS +author: windows-driver-content +description: The NDIS_STATUS_OPER_STATUS status indicates the current operational state of an NDIS network interface to overlying drivers. +ms.assetid: dbe7ce19-290d-4a48-a6c2-1b95e956c26c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_OPER_STATUS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_OPER\_STATUS + + +The NDIS\_STATUS\_OPER\_STATUS status indicates the current operational state of an NDIS network interface to overlying drivers. + +Remarks +------- + +NDIS generates this status indication; NDIS miniport drivers should not generate this status indication. + +NDIS supplies an [**NDIS\_OPER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566737) structure in the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure. + +The **StatusBufferSize** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure is set to sizeof(NDIS\_OPER\_STATE). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OPER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566737) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_OPER_STATUS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-packet-filter.md b/windows-driver-docs-pr/network/ndis-status-packet-filter.md new file mode 100644 index 0000000000..53232e7133 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-packet-filter.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_PACKET_FILTER +author: windows-driver-content +description: The NDIS_STATUS_PACKET_FILTER status indicates a packet filter change to overlying drivers. +ms.assetid: 7633772a-cd3d-4030-b97a-9d503341fdeb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PACKET_FILTER Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PACKET\_FILTER + + +The NDIS\_STATUS\_PACKET\_FILTER status indicates a packet filter change to overlying drivers. NDIS generates this status indications for a miniport adapter to notify overlying drivers that there might be a change in the miniport adapter's packet filter setting. + +Remarks +------- + +NDIS does not guarantee that the packet filter has changed when NDIS generates the NDIS\_STATUS\_PACKET\_FILTER status indication. + +NDIS filter drivers can also generate the NDIS\_STATUS\_PACKET\_FILTER status indication. + +NDIS supplies a bitwise OR of the filter type flags in the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure. For a list of the filter type flags, see the [OID\_GEN\_CURRENT\_PACKET\_FILTER](https://msdn.microsoft.com/library/windows/hardware/ff569575) OID. For additional information about packet filters, see [OID\_GEN\_SUPPORTED\_PACKET\_FILTERS](https://msdn.microsoft.com/library/windows/hardware/ff569643). + +The **StatusBufferSize** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure is set to sizeof(ULONG). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_GEN\_CURRENT\_PACKET\_FILTER](https://msdn.microsoft.com/library/windows/hardware/ff569575) + +[OID\_GEN\_SUPPORTED\_PACKET\_FILTERS](https://msdn.microsoft.com/library/windows/hardware/ff569643) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PACKET_FILTER%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pd-current-config.md b/windows-driver-docs-pr/network/ndis-status-pd-current-config.md new file mode 100644 index 0000000000..9f05476d5c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pd-current-config.md @@ -0,0 +1,75 @@ +--- +title: NDIS_STATUS_PD_CURRENT_CONFIG +author: windows-driver-content +description: This status indication is a notification that the NDIS_PD_CONFIG structure has changed. +ms.assetid: 0B63E85E-36A8-4DC4-A060-C40DCB6BE454 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PD_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PD\_CURRENT\_CONFIG + + +This status indication is a notification that the [**NDIS\_PD\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/dn931835) structure has changed. + +A PacketDirect-capable miniport driver must make an NDIS\_STATUS\_PD\_CURRENT\_CONFIG status indication after an [OID\_PD\_CLOSE\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/dn931851) or [OID\_PD\_OPEN\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/dn931852) request. + +The miniport driver calls [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) to make the status indication, and must pass a pointer to an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure through the *StatusIndication* parameter. When making this indication, the miniport driver must set the following members of the **NDIS\_STATUS\_INDICATION** structure: + +- **SourceHandle** must be set to the handle that the miniport received in the *MiniportAdapterHandle* parameter of the [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function. + +- **StatusCode** must be set to NDIS\_STATUS\_PD\_CURRENT\_CONFIG. + +- **StatusBuffer** must be set to the address of a ULONG variable, which stores the appropriate NDIS\_STATUS\_xxxx code for the result of the scan operation. + +- **StatusBufferSize** must be set to **sizeof**(ULONG). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[OID\_PD\_CLOSE\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/dn931851) + +[OID\_PD\_OPEN\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/dn931852) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PD_CURRENT_CONFIG%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pm-capabilities-change.md b/windows-driver-docs-pr/network/ndis-status-pm-capabilities-change.md new file mode 100644 index 0000000000..a401f85b00 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pm-capabilities-change.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_PM_CAPABILITIES_CHANGE +author: windows-driver-content +description: The NDIS_STATUS_PM_CAPABILITIES_CHANGE status indicates a change in the power management capabilities of a network adapter to overlying drivers. +ms.assetid: 28a2ed15-606a-4a40-b975-b766815a02cc +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PM_CAPABILITIES_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE + + +The NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE status indicates a change in the power management capabilities of a network adapter to overlying drivers. + +Remarks +------- + +NDIS generates an NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE status indication when an update to the previously reported power management capabilities is required. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a pointer to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure with the updated power management capabilities. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PM_CAPABILITIES_CHANGE%20%20RELEASE:%20%287/6/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pm-hardware-capabilities.md b/windows-driver-docs-pr/network/ndis-status-pm-hardware-capabilities.md new file mode 100644 index 0000000000..3405861d1f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pm-hardware-capabilities.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_PM_HARDWARE_CAPABILITIES +author: windows-driver-content +description: The NDIS_STATUS_PM_HARDWARE_CAPABILITIES status indicates to overlying drivers that a change in the power management (PM) hardware capabilities of a network adapter has occurred. +ms.assetid: A4AACA48-DCD2-44FA-B016-52C37EE9A1D6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PM_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PM\_HARDWARE\_CAPABILITIES + + +The **NDIS\_STATUS\_PM\_HARDWARE\_CAPABILITIES** status indicates to overlying drivers that a change in the power management (PM) hardware capabilities of a network adapter has occurred. + +Remarks +------- + +The miniport driver generates an **NDIS\_STATUS\_PM\_HARDWARE\_CAPABILITIES** status indication when an update to the previously reported power management capabilities is required. + +The miniport driver for an 802.11 network adapter can generate this status indication. + +A MUX intermediate driver that provides load balancing failover (LBFO) support can also generate this status indication. The MUX driver aggregates the PM capabilities of the underlying network adapters that are part of the LBFO team. If the PM capabilities change because an adapter has been either added or removed from the team, the MUX driver must generate this status indication. For more information on LBFO MUX intermediate drivers, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a pointer to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure with the updated power management capabilities. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PM_HARDWARE_CAPABILITIES%20%20RELEASE:%20%287/6/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pm-offload-rejected.md b/windows-driver-docs-pr/network/ndis-status-pm-offload-rejected.md new file mode 100644 index 0000000000..82381fa246 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pm-offload-rejected.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_PM_OFFLOAD_REJECTED +author: windows-driver-content +description: The NDIS_STATUS_PM_OFFLOAD_REJECTED status indicates to overlying drivers that a power management protocol offload was rejected. +ms.assetid: 54922e70-2b56-4141-b79b-73418c7553e3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PM_OFFLOAD_REJECTED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED + + +The NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED status indicates to overlying drivers that a power management protocol offload was rejected. + +Remarks +------- + +NDIS or miniport drivers can generate the NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED status indication when either of them removes an offloaded protocol. The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a ULONG for the protocol offload identifier of the rejected protocol offload. NDIS provided the protocol offload identifier in the **ProtocolOffloadId** member of the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure. + +NDIS generates an NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED status indication when it has to remove a previously offloaded protocol from a network adapter. For example, NDIS might remove the protocol offload to free resources for a higher priority protocol offload. NDIS sends the status indication to the binding that offloaded the rejected protocol offload, but does not send it to other bindings. + +Miniport drivers report this status indication to reject a previously accepted protocol offload. For example, for a WiFi WOL case, the miniport driver must make an NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED status indication when PTK/GTK rotation is not required to support WOL (due to vendor specific infrastructure support). + +For wireless network adapters that use infrastructure elements to offload protocols and roam across the infrastructure, it is possible that a new infrastructure element might not support the same capabilities as the previous one. In this case, the miniport driver can issue a status indication to NDIS, and NDIS will issue NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED with a specific error code. + +A WiFi driver might cache protocol offload requests locally. When the driver processes an OID for adding or deleting a protocol offload, the driver can choose to only update its local cache. The driver can defer the update of the infrastructure until it receives the [OID\_PM\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569768) OID. + +The infrastructure might not have enough resources to accommodate all of the protocol offloads. In this case, the infrastructure can accept a partial list of the protocol offloads. When the miniport driver completes the OID\_PM\_PARAMETERS set request, the miniport driver must make NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED status indications for each of the protocol offloads that the AP rejects. + +For example, a network adapter can use the AP's proxy ARP to support ARP offload. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_PM\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569768) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PM_OFFLOAD_REJECTED%20%20RELEASE:%20%287/6/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pm-wake-reason.md b/windows-driver-docs-pr/network/ndis-status-pm-wake-reason.md new file mode 100644 index 0000000000..41bec4cbdf --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pm-wake-reason.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_PM_WAKE_REASON +author: windows-driver-content +description: The NDIS_STATUS_PM_WAKE_REASON status indication provides information about the wake-up event that was generated by a network adapter. +ms.assetid: 0CF29C9B-4AAA-473D-A3E8-C1E9530B595E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PM_WAKE_REASON Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PM\_WAKE\_REASON + + +The **NDIS\_STATUS\_PM\_WAKE\_REASON** status indication provides information about the wake-up event that was generated by a network adapter. + +Remarks +------- + +Starting with NDIS 6.30, the miniport driver issues an NDIS status indication of **NDIS\_STATUS\_PM\_WAKE\_REASON**. This status indication notifies NDIS and overlying drivers about the reason for a wake-up event generated by the network adapter. + +If the miniport driver supports this type of status indication, the miniport driver must issue an **NDIS\_STATUS\_PM\_WAKE\_REASON** status indication if the network adapter generated a wake-up signal. The driver does this while it is handling the OID set request of [OID\_PNP\_SET\_POWER](https://msdn.microsoft.com/library/windows/hardware/ff569780) for the transition of the adapter to a full-power state. + +When the miniport driver makes this status indication, it sets the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to a pointer to an [**NDIS\_PM\_WAKE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/hh451605) structure. + +For more information about how to issue an **NDIS\_STATUS\_PM\_WAKE\_REASON** indication, see [Issuing NDIS Wake Reason Status Indications](https://msdn.microsoft.com/library/windows/hardware/hh463944). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_PM\_WAKE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/hh451605) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PM_WAKE_REASON%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-pm-wol-pattern-rejected.md b/windows-driver-docs-pr/network/ndis-status-pm-wol-pattern-rejected.md new file mode 100644 index 0000000000..826f0b1f5c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-pm-wol-pattern-rejected.md @@ -0,0 +1,70 @@ +--- +title: NDIS_STATUS_PM_WOL_PATTERN_REJECTED +author: windows-driver-content +description: The NDIS_STATUS_PM_WOL_PATTERN_REJECTED status indicates to overlying drivers that a power management wake on LAN (WOL) pattern was rejected. +ms.assetid: 49180c69-a3b8-4a6f-b34f-93e063c88f43 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PM_WOL_PATTERN_REJECTED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED + + +The NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED status indicates to overlying drivers that a power management wake on LAN (WOL) pattern was rejected. + +Remarks +------- + +NDIS or miniport drivers can generate the NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED status indication when either of them removes a WOL pattern. The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a ULONG for the WOL pattern identifier of the rejected WOL pattern. NDIS provided the WOL pattern identifier in the **PatternId** member of the [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure. + +NDIS generates an NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED status indication when it must remove a previously added WOL pattern from a network adapter. For example, NDIS might remove the WOL pattern to free resources for a higher priority WOL pattern. The notification event will only be sent to the binding that added the removed pattern. + +For wireless network adapters that use infrastructure elements to offload the patterns and roam across the infrastructure, it is possible that a new infrastructure element might not support the same capabilities as the previous one. In this case, the miniport driver can issue a status indication to NDIS, and NDIS will issue NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED with a specific error code. + +A WiFi driver might cache wake-up patterns locally. When the driver processes an OID for adding or deleting a wake-up pattern, the driver can choose to only update its local cache. The driver can defer the update of the infrastructure until it receives the [OID\_PM\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569768) OID. + +The infrastructure might not have enough resources to accommodate all of the wake-up patterns. In this case, the infrastructure can accept a partial list of the wake-up patterns. When the miniport driver completes the OID\_PM\_PARAMETERS set request, the driver must make NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED status indications for each of the WOL patterns that the access point (AP) rejects. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_PM\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569768) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PM_WOL_PATTERN_REJECTED%20%20RELEASE:%20%287/6/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-port-state.md b/windows-driver-docs-pr/network/ndis-status-port-state.md new file mode 100644 index 0000000000..0e41b18f2c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-port-state.md @@ -0,0 +1,60 @@ +--- +title: NDIS_STATUS_PORT_STATE +author: windows-driver-content +description: Miniport drivers that support NDIS ports use the NDIS_STATUS_PORT_STATE status indication to indicate changes in the state of an NDIS port. +ms.assetid: 28e76963-af06-4a00-83ef-14e009cf35ec +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_PORT_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_PORT\_STATE + + +Miniport drivers that support NDIS ports use the NDIS\_STATUS\_PORT\_STATE status indication to indicate changes in the state of an NDIS port. + +Remarks +------- + +Miniport drivers must set the port number in the **PortNumber** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure. The **StatusBuffer** member of this structure contains a pointer to an [**NDIS\_PORT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566800) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PORT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566800) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_PORT_STATE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-qos-operational-parameters-change.md b/windows-driver-docs-pr/network/ndis-status-qos-operational-parameters-change.md new file mode 100644 index 0000000000..7cd250e473 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-qos-operational-parameters-change.md @@ -0,0 +1,89 @@ +--- +title: NDIS_STATUS_QOS_OPERATIONAL_PARAMETERS_CHANGE +author: windows-driver-content +description: The miniport driver that supports NDIS Quality of Service (QoS) issues an NDIS_STATUS_QOS_OPERATIONAL_PARAMETERS_CHANGE status indication when its operational NDIS QoS parameters are either resolved for the first time or changed later. +ms.assetid: 15D2B139-1AEA-4252-8599-0EA4ED2E3733 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_QOS_OPERATIONAL_PARAMETERS_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE + + +The miniport driver that supports NDIS Quality of Service (QoS) issues an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication when its operational NDIS QoS parameters are either resolved for the first time or changed later. The miniport driver configures the network adapter with these operational parameters to perform QoS packet transmission. + +When the miniport driver makes this status indication, it sets the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to a pointer to an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. The driver initializes this structure with its operational NDIS QoS parameters. + +**Note**  This NDIS status indication is valid only for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +The miniport driver issues an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication under the following conditions: + +- The miniport driver must issue an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication after it has initially resolved its operational NDIS QoS parameters and configured the network adapter with them. + +- After this initial status indication, the miniport driver must issue an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication when its operational NDIS QoS parameters are changed. This can happen when either the local or remote NDIS QoS parameters are changed. + +- Miniport drivers obtain the local NDIS QoS parameters from the Windows operating system when the Data Center Bridging (DCB) component (Msdcb.sys) issues an object identifier (OID) method request of [OID\_QOS\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451835). This OID request contains an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure that specifies the local NDIS QoS parameters. + + There may be situations when the miniport driver has to override the local NDIS QoS parameters when it resolves its operational NDIS QoS parameters. This is especially true if the local QoS parameters compromise the operational QoS parameters that are being used by any underlying protocols or technologies that are currently enabled on the network adapter. For example, the driver can override the local QoS parameters if the network adapter is enabled for remote boot through the Fibre Channel over Ethernet (FCoE) protocol. + + The miniport driver notifies NDIS and overlying drivers of its intention to override the local NDIS QoS parameters by issuing an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication. + + For more information, see [Managing NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh464015). + +**Note**  Overlying drivers can use the **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication to determine the operational NDIS QoS parameters. Alternatively, these drivers can also issue OID query requests of [OID\_QOS\_OPERATIONAL\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451832) to obtain the operational NDIS QoS parameters at any time. + +  + +For information on how the miniport driver issues an **NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE** status indication, see [Indicating Changes to the Operational NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh451447). + +For more information about the various types of NDIS QoS parameters, see [Overview of NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440130). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) + +[OID\_QOS\_OPERATIONAL\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451832) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_QOS_OPERATIONAL_PARAMETERS_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-qos-remote-parameters-change.md b/windows-driver-docs-pr/network/ndis-status-qos-remote-parameters-change.md new file mode 100644 index 0000000000..4e1ef97787 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-qos-remote-parameters-change.md @@ -0,0 +1,95 @@ +--- +title: NDIS_STATUS_QOS_REMOTE_PARAMETERS_CHANGE +author: windows-driver-content +description: The miniport driver that supports NDIS Quality of Service (QoS) issues an NDIS_STATUS_QOS_REMOTE_PARAMETERS_CHANGE status indication when its remote NDIS QoS parameters are either received from a peer for the first time or change later. +ms.assetid: 3DA5F4FA-193F-4716-8678-7B6FB833E68E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_QOS_REMOTE_PARAMETERS_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE + + +The miniport driver that supports NDIS Quality of Service (QoS) issues an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication when its remote NDIS QoS parameters are either received from a peer for the first time or change later. The miniport driver receives these QoS parameters from a remote peer through the IEEE 802.1Qaz Data Center Bridging Exchange (DCBX) protocol. + +When the miniport driver makes this status indication, it sets the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to a pointer to an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. The driver initializes this structure with its remote NDIS QoS parameters. + +**Note**  This NDIS status indication is valid only for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +The miniport driver uses the DCBX protocol to receive the QoS parameters for a remote peer. The miniport driver resolves its operational NDIS QoS parameters based on its local and remote QoS settings. Once the operational parameters are resolved, the miniport driver configures the network adapter with these parameters for QoS packet transmission. + +For more information about how the driver resolves its operational NDIS QoS parameter settings, see [Resolving Operational NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440220). + +The miniport driver must follow these guidelines for issuing an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication: + +- If the miniport driver has not received a DCBX frame from a remote peer, it must not issue an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication. + +- The miniport driver must issue an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication after it has first received the QoS settings from a remote peer. + + **Note**  The miniport driver must issue this status indication if the network adapter receives remote QoS parameter settings from a peer before the driver's local QoS parameters are set. For more information, see [Setting Local NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440225). + +   + +- After this initial status indication, the miniport driver must only issue an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication when it determines a change in the QoS settings on the remote peer. + + **Note**  Miniport drivers must not issue an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication if there have been no changes to the remote NDIS QoS parameters. If the driver does make this type of status indication, NDIS may not pass the indication to overlying drivers. + +   + +**Note**  Overlying drivers can use the **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication to determine the remote NDIS QoS parameters. Alternatively, these drivers can also issue OID query requests of [OID\_QOS\_REMOTE\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451841) to obtain the remote NDIS QoS parameters at any time. + +  + +For more information on how the miniport driver issues an **NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE** status indication, see [Indicating Changes to the Remote NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh406724). + +For more information about the remote NDIS QoS parameters, see [Overview of NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440130). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) + +[OID\_QOS\_REMOTE\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451841) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_QOS_REMOTE_PARAMETERS_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-receive-filter-current-capabilities.md b/windows-driver-docs-pr/network/ndis-status-receive-filter-current-capabilities.md new file mode 100644 index 0000000000..0afbc8d587 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-receive-filter-current-capabilities.md @@ -0,0 +1,103 @@ +--- +title: NDIS_STATUS_RECEIVE_FILTER_CURRENT_CAPABILITIES +author: windows-driver-content +description: The miniport driver issues an NDIS_STATUS_RECEIVE_FILTER_CURRENT_CAPABILITIES status indication when its currently enabled receive filtering capabilities change. +ms.assetid: 6A1141A3-6E46-4A97-B482-CBE69E3D5075 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RECEIVE_FILTER_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES + + +The miniport driver issues an **NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES** status indication when its currently enabled receive filtering capabilities change. + +**Note**  This status indication should only be made by miniport drivers that support NDIS receive filters. + +  + +When the miniport driver makes this status indication, it sets the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to a pointer to an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. The driver initializes this structure with its currently enabled receive filter capabilities. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +The miniport driver issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES** status indication when one of the following conditions is true: + +- The currently enabled receive filter capabilities change on a single network adapter. For example, receive filters can be enabled or disabled through a management application developed by the independent hardware vendor (IHV). + +- The currently enabled receive filter capabilities change for one or more network adapters that belong to a load balancing failover (LBFO) team managed by a MUX intermediate driver. For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +The miniport driver follows these steps when it issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES** status indication: + +1. The miniport initializes the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure with the receive filter capabilities that are currently enabled on the network adapter. + + When the miniport driver initializes the **Header** member, it sets the **Type** member of **Header** to NDIS\_OBJECT\_TYPE\_DEFAULT. The miniport driver sets the **Revision** member of **Header** to NDIS\_RECEIVE\_FILTER\_CAPABILITIES\_REVISION\_2 and the **Size** member to NDIS\_SIZEOF\_RECEIVE\_FILTER\_CAPABILITIES\_REVISION\_2. + +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the status indication in the following way: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES**. + + - The **StatusBuffer** member must be set to the address of the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + + - The **StatusBufferSize** member must be set to `sizeof(NDIS_RECEIVE_FILTER_CAPABILITIES)`. + +3. The miniport driver issues the status indication by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +**Note**  Overlying drivers can use the **NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES** status indication to determine the currently enabled receive filter capabilities of the network adapter. Alternatively, these drivers can also issue OID query requests of [OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569786) to obtain the currently enabled receive filter capabilities at any time. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) + +[OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569786) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RECEIVE_FILTER_CURRENT_CAPABILITIES%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-receive-filter-hardware-capabilities.md b/windows-driver-docs-pr/network/ndis-status-receive-filter-hardware-capabilities.md new file mode 100644 index 0000000000..6d69df908f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-receive-filter-hardware-capabilities.md @@ -0,0 +1,105 @@ +--- +title: NDIS_STATUS_RECEIVE_FILTER_HARDWARE_CAPABILITIES +author: windows-driver-content +description: The miniport driver issues an NDIS_STATUS_RECEIVE_FILTER_HARDWARE_CAPABILITIES status indication when its hardware receive filtering capabilities change. +ms.assetid: 12F7A736-D85A-4BB6-89E6-55195B76C29F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RECEIVE_FILTER_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES + + +The miniport driver issues an **NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES** status indication when its hardware receive filtering capabilities change. These capabilities include the hardware capabilities that are currently disabled by INF file settings or through the **Advanced** properties page. + +**Note**  This status indication should only be made by miniport drivers that support NDIS receive filters. + +  + +When the miniport driver makes this status indication, it sets the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to a pointer to an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. The driver initializes this structure with its currently enabled receive filter capabilities. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +The miniport driver issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES** status indication when one of the following conditions is true: + +- The hardware receive filter capabilities change on a single network adapter. For example, receive filters can be enabled or disabled through a management application developed by the independent hardware vendor (IHV). + +- The hardware receive filter capabilities change for the load balancing failover (LBFO) team of network adapters that are managed by a MUX intermediate driver. For example, the hardware receive filter capabilities could change when an adapter is added to or removed from the team. + + For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +The miniport driver follows these steps when it issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES** status indication: + +1. The miniport initializes the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure with the receive filter capabilities that are currently enabled on the network adapter. + + When the miniport driver initializes the **Header** member, it sets the **Type** member of **Header** to NDIS\_OBJECT\_TYPE\_DEFAULT. The miniport driver sets the **Revision** member of **Header** to NDIS\_RECEIVE\_FILTER\_CAPABILITIES\_REVISION\_2 and the **Size** member to NDIS\_SIZEOF\_RECEIVE\_FILTER\_CAPABILITIES\_REVISION\_2. + +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the status indication in the following way: + + - The **StatusCode** member must be set to [**NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES**](ndis-status-receive-filter-current-capabilities.md). + + - The **StatusBuffer** member must be set to the address of the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + + - The **StatusBufferSize** member must be set to `sizeof(NDIS_RECEIVE_FILTER_CAPABILITIES)`. + +3. The miniport driver issues the status indication by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +**Note**  Overlying drivers can use the **NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES** status indication to determine the currently enabled receive filter capabilities of the network adapter. Alternatively, these drivers can also issue OID query requests of [OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569791) to obtain the hardware receive filter capabilities at any time. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) + +[OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569786) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RECEIVE_FILTER_HARDWARE_CAPABILITIES%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-allocation-state.md b/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-allocation-state.md new file mode 100644 index 0000000000..93aa407d44 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-allocation-state.md @@ -0,0 +1,80 @@ +--- +title: NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE +author: windows-driver-content +description: The NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE status indicates to NDIS and overlying drivers that the allocation state of virtual machine (VM) queues on the network adapter has changed. +ms.assetid: E8E62EE1-78F5-4DDB-9623-D31B807D753C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_RECEIVE_FILTER_QUEUE_ALLOCATION_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE + + +The **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE** status indicates to NDIS and overlying drivers that the allocation state of virtual machine (VM) queues on the network adapter has changed. + +Remarks +------- + +The miniport driver must issue an **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE** status indication when the VM queue capabilities of the network adapter change. The VM queue capabilities could change when one of the following conditions is true: + +- The VM queue allocation state is changed through a management application developed by the independent hardware vendor (IHV). + +- The VM queue allocation state changes for one or more network adapters that belong to a load balancing failover (LBFO) team managed by a MUX intermediate driver. For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +When the miniport driver issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE** status indication, it must follow these steps: + +1. The miniport driver initializes an [**NDIS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh451653) structure with the current VM queue allocation state on the network adapter. If VM queue allocation is allowed, the driver must set the **AllocationAllowed** member to TRUE. Otherwise, the driver must set the **AllocationAllowed** member to FALSE. +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure in the following way: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**. + + - The **StatusBuffer** member must be set to the pointer to a [**NDIS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh451653) structure. This structure contains the currently enabled hardware capabilities of the NIC switch. + + - The **StatusBufferSize** member must be set to sizeof([**NDIS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh451653)). + +3. The miniport driver issues the status notification by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +Starting with NDIS 6.30, if VM queue allocation is no longer enabled or allowed, the overlying drivers that receive this status indication must issue an object identifier (OID) set request of [OID\_RECEIVE\_FILTER\_FREE\_QUEUE](oid-receive-filter-free-queue.md). This OID requests the underlying miniport driver to free any VM queues that have been allocated on the network adapter. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh451653) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RECEIVE_FILTER_QUEUE_ALLOCATION_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-parameters.md b/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-parameters.md new file mode 100644 index 0000000000..cec99f18d5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-receive-filter-queue-parameters.md @@ -0,0 +1,89 @@ +--- +title: NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS +author: windows-driver-content +description: The NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS status indicates to NDIS and overlying drivers that the current virtual machine (VM) queue parameters have changed on the network adapter. +ms.assetid: 30782C77-578F-4533-8B6B-9D2F64EE6189 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_RECEIVE_FILTER_QUEUE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS + + +The **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS** status indicates to NDIS and overlying drivers that the current virtual machine (VM) queue parameters have changed on the network adapter. + +Remarks +------- + +The miniport driver must issue an **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS** status indication when the current VM queue parameters have changed on the network adapter. The VM queue parameters could change when one of the following conditions is true: + +- The VM queue parameters are changed through a management application developed by the independent hardware vendor (IHV). + +- The VM queue parameters change for one or more network adapters that belong to a load balancing failover (LBFO) team managed by a MUX intermediate driver. For more information, see [NDIS MUX Intermediate Drivers](https://msdn.microsoft.com/library/windows/hardware/ff566498). + +When the miniport driver issues the **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS** status indication, it must follow these steps: + +1. The miniport driver initializes an [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure with the current VM queue parameters on the network adapter. The driver must also set the **Flags** member of this structure with the appropriate NDIS\_RECEIVE\_QUEUE\_PARAMETERS\_*Xxx*\_CHANGED flags to report on **NDIS\_RECEIVE\_QUEUE\_PARAMETERS** member values that have changed. + + **Note**  Starting with NDIS 6.30, the miniport driver can only issue an **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS** status indication to report on changes to the **InterruptCoalescingDomainId** member. + +   + + When the miniport driver initializes the **Header** member of this structure, it sets the **Type** member of **Header** to NDIS\_OBJECT\_TYPE\_DEFAULT. The miniport driver sets the **Revision** member of **Header** to NDIS\_RECEIVE\_QUEUE\_PARAMETERS\_REVISION\_2 and the **Size** member to NDIS\_SIZEOF\_RECEIVE\_QUEUE\_PARAMETERS\_REVISION\_2. + +2. The miniport driver initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure in the following way: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS**. + + - The **StatusBuffer** member must be set to the pointer to a [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure. This structure contains the currently enabled hardware capabilities of the NIC switch. + + - The **StatusBufferSize** member must be set to sizeof([**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211)). + +3. The miniport driver issues the status notification by calling [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600). The driver must pass a pointer to the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure to the *StatusIndication* parameter. + +Overlying drivers can use the **NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS** status indication to determine the current VM queue parameters on the network adapter. Alternatively, these drivers can also issue object identifier (OID) query requests of [OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS](oid-receive-filter-queue-parameters.md) to obtain these parameters at any time. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS](oid-receive-filter-queue-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RECEIVE_FILTER_QUEUE_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-receive-queue-state.md b/windows-driver-docs-pr/network/ndis-status-receive-queue-state.md new file mode 100644 index 0000000000..c0b3d3acd3 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-receive-queue-state.md @@ -0,0 +1,70 @@ +--- +title: NDIS_STATUS_RECEIVE_QUEUE_STATE +author: windows-driver-content +description: The NDIS_STATUS_RECEIVE_QUEUE_STATE status indicates to overlying drivers that the queue state of a virtual machine queue (VMQ) receive queue has changed. +ms.assetid: 59b42de9-6aa5-445e-a39a-de2421c945ea +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RECEIVE_QUEUE_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RECEIVE\_QUEUE\_STATE + + +The NDIS\_STATUS\_RECEIVE\_QUEUE\_STATE status indicates to overlying drivers that the queue state of a virtual machine queue (VMQ) receive queue has changed. + +Remarks +------- + +NDIS 6.20 and later miniport drivers that support the virtual machine queue interface generate this status indication. + +The miniport driver supplies an [**NDIS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567214) structure in the **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure. + +The change to the *DMA Stopped* state is the only queue state change indication that is required. A miniport driver must indicate this state after it receives an [OID\_RECEIVE\_FILTER\_FREE\_QUEUE](https://msdn.microsoft.com/library/windows/hardware/ff569789) set request and stops the DMA. In this case, the miniport driver sets the **QueueState** member of the [**NDIS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567214) structure to **NdisReceiveQueueOperationalStateDmaStopped**. + +After the miniport driver receives the [OID\_RECEIVE\_FILTER\_FREE\_QUEUE](https://msdn.microsoft.com/library/windows/hardware/ff569789) set request, it must stop DMA to any shared memory that was allocated for the specified queue. + +If the miniport driver stopped the DMA for some other reason (for example, it freed the last filter on a queue), the queue should not enter the *DMA Stopped* state. However, the DMA can be stopped in the *Paused* or *Running* states if there are no filters set on the queue. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567214) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[OID\_RECEIVE\_FILTER\_FREE\_QUEUE](https://msdn.microsoft.com/library/windows/hardware/ff569789) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RECEIVE_QUEUE_STATE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-reset-end.md b/windows-driver-docs-pr/network/ndis-status-reset-end.md new file mode 100644 index 0000000000..0f9fe96c3f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-reset-end.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_RESET_END +author: windows-driver-content +description: The NDIS_STATUS_RESET_END status indicates that a miniport adapter reset operation is complete. +ms.assetid: 09ced263-9e4b-45e3-ae5e-db033a03b5b6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RESET_END Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RESET\_END + + +The NDIS\_STATUS\_RESET\_END status indicates that a miniport adapter reset operation is complete. + +Remarks +------- + +Miniport drivers should not call the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function to signal the start and finish of each reset operation because NDIS notifies overlying drivers when a reset operation begins and ends. + +When a miniport driver starts a reset operation, NDIS notifies the overlying drivers with an [**NDIS\_STATUS\_RESET\_START**](ndis-status-reset-start.md) status indication. + +After a bound protocol driver receives an NDIS\_STATUS\_RESET\_END status indication, the protocol driver can resume sending data and making OID requests. + +After an overlying filter or intermediate driver receives an NDIS\_STATUS\_RESET\_END status indication, the driver can resume sending data and making OID requests to overlying drivers. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_RESET\_START**](ndis-status-reset-start.md) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RESET_END%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-reset-start.md b/windows-driver-docs-pr/network/ndis-status-reset-start.md new file mode 100644 index 0000000000..0164a2f8bf --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-reset-start.md @@ -0,0 +1,76 @@ +--- +title: NDIS_STATUS_RESET_START +author: windows-driver-content +description: The NDIS_STATUS_RESET_START status indicates that a miniport adapter is being reset. +ms.assetid: 8758652b-137b-43e3-a896-8360f2b5051c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RESET_START Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RESET\_START + + +The NDIS\_STATUS\_RESET\_START status indicates that a miniport adapter is being reset. + +Remarks +------- + +Miniport drivers should not call the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function to signal the start and finish of each reset operation because NDIS notifies overlying drivers when a reset operation begins and ends. + +A miniport driver resets a miniport adapter when NDIS calls the miniport driver's [*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) function. NDIS calls the [*ProtocolStatusEx*](https://msdn.microsoft.com/library/windows/hardware/ff570270) function of each bound protocol and intermediate driver and the [*FilterStatus*](https://msdn.microsoft.com/library/windows/hardware/ff549973) function of the overlying filter modules with a status of NDIS\_STATUS\_RESET\_START. When the miniport driver completes the reset, NDIS notifies the overlying drivers with a status of [**NDIS\_STATUS\_RESET\_END**](ndis-status-reset-end.md). + +When a protocol driver receives an NDIS\_STATUS\_RESET\_START status indication, it should: + +- Hold any data that is ready to transmit until its *ProtocolStatusEx* function receives an NDIS\_STATUS\_RESET\_END status indication. + +- Not make any NDIS calls that are directed to the underlying miniport driver, except calls to return resources such as received data buffers with the [**NdisReturnNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff564534) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[*FilterStatus*](https://msdn.microsoft.com/library/windows/hardware/ff549973) + +[*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) + +[**NDIS\_STATUS\_RESET\_END**](ndis-status-reset-end.md) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +[**NdisReturnNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff564534) + +[*ProtocolStatusEx*](https://msdn.microsoft.com/library/windows/hardware/ff570270) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RESET_START%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-ring-status.md b/windows-driver-docs-pr/network/ndis-status-ring-status.md new file mode 100644 index 0000000000..def202c9eb --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-ring-status.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_RING_STATUS +author: windows-driver-content +description: The NDIS_STATUS_RING_STATUS status indicates the ring status of a line. A WAN-capable miniport driver can use this status to report a ring failure. +ms.assetid: 8971eeea-13ff-47d5-8167-83c061cad054 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_RING_STATUS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_RING\_STATUS + + +The NDIS\_STATUS\_RING\_STATUS status indicates the ring status of a line. A WAN-capable miniport driver can use this status to report a ring failure. + +Remarks +------- + +NDIS 4.*x* and earlier NDIS WAN miniport drivers use this status indication. NDIS 5.0 and later WAN miniport drivers must use the CoNDIS WAN interface. For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546752). + +The *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function contains a ULONG value with one of the following status values: + +NDIS\_RING\_LOBE\_WIRE\_FAULT + +NDIS\_RING\_HARD\_ERROR + +NDIS\_RING\_SIGNAL\_LOSS + +These values specify ring conditions that are the reason for the status indication. For more information about NDIS\_STATUS\_RING\_STATUS, see [Reporting Hardware Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff564044). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported for NDIS 6.0 drivers or NDIS 5.1 drivers in Windows Vista or Windows XP. Supported for NDIS 4.x drivers.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_RING_STATUS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-switch-nic-status.md b/windows-driver-docs-pr/network/ndis-status-switch-nic-status.md new file mode 100644 index 0000000000..8075c3f09c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-switch-nic-status.md @@ -0,0 +1,79 @@ +--- +title: NDIS_STATUS_SWITCH_NIC_STATUS +author: windows-driver-content +description: The NDIS_STATUS_SWITCH_NIC_STATUS status indication is used to encapsulate a status indication from a physical network adapter that is bound to the external network adapter of the Hyper-V extensible switch. +ms.assetid: 51A3BE6A-35F1-4AF0-91C0-94681640BD64 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_SWITCH_NIC_STATUS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_SWITCH\_NIC\_STATUS + + +The **NDIS\_STATUS\_SWITCH\_NIC\_STATUS** status indication is used to encapsulate a status indication from a physical network adapter that is bound to the external network adapter of the Hyper-V extensible switch. Through this encapsulation, the status indication is forwarded up the extensible switch driver stack. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for this indication contains a pointer to an [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure. + +Remarks +------- + +When an underlying physical network adapter issues an NDIS status indication, it is received by the external network adapter. When this happens, the extensible switch interface performs these steps: + +1. The interface encapsulates the status indication inside an [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure. + +2. The interface issues an **NDIS\_STATUS\_SWITCH\_NIC\_STATUS** status indication to forward the encapsulated status indication up the extensible switch driver stack. This allows extensible switch extensions to modify the encapsulated status indication. + + Typically, the extension modifies an encapsulated status indication to change the current offload capabilities of the underlying team of physical adapters that are bound to the external network adapter. + + For more information about the different configurations in which physical network adapters can be bound to the external network adapter, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +3. When the **NDIS\_STATUS\_SWITCH\_NIC\_STATUS** status indication is received by the overlying extensible switch protocol driver in the stack, the interface forwards the decapsulated status indication to overlying protocol or filter drivers. + +An extension can also originate encapsulated hardware offload status indications to overlying drivers in the extensible switch driver stack. This also allows the driver to change the current offload capabilities of the underlying team of physical adapters that are attached to the external network adapter. When a team of adapters are bound to the external network adapter, only the common capabilities of the team are advertised to NDIS or the overlying protocol and filter drivers. The extension can extend the advertised capabilities by originating encapsulated status indications to advertise capabilities that are supported by some adapters in the team. + +For example, the extension can issue an encapsulated [**NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES**](ndis-status-receive-filter-current-capabilities.md) indication to change the currently-enabled receive filter capabilities for the entire team. + +For more information on how to forward or originate **NDIS\_STATUS\_SWITCH\_NIC\_STATUS** indications, see [Managing NDIS Status Indications from Physical Network Adapters](https://msdn.microsoft.com/library/windows/hardware/hh598199). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES**](ndis-status-receive-filter-current-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_SWITCH_NIC_STATUS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-switch-port-remove-vf.md b/windows-driver-docs-pr/network/ndis-status-switch-port-remove-vf.md new file mode 100644 index 0000000000..848592efbd --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-switch-port-remove-vf.md @@ -0,0 +1,149 @@ +--- +title: NDIS_STATUS_SWITCH_PORT_REMOVE_VF +author: windows-driver-content +description: The NDIS_STATUS_SWITCH_PORT_REMOVE_VF status indication is issued by a Hyper-V extensible switch forwarding extension to remove the binding between a virtual machine (VM) network adapter and a PCI Express (PCIe) virtual function (VF). +ms.assetid: D6A52183-C9C6-4F0B-9E25-6C5C16CBEFFE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_SWITCH_PORT_REMOVE_VF Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF + + +The **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication is issued by a Hyper-V extensible switch forwarding extension to remove the binding between a virtual machine (VM) network adapter and a PCI Express (PCIe) virtual function (VF). The VF is exposed and supported by an underlying physical network adapter that supports the single root I/O virtualization (SR-IOV) interface. + +In order to issue the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication, the forwarding extension must encapsulate the indication in an [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure and issue an [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](ndis-status-switch-nic-status.md) status indication. + +For more information on this process, see [Guidelines for Issuing an **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** Status Indication](#issuing). + +Remarks +------- + +A PCIe VF is created and allocated by an underlying physical adapter that supports the SR-IOV interface. Once created, the virtualization stack attaches, or *assigns*, the VF to a Hyper-V child partition. The guest operating system that runs in this partition exposes a virtual machine (VM) network adapter that is bound to the VF of the underlying SR-IOV physical adapter. + +After the virtual and physical network adapters are assigned, packets are routed directly between the VF and the VM network adapter. However, because the extensible switch is not involved in packet delivery, extensible switch port policies are not applied to these packets. This includes port policies for access control lists (ACLs) and quality of service (QoS). + +An extensible switch forwarding extension can remove the assignment of the VF to the child partition by issuing an **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication. This indication causes the packets to be delivered through an extensible switch port instead of directly between the VM network adapter and the VF of the underlying SR-IOV physical adapter. This allows the extensible switch port policies to be applied to packets that are received or sent over the extensible switch port. + +When the forwarding extension makes the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication, it specifies the extensible switch port to which the VM network adapter is connected. + +For more information about extensible switch forwarding extensions, see [Forwarding Extensions](https://msdn.microsoft.com/library/windows/hardware/hh598148). + +### Guidelines for Issuing an NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF Status Indication + +In order to issue the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication, the forwarding extension must follow these steps: + +1. The forwarding extension initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** indication. For this indication, the forwarding extensions sets the following members of the **NDIS\_STATUS\_INDICATION** structure: + + - The **StatusCode** member must be set to **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF**. + + - The **StatusBuffer** member must be set to **NULL**. + + - The **StatusBufferSize** must be set to zero. + +2. The forwarding extension initializes an [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure. In order to remove a VF assignment, the forwarding extension must set the members in the following way: + + - The **DestinationPortId** member must be set to the identifier of an extensible switch port to which the VM network adapter is connected. + + - The **DestinationNicIndex** member must be set to the index value of the VM network adapter that is connected to the specified port. + + - The **SourcePortId** member must be set to **NDIS\_SWITCH\_DEFAULT\_PORT\_ID**. + + - The **SourceNicIndex** member must be set to **NDIS\_SWITCH\_DEFAULT\_NIC\_INDEX**. + + - The **StatusIndication** member must be set to the address of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** indication. + +3. The forwarding extension initializes an [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) indication. For this indication, the forwarding extension sets the following members of the **NDIS\_STATUS\_INDICATION** structure: + + - The **StatusCode** member must be set to [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](ndis-status-switch-nic-status.md). + + - The **StatusBuffer** member must be set to the address of the [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure. + + - The **StatusBufferSize** must be set to the length, in bytes, of the [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) structure and the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure for the **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** indication. + +4. The forwarding extension must call [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment a reference counter for the VM network adapter. If *ReferenceSwitchNic* does not complete with NDIS\_STATUS\_SUCCESS, the forwarding extension must not forward the status indication. + + **Note**  If the forwarding extension has received an [OID\_SWITCH\_NIC\_DISCONNECT](https://msdn.microsoft.com/library/windows/hardware/hh598265) set request for the VM adapter, it must not call [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) nor forward the status indication. + +   + +5. The forwarding extension calls [**NdisFIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff561824) to forward the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) to overlying extensions in the extensible switch driver stack. When the forwarding extension calls this function, it sets the *StatusIndication* parameter to a pointer to the **NDIS\_STATUS\_INDICATION** structure for the [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](ndis-status-switch-nic-status.md) indication. + +6. After [**NdisFIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff561824) returns, the forwarding extension must call [*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141) to decrement the reference counter for the VM network adapter. + +**Note**  The forwarding extension must follow the previous steps for each VF assignment that the forwarding extension is removing. + +  + +For more information on how a forwarding extension forwards status indications, see [Filter Module Status Indications](https://msdn.microsoft.com/library/windows/hardware/ff550020). + +### Guidelines for Determining VF Assignments + +The forwarding extension can enumerate the current VF assignments for virtual network adapters by issuing an OID query request of [OID\_SWITCH\_NIC\_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598261). This request returns an [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure that contains an array of [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structures. Each **NDIS\_SWITCH\_NIC\_PARAMETERS** structure specifies the parameters of a network adapter that is exposed in one of the following environments: + +- The management operating system that runs in the Hyper-V parent partition. + + Network adapters that are exposed in this operating system are specified with an [**NDIS\_SWITCH\_NIC\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh598218) enumeration value of **NdisSwitchNicTypeExternal** or **NdisSwitchNicTypeInternal**. + +- The guest operating system that runs in a Hyper-V child partition. + + Network adapters that are exposed in this operating system are specified with an [**NDIS\_SWITCH\_NIC\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh598218) enumeration value of **NdisSwitchNicTypeSynthetic** or **NdisSwitchNicTypeEmulated**. + +If the OID query request of [OID\_SWITCH\_NIC\_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598261) completes with a status of NDIS\_STATUS\_SUCCESS, the forwarding extension can determine VF assignments by inspecting each [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure in the returned array. If the **VFAssigned** member of the **NDIS\_SWITCH\_NIC\_PARAMETERS** structure is set to **TRUE**, the network adapter that corresponds to the **NDIS\_SWITCH\_NIC\_PARAMETERS** structure is assigned to a VF. + +The forwarding extension can remove the assignment by issuing an **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication. In this case, the forwarding extension must set the **DestinationPortId** member of the [**NDIS\_SWITCH\_NIC\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/hh598217) to the value of the **PortId** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +For more information on how to issue an **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** status indication, see [Guidelines for Issuing an **NDIS\_STATUS\_SWITCH\_PORT\_REMOVE\_VF** Status Indication](#issuing). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisFIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff561824) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](ndis-status-switch-nic-status.md) + +[**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[**NDIS\_SWITCH\_NIC\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh598218) + +[OID\_SWITCH\_NIC\_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598261) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_SWITCH_PORT_REMOVE_VF%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-tapi-indication.md b/windows-driver-docs-pr/network/ndis-status-tapi-indication.md new file mode 100644 index 0000000000..a771795de3 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-tapi-indication.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_TAPI_INDICATION +author: windows-driver-content +description: The NDIS_STATUS_TAPI_INDICATION status indicates that a TAPI event occurred. A WAN-capable miniport driver can indicate TAPI status. +ms.assetid: b90c5524-2e03-45e1-9ec9-478112eba01b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_TAPI_INDICATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_TAPI\_INDICATION + + +The NDIS\_STATUS\_TAPI\_INDICATION status indicates that a TAPI event occurred. A WAN-capable miniport driver can indicate TAPI status. + +Remarks +------- + +NDIS 4.*x* and earlier NDIS WAN miniport drivers use this status indication. NDIS 5.0 and later WAN miniport drivers must use the CoNDIS WAN interface. For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546752). + +The *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function contains a pointer to an [**NDIS\_TAPI\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff558986) structure.The NDIS\_TAPI\_EVENT structure describes the TAPI line or call event that occurs (for example, changes in line and call states, the arrival of an incoming call, and the closing by a remote node or by the miniport driver of an existing call or line). + +For more information about NDIS\_STATUS\_TAPI\_INDICATION, see [Indicating NDIS WAN Miniport Driver Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546867). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported for NDIS 6.0 drivers or NDIS 5.1 drivers in Windows Vista or Windows XP. Supported for NDIS 4.x drivers.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_TAPI\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff558986) + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_TAPI_INDICATION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-task-offload-current-config.md b/windows-driver-docs-pr/network/ndis-status-task-offload-current-config.md new file mode 100644 index 0000000000..1d6d4f095b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-task-offload-current-config.md @@ -0,0 +1,83 @@ +--- +title: NDIS_STATUS_TASK_OFFLOAD_CURRENT_CONFIG +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_TASK_OFFLOAD_CURRENT_CONFIG status indication to notify NDIS and overlying drivers that there has been a change in the task offload configuration of a NIC. +ms.assetid: 8a098dff-409e-4168-a3aa-372851aa999d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_TASK_OFFLOAD_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG + + +Miniport drivers use the **NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG** status indication to notify NDIS and overlying drivers that there has been a change in the task offload configuration of a NIC. + +Remarks +------- + +Miniport drivers must report the current capabilities with the **NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG** status indication when current capabilities change. This status indication ensures that all of the overlying protocol drivers are updated with the new capabilities information. Miniport drivers are required to issue this status indication in the following cases: + +1. When a miniport driver receives an [OID\_TCP\_OFFLOAD\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569807) set request, it must use the contents of the [**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) structure to update the currently-enabled task offload capabilities. +2. When a miniport driver receives an [OID\_OFFLOAD\_ENCAPSULATION](https://msdn.microsoft.com/library/windows/hardware/ff569762) set request, it must use the contents of the [**NDIS\_OFFLOAD\_ENCAPSULATION**](https://msdn.microsoft.com/library/windows/hardware/ff566702) structure to update the currently-enabled task offload capabilities. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains an [**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566599) structure. When issuing the **NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG** status indication, a miniport driver must use the **NDIS\_OFFLOAD** structure to report the current task offload configuration of the NIC. + +**Note**  The contents of the [**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566599) structure reflect only the NIC's current task offload configuration, not its actual hardware capabilities. + +  + +For more information about the current task offload configuration, see [OID\_TCP\_OFFLOAD\_CURRENT\_CONFIG](https://msdn.microsoft.com/library/windows/hardware/ff569805). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566599) + +[**NDIS\_OFFLOAD\_ENCAPSULATION**](https://msdn.microsoft.com/library/windows/hardware/ff566702) + +[**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_TASK\_OFFLOAD\_HARDWARE\_CAPABILITIES**](ndis-status-task-offload-hardware-capabilities.md) + +[OID\_OFFLOAD\_ENCAPSULATION](https://msdn.microsoft.com/library/windows/hardware/ff569762) + +[OID\_TCP\_OFFLOAD\_CURRENT\_CONFIG](https://msdn.microsoft.com/library/windows/hardware/ff569805) + +[OID\_TCP\_OFFLOAD\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569807) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_TASK_OFFLOAD_CURRENT_CONFIG%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-task-offload-hardware-capabilities.md b/windows-driver-docs-pr/network/ndis-status-task-offload-hardware-capabilities.md new file mode 100644 index 0000000000..42cd262079 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-task-offload-hardware-capabilities.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_TASK_OFFLOAD_HARDWARE_CAPABILITIES +author: windows-driver-content +description: NDIS miniport drivers and MUX intermediate drivers use the NDIS_STATUS_TASK_OFFLOAD_HARDWARE_CAPABILITIES status indication to notify NDIS and overlying drivers that there has been change in the task offload hardware capabilities of the underlying NIC. +ms.assetid: 9ac8f4c9-66f4-4889-932b-a51381c54734 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_TASK_OFFLOAD_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_TASK\_OFFLOAD\_HARDWARE\_CAPABILITIES + + +NDIS miniport drivers and MUX intermediate drivers use the **NDIS\_STATUS\_TASK\_OFFLOAD\_HARDWARE\_CAPABILITIES** status indication to notify NDIS and overlying drivers that there has been change in the task offload hardware capabilities of the underlying NIC. + +Remarks +------- + +If an underlying NIC is added or deleted, the overall set of hardware capabilities that is associated with a miniport driver or MUX intermediate driver can change. For example, if a miniport driver issues the **NDIS\_STATUS\_TASK\_OFFLOAD\_HARDWARE\_CAPABILITIES** status indication, specifying that it cannot support Large Send Offload (LSO), the NIC can no longer be configured to support LSO. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains an [**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566599) structure. This structure specifies the task offload hardware capabilities. + +For more information about task offload hardware capabilities, see [OID\_TCP\_OFFLOAD\_HARDWARE\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569806). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566599) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG**](ndis-status-task-offload-current-config.md) + +[OID\_TCP\_OFFLOAD\_HARDWARE\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569806) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_TASK_OFFLOAD_HARDWARE_CAPABILITIES%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-tcp-connection-offload-hardware-capabilities.md b/windows-driver-docs-pr/network/ndis-status-tcp-connection-offload-hardware-capabilities.md new file mode 100644 index 0000000000..6f9e6e0f7a --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-tcp-connection-offload-hardware-capabilities.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_TCP_CONNECTION_OFFLOAD_HARDWARE_CAPABILITIES +author: windows-driver-content +description: MUX intermediate drivers use the NDIS_STATUS_TCP_CONNECTION_OFFLOAD_HARDWARE_CAPABILITIES CAPABILITIES status indication to notify NDIS and overlying drivers that there has been change in the connection offload characteristics of the underlying hardware. +ms.assetid: 694cc0c4-0987-4095-8490-14ddfc9eaedb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_TCP_CONNECTION_OFFLOAD_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_TCP\_CONNECTION\_OFFLOAD\_HARDWARE\_CAPABILITIES + + +MUX intermediate drivers use the NDIS\_STATUS\_TCP\_CONNECTION\_OFFLOAD\_HARDWARE\_CAPABILITIES CAPABILITIES status indication to notify NDIS and overlying drivers that there has been change in the connection offload characteristics of the underlying hardware. + +Remarks +------- + +If an underlying NIC is added or deleted, the overall set of hardware capabilities that is associated with a MUX intermediate driver can change. + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains an [**NDIS\_TCP\_CONNECTION\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567875) structure. NDIS\_TCP\_CONNECTION\_OFFLOAD specifies the task offload hardware capabilities. + +For more information about task offload hardware capabilities, see [OID\_TCP\_CONNECTION\_OFFLOAD\_HARDWARE\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569803). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_TCP\_CONNECTION\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567875) + +[OID\_TCP\_CONNECTION\_OFFLOAD\_HARDWARE\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff569803) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_TCP_CONNECTION_OFFLOAD_HARDWARE_CAPABILITIES%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-co-fragment.md b/windows-driver-docs-pr/network/ndis-status-wan-co-fragment.md new file mode 100644 index 0000000000..5b33a52f29 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-co-fragment.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_WAN_CO_FRAGMENT +author: windows-driver-content +description: The NDIS_STATUS_WAN_CO_FRAGMENT status indicates that a CoNDIS WAN miniport driver has received a partial packet from the endpoint of a VC. +ms.assetid: 5a534364-d528-45f8-a2e0-3c745b3b5ad0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_CO_FRAGMENT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_CO\_FRAGMENT + + +The NDIS\_STATUS\_WAN\_CO\_FRAGMENT status indicates that a CoNDIS WAN miniport driver has received a partial packet from the endpoint of a VC. + +Remarks +------- + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a pointer to an [**NDIS\_WAN\_CO\_FRAGMENT**](https://msdn.microsoft.com/library/windows/hardware/ff559030) structure. The NDIS\_WAN\_CO\_FRAGMENT structure describes the reason that the partial packet was received. + +For more information about NDIS\_STATUS\_WAN\_CO\_FRAGMENT, see [Indicating CoNDIS WAN Miniport Driver Status](https://msdn.microsoft.com/library/windows/hardware/ff554825). For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff553805). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_WAN\_CO\_FRAGMENT**](https://msdn.microsoft.com/library/windows/hardware/ff559030) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_CO_FRAGMENT%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-co-linkparams.md b/windows-driver-docs-pr/network/ndis-status-wan-co-linkparams.md new file mode 100644 index 0000000000..f4ad299002 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-co-linkparams.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_WAN_CO_LINKPARAMS +author: windows-driver-content +description: The NDIS_STATUS_WAN_CO_FRAGMENT status indicates that parameters for a particular VC that is active on a CoNDIS miniport adapter have changed. +ms.assetid: a28460fc-c9e6-49c4-949a-badd3491cdd6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_CO_LINKPARAMS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_CO\_LINKPARAMS + + +The NDIS\_STATUS\_WAN\_CO\_FRAGMENT status indicates that parameters for a particular VC that is active on a CoNDIS miniport adapter have changed. + +Remarks +------- + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a pointer to a [**WAN\_CO\_LINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565819) structure. The WAN\_CO\_LINKPARAMS structure describes new parameters for the VC. + +For more information about NDIS\_STATUS\_WAN\_CO\_LINKPARAMS, see [Indicating CoNDIS WAN Miniport Driver Status](https://msdn.microsoft.com/library/windows/hardware/ff554825). For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff553805). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**WAN\_CO\_LINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565819) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_CO_LINKPARAMS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-co-mtulinkparams.md b/windows-driver-docs-pr/network/ndis-status-wan-co-mtulinkparams.md new file mode 100644 index 0000000000..8cace23f8b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-co-mtulinkparams.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_WAN_CO_MTULINKPARAMS +author: windows-driver-content +description: The NDIS_STATUS_WAN_CO_MTULINKPARAMS status indicates that the link speed and send window parameters have changed for a particular VC that is active on a CoNDIS miniport adapter. +ms.assetid: 1ba67087-08aa-4359-9884-e47bf634fda5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_CO_MTULINKPARAMS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_CO\_MTULINKPARAMS + + +The NDIS\_STATUS\_WAN\_CO\_MTULINKPARAMS status indicates that the link speed and send window parameters have changed for a particular VC that is active on a CoNDIS miniport adapter. + +Remarks +------- + +The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains a pointer to a [**WAN\_CO\_MTULINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565821) structure. The WAN\_CO\_MTULINKPARAMS structure describes new parameters for the VC. + +For more information about NDIS\_STATUS\_WAN\_CO\_MTULINKPARAMS, see [Indicating CoNDIS WAN Miniport Driver Status](https://msdn.microsoft.com/library/windows/hardware/ff554825). For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff553805). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**WAN\_CO\_MTULINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565821) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_CO_MTULINKPARAMS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-fragment.md b/windows-driver-docs-pr/network/ndis-status-wan-fragment.md new file mode 100644 index 0000000000..9a4f545477 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-fragment.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_WAN_FRAGMENT +author: windows-driver-content +description: The NDIS_STATUS_WAN_FRAGMENT status indicates that a WAN-capable miniport driver has received a partial packet from a remote node. +ms.assetid: 1ac00110-8b97-4905-b409-454e3d9a09e0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_FRAGMENT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_FRAGMENT + + +The NDIS\_STATUS\_WAN\_FRAGMENT status indicates that a WAN-capable miniport driver has received a partial packet from a remote node. + +Remarks +------- + +NDIS 4.*x* and earlier NDIS WAN miniport drivers use this status indication. NDIS 5.0 and later miniport drivers should use the CoNDIS WAN interface. For more information about NDIS\_STATUS\_WAN\_FRAGMENT, see [**NDIS\_STATUS\_WAN\_CO\_FRAGMENT**](ndis-status-wan-co-fragment.md). + +The *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function contains a pointer to an [**NDIS\_MAC\_FRAGMENT**](https://msdn.microsoft.com/library/windows/hardware/ff557055) structure. NDIS\_MAC\_FRAGMENT identifies a particular link and describes the reason that the partial packet was received. + +For more information about NDIS\_STATUS\_WAN\_FRAGMENT, see [Indicating NDIS WAN Miniport Driver Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546867). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported for NDIS 6.0 drivers or NDIS 5.1 drivers in Windows Vista or Windows XP. Supported for NDIS 4.x drivers.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MAC\_FRAGMENT**](https://msdn.microsoft.com/library/windows/hardware/ff557055) + +[**NDIS\_STATUS\_WAN\_CO\_FRAGMENT**](ndis-status-wan-co-fragment.md) + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_FRAGMENT%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-line-down.md b/windows-driver-docs-pr/network/ndis-status-wan-line-down.md new file mode 100644 index 0000000000..65c4012053 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-line-down.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_WAN_LINE_DOWN +author: windows-driver-content +description: The NDIS_STATUS_WAN_LINE_DOWN status indicates that a WAN-capable miniport driver has lost an established connection with a remote node. +ms.assetid: 85904e2f-ae34-4cca-a5b9-2ec4b342672a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_LINE_DOWN Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_LINE\_DOWN + + +The NDIS\_STATUS\_WAN\_LINE\_DOWN status indicates that a WAN-capable miniport driver has lost an established connection with a remote node. + +Remarks +------- + +NDIS 4.*x* and earlier NDIS WAN miniport drivers use this status indication. NDIS 5.0 and later WAN miniport drivers must use the CoNDIS WAN interface. For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546752). + +The *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function contains a pointer to an [**NDIS\_MAC\_LINE\_DOWN**](https://msdn.microsoft.com/library/windows/hardware/ff557057) structure. The **NdisLinkContext** member of NDIS\_MAC\_LINE\_DOWN identifies the link that is no longer valid. + +For more information about NDIS\_STATUS\_WAN\_LINE\_DOWN, see [Indicating NDIS WAN Miniport Driver Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546867). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported for NDIS 6.0 drivers or NDIS 5.1 drivers in Windows Vista or Windows XP. Supported for NDIS 4.x drivers.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MAC\_LINE\_DOWN**](https://msdn.microsoft.com/library/windows/hardware/ff557057) + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_LINE_DOWN%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wan-line-up.md b/windows-driver-docs-pr/network/ndis-status-wan-line-up.md new file mode 100644 index 0000000000..0e512f2880 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wan-line-up.md @@ -0,0 +1,64 @@ +--- +title: NDIS_STATUS_WAN_LINE_UP +author: windows-driver-content +description: The NDIS_STATUS_WAN_LINE_UP status indicates that a WAN-capable miniport driver has established a connection with a remote node. +ms.assetid: 1eb9d934-871a-4d95-b04f-d0b174716c98 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WAN_LINE_UP Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WAN\_LINE\_UP + + +The NDIS\_STATUS\_WAN\_LINE\_UP status indicates that a WAN-capable miniport driver has established a connection with a remote node. + +Remarks +------- + +NDIS 4.*x* and earlier NDIS WAN miniport drivers use this status indication. NDIS 5.0 and later WAN miniport drivers must use the CoNDIS WAN interface. For more information about the CoNDIS WAN interface, see [Implementing CoNDIS WAN Miniport Drivers (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546752). + +The *StatusBuffer* parameter of the [**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) function contains a pointer to an [**NDIS\_MAC\_LINE\_UP**](https://msdn.microsoft.com/library/windows/hardware/ff557058) structure. + +For more information about NDIS\_STATUS\_WAN\_LINE\_UP, see [Line-Up Indication (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff549189) and [Indicating NDIS WAN Miniport Driver Status (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff546867). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported for NDIS 6.0 drivers or NDIS 5.1 drivers in Windows Vista or Windows XP. Supported for NDIS 4.x drivers.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MAC\_LINE\_UP**](https://msdn.microsoft.com/library/windows/hardware/ff557058) + +[**NdisMIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553538) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WAN_LINE_UP%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-action-frame-received.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-action-frame-received.md new file mode 100644 index 0000000000..47dbc56219 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-action-frame-received.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_ACTION_FRAME_RECEIVED +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_ACTION_FRAME_RECEIVED to indicate that an Action Frame has been received. +ms.assetid: C1F6EB50-C11F-428F-BF51-5C89A59CBF76 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_ACTION_FRAME_RECEIVED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_ACTION\_FRAME\_RECEIVED + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_ACTION\_FRAME\_RECEIVED to indicate that an Action Frame has been received. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](https://msdn.microsoft.com/library/windows/hardware/dn926153) | | | The BSSID of the source. | +| [**WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn926155) | | | The logical channel number and band ID for the BSS entry. | +| [**WDI\_TLV\_ACTION\_FRAME\_BODY**](https://msdn.microsoft.com/library/windows/hardware/dn926118) | | | The incoming Action Frame body. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_ADVERTISEMENT\_INFORMATION](oid-wdi-set-advertisement-information.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_ACTION_FRAME_RECEIVED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-ap-association-request-received.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ap-association-request-received.md new file mode 100644 index 0000000000..fb219642b1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ap-association-request-received.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_AP_ASSOCIATION_REQUEST_RECEIVED +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_AP_ASSOCIATION_REQUEST_RECEIVED to indicate that a Wi-Fi Association Request Frame has been received for an operational Wi-Fi Direct Group Owner. +ms.assetid: c207ada5-39fd-4326-9b62-4844d3bb01af +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_AP_ASSOCIATION_REQUEST_RECEIVED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_AP\_ASSOCIATION\_REQUEST\_RECEIVED + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_AP\_ASSOCIATION\_REQUEST\_RECEIVED to indicate that a Wi-Fi Association Request Frame has been received for an operational Wi-Fi Direct Group Owner. The host may issue an [OID\_WDI\_TASK\_SEND\_AP\_ASSOCIATION\_RESPONSE](oid-wdi-task-send-ap-association-response.md) for this request. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------| +| [**WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn926315) | | | The incoming Association Request information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_AP_ASSOCIATION_REQUEST_RECEIVED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-parameters-request.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-parameters-request.md new file mode 100644 index 0000000000..66eb8a5c34 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-parameters-request.md @@ -0,0 +1,75 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_ASSOCIATION_PARAMETERS_REQUEST +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_ASSOCIATION_PARAMETERS_REQUEST to request association parameters for a set of BSSIDs from the host. +ms.assetid: 2c8aef86-bb4a-47c6-a839-eb14eb430a31 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_ASSOCIATION_PARAMETERS_REQUEST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_PARAMETERS\_REQUEST + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_PARAMETERS\_REQUEST to request association parameters for a set of BSSIDs from the host. + +| Object | +|--------| +| Port | + +  + +This indication can be sent by the adapter when it finds a BSS entry that is a candidate for association based on the current settings. Upon receiving this indication, the host checks if the association parameters are available, and if so, sends them with [OID\_WDI\_SET\_ASSOCIATION\_PARAMETERS](oid-wdi-set-association-parameters.md). + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------| +| [**WDI\_TLV\_ASSOCIATION\_PARAMETERS\_REQUESTED\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926131) | | | The list of requested association parameters. | +| [**WDI\_TLV\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926162) | X | X | The list of BSSIDs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_CONNECT](oid-wdi-task-connect.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_ASSOCIATION_PARAMETERS_REQUEST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-result.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-result.md new file mode 100644 index 0000000000..8cf84ef1f0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-association-result.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_ASSOCIATION_RESULT +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_ASSOCIATION_RESULT to indicate association results. +ms.assetid: dc025aec-30f4-4a78-b449-acc49d13b507 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_ASSOCIATION_RESULT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_RESULT + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_RESULT to indicate association results. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------|--------------------------------|----------|--------------------------------| +| [**WDI\_TLV\_ASSOCIATION\_RESULT**](https://msdn.microsoft.com/library/windows/hardware/dn926140) | X | | A list of association results. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_CONNECT](oid-wdi-task-connect.md) + +[OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_ASSOCIATION_RESULT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-bss-entry-list.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-bss-entry-list.md new file mode 100644 index 0000000000..8e7777a9f6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-bss-entry-list.md @@ -0,0 +1,76 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_BSS_ENTRY_LIST +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_BSS_ENTRY_LIST to inform the host about updates to the BSS entries. This is an unsolicited indication and can be sent at any time. +ms.assetid: 5b9fd7b1-0817-4b86-9acc-b4f99cb7ae9a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_BSS_ENTRY_LIST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST to inform the host about updates to the BSS entries. This is an unsolicited indication and can be sent at any time. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------|--------------------------------|----------|-----------------------------| +| [**WDI\_TLV\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926162) | X | X | The list of updated BSSIDs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_SCAN](oid-wdi-task-scan.md) + +[OID\_WDI\_TASK\_P2P\_DISCOVER](oid-wdi-task-p2p-discover.md) + +[OID\_WDI\_SET\_P2P\_START\_BACKGROUND\_DISCOVERY](oid-wdi-set-p2p-start-background-discovery.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_BSS_ENTRY_LIST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-can-sustain-ap.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-can-sustain-ap.md new file mode 100644 index 0000000000..326b3599af --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-can-sustain-ap.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_CAN_SUSTAIN_AP +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_CAN_SUSTAIN_AP to indicate that the port is ready to receive a OID_WDI_TASK_START_AP request, after previously indicating NDIS_STATUS_WDI_INDICATION_STOP_AP. +ms.assetid: 638822A9-4CED-4564-86B3-8BC9DBA05DD3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_CAN_SUSTAIN_AP Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP to indicate that the port is ready to receive a [OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md) request, after previously indicating [NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP](ndis-status-wdi-indication-stop-ap.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------| +| [**WDI\_TLV\_INDICATION\_CAN\_SUSTAIN\_AP**](https://msdn.microsoft.com/library/windows/hardware/dn926317) | | | The reason the adapter can now sustain 802.11 AP functionality. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_CAN_SUSTAIN_AP%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-change-operation-mode-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-change-operation-mode-complete.md new file mode 100644 index 0000000000..42aa8cc10f --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-change-operation-mode-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_CHANGE_OPERATION_MODE_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_CHANGE_OPERATION_MODE_COMPLETE to indicate the completion of OID_WDI_TASK_CHANGE_OPERATION_MODE. +ms.assetid: fa2a6544-c3ef-4a20-9182-f3678488053d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_CHANGE_OPERATION_MODE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_CHANGE\_OPERATION\_MODE\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_CHANGE\_OPERATION\_MODE\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_CHANGE\_OPERATION\_MODE](oid-wdi-task-change-operation-mode.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_CHANGE_OPERATION_MODE_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-close-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-close-complete.md new file mode 100644 index 0000000000..c71dae70e1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-close-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_CLOSE_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_CLOSE_COMPLETE to indicate the completion of OID_WDI_TASK_CLOSE. +ms.assetid: 3819eff9-4d94-4d0d-b98b-71bfe54c4ecf +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_CLOSE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_CLOSE\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_CLOSE\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_CLOSE](oid-wdi-task-close.md). + +| Object | +|---------| +| Adapter | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_CLOSE_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-connect-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-connect-complete.md new file mode 100644 index 0000000000..81c60e8689 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-connect-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_CONNECT_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_CONNECT_COMPLETE to indicate the completion of OID_WDI_TASK_CONNECT. +ms.assetid: f181f3e4-310f-4346-a6aa-f10398027194 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_CONNECT_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_CONNECT\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_CONNECT\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_CONNECT](oid-wdi-task-connect.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_CONNECT_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-create-port-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-create-port-complete.md new file mode 100644 index 0000000000..99a0241e4d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-create-port-complete.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_CREATE_PORT_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_CREATE_PORT_COMPLETE to indicate the completion of OID_WDI_TASK_CREATE_PORT. +ms.assetid: 8d3cdac1-06d3-4a21-ac13-e6d789c6922e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_CREATE_PORT_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_CREATE\_PORT\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_CREATE\_PORT\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_CREATE\_PORT](oid-wdi-task-create-port.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------|--------------------------------|----------|-------------------------------------| +| [**WDI\_TLV\_PORT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/dn898038) | | | The attributes of the created port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_CREATE_PORT_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-delete-port-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-delete-port-complete.md new file mode 100644 index 0000000000..ad4bd6af32 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-delete-port-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_DELETE_PORT_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_DELETE_PORT_COMPLETE to indicate the completion of OID_WDI_TASK_DELETE_PORT. +ms.assetid: 56156ba2-1ee1-445f-a413-6fa4b3092357 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_DELETE_PORT_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_DELETE\_PORT\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_DELETE\_PORT\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_DELETE\_PORT](oid-wdi-task-delete-port.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_DELETE_PORT_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-disassociation.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-disassociation.md new file mode 100644 index 0000000000..88f3f49a3a --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-disassociation.md @@ -0,0 +1,86 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_DISASSOCIATION +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_DISASSOCIATION to indicate that a port disconnected from the network. +ms.assetid: 4e3ed3ed-1b96-49ea-b60f-a36d2a3fc082 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_DISASSOCIATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION to indicate that a port disconnected from the network. + +| Object | +|--------| +| Port | + +  + +The disconnect may be triggered by a command from the operating system or triggered from the network. Network triggered disconnect may be explicit from received disassociation or deauthentication packets, or may be implicit when the port cannot detect the presence of the peer it is connected to. + +Before the disassociation indication is sent, the port must clear the state associated with this peer. This includes any keys and 802.1x port authorization information associated with this peer. The port must not trigger a roam on its own. + +## Payload data + + +Type +Multiple TLV instances allowed +Optional +Description +[**WDI\_TLV\_DISASSOCIATION\_INDICATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926292) +The disassociation indication parameters. +[**WDI\_TLV\_DISCONNECT\_DEAUTH\_FRAME**](https://msdn.microsoft.com/library/windows/hardware/dn926296) +X +The deauthentication frame that was received. This does not include the 802.11 MAC header. +[**WDI\_TLV\_DISCONNECT\_DISASSOCIATION\_FRAME**](https://msdn.microsoft.com/library/windows/hardware/dn926298) +X +The disassociation frame that was received. This does not include the 802.11 MAC header. +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_DISCONNECT](oid-wdi-task-disconnect.md) + +[OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_DISASSOCIATION%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-disconnect-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-disconnect-complete.md new file mode 100644 index 0000000000..0056fb62cf --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-disconnect-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_DISCONNECT_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_DISCONNECT_COMPLETE to indicate the completion of OID_WDI_TASK_DISCONNECT. +ms.assetid: 07f14f77-04e9-4991-9a50-9e2d13afcfe9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_DISCONNECT_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_DISCONNECT\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_DISCONNECT\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_DISCONNECT](oid-wdi-task-disconnect.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_DISCONNECT_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-dot11-reset-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-dot11-reset-complete.md new file mode 100644 index 0000000000..5a1e6af4ea --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-dot11-reset-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_DOT11_RESET_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_DOT11_RESET_COMPLETE to indicate the completion of OID_WDI_TASK_DOT11_RESET. +ms.assetid: bef0eb15-5089-4b42-9d89-d45d1145d8e7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_DOT11_RESET_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_DOT11\_RESET\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_DOT11\_RESET\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_DOT11\_RESET](oid-wdi-task-dot11-reset.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_DOT11_RESET_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-firmware-stalled.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-firmware-stalled.md new file mode 100644 index 0000000000..325d573321 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-firmware-stalled.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_FIRMWARE_STALLED +author: windows-driver-content +description: NDIS_STATUS_WDI_INDICATION_FIRMWARE_STALLED is used to indicate that the firmware stalled. +ms.assetid: 0A0E1446-4FDD-4FB2-8CA7-04FBF5D6DDD1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_FIRMWARE_STALLED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_FIRMWARE\_STALLED + + +NDIS\_STATUS\_WDI\_INDICATION\_FIRMWARE\_STALLED is used to indicate that the firmware stalled. + +| Object | +|---------| +| Adapter | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_FIRMWARE_STALLED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-ft-assoc-params-needed.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ft-assoc-params-needed.md new file mode 100644 index 0000000000..efb8a705dc --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ft-assoc-params-needed.md @@ -0,0 +1,78 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED to request parameters for 802.11r roaming.ObjectPort . +ms.assetid: AB745908-AA7B-416A-9C97-B376293F3DEE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_FT\_ASSOC\_PARAMS\_NEEDED + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_FT\_ASSOC\_PARAMS\_NEEDED to request parameters for 802.11r roaming. + +| Object | +|--------| +| Port | + +  + +During [OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md), WDI provides the parameters to send the 802.11 Authentication Request (PmkR0Name, R0KH-ID, SNonce, MDIE). Upon receiving the Authentication response, the LE requests additional needed parameters for the reassociation request, such as PMKR1Name and R1KH-ID. The LE also sends the parameters received in the Authentication Response (ANonce, SNonce, and R1KHID). + +For a connection where Initial Mobility Domain is successfully done, the LE should only perform 11r roams (Fast roams). The LE can use the candidate list provided by the operating system, or use their own for the roams. If the LE uses its own candidate list, it must use the parameters (MDE, FTE, and PMKR0Name) provided in any one of the candidates suggested by the operating system to do a 11r roam. 11r is disabled whenever the connection is in FIPS mode. 11r fast roaming is currently only supported for FT over 1x authentication type. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------|--------------------------------|----------|----------------------------------------| +| [**WDI\_TLV\_BSSID**](https://msdn.microsoft.com/library/windows/hardware/dn926153) | | | The BSSID of the AP. | +| [**WDI\_TLV\_FT\_AUTH\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/mt269116) | | | The authentication request byte blob. | +| [**WDI\_TLV\_FT\_AUTH\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/mt269117) | | | The authentication response byte blob. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-event.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-event.md new file mode 100644 index 0000000000..12a739f9ee --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-event.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_IHV_EVENT +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_IHV_EVENT to pass IHV specific information to the IHV extensibility module. +ms.assetid: 767f15cd-456f-4d91-9b78-58f8f8b7a465 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_IHV_EVENT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_IHV\_EVENT + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_IHV\_EVENT to pass IHV specific information to the IHV extensibility module. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------| +| [**WDI\_TLV\_IHV\_DATA**](https://msdn.microsoft.com/library/windows/hardware/dn926312) | | X | The event to be sent to the IHV extensibility module. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_IHV_EVENT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-complete.md new file mode 100644 index 0000000000..2206e83cf2 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_IHV_TASK_COMPLETE +author: windows-driver-content +description: NDIS_STATUS_WDI_INDICATION_IHV_TASK_COMPLETE indicates the completion of OID_WDI_TASK_IHV. +ms.assetid: 03EA1580-110D-483B-BD4D-9275A7AC18A8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_IHV_TASK_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_COMPLETE + + +NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_COMPLETE indicates the completion of [OID\_WDI\_TASK\_IHV](oid-wdi-task-ihv.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. The completion status from the message is not forwarded to anyone. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_IHV_TASK_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-request.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-request.md new file mode 100644 index 0000000000..f8175a3680 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-ihv-task-request.md @@ -0,0 +1,73 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST to request that the Microsoft component queue an IHV task.ObjectPort . +ms.assetid: E123F957-574F-4C78-B366-76E886018503 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST to request that the Microsoft component queue an IHV task. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_IHV\_TASK\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926314) | | | The IHV-requested priority for this task. Refer to the [**WDI\_IHV\_TASK\_PRIORITY**](https://msdn.microsoft.com/library/windows/hardware/dn926064) enum for valid values. | +| [**WDI\_TLV\_IHV\_TASK\_DEVICE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/dn926313) | | X | The IHV-provided context information that is forwarded to [OID\_WDI\_TASK\_IHV](oid-wdi-task-ihv.md). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_IHV](oid-wdi-task-ihv.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-link-state-change.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-link-state-change.md new file mode 100644 index 0000000000..7e44b94b5e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-link-state-change.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE to indicate any of the following situations +ms.assetid: 5a8fbe41-d063-4d34-beb8-92ceeb1d97a2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_LINK\_STATE\_CHANGE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_LINK\_STATE\_CHANGE to indicate any of the following situations: + +- The link speed changed. +- The link quality changed by more than a threshold value. The threshold is 1 if the connection quality hint is set to WDI\_CONNECTION\_QUALITY\_LOW\_LATENCY (defined in [**WDI\_CONNECTION\_QUALITY\_HINT**](https://msdn.microsoft.com/library/windows/hardware/dn897807)). Otherwise, the threshold is 5. + +| Object | +|--------| +| Port | + +  + +This information from this indication is used by the host to keep track of metadata about the current link, and it may be propagated to the user. + +In Station and P2P Client cases, the Peer MAC Address is set to the BSSID of the connected network. In AP/P2P GO cases, the Peer MAC Address is set to the MAC address of a given connected device. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------| +| [**WDI\_TLV\_LINK\_STATE\_CHANGE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn897842) | | | The link state change parameters. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-nlo-discovery.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-nlo-discovery.md new file mode 100644 index 0000000000..a984b33d40 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-nlo-discovery.md @@ -0,0 +1,84 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_NLO_DISCOVERY +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_NLO_DISCOVERY to indicate Network List Offload (NLO) discovery. +ms.assetid: 1a789bd8-8601-45f3-a9bf-5220c20379cb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_NLO_DISCOVERY Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_NLO\_DISCOVERY + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_NLO\_DISCOVERY to indicate Network List Offload (NLO) discovery. + +| Object | +|--------| +| Port | + +  + +The firmware detects APs for SSIDs pushed down in NLO. NLO is used in non-AOAC systems for fast connection when resuming from system sleep. It is also used in AOAC systems to scan APs for SSIDs that are pushed to the firmware. + +The OS does not request periodic background scans when in CS. NLO scan is the preferred method in CS because the screen is off when users don’t need to see all visible APs but those for SSIDs that users have auto-connect profiles to auto connect to. The list of SSIDs to offload from the OS has a preferred authentication and cipher pair and up to 4 channel hints. When the list has at least one SSID, the firmware should start an NLO scan autonomously following the schedule of fast scan and slow scan phases. The class driver translates the OS request to a firmware request. The firmware is expected to do NLO scan according the schedule for the APs that support the preferred authentication and cipher pair associated with the SSIDs. + +In each scan period, the firmware scans for SSIDs that match the criteria on the list of channels but not necessary constrained on the list of channels. The discovered AP information should be cached for indication. + +When any matches are found, the firmware indicates NLO discovery and caches the list of discovered AP information for the host to retrieve. + +The indication of NLO discovery happens in the following two cases. + +- When the NIC is in Dx: + 1. Trigger the wake interrupt and wait for set power to D0 to continue the following steps. + 2. Indicate NLO discovery. + 3. Indicate that the firmware woke the stack with the reason of NLO discovery. +- When the NIC is in D0: + - Indicate NLO discovery. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926162) | X | | A list of BSSIDs. The list must at least contain the entry that triggered this discovery status. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_NLO_DISCOVERY%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-open-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-open-complete.md new file mode 100644 index 0000000000..c2c19c096a --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-open-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_OPEN_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_OPEN_COMPLETE to indicate the completion of OID_WDI_TASK_OPEN. +ms.assetid: 30258df1-f882-4779-b0d3-e990b96cf67b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_OPEN_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_OPEN\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_OPEN\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_OPEN](oid-wdi-task-open.md). + +| Object | +|---------| +| Adapter | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_OPEN_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-action-frame-received.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-action-frame-received.md new file mode 100644 index 0000000000..ab5f08018e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-action-frame-received.md @@ -0,0 +1,82 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_ACTION_FRAME_RECEIVED +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_ACTION_FRAME_RECEIVED to indicate that a Wi-Fi Direct Action Frame has been received. +ms.assetid: 16e8f61d-373b-49fb-a0c5-4505fa7e653d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_ACTION_FRAME_RECEIVED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_ACTION\_FRAME\_RECEIVED + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_ACTION\_FRAME\_RECEIVED to indicate that a Wi-Fi Direct Action Frame has been received. + +| Object | +|--------| +| Port | + +  + +The host may issue an [OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md) for this request. + +The port must indicate these packets in any of the following situations: + +- The port is in listen state. +- The port has a GO in operational state. +- The port is dwelling on a remote listen channel when an [OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME](oid-wdi-task-p2p-send-request-action-frame.md) or [OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md) has been recently issued. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_INCOMING\_FRAME\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/dn897957) | | | The incoming Wi-Fi Direct Action Frame information. This information is forwarded back to the port when the host issues [OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME](oid-wdi-task-p2p-send-request-action-frame.md) + +[OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_ACTION_FRAME_RECEIVED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-discovery-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-discovery-complete.md new file mode 100644 index 0000000000..b9878a0dd1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-discovery-complete.md @@ -0,0 +1,63 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_DISCOVERY_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_DISCOVERY_COMPLETE to indicate the completion of OID_WDI_TASK_P2P_DISCOVER. +ms.assetid: 638e0a36-d4d0-44c1-8eb5-cb6bcc34daa8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_DISCOVERY_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_DISCOVERY\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_DISCOVERY\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_P2P\_DISCOVER](oid-wdi-task-p2p-discover.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_DISCOVERY_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-group-operating-channel.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-group-operating-channel.md new file mode 100644 index 0000000000..e3adf9a1de --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-group-operating-channel.md @@ -0,0 +1,66 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_GROUP_OPERATING_CHANNEL +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_GROUP_OPERATING_CHANNEL to indicate which operating channel a given Wi-Fi Direct port is operating on. +ms.assetid: 170e5df7-3128-4942-869d-45206022dfaa +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_GROUP_OPERATING_CHANNEL Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_GROUP\_OPERATING\_CHANNEL + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_GROUP\_OPERATING\_CHANNEL to indicate which operating channel a given Wi-Fi Direct port is operating on. + +For a Wi-Fi Direct Client port, this must be indicated during the connect (before the connect completion). + +For a Wi-Fi Direct GO port, this must be indicated during [OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md) (before the OID completion). + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](https://msdn.microsoft.com/library/windows/hardware/dn897869) | | | The operating channel the given Wi-Fi Direct port is operating on. | +| [**WDI\_TLV\_P2P\_CHANNEL\_INDICATE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/dn897867) | | | The reason for sending the indication. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_GROUP_OPERATING_CHANNEL%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-operating-channel-attributes.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-operating-channel-attributes.md new file mode 100644 index 0000000000..1036a744e0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-operating-channel-attributes.md @@ -0,0 +1,73 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_OPERATING_CHANNEL_ATTRIBUTES +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_OPERATING_CHANNEL_ATTRIBUTES to indicate the preferred operating channel to start a GO, the preferred listen channel if asked to enter listen state, and the full set of supported channels at any point of time. The indication is sent once when adapter initializes, and then sent each time one of these parameters changes due to events such as roaming or connecting or disconnecting from an access point. +ms.assetid: F7D27328-99B3-4EB5-9F48-864338EF8D8A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_OPERATING_CHANNEL_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_OPERATING\_CHANNEL\_ATTRIBUTES + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_OPERATING\_CHANNEL\_ATTRIBUTES to indicate the preferred operating channel to start a GO, the preferred listen channel if asked to enter listen state, and the full set of supported channels at any point of time. The indication is sent once when adapter initializes, and then sent each time one of these parameters changes due to events such as roaming or connecting or disconnecting from an access point. + +| Object | +|--------| +| Port | + +  + +The operating channel and channel list values are local settings and do not account for the actual channel negotiation during GO negotiation/invitation. The driver is still expected to negotiate the channel when GO negotiation/invitation is performed. + +It is expected that the listen channel reported by the driver is honored if listen state is turned on. It is expected that this indication is fired if the host configured a listen channel that is different from the preferred listen channel reported earlier via this indication. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------| +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](https://msdn.microsoft.com/library/windows/hardware/dn897869) | | | The Wi-Fi Direct Operating channel attribute. | +| [**WDI\_TLV\_P2P\_CHANNEL\_LIST\_ATTRIBUTE**](https://msdn.microsoft.com/library/windows/hardware/dn897868) | | | The full set of channels supported by the local adapter. | +| [**WDI\_TLV\_P2P\_LISTEN\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/mt269138) | | | The Wi-Fi Direct Listen channel attribute. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_OPERATING_CHANNEL_ATTRIBUTES%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md new file mode 100644 index 0000000000..35d19160ab --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_SEND_REQUEST_ACTION_FRAME_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_SEND_REQUEST_ACTION_FRAME_COMPLETE to indicate information about the Request Action frame sent by OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME. +ms.assetid: 4c67b512-456f-48ed-bd1c-71a32bcf85f0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_SEND_REQUEST_ACTION_FRAME_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE to indicate information about the Request Action frame sent by [OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME](oid-wdi-task-p2p-send-request-action-frame.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------|--------------------------------|-----------------------------------------------------|-----------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT**](https://msdn.microsoft.com/library/windows/hardware/dn897993) | | This TLV is only required if the status is success. | Information about the Request Action frame that was sent to the peer. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_SEND_REQUEST_ACTION_FRAME_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md new file mode 100644 index 0000000000..f812315e6d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_P2P_SEND_RESPONSE_ACTION_FRAME_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_P2P_SEND_RESPONSE_ACTION_FRAME_COMPLETE to indicate information about the Response Action frame sent by OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME. +ms.assetid: 0b330ad6-4a55-4a3e-951f-0e5a951a8cf1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_P2P_SEND_RESPONSE_ACTION_FRAME_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE to indicate information about the Response Action frame sent by [OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------|--------------------------------|-----------------------------------------------------|------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT**](https://msdn.microsoft.com/library/windows/hardware/dn897993) | | This TLV is only required if the status is success. | Information about the Response Action frame that was sent to the peer. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_P2P_SEND_RESPONSE_ACTION_FRAME_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-radio-status.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-radio-status.md new file mode 100644 index 0000000000..841c11b87b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-radio-status.md @@ -0,0 +1,72 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_RADIO_STATUS +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_RADIO_STATUS to indicate changes in the adapter's radio state. +ms.assetid: c2f90a52-ce55-4819-a66a-cfcc591cb3e9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_RADIO_STATUS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_RADIO\_STATUS + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_RADIO\_STATUS to indicate changes in the adapter's radio state. This unsolicited indication is sent when a software radio change is triggered by the host, and when a hardware radio state change is detected by the adapter. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------| +| [**WDI\_TLV\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/dn898043) | | | The current state of the radio in hardware and software. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[WDI\_TASK\_SET\_RADIO\_STATE](oid-wdi-task-set-radio-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_RADIO_STATUS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-roam-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-roam-complete.md new file mode 100644 index 0000000000..ecb0e97da5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-roam-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_ROAM_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_ROAM_COMPLETE to indicate the completion of OID_WDI_TASK_ROAM. +ms.assetid: 25263d5a-3866-4fa5-916e-660ed3fbe38e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_ROAM_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_ROAM\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_ROAM\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_ROAM_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-roaming-needed.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-roaming-needed.md new file mode 100644 index 0000000000..6bcd3e0d69 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-roaming-needed.md @@ -0,0 +1,72 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_ROAMING_NEEDED +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_DISASSOCIATION to indicate that the host should try to find a better peer to connect to. +ms.assetid: 25f920e9-af87-48ad-be64-aa3ebfe2db5f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_ROAMING_NEEDED Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION to indicate that the host should try to find a better peer to connect to. This notification is used when the link quality with the currently connected peer falls below a certain threshold. On sending this notification, the host may trigger a roam scan and/or a roam operation. The Microsoft component does not perform a disconnect before it starts the roam operation. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_ROAMING\_NEEDED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898049) | | | The reason for the roam trigger. When a [OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) is triggered, this reason is forwarded to it. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_ROAM](oid-wdi-task-roam.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_ROAMING_NEEDED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-scan-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-scan-complete.md new file mode 100644 index 0000000000..cb166c8f7d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-scan-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_SCAN_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_SCAN_COMPLETE to indicate the completion of OID_WDI_TASK_SCAN. +ms.assetid: ed4b53e2-889d-4ce6-b9ea-92a95af28a8a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_SCAN_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_SCAN\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_SCAN\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_SCAN](oid-wdi-task-scan.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_SCAN](oid-wdi-task-scan.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_SCAN_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-ap-association-response-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-ap-association-response-complete.md new file mode 100644 index 0000000000..b1d2919ddb --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-ap-association-response-complete.md @@ -0,0 +1,76 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_SEND_AP_ASSOCIATION_RESPONSE_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_SEND_AP_ASSOCIATION_RESPONSE_COMPLETE to indicate information about the AP association response sent by OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE. +ms.assetid: c8bfa3b3-5d22-4831-9355-94c62fed7fd4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_SEND_AP_ASSOCIATION_RESPONSE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_SEND\_AP\_ASSOCIATION\_RESPONSE\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_SEND\_AP\_ASSOCIATION\_RESPONSE\_COMPLETE to indicate information about the AP association response sent by [OID\_WDI\_TASK\_SEND\_AP\_ASSOCIATION\_RESPONSE](oid-wdi-task-send-ap-association-response.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +Type +Multiple TLV instances allowed +Optional +Description +[**WDI\_TLV\_ASSOCIATION\_RESPONSE\_RESULT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926138) +The association response parameters. +[**WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME**](https://msdn.microsoft.com/library/windows/hardware/dn926135) +The received association response. This does not include the 802.11 MAC header. +[**WDI\_TLV\_BEACON\_IES**](https://msdn.microsoft.com/library/windows/hardware/dn926148) +The beacon IEs from the association. +[**WDI\_TLV\_PHY\_TYPE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/dn898029) +X +The list of PHY types. +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_SEND_AP_ASSOCIATION_RESPONSE_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-request-action-frame-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-request-action-frame-complete.md new file mode 100644 index 0000000000..9d8f4cdb18 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-request-action-frame-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_SEND_REQUEST_ACTION_FRAME_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_SEND_REQUEST_ACTION_FRAME_COMPLETE to indicate the completion of OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME. +ms.assetid: A349C873-CBC4-4C90-8786-A1DA158EDD89 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_SEND_REQUEST_ACTION_FRAME_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_SEND\_REQUEST\_ACTION\_FRAME](oid-wdi-task-send-request-action-frame.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_SEND\_REQUEST\_ACTION\_FRAME](oid-wdi-task-send-request-action-frame.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_SEND_REQUEST_ACTION_FRAME_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-response-action-frame-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-response-action-frame-complete.md new file mode 100644 index 0000000000..38d780b9fb --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-send-response-action-frame-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_SEND_RESPONSE_ACTION_FRAME_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_SEND_RESPONSE_ACTION_FRAME_COMPLETE to indicate the completion of OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME. +ms.assetid: 9D07F05B-212F-403E-AD37-4AB537C25536 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_SEND_RESPONSE_ACTION_FRAME_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-send-response-action-frame.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-send-response-action-frame.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_SEND_RESPONSE_ACTION_FRAME_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-set-radio-state-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-set-radio-state-complete.md new file mode 100644 index 0000000000..204b001ccd --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-set-radio-state-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_SET_RADIO_STATE_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_SET_RADIO_STATE_COMPLETE to indicate the completion of OID_WDI_TASK_SET_RADIO_STATE. +ms.assetid: 43b9e513-d9bd-456c-9d80-aaefd21dce5f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_SET_RADIO_STATE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_SET\_RADIO\_STATE\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_SET\_RADIO\_STATE\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_SET\_RADIO\_STATE](oid-wdi-task-set-radio-state.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_SET\_RADIO\_STATE](oid-wdi-task-set-radio-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_SET_RADIO_STATE_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-start-ap-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-start-ap-complete.md new file mode 100644 index 0000000000..2addec7d95 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-start-ap-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_START_AP_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_START_AP_COMPLETE to indicate the completion of OID_WDI_TASK_START_AP. +ms.assetid: 24f63533-2eee-4559-8feb-02488ce75fc2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_START_AP_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_START\_AP\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_START\_AP\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_START_AP_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap-complete.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap-complete.md new file mode 100644 index 0000000000..e21b951fbd --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap-complete.md @@ -0,0 +1,68 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_STOP_AP_COMPLETE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_STOP_AP_COMPLETE to indicate the completion of OID_WDI_TASK_STOP_AP. +ms.assetid: 8756b9da-5638-4dcc-a0f7-13ed8042c81e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_STOP_AP_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP\_COMPLETE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP\_COMPLETE to indicate the completion of [OID\_WDI\_TASK\_STOP\_AP](oid-wdi-task-stop-ap.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +This indication contains no additional data. The data in the header is sufficient. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_STOP\_AP](oid-wdi-task-stop-ap.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_STOP_AP_COMPLETE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap.md new file mode 100644 index 0000000000..54c58a69d9 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-stop-ap.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_STOP_AP +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_STOP_AP to indicate that the adapter cannot sustain 802.11 Access Point (AP) functionality on any of the PHYs. +ms.assetid: EF129BD3-6AA2-4F38-BECD-E9D526314A27 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_STOP_AP Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP to indicate that the adapter cannot sustain 802.11 Access Point (AP) functionality on any of the PHYs. The adapter should send this indication only after the NIC has stopped any APs that are operating on the available PHYs. The host blocks all [OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md) requests until the adapter sends [NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP](ndis-status-wdi-indication-can-sustain-ap.md). + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------| +| [**WDI\_TLV\_INDICATION\_STOP\_AP**](https://msdn.microsoft.com/library/windows/hardware/dn926318) | | | The reason the adapter cannot sustain 802.11 AP functionality on any of the PHYs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_TASK\_START\_AP](oid-wdi-task-start-ap.md) + +[NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP](ndis-status-wdi-indication-can-sustain-ap.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_STOP_AP%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-task-offload-current-config.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-task-offload-current-config.md new file mode 100644 index 0000000000..f5fbf61d10 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-task-offload-current-config.md @@ -0,0 +1,74 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_TASK_OFFLOAD_CURRENT_CONFIG +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_TASK_OFFLOAD_CURRENT_CONFIG to indicate when there is a change in the TCP offload capabilities of the hardware. +ms.assetid: 4E73F09A-965F-4F32-AFF7-FDF1E3B2853C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_TASK_OFFLOAD_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_TASK\_OFFLOAD\_CURRENT\_CONFIG + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_TASK\_OFFLOAD\_CURRENT\_CONFIG to indicate when there is a change in the TCP offload capabilities of the hardware. + +| Object | +|--------| +| Port | + +  + +When there is a change in the TCP offload capabilities of the hardware, the LE sends this unsolicited indication to the UE, with the new TCP checksum/LSO capabilities. Use the values **NDIS\_OFFLOAD\_SET\_OFF** and **NDIS\_OFFLOAD\_SET\_ON** for members in [**WDI\_TLV\_TCP\_OFFLOAD\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/dn898069) for indicating changes in offload capabilities. When the UE sends down a [OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS](oid-wdi-set-tcp-offload-parameters.md), the LE should update the offload capabilities and then send this indication so that the OS is updated with the latest offload capabilities information. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------| +| [**WDI\_TLV\_TCP\_OFFLOAD\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/dn898069) | | X | The TCP/IP checksum and Large Send Offload capabilities. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS](oid-wdi-set-tcp-offload-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_TASK_OFFLOAD_CURRENT_CONFIG%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-tkip-mic-failure.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-tkip-mic-failure.md new file mode 100644 index 0000000000..46b46a0f33 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-tkip-mic-failure.md @@ -0,0 +1,67 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_TKIP_MIC_FAILURE +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_TKIP_MIC_FAILURE to indicate when a received packet that was successfully decrypted by the TKIP cipher algorithm fails the message integrity code (MIC) verification. +ms.assetid: ab9d3109-72af-457e-9e65-456613cea32f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_TKIP_MIC_FAILURE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_TKIP\_MIC\_FAILURE + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_TKIP\_MIC\_FAILURE to indicate when a received packet that was successfully decrypted by the TKIP cipher algorithm fails the message integrity code (MIC) verification. + +| Object | +|--------| +| Port | + +  + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------| +| [**WDI\_TLV\_TKIP\_MIC\_FAILURE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn898072) | | | The TKIP MIC failure information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_TKIP_MIC_FAILURE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wdi-indication-wake-reason.md b/windows-driver-docs-pr/network/ndis-status-wdi-indication-wake-reason.md new file mode 100644 index 0000000000..90349a8066 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wdi-indication-wake-reason.md @@ -0,0 +1,73 @@ +--- +title: NDIS_STATUS_WDI_INDICATION_WAKE_REASON +author: windows-driver-content +description: Miniport drivers use NDIS_STATUS_WDI_INDICATION_WAKE_REASON to indicate the reason for a wake when the NIC wakes the host. The wake reason is used for debugging purposes and has no functional effect. +ms.assetid: 5f2eb569-be1e-4f24-92f5-8405ffc7b061 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WDI_INDICATION_WAKE_REASON Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WDI\_INDICATION\_WAKE\_REASON + + +Miniport drivers use NDIS\_STATUS\_WDI\_INDICATION\_WAKE\_REASON to indicate the reason for a wake when the NIC wakes the host. The wake reason is used for debugging purposes and has no functional effect. + +| Object | +|--------| +| Port | + +  + +When the host goes to low power state, it offloads a few functions to the NIC and arms the NIC for wake. When a wake event occurs, the NIC asserts the wake interrupt line to wake the host. The host then brings the NIC into D0 (running power state). The NIC must indicate the wake reason once it enters D0. + +If the wake reason is a wake packet, the NIC should also include the wake packet and the wake pattern ID that matches the packet. The packet is encapsulated as [**WDI\_TLV\_INDICATION\_WAKE\_PACKET**](https://msdn.microsoft.com/library/windows/hardware/dn897833). The wake reason should also include [**WDI\_TLV\_INDICATION\_WAKE\_PACKET\_PATTERN\_ID**](https://msdn.microsoft.com/library/windows/hardware/dn897832) to specify the pattern ID which matches the packet. + +## Payload data + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_INDICATION\_WAKE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/dn897834) | | | The wake reason. | +| [**WDI\_TLV\_INDICATION\_WAKE\_PACKET**](https://msdn.microsoft.com/library/windows/hardware/dn897833) | | X | The wake packet. | +| [**WDI\_TLV\_INDICATION\_WAKE\_PACKET\_PATTERN\_ID**](https://msdn.microsoft.com/library/windows/hardware/dn897832) | | X | The ID of the pattern that matches the wake packet. The ID is obtained from the Add command of the pattern. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WDI_INDICATION_WAKE_REASON%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-ww-indication.md b/windows-driver-docs-pr/network/ndis-status-ww-indication.md new file mode 100644 index 0000000000..fc76023f1d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-ww-indication.md @@ -0,0 +1,60 @@ +--- +title: NDIS_STATUS_WW_INDICATION +author: windows-driver-content +description: The NDIS_STATUS_WW_INDICATION status is the same as the NDIS_STATUS_MEDIA_SPECIFIC_INDICATION status. +ms.assetid: 8c0a7b33-bab3-4e8c-a1f0-8564633dbc7c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WW_INDICATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WW\_INDICATION + + +The NDIS\_STATUS\_WW\_INDICATION status is the same as the [**NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION**](ndis-status-media-specific-indication.md) status. + +Remarks +------- + +For more information about NDIS\_STATUS\_WW\_INDICATION, see [OID\_WW\_GEN\_INDICATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff561411). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported in NDIS 6.0 and later. Supported only for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_MEDIA\_SPECIFIC\_INDICATION**](ndis-status-media-specific-indication.md) + +[OID\_WW\_GEN\_INDICATION\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff561411) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WW_INDICATION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-auth-response.md b/windows-driver-docs-pr/network/ndis-status-wwan-auth-response.md new file mode 100644 index 0000000000..2313485737 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-auth-response.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_AUTH_RESPONSE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_AUTH_RESPONSE notification to inform the MB Service of a challenge response received from a previous challenge request issued using an OID_WWAN_AUTH_CHALLENGE query request.NDIS_WWAN_AUTH_RESPONSE structure. +ms.assetid: 24831764-4F6D-481B-A440-4F9CAE1F7501 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_AUTH_RESPONSE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_AUTH\_RESPONSE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_AUTH\_RESPONSE notification to inform the MB Service of a challenge response received from a previous challenge request issued using an [OID\_WWAN\_AUTH\_CHALLENGE](https://msdn.microsoft.com/library/windows/hardware/hh440092) query request. + +Miniport drivers can also send unsolicited events with this notification. + +This NDIS status notification uses the [NDIS\_WWAN\_AUTH\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh439834) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_AUTH\_CHALLENGE](https://msdn.microsoft.com/library/windows/hardware/hh440092) + +[NDIS\_WWAN\_AUTH\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/hh439834) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_AUTH_RESPONSE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-context-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-context-state.md new file mode 100644 index 0000000000..3cc97ec2f6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-context-state.md @@ -0,0 +1,74 @@ +--- +title: NDIS\_STATUS\_WWAN\_CONTEXT\_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_CONTEXT\_STATE notification to send an event notification when the activation state of a particular context changes. +ms.assetid: 6713f6a3-d1b7-49d0-83e1-50a33e9fff32 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_CONTEXT_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_CONTEXT\_STATE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_CONTEXT\_STATE notification to send an event notification when the activation state of a particular context changes. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567906) structure. + +Remarks +------- + +Miniport drivers must also notify the MB Service when context state changes are not caused as a result of a *set* request from the MB Service. For example, miniport drivers must notify the MB Service if the network deactivates a context. Miniport drivers should not implement network initiated context activations. + +Miniport drivers must notify Windows directly about all applicable context state changes, such as when processing NDIS\_STATUS\_WWAN\_PACKET\_SERVICE or NDIS\_STATUS\_WWAN\_REGISTER\_STATE status notifications. + +Miniport drivers of MB devices that support separate voice and data connections must follow these guidelines: + +- At the time of initialization, the VoiceCallState must be set to WwanVoiceCallStateNone. + +- On the start of the voice call, send an event notification with VoiceCallState set to WwanVoiceCallStateInProgress. All the other members must reflect their current state. In case of no active connection during the voice call, the ConnectionId should be set to "0" . + +- Once the voice call is completed, send an event notification with VoiceCallState set to WwanVoiceCallStateHangUp. All the other members must reflect their current state. In case of no active connection during the voice call hang up, the ConnectionId should be set to "0". After this event, the VoiceCallState must be set to **WwanVoiceCallStateNone** in the miniport driver. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567906) + +[OID\_WWAN\_PROVISIONED\_CONTEXTS](oid-wwan-provisioned-contexts.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_CONTEXT_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-caps-ex.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-caps-ex.md new file mode 100644 index 0000000000..bd632d01df --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-caps-ex.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_CAPS_EX +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_CAPS_EX notification to inform the MB service about the completion of a previous OID_WWAN_DEVICE_CAPS_EX query request. +ms.assetid: 7E596CB0-2A08-45E4-9932-5E951B880D62 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_CAPS_EX Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_CAPS\_EX + + +Miniport drivers use the **NDIS\_STATUS\_WWAN\_DEVICE\_CAPS\_EX** notification to inform the MB service about the completion of a previous [OID\_WWAN\_DEVICE\_CAPS\_EX](https://msdn.microsoft.com/library/windows/hardware/mt799830) query request. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782401) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_CAPS\_EX](https://msdn.microsoft.com/library/windows/hardware/mt799830) + +[**NDIS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782401) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_CAPS_EX%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-caps.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-caps.md new file mode 100644 index 0000000000..dd226700bc --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-caps.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_CAPS +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_CAPS notification to respond to OID_WWAN_DEVICE_CAPS query requests. Miniport drivers cannot use this notification to send unsolicited events.This notification uses the NDIS_WWAN_DEVICE_CAPS structure. +ms.assetid: e21e2928-c50d-4dec-a575-7e306fecf20f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_CAPS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_CAPS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_CAPS notification to respond to [OID\_WWAN\_DEVICE\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569824) query requests. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567907) structure. + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_CAPS](https://msdn.microsoft.com/library/windows/hardware/ff569824) + +[**NDIS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567907) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_CAPS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-event.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-event.md new file mode 100644 index 0000000000..798d8aab80 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-event.md @@ -0,0 +1,57 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_EVENT +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_EVENT indication to notify the MB Service of device service changes.NDIS_WWAN_DEVICE_SERVICE_EVENT structure. +ms.assetid: 2414F63D-756F-4057-974C-A363CEB6399B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_EVENT Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT indication to notify the MB Service of device service changes. + +Miniport drivers can only use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/hh439837) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/hh439837) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_EVENT%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-response.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-response.md new file mode 100644 index 0000000000..35158f896a --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-response.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_RESPONSE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_RESPONSE indication to implement the transaction completion response for OID_WWAN_DEVICE_SERVICE_COMMAND.NDIS_WWAN_DEVICE_SERVICE_RESPONSE structure. +ms.assetid: 2817EAFA-7A9A-4DC1-B2B7-31E1F4E5E331 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_RESPONSE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE indication to implement the transaction completion response for [OID\_WWAN\_DEVICE\_SERVICE\_COMMAND](https://msdn.microsoft.com/library/windows/hardware/hh440094). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh439838) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_SERVICE\_COMMAND](https://msdn.microsoft.com/library/windows/hardware/hh440094) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh439838) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_RESPONSE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-read.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-read.md new file mode 100644 index 0000000000..bb4858f6df --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-read.md @@ -0,0 +1,57 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_READ +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_READ notification to inform the MB Service that data has been received from an open device service session.NDIS_WWAN_DEVICE_SERVICE_SESSION_READ structure. +ms.assetid: 680C15DA-B37C-4A7C-B7BE-B13B3B050EC3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_READ Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_READ + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_READ notification to inform the MB Service that data has been received from an open device service session. + +Miniport drivers can only use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_READ**](https://msdn.microsoft.com/library/windows/hardware/hh831859) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_READ**](https://msdn.microsoft.com/library/windows/hardware/hh831859) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_READ%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-write-complete.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-write-complete.md new file mode 100644 index 0000000000..61253d65e9 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session-write-complete.md @@ -0,0 +1,57 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE notification to report the status of a write operation on a device service session.NDIS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE structure. +ms.assetid: 39C0FE62-E262-4D7D-8A93-6C31431AF846 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE notification to report the status of a write operation on a device service session. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh831861) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh831861) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION_WRITE_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session.md new file mode 100644 index 0000000000..538ec7ae08 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-session.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION indication to report the completion of a device service session state change originated by OID_WWAN_DEVICE_SERVICE_SESSION.NDIS_WWAN_DEVICE_SERVICE_SESSION_INFO structure. +ms.assetid: 0A3D8323-20F1-4405-97D4-0E497946118E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION indication to report the completion of a device service session state change originated by [OID\_WWAN\_DEVICE\_SERVICE\_SESSION](https://msdn.microsoft.com/library/windows/hardware/hh846218). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh831858) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_SERVICE\_SESSION](https://msdn.microsoft.com/library/windows/hardware/hh846218) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh831858) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_SESSION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-subscription.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-subscription.md new file mode 100644 index 0000000000..d9d56e2e98 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-subscription.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_SUBSCRIPTION +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_SUBSCRIPTION notification to inform the MB Service about a device service subscription in response to an OID_WWAN_SUBSCRIBE_DEVICE_SERVICE_EVENTS set request.NDIS_WWAN_DEVICE_SERVICE_SUBSCRIPTION structure. +ms.assetid: E2B839AE-F81A-41EE-8374-F830B79D1E74 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_SUBSCRIPTION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION notification to inform the MB Service about a device service subscription in response to an [OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS](https://msdn.microsoft.com/library/windows/hardware/hh440096) set request. + +Miniport drivers cannot use this notification to send unsolicited events. + +This indication uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/hh439839) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS](https://msdn.microsoft.com/library/windows/hardware/hh440096) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/hh439839) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_SUBSCRIPTION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-service-supported-commands.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-supported-commands.md new file mode 100644 index 0000000000..23c509a86d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-service-supported-commands.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS notification to report the completion of a query of OID_WWAN_ENUMERATE_DEVICE_SERVICE_COMMANDS.NDIS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS structure. +ms.assetid: 3EFEFB4B-6B13-44D7-8788-140B90103A93 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS notification to report the completion of a query of [OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS](https://msdn.microsoft.com/library/windows/hardware/hh846221). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846214) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS](https://msdn.microsoft.com/library/windows/hardware/hh846221) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846214) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SERVICE_SUPPORTED_COMMANDS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-device-slot-mappings.md b/windows-driver-docs-pr/network/ndis-status-wwan-device-slot-mappings.md new file mode 100644 index 0000000000..5683c12e75 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-device-slot-mappings.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_DEVICE_SLOT_MAPPING_INFO +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_DEVICE_SLOT_MAPPING_INFO notification to inform the MB service about the completion of a previous OID_WWAN_DEVICE_SLOT_MAPPING_INFO query or set request. +ms.assetid: 7825C20E-FB56-420D-B516-1ADA0C7C382E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_DEVICE_SLOT_MAPPING_INFO Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO + + +Miniport drivers use the **NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO** notification to inform the MB service about the completion of a previous [OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799831) query or set request. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782403) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799831) + +[**NDIS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782403) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_DEVICE_SLOT_MAPPING_INFO%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-home-provider.md b/windows-driver-docs-pr/network/ndis-status-wwan-home-provider.md new file mode 100644 index 0000000000..c7129276c8 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-home-provider.md @@ -0,0 +1,72 @@ +--- +title: NDIS\_STATUS\_WWAN\_HOME\_PROVIDER +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_HOME\_PROVIDER notification to inform the MB Service about the completion of OID\_WWAN\_HOME\_PROVIDER \ 160; query requests. +ms.assetid: a5733c62-be4e-4f86-9639-6addd31baf0c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_HOME_PROVIDER Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_HOME\_PROVIDER + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_HOME\_PROVIDER notification to inform the MB Service about the completion of [OID\_WWAN\_HOME\_PROVIDER](oid-wwan-home-provider.md)  query requests. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/ff567909) structure. + +Remarks +------- + +Miniport drivers must comply with the following rules when responding to OID\_WWAN\_HOME\_PROVIDER query requests: + +- GSM-Based Devices: The home provider name can be retrieved from the Subscriber Identity Module (SIM) using several methods, such as from the EFSPN elementary file in the SIM (EFSPN is defined in the 3GPP TS 31.102 under section Service Provider Name), or from the operator-specific extensions when the EFSPN is not provisioned. You should refer to the operator-specific requirements specifications for obtaining the home provider name, extracting MCC-MNC from IMSI, and performing a look up in the GSMA SE.13 database. Contact the operator when retrieving operator-specific home provider names if the EFSPN is not provisioned. If a SIM is not provisioned with a home provider name through EFSPN or any other mechanism, miniport drivers should set the provider name to **NULL**. + + For details about a SIM card's file system, see the 3GPP TS 11.11 specification. If the provider identification is not provisioned in the Subscriber Identity Module (SIM card), miniport drivers should return WWAN\_STATUS\_READ\_FAILURE. + +- CDMA-Based Devices: Returning the home provider name is mandatory. It is recommended that IHVs provide this information in their device as part of network personalization. If the provider identity is not available, miniport drivers for CDMA-based providers must set the **Provider.ProviderId** member of the NDIS\_WWAN\_HOME\_PROVIDER structure to WWAN\_CDMA\_DEFAULT\_PROVIDER\_ID. + +Miniport drivers must return this information when the device ready-state changes to **WwanReadyStateInitialized** and format all the members of the WWAN\_PROVIDER structure, as appropriate. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_HOME\_PROVIDER](oid-wwan-home-provider.md) + +[**NDIS\_WWAN\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/ff567909) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_HOME_PROVIDER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-ip-address-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-ip-address-state.md new file mode 100644 index 0000000000..9cee776d85 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-ip-address-state.md @@ -0,0 +1,62 @@ +--- +title: NDIS_STATUS_WWAN_IP_ADDRESS_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_IP_ADDRESS_STATE notification to inform the MB service about changes to the IP configuration for an additional PDP context. +ms.assetid: 98E4028D-AD75-4F12-ADA4-41725253166F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_IP_ADDRESS_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_IP\_ADDRESS\_STATE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_IP\_ADDRESS\_STATE notification to inform the MB service about changes to the IP configuration for an additional PDP context. + +This notification uses the [**NDIS\_WWAN\_IP\_ADDRESS\_STATE**](https://msdn.microsoft.com/library/windows/hardware/dn449746) structure. + +Remarks +------- + +This notification must be sent on the NDIS port associated with the additional PDP context session. + +Miniport drivers should send this notification after an additional PDP context has been successfully activated and the IP configuration has been acquired for that context. If the device indicates unsolicited IP configuration changes post-context activation, then miniport drivers should send an unsolicited indication with this notification with the updated IP configuration. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 8.1 and later versions of Windows.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_IP\_ADDRESS\_STATE**](https://msdn.microsoft.com/library/windows/hardware/dn449746) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_IP_ADDRESS_STATE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-packet-service.md b/windows-driver-docs-pr/network/ndis-status-wwan-packet-service.md new file mode 100644 index 0000000000..0f0e85c2c6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-packet-service.md @@ -0,0 +1,90 @@ +--- +title: NDIS\_STATUS\_WWAN\_PACKET\_SERVICE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_PACKET\_SERVICE notification to inform the MB Service when packet service availability changes, including to notify of a change to the type of packet data service currently used. +ms.assetid: 7a04b54e-e07b-43dc-ba76-086d7521ff60 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_PACKET_SERVICE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PACKET\_SERVICE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PACKET\_SERVICE notification to inform the MB Service when packet service availability changes, including to notify of a change to the type of packet data service currently used. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_PACKET\_SERVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567910) structure. + +Remarks +------- + +CDMA-based miniport drivers can automatically initiate packet-attach service if there is no resource allocation/release is possible and can send the event notification to the MB Service. + +Miniport drivers should obey the following guidelines for event notifications: + +- Miniport drivers should set **AvailableDataClasses** is set to WWAN\_DATA\_CLASS\_NONE during miniport driver initialization. Thereafter, miniport drivers must notify the MB Service whenever there is any change to **AvailableDataClasses**. + +- Miniport drivers should set **CurrentDataClass** to WWAN\_DATA\_CLASS\_NONE during miniport driver initialization. Thereafter, miniport drivers must notify the MB Service whenever there is any change to **CurrentDataClass** . Miniport drivers should send an NDIS\_STATUS\_LINK\_STATE notification if the change to **CurrentDataClass** results in a change of the transmit or receive link speed. + +- Miniport drivers must notify the MB Service whenever there is any change in Packet Service attach state. + +Miniport drivers should return *query* results according to the following rules: + +- Miniport drivers must return WWAN\_STATUS\_SUCCESS with **WwanPacketServiceStateAttaching** whenever the device attempts to packet-attach. + +- Miniport drivers should return WWAN\_STATUS\_SUCCESS with **WwanPacketServiceStateDetaching** whenever the device attempts to packet-detach. + +- When the device is in final state, miniport drivers should return WWAN\_STATUS\_SUCCESS along with the appropriate current state ( **WwanPacketServiceStateAttached** or **WwanPacketServiceStateDetached**) + +- Miniport drivers must list all the available data-classes; not just the highest data-class available. This applies to both *query* operations as well as event notifications. + +Miniport drivers should return *set* results according to the following rules: + +- Return WWAN\_STATUS\_SUCCESS, if *set* request with **WwanPacketServiceActionAttach**, is issued by the Service and the device is already in the packet-attached state. + +- Return WWAN\_STATUS\_SUCCESS, if *set* request with **WwanPacketServiceActionDetach**, is issued by the Service and the device is already in the packet-detached state. + +- Never return transient states for the *set* request. Only the final states **WwanPacketServiceStateAttached** or **WwanPacketServiceStateDetached** must be returned after the successful completion of the packet service operation with WWAN\_STATUS\_SUCCESS + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PACKET\_SERVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567910) + +[OID\_WWAN\_PACKET\_SERVICE](oid-wwan-packet-service.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PACKET_SERVICE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-pin-info.md b/windows-driver-docs-pr/network/ndis-status-wwan-pin-info.md new file mode 100644 index 0000000000..f768181fbb --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-pin-info.md @@ -0,0 +1,122 @@ +--- +title: NDIS\_STATUS\_WWAN\_PIN\_INFO +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_INFO notification to respond to OID query and set requests of OID\_WWAN\_PIN. Miniport drivers cannot use this notification to send unsolicited events.This notification uses the NDIS\_WWAN\_PIN\_INFO structure. +ms.assetid: fa3c2467-2240-423b-b91b-f7e19d5be353 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_PIN_INFO Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PIN\_INFO + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_INFO notification to respond to OID query and set requests of [OID\_WWAN\_PIN](oid-wwan-pin.md). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_PIN\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567911) structure. + +Remarks +------- + +Miniport drivers should return information about the Personal Identity Number (PIN) that the MB device currently expects in response to a query request. Miniport drivers should return the status notification filled in as described in sections below in response to a set request. + +**Responding to WwanPinOperationEnter Requests** + +When miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_INFO notification to respond to **WwanPinOperationEnter** requests, they should implement these procedures: + +- For successful **WwanPinOperationEnter** query requests, when the MB device no longer requires a PIN, miniport drivers must set **uStatus** to WWAN\_STATUS\_SUCCESS and **PinType** to **WwanPinTypeNone**. + +- For failed **WwanPinOperationEnter** requests, miniport drivers must set **uStatus** to WWAN\_STATUS\_FAILURE and include applicable data as per the following details: + + - PIN Disabled or PIN Not Expected: For **WwanPinOperationEnter** set requests, when the corresponding PIN is either disabled or currently not expected by the MB device, miniport drivers must set **PinType** to **WwanPinTypeNone**. All other members are ignored. + + - PIN Not Supported: If the given PIN is not supported by the MB device, miniport drivers must set **uStatus** to WWAN\_STATUS\_NO\_DEVICE\_SUPPORT. + + - PIN Retrial: In this mode, the MB device requires the PIN to be re-entered as the **AttemptsRemaining** value is still non-zero for this particular type of PIN. Miniport drivers must set **PinType** to the same value as that of **PinType** in NDIS\_WWAN\_SET\_PIN. + + - PIN Blocking: The PIN is blocked when **AttemptsRemaining** is zero. If the PIN unblock operation is not available, miniport drivers must set **uStatus** to WWAN\_STATUS\_FAILURE and **PinType** to **WwanPinTypeNone**. All the other members are ignored. + + **Note**  If the MB device supports PIN unblock operations, miniport drivers should follow the PIN Unblocking step to respond to the request. + +   + + - PIN Unblocking: The PIN is blocked when **AttemptsRemaining** is zero. To unblock the PIN, the MB device may request a corresponding PIN Unlock Key (PUK), if applicable. In this case, miniport drivers must set **PinType** to the corresponding WwanPinType*Xxx*PUK with the relevant details. + + - Blocked PUK: If the number of failed trials exceeds the preset value for entering the WwanPinType*Xxx*PUK, then the PUK becomes blocked. Miniport drivers must signal this by setting **uStatus** to WWAN\_STATUS\_FAILURE and **PinType** to **WwanPinTypeNone**. In case PUK1 is blocked, miniport drivers must send an NDIS\_STATUS\_WWAN\_READY\_INFO with **ReadyState** set to **WwanReadyStateBadSim**. + +**Responding to WwanPinOperationEnable, WwanPinOperationDisable, or WwanPinOperationChange Requests** + +When miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_INFO notification to respond to **WwanPinOperationEnable**, **WwanPinOperationDisable**, and **WwanPinOperationChange**, they should implement the following operations: + +- For successful requests, miniport drivers must set **uStatus** to WWAN\_STATUS\_SUCCESS. Other members are ignored. + +- Miniport drivers must set **uStatus** to WWAN\_STATUS\_SUCCESS for PIN-enable and PIN-disable operations when the PIN is already in the requested state. Miniport drivers must set **PinType** to **WwanPinTypeNone**. Other members are ignored. + +- When a PIN mode is changed from disabled to enabled the PIN state should be WwanPinStateNone. + +- If PIN1 is enabled, the PIN state shall become WwanPinStateEnter when power is cycled to the MB device. + +- For all other PINs, the PIN state can change from WwanPinStateNone to WwanPinStateEnter depending on MB device specific conditions. + +- PIN Not Supported: If a PIN operation is not supported by the MB device, miniport drivers must set **uStatus** to WWAN\_STATUS\_NO\_DEVICE\_SUPPORT. For example, enabling and disabling PIN2 is not typically supported by MB devices so the above error code must be returned. All other members are ignored. + +- PIN Must be Entered: If a PIN operation requires a PIN to be entered, miniport drivers must set **uStatus** to WWAN\_STATUS\_PIN\_REQUIRED and **PinType** to WwanPinType*Xxx*. Other members are ignored. + +- PIN Change Operation: If the MB device restricts the change of PIN value only when it is in enabled state, a request to change in disabled state must be returned with WWAN\_STATUS\_PIN\_DISABLED. + +- PIN Retrial: On failure, miniport drivers must set **uStatus** to WWAN\_STATUS\_FAILURE, and **PinType** to the same value as specified in NDIS\_WWAN\_SET\_PIN. Other members are ignored except for **AttemptsRemaining**. This may occur when an incorrect PIN is entered. + +- PIN Blocking: The PIN is blocked when the number of **AttemptsRemaining** is zero. If the PIN unblock operation is not available, miniport drivers must set **uStatus** to WWAN\_STATUS\_FAILURE and **PinType** to **WwanPinTypeNone**. **AttemptsRemaining** should be set to 0 and all the other members are ignored. + + **Note**  If the MB device supports PIN unblock operations, miniport drivers should follow the PIN Unblocking step to respond to the request. + +   + +- Unblocking PIN: The PIN is blocked when **AttemptsRemaining** is zero. To unblock the PIN, the MB device may request a corresponding PUK, if applicable. In this case, miniport drivers must set **uStatus** to WWAN\_STATUS\_FAILURE, **PinType** to the corresponding WwanPinType*Xxx*PUK, **PinState** to **WwanPinStateEnter**, and **AttemptsRemaining** should have the number of attempts allowed to enter a valid PUK. + + If PIN blocking results in the MB device or SIM becomes blocked, miniport drivers must send an event notification with **ReadyState** set to **WwanReadyStateDeviceLocked**. + +- If there is an active PDP context at the time of PIN1 blocking, miniport drivers must deactivate the PDP context and send notifications to the operating system about the PDP deactivation and link state change. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_PIN](oid-wwan-pin.md) + +[**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PIN_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-pin-list.md b/windows-driver-docs-pr/network/ndis-status-wwan-pin-list.md new file mode 100644 index 0000000000..c8c0989bf9 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-pin-list.md @@ -0,0 +1,68 @@ +--- +title: NDIS\_STATUS\_WWAN\_PIN\_LIST +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_LIST notification to respond to OID query requests of OID\_WWAN\_PIN\_LIST. Miniport drivers cannot use this notification to send unsolicited events.This notification uses the NDIS\_WWAN\_PIN\_LIST structure. +ms.assetid: fd8e6734-d032-445a-819a-0d5a773e9ea3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_PIN_LIST Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PIN\_LIST + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PIN\_LIST notification to respond to OID query requests of [OID\_WWAN\_PIN\_LIST](oid-wwan-pin-list.md). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_PIN\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff567912) structure. + +Remarks +------- + +This INDICATION is a response only notification to OID query requests of OID\_WWAN\_PIN\_LIST. Unsolicited indications are not expected for this INDICATION. + +Any change in the PIN-entry mode caused as a result of an OID\_WWAN\_PIN enable or disable operation will not result in an NDIS\_STATUS\_WWAN\_PIN\_LIST INDICATION. + +Note that the current PinMode for all of the PINs that the device supports must be updated to reflect the current state by the miniport driver on each query request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_PIN\_LIST](oid-wwan-pin-list.md) + +[**NDIS\_WWAN\_PIN\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff567912) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PIN_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-preferred-multicarrier-providers.md b/windows-driver-docs-pr/network/ndis-status-wwan-preferred-multicarrier-providers.md new file mode 100644 index 0000000000..6ae23d41f4 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-preferred-multicarrier-providers.md @@ -0,0 +1,57 @@ +--- +title: NDIS_STATUS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS notification to respond to a previous OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERSquery request.Miniport drivers may also use this notification to inform the MB Service about the update as a result of a OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS set request from the MB Service. A response to an OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS set request must contain zero elements in the PreferredListHeader member. Miniport drivers can also send unsolicited events with this notification to inform the MB Service that the Preferred Multi-Carrier Provider List (PMCPL) has changed.This notification uses the NDIS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS structure. +ms.assetid: DBE8911D-1A92-40BC-94EB-BED3B8B82CB0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS notification to respond to a previous [OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS](https://msdn.microsoft.com/library/windows/hardware/hh831868)*query* request. + +Miniport drivers may also use this notification to inform the MB Service about the update as a result of a OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS *set* request from the MB Service. A response to an OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS *set* request must contain zero elements in the **PreferredListHeader** member. Miniport drivers can also send unsolicited events with this notification to inform the MB Service that the Preferred Multi-Carrier Provider List (PMCPL) has changed. + +This notification uses the [**NDIS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh831864) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh831864) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PREFERRED_MULTICARRIER_PROVIDERS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-preferred-providers.md b/windows-driver-docs-pr/network/ndis-status-wwan-preferred-providers.md new file mode 100644 index 0000000000..0f52054230 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-preferred-providers.md @@ -0,0 +1,66 @@ +--- +title: NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS notification to inform the MB Service that the Preferred Provider List (PPL) has changed. +ms.assetid: b0c06db9-82ca-4f94-80e6-3cf13197abf5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_PREFERRED_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS notification to inform the MB Service that the Preferred Provider List (PPL) has changed. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567913) structure. + +Remarks +------- + +In some cases, the PPL (for GSM-based devices) is updated by the network either Over-The-Air (OTA) or by Short Message Service (SMS). The miniport driver must update the PPL accordingly. Afterwards, miniport drivers must notify the MB Service about the updates using this INDICATION with the updated PPL. For GSM-based networks, the **PreferredListHeader** member of the NDIS\_WWAN\_PREFERRED\_PROVIDERS structure must point to the updated PPL. + +Miniport drivers use this INDICATION to inform the MB Service about the update as a result of a [OID\_WWAN\_PREFERRED\_PROVIDERS](oid-wwan-preferred-providers.md) set request from the MB Service. A response to an OID\_WWAN\_PREFERRED\_PROVIDERS set request must contain zero elements in the **PreferredListHeader** member. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567913) + +[OID\_WWAN\_PREFERRED\_PROVIDERS](oid-wwan-preferred-providers.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PREFERRED_PROVIDERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-preshutdown-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-preshutdown-state.md new file mode 100644 index 0000000000..4e3bc9de64 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-preshutdown-state.md @@ -0,0 +1,50 @@ +--- +title: NDIS_STATUS_WWAN_PRESHUTDOWN_STATE +author: windows-driver-content +description: The NDIS_STATUS_WWAN_PRESHUTDOWN_STATE notification is a one-way notification from the MBB driver to the host. +ms.assetid: 191629A1-2BBF-42D8-A053-827222CE35B0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_PRESHUTDOWN_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PRESHUTDOWN\_STATE + + +The NDIS\_STATUS\_WWAN\_PRESHUTDOWN\_STATE notification is a one-way notification from the MBB driver to the host. The MBB driver sends up this notification when the modem has finished all operations required before shutdown. + +This notification uses the [**NDIS\_WWAN\_PRESHUTDOWN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt593234) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 10, version 1511.

Header

Ndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PRESHUTDOWN_STATE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-provisioned-contexts.md b/windows-driver-docs-pr/network/ndis-status-wwan-provisioned-contexts.md new file mode 100644 index 0000000000..b6764f9646 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-provisioned-contexts.md @@ -0,0 +1,66 @@ +--- +title: NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS notification to inform the MB Service about updates to the list of provisioned contexts as a result of a network update. +ms.assetid: 3ec3d991-98c0-4be3-a157-a04e8565a54b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS notification to inform the MB Service about updates to the list of provisioned contexts as a result of a network update. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_PROVISIONED\_CONTEXTS**](https://msdn.microsoft.com/library/windows/hardware/ff567914) structure. + +Remarks +------- + +Miniport drivers must set the **ElementType** member of the NDIS\_WWAN\_PROVISIONED\_CONTEXTS structure's **ContextListHeader** to **WwanStructContext**. + +In some cases, the list of provisioned contexts is updated by the network either Over-The-Air (OTA) or by Short Message Service (SMS). The miniport driver must update the list of provisioned contexts accordingly. Thereafter, miniport drivers must notify the MB Service about the updates using this INDICATION with the updated list. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PROVISIONED\_CONTEXTS**](https://msdn.microsoft.com/library/windows/hardware/ff567914) + +[OID\_WWAN\_PROVISIONED\_CONTEXTS](oid-wwan-provisioned-contexts.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-radio-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-radio-state.md new file mode 100644 index 0000000000..22d8cbdd66 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-radio-state.md @@ -0,0 +1,64 @@ +--- +title: NDIS\_STATUS\_WWAN\_RADIO\_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_RADIO\_STATE notification to inform the MB Service when the user changes the hardware radio power, or the device's software-based radio power state changes in response to an OID query or set request of OID\_WWAN\_RADIO\_STATE. Miniport drivers can also send unsolicited events with this notification.This notification uses the NDIS\_WWAN\_RADIO\_STATE structure. +ms.assetid: 77c10b2a-ab43-4349-947a-e89c7af27f68 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_RADIO_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_RADIO\_STATE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_RADIO\_STATE notification to inform the MB Service when the user changes the hardware radio power, or the device's software-based radio power state changes in response to an OID query or set request of [OID\_WWAN\_RADIO\_STATE](oid-wwan-radio-state.md). + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567915) structure. + +Remarks +------- + +Miniport drivers should return both the current hardware-based and software-based radio power states in response to a query request + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567915) + +[OID\_WWAN\_RADIO\_STATE](oid-wwan-radio-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_RADIO_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-ready-info.md b/windows-driver-docs-pr/network/ndis-status-wwan-ready-info.md new file mode 100644 index 0000000000..bae221dcb4 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-ready-info.md @@ -0,0 +1,66 @@ +--- +title: NDIS\_STATUS\_WWAN\_READY\_INFO +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_READY\_INFO notification to inform the MB Service of device ready-state changes in response to OID\_WWAN\_READY\_INFO \ 160;query requests. +ms.assetid: 92ddf95f-8829-4259-b53a-c7ce56ee53f0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_READY_INFO Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_READY\_INFO + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_READY\_INFO notification to inform the MB Service of device ready-state changes in response to [OID\_WWAN\_READY\_INFO](oid-wwan-ready-info.md) query requests. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_READY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567916) structure. + +Remarks +------- + +Miniport drivers must report all device ready-state changes as an unsolicited event. When the miniport driver initializes the MB device, the miniport driver must set the WWAN\_READY\_INFO **ReadyState** member to **WwanReadyStateOff**. Thereafter, miniport drivers must report any device ready-state change to the MB Service through this notification. For example, miniport drivers must report a device ready-state change when the **ReadyState** member changes from **WwanReadyStateOff** to **WwanReadyStateDeviceLocked**, or **WwanReadyStateBadSim**, or **WwanReadyStateSimNotInserted**, or any other different device ready-state. + +Most device ready-state changes happen when the device initializes the radio stack and the SIM card (if required). A change can also happen during the course of a session between the MB Service and the miniport driver, such as user changing the SIM card. The behavior of the MB Service shall change accordingly based on the new device ready-state. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_READY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567916) + +[OID\_WWAN\_READY\_INFO](oid-wwan-ready-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_READY_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-register-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-register-state.md new file mode 100644 index 0000000000..df37a24009 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-register-state.md @@ -0,0 +1,112 @@ +--- +title: NDIS\_STATUS\_WWAN\_REGISTER\_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_REGISTER\_STATE notification to communicate changes to the MB device's registration state to the MB Service. +ms.assetid: 3da8489a-6ca3-4897-9794-86665ce10e81 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_REGISTER_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_REGISTER\_STATE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_REGISTER\_STATE notification to communicate changes to the MB device's registration state to the MB Service. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_REGISTRATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567917) structure. + +Remarks +------- + +As the registration state of the device changes, the miniport driver must send appropriate indications so that the MB Service can reflect the correct state to the user. + +Registration state changes due to a number of reasons. It may directly result from *set* requests from the MB Service for OID\_WWAN\_REGISTER\_STATE such as a transient state transition from **WwanRegisterStateSearching** to **WwanRegisterStateHome**. It may also result from automatic operations by the miniport driver in the case of automatic provider selection. Finally, it may be caused by change of network availability, for example, losing network coverage may result in transition from **WwanRegisterStateHome** to **WwanRegisterStateDeregistered**. + +Except for the changes caused by MB Service OID\_WWAN\_REGISTER\_STATE requests, the miniport driver shall notify the MB Service whenever the registration state changes regardless of the underlying cause. + +CDMA devices do not support the MB Service initiated registration and deregistration. However, a device initiated register state change notifications based on the availability or non-availability of the carrier network must be sent to the MB Service. CDMA devices must do automatic registration. + +For devices that do automatic registration on power-up, irrespective of the current registration mode--auto or manual, the miniport driver must send the register state notification on successful registration. + +For manual registration, the MB Service shall only initiate registration after the miniport driver indicates that **ReadyState** is **WwanReadyStateInitialized**. + +Miniport driver must use the following guidelines while responding to *set* requests: + +- Drivers must not respond with transient state for a *set* requests. Transient state for registration is **WwanRegisterStateSearching**. + +- When **RegisterAction** is set to **WwanRegisterActionManual**, if the provider is not visible when the miniport driver receives the request, the miniport driver shall return error code WWAN\_STATUS\_PROVIDER\_NOT\_VISIBLE. The device must not switch to automatic registration because of a failure in setting the manual mode. If the device was earlier set to manually register to another network, this request should change the device to register to the network specified in the request. The value of **RegisterState** in response to the request should be set to **WwanRegisterStateDeregistered**. + +- When **RegisterAction** is set to **WwanRegisterActionManual**, if the miniport driver has already registered with the same network that is been requested, it shall respond with WWAN\_STATUS\_SUCCESS. + +- The driver should attempt to register to the requested data-class in the set OID\_WWAN\_REGISTER request. If the miniport driver cannot register to the requested data-class, it should register to the best possible data-class. This is also applicable when the device is already registered to a provider (automatic and manual registration mode) with some other data-class. Any change in the data-class should also result in NDIS\_STATUS\_WWAN\_PACKET\_SERVICE notification. + +- When **RegisterAction** is set to **WwanRegisterActionManual**, and the Radio is OFF, the miniport driver must program the device to manual registration mode and complete the request with the transaction notification. The **RegisterState** should be set to **WwanRegisterStateDeregistered**. The device must attempt a manual registration when the Radio changes to ON state and the event notification must be sent. + +- When **RegisterAction** is set to **WwanRegisterActionAutomatic**, and the Radio is OFF, the miniport driver must program the device to automatic registration mode and must complete the request with the transaction notification. The **RegisterState** should be set to **WwanRegisterStateDeregistered**. The device must do an automatic registration when the Radio goes to ON state and the event notification must be sent. + +- In case of emergency state registration ( **WwanRegisterStateDenied**), the **uStatus** should be set to WWAN\_STATUS\_SUCCESS and NDIS\_STATUS\_WWAN\_READY\_INFO notification must be sent with **EmergencyMode** set to **WwanEmergencyModeOn**. + +- For using the state **WwanRegisterStateDeregistered** the miniport driver must use the following guidelines: + + - **WwanRegisterStateDeregistered** is used by the miniport drivers for notifying the MB Service that the Radio is OFF but the request for **RegisterAction** is completed. + + - **WwanRegisterStateDeregistered** is used by the miniport drivers for notifying the MB Service of a network initiated deregistration. + + - **WwanRegisterStateDeregistered** is used by the miniport drivers for notifying the MB Service of the lost connectivity to the network due to no network coverage. + +- GSM and CDMA devices must send the register state notification to notify the availability or non-availability of the carrier for a PS connection. When the MB device detects the availability of the carrier network, it must send an event notification with one of the appropriate register states-- **WwanRegisterStateHome**, **WwanRegisterStateRoaming**, or **WwanRegisterStatePartner**. On losing the carrier network signal, an event notification with **WwanRegisterStateDeregistered** must be indicated to the MB Service. + +The miniport driver returns the query result according to the following rules: + +- When the device is trying to lock on to a provider during registration, the miniport driver shall set **RegisterState** as **WwanRegisterStateSearching**. Both the **ProviderName** and **RoamingText** members should be set to **NULL**. In case of Manual register mode, **ProviderId** must be filled in with the ProviderId from the last manual registration set request. **ProviderId** can be set to **NULL** in case of automatic register mode. + +- This is a transient state as the miniport driver will eventually move to a stable state at the end of registration, for example, **WwanRegisterStateHome**, **WwanRegisterStatePartner**, or **WwanRegisterStateRoaming** for a successful registration; or **WwanRegisterStateDenied** for an emergency state registration. + +- If the device is not registered with any provider, the miniport driver shall return **WwanRegisterStateDeregistered**. Both the **ProviderName** and **RoamingText** members should be set to **NULL**. In case of Manual register mode, **ProviderId** must be filled in with the ProviderId from the last manual registration set request. **ProviderId** can be set to **NULL** in case of automatic register mode. + +- If the device is registered with the home provider, the miniport driver shall set **RegisterState** as **WwanRegisterStateHome**. The **ProviderId** member shall be set to the home provider ID. The **ProviderName** must be set to the name of home provider network. The **RoamingText** member should be set to **NULL**. + +- If the device is registered with a roaming provider, the miniport driver shall set **RegisterState** as **WwanRegisterStatePartner** if the provider is a preferred roaming partner or just **WwanRegisterStateRoaming** for a roaming partner, respectively. If the miniport driver does not distinguish the two, it shall set the value to **WwanRegisterStateRoaming**. The **ProviderId** member shall be set to the provider ID of the current provider the device is registered with and the **ProviderName** must be filled in with the current registered provider name. The **RoamingText** member should be set to some provider specific string value if exists or to **NULL** otherwise. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_REGISTRATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567917) + +[OID\_WWAN\_REGISTER\_STATE](oid-wwan-register-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_REGISTER_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-service-activation.md b/windows-driver-docs-pr/network/ndis-status-wwan-service-activation.md new file mode 100644 index 0000000000..afa5bd47b6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-service-activation.md @@ -0,0 +1,57 @@ +--- +title: NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION notification to respond to OID set requests of OID\_WWAN\_SERVICE\_ACTIVATION. +ms.assetid: c5700759-b903-4564-a8b8-c49140d2acd3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SERVICE_ACTIVATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION notification to respond to OID set requests of [OID\_WWAN\_SERVICE\_ACTIVATION](oid-wwan-service-activation.md). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the NDIS\_WWAN\_SERVICE\_ACTIVATION\_STATUS structure. + +Remarks +------- + +Miniport drivers must return the service activation status in response to an OID set request of [OID\_WWAN\_SERVICE\_ACTIVATION](oid-wwan-service-activation.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SERVICE_ACTIVATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-set-home-provider-complete.md b/windows-driver-docs-pr/network/ndis-status-wwan-set-home-provider-complete.md new file mode 100644 index 0000000000..fbe7fe213d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-set-home-provider-complete.md @@ -0,0 +1,50 @@ +--- +title: NDIS_STATUS_WWAN_SET_HOME_PROVIDER_COMPLETE +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_SET_HOME_PROVIDER_COMPLETE notification to inform the MB Service about the completion of OID_WWAN_HOME_PROVIDER set requests. This notification uses the NDIS_WWAN_SET_HOME_PROVIDER structure. +ms.assetid: 458B5AF6-4785-4A19-9B8D-5A7CF04D5AB4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_SET_HOME_PROVIDER_COMPLETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SET\_HOME\_PROVIDER\_COMPLETE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SET\_HOME\_PROVIDER\_COMPLETE notification to inform the MB Service about the completion of [OID\_WWAN\_HOME\_PROVIDER](https://msdn.microsoft.com/library/windows/hardware/ff569826) set requests. + +This notification uses the [**NDIS\_WWAN\_SET\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/hh439841) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SET_HOME_PROVIDER_COMPLETE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-signal-state.md b/windows-driver-docs-pr/network/ndis-status-wwan-signal-state.md new file mode 100644 index 0000000000..647f91e70e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-signal-state.md @@ -0,0 +1,68 @@ +--- +title: NDIS\_STATUS\_WWAN\_SIGNAL\_STATE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SIGNAL\_STATE notification to send a signal strength notification when measured signal strength travels outside the threshold within a pre-defined interval. +ms.assetid: b5d6b2a6-ed19-45d9-85ca-ac66e38f41fd +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SIGNAL_STATE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SIGNAL\_STATE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SIGNAL\_STATE notification to send a signal strength notification when measured signal strength travels outside the threshold within a pre-defined interval. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_SIGNAL\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567931) structure. + +Remarks +------- + +By default, miniport drivers must notify the MB Service if the Rssi value changes by at least +/-5 decibels from the last reported value, or at a maximum frequency of one indication every 5 seconds. The threshold value is specified in the **SignalState.RssiThreshold** member of the NDIS\_WWAN\_SIGNAL\_STATE structure; while the maximum frequency value is specified in the **SignalState.RssiInterval** member. + +The **DeviceCaps.WwanCellularClass** member of the NDIS\_WWAN\_DEVICE\_CAPS structure controls how the Rssi value will be interpreted by the MB Service. If **WwanCellularClass** is **WwanCellularClassGSM**, Rssi is reported as decibels above the device's sensitivity noise floor. If **WwanCellularClass** is **WwanCellularClassCDMA**, Rssi is reported as compensated RSSI (accounts for noise). + +Applications should never poll for signal strength. Only in special situations, such as startup, an application might use a *query* request to obtain signal strength. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SIGNAL\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567931) + +[OID\_WWAN\_SIGNAL\_STATE](oid-wwan-signal-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SIGNAL_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-slot-info-status.md b/windows-driver-docs-pr/network/ndis-status-wwan-slot-info-status.md new file mode 100644 index 0000000000..07bc491028 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-slot-info-status.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_SLOT_INFO +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_SLOT_INFO notification to inform the MB service about the completion of a previous OID_WWAN_SLOT_INFO query request. +ms.assetid: FA1E16E4-56A3-4401-875F-D75DD01FE75D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_SLOT_INFO Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SLOT\_INFO + + +Miniport drivers use the **NDIS\_STATUS\_WWAN\_SLOT\_INFO** notification to inform the MB service about the completion of a previous [OID\_WWAN\_SLOT\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799832) query request. + +Miniport drivers can send a **NDIS\_STATUS\_WWAN\_SLOT\_INFO** notification as an unsolicited event when the slot/card state changes. + +This notification uses the [**NDIS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782408) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SLOT\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799832) + +[**NDIS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782408) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SLOT_INFO%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sms-configuration.md b/windows-driver-docs-pr/network/ndis-status-wwan-sms-configuration.md new file mode 100644 index 0000000000..76130ef79c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sms-configuration.md @@ -0,0 +1,64 @@ +--- +title: NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION notification to inform the MB Service about either the completion of a previous OID\_WWAN\_SMS\_CONFIGURATION \ 160;query or set request, or an event notification in the case of change in SMS configuration. Miniport drivers can also send unsolicited events with this notification.This notification uses the NDIS\_WWAN\_SMS\_CONFIGURATION structure. +ms.assetid: 86dfe2dc-070b-43d9-b6fa-54dee985c65d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SMS_CONFIGURATION Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION notification to inform the MB Service about either the completion of a previous [OID\_WWAN\_SMS\_CONFIGURATION](oid-wwan-sms-configuration.md) query or set request, or an event notification in the case of change in SMS configuration. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567935) structure. + +Remarks +------- + +The miniport driver must send this unsolicited indication when the MB device's SMS subsystem is ready for SMS operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SMS\_CONFIGURATION](oid-wwan-sms-configuration.md) + +[**NDIS\_WWAN\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567935) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SMS_CONFIGURATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sms-delete.md b/windows-driver-docs-pr/network/ndis-status-wwan-sms-delete.md new file mode 100644 index 0000000000..07d1c932f6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sms-delete.md @@ -0,0 +1,62 @@ +--- +title: NDIS\_STATUS\_WWAN\_SMS\_DELETE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_DELETE notification to inform the MB Service about the completion of a previous delete request through OID\_WWAN\_SMS\_DELETE. +ms.assetid: 0083dcd9-4e18-4582-993a-c4402cb552de +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SMS_DELETE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SMS\_DELETE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_DELETE notification to inform the MB Service about the completion of a previous delete request through [OID\_WWAN\_SMS\_DELETE](oid-wwan-sms-delete.md). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_SMS\_DELETE\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567940) structure. + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SMS\_DELETE](oid-wwan-sms-delete.md) + +[**NDIS\_WWAN\_SMS\_DELETE\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567940) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SMS_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sms-receive.md b/windows-driver-docs-pr/network/ndis-status-wwan-sms-receive.md new file mode 100644 index 0000000000..44c787bf2e --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sms-receive.md @@ -0,0 +1,70 @@ +--- +title: NDIS\_STATUS\_WWAN\_SMS\_RECEIVE +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_RECEIVE notification to inform the MB Service about either the completion of a previous read request through a OID\_WWAN\_SMS\_READ \ 160;query request, or the arrival of a new class-0 (flash/alert) message from the network provider as an event notification. Miniport drivers can also send unsolicited events with this notification.This notification uses the NDIS\_WWAN\_SMS\_RECEIVE structure. +ms.assetid: fc1c3587-8bba-4ffd-9561-4140c307c705 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SMS_RECEIVE Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SMS\_RECEIVE + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_RECEIVE notification to inform the MB Service about either the completion of a previous read request through a [OID\_WWAN\_SMS\_READ](oid-wwan-sms-read.md) query request, or the arrival of a new class-0 (flash/alert) message from the network provider as an event notification. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_SMS\_RECEIVE**](https://msdn.microsoft.com/library/windows/hardware/ff567942) structure. + +Remarks +------- + +RequestId is set to "0" by the miniport driver to indicate the arrival of the new class-0 (flash/alert) message. Arrival of new class-0 (flash/alert) messages is dependent on the current network registration state. + +If the request for read results in retrieval of large number of SMS records that can't be accommodated in a pre-allocated buffer of miniport driver, then the SMS records can be sent to the MB Service in multiple indications. The uStatus in this case must be set to WWAN\_STATUS\_SMS\_MORE\_DATA for the intermediate transactions and the final transaction must end with WWAN\_STATUS\_SUCCESS. + +The following diagram represents the usage of the multiple indication method for large number of SMS record retrieval: + +![diagram illustrating the usage of the multiple indication method for a large number of sms record retrieval](images/wwansmsrecordretrieval.png) + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SMS\_READ](oid-wwan-sms-read.md) + +[**NDIS\_WWAN\_SMS\_RECEIVE**](https://msdn.microsoft.com/library/windows/hardware/ff567942) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SMS_RECEIVE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sms-send.md b/windows-driver-docs-pr/network/ndis-status-wwan-sms-send.md new file mode 100644 index 0000000000..f81bebf367 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sms-send.md @@ -0,0 +1,62 @@ +--- +title: NDIS\_STATUS\_WWAN\_SMS\_SEND +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_SEND notification to inform the MB Service about the completion of a previous send request through OID\_WWAN\_SMS\_SEND. +ms.assetid: f750b09c-1a7c-40d8-8a4e-a7f9f3160248 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SMS_SEND Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SMS\_SEND + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_SEND notification to inform the MB Service about the completion of a previous send request through [OID\_WWAN\_SMS\_SEND](oid-wwan-sms-send.md). + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_SMS\_SEND\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567944) structure. + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SMS\_SEND](oid-wwan-sms-send.md) + +[**NDIS\_WWAN\_SMS\_SEND\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567944) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SMS_SEND%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sms-status.md b/windows-driver-docs-pr/network/ndis-status-wwan-sms-status.md new file mode 100644 index 0000000000..5b8d2f8071 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sms-status.md @@ -0,0 +1,70 @@ +--- +title: NDIS\_STATUS\_WWAN\_SMS\_STATUS +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_STATUS notification to inform the MB Service about the following events The MB device's message store is full.A new SMS text message has arrived, with the new message corresponding to MessageIndex.Miniport drivers can also send unsolicited events with this notification.This notification uses the NDIS\_WWAN\_SMS\_STATUS structure. +ms.assetid: 65553a3f-57af-49ef-a3b7-ed35df0a319d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_SMS_STATUS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SMS\_STATUS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SMS\_STATUS notification to inform the MB Service about the following events: + +- The MB device's message store is full. + +- A new SMS text message has arrived, with the new message corresponding to *MessageIndex*. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_SMS\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567945) structure. + +Remarks +------- + +Miniport drivers must use NDIS\_STATUS\_WWAN\_SMS\_STATUS to inform the MB Service about the arrival of all non-class-0 (flash/alert) messages. To inform the MB Service about class-0 (flash/alert) message arrival, miniport drivers must use [**NDIS\_STATUS\_WWAN\_SMS\_RECEIVE**](ndis-status-wwan-sms-receive.md). + +This indication could be a transactional notification for a *query* request of OID\_WWAN\_SMS\_STATUS or an unsolicited event. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SMS\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567945) + +[**NDIS\_STATUS\_WWAN\_SMS\_RECEIVE**](ndis-status-wwan-sms-receive.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SMS_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-supported-device-services.md b/windows-driver-docs-pr/network/ndis-status-wwan-supported-device-services.md new file mode 100644 index 0000000000..f7a32e9628 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-supported-device-services.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_SUPPORTED_DEVICE_SERVICES +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_SUPPORTED_DEVICE_SERVICES notification to inform the MB Service about the completion of OID_WWAN_ENUMERATE_DEVICE_SERVICES query requests.NDIS_WWAN_SUPPORTED_DEVICE_SERVICES structure. +ms.assetid: 6364DDF7-CE68-4E00-8532-221DD209F145 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_SUPPORTED_DEVICE_SERVICES Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES notification to inform the MB Service about the completion of [OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES](https://msdn.microsoft.com/library/windows/hardware/hh846220) query requests. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/hh831867) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES](https://msdn.microsoft.com/library/windows/hardware/hh846220) + +[**NDIS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/hh831867) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SUPPORTED_DEVICE_SERVICES%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-sys-caps.md b/windows-driver-docs-pr/network/ndis-status-wwan-sys-caps.md new file mode 100644 index 0000000000..b17e06b4e8 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-sys-caps.md @@ -0,0 +1,59 @@ +--- +title: NDIS_STATUS_WWAN_SYS_CAPS_INFO +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_SYS_CAPS_INFO notification to inform the MB service about the completion of a previous OID_WWAN_SYS_CAPS_INFO query request. +ms.assetid: 653A35EC-29BB-458D-B33C-41EF6EF47A6E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_SYS_CAPS_INFO Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_SYS\_CAPS\_INFO + + +Miniport drivers use the **NDIS\_STATUS\_WWAN\_SYS\_CAPS\_INFO** notification to inform the MB service about the completion of a previous [OID\_WWAN\_SYS\_CAPS\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799833) query request. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782410) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_SYS\_CAPS\_INFO](https://msdn.microsoft.com/library/windows/hardware/mt799833) + +[**NDIS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782410) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_SYS_CAPS_INFO%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-ussd.md b/windows-driver-docs-pr/network/ndis-status-wwan-ussd.md new file mode 100644 index 0000000000..23a82c47f6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-ussd.md @@ -0,0 +1,57 @@ +--- +title: NDIS_STATUS_WWAN_USSD +author: windows-driver-content +description: Miniport drivers use the NDIS_STATUS_WWAN_USSD notification to implement the transaction completion response for Unstructured Supplementary Service Data (USSD) operations with the NDIS_WWAN_USSD_REQUEST structure.Miniport drivers can also send unsolicited events with this notification using the NDIS_WWAN_USSD_EVENT structure to describe the nature of the USSD event. +ms.assetid: 6EE1235A-486E-4653-BFAC-6151C795676B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_STATUS_WWAN_USSD Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_USSD + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_USSD notification to implement the transaction completion response for Unstructured Supplementary Service Data (USSD) operations with the [NDIS\_WWAN\_USSD\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh439846) structure. + +Miniport drivers can also send unsolicited events with this notification using the [NDIS\_WWAN\_USSD\_EVENT](https://msdn.microsoft.com/library/windows/hardware/hh439844) structure to describe the nature of the USSD event. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[NDIS\_WWAN\_USSD\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh439846) + +[NDIS\_WWAN\_USSD\_EVENT](https://msdn.microsoft.com/library/windows/hardware/hh439844) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_USSD%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-vendor-specific.md b/windows-driver-docs-pr/network/ndis-status-wwan-vendor-specific.md new file mode 100644 index 0000000000..26fdaf2e66 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-vendor-specific.md @@ -0,0 +1,62 @@ +--- +title: NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC notification to implement the transaction completion response for vendor specific operation or vendor specific change notifications. +ms.assetid: 2032ed5e-8a4a-4c1c-9dbe-05e7cec1b683 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_VENDOR_SPECIFIC Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC notification to implement the transaction completion response for vendor specific operation or vendor specific change notifications. + +Miniport drivers can also send unsolicited events with this notification. + +This notification uses the [**NDIS\_WWAN\_VENDOR\_SPECIFIC**](https://msdn.microsoft.com/library/windows/hardware/ff567947) structure. + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_VENDOR\_SPECIFIC**](https://msdn.microsoft.com/library/windows/hardware/ff567947) + +[OID\_WWAN\_VENDOR\_SPECIFIC](oid-wwan-vendor-specific.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_VENDOR_SPECIFIC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-status-wwan-visible-providers.md b/windows-driver-docs-pr/network/ndis-status-wwan-visible-providers.md new file mode 100644 index 0000000000..c2d942ca22 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-status-wwan-visible-providers.md @@ -0,0 +1,62 @@ +--- +title: NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS +author: windows-driver-content +description: Miniport drivers use the NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS notification to inform the MB Service about the completion of OID\_WWAN\_VISIBLE\_PROVIDERS \ 160;query requests. +ms.assetid: 57e79d45-536a-4ab9-8cc0-0408d722b6f7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_STATUS_WWAN_VISIBLE_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS + + +Miniport drivers use the NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS notification to inform the MB Service about the completion of [OID\_WWAN\_VISIBLE\_PROVIDERS](oid-wwan-visible-providers.md) query requests. + +Miniport drivers cannot use this notification to send unsolicited events. + +This notification uses the [**NDIS\_WWAN\_VISIBLE\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567948) structure. + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_VISIBLE\_PROVIDERS](oid-wwan-visible-providers.md) + +[**NDIS\_WWAN\_VISIBLE\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567948) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_STATUS_WWAN_VISIBLE_PROVIDERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-supported-wmi-operations.md b/windows-driver-docs-pr/network/ndis-supported-wmi-operations.md index ef822ab5df..ba108b1f80 100644 --- a/windows-driver-docs-pr/network/ndis-supported-wmi-operations.md +++ b/windows-driver-docs-pr/network/ndis-supported-wmi-operations.md @@ -43,7 +43,7 @@ NDIS supports the following WMI operations: - EXECUTE METHOD - Through NDIS, a WMI client can run a method that is associated with a data block, which corresponds to a single OID. WMI clients provide the information that NDIS requires to run the method. The NDIS\_WMI\_DEFAULT\_METHOD\_ID method identifier specifies the default method. Method requests can be associated with miniport adapters, NDIS ports, or VCs. NDIS returns the resulting information after the method is successfully run. + Through NDIS, a WMI client can run a method that is associated with a data block, which corresponds to a single OID. WMI clients provide the information that NDIS requires to run the method. Method requests can be associated with miniport adapters, NDIS ports, or VCs. NDIS returns the resulting information after the method is successfully run.   diff --git a/windows-driver-docs-pr/network/ndis-switch-nic-at-array-index.md b/windows-driver-docs-pr/network/ndis-switch-nic-at-array-index.md new file mode 100644 index 0000000000..0e1d6e6918 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-nic-at-array-index.md @@ -0,0 +1,88 @@ +--- +title: NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX macro to access an NDIS\_SWITCH\_NIC\_PARAMETERS element inside an NDIS\_SWITCH\_NIC\_ARRAY structure. +ms.assetid: 356DE3C3-38E3-47FB-A595-1A1CAEA10312 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_SWITCH_NIC_AT_ARRAY_INDEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX** macro to access an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) element inside an [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_NIC_PARAMETERS NDIS_SWITCH_NIC_AT_ARRAY_INDEX( +  PNDIS_SWITCH_NIC_ARRAY _NicArray_, +  USHORT                 _Index_ +); +``` + +Parameters +---------- + +*\_NicArray\_* +A pointer to an [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure. + +*\_Index\_* +A USHORT value that specifies the zero-based index of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) element inside the [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212). + +**Note**  This value must be less than the value of the **NumElements** member of the [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure. + +  + +Return value +------------ + +The **NDIS\_SWITCH\_NIC\_AT\_ARRAY\_INDEX** macro returns a pointer to the specified [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) element inside the [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_NIC_AT_ARRAY_INDEX%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-at-array-index.md b/windows-driver-docs-pr/network/ndis-switch-port-at-array-index.md new file mode 100644 index 0000000000..2002cdd269 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-at-array-index.md @@ -0,0 +1,88 @@ +--- +title: NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX macro to access an NDIS\_SWITCH\_PORT\_PARAMETERS element inside an NDIS\_SWITCH\_PORT\_ARRAY structure. +ms.assetid: C632350C-CD13-4564-B8E5-4FE90B674510 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_SWITCH_PORT_AT_ARRAY_INDEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX** macro to access an [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) element inside an [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PORT_PARAMETERS NDIS_SWITCH_PORT_AT_ARRAY_INDEX( +  PNDIS_SWITCH_PORT_ARRAY _PortArray_, +  USHORT                  _Index_ +); +``` + +Parameters +---------- + +*\_PortArray\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) structure. + +*\_Index\_* +A USHORT value that specifies the zero-based index of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) element inside the [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221). + +**Note**  This value must be less than the value of the **NumElements** member of the [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) structure. + +  + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_AT\_ARRAY\_INDEX** macro returns a pointer to the specified [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) element inside the [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_AT_ARRAY_INDEX%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-destination-at-array-index.md b/windows-driver-docs-pr/network/ndis-switch-port-destination-at-array-index.md new file mode 100644 index 0000000000..b1a33eaf79 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-destination-at-array-index.md @@ -0,0 +1,88 @@ +--- +title: NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX macro to access an NDIS_SWITCH_PORT_DESTINATION element inside an NDIS_SWITCH_FORWARDING_DESTINATION_ARRAY structure. +ms.assetid: 2FD94E64-1E15-426D-822A-B6F5FC035C92 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_DESTINATION\_AT\_ARRAY\_INDEX macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_DESTINATION\_AT\_ARRAY\_INDEX** macro to access an [**NDIS\_SWITCH\_PORT\_DESTINATION**](https://msdn.microsoft.com/library/windows/hardware/hh598224) element inside an [**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PORT_DESTINATION NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX( +  PNDIS_SWITCH_FORWARDING_DESTINATION_ARRAY _DestArray_, +  USHORT                                    _Index_ +); +``` + +Parameters +---------- + +*\_DestArray\_* +A pointer to an [**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210) structure. + +*\_Index\_* +A USHORT value that specifies the zero-based index of the [**NDIS\_SWITCH\_PORT\_DESTINATION**](https://msdn.microsoft.com/library/windows/hardware/hh598224) element inside the [**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210). + +**Note**  This value must be less than the value of the **NumElements** member of the [**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210) structure. + +  + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_DESTINATION\_AT\_ARRAY\_INDEX** macro returns a pointer to the specified [**NDIS\_SWITCH\_PORT\_DESTINATION**](https://msdn.microsoft.com/library/windows/hardware/hh598224) element inside the [**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_DESTINATION**](https://msdn.microsoft.com/library/windows/hardware/hh598224) + +[**NDIS\_SWITCH\_FORWARDING\_DESTINATION\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598210) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_DESTINATION_AT_ARRAY_INDEX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-custom-get-buffer.md b/windows-driver-docs-pr/network/ndis-switch-port-property-custom-get-buffer.md new file mode 100644 index 0000000000..51a6a5f228 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-custom-get-buffer.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER macro to access the custom port property buffer inside an NDIS_SWITCH_PORT_PROPERTY_CUSTOM structure. +ms.assetid: 6271BE89-F5C3-41F5-A9C2-B6AE69273F70 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM\_GET\_BUFFER macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM\_GET\_BUFFER** macro to access the custom port property buffer inside an [**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER( +  PNDIS_SWITCH_PORT_PROPERTY_CUSTOM __PortPropertyCustom__ +); +``` + +Parameters +---------- + +*\_\_PortPropertyCustom\_\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM\_GET\_BUFFER** returns a pointer to the custom port property buffer inside an [**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_CUSTOM_GET_BUFFER%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-next.md b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-next.md new file mode 100644 index 0000000000..74e3793a93 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-next.md @@ -0,0 +1,80 @@ +--- +title: NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT macro to access the next NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO element that follows an NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO structure in the array that is specified by an NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS structure. +ms.assetid: 103DE1CC-08DA-4F79-9F20-BA15C5245080 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_NEXT macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_NEXT** macro to access the next [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) element that follows an **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO** structure in the array that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PORT_PROPERTY_ENUM_INFO NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT( +  PNDIS_SWITCH_PORT_PROPERTY_ENUM_INFO __PortEnumInfo__ +); +``` + +Parameters +---------- + +*\_\_PortEnumInfo\_\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_NEXT** macro returns a pointer to the next [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) element in the array. If the *\_\_PortEnumInfo\_\_* parameter is the last element in the array, the macro returns **NULL**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-property.md b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-property.md new file mode 100644 index 0000000000..cf9cc294cb --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-info-get-property.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY macro to access the port property buffer that is specified by an NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO structure. +ms.assetid: 76E08A71-E030-4814-AE4D-D55974968F3A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY** macro to access the port property buffer that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY( +  PVOID __PortEnumInfo__ +); +``` + +Parameters +---------- + +*\_\_PortEnumInfo\_\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY** macro returns a pointer to the port property buffer. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_PROPERTY%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-enum-parameters-get-first-info.md b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-parameters-get-first-info.md new file mode 100644 index 0000000000..8deff91964 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-enum-parameters-get-first-info.md @@ -0,0 +1,80 @@ +--- +title: NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro to access the first NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO element that is specified by an NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS structure. +ms.assetid: 43DDB75F-7CD6-421E-9AC6-C9C96A2348D4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO** macro to access the first [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) element that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PORT_PROPERTY_ENUM_INFO NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO( +  PNDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS _PortEnumParams_ +); +``` + +Parameters +---------- + +*\_PortEnumParams\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO** macro returns a pointer to the first [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) element that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-parameters-get-property.md b/windows-driver-docs-pr/network/ndis-switch-port-property-parameters-get-property.md new file mode 100644 index 0000000000..4d79297fc5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-parameters-get-property.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY macro to access the port property buffer inside an NDIS_SWITCH_PORT_PROPERTY_PARAMETERS structure. +ms.assetid: 51E84480-1858-4B7A-BB4E-A2EA72149271 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS\_GET\_PROPERTY macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS\_GET\_PROPERTY** macro to access the port property buffer inside an [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY( +  PNDIS_SWITCH_PORT_PROPERTY_PARAMETERS _PortParameters_ +); +``` + +Parameters +---------- + +*\_PortParameters\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS\_GET\_PROPERTY** macro returns a pointer to the port property buffer inside an [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_PARAMETERS_GET_PROPERTY%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-port-property-routing-domain-get-first-isolation-entry.md b/windows-driver-docs-pr/network/ndis-switch-port-property-routing-domain-get-first-isolation-entry.md new file mode 100644 index 0000000000..f41debf629 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-port-property-routing-domain-get-first-isolation-entry.md @@ -0,0 +1,79 @@ +--- +title: NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN\_GET\_FIRST\_ISOLATION\_ENTRY macro +author: windows-driver-content +description: The NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN\_GET\_FIRST\_ISOLATION\_ENTRY macro is used to access the first NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY that is specified by an NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN structure. +ms.assetid: AB873417-5FBD-4D01-92E7-B9BF466333BC +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN_GET_FIRST_ISOLATION_ENTRY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN\_GET\_FIRST\_ISOLATION\_ENTRY macro + + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN\_GET\_FIRST\_ISOLATION\_ENTRY** macro is used to access the first [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) that is specified by an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN**](https://msdn.microsoft.com/library/windows/hardware/dn383688) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_ROUTING_DOMAIN_ISOLATION_ENTRY NDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN_GET_FIRST_ISOLATION_ENTRY( +  PNDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN _RoutingDomainProperty_ +); +``` + +Parameters +---------- + +*\_RoutingDomainProperty\_* +A pointer to an [**NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN**](https://msdn.microsoft.com/library/windows/hardware/dn383688) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN\_GET\_FIRST\_ISOLATION\_ENTRY** macro returns a pointer to the first [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ROUTING\_DOMAIN**](https://msdn.microsoft.com/library/windows/hardware/dn383688) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN_GET_FIRST_ISOLATION_ENTRY%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-property-custom-get-buffer.md b/windows-driver-docs-pr/network/ndis-switch-property-custom-get-buffer.md new file mode 100644 index 0000000000..a5ff1672c1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-property-custom-get-buffer.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER macro to access the custom extensible switch property buffer inside an NDIS_SWITCH_PROPERTY_CUSTOM structure. +ms.assetid: 40D17048-0014-4FFE-8FEA-73E94CC7AD32 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PROPERTY\_CUSTOM\_GET\_BUFFER macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PROPERTY\_CUSTOM\_GET\_BUFFER** macro to access the custom extensible switch property buffer inside an [**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER( +  PNDIS_SWITCH_PROPERTY_CUSTOM _SwitchPropertyCustom_ +); +``` + +Parameters +---------- + +*\_SwitchPropertyCustom\_* +A pointer to an [**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PROPERTY\_CUSTOM\_GET\_BUFFER** returns a pointer to the custom extensible switch property buffer inside an [**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PROPERTY_CUSTOM_GET_BUFFER%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-next.md b/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-next.md new file mode 100644 index 0000000000..402a439485 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-next.md @@ -0,0 +1,80 @@ +--- +title: NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_NEXT macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_NEXT macro to access the next NDIS_SWITCH_PROPERTY_ENUM_INFO element that follows an NDIS_SWITCH_PROPERTY_ENUM_INFO structure in the array that is specified by an NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS structure. +ms.assetid: 81A8B9AE-E401-4A8A-A84E-93F745B34954 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_NEXT macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_NEXT macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_NEXT** macro to access the next [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) element that follows an **NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO** structure in the array that is specified by an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PROPERTY_ENUM_INFO NDIS_SWITCH_PORT_PROPERTY_ENUM_INFO_GET_NEXT( +  PNDIS_SWITCH_PROPERTY_ENUM_INFO _SwitchEnumInfo_ +); +``` + +Parameters +---------- + +*\_SwitchEnumInfo\_* +A pointer to an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_NEXT** macro returns a pointer to the next [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) element in the array. If the *\_SwitchEnumInfo\_* parameter is the last element in the array, the macro returns **NULL**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_NEXT%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-property.md b/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-property.md new file mode 100644 index 0000000000..3d310f084b --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-property-enum-info-get-property.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY macro to access the extensible switch property buffer that is specified by an NDIS_SWITCH_PROPERTY_ENUM_INFO structure. +ms.assetid: D158A9FB-8646-40FD-9C2F-98BFB30A6125 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY** macro to access the extensible switch property buffer that is specified by an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY( +  PVOID _SwitchEnumInfo_ +); +``` + +Parameters +---------- + +*\_SwitchEnumInfo\_* +A pointer to an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO\_GET\_PROPERTY** macro returns a pointer to the extensible switch property buffer. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PROPERTY_ENUM_INFO_GET_PROPERTY%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-property-enum-parameters-get-first-info.md b/windows-driver-docs-pr/network/ndis-switch-property-enum-parameters-get-first-info.md new file mode 100644 index 0000000000..a00023f668 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-property-enum-parameters-get-first-info.md @@ -0,0 +1,80 @@ +--- +title: NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro to access the first NDIS_SWITCH_PROPERTY_ENUM_INFO element that is specified by an NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS structure. +ms.assetid: C12E4047-A558-4812-A9F9-6AA68FF10928 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO** macro to access the first [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) element that is specified by an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_PROPERTY_ENUM_INFO NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO( +  PNDIS_SWITCH_PROPERTY_ENUM_PARAMETERS _SwitchEnumParams_ +); +``` + +Parameters +---------- + +*\_SwitchEnumParams\_* +A pointer to an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS\_GET\_FIRST\_INFO** macro returns a pointer to the first [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) element that is specified by an [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS_GET_FIRST_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-switch-property-parameters-get-property.md b/windows-driver-docs-pr/network/ndis-switch-property-parameters-get-property.md new file mode 100644 index 0000000000..fb6c3a7779 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-switch-property-parameters-get-property.md @@ -0,0 +1,78 @@ +--- +title: NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY macro to access the extensible switch property buffer inside an NDIS_SWITCH_PROPERTY_PARAMETERS structure. +ms.assetid: EED459C4-F01E-4C39-9936-93F597751414 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_SWITCH\_PROPERTY\_PARAMETERS\_GET\_PROPERTY macro + + +Hyper-V extensible switch extensions use the **NDIS\_SWITCH\_PROPERTY\_PARAMETERS\_GET\_PROPERTY** macro to access the extensible switch property buffer inside an [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY( +  PNDIS_SWITCH_PROPERTY_PARAMETERS _SwitchParameters_ +); +``` + +Parameters +---------- + +*\_SwitchParameters\_* +A pointer to an [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure. + +Return value +------------ + +The **NDIS\_SWITCH\_PROPERTY\_PARAMETERS\_GET\_PROPERTY** macro returns a pointer to the extensible switch property buffer inside an [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_SWITCH_PROPERTY_PARAMETERS_GET_PROPERTY%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-tcp-ip-offload-status-indications.md b/windows-driver-docs-pr/network/ndis-tcp-ip-offload-status-indications.md new file mode 100644 index 0000000000..acda5f379d --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-tcp-ip-offload-status-indications.md @@ -0,0 +1,37 @@ +--- +title: NDIS TCP/IP Offload Status Indications +author: windows-driver-content +description: NDIS TCP/IP Offload Status Indications +ms.assetid: 181539a5-1855-4092-86d0-e6d5eb154119 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS TCP/IP Offload Status Indications + + +## + + +This section includes: + +[**NDIS\_STATUS\_TASK\_OFFLOAD\_CURRENT\_CONFIG**](ndis-status-task-offload-current-config.md) + +[**NDIS\_STATUS\_TASK\_OFFLOAD\_HARDWARE\_CAPABILITIES**](ndis-status-task-offload-hardware-capabilities.md) + +[**NDIS\_STATUS\_OFFLOAD\_ENCASPULATION\_CHANGE**](ndis-status-offload-encaspulation-change.md) + +[**NDIS\_STATUS\_TCP\_CONNECTION\_OFFLOAD\_HARDWARE\_CAPABILITIES**](ndis-status-tcp-connection-offload-hardware-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20TCP/IP%20Offload%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-version-guide.md b/windows-driver-docs-pr/network/ndis-version-guide.md new file mode 100644 index 0000000000..c4075c5114 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-version-guide.md @@ -0,0 +1,21 @@ +--- +title: NDIS version guide +description: This section contains information about the different versions of NDIS and how to port drivers from older versions of NDIS to newer versions +ms.assetid: 5B1AB601-6C84-44AA-8333-C8FC723CAA7A +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS version guide + +This section contains an overview of the different versions of NDIS, introductions to each major version of NDIS starting with NDIS 6.0, information for specifying NDIS versions, and guidance on porting NDIS drivers to newer versions. + +- [Overview of NDIS versions](overview-of-ndis-versions.md) +- [Introductions to NDIS 6.0 and later](introductions-to-ndis-6-0-and-later.md) +- [Specifying NDIS Version Information](specifying-ndis-version-information.md) +- [Porting NDIS Drivers to Newer NDIS Versions](porting-ndis-drivers-to-newer-ndis-versions.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/ndis-wait-for-mutex.md b/windows-driver-docs-pr/network/ndis-wait-for-mutex.md new file mode 100644 index 0000000000..af248a021c --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-wait-for-mutex.md @@ -0,0 +1,123 @@ +--- +title: NDIS_WAIT_FOR_MUTEX macro +author: windows-driver-content +description: The NDIS_WAIT_FOR_MUTEX macro puts the current thread into the wait state until the specified mutex object is set to the signaled state. +ms.assetid: eaa323cc-4a17-4e94-8779-16efa079c5c4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS_WAIT_FOR_MUTEX macro Network Drivers Starting with Windows Vista +--- + +# NDIS\_WAIT\_FOR\_MUTEX macro + + +The NDIS\_WAIT\_FOR\_MUTEX macro puts the current thread into the wait state until the specified mutex object is set to the signaled state. + +Syntax +------ + +```ManagedCPlusPlus +NTSTATUS NDIS_WAIT_FOR_MUTEX( +  PNDIS_MUTEX _Mutex_ +); +``` + +Parameters +---------- + +*\_Mutex\_* +A pointer to an initialized NDIS\_MUTEX-type mutex object. The caller initialized the mutex object in a prior call to the [**NDIS\_INIT\_MUTEX**](ndis-init-mutex.md) macro. NDIS\_MUTEX is a wrapper for the KMUTEX type. + +Return value +------------ + +NDIS\_WAIT\_FOR\_MUTEX returns the following status value: + + ++++ + + + + + + + + + + + + +
Return codeDescription
STATUS_SUCCESS

The operation completed successfully.

+ +  + +Remarks +------- + +NDIS network drivers should use the NDIS\_WAIT\_FOR\_MUTEX macro to wait for a mutex to transition to the signaled state. + +A driver cannot wait for a nonzero time interval on a mutex object at a raised IRQL or in an *arbitrary thread context* (that is, the context of whatever thread is current when a driver function is called). + +NDIS\_WAIT\_FOR\_MUTEX examines the current state of the mutex object to determine if the wait operation can be satisfied immediately. If the operation can be satisfied immediately, the necessary updates are made to mutex object. Otherwise, the current thread is in a waiting state, and a new thread is selected for execution on the current processor. + +This macro is an NDIS wrapper for the [**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) routine. + +Callers of NDIS\_WAIT\_FOR\_MUTEX must be running at IRQL = PASSIVE\_LEVEL and in a nonarbitrary thread context. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL (see Remarks section)

DDI compliance rules

[Irql_Synch_Function](https://msdn.microsoft.com/library/windows/hardware/ff548015)
+ +## See also + + +[**KeWaitForSingleObject**](https://msdn.microsoft.com/library/windows/hardware/ff553350) + +[**NDIS\_INIT\_MUTEX**](ndis-init-mutex.md) + +[**NDIS\_RELEASE\_MUTEX**](ndis-release-mutex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS_WAIT_FOR_MUTEX%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-wake-reason-status-indications-ref.md b/windows-driver-docs-pr/network/ndis-wake-reason-status-indications-ref.md new file mode 100644 index 0000000000..c7eb7c0437 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-wake-reason-status-indications-ref.md @@ -0,0 +1,34 @@ +--- +title: NDIS Wake Reason Status Indications +author: windows-driver-content +description: NDIS Wake Reason Status Indications +ms.assetid: 2F79CB52-0359-4E14-B7A2-49CA55568C44 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS Wake Reason Status Indications + + +This section includes the following reference topics for the data types used with NDIS wake reason status indications: + +[**NDIS\_STATUS\_PM\_WAKE\_REASON**](ndis-status-pm-wake-reason.md) + +[**NDIS\_PM\_WAKE\_PACKET**](https://msdn.microsoft.com/library/windows/hardware/hh451603) + +[**NDIS\_PM\_WAKE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/hh451605) + +[**NDIS\_PM\_WAKE\_REASON\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh451607) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20Wake%20Reason%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndis-wan-status-indications.md b/windows-driver-docs-pr/network/ndis-wan-status-indications.md new file mode 100644 index 0000000000..94d5a005d0 --- /dev/null +++ b/windows-driver-docs-pr/network/ndis-wan-status-indications.md @@ -0,0 +1,47 @@ +--- +title: NDIS WAN Status Indications +author: windows-driver-content +description: NDIS WAN Status Indications +ms.assetid: 7ee48d2d-0a6f-4d6e-8eda-5af19f7fa313 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NDIS WAN Status Indications + + +## + + +This section includes: + +[**NDIS\_STATUS\_WAN\_LINE\_UP**](ndis-status-wan-line-up.md) + +[**NDIS\_STATUS\_WAN\_LINE\_DOWN**](ndis-status-wan-line-down.md) + +[**NDIS\_STATUS\_WAN\_FRAGMENT**](ndis-status-wan-fragment.md) + +[**NDIS\_STATUS\_TAPI\_INDICATION**](ndis-status-tapi-indication.md) + +[**NDIS\_STATUS\_RING\_STATUS**](ndis-status-ring-status.md) + +[**NDIS\_STATUS\_WW\_INDICATION**](ndis-status-ww-indication.md) + +[**NDIS\_STATUS\_WAN\_CO\_FRAGMENT**](ndis-status-wan-co-fragment.md) + +[**NDIS\_STATUS\_WAN\_CO\_LINKPARAMS**](ndis-status-wan-co-linkparams.md) + +[**NDIS\_STATUS\_WAN\_CO\_MTULINKPARAMS**](ndis-status-wan-co-mtulinkparams.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NDIS%20WAN%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndisclearnblflag.md b/windows-driver-docs-pr/network/ndisclearnblflag.md new file mode 100644 index 0000000000..b2c27342be --- /dev/null +++ b/windows-driver-docs-pr/network/ndisclearnblflag.md @@ -0,0 +1,88 @@ +--- +title: NdisClearNblFlag macro +author: windows-driver-content +description: The NdisClearNblFlag macro clears a flag in a NET_BUFFER_LIST structure. +ms.assetid: a9f85e1c-b96e-4e2b-b0f6-ef2676ac2ef5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisClearNblFlag macro Network Drivers Starting with Windows Vista +--- + +# NdisClearNblFlag macro + + +The **NdisClearNblFlag** macro clears a flag in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisClearNblFlag( +   _NBL, +   _F +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_F* +The flag in the **NblFlags** member of the NET\_BUFFER\_LIST structure to clear. + +Return value +------------ + +None + +Remarks +------- + +NDIS drivers use the **NdisClearNblFlag** macro to clear the specified flag ( *\_F* ) in the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +For more information about the flags, see the **NblFlags** member on the NET\_BUFFER\_LIST topics. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisClearNblFlag%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndisgetmdlphysicalarraysize.md b/windows-driver-docs-pr/network/ndisgetmdlphysicalarraysize.md new file mode 100644 index 0000000000..cfff8729b5 --- /dev/null +++ b/windows-driver-docs-pr/network/ndisgetmdlphysicalarraysize.md @@ -0,0 +1,94 @@ +--- +title: NdisGetMdlPhysicalArraySize macro +author: windows-driver-content +description: The NdisGetMdlPhysicalArraySize macro retrieves the number of disconnected physical memory blocks that are associated with an MDL. +ms.assetid: 25e3f9a3-3057-4081-af74-427102197906 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisGetMdlPhysicalArraySize macro Network Drivers Starting with Windows Vista +--- + +# NdisGetMdlPhysicalArraySize macro + + +The **NdisGetMdlPhysicalArraySize** macro retrieves the number of disconnected physical memory blocks that are associated with an MDL. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisGetMdlPhysicalArraySize( +   _Mdl, +   _ArraySize +); +``` + +Parameters +---------- + +*\_Mdl* +A pointer to an MDL. + +*\_ArraySize* +A pointer to a caller-supplied variable in which this macro returns the number of disconnected physical memory blocks that are associated with the specified MDL. + +Return value +------------ + +None + +Remarks +------- + +The **NdisGetMdlPhysicalArraySize** macro provides an MDL-based version of the [**NdisGetBufferPhysicalArraySize**](https://msdn.microsoft.com/library/windows/hardware/ff552033) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

[Irql_NetBuffer_Function](https://msdn.microsoft.com/library/windows/hardware/ff547985)
+ +## See also + + +[**NdisGetBufferPhysicalArraySize**](https://msdn.microsoft.com/library/windows/hardware/ff552033) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisGetMdlPhysicalArraySize%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndisgetnextmdl.md b/windows-driver-docs-pr/network/ndisgetnextmdl.md new file mode 100644 index 0000000000..0a969f1e35 --- /dev/null +++ b/windows-driver-docs-pr/network/ndisgetnextmdl.md @@ -0,0 +1,90 @@ +--- +title: NdisGetNextMdl macro +author: windows-driver-content +description: The NdisGetNextMdl macro retrieves the next MDL in an MDL chain, given a pointer to the current MDL. +ms.assetid: 5b59ca7c-0998-4d53-9553-4946ef85327c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisGetNextMdl macro Network Drivers Starting with Windows Vista +--- + +# NdisGetNextMdl macro + + +The **NdisGetNextMdl** macro retrieves the next MDL in an MDL chain, given a pointer to the current MDL. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisGetNextMdl( +   _CurrentMdl, +   _NextMdl +); +``` + +Parameters +---------- + +*\_CurrentMdl* +A pointer to the specified current MDL. + +*\_NextMdl* +A pointer to a caller-supplied variable in which this macro returns a pointer to the next MDL in the MDL chain, if any, that follows the MDL at *\_CurrentMdl* . + +Return value +------------ + +None + +Remarks +------- + +The **NdisGetNextMdl** macro provides an MDL-based version of the [**NdisGetNextBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff552070) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

+ +## See also + + +[**NdisGetNextBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff552070) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisGetNextMdl%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndisquerymdl.md b/windows-driver-docs-pr/network/ndisquerymdl.md new file mode 100644 index 0000000000..187a06e6b3 --- /dev/null +++ b/windows-driver-docs-pr/network/ndisquerymdl.md @@ -0,0 +1,108 @@ +--- +title: NdisQueryMdl macro +author: windows-driver-content +description: The NdisQueryMdl macro retrieves the buffer length, and optionally the base virtual address, from an MDL. +ms.assetid: 0eccd784-c815-4094-87e5-a3e283abed73 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisQueryMdl macro Network Drivers Starting with Windows Vista +--- + +# NdisQueryMdl macro + + +The **NdisQueryMdl** macro retrieves the buffer length, and optionally the base virtual address, from an MDL. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisQueryMdl( +   _Mdl, +   _VirtualAddress, +   _Length, +   _Priority +); +``` + +Parameters +---------- + +*\_Mdl* +A pointer to an MDL. + +*\_VirtualAddress* +A pointer to a caller-supplied variable in which this macro returns the base virtual address of the virtual address range that is described by the MDL. The base virtual address can be **NULL** for either of the following reasons: + +- System resources are low or exhausted and the *\_Priority* parameter is set to **LowPagePriority** or **NormalPagePriority**. + +- System resources are exhausted and the *\_Priority* parameter is set to **HighPagePriority**. + +*\_Length* +A pointer to a caller-supplied variable in which this macro returns the length, in bytes, of the virtual address range that is described by the MDL. + +*\_Priority* +A page priority value. For a list of the possible values for this parameter, see the *Priority* parameter of the [**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) macro. + +Return value +------------ + +None + +Remarks +------- + +The **NdisQueryMdl** macro provides an MDL-based version of the [**NdisQueryBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff554407) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

[Irql_NetBuffer_Function](https://msdn.microsoft.com/library/windows/hardware/ff547985)
+ +## See also + + +[**MmGetSystemAddressForMdlSafe**](https://msdn.microsoft.com/library/windows/hardware/ff554559) + +[**NdisQueryBuffer**](https://msdn.microsoft.com/library/windows/hardware/ff554407) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisQueryMdl%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndisquerymdloffset.md b/windows-driver-docs-pr/network/ndisquerymdloffset.md new file mode 100644 index 0000000000..7e0bae04b2 --- /dev/null +++ b/windows-driver-docs-pr/network/ndisquerymdloffset.md @@ -0,0 +1,98 @@ +--- +title: NdisQueryMdlOffset macro +author: windows-driver-content +description: The NdisQueryMdlOffset macro retrieves the offset within a physical page at which a given MDL buffer begins and the length of the buffer. +ms.assetid: d6f23e9c-5015-4087-b7a2-badee00bdafa +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisQueryMdlOffset macro Network Drivers Starting with Windows Vista +--- + +# NdisQueryMdlOffset macro + + +The **NdisQueryMdlOffset** macro retrieves the offset within a physical page at which a given MDL buffer begins and the length of the buffer. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisQueryMdlOffset( +   _Mdl, +   _Offset, +   _Length +); +``` + +Parameters +---------- + +*\_Mdl* +A pointer to an MDL. + +*\_Offset* +A pointer to a caller-supplied variable in which this macro returns the zero-based byte offset within the physical page that contains the MDL-specified buffer. + +*\_Length* +A pointer to a caller-supplied variable in which this macro returns the length, in bytes, of the virtual address range that is specified by the MDL. + +Return value +------------ + +None + +Remarks +------- + +The **NdisQueryMdlOffset** macro provides an MDL-based version of the [**NdisQueryBufferOffset**](https://msdn.microsoft.com/library/windows/hardware/ff554411) function. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

[Irql_NetBuffer_Function](https://msdn.microsoft.com/library/windows/hardware/ff547985)
+ +## See also + + +[**NdisQueryBufferOffset**](https://msdn.microsoft.com/library/windows/hardware/ff554411) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisQueryMdlOffset%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndissetnblflag.md b/windows-driver-docs-pr/network/ndissetnblflag.md new file mode 100644 index 0000000000..143dd871f6 --- /dev/null +++ b/windows-driver-docs-pr/network/ndissetnblflag.md @@ -0,0 +1,88 @@ +--- +title: NdisSetNblFlag macro +author: windows-driver-content +description: The NdisSetNblFlag macro sets a flag in a NET_BUFFER_LIST structure. +ms.assetid: 0a92b689-fe82-4ac6-a674-5e249dd8e1f1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisSetNblFlag macro Network Drivers Starting with Windows Vista +--- + +# NdisSetNblFlag macro + + +The **NdisSetNblFlag** macro sets a flag in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisSetNblFlag( +   _NBL, +   _F +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_F* +The flag in the **NblFlags** member of the NET\_BUFFER\_LIST structure to set. + +Return value +------------ + +None + +Remarks +------- + +NDIS drivers use the **NdisSetNblFlag** macro to set the specified flag ( *\_F* ) in the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +For more information about the flags, see the **NblFlags** member on the NET\_BUFFER\_LIST topic. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisSetNblFlag%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndissetnetbufferlistprotocolid.md b/windows-driver-docs-pr/network/ndissetnetbufferlistprotocolid.md new file mode 100644 index 0000000000..2a19c103c1 --- /dev/null +++ b/windows-driver-docs-pr/network/ndissetnetbufferlistprotocolid.md @@ -0,0 +1,108 @@ +--- +title: NdisSetNetBufferListProtocolId macro +author: windows-driver-content +description: The NdisSetNetBufferListProtocolId macro sets the protocol identifier in the NetBufferListInfo member of a NET_BUFFER_LIST structure. +ms.assetid: e143c914-cfb0-4c06-9da7-a2f5ef09afe2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisSetNetBufferListProtocolId macro Network Drivers Starting with Windows Vista +--- + +# NdisSetNetBufferListProtocolId macro + + +The **NdisSetNetBufferListProtocolId** macro sets the protocol identifier in the **NetBufferListInfo** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NdisSetNetBufferListProtocolId( +   _NBL, +   _ProtocolId +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_ProtocolId* +A protocol identifier, as one of the following values: + +NDIS\_PROTOCOL\_ID\_DEFAULT +A default protocol driver identifier. + +NDIS\_PROTOCOL\_ID\_TCP\_IP +The TCP/IP protocol. + +NDIS\_PROTOCOL\_ID\_IPX +The IPX protocol. + +NDIS\_PROTOCOL\_ID\_NBF +The NetBEUI protocol. + +Return value +------------ + +None + +Remarks +------- + +Drivers that create [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structures should set the protocol identifier by calling the **NdisSetNetBufferListProtocolId** macro or by associating an identifier with a NET\_BUFFER\_LIST pool. + +To associate a protocol identifier with a NET\_BUFFER\_LIST pool, call the [**NdisAllocateNetBufferListPool**](https://msdn.microsoft.com/library/windows/hardware/ff561611) function and specify the protocol identifier in the **ProtocolId** member of the [**NET\_BUFFER\_LIST\_POOL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh205394) structure. + +Miniport, filter, and intermediate drivers set the protocol identifier to zero. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_POOL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh205394) + +[**NdisAllocateNetBufferListPool**](https://msdn.microsoft.com/library/windows/hardware/ff561611) + +[**NdisGetNetBufferListProtocolId**](https://msdn.microsoft.com/library/windows/hardware/ff562642) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisSetNetBufferListProtocolId%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndistestnblflag.md b/windows-driver-docs-pr/network/ndistestnblflag.md new file mode 100644 index 0000000000..50f46da654 --- /dev/null +++ b/windows-driver-docs-pr/network/ndistestnblflag.md @@ -0,0 +1,88 @@ +--- +title: NdisTestNblFlag macro +author: windows-driver-content +description: The NdisTestNblFlag macro retrieves the current setting of a flag in a NET_BUFFER_LIST structure. +ms.assetid: 098e5ab4-82af-423a-82ce-65be7e6d853c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisTestNblFlag macro Network Drivers Starting with Windows Vista +--- + +# NdisTestNblFlag macro + + +The **NdisTestNblFlag** macro retrieves the current setting of a flag in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +BOOLEAN NdisTestNblFlag( +   _NBL, +   _F +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_F* +The flag in the **NblFlags** member of the NET\_BUFFER\_LIST structure to retrieve the current setting for. + +Return value +------------ + +**NdisTestNblFlag** returns **TRUE** if the flag that is specified in the *\_F* parameter is set. Otherwise, this macro returns **FALSE**. + +Remarks +------- + +NDIS drivers use the **NdisTestNblFlag** macro to retrieve the setting of the specified flag ( *\_F* ) in the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +For more information about the flags, see the **NblFlags** member on the NET\_BUFFER\_LIST topic. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisTestNblFlag%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ndistestnblflags.md b/windows-driver-docs-pr/network/ndistestnblflags.md new file mode 100644 index 0000000000..bf6447219d --- /dev/null +++ b/windows-driver-docs-pr/network/ndistestnblflags.md @@ -0,0 +1,90 @@ +--- +title: NdisTestNblFlags macro +author: windows-driver-content +description: The NdisTestNblFlags macro tests the setting of a set of flags in a NET_BUFFER_LIST structure. +ms.assetid: adddae72-11ff-44f0-ac90-5792e0203b64 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NdisTestNblFlags macro Network Drivers Starting with Windows Vista +--- + +# NdisTestNblFlags macro + + +The **NdisTestNblFlags** macro tests the setting of a set of flags in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +BOOLEAN NdisTestNblFlags( +   _NBL, +   _F +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +*\_F* +The flags, combined with a bitwise OR operation, in the **NblFlags** member of the NET\_BUFFER\_LIST structure to test. + +Return value +------------ + +**NdisTestNblFlags** returns **TRUE** if all flags that are specified in the *\_F* parameter are set. Otherwise, this macro returns **FALSE**. + +Remarks +------- + +NDIS drivers use the **NdisTestNblFlags** macro to retrieve the state of the specified flags ( *\_F* ) in the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Use **NdisTestNblFlags** to determine whether a set of specified flags are all set. + +For more information about the flags, see the **NblFlags** member on the NET\_BUFFER\_LIST topic. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NdisTestNblFlags%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-architecture.md b/windows-driver-docs-pr/network/net-buffer-architecture.md index c22cdf5ff0..d288306c75 100644 --- a/windows-driver-docs-pr/network/net-buffer-architecture.md +++ b/windows-driver-docs-pr/network/net-buffer-architecture.md @@ -1,6 +1,6 @@ --- -title: NET\_BUFFER Architecture -description: NET\_BUFFER Architecture +title: NET_BUFFER Architecture +description: NET_BUFFER Architecture ms.assetid: 97cddcd1-7242-4cc5-9af9-fe82a2ef995f keywords: - NET_BUFFER diff --git a/windows-driver-docs-pr/network/net-buffer-checksum-bias.md b/windows-driver-docs-pr/network/net-buffer-checksum-bias.md new file mode 100644 index 0000000000..f7cd74a53d --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-checksum-bias.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_CHECKSUM_BIAS macro +author: windows-driver-content +description: NET_BUFFER_CHECKSUM_BIAS is a macro that NDIS drivers use to get the ChecksumBias member of a NET_BUFFER structure. +ms.assetid: 8fd4aafc-c095-4026-8c6b-8f739e429285 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_CHECKSUM_BIAS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_CHECKSUM\_BIAS macro + + +NET\_BUFFER\_CHECKSUM\_BIAS is a macro that NDIS drivers use to get the **ChecksumBias** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +USHORT NET_BUFFER_CHECKSUM_BIAS( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_CHECKSUM\_BIAS returns the value of the **ChecksumBias** member of the indicated NET\_BUFFER structure. + +Remarks +------- + +The return value specifies the number of bytes of data to skip over at the beginning of the data buffer when computing a checksum. This value is used by the TCP/IP protocol. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_CHECKSUM_BIAS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-current-mdl-offset.md b/windows-driver-docs-pr/network/net-buffer-current-mdl-offset.md new file mode 100644 index 0000000000..fe3389402b --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-current-mdl-offset.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_CURRENT_MDL_OFFSET macro +author: windows-driver-content +description: NET_BUFFER_CURRENT_MDL_OFFSET is a macro that NDIS drivers use to get the CurrentMdlOffset member of a NET_BUFFER structure. +ms.assetid: 49b14d42-584f-40de-8ba7-d0a74800886a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_CURRENT_MDL_OFFSET macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_CURRENT\_MDL\_OFFSET macro + + +NET\_BUFFER\_CURRENT\_MDL\_OFFSET is a macro that NDIS drivers use to get the **CurrentMdlOffset** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_CURRENT_MDL_OFFSET( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_CURRENT\_MDL\_OFFSET returns the value of the **CurrentMdlOffset** member of the indicated NET\_BUFFER structure. + +Remarks +------- + +The return value specifies the offset, in bytes, to the beginning of the used data space in the MDL that is specified by the **CurrentMdl** member of the NET\_BUFFER structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_CURRENT_MDL_OFFSET%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-current-mdl.md b/windows-driver-docs-pr/network/net-buffer-current-mdl.md new file mode 100644 index 0000000000..32cadcbd40 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-current-mdl.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_CURRENT_MDL macro +author: windows-driver-content +description: NET_BUFFER_CURRENT_MDL is a macro that NDIS drivers use to get the CurrentMdl member of a NET_BUFFER_DATA structure in a NET_BUFFER structure. +ms.assetid: c2fc283f-13b7-4c04-96c2-4bc1ea811a17 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_CURRENT_MDL macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_CURRENT\_MDL macro + + +NET\_BUFFER\_CURRENT\_MDL is a macro that NDIS drivers use to get the **CurrentMdl** member of a [**NET\_BUFFER\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff568381) structure in a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +PMDL NET_BUFFER_CURRENT_MDL( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_CURRENT\_MDL returns the value of the **CurrentMdl** member of the indicated NET\_BUFFER structure. + +Remarks +------- + +The return value is a pointer to the first MDL that the current driver is using. This pointer provides an optimization that improves performance by skipping over any MDLs that the current driver is not using. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff568381) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_CURRENT_MDL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-data-length.md b/windows-driver-docs-pr/network/net-buffer-data-length.md new file mode 100644 index 0000000000..c0b3596679 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-data-length.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_DATA_LENGTH macro +author: windows-driver-content +description: NET_BUFFER_DATA_LENGTH is a macro that NDIS drivers use to get the amount of used data space in a NET_BUFFER structure. +ms.assetid: 7fa9f67e-7b81-4bab-914b-cd02028fb21e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_DATA_LENGTH macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_DATA\_LENGTH macro + + +NET\_BUFFER\_DATA\_LENGTH is a macro that NDIS drivers use to get the amount of *used data space* in a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_DATA_LENGTH( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_DATA\_LENGTH returns the amount of *used data space* in a NET\_BUFFER structure. + +Remarks +------- + +NET\_BUFFER\_DATA\_LENGTH gets the return value from the **DataLength** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_DATA_LENGTH%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-data-offset.md b/windows-driver-docs-pr/network/net-buffer-data-offset.md new file mode 100644 index 0000000000..5c914f411e --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-data-offset.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_DATA_OFFSET macro +author: windows-driver-content +description: NET_BUFFER_DATA_OFFSET is a macro that NDIS drivers use to get the current offset from the beginning of the data space to the start of the used data space in a NET_BUFFER structure. +ms.assetid: 08c2238e-5583-4c09-b8ee-d40335a33c28 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_DATA_OFFSET macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_DATA\_OFFSET macro + + +NET\_BUFFER\_DATA\_OFFSET is a macro that NDIS drivers use to get the current offset from the beginning of the data space to the start of the *used data space* in a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_DATA_OFFSET( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_DATA\_OFFSET returns the offset, in bytes, from the beginning of the data space to the start of the *used data space* of the indicated NET\_BUFFER structure. This value also represents the size of the *unused data space* (available backfill). + +Remarks +------- + +NET\_BUFFER\_DATA\_OFFSET gets the return value from the **DataOffset** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_DATA_OFFSET%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-data-packaging.md b/windows-driver-docs-pr/network/net-buffer-data-packaging.md index 7d3378efb1..966e97b879 100644 --- a/windows-driver-docs-pr/network/net-buffer-data-packaging.md +++ b/windows-driver-docs-pr/network/net-buffer-data-packaging.md @@ -1,6 +1,6 @@ --- -title: NET\_BUFFER Data Packaging -description: NET\_BUFFER Data Packaging +title: NET_BUFFER Data Packaging +description: NET_BUFFER Data Packaging ms.assetid: f0d539ab-c6ed-4cd9-9891-ef4235016d50 keywords: - NDIS WDK , sending and receiving data diff --git a/windows-driver-docs-pr/network/net-buffer-data-physical-address.md b/windows-driver-docs-pr/network/net-buffer-data-physical-address.md new file mode 100644 index 0000000000..74a166a988 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-data-physical-address.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_DATA_PHYSICAL_ADDRESS macro +author: windows-driver-content +description: The NET_BUFFER_DATA_PHYSICAL_ADDRESS macro retrieves the DataPhysicalAddress member of a NET_BUFFER structure. +ms.assetid: da9971ec-38ce-4489-a11a-886aab9c6e6c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_DATA_PHYSICAL_ADDRESS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_DATA\_PHYSICAL\_ADDRESS macro + + +The NET\_BUFFER\_DATA\_PHYSICAL\_ADDRESS macro retrieves the **DataPhysicalAddress** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +NDIS_PHYSICAL_ADDRESS NET_BUFFER_DATA_PHYSICAL_ADDRESS( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_DATA\_PHYSICAL\_ADDRESS returns the **DataPhysicalAddress** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Remarks +------- + +NDIS network drivers should use the NET\_BUFFER\_DATA\_PHYSICAL\_ADDRESS macro to get the **DataPhysicalAddress** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.1 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_DATA_PHYSICAL_ADDRESS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-first-mdl.md b/windows-driver-docs-pr/network/net-buffer-first-mdl.md new file mode 100644 index 0000000000..6301fd3d46 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-first-mdl.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_FIRST_MDL macro +author: windows-driver-content +description: NET_BUFFER_FIRST_MDL is a macro that NDIS drivers use to get the first MDL in a NET_BUFFER structure. +ms.assetid: d62c7183-ef28-408a-b862-6a2d97026b35 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_FIRST_MDL macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_FIRST\_MDL macro + + +NET\_BUFFER\_FIRST\_MDL is a macro that NDIS drivers use to get the first MDL in a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +PMDL NET_BUFFER_FIRST_MDL( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_FIRST\_MDL returns a pointer to the first MDL in a linked list of MDLs that is associated with the indicated NET\_BUFFER structure. + +Remarks +------- + +NET\_BUFFER\_FIRST\_MDL gets the return value from the **MdlChain** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_FIRST_MDL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-coalesced-seg-count.md b/windows-driver-docs-pr/network/net-buffer-list-coalesced-seg-count.md new file mode 100644 index 0000000000..fe7042344f --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-coalesced-seg-count.md @@ -0,0 +1,86 @@ +--- +title: NET\_BUFFER\_LIST\_COALESCED\_SEG\_COUNT macro +author: windows-driver-content +description: The NET\_BUFFER\_LIST\_COALESCED\_SEG\_COUNT is a macro that NDIS drivers use to get and set the number of coalesced segments in a NET\_BUFFER\_LIST structure. +ms.assetid: CAF2D3C1-A91D-4FAF-8358-46064398C813 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NET_BUFFER_LIST_COALESCED_SEG_COUNT macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_COALESCED\_SEG\_COUNT macro + + +The **NET\_BUFFER\_LIST\_COALESCED\_SEG\_COUNT** is a macro that NDIS drivers use to get and set the number of coalesced segments in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_COALESCED_SEG_COUNT( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +**NET\_BUFFER\_LIST\_COALESCED\_SEG\_COUNT** returns the **CoalescedSegCount** member of the [**NDIS\_RSC\_NBL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451655) union that is associated with the **TcpRecvSegCoalesceInfo** identifier. The information is retrieved from the **NetBufferListInfo** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +This macro uses the [**NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff568401) macro to access the **TcpRecvSegCoalesceInfo** information. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RSC\_NBL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451655) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff568401) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_COALESCED_SEG_COUNT%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-context-data-size.md b/windows-driver-docs-pr/network/net-buffer-list-context-data-size.md new file mode 100644 index 0000000000..359d1807a5 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-context-data-size.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_LIST_CONTEXT_DATA_SIZE macro +author: windows-driver-content +description: NET_BUFFER_LIST_CONTEXT_DATA_SIZE is a macro that NDIS drivers use to get the size of the NET_BUFFER_LIST_CONTEXT data buffer that is associated with a NET_BUFFER_LIST structure. +ms.assetid: 28966e3d-db1d-4caf-b7e2-b79e97ed25cb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_CONTEXT_DATA_SIZE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_CONTEXT\_DATA\_SIZE macro + + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_SIZE is a macro that NDIS drivers use to get the size of the [**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) data buffer that is associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +USHORT NET_BUFFER_LIST_CONTEXT_DATA_SIZE( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_SIZE returns the size, in bytes, of the NET\_BUFFER\_LIST\_CONTEXT data buffer that is associated with the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_SIZE gets the return value from the **Size** member of the first [**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_CONTEXT_DATA_SIZE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-context-data-start.md b/windows-driver-docs-pr/network/net-buffer-list-context-data-start.md new file mode 100644 index 0000000000..b347b27250 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-context-data-start.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_LIST_CONTEXT_DATA_START macro +author: windows-driver-content +description: NET_BUFFER_LIST_CONTEXT_DATA_START is a macro that NDIS drivers use to get a pointer to the NET_BUFFER_LIST_CONTEXT context space that is associated with a NET_BUFFER_LIST structure. +ms.assetid: 165dc176-61fc-41d0-9342-803b45ad3bc1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_CONTEXT_DATA_START macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_CONTEXT\_DATA\_START macro + + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_START is a macro that NDIS drivers use to get a pointer to the [**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) context space that is associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_CONTEXT_DATA_START( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_START returns a pointer to the NET\_BUFFER\_LIST\_CONTEXT context space that is associated with the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +NET\_BUFFER\_LIST\_CONTEXT\_DATA\_START returns a pointer to the start of the used context space in the **ContextData** member of the [**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff568389) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_CONTEXT_DATA_START%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-context-structure.md b/windows-driver-docs-pr/network/net-buffer-list-context-structure.md index ffc5c477bd..7c888890db 100644 --- a/windows-driver-docs-pr/network/net-buffer-list-context-structure.md +++ b/windows-driver-docs-pr/network/net-buffer-list-context-structure.md @@ -1,6 +1,6 @@ --- -title: NET\_BUFFER\_LIST\_CONTEXT Structure -description: NET\_BUFFER\_LIST\_CONTEXT Structure +title: NET_BUFFER_LIST_CONTEXT Structure +description: NET_BUFFER_LIST_CONTEXT Structure ms.assetid: 45be8503-2c5f-46e6-9fc3-b1b3c42f0d91 keywords: - NET_BUFFER_LIST_CONTEXT diff --git a/windows-driver-docs-pr/network/net-buffer-list-dup-ack-count.md b/windows-driver-docs-pr/network/net-buffer-list-dup-ack-count.md new file mode 100644 index 0000000000..d48231c2c4 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-dup-ack-count.md @@ -0,0 +1,86 @@ +--- +title: NET\_BUFFER\_LIST\_DUP\_ACK\_COUNT macro +author: windows-driver-content +description: The NET\_BUFFER\_LIST\_DUP\_ACK\_COUNT is a macro that NDIS drivers use to get and set the number of coalesced segments in a NET\_BUFFER\_LIST structure. +ms.assetid: BA0E8B4B-F587-4919-8F81-1A690DF4D255 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -NET_BUFFER_LIST_DUP_ACK_COUNT macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_DUP\_ACK\_COUNT macro + + +The **NET\_BUFFER\_LIST\_DUP\_ACK\_COUNT** is a macro that NDIS drivers use to get and set the number of coalesced segments in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_DUP_ACK_COUNT( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +**NET\_BUFFER\_LIST\_DUP\_ACK\_COUNT** returns the **DupAckCount** member of the [**NDIS\_RSC\_NBL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451655) union that is associated with the **TcpRecvSegCoalesceInfo** identifier. The information is retrieved from the **NetBufferListInfo** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +This macro uses the [**NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff568401) macro to access the **TcpRecvSegCoalesceInfo** information. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RSC\_NBL\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451655) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff568401) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_DUP_ACK_COUNT%20macro%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-first-nb.md b/windows-driver-docs-pr/network/net-buffer-list-first-nb.md new file mode 100644 index 0000000000..37db2e08a8 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-first-nb.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_LIST_FIRST_NB macro +author: windows-driver-content +description: NET_BUFFER_LIST_FIRST_NB is a macro that NDIS drivers use to get the first NET_BUFFER structure in a NET_BUFFER_LIST structure. +ms.assetid: 695cb2ea-04aa-49e8-9910-01f8d85b7338 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_FIRST_NB macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_FIRST\_NB macro + + +NET\_BUFFER\_LIST\_FIRST\_NB is a macro that NDIS drivers use to get the first [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNET_BUFFER NET_BUFFER_LIST_FIRST_NB( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_FIRST\_NB returns a pointer to the first NET\_BUFFER structure in the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +NET\_BUFFER\_LIST\_FIRST\_NB gets the return value from the **FirstNetBuffer** member of the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_FIRST_NB%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-flags-macros.md b/windows-driver-docs-pr/network/net-buffer-list-flags-macros.md new file mode 100644 index 0000000000..9457996abe --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-flags-macros.md @@ -0,0 +1,37 @@ +--- +title: NET_BUFFER_LIST Flags Macros +author: windows-driver-content +description: NET_BUFFER_LIST Flags Macros +ms.assetid: c224f97f-bd9c-437e-86ec-223b8d85c49a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NET\_BUFFER\_LIST Flags Macros + + +## + + +This section includes the following topics: + +[**NdisTestNblFlag**](ndistestnblflag.md) + +[**NdisTestNblFlags**](ndistestnblflags.md) + +[**NdisSetNblFlag**](ndissetnblflag.md) + +[**NdisClearNblFlag**](ndisclearnblflag.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST%20Flags%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-flags.md b/windows-driver-docs-pr/network/net-buffer-list-flags.md new file mode 100644 index 0000000000..04a6fe5e64 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-flags.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_LIST_FLAGS macro +author: windows-driver-content +description: NET_BUFFER_LIST_FLAGS is a macro that NDIS drivers use to get the flags associated with a NET_BUFFER_LIST structure. +ms.assetid: 2ad9b515-4bce-463c-893f-047554e9cbd0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_FLAGS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_FLAGS macro + + +NET\_BUFFER\_LIST\_FLAGS is a macro that NDIS drivers use to get the flags associated with a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_LIST_FLAGS( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_FLAGS returns the **Flags** member of the indicated NDIS\_BUFFER\_LIST structure. + +Remarks +------- + +For definitions of the possible NET\_BUFFER\_LIST structure flags, see [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_FLAGS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-get-hash-function.md b/windows-driver-docs-pr/network/net-buffer-list-get-hash-function.md new file mode 100644 index 0000000000..d1fb2fadf9 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-get-hash-function.md @@ -0,0 +1,101 @@ +--- +title: NET_BUFFER_LIST_GET_HASH_FUNCTION macro +author: windows-driver-content +description: The NET_BUFFER_LIST_GET_HASH_FUNCTION macro gets the hash function information from a NET_BUFFER_LIST structure. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: bb80344c-8f82-4446-9f6f-8c2d4cabfd5a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_GET_HASH_FUNCTION macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_GET\_HASH\_FUNCTION macro + + +The NET\_BUFFER\_LIST\_GET\_HASH\_FUNCTION macro gets the hash function information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_LIST_GET_HASH_FUNCTION( +  PNET_BUFFER_LIST NetBufferList +); +``` + +Parameters +---------- + +*NetBufferList* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_GET\_HASH\_FUNCTION returns the hash function used. For more information, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +The hash function can be one of the following values: + +**NdisHashFunctionToeplitz** + +**NdisHashFunctionReserved1** + +**NdisHashFunctionReserved2** + +**NdisHashFunctionReserved3** + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hashing function to calculate an RSS hash value. + +For more information about the hashing functions, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_GET_HASH_FUNCTION%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-get-hash-type.md b/windows-driver-docs-pr/network/net-buffer-list-get-hash-type.md new file mode 100644 index 0000000000..3ffa469691 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-get-hash-type.md @@ -0,0 +1,102 @@ +--- +title: NET_BUFFER_LIST_GET_HASH_TYPE macro +author: windows-driver-content +description: The NET_BUFFER_LIST_GET_HASH_TYPE macro gets the hash type information from a NET_BUFFER_LIST structure. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 96a6e299-f3f4-456d-be5e-1c4e6ec98aa4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_GET_HASH_TYPE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_GET\_HASH\_TYPE macro + + +The NET\_BUFFER\_LIST\_GET\_HASH\_TYPE macro gets the hash type information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_LIST_GET_HASH_TYPE( +  PNET_BUFFER_LIST NetBufferList +); +``` + +Parameters +---------- + +*NetBufferList* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_GET\_HASH\_TYPE returns the hash type of the specified NET\_BUFFER\_LIST structure. + +The hash type is an OR value of valid combinations of the following flags: + +- NDIS\_HASH\_IPV4 +- NDIS\_HASH\_TCP\_IPV4 +- NDIS\_HASH\_IPV6 +- NDIS\_HASH\_TCP\_IPV6 +- NDIS\_HASH\_IPV6\_EX +- NDIS\_HASH\_TCP\_IPV6\_EX + +For more information about hash types and the valid combinations of these flags, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hash type to identify the portion of received network data that is used to calculate an RSS hash value. + +For more information about the hash type, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_GET_HASH_TYPE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-get-hash-value.md b/windows-driver-docs-pr/network/net-buffer-list-get-hash-value.md new file mode 100644 index 0000000000..cfcde0bd65 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-get-hash-value.md @@ -0,0 +1,89 @@ +--- +title: NET_BUFFER_LIST_GET_HASH_VALUE macro +author: windows-driver-content +description: The NET_BUFFER_LIST_GET_HASH_VALUE macro gets the hash value information from a NET_BUFFER_LIST structure. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 7e3794e4-1afe-416f-b8f8-689f6397fc6a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_GET_HASH_VALUE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_GET\_HASH\_VALUE macro + + +The NET\_BUFFER\_LIST\_GET\_HASH\_VALUE macro gets the hash value information from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_LIST_GET_HASH_VALUE( +  PNET_BUFFER_LIST NetBufferList +); +``` + +Parameters +---------- + +*NetBufferList* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_GET\_HASH\_VALUE returns the hash value formatted as a ULONG. + +## + + +Remarks +------- + +For more information about the hash value, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_GET_HASH_VALUE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-info.md b/windows-driver-docs-pr/network/net-buffer-list-info.md new file mode 100644 index 0000000000..fcb13373b6 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-info.md @@ -0,0 +1,102 @@ +--- +title: NET_BUFFER_LIST_INFO macro +author: windows-driver-content +description: NET_BUFFER_LIST_INFO is a macro that NDIS drivers use to get and set information that applies to all the NET_BUFFER structures in a NET_BUFFER_LIST structure. +ms.assetid: 3ee2e7b5-1592-4913-a39d-44b815398c76 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_INFO macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_INFO macro + + +NET\_BUFFER\_LIST\_INFO is a macro that NDIS drivers use to get and set information that applies to all the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structures in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_INFO( +  PNET_BUFFER_LIST _NBL, +  ULONG            _Id +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +*\_Id* +An ID that indicates the type of information to access from the **NetBufferListInfo** member of the NET\_BUFFER\_LIST structure that the *\_NBL* parameter specifies. + +Return value +------------ + +NET\_BUFFER\_LIST\_INFO returns the information that is associated with the specified ID. The information is retrieved from the **NetBufferListInfo** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +For a list of the valid **NetBufferListInfo** IDs, see the [**NDIS\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566569) reference page. + +The following example demonstrates getting a **NetBufferListInfo** value: + +``` + value = NET_BUFFER_LIST_INFO(pNbl, Id); +``` + +The following example demonstrates setting a **NetBufferListInfo** value: + +``` + NET_BUFFER_LIST_INFO(pNbl, Id) = value; +``` + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566569) + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_INFO%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-miniport-reserved.md b/windows-driver-docs-pr/network/net-buffer-list-miniport-reserved.md new file mode 100644 index 0000000000..0f3a9afa7d --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-miniport-reserved.md @@ -0,0 +1,86 @@ +--- +title: NET_BUFFER_LIST_MINIPORT_RESERVED macro +author: windows-driver-content +description: NET_BUFFER_LIST_MINIPORT_RESERVED is a macro that NDIS drivers use to access the MiniportReserved member of a NET_BUFFER_LIST structure. +ms.assetid: 1f790c34-e235-4e19-9dd9-62f54703206c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_MINIPORT_RESERVED macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_MINIPORT\_RESERVED macro + + +NET\_BUFFER\_LIST\_MINIPORT\_RESERVED is a macro that NDIS drivers use to access the **MiniportReserved** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_MINIPORT_RESERVED( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_MINIPORT\_RESERVED returns a pointer to the start of the **MiniportReserved** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +Miniport drivers and NDIS intermediate drivers can use **MiniportReserved** for their own purposes. + +**Note**  Only one driver can use **MiniportReserved** . Therefore, if another driver has used **MiniportReserved**, an intermediate driver cannot use it. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_MINIPORT_RESERVED%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-nbl-flags.md b/windows-driver-docs-pr/network/net-buffer-list-nbl-flags.md new file mode 100644 index 0000000000..5081f86353 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-nbl-flags.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_LIST_NBL_FLAGS macro +author: windows-driver-content +description: The NET_BUFFER_LIST_NBL_FLAGS macro retrieves the NblFlags member of a NET_BUFFER_LIST structure. +ms.assetid: 3ae4336d-4b62-476e-9b20-bf41fc308dc4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_NBL_FLAGS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_NBL\_FLAGS macro + + +The NET\_BUFFER\_LIST\_NBL\_FLAGS macro retrieves the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +VOID NET_BUFFER_LIST_NBL_FLAGS( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +None + +Remarks +------- + +NDIS network drivers should use the NET\_BUFFER\_LIST\_NBL\_FLAGS macro to get the **NblFlags** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.1 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_NBL_FLAGS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-next-nbl.md b/windows-driver-docs-pr/network/net-buffer-list-next-nbl.md new file mode 100644 index 0000000000..756cc44de0 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-next-nbl.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_LIST_NEXT_NBL macro +author: windows-driver-content +description: NET_BUFFER_LIST_NEXT_NBL is a macro that NDIS drivers use to get the next NET_BUFFER_LIST structure in a linked list of NET_BUFFER_LIST structures. +ms.assetid: 5f0fc110-5e17-4030-b25b-e00d25b60b14 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_NEXT_NBL macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_NEXT\_NBL macro + + +NET\_BUFFER\_LIST\_NEXT\_NBL is a macro that NDIS drivers use to get the next [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure in a linked list of NET\_BUFFER\_LIST structures. + +Syntax +------ + +```ManagedCPlusPlus +PNET_BUFFER_LIST NET_BUFFER_LIST_NEXT_NBL( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_NEXT\_NBL returns a pointer to the next NET\_BUFFER\_LIST structure in the linked list of NET\_BUFFER\_LIST structures, or it returns **NULL** if the end of the linked list is reached. + +Remarks +------- + +NET\_BUFFER\_LIST\_NEXT\_NBL gets the return value from the **Next** member of the [**NET\_BUFFER\_LIST\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff568393) structure in the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure that the *\_NBL* parameter points to. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_DATA**](https://msdn.microsoft.com/library/windows/hardware/ff568393) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_NEXT_NBL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-protocol-reserved.md b/windows-driver-docs-pr/network/net-buffer-list-protocol-reserved.md new file mode 100644 index 0000000000..56d6c9055e --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-protocol-reserved.md @@ -0,0 +1,86 @@ +--- +title: NET_BUFFER_LIST_PROTOCOL_RESERVED macro +author: windows-driver-content +description: NET_BUFFER_LIST_PROTOCOL_RESERVED is a macro that NDIS drivers use to access the ProtocolReserved member of a NET_BUFFER_LIST structure. +ms.assetid: f14d2948-59f8-4249-aca1-dc207a5ba596 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_PROTOCOL_RESERVED macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_PROTOCOL\_RESERVED macro + + +NET\_BUFFER\_LIST\_PROTOCOL\_RESERVED is a macro that NDIS drivers use to access the **ProtocolReserved** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_LIST_PROTOCOL_RESERVED( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_PROTOCOL\_RESERVED returns a pointer to the start of the **ProtocolReserved** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +Protocol drivers and NDIS intermediate drivers can use **ProtocolReserved** for their own purposes. + +**Note**  Only one driver can use **ProtocolReserved** . Therefore, if another driver has used **ProtocolReserved**, an intermediate driver cannot use it. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_PROTOCOL_RESERVED%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-receive-filter-id.md b/windows-driver-docs-pr/network/net-buffer-list-receive-filter-id.md new file mode 100644 index 0000000000..07667e8049 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-receive-filter-id.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_LIST_RECEIVE_FILTER_ID macro +author: windows-driver-content +description: The NET_BUFFER_LIST_RECEIVE_FILTER_ID macro gets a receive filter identifier from the out-of-band (OOB) data in a NET_BUFFER_LIST structure. +ms.assetid: 70ae6dc6-ae4d-4bef-adda-924b39547fa7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_RECEIVE_FILTER_ID macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID macro + + +The NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID macro gets a receive filter identifier from the out-of-band (OOB) data in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +USHORT NET_BUFFER_LIST_RECEIVE_FILTER_ID( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID returns a USHORT value for a receive filter identifier. + +Remarks +------- + +Any NDIS 6.20 or later driver can use NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID to get the receive filter identifier from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID gets the receive filter identifier from the **FilterId** member of the [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_RECEIVE_FILTER_ID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-receive-filter-vport-id.md b/windows-driver-docs-pr/network/net-buffer-list-receive-filter-vport-id.md new file mode 100644 index 0000000000..5db066df57 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-receive-filter-vport-id.md @@ -0,0 +1,85 @@ +--- +title: NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID macro +author: windows-driver-content +description: The NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID macro sets or gets the identifier of a virtual port (VPort) within the out-of-band (OOB) data in a NET_BUFFER_LIST structure. +ms.assetid: 809FE51C-8679-49D5-9E4A-5820747DBE97 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_VPORT\_ID macro + + +The **NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_VPORT\_ID** macro sets or gets the identifier of a virtual port (VPort) within the out-of-band (OOB) data in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +USHORT NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +**NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_VPORT\_ID** returns a USHORT value for a VPort identifier. + +Remarks +------- + +Miniport drivers that support the single root I/O virtualization (SR-IOV) interface can use the **NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_VPORT\_ID** macro to set or get the VPort identifier in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. The **NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_VPORT\_ID** macro accesses the VPort identifier from the **VPortId** member of the [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_RECEIVE_FILTER_VPORT_ID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-receive-queue-id.md b/windows-driver-docs-pr/network/net-buffer-list-receive-queue-id.md new file mode 100644 index 0000000000..3e85b50cf0 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-receive-queue-id.md @@ -0,0 +1,90 @@ +--- +title: NET_BUFFER_LIST_RECEIVE_QUEUE_ID macro +author: windows-driver-content +description: The NET_BUFFER_LIST_RECEIVE_QUEUE_ID macro sets or gets the identifier of a virtual machine queue (VMQ) or single root I/O virtualization (SR-IOV) receive queue identifier within the out-of-band (OOB) data of a NET_BUFFER_LIST structure. +ms.assetid: d205bb23-2e25-4643-baa9-19856de37eb1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_RECEIVE_QUEUE_ID macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID macro + + +The **NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID** macro sets or gets the identifier of a virtual machine queue (VMQ) or single root I/O virtualization (SR-IOV) receive queue identifier within the out-of-band (OOB) data of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +For the SR-IOV interface, the receive queue is created on a default or nondefault virtual port (VPort). Starting with Windows Server 2012, only the default receive queue of a VPort is supported. + +Syntax +------ + +```ManagedCPlusPlus +USHORT NET_BUFFER_LIST_RECEIVE_QUEUE_ID( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +**NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID** returns a **USHORT** value for a receive queue identifier. + +Remarks +------- + +Any NDIS 6.20 or later driver can use **NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID** to set or get the receive queue identifier from a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. **NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID** accesses the receive queue identifier from the **QueueId** member of the [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) structure. + +**Note**  When a VMQ is deleted (for example, during VM live migration), it is possible for the miniport driver to receive an NBL that contains an invalid **QueueId** value. If this happens, the miniport should ignore the invalid queue ID and use 0 (the default queue) instead. The **QueueId** is found in the **NetBufferListFilteringInfo** portion of the NBL's OOB data, and is retrieved by using the **NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID** macro. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_RECEIVE_QUEUE_ID%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-set-hash-function.md b/windows-driver-docs-pr/network/net-buffer-list-set-hash-function.md new file mode 100644 index 0000000000..8de9b9d7d2 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-set-hash-function.md @@ -0,0 +1,105 @@ +--- +title: NET_BUFFER_LIST_SET_HASH_FUNCTION macro +author: windows-driver-content +description: The NET_BUFFER_LIST_SET_HASH_FUNCTION macro sets the hash function information in a NET_BUFFER_LIST structure. Version InformationWindows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 01257316-b037-4e7a-8084-d2cc8ad2a55a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_SET_HASH_FUNCTION macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_SET\_HASH\_FUNCTION macro + + +The NET\_BUFFER\_LIST\_SET\_HASH\_FUNCTION macro sets the hash function information in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +VOID NET_BUFFER_LIST_SET_HASH_FUNCTION( + [in] PNET_BUFFER_LIST          NetBufferList, + [in] ULONG            volatile HashFunctionUsed +); +``` + +Parameters +---------- + +*NetBufferList* \[in\] +A pointer to a NET\_BUFFER\_LIST structure. + +*HashFunctionUsed* \[in\] +The hash function that is used. For more information, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +The hash function can be one of the following: + +**NdisHashFunctionToeplitz** + +**NdisHashFunctionReserved1** + +**NdisHashFunctionReserved2** + +**NdisHashFunctionReserved3** + +Return value +------------ + +None + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hashing function to calculate an RSS hash value. + +For more information about the hashing functions, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_SET_HASH_FUNCTION%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-set-hash-type.md b/windows-driver-docs-pr/network/net-buffer-list-set-hash-type.md new file mode 100644 index 0000000000..b84e6f2011 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-set-hash-type.md @@ -0,0 +1,111 @@ +--- +title: NET_BUFFER_LIST_SET_HASH_TYPE macro +author: windows-driver-content +description: The NET_BUFFER_LIST_SET_HASH_TYPE macro sets the hash type information in a NET_BUFFER_LIST structure. Version Information Windows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: 46bd8e4b-3c52-4708-ac13-05f54ac28869 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_SET_HASH_TYPE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_SET\_HASH\_TYPE macro + + +The NET\_BUFFER\_LIST\_SET\_HASH\_TYPE macro sets the hash type information in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +VOID NET_BUFFER_LIST_SET_HASH_TYPE( + [in] PNET_BUFFER_LIST          NetBufferList, + [in] ULONG            volatile HashType +); +``` + +Parameters +---------- + +*NetBufferList* \[in\] +A pointer to a NET\_BUFFER\_LIST structure. + +*HashType* \[in\] +The hash type. + +The hash type is an OR value of valid combinations of the following flags: + +NDIS\_HASH\_IPV4 + +NDIS\_HASH\_TCP\_IPV4 + +NDIS\_HASH\_IPV6 + +NDIS\_HASH\_TCP\_IPV6 + +NDIS\_HASH\_IPV6\_EX + +NDIS\_HASH\_TCP\_IPV6\_EX + +For more information about hash types and the valid combinations of these flags, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +Return value +------------ + +None + +## + + +Remarks +------- + +A NIC (or its miniport driver) uses the receive side scaling (RSS) hash type to identify the portion of received network data that is used to calculate an RSS hash value. + +For more information about the hash type, see [RSS Hashing Types](https://msdn.microsoft.com/library/windows/hardware/ff570726). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_SET_HASH_TYPE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-set-hash-value.md b/windows-driver-docs-pr/network/net-buffer-list-set-hash-value.md new file mode 100644 index 0000000000..7c5cfff51b --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-set-hash-value.md @@ -0,0 +1,93 @@ +--- +title: NET_BUFFER_LIST_SET_HASH_VALUE macro +author: windows-driver-content +description: The NET_BUFFER_LIST_SET_HASH_VALUE macro sets the hash value information in a NET_BUFFER_LIST structure. Version InformationWindows VistaSupported. NDIS 6.0 driversSupported. +ms.assetid: cca681ab-7867-40e3-beab-ad001fb0dd39 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_SET_HASH_VALUE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_SET\_HASH\_VALUE macro + + +The NET\_BUFFER\_LIST\_SET\_HASH\_VALUE macro sets the hash value information in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 drivers +Supported. + +Syntax +------ + +```ManagedCPlusPlus +VOID NET_BUFFER_LIST_SET_HASH_VALUE( +  PNET_BUFFER_LIST NetBufferList, +  ULONG            HashValue +); +``` + +Parameters +---------- + +*NetBufferList* +A pointer to a NET\_BUFFER\_LIST structure. + +*HashValue* +The hash value, which is formatted as a ULONG. + +Return value +------------ + +None + +## + + +Remarks +------- + +For more information about the hash value, see [RSS Hashing Functions](https://msdn.microsoft.com/library/windows/hardware/ff570725). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_SET_HASH_VALUE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-status.md b/windows-driver-docs-pr/network/net-buffer-list-status.md new file mode 100644 index 0000000000..52f9fad488 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-status.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_LIST_STATUS macro +author: windows-driver-content +description: NET_BUFFER_LIST_STATUS is a macro that NDIS drivers use to access the StatusCode member of a NET_BUFFER_LIST structure. +ms.assetid: 0101c6f1-4690-4d53-a28d-d13995dc2691 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_STATUS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_STATUS macro + + +NET\_BUFFER\_LIST\_STATUS is a macro that NDIS drivers use to access the **StatusCode** member of a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +NDIS_STATUS NET_BUFFER_LIST_STATUS( +  PNET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a NET\_BUFFER\_LIST structure. + +Return value +------------ + +NET\_BUFFER\_LIST\_STATUS returns the value of the **StatusCode** member of the indicated NET\_BUFFER\_LIST structure. + +Remarks +------- + +Miniport drivers and NDIS intermediate drivers can use **StatusCode** for their own purposes. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_STATUS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-structure-macros.md b/windows-driver-docs-pr/network/net-buffer-list-structure-macros.md new file mode 100644 index 0000000000..932e83df4c --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-structure-macros.md @@ -0,0 +1,117 @@ +--- +title: NET_BUFFER_LIST Structure Macros +author: windows-driver-content +description: NET_BUFFER_LIST Structure Macros +ms.assetid: b3979a02-2367-468f-af25-9ece28e14ccb +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NET\_BUFFER\_LIST Structure Macros + + +## + + +This section includes: + +## In this section + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicDescription

[NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO](ndis-nbl-add-media-specific-info.md)

The [NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO](ndis-nbl-add-media-specific-info.md) macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-add-media-specific-info-ex.md)

The NDIS_NBL_ADD_MEDIA_SPECIFIC_INFO_EX macro adds a media-specific information data structure to the beginning of a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NDIS_NBL_GET_MEDIA_SPECIFIC_INFO](ndis-nbl-get-media-specific-info.md)

The NDIS_NBL_GET_MEDIA_SPECIFIC_INFO macro gets a media-specific information data structure from a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-get-media-specific-info-ex.md)

The [NDIS_NBL_GET_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-get-media-specific-info-ex.md) macro gets a media-specific information data structure from a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO](ndis-nbl-remove-media-specific-info.md)

The NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO macro removes a media-specific information data structure from a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-remove-media-specific-info-ex.md)

The [NDIS_NBL_REMOVE_MEDIA_SPECIFIC_INFO_EX](ndis-nbl-remove-media-specific-info-ex.md) macro removes a media-specific information data structure from a linked list of such structures that are associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NdisSetNetBufferListProtocolId](ndissetnetbufferlistprotocolid.md)

The NdisSetNetBufferListProtocolId macro sets the protocol identifier in the NetBufferListInfo member of a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_CONTEXT_DATA_SIZE](net-buffer-list-context-data-size.md)

NET_BUFFER_LIST_CONTEXT_DATA_SIZE is a macro that NDIS drivers use to get the size of the [NET_BUFFER_LIST_CONTEXT](https://msdn.microsoft.com/library/windows/hardware/ff568389) data buffer that is associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_CONTEXT_DATA_START](net-buffer-list-context-data-start.md)

NET_BUFFER_LIST_CONTEXT_DATA_START is a macro that NDIS drivers use to get a pointer to the [NET_BUFFER_LIST_CONTEXT](https://msdn.microsoft.com/library/windows/hardware/ff568389) context space that is associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_FIRST_NB](net-buffer-list-first-nb.md)

NET_BUFFER_LIST_FIRST_NB is a macro that NDIS drivers use to get the first [NET_BUFFER](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure in a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_FLAGS](net-buffer-list-flags.md)

NET_BUFFER_LIST_FLAGS is a macro that NDIS drivers use to get the flags associated with a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_MINIPORT_RESERVED](net-buffer-list-miniport-reserved.md)

NET_BUFFER_LIST_MINIPORT_RESERVED is a macro that NDIS drivers use to access the MiniportReserved member of a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_NEXT_NBL](net-buffer-list-next-nbl.md)

NET_BUFFER_LIST_NEXT_NBL is a macro that NDIS drivers use to get the next [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure in a linked list of NET_BUFFER_LIST structures.

[NET_BUFFER_LIST_INFO](net-buffer-list-info.md)

NET_BUFFER_LIST_INFO is a macro that NDIS drivers use to get and set information that applies to all the [NET_BUFFER](https://msdn.microsoft.com/library/windows/hardware/ff568376) structures in a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_STATUS](net-buffer-list-status.md)

NET_BUFFER_LIST_STATUS is a macro that NDIS drivers use to access the StatusCode member of a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_PROTOCOL_RESERVED](net-buffer-list-protocol-reserved.md)

NET_BUFFER_LIST_PROTOCOL_RESERVED is a macro that NDIS drivers use to access the ProtocolReserved member of a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

[NET_BUFFER_LIST_RECEIVE_FILTER_ID](net-buffer-list-receive-filter-id.md)

The NET_BUFFER_LIST_RECEIVE_FILTER_ID macro gets a receive filter identifier from the out-of-band (OOB) data in a [NET_BUFFER_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure.

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST%20Structure%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-list-structure.md b/windows-driver-docs-pr/network/net-buffer-list-structure.md index 90790da71e..4016d8eab5 100644 --- a/windows-driver-docs-pr/network/net-buffer-list-structure.md +++ b/windows-driver-docs-pr/network/net-buffer-list-structure.md @@ -1,6 +1,6 @@ --- -title: NET\_BUFFER\_LIST Structure -description: NET\_BUFFER\_LIST Structure +title: NET_BUFFER_LIST Structure +description: NET_BUFFER_LIST Structure ms.assetid: f7f19e48-cb63-458d-b175-6f99080e4cdf keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/net-buffer-list-switch-forwarding-detail.md b/windows-driver-docs-pr/network/net-buffer-list-switch-forwarding-detail.md new file mode 100644 index 0000000000..fe7b027895 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-list-switch-forwarding-detail.md @@ -0,0 +1,103 @@ +--- +title: NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL macro +author: windows-driver-content +description: Hyper-V extensible switch extensions use the NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL macro to access the NDIS_SWITCH_FORWARDING_DETAIL_NET_BUFFER_LIST_INFO union in the extensible switch context area in a NET_BUFFER_LIST structure. +ms.assetid: 8E6BE3AA-C4FD-40D8-AF13-5C7D0E7B8080 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_LIST\_SWITCH\_FORWARDING\_DETAIL macro + + +Hyper-V extensible switch extensions use the **NET\_BUFFER\_LIST\_SWITCH\_FORWARDING\_DETAIL** macro to access the [**NDIS\_SWITCH\_FORWARDING\_DETAIL\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598211) union in the extensible switch context area in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNDIS_SWITCH_FORWARDING_DETAIL_NET_BUFFER_LIST_INFO NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL( +  NET_BUFFER_LIST _NBL +); +``` + +Parameters +---------- + +*\_NBL* +A pointer to a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +Return value +------------ + +The **NET\_BUFFER\_LIST\_SWITCH\_FORWARDING\_DETAIL** macro returns a pointer to the [**NDIS\_SWITCH\_FORWARDING\_DETAIL\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598211) union within the specified [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. + +**Note**  **NET\_BUFFER\_LIST\_SWITCH\_FORWARDING\_DETAIL** returns **NULL** if the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure does not contain an [**NDIS\_SWITCH\_FORWARDING\_DETAIL\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598211) structure. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

Desktop

Version

Supported in NDIS 6.30 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[Adding Extensible Switch Destination Port Data to a Packet](https://msdn.microsoft.com/library/windows/hardware/hh582253) + +[Cloning Packet Traffic](https://msdn.microsoft.com/library/windows/hardware/hh582254) + +[Excluding Packet Delivery to Extensible Switch Destination Ports](https://msdn.microsoft.com/library/windows/hardware/hh582255) + +[Forwarding Extensions](https://msdn.microsoft.com/library/windows/hardware/hh598148) + +[Forwarding Packets to Hyper-V Extensible Switch Ports](https://msdn.microsoft.com/library/windows/hardware/hh598152) + +[Forwarding Packets to Physical Network Adapters](https://msdn.microsoft.com/library/windows/hardware/hh582257) + +[Modifying a Packet's Extensible Switch Source Port Data](https://msdn.microsoft.com/library/windows/hardware/hh582266) + +[Overview of the Hyper-V Extensible Switch](https://msdn.microsoft.com/library/windows/hardware/hh582268) + +[Packet Management Guidelines for the Extensible Switch Data Path](https://msdn.microsoft.com/library/windows/hardware/hh582270) + +[Querying a Packet's Extensible Switch Source Port Data](https://msdn.microsoft.com/library/windows/hardware/hh582272) + +[**NDIS\_SWITCH\_FORWARDING\_DETAIL\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598211) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_LIST_SWITCH_FORWARDING_DETAIL%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-miniport-reserved.md b/windows-driver-docs-pr/network/net-buffer-miniport-reserved.md new file mode 100644 index 0000000000..3b645fa926 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-miniport-reserved.md @@ -0,0 +1,86 @@ +--- +title: NET_BUFFER_MINIPORT_RESERVED macro +author: windows-driver-content +description: NET_BUFFER_MINIPORT_RESERVED is a macro that NDIS drivers use to access the MiniportReserved member of a NET_BUFFER structure. +ms.assetid: 609b2d69-61bd-458b-865b-29c8305dd841 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_MINIPORT_RESERVED macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_MINIPORT\_RESERVED macro + + +NET\_BUFFER\_MINIPORT\_RESERVED is a macro that NDIS drivers use to access the **MiniportReserved** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_MINIPORT_RESERVED( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_MINIPORT\_RESERVED returns a pointer to the start of the **MiniportReserved** member of the specified NET\_BUFFER structure. + +Remarks +------- + +Miniport drivers and NDIS intermediate drivers can use **MiniportReserved** for their own purposes. Miniport drivers typically use **MiniportReserved** to maintain [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure context information for outstanding transfers. + +**Note**  Only one driver can use **MiniportReserved** . Therefore, if another driver has used **MiniportReserved**, an intermediate driver cannot use it. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_MINIPORT_RESERVED%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-next-nb.md b/windows-driver-docs-pr/network/net-buffer-next-nb.md new file mode 100644 index 0000000000..bc3ce866dc --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-next-nb.md @@ -0,0 +1,82 @@ +--- +title: NET_BUFFER_NEXT_NB macro +author: windows-driver-content +description: NET_BUFFER_NEXT_NB is a macro that NDIS drivers use to get a pointer to the next NET_BUFFER structure in a linked list of NET_BUFFER structures. +ms.assetid: 2c9bf3eb-4aa9-4983-91a8-c78f100b2d5f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_NEXT_NB macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_NEXT\_NB macro + + +NET\_BUFFER\_NEXT\_NB is a macro that NDIS drivers use to get a pointer to the next [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure in a linked list of NET\_BUFFER structures. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_NEXT_NB( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_NEXT\_NB returns a pointer to the next NET\_BUFFER structure in the linked list of NET\_BUFFER structures, or it returns **NULL** if the end of the linked list is reached. + +Remarks +------- + +NET\_BUFFER\_NEXT\_NB gets the return value from the **Next** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_NEXT_NB%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-protocol-reserved.md b/windows-driver-docs-pr/network/net-buffer-protocol-reserved.md new file mode 100644 index 0000000000..e9f433a3d2 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-protocol-reserved.md @@ -0,0 +1,86 @@ +--- +title: NET_BUFFER_PROTOCOL_RESERVED macro +author: windows-driver-content +description: NET_BUFFER_PROTOCOL_RESERVED is a macro that NDIS drivers use to get the ProtocolReserved member of a NET_BUFFER structure. +ms.assetid: ab46cce0-c77f-4e08-9522-6a6674d557e8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_PROTOCOL_RESERVED macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_PROTOCOL\_RESERVED macro + + +NET\_BUFFER\_PROTOCOL\_RESERVED is a macro that NDIS drivers use to get the **ProtocolReserved** member of a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. + +Syntax +------ + +```ManagedCPlusPlus +PVOID NET_BUFFER_PROTOCOL_RESERVED( +  PNET_BUFFER _NB +); +``` + +Parameters +---------- + +*\_NB* +A pointer to a NET\_BUFFER structure. + +Return value +------------ + +NET\_BUFFER\_PROTOCOL\_RESERVED returns the value of the **ProtocolReserved** member of the specified NET\_BUFFER structure. + +Remarks +------- + +Protocol drivers and NDIS intermediate drivers can use this area for their own purposes. Protocol drivers typically use **ProtocolReserved** to maintain [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure context information for outstanding transfers. + +**Note**  Only one driver can use **ProtocolReserved** . Therefore, if an another driver has used **ProtocolReserved**, an intermediate driver cannot use it. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_PROTOCOL_RESERVED%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-shared-mem-flags.md b/windows-driver-docs-pr/network/net-buffer-shared-mem-flags.md new file mode 100644 index 0000000000..26cf477f11 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-shared-mem-flags.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_SHARED_MEM_FLAGS macro +author: windows-driver-content +description: The NET_BUFFER_SHARED_MEM_FLAGS macro gets the shared memory flags from a NET_BUFFER_SHARED_MEMORY structure. +ms.assetid: b9018846-d085-48bc-991b-4f6986cd820c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_SHARED_MEM_FLAGS macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_SHARED\_MEM\_FLAGS macro + + +The **NET\_BUFFER\_SHARED\_MEM\_FLAGS** macro gets the shared memory flags from a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_SHARED_MEM_FLAGS( +  PNET_BUFFER_SHARED_MEMORY _SHI +); +``` + +Parameters +---------- + +*\_SHI* +A pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Return value +------------ + +**NET\_BUFFER\_SHARED\_MEM\_FLAGS** returns a ULONG that contains shared memory flags. + +Remarks +------- + +An NDIS 6.20 or later driver can use the **NET\_BUFFER\_SHARED\_MEM\_FLAGS** macro to get shared memory flags that are associated with a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. **NET\_BUFFER\_SHARED\_MEM\_FLAGS** gets the flags from the **SharedMemoryFlags** member of the **NET\_BUFFER\_SHARED\_MEMORY** structure. The **SharedMemoryInfo** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure contains the first **NET\_BUFFER\_SHARED\_MEMORY** structure in a linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_SHARED_MEM_FLAGS%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-shared-mem-handle.md b/windows-driver-docs-pr/network/net-buffer-shared-mem-handle.md new file mode 100644 index 0000000000..5283572ab2 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-shared-mem-handle.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_SHARED_MEM_HANDLE macro +author: windows-driver-content +description: The NET_BUFFER_SHARED_MEM_HANDLE macro gets the shared memory handle from a NET_BUFFER_SHARED_MEMORY structure. +ms.assetid: 4bec976b-2cee-405d-889b-b0a3e293840e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_SHARED_MEM_HANDLE macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_SHARED\_MEM\_HANDLE macro + + +The **NET\_BUFFER\_SHARED\_MEM\_HANDLE** macro gets the shared memory handle from a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Syntax +------ + +```ManagedCPlusPlus +NDIS_HANDLE NET_BUFFER_SHARED_MEM_HANDLE( +  PNET_BUFFER_SHARED_MEMORY _SHI +); +``` + +Parameters +---------- + +*\_SHI* +A pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Return value +------------ + +**NET\_BUFFER\_SHARED\_MEM\_HANDLE** returns an NDIS shared memory handle. + +Remarks +------- + +An NDIS 6.20 or later driver can use the **NET\_BUFFER\_SHARED\_MEM\_HANDLE** macro to get shared memory handle that is associated with a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. **NET\_BUFFER\_SHARED\_MEM\_HANDLE** gets the handle from the **SharedMemoryHandle** member of the **NET\_BUFFER\_SHARED\_MEMORY** structure. The **SharedMemoryInfo** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure contains the first **NET\_BUFFER\_SHARED\_MEMORY** structure in a linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_SHARED_MEM_HANDLE%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-shared-mem-length.md b/windows-driver-docs-pr/network/net-buffer-shared-mem-length.md new file mode 100644 index 0000000000..e49e572733 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-shared-mem-length.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_SHARED_MEM_LENGTH macro +author: windows-driver-content +description: The NET_BUFFER_SHARED_MEM_LENGTH macro gets the shared memory offset from a NET_BUFFER_SHARED_MEMORY structure. +ms.assetid: 651143e7-9198-4cc6-92a8-d5247f6e32f9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_SHARED_MEM_LENGTH macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_SHARED\_MEM\_LENGTH macro + + +The **NET\_BUFFER\_SHARED\_MEM\_LENGTH** macro gets the shared memory offset from a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_SHARED_MEM_LENGTH( +  PNET_BUFFER_SHARED_MEMORY _SHI +); +``` + +Parameters +---------- + +*\_SHI* +A pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Return value +------------ + +**NET\_BUFFER\_SHARED\_MEM\_LENGTH** returns a ULONG value for the length, in bytes, of the shared memory. + +Remarks +------- + +An NDIS 6.20 or later driver can use the **NET\_BUFFER\_SHARED\_MEM\_LENGTH** macro to get shared memory length that is associated with a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. **NET\_BUFFER\_SHARED\_MEM\_LENGTH** gets the length from the **SharedMemoryLength** member of the **NET\_BUFFER\_SHARED\_MEMORY** structure. The **SharedMemoryInfo** member of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure contains the first **NET\_BUFFER\_SHARED\_MEMORY** structure in a linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_SHARED_MEM_LENGTH%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-shared-mem-next-segment.md b/windows-driver-docs-pr/network/net-buffer-shared-mem-next-segment.md new file mode 100644 index 0000000000..a3f5b0eeec --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-shared-mem-next-segment.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_SHARED_MEM_NEXT_SEGMENT macro +author: windows-driver-content +description: The NET_BUFFER_SHARED_MEM_NEXT_SEGMENT macro gets the next shared memory segment from a NET_BUFFER_SHARED_MEMORY structure. +ms.assetid: 6c2445c5-166e-42c9-aa95-d7c6878571e3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_SHARED_MEM_NEXT_SEGMENT macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT macro + + +The **NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT** macro gets the next shared memory segment from a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Syntax +------ + +```ManagedCPlusPlus +PNET_BUFFER_SHARED_MEMORY NET_BUFFER_SHARED_MEM_NEXT_SEGMENT( +  PNET_BUFFER_SHARED_MEMORY _SHI +); +``` + +Parameters +---------- + +*\_SHI* +A pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Return value +------------ + +**NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT** returns a pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure or returns **NULL**. + +Remarks +------- + +An NDIS 6.20 or later driver can use the **NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT** macro to get the next shared memory segment in a linked list of [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structures that are associated with a [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structure. **NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT** gets a pointer to the next **NET\_BUFFER\_SHARED\_MEMORY** structure from the **NextSharedMemorySegment** member of the **NET\_BUFFER\_SHARED\_MEMORY** structure. The **SharedMemoryInfo** member of the **NET\_BUFFER** structure contains the first **NET\_BUFFER\_SHARED\_MEMORY** structure in the linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_SHARED_MEM_NEXT_SEGMENT%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-shared-mem-offset.md b/windows-driver-docs-pr/network/net-buffer-shared-mem-offset.md new file mode 100644 index 0000000000..6e19f8d3f1 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-shared-mem-offset.md @@ -0,0 +1,84 @@ +--- +title: NET_BUFFER_SHARED_MEM_OFFSET macro +author: windows-driver-content +description: The NET_BUFFER_SHARED_MEM_OFFSET macro gets the shared memory offset from a NET_BUFFER_SHARED_MEMORY structure. +ms.assetid: 7610238b-631b-414d-85ca-6b90c320dfbf +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NET_BUFFER_SHARED_MEM_OFFSET macro Network Drivers Starting with Windows Vista +--- + +# NET\_BUFFER\_SHARED\_MEM\_OFFSET macro + + +The **NET\_BUFFER\_SHARED\_MEM\_OFFSET** macro gets the shared memory offset from a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Syntax +------ + +```ManagedCPlusPlus +ULONG NET_BUFFER_SHARED_MEM_OFFSET( +  PNET_BUFFER _SHI +); +``` + +Parameters +---------- + +*\_SHI* +A pointer to a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. + +Return value +------------ + +**NET\_BUFFER\_SHARED\_MEM\_OFFSET** returns a ULONG value that contains the offset, in bytes, of the shared memory. + +Remarks +------- + +An NDIS 6.20 or later driver can use the [**NET\_BUFFER\_SHARED\_MEM\_HANDLE**](net-buffer-shared-mem-handle.md) macro to get shared memory offset that is associated with a [**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) structure. **NET\_BUFFER\_SHARED\_MEM\_HANDLE** gets the offset from the **SharedMemoryOffset** member of the **NET\_BUFFER\_SHARED\_MEMORY** structure. The **SharedMemoryInfo** member of the NET\_BUFFER structure contains the first **NET\_BUFFER\_SHARED\_MEMORY** structure in a linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Target platform

[Universal](http://go.microsoft.com/fwlink/p/?linkid=531356)

Version

Supported in NDIS 6.20 and later.

Header

Ndis.h (include Ndis.h)
+ +## See also + + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +[**NET\_BUFFER\_SHARED\_MEMORY**](https://msdn.microsoft.com/library/windows/hardware/ff568419) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER_SHARED_MEM_OFFSET%20macro%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-structure-macros.md b/windows-driver-docs-pr/network/net-buffer-structure-macros.md new file mode 100644 index 0000000000..75a1f469f2 --- /dev/null +++ b/windows-driver-docs-pr/network/net-buffer-structure-macros.md @@ -0,0 +1,44 @@ +--- +title: NET_BUFFER Structure Macros +author: windows-driver-content +description: NET_BUFFER Structure Macros +ms.assetid: a996ee50-076c-4c83-927b-3e9775c60c62 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# NET\_BUFFER Structure Macros + + +## + + +This section includes: + +- [**NET\_BUFFER\_CHECKSUM\_BIAS**](net-buffer-checksum-bias.md) +- [**NET\_BUFFER\_CURRENT\_MDL**](net-buffer-current-mdl.md) +- [**NET\_BUFFER\_CURRENT\_MDL\_OFFSET**](net-buffer-current-mdl-offset.md) +- [**NET\_BUFFER\_DATA\_LENGTH**](net-buffer-data-length.md) +- [**NET\_BUFFER\_DATA\_OFFSET**](net-buffer-data-offset.md) +- [**NET\_BUFFER\_FIRST\_MDL**](net-buffer-first-mdl.md) +- [**NET\_BUFFER\_MINIPORT\_RESERVED**](net-buffer-miniport-reserved.md) +- [**NET\_BUFFER\_NEXT\_NB**](net-buffer-next-nb.md) +- [**NET\_BUFFER\_PROTOCOL\_RESERVED**](net-buffer-protocol-reserved.md) +- [**NET\_BUFFER\_SHARED\_MEM\_FLAGS**](net-buffer-shared-mem-flags.md) +- [**NET\_BUFFER\_SHARED\_MEM\_HANDLE**](net-buffer-shared-mem-handle.md) +- [**NET\_BUFFER\_SHARED\_MEM\_LENGTH**](net-buffer-shared-mem-length.md) +- [**NET\_BUFFER\_SHARED\_MEM\_NEXT\_SEGMENT**](net-buffer-shared-mem-next-segment.md) +- [**NET\_BUFFER\_SHARED\_MEM\_OFFSET**](net-buffer-shared-mem-offset.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20NET_BUFFER%20Structure%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/net-buffer-structure.md b/windows-driver-docs-pr/network/net-buffer-structure.md index 1a084582d2..80a31cde5e 100644 --- a/windows-driver-docs-pr/network/net-buffer-structure.md +++ b/windows-driver-docs-pr/network/net-buffer-structure.md @@ -1,6 +1,6 @@ --- -title: NET\_BUFFER Structure -description: NET\_BUFFER Structure +title: NET_BUFFER Structure +description: NET_BUFFER Structure ms.assetid: 6ba44aef-d4e6-4f18-8ae3-aebd8045791f keywords: - NET_BUFFER diff --git a/windows-driver-docs-pr/network/net-luid-value.md b/windows-driver-docs-pr/network/net-luid-value.md index a63bb9b556..b4019cc883 100644 --- a/windows-driver-docs-pr/network/net-luid-value.md +++ b/windows-driver-docs-pr/network/net-luid-value.md @@ -1,6 +1,6 @@ --- -title: NET\_LUID Value -description: NET\_LUID Value +title: NET_LUID Value +description: NET_LUID Value ms.assetid: 9b9c63c1-f8b4-4e26-afc1-a3e4910609e2 keywords: - NDIS network interfaces WDK , NET_LUID diff --git a/windows-driver-docs-pr/network/net-luid-values-for-miniport-adapters-and-filter-modules.md b/windows-driver-docs-pr/network/net-luid-values-for-miniport-adapters-and-filter-modules.md index 23853fd56c..6bd1a16d65 100644 --- a/windows-driver-docs-pr/network/net-luid-values-for-miniport-adapters-and-filter-modules.md +++ b/windows-driver-docs-pr/network/net-luid-values-for-miniport-adapters-and-filter-modules.md @@ -1,6 +1,6 @@ --- -title: NET\_LUID Values for Miniport Adapters and Filter Modules -description: NET\_LUID Values for Miniport Adapters and Filter Modules +title: NET_LUID Values for Miniport Adapters and Filter Modules +description: NET_LUID Values for Miniport Adapters and Filter Modules ms.assetid: d9135438-3399-4845-a28d-d445471cb41d keywords: - NDIS network interfaces WDK , NET_LUID diff --git a/windows-driver-docs-pr/network/network-driver-programming-considerations.md b/windows-driver-docs-pr/network/network-driver-programming-considerations.md index e4602bcdd5..bb03484e5a 100644 --- a/windows-driver-docs-pr/network/network-driver-programming-considerations.md +++ b/windows-driver-docs-pr/network/network-driver-programming-considerations.md @@ -30,7 +30,6 @@ This section includes the following topics: - [Packet Structures in Network Drivers](packet-structures-in-network-drivers.md) - [Using Shared Memory in Network Drivers](using-shared-memory-in-network-drivers.md) - [Asynchronous I/O and Completion Functions in Network Drivers](asynchronous-i-o-and-completion-functions-in-network-drivers.md) -- [NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) - [Security Issues for Network Drivers](security-issues-for-network-drivers.md)   diff --git a/windows-driver-docs-pr/network/network-programming-interface.md b/windows-driver-docs-pr/network/network-programming-interface.md index 39d3e42522..f9a1913b3f 100644 --- a/windows-driver-docs-pr/network/network-programming-interface.md +++ b/windows-driver-docs-pr/network/network-programming-interface.md @@ -24,9 +24,9 @@ Each NPI defines the following items: - An *NPI identifier* that uniquely identifies the NPI. A network module specifies an NPI identifier to indicate the particular NPI that it supports when the network module registers itself with the Network Module Registrar (NMR). A network module can support multiple NPIs by registering itself with the NMR multiple times, once for each NPI that it supports. The NMR will initiate attaching a client module to a provider module only if they both support the same NPI. -- An optional *client characteristics* structure that specifies the NPI-specific characteristics of each client module. Such NPI-specific characteristics might include items such as which version (or versions) of the NPI that a client module supports, or which address family or protocol a client module requires. A provider module can use the information contained in a client module's client characteristics structure to determine if it will attach to the client module. If an NPI does not define any NPI-specific client characteristics, then this structure is not required. +- An optional [*client characteristics*](https://msdn.microsoft.com/library/windows/hardware/ff568812) structure that specifies the NPI-specific characteristics of each client module. Such NPI-specific characteristics might include items such as which version (or versions) of the NPI that a client module supports, or which address family or protocol a client module requires. A provider module can use the information contained in a client module's client characteristics structure to determine if it will attach to the client module. If an NPI does not define any NPI-specific client characteristics, then this structure is not required. -- An optional *provider characteristics* structure that specifies the NPI-specific characteristics of each provider module. Such NPI-specific characteristics might include items such as which version (or versions) of the NPI that a provider module supports, or which address families or protocols a provider module supports. A client module can use the information contained in a provider module's client characteristics structure to determine if it will attach to the provider module. If an NPI does not define any NPI-specific provider characteristics, then this structure is not required. +- An optional [*provider characteristics*](https://msdn.microsoft.com/library/windows/hardware/ff568814) structure that specifies the NPI-specific characteristics of each provider module. Such NPI-specific characteristics might include items such as which version (or versions) of the NPI that a provider module supports, or which address families or protocols a provider module supports. A client module can use the information contained in a provider module's client characteristics structure to determine if it will attach to the provider module. If an NPI does not define any NPI-specific provider characteristics, then this structure is not required. - Zero or more client module callback functions. After a provider module successfully attaches to a client module, the provider module can access the client module's functionality by calling the client module's callback functions. diff --git a/windows-driver-docs-pr/network/ntddndis-h.md b/windows-driver-docs-pr/network/ntddndis-h.md new file mode 100644 index 0000000000..69380e95f5 --- /dev/null +++ b/windows-driver-docs-pr/network/ntddndis-h.md @@ -0,0 +1,316 @@ +--- +title: Ntddndis.h +author: windows-driver-content +description: This section contains network driver topics for the Ntddndis.h header. +ms.assetid: EC2CD8C5-A2E9-4CA3-9229-BF0A955E6F53 +keywords: +- Ntddndis.h network drivers +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Ntddndis.h + + +This section contains network driver topics for the Ntddndis.h header. These topics may also be shared with the user mode applications that interact with network drivers. + +The Ntddndis.h header contains definitions for constants and types for interfacing with network drivers. + +> [!IMPORTANT] +> This section's topics contains pages for definitions, macros, OIDs, status indications, and other data structures that are not part of network driver reference (structures, enumerations, functions, and callbacks). +> +> For more information about network driver reference for this header, see [Ntddndis.h (reference)](https://msdn.microsoft.com/library/windows/hardware/mt808524). + +## In this section + +* [GUID_NDIS_GEN_PCI_DEVICE_CUSTOM_PROPERTIES](guid-ndis-gen-pci-device-custom-properties.md) +* [NDIS_DECLARE_SWITCH_NET_BUFFER_LIST_CONTEXT_TYPE ](ndis-declare-switch-net-buffer-list-context-type.md) +* [NDIS_MAKE_NET_LUID macro](ndis-make-net-luid.md) +* [NDIS_ROUTING_DOMAIN_ENTRY_GET_FIRST_ISOLATION_ENTRY macro](ndis-routing-domain-entry-get-first-isolation-entry.md) +* [NDIS_ROUTING_DOMAIN_ENTRY_GET_NEXT macro](ndis-routing-domain-entry-get-next.md) +* [NDIS_ROUTING_DOMAIN_ISOLATION_ENTRY_GET_NEXT macro](ndis-routing-domain-isolation-entry-get-next.md) +* [NDIS_STATUS_ISOLATION_PARAMETERS_CHANGE](ndis-status-isolation-parameters-change.md) +* [NDIS_STATUS_NIC_SWITCH_CURRENT_CAPABILITIES](ndis-status-nic-switch-current-capabilities.md) +* [NDIS_STATUS_NIC_SWITCH_HARDWARE_CAPABILITIES](ndis-status-nic-switch-hardware-capabilities.md) +* [NDIS_STATUS_RECEIVE_FILTER_QUEUE_ALLOCATION_STATE](ndis-status-receive-filter-queue-allocation-state.md) +* [NDIS_STATUS_RECEIVE_FILTER_QUEUE_PARAMETERS](ndis-status-receive-filter-queue-parameters.md) +* [NDIS_STATUS_WWAN_CONTEXT_STATE](ndis-status-wwan-context-state.md) +* [NDIS_STATUS_WWAN_HOME_PROVIDER](ndis-status-wwan-home-provider.md) +* [NDIS_STATUS_WWAN_PACKET_SERVICE](ndis-status-wwan-packet-service.md) +* [NDIS_STATUS_WWAN_PIN_INFO](ndis-status-wwan-pin-info.md) +* [NDIS_STATUS_WWAN_PIN_LIST](ndis-status-wwan-pin-list.md) +* [NDIS_STATUS_WWAN_PREFERRED_PROVIDERS](ndis-status-wwan-preferred-providers.md) +* [NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS](ndis-status-wwan-provisioned-contexts.md) +* [NDIS_STATUS_WWAN_RADIO_STATE](ndis-status-wwan-radio-state.md) +* [NDIS_STATUS_WWAN_READY_INFO](ndis-status-wwan-ready-info.md) +* [NDIS_STATUS_WWAN_REGISTER_STATE](ndis-status-wwan-register-state.md) +* [NDIS_STATUS_WWAN_SERVICE_ACTIVATION](ndis-status-wwan-service-activation.md) +* [NDIS_STATUS_WWAN_SIGNAL_STATE](ndis-status-wwan-signal-state.md) +* [NDIS_STATUS_WWAN_SMS_CONFIGURATION](ndis-status-wwan-sms-configuration.md) +* [NDIS_STATUS_WWAN_SMS_DELETE](ndis-status-wwan-sms-delete.md) +* [NDIS_STATUS_WWAN_SMS_RECEIVE](ndis-status-wwan-sms-receive.md) +* [NDIS_STATUS_WWAN_SMS_SEND](ndis-status-wwan-sms-send.md) +* [NDIS_STATUS_WWAN_SMS_STATUS](ndis-status-wwan-sms-status.md) +* [NDIS_STATUS_WWAN_VENDOR_SPECIFIC](ndis-status-wwan-vendor-specific.md) +* [NDIS_STATUS_WWAN_VISIBLE_PROVIDERS](ndis-status-wwan-visible-providers.md) +* [NDIS_SWITCH_NIC_AT_ARRAY_INDEX macro](ndis-switch-nic-at-array-index.md) +* [NDIS_SWITCH_PORT_AT_ARRAY_INDEX macro](ndis-switch-port-at-array-index.md) +* [NDIS_SWITCH_PORT_PROPERTY_ROUTING_DOMAIN_GET_FIRST_ISOLATION_ENTRY macro](ndis-switch-port-property-routing-domain-get-first-isolation-entry.md) +* [NET_BUFFER_LIST_COALESCED_SEG_COUNT macro](net-buffer-list-coalesced-seg-count.md) +* [NET_BUFFER_LIST_DUP_ACK_COUNT macro](net-buffer-list-dup-ack-count.md) +* [OID_802_3_ADD_MULTICAST_ADDRESS](oid-802-3-add-multicast-address.md) +* [OID_802_3_CURRENT_ADDRESS](oid-802-3-current-address.md) +* [OID_802_3_DELETE_MULTICAST_ADDRESS](oid-802-3-delete-multicast-address.md) +* [OID_802_3_MAC_OPTIONS](oid-802-3-mac-options.md) +* [OID_802_3_MAXIMUM_LIST_SIZE](oid-802-3-maximum-list-size.md) +* [OID_802_3_MULTICAST_LIST](oid-802-3-multicast-list.md) +* [OID_802_3_PERMANENT_ADDRESS](oid-802-3-permanent-address.md) +* [OID_GEN_ADMIN_STATUS](oid-gen-admin-status.md) +* [OID_GEN_ALIAS](oid-gen-alias.md) +* [OID_GEN_BROADCAST_BYTES_RCV](oid-gen-broadcast-bytes-rcv.md) +* [OID_GEN_BROADCAST_BYTES_XMIT](oid-gen-broadcast-bytes-xmit.md) +* [OID_GEN_BROADCAST_FRAMES_RCV](oid-gen-broadcast-frames-rcv.md) +* [OID_GEN_BROADCAST_FRAMES_XMIT](oid-gen-broadcast-frames-xmit.md) +* [OID_GEN_BYTES_RCV](oid-gen-bytes-rcv.md) +* [OID_GEN_BYTES_XMIT](oid-gen-bytes-xmit.md) +* [OID_GEN_CURRENT_LOOKAHEAD](oid-gen-current-lookahead.md) +* [OID_GEN_CURRENT_PACKET_FILTER](oid-gen-current-packet-filter.md) +* [OID_GEN_DEVICE_PROFILE](oid-gen-device-profile.md) +* [OID_GEN_DIRECTED_BYTES_RCV](oid-gen-directed-bytes-rcv.md) +* [OID_GEN_DIRECTED_BYTES_XMIT](oid-gen-directed-bytes-xmit.md) +* [OID_GEN_DIRECTED_FRAMES_RCV](oid-gen-directed-frames-rcv.md) +* [OID_GEN_DIRECTED_FRAMES_XMIT](oid-gen-directed-frames-xmit.md) +* [OID_GEN_DISCONTINUITY_TIME](oid-gen-discontinuity-time.md) +* [OID_GEN_DRIVER_VERSION](oid-gen-driver-version.md) +* [OID_GEN_ENUMERATE_PORTS](oid-gen-enumerate-ports.md) +* [OID_GEN_FRIENDLY_NAME](oid-gen-friendly-name.md) +* [OID_GEN_HARDWARE_STATUS](oid-gen-hardware-status.md) +* [OID_GEN_HD_SPLIT_CURRENT_CONFIG](oid-gen-hd-split-current-config.md) +* [OID_GEN_HD_SPLIT_PARAMETERS](oid-gen-hd-split-parameters.md) +* [OID_GEN_INIT_TIME_MS](oid-gen-init-time-ms.md) +* [OID_GEN_INTERFACE_INFO](oid-gen-interface-info.md) +* [OID_GEN_INTERRUPT_MODERATION](oid-gen-interrupt-moderation.md) +* [OID_GEN_ISOLATION_PARAMETERS](oid-gen-isolation-parameters.md) +* [OID_GEN_LAST_CHANGE](oid-gen-last-change.md) +* [OID_GEN_LINK_PARAMETERS](oid-gen-link-parameters.md) +* [OID_GEN_LINK_SPEED](oid-gen-link-speed.md) +* [OID_GEN_LINK_SPEED_EX](oid-gen-link-speed-ex.md) +* [OID_GEN_LINK_STATE](oid-gen-link-state.md) +* [OID_GEN_MAC_OPTIONS](oid-gen-mac-options.md) +* [OID_GEN_MACHINE_NAME](oid-gen-machine-name.md) +* [OID_GEN_MAX_LINK_SPEED](oid-gen-max-link-speed.md) +* [OID_GEN_MAXIMUM_FRAME_SIZE](oid-gen-maximum-frame-size.md) +* [OID_GEN_MAXIMUM_LOOKAHEAD](oid-gen-maximum-lookahead.md) +* [OID_GEN_MAXIMUM_SEND_PACKETS](oid-gen-maximum-send-packets.md) +* [OID_GEN_MAXIMUM_TOTAL_SIZE](oid-gen-maximum-total-size.md) +* [OID_GEN_MEDIA_CAPABILITIES](oid-gen-media-capabilities.md) +* [OID_GEN_MEDIA_CONNECT_STATUS](oid-gen-media-connect-status.md) +* [OID_GEN_MEDIA_CONNECT_STATUS_EX](oid-gen-media-connect-status-ex.md) +* [OID_GEN_MEDIA_DUPLEX_STATE](oid-gen-media-duplex-state.md) +* [OID_GEN_MEDIA_IN_USE](oid-gen-media-in-use.md) +* [OID_GEN_MEDIA_SENSE_COUNTS](oid-gen-media-sense-counts.md) +* [OID_GEN_MEDIA_SUPPORTED](oid-gen-media-supported.md) +* [OID_GEN_MINIPORT_RESTART_ATTRIBUTES](oid-gen-miniport-restart-attributes.md) +* [OID_GEN_MULTICAST_BYTES_RCV](oid-gen-multicast-bytes-rcv.md) +* [OID_GEN_MULTICAST_BYTES_XMIT](oid-gen-multicast-bytes-xmit.md) +* [OID_GEN_MULTICAST_FRAMES_RCV](oid-gen-multicast-frames-rcv.md) +* [OID_GEN_MULTICAST_FRAMES_XMIT](oid-gen-multicast-frames-xmit.md) +* [OID_GEN_NDIS_RESERVED_1](oid-gen-ndis-reserved-1.md) +* [OID_GEN_NDIS_RESERVED_2](oid-gen-ndis-reserved-2.md) +* [OID_GEN_NDIS_RESERVED_5](oid-gen-ndis-reserved-5.md) +* [OID_GEN_NETWORK_LAYER_ADDRESSES](oid-gen-network-layer-addresses.md) +* [OID_GEN_OPERATIONAL_STATUS](oid-gen-operational-status.md) +* [OID_GEN_PCI_DEVICE_CUSTOM_PROPERTIES](oid-gen-pci-device-custom-properties.md) +* [OID_GEN_PHYSICAL_MEDIUM](oid-gen-physical-medium.md) +* [OID_GEN_PHYSICAL_MEDIUM_EX](oid-gen-physical-medium-ex.md) +* [OID_GEN_PORT_AUTHENTICATION_PARAMETERS](oid-gen-port-authentication-parameters.md) +* [OID_GEN_PORT_STATE](oid-gen-port-state.md) +* [OID_GEN_PROMISCUOUS_MODE](oid-gen-promiscuous-mode.md) +* [OID_GEN_PROTOCOL_OPTIONS](oid-gen-protocol-options.md) +* [OID_GEN_RCV_CRC_ERROR](oid-gen-rcv-crc-error.md) +* [OID_GEN_RCV_DISCARDS](oid-gen-rcv-discards.md) +* [OID_GEN_RCV_ERROR](oid-gen-rcv-error.md) +* [OID_GEN_RCV_LINK_SPEED](oid-gen-rcv-link-speed.md) +* [OID_GEN_RCV_NO_BUFFER](oid-gen-rcv-no-buffer.md) +* [OID_GEN_RCV_OK](oid-gen-rcv-ok.md) +* [OID_GEN_RECEIVE_BLOCK_SIZE](oid-gen-receive-block-size.md) +* [OID_GEN_RECEIVE_BUFFER_SPACE](oid-gen-receive-buffer-space.md) +* [OID_GEN_RECEIVE_HASH](oid-gen-receive-hash.md) +* [OID_GEN_RECEIVE_SCALE_CAPABILITIES](oid-gen-receive-scale-capabilities.md) +* [OID_GEN_RECEIVE_SCALE_PARAMETERS](oid-gen-receive-scale-parameters.md) +* [OID_GEN_RESET_COUNTS](oid-gen-reset-counts.md) +* [OID_GEN_RNDIS_CONFIG_PARAMETER](oid-gen-rndis-config-parameter.md) +* [OID_GEN_STATISTICS](oid-gen-statistics.md) +* [OID_GEN_SUPPORTED_GUIDS](oid-gen-supported-guids.md) +* [OID_GEN_SUPPORTED_LIST](oid-gen-supported-list.md) +* [OID_GEN_SUPPORTED_PACKET_FILTERS](oid-gen-supported-packet-filters.md) +* [OID_GEN_TRANSMIT_BLOCK_SIZE](oid-gen-transmit-block-size.md) +* [OID_GEN_TRANSMIT_BUFFER_SPACE](oid-gen-transmit-buffer-space.md) +* [OID_GEN_TRANSMIT_QUEUE_LENGTH](oid-gen-transmit-queue-length.md) +* [OID_GEN_TRANSPORT_HEADER_OFFSET](oid-gen-transport-header-offset.md) +* [OID_GEN_UNKNOWN_PROTOS](oid-gen-unknown-protos.md) +* [OID_GEN_VENDOR_ID](oid-gen-vendor-id.md) +* [OID_GEN_VLAN_ID](oid-gen-vlan-id.md) +* [OID_GEN_XMIT_DISCARDS](oid-gen-xmit-discards.md) +* [OID_GEN_XMIT_ERROR](oid-gen-xmit-error.md) +* [OID_GEN_XMIT_LINK_SPEED](oid-gen-xmit-link-speed.md) +* [OID_GEN_XMIT_OK](oid-gen-xmit-ok.md) +* [OID_NDK_CONNECTIONS](oid-ndk-connections.md) +* [OID_NDK_LOCAL_ENDPOINTS](oid-ndk-local-endpoints.md) +* [OID_NDK_SET_STATE](oid-ndk-set-state.md) +* [OID_NDK_STATISTICS](oid-ndk-statistics.md) +* [OID_NIC_SWITCH_ALLOCATE_VF](oid-nic-switch-allocate-vf.md) +* [OID_NIC_SWITCH_CREATE_SWITCH](oid-nic-switch-create-switch.md) +* [OID_NIC_SWITCH_CREATE_VPORT](oid-nic-switch-create-vport.md) +* [OID_NIC_SWITCH_CURRENT_CAPABILITIES](oid-nic-switch-current-capabilities.md) +* [OID_NIC_SWITCH_DELETE_SWITCH](oid-nic-switch-delete-switch.md) +* [OID_NIC_SWITCH_DELETE_VPORT](oid-nic-switch-delete-vport.md) +* [OID_NIC_SWITCH_ENUM_SWITCHES](oid-nic-switch-enum-switches.md) +* [OID_NIC_SWITCH_ENUM_VFS](oid-nic-switch-enum-vfs.md) +* [OID_NIC_SWITCH_ENUM_VPORTS](oid-nic-switch-enum-vports.md) +* [OID_NIC_SWITCH_FREE_VF](oid-nic-switch-free-vf.md) +* [OID_NIC_SWITCH_HARDWARE_CAPABILITIES](oid-nic-switch-hardware-capabilities.md) +* [OID_NIC_SWITCH_PARAMETERS](oid-nic-switch-parameters.md) +* [OID_NIC_SWITCH_VF_PARAMETERS](oid-nic-switch-vf-parameters.md) +* [OID_NIC_SWITCH_VPORT_PARAMETERS](oid-nic-switch-vport-parameters.md) +* [OID_PACKET_COALESCING_FILTER_MATCH_COUNT](oid-packet-coalescing-filter-match-count.md) +* [OID_PD_CLOSE_PROVIDER](oid-pd-close-provider.md) +* [OID_PD_OPEN_PROVIDER](oid-pd-open-provider.md) +* [OID_PD_QUERY_CURRENT_CONFIG](oid-pd-query-current-config.md) +* [OID_PM_ADD_PROTOCOL_OFFLOAD](oid-pm-add-protocol-offload.md) +* [OID_PM_ADD_WOL_PATTERN](oid-pm-add-wol-pattern.md) +* [OID_PM_CURRENT_CAPABILITIES](oid-pm-current-capabilities.md) +* [OID_PM_GET_PROTOCOL_OFFLOAD](oid-pm-get-protocol-offload.md) +* [OID_PM_HARDWARE_CAPABILITIES](oid-pm-hardware-capabilities.md) +* [OID_PM_PARAMETERS](oid-pm-parameters.md) +* [OID_PM_PROTOCOL_OFFLOAD_LIST](oid-pm-protocol-offload-list.md) +* [OID_PM_REMOVE_PROTOCOL_OFFLOAD](oid-pm-remove-protocol-offload.md) +* [OID_PM_REMOVE_WOL_PATTERN](oid-pm-remove-wol-pattern.md) +* [OID_PM_WOL_PATTERN_LIST](oid-pm-wol-pattern-list.md) +* [OID_PNP_ADD_WAKE_UP_PATTERN](oid-pnp-add-wake-up-pattern.md) +* [OID_PNP_CAPABILITIES](oid-pnp-capabilities.md) +* [OID_PNP_ENABLE_WAKE_UP](oid-pnp-enable-wake-up.md) +* [OID_PNP_QUERY_POWER](oid-pnp-query-power.md) +* [OID_PNP_REMOVE_WAKE_UP_PATTERN](oid-pnp-remove-wake-up-pattern.md) +* [OID_PNP_SET_POWER](oid-pnp-set-power.md) +* [OID_PNP_WAKE_UP_ERROR](oid-pnp-wake-up-error.md) +* [OID_PNP_WAKE_UP_OK](oid-pnp-wake-up-ok.md) +* [OID_PNP_WAKE_UP_PATTERN_LIST](oid-pnp-wake-up-pattern-list.md) +* [OID_QOS_CURRENT_CAPABILITIES](oid-qos-current-capabilities.md) +* [OID_QOS_HARDWARE_CAPABILITIES](oid-qos-hardware-capabilities.md) +* [OID_QOS_OPERATIONAL_PARAMETERS](oid-qos-operational-parameters.md) +* [OID_QOS_PARAMETERS](oid-qos-parameters.md) +* [OID_QOS_REMOTE_PARAMETERS](oid-qos-remote-parameters.md) +* [OID_RECEIVE_FILTER_ALLOCATE_QUEUE](oid-receive-filter-allocate-queue.md) +* [OID_RECEIVE_FILTER_CLEAR_FILTER](oid-receive-filter-clear-filter.md) +* [OID_RECEIVE_FILTER_CURRENT_CAPABILITIES](oid-receive-filter-current-capabilities.md) +* [OID_RECEIVE_FILTER_ENUM_FILTERS](oid-receive-filter-enum-filters.md) +* [OID_RECEIVE_FILTER_ENUM_QUEUES](oid-receive-filter-enum-queues.md) +* [OID_RECEIVE_FILTER_FREE_QUEUE](oid-receive-filter-free-queue.md) +* [OID_RECEIVE_FILTER_GLOBAL_PARAMETERS](oid-receive-filter-global-parameters.md) +* [OID_RECEIVE_FILTER_HARDWARE_CAPABILITIES](oid-receive-filter-hardware-capabilities.md) +* [OID_RECEIVE_FILTER_MOVE_FILTER](oid-receive-filter-move-filter.md) +* [OID_RECEIVE_FILTER_PARAMETERS](oid-receive-filter-parameters.md) +* [OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE](oid-receive-filter-queue-allocation-complete.md) +* [OID_RECEIVE_FILTER_QUEUE_PARAMETERS](oid-receive-filter-queue-parameters.md) +* [OID_RECEIVE_FILTER_SET_FILTER](oid-receive-filter-set-filter.md) +* [OID_SRIOV_BAR_RESOURCES](oid-sriov-bar-resources.md) +* [OID_SRIOV_CURRENT_CAPABILITIES](oid-sriov-current-capabilities.md) +* [OID_SRIOV_HARDWARE_CAPABILITIES](oid-sriov-hardware-capabilities.md) +* [OID_SRIOV_PF_LUID](oid-sriov-pf-luid.md) +* [OID_SRIOV_PROBED_BARS](oid-sriov-probed-bars.md) +* [OID_SRIOV_READ_VF_CONFIG_BLOCK](oid-sriov-read-vf-config-block.md) +* [OID_SRIOV_READ_VF_CONFIG_SPACE](oid-sriov-read-vf-config-space.md) +* [OID_SRIOV_RESET_VF](oid-sriov-reset-vf.md) +* [OID_SRIOV_SET_VF_POWER_STATE](oid-sriov-set-vf-power-state.md) +* [OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK](oid-sriov-vf-invalidate-config-block.md) +* [OID_SRIOV_VF_SERIAL_NUMBER](oid-sriov-vf-serial-number.md) +* [OID_SRIOV_VF_VENDOR_DEVICE_ID](oid-sriov-vf-vendor-device-id.md) +* [OID_SRIOV_WRITE_VF_CONFIG_BLOCK](oid-sriov-write-vf-config-block.md) +* [OID_SRIOV_WRITE_VF_CONFIG_SPACE](oid-sriov-write-vf-config-space.md) +* [OID_SWITCH_FEATURE_STATUS_QUERY](oid-switch-feature-status-query.md) +* [OID_SWITCH_NIC_ARRAY](oid-switch-nic-array.md) +* [OID_SWITCH_NIC_CONNECT](oid-switch-nic-connect.md) +* [OID_SWITCH_NIC_CREATE](oid-switch-nic-create.md) +* [OID_SWITCH_NIC_DELETE](oid-switch-nic-delete.md) +* [OID_SWITCH_NIC_DISCONNECT](oid-switch-nic-disconnect.md) +* [OID_SWITCH_NIC_REQUEST](oid-switch-nic-request.md) +* [OID_SWITCH_NIC_RESTORE](oid-switch-nic-restore.md) +* [OID_SWITCH_NIC_RESTORE_COMPLETE](oid-switch-nic-restore-complete.md) +* [OID_SWITCH_NIC_SAVE](oid-switch-nic-save.md) +* [OID_SWITCH_NIC_SAVE_COMPLETE](oid-switch-nic-save-complete.md) +* [OID_SWITCH_NIC_UPDATED](oid-switch-nic-updated.md) +* [OID_SWITCH_PARAMETERS](oid-switch-parameters.md) +* [OID_SWITCH_PORT_ARRAY](oid-switch-port-array.md) +* [OID_SWITCH_PORT_CREATE](oid-switch-port-create.md) +* [OID_SWITCH_PORT_DELETE](oid-switch-port-delete.md) +* [OID_SWITCH_PORT_FEATURE_STATUS_QUERY](oid-switch-port-feature-status-query.md) +* [OID_SWITCH_PORT_PROPERTY_ADD](oid-switch-port-property-add.md) +* [OID_SWITCH_PORT_PROPERTY_DELETE](oid-switch-port-property-delete.md) +* [OID_SWITCH_PORT_PROPERTY_ENUM](oid-switch-port-property-enum.md) +* [OID_SWITCH_PORT_PROPERTY_UPDATE](oid-switch-port-property-update.md) +* [OID_SWITCH_PORT_TEARDOWN](oid-switch-port-teardown.md) +* [OID_SWITCH_PORT_UPDATED](oid-switch-port-updated.md) +* [OID_SWITCH_PROPERTY_ADD](oid-switch-property-add.md) +* [OID_SWITCH_PROPERTY_DELETE](oid-switch-property-delete.md) +* [OID_SWITCH_PROPERTY_ENUM](oid-switch-property-enum.md) +* [OID_SWITCH_PROPERTY_UPDATE](oid-switch-property-update.md) +* [OID_TCP_RSC_STATISTICS](oid-tcp-rsc-statistics.md) +* [OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA](oid-tcp-task-ipsec-offload-v2-add-sa.md) +* [OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA_EX](oid-tcp-task-ipsec-offload-v2-add-sa-ex.md) +* [OID_TCP_TASK_IPSEC_OFFLOAD_V2_DELETE_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) +* [OID_TCP_TASK_IPSEC_OFFLOAD_V2_UPDATE_SA](oid-tcp-task-ipsec-offload-v2-update-sa.md) +* [OID_WAN_CO_GET_COMP_INFO](oid-wan-co-get-comp-info.md) +* [OID_WAN_CO_GET_INFO](oid-wan-co-get-info.md) +* [OID_WAN_CO_GET_LINK_INFO](oid-wan-co-get-link-info.md) +* [OID_WAN_CO_GET_STATS_INFO](oid-wan-co-get-stats-info.md) +* [OID_WAN_CO_SET_COMP_INFO](oid-wan-co-set-comp-info.md) +* [OID_WAN_CO_SET_LINK_INFO](oid-wan-co-set-link-info.md) +* [OID_WWAN_AUTH_CHALLENGE](oid-wwan-auth-challenge.md) +* [OID_WWAN_CONNECT](oid-wwan-connect.md) +* [OID_WWAN_CREATE_MAC](oid-wwan-create-mac.md) +* [OID_WWAN_DELETE_MAC](oid-wwan-delete-mac.md) +* [OID_WWAN_DEVICE_CAPS](oid-wwan-device-caps.md) +* [OID_WWAN_DEVICE_CAPS_EX](oid-wwan-device-caps-ex.md) +* [OID_WWAN_DEVICE_SERVICE_COMMAND](oid-wwan-device-service-command.md) +* [OID_WWAN_DEVICE_SERVICE_SESSION](oid-wwan-device-service-session.md) +* [OID_WWAN_DEVICE_SERVICE_SESSION_WRITE](oid-wwan-device-service-session-write.md) +* [OID_WWAN_DEVICE_SERVICES](oid-wwan-device-services.md) +* [OID_WWAN_DEVICE_SLOT_MAPPING_INFO](oid-wwan-device-slot-mappings.md) +* [OID_WWAN_DRIVER_CAPS](oid-wwan-driver-caps.md) +* [OID_WWAN_ENUMERATE_DEVICE_SERVICE_COMMANDS](oid-wwan-enumerate-device-service-commands.md) +* [OID_WWAN_ENUMERATE_DEVICE_SERVICES](oid-wwan-enumerate-device-services.md) +* [OID_WWAN_HOME_PROVIDER](oid-wwan-home-provider.md) +* [OID_WWAN_NETWORK_IDLE_HINT](oid-wwan-network-idle-hint.md) +* [OID_WWAN_PACKET_SERVICE](oid-wwan-packet-service.md) +* [OID_WWAN_PIN](oid-wwan-pin.md) +* [OID_WWAN_PIN_EX](oid-wwan-pin-ex.md) +* [OID_WWAN_PIN_LIST](oid-wwan-pin-list.md) +* [OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS](oid-wwan-preferred-multicarrier-providers.md) +* [OID_WWAN_PREFERRED_PROVIDERS](oid-wwan-preferred-providers.md) +* [OID_WWAN_PRESHUTDOWN](oid-wwan-preshutdown.md) +* [OID_WWAN_PROVISIONED_CONTEXTS](oid-wwan-provisioned-contexts.md) +* [OID_WWAN_RADIO_STATE](oid-wwan-radio-state.md) +* [OID_WWAN_READY_INFO](oid-wwan-ready-info.md) +* [OID_WWAN_REGISTER_STATE](oid-wwan-register-state.md) +* [OID_WWAN_SERVICE_ACTIVATION](oid-wwan-service-activation.md) +* [OID_WWAN_SIGNAL_STATE](oid-wwan-signal-state.md) +* [OID_WWAN_SLOT_INFO](oid-wwan-slot-info-status.md) +* [OID_WWAN_SMS_CONFIGURATION](oid-wwan-sms-configuration.md) +* [OID_WWAN_SMS_DELETE](oid-wwan-sms-delete.md) +* [OID_WWAN_SMS_READ](oid-wwan-sms-read.md) +* [OID_WWAN_SMS_SEND](oid-wwan-sms-send.md) +* [OID_WWAN_SMS_STATUS](oid-wwan-sms-status.md) +* [OID_WWAN_SUBSCRIBE_DEVICE_SERVICE_EVENTS](oid-wwan-subscribe-device-service-events.md) +* [OID_WWAN_SYS_CAPS_INFO](oid-wwan-sys-caps.md) +* [OID_WWAN_USSD](oid-wwan-ussd.md) +* [OID_WWAN_VENDOR_SPECIFIC](oid-wwan-vendor-specific.md) +* [OID_WWAN_VISIBLE_PROVIDERS](oid-wwan-visible-providers.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Ntddndis.h%20%20RELEASE:%20%288/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/obtaining-the-ndis-version.md b/windows-driver-docs-pr/network/obtaining-the-ndis-version.md index 4a9d920bc4..967a88cf94 100644 --- a/windows-driver-docs-pr/network/obtaining-the-ndis-version.md +++ b/windows-driver-docs-pr/network/obtaining-the-ndis-version.md @@ -22,7 +22,7 @@ NDIS versions might not be the same as the operating system versions. For exampl ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md) [Specifying NDIS Version Information](specifying-ndis-version-information.md) diff --git a/windows-driver-docs-pr/network/oid-802-3-add-multicast-address.md b/windows-driver-docs-pr/network/oid-802-3-add-multicast-address.md new file mode 100644 index 0000000000..53818d62a7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-add-multicast-address.md @@ -0,0 +1,84 @@ +--- +title: OID\_802\_3\_ADD\_MULTICAST\_ADDRESS +author: windows-driver-content +description: As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_ADD\_MULTICAST\_ADDRESS OID request to add an 802.3 multicast address to the multicast address list of a miniport adapter. +ms.assetid: e3e6defe-e65f-46bb-9cd6-cb65ffa7d7f0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_ADD_MULTICAST_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_ADD\_MULTICAST\_ADDRESS + + +As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_ADD\_MULTICAST\_ADDRESS OID request to add an 802.3 multicast address to the multicast address list of a miniport adapter. The multicast address is an array of 6 bytes. Adding an address enables that address to receive multicast packets. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +Remarks +------- + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the 6-byte address to be added to the multicast address list. + +The OID\_802\_3\_ADD\_MULTICAST\_ADDRESS OID request can add only one address. To add more than one address, the overlying driver must issue multiple OID\_802\_3\_ADD\_MULTICAST\_ADDRESS OID requests. + +NDIS miniport drivers do not receive this OID request directly. Instead, NDIS consolidates each sequence of OID\_802\_3\_ADD\_MULTICAST\_ADDRESS and [OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md) OID requests into a single [OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) OID request, which it sends to the miniport driver. + +To receive multicast packets, the overlying driver must use the [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) OID to set the packet filter **NDIS\_PACKET\_TYPE\_MULTICAST** flag. + +The miniport driver can set a limit on the number of multicast addresses that the multicast address list can contain. To specify the maximum number of multicast addresses, the miniport driver sets the **MaxMulticastListSize** member of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that it passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. For miniport drivers that are based on NDIS versions before NDIS 6.0, NDIS queries the maximum number of multicast addresses by sending an [OID\_802\_3\_MAXIMUM\_LIST\_SIZE](oid-802-3-maximum-list-size.md) OID request. NDIS returns **NDIS\_STATUS\_MULTICAST\_FULL** if an OID\_802\_3\_ADD\_MULTICAST\_ADDRESS request exceeds this limit. + +To delete a previously added multicast address, make a set request with the [OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md) OID. The overlying driver can add a given multicast address multiple times. If NDIS succeeds the first add request for a given multicast address, NDIS will succeed all subsequent add requests for that address. To delete a multicast address that was added more than once, the overlying driver must delete the address the same number of times that it added the address. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md) + +[OID\_802\_3\_MAXIMUM\_LIST\_SIZE](oid-802-3-maximum-list-size.md) + +[OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) + +[OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_ADD_MULTICAST_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-current-address.md b/windows-driver-docs-pr/network/oid-802-3-current-address.md new file mode 100644 index 0000000000..ff349d7623 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-current-address.md @@ -0,0 +1,49 @@ +--- +title: OID\_802\_3\_CURRENT\_ADDRESS +author: windows-driver-content +description: OID\_802\_3\_CURRENT\_ADDRESS +ms.assetid: 36815f3e-7edc-486f-9c16-948119c469fc +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_CURRENT_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_CURRENT\_ADDRESS + + +## + + +The address the NIC is currently using. + +The network management software cannot set the current station address using the NDIS interface library. It must set this address as a configuration parameter. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_CURRENT_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-delete-multicast-address.md b/windows-driver-docs-pr/network/oid-802-3-delete-multicast-address.md new file mode 100644 index 0000000000..3e606487c6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-delete-multicast-address.md @@ -0,0 +1,113 @@ +--- +title: OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS +author: windows-driver-content +description: As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS OID to delete a previously added multicast address from the multicast address list of a miniport adapter. +ms.assetid: 5efaa724-80b4-4721-a1b0-8ba67c03bb32 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_DELETE_MULTICAST_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS + + +As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS OID to delete a previously added multicast address from the multicast address list of a miniport adapter. The multicast address is an array of 6 bytes. Deleting an address disables that address so that it can no longer receive multicast packets. + +**Version Information** + +Windows Vista +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +Remarks +------- + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the 6-byte address to be deleted from the multicast address list. + +The OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS OID request can delete only one address. To delete more than one address, the protocol driver must issue multiple OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS OID requests. + +NDIS miniport drivers do not receive this OID request directly. Instead, NDIS consolidates each sequence of [OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) and OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS OID requests into a single [OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) OID request. + +To replace or delete the entire multicast list, the protocol driver can use the [OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) OID request. + +To add an address to the list, the protocol driver can use the [OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) OID request. + +The overlying protocol driver can add a given multicast address multiple times by sending multiple [OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) OID requests. If NDIS succeeds the first add request for a given multicast address, NDIS will succeed all subsequent add requests for that address. To delete a multicast address that was added more than once, the overlying driver must delete the address the same number of times that it added the address. + +### Return status codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) + +[OID\_802\_3\_MAXIMUM\_LIST\_SIZE](oid-802-3-maximum-list-size.md) + +[OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_DELETE_MULTICAST_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-mac-options.md b/windows-driver-docs-pr/network/oid-802-3-mac-options.md new file mode 100644 index 0000000000..13cbf0f5a7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-mac-options.md @@ -0,0 +1,53 @@ +--- +title: OID\_802\_3\_MAC\_OPTIONS +author: windows-driver-content +description: OID\_802\_3\_MAC\_OPTIONS +ms.assetid: 9c1f29ad-6a2c-4cb4-b402-bd86e851dc2d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_MAC_OPTIONS Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_MAC\_OPTIONS + + +## + + +A protocol can use this OID to determine features supported by the underlying driver, which could be emulating Ethernet. + +The underlying driver returns zero, indicating that it supports no options. + +**Note**  This OID is obsolete for NDIS 6 drivers. + +  + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_MAC_OPTIONS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-maximum-list-size.md b/windows-driver-docs-pr/network/oid-802-3-maximum-list-size.md new file mode 100644 index 0000000000..e27f5d1835 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-maximum-list-size.md @@ -0,0 +1,58 @@ +--- +title: OID\_802\_3\_MAXIMUM\_LIST\_SIZE +author: windows-driver-content +description: OID\_802\_3\_MAXIMUM\_LIST\_SIZE +ms.assetid: e4288fb3-6bb3-415c-b150-1f258a2fa1a0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_MAXIMUM_LIST_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_MAXIMUM\_LIST\_SIZE + + +## + + +NDIS and overlying protocol drivers use the OID\_802\_3\_MAXIMUM\_LIST\_SIZE OID request to query or set the maximum number of 6-byte multicast addresses that the miniport adapter's multicast address list can hold. + +This multicast address list is shared by all protocol drivers that are bound to the miniport adapter. Because it is a shared resource, a protocol driver can receive **NDIS\_STATUS\_MULTICAST\_FULL** from the miniport adapter in response to an [OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) OID set request, even if the number of elements in the list is less than the number that NDIS previously returned for an OID\_802\_3\_MAXIMUM\_LIST\_SIZE OID query request. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) + +[OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md) + +[OID\_802\_3\_MULTICAST\_LIST](oid-802-3-multicast-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_MAXIMUM_LIST_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-multicast-list.md b/windows-driver-docs-pr/network/oid-802-3-multicast-list.md new file mode 100644 index 0000000000..3fd6ba43d4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-multicast-list.md @@ -0,0 +1,85 @@ +--- +title: OID\_802\_3\_MULTICAST\_LIST +author: windows-driver-content +description: As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_MULTICAST\_LIST OID request to replace the current multicast address list on a miniport adapter. +ms.assetid: 601f38e1-26ae-4d72-9d72-91bd58f81bba +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_MULTICAST_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_MULTICAST\_LIST + + +As a set request, NDIS and overlying protocol drivers use the OID\_802\_3\_MULTICAST\_LIST OID request to replace the current multicast address list on a miniport adapter. If an address is present in the list, that address is enabled to receive multicast packets. + +As a query request, NDIS and protocol drivers use the OID\_802\_3\_MULTICAST\_LIST OID request to obtain the current multicast address list. + +## + + +NDIS handles OID\_802\_3\_MULTICAST\_LIST query requests for miniport drivers, so miniport drivers never receive these query requests. + +Miniport drivers that support multicast address lists must support OID\_802\_3\_MULTICAST\_LIST set requests. + +For a set request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the multicast address list as an array of addresses. + +- Each address is an array of 6 bytes. +- The **InformationBufferLength** member contains the length, in bytes, of the **InformationBuffer** array. +- If there are duplicate addresses in the list in the **InformationBuffer** member, NDIS removes the duplicates before sending the OID\_802\_3\_MULTICAST\_LIST set request to the miniport driver. +- If the **InformationBufferLength** member is zero, the miniport driver must clear the multicast address list. +- If the **InformationBufferLength** member is greater than zero, the miniport driver must replace any existing multicast address list with the list in the **InformationBuffer** member. + +The miniport adapter's multicast address list is shared by all protocol drivers that are bound to the miniport adapter. NDIS controls access to this list. If multiple protocol drivers try to modify the list at the same time, NDIS combines their requests into a single OID\_802\_3\_MULTICAST\_LIST set request, which it sends to the miniport driver. + +When a miniport adapter is initialized, it resets the NIC so the multicast address list is zero. NDIS also initializes the packet filter so it does not allow the protocol driver to receive multicast packets. + +To receive a multicast packet, the protocol driver must later do one of the following: + +- Set the packet filter to include the **NDIS\_PACKET\_TYPE\_MULTICAST** flag. At any time, it can disable multicast packet reception by canceling this flag. The order in which the protocol driver enables reception for multicast packets is not important. For more information, see the [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) OID request. +- Set the packet filter to include the **NDIS\_PACKET\_TYPE\_ALL\_MULTICAST** flag, which enables all multicast packets, and do the filtering itself. + +The miniport driver can set a limit on the number of multicast addresses that the multicast address list can contain. NDIS returns **NDIS\_STATUS\_MULTICAST\_FULL** if a protocol driver exceeds this limit or if it specifies an invalid multicast address. + +For a query request, NDIS returns a multicast address list that is the union of all multicast address lists for all protocol bindings. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) + +[OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md) + +[OID\_802\_3\_MAXIMUM\_LIST\_SIZE](oid-802-3-maximum-list-size.md) + +[OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_MULTICAST_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-802-3-permanent-address.md b/windows-driver-docs-pr/network/oid-802-3-permanent-address.md new file mode 100644 index 0000000000..1fa82992ea --- /dev/null +++ b/windows-driver-docs-pr/network/oid-802-3-permanent-address.md @@ -0,0 +1,47 @@ +--- +title: OID\_802\_3\_PERMANENT\_ADDRESS +author: windows-driver-content +description: OID\_802\_3\_PERMANENT\_ADDRESS +ms.assetid: 97d83c17-d98f-41c1-b1fd-44327b72f178 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_802_3_PERMANENT_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_802\_3\_PERMANENT\_ADDRESS + + +## + + +The address of the NIC encoded in the hardware. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_802_3_PERMANENT_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-active-phy-list.md b/windows-driver-docs-pr/network/oid-dot11-active-phy-list.md new file mode 100644 index 0000000000..ffa747fa14 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-active-phy-list.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_ACTIVE\_PHY\_LIST +author: windows-driver-content +description: OID\_DOT11\_ACTIVE\_PHY\_LIST +ms.assetid: d285248b-aae8-440c-a63f-9acdf7379eb1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ACTIVE_PHY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ACTIVE\_PHY\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ACTIVE\_PHY\_LIST object identifier (OID) requests that the miniport driver return the value of the Extensible Station (ExtSTA) **msDot11ActivePhyList** management information base (MIB) object. + +The **msDot11ActivePhyList** MIB object specifies the PHYs on the 802.11 station that it can use for transmitting and receiving packets over the current basic service set (BSS) network connection. The miniport driver specifies the active PHY list when it makes an [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication. This list must not change during the lifetime of the BSS network connection. + +Each entry in the **msDot11ActivePhyList** MIB object is a PHY identifier (IDs), which can be one of the following: + +- An index into the table of supported PHYs as defined by the Native 802.11 Operational **msDot11SupportedPhyTypes** MIB object. For more information about PHY IDs and the **msDot11SupportedPhyTypes** MIB object, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +- A PHY ID with the value of DOT11\_PHY\_ID\_ANY and is the wildcard PHY ID. If the **msDot11ActivePhyList** MIB object contains the wildcard PHY ID, the 802.11 station can use any supported PHY to operate in the BSS network. + +The **msDot11ActivePhyList** MIB object does not define the PHY IDs that can be used by the 802.11 station for scan operations. The PHY IDs that the 802.11 station uses for scanning are specified when [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md) is set. + +The data type for this OID is the [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738) structure. + +When this OID is queried, the miniport driver must do the following: + +- If the 802.11 station is not connected to a BSS network, fail the query request by returning NDIS\_STATUS\_INVALID\_STATE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Verify that the **InformationBuffer** member of its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the desired PHY ID list. For more information about this procedure, see [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ACTIVE_PHY_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-additional-ie.md b/windows-driver-docs-pr/network/oid-dot11-additional-ie.md new file mode 100644 index 0000000000..cd542a91a3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-additional-ie.md @@ -0,0 +1,83 @@ +--- +title: OID\_DOT11\_ADDITIONAL\_IE +author: windows-driver-content +description: OID\_DOT11\_ADDITIONAL\_IE +ms.assetid: 50c539c0-9106-42e6-b4e8-255169eb0089 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ADDITIONAL_IE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ADDITIONAL\_IE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ADDITIONAL\_IE object identifier (OID) requests that the miniport driver set the value of the **msDot11AdditionalIEs** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11AdditionalIEs** MIB object. + +The **msDot11AdditionalIEs** MIB object specifies the values of the additional information elements (IEs) in the BSS 802.11 beacon or probe response frame. + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/ff547645) structure. + +When this OID is set, the NIC must behave as follows: + +- If the Extensible AP is in the INIT state, the NIC must complete the request. + +- If the Extensible AP is in the OP state, the NIC must complete the request and, upon completion of the set request, the NIC must begin using the new additional IEs in the beacon or probe response frames that it sends. + +The NIC should place additional IEs at the end of beacon or probe response frames. + +The NIC must ensure that the corresponding additional IEs appear in every beacon or probe response frame that it sends, unless the additional IEs would cause the size of the frame to exceed the MAC management protocol data unit (MMPDU) limit. In this case, the NIC should discard the new additional IEs, keep the original list of additional IEs, and return NDIS\_STATUS\_BUFFER\_OVERFLOW. However, this overflow situation should not change the NIC operational mode or state. + +The miniport driver should reset the members of the DOT11\_ADDITIONAL\_IE structure to the default values when it receives an [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/ff547645) + +[OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ADDITIONAL_IE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-association-params.md b/windows-driver-docs-pr/network/oid-dot11-association-params.md new file mode 100644 index 0000000000..bc9a868b2e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-association-params.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_ASSOCIATION\_PARAMS +author: windows-driver-content +description: OID\_DOT11\_ASSOCIATION\_PARAMS +ms.assetid: 3d9af740-2efa-4a9e-a3e0-0af5c6745aac +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ASSOCIATION_PARAMS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ASSOCIATION\_PARAMS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ASSOCIATION\_PARAMS OID requests that the miniport driver append a list of additional information elements (IEs) to the association request that the NIC sends to an access point in an infrastructure BSS network. + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_ASSOCIATION\_PARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff547648) structure. + +When this OID is set, the NIC must behave as follows: + +- If the ExtSTA is in the INIT state, the NIC must complete the request. + +- If the ExtSTA is in the OP state, the NIC must fail the request and return error code NDIS\_STATUS\_INVALID\_STATE. + +The NIC should place additional IEs at the end of the association request unless the additional IEs would cause the size of the frame to exceed the MAC management protocol data unit (MMPDU) limit. In this case, the NIC can discard the new additional IEs. + +If the additional IEs are successfully added to the association request, the miniport driver should include these additional IEs in the association request frames that it reports in the [**DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547647) structure. + +The miniport driver should clear its copy of the information in the association request if the **bSetDefaultMIB** member of the [DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) structure is **TRUE** and an OID\_DOT11\_RESET\_REQUEST method request is made to reset the MAC layer of the 802.11 station. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547647) + +[**DOT11\_ASSOCIATION\_PARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff547648) + +[OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ASSOCIATION_PARAMS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-atim-window.md b/windows-driver-docs-pr/network/oid-dot11-atim-window.md new file mode 100644 index 0000000000..82c17d397c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-atim-window.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_ATIM\_WINDOW +author: windows-driver-content +description: OID\_DOT11\_ATIM\_WINDOW +ms.assetid: 440b3948-6008-4ac7-8ff1-307d5edaa9b5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ATIM_WINDOW Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ATIM\_WINDOW + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ATIM\_WINDOW object identifier (OID) requests that the miniport driver set the value of the announcement traffic information message (ATIM) window to the specified value. + +When queried, OID\_DOT11\_ATIM\_WINDOW requests that the miniport driver return the value of the ATIM window. + +The data type for this OID is a ULONG value that specifies the ATIM window in 802.11 time units (TU). One TU is 1024 microseconds. + +The ATIM window is a short time period immediately following the transmission of each 802.11 Beacon frame in an independent basic service set (IBSS) network. During the ATIM window, any station in the IBSS network can indicate the need to transfer data to another station during the next data transmission window. + +**Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +  + +If the miniport driver is operating in the Extensible Station (ExtSTA) mode, it fails a set request of OID\_DOT11\_ATIM\_WINDOW under the following conditions: + +- The 802.11 station does not support 802.11 ATIM windows. In this situation, the miniport driver returns NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- The desired basic service set (BSS) type had not previously been set to **dot11\_BSS\_type\_independent** through a set of [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). In this situation, the miniport driver returns NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- The beacon period was not previously initialized through a set of [OID\_DOT11\_BEACON\_PERIOD](oid-dot11-beacon-period.md). In this situation, the miniport driver returns NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function. + +- The specified ATIM window is less than the target beacon transmission time (TBTT). In this situation, the miniport driver returns NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When queried, the OID\_DOT11\_ATIM\_WINDOW OID requests that the miniport driver return the value of the ATIM window. If the desired BSS type is not **dot11\_BSS\_type\_independent**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ATIM_WINDOW%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-auto-config-enabled.md b/windows-driver-docs-pr/network/oid-dot11-auto-config-enabled.md new file mode 100644 index 0000000000..ebf97085d2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-auto-config-enabled.md @@ -0,0 +1,91 @@ +--- +title: OID\_DOT11\_AUTO\_CONFIG\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_AUTO\_CONFIG\_ENABLED +ms.assetid: aefa79fb-e156-4b67-9008-ef88f4f32302 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_AUTO_CONFIG_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_AUTO\_CONFIG\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_AUTO\_CONFIG\_ENABLED object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11AutoConfigEnabled** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **msDot11AutoConfigEnabled** MIB object. + +The **msDot11AutoConfigEnabled** MIB object specifies the current settings for the following automatic configuration modes: + +Automatic media access control (MAC) configuration. +When automatic MAC configuration is enabled, the 802.11 station manages the configuration of the MAC and can fail set requests that would change MAC related parameters. + +For more information about this mode, see [Automatic MAC Configuration](https://msdn.microsoft.com/library/windows/hardware/ff543813). + +Automatic PHY configuration. +When automatic PHY configuration is enabled, the 802.11 station manages the configuration of the PHY and can fail set requests that would change PHY related parameters. + +For more information about this mode, see [Automatic PHY Configuration](https://msdn.microsoft.com/library/windows/hardware/ff543816). + +The data type for OID\_DOT11\_AUTO\_CONFIG\_ENABLED is a ULONG value, with the automatic configuration settings defined through the following bitmask: + +DOT11\_PHY\_AUTO\_CONFIG\_ENABLED\_FLAG +If this bit is set, the miniport driver has enabled automatic PHY configuration. + +DOT11\_MAC\_AUTO\_CONFIG\_ENABLED\_FLAG +If this bit is set, the miniport driver has enabled automatic MAC configuration. + +The default for the **msDot11AutoConfigEnabled** MIB object has the following flags set: + +- DOT11\_PHY\_AUTO\_CONFIG\_ENABLED\_FLAG + +- DOT11\_MAC\_AUTO\_CONFIG\_ENABLED\_FLAG + +The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_AUTO_CONFIG_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-available-channel-list.md b/windows-driver-docs-pr/network/oid-dot11-available-channel-list.md new file mode 100644 index 0000000000..4cda9e831a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-available-channel-list.md @@ -0,0 +1,67 @@ +--- +title: OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST +author: windows-driver-content +description: OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST +ms.assetid: 3728261d-ed23-491e-b791-ca3778944939 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_AVAILABLE_CHANNEL_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_AVAILABLE\_CHANNEL\_LIST OID requests that the miniport driver return the value of the **msDot11AvailableChannelList** MIB object. The **msDot11AvailableChannelList** MIB object specifies the available operating frequency channel list of the [DSSS, HRDSSS, and ERP PHY configurations](https://msdn.microsoft.com/library/windows/hardware/ff548836) that the NIC can operate with. + +**Note**  Support for this OID is mandatory if the NIC reports to the operating system that it supports DSSS, HRDSSS, or ERP PHY configurations. + +  + +The data type for this OID is the [**DOT11\_AVAILABLE\_CHANNEL\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547663) structure. + +Valid channel numbers are defined in 15.4.6.2 of *IEEE Std. 802.11-1997*. The NIC should return the available frequency channel list based on its own capability and knowledge of the regulatory domain. The NIC must ensure that any entry in this list does not violate the regulatory domain requirements where the NIC is operating. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_AVAILABLE\_CHANNEL\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547663) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_AVAILABLE_CHANNEL_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-available-frequency-list.md b/windows-driver-docs-pr/network/oid-dot11-available-frequency-list.md new file mode 100644 index 0000000000..63fd99ee06 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-available-frequency-list.md @@ -0,0 +1,65 @@ +--- +title: OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST +author: windows-driver-content +description: OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST +ms.assetid: f4531c27-c818-4eed-bbf5-d8e8032167ac +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_AVAILABLE_FREQUENCY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_AVAILABLE\_FREQUENCY\_LIST requests that the miniport driver return the value of the **msDot11AvailableFrequencyList** management information base (MIB) object. The **msDot11AvailableFrequencyList** MIB object specifies the list of available frequencies that the NIC can operate with. + +**Note**  Support for this OID is mandatory if the NIC reports to the operating system that it supports the [OFDM PHY configuration](https://msdn.microsoft.com/library/windows/hardware/ff568828). + +  + +The data type for this OID is the [**DOT11\_AVAILABLE\_FREQUENCY\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547664) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_AVAILABLE\_FREQUENCY\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547664) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_AVAILABLE_FREQUENCY_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-beacon-period.md b/windows-driver-docs-pr/network/oid-dot11-beacon-period.md new file mode 100644 index 0000000000..14489d2f63 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-beacon-period.md @@ -0,0 +1,94 @@ +--- +title: OID\_DOT11\_BEACON\_PERIOD +author: windows-driver-content +description: OID\_DOT11\_BEACON\_PERIOD +ms.assetid: fbb19209-e0dc-44cf-9ebf-60262036ccdc +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_BEACON_PERIOD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_BEACON\_PERIOD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_BEACON\_PERIOD object identifier (OID) requests that the miniport driver set the value of the IEEE 802.11 **dot11BeaconPeriod** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **dot11BeaconPeriod** MIB object. + +**Note**  If the miniport driver is operating in the Extensible AP (ExtAP) mode, the following requirements apply: +- Support for this OID is mandatory. + +- The driver must successfully complete a set request. If the **msDot11AutoConfigEnabled** MIB object has the automatic MAC configuration flag DOT11\_MAC\_AUTO\_CONFIG\_ENABLED\_FLAG set, the miniport driver can choose to use a different MAC value. + +- In response to a query request, the miniport driver should return the actual value of the Beacon frame period (the time interval between two Beacons) that the miniport driver uses. + +  + +The **dot11BeaconPeriod** MIB object is used by the 802.11 station for scheduling the transmission of 802.11 Beacon frames. This value is also specified in the Beacon Interval field of the 802.11 Beacon and Probe Response frames sent by the station. + +The data type for OID\_DOT11\_BEACON\_PERIOD is a ULONG value that specifies the beacon period in 802.11 time units (TU). One TU is 1024 microseconds. The **dot11BeaconPeriod** MIB object has a value from 1 through 65535. + +**Note**  If the miniport driver is operating in the Extensible Station (ExtSTA) mode, it can only transmit Beacon or Probe Response frames if the desired BSS type is set to **dot11\_BSS\_type\_independent**. For more information about the desired BSS type, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +  + +If the miniport driver is operating in ExtSTA mode, the driver and 802.11 station must do the following when set by OID\_DOT11\_BEACON\_PERIOD: + +- The desired BSS type must have previously been set to **dot11\_BSS\_type\_independent** through [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). If not, the miniport driver must fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- After the OID has been set, the 802.11 station uses the specified beacon period only if it starts an IBSS network. + +When queried by OID\_DOT11\_BEACON\_PERIOD, the miniport driver must do the following: + +- If the 802.11 station associates with an ESS or joins an IBSS, return the beacon period from the most recently received Beacon or Probe Response. + +- If the 802.11 station starts an IBSS, return the value of **dot11BeaconPeriod** from the previous set of OID\_DOT11\_BEACON\_PERIOD. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_BEACON_PERIOD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cca-mode-supported.md b/windows-driver-docs-pr/network/oid-dot11-cca-mode-supported.md new file mode 100644 index 0000000000..db4a201ea2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cca-mode-supported.md @@ -0,0 +1,88 @@ +--- +title: OID\_DOT11\_CCA\_MODE\_SUPPORTED +author: windows-driver-content +description: OID\_DOT11\_CCA\_MODE\_SUPPORTED +ms.assetid: b4cebe6a-d128-453e-9c12-c9f6099dbea7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CCA_MODE_SUPPORTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CCA\_MODE\_SUPPORTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CCA\_MODE\_SUPPORTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CCAModeSupported** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the types of clear channel assessment (CCA) modes supported by the current PHY type. For more information about CCA, refer to Clause 16.4.8.5 of the IEEE 802.11-2012 standard and Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +The data type for OID\_DOT11\_CCA\_MODE\_SUPPORTED is a ULONG value, which defines the supported CCA modes through the following bitmask: + +DOT11\_CCA\_MODE\_ED\_ONLY (0x00000001) +Only CCA mode using the energy detect (ED) signal is supported. For more information about the ED signal, refer to Clause 15.4.6.1 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_CS\_ONLY (0x00000002) +Only CCA mode using the carrier sense (CS) signal is supported. For more information about the CS signal, refer to Clause 15.4.6.2 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_ED\_and\_CS (0x00000004) +Both ED and CS modes are supported. + +The **dot11CCAModeSupported** MIB object is only valid for the following PHY types: + +- Direct-sequence spread spectrum (DSSS) PHY. + +- High-rate DSSS (HRDSSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_dsss**, **dot11\_phy\_type\_hrdsss**, or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CCA_MODE_SUPPORTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-max.md b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-max.md new file mode 100644 index 0000000000..0477f287e3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-max.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX +author: windows-driver-content +description: OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX +ms.assetid: 63d50370-43ad-47d7-acc5-166b5d038754 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CCA_WATCHDOG_COUNT_MAX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CCAWatchdogCountMax** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11CCAWatchdogCountMax** MIB object, along with the IEEE 802.11 **dot11CCAWatchdogTimerMax** MIB object, specifies when the current PHY type can ignore energy detected on the channel through the clear channel assessment (CCA) mechanism. For more information about CCA, refer to Clause 16.4.8.5 of the IEEE 802.11-2012 standard. + +The data type for OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX is a ULONG value. + +The **dot11CCAWatchdogCountMax** MIB object is only valid for the infrared (IR) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ir**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CCA_WATCHDOG_COUNT_MAX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-min.md b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-min.md new file mode 100644 index 0000000000..18e133521d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-count-min.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MIN +author: windows-driver-content +description: OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MIN +ms.assetid: a9c535db-6942-44f3-af9c-cba398214e21 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CCA_WATCHDOG_COUNT_MIN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MIN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MIN object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CCAWatchdogCountMin** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11CCAWatchdogCountMin** MIB object specifies the minimum allowed value for the IEEE 802.11 **dot11CCAWatchdogCountMax** MIB object. For more information about the **dot11CCAWatchdogCountMax** MIB object, see [OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MAX](oid-dot11-cca-watchdog-count-max.md). + +The data type for OID\_DOT11\_CCA\_WATCHDOG\_COUNT\_MIN is a ULONG value. + +The **dot11CCAWatchdogCountMin** MIB object is only valid for the infrared (IR) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ir**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CCA_WATCHDOG_COUNT_MIN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-max.md b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-max.md new file mode 100644 index 0000000000..57b3a92be2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-max.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX +author: windows-driver-content +description: OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX +ms.assetid: 4199dff5-bdcf-4ae0-b8c2-0b9ecc54a128 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CCA_WATCHDOG_TIMER_MAX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CCAWatchdogTimerMax** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11CCAWatchdogTimerMax** MIB object, along with the IEEE 802.11 **dot11CCAWatchdogCountMax** MIB object, specifies when the current PHY type can ignore energy detected in the channel through the clear channel assessment (CCA) mechanism. For more information about CCA, refer to Clause 16.4.8.5 of the IEEE 802.11-2012 standard. + +The data type for OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX is a ULONG value, in units of nanoseconds. + +The **dot11CCAWatchdogTimerMax** MIB object is only valid for the infrared (IR) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ir**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CCA_WATCHDOG_TIMER_MAX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-min.md b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-min.md new file mode 100644 index 0000000000..ad867e4add --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cca-watchdog-timer-min.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MIN +author: windows-driver-content +description: OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MIN +ms.assetid: d17d12b3-1ef3-4bc7-8d15-d02cc4b7bc5d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CCA_WATCHDOG_TIMER_MIN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MIN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MIN object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CCAWatchdogTimerMin** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11CCAWatchdogTimerMin** MIB object specifies the minimum allowed value for the IEEE 802.11 **dot11CCAWatchdogTimerMax** MIB object. For more information about the **dot11CCAWatchdogTimerMax** MIB object, see [OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MAX](oid-dot11-cca-watchdog-timer-max.md). + +The data type for OID\_DOT11\_CCA\_WATCHDOG\_TIMER\_MIN is a ULONG value. + +The **dot11CCAWatchdogTimerMin** MIB object is only valid for the infrared (IR) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ir**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA. from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CCA_WATCHDOG_TIMER_MIN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cf-pollable.md b/windows-driver-docs-pr/network/oid-dot11-cf-pollable.md new file mode 100644 index 0000000000..4b369c2e29 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cf-pollable.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CF\_POLLABLE +author: windows-driver-content +description: OID\_DOT11\_CF\_POLLABLE +ms.assetid: 1eb80044-5303-4f81-b821-59376f60ff34 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CF_POLLABLE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CF\_POLLABLE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CF\_POLLABLE object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CFPollable** management information base (MIB) object. + +The **dot11CFPollable** MIB object specifies whether the 802.11 station supports the contention free (CF) access method and CF-Poll frames. + +The data type for OID\_DOT11\_CF\_POLLABLE is a BOOLEAN value. A value of **TRUE** indicates that the 802.11 station supports CF-Poll frames. + +**Note**  The MIB object is **TRUE** only if the 802.11 station can respond to a CF-Poll frame with an MPDU data frame within a short interframe space (SIFS) time. + +  + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CF_POLLABLE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-channel-agility-enabled.md b/windows-driver-docs-pr/network/oid-dot11-channel-agility-enabled.md new file mode 100644 index 0000000000..d95041361b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-channel-agility-enabled.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_CHANNEL\_AGILITY\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_CHANNEL\_AGILITY\_ENABLED +ms.assetid: f77860bd-79d5-4028-b1d6-5f97315b6490 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CHANNEL_AGILITY_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CHANNEL\_AGILITY\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CHANNEL\_AGILITY\_ENABLED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11b **dot11ChannelAgilityEnabled** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the current PHY type has enabled channel agility. For more information about channel agility, refer to Clause 18 of the IEEE 802.11b-1999 standard and Clause 19 of the IEEE 802.11g-2003 standard. + +The data type for OID\_DOT11\_CHANNEL\_AGILITY\_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type has enabled channel agility. + +The **dot11ChannelAgilityEnabled** MIB object is only valid for the following PHY types: + +- High-Rate Direct-sequence spread spectrum (HRDSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_hrdsss** or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CHANNEL_AGILITY_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-channel-agility-present.md b/windows-driver-docs-pr/network/oid-dot11-channel-agility-present.md new file mode 100644 index 0000000000..2b08853cd3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-channel-agility-present.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_CHANNEL\_AGILITY\_PRESENT +author: windows-driver-content +description: OID\_DOT11\_CHANNEL\_AGILITY\_PRESENT +ms.assetid: efa40eb3-cc90-4f7a-a22d-943ce6e6c614 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CHANNEL_AGILITY_PRESENT Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CHANNEL\_AGILITY\_PRESENT + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CHANNEL\_AGILITY\_PRESENT object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11ChannelAgilityPresent** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the current PHY type supports channel agility. For more information about channel agility, refer to Clause 18 of the IEEE 802.11b-1999 standard and Clause 19 of the IEEE 802.11g-2003 standard. + +The data type for OID\_DOT11\_CHANNEL\_AGILITY\_PRESENT is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports channel agility. + +The **dot11ChannelAgilityPresent** MIB object is only valid for the following PHY types: + +- High-Rate Direct-sequence spread spectrum (HRDSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_hrdsss** or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CHANNEL_AGILITY_PRESENT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cipher-default-key-id.md b/windows-driver-docs-pr/network/oid-dot11-cipher-default-key-id.md new file mode 100644 index 0000000000..e77d2c5b65 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cipher-default-key-id.md @@ -0,0 +1,85 @@ +--- +title: OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID +author: windows-driver-content +description: OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID +ms.assetid: 2ff0ec23-a957-452e-9762-bf1d83e293e8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CIPHER_DEFAULT_KEY_ID Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **dot11DefaultKeyID** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **dot11DefaultKeyID** MIB object. + +The **dot11DefaultKeyID** MIB object specifies the index of a cipher key in the 802.11 station's default key table that the station uses for data encryption. The 802.11 station uses the cipher key referenced by the **dot11DefaultKeyID** MIB object as the default encryption key for transmitted packets unless a key-mapping key exists for the destination media access control (MAC) address. + +For more information about the default keys, per-station default keys, and key-mapping keys, see [802.11 Cipher Key Types](https://msdn.microsoft.com/library/windows/hardware/ff543625). + +**Note**  Support for this OID is mandatory if the 802.11 station supports any cipher algorithms. The miniport driver returns a list of supported cipher algorithms when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for this OID is a ULONG value. For standard 802.11 cipher algorithms, the default key ID must be from 0 through 3. For a cipher algorithm developed by an IHV, the default key ID can be any value within the range defined by the IHV. + +The IEEE 802.11-2012 standard defines key index values from 1 through 4. The value *x* specified by this OID maps to the 802.11 key index (*x* + 1). + +When transmitting 802.11 data, the 802.11 station will encrypt the MAC service data unit (MSDU) payload data using the cipher key referenced by the **dot11DefaultKeyID** MIB object if the following are true: + +- The basic service set (BSS) network has enabled encryption. + +- A key mapping key does not exist for the destination MAC address. For more information about key-mapping keys, see [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md). + +When OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID is set, the 802.11 station must synchronize the change to the default key ID with its packet-processing path. When the default key ID is changed, the 802.11 station must use it to encrypt the next MAC protocol data unit (MPDU) data frame that it transmits. + +The default value of the **dot11DefaultKeyID** MIB object is zero. The miniport driver must set this MIB object to its default if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CIPHER_DEFAULT_KEY_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cipher-default-key.md b/windows-driver-docs-pr/network/oid-dot11-cipher-default-key.md new file mode 100644 index 0000000000..73e0c2d025 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cipher-default-key.md @@ -0,0 +1,95 @@ +--- +title: OID\_DOT11\_CIPHER\_DEFAULT\_KEY +author: windows-driver-content +description: OID\_DOT11\_CIPHER\_DEFAULT\_KEY +ms.assetid: 51b6c89f-4f9f-482a-a3fe-6622cbcfa04a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CIPHER_DEFAULT_KEY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CIPHER\_DEFAULT\_KEY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CIPHER\_DEFAULT\_KEY object identifier (OID) requests that the miniport driver add, modify, or delete an entry in its default key or per-station default key tables. + +**Note**  Support for this OID is mandatory if the 802.11 station supports any cipher algorithms. The miniport driver returns a list of supported cipher algorithms when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for this OID is the [**DOT11\_CIPHER\_DEFAULT\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547674) structure. + +When the OID\_DOT11\_CIPHER\_DEFAULT\_KEY OID is set, the miniport driver must follow these guidelines: + +- If the 802.11 station does not support the cipher algorithm specified by the **AlgorithmId** member, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the specified cipher algorithm does not support the key index specified by the **uKeyIndex** member, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function. + +- If the **dot11DesiredBSSType** management information base (MIB) object is set to **dot11\_BSS\_type\_independent** and the **MacAddr** member is not set to 0x000000000000, the key defined by the [**DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547675) structure is a per-station cipher key. For more information about per-station default cipher keys, see [Per-Station Default Keys](https://msdn.microsoft.com/library/windows/hardware/ff570016). + + In this situation, the miniport driver must fail the set request if any of the following are true: + + - The **dot11DesiredBSSType** management information base (MIB) object is not set to **dot11\_BSS\_type\_independent**. In this situation, the miniport driver returns NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about the **dot11DesiredBSSType** MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + - **MacAddr** is not a valid unicast MAC address. In this situation, the miniport driver returns NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + - A per-station default key table referenced by **MacAddr** does not exist and the 802.11 station does not have the resources to add a per-station default key table. In this situation, the driver returns NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + **Note**  The miniport driver returns the number of per-station default key tables supported by the 802.11 station when [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md) is queried. + +   + +- If the **bDelete** member is set to **TRUE**, delete the key material for the key referenced by the **uKeyIndex** member. If the driver had previously deleted the specified key, it must accept the set request by returning NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When modifying TKIP keys, the miniport driver must synchronize the key update with the packet-processing path on the 802.11 station. + +For example, the miniport driver must avoid situations in which the packet payload was decrypted using the old cipher key and verified using the new message integrity code (MIC) key. + +The 802.11 station must clear its default keys in the following situations: + +- When the miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- When a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station. + +For more information about default keys and per-station default keys, see [802.11 Cipher Key Types](https://msdn.microsoft.com/library/windows/hardware/ff543625). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CIPHER_DEFAULT_KEY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-cipher-key-mapping-key.md b/windows-driver-docs-pr/network/oid-dot11-cipher-key-mapping-key.md new file mode 100644 index 0000000000..99c8bde916 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-cipher-key-mapping-key.md @@ -0,0 +1,109 @@ +--- +title: OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY +author: windows-driver-content +description: OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY +ms.assetid: 45ee67a9-28f8-43e6-a6c0-8cf233498204 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CIPHER_KEY_MAPPING_KEY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY object identifier (OID) requests that the miniport driver add, modify, or delete one or more entries in its key-mapping key table. + +The 802.11 station uses key-mapping keys for data encryption and decryption between the 802.11 station and a specific AP or peer station in the basic service set (BSS) network. These keys are different from the default cipher keys, which the 802.11 station uses for data encryption and decryption between the 802.11 station and any AP or peer station in the BSS network. + +**Note**  Support for this OID is mandatory if the 802.11 station supports one or more key-mapping keys. The miniport driver returns the number of key-mapping keys it supports when [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md) is queried. + +  + +The data type for this OID is the [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure. The miniport driver sets the members of this structure as follows: + +**Header** +The type and size of the DOT11\_BYTE\_ARRAY structure and the revision of the [**DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547675) structures that follows it. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE\_BYTE\_ARRAY\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_BYTE\_ARRAY). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfBytes** +Number of bytes within the **ucBuffer** array pertaining to the set request. + +**uTotalNumOfBytes** +Total number of bytes within the **ucBuffer** array. This value must be greater than or equal to **uNumOfBytes** . + +**ucBuffer** +The list of key-mapping keys. + +Each element in the list of key-mapping keys is formatted as a variable-length [**DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547675) structure. There must not be padding between key entries within the **ucBuffer** array. + +When the OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY OID is set, the miniport driver must do the following: + +- If the 802.11 station does not support key-mapping keys, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Follow these guidelines when validating the members of the [**DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547675) structure in the following ways: + - If the 802.11 station does not support the cipher algorithm specified by the **AlgorithmId** member, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + - If the **bDelete** member of the [**DOT11\_CIPHER\_KEY\_MAPPING\_KEY\_VALUE**](https://msdn.microsoft.com/library/windows/hardware/ff547675) structure is set to **TRUE**, delete the key material for the key referenced by the **PeerMacAddr** and **Direction** members. If the driver had previously deleted the specified key, it must accept the set request by returning NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. +- When modifying TKIP keys, synchronize the key update with the packet-processing path of the 802.11 station. + + For example, the miniport driver must avoid situations in which the packet payload was decrypted using the old cipher key and verified using the new message integrity code (MIC) key. + +The 802.11 station must clear its key-mapping keys if the following conditions are met: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CIPHER_KEY_MAPPING_KEY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-connect-request.md b/windows-driver-docs-pr/network/oid-dot11-connect-request.md new file mode 100644 index 0000000000..f64a73a618 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-connect-request.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_CONNECT\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_CONNECT\_REQUEST +ms.assetid: 732b9549-6138-4a58-9772-e741880451eb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CONNECT_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CONNECT\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CONNECT\_REQUEST object identifier (OID) requests that the miniport driver perform a connection operation to a basic service set (BSS) network. For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +No data is associated with this OID. + +If the connection operation completes successfully, the miniport driver must transition to the Extensible Station (ExtSTA) operational (OP) state. The miniport driver must remain in the ExtSTA OP state until either a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) or set request of [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) is made. For more information about this state, see [Extensible Station Operating States](https://msdn.microsoft.com/library/windows/hardware/ff549883). + +When OID\_DOT11\_CONNECT\_REQUEST is set, the miniport driver must fail the request by returning NDIS\_STATUS\_POWER\_STATE\_INVALID from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function if any of the following are true: + +- All of the PHYs specified through the ExtSTA **msDot11DesiredPhyList** MIB object are turned off through sets of [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). For more information about this MIB object, see [OID\_DOT11\_DESIRED\_PHY\_LIST](oid-dot11-desired-phy-list.md). + +- All of the PHYs specified through the ExtSTA **msDot11DesiredPhyList** MIB object are turned off through a hardware switch setting or proprietary software setting. + +- Additional criteria apply for the connection request to fail, as described in [General Connection Operation Guidelines](https://msdn.microsoft.com/library/windows/hardware/ff552458). + +When OID\_DOT11\_CONNECT\_REQUEST is set, the miniport driver can do one of the following: + +- Wait for the connection operation to complete before completing the set request. + +- Initiate the connection operation and complete the set request. In this situation, the miniport driver must return NDIS\_STATUS\_PENDING from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the connection operation. After the reset operation has finished, the miniport driver completes the set request by calling [**NdisMRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CONNECT_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-country-string.md b/windows-driver-docs-pr/network/oid-dot11-country-string.md new file mode 100644 index 0000000000..4eb1a27bbd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-country-string.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_COUNTRY\_STRING +author: windows-driver-content +description: OID\_DOT11\_COUNTRY\_STRING +ms.assetid: 17942342-0983-46ff-a1ed-f1a37a097010 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_COUNTRY_STRING Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_COUNTRY\_STRING + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_COUNTRY\_STRING object identifier (OID) requests that the miniport driver return the value of the **dot11CountryString** management information base (MIB) object. + +**Note**  Support for OID\_DOT11\_COUNTRY\_STRING is mandatory if the 802.11 station supports more than one regulatory domain. For more information about how the miniport driver specifies its support for regulatory domains, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +  + +The data type for OID\_DOT11\_COUNTRY\_STRING is the [**DOT11\_COUNTRY\_STRING**](dot11-country-string.md) structure. + +The 802.11 station sets the **dot11CountryString** MIB object from the value of the Country Information Element (IE) from the 802.11 Beacon or Probe Response frames received within the basic service set (BSS) network to which the station has connected. For more information about this IE, refer to Clause 7.3.2.12 of the IEEE 802.1d-2001 standard. + +When queried by OID\_DOT11\_COUNTRY\_STRING, the miniport driver must fail the request under the following conditions: + +- If the miniport driver does not support more than one regulatory domain, it must fail the query request by returning NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. The miniport driver specifies its support of regulatory domains in response to queries of [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the miniport driver supports more than one regulatory domain, but this capability is currently disabled, it must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. The miniport driver specifies the status of the multiple regulatory domain support in response to queries of [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +- If the 802.11 station is performing a scan request, the miniport driver must fail the query request by returning NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about scan requests, see [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_COUNTRY_STRING%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-create-mac.md b/windows-driver-docs-pr/network/oid-dot11-create-mac.md new file mode 100644 index 0000000000..fce367592d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-create-mac.md @@ -0,0 +1,82 @@ +--- +title: OID\_DOT11\_CREATE\_MAC +author: windows-driver-content +description: OID\_DOT11\_CREATE\_MAC +ms.assetid: 808f60d4-bd3d-46c9-8bb4-f6d6e9307ff5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CREATE_MAC Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CREATE\_MAC + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When a method request of the OID\_DOT11\_CREATE\_MAC object identifier (OID) is made, the miniport driver must create a new 802.11 MAC entity and return a [**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) structure. For more information about the method request type, see [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710). + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) structure. + +If the miniport driver has already created the maximum number of MAC entities that it can support, it should fail this OID method request and return the status indication NDIS\_STATUS\_OPEN\_LIST\_FULL. + +Before the miniport driver completes its response to this OID request, it should call the [**NdisMAllocatePort**](https://msdn.microsoft.com/library/windows/hardware/ff562779) function to allocate a corresponding NDIS port for each 802.11 MAC entity that the driver creates. + +Starting in Windows 8, if the input buffer size is > 0, the input for this OID is formatted as a [**DOT11\_MAC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406491) structure. + +Remarks +------- + +If the MAC is to function as a Wi-Fi Direct device port, **uOpmodeMask** in [**DOT11\_MAC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406491) will contain the **DOT11\_OPERATION\_MODE\_WFD\_DEVICE** flag. In this case, the miniport driver must return the same device address in [**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) as the one specified in the **DeviceAddress** member of [**DOT11\_WFD\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/hh406574) sent with the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available starting with Windows 7.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) + +[**DOT11\_MAC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406491) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisMAllocatePort**](https://msdn.microsoft.com/library/windows/hardware/ff562779) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CREATE_MAC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-address.md b/windows-driver-docs-pr/network/oid-dot11-current-address.md new file mode 100644 index 0000000000..2806bca659 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-address.md @@ -0,0 +1,59 @@ +--- +title: OID\_DOT11\_CURRENT\_ADDRESS +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_ADDRESS +ms.assetid: f8141fae-a771-43c4-8ced-5bb0cc7001c2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_ADDRESS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_ADDRESS object identifier (OID) requests that the miniport driver return the IEEE media access control (MAC) address that the 802.11 station is currently using. + +The data type for this OID is the [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-cca-mode.md b/windows-driver-docs-pr/network/oid-dot11-current-cca-mode.md new file mode 100644 index 0000000000..c3cff3d6cc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-cca-mode.md @@ -0,0 +1,102 @@ +--- +title: OID\_DOT11\_CURRENT\_CCA\_MODE +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_CCA\_MODE +ms.assetid: 7fce5f95-37e5-4efc-a740-6a27628a4a5a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_CCA_MODE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_CCA\_MODE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_CCA\_MODE object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentCCAMode** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the current clear channel assessment (CCA) mode in use by the current PHY type. For more information about CCA, refer to Clause 16.4.8.5 of the IEEE 802.11-2012 standard and Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +The data type for OID\_DOT11\_CURRENT\_CCA\_MODE is a ULONG value. + +The current CCA mode is explained in the following bitmask: + +DOT11\_CCA\_MODE\_ED\_ONLY (0x00000001) +CCA mode using the energy detect (ED) signal. For more information about the ED signal, refer to Clause 15.4.6.1 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_CS\_ONLY (0x00000002) +CCA mode using the carrier sense (CS) signal. For more information about the CS signal, refer to Clause 15.4.6.2 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_ED\_and\_CS (0x00000004) +Both ED and CS modes. + +DOT11\_HR\_CCA\_MODE\_CS\_WITH\_TIMER (0x00000008) +CCA mode using the CS signal with a timer. For more information about this CCA mode, refer to Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +This mode is valid only for high-rate direct-sequence spread spectrum (HRDSSS) PHYs. + +DOT11\_HR\_CCA\_MODE\_HRCS\_AND\_ED (0x00000010) +Both ED and CS modes on high-rate (HR) PHYs. For more information about this CCA mode, refer to Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +This mode is valid only for HRDSSS PHYs. + +The miniport driver must not set more than one bit when specifying the current CCA mode. + +The **dot11CurrentCCAMode** MIB object is only valid for the following PHY types: + +- Direct-sequence spread spectrum (DSSS) PHY. + +- High-rate DSSS (HRDSSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_dsss**, **dot11\_phy\_type\_hrdsss**, or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_CCA_MODE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-channel-number.md b/windows-driver-docs-pr/network/oid-dot11-current-channel-number.md new file mode 100644 index 0000000000..a3aa08e6ee --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-channel-number.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER +ms.assetid: e4f5cea0-54f8-44cb-99d4-05a4e711d199 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_CHANNEL_NUMBER Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentChannelNumber** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11CurrentChannelNumber** MIB object stores the current channel number used by the physical media dependent (PMD) sublayer of the current PHY type for transmit and receive operations. For more information about channel numbers, refer to Clause 14.9.2.17 of the IEEE 802.11-2012 standard. + +**Note**  Support for OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_CHANNEL\_NUMBER is a ULONG value that specifies the channel number from 0 through 99. + +The **dot11CurrentChannelNumber** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_CHANNEL_NUMBER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-channel.md b/windows-driver-docs-pr/network/oid-dot11-current-channel.md new file mode 100644 index 0000000000..51bf249035 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-channel.md @@ -0,0 +1,124 @@ +--- +title: OID\_DOT11\_CURRENT\_CHANNEL +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_CHANNEL +ms.assetid: 85f75cd8-ae9f-4dca-be9c-39e1c824d48c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_CHANNEL Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_CHANNEL + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CURRENT\_CHANNEL object identifier (OID) requests that the miniport driver set the IEEE 802.11 **dot11CurrentChannel** or **dot11CurrentPrimaryChannel** management information base (MIB) object to the specified value for the current PHY type on the 802.11 station. + +For the **dot11\_phy\_type\_ht** and **dot11\_phy\_type\_vht** PHY types, the OID sets the value of the **dot11CurrentPrimaryChannel** MIB object. For the **dot11\_phy\_type\_ht** operating in the 2.4 GHz band, the OID also sets the value of the **dot11CurrentChannel** MIB object. + +When queried, this OID requests that the miniport driver return the value of the **dot11CurrentChannel** or **dot11CurrentPrimaryChannel** MIB object for the current PHY type. For the **dot11\_phy\_type\_ht** and **dot11\_phy\_type\_vht** PHY types, the miniport queries the **dot11CurrentPrimaryChannel** MIB object. + +The **dot11CurrentChannel** MIB object defines the current operating frequency channel used by the PHY for transmit and receive operations. For more information about frequency channels, refer to clause 16.4.6.3 of the [IEEE 802.11-2012 standard](http://standards.ieee.org/getieee802/download/802.11-2012.pdf). + +The **dot11CurrentPrimaryChannel** MIB object defines the location of the primary 20 MHz channel. For more information about this MIB object, see clause 20.4.2 of the [IEEE 802.11-2012 standard](http://standards.ieee.org/getieee802/download/802.11-2012.pdf) and clause 22.3.14 of IEEE Draft P802.11ac/D4.2. + +For more information about 802.11n (HT) operation, refer to clause 10.15 of the [IEEE 802.11-2012 standard](http://standards.ieee.org/getieee802/download/802.11-2012.pdf). + +For more information about 802.11ac operation, refer to clause 10.39 of IEEE Draft P802.11ac/D4.2. + +The data type for OID\_DOT11\_CURRENT\_CHANNEL is a ULONG value that specifies the channel number. + +This OID is valid only for the following PHY types: + +- Direct-sequence spread spectrum (DSSS) PHY (**dot11\_phy\_type\_dsss**). +- High-rate DSSS (HRDSSS) PHY (**dot11\_phy\_type\_hrdsss**). +- Extended-rate PHY (ERP) (**dot11\_phy\_type\_erp**). +- High-Throughput (HT) PHY (**dot11\_phy\_type\_ht**). +- Very High-Throughput (VHT) PHY (**dot11\_phy\_type\_vht**). + +If the current PHY type is not set to one of these valid PHY types, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**Note**  Support for OID\_DOT11\_CURRENT\_CHANNEL is mandatory if the NIC supports any of these valid PHY types. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +If the miniport driver is operating in the Extensible Station (ExtSTA) mode, the miniport driver fails a set request of OID\_DOT11\_CURRENT\_CHANNEL under the following conditions: + +- If the NIC is in a powered-off state, the miniport driver must fail the request by returning NDIS\_STATUS\_POWER\_STATE\_INVALID from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about power states, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +- If the 802.11 station is performing a scan request, the miniport driver can fail the set request by returning NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about scan requests, see [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + + The miniport driver can fail the set request if the 802.11 station is unable to change channels while performing the scan request. + +- If the miniport driver has enabled automatic PHY configuration, it can fail the set request if the 802.11 station manages the PHY-layer configuration. In this situation, the driver returns NDIS\_STATUS\_DOT11\_AUTO\_CONFIG\_ENABLED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about automatic PHY configuration, see [OID\_DOT11\_AUTO\_CONFIG\_ENABLED](oid-dot11-auto-config-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +If the miniport driver is in Extensible Access Point (ExtAP) mode, the driver is responsible for implementing regulatory domain support in the NIC. The driver should therefore treat any channel or frequency set by the operating system in OID\_DOT11\_CURRENT\_CHANNEL or [OID\_DOT11\_CURRENT\_FREQUENCY](oid-dot11-current-frequency.md) to be only a suggestion. In response to query calls to these OIDs, the driver should return the actual channel or frequency values that the NIC is using. Whenever the driver adopts a channel or frequency, or it has started an AP, it should call the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function to make a [**DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548735) indication to the operating system. + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +When the PHY is operating in 802.11n or 802.11ac mode, the miniport driver must report the primary channel when it completes the following: + +- Packet receive indications. For more information, see [Media-Specific OOB Data for Received 802.11 Packets](https://msdn.microsoft.com/library/windows/hardware/ff559169). + +- [Native 802.11 status indications](https://msdn.microsoft.com/library/windows/hardware/ff560685) that report channel information, such as [**DOT11\_PHY\_FREQUENCY\_ADOPTED\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff548735). +- Query requests of OID\_DOT11\_CURRENT\_CHANNEL. + +- Query requests of [OID\_DOT11\_ENUM\_BSS\_LIST](oid-dot11-enum-bss-list.md). + + In this case, the miniport driver reports the primary channel in the **PhySpecificInfo** member of the [**DOT11\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff547665) structure. The driver returns this structure when it completes the query request of OID\_DOT11\_ENUM\_BSS\_LIST. + +For more information about 802.11ac 20/40/80/160/80+80 MHz mode, refer to the [IEEE P802.11ac standard (under development)](http://www.ieee802.org/11/Reports/tgac_update.md). + +**Note**  When the miniport driver receives an [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) method request the miniport driver must reset the **dot11CurrentChannel** and **dot11CurrentPrimaryChannel** MIB objects to their default values under the following conditions: +- When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to TRUE. +- When MAC or PHY values are affected by the value of the **dot11ResetType** member. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_CHANNEL%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-dwell-time.md b/windows-driver-docs-pr/network/oid-dot11-current-dwell-time.md new file mode 100644 index 0000000000..4f82ffd0b4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-dwell-time.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_CURRENT\_DWELL\_TIME +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_DWELL\_TIME +ms.assetid: 373ec7fc-5302-40ad-bf65-c27f5d725354 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_DWELL_TIME Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_DWELL\_TIME + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_DWELL\_TIME object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentDwellTime** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object defines the amount of time that the current PHY type can use when transmitting on a single channel. + +**Note**  Support for OID\_DOT11\_CURRENT\_DWELL\_TIME is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_DWELL\_TIME is a ULONG value that specifies the maximum dwell time in units of 802.11 time units (TU). One TU is 1024 microseconds. The value of the **dot11CurrentDwellTime** MIB must be from 1 through 65535. + +The **dot11CurrentDwellTime** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_DWELL_TIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-frequency.md b/windows-driver-docs-pr/network/oid-dot11-current-frequency.md new file mode 100644 index 0000000000..17a02837a2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-frequency.md @@ -0,0 +1,97 @@ +--- +title: OID\_DOT11\_CURRENT\_FREQUENCY +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_FREQUENCY +ms.assetid: 8e164bef-0a83-41cb-a287-82d67553a611 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_FREQUENCY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_FREQUENCY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CURRENT\_FREQUENCY object identifier (OID) requests that the miniport driver set the value of the IEEE 802.11a **dot11CurrentFrequency** management information base (MIB) object for the current PHY type on the 802.11 station. + +When queried, OID\_DOT11\_CURRENT\_FREQUENCY requests that the miniport driver return the value of the **dot11CurrentFrequency** MIB object. + +This MIB object defines the current operating frequency channel used by the PHY. + +**Note**  Support for OID\_DOT11\_CURRENT\_FREQUENCY is mandatory if the NIC supports the **dot11\_phy\_type\_ofdm** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_FREQUENCYis a ULONG value from 0 through 200. + +**Note**  If a service provided by the independent hardware vendor (IHV) is managing the wireless network profiles, the IHV can use whatever value range it supports. + +  + +The **dot11CurrentFrequency** MIB object is only valid for the orthogonal frequency division multiplexing (OFDM) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ofdm**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_CURRENT\_FREQUENCY is set, the miniport driver fails the request under the following conditions: + +- If the current PHY type is in a powered-off state, the miniport driver must fail the request by returning NDIS\_STATUS\_POWER\_STATE\_INVALID from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about power states, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +- If the 802.11 station is currently performing a scan request, the miniport driver must fail the set request by returning NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about scan requests, see [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + +If the miniport driver is operating in the Extensible Station (ExtSTA) mode, it fails the set request of OID\_DOT11\_CURRENT\_FREQUENCY under the following conditions: + +- If the desired BSS type is **dot11\_BSS\_type\_infrastructure**, the miniport driver must fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about the desired BSS type, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +- If the miniport driver has enabled automatic PHY configuration, it can fail the set request if the 802.11 station manages the PHY-layer configuration. In this situation, the driver returns NDIS\_STATUS\_DOT11\_AUTO\_CONFIG\_ENABLED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about automatic PHY configuration, see [OID\_DOT11\_AUTO\_CONFIG\_ENABLED](oid-dot11-auto-config-enabled.md). + +If the miniport driver is operating in ExtSTA mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_FREQUENCY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-index.md b/windows-driver-docs-pr/network/oid-dot11-current-index.md new file mode 100644 index 0000000000..dadc498d2a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-index.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_CURRENT\_INDEX +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_INDEX +ms.assetid: bc22e608-fcc5-4ad3-bd6b-5fe42e166fdf +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_INDEX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_INDEX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_INDEX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentIndex** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object defines the current index in the hop pattern that the layer management entity (LME) of the PHY uses to determine the current channel number. For more information about how the current channel number is determined, refer to Clause 14.9.2.21 of the IEEE 802.11-2012 standard. + +**Note**  Support for OID\_DOT11\_CURRENT\_INDEX is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_INDEX is a ULONG value from 1 through 255. + +The **dot11CurrentIndex** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +For more information about the 802.11 station's list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +For more information about the current hop pattern, see [OID\_DOT11\_CURRENT\_PATTERN](oid-dot11-current-pattern.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_INDEX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-operation-mode.md b/windows-driver-docs-pr/network/oid-dot11-current-operation-mode.md new file mode 100644 index 0000000000..c4336eee7c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-operation-mode.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_CURRENT\_OPERATION\_MODE +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_OPERATION\_MODE +ms.assetid: 6fe4261a-ab7a-4aef-a67b-62f76d83796e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_OPERATION_MODE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_OPERATION\_MODE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CURRENT\_OPERATION\_MODE object identifier (OID) requests that the miniport driver set its Native 802.11 or Wi-Fi Direct (WFD) operation mode to the specified value. + +When queried, this OID requests that the miniport driver return its Native 802.11 operation mode. + +The data type for OID\_DOT11\_CURRENT\_OPERATION\_MODE is the [**DOT11\_CURRENT\_OPERATION\_MODE**](https://msdn.microsoft.com/library/windows/hardware/ff547678) structure. + +When OID\_DOT11\_CURRENT\_OPERATION\_MODE is set, the miniport driver must do the following: + +- If the miniport driver does not support the specified operation mode, fail the set request by returning NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the operation mode changes, configure the 802.11 station with the default settings defined for the operation mode. The miniport driver must also transition to the initialization (INIT) state for the operation mode. + +The operation mode setting must persist through resets resulting from a call to the miniport driver's [*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) function or a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +A Wi-Fi Direct–capable miniport must support all defined WFD operation modes. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available starting with Windows Vista.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_OPERATION_MODE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-optional-capability.md b/windows-driver-docs-pr/network/oid-dot11-current-optional-capability.md new file mode 100644 index 0000000000..e0bc92963d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-optional-capability.md @@ -0,0 +1,96 @@ +--- +title: OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY +author: windows-driver-content +description: When queried, the OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY object identifier (OID) requests that the miniport driver return the state of the optional wireless LAN (WLAN) capabilities supported by the 802.11 station. +ms.assetid: e029712c-b34f-447c-9e43-48e5a72ad6ad +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_OPTIONAL_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY object identifier (OID) requests that the miniport driver return the state of the optional wireless LAN (WLAN) capabilities supported by the 802.11 station. + +Optional WLAN capabilities are not required for the 802.11 station to operate within a basic service set (BSS) network. However, once enabled, these capabilities could provide better performance within the BSS network. When [OID\_DOT11\_OPTIONAL\_CAPABILITY](oid-dot11-optional-capability.md) is queried, the miniport driver specifies the types of optional WLAN capabilities supported by the 802.11 station. + +The data type for OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY is the DOT11\_CURRENT\_OPTIONAL\_CAPABILITY structure. + +```ManagedCPlusPlus + typedef struct _DOT11_CURRENT_OPTIONAL_CAPABILITY { + ULONG uReserved; + BOOLEAN bDot11CFPollable; + BOOLEAN bDot11PCF; + BOOLEAN bDot11PCFMPDUTransferToPC; + BOOLEAN bStrictlyOrderedServiceClass; + } DOT11_CURRENT_OPTIONAL_CAPABILITY, *PDOT11_CURRENT_OPTIONAL_CAPABILITY; + +``` + +This structure includes the following members: + +**uReserved** +This member is reserved. The miniport driver must not modify the value of this member. + +**bDot11CFPollable** +Specifies whether the 802.11 station can respond to an 802.11 CF-Poll frame. The miniport driver should return the value of the IEEE 802.11 **dot11CFPollable** management information base (MIB) object. For more information about this MIB object, see [OID\_DOT11\_CF\_POLLABLE](oid-dot11-cf-pollable.md). + +**bDot11PCF** +Specifies whether the 802.11 station has enabled the Point Coordination Function (PCF). For more information about PCF, refer to clauses 9.2.3 and 9.4 of the IEEE 802.11-2012 standard. + +**bDot11PCFMPDUTransferToPC** +Specifies whether the 802.11 station has enabled delivery of received PCF MAC protocol data unit (MPDU) frames to the operating system. + +**Note**   +If the miniport driver sets this member to **TRUE**, the miniport driver must also set the **bDot11PCF** member to **TRUE**. + +  + +**bStrictlyOrderedServiceClass** +Specifies whether the 802.11 station has enabled the StrictlyOrdered service class for MSDU packet ordering. For more information about the StrictlyOrdered service class, refer to clause 5.1.3 of the IEEE 802.11-2012 standard. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY is a query-only OID and cannot be used to enable or disable the optional WLAN capabilities supported by the 802.11 station. However, the independent hardware vendor (IHV) can define a proprietary NIC-specific extension to change the optional WLAN capabilities. After its been defined, a service supplied by the IHV can issue the NIC-specific extension to the miniport driver. For more information about NIC-specific extensions, see [OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION](oid-dot11-nic-specific-extension.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_OPTIONAL_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-pattern.md b/windows-driver-docs-pr/network/oid-dot11-current-pattern.md new file mode 100644 index 0000000000..1d9724dd4e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-pattern.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_CURRENT\_PATTERN +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_PATTERN +ms.assetid: ea27b5dd-ac07-4c4f-8a1f-1ced7d658717 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_PATTERN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_PATTERN object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentPattern** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object defines the current hopping pattern used by the layer management entity (LME) of the current PHY type to determine the hopping sequence. For more information about how the hopping sequence is determined, refer to Clause 14.9.2.20 of the IEEE 802.11-2012 standard. + +**Note**  Support for OID\_DOT11\_CURRENT\_PATTERN is mandatory if the NIC supports the **dot11\_phy\_type\_fhsss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_PATTERN is a ULONG value from 0 through 255. + +The **dot11CurrentPattern** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID** t, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-phy-id.md b/windows-driver-docs-pr/network/oid-dot11-current-phy-id.md new file mode 100644 index 0000000000..70cfc67637 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-phy-id.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_CURRENT\_PHY\_ID +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_PHY\_ID +ms.assetid: 1f551f19-01e7-4e12-8399-977589ffca32 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_PHY_ID Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_PHY\_ID + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_CURRENT\_PHY\_ID object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11CurrentPhyID** management information base (MIB) object to the specified value. + +When queried, OID\_DOT11\_CURRENT\_PHY\_ID requests that the miniport driver return the value of the **msDot11CurrentPhyID** MIB object. + +The **msDot11CurrentPhyID** MIB object specifies the PHY identifier (ID) that the miniport driver uses when PHY-layer OIDs are set or queried. Examples of PHY-layer OIDs are: + +- [OID\_DOT11\_HARDWARE\_PHY\_STATE](oid-dot11-hardware-phy-state.md) + +- [OID\_DOT11\_CURRENT\_CHANNEL](oid-dot11-current-channel.md) + +- [OID\_DOT11\_DIVERSITY\_SUPPORT](oid-dot11-diversity-support.md) + +A PHY ID is an index into the table of supported PHYS as defined by the Native 802.11 Operational **msDot11SupportedPhyTypes** MIB object. For more information about PHY IDs and the **msDot11SupportedPhyTypes** MIB object, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +When OID\_DOT11\_CURRENT\_PHY\_ID is set, the miniport driver must fail the request if the specified PHY ID is greater than or equal to the number of entries defined by the **msDot11SupportedPhyTypes** MIB object. In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The data type for this OID is a ULONG value. The default value of the **msDot11CurrentPhyID** MIB object is zero. The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_PHY_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-reg-domain.md b/windows-driver-docs-pr/network/oid-dot11-current-reg-domain.md new file mode 100644 index 0000000000..28fff28855 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-reg-domain.md @@ -0,0 +1,131 @@ +--- +title: OID\_DOT11\_CURRENT\_REG\_DOMAIN +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_REG\_DOMAIN +ms.assetid: 29937d0b-ed26-45cb-8ebc-2a37e313faf9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_REG_DOMAIN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_REG\_DOMAIN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_REG\_DOMAIN object identifier (OID) requests that the miniport driver return the IEEE 802.11 **dot11CurrentRegDomain** management information base (MIB) object. + +This MIB object defines the current regulatory domain used by the physical media dependent (PMD) sublayer of the current PHY type on the 802.11 station. + +The data type for OID\_DOT11\_CURRENT\_REG\_DOMAIN is a ULONG value. The following table lists the values of the regulatory domains defined for the **dot11CurrentRegDomain** MIB object. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameValueRegulatory domain

DOT11_REG_DOMAIN_OTHER

0x00000000

Defined by country code settings.

DOT11_REG_DOMAIN_FCC

0x00000010

United States

DOT11_REG_DOMAIN_DOC

0x00000020

Canada

DOT11_REG_DOMAIN_ETSI

0x00000030

Most of Europe

DOT11_REG_DOMAIN_SPAIN

0x00000031

Spain

DOT11_REG_DOMAIN_FRANCE

0x00000032

France

DOT11_REG_DOMAIN_MKK

0x00000040

Japan

+ +  + +The miniport driver, operating in Extensible Station (ExtSTA) mode, must support the OID\_DOT11\_CURRENT\_REG\_DOMAIN for query requests only. In this operating mode, the current regulatory domain is changed through a set request of [OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING](oid-dot11-desired-country-or-region-string.md). For more information about the ExtSTA operation mode, see [Extensible Station Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff549887). + +The 802.11 station is defined to be operating in a default regulatory domain whenever the miniport driver sets the value of the **dot11CurrentRegDomain** MIB object to any value except DOT11\_REG\_DOMAIN\_OTHER through one of the following: + +- A call to the driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function. In this situation, the driver can set the **dot11CurrentRegDomain** MIB object to a default regulatory domain based on configuration parameters from the system registry. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). In this situation, the driver can restore the **dot11CurrentRegDomain** MIB object to its initialization value. + +- A set request of [OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING](oid-dot11-desired-country-or-region-string.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_REG_DOMAIN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-set.md b/windows-driver-docs-pr/network/oid-dot11-current-set.md new file mode 100644 index 0000000000..142b117e09 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-set.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_CURRENT\_SET +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_SET +ms.assetid: 8cf7fc2f-8fac-4203-8281-87e96f3cc098 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_SET Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_SET + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_SET object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentSet** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object defines the current set of patterns used by the layer management entity (LME) of the current PHY type to determine the hopping sequence. For more information about the hopping pattern sets, refer to Clause 14.9.2.19 of the IEEE 802.11-2012 standard. + +**Note**  Support for OID\_DOT11\_CURRENT\_SET is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_CURRENT\_SET is a ULONG value that specifies the antenna index from 1 through 255. + +The **dot11CurrentSet** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_SET%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-current-tx-power-level.md b/windows-driver-docs-pr/network/oid-dot11-current-tx-power-level.md new file mode 100644 index 0000000000..42e3fba18f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-current-tx-power-level.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_CURRENT\_TX\_POWER\_LEVEL +author: windows-driver-content +description: OID\_DOT11\_CURRENT\_TX\_POWER\_LEVEL +ms.assetid: 082c900c-9037-4c16-8c42-6896b762c9be +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_CURRENT_TX_POWER_LEVEL Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_CURRENT\_TX\_POWER\_LEVEL + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_CURRENT\_TX\_POWER\_LEVEL object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11CurrentTxPowerLevel** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the power level of the current PHY type. Depending upon the PHY type, this MIB object can be used to determine the receiver sensitivity requirements for the PHY's clear channel assessment (CCA) mechanism. + +The data type for OID\_DOT11\_CURRENT\_TX\_POWER\_LEVEL is a ULONG value from 1 through 8. + +The current TX power level for the current PHY type in use must be within the range of TX power levels previously specified by the miniport driver when queried by [OID\_DOT11\_SUPPORTED\_POWER\_LEVELS](oid-dot11-supported-power-levels.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_CURRENT_TX_POWER_LEVEL%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-data-rate-mapping-table.md b/windows-driver-docs-pr/network/oid-dot11-data-rate-mapping-table.md new file mode 100644 index 0000000000..9e03597ffc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-data-rate-mapping-table.md @@ -0,0 +1,102 @@ +--- +title: OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE +author: windows-driver-content +description: When queried, the OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE object identifier (OID) requests that the miniport driver return the table of data rates supported by a PHY on the 802.11 station for transmit and receive operations. +ms.assetid: f0d7a91d-9eaa-4a54-98dd-6e60641c8386 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DATA_RATE_MAPPING_TABLE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE object identifier (OID) requests that the miniport driver return the table of data rates supported by a PHY on the 802.11 station for transmit and receive operations. + +The data type for OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE is the DOT11\_DATA\_RATE\_MAPPING\_TABLE structure. + +```ManagedCPlusPlus + typedef struct _DOT11_DATA_RATE_MAPPING_TABLE { + NDIS_OBJECT_HEADER Header; + ULONG uDataRateMappingLength; + DOT11_DATA_RATE_MAPPING_ENTRY DataRateMappingEntries[126]; + } DOT11_DATA_RATE_MAPPING_TABLE, *PDOT11_DATA_RATE_MAPPING_TABLE; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_DATA\_RATE\_MAPPING\_TABLE structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_DATA\_RATE\_MAPPING\_TABLE\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_DATA\_RATE\_MAPPING\_TABLE). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uDataRateMappingLength** +The number of entries in the **DataRateMappingEntries** array. + +**DataRateMappingEntries** +The data rates supported by the 802.11 station. Each entry in the **DataRateMappingEntries** array is formatted as a [**DOT11\_DATA\_RATE\_MAPPING\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff547679) structure. + +When OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE is queried, the miniport driver must do the following: + +- Return the data rates for the current PHY type. + + The current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +- Return all of the IEEE 802.11 standard data rates, even if the PHY does not support the data rate. + +- Return any proprietary, non-standard data rates supported by the PHY. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DATA_RATE_MAPPING_TABLE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-delete-mac.md b/windows-driver-docs-pr/network/oid-dot11-delete-mac.md new file mode 100644 index 0000000000..e762aa2b22 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-delete-mac.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_DELETE\_MAC +author: windows-driver-content +description: OID\_DOT11\_DELETE\_MAC +ms.assetid: 84ca1060-5460-4f63-b452-a0f6429aaca8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DELETE_MAC Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DELETE\_MAC + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When a set request of the OID\_DOT11\_DELETE\_MAC object identifier (OID) is made, the miniport driver must delete an 802.11 MAC entity that corresponds to a caller-provided [**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) structure. + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) structure. + +If there is no 802.11 MAC entity that corresponds to the **uNdisPortNumber** NDIS port in the caller-provided DOT11\_MAC\_INFO structure, the miniport driver should return the NDIS\_STATUS\_INVALID\_PARAMETER status code. + +Before the miniport driver returns from a set request from this OID, it should call the [**NdisMFreePort**](https://msdn.microsoft.com/library/windows/hardware/ff563588) function to free the corresponding NDIS port that was earlier created in a call to [OID\_DOT11\_CREATE\_MAC](oid-dot11-create-mac.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548689) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisMFreePort**](https://msdn.microsoft.com/library/windows/hardware/ff563588) + +[OID\_DOT11\_CREATE\_MAC](oid-dot11-create-mac.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DELETE_MAC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-desired-bss-type.md b/windows-driver-docs-pr/network/oid-dot11-desired-bss-type.md new file mode 100644 index 0000000000..70d2407df4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-desired-bss-type.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_DESIRED\_BSS\_TYPE +author: windows-driver-content +description: OID\_DOT11\_DESIRED\_BSS\_TYPE +ms.assetid: 8e90f503-5aeb-49b9-b368-4fdc8f0cf496 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DESIRED_BSS_TYPE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DESIRED\_BSS\_TYPE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DESIRED\_BSS\_TYPE object identifier (OID) requests that the miniport driver set the value of the IEEE 802.11 **dot11DesiredBSSType** management information base (MIB) object to the specified value. + +When queried, OID\_DOT11\_DESIRED\_BSS\_TYPE requests that the miniport driver return the value of the **dot11DesiredBSSType** MIB object. + +The **dot11DesiredBSSType** MIB object specifies the type of basic service set (BSS) that the 802.11 station can join or start. The 802.11 station uses the desired BSS type to determine the type of 802.11 BSS to join or start in the following way: + +- If the desired BSS type is **dot11\_BSS\_type\_infrastructure**, the 802.11 station can only connect to infrastructure BSSs. + +- If the desired BSS type is **dot11\_BSS\_type\_independent**, the 802.11 station can only connect to an existing independent BSS (IBSS) or start a new IBSS network. + +The miniport driver cannot set the **dot11DesiredBSSType** MIB object to **dot11\_BSS\_type\_any**. The miniport driver must fail a set request for this value by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Regardless of whether the **dot11DesiredBSSType** MIB object changes when OID\_DOT11\_DESIRED\_BSS\_TYPE is set, the miniport driver must always reload the defaults values for the following: + +- The enabled authentication algorithms. For more information about the default values for authentication algorithms, see [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md). + +- The enabled unicast cipher algorithms. For more information about the default values for unicast cipher algorithms, see [OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md). + +- The enabled multicast cipher algorithms. For more information about the default values for multicast cipher algorithms, see [OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md). + +The default for the **dot11DesiredBSSType** MIB object is **dot11\_BSS\_type\_infrastructure**. The miniport driver must set this MIB object to its default if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DESIRED_BSS_TYPE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-desired-bssid-list.md b/windows-driver-docs-pr/network/oid-dot11-desired-bssid-list.md new file mode 100644 index 0000000000..a81ef25e8c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-desired-bssid-list.md @@ -0,0 +1,162 @@ +--- +title: OID\_DOT11\_DESIRED\_BSSID\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_DESIRED\_BSSID\_LIST object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) msDot11DesiredBSSIDList management information base (MIB) object to the specified data. +ms.assetid: 17989e77-0a75-48f3-8fda-e9f9cf124f1a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DESIRED_BSSID_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DESIRED\_BSSID\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DESIRED\_BSSID\_LIST object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11DesiredBSSIDList** management information base (MIB) object to the specified data. + +When queried, OID\_DOT11\_DESIRED\_BSSID\_LIST requests that the miniport driver return the value of the **msDot11DesiredBSSIDList** MIB object. + +The **msDot11DesiredBSSIDList** MIB object specifies the list of 802.11 basic service set identifiers (BSSIDs) that the 802.11 station uses when connecting to a basic service set (BSS) network. After [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station will attempt to connect to a BSS with a BSSID that matches an entry from this list. + +The data type for this OID is the DOT11\_BSSID\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_BSSID_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_MAC_ADDRESS BSSIDs[1]; + } DOT11_BSSID_LIST, *PDOT11_BSSID_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_BSSID\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_BSSID\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_BSSID\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **BSSIDs** array. A zero value for this member indicates an empty desired BSSID list. + +**uTotalNumOfEntries** +Maximum number of entries that the **BSSIDs** array can contain. + +**BSSIDs** +The list of desired BSSIDs. For more information about the data type of this member, see [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681). + +A wildcard BSSID has the value of 0xFFFFFFFFFFFF. The wildcard BSSID matches any BSSID. + +A desired BSSID list containing the wildcard BSSID cannot contain other BSSIDs. When this OID is set, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function if the **BSSIDs** array contains a wildcard BSSID and **uNumOfEntries** is greater than one. + +If the miniport driver's desired BSS type is set to **dot11\_BSS\_type\_infrastructure**, the 802.11 station can associate with a BSS only if the following are true: + +- The service set identifier (SSID) of the BSS is in the miniport driver's desired SSID list. If the desired SSID list contains the wildcard SSID, the 802.11 station can associate with any infrastructure BSS network. + + For more information about the wildcard SSID, see [**DOT11\_SSID**](https://msdn.microsoft.com/library/windows/hardware/ff548773). + +- The BSSID of an access point (AP) in the BSS is in the miniport driver's desired BSSID list. If the desired BSSID list contains the wildcard BSSID, the 802.11 station can associate with any AP in the BSS network. + +If the miniport driver's desired BSS type is set to **dot11\_BSS\_type\_independent**, the 802.11 station can join or start an IBSS only if the following are true: + +- The SSID of the BSS is in the miniport driver's desired SSID list. If the desired SSID list contains the wildcard SSID, the 802.11 station can connect to any IBSS network. + +- If an IBSS is within range, the 802.11 station can connect if the BSSID of the IBSS is in the miniport driver's desired BSSID list. If the desired BSSID list contains the wildcard BSSID, the 802.11 station can associate with any IBSS within range. + +- If an IBSS is not within range, the 802.11 station must start the IBSS network. The 802.11 station uses the first entry from the desired BSSID list as the BSSID for the IBSS network. If the desired BSSID list contains the wildcard BSSID, the 802.11 station can use any locally administered unicast media access control (MAC) address as the BSSID for the IBSS network. + +**Note**  The 802.11 station cannot connect to a BSS network or start an IBSS if its desired BSSID list is empty. + +  + +For more information about the desired BSS type, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +For more information about the desired SSID list, see [OID\_DOT11\_DESIRED\_SSID\_LIST](oid-dot11-desired-ssid-list.md). + +When OID\_DOT11\_DESIRED\_BSSID\_LIST is set, the miniport driver should ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + +``` + FIELD_OFFSET(DOT11_BSSID_LIST, BSSIDs) + uNumOfEntries * sizeof(DOT11_MAC_ADDRESS)) +``` + +When OID\_DOT11\_DESIRED\_BSSID\_LIST is set, the miniport driver must fail the set request if the **uNumOfEntries** member has a value greater than the value of **uDesiredBSSIDListSize** that the driver previously returned through a query of [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md). In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_DESIRED\_BSSID\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_BSSID\_LIST structure, including all entries in the **BSSIDs** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_BSSID\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **BSSIDs** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_BSSID\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_BSSID\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_BSSID\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **BSSIDs** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_BSSID\_LIST structure. The miniport driver must also copy the entire DOT11\_BSSID\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default for the **msDot11DesiredBSSIDList** MIB object contains a single entry with **BSSIDs\[0\]** set to the wildcard BSSID and **uNumEntries** set to one. The miniport driver must set this MIB object to its default if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DESIRED_BSSID_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-desired-country-or-region-string.md b/windows-driver-docs-pr/network/oid-dot11-desired-country-or-region-string.md new file mode 100644 index 0000000000..9cd5c3bc91 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-desired-country-or-region-string.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING +author: windows-driver-content +description: OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING +ms.assetid: 5a1e9019-c821-45c9-b8ed-5b78d213f7ee +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11DesiredCountryOrRegionString** management information base (MIB) object to the specified data. + +When queried, OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING requests that the miniport driver return the value of the **msDot11DesiredCountryOrRegionString** MIB object. + +The data type for OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING is the [**DOT11\_COUNTRY\_OR\_REGION\_STRING**](dot11-country-or-region-string.md) structure. + +**Note**  Support for OID\_DOT11\_DESIRED\_COUNTRY\_OR\_REGION\_STRING is mandatory if the 802.11 station supports multiple regulatory domains as defined through the IEEE 802.11d-2001 standard. For more information about how the miniport driver specifies its support for regulatory domains, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +  + +The **msDot11DesiredCountryOrRegionString** MIB object specifies an IEEE 802.11d country string used by the 802.11 station whenever it does one of the following: + +- Associates with an access point (AP) or peer stationconnection operation. In this situation, the 802.11 station uses the **msDot11DesiredCountryOrRegionString** MIB object to create a BSS network candidate list in order to determine which AP or peer station it can associate with. + + For more information about the association operation, see [Association Operations](https://msdn.microsoft.com/library/windows/hardware/ff543789). For more information about the BSS network candidate list, see [BSS Network Candidate List](https://msdn.microsoft.com/library/windows/hardware/ff543855). + +- Starts a new independent BSS (IBSS) network during a connection operation. In this situation, the 802.11 station sets the IEEE 802.11Country Information Element (IE) to the value of the **msDot11DesiredCountryOrRegionString** MIB object in the 802.11 Beacon and Probe Response frames that the station transmits. + + For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). For more information about how the 802.11 station starts an IBSS network, see [Connection Operation Guidelines for Independent BSS Networks](https://msdn.microsoft.com/library/windows/hardware/ff545188). + +The default for the **msDot11DesiredCountryOrRegionString** MIB object is a [**DOT11\_COUNTRY\_OR\_REGION\_STRING**](dot11-country-or-region-string.md) string of all zeros. The miniport driver must set this MIB object to its default if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-desired-phy-list.md b/windows-driver-docs-pr/network/oid-dot11-desired-phy-list.md new file mode 100644 index 0000000000..9ef0546b69 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-desired-phy-list.md @@ -0,0 +1,107 @@ +--- +title: OID\_DOT11\_DESIRED\_PHY\_LIST +author: windows-driver-content +description: OID\_DOT11\_DESIRED\_PHY\_LIST +ms.assetid: 48f68993-1b30-4eec-abb3-9f3d32905818 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DESIRED_PHY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DESIRED\_PHY\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DESIRED\_PHY\_LIST object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11DesiredPhyList** management information base (MIB) object to the specified data. + +When queried, OID\_DOT11\_DESIRED\_PHY\_LIST requests that the miniport driver return the value of the **msDot11DesiredPhyList** MIB object. + +The **msDot11DesiredPhyList** MIB object specifies the desired PHY list that the 802.11 station uses when connecting to and operating in a BSS network. Each entry in the **msDot11DesiredPhyList** MIB object is a PHY identifier (IDs), which can be one of the following: + +- An index into the table of supported PHYs as defined by the Native 802.11 Operational **msDot11SupportedPhyTypes** MIB object. For more information about PHY IDs and the **msDot11SupportedPhyTypes** MIB object, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +- A PHY ID with the value of DOT11\_PHY\_ID\_ANY is the wildcard PHY ID. If the **msDot11DesiredPhyList** MIB object contains the wildcard PHY ID, the 802.11 station can use any supported PHY to connect to and operate in a BSS network. + +The **msDot11DesiredPhyList** MIB object does not define the PHY IDs that can be used by the 802.11 station for scan operations. The PHY IDs that the 802.11 station uses for scanning are specified when [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md) is set. + +The data type for OID\_DOT11\_DESIRED\_PHY\_LIST is the [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738) structure. + +When OID\_DOT11\_DESIRED\_PHY\_LIST is set, the miniport driver should ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + +``` + FIELD_OFFSET(DOT11_PHY_ID_LIST, dot11PhyId) + uNumOfEntries * sizeof(ULONG)) +``` + +When OID\_DOT11\_DESIRED\_PHY\_LIST is set, the miniport driver must fail the set request if the members of the [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738) structure meet the following conditions: + +- The desired PHY list must always contain at least one entry. If **uNumOfEntries** is set to zero, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- A desired PHY list containing a wildcard PHY ID cannot contain other PHY IDs. When OID\_DOT11\_DESIRED\_PHY\_LIST is set, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function if the **dot11PhyIds** array contains the wildcard PHY ID and **uNumOfEntries** is greater than one. + +- If the **dot11PhyId** array contains a PHY ID that is not the wildcard PHY ID and has a value greater than or equal to the number of entries defined by the **msDot11SupportedPhyTypes** MIB object, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the **dot11PhyId** array contains a PHY ID that is not supported on the 802.11 station, the miniport driver must fail the request by returning NDIS\_STATUS\_UNSUPPORTED\_MEDIA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the **dot11PhyId** array contains a PHY ID that has been disabled on the 802.11 station through a proprietary mechanism implemented by the independent hardware vendor (IHV), the miniport driver must fail the request by returning NDIS\_STATUS\_UNSUPPORTED\_MEDIA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + **Note**  This condition does not apply to PHYs disabled through a set request of [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +   + +When OID\_DOT11\_DESIRED\_PHY\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the desired PHY ID list. For more information about this procedure, see [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738). + +The default for the **msDot11DesiredPhyList** MIB object contains a single entry with the members of the [**DOT11\_PHY\_ID\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548738) structure set as follows: + +- **dot11PhyId\[0\]** is set to DOT11\_PHY\_ID\_ANY. + +- **uNumEntries** is set to one. + +The miniport driver must set the **msDot11DesiredPhyList** MIB object to its default whenever the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Beginning in Windows 7, the default behavior of the ExtAP mode is to support only one desired PHY ID at a time. If multiple PHY IDs are present in a set request to this OID, the NIC should start a BSS using the first PHY ID in the list. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DESIRED_PHY_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-desired-ssid-list.md b/windows-driver-docs-pr/network/oid-dot11-desired-ssid-list.md new file mode 100644 index 0000000000..b99a0da741 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-desired-ssid-list.md @@ -0,0 +1,142 @@ +--- +title: OID\_DOT11\_DESIRED\_SSID\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_DESIRED\_SSID\_LIST object identifier (OID) requests that the miniport driver set the value of the msDot11DesiredSSIDList management information base (MIB) object to the specified data. +ms.assetid: a04d7f5a-d262-4a2a-b439-d311a300a574 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DESIRED_SSID_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DESIRED\_SSID\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DESIRED\_SSID\_LIST object identifier (OID) requests that the miniport driver set the value of the **msDot11DesiredSSIDList** management information base (MIB) object to the specified data. + +When queried, OID\_DOT11\_DESIRED\_SSID\_LIST requests that the miniport driver return the value of the **msDot11DesiredSSIDList** MIB object. + +The **msDot11DesiredSSIDList** MIB object specifies the list of 802.11 service set identifiers (SSIDs) that the 802.11 station uses when connecting to a basic service set (BSS) network. After [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station will attempt to connect to a BSS with an service set identifier (SSID) that matches an entry from this list. + +The data type for OID\_DOT11\_DESIRED\_SSID\_LIST is the DOT11\_SSID\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_SSID_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_SSID SSIDs[1]; + } DOT11_SSID_LIST, *PDOT11_SSID_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_SSID\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_SSID\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_SSID\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **SSIDs** array. A zero value for this member indicates an empty desired SSID list. + +**uTotalNumOfEntries** +Maximum number of entries that the **SSIDs** array can contain. + +**SSIDs** +The list of desired SSIDs, with each entry formatted as a [**DOT11\_SSID**](https://msdn.microsoft.com/library/windows/hardware/ff548773) structure. + +The operating system will define a desired SSID list containing a single SSID. However, a service developed by the independent hardware vendor (IHV) can define a list containing one or more SSIDs. + +An SSID with the **uSSIDLength** member of the [**DOT11\_SSID**](https://msdn.microsoft.com/library/windows/hardware/ff548773) structure set to zero is a wildcard SSID. The wildcard SSID matches any SSID. + +A desired SSID list containing a wildcard SSID cannot contain other SSIDs. When OID\_DOT11\_DESIRED\_SSID\_LIST is set, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function if the **SSIDs** array contains a wildcard SSID and **uNumOfEntries** is greater than one. + +After the [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) OID is set, the 802.11 station performs a connection operation to a BSS network only if the SSID of the BSS is in the desired SSID list. If the desired SSID list contains a wildcard SSID, the 802.11 station can connect to any BSS network. The 802.11 station cannot connect to any BSS if its desired SSID list is empty. For more information about connecting to a BSS network, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +When OID\_DOT11\_DESIRED\_SSID\_LIST is set, the miniport driver should ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + +``` + FIELD_OFFSET(DOT11_SSID_LIST, SSIDs) + uNumOfEntries * sizeof(DOT11_SSID)) +``` + +When OID\_DOT11\_DESIRED\_SSID\_LIST is set, the miniport driver must fail the set request if the **uNumOfEntries** member has a value greater than the value of **uDesiredSSIDListSize** that the driver previously returned through a query of [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md). In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_DESIRED\_SSID\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_SSID\_LIST structure, including all entries in the **SSIDs** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_SSID\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **SSIDs** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_SSID\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_SSID\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_SSID\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **SSIDs** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_SSID\_LIST structure. The miniport driver must also copy the entire DOT11\_SSID\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default for the **msDot11DesiredSSIDList** MIB object is an empty list with **uNumEntries** set to zero. The miniport driver must set this MIB object to its default whenever the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DESIRED_SSID_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-disassociate-peer-request.md b/windows-driver-docs-pr/network/oid-dot11-disassociate-peer-request.md new file mode 100644 index 0000000000..82d41e30d6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-disassociate-peer-request.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_DISASSOCIATE\_PEER\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_DISASSOCIATE\_PEER\_REQUEST +ms.assetid: d12e6374-bc2f-4302-b0ba-24d0b6687849 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DISASSOCIATE_PEER_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DISASSOCIATE\_PEER\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DISASSOCIATE\_PEER\_REQUEST object identifier (OID) requests that the miniport driver disassociate the NIC from a specified peer station with which the 802.11 station is associated. If the NIC has an association with the specified peer station, it must disassociate from the peer station as described in [Explicit Disassociation Operations](https://msdn.microsoft.com/library/windows/hardware/ff548876) and return a DOT11\_STATUS\_DISASSOCIATION status indication. If the NIC disassociates from all peer stations (when DOT11\_DISASSOCIATE\_PEER\_REQUEST. **PeerMacAddr** = 0xFF), it can return a single DOT11\_STATUS\_DISASSOCIATION status indication. + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_DISASSOCIATE\_PEER\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff547681) structure. + +When this OID is set, the NIC must behave as follows: + +- If the Extensible AP is in the INIT state, the NIC must fail the request and return a status indication of NDIS\_STATUS\_INVALID\_STATE. + +- If the Extensible AP is in the OP state, the NIC must complete the request if the peer station is in the association table. The NIC must enforce synchronization because the NIC could receive this request while the NIC is already associating or disassociating with a peer station. + +While the NIC is in the process of associating with a peer station, it will not receive this OID, but it can receive the reset request OID, OID\_DOT11\_RESET\_REQUEST. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_DISASSOCIATE\_PEER\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff547681) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DISASSOCIATE_PEER_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-disconnect-request.md b/windows-driver-docs-pr/network/oid-dot11-disconnect-request.md new file mode 100644 index 0000000000..f104a1b7d2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-disconnect-request.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_DISCONNECT\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_DISCONNECT\_REQUEST +ms.assetid: 89f46c68-1057-4998-86ee-b568eddfe8c2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DISCONNECT_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DISCONNECT\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_DISCONNECT\_REQUEST object identifier (OID) requests that the miniport driver perform a disconnection operation from the basic service set (BSS) network with which it is connected. + +No data is associated with this OID. + +When OID\_DOT11\_DISCONNECT\_REQUEST is set, the miniport driver must do the following: + +- If the 802.11 station is not connected to a BSS, fail the set request by returning NDIS\_STATUS\_INVALID\_STATE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 station is performing a connection operation initiated through a set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md), fail the set request by returning NDIS\_STATUS\_INVALID\_STATE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +- If the 802.11 station is connected to a BSS network, perform a disconnection operation from the BSS network. For more information about the disconnection operation, see [Disconnection Operations](https://msdn.microsoft.com/library/windows/hardware/ff546447). + +- The 802.11 station must not power the radio off. + +- The miniport driver must transition to the INIT state of the Extensible Station (ExtSTA) operation mode. For more information about operation modes and related states, see [Extensible Station Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff549887). + +- The 802.11 station must stay disconnected from any BSS network until the next set request of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md). + +When OID\_DOT11\_DISCONNECT\_REQUEST is set, the miniport driver can do one of the following: + +- Wait for the disconnection operation to complete before completing the set request. + +- Initiate the disconnection operation and complete the set request. The miniport driver must return NDIS\_STATUS\_PENDING from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the disconnection operation. After the disconnection operation has finished, the miniport driver completes the set request by calling [**NdisMRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622).The miniport driver also makes the NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION asynchronously after the set request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DISCONNECT_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-diversity-selection-rx.md b/windows-driver-docs-pr/network/oid-dot11-diversity-selection-rx.md new file mode 100644 index 0000000000..f6a3d78bb9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-diversity-selection-rx.md @@ -0,0 +1,123 @@ +--- +title: OID\_DOT11\_DIVERSITY\_SELECTION\_RX +author: windows-driver-content +description: When queried, the OID\_DOT11\_DIVERSITY\_SELECTION\_RX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 dot11DiversitySelectionRx management information base (MIB) object for the current PHY type on the 802.11 station. +ms.assetid: b5be9319-3702-4bda-8dfa-3c94da2b1a69 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DIVERSITY_SELECTION_RX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DIVERSITY\_SELECTION\_RX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DIVERSITY\_SELECTION\_RX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11DiversitySelectionRx** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the list of antennas on the current PHY type that are available for receive (RX) diversity operations. + +The data type for OID\_DOT11\_DIVERSITY\_SELECTION\_RX is the DOT11\_DIVERSITY\_SELECTION\_RX\_LIST. + +```ManagedCPlusPlus + typedef struct _DOT11_DIVERSITY_SELECTION_RX_LIST { + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_DIVERSITY_SELECTION_RX dot11DiversitySelectionRx[1]; + } DOT11_DIVERSITY_SELECTION_RX_LIST, *PDOT11_DIVERSITY_SELECTION_RX_LIST; + +``` + +This structure includes the following members: + +**uNumOfEntries** +Number of entries in the **dot11DiversitySelectionRx** array. A zero value for this member indicates an empty list. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11DiversitySelectionRx** array requires. + +**dot11DiversitySelectionRx** +The list of receive (RX) antennas that may be used for RX diversity operations. + +The data type for the elements of the **dot11DiversitySelectionRx** array is the DOT11\_DIVERSITY\_SELECTION\_RX structure. + +``` syntax +typedef struct _DOT11_DIVERSITY_SELECTION_RX { ULONG uAntennaListIndex; + BOOLEAN + bDiversitySelectionRX; } DOT11_DIVERSITY_SELECTION_RX,*PDOT11_DIVERSITY_SELECTION_RX; +``` + +This structure includes the following members: + +**uAntennaListIndex** +The antenna index. The value of **uAntennaListIndex** must be from 1 through 255. + +The antenna index value must match the index of a supported RX antenna previously specified by the miniport driver when queried by [OID\_DOT11\_SUPPORTED\_RX\_ANTENNA](oid-dot11-supported-rx-antenna.md). + +**bDiversitySelectionRX** +When set to **TRUE**, this indicates that the antenna represented by **uAntennaListIndex** can be used for receive diversity. + +When OID\_DOT11\_DIVERSITY\_SELECTION\_RX is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure, including all entries in the **dot11DiversitySelectionRx** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11DiversitySelectionRx** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure. The miniport driver must also copy the entire DOT11\_DIVERSITY\_SELECTION\_RX\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DIVERSITY_SELECTION_RX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-diversity-support.md b/windows-driver-docs-pr/network/oid-dot11-diversity-support.md new file mode 100644 index 0000000000..08180d36b5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-diversity-support.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_DIVERSITY\_SUPPORT +author: windows-driver-content +description: OID\_DOT11\_DIVERSITY\_SUPPORT +ms.assetid: 9e04f9cc-b638-45ac-a1a6-c099ae889018 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DIVERSITY_SUPPORT Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DIVERSITY\_SUPPORT + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DIVERSITY\_SUPPORT object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11DiversitySupport** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the type of antenna diversity supported by the current PHY type. + +The data type for OID\_DOT11\_DIVERSITY\_SUPPORT is the [**DOT11\_DIVERSITY\_SUPPORT**](https://msdn.microsoft.com/library/windows/hardware/ff547683) enumeration. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DIVERSITY_SUPPORT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-enabled.md b/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-enabled.md new file mode 100644 index 0000000000..61189e9192 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-enabled.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_DSSS\_OFDM\_OPTION\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_DSSS\_OFDM\_OPTION\_ENABLED +ms.assetid: 17d1b975-093d-4d82-bbb9-3f678e8e4ac8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DSSS_OFDM_OPTION_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DSSS\_OFDM\_OPTION\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DSSS\_OFDM\_OPTION \_ENABLED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11DSSSOFDMOptionEnabled** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11DSSSOFDMOptionEnabled** MIB object specifies whether the current PHY type has enabled the use of the hybrid DSSS-OFDM modulation. When the 802.11 station enables this option, the PHY combines the direct-sequence spread spectrum (DSSS) preamble and header with the orthogonal frequency division multiplexing (OFDM) payload. + +For more information about DSSS-OFDM modulation, refer to Clause 19.7 of the IEEE 802.11g-2003 standard. + +**Note**  Support for OID\_DOT11\_DSSS\_OFDM\_OPTION \_ENABLED is mandatory if the NIC supports the **dot11\_phy\_type\_erp** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_DSSS\_OFDM\_OPTION \_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type has enabled the DSSS-OFDM option. + +The **dot11DSSSOFDMOptionEnabled** MIB object is only valid for the Extended-rate PHY (ERP) type. If the current PHY type is not set to dot11\_phy\_type\_erp, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DSSS_OFDM_OPTION_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-implemented.md b/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-implemented.md new file mode 100644 index 0000000000..236ed4cea1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-dsss-ofdm-option-implemented.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_DSSS\_OFDM\_OPTION\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_DSSS\_OFDM\_OPTION\_IMPLEMENTED +ms.assetid: f8da0630-5f34-4ee6-8f0c-9404bb2e1ce5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DSSS_OFDM_OPTION_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DSSS\_OFDM\_OPTION\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DSSS\_OFDM\_OPTION\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11DSSSOFDMOptionImplemented** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11DSSSOFDMOptionImplemented** MIB object specifies whether the current PHY type has enabled the use of the hybrid DSSS-OFDM modulation. If the 802.11 station supports this option, the PHY is capable of combining the direct-sequence spread spectrum (DSSS) preamble and header with the orthogonal frequency division multiplexing (OFDM) payload. + +For more information about DSSS-OFDM modulation, refer to Clause 19.7 of the IEEE 802.11g-2003 standard. + +The data type for OID\_DOT11\_DSSS\_OFDM\_OPTION\_IMPLEMENTED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports the DSSS-OFDM option. + +The **dot11DSSSOFDMOptionImplemented** MIB object is only valid for the Extended-rate PHY (ERP) type. If the current PHY type is not set to **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DSSS_OFDM_OPTION_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-dtim-period.md b/windows-driver-docs-pr/network/oid-dot11-dtim-period.md new file mode 100644 index 0000000000..8f9183e405 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-dtim-period.md @@ -0,0 +1,63 @@ +--- +title: OID\_DOT11\_DTIM\_PERIOD +author: windows-driver-content +description: OID\_DOT11\_DTIM\_PERIOD +ms.assetid: 32690679-e806-4644-b163-7e7b6c494e1d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_DTIM_PERIOD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_DTIM\_PERIOD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_DTIM\_PERIOD object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11DTIMPeriod** management information base (MIB) object for the current PHY type on the 802.11 station. + +When set, this OID requests that the miniport driver set the value of **dot11DTIMPeriod**. + +The **dot11DTIMPeriod** MIB object specifies the number of beacon intervals between transmissions of beacon frames that contain a TIM element with a DTIM Count field that equals zero. This value is transmitted in the DTIM Period field of beacon frames. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_DTIM_PERIOD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ed-threshold.md b/windows-driver-docs-pr/network/oid-dot11-ed-threshold.md new file mode 100644 index 0000000000..704b89d320 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ed-threshold.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_ED\_THRESHOLD +author: windows-driver-content +description: OID\_DOT11\_ED\_THRESHOLD +ms.assetid: 7cdccb9b-e12d-44c3-8149-64007d0da59a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ED_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ED\_THRESHOLD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ED\_THRESHOLD object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11EDThreshold** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the energy detect (ED) threshold of the current PHY type. The PHY uses the ED threshold to determine when it has detected sufficient energy in order to enable receive operations. + +For more information about the ED threshold, refer to Clause 16.4.5.14 of the IEEE 802.11-2012 standard and Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +The data type for OID\_DOT11\_ED\_THRESHOLD is a ULONG value that specifies the ED threshold in units of dBm. + +The **dot11EDThreshold** MIB object is only valid for the following PHY types: + +- Direct-sequence spread spectrum (DSSS) PHY. + +- High-rate DSSS (HRDSSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_dsss**, **dot11\_phy\_type\_hrdsss**, or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ED_THRESHOLD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-enabled.md b/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-enabled.md new file mode 100644 index 0000000000..c5692a65e7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-enabled.md @@ -0,0 +1,87 @@ +--- +title: OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED +ms.assetid: 3c930dd2-3351-4c3d-911c-8e4aabd1ac91 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EHCC_CAPABILITY_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11EHCCCapabilityEnabled** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the frequency-hopping spread spectrum (FHSS) PHY is capable of enabling the hyperbolic congruence codes (HCC) or extended hyperbolic congruence codes (EHCC) algorithms to generate hopping patterns. For more information about the HCC/EHCC algorithms, refer to Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +This MIB object does not explicitly enable the use of these algorithms. The IEEE 802.11d **dot11HopAlgorithmAdopted** MIB object enables or disables the use of these algorithms to generate hopping patterns. For more information about the **dot11HopAlgorithmAdopted** MIB object, see [OID\_DOT11\_HOP\_ALGORITHM\_ADOPTED](oid-dot11-hop-algorithm-adopted.md). + +**Note**  Support for OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type is capable of enabling the HCC/EHCC algorithms. + +When queried by OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED, the miniport driver fails the request under the following conditions: + +- The **dot11EHCCCapabilityEnabled** MIB object is valid for only the FHSS PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EHCC_CAPABILITY_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-implemented.md b/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-implemented.md new file mode 100644 index 0000000000..1e8d577440 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ehcc-capability-implemented.md @@ -0,0 +1,85 @@ +--- +title: OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED +ms.assetid: 59adb057-2b9e-4b0f-9949-ff94d84a6ae4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11EHCCCapabilityImplemented** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the frequency-hopping spread spectrum (FHSS) PHY is capable of generating hopping patterns through the hyperbolic congruence codes (HCC) or extended hyperbolic congruence codes (EHCC) algorithms. For more information about the HCC/EHCC algorithms, refer to Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +**Note**  Support for OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED is a BOOLEAN value. A value of **TRUE** indicates that the FHSS PHY supports the HCC/EHCC algorithms. + +When queried by OID\_DOT11\_EHCC\_CAPABILITY\_IMPLEMENTED, the miniport driver must fail the request under the following conditions: + +- The **dot11EHCCCapabilityImplemented** MIB object is valid for only the FHSS PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ehcc-number-of-channels-family-index.md b/windows-driver-docs-pr/network/oid-dot11-ehcc-number-of-channels-family-index.md new file mode 100644 index 0000000000..0b81ad0cfd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ehcc-number-of-channels-family-index.md @@ -0,0 +1,91 @@ +--- +title: OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX +author: windows-driver-content +description: OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX +ms.assetid: bbaaa263-f1d8-432d-8d7c-c6f294f1b2f1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11EHCCNumberOfChannelsFamilyIndex** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the maximum value of the family index in the hyperbolic congruence codes (HCC) or extended hyperbolic congruence codes (EHCC) algorithms. A family index is an index within the code families generated by these algorithms. The frequency-hopping spread spectrum (FHSS) PHY generates its hopping patterns through these algorithms. + +For more information about the HCC/EHCC algorithms, refer to Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +**Note**  Support for OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_EHCC\_CAPABILITY\_ENABLED is a ULONG value. + +The value of the **dot11EHCCNumberOfChannelsFamilyIndex** MIB object depends on the value of the IEEE 802.11d **dot11EHCCPrimeRadix** MIB object and must be from ( **dot11EHCCPrimeRadix**- 1) through ( **dot11EHCCPrimeRadix**- 3). + +For more information about the **dot11EHCCPrimeRadix** MIB object, see [OID\_DOT11\_EHCC\_PRIME\_RADIX](oid-dot11-ehcc-prime-radix.md). + +When queried by OID\_DOT11\_EHCC\_NUMBER\_OF\_CHANNELS\_FAMILY\_INDEX, the miniport driver fails the request under the following conditions: + +- The **dot11EHCCNumberOfChannelsFamilyIndex** MIB object is valid for only the FHSS PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ehcc-prime-radix.md b/windows-driver-docs-pr/network/oid-dot11-ehcc-prime-radix.md new file mode 100644 index 0000000000..6a0d14e136 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ehcc-prime-radix.md @@ -0,0 +1,87 @@ +--- +title: OID\_DOT11\_EHCC\_PRIME\_RADIX +author: windows-driver-content +description: OID\_DOT11\_EHCC\_PRIME\_RADIX +ms.assetid: bc561b41-8ab6-4e6b-889a-701b681f3f7d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EHCC_PRIME_RADIX Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EHCC\_PRIME\_RADIX + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_EHCC\_PRIME\_RADIX object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11EHCCPrimeRadix** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11EHCCPrimeRadix** MIB object specifies the prime radix value for the hyperbolic congruence codes (HCC) or extended hyperbolic congruence codes (EHCC) algorithms. The frequency-hopping spread spectrum (FHSS) PHY generates its hopping patterns through these algorithms. + +For more information about the HCC/EHCC algorithms, refer to Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +**Note**  Support for OID\_DOT11\_EHCC\_PRIME\_RADIX is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_EHCC\_PRIME\_RADIX is a ULONG value. + +When queried by OID\_DOT11\_EHCC\_PRIME\_RADIX, the miniport driver must fail the request under the following conditions: + +- The **dot11EHCCPrimeRadix** MIB object is valid for only the FHSS PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EHCC_PRIME_RADIX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enabled-authentication-algorithm.md b/windows-driver-docs-pr/network/oid-dot11-enabled-authentication-algorithm.md new file mode 100644 index 0000000000..2a4cdf10d7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enabled-authentication-algorithm.md @@ -0,0 +1,188 @@ +--- +title: OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM +author: windows-driver-content +description: When set, the OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) msDot11EnabledAuthAlgo management information base (MIB) object to the specified data. +ms.assetid: d3c262b0-1b04-4a98-be2d-baae4abbd58f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) **msDot11EnabledAuthAlgo** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11EnabledAuthAlgo** MIB object. + +The **msDot11EnabledAuthAlgo** MIB object defines the list of authentication algorithms the 802.11 station has enabled for use when connecting to a basic service set (BSS) network. After [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station will attempt to connect to a BSS whose 802.11 Beacon or Probe Response frames specify support for an authentication algorithm defined by an entry within the **msDot11EnabledAuthAlgo** MIB object. + +The data type for OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM is the DOT11\_AUTH\_ALGORITHM\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_AUTH_ALGORITHM_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_AUTH_ALGORITHM AlgorithmIds[1]; + } DOT11_AUTH_ALGORITHM_LIST, *PDOT11_AUTH_ALGORITHM_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_AUTH\_ALGORITHM\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_AUTH\_ALGORITHM\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_AUTH\_ALGORITHM\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **AlgorithmIds** array. A zero value for this member indicates an empty list. + +**uTotalNumOfEntries** +Maximum number of entries that the **AlgorithmIds** array can contain. + +**AlgorithmIds** +The authentication algorithm list, with each entry specified by a [**DOT11\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547655) enumerator value. + +The list of authentication algorithms is sorted by preference. **AlgorithmIds\[0\]** specifies the authentication algorithm with the highest preference. + +The Microsoft 802.1X supplicant enables only one standard 802.11 authentication algorithm. However, a supplicant developed by the independent hardware vendor (IHV) can enable one or more authentication algorithms. For more information about 802.1X supplicants, refer to the IEEE 802.1X-2001 standard. + +The 802.11 station uses the list of authentication algorithms when performing a connection operation to a BSS network. Depending on the authentication algorithms supported by the BSS (as advertised in the 802.11 Beacon or Probe Response frames), the following apply to the 802.11 station: + +- If none of the advertised authentication algorithms matches an algorithm from its list, the 802.11 station cannot connect to the BSS network. + +- If the BSS advertises one or more authentication algorithm that match algorithms from its list, the 802.11 station must connect to the BSS using the most preferred algorithm from the intersection of the advertised algorithms with its list. For example, if the Beacon frame advertises authentication algorithms that match **AlgorithmIds\[0\]** and **AlgorithmIds\[3\]**, the station must connect to the BSS using **AlgorithmIds\[0\]**. + +For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +When OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM is set, the miniport driver must do the following: + +- If **uNumOfEntries** is set to zero, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. The **msDot11EnabledAuthAlgo** MIB object must always contain at least one entry. + +- If the 802.11 station does not support any of the authentication algorithms in the specified list, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function. + +- Reload the default values for the enabled unicast cipher algorithms for each authentication algorithm in the specified list. For more information about the default values for unicast cipher algorithms, see [OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md). + +- Reload the default values for the enabled multicast cipher algorithms for each authentication algorithm in the specified list. For more information about the default values for multicast cipher algorithms, see [OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md). + +- Disable any authentication algorithms that are not in the specified list. + +- Ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + + ``` + FIELD_OFFSET(DOT11_AUTH_ALGORITHM_LIST, AlgorithmIds) + uNumOfEntries * sizeof(DOT11_AUTH_ALGORITHM)) + ``` + +When OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_AUTH\_ALGORITHM\_LIST structure, including all entries in the **AlgorithmIds** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_AUTH\_ALGORITHM\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **AlgorithmIds** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_AUTH\_ALGORITHM\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_AUTH\_ALGORITHM\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_AUTH\_ALGORITHM\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **AlgorithmIds** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_AUTH\_ALGORITHM\_LIST structure. The miniport driver must also copy the entire DOT11\_AUTH\_ALGORITHM\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The miniport driver must define a default authentication algorithm from its supported algorithms based on the following: + +- If the desired BSS type is **dot11\_BSS\_type\_infrastructure**, the miniport driver must choose the default authentication algorithm based on the following order of preference: + + **DOT11\_AUTH\_ALGO\_RSNA**(highest preference) + + **DOT11\_AUTH\_ALGO\_WPA** + + **DOT11\_AUTH\_ALGO\_RSNA\_PSK** + + **DOT11\_AUTH\_ALGO\_WPA\_PSK** + + **DOT11\_AUTH\_ALGO\_80211\_OPEN** + + **DOT11\_AUTH\_ALGO\_80211\_SHARED\_KEY**(lowest preference) + +- If the desired BSS type is **dot11\_BSS\_type\_independent**, the miniport driver must choose the default authentication algorithm based on the following preference order: + + **DOT11\_AUTH\_ALGO\_RSNA\_PSK**(highest preference) + + **DOT11\_AUTH\_ALGO\_80211\_OPEN** + + **DOT11\_AUTH\_ALGO\_80211\_SHARED\_KEY**(lowest preference) + +- If the 802.11 station supports one or more vendor-defined authentication algorithms, the miniport driver must select the most preferred vendor algorithm as its default authentication algorithm. + +The miniport driver must set the **msDot11EnabledAuthAlgo** MIB object to the default authentication algorithm whenever the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +- A set request of [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md) is made. + +**Note**  Beginning in Windows 7, the operating system enables only one authentication algorithm at a time. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enabled-multicast-cipher-algorithm.md b/windows-driver-docs-pr/network/oid-dot11-enabled-multicast-cipher-algorithm.md new file mode 100644 index 0000000000..c55e590d11 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enabled-multicast-cipher-algorithm.md @@ -0,0 +1,115 @@ +--- +title: OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM +author: windows-driver-content +description: OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM +ms.assetid: c661d254-8614-4282-9887-c7806a4f1606 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENABLED_MULTICAST_CIPHER_ALGORITHM Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) **msDot11EnabledMulticastCipherAlgo** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11EnabledMulticastCipherAlgo** MIB object. + +The **msDot11EnabledMulticastCipherAlgo** MIB object specifies the list of multicast cipher algorithms that the 802.11 station enables for use when connecting to a basic service set (BSS) network. After [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station will attempt to connect to a BSS whose 802.11 Beacon or Probe Response frames specify support for a multicast cipher algorithm defined by an entry within the **msDot11EnabledMulticastCipherAlgo** MIB object. + +**Note**  Support for this OID is mandatory if the 802.11 station supports any multicast cipher algorithms. The miniport driver returns a list of supported multicast cipher algorithms when [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) is queried. + +  + +The data type for this OID is the [**DOT11\_CIPHER\_ALGORITHM\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547673) structure. + +When OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM is set, the miniport driver must do the following: + +- If the **uNumOfEntries** member of the DOT11\_CIPHER\_ALGORITHM\_LIST structure is set to zero, fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. The **msDot11EnabledMulticastCipherAlgo** MIB object must always contain at least one entry. + +- If the 802.11 station does not support a specified multicast cipher algorithm, return NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function. + +- If the 802.11 station does not support any of the specified multicast cipher algorithms for any of the enabled authentication algorithms defined by the ExtSTA **msDot11EnabledAuthAlgo** MIB object, return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **msDot11EnabledAuthAlgo** MIB object, see [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md). + +- Enable the specified multicast cipher algorithms for any enabled authentication algorithm that supports the cipher. + +- Disable all supported multicast cipher algorithms that are not in the specified list. + +- Ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + + ``` + FIELD_OFFSET(DOT11_CIPHER_ALGORITHM_LIST, AlgorithmIds) + uNumOfEntries * sizeof(DOT11_CIPHER_ALGORITHM)) + ``` + +When OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM is queried, the miniport driver must do the following: + +- If this OID was previously set, returns the list of multicast cipher algorithms in the same order as they were set. + +- If OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM was not previously set, returns its default multicast ciphers in the list. + +- The miniport driver cannot return an empty list of multicast cipher algorithms. If the 802.11 station has not enabled any multicast cipher algorithms, the miniport driver must return a list containing DOT11\_CIPHER\_ALGO\_NONE. + +The default value for the **msDot11EnabledMulticastCipherAlgo** MIB object is the list of multicast ciphers supported by the enabled authentication algorithms specified by the **msDot11EnabledAuthAlgo** MIB object. The default multicast cipher list must be ordered by preference. For more information about cipher preference, see [**DOT11\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547672). + +The miniport driver must set the **msDot11EnabledMulticastCipherAlgo** MIB object to the default multicast cipher if the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +- The **msDot11EnabledAuthAlgo** MIB object is changed in response to a set request of the [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md) OID. + +The following points describe set requests of OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM by the operating system: + +- The operating system might not always issue a set request of OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM. In this case, the 802.11 station should use the default multicast cipher during any connection or roam operations. For more information about these operations, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185) and [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +- If the operating system issues a set request of OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM, it will precede a set request of [OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md). + +**Note**  Beginning in Windows 7, the operating system enables only one cipher algorithm at a time. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENABLED_MULTICAST_CIPHER_ALGORITHM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enabled-unicast-cipher-algorithm.md b/windows-driver-docs-pr/network/oid-dot11-enabled-unicast-cipher-algorithm.md new file mode 100644 index 0000000000..c0d2b7c71a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enabled-unicast-cipher-algorithm.md @@ -0,0 +1,112 @@ +--- +title: OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM +author: windows-driver-content +description: OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM +ms.assetid: e8ab5623-2021-499c-a324-6b2b47905e88 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENABLED_UNICAST_CIPHER_ALGORITHM Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11EnabledUnicastCipherAlgo** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11EnabledUnicastCipherAlgo** MIB object. + +The **msDot11EnabledUnicastCipherAlgo** MIB object specifies the list of unicast cipher algorithms that the 802.11 station enables for use when connecting to a basic service set (BSS) network. After [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station will attempt to connect to a BSS whose 802.11 Beacon or Probe Response frames specify support for a unicast cipher algorithm defined by an entry within the **msDot11EnabledUnicastCipherAlgo** MIB object. + +**Note**   +Support for OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM is mandatory if the 802.11 station supports any unicast cipher algorithms. The miniport driver returns a list of supported unicast cipher algorithms when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) is queried. + +  + +The data type for this OID is the [**DOT11\_CIPHER\_ALGORITHM\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547673) structure. + +When OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM is set, the miniport driver must do the following: + +- The **msDot11EnabledUnicastCipherAlgo** MIB object must always contain at least one entry. If the **uNumOfEntries** member of the DOT11\_CIPHER\_ALGORITHM\_LIST structure is set to zero, the miniport driver must fail the set request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 station does not support a specified unicast cipher algorithm, return NDIS\_STATUS\_INVALID\_DATA from its *MiniportOidRequest* function. + +- If the 802.11 station does not support any of the specified unicast cipher algorithms for any of the enabled authentication algorithms defined by the ExtSTA **msDot11EnabledAuthAlgo** MIB object, return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **msDot11EnabledAuthAlgo** MIB object, see [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md). + +- Enable the specified unicast cipher algorithms for every enabled authentication algorithm that supports it. + +- Disable all supported unicast cipher algorithms that are not in the specified list. + +- Ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + + ``` + FIELD_OFFSET(DOT11_CIPHER_ALGORITHM_LIST, AlgorithmIds) + uNumOfEntries * sizeof(DOT11_CIPHER_ALGORITHM)) + ``` + +The Microsoft 802.1X supplicant enables only one standard 802.11 unicast cipher algorithm. However, a supplicant provided by the independent hardware vendor (IHV) can enable one or more unicast cipher authentication algorithms. For more information about 802.1X supplicants, refer to the IEEE 802.1X-2001 standard. + +When OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM is queried, the miniport driver must do the following: + +- If this OID was previously set, returns the list of unicast cipher algorithms in the same order as they were set. + +- If this OID was not previously set, returns its default unicast cipher algorithms in the list. + +- The miniport driver cannot return an empty list of unicast cipher algorithms. If the 802.11 station has not enabled any unicast cipher algorithms, the miniport driver must return a list containing **DOT11\_CIPHER\_ALGO\_NONE**. + +The default value for the **msDot11EnabledUnicastCipherAlgo** MIB object is the list of unicast ciphers supported by the authentication algorithms specified by the **msDot11EnabledAuthAlgo** MIB object. The default unicast cipher list must be ordered by preference. For more information about cipher preference, see [**DOT11\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547672). + +The miniport driver must set the **msDot11EnabledUnicastCipherAlgo** MIB object to the default multicast cipher whenever the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +- The **msDot11EnabledAuthAlgo** MIB object is changed in response to a set of [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md). + +**Note**  Beginning in Windows 7, the operating system enables only one cipher algorithm at a time. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENABLED_UNICAST_CIPHER_ALGORITHM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enum-association-info.md b/windows-driver-docs-pr/network/oid-dot11-enum-association-info.md new file mode 100644 index 0000000000..7487ed12c2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enum-association-info.md @@ -0,0 +1,197 @@ +--- +title: OID\_DOT11\_ENUM\_ASSOCIATION\_INFO +author: windows-driver-content +description: When queried, the OID\_DOT11\_ASSOCIATION\_INFO object identifier (OID) requests that the miniport driver return a list of the access point (AP) (for infrastructure basic service set (BSS) networks) or all peer stations (for independent BSS (IBSS) networks) with which the 802.11 station is associated. +ms.assetid: 1aba29c6-bea9-41a1-b530-4df248f19821 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENUM_ASSOCIATION_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENUM\_ASSOCIATION\_INFO + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ASSOCIATION\_INFO object identifier (OID) requests that the miniport driver return a list of the access point (AP) (for infrastructure basic service set (BSS) networks) or all peer stations (for independent BSS (IBSS) networks) with which the 802.11 station is associated. + +The data type for this OID is the DOT11\_ASSOCIATION\_INFO\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_ASSOCIATION_INFO_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_ASSOCIATION_INFO_EX dot11AssocInfo[1]; + } DOT11_ASSOCIATION_INFO_LIST, *PDOT11_ASSOCIATION_INFO_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_ASSOCIATION\_INFO\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_ASSOCIATION\_INFO\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_ASSOCIATION\_INFO\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **dot11AssocInfo** array. A zero value for this member indicates an empty list. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11AssocInfo** array can contain. + +**dot11AssocInfo** +The association information list. + +The data type for the entries in the **dot11AssocInfo** array is the DOT11\_ASSOCIATION\_INFO\_EX structure. + +``` syntax +typedef struct DOT11_ASSOCIATION_INFO_EX { + DOT11_MAC_ADDRESS PeerMacAddress; + DOT11_MAC_ADDRESS BSSID; + USHORT usCapabilityInformation; + USHORT usListenInterval; + UCHAR ucPeerSupportedRates[MAX_NUM_SUPPORTED_RATES_V2]; + USHORT usAssociationID; + DOT11_ASSOCIATION_STATE dot11AssociationState; + DOT11_POWER_MODE dot11PowerMode; + LARGE_INTEGER liAssociationUpTime; + ULONGLONG ullNumOfTxPacketSuccesses; + ULONGLONG ullNumOfTxPacketFailures; + ULONGLONG ullNumOfRxPacketSuccesses; + ULONGLONG ullNumOfRxPacketFailures; + } DOT11_ASSOCIATION_INFO_EX, *PDOT11_ASSOCIATION_INFO_EX; +``` + +This structure includes the following members: + +**PeerMacAddress** +The MAC address of the AP or peer station. + +**BSSID** +The BSS identifier (BSSID). The BSSID is one of the following: + +- The MAC address of the AP. + +- The BSSID of the IBSS network that the peer station is connected to. + +**usCapabilityInformation** +The 802.11 Capability Information field from the Beacon or Probe Response frames that the 802.11 station most recently received from the peer. + +**usListenInterval** +The 802.11 Listen Interval field from the Association Request or Reassociation Request frames the 802.11 station sent to the AP. + +If the desired BSS type is **dot11\_BSS\_type\_independent**, the miniport driver must set this member to zero. + +**ucPeerSupportedRates** +The data rates supported by the AP or peer station. These rates are based on the 802.11 Supported Rates IE from the Beacon or Probe Response frames that the 802.11 station most recently received from the peer. + +Each entry in the **ucPeerSupportedRates** array is the value of an index within the table of data rates returned through a query of [OID\_DOT11\_DATA\_RATE\_MAPPING\_TABLE](oid-dot11-data-rate-mapping-table.md). The index value must be between 2 and 127. + +**usAssociationID** +The 802.11 Association ID field from the Association or Reassociation Response frames that the 802.11 station received from the AP. + +If the desired BSS type is **dot11\_BSS\_type\_independent**, the miniport driver must set this member to zero. + +**dot11AssociationState** +The 802.11 authentication and association state of the peer. This member can have one of the values of the [**DOT11\_ASSOCIATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff547650) enumeration. + +If the desired BSS type is **dot11\_BSS\_type\_independent**, the miniport driver must not set this member to **dot11\_assoc\_state\_auth\_assoc**. Since the 802.11 authentication procedure is optional for IBSSs, the miniport driver might set this member to **dot11\_assoc\_state\_unauth\_unassoc** even though it is connected to an IBSS network. + +**dot11PowerMode** +Power management mode of the peer. For more information about this structure, see [**DOT11\_POWER\_MODE**](https://msdn.microsoft.com/library/windows/hardware/ff548755). + +If the desired BSS type is **dot11\_BSS\_type\_infrastructure**, the miniport driver must set this member to **dot11\_power\_mode\_active**. + +**liAssociationUpTime** +The timestamp when the 802.11 association procedure successfully completed. The miniport driver calls [**NdisGetCurrentSystemTime**](https://msdn.microsoft.com/library/windows/hardware/ff562629) to get the timestamp of the association completion. + +If the desired BSS type is **dot11\_BSS\_type\_independent**, the miniport driver must set this member to zero. + +**ullNumOfTxPacketSuccesses** +The number of 802.11 MAC protocol data unit (MPDU), management MPDU (MMPDU), and control frames successfully transmitted to the peer. + +**ullNumOfTxPacketFailures** +The number of 802.11 MPDU, MMPDU, and control frames that failed during transmission to the peer. + +**ullNumOfRxPacketSuccesses** +The number of 802.11 MPDU, MMPDU, and control frames successfully received from the peer. + +**ullNumOfRxPacketFailures** +The number of 802.11 MPDU, MMPDU, and control frames that the 802.11 failed to receive from the peer. This counter must include packets that the 802.11 station received successfully but failed to decrypt. + +If the desired BSS type is **dot11\_BSS\_type\_infrastructure**, the association information list must contain DOT11\_ASSOCIATION\_INFO\_EX data for only the AP with which the 802.11 station is associated. If the 802.11 station is not associated, the miniport driver must return an empty list and set the **uNumOfEntries** member to zero. + +If the desired BSS type is **dot11\_BSS\_type\_independent**, the association information list must contain DOT11\_ASSOCIATION\_INFO\_EX data for every peer station in the IBSS with which the 802.11 station has connected. + +When OID\_DOT11\_ASSOCIATION\_INFO is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_ASSOCIATION\_INFO\_LIST structure, including all entries in the **dot11AssocInfo** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_ASSOCIATION\_INFO\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **dot11AssocInfo** array. + + For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_ASSOCIATION\_INFO\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_ASSOCIATION\_INFO\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_ASSOCIATION\_INFO\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11AssocInfo** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_ASSOCIATION\_INFO\_LIST structure. The miniport driver must also copy the entire DOT11\_ASSOCIATION\_INFO\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENUM_ASSOCIATION_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enum-bss-list.md b/windows-driver-docs-pr/network/oid-dot11-enum-bss-list.md new file mode 100644 index 0000000000..855d9148e9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enum-bss-list.md @@ -0,0 +1,110 @@ +--- +title: OID\_DOT11\_ENUM\_BSS\_LIST +author: windows-driver-content +description: OID\_DOT11\_ENUM\_BSS\_LIST +ms.assetid: eaf6f81f-f420-4027-a45d-3c935c1b8b07 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENUM_BSS_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENUM\_BSS\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When a method request of the OID\_DOT11\_ENUM\_BSS\_LIST OID is made, the miniport driver must return a list of the basic service set (BSS) networks within range of the 802.11 station. For more information about the method request type, see [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710). + +The miniport driver derives this list from the cache of BSS networks that the 802.11 station detected during the most recent scan operation. For more information about scan operations, see [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + +When the method request of OID\_DOT11\_ENUM\_BSS\_LIST is made through a call to the miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function, the **InformationBuffer** member of the *OidRequest* parameter contains a three-character country string as defined in the IEEE 802.11d-2001 standard. For more information about country strings, see [OID\_DOT11\_COUNTRY\_STRING](oid-dot11-country-string.md). + +The miniport driver completes the method request by overwriting the **InformationBuffer** member with a [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure. The miniport driver sets the members of this structure as follows: + +**Header** +The type and size of the DOT11\_BYTE\_ARRAY structure and the revision of the [**DOT11\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff547665) structures that follow it. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_BSS\_ENTRY\_BYTE\_ARRAY\_REVISION\_1. + +**Size** +This member must be set to `sizeof(DOT11_BYTE_ARRAY)`. + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfBytes** +Number of bytes within the **ucBuffer** array. A zero value for this member indicates an empty BSS list. + +**uTotalNumOfBytes** +Maximum number of bytes that the **ucBuffer** array requires. + +**ucBuffer** +The BSS list. + +Each entry in the BSS list is formatted as a [**DOT11\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff547665) structure. + +When this OID is queried, the miniport driver must do the following: + +- Verify that the **InformationBuffer** member of its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the BSS list. For more information about this procedure, see [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670). + +- The [**DOT11\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/ff547665) structure has a variable length. However, the miniport driver must not add padding for alignment between DOT11\_BSS\_ENTRY structures returned in the **InformationBuffer** member of the *OidRequest* parameter. + +- Use the following formula for calculating the values of the **uNumOfBytes** and **uTotalNumOfBytes** members of the [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure: + + ``` + FIELD_OFFSET(DOT11_BSS_ENTRY, ucBuffer) + uBufferLength + ``` + +- If the 802.11 station is connected to an infrastructure BSS network, include an entry in the BSS list for the AP with which the 802.11 station is currently associated. The DOT11\_BSS\_ENTRY entry must reflect the last 802.11 Beacon or Probe Response frame received from the AP, regardless of whether these frames were received when the Native 802.11 miniport driver was performing the scan operation. + +If an 802.11n PHY is used to detect the BSS network, the miniport driver should perform the following operations. + +- Set the **uPhyId** member of DOT11\_BSS\_ENTRY to the **dot11\_phy\_type\_ht** value. + +- Set the DOT11\_BSS\_ENTRY-> **PhySpecificInfo** -> **uChCenterFrequency** member to the appropriate channel center frequency, in MHz. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENUM_BSS_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-enum-peer-info.md b/windows-driver-docs-pr/network/oid-dot11-enum-peer-info.md new file mode 100644 index 0000000000..704d9afcde --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-enum-peer-info.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_ENUM\_PEER\_INFO +author: windows-driver-content +description: OID\_DOT11\_ENUM\_PEER\_INFO +ms.assetid: d836f261-b335-4284-9d5b-79ebb9943a02 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ENUM_PEER_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ENUM\_PEER\_INFO + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ENUM\_PEER\_INFO object identifier (OID) requests that the miniport driver return information on all peer stations within an infrastructure basic service set (BSS) network. The miniport driver must fill in the members of a DOT11\_PEER\_INFO\_LIST structure. + +**Note**  Support for this OID is mandatory. + +  + +The data type for this OID is the [**DOT11\_PEER\_INFO\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548719) structure. + +The miniport driver must also verify that the input buffer is large enough to hold all the data in the DOT11\_PEER\_INFO\_LIST structure. + +If the input buffer is not large enough, in the call to the NDIS [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function, set *OidRequest* . **Data** . **BytesNeeded** to the number of bytes required and return the status indication NDIS\_STATUS\_INVALID\_LENGTH so that the 802.11 framework can allocate a buffer of sufficient size before it makes the next function call. + +If the input buffer is large enough to hold all the data in the DOT11\_PEER\_INFO\_LIST structure, the miniport driver must return a list of [**DOT11\_PEER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff548713) structures and set *OidRequest*.**Data**.**BytesNeeded** to the number of bytes that the miniport driver returns. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ENUM_PEER_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-enabled.md b/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-enabled.md new file mode 100644 index 0000000000..564411f074 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-enabled.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED +ms.assetid: 2a8c7402-402e-4c47-9917-121b6b19a241 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ERP_PBCC_OPTION_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11ERPBCCOptionEnabled** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the Extended-rate PHY (ERP) has enabled packet binary convolutional code (PBCC) modulation. + +For more information about PBCC modulation, refer to Clause 18.4.6.6 of the IEEE 802.11b-1999 standard. For more information about the ERP-PBCC option, refer to Clause 19.6 of the IEEE 802.11g-2003 standard. + +**Note**  Support for OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED is mandatory if the NIC supports the **dot11\_phy\_type\_erp** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_ERP\_PBCC\_OPTION\_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type has enabled PBCC modulation. + +The **dot11ERPBCCOptionEnabled** MIB object is valid for only the ERP PHY type. If the current PHY type is not set to **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ERP_PBCC_OPTION_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-implemented.md b/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-implemented.md new file mode 100644 index 0000000000..aa75368790 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-erp-pbcc-option-implemented.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_ERP\_PBCC\_OPTION\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_ERP\_PBCC\_OPTION\_IMPLEMENTED +ms.assetid: 60e9737e-a97b-4d25-afa0-50d93aef773c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_ERP\_PBCC\_OPTION\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_ERP\_PBCC\_OPTION\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11ERPPBCCOptionImplemented** MIB object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the Extended-rate PHY (ERP) supports enabled packet binary convolutional code (PBCC) modulation. + +For more information about PBCC modulation, refer to Clause 18.4.6.6 of the IEEE 802.11b-1999 standard. For more information about the ERP-PBCC option, refer to Clause 19.6 of the IEEE 802.11g-2003 standard. + +The data type for OID\_DOT11\_ERP\_PBCC\_OPTION\_IMPLEMENTED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports PBCC modulation. + +The **dot11ERPPBCCOptionImplemented** MIB object is valid for only the ERP PHY type. If the current PHY type is not set to **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-exclude-unencrypted.md b/windows-driver-docs-pr/network/oid-dot11-exclude-unencrypted.md new file mode 100644 index 0000000000..ea242ad4d7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-exclude-unencrypted.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_EXCLUDE\_UNENCRYPTED +author: windows-driver-content +description: OID\_DOT11\_EXCLUDE\_UNENCRYPTED +ms.assetid: 51a6563d-9e9d-4156-9f7a-b2892f4b7c25 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EXCLUDE_UNENCRYPTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EXCLUDE\_UNENCRYPTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_EXCLUDE\_UNENCRYPTED OID requests that the miniport driver set the IEEE 802.11 **dot11ExcludeUnencrypted** management information base (MIB) object. + +When queried, this OID requests that the miniport driver return the setting of the **dot11ExcludeUnencrypted** MIB object. + +The **dot11ExcludeUnencrypted** MIB object specifies how the 802.11 station handles received packets with unencrypted payload data. + +**Note**  Support for OID\_DOT11\_EXCLUDE\_UNENCRYPTED is mandatory if the 802.11 station supports any cipher algorithms. The miniport driver returns a list of supported cipher algorithms when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for this OID is a BOOLEAN value. + +The **dot11ExcludeUnencrypted** MIB object defines the following actions: + +- If **dot11ExcludeUnencrypted** is **TRUE**, then the 802.11 station must discard any received unicast packets in which the Protected Frame subfield of the Frame Control field in the 802.11 MAC header is set to zero. + +- If **dot11ExcludeUnencrypted** is **FALSE**, then the 802.11 station can accept these packets and indicate them to the operating system. + +When **dot11ExcludeUnencrypted** is **FALSE**, the miniport driver must connect to an access point (AP) with a Wired Equivalent Privacy (WEP) profile, even if the AP does not set the privacy field in the relevant management frames. + +The actions defined by the **dot11ExcludeUnencrypted** MIB object do not apply to received packets that match an entry in the 802.11 station's current EtherType exemption list. For more information about the EtherType exemption list, see [OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST](oid-dot11-privacy-exemption-list.md). + +The default setting for the **dot11ExcludeUnencrypted** MIB object is **FALSE**. The miniport driver must set the MIB object to this default through its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function or when reset through [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EXCLUDE_UNENCRYPTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-excluded-mac-address-list.md b/windows-driver-docs-pr/network/oid-dot11-excluded-mac-address-list.md new file mode 100644 index 0000000000..f2eb0b1812 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-excluded-mac-address-list.md @@ -0,0 +1,146 @@ +--- +title: OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) msDot11ExcludedMacAddressList management information base (MIB) object to the specified data. +ms.assetid: ef2e3313-576b-4072-aba4-a940e50b0a5c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST object identifier (OID) requests that the miniport driver set the value of the Extensible Station (ExtSTA) **msDot11ExcludedMacAddressList** management information base (MIB) object to the specified data. + +When queried, OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST requests that the miniport driver return the value of the **msDot11ExcludedMacAddressList** MIB object. + +The **msDot11ExcludedMacAddressList** MIB object specifies the list of media access control (MAC) addresses of remote stations that the 802.11 station must not connect to. When [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md) is set, the 802.11 station must attempt to connect with any remote station, such as an access point (AP) in an infrastructure basic service set (BSS) network or peer station in an independent BSS (IBSS) network, that does not have a MAC address within the excluded MAC address list. + +The data type for OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST is the DOT11\_MAC\_ADDRESS\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_MAC_ADDRESS_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_MAC_ADDRESS MacAddrs[1]; + } DOT11_MAC_ADDRESS_LIST, *PDOT11_MAC_ADDRESS_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_MAC\_ADDRESS\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_MAC\_ADDRESS\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_MAC\_ADDRESS\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **MacAddrs** array. A zero value for this member indicates an empty excluded MAC address list. + +**uTotalNumOfEntries** +Maximum number of entries that the **MacAddrs** array can contain. + +**MacAddrs** +The excluded MAC address list. For more information about the data type of this member, see [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681). + +A wildcard MAC address has the value of 0xFFFFFFFFFFFF. The wildcard MAC address matches the MAC address of any AP or peer station. If the excluded MAC address list contains the wildcard MAC address, the 802.11 station must not connect to any AP or peer station. + +**Note**  A list of excluded MAC address that contains the wildcard MAC address must be the only entry in the list. + +  + +When OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST is set, the miniport driver should ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + +``` + FIELD_OFFSET(DOT11_MAC_ADDRESS_LIST, MacAddrs) + uNumOfEntries * sizeof(DOT11_MAC_ADDRESS)) +``` + +When OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST is set, the miniport driver must: + +- Fail the set request if the excluded MAC address list contains the wildcard MAC address but the **uNumOfEntries** member is not set to one. In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Fail the set request if the **uNumOfEntries** member has a value greater than the value of **uExcludedMacAddressListSize** that the driver previously returned through a query of [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md). In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Overwrite the 802.11 station's excluded MAC address list with the entries from the **MacAddrs** array. If an entry has the MAC address of the AP or peer station that the 802.11 station is connected to, the 802.11 station must disassociate and roam to another station. For more information about the procedures for disassociating and roaming, see [Disassociation Operations](https://msdn.microsoft.com/library/windows/hardware/ff546439) and [Roaming Operations](https://msdn.microsoft.com/library/windows/hardware/ff570717). + +When OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_MAC\_ADDRESS\_LIST structure, including all entries in the **MacAddrs** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_MAC\_ADDRESS\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **MacAddrs** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_MAC\_ADDRESS\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_MAC\_ADDRESS\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_MAC\_ADDRESS\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **MacAddrs** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_MAC\_ADDRESS\_LIST structure. The miniport driver must also copy the entire DOT11\_MAC\_ADDRESS\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default for the **msDot11ExcludedMacAddressList** MIB object is an empty list with **uNumEntries** set to zero. The miniport driver must set this MIB object to its default if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-extsta-capability.md b/windows-driver-docs-pr/network/oid-dot11-extsta-capability.md new file mode 100644 index 0000000000..4d95aec854 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-extsta-capability.md @@ -0,0 +1,180 @@ +--- +title: OID\_DOT11\_EXTSTA\_CAPABILITY +author: windows-driver-content +description: When queried, the OID\_DOT11\_EXTSTA\_CAPABILITY object identifier (OID) requests that the miniport driver return the sizes of various tables and lists supported by the 802.11 station. +ms.assetid: 0ecbaca2-67ab-4185-ae84-d72f52fffe39 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_EXTSTA_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_EXTSTA\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_EXTSTA\_CAPABILITY object identifier (OID) requests that the miniport driver return the sizes of various tables and lists supported by the 802.11 station. + +The data type for this OID is the DOT11\_EXTSTA\_CAPABILITY structure. + +```ManagedCPlusPlus + typedef struct DOT11_EXTSTA_CAPABILITY { + NDIS_OBJECT_HEADER Header; + ULONG uScanSSIDListSize; + ULONG uDesiredBSSIDListSize; + ULONG uDesiredSSIDListSize; + ULONG uExcludedMacAddressListSize; + ULONG uPrivacyExemptionListSize; + ULONG uKeyMappingTableSize; + ULONG uDefaultKeyTableSize; + ULONG uWEPKeyValueMaxLength; + ULONG uPMKIDCacheSize; + ULONG uMaxNumPerSTADefaultKeyTables; + } DOT11_EXTSTA_CAPABILITY, *PDOT11_EXTSTA_CAPABILITY; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_EXTSTA\_CAPABILITY structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_EXTSTA\_CAPABILITY\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_EXTSTA\_CAPABILITY). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uScanSSIDListSize** +The maximum number of service set identifiers (SSIDs) supported by the 802.11 station for scan operations. The 802.11 station must support an SSID list of at least four entries. + +The SSID list that the 802.11 station uses for scanning is specified when [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md) is set. + +**uDesiredBSSIDListSize** +The maximum number of entries in the desired list of basic service set identifiers (BSSIDs) supported by the 802.11 station. The 802.11 station must support a BSSID list with at least one entry. + +For more information about the desired BSSID list, see [OID\_DOT11\_DESIRED\_BSSID\_LIST](oid-dot11-desired-bssid-list.md). + +**uDesiredSSIDListSize** +The maximum number of entries in the desired SSID list supported by the 802.11 station. The 802.11 station must support a desired SSID list with at least one entry. + +For more information about the desired SSID list, see [OID\_DOT11\_DESIRED\_SSID\_LIST](oid-dot11-desired-ssid-list.md). + +**uExcludedMacAddressListSize** +The maximum number of entries in the excluded MAC address list supported by the 802.11 station. The 802.11 station must support an excluded MAC address list with at least four entries. + +For more information about the desired excluded MAC address list, see [OID\_DOT11\_EXCLUDED\_MAC\_ADDRESS\_LIST](oid-dot11-excluded-mac-address-list.md). + +**uPrivacyExemptionListSize** +The maximum number of entries in the privacy exemption list supported by the 802.11 station. The 802.11 station must support a privacy exemption list with at least one entry. + +For more information about the privacy exemption list, see [OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST](oid-dot11-privacy-exemption-list.md). + +**uKeyMappingTableSize** +The maximum number of cipher key-mapping keys supported by the 802.11 station. It is recommended that the 802.11 station support at least 32 key-mapping keys. + +For more information about key mapping keys, see [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md) + +**uDefaultKeyTableSize** +The maximum number of cipher keys the 802.11 station supports for the default key and per-station default key tables. For more information about default keys and per-station default keys, see [802.11 Cipher Key Types](https://msdn.microsoft.com/library/windows/hardware/ff543625). + +For standard 802.11 cipher algorithms, the 802.11 station must support a table size of at least four cipher keys. For cipher algorithms developed by the independent hardware vendor (IHV), the table size can be four or greater. + +**uWEPKeyValueMaxLength** +The maximum length, in bytes, of a WEP cipher key supported by the 802.11 station. + +The following table lists the minimum and maximum key lengths, in bytes, for the various WEP cipher enumerator values defined through [**DOT11\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547672). + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
WEP cipherMinimum key lengthMaximum key length

DOT11_CIPHER_ALGO_WEP40

5

5

DOT11_CIPHER_ALGO_WEP104

13

13

DOT11_CIPHER_ALGO_WEP

13

Any length supported by the 802.11 station

+ +  + +**uPMKIDCacheSize** +The maximum number of entries in the pairwise master key identifier (PMKID) cache supported by the 802.11 station. + +If the 802.11 station does not support a PMKID cache, the miniport driver must set this member to zero. Otherwise, the 802.11 station must support a PMKID cache size of at least three entries. + +For more information about the PMKID cache, see [OID\_DOT11\_PMKID\_LIST](oid-dot11-pmkid-list.md). + +**uMaxNumPerSTADefaultKeyTables** +The maximum number of per station default cipher key tables supported by the 802.11 station. It is recommended that the 802.11 station support at least 32 per-station default cipher key tables. + +For more information about per-station default cipher key tables, see [Per-Station Default Keys](https://msdn.microsoft.com/library/windows/hardware/ff570016). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_EXTSTA_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-flush-bss-list.md b/windows-driver-docs-pr/network/oid-dot11-flush-bss-list.md new file mode 100644 index 0000000000..f99f6aba7f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-flush-bss-list.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_FLUSH\_BSS\_LIST +author: windows-driver-content +description: OID\_DOT11\_FLUSH\_BSS\_LIST +ms.assetid: e56d9b5b-1f06-400a-8c9d-39fffb068a10 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_FLUSH_BSS_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_FLUSH\_BSS\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_FLUSH\_BSS\_LIST object identifier (OID) requests that the miniport driver clear its cached basic service set (BSS) list. + +The miniport driver updates the cached BSS list when it performs a network scan. For more information about the cached BSS list, see [OID\_DOT11\_ENUM\_BSS\_LIST](oid-dot11-enum-bss-list.md). + +This OID does not require any data. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_FLUSH_BSS_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-fragmentation-threshold.md b/windows-driver-docs-pr/network/oid-dot11-fragmentation-threshold.md new file mode 100644 index 0000000000..b1dbbace5d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-fragmentation-threshold.md @@ -0,0 +1,109 @@ +--- +title: OID\_DOT11\_FRAGMENTATION\_THRESHOLD +author: windows-driver-content +description: OID\_DOT11\_FRAGMENTATION\_THRESHOLD +ms.assetid: 4b2fe2e0-2a6d-4dbb-b46c-7de32f38a349 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_FRAGMENTATION_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_FRAGMENTATION\_THRESHOLD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_FRAGMENTATION\_THRESHOLD object identifier (OID) requests that the miniport driver set the value of the IEEE 802.11 **dot11FragmentationThreshold** management information base (MIB) object to the specified value. + +When queried, OID\_DOT11\_FRAGMENTATION\_THRESHOLD requests that the miniport driver return the value of the **dot11FragmentationThreshold** MIB object. + +This MIB object specifies the current maximum size, in bytes, of the MAC protocol data unit (MPDU) frame that the PHY can transmit. + +The 802.11 station fragments a MAC service data unit (MSDU) packet if the payload length (plus the 802.11 MAC header and trailer) exceeds the value of **dot11FragmentationThreshold**. + +The data type for OID\_DOT11\_FRAGMENTATION\_THRESHOLD is a ULONG value that specifies the fragmentation threshold in bytes. + +The **aMPDUMaxLength** attribute of the current PHY type on the 802.11 station determines the range of values for the **dot11FragmentationThreshold** MIB object, and is based on the following formula: + +``` +256 <= dot11FragmentationThreshold <= min(2346, aMPDUMaxLength PHY attribute) +``` + +When OID\_DOT11\_FRAGMENTATION\_THRESHOLD is set, the 802.11 station must do the following: + +- After the set request, use the new fragmentation threshold value on all MSDU packets issued by the operating system to the miniport driver's [*MiniportSendNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559440) function. + +- Either use the new fragmentation threshold value on all MSDU packets that are pending in the station's transmit queue, or continue to use the old fragmentation threshold value for the pending MSDU packets. + +When OID\_DOT11\_FRAGMENTATION\_THRESHOLD is set, the 802.11 station must not apply the new fragmentation threshold value on the MSDU packet that the station is transmitting. + +The following points apply to a miniport driver operating in Extensible Station (ExtSTA) mode: + +- If the miniport driver has enabled automatic MAC configuration, it can fail the set request if the 802.11 station manages the MAC-layer configuration. In this situation, the driver returns NDIS\_STATUS\_DOT11\_AUTO\_CONFIG\_ENABLED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the automatic MAC configuration, see [OID\_DOT11\_AUTO\_CONFIG\_ENABLED](oid-dot11-auto-config-enabled.md). + +- The current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +The default value for the **dot11FragmentationThreshold** MIB object depends on the IEEE 802.11 **aMPDUMaxLength** attribute of the current PHY type on the 802.11 station based on the following formula: + +``` +dot11FragmentationThreshold = min(2346, aMPDUMaxLength) +``` + +The miniport driver must set the **dot11FragmentationThreshold** MIB object to this default when all of the following apply: + +- A set request of [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md) changes the current PHY type. + +- The miniport driver initializes the current PHY type through its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +For more information about the **aMPDUMaxLength** PHY attribute, see [OID\_DOT11\_MPDU\_MAX\_LENGTH](oid-dot11-mpdu-max-length.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_FRAGMENTATION_THRESHOLD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-frequency-bands-supported.md b/windows-driver-docs-pr/network/oid-dot11-frequency-bands-supported.md new file mode 100644 index 0000000000..d35a34fa30 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-frequency-bands-supported.md @@ -0,0 +1,122 @@ +--- +title: OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED +author: windows-driver-content +description: OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED +ms.assetid: 14f9e174-dffc-45e3-8a8b-a7e204276f7c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_FREQUENCY_BANDS_SUPPORTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED object identifier (OID) requests that the miniport driver return the IEEE 802.11 **dot11FrequencyBandsSupported** MIB object for the current PHY type on the 802.11 station. + +This MIB object specifies the frequency bands in which the orthogonal frequency division multiplexing (OFDM) PHY is capable of operating. Frequency bands are defined for: + +- Unlicensed national information infrastructure (U-NII) bands. + +- Conference of European Post and Telecommunication (CEPT) bands. + +- Japan 5 GHz bands. + +The data type for OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED is a ULONG value, which defines the supported frequency bands through one of the bitmasks in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BitDescription

0

Capable of operating in the lower (5.15-5.25 GHz) U-NII band.

1

Capable of operating in the middle (5.25-5.35 GHz) U-NII band.

2

Capable of operating in the upper (5.725-5.825 GHz) U-NII band.

3

Capable of operating in CEPT B (5.47-5.7253 GHz) band.

4

Capable of operating in the lower Japan (5.15-5.25 GHz) band.

5

Capable of operating in the Japan 5.0 (5.03-5.091 GHz) band.

6

Capable of operating in the Japan 4.9 (4.9-5.0GHz) band.

+ +  + +The **dot11FrequencyBandsSupported** MIB object is valid for only the OFDM PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ofdm**, the miniport driver must fail a query of OID\_DOT11\_FREQUENCY\_BANDS\_SUPPORTED by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_FREQUENCY_BANDS_SUPPORTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hardware-phy-state.md b/windows-driver-docs-pr/network/oid-dot11-hardware-phy-state.md new file mode 100644 index 0000000000..e551c81276 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hardware-phy-state.md @@ -0,0 +1,116 @@ +--- +title: OID\_DOT11\_HARDWARE\_PHY\_STATE +author: windows-driver-content +description: OID\_DOT11\_HARDWARE\_PHY\_STATE +ms.assetid: 74ddc4d9-166c-4e80-996e-b63cab7938aa +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HARDWARE_PHY_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HARDWARE\_PHY\_STATE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HARDWARE\_PHY\_STATE object identifier (OID) requests that the miniport driver return the value of the Extensible Station (ExtSTA) **msDot11HardwarePHYState** management information base (MIB) object. + +The **msDot11HardwarePHYState** MIB object defines the power state of the current PHY type on the 802.11 station. + +The data type for OID\_DOT11\_HARDWARE\_PHY\_STATE is a BOOLEAN value. A value of **TRUE** indicates that the PHY is turned on. + +Some 802.11 NICs support a hardware setting on the computer for turning the PHY on or off. The OID\_DOT11\_HARDWARE\_PHY\_STATE OID queries power state of the current PHY type based on the hardware setting. + +When OID\_DOT11\_HARDWARE\_PHY\_STATE is queried, the miniport driver must set the returned BOOLEAN value as follows: + +- If the NIC does support a hardware setting, the value must be **FALSE** (if the PHY is turned off) or **TRUE** (if the PHY is turned on). + +- If the NIC does not support a hardware setting, the value must be **TRUE**. + +Software settings for the PHY power state are made through the Native 802.11 Operational **msDot11NICPowerState** MIB variable. For more information about this MIB variable, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +The 802.11 station must set the PHY's power state based on the **msDot11NICPowerState** and **msDot11HardwarePHYState** MIB variables in the following way: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
msDot11NICPowerState valuemsDot11HardwarePHYState valuePHY power state

TRUE

TRUE

Turned on

FALSE

TRUE

Turned off

TRUE

FALSE

Turned off

FALSE

FALSE

Turned off

+ +  + +The current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index (ID) of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +The miniport driver must make an [NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED](ndis-status-dot11-phy-state-changed.md) indication whenever the value of the **msDot11HardwarePHYState** MIB object changes. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HARDWARE_PHY_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hidden-network-enabled.md b/windows-driver-docs-pr/network/oid-dot11-hidden-network-enabled.md new file mode 100644 index 0000000000..e71b1cb558 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hidden-network-enabled.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_HIDDEN\_NETWORK\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_HIDDEN\_NETWORK\_ENABLED +ms.assetid: ecbcc751-3c05-464e-adee-d07463bc3b1b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HIDDEN_NETWORK_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HIDDEN\_NETWORK\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_HIDDEN\_NETWORK\_ENABLED object identifier (OID) requests that the miniport driver enable the 802.11 station's ability to access an infrastructure network that includes hidden access points (APs). Hidden APs do not broadcast their SSIDs. + +When queried, this OID requests that the miniport driver return the value of the **msDot11HiddenNetworkEnabled** MIB object. + +The data type for this OID is a Boolean value. + +An OID value of **TRUE** indicates that the infrastructure network might contain APs that do not broadcast their SSIDs. The NIC might include the desired SSID in the probe request transmitted during roaming scanning. + +An OID value of **FALSE** indicates that the NIC must assume that all APs in the infrastructure network will broadcast their SSIDs. The default OID value is **FALSE**. + +This OID only applies to situations where the NIC connects to an infrastructure network. When resuming from standby or hibernation and the OID value is **FALSE**, the NIC must use the wildcard SSID in the probe requests until it determines a set of visible candidate APs. In normal roaming cases that do not involve standby or hibernation, the NIC can choose its own probe requests. APs cached prior to standby or hibernation are considered hidden unless the NIC can see their packets after waking up. + +The miniport driver must fail a set request with error code NDIS\_STATUS\_INVALID\_STATE if the 802.11 station is in any state except the initialization (INIT) state. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HIDDEN_NETWORK_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hop-algorithm-adopted.md b/windows-driver-docs-pr/network/oid-dot11-hop-algorithm-adopted.md new file mode 100644 index 0000000000..9de82f9a99 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hop-algorithm-adopted.md @@ -0,0 +1,98 @@ +--- +title: OID\_DOT11\_HOP\_ALGORITHM\_ADOPTED +author: windows-driver-content +description: OID\_DOT11\_HOP\_ALGORITHM\_ADOPTED +ms.assetid: bf577fa8-ed78-4afc-9752-d5702f917c31 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HOP_ALGORITHM_ADOPTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HOP\_ALGORITHM\_ADOPTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HOP\_ALGORITHM object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11HopAlgorithmAdopted** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11HopAlgorithmAdopted** MIB object specifies the type of algorithm that generates the hopping patterns used by the frequency-hopping spread spectrum (FHSS) PHY. + +**Note**  Support for OID\_DOT11\_HOP\_ALGORITHM is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_HOP\_ALGORITHM is the DOT11\_HOP\_ALGO\_ADOPTED enumeration, which include the following algorithms: + +**dot11\_hop\_algo\_current** +The algorithm generates hopping patterns as defined in Clause 14 of the IEEE 802.11-2012 and IEEE 802.11d-2001 standards. + +**dot11\_hop\_algo\_hop\_index** +The algorithm generates hopping patterns through the hop index method as defined in Clause 7.3.2.14 of the IEEE 802.11d-2001 standard. + +The 802.11 station must use the random table method to generate hopping patterns if the Flag field of the Hopping Pattern Table information element (IE) was set to one in the last received Beacon or Probe Response frame. Otherwise, the 802.11 station must use the hop index method. + +For more information regarding the hop index and random table methods, see Clause 7.3.2.14 of the IEEE 802.11d-2001 standard + +**dot11\_hop\_algo\_hcc** +The algorithm generates hopping patterns using the hyperbolic congruence codes (HCC) or extended hyperbolic congruence codes (EHCC) methods. For more information about the HCC/EHCC methods, refer to Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +The miniport driver fails a query of OID\_DOT11\_HOP\_ALGORITHM under the following conditions: + +- The **dot11HopAlgorithmAdopted** MIB object is valid for only the FHSS PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HOP_ALGORITHM_ADOPTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hop-modulus.md b/windows-driver-docs-pr/network/oid-dot11-hop-modulus.md new file mode 100644 index 0000000000..0b45aea615 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hop-modulus.md @@ -0,0 +1,87 @@ +--- +title: OID\_DOT11\_HOP\_MODULUS +author: windows-driver-content +description: OID\_DOT11\_HOP\_MODULUS +ms.assetid: 07061c13-58b0-4e4d-9f24-7b4f5811e087 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HOP_MODULUS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HOP\_MODULUS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HOP\_MODULUS object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11HopModulus** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11HopModulus** MIB object defines the number of channels for the hopping set used by the current PHY type. + +The governing regulatory agency for the country code (as specified by the IEEE 802.11d **dot11CountryString** MIB object) defines the number of channels in the hopping set. For more information about the **dot11CountryString** MIB object, see [OID\_DOT11\_COUNTRY\_STRING](oid-dot11-country-string.md). + +**Note**  Support for OID\_DOT11\_HOP\_MODULUS OID is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_HOP\_MODULUS OID is a ULONG value. + +The miniport driver fails a query of OID\_DOT11\_HOP\_MODULUS OID under the following conditions: + +- The **dot11HopModulus** MIB object is valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HOP_MODULUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hop-offset.md b/windows-driver-docs-pr/network/oid-dot11-hop-offset.md new file mode 100644 index 0000000000..05946cd719 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hop-offset.md @@ -0,0 +1,85 @@ +--- +title: OID\_DOT11\_HOP\_OFFSET +author: windows-driver-content +description: OID\_DOT11\_HOP\_OFFSET +ms.assetid: c72c870a-2909-4eb1-83fb-2f16610c9b14 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HOP_OFFSET Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HOP\_OFFSET + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HOP\_OFFSET object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11HopOffset** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11HopOffset** MIB object defines the next position in the hopping set used by the current PHY type. + +**Note**  Support for OID\_DOT11\_HOP\_OFFSET is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_HOP\_OFFSET is a ULONG value. + +The miniport driver fails a query of OID\_DOT11\_HOP\_OFFSET under the following conditions: + +- The **dot11HopOffset** MIB object is valid for only the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HOP_OFFSET%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hop-time.md b/windows-driver-docs-pr/network/oid-dot11-hop-time.md new file mode 100644 index 0000000000..9fb3967043 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hop-time.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_HOP\_TIME +author: windows-driver-content +description: OID\_DOT11\_HOP\_TIME +ms.assetid: 7c4b0306-b375-44c2-9b44-d6ebf6f1e7eb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HOP_TIME Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HOP\_TIME + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HOP\_TIME object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11HopTime** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11HopTime** MIB object defines the time, in microseconds, that the physical media dependent (PMD) sublayer of the current PHY type requires to change from channel 2 to channel 80. + +**Note**  Support for OID\_DOT11\_HOP\_TIME is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_HOP\_TIME is a ULONG value. + +The IEEE 802.11-2012 standard defines the value of the **dot11HopTime** MIB object to be 224. + +The **dot11HopTime** MIB object is valid for only the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HOP_TIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hopping-pattern.md b/windows-driver-docs-pr/network/oid-dot11-hopping-pattern.md new file mode 100644 index 0000000000..f890cc66f3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hopping-pattern.md @@ -0,0 +1,125 @@ +--- +title: OID\_DOT11\_HOPPING\_PATTERN +author: windows-driver-content +description: When queried, the OID\_DOT11\_HOPPING\_PATTERN object identifier (OID) requests that the miniport driver return the list of hopping patterns currently used by the current PHY type on the 802.11 station. +ms.assetid: 6bf0c5e9-f2d6-48ab-9f2e-a4fd742f20f7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HOPPING_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HOPPING\_PATTERN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HOPPING\_PATTERN object identifier (OID) requests that the miniport driver return the list of hopping patterns currently used by the current PHY type on the 802.11 station. + +**Note**  Support for OID\_DOT11\_HOPPING\_PATTERN is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_HOPPING\_PATTERN is the DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure. + +```ManagedCPlusPlus + typedef struct _DOT11_HOPPING_PATTERN_ENTRY_LIST { + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_HOPPING_PATTERN_ENTRY dot11HoppingPatternEntry[1]; + } DOT11_HOPPING_PATTERN_ENTRY_LIST, *PDOT11_HOPPING_PATTERN_ENTRY_LIST; + +``` + +This structure includes the following members: + +**uNumOfEntries** +Number of entries in the **dot11HoppingPatternEntry** array. A zero value for this member indicates an empty list of hopping patterns. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11HoppingPatternEntry** array requires. + +**dot11HoppingPatternEntry** +The list of hopping patterns. + +Each element of the **dot11HoppingPatternEntry** array is formatted as a DOT11\_HOPPING\_PATTERN\_ENTRY structure, which is based on the IEEE 802.11d **dot11HoppingPatternEntry** MIB object: + +``` syntax +typedef struct _DOT11_HOPPING_PATTERN_ENTRY { ULONG uHoppingPatternIndex; + ULONG + uRandomTableFieldNumber; } DOT11_HOPPING_PATTERN_ENTRY, *PDOT11_HOPPING_PATTERN_ENTRY; +``` + +This structure includes the following members: + +**uHoppingPatternIndex** +Identifies this entry in the miniport driver's hopping pattern table. + +**uRandomTableFieldNumber** +The starting channel number in the subband for the domain that is identified by the IEEE 802.11 **dot11CountryString** management information base (MIB) object. For more information about this MIB object, see [OID\_DOT11\_COUNTRY\_STRING](oid-dot11-country-string.md). + +The **dot11HoppingPatternEntry** MIB object is valid for the frequency-hopping spread spectrum (FHSS) PHY type only. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_HOPPING\_PATTERN is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure, including all entries in the **dot11HoppingPatternEntry** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, for example: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11HoppingPatternEntry** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure. The miniport driver must also copy the entire DOT11\_RECV\_SENSITIVITY\_LIST structure to the **InformationBuffer** member and the entire DOT11\_HOPPING\_PATTERN\_ENTRY\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HOPPING_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-hr-cca-mode-supported.md b/windows-driver-docs-pr/network/oid-dot11-hr-cca-mode-supported.md new file mode 100644 index 0000000000..76eced59c5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-hr-cca-mode-supported.md @@ -0,0 +1,86 @@ +--- +title: OID\_DOT11\_HR\_CCA\_MODE\_SUPPORTED +author: windows-driver-content +description: OID\_DOT11\_HR\_CCA\_MODE\_SUPPORTED +ms.assetid: 3589de1d-9c9f-4340-a418-0c221e294e54 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_HR_CCA_MODE_SUPPORTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_HR\_CCA\_MODE\_SUPPORTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_HR\_CCA\_MODE\_SUPPORTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11HRCCAModeSupported** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the type of clear channel assessment (CCA) mode supported by the current PHY type. For more information about CCA, refer to Clause 16.4.8.5 of the IEEE 802.11-2012 standard and Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +The data type for OID\_DOT11\_HR\_CCA\_MODE\_SUPPORTED is a ULONG value, which defines the supported CCA modes through the following bitmask: + +DOT11\_CCA\_MODE\_ED\_ONLY (0x00000001) +CCA mode using the energy detect (ED) signal. For more information about the ED signal, refer to Clause 15.4.6.1 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_CS\_ONLY (0x00000002) +CCA mode using the carrier sense (CS) signal. For more information about the CS signal, refer to Clause 15.4.6.2 of the IEEE 802.11-2012 standard. + +DOT11\_CCA\_MODE\_ED\_and\_CS (0x00000004) +Both ED and CS modes. + +DOT11\_HR\_CCA\_MODE\_CS\_WITH\_TIMER (0x00000008) +CCA mode using the CS signal with a timer. For more information about this CCA mode, refer to Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +DOT11\_HR\_CCA\_MODE\_HRCS\_AND\_ED (0x00000010) +Both ED and CS modes on high-rate (HR) PHYs. For more information about this CCA mode, refer to Clause 18.4.8.4 of the IEEE 802.11b-1999 standard. + +The **dot11HRCCAModeSupported** MIB object is only valid for the high-rate direct-sequence spread spectrum (HRDSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_hrdsss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_HR_CCA_MODE_SUPPORTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ibss-params.md b/windows-driver-docs-pr/network/oid-dot11-ibss-params.md new file mode 100644 index 0000000000..ee4ffc0eff --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ibss-params.md @@ -0,0 +1,163 @@ +--- +title: OID\_DOT11\_IBSS\_PARAMS +author: windows-driver-content +description: When set, the OID\_DOT11\_IBSS\_PARAMS object identifier (OID) requests that the miniport driver set parameters to be used when connecting to an independent basic service set (IBSS) network.Note  IBSS (Ad hoc) and SoftAP are deprecated. +ms.assetid: 5b0500ed-40c1-4e23-8610-e299bfe692db +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_IBSS_PARAMS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_IBSS\_PARAMS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_IBSS\_PARAMS object identifier (OID) requests that the miniport driver set parameters to be used when connecting to an independent basic service set (IBSS) network. + +**Note**  IBSS (Ad hoc) and SoftAP are deprecated. Starting with Windows 8.1 and Windows Server 2012 R2, use [Wi-Fi Direct](https://msdn.microsoft.com/library/windows/hardware/hh440289). + +  + +When queried, this OID requests that the miniport driver return the IBSS network connection parameters. + +If the IEEE **dot11DesiredBSSType** management information base (MIB) object is set to **dot11\_BSS\_type\_independent**, the 802.11 station uses the IBSS network parameters when performing a connection operation to an IBSS network. Connection operations are initiated through a set of [OID\_DOT11\_CONNECT\_REQUEST](oid-dot11-connect-request.md). + +For more information about the **dot11DesiredBSSType** MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +The data type for OID\_DOT11\_IBSS\_PARAMS is the DOT11\_IBSS\_PARAMS structure. + +```ManagedCPlusPlus + typedef struct DOT11_IBSS_PARAMS { + NDIS_OBJECT_HEADER Header; + BOOLEAN bJoinOnly; + ULONG uIEsOffset; + ULONG uIEsLength; + } DOT11_IBSS_PARAMS, *PDOT11_IBSS_PARAMS; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_IBSS\_PARAMS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_IBSS\_PARAMS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_IBSS\_PARAMS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**bJoinOnly** +Specifies whether the 802.11 station should only join an existing IBSS network or start a new IBSS network during the connection operation. + +If **bJoinOnly** is **FALSE**, the 802.11 station must join an existing IBSS network if the station detects one. If the 802.11 station does not detect an IBSS network, the station must start a new one. + +If **bJoinOnly** is **TRUE**, the 802.11 station must only join an existing IBSS network. If the 802.11 station does not detect an IBSS network, the station must continue searching for an IBSS network to join until either a set request of [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) or a set request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made. + +**uIEsOffset** +Offset in the **InformationBuffer** member of the NDIS\_OID\_REQUEST structure where additional 802.11 Information Elements (IE) are stored. + +The 802.11 station must append these additional IEs to the end of every transmitted 802.11 Beacon or Probe Response frames. If adding the additional IEs causes the size of the frames to exceed the maximum length for 802.11 media access control (MAC) management protocol data unit (MMPDU) frames, the 802.11 station must not append the additional IEs. + +**Note**  If it cannot append the additional IEs, the 802.11 station must remain connected to the IBSS network. + +  + +**uIEsOffset** is calculated from the beginning of the DOT11\_IBSS\_PARAMS structure. + +**uIEsLength** +Length of the additional 802.11 IEs. If **uIEsLength** is zero, no additional IEs are stored. + +The 802.11 station must follow these guidelines when **bJoinOnly** is set to **TRUE**. + +- After joining an existing IBSS network, the 802.11 station cannot perform a roaming operation to a new IBSS network until it is the only station within the IBSS network with which it is joined. If it is the only station within the IBSS network with which it is joined, it should stop sending Beacon frames and must continue searching for an IBSS network to join until either a set request of [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) or a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made. + +- If the 802.11 station supports 802.11h for IBSS networks, the station must not enter the DFS owner recovery mode as defined in Clause 11.6.7.2 of the IEEE 802.11h-2003 standard. Instead, the 802.11 station must disassociate from all the existing peer stations within the IBSS network and perform a roaming operation to another IBSS network. + + If the 802.11 station does not detect another IBSS network, the station must continue searching for an IBSS network to join until either a set request of [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) or a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made. + +The default values for the members of the DOT11\_IBSS\_PARAMS structure are defined in the following table. + + ++++ + + + + + + + + + + + + + + + + + + + + +
DOT11_IBSS_PARAMS memberDefault value

bJoinOnly

FALSE

uIEsOffset

0

uIEsLength

0

+ +  + +The miniport driver must set the members of the DOT11\_IBSS\_PARAMS structure to the default values if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_IBSS_PARAMS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-incoming-association-decision.md b/windows-driver-docs-pr/network/oid-dot11-incoming-association-decision.md new file mode 100644 index 0000000000..dacc0e2f30 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-incoming-association-decision.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_INCOMING\_ASSOCIATION\_DECISION +author: windows-driver-content +description: OID\_DOT11\_INCOMING\_ASSOCIATION\_DECISION +ms.assetid: dd9601c7-ff89-4629-affc-02a401b9ca83 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_INCOMING_ASSOCIATION_DECISION Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_INCOMING\_ASSOCIATION\_DECISION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_INCOMING\_ASSOCIATION\_DECISION object identifier (OID) requests that the miniport driver notify the NIC whether it has accepted an incoming request from an 802.11 peer station to perform an association procedure. + +**Note**  Support for this OID is mandatory. NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +The data type for this OID is the [**DOT11\_INCOMING\_ASSOC\_DECISION**](https://msdn.microsoft.com/library/windows/hardware/ff548654) structure. + +When this OID is set, the NIC must behave as follows: + +- If the Extensible AP is in the INIT state, the NIC must fail the request and return a status indication of NDIS\_STATUS\_INVALID\_STATE. + +- If the Extensible AP is in the OP state, the NIC must complete the request. + +**Note**  Miniports must handle this OID synchronously. They must not process requests as pending. + +  + +For more information about the association procedure, see [Association Operation Guidelines for Extensible Access Point (ExtAP) Mode](https://msdn.microsoft.com/library/windows/hardware/ff543791). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_INCOMING\_ASSOC\_DECISION**](https://msdn.microsoft.com/library/windows/hardware/ff548654) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_INCOMING_ASSOCIATION_DECISION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-long-retry-limit.md b/windows-driver-docs-pr/network/oid-dot11-long-retry-limit.md new file mode 100644 index 0000000000..e5f780a2e0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-long-retry-limit.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_LONG\_RETRY\_LIMIT +author: windows-driver-content +description: OID\_DOT11\_LONG\_RETRY\_LIMIT +ms.assetid: e596d56c-36c8-4fa4-b62c-3656ad521b6e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_LONG_RETRY_LIMIT Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_LONG\_RETRY\_LIMIT + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_LONG\_RETRY\_LIMIT object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11LongtRetryLimit** management information base (MIB) object. + +This MIB object specifies the maximum number of retransmission attempts made by the 802.11 station for MSDU packets with lengths greater than the value of the IEEE 802.11 **dot11RTSThreshold** MIB object. For more information about the **dot11RTSThreshold** MIB object, see [OID\_DOT11\_RTS\_THRESHOLD](oid-dot11-rts-threshold.md). + +The data type for OID\_DOT11\_LONG\_RETRY\_LIMIT is a ULONG value from 1 through 255. + +When the 802.11 station exceeds the maximum number of retransmission attempts defined by the **dot11LongRetryLimit** MIB object, it must do the following: + +- Discard the packet. + +- If the miniport driver is operating in Extensible Station (ExtSTA) mode, increment the **ullMaxRXLifetimeExceededCount** member of the DOT11\_STATISTICS structure. For more information about this structure, see [OID\_DOT11\_STATISTICS](oid-dot11-statistics.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_LONG_RETRY_LIMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-mac-address.md b/windows-driver-docs-pr/network/oid-dot11-mac-address.md new file mode 100644 index 0000000000..ca8205b1b4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-mac-address.md @@ -0,0 +1,67 @@ +--- +title: OID\_DOT11\_MAC\_ADDRESS +author: windows-driver-content +description: OID\_DOT11\_MAC\_ADDRESS +ms.assetid: ebc9ec2b-7783-44e6-9a48-9013df8895b0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MAC_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MAC\_ADDRESS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MAC\_ADDRESS object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11MACAddress** MIB object. + +This MIB object contains the media access control (MAC) address currently assigned to the 802.11 station. + +The data type for OID\_DOT11\_MAC\_ADDRESS is the [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MAC_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-max-dwell-time.md b/windows-driver-docs-pr/network/oid-dot11-max-dwell-time.md new file mode 100644 index 0000000000..2bcdee449c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-max-dwell-time.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_MAX\_DWELL\_TIME +author: windows-driver-content +description: OID\_DOT11\_MAX\_DWELL\_TIME +ms.assetid: 6adbe09e-9ba3-4186-9ae1-435a8a6b233a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MAX_DWELL_TIME Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MAX\_DWELL\_TIME + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MAX\_DWELL\_TIME object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11MaxDwellTime** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11MaxDwellTime** MIB object defines the maximum time that the current PHY type operates on a single channel when the 802.11 station is transmitting data. + +**Note**  Support for OID\_DOT11\_MAX\_DWELL\_TIME is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_MAX\_DWELL\_TIME is a ULONG value that specifies the maximum dwell time in units of 802.11 time units (TU). One TU is 1024 microseconds. The value of the **dot11MaxDwellTime** MIB must be from 1 through 65535. + +The **dot11MaxDwellTime** MIB object is valid for only the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MAX_DWELL_TIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-max-receive-lifetime.md b/windows-driver-docs-pr/network/oid-dot11-max-receive-lifetime.md new file mode 100644 index 0000000000..a44c4f5827 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-max-receive-lifetime.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_MAX\_RECEIVE\_LIFETIME +author: windows-driver-content +description: OID\_DOT11\_MAX\_RECEIVE\_LIFETIME +ms.assetid: 1126bda6-aca9-41ec-8a31-2d6a1a6e3a89 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MAX_RECEIVE_LIFETIME Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MAX\_RECEIVE\_LIFETIME + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MAX\_RECEIVE\_LIFETIME object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11MaxReceiveLifetime** management information base (MIB) object. + +This MIB object specifies the maximum elapsed time after the initial reception of a management protocol data unit (MPDU) fragment that the 802.11 station can wait to receive all remaining fragments of the management service data unit (MSDU) packet. + +The data type for OID\_DOT11\_MAX\_RECEIVE\_LIFETIME is a ULONG value that specifies the maximum receive lifetime in 802.11 time units (TU). One TU is 1024 microseconds. The value of the **dot11MaxReceiveLifetime** MIB must be from 1 through 4294967295. + +If the maximum receive lifetime expires and the 802.11 station has not received all of the MPDU fragments, the miniport driver must do the following: + +- Discard the MSDU packet and stop any further attempts to reassemble the packet. + +- If the miniport driver is operating in Extensible Station (ExtSTA) mode, increment the **ullMaxRXLifetimeExceededCount** member of the DOT11\_STATISTICS structure. For more information about this structure, see [OID\_DOT11\_STATISTICS](oid-dot11-statistics.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MAX_RECEIVE_LIFETIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-max-transmit-msdu-lifetime.md b/windows-driver-docs-pr/network/oid-dot11-max-transmit-msdu-lifetime.md new file mode 100644 index 0000000000..f5ecab70dc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-max-transmit-msdu-lifetime.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME +author: windows-driver-content +description: OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME +ms.assetid: fb129074-6078-48b6-8043-e6296ec831d4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11MaxTransmitMSDULifetime** MIB object. + +The **dot11MaxTransmitMSDULifetime** MIB object specifies the maximum time that the 802.11 station can spend transmitting all management protocol data unit (MPDU) fragments for a management service data unit (MSDU) packet. + +The data type for OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME is a ULONG value that specifies the maximum transmit lifetime in 802.11 time units (TU). One TU is 1024 microseconds. The value of the **dot11MaxTransmitMSDULifetime** MIB object must be from 1 through 4294967295. + +If the maximum transmit lifetime expires before the transmission of the MSDU packet has completed, the miniport driver must do the following: + +- Discard the MSDU packet. + +- If the miniport driver is operating in Extensible Station (ExtSTA) mode, increment the **ullMaxTXLifetimeExceededCount** member of the DOT11\_STATISTICS structure. For more information about this structure, see [OID\_DOT11\_STATISTICS](oid-dot11-statistics.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes**-> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-maximum-list-size.md b/windows-driver-docs-pr/network/oid-dot11-maximum-list-size.md new file mode 100644 index 0000000000..759aede8da --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-maximum-list-size.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_MAXIMUM\_LIST\_SIZE +author: windows-driver-content +description: OID\_DOT11\_MAXIMUM\_LIST\_SIZE +ms.assetid: f4403b06-a8c7-4c0a-8db1-82c87976175b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MAXIMUM_LIST_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MAXIMUM\_LIST\_SIZE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MAXIMUM\_LIST\_SIZE object identifier (OID) requests that the miniport driver return the maximum number of multicast addresses supported by the 802.11 station. + +The data type for this OID is a ULONG value. + +For more information about how multicast addresses are added or deleted, see [OID\_DOT11\_MULTICAST\_LIST](oid-dot11-multicast-list.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MAXIMUM_LIST_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-media-streaming-enabled.md b/windows-driver-docs-pr/network/oid-dot11-media-streaming-enabled.md new file mode 100644 index 0000000000..3ed9685e41 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-media-streaming-enabled.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_MEDIA\_STREAMING\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_MEDIA\_STREAMING\_ENABLED +ms.assetid: c286775c-996e-419d-9d65-84aa3c732dbd +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MEDIA_STREAMING_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MEDIA\_STREAMING\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_MEDIA\_STREAMING\_ENABLED object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) **msDot11MediaStreamingEnabled** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **msDot11MediaStreamingEnabled** MIB object. + +The **msDot11MediaStreamingEnabled** MIB object defines the current setting of media streaming on the 802.11 station. For more information about media streaming, see [Native 802.11 Media Streaming](https://msdn.microsoft.com/library/windows/hardware/ff560643). + +The data type for OID\_DOT11\_MEDIA\_STREAMING\_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the 802.11 station has enabled media streaming. + +The default for the **msDot11MediaStreamingEnabled** MIB object is **FALSE**. The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MEDIA_STREAMING_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-mpdu-max-length.md b/windows-driver-docs-pr/network/oid-dot11-mpdu-max-length.md new file mode 100644 index 0000000000..cc0b2b4591 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-mpdu-max-length.md @@ -0,0 +1,112 @@ +--- +title: OID\_DOT11\_MPDU\_MAX\_LENGTH +author: windows-driver-content +description: OID\_DOT11\_MPDU\_MAX\_LENGTH +ms.assetid: f278f5ec-ad01-41e8-ab14-a245d46f127e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MPDU_MAX_LENGTH Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MPDU\_MAX\_LENGTH + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MPDU\_MAX\_LENGTH object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **aMPDUMaxLength** attribute for the current PHY type on the 802.11 station. + +The data type for this OID is a **ULONG** value. + +The **aMPDUMaxLength** attribute defines the maximum length, in bytes, of a MAC protocol data unit (MPDU) frame that the PHY can transmit or receive. The following table lists the values of this attribute for the various 802.11 PHY types supported. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PHY typeaMPDUMaxLength value

dot11_phy_type_fhss

4095 bytes

dot11_phy_type_dsss

4-8191 bytes

dot11_phy_type_irbaseband

2500 bytes

dot11_phy_type_ofdm

4095 bytes

dot11_phy_type_hrdsss

4095 bytes

dot11_phy_type_erp

4095 bytes

+ +  + +**Note**  The **dot11\_phy\_type\_ht** and **dot11\_phy\_type\_vht** PHY types do not appear in the table, because they have no **aMPDUMaxLength** attribute. + +  + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +If the **aMPDUMaxLength** value changes, the miniport driver must make a media-specific [NDIS\_STATUS\_DOT11\_MPDU\_MAX\_LENGTH\_CHANGED](ndis-status-dot11-mpdu-max-length-changed.md) indication. This indication notifies the operating system of the change in the maximum MPDU length supported on the 802.11 station. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MPDU_MAX_LENGTH%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-enabled.md b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-enabled.md new file mode 100644 index 0000000000..710b7f2d9b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-enabled.md @@ -0,0 +1,105 @@ +--- +title: OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED +ms.assetid: 3d2431b6-02b8-4a4c-88fb-6d3387fe6918 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED object identifier (OID) requests that the miniport driver set the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **dot11MultiDomainCapabilityEnabled** MIB object. + +**Note**  Support for OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED is mandatory if the 802.11 station supports more than one regulatory domain and the IEEE 802.11 **dot11MultiDomainCapabilityImplemented** MIB object is **TRUE**. For more information about this MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +  + +The data type for OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED is a BOOLEAN value. + +If the **dot11MultiDomainCapabilityEnabled** MIB object is **TRUE**, the 802.11 station can operate in multiple regulatory domains. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_REG\_DOMAIN](oid-dot11-current-reg-domain.md). + +The 802.11 station operates in multiple regulatory domains in the following way: + +- If the **dot11CurrentRegDomain** MIB object is set to DOT11\_REG\_DOMAIN\_OTHER, the 802.11 station operates dynamically in multiple regulatory domains through the procedures and protocols defined by the IEEE 802.11d-2001 standard. + +- If the **dot11CurrentRegDomain** MIB object is not set DOT11\_REG\_DOMAIN\_OTHER, the 802.11 station only operates within the regulatory domain as specified by the MIB object. + + In this situation, the value of the **dot11CurrentRegDomain** MIB object defines the default regulatory domain of the 802.11 station. For more information about the default regulatory domain, see [OID\_DOT11\_CURRENT\_REG\_DOMAIN](oid-dot11-current-reg-domain.md). + + **Note**  The default regulatory domain can only be changed while the miniport driver is operating in the initialization (INIT) state. For more information about this state, see [Native 802.11 Operating States](https://msdn.microsoft.com/library/windows/hardware/ff560664). + +   + +If the **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the 802.11 station can only operate in its default regulatory domain. + +The miniport driver fails a set or query of OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED under the following conditions: + +- If the **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the 802.11 station does not support multiple regulatory domains. In this situation, the miniport driver must return NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the **dot11MultiDomainCapabilityImplemented** MIB object is **TRUE** and the 802.11 station does not support a default regulatory domain, it must fail the set request if the specified value of the **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**. The miniport driver must return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 has not completed an explicit scan initiated through a set of [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md), the miniport driver must return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default value for the **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**. The miniport driver must set this MIB object to this default when one of the following occurs: + +- The miniport driver initializes the current PHY type through its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-implemented.md b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-implemented.md new file mode 100644 index 0000000000..5891d8b21a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability-implemented.md @@ -0,0 +1,67 @@ +--- +title: OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED +ms.assetid: 5de9d07f-d0d1-4507-8193-331c7bf176f5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** management information base (MIB) object. + +If the **dot11MultiDomainCapabilityImplemented** MIB object is **TRUE**, the 802.11 station supports more than one regulatory domain. For more information about 802.11 regulatory domains, refer to the IEEE 802.11d-2001 standard. + +The data type for OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED is a BOOLEAN value. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability.md b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability.md new file mode 100644 index 0000000000..120e5276b7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-multi-domain-capability.md @@ -0,0 +1,144 @@ +--- +title: OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY +author: windows-driver-content +description: When queried, the OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY object identifier (OID) requests that the miniport driver return the list of supported regulatory domains associated with +ms.assetid: 45115177-e641-47b9-8b40-ad2091db22bd +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MULTI_DOMAIN_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY object identifier (OID) requests that the miniport driver return the list of supported regulatory domains associated with: + +- The value of the IEEE 802.11d **dot11CountryString** management information base (MIB) object. For more information about the **dot11CountryString** management information base (MIB) object, see [OID\_DOT11\_COUNTRY\_STRING](oid-dot11-country-string.md). + +- The current PHY type on the 802.11 station. + +The data type for OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY is the DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure. + +```ManagedCPlusPlus + typedef struct _DOT11_MD_CAPABILITY_ENTRY_LIST { + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_MULTI_DOMAIN_CAPABILITY_ENTRY dot11MDCapabilityEntry[1]; + } DOT11_MD_CAPABILITY_ENTRY_LIST, *PDOT11_MD_CAPABILITY_ENTRY_LIST; + +``` + +This structure includes the following members: + +**uNumOfEntries** +Number of entries in the **dot11MDCapabilityEntry** array. A zero value for this member indicates an empty list of supported regulatory domains. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11MDCapabilityEntry** array requires. + +**dot11MDCapabilityEntry** +The list of supported regulatory domains. + +The data type for the elements of the **dot11MDCapabilityEntry** array is the DOT11\_MD\_CAPABILITY\_ENTRY structure. + +``` syntax +typedef struct _DOT11_MULTI_DOMAIN_CAPABILITY_ENTRY { ULONG + uMultiDomainCapabilityIndex; ULONG uFirstChannelNumber; + ULONG uNumberOfChannels; + LONG + lMaximumTransmitPowerLevel; } DOT11_MULTI_DOMAIN_CAPABILITY_ENTRY, + *PDOT11_MULTI_DOMAIN_CAPABILITY_ENTRY; +``` + +This structure includes the following members: + +**uMultiDomainCapabilityIndex** +Identifies this entry in the miniport driver's supported regulatory domain list. + +**uFirstChannelNumber** +The lowest channel number in the sub-band for the regulatory domain that is identified by the **dot11CountryString** MIB object. + +**uNumberOfChannels** +Total number of channels allowed in the sub-band for the regulatory domain that is identified by the **dot11CountryString** MIB object. + +**lMaximumTransmitPowerLevel** +The maximum transmit power, in dBm, allowed in the sub-band for the regulatory domain that is identified by the **dot11CountryString** MIB object. + +When OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY is queried, the miniport driver fails the query request under the following conditions: + +- If the **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the 802.11 station does not support multiple regulatory domains. In this situation, the miniport driver must return NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the 802.11 station has not enabled the support for multiple regulatory domains. In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 station has not completed an explicit scan initiated through a set of [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md), the miniport driver must return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure, including all entries in the **dot11MDCapabilityEntry** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, for example: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11MDCapabilityEntry** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure. The miniport driver must also copy the entire DOT11\_MD\_CAPABILITY\_ENTRY\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MULTI_DOMAIN_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-multicast-list.md b/windows-driver-docs-pr/network/oid-dot11-multicast-list.md new file mode 100644 index 0000000000..9b3b6b4479 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-multicast-list.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_MULTICAST\_LIST +author: windows-driver-content +description: OID\_DOT11\_MULTICAST\_LIST +ms.assetid: 5a27a01f-57d8-435c-a0a8-6ae671b350e2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_MULTICAST_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_MULTICAST\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_MULTICAST\_LIST object identifier (OID) requests that the miniport driver set its multicast address list to the specified list. + +When queried, this OID requests that the miniport driver return its list of multicast addresses. + +The data type for OID\_DOT11\_MULTICAST\_LIST is the [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +The miniport driver can determine the number of media access control (MAC) addresses in the multicast address list from the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter: + +``` + NumOfMulticastAddresses = (InformationBufferLength / sizeof(DOT11_MAC_ADDRESS) +``` + +The OID\_DOT11\_MULTICAST\_LIST OID can be set at any time, regardless of the miniport driver's current packet filter. After the packet filter is changed to enable any multicast address filter, the miniport driver must enable filtering on the 802.11 station using the current multicast address list. + +For more information about 802.11 packet filters, see [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md). + +The miniport driver must clear its multicast address list and disable multicast address filtering on the 802.11 station if any of the following occur: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station. + +The miniport driver must retain its current multicast address list following a call to its [*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) function. The miniport driver must also enable multicast filtering on the 802.11 station if the multicast address list contains one or more MAC addresses. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_MULTICAST_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-nic-power-state.md b/windows-driver-docs-pr/network/oid-dot11-nic-power-state.md new file mode 100644 index 0000000000..9aa98538b0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-nic-power-state.md @@ -0,0 +1,96 @@ +--- +title: OID\_DOT11\_NIC\_POWER\_STATE +author: windows-driver-content +description: OID\_DOT11\_NIC\_POWER\_STATE +ms.assetid: ed05b714-7cdf-4996-bc5d-ab9baa67e11b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_NIC_POWER_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_NIC\_POWER\_STATE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_NIC\_POWER\_STATE object identifier (OID) requests that the miniport driver set the Native 802.11 Operational **msDot11NICPowerState** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **msDot11NICPowerState** MIB object. + +The **msDot11NICPowerState** MIB object specifies the power state of the current PHY type on the 802.11 station. + +The miniport driver must retain the value of the **msDot11NICPowerState** MIB object through any of the following: + +- Resets of the 802.11 station through a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +- Resets of the miniport driver through a call to the driver's [*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) function. + +- Calls to the miniport driver's [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) or [*MiniportShutdownEx*](https://msdn.microsoft.com/library/windows/hardware/ff559449) function. The driver must restore the value of the **msDot11NICPowerState** MIB object and the power state of the current PHY type whenever the driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +The data type for OID\_DOT11\_NIC\_POWER\_STATE is a BOOLEAN value. A value of **TRUE** indicates that the PHY is turned on. In response to a value of **FALSE**, the miniport driver can either turn off the radio only for the current PHY, or it can turn off the radios for all supported PHYs. + +After OID\_DOT11\_NIC\_POWER\_STATE is set, the 802.11 station must do the following: + +- If the 802.11 station is performing an explicit scan operation initiated through a set of [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md), fail the set request by returning NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- After all PHYs that use the radio are turned off, turn off the radio. + +The following points apply to a miniport driver operating in Extensible Station (ExtSTA) mode: + +- The current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +- If the value of the **msDot11NICPowerState** MIB object is changed when OID\_DOT11\_NIC\_POWER\_STATE is set, the miniport driver must make an [NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED](ndis-status-dot11-phy-state-changed.md) indication. The miniport driver must also make this indication if the value of the **msDot11NICPowerState** MIB object is changed through a proprietary interface or OID implemented by the independent hardware vendor (IHV). + +- Some 802.11 NICs support a hardware setting on the computer for turning the PHY on or off. The ExtSTA **msDot11HardwarePHYState** MIB variable specifies the current hardware setting for the PHY. The 802.11 station must set the PHY's power state based on the **msDot11NICPowerState** and **msDot11HardwarePHYState** MIB variables. For more information about the **msDot11HardwarePHYState** MIB variable, see [NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED](ndis-status-dot11-phy-state-changed.md). + +If the value of the **msDot11NICPowerState** MIB object has not been previously set, the miniport driver must use a default value of **TRUE** for this MIB object. + +**Note**  If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the following requirements apply: +- The **msDot11NICPowerState** MIB object applies to the same PHY on all such MAC entities. + +- If the operating system enables or disables a PHY through an OID set on one of the MAC entities, the driver should apply that change to the PHY on all virtualized MAC entities. The driver should then send appropriate [NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED](ndis-status-dot11-phy-state-changed.md) indications for all MAC entities, both physical and virtual. + +- The driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_NIC_POWER_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-nic-specific-extension.md b/windows-driver-docs-pr/network/oid-dot11-nic-specific-extension.md new file mode 100644 index 0000000000..3364ff646f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-nic-specific-extension.md @@ -0,0 +1,63 @@ +--- +title: OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION +author: windows-driver-content +description: OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION +ms.assetid: 4d9194ca-4d40-4c83-a464-7f145f0a52b5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_NIC_SPECIFIC_EXTENSION Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The independent hardware vendor (IHV) uses the OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION object identifier (OID) to define proprietary method requests for its miniport driver. The IHV is responsible for defining the format of the data passed in the method requests of this OID. For more information about the method request type that is defined by OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION, see [**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710). + +**Note**  Miniport drivers that provide NIC-specific extensions should use OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION rather than vendor-defined OIDs. + +  + +The operating system does not use OID\_DOT11\_NIC\_SPECIFIC\_EXTENSION. This OID is reserved for use through calls to [**Dot11ExtNicSpecificExtension**](https://msdn.microsoft.com/library/windows/hardware/ff547526) made by the IHV Extensions DLL. The DLL calls this function to pass IHV-specific information to the miniport driver. For more information about the IHV Extensions DLL, see [Native 802.11 IHV Extensions DLL](https://msdn.microsoft.com/library/windows/hardware/ff560614). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_NIC_SPECIFIC_EXTENSION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-number-of-hopping-sets.md b/windows-driver-docs-pr/network/oid-dot11-number-of-hopping-sets.md new file mode 100644 index 0000000000..5bfa9e4196 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-number-of-hopping-sets.md @@ -0,0 +1,86 @@ +--- +title: OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS +author: windows-driver-content +description: OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS +ms.assetid: 8a61edff-9f9b-4e98-a2de-907d2d9fa836 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_NUMBER_OF_HOPPING_SETS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11NumberOfHoppingSets** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11NumberOfHoppingSets** MIB object defines the total number of sets of hopping patterns used by the current PHY type. + +**Note**   +Support for OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS is a ULONG value. + +The miniport driver fails a query of OID\_DOT11\_NUMBER\_OF\_HOPPING\_SETS under the following conditions: + +- The **dot11NumberOfHoppingSets** MIB object is only valid for the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_fhss**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_NUMBER_OF_HOPPING_SETS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-offload-network-list.md b/windows-driver-docs-pr/network/oid-dot11-offload-network-list.md new file mode 100644 index 0000000000..b7ff1f1a92 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-offload-network-list.md @@ -0,0 +1,74 @@ +--- +title: OID\_DOT11\_OFFLOAD\_NETWORK\_LIST +author: windows-driver-content +description: This OID supports Set operation. +ms.assetid: F404E428-4B82-45F3-9AFA-AABA213B6C2A +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_OFFLOAD_NETWORK_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_OFFLOAD\_NETWORK\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +This OID supports Set operation. OID\_DOT11\_OFFLOAD\_NETWORK\_LIST Set OID requests the Wi-Fi device to set up hardware to scan for networks in the offload list. Hardware should scan for all SSIDs on hinted channels and only interrupt Windows when it finds one or more networks with BSS's in the offload list. This list contains SSID's that are setup to auto-connect. Devices must configure the offload of all networks on the list or none when it returns failure. The offload-list may contain networks less or equal to the number of **uMaxNetworkOffloadListSize** in the [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) structure. The NIC should indicate when the network appears but not when the network disappears. If the device is in a low power state (D3), the NIC should wake Windows, to indicate a match within the NLO list. + +The NIC scans for offload network list in two phases, first fast-scan phase followed by the slow-scan phase. This is to allow a backoff from aggressive scanning to better improve battery efficiency. + +If the request is successful, the full list is offloaded and functional. If not successful, no entries in the list should be offloaded. If a device succeeds this request, it continues to function in this mode until Windows explicitly resets the OID. + +When a miniport driver receives an OID\_DOT11\_OFFLOAD\_NETWORK\_LIST with non-empty list, it starts to scan for networks. Once that initial scan is complete it follows the fast scan and slow scan schedule. It indicates [NDIS\_STATUS\_DOT11\_OFFLOAD\_NETWORK\_STATUS\_CHANGED](https://msdn.microsoft.com/library/windows/hardware/hh451702) when a newly discovered network is on the list, but not when one disappears from the list. A "newly" discovered network is a network that comes into range. A given network should only trigger an indication once during the lifetime of the NLO Set operation. + +The NIC should not scan if the radio is off even though NLO is configured. The NIC in low power state should wake Windows for offload network list change indications. Miniport drivers should prepare devices to wake up Windows prior to device entering a low power state. + +For example: + +FastScanPeriod=60 seconds + +FastScanIteration=15 + +SlowScanPeriod=1800 seconds + +Unless Windows issues a new offload list, the NIC will scan for offload network list every 60 seconds for 15 times. After 15 times, the NIC switches to SlowScanPeriod when the NIC will scan every 1800 seconds. + +In response to a [NDIS\_STATUS\_DOT11\_OFFLOAD\_NETWORK\_STATUS\_CHANGED](https://msdn.microsoft.com/library/windows/hardware/hh451702) indication, Windows may follow-up with a full scan and query for [OID\_DOT11\_ENUM\_BSS\_LIST](oid-dot11-enum-bss-list.md) to decide the best network from the visible networks in order to make a connection. For each indication, Windows may make a connection and subsequently clear the list. When Windows decides to make a connection, NWifi first issues a DOT11 reset which makes the miniport driver/NIC clear all offloads. Windows then evaluates and plumbs down a new network offload list once the connection is complete. Other protocol offloads may be plumbed down at this time. + +![network list offload example sequence showing calls down to the miniport driver and the hardware](images/nlo.png) + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_OFFLOAD_NETWORK_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-operation-mode-capability.md b/windows-driver-docs-pr/network/oid-dot11-operation-mode-capability.md new file mode 100644 index 0000000000..b92b6b01ac --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-operation-mode-capability.md @@ -0,0 +1,104 @@ +--- +title: OID\_DOT11\_OPERATION\_MODE\_CAPABILITY +author: windows-driver-content +description: When queried, the OID\_DOT11\_OPERATION\_MODE\_CAPABILITY object identifier (OID) requests that the miniport driver return the Native 802.11 operation modes that it supports. +ms.assetid: d56151e0-8390-4639-bb2f-8fd27c3ddcf4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_OPERATION_MODE_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_OPERATION\_MODE\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_OPERATION\_MODE\_CAPABILITY object identifier (OID) requests that the miniport driver return the Native 802.11 operation modes that it supports. + +The data type for this OID is the DOT11\_OPERATION\_MODE\_CAPABILITY structure. + +```ManagedCPlusPlus + typedef struct _DOT11_OPERATION_MODE_CAPABILITY { + ULONG uReserved; + ULONG uMajorVersion; + ULONG uMinorVersion; + ULONG uNumOfTxBuffers; + ULONG uNumOfRxBuffers; + ULONG uOpModeCapability; + } DOT11_OPERATION_MODE_CAPABILITY, *PDOT11_OPERATION_MODE_CAPABILITY; + +``` + +This structure includes the following members: + +**uReserved** +This member is reserved. The miniport driver must not modify the value of this member. + +**uMajorVersion** +The major version of the Native 802.11 framework that the miniport driver supports. For the Windows Vista operating system, the major version is two. + +**uMinorVersion** +The minor version of the Native 802.11 framework that the miniport driver supports. For the Windows Vista operating system, the minor version is zero. + +**uNumOfTxBuffers** +Maximum number of media access control (MAC) service data unit (MSDU) packets that the 802.11 station can hold in its transmit queue. The miniport driver must support a minimum transmit queue depth of 64. + +The value of this member must not include the number of transmit buffers that the 802.11 station uses to send packets on its own, such as Beacon packets or 802.11 control packets. + +**uNumOfRxBuffers** +Maximum number of MSDU packets that the 802.11 station can buffer in its receive queue. The miniport driver must support a minimum receive queue depth of 64. + +**uOpModeCapability** +A bitmask of the miniport driver's supported operation modes. This bitmask is defined through the following: + +DOT11\_OPERATION\_MODE\_EXTENSIBLE\_AP +Specifies that the miniport driver supports the Extensible Access Point (ExtAP) operation mode. + +DOT11\_OPERATION\_MODE\_EXTENSIBLE\_STATION +Specifies that the miniport driver supports the Extensible Station (ExtSTA) operation mode. + +DOT11\_OPERATION\_MODE\_NETWORK\_MONITOR +Specifies that the miniport driver supports the Network Monitor (NetMon) operation mode. + +For more information about the operation modes of a Native 802.11 miniport driver, see [Native 802.11 Operation Modes](https://msdn.microsoft.com/library/windows/hardware/ff560671). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_OPERATION_MODE_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-operational-rate-set.md b/windows-driver-docs-pr/network/oid-dot11-operational-rate-set.md new file mode 100644 index 0000000000..a26d223a1d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-operational-rate-set.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_OPERATIONAL\_RATE\_SET +author: windows-driver-content +description: OID\_DOT11\_OPERATIONAL\_RATE\_SET +ms.assetid: 4b22c1b2-1046-4e1c-880c-ab748f3ce1b0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_OPERATIONAL_RATE_SET Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_OPERATIONAL\_RATE\_SET + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_OPERATIONAL\_RATE\_SET object identifier (OID) requests that the miniport driver set the operational data rates to the specified value. + +When queried, this OID requests that the miniport driver return the set of operational data rates. + +The data type for OID\_DOT11\_OPERATIONAL\_RATE\_SET is the [**DOT11\_RATE\_SET**](https://msdn.microsoft.com/library/windows/hardware/ff548759) structure, based on the IEEE 802.11 **dot11OperationalRateSet** management information base (MIB) object. + +The operational rate set of the 802.11 station defines the rates at which the station can transmit data. The 802.11 station specifies the rates it supports in the Supported Rates information element (IE) of various 802.11 management frames, such as Beacon and Probe Response frames. For more information about the Supported Rates IE, refer to Clause 8.4.2.3 of the IEEE 802.11-2012 standard. + +The 802.11 station also uses the operational rate set to determine whether it can connect to a BSS based on the Supported Rates IE from Beacons or Probe Response frames received within the BSS network. For more information about this process, refer to Clause 6.3 of the IEEE 802.11-2012 standard. + +If the 802.11 station has not completed a scan request when OID\_DOT11\_OPERATIONAL\_RATE\_SET is set, it must use the specified operational rate set for the next 802.11 Probe Request frame that it transmits. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_OPERATIONAL_RATE_SET%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-optional-capability.md b/windows-driver-docs-pr/network/oid-dot11-optional-capability.md new file mode 100644 index 0000000000..ad6a6f5776 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-optional-capability.md @@ -0,0 +1,95 @@ +--- +title: OID\_DOT11\_OPTIONAL\_CAPABILITY +author: windows-driver-content +description: When queried, the OID\_DOT11\_OPTIONAL\_CAPABILITY object identifier (OID) requests that the miniport driver return the optional capabilities that the 802.11 station supports. +ms.assetid: ad6573ed-8c27-4075-975f-1b7673c564d8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_OPTIONAL_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_OPTIONAL\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_OPTIONAL\_CAPABILITY object identifier (OID) requests that the miniport driver return the optional capabilities that the 802.11 station supports. + +The data type for this OID is the DOT11\_OPTIONAL\_CAPABILITY structure. + +```ManagedCPlusPlus + typedef struct _DOT11_OPTIONAL_CAPABILITY { + ULONG uReserved; + BOOLEAN bDot11PCF; + BOOLEAN bDot11PCFMPDUTransferToPC; + BOOLEAN bStrictlyOrderedServiceClass; + } DOT11_OPTIONAL_CAPABILITY, *PDOT11_OPTIONAL_CAPABILITY; + +``` + +This structure includes the following members: + +**uReserved** +This member is reserved. The miniport driver must not modify the value of this member. + +**bDot11PCF** +Specifies whether the 802.11 station supports the Point Coordination Function (PCF). For more information about PCF, refer to Clauses 9.2.3 and 9.4 of the IEEE 802.11-2012 standard. + +**bDot11PCFMPDUTransferToPC** +Specifies whether the 802.11 station supports the delivery of received PCF MAC protocol data unit (MPDU)frames to the operating system. + +**Note**  If the miniport driver sets this member to **TRUE**, it must set the **bDot11PCF** member to **TRUE**. + +  + +**bStrictlyOrderedServiceClass** +Specifies whether the 802.11 station supports the StrictlyOrdered service class for MAC service data unit (MSDU) ordering. For more information about the StrictlyOrdered service class, refer to clause 5.1.3 of the IEEE 802.11-2012 standard. + +If the miniport driver sets the **bDot11PCF** member to **TRUE**, the 802.11 station must support the following PCF operations: + +- Maintenance of the contention-free period (CFP) structure and timing. + +- Deliveries of PCF MPDU frames from the operating system for transmit. + +When [OID\_DOT11\_CURRENT\_OPTIONAL\_CAPABILITY](oid-dot11-current-optional-capability.md) is queried, the miniport driver specifies the status of these optional capabilities. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_OPTIONAL_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-pbcc-option-implemented.md b/windows-driver-docs-pr/network/oid-dot11-pbcc-option-implemented.md new file mode 100644 index 0000000000..ed13d53682 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-pbcc-option-implemented.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_PBCC\_OPTION\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_PBCC\_OPTION\_IMPLEMENTED +ms.assetid: 38ef6940-05c1-42e4-a19e-68155f609239 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PBCC_OPTION_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PBCC\_OPTION\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_PBCC\_OPTION\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11b **dot11PBCCOptionImplemented** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11PBCCOptionImplemented** MIB object specifies whether the current PHY type supports enabled packet binary convolutional code (PBCC) modulation. For more information about PBCC modulation, refer to Clause 18.4.6.6 of the IEEE 802.11b-1999 standard. + +The data type for OID\_DOT11\_PBCC\_OPTION\_IMPLEMENTED is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports PBCC modulation. + +The **dot11ERPPBCCOptionImplemented** MIB object is only valid for the following PHY types: + +- High-rate direct-sequence spread spectrum (HRDSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_hrdsss** or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PBCC_OPTION_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-permanent-address.md b/windows-driver-docs-pr/network/oid-dot11-permanent-address.md new file mode 100644 index 0000000000..7077e3d8e1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-permanent-address.md @@ -0,0 +1,59 @@ +--- +title: OID\_DOT11\_PERMANENT\_ADDRESS +author: windows-driver-content +description: OID\_DOT11\_PERMANENT\_ADDRESS +ms.assetid: f7830cd0-2e9e-4d11-b027-106b990299d0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PERMANENT_ADDRESS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PERMANENT\_ADDRESS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_PERMANENT\_ADDRESS object identifier (OID) requests that the miniport driver return the IEEE media access control (MAC) address encoded in the NIC hardware. + +The data type for this OID is the [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PERMANENT_ADDRESS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-pmkid-list.md b/windows-driver-docs-pr/network/oid-dot11-pmkid-list.md new file mode 100644 index 0000000000..9ce03f54b6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-pmkid-list.md @@ -0,0 +1,175 @@ +--- +title: OID\_DOT11\_PMKID\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_PMKID\_LIST object identifier (OID) requests that the miniport driver flush its cache of pairwise master key identifiers (PMKIDs) and add the PMKID entries from the specified list to its cache. +ms.assetid: 815a29e6-29f6-4a7d-82cb-40d4d6cedc25 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PMKID_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PMKID\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_PMKID\_LIST object identifier (OID) requests that the miniport driver flush its cache of pairwise master key identifiers (PMKIDs) and add the PMKID entries from the specified list to its cache. + +When queried, this OID requests that the miniport driver return a list of the entries from its PMKID cache. + +The 802.11 station uses the PMKID cache for preauthentication to access points that have enabled the Robust Security Network Association (RSNA) authentication algorithm. If the 802.11 station is associating or reassociating to a BSSID that matches an entry in its PMKID cache, the 802.11 station must use the PMKID data in the RSN information element (RSN IE) of its Association or Reassociation frame. For more information about the RSN IE, refer to Clause 7.3.2.25 of the 802.11i-2004 standard. + +**Note**  Support for OID\_DOT11\_PMKID\_LIST is mandatory if the 802.11 station supports PMKID caching for the **DOT11\_AUTH\_ALGO\_RSNA** authentication algorithms. The miniport driver specifies its support for this authentication algorithm when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for OID\_DOT11\_PMKID\_LIST is the DOT11\_PMKID\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_PMKID_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_PMKID_ENTRY PMKIDs[1]; + } DOT11_PMKID_LIST, *PDOT11_PMKID_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_PMKID\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_PMKID\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_PMKID\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **PMKIDs** array. A zero value for this member indicates an empty list of PMKID entries. + +**uTotalNumOfEntries** +Maximum number of entries that the **PMKIDs** array can contain. + +**PMKIDs** +The list of PMKID entries. + +The data type for the elements of the **PMKIDs** array is the DOT11\_PMKID\_ENTRY structure. + +``` syntax +typedef struct DOT11_PMKID_ENTRY { + DOT11_MAC_ADDRESS BSSID; + DOT11_PMKID_VALUE PMKID; + ULONG uFlags; + } DOT11_PMKID_ENTRY, *PDOT11_PMKID_ENTRY; +``` + +This structure includes the following members: + +**BSSID** +The BSSID of the target access point (AP) with which the 802.11 station associates. For more information about the data type of this member, see [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681). + +**PMKID** +The PMKID value. For more information about the data type of this member, see [**DOT11\_PMKID\_VALUE**](dot11-pmkid-value.md). + +The 802.11 station uses this value in the RSN information element (IE) of the 802.11 Association or Reassociation Request frames when connecting to the target BSSID. + +**Note**  When OID\_DOT11\_PMKID\_LIST is set, the entries in the **PMKIDs** array might be different than the entries in the list of PMKID candidates that the miniport driver specified when it made a previous [NDIS\_STATUS\_DOT11\_PMKID\_CANDIDATE\_LIST](ndis-status-dot11-pmkid-candidate-list.md) indication. + +  + +**uFlags** +This member is reserved and must be set to zero. + +When OID\_DOT11\_PMKID\_LIST is set, the miniport driver must do the following: + +- If the **uNumOfEntries** member has a value greater than the value of **uPMKIDCacheSize** that the driver previously returned through a query of [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md), fail the set request by returning NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 station does not support the **DOT11\_AUTH\_ALGO\_RSNA** authentication algorithm, fail the request by returning NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the 802.11 station has not enabled the **DOT11\_AUTH\_ALGO\_RSNA** authentication algorithm, fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Ignore any list entry that has a **BSSID** member that is not in the miniport driver's desired BSSID list. For more information about the desired BSSID list, see [OID\_DOT11\_DESIRED\_BSSID\_LIST](oid-dot11-desired-bssid-list.md). + + If none of the entries in the list has a **BSSID** member that matches an entry in the miniport driver's desired BSSID list, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- Ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + + ``` + FIELD_OFFSET(DOT11_PMKID_LIST, PMKIDs) + uNumOfEntries * sizeof(DOT11_PMKID_ENTRY)) + ``` + +When OID\_DOT11\_PMKID\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_PMKID\_LIST structure, including all entries in the **PMKIDs** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_PMKID\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **PMKIDs** array. + + For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_PMKID\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_PMKID\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_PMKID\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **PMKIDs** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_PMKID\_LIST structure. The miniport driver must also copy the entire DOT11\_PMKID\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default PMKID cache is an empty list with **uNumEntries** set to zero. The miniport driver must set this cache to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made. The miniport driver must unconditionally set the PMKID cache to its default value whenever OID\_DOT11\_RESET\_REQUEST is set. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PMKID_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-port-state-notification.md b/windows-driver-docs-pr/network/oid-dot11-port-state-notification.md new file mode 100644 index 0000000000..fe5d649066 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-port-state-notification.md @@ -0,0 +1,96 @@ +--- +title: OID\_DOT11\_PORT\_STATE\_NOTIFICATION +author: windows-driver-content +description: When set, the OID\_DOT11\_PORT\_STATE\_NOTIFICATION object identifier (OID) indicates the status of the data port used for network access to the access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS networks) with which the 802.11 station is associated. +ms.assetid: 2696f8a4-d9dd-4b17-86a2-02d9855f9b87 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PORT_STATE_NOTIFICATION Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PORT\_STATE\_NOTIFICATION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_PORT\_STATE\_NOTIFICATION object identifier (OID) indicates the status of the data port used for network access to the access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS networks) with which the 802.11 station is associated. + +The data type for OID\_DOT11\_PORT\_STATE\_NOTIFICATION is the DOT11\_PORT\_STATE\_NOTIFICATION structure. + +```ManagedCPlusPlus + typedef struct DOT11_PORT_STATE_NOTIFICATION { + NDIS_OBJECT_HEADER Header; + DOT11_MAC_ADDRESS PeerMac; + BOOLEAN bOpen; + } DOT11_PORT_STATE_NOTIFICATION, *PDOT11_PORT_STATE_NOTIFICATION; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_PORT\_STATE\_NOTIFICATION structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_PORT\_STATE\_NOTIFICATION\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_PORT\_STATE\_NOTIFICATION). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**PeerMac** +The media access control (MAC) address of the AP or peer station with which the 802.11 station is associated. + +**bOpen** +The data port state. If **bOpen** is **TRUE**, the port is open for sending and receiving data packets. + +The actions performed by the miniport driver following the set request of OID\_DOT11\_PORT\_STATE\_NOTIFICATION are specific to the implementation by the independent hardware vendor (IHV). + +For more information about port-based network access, see [Port Access Management](https://msdn.microsoft.com/library/windows/hardware/ff570184). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PORT_STATE_NOTIFICATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-power-mgmt-mode-status.md b/windows-driver-docs-pr/network/oid-dot11-power-mgmt-mode-status.md new file mode 100644 index 0000000000..3dc98c465b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-power-mgmt-mode-status.md @@ -0,0 +1,52 @@ +--- +title: OID\_DOT11\_POWER\_MGMT\_MODE\_STATUS +author: windows-driver-content +description: This OID supports Query operation. Windows issues this OID to query the status of the power mode. +ms.assetid: 6B232446-3CF7-44F8-A1C9-6431D28F3EDA +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_POWER_MGMT_MODE_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_POWER\_MGMT\_MODE\_STATUS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +This OID supports Query operation. Windows issues this OID to query the status of the power mode. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_POWER_MGMT_MODE_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-power-mgmt-request.md b/windows-driver-docs-pr/network/oid-dot11-power-mgmt-request.md new file mode 100644 index 0000000000..ad2341063a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-power-mgmt-request.md @@ -0,0 +1,129 @@ +--- +title: OID\_DOT11\_POWER\_MGMT\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_POWER\_MGMT\_REQUEST +ms.assetid: 5b79d5e4-7b0a-4c70-93c6-957385356244 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_POWER_MGMT_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_POWER\_MGMT\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_POWER\_MGMT\_REQUEST object identifier (OID) requests that the miniport driver set its Extensible Station (ExtSTA) **msDot11PowerSavingLevel** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11PowerSavingLevel** MIB object. + +The **msDot11PowerSavingLevel** MIB object specifies the power management mode of the 802.11 station. + +The data type for OID\_DOT11\_POWER\_MGMT\_REQUEST is a ULONG value, which specifies the level of power-saving activity performed by the 802.11 station. + +The following power-saving levels are defined: + +DOT11\_POWER\_SAVING\_NO\_POWER\_SAVING +Specifies no power-saving activity performed by the 802.11 station. + +**Note**  This is the default value for the **msDot11PowerSavingLevel** MIB object. + +  + +DOT11\_POWER\_SAVING\_FAST\_PSP +Specifies a power save polling (PSP) mode that uses the fastest power-saving mode. This power mode must provide the best combination of network performance and power usage. + +DOT11\_POWER\_SAVING\_MAX\_PSP +Specifies a PSP mode that uses the maximum (MAX) power saving capabilities. The MAX power save mode results in the greatest power savings for the radio on the 802.11 station. + +DOT11\_POWER\_SAVING\_MAXIMUM\_LEVEL +Specifies a proprietary PSP mode implemented by the independent hardware vendor (IHV) that exceeds the DOT11\_POWER\_SAVING\_MAX\_PSP power-saving level. + +**Note**  When the miniport driver receives an [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) method request the miniport driver must reset the **msDot11PowerSavingLevel** MIB object to its default value under the following conditions: +- When MIB values for the MAC and/or PHY are reset to their default values only if **bSetDefaultMIB** is set to TRUE. +- When MAC or PHY values are affected by the value of the **dot11ResetType** member. + +  + +The 802.11 station is required to support power-saving levels of DOT11\_POWER\_SAVING\_FAST\_PSP and DOT11\_POWER\_SAVING\_MAX\_PSP. + +After the power-saving levels are changed to any value except DOT11\_POWER\_SAVING\_NO\_POWER\_SAVING, the 802.11 station must do the following: + +- If the 802.11 station is connected to a basic service set (BSS) network: + + - If its transmit queue is not empty, announce its power management mode in the next packet it transmits. It does this by setting the Power Management subfield of the Frame Control field in the 802.11 MAC header of the transmitted frame. + + For more information about the Power Management subfield, refer to Clause 8.2.4.1.7 of the IEEE 802.11-2012 standard. + + - If its transmit queue is empty, announce its power mode by creating and transmitting a frame containing only the 802.11 MAC header. + + - After entering a power-save state, perform the power management procedures defined in Clause 10.2 of the IEEE 802.11-2012 standard. + +- If the 802.11 station is not connected to a BSS network: + + - If the radio is turned on and the Native 802.11 Operational **msDot11NICPowerState** management information base (MIB) object is set to **TRUE**, turn off the radio and only turn on the radio when performing scan operations. + + For more information about the **msDot11NICPowerState** MIB object, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + + For more information about scan operations, see [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md). + + - Retain the current value of the **msDot11NICPowerState** MIB object whenever the 802.11 station turns the radio off or on. + + - When the radio is turned off or on, the miniport driver must not make an [NDIS\_STATUS\_DOT11\_PHY\_STATE\_CHANGED](ndis-status-dot11-phy-state-changed.md) indication. + +The miniport driver must not change the power state of the 802.11 station when the driver's [*MiniportDevicePnPEventNotify*](https://msdn.microsoft.com/library/windows/hardware/ff559369) function is called for the **NdisDevicePnPEventPowerProfileChanged** event. The miniport driver must ignore this event and only make changes to the 802.11 station's power state when OID\_DOT11\_POWER\_MGMT\_REQUEST is set. + +Starting with Windows 7, if the wireless adapter is set to a **Medium Power Saving** setting, the operating system enables DOT11\_POWER\_SAVING\_MAX\_PSP on the 802.11 station if one of the following is true: + +- The wireless adapter is not associated with an infrastructure network. + +- The wireless adapter is associated with an infrastructure network and the associated AP supports the Automatic Power Save Delivery (APSD) - Power Save mode. + +**Note**  **Medium Power Saving** is the default **Power Saving Mode** behavior when the computer is in the **Balanced** power plan. These adapter settings are accessed through the **Power Options** control panel. + +  + +Starting with Windows 8, supporting Wi-Fi Direct requires that this OID is used to configure power level for all Wi-Fi Direct ports. The port availability period and power saving features are adapted to the power level requested. + +When the power-saving level is set to DOT11\_POWER\_SAVING\_NO\_POWER\_SAVING the miniport should disable all power saving mechanisms on the WFD port, and provide the specific port maximum access to the radio. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_POWER_MGMT_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-powermgmt-mode-auto-enabled.md b/windows-driver-docs-pr/network/oid-dot11-powermgmt-mode-auto-enabled.md new file mode 100644 index 0000000000..7495d73852 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-powermgmt-mode-auto-enabled.md @@ -0,0 +1,54 @@ +--- +title: OID\_DOT11\_POWER\_MGMT\_MODE\_AUTO\_ENABLED +author: windows-driver-content +description: This OID supports Set operation. +ms.assetid: 56817EBC-EF21-4013-8298-92944CD05C11 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_POWER_MGMT_MODE_AUTO_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_POWER\_MGMT\_MODE\_AUTO\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +This OID supports Set operation. If a miniport driver reports that it supports automatic Power Save Mode (Auto-PSM) capability, then Windows issues this OID when appropriate. For example, when the power policy UX does not set Wi-Fi power to "Maximum Performance". On receipt of this OID, devices should operate intelligently in a power efficient way, and transition in and out of PS mode as appropriate. + +![default power save mode example sequence showing calls from ndis to nwifi and then to the miniport driver](images/wifiautopsm.png) + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_POWER_MGMT_MODE_AUTO_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-preferred-mac.md b/windows-driver-docs-pr/network/oid-dot11-preferred-mac.md new file mode 100644 index 0000000000..ffe334c24e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-preferred-mac.md @@ -0,0 +1,57 @@ +--- +title: OID\_DOT11\_PREFERRED\_MAC +author: windows-driver-content +description: OID\_DOT11\_PREFERRED\_MAC +ms.assetid: 35e28d86-e546-4805-bdc5-73e0e775c8e6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PREFERRED_MAC Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PREFERRED\_MAC + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The OID\_DOT11\_PREFERRED\_MAC object identifier (OID) is reserved for system use. Do not use it in your driver. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PREFERRED_MAC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-privacy-exemption-list.md b/windows-driver-docs-pr/network/oid-dot11-privacy-exemption-list.md new file mode 100644 index 0000000000..f838bb750d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-privacy-exemption-list.md @@ -0,0 +1,138 @@ +--- +title: OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST object identifier (OID) requests that the miniport driver set its Extensible Station (ExtSTA) msDot11PrivacyExemptionList management information base (MIB) object to the specified data. +ms.assetid: 0867c5b2-035e-47c1-970b-a928f6e8aab9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_PRIVACY_EXEMPTION_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST object identifier (OID) requests that the miniport driver set its Extensible Station (ExtSTA) **msDot11PrivacyExemptionList** management information base (MIB) object to the specified data. + +When queried, this OID requests that the miniport driver return the value of the **msDot11PrivacyExemptionList** MIB object. + +The **msDot11PrivacyExemptionList** MIB object contains a list of exemptions for packet decryption. The 802.11 station applies these exemptions to packets it receives that match the IEEE EtherType value specified for the exemption. + +**Note**  Support for OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST is mandatory if the 802.11 station supports any cipher algorithms. The miniport driver returns a list of supported cipher algorithms when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST is the DOT11\_PRIVACY\_EXEMPTION\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_PRIVACY_EXEMPTION_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_PRIVACY_EXEMPTION PrivacyExemptionEntries[1]; + } DOT11_PRIVACY_EXEMPTION_LIST, *PDOT11_PRIVACY_EXEMPTION_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_PRIVACY\_EXEMPTION\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_PRIVACY\_EXEMPTION\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_PRIVACY\_EXEMPTION\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **PrivacyExemptionEntries** array. A zero value for this member indicates an empty privacy exemption list. + +**uTotalNumOfEntries** +Maximum number of entries that the **PrivacyExemptionEntries** array can contain. + +**PrivacyExemptionEntries** +The list of exempted EtherTypes. Each entry in the list is formatted as a [**DOT11\_PRIVACY\_EXEMPTION**](https://msdn.microsoft.com/library/windows/hardware/ff548756) structure. + +When OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST is set, the miniport driver should ensure that the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's OidRequest parameter is at least the value returned by the following formula: + +``` + FIELD_OFFSET(DOT11_PRIVACY_EXEMPTION_LIST, PrivacyExemptionEntries) + uNumOfEntries * sizeof(DOT11_PRIVACY_EXEMPTION)) +``` + +When OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST is set, the miniport driver must fail the set request if the **uNumOfEntries** member has a value greater than the value of **uPrivacyExemptionListSize** that the driver previously returned through a query of [OID\_DOT11\_EXTSTA\_CAPABILITY](oid-dot11-extsta-capability.md). In this situation, the miniport driver must return NDIS\_STATUS\_INVALID\_LENGTH from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +When OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure, including all entries in the **PrivacyExemptionEntries** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **PrivacyExemptionEntries** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_PRIVACY\_EXEMPTION\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **PrivacyExemptionEntries** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure. The miniport driver must also copy the entire DOT11\_PRIVACY\_EXEMPTION\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +The default for the **msDot11PrivacyExemptionList** MIB object is an empty list with **uNumEntries** set to zero. The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_PRIVACY_EXEMPTION_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-qos-params.md b/windows-driver-docs-pr/network/oid-dot11-qos-params.md new file mode 100644 index 0000000000..e6ee9f7e64 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-qos-params.md @@ -0,0 +1,100 @@ +--- +title: OID\_DOT11\_QOS\_PARAMS +author: windows-driver-content +description: When set, the OID\_DOT11\_QOS\_PARAMS object identifier (OID) requests that the miniport driver set quality of service (QoS) parameters for the 802.11 station. +ms.assetid: c7f767bb-95ff-4d66-b0ca-0a658c31dbb0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_QOS_PARAMS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_QOS\_PARAMS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_QOS\_PARAMS object identifier (OID) requests that the miniport driver set quality of service (QoS) parameters for the 802.11 station. + +The data type for OID\_DOT11\_QOS\_PARAMS is the DOT11\_QOS\_PARAMS structure. + +```ManagedCPlusPlus + typedef struct DOT11_QOS_PARAMS { + NDIS_OBJECT_HEADER Header; + UCHAR ucEnabledQoSProtocolFlags; + } DOT11_QOS_PARAMS, *PDOT11_QOS_PARAMS; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_QOS\_PARAMS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_QOS\_PARAMS\_REVISION\_1 + +**Size** +This member must be set to sizeof(OID\_DOT11\_QOS\_PARAMS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**ucEnabledQoSProtocolFlags** +A set of flags that specify the quality of service (QoS) protocols enabled on the NIC. This member is either zero or a bitwise OR combination of the following flags: + +DOT11\_QOS\_PROTOCOL\_FLAG\_WMM +If the NIC supports the 802.11 WMM standard and this flag is set, the 802.11 WMM QoS protocol is enabled. Otherwise, the 802.11 WMM QoS protocol is disabled. + +DOT11\_QOS\_PROTOCOL\_FLAG\_11E +If the NIC supports the 802.11e standard and this flag is set, the 802.11e QoS protocol is enabled. Otherwise, the 802.11e QoS protocol is disabled. + +The default value of **ucEnabledQoSProtocolFlags** is the **ucSupportedQoSProtocolFlags** member of the [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) structure. + +The miniport driver must fail a set request with error code NDIS\_STATUS\_INVALID\_STATE if the 802.11 station is in any state except the initialization (INIT) state. + +When queried, OID\_DOT11\_QOS\_PARAMS requests that the miniport driver return the value of the **msDot11QoSParams** MIB object. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_QOS_PARAMS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-random-table-flag.md b/windows-driver-docs-pr/network/oid-dot11-random-table-flag.md new file mode 100644 index 0000000000..f55720d3ee --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-random-table-flag.md @@ -0,0 +1,87 @@ +--- +title: OID\_DOT11\_RANDOM\_TABLE\_FLAG +author: windows-driver-content +description: OID\_DOT11\_RANDOM\_TABLE\_FLAG +ms.assetid: d8a42690-dd37-494f-b06a-04364a3f9637 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_RANDOM_TABLE_FLAG Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_RANDOM\_TABLE\_FLAG + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_RANDOM\_TABLE\_FLAG object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11d **dot11RandomTableFlag** MIB object for the current PHY type on the 802.11 station. + +The **dot11RandomTableFlag** MIB object specifies whether the current PHY type uses hopping patterns from the Random Table field of the Hopping Pattern Table information element (IE). For more information about this IE, refer to Clause 7.3.2.14 of the IEEE 802.11d-2001 standard. + +**Note**  Support for OID\_DOT11\_RANDOM\_TABLE\_FLAG is mandatory if the NIC supports the **dot11\_phy\_type\_fhss** PHY type and more than one regulatory domain. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for OID\_DOT11\_RANDOM\_TABLE\_FLAG is a BOOLEAN value. + +If the **dot11RandomTableFlag** MIB object is **TRUE**, the 802.11 station determines its hopping patterns from the Random Table field of the Hopping Pattern Table IE. If **dot11RandomTableFlag** is **FALSE**, the 802.11 station determines its hopping patterns through the Hop Index Method as defined in Clause 9.9.2.1 of the IEEE 802.11d-2001 standard. + +When queried by OID\_DOT11\_RANDOM\_TABLE\_FLAG, the miniport driver fails the request under the following conditions: + +- The **dot11RandomTableFlag** MIB object is valid for only the frequency-hopping spread spectrum (FHSS) PHY type. If the current PHY type is not set to dot11\_phy\_type\_fhss, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the IEEE 802.11d **dot11MultiDomainCapabilityImplemented** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityImplemented** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md). + +- If the IEEE 802.11d **dot11MultiDomainCapabilityEnabled** MIB object is **FALSE**, the miniport driver must fail the request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + For more information about the **dot11MultiDomainCapabilityEnabled** MIB object, see [OID\_DOT11\_MULTI\_DOMAIN\_CAPABILITY\_ENABLED](oid-dot11-multi-domain-capability-enabled.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_RANDOM_TABLE_FLAG%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-recv-sensitivity-list.md b/windows-driver-docs-pr/network/oid-dot11-recv-sensitivity-list.md new file mode 100644 index 0000000000..8303732f91 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-recv-sensitivity-list.md @@ -0,0 +1,137 @@ +--- +title: OID\_DOT11\_RECV\_SENSITIVITY\_LIST +author: windows-driver-content +description: When queried, the OID\_DOT11\_RECV\_SENSITIVITY\_LIST object identifier (OID) requests that the miniport driver return the list of receive sensitivity ranges for all data rates supported on a PHY. +ms.assetid: 6220b866-b914-4bc9-9a26-13f2109736e6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_RECV_SENSITIVITY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_RECV\_SENSITIVITY\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_RECV\_SENSITIVITY\_LIST object identifier (OID) requests that the miniport driver return the list of receive sensitivity ranges for all data rates supported on a PHY. The miniport driver returns the receive sensitivity list for the PHY that is specified in the query request. + +The data type for this OID is the DOT11\_RECV\_SENSITIVITY\_LIST structure. + +```ManagedCPlusPlus + typedef struct _DOT11_RECV_SENSITIVITY_LIST { + union { + DOT11_PHY_TYPE dot11PhyType; + ULONG uPhyId; + }; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_RECV_SENSITIVITY dot11RecvSensitivity[1]; +} DOT11_RECV_SENSITIVITY_LIST, * PDOT11_RECV_SENSITIVITY_LIST; + +``` + +This structure includes the following members: + +**dot11PhyType** +The PHY type queried for the receive sensitivity list. The PHY type is defined by the [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) enumeration. + +If the 802.11 station does not support the specified PHY type, the miniport driver must fail the query request by returning NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**Note**  The miniport driver must not use this member if it is operating in Extensible Station (ExtSTA) mode. + +  + +**uPhyId** +The identifier (ID) of the PHY that is queried for the receive sensitivity list. The PHY ID is the index within the list of supported PHYs returned by the driver through a query of [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +If the ID is invalid, the miniport driver must fail the query request by returning NDIS\_STATUS\_BAD\_VERSION from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**Note**  The miniport driver must use this member if it is operating in ExtSTA mode. + +  + +**uNumOfEntries** +Number of entries in the **dot11RecvSensitivity** array. A zero value for this member indicates an empty receive sensitivity list. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11RecvSensitivity** array requires. + +**dot11RecvSensitivity** +The receive sensitivity list for the PHY that is specified by the **dot11PhyType** member. + +The data type for the elements of the **dot11RecvSensitivity** array is the DOT11\_RECV\_SENSITIVITY structure. + +``` syntax +typedef struct _DOT11_RECV_SENSITIVITY { UCHAR ucDataRate; + LONG lRSSIMin; + LONG + lRSSIMax; } DOT11_RECV_SENSITIVITY, *PDOT11_RECV_SENSITIVITY; +``` + +This structure includes the following members: + +**ucDataRate** +A data rate supported by the PHY that is specified by the **dot11PhyType** member. The miniport driver must specify a data rate from 2 through 127 and in units of 500 kilobits per second (kbps). + +**lRSSIMin** +The minimum receive signal strength indication (RSSI) value, in units of decibels referenced to 1.0 milliwatts (dBm), for the data rate specified by the **ucDataRate** member. + +**lRSSIMax** +The maximum RSSI value, in units of dBm, for the data rate that is specified by the **ucDataRate** member. + +When OID\_DOT11\_RECV\_SENSITIVITY\_LIST is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_RECV\_SENSITIVITY\_LIST structure, including all entries in the **dot11RecvSensitivity** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as shown in the following list: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_RECV\_SENSITIVITY\_LIST structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_RECV\_SENSITIVITY\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_RECV\_SENSITIVITY\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_RECV\_SENSITIVITY\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11RecvSensitivity** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_RECV\_SENSITIVITY\_LIST structure. The miniport driver must also copy the entire DOT11\_RECV\_SENSITIVITY\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_RECV_SENSITIVITY_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-reg-domains-support-value.md b/windows-driver-docs-pr/network/oid-dot11-reg-domains-support-value.md new file mode 100644 index 0000000000..237d01d704 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-reg-domains-support-value.md @@ -0,0 +1,173 @@ +--- +title: OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE +author: windows-driver-content +description: When queried, the OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE object identifier (OID) requests that the miniport driver return the list of regulatory domains supported by the Physical Layer Convergence Procedure (PLCP) and Physical Media Dependent (PMD) sublayers of the current PHY type on the 802.11 station. +ms.assetid: 0449cb9e-02cb-4a23-a360-a6db1ac2b29d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_REG_DOMAINS_SUPPORT_VALUE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE object identifier (OID) requests that the miniport driver return the list of regulatory domains supported by the Physical Layer Convergence Procedure (PLCP) and Physical Media Dependent (PMD) sublayers of the current PHY type on the 802.11 station. + +The data type for OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE is the DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure. + +```ManagedCPlusPlus + typedef struct _DOT11_REG_DOMAINS_SUPPORT_VALUE { + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_REG_DOMAIN_VALUE dot11RegDomainValue[1]; + } DOT11_REG_DOMAINS_SUPPORT_VALUE, *PDOT11_REG_DOMAINS_SUPPORT_VALUE; + +``` + +This structure includes the following members: + +**uNumOfEntries** +Number of entries in the **dot11RegDomainValue** array. A zero value for this member indicates an empty list of supported regulatory domains. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11RegDomainValue** array requires. + +**dot11RegDomainValue** +The list of supported regulatory domains. + +The data type for the elements of the **dot11RegDomainValue** array is the DOT11\_REG\_DOMAIN\_VALUE structure. + +``` syntax +typedef struct _DOT11_REG_DOMAIN_VALUE { ULONG uRegDomainsSupportIndex; + ULONG + uRegDomainsSupportValue; } DOT11_REG_DOMAIN_VALUE, *PDOT11_REG_DOMAIN_VALUE; +``` + +This structure includes the following members: + +**uRegDomainsSupportIndex** +Identifies this entry in the miniport driver's supported regulatory domain list. + +**uRegDomainsSupportValue** +The value of the regulatory domain, which is defined in the following table. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameValueRegulatory domain

DOT11_REG_DOMAIN_OTHER

0x00000000

Defined by country code settings

DOT11_REG_DOMAIN_FCC

0x00000010

United States

DOT11_REG_DOMAIN_DOC

0x00000020

Canada

DOT11_REG_DOMAIN_ETSI

0x00000030

Most of Europe

DOT11_REG_DOMAIN_SPAIN

0x00000031

Spain

DOT11_REG_DOMAIN_FRANCE

0x00000032

France

DOT11_REG_DOMAIN_MKK

0x00000040

Japan

+ +  + +When OID\_DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure, including all entries in the **dot11RegDomainValue** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, for example: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to than the length, in bytes, of the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11RegDomainValue** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure. The miniport driver must also copy the entire DOT11\_REG\_DOMAINS\_SUPPORT\_VALUE structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_REG_DOMAINS_SUPPORT_VALUE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-reset-request.md b/windows-driver-docs-pr/network/oid-dot11-reset-request.md new file mode 100644 index 0000000000..24d9ae9a57 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-reset-request.md @@ -0,0 +1,199 @@ +--- +title: OID\_DOT11\_RESET\_REQUEST +author: windows-driver-content +description: When a method request of the OID\_DOT11\_RESET\_REQUEST OID is made, the miniport driver must reset the specified IEEE layers of the 802.11 station and transition to the initialization (INIT) state of the current operation mode. +ms.assetid: 1338f6fa-fe87-4c10-8c32-6525561354e0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_RESET_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_RESET\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When a method request of the OID\_DOT11\_RESET\_REQUEST OID is made, the miniport driver must reset the specified IEEE layers of the 802.11 station and transition to the initialization (INIT) state of the current operation mode. For more information about the method request type, see [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710). + +The data type for this OID is the DOT11\_RESET\_REQUEST structure. + +```ManagedCPlusPlus + typedef struct _DOT11_RESET_REQUEST { + DOT11_RESET_TYPE dot11ResetType; + DOT11_MAC_ADDRESS dot11MacAddress; + BOOLEAN bSetDefaultMIB; + } DOT11_RESET_REQUEST, *PDOT11_RESET_REQUEST; + +``` + +This structure includes the following members: + +**dot11ResetType** +The IEEE layer to be reset on the 802.11 station. The data type for this member is the DOT11\_RESET\_TYPE enumeration: + +**dot11\_reset\_type\_phy** +Only the PHY layer is reset. + +**dot11\_reset\_type\_mac** +Only the MAC layer is reset. + +**dot11\_reset\_type\_phy\_and\_mac** +Both the PHY and MAC layers are reset. + +**Note**  A miniport driver operating in Extensible Station (ExtSTA) mode must only support the reset type of **dot11\_reset\_type\_phy\_and\_mac**. In this situation, the driver must reset the MAC and all PHY layers supported on the 802.11 station. + +  + +**dot11MacAddress** +The unicast media access control (MAC) address used by the 802.11 station following the reset. This member can be used to configure a locally administered MAC address on the 802.11 station. + +The miniport driver must not ignore this member if **dot11ResetType** is set to **dot11\_reset\_type\_mac** or **dot11\_reset\_type\_phy\_and\_mac**. + +**bSetDefaultMIB** +The 802.11 station resets the specified IEEE layers and resets the 802.11 management information base (MIB) objects of the IEEE layer to their default values. The default values are mostly defined by the miniport implementation. However, some Native 802.11 MIB objects have explicit default values defined, such as [OID\_DOT11\_RTS\_THRESHOLD](oid-dot11-rts-threshold.md) and [OID\_DOT11\_SHORT\_RETRY\_LIMIT](oid-dot11-short-retry-limit.md). For more information about the default values for the Native 802.11 MIB objects, see [IEEE 802.11 MIB Objects](https://msdn.microsoft.com/library/windows/hardware/ff553782). + +The Native 802.11 miniport driver must follow these guidelines when it resets the 802.11 MIB objects to their default values: + +- In a call to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function, if the Native 802.11 miniport driver sets *MiniportAttributes-*> **Native\_802\_11\_Attributes**-> **Header-**> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1, the driver must always reset the 802.11 MIB objects to their default value regardless of the value of the **bSetDefaultMIB** member. + +- In a call to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function, if the Native 802.11 miniport driver sets *MiniportAttributes-*> **Native\_802\_11\_Attributes**-> **Header-**> **Revision** to a higher revision number, the driver should reset the 802.11 MIB objects to their default value only when the value of the **bSetDefaultMIB** member is set to **TRUE**. + + If this member is **FALSE**, the 802.11 station resets the specified IEEE layers but retains the current values of the 802.11 MIB objects. + +When the method request of OID\_DOT11\_RESET\_REQUEST is made, the miniport driver can do one of the following: + +- Wait for the reset operation to complete before completing the set request. + +- Initiate the reset operation and complete the set request. In this situation, the miniport driver must return NDIS\_STATUS\_PENDING from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the reset operation. After the reset operation has finished, the miniport driver completes the set request by calling [**NdisMRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622). + +When the method request of OID\_DOT11\_RESET\_REQUEST is made, the miniport driver must do the following regardless of the value of **dot11ResetType**: + +- Fail the query request if the value of the **InformationBufferLength** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function is less than the length, in bytes, of the [**DOT11\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff548782) structure. In this situation, the miniport driver returns NDIS\_STATUS\_BUFFER\_OVERFLOW from the *MiniportOidRequest* function. + +- Disconnect from the basic service set (BSS) network if the miniport driver is operating in ExtSTA mode and the 802.11 station is connected to the BSS network. If the 802.11 station connected to an infrastructure BSS, it must send an 802.11 Disassociation frame. + + When the 802.11 disconnects from the BSS, the miniport driver must make a media-specific [NDIS\_STATUS\_DOT11\_DISASSOCIATION](ndis-status-dot11-disassociation.md) indication. The **uSource** member of the DOT11\_DISASSOCIATION\_PARAMETERS structure must be set to **DOT11\_DISASSOC\_SOURCE\_OS**. + + **Note**  The miniport driver must make the NDIS\_STATUS\_DOT11\_DISASSOCIATION indication before it completes the method request of DOT11\_RESET\_REQUEST. + +   + +- Cancel any scan operation the 802.11 station is performing. + + If the 802.11 station is performing an explicit scan operation initiated through a set request of [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md), the miniport driver must make the [NDIS\_STATUS\_DOT11\_SCAN\_CONFIRM](ndis-status-dot11-scan-confirm.md) indication before it completes the method request of DOT11\_RESET\_REQUEST. + +- Clear its transmit and receive queues. If transmit packets are pending, the miniport driver must call [**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) for each packet in the transmit queue. When it calls **NdisMSendNetBufferListsComplete**, the miniport driver must set the **Status** member of each NET\_BUFFER\_LIST structure that is specified by the *NetBufferLists* parameter to NDIS\_STATUS\_RESET\_IN\_PROGRESS. + +- Retain the current power state of the 802.11 station as specified through the Native 802.11 Operational **msDot11NICPowerState** MIB object. For more information about this MIB object, see [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md). + +- Transition to the INIT state of the current operation mode. + + For more information about the operation modes of a Native 802.11 miniport driver, see [Native 802.11 Operation Modes](https://msdn.microsoft.com/library/windows/hardware/ff560671). + + For more information about the operating states of a Native 802.11 miniport driver, see [Native 802.11 Operating States](https://msdn.microsoft.com/library/windows/hardware/ff560664). + +The miniport driver can also choose to re-initialize data that is specific to the Extensible AP (ExtAP) operating mode, such as beacon data and cached information elements (IEs). + +When the method request of OID\_DOT11\_RESET\_REQUEST is made and the miniport driver is operating in the Extensible Station (ExtSTA) mode, the miniport driver must do the following: + +- Clear the PMKID cache that was previously set through [OID\_DOT11\_PMKID\_LIST](oid-dot11-pmkid-list.md). The miniport driver must set the PMKID list to its default value of an empty list. + +- Clear the privacy exemption list that was previously set through [OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST](oid-dot11-privacy-exemption-list.md). The miniport driver must set the privacy exemption list to its default value of an empty list. + +- Discard all cipher keys. + + If the miniport driver is operating in Extensible Station (ExtSTA) mode, these keys were previously set through [OID\_DOT11\_CIPHER\_DEFAULT\_KEY](oid-dot11-cipher-default-key.md) or [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md). + +- Set the members of its DOT11\_STATISTICS structure to zero. For more information about this structure, see [OID\_DOT11\_STATISTICS](oid-dot11-statistics.md). + +- If the miniport driver previously made a media-specific indication of [NDIS\_STATUS\_DOT11\_CONNECTION\_START](ndis-status-dot11-connection-start.md) but did not make the [NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION](ndis-status-dot11-connection-completion.md) indication, make the completion indication before it completes the method request of DOT11\_RESET\_REQUEST. + +- If the miniport driver previously made a media-specific indication of [NDIS\_STATUS\_DOT11\_ASSOCIATION\_START](ndis-status-dot11-association-start.md) but did not make the [NDIS\_STATUS\_DOT11\_ASSOCIATION\_COMPLETION](ndis-status-dot11-association-completion.md) indication, make the completion indication before it completes the method request of DOT11\_RESET\_REQUEST. + +- If the miniport driver previously made a media-specific indication of [NDIS\_STATUS\_DOT11\_ROAMING\_START](ndis-status-dot11-roaming-start.md) but did not make the [NDIS\_STATUS\_DOT11\_ROAMING\_COMPLETION](ndis-status-dot11-roaming-completion.md) indication, make the completion indication before it completes the method request of DOT11\_RESET\_REQUEST. + +When resetting the MAC layer, the 802.11 station must set the following MIB objects to their default values if **bSetDefaultMIB** is set to **TRUE**: + +- All Native 802.11 MIB objects associated with the MAC layer. For more information about these MIB objects, see [Native 802.11 MIB Objects](https://msdn.microsoft.com/library/windows/hardware/ff560645). + +- All ExtSTA MIB objects associated with the MAC layer. For more information about these MIB objects, see [Extensible Station MIB Objects](https://msdn.microsoft.com/library/windows/hardware/ff549882). + + The miniport driver resets these MIB objects to their default values only if the driver is operating in ExtSTA mode. + +- All ExtAP MIB objects associated with the MAC layer. For more information about these MIB objects, see [Extensible AP MIB Objects](https://msdn.microsoft.com/library/windows/hardware/ff549865). + +- All Native 802.11 Operational MIB objects associated with the MAC layer. For more information about these MIB objects, see [Native 802.11 Operational MIB Objects](https://msdn.microsoft.com/library/windows/hardware/ff560668). + +The 802.11 station must do the following when it resets the PHY layer: + +- Reset all supported PHY types. + +- If **bSetDefaultMIB** is set to **TRUE**, set the standard 802.11 MIB objects for the PHY layer to the default values. The station must set the MIB objects pertaining to all of the supported PHY types to their default values. + +When the reset operation is complete, the miniport driver must return a [**DOT11\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff548782) structure to confirm the reset operation. The miniport driver does this by: + +- Formatting the **InformationBuffer** member of the *OidRequest* parameter as a [**DOT11\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff548782) structure. + + The miniport driver sets the **uStatusType** member of the DOT11\_STATUS\_INDICATION structure to DOT11\_STATUS\_RESET\_CONFIRM. + + The miniport driver sets the **ndisStatus** member of the [**DOT11\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff548782) structure to NDIS\_STATUS\_SUCCESS if the reset operation completed successfully. If the reset operation failed, the miniport driver sets this member to the appropriate NDIS\_STATUS value. + +- Setting the value of the **BytesRead** member of the *OidRequest* parameter to the size of the DOT11\_RESET\_REQUEST structure. + + **Note**  The miniport driver must not set the value of the **BytesWritten** member of the *OidRequest* parameter. + +   + +Starting with Windows 8, the Wi-Fi Direct port must reset the specified layers of the 802.11 state and all the Wi-Fi Direct state programmed on it whenever an OID\_DOT11\_RESET\_REQUEST request is made. The miniport must transition to the initialization (INIT) state of the current operation mode. If it is operating as a Wi-Fi Direct Group Owner, it must stop the group and disconnect all its clients. If it is operating as a Wi-Fi Direct Client in a group, it must leave the group. + +The Wi-Fi Direct state configured by the following OIDs must be reset to their default values whenever an OID\_DOT11\_RESET\_REQUEST request is made: + +- [OID\_DOT11\_WFD\_DEVICE\_INFO](oid-dot11-wfd-device-info.md) +- [OID\_DOT11\_WFD\_DEVICE\_CAPABILITY](oid-dot11-wfd-device-capability.md) +- [OID\_DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY](oid-dot11-wfd-group-owner-capability.md) +- [OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST](oid-dot11-wfd-secondary-device-type-list.md) +- [OID\_DOT11\_WFD\_ADDITIONAL\_IE](oid-dot11-wfd-additional-ie.md) +- [OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY](oid-dot11-wfd-listen-state-discoverability.md) +- [OID\_DOT11\_WFD\_GROUP\_START\_PARAMETERS](oid-dot11-wfd-group-start-parameters.md) +- [OID\_DOT11\_WFD\_GROUP\_JOIN\_PARAMETERS](-oid-dot11-wfd-group-join-parameters.md) + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_RESET_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-rf-usage.md b/windows-driver-docs-pr/network/oid-dot11-rf-usage.md new file mode 100644 index 0000000000..411eff81b7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-rf-usage.md @@ -0,0 +1,65 @@ +--- +title: OID\_DOT11\_RF\_USAGE +author: windows-driver-content +description: OID\_DOT11\_RF\_USAGE +ms.assetid: 69fd1e3b-9e6c-4420-af7f-ef4b10f03546 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_RF_USAGE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_RF\_USAGE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_RF\_USAGE object identifier (OID) requests that the miniport driver return the radio frequency (RF) usage detected on the wireless media by the current PHY type on the 802.11 station. + +The data type for this OID is a ULONG value that represents the percentage of RF usage. + +When OID\_DOT11\_RF\_USAGE is queried, the miniport driver reports how busy the wireless media is. The 802.11 station must start gathering RF usage data after the PHY is turned on. The 802.11 station must clear its RF usage data after each query of OID\_DOT11\_RF\_USAGE. + +For more information about how to determine the RF usage of the wireless media, including physical carrier-sense and virtual carrier-sense methods, refer to clause 9.3.2.1 (for DCF operations) and clause 9.4 (for PCF operations) of the IEEE 802.11-2012 standard. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about the ExtSTA **msDot11CurrentPhyID** MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_RF_USAGE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-rts-threshold.md b/windows-driver-docs-pr/network/oid-dot11-rts-threshold.md new file mode 100644 index 0000000000..48cb8c7ae4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-rts-threshold.md @@ -0,0 +1,85 @@ +--- +title: OID\_DOT11\_RTS\_THRESHOLD +author: windows-driver-content +description: OID\_DOT11\_RTS\_THRESHOLD +ms.assetid: e4049926-7a89-4c32-8789-784dafe76ca3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_RTS_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_RTS\_THRESHOLD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_RTS\_THRESHOLD object identifier (OID) requests that the miniport driver set the IEEE 802.11 **dot11RTSThreshold** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **dot11RTSThreshold** MIB object. + +The **dot11RTSThreshold** MIB object specifies the maximum length that a MAC protocol data unit (MPDU) frame can have before the 802.11 station initiates the 802.11 request to send (RTS)/clear to send (CTS) handshake. For more information about the RTS/CTS handshake and RTS threshold, refer to Clause 9.3 of the IEEE 802.11-2012 standard. + +The data type for OID\_DOT11\_RTS\_THRESHOLD is a ULONG value that specifies the RTS threshold in bytes. + +The value of the **dot11RTSThreshold** MIB object must be from 0 through 2347. + +When OID\_DOT11\_RTS\_THRESHOLD is set, the following actions apply to the 802.11 station: + +- The 802.11 station must use the new RTS threshold value on all MAC service data unit (MSDU) packets passed after the set request by the operating system to the miniport driver's [*MiniportSendNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559440) function. + +- The 802.11 station can use the new RTS threshold value on all MSDU packets that are pending in the station's transmit queue. Alternatively, the 802.11 station can continue to use the old RTS threshold value for the pending MSDU packets. + +- The 802.11 station must not use the new RTS threshold value for any MPDU frames of the MSDU packet that the station is transmitting when OID\_DOT11\_RTS\_THRESHOLD is set. + +The default value for the **dot11RTSThreshold** MIB object is 2347. The miniport driver must set this MIB object to its default when one of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the MAC layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_RTS_THRESHOLD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-safe-mode-enabled.md b/windows-driver-docs-pr/network/oid-dot11-safe-mode-enabled.md new file mode 100644 index 0000000000..54e2bb24e4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-safe-mode-enabled.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_SAFE\_MODE\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_SAFE\_MODE\_ENABLED +ms.assetid: 29fa1ba3-dd32-4deb-9780-cb5b778fc72c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SAFE_MODE_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SAFE\_MODE\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_SAFE\_MODE\_ENABLED object identifier (OID) requests that the miniport driver enable 802.11 safe mode on the 802.11 station by setting the Boolean value **msDot11SafeModeEnabled** to **TRUE**. + +The data type for this OID is a Boolean value. + +The miniport driver must fail a set request with error code NDIS\_STATUS\_INVALID\_STATE if the 802.11 station is in any state except the initialization (INIT) state. When this OID is queried when the extensible station is in the INIT state, the miniport driver must complete the request if the NIC set the **bSafeModeImplemented** member of the [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) structure to **TRUE**. Otherwise, the miniport driver should fail the set request. + +This OID is set only if the NIC implements the 802.11 safe mode of operation, as indicated by the value of the **bSafeModeImplemented** member of [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688). + +If this OID is not set, its default value is used. + +Safe mode is disabled by default. The default value of **msDot11SafeModeEnabled** is **FALSE**. + +When queried, OID\_DOT11\_SAFE\_MODE\_ENABLED requests that the miniport driver return the value of **msDot11SafeModeEnabled**. + +When in safe mode, the miniport driver should ignore **dot11ExcludeUnencrypted**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) + +[OID\_DOT11\_EXCLUDE\_UNENCRYPTED](oid-dot11-exclude-unencrypted.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SAFE_MODE_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-safe-mode-ht-enabled.md b/windows-driver-docs-pr/network/oid-dot11-safe-mode-ht-enabled.md new file mode 100644 index 0000000000..edafb790f2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-safe-mode-ht-enabled.md @@ -0,0 +1,97 @@ +--- +title: OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED +author: windows-driver-content +description: When set, the OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED object identifier (OID) requests that the miniport driver enable 802.11n safe mode on the 802.11 station by setting the Boolean value msDot11SafeModeHtEnabled to TRUE. +ms.assetid: 55E517EA-046B-43FF-9FA1-52A89AC8255B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SAFE_MODE_HT_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED object identifier (OID) requests that the miniport driver enable 802.11n safe mode on the 802.11 station by setting the Boolean value **msDot11SafeModeHtEnabled** to **TRUE**. + +The data type for this OID is a Boolean value. + +The miniport driver must fail a set request with error code **NDIS\_STATUS\_INVALID\_STATE** if the 802.11 station is in any state except the initialization (INIT) state. + +When this OID is queried, if the extensible station is in the INIT state, the miniport driver must complete the request if the NIC set the **bSafeModeImplemented** member of the [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) structure to **TRUE**. Otherwise, the miniport driver should fail the set request. + +This OID is set only if the NIC implements the 802.11n safe mode of operation, as indicated by the value of the **bSafeModeImplemented** member of [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688). + +If this OID is not set, its default value is used. + +Safe mode is disabled by default. The default value of **msDot11SafeModeHtEnabled** is **FALSE**. + +When queried, OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED requests that the miniport driver return the value of **msDot11SafeModeHtEnabled**. + +When in safe mode, the miniport driver should ignore **dot11ExcludeUnencrypted**. + +The NIC must not use traffic specification (TSPEC) in safe mode. + +When processing an OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED OID request, the miniport should do the following: + +- Indicate that QoS is in use on the network by setting the **ucActiveQoSProtocol** member of the [**DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547647) structure to one of the flag values listed in the **ucActiveQoSProtocolmember description**. +- In the case of an 802.11g association, the miniport should not use QoS. The **ucActiveQoSProtocol** member of [**DOT11\_ASSOCIATION\_COMPLETION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff547647) should be set to zero on association completion. +- On the TX path, the miniport should extend the 802.11 header with QoS priority-received in-frame OOB data, based on the condition that WMM was negotiated on the current association. +- On the RX path, the miniport should not strip the QoS flag from the 802.11 header when operating in safe mode. +- Pass the QoS data in the 802.11 frame as-is to the Nwifi driver. +- Disable 802.11w when in Federal Information Processing Standards (FIPS) mode. Otherwise, Windows would not succeed the association. +- While it is transmitting RSN capabilities, the miniport should ensure that the SPP (signaling and payload protected) A-MSDU capable bit (Bit 10) is set to zero. Only PP (payload protected) A-MSDU is supported in safe mode. + +**Note**  The miniport will not receive [OID\_DOT11\_SAFE\_MODE\_ENABLED](oid-dot11-safe-mode-enabled.md) if it completes OID\_DOT11\_SAFE\_MODE\_HT\_ENABLED successfully. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

None supported

Minimum supported server

Windows Server 2012 R2

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) + +[OID\_DOT11\_SAFE\_MODE\_ENABLED](oid-dot11-safe-mode-enabled.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SAFE_MODE_HT_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-scan-request.md b/windows-driver-docs-pr/network/oid-dot11-scan-request.md new file mode 100644 index 0000000000..9e3b80acf6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-scan-request.md @@ -0,0 +1,129 @@ +--- +title: OID\_DOT11\_SCAN\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_SCAN\_REQUEST +ms.assetid: 84b62c71-f73c-4cb5-b00e-fb17d6b55851 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SCAN_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SCAN\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_SCAN\_REQUEST object identifier (OID) requests that the 802.11 station perform a survey of all basic service set (BSS) networks within range of the NIC's radio. The 802.11 station performs the scan operation by using the parameters defined in the set request. + +The data type for this OID is the [**DOT11\_SCAN\_REQUEST\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff548767) structure. + +When OID\_DOT11\_SCAN\_REQUEST is set, the miniport driver must fail the set request under the following conditions by returning the specified value from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConditionReturn value

The uNumOfdot11SSIDs member of the [DOT11_SCAN_REQUEST_V2](https://msdn.microsoft.com/library/windows/hardware/ff548767) structure has a value greater than the value of uScanSSIDListSize that the driver previously returned through a query of [OID_DOT11_EXTSTA_CAPABILITY](oid-dot11-extsta-capability.md).

+
+Note  This condition is applicable only when the miniport driver is operating in Extensible Station (ExtSTA) mode. +
+
+  +

NDIS_STATUS_INVALID_LENGTH

The ChDescriptionType member of the [DOT11_SCAN_REQUEST_V2](https://msdn.microsoft.com/library/windows/hardware/ff548767) structure contains an invalid enumerator value.

NDIS_STATUS_BAD_VERSION

The dot11PhyType member of the [DOT11_PHY_TYPE_INFO](https://msdn.microsoft.com/library/windows/hardware/ff548745) structure specifies a PHY type that is not supported by the 802.11 station.

NDIS_STATUS_BAD_VERSION

The dot11PhyId member of the [DOT11_PHY_TYPE_INFO](https://msdn.microsoft.com/library/windows/hardware/ff548745) structure is set to a value of DOT11_PHY_ID_ANY.

NDIS_STATUS_INVALID_DATA

The dot11PhyId member of the [DOT11_PHY_TYPE_INFO](https://msdn.microsoft.com/library/windows/hardware/ff548745) structure is set to a value that is larger than the number of entries in the list of supported PHYs returned by the driver through a query of [OID_DOT11_SUPPORTED_PHY_TYPES](oid-dot11-supported-phy-types.md).

NDIS_STATUS_BAD_VERSION

A scan initiated from a previous set of OID_DOT11_SCAN_REQUEST is not complete.

NDIS_STATUS_DOT11_MEDIA_IN_USE

The msDot11NICPowerState management information base (MIB) object is set to FALSE. For more information about this MIB object, see [OID_DOT11_NIC_POWER_STATE](oid-dot11-nic-power-state.md).

NDIS_STATUS_POWER_STATE_INVALID

All of the PHYs in the list of PHY types are turned off through a hardware switch setting or proprietary software setting.

NDIS_STATUS_DOT11_POWER_STATE_INVALID

One or more of the PHYs in the list of PHY types are either not supported or have been disabled on the 802.11 station through a proprietary mechanism implemented by the independent hardware vendor (IHV).

+

This condition does not apply to PHYs disabled through a set request of [OID_DOT11_NIC_POWER_STATE](oid-dot11-nic-power-state.md).

NDIS_STATUS_UNSUPPORTED_MEDIA

The list of PHY types includes a type that is not supported by the 802.11 station or contains a channel description that is not supported by the regulatory domain in which the station is operating.

NDIS_STATUS_BAD_VERSION

+ +  + +When performing the scan operation, the miniport driver and 802.11 station must follow the guidelines described in [Native 802.11 Scan Operations](https://msdn.microsoft.com/library/windows/hardware/ff560679). The miniport driver must not wait for the scan operation to finish before completing the set request. The driver must return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the scan operation. + +If the miniport driver supports the functionality of multiple MAC entities through [virtualization](https://msdn.microsoft.com/library/windows/hardware/ff571041), the driver should not return NDIS\_STATUS\_DOT11\_MEDIA\_IN\_USE if the medium is blocked by another MAC. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SCAN_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-short-preamble-option-implemented.md b/windows-driver-docs-pr/network/oid-dot11-short-preamble-option-implemented.md new file mode 100644 index 0000000000..8552c33df8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-short-preamble-option-implemented.md @@ -0,0 +1,77 @@ +--- +title: OID\_DOT11\_SHORT\_PREAMBLE\_OPTION\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_SHORT\_PREAMBLE\_OPTION\_IMPLEMENTED +ms.assetid: dac3e058-ab18-4a06-aea2-76aa15bd1e10 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SHORT\_PREAMBLE\_OPTION\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SHORT\_PREAMBLE\_OPTION\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11b **dot11ShortPreambleOptionImplemented** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11ShortPreambleOptionImplemented** MIB object specifies whether the current PHY type supports the option to enable the short Physical Layer Convergence Procedure (PLCP) preamble and header. For more information about the short PLCP preamble and header, refer to Clause 18.2.2.2 of the IEEE 802.11b-1999 standard. + +The data type for this OID is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports the short preamble option. + +The **dot11ShortPreambleOptionImplemented** MIB object is only valid for the following PHY types: + +- High-rate direct-sequence spread spectrum (HRDSS) PHY. + +- Extended-rate PHY (ERP). + +If the current PHY type is not set to **dot11\_phy\_type\_hrdsss** or **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-short-retry-limit.md b/windows-driver-docs-pr/network/oid-dot11-short-retry-limit.md new file mode 100644 index 0000000000..9c4888efc9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-short-retry-limit.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_SHORT\_RETRY\_LIMIT +author: windows-driver-content +description: OID\_DOT11\_SHORT\_RETRY\_LIMIT +ms.assetid: ccf0f3ef-179d-4b9c-b98a-c942e4e37f59 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SHORT_RETRY_LIMIT Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SHORT\_RETRY\_LIMIT + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SHORT\_RETRY\_LIMIT object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11ShortRetryLimit** management information base (MIB) object. + +The **dot11ShortRetryLimit** MIB object specifies the maximum number of retransmission attempts made by the 802.11 station for MAC service data unit (MSDU) packets with lengths less than or equal to the value of the IEEE 802.11 **dot11RTSThreshold** MIB object. For more information about the **dot11RTSThreshold** MIB object, see [OID\_DOT11\_RTS\_THRESHOLD](oid-dot11-rts-threshold.md). + +The data type for this OID is a ULONG value from 1 through 255. + +When the 802.11 station exceeds the number of maximum number of retransmission attempts defined by the **dot11ShortRetryLimit** MIB object, it must do the following: + +- Discard the packet. + +- If the miniport driver is operating in Extensible Station (ExtSTA) mode, it must increment the **ullFailedCount** member of the DOT11\_STATISTICS structure. For more information about this structure, see [OID\_DOT11\_STATISTICS](oid-dot11-statistics.md). + +The default value for the **dot11ShortRetryLimit** MIB object is seven. The miniport driver must set the MIB object to this default through its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function or when reset through [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SHORT_RETRY_LIMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-enabled.md b/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-enabled.md new file mode 100644 index 0000000000..11b06122de --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-enabled.md @@ -0,0 +1,75 @@ +--- +title: OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_ENABLED +ms.assetid: eba45a33-a61a-4aac-b655-b891187ddf41 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_ENABLED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11ShortSlotTimeOptionEnabled** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the current PHY type has enabled the 802.11g short slot time option. For more information about short slot time option, refer to Clause 7.3.1.4 of the IEEE 802.11g-2003 standard. + +**Note**  Support for this OID is mandatory if the NIC supports the **dot11\_phy\_type\_erp** PHY type. For more information about how the miniport driver specifies its list of supported PHY types, see [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +  + +The data type for this OID is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type has the 802.11g short slot time option enabled. + +The **dot11ShortSlotTimeOptionEnabled** MIB object is only valid for the Extended-rate PHY (ERP) type. If the current PHY type is not set to **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-implemented.md b/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-implemented.md new file mode 100644 index 0000000000..381447273b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-short-slot-time-option-implemented.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_IMPLEMENTED +author: windows-driver-content +description: OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_IMPLEMENTED +ms.assetid: 61047d89-52b4-431e-b042-55add0928380 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_IMPLEMENTED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SHORT\_SLOT\_TIME\_OPTION\_IMPLEMENTED object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11g **dot11ShortSlotTimeOptionImplemented** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies whether the current PHY type supports the 802.11g short slot time option. For more information about the short slot time, refer to Clause 7.3.1.4 of the IEEE 802.11g-2003 standard. + +The data type for this OID is a BOOLEAN value. A value of **TRUE** indicates that the current PHY type supports the 802.11g short slot time option. + +The **dot11ShortSlotTimeOptionImplemented** MIB object is only valid for the Extended-rate PHY (ERP) type. If the current PHY type is not set to **dot11\_phy\_type\_erp**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about this MIB object, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-start-ap-request.md b/windows-driver-docs-pr/network/oid-dot11-start-ap-request.md new file mode 100644 index 0000000000..5cb1c8a737 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-start-ap-request.md @@ -0,0 +1,158 @@ +--- +title: OID\_DOT11\_START\_AP\_REQUEST +author: windows-driver-content +description: OID\_DOT11\_START\_AP\_REQUEST +ms.assetid: b37ce67b-e80e-4b34-a810-89d438ed848f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_START_AP_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_START\_AP\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_START\_AP\_REQUEST object identifier (OID) requests that the miniport driver configure the NIC to start the infrastructure network and to serve as an access point (AP). The NIC must switch from ExtAP INIT mode to ExtAP OP mode. + +**Note**  Support for this OID is mandatory. + +  + +The NIC must be in ExtAP INIT mode in order to configure new AP profile settings. If the NIC is in ExtAP OP mode, the operating system will issue an OID\_DOT11\_RESET\_REQUEST before it configures a new AP profile. + +Before the operating system issues an OID\_DOT11\_START\_AP\_REQUEST to start an 802.11 infrastructure network, it adds configuration parameters for the network by using set requests on one or more of the following OIDs: + +- [OID\_DOT11\_ADDITIONAL\_IE](oid-dot11-additional-ie.md) + +- [OID\_DOT11\_AUTO\_CONFIG\_ENABLED](oid-dot11-auto-config-enabled.md) + +- [OID\_DOT11\_BEACON\_PERIOD](oid-dot11-beacon-period.md) + +- [OID\_DOT11\_CIPHER\_DEFAULT\_KEY](oid-dot11-cipher-default-key.md) + +- [OID\_DOT11\_CIPHER\_DEFAULT\_KEY\_ID](oid-dot11-cipher-default-key-id.md) + +- [OID\_DOT11\_CIPHER\_KEY\_MAPPING\_KEY](oid-dot11-cipher-key-mapping-key.md) + +- [OID\_DOT11\_CURRENT\_CHANNEL](oid-dot11-current-channel.md) + +- [OID\_DOT11\_CURRENT\_FREQUENCY](oid-dot11-current-frequency.md) + +- [OID\_DOT11\_CURRENT\_OPERATION\_MODE](oid-dot11-current-operation-mode.md) + +- [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md) + +- [OID\_DOT11\_DESIRED\_PHY\_LIST](oid-dot11-desired-phy-list.md) + +- [OID\_DOT11\_DESIRED\_SSID\_LIST](oid-dot11-desired-ssid-list.md) + +- [OID\_DOT11\_DTIM\_PERIOD](oid-dot11-dtim-period.md) + +- [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md) + +- [OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md) + +- [OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md) + +- [OID\_DOT11\_EXCLUDE\_UNENCRYPTED](oid-dot11-exclude-unencrypted.md) + +- [OID\_DOT11\_FLUSH\_BSS\_LIST](oid-dot11-flush-bss-list.md) + +- [OID\_DOT11\_FRAGMENTATION\_THRESHOLD](oid-dot11-fragmentation-threshold.md) + +- [OID\_DOT11\_MULTICAST\_LIST](oid-dot11-multicast-list.md) + +- [OID\_DOT11\_NIC\_POWER\_STATE](oid-dot11-nic-power-state.md) + +- [OID\_DOT11\_OPERATIONAL\_RATE\_SET](oid-dot11-operational-rate-set.md) + +- [OID\_DOT11\_PRIVACY\_EXEMPTION\_LIST](oid-dot11-privacy-exemption-list.md) + +- [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) + +- [OID\_DOT11\_SCAN\_REQUEST](oid-dot11-scan-request.md) + +The following interaction sequence between miniport driver and operating system takes place: + +1. The operating system sets the network service set identifier (SSID) by setting [OID\_DOT11\_DESIRED\_SSID\_LIST](oid-dot11-desired-ssid-list.md). + +2. The miniport driver should set the basic service set identifier (BSSID) to be the NIC's MAC address. + +3. The miniport driver can optionally set [OID\_DOT11\_BEACON\_PERIOD](oid-dot11-beacon-period.md) to schedule the NIC's transmission of 802.11 Beacon frames. + +4. The operating system sets security-related OIDs in the following order: + + - [OID\_DOT11\_ENABLED\_AUTHENTICATION\_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md) + - [OID\_DOT11\_ENABLED\_UNICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md) + - [OID\_DOT11\_ENABLED\_MULTICAST\_CIPHER\_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md)(optional). If this OID is not set, the NIC should use the unicast cipher algorithm. + + Any OIDs not listed here that can be set in ExtAP INIT mode can come to the miniport driver in any order. + + If the miniport driver receives an OID\_DOT11\_START\_AP\_REQUEST set request after it has indicated [NDIS\_STATUS\_DOT11\_STOP\_AP](ndis-status-dot11-stop-ap.md) but before it has indicated [NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP](ndis-status-dot11-can-sustain-ap.md), the driver should fail the OID request with a failure code of NDIS\_STATUS\_INVALID\_STATE. + + The NIC should support 802.11 open authentication and shared-key authentication infrastructure security. The NIC can additionally support any of the following infrastructure security features: + + - WPA + - WPA-PSK + - RSNA + - RSNA-PSK + +5. For each enabled 802.11a PHY, the miniport driver should set [OID\_DOT11\_CURRENT\_FREQUENCY](oid-dot11-current-frequency.md). + +6. For each enabled 802.11b or g PHY, the miniport driver should set [OID\_DOT11\_CURRENT\_CHANNEL](oid-dot11-current-channel.md). + +7. The operating system sets other Microsoft standard configuration parameters, such as a packet exemption list that exempts packets with certain Ethernet types from cipher operations. + +For any optional settings that are not set by the operating system, the miniport driver should use the default values provided by the NIC manufacturer. + +The miniport driver should use the first entry from the desired SSID list as the SSID for the NIC. The BSSID of the network must be the MAC address of the NIC. If the **msDot11DesiredPhyList** management information base (MIB) object is DOT11\_PHY\_ID\_ANY, the miniport driver can start the new BSS on any PHY. If **msDot11DesiredPhyList** contains a list of specific PHY identifiers, the miniport driver should start the new BSS by using the first specified PHY identifier. + +The NIC should send out 802.11 beacon packets periodically as specified in the *IEEE 802.11 Standard*. When the NIC does this, it should attach the list of additional information elements (IEs) to the end of each beacon packet. The operating system will guarantee that it will not set WPA and WMM IEs in its list of IEs. For more information on how the miniport driver should handle additional IE data, see [OID\_DOT11\_ADDITIONAL\_IE](oid-dot11-additional-ie.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[NDIS\_STATUS\_DOT11\_CAN\_SUSTAIN\_AP](ndis-status-dot11-can-sustain-ap.md) + +[NDIS\_STATUS\_DOT11\_STOP\_AP](ndis-status-dot11-stop-ap.md) + +[OID\_DOT11\_ADDITIONAL\_IE](oid-dot11-additional-ie.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_START_AP_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-station-id.md b/windows-driver-docs-pr/network/oid-dot11-station-id.md new file mode 100644 index 0000000000..0dc0976b8e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-station-id.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_STATION\_ID +author: windows-driver-content +description: OID\_DOT11\_STATION\_ID +ms.assetid: 934721c1-09a0-40d5-85e3-6913fac37f1a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_STATION_ID Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_STATION\_ID + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_STATION\_ID object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11StationID** management information base (MIB) object. + +This MIB object contains an identifier (ID) value that uniquely identifies the 802.11 station to a remote management platform. + +The data type for this OID is the [**DOT11\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/ff548681) structure. + +The default value of the **dot11StationID** MIB object is the same as the value of the **dot11MACAddress** MIB object. For more information about the **dot11MACAddress** MIB object, see [OID\_DOT11\_MAC\_ADDRESS](oid-dot11-mac-address.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_STATION_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-statistics.md b/windows-driver-docs-pr/network/oid-dot11-statistics.md new file mode 100644 index 0000000000..1cd6ac6399 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-statistics.md @@ -0,0 +1,324 @@ +--- +title: OID\_DOT11\_STATISTICS +author: windows-driver-content +description: When queried, the OID\_DOT11\_STATISTICS object identifier (OID) requests that the miniport driver return the statistics for the IEEE 802.11 interface, including +ms.assetid: 631f29fb-c59f-4ecf-9d63-cde348270315 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_STATISTICS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_STATISTICS object identifier (OID) requests that the miniport driver return the statistics for the IEEE 802.11 interface, including: + +- Statistics for the IEEE media access control (MAC) layer of the 802.11 station. + +- Statistics for the IEEE PHY layer of the 802.11 station for each supported PHY. + +The data type for this OID is the DOT11\_STATISTICS structure. + +```ManagedCPlusPlus + typedef struct DOT11_STATISTICS { + NDIS_OBJECT_HEADER Header; + ULONGLONG ullFourWayHandshakeFailures; + ULONGLONG ullTKIPCounterMeasuresInvoked; + ULONGLONG ullReserved; + DOT11_MAC_FRAME_STATISTICS MacUcastCounters; + DOT11_MAC_FRAME_STATISTICS MacMcastCounters; + DOT11_PHY_FRAME_STATISTICS PhyCounters[]; + } DOT11_STATISTICS, *PDOT11_STATISTICS; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_STATISTICS structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_STATISTICS\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_STATISTICS). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**ullFourWayHandshakeFailures** +The number of four-way handshake failures that the 802.11 station encountered during Wi-Fi Protected Access (WPA) or Robust Security Network Association (RSNA) authentication. + +If the 802.11 station is not performing the WPA or RSNA authentication, it must not write to this member. + +**ullTKIPCounterMeasuresInvoked** +The number of times that the 802.11 station invoked countermeasures following a message integrity code (MIC) failure. + +If the 802.11 station is not performing TKIP countermeasures, it must not write to this member. + +**ullReserved** +This member is reserved for use by the operating system. The miniport driver must not write to this member. + +**MacUcastCounters** +The MAC layer counters based on unicast packets sent or received by the 802.11 station. The data structure for this member is the DOT11\_MAC\_FRAME\_STATISTICS structure. + +**Note**  The miniport driver must increment counters for received unicast packets only for those packets with a destination MAC address in the 802.11 MAC header that matches the 802.11 station's MAC address. + +  + +**MacMcastCounters** +The MAC layer counters based on multicast or broadcast packets sent or received by the 802.11 station. The data structure for this member is the DOT11\_MAC\_FRAME\_STATISTICS structure. + +**Note**  The miniport driver must increment counters for received multicast packets if the MAC address in the 802.11 MAC header matches an entry in the multicast address list of the 802.11 station. For more information about the multicast address list, see [OID\_DOT11\_MULTICAST\_LIST](oid-dot11-multicast-list.md). The driver must increment counters on receipt of broadcast packets that match the currently configured packet filter. For more information about packet filters, see [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md). + +  + +**PhyCounters** +An array of PHY layer counters. Each entry in this array is formatted as a DOT11\_PHY\_FRAME\_STATISTICS structure. + +The driver must maintain separate copies of the DOT11\_PHY\_FRAME\_STATISTICS structure for each supported PHY. + +The miniport driver returns the list of supported PHYs when queried by [OID\_DOT11\_SUPPORTED\_PHY\_TYPES](oid-dot11-supported-phy-types.md). + +When OID\_DOT11\_STATISTICS is queried, the miniport driver must return an entry in the **PhyCounters** array for each supported PHY. + +The data type for the **MacUcastCounters** and **MacMcastCounters** members is the DOT11\_MAC\_FRAME\_STATISTICS structure. + +``` syntax +typedef struct DOT11_MAC_FRAME_STATISTICS { + ULONGLONG ullTransmittedFrameCount; + ULONGLONG ullReceivedFrameCount; + ULONGLONG ullWEPExcludedCount; + ULONGLONG ullTKIPLocalMICFailures; + ULONGLONG ullTKIPReplays; + ULONGLONG ullTKIPICVErrorCount; + ULONGLONG ullCCMPFormatErrors; + ULONGLONG ullCCMPReplays; + ULONGLONG ullCCMPDecryptErrors; + ULONGLONG ullWEPUndecryptableCount; + ULONGLONG ullWEPICVErrorCount; + ULONGLONG ullDecryptSuccessCount; + ULONGLONG ullDecryptFailureCount; + } DOT11_MAC_STATISTICS, * PDOT11_MAC_STATISTICS; +``` + +The members of this structure are used to record MAC-level statistics for: + +- MAC service data unit (MSDU) packets. + +- MAC protocol data unit (MPDU) frames. + + MPDU frame counters must include all MPDU fragments sent for an MSDU packet. + +- Management MPDU (MMPDU) frames. + +This structure includes the following members: + +**ullTransmittedFrameCount** +The number of MSDU packets and MMPDU frames that the IEEE MAC layer of the 802.11 station successfully transmitted. + +**ullReceivedFrameCount** +The number of MSDU packets and MMPDU frames that the IEEE MAC layer of the 802.11 station successfully received. This member should not be incremented for received packets that failed cipher decryption or MIC validation. + +**ullWEPExcludedCount** +The number of unencrypted received MPDU frames that the MAC layer discarded when the IEEE 802.11 **dot11ExcludeUnencrypted** management information base (MIB) object is enabled. For more information about this MIB object, see [OID\_DOT11\_EXCLUDE\_UNENCRYPTED](oid-dot11-exclude-unencrypted.md). + +MPDU frames are considered unencrypted when the Protected Frame subfield of the Frame Control field in the IEEE 802.11 MAC header is set to zero. + +**ullTKIPLocalMICFailures** +The number of received MSDU packets that the 802.11 station discarded because of MIC failures. + +**ullTKIPReplays** +The number of received MPDU frames that the 802.11 station discarded because of the TKIP replay protection procedure. + +**ullTKIPICVErrorCount** +The number of encrypted MPDU frames that the 802.11 station failed to decrypt because of a TKIP ICV error. + +**ullCCMPFormatErrors** +The number of received MPDU frames that the 802.11 discarded because of an invalid AES-CCMP format. + +**ullCCMPReplays** +The number of received MPDU frames that the 802.11 station discarded because of the AES-CCMP replay protection procedure. + +**ullCCMPDecryptErrors** +The number of received MPDU frames that the 802.11 station discarded because of errors detected by the AES-CCMP decryption algorithm. + +**ullWEPUndecryptableCount** +The number of encrypted MPDU frames received for which a WEP decryption key was not available on the 802.11 station. + +**ullWEPICVErrorCount** +The number of encrypted MPDU frames that the 802.11 station failed to decrypt because of a WEP ICV error. + +**ullDecryptSuccessCount** +The number of received encrypted packets that the 802.11 station successfully decrypted. + +For the WEP and TKIP cipher algorithms, the miniport driver must increment this counter for each received encrypted MPDU that was successfully decrypted. For the AES-CCMP cipher algorithm, the miniport driver must increment this counter on each received encrypted MSDU packet that was successfully decrypted. + +**ullDecryptFailureCount** +The number of encrypted packets that the 802.11 station failed to decrypt. + +For the WEP and TKIP cipher algorithms, the miniport driver must increment this counter for each received encrypted MPDU that was not successfully decrypted. For the AES-CCMP cipher algorithm, the miniport driver must increment this counter on each received encrypted MSDU packet that was not successfully decrypted. + +The miniport driver must not increment this counter for packets that are decrypted successfully, but are discarded for other reasons. For example, the miniport driver must not increment this counter for packets discarded because of TKIP MIC failures or TKIP/CCMP replays. + +The data type for the elements of the **PhyCounters** array is the DOT11\_PHY\_FRAME\_STATISTICS structure. + +``` syntax +typedef struct DOT11_PHY_FRAME_STATISTICS { + ULONGLONG ullTransmittedFrameCount; + ULONGLONG ullMulticastTransmittedFrameCount; + ULONGLONG ullFailedCount; + ULONGLONG ullRetryCount; + ULONGLONG ullMultipleRetryCount; + ULONGLONG ullMaxTXLifetimeExceededCount; + ULONGLONG ullTransmittedFragmentCount; + ULONGLONG ullRTSSuccessCount; + ULONGLONG ullRTSFailureCount; + ULONGLONG ullACKFailureCount; + ULONGLONG ullReceivedFrameCount; + ULONGLONG ullMulticastReceivedFrameCount; + ULONGLONG ullPromiscuousReceivedFrameCount; + ULONGLONG ullMaxRXLifetimeExceededCount; + ULONGLONG ullFrameDuplicateCount; + ULONGLONG ullReceivedFragmentCount; + ULONGLONG ullPromiscuousReceivedFragmentCount; + ULONGLONG ullFCSErrorCount; + } DOT11_PHY_FRAME_STATISTICS, *PDOT11_PHY_FRAME_STATISTICS; +``` + +The members of this structure are used to record PHY-level statistics for: + +- MAC service data unit (MSDU) packets. + +- MAC protocol data unit (MPDU) frames. + + MPDU frame counters must include all MPDU fragments sent for an MSDU packet. + +- Management MPDU (MMPDU) frames. + +This structure includes the following members: + +**ullTransmittedFrameCount** +The number of MSDU packets and MMPDU frames that the IEEE PHY layer of the 802.11 station has successfully transmitted. + +**ullMulticastTransmittedFrameCount** +The number of multicast or broadcast MSDU packets and MMPDU frames that the IEEE PHY layer of the 802.11 station has successfully transmitted. + +**ullFailedCount** +The number of MSDU packets and MMPDU frames that the 802.11 station failed to transmit after exceeding the retry limits defined by the 802.11 IEEE **dot11ShortRetryLimit** or **dot11LongRetryLimit** MIB counters. For more information about these MIB counters, see [OID\_DOT11\_SHORT\_RETRY\_LIMIT](oid-dot11-short-retry-limit.md) or [OID\_DOT11\_LONG\_RETRY\_LIMIT](oid-dot11-long-retry-limit.md). + +**ullRetryCount** +The number of MSDU packets and MMPDU frames that the 802.11 station successfully transmitted after one or more attempts. + +**ullMultipleRetryCount** +The number of MSDU packets and MMPDU frames that the 802.11 station successfully transmitted after more than one retransmission attempt. + +For MSDU packets, the miniport driver must increment this counter for each packet that was transmitted successfully after one or more of its MPDU fragments required retransmission. + +**ullMaxTXLifetimeExceededCount** +The number of MSDU packets and MMPDU frames that the 802.11 station failed to transmit because of a timeout as defined by the IEEE 802.11 **dot11MaxTransmitMSDULifetime** MIB object. For more information about this MIB object, see [OID\_DOT11\_MAX\_TRANSMIT\_MSDU\_LIFETIME](oid-dot11-max-transmit-msdu-lifetime.md). + +**ullTransmittedFragmentCount** +The number of MPDU frames that the 802.11 station transmitted and acknowledged through a received 802.11 ACK frame. + +**ullRTSSuccessCount** +The number of times that the 802.11 station received a Clear To Send (CTS) frame in response to a Request To Send (RTS) frame. + +**ullRTSFailureCount** +The number of times that the 802.11 station did not receive a CTS frame in response to an RTS frame. + +**ullACKFailureCount** +The number of times that the 802.11 station expected and did not receive an Acknowledgement (ACK) frame. + +**ullReceivedFrameCount** +The number of MSDU packets and MMPDU frames that the 802.11 station has successfully received. + +For MSDU packets, the miniport driver must increment this counter for each packet whose MPDU fragments were received and passed frame check sequence (FCS) verification and replay detection. The miniport driver must increment this member regardless of whether the received MSDU packet or MPDU fragment fail MAC-layer cipher decryption. + +**ullMulticastReceivedFrameCount** +The number of multicast or broadcast MSDU packets and MMPDU frames that the 802.11 station has successfully received. + +For MSDU packets, the miniport driver must increment this counter for each packet whose MPDU fragments were received and passed FCS verification and replay detection. The miniport driver must increment this member regardless of whether the received MSDU packet or MPDU fragment fail MAC-layer cipher decryption. + +**ullPromiscuousReceivedFrameCount** +The number of MSDU packets or MMPDU frames received by the 802.11 station when a promiscuous packet filter is enabled. For more information about packet filters, see [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md). + +If a promiscuous packet filter is enabled, the miniport driver must only increment this counter for received MSDU packets or MMPDU frames that would have been rejected if the filter was not enabled. The driver must not increment this counter for: + +- Unicast MSDU packets or MMPDU frames with a destination MAC address that matches the 802.11 station's MAC address. + +- Multicast or broadcast MSDU packets or MMPDU frames with a destination MAC address that matches an entry in the multicast address list of the 802.11 station. For more information about the multicast address list, see [OID\_DOT11\_MULTICAST\_LIST](oid-dot11-multicast-list.md). + +**ullMaxRXLifetimeExceededCount** +The number if MSDU packets and MMPDU frames that the 802.11 station discarded because of a timeout as defined by the IEEE 802.11 **dot11MaxReceiveLifetime** MIB object. For more information about this MIB object, see [OID\_DOT11\_MAX\_RECEIVE\_LIFETIME](oid-dot11-max-receive-lifetime.md). + +**ullFrameDuplicateCount** +The number of duplicate MPDU frames that the 802.11 station received. The 802.11 station determines duplicate frames through the Sequence Control field of the 802.11 MAC header. + +**ullReceivedFragmentCount** +The number of MPDU frames received by the 802.11 station for MSDU packets or MMPDU frames. + +**ullPromiscuousReceivedFragmentCount** +The number of MPDU frames received by the 802.11 station for MSDU packets or MMPDU frames when a promiscuous packet filter was enabled. For more information about packet filters, see [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md). + +If a promiscuous packet filter is enabled, the miniport driver must only increment this counter for received MPDU frames that would have been rejected if the filter was not enabled. The driver must not increment this counter for: + +- Unicast MPDU frames with a destination MAC address that matches the 802.11 station's MAC address. + +- Multicast or broadcast MPDU frames with a destination MAC address that matches an entry in the multicast address list of the 802.11 station. For more information about the multicast address list, see [OID\_DOT11\_MULTICAST\_LIST](oid-dot11-multicast-list.md). + +**ullFCSErrorCount** +The number of MPDU frames that the 802.11 station received with FCS errors. + +The miniport driver must unconditionally set all of the counters in the DOT11\_STATISTICS structure to zero, including MAC-layer and PHY-layer counters, when one of the following occurs: + +- The driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- The driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function is called with a method request of the [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) OID, regardless of the type of reset operation specified in the set request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_STATISTICS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-country-or-region-string.md b/windows-driver-docs-pr/network/oid-dot11-supported-country-or-region-string.md new file mode 100644 index 0000000000..90523473ca --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-country-or-region-string.md @@ -0,0 +1,116 @@ +--- +title: OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING +author: windows-driver-content +description: When queried, the OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING object identifier (OID) requests that the miniport driver return a list of the country strings identifying the regulatory domains supported by the 802.11 station. +ms.assetid: a8efc910-898a-4790-9da8-79d216c7ccff +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_COUNTRY_OR_REGION_STRING Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING object identifier (OID) requests that the miniport driver return a list of the country strings identifying the regulatory domains supported by the 802.11 station. For more information about country strings, refer to the IEEE 802.11d-2001 standard. + +The data type for this OID is the DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure. + +```ManagedCPlusPlus + typedef struct DOT11_COUNTRY_OR_REGION_STRING_LIST { + NDIS_OBJECT_HEADER Header; + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_COUNTRY_OR_REGION_STRING CountryOrRegionStrings[1]; + } DOT11_COUNTRY_OR_REGION_STRING_LIST, *PDOT11_COUNTRY_OR_REGION_STRING_LIST; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST\_REVISION\_1. + +**Size** +This member must be set to sizeof(DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST). + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + +**uNumOfEntries** +Number of entries in the **CountryOrRegionStrings** array. A zero value for this member indicates an empty country string list. + +**uTotalNumOfEntries** +Maximum number of entries that the **CountryOrRegionStrings** array can contain. + +**CountryOrRegionStrings** +The list of supported 802.11d country strings. For more information about the data type of this member, see [**DOT11\_COUNTRY\_OR\_REGION\_STRING**](dot11-country-or-region-string.md). + +When OID\_DOT11\_SUPPORTED\_COUNTRY\_OR\_REGION\_STRING is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure, including all entries in the **CountryOrRegionStrings** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, as the following list shows: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure, the miniport driver must do the following: + + - Set the **uNumOfEntries** member to zero. + + - Set the **uTotalNumOfEntries** member to the number of entries in the **CountryOrRegionStrings** array. + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **CountryOrRegionStrings** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure. The miniport driver must also copy the entire DOT11\_COUNTRY\_OR\_REGION\_STRING\_LIST structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_COUNTRY_OR_REGION_STRING%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-data-rates-value.md b/windows-driver-docs-pr/network/oid-dot11-supported-data-rates-value.md new file mode 100644 index 0000000000..b7ccea9f47 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-data-rates-value.md @@ -0,0 +1,65 @@ +--- +title: OID\_DOT11\_SUPPORTED\_DATA\_RATES\_VALUE +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_DATA\_RATES\_VALUE +ms.assetid: 5daf34be-bbbf-4aca-818d-6db24aa15cd4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_DATA_RATES_VALUE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_DATA\_RATES\_VALUE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_DATA\_RATES\_VALUE OID requests that the miniport driver return the following for the current PHY type on the 802.11 station: + +- The transmit data rates supported by the Physical Layer Convergence Procedure (PLCP) and Physical Media Dependent (PMD) sublayer of the PHY. + +- The receive data rates supported by the PLCP and PMD of the PHY. + +The data type for OID\_DOT11\_SUPPORTED\_DATA\_RATES\_VALUE is the [**DOT11\_SUPPORTED\_DATA\_RATES\_VALUE\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff548790) structure. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_DATA_RATES_VALUE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-dsss-channel-list.md b/windows-driver-docs-pr/network/oid-dot11-supported-dsss-channel-list.md new file mode 100644 index 0000000000..7db48b8547 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-dsss-channel-list.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_SUPPORTED\_DSSS\_CHANNEL\_LIST +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_DSSS\_CHANNEL\_LIST +ms.assetid: ee1ff240-77ab-43eb-90a5-d11025fa5de4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_DSSS_CHANNEL_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_DSSS\_CHANNEL\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_DSSS\_CHANNEL\_LIST OID requests that the miniport driver returns the list of frequency channels that the 802.11 station can operate with. + +The data type for this OID is the [**DOT11\_SUPPORTED\_DSSS\_CHANNEL\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548796) structure. + +You can use this OID to indicate to the operating system any frequency channels that should be scanned for conformance with performance specifications. The operating system does not use these OIDs during routine operation of the 802.11 station. + +The OID MIB object is only valid for the following PHY types: + +- Direct-sequence spread spectrum (DSSS) PHY. + +- High-rate DSSS (HRDSSS) PHY. + +- Extended-rate PHY (ERP). + +- High-throughput (HT) 802.11n PHY when operating in the 2.4-GHz band. + +If the current PHY type is not set to **dot11\_phy\_type\_dsss**, **dot11\_phy\_type\_hrdsss**, **dot11\_phy\_type\_erp**, or **dot11\_phy\_type\_ht**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Support for this OID is optional, unless the station reports to the operating system that it supports one or more of the **dot11\_phy\_type\_dsss**, **dot11\_phy\_type\_hrdsss**, and **dot11\_phy\_type\_erp** PHY types. In this case support for this OID is mandatory. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_DSSS_CHANNEL_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-multicast-algorithm-pair.md b/windows-driver-docs-pr/network/oid-dot11-supported-multicast-algorithm-pair.md new file mode 100644 index 0000000000..e5f646849f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-multicast-algorithm-pair.md @@ -0,0 +1,67 @@ +--- +title: OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR +ms.assetid: 93927df1-acaa-4c42-b8e1-48f651b9ef96 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR object identifier (OID) requests that the miniport driver return a list of the authentication and cipher algorithms that the 802.11 station supports for multicast and broadcast packets. + +The data type for this OID is the [**DOT11\_AUTH\_CIPHER\_PAIR\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547662) structure. + +When OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR is queried, the miniport driver only returns 802.11 authentication and cipher algorithms that the 802.11 station supports for the current value of the IEEE **dot11DesiredBSSType** management information base (MIB) object. For more information about this MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +**Note**  For each value of the **dot11DesiredBSSType** MIB object, the miniport driver must not change the list of the 802.11 authentication and cipher algorithms after the OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR is queried. + +  + +There must be at least one cipher algorithm defined for each supported authentication algorithm. If the miniport driver does not support any multicast cipher algorithms for a particular authentication algorithm, it must still create a list entry for the authentication algorithm and use **DOT11\_CIPHER\_ALGO\_NONE** for the related cipher algorithm. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-ofdm-frequency-list.md b/windows-driver-docs-pr/network/oid-dot11-supported-ofdm-frequency-list.md new file mode 100644 index 0000000000..7cec8218c4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-ofdm-frequency-list.md @@ -0,0 +1,74 @@ +--- +title: OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST +ms.assetid: d6b22bc7-27c2-44cb-8f33-17e04596e0b1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_OFDM_FREQUENCY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST OID requests that the miniport driver returns the list of channel center frequencies that the 802.11 station can operate with. + +The data type for this OID is the [**DOT11\_SUPPORTED\_OFDM\_FREQUENCY\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548800) structure. + +You can use this OID to indicate to the operating system any frequency channels that should be scanned for conformance with performance specifications. The operating system does not use these OIDs during routine operation of the 802.11 station. + +The OID MIB object is only valid for the following PHY types: + +- Orthogonal frequency division multiplexing (OFDM) PHY. +- High-throughput (HT) 802.11n PHY or very high-throughput (VHT) 802.11ac PHY when operating in the 5-GHz band. + +If the current PHY type is not set to **dot11\_phy\_type\_ofdm**, **dot11\_phy\_type\_ht**, or **dot11\_phy\_type\_vht**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +Support for this OID is optional, unless the station reports to the operating system that it supports the **dot11\_phy\_type\_ofdm** PHY type. In this case support for this OID is mandatory. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_OFDM_FREQUENCY_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-phy-types.md b/windows-driver-docs-pr/network/oid-dot11-supported-phy-types.md new file mode 100644 index 0000000000..5ae49c4745 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-phy-types.md @@ -0,0 +1,131 @@ +--- +title: OID\_DOT11\_SUPPORTED\_PHY\_TYPES +author: windows-driver-content +description: When queried, the OID\_DOT11\_SUPPORTED\_PHY\_TYPES object identifier (OID) requests that the miniport driver return the value of the Native 802.11 Operational msDot11SupportedPhyTypes management information base (MIB) object. +ms.assetid: 4b267371-5e17-47d8-b521-bd4b130daa32 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_PHY_TYPES Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_PHY\_TYPES + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_PHY\_TYPES object identifier (OID) requests that the miniport driver return the value of the Native 802.11 Operational **msDot11SupportedPhyTypes** management information base (MIB) object. This MIB object defines the list of PHY types supported by the 802.11 station. + +The data type for this OID is the DOT11\_SUPPORTED\_PHY\_TYPES structure. + +```ManagedCPlusPlus + typedef struct _DOT11_SUPPORTED_PHY_TYPES { + ULONG uNumOfEntries; + ULONG uTotalNumOfEntries; + DOT11_PHY_TYPE dot11PHYType[1]; + } DOT11_SUPPORTED_PHY_TYPES, *PDOT11_SUPPORTED_PHY_TYPES; + +``` + +This structure includes the following members: + +**uNumOfEntries** +Number of entries in the **dot11PhyType** array. A zero value for this member indicates an empty list of supported PHY types. + +**uTotalNumOfEntries** +Maximum number of entries that the **dot11PhyType** array requires. + +**Note**  The operating system supports a maximum of 64 entries for the **dot11PhyType** array. + +  + +**dot11PhyType** +The list of supported PHY types. Each entry in this list is specified through a [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) enumeration. + +The following points apply to a miniport driver operating in Extensible Station (ExtSTA) mode: + +- When OID\_DOT11\_SUPPORTED\_PHY\_TYPES is queried, the miniport driver must add an entry in the **dot11PhyType** array for every PHY supported on the 802.11 station. If the 802.11 station supports proprietary or non-standard PHY types, the miniport driver must add an entry containing a PHY type value defined by the independent hardware vendor (IHV). For more information about IHV-defined PHY types, see [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741). + + If the 802.11 station supports multiple PHYs of the same type, the miniport driver must add separate entries for each PHY. + +- The number of entries within the **dot11PhyType** array and the order of the entries within the array must remain unchanged during the lifetime of the installation of the miniport driver. + + For any PHY type supported by the 802.11 station, its index within the **dot11PhyType** array must persist and not change while the miniport driver is installed on the host computer system. + +After OID\_DOT11\_SUPPORTED\_PHY\_TYPES is queried, the operating system will identify a PHY on the 802.11 station through one of the following methods: + +- If the miniport driver is operating in ExtSTA mode, the operating system will identify the PHY through a PHY identifier (ID). The PHY ID is the index into the list of PHYs returned in the **dot11PhyType** array. If the operating system specifies a PHY ID of DOT11\_PHY\_ID\_ANY, the miniport driver can use any supported PHY on the 802.11 station. + + The miniport driver will also use the PHY ID for Native 802.11 media-specific status indications. The miniport driver cannot use DOT11\_PHY\_ID\_ANY as a PHY ID for status indications. For more information about Native 802.11 media-specific status indications, see [Native 802.11 Wireless LAN Status Indications](https://msdn.microsoft.com/library/windows/hardware/ff560692). + +- If the miniport driver is not operating in ExtSTA mode, the operating system will identify the PHY through a PHY type as defined by a [**DOT11\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548741) enumeration value. + +When OID\_DOT11\_SUPPORTED\_PHY\_TYPES is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the entire DOT11\_SUPPORTED\_PHY\_TYPES structure, including all entries in the **dot11PhyType** array. The value of the **InformationBufferLength** member of the *OidRequest* parameter determines what the miniport driver must do, for example: + +- If the value of the **InformationBufferLength** member is less than the length, in bytes, of the entire DOT11\_SUPPORTED\_PHY\_TYPES structure, the miniport driver must do the following: + + - For the *OidRequest* parameter, set the **BytesWritten** member to zero and the **BytesNeeded** member to the length, in bytes, of the entire DOT11\_SUPPORTED\_PHY\_TYPES structure. + + - Fail the query request by returning NDIS\_STATUS\_BUFFER\_OVERFLOW from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the value of the **InformationBufferLength** member is greater than or equal to the length, in bytes, of the entire DOT11\_SUPPORTED\_PHY\_TYPES structure, the miniport driver must do the following to complete a successful query request: + + - For the DOT11\_SUPPORTED\_PHY\_TYPES structure, set the **uNumOfEntries** and **uTotalNumOfEntries** members to the total number of entries in the **dot11PhyType** array. + + - For the *OidRequest* parameter, set the **BytesNeeded** member to zero and the **BytesWritten** member to the length, in bytes, of the entire DOT11\_SUPPORTED\_PHY\_TYPES structure. The miniport driver must also copy the entire DOT11\_SUPPORTED\_PHY\_TYPES structure to the **InformationBuffer** member. + + - Return NDIS\_STATUS\_SUCCESS from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**Note**  If the miniport driver supports an 802.11n PHY, it must indicate this to the operating system as follows. +1. During initialization of the miniport driver and 802.11 station, set the **dot11\_phy\_type\_ht** value in the NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES->**SupportedPhyAttributes**->**PhyType** member. + +2. In response to an OID\_DOT11\_SUPPORTED\_PHY\_TYPES query, set the **dot11\_phy\_type\_ht** value in the DOT11\_SUPPORTED\_PHY\_TYPES->**dot11PhyType** member. + +  + +**Note**  If the miniport driver supports an 802.11ac PHY, it must indicate this to the operating system as follows. +1. During initialization of the miniport driver and 802.11 station, set the **dot11\_phy\_type\_vht** value in the NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES->**SupportedPhyAttributes**->**PhyType** member. + +2. In response to an OID\_DOT11\_SUPPORTED\_PHY\_TYPES query, set the **dot11\_phy\_type\_vht** value in the DOT11\_SUPPORTED\_PHY\_TYPES->**dot11PhyType** member. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_PHY_TYPES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-power-levels.md b/windows-driver-docs-pr/network/oid-dot11-supported-power-levels.md new file mode 100644 index 0000000000..14dcbfafd9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-power-levels.md @@ -0,0 +1,83 @@ +--- +title: OID\_DOT11\_SUPPORTED\_POWER\_LEVELS +author: windows-driver-content +description: When queried, the OID\_DOT11\_SUPPORTED\_POWER\_LEVELS OID requests that the miniport driver return the following for the current PHY type on the 802.11 station +ms.assetid: c285ff65-f6c0-444d-961d-614c50c86a1c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_POWER_LEVELS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_POWER\_LEVELS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_POWER\_LEVELS OID requests that the miniport driver return the following for the current PHY type on the 802.11 station: + +- The number of transmit power levels supported by the Physical Media Dependent (PMD) sublayer of the PHY. + +- The transmit power for all the supported levels, in milliwatts (mWs). + +The data type for OID\_DOT11\_SUPPORTED\_POWER\_LEVELS is the DOT11\_SUPPORTED\_POWER\_LEVELS structure. + +```ManagedCPlusPlus + typedef struct _DOT11_SUPPORTED_POWER_LEVELS { + ULONG uNumOfSupportedPowerLevels; + ULONG uTxPowerLevelValues[8]; + } DOT11_SUPPORTED_POWER_LEVELS, *PDOT11_SUPPORTED_POWER_LEVELS; + +``` + +This structure includes the following members: + +**uNumOfSupportedPowerLevels** +Number of supported power levels. **uNumOfSupportedPowerLevels** must have a value from 1 through 8. + +**uTxPowerLevelValues** +An array of the supported transmit power levels in units of milliwatts (mWs). Each power level must be a value from 0 through 1000. + +The miniport driver must use the power level specified in **uTxPowerLevelValues\[0\]** as its default power level. The miniport driver must set the power level of the 802.11 station to this default through its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function or when reset through a method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md). + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** management information base (MIB) object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_POWER_LEVELS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-rx-antenna.md b/windows-driver-docs-pr/network/oid-dot11-supported-rx-antenna.md new file mode 100644 index 0000000000..01a759a135 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-rx-antenna.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_SUPPORTED\_RX\_ANTENNA +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_RX\_ANTENNA +ms.assetid: 03159f85-e69b-4510-b429-507d1a2f517b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_RX_ANTENNA Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_RX\_ANTENNA + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_RX\_ANTENNA object identifier (OID) requests that the miniport driver return the list of antennas on the 802.11 station that support receive (RX) operations. + +The data type for this OID is the [**DOT11\_SUPPORTED\_ANTENNA\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548788) structure. + +When this OID is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the list of supported receive antennas. For more information about this procedure, see [**DOT11\_SUPPORTED\_ANTENNA\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548788). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_RX_ANTENNA%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-tx-antenna.md b/windows-driver-docs-pr/network/oid-dot11-supported-tx-antenna.md new file mode 100644 index 0000000000..19fd1e7d85 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-tx-antenna.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_SUPPORTED\_TX\_ANTENNA +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_TX\_ANTENNA +ms.assetid: 0b4dd0f2-50ba-4e5a-9cc7-354dadc70c06 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_TX_ANTENNA Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_TX\_ANTENNA + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_TX\_ANTENNA object identifier (OID) requests that the miniport driver return the list of antennas on the 802.11 station that support transmit (TX) operations. + +The data type for this OID is the [**DOT11\_SUPPORTED\_ANTENNA\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548788) structure. + +When OID\_DOT11\_SUPPORTED\_TX\_ANTENNA is queried, the miniport driver must verify that the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the list of supported transmit antennas. For more information about the procedure that verifies the size of the **InformationBuffer** member, see [**DOT11\_SUPPORTED\_ANTENNA\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff548788). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_TX_ANTENNA%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-supported-unicast-algorithm-pair.md b/windows-driver-docs-pr/network/oid-dot11-supported-unicast-algorithm-pair.md new file mode 100644 index 0000000000..724b2118a7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-supported-unicast-algorithm-pair.md @@ -0,0 +1,67 @@ +--- +title: OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR +author: windows-driver-content +description: OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR +ms.assetid: 8b16dfca-d9f3-4b51-8363-2799b8fb49c7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR object identifier (OID) requests that the miniport driver return a list of the 802.11 authentication and cipher algorithms that the 802.11 station supports for unicast packets. + +The data type for this OID is the [**DOT11\_AUTH\_CIPHER\_PAIR\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff547662) structure. + +When OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR is queried, the miniport driver only returns 802.11 authentication and cipher algorithms that the 802.11 station supports for the current value of the IEEE **dot11DesiredBSSType** management information base (MIB) object. For more information about this MIB object, see [OID\_DOT11\_DESIRED\_BSS\_TYPE](oid-dot11-desired-bss-type.md). + +**Note**  For each value of the **dot11DesiredBSSType** MIB object, the miniport driver must not change the list of the 802.11 authentication and cipher algorithms after the OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR is queried. + +  + +There must be at least one cipher algorithm defined for each supported authentication algorithm. If the miniport driver does not support any unicast cipher algorithms for a particular authentication algorithm, it must still create a list entry for the authentication algorithm and use **DOT11\_CIPHER\_ALGO\_NONE** for the related cipher algorithm. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-temp-type.md b/windows-driver-docs-pr/network/oid-dot11-temp-type.md new file mode 100644 index 0000000000..9ec10886d5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-temp-type.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_TEMP\_TYPE +author: windows-driver-content +description: OID\_DOT11\_TEMP\_TYPE +ms.assetid: dbfcb23a-5c59-4c03-acd8-46d61b71ab21 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_TEMP_TYPE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_TEMP\_TYPE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_TEMP\_TYPE object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11 **dot11TempType** management information base (MIB) object for the current PHY type on the 802.11 station. + +This MIB object specifies the operating temperature range of the current PHY type. + +The data type for OID\_DOT11\_TEMP\_TYPE is the [**DOT11\_TEMP\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/ff548806) enumeration. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_TEMP_TYPE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-ti-threshold.md b/windows-driver-docs-pr/network/oid-dot11-ti-threshold.md new file mode 100644 index 0000000000..717354bb96 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-ti-threshold.md @@ -0,0 +1,71 @@ +--- +title: OID\_DOT11\_TI\_THRESHOLD +author: windows-driver-content +description: OID\_DOT11\_TI\_THRESHOLD +ms.assetid: c3f5419b-d137-4ba8-a028-637e6c337db1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_TI_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_TI\_THRESHOLD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_TI\_THRESHOLD object identifier (OID) requests that the miniport driver return the value of the IEEE 802.11a **dot11TIThreshold** management information base (MIB) object for the current PHY type on the 802.11 station. + +The **dot11TIThreshold** MIB object specifies the TI threshold used by the current PHY type to detect a busy media. The PHY's clear channel assessment (CCA) mechanism reports a busy media when it detects an RSSI value above this threshold. + +The data type for OID\_DOT11\_TI\_THRESHOLD is a LONG value in units of dBm. + +The **dot11TIThreshold** MIB object is valid for only the orthogonal frequency division multiplexing (OFDM) PHY type. If the current PHY type is not set to **dot11\_phy\_type\_ofdm**, the miniport driver must fail the query request by returning NDIS\_STATUS\_INVALID\_DATA from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +If the miniport driver is operating in Extensible Station (ExtSTA) mode, the current PHY type is determined through the ExtSTA **msDot11CurrentPhyID** MIB object. This MIB object specifies the index of the current PHY type within the 802.11 station's list of supported PHY types. For more information about **msDot11CurrentPhyID**, see [OID\_DOT11\_CURRENT\_PHY\_ID](oid-dot11-current-phy-id.md). + +**Note**  A Native 802.11 miniport driver that is designed to run on the Windows Vista or Windows Server 2008 operating systems must always reset this 802.11 MIB OID to its default value. This is the case regardless of the value of the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure. This requirement applies to a miniport driver that, in a call to the **NdisMSetMiniportAttributes** function, sets **MiniportAttributes** -> **Native\_802\_11\_Attributes** -> **Header** -> **Revision** to NDIS\_MINIPORT\_ADAPTER\_802\_11\_ATTRIBUTES\_REVISION\_1. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 MIB OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560645) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_TI_THRESHOLD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-unicast-use-group-enabled.md b/windows-driver-docs-pr/network/oid-dot11-unicast-use-group-enabled.md new file mode 100644 index 0000000000..da834969b9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-unicast-use-group-enabled.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED +ms.assetid: 4ba327e9-0404-43ed-a45f-7a60e1c1892d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_UNICAST_USE_GROUP_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) **msDot11UnicastUseGroupEnabled** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **msDot11UnicastUseGroupEnabled** MIB object. + +The **msDot11UnicastUseGroupEnabled** MIB object specifies whether the 802.11 station has enabled the support for the "Use Group Key" cipher suite. For more information about the "Use Group Key" cipher suite, refer to Clause 7.3.2.9.1 of the IEEE 802.11i-2004 standard. + +**Note**  Support for OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED is mandatory if the 802.11 station supports any Wi-Fi Protected Access (WPA) or Robust Security Network Association (RSNA) authentication algorithms. The miniport driver specifies its support for this authentication algorithm when [OID\_DOT11\_SUPPORTED\_UNICAST\_ALGORITHM\_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) or [OID\_DOT11\_SUPPORTED\_MULTICAST\_ALGORITHM\_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) are queried. + +  + +The data type for OID\_DOT11\_UNICAST\_USE\_GROUP\_ENABLED is a BOOLEAN value. A value of **TRUE** indicates that the 802.11 station has enabled the support for the "Use Group Key" cipher suite. + +"Use Group Key" is a cipher suite defined for the Pairwise Key Cipher Suite List subfield of the RSN and WPA information elements (IEs). An access point (AP) uses this cipher suite if it does not support the use of a pairwise cipher algorithm for unicast packets. The AP advertises this cipher suite in the RSN and WPA IE that it sends in its Beacon and Probe Response frames. An 802.11 station that associates with the AP must use the "Use Group Key" cipher suite defined in the RSN or WPA IE for unicast packets. + +The 802.11 station can associate only with an AP that advertises the "Use Group Key" cipher suite if the following are true: + +- The 802.11 station has enabled the support for the "Use Group Key" cipher suite. + +- The 802.11 station has enabled the multicast cipher suite advertised in the Beacon or Probe Response received from the AP. + +The default for the **msDot11UnicastUseGroupEnabled** MIB object is **TRUE**. The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_UNICAST_USE_GROUP_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-unreachable-detection-threshold.md b/windows-driver-docs-pr/network/oid-dot11-unreachable-detection-threshold.md new file mode 100644 index 0000000000..83f267ac67 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-unreachable-detection-threshold.md @@ -0,0 +1,73 @@ +--- +title: OID\_DOT11\_UNREACHABLE\_DETECTION\_THRESHOLD +author: windows-driver-content +description: OID\_DOT11\_UNREACHABLE\_DETECTION\_THRESHOLD +ms.assetid: f73461f4-088d-4281-a7dd-5cf823f94293 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_UNREACHABLE\_DETECTION\_THRESHOLD + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_UNREACHABLE\_DETECTION\_THRESHOLD object identifier (OID) requests that the miniport driver set the Extensible Station (ExtSTA) **msDot11UnreachableDetectionThreshold** management information base (MIB) object to the specified value. + +When queried, this OID requests that the miniport driver return the value of the **msDot11UnreachableDetectionThreshold** MIB object. + +The **msDot11UnreachableDetectionThreshold** MIB object specifies the maximum amount of time before the 802.11 station determines that it has lost connectivity to either an access point (AP) (for infrastructure BSS networks) or peer station (for independent BSS networks). + +The data type for OID\_DOT11\_UNREACHABLE\_DETECTION\_THRESHOLD is a ULONG value in units of milliseconds. + +The independent hardware vendor (IHV) can define any criteria to determine an AP or peer station as unreachable. For example, the 802.11 station might consider an AP it has associated with as unreachable if the station has not received 802.11 Beacon or Probe Response frames from the AP during the past **msDot11UnreachableDetectionThreshold** milliseconds. + +After the 802.11 station has determined that the AP or peer station is unreachable, the miniport driver must perform a disassociation operation. For more information about this operation, see [Disassociation Operations](https://msdn.microsoft.com/library/windows/hardware/ff546439). + +The default for the **msDot11UnreachableDetectionThreshold** MIB object is 2,000 milliseconds (2 seconds). The miniport driver must set this MIB object to its default if any of the following occurs: + +- The miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. + +- A method request of [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) is made to reset the media access control (MAC) layer of the 802.11 station and the **bSetDefaultMIB** member of the DOT11\_RESET\_REQUEST structure is **TRUE**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-virtual-station-capability.md b/windows-driver-docs-pr/network/oid-dot11-virtual-station-capability.md new file mode 100644 index 0000000000..8e45ed7b41 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-virtual-station-capability.md @@ -0,0 +1,65 @@ +--- +title: OID\_DOT11\_VIRTUAL\_STATION\_CAPABILITY +author: windows-driver-content +description: OID\_DOT11\_VIRTUAL\_STATION\_CAPABILITY +ms.assetid: 589b0f06-ddb5-4771-98e3-26b52f07ac66 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_VIRTUAL_STATION_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_VIRTUAL\_STATION\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +The OID\_DOT11\_VIRTUAL\_STATION\_CAPABILITY object identifier (OID) requests that the NIC driver return the capabilities of a virtual 802.11 station. + +Support for this OID is optional. If the driver supports a Virtual Station MAC, it must also support this OID. + +The data type for this OID is the [**DOT11\_EXTSTA\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff547688) structure. + +The DOT11\_EXTSTA\_ATTRIBUTES structure that this OID returns must not contain any embedded pointers. The memory that this structure uses should be contiguous, and any pointers should point within this contiguous memory. + +The miniport driver must report support for the standard **DOT11\_AUTH\_ALGO\_80211\_OPEN** and **DOT11\_CIPHER\_ALGO\_NONE** authentication and cipher algorithms. The miniport driver can additionally report one or more IHV-defined authentication/cipher algorithm pairs. The operating system will block any IHV-defined network profiles that attempt to set the **DOT11\_AUTH\_ALGO\_80211\_OPEN**/ **DOT11\_CIPHER\_ALGO\_NONE** authentication/cipher algorithm pair on the virtual station adapter. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_VIRTUAL_STATION_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-additional-ie.md b/windows-driver-docs-pr/network/oid-dot11-wfd-additional-ie.md new file mode 100644 index 0000000000..09a005a6cd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-additional-ie.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_ADDITIONAL\_IE +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_ADDITIONAL\_IE object identifier (OID) is sent to the miniport to add Informational Elements (IEs) to probe responses and beacons. +ms.assetid: 45C14728-F53A-4FDA-A13D-CDB22DDB6F8C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_ADDITIONAL_IE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_ADDITIONAL\_IE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_ADDITIONAL\_IE object identifier (OID) is sent to the miniport to add Informational Elements (IEs) to probe responses and beacons. Additional IEs are also sent with this OID for inclusion in the probe requests generated by the miniport driver. + +The data type for OID\_DOT11\_WFD\_ADDITIONAL\_IE is the [**DOT11\_WFD\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/hh464144) structure. + +When the Wi-Fi Direct (WFD) port is operating in device mode, the IEs are only added to probe requests and responses. When the WFD port is operating in Group Owner (GO) mode, the IEs are also added to the beacons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/hh464144) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_ADDITIONAL_IE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-desired-group-id.md b/windows-driver-docs-pr/network/oid-dot11-wfd-desired-group-id.md new file mode 100644 index 0000000000..2d273aaa98 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-desired-group-id.md @@ -0,0 +1,78 @@ +--- +title: OID\_DOT11\_WFD\_DESIRED\_GROUP\_ID +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_DESIRED\_GROUP\_ID object identifier (OID) sets WFD group identifier that the miniport should use when starting as the WFD Group Owner (GO). +ms.assetid: BCE476DA-A9CD-4B50-AA89-8B604FDCE1E8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DESIRED_GROUP_ID Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DESIRED\_GROUP\_ID + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DESIRED\_GROUP\_ID object identifier (OID) sets WFD group identifier that the miniport should use when starting as the WFD Group Owner (GO). + +The data type for this OID is the **DOT11\_WFD\_GROUP\_ID** structure. + +```ManagedCPlusPlus + typedef struct _DOT11_WFD_GROUP_ID + { + DOT11_MAC_ADDRESS DeviceAddress; + DOT11_SSID SSID; + } DOT11_WFD_GROUP_ID, * PDOT11_WFD_GROUP_ID; + +``` + +This structure includes the following members: + +**DeviceAddress** +The address of the device that will become the GO. + + **SSID** +The SSID for the GO device. + +The identifier is used to configure the group when an [OID\_DOT11\_WFD\_START\_GO\_REQUEST](oid-dot11-wfd-start-go-request.md) OID is received. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[OID\_DOT11\_WFD\_START\_GO\_REQUEST](oid-dot11-wfd-start-go-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DESIRED_GROUP_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-device-capability.md b/windows-driver-docs-pr/network/oid-dot11-wfd-device-capability.md new file mode 100644 index 0000000000..d5718ad71f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-device-capability.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_DEVICE\_CAPABILITY +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_DEVICE\_CAPABILITY object identifier (OID) modifies the Peer-to-Peer (P2P) device functionality that a Wi-Fi Direct (WFD) device supports and advertises in the P2P Capability attribute. +ms.assetid: DAB74B39-A904-4F53-9123-0BBA86EBEEF0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DEVICE_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DEVICE\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DEVICE\_CAPABILITY object identifier (OID) modifies the Peer-to-Peer (P2P) device functionality that a Wi-Fi Direct (WFD) device supports and advertises in the P2P Capability attribute. + +The data type for this OID is the [**DOT11\_WFD\_DEVICE\_CAPABILITY\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/hh464145) structure. + +A miniport retains the updated information from the [**DOT11\_WFD\_DEVICE\_CAPABILITY\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/hh464145) for later use in a response. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_DEVICE\_CAPABILITY\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/hh464145) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DEVICE_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-device-info.md b/windows-driver-docs-pr/network/oid-dot11-wfd-device-info.md new file mode 100644 index 0000000000..f17b2fac73 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-device-info.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_DEVICE\_INFO +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_DEVICE\_INFO object identifier (OID) provides Wi-Fi Direct device information for setting Peer-to-Peer (P2P) attributes. +ms.assetid: EC526346-D2BB-4C25-A4B7-241CDBF6AD9E +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DEVICE_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DEVICE\_INFO + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DEVICE\_INFO object identifier (OID) provides Wi-Fi Direct device information for setting Peer-to-Peer (P2P) attributes. + +The data type for OID\_DOT11\_WFD\_DEVICE\_INFO is the [**DOT11\_WFD\_DEVICE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh464147) structure. + +The miniport retains the attribute information from the [**DOT11\_WFD\_DEVICE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh464147) structure for use in later response operations. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_DEVICE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh464147) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DEVICE_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-device-listen-channel.md b/windows-driver-docs-pr/network/oid-dot11-wfd-device-listen-channel.md new file mode 100644 index 0000000000..f9271a416a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-device-listen-channel.md @@ -0,0 +1,63 @@ +--- +title: OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL object identifier (OID) sets the listen channel of the Wi-Fi Direct device. +ms.assetid: D9413770-453E-4778-B765-82A49CFAA45F +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DEVICE_LISTEN_CHANNEL Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL object identifier (OID) sets the listen channel of the Wi-Fi Direct device. + +When queried, the OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL object identifier (OID) returns the listen channel of the Wi-Fi Direct device. + +The data type for OID\_DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL is the [**DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/hh768267) structure. + +Support for this OID is optional. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_DEVICE\_LISTEN\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/hh768267) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DEVICE_LISTEN_CHANNEL%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-disconnect-from-group-request.md b/windows-driver-docs-pr/network/oid-dot11-wfd-disconnect-from-group-request.md new file mode 100644 index 0000000000..3ee1655adf --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-disconnect-from-group-request.md @@ -0,0 +1,81 @@ +--- +title: OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST +author: windows-driver-content +ms.assetid: C0AE95DB-8186-4B89-8115-B6B300FD8D73 +description: +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DISCONNECT_FROM_GROUP_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST object identifier (OID) requests that a Wi-Fi Direct (WFD) client perform a disconnection operation from the WFD group it joined previously. The operation for this OID is identical to that of an [OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) request for an Extensible Station (ExtSTA) port. + +No data is associated with this OID. + +When OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUEST is set, the miniport driver must do the following: + +- If the WFD client is not joined to a group, fail the set request by returning **NDIS\_STATUS\_INVALID\_STATE** from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +- If the WFD client is performing a connection operation initiated through a set request of [OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST](-oid-dot11-wfd-connect-to-group-request.md), fail the set request by returning **NDIS\_STATUS\_INVALID\_STATE** from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. For more information about the connection operation, see [Connection Operations](https://msdn.microsoft.com/library/windows/hardware/ff545185). + +- If the WFD client station is joined to a group, perform a disconnection operation from the WFD group. For more information about the disconnection operation, see [Disconnection Operations](https://msdn.microsoft.com/library/windows/hardware/ff546447). + +- The WFD client must not power the radio off. + +- The miniport driver must transition to the INIT state of the WFD client port operation mode. For more information about operation modes and related states, see [Extensible Station Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff549887). + +- The WFD client must stay disconnected from any WFD group until the next set request of [OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST](-oid-dot11-wfd-connect-to-group-request.md). + +When OID\_DOT11\_WFD\_DISCONNECT\_FROM\_GROUP\_REQUESTis set, the miniport driver can do one of the following: + +- Wait for the disconnection operation to complete before completing the set request. + +- Initiate the disconnection operation and complete the set request. The miniport driver must return **NDIS\_STATUS\_PENDING** from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function after initiating the disconnection operation. After the disconnection operation has finished, the miniport driver completes the set request by calling [**NdisMRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622).The miniport driver also makes the [**NDIS\_STATUS\_DOT11\_CONNECTION\_COMPLETION**](ndis-status-dot11-connection-completion.md) asynchronously after the set request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[OID\_DOT11\_DISCONNECT\_REQUEST](oid-dot11-disconnect-request.md) + +[OID\_DOT11\_WFD\_CONNECT\_TO\_GROUP\_REQUEST](-oid-dot11-wfd-connect-to-group-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DISCONNECT_FROM_GROUP_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-discover-request.md b/windows-driver-docs-pr/network/oid-dot11-wfd-discover-request.md new file mode 100644 index 0000000000..edf2c2acfb --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-discover-request.md @@ -0,0 +1,87 @@ +--- +title: OID\_DOT11\_WFD\_DISCOVER\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_DISCOVER\_REQUEST object identifier (OID) requests that the miniport driver perform a device discovery operation and return the list of discovered devices and networks. +ms.assetid: 87EB02C3-09CA-4F7E-9523-35096727B16B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_DISCOVER_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_DISCOVER\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_DISCOVER\_REQUEST object identifier (OID) requests that the miniport driver perform a device discovery operation and return the list of discovered devices and networks. + +The data type for OID\_DOT11\_WFD\_DISCOVER\_REQUEST is the [**DOT11\_WFD\_DISCOVER\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh464149) structure. + +The system may provide the miniport driver additional Information Elements (IEs) that it should insert into the probe request packets for Wi-Fi Direct (WFD) device discovery. If provided, the driver should include these in probe requests sent for WFD devices. If IEs are not provided, the miniport driver must use the default request IEs in the [**DOT11\_WFD\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/hh464144) structure that was sent with [OID\_DOT11\_WFD\_ADDITIONAL\_IE](oid-dot11-wfd-additional-ie.md). + +After the device discovery has started, the miniport must perform the following to complete the OID: + +- If the process started successfully, the OID must be completed with **NDIS\_STATUS\_INDICATION\_REQUIRED**. + +- The completion of device discovery initiated by OID\_DOT11\_WFD\_DISCOVER\_REQUEST must be indicated to the system with a [**NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh451704) status indication. + +When the WFD device port performs a device discovery operation, the miniport driver should cache the received beacon and probe response packets. The miniport driver returns the list of the cached beacon and probe response packets in the completion indication and when queried by [OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](oid-dot11-wfd-enum-device-list.md). This list can contain devices discovered in other recent scans. + +The miniport driver must not report about any devices that have sent only probe requests and have not sent beacons or probe responses. The [**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) structure for each discovered peer device should include the IEs from both the beacon and probe response packets. + +While device discovery is in progress, the miniport may receive [OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](oid-dot11-wfd-enum-device-list.md) requests. It should return a device list that includes the devices found during the ongoing discovery, in addition to devices that have been discovered in other recent scans. + +The miniport must handle the situation where a WFD device supports multiple concurrent groups and can respond to probe requests as a WFD device as well as one or more WFD direct Group Owners (GOs). The miniport can use the transmitter address or BSSID from the received packets to distinguish various responses from the same Peer-to-Peer (P2P) device address. + +The miniport driver should delete stale entries from its cached device list. The rules for identifying stale entries is determined by miniport. Devices that have not been visible for more than five minutes must not be reported to the system. The miniport driver can also perform internal device discovery operations to add or update its cached device list. + +While operating system-requested discovery is in progress, the miniport should not enter the listen state except during the Find phase. That is, the miniport should ignore the listen-state discoverability setting if it is set to a value other than DOT11\_WFD\_DEVICE\_NOT\_DISCOVERABLE. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_ADDITIONAL\_IE**](https://msdn.microsoft.com/library/windows/hardware/hh464144) + +[**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) + +[**DOT11\_WFD\_DISCOVER\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh464149) + +[**NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh451704) + +[OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](oid-dot11-wfd-enum-device-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_DISCOVER_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-enum-device-list.md b/windows-driver-docs-pr/network/oid-dot11-wfd-enum-device-list.md new file mode 100644 index 0000000000..675839d8c4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-enum-device-list.md @@ -0,0 +1,79 @@ +--- +title: OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST +author: windows-driver-content +description: When queried, the OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST object identifier (OID) requests that the miniport driver return the list of other devices within range of the Wi-Fi Direct (WFD) device. +ms.assetid: 08264B77-BA5F-4352-A113-2FB5116F20B0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_ENUM_DEVICE_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST object identifier (OID) requests that the miniport driver return the list of other devices within range of the Wi-Fi Direct (WFD) device. The device list is created from the cache of devices the WFD device detected during the most recent device discovery operation. Device discovery is initiated with an [OID\_DOT11\_WFD\_DISCOVER\_REQUEST](oid-dot11-wfd-discover-request.md) OID. + +The data type for OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST is the [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure. + +The device list is returned in the **InformationBuffer** member of the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter. Each entry in the list is in the form of a [**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) structure. The entries are placed in the **ucBuffer** of the [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure. + +When this OID is queried, the miniport driver must do the following: + +- Verify that the **InformationBuffer** member of its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function's *OidRequest* parameter is large enough to return the device list. For more information about this procedure, see [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670). + + + +- The [**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) structure has a variable length. However, the miniport driver must not add padding for alignment between **DOT11\_WFD\_DEVICE\_ENTRY** structures returned in the **InformationBuffer** member of the *OidRequest* parameter. + + + +- Use the following macro for calculating the values of the **uNumOfBytes** and **uTotalNumOfBytes** members of the [**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) structure: `DOT11_WFD_DEVICE_ENTRY_GET_DEVICE_SIZE()`. + +The miniport driver may include any legacy networks discovered during a device discovery. If legacy networks are included, the information collected about the access point (AP) (infrastructure BSS networks) or peer station (independent BSS networks) should be included in the [**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) fields. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_BYTE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff547670) + +[**DOT11\_WFD\_DEVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/hh464146) + +[OID\_DOT11\_WFD\_ENUM\_DEVICE\_LIST](oid-dot11-wfd-enum-device-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_ENUM_DEVICE_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-flush-device-list.md b/windows-driver-docs-pr/network/oid-dot11-wfd-flush-device-list.md new file mode 100644 index 0000000000..cf3715eee4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-flush-device-list.md @@ -0,0 +1,56 @@ +--- +title: OID\_DOT11\_WFD\_FLUSH\_DEVICE\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_FLUSH\_DEVICE\_LIST object identifier (OID) requests that the miniport driver clear the device list cached in the Wi-Fi Direct (WFD) device. +ms.assetid: B9A281B8-331B-47D3-BB00-36BFC7948DE0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_FLUSH_DEVICE_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_FLUSH\_DEVICE\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_FLUSH\_DEVICE\_LIST object identifier (OID) requests that the miniport driver clear the device list cached in the Wi-Fi Direct (WFD) device. The miniport must flush the list of WFD devices and Group Owners (GOs) when it receives this OID. + +The miniport may also flush the list of infrastructure access points and discovered adhoc networks when it receives this OID. + +No data is sent with this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_FLUSH_DEVICE_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-get-dialog-token.md b/windows-driver-docs-pr/network/oid-dot11-wfd-get-dialog-token.md new file mode 100644 index 0000000000..09855a9394 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-get-dialog-token.md @@ -0,0 +1,66 @@ +--- +title: OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN +author: windows-driver-content +description: When queried, the OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN object identifier (OID) requests that the miniport driver return a dialog token for use in a later action frame send request OID. +ms.assetid: 5F283F85-4470-4605-877E-E6DC143DA659 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_GET_DIALOG_TOKEN Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When queried, the OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN object identifier (OID) requests that the miniport driver return a dialog token for use in a later action frame send request OID. + +The data type for OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN is the **DOT11\_DIALOG\_TOKEN** definition. + +```ManagedCPlusPlus + typedef UCHAR DOT11_DIALOG_TOKEN; + +``` + +The meaning of the data type is: + +**DOT11\_DIALOG\_TOKEN** +The dialog token value from the action request and response packets. + +Before issuing an OID to send a Group Owner (GO) negotiation request, a Peer-to-Peer (P2P) invitation request, or a provision discovery request, the system issues an OID\_DOT11\_WFD\_GET\_DIALOG\_TOKEN to query the miniport for the dialog token to use in the send request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_GET_DIALOG_TOKEN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-group-owner-capability.md b/windows-driver-docs-pr/network/oid-dot11-wfd-group-owner-capability.md new file mode 100644 index 0000000000..5d58364be0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-group-owner-capability.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY object identifier (OID) modifies the Peer-to-Peer (P2P) group capability bitmask that a Group Owner (GO) advertises in a P2P capability attribute. +ms.assetid: 9C28ABA0-C69F-4383-8BD5-4306D31FA27D +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_GROUP_OWNER_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY object identifier (OID) modifies the Peer-to-Peer (P2P) group capability bitmask that a Group Owner (GO) advertises in a P2P capability attribute. + +The data type for this OID is the [**DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/hh464151) structure. + +A miniport retains the updated information from the [**DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/hh464151) for later use in a response. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_GROUP\_OWNER\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/hh464151) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_GROUP_OWNER_CAPABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-group-start-parameters.md b/windows-driver-docs-pr/network/oid-dot11-wfd-group-start-parameters.md new file mode 100644 index 0000000000..19df7ed44b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-group-start-parameters.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_GROUP\_START\_PARAMETERS +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_GROUP\_START\_PARAMETERS object identifier (OID) provides the startup parameters for a Wi-Fi Direct (WFD) Group Owner (GO). +ms.assetid: E71D6292-2265-4D41-A4E9-430B6AB7B702 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_GROUP_START_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_GROUP\_START\_PARAMETERS + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_GROUP\_START\_PARAMETERS object identifier (OID) provides the startup parameters for a Wi-Fi Direct (WFD) Group Owner (GO). + +The data type for this OID is the [**DOT11\_WFD\_GROUP\_START\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406659) structure. + +This OID is sent to the miniport only when the group is started after a GO negotiation or invitation exchange. The WFD GO port must also support starting the group with appropriate start parameters when this OID is not set. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_GROUP\_START\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406659) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_GROUP_START_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-listen-state-discoverability.md b/windows-driver-docs-pr/network/oid-dot11-wfd-listen-state-discoverability.md new file mode 100644 index 0000000000..846f8945f1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-listen-state-discoverability.md @@ -0,0 +1,91 @@ +--- +title: OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY object identifier (OID) is used to set the discoverability state of a Wi-Fi Direct (WFD) device and to configure its availability settings. +ms.assetid: C2BFB189-18B4-4FA9-AC17-2FEE53DC2E53 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_LISTEN_STATE_DISCOVERABILITY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY object identifier (OID) is used to set the discoverability state of a Wi-Fi Direct (WFD) device and to configure its availability settings. + +The data type for OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY is a **ULONG** availability value. + +The WFD availability is set to one of the following values. + + ++++ + + + + + + + + + + + + + + + + + + + + +
TermDescription

DOT11_WFD_DEVICE_NOT_DISCOVERABLE

The WFD device port must remain undiscoverable. The device must not periodically put itself in the listen state to allow other devices to discover it. This is the default availability setting.

DOT11_WFD_DEVICE_AUTO_AVAILABILITY

The WFD device port must periodically put itself in the listen state to become discoverable. It must use appropriate availability periods to balance power, discoverability, and performance of the WFD ports and other ports on the miniport. It must follow the availability guidelines in the Wi-Fi Direct Peer-To-Peer Technical Specification.

DOT11_WFD_DEVICE_HIGH_AVAILABILITY

The WFD device port must frequently put itself into the listen state for an extended duration to increase the speed and reliability of remote devices discovering it. For example, a remote device that periodically scans the listen channel at 250ms intervals should discover the device within no more than 250ms. To achieve this, the device may be available on the listen channel for a contiguous 300ms every 400ms. The DOT11_WFD_DEVICE_HIGH_AVAILABILITY setting must not result in loss of connectivity on the ExtSTA (infrastructure) or any Wi-Fi Direct ports. It is, however, expected that this setting may degrade the performance of these connections in terms of latency and throughput.

+ +  + +Responding to the OID\_DOT11\_WFD\_LISTEN\_STATE\_DISCOVERABILITY request is only applicable when the WFD port is in device mode. When the port is in Group Owner (GO) mode and the group is started, it must be discoverable as required by the Wi-Fi Peer-To-Peer Technical Specification. + +When the WFD device is discoverable, the miniport driver selects a listen channel. After the miniport sets the device to discoverable, it should transition in and out of the listen state as required by the Wi-Fi Direct Peer-To-Peer Technical Specification. + +On initialization, the WFD port must use the default availability setting, **DOT11\_WFD\_DEVICE\_NOT\_DISCOVERABLE**, to determine its behavior. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_LISTEN_STATE_DISCOVERABILITY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-secondary-device-type-list.md b/windows-driver-docs-pr/network/oid-dot11-wfd-secondary-device-type-list.md new file mode 100644 index 0000000000..74c4664e6d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-secondary-device-type-list.md @@ -0,0 +1,61 @@ +--- +title: OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST object identifier (OID) is used to configure the secondary device types advertised by a Wi-Fi Direct (WFD) device. +ms.assetid: CC712E1D-6A06-458C-A6C1-76713CE78DAF +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SECONDARY_DEVICE_TYPE_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST object identifier (OID) is used to configure the secondary device types advertised by a Wi-Fi Direct (WFD) device. + +The data type for OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST is the [**DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/hh464152) structure. + +The OID\_DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST OID can be submitted to a WFD port in any operational state, either INIT or OP. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_WFD\_SECONDARY\_DEVICE\_TYPE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/hh464152) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SECONDARY_DEVICE_TYPE_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-confirmation.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-confirmation.md new file mode 100644 index 0000000000..f638456ef3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-confirmation.md @@ -0,0 +1,70 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION object identifier (OID) provides the miniport driver with the parameters for a Group Owner (GO) negotiation confirmation. +ms.assetid: 4D836BED-F3F0-4224-9438-C39B8122EE03 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_GO_NEGOTIATION_CONFIRMATION Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION object identifier (OID) provides the miniport driver with the parameters for a Group Owner (GO) negotiation confirmation. The OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION request is sent after the miniport inidicates a [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh439791) indication. + +The data type for OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_CONFIRMATION is the [**DOT11\_SEND\_GO\_NEGOTIATION\_COMFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406537) structure. + +This is a direct OID called in the context of a [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh439791) indication. + +After receiving this OID, the miniport must create and populate all the required Peer-to-Peer (P2P) attributes in the P2P Information Element (IE) before it sends the GO negotiation confirmation packet. + +**Note**  Miniports must handle this OID synchronously. They must not process requests as pending. + +  + +The completion of the attempt to send the GO negotiation response attempt must be indicated to the system with a [**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh451706) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_CONFIRMATION\_SEND\_COMPLETE** indication after it has stopped the attempt to send the GO negotiation response. This must occur in either case of success or failure. +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_SEND\_GO\_NEGOTIATION\_COMFIRMATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406537) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh439791) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_GO_NEGOTIATION_CONFIRMATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-request.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-request.md new file mode 100644 index 0000000000..9624c4fe15 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-request.md @@ -0,0 +1,128 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) miniport driver send a Group Owner (GO) negotiation request to a WFD peer currently in device mode. +ms.assetid: B23D8381-1331-4DCD-B63A-7514A38970C6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_GO_NEGOTIATION_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) miniport driver send a Group Owner (GO) negotiation request to a WFD peer currently in device mode. + +The data type for OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_REQUEST is the **DOT11\_SEND\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS** structure. + +```ManagedCPlusPlus + typedef struct _DOT11_SEND_GO_NEGOTIATION_REQUEST_PARAMETERS { + NDIS_OBJECT_HEADER Header; + DOT11_MAC_ADDRESS PeerDeviceAddress; + DOT11_DIALOG_TOKEN DialogToken; + ULONG uSendTimeout; + DOT11_WFD_GO_INTENT GroupOwnerIntent; + DOT11_WFD_CONFIGURATION_TIMEOUT MinimumConfigTimeout; + DOT11_MAC_ADDRESS IntendedInterfaceAddress; + DOT11_WFD_GROUP_CAPABILITY GroupCapability; + ULONG uIEsOffset; + ULONG uIEsLength; + } DOT11_SEND_GO_NEGOTIATION_REQUEST_PARAMETERS, * PDOT11_SEND_GO_NEGOTIATION_REQUEST_PARAMETERS; + +``` + +This structure includes the following members: + +**Header** +The type, revision, and size of the **DOT11\_SEND\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS** structure. This member is formatted as an [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure. + +The miniport driver must set the members of **Header** to the following values: + +**Type** +This member must be set to NDIS\_OBJECT\_TYPE\_DEFAULT. + +**Revision** +This member must be set to DOT11\_SEND\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS\_REVISION\_1. + +**Size** +This member must be set to DOT11\_SIZEOF\_SEND\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS\_REVISION\_1. + +For more information about these members, see [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588). + + **PeerDeviceAddress** +The Peer-to-Peer (P2P) address of the Wi-Fi Direct (WFD) device where the GO negotiation request will be sent. + + **DialogToken** +The dialog token to insert in the GO negotiation request packet. + + **uSendTimeout** +The maximum time, in milliseconds, allowed to send the GO negotiation request. If the time-out expires before the miniport has successfully transmitted the GO negotiation request, it should indicate the [**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439774) with a failure status. + + **GroupOwnerIntent** +The GO intent value. This value is included in the Group Owner Intent attribute of the GO negotiation request packet. + + **MinimumConfigTimeout** +The configuration time-out, in milliseconds, required by the system to change its mode of operation to Peer-to-Peer (P2P) GO or P2P Client. The miniport driver can overwrite this value with a longer time-out. + + **IntendedInterfaceAddress** +The Intended Interface address to be used for generation of the GO negotiation request. + + **GroupCapability** +The values to set in the Group Capability bitmask of the P2P Capability Information Element (IE) in the GO negotiation request. + + **uIEsOffset** +The offset, in bytes, of the array of additional IEs the Wi-Fi Direct (WFD) port must add to the GO negotiation request packet. This offset is from the start of the buffer that contains this structure. + + **uIEsLength** +The length, in bytes, of the array of IEs provided at **uIEsOffset**. + +When receiving this OID, the miniport must create and populate all the required P2P attributes in the P2P IE prior to sending the GO negotiation request packet. + +This OID is sent to the miniport with **NdisRequestSetInformation** as the OID request type. After creating the packet for transmission, the miniport must complete the OID with **NDIS\_STATUS\_INDICATION\_REQUIRED**. The completion of the attempt to send the GO negotiation request must be indicated back to the system with an [**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439774) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE** after stopping the attempt to send the GO negotiation request. This must occur in either case of success or failure. + +Miniport drivers should periodically attempt sending the GO Negotiation Request frame at intervals no longer than 50ms because a remote device may not be constantly available on its listen channel. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) + +[**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439774) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_GO_NEGOTIATION_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-response.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-response.md new file mode 100644 index 0000000000..d15a77431a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-go-negotiation-response.md @@ -0,0 +1,70 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE object identifier (OID) provides the miniport driver with the parameters for a Group Owner (GO) negotiation request. +ms.assetid: 2D13222D-1936-4676-B20E-D26E3B219FC2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_GO_NEGOTIATION_RESPONSE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE object identifier (OID) provides the miniport driver with the parameters for a Group Owner (GO) negotiation request. The OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE request is sent after the miniport indicates an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439789) indication. + +The data type for OID\_DOT11\_WFD\_SEND\_GO\_NEGOTIATION\_RESPONSE is the [**DOT11\_SEND\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406540) structure. + +This is a direct OID called in the context of an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439789) indication. + +After receiving this OID, the miniport must create and populate all the required Peer-to-Peer (P2P) attributes in the P2P Information Element (IE) before it sends the GO negotiation response packet. + +**Note**  Miniports must handle this OID synchronously. They must not process requests as pending. + +  + +The completion of the attempt to send the GO negotiation response attempt must be indicated to the system with an [**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439776) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE** indication after it has stopped the attempt to send the GO negotiation response. This must occur in either case of success or failure. +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**NDIS\_STATUS\_DOT11\_WFD\_GO\_NEGOTIATION\_RESPONSE\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439776) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_GO\_NEGOTIATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439789) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_GO_NEGOTIATION_RESPONSE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-request.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-request.md new file mode 100644 index 0000000000..d44e8afd07 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-request.md @@ -0,0 +1,69 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST object identifier (OID) is sent to the miniport driver with the parameters for an invitation request. +ms.assetid: 1612EE79-FF44-4FC5-9266-39314E511BD0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_INVITATION_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST object identifier (OID) is sent to the miniport driver with the parameters for an invitation request. + +The data type for OID\_DOT11\_WFD\_SEND\_INVITATION\_REQUEST is the [**DOT11\_SEND\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406546) structure. + +This OID is sent to the miniport as an **NdisRequestMethod** OID request type. + +After receiving this OID, the miniport must create and populate all the required Peer-to-Peer (P2P) attributes in the P2P Information Element (IE) before it sends the invitation request packet. + +After creating the packet for transmission, the miniport must complete the OID with a status of **NDIS\_STATUS\_INDICATION\_REQUIRED**. The completion of the attempt to send the invitation request attempt must be indicated to the system with an [**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439779) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE** indication after it has stopped the attempt to send the invitation request. This must occur in either case of success or failure. + +Miniport drivers should periodically attempt sending the Invitation Request frame at intervals no longer than 50ms because a remote device may not be constantly available on its listen channel (or, operating channel in case of GO). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_SEND\_INVITATION\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406546) + +[**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_REQUEST\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439779) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_INVITATION_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-response.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-response.md new file mode 100644 index 0000000000..08138ce56e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-invitation-response.md @@ -0,0 +1,72 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE object identifier (OID) is sent to the miniport driver with the parameters to respond to an invitation request. +ms.assetid: D80224C0-980E-4F9E-9A10-6F5AB4B306D4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_INVITATION_RESPONSE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE object identifier (OID) is sent to the miniport driver with the parameters to respond to an invitation request. The OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE request is sent after the miniport inidicates an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439793) indication. + +The data type for OID\_DOT11\_WFD\_SEND\_INVITATION\_RESPONSE is the [**DOT11\_SEND\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406551) structure. + +This is a direct OID called in the context of an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439793) indication. + +After receiving this OID, the miniport must create and populate all the required Peer-to-Peer (P2P) attributes in the P2P Information Element (IE) before it sends the invitation response packet. + +**Note**  Miniports must handle this OID synchronously. They must not process requests as pending. + +  + +The completion of the attempt to send the invitation response attempt must be indicated to the system with an [**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439781) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE** indication after it has stopped the attempt to send the invitation response. This must occur in either case of success or failure. +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_SEND\_INVITATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406551) + +[**NDIS\_STATUS\_DOT11\_WFD\_INVITATION\_RESPONSE\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439781) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_INVITATION\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439793) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_INVITATION_RESPONSE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-send-provision-discovery-response.md b/windows-driver-docs-pr/network/oid-dot11-wfd-send-provision-discovery-response.md new file mode 100644 index 0000000000..7bfeee4f6d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-send-provision-discovery-response.md @@ -0,0 +1,68 @@ +--- +title: OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE object identifier (OID) is sent to the miniport driver with the parameters to send in a provision discovery response. +ms.assetid: 07EEB56F-EC84-4C7E-AF06-A4B87269A992 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_RESPONSE Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE object identifier (OID) is sent to the miniport driver with the parameters to send in a provision discovery response. The OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE request is sent after the miniport indicates an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439797) indication. + +The data type for OID\_DOT11\_WFD\_SEND\_PROVISION\_DISCOVERY\_RESPONSE is the [**DOT11\_SEND\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406561) structure. + +This is a direct OID called in the context of an [**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439797) indication. + +**Note**  Miniports must handle this OID synchronously. They must not process requests as pending. + +  + +The completion of the attempt to send the invitation response attempt must be indicated to the system with an [**NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh439781) indication. The miniport driver must send the **NDIS\_STATUS\_DOT11\_WFD\_PROVISION\_DISCOVERY\_RESPONSE\_SEND\_COMPLETE** indication after it has stopped the attempt to send the provision discovery response. This must occur in either case of success or failure. +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**DOT11\_SEND\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh406561) + +[**NDIS\_STATUS\_DOT11\_WFD\_RECEIVED\_PROVISION\_DISCOVERY\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh439797) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_RESPONSE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-start-go-request.md b/windows-driver-docs-pr/network/oid-dot11-wfd-start-go-request.md new file mode 100644 index 0000000000..1fd8d0db27 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-start-go-request.md @@ -0,0 +1,59 @@ +--- +title: OID\_DOT11\_WFD\_START\_GO\_REQUEST +author: windows-driver-content +description: When set, the OID\_DOT11\_WFD\_START\_GO\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) Group Owner (GO) start the group. +ms.assetid: 1512E48E-5498-4261-BA04-14581F1FD70F +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_START_GO_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_START\_GO\_REQUEST + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WFD\_START\_GO\_REQUEST object identifier (OID) requests that the Wi-Fi Direct (WFD) Group Owner (GO) start the group. The WFD port should use port configuration information to create beacons, start beaconing, and respond to probe requests. + +The miniport behavior for this OID on a WFD GO port is identical to the behavior of an Extensible Access Point port for an [OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[OID\_DOT11\_START\_AP\_REQUEST](oid-dot11-start-ap-request.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_START_GO_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wfd-stop-discovery.md b/windows-driver-docs-pr/network/oid-dot11-wfd-stop-discovery.md new file mode 100644 index 0000000000..685ca9db84 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wfd-stop-discovery.md @@ -0,0 +1,57 @@ +--- +title: OID\_DOT11\_WFD\_STOP\_DISCOVERY +author: windows-driver-content +description: OID\_DOT11\_WFD\_STOP\_DISCOVERY is used to request the Wi-Fi Direct Device to stop any ongoing P2P discovery operation. +ms.assetid: 3180CE98-E8A0-4505-B2E6-766442A820FD +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WFD_STOP_DISCOVERY Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WFD\_STOP\_DISCOVERY + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +OID\_DOT11\_WFD\_STOP\_DISCOVERY is used to request the Wi-Fi Direct Device to stop any ongoing P2P discovery operation. If a discovery request initiated by Windows is in progress, the Wi-Fi Direct device must complete it by issuing [**NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh451704) status indication to Windows. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Windot11.h (include Windot11.h)
+ +## See also + + +[**NDIS\_STATUS\_DOT11\_WFD\_DISCOVER\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh451704) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WFD_STOP_DISCOVERY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-dot11-wps-enabled.md b/windows-driver-docs-pr/network/oid-dot11-wps-enabled.md new file mode 100644 index 0000000000..4b5012faec --- /dev/null +++ b/windows-driver-docs-pr/network/oid-dot11-wps-enabled.md @@ -0,0 +1,95 @@ +--- +title: OID\_DOT11\_WPS\_ENABLED +author: windows-driver-content +description: OID\_DOT11\_WPS\_ENABLED +ms.assetid: 84dd7496-19e4-4c0c-8208-9ad4d1797154 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_DOT11_WPS_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_DOT11\_WPS\_ENABLED + + +**Important**  The [Native 802.11 Wireless LAN](https://msdn.microsoft.com/library/windows/hardware/ff560690) interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see [WLAN Universal Windows driver model](https://msdn.microsoft.com/library/windows/hardware/dn897672). + +  + +When set, the OID\_DOT11\_WPS\_ENABLED object identifier (OID) requests that the miniport driver set the value of the Boolean **msDot11WpsEnabled** management information base (MIB) object. If **msDot11WpsEnabled** is set to **TRUE**, WiFi Protected Setup (WPS) is enabled on the NIC. Otherwise WPS is disabled. The NIC must complete the set request regardless of whether the Extensible AP is in the INIT or OP states. + +When queried, this OID requests that the miniport driver return the value of the Boolean **msDot11WpsEnabled** MIB object. If **msDot11AdditionalIEs** is **TRUE**, WiFi Protected Setup (WPS) is enabled on the NIC. Otherwise WPS is disabled. + +The **msDot11WpsEnabled** object is only applicable to the Extensible AP. + +**Note**  Support for this OID is mandatory. + +  + +The default value of **msDot11WpsEnabled** is **FALSE**. It is reset to the default value whenever an [OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) request is received. + +If WPS is enabled on a NIC that is operating in Extensible AP mode, the miniport driver must allow peer stations to associate with the Extensible AP by using [Open System Authentication](https://msdn.microsoft.com/library/windows/hardware/ff569852) or [Wired Equivalent Privacy (WEP)](https://msdn.microsoft.com/library/windows/hardware/ff571060) algorithms, regardless of the enabled authorization and cipher algorithms. For these peer stations, the miniport driver must enforce the following: + +- For inbound packets, only unicast 802.1X packets are accepted. Other data packets will be dropped. + +- For outbound packets, only unicast 802.1X packets are allowed to be sent to the stations. Broadcast and multicast packets are not affected. + +- No encryption or decryption is allowed on unicast data packets. Inbound encrypted data packets are dropped. + +When WPS is disabled, the miniport driver must disassociate all peer stations that were associated by using Open System Authentication or WEP algorithms if they were not among the enabled authorization and cipher algorithms. + +The 802.11 miniport driver should allow only the following pairs of [**DOT11\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547655) and [**DOT11\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/ff547672) authentication and cipher algorithms, depending on whether WPS is enabled or disabled. + +**WPS is enabled** +- **DOT11\_AUTH\_ALGO\_WPA\_PSK/DOT11\_CIPHER\_ALGO\_CCMP** + +- **DOT11\_AUTH\_ALGO\_80211\_OPEN/DOT11\_CIPHER\_ALGO\_WEPXXX** + +- **DOT11\_AUTH\_ALGO\_80211\_OPEN/DOT11\_CIPHER\_ALGO\_NONE** + +**WPS is disabled** +- **DOT11\_AUTH\_ALGO\_WPA\_PSK/DOT11\_CIPHER\_ALGO\_CCMP** + +**Note**  The NIC's response to 802.11 Beacon or Probe Response frames must not change when WPS is enabled with this OID, even if some peer stations were associated by using Open System Authentication or WEP algorithms. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of the Windows operating systems.

Header

Windot11.h (include Ndis.h)
+ +## See also + + +[OID\_DOT11\_RESET\_REQUEST](oid-dot11-reset-request.md) + +[Native 802.11 Wireless LAN OIDs](https://msdn.microsoft.com/library/windows/hardware/ff560691) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_DOT11_WPS_ENABLED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-admin-status.md b/windows-driver-docs-pr/network/oid-gen-admin-status.md new file mode 100644 index 0000000000..c8bb71d214 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-admin-status.md @@ -0,0 +1,68 @@ +--- +title: OID\_GEN\_ADMIN\_STATUS +author: windows-driver-content +description: As a query, use the OID\_GEN\_ADMIN\_STATUS OID to determine the administrative status for an interface (ifAdminStatus from RFC 2863). +ms.assetid: e8f45521-7419-4c11-b84b-36d4d3306fc2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_ADMIN_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_ADMIN\_STATUS + + +As a query, use the OID\_GEN\_ADMIN\_STATUS OID to determine the administrative status for an interface (*ifAdminStatus* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +The administrative status is the status that the system administrator requested. + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the query succeeds, the interface provider returns NDIS\_STATUS\_SUCCESS, and the result of the query can be one of the values in the [**NET\_IF\_ADMIN\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff568740) enumeration. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NET\_IF\_ADMIN\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff568740) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_ADMIN_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-alias.md b/windows-driver-docs-pr/network/oid-gen-alias.md new file mode 100644 index 0000000000..326d9c629a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-alias.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_ALIAS +author: windows-driver-content +description: As a query, use the OID\_GEN\_ALIAS OID to obtain the alias string for an interface (ifAlias from RFC 2863). Version Information Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: ff5e6494-aa4e-4a0a-b773-64b612236c8c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_ALIAS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_ALIAS + + +As a query, use the OID\_GEN\_ALIAS OID to obtain the alias string for an interface (*ifAlias* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +An [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) provider can assign unique alias strings for its interfaces. If the name should remain associated with the same interface, the provider can make the strings persistent after the computer restarts and reinitializations. + +Only NDIS network interface providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is an alias string that is returned in an NDIS\_IF\_COUNTED\_STRING structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_ALIAS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-rcv.md b/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-rcv.md new file mode 100644 index 0000000000..b589dc15a3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_BROADCAST\_BYTES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_BROADCAST\_BYTES\_RCV OID specifies the number of bytes in broadcast packets that are received without errors. +ms.assetid: 1047f3a9-be4a-4836-ac48-a9029c6f748f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BROADCAST_BYTES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BROADCAST\_BYTES\_RCV + + +As a query, the OID\_GEN\_BROADCAST\_BYTES\_RCV OID specifies the number of bytes in broadcast packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BROADCAST_BYTES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-xmit.md b/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-xmit.md new file mode 100644 index 0000000000..bf6eabde17 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-broadcast-bytes-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_BROADCAST\_BYTES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_BROADCAST\_BYTES\_XMIT OID specifies the number of bytes in broadcast packets that are transmitted without errors. +ms.assetid: a7df77fb-4319-4d15-9c12-5fd718395305 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BROADCAST_BYTES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BROADCAST\_BYTES\_XMIT + + +As a query, the OID\_GEN\_BROADCAST\_BYTES\_XMIT OID specifies the number of bytes in broadcast packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BROADCAST_BYTES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-broadcast-frames-rcv.md b/windows-driver-docs-pr/network/oid-gen-broadcast-frames-rcv.md new file mode 100644 index 0000000000..a59b163a2b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-broadcast-frames-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_BROADCAST\_FRAMES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_BROADCAST\_FRAMES\_RCV OID specifies the number of broadcast packets that are received without errors. +ms.assetid: c9b09318-a12e-4429-b05c-fee525ab33f5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BROADCAST_FRAMES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BROADCAST\_FRAMES\_RCV + + +As a query, the OID\_GEN\_BROADCAST\_FRAMES\_RCV OID specifies the number of broadcast packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BROADCAST_FRAMES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-broadcast-frames-xmit.md b/windows-driver-docs-pr/network/oid-gen-broadcast-frames-xmit.md new file mode 100644 index 0000000000..fe2dc3bcc0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-broadcast-frames-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_BROADCAST\_FRAMES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_BROADCAST\_FRAMES\_XMIT OID specifies the number of broadcast packets that are transmitted without errors. +ms.assetid: e86602ce-18b7-48ef-8962-75f6984d7bdb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BROADCAST_FRAMES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BROADCAST\_FRAMES\_XMIT + + +As a query, the OID\_GEN\_BROADCAST\_FRAMES\_XMIT OID specifies the number of broadcast packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BROADCAST_FRAMES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-bytes-rcv.md b/windows-driver-docs-pr/network/oid-gen-bytes-rcv.md new file mode 100644 index 0000000000..e5c709f91d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-bytes-rcv.md @@ -0,0 +1,70 @@ +--- +title: OID\_GEN\_BYTES\_RCV +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_BYTES\_RCV OID to determine the total number of bytes that a miniport adapter received. +ms.assetid: e613e155-e4ff-48e4-8087-20ecad3c4644 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BYTES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BYTES\_RCV + + +As a query, NDIS and overlying drivers use the OID\_GEN\_BYTES\_RCV OID to determine the total number of bytes that a miniport adapter received. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID for miniport drivers. See the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) OID for more information about statistics. + +The total byte count is the sum of the receive-directed byte count, receive-multicast byte count and receive-broadcast byte count. This value is the same as the sum of the values that are returned by the [OID\_GEN\_DIRECTED\_BYTES\_RCV](oid-gen-directed-bytes-rcv.md), [OID\_GEN\_MULTICAST\_BYTES\_RCV](oid-gen-multicast-bytes-rcv.md), and [OID\_GEN\_BROADCAST\_BYTES\_RCV](oid-gen-broadcast-bytes-rcv.md) OIDs. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_BROADCAST\_BYTES\_RCV](oid-gen-broadcast-bytes-rcv.md) + +[OID\_GEN\_DIRECTED\_BYTES\_RCV](oid-gen-directed-bytes-rcv.md) + +[OID\_GEN\_MULTICAST\_BYTES\_RCV](oid-gen-multicast-bytes-rcv.md) + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BYTES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-bytes-xmit.md b/windows-driver-docs-pr/network/oid-gen-bytes-xmit.md new file mode 100644 index 0000000000..20115a516c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-bytes-xmit.md @@ -0,0 +1,70 @@ +--- +title: OID\_GEN\_BYTES\_XMIT +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_BYTES\_XMIT OID to determine the total bytes that a miniport adapter transmitted. +ms.assetid: 95b89a01-39e0-4e13-b960-32923e47a88d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_BYTES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_BYTES\_XMIT + + +As a query, NDIS and overlying drivers use the OID\_GEN\_BYTES\_XMIT OID to determine the total bytes that a miniport adapter transmitted. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID for miniport drivers. See the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) OID for more information about statistics. + +The total byte count is the sum of the transmit-directed byte count, transmit-multicast byte count and transmit-broadcast byte count. This value is the same as the sum of the values that are returned by the [OID\_GEN\_DIRECTED\_BYTES\_XMIT](oid-gen-directed-bytes-xmit.md), [OID\_GEN\_MULTICAST\_BYTES\_XMIT](oid-gen-multicast-bytes-xmit.md), and [OID\_GEN\_BROADCAST\_BYTES\_XMIT](oid-gen-broadcast-bytes-xmit.md) OIDs. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_BROADCAST\_BYTES\_XMIT](oid-gen-broadcast-bytes-xmit.md) + +[OID\_GEN\_DIRECTED\_BYTES\_XMIT](oid-gen-directed-bytes-xmit.md) + +[OID\_GEN\_MULTICAST\_BYTES\_XMIT](oid-gen-multicast-bytes-xmit.md) + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_BYTES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-current-lookahead.md b/windows-driver-docs-pr/network/oid-gen-current-lookahead.md new file mode 100644 index 0000000000..07d7f2d858 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-current-lookahead.md @@ -0,0 +1,77 @@ +--- +title: OID\_GEN\_CURRENT\_LOOKAHEAD +author: windows-driver-content +description: As a query, the OID\_GEN\_CURRENT\_LOOKAHEAD OID returns the number of bytes of received packet data that will be indicated to the protocol driver. +ms.assetid: ccfcb5ca-04bd-416b-91ec-690e78daeda0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_CURRENT_LOOKAHEAD Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_CURRENT\_LOOKAHEAD + + +As a query, the OID\_GEN\_CURRENT\_LOOKAHEAD OID returns the number of bytes of received packet data that will be indicated to the protocol driver. This specification does not include the header. + +As a set, the OID\_GEN\_CURRENT\_LOOKAHEAD OID specifies the number of bytes of received packet data that the miniport driver should indicate to the protocol driver. This specification does not include the header. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. (see Remarks section) + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS handles query and unsuccessful set requests for NDIS 6.0 and later miniport drivers. NDIS obtains the information from the miniport driver during initialization and miniport adapter restart. However, NDIS sends valid set requests to the miniport driver. + +For a query, NDIS returns the largest lookahead size from among all the bindings. A protocol driver can set a suggested value for the number of bytes to be used in its binding; however, the underlying miniport driver is never required to limit its indications to the value set. + +If the underlying driver supports multipacket receive indications, bound protocol drivers are given full net packets on every indication. Consequently, this value is identical to that returned for [OID\_GEN\_RECEIVE\_BLOCK\_SIZE](oid-gen-receive-block-size.md). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_RECEIVE\_BLOCK\_SIZE](oid-gen-receive-block-size.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_CURRENT_LOOKAHEAD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-current-packet-filter.md b/windows-driver-docs-pr/network/oid-gen-current-packet-filter.md new file mode 100644 index 0000000000..01d60467a9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-current-packet-filter.md @@ -0,0 +1,217 @@ +--- +title: OID\_GEN\_CURRENT\_PACKET\_FILTER +author: windows-driver-content +description: As a query, the OID\_GEN\_CURRENT\_PACKET\_FILTER OID reports the types of net packets that are in receive indications from a miniport driver. +ms.assetid: d5a32626-caff-4708-a134-d80a845dee91 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_CURRENT_PACKET_FILTER Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_CURRENT\_PACKET\_FILTER + + +As a query, the OID\_GEN\_CURRENT\_PACKET\_FILTER OID reports the types of net packets that are in receive indications from a miniport driver. + +As a set, the OID\_GEN\_CURRENT\_PACKET\_FILTER OID specifies the types of net packets for which a protocol receives indications from a miniport driver. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. (see Remarks section) + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +For NDIS 6.0 and later miniport drivers, the query is not requested and the set is mandatory. NDIS handles the query for miniport drivers. The miniport driver reports the packet filter information during initialization. + +The miniport driver reports its medium type as one for which the system provides a filter library. The packet filter uses the OR operation to inclusively combine the following types: + +NDIS\_PACKET\_TYPE\_DIRECTED +Directed packets. Directed packets contain a destination address equal to the station address of the NIC. + +NDIS\_PACKET\_TYPE\_MULTICAST +Multicast address packets sent to addresses in the multicast address list. + +A protocol driver can receive Ethernet (802.3) multicast packets by specifying the multicast or functional address packet type. Setting the multicast address list or functional address determines which multicast address groups the NIC driver enables. + +NDIS\_PACKET\_TYPE\_ALL\_MULTICAST +All multicast address packets, not just the ones enumerated in the multicast address list. + +NDIS\_PACKET\_TYPE\_BROADCAST +Broadcast packets. + +NDIS\_PACKET\_TYPE\_PROMISCUOUS +Specifies all packets regardless of whether VLAN filtering is enabled or not and whether the VLAN identifier matches or not. + +NDIS\_PACKET\_TYPE\_ALL\_FUNCTIONAL +All functional address packets, not just the ones in the current functional address. + +NDIS\_PACKET\_TYPE\_ALL\_LOCAL +All packets sent by installed protocols and all packets indicated by the NIC that is identified by a given *NdisBindingHandle* . + +NDIS\_PACKET\_TYPE\_FUNCTIONAL +Functional address packets sent to addresses included in the current functional address. + +NDIS\_PACKET\_TYPE\_GROUP +Packets sent to the current group address. + +NDIS\_PACKET\_TYPE\_MAC\_FRAME +NIC driver frames that a Token Ring NIC receives. + +NDIS\_PACKET\_TYPE\_SMT +SMT packets that an FDDI NIC receives. + +NDIS\_PACKET\_TYPE\_SOURCE\_ROUTING +All source routing packets. If the protocol driver sets this bit, the NDIS library attempts to act as a source routing bridge. + +For miniport adapters whose media type is **NdisMedium802\_3** or **NdisMedium802\_5**, NDIS disables packet reception, along with multicast and functional addresses during a call to the [**NdisOpenAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff563715) function. + +For miniport adapters with all other media types, the protocol driver can begin receiving packets at any time during the [**NdisOpenAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff563715) call. Note that the protocol can even receive packets before **NdisOpenAdapterEx** returns. In general, packet filtering is best effort, and protocol drivers must be prepared to handle receive indications even when the packet filter is zero. + +For a query, NDIS returns the binding filters that are combined using the OR operator. + +For a set, the specified packet filter replaces the previous packet filter for the binding. If the miniport driver previously enabled a packet type but the protocol driver does not specify that type in a new filter, the protocol driver will not receive packets of this type. + +For miniport adapters whose media type is **NdisMedium802\_3** or **NdisMedium802\_5**, if the miniport driver does not set a bit for a particular packet type in response to this query, the protocol driver will not receive packets of that type. Consequently, a protocol driver can disable packet reception by calling the [**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) or [**NdisCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561711) function using a filter of zero. + +For miniport adapters with all other media types, NDIS does not check the packet type. For these media types, a protocol driver cannot disable packet reception by specifying a filter of zero. + +When a miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called, the miniport driver's packet filter should be set to zero. When the packet filter is zero, receive indications are disabled. After a miniport driver's *MiniportInitializeEx* function has returned, a protocol driver can set OID\_GEN\_CURRENT\_PACKET\_FILTER to a nonzero value, thereby enabling the miniport driver to indicate received packets to that protocol. + +If promiscuous mode is enabled with the NDIS\_PACKET\_TYPE\_PROMISCUOUS bit, the protocol driver continues to receive packets even if the sending network node does not direct them to it. NDIS then sends the protocol driver all packets the NIC receives. + +Setting a specific packet filter does not alter the packet filter for other protocol drivers that are bound to (or above) the same NIC. For example, if one bound protocol enables promiscuous mode, other bound protocol drivers do not receive packets that they have not specifically requested with their own packet filters. + +**Native 802.11 Packet Filters** + +The Native 802.11 miniport driver must only support the following standard packet filter types: + +- NDIS\_PACKET\_TYPE\_DIRECTED + +- NDIS\_PACKET\_TYPE\_MULTICAST + +- NDIS\_PACKET\_TYPE\_BROADCAST + +- NDIS\_PACKET\_TYPE\_PROMISCUOUS + +When enabled, these standard packet filters are only applicable to 802.11 data packets. + +In addition, the Native 802.11 miniport driver must support the following packet filter types, which are specific to the Native 802.11 media: + +NDIS\_PACKET\_TYPE\_802\_11\_RAW\_DATA +An 802.11 media access control (MAC) protocol data unit (MPDU) frame, which contains all of the data in the format received by the 802.11 station. When this filter is set, the driver must indicate every unmodified MPDU fragment before it indicates the MAC service data unit (MSDU) packet reassembled from the MPDU fragments. + +If an MPDU fragment is encrypted, it must not decrypt the fragment before it is indicated. However, the miniport driver must decrypt each MPDU fragment before reassembling and indicating the MSDU packet. + +If enabled, this filter type only affects other standard packet filters, such as NDIS\_PACKET\_TYPE\_DIRECTED or NDIS\_PACKET\_TYPE\_BROADCAST. + +For more information about the method for indicating raw 802.11 data packets, see [Indicating Raw 802.11 Packets](https://msdn.microsoft.com/library/windows/hardware/ff554833). + +NDIS\_PACKET\_TYPE\_802\_11\_DIRECTED\_MGMT +Directed 802.11 management packets. Directed packets contain a destination address equal to the station address of the NIC. + +NDIS\_PACKET\_TYPE\_802\_11\_MULTICAST\_MGMT +Multicast 802.11 management packets sent to addresses in the multicast address list. + +NDIS\_PACKET\_TYPE\_802\_11\_ALL\_MULTICAST\_MGMT +All multicast 802.11 management packets received by the 802.11 station, regardless of whether the destination address in the 802.11 MAC header is in the multicast address list. + +NDIS\_PACKET\_TYPE\_802\_11\_BROADCAST\_MGMT +Broadcast 802.11 management packets received by the 802.11 station. + +NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_MGMT +All 802.11 management packets received by the 802.11 station. + +NDIS\_PACKET\_TYPE\_802\_11\_RAW\_MGMT +An 802.11 MPDU management frame, which contains all of the data in the format received by the 802.11 station. When this filter is set, the driver must indicate every unmodified MPDU fragment before it indicates the MAC management protocol data unit (MMPDU) packet reassembled from the MPDU fragments. + +If enabled, this filter type only affects other 802.11 management packet filters, such as NDIS\_PACKET\_TYPE\_802\_11\_DIRECTED\_MGMT or NDIS\_PACKET\_TYPE\_802\_11\_MULTICAST\_MGMT. + +For more information about the method for indicating raw 802.11 management packets, see [Indicating Raw 802.11 Packets](https://msdn.microsoft.com/library/windows/hardware/ff554833). + +NDIS\_PACKET\_TYPE\_802\_11\_DIRECTED\_CTRL +Directed 802.11 control packets. Directed packets contain a destination address equal to the station address of the NIC. + +NDIS\_PACKET\_TYPE\_802\_11\_BROADCAST\_CTRL +Broadcast 802.11 control packets received by the 802.11 station. + +NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_CTRL +All 802.11 control packets received by the 802.11 station. + +If a miniport driver is operating in Native 802.11 Network Monitor (NetMon) or Extensible Access Point (AP) modes, the driver must enable the following packet filters through a set request of OID\_GEN\_CURRENT\_PACKET\_FILTER. + +- NDIS\_PACKET\_TYPE\_PROMISCUOUS + +- NDIS\_PACKET\_TYPE\_802\_11\_RAW\_DATA + +- NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_MGMT + +- NDIS\_PACKET\_TYPE\_802\_11\_RAW\_MGMT + +- NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_CTRL + +A miniport driver operating in other Native 802.11 modes besides NetMon must not enable these packet filter settings, with the exception of NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_CTRL. A miniport driver that is not operating in NetMon mode can optionally enable NDIS\_PACKET\_TYPE\_802\_11\_PROMISCUOUS\_CTRL through a set request of OID\_GEN\_CURRENT\_PACKET\_FILTER. + +**Note**  When the miniport driver is in Native 802.11 modes other than NetMon, and OID\_GEN\_CURRENT\_PACKET\_FILTER is set, the driver must not fail the set request if any promiscuous or raw filter settings are enabled in the OID data. + +  + +For more information about the NetMon and ExtAP operating modes, see the following topics: + +[Network Monitor Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff568369) + +[Extensible Access Point Operation Mode](https://msdn.microsoft.com/library/windows/hardware/ff549858) + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NdisCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561711) + +[**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) + +[**NdisOpenAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff563715) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_CURRENT_PACKET_FILTER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-device-profile.md b/windows-driver-docs-pr/network/oid-gen-device-profile.md new file mode 100644 index 0000000000..5fc1e51a46 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-device-profile.md @@ -0,0 +1,48 @@ +--- +title: OID\_GEN\_DEVICE\_PROFILE +author: windows-driver-content +description: The OID\_GEN\_DEVICE\_PROFILE OID is obsolete. NDIS and NDIS drivers do not use this OID. +ms.assetid: 0c95bbce-235a-4827-b935-137b9ee983b6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DEVICE_PROFILE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DEVICE\_PROFILE + + +The OID\_GEN\_DEVICE\_PROFILE OID is obsolete. NDIS and NDIS drivers do not use this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DEVICE_PROFILE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-directed-bytes-rcv.md b/windows-driver-docs-pr/network/oid-gen-directed-bytes-rcv.md new file mode 100644 index 0000000000..f8457cb7b9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-directed-bytes-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_DIRECTED\_BYTES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_DIRECTED\_BYTES\_RCV OID specifies the number of bytes in directed packets that are received without errors. +ms.assetid: 435941b5-647f-4c5f-84ef-7b4b832c452e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DIRECTED_BYTES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DIRECTED\_BYTES\_RCV + + +As a query, the OID\_GEN\_DIRECTED\_BYTES\_RCV OID specifies the number of bytes in directed packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DIRECTED_BYTES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-directed-bytes-xmit.md b/windows-driver-docs-pr/network/oid-gen-directed-bytes-xmit.md new file mode 100644 index 0000000000..4ed9f3c54e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-directed-bytes-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_DIRECTED\_BYTES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_DIRECTED\_BYTES\_XMIT OID specifies the number of bytes in directed packets that are transmitted without errors. +ms.assetid: 645215fb-457e-43cd-b45e-e34f313af46e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DIRECTED_BYTES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DIRECTED\_BYTES\_XMIT + + +As a query, the OID\_GEN\_DIRECTED\_BYTES\_XMIT OID specifies the number of bytes in directed packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DIRECTED_BYTES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-directed-frames-rcv.md b/windows-driver-docs-pr/network/oid-gen-directed-frames-rcv.md new file mode 100644 index 0000000000..e5490651b3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-directed-frames-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_DIRECTED\_FRAMES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_DIRECTED\_FRAMES\_RCV OID specifies the number of directed packets that are received without errors. +ms.assetid: 6f8b84d3-19d6-4a2a-a2eb-8961614fbba4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DIRECTED_FRAMES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DIRECTED\_FRAMES\_RCV + + +As a query, the OID\_GEN\_DIRECTED\_FRAMES\_RCV OID specifies the number of directed packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DIRECTED_FRAMES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-directed-frames-xmit.md b/windows-driver-docs-pr/network/oid-gen-directed-frames-xmit.md new file mode 100644 index 0000000000..697a934708 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-directed-frames-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_DIRECTED\_FRAMES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_DIRECTED\_FRAMES\_XMIT OID specifies the number of directed packets that are transmitted without errors. +ms.assetid: 7863c5c5-618f-4e3c-9a50-3bfdcf00034d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DIRECTED_FRAMES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DIRECTED\_FRAMES\_XMIT + + +As a query, the OID\_GEN\_DIRECTED\_FRAMES\_XMIT OID specifies the number of directed packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DIRECTED_FRAMES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-discontinuity-time.md b/windows-driver-docs-pr/network/oid-gen-discontinuity-time.md new file mode 100644 index 0000000000..6c45c6f050 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-discontinuity-time.md @@ -0,0 +1,68 @@ +--- +title: OID\_GEN\_DISCONTINUITY\_TIME +author: windows-driver-content +description: As a query, use the OID\_GEN\_DISCONTINUITY\_TIME OID to determine the discontinuity time of a network interface (ifCounterDiscontinuityTime from RFC 2863). +ms.assetid: 3eac6818-c346-47f6-b812-f98b808dc36a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DISCONTINUITY_TIME Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DISCONTINUITY\_TIME + + +As a query, use the OID\_GEN\_DISCONTINUITY\_TIME OID to determine the discontinuity time of a network interface (*ifCounterDiscontinuityTime* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +This OID returns the time, starting from the last computer restart, when the interface had a discontinuity in maintaining the statistics counters. For example, there was a discontinuity because the interface was disabled or the associated adapter was removed from the computer. For more information about the statistics counters, see [OID\_GEN\_STATISTICS](oid-gen-statistics.md). To get the current time, an interface provider can call the [**NdisGetSystemUpTimeEx**](https://msdn.microsoft.com/library/windows/hardware/ff562675) function. + +If no such discontinuity occurred since the last re-initialization of the interface this value should be zero. If the interface provider does not track discontinuity time, this value should be zero. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is a ULONG64 value that specifies the discontinuity time, in milliseconds, since the last computer restart. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DISCONTINUITY_TIME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-driver-version.md b/windows-driver-docs-pr/network/oid-gen-driver-version.md new file mode 100644 index 0000000000..fcc1a2e705 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-driver-version.md @@ -0,0 +1,68 @@ +--- +title: OID\_GEN\_DRIVER\_VERSION +author: windows-driver-content +description: As a query, the OID\_GEN\_DRIVER\_VERSION OID specifies the NDIS version in use by the miniport driver. +ms.assetid: 8c3ac2ab-a83a-44d2-88bc-bd1468a0a59b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_DRIVER_VERSION Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_DRIVER\_VERSION + + +As a query, the OID\_GEN\_DRIVER\_VERSION OID specifies the NDIS version in use by the miniport driver. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS handles this OID for NDIS 6.0 and later miniport drivers. + +The high byte is the major version number; the low byte is the minor version number. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_DRIVER_VERSION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-enumerate-ports.md b/windows-driver-docs-pr/network/oid-gen-enumerate-ports.md new file mode 100644 index 0000000000..a5b8562d17 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-enumerate-ports.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_ENUMERATE\_PORTS +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_ENUMERATE\_PORTS OID to determine the characteristics of the active NDIS ports that are associated with an underlying miniport adapter. +ms.assetid: 42a12a05-e360-4493-b037-d3a63906a132 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_ENUMERATE_PORTS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_ENUMERATE\_PORTS + + +As a query, NDIS and overlying drivers use the OID\_GEN\_ENUMERATE\_PORTS OID to determine the characteristics of the active NDIS ports that are associated with an underlying miniport adapter. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID and miniport drivers do not receive this OID query. + +If the query succeeds, NDIS returns NDIS\_STATUS\_SUCCESS and provides the results of the query in an [**NDIS\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff566786) structure. The **NumberOfPorts** member of NDIS\_PORT\_ARRAY contains the number of active ports that are associated with the miniport adapter. The **Ports** member of NDIS\_PORT\_ARRAY contains a list of pointers to [**NDIS\_PORT\_CHARACTERISTICS**](https://msdn.microsoft.com/library/windows/hardware/ff566791) structures. Each NDIS\_PORT\_CHARACTERISTICS structure defines the characteristics of a single NDIDS port. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff566786) + +[**NDIS\_PORT\_CHARACTERISTICS**](https://msdn.microsoft.com/library/windows/hardware/ff566791) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_ENUMERATE_PORTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-friendly-name.md b/windows-driver-docs-pr/network/oid-gen-friendly-name.md new file mode 100644 index 0000000000..a41b39cca4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-friendly-name.md @@ -0,0 +1,55 @@ +--- +title: OID\_GEN\_FRIENDLY\_NAME +author: windows-driver-content +description: As a query, the OID\_GEN\_FRIENDLY\_NAME OID returns the friendly name of a miniport adapter. +ms.assetid: 003e729c-32e3-45a8-be3a-5dfafc49863e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_FRIENDLY_NAME Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_FRIENDLY\_NAME + + +As a query, the OID\_GEN\_FRIENDLY\_NAME OID returns the friendly name of a miniport adapter. + +Remarks +------- + +The OID\_GEN\_FRIENDLY\_NAME OID returns the friendly name of a miniport adapter. + +Friendly names are intended to help the user quickly and accurately identify a miniport adapter--for example, "PCI Ethernet Adapter" and "Virtual Private Networking Adapter" are considered friendly names. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1 and later drivers in Windows Vista and later versions of Windows and later versions of Windows. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_FRIENDLY_NAME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-hardware-status.md b/windows-driver-docs-pr/network/oid-gen-hardware-status.md new file mode 100644 index 0000000000..2c31fcfe8c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-hardware-status.md @@ -0,0 +1,81 @@ +--- +title: OID\_GEN\_HARDWARE\_STATUS +author: windows-driver-content +description: As a query, the OID\_GEN\_HARDWARE\_STATUS OID specifies the current hardware status of the underlying NIC. +ms.assetid: beab6f7a-b064-446f-8008-ef8db9d7c080 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_HARDWARE_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_HARDWARE\_STATUS + + +As a query, the OID\_GEN\_HARDWARE\_STATUS OID specifies the current hardware status of the underlying NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Obsolete. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The OID\_GEN\_HARDWARE\_STATUS OID specifies the current hardware status of the underlying NIC as one of the following NDIS\_HARDWARE\_STATUS-type values: + +**NdisHardwareStatusReady** +Available and capable of sending and receiving data over the wire + +**NdisHardwareStatusInitializing** +Initializing + +**NdisHardwareStatusReset** +Resetting + +**NdisHardwareStatusClosing** +Closing + +**NdisHardwareStatusNotReady** +Not ready + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_HARDWARE_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-hd-split-current-config.md b/windows-driver-docs-pr/network/oid-gen-hd-split-current-config.md new file mode 100644 index 0000000000..9d1a5c1624 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-hd-split-current-config.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_HD\_SPLIT\_CURRENT\_CONFIG +author: windows-driver-content +description: As a query, overlying drivers or administrative utilities can use the OID\_GEN\_HD\_SPLIT\_CURRENT\_CONFIG OID to determine the current header-data split configuration of a miniport adapter. +ms.assetid: fc363227-1040-45bc-8c76-2ac61606d777 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_HD_SPLIT_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_HD\_SPLIT\_CURRENT\_CONFIG + + +As a query, overlying drivers or administrative utilities can use the OID\_GEN\_HD\_SPLIT\_CURRENT\_CONFIG OID to determine the current header-data split configuration of a miniport adapter. A system administrator can use the GUID that is associated with this OID through the WMI interface. + +Remarks +------- + +NDIS handles this OID on behalf of the miniport driver. NDIS maintains the current header-data split configuration information based on the miniport driver initialization attributes and the [**NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff567370) status indication. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains an [**NDIS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff565696) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff565696) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_STATUS\_HD\_SPLIT\_CURRENT\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/ff567370) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_HD_SPLIT_CURRENT_CONFIG%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-hd-split-parameters.md b/windows-driver-docs-pr/network/oid-gen-hd-split-parameters.md new file mode 100644 index 0000000000..2754182cca --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-hd-split-parameters.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_HD\_SPLIT\_PARAMETERS +author: windows-driver-content +description: As a set, NDIS and overlying drivers or user-mode applications use the OID\_GEN\_HD\_SPLIT\_PARAMETERS OID to set the current header-data split settings of a miniport adapter. +ms.assetid: 1b33c601-4302-4f63-8265-b75889b42d42 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_HD_SPLIT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_HD\_SPLIT\_PARAMETERS + + +As a set, NDIS and overlying drivers or user-mode applications use the OID\_GEN\_HD\_SPLIT\_PARAMETERS OID to set the current header-data split settings of a miniport adapter. NDIS 6.1 and later miniport drivers that provide header-data split services must support this OID. Otherwise, this OID is optional. + +Remarks +------- + +The **InformationBuffer** member of [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains an [**NDIS\_HD\_SPLIT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565701) structure. + +NDIS might set the OID\_GEN\_HD\_SPLIT\_PARAMETERS OID when an NDIS 5.*x* protocol driver binds to an NDIS 6.1 miniport. NDIS processes this OID before passing it to the miniport driver and updates the miniport adapter's **\*HeaderDataSplit** standardized keyword, if required. If header-data split is disabled, NDIS does not send this OID to the miniport adapter. + +NDIS will send this OID to the miniport driver only if header-data split was enabled with the NDIS\_HD\_SPLIT\_ENABLE\_HEADER\_DATA\_SPLIT flag in the [**NDIS\_HD\_SPLIT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565694) structure during miniport initialization. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_HD\_SPLIT\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565694) + +[**NDIS\_HD\_SPLIT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565701) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_HD_SPLIT_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-init-time-ms.md b/windows-driver-docs-pr/network/oid-gen-init-time-ms.md new file mode 100644 index 0000000000..eaab4f7f20 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-init-time-ms.md @@ -0,0 +1,53 @@ +--- +title: OID\_GEN\_INIT\_TIME\_MS +author: windows-driver-content +description: As a query, the OID\_GEN\_INIT\_TIME\_MS OID returns the time in milliseconds that a driver required to initialize. +ms.assetid: 044e7a4f-b4d5-4a47-81c0-571fdd2ae5bb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_INIT_TIME_MS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_INIT\_TIME\_MS + + +As a query, the OID\_GEN\_INIT\_TIME\_MS OID returns the time in milliseconds that a driver required to initialize. + +Remarks +------- + +The OID\_GEN\_INIT\_TIME\_MS OID returns the time in milliseconds that a driver required to initialize. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1 and later drivers in Windows Vista and later versions of Windows and later versions of Windows. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_INIT_TIME_MS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-interface-info.md b/windows-driver-docs-pr/network/oid-gen-interface-info.md new file mode 100644 index 0000000000..bba00c2556 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-interface-info.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_INTERFACE\_INFO +author: windows-driver-content +description: As a query, use the OID\_GEN\_INTERFACE\_INFO OID to obtain the current state and statistics information for a network interface. +ms.assetid: fa1dd52f-7cf6-4e95-af15-02ae65fcb872 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_INTERFACE_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_INTERFACE\_INFO + + +As a query, use the OID\_GEN\_INTERFACE\_INFO OID to obtain the current state and statistics information for a network interface. + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the query succeeds, the interface provider returns NDIS\_STATUS\_SUCCESS, and the result of the query is an [**NDIS\_INTERFACE\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff565736) structure. This structure contains information that changes during the lifetime of the interface. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_INTERFACE\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/ff565736) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_INTERFACE_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-interrupt-moderation.md b/windows-driver-docs-pr/network/oid-gen-interrupt-moderation.md new file mode 100644 index 0000000000..1915ce8473 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-interrupt-moderation.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_INTERRUPT\_MODERATION +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_INTERRUPT\_MODERATION OID to determine if interrupt moderation is enabled on a miniport adapter. +ms.assetid: 4d9d2bda-f0b3-42d5-bb49-93a9b256f5ad +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_INTERRUPT_MODERATION Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_INTERRUPT\_MODERATION + + +As a query, NDIS and overlying drivers use the OID\_GEN\_INTERRUPT\_MODERATION OID to determine if interrupt moderation is enabled on a miniport adapter. If the query succeeds, NDIS returns an [**NDIS\_INTERRUPT\_MODERATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565793) structure that contains the current interrupt moderation settings. + +As a set, NDIS and overlying drivers use the OID\_GEN\_INTERRUPT\_MODERATION OID to enable or disable the interrupt moderation on a miniport adapter. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. Set and query. + +Remarks +------- + +For a query, if a miniport driver does not support interrupt moderation, the driver must specify **NdisInterruptModerationNotSupported** in the **InterruptModeration** member of the NDIS\_INTERRUPT\_MODERATION\_PARAMETERS structure. + +For a set, if the driver reported **NdisInterruptModerationNotSupported** in response to the OID\_GEN\_INTERRUPT\_MODERATION query, the driver should return NDIS\_STATUS\_INVALID\_DATA in response to the set request. The miniport driver receives an [**NDIS\_INTERRUPT\_MODERATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565793) structure. If the **InterruptModeration** member of NDIS\_INTERRUPT\_MODERATION\_PARAMETERS is set to **NdisInterruptModerationEnabled**, the miniport driver should enable interrupt moderation. Otherwise, it should disable interrupt moderation. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_INTERRUPT\_MODERATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565793) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_INTERRUPT_MODERATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-isolation-parameters.md b/windows-driver-docs-pr/network/oid-gen-isolation-parameters.md new file mode 100644 index 0000000000..8f6c980e73 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-isolation-parameters.md @@ -0,0 +1,116 @@ +--- +title: OID\_GEN\_ISOLATION\_PARAMETERS +author: windows-driver-content +description: NDIS and overlying drivers issue an object identifier (OID) request of OID\_GEN\_ISOLATION\_PARAMETERS to obtain the multi-tenancy configuration (isolation) parameters that are set on a VM network adapter's port. +ms.assetid: 68E89349-4907-4241-9C50-B13C75273F0D +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_ISOLATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_ISOLATION\_PARAMETERS + + +NDIS and overlying drivers issue an object identifier (OID) request of OID\_GEN\_ISOLATION\_PARAMETERS to obtain the multi-tenancy configuration (isolation) parameters that are set on a VM network adapter's port. + +Although each routing domain is configured separately on the port, this OID returns parameters for all of the routing domains in a single query. + +An overlying driver should issue this OID in two steps: + +1. Io query the required buffer size, issue the OID query with the **Size** member of the **Header** member of the [**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) structure set to **NDIS\_SIZEOF\_NDIS\_ISOLATION\_PARAMETERS\_REVISION\_1**. (See **NDIS\_STATUS\_INVALID\_LENGTH** below.) +2. Issue the OID with an **InformationBuffer** of the required size. + +If the OID query request is completed successfully, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data, in order: + +1. An [**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) structure + +2. One or more [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) structures, one for each routing domain + +3. One or more [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) structures, grouped by routing domain + +In each [**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) structure, the **FirstIsolationInfoEntryOffset** member contains the offset from the beginning of the OID information buffer (that is, the beginning of the buffer that the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure points to) to the first [**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) for that routing domain. The offset in the **NextIsolationInfoEntryOffset** member of the last structure in the list is zero. + +If no multi-tenancy configuration parameters are set on the VM network adapter, the network adapter miniport driver sets the **DATA.QUERY\_INFORMATION.BytesWritten** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to zero and returns **NDIS\_STATUS\_SUCCESS**. In this case, the data within the **DATA.QUERY\_INFORMATION.InformationBuffer** member is not modified by the miniport driver. + +Remarks +------- + +### Return Status Codes + +The VM network adapter miniport driver returns one of the following status codes for this OID request: + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the requested information. The VM network adapter miniport driver sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size, in bytes, that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.40 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_ISOLATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn383679) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_ROUTING\_DOMAIN\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383681) + +[**NDIS\_ROUTING\_DOMAIN\_ISOLATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn383684) + +[**NDIS\_STATUS\_ISOLATION\_PARAMETERS\_CHANGE**](ndis-status-isolation-parameters-change.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_ISOLATION_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-last-change.md b/windows-driver-docs-pr/network/oid-gen-last-change.md new file mode 100644 index 0000000000..0c0ca40f58 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-last-change.md @@ -0,0 +1,74 @@ +--- +title: OID\_GEN\_LAST\_CHANGE +author: windows-driver-content +description: As a query, use the OID\_GEN\_LAST\_CHANGE OID to determine the time of the last operational state change of a network interface (ifLastChange from RFC 2863). +ms.assetid: bd96d1ec-2fd0-491f-acb4-c1594ce6a084 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_LAST_CHANGE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_LAST\_CHANGE + + +As a query, use the OID\_GEN\_LAST\_CHANGE OID to determine the time of the last operational state change of a network interface (*ifLastChange* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +This OID returns the time, starting from the last computer restart, when the interface entered its current operational state. For more information about the operational state, see [**NDIS\_STATUS\_OPER\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567406) and [OID\_GEN\_OPERATIONAL\_STATUS](oid-gen-operational-status.md). To get the current time, an interface provider can call the [**NdisGetSystemUpTimeEx**](https://msdn.microsoft.com/library/windows/hardware/ff562675) function. + +If the current operational state was entered before the last reinitialization of the interface, this value should be zero. . If the interface provider does not track operational state change time, the value should be zero. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is a ULONG64 value that specifies the state change time, in milliseconds, since the last computer restart. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_OPERATIONAL\_STATUS](oid-gen-operational-status.md) + +[**NDIS\_STATUS\_OPER\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff567406) + +[**NdisGetSystemUpTimeEx**](https://msdn.microsoft.com/library/windows/hardware/ff562675) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_LAST_CHANGE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-link-parameters.md b/windows-driver-docs-pr/network/oid-gen-link-parameters.md new file mode 100644 index 0000000000..0008b3ec19 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-link-parameters.md @@ -0,0 +1,131 @@ +--- +title: OID\_GEN\_LINK\_PARAMETERS +author: windows-driver-content +description: As a set, NDIS and overlying drivers use the OID\_GEN\_LINK\_PARAMETERS OID to set the current link state of a miniport adapter. The miniport driver receives the duplex state, link speeds, and pause functions in an NDIS\_LINK\_PARAMETERS structure. +ms.assetid: 6a8ee5b1-ac68-424f-b749-45b085ca1d75 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_LINK_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_LINK\_PARAMETERS + + +As a set, NDIS and overlying drivers use the OID\_GEN\_LINK\_PARAMETERS OID to set the current link state of a miniport adapter. The miniport driver receives the duplex state, link speeds, and pause functions in an NDIS\_LINK\_PARAMETERS structure. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +The NDIS\_LINK\_PARAMETERS structure is defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_LINK_PARAMETERS { + NDIS_OBJECT_HEADER Header; + NDIS_MEDIA_DUPLEX_STATE MediaDuplexState; + ULONG64 XmitLinkSpeed; + ULONG64 RcvLinkSpeed; + NDIS_SUPPORTED_PAUSE_FUNCTIONS PauseFunctions; + ULONG AutoNegotiationFlags; + } NDIS_LINK_PARAMETERS, *PNDIS_LINK_PARAMETERS; + +``` + +## + + +This structure contains the following members: + +**Header** +The [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure for the NDIS\_LINK\_PARAMETERS structure. Set the **Type** member of the structure that **Header** specifies to NDIS\_OBJECT\_TYPE\_DEFAULT, the **Revision** member to NDIS\_LINK\_PARAMETERS\_REVISION\_1, and the **Size** member to NDIS\_SIZEOF\_LINK\_PARAMETERS\_REVISION\_1. + +**MediaDuplexState** +The media duplex state. This value is the same as the value that is returned by the [OID\_GEN\_MEDIA\_DUPLEX\_STATE](oid-gen-media-duplex-state.md) OID. + +**XmitLinkSpeed** +The transmit link speed in bits per second. + +**RcvLinkSpeed** +The receive link speed in bits per second. + +**PauseFunctions** +The type of support for the IEEE 802.3 pause frames. This member must be one of the following pause functions: + +**NdisPauseFunctionsUnsupported** +The adapter or link partner does not support pause frames. + +**NdisPauseFunctionsSendOnly** +The adapter and link partner support only sending pause frames from the adapter to the link partner. + +**NdisPauseFunctionsReceiveOnly** +The adapter and link partner support only sending pause frames from the link partner to the adapter + +**NdisPauseFunctionsSendAndReceive** +The adapter and link partner support sending and receiving pause frames in both transmit and receive directions. + +**AutoNegotiationFlags** +The auto-negotiation settings for the miniport adapter. This member is created from a bitwise OR of the following flags: + +NDIS\_LINK\_STATE\_XMIT\_LINK\_SPEED\_AUTO\_NEGOTIATED +The adapter should auto-negotiate the transmit link speed with the link partner. If this flag is not set, the miniport driver should set the transmit link speed to the value that is specified in the **XmitLinkSpeed** member. + +NDIS\_LINK\_STATE\_RCV\_LINK\_SPEED\_AUTO\_NEGOTIATED +The adapter should auto-negotiate the receive link speed with the link partner. If this flag is not set, the miniport driver should set the receive link speed to the value that is specified in the **RcvLinkSpeed** member. + +NDIS\_LINK\_STATE\_DUPLEX\_AUTO\_NEGOTIATED +The adapter should auto-negotiate the duplex state with the link partner. If this flag is not set, the miniport driver should set the duplex state to the value that is specified in the **MediaDuplexState** member. + +NDIS\_LINK\_STATE\_PAUSE\_FUNCTIONS\_AUTO\_NEGOTIATED +The miniport driver should auto-negotiate the support for pause frames with the other end. If this flag is not set, the miniport driver should use the pause frame support that is specified in the **PauseFunctions** member. + +Remarks +------- + +**Note**  Setting OID\_GEN\_LINK\_PARAMETERS can cause a loss of connectivity. Miniport drivers must reconfigure the miniport adapter when this OID is set. For example, the miniport driver can reset the miniport adapter with the resulting loss of existing connections. The specific mechanism for reconfiguration is application dependent. + +  + +If the link state of the miniport adapter changes because of the OID\_GEN\_LINK\_PARAMETERS set request, the miniport driver should generate an [**NDIS\_STATUS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567391) status indication to notify NDIS and overlying drivers of the new link state. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) + +[**NDIS\_STATUS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567391) + +[OID\_GEN\_MEDIA\_DUPLEX\_STATE](oid-gen-media-duplex-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_LINK_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-link-speed-ex.md b/windows-driver-docs-pr/network/oid-gen-link-speed-ex.md new file mode 100644 index 0000000000..ee9e278062 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-link-speed-ex.md @@ -0,0 +1,74 @@ +--- +title: OID\_GEN\_LINK\_SPEED\_EX +author: windows-driver-content +description: As a query, the OID\_GEN\_LINK\_SPEED\_EX OID provides the transmit and receive link speeds of an interface. Version Information Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: 86cc281b-3898-484c-9418-4408a45ebe71 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_LINK_SPEED_EX Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_LINK\_SPEED\_EX + + +As a query, the OID\_GEN\_LINK\_SPEED\_EX OID provides the transmit and receive link speeds of an interface. + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +NDIS uses this OID to query the link speed of an [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) provider. Only NDIS interface providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +This OID returns the link speeds in an [**NDIS\_LINK\_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff565864) structure. + +Miniport drivers supply the link speed during initialization and provide updated link speeds with status indications. + +To specify the link speeds in a miniport driver, set the **XmitLinkSpeed** and **RcvLinkSpeed** members of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that the miniport driver passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_LINK\_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff565864) + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_LINK_SPEED_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-link-speed.md b/windows-driver-docs-pr/network/oid-gen-link-speed.md new file mode 100644 index 0000000000..a13cb5f7dd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-link-speed.md @@ -0,0 +1,75 @@ +--- +title: OID\_GEN\_LINK\_SPEED +author: windows-driver-content +description: As a query, the OID\_GEN\_LINK\_SPEED OID specifies the maximum speed of the NIC. +ms.assetid: f8ee887a-969e-4167-9b39-9ee6ef8b1fbc +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_LINK_SPEED Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_LINK\_SPEED + + +As a query, the OID\_GEN\_LINK\_SPEED OID specifies the maximum speed of the NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later miniport drivers +Obsolete. (see Remarks section) + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The [OID\_GEN\_LINK\_STATE](oid-gen-link-state.md) is the NDIS 6.0 and later and later equivalent of this OID. However NDIS 6.0 and later miniport drivers must use the [**NDIS\_STATUS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567391) status indication instead to indicate link speed changes. + +The unit of measurement is 100 bps, so a value of 100,000 represents a hardware bit rate of 10 Mbps. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567391) + +[OID\_GEN\_LINK\_STATE](oid-gen-link-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_LINK_SPEED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-link-state.md b/windows-driver-docs-pr/network/oid-gen-link-state.md new file mode 100644 index 0000000000..667a9aef92 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-link-state.md @@ -0,0 +1,76 @@ +--- +title: OID\_GEN\_LINK\_STATE +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_LINK\_STATE OID to determine the current link state of a miniport adapter. +ms.assetid: 75a30054-8700-4b79-902c-c8382a25c0a2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_LINK_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_LINK\_STATE + + +As a query, NDIS and overlying drivers use the OID\_GEN\_LINK\_STATE OID to determine the current link state of a miniport adapter. The miniport driver receives the link state in an [**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) structure. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +Miniport drivers supply the link state during initialization and provide updates with status indications. + +To specify the link state, set the **MediaConnectState**, **MediaDuplexState**, **XmitLinkSpeed**, **RcvLinkSpeed**, **PauseFunctions**, and **AutoNegotiationFlags** members of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that the miniport driver passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +If a miniport driver does not support this OID, the driver should return NDIS\_STATUS\_NOT\_SUPPORTED. If the miniport driver supports this OID, it returns the connection state, duplex state, and link speeds in an [**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_LINK\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh205390) + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[OID\_GEN\_MEDIA\_CONNECT\_STATUS\_EX](oid-gen-media-connect-status-ex.md) + +[OID\_GEN\_MEDIA\_DUPLEX\_STATE](oid-gen-media-duplex-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_LINK_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-mac-options.md b/windows-driver-docs-pr/network/oid-gen-mac-options.md new file mode 100644 index 0000000000..ca2646f119 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-mac-options.md @@ -0,0 +1,130 @@ +--- +title: OID\_GEN\_MAC\_OPTIONS +author: windows-driver-content +description: As a query, the OID\_GEN\_MAC\_OPTIONS OID specifies a bitmask that defines optional properties of the underlying driver or a NIC. +ms.assetid: 2a093bcb-ae6f-491c-a596-03e6f47b0b86 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAC_OPTIONS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAC\_OPTIONS + + +As a query, the OID\_GEN\_MAC\_OPTIONS OID specifies a bitmask that defines optional properties of the underlying driver or a NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS handles this OID for NDIS 6.0 and later miniport drivers. + +A protocol that initiates this query can determine which of the flags the underlying driver sets, and can optionally take advantage of them. + +The following flags are currently defined: + +NDIS\_MAC\_OPTION\_COPY\_LOOKAHEAD\_DATA +The protocol driver is free to access indicated data by any means. Some fast-copy functions have trouble accessing on-board device memory. Miniport drivers that indicate data out of mapped device memory should never set this flag. If a miniport driver does set this flag, it relaxes the restriction on fast-copy functions. + +NDIS\_MAC\_OPTION\_RECEIVE\_SERIALIZED +The miniport driver indicates packets in a serial manner. That is, such a driver does not enter a new receive indication until the previous receive, if any, has been completed. + +NDIS\_MAC\_OPTION\_TRANSFERS\_NOT\_PEND +The miniport driver never completes receive indications asynchronously. + +A miniport driver that indicates receive operations with the [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) function should set this flag. + +NDIS\_MAC\_OPTION\_NO\_LOOPBACK +The NIC has no internal loopback support so NDIS will manage loopbacks on behalf of this driver. A miniport driver cannot provide its own software loopback as efficiently as NDIS, so every miniport driver should set this flag unless a NIC has hardware loopback support. WAN miniport drivers must set this flag. + +NDIS\_MAC\_OPTION\_FULL\_DUPLEX +The miniport driver supports full-duplex transmits and indications on SMP platforms. + +**Note**  This flag has been deprecated for use by NDIS 5.0 and later miniport drivers. NDIS 5.0 and later ignores this flag. + +  + +NDIS\_MAC\_OPTION\_EOTX\_INDICATION +This flag is obsolete. + +NDIS\_MAC\_OPTION\_8021P\_PRIORITY +The NIC and its driver support 802.1p packet priority. For more information, see [Packet Priority](https://msdn.microsoft.com/library/windows/hardware/ff562331). Packet-priority values are received in [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structures from higher-layer drivers. The appropriate information is generated in the MAC headers of packets and transmitted over the network. In addition, this NIC and its driver support extracting the appropriate information from the MAC headers of packets received from the network. This information is forwarded in NET\_BUFFER structures to higher-layer drivers. + +**Note**  NDIS 6.0 and later and later and later miniport drivers must set the NDIS\_MAC\_OPTION\_8021P\_PRIORITY flag. + +  + +NDIS\_MAC\_OPTION\_SUPPORTS\_MAC\_ADDRESS\_OVERWRITE +NDIS sets this flag when a miniport driver calls the [**NdisReadNetworkAddress**](https://msdn.microsoft.com/library/windows/hardware/ff564512) function. + +NDIS\_MAC\_OPTION\_RECEIVE\_AT\_DPC +This flag is obsolete. + +NDIS\_MAC\_OPTION\_8021Q\_VLAN +The miniport driver can assign and remove VLAN identifier (ID) marking in the MAC headers of packets. The driver maintains a configured VLAN ID for each NIC that the driver handles. The driver filters out incoming packets that do not belong to the VLAN to which a NIC is associated and marks outgoing packets with the VLAN ID. During the driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function for a particular NIC, the driver initially sets the NIC's VLAN ID to zero. The driver's *MiniportInitializeEx* function then reads the following configuration parameter from the registry, and, if the parameter is present, sets the NIC's VLAN ID to the parameter's value. + +``` +VlanId, REG_DWORD +``` + +NDIS\_MAC\_OPTION\_RESERVED +Reserved for NDIS internal use. + +**Note**  A miniport driver that sets the NDIS\_MAC\_OPTION\_8021Q\_VLAN flag must also set the NDIS\_MAC\_OPTION\_8021P\_PRIORITY flag. In other words, a miniport driver that supports 802.1Q must also support 802.1p. + +  + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NdisReadNetworkAddress**](https://msdn.microsoft.com/library/windows/hardware/ff564512) + +[**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAC_OPTIONS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-machine-name.md b/windows-driver-docs-pr/network/oid-gen-machine-name.md new file mode 100644 index 0000000000..78411f93c5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-machine-name.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_MACHINE\_NAME +author: windows-driver-content +description: As a set, the OID\_GEN\_MACHINE\_NAME OID indicates the local computer name to a miniport driver. +ms.assetid: 771d21ff-e989-4717-8f3e-28f4b8afe274 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MACHINE_NAME Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MACHINE\_NAME + + +As a set, the OID\_GEN\_MACHINE\_NAME OID indicates the local computer name to a miniport driver. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +The information buffer passed in this request contains an array of Unicode characters that represents the local computer name. The **InformationBufferLength** value that is supplied to the [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function specifies the length of this array in bytes, not including a NULL terminator. + +NDIS sets OID\_GEN\_MACHINE\_NAME only once after a miniport driver completes initialization. Under Windows XP, NDIS does not dynamically notify miniport drivers of a change in the computer name. After changing the computer name, a user must restart the computer so that NDIS notifies miniport drivers of the new computer name. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MACHINE_NAME%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-max-link-speed.md b/windows-driver-docs-pr/network/oid-gen-max-link-speed.md new file mode 100644 index 0000000000..bbfd7cfa4d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-max-link-speed.md @@ -0,0 +1,68 @@ +--- +title: OID\_GEN\_MAX\_LINK\_SPEED +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_MAX\_LINK\_SPEED OID to determine the maximum supported transmit and receive link speeds of a miniport adapter. +ms.assetid: 4009c5c6-57ec-47f5-80d6-d69df797857f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAX_LINK_SPEED Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAX\_LINK\_SPEED + + +As a query, NDIS and overlying drivers use the OID\_GEN\_MAX\_LINK\_SPEED OID to determine the maximum supported transmit and receive link speeds of a miniport adapter. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +The miniport driver supplies the maximum link speed during initialization. + +To specify the maximum link speeds, set the **MaxXmitLinkSpeed** and **MaxRcvLinkSpeed** members of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that the miniport driver passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. If a miniport driver does not support this OID, the driver should return NDIS\_STATUS\_NOT\_SUPPORTED. If the miniport driver supports this OID, it returns the maximum link speeds in an [**NDIS\_LINK\_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff565864) structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_LINK\_SPEED**](https://msdn.microsoft.com/library/windows/hardware/ff565864) + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAX_LINK_SPEED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-maximum-frame-size.md b/windows-driver-docs-pr/network/oid-gen-maximum-frame-size.md new file mode 100644 index 0000000000..4e0204872f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-maximum-frame-size.md @@ -0,0 +1,70 @@ +--- +title: OID\_GEN\_MAXIMUM\_FRAME\_SIZE +author: windows-driver-content +description: As a query, the OID\_GEN\_MAXIMUM\_FRAME\_SIZE OID specifies the maximum network packet size, in bytes, that the NIC supports. +ms.assetid: 4c81f3a6-6f66-466d-8d22-67841a5a8320 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAXIMUM_FRAME_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAXIMUM\_FRAME\_SIZE + + +As a query, the OID\_GEN\_MAXIMUM\_FRAME\_SIZE OID specifies the maximum network packet size, in bytes, that the NIC supports. This specification does not include a header. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not Requested. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The miniport driver supplies the maximum frame size during initialization and during a restart. NDIS handles this OID query for NDIS 6.0 and later and later and later miniport drivers. + +In response to this query from requesting transports, the miniport driver should indicate the maximum frame size that the transports can send, excluding the header. A miniport driver that emulates another medium type for binding to a transport must ensure that the maximum frame size for a protocol-supplied net packet does not exceed the size limitations for the true network medium. The same is true for a miniport driver that supports a NIC that requires inserting fields in frames. For example, to determine the maximum transfer unit (MTU), transports send this query to a NIC. + +If the miniport driver supports 802.1p packet priority and 802.1Q virtual LAN (VLAN) tags, based on prior actions, if the miniport driver expects that frames must traverse old networks before priority values are removed, that miniport driver might indicate a smaller value in response to this query. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAXIMUM_FRAME_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-maximum-lookahead.md b/windows-driver-docs-pr/network/oid-gen-maximum-lookahead.md new file mode 100644 index 0000000000..33ba5f35f7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-maximum-lookahead.md @@ -0,0 +1,75 @@ +--- +title: OID\_GEN\_MAXIMUM\_LOOKAHEAD +author: windows-driver-content +description: As a query, the OID\_GEN\_MAXIMUM\_LOOKAHEAD OID specifies the maximum number of bytes that the NIC can provide as lookahead data. +ms.assetid: 086581f7-c0a5-4355-82fe-22f53201b540 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAXIMUM_LOOKAHEAD Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAXIMUM\_LOOKAHEAD + + +As a query, the OID\_GEN\_MAXIMUM\_LOOKAHEAD OID specifies the maximum number of bytes that the NIC can provide as lookahead data. This specification does not include a header. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS 6.0 and later miniport drivers do not receive this OID request. NDIS handles this OID with a cached value that miniport drivers supply during initialization. + +Upper-layer drivers examine lookahead data to determine whether a packet that is associated with the lookahead data is intended for one or more of their clients. + +If the underlying driver supports multipacket receive indications, bound protocol drivers are given full net packets on every indication. Consequently, this value is identical to that returned for [OID\_GEN\_RECEIVE\_BLOCK\_SIZE](oid-gen-receive-block-size.md). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_RECEIVE\_BLOCK\_SIZE](oid-gen-receive-block-size.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAXIMUM_LOOKAHEAD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-maximum-send-packets.md b/windows-driver-docs-pr/network/oid-gen-maximum-send-packets.md new file mode 100644 index 0000000000..519c8c9377 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-maximum-send-packets.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_MAXIMUM\_SEND\_PACKETS +author: windows-driver-content +description: As a query, the OID\_GEN\_MAXIMUM\_SEND\_PACKETS OID specifies the maximum number of send packet descriptors that a miniport driver's MiniportSendPackets function can accept. +ms.assetid: 7e87285f-26c5-4b7d-99a8-bc0f30c643dc +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAXIMUM_SEND_PACKETS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAXIMUM\_SEND\_PACKETS + + +As a query, the OID\_GEN\_MAXIMUM\_SEND\_PACKETS OID specifies the maximum number of send packet descriptors that a miniport driver's [*MiniportSendPackets*](https://msdn.microsoft.com/library/windows/hardware/ff550524) function can accept. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later miniport drivers +Obsolete. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS ignores any value returned by a deserialized driver in response to a query of OID\_GEN\_MAXIMUM\_SEND\_PACKETS. NDIS does not adjust the size of the array of packet descriptors that it supplies to a deserialized miniport driver's *MiniportSendPackets* function. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportSendPackets*](https://msdn.microsoft.com/library/windows/hardware/ff550524) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAXIMUM_SEND_PACKETS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-maximum-total-size.md b/windows-driver-docs-pr/network/oid-gen-maximum-total-size.md new file mode 100644 index 0000000000..a59e85350a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-maximum-total-size.md @@ -0,0 +1,75 @@ +--- +title: OID\_GEN\_MAXIMUM\_TOTAL\_SIZE +author: windows-driver-content +description: As a query, the OID\_GEN\_MAXIMUM\_TOTAL\_SIZE OID specifies the maximum total packet length, in bytes, the NIC supports. +ms.assetid: 4973b4bd-58a5-4242-b33f-1ff8c3a7ec4b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MAXIMUM_TOTAL_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MAXIMUM\_TOTAL\_SIZE + + +As a query, the OID\_GEN\_MAXIMUM\_TOTAL\_SIZE OID specifies the maximum total packet length, in bytes, the NIC supports. This specification includes the header. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The returned length specifies the largest packet size for the underlying medium. Thus, the returned length depends on the particular medium. A protocol driver might use this returned length as a gauge to determine the maximum size packet that a miniport driver could forward to the protocol driver. If the protocol driver preallocates buffers, it allocates buffers accordingly. The returned length also specifies the largest packet that a protocol driver can pass to the [**NdisSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff564535) function. + +If the miniport driver for a NIC enables [802.1p packet priority](https://msdn.microsoft.com/library/windows/hardware/ff562331)(that is, the miniport driver specifies the NDIS\_MAC\_OPTION\_8021P\_PRIORITY bit in the [OID\_GEN\_MAC\_OPTIONS](oid-gen-mac-options.md) OID bitmask), then the miniport driver must specify its maximum total packet length as 4 bytes less than the maximum size of packets received or sent over the network. For example, if a NIC that has 802.1p packet priority enabled receives and sends packets on the wire that are 1514 bytes in length, the miniport driver for the NIC must report its maximum total packet length as 1510 bytes. The miniport driver must never indicate up to the bound protocol driver packets received over the network that are longer than the packet size specified by OID\_GEN\_MAXIMUM\_TOTAL\_SIZE. That is, even if the miniport driver receives packets over the network that are not marked with priority values but are still the maximum size that the underlying medium supports, the miniport driver can only indicate up packets that are no longer than the size specified by OID\_GEN\_MAXIMUM\_TOTAL\_SIZE. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisSendNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff564535) + +[OID\_GEN\_MAC\_OPTIONS](oid-gen-mac-options.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MAXIMUM_TOTAL_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-capabilities.md b/windows-driver-docs-pr/network/oid-gen-media-capabilities.md new file mode 100644 index 0000000000..89be5b1f83 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-capabilities.md @@ -0,0 +1,48 @@ +--- +title: OID\_GEN\_MEDIA\_CAPABILITIES +author: windows-driver-content +description: The OID\_GEN\_MEDIA\_CAPABILITIES OID is obsolete. NDIS and NDIS drivers do not use this OID. +ms.assetid: 5806ec46-d860-466f-b163-d7a7ad59e87a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_CAPABILITIES + + +The OID\_GEN\_MEDIA\_CAPABILITIES OID is obsolete. NDIS and NDIS drivers do not use this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Not supported.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-connect-status-ex.md b/windows-driver-docs-pr/network/oid-gen-media-connect-status-ex.md new file mode 100644 index 0000000000..b4a2dfdf63 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-connect-status-ex.md @@ -0,0 +1,72 @@ +--- +title: OID\_GEN\_MEDIA\_CONNECT\_STATUS\_EX +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_CONNECT\_STATUS\_EX OID returns the connection state of an interface. Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: 8239616c-788a-4073-8bbe-41f493a461de +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_CONNECT_STATUS_EX Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_CONNECT\_STATUS\_EX + + +As a query, the OID\_GEN\_MEDIA\_CONNECT\_STATUS\_EX OID returns the connection state of an interface. + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +NDIS uses this OID to query the connection state of an [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) provider. Only NDIS interface providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the query succeeds, the interface provider returns NDIS\_STATUS\_SUCCESS, and the result of the query can be one of the values in the [**NET\_IF\_MEDIA\_CONNECT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff568744) enumeration. + +Miniport drivers supply the media connect status during initialization and provide updates with status indications. + +To specify the connection state in a miniport driver, set the **MediaConnectState** member of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that the miniport driver passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[**NET\_IF\_MEDIA\_CONNECT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff568744) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_CONNECT_STATUS_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-connect-status.md b/windows-driver-docs-pr/network/oid-gen-media-connect-status.md new file mode 100644 index 0000000000..52c254e8bc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-connect-status.md @@ -0,0 +1,80 @@ +--- +title: OID\_GEN\_MEDIA\_CONNECT\_STATUS +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_CONNECT\_STATUS OID requests the connection status of the NIC on the network. +ms.assetid: 3ed26e62-a285-4b78-91c6-7c3cc0963570 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_CONNECT_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_CONNECT\_STATUS + + +As a query, the OID\_GEN\_MEDIA\_CONNECT\_STATUS OID requests the connection status of the NIC on the network. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS handles this OID for NDIS 6.0 and later miniport drivers. + +The OID\_GEN\_MEDIA\_CONNECT\_STATUS OID requests the connection status of the NIC on the network as one of the following system-defined values: + +**NdisMediaStateConnected** + +**NdisMediaStateDisconnected** +When a miniport driver senses that the network connection has been lost, it must also call the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) or [**NdisMCoIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563562) function with NDIS\_STATUS\_MEDIA\_DISCONNECT. When the connection is restored, it must then call **NdisM(Co)IndicateStatus** with NDIS\_STATUS\_MEDIA\_CONNECT. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMCoIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563562) + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_CONNECT_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-duplex-state.md b/windows-driver-docs-pr/network/oid-gen-media-duplex-state.md new file mode 100644 index 0000000000..139505a9e2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-duplex-state.md @@ -0,0 +1,74 @@ +--- +title: OID\_GEN\_MEDIA\_DUPLEX\_STATE +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_DUPLEX\_STATE OID returns the duplex state of an interface. Version Information Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: 63776227-dc48-4506-888f-c4b944837c4c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_DUPLEX_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_DUPLEX\_STATE + + +As a query, the OID\_GEN\_MEDIA\_DUPLEX\_STATE OID returns the duplex state of an interface. + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +NDIS uses this OID to query the duplex state of an [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) provider. Only NDIS interface providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the query succeeds, the interface provider returns NDIS\_STATUS\_SUCCESS, and the result of the query can be one of the values in the [**NET\_IF\_MEDIA\_DUPLEX\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff568745) enumeration. + +Miniport drivers supply the media duplex state during initialization and provide updates with status indications. + +To specify the duplex state in a miniport driver, set the **MediaDuplexState** member of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure that the miniport driver passes to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NET\_IF\_MEDIA\_DUPLEX\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff568745) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_DUPLEX_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-in-use.md b/windows-driver-docs-pr/network/oid-gen-media-in-use.md new file mode 100644 index 0000000000..71f6e27cdd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-in-use.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_MEDIA\_IN\_USE +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_IN\_USE OID specifies a complete list of the media types that the NIC currently uses. +ms.assetid: 3b8db63d-07e0-4a5c-9848-57e594e3dd54 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_IN_USE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_IN\_USE + + +As a query, the OID\_GEN\_MEDIA\_IN\_USE OID specifies a complete list of the media types that the NIC currently uses. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Obsolete. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +NDIS 6.0 and later miniport drivers do not receive this OID request. NDIS handles this OID with a cached value that miniport drivers supply during initialization. + +This OID provides the same information as the [OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) OID. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_IN_USE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-sense-counts.md b/windows-driver-docs-pr/network/oid-gen-media-sense-counts.md new file mode 100644 index 0000000000..dd153250db --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-sense-counts.md @@ -0,0 +1,53 @@ +--- +title: OID\_GEN\_MEDIA\_SENSE\_COUNTS +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_SENSE\_COUNTS OID returns the number of times the miniport adapter reported a media state change. +ms.assetid: 0f5c772e-4a60-492b-a578-b7ac3fed2eeb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_SENSE_COUNTS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_SENSE\_COUNTS + + +As a query, the OID\_GEN\_MEDIA\_SENSE\_COUNTS OID returns the number of times the miniport adapter reported a media state change. + +Remarks +------- + +The OID\_GEN\_MEDIA\_SENSE\_COUNTS OID returns the number of times the miniport adapter reported a media state change. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1 and later drivers in Windows Vista and later versions of Windows and later versions of Windows. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_SENSE_COUNTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-media-supported.md b/windows-driver-docs-pr/network/oid-gen-media-supported.md new file mode 100644 index 0000000000..614910eeec --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-media-supported.md @@ -0,0 +1,164 @@ +--- +title: OID\_GEN\_MEDIA\_SUPPORTED +author: windows-driver-content +description: As a query, the OID\_GEN\_MEDIA\_SUPPORTED OID specifies the media types that a NIC can support but not necessarily the media types that the NIC currently uses. +ms.assetid: e7b8d2b1-4e84-416f-aeb3-75591ed44b22 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MEDIA_SUPPORTED Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MEDIA\_SUPPORTED + + +As a query, the OID\_GEN\_MEDIA\_SUPPORTED OID specifies the media types that a NIC can support but not necessarily the media types that the NIC currently uses. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Obsolete. + +The following media types were added for NDIS 6.0 and later drivers: + +- **NdisMediumTunnel** + +- **NdisMediumLoopback** + +- **NdisMediumNative802\_11** + +The following media types were added for NDIS 6.20 and later drivers: + +- **NdisMediumIP** + +NDIS 5.1 miniport drivers +Mandatory. See [OID\_GEN\_MEDIA\_SUPPORTED (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff560254). + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. See [OID\_GEN\_MEDIA\_SUPPORTED (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff560254). + +Remarks +------- + +NDIS 6.0 and later miniport drivers do not receive this OID request. NDIS handles this OID with a cached value that miniport drivers supply during initialization. + +These media types are listed as a proper subset of the following system-defined values: + +**NdisMedium802\_3** +Ethernet (802.3). + +**Note**  NDIS 5.*x* miniport drivers that conform to the 802.11 interface must use this media type. For more information about the 802.11 interface, see [802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff543933). + +  + +**NdisMedium802\_5** +Token Ring (802.5). This media type is not supported for NDIS 6.0 and later drivers. + +**Note**  Starting with Windows 8, the operating system will not support this media type for any miniport drivers. + +  + +**NdisMediumFddi** +FDDI. This media type is not supported on Windows Vista and later versions of Windows. + +**NdisMediumWan** +WAN + +**NdisMediumLocalTalk** +LocalTalk + +**NdisMediumDix** +DEC/Intel/Xerox (DIX) Ethernet + +**NdisMediumArcnetRaw** +ARCNET (raw). This media type is not supported on Windows Vista and later versions of Windows. + +**NdisMediumArcnet878\_2** +ARCNET (878.2). This media type is not supported on Windows Vista and later versions of Windows. + +**NdisMediumAtm** +ATM. This media type is not supported for NDIS 6.0 and later drivers. + +**NdisMediumNative802\_11** +Native 802.11. This media type is used by miniport drivers that conform to the Native 802.11 interface. For more information about this interface, see [Native 802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff560648). + +**NdisMediumWirelessWan** +Various types of **NdisWireless***Xxx* media. This media type is not available for use beginning with Windows Vista and later versions of Windows. + +**NdisMediumIrda** +Infrared (IrDA). + +**NdisMediumCoWan** +Connection-oriented WAN. + +**NdisMedium1394** +IEEE 1394 (firewire) bus. This media type is not supported on Windows Vista and later versions of Windows. + +**NdisMediumBpc** +Broadcast PC network. + +**NdisMediumInfiniBand** +InfiniBand network. + +**NdisMediumTunnel** +Tunnel network. + +**NdisMediumLoopback** +NDIS loopback network. + +**NdisMediumIP** +A generic medium that is capable of sending and receiving raw IP packets. + +NDIS 5. *x* miniport drivers that support wireless LAN (WLAN) or wireless WAN (WWAN) packets appear to the operating system and to NDIS as Ethernet packets. These NDIS drivers must provide support for WWAN or WLAN networks as Ethernet networks. Such drivers declare their medium as **NdisMedium802\_3** and emulate Ethernet to higher-level NDIS drivers. Such drivers must also declare in [OID\_GEN\_PHYSICAL\_MEDIUM](oid-gen-physical-medium.md) the appropriate physical medium that they support.. + +For more information about NDIS 5.X WLAN miniport drivers, see [802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff543933). + +NDIS 6.0 and later miniport drivers that support the WLAN media transfer packets that appear to the operating system and to NDIS as IEEE 802.11 packets. These NDIS drivers must provide support for WLAN networks as Native 802.11 miniport drivers. Such drivers declare their medium as **NdisMediumNative802\_11**. + +For more information about Native 802.11 miniport drivers, see [Native 802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff560648). + +If the underlying miniport driver returns **NULL** for this query, or if an experimental media type is used, the driver must indicate receive operations using the [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) function. Any protocol that is bound to such an underlying miniport driver receives all such indications, that is, the protocol driver cannot filter receive operations with [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) + +[OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) + +[OID\_GEN\_PHYSICAL\_MEDIUM](oid-gen-physical-medium.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MEDIA_SUPPORTED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-miniport-restart-attributes.md b/windows-driver-docs-pr/network/oid-gen-miniport-restart-attributes.md new file mode 100644 index 0000000000..1747346bf3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-miniport-restart-attributes.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES +author: windows-driver-content +description: The OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES OID identifies general attributes for the propagation of miniport adapter restart attributes in an NDIS driver stack. +ms.assetid: 239993f6-2176-4925-aadc-44e0df66f56b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MINIPORT_RESTART_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES + + +The OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES OID identifies general attributes for the propagation of miniport adapter restart attributes in an NDIS driver stack. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +Remarks +------- + +The OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES OID is not used to issue OID query or set requests. + +If the **Oid** member in the [**NDIS\_RESTART\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff567255) structure is OID\_GEN\_MINIPORT\_RESTART\_ATTRIBUTES, the **Data** member of the structure contains an [**NDIS\_RESTART\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff567260) structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RESTART\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff567255) + +[**NDIS\_RESTART\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff567260) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MINIPORT_RESTART_ATTRIBUTES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-multicast-bytes-rcv.md b/windows-driver-docs-pr/network/oid-gen-multicast-bytes-rcv.md new file mode 100644 index 0000000000..db1b0f7777 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-multicast-bytes-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_MULTICAST\_BYTES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_MULTICAST\_BYTES\_RCV OID specifies the number of bytes in multicast/functional packets that are received without errors. +ms.assetid: 9c360aeb-f9b0-41d2-a6e0-feacd5419f55 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MULTICAST_BYTES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MULTICAST\_BYTES\_RCV + + +As a query, the OID\_GEN\_MULTICAST\_BYTES\_RCV OID specifies the number of bytes in multicast/functional packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MULTICAST_BYTES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-multicast-bytes-xmit.md b/windows-driver-docs-pr/network/oid-gen-multicast-bytes-xmit.md new file mode 100644 index 0000000000..8cdaf6eba3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-multicast-bytes-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_MULTICAST\_BYTES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_MULTICAST\_BYTES\_XMIT OID specifies the number of bytes in multicast/functional packets that are transmitted without errors. +ms.assetid: 4e9b5fe7-4ca6-4099-9b99-8d90a591e8ec +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MULTICAST_BYTES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MULTICAST\_BYTES\_XMIT + + +As a query, the OID\_GEN\_MULTICAST\_BYTES\_XMIT OID specifies the number of bytes in multicast/functional packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MULTICAST_BYTES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-multicast-frames-rcv.md b/windows-driver-docs-pr/network/oid-gen-multicast-frames-rcv.md new file mode 100644 index 0000000000..d6cc2d3ab9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-multicast-frames-rcv.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_MULTICAST\_FRAMES\_RCV +author: windows-driver-content +description: As a query, the OID\_GEN\_MULTICAST\_FRAMES\_RCV OID specifies the number of multicast/functional packets that are received without errors. +ms.assetid: 6001dc07-43ab-420d-b29b-1138485ce218 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MULTICAST_FRAMES_RCV Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MULTICAST\_FRAMES\_RCV + + +As a query, the OID\_GEN\_MULTICAST\_FRAMES\_RCV OID specifies the number of multicast/functional packets that are received without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MULTICAST_FRAMES_RCV%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-multicast-frames-xmit.md b/windows-driver-docs-pr/network/oid-gen-multicast-frames-xmit.md new file mode 100644 index 0000000000..5767d8b522 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-multicast-frames-xmit.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_MULTICAST\_FRAMES\_XMIT +author: windows-driver-content +description: As a query, the OID\_GEN\_MULTICAST\_FRAMES\_XMIT OID specifies the number of multicast/functional packets that are transmitted without errors. +ms.assetid: 780763a5-6220-44ad-a6e7-ed63e89baaed +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_MULTICAST_FRAMES_XMIT Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_MULTICAST\_FRAMES\_XMIT + + +As a query, the OID\_GEN\_MULTICAST\_FRAMES\_XMIT OID specifies the number of multicast/functional packets that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_MULTICAST_FRAMES_XMIT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-ndis-reserved-1.md b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-1.md new file mode 100644 index 0000000000..f65291ad41 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-1.md @@ -0,0 +1,48 @@ +--- +title: OID\_GEN\_NDIS\_RESERVED\_1 +author: windows-driver-content +description: The OID\_GEN\_NDIS\_RESERVED\_1 OID is reserved for NDIS. NDIS drivers do not use this OID. +ms.assetid: 483315ba-92a4-44da-b74a-c944cc3bf2e5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_NDIS_RESERVED_1 Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_NDIS\_RESERVED\_1 + + +The OID\_GEN\_NDIS\_RESERVED\_1 OID is reserved for NDIS. NDIS drivers do not use this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Reserved for NDIS.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_NDIS_RESERVED_1%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-ndis-reserved-2.md b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-2.md new file mode 100644 index 0000000000..f8c2392c6e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-2.md @@ -0,0 +1,48 @@ +--- +title: OID\_GEN\_NDIS\_RESERVED\_2 +author: windows-driver-content +description: The OID\_GEN\_NDIS\_RESERVED\_2 OID is reserved for NDIS. NDIS drivers do not use this OID. +ms.assetid: 1d30604b-e8e2-41aa-ac5b-8e7ba8654a2f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_NDIS_RESERVED_2 Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_NDIS\_RESERVED\_2 + + +The OID\_GEN\_NDIS\_RESERVED\_2 OID is reserved for NDIS. NDIS drivers do not use this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Reserved for NDIS.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_NDIS_RESERVED_2%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-ndis-reserved-5.md b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-5.md new file mode 100644 index 0000000000..cd14b1bdf0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-ndis-reserved-5.md @@ -0,0 +1,48 @@ +--- +title: OID\_GEN\_NDIS\_RESERVED\_5 +author: windows-driver-content +description: The OID\_GEN\_NDIS\_RESERVED\_5 OID is reserved for NDIS. NDIS drivers do not use this OID. +ms.assetid: 100e20a6-54f5-4454-baf9-d0cbe8c9c7b7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_NDIS_RESERVED_5 Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_NDIS\_RESERVED\_5 + + +The OID\_GEN\_NDIS\_RESERVED\_5 OID is reserved for NDIS. NDIS drivers do not use this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Reserved for NDIS.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_NDIS_RESERVED_5%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-network-layer-addresses.md b/windows-driver-docs-pr/network/oid-gen-network-layer-addresses.md new file mode 100644 index 0000000000..4e688bbf4d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-network-layer-addresses.md @@ -0,0 +1,131 @@ +--- +title: OID\_GEN\_NETWORK\_LAYER\_ADDRESSES +author: windows-driver-content +description: As a set, the OID\_GEN\_NETWORK\_LAYER\_ADDRESSES OID notifies underlying miniport driver and other layered drivers about the list of network-layer addresses that are associated with bound instances. +ms.assetid: 4a75c2ca-1a58-462e-876a-a65cfe63441e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_NETWORK_LAYER_ADDRESSES Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_NETWORK\_LAYER\_ADDRESSES + + +As a set, the OID\_GEN\_NETWORK\_LAYER\_ADDRESSES OID notifies underlying miniport driver and other layered drivers about the list of network-layer addresses that are associated with bound instances. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +A bound instance is the binding between the calling transport and a driver set up by a call to [**NdisOpenAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff563715). Transports use TRANSPORT\_ADDRESS and TA\_ADDRESS structures to notify underlying miniport drivers and other layered drivers about the list of network-layer addresses. Miniport drivers and other layered drivers use compatible NETWORK\_ADDRESS\_LIST and NETWORK\_ADDRESS structures, defined as follows, to set the list of network-layer addresses on a bound interface. + +``` +typedef struct _NETWORK_ADDRESS_LIST { + LONG AddressCount; + USHORT AddressType; + NETWORK_ADDRESS Address[1]; +} NETWORK_ADDRESS_LIST, *PNETWORK_ADDRESS_LIST; +``` + +The members of this structure contain the following information: + +**AddressCount** +Specifies the number of network-layer addresses listed in the array in the **Address** member. + +**AddressType** +Specifies the protocol type that sends this OID. This member is only valid if the **AddressCount** member is set to zero. The **AddressCount** member is set to zero to notify a miniport driver or other layered driver to clear the list of network-layer addresses on a bound interface. The protocol can be one of the following values: + +NDIS\_PROTOCOL\_ID\_DEFAULT +Default protocol + +NDIS\_PROTOCOL\_ID\_TCP\_IP +TCP/IP protocol + +NDIS\_PROTOCOL\_ID\_IPX +NetWare IPX protocol + +NDIS\_PROTOCOL\_ID\_NBF +NetBIOS protocol + +**Address** +Array of network-layer addresses of type NETWORK\_ADDRESS. The **AddressCount** member specifies the number of elements in this array. + +``` +typedef struct _NETWORK_ADDRESS { + USHORT AddressLength; + USHORT AddressType; + UCHAR Address[1]; +} NETWORK_ADDRESS, *PNETWORK_ADDRESS; +``` + +The members of this structure contain the following information: + +**AddressLength** +Specifies the size, in bytes, of this network-layer address. The **Address** member contains the array of bytes that specify this address. + +**AddressType** +Specifies the protocol type that sends this OID and this network-layer address. This member is only valid if the **AddressCount** member in the NETWORK\_ADDRESS\_LIST structure is set to a nonzero value. The **AddressCount** member in NETWORK\_ADDRESS\_LIST is set to a nonzero value to notify a miniport driver or other layered driver to change the list of network-layer addresses on a bound interface. Protocol types are defined in the preceding list. + +**Address** +Array of bytes that specify this network-layer address. The **AddressLength** member specifies the number of bytes in this array. + +The transport can call the [**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) function and can pass an [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure that is filled with the OID\_GEN\_NETWORK\_LAYER\_ADDRESSES code. This call notifies a bound instance of a change in the addresses that are associated with that instance. In this call, the transport also passes the bound instance in the *NdisBindingHandle* parameter. The bound instance is the binding set up between the transport and the underlying miniport driver or other layered driver. For this call, the transport should fill the **InformationBuffer** member of NDIS\_OID\_REQUEST with a pointer to a TRANSPORT\_ADDRESS structure. TRANSPORT\_ADDRESS corresponds to a NETWORK\_ADDRESS\_LIST structure and should contain the list of network-layer addresses. + +Suppose a transport passes addresses through an intermediate driver down to an underlying miniport driver. If the intermediate driver also requires the addresses, it should take note of them before passing them on to the underlying miniport driver. An underlying miniport driver, especially an old driver, can return a status value of NDIS\_STATUS\_NOT\_SUPPORTED or NDIS\_STATUS\_SUCCESS. The underlying miniport driver propagates the status of the operation back up towards the transport. If the intermediate driver must continue receiving address notifications, and if it is necessary, the intermediate driver should change the status to NDIS\_STATUS\_SUCCESS.Otherwise, the transport might interpret NDIS\_STATUS\_NOT\_SUPPORTED as an indication that the underlying miniport driver does not require that the transport issue additional address updates. If NDIS\_STATUS\_SUCCESS is returned, transports are obligated to continue notifying underlying drivers of any change in associated addresses, including addition and deletion of addresses. + +A protocol can set the **AddressCount** member of TRANSPORT\_ADDRESS to zero to notify a miniport driver or other layered driver to clear the list of network-layer addresses on a bound interface. If **AddressCount** is set to zero, the **AddressType** member in NETWORK\_ADDRESS\_LIST is valid and the **AddressType** members in NETWORK\_ADDRESS structures are not valid. On the other hand, a protocol can set **AddressCount** to a nonzero value to notify a miniport driver or other layered driver to change the list of network-layer addresses on a bound interface. In this case, the **AddressType** member in NETWORK\_ADDRESS\_LIST is not valid and the **AddressType** members in NETWORK\_ADDRESS structures are valid. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) + +[**NdisOpenAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff563715) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_NETWORK_LAYER_ADDRESSES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-operational-status.md b/windows-driver-docs-pr/network/oid-gen-operational-status.md new file mode 100644 index 0000000000..4cca92048c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-operational-status.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_OPERATIONAL\_STATUS +author: windows-driver-content +description: As a query, use the OID\_GEN\_OPERATIONAL\_STATUS OID to determine the current operational status of a network interface (ifOperStatus from RFC 2863). +ms.assetid: fa00d449-6ec0-4e72-8d9c-a453a0b1f3e9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_OPERATIONAL_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_OPERATIONAL\_STATUS + + +As a query, use the OID\_GEN\_OPERATIONAL\_STATUS OID to determine the current operational status of a network interface (*ifOperStatus* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +NDIS handles this OID for miniport adapters and filter modules, and only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers receive this OID query. + +If the query succeeds, the interface provider returns NDIS\_STATUS\_SUCCESS, and the result of the query can be one of the values in the [**NET\_IF\_OPER\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff568746) enumeration. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NET\_IF\_OPER\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/ff568746) + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_OPERATIONAL_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-pci-device-custom-properties.md b/windows-driver-docs-pr/network/oid-gen-pci-device-custom-properties.md new file mode 100644 index 0000000000..82a50ecbf8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-pci-device-custom-properties.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES +author: windows-driver-content +description: As a query, overlying drivers use the OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES OID to get the PCI custom properties of a device. +ms.assetid: fe94884b-f5e3-4c60-8f52-e61d0df81a2a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PCI_DEVICE_CUSTOM_PROPERTIES Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES + + +As a query, overlying drivers use the OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES OID to get the PCI custom properties of a device. + +Remarks +------- + +NDIS handles OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES and miniport drivers do not receive an OID query. + +This query is optional for other NDIS drivers. + +NDIS returns an [**NDIS\_PCI\_DEVICE\_CUSTOM\_PROPERTIES**](https://msdn.microsoft.com/library/windows/hardware/ff566745) structure that contains the PCI custom properties. + +For non-PCI miniport adapters, NDIS fails OID\_GEN\_PCI\_DEVICE\_CUSTOM\_PROPERTIES with the NDIS\_STATUS\_INVALID\_DEVICE\_REQUEST status code. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PCI\_DEVICE\_CUSTOM\_PROPERTIES**](https://msdn.microsoft.com/library/windows/hardware/ff566745) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PCI_DEVICE_CUSTOM_PROPERTIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-physical-medium-ex.md b/windows-driver-docs-pr/network/oid-gen-physical-medium-ex.md new file mode 100644 index 0000000000..e6147085c9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-physical-medium-ex.md @@ -0,0 +1,76 @@ +--- +title: OID\_GEN\_PHYSICAL\_MEDIUM\_EX +author: windows-driver-content +description: As a query, the OID\_GEN\_PHYSICAL\_MEDIUM\_EX OID specifies the types of physical media that a miniport adapter supports. +ms.assetid: cbac8c9b-d7fe-4588-8a64-599d04a77a72 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PHYSICAL_MEDIUM_EX Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PHYSICAL\_MEDIUM\_EX + + +As a query, the OID\_GEN\_PHYSICAL\_MEDIUM\_EX OID specifies the types of physical media that a miniport adapter supports. + +Remarks +------- + +NDIS handles this OID for NDIS 6.0 and later miniport drivers. The miniport driver supplies the physical medium value during initialization. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains an NDIS\_PHYSICAL\_MEDIUM enumeration value. + +**Note**  The difference between OID\_GEN\_PHYSICAL\_MEDIUM\_EX and [OID\_GEN\_PHYSICAL\_MEDIUM](oid-gen-physical-medium.md) is that the OID\_GEN\_PHYSICAL\_MEDIUM\_EX version does not override the **NdisPhysicalMedium802\_3** type as **NdisPhysicalMediumUnspecified** whereas OID\_GEN\_PHYSICAL\_MEDIUM still does. We recommend that all 6.x drivers use the EX version. OID\_GEN\_PHYSICAL\_MEDIUM\_EX is exposed through a WMI GUID. + +  + +Miniport drivers report a physical media type to differentiate their physical media from media that they declared to support in the [OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) OID query. + +NDIS supports the OID\_GEN\_PHYSICAL\_MEDIUM\_EX OID for miniport adapters that support newer networks, even though those networks transfer packets that appear to the operating system and to NDIS as standard, well-known media types. + +Newer networks transfer packets that might appear like standard media, but that might have new features or slight differences from the standard. This OID exists so upper-layer drivers and applications can determine the actual networks to which a NIC connects. After retrieving information about underlying networks, upper-layer drivers and applications can use this information to modify how such drivers and applications behave. + +To clearly distinguish an 802.3 NIC from an emulated 802.3 NIC for which there is no physical medium type defined, NDIS 6.0 and later and later versions require 802.3 miniport drivers to report an **NdisPhysicalMedium802\_3** media type. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Not requested for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) + +[OID\_GEN\_PHYSICAL\_MEDIUM](oid-gen-physical-medium.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PHYSICAL_MEDIUM_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-physical-medium.md b/windows-driver-docs-pr/network/oid-gen-physical-medium.md new file mode 100644 index 0000000000..e16f03d2ea --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-physical-medium.md @@ -0,0 +1,135 @@ +--- +title: OID\_GEN\_PHYSICAL\_MEDIUM +author: windows-driver-content +description: As a query, the OID\_GEN\_PHYSICAL\_MEDIUM OID specifies the types of physical media that the NIC supports. +ms.assetid: 84d7231b-8af2-4bdb-8df5-37088767f708 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PHYSICAL_MEDIUM Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PHYSICAL\_MEDIUM + + +As a query, the OID\_GEN\_PHYSICAL\_MEDIUM OID specifies the types of physical media that the NIC supports. This OID is essentially an extension of [OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md). + +**Version Information** + +**Note**  This OID is supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [OID\_GEN\_PHYSICAL\_MEDIUM\_EX](oid-gen-physical-medium-ex.md). + +  + +Remarks +------- + +NDIS handles this OID for miniport drivers. The miniport driver supplies the physical medium value during initialization. + +Miniport drivers report a physical media type to differentiate their physical media from media that they declared to support in the [OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) OID query. These media types are listed as a proper subset of the following system-defined values from the **NDIS\_PHYSICAL\_MEDIUM** enumeration: + +**NdisPhysicalMediumUnspecified** +The physical medium is none of the preceding mediums. For example, a one-way satellite feed is an unspecified physical medium. + +**NdisPhysicalMediumWirelessLan** +Packets are transferred over a wireless LAN network through a miniport driver that conforms to the 802.11 interface. For more information about this interface, see. [802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff543933) + +**NdisPhysicalMediumCableModem** +Packets are transferred over a DOCSIS-based cable network. + +**NdisPhysicalMediumPhoneLine** +Packets are transferred over standard phone lines. +Includes, for example, HomePNA media. +**NdisPhysicalMediumPowerLine** +Packets are transferred over wiring that is connected to a power distribution system. + +**NdisPhysicalMediumDSL** +Packets are transferred over a Digital Subscriber Line (DSL) network. +Includes, for example, ADSL and UADSL (G.Lite). +**NdisPhysicalMediumFibreChannel** +Packets are transferred over a Fibre Channel interconnect. + +**NdisPhysicalMedium1394** +Packets are transferred over an IEEE 1394 bus. + +**NdisPhysicalMediumWirelessWan** +Packets are transferred over a Wireless WAN link. Includes, for example, CDPD, CDMA, and GPRS. + +**NdisPhysicalMediumNative802\_11** +Packets are transferred over a wireless LAN network through a miniport driver that conforms to the Native 802.11 interface. For more information about this interface, see [Native 802.11 Wireless LAN Miniport Drivers](https://msdn.microsoft.com/library/windows/hardware/ff560648). + +**Note**  The Native 802.11 interface is supported in NDIS 6.0 and later and later and later versions. + +  + +**NdisPhysicalMediumBluetooth** +Packets are transferred over a Bluetooth network. Bluetooth is a short-range wireless technology that uses the 2.4 GHz spectrum. + +**NdisPhysicalMediumInfiniband** +The Infiniband physical medium. Packets are transferred over an infiniband interconnect. + +**NdisPhysicalMediumUWB** +The Ultra Wideband (UWB) physical medium. Packets are transferred over a UWB network. UWB is a radio frequency platform that personal area networks can use to wirelessly communicate over short distances at high speeds. + +**NdisPhysicalMedium802\_3** +The Ethernet (802.3) physical medium. Packets are transferred over a wired LAN through a miniport driver that conforms to the 802.3 interface specification. This medium type does not include devices that emulate 802.3. + +**NdisPhysicalMedium802\_5** +The Token Ring physical medium. (802.5 is not supported in NDIS 6.0 and later and later drivers.) Packets are transferred over a Token Ring network through a miniport driver that conforms to the 802.5 interface specification. + +**NdisPhysicalMediumIrda** +The infrared (IrDA) physical medium. Packets are transferred over a nonvisible, infrared light spectrum IrDA network. + +**NdisPhysicalMediumWiredWAN** +The wired, wide area network (WAN) physical medium. Packets are transferred over a wired WAN. + +**NdisPhysicalMediumWiredCoWan** +The wired, connection-oriented WAN physical medium. Packets are transferred over a wired WAN in a connection-oriented environment. + +**NdisPhysicalMediumOther** +The physical medium is none of the preceding mediums. **NdisPhysicalMediumOther** specifies a new physical medium type that is not present in the NDIS\_PHYSICAL\_MEDIUM enumeration. + +NDIS supports the OID\_GEN\_PHYSICAL\_MEDIUM OID for miniport adapters that support newer networks, even though those networks transfer packets that appear to the operating system and to NDIS as standard and well known media types. + +Newer networks transfer packets that might appear like standard media but that might have new features or slight differences from the standard. This OID was developed so upper-layer drivers and applications could determine the actual networks to which a NIC connects. After retrieving information about underlying networks, upper-layer drivers and applications could use this information to modify how such drivers and applications behave. + +To clearly distinguish an 802.3 NIC from an emulated 802.3 NIC for which there is no physical medium type defined, NDIS 6.0 and later and later and later versions require 802.3 miniport drivers to report **NdisPhysicalMedium802\_3**. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [OID_GEN_PHYSICAL_MEDIUM_EX](oid-gen-physical-medium-ex.md) instead.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_MEDIA\_SUPPORTED](oid-gen-media-supported.md) + +[OID\_GEN\_PHYSICAL\_MEDIUM\_EX](oid-gen-physical-medium-ex.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PHYSICAL_MEDIUM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-port-authentication-parameters.md b/windows-driver-docs-pr/network/oid-gen-port-authentication-parameters.md new file mode 100644 index 0000000000..77ab413c49 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-port-authentication-parameters.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_PORT\_AUTHENTICATION\_PARAMETERS +author: windows-driver-content +description: As a set, NDIS and overlying drivers use the OID\_GEN\_PORT\_AUTHENTICATION\_PARAMETERS OID to set the current state of an NDIS port. +ms.assetid: 676601c1-2647-4341-9a5c-cee895d2dbf7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PORT_AUTHENTICATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PORT\_AUTHENTICATION\_PARAMETERS + + +As a set, NDIS and overlying drivers use the OID\_GEN\_PORT\_AUTHENTICATION\_PARAMETERS OID to set the current state of an NDIS port. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. Mandatory for NDIS ports. (see Remarks section) + +Remarks +------- + +Miniport drivers that support NDIS ports must support this OID. + +If a miniport driver does not support this OID, the miniport driver should return NDIS\_STATUS\_NOT\_SUPPORTED. + +If the miniport driver supports this OID, the driver returns NDIS\_STATUS\_SUCCESS and provides the receive port direction, port control state, and authenticate state in an [**NDIS\_PORT\_AUTHENTICATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566788) structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PORT\_AUTHENTICATION\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566788) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PORT_AUTHENTICATION_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-port-state.md b/windows-driver-docs-pr/network/oid-gen-port-state.md new file mode 100644 index 0000000000..e4b87fefd0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-port-state.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_PORT\_STATE +author: windows-driver-content +description: As a query, overlying drivers use the OID\_GEN\_PORT\_STATE OID to get the current state of the port that is specified in the PortNumber member of the NDIS\_OID\_REQUEST structure. +ms.assetid: e0705b2e-08ea-4ed4-a6df-4c33b934c3dd +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PORT_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PORT\_STATE + + +As a query, overlying drivers use the OID\_GEN\_PORT\_STATE OID to get the current state of the port that is specified in the **PortNumber** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID and miniport drivers do not receive this OID query. + +If the query succeeds, NDIS returns NDIS\_STATUS\_SUCCESS and returns the port state information in an [**NDIS\_PORT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566800) structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PORT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff566800) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PORT_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-promiscuous-mode.md b/windows-driver-docs-pr/network/oid-gen-promiscuous-mode.md new file mode 100644 index 0000000000..fe96c8a119 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-promiscuous-mode.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_PROMISCUOUS\_MODE +author: windows-driver-content +description: As a query, use the OID\_GEN\_PROMISCUOUS\_MODE OID to determine whether a network interface is promiscuous or not (ifPromiscuousMode from RFC 2863). +ms.assetid: c3ba0908-724c-4149-a66f-5c3d41751165 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PROMISCUOUS_MODE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PROMISCUOUS\_MODE + + +As a query, use the OID\_GEN\_PROMISCUOUS\_MODE OID to determine whether a network interface is promiscuous or not (*ifPromiscuousMode* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the interface provider returns NDIS\_STATUS\_SUCCESS and if the interface accepts only packets that are addressed to that interface, the result value should be **FALSE**. This value should be **TRUE** if the interface accepts all network packets. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PROMISCUOUS_MODE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-protocol-options.md b/windows-driver-docs-pr/network/oid-gen-protocol-options.md new file mode 100644 index 0000000000..1ebbc35293 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-protocol-options.md @@ -0,0 +1,74 @@ +--- +title: OID\_GEN\_PROTOCOL\_OPTIONS +author: windows-driver-content +description: As a set, the OID\_GEN\_PROTOCOL\_OPTIONS OID specifies a bitmask that defines optional properties of the protocol driver. +ms.assetid: 48c3468b-2d8b-48cb-9a25-19470923f582 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_PROTOCOL_OPTIONS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_PROTOCOL\_OPTIONS + + +As a set, the OID\_GEN\_PROTOCOL\_OPTIONS OID specifies a bitmask that defines optional properties of the protocol driver. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. This OID is for protocol drivers. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +A protocol informs NDIS of its properties, which can optionally take advantage of them. If the protocol driver does not set its flags on a binding, NDIS assumes they are all clear. + +The following flags are currently defined: + +NDIS\_PROT\_OPTION\_ESTIMATED\_LENGTH +Specifies that packets can be indicated at the worst-case estimate of packet size, instead of an exact value, to this protocol. + +NDIS\_PROT\_OPTION\_NO\_LOOPBACK +Specifies that the protocol does not require loopback support on the binding. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_PROTOCOL_OPTIONS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-crc-error.md b/windows-driver-docs-pr/network/oid-gen-rcv-crc-error.md new file mode 100644 index 0000000000..c15b8b2b27 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-crc-error.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_RCV\_CRC\_ERROR +author: windows-driver-content +description: As a query, the OID\_GEN\_RCV\_CRC\_ERROR OID specifies the number of frames that are received with checksum errors. +ms.assetid: dfa5e568-2b0a-4b26-8100-06ea8b0f1a71 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_CRC_ERROR Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_CRC\_ERROR + + +As a query, the OID\_GEN\_RCV\_CRC\_ERROR OID specifies the number of frames that are received with checksum errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +The value for the [OID\_GEN\_RCV\_DISCARDS](oid-gen-rcv-discards.md) OID includes CRC errors. For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_CRC_ERROR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-discards.md b/windows-driver-docs-pr/network/oid-gen-rcv-discards.md new file mode 100644 index 0000000000..dc27acab2f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-discards.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_RCV\_DISCARDS +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_RCV\_DISCARDS OID to determine the number of receive discards on a miniport adapter. +ms.assetid: 638d2961-d327-490d-925b-3f6c30a13a89 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_DISCARDS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_DISCARDS + + +As a query, NDIS and overlying drivers use the OID\_GEN\_RCV\_DISCARDS OID to determine the number of receive discards on a miniport adapter. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID for miniport drivers. See the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) OID for more information about statistics. + +The count is the dropped-receive-buffer error count as described in RFC 2863. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_DISCARDS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-error.md b/windows-driver-docs-pr/network/oid-gen-rcv-error.md new file mode 100644 index 0000000000..e348707a6f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-error.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_RCV\_ERROR +author: windows-driver-content +description: As a query, the OID\_GEN\_RCV\_ERROR OID specifies the number of frames that a NIC receives but does not indicate to the protocols due to errors. +ms.assetid: 0481f225-869f-4313-9bc5-7af1de0b7d2d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_ERROR Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_ERROR + + +As a query, the OID\_GEN\_RCV\_ERROR OID specifies the number of frames that a NIC receives but does not indicate to the protocols due to errors. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 drivers +Mandatory. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_ERROR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-link-speed.md b/windows-driver-docs-pr/network/oid-gen-rcv-link-speed.md new file mode 100644 index 0000000000..6ba541aa6b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-link-speed.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_RCV\_LINK\_SPEED +author: windows-driver-content +description: As a query, use the OID\_GEN\_RCV\_LINK\_SPEED OID to determine the receive link speed of a network interface. Version Information Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: d66bdba3-93f4-4a5a-a658-9b1a2e1b9407 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_LINK_SPEED Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_LINK\_SPEED + + +As a query, use the OID\_GEN\_RCV\_LINK\_SPEED OID to determine the receive link speed of a network interface. + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is a ULONG64 value that indicates the receive link speed of the interface, in bits per second. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_LINK_SPEED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-no-buffer.md b/windows-driver-docs-pr/network/oid-gen-rcv-no-buffer.md new file mode 100644 index 0000000000..1571b5e2f2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-no-buffer.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_RCV\_NO\_BUFFER +author: windows-driver-content +description: As a query, the OID\_GEN\_RCV\_NO\_BUFFER OID specifies the number of frames that the NIC cannot receive due to lack of NIC receive buffer space. +ms.assetid: 0fcbc7cc-439b-450f-b256-3584b29909fb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_NO_BUFFER Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_NO\_BUFFER + + +As a query, the OID\_GEN\_RCV\_NO\_BUFFER OID specifies the number of frames that the NIC cannot receive due to lack of NIC receive buffer space. Some NICs do not provide the exact number of missed frames; they provide only the number of times at least one frame is missed. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 drivers +Mandatory. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_NO_BUFFER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rcv-ok.md b/windows-driver-docs-pr/network/oid-gen-rcv-ok.md new file mode 100644 index 0000000000..0833f80bb4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rcv-ok.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_RCV\_OK +author: windows-driver-content +description: As a query, the OID\_GEN\_RCV\_OK OID specifies the number of frames that the NIC receives without errors and indicates to bound protocols. +ms.assetid: 737ac1a5-9f7a-422b-9ccf-42a3176639bc +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RCV_OK Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RCV\_OK + + +As a query, the OID\_GEN\_RCV\_OK OID specifies the number of frames that the NIC receives without errors and indicates to bound protocols. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later drivers +Mandatory. + +NDIS 5.1 drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 drivers +Mandatory. + +Remarks +------- + +OID\_GEN\_RCV\_OK specifies the number of frames that are received without errors. However, the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) does not include this information. + +NOTE: Statistics OIDs are mandatory for NDIS 6.0 and later miniport drivers unless NDIS handles them. For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RCV_OK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-receive-block-size.md b/windows-driver-docs-pr/network/oid-gen-receive-block-size.md new file mode 100644 index 0000000000..4eda682f76 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-receive-block-size.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_RECEIVE\_BLOCK\_SIZE +author: windows-driver-content +description: As a query. +ms.assetid: 92a7a388-4a41-41cf-96e5-a65b5559553d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RECEIVE_BLOCK_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RECEIVE\_BLOCK\_SIZE + + +As a query. the OID\_GEN\_RECEIVE\_BLOCK\_SIZE OID specifies the amount of storage, in bytes, that a single packet occupies in the receive buffer space of the NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The OID\_GEN\_RECEIVE\_BLOCK\_SIZE OID specifies the amount of storage, in bytes, that a single packet occupies in the receive buffer space of a NIC. + +The same information can be obtained from the current and maximum *lookahead* size. However, one of these OIDs can be mandatory to verify each other. Also protocol drivers can determine if the underlying driver indicates full-packet receives by comparing the values that driver returns for the [OID\_GEN\_CURRENT\_LOOKAHEAD](oid-gen-current-lookahead.md) and OID\_GEN\_RECEIVE\_BLOCK\_SIZE OIDs. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_CURRENT\_LOOKAHEAD](oid-gen-current-lookahead.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RECEIVE_BLOCK_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-receive-buffer-space.md b/windows-driver-docs-pr/network/oid-gen-receive-buffer-space.md new file mode 100644 index 0000000000..f9310ad7d0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-receive-buffer-space.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_RECEIVE\_BUFFER\_SPACE +author: windows-driver-content +description: As a query, the OID\_GEN\_RECEIVE\_BUFFER\_SPACE OID specifies the amount of memory on the NIC that is available for buffering receive data. +ms.assetid: 6eec18fa-22cd-4f65-acf4-0dd438dea2ff +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RECEIVE_BUFFER_SPACE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RECEIVE\_BUFFER\_SPACE + + +As a query, the OID\_GEN\_RECEIVE\_BUFFER\_SPACE OID specifies the amount of memory on the NIC that is available for buffering receive data. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +A protocol driver can use this OID as a guide for advertising its receive window after it establishes sessions with remote nodes. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RECEIVE_BUFFER_SPACE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-receive-hash.md b/windows-driver-docs-pr/network/oid-gen-receive-hash.md new file mode 100644 index 0000000000..44b275d7f0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-receive-hash.md @@ -0,0 +1,72 @@ +--- +title: OID\_GEN\_RECEIVE\_HASH +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_RECEIVE\_HASH OID to obtain the current receive hash calculation settings of a miniport adapter. +ms.assetid: be120dab-c98d-418f-8777-e2fb37b774a1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RECEIVE_HASH Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RECEIVE\_HASH + + +As a query, NDIS and overlying drivers use the OID\_GEN\_RECEIVE\_HASH OID to obtain the current receive hash calculation settings of a miniport adapter. NDIS returns an [**NDIS\_RECEIVE\_HASH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567190) structure that contains the current receive hash settings. + +As a set, NDIS and overlying drivers use the OID\_GEN\_RECEIVE\_HASH OID to configure the receive hash calculations on a miniport adapter. The miniport driver receives an NDIS\_RECEIVE\_HASH\_PARAMETERS structure. + +Remarks +------- + +For NDIS miniport drivers, the query is not requested. + +Support for this OID set is optional for miniport drivers, including those that support RSS. + +An overlying driver can use the OID\_GEN\_RECEIVE\_HASH OID to enable and configure hash calculations on received frames without enabling RSS. + +**Note**  Protocol drivers must disable receive hash calculations before they enable RSS. If RSS is enabled, a protocol driver disables RSS before it enables receive hash calculations. A miniport driver should fail a set request with **NDIS\_STATUS\_INVALID\_OID** or **NDIS\_STATUS\_NOT\_SUPPORTED** to enable receive hash calculations if [OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS](oid-gen-receive-scale-parameters.md) is currently enabled. + +  + +**Note**  The secret key is appended after the [**NDIS\_RECEIVE\_HASH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567190) structure members. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RECEIVE\_HASH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567190) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RECEIVE_HASH%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-receive-scale-capabilities.md b/windows-driver-docs-pr/network/oid-gen-receive-scale-capabilities.md new file mode 100644 index 0000000000..6bf21c54d4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-receive-scale-capabilities.md @@ -0,0 +1,60 @@ +--- +title: OID\_GEN\_RECEIVE\_SCALE\_CAPABILITIES +author: windows-driver-content +description: As a query, overlying drivers can use the OID\_GEN\_RECEIVE\_SCALE\_CAPABILITIES OID to query the receive side scaling (RSS) capabilities of a NIC and its miniport driver. +ms.assetid: b7640ec3-248c-4db2-818d-3976df2dcb9b +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RECEIVE_SCALE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RECEIVE\_SCALE\_CAPABILITIES + + +As a query, overlying drivers can use the OID\_GEN\_RECEIVE\_SCALE\_CAPABILITIES OID to query the receive side scaling (RSS) capabilities of a NIC and its miniport driver. + +Remarks +------- + +NDIS miniport drivers do not receive this OID request. NDIS handles the query for miniport drivers. + +The miniport driver returns the RSS capabilities in an [**NDIS\_RECEIVE\_SCALE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff567220) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RECEIVE\_SCALE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff567220) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RECEIVE_SCALE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-receive-scale-parameters.md b/windows-driver-docs-pr/network/oid-gen-receive-scale-parameters.md new file mode 100644 index 0000000000..94a5960403 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-receive-scale-parameters.md @@ -0,0 +1,78 @@ +--- +title: OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS +author: windows-driver-content +description: As a query, NDIS and overlying drivers can use the OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS OID to query the current receive side scaling (RSS) parameters of a NIC. +ms.assetid: a54190f7-0d2e-4f85-84c2-05fc9ec4994a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RECEIVE_SCALE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS + + +As a query, NDIS and overlying drivers can use the OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS OID to query the current receive side scaling (RSS) parameters of a NIC. NDIS returns an [**NDIS\_RECEIVE\_SCALE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567228) structure that defines the current RSS parameters. + +As a set, NDIS and overlying drivers use the OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS OID to set the current RSS parameters of a NIC. The miniport driver receives an NDIS\_RECEIVE\_SCALE\_PARAMETERS structure that defines the RSS parameters. + +Remarks +------- + +For NDIS miniport drivers, the query is not requested and the set is required for drivers that support RSS. NDIS handles the query for miniport drivers. + +The TCP/IP driver configures IPv4 and IPv6 with a single OID set request of OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS. That is, when the stack should enable RSS for both IPv4 and IPv6, it sets both of the corresponding flags in the **HashInformation** member of the [**NDIS\_RECEIVE\_SCALE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567228) structure and sends one OID request. Also, IPv4 and IPv6 use the same secret key and the key will always be 40 bytes, even if only IPv4 is enabled. + +The underlying miniport adapter must use the most recent OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS OID settings it has received. For example, if the miniport gets an OID\_GEN\_RECEIVE\_SCALE\_PARAMETERS OID with the IPv4 hash types missing, it must disable IPv4 RSS if it was previously enabled. + +**Note**  An overlying driver can use the [OID\_GEN\_RECEIVE\_HASH](oid-gen-receive-hash.md) OID to enable and configure hash calculations on received frames without enabling RSS. + +  + +**Note**  Protocol drivers must disable receive hash calculations ([OID\_GEN\_RECEIVE\_HASH](oid-gen-receive-hash.md)) before they enable RSS. If RSS is enabled, a protocol driver disables RSS before it enables receive hash calculations. A miniport driver should fail a set request with **NDIS\_STATUS\_INVALID\_OID** or **NDIS\_STATUS\_NOT\_SUPPORTED** to enable RSS if OID\_GEN\_RECEIVE\_HASH is currently enabled. + +  + +**Note**  The indirection table and secret key are appended after the [**NDIS\_RECEIVE\_SCALE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567228) structure members. For more information about the indirection table and secret key, see **NDIS\_RECEIVE\_SCALE\_PARAMETERS**. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_RECEIVE\_SCALE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567228) + +[OID\_GEN\_RECEIVE\_HASH](oid-gen-receive-hash.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RECEIVE_SCALE_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-reset-counts.md b/windows-driver-docs-pr/network/oid-gen-reset-counts.md new file mode 100644 index 0000000000..d3f689def9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-reset-counts.md @@ -0,0 +1,53 @@ +--- +title: OID\_GEN\_RESET\_COUNTS +author: windows-driver-content +description: As a query, the OID\_GEN\_RESET\_COUNTS OID returns the number of times the miniport adapter was reset. +ms.assetid: 3f27d801-f044-4f50-98eb-c16d8e4291f2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RESET_COUNTS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RESET\_COUNTS + + +As a query, the OID\_GEN\_RESET\_COUNTS OID returns the number of times the miniport adapter was reset. + +Remarks +------- + +The OID\_GEN\_RESET\_COUNTS OID returns the number of times the miniport adapter was reset. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1 and later drivers in Windows Vista and later versions of Windows and later versions of Windows. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RESET_COUNTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-rndis-config-parameter.md b/windows-driver-docs-pr/network/oid-gen-rndis-config-parameter.md new file mode 100644 index 0000000000..e48afb0b3d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-rndis-config-parameter.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_RNDIS\_CONFIG\_PARAMETER +author: windows-driver-content +description: As a set, the OID\_GEN\_RNDIS\_CONFIG\_PARAMETER is used to set device-specific parameters. +ms.assetid: 79e74e8b-7811-46a5-8ede-f6cca92967b0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_RNDIS_CONFIG_PARAMETER Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_RNDIS\_CONFIG\_PARAMETER + + +As a set, the OID\_GEN\_RNDIS\_CONFIG\_PARAMETER is used to set device-specific parameters. The host uses it with RNDIS devices only. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For RNDIS devices only. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +The OID\_GEN\_RNDIS\_CONFIG\_PARAMETER is used with RNDIS devices. The host uses it to set device-specific parameters. It is not used by miniport drivers. For more information about this OID, see [Setting Device-Specific Parameters](https://msdn.microsoft.com/library/windows/hardware/ff570784). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_RNDIS_CONFIG_PARAMETER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-statistics.md b/windows-driver-docs-pr/network/oid-gen-statistics.md new file mode 100644 index 0000000000..c864d2258b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-statistics.md @@ -0,0 +1,251 @@ +--- +title: OID\_GEN\_STATISTICS +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_STATISTICS OID to obtain statistics of an adapter or a miniport driver. +ms.assetid: ff81d6b0-806d-4ddf-9da1-a169221be61f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_STATISTICS + + +As a query, NDIS and overlying drivers use the OID\_GEN\_STATISTICS OID to obtain statistics of an adapter or a miniport driver. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +The NDIS\_STATISTICS\_INFO structure is defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_STATISTICS_INFO { + NDIS_OBJECT_HEADER Header; + ULONG SupportedStatistics; + ULONG64 ifInDiscards; + ULONG64 ifInErrors; + ULONG64 ifHCInOctets; + ULONG64 ifHCInUcastPkts; + ULONG64 ifHCInMulticastPkts; + ULONG64 ifHCInBroadcastPkts; + ULONG64 ifHCOutOctets; + ULONG64 ifHCOutUcastPkts; + ULONG64 ifHCOutMulticastPkts; + ULONG64 ifHCOutBroadcastPkts; + ULONG64 ifOutErrors; + ULONG64 ifOutDiscards; + ULONG64 ifHCInUcastOctets; + ULONG64 ifHCInMulticastOctets; + ULONG64 ifHCInBroadcastOctets; + ULONG64 ifHCOutUcastOctets; + ULONG64 ifHCOutMulticastOctets; + ULONG64 ifHCOutBroadcastOctets; + } NDIS_STATISTICS_INFO, *PNDIS_STATISTICS_INFO; + +``` + +## + + +This structure contains the following members: + +**Header** +The [**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) structure for the NDIS\_STATISTICS\_INFO structure. Set the **Type** member of the structure that **Header** specifies to NDIS\_OBJECT\_TYPE\_DEFAULT, the **Revision** member to NDIS\_STATISTICS\_INFO\_REVISION\_1, and the **Size** member to NDIS\_SIZEOF\_STATISTICS\_INFO\_REVISION\_1. + +**SupportedStatistics** +The set of statistics that the miniport driver supports. + +**Note**  NDIS 6.0 and later drivers must support all statistics and must report them when queried for OID\_GEN\_STATISTICS. + +  + +The value is the bitwise OR of the following flags: + +NDIS\_STATISTICS\_FLAGS\_VALID\_DIRECTED\_FRAMES\_RCV +The data in the **ifHCInUcastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_MULTICAST\_FRAMES\_RCV +The data in the **ifHCInMulticastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BROADCAST\_FRAMES\_RCV +The data in the **ifHCInBroadcastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BYTES\_RCV +The data in the **ifHCInOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_RCV\_DISCARDS +The data in the **ifInDiscards** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_RCV\_ERROR +The data in the **ifInErrors** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_DIRECTED\_FRAMES\_XMIT +The data in the **ifHCOutUcastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_MULTICAST\_FRAMES\_XMIT +The data in the **ifHCOutMulticastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BROADCAST\_FRAMES\_XMIT +The data in the **ifHCOutBroadcastPkts** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BYTES\_XMIT +The data in the **ifHCOutOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_XMIT\_ERROR +The data in the **ifOutErrors** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_XMIT\_DISCARDS +The data in the **ifOutDiscards** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_DIRECTED\_BYTES\_RCV +The data in the **ifHCInUcastOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_MULTICAST\_BYTES\_RCV +The data in the **ifHCInMulticastOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BROADCAST\_BYTES\_RCV +The data in the **ifHCInBroadcastOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_DIRECTED\_BYTES\_XMIT +The data in the **ifHCOutUcastOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_MULTICAST\_BYTES\_XMIT +The data in the **ifHCOutMulticastOctets** member is valid. + +NDIS\_STATISTICS\_FLAGS\_VALID\_BROADCAST\_BYTES\_XMIT +The data in the **ifHCOutBroadcastOctets** member is valid. + +**ifInDiscards** +The dropped-receive-buffer error count. This is the same value that [OID\_GEN\_RCV\_DISCARDS](oid-gen-rcv-discards.md) returns. + +**ifInErrors** +The receive error count. This count is the same value that [OID\_GEN\_RCV\_ERROR](oid-gen-rcv-error.md) returns. + +**ifHCInOctets** +The sum of the receive-directed byte count, receive-multicast byte count, and receive-broadcast byte count. This sum is the same value that [OID\_GEN\_BYTES\_RCV](oid-gen-bytes-rcv.md) returns. + +**ifHCInUcastPkts** +The number of directed packets that are received without errors. This number is the same value that [OID\_GEN\_DIRECTED\_FRAMES\_RCV](oid-gen-directed-frames-rcv.md) returns. + +**ifHCInMulticastPkts** +The number of multicast/functional packets that are received without errors. This number is the same value that [OID\_GEN\_MULTICAST\_FRAMES\_RCV](oid-gen-multicast-frames-rcv.md) returns. + +**ifHCInBroadcastPkts** +The number of broadcast packets that are received without errors. This number is the same value that [OID\_GEN\_BROADCAST\_FRAMES\_RCV](oid-gen-broadcast-frames-rcv.md) returns. + +**ifHCOutOctets** +The sum of the transmit-directed byte count, transmit-multicast byte count and transmit-broadcast byte count. This sum is the same value that [OID\_GEN\_BYTES\_XMIT](oid-gen-bytes-xmit.md) returns. + +**ifHCOutUcastPkts** +The number of directed packets that are transmitted without errors. This number is the same value that [OID\_GEN\_DIRECTED\_FRAMES\_XMIT](oid-gen-directed-frames-xmit.md) returns. + +**ifHCOutMulticastPkts** +The number of multicast/functional packets that are transmitted without errors. This number is the same value that [OID\_GEN\_MULTICAST\_FRAMES\_XMIT](oid-gen-multicast-frames-xmit.md) returns. + +**ifHCOutBroadcastPkts** +The number of broadcast packets that are transmitted without errors. This number is the same value that [OID\_GEN\_BROADCAST\_FRAMES\_XMIT](oid-gen-broadcast-frames-xmit.md) returns. + +**ifOutErrors** +The transmit error count. This count is the same value that [OID\_GEN\_XMIT\_ERROR](oid-gen-xmit-error.md) returns. + +**ifOutDiscards** +The number of packets that is discarded by the interface. This is same as the value that is returned by querying the [OID\_GEN\_XMIT\_DISCARDS](oid-gen-xmit-discards.md) OID. + +**ifHCInUcastOctets** +The number of bytes in directed packets that are received without errors. This count is the same value that [OID\_GEN\_DIRECTED\_BYTES\_RCV](oid-gen-directed-bytes-rcv.md) returns. + +**ifHCInMulticastOctets** +The number of bytes in multicast/functional packets that are received without errors. This count is the same value that [OID\_GEN\_MULTICAST\_BYTES\_RCV](oid-gen-multicast-bytes-rcv.md) returns. + +**ifHCInBroadcastOctets** +The number of bytes in broadcast packets that are received without errors. This count is the same value that [OID\_GEN\_BROADCAST\_BYTES\_RCV](oid-gen-broadcast-bytes-rcv.md) returns. + +**ifHCOutUcastOctets** +The number of bytes in directed packets that are transmitted without errors. This count is the same value that [OID\_GEN\_DIRECTED\_BYTES\_XMIT](oid-gen-directed-bytes-xmit.md) returns. + +**ifHCOutMulticastOctets** +The number of bytes in multicast/functional packets that are transmitted without errors. This count is the same value that [OID\_GEN\_MULTICAST\_BYTES\_XMIT](oid-gen-multicast-bytes-xmit.md) returns. + +**ifHCOutBroadcastOctets** +The number of bytes in broadcast packets that are transmitted without errors. This count is the same value that [OID\_GEN\_BROADCAST\_BYTES\_XMIT](oid-gen-broadcast-bytes-xmit.md) returns. + +Remarks +------- + +Miniport drivers must implement the statistics counters and report the correct statistics values. The statistics counters are unsigned 64-bit values. The miniport driver returns the statistics in an NDIS\_STATISTICS\_INFO structure. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OBJECT\_HEADER**](https://msdn.microsoft.com/library/windows/hardware/ff566588) + +[OID\_GEN\_BROADCAST\_BYTES\_RCV](oid-gen-broadcast-bytes-rcv.md) + +[OID\_GEN\_BROADCAST\_BYTES\_XMIT](oid-gen-broadcast-bytes-xmit.md) + +[OID\_GEN\_BROADCAST\_FRAMES\_RCV](oid-gen-broadcast-frames-rcv.md) + +[OID\_GEN\_BROADCAST\_FRAMES\_XMIT](oid-gen-broadcast-frames-xmit.md) + +[OID\_GEN\_BYTES\_RCV](oid-gen-bytes-rcv.md) + +[OID\_GEN\_BYTES\_XMIT](oid-gen-bytes-xmit.md) + +[OID\_GEN\_DIRECTED\_BYTES\_RCV](oid-gen-directed-bytes-rcv.md) + +[OID\_GEN\_DIRECTED\_BYTES\_XMIT](oid-gen-directed-bytes-xmit.md) + +[OID\_GEN\_DIRECTED\_FRAMES\_RCV](oid-gen-directed-frames-rcv.md) + +[OID\_GEN\_DIRECTED\_FRAMES\_XMIT](oid-gen-directed-frames-xmit.md) + +[OID\_GEN\_MULTICAST\_FRAMES\_RCV](oid-gen-multicast-frames-rcv.md) + +[OID\_GEN\_MULTICAST\_FRAMES\_XMIT](oid-gen-multicast-frames-xmit.md) + +[OID\_GEN\_MULTICAST\_BYTES\_RCV](oid-gen-multicast-bytes-rcv.md) + +[OID\_GEN\_MULTICAST\_BYTES\_XMIT](oid-gen-multicast-bytes-xmit.md) + +[OID\_GEN\_RCV\_DISCARDS](oid-gen-rcv-discards.md) + +[OID\_GEN\_RCV\_ERROR](oid-gen-rcv-error.md) + +[OID\_GEN\_XMIT\_DISCARDS](oid-gen-xmit-discards.md) + +[OID\_GEN\_XMIT\_ERROR](oid-gen-xmit-error.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_STATISTICS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-supported-guids.md b/windows-driver-docs-pr/network/oid-gen-supported-guids.md new file mode 100644 index 0000000000..f29165125f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-supported-guids.md @@ -0,0 +1,147 @@ +--- +title: OID\_GEN\_SUPPORTED\_GUIDS +author: windows-driver-content +description: As a query, the OID\_GEN\_SUPPORTED\_GUIDS OID requests the miniport driver to return an array of structures of the type NDIS\_GUID. +ms.assetid: 6985727e-50f8-4dbf-b8cd-ce31d49e8294 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_SUPPORTED_GUIDS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_SUPPORTED\_GUIDS + + +As a query, the OID\_GEN\_SUPPORTED\_GUIDS OID requests the miniport driver to return an array of structures of the type NDIS\_GUID. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +Each structure in the array specifies the mapping of a custom GUID (globally unique identifier) to either a custom OID or to an NDIS\_STATUS that the miniport driver sends through the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function. + +The NDIS\_GUID structure is defined as follows: + +``` +typedef struct _NDIS_GUID { + GUID Guid; + union { + NDIS_OID Oid; + NDIS_STATUS Status; + }; + ULONG Size; + ULONG Flags; +} NDIS_GUID, *PNDIS_GUID; +``` + +The members of this structure contain the following information: + +**Guid** +Specifies the custom GUID defined for the miniport driver. + +**Oid** +Specifies the custom OID to which **Guid** maps. + +**Status** +Specifies the NDIS\_STATUS to which **Guid** maps. + +**Size** +Specifies the size in bytes of each data item in the array returned by the miniport driver. If the fNDIS\_GUID\_ANSI\_STRING or fNDIS\_GUID\_NDIS\_STRING flag is set, **Size** is set to -1. Otherwise, **Size** specifies the size in bytes of the data item that the GUID represents. This member is specified only when the fNDIS\_GUID\_ARRAY flag is set. + +**Flags** +The following flags can be combined by the OR operator to indicate whether the GUID maps to an OID or to an NDIS\_STATUS string and to indicate the type of data that is supplied for the GUID: + +fNDIS\_GUID\_TO\_OID +Indicates that the NDIS\_GUID structure maps a GUID to an OID. + +fNDIS\_GUID\_TO\_STATUS +Indicates that the NDIS\_GUID structure maps a GUID to an NDIS\_STATUS string. + +fNDIS\_GUID\_ANSI\_STRING +Indicates that a null-terminated ANSI string is supplied for the GUID. + +fNDIS\_GUID\_UNICODE\_STRING +Indicates that a Unicode string is supplied for the GUID. + +fNDIS\_GUID\_ARRAY +Indicates that an array of data items is supplied for the GUID. The specified **Size** indicates the length of each data item in the array. + +fNDIS\_GUID\_ALLOW\_READ +When set, indicates that all users are allowed to use this GUID to obtain information. + +fNDIS\_GUID\_ALLOW\_WRITE +When set, indicates that all users are allowed to use this GUID to set information. + +**Note**   +By default, custom WMI GUIDs supplied by a miniport driver are only accessible to users with administrator privileges. A user with administrator privileges can always read or write to a custom GUID if the miniport driver supports the read or write operation for that GUID. Set the fNDIS\_GUID\_ALLOW\_READ and fNDIS\_GUID\_ALLOW\_WRITE flags to allow all users to access a custom GUID. + +  + +Note that all custom GUIDs registered by a miniport driver must set either fNDIS\_GUID\_TO\_OID or fNDIS\_GUID\_TO\_STATUS (never set both). All other flags may be combined by using the OR operator as applicable. + +In the following example, an NDIS\_GUID structure maps a GUID to OID\_802\_3\_MULTICAST\_LIST: + +``` +NDIS_GUID NdisGuid = {{0x44795701, 0xa61b, 0x11d0, 0x8d, 0xd4, + 0x00, 0xc0, 0x4f, 0xc3, + 0x35, 0x8c}, + OID_802_3_MULTICAST_LIST, + 6, + fNDIS_GUID_TO_OID | fNDIS_GUID_ARRAY}; +``` + +A GUID is an identifier used by Windows Management Instrumentation (WMI) to obtain or set information. NDIS intercepts a GUID sent by WMI to an NDIS driver, it maps the GUID to an OID, and sends the OID to the driver. The driver returns the data items to NDIS, which then returns the data to WMI. + +NDIS also translates changes in NIC status into GUIDs that are recognized by WMI. When a miniport driver reports a change in NIC status using the [**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) function, NDIS translates the NDIS\_STATUS indicated by the miniport driver into a GUID that NDIS sends to WMI. + +If a miniport driver supports customs GUIDs, it must support OID\_GEN\_SUPPORTED\_GUIDS. This OID returns to NDIS the mapping of custom GUIDs to custom OIDs or NDIS\_STATUS strings. After querying the miniport driver using OID\_GEN\_SUPPORTED\_GUIDS, NDIS registers the miniport driver's custom GUIDs with WMI. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMIndicateStatusEx**](https://msdn.microsoft.com/library/windows/hardware/ff563600) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_SUPPORTED_GUIDS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-supported-list.md b/windows-driver-docs-pr/network/oid-gen-supported-list.md new file mode 100644 index 0000000000..9c7fde2e04 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-supported-list.md @@ -0,0 +1,77 @@ +--- +title: OID\_GEN\_SUPPORTED\_LIST +author: windows-driver-content +description: As a query, the OID\_GEN\_SUPPORTED\_LIST OID specifies an array of OIDs for objects that the miniport driver or a NIC supports. +ms.assetid: 4e663204-eee0-4732-83c9-ec1dacd41034 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_SUPPORTED_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_SUPPORTED\_LIST + + +As a query, the OID\_GEN\_SUPPORTED\_LIST OID specifies an array of OIDs for objects that the miniport driver or a NIC supports. Objects include general, media-specific, and implementation-specific objects. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. + +NDIS 5.1 miniport drivers +Mandatory. See [OID\_GEN\_SUPPORTED\_LIST (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff560258). + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. See [OID\_GEN\_SUPPORTED\_LIST (NDIS 5.1)](https://msdn.microsoft.com/library/windows/hardware/ff560258). + +Remarks +------- + +NDIS 6.0 and later miniport drivers do not receive this OID request. NDIS handles this OID with a cached value that miniport drivers supply during initialization. + +NDIS forwards a subset of the provided list to protocol drivers that make this query. That is, NDIS filters any supported statistics OIDs out of the list because protocol drivers never make statistics queries. + +If a miniport driver lists an OID in its supported OIDs list, it must fully support the OID. That is, the miniport driver must return valid data when it responds to a query or set request for the OIDs that it includes in the list. For example, the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) OID is a required OID for NDIS 6.0 and later miniport drivers. If a miniport driver does not support the statistics in hardware or software and returns incorrect statistics information, the driver cannot specify OID\_GEN\_STATISTICS in its supported OIDs list. + +Duplicates might appear in the supported OIDs list. Drivers are not required to guarantee that there is only one entry for each OID in the list. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_SUPPORTED_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-supported-packet-filters.md b/windows-driver-docs-pr/network/oid-gen-supported-packet-filters.md new file mode 100644 index 0000000000..b78d23d189 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-supported-packet-filters.md @@ -0,0 +1,78 @@ +--- +title: OID\_GEN\_SUPPORTED\_PACKET\_FILTERS +author: windows-driver-content +description: NDIS and overlying drivers obtain the types of net packets that the miniport adapter can filter during initialization. +ms.assetid: c19cecf3-ae47-4fd1-b5dc-1f3de469e548 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_SUPPORTED_PACKET_FILTERS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_SUPPORTED\_PACKET\_FILTERS + + +NDIS and overlying drivers obtain the types of net packets that the miniport adapter can filter during initialization. + +**Note**  This OID is not implemented in the Windows Vista and later versions of Windows operating system. For more information, see the Remarks section. + +  + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not implemented. (See Remarks section.) + +Remarks +------- + +Miniport drivers supply the supported packet filters during initialization. + +To specify the supported packet filters, a miniport driver sets the **SupportedPacketFilters** member of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure and passes the structure to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +NDIS passes the information to protocol drivers in the **SupportedPacketFilters** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure. + +The values in **SupportedPacketFilters** are a bitwise OR of the filter type flags. For a list of the filter type flags, see the [OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) OID. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[OID\_GEN\_CURRENT\_PACKET\_FILTER](oid-gen-current-packet-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_SUPPORTED_PACKET_FILTERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-transmit-block-size.md b/windows-driver-docs-pr/network/oid-gen-transmit-block-size.md new file mode 100644 index 0000000000..36107db4fc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-transmit-block-size.md @@ -0,0 +1,68 @@ +--- +title: OID\_GEN\_TRANSMIT\_BLOCK\_SIZE +author: windows-driver-content +description: As a query, the OID\_GEN\_TRANSMIT\_BLOCK\_SIZE OID specifies the minimum number of bytes that a single net packet occupies in the transmit buffer space of the NIC. +ms.assetid: 81874999-029a-4e7e-8dbe-fc8e34bcae67 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_TRANSMIT_BLOCK_SIZE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_TRANSMIT\_BLOCK\_SIZE + + +As a query, the OID\_GEN\_TRANSMIT\_BLOCK\_SIZE OID specifies the minimum number of bytes that a single net packet occupies in the transmit buffer space of the NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The OID\_GEN\_TRANSMIT\_BLOCK\_SIZE OID specifies the minimum number of bytes that a single net packet occupies in the transmit buffer space of the NIC. For example, a NIC that has a transmit space divided into 256-byte pieces would have a transmit block size of 256 bytes. To calculate the total transmit buffer space on such a NIC, its driver multiplies the number of transmit buffers on the NIC by its transmit block size. + +For other NICs, the transmit block size is identical to its maximum packet size. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_TRANSMIT_BLOCK_SIZE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-transmit-buffer-space.md b/windows-driver-docs-pr/network/oid-gen-transmit-buffer-space.md new file mode 100644 index 0000000000..5a1c247e1d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-transmit-buffer-space.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_TRANSMIT\_BUFFER\_SPACE +author: windows-driver-content +description: As a query, the OID\_GEN\_TRANSMIT\_BUFFER\_SPACE OID specifies the amount of memory, in bytes, on the NIC that is available for buffering transmit data. +ms.assetid: 23d242fc-8447-4660-ab84-b8cbdb638a71 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_TRANSMIT_BUFFER_SPACE Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_TRANSMIT\_BUFFER\_SPACE + + +As a query, the OID\_GEN\_TRANSMIT\_BUFFER\_SPACE OID specifies the amount of memory, in bytes, on the NIC that is available for buffering transmit data. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +A protocol can use this OID as a guide for sizing the amount of transmit data per send. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_TRANSMIT_BUFFER_SPACE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-transmit-queue-length.md b/windows-driver-docs-pr/network/oid-gen-transmit-queue-length.md new file mode 100644 index 0000000000..ef3fbe6fe6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-transmit-queue-length.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_TRANSMIT\_QUEUE\_LENGTH +author: windows-driver-content +description: As a query, the OID\_GEN\_TRANSMIT\_QUEUE\_LENGTH OID specifies the number of packets that are currently queued for transmission, whether on the NIC or in a driver-internal queue. +ms.assetid: 042a7df3-a204-45f8-b147-96def7438b4a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_TRANSMIT_QUEUE_LENGTH Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_TRANSMIT\_QUEUE\_LENGTH + + +As a query, the OID\_GEN\_TRANSMIT\_QUEUE\_LENGTH OID specifies the number of packets that are currently queued for transmission, whether on the NIC or in a driver-internal queue. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later drivers +Optional. + +NDIS 5.1 drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 drivers +Optional. + +Remarks +------- + +For queries, the number returned is always the total number of packets currently queued. This number can include unsubmitted send requests queued in the NDIS library. + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_TRANSMIT_QUEUE_LENGTH%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-transport-header-offset.md b/windows-driver-docs-pr/network/oid-gen-transport-header-offset.md new file mode 100644 index 0000000000..c3cf992a88 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-transport-header-offset.md @@ -0,0 +1,108 @@ +--- +title: OID\_GEN\_TRANSPORT\_HEADER\_OFFSET +author: windows-driver-content +description: As a set, the OID\_GEN\_TRANSPORT\_HEADER\_OFFSET OID indicates the size of additional headers for packets that a particular transport sends and receives. +ms.assetid: 00b00c5b-cdf3-4b87-8914-e87876c9ae23 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_TRANSPORT_HEADER_OFFSET Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_TRANSPORT\_HEADER\_OFFSET + + +As a set, the OID\_GEN\_TRANSPORT\_HEADER\_OFFSET OID indicates the size of additional headers for packets that a particular transport sends and receives. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +A transport informs miniport drivers and other layered drivers of this header size; these drivers can then use this information when processing packets. For example, a driver could use the sublayer header size obtained from the transport to locate the beginning of higher layer information in packets, such as the start of the IP header; the driver could then parse and adjust the fields of the IP protocol header as appropriate. Transports use a TRANSPORT\_HEADER\_OFFSET structure, defined as follows, to indicate this header size. + +``` +typedef struct _TRANSPORT_HEADER_OFFSET { + USHORT ProtocolType; + USHORT HeaderOffset; +} TRANSPORT_HEADER_OFFSET, *PTRANSPORT_HEADER_OFFSET; +``` + +The members of this structure contain the following information: + +**ProtocolType** +Specifies the protocol type that sends this OID and that subsequently sends and receives packets using the specified sublayer header size. The protocol is one of the following values: + +NDIS\_PROTOCOL\_ID\_DEFAULT +Default protocol + +NDIS\_PROTOCOL\_ID\_TCP\_IP +TCP/IP protocol + +NDIS\_PROTOCOL\_ID\_IPX +NetWare IPX protocol + +NDIS\_PROTOCOL\_ID\_NBF +NetBIOS protocol + +**HeaderOffset** +Specifies the size, in bytes, of the sublayer header that precedes the protocol header for packets that the protocol subsequently sends to or receives from the miniport driver or other layered driver. For example, sizeof(Ethernet header) + sizeof(SNAP header). + +Typically, transports calculate the header size of packets from information that is retrieved from miniport drivers. To request the maximum total packet size in bytes that a NIC supports, including the header, transports use the [OID\_GEN\_MAXIMUM\_TOTAL\_SIZE](oid-gen-maximum-total-size.md) OID. To request the maximum packet size in bytes that a NIC supports, not including a header, transports use the [OID\_GEN\_MAXIMUM\_FRAME\_SIZE](oid-gen-maximum-frame-size.md) OID. To calculate the maximum header size, transports subtract the maximum frame size from the maximum total size. + +If a transport transmits packets that contain sublayer header information, the transport must know the sublayer header size of these packets and must inform underlying miniport drivers and other layered drivers about the size so that the drivers can process the packets. Sending and receiving particular sublayer header information within a packet may be an option that can be set in the registry for a particular protocol. Transports could then obtain information about sublayer headers from the registry and pass the header size down to miniport drivers or other layered drivers. + +For example, if a transport handles packets from the Fiber Distributed Data Interface medium, the transport must send a set request to underlying miniport drivers and other layered drivers using OID\_GEN\_TRANSPORT\_HEADER\_OFFSET to inform those drivers about the size of the packets' sublayer header. (FDDI is not supported in Windows Vista and later versions of Windows.) These packets from FDDI could contain Logical Link Control (LLC) information. This LLC information could in turn include an LLC header and other headers such as Sub-Network Access Protocol (SNAP). The transport determines from the registry to use LLC/SNAP and passes the header size of the LLC/SNAP segments of packets to miniport drivers. + +This OID is optional for miniport drivers and other layered drivers. Because this OID is optional, drivers are not required to respond to requests that transports make using this OID. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_MAXIMUM\_FRAME\_SIZE](oid-gen-maximum-frame-size.md) + +[OID\_GEN\_MAXIMUM\_TOTAL\_SIZE](oid-gen-maximum-total-size.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_TRANSPORT_HEADER_OFFSET%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-unknown-protos.md b/windows-driver-docs-pr/network/oid-gen-unknown-protos.md new file mode 100644 index 0000000000..86e2248bef --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-unknown-protos.md @@ -0,0 +1,66 @@ +--- +title: OID\_GEN\_UNKNOWN\_PROTOS +author: windows-driver-content +description: As a query, use the OID\_GEN\_UNKNOWN\_PROTOS OID to determine the unknown-protocol packet count of a network interface (ifInUnknownProtos from RFC 2863). +ms.assetid: a0bebd8d-c202-41f5-84be-a3056a2eeef9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_UNKNOWN_PROTOS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_UNKNOWN\_PROTOS + + +As a query, use the OID\_GEN\_UNKNOWN\_PROTOS OID to determine the unknown-protocol packet count of a network interface (*ifInUnknownProtos* from [RFC 2863](http://go.microsoft.com/fwlink/p/?linkid=84054)). + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +The unknown-protocol statistics counter specifies the number of packets that were received through the interface that were discarded because the associated protocol was unknown or unsupported. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is a ULONG64 value that specifies the number of packets. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_UNKNOWN_PROTOS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-vendor-id.md b/windows-driver-docs-pr/network/oid-gen-vendor-id.md new file mode 100644 index 0000000000..0b787efce5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-vendor-id.md @@ -0,0 +1,70 @@ +--- +title: OID\_GEN\_VENDOR\_ID +author: windows-driver-content +description: As a query, the OID\_GEN\_VENDOR\_ID OID specifies a three-byte IEEE-registered vendor code, followed by a single byte that the vendor assigns to identify a particular NIC. +ms.assetid: dce0a2e4-5d34-417f-9764-85644fe2ce46 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_VENDOR_ID Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_VENDOR\_ID + + +As a query, the OID\_GEN\_VENDOR\_ID OID specifies a three-byte IEEE-registered vendor code, followed by a single byte that the vendor assigns to identify a particular NIC. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Mandatory. + +NDIS 5.1 miniport drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Mandatory. + +Remarks +------- + +The IEEE code uniquely identifies the vendor and is the same as the three bytes appearing at the beginning of the NIC hardware address. + +Vendors without an IEEE-registered code should use the value 0xFFFFFF. + +Independent hardware vendor's filter drivers or intermediate drivers might query this OID. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_VENDOR_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-vlan-id.md b/windows-driver-docs-pr/network/oid-gen-vlan-id.md new file mode 100644 index 0000000000..b8b0ba5f77 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-vlan-id.md @@ -0,0 +1,81 @@ +--- +title: OID\_GEN\_VLAN\_ID +author: windows-driver-content +description: As a query, the OID\_GEN\_VLAN\_ID OID reports the configured VLAN identifier (ID) for a NIC. +ms.assetid: 4e024951-a578-4f69-873d-879aecc96e68 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_VLAN_ID Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_VLAN\_ID + + +As a query, the OID\_GEN\_VLAN\_ID OID reports the configured VLAN identifier (ID) for a NIC. + +As a set, the OID\_GEN\_VLAN\_ID OID specifies the configured VLAN identifier (ID) for an NIC that the miniport driver handles. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Optional. + +NDIS 5.1 miniport drivers +Optional. + +Windows XP +Supported. + +NDIS 5.1 miniport drivers +Optional. + +Remarks +------- + +The information buffer passed in this request contains an NDIS\_VLAN\_ID data type. This NDIS\_VLAN\_ID value contains the VLAN ID in the 12 least significant bits per the IEEE 802.1Q-2005 standard. Higher order bits of the NDIS\_VLAN\_ID value are reserved and must be set to 0. Note that NDIS defines NDIS\_VLAN\_ID as a ULONG. + +When a transport uses OID\_GEN\_VLAN\_ID in a query, the miniport driver returns the current configured VLAN ID for the NIC. When used in a set, the miniport driver sets the NIC's current configured VLAN ID to the specified value. + +During the miniport driver's [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function for a particular NIC, the driver initially sets the NIC's VLAN ID to zero. The driver's *MiniportInitializeEx* function then reads the following configuration parameter from the registry, and, if the parameter is present, sets the NIC's VLAN ID to the parameter's value. + +``` +VlanId, REG_DWORD +``` + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_VLAN_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-xmit-discards.md b/windows-driver-docs-pr/network/oid-gen-xmit-discards.md new file mode 100644 index 0000000000..162cc9dd92 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-xmit-discards.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_XMIT\_DISCARDS +author: windows-driver-content +description: As a query, NDIS and overlying drivers use the OID\_GEN\_XMIT\_DISCARDS OID to determine the number of transmit discards on a miniport adapter. +ms.assetid: f6265262-c485-441c-bb89-fa1d302608d2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_XMIT_DISCARDS Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_XMIT\_DISCARDS + + +As a query, NDIS and overlying drivers use the OID\_GEN\_XMIT\_DISCARDS OID to determine the number of transmit discards on a miniport adapter. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. (see Remarks section) + +Remarks +------- + +NDIS handles this OID for miniport drivers. See the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) OID for more information about statistics. + +The count that this OID returns is the number of packets that is discarded by the interface. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_XMIT_DISCARDS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-xmit-error.md b/windows-driver-docs-pr/network/oid-gen-xmit-error.md new file mode 100644 index 0000000000..181ba083b1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-xmit-error.md @@ -0,0 +1,71 @@ +--- +title: OID\_GEN\_XMIT\_ERROR +author: windows-driver-content +description: As a query, the OID\_GEN\_XMIT\_ERROR OID specifies the number of frames that a NIC fails to transmit. +ms.assetid: c4f42271-812b-4da9-8280-79d3bddc5164 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_XMIT_ERROR Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_XMIT\_ERROR + + +As a query, the OID\_GEN\_XMIT\_ERROR OID specifies the number of frames that a NIC fails to transmit. + +**Version Information** + +Windows Vista and later versions of Windows +Obsolete. + +NDIS 6.0 and later drivers +Not requested. Use [OID\_GEN\_STATISTICS](oid-gen-statistics.md) instead. + +NDIS 5.1 drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 drivers +Mandatory. + +Remarks +------- + +For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_XMIT_ERROR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-xmit-link-speed.md b/windows-driver-docs-pr/network/oid-gen-xmit-link-speed.md new file mode 100644 index 0000000000..4b905f0adb --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-xmit-link-speed.md @@ -0,0 +1,64 @@ +--- +title: OID\_GEN\_XMIT\_LINK\_SPEED +author: windows-driver-content +description: As a query, use the OID\_GEN\_XMIT\_LINK\_SPEED OID to determine the transmit link speed of a network interface. Version Information Windows Vista and laterSupported. NDIS 6.0 and later miniport driversNot requested. For NDIS interface providers only. +ms.assetid: 0a390456-8974-4668-b624-55259c2f9e20 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_XMIT_LINK_SPEED Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_XMIT\_LINK\_SPEED + + +As a query, use the OID\_GEN\_XMIT\_LINK\_SPEED OID to determine the transmit link speed of a network interface. + +**Version Information** + +Windows Vista and later +Supported. + +NDIS 6.0 and later miniport drivers +Not requested. For NDIS interface providers only. + +Remarks +------- + +Only [NDIS network interface](https://msdn.microsoft.com/library/windows/hardware/ff566527) providers, and therefore not miniport drivers or filter drivers, must support this OID as an OID request. + +If the interface provider returns NDIS\_STATUS\_SUCCESS, the result of the query is a ULONG64 value that indicates the transmit link speed of the interface, in bits per second. + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS Network Interface OIDs](https://msdn.microsoft.com/library/windows/hardware/ff566545) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_XMIT_LINK_SPEED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-gen-xmit-ok.md b/windows-driver-docs-pr/network/oid-gen-xmit-ok.md new file mode 100644 index 0000000000..d81f4525c9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-gen-xmit-ok.md @@ -0,0 +1,73 @@ +--- +title: OID\_GEN\_XMIT\_OK +author: windows-driver-content +description: As a query, the OID\_GEN\_XMIT\_OK OID specifies the number of frames that are transmitted without errors. +ms.assetid: ac7120a3-58bb-4047-b4b7-ad9fbaf14e4f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_GEN_XMIT_OK Network Drivers Starting with Windows Vista +--- + +# OID\_GEN\_XMIT\_OK + + +As a query, the OID\_GEN\_XMIT\_OK OID specifies the number of frames that are transmitted without errors. + +**Version Information** + +Windows Vista and later versions of Windows +Supported. + +NDIS 6.0 and later drivers +Mandatory. + +NDIS 5.1 drivers +Mandatory. + +Windows XP +Supported. + +NDIS 5.1 drivers +Mandatory. + +Remarks +------- + +OID\_GEN\_XMIT\_OK specifies the number of frames that are transmitted without errors. However, the [OID\_GEN\_STATISTICS](oid-gen-statistics.md) does not include this information. + +NOTE: Statistics OIDs are mandatory for NDIS 6.0 and later miniport drivers unless NDIS handles them. For general information about statistics OIDs, see [General Statistics](https://msdn.microsoft.com/library/windows/hardware/ff552485). + +Requirements +------------ + + ++++ + + + + + + +

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_GEN\_STATISTICS](oid-gen-statistics.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_GEN_XMIT_OK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-ndk-connections.md b/windows-driver-docs-pr/network/oid-ndk-connections.md new file mode 100644 index 0000000000..5a9453c3cf --- /dev/null +++ b/windows-driver-docs-pr/network/oid-ndk-connections.md @@ -0,0 +1,72 @@ +--- +title: OID\_NDK\_CONNECTIONS +author: windows-driver-content +description: As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_CONNECTIONS OID to query the list of active Network Direct connections from the miniport adapter. +ms.assetid: 31A0BB2B-B571-4548-A9D1-BE44687DEA37 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NDK_CONNECTIONS Network Drivers Starting with Windows Vista +--- + +# OID\_NDK\_CONNECTIONS + + +As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_CONNECTIONS OID to query the list of active Network Direct connections from the miniport adapter. + +NDIS 6.30 and later miniport drivers that provide NDK services must support this OID. Otherwise, this OID is optional. + +Remarks +------- + +NDIS issues this OID to obtain the list of active Network Direct connections from an adapter. The adapter must return the list of connections with the [**NDIS\_NDK\_CONNECTIONS**](https://msdn.microsoft.com/library/windows/hardware/hh451561) structure at the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +This structure is variable-sized based on the number of connections that are returned. The size of the connection array, as element count, is specified in the **Count** member. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

None supported

Minimum supported server

Windows Server 2012

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NDK\_CONNECTIONS**](https://msdn.microsoft.com/library/windows/hardware/hh451561) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NDK_CONNECTIONS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-ndk-local-endpoints.md b/windows-driver-docs-pr/network/oid-ndk-local-endpoints.md new file mode 100644 index 0000000000..afbce83de3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-ndk-local-endpoints.md @@ -0,0 +1,72 @@ +--- +title: OID\_NDK\_LOCAL\_ENDPOINTS +author: windows-driver-content +description: As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_LOCAL\_ENDPOINTS OID to the list of active Network Direct listeners and shared endpoints on a miniport adapter. +ms.assetid: 93F077AF-7FEA-4F92-9784-B65ADCC16564 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NDK_LOCAL_ENDPOINTS Network Drivers Starting with Windows Vista +--- + +# OID\_NDK\_LOCAL\_ENDPOINTS + + +As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_LOCAL\_ENDPOINTS OID to the list of active Network Direct listeners and shared endpoints on a miniport adapter. + +NDIS 6.30 and later miniport drivers that provide NDK services must support this OID. Otherwise, this OID is optional. + +Remarks +------- + +NDIS issues this OID to obtain the list of active Network Direct listeners and shared endpoints from an adapter. The adapter is required to return the list of listeners and shared endpoints in the [**NDIS\_NDK\_LOCAL\_ENDPOINTS**](https://msdn.microsoft.com/library/windows/hardware/hh451563) structure at **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +This structure is variable-sized based on the number of local endpoints that are returned. The size of the local endpoint array, as element count, is specified in the **Count** member. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

None supported

Minimum supported server

Windows Server 2012

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_NDK\_LOCAL\_ENDPOINTS**](https://msdn.microsoft.com/library/windows/hardware/hh451563) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NDK_LOCAL_ENDPOINTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-ndk-set-state.md b/windows-driver-docs-pr/network/oid-ndk-set-state.md new file mode 100644 index 0000000000..0f37ba2762 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-ndk-set-state.md @@ -0,0 +1,100 @@ +--- +title: OID\_NDK\_SET\_STATE +author: windows-driver-content +description: As a set request, NDIS and overlying drivers use the OID\_NDK\_SET\_STATE OID to set the state of the miniport adapter's NDK functionality. +ms.assetid: 5BA49F42-FE37-4860-B68F-92A7F4007639 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NDK_SET_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_NDK\_SET\_STATE + + +As a set request, NDIS and overlying drivers use the OID\_NDK\_SET\_STATE OID to set the state of the miniport adapter's NDK functionality. + +NDIS 6.30 and later miniport drivers that provide NDK services must support this OID. Otherwise, this OID is optional. + +Remarks +------- + +NDIS issues this OID with the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure pointing to a **BOOLEAN** and **InformationBufferLength** member equal to sizeof(**BOOLEAN**). + +- If the **BOOLEAN** value is **TRUE** and the **\*NetworkDirect** keyword value is nonzero, the miniport adapter's NDK functionality must be enabled. + + The miniport driver can read the **\*NetworkDirect** keyword value by doing the following: + + 1. Call [**NdisOpenConfigurationEx**](https://msdn.microsoft.com/library/windows/hardware/ff563717) with the NDIS handle that the [**NdisMRegisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563654) function returned when the miniport driver was initialized. For more information about calling **NdisOpenConfigurationEx**, see [Reading the Registry in an NDIS 6.0 Miniport Driver](https://msdn.microsoft.com/library/windows/hardware/ff570429). + + 2. Call [**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511), passing: + + - "\*NetworkDirect" for the *Keyword* parameter + + - **NdisParameterInteger** for the *ParameterType* parameter + +- If the **BOOLEAN** value is **FALSE**, the NDK functionality of the miniport adapter must be disabled. + +To enable or disable its NDK functionality, the miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) callback function should follow the steps in [Enabling and Disabling NDK Functionality](https://msdn.microsoft.com/library/windows/hardware/dn163547). + +**Note**  An NDK-capable miniport driver must never call [**NdisMNetPnPEvent**](https://msdn.microsoft.com/library/windows/hardware/ff563616) from the context of its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function, because doing so could cause a deadlock. Instead, it should call **NdisMNetPnPEvent** from some other context or queue a work item. + +  + +An NDK-capable miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function must return **STATUS\_SUCCESS** for an OID\_NDK\_SET\_STATE OID request unless a failure occurs. The driver must not return **NDIS\_STATUS\_PENDING**. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

None supported

Minimum supported server

Windows Server 2012

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisMNetPnPEvent**](https://msdn.microsoft.com/library/windows/hardware/ff563616) + +[**NdisQueueIoWorkItem**](https://msdn.microsoft.com/library/windows/hardware/ff563775) + +[**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511) + +[**NDK\_ADAPTER**](https://msdn.microsoft.com/library/windows/hardware/hh439848) + +[OID\_NDK\_SET\_STATE](oid-ndk-set-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NDK_SET_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-ndk-statistics.md b/windows-driver-docs-pr/network/oid-ndk-statistics.md new file mode 100644 index 0000000000..915267a3ed --- /dev/null +++ b/windows-driver-docs-pr/network/oid-ndk-statistics.md @@ -0,0 +1,84 @@ +--- +title: OID\_NDK\_STATISTICS +author: windows-driver-content +description: As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_STATISTICS OID to get the NDK statistics of a miniport adapter. +ms.assetid: 30F16DEC-AEE6-49D4-8599-95374ACBD446 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NDK_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_NDK\_STATISTICS + + +As a query, NDIS and overlying drivers or user-mode applications use the OID\_NDK\_STATISTICS OID to get the NDK statistics of a miniport adapter. + +NDIS 6.30 and later miniport drivers that provide NDK services must support this OID. Otherwise, this OID is optional. + +**Note**  NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +Remarks +------- + +NDIS issues this OID with the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure pointing to an [**NDIS\_NDK\_STATISTICS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451567) structure. + +The NDK-capable miniport driver must provide the **CounterSet** member, which is a [**NDIS\_NDK\_PERFORMANCE\_COUNTERS**](https://msdn.microsoft.com/library/windows/hardware/hh451565) structure. + +The counters are published to tools such as [perfmon](http://technet.microsoft.com/library/cc731067.aspx) (see the [NetworkDirect Activity](http://technet.microsoft.com/library/hh997022.aspx) performance counter) and made available programmatically with the Performance Data Helper (PDH) and Performance Library (PERFLIB) programming interfaces. For more information about these interfaces, see [Performance Counters](https://msdn.microsoft.com/library/windows/desktop/aa373083). + +These counters are also available by calling the [Get-NetAdapterStatistics](http://technet.microsoft.com/library/jj130889) PowerShell cmdlet with the **RdmaStatistics** attribute. For more information about the **RdmaStatistics** attribute, see [**MSFT\_NetAdapterStatisticsSettingData**](https://msdn.microsoft.com/library/hh872390). + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

None supported

Minimum supported server

Windows Server 2012

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[Kernel Mode Performance Monitoring](https://msdn.microsoft.com/library/windows/hardware/ff548159) + +[**NDIS\_NDK\_PERFORMANCE\_COUNTERS**](https://msdn.microsoft.com/library/windows/hardware/hh451565) + +[**NDIS\_NDK\_STATISTICS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451567) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NDK_STATISTICS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-allocate-vf.md b/windows-driver-docs-pr/network/oid-nic-switch-allocate-vf.md new file mode 100644 index 0000000000..acddcd36fa --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-allocate-vf.md @@ -0,0 +1,118 @@ +--- +title: OID\_NIC\_SWITCH\_ALLOCATE\_VF +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ALLOCATE\_VF to allocate resources for a PCI Express (PCIe) Virtual Function (VF). +ms.assetid: CB88CE0C-705F-406B-90FE-FB206D6F4864 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_ALLOCATE_VF Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_ALLOCATE\_VF + + +An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ALLOCATE\_VF to allocate resources for a PCI Express (PCIe) Virtual Function (VF). The VF is exposed on a network adapter that supports the single root I/O virtualization (SR-IOV) interface. + +Overlying drivers issue this OID method request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure. + +Remarks +------- + +The PF miniport driver allocates software resources for a VF when the driver handles an object identifier (OID) method request of OID\_NIC\_SWITCH\_ALLOCATE\_VF. Even though the hardware resources have been allocated for a VF, it is considered to be nonoperational until the PF miniport driver successfully completes the OID\_NIC\_SWITCH\_ALLOCATE\_VF. + +For more information about how to allocate VF resources, see [Allocating Resources for a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh439285). + +**Note**  After an overlying driver requests resource allocation for a VF, that driver is the only component that can request the freeing of the resources for the same VF. The overlying driver must issue an OID set request of [OID\_NIC\_SWITCH\_FREE\_VF](oid-nic-switch-free-vf.md) to free the VF resources. Before the overlying driver can be halted, it must free the resources for each VF that was allocated by the driver's OID\_NIC\_SWITCH\_ALLOCATE\_VF request. + +  + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID method request of OID\_NIC\_SWITCH\_ALLOCATE\_VF. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451593)). The PF miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_MAKE\_RID**](https://msdn.microsoft.com/library/windows/hardware/hh451557) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +[**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) + +[OID\_NIC\_SWITCH\_FREE\_VF](oid-nic-switch-free-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_ALLOCATE_VF%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-create-switch.md b/windows-driver-docs-pr/network/oid-nic-switch-create-switch.md new file mode 100644 index 0000000000..d9536c3366 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-create-switch.md @@ -0,0 +1,148 @@ +--- +title: OID\_NIC\_SWITCH\_CREATE\_SWITCH +author: windows-driver-content +description: NDIS issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH to create a NIC switch on a network adapter. +ms.assetid: 16FFC6A4-11A6-45A1-ABCF-8C1EBE3FD953 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_CREATE_SWITCH Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_CREATE\_SWITCH + + +NDIS issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH to create a NIC switch on a network adapter. When it handles this OID request, the miniport driver allocates the resources for the NIC switch on the adapter. + +NDIS issues this OID method request to the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +**Note**  Overlying drivers, such as protocol or filter drivers, cannot issue OID method requests of OID\_NIC\_SWITCH\_CREATE\_SWITCH to the PF miniport driver. + +  + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure. + +Remarks +------- + +When it receives the OID method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH, the PF miniport driver must do the following: + +1. If the PF miniport driver supports static switch creation and configuration, it creates the NIC switch when NDIS calls [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389). When the driver handles this OID request, it must verify the configuration parameters in the [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure. The parameters must be the same as those used by the driver to create the switch during the call to *MiniportInitializeEx*. If this is not true, the driver must fail the OID request. + + For more information, see [Static Creation of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh440256). + +2. If the PF miniport driver supports dynamic switch creation and configuration, the driver must validate the configuration values of the [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure and create the NIC switch based on these values. + + For more information, see [Dynamic Creation of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh406694). + +3. The PF miniport driver must allocate the necessary hardware and software resources for the default VPort on the NIC switch. + + **Note**  The default VPort is always created through an OID request of OID\_NIC\_SWITCH\_CREATE\_SWITCH and deleted through an OID request of [OID\_NIC\_SWITCH\_DELETE\_SWITCH](oid-nic-switch-delete-switch.md). OID requests of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) and [OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) are used for the creation and deletion of nondefault VPorts on the NIC switch. + +   + +4. The PF miniport driver that supports dynamic switch creation and configuration must enable SR-IOV virtualization on the switch by calling [**NdisMEnableVirtualization**](https://msdn.microsoft.com/library/windows/hardware/hh451481). This call configures the **NumVFs** member and the **VF Enable** bit in the SR-IOV Extended Capability structure of the adapter's PCI Express (PCIe) configuration space. + + For more information about the SR-IOV configuration space, see the PCI-SIG [Single Root I/O Virtualization and Sharing 1.1](http://go.microsoft.com/fwlink/p/?linkid=221742) specification. + + **Note**  If the PF miniport driver supports static switch creation, it enables SR-IOV virtualization after it creates the switch when [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) is called. + +   + +If the PF miniport driver successfully completes the OID method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH, it allows the following to occur: + +- VFs can be allocated on the NIC switch through OID method requests of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + +- Nondefault VPorts can be created on the NIC switch through OID method requests of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md). + +For more information on how to handle this OID request, see [Handling the OID\_NIC\_SWITCH\_CREATE\_SWITCH Request](https://msdn.microsoft.com/library/windows/hardware/hh451370). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the SR-IOV interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451587)). The PF miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) + +[**NdisMEnableVirtualization**](https://msdn.microsoft.com/library/windows/hardware/hh451481) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_CREATE_SWITCH%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-create-vport.md b/windows-driver-docs-pr/network/oid-nic-switch-create-vport.md new file mode 100644 index 0000000000..75b5f8e6a5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-create-vport.md @@ -0,0 +1,136 @@ +--- +title: OID\_NIC\_SWITCH\_CREATE\_VPORT +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_CREATE\_VPORT to create a nondefault virtual port (VPort) on a network adapter's NIC switch. +ms.assetid: 31109117-2242-40E0-B215-0FAE014B2035 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_CREATE_VPORT Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_CREATE\_VPORT + + +An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_CREATE\_VPORT to create a nondefault virtual port (VPort) on a network adapter's NIC switch. This OID method request also attaches the created VPort to the network adapter's PCI Express (PCIe) Physical Function (PF) or a previously allocated PCIe Virtual Function (VF). + +Overlying drivers issue this OID method request to the miniport driver for the network adapter's PF. This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure. + +Remarks +------- + +The overlying driver initializes the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure with the configuration information about the nondefault VPort to be created. The configuration information includes the PCIe function to which the nondefault VPort is attached and the number of queue pairs for the nondefault VPort. + +When the PF miniport driver is issued the OID request, the driver allocates the hardware and software resources associated with the specified nondefault VPort. After all the resources are successfully allocated, the PF miniport driver completes the OID successfully by returning NDIS\_STATUS\_SUCCESS from [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416). + +If the OID\_NIC\_SWITCH\_CREATE\_VPORT request completes successfully, the PF miniport driver and the overlying driver must retain the **VPortId** value of the nondefault VPort for successive operations. The **VPortId** value is used during these operations: + +- NDIS and the overlying drivers use the **VPortId** value to identify the nondefault VPort in successive OID requests related to this VPort, such as [OID\_NIC\_SWITCH\_VPORT\_PARAMETERS](oid-nic-switch-vport-parameters.md) and [OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md). + +- During send operations, NDIS specifies the **VPortId** value to identify the VPort from which a packet was sent. This value is specified within the out-of-band (OOB) [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) data of the [NET\_BUFFER\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568412) structure. + +- During receive operations, the PF miniport driver specifies the **VPortId** value to which a packet is to be forwarded. This value is also specified in the OOB [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) data of the [NET\_BUFFER\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568412) structure. + +For more information, see [Creating a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh439412). + +**Note**  The default VPort always exists and is not created though an OID request of OID\_NIC\_SWITCH\_CREATE\_VPORT. The default VPort has an identifier of NDIS\_DEFAULT\_VPORT\_ID. When the PF miniport driver creates a NIC switch, the driver automatically attaches the default VPort to the PF of the network adapter. + +  + +### Return Status Codes + +NDIS or the PF miniport driver returns one of the following status codes for the OID method request of OID\_NIC\_SWITCH\_CREATE\_SWITCH. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the SR-IOV interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451597)). The PF miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +[**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) + +[**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[NET\_BUFFER\_LIST](https://msdn.microsoft.com/library/windows/hardware/ff568412) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) + +[OID\_NIC\_SWITCH\_PARAMETERS](oid-nic-switch-parameters.md) + +[OID\_NIC\_SWITCH\_VPORT\_PARAMETERS](oid-nic-switch-vport-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_CREATE_VPORT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-current-capabilities.md b/windows-driver-docs-pr/network/oid-nic-switch-current-capabilities.md new file mode 100644 index 0000000000..cb4bd4d360 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-current-capabilities.md @@ -0,0 +1,117 @@ +--- +title: OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES to obtain the currently enabled hardware capabilities of the NIC switch in a network adapter. +ms.assetid: 529dc5d5-9b84-4891-9e7a-1f9f7850c6d7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES to obtain the currently enabled hardware capabilities of the NIC switch in a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure. + +Remarks +------- + +Starting with NDIS 6.20, miniport drivers supply the currently enabled NIC switch hardware capabilities on the network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver initializes an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure with the NIC switch hardware capabilities and sets the **CurrentNicSwitchCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the **NDIS\_NIC\_SWITCH\_CAPABILITIES** structure. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an **NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES** structure. + +**Note**  Starting with NDIS 6.30, miniport drivers that support the single root I/O virtualization (SR-IOV) interface must register the enabled hardware capabilities of the NIC switch. Drivers register these capabilities by calling [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672). + +  + +Overlying protocol and filter drivers do not have to issue OID query requests of OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES. NDIS provides the currently enabled NIC switch hardware capabilities of a network adapter to these drivers in the following way: + +- NDIS reports the currently enabled NIC switch hardware capabilities of an underlying network adapter to overlying protocol drivers in the **NicSwitchCapabilities** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure during the bind operation. + +- NDIS reports the currently enabled NIC switch hardware capabilities of an underlying network adapter to overlying filter drivers in the **NicSwitchCapabilities** member of the [**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) structure during the attach operation. + +### Return Status Codes + +NDIS handles the OID query request of the OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_NIC\_SWITCH\_CURRENT\_CAPABILITIES request, it returns one of the following status codes: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer points to an [NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583)). The miniport driver must set the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-delete-switch.md b/windows-driver-docs-pr/network/oid-nic-switch-delete-switch.md new file mode 100644 index 0000000000..b5989ca836 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-delete-switch.md @@ -0,0 +1,171 @@ +--- +title: OID\_NIC\_SWITCH\_DELETE\_SWITCH +author: windows-driver-content +description: NDIS issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_DELETE\_SWITCH to delete a NIC switch from a network adapter. +ms.assetid: 5785B30F-B67F-4D5A-A93A-243D33B9CAE8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_DELETE_SWITCH Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_DELETE\_SWITCH + + +NDIS issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_DELETE\_SWITCH to delete a NIC switch from a network adapter. + +NDIS issues this OID set request to the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). This OID set request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +**Note**  Overlying drivers, such as protocol or filter drivers, cannot issue this OID method request to the PF miniport driver. + +  + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_DELETE\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451575) structure. + +Remarks +------- + +An OID set request of OID\_NIC\_SWITCH\_DELETE\_SWITCH deletes a NIC switch that was previously created through an OID method request of [OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md). + +When it receives the OID method request of OID\_NIC\_SWITCH\_DELETE\_SWITCH, the PF miniport driver must do the following: + +1. If the PF miniport driver supports static creation and configuration of NIC switches, it must free the software resources associated with the specified NIC switch. However, the driver can only free the hardware resources for the NIC switch when [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) is called. + + For more information about static NIC switch creation, see [Static Creation of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh440256). + +2. If the PF miniport driver supports the dynamic creation and configuration of NIC switches, it must free the hardware and software resources associated with the specified NIC switch. + + For more information about dynamic NIC switch creation, see [Dynamic Creation of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh406694). + +3. If the PF miniport driver supports the dynamic creation and all the NIC switches have been deleted, the driver must disable virtualization on the adapter by calling [**NdisMEnableVirtualization**](https://msdn.microsoft.com/library/windows/hardware/hh451481). To disable virtualization, the network adapter must set the *EnableVirtualization* parameter to FALSE and the *NumVFs* parameter to zero. + + [**NdisMEnableVirtualization**](https://msdn.microsoft.com/library/windows/hardware/hh451481) clears the **NumVFs** member and the **VF Enable** bit in the SR-IOV Extended Capability structure in the PCI configuration space of the network adapter's PF. + + **Note**  If the PF miniport driver supports static creation and configuration of NIC switches, it must only call [**NdisMEnableVirtualization**](https://msdn.microsoft.com/library/windows/hardware/hh451481) when [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) is called. + +   + +For more information, see [Deleting a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh439415). + +### Return Status Codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +NDIS returns one of the following status codes for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the SR-IOV interface or is not enabled to use the interface.

NDIS_STATUS_FILE_NOT_FOUND

One or more of the members of the [NDIS_NIC_SWITCH_DELETE_SWITCH_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451575) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer is too small. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_NIC\_SWITCH\_DELETE\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451575) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) + +[OID\_NIC\_SWITCH\_FREE\_VF](oid-nic-switch-free-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_DELETE_SWITCH%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-delete-vport.md b/windows-driver-docs-pr/network/oid-nic-switch-delete-vport.md new file mode 100644 index 0000000000..735fbfb27b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-delete-vport.md @@ -0,0 +1,120 @@ +--- +title: OID\_NIC\_SWITCH\_DELETE\_VPORT +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_DELETE\_VPORT to delete a nondefault virtual port (VPort) that was previously created on a network adapter's NIC switch. +ms.assetid: D762035C-33AC-4579-8EA0-6A422AE4CA76 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_DELETE_VPORT Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_DELETE\_VPORT + + +An overlying driver issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_DELETE\_VPORT to delete a nondefault virtual port (VPort) that was previously created on a network adapter's NIC switch. The overlying driver can delete a VPort that it has previously created only by issuing an OID method request of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md). + +Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID set request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to the [**NDIS\_NIC\_SWITCH\_DELETE\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451577) structure. + +Remarks +------- + +An overlying driver, such as a protocol or filter driver, can only delete a nondefault VPort that it has previously created. The overlying driver creates a VPort by issuing an OID method request of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md). + +When the PF miniport driver receives the OID request of OID\_NIC\_SWITCH\_DELETE\_VPORT, the driver must free the hardware and software resources that were allocated for the specified VPort. + +For more information, see [Deleting a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh439418). + +**Note**  Only nondefault VPorts can be explicitly deleted through OID requests of OID\_NIC\_SWITCH\_DELETE\_VPORT. The default VPort is implicitly deleted when the PF miniport driver deletes the default NIC switch. For more information, see [Deleting a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh439415). + +  + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID set request of OID\_NIC\_SWITCH\_DELETE\_VPORT. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_DELETE_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451577) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_DELETE_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451577)). The PF miniport driver must set the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_DELETE\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451577) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisCloseAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff561640) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +[OID\_NIC\_SWITCH\_DELETE\_SWITCH](oid-nic-switch-delete-switch.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_DELETE_VPORT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-enum-switches.md b/windows-driver-docs-pr/network/oid-nic-switch-enum-switches.md new file mode 100644 index 0000000000..8e1e8f4594 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-enum-switches.md @@ -0,0 +1,124 @@ +--- +title: OID\_NIC\_SWITCH\_ENUM\_SWITCHES +author: windows-driver-content +description: An overlying driver or user-mode application issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_ENUM\_SWITCHES to obtain an array. +ms.assetid: 706C3F1C-239F-4731-A38E-E150D26C79A5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_ENUM_SWITCHES Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_ENUM\_SWITCHES + + +An overlying driver or user-mode application issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_ENUM\_SWITCHES to obtain an array. Each element in the array specifies the attributes of a NIC switch that has been created on a network adapter. + +After a successful return from this OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer that contains the following: + +- An [**NDIS\_NIC\_SWITCH\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451584) structure that defines the number of elements within the array. + +- An array of [**NDIS\_NIC\_SWITCH\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451582) structures. Each of these structures contains the information about a single NIC switch created on the network adapter. + + **Note**  If the network adapter has no NIC switches, the driver sets the **NumElements** member of the [**NDIS\_NIC\_SWITCH\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451584) structure to zero and no [**NDIS\_NIC\_SWITCH\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451582) structures are returned. + +   + +Remarks +------- + +Overlying drivers and user-mode applications issue OID query requests of OID\_NIC\_SWITCH\_ENUM\_SWITCHES to enumerate the NIC switches created on a network adapter. + +**Note**  Starting with Windows Server 2012, the single root I/O virtualization (SR-IOV) interface only supports the default NIC switch on the network adapter. Therefore, the returned [**NDIS\_NIC\_SWITCH\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451584) structure must specify a single [**NDIS\_NIC\_SWITCH\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451582) element for the default NIC switch, which is referenced by the identifier of NDIS\_DEFAULT\_SWITCH\_ID. + +  + +### Return Status Codes + +NDIS handles the OID query request of the OID\_NIC\_SWITCH\_ENUM\_SWITCHES request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_NIC\_SWITCH\_ENUM\_SWITCHES request, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the SR-IOV interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_INFO_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh451577) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451582) + +[**NDIS\_NIC\_SWITCH\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451584) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_PARAMETERS](oid-nic-switch-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_ENUM_SWITCHES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-enum-vfs.md b/windows-driver-docs-pr/network/oid-nic-switch-enum-vfs.md new file mode 100644 index 0000000000..f8b41cb1b1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-enum-vfs.md @@ -0,0 +1,138 @@ +--- +title: OID\_NIC\_SWITCH\_ENUM\_VFS +author: windows-driver-content +description: An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ENUM\_VFS to obtain an array. +ms.assetid: ABACB70C-9307-4560-93DD-0475AD1FFF10 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_ENUM_VFS Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_ENUM\_VFS + + +An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ENUM\_VFS to obtain an array. Each element in the array specifies the attributes of a PCI Express (PCIe) Virtual Function (VF) that are attached to a NIC switch on a network adapter's NIC switch. + +After a successful return from this OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer that contains the following: + +- An [**NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451592) structure that defines the number of elements within the array. + +- An array of [**NDIS\_NIC\_SWITCH\_VF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451591) structures. Each of these structures contains information about a single VF on a NIC switch of the network adapter. A VF is attached to a NIC switch through OID method requests of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + + **Note**  If no VFs are attached to a NIC switch on the network adapter, the **NumElements** member of the [**NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451592) structure is set to zero and no [**NDIS\_NIC\_SWITCH\_VF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451591) structures are returned. + +   + +Remarks +------- + +Overlying drivers and user-mode applications issue OID method requests of OID\_NIC\_SWITCH\_ENUM\_VFS to enumerate the VFs attached to a network adapter's NIC switch. + +Before the driver or application issues the OID request, it must initialize an [**NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451592) structure that is passed along with the request. The driver or application must follow these guidelines when initializing the **NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY** structure: + +- If the NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY\_ENUM\_ON\_SPECIFIC\_SWITCH flag is set in the **Flags** member, the driver or application must set the **SwitchId** member to the NIC switch identifier on the SR-IOV network adapter. By setting these members in this way, VF information is returned only for the specified NIC switch on the SR-IOV network adapter. + + **Note**  The overlying driver and user-mode application can obtain the NIC switch identifiers by issuing an OID query request of [OID\_NIC\_SWITCH\_ENUM\_SWITCHES](oid-nic-switch-enum-switches.md). + +   + +- If the **Flags** member is set to zero, the driver or application must set the **SwitchId** member to zero. By setting these members in this way, VF information is returned for all NIC switch on the SR-IOV network adapter. + +**Note**  Starting with Windows Server 2012, Windows supports only the default NIC switch on the network adapter. Regardless of the flags set in the **Flags** member, the **SwitchId** member must be set to NDIS\_DEFAULT\_SWITCH\_ID. + +  + +For more information about NIC switches, see [NIC Switches](https://msdn.microsoft.com/library/windows/hardware/hh439961). + +### Return Status Codes + +NDIS handles the OID method request of the OID\_NIC\_SWITCH\_ENUM\_VFS request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_NIC\_SWITCH\_ENUM\_VFS request, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VF_INFO_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh451592) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_VF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451591) + +[**NDIS\_NIC\_SWITCH\_VF\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451592) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_VF\_PARAMETERS](oid-nic-switch-vf-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_ENUM_VFS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-enum-vports.md b/windows-driver-docs-pr/network/oid-nic-switch-enum-vports.md new file mode 100644 index 0000000000..39aac451e5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-enum-vports.md @@ -0,0 +1,140 @@ +--- +title: OID\_NIC\_SWITCH\_ENUM\_VPORTS +author: windows-driver-content +description: An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ENUM\_VPORTS to obtain an array. +ms.assetid: 4B9587E0-3CA9-46AF-A80E-969E6D563922 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_ENUM_VPORTS Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_ENUM\_VPORTS + + +An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_ENUM\_VPORTS to obtain an array. Each element in the array specifies the attributes of a virtual port (VPort) that has been created on a network adapter's NIC switch. + +After a successful return from this OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer that contains the following: + +- An [**NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451595) structure that defines the number of elements within the array. + +- An array of [**NDIS\_NIC\_SWITCH\_VPORT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451594) structures. Each of these structures contains information about a VPort on the network adapter's NIC switch. + + **Note**  If no VPorts have been created on the network adapter, the driver sets the **NumElements** member of the [**NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451595) structure to zero and no [**NDIS\_NIC\_SWITCH\_VPORT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451594) structures are returned. + +   + +Remarks +------- + +Overlying drivers and user-mode applications issue OID query requests of OID\_NIC\_SWITCH\_ENUM\_VPORTS to enumerate the VPorts that are allocated on a network adapter's NIC switch. + +Before the driver or application issues the OID request, it must initialize an [**NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451595) structure that is passed along with the request. The driver or application must follow these guidelines when initializing the **NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY** structure: + +- If the NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY\_ENUM\_ON\_SPECIFIC\_SWITCH flag is set in the **Flags** member, information is retuned for all VPorts created on a specified NIC switch. The NIC switch is specified by the **SwitchId** member of that structure. + + **Note**  Starting with Windows Server 2012, the SR-IOV interface supports only the default NIC switch on the network adapter. Regardless of the flags that are set in the **Flags** member, the **SwitchId** member must be set to NDIS\_DEFAULT\_SWITCH\_ID. + +   + +- If the NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY\_ENUM\_ON\_SPECIFIC\_FUNCTION flag is set in the **Flags** member, information is retuned for all VPorts attached to a specified PCI Express (PCIe) Physical Function (PF) or Virtual Function (VF) on the network adapter. The PF or VF is specified by the **AttachedFunctionId** member of that structure. + + If the **AttachedFunctionId** member is set to NDIS\_PF\_FUNCTION\_ID, information is returned for all VPorts, including the default VPort, that are attached to the network adapter's PF. If the **AttachedFunctionId** member is set to a valid VF identifier, information is returned for all VPorts to the specified VF. + + **Note**  Starting with Windows Server 2012, only one nondefault VPort can be attached to a VF. However, multiple VPorts (including the default VPort) can be attached to the PF. + +   + +- If the **Flags** member is set to zero, information is returned for all VPorts attached to the PF or VF on the network adapter. In this case, the values of the **SwitchId** and **AttachedFunctionId** are ignored. + +For more information, see [Enumerating Virtual Ports on a Network Adapter](https://msdn.microsoft.com/library/windows/hardware/hh406710). + +### Return Status Codes + +NDIS handles the OID method request of the OID\_NIC\_SWITCH\_ENUM\_VPORTS request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_NIC\_SWITCH\_ENUM\_VPORTS request, it returns one of the following status codes: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VF_INFO_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh451592) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_VPORT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451594) + +[**NDIS\_NIC\_SWITCH\_VPORT\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh451595) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_PARAMETERS](oid-nic-switch-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_ENUM_VPORTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-free-vf.md b/windows-driver-docs-pr/network/oid-nic-switch-free-vf.md new file mode 100644 index 0000000000..307db40688 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-free-vf.md @@ -0,0 +1,155 @@ +--- +title: OID\_NIC\_SWITCH\_FREE\_VF +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_FREE\_VF to free the resources for a network adapter's PCI Express (PCIe) Virtual Function (VF).Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID set request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. +ms.assetid: B1A72D34-286A-4A70-8BE3-F21324B92187 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_FREE_VF Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_FREE\_VF + + +An overlying driver issues an object identifier (OID) set request of OID\_NIC\_SWITCH\_FREE\_VF to free the resources for a network adapter's PCI Express (PCIe) Virtual Function (VF). + +Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID set request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_FREE\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451579) structure. + +The overlying driver specifies the identifier of the VF to be freed through the **VFId** member of this structure. The driver obtained this identifier from an earlier OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + +Remarks +------- + +An overlying driver issues an OID set request of OID\_NIC\_SWITCH\_FREE\_VF to free the resources for a VF. These resources were previously allocated through an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + +For more information about how to free VF resources, see [Freeing Resources for a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh439570). + +**Note**  Once an overlying driver requests resource allocation for a VF, that driver is the only component that can request the freeing of the resources for the same VF. The overlying driver must issue an OID set request of OID\_NIC\_SWITCH\_FREE\_VF to free the VF resources. Before the overlying driver can be halted, it must free the resources for each VF that was allocated by the driver's [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) request. + +  + +### Return status codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +NDIS returns one of the following status codes for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the SR-IOV interface or is not enabled to use the interface.

NDIS_STATUS_FILE_NOT_FOUND

One or more of the members of the [NDIS_NIC_SWITCH_FREE_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451579) structure have invalid values. For example, the VFId member might specify a VF that either has not been allocated or that has VPorts that have not been deleted.

NDIS_STATUS_INVALID_LENGTH

The information buffer is too small. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_FREE\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451579) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisCloseAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff561640) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +[OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) + +[OID\_NIC\_SWITCH\_DELETE\_SWITCH](oid-nic-switch-delete-switch.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_FREE_VF%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-hardware-capabilities.md b/windows-driver-docs-pr/network/oid-nic-switch-hardware-capabilities.md new file mode 100644 index 0000000000..30e0c838bb --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-hardware-capabilities.md @@ -0,0 +1,113 @@ +--- +title: OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES to obtain the hardware capabilities of the NIC switch in the network adapter. +ms.assetid: 2c417a16-68e1-4754-88a5-8bac4653e05d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES to obtain the hardware capabilities of the NIC switch in the network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure. + +Remarks +------- + +The [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure contains information about the hardware capabilities of a NIC switch on the network adapter. These capabilities can include the hardware capabilities that are currently disabled by the INF file settings or through the **Advanced** properties page. + +**Note**  All the capabilities of the specified NIC switch are returned through an OID query request of OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES, regardless of whether a capability is enabled or disabled. + +  + +Starting with NDIS 6.20, miniport drivers supply the NIC switch hardware capabilities when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver initializes an [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure with the NIC switch hardware capabilities and sets the **HardwareNicSwitchCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the **NDIS\_NIC\_SWITCH\_CAPABILITIES** structure. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an **NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES** structure. + +**Note**  Starting with NDIS 6.30, miniport drivers that support the single root I/O virtualization (SR-IOV) interface must register the hardware capabilities of the NIC switch. Drivers register these capabilities by calling [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672). + +  + +### Return Status Codes + +NDIS handles the OID query request of OID\_NIC\_SWITCH\_HARDWARE\_CAPABILITIES request for miniport drivers, and returns one of the following status codes: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer points to an [NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-parameters.md b/windows-driver-docs-pr/network/oid-nic-switch-parameters.md new file mode 100644 index 0000000000..466d9423cd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-parameters.md @@ -0,0 +1,146 @@ +--- +title: OID\_NIC\_SWITCH\_PARAMETERS +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_PARAMETERS to obtain the current configuration parameters of a specified NIC switch on a network adapter. +ms.assetid: 3F2FF2C0-8710-4243-8583-CD80F244FCFB +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_PARAMETERS + + +An overlying driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_PARAMETERS to obtain the current configuration parameters of a specified NIC switch on a network adapter. NDIS handles these OID method requests for the miniport driver. + +Overlying drivers issue an OID set request of OID\_NIC\_SWITCH\_PARAMETERS to set the configuration parameters of a specified NIC switch on a network adapter. These OID set requests are issued to the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). These OID set requests are required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure. + +The overlying driver specifies the NIC switch for the OID method or set request by setting the **SwitchId** member of the [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure to the switch identifier. The overlying driver obtains the switch identifier through one of the following ways: + +- From a previous OID method request of [OID\_NIC\_SWITCH\_ENUM\_SWITCHES](oid-nic-switch-enum-switches.md). + +- From the **NicSwitchArray** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure. NDIS passes a pointer to this structure in the *BindParameters* parameter of the [*ProtocolBindAdapterEx*](https://msdn.microsoft.com/library/windows/hardware/ff570220) function. + +- From the **NicSwitchArray** member of the [**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) structure. NDIS passes a pointer to this structure in the *AttachParameters* parameter of the [*FilterAttach*](https://msdn.microsoft.com/library/windows/hardware/ff549905) function. + +**Note**  Starting with Windows Server 2012, Windows supports only the default NIC switch on the network adapter. The **SwitchId** member of the [**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure must be set to NDIS\_DEFAULT\_SWITCH\_ID. + +  + +Remarks +------- + +The overlying driver issues OID\_NIC\_SWITCH\_PARAMETERS requests in the following way: + +- The overlying driver issues an OID method request of OID\_NIC\_SWITCH\_PARAMETERS to obtain the current parameters of a specified NIC switch. For more information, see [Querying the Parameters of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh440179). + + **Note**  NDIS handles OID method requests of OID\_NIC\_SWITCH\_PARAMETERS for the PF miniport driver. + +   + +- The overlying driver issues an OID set request of OID\_NIC\_SWITCH\_PARAMETERS to change the current parameters of a specified NIC switch. For more information, see [Setting the Parameters of a NIC Switch](https://msdn.microsoft.com/library/windows/hardware/hh440227). + + **Note**  The PF miniport driver handles OID set requests of OID\_NIC\_SWITCH\_PARAMETERS. + +   + +### Return Status Codes + +NDIS or the PF miniport driver returns the following status codes for set or method OID requests of OID\_NIC\_SWITCH\_PARAMETERS. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer points to an [NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451587) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS or the PF miniport driver sets the DATA.METHOD_INFORMATION.BytesNeeded member (for OID method requests) or DATA.SET_INFORMATION.BytesNeeded member (for OID set requests) in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_REINIT_REQUIRED

The PF miniport driver requires a reinitialization of the network adapter to apply the changes to the NIC switch.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*FilterAttach*](https://msdn.microsoft.com/library/windows/hardware/ff549905) + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) + +[**NDIS\_NIC\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451587) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_CREATE\_SWITCH](oid-nic-switch-create-switch.md) + +[OID\_NIC\_SWITCH\_ENUM\_SWITCHES](oid-nic-switch-enum-switches.md) + +[*ProtocolBindAdapterEx*](https://msdn.microsoft.com/library/windows/hardware/ff570220) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-vf-parameters.md b/windows-driver-docs-pr/network/oid-nic-switch-vf-parameters.md new file mode 100644 index 0000000000..6488dd4b59 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-vf-parameters.md @@ -0,0 +1,132 @@ +--- +title: OID\_NIC\_SWITCH\_VF\_PARAMETERS +author: windows-driver-content +description: An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_VF\_PARAMETERS to obtain the current configuration parameters of a PCI Express (PCIe) Virtual Function (VF) on a network adapter. +ms.assetid: DF08B0BA-6D86-4C4F-AC38-8A401F097925 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_VF_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_VF\_PARAMETERS + + +An overlying driver or user-mode application issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_VF\_PARAMETERS to obtain the current configuration parameters of a PCI Express (PCIe) Virtual Function (VF) on a network adapter. Only VFs that have resources allocated through an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) can be queried through an OID method request of OID\_NIC\_SWITCH\_VF\_PARAMETERS. + +NDIS handles the OID method request of OID\_NIC\_SWITCH\_VF\_PARAMETERS for miniport drivers. + +When the OID method request is made, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure. + +Remarks +------- + +The overlying driver or user-mode application specifies the VF to query by setting the **VFId** member of the [**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure to the identifier of the VF. The overlying driver or application obtains the VF identifier through one of the following ways: + +- By issuing an OID method request of [OID\_NIC\_SWITCH\_ENUM\_VFS](oid-nic-switch-enum-vfs.md). + + If this OID request is completed successfully, the overlying driver or user-mode application receives a list of all VFs allocated on the network adapter. Each element within the list is an [**NDIS\_NIC\_SWITCH\_VF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451591) structure, with the VF identifier specified by the **VFId** member. + +- By issuing an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + + If this OID request is completed successfully, the overlying driver receives the identifier of the newly created VF in the **VFId** member of the returned [**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure. + + **Note**  Only overlying drivers can obtain the VF identifier in this manner. + +   + +After a successful return from the OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure. This structure contains the configuration parameters for the specified VF. + +### Return Status Codes + +NDIS handles the OID method request of OID\_NIC\_SWITCH\_VF\_PARAMETERS for miniport drivers, and returns the following status code for OID method requests of OID\_NIC\_SWITCH\_VF\_PARAMETERS. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer member points to an [NDIS_NIC_SWITCH_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451593) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_NIC_SWITCH_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451593)). NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451593) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_NIC\_SWITCH\_ENUM\_VFS](oid-nic-switch-enum-vfs.md) + +[**NDIS\_NIC\_SWITCH\_VF\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451591) + +[OID\_NIC\_SWITCH\_VF\_PARAMETERS](oid-nic-switch-vf-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_VF_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-nic-switch-vport-parameters.md b/windows-driver-docs-pr/network/oid-nic-switch-vport-parameters.md new file mode 100644 index 0000000000..e43db57d65 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-nic-switch-vport-parameters.md @@ -0,0 +1,142 @@ +--- +title: OID\_NIC\_SWITCH\_VPORT\_PARAMETERS +author: windows-driver-content +description: An overlying driver can obtain the parameters for a virtual port (VPort) on a NIC switch that has been created on a network adapter that supports single root I/O virtualization (SR-IOV). +ms.assetid: B22C760E-F2B0-4774-A532-4044C679CD64 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_NIC_SWITCH_VPORT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_NIC\_SWITCH\_VPORT\_PARAMETERS + + +An overlying driver can obtain the parameters for a virtual port (VPort) on a NIC switch that has been created on a network adapter that supports single root I/O virtualization (SR-IOV). The driver issues an object identifier (OID) method request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS to obtain these parameters. + +Overlying drivers issue an OID set request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS to set the configuration parameters of a specified VPort that is attached to the network adapter's NIC switch. These OID set requests are issued to the miniport driver of the network adapter's PCI Express (PCIe) Physical Function (PF). These OID set requests are required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure. + +The overlying driver specifies the VPort for the OID method or set request by setting the **VPortId** member of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure to the identifier associated with the VPort. The overlying driver obtains the VPort identifier through one of the following ways: + +- From a previous OID method request of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md). + +- From a previous OID method request of [OID\_NIC\_SWITCH\_ENUM\_VPORTS](oid-nic-switch-enum-vports.md). + +Remarks +------- + +OID\_NIC\_SWITCH\_VPORT\_PARAMETERS can be used in either [OID method requests](#oid-method-requests) or [OID set requests](#oid-set-requests). + +### Handling OID Method Requests of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS + +Overlying drivers issue an OID method request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS to query the current configuration parameters of a VPort that is attached to the network adapter's NIC switch. Overlying drivers specify the VPort to query by setting the **VPortId** member of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure to the VPort identifier. + +NDIS handles the OID method request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS for miniport drivers. NDIS returns information that it obtained from previous OID requests of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) and [OID\_NIC\_SWITCH\_ENUM\_VPORTS](oid-nic-switch-enum-vports.md). + +After a successful return from the OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure. This structure contains the configuration parameters for the specified switch. + +For more information, see [Querying the Parameters of a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440181). + +### Handling OID Set Requests of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS + +Overlying drivers issue an OID set request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS to change the current configuration parameters of a VPort that is attached to a network adapter's NIC switch. This OID request can be used to update the parameters for default as well as nondefault VPorts. + +Only a limited subset of configuration parameters for a VPort can be changed. The overlying driver specifies the parameter to change by setting the following members of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure: + +1. The **VPortId** member is set to the identifier of the VPort whose parameters will be changed. + +2. The appropriate NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS\_*Xxx*\_CHANGED flags are set in the **Flags** member. Members of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure can only be changed if a corresponding NDIS\_NIC\_SWITCH\_PARAMETERS\_*Xxx*\_CHANGED flag is defined in Ntddndis.h. + +3. The corresponding members of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure are set with the VPort configuration parameters that are to be changed. + +After the PF miniport driver receives the OID set request of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS, the driver configures the hardware with the configuration parameters. The driver can only change those configuration parameters identified by NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS\_*Xxx*\_CHANGED flags in the **Flags** member of the [**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure. + +For more information, see [Setting the Parameters of a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440228). + +### Return Status Codes + +NDIS or the PF miniport driver returns the following status code for set or method OID requests of OID\_NIC\_SWITCH\_VPORT\_PARAMETERS. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer points to an [NDIS_NIC_SWITCH_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff566583) structure.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_NIC_SWITCH_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451597) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS or the PF miniport driver sets the DATA.METHOD_INFORMATION.BytesNeeded member (for OID method requests) or DATA.SET_INFORMATION.BytesNeeded member (for OID set requests) in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_NIC\_SWITCH\_VPORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451597) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +[OID\_NIC\_SWITCH\_ENUM\_VPORTS](oid-nic-switch-enum-vports.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_NIC_SWITCH_VPORT_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-packet-coalescing-filter-match-count.md b/windows-driver-docs-pr/network/oid-packet-coalescing-filter-match-count.md new file mode 100644 index 0000000000..06e77bef4b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-packet-coalescing-filter-match-count.md @@ -0,0 +1,95 @@ +--- +title: OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT +author: windows-driver-content +description: NDIS issues an OID query request of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT to obtain the number of packets that were cached, or coalesced, on the network adapter. +ms.assetid: 3325865D-A329-4562-8270-CC2F42043D48 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PACKET_COALESCING_FILTER_MATCH_COUNT Network Drivers Starting with Windows Vista +--- + +# OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT + + +NDIS issues an OID query request of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT to obtain the number of packets that were cached, or *coalesced*, on the network adapter. The network adapter coalesces received packets if the adapter is enabled for [NDIS packet coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601) and the packet matches a receive filter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated ULONG64 variable. Before a successful return from the query request, the driver updates the ULONG64 variable with the number of packets that have matched receive filters on the network adapter. + +Remarks +------- + +Starting with NDIS 6.30, drivers that support [NDIS packet coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601) must support OID query requests of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT. + +**Note**  Drivers that support the [single root I/O virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235) or [virtual machine queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035) interfaces are not required to support OID query requests of this OID. + +  + +A miniport driver that supports packet coalescing must increment a ULONG64 counter for each received packet that was coalesced on the network adapter. Packets are coalesced if they match a receive filter, which overlying drivers download to the miniport driver through OID method requests of [OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md). + +The driver returns the value of this counter when it handles an OID query request of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT. + +The miniport driver must not clear the counter after it handles the OID query request of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT. The miniport driver must only clear the counter if the following conditions are true: + +- The miniport driver handles an OID set request of [OID\_PNP\_SET\_POWER](oid-pnp-set-power.md) to resume to a full-power state of NdisDeviceStateD0. + +- NDIS calls the miniport driver's [*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) function to reset the underlying network adapter. + +For more information about packet coalescing, see [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh205393). + +### Return status codes + +The miniport driver returns one of the following status codes for the OID method request of OID\_PACKET\_COALESCING\_FILTER\_MATCH\_COUNT: + +NDIS\_STATUS\_SUCCESS +The OID request completed successfully. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. The driver sets the **DATA.SET\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportResetEx*](https://msdn.microsoft.com/library/windows/hardware/ff559432) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_PNP\_SET\_POWER](oid-pnp-set-power.md) + +[OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PACKET_COALESCING_FILTER_MATCH_COUNT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pd-close-provider.md b/windows-driver-docs-pr/network/oid-pd-close-provider.md new file mode 100644 index 0000000000..ddcc8c1377 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pd-close-provider.md @@ -0,0 +1,67 @@ +--- +title: OID\_PD\_CLOSE\_PROVIDER +author: windows-driver-content +description: An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_CLOSE\_PROVIDER to the PDPI provider to give up access to the PD capability in a PDPI provider object. +ms.assetid: 8A504A81-6DC8-415C-9FDC-F03657A0EB87 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PD_CLOSE_PROVIDER Network Drivers Starting with Windows Vista +--- + +# OID\_PD\_CLOSE\_PROVIDER + + +An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_CLOSE\_PROVIDER to the PDPI provider to give up access to the PD capability in a PDPI provider object. + +An NDIS protocol or filter driver must call this OID when it receives an unbind notification, a pause indication, a low-power event, or a PD configuration change event that indicates the PD is disabled on the binding. + +Before calling this OID, the NDIS protocol or filter driver must ensure that it has closed and freed all PD objects such as queues, counters, and filters that it created over the PD provider instance. The NDIS protocol or filter driver must guarantee that there are no in-progress calls to any of the PD provider dispatch table functions before issuing this OID. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +[**NDIS\_PD\_CLOSE\_PROVIDER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn931834) + +[NDIS\_STATUS\_PD\_CURRENT\_CONFIG](https://msdn.microsoft.com/library/windows/hardware/dn931850) + +[OID\_PD\_OPEN\_PROVIDER](oid-pd-open-provider.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PD_CLOSE_PROVIDER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pd-open-provider.md b/windows-driver-docs-pr/network/oid-pd-open-provider.md new file mode 100644 index 0000000000..7bafc5b48e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pd-open-provider.md @@ -0,0 +1,70 @@ +--- +title: OID\_PD\_OPEN\_PROVIDER +author: windows-driver-content +description: An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_OPEN\_PROVIDER to a PD-capable miniport driver to gain access to the PD capability in the miniport driver's PDPI provider object. +ms.assetid: B13E0FAC-A179-4785-9B39-CB498064947B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PD_OPEN_PROVIDER Network Drivers Starting with Windows Vista +--- + +# OID\_PD\_OPEN\_PROVIDER + + +An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_OPEN\_PROVIDER to a PD-capable miniport driver to gain access to the PD capability in the miniport driver's PDPI provider object. All PD-capable miniport drivers must handle this OID request. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_PD\_OPEN\_PROVIDER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn931842) structure + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +[**NDIS\_PD\_OPEN\_PROVIDER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn931842) + +[NDIS\_STATUS\_PD\_CURRENT\_CONFIG](https://msdn.microsoft.com/library/windows/hardware/dn931850) + +[OID\_PD\_CLOSE\_PROVIDER](oid-pd-close-provider.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PD_OPEN_PROVIDER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pd-query-current-config.md b/windows-driver-docs-pr/network/oid-pd-query-current-config.md new file mode 100644 index 0000000000..9eae25bbdd --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pd-query-current-config.md @@ -0,0 +1,68 @@ +--- +title: OID\_PD\_QUERY\_CURRENT\_CONFIG +author: windows-driver-content +description: An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_QUERY\_CURRENT\_CONFIG to a PD-capable miniport driver to retrieve the PD status and capabilities. All PD-capable miniport drivers must handle this OID request. +ms.assetid: 1BF09EAE-9D03-4655-98CD-D3A10BF48A48 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PD_QUERY_CURRENT_CONFIG Network Drivers Starting with Windows Vista +--- + +# OID\_PD\_QUERY\_CURRENT\_CONFIG + + +An NDIS protocol or filter driver sends an object identifier (OID) method request of OID\_PD\_QUERY\_CURRENT\_CONFIG to a PD-capable miniport driver to retrieve the PD status and capabilities. All PD-capable miniport drivers must handle this OID request. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_PD\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/dn931835) structure + +Remarks +------- + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) + +[**NDIS\_PD\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/dn931835) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PD_QUERY_CURRENT_CONFIG%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-add-protocol-offload.md b/windows-driver-docs-pr/network/oid-pm-add-protocol-offload.md new file mode 100644 index 0000000000..87a8c411bc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-add-protocol-offload.md @@ -0,0 +1,108 @@ +--- +title: OID\_PM\_ADD\_PROTOCOL\_OFFLOAD +author: windows-driver-content +description: As a set, NDIS protocol drivers use the OID\_PM\_ADD\_PROTOCOL\_OFFLOAD OID to add a protocol offload for power management to a network adapter. +ms.assetid: 418f4ce8-64af-4e1e-877a-4cc606f63747 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_ADD_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_ADD\_PROTOCOL\_OFFLOAD + + +As a set, NDIS protocol drivers use the OID\_PM\_ADD\_PROTOCOL\_OFFLOAD OID to add a protocol offload for power management to a network adapter. The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure. + +Remarks +------- + +NDIS 6.20 and later protocol drivers use OID\_PM\_ADD\_PROTOCOL\_OFFLOAD OID to add a protocol offload for power management to a network adapter. If the request is successful, the network adapter must generate and transmit the necessary response packets for the offloaded protocol when the network adapter is in a low power state. + +A protocol driver can offload a protocol after it successfully binds to an underlying network adapter and as soon as it has the necessary data (such as the IP address of the interface) to offload the protocol. The protocol driver can also offload a protocol in response to some other power management event notifications, such as the rejection of a previously added WOL pattern or an offloaded protocol. + +To avoid race conditions in NDIS and other protocol drivers that are bound to the same miniport adapter, after NDIS starts to set a network adapter to a low power state, it will fail any attempt to offload another protocol to that network adapter. For example, if an NDIS protocol driver tries to offload a protocol in the context of processing a **NetEventSetPower** event notification for that network adapter, NDIS will fail the request. + +Before NDIS sends this OID request down to the underlying NDIS drivers or completes the request to the overlying driver, it sets the ULONG **ProtocolOffloadId** member of the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure to a unique value. Protocol drivers and NDIS use this protocol offload identifier with the [OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD](oid-pm-remove-protocol-offload.md) OID request to remove the protocol offload from the underlying network adapter. + +**Note**  The protocol offload identifier is a unique value for each of the protocol offloads that are set on a network adapter. However, the protocol offload identifier is not globally unique across all network adapters. + +  + +If NDIS or an underlying network adapter rejects an offload, it generates an [**NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED**](https://msdn.microsoft.com/library/windows/hardware/ff567412) status indication. This can occur after returning NDIS\_STATUS\_SUCCESS for the OID. The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains the ULONG protocol offload identifier of the rejected protocol offload. + +For information on how a Native 802.11 Wireless LAN miniport driver uses this OID, see [Adding and Deleting Low Power Protocol Offloads](https://msdn.microsoft.com/library/windows/hardware/ff543707). + +The miniport driver returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The requested protocol offload was added successfully. The **ProtocolOffloadId** member of the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure contains a protocol offload identifier. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_PM\_PROTOCOL\_OFFLOAD\_LIST\_FULL +The request failed because the protocol offload list is full and the network adapter cannot add another protocol offload. + +NDIS\_STATUS\_RESOURCES +NDIS or an underlying network adapter could not add the new protocol offload due to lack of resources. + +NDIS\_STATUS\_INVALID\_PARAMETER +One or more parameters in the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure were invalid. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.SET\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The network adapter does not support the requested protocol offload. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Mandatory for miniport drivers.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED**](https://msdn.microsoft.com/library/windows/hardware/ff567412) + +[OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD](oid-pm-remove-protocol-offload.md) + +[Adding and Deleting Low Power Protocol Offloads](https://msdn.microsoft.com/library/windows/hardware/ff543707) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_ADD_PROTOCOL_OFFLOAD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-add-wol-pattern.md b/windows-driver-docs-pr/network/oid-pm-add-wol-pattern.md new file mode 100644 index 0000000000..1f9cfbb3c9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-add-wol-pattern.md @@ -0,0 +1,106 @@ +--- +title: OID\_PM\_ADD\_WOL\_PATTERN +author: windows-driver-content +description: As a set, NDIS protocol drivers use the OID\_PM\_ADD\_WOL\_PATTERN OID to add a power management wake-on-LAN pattern to a network adapter. The InformationBuffer member of the NDIS\_OID\_REQUEST structure contains a pointer to an NDIS\_PM\_WOL\_PATTERN structure. +ms.assetid: 1005cebb-8ead-4d16-b3ea-5a74da0b054f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_ADD_WOL_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_ADD\_WOL\_PATTERN + + +As a set, NDIS protocol drivers use the OID\_PM\_ADD\_WOL\_PATTERN OID to add a power management wake-on-LAN pattern to a network adapter. The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure. + +Remarks +------- + +NDIS 6.20 and later protocol drivers use OID\_PM\_ADD\_WOL\_PATTERN to add a Wake on LAN (WOL) pattern to a network adapter. The OID request contains criterion that the network adapter must compare to incoming packets when it is in a low power state. The network adapter must generate a wake up event when it receives a packet that matches the pattern criteria. + +A protocol driver can add WOL patterns after it successfully binds to an underlying network adapter and as soon as it has the necessary data (such as the IP address of the interface) to set up the WOL pattern. The protocol driver can also add a WOL pattern in response to some other power management event notifications such as the rejection of a previously added WOL pattern or an offloaded protocol. + +To avoid race conditions in NDIS and other protocol drivers that are bound to the same miniport adapter, after NDIS starts to set a network adapter to a low power state, it will fail any attempt to add a new wake up pattern to that network adapter. For example, if an NDIS protocol driver tries to add a new WOL pattern in the context of processing a **NetEventSetPower** event notification for that network adapter, NDIS will fail the request. + +Before NDIS sends this OID request down to the underlying NDIS drivers or completes the request to the overlying driver, it sets the ULONG **PatternId** member of the [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure to a unique value. Protocol drivers and NDIS use this pattern identifier with the [OID\_PM\_REMOVE\_WOL\_PATTERN](oid-pm-remove-wol-pattern.md) OID request to remove the WOL pattern from the underlying network adapter. + +**Note**  The pattern identifier is a unique value for each of the patterns that are set on a network adapter. However, the pattern identifier is not globally unique across all miniport adapters. + +  + +If NDIS or an underlying network adapter removes a WOL pattern, it generates an [**NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED**](https://msdn.microsoft.com/library/windows/hardware/ff567414) status indication. The **StatusBuffer** member of the [**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) structure contains the ULONG WOL pattern identifier of the rejected WOL pattern. + +The miniport driver returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The requested pattern was added successfully. The **PatternId** member of the NDIS\_PM\_WOL\_PATTERN structure contains a pattern identifier. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_PM\_WOL\_PATTERN\_LIST\_FULL +The request failed because the pattern list is full and the network adapter cannot add another pattern. + +NDIS\_STATUS\_RESOURCES +NDIS or underlying network adapter could not add the new pattern due to lack of resources. + +NDIS\_STATUS\_INVALID\_PARAMETER +One or more parameters in the NDIS\_PM\_WOL\_PATTERN structure were invalid. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.SET\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The network adapter does not support the requested WOL pattern. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Mandatory for miniport drivers.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED**](https://msdn.microsoft.com/library/windows/hardware/ff567414) + +[OID\_PM\_REMOVE\_WOL\_PATTERN](oid-pm-remove-wol-pattern.md) + +[OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_ADD_WOL_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-current-capabilities.md b/windows-driver-docs-pr/network/oid-pm-current-capabilities.md new file mode 100644 index 0000000000..b4ead8f05e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-current-capabilities.md @@ -0,0 +1,86 @@ +--- +title: OID\_PM\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: As a query, overlying drivers can use the OID\_PM\_CURRENT\_CAPABILITIES OID to query the currently available power management capabilities of a network adapter. +ms.assetid: b35ce325-a1aa-43e0-bf68-cb2ab89dff76 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_CURRENT\_CAPABILITIES + + +As a query, overlying drivers can use the OID\_PM\_CURRENT\_CAPABILITIES OID to query the currently available power management capabilities of a network adapter. After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure. + +Remarks +------- + +NDIS handles the query for miniport drivers. Starting with NDIS 6.20, miniport drivers supply the power management hardware capabilities during initialization. However, NDIS can hide some capabilities from the protocol driver. For example, NDIS might report different capabilities when a user disables some or all of the power management capabilities. + +Note that the current power management capabilities that NDIS reports to a protocol driver are not necessarily the same as the hardware capabilities that the miniport driver reported to NDIS. + +NDIS reports the power management capabilities of an underlying network adapter to overlying protocol drivers in the **PowerManagementCapabilitiesEx** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure during the bind operation. Therefore, protocol drivers do not have to query the OID. + +NDIS issues an [**NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/ff567410) status indication to report changes in the power management capabilities that are available to overlying drivers. + +If the underlying network adapter has an NDIS 6.1 or older miniport driver, NDIS translates the power management capabilities of the underlying network adapter to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure. + +NDIS returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Not requested for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) + +[**NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/ff567410) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-get-protocol-offload.md b/windows-driver-docs-pr/network/oid-pm-get-protocol-offload.md new file mode 100644 index 0000000000..eb6de305eb --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-get-protocol-offload.md @@ -0,0 +1,84 @@ +--- +title: OID\_PM\_GET\_PROTOCOL\_OFFLOAD +author: windows-driver-content +description: An overlying driver issues an OID method request of OID\_PM\_GET\_PROTOCOL\_OFFLOAD to obtain parameter settings for a low power protocol offload from a network adapter. +ms.assetid: c14b9278-6f24-41a1-bc2e-536a75460ecd +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_GET_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_GET\_PROTOCOL\_OFFLOAD + + +An overlying driver issues an OID method request of OID\_PM\_GET\_PROTOCOL\_OFFLOAD to obtain parameter settings for a low power protocol offload from a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure initially contains a pointer to a ULONG protocol offload identifier. After a successful return from the OID method request, the **InformationBuffer** member of the **NDIS\_OID\_REQUEST** structure contains a pointer to an [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure. + +Remarks +------- + +NDIS 6.20 and later protocol drivers use OID\_PM\_GET\_PROTOCOL\_OFFLOAD method OID to retrieve parameter settings for a low power protocol offload from a network adapter. + +The information buffer must point to a ULONG-type protocol offload identifier. NDIS set this protocol offload identifier in the **ProtocolOffloadId** member of the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure when NDIS sent the prior [OID\_PM\_ADD\_PROTOCOL\_OFFLOAD](oid-pm-add-protocol-offload.md) OID request to the underlying network adapter. + +The miniport driver returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The requested data was retrieved successfully. The information buffer contains the corresponding NDIS\_PM\_PROTOCOL\_OFFLOAD structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller. + +NDIS\_STATUS\_INVALID\_PARAMETER +The specified protocol offload identifier was not valid. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The NDIS version of the miniport driver is below 6.20. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Mandatory for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +[OID\_PM\_ADD\_PROTOCOL\_OFFLOAD](oid-pm-add-protocol-offload.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_GET_PROTOCOL_OFFLOAD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-hardware-capabilities.md b/windows-driver-docs-pr/network/oid-pm-hardware-capabilities.md new file mode 100644 index 0000000000..340a3c73f3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-hardware-capabilities.md @@ -0,0 +1,80 @@ +--- +title: OID\_PM\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: As a query, overlying drivers can use the OID\_PM\_HARDWARE\_CAPABILITIES OID to query the power management hardware capabilities of a network adapter. +ms.assetid: 52446584-bb73-4cf4-bda9-bf92ef2488e3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_HARDWARE\_CAPABILITIES + + +As a query, overlying drivers can use the OID\_PM\_HARDWARE\_CAPABILITIES OID to query the power management hardware capabilities of a network adapter. After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure. + +Remarks +------- + +NDIS handles the query for miniport drivers. Starting with NDIS 6.20, miniport drivers supply the power management hardware capabilities during initialization in the **PowerManagementCapabilitiesEx** member of the [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) structure. + +The miniport driver must issue an [**NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/ff567410) status indication to report changes in the power management hardware capabilities of a network adapter to NDIS and overlying drivers. + +NDIS returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Not requested for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) + +[**NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/ff567410) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-parameters.md b/windows-driver-docs-pr/network/oid-pm-parameters.md new file mode 100644 index 0000000000..85d834109b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-parameters.md @@ -0,0 +1,89 @@ +--- +title: OID\_PM\_PARAMETERS +author: windows-driver-content +description: As a query, protocol drivers can use the OID\_PM\_PARAMETERS OID to query the power management hardware capabilities of a network adapter that are currently enabled. +ms.assetid: c3431724-1b5f-4634-8b1e-27fed9031f01 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_PARAMETERS + + +As a query, protocol drivers can use the OID\_PM\_PARAMETERS OID to query the power management hardware capabilities of a network adapter that are currently enabled. After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) structure. + +As a set, protocol drivers can use the OID\_PM\_PARAMETERS OID to enable or disable the current hardware capabilities of a network adapter. The protocol driver provides a pointer to an [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) structure in the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +Remarks +------- + +Starting with NDIS 6.20, overlying protocol and filter drivers use OID\_PM\_PARAMETERS to query and set the power management hardware capabilities of a network adapter that are currently enabled. + +When an overlying driver queries the OID\_PM\_PARAMETERS OID, NDIS completes the request without forwarding it to the miniport driver. NDIS stores the requested settings and combines them with the settings from other such requests. Before NDIS transitions the network adapter to the low power state, NDIS sends a set request to the miniport driver that contains the combined settings from all of the requests that NDIS stored. + +The capabilities that are currently enabled can be a subset of the capabilities that the hardware supports. For more information about the capabilities that the hardware supports, see [OID\_PM\_HARDWARE\_CAPABILITIES](oid-pm-hardware-capabilities.md). + +**Note**  If NDIS sets the NDIS\_PM\_SELECTIVE\_SUSPEND\_ENABLED flag in the **WakeUpFlags** member of [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) structure, it issues the OID set request of OID\_PM\_PARAMETERS directly to the miniport driver. This allows NDIS to bypass the processing by filter drivers in the networking driver stack. + +  + +NDIS or the miniport driver returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_INVALID\_PARAMETER +The request failed because it tried to enable a capability that the underlying network adapter does not support. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) + +[OID\_PM\_HARDWARE\_CAPABILITIES](oid-pm-hardware-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-protocol-offload-list.md b/windows-driver-docs-pr/network/oid-pm-protocol-offload-list.md new file mode 100644 index 0000000000..9d275ad021 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-protocol-offload-list.md @@ -0,0 +1,78 @@ +--- +title: OID\_PM\_PROTOCOL\_OFFLOAD\_LIST +author: windows-driver-content +description: As a query, overlying drivers can use the OID\_PM\_PROTOCOL\_OFFLOAD\_LIST OID to enumerate the protocol offloads that are set on an underlying network adapter. +ms.assetid: 95ace77b-e583-4611-8460-af67b4d4805d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_PROTOCOL_OFFLOAD_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_PROTOCOL\_OFFLOAD\_LIST + + +As a query, overlying drivers can use the OID\_PM\_PROTOCOL\_OFFLOAD\_LIST OID to enumerate the protocol offloads that are set on an underlying network adapter. After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a list of [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structures that describe the currently active protocol offloads. + +Remarks +------- + +NDIS handles the query for miniport drivers. NDIS drivers can use the OID\_PM\_PROTOCOL\_OFFLOAD\_LIST OID to get a list of protocol offloads that are set on an underlying network adapter. + +For each [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure in the list, NDIS sets the **NextProtocolOffloadOffset** member to the offset from the beginning of the OID information buffer (that is, the beginning of the buffer that the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure points to) to the beginning of the next NDIS\_PM\_PROTOCOL\_OFFLOAD structure in the list. The offset in the **NextProtocolOffloadOffset** member of the last structure in the list is zero. + +If there are no protocol offloads that are set on the network adapter, NDIS sets the **DATA.QUERY\_INFORMATION.BytesWritten** member of the NDIS\_OID\_REQUEST structure to zero and returns NDIS\_STATUS\_SUCCESS. The data within the **DATA.QUERY\_INFORMATION.InformationBuffer** member is not modified by NDIS. + +NDIS returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** contains a pointer to a list of protocol offloads, if any. + +NDIS\_STATUS\_PENDING +The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Not requested for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_PROTOCOL_OFFLOAD_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-remove-protocol-offload.md b/windows-driver-docs-pr/network/oid-pm-remove-protocol-offload.md new file mode 100644 index 0000000000..be1a4faf21 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-remove-protocol-offload.md @@ -0,0 +1,88 @@ +--- +title: OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD +author: windows-driver-content +description: As a set request, NDIS and protocol drivers use the OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD OID to remove a power management protocol offload from a network adapter. +ms.assetid: efca3018-28bf-4d91-b698-4b1c9e02f6e3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_REMOVE_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD + + +As a set request, NDIS and protocol drivers use the OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD OID to remove a power management protocol offload from a network adapter. The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a **ULONG** protocol offload identifier. + +Remarks +------- + +NDIS and protocol drivers use the OID\_PM\_REMOVE\_PROTOCOL\_OFFLOAD OID to remove a protocol offload from the underlying network adapter. + +The **DATA.SET\_INFORMATION.InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure must point to a **ULONG** value for a previously added protocol offload identifier. NDIS sets this protocol offload identifier in the **ProtocolOffloadId** member of the [**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) structure when NDIS sent the prior [OID\_PM\_ADD\_PROTOCOL\_OFFLOAD](oid-pm-add-protocol-offload.md) OID request to the underlying network adapter. + +### Remarks for miniport driver writers + +NDIS ensures that the buffer size is at least **sizeof**(**ULONG**) and contains a valid protocol offload ID. Therefore, a miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function should return NDIS\_STATUS\_SUCCESS for this request. + +**Note**  If the miniport driver is resetting, its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function should return NDIS\_STATUS\_NOT\_ACCEPTED. + +  + +### Return status codes + +NDIS returns one of the following status codes for this request: + +**NDIS\_STATUS\_SUCCESS** +The protocol offload was removed successfully. + +**NDIS\_STATUS\_PENDING** +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +**NDIS\_STATUS\_INVALID\_LENGTH** +The information buffer is too small. NDIS sets the **DATA.SET\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required, in bytes. + +**NDIS\_STATUS\_FILE\_NOT\_FOUND** +The protocol offload identifier in the OID request is not valid. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Mandatory for miniport drivers.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_PROTOCOL\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566760) + +[OID\_PM\_ADD\_PROTOCOL\_OFFLOAD](oid-pm-add-protocol-offload.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_REMOVE_PROTOCOL_OFFLOAD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-remove-wol-pattern.md b/windows-driver-docs-pr/network/oid-pm-remove-wol-pattern.md new file mode 100644 index 0000000000..934568a16b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-remove-wol-pattern.md @@ -0,0 +1,138 @@ +--- +title: OID\_PM\_REMOVE\_WOL\_PATTERN +author: windows-driver-content +description: As a set, NDIS and protocol drivers use the OID\_PM\_REMOVE\_WOL\_PATTERN OID to remove a power management wake on LAN (WOL) pattern from a network adapter. +ms.assetid: fdaa2646-6f41-4f51-9c27-6194270f26ed +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_REMOVE_WOL_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_REMOVE\_WOL\_PATTERN + + +As a set, NDIS and protocol drivers use the OID\_PM\_REMOVE\_WOL\_PATTERN OID to remove a power management wake on LAN (WOL) pattern from a network adapter. The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a ULONG pattern identifier. + +Remarks +------- + +NDIS and protocol drivers use OID\_PM\_REMOVE\_WOL\_PATTERN to remove a wake on LAN (WOL) pattern from the underlying network adapter. + +The **DATA.SET\_INFORMATION.InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure must point to a ULONG value for a previously added WOL pattern identifier. NDIS set this pattern identifier in the **PatternId** member of the [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure when NDIS sent the prior [OID\_PM\_ADD\_WOL\_PATTERN](oid-pm-add-wol-pattern.md) OID request to the underlying network adapter. + +### Return Status Codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +NDIS returns one of the following status codes for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The NDIS version of the miniport driver is less than NDIS 6.20.

NDIS_STATUS_FILE_NOT_FOUND

The pattern identifier in the OID request is invalid.

NDIS_STATUS_INVALID_LENGTH

The information buffer is too small. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Mandatory for miniport drivers.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +[OID\_PM\_ADD\_WOL\_PATTERN](oid-pm-add-wol-pattern.md) + +[**NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED**](https://msdn.microsoft.com/library/windows/hardware/ff567414) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_REMOVE_WOL_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pm-wol-pattern-list.md b/windows-driver-docs-pr/network/oid-pm-wol-pattern-list.md new file mode 100644 index 0000000000..76f3452a01 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pm-wol-pattern-list.md @@ -0,0 +1,86 @@ +--- +title: OID\_PM\_WOL\_PATTERN\_LIST +author: windows-driver-content +description: As a query, overlying drivers can use the OID\_PM\_WOL\_PATTERN\_LIST OID to enumerate the wake on LAN patterns that are set on an underlying network adapter. +ms.assetid: 7e5a65d8-39ec-4624-aede-97df945ef5e5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PM_WOL_PATTERN_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_PM\_WOL\_PATTERN\_LIST + + +As a query, overlying drivers can use the OID\_PM\_WOL\_PATTERN\_LIST OID to enumerate the wake on LAN patterns that are set on an underlying network adapter. After a successful return from the query, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a list of [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structures that describe the currently added WOL patterns. + +Remarks +------- + +NDIS handles the query for miniport drivers. NDIS drivers can use the OID\_PM\_WOL\_PATTERN\_LIST OID to get a list of wake on LAN patterns that are set on an underlying network adapter. + +For each [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure in the list, NDIS sets the **NextWoLPatternOffset** member to the offset from the beginning of the OID information buffer (that is, the beginning of the buffer that the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure points to) to the beginning of the next **NDIS\_PM\_WOL\_PATTERN** structure in the list. The offset in the **NextWoLPatternOffset** member of the last structure in the list is zero. + +For offsets in an [**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) structure other than **NextWoLPatternOffset** (for example, **NameBufferOffset**), NDIS provides offsets that are relative to the beginning of each **NDIS\_PM\_WOL\_PATTERN** structure. + +If there are no WOL patterns that are set on the network adapter, NDIS sets the **DATA.QUERY\_INFORMATION.BytesWritten** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to zero and returns **NDIS\_STATUS\_SUCCESS** for the request. The data within the **DATA.QUERY\_INFORMATION.InformationBuffer** member is not modified by NDIS. + +NDIS returns one of the following status codes for the request: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** contains a pointer to a list of WOL patterns, if any. + +NDIS\_STATUS\_PENDING +The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller. + +NDIS\_STATUS\_BUFFER\_TOO\_SHORT +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the NDIS\_OID\_REQUEST structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for reasons other than the preceding reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later. Not requested for miniport drivers. (See Remarks section.)

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_PM\_WOL\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566768) + +[OID\_PM\_ADD\_WOL\_PATTERN](oid-pm-add-wol-pattern.md) + +[OID\_PM\_REMOVE\_WOL\_PATTERN](oid-pm-remove-wol-pattern.md) + +[OID\_PNP\_WAKE\_UP\_PATTERN\_LIST](oid-pnp-wake-up-pattern-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PM_WOL_PATTERN_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-add-wake-up-pattern.md b/windows-driver-docs-pr/network/oid-pnp-add-wake-up-pattern.md new file mode 100644 index 0000000000..c24ad36ae0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-add-wake-up-pattern.md @@ -0,0 +1,74 @@ +--- +title: OID\_PNP\_ADD\_WAKE\_UP\_PATTERN +author: windows-driver-content +description: OID\_PNP\_ADD\_WAKE\_UP\_PATTERN +ms.assetid: 96b95d1d-d557-4012-b95f-b1c43e2c590f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_ADD_WAKE_UP_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_ADD\_WAKE\_UP\_PATTERN + + +## + + +The OID\_PNP\_ADD\_WAKE\_UP\_PATTERN OID is sent by a protocol driver to a miniport driver to specify a wake-up pattern. The wake-up pattern, along with its mask, is described by an [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure. + +A protocol that enables pattern-match wake-up for a miniport driver (see [OID\_PNP\_ENABLE\_WAKE\_UP](oid-pnp-enable-wake-up.md)) uses OID\_PNP\_ADD\_WAKE\_UP\_PATTERN to specify a wake-up pattern. The wake-up pattern can be stored in host memory or on the network adapter, depending on the capabilities of the network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the following: + +- An [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure that provides information about the pattern and its mask. + +- A mask that indicates which bytes of an incoming packet should be compared with corresponding bytes in the pattern. The mask starts with the first byte of the packet. The mask immediately follows the [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure in the *InformationBuffer*. For more information about how this mask works, see the [Network Device Class Power Management Reference specification](http://go.microsoft.com/fwlink/p/?linkid=27255). + +- A wake-up pattern, which begins **PatternOffset** bytes from the beginning of the *InformationBuffer*. For more information about wake-up patterns, see the [Network Device Class Power Management Reference specification](http://go.microsoft.com/fwlink/p/?linkid=27255). + +The number of wake-up patterns that the miniport driver can accept from a protocol might depend on the availability of resources, such as the host memory that the miniport driver has allocated for such patterns, or the available storage in the network adapter. If a miniport driver cannot add a wake-up pattern due to insufficient resources, the miniport driver returns **NDIS\_STATUS\_RESOURCES** in response to OID\_PNP\_ADD\_WAKE\_UP\_PATTERN. + +If a protocol driver tries to add a duplicate pattern, the miniport driver should return **NDIS\_STATUS\_INVALID\_DATA** in response to OID\_PNP\_ADD\_WAKE\_UP\_PATTERN. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling [**NdisRequest**](https://msdn.microsoft.com/library/windows/hardware/ff554681) or [**NdisCoRequest**](https://msdn.microsoft.com/library/windows/hardware/ff551877). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and NDIS 6.1. For NDIS 6.20 and later, use [OID_PM_ADD_WOL_PATTERN](oid-pm-add-wol-pattern.md) instead.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) + +[OID\_PM\_ADD\_WOL\_PATTERN](oid-pm-add-wol-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_ADD_WAKE_UP_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-capabilities.md b/windows-driver-docs-pr/network/oid-pnp-capabilities.md new file mode 100644 index 0000000000..6e3085893b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-capabilities.md @@ -0,0 +1,163 @@ +--- +title: OID\_PNP\_CAPABILITIES +author: windows-driver-content +description: The OID\_PNP\_CAPABILITIES OID requests a miniport driver to return the wake-up capabilities of its network adapter or requests an intermediate driver to return the intermediate driver's wake-up capabilities. +ms.assetid: f2e3a867-d7d2-4d09-b84b-e8f8610b8535 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_CAPABILITIES + + +The OID\_PNP\_CAPABILITIES OID requests a miniport driver to return the wake-up capabilities of its network adapter or requests an intermediate driver to return the intermediate driver's wake-up capabilities. The wake-up capabilities are formatted as an **NDIS\_PNP\_CAPABILITIES** structure, which is defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_PNP_CAPABILITIES { + ULONG Flags; + NDIS_PM_WAKE_UP_CAPABILITIES WakeUpCapabilities; + } NDIS_PNP_CAPABILITIES, *PNDIS_PNP_CAPABILITIES; + +``` + +## + + +The members of this structure contain the following information: + +**Flags** +**NDIS\_DEVICE\_WAKE\_UP\_ENABLE** + +NDIS sets this flag if the underlying miniport driver supports one or more wake-up capabilities. Protocol drivers can test this flag to determine whether an underlying miniport driver has wake-up capabilities. Miniport drivers should not access this flag. + +**WakeUpCapabilities** +An **NDIS\_PM\_WAKE\_UP\_CAPABILITIES** structure that specifies the wake-up capabilities of the miniport driver's network adapter. The **NDIS\_PM\_WAKE\_UP\_CAPABILITIES** structure is defined as follows: + +``` +typedef struct _NDIS_PM_WAKE_UP_CAPABILITIES { + NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp; + NDIS_DEVICE_POWER_STATE MinPatternWakeUp; + NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp; + } NDIS_PM_WAKE_UP_CAPABILITIES, *PNDIS_PM_WAKE_UP_CAPABILITIES; +``` + +The members of this structure contain the following information: + +**MinMagicPacketWakeUp** +Specifies the lowest device power state from which the miniport driver's network adapter can signal a wake-up on receipt of a magic packet. (A *magic packet* is a packet that contains 16 contiguous copies of the receiving network adapter's Ethernet address.) The device power state is specified as one of the following [**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) values: + +**NdisDeviceStateUnspecified** +The network adapter does not support magic-packet wake-ups. + +**NdisDeviceStateD0** +The network adapter can signal a magic-packet wake-up from device power state D0. Because D0 is the fully powered state, this does not cause a wake-up but can be used as a run-time event. + +**NdisDeviceStateD1** +The network adapter can signal a magic-packet wake-up from device power states D1 and D0. + +**NdisDeviceStateD2** +The network adapter can signal a magic-packet wake-up from device states D2, D1, and D0. + +**NdisDeviceStateD3** +The network adapter can signal a magic-packet wake-up from device power states D3, D2, D1, and D0. + +**MinPatternWakeUp** +Specifies the lowest device power state from which the miniport driver's network adapter can signal a wake-up event on receipt of a network frame that contains a pattern specified by the protocol driver. The power state is specified as one of the following [**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) values: + +**NdisDeviceStateUnspecified** +The network adapter does not support pattern-match wake-ups. + +**NdisDeviceStateD0** +The network adapter can signal a pattern-match wake-up from device power state D0. Because D0 is the fully powered state, this does not cause a wake-up but can be used as a run-time event. + +**NdisDeviceStateD1** +The network adapter can signal a pattern-match wake-up from device power states D1 and D0. + +**NdisDeviceStateD2** +The network adapter can signal a pattern-match wake-up from device power states D2, D1, and D0. + +**NdisDeviceStateD3** +The network adapter can signal a pattern-match wake-up from device power states D3, D2, D1, and D0. + +**MinLinkChangeWakeUp** +Reserved. NDIS ignores this member. + +**For Miniport Drivers** + +After the miniport driver completes initialization, both the protocol driver and NDIS can query the miniport driver with this OID to determine the following: + +- Whether the miniport driver is PM-aware. + +- The network adapter's capabilities of indicating network wake-up events. + +If the miniport driver returns **NDIS\_STATUS\_SUCCESS** to a query of OID\_PNP\_CAPABILITIES, NDIS considers the miniport driver to be PM-aware. If the miniport driver returns **NDIS\_STATUS\_NOT\_SUPPORTED**, NDIS considers the miniport driver to be a legacy miniport driver that is not PM-aware. + +When calling [**NdisMSetAttributesEx**](https://msdn.microsoft.com/library/windows/hardware/ff553623), a miniport driver that does not support wake-up capabilities but that can save and restore its network adapter state across a power-state transition can set the **NDIS\_ATTRIBUTE\_NO\_HALT\_ON\_SUSPEND** flag. Setting this flag prevents NDIS from calling the driver's *MiniportHalt* function before the system transitions to a low-power (sleeping) state. However, if the miniport driver returns **NDIS\_STATUS\_NOT\_SUPPORTED** in response to a query OID\_PNP\_CAPABILITIES, NDIS ignores the **NDIS\_ATTRIBUTE\_NO\_HALT\_ON\_SUSPEND** flag and halts the network adapter if the system goes into a low-power state. + +A miniport driver's network adapter can support any combination of wake-up events, including no wake-up events. A miniport driver can still support power management even if its network adapter cannot not signal wake-up events. In this case, the only power management OIDs that the miniport driver supports in addition to OID\_PNP\_CAPABILITIES are [OID\_PNP\_QUERY\_POWER](oid-pnp-query-power.md) and [OID\_PNP\_SET\_POWER](oid-pnp-set-power.md). + +If a miniport driver's network adapter does not support a particular wake-up event, the miniport driver should indicate an [**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) value of **NdisDeviceStateUnspecified** for the wake-up event in the **NDIS\_PM\_WAKE\_UP\_CAPABILITIES** structure. + +OID\_PNP\_CAPABILITIES only indicates the wake-up capabilities of a miniport driver' s network adapter; it does not enable such capabilities. [OID\_PNP\_ENABLE\_WAKE\_UP](oid-pnp-enable-wake-up.md) is used to enable a network adapter's wake-up capabilities. + +**For Intermediate Drivers** + +If the underlying network adapter is PM-aware, the intermediate driver should return **NDIS\_STATUS\_SUCCESS** to a query of OID\_PNP\_CAPABILITIES. In the **NDIS\_PM\_WAKE\_UP\_CAPABILITIES** structure returned by this OID, the intermediate driver should specify a device power state of **NdisDeviceStateUnspecified** for each wake-up capability ( **MinMagicPacketWakeUp** or **MinPatternWakeUp**). Such a response indicates that the intermediate driver is PM-aware but does not manage a physical device. + +If the underlying network adapter is not PM-aware, the intermediate driver should return **NDIS\_STATUS\_NOT\_SUPPORTED** to a query of OID\_PNP\_CAPABILITIES. + +**Note**  For information about how NDIS 6.20 and later miniport drivers report power management capabilities, see [Reporting Power Management Capabilities](https://msdn.microsoft.com/library/windows/hardware/ff570672). + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and NDIS 6.1. For NDIS 6.20 and later, use [OID_PM_CURRENT_CAPABILITIES](oid-pm-current-capabilities.md) instead.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) + +[**NdisMSetAttributesEx**](https://msdn.microsoft.com/library/windows/hardware/ff553623) + +[OID\_PM\_CURRENT\_CAPABILITIES](oid-pm-current-capabilities.md) + +[OID\_PNP\_ENABLE\_WAKE\_UP](oid-pnp-enable-wake-up.md) + +[OID\_PNP\_QUERY\_POWER](oid-pnp-query-power.md) + +[OID\_PNP\_SET\_POWER](oid-pnp-set-power.md) + +[Reporting Power Management Capabilities](https://msdn.microsoft.com/library/windows/hardware/ff570672) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-enable-wake-up.md b/windows-driver-docs-pr/network/oid-pnp-enable-wake-up.md new file mode 100644 index 0000000000..e00bb4fbdf --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-enable-wake-up.md @@ -0,0 +1,91 @@ +--- +title: OID\_PNP\_ENABLE\_WAKE\_UP +author: windows-driver-content +description: OID\_PNP\_ENABLE\_WAKE\_UP +ms.assetid: 9afe774b-a429-413f-a7b6-3a3d79d2b95f +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_ENABLE_WAKE_UP Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_ENABLE\_WAKE\_UP + + +## + + +As a set, the OID\_PNP\_ENABLE\_WAKE\_UP OID specifies the wake-up capabilities that a miniport driver should enable in a network adapter. + +As a query, OID\_PNP\_ENABLE\_WAKE\_UP obtains the current wake-up capabilities that are enabled for a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure is a bitmask of flags that can be used to enable a combination of wake-up events: + +**NDIS\_PNP\_WAKE\_UP\_MAGIC\_PACKET** +When set, specifies that the miniport driver should enable a network adapter to signal a wake-up event on receipt of a magic packet. (A *magic packet* is a packet that contains 16 contiguous copies of the receiving network adapter's Ethernet address.) When cleared, specifies that the miniport driver should disable the network adapter from signaling such a wake-up event. + +**NDIS\_PNP\_WAKE\_UP\_PATTERN\_MATCH** +When set, specifies that the miniport driver should enable a network adapter to signal a wake-up event on receipt of a packet that contains a pattern specified by the protocol with [OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md). When cleared, specifies that the miniport driver should disable the network adapter from signaling such a wake-up event. + +**NDIS\_PNP\_WAKE\_UP\_LINK\_CHANGE** +Reserved. NDIS ignores this flag. + +A protocol driver uses the network adapter's wake-up capabilities in [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) to enable the associated network adapter's wake-up capabilities. A protocol driver can also query this OID to determine which wake-up capabilities are enabled for a network adapter. + +NDIS does not immediately enable the wake-up capabilities that a protocol driver specifies. Instead, NDIS keeps tracks of the wake-up capabilities that the protocol driver enabled and, just before the network adapter transitions to a low-power state, NDIS sends an OID\_PNP\_ENABLE\_WAKE\_UP set request to the miniport driver to enable the appropriate wake-up events. + +Before the network adapter transitions to a low-power state (that is, before NDIS sends the miniport driver an [OID\_PNP\_SET\_POWER](oid-pnp-set-power.md) request), NDIS sends the miniport driver an OID\_PNP\_ENABLE\_WAKE\_UP request to enable the appropriate wake-up capabilities. + +The miniport driver must take the appropriate device-dependent steps to enable or disable wake-up events on the network adapter. + +The miniport driver should clear the wake-up capabilities that NDIS set with OID\_PNP\_ENABLE\_WAKE\_UP when the system is resumed. The wake-up capabilities should not be persisted across resumes. If wake-up capabilities are enabled, NDIS explicitly sets OID\_PNP\_ENABLE\_WAKE\_UP before the miniport transitions to the low-power state. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling the [**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) or [**NdisCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561711) function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [OID_PM_PARAMETERS](oid-pm-parameters.md) instead).

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NdisCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561711) + +[**NdisOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff563710) + +[OID\_PM\_PARAMETERS](oid-pm-parameters.md) + +[OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_ENABLE_WAKE_UP%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-query-power.md b/windows-driver-docs-pr/network/oid-pnp-query-power.md new file mode 100644 index 0000000000..26ca8b9a5e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-query-power.md @@ -0,0 +1,68 @@ +--- +title: OID\_PNP\_QUERY\_POWER +author: windows-driver-content +description: OID\_PNP\_QUERY\_POWER +ms.assetid: 62675042-3339-48de-97bb-58bfa05e1b39 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_QUERY_POWER Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_QUERY\_POWER + + +## + + +The OID\_PNP\_QUERY\_POWER OID requests the miniport driver to indicate whether it can transition its network adapter to the low-power state specified in the *InformationBuffer*. The low-power state is specified as one of the following NDIS\_DEVICE\_POWER\_STATE values: + +**NdisDeviceStateD1** +This specifies a device state of D1. + +**NdisDeviceStateD2** +This specifies a device state of D2. + +**NdisDeviceStateD3** +This specifies a device state of D3. + +An OID\_PNP\_QUERY\_POWER request is not used to request a transition to a device state of D0. NDIS simply sends an [OID\_PNP\_SET\_POWER](oid-pnp-set-power.md) request that specifies a device state of D0. + +By returning NDIS\_STATUS\_SUCCESS to this OID request, the miniport driver guarantees that it will transition the network adapter to the specified device power state on receipt of a subsequent OID\_PNP\_SET\_POWER request. The miniport driver, in this case, must do nothing to jeopardize the transition. + +An OID\_PNP\_QUERY\_POWER request is always followed by an OID\_PNP\_SET\_POWER request. The OID\_PNP\_SET\_POWER request may immediately follow the OID\_PNP\_QUERY\_POWER request or may arrive at an unspecified interval after the OID\_PNP\_QUERY\_POWER request. A device state of D0 specified in the OID\_PNP\_SET\_POWER request effectively cancels the OID\_PNP\_QUERY\_POWER request. + +An intermediate driver must always return NDIS\_STATUS\_SUCCESS to a query of OID\_PNP\_QUERY\_POWER. An intermediate driver should never propagate an OID\_PNP\_QUERY\_POWER request to an underlying miniport driver. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1, and NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_QUERY_POWER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-remove-wake-up-pattern.md b/windows-driver-docs-pr/network/oid-pnp-remove-wake-up-pattern.md new file mode 100644 index 0000000000..f8df03d595 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-remove-wake-up-pattern.md @@ -0,0 +1,70 @@ +--- +title: OID\_PNP\_REMOVE\_WAKE\_UP\_PATTERN +author: windows-driver-content +description: OID\_PNP\_REMOVE\_WAKE\_UP\_PATTERN +ms.assetid: 493019d0-9cd9-4712-8d18-5ee0264be9e1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_REMOVE_WAKE_UP_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_REMOVE\_WAKE\_UP\_PATTERN + + +## + + +The OID\_PNP\_REMOVE\_WAKE\_UP\_PATTERN OID requests the miniport driver to delete a wake-up pattern that it previously received in an [OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md) request. The wake-up pattern, along with its mask, is described by an [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the following: + +- An [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure that provides information about the pattern and its mask. + +- A mask that indicates which bytes of an incoming packet should be compared with corresponding bytes in the pattern. The mask starts with the first byte of the packet. The mask immediately follows the [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure in the **InformationBuffer**. + +- A wake-up pattern, which begins **PatternOffset** bytes from the beginning of the **InformationBuffer**. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling Ndis(Co)Request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [OID_PM_REMOVE_WOL_PATTERN](oid-pm-remove-wol-pattern.md) instead.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) + +[OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md) + +[OID\_PM\_REMOVE\_WOL\_PATTERN](oid-pm-remove-wol-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_REMOVE_WAKE_UP_PATTERN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-set-power.md b/windows-driver-docs-pr/network/oid-pnp-set-power.md new file mode 100644 index 0000000000..786d2b6dd2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-set-power.md @@ -0,0 +1,170 @@ +--- +title: OID\_PNP\_SET\_POWER +author: windows-driver-content +description: OID\_PNP\_SET\_POWER +ms.assetid: 21232db2-7484-4878-a2f9-5131c18ecf57 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_SET_POWER Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_SET\_POWER + + +## + + +The OID\_PNP\_SET\_POWER OID notifies a miniport driver that its underlying network adapter will be transitioning to the device power state specified in the *InformationBuffer*. The device power state is specified as one of the following [**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) values: + +- **NdisDeviceStateD0** +- **NdisDeviceStateD1** +- **NdisDeviceStateD2** +- **NdisDeviceStateD3** + +An OID\_PNP\_SET\_POWER request may be preceded by an [OID\_PNP\_QUERY\_POWER](oid-pnp-query-power.md) request. + +Starting with NDIS 6.30, NDIS will not pause and restart the NDIS drivers in the driver stack during power-state transitions if the following conditions are true: + +- The underlying miniport driver sets the **NDIS\_MINIPORT\_ATTRIBUTES\_NO\_PAUSE\_ON\_SUSPEND** flag in the [**NDIS\_MINIPORT\_ADAPTER\_REGISTRATION\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565934) structure. The driver passes a pointer to this structure in its call to the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function. + +- All overlying filter drivers that are attached to the miniport driver support NDIS 6.30 or later versions of NDIS. + +- All overlying protocol drivers that are bound to the miniport driver support NDIS 6.30 or later versions of NDIS. + +### Transitioning to a Low-Power State (D1-D3) + +When the miniport driver handles a set request of OID\_PNP\_SET\_POWER to transition to a low-power state, it must do the following: + +- Fully prepare the network adapter for the indicated network device power state. The task that is performed by the miniport driver to accomplish this is device-dependent. + +- Wait for calls to the [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) function to return. + +- Wait for send requests processed by the network adapter to complete. Once completed, the miniport driver must call the [**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) function. The driver should set the **Status** member in each [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure to the appropriate NDIS\_STATUS\_*Xxx* value. + +- Complete all pending send requests by calling the [**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) function. The driver must set the **Status** member in each [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure to **NDIS\_STATUS\_LOW\_POWER\_STATE**. + +- Reject all new send requests made to its [*MiniportSendNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559440) function immediately by calling the [**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) function. The driver must set the **Status** member in each [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure to **NDIS\_STATUS\_LOW\_POWER\_STATE**. + +The miniport driver that supports NDIS 6.30 and later versions of NDIS must also do the following: + +- Not wait for the completion of pending receive indications through calls to its [*MiniportReturnNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559437) function. Also, the miniport driver must not alter the [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure or data for any packets that are waiting to be completed. + +- Handle the OID\_PNP\_SET\_POWER request to a low-power state from either the Paused or Running adapter states. For more information about these states, see [Miniport Adapter States and Operations](https://msdn.microsoft.com/library/windows/hardware/ff560490). + +Before the network adapter transitions to the D3 state, the miniport driver must turn off everything under the miniport driver's control by performing the following tasks: + +- Disable interrupts and the DMA engine on the network adapter. + +- Stop the receive engine on the network adapter. + +- Do not deallocate or modify receive descriptors and packet buffers that are associated with pending receive indications. + +- Cancel all NDIS timers. + +**Note**  A miniport driver cannot access the network adapter after the bus driver has transitioned the network adapter to the D3 state. + +  + +### Transitioning to the Full-Power State (D0) + +When the miniport driver handles a set request of OID\_PNP\_SET\_POWER to transition to a full-power state, it must restore the receive engine of the network adapter to the same state that the receive engine was in before the adapter was transitioned to the low-power state. + +**Note**  The miniport driver must not access or change any receive buffers that are associated with pending receive indications. + +  + +NDIS calls the miniport driver's [*MiniportRestart*](https://msdn.microsoft.com/library/windows/hardware/ff559435) function after the transition to a full-power state only if NDIS called the driver's [*MiniportPause*](https://msdn.microsoft.com/library/windows/hardware/ff559418) function before the transition to a low-power state. + +**Note**  An intermediate driver must always return **NDIS\_STATUS\_SUCCESS** to a query of OID\_PNP\_SET\_POWER. An intermediate driver should never propagate an OID\_PNP\_SET\_POWER request to an underlying miniport driver. + +  + +## Return status codes + + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1, and NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[*MiniportPause*](https://msdn.microsoft.com/library/windows/hardware/ff559418) + +[*MiniportRestart*](https://msdn.microsoft.com/library/windows/hardware/ff559435) + +[*MiniportReturnNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559437) + +[*MiniportSendNetBufferLists*](https://msdn.microsoft.com/library/windows/hardware/ff559440) + +[**NDIS\_DEVICE\_POWER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/gg602135) + +[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) + +[**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_SET_POWER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-wake-up-error.md b/windows-driver-docs-pr/network/oid-pnp-wake-up-error.md new file mode 100644 index 0000000000..59a5913320 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-wake-up-error.md @@ -0,0 +1,55 @@ +--- +title: OID\_PNP\_WAKE\_UP\_ERROR +author: windows-driver-content +description: OID\_PNP\_WAKE\_UP\_ERROR +ms.assetid: e6386a35-7077-45b3-bc0c-164477168a55 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_WAKE_UP_ERROR Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_WAKE\_UP\_ERROR + + +## + + +The optional OID\_PNP\_WAKE\_UP\_ERROR OID indicates the number of false wake-ups that are signaled by the miniport driver's network adapter. A false wake-up occurs when the network adapter wakes up the system when it shouldn't have. For example, the network adapter could erroneously wake up the system due to an inexact pattern match. + +The data type for this OID is a ULONG value. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling Ndis(Co)Request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1, and NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_WAKE_UP_ERROR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-wake-up-ok.md b/windows-driver-docs-pr/network/oid-pnp-wake-up-ok.md new file mode 100644 index 0000000000..16567454fc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-wake-up-ok.md @@ -0,0 +1,55 @@ +--- +title: OID\_PNP\_WAKE\_UP\_OK +author: windows-driver-content +description: OID\_PNP\_WAKE\_UP\_OK +ms.assetid: 93389bfe-11b9-4433-8eca-4446f05d01c0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_WAKE_UP_OK Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_WAKE\_UP\_OK + + +## + + +The optional OID\_PNP\_WAKE\_UP\_OK OID indicates the number of valid wake-ups that are signaled by the miniport driver's NIC. A valid wake-up occurs when the NIC wakes up the system in response to a valid pattern match or magic packet. + +The data type for this OID is a ULONG value. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling Ndis(Co)Request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 5.1, and NDIS 6.0 and later.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_WAKE_UP_OK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-pnp-wake-up-pattern-list.md b/windows-driver-docs-pr/network/oid-pnp-wake-up-pattern-list.md new file mode 100644 index 0000000000..198d3e9451 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-pnp-wake-up-pattern-list.md @@ -0,0 +1,78 @@ +--- +title: OID\_PNP\_WAKE\_UP\_PATTERN\_LIST +author: windows-driver-content +description: OID\_PNP\_WAKE\_UP\_PATTERN\_LIST +ms.assetid: 36e4243f-5df6-4231-b1e3-63fcb2e2ec04 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_PNP_WAKE_UP_PATTERN_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_PNP\_WAKE\_UP\_PATTERN\_LIST + + +## + + +The OID\_PNP\_WAKE\_UP\_PATTERN\_LIST OID is used by a protocol to query a list of the wake-up patterns currently set for the miniport driver's network adapter. A protocol specifies a wake-up pattern with [OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md). + +OID\_PNP\_WAKE\_UP\_PATTERN\_LIST is handled by NDIS rather than the miniport driver. + +NDIS returns to the protocol a description of each wake-up pattern set in the miniport driver. Each wake-up pattern, along with its mask, is described by an [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure. + +For each wake-up pattern, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains the following: + +- An [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure that provides information about the pattern and its mask. + +- A mask that indicates which bytes of an incoming packet should be compared with corresponding bytes in the pattern. The mask starts with the first byte of the packet. The mask immediately follows the [**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) structure in the **InformationBuffer**. + +- A wake-up pattern, which begins **PatternOffset** bytes from the beginning of the **InformationBuffer**. + +An intermediate driver in which the upper edge receives this OID request must always propagate the request to the underlying miniport driver by calling Ndis(Co)Request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.0 and 6.1. For NDIS 6.20 and later, use [OID_PM_WOL_PATTERN_LIST](oid-pm-wol-pattern-list.md) instead.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_PM\_PACKET\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/ff566756) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_PM\_WOL\_PATTERN\_LIST](oid-pm-wol-pattern-list.md) + +[OID\_PNP\_ADD\_WAKE\_UP\_PATTERN](oid-pnp-add-wake-up-pattern.md) + +[OID\_PNP\_REMOVE\_WAKE\_UP\_PATTERN](oid-pnp-remove-wake-up-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_PNP_WAKE_UP_PATTERN_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-qos-current-capabilities.md b/windows-driver-docs-pr/network/oid-qos-current-capabilities.md new file mode 100644 index 0000000000..a5254385ac --- /dev/null +++ b/windows-driver-docs-pr/network/oid-qos-current-capabilities.md @@ -0,0 +1,122 @@ +--- +title: OID\_QOS\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_QOS\_CURRENT\_CAPABILITIES to obtain the currently enabled NDIS Quality of Service (QoS) hardware capabilities of a network adapter. +ms.assetid: E9013EB2-5EDB-4BCB-BC1D-17345B85D1C4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_QOS_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_QOS\_CURRENT\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_QOS\_CURRENT\_CAPABILITIES to obtain the currently enabled NDIS Quality of Service (QoS) hardware capabilities of a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure. + +**Note**  This OID query request is handled by NDIS for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +Miniport drivers register the currently-enabled NDIS QoS hardware capabilities of a network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver registers these capabilities by following these steps: + +1. The driver initializes an [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure with the enabled QoS hardware capabilities. + +2. The driver sets the **CurrentQosCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure. + +3. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure. + +**Note**  NDIS does not report the currently-enabled NDIS QoS hardware capabilities of a network adapter to overlying protocol and filter drivers during the bind or attach operations. + +  + +For more information on how to register NDIS QoS capabilities, see [Registering NDIS QoS Capabilities](https://msdn.microsoft.com/library/windows/hardware/hh440188). + +### Return Status Codes + +NDIS handles the OID query request of OID\_QOS\_CURRENT\_CAPABILITIES request for miniport drivers, and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver does not support the NDIS QoS interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_QOS_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/hh451629)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_QOS_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-qos-hardware-capabilities.md b/windows-driver-docs-pr/network/oid-qos-hardware-capabilities.md new file mode 100644 index 0000000000..7c386aa412 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-qos-hardware-capabilities.md @@ -0,0 +1,128 @@ +--- +title: OID\_QOS\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_QOS\_HARDWARE\_CAPABILITIES to obtain the NDIS Quality of Service (QoS) hardware capabilities of a network adapter. +ms.assetid: 50D93F3F-DEA0-4D7D-8866-4155EED8D8BC +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_QOS_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_QOS\_HARDWARE\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_QOS\_HARDWARE\_CAPABILITIES to obtain the NDIS Quality of Service (QoS) hardware capabilities of a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure. + +**Note**  This OID query request is handled by NDIS for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +The [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure contains information about the NDIS QoS hardware capabilities of a network adapter. These capabilities can include hardware capabilities that are currently disabled by INF file settings or through the **Advanced** properties page. + +**Note**  All the NDIS QoS hardware capabilities of a network adapter are returned through an OID query request of OID\_QOS\_HARDWARE\_CAPABILITIES, regardless of whether a capability is enabled or disabled. + +  + +Miniport drivers registers the NDIS QoS hardware capabilities of a network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver registers these capabilities by following these steps: + +1. The driver initializes an [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure with the NDIS QoS hardware capabilities. + +2. The driver sets the **HardwareQosCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the [**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) structure. + +3. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure. + +**Note**  NDIS does not report the NDIS QoS hardware capabilities of a network adapter to overlying protocol and filter drivers during the bind or attach operations. + +  + +For more information on how to register NDIS QoS capabilities, see [Registering NDIS QoS Capabilities](https://msdn.microsoft.com/library/windows/hardware/hh440188). + +### Return Status Codes + +NDIS handles the OID query request of OID\_QOS\_HARDWARE\_CAPABILITIES request for miniport drivers, and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver does not support the NDIS QoS interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_QOS_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/hh451629)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_QOS_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-qos-operational-parameters.md b/windows-driver-docs-pr/network/oid-qos-operational-parameters.md new file mode 100644 index 0000000000..2726b4a6f3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-qos-operational-parameters.md @@ -0,0 +1,120 @@ +--- +title: OID\_QOS\_OPERATIONAL\_PARAMETERS +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_QOS\_OPERATIONAL\_PARAMETERS to obtain the current NDIS Quality of Service (QoS) operational parameters for a network adapter. +ms.assetid: 546EE7C6-BCED-4FF9-9B87-A36199B1B31C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_QOS_OPERATIONAL_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_QOS\_OPERATIONAL\_PARAMETERS + + +An overlying driver issues an object identifier (OID) query request of OID\_QOS\_OPERATIONAL\_PARAMETERS to obtain the current NDIS Quality of Service (QoS) operational parameters for a network adapter. The miniport driver configures the network adapter with the operational NDIS QoS parameters in order to perform QoS packet transmission. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. + +**Note**  This OID query request is handled by NDIS for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +When NDIS handles the OID query request of OID\_QOS\_OPERATIONAL\_PARAMETERS successfully, it returns the operational NDIS QoS parameters that it had cached from the previous [**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) status indication that was issued by the miniport driver. The driver issues this status indication to report on the initial set of operational NDIS QoS parameters. The driver also issues this status indication whenever the operational NDIS QoS parameters change. + +NDIS returns an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure that is initialized in the following way: + +- If the miniport driver previously issued an [**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) status indication, NDIS caches the [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) data and returns this data for the OID query request of OID\_QOS\_OPERATIONAL\_PARAMETERS. + +- If the miniport driver did not issue an [**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) status indication, NDIS returns an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure with all the members (with the exception of the **Header** member) set to zero. + +For more information on operational NDIS QoS parameters, see [Overview of NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440130). + +### Return Status Codes + +NDIS returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver does not support the NDIS QoS interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_QOS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451640)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMOidRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) + +[**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) + +[**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) + +[OID\_QOS\_PARAMETERS](oid-qos-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_QOS_OPERATIONAL_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-qos-parameters.md b/windows-driver-docs-pr/network/oid-qos-parameters.md new file mode 100644 index 0000000000..085fdfcc4d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-qos-parameters.md @@ -0,0 +1,164 @@ +--- +title: OID\_QOS\_PARAMETERS +author: windows-driver-content +description: The Data Center Bridging (DCB) component (Msdcb.sys) issues an object identifier (OID) method request of OID\_QOS\_PARAMETERS to configure the local NDIS Quality of Service (QoS) parameters on a network adapter. +ms.assetid: 1CA97C8A-8F5B-4AB2-B68E-DF1FA772C08F +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_QOS_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_QOS\_PARAMETERS + + +The Data Center Bridging (DCB) component (Msdcb.sys) issues an object identifier (OID) method request of OID\_QOS\_PARAMETERS to configure the local NDIS Quality of Service (QoS) parameters on a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. + +**Note**  This OID method request is mandatory for miniport drivers that support NDIS QoS for the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +Miniport drivers obtain the local NDIS QoS parameters through an OID method request of OID\_QOS\_PARAMETERS. These parameters define how the network adapter prioritizes transmit, or *egress*, packets. For more information about these parameters, see [Overview of NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440130). + +**Note**  Only the DCB component can issue an OID method request of OID\_QOS\_PARAMETERS. An overlying protocol or filter driver must not issue this OID. For more information on the DCB component, see [NDIS QoS Architecture for Data Center Bridging](https://msdn.microsoft.com/library/windows/hardware/hh451627). + +  + +The DCB component issues an OID\_QOS\_PARAMETERS request under the following conditions: + +- The system administrator installs or uninstalls the Microsoft DCB server feature. + + For more information about the DCB server feature, see [System-Provided DCB Components](https://msdn.microsoft.com/library/windows/hardware/hh440259). + +- The system administrator enables or disables the DCB server feature while the feature is still installed. + +- The system administrator changes any of the DCB server feature parameters. + +- The operating system starts or restarts while the DCB server feature is installed. + +When the miniport driver handles the OID method request of OID\_QOS\_PARAMETERS, it must follow these guidelines: + +- The miniport driver copies the data within the [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure to its cache of local NDIS QoS parameters. The driver then resolves its operational NDIS QoS parameters based on its cache of local NDIS QoS parameters and its cache of NDIS QoS parameters that it received from a remote peer. + + For more information about how the miniport driver resolves its operational parameters, see [Resolving Operational NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440220). + +- The miniport driver must not modify any data that is contained within the [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. The driver must complete the OID method request and return the original data within the **NDIS\_QOS\_PARAMETERS** structure. + +- The **NDIS\_QOS\_PARAMETERS\_WILLING** flag specifies whether the miniport driver enables or disables the local Data Center Bridging Exchange (DCBX) Willing state. The driver handles this flag in the following way: + + - If this flag is set, the miniport driver must enable the local DCBX Willing state. This allows the driver to be remotely configured with QoS settings. In this case, the driver resolves its operational QoS parameters based on the remote QoS parameters. The miniport driver can also resolve its operational QoS parameters based on any proprietary QoS settings that are defined by the independent hardware vendor (IHV). + + - If this flag is not set, the miniport driver must disable the local DCBX Willing state. This allows the driver to resolve its operational QoS parameters from its local QoS parameters instead of remote QoS parameters. The miniport driver must also disable or override any local QoS parameter for which the related **NDIS\_QOS\_PARAMETERS\_*Xxx*\_CONFIGURED** flag is not set. + + For example, the miniport driver can override an unconfigured local QoS parameter with its proprietary settings for the QoS parameter that is defined by the IHV. If there are no proprietary settings for local QoS parameters that are not specified with an **NDIS\_QOS\_PARAMETERS\_*Xxx*\_CONFIGURED** flag, the driver must disable the use of these QoS parameters on the network adapter. + + **Note**  The driver can also override configured local QoS parameters if they compromise the QoS parameters used by protocols or technologies that are enabled on the network adapter. For example, the driver can override the local QoS parameters if the network adapter is enabled for remote boot through the Fibre Channel over Ethernet (FCoE) protocol. + +   + + For more information about the local DCBX Willing state, see [Managing the Local DCBX Willing State](https://msdn.microsoft.com/library/windows/hardware/hh706282). + + For more information on how the miniport driver overrides local QoS parameters, see [Managing NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh464015). + + **Note**  Overriding the local QoS parameters should not cause the miniport driver to fail the OID method request of OID\_QOS\_PARAMETERS. + +   + +For more information on how the miniport driver manages the local QoS parameters, see [Setting Local NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440225). + +### Return Status Codes + +The miniport driver returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_PENDING

The OID request is pending completion. When the miniport driver calls [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622), NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is completed.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver does not support the NDIS QoS interface.

NDIS_STATUS_INVALID_PARAMETER

One or more members of the [NDIS_QOS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure contain incorrect values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_QOS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451640)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMOidRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) + +[**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) + +[**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_QOS_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-qos-remote-parameters.md b/windows-driver-docs-pr/network/oid-qos-remote-parameters.md new file mode 100644 index 0000000000..c808ea0a11 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-qos-remote-parameters.md @@ -0,0 +1,120 @@ +--- +title: OID\_QOS\_REMOTE\_PARAMETERS +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_QOS\_REMOTE\_PARAMETERS to obtain the NDIS Quality of Service (QoS) parameters for a remote peer. +ms.assetid: F9DA87FF-577F-4E06-929B-4AD65105B2F0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_QOS_REMOTE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_QOS\_REMOTE\_PARAMETERS + + +An overlying driver issues an object identifier (OID) query request of OID\_QOS\_REMOTE\_PARAMETERS to obtain the NDIS Quality of Service (QoS) parameters for a remote peer. The miniport driver uses these remote QoS parameters to resolve its operational NDIS QoS parameters. The driver configures the network adapter with the operational parameters in order to perform QoS packet transmission. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure. + +**Note**  This OID query request is valid only for miniport drivers that support the IEEE 802.1 Data Center Bridging (DCB) interface. + +  + +Remarks +------- + +When NDIS handles the OID request of OID\_QOS\_REMOTE\_PARAMETERS successfully, it returns the remote NDIS QoS parameters that it had cached from the previous [**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) status indication that was issued by the miniport driver. The driver issues this status indication to report on the initial set of remote NDIS QoS parameters. The driver also issues this status indication whenever the remote NDIS QoS parameters change. + +NDIS returns an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure that is initialized in the following way: + +- If the miniport driver previously issued an [**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) status indication, NDIS caches the [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) data and returns this data for the OID query request of OID\_QOS\_REMOTE\_PARAMETERS. + +- If the miniport driver did not issue an [**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) status indication, NDIS returns an [**NDIS\_QOS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451640) structure with all the members (with the exception of the **Header** member) set to zero. + +For more information on remote NDIS QoS parameters, see [Overview of NDIS QoS Parameters](https://msdn.microsoft.com/library/windows/hardware/hh440130). + +### Return Status Codes + +NDIS returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver does not support the NDIS QoS interface.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_QOS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451640)). NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisMOidRequestComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563622) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_QOS\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451629) + +[**NDIS\_STATUS\_QOS\_OPERATIONAL\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439810) + +[**NDIS\_STATUS\_QOS\_REMOTE\_PARAMETERS\_CHANGE**](https://msdn.microsoft.com/library/windows/hardware/hh439812) + +[OID\_QOS\_PARAMETERS](oid-qos-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_QOS_REMOTE_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-allocate-queue.md b/windows-driver-docs-pr/network/oid-receive-filter-allocate-queue.md new file mode 100644 index 0000000000..96f18ab80b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-allocate-queue.md @@ -0,0 +1,137 @@ +--- +title: OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE +author: windows-driver-content +description: Overlying drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE to allocate a queue that has an initial set of configuration parameters. +ms.assetid: 8dd7ab91-b752-46fd-ae1b-014dc0fb0157 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_ALLOCATE_QUEUE Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE + + +Overlying drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE to allocate a queue that has an initial set of configuration parameters. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure. After a successful return from the OID method request, the **InformationBuffer** member of the **NDIS\_OID\_REQUEST** structure contains a pointer to an **NDIS\_RECEIVE\_QUEUE\_PARAMETERS** structure that has a new queue identifier. + +Remarks +------- + +The OID method request of OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue (VMQ) interface. + +The overlying driver initializes the [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure with its requested queue configuration. NDIS assigns a queue identifier in the **QueueId** member of the **NDIS\_RECEIVE\_QUEUE\_PARAMETERS** structure and passes the method request to the miniport driver. + +**Note**  The overlying driver can set the **NDIS\_RECEIVE\_QUEUE\_PARAMETERS\_PER\_QUEUE\_RECEIVE\_INDICATION** and **NDIS\_RECEIVE\_QUEUE\_PARAMETERS\_LOOKAHEAD\_SPLIT\_REQUIRED** flags in the **Flags** member of the [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure. The other flags are not used for queue allocation. + +  + +After a miniport driver is issued an OID request of OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE and handles it successfully, the queue is in the Paused state. + +The overlying driver must use the queue identifier that NDIS provides in subsequent OID requests, for example, to modify the queue parameters or free the queue. The queue identifier is also included in the out-of-band (OOB) data on all [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structures that are associated with the queue. Drivers use the [**NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff568407) macro to retrieve the queue identifier in a **NET\_BUFFER\_LIST** structure. + +When NDIS receives an OID request to allocate a receive queue, it verifies the queue parameters. After NDIS allocates the necessary resources and the queue identifier, it submits the OID request to the underlying miniport driver. The queue identifier is unique to the associated network adapter. + +If the miniport driver can successfully allocate the necessary software and hardware resources for the receive queue, it completes the OID request by returning **NDIS\_STATUS\_SUCCESS**. + +The miniport driver must retain the queue identifiers for the allocated receive queues. NDIS uses the queue identifier of a receive queue for subsequent calls to the miniport driver in order to set a receive filter on the receive queue, change the receive queue parameters, or free the receive queue. + +After an overlying driver allocates one or more receive queues and optionally sets the initial filters, it must issue [OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE](oid-receive-filter-queue-allocation-complete.md) set OID requests to notify the miniport driver that the allocation is complete for the current batch of receive queues. + +The miniport driver must not retain any packets in a receive queue if there are no filters set on that queue. If either a queue never had any filters set or all the filters were cleared, the queue should be empty and any packets should be discarded. That is, the packets are not indicated up the driver stack or retained in the queue. + +Overlying drivers use OID requests of [OID\_RECEIVE\_FILTER\_FREE\_QUEUE](oid-receive-filter-free-queue.md) to free queues that they allocate. + +### Return Status Codes + +Either NDIS or the miniport driver returns one of the following status codes for the OID method request of OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeDescription

NDIS_STATUS_SUCCESS

The queue was allocated successfully. The information buffer contains the updated [NDIS_RECEIVE_QUEUE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure.

NDIS_STATUS_PENDING

The request is pending completion. The final status code and results will be passed to an OID request completion handler of the caller.

NDIS_STATUS_INVALID_PARAMETER

One or more of the parameters that the overlying driver provided were not valid.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_NOT_SUPPORTED

The NDIS version of the miniport driver is earlier than version 6.20.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff568407) + +[OID\_RECEIVE\_FILTER\_FREE\_QUEUE](oid-receive-filter-free-queue.md) + +[OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE](oid-receive-filter-queue-allocation-complete.md) + +[**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_ALLOCATE_QUEUE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-clear-filter.md b/windows-driver-docs-pr/network/oid-receive-filter-clear-filter.md new file mode 100644 index 0000000000..616e7144c4 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-clear-filter.md @@ -0,0 +1,157 @@ +--- +title: OID\_RECEIVE\_FILTER\_CLEAR\_FILTER +author: windows-driver-content +description: Overlying drivers issue OID set requests of OID\_RECEIVE\_FILTER\_CLEAR\_FILTER to clear a receive filter on a network adapter. +ms.assetid: 5e92a11a-468e-431d-b4e5-7b0da3847e8a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_CLEAR_FILTER Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_CLEAR\_FILTER + + +Overlying drivers issue OID set requests of OID\_RECEIVE\_FILTER\_CLEAR\_FILTER to clear a receive filter on a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_CLEAR\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567166) structure. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +The OID set request of OID\_RECEIVE\_FILTER\_CLEAR\_FILTER is mandatory for miniport drivers that support the NDIS packet coalescing, SR-IOV, or VMQ interface. + +An overlying driver, such as an NDIS protocol or filter driver, uses the OID\_RECEIVE\_FILTER\_CLEAR\_FILTER set request to clear a previously set filter. Only the driver that set the receive filter can clear it. + +The overlying driver clears a receive filter by setting the **FilterId** member of the [**NDIS\_RECEIVE\_FILTER\_CLEAR\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567166) structure to the identifier for the filter. The driver obtained the filter identifier from an earlier OID method request of [OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md). + +### Additional Instructions for NDIS Packet Coalescing + +The following point applies to miniport and overlying drivers that support NDIS packet coalescing: + +- An overlying driver must clear all the receive filters that it set on the miniport driver before it unbinds or detaches from the driver. + +### Additional Guidelines for the SR-IOV Interface + +The following points apply to miniport and overlying drivers that support the SR-IOV interface: + +- An overlying driver must clear all the filters that it set on a SR-IOV VPort before it frees the VPort. The overlying driver must also clear all the filters that it set on the default VPort before it closes its binding to the network adapter. + +- A miniport driver must not indicate packets on a nondefault VPort if it has completed the OID request of OID\_RECEIVE\_FILTER\_CLEAR\_FILTER to clear the last filter on the VPort. + + **Note**  A miniport driver also must not indicate packets on a nondefault VPort if it has completed an OID request of [OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) to free the VPort. + +   + +### Additional Guidelines for the VMQ Interface + +The following points apply to miniport and overlying drivers that support the VMQ interface: + +- An overlying driver must clear all the filters that it set on a VMQ receive queue before it frees the queue. The overlying driver must also clear all the filters that it set on the default or drop queues before it closes its binding to the network adapter. + +- A miniport driver must not indicate packets on a receive queue if it has completed the OID request of OID\_RECEIVE\_FILTER\_CLEAR\_FILTER to clear the last filter on the receive queue. + + **Note**  A miniport driver also must not indicate packets on a receive queue if it has completed an OID request of [OID\_RECEIVE\_FILTER\_FREE\_QUEUE](oid-receive-filter-free-queue.md) to free the receive queue. + +   + +### Return status codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport adapter has been surprise removed.

+ +  + +NDIS returns one of the following status codes for this request: + +**NDIS\_STATUS\_SUCCESS** +The specified filter was cleared successfully. + +**NDIS\_STATUS\_PENDING** +The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request is complete. + +**NDIS\_STATUS\_FILE\_NOT\_FOUND** +The filter identifier is not valid. + +**NDIS\_STATUS\_INVALID\_LENGTH** +The information buffer is too small. NDIS sets the **DATA.SET\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_CLEAR\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567166) + +[OID\_NIC\_SWITCH\_DELETE\_VPORT](oid-nic-switch-delete-vport.md) + +[OID\_RECEIVE\_FILTER\_FREE\_QUEUE](oid-receive-filter-free-queue.md) + +[OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_CLEAR_FILTER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-current-capabilities.md b/windows-driver-docs-pr/network/oid-receive-filter-current-capabilities.md new file mode 100644 index 0000000000..5b2b0435e6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-current-capabilities.md @@ -0,0 +1,105 @@ +--- +title: OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES to obtain the currently enabled receive filtering capabilities of a network adapter. +ms.assetid: bd4f5b9b-e33b-42ba-a430-b3b6108c80b1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES + + +Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES to obtain the currently enabled receive filtering capabilities of a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +Starting with NDIS 6.20, miniport drivers register the currently enabled receive filtering hardware capabilities of the network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. Miniport drivers register these capabilities by following these steps: + +1. The driver initializes an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure with the currently enabled receive filtering hardware capabilities. + +2. The driver initializes an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure and sets the **CurrentReceiveFilterCapabilities** member to a pointer to the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +3. The miniport driver calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure. + +Overlying protocol and filter drivers do not have to issue OID query requests of OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES. NDIS provides the currently enabled receive filtering capabilities to these drivers in the following way: + +- NDIS provides the currently enabled receive filtering capabilities of an underlying network adapter to overlying protocol drivers in the **ReceiveFilterCapabilities** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure during the bind operation. + +- NDIS provides the currently enabled receive filtering capabilities of an underlying network adapter to overlying filter drivers in the **ReceiveFilterCapabilities** member of the [**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) structure during the attach operation. + +### Return status codes + +NDIS handles the OID query request of OID\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES for miniport drivers, and returns one of the following status codes: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS passes the final status code and results to the OID request completion handler of the caller after the request has completed. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The network adapter does not support receive filtering. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-enum-filters.md b/windows-driver-docs-pr/network/oid-receive-filter-enum-filters.md new file mode 100644 index 0000000000..ad07eda97c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-enum-filters.md @@ -0,0 +1,120 @@ +--- +title: OID\_RECEIVE\_FILTER\_ENUM\_FILTERS +author: windows-driver-content +description: An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_ENUM\_FILTERS to obtain a list of all the filters that are configured on a network adapter. +ms.assetid: 498c1e96-c3ee-4f5d-b0f2-6e88921187e5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_ENUM_FILTERS Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_ENUM\_FILTERS + + +An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_ENUM\_FILTERS to obtain a list of all the filters that are configured on a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure. + +After a successful return from the OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure that specifies a list of receive filters that are currently configured on a miniport driver. + +- An array of [**NDIS\_RECEIVE\_FILTER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567176) structures. Each structure specifies the parameters of a receive filter that is currently configured on a miniport driver. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +Overlying drivers or applications issue OID method requests of OID\_RECEIVE\_FILTER\_ENUM\_FILTERS to enumerate the receive filters that were set on a network adapter. This includes receive filters that were set on an SR-IOV virtual port (VPort) or a VMQ receive queue. + +### Additional Guidelines for the NDIS Packet Coalescing Interface + +Starting with Windows Server 2012, NDIS packet coalescing only supports the default receive queue of a network adapter. + +To enumerate the packet coalescing receive filters, the overlying driver must set the **QueueId** member of the [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure to NDIS\_DEFAULT\_RECEIVE\_QUEUE\_ID. + +### Additional Guidelines for the SR-IOV Interface + +Starting with Windows Server 2012, the SR-IOV interface only supports the default receive queue of a virtual port (VPort). + +To enumerate the VPort receive filters, the overlying driver must set the **QueueId** member of the [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure to NDIS\_DEFAULT\_RECEIVE\_QUEUE\_ID. + +### Additional Guidelines for the VMQ Interface + +An overlying driver can issue OID method requests of OID\_RECEIVE\_FILTER\_ENUM\_FILTERS to enumerate the receive filters that were set on a VMQ receive queue. When the overlying driver initializes the [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure, it sets the **QueueId** member to one of the following values: + +- The queue identifier value for a nondefault receive queue. The overlying driver obtained the queue identifier input value from an earlier OID method request of [OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) or an OID query request of [OID\_RECEIVE\_FILTER\_ENUM\_QUEUES](oid-receive-filter-enum-queues.md). + +- The queue identifier value of NDIS\_DEFAULT\_RECEIVE\_QUEUE\_ID, which specifies the default receive queue. + +### Return status codes + +NDIS handles the OID method request of OID\_RECEIVE\_FILTER\_ENUM\_FILTERS for miniport drivers, and returns one of the following status codes: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS passes the final status code and results to the OID request completion handler of the caller after the request has completed. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567176) + +[**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) + +[OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) + +[OID\_RECEIVE\_FILTER\_ENUM\_QUEUES](oid-receive-filter-enum-queues.md) + +[OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_ENUM_FILTERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-enum-queues.md b/windows-driver-docs-pr/network/oid-receive-filter-enum-queues.md new file mode 100644 index 0000000000..61ba09e7f0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-enum-queues.md @@ -0,0 +1,109 @@ +--- +title: OID\_RECEIVE\_FILTER\_ENUM\_QUEUES +author: windows-driver-content +description: Overlying drivers and user-mode applications issue object identifier (OID) query requests of OID\_RECEIVE\_FILTER\_ENUM\_QUEUES to obtain a list of all the receive queues that are allocated on a network adapter. +ms.assetid: e8a946a2-9ee9-42a0-8175-fbc592d404d1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_ENUM_QUEUES Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_ENUM\_QUEUES + + +Overlying drivers and user-mode applications issue object identifier (OID) query requests of OID\_RECEIVE\_FILTER\_ENUM\_QUEUES to obtain a list of all the receive queues that are allocated on a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_QUEUE\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567205) structure that is followed by an [**NDIS\_RECEIVE\_QUEUE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567204) structure for each filter. + +Remarks +------- + +NDIS obtained the information from an internal cache of the data that it received from the [OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) and [OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS](oid-receive-filter-queue-parameters.md) OID requests. + +Overlying drivers and user-mode applications issue OID query requests of OID\_RECEIVE\_FILTER\_ENUM\_QUEUES to enumerate the receive queues on a network adapter. + +If a protocol driver issues the request, the request type inside the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure is set to **NdisRequestQueryInformation** and this OID returns an array of all the receive queues that the protocol driver allocated on the network adapter. If a user-mode application issued the request, the request type inside the **NDIS\_OID\_REQUEST** structure is set to **NdisRequestQueryStatistics**, and this OID returns an array of information for all the receive queues on the network adapter. + +### Return Status Codes + +NDIS handles the OID query request of OID\_RECEIVE\_FILTER\_ENUM\_QUEUES for miniport drivers, and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeDescription

NDIS_STATUS_SUCCESS

The request completed successfully. The InformationBuffer points to an [NDIS_RECEIVE_QUEUE_INFO_ARRAY](https://msdn.microsoft.com/library/windows/hardware/ff567205) structure.

NDIS_STATUS_PENDING

The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request has completed.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_QUEUE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567204) + +[**NDIS\_RECEIVE\_QUEUE\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567205) + +[OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) + +[OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS](oid-receive-filter-queue-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_ENUM_QUEUES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-free-queue.md b/windows-driver-docs-pr/network/oid-receive-filter-free-queue.md new file mode 100644 index 0000000000..a21a34a901 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-free-queue.md @@ -0,0 +1,162 @@ +--- +title: OID\_RECEIVE\_FILTER\_FREE\_QUEUE +author: windows-driver-content +description: NDIS protocol drivers issue object identifier (OID) set requests of OID\_RECEIVE\_FILTER\_FREE\_QUEUE to free a receive queue. +ms.assetid: ee8cff69-2f5e-4798-9c18-28e996dd1dd4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_FREE_QUEUE Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_FREE\_QUEUE + + +NDIS protocol drivers issue object identifier (OID) set requests of OID\_RECEIVE\_FILTER\_FREE\_QUEUE to free a receive queue. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_QUEUE\_FREE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567201) structure with a queue identifier of type **NDIS\_RECEIVE\_QUEUE\_ID**. + +Remarks +------- + +The OID set request of OID\_RECEIVE\_FILTER\_FREE\_QUEUE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue interface. + +After an overlying driver issues the [OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) OID to allocate a receive queue, it issues the OID\_RECEIVE\_FILTER\_FREE\_QUEUE OID to free the receive queue. + +When NDIS requests a miniport driver to free a VMQ receive queue, it follows these steps: + +1. The network adapter stops the DMA transfer of data to receive buffers that are associated with the receive queue, after which the queue must enter the DMA Stopped state. The network adapter probably stopped the DMA activity when it received the [OID\_RECEIVE\_FILTER\_CLEAR\_FILTER](oid-receive-filter-clear-filter.md) OID request to clear the last set filter on the receive queue. + +2. The miniport driver generates an [**NDIS\_STATUS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567417) status indication with the **QueueState** member of the [**NDIS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567214) structure set to **NdisReceiveQueueOperationalStateDmaStopped** to notify NDIS that the DMA transfer has been stopped. + +3. The miniport driver waits for all the indicated receive packets for that queue to be returned to the miniport driver. + +4. The miniport driver frees all the shared memory that it allocated for the network adapter's receive buffers that are associated with the queue by calling [**NdisFreeSharedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff562601). + +5. The miniport driver completes the OID\_RECEIVE\_FILTER\_FREE\_QUEUE OID request to free the receive queue. + +Miniport drivers call the [**NdisFreeSharedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff562601) function to free shared memory for a queue. If the miniport driver allocated the shared memory for a nondefault queue, the driver frees the shared memory in the context of the OID\_RECEIVE\_FILTER\_FREE\_QUEUE OID while it is freeing the queue. Miniport drivers free shared memory that they allocated for the default queue in the context of the [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) function. + +An overlying driver must free all the filters that it set on a queue before it frees the queue. Also, an overlying driver must free all the receive queues that it allocated on a network adapter before it calls the [**NdisCloseAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff561640) function to close a binding to the network adapter. NDIS frees all the queues that are allocated on a network adapter before it calls the miniport driver's [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) function. + +### Return Status Codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +NDIS returns one of the following status codes for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeDescription

NDIS_STATUS_SUCCESS

The requested queue was freed successfully.

NDIS_STATUS_PENDING

The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler for the caller after the request has completed.

NDIS_STATUS_INVALID_PARAMETER

The queue identifier is invalid.

NDIS_STATUS_INVALID_LENGTH

The information buffer is too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_QUEUE\_FREE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567201) + +[**NDIS\_STATUS\_RECEIVE\_QUEUE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567417) + +[**NdisCloseAdapterEx**](https://msdn.microsoft.com/library/windows/hardware/ff561640) + +[**NdisFreeSharedMemory**](https://msdn.microsoft.com/library/windows/hardware/ff562601) + +[OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_FREE_QUEUE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-global-parameters.md b/windows-driver-docs-pr/network/oid-receive-filter-global-parameters.md new file mode 100644 index 0000000000..623f24acf5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-global-parameters.md @@ -0,0 +1,89 @@ +--- +title: OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS +author: windows-driver-content +description: Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS to obtain the global receive filtering parameters of a network adapter. +ms.assetid: be6f7210-d1f9-4490-838a-806488df41da +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_GLOBAL_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS + + +Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS to obtain the global receive filtering parameters of a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567171) structure. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +Starting with NDIS 6.20, protocol drivers use OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS to query the current global configuration parameters for receive filtering on a network adapter. For example, protocol drivers can use this OID to determine whether types of receive filters or receive queues are enabled or disabled. + +### Return status codes + +NDIS handles the OID query request of OID\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS for miniport drivers, and returns one of the following status codes: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS passes the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_INVALID\_PARAMETER +The request failed because it tried to enable a capability that the underlying network adapter does not support. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_GLOBAL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567171) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_GLOBAL_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-hardware-capabilities.md b/windows-driver-docs-pr/network/oid-receive-filter-hardware-capabilities.md new file mode 100644 index 0000000000..7c4c64864b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-hardware-capabilities.md @@ -0,0 +1,105 @@ +--- +title: OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES to obtain the receive filtering hardware capabilities of a network adapter. +ms.assetid: 2b80944e-5309-4cb0-a69a-331f8fd3f7a4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES + + +Overlying drivers issue OID query requests of OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES to obtain the receive filtering hardware capabilities of a network adapter. + +After a successful return from the OID query request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +The [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure contains information about the receive filtering hardware capabilities of a network adapter. These capabilities can include hardware capabilities that are currently disabled by INF file settings or through the **Advanced** properties page. + +**Note**  All the receive filtering hardware capabilities of a network adapter are returned through an OID query request of OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES, regardless of whether a capability is enabled or disabled. + +  + +Starting with NDIS 6.20, miniport drivers register the currently enabled receive filtering hardware capabilities of the network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. Miniport drivers register these capabilities by following these steps: + +1. The driver initializes an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure with the receive filtering hardware capabilities. + +2. The driver initializes an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure and sets the **CurrentReceiveFilterCapabilities** member to a pointer to the [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +3. The miniport driver calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure. + +### Return status codes + +NDIS handles the OID query request of OID\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES for miniport drivers, and returns one of the following status codes: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS passes the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS set the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The network adapter does not support receive filtering. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-move-filter.md b/windows-driver-docs-pr/network/oid-receive-filter-move-filter.md new file mode 100644 index 0000000000..4b227c2da9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-move-filter.md @@ -0,0 +1,110 @@ +--- +title: OID\_RECEIVE\_FILTER\_MOVE\_FILTER +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_RECEIVE\_FILTER\_MOVE\_FILTER to move a previously configured receive filter. +ms.assetid: CC899ABD-EE6B-4932-889F-984C8B5A403F +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_MOVE_FILTER Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_MOVE\_FILTER + + +An overlying driver issues an object identifier (OID) set request of OID\_RECEIVE\_FILTER\_MOVE\_FILTER to move a previously configured receive filter. Receive filters are moved from one virtual port (VPort) to a different VPort. + +Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID set request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_MOVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451651) structure. + +Remarks +------- + +NDIS validates the members of the [**NDIS\_RECEIVE\_FILTER\_MOVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451651) structure before it forwards the OID set request to the PF miniport driver. + +The PF miniport driver must handle this OID set request atomically. The driver must be able to configure the network adapter to simultaneously remove the filter from a receive queue and VPort and set it on a different receive queue and VPort. + +For more information, see [Moving a Receive Filter to a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh464102). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID set request of OID\_RECEIVE\_FILTER\_MOVE\_FILTER. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_RECEIVE_FILTER_MOVE_FILTER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451651) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is less than sizeof([NDIS_RECEIVE_FILTER_MOVE_FILTER_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451651)). The PF miniport driver must set the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_MOVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451651) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_MOVE_FILTER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-parameters.md b/windows-driver-docs-pr/network/oid-receive-filter-parameters.md new file mode 100644 index 0000000000..7b665a8c99 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-parameters.md @@ -0,0 +1,101 @@ +--- +title: OID\_RECEIVE\_FILTER\_PARAMETERS +author: windows-driver-content +description: An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_PARAMETERS to obtain the current configuration parameters of a filter on a network adapter. +ms.assetid: 1bb12945-0dad-47b9-9f44-e05efe292979 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_PARAMETERS + + +An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_PARAMETERS to obtain the current configuration parameters of a filter on a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure. NDIS uses the **FilterId** member in the input structure to identify the filter. + +After a successful return from the OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure that specifies the parameters for an NDIS receive filter. + +- An array of [**NDIS\_RECEIVE\_FILTER\_FIELD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567169) structures that specifies the filter test criterion for a field in a network packet header. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +Overlying drivers issue OID method requests of OID\_RECEIVE\_FILTER\_PARAMETERS to obtain the configuration parameters for a receive filter that was set on a network adapter. This includes a receive filter that was set on a VMQ receive queue or SR-IOV virtual port (VPort), as well as a packet coalescing filter that was downloaded to the miniport driver. + +The overlying driver obtained the filter identifier from an earlier OID method request of [OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md) or from OID requests of [OID\_RECEIVE\_FILTER\_ENUM\_FILTERS](oid-receive-filter-enum-filters.md). + +### Return status codes + +NDIS handles the OID request of OID\_RECEIVE\_FILTER\_PARAMETERS for miniport drivers, and returns one of the following status codes: + +NDIS\_STATUS\_SUCCESS +The request completed successfully. The **InformationBuffer** points to an [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. NDIS passes the final status code and results to the OID request completion handler of the caller after the request is complete. + +NDIS\_STATUS\_INVALID\_PARAMETER +The overlying driver or application provided an invalid filter identifier. A filter identifier is not valid if it is zero or if it specifies an undefined filter. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS sets the **DATA.QUERY\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[OID\_RECEIVE\_FILTER\_ENUM\_FILTERS](oid-receive-filter-enum-filters.md) + +[**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) + +[OID\_RECEIVE\_FILTER\_SET\_FILTER](oid-receive-filter-set-filter.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-queue-allocation-complete.md b/windows-driver-docs-pr/network/oid-receive-filter-queue-allocation-complete.md new file mode 100644 index 0000000000..53dfaef963 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-queue-allocation-complete.md @@ -0,0 +1,115 @@ +--- +title: OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE +author: windows-driver-content +description: NDIS protocol drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE to notify the miniport driver that an allocation has completed for the current batch of receive queues. +ms.assetid: d09fcab5-4c3b-432a-ba9e-fd4269537de6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE + + +NDIS protocol drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE to notify the miniport driver that an allocation has completed for the current batch of receive queues. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_QUEUE\_ALLOCATION\_COMPLETE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567195) structure that is followed by an [**NDIS\_RECEIVE\_QUEUE\_ALLOCATION\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567197) structure for each queue. After a successful return from the OID method request, the **InformationBuffer** member of the **NDIS\_OID\_REQUEST** structure contains a pointer to the same array of structures, and the **CompletionStatus** member of each **NDIS\_RECEIVE\_QUEUE\_ALLOCATION\_COMPLETE\_PARAMETERS** structure contains the completion status for each queue. + +Remarks +------- + +The OID method request of OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue (VMQ) interface. + +After allocating one or more receive queues and optionally setting the initial filters, the protocol driver must issue the OID method request of OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE in order to notify the miniport driver that the allocation has completed for the current batch of receive queues. This allows the miniport driver to balance the hardware resources among multiple receive queues; if necessary, it can allocate resources such as shared memory for the receive queues. + +After a miniport driver receives an OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE request and it has filters that are set on the queue, the queue is in the Running state. In this state, the miniport driver can start indications of packets in the queue by calling [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598). + +### Return Status Codes + +The miniport driver returns one of the following status codes for the OID method request of OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeDescription

NDIS_STATUS_SUCCESS

The queue allocation has completed. The information buffer contains the updated [NDIS_RECEIVE_QUEUE_ALLOCATION_COMPLETE_ARRAY](https://msdn.microsoft.com/library/windows/hardware/ff567195) structure and parameter structures with the completion status for the queue allocation.

NDIS_STATUS_PENDING

The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller.

NDIS_STATUS_INVALID_PARAMETER

One or more of the parameters that the overlying driver provided were not valid.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_NOT_SUPPORTED

The NDIS version of the miniport driver is earlier than version 6.20.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_QUEUE\_ALLOCATION\_COMPLETE\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567195) + +[**NDIS\_RECEIVE\_QUEUE\_ALLOCATION\_COMPLETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567197) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-queue-parameters.md b/windows-driver-docs-pr/network/oid-receive-filter-queue-parameters.md new file mode 100644 index 0000000000..b4e117842c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-queue-parameters.md @@ -0,0 +1,115 @@ +--- +title: OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS +author: windows-driver-content +description: Overlying drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS to obtain the current configuration parameters of a receive queue. +ms.assetid: f6cd7896-0811-4029-b1d8-8cf800d7813e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_QUEUE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS + + +Overlying drivers issue object identifier (OID) method requests of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS to obtain the current configuration parameters of a receive queue. The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure with a queue identifier of type **NDIS\_RECEIVE\_QUEUE\_ID**. After a successful return from the OID method request, the **InformationBuffer** member of the **NDIS\_OID\_REQUEST** structure contains a pointer to an **NDIS\_RECEIVE\_QUEUE\_PARAMETERS** structure. + +Overlying drivers issue OID set requests of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS to change the current configuration parameters of a queue. The overlying driver provides a pointer to an [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure in the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. + +Remarks +------- + +Overlying drivers issue OID set requests of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS to change the parameters of one or more receive queues. The OID set request is optional for NDIS 6.20 and later miniport drivers. However, the OID request is mandatory for miniport drivers that support the virtual machine queue (VMQ) interface. + +**Note**  Only the overlying driver that allocated the queue can change the configuration parameters by issuing OID set requests of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS. + +  + +The overlying driver obtained the queue identifier input value from an earlier [OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) method OID request. + +After the overlying driver allocates a queue, it can change the configuration parameters that have a corresponding change flag (NDIS\_RECEIVE\_QUEUE\_PARAMETER\_*Xxx*\_CHANGED) in the **Flags** member of the [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) structure. However, after the queue has been allocated, the overlying driver cannot change the configuration parameters that do not have a corresponding change flag. + +### Return Status Codes + +NDIS handles the OID method request of OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS for miniport drivers, and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeDescription

NDIS_STATUS_SUCCESS

The request completed successfully.

NDIS_STATUS_PENDING

The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler of the caller after the request has completed.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS set the DATA.METHOD_INFORMATION.BytesNeeded member in the NDIS_OID_REQUEST structure to the minimum buffer size that is required.

NDIS_STATUS_INVALID_PARAMETER

The request failed because it tried to enable a capability that the underlying network adapter does not support.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) + +[OID\_RECEIVE\_FILTER\_ALLOCATE\_QUEUE](oid-receive-filter-allocate-queue.md) + +[OID\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS](oid-receive-filter-queue-parameters.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_QUEUE_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-receive-filter-set-filter.md b/windows-driver-docs-pr/network/oid-receive-filter-set-filter.md new file mode 100644 index 0000000000..3638dbcf74 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-receive-filter-set-filter.md @@ -0,0 +1,166 @@ +--- +title: OID\_RECEIVE\_FILTER\_SET\_FILTER +author: windows-driver-content +description: An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_SET\_FILTER to set a filter on a network adapter. +ms.assetid: ec3e119e-662f-48a6-8c68-20da20590b24 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_RECEIVE_FILTER_SET_FILTER Network Drivers Starting with Windows Vista +--- + +# OID\_RECEIVE\_FILTER\_SET\_FILTER + + +An overlying driver issues an OID method request of OID\_RECEIVE\_FILTER\_SET\_FILTER to set a filter on a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure that specifies the parameters for an NDIS receive filter. + +- An array of [**NDIS\_RECEIVE\_FILTER\_FIELD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567169) structures that specifies the filter test criterion for a field in a network packet header. + +After a successful return from the OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure. If the overlying driver is creating a new receive filter, NDIS updates this structure with a new filter identifier. + +Remarks +------- + +NDIS receive filters are used in the following NDIS interfaces: + +- [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). For more information about how to use receive filters in this interface, see [Managing Packet Coalescing Receive Filters](https://msdn.microsoft.com/library/windows/hardware/hh464026). + +- [Single Root I/O Virtualization (SR-IOV)](https://msdn.microsoft.com/library/windows/hardware/hh440235). For more information about how to use receive filters in this interface, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224). + +- [Virtual Machine Queue (VMQ)](https://msdn.microsoft.com/library/windows/hardware/ff571035). For more information about how to use receive filters in this interface, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780). + +The OID method request of OID\_RECEIVE\_FILTER\_SET\_FILTER is mandatory for miniport drivers that support the NDIS packet coalescing, SR-IOV, or VMQ interface. + +The overlying driver initializes the [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure with its requested filter configuration. NDIS assigns a filter identifier in the **FilterId** member of the NDIS\_RECEIVE\_FILTER\_PARAMETERS structure and passes the method request to the underlying miniport driver. + +Each filter that is set on a receive queue has a unique filter identifier for a network adapter. That is, the filter identifiers are not duplicated on different queues that the network adapter manages. When NDIS receives an OID request to set a filter on a receive queue, it verifies the filter parameters. After NDIS allocates the necessary resources and the filter identifier, it submits the OID request to the underlying network adapter. If the network adapter can successfully allocate the necessary software and hardware resources for the filter, it completes the OID request with a return status of NDIS\_STATUS\_SUCCESS. + +**Note**  Starting with NDIS 6.30, packet coalescing receive filter are only supported on the default receive queue of the network adapter. This receive queue has an identifier of NDIS\_DEFAULT\_RECEIVE\_QUEUE\_ID. + +  + +The miniport driver must retain the filter identifiers for the allocated receive filters. NDIS uses the identifier of a filter in later OID requests to change the receive filter parameters or clear the receive filter. + +After a miniport driver receives an [OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE](oid-receive-filter-queue-allocation-complete.md) request and it has filters that are set on the queue, the queue is in the *Running* state. In this state, the miniport driver can start indications of packets in the queue by calling [**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598). + +### Additional Guidelines for the SR-IOV Interface + +The following points apply to miniport drivers that support the SR-IOV interface: + +- For the SR-IOV interface, a receive queue is created on a default or nondefault virtual port (VPort). + + **Note**  Starting with Windows Server 2012, the SR-IOV interface only supports the default receive queue of a VPort. + +   + + After an SR-IOV VPort is allocated through an OID set request of [OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md), overlying drivers can set filters on the VPort with OID requests of OID\_RECEIVE\_FILTER\_SET\_FILTER. + + **Note**  Only the overlying driver that allocated the VPort can set a filter on that VPort. + +   + +- Because the default VPort always exists, overlying drivers can always set a filter on the default VPort. + +- When the VPort is created, no receive filters are set on it. In this case, the miniport driver must not indicate any receive packets on that VPort before the miniport driver receives an OID request of OID\_RECEIVE\_FILTER\_SET\_FILTER for the VPort. After this OID request is issued, the miniport driver can indicate packets on that VPort. + + **Note**  If the miniport driver indicates packets on a VPort while it is processing an OID request of OID\_RECEIVE\_FILTER\_SET\_FILTER, it must complete the OID request and return an NDIS\_STATUS\_SUCCESS status code. + +   + +### Additional Guidelines for the VMQ Interface + +The following points apply to miniport drivers that support the VMQ interface: + +- After a VMQ receive queue is allocated, overlying drivers can set filters on the receive queue with OID requests of OID\_RECEIVE\_FILTER\_SET\_FILTER. + + **Note**  Only the protocol driver that allocated a receive queue can set a filter on that queue. + +   + +- Because the default queue always exists, overlying drivers can always set a filter on the default queue. If the network adapter supports a drop queue, overlying drivers can set a filter on the drop queue. + + Overlying drivers do not own the default or drop queues. Therefore, all protocol drivers that are bound to a network adapter use the default or drop queue. + +- When the receive queue is created, no receive filters are set on it. In this case, the miniport driver must not indicate any receive packets on that receive queue before the miniport driver receives an OID request of OID\_RECEIVE\_FILTER\_SET\_FILTER for the receive queue. After this OID request is issued, the miniport driver can indicate packets on that receive queue. + + **Note**  If the miniport driver indicates packets on a queue while it is processing an OID request of OID\_RECEIVE\_FILTER\_SET\_FILTER, it must complete the OID request and return an NDIS\_STATUS\_SUCCESS status code. + +   + +### Return status codes + +The miniport driver returns one of the following status codes for the OID method request of OID\_RECEIVE\_FILTER\_SET\_FILTER: + +NDIS\_STATUS\_SUCCESS +The filter was set on the queue successfully. The information buffer contains the updated [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) structure. + +NDIS\_STATUS\_PENDING +The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller. + +NDIS\_STATUS\_INVALID\_PARAMETER +One or more of the parameters that the overlying driver provided was not valid. + +NDIS\_STATUS\_INVALID\_LENGTH +The information buffer was too short. NDIS sets the **DATA.METHOD\_INFORMATION.BytesNeeded** member in the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required. + +NDIS\_STATUS\_NOT\_SUPPORTED +The NDIS version of the miniport driver is an earlier version than 6.20. + +NDIS\_STATUS\_FAILURE +The request failed for other reasons. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +[**NET\_BUFFER\_LIST\_RECEIVE\_FILTER\_ID**](https://msdn.microsoft.com/library/windows/hardware/ff568406) + +[OID\_NIC\_SWITCH\_CREATE\_VPORT](oid-nic-switch-create-vport.md) + +[OID\_RECEIVE\_FILTER\_CLEAR\_FILTER](oid-receive-filter-clear-filter.md) + +[OID\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_COMPLETE](oid-receive-filter-queue-allocation-complete.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_RECEIVE_FILTER_SET_FILTER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-bar-resources.md b/windows-driver-docs-pr/network/oid-sriov-bar-resources.md new file mode 100644 index 0000000000..4a52df162c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-bar-resources.md @@ -0,0 +1,128 @@ +--- +title: OID\_SRIOV\_BAR\_RESOURCES +author: windows-driver-content +description: NDIS issues an object identifier (OID) method request of OID\_SRIOV\_BAR\_RESOURCES to determine the memory resources that were allocated to a PCI Express (PCIe) Base Address Register (BAR) of a PCIe Virtual Function (VF). +ms.assetid: CA29591B-EBFB-4B12-A980-F3FAD65207E2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_BAR_RESOURCES Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_BAR\_RESOURCES + + +NDIS issues an object identifier (OID) method request of OID\_SRIOV\_BAR\_RESOURCES to determine the memory resources that were allocated to a PCI Express (PCIe) Base Address Register (BAR) of a PCIe Virtual Function (VF). + +NDIS issues this OID method request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following structures: + +- An [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure that specifies the VF and BAR for which the PF miniport driver returns resource information. + +- A [**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) structure which follows the [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure. The **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** structure contains information about the memory resources that were allocated to the specified BAR. + +Remarks +------- + +NDIS issues an OID method request of OID\_SRIOV\_BAR\_RESOURCES to obtain the system physical address and length of the memory resources that were allocated to a VF BAR. Before it issues the OID method request, NDIS formats the [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure in the following way: + +- NDIS sets the **VFId** member of the [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure to the identifier associated with the VF. + +- NDIS sets the **BarIndex** member of the [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure to the BAR index for the specified VF. The BAR index is the offset of the register within the table of BARs in the PCI configuration space. + +- NDIS sets the **BarResourcesOffset** member of the [**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure to the offset, in units of bytes, from the beginning of the **NDIS\_SRIOV\_BAR\_RESOURCES\_INFO** structure to a [**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) structure. + +**Note**  Overlying drivers, such as protocol or filter drivers, cannot issue OID method requests of OID\_SRIOV\_BAR\_RESOURCES to the PF miniport driver. + +  + +When the PF miniport driver receives the OID method request, the driver returns the resources for the specified BAR by formatting the [**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) structure within the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. The driver formats the **CM\_PARTIAL\_RESOURCE\_DESCRIPTOR** structure with the system hardware resources associated with the BAR for the specified VF. + +**Note**  The driver must format the structure for a resource type of **CmResourceTypeMemory**. + +  + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the method request of OID\_SRIOV\_BAR\_RESOURCES. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_BAR_RESOURCES_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451675) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer is less than (sizeof([NDIS_SRIOV_BAR_RESOURCES_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451675)) + sizeof([CM_PARTIAL_RESOURCE_DESCRIPTOR](https://msdn.microsoft.com/library/windows/hardware/ff541977)). The PF miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**CM\_PARTIAL\_RESOURCE\_DESCRIPTOR**](https://msdn.microsoft.com/library/windows/hardware/ff541977) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_BAR\_RESOURCES\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451675) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_BAR_RESOURCES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-current-capabilities.md b/windows-driver-docs-pr/network/oid-sriov-current-capabilities.md new file mode 100644 index 0000000000..93a24e6461 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-current-capabilities.md @@ -0,0 +1,116 @@ +--- +title: OID\_SRIOV\_CURRENT\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_CURRENT\_CAPABILITIES to obtain the current single root I/O virtualization (SR-IOV) capabilities of a network adapter. +ms.assetid: EE76B3F8-2883-484A-B2EE-6F7D4738934E +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_CURRENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_CURRENT\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_CURRENT\_CAPABILITIES to obtain the current single root I/O virtualization (SR-IOV) capabilities of a network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to the [**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) structure. + +Remarks +------- + +Starting with NDIS 6.30, miniport drivers supply the enabled SR-IOV hardware capabilities on the network adapter when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver initializes an [**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) structure with the currently enabled SR-IOV hardware capabilities and sets the **CurrentSriovCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the **NDIS\_SRIOV\_CAPABILITIES** structure. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an **NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES** structure. + +Overlying protocol and filter drivers do not have to issue OID query requests of OID\_SRIOV\_CURRENT\_CAPABILITIES. NDIS provides the currently enabled SR-IOV capabilities of a network adapter to these drivers in the following way: + +- NDIS reports the currently enabled SR-IOV capabilities of an underlying network adapter to overlying protocol drivers in the **SriovCapabilities** member of the [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) structure during the bind operation. + +- NDIS reports the currently enabled SR-IOV capabilities of an underlying network adapter to overlying filter drivers in the **SriovCapabilities** member of the [**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) structure during the attach operation. + +### Return Status Codes + +NDIS handles the OID query request of the OID\_SRIOV\_CURRENT\_CAPABILITIES request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_SRIOV\_CURRENT\_CAPABILITIES request, it returns one of the following status codes: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The miniport driver must set the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_CURRENT_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-hardware-capabilities.md b/windows-driver-docs-pr/network/oid-sriov-hardware-capabilities.md new file mode 100644 index 0000000000..ca9cfe24db --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-hardware-capabilities.md @@ -0,0 +1,116 @@ +--- +title: OID\_SRIOV\_HARDWARE\_CAPABILITIES +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_HARDWARE\_CAPABILITIES to obtain the single root I/O virtualization (SR-IOV) hardware capabilities of the network adapter. +ms.assetid: EEF99105-BBDC-4093-8B11-D27F13B1A3D0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_HARDWARE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_HARDWARE\_CAPABILITIES + + +An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_HARDWARE\_CAPABILITIES to obtain the single root I/O virtualization (SR-IOV) hardware capabilities of the network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to the [**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) structure. + +Remarks +------- + +The [**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) structure contains information about the hardware capabilities of the network adapter, such as whether the adapter supports SR-IOV and whether the miniport driver is managing the adapter's PCI Express (PCIe) Physical Function (PF) or Virtual Function (VF). These capabilities can include the hardware capabilities that are currently disabled by the INF file settings or through the **Advanced** properties page. + +**Note**  All the SR-IOV capabilities of the network adapter are returned through an OID query request of OID\_SRIOV\_HARDWARE\_CAPABILITIES, regardless of whether a capability is enabled or disabled. + +  + +Starting with NDIS 6.30, miniport drivers supply the SR-IOV hardware capabilities when its [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function is called. The driver initializes an [**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) structure with the SR-IOV hardware capabilities and sets the **HardwareSriovCapabilities** member of the [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) structure to a pointer to the **NDIS\_SRIOV\_CAPABILITIES** structure. The miniport driver then calls the [**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) function and sets the *MiniportAttributes* parameter to a pointer to an **NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES** structure. + +### Return Status Codes + +NDIS handles the OID query request of the OID\_SRIOV\_HARDWARE\_CAPABILITIES request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_SRIOV\_HARDWARE\_CAPABILITIES request, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The miniport driver must set the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) + +[**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) + +[**NDIS\_SRIOV\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/hh451677) + +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_HARDWARE_CAPABILITIES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-pf-luid.md b/windows-driver-docs-pr/network/oid-sriov-pf-luid.md new file mode 100644 index 0000000000..6f2e264a6b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-pf-luid.md @@ -0,0 +1,108 @@ +--- +title: OID\_SRIOV\_PF\_LUID +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_PF\_LUID to receive the locally unique identifier (LUID) associated with the PCI Express (PCIe) Physical Function (PF) of the network adapter. +ms.assetid: 363D308D-CE88-4F3B-81FF-37A2D86CB7BC +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_PF_LUID Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_PF\_LUID + + +An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_PF\_LUID to receive the locally unique identifier (LUID) associated with the PCI Express (PCIe) Physical Function (PF) of the network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to the [**NDIS\_SRIOV\_PF\_LUID\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451678) structure. + +Remarks +------- + +NDIS generates a LUID for the PF before NDIS calls the [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) function of the miniport driver for the PF. This LUID is valid until NDIS calls the [*MiniportHaltEx*](https://msdn.microsoft.com/library/windows/hardware/ff559388) function of the driver. + +**Note**  The value of the **Luid** member differs from the **NetLuid** member of the [**NDIS\_MINIPORT\_INIT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565972) structure. This structure is passed to the miniport driver through the *MiniportInitParameters* parameter of [*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389). + +  + +### Return Status Codes + +NDIS handles the OID query request of OID\_SRIOV\_PF\_LUID request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_SRIOV\_PF\_LUID request, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The miniport driver must set the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*MiniportInitializeEx*](https://msdn.microsoft.com/library/windows/hardware/ff559389) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_PF\_LUID\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451678) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_PF_LUID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-probed-bars.md b/windows-driver-docs-pr/network/oid-sriov-probed-bars.md new file mode 100644 index 0000000000..14e83d6bed --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-probed-bars.md @@ -0,0 +1,134 @@ +--- +title: OID\_SRIOV\_PROBED\_BARS +author: windows-driver-content +description: NDIS issues an object identifier (OID) query request of OID\_SRIOV\_PROBED\_BARS to obtain the values of a network adapter's PCI Express (PCIe) Base Address Registers (BARs). +ms.assetid: 81C3A5B5-58D5-41F4-A000-79F3F4E00DAD +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_PROBED_BARS Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_PROBED\_BARS + + +NDIS issues an object identifier (OID) query request of OID\_SRIOV\_PROBED\_BARS to obtain the values of a network adapter's PCI Express (PCIe) Base Address Registers (BARs). This function returns the BAR values that were reported by the network adapter following a query performed by the PCI bus driver. This query determines the memory or I/O address space that is required by the network adapter. + +NDIS issues OID query requests of OID\_SRIOV\_PROBED\_BARS to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID query request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_SRIOV\_PROBED\_BARS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451679) structure that contains the parameters for a read operation on the PCI BARs of a network adapter. + +- An array of ULONG values for each BAR of the PCIe network adapter. The maximum number of elements within this array is PCI\_TYPE0\_ADDRESSES. + +Remarks +------- + +The PCI bus driver, which runs in the management operating system of the Hyper-V parent partition, queries the memory or I/O address space requirements of each PCI Base Address Register (BAR) of the network adapter. The PCI bus driver performs this query when it first detects the adapter on the bus. + +Through this PCI BAR query, the PCI bus driver determines the following: + +- Whether a PCI BAR is supported by the network adapter. + +- If a BAR is supported, how much memory or I/O address space is required for the BAR. + +The virtual PCI (VPCI) bus driver runs in the guest operating system of a Hyper-V child partition. When a PCI Express (PCIe) Virtual Function (VF) is attached to the child partition, the VPCI bus driver will expose a virtual network adapter for the VF (*VF network adapter*). Before it does this, the VPCI bus driver must perform a PCI BAR query to determine the required memory or address space that is required by the VF network adapter. + +Because access to the PCI configuration space is a privileged operation, it can only be performed by components that run in the management operating system of a Hyper-V parent partition. When the VPCI bus driver queries the PCI BARs, NDIS issues an OID query request of OID\_SRIOV\_PROBED\_BARS to the PF miniport driver. The results returned by this OID query request are forwarded to the VPCI bus driver so that it can determine how much memory address space would be needed by the VF network adapter. + +**Note**  OID requests of OID\_SRIOV\_PROBED\_BARS can only be issued by NDIS. The OID request must not be issued by overlying drivers, such as protocol of filter drivers. + +  + +The OID\_SRIOV\_PROBED\_BARS query request contains an [**NDIS\_SRIOV\_PROBED\_BARS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451679) structure. When the PF miniport driver handles this OID, the driver must return the PCI BAR values within the array referenced by the **BaseRegisterValuesOffset** member of the **NDIS\_SRIOV\_PROBED\_BARS\_INFO** structure. For each offset within the array, the PF miniport driver must set the array element to the ULONG value of the BAR at the same offset within the physical adapter's PCI configuration space. + +Each BAR value returned by the driver must be the same value that would follow a PCI BAR query as performed by the PCI driver that runs in the management operating system. The PF miniport driver can call [**NdisMQueryProbedBars**](https://msdn.microsoft.com/library/windows/hardware/hh451520) to determine this information. + +For more information about the BARs of a PCI device, see the *PCI Local Bus Specification*. + +For more information on how to query PCI BAR registers for a VF, see the [Querying the PCI Base Address Registers of a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440182). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the query request of OID\_SRIOV\_PROBED\_BARS: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_PROBED_BARS_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451679) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer is less than (sizeof([NDIS_SRIOV_PROBED_BARS_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451679)) + PCI_TYPE0_ADDRESSES). The PF miniport driver must set the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_PROBED\_BARS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451679) + +[**NdisMQueryProbedBars**](https://msdn.microsoft.com/library/windows/hardware/hh451520) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_PROBED_BARS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-read-vf-config-block.md b/windows-driver-docs-pr/network/oid-sriov-read-vf-config-block.md new file mode 100644 index 0000000000..25ee752eaa --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-read-vf-config-block.md @@ -0,0 +1,136 @@ +--- +title: OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK to read data from a specified PCI Express (PCIe) Virtual Function (VF) configuration block. +ms.assetid: A7AC7A18-5DA2-4EE8-B635-04616ABFE08C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_READ_VF_CONFIG_BLOCK Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK + + +An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK to read data from a specified PCI Express (PCIe) Virtual Function (VF) configuration block. + +Overlying drivers issue this OID method request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure that contains the offset, in units of bytes, from the beginning of this structure to a location within the buffer that contains the data that is read from the VF configuration block. + +- Additional buffer space for the data to be read from the specified VF configuration block. + +Remarks +------- + +A VF configuration block is used for backchannel communication between the PF and VF miniport drivers. The IHV can define one or more VF configuration blocks for the miniport drivers. Each VF configuration block has an IHV-defined format, length, and block ID. + +**Note**  Data from each VF configuration block is used only by the PF and VF miniport drivers. + +  + +Before it issues the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK, the overlying driver must set the members of [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure in the following way: + +- Set the **VFId** member to the identifier of the VF from which the information is to be read. + +- Set the **BlockId** member to the identifier of the VF configuration block from which the information is to be read. + +- Set the **Length** member to the number of bytes to read from the configuration block. + +- Set the **BufferOffset** member to the offset within the buffer (referenced by **InformationBuffer** member) that will contain the data that is read from the specified VF configuration block. This offset is specified in units of bytes from the beginning of the [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure. + +When it handles the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK, the PF miniport driver must follow these guidelines: + +- The PF miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure, has resources that have been previously allocated. The PF miniport driver allocates resources for a VF during an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If resources for the specified VF have not been allocated, the driver must fail the OID request. + +- The PF miniport driver must verify that the **BlockId** member of the [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure specifies a valid VF configuration block. If not, the driver must fail the OID request. + +For more information about backchannel communication within the single root I/O virtualization (SR-IOV) interface, see [SR-IOV PF/VF Backchannel Communication](https://msdn.microsoft.com/library/windows/hardware/hh440251). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the method request of OID\_SRIOV\_READ\_VF\_CONFIG\_BLOCK. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_READ_VF_CONFIG_BLOCK_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451680) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_READ\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451680) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE](oid-sriov-read-vf-config-space.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_READ_VF_CONFIG_BLOCK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-read-vf-config-space.md b/windows-driver-docs-pr/network/oid-sriov-read-vf-config-space.md new file mode 100644 index 0000000000..f747a335f9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-read-vf-config-space.md @@ -0,0 +1,137 @@ +--- +title: OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE to read data from the PCI Express (PCIe) configuration space for a specified PCIe Virtual Function (VF) on the network adapter. +ms.assetid: 48CD54F5-F18F-4BC1-A93A-A824EC041605 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_READ_VF_CONFIG_SPACE Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE + + +An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE to read data from the PCI Express (PCIe) configuration space for a specified PCIe Virtual Function (VF) on the network adapter. + +After a successful return from this OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451681) structure that contains the parameters for a read operation of the PCI configuration space of a VF. + +- Additional buffer space for the data to be read from the PCI configuration space. + +Remarks +------- + +The VF miniport driver runs in the guest operating system of a Hyper-V child partition. Because of this, the VF miniport driver cannot directly access hardware resources, such as the VF's PCI configuration space. Only the miniport driver for the PCIe Physical Function (PF) can access the PCI configuration space for a VF. The PF miniport driver runs in the management operating system of a Hyper-V parent partition and has privileged access to the VF resources. + +In order to read the VF PCI configuration space, overlying drivers that run in the management operating system issue the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE to the PF miniport driver. This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +For example, the virtualization stack that runs in the management operating system issues the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE when the VF miniport driver calls [**NdisMGetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff563591) to read from its VF PCI configuration space. + +When it handles the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE, the PF miniport driver must follow these guidelines: + +- The miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451681) structure, has resources that have been previously allocated. The miniport driver allocates resources for a VF through an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If resources for the specified VF have not been allocated, the driver must fail the OID request. + +- The miniport driver must verify that the buffer (referenced by the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure) is large enough to return the requested PCIe configuration space data. If this is not true, the driver must fail the OID request. +- The miniport driver typically calls [**NdisMGetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451484) to query the requested PCIe configuration space. However, the miniport driver can also return PCIe configuration space data for the VF that the driver has cached from previous read or write operations of the PCIe configuration space. + + **Note**  If an independent hardware vendor (IHV) provides a virtual bus driver (VBD) as part of its SR-IOV [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840), its miniport driver must not call [**NdisMGetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451484). Instead, the driver must interface with the VBD through a private communication channel, and request that the VBD call [*ReadVfConfigBlock*](https://msdn.microsoft.com/library/windows/hardware/hh439637). This function is exposed from the [GUID\_VPCI\_INTERFACE\_STANDARD](https://msdn.microsoft.com/library/windows/hardware/hh451146) interface that is supported by the underlying virtual PCI (VPCI) bus driver. + +   + +If the PF miniport driver can successfully complete the OID request, the driver must copy the requested PCI configuration space data to the buffer referenced by the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. The driver copies the data to the buffer at the offset specified by **BufferOffset** member of [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451681) structure. + +For more information, see [Querying the PCI Configuration Data of a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440183). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID method request of OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_READ_VF_CONFIG_SPACE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451681) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The miniport driver must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[GUID\_VPCI\_INTERFACE\_STANDARD](https://msdn.microsoft.com/library/windows/hardware/hh451146) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_READ\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451681) + +[**NdisMGetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff563591) + +[**NdisMGetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451484) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[*ReadVfConfigBlock*](https://msdn.microsoft.com/library/windows/hardware/hh439637) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_READ_VF_CONFIG_SPACE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-reset-vf.md b/windows-driver-docs-pr/network/oid-sriov-reset-vf.md new file mode 100644 index 0000000000..072d55774c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-reset-vf.md @@ -0,0 +1,114 @@ +--- +title: OID\_SRIOV\_RESET\_VF +author: windows-driver-content +description: Overlying drivers issue an object identifier (OID) set request of OID\_SRIOV\_RESET\_VF to reset a specified PCI Express (PCIe) Virtual Function (VF) on a network adapter that supports single root I/O virtualization. +ms.assetid: 7D5EB64B-3345-478A-8D42-192939C0B9C2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_RESET_VF Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_RESET\_VF + + +Overlying drivers issue an object identifier (OID) set request of OID\_SRIOV\_RESET\_VF to reset a specified PCI Express (PCIe) Virtual Function (VF) on a network adapter that supports single root I/O virtualization. Overlying drivers issue this OID set request to the miniport driver of the PCI Express (PCIe) Physical Function (PF) of the network adapter. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SRIOV\_RESET\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451682) structure. The overlying driver specifies the identifier of the VF to be reset through the **VFId** member of this structure. + +Remarks +------- + +A VF can be reset through a PCI Express (PCIe) Function Level Reset (FLR). Because the FLR request is a privileged operation, it can only be performed by the PF miniport driver that runs in the management operating system of a Hyper-V parent partition. Overlying drivers that run in the management operating system are notified of the FLR request and issue the OID set request of OID\_SRIOV\_RESET\_VF to the PF miniport driver. + +When it handles this OID request, the PF miniport driver must follow these guidelines: + +- The PF miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_RESET\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451682) structure, has resources that have been previously allocated. The PF miniport driver allocates resources for a VF during an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If resources for the specified VF have not been allocated, the driver must fail the OID request. + +- The reset operation must only affect the specified VF. The operation must not affect other VFs or the PF on the same network adapter. + +For more information, see [Resetting a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440219). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the set request of OID\_SRIOV\_RESET\_VF. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_RESET_VF_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451682) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The PF miniport driver must set the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_RESET\_VF\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451682) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_RESET_VF%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-set-vf-power-state.md b/windows-driver-docs-pr/network/oid-sriov-set-vf-power-state.md new file mode 100644 index 0000000000..8646af10f5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-set-vf-power-state.md @@ -0,0 +1,112 @@ +--- +title: OID\_SRIOV\_SET\_VF\_POWER\_STATE +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_SET\_VF\_POWER\_STATE to change the power state of a specified PCI Express (PCIe) Virtual Function (VF) on the network adapter. +ms.assetid: 9723518E-2312-48F9-820A-19F5567A33DB +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_SET_VF_POWER_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_SET\_VF\_POWER\_STATE + + +An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_SET\_VF\_POWER\_STATE to change the power state of a specified PCI Express (PCIe) Virtual Function (VF) on the network adapter. Since changing the power state is a privileged operation, overlying drivers issue this OID set request to the miniport driver of the PCIe Physical Function (PF) on the network adapter. The PF miniport driver then sets the specified power state on the VF. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SRIOV\_SET\_VF\_POWER\_STATE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451683) structure. + +Remarks +------- + +When the PF miniport driver is issued this OID set request, it must follow these guidelines: + +- The PF miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_SET\_VF\_POWER\_STATE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451683) structure, has resources that have been previously allocated. The PF miniport driver allocates resources for a VF during an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If the specified VF is not in an allocated state, the driver must fail the OID request. + +- The power state operation must only affect the specified VF. The operation must not affect other VFs or the PF on the same network adapter. + +For more information, see [Setting the Power State of a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440230). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID set request of OID\_SRIOV\_SET\_VF\_POWER\_STATE. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_SET_VF_POWER_STATE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451683) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. The PF miniport driver must set the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_SET\_VF\_POWER\_STATE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451683) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_SET_VF_POWER_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-vf-invalidate-config-block.md b/windows-driver-docs-pr/network/oid-sriov-vf-invalidate-config-block.md new file mode 100644 index 0000000000..8f57f24a98 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-vf-invalidate-config-block.md @@ -0,0 +1,149 @@ +--- +title: OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK +author: windows-driver-content +description: NDIS issues an object identifier (OID) method request of OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK to notify the miniport driver of a PCI Express (PCIe) Virtual Function (VF) that data within one or more configuration blocks has changed. +ms.assetid: CF73E0DA-20DA-49A0-80B0-0F5A56DCEF5D +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK + + +NDIS issues an object identifier (OID) method request of OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK to notify the miniport driver of a PCI Express (PCIe) Virtual Function (VF) that data within one or more configuration blocks has changed. NDIS issues this OID when the miniport driver for a PCIe Physical Function (PF) calls [**NdisMInvalidateConfigBlock**](https://msdn.microsoft.com/library/windows/hardware/hh451517). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451684) structure. This structure specifies one or more Virtual Function (VF) configuration blocks whose data has been changed (*invalidated*) by the PF miniport driver. + +Remarks +------- + +A VF configuration block is used for backchannel communication between the PF and VF miniport drivers. The IHV can define one or more VF configuration blocks for the device. Each VF configuration block has an IHV-defined format, length, and block ID. + +**Note**  Data from each VF configuration block is used only by the PF and VF miniport drivers. + +  + +VF configuration data is exchanged between the following drivers: + +- The VF driver, which runs in the guest operating system. This operating system runs within a Hyper-V child partition. + +- The PF driver, which runs in the management operating system. This operating system runs within the Hyper-V parent partition. + +In order to handle notifications of invalid VF configuration data, NDIS and the miniport drivers perform the following steps: + +1. In the guest operating system, NDIS issues an I/O control request of [**IOCTL\_VPCI\_INVALIDATE\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/hh439301) request. When this IOCTL is completed, NDIS is notified that VF configuration data has changed. + +2. In the management operating system, the following steps occur: + + 1. The PF miniport driver calls the [**NdisMInvalidateConfigBlock**](https://msdn.microsoft.com/library/windows/hardware/hh451517) function to notify NDIS that VF configuration data has changed and is no longer valid. The driver sets the *BlockMask* parameter to a ULONGLONG bitmask that specifies which VF configuration blocks have changed. Each bit in the bitmask corresponds to a VF configuration block. If the bit is set to one, the data in the corresponding VF configuration block has changed. + 2. NDIS signals the virtualization stack, which runs in the management operating system, about the change to VF configuration block data. The virtualization stack caches the *BlockMask* parameter data. + + **Note**  Each time that the PF miniport driver calls [**NdisMInvalidateConfigBlock**](https://msdn.microsoft.com/library/windows/hardware/hh451517), the virtualization stack ORs the *BlockMask* parameter data with the current value in its cache. + +   + + 3. The virtualization stack notifies the virtual PCI (VPCI) driver, which runs in the guest operating system, about the invalidation of VF configuration data. The virtualization stack sends the cached *BlockMask* parameter data to the VPCI driver. + +3. In the Guest operating system, the following steps occur: + + 1. The VPCI driver saves the cached *BlockMask* parameter data in the **BlockMask** member of the [**VPCI\_INVALIDATE\_BLOCK\_OUTPUT**](https://msdn.microsoft.com/library/windows/hardware/hh451586) structure that is associated with the [**IOCTL\_VPCI\_INVALIDATE\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/hh439301) request. + + 2. The VPCI driver successfully completes the [**IOCTL\_VPCI\_INVALIDATE\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/hh439301) request. When this happens, NDIS issues an OID method request of OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK to the VF miniport driver. An [**NDIS\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451684) is passed along in the OID request. This structure contains the cached *BlockMask* parameter data. + + NDIS also issues another [**IOCTL\_VPCI\_INVALIDATE\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/hh439301) request to handle successive notifications of changes to VF configuration data. + + 3. When the VF driver handles the OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK request, it reads data from the specified VF configuration blocks. + +For more information about backchannel communication within the single root I/O virtualization (SR-IOV) interface, see [SR-IOV PF/VF Backchannel Communication](https://msdn.microsoft.com/library/windows/hardware/hh440251). + +### Return Status Codes + +The miniport driver returns one of the following status codes for the OID method request of OID\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_VF_INVALIDATE_CONFIG_BLOCK_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451684) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the size of the [NDIS_SRIOV_VF_INVALIDATE_CONFIG_BLOCK_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451684) structure.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**IOCTL\_VPCI\_INVALIDATE\_BLOCK**](https://msdn.microsoft.com/library/windows/hardware/hh439301) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_VF\_INVALIDATE\_CONFIG\_BLOCK\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451684) + +[**NdisMInvalidateConfigBlock**](https://msdn.microsoft.com/library/windows/hardware/hh451517) + +[OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE](oid-sriov-read-vf-config-space.md) + +[**VPCI\_INVALIDATE\_BLOCK\_OUTPUT**](https://msdn.microsoft.com/library/windows/hardware/hh451586) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_VF_INVALIDATE_CONFIG_BLOCK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-vf-serial-number.md b/windows-driver-docs-pr/network/oid-sriov-vf-serial-number.md new file mode 100644 index 0000000000..343e85c8a6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-vf-serial-number.md @@ -0,0 +1,104 @@ +--- +title: OID\_SRIOV\_VF\_SERIAL\_NUMBER +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_VF\_SERIAL\_NUMBER to determine the serial number of the PCI Express (PCIe) Virtual Function (VF) network adapter. +ms.assetid: C4D04C96-94FA-4E01-839C-A9C5026D7AE5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_VF_SERIAL_NUMBER Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_VF\_SERIAL\_NUMBER + + +An overlying driver issues an object identifier (OID) query request of OID\_SRIOV\_VF\_SERIAL\_NUMBER to determine the serial number of the PCI Express (PCIe) Virtual Function (VF) network adapter. This virtual network adapter is exposed in the guest operating system of a Hyper-V child partition to which the VF is attached. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SRIOV\_VF\_SERIAL\_NUMBER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451685) structure. + +Remarks +------- + +The overlying driver uses the serial number to map the VF network adapter to an instance of a VF on the physical network adapter. The serial number is generated by the virtualization stack before resources for the VF are allocated through an OID set request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + +### Return Status Codes + +NDIS handles the OID query request of the OID\_SRIOV\_VF\_SERIAL\_NUMBER request for miniport drivers. The drivers will not be issued this OID request. + +When NDIS handles the OID\_SRIOV\_VF\_SERIAL\_NUMBER request, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_VF\_SERIAL\_NUMBER\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451685) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_VF_SERIAL_NUMBER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-vf-vendor-device-id.md b/windows-driver-docs-pr/network/oid-sriov-vf-vendor-device-id.md new file mode 100644 index 0000000000..1aae84ab38 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-vf-vendor-device-id.md @@ -0,0 +1,112 @@ +--- +title: OID\_SRIOV\_VF\_VENDOR\_DEVICE\_ID +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_VF\_VENDOR\_DEVICE\_ID to query the PCI Express (PCIe) device identifier (DeviceID) and vendor identifier (VendorID) for a PCI Express (PCIe) Virtual Function (VF) network adapter. This virtual network adapter is exposed in the Hyper-V child partition that is attached to the VF.Overlying drivers issue this OID method request to the miniport driver of the PCI Express (PCIe) Physical Function (PF) of the network adapter. This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. +ms.assetid: 19D98264-325B-4EA4-83BF-BBFECD185E55 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_VF_VENDOR_DEVICE_ID Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_VF\_VENDOR\_DEVICE\_ID + + +An overlying driver issues an object identifier (OID) method request of OID\_SRIOV\_VF\_VENDOR\_DEVICE\_ID to query the PCI Express (PCIe) device identifier (DeviceID) and vendor identifier (VendorID) for a PCI Express (PCIe) Virtual Function (VF) network adapter. This virtual network adapter is exposed in the Hyper-V child partition that is attached to the VF. + +Overlying drivers issue this OID method request to the miniport driver of the PCI Express (PCIe) Physical Function (PF) of the network adapter. This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SRIOV\_VF\_VENDOR\_DEVICE\_ID\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451686) structure. + +Remarks +------- + +Before it issues this OID method request, the overlying driver must initialize an [**NDIS\_SRIOV\_VF\_VENDOR\_DEVICE\_ID\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451686) structure and must set the **VFId** member to the identifier of the VF from which the information is to be read. + +When it handles this OID request, the PF miniport driver must verify that the specified VF has resources that have been previously allocated. The PF miniport driver allocates resources for a VF during an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If resources for the specified VF have not been allocated, the driver must fail the OID request. + +For more information, see [Querying the PCI Vendor and Device Identifiers for a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440185). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID method request of OID\_SRIOV\_VF\_VENDOR\_DEVICE\_ID. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_VF_VENDOR_DEVICE_ID_INFO](https://msdn.microsoft.com/library/windows/hardware/hh451686) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_VF\_VENDOR\_DEVICE\_ID\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451686) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_VF_VENDOR_DEVICE_ID%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-write-vf-config-block.md b/windows-driver-docs-pr/network/oid-sriov-write-vf-config-block.md new file mode 100644 index 0000000000..4f88cfd8a2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-write-vf-config-block.md @@ -0,0 +1,136 @@ +--- +title: OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK to write data to a PCI Express (PCIe) Virtual Function (VF) configuration block. +ms.assetid: 60527938-5627-482D-B94D-522DA8E32540 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_WRITE_VF_CONFIG_BLOCK Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK + + +An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK to write data to a PCI Express (PCIe) Virtual Function (VF) configuration block. + +Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure that contains the offset, in units of bytes, from the beginning of this structure to a location within the buffer that contains the data that is written to the VF configuration block. + +- Additional buffer space for the data to be written to the specified VF configuration block. + +Remarks +------- + +A VF configuration block is used for backchannel communication between the PF and VF miniport drivers. The IHV can define one or more VF configuration blocks for the miniport drivers. Each VF configuration block has an IHV-defined format, length, and block ID. + +**Note**  Data from each VF configuration block is used only by the PF and VF miniport drivers. + +  + +Before it issues the OID set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK, the overlying driver must set the members of [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure in the following way: + +- Set the **VFId** member to the identifier of the VF for which the information is to be written. + +- Set the **BlockId** member to the identifier of the configuration block from which the information is to be written. + +- Set the **Length** member to the number of bytes to write to the VF configuration block. + +- Set the **BufferOffset** member to the offset within the buffer (referenced by **InformationBuffer** member) that contains the data that is to be written from the specified VF configuration block. This offset is specified in units of bytes from the beginning of the [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure. + +When it handles the OID set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK, the PF miniport driver must follow these guidelines: + +- The PF miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure, has resources that have been previously allocated. The PF miniport driver allocates resources for a VF during an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). If resources for the specified VF have not been allocated, the driver must fail the OID request. + +- The PF miniport driver must verify that the **BlockId** member of the [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure specifies a valid VF configuration block. If not, the driver must fail the OID request. + +For more information about backchannel communication within the single root I/O virtualization (SR-IOV) interface, see [SR-IOV PF/VF Backchannel Communication](https://msdn.microsoft.com/library/windows/hardware/hh440251). + +### Return Status Codes + +The miniport driver returns one of the following status codes for the OID set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_WRITE_VF_CONFIG_BLOCK_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451687) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_BLOCK\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451687) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE](oid-sriov-read-vf-config-space.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_WRITE_VF_CONFIG_BLOCK%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-sriov-write-vf-config-space.md b/windows-driver-docs-pr/network/oid-sriov-write-vf-config-space.md new file mode 100644 index 0000000000..583aa401b8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-sriov-write-vf-config-space.md @@ -0,0 +1,140 @@ +--- +title: OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE +author: windows-driver-content +description: An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE to write data to the PCI Express (PCIe) configuration space for a specified PCIe Virtual Function (VF) on the network adapter. +ms.assetid: 0D9866A6-A8C6-4B0A-8D17-A632E1AE37BF +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SRIOV_WRITE_VF_CONFIG_SPACE Network Drivers Starting with Windows Vista +--- + +# OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE + + +An overlying driver issues an object identifier (OID) set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE to write data to the PCI Express (PCIe) configuration space for a specified PCIe Virtual Function (VF) on the network adapter. + +Overlying drivers issue this OID set request to the miniport driver for the network adapter's PCIe Physical Function (PF). This OID method request is required for PF miniport drivers that support the single root I/O virtualization (SR-IOV) interface. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following: + +- An [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451688) structure that contains the parameters for a write operation of the PCI configuration space of a VF. + +- Additional buffer space that contains the data to be written to the PCI configuration space. + +Remarks +------- + +The VF miniport driver runs in the guest operating system of a Hyper-V child partition. Because of this, the VF miniport driver cannot directly access hardware resources, such as the VF's PCI configuration space. Only the PF miniport driver, which runs in the management operating system of a Hyper-V parent partition, can access the PCI configuration space for a VF. + +The overlying driver, such as the virtualization stack, issues the OID set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE when the VF miniport driver calls [**NdisMSetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff563670) to write to its PCI configuration space. + +When it handles the OID method request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE, the PF miniport driver must follow these guidelines: + +- The PF miniport driver must verify that the VF, specified by the **VFId** member of the [**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451688) structure, has resources that have been previously allocated. The PF miniport driver allocates resources for a VF through an OID method request of [OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md). + + If resources for the specified VF have not been allocated, the driver must fail the OID request. + +- The PF miniport driver calls [**NdisMSetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451526) to write to the requested PCI configuration space. However, the PF miniport driver can also return PCI configuration space data for the VF that the driver has cached from previous read or write operations of the PCI configuration space. + + **Note**  If an independent hardware vendor (IHV) provides a virtual bus driver (VBD) as part of its SR-IOV [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840), its PF miniport driver must not call [**NdisMSetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451526). Instead, the driver must interface with the VBD through a private communication channel, and request that the VBD call [*SetVirtualFunctionData*](https://msdn.microsoft.com/library/windows/hardware/hh451552). This function is exposed from the [GUID\_VPCI\_INTERFACE\_STANDARD](https://msdn.microsoft.com/library/windows/hardware/hh451146) interface that is supported by the underlying virtual PCI (VPCI) bus driver. + +   + +If the PF miniport driver can successfully complete the OID request, the driver must copy the requested PCI configuration space data to the buffer referenced by the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure. The driver copies the data to the buffer at the offset specified by **BufferOffset** member of the [**NDIS\_SRIOV\_READ\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451681) structure. + +For more information, see [Setting the PCI Configuration Data of a Virtual Function](https://msdn.microsoft.com/library/windows/hardware/hh440229). + +### Return Status Codes + +The PF miniport driver returns one of the following status codes for the OID set request of OID\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The PF miniport driver either does not support the single root I/O virtualization (SR-IOV) interface or is not enabled to use the interface.

NDIS_STATUS_INVALID_PARAMETER

One or more of the members of the [NDIS_SRIOV_WRITE_VF_CONFIG_SPACE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451688) structure have invalid values.

NDIS_STATUS_INVALID_LENGTH

The information buffer was too short. NDIS sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[GUID\_VPCI\_INTERFACE\_STANDARD](https://msdn.microsoft.com/library/windows/hardware/hh451146) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SRIOV\_WRITE\_VF\_CONFIG\_SPACE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh451688) + +[**NdisMSetBusData**](https://msdn.microsoft.com/library/windows/hardware/ff563670) + +[**NdisMSetVirtualFunctionBusData**](https://msdn.microsoft.com/library/windows/hardware/hh451526) + +[OID\_NIC\_SWITCH\_ALLOCATE\_VF](oid-nic-switch-allocate-vf.md) + +[OID\_SRIOV\_READ\_VF\_CONFIG\_SPACE](oid-sriov-read-vf-config-space.md) + +[*SetVirtualFunctionData*](https://msdn.microsoft.com/library/windows/hardware/hh451552) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SRIOV_WRITE_VF_CONFIG_SPACE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-feature-status-query.md b/windows-driver-docs-pr/network/oid-switch-feature-status-query.md new file mode 100644 index 0000000000..24dbb51c16 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-feature-status-query.md @@ -0,0 +1,104 @@ +--- +title: OID\_SWITCH\_FEATURE\_STATUS\_QUERY +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_FEATURE\_STATUS\_QUERY to obtain custom status information from an extension about the extensible switch. +ms.assetid: 580EFBD0-7798-4C56-99C5-84EADB8F8E82 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_FEATURE_STATUS_QUERY Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_FEATURE\_STATUS\_QUERY + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_FEATURE\_STATUS\_QUERY to obtain custom status information from an extension about the extensible switch. This information is known as *feature status* information. The format of this information is defined by the independent software vendor (ISV). + +After a successful return from this OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_FEATURE\_STATUS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598208) structure that specifies the parameters for the type of feature status information to be returned. + +- An [**NDIS\_SWITCH\_FEATURE\_STATUS\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598207) structure that contains the feature status information for the extensible switch. + +Remarks +------- + +For guidelines on how to handle an OID set request of OID\_SWITCH\_FEATURE\_STATUS\_QUERY, see [Managing Custom Switch Feature Status Information](https://msdn.microsoft.com/library/windows/hardware/hh598193). + +### Return Status Codes + +The extension returns one of the following status codes for the OID method request of OID\_SWITCH\_FEATURE\_STATUS\_QUERY. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the feature status information as well as the [NDIS_SWITCH_FEATURE_STATUS_CUSTOM](https://msdn.microsoft.com/library/windows/hardware/hh598207) and [NDIS_SWITCH_FEATURE_STATUS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598208) structures. The underlying miniport edge of the extensible switch sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PROPERTY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh598257) + +[**NDIS\_SWITCH\_FEATURE\_STATUS\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598207) + +[**NDIS\_SWITCH\_FEATURE\_STATUS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598208) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_FEATURE_STATUS_QUERY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-array.md b/windows-driver-docs-pr/network/oid-switch-nic-array.md new file mode 100644 index 0000000000..08b85dbc89 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-array.md @@ -0,0 +1,114 @@ +--- +title: OID\_SWITCH\_NIC\_ARRAY +author: windows-driver-content +description: A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_NIC\_ARRAY to obtain an array. +ms.assetid: CA9958DF-4389-4B4F-B110-03F500E27A1B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_ARRAY Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_ARRAY + + +A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_NIC\_ARRAY to obtain an array. Each element in the array specifies the configuration parameters of a virtual network adapter that is associated with an extensible switch port. + +If the OID query request is completed successfully, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure that defines the number of elements in the array. This structure also specifies the offset to the first element in the array. + +- An array of [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structures. Each of these structures contains information about a network adapter that is connected to an extensible switch port. + + **Note**  If no network adapters are connected to extensible switch ports, the underlying miniport edge of the extensible switch sets the **NumElements** member of the [**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) structure to zero. In this case, no [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structures are returned. + +   + +Remarks +------- + +The OID\_SWITCH\_NIC\_ARRAY OID must only be issued when the Hyper-V extensible switch has completed activation. Please see [Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) for more details. + +When the extension processes the returned [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure, it must not assume that the various string members of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure, such as **NicFriendlyName**, are NULL-terminated. The data types for these string members are type-defined by the [**IF\_COUNTED\_STRING**](https://msdn.microsoft.com/library/windows/hardware/hh451419) structure. The driver must determine the string length from the value of the **Length** member of this structure. + +**Note**  If the string is null-terminated, the **Length** member must not include the terminating null character. + +  + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_ARRAY and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the [NDIS_SWITCH_NIC_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598212) and its array of [NDIS_SWITCH_NIC_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598215) elements. The underlying miniport edge of the extensible switch sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598212) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_ARRAY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-connect.md b/windows-driver-docs-pr/network/oid-switch-nic-connect.md new file mode 100644 index 0000000000..752dba566c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-connect.md @@ -0,0 +1,122 @@ +--- +title: OID\_SWITCH\_NIC\_CONNECT +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_CONNECT to notify underlying extensible switch extensions that a network connection between an extensible switch port and a network adapter is completely established. The protocol edge previously notified extensions that this connection is being established when it issued an OID set request of OID\_SWITCH\_NIC\_CREATE. +ms.assetid: 98A4AD28-2716-40DD-AE46-70969A23FAB7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_CONNECT Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_CONNECT + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_CONNECT to notify underlying extensible switch extensions that a network connection between an extensible switch port and a network adapter is completely established. The protocol edge previously notified extensions that this connection is being established when it issued an OID set request of [OID\_SWITCH\_NIC\_CREATE](oid-switch-nic-create.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the extensible switch port for which the connect notification is being made. The extensible switch extension can obtain the parameter information for this port and other extensible switch ports in the following ways: + +- By issuing OID query requests of [OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md). The extension issues this OID on [*FilterAttach*](https://msdn.microsoft.com/library/windows/hardware/ff549905) only when OID\_SWITCH\_PARAMETERS returns an [**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) structure with **IsActive** set to TRUE. If **IsActive** is FALSE, the extension issues the OID when the **NetEventSwitchActivate** [**NET\_PNP\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff568751) is issued by the extension miniport adapter. + +- By inspecting the various OID sets requests of [OID\_SWITCH\_PORT\_CREATE](oid-switch-port-create.md) and [OID\_SWITCH\_PORT\_DELETE](oid-switch-port-delete.md). + +The **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the index of a network adapter for which the connection notification is being made. The network adapter with the specified **Index** value is connected to the extensible switch port specified by the **PortId** member. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + +When it receives the OID set request of OID\_SWITCH\_NIC\_CONNECT, the extension must follow these guidelines: + +- When the OID\_SWITCH\_NIC\_CONNECT request completes with NDIS\_STATUS\_SUCCESS, the network connection and extensible switch port are fully operational. The extension can generate or forward packet traffic to the port's network connection. The extension can also issue extensible switch OIDs or status indications that use the port as the source port. The extension can also call [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) to increment the extensible switch reference counter for the port. + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure that is associated with the OID request. + +- The extension must always call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID request to underlying extensions. The extension must not complete the OID request itself. + +- The extensible switch external network adapter can bind to one or more underlying physical adapters. For every physical network adapter that is bound to the external network adapter, the protocol edge of the extensible switch issues a separate OID set request of OID\_SWITCH\_NIC\_CONNECT. Each OID set request specifies a different network adapter connection index value. For more information on these values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + + The extension must maintain the connection state for each underlying physical adapter that is bound to the external network adapter. For more information about the different configurations in which physical network adapters can be bound to the external network adapter, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +**Note**  The extension must not issue its own OID set requests of OID\_SWITCH\_NIC\_CONNECT. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID set request of OID\_SWITCH\_NIC\_CONNECT and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NdisFReturnNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff562613) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_CREATE](oid-switch-nic-create.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_CONNECT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-create.md b/windows-driver-docs-pr/network/oid-switch-nic-create.md new file mode 100644 index 0000000000..a6380ccaf9 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-create.md @@ -0,0 +1,185 @@ +--- +title: OID\_SWITCH\_NIC\_CREATE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_CREATE to notify underlying extensible switch extensions that a new connection is being established between an extensible switch port and an external or virtual network adapter. After the connection is fully established, the protocol edge of the extensible switch issues an OID set request of OID\_SWITCH\_NIC\_CONNECT. +ms.assetid: 1D6B2C6B-A63E-4A20-B534-AF12714F5FB5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_CREATE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_CREATE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_CREATE to notify underlying extensible switch extensions that a new connection is being established between an extensible switch port and an external or virtual network adapter. After the connection is fully established, the protocol edge of the extensible switch issues an OID set request of [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the extensible switch port for which the creation notification is being made. The extensible switch extension can obtain the parameter information for this and other ports on the extensible switch by issuing OID query requests of [OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md). + +The **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the index of a network adapter for which the creation notification is being made. The network adapter with the specified **Index** value is connected to the extensible switch port specified by the **PortId** member. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + +When it receives the OID set request of OID\_SWITCH\_NIC\_CREATE, the extension must follow these guidelines: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure that is associated with the OID request. + +- The OID\_SWITCH\_NIC\_CREATE request only notifies the extension that a new extensible switch connection is being brought up and that packet traffic may soon begin to occur over the specified port. However, the extension cannot use the port until the protocol edge of the extensible switch issues an OID set request of [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md). Until that OID is issued, the extension must not do the following: + + - Generate any packet traffic to the network adapter connection on the extensible switch port for which the OID\_SWITCH\_NIC\_CREATE OID request was issued. + + - Forward or originate OID requests of [OID\_SWITCH\_NIC\_REQUEST](oid-switch-nic-request.md) to an underlying network adapter for which the OID\_SWITCH\_NIC\_CREATE OID request was issued. + + - Forward or originate NDIS status indications of [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/hh598205) from an underlying network adapter for which the OID\_SWITCH\_NIC\_CREATE OID request was issued. + + - Call [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment the extensible switch reference counter for the specified network adapter connection on the extensible switch port. + + **Note**  The extension may intercept send or receive packets for the specified port between the OID requests of OID\_SWITCH\_NIC\_CREATE and [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md). In this case, the extension should forward the send or receive packet requests instead of canceling them. + +   + +- The extension can veto the creation notification by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot satisfy its configured policies on the specified port, the extension should veto the creation notification. + + If the extension returns other NDIS\_STATUS\_*Xxx* status codes, the creation notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + + If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + + **Note**  The extension can only veto the OID request if the **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies a network adapter index value of zero. + +   + +- If the extension does not veto the creation notification, it must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID request to underlying extensions in the extensible switch driver stack. + + **Note**  The extension should monitor the completion status of this OID request. The extension does this to detect whether underlying extensions in the extensible switch driver stack have vetoed the creation notification. + +   + +- If the extension calls [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID request, the extension will not immediately receive any packet traffic to or from the extensible switch port. In addition, the extension cannot immediately inject send or receive traffic for the extensible switch port. + +- The extension can only forward packet traffic to the extensible switch port after the protocol edge of the extensible switch issues an OID set request of [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md). + + **Note**  In some situations, packet traffic may be forwarded by the extensible switch to the port before an OID set request of [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md) is issued. + +   + +- The extensible switch external network adapter can bind to one or more underlying physical adapters. For every physical network adapter that is bound to the external network adapter, the protocol edge of the extensible switch issues a separate OID set request of OID\_SWITCH\_NIC\_CREATE. Each OID set request specifies a different network adapter connection index value. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + + The extension must maintain the connection state for each underlying physical adapter. For more information about the different configurations in which physical network adapters can be bound to the external network adapter, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +**Note**  The extension must not issue its own OID set requests of OID\_SWITCH\_NIC\_CREATE. + +  + +### Return Status Codes + +If the extension completes the OID set request of OID\_SWITCH\_NIC\_CREATE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_DATA_NOT_ACCEPTED

The extension vetoed the creation notification.

NDIS_STATUS_RESOURCES

The extension vetoed the creation notification due to a low resource condition.

NDIS_STATUS_Xxx

The extension vetoed the creation notification for other reasons.

+ +  + +**Note**  If the extension completes the OID set request, it must not return NDIS\_STATUS\_SUCCESS. + +  + +If the extension does not complete the OID set request of OID\_SWITCH\_NIC\_CREATE, the request is completed by the underlying miniport edge of the extensible switch. The underlying miniport edge returns the following status code for this OID set request: + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_CREATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-delete.md b/windows-driver-docs-pr/network/oid-switch-nic-delete.md new file mode 100644 index 0000000000..e6f4323bd3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-delete.md @@ -0,0 +1,118 @@ +--- +title: OID\_SWITCH\_NIC\_DELETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_DELETE to the extensible switch driver stack. +ms.assetid: 7564EA39-09F5-45A3-81A0-F8DD2B23B639 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_DELETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_DELETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_DELETE to the extensible switch driver stack. This OID request notifies underlying extensible switch extensions about the deletion of a connection between an extensible switch port and a network adapter. The protocol edge of the extensible switch previously notified extensions that this connection is being deleted when it issued an OID set request of [OID\_SWITCH\_NIC\_DISCONNECT](oid-switch-nic-disconnect.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the port for which the deletion notification is being made. The extensible switch extension can obtain the parameter information for this and other ports on the extensible switch by issuing OID query requests of [OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md). + +The **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the index of a network adapter for which the deletion notification is being made. The network adapter with the specified **Index** value is connected to the extensible switch port specified by the **PortId** member. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + +Before the protocol edge of the extensible switch issues the OID\_SWITCH\_NIC\_DELETE request, it guarantees that all pending send or receive packet requests for the specified network adapter connection have been completed. The protocol edge also guarantees that all pending OID requests for the adapter connection have been completed, and the extensible switch reference counters for the adapter connection have a zero value. + +**Note**  If the extension had incremented an extensible switch reference counter for the network adapter by calling [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294), the OID\_SWITCH\_NIC\_DELETE request is not issued while the reference counter is nonzero. The extension decrements the extensible switch reference counter by calling [*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141). + +  + +The extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_NIC\_DELETE: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure that is associated with the OID request. + +- The extension must always forward this OID set request to underlying extensions. The extension must not complete the request. + +- The extension must not issue its own OID set requests of OID\_SWITCH\_NIC\_DELETE. + +- The extensible switch external network adapter can bind to one or more underlying physical adapters. For every physical network adapter that is bound to the external network adapter, the protocol edge of the extensible switch issues a separate OID set request of OID\_SWITCH\_NIC\_DELETE. Each OID set request specifies a different network adapter connection index value. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + + The extension must maintain the connection state for each underlying physical adapter. For more information about the different configurations in which physical network adapters can be bound to the external network adapter, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_DELETE and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[OID\_SWITCH\_NIC\_DISCONNECT](oid-switch-nic-disconnect.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-disconnect.md b/windows-driver-docs-pr/network/oid-switch-nic-disconnect.md new file mode 100644 index 0000000000..d890812abe --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-disconnect.md @@ -0,0 +1,132 @@ +--- +title: OID\_SWITCH\_NIC\_DISCONNECT +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_DISCONNECT to notify underlying extensible switch extensions that a connection between an extensible switch port and a network adapter is being torn down. After the connection is completely torn down, the protocol edge of the extensible switch will issue an OID set request of OID\_SWITCH\_NIC\_DELETE. +ms.assetid: 367081A7-F259-4132-B857-C956C0F2829C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_DISCONNECT Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_DISCONNECT + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_DISCONNECT to notify underlying extensible switch extensions that a connection between an extensible switch port and a network adapter is being torn down. After the connection is completely torn down, the protocol edge of the extensible switch will issue an OID set request of [OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +Remarks +------- + +The **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the index of a network adapter for which the disconnect notification is being made. The network adapter with the specified **Index** value is connected to the extensible switch port specified by the **PortId** member. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + +The extension must follow these guidelines when it handles OID set requests of OID\_SWITCH\_NIC\_DISCONNECT: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure that is associated with the OID request. + +- The OID\_SWITCH\_NIC\_DISCONNECT request only notifies the extension that the extensible switch connection is being torn down between the specified network adapter and extensible switch port. After the extension handles this OID request, it must not do the following: + + - Generate any packet traffic to the network adapter connection on the extensible switch port for which the OID\_SWITCH\_NIC\_DISCONNECT OID request was issued. + + - Call [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment the extensible switch reference counter for the specified network adapter connection on the extensible switch port. + + - Forward or originate OID requests of [OID\_SWITCH\_NIC\_REQUEST](oid-switch-nic-request.md) to an underlying network adapter for which the OID\_SWITCH\_NIC\_DISCONNECT OID request was issued. + + **Note**  If the extension called [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment the extensible switch reference counter before the OID\_SWITCH\_NIC\_DISCONNECT is issued, the extension can still forward or originate OID requests. + +   + + - Forward or originate NDIS status indications of [**NDIS\_STATUS\_SWITCH\_NIC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/hh598205) from an underlying network adapter for which the OID\_SWITCH\_NIC\_DISCONNECT OID request was issued. + + **Note**  If the extension called [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment the extensible switch reference counter before the OID\_SWITCH\_NIC\_DISCONNECT is issued, the extension can still forward or originate NDIS status indications. + +   + + **Note**  If the extension previously called [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment the extensible switch reference counter, it does not need to synchronize its calls to originate or forward OID requests or NDIS status indications with its code that manages Hyper-V extensible switch OID requests. After the extension increments the reference counter, the extensible switch interface will not issue an OID set request of [OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md). + +   + +- The extension must always forward this OID set request to underlying extensions. The extension must not complete the request. + +- The extensible switch external network adapter can bind to one or more underlying physical adapters. For every physical network adapter that is bound to the external network adapter, the protocol edge of the extensible switch issues a separate OID set request of OID\_SWITCH\_NIC\_DISCONNECT. Each OID set request specifies a different network adapter connection index value. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + + The extension must maintain the connection state for each underlying physical adapter. For more information about the different configurations in which physical network adapters can be bound to the external network adapter, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +**Note**  The extension must not issue its own OID set requests of OID\_SWITCH\_NIC\_DISCONNECT. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_DISCONNECT and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_DISCONNECT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-request.md b/windows-driver-docs-pr/network/oid-switch-nic-request.md new file mode 100644 index 0000000000..97c3ac947f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-request.md @@ -0,0 +1,148 @@ +--- +title: OID\_SWITCH\_NIC\_REQUEST +author: windows-driver-content +description: An object identifier (OID) method request of OID\_SWITCH\_NIC\_REQUEST is used to encapsulate and forward OID requests to the Hyper-V extensible switch external network adapter. +ms.assetid: 7EF4D950-D18E-400A-B1DD-39768A16E4C4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_REQUEST + + +An object identifier (OID) method request of OID\_SWITCH\_NIC\_REQUEST is used to encapsulate and forward OID requests to the Hyper-V extensible switch external network adapter. This allows the encapsulated OID request to be delivered to the driver for the underlying physical network adapter that is bound to the external network adapter. + +This OID request is also used to encapsulate OID requests that were issued to other network adapters that are connected to extensible switch ports. In this case, the encapsulated OID request is forwarded through the extensible switch driver stack for inspection by extensions. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh598214) structure. This structure specifies the forwarding information for the OID request. This structure also contains a pointer to the original **NDIS\_OID\_REQUEST** structure of the OID request that is being forwarded. + +Remarks +------- + +When OID requests arrive at the Hyper-V extensible switch interface, it encapsulates them in order to forward them down the extensible switch control path. These OID requests include the following: + +- Hardware offload OID requests, including requests for Internet Protocol security (IPsec), virtual machine queue (VMQ), and single root I/O virtualization (SR-IOV). These OID requests are issued by an overlying protocol or filter driver that runs in the management operating system of the Hyper-V parent partition. + + When these OID requests arrive at the extensible switch interface, the protocol edge of the extensible switch encapsulates the OID request within an [**NDIS\_SWITCH\_NIC\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh598214) structure. The protocol edge sets the members of this structure in the following way: + + - The **DestinationPortId** and **DestinationNicIndex** members are set to the corresponding values for the external network adapter. + + - If the OID request was originated from a Hyper-V child partition, the **SourcePortId** and **SourceNicIndex** members are set to the corresponding values for the port and network adapter that are used by the partition. Otherwise, the **SourcePortId** and **SourceNicIndex** members are set to zero. + + **Note**  The extension must retain the values of these members if it forwards or redirects the OID request. + +   + + - The **OidRequest** member is set to a pointer to the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure for the encapsulated OID request. + + The protocol edge then issues the OID\_SWITCH\_NIC\_REQUEST request to forward the encapsulated OID request down the extensible switch control path to the external network adapter. + + An underlying forwarding extension can redirect encapsulated hardware offload OID requests to a physical network adapter that is bound to the external network adapter. For example, if the extension supports physical network adapters from an extensible switch team that are bound to the external network adapter, it can forward the OID\_SWITCH\_NIC\_REQUEST request to a physical adapter in the load balancing failover (LBFO) team that supports the hardware offload. For more information on this procedure, see [Managing Hardware Offload OID Requests to Physical Network Adapters](https://msdn.microsoft.com/library/windows/hardware/hh598194). + + For more information about extensible switch teams, see [Types of Physical Network Adapter Configurations](https://msdn.microsoft.com/library/windows/hardware/hh582274). + +- Multicast OID requests, including [OID\_802\_3\_ADD\_MULTICAST\_ADDRESS](oid-802-3-add-multicast-address.md) and [OID\_802\_3\_DELETE\_MULTICAST\_ADDRESS](oid-802-3-delete-multicast-address.md). These OID requests are issued by overlying protocol and filter drivers that run in either the management operating system or the guest operating system of a Hyper-V child partition. + + When these OID requests arrive at the extensible switch interface, the protocol edge of the extensible switch encapsulates the OID request within an [**NDIS\_SWITCH\_NIC\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh598214) structure. The protocol edge also sets the **SourcePortId** and **SourceNicIndex** members to the corresponding values for the port and network adapter from which the OID request originated. The protocol edge then issues the OID\_SWITCH\_NIC\_REQUEST request to forward the encapsulated OID request down the extensible switch control path for inspection by underlying extensions. + + **Note**  In this case, the protocol edge sets the **DestinationPortId** and **DestinationNicIndex** members to zero. This specifies that the encapsulated OID request is to be delivered to extensions in the control path. + +   + + Underlying forwarding extensions can inspect these encapsulated OID requests and retain the multicast address information that they specify. For example, the extension may need this information if it originates multicast packets that it forwards to an extensible switch port. + + For more information, see [Forwarding OID Requests from a Hyper-V Child Partition](https://msdn.microsoft.com/library/windows/hardware/hh598150). + +A forwarding extension can also issue an OID\_SWITCH\_NIC\_REQUEST in order to forward encapsulated OID requests to a physical network adapter that is bound to the external network adapter. This allows the extension to originate its own OID request or redirect an existing OID request to a physical network adapter that is bound to the external network adapter. In order to do this, the extension must follow these steps: + +1. The extension calls [*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) to increment a reference counter for the index of the destination physical network adapter. This guarantees that the extensible switch interface will not delete the physical network adapter connection while its reference counter is nonzero. + + **Note**  The extensible switch interface could disconnect the physical network adapter connection while its reference counter is nonzero. For more information, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +   + +2. The extension encapsulates the OID request by initializing an [**NDIS\_SWITCH\_NIC\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh598214) structure in the following way: + + - The **DestinationPortId** member must be set to the identifier of the extensible switch port to which the external network adapter is connected. + - The **DestinationNicIndex** member must be set to the nonzero index value of the underlying physical network adapter. + - If the extension is originating on behalf of a Hyper-V child partition, the **SourcePortId** and **SourceNicIndex** members are set to the corresponding values for the port and network adapter that are used by the partition. Otherwise, the **SourcePortId** and **SourceNicIndex** members are set to zero. + + For example, if the extension is managing hardware offload resources for a child partition, it must set the **SourcePortId** and **SourceNicIndex** members to specify which partition the encapsulated hardware offload OID request is for. + + - The **OidRequest** member must be set to a pointer to an initialized [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure for the encapsulated OID request. + +3. The extension calls [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the specified destination extensible switch port and network adapter. + +4. When NDIS calls the [*FilterOidRequestComplete*](https://msdn.microsoft.com/library/windows/hardware/ff549956) function, the extension calls [*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141) to clear the reference counter for the index of the destination physical network adapter. + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_REQUEST and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_Xxx

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_STATUS\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567373) + +[**NDIS\_SWITCH\_NIC\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/hh598214) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_REQUEST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-restore-complete.md b/windows-driver-docs-pr/network/oid-switch-nic-restore-complete.md new file mode 100644 index 0000000000..052a4891be --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-restore-complete.md @@ -0,0 +1,95 @@ +--- +title: OID\_SWITCH\_NIC\_RESTORE\_COMPLETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_RESTORE\_COMPLETE to notify Hyper-V extensible switch extensions about the completion of the operation to restore run-time data. +ms.assetid: E47EBA55-FF35-4366-AF9C-A714C2E6F8FE +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_RESTORE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_RESTORE\_COMPLETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_RESTORE\_COMPLETE to notify Hyper-V extensible switch extensions about the completion of the operation to restore run-time data. Through this operation, the extension restores its run-time data for a port and its associated network adapter connection. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure. This structure is allocated by the protocol edge of the extensible switch. + +Remarks +------- + +When it receives the OID set request of OID\_SWITCH\_NIC\_RESTORE\_COMPLETE, the extension must follow these guidelines: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure that is associated with the OID request. +- The extension must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID set request to underlying extensions in the extensible switch driver stack. The extension must not fail the OID request. + +OID set requests of OID\_SWITCH\_NIC\_RESTORE\_COMPLETE are ultimately handled by the underlying miniport edge of the extensible switch. After this OID method request has been received by the miniport edge, it completes the OID request with NDIS\_STATUS\_SUCCESS. This notifies the protocol edge of the extensible switch that all extensions in the extensible switch driver stack have completed the save operation. + +For more information on how to save run-time data for an extensible switch port, see [Saving Hyper-V Extensible Switch Run-Time Data](https://msdn.microsoft.com/library/windows/hardware/hh598299). + +### Return Status Codes + +If the extension completes the OID set request of [OID\_SWITCH\_NIC\_RESTORE\_COMPLETE](oid-switch-nic-restore.md), it returns one of the following status codes. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_RESTORE_COMPLETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-restore.md b/windows-driver-docs-pr/network/oid-switch-nic-restore.md new file mode 100644 index 0000000000..6c5a44c753 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-restore.md @@ -0,0 +1,114 @@ +--- +title: OID\_SWITCH\_NIC\_RESTORE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_RESTORE to notify the extensible switch extension about run-time data that can be restored for an extensible switch port and its network adapter connection. +ms.assetid: 252FB1D2-932F-4FB8-83D6-2690171D746D +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_RESTORE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_RESTORE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_RESTORE to notify the extensible switch extension about run-time data that can be restored for an extensible switch port and its network adapter connection. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure. This structure is allocated by the protocol edge of the extensible switch. + +Remarks +------- + +When it receives the OID set request of OID\_SWITCH\_NIC\_RESTORE, the extensible switch extension must first determine whether it owns the run-time data. The extension does this by comparing the value of the **ExtensionId** member of the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure to the GUID value that the extension uses to identify itself. + +If the extension owns the run-time data for an extensible switch port, it restores this data in the following way: + +1. The extension copies the run-time data in the **SaveData** member to extension-allocated storage. + + **Note**  The value of the **PortId** member of the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure may be different from the **PortId** value at the time that the run-time data was saved. This can occur if run-time data was saved during a Live Migration from one host to another. However, the configuration of the extensible switch port is retained during the Live Migration. This enables the extension to restore the run-time data to the extensible switch port by using the new **PortId** value. + +   + +2. The extension completes the OID set request with NDIS\_STATUS\_SUCCESS. + +If the extension does not own the specified run-time data, the extension calls [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID set request to underlying extensions in the extensible switch driver stack. In this case, the extension must not modify the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure that is associated with the OID request. + +If the OID\_SWITCH\_NIC\_RESTORE set request is received by the miniport edge of the extensible switch, it completes the OID request with NDIS\_STATUS\_SUCCESS. This notifies the protocol edge of the extensible switch that no extension owns the run-time data. + +For more information about how to restore run-time data, see [Restoring Hyper-V Extensible Switch Run-Time Data](https://msdn.microsoft.com/library/windows/hardware/hh598298). + +**Note**  If the extension fails the OID set request, the extensible switch will fail the entire restore operation. As a result, the extension should avoid failing the OID request if it is possible. For example, if the extension cannot allocate the resource necessary to restore the run-time data, it should fail the OID request if it cannot function properly without restoring the run-time data. However, if the extension can recover from the failure condition, it should not fail the OID set request. + +  + +### Return Status Codes + +If the extension completes the OID set request of OID\_SWITCH\_NIC\_RESTORE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_Xxx

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_RESTORE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-save-complete.md b/windows-driver-docs-pr/network/oid-switch-nic-save-complete.md new file mode 100644 index 0000000000..e9ce088c78 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-save-complete.md @@ -0,0 +1,96 @@ +--- +title: OID\_SWITCH\_NIC\_SAVE\_COMPLETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_SAVE\_COMPLETE to notify Hyper-V extensible switch extensions about the completion of the operation to save run-time data. +ms.assetid: 75D4C0D5-B4B2-493D-8D1D-400F60613FCA +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_SAVE_COMPLETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_SAVE\_COMPLETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_SAVE\_COMPLETE to notify Hyper-V extensible switch extensions about the completion of the operation to save run-time data. Through this operation, the extension saves run-time data for a port and its associated network adapter connection. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure. + +Remarks +------- + +When it receives the OID set request of OID\_SWITCH\_NIC\_SAVE\_COMPLETE, the extension must follow these guidelines: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure that is associated with the OID request. + +- The extension must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID set request to underlying extensions in the extensible switch driver stack. The extension must not fail the OID request. + +OID set requests of OID\_SWITCH\_NIC\_SAVE\_COMPLETE are ultimately handled by the underlying miniport edge of the extensible switch. After this OID method request has been received by the miniport edge, it completes the OID request with NDIS\_STATUS\_SUCCESS. This notifies the protocol edge of the extensible switch that all extensions in the extensible switch driver stack have completed the save operation. + +For more information on how to save run-time data for an extensible switch port, see [Saving Hyper-V Extensible Switch Run-Time Data](https://msdn.microsoft.com/library/windows/hardware/hh598299). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_SAVE\_COMPLETE and returns one of the following status codes. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_SAVE_COMPLETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-save.md b/windows-driver-docs-pr/network/oid-switch-nic-save.md new file mode 100644 index 0000000000..6334044c65 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-save.md @@ -0,0 +1,141 @@ +--- +title: OID\_SWITCH\_NIC\_SAVE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_NIC\_SAVE during an operation to save run-time data for an extensible switch port and its network adapter connection. +ms.assetid: FE2F9767-7186-42FF-85C1-2A8203FEF629 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_SAVE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_SAVE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_NIC\_SAVE during an operation to save run-time data for an extensible switch port and its network adapter connection. The extension returns this data so that run-time data can be saved and restored at a later time. After the run-time data is saved, it is restored through OID set requests of [OID\_SWITCH\_NIC\_RESTORE](oid-switch-nic-restore.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure. This structure is allocated by the protocol edge of the extensible switch. + +Remarks +------- + +When it receives the OID method request of OID\_SWITCH\_NIC\_SAVE, the extensible switch extension saves run-time data by doing the following: + +- The extension saves the data within the [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure starting from *SaveDataOffset* bytes from the start of the structure. + +- If the *SaveDataSize* provided is not large enough to hold the required save data, the extension sets the method structure’s *BytesNeeded* field to NDIS\_SIZEOF\_NDIS\_SWITCH\_NIC\_SAVE\_STATE\_REVISION\_1 plus the amount of buffer necessary to hold the save data, and completes the OID with NDIS\_STATUS\_BUFFER\_TOO\_SHORT. The OID will be reissued with the required size. + +- The extension populates the *ExtensionId* and *ExtensionFriendlyName* fields with its own identifier and name, and completes the OID method request with NDIS\_STATUS\_SUCCESS. This causes the protocol edge of the extensible switch to issue another OID method request to allow the extension to either return more save data, or allow other extensions down the stack to save their own data. + +**Note**  If the extension does not have run-time data to save, it must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID method request to underlying extensions in the extensible switch driver stack. For more information about this procedure, see [Filtering OID Requests in an NDIS Filter Driver](https://msdn.microsoft.com/library/windows/hardware/ff549950). + +  + +The Hyper-V extensible switch populates the *Header*, *PortId*, *NicIdex*, *SaveDataSize* and *SaveDataOffset* fields of the structure before issuing the OID. The extension cannot modify these fields. + +OID method requests of OID\_SWITCH\_NIC\_SAVE are ultimately handled by the underlying miniport edge of the extensible switch. After this OID method request has been received by the miniport edge of the extensible switch, it completes the OID request with NDIS\_STATUS\_SUCCESS. This notifies the protocol edge of the extensible switch that all extensions in the extensible switch driver stack have been queried for run-time data. The protocol edge of the extensible switch then issues an OID set request of [OID\_SWITCH\_NIC\_SAVE\_COMPLETE](oid-switch-nic-save-complete.md) to complete the save operation. + +For more information on how to save run-time data for an extensible switch port, see [Saving Hyper-V Extensible Switch Run-Time Data](https://msdn.microsoft.com/library/windows/hardware/hh598299). + +### Return Status Codes + +The extensible switch extension returns one of the following status codes for the OID method request of OID\_SWITCH\_NIC\_SAVE. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_BUFFER_TOO_SHORT

The length of the information buffer is too small for the [NDIS_SWITCH_NIC_SAVE_STATE](https://msdn.microsoft.com/library/windows/hardware/hh598216) and its associated run-time data The extensible switch extension must set the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_SUCCESS

The extension returns this status if it is returning run-time data to save.

NDIS_STATUS_Xxx

The request failed for other reasons.

+ +  + +The underlying miniport edge of the extensible switch returns the following status code for the OID method request of OID\_SWITCH\_NIC\_SAVE. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_RESTORE](oid-switch-nic-restore.md) + +[OID\_SWITCH\_NIC\_SAVE\_COMPLETE](oid-switch-nic-save-complete.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_SAVE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-nic-updated.md b/windows-driver-docs-pr/network/oid-switch-nic-updated.md new file mode 100644 index 0000000000..2386ad9648 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-nic-updated.md @@ -0,0 +1,104 @@ +--- +title: OID\_SWITCH\_NIC\_UPDATED +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_UPDATED to the extensible switch driver stack. +ms.assetid: C1B446A3-861F-41B4-99EF-C7CB45F86F39 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_NIC_UPDATED Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_NIC\_UPDATED + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_NIC\_UPDATED to the extensible switch driver stack. This OID request notifies underlying extensible switch extensions about the update of the parameters of a network adapter. The OID will only be issued for NICs that have already been connected, and have not yet begun the disconnect process. These run-time configuration changes can include **NicFriendlyName**, **NetCfgInstanceId**, **MTU**, **NumaNodeId**, **PermanentMacAddress**, **VMMacAddress**, **CurrentMacAddress**, and **VFAssigned**. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the port for which the update notification is being made. The extensible switch extension can obtain the parameter information for this and other ports on the extensible switch by issuing OID query requests of [OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md). + +The **Index** member of the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure specifies the index of a network adapter for which the update notification is being made. The network adapter with the specified **Index** value is connected to the extensible switch port specified by the **PortId** member. For more information on these index values, see [Network Adapter Index Values](https://msdn.microsoft.com/library/windows/hardware/hh598258). + +The extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_NIC\_UPDATED: + +- The extension must not modify the [**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) structure that is associated with the OID request. +- The extension must always forward this OID set request to underlying extensions. The extension must not complete the request. +- The extension must not issue its own OID set requests of OID\_SWITCH\_NIC\_UPDATED. + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_NIC\_UPDATED and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_NIC\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598215) + +[OID\_SWITCH\_NIC\_DISCONNECT](oid-switch-nic-disconnect.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_NIC_UPDATED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-parameters.md b/windows-driver-docs-pr/network/oid-switch-parameters.md new file mode 100644 index 0000000000..7b921ed64d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-parameters.md @@ -0,0 +1,102 @@ +--- +title: OID\_SWITCH\_PARAMETERS +author: windows-driver-content +description: A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_PARAMETERS to obtain the configuration data of the extensible switch. +ms.assetid: F2CA0BE5-ED21-4ACF-B26A-4F512D4B15C7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PARAMETERS + + +A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_PARAMETERS to obtain the configuration data of the extensible switch. + +If the OID query request completes successfully, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) structure. + +Remarks +------- + +When the extension processes the returned [**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) structure, it must not assume that the various string members of the **NDIS\_SWITCH\_PARAMETERS** structure, such as **SwitchName**, are null-terminated. The data types for these string members are type-defined by the [**IF\_COUNTED\_STRING**](https://msdn.microsoft.com/library/windows/hardware/hh451419) structure. The extension must determine the string length from the value of the **Length** member of this structure. + +**Note**  If the string is null-terminated, the **Length** member must not include the terminating null character. + +  + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_PARAMETERS and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the OID_SWITCH_PARAMETERS structure for an OID query request. The underlying miniport edge of the extensible switch sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PARAMETERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-array.md b/windows-driver-docs-pr/network/oid-switch-port-array.md new file mode 100644 index 0000000000..4a2daaf86e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-array.md @@ -0,0 +1,114 @@ +--- +title: OID\_SWITCH\_PORT\_ARRAY +author: windows-driver-content +description: A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_PORT\_ARRAY to obtain an array. Each element in the array specifies the configuration parameters for an extensible switch port. +ms.assetid: 9ED5E7A5-A23E-48E7-B8A2-9089C81851A1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_ARRAY Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_ARRAY + + +A Hyper-V extensible switch extension issues an object identifier (OID) query request of OID\_SWITCH\_PORT\_ARRAY to obtain an array. Each element in the array specifies the configuration parameters for an extensible switch port. + +If the OID query request completes successfully, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) structure that defines the number of elements within the array. + +- An array of [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structures. Each of these structures contains information about a port on the extensible switch. + + **Note**  If no ports have been created on the extensible switch, the driver sets the **NumElements** member of the [**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) structure to zero and no [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structures are returned. + +   + +Remarks +------- + +The OID\_SWITCH\_PORT\_ARRAY OID must only be issued when the Hyper-V extensible switch has completed activation. Please see [Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) for more details. + +When the extension handles the returned [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure, it must not assume that the various string members of the **NDIS\_SWITCH\_PORT\_PARAMETERS** structure, such as **PortName**, are null-terminated. The data types for these string members are type-defined by the [**IF\_COUNTED\_STRING**](https://msdn.microsoft.com/library/windows/hardware/hh451419) structure. The driver must determine the string length from the value of the **Length** member of this structure. + +**Note**  If the string is null-terminated, the **Length** member must not include the terminating null character. + +  + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_PORT\_ARRAY and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the [NDIS_SWITCH_PORT_ARRAY](https://msdn.microsoft.com/library/windows/hardware/hh598221) and its array of [NDIS_SWITCH_PORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598229) elements. The underlying miniport edge of the extensible switch sets the DATA.QUERY_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/hh598221) + +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_ARRAY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-create.md b/windows-driver-docs-pr/network/oid-switch-port-create.md new file mode 100644 index 0000000000..ea7b0f628b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-create.md @@ -0,0 +1,155 @@ +--- +title: OID\_SWITCH\_PORT\_CREATE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_CREATE to notify extensible switch extensions about the creation of an extensible switch port. +ms.assetid: 579D51CD-0594-4A06-998E-3886E7325D97 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_CREATE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_CREATE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_CREATE to notify extensible switch extensions about the creation of an extensible switch port. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure specifies the port for which the creation notification is being made. + +The extensible switch extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_PORT\_CREATE: + +- The extension must not modify the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure that is associated with the OID request. + +- The extension can veto the creation notification by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot allocate resources to enforce its configured policies on the port, the driver should veto the creation notification. + + If the extension returns other NDIS\_STATUS\_*Xxx* error status codes, the creation notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + + If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + + For more information on port policies, see [Managing Hyper-V Extensible Switch Policies](https://msdn.microsoft.com/library/windows/hardware/hh598195). + +- If the extension calls [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward this OID set request, the extension should monitor the completion status of this OID request. The extension does this to detect whether underlying extensions in the extensible switch driver stack have vetoed the port creation notification. + +- After the OID request is forwarded and completes successfully, the extension can issue OIDs requests for the port, such as [OID\_SWITCH\_PORT\_PROPERTY\_ENUM](oid-switch-port-property-enum.md), until an OID request of [OID\_SWITCH\_PORT\_TEARDOWN](oid-switch-port-teardown.md) is issued. This OID request notifies the extension that the port will begin the deletion process from the extensible switch. + +- Extensions cannot forward packets to the specified port in the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure until an OID set request of [OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md) is issued and is completed successfully. + +**Note**  Extensions must not issue OID set requests of OID\_SWITCH\_PORT\_CREATE. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +If the extension completes the OID set request of OID\_SWITCH\_PORT\_CREATE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_DATA_NOT_ACCEPTED

The extension vetoed the creation notification.

NDIS_STATUS_RESOURCES

The extension vetoed the creation notification due to a low resource condition.

NDIS_STATUS_Xxx

The extension vetoed the creation notification for other reasons.

+ +  + +**Note**  If the extension completes the OID set request, it must not return NDIS\_STATUS\_SUCCESS. + +  + +If the extension does not complete the OID set request of OID\_SWITCH\_PORT\_CREATE, the request is completed by the underlying miniport edge of the extensible switch. The underlying miniport edge returns the following status code for this OID set request. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_CONNECT](oid-switch-nic-connect.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[OID\_SWITCH\_PORT\_PROPERTY\_ENUM](oid-switch-port-property-enum.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_CREATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-delete.md b/windows-driver-docs-pr/network/oid-switch-port-delete.md new file mode 100644 index 0000000000..be374e16d7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-delete.md @@ -0,0 +1,130 @@ +--- +title: OID\_SWITCH\_PORT\_DELETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_DELETE to notify extensible switch extensions about the deletion of an extensible switch port. +ms.assetid: D8893395-3D33-4777-B8F0-4DD6BE9B8A37 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_DELETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_DELETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_DELETE to notify extensible switch extensions about the deletion of an extensible switch port. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure specifies the extensible switch port for which the delete notification is being made. + +If a network adapter is connected to the specified port, the protocol edge of the extensible switch will delete the connection before it deletes the port. In this case, the protocol edge will follow these steps before it deletes the port: + +- The protocol edge issues an OID set request of [OID\_SWITCH\_NIC\_DISCONNECT](oid-switch-nic-disconnect.md) to notify the extension that the connection between a network adapter and the extensible switch port is being deleted. + +- After all pending packets for the specified extensible switch port have been canceled or completed, the protocol edge issues an OID set request of [OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) to notify the extension that the connection between a network adapter and the extensible switch port has been deleted. + + At this point, the protocol edge can start to delete the port. + +The protocol edge of the extensible switch follows these steps when it deletes an extensible switch port: + +1. The protocol edge of the extensible switch issues an OID set request of [OID\_SWITCH\_PORT\_TEARDOWN](oid-switch-port-teardown.md). This OID request notifies underlying extensible switch extensions about the start of the deletion process for an extensible switch port. + +2. The protocol edge issues an OID set request of OID\_SWITCH\_PORT\_DELETE after all OID requests to the extensible switch port have completed. + + **Note**  If the extension had previously called [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) to increment the port's reference counter, it must call [*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142) before the protocol edge issues the [OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) request. + +   + +The extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_PORT\_DELETE: + +- The extension must not modify the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure that is associated with the OID request. + +- The extension must always forward this OID set request to underlying extensions. The extension must not fail the request. + +- After the OID\_SWITCH\_PORT\_DELETE request is completed with NDIS\_STATUS\_SUCCESS, the extension will not receive any packets or OID requests for the deleted port. The extension cannot forward packets to the deleted port. The extension also cannot issue OID requests nor call the [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) function for the deleted port. + +**Note**  Extensible switch extensions must not issue OID set requests of OID\_SWITCH\_PORT\_DELETE. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID set request of OID\_SWITCH\_PORT\_DELETE and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-feature-status-query.md b/windows-driver-docs-pr/network/oid-switch-port-feature-status-query.md new file mode 100644 index 0000000000..585b25890e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-feature-status-query.md @@ -0,0 +1,104 @@ +--- +title: OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY to obtain custom status information from an extension about an extensible switch port. +ms.assetid: 577CF1C2-9737-4FB0-9C40-AEE529EF1439 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_FEATURE_STATUS_QUERY Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) method request of OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY to obtain custom status information from an extension about an extensible switch port. This information is known as *feature status* information. The format of this information is defined by the independent software vendor (ISV). + +After a successful return from this OID method request, the **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PORT\_FEATURE\_STATUS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598227) structure that specifies the parameters for the type of feature status information to be returned. + +- An [**NDIS\_SWITCH\_PORT\_FEATURE\_STATUS\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598226) structure that contains the feature status information for the extensible switch port. + +Remarks +------- + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY, see [Managing Custom Port Feature Status Information](https://msdn.microsoft.com/library/windows/hardware/hh598192). + +### Return Status Codes + +The extension returns one of the following status codes for the OID method request of OID\_SWITCH\_PORT\_FEATURE\_STATUS\_QUERY. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the feature status information as well as the [NDIS_SWITCH_PORT_FEATURE_STATUS_CUSTOM](https://msdn.microsoft.com/library/windows/hardware/hh598226) and [NDIS_SWITCH_PORT_FEATURE_STATUS_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598227) structures. The underlying miniport edge of the extensible switch sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_FEATURE\_STATUS\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598226) + +[**NDIS\_SWITCH\_PORT\_FEATURE\_STATUS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598227) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/hh598242) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_FEATURE_STATUS_QUERY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-property-add.md b/windows-driver-docs-pr/network/oid-switch-port-property-add.md new file mode 100644 index 0000000000..7cba5a25f6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-property-add.md @@ -0,0 +1,143 @@ +--- +title: OID\_SWITCH\_PORT\_PROPERTY\_ADD +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD to notify extensible switch extensions about the addition of a policy property for an extensible switch port. +ms.assetid: 6F246E5A-A02A-4303-9DB0-51E2FD4DC9E7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_PROPERTY_ADD Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_PROPERTY\_ADD + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD to notify extensible switch extensions about the addition of a policy property for an extensible switch port. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure that specifies the identification and type of parameters for a port policy. + +- A property buffer that contains the parameters for a port policy. The property buffer contains a structure that is based on the **PropertyType** member of the [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure. For example, if the **PropertyType** member is set to **NdisSwitchPortPropertyTypeVlan**, the property buffer contains an [**NDIS\_SWITCH\_PORT\_PROPERTY\_VLAN**](https://msdn.microsoft.com/library/windows/hardware/hh598243) structure. + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +The extension can veto the addition of the port property by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot allocate resources to enforce its configured policies on the port, it should veto the addition request. + +**Note**  If the extension returns other NDIS\_STATUS\_*Xxx* error status codes, the creation notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + +  + +If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD, see [Managing Port Policies](https://msdn.microsoft.com/library/windows/hardware/hh598202). + +### Return Status Codes + +If the forwarding extension completes the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD, it returns one of the following status codes: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to process the [NDIS_SWITCH_PORT_PROPERTY_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure and the data in the structure's property buffer. The extension sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_DATA_NOT_ACCEPTED

The forwarding extension has vetoed the port policy addition notification.

NDIS_STATUS_NOT_SUPPORTED

The forwarding extension does not support the port policy.

NDIS_STATUS_Xxx

The OID request failed for other reasons.

+ +  + +If the extension does not complete the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_ADD, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code: + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_VLAN**](https://msdn.microsoft.com/library/windows/hardware/hh598243) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_PROPERTY_ADD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-property-delete.md b/windows-driver-docs-pr/network/oid-switch-port-property-delete.md new file mode 100644 index 0000000000..b8dfca2c89 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-property-delete.md @@ -0,0 +1,127 @@ +--- +title: OID\_SWITCH\_PORT\_PROPERTY\_DELETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE to notify extensible switch extensions about the deletion of a policy property for an extensible switch port. +ms.assetid: BA8AB5D9-FF2C-4E16-B09F-B09E3EC19B90 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_PROPERTY_DELETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_PROPERTY\_DELETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE to notify extensible switch extensions about the deletion of a policy property for an extensible switch port. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer that contains an [**NDIS\_SWITCH\_PORT\_PROPERTY\_DELETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598232) structure. + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE, see [Managing Port Policies](https://msdn.microsoft.com/library/windows/hardware/hh598202). + +### Return Status Codes + +If the forwarding extension completes the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The forwarding extension does not support the port policy.

NDIS_STATUS_Xxx

The OID request failed for other reasons.

+ +  + +If the forwarding extension does not complete the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_DELETE, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_VLAN**](https://msdn.microsoft.com/library/windows/hardware/hh598243) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_PROPERTY_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-property-enum.md b/windows-driver-docs-pr/network/oid-switch-port-property-enum.md new file mode 100644 index 0000000000..97875d4c68 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-property-enum.md @@ -0,0 +1,118 @@ +--- +title: OID\_SWITCH\_PORT\_PROPERTY\_ENUM +author: windows-driver-content +description: The Hyper-V extensible switch extension issues an object identifier (OID) method request of OID\_SWITCH\_PORT\_PROPERTY\_ENUM to obtain an array. +ms.assetid: 5C391B82-FCA6-4A95-992F-EDB5DF6183C7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_PROPERTY_ENUM Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_PROPERTY\_ENUM + + +The Hyper-V extensible switch extension issues an object identifier (OID) method request of OID\_SWITCH\_PORT\_PROPERTY\_ENUM to obtain an array. This array contains the provisioned port policies that match the specified criteria. Each element in the array specifies the properties of a policy for a specified extensible switch port. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure that specifies the parameters for the policy enumeration of a specified port. + +- An array of [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) structures. Each of these structures contains information about the properties of an extensible switch port policy. + + **Note**  If the **NumProperties** member of the [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) structure is set to zero, no [**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) structures are returned. + +   + +Remarks +------- + +Before it issues an OID method request of OID\_SWITCH\_PORT\_PROPERTY\_ENUM, the extensible switch extension must follow these guidelines: + +- The extension can only issue the OID\_SWITCH\_PORT\_PROPERTY\_ENUM request after the protocol edge of the extensible switch issues an [OID\_SWITCH\_PORT\_CREATE](oid-switch-port-create.md) request and before it issues an [OID\_SWITCH\_PORT\_TEARDOWN](oid-switch-port-teardown.md) request. + +- The extension must call [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) before it calls [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to issue the OID\_SWITCH\_PORT\_PROPERTY\_ENUM request. This ensures that the specified port will not be deleted until after the OID request is completed. + + After the OID request is completed, the extension must call [*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142). The extension must call this function regardless of whether the OID request was completed with NDIS\_STATUS\_SUCCESS. + +The OID\_SWITCH\_PORT\_PROPERTY\_ENUM OID must only be issued when the Hyper-V extensible switch has completed activation. Please see [Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) for more details. + +**Note**  If the extension receives the OID method request of OID\_SWITCH\_PORT\_PROPERTY\_ENUM, it must not complete the OID request. Instead, it must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request down the extensible switch driver stack. + +  + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_PORT\_PROPERTY\_ENUM and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598233) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598236) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_PROPERTY_ENUM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-property-update.md b/windows-driver-docs-pr/network/oid-switch-port-property-update.md new file mode 100644 index 0000000000..28a43ee608 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-property-update.md @@ -0,0 +1,143 @@ +--- +title: OID\_SWITCH\_PORT\_PROPERTY\_UPDATE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE to notify extensible switch extensions about the update of a property for an extensible switch port policy. +ms.assetid: 674CA5EB-BF11-47E8-A2AC-6C789CA4FDB5 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_PROPERTY_UPDATE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_PROPERTY\_UPDATE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE to notify extensible switch extensions about the update of a property for an extensible switch port policy. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure that specifies the identification and type of a port property. + +- A property buffer that contains the parameters for a port policy. The property buffer contains a structure that is based on the **PropertyType** member of the [**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure. For example, if the **PropertyType** member is set to **NdisSwitchPortPropertyTypeVlan**, the property buffer contains an [**NDIS\_SWITCH\_PORT\_PROPERTY\_VLAN**](https://msdn.microsoft.com/library/windows/hardware/hh598243) structure. + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +The extension can veto the update of the port property by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot allocate resources to enforce its updated policies on the port, it should veto the update request. + +**Note**  If the extension returns other NDIS\_STATUS\_*Xxx* error status codes, the update notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + +  + +If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE, see [Managing Port Policies](https://msdn.microsoft.com/library/windows/hardware/hh598202). + +### Return Status Codes + +If the forwarding extension completes the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to process the [NDIS_SWITCH_PORT_PROPERTY_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598238) structure and the data in the structure's property buffer. The extension sets the DATA.SET_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_DATA_NOT_ACCEPTED

The forwarding extension has vetoed the port policy deletion notification.

NDIS_STATUS_NOT_SUPPORTED

The forwarding extension does not support the port policy.

NDIS_STATUS_Xxx

The OID request failed for other reasons.

+ +  + +If the extension does not complete the OID set request of OID\_SWITCH\_PORT\_PROPERTY\_UPDATE, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598230) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598238) + +[**NDIS\_SWITCH\_PORT\_PROPERTY\_VLAN**](https://msdn.microsoft.com/library/windows/hardware/hh598243) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_PROPERTY_UPDATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-teardown.md b/windows-driver-docs-pr/network/oid-switch-port-teardown.md new file mode 100644 index 0000000000..c1a8e4a015 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-teardown.md @@ -0,0 +1,140 @@ +--- +title: OID\_SWITCH\_PORT\_TEARDOWN +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_TEARDOWN to notify underlying extensible switch extensions that an extensible switch port will begin the deletion process. +ms.assetid: 94FA23AC-2064-40C8-B99C-D8D3DC10BFF9 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_TEARDOWN Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_TEARDOWN + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_TEARDOWN to notify underlying extensible switch extensions that an extensible switch port will begin the deletion process. This process is started when the protocol driver issues an OID set request of [OID\_SWITCH\_PORT\_DELETE](oid-switch-port-delete.md). + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure specifies the extensible switch port for which the connect notification is being made. The extensible switch extension must update any cached information about the port that it obtained in the following ways: + +- By issuing OID query requests of [OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md). The extension issues this OID on [*FilterAttach*](https://msdn.microsoft.com/library/windows/hardware/ff549905) only when [OID\_SWITCH\_PARAMETERS](oid-switch-parameters.md) returns an [**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) structure with **IsActive** set to TRUE. If **IsActive** is FALSE, the extension issues the OID when the **NetEventSwitchActivate** [**NET\_PNP\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff568751) is issued by the extension miniport. + +- By inspecting the various OID sets requests of [OID\_SWITCH\_PORT\_CREATE](oid-switch-port-create.md) and [OID\_SWITCH\_PORT\_DELETE](oid-switch-port-delete.md). + +The protocol edge of the extensible switch issues an OID set request of OID\_SWITCH\_PORT\_TEARDOWN to notify the extension that a port is in the process of being deleted from the extensible switch. Before this OID request is issued, the protocol edge of the extensible switch had previously issued the following OIDs if the port had an active network adapter connection: + +- [OID\_SWITCH\_NIC\_DISCONNECT](oid-switch-nic-disconnect.md), which notified underlying extensions that the network adapter is no longer connected to the port that is specified in the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure. + +- [OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md), which notified underlying extensions that the network connection between the network adapter and extensible switch port has been deleted. + + The protocol edge issues this OID set request after all pending packets for the specified extensible switch port have been canceled or completed. + +After the extension completes this OID set request and the reference counter for the extensible switch port is zero, the protocol edge of the extensible switch issues an OID set request of [OID\_SWITCH\_PORT\_DELETE](oid-switch-port-delete.md). This OID request deletes the port from the extensible switch. + +**Note**  An extension increments the reference counter for an extensible switch port by calling [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295). An extension decrements the reference counter by calling [*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142). + +  + +The extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_PORT\_TEARDOWN: + +- The extension must always forward this OID set request to underlying extensions. The extension must not fail the request. + + **Note**  The extension must not modify the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure that is associated with the OID request. + +   + +- After the extension forwards this OID request, it cannot forward packets to the deleted port. The extension also cannot issue OID requests nor call the [*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) function for the deleted port. + +**Note**  The extension must not issue OID set requests of OID\_SWITCH\_PORT\_TEARDOWN. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID set request of OID\_SWITCH\_PORT\_TEARDOWN and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598142) + +[*FilterAttach*](https://msdn.microsoft.com/library/windows/hardware/ff549905) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598220) + +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[**NET\_PNP\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/ff568751) + +[OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) + +[OID\_SWITCH\_PARAMETERS](oid-switch-parameters.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchPort*](https://msdn.microsoft.com/library/windows/hardware/hh598295) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_TEARDOWN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-port-updated.md b/windows-driver-docs-pr/network/oid-switch-port-updated.md new file mode 100644 index 0000000000..4a154346b8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-port-updated.md @@ -0,0 +1,110 @@ +--- +title: OID\_SWITCH\_PORT\_UPDATED +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_UPDATED to notify extensible switch extensions about the update of an extensible switch port. +ms.assetid: 7FDC963A-92E4-49B2-AB77-FA9C92EEBC25 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PORT_UPDATED Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PORT\_UPDATED + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PORT\_UPDATED to notify extensible switch extensions about the update of an extensible switch port. The OID will only be issued for ports that have already been created, and have not yet begun the teardown/delete process. Currently, only the **PortFriendlyName** field is subject to update after creation. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to an [**NDIS\_SWITCH\_NIC\_SAVE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh598216) structure. + +Remarks +------- + +The **PortId** member of the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure specifies the extensible switch port for which the update notification is being made. + +The extension must follow these guidelines for handling OID set requests of OID\_SWITCH\_PORT\_UPDATED: + +- The extension must not modify the [**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) structure that is associated with the OID request. + +- The extension must always forward this OID set request to underlying extensions. The extension must not fail the request. + +**Note**  Extensible switch extensions must not issue OID set requests of OID\_SWITCH\_PORT\_UPDATED. + +  + +For more information about the states of extensible switch ports and network adapter connections, see [Hyper-V Extensible Switch Port and Network Adapter States](https://msdn.microsoft.com/library/windows/hardware/hh598182). + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID set request of OID\_SWITCH\_PORT\_UPDATED and returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[*DereferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598141) + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598229) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +[OID\_SWITCH\_NIC\_DELETE](oid-switch-nic-delete.md) + +[OID\_SWITCH\_PORT\_ARRAY](oid-switch-port-array.md) + +[*ReferenceSwitchNic*](https://msdn.microsoft.com/library/windows/hardware/hh598294) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PORT_UPDATED%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-property-add.md b/windows-driver-docs-pr/network/oid-switch-property-add.md new file mode 100644 index 0000000000..0e4f793f9b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-property-add.md @@ -0,0 +1,137 @@ +--- +title: OID\_SWITCH\_PROPERTY\_ADD +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_ADD to notify extensible switch extensions about the addition of a switch policy property. +ms.assetid: 63A6D2BE-81F4-4D27-B5DF-68466EFF306E +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PROPERTY_ADD Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PROPERTY\_ADD + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_ADD to notify extensible switch extensions about the addition of a switch policy property + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure that specifies the identification and type of an extensible switch policy. + +- A property buffer that contains the parameters for an extensible switch policy. The property buffer contains a structure that is based on the **PropertyType** member of the [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure. + + **Note**  Starting with Windows Server 2012, the **PropertyType** member must be set to **NdisSwitchPropertyTypeCustom** and the property buffer must contain an [**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) structure. + +   + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PROPERTY\_ADD. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +The extension can veto the addition of the switch property by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot allocate resources to enforce its updated policies on the switch, it should veto the addition request. + +**Note**  If the extension returns other NDIS\_STATUS\_*Xxx* error status codes, the creation notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + +  + +If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PROPERTY\_ADD, see [Managing Switch Policies](https://msdn.microsoft.com/library/windows/hardware/hh598203). + +### Return Status Codes + +If the forwarding extension completes the OID set request of OID\_SWITCH\_PROPERTY\_ADD, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_DATA_NOT_ACCEPTED

The extension has vetoed the switch policy addition notification.

NDIS_STATUS_FAILURE

The OID request failed for other reasons.

+ +  + +If the extension does not complete the OID set request of OID\_SWITCH\_PROPERTY\_ADD, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) + +[**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PROPERTY_ADD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-property-delete.md b/windows-driver-docs-pr/network/oid-switch-property-delete.md new file mode 100644 index 0000000000..72555e552f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-property-delete.md @@ -0,0 +1,125 @@ +--- +title: OID\_SWITCH\_PROPERTY\_DELETE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_DELETE to notify extensible switch extensions about the deletion of a switch policy property. +ms.assetid: 55291392-C018-4578-9767-DC5621F75D44 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PROPERTY_DELETE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PROPERTY\_DELETE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_DELETE to notify extensible switch extensions about the deletion of a switch policy property. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer that contains an [**NDIS\_SWITCH\_PROPERTY\_DELETE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598249) structure. + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PROPERTY\_DELETE. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PROPERTY\_DELETE, see [Managing Switch Policies](https://msdn.microsoft.com/library/windows/hardware/hh598203). + +### Return Status Codes + +If the forwarding extension completes the OID set request of OID\_SWITCH\_PROPERTY\_DELETE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_NOT_SUPPORTED

The forwarding extension does not support the switch policy.

NDIS_STATUS_Xxx

The OID request failed for other reasons.

+ +  + +If the forwarding extension does not complete the OID set request of OID\_SWITCH\_PROPERTY\_DELETE, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) + +[**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PROPERTY_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-property-enum.md b/windows-driver-docs-pr/network/oid-switch-property-enum.md new file mode 100644 index 0000000000..49ebea0e86 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-property-enum.md @@ -0,0 +1,114 @@ +--- +title: OID\_SWITCH\_PROPERTY\_ENUM +author: windows-driver-content +description: The Hyper-V extensible switch extension issues an object identifier (OID) method request of OID\_SWITCH\_PROPERTY\_ENUM to obtain an array. +ms.assetid: 45277355-4486-4CE0-ACBF-68D6BC6B79E7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PROPERTY_ENUM Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PROPERTY\_ENUM + + +The Hyper-V extensible switch extension issues an object identifier (OID) method request of OID\_SWITCH\_PROPERTY\_ENUM to obtain an array. This array contains the provisioned switch policies that match the specified criteria. Each element in the array specifies the properties of an extensible switch policy. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure that specifies the parameters for the extensible switch policy enumeration. + +- An array of [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) structures. Each of these structures contains information about an extensible switch policy. + + **Note**  If the extension has not been provisioned with instances of the specified extensible switch policy, the extension sets the **NumProperties** member of the [**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure to zero and no [**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) structures are returned. + +   + +Remarks +------- + +The OID\_SWITCH\_PROPERTY\_ENUM OID must only be issued when the Hyper-V extensible switch has completed activation. Please see [Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) for more details. + +Unlike OID query requests of [OID\_SWITCH\_PORT\_PROPERTY\_ENUM](oid-switch-port-property-enum.md), the extension does not have to call any *ReferenceSwitchXxx* or *DereferenceSwitchXxx* functions when it issues the OID\_SWITCH\_PROPERTY\_ENUM request down the extensible switch driver stack. + +**Note**  If the extension receives the OID method request of OID\_SWITCH\_PROPERTY\_ENUM, it must not complete the OID request. Instead, it must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request down the extensible switch driver stack. + +  + +### Return Status Codes + +The underlying miniport edge of the extensible switch completes the OID query request of OID\_SWITCH\_PROPERTY\_ENUM and returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

NDIS_STATUS_INVALID_LENGTH

The length of the information buffer is too small to return the [NDIS_SWITCH_PROPERTY_ENUM_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh598253) structure and its array of [NDIS_SWITCH_PROPERTY_ENUM_INFO](https://msdn.microsoft.com/library/windows/hardware/hh598250) elements. The underlying miniport edge of the extensible switch sets the DATA.METHOD_INFORMATION.BytesNeeded member in the [NDIS_OID_REQUEST](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure to the minimum buffer size that is required.

NDIS_STATUS_FAILURE

The request failed for other reasons.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh598250) + +[**NDIS\_SWITCH\_PROPERTY\_ENUM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598253) + +[Querying the Hyper-V Extensible Switch Configuration](https://msdn.microsoft.com/library/windows/hardware/hh598293) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PROPERTY_ENUM%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-switch-property-update.md b/windows-driver-docs-pr/network/oid-switch-property-update.md new file mode 100644 index 0000000000..a77e83d096 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-switch-property-update.md @@ -0,0 +1,137 @@ +--- +title: OID\_SWITCH\_PROPERTY\_UPDATE +author: windows-driver-content +description: The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_UPDATE to notify extensible switch extensions about the update to parameters for an extensible switch policy property. +ms.assetid: AEC32AD8-B353-4D58-9111-D70C2FFA9F66 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_SWITCH_PROPERTY_UPDATE Network Drivers Starting with Windows Vista +--- + +# OID\_SWITCH\_PROPERTY\_UPDATE + + +The protocol edge of the Hyper-V extensible switch issues an object identifier (OID) set request of OID\_SWITCH\_PROPERTY\_UPDATE to notify extensible switch extensions about the update to parameters for an extensible switch policy property. + +The **InformationBuffer** member of the [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains a pointer to a buffer. This buffer contains the following data: + +- An [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure that specifies the identification and type of an extensible switch policy. + +- A property buffer that contains the parameters for an extensible switch policy. The property buffer contains a structure that is based on the **PropertyType** member of the [**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) structure. + + **Note**  Starting with Windows Server 2012, the **PropertyType** member must be set to **NdisSwitchPropertyTypeCustom** and the property buffer must contain an [**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) structure. + +   + +Remarks +------- + +A forwarding extension can handle the OID set request of OID\_SWITCH\_PROPERTY\_UPDATE. All other types of extensions must call [**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) to forward the OID request to the next extension in the extensible switch driver stack. + +The extension can veto the update of the switch property by returning NDIS\_STATUS\_DATA\_NOT\_ACCEPTED for the OID request. For example, if an extension cannot allocate resources to enforce its updated policies on the switch, it should veto the update request. + +**Note**  If the extension returns other NDIS\_STATUS\_*Xxx* error status codes, the creation notification is also vetoed. However, returning status codes for transitory scenarios, such as returning NDIS\_STATUS\_RESOURCES, could result in a retry of the creation notification. + +  + +If the extension does not veto the OID request, it should monitor the status when the request is completed. The extension should do this to determine whether the OID request was vetoed by underlying extensions in the extensible switch control path or by the extensible switch interface. + +For guidelines on how to handle an OID set request of OID\_SWITCH\_PROPERTY\_UPDATE, see [Managing Switch Policies](https://msdn.microsoft.com/library/windows/hardware/hh598203). + +### Return Status Codes + +If the extension completes the OID set request of OID\_SWITCH\_PROPERTY\_UPDATE, it returns one of the following status codes. + + ++++ + + + + + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_DATA_NOT_ACCEPTED

The extension has vetoed the switch policy update notification.

NDIS_STATUS_FAILURE

The OID request failed for other reasons.

+ +  + +If the extension does not complete the OID set request of OID\_SWITCH\_PROPERTY\_UPDATE, the request is completed by the underlying miniport edge of the extensible switch. The miniport edge returns the following status code. + + ++++ + + + + + + + + + + + + +
Status CodeDescription

NDIS_STATUS_SUCCESS

The OID request completed successfully.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +**** +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_SWITCH\_PROPERTY\_CUSTOM**](https://msdn.microsoft.com/library/windows/hardware/hh598247) + +[**NDIS\_SWITCH\_PROPERTY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh598255) + +[**NdisFOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff561830) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_SWITCH_PROPERTY_UPDATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-tcp-rsc-statistics.md b/windows-driver-docs-pr/network/oid-tcp-rsc-statistics.md new file mode 100644 index 0000000000..6e44b5da38 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-tcp-rsc-statistics.md @@ -0,0 +1,69 @@ +--- +title: OID\_TCP\_RSC\_STATISTICS +author: windows-driver-content +description: As a query, NDIS and overlying drivers or user-mode applications use the OID\_TCP\_RSC\_STATISTICS OID to get the receive-segment coalescing (RSC) statistics of a miniport adapter. +ms.assetid: CD289868-1925-4222-8A4D-359118124325 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_TCP_RSC_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_TCP\_RSC\_STATISTICS + + +As a query, NDIS and overlying drivers or user-mode applications use the OID\_TCP\_RSC\_STATISTICS OID to get the receive-segment coalescing (RSC) statistics of a miniport adapter. + +NDIS 6.30 and later miniport drivers that provide RSC services must support this OID. Otherwise, this OID is optional. + +Remarks +------- + +The **InformationBuffer** member of [**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) structure contains an [**NDIS\_RSC\_STATISTICS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451657) structure. + +The miniport driver must maintain the statistics in the members of the [**NDIS\_RSC\_STATISTICS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451657) structure as follows: + +- The driver must increment the coalesced packet count in the **CoalescedPkts** member by one every time a packet is added to a single coalesced unit (SCU). +- The driver must increment the coalesced octet count in the **CoalescedOctets** member by the size of the TCP payload of the packet every time a packet is added to a SCU. +- The driver must increment the coalesced events count **CoalesceEvents** member by one every time a SCU is finalized. All such SCUs should have a non-zero **CoalescedSegCount** value. +- The driver must increment the abort count in the **Aborts** member by one every time it encounters an exception other than the IP datagram length being exceeded. This count should include the cases where a packet is not coalesced because of hardware resources. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.30 and later drivers in Windows 8.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_OID\_REQUEST**](https://msdn.microsoft.com/library/windows/hardware/ff566710) + +[**NDIS\_RSC\_STATISTICS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/hh451657) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_TCP_RSC_STATISTICS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa-ex.md b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa-ex.md new file mode 100644 index 0000000000..6b14fb6653 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa-ex.md @@ -0,0 +1,82 @@ +--- +title: OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX +author: windows-driver-content +description: As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX OID to request that a miniport driver add the specified security associations (SAs) to a NIC. +ms.assetid: 9D356CFA-3353-4E62-9B1C-0FF650DCE75C +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA_EX Network Drivers Starting with Windows Vista +--- + +# OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX + + +\[The IPsec Task Offload feature is deprecated and should not be used.\] + +As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX OID to request that a miniport driver add the specified security associations (SAs) to a NIC. + +**Note**  NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +Remarks +------- + +All NDIS 6.30 miniport drivers that support IPsec offload version 2 (IPsecOV2) must support this OID. + +After TCP/IP transport determines that a NIC can perform IPsecOV2 operations, the TCP/IP transport requests the miniport driver to add SAs. The transport cannot offload IPsecOV2 operations to the NIC before the transport adds an SA. + +The miniport driver configures the NIC for IPsecOV2 processing on the SAs. With a successful set to OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX, the miniport driver supplies the handle that identifies the offloaded SA in the **OffloadHandle** member of the [**IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh463943) structure. (For example, the transport uses the handle in the send path to indicate which offloaded SA to use). If an SA was offloaded, the set request is successful. + +The miniport driver can return a failure status for the OID request, for example, when the NIC runs out of capacity to offload more SAs. Also, the miniport driver might return a failure status because it needs to avoid a race condition. In this case, the NIC configuration changes and excludes a particular algorithm. + +If the request fails, SAs were not offloaded. If failure occurs for an SA, the miniport driver should set the **OffloadHandle** member in the corresponding IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX structure to **NULL**. + +The miniport driver reports the maximum number of SAs that a NIC can support in the **SaOffloadCapacity** member of the [**NDIS\_IPSEC\_OFFLOAD\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff565808) structure during initialization. If necessary, the TCP/IP transport can set the [OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) OID to request that the miniport driver delete an SA from the NIC. + +This OID is essentially identical to the previous version, [OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA](oid-tcp-task-ipsec-offload-v2-add-sa.md). The only difference is the updated [**IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh463943) structure. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.30 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh463943) + +[**NDIS\_IPSEC\_OFFLOAD\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff565808) + +[OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA](oid-tcp-task-ipsec-offload-v2-add-sa.md) + +[OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa.md b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa.md new file mode 100644 index 0000000000..f430e0d99f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-add-sa.md @@ -0,0 +1,84 @@ +--- +title: OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA +author: windows-driver-content +description: As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA OID to request that a miniport driver add the specified security associations (SAs) to a NIC. +ms.assetid: bd1d0cf2-234d-4c06-904e-fe2de6022981 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA Network Drivers Starting with Windows Vista +--- + +# OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA + + +\[The IPsec Task Offload feature is deprecated and should not be used.\] + +As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA OID to request that a miniport driver add the specified security associations (SAs) to a NIC. + +**Note**  NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +**Note**  This OID is supported in NDIS 6.1 and 6.20. For NDIS 6.30 and later drivers see [OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX](oid-tcp-task-ipsec-offload-v2-add-sa-ex.md). + +  + +Remarks +------- + +All NDIS 6.1 and 6.20 miniport drivers that support IPsec offload version 2 (IPsecOV2) must support this OID. + +After TCP/IP transport determines that a NIC can perform IPsecOV2 operations, the TCP/IP transport requests the miniport driver to add SAs. The transport cannot offload IPsecOV2 operations to the NIC before the transport adds an SA. + +The miniport driver receives an [**IPSEC\_OFFLOAD\_V2\_ADD\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556977) structure that contains a pointer to the next IPSEC\_OFFLOAD\_V2\_ADD\_SA structure in a linked list. The miniport driver configures the NIC for IPsecOV2 processing on the SAs. With a successful set to OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA, the miniport driver supplies the handles that identify the offloaded SAs in the **OffloadHandle** member of IPSEC\_OFFLOAD\_V2\_ADD\_SA. (For example, the transport uses the handle in the send path to indicate which offloaded SA to use). If any of the SAs in the linked list were offloaded, the set request is successful. + +The miniport driver can return a failure status for the OID request, for example, when the NIC runs out of capacity to offload more SAs. Also, the miniport driver might return a failure status because it needs to avoid a race condition. In this case, the NIC configuration changes and excludes a particular algorithm. + +If the request fails, none of the SAs in the linked list were offloaded. If failure occurs for a particular SA in the linked list, the miniport driver should set the **OffloadHandle** member in the corresponding IPSEC\_OFFLOAD\_V2\_ADD\_SA structure to **NULL**. + +The miniport driver reports the maximum number of SAs that a NIC can support in the **SaOffloadCapacity** member of the [**NDIS\_IPSEC\_OFFLOAD\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff565808) structure during initialization. If necessary, the TCP/IP transport can set the [OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) OID to request that the miniport driver delete an SA from the NIC. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and 6.20. For NDIS 6.30 and later, use [OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA_EX](oid-tcp-task-ipsec-offload-v2-add-sa-ex.md).

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**IPSEC\_OFFLOAD\_V2\_ADD\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556977) + +[**NDIS\_IPSEC\_OFFLOAD\_V2**](https://msdn.microsoft.com/library/windows/hardware/ff565808) + +[OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_ADD\_SA\_EX](oid-tcp-task-ipsec-offload-v2-add-sa-ex.md) + +[OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA](oid-tcp-task-ipsec-offload-v2-delete-sa.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_TCP_TASK_IPSEC_OFFLOAD_V2_ADD_SA%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-delete-sa.md b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-delete-sa.md new file mode 100644 index 0000000000..0929bf0b75 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-delete-sa.md @@ -0,0 +1,111 @@ +--- +title: OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA +author: windows-driver-content +description: As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA OID to request that a miniport driver delete the specified security associations (SAs) from a NIC. +ms.assetid: 9b2c702c-beaa-4caf-97c5-d80a2632e4d3 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_TCP_TASK_IPSEC_OFFLOAD_V2_DELETE_SA Network Drivers Starting with Windows Vista +--- + +# OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA + + +\[The IPsec Task Offload feature is deprecated and should not be used.\] + +As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA OID to request that a miniport driver delete the specified security associations (SAs) from a NIC. + +**Note**  NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +Remarks +------- + +All NDIS 6.1 miniport drivers that support IPsec offload version 2 (IPsecOV2) must support this OID. + +When a miniport driver receives this request, the driver should delete the specified SAs from the NIC and free any system resources that were allocated for the SAs. + +The miniport driver receives an [**IPSEC\_OFFLOAD\_V2\_DELETE\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556979) structure that contains a handle to an SA bundle and a pointer to the next **IPSEC\_OFFLOAD\_V2\_DELETE\_SA** structure in a linked list. + +The miniport driver can set **SaDeleteReq** in the [**NDIS\_IPSEC\_OFFLOAD\_V2\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff565818) structure for a receive [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure. The TCP/IP transport subsequently issues OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA once to delete the inbound SA that the packet was received over and once again to delete the outbound SA that corresponds to the deleted inbound SA. The NIC must not remove either of these SAs before receiving the corresponding OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_DELETE\_SA request. + +### Return status codes + +The miniport driver's [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function returns one of the following values for this request: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the [NdisMOidRequestComplete](https://msdn.microsoft.com/library/windows/hardware/ff563622) function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the [MiniportResetEx](https://msdn.microsoft.com/library/windows/hardware/ff559432) function.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**IPSEC\_OFFLOAD\_V2\_DELETE\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556979) + +[**NDIS\_IPSEC\_OFFLOAD\_V2\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff565818) + +[**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_TCP_TASK_IPSEC_OFFLOAD_V2_DELETE_SA%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-update-sa.md b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-update-sa.md new file mode 100644 index 0000000000..3194dbe9e1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-tcp-task-ipsec-offload-v2-update-sa.md @@ -0,0 +1,68 @@ +--- +title: OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_UPDATE\_SA +author: windows-driver-content +description: As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_UPDATE\_SA OID to request that a miniport driver update the specified security associations (SAs) on a NIC. +ms.assetid: 22849103-9148-4621-b78f-b9f34f2c7ac1 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_TCP_TASK_IPSEC_OFFLOAD_V2_UPDATE_SA Network Drivers Starting with Windows Vista +--- + +# OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_UPDATE\_SA + + +\[The IPsec Task Offload feature is deprecated and should not be used.\] + +As a set, the TCP/IP transport uses the OID\_TCP\_TASK\_IPSEC\_OFFLOAD\_V2\_UPDATE\_SA OID to request that a miniport driver update the specified security associations (SAs) on a NIC. + +**Note**  NDIS supports this OID with the direct OID request interface. For more information about the direct OID request interface, see [NDIS 6.1 Direct OID Request Interface](https://msdn.microsoft.com/library/windows/hardware/ff564736). + +  + +Remarks +------- + +All NDIS 6.1 miniport drivers that support IPsec offload version 2 (IPsecOV2) must support this OID. + +When a miniport driver receives this request, the driver should update the specified SAs on the NIC. The miniport driver can fail this request if the SA is not found or the ESN is not supported. In this case, the returned status should be NDIS\_STATUS\_INVALID\_PARAMETER. + +The miniport driver receives an [**IPSEC\_OFFLOAD\_V2\_UPDATE\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556990) structure that contains information about the update and a pointer to the next IPSEC\_OFFLOAD\_V2\_UPDATE\_SA structure in a linked list. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported in NDIS 6.1 and later.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**IPSEC\_OFFLOAD\_V2\_UPDATE\_SA**](https://msdn.microsoft.com/library/windows/hardware/ff556990) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_TCP_TASK_IPSEC_OFFLOAD_V2_UPDATE_SA%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-get-comp-info.md b/windows-driver-docs-pr/network/oid-wan-co-get-comp-info.md new file mode 100644 index 0000000000..a700272f46 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-get-comp-info.md @@ -0,0 +1,81 @@ +--- +title: OID\_WAN\_CO\_GET\_COMP\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_GET\_COMP\_INFO OID requests the miniport driver to return information about the capabilities of the NIC or of its driver, in particular whether either supports compression. +ms.assetid: a2525548-ca5a-47a8-ab19-e0469913f6be +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_GET_COMP_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_GET\_COMP\_INFO + + +The OID\_WAN\_CO\_GET\_COMP\_INFO OID requests the miniport driver to return information about the capabilities of the NIC or of its driver, in particular whether either supports compression. If so, the values returned are used to negotiate compression with the Point-to-Point Protocol (PPP) Compression Control Protocol. The protocol subsequently negotiates a PPP compression scheme with an [OID\_WAN\_CO\_SET\_COMP\_INFO](oid-wan-co-set-comp-info.md) request. This compression information is specific to a virtual connection (VC). + +Compression information is returned in an NDIS\_WAN\_CO\_GET\_COMP\_INFO structure, defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_GET_COMP_INFO { + OUT NDIS_WAN_COMPRESS_INFO SendCapabilities; + OUT NDIS_WAN_COMPRESS_INFO RecvCapabilities; + } NDIS_WAN_CO_GET_COMP_INFO, *PNDIS_WAN_CO_GET_COMP_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**SendCapabilities** +Specifies a structure containing information about compression capabilities for sending data. + +**RecvCapabilities** +Specifies a structure containing information about compression capabilities for receiving data. + +Remarks +------- + +For specifics of the NDIS\_WAN\_COMPRESS\_INFO structure, see [OID\_WAN\_GET\_COMP\_INFO](https://msdn.microsoft.com/library/windows/hardware/ff561202). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WAN\_GET\_COMP\_INFO](https://msdn.microsoft.com/library/windows/hardware/ff561202) + +[OID\_WAN\_CO\_SET\_COMP\_INFO](oid-wan-co-set-comp-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_GET_COMP_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-get-info.md b/windows-driver-docs-pr/network/oid-wan-co-get-info.md new file mode 100644 index 0000000000..129d036411 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-get-info.md @@ -0,0 +1,169 @@ +--- +title: OID\_WAN\_CO\_GET\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_GET\_INFO OID requests the miniport driver to return information that applies to all virtual connections (VCs) on its NIC. This information is returned in an NDIS\_WAN\_CO\_INFO structure, defined as follows. +ms.assetid: c97130a5-68e1-4c69-a5a5-9781ea59af0c +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_GET_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_GET\_INFO + + +The OID\_WAN\_CO\_GET\_INFO OID requests the miniport driver to return information that applies to all virtual connections (VCs) on its NIC. This information is returned in an NDIS\_WAN\_CO\_INFO structure, defined as follows. + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_INFO { + OUT ULONG MaxFrameSize; + OUT ULONG MaxSendWindow; + OUT ULONG FramingBits; + OUT ULONG DesiredACCM; + } NDIS_WAN_CO_INFO, *PNDIS_WAN_CO_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**MaxFrameSize** +Specifies the maximum frame size for any net packet that the miniport driver can send and receive. This value should exclude the miniport driver's own framing overhead and/or the PPP HDLC overhead. Typically this value is around 1500. + +However, all CoNDIS WAN miniport drivers should use an internal **MaxFrameSize** that is 32 bytes larger than the value they return for this OID. For example, a CoNDIS WAN miniport driver that returns 1500 for this OID should internally accept and send up to 1532. Such a miniport driver can readily support future bridging and additional protocols. + +**MaxSendWindow** +Specifies the maximum number of outstanding packets that the CoNDIS WAN miniport driver can handle on a VC. This member must be set to at least one. + +The NDISWAN driver uses the value of this member as a limit on how many packets it submits in send requests to the miniport driver's *MiniportCoSendPackets* function before NDISWAN holds send packets. These packets are queued until the miniport driver completes an outstanding send. A miniport driver can adjust this value dynamically and on a per-VC basis using the **SendWindow** member in the [**WAN\_CO\_LINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565819) structure that the miniport driver passes to [**NdisMCoIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553458). NDISWAN uses the current **SendWindow** value as its limit on outstanding sends. If the miniport driver sets **SendWindow** to zero, NDISWAN must stop sending packets for the particular VC. That is, the miniport driver specifies that the send window is shut down, which, in effect, specifies that it cannot accept any packets from NDISWAN. + +Because a CoNDIS WAN miniport driver must queue packets internally, the value of **MaxSendWindow** is theoretically **max**( ULONG). However, this driver-determined value should reflect the link speed or hardware capabilities of the NIC. For example, if a miniport driver's NIC always has room for at least four packets, the miniport driver sets **MaxSendWindow** to four so that any incoming packet to *MiniportCoSendPackets* can be placed on the hardware immediately. + +**FramingBits** +A 32-bit value that specifies a bitmask specifying the types of framing the miniport driver supports. The miniport driver can specify a combination of the following values, using the binary OR operator: + +RAS\_FRAMING +Set only if the miniport driver can detect older RAS framing. Only legacy drivers that supported earlier RAS framing set this flag. + +RAS\_COMPRESSION +Set only if the miniport driver supports the older RAS compression scheme. + +PPP\_FRAMING +Should always be set. Indicates the miniport driver can detect and support PPP framing for its medium type. + +PPP\_COMPRESS\_ADDRESS\_CONTROL +Set if the miniport driver supports PPP address and control-field compression. + +NDISWAN will remove the address and control field if this LCP option is negotiated. Some WAN medium types, such as X.25, do not support this option. + +PPP\_COMPRESS\_PROTOCOL\_FIELD +Set if the miniport driver supports PPP protocol field compression. + +NDISWAN will remove one byte from the protocol field when applicable if this LCP option is negotiated. + +PPP\_ACCM\_SUPPORTED +Set if the miniport driver supports Asynchronous Control Character Mapping. This bit is only valid for asynchronous media, such as modems. If this bit is set the **DesiredACCM** member should be valid. + +PPP\_MULTILINK\_FRAMING +Set if the miniport driver supports multiple-link framing as specified in IETF RFC 1717. + +PPP\_SHORT\_SEQUENCE\_HDR\_FORMAT +Set if the miniport driver supports header format for multiple-link framing as specified in IETF RFC 1717. + +SLIP\_FRAMING +Set if the miniport driver can detect and support SLIP framing (asynchronous miniport drivers only). + +SLIP\_VJ\_COMPRESSION +Set if the miniport driver can support Van Jacobsen TCP/IP header compression for SLIP. NDISWAN supports SLIP\_VJ\_COMPRESSION (with 16 slots). Asynchronous media (serial miniport drivers) that support SLIP framing should set this bit. + +Asynchronous media need not write any code to support VJ header compression. NDISWAN will take care of it. + +SLIP\_VJ\_AUTODETECT +Set if the miniport driver can auto-detect Van Jacobsen TCP/IP header compression for SLIP. NDISWAN will auto-detect VJ header compression. Asynchronous media (serial miniport drivers) should set this bit if they support SLIP framing. + +TAPI\_PROVIDER +Set if the miniport driver supports the TAPI Service Provider OIDs. Unless this bit is set, TAPI OID calls will not be made to the miniport driver. + +MEDIA\_NRZ\_ENCODING +Set if the miniport driver supports NRZ encoding, the PPP default for some media types such as ISDN. This value is reserved for future use. + +MEDIA\_NRZI\_ENCODING +Set if the miniport driver supports NRZI encoding. This value is reserved for future use. + +MEDIA\_NLPID +Set if the miniport driver has and can set the NLPID in its frame. This value is reserved for future use. + +RFC\_1356\_FRAMING +Set if the miniport driver supports IETF RFC 1356 X.25 and ISDN framing. This value is reserved for future use. + +RFC\_1483\_FRAMING +Set if the miniport driver supports IETF RFC 1483 ATM adaptation layer-5 encapsulation. This value is reserved for future use. + +RFC\_1490\_FRAMING +Set if the miniport driver supports IETF RFC 1490 Frame Relay framing. This value is reserved for future use. + +NBF\_PRESERVE\_MAC\_ADDRESS +Set if the miniport driver supports IETF framing as specified in the draft "The PPP NETBIOS Frames Control Protocol (NBFCP)." + +SHIVA\_FRAMING +Superseded by NBF\_PRESERVE\_MAC\_ADDRESS. + +PASS\_THROUGH\_MODE +Set if the miniport driver does its own framing. If this flag is set, NDISWAN passes frames, uninterpreted and unmodified. + +Miniport drivers must be in the default PPP framing mode until each miniport driver receives an [OID\_WAN\_CO\_SET\_LINK\_INFO](oid-wan-co-set-link-info.md) request. The miniport driver must auto-detect any framing that it claims to support. + +For example, miniport drivers that support old RAS framing must auto-detect RAS framing from PPP framing. If a miniport driver detects a framing scheme other than the default, that miniport driver should automatically switch its framing into the newly detected framing. + +A subsequent query with [OID\_WAN\_CO\_GET\_LINK\_INFO](oid-wan-co-get-link-info.md) should indicate the detected framing. If no framing is yet detected, the **FramingBits** should be zero in the returned NDIS\_WAN\_CO\_GET\_LINK\_INFO information. + +If the WAN miniport driver is called subsequently with OID\_WAN\_CO\_SET\_LINK\_INFO in which the **FramingBits** member is zero, the miniport driver should attempt to auto-detect the framing upon reception of each frame. + +**DesiredACCM** +The Asynchronous Control Character Map is negotiated. This member is relevant only for asynchronous media types. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NdisMCoIndicateStatus**](https://msdn.microsoft.com/library/windows/hardware/ff553458) + +[OID\_WAN\_CO\_GET\_LINK\_INFO](oid-wan-co-get-link-info.md) + +[OID\_WAN\_CO\_SET\_LINK\_INFO](oid-wan-co-set-link-info.md) + +[**WAN\_CO\_LINKPARAMS**](https://msdn.microsoft.com/library/windows/hardware/ff565819) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_GET_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-get-link-info.md b/windows-driver-docs-pr/network/oid-wan-co-get-link-info.md new file mode 100644 index 0000000000..0db11d0dfc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-get-link-info.md @@ -0,0 +1,103 @@ +--- +title: OID\_WAN\_CO\_GET\_LINK\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_GET\_LINK\_INFO OID requests the miniport driver to return PPP framing information about the current state of a virtual connection (VC). This information is returned in an NDIS\_WAN\_CO\_GET\_LINK\_INFO structure, defined as follows. +ms.assetid: 26582bc4-c32f-4243-a208-9230c62f4d16 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_GET_LINK_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_GET\_LINK\_INFO + + +The OID\_WAN\_CO\_GET\_LINK\_INFO OID requests the miniport driver to return PPP framing information about the current state of a virtual connection (VC). This information is returned in an NDIS\_WAN\_CO\_GET\_LINK\_INFO structure, defined as follows. + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_GET_LINK_INFO { + OUT ULONG MaxSendFrameSize; + OUT ULONG MaxRecvFrameSize; + OUT ULONG SendFramingBits; + OUT ULONG RecvFramingBits; + OUT ULONG SendCompressionBits; + OUT ULONG RecvCompressionBits; + OUT ULONG SendACCM; + OUT ULONG RecvACCM; + } NDIS_WAN_CO_GET_LINK_INFO, *PNDIS_WAN_CO_GET_LINK_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**MaxSendFrameSize** +Specifies the maximum buffer size, in bytes, that the miniport driver can accept for transmission on this VC. The miniport driver's *MiniportCoSendPackets* function can reject any incoming send packet that is larger than this size. + +**MaxRecvFrameSize** +Specifies the largest packet that will be received from the network. The miniport driver can drop any packets that are larger. + +**SendFramingBits** +Specifies send-framing bits indicating the type of framing that should be sent. If the miniport driver detects incompatibilities between **SendFramingBits** and **RecvFramingBits**, it returns NDIS\_STATUS\_INVALID\_DATA. + +The proper NLPID and framing format should be used based on the framing bits wherever applicable. + +**RecvFramingBits** +Specifies receive-framing bits indicating the type of framing that should be received. + +**SendCompressionBits** +Reserved. + +**RecvCompressionBits** +Reserved. + +**SendACCM** +For asynchronous media types, logical bits 0-31 indicate the respective byte to be byte stuffed. That is, if bit 0 is set to 1, then ASCII character 0x00 should be byte stuffed, and so forth. + +**RecvACCM** +As described for **SendACCM**. + +Remarks +------- + +Possible values for **SendFramingBits** and **RecvFramingBits** include any the driver returned in response to the OID\_WAN\_CO\_GET\_LINK\_INFO query. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WAN\_CO\_GET\_LINK\_INFO](oid-wan-co-get-link-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_GET_LINK_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-get-stats-info.md b/windows-driver-docs-pr/network/oid-wan-co-get-stats-info.md new file mode 100644 index 0000000000..b8d03ce1a1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-get-stats-info.md @@ -0,0 +1,120 @@ +--- +title: OID\_WAN\_CO\_GET\_STATS\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_GET\_STATS\_INFO OID requests the miniport driver to return statistics information that is specific to a virtual connection (VC). +ms.assetid: 53ab1c04-7bb2-401d-ad54-72f3c1587dc0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_GET_STATS_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_GET\_STATS\_INFO + + +The OID\_WAN\_CO\_GET\_STATS\_INFO OID requests the miniport driver to return statistics information that is specific to a virtual connection (VC). A WAN miniport driver is expected to keep statistics and to return these statistics for this OID in an NDIS\_WAN\_CO\_GET\_STATS\_INFO structure, defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_GET_STATS_INFO { + OUT ULONG BytesSent; + OUT ULONG BytesRcvd; + OUT ULONG FramesSent; + OUT ULONG FramesRcvd; + OUT ULONG CRCErrors; + OUT ULONG TimeoutErrors; + OUT ULONG AlignmentErrors; + OUT ULONG SerialOverrunErrors; + OUT ULONG FramingErrors; + OUT ULONG BufferOverrunErrors; + OUT ULONG BytesTransmittedUncompressed; + OUT ULONG BytesReceivedUncompressed; + OUT ULONG BytesTransmittedCompressed; + OUT ULONG BytesReceivedCompressed; + } NDIS_WAN_CO_GET_STATS_INFO, *PNDIS_WAN_CO_GET_STATS_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**BytesSent** +Specifies the number of bytes transmitted. + +**BytesRcvd** +Specifies the number of bytes received. + +**FramesSent** +Specifies the number of frames (WAN packets) sent. + +**FramesRcvd** +Specifies the number of frames received. + +**CRCErrors** +Specifies the number of CRC errors encountered for this VC. CRC errors are caused by the failure of a cyclic redundancy check. A CRC error indicates that one or more bytes in the frame received were found garbled on arrival. + +**TimeoutErrors** +Specifies the number of time-out errors encountered for this VC. Time-out errors occur when an expected byte is not received in time. + +**AlignmentErrors** +Specifies the number of alignment errors encountered for this VC. Alignment errors occur when a byte received is different from the byte expected. This typically happens when a byte is lost or when a time-out error occurs. + +**SerialOverrunErrors** +Specifies the number of serial overruns encountered for this VC. Serial overruns occur when the WAN NIC cannot handle the rate at which data is received. + +**FramingErrors** +Specifies the number of framing errors encountered for this VC. A framing error occurs when an asynchronous byte is received with an invalid start or stop bit. + +**BufferOverrunErrors** +Specifies the number of buffer overruns encountered for this VC. Buffer overruns occur when the WAN miniport driver cannot handle the rate at which data is received. + +**BytesTransmittedUncompressed** +Specifies the number of bytes of uncompressed data transmitted. A miniport driver returns a nonzero value only if it supports compression. + +**BytesReceivedUncompressed** +Specifies the number of bytes of uncompressed data received. A miniport driver returns a nonzero value only if it supports compression. + +**BytesTransmittedCompressed** +Specifies the number of bytes of compressed data transmitted. A miniport driver returns a nonzero value only if it supports compression. + +**BytesReceivedCompressed** +Specifies the number of bytes of compressed data received. A miniport driver returns a nonzero value only if it supports compression. + +Remarks +------- + +If the underlying driver or its NIC does not support compression, the driver returns zero for the **Bytes..Uncompressed/Compressed** members. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_GET_STATS_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-set-comp-info.md b/windows-driver-docs-pr/network/oid-wan-co-set-comp-info.md new file mode 100644 index 0000000000..707cead34b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-set-comp-info.md @@ -0,0 +1,79 @@ +--- +title: OID\_WAN\_CO\_SET\_COMP\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_SET\_COMP\_INFO OID notifies the miniport driver of the PPP compression scheme selected by a protocol to which the miniport driver already returned information with a OID\_WAN\_CO\_GET\_COMP\_INFO query. +ms.assetid: f3b6b846-fa8c-425b-ba05-45927e744d66 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_SET_COMP_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_SET\_COMP\_INFO + + +The OID\_WAN\_CO\_SET\_COMP\_INFO OID notifies the miniport driver of the PPP compression scheme selected by a protocol to which the miniport driver already returned information with a [OID\_WAN\_CO\_GET\_COMP\_INFO](oid-wan-co-get-comp-info.md) query. This PPP compression scheme is specific to a virtual connection (VC). + +The protocol supplies a specification for the PPP compression scheme it selected in an NDIS\_WAN\_CO\_SET\_COMP\_INFO structure, defined as follows: + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_SET_COMP_INFO { + IN NDIS_WAN_COMPRESS_INFO SendCapabilities; + IN NDIS_WAN_COMPRESS_INFO RecvCapabilities; + } NDIS_WAN_CO_SET_COMP_INFO, *PNDIS_WAN_CO_SET_COMP_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**SendCapabilities** +Specifies a structure containing information about compression capabilities for sending data. + +**RecvCapabilities** +Specifies a structure containing information about compression capabilities for receiving data. + +Remarks +------- + +For specifics of the NDIS\_WAN\_COMPRESS\_INFO structure, see [OID\_WAN\_GET\_COMP\_INFO](https://msdn.microsoft.com/library/windows/hardware/ff561202). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WAN\_CO\_GET\_COMP\_INFO](oid-wan-co-get-comp-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_SET_COMP_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wan-co-set-link-info.md b/windows-driver-docs-pr/network/oid-wan-co-set-link-info.md new file mode 100644 index 0000000000..876232348a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wan-co-set-link-info.md @@ -0,0 +1,107 @@ +--- +title: OID\_WAN\_CO\_SET\_LINK\_INFO +author: windows-driver-content +description: The OID\_WAN\_CO\_SET\_LINK\_INFO OID requests the miniport driver to set PPP framing information for a specific virtual connection (VC). A protocol uses an NDIS\_WAN\_CO\_SET\_LINK\_INFO structure, defined as follows, to indicate this PPP framing information. +ms.assetid: 4487289a-01f6-4ae1-b660-3011d66acb29 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WAN_CO_SET_LINK_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WAN\_CO\_SET\_LINK\_INFO + + +The OID\_WAN\_CO\_SET\_LINK\_INFO OID requests the miniport driver to set PPP framing information for a specific virtual connection (VC). A protocol uses an NDIS\_WAN\_CO\_SET\_LINK\_INFO structure, defined as follows, to indicate this PPP framing information. + +```ManagedCPlusPlus + typedef struct _NDIS_WAN_CO_SET_LINK_INFO { + IN ULONG MaxSendFrameSize; + IN ULONG MaxRecvFrameSize; + IN ULONG SendFramingBits; + IN ULONG RecvFramingBits; + IN ULONG SendCompressionBits; + IN ULONG RecvCompressionBits; + IN ULONG SendACCM; + IN ULONG RecvACCM; + } NDIS_WAN_CO_SET_LINK_INFO, *PNDIS_WAN_CO_SET_LINK_INFO; + +``` + +## + + +The members of this structure contain the following information: + +**MaxSendFrameSize** +Specifies the largest buffer, in bytes, the protocol will send for this VC. This value must be less than or equal to that returned by the miniport driver for the [OID\_WAN\_CO\_GET\_LINK\_INFO](oid-wan-co-get-link-info.md) query. + +The miniport driver's *MiniportCoSendPackets* function can reject any send packets submitted for this link that are larger than this value. + +**MaxRecvFrameSize** +Specifies the largest network packet that the protocol will receive subsequently. This value must be less than or equal to that returned by the miniport driver for the OID\_WAN\_CO\_GET\_LINK\_INFO query. The miniport driver can drop any received packets for this VC that are larger. + +**SendFramingBits** +Specifies send-framing bits indicating the type of framing that should be sent. If the miniport driver detects incompatibilities between **SendFramingBits** and **RecvFramingBits**, it returns NDIS\_STATUS\_INVALID\_DATA. + +The proper NLPID and framing format should be used based on the framing bits wherever applicable. + +**RecvFramingBits** +Specifies receive-framing bits indicating the type of framing that should be received. + +**SendCompressionBits** +Reserved. + +**RecvCompressionBits** +Reserved. + +**SendACCM** +For asynchronous media types, logical bits 0-31 indicate the respective byte to be byte stuffed. That is, if bit 0 is set to one then ASCII character 0x00 should be byte stuffed, and so forth. + +**RecvACCM** +As described for **SendACCM**. + +Remarks +------- + +Possible values for **SendFramingBits** and **RecvFramingBits** include any the underlying driver returned in response to the [OID\_WAN\_CO\_GET\_INFO](oid-wan-co-get-info.md) query. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows XP.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WAN\_CO\_GET\_INFO](oid-wan-co-get-info.md) + +[OID\_WAN\_CO\_GET\_LINK\_INFO](oid-wan-co-get-link-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WAN_CO_SET_LINK_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-abort-task.md b/windows-driver-docs-pr/network/oid-wdi-abort-task.md new file mode 100644 index 0000000000..0fd92a6716 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-abort-task.md @@ -0,0 +1,192 @@ +--- +title: OID_WDI_ABORT_TASK +author: windows-driver-content +description: OID_WDI_ABORT_TASK is a property that is sent down to cancel a specific pending task. +ms.assetid: 0E454DC9-1CED-497F-90A8-7065883BB945 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_ABORT_TASK Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_ABORT\_TASK + + +OID\_WDI\_ABORT\_TASK is a property that is sent down to cancel a specific pending task. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +This command follows property semantics. It should be treated as a signal, should be handled as quickly as possible, and should be completed independently of task completion. The IHV component must then attempt to complete the pending task as soon as possible. + +## Command parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------| +| [**WDI\_TLV\_CANCEL\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926163) | | | Information for the command that is being cancelled. | + +  + +## Command result + + +Contains a status of NDIS\_STATUS\_SUCCESS. There is no additional payload. +## Examples + + +Original input task command: + +Field +Subfield +Type +Value +NDIS\_OID\_REQUEST +Oid +NDIS\_OID +OID(WDI\_TASK\_SCAN) +InputBufferLength +UINT32 +0x210 (example) +InformationBuffer +PVOID +Pointer to memory block containing WDI\_MESSAGE\_HEADER + TLV payload +WDI\_MESSAGE\_HEADER +PortId +UINT16 +0x0001 (example) +Reserved +UINT16 +N/A +WiFiStatus +NDIS\_STATUS +N/A +TransactionId +UINT32 +0x1111 (example) +IhvSpecificId +UINT32 +N/A +TLV Payload +TLV Payload +Various +Payload data +  + +Abort task input command (with message header): + +Field +Subfield +Type +Value +NDIS\_OID\_REQUEST +Oid +NDIS\_OID +OID(WDI\_ABORT\_TASK) +InputBufferLength +UINT32 +sizeof(WDI\_MESSAGE\_HEADER) + sizeof(WDI\_TLV\_CANCEL\_PARAMETERS) +InformationBuffer +PVOID +Pointer to memory block containing WDI\_MESSAGE\_HEADER + TLV payload +WDI\_MESSAGE\_HEADER +PortId +UINT16 +0x0001 (example) +Reserved +UINT16 +N/A +WiFiStatus +NDIS\_STATUS +N/A +TransactionId +UINT32 +0x2222 (example) +IhvSpecificId +UINT32 +0 +WDI\_TLV\_CANCEL\_PARAMETERS +OriginalTaskOid +NDIS\_OID +OID(WDI\_TASK\_SCAN) +OriginalPortId +UINT16 +0x0001 (example) +OriginalTransactionId +UINT32 +0x1111 (example) +  + +Abort task command result: + +Field +Subfield +Type +Value +NDIS\_OID\_REQUEST +Oid +NDIS\_OID +OID(WDI\_TASK\_SCAN) +OutputBufferLength +UINT32 +sizeof(WDI\_MESSAGE\_HEADER) +InformationBuffer +PVOID +Pointer to memory block containing WDI\_MESSAGE\_HEADER +WDI\_MESSAGE\_HEADER +PortId +UINT16 +0x0001 (example) +Reserved +UINT16 +N/A +WiFiStatus +NDIS\_STATUS +NDIS\_STATUS\_SUCCESS +TransactionId +UINT32 +0x2222 (example) +IhvSpecificId +UINT32 +N/A +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_ABORT_TASK%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-adapter-capabilities.md b/windows-driver-docs-pr/network/oid-wdi-get-adapter-capabilities.md new file mode 100644 index 0000000000..771a0f2a80 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-adapter-capabilities.md @@ -0,0 +1,173 @@ +--- +title: OID_WDI_GET_ADAPTER_CAPABILITIES +author: windows-driver-content +description: OID_WDI_GET_ADAPTER_CAPABILITIES is a read-only property that is issued from the host to the adapter during initialization and requests the adapter’s capabilities. +ms.assetid: e79deb29-bc0b-472e-b549-86bf71fe66ff +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_ADAPTER_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_ADAPTER\_CAPABILITIES + + +OID\_WDI\_GET\_ADAPTER\_CAPABILITIES is a read-only property that is issued from the host to the adapter during initialization and requests the adapter’s capabilities. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|---------|--------------------------|---------------------------------| +| Adapter | Set not supported | 1 | + +  + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +If the adapter supports Wi-Fi Direct, both [**WDI\_TLV\_AP\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/dn926129) and [**WDI\_TLV\_P2P\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/dn897863) must be specified + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn926255)XHost-adapter communication protocol configuration attributes.
[WDI_TLV_INTERFACE_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn897835)Interface attributes.
[WDI_TLV_STATION_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn898066)Station attributes.
[WDI_TLV_AP_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn926129)XAccess point attributes.
[WDI_TLV_VIRTUALIZATION_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn898078)XVirtualization attributes.
[WDI_TLV_P2P_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn897863)XThe Wi-Fi Direct attributes.
[WDI_TLV_DATAPATH_ATTRIBUTES](https://msdn.microsoft.com/library/windows/hardware/dn926277)XDatapath attributes.
[WDI_TLV_BAND_INFO](https://msdn.microsoft.com/library/windows/hardware/dn926146)XXBand information.
[WDI_TLV_PHY_INFO](https://msdn.microsoft.com/library/windows/hardware/dn898023)XXPHY information.
[WDI_TLV_PM_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn898032)XPower management capabilities.
[WDI_TLV_COUNTRY_REGION_LIST](https://msdn.microsoft.com/library/windows/hardware/dn926268)XCountry or region codes.
[WDI_TLV_RECEIVE_COALESCING_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn898046)XHardware assisted receive filter capabilities.
[WDI_TLV_TCP_OFFLOAD_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn898069)XTCP/IP offload capabilities.

[WDI_TLV_SUPPORTED_GUIDS](https://msdn.microsoft.com/library/windows/hardware/mt769918)

X

X

Added in Windows 10, version 1607, WDI version 1.0.21.

+

A list of GUIDs that are passed on to NDIS when WDI is queried for [OID_GEN_SUPPORTED_GUIDS](https://msdn.microsoft.com/library/windows/hardware/ff569641).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_ADAPTER_CAPABILITIES%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-auto-power-save.md b/windows-driver-docs-pr/network/oid-wdi-get-auto-power-save.md new file mode 100644 index 0000000000..e85ea31916 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-auto-power-save.md @@ -0,0 +1,73 @@ +--- +title: OID_WDI_GET_AUTO_POWER_SAVE +author: windows-driver-content +description: OID_WDI_GET_AUTO_POWER_SAVE gets the power save state of the port. +ms.assetid: b7a14348-66ad-4728-986d-05145eb49b27 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_AUTO_POWER_SAVE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_AUTO\_POWER\_SAVE + + +OID\_WDI\_GET\_AUTO\_POWER\_SAVE gets the power save state of the port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Not applicable | 1 | + +  + +There is a trade-off between power saving and latency. When auto power save mode is set to be enabled with the [OID\_WDI\_SET\_CONNECTION\_QUALITY](oid-wdi-set-connection-quality.md) command, the firmware tries to interact with the connected access point to go to power save mode as much as appropriate to save power. The firmware is also responsible for detecting if the connected access point confirms to the 802.11 specification and follows the power save mode protocol. If the access point does not conform (does not support power save mode correctly), the firmware should not go into power save mode, even when Auto Power Save is set to enabled. When Auto Power Save is set to disabled, the firmware focuses on low latency of sending and receiving packets. Examples of this are when streaming mode is on, and when the system is using AC power so low latency is preferred to saving power. + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------|--------------------------------|----------|------------------------------| +| [**WDI\_TLV\_GET\_AUTO\_POWER\_SAVE**](https://msdn.microsoft.com/library/windows/hardware/dn926307) | | | Auto power save information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_AUTO_POWER_SAVE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-bss-entry-list.md b/windows-driver-docs-pr/network/oid-wdi-get-bss-entry-list.md new file mode 100644 index 0000000000..f5405d8b7f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-bss-entry-list.md @@ -0,0 +1,81 @@ +--- +title: OID_WDI_GET_BSS_ENTRY_LIST +author: windows-driver-content +description: OID_WDI_GET_BSS_ENTRY_LIST is used to ask the adapter to indicate the list of BSS networks that have been cached by the port. +ms.assetid: 0eaa2b3a-6a1f-49e1-9556-81691892e666 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_BSS_ENTRY_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_BSS\_ENTRY\_LIST + + +OID\_WDI\_GET\_BSS\_ENTRY\_LIST is used to ask the adapter to indicate the list of BSS networks that have been cached by the port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Set not supported | 1 | + +  + +This is only used for an adapter that perform BSS list caching. When acting as a client, the port must report the BSS entry for the access point. In addition, if the port is performing background scans, it should report BSS entries that it has discovered in its scan. + +When this request is received by the adapter, it must send [NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) indications to the Microsoft component. These indications must contain the BSS entries that match the Get parameters. The adapter can send one or more NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST indications, but they must be completed before the property completes. + +The Microsoft component uses the list of indicated entries to report the BSS list to the operation system. It is also used to populate parameters for roam and connect tasks. + +## Get property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------|--------------------------------|----------|-------------------------------------------------------| +| [**WDI\_TLV\_SSID**](https://msdn.microsoft.com/library/windows/hardware/dn898064) | | | The SSID that the host needs the BSS list update for. | + +  + +## Get property results + + +No additional data. The data in the header is sufficient. +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_BSS_ENTRY_LIST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-next-action-frame-dialog-token.md b/windows-driver-docs-pr/network/oid-wdi-get-next-action-frame-dialog-token.md new file mode 100644 index 0000000000..32228f8014 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-next-action-frame-dialog-token.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_GET_NEXT_ACTION_FRAME_DIALOG_TOKEN +author: windows-driver-content +description: OID_WDI_GET_NEXT_ACTION_FRAME_DIALOG_TOKEN requests the DialogToken to be used in the next Action frame. +ms.assetid: EB5F6077-1566-41AE-B414-9ECF24BAE982 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_NEXT_ACTION_FRAME_DIALOG_TOKEN Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_NEXT\_ACTION\_FRAME\_DIALOG\_TOKEN + + +OID\_WDI\_GET\_NEXT\_ACTION\_FRAME\_DIALOG\_TOKEN requests the DialogToken to be used in the next Action frame. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------|--------------------------------|----------|-----------------| +| [**WDI\_TLV\_NEXT\_DIALOG\_TOKEN**](https://msdn.microsoft.com/library/windows/hardware/dn897854) | | | A dialog token. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_NEXT_ACTION_FRAME_DIALOG_TOKEN%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-pm-protocol-offload.md b/windows-driver-docs-pr/network/oid-wdi-get-pm-protocol-offload.md new file mode 100644 index 0000000000..17215168d1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-pm-protocol-offload.md @@ -0,0 +1,85 @@ +--- +title: OID_WDI_GET_PM_PROTOCOL_OFFLOAD +author: windows-driver-content +description: OID_WDI_GET_PM_PROTOCOL_OFFLOAD requests a list of protocol offloads for power management. +ms.assetid: ed7604fa-666c-4aa1-9041-ed56d282c29b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_PM_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD + + +OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD requests a list of protocol offloads for power management. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Not applicable | 1 | + +  + +## Get property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------|--------------------------------|----------|----------------------| +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_GET**](https://msdn.microsoft.com/library/windows/hardware/dn898034) | | | Protocol offload ID. | + +  + +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------| +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv4ARP**](https://msdn.microsoft.com/library/windows/hardware/dn898035) | | X | IPv4 ARP protocol offload parameters. | +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv6NS**](https://msdn.microsoft.com/library/windows/hardware/dn898036) | | X | IPv6 NS protocol offload parameters. | +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_80211RSN\_REKEY**](https://msdn.microsoft.com/library/windows/hardware/dn898033) | | X | RSN Rekey protocol offload parameters. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_ADD\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-add-pm-protocol-offload.md) + +[OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-remove-pm-protocol-offload.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_PM_PROTOCOL_OFFLOAD%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-receive-coalescing-match-count.md b/windows-driver-docs-pr/network/oid-wdi-get-receive-coalescing-match-count.md new file mode 100644 index 0000000000..0f30c0d048 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-receive-coalescing-match-count.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_GET_RECEIVE_COALESCING_MATCH_COUNT +author: windows-driver-content +description: OID_WDI_GET_RECEIVE_COALESCING_MATCH_COUNT requests the number of packets that have matched receive filters on the network port. +ms.assetid: 45b68057-d62a-4b77-9634-dfbed2817f23 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_RECEIVE_COALESCING_MATCH_COUNT Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_RECEIVE\_COALESCING\_MATCH\_COUNT + + +OID\_WDI\_GET\_RECEIVE\_COALESCING\_MATCH\_COUNT requests the number of packets that have matched receive filters on the network port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------| +| [**WDI\_TLV\_COALESCING\_FILTER\_MATCH\_COUNT**](https://msdn.microsoft.com/library/windows/hardware/dn926252) | | | The number of packets that have matched receive filters on the network port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_RECEIVE_COALESCING_MATCH_COUNT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-get-statistics.md b/windows-driver-docs-pr/network/oid-wdi-get-statistics.md new file mode 100644 index 0000000000..6d0f000c50 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-get-statistics.md @@ -0,0 +1,74 @@ +--- +title: OID_WDI_GET_STATISTICS +author: windows-driver-content +description: OID_WDI_GET_STATISTICS requests that the IHV component returns MAC and PHY layer statistics. +ms.assetid: 55c36869-ce85-42fe-877b-07aefb669b56 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_GET_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_GET\_STATISTICS + + +OID\_WDI\_GET\_STATISTICS requests that the IHV component returns MAC and PHY layer statistics. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Set not supported | 1 | + +  + +The MAC statistics must all be maintained per port. PHY statistics must also be maintained per port unless exempted. If PHY statistics cannot be maintained per port (as allowed by exemption), the statistics can be maintained per "channel" (PHY statistics for two ports operating on the same port can be combined). + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------|--------------------------------|----------|--------------------------| +| [**WDI\_TLV\_MAC\_STATISTICS**](https://msdn.microsoft.com/library/windows/hardware/dn897846) | X | | Per-peer MAC statistics. | +| [**WDI\_TLV\_PHY\_STATISTICS**](https://msdn.microsoft.com/library/windows/hardware/dn898025) | X | | Per-port PHY statistics. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_GET_STATISTICS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-ihv-request.md b/windows-driver-docs-pr/network/oid-wdi-ihv-request.md new file mode 100644 index 0000000000..1b4fa33b88 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-ihv-request.md @@ -0,0 +1,78 @@ +--- +title: OID_WDI_IHV_REQUEST +author: windows-driver-content +description: OID_WDI_IHV_REQUEST is used to forward information that an IHV extensibility module has sent to the miniport. +ms.assetid: d5639def-ddde-4972-b331-46c0f768d155 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_IHV_REQUEST Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_IHV\_REQUEST + + +OID\_WDI\_IHV\_REQUEST is used to forward information that an IHV extensibility module has sent to the miniport. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +This command is not serialized with any tasks. It is serialized with other properties and with the M1-M3 of a task. + +## Command parameter + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------|--------------------------------|----------|----------------------------------------------------| +| [**WDI\_TLV\_IHV\_DATA**](https://msdn.microsoft.com/library/windows/hardware/dn926312) | | X | The information from the IHV extensibility module. | + +  + +## Response result + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_IHV\_DATA**](https://msdn.microsoft.com/library/windows/hardware/dn926312) | | X | The response to be sent to the IHV extensibility module. The data value is forwarded as-is to the IHV extensibility module. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_IHV_REQUEST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-adapter-configuration.md b/windows-driver-docs-pr/network/oid-wdi-set-adapter-configuration.md new file mode 100644 index 0000000000..49a7737840 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-adapter-configuration.md @@ -0,0 +1,129 @@ +--- +title: OID_WDI_SET_ADAPTER_CONFIGURATION +author: windows-driver-content +description: OID_WDI_SET_ADAPTER_CONFIGURATION configures the adapter. It is an optional property and can only be sent before any ports are created. +ms.assetid: d1c37943-4755-4b9e-ab9c-9378aeca9c03 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ADAPTER_CONFIGURATION Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ADAPTER\_CONFIGURATION + + +OID\_WDI\_SET\_ADAPTER\_CONFIGURATION configures the adapter. It is an optional property and can only be sent before any ports are created. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|---------|--------------------------|---------------------------------| +| Adapter | Yes | 1 | + +  + +## Set property parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_CONFIGURED_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/dn926257)XMAC address.
[WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD](https://msdn.microsoft.com/library/windows/hardware/dn898075)XUnreachable detection threshold.
[WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY](https://msdn.microsoft.com/library/windows/hardware/dn897879)XPolicy used by the firmware for operating channel selection after a Wi-Fi Direct GO Reset is stopped/restarted.
[WDI_TLV_BAND_ID_LIST](https://msdn.microsoft.com/library/windows/hardware/dn926145)XList of band IDs.
[WDI_TLV_LINK_QUALITY_BAR_MAP](https://msdn.microsoft.com/library/windows/hardware/dn897841)Mapping of signal quality to Wi-Fi signal strength bars. This field should be ignored by the adapter and it should use the behavior specified in [NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE](ndis-status-wdi-indication-link-state-change.md) for doing Link Quality notifications.
[WDI_TLV_ADAPTER_NLO_SCAN_MODE](https://msdn.microsoft.com/library/windows/hardware/mt269108)XIndicates whether the NLO scans should be performed in active or passive mode.
[WDI_TLV_PLDR_SUPPORT](https://msdn.microsoft.com/library/windows/hardware/mt593243)Added in Windows 10, version 1511, WDI version 1.0.10. +

Specifies if PLDR is supported.

+ +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ADAPTER_CONFIGURATION%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-add-cipher-keys.md b/windows-driver-docs-pr/network/oid-wdi-set-add-cipher-keys.md new file mode 100644 index 0000000000..c197654257 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-add-cipher-keys.md @@ -0,0 +1,78 @@ +--- +title: OID_WDI_SET_ADD_CIPHER_KEYS +author: windows-driver-content +description: OID_WDI_SET_ADD_CIPHER_KEYS adds or overwrites cipher keys in the key table of a port. This is a set-only property. +ms.assetid: d10fc976-9e51-4bbb-8f29-caf8c600618a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ADD_CIPHER_KEYS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ADD\_CIPHER\_KEYS + + +OID\_WDI\_SET\_ADD\_CIPHER\_KEYS adds or overwrites cipher keys in the key table of a port. This is a set-only property. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +Cipher keys that are marked as Static should not be cleared on a roam. They can only be cleared on a [OID\_WDI\_TASK\_DOT11\_RESET](oid-wdi-task-dot11-reset.md) or if they are overwritten with a new OID\_WDI\_SET\_ADD\_CIPHER\_KEYS. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------| +| [**WDI\_TLV\_SET\_CIPHER\_KEY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn898056) | X | | The cipher keys to be added or overwritten in the key table of the port. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS](oid-wdi-set-delete-cipher-keys.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ADD_CIPHER_KEYS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-add-pm-protocol-offload.md b/windows-driver-docs-pr/network/oid-wdi-set-add-pm-protocol-offload.md new file mode 100644 index 0000000000..3f002667ee --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-add-pm-protocol-offload.md @@ -0,0 +1,82 @@ +--- +title: OID_WDI_SET_ADD_PM_PROTOCOL_OFFLOAD +author: windows-driver-content +description: OID_WDI_SET_ADD_PM_PROTOCOL_OFFLOAD adds a list of one or more protocol offloads for power management. +ms.assetid: 50c69dd4-352d-484f-81c1-a4c9587ab368 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ADD_PM_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ADD\_PM\_PROTOCOL\_OFFLOAD + + +OID\_WDI\_SET\_ADD\_PM\_PROTOCOL\_OFFLOAD adds a list of one or more protocol offloads for power management. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +This property provides information to enable the device/firmware to implement these protocols while the main CPU is asleep. In this state, the firmware and device handles the offloaded tasks without waking up the host. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------| +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv4ARP**](https://msdn.microsoft.com/library/windows/hardware/dn898035) | | X | IPv4 ARP protocol offload parameters. | +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv6NS**](https://msdn.microsoft.com/library/windows/hardware/dn898036) | | X | IPv6 NS protocol offload parameters. | +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_80211RSN\_REKEY**](https://msdn.microsoft.com/library/windows/hardware/dn898033) | | X | RSN Rekey protocol offload parameters. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-get-pm-protocol-offload.md) + +[OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-remove-pm-protocol-offload.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ADD_PM_PROTOCOL_OFFLOAD%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-add-wol-pattern.md b/windows-driver-docs-pr/network/oid-wdi-set-add-wol-pattern.md new file mode 100644 index 0000000000..68d64d93f5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-add-wol-pattern.md @@ -0,0 +1,82 @@ +--- +title: OID_WDI_SET_ADD_WOL_PATTERN +author: windows-driver-content +description: OID_WDI_SET_ADD_WOL_PATTERN adds a wake-on-LAN (WOL) pattern to the firmware. +ms.assetid: 96fb71fd-412b-4013-b3bc-c31a43516f55 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ADD_WOL_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ADD\_WOL\_PATTERN + + +OID\_WDI\_SET\_ADD\_WOL\_PATTERN adds a wake-on-LAN (WOL) pattern to the firmware. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +The host defines the packet pattern types to add to the firmware. The firmware detects matching packets that arrive in Dx. If detected, the firmware asserts the wake interrupt. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------| +| [**WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN**](https://msdn.microsoft.com/library/windows/hardware/dn898084) | X | X | WOL pattern information. | +| [**WDI\_TLV\_WAKE\_PACKET\_MAGIC\_PACKET**](https://msdn.microsoft.com/library/windows/hardware/dn898185) | | X | Pattern ID of the magic packet. | +| [**WDI\_TLV\_WAKE\_PACKET\_IPv4\_TCP\_SYNC**](https://msdn.microsoft.com/library/windows/hardware/dn898089) | X | X | WOL IPv4 TCP sync packet information. | +| [**WDI\_TLV\_WAKE\_PACKET\_IPv6\_TCP\_SYNC**](https://msdn.microsoft.com/library/windows/hardware/dn898091) | X | X | WOL IPv4 TCP sync packet information. | +| [**WDI\_TLV\_WAKE\_PACKET\_EAPOL\_REQUEST\_ID\_MESSAGE**](https://msdn.microsoft.com/library/windows/hardware/dn898087) | | X | WOL pattern ID of a EAPOL request ID message. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_REMOVE\_WOL\_PATTERN](oid-wdi-set-remove-wol-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ADD_WOL_PATTERN%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-advertisement-information.md b/windows-driver-docs-pr/network/oid-wdi-set-advertisement-information.md new file mode 100644 index 0000000000..521f01b39f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-advertisement-information.md @@ -0,0 +1,86 @@ +--- +title: OID_WDI_SET_ADVERTISEMENT_INFORMATION +author: windows-driver-content +description: OID_WDI_SET_ADVERTISEMENT_INFORMATION configures the Information Elements (IEs) and other advertisement settings to be included in the probe request, probe response, and beacons sent by the specified port. +ms.assetid: efa1fc93-2cc8-4d14-be5f-d099ef3c371e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ADVERTISEMENT_INFORMATION Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ADVERTISEMENT\_INFORMATION + + +OID\_WDI\_SET\_ADVERTISEMENT\_INFORMATION configures the Information Elements (IEs) and other advertisement settings to be included in the probe request, probe response, and beacons sent by the specified port. This request is only applicable to Wi-Fi Direct ports. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +When this command is received by the device, it shall update any relevant Wi-Fi Direct IEs, and append any necessary additional IEs in future outgoing messages sent by this port. + +## Set property parameters + + +WDI can provide a pre-configured set of prefix hashes for the advertised services. If a peer sends a hash, the driver first tries to match with a service name hash as defined in [**WDI\_TLV\_P2P\_ADVERTISED\_PREFIX\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/mt269134). If a match is found from the prefix hashes, the driver searches for the service(s) in [**WDI\_TLV\_P2P\_ADVERTISED\_SERVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897861) that have the prefix and responds with those. If a match is not found, the driver tries to match the requested service name hash in [**WDI\_TLV\_P2P\_ADVERTISED\_SERVICE\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897861). + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------| +| [**WDI\_TLV\_ADDITIONAL\_IES**](https://msdn.microsoft.com/library/windows/hardware/dn926122) | | X | Additional IEs to be included. | +| [**WDI\_TLV\_P2P\_DEVICE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897875) | | X | Wi-Fi Direct device information. | +| [**WDI\_TLV\_P2P\_DEVICE\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/dn897872) | | X | Wi-Fi Direct device capabilities. | +| [**WDI\_TLV\_P2P\_GROUP\_OWNER\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/dn897954) | | X | Wi-Fi Direct Group Owner capability information | +| [**WDI\_TLV\_P2P\_SECONDARY\_DEVICE\_TYPE\_LIST**](https://msdn.microsoft.com/library/windows/hardware/dn897991) | | X | List of Wi-Fi Direct secondary device types. | +| [**WDI\_TLV\_P2P\_ADVERTISED\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/dn897860) | | X | Wi-Fi Direct advertised services. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_ACTION\_FRAME\_RECEIVED](ndis-status-wdi-indication-action-frame-received.md) +The adapter must indicate ANQP Action Frame requests for the Service Information if it receives an ANQP request (or any other unknown action frame) from a peer. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ADVERTISEMENT_INFORMATION%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-association-parameters.md b/windows-driver-docs-pr/network/oid-wdi-set-association-parameters.md new file mode 100644 index 0000000000..a56f256ebc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-association-parameters.md @@ -0,0 +1,73 @@ +--- +title: OID_WDI_SET_ASSOCIATION_PARAMETERS +author: windows-driver-content +description: OID_WDI_SET_ASSOCIATION_PARAMETERS specifies parameters that the adapter can use during association to a set of BSSIDs. +ms.assetid: 86a6cc62-eaa4-435c-af6c-b76591d92c00 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ASSOCIATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ASSOCIATION\_PARAMETERS + + +OID\_WDI\_SET\_ASSOCIATION\_PARAMETERS specifies parameters that the adapter can use during association to a set of BSSIDs. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +This command replaces the previously configured list of BSSID-specific association parameters. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------|--------------------------------|----------|---------------------------------| +| [**WDI\_TLV\_CONNECT\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926264) | X | | The BSS entries and parameters. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ASSOCIATION_PARAMETERS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-clear-receive-coalescing.md b/windows-driver-docs-pr/network/oid-wdi-set-clear-receive-coalescing.md new file mode 100644 index 0000000000..f7a9312409 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-clear-receive-coalescing.md @@ -0,0 +1,76 @@ +--- +title: OID_WDI_SET_CLEAR_RECEIVE_COALESCING +author: windows-driver-content +description: OID_WDI_SET_CLEAR_RECEIVE_COALESCING is used by the host to remove a packet filter for packet coalescing. +ms.assetid: 1c2848c4-c412-4f33-9fc6-bf900a89c65d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_CLEAR_RECEIVE_COALESCING Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING + + +OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING is used by the host to remove a packet filter for packet coalescing. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------| +| [**WDI\_TLV\_SET\_CLEAR\_RECEIVE\_COALESCING**](https://msdn.microsoft.com/library/windows/hardware/dn898057) | | | The packet filter ID to be removed. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_RECEIVE\_COALESCING](oid-wdi-set-receive-coalescing.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_CLEAR_RECEIVE_COALESCING%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-connection-quality.md b/windows-driver-docs-pr/network/oid-wdi-set-connection-quality.md new file mode 100644 index 0000000000..6a93e7f964 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-connection-quality.md @@ -0,0 +1,76 @@ +--- +title: OID_WDI_SET_CONNECTION_QUALITY +author: windows-driver-content +description: OID_WDI_SET_CONNECTION_QUALITY provides a hint to the IHV component to enforce connection quality for a given virtualized port. This hint allows the port to optimize channel usage in different scenarios. +ms.assetid: 753e25c5-44b5-4afa-8769-49f693472aa9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_CONNECTION_QUALITY Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_CONNECTION\_QUALITY + + +OID\_WDI\_SET\_CONNECTION\_QUALITY provides a hint to the IHV component to enforce connection quality for a given virtualized port. This hint allows the port to optimize channel usage in different scenarios. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +**Note**  This property specifies data path quality of service hints, which may cause conflicts with other properties or tasks that are issued to the adapter. + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_CONNECTION\_QUALITY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926259) | | | The desired Wi-Fi connection quality hint. | +| [**WDI\_TLV\_LOW\_LATENCY\_CONNECTION\_QUALITY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn897843) | | X | The behavior for low latency connection quality. This is only required if the connection quality is set to [**WDI\_CONNECTION\_QUALITY\_LOW\_LATENCY**](https://msdn.microsoft.com/library/windows/hardware/dn897807). | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_CONNECTION_QUALITY%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-default-key-id.md b/windows-driver-docs-pr/network/oid-wdi-set-default-key-id.md new file mode 100644 index 0000000000..8c6d70827c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-default-key-id.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_SET_DEFAULT_KEY_ID +author: windows-driver-content +description: OID_WDI_SET_DEFAULT_KEY_ID sets the default key ID for packet transmission on a port. +ms.assetid: 5112a661-3560-4070-b74a-0027e3adfac1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_DEFAULT_KEY_ID Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_DEFAULT\_KEY\_ID + + +OID\_WDI\_SET\_DEFAULT\_KEY\_ID sets the default key ID for packet transmission on a port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------| +| [**WDI\_TLV\_DEFAULT\_TX\_KEY\_ID\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926281) | | | The default key ID for packet transmission on the port. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_DEFAULT_KEY_ID%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-delete-cipher-keys.md b/windows-driver-docs-pr/network/oid-wdi-set-delete-cipher-keys.md new file mode 100644 index 0000000000..38dd7ca490 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-delete-cipher-keys.md @@ -0,0 +1,76 @@ +--- +title: OID_WDI_SET_DELETE_CIPHER_KEYS +author: windows-driver-content +description: OID_WDI_SET_DELETE_CIPHER_KEYS deletes cipher keys from the device's cipher key table. +ms.assetid: 0a8d4625-382b-4976-aa3f-a8fea0976a00 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_DELETE_CIPHER_KEYS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS + + +OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS deletes cipher keys from the device's cipher key table. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------| +| [**WDI\_TLV\_DELETE\_CIPHER\_KEY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn926283) | X | | The cipher keys to be deleted from the device's key table. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](oid-wdi-set-add-cipher-keys.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_DELETE_CIPHER_KEYS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-encapsulation-offload.md b/windows-driver-docs-pr/network/oid-wdi-set-encapsulation-offload.md new file mode 100644 index 0000000000..82da7ada76 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-encapsulation-offload.md @@ -0,0 +1,74 @@ +--- +title: OID_WDI_SET_ENCAPSULATION_OFFLOAD +author: windows-driver-content +description: OID_WDI_SET_ENCAPSULATION_OFFLOAD is sent by the OS to indicate that the lower edge driver (LE) should start doing the TCP Checksum/LSO offloads. +ms.assetid: 1095DBE0-2C6B-40F4-8E01-39F4BBA2FDBC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_ENCAPSULATION_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD + + +OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD is sent by the OS to indicate that the lower edge driver (LE) should start doing the TCP Checksum/LSO offloads. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +When this message is received, the LE should indicate its current encapsulation offload configuration with [NDIS\_STATUS\_WDI\_INDICATION\_TASK\_OFFLOAD\_CURRENT\_CONFIG](ndis-status-wdi-indication-task-offload-current-config.md). For receive operations, the LE should not start the checksum offload until after it receives the OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD message. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------| +| [**WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V4\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898058) | | | Specifies if IPv4 offloading should be started. | +| [**WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V6\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898059) | | | Specifies if IPv6 offloading should be started. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_ENCAPSULATION_OFFLOAD%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-end-dwell-time.md b/windows-driver-docs-pr/network/oid-wdi-set-end-dwell-time.md new file mode 100644 index 0000000000..933e8099ee --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-end-dwell-time.md @@ -0,0 +1,68 @@ +--- +title: OID_WDI_SET_END_DWELL_TIME +author: windows-driver-content +description: OID_WDI_SET_END_DWELL_TIME is typically sent during an Action Frame exchange, either when WDI has to wait some time before sending a followup Action Frame, or when the protocol sequence is complete. +ms.assetid: 8ED1FDB1-BFDB-4522-8FF8-00D3B59EE43C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_END_DWELL_TIME Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_END\_DWELL\_TIME + + +OID\_WDI\_SET\_END\_DWELL\_TIME is typically sent during an Action Frame exchange, either when WDI has to wait some time before sending a followup Action Frame, or when the protocol sequence is complete. This command can be sent on the device port or station port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +On receipt of this command, the firmware can choose to stop dwelling on the channel that had been specified when WDI sent the command to send the Action Frame. If the Dwell Time had already expired, the firmware should ignore this command. + +## Set property parameters + + +No additional parameters. The data in the header is sufficient. +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_END_DWELL_TIME%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-fast-bss-transition-parameters.md b/windows-driver-docs-pr/network/oid-wdi-set-fast-bss-transition-parameters.md new file mode 100644 index 0000000000..04830da3a5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-fast-bss-transition-parameters.md @@ -0,0 +1,74 @@ +--- +title: OID_WDI_SET_FAST_BSS_TRANSITION_PARAMETERS +author: windows-driver-content +description: OID_WDI_SET_FAST_BSS_TRANSITION_PARAMETERS is sent in response to NDIS_STATUS_WDI_INDICATION_FT_ASSOC_PARAMS_NEEDED. It has the parameters required to send the (Re)Association request. The command is sent to the driver as a direct OID. +ms.assetid: D769E49D-C565-41CD-9C91-195B1223AE66 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_FAST_BSS_TRANSITION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_FAST\_BSS\_TRANSITION\_PARAMETERS + + +OID\_WDI\_SET\_FAST\_BSS\_TRANSITION\_PARAMETERS is sent in response to [NDIS\_STATUS\_WDI\_INDICATION\_FT\_ASSOC\_PARAMS\_NEEDED](ndis-status-wdi-indication-ft-assoc-params-needed.md). It has the parameters required to send the (Re)Association request. The command is sent to the driver as a direct OID. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn898068) | | | If this status is success, the rest of the fields (RSNIE, MDE, FTE) are present. This indicates that there are no problems or errors with the Authentication response (for example, MIC check failure) and the IHV can proceed with the reassociation request. | +| [**WDI\_TLV\_FT\_RSNIE**](https://msdn.microsoft.com/library/windows/hardware/mt269125) | | X | The RSN IE byte blob. | +| [**WDI\_TLV\_FT\_MDE**](https://msdn.microsoft.com/library/windows/hardware/mt269120) | | X | The MDE byte blob. | +| [**WDI\_TLV\_FT\_FTE**](https://msdn.microsoft.com/library/windows/hardware/mt269118) | | X | The FTE byte blob. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_FAST_BSS_TRANSITION_PARAMETERS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-flush-bss-entry.md b/windows-driver-docs-pr/network/oid-wdi-set-flush-bss-entry.md new file mode 100644 index 0000000000..ec79686a0d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-flush-bss-entry.md @@ -0,0 +1,66 @@ +--- +title: OID_WDI_SET_FLUSH_BSS_ENTRY +author: windows-driver-content +description: OID_WDI_SET_FLUSH_BSS_ENTRY is sent to the device to flush the list of BSS entries maintained by the adapter. This command can only be sent on the station port. +ms.assetid: 8d54a7f3-4680-444c-aa1a-e8da8d2d2f0e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_FLUSH_BSS_ENTRY Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_FLUSH\_BSS\_ENTRY + + +OID\_WDI\_SET\_FLUSH\_BSS\_ENTRY is sent to the device to flush the list of BSS entries maintained by the adapter. This command can only be sent on the station port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +## Set property parameters + + +No additional parameters. The data in the header is sufficient. +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_FLUSH_BSS_ENTRY%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-multicast-list.md b/windows-driver-docs-pr/network/oid-wdi-set-multicast-list.md new file mode 100644 index 0000000000..262fb236c8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-multicast-list.md @@ -0,0 +1,75 @@ +--- +title: OID_WDI_SET_MULTICAST_LIST +author: windows-driver-content +description: OID_WDI_SET_MULTICAST_LIST specifies the multicast address list for a given port. This command can be set at any time. +ms.assetid: dee41a49-2be2-4364-877c-b2b3bf29e78d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_MULTICAST_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_MULTICAST\_LIST + + +OID\_WDI\_SET\_MULTICAST\_LIST specifies the multicast address list for a given port. This command can be set at any time. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +The IHV component should only fail the command if the list size exceeds the limit specified in [**WDI\_TLV\_INTERFACE\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/dn897835). + +After the host enables multicast packet filtering on the port using [OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER](oid-wdi-set-receive-packet-filter.md), the device must indicate received multicast frames with a destination address matching an address in the port’s multicast list to the host. The device must clear the multicast list as part of processing of [OID\_WDI\_TASK\_DOT11\_RESET](oid-wdi-task-dot11-reset.md). When the command is sent with no multicast list specified, the driver must clear its multicast list. In this case, no packets should be indicated up unless OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER has the WDI\_PACKET\_FILTER\_ALL\_MULTICAST bit set. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------| +| [**WDI\_TLV\_MULTICAST\_LIST**](https://msdn.microsoft.com/library/windows/hardware/dn897849) | | X | List of multicast MAC addresses. The list must not be empty. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_MULTICAST_LIST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-neighbor-report-entries.md b/windows-driver-docs-pr/network/oid-wdi-set-neighbor-report-entries.md new file mode 100644 index 0000000000..b33acf5ffe --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-neighbor-report-entries.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_SET_NEIGHBOR_REPORT_ENTRIES +author: windows-driver-content +description: OID_WDI_SET_NEIGHBOR_REPORT_ENTRIES sends the list of neighbor reports received from the AP to the LE. This is sent as soon as the UE receives the neighbor report from the currently connected AP. +ms.assetid: F77FDA4A-3029-4F6E-A82E-B318543484FF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_NEIGHBOR_REPORT_ENTRIES Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_NEIGHBOR\_REPORT\_ENTRIES + + +OID\_WDI\_SET\_NEIGHBOR\_REPORT\_ENTRIES sends the list of neighbor reports received from the AP to the LE. This is sent as soon as the UE receives the neighbor report from the currently connected AP. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------| +| [**WDI\_TLV\_NEIGHBOR\_REPORT\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/mt269133) | X | | The list of neighbor reports. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_NEIGHBOR_REPORT_ENTRIES%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-network-list-offload.md b/windows-driver-docs-pr/network/oid-wdi-set-network-list-offload.md new file mode 100644 index 0000000000..c9301aeb7a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-network-list-offload.md @@ -0,0 +1,104 @@ +--- +title: OID_WDI_SET_NETWORK_LIST_OFFLOAD +author: windows-driver-content +description: OID_WDI_SET_NETWORK_LIST_OFFLOAD sets a list of preferred SSIDs for the firmware to scan for APs. +ms.assetid: 2df9ee2b-78df-4f92-9b40-5945ecc81c7e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_NETWORK_LIST_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_NETWORK\_LIST\_OFFLOAD + + +OID\_WDI\_SET\_NETWORK\_LIST\_OFFLOAD sets a list of preferred SSIDs for the firmware to scan for APs. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|--------------|--------------------------|---------------------------------| +| Primary port | Yes | 1 | + +  + +There are two types of Network List Offload (NLO). One type is offload to NICs on Always On Always Connected (AOAC) systems. The other is Instant Connect NLO which, in Windows 8 and Windows 8.1, was only used for non-AOAC systems to quickly reconnect Wi-Fi at resume from hibernation. For Instant Connect, the list is sent down before the system goes into hibernation. Going forward, Instant Connect is used for resume from hibernation on AOAC systems that support it. + +## Instant Connect + + +WDI handles Instant Connect NLO and uses a combination of targeted scans to fulfill the request from the OS. IHV drivers do not need to handle this Instant Connect OS request. + +When the OS resumes from hibernation, the OS sends an Instant Connect NLO. WDI makes a union of all channel hints for a targeted scan OID. IHV drivers should support such a targeted scan as defined in [OID\_WDI\_TASK\_SCAN](oid-wdi-task-scan.md). The following section applies to Network List Offload to capable NICs on AOAC systems. + +## Network List Offload + + +The OS does not request periodic background scans when in CS. A NLO scan is the preferred method in CS because the screen is off when users do not need to see all visible APs. SSIDs that users have auto-connect profiles set to auto-connect are the only useful APs. The list of SSIDs to offload from the OS has a preferred authentication and cipher pair, and up to four channel hints. When the list has a least one SSID, the firmware should start to do a NLO scan autonomously, following the schedule of fast scan and slow scan phases. The WDI compliant driver translates the operating system request to a firmware request. The firmware is expected to do a NLO scan according the schedule for the APs. The APs should support the preferred authentication and cipher pair associated with the SSIDs. + +The request to the firmware has a list of channel hints for all offload SSIDs. The WDI compliant driver combines them for the firmware. For example, if SSID1\[auth1, cipher1\] has channel hints of 1 and 6, and SSID2\[auth2, cipher2\] has channel hints of 6 and 11, the request to the firmware is a list of SSIDs { SSID1\[auth1, cipher1\], SSID2\[auth2, cipher2\] } and list of channels to scan { 1, 6, 11 }. + +In each scan period, the firmware scans for SSIDs that match the criteria on the list of channels, but not necessary constrained on the list of channels. The discovered AP information should be cached for the host to retrieve. The firmware indicates NLO discovery when at least one BSSID matches the SSID, algorithm, and cipher, but the channel match is not required. + +Each OID\_WDI\_SET\_NETWORK\_LIST\_OFFLOAD that the UE sends to the LE represents a fresh NLO scan request. Any previous such requests or states are renewed. LE scans for NLO and only indicates once for a found AP per request. The UE replumbs (12 times; this is subject to change) NLO at Dx transitions if a found AP is not connected successfully (due to reasons such as: an AP is found but devices move around, the AP signal fades, and the connection fails; or prolong EAP authentication fails partway through). The LE and firmware should delay the NLO scan schedule based on the delay configuration in [**WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_CONFIG**](https://msdn.microsoft.com/library/windows/hardware/dn897851). This is a number that the UE uses to conform to the schedule of the operating system's original NLO command. + +The default scan type for NLO is WDI\_SCAN\_TYPE\_AUTO. When actively scanning a channel, the firmware should use the wildcard SSID. Visible APs should be compared with SSIDs on the offload list to decide a match. This is to reduce privacy exposure. + +Indicating NLO discovery has two cases. + +1. When the NIC is in D2, it must do the following steps. + - Trigger the wake interrupt and wait for set power to D0 before continuing to the following steps. + - Indicate that the firmware woke the stack with the reason of NLO discovery. + - Return D0 command. + - Indicate NLO discovery with all of the found AP information. + +2. When the NIC is in D0, it must do the following step. + - Indicate NLO discovery with all of the found AP information. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------| +| [**WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn897852) | | | The NLO parameters. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_NETWORK_LIST_OFFLOAD%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-p2p-listen-state.md b/windows-driver-docs-pr/network/oid-wdi-set-p2p-listen-state.md new file mode 100644 index 0000000000..84e9fb0b8a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-p2p-listen-state.md @@ -0,0 +1,85 @@ +--- +title: OID_WDI_SET_P2P_LISTEN_STATE +author: windows-driver-content +description: OID_WDI_SET_P2P_LISTEN_STATE sets the Wi-Fi Direct listen state on the port. +ms.assetid: d488903b-ef64-44b6-b07a-70168a0ccfd8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_P2P_LISTEN_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_P2P\_LISTEN\_STATE + + +OID\_WDI\_SET\_P2P\_LISTEN\_STATE sets the Wi-Fi Direct listen state on the port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +There are different levels of listen state, and the port is expected to adhere to concurrency requirements across ports. + +This property is only applicable to virtualized Wi-Fi Direct Adapter Port interfaces. + +When the listen state is active, the port is expected to park the radio on a social channel for a certain period of time. + +If the adapter has a virtualized port operating on a non-social channel, the port may become discoverable on that channel. If this behavior is used, the port must be very highly available to allow other adapters to quickly discover it when in the scan phase of Wi-Fi Direct discovery. This is provided as a trade-off to avoid channel hopping in low latency scenarios. + +**Note**  This property specifies a radio time slice requirement to the port, which may cause conflicts with other properties or tasks issued to the port. + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_LISTEN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/dn897975) | | | Desired listen state. | +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](https://msdn.microsoft.com/library/windows/hardware/dn897869) | | X | The host’s desired listen channel when enabling the Wi-Fi Direct listen state. If this option is not specified, the port may select a listen channel on its own. | +| [**WDI\_TLV\_P2P\_LISTEN\_DURATION**](https://msdn.microsoft.com/library/windows/hardware/dn897973) | | | Cycle duration and listen time. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_P2P_LISTEN_STATE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-p2p-start-background-discovery.md b/windows-driver-docs-pr/network/oid-wdi-set-p2p-start-background-discovery.md new file mode 100644 index 0000000000..f058d5af95 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-p2p-start-background-discovery.md @@ -0,0 +1,92 @@ +--- +title: OID_WDI_SET_P2P_START_BACKGROUND_DISCOVERY +author: windows-driver-content +description: OID_WDI_SET_P2P_START_BACKGROUND_DISCOVERY instructs the adapter to periodically perform Wi-Fi Direct discovery in the background +ms.assetid: DF58B71D-7D45-4E0D-963F-A70471363DF5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_P2P_START_BACKGROUND_DISCOVERY Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_P2P\_START\_BACKGROUND\_DISCOVERY + + +OID\_WDI\_SET\_P2P\_START\_BACKGROUND\_DISCOVERY instructs the adapter to periodically perform Wi-Fi Direct discovery in the background + +| Scope | Set serialized with task | Normal execution time (seconds) | Affects data throughput/latency | +|-------|--------------------------|---------------------------------|---------------------------------| +| Port | No | 1 | Yes | + +  + +The adapter is required to scan the specified channels at regular intervals and be able to find a device that becomes discoverable within the device visibility timeout (typically 5 minutes). The behavior is similar to the regular Wi-Fi Direct Discovery scan (as defined in [OID\_WDI\_TASK\_P2P\_DISCOVER](oid-wdi-task-p2p-discover.md)), but it is not time-bound, and the adapter may schedule the scans at some later point in time. The adapter must perform at least one scan within each device visibility timeout. If the device visibility timeout is 0, the adapter should continue to scan regularly using its own cycle time. If a DISCOVER or SCAN task request is made during this time, the adapter should suspend the background discovery for the duration of the task and continue when the task is finished. Upon completing a background scan, the device should send the [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_DISCOVERY\_COMPLETE](ndis-status-wdi-indication-p2p-discovery-complete.md) indication (with transaction ID equal to 0) to let the operating system know that it has completed a scan. The adapter must send this indication every time it completes a background scan. + +If the channel list is provided, the adapter should only scan on the specified channels. Otherwise, it should scan all channels. If the firmware happened to discover a device outside of the specified channels, it should still send the information to the operating system. + +When Listen Duration and channels ([**WDI\_TLV\_P2P\_DISCOVERY\_CHANNEL\_SETTINGS**](https://msdn.microsoft.com/library/windows/hardware/dn897877)) are specified, they refer to the listen times for the remote devices. Based on all the values of Listen Duration and channels, the adapter needs to come up with a schedule to scan the requested channels in the most efficient manner. The operating system may also specify multiple instances of Listen Duration and channels. In this case, the adapter should first come up with the scan schedule for those entries which have non-zero values of Listen Duration and Channel list. Then, the adapter should use default values in the following cases: + +1. If the Listen duration is 0, the adapter should use the default scan times for the specified channels. +2. If the channel list is empty, the adapter should scan all of the channels in that band using the listen and cycle times specified for that band. The scan times would not apply to any channels that have separate listen durations specified by the operating system. + +When the NIC is in D0, the adapter indicates the responses to the probe requests for the specific service name(s) as [NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) notifications to the operating system. WDI caches the response information for the OS for the higher layer services, and notifies them as necessary. + +When the NIC is in D2, it suspends background discovery until it goes back to D0. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_BACKGROUND\_DISCOVER\_MODE**](https://msdn.microsoft.com/library/windows/hardware/dn897864) | | | Wi-Fi Direct Background Discover Mode parameters. | +| [**WDI\_TLV\_P2P\_DISCOVERY\_CHANNEL\_SETTINGS**](https://msdn.microsoft.com/library/windows/hardware/dn897877) | X | X | List of recommended channels to scan. | +| [**WDI\_TLV\_P2P\_DEVICE\_FILTER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/dn897873) | | X | List of Wi-Fi Direct devices and Group Owners to search for during Wi-Fi Direct device discover. | +| [**WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn898009) | X | X | List of Service Hash names to be queried. This is required if WDI\_P2P\_SERVICE\_DISCOVERY\_TYPE\_SERVICE\_NAME\_ONLY is specified. | +| [**WDI\_TLV\_VENDOR\_SPECIFIC\_IE**](https://msdn.microsoft.com/library/windows/hardware/dn898076) | | X | One or more IEs that must be included in the probe requests sent by the port. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_P2P_START_BACKGROUND_DISCOVERY%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-p2p-stop-background-discovery.md b/windows-driver-docs-pr/network/oid-wdi-set-p2p-stop-background-discovery.md new file mode 100644 index 0000000000..e32fc9ef93 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-p2p-stop-background-discovery.md @@ -0,0 +1,66 @@ +--- +title: OID_WDI_SET_P2P_STOP_BACKGROUND_DISCOVERY +author: windows-driver-content +description: OID_WDI_SET_P2P_STOP_BACKGROUND_DISCOVERY instructs the adapter to cancel the background discovery and stop any active scans in progress. +ms.assetid: 485E795A-88BB-4A04-8B07-1B78593CB92F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_P2P_STOP_BACKGROUND_DISCOVERY Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_P2P\_STOP\_BACKGROUND\_DISCOVERY + + +OID\_WDI\_SET\_P2P\_STOP\_BACKGROUND\_DISCOVERY instructs the adapter to cancel the background discovery and stop any active scans in progress. + +| Scope | Set serialized with task | Normal execution time (seconds) | Affects data throughput/latency | +|-------|--------------------------|---------------------------------|---------------------------------| +| Port | No | 1 | No | + +  + +## Set property parameters + + +No additional parameters. The data in the header is sufficient. +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_P2P_STOP_BACKGROUND_DISCOVERY%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-p2p-wps-enabled.md b/windows-driver-docs-pr/network/oid-wdi-set-p2p-wps-enabled.md new file mode 100644 index 0000000000..a38d418a1d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-p2p-wps-enabled.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_SET_P2P_WPS_ENABLED +author: windows-driver-content +description: OID_WDI_SET_P2P_WPS_ENABLED requests that the adapter enables or disables Wi-Fi Protected Setup (WPS) on the NIC. +ms.assetid: 96F21807-464F-4B50-AF7E-779F6BF6FE37 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_P2P_WPS_ENABLED Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_P2P\_WPS\_ENABLED + + +OID\_WDI\_SET\_P2P\_WPS\_ENABLED requests that the adapter enables or disables Wi-Fi Protected Setup (WPS) on the NIC. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------| +| [**WDI\_TLV\_P2P\_WPS\_ENABLED**](https://msdn.microsoft.com/library/windows/hardware/dn898018) | | | Specifies whether to enable or disable WPS. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_P2P_WPS_ENABLED%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-power-state.md b/windows-driver-docs-pr/network/oid-wdi-set-power-state.md new file mode 100644 index 0000000000..cdba26f0d5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-power-state.md @@ -0,0 +1,286 @@ +--- +title: OID_WDI_SET_POWER_STATE +author: windows-driver-content +description: OID_WDI_SET_POWER_STATE sets the power state of the device. +ms.assetid: f1453ace-5e36-464e-96f0-e578890cdf3f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_POWER_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_POWER\_STATE + + +OID\_WDI\_SET\_POWER\_STATE sets the power state of the device. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|---------|--------------------------|---------------------------------| +| Adapter | Yes | 10 | + +  + +A NIC comes up in D0 (device fully powered) when the system boots or when the NIC is plugged in to the system. When the condition is right (on AOAC platforms, this is when NIC Active reference is 0 on the NIC), the operating system prepares and puts the NIC in D0. When users are not present, the host goes to low power state to save power. The host may set the NIC into a lower power state where the NIC can keep connections autonomously for the host. The NIC wakes up the host for external events that the host expresses interest in. + +OID\_WDI\_SET\_POWER\_STATE sets the device into D0, D1, D2, and D3. The D states are device class and platform specific. A Wi-Fi NIC usually supports only a subset of the states. For example, for Wi-Fi devices on SD bus, the supported set consists of D0, D2, and D3. The meaning of D2 and D3 are device-specific as well. For a Wi-Fi NIC on SDIO bus, it is defined to be able to wake from D2, but in D3, the NIC is halted. + +A PCIe bus NIC supports D0 and D3, where D3 can be D3Hot or D3Cold. On the host software stack, there is only D3. D3hot or D3Cold depends on the host scenarios and underlying platform support. For example, in connected standby scenarios, the host offloads wake events to the NIC and sets the NIC in D3, which is D3hot with platform support to keep the NIC powered so that the NIC can watch for external events for the host. In the hibernation scenario, the host sets the NIC in D3 and the platform turns off the power to the NIC so the NIC does not use any power. + +For an AOAC system that supports hibernation, the following is a summary of important system power states. On an AOAC system, a system sleep state is a connected standby state. This is the state where NICs are set to low power (D2 for SDBus NICs, D3 for PCIe NICs) and armed to wake. If the driver is suspended to the hard drive, it is the driver’s responsibility to resume firmware states as the driver does not go through reinitialization again (for example, DriverEntry is not called). + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SleepHibernationHybrid shutdownFull shutdown
Request by

Power button (default)

shutdown /h

shutdown /s /hybrid

shutdown /s

UI

Start > Power > Sleep

--

Start > Power > Shutdown

--

System state

Connected standby

Hibernation

Hybrid shutdown

Power off

Driver state

Alive - armed to wake

Suspend to hard drive

Suspend to hard drive

Power off

+ +  + +For an AOAC system where hibernation is not required or supported, here is the summary of driver power states. + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SleepFull shutdown
Request by

Power button (default)

shutdown /s

UI

Start > Power > Sleep

Start > Power > Shutdown

System state

Connected standby

Power off

Driver state

Alive - armed to wake

Power off

+ +  + +Set power commands cannot fail. The firmware should never fail such commands. The Microsoft component ensures that there are no outstanding tasks or commands when it sends any set power command. While the set power command is outstanding, the Microsoft component also guarantees that no other commands or tasks are sent to the IHV component. + +| Power state | Description | +|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| D0 (fully powered) | The NIC is fully powered and ready to receive commands. The host never requests changes between low power states. For example, if the host wants to set the NIC power state from D2 to D3, it first sets the power state to D0, and then to D3. | +| D2 and armed for wake (SDBus NICs) | In D2, the host never sends requests to the firmware except the Set D0 command. See later sections in this topic for relevant flow charts. | +| D3: power off (SDBus NICs), armed for wake (PCIe NICs) | For SDBus NICs, this state is powered off. For PCIe bus NICs, the operating system may arm NICs for wakes (D3Hot) or may turn off the power (D3Cold). Note that from the driver stack perspective, there is only D3 state. Multiple components are involved to enable the D3Hot state, including the ACPI table and the processing of NDIS system power IRPs that come from the operating system depending on end-user actions or inactions, such as hibernation, Connection Standby, and hybrid shutdown. | +| Dx for non-default ports | Dx is either D2 or D3. When the NIC is put into Dx all non-default ports are reset, which means all non-default ports are disconnected in Dx. | + +  + +## Set property parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription

[WDI_TLV_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/dn898040)

The power state. This applies to the primary port.

[WDI_TLV_ENABLE_WAKE_EVENTS](https://msdn.microsoft.com/library/windows/hardware/dn926303)

X

This field may only appear when the NIC is being put into low power and is armed to wake on any of the specified events (such as D2 on SD IO).

[WDI_TLV_SET_POWER_DX_REASON](https://msdn.microsoft.com/library/windows/hardware/dn898060)

X

The set power reason.

+ +  + +## Set property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_ADAPTER\_RESUME\_REQUIRED**](https://msdn.microsoft.com/library/windows/hardware/dn926120) | | X | If the value is true, it signals to the OS that the firmware needs assistance in resuming its context. This should only occur when the driver is suspended to storage. The IHV component must reset the software state because the operating system issues a series of Wi-Fi commands to bring the firmware context and IHV component context up to date. | + +  + +## Enable wake events + + +A NIC specifies the set of events that it can detect to wake the stack. The operating system plumbs down a subset or full set of the events to the NIC with the low power command. Some wake event parameters are set much earlier than the Dx command. Others are set right before the Dx command to the firmware. All events only become enabled with the Dx command. + +In this interface, the event that is set to enabled is plumbed down in the optional [**WDI\_TLV\_ENABLE\_WAKE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/dn926303) TLV as part of the OID\_WDI\_SET\_POWER command for device power state Dx. The TLV is absent if the operating system does not want to arm the NIC to wake. + +When the firmware receives a Dx command with [**WDI\_TLV\_ENABLE\_WAKE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/dn926303), it may detect a wake event before it completes the Dx command. It should buffer the event, finish processing the command, and then assert the wake interrupt. + +Each and every wake by the Wi-Fi NIC should be followed by a wake reason for why the NIC wakes the stack. A NIC wakes the stack by asserting the wake interrupt line, which is typically serviced by the bus or ACPI methods. The methods wake the CPU and required components to handle the wake event, and complete the Wi-Fi Wait Wake IRP for the stack. Subsequently, the operating system issues a D0 request to the driver and firmware. This request is a power OID to the driver that sends a D0 command to the firmware. The firmware holds the indication of the wake reason until it receives and completes the D0 command. + +**Note**  If the NIC receives the D0 command for some other reason (for example, the NIC does not wake the host), the NIC should not indicate a wake reason. + +  + +## No enabled wake events + + +If there is no [**WDI\_TLV\_ENABLE\_WAKE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/dn926303) present, the operating system does not need the NICs to run at low power. The NICs may be completely powered off. If suspended to a hard drive, the NICs drivers are expected to resume firmware context at resume. + +## Power state interaction and transition examples + + +The following diagrams show interactions and sequences of transitions between D0 and Dx (D2 or D3) for the NIC. In this context, the "Miniport" represents the host or WDI compliant driver. + +### D0 to Dx (armed to wake) + +![wdi d0 to dx armed transition](images/wdi-d0-to-dx-armed-to-wake.png) + +- Stop \[DnIO|UpIO\]: DnIO are messages (controls and data) to lower layer. UpIO are messages to upper layer. + + - Reject new requests from above layer (fail fast). + - Stop initiating IO from this layer (except this Dx command). + - Allow lower layer to inject TXs needed to go into Dx. + - Flush queues. +- AwaitInflight: Waiting for IO calls to return, including DMA in progress. Flush queues. + +- Dx is any non-D0 state. For SDBus Wi-Fi, this is D2. For PCIe bus, this is D3Hot. Firmware shall not lose power. + +### Dx (armed to wake) to D0 transition + +![dx armed to d0 transition](images/wdi-dx-to-d0-armed-to-wake.png) + +- If the NIC is armed to wake, it can't be D3Cold. Firmware must continue running in Dx. + +### D0 to D3 (not armed to wake) transition + +![d0 to d3 not armed transition](images/wdi-d0-to-d3-not-armed.png) + +- Stop \[DnIO|UpIO\]: DnIO are messages (controls and data) to lower layer. UpIO are messages to upper layer. + + - Reject new requests from above layer (fail fast). + - Stop initiating IO from this layer (except this Dx command). + - Allow lower layer to inject TXs needed to go into Dx. + - Flush queues. +- AwaitInflight: Waiting for IO calls to return, including DMA in progress. Flush queues. + +- D3 without PmParameters. The NIC may (D3Cold) or may not be powered off (for example, a shared power rail with a D0 device). + +### Dx (not armed to wake) to D0 transition + +![dx not armed to d0 transition](images/wdi-dx-to-d0-not-armed.png) + +- D2 notArmToWake: Kept power, no reinitialization required. +- D3 notArmtoWake: Might be Hot or Cold. Cold requires that context be restored. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_POWER_STATE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-privacy-exemption-list.md b/windows-driver-docs-pr/network/oid-wdi-set-privacy-exemption-list.md new file mode 100644 index 0000000000..699130d33e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-privacy-exemption-list.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_SET_PRIVACY_EXEMPTION_LIST +author: windows-driver-content +description: OID_WDI_SET_PRIVACY_EXEMPTION_LIST is used by the host to provide the list of exemptions for packet description. The adapter applies these exemptions to packets it receives that match the IEEE EtherType value specified for the exemption. +ms.assetid: 409ac8c5-0bf7-4ae9-b709-5c2cfa1f8b7f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_PRIVACY_EXEMPTION_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_PRIVACY\_EXEMPTION\_LIST + + +OID\_WDI\_SET\_PRIVACY\_EXEMPTION\_LIST is used by the host to provide the list of exemptions for packet description. The adapter applies these exemptions to packets it receives that match the IEEE EtherType value specified for the exemption. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------| +| [**WDI\_TLV\_PRIVACY\_EXEMPTION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn898041) | X | X | List of privacy exemption entries. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_PRIVACY_EXEMPTION_LIST%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-receive-coalescing.md b/windows-driver-docs-pr/network/oid-wdi-set-receive-coalescing.md new file mode 100644 index 0000000000..fa9b4fcf31 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-receive-coalescing.md @@ -0,0 +1,78 @@ +--- +title: OID_WDI_SET_RECEIVE_COALESCING +author: windows-driver-content +description: OID_WDI_SET_RECEIVE_COALESCING is used by the host to add a packet filter for packet coalescing. +ms.assetid: c8856813-0d81-4735-95cc-d9b5dc6ede87 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_RECEIVE_COALESCING Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_RECEIVE\_COALESCING + + +OID\_WDI\_SET\_RECEIVE\_COALESCING is used by the host to add a packet filter for packet coalescing. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +When the host receives a request from the OS to set packet coalescing filters, it uses this command to add a packet filter for packet coalescing. To clear a packet filter for packet coalescing, see [OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING](oid-wdi-set-clear-receive-coalescing.md). + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------| +| [**WDI\_TLV\_SET\_RECEIVE\_COALESCING**](https://msdn.microsoft.com/library/windows/hardware/dn898061) | | | The packet coalescing parameters to be set. | + +  + +## Set property results + + +No additional parameters. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING](oid-wdi-set-clear-receive-coalescing.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_RECEIVE_COALESCING%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-receive-packet-filter.md b/windows-driver-docs-pr/network/oid-wdi-set-receive-packet-filter.md new file mode 100644 index 0000000000..1a6e11b009 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-receive-packet-filter.md @@ -0,0 +1,73 @@ +--- +title: OID_WDI_SET_RECEIVE_PACKET_FILTER +author: windows-driver-content +description: OID_WDI_SET_RECEIVE_PACKET_FILTER defines a bitmask filter for data packets to be indicated for a given virtualized port. +ms.assetid: 180efda5-3ca2-40f8-89d1-098a53f33844 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_RECEIVE_PACKET_FILTER Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER + + +OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER defines a bitmask filter for data packets to be indicated for a given virtualized port. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +If set, the port shall only notify the host of packets which match the provided filter. These filters are similar to the required 802.11 filters provided to [OID\_GEN\_CURRENT\_PACKET\_FILTER](https://msdn.microsoft.com/library/windows/hardware/ff569575). + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------| +| [**WDI\_TLV\_PACKET\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898019) | | | The bitmask filter for data packets. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_RECEIVE_PACKET_FILTER%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-remove-pm-protocol-offload.md b/windows-driver-docs-pr/network/oid-wdi-set-remove-pm-protocol-offload.md new file mode 100644 index 0000000000..e6500343fc --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-remove-pm-protocol-offload.md @@ -0,0 +1,78 @@ +--- +title: OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD +author: windows-driver-content +description: OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD removes the protocol offload specified by the protocol offload ID. +ms.assetid: 47850c43-4d10-48f5-b2e9-1f94f23eabf2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD + + +OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD removes the protocol offload specified by the protocol offload ID. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------| +| [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_REMOVE**](https://msdn.microsoft.com/library/windows/hardware/dn898037) | | | Protocol offload ID. | + +  + +## Set property results + + +No additional parameters. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-get-pm-protocol-offload.md) + +[OID\_WDI\_SET\_ADD\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-add-pm-protocol-offload.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-remove-wol-pattern.md b/windows-driver-docs-pr/network/oid-wdi-set-remove-wol-pattern.md new file mode 100644 index 0000000000..10d0f317db --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-remove-wol-pattern.md @@ -0,0 +1,76 @@ +--- +title: OID_WDI_SET_REMOVE_WOL_PATTERN +author: windows-driver-content +description: OID_WDI_SET_REMOVE_WOL_PATTERN removes a wake-on-LAN (WOL) pattern from the firmware. +ms.assetid: 9fb03747-b585-4c73-b004-1bdc2a995e9d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_REMOVE_WOL_PATTERN Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_REMOVE\_WOL\_PATTERN + + +OID\_WDI\_SET\_REMOVE\_WOL\_PATTERN removes a wake-on-LAN (WOL) pattern from the firmware. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------| +| [**WDI\_TLV\_WAKE\_PACKET\_PATTERN\_REMOVE**](https://msdn.microsoft.com/library/windows/hardware/dn898186) | | | WOL pattern ID. | + +  + +## Set property results + + +No additional parameters. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +## See also + + +[OID\_WDI\_SET\_ADD\_WOL\_PATTERN](oid-wdi-set-add-wol-pattern.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_REMOVE_WOL_PATTERN%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-set-tcp-offload-parameters.md b/windows-driver-docs-pr/network/oid-wdi-set-tcp-offload-parameters.md new file mode 100644 index 0000000000..f067cc4755 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-set-tcp-offload-parameters.md @@ -0,0 +1,75 @@ +--- +title: OID_WDI_SET_TCP_OFFLOAD_PARAMETERS +author: windows-driver-content +description: OID_WDI_SET_TCP_OFFLOAD_PARAMETERS is sent down to the device from the OS to set the TCP offload parameters. +ms.assetid: B615066B-3871-4445-8397-B41CB66EEF35 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_SET_TCP_OFFLOAD_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS + + +OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS is sent down to the device from the OS to set the TCP offload parameters. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | Yes | 1 | + +  + +This command is sent in some cases such as when there is a need to turn off the offloads due to a performance issue. + +The lower edge driver (LE) must use the contents of [**WDI\_TLV\_TCP\_SET\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898071) to update the currently reported TCP offload capabilities. After the update, the LE must report the current task offload capabilities with [NDIS\_STATUS\_WDI\_INDICATION\_TASK\_OFFLOAD\_CURRENT\_CONFIG](ndis-status-wdi-indication-task-offload-current-config.md). This status indication ensures that all of the overlying protocol drivers are updated with the new capabilities information. + +## Set property parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------| +| [**WDI\_TLV\_TCP\_SET\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898071) | | | The TCP offload parameters to be set. | + +  + +## Set property results + + +No additional data. The data in the header is sufficient. +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_SET_TCP_OFFLOAD_PARAMETERS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-change-operation-mode.md b/windows-driver-docs-pr/network/oid-wdi-task-change-operation-mode.md new file mode 100644 index 0000000000..af4a9884ce --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-change-operation-mode.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_TASK_CHANGE_OPERATION_MODE +author: windows-driver-content +description: OID_WDI_TASK_CHANGE_OPERATION_MODE configures the operation mode for the port. +ms.assetid: 84be0658-104d-4336-bc2f-6f2624f33857 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_CHANGE_OPERATION_MODE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_CHANGE\_OPERATION\_MODE + + +OID\_WDI\_TASK\_CHANGE\_OPERATION\_MODE configures the operation mode for the port. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------|---------------------------------------|---------------------------------| +| Port | No | 4 | 1 | + +  + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------|--------------------------------|----------|-----------------------------| +| [**WDI\_TLV\_OPERATION\_MODE**](https://msdn.microsoft.com/library/windows/hardware/dn897856) | | | The desired operation mode. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_CHANGE\_OPERATION\_MODE\_COMPLETE](ndis-status-wdi-indication-change-operation-mode-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_CHANGE_OPERATION_MODE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-close.md b/windows-driver-docs-pr/network/oid-wdi-task-close.md new file mode 100644 index 0000000000..2a451b40b2 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-close.md @@ -0,0 +1,66 @@ +--- +title: OID_WDI_TASK_CLOSE +author: windows-driver-content +description: OID_WDI_TASK_CLOSE requests that the IHV component closes the adapter. This includes disabling interrupts and shutting down hardware. During a halt, this task is passed to the IHV through the CloseAdapterHandler handler registered by the IHV. +ms.assetid: 407d1dfa-18f7-4e22-8f7e-51fd610210af +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_CLOSE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_CLOSE + + +OID\_WDI\_TASK\_CLOSE requests that the IHV component closes the adapter. This includes disabling interrupts and shutting down hardware. During a halt, this task is passed to the IHV through the CloseAdapterHandler handler registered by the IHV. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|---------|---------------|---------------------------------------|---------------------------------| +| Adapter | No | 1 | 5 | + +  + +## Task parameters + + +None +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_CLOSE\_COMPLETE](ndis-status-wdi-indication-close-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_CLOSE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-connect.md b/windows-driver-docs-pr/network/oid-wdi-task-connect.md new file mode 100644 index 0000000000..4a4014fc8a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-connect.md @@ -0,0 +1,103 @@ +--- +title: OID_WDI_TASK_CONNECT +author: windows-driver-content +description: OID_WDI_TASK_CONNECT requests that the IHV component connects to an Access Point or to a Wi-Fi Direct GO. +ms.assetid: 63ba3979-6b30-49bf-91a9-fa01f0ef4922 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_CONNECT Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_CONNECT + + +OID\_WDI\_TASK\_CONNECT requests that the IHV component connects to an Access Point or to a Wi-Fi Direct GO. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The abort must be followed by a dot11 reset. | 4 | 10 | + +  + +As part of the connect, the IHV component must synchronize with, authenticate to, and associate to the BSS. The host provides the BSS entries that the IHV component can attempt to connect to. Once the IHV component has successfully connected to one of those entries, it should complete the connect process. If it is unable to connect to any of the BSS entries, it should complete the connect process with a failure. + +The IHV component does not need to perform a scan to find candidate BSS entries. It can use the list provided by the host for the connect. It can attempt to connect to each one, one after another. The host sorts the networks by RSSI, but the IHV component can use its own order for connection. If the adapter does not specify "Connect BSS Selection Override", it must only use the entries provided by the host for the connect. The host may issue an abort on an outstanding connect. On receiving the abort, the port must end the connection attempts and report a completion to the host. + +If the adapter specifies "Connect BSS Selection Override", it can perform scans on its own to find candidate BSS entries. It can connect to any BSS entry it finds as long as it meets the parameters configured by the host. It should optimize this selection to ensure that it meets any configured connection quality requirements. This could include optimizing roam scan, optimize AP selection, optimize association process, and minimize the security handshake needed. During a scan, if the device needs additional association parameters for a found BSS entry (for example, PMKID for roaming), it can send a [NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_PARAMETERS\_REQUEST](ndis-status-wdi-indication-association-parameters-request.md) indication to get the parameters. When available, the host configures these parameters with [OID\_WDI\_SET\_ASSOCIATION\_PARAMETERS](oid-wdi-set-association-parameters.md). + +If the connect fails or is aborted, the port should not reset any settings that may have been configured outside of the connect command. It must support the host issuing a second connect call on the same port. + +The status of the connect attempt for each BSS entry must be reported by the port at the end of the association attempt. This includes the successful attempt and also any failed attempts. At any time, the port must be associated with no more than one Access Point or Wi-Fi Direct GO. + +While a connect is ongoing, the port must maintain any connections established on other ports (for example, Infrastructure or Wi-Fi Direct). However, the port may reduce the amount of medium access provided to the other ports to finish the connection. During the connect, the host can submit packet send requests on other ports. + +If the authentication algorithm that is used for the connection requires 802.1x port authorization for network access, the host authorizes the port after the association operation has completed successfully. + +The 802.11 station uses the PMKID cache for pre-authentication to access points that have enabled the Robust Security Network Association (RSNA) authentication algorithm. If the 802.11 station is associating or reassociating to a BSSID that has a provided PMKID, the 802.11 station must use the PMKID data in the RSN information element (RSN IE) of its Association or Reassociation frame. + +If the port declares support for Host FIPS mode in [**WDI\_TLV\_STATION\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/dn898066), HostFIPSModeEnabled may be set to 1 in the connection parameters. + +If HostFIPSModeEnabled is set to 1, the following rules apply. + +- The port must follow the guidelines for sending/receiving data frames in Send operations in FIPS mode and Receive operations in FIPS mode. +- The port must not declare support for any QoS protocol in the association request sent to a non-HT access point. QoS support is required for HT connections. +- The port must not negotiate TSpec and must not perform transmit MSDU aggregation. +- The port must ensure that the SPP A-MSDU capable bit (bit 10) of the RSN capabilities IE it transmits is set to zero. Only PP A-MSDU are supported in this mode. + +The connection parameters must not have MFPEnabled and HostFIPSModeEnabled both set to 1. Management Frame Protection (802.11w) requires the port to encrypt/decrypt certain management and action frames, so it cannot be enabled for a connection using Host FIPS mode. In addition, Wake on Wireless LAN features are not applicable in Host-FIPS mode. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_CONNECT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926266) | | | The connection parameters. | +| [**WDI\_TLV\_CONNECT\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926264) | X | | The preferred list of candidate connect BSS entries. The port should attempt to connect to any of these BSS entries until the list is exhausted or the connection completed successfully. The port can reprioritize the entries if needed. If the adapter has set the Connect BSS Selection Override bit, then it can pick a BSS that is not in this list as long as it follows the Allowed/Disallowed list. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_CONNECT\_COMPLETE](ndis-status-wdi-indication-connect-complete.md) +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_RESULT](ndis-status-wdi-indication-association-result.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_CONNECT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-create-port.md b/windows-driver-docs-pr/network/oid-wdi-task-create-port.md new file mode 100644 index 0000000000..2b621a2c8a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-create-port.md @@ -0,0 +1,103 @@ +--- +title: OID_WDI_TASK_CREATE_PORT +author: windows-driver-content +description: OID_WDI_TASK_CREATE_PORT requests that a new 802.11 entity is created by the IHV component. +ms.assetid: e1a03a97-608f-42af-bd39-37a7eb9ad5b7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_CREATE_PORT Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_CREATE\_PORT + + +OID\_WDI\_TASK\_CREATE\_PORT requests that a new 802.11 entity is created by the IHV component. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|---------|---------------|---------------------------------------|---------------------------------| +| Adapter | No | 6 | 1 | + +  + +The operation mode of the created port is set to **WDI\_OPERATION\_MODE\_STA** unless it has been specified in the task parameters. + +If the MAC is to function as a Wi-Fi Direct device port, **uOpmodeMask** contains **WDI\_OPERATION\_MODE\_P2P\_DEVICE**. In this case, the IHV component driver must assign the MAC address reserved for the Wi-Fi Direct Device to this port and return it in the request completion indication. + +## Task parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_CREATE_PORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn926273)Parameters for port creation.
[WDI_TLV_CREATE_PORT_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/dn926270)X

This TLV is used when the UE recreates the non-primary port during resume from hibernation. When this TLV is present, the firmware must use this MAC address to create the port. This MAC address is guaranteed to be the MAC address that the firmware created for the port type prior to hibernation.

+

The goal is to use the same NDIS port number and MAC address in order to match the states of the upper layers. Note that the WFC_PORT_ID can be different at recreation, but the port ID should not collide with any port ID of an existing port. This information is only used between the UE and LE/firmware.

+ +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_CREATE\_PORT\_COMPLETE](ndis-status-wdi-indication-create-port-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_CREATE_PORT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-delete-port.md b/windows-driver-docs-pr/network/oid-wdi-task-delete-port.md new file mode 100644 index 0000000000..2160f32eec --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-delete-port.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_TASK_DELETE_PORT +author: windows-driver-content +description: OID_WDI_TASK_DELETE_PORT requests that the IHV component releases all resources (including MAC and PHY) allocated to the specified port. +ms.assetid: c84b6cd6-a8e7-4ba7-a9d9-04b2881904c8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_DELETE_PORT Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_DELETE\_PORT + + +OID\_WDI\_TASK\_DELETE\_PORT requests that the IHV component releases all resources (including MAC and PHY) allocated to the specified port. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|---------|---------------|---------------------------------------|---------------------------------| +| Adapter | No | 6 | 1 | + +  + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------| +| [**WDI\_TLV\_DELETE\_PORT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926288) | | | The delete port parameters. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_DELETE\_PORT\_COMPLETE](ndis-status-wdi-indication-delete-port-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_DELETE_PORT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-disconnect.md b/windows-driver-docs-pr/network/oid-wdi-task-disconnect.md new file mode 100644 index 0000000000..81c0166a8f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-disconnect.md @@ -0,0 +1,81 @@ +--- +title: OID_WDI_TASK_DISCONNECT +author: windows-driver-content +description: OID_WDI_TASK_DISCONNECT is used to terminate a connection with a peer. +ms.assetid: 03566fbd-5043-4166-bd33-0ed48f85f370 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_DISCONNECT Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_DISCONNECT + + +OID\_WDI\_TASK\_DISCONNECT is used to terminate a connection with a peer. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------|---------------------------------------|---------------------------------| +| Port | No | 2 | 1 | + +  + +This command is used to disconnect from an Access Point or a Wi-Fi Direct GO, and also to disconnect clients of the port. When the disconnect is received, the port must disassociate and deauthenticate from the peer and clear the state associated with that peer. However, it must not reset any of the connection parameters that are not specific to this peer. The task must be completed only after the disconnect activity has been completed. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------|--------------------------------|----------|----------------------------| +| [**WDI\_TLV\_DISCONNECT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926300) | | | The disconnect parameters. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_DISCONNECT\_COMPLETE](ndis-status-wdi-indication-disconnect-complete.md) +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION](ndis-status-wdi-indication-disassociation.md) +When the port gets disconnected from the network, it sends the disassociation indication to the OS. The disconnect may be triggered by a command from the OS, or may be triggered from the network. Network triggered disconnects may be explicit from received disassociation or deauthentication packets, or may be implicit when the port cannot detect the presence of the peer it is connected to. + +Before the disassociation indication is sent, the port must clear the state associated with the peer. This includes any keys and 802.1x port authorization information associated with the peer. The port must not trigger a roam on its own. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_DISCONNECT%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-dot11-reset.md b/windows-driver-docs-pr/network/oid-wdi-task-dot11-reset.md new file mode 100644 index 0000000000..f802a4552e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-dot11-reset.md @@ -0,0 +1,85 @@ +--- +title: OID_WDI_TASK_DOT11_RESET +author: windows-driver-content +description: OID_WDI_TASK_DOT11_RESET requests that the IHV component resets the MAC and PHY state on a specified port. +ms.assetid: 5fcac1da-0776-47a5-87b7-8e831f968f7c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_DOT11_RESET Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_DOT11\_RESET + + +OID\_WDI\_TASK\_DOT11\_RESET requests that the IHV component resets the MAC and PHY state on a specified port. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------|---------------------------------------|---------------------------------| +| Port | No | 1 | 1 | + +  + +Prior to issuing a dot11 reset command, the WDI driver stops issuing new commands to IHV component and aborts any task in progress on the port. It also flushes its Rx and TX queues. + +The dot11 reset combines the semantics of the 802.11 MLME and PLME reset primitive. When the IHV component receives a dot11 reset request, it should perform the following tasks. + +- Reset the port’s MAC entity to its initial state. +- Reset the port’s MIB attributes so they are set to their default values, if bSetDefaultMIB is true. +- Reset the TX/Rx state machines for the PHY entity and set it to Rx state only to ensure no more frames are transmitted. +- Flush the adapter’s Rx queue and complete the send for each packet in the TX queues. +- If the MAC address parameter is present, reset the port’s MAC address to the specified value. +- Set the port state to INIT before completing the dot11 reset operation. + +If the port being reset was operating as a STA, AP, or a Wi-Fi Direct Client or GO, the host would have triggered the disconnect task to request the IHV component to send disassociation to the peers before the reset. As such, the IHV component does not need to do it again. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------| +| [**WDI\_TLV\_DOT11\_RESET\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926302) | | | Parameters for the dot11 reset. | +| [**WDI\_TLV\_CONFIGURED\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926257) | | X | The MAC address that should be used for the port. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_DOT11\_RESET\_COMPLETE](ndis-status-wdi-indication-dot11-reset-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_DOT11_RESET%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-ihv.md b/windows-driver-docs-pr/network/oid-wdi-task-ihv.md new file mode 100644 index 0000000000..64d804d9fb --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-ihv.md @@ -0,0 +1,73 @@ +--- +title: OID_WDI_TASK_IHV +author: windows-driver-content +description: OID_WDI_TASK_IHV is used to start an IHV-initiated task. +ms.assetid: 2F18A92D-D658-4454-874F-7DC3B6F8F453 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_IHV Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_IHV + + +OID\_WDI\_TASK\_IHV is used to start an IHV-initiated task. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | Priority depends on IHV-requested settings. | 10 | + +  + +The task is initiated by the sending [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST](ndis-status-wdi-indication-ihv-task-request.md), and is prioritized based on the value requested by the IHV. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_IHV\_TASK\_DEVICE\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/dn926313) | | X | The context data provided by the IHV component. This is forwarded from [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_ TASK\_REQUEST](ndis-status-wdi-indication-ihv-task-request.md). | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_COMPLETE](ndis-status-wdi-indication-ihv-task-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_IHV%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-open.md b/windows-driver-docs-pr/network/oid-wdi-task-open.md new file mode 100644 index 0000000000..3bba57aa7c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-open.md @@ -0,0 +1,68 @@ +--- +title: OID_WDI_TASK_OPEN +author: windows-driver-content +description: OID_WDI_TASK_OPEN requests that the IHV component initializes the adapter. +ms.assetid: f4a77e08-1a1e-4d75-a559-a5cb01d825ee +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_OPEN Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_OPEN + + +OID\_WDI\_TASK\_OPEN requests that the IHV component initializes the adapter. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|---------|---------------|---------------------------------------|---------------------------------| +| Adapter | No | 1 | 2 | + +  + +Adapter initialization includes downloading firmware to the adapter, and setting up interrupts and other hardware resources. During initialization, this task is passed to the IHV using the OpenAdapterHandler handler registered by the IHV. On resume from low power state, this is passed to the IHV using OID\_WDI\_TASK\_OPEN. + +## Task parameters + + +None +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_OPEN\_COMPLETE](ndis-status-wdi-indication-open-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_OPEN%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-p2p-discover.md b/windows-driver-docs-pr/network/oid-wdi-task-p2p-discover.md new file mode 100644 index 0000000000..226c847b91 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-p2p-discover.md @@ -0,0 +1,154 @@ +--- +title: OID_WDI_TASK_P2P_DISCOVER +author: windows-driver-content +description: OID_WDI_TASK_P2P_DISCOVER is issued to the device to perform Wi-Fi Direct discovery. +ms.assetid: 9425a8d1-af68-488c-8a1e-a9b759f102cc +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_P2P_DISCOVER Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_P2P\_DISCOVER + + +OID\_WDI\_TASK\_P2P\_DISCOVER is issued to the device to perform Wi-Fi Direct discovery. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 6 | 15 | + +  + +The command contains properties which define either a specific set of Wi-Fi Direct devices to search for, or wildcard discovery. + +Wi-Fi Direct discovery is mutually exclusive from standard Wi-Fi scanning. While this task is running, broadcast probe requests shall not be sent without a "DIRECT-" SSID, or a specific GO SSID. These probe requests must also include all necessary Wi-Fi Direct IEs. + +The host may have search criteria which is not provided as part of the task parameters down to the device. The host may use the task abort mechanism if it has matched the required criteria, therefore it is important that the device can abort Wi-Fi Direct Discovery tasks quickly so as not to degrade scenario performance. + +When the task has been completed (either normally or due to an abort), the port should be in a good state such that another discover request can be issued on that port. + +## Task parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_P2P_DISCOVER_MODE](https://msdn.microsoft.com/library/windows/hardware/dn897878)Discovery mode information, such as scan type, count, and time between scans.
[WDI_TLV_SCAN_DWELL_TIME](https://msdn.microsoft.com/library/windows/hardware/dn898051)Scanning dwell time settings.
[WDI_TLV_P2P_DISCOVERY _CHANNEL_SETTINGS](https://msdn.microsoft.com/library/windows/hardware/dn897877)XXScan duration and list of channels to scan. When specified, the listen settings override those specified in WDI_TLV_SCAN_DWELL_TIME. If this list is empty, the port must scan on all supported channels and use the listen settings from WDI_TLV_SCAN_DWELL_TIME.
[WDI_TLV_SSID](https://msdn.microsoft.com/library/windows/hardware/dn898064)XXA list of SSIDs that the port should scan for. There can be multiple SSIDs in this list and one of them can be a wildcard. When doing an active scan on a channel, the port must send a probe request for each SSID in the list. If this list is empty, the port must scan for all SSIDs.
[WDI_TLV_P2P_SERVICE_NAME_HASH](https://msdn.microsoft.com/library/windows/hardware/dn898009)XXA list of Service Hash names to be queried. Required if WDI_P2P_SERVICE_DISCOVERY_TYPE_SERVICE_NAME_ONLY or WDI_P2P_SERVICE_DISCOVERY_TYPE_ASP2_SERVICE_NAME_ONLY is specified.
[WDI_TLV_VENDOR_SPECIFIC_IE](https://msdn.microsoft.com/library/windows/hardware/dn898076)XOne or more IEs that must be included in the probe requests sent by the port. These IEs are not used for passive scan.
[WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY](https://msdn.microsoft.com/library/windows/hardware/mt269140)XXAn optional list of Service Information Discovery Entries to be queried. This is required if WDI_P2P_SERVICE_DISCOVERY_TYPE_SERVICE_INFORMATION is specified. The driver is expected to perform a P2P service discovery over probe request/response using the service name hash. For each service entry that contains service information, the driver is expected to perform an ANQP query request/response to query the service information.

[WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY](https://msdn.microsoft.com/library/windows/hardware/mt769912)

X

X

Added in Windows 10, version 1607, WDI version 1.0.21.

+

An optional list of ASP2 Service Information Discovery Entries to be queried. This is required if WDI_P2P_SERVICE_DISCOVERY_TYPE_ASP2_SERVICE_INFORMATION is specified. The driver is expected to perform a P2P service discovery over probe request/response using the service name hash. For each service entry that contains service information, the driver is expected to perform an ANQP query request/response to query the service information.

[WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/mt769913)

X

Added in Windows 10, version 1607, WDI version 1.0.21.

+

Specifies whether the probe request should include the Listen Channel attribute during discovery.

+ +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_P2P\_DISCOVERY\_COMPLETE](ndis-status-wdi-indication-p2p-discovery-complete.md) +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_P2P_DISCOVER%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-request-action-frame.md b/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-request-action-frame.md new file mode 100644 index 0000000000..9efc6d661e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-request-action-frame.md @@ -0,0 +1,133 @@ +--- +title: OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME +author: windows-driver-content +description: OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME is issued to the device to send a Wi-Fi Direct Public Action Frame Request. +ms.assetid: bd8a746e-7d47-44c1-ad05-a452ce00749f +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME + + +OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME is issued to the device to send a Wi-Fi Direct Public Action Frame Request. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 3 | 5 | + +  + +This command is different than [OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-p2p-send-response-action-frame.md), which is a significantly more time-sensitive operation. + +When the device receives an acknowledgment for a request frame, it shall dwell on the same channel for 100ms and indicate any Wi-Fi Direct Public Action Frames it receives to the host. + +While the maximum timeout has not expired, the device shall retry sending the Wi-Fi Direct Public Action frame to the remote device on the remote device’s listen channel. + +The task is complete either when the local device receives an acknowledgment from the remote device for the action frame that was sent, the timeout expires, or the host aborts the operation. The device may indicate task completion after the same-channel dwell time has expired. + +The host may decide to abort this operation and continue/retry the Wi-Fi Direct action frame exchange, so it is important that the device is able to abort this operation quickly. + +## Task parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_P2P_SEND_ACTION_ REQUEST_FRAME_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn898001)Parameters such as action frame type, device address of target peer adapter, and dialog token.
[WDI_TLV_P2P_GO_ NEGOTIATION_REQUEST_INFO](https://msdn.microsoft.com/library/windows/hardware/dn897937)XGO Negotiation Request Parameters. THe port shall only examine this structure if wfdRequestFrameType is a GO Negotiation request.
[WDI_TLV_P2P_INVITATION_REQUEST_INFO](https://msdn.microsoft.com/library/windows/hardware/dn897963)XInvitation Request Parameters. The port shall only examine this structure if wfdRequestFrameType is an Invitation request.
[WDI_TLV_P2P_PROVISION_ DISCOVERY_REQUEST_INFO](https://msdn.microsoft.com/library/windows/hardware/dn897980)XProvision Discovery Request Parameters. The port shall only examine this structure if wfdRequestFrameType is an Provision Discovery request.
[WDI_TLV_BSS_ENTRY](https://msdn.microsoft.com/library/windows/hardware/dn926162)

The device discovery entry as returned by the Wi-Fi Direct Discovery task from the port.

+

This is provided so the port does not need to remember its discovery database in order to send Wi-Fi Direct Action Frame Requests to remote Wi-Fi Direct devices without requiring a discovery.

[WDI_TLV_VENDOR_SPECIFIC_IE](https://msdn.microsoft.com/library/windows/hardware/dn898076)XOne or more IEs that must be included in the frame sent by the port.
+ +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-response-action-frame.md b/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-response-action-frame.md new file mode 100644 index 0000000000..9d82f6a031 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-p2p-send-response-action-frame.md @@ -0,0 +1,96 @@ +--- +title: OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME +author: windows-driver-content +description: OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME is issued to the IHV component to send a Wi-Fi Direct Public Action Frame Request to a peer. +ms.assetid: 5cb57f20-ef9d-4e79-9b4b-8cf939221d47 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME + + +OID\_WDI\_TASK\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME is issued to the IHV component to send a Wi-Fi Direct Public Action Frame Request to a peer. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 3 | 5 | + +  + +When port receives an acknowledgment for a request frame, it shall dwell on the same channel for 100ms and indicate any Wi-Fi Direct Public Action Frames it receives to the host. + +This task is time sensitive. The Wi-Fi Direct specification requires that sending Wi-Fi Direct action responses are only serviced within 100 milliseconds of receiving this packet. + +While the maximum timeout has not expired, the port shall retry sending the Wi-Fi Direct to the remote device on the appropriate channel as defined by the following table. The table defines the explicit channel requirements for where to send the packets when the command is issued. The general rule is that the response packet shall be sent out on the same channel as the prior request. + +| Response Action Frame Type | Target Transmit Channel | +|------------------------------|-------------------------------------------------------| +| GO Negotiation Response | Local Listen Channel | +| GO Negotiation Confirmation | Remote Listen Channel | +| Invitation Response | Local Listen or Local GO Operational Channel | +| Provision Discovery Response | Local Listen Channel or Remote GO Operational Channel | + +  + +The task is complete either when local device receives an acknowledgment from the remote device for the action frame that was sent, the timeout expires, or the host aborts the operation. The device may indicate task completion after the same-channel dwell time has expired. + +The host may decide to abort this operation and continue/retry the Wi-Fi Direct action frame exchange, so it is important that the device is able to abort this operation quickly. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_ACTION\_FRAME\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn897859) | | | Parameters such as action frame type, device address of target peer adapter, and dialog token. | +| [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897942) | | X | GO Negotiation Response Parameters. The port shall only examine this structure if wfdRequestFrameType is a GO Negotiation Response. | +| [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897880) | | X | GO Negotiation Confirmation Parameters. The port shall only examine this structure if wfdRequestFrameType is a GO Negotiation Confirmation. | +| [**WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897968) | | X | Invitation Response Parameters. The port shall only examine this structure if wfdRequestFrameType is an Invitation Response. | +| [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897983) | | X | Provision Discovery Response Parameters. The port shall only examine this structure if wfdRequestFrameType is an Provision Discovery Response. | +| [**WDI\_TLV\_P2P\_INCOMING\_FRAME\_INFORMATION**](https://msdn.microsoft.com/library/windows/hardware/dn897957) | | | Information that was indicated from the previously received P2P Action Frame. The received indication is provided back to the port. | +| [**WDI\_TLV\_VENDOR\_SPECIFIC\_IE**](https://msdn.microsoft.com/library/windows/hardware/dn898076) | | X | One or more IEs that must be included in the frame sent by the port. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-roam.md b/windows-driver-docs-pr/network/oid-wdi-task-roam.md new file mode 100644 index 0000000000..2312ed8288 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-roam.md @@ -0,0 +1,86 @@ +--- +title: OID_WDI_TASK_ROAM +author: windows-driver-content +description: OID_WDI_TASK_ROAM requests that the adapter tries to roam from the currently connected AP to a new one. +ms.assetid: 22976d21-9212-4915-ab7a-fcc15d228db1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_ROAM Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_ROAM + + +OID\_WDI\_TASK\_ROAM requests that the adapter tries to roam from the currently connected AP to a new one. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|-----------------------------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. If aborted after disassociation, it must be followed by a dot11 reset. | 4 | 10 | + +  + +The Microsoft component provides the list of preferred BSS entries that the adapter should consider for roaming. + +When this command issued, if its currently associated, the adapter would need to disassociate from the currently connected AP and then roam to the new AP. In this case it would first indicate disassociation for the old AP, then indicate association result for the new AP and then complete the task. + +It can also determine not to perform the roam and stay connected to the current AP. In this case it would only complete the task without any association or disassociation indications. + +The scan and AP selection requirements for this task are same as for [OID\_WDI\_TASK\_CONNECT](oid-wdi-task-connect.md). + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_CONNECT\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926266) | | | Connection parameters. | +| [**WDI\_TLV\_CONNECT\_BSS\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn926264) | X | | The preferred list of candidate connect BSS entries. The port should attempt to connect to these BSS entries until the list is exhausted, or the connection completed successfully. The port can reprioritize the entries if needed. If the adapter has set the Connect BSS Selection Override bit, then it can pick a BSS that is not in this list as long as it follows the Allowed/Disallowed list requirements. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_ROAM\_COMPLETE](ndis-status-wdi-indication-roam-complete.md) +## Unsolicited indications + + +[NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_RESULT](ndis-status-wdi-indication-association-result.md) +[NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION](ndis-status-wdi-indication-disassociation.md) +[NDIS\_STATUS\_WDI\_INDICATION\_FT\_ASSOC\_PARAMS\_NEEDED](ndis-status-wdi-indication-ft-assoc-params-needed.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_ROAM%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-scan.md b/windows-driver-docs-pr/network/oid-wdi-task-scan.md new file mode 100644 index 0000000000..20bbddf216 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-scan.md @@ -0,0 +1,120 @@ +--- +title: OID_WDI_TASK_SCAN +author: windows-driver-content +description: OID_WDI_TASK_SCAN requests a survey of BSS networks. The port performs a scan according to the requirements of the IEEE 802.11 specification. +ms.assetid: c4131010-20f2-45a4-8fb9-5a1e3e9735e5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_SCAN Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_SCAN + + +OID\_WDI\_TASK\_SCAN requests a survey of BSS networks. The port performs a scan according to the requirements of the IEEE 802.11 specification. + + ++++++ + + + + + + + + + + + + + + + + +
ObjectAbort capableDefault priority (host driver policy)Normal execution time (seconds)
PortYes. The port must be in a clean state after the abort.

6 (background scan)

+

5 (user-initiated scan)

4
+ +  + +A task started message containing a [**WDI\_TLV\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn898068) is indicated once the port has started the scan and is ready to receive other commands. + +Once a scan is started when enabled by LiveUpdatesNeeded, the port must provide incremental updates (using unsolicited indications of [NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md)) about discovered BSS entries. BSS entries that had previously been discovered but were not found by the port in the current scan should not be reported by the port. For power and performance reasons, the port should throttle indications and send updates to the host only when it has discovered 3 or more, or when it has discovered less than 3 entries but has not reported them to the host for more than 500 milliseconds. After the scan is completed, if the adapter does not manage BSS entries, it does not need to remember the BSS entries that it has discovered. Once the scan operation has finished, the port must send the task complete notification to the operating system and stop reporting BSS entries to the host. The scan command is used for finding legacy (non-Wi-Fi Direct networks) and the port should not include the Wi-Fi Direct IEs in the probe requests. + +If the adapter does not manage BSS entries, the host remembers the BSS entries reported by the port from a scan for a finite period of time. It times out its cached entries and flushes them. If the adapter manages the BSS entries, it caches and times them out. The host may send the [OID\_WDI\_SET\_FLUSH\_BSS\_ENTRY](oid-wdi-set-flush-bss-entry.md) command to explicitly flush the entries. + +The host tracks BSS entries using their BSSID. If the port reports two BSS entries for the same BSSID, the host overwrites one with another. + +While the scan is ongoing, the port must maintain the existing connections (for example, Infrastructure or Wi-Fi Direct). If connections already exist, the port should scan a subset of channels at a time and in between subsets, provide the other connections access to the medium. During the scan, the host can submit packet send requests to any port on the adapter. + +In the indicated BSS entries, the port can include device specific context information. This context information is passed back to the device if the port is asked to connect to that BSS entry. However, this context may be cleared by the host automatically if the BSS entry is flushed. + +The scan command can be aborted. On receiving the abort command, the port should stop trying to find new BSS networks and complete the scan task as soon as possible. When the task has been completed (either normally or due to an abort), the port should be in a good state such that another scan can be issued on that port. + +The adapter must not violate regulatory restrictions when performing a scan. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](https://msdn.microsoft.com/library/windows/hardware/dn926153) | | | BSSID of the network to scan for. If this is the broadcast MAC address, the station scans for all BSSIDs. | +| [**WDI\_TLV\_SSID**](https://msdn.microsoft.com/library/windows/hardware/dn898064) | X | | A list of SSID list that the port should scan for. There can be multiple SSIDs in this list and one of them can be a wildcard. When doing an active scan on a channel, the port must send a probe request for each SSID in the list. If this list is empty, the port must scan for all SSIDs. | +| [**WDI\_TLV\_VENDOR\_SPECIFIC\_IE**](https://msdn.microsoft.com/library/windows/hardware/dn898076) | | X | One or more IEs that must be included in the probe requests sent by the port. These IEs are not used for passive scan. | +| [**WDI\_TLV\_SCAN\_MODE**](https://msdn.microsoft.com/library/windows/hardware/dn898052) | | | Scan mode parameters. | +| [**WDI\_TLV\_SCAN\_DWELL\_TIME**](https://msdn.microsoft.com/library/windows/hardware/dn898051) | | | Dwell time parameters. | +| [**WDI\_TLV\_BAND\_CHANNEL**](https://msdn.microsoft.com/library/windows/hardware/dn926144) | X | X | A list of recommended channels to scan. The adapter can perform a scan on a subset or superset of the channel list as long as it meets the Maximum Scan Time requirements. If this list is empty, the port must scan on all supported channels. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_SCAN\_COMPLETE](ndis-status-wdi-indication-scan-complete.md) +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) +This notification is used by the device to tell the host about updates to the BSS entries. It can be sent at any time. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_SCAN%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-send-ap-association-response.md b/windows-driver-docs-pr/network/oid-wdi-task-send-ap-association-response.md new file mode 100644 index 0000000000..b67447a17b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-send-ap-association-response.md @@ -0,0 +1,76 @@ +--- +title: OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE +author: windows-driver-content +description: OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE requests that the IHV component sends an Association Response to a peer device that has recently sent an association request. +ms.assetid: 8d19b009-db81-4b5e-ac63-5e6c5ad9727d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_SEND\_AP\_ASSOCIATION\_RESPONSE + + +OID\_WDI\_TASK\_SEND\_AP\_ASSOCIATION\_RESPONSE requests that the IHV component sends an Association Response to a peer device that has recently sent an association request. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 3 | 1 | + +  + +If the send fails for any reason, an empty [NDIS\_STATUS\_WDI\_INDICATION\_SEND\_AP\_ASSOCIATION\_RESPONSE\_COMPLETE](ndis-status-wdi-indication-send-ap-association-response-complete.md) is expected, with the correct status included in the populated header. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn926137) | | | Association response parameters. | +| [**WDI\_TLV\_VENDOR\_SPECIFIC\_IE**](https://msdn.microsoft.com/library/windows/hardware/dn898076) | | X | Additional IEs that the port must append to Association Response IE set before sending response to peer adapter. | +| [**WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn926315) | | | Information about the incoming association request. | +| [**WDI\_TLV\_WFD\_ASSOCIATION\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/mt269148) | | X | The Status value to set when the association request is denied. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_SEND\_AP\_ASSOCIATION\_RESPONSE\_COMPLETE](ndis-status-wdi-indication-send-ap-association-response-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-send-request-action-frame.md b/windows-driver-docs-pr/network/oid-wdi-task-send-request-action-frame.md new file mode 100644 index 0000000000..ac5e0519b0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-send-request-action-frame.md @@ -0,0 +1,82 @@ +--- +title: OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME +author: windows-driver-content +description: OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME requests that the device sends an Action Frame Request to another device. +ms.assetid: CAC86B50-BE85-4650-B6D3-738B4E960587 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_SEND\_REQUEST\_ACTION\_FRAME + + +OID\_WDI\_TASK\_SEND\_REQUEST\_ACTION\_FRAME requests that the device sends an Action Frame Request to another device. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 3 | 5 | + +  + +This command is different from [OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME](oid-wdi-task-send-response-action-frame.md), which is a significantly more time-sensitive operation. + +When the device receives an acknowledgment for a request frame, it shall dwell on the same channel for the Post-ACK Dwell time as specified in the Task Parameters, and shall indicate to the host any Action Frames it receives and doesn’t handle itself. + +As long as the maximum timeout has not expired, the device shall retry sending the Public Action frame to the remote device on the remote device’s listen channel. + +The task is complete either when local device receives an acknowledgment from the remote device for the action frame that was sent, the timeout expires, or the host aborts the operation. The device may indicate task completion after the same-channel dwell time has expired. + +The host may decide to abort this operation and continue/retry the public action frame exchange, so it is important that the device is able to abort this operation quickly. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------| +| [**WDI\_TLV\_SEND\_ACTION\_FRAME\_REQUEST\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898053) | | | Parameters for sending an Action Frame Request. | +| [**WDI\_TLV\_ACTION\_FRAME\_BODY**](https://msdn.microsoft.com/library/windows/hardware/dn926118) | | | The Action Frame body. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-send-request-action-frame-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-send-response-action-frame.md b/windows-driver-docs-pr/network/oid-wdi-task-send-response-action-frame.md new file mode 100644 index 0000000000..22f83c1852 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-send-response-action-frame.md @@ -0,0 +1,80 @@ +--- +title: OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME +author: windows-driver-content +description: OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME requests that the IHV component sends Response Action Frames. +ms.assetid: DA2FF006-BA81-48B9-8AAD-694818E78AEF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME + + +OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME requests that the IHV component sends Response Action Frames. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The port must be in a clean state after the abort. | 3 | 5 | + +  + +This task is time sensitive and must be serviced within 100 milliseconds of receiving this packet. + +While the maximum timeout has not expired, the port shall retry sending the frame to the remote device on the specified channel. + +The task is complete either when local device receives an acknowledgment from the remote device for the action frame that was sent, the timeout expires, or the host aborts the operation. The device may indicate task completion after the same-channel dwell time has expired. + +The host may decide to abort this operation and continue/retry the action frame exchange, so it is important that the device is able to abort this operation quickly. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------| +| [**WDI\_TLV\_SEND\_ACTION\_FRAME\_RESPONSE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898054) | | | Parameters for sending an Action Frame Response. | +| [**WDI\_TLV\_ACTION\_FRAME\_BODY**](https://msdn.microsoft.com/library/windows/hardware/dn926118) | | | The Action Frame body. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-send-response-action-frame-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-set-radio-state.md b/windows-driver-docs-pr/network/oid-wdi-task-set-radio-state.md new file mode 100644 index 0000000000..a819f18f60 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-set-radio-state.md @@ -0,0 +1,83 @@ +--- +title: OID_WDI_TASK_SET_RADIO_STATE +author: windows-driver-content +description: OID_WDI_TASK_SET_RADIO_STATE is used to set the Wi-Fi radio state for the adapter. +ms.assetid: d7981df2-d3e5-49fd-8414-ca350775828b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_SET_RADIO_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_SET\_RADIO\_STATE + + +OID\_WDI\_TASK\_SET\_RADIO\_STATE is used to set the Wi-Fi radio state for the adapter. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|---------|---------------|---------------------------------------|---------------------------------| +| Adapter | No | 1 | 1 | + +  + +The task must be completed only after the disconnect activity has been completed. + +The IHV component may also send unsolicited indications about radio state changes to the host. + +Before the host turns off the radio, it disconnects all peers and stops any Group Owner that is running. The adapter is not expected to remember the station/GO profile information across a radio OFF/ON transition. + +## Task parameters + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_RADIO\_STATE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898043) | | | The desired state of the radio. If this set to 1, the radio is enabled. If this is set to 0, the radio is turned off. | + +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_SET\_RADIO\_STATE\_COMPLETE](ndis-status-wdi-indication-set-radio-state-complete.md) +## Unsolicited indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_RADIO\_STATUS](ndis-status-wdi-indication-radio-status.md) +This indication is used to report changes in the radio state for the adapter. This is sent both when a software radio change is triggered by the host and when a hardware radio state change is detected by the adapter. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_SET_RADIO_STATE%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-start-ap.md b/windows-driver-docs-pr/network/oid-wdi-task-start-ap.md new file mode 100644 index 0000000000..71153a2503 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-start-ap.md @@ -0,0 +1,144 @@ +--- +title: OID_WDI_TASK_START_AP +author: windows-driver-content +description: OID_WDI_TASK_START_AP requests that the IHV component configures a port to start a Wi-Fi Direct Group Owner on the specified port. +ms.assetid: 647b039b-eb9a-43e7-9027-15a55df62c79 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_START_AP Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_START\_AP + + +OID\_WDI\_TASK\_START\_AP requests that the IHV component configures a port to start a Wi-Fi Direct Group Owner on the specified port. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------------------------------------------|---------------------------------------|---------------------------------| +| Port | Yes. The abort must be followed by a dot11 reset. | 4 | 1 | + +  + +During initialization, the driver sets the GO on 5GHz band capability in [**WDI\_TLV\_P2P\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/dn897865) to indicate whether it can start the access point on the 5 GHz band. + +If GO on 5 GHz band support is set, the adapter should start the AP on the Advertised Operating channel, and if that fails, it should try the list specified in the AP band channel list parameter. The operating system will provide a hint to the driver about whether this AP would provide internet connectivity by setting the **DOT11\_WFD\_GROUP\_CAPABILITY\_CROSS\_CONNECTION\_SUPPORTED** flag in [**WDI\_TLV\_P2P\_GROUP\_OWNER\_CAPABILITY**](https://msdn.microsoft.com/library/windows/hardware/dn897954). + +If **MustUseSpecifiedChannel** in [**WDI\_TLV\_START\_AP\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898065) is specified, the AP may return one of the following errors if it is unable to start the AP on the specified band/channel(s). + +| | | +|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------| +| **NDIS\_STATUS\_DOT11\_AP\_CHANNEL\_CURRENTLY\_NOT\_AVAILABLE** | Unable to start the AP on the specified channel(s) right now . Retry on the specified channel(s) later. | +| **NDIS\_STATUS\_DOT11\_AP\_BAND\_CURRENTLY\_NOT\_AVAILABLE** | Unable to start the AP on the specified band(s) right now. Retry on the specified band(s) later. | +| **NDIS\_STATUS\_DOT11\_AP\_CHANNEL\_NOT\_ALLOWED** | Unable to start the AP on the specified channel(s) due to regulatory reasons. | +| **NDIS\_STATUS\_DOT11\_AP\_BAND\_NOT\_ALLOWED** | Unable to start the AP on the specified band(s) due to regulatory reasons. | + +  + +## Task parameters + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TLVMultiple TLV instances allowedOptionalDescription
[WDI_TLV_SSID](https://msdn.microsoft.com/library/windows/hardware/dn898062)The SSID to be used by the AP.
[WDI_TLV_START_AP_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn898065)Additional parameters for this task.
[WDI_TLV_AUTH_ALGO_LIST](https://msdn.microsoft.com/library/windows/hardware/dn926141)The list of authentication algorithms that the connection can use.
[WDI_TLV_MULTICAST_CIPHER_ALGO_LIST](https://msdn.microsoft.com/library/windows/hardware/dn897847)The list of multicast cipher algorithms that the connection can use.
[WDI_TLV_UNICAST_CIPHER_ALGO_LIST](https://msdn.microsoft.com/library/windows/hardware/dn898074)The list of multicast cipher algorithms that the connection can use.
[WDI_TLV_P2P_CHANNEL_NUMBER](https://msdn.microsoft.com/library/windows/hardware/dn897869)XIf specified, this defines the operating channel determined in group formation. This may only be specified when the operating mode is Wi-Fi Direct GO.
[WDI_TLV_AP_BAND_CHANNEL](https://msdn.microsoft.com/library/windows/hardware/mt593242)XXAdded in Windows 10, version 1511, WDI version 1.0.10. +

Optional list of bands and channels to start the access point on. If MustUseSpecifiedChannels is set to 1, the AP can only be started from this list. If it is not set, this list is meant to be a recommendation of channels that the firmware can pick from, and it may pick another channel if it is not possible to start the AP on any of the specified channels.

+ +  + +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_START\_AP\_COMPLETE](ndis-status-wdi-indication-start-ap-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_START_AP%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-task-stop-ap.md b/windows-driver-docs-pr/network/oid-wdi-task-stop-ap.md new file mode 100644 index 0000000000..7286a5b016 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-task-stop-ap.md @@ -0,0 +1,66 @@ +--- +title: OID_WDI_TASK_STOP_AP +author: windows-driver-content +description: OID_WDI_TASK_STOP_AP requests that the IHV component disconnects all connected clients on the specified port and stops beaconing and responding to probe requests. AP configuration and MIB attributes are preserved. +ms.assetid: b7df1d2f-fed4-4079-8a2d-3f691a52ad52 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TASK_STOP_AP Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TASK\_STOP\_AP + + +OID\_WDI\_TASK\_STOP\_AP requests that the IHV component disconnects all connected clients on the specified port and stops beaconing and responding to probe requests. AP configuration and MIB attributes are preserved. + +| Object | Abort capable | Default priority (host driver policy) | Normal execution time (seconds) | +|--------|---------------|---------------------------------------|---------------------------------| +| Port | No | 2 | 1 | + +  + +## Task parameters + + +None +## Task completion indication + + +[NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP\_COMPLETE](ndis-status-wdi-indication-stop-ap-complete.md) +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TASK_STOP_AP%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wdi-tcp-rsc-statistics.md b/windows-driver-docs-pr/network/oid-wdi-tcp-rsc-statistics.md new file mode 100644 index 0000000000..44d80c3f0a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wdi-tcp-rsc-statistics.md @@ -0,0 +1,71 @@ +--- +title: OID_WDI_TCP_RSC_STATISTICS +author: windows-driver-content +description: OID_WDI_TCP_RSC_STATISTICS is a get command that queries the RSC statistics of the hardware. +ms.assetid: 9079DD03-597D-4B6D-8515-ECF5DAC2A41A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - OID_WDI_TCP_RSC_STATISTICS Network Drivers Starting with Windows Vista +--- + +# OID\_WDI\_TCP\_RSC\_STATISTICS + + +OID\_WDI\_TCP\_RSC\_STATISTICS is a get command that queries the RSC statistics of the hardware. + +| Scope | Set serialized with task | Normal execution time (seconds) | +|-------|--------------------------|---------------------------------| +| Port | No | 1 | + +  + +## Get property parameters + + +No additional parameters. The data in the header is sufficient. +## Get property results + + +| TLV | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------| +| [**WDI\_TLV\_TCP\_RSC\_STATISTICS\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/dn898070) | | | TCP RSC statistics of the hardware. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WDI_TCP_RSC_STATISTICS%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-auth-challenge.md b/windows-driver-docs-pr/network/oid-wwan-auth-challenge.md new file mode 100644 index 0000000000..71cc8d3902 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-auth-challenge.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_AUTH\_CHALLENGE +author: windows-driver-content +description: OID\_WWAN\_AUTH\_CHALLENGE sends an authentication challenge to the MB device, or Subscriber Identity Module (SIM) card, to obtain the response from the SIM.n NDIS\_STATUS\_WWAN\_AUTHENTICATION\_RESPONSE status notification containing an NDIS\_WWAN\_AUTHENTICATION\_RESPONSE structure to provide the authentication keys requested based on challenges by the caller when completing query requests. +ms.assetid: C39300F2-DF14-4DA8-9BD2-83593CC29837 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_AUTH_CHALLENGE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_AUTH\_CHALLENGE + + +OID\_WWAN\_AUTH\_CHALLENGE sends an authentication challenge to the MB device, or Subscriber Identity Module (SIM) card, to obtain the response from the SIM. + +Set requests are not supported. + +This is an optional OID. When miniport drivers implement it, they must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an NDIS\_STATUS\_WWAN\_AUTHENTICATION\_RESPONSE status notification containing an NDIS\_WWAN\_AUTHENTICATION\_RESPONSE structure to provide the authentication keys requested based on challenges by the caller when completing query requests. + +Remarks +------- + +When processing this OID, miniport drivers can access the SIM card, but should not access the provider network. This OID must work even in Radio OFF or Airplane Mode. + +OID\_WWAN\_AUTH\_CHALLENGE supports both second-generation and third-generation mobile networks. SIM specifies an authentication mechanism that is based on the GSM authentication and key agreement primitives, which is a second-generation mobile network standard. AKA and AKA' uses the third-generation Authentication and Key Agreement mechanism, specified for Universal Mobile Telecommunications System (UMTS) in \[TS33.102\] and for CDMA2000 in \[S.S0055-A\] depending on the capabilities of the device. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support returning one or all authentication methods. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_AUTH_CHALLENGE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-connect.md b/windows-driver-docs-pr/network/oid-wwan-connect.md new file mode 100644 index 0000000000..5f510f244b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-connect.md @@ -0,0 +1,104 @@ +--- +title: OID\_WWAN\_CONNECT +author: windows-driver-content +description: OID\_WWAN\_CONNECT activates or deactivates a particular packet context and reads the activation state of a context. +ms.assetid: 51be35fe-750b-4c2b-aab3-a9df59711f7d +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_CONNECT Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_CONNECT + + +OID\_WWAN\_CONNECT activates or deactivates a particular packet context and reads the activation state of a context. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_CONTEXT\_STATE**](ndis-status-wwan-context-state.md) status notification containing an [**NDIS\_WWAN\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567906) structure that indicates the Packet Data Protocol (PDP) context state of the MB device regardless of completing set or query requests. + +Callers requesting to set the Packet Data Protocol (PDP) context state of the MB device provide an [**NDIS\_WWAN\_SET\_CONTEXT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567920) structure to the miniport driver with the appropriate information. + +Remarks +------- + +For more information about using this OID, see [WWAN Packet Context Management](https://msdn.microsoft.com/library/windows/hardware/ff559086). + +This object activates or deactivates a particular packet context and reads the activation state of a context. The miniport driver must send appropriate event notifications whenever the activation state changes. + +This object is called only if the miniport driver is in a register state of **WwanRegisterStateHome**, **WwanRegisterStatePartner**, or **WwanRegisterStateRoaming**. When packet service is active, the device must also be in an attach state of **WwanPacketServiceStateAttached**. + +Both set and query operations are supported for this object. + +- Processing of a set request requires network access but not SIM access. + +- Processing of a query request does not require access to network or the SIM. + +The data structure for this OID is NDIS\_WWAN\_SET\_CONTEXT\_STATE. The miniport driver issues a status indication of NDIS\_STATUS\_WWAN\_CONTEXT\_STATE for both set and query requests. + +In this version of the driver model, the miniport driver attempts context activation only as instructed by the MB Service. (Miniport drivers may activate a context initiated by the network in later versions.) Miniport drivers must not automatically activate a context even after losing registration or a signal. If the access string is not provided in the activation request, a miniport driver should not attempt to provide a default string. Instead, it must proceed with activating the context with a blank access string. + +On the other hand, the miniport driver may deactivate a context as instructed by the MB service. This may occur when network connectivity has been lost for a period that exceeds the threshold of temporary loss of signal, or as part of a graceful shutdown or state cleanup. + +Since only one activated context is supported in this version, activating or deactivating a particular context amounts to setting up or tearing down the layer-2 MB connection. + +On set requests, the MB service furnishes both **ConnectionId** and **ActivationCommand** parameters in the WWAN\_CONTEXT\_STATE data structure. It instructs the miniport driver to activate or deactivate a packet context identified by **ConnectionId**, based on the **ActivationCommand** parameter value *WwanActivationCommandActivate* or *WwanActivationCommandDeactivate*. + +- If the service or subscription requires activation, the miniport driver should return error code WWAN\_STATUS\_SERVICE\_NOT\_ACTIVATED. The PDP-activation may not happen until the service or subscription is activated. All the emergency services might be available subject to the support from the device and the operator. The operating system might call the OID\_WWAN\_SERVICE\_ACTIVATION in response to this error code. + +- If the miniport driver receives a context activation request while another packet context is currently activated, it returns error code WWAN\_STATUS\_MAX\_ACTIVATED\_CONTEXTS. + +- If the miniport driver receives a context deactivation request but the context identified by **ConnectionId** is not currently activated, it returns error code WWAN\_STATUS\_CONTEXT\_NOT\_ACTIVATED. + +The miniport driver uses the following logic to determine the validity of AccessString, UserName, and Password settings from a set request: + +- If **ActivationCommand** is *WwanActivationCommandDeactivate*, the miniport driver should ignore the settings of these three parameters. The rest of the cases only consider the case when **ActivationCommand** is *WwanActivationCommandActivate*. + +Context activation persists across user logon and logoff. It is not per logon user. + +On query requests, the MB Service uses this object to find out the activation state. + +For response to query requests, miniport driver sends the NDIS\_STATUS\_WWAN\_CONTEXT\_STATE notification. + +**Important**  Note: + +  + +In rare, but specific circumstances, the MB Service on Windows 7 may attempt to auto-connect before connectivity to the Internet has been determined for pre-existing connections or during a momentary disruption in Internet connectivity of pre-existing connections. This could result in simultaneous MB and WLAN/Ethernet connections. For example, this can occur during system boot when MB and other connections are attempted simultaneously and the Network List Manager service is still attempting to determine the Internet connectivity of other connections using active and passive methods. It could also occur due to temporary outages in network infrastructure like a corporate proxy server or an ISP network. Thus, the MB Service may attempt to auto-connect to the internet regardless of whether the "Auto-connect only if no alternate Internet connection is available" option is selected. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[WWAN Packet Context Management](https://msdn.microsoft.com/library/windows/hardware/ff559086) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_CONNECT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-create-mac.md b/windows-driver-docs-pr/network/oid-wwan-create-mac.md new file mode 100644 index 0000000000..e532e52abe --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-create-mac.md @@ -0,0 +1,64 @@ +--- +title: OID\_WWAN\_CREATE\_MAC +author: windows-driver-content +description: OID\_WWAN\_CREATE\_MAC requests the miniport driver to create a new NDIS port. +ms.assetid: 4EF98858-86CD-409B-BE41-E57B24158609 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_CREATE_MAC Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_CREATE\_MAC + + +OID\_WWAN\_CREATE\_MAC requests the miniport driver to create a new NDIS port. Context activation requests for the additional PDP context will be sent on this new NDIS port. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later completing the request with the [**NDIS\_WWAN\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn449747) structure that indicates the NDIS port number and MAC address associated with the port. + +Query requests are not supported. + +Remarks +------- + +Miniport drivers must process requests to create (activate) new NDIS ports asynchronously in order to prevent deadlocks. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 8.1 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_MAC\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn449747) + +[OID\_WWAN\_DELETE\_MAC](oid-wwan-delete-mac.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_CREATE_MAC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-delete-mac.md b/windows-driver-docs-pr/network/oid-wwan-delete-mac.md new file mode 100644 index 0000000000..f127991e5c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-delete-mac.md @@ -0,0 +1,68 @@ +--- +title: OID\_WWAN\_DELETE\_MAC +author: windows-driver-content +description: OID\_WWAN\_DELETE\_MAC requests the miniport driver to delete the NDIS port specified in the NDIS\_WWAN\_MAC\_INFO parameter. +ms.assetid: 3C992E0D-132E-4687-B38E-31409E1A9F54 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DELETE_MAC Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DELETE\_MAC + + +OID\_WWAN\_DELETE\_MAC requests the miniport driver to delete the NDIS port specified in the NDIS\_WWAN\_MAC\_INFO parameter. The NDIS port should have been created earlier using [OID\_WWAN\_CREATE\_MAC](oid-wwan-create-mac.md). + +Miniport drivers must process the set request asynchronously, initially returning NDIS\_STATUS\_PENDING to the original request, and later completing the request with NDIS\_STATUS\_SUCCESS. + +Query requests are not supported. + +Remarks +------- + +Miniport drivers must process requests to delete (deactivate) NDIS ports asynchronously in order to prevent deadlocks. + +OID\_WWAN\_DELETE\_MAC requests sent to delete the default port will fail with the NDIS status error code NDIS\_STATUS\_INVALID\_PORT. + +Upon receiving an OID\_WWAN\_DELETE\_MAC request, miniport drivers should deactivate the PDP context associated with the port, if it has not already been deactivated. This is because a surprise removal event could occur. Deactivating the PDP context at such time will ensure that the modem and the miniport driver remain in a good state. + +When the driver receives a surprise removal, the driver blocks and cancels all further OIDs. This means that the driver filters out OID\_WWAN\_DELETE\_MAC even though Windows sends a call with OID\_WWAN\_DELETE\_MAC as part of the [*FILTER\_DETACH*](https://msdn.microsoft.com/library/windows/hardware/ff549918) call. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 8.1 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_CREATE\_MAC](oid-wwan-create-mac.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DELETE_MAC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-caps-ex.md b/windows-driver-docs-pr/network/oid-wwan-device-caps-ex.md new file mode 100644 index 0000000000..cb7290d653 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-caps-ex.md @@ -0,0 +1,82 @@ +--- +title: OID\_WWAN\_DEVICE\_CAPS\_EX +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_CAPS\_EX is a similar but different OID from OID\_WWAN\_DEVICE\_CAPS. +ms.assetid: BE664B41-3FE7-4E93-8739-12BD2F0AE5B8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_CAPS_EX Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_CAPS\_EX + + +OID\_WWAN\_DEVICE\_CAPS\_EX is a similar but different OID from [OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md). OID\_WWAN\_DEVICE\_CAPS\_EX is a per-executor OID. This OID serves to indicate the hardware’s device/executor capability, including the capability on extended optional features such as LTE attach APN configuration. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request before later sending an [**NDIS\_STATUS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782396) status notification containing an [**NDIS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782401) structure, which in turn contains a [**WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt799889) structure, to provide information about the device's capability. + +The following diagram illustrates a query request. + +![executor capability query](images/multi-SIM_6_executorCapabilityQuery.png) + +Set requests are not applicable. + +Remarks +------- + +It is critical for the driver to report service extension capability as a whole including from the driver to the actual device. If a driver supports a service but it is not supported by the underlying hardware, then the service capabilities should be marked as FALSE. + +OID\_WWAN\_DEVICE\_CAPS\_EX is also used to retrieve each executor’s capability. This OID is the same in structure as existing [OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md) but with the addition of **Executor ID**. A miniport driver should report the highest OID version it supports. + +Just as with [OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md), the parameters in this OID are not expected to change due to SIM cards but rather represent the modem’s RF capability of the selected executor. A physical hardware modem may have multiple executors and thus may have multiple interfaces that support OID\_WWAN\_DEVICE\_CAPS\_EX. + +For possible future updates, if the OS’s requested version is newer than the device-supported version, the device should return the newest version of the OID structure it supports. If the OS’s requested version is older than the latest one supported by the device, then the device should return the version matching the OS’s specification. It is a requirement for IHVs to make sure all revisions of OID\_WWAN\_DEVICE\_CAPS\_EX are supported for backwards compatibility and legacy support. + +Unlike other OIDs new to Windows 10 Version 1703 that are only required if the modem supports multi-SIM/multi-executors, this OID must be implemented for modems that would like to support any Microsoft-defined service extensions starting in Windows 10 Version 1703. + +Versions of Windows prior to Windows 10 Version 1703 may still use the existing [OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md); their behavior with multi-executor capable modems is not a supported scenario. IHVs must define this behavior. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782396) + +[**NDIS\_WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt782401) + +[**WWAN\_DEVICE\_CAPS\_EX**](https://msdn.microsoft.com/library/windows/hardware/mt799889) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_CAPS_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-caps.md b/windows-driver-docs-pr/network/oid-wwan-device-caps.md new file mode 100644 index 0000000000..99eff0b9a1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-caps.md @@ -0,0 +1,329 @@ +--- +title: OID\_WWAN\_DEVICE\_CAPS +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_CAPS returns the capabilities of the MB device, including the cellular technology it supports, the classes of packet data it supports, the radio frequencies it supports, the type of voice service it provides, and whether it uses a Subscriber Identity Module (SIM card). The supported cellular technology and whether the device uses a SIM are particularly important because network provider selection and SIM user interfaces depend on the values of these two capabilities. The manufacturer and firmware revision are returned as optional fields. Set requests are not supported. Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a NDIS\_STATUS\_WWAN\_DEVICE\_CAPS status notification containing a NDIS\_WWAN\_DEVICE\_CAPS structure that indicates the capabilities of the MB device when completing query requests. +ms.assetid: bcf04d0b-70f3-48b7-a505-c82e50edadb2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_CAPS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_CAPS + + +OID\_WWAN\_DEVICE\_CAPS returns the capabilities of the MB device, including the cellular technology it supports, the classes of packet data it supports, the radio frequencies it supports, the type of voice service it provides, and whether it uses a Subscriber Identity Module (SIM card). The supported cellular technology and whether the device uses a SIM are particularly important because network provider selection and SIM user interfaces depend on the values of these two capabilities. The manufacturer and firmware revision are returned as optional fields. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567845) status notification containing a [**NDIS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567907) structure that indicates the capabilities of the MB device when completing query requests. + +Remarks +------- + +Starting with Windows 8, the MB driver model has been updated to version 2.0. Windows 8 miniport drivers should set the **Header.Revision** member of the [**NDIS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567907) structure to **NDIS\_WWAN\_DEVICE\_CAPS\_REVISION\_2** for *query* requests. Windows 7 miniport drivers should set the **Header.Revision** member of the **NDIS\_WWAN\_DEVICE\_CAPS** structure to **NDIS\_WWAN\_DEVICE\_CAPS\_REVISION\_1** for *query* requests. + +For more information about using this OID, see [WWAN Driver Initialization Procedure](https://msdn.microsoft.com/library/windows/hardware/ff557186). + +Miniport drivers can access device memory when processing query operations, but should not access the provider network or the Subscriber Identity Module (SIM card). + +Many "world-wide" MB devices today support multiple frequency bands because the frequency bands for 2.5G/3G vary from country to country. The list of all the radio frequencies specified in the 3GPP standards (for GSM-based networks) and 3GPP2 standards (for CDMA-based networks) is shown in the following tables. Both standards adopt a similar band classification scheme. + +**3GPP (GSM-based) Frequency Band Classes** + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
3GPP bandDesignated spectrumIndustry nameUplink (MS to BTS)Downlink (BTS to MS)Regions

Band I

UMTS2100

IMT

1920-1980

2110-2170

Europe, Korea, Japan, China

Band II

UMTS1900

PCS1900

1850-1910

1930-1990

North America, LATAM

Band III

UMTS1800

DCS1800

1710-1785

1805-1880

Europe, China

Band IV

AWS

AWS, 1.7/2.1

1710-1755

2110-2155

North America, LATAM

Band V

UMTS850

GSM850

824-849

869-894

North America, LATAM

Band VI

UMTS800

UMTS800

830-840

875-885

Japan

Band VII

UMTS2600

UMTS2600

2500-2570

2620-2690

Europe

Band VIII

UMTS900

EGSM900

880-915

925-960

Europe, China

Band IX

UMTS1700

UMTS1700

1750-1785

1845-1880

Japan

Band X

1710-1770

2110-2170

+ +  + +**3GPP2 (CDMA-based) Frequency Band Classes** + +3GPP band +Industry name +Uplink (MS to BTS) +Downlink (BTS to MS) +Band 0 + +800MHz Cellular + +824.025-844.995 + +869.025-889.995 + +Band I + +1900MHz Band + +1850-1910 + +1930-1990 + +Band II + +TACS Band + +872.025-914.9875 + +917.0125-959.9875 + +Band III + +JTACS Band + +887.0125-924.9875 + +832.0125-869.9875 + +Band IV + +Korean PCS Band + +1750 - 1780 + +1840 - 1870 + +Band V + +450 MHz Band + +410 - 483.475 + +420 - 493.475 + +Band VI + +2 GHz Band + +1920 - 1979.950 + +2110 - 2169.950 + +Band VII + +700 MHz Band + +776 - 794 + +746 - 764 + +Band VIII + +1800 MHz Band + +1710 - 1784.950 + +1805 - 1879.95 + +Band IX + +900 MHz Band + +880 - 914.950 + +925 - 959.950 + +Band X + +Secondary 800 MHz Band + +806 - 900.975 + +851 - 939.975 + +Band XI + +400 MHz European PAMR Band + +410 - 483.475 + +420 - 493.475 + +Band XII + +800 MHz PAMR Band + +870.125 - 875.9875 + +915.0125 - 920.9875 + +Band XIII + +2.5GHz IMT2000 Extension Band + +2500 - 2570 + +2620 - 2690 + +Band XIV + +US PCS 1.9GHz Band + +1850 - 1915 + +1930 - 1995 + +Band XV + +AWS Band + +1710 - 1755 + +2110 - 2155 + +Band XVI + +US 2.5GHz Band + +2502 - 2568 + +2624 - 2690 + +Band XVII + +US 2.5 GHz Forward Link Only Band + +2624-2690 + +  + +The unit for radio frequency bands in both tables is megahertz (MHz). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567907) + +[WWAN Driver Initialization Procedure](https://msdn.microsoft.com/library/windows/hardware/ff557186) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_CAPS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-service-command.md b/windows-driver-docs-pr/network/oid-wwan-device-service-command.md new file mode 100644 index 0000000000..f043efc9e1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-service-command.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_DEVICE\_SERVICE\_COMMAND +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_SERVICE\_COMMAND allows miniport drivers to implement vendor specific commands.NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE status notification containing a vendor-defined structure (NDIS\_WWAN\_DEVICE\_SERVICE\_COMMAND) to provide responses when they have completed the transaction. +ms.assetid: 296E2D23-6EDA-4480-91A3-B6CB39243DAD +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_SERVICE_COMMAND Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_SERVICE\_COMMAND + + +OID\_WWAN\_DEVICE\_SERVICE\_COMMAND allows miniport drivers to implement vendor specific commands. + +Both query and set requests are supported. + +Miniport drivers must process query and set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh846205) status notification containing a vendor-defined structure ([**NDIS\_WWAN\_DEVICE\_SERVICE\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/hh439836)) to provide responses when they have completed the transaction. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support the specified device service or operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_RESPONSE**](https://msdn.microsoft.com/library/windows/hardware/hh846205) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_COMMAND**](https://msdn.microsoft.com/library/windows/hardware/hh439836) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_SERVICE_COMMAND%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-service-session-write.md b/windows-driver-docs-pr/network/oid-wwan-device-service-session-write.md new file mode 100644 index 0000000000..49ecdd81c0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-service-session-write.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE directs the miniport driver to write data to the MB device for a device service session.NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE status notification containing a NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE structure that describes the completion status of the operation. +ms.assetid: C1389D7D-3C8E-41B5-8E00-617D699699A2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_SERVICE_SESSION_WRITE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE + + +OID\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE directs the miniport driver to write data to the MB device for a device service session. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh846208) status notification containing a [**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh831861) structure that describes the completion status of the operation. + +Miniport drivers should return NDIS\_STATUS\_ADAPTER\_NOT\_OPEN if the device service session is not open. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE\_COMPLETE**](https://msdn.microsoft.com/library/windows/hardware/hh846208) + +[**NDIS\_WWAN\_DEVICE\_SERVICE\_SESSION\_WRITE**](https://msdn.microsoft.com/library/windows/hardware/hh831860) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_SERVICE_SESSION_WRITE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-service-session.md b/windows-driver-docs-pr/network/oid-wwan-device-service-session.md new file mode 100644 index 0000000000..3bd53a4995 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-service-session.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_DEVICE\_SERVICE\_SESSION +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_SERVICE\_SESSION directs a miniport driver to open or close a device service session.NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION status notification containing a NDIS\_WWAN\_SET\_DEVICE\_SERVICE\_SESSION structure that describes the result of the operation. +ms.assetid: 32D4EDE3-4782-4C54-95B8-83DE7E63C4F8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_SERVICE_SESSION Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_SERVICE\_SESSION + + +OID\_WWAN\_DEVICE\_SERVICE\_SESSION directs a miniport driver to open or close a device service session. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION**](https://msdn.microsoft.com/library/windows/hardware/hh846206) status notification containing a [**NDIS\_WWAN\_SET\_DEVICE\_SERVICE\_SESSION**](https://msdn.microsoft.com/library/windows/hardware/hh831865) structure that describes the result of the operation. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support specified device service or operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SET\_DEVICE\_SERVICE\_SESSION**](https://msdn.microsoft.com/library/windows/hardware/hh831865) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SESSION**](https://msdn.microsoft.com/library/windows/hardware/hh846206) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_SERVICE_SESSION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-services.md b/windows-driver-docs-pr/network/oid-wwan-device-services.md new file mode 100644 index 0000000000..545bb563ff --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-services.md @@ -0,0 +1,52 @@ +--- +title: OID\_WWAN\_DEVICE\_SERVICES +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_SERVICES returns the list of device services supported by the miniport driver.NDIS\_WWAN\_DEVICE\_SERVICES structure that indicates the supported device service GUIDs. +ms.assetid: 79DB0FC0-9AAA-465D-9479-9AD41BE9F4B4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_SERVICES Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_SERVICES + + +OID\_WWAN\_DEVICE\_SERVICES returns the list of device services supported by the miniport driver. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a NDIS\_STATUS\_WWAN\_DEVICE\_SERVICES status notification containing a [**NDIS\_WWAN\_DEVICE\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/hh439835) structure that indicates the supported device service GUIDs. + +Set requests are not supported. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_SERVICES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-device-slot-mappings.md b/windows-driver-docs-pr/network/oid-wwan-device-slot-mappings.md new file mode 100644 index 0000000000..7491b30715 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-device-slot-mappings.md @@ -0,0 +1,74 @@ +--- +title: OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO +author: windows-driver-content +description: OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO sets or returns the device-slot mappings of the MB device (i.e. the executor-slot mappings). +ms.assetid: 54AF3447-7918-49CE-945A-DC8DC1E78CBF +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DEVICE_SLOT_MAPPING_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO + + +OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO sets or returns the device-slot mappings of the MB device (i.e. the executor-slot mappings). + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request before later sending an [**NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782397) status notification containing an [**NDIS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782403) structure to provide information on the executor-to-slot mappings. + +The following diagram illustrates a query request. + +![slot mapping query](images/multi-SIM_8_slotMappingQuery.png) + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request before later sending an [**NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782397) status notification containing an [**NDIS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782403) structure, which in turn contains a [**WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799890) structure to indicate the current mapping status. This holds true even if the set request failed. The structure for set requests for OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO is [**NDIS\_WWAN\_SET\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782405). + +The following diagram illustrates a set request. + +![slot mapping set](images/multi-SIM_7_slotMappingSet.png) + +Remarks +------- + +The host expects that on first boot, the modem would have a default mapping between slots and executors. The host performs a SET operation with OID\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO to define the slot that is bound to each executor. The host expects the modem to maintain the mapping across reboots and removals/insertions. This OID is not executor-specific and may be sent to any NDIS instance on the device. It may also query the current mapping as shown above. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782397) + +[**NDIS\_WWAN\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782403) + +[**NDIS\_WWAN\_SET\_DEVICE\_SLOT\_MAPPING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782405) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DEVICE_SLOT_MAPPING_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-driver-caps.md b/windows-driver-docs-pr/network/oid-wwan-driver-caps.md new file mode 100644 index 0000000000..aa2237e803 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-driver-caps.md @@ -0,0 +1,72 @@ +--- +title: OID\_WWAN\_DRIVER\_CAPS +author: windows-driver-content +description: OID\_WWAN\_DRIVER\_CAPS returns the version of the MB driver model supported by the miniport driver. +ms.assetid: 2310a341-6899-44ad-8dfb-a13fd0c42dcb +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_DRIVER_CAPS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_DRIVER\_CAPS + + +OID\_WWAN\_DRIVER\_CAPS returns the version of the MB driver model supported by the miniport driver. + +Set requests are not supported. + +Miniport drivers process OID\_WWAN\_DRIVER\_CAPS synchronously and should immediately return with the response buffer containing an [**NDIS\_WWAN\_DRIVER\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567908) structure that describes the version of the MB driver model implemented by the miniport driver when completing query requests. + +Remarks +------- + +For more information about using this OID, see [MB Miniport Driver Initialization](https://msdn.microsoft.com/library/windows/hardware/ff557186). + +Miniport drivers should not access the provider network, or the Subscriber Identity Module (SIM card), when processing query operations. + +The current version of the MB driver model version is defined by the WWAN\_MAJOR\_VERSION and WWAN\_MINOR\_VERSION \#define tokens. If the miniport driver returns a version of the MB driver model that the MB Service does not support, the MB Service will ignore the device. + +When the MB Service is initialized or restarted, the miniport driver may already have been loaded. In this case, the MB Service queries the version of the MB driver model implement by miniport driver before it proceeds to issue any other OIDs. This occurs at the beginning of any session. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED in the case of any initialization error. If a miniport driver returns NDIS\_STATUS\_NOT\_SUPPORTED, the MB Service will ignore the device and will not proceed with any other OIDs. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[MB Miniport Driver Initialization](https://msdn.microsoft.com/library/windows/hardware/ff557186) + +[**NDIS\_WWAN\_DRIVER\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff567908) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_DRIVER_CAPS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-enumerate-device-service-commands.md b/windows-driver-docs-pr/network/oid-wwan-enumerate-device-service-commands.md new file mode 100644 index 0000000000..6824765dc8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-enumerate-device-service-commands.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS +author: windows-driver-content +description: OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS returns a list of commands supported for a device service.NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS status notification containing a NDIS\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS structure that describes the result of the operation. +ms.assetid: 9888E4EC-D4BB-4BAC-B20B-DFA51005EEDA +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_ENUMERATE_DEVICE_SERVICE_COMMANDS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS + + +OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS returns a list of commands supported for a device service. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846210) status notification containing a [**NDIS\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh831862) structure that describes the result of the operation. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support specified device service or operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846210) + +[**NDIS\_WWAN\_ENUMERATE\_DEVICE\_SERVICE\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh831862) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_ENUMERATE_DEVICE_SERVICE_COMMANDS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-enumerate-device-services.md b/windows-driver-docs-pr/network/oid-wwan-enumerate-device-services.md new file mode 100644 index 0000000000..a22acc1353 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-enumerate-device-services.md @@ -0,0 +1,59 @@ +--- +title: OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES +author: windows-driver-content +description: OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES returns the list of device services supported by the miniport driver.NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS status notification containing a NDIS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES structure that provides the list of supported device service GUIDs. +ms.assetid: 12AB2235-DDF8-44CB-BD3D-61D0FFCB4080 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_ENUMERATE_DEVICE_SERVICES Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES + + +OID\_WWAN\_ENUMERATE\_DEVICE\_SERVICES returns the list of device services supported by the miniport driver. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846210) status notification containing a [**NDIS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/hh831867) structure that provides the list of supported device service GUIDs. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUPPORTED\_COMMANDS**](https://msdn.microsoft.com/library/windows/hardware/hh846210) + +[**NDIS\_WWAN\_SUPPORTED\_DEVICE\_SERVICES**](https://msdn.microsoft.com/library/windows/hardware/hh831867) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_ENUMERATE_DEVICE_SERVICES%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-home-provider.md b/windows-driver-docs-pr/network/oid-wwan-home-provider.md new file mode 100644 index 0000000000..dcd7cb80c1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-home-provider.md @@ -0,0 +1,80 @@ +--- +title: OID\_WWAN\_HOME\_PROVIDER +author: windows-driver-content +description: OID\_WWAN\_HOME\_PROVIDER is used to set and retrieve information about the home provider of the cellular service subscription. +ms.assetid: f7bea146-261d-4d01-9fd5-ae512a1ac083 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_HOME_PROVIDER Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_HOME\_PROVIDER + + +OID\_WWAN\_HOME\_PROVIDER is used to set and retrieve information about the home provider of the cellular service subscription. For GSM-based devices and CDMA-based device with U-RIM, this information should be stored on the Subscriber Identity Module (SIM card). For CDMA-based devices without U-RIM, this information should be stored in auxiliary device memory. + +Windows 8 supports both *set* and *query* requests. Windows 7 supports only *query* requests. + +Miniport drivers must process both *set* and *query* requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request and later sending a [**NDIS\_STATUS\_WWAN\_HOME\_PROVIDER**](ndis-status-wwan-home-provider.md) status notification, for a *query*, or NDIS\_STATUS\_WWAN\_SET\_HOME\_PROVIDER\_COMPLETE status notification, for *set*, containing an [**NDIS\_WWAN\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/ff567909) structure to return information about the home network provider with the **Provider.ProviderState** member of the NDIS\_WWAN\_HOME\_PROVIDER structure set to WWAN\_PROVIDER\_STATE\_HOME. + +*Set* operations are only required to be supported by multi-carrier capable devices. The MB service will only *set* the home provider to multi-carrier providers reported by the miniport via OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS or OID\_WWAN\_VISIBLE\_PROVIDERS. *Set* operations have an input buffer of NDIS\_WWAN\_SET\_HOME\_PROVIDER. + +Remarks +------- + +A *set* operation should not require the user to unlock the device regardless if the current SIM or target SIM is in a locked state. + +| Current Provider SIM | Target Provider SIM | Result of *set* HOME\_PROVIDER | +|----------------------|---------------------|--------------------------------------------------------------| +| - | Locked | Target PIN not required for setting home provider | +| Locked | - | Source PIN not required for setting home provider | +| Locked | Locked | Source and Target PIN not required for setting home provider | + +  + +For more information about using this OID, see [WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101). + +Miniport drivers can access the Subscriber Identity Module (SIM card) when processing query operations, but should not access the provider network. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_HOME\_PROVIDER**](https://msdn.microsoft.com/library/windows/hardware/ff567909) + +[**NDIS\_STATUS\_WWAN\_HOME\_PROVIDER**](ndis-status-wwan-home-provider.md) + +[WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_HOME_PROVIDER%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-network-idle-hint.md b/windows-driver-docs-pr/network/oid-wwan-network-idle-hint.md new file mode 100644 index 0000000000..76694d330f --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-network-idle-hint.md @@ -0,0 +1,57 @@ +--- +title: OID\_WWAN\_NETWORK\_IDLE\_HINT +author: windows-driver-content +description: OID\_WWAN\_NETWORK\_IDLE\_HINT sends a hint to the network interface regarding whether data is expected to be active or idle on the interface. +ms.assetid: 1FE758C1-543A-45B4-A377-336A1307689F +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_NETWORK_IDLE_HINT Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_NETWORK\_IDLE\_HINT + + +OID\_WWAN\_NETWORK\_IDLE\_HINT sends a hint to the network interface regarding whether data is expected to be active or idle on the interface. The network service uses heuristics to determine when to send this request to the interface, typically when it estimates that for a period of time there will be a reduction in network traffic or if the system is entering an idle state (such as connected standby). The network interface can use this as an input to its heuristics to implement procedures such as "fast dormancy". + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later completing the request with the [**NDIS\_WWAN\_NETWORK\_IDLE\_HINT**](https://msdn.microsoft.com/library/windows/hardware/dn931088) structure that indicates the network idle hint. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 10 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_NETWORK\_IDLE\_HINT**](https://msdn.microsoft.com/library/windows/hardware/dn931088) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_NETWORK_IDLE_HINT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-packet-service.md b/windows-driver-docs-pr/network/oid-wwan-packet-service.md new file mode 100644 index 0000000000..e5bb8b4aaf --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-packet-service.md @@ -0,0 +1,76 @@ +--- +title: OID\_WWAN\_PACKET\_SERVICE +author: windows-driver-content +description: OID\_WWAN\_PACKET\_SERVICE is used to instruct miniport drivers to perform packet service attach/detach actions on the current registered provider’s network for both GSM-based and CDMA-based MB devices. +ms.assetid: 97bb9324-8052-437c-baa5-fb9a8176c779 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PACKET_SERVICE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PACKET\_SERVICE + + +OID\_WWAN\_PACKET\_SERVICE is used to instruct miniport drivers to perform packet service attach/detach actions on the current registered provider’s network for both GSM-based and CDMA-based MB devices. In addition to the packet service attach/detach status, this OID is used to determine data class availability and the currently used data class information. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PACKET\_SERVICE**](ndis-status-wwan-packet-service.md) status notification containing an [**NDIS\_WWAN\_PACKET\_SERVICE\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567910) structure to provide information about the current packet service state regardless of completing set or query requests. + +Callers requesting to set the current packet service state provide an [**NDIS\_WWAN\_SET\_PACKET\_SERVICE**](https://msdn.microsoft.com/library/windows/hardware/ff567921) structure to the miniport driver with the appropriate information. + +Remarks +------- + +See [WWAN Packet Service Attach Operations](https://msdn.microsoft.com/library/windows/hardware/ff559092) for more information about using this OID. + +Miniport drivers can access the provider network when processing query or set operations, but should not access the Subscriber Identity Module (SIM card). + +CDMA-based devices should use this as an opportunity to release the network resource allocation if possible. + +Some SIM cards enable the MB device to register only on the packet domain and not the circuit-switched domain. Once a data call ends, the VAN UI sends an OID\_WWAN\_PACKET\_SERVICE set request to detach packet service. This causes the MB device to detach from the packet domain. The MB device unregisters from the network and goes into a power save mode. Consequently, the device disappears from the VAN UI as a result of being unregistered, and can only be recovered by rebooting. In this scenario, miniport drivers should spoof the packet attach/detach operations by returning positive data without setting the MB device into such a mode. + +For technologies that do not support packet-attach, miniport drivers should spoof an attach state to let the MB Service know that it can proceed with context activation. Miniport drivers should also spoof the set OID\_WWAN\_PACKET\_SERVICE requests in the miniport driver. Miniport drivers should send [**NDIS\_STATUS\_WWAN\_PACKET\_SERVICE**](ndis-status-wwan-packet-service.md) notifications for query operations and for unsolicited events. Miniport drivers should fail PDP activation if the device packet service state is not set to *WwanPacketServiceStateAttached*. + +The MB Service shall not proceed with context activation until the packet service state has reached *WwanPacketServiceStateAttached*. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SET\_PACKET\_SERVICE**](https://msdn.microsoft.com/library/windows/hardware/ff567921) + +[**NDIS\_STATUS\_WWAN\_PACKET\_SERVICE**](ndis-status-wwan-packet-service.md) + +[WWAN Packet Service Attach Operations](https://msdn.microsoft.com/library/windows/hardware/ff559092) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PACKET_SERVICE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-pin-ex.md b/windows-driver-docs-pr/network/oid-wwan-pin-ex.md new file mode 100644 index 0000000000..07c125bf65 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-pin-ex.md @@ -0,0 +1,54 @@ +--- +title: OID\_WWAN\_PIN\_EX +author: windows-driver-content +description: OID\_WWAN\_PIN\_EX sets or returns expanded information related to Personal Identification Numbers (PINs). +ms.assetid: 4D3D91B2-7B3C-4C8F-B98F-0F9999D04C03 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PIN_EX Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PIN\_EX + + +OID\_WWAN\_PIN\_EX sets or returns expanded information related to Personal Identification Numbers (PINs). + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) status notification when they have completed the set or query request. + +Miniport drivers should send [**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) status notifications containing an [**NDIS\_WWAN\_PIN\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567911) structure to return PIN-type and PIN-entry state information, primarily to indicate whether a PIN is required to unlock the MB device or Subscriber Identity Module (SIM card) when completing query requests. + +Callers requesting to set information related to PINs provide an [**NDIS\_WWAN\_SET\_PIN\_EX**](https://msdn.microsoft.com/library/windows/hardware/hh439842) structure to the miniport driver to send a PIN to the MB device, enable or disable PIN settings, or to change a PIN on the SIM. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PIN_EX%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-pin-list.md b/windows-driver-docs-pr/network/oid-wwan-pin-list.md new file mode 100644 index 0000000000..e0b539d673 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-pin-list.md @@ -0,0 +1,74 @@ +--- +title: OID\_WWAN\_PIN\_LIST +author: windows-driver-content +description: OID\_WWAN\_PIN\_LIST returns a list of all the different types of Personal Identification Numbers (PINs) that are supported by the MB device and additional details for each PIN type, such as the length of the PIN (minimum and maximum lengths), PIN format, PIN-entry mode (enabled/disabled/not-available). This OID also specifies the current mode of each PIN supported by the device. Set requests are not supported. Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an NDIS\_STATUS\_WWAN\_PIN\_LIST status notification containing an NDIS\_WWAN\_PIN\_LIST structure to return a list of PINs with corresponding descriptions when completing query requests. +ms.assetid: 76a1181c-974e-472d-ad15-d9c6208aa2b4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PIN_LIST Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PIN\_LIST + + +OID\_WWAN\_PIN\_LIST returns a list of all the different types of Personal Identification Numbers (PINs) that are supported by the MB device and additional details for each PIN type, such as the length of the PIN (minimum and maximum lengths), PIN format, PIN-entry mode (enabled/disabled/not-available). This OID also specifies the current mode of each PIN supported by the device. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PIN\_LIST**](ndis-status-wwan-pin-list.md) status notification containing an [**NDIS\_WWAN\_PIN\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff567912) structure to return a list of PINs with corresponding descriptions when completing query requests. + +Remarks +------- + +For more information about using this OID, see [WWAN Pin Operations](https://msdn.microsoft.com/library/windows/hardware/ff559093). + +Miniport drivers can access the Subscriber Identity Module (SIM card) when processing query operations, but should not access the provider network. + +Miniport drivers must report all the PINs supported by their device. If the device does not support listing PINs, the miniport driver must report this list from a static (hard-coded) list maintained in the miniport driver itself for all the devices it supports. + +Any PIN that provides device power-on verification or identification functionality should be reported as PIN1 and must be compliant to PIN1 guidelines. + +Miniport drivers must return this information when the device ready-state changes to *WwanReadyStateInitialized* or when the device ready-state is *WwanReadyStateDeviceLocked* (PIN locked). Miniport drivers should also return this information in other device ready-states, wherever possible. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PIN\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff567912) + +[**NDIS\_STATUS\_WWAN\_PIN\_LIST**](ndis-status-wwan-pin-list.md) + +[WWAN Pin Operations](https://msdn.microsoft.com/library/windows/hardware/ff559093) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PIN_LIST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-pin.md b/windows-driver-docs-pr/network/oid-wwan-pin.md new file mode 100644 index 0000000000..80656876d3 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-pin.md @@ -0,0 +1,88 @@ +--- +title: OID\_WWAN\_PIN +author: windows-driver-content +description: OID\_WWAN\_PIN sets or returns information related to Personal Identification Numbers (PINs). +ms.assetid: 5c93ffe0-8067-4022-ba8e-e528e44692e6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PIN Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PIN + + +OID\_WWAN\_PIN sets or returns information related to Personal Identification Numbers (PINs). + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) status notification when they have completed the set or query request. + +Miniport drivers should send [**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) status notifications containing an [**NDIS\_WWAN\_PIN\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567911) structure to return PIN-type and PIN-entry state information, primarily to indicate whether a PIN is required to unlock the MB device or Subscriber Identity Module (SIM card) when completing query requests. + +Callers requesting to set information related to PINs provide an [**NDIS\_WWAN\_SET\_PIN**](https://msdn.microsoft.com/library/windows/hardware/ff567922) structure to the miniport driver to send a PIN to the MB device, enable or disable PIN settings, or to change a PIN on the SIM. + +Remarks +------- + +See [WWAN Pin Operations](https://msdn.microsoft.com/library/windows/hardware/ff559093) for more information about using this OID. + +Windows 7 miniport drivers should use OID\_WWAN\_PIN. Windows 8 miniport drivers should use [OID\_WWAN\_PIN\_EX](oid-wwan-pin-ex.md). + +Miniport drivers can access the Subscriber Identity Module (SIM card) when processing query operations, but should not access the provider network. + +During the miniport driver initialization process, the MB Service does not proceed to registration until PIN1 is successfully unlocked, if enabled. + +Miniport drivers provide a PIN value, entered by the end user, in the **PinAction.Pin** member of the NDIS\_WWAN\_SET\_PIN structure when processing set requests. Only when the PIN value matches the value stored in the SIM card should the request be processed by the miniport driver. Otherwise, miniport drivers should fail the set request with status code WWAN\_STATUS\_FAILURE. + +CDMA-based devices must report the power-on device lock as PIN1. + +For all supported PIN types, miniport drivers must support the *WwanPinOperationEnter* operation. Additionally, if PIN1 is supported, miniport drivers must support the *WwanPinOperationEnable*, *WwanPinOperationDisable*, and *WwanPinOperationChange* operations. + +If a PIN disable operation for a PIN type is tried when that PIN type is locked, miniport drivers can either fail the request with WWAN\_STATUS\_PIN\_REQUIRED or they can successfully complete the request. If the miniport driver completes the request successfully, the disable operation should also unlock the PIN. + +If reporting multiple PINs are enabled, and only one PIN can be reported at a time, then miniport drivers are expected to report PIN1 first. For example, if reporting of SubsidyLock and SIM PIN1 are enabled, then the SubsidyLock PIN should be reported (in a subsequent query request) only after PIN1 has been successfully verified. + +The MB API supports other PINs in addition to PIN1. However, a 3rd-party connection manager/GUI would need to be installed because the Windows Connection Manager/GUI supports only PIN1. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PIN\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567911) + +[**NDIS\_WWAN\_SET\_PIN**](https://msdn.microsoft.com/library/windows/hardware/ff567922) + +[**NDIS\_STATUS\_WWAN\_PIN\_INFO**](ndis-status-wwan-pin-info.md) + +[WWAN Pin Operations](https://msdn.microsoft.com/library/windows/hardware/ff559093) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PIN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-preferred-multicarrier-providers.md b/windows-driver-docs-pr/network/oid-wwan-preferred-multicarrier-providers.md new file mode 100644 index 0000000000..6538fe68e7 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-preferred-multicarrier-providers.md @@ -0,0 +1,67 @@ +--- +title: OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS +author: windows-driver-content +description: OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS is used to set or query the list of preferred multi-carrier network providers. Multi-carrier providers are ones that can be set as home providers. +ms.assetid: BA78E0B9-1B57-412C-83E7-328F8304C82D +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS + + +OID\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS is used to *set* or *query* the list of preferred multi-carrier network providers. Multi-carrier providers are ones that can be *set* as home providers. + +Both *set* and *query* requests are supported. Miniport drivers must process *set* and *query* requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh846211) status notification containing an [**NDIS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh831864) structure. + +Miniport drivers should set the **PreferredListHeader.ElementType** member to **WwanStructProvider2** and the **PreferredListHeader.ElementCount** member to the number of providers in the list when responding to OID\_WWAN\_PREFERRED\_PROVIDERS *query* requests. The multi-carrier providers returned in a *query* must be able to be set as the home provider at the time the preferred multi-carrier list is returned to the service. + +Miniport drivers should set the **PreferredListHeader.ElementType** member to **WwanStructProvider2** and the **PreferredListHeader.ElementCount** member to 0 when responding to OID\_WWAN\_PREFERRED\_PROVIDERS *set* requests. + +On error miniports should set the **uStatus** member of NDIS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS structure with the failure status and **PreferredListHeader.ElementCount** to 0 and **PreferredLIstHeader.ElementType** to **WwanStructProvider2**. + +The **Rssi** and **ErrorRate** members of WWAN\_PROVIDER2 structure should be set if available. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh831864) + +[**NDIS\_STATUS\_WWAN\_PREFERRED\_MULTICARRIER\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/hh846211) + +[MB Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PREFERRED_MULTICARRIER_PROVIDERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-preferred-providers.md b/windows-driver-docs-pr/network/oid-wwan-preferred-providers.md new file mode 100644 index 0000000000..d3efa2633a --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-preferred-providers.md @@ -0,0 +1,76 @@ +--- +title: OID\_WWAN\_PREFERRED\_PROVIDERS +author: windows-driver-content +description: OID\_WWAN\_PREFERRED\_PROVIDERS returns information about the list of preferred providers for GSM-based devices. +ms.assetid: fa70f1ac-5b14-44f8-a2c4-d2163fe81c5a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PREFERRED_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PREFERRED\_PROVIDERS + + +OID\_WWAN\_PREFERRED\_PROVIDERS returns information about the list of preferred providers for GSM-based devices. Miniport drivers of CDMA-based devices do not need to support this OID. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS**](ndis-status-wwan-preferred-providers.md) status notification containing an [**NDIS\_WWAN\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567913) structure to provide information about the Preferred Provider List (PPL) regardless of completing set or query requests. + +Remarks +------- + +For more information about using this OID, see [WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101). + +Miniport drivers can access the Subscriber Identity Module (SIM card) when processing query requests, but should not access the provider network. + +Miniport drivers can access the Subscriber Identity Module (SIM card) or the provider network, when processing set requests. + +When processing OID\_WWAN\_PREFERRED\_PROVIDERS, miniport drivers may set only the WWAN\_PROVIDER\_STATE\_PREFERRED or WWAN\_PROVIDER\_STATE\_FORBIDDEN flags to tag the list entries. Be aware that forbidden providers might not appear in the list for GSM-based devices. + +Miniport driverrs should set the **PreferredListHeader.ElementType** member to *WwanStructProvider*. The miniport driver should set the **PreferredListHeader.ElementCount** member to 0 when responding to OID\_WWAN\_PREFERRED\_PROVIDERS set requests. + +Whether the PPL on the device can be overwritten or not when processing set requests depends on the device capability, the cellular technology, and/or the network provider's policy. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support returning or setting the PPL. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_PREFERRED\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567913) + +[**NDIS\_STATUS\_WWAN\_PREFERRED\_PROVIDERS**](ndis-status-wwan-preferred-providers.md) + +[WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PREFERRED_PROVIDERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-preshutdown.md b/windows-driver-docs-pr/network/oid-wwan-preshutdown.md new file mode 100644 index 0000000000..52cc1e2c9c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-preshutdown.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_PRESHUTDOWN +author: windows-driver-content +description: OID\_WWAN\_PRESHUTDOWN is sent to notify the modem that the system is entering the shutdown phase and the modem should finish its operations so it can be shut down properly. +ms.assetid: B00A2D70-64E0-4686-92FC-D4095BDD713B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PRESHUTDOWN Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PRESHUTDOWN + + +OID\_WWAN\_PRESHUTDOWN is sent to notify the modem that the system is entering the shutdown phase and the modem should finish its operations so it can be shut down properly. It is only sent down with the port number corresponding to the physical MBB adapters. Virtual adapters that support multiple PDP contexts should not receive this OID. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning **NDIS\_STATUS\_INDICATION\_REQUIRED** to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_PRESHUTDOWN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt593233) status notification when the MBB driver has finished all necessary modem operations prior to shutting down. The set request has a [**NDIS\_WWAN\_SET\_PRESHUTDOWN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt593235) structure. + +Miniport drivers should return **NDIS\_STATUS\_NOT\_SUPPORTED** if they do not support this operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available starting with Windows 10, version 1511.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_PRESHUTDOWN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt593233) + +[**NDIS\_WWAN\_SET\_PRESHUTDOWN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt593235) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PRESHUTDOWN%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-provisioned-contexts.md b/windows-driver-docs-pr/network/oid-wwan-provisioned-contexts.md new file mode 100644 index 0000000000..d83b051b53 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-provisioned-contexts.md @@ -0,0 +1,88 @@ +--- +title: OID\_WWAN\_PROVISIONED\_CONTEXTS +author: windows-driver-content +description: OID\_WWAN\_PROVISIONED\_CONTEXTS reads or updates the provisioned context entries stored on the MB device or the Subscriber Identity Module (SIM). +ms.assetid: 7634fc32-9059-4f89-a591-7aa663b0c188 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_PROVISIONED_CONTEXTS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_PROVISIONED\_CONTEXTS + + +OID\_WWAN\_PROVISIONED\_CONTEXTS reads or updates the provisioned context entries stored on the MB device or the Subscriber Identity Module (SIM). + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS**](ndis-status-wwan-provisioned-contexts.md) status notification containing an [**NDIS\_WWAN\_PROVISIONED\_CONTEXTS**](https://msdn.microsoft.com/library/windows/hardware/ff567914) structure to provide information about provisioned context entries stored on the MB device or the Subscriber Identity Module (SIM) regardless of completing set or query requests. + +Remarks +------- + +For more information about using this OID, see [WWAN Packet Context Management](https://msdn.microsoft.com/library/windows/hardware/ff559086). + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if the MB device they support does not support retrieval of provisioned contexts. + +GSM-based devices can optionally support query and set operations. CDMA-based devices can optionally support query operations reporting Simple IP (WWAN\_CTRL\_CAPS\_CDMA\_SIMPLE\_IP). + +The provisioned context entries stored on the MB device or the SIM are local to the device. Miniport drivers should not connect to the network to read in these fields. + +The input structure for a set request is NDIS\_WWAN\_SET\_PROVISIONED\_CONTEXT and status indication of this object is NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS. + +Provisioned contexts are not same as that of the GPRS context definitions in 3GPP that caches the list of APNs. Provisioned contexts are the connectivity parameters (AccessString, UserName, and Password) that are either pre-provisioned by the Operators or OTA provisioned by the device and can be stored either in the device memory or SIM. The connectivity parameters returned by the Provisioned contexts will be used by the MB Service for PDP activation. + +Both query and set form of this object is used. + +Processing of this request does not require network access, but requires access to the SIM or auxiliary memory on the MB device. + +The miniport driver sends NDIS\_STATUS\_WWAN\_PROVISIONED\_CONTEXTS notification to the operating system. The **ContextListHeader.ElementType** member shall be set to *WwanStructContext*. Miniport driver should set the **ContextListHeader.ElementCount** member to 0 when notification is sent in response to a set request. + +The MB Service should retrieve the list of provisioned contexts from the device before conducting any individual context activation or deactivation. The list of provisioned contexts must be restricted only to the home provider network even though the device may have the capability to store multiple network provider contexts. The context list must always be the home provider network specific even in case of roaming. + +SET OID\_WWAN\_PROVISIONED\_CONTEXT operation should associate the context with the network provider that is specified in the set request in **ProviderId** member of the WWAN\_SET\_CONTEXT structure. Provisioned context stored through set OID\_WWAN\_PROVISIONED\_CONTEXT requests must persist across system restarts and device power recycles. + +All the empty contexts need to be reported on a query along with the provisioned contexts applicable to the home provider network. + +CDMA devices that are configured for SimpleIP, reporting in WWAN\_CTRL\_CAPS\_CDMA\_SIMPLE\_IP in WwanControlCaps can optionally return at least one provisioned context filled with the correct **AccessString**, **UserName**, and **Password** members for the query request from MB Service. + +Provisioned context list should be pre-provisioned in the device, updated by set OID\_WWAN\_PROVISIONED\_CONTEXT operations, or updated by device/operator using SMS or OTA. It must not be updated dynamically based on the context information provided in the OID\_WWAN\_CONNECT operation by MB Service. + +For more information about how to access AccessString, UserName, and Password from the MB device for each provisioned context in the list, see [**WWAN\_CONTEXT**](https://msdn.microsoft.com/library/windows/hardware/ff571201). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[WWAN Packet Context Management](https://msdn.microsoft.com/library/windows/hardware/ff559086) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_PROVISIONED_CONTEXTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-radio-state.md b/windows-driver-docs-pr/network/oid-wwan-radio-state.md new file mode 100644 index 0000000000..5f1d6d73b5 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-radio-state.md @@ -0,0 +1,129 @@ +--- +title: OID\_WWAN\_RADIO\_STATE +author: windows-driver-content +description: OID\_WWAN\_RADIO\_STATE sets or returns information about a MB device's radio power state. +ms.assetid: e6d09ae8-65c8-4544-9581-8937f61f0747 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_RADIO_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_RADIO\_STATE + + +OID\_WWAN\_RADIO\_STATE sets or returns information about a MB device's radio power state. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_RADIO\_STATE**](ndis-status-wwan-radio-state.md) status notification containing an [**NDIS\_WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567915) structure that indicates the MB device's current radio power state regardless of completing set or query requests. + +Callers requesting to set the MB device's radio power state provide an [**NDIS\_WWAN\_SET\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567925) structure to the miniport driver with the appropriate information. + +Remarks +------- + +For more information about using this OID, see [WWAN Radio Power State Operations](https://msdn.microsoft.com/library/windows/hardware/ff559107). + +Miniport drivers should not access the provider network, or the Subscriber Identity Module (SIM card), when processing query or set operations. + +Miniport drivers must retain software radio power states across system restart or device removal and reinsertion. Miniport drivers should store the device's software radio information and use it for setting the device software radio power state immediately on each restart or reinsertion of device. The effective radio power state of the device is decided based on combination of software and hardware radio power state as per the table in [**WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff571225). + +If the value is *WwanRadioOn*, miniport drivers must turn on the radio power and set the **RadioState.SwRadioState** member of the WWAN\_RADIO\_STATE structure to *WwanRadioOn*. If the **RadioState.HwRadioState** member was *WwanRadioOff*, miniport drivers should cache this power state information and ensure to physically turn on the radio power state when **RadioState.HwRadioState** changes to *WwanRadioOn*. + +If the value is *WwanRadioOff*, miniport drivers must turn off the radio power state and set the **RadioState.SwRadioState** member to *WwanRadioOff*. + +Refer to the following table for the expected radio state programming by miniport drivers. + +**Valid Combinations for PIN Mode and PIN State** + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HwRadioState valueSwRadioState valueOverall radio power state

WwanRadioOff

WwanRadioOff

WwanRadioOff

WwanRadioOff

WwanRadioOn

WwanRadioOff

WwanRadioOn

WwanRadioOff

WwanRadioOff

WwanRadioOn

WwanRadioOn

WwanRadioOn

+ +  + +For devices that do not provide a hardware radio power switch, the **RadioState.HwRadioState** member of the NDIS\_WWAN\_RADIO\_STATE structure must always be set to *WwanRadioOn*. + +Starting in Windows 10, version 1703, OID\_WWAN\_RADIO\_STATE has additional specifications for how a multi-executor supported modem should handle radio state configuration from the OS. + +With a multi-executor supported modem, there are power benefits to configuring radio power state per executor. When an executor’s radio is turned off, the OS expects the modem to de-register from the network and does not attempt any scanning or location updates from it. The modem should support a radio state for each executor that it advertises to the OS so it can determine the hardware power state in which it should be. + +As an example, if the modem has two executors and one of the executors' radio is off while the other is on, then the modem may keep the RF front end powered on to maintain registration on the executor whose radio is on but does not need to do scanning/pinging/location updates or other cellular services for the executor that is turned off. If both radios are turned off, the modem can turn off its RF front end and bring the overall hardware to a lower power state. The implementation specifics are left to each IHV. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567915) + +[**NDIS\_WWAN\_SET\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567925) + +[**NDIS\_STATUS\_WWAN\_RADIO\_STATE**](ndis-status-wwan-radio-state.md) + +[WWAN Radio Power State Operations](https://msdn.microsoft.com/library/windows/hardware/ff559107) + +[**WWAN\_RADIO\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff571225) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_RADIO_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-ready-info.md b/windows-driver-docs-pr/network/oid-wwan-ready-info.md new file mode 100644 index 0000000000..b3d9c65b3d --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-ready-info.md @@ -0,0 +1,84 @@ +--- +title: OID\_WWAN\_READY\_INFO +author: windows-driver-content +description: OID\_WWAN\_READY\_INFO returns the device ready-state, which includes its Subscriber Identity Module (SIM card). +ms.assetid: 3e6f6cb7-14fc-4eee-b5d6-d5e0cad46ea2 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_READY_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_READY\_INFO + + +OID\_WWAN\_READY\_INFO returns the device ready-state, which includes its Subscriber Identity Module (SIM card). This typically occurs at the beginning of any session. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_READY\_INFO**](ndis-status-wwan-ready-info.md) status notification containing an [**NDIS\_WWAN\_READY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567916) structure that indicates the MB device's ready-state when completing query requests. + +Remarks +------- + +For more information about using this OID, see [MB device Readiness](https://msdn.microsoft.com/library/windows/hardware/ff557164). + +Miniport drivers can access device memory or the SIM card when processing query operations, but should not access the provider network. + +Miniport drivers should wait until the PIN is cleared (if required) and then read the subscriber's identity and telephone number(s) (TNs), and then set the ReadyInfo.ReadyState member of the NDIS\_WWAN\_READY\_INFO structure to WwanReadyStateInitialized. + +Miniport drivers must never fail OID\_WWAN\_READY\_INFO and must always return the correct device ready-state. + +Miniport drivers must always notify the MB Service whenever the device ready-state changes. + +Miniport drivers should follow these steps to provide a good user experience: + +- If PIN1 is locked, miniport drivers must first send a ready-state event notification with **ReadyInfo.ReadyState** set to *WwanReadyStateDeviceLocked*. The MB Service then sends the miniport driver an OID set request of OID\_WWAN\_PIN. After the device unlocks then the miniport driver must send another ready-state event notification with **ReadyInfo.ReadyState** set to *WwanReadyStateInitialized*. Until PIN1 is successfully unlocked, miniport drivers must not change the device ready-state to *WwanReadyStateInitialized*. + +- Miniport drivers must first send an event notification with **ReadyInfo.ReadyState** set to *WwanReadyStateSimNotInserted* when the MB Service loads the miniport driver if no SIM card is present, as may be the case with devices that allow SIM cards to be inserted or removed. If the device has the capability to detect a hot insertion of a SIM card, the miniport driver must send another event notification with **ReadyInfo.ReadyState** set to *WwanReadyStateInitialized* when the user inserts a SIM. + +- Devices that have the capability to detect service activation state must set **ReadyInfo.ReadyState** to *WwanReadyStateNotActivated*. Furthermore, if the miniport driver supports service activation, the miniport driver will receive an OID set request of OID\_WWAN\_SERVICE\_ACTIVATION. On successful completion of service activation, miniport drivers must send another event notification with **ReadyInfo.ReadyState** set to *WwanReadyStateInitialized*. + +- Miniport drivers that require a specific firmware revision must ensure that the correct firmware revision is available. If the firmware revision is not available, the miniport driver should complete the event notification transaction by setting **ReadyInfo.ReadyState** to *WwanReadyStateFailure*. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_READY\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567916) + +[**NDIS\_STATUS\_WWAN\_READY\_INFO**](ndis-status-wwan-ready-info.md) + +[MB device Readiness](https://msdn.microsoft.com/library/windows/hardware/ff557164) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_READY_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-register-state.md b/windows-driver-docs-pr/network/oid-wwan-register-state.md new file mode 100644 index 0000000000..6c3c63a298 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-register-state.md @@ -0,0 +1,84 @@ +--- +title: OID\_WWAN\_REGISTER\_STATE +author: windows-driver-content +description: OID\_WWAN\_REGISTER\_STATE selects a network provider to register with. +ms.assetid: 564de5bf-10d9-47fe-a4c1-3409d9b2aee8 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_REGISTER_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_REGISTER\_STATE + + +OID\_WWAN\_REGISTER\_STATE selects a network provider to register with. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_REGISTER\_STATE**](ndis-status-wwan-register-state.md) status notification containing an [**NDIS\_WWAN\_REGISTRATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567917) structure to provide information about the registered network provider regardless of completing set or query requests. + +Callers requesting to set the network provider to register with provide an [**NDIS\_WWAN\_SET\_REGISTER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567926) structure to the miniport driver with the appropriate information. + +Remarks +------- + +For more information about using this OID, see [WWAN Registration Operations](https://msdn.microsoft.com/library/windows/hardware/ff559116). + +Miniport drivers can access the provider network when processing query or set operations, but should not access the Subscriber Identity Module (SIM card). + +The MB driver model supports two registration methods--automatic and manual. For CDMA-based networks, the MB driver model supports only automatic registration. + +Devices supporting manual registration must set the **WwanControlCaps** member in [**WWAN\_DEVICE\_CAPS**](https://msdn.microsoft.com/library/windows/hardware/ff571204) structure to WWAN\_CTRL\_CAPS\_REG\_MANUAL. Be aware that GSM-based devices must support manual registration. + +If the registration state is automatic, miniport drivers must instruct their device to select a network provider based on the selection algorithm specific to the cellular technology and proceed with registration. + +The semantics of RegisterAction values are defined as follows: + +- The *WwanRegisterActionAutomatic* flag is used by the MB Service to instruct the miniport driver to set the device to automatic register mode and let the device select the best provider network. The miniport driver must ignore **ProviderId** parameter. This setting is persistent across radio states (ON/OFF), and device power cycles, until it is explicitly change by the MB Service. + +- The *WwanRegisterActionManual* flag is used by the MB Service to instruct the miniport driver to register with the provider network identified by the **ProviderId** parameter. The **ProviderId** value shall come from the **ProviderId** member of WWAN\_PROVIDER data structure of one of the visible providers. This setting is persistent across radio states (ON/OFF), and device power cycles, until it is explicitly changed by the MB Service. + +- Changing between the different RegisterAction values are allowed even if the device is currently registered to a provider. If the device need to deregister before switching between the Automatic and Manual registration modes, the miniport driver must ensure that the device is set to deregistration before setting to the new registration mode. + +- The *Manual* and *Automatic* registration mode only affects the network selection mode. The MB device should try to register to selected network whenever the radio is turned on. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SET\_REGISTER\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567926) + +[**NDIS\_STATUS\_WWAN\_REGISTER\_STATE**](ndis-status-wwan-register-state.md) + +[WWAN Registration Operations](https://msdn.microsoft.com/library/windows/hardware/ff559116) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_REGISTER_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-service-activation.md b/windows-driver-docs-pr/network/oid-wwan-service-activation.md new file mode 100644 index 0000000000..4a364ffdb8 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-service-activation.md @@ -0,0 +1,76 @@ +--- +title: OID\_WWAN\_SERVICE\_ACTIVATION +author: windows-driver-content +description: OID\_WWAN\_SERVICE\_ACTIVATION instructs miniport drivers to initiate service activation in order to gain access to the provider's network. +ms.assetid: a70c087d-0650-4aab-b78e-0d5a7aa49eb6 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SERVICE_ACTIVATION Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SERVICE\_ACTIVATION + + +OID\_WWAN\_SERVICE\_ACTIVATION instructs miniport drivers to initiate service activation in order to gain access to the provider's network. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION**](ndis-status-wwan-service-activation.md) status notification containing an [**NDIS\_WWAN\_SERVICE\_ACTIVATION**](https://msdn.microsoft.com/library/windows/hardware/ff567918) structure to initiate service activation in order to gain access to the provider's network when they have completed the transaction. + +Remarks +------- + +For more information about using this OID, see [MB Service Detection and Activation](https://msdn.microsoft.com/library/windows/hardware/ff559122). + +Miniport drivers can access the Subscriber Identity Module (SIM card) or the provider network when processing query or set requests. + +The MB Service uses OID\_WWAN\_SERVICE\_ACTIVATION in the case where the service activation process requires miniport driver and user interactions. + +This is not needed for miniport driver initiated or out-of-band manual service activations such as calling into the service provider's helpdesk. After the device is activated as in the above scenarios, if the current miniport driver **ReadyState** is *WwanReadyStateNotActivated*, the miniport driver shall proceed with MB initialization and notify the MB Service of ready-state change using NDIS\_STATUS\_WWAN\_READY\_INFO INDICATION . + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support miniport driver-based service activation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[OID\_WWAN\_READY\_INFO](oid-wwan-ready-info.md) + +[**NDIS\_WWAN\_SERVICE\_ACTIVATION**](https://msdn.microsoft.com/library/windows/hardware/ff567918) + +[**NDIS\_STATUS\_WWAN\_SERVICE\_ACTIVATION**](ndis-status-wwan-service-activation.md) + +[MB Service Detection and Activation](https://msdn.microsoft.com/library/windows/hardware/ff559122) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SERVICE_ACTIVATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-signal-state.md b/windows-driver-docs-pr/network/oid-wwan-signal-state.md new file mode 100644 index 0000000000..79fc2c5f05 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-signal-state.md @@ -0,0 +1,111 @@ +--- +title: OID\_WWAN\_SIGNAL\_STATE +author: windows-driver-content +description: OID\_WWAN\_SIGNAL\_STATE returns or sets the current signal state. +ms.assetid: 6f5d8fd6-b4cf-4058-a27e-d4f7cea19f47 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SIGNAL_STATE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SIGNAL\_STATE + + +OID\_WWAN\_SIGNAL\_STATE returns or sets the current signal state. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_SIGNAL\_STATE**](ndis-status-wwan-signal-state.md) status notification containing an [**NDIS\_WWAN\_SIGNAL\_STATE**](https://msdn.microsoft.com/library/windows/hardware/ff567931) structure to provide information about the current signal state indication shown to the end-user regardless of completing set or query requests. + +Callers requesting to set the current signal state indication to the end user provide an [**NDIS\_WWAN\_SET\_SIGNAL\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567928) structure to the miniport driver with the appropriate information. + +Remarks +------- + +For more information about using this OID, see [WWAN Signal Strength Operations](https://msdn.microsoft.com/library/windows/hardware/ff559125). + +Miniport drivers should not access the provider network, or the Subscriber Identity Module (SIM card), when processing query or set operations. + +Generally, signal state should be indicated rather than polled. However, this OID is made available in case the current signal state needs to be determined by the MB Service. + +For response to query requests, miniport drivers should send an NDIS\_STATUS\_WWAN\_SIGNAL\_STATE notification. + +On a set request from the MB Service, miniport drivers should: + +- Return the current values for **Rssi** and **ErrorRate** in the NDIS\_WWAN\_SIGNAL\_STATE structure in addition to reporting the absolute values for **RssiInterval** and **RssiThreshold** that has been set in the miniport driver. + +- Internally cache the **RssiInterval** and/or **RssiThreshold** values even if the device is not currently registered with any operator and that any restriction imposed by device in setting parameters can only be possible post-registration state. The miniport driver should try to apply these settings in the next immediate available situation. + +- Complete the request successfully, if the hardware and/or software radio switch state is currently OFF. Miniport driver cache the request data and start reporting the signal strength after the switch is turned ON. + +- Can fail this request with the appropriate **uStatus** error code set. + +Miniport drivers can do the following when processing query requests from the MB Service: + +- Return the current values for **Rssi** and **ErrorRate** in the NDIS\_WWAN\_SIGNAL\_STATE structure in addition to reporting the absolute values for **RssiInterval** and **RssiThreshold** that has been set in the miniport driver. + +- Fail this request with the appropriate **uStatus** error code set. + +Return Values: + +NDIS\_STATUS\_NOT\_SUPPORTED + +Miniport drivers can return this for specific devices that are aware of device capabilities not supporting the signal strength can fail the request with this error code. + +**Recommended Implementation** + +1. Devices must support signal strength indications. + +2. Drivers must report signal strength indications of at least 50% of the **RssiInterval** setting over a time period of five minutes. + +3. Devices must avoid reporting the signal strength in the following states: + 1. Device not registered or deregistered and is applicable only for GSM devices. + 2. Effective state of radio is OFF. + 3. In the above states, a query to the signal strength must be returned with the following data by the miniport driver: + + Rssi = WWAN\_RSSI\_UNKNOWN + + ErrorRate = WWAN\_ERROR\_RATE\_UNKNOWN; + + RssiInterval = < WWAN\_RSSI\_DISABLE, WWAN\_RSSI\_DEFAULT or last set value> + + RssiThreshold = < WWAN\_RSSI\_DISABLE, WWAN\_RSSI\_DEFAULT or the last set value> + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SET\_SIGNAL\_INDICATION**](https://msdn.microsoft.com/library/windows/hardware/ff567928) + +[WWAN Signal Strength Operations](https://msdn.microsoft.com/library/windows/hardware/ff559125) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SIGNAL_STATE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-slot-info-status.md b/windows-driver-docs-pr/network/oid-wwan-slot-info-status.md new file mode 100644 index 0000000000..279248f9e0 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-slot-info-status.md @@ -0,0 +1,86 @@ +--- +title: OID\_WWAN\_SLOT\_INFO +author: windows-driver-content +description: OID\_WWAN\_SLOT\_INFO retrieves a high-level aggregated status of a specified UICC slot and the card within it (if any). It may also be used to deliver an unsolicited notification when the status of one of the slots changes. +ms.assetid: 6267D480-5055-4A7A-B2A0-F4DF9154DCD7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SLOT_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SLOT\_INFO + + +OID\_WWAN\_SLOT\_INFO retrieves a high-level aggregated status of a specified UICC slot and the card within it (if any). It may also be used to deliver an unsolicited notification when the status of one of the slots changes. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request before later sending an [**NDIS\_STATUS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782398) status notification containing an [**NDIS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782408) structure, which in turn contains a [**WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799892) structure, to provide information about the overall modem system capability. + +Query requests specify [**NDIS\_WWAN\_GET\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782404) structure as input. The miniport driver should return the slot status according to the slot ID specified in the **SlotIndex** member of the [**WWAN\_GET\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799891) structure. + +The following diagram illustrates a query request. + +![slot status query](images/multi-SIM_9_slotStatusQuery.png) + +Set requests are not applicable. + +An [**NDIS\_STATUS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782398) notification with a [**NDIS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782408) structure is sent to host when the slot/card state changes. + +Remarks +------- + +The host uses OID\_WWAN\_SLOT\_INFO to query the status of a specific slot on the modem. This OID is not executor-specific and may be sent to any NDIS instance belonging to one modem. The slot state represents a summary of both the slot and card state. + +The set of reported states is constrained by the capability of the slot hardware. In the most restrictive case, the slot hardware may only be able to determine that a card is present when it is powered on and active—in such a case the **OffEmpty** and **Off** states will not be reported. + +[OID\_WWAN\_READY\_INFO](oid-wwan-ready-info.md) and OID\_WWAN\_SLOT\_INFO perform the same core function of retrieving the device ready-state of a SIM card slot; however, OID\_WWAN\_READY\_INFO is a per-executor command whereas OID\_WWAN\_SLOT\_INFO could be used on any physical instance (executor) and is expected to return the appropriate slot state even if it is not mapped to any executors at the moment. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782398) + +[**NDIS\_WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782408) + +[**WWAN\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799892) + +[**NDIS\_WWAN\_GET\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782404) + +[**WWAN\_GET\_SLOT\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799891) + +[**WWAN\_UICCSLOT\_STATE**](https://msdn.microsoft.com/library/windows/hardware/mt799894) + +[OID\_WWAN\_READY\_INFO](oid-wwan-ready-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SLOT_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sms-configuration.md b/windows-driver-docs-pr/network/oid-wwan-sms-configuration.md new file mode 100644 index 0000000000..45813fdf7b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sms-configuration.md @@ -0,0 +1,78 @@ +--- +title: OID\_WWAN\_SMS\_CONFIGURATION +author: windows-driver-content +description: OID\_WWAN\_SMS\_CONFIGURATION sets or returns a MB device's SMS text message configuration. +ms.assetid: 3292a91d-4aa8-4c57-9223-d7d984dc5d69 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SMS_CONFIGURATION Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SMS\_CONFIGURATION + + +OID\_WWAN\_SMS\_CONFIGURATION sets or returns a MB device's SMS text message configuration. + +Miniport drivers must process set and query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION**](ndis-status-wwan-sms-configuration.md) status notification regardless of completing set or query requests. + +Query requests return the MB device's current SMS text message configuration stored in the device or Subscriber Identity Module (SIM) card. + +Set requests use the [**NDIS\_WWAN\_SET\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567929) structure to change the SMS text message configuration of the MB device. + +Remarks +------- + +For more information about using this OID, see [WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131). + +When processing this OID, miniport drivers can access the SIM card, but should not access the provider network. + +Miniport drivers of GSM-based devices should support both query and set operations. Miniport drivers of CDMA-based devices should support only query operations. Miniport drivers of CDMA-based devices should return a valid value in the **ulMaxMessageIndex** member of the WWAN\_SMS\_CONFIGURATION structure for query requests and can ignore the other members. + +Miniport drivers must send an unsolicited NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION indication when the MB device's SMS subsystem is ready for SMS operation. Thereafter, when responding to OID\_WWAN\_SMS\_CONFIGURATION query requests, miniport drivers must return valid values for all members of the WWAN\_SMS\_CONFIGURATION structure. + +Miniport drivers should return NDIS\_STATUS\_NOT\_INITIALIZED if the device is initialized but the SMS subsystem is not yet initialized. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support configuring SMS text messages. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SET\_SMS\_CONFIGURATION**](https://msdn.microsoft.com/library/windows/hardware/ff567929) + +[**NDIS\_STATUS\_WWAN\_SMS\_CONFIGURATION**](ndis-status-wwan-sms-configuration.md) + +[WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SMS_CONFIGURATION%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sms-delete.md b/windows-driver-docs-pr/network/oid-wwan-sms-delete.md new file mode 100644 index 0000000000..d290ccf09b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sms-delete.md @@ -0,0 +1,72 @@ +--- +title: OID\_WWAN\_SMS\_DELETE +author: windows-driver-content +description: OID\_WWAN\_SMS\_DELETE deletes SMS text messages stored in the MB device, or Subscriber Identity Module (SIM card), or any other auxiliary non-volatile memory or memories. +ms.assetid: b80fae94-35cc-4709-8346-d5a500d3fd49 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SMS_DELETE Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SMS\_DELETE + + +OID\_WWAN\_SMS\_DELETE deletes SMS text messages stored in the MB device, or Subscriber Identity Module (SIM card), or any other auxiliary non-volatile memory or memories. + +Query requests are not supported. + +Set requests use the [**NDIS\_WWAN\_SMS\_DELETE**](https://msdn.microsoft.com/library/windows/hardware/ff567938) structure. + +Miniport drivers process this OID asynchronously, and should return an NDIS\_STATUS\_INDICATION\_REQUIRED provisional response to any set requests. Miniport drivers should send an [**NDIS\_STATUS\_WWAN\_SMS\_DELETE**](ndis-status-wwan-sms-delete.md) indication when they have completed the transaction. + +Remarks +------- + +For more information about using this OID, see [WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131). + +When processing this OID, miniport drivers can access the Subscriber Identity Module (SIM card), but should not access the provider's network. + +Miniport drivers may receive requests to delete SMS text messages based on an index, or to delete all SMS text messages. Delete requests may consist of any one of the basic filters such as new (unread) messages, old (read) messages, draft messages, or sent messages. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support SMS text messages, or the ability to delete SMS text messages. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SMS\_DELETE**](https://msdn.microsoft.com/library/windows/hardware/ff567938) + +[WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SMS_DELETE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sms-read.md b/windows-driver-docs-pr/network/oid-wwan-sms-read.md new file mode 100644 index 0000000000..252432c15c --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sms-read.md @@ -0,0 +1,78 @@ +--- +title: OID\_WWAN\_SMS\_READ +author: windows-driver-content +description: OID\_WWAN\_SMS\_READ reads SMS text messages stored in the MB device, or Subscriber Identity Module (SIM card), or any other auxiliary non-volatile memory or memories. +ms.assetid: f4dbb7e8-1348-4fa8-abac-f644a443df48 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SMS_READ Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SMS\_READ + + +OID\_WWAN\_SMS\_READ reads SMS text messages stored in the MB device, or Subscriber Identity Module (SIM card), or any other auxiliary non-volatile memory or memories. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_SMS\_RECEIVE**](ndis-status-wwan-sms-receive.md) status notification containing an [**NDIS\_WWAN\_SMS\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff567941) structure to provide the SMS messages requested that was initially provided by the caller when completing query requests. + +Callers requesting to read SMS text messages provide an NDIS\_WWAN\_SMS\_READ structure to indicate which SMS messages the caller wants the miniport to return. + +Remarks +------- + +For more information about using this OID, see [WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131). + +When processing this OID, miniport drivers can access the Subscriber Identity Module (SIM card), but should not access the provider network. + +OID\_WWAN\_SMS\_READ supports reading both PDU-mode and CDMA-mode SMS text messages, depending on the capabilities of the device. + +Miniport drivers may receive requests to read SMS text messages based on an index, or to read all SMS text messages. Read requests may consist of any one of the basic filters such as new (unread) messages, old (read) messages, draft messages, or sent messages. + +Miniport drivers that implement SMS text message functionality must support the reading of new messages using the basic filter for *WwanSmsFlagNew*. All other filter types are optional to support. + +Miniport drivers must logically project a single SMS text message store across all available physically different SMS text message stores. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support SMS text messages. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SMS\_READ**](https://msdn.microsoft.com/library/windows/hardware/ff567941) + +[WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SMS_READ%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sms-send.md b/windows-driver-docs-pr/network/oid-wwan-sms-send.md new file mode 100644 index 0000000000..256a356888 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sms-send.md @@ -0,0 +1,74 @@ +--- +title: OID\_WWAN\_SMS\_SEND +author: windows-driver-content +description: OID\_WWAN\_SMS\_SEND sends SMS text messages to another MB device. +ms.assetid: 557d2bdc-8414-4fcb-903c-23bb68955d07 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SMS_SEND Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SMS\_SEND + + +OID\_WWAN\_SMS\_SEND sends SMS text messages to another MB device. + +Query requests are not supported. + +Set requests use the [**NDIS\_WWAN\_SMS\_SEND**](https://msdn.microsoft.com/library/windows/hardware/ff567943) structure. + +Miniport drivers process this OID asynchronously, and should return an NDIS\_STATUS\_INDICATION\_REQUIRED provisional response to any set requests. Miniport drivers should send an [**NDIS\_STATUS\_WWAN\_SMS\_SEND**](ndis-status-wwan-sms-send.md) indication when they have completed the transaction. + +Remarks +------- + +For more information about using this OID, see [WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131). + +When processing this OID, miniport drivers can access the provider network, but should not access the Subscriber Identity Module (SIM card). + +OID\_WWAN\_SMS\_SEND supports sending both PDU-mode and CDMA-mode SMS text messages, depending on the capabilities of the device. + +GSM-based devices are expected to support only PDU-mode SMS text messages. CDMA-based devices are expected to support only CDMA-mode SMS text messages. Miniport drivers must be able to complete set requests irrespective of SMS text message mode. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support SMS text messages, or the ability to send SMS text messages. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_SMS\_SEND**](https://msdn.microsoft.com/library/windows/hardware/ff567943) + +[WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SMS_SEND%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sms-status.md b/windows-driver-docs-pr/network/oid-wwan-sms-status.md new file mode 100644 index 0000000000..d4467db7d6 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sms-status.md @@ -0,0 +1,70 @@ +--- +title: OID\_WWAN\_SMS\_STATUS +author: windows-driver-content +description: OID\_WWAN\_SMS\_STATUS reports the status of the MB device's message store. +ms.assetid: a43451e6-f589-4963-acc7-855555655d37 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SMS_STATUS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SMS\_STATUS + + +OID\_WWAN\_SMS\_STATUS reports the status of the MB device's message store. + +Set requests are not supported. + +Query requests do not use a structure. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_SMS\_STATUS**](ndis-status-wwan-sms-status.md) status notification that indicates the status of the MB device's message store when completing query requests. + +Remarks +------- + +For more information about using this OID, see [WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131). + +When processing this OID, miniport drivers can access the Subscriber Identity Module (SIM card), but should not access the provider network. + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support SMS text messages. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[WWAN SMS Operations](https://msdn.microsoft.com/library/windows/hardware/ff559131) + +[**NDIS\_STATUS\_WWAN\_SMS\_STATUS**](ndis-status-wwan-sms-status.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SMS_STATUS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-subscribe-device-service-events.md b/windows-driver-docs-pr/network/oid-wwan-subscribe-device-service-events.md new file mode 100644 index 0000000000..cd453aefcf --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-subscribe-device-service-events.md @@ -0,0 +1,61 @@ +--- +title: OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS +author: windows-driver-content +description: OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS sets information about the list of device services for which the MB device must send NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT notifications. +ms.assetid: 34D38A28-0E81-47B0-9232-F89927DA4B2B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SUBSCRIBE_DEVICE_SERVICE_EVENTS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS + + +OID\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS sets information about the list of device services for which the MB device must send [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/hh846204) notifications. The MB device should not indicate events for any device service which is not in this list. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/hh846209) status notification that contains the current list of event subscriptions on the MB device. + +Callers requesting to set the MB device service event subscription list provide a [**NDIS\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/hh439843) structure to the miniport driver with the appropriate information. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Versions: Supported in Windows 8 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_EVENT**](https://msdn.microsoft.com/library/windows/hardware/hh846204) + +[**NDIS\_STATUS\_WWAN\_DEVICE\_SERVICE\_SUBSCRIPTION**](https://msdn.microsoft.com/library/windows/hardware/hh846209) + +[**NDIS\_WWAN\_SUBSCRIBE\_DEVICE\_SERVICE\_EVENTS**](https://msdn.microsoft.com/library/windows/hardware/hh439843) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SUBSCRIBE_DEVICE_SERVICE_EVENTS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-sys-caps.md b/windows-driver-docs-pr/network/oid-wwan-sys-caps.md new file mode 100644 index 0000000000..4b62803cb1 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-sys-caps.md @@ -0,0 +1,78 @@ +--- +title: OID\_WWAN\_SYS\_CAPS\_INFO +author: windows-driver-content +description: OID\_WWAN\_SYS\_CAPS\_INFO retrieves information about the modem. It can be sent on any of the NDIS instances exposed by the modem. +ms.assetid: D158432A-A715-4ABB-969C-F8F80D2DB845 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_SYS_CAPS_INFO Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_SYS\_CAPS\_INFO + + +OID\_WWAN\_SYS\_CAPS\_INFO retrieves information about the modem. It can be sent on any of the NDIS instances exposed by the modem. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request before later sending an [**NDIS\_STATUS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782400) status notification containing an [**NDIS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782410) structure, which in turn contains a [**WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799893) structure, to provide information about the overall modem system capability. + +The following diagram illustrates a query request. + +![system capability query](images/multi-SIM_5_systemCapabilityQuery.png) + +Set requests are not applicable. + +Remarks +------- + +The host uses OID\_WWAN\_SYS\_CAPS\_INFO to query the number of devices (executors) and slots in the modem as well as the number of executors that may be active concurrently. A dual-standby modem would have a concurrency of 1; a dual-active modem would have a concurrency of 2. This OID is not executor-specific and may be sent to any NDIS instance. + +The modem may expose multiple configurations with differing numbers of executors and slots. Regardless of which configuration is selected, this query will return the maximum number of devices and slots that the modem can support as currently configured. + +A modem supporting OID\_WWAN\_SYS\_CAPS\_INFO is expected to also support [OID\_WWAN\_DEVICE\_CAPS\_EX](oid-wwan-device-caps-ex.md). Versions of Windows that support multi-executor modems will not use the legacy [OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md) if the underlying modem supports OID\_WWAN\_SYS\_CAPS\_INFO. For legacy versions of the OS (any version before Windows 10 Version 1703 for the purposes of this OID), a multi-executor modem would be represented as multiple independent modems and the existing OID\_WWAN\_DEVICE\_CAPS, available starting in Windows 8, will be used. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10, version 1703

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_STATUS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782400) + +[**NDIS\_WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt782410) + +[**WWAN\_SYS\_CAPS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/mt799893) + +[OID\_WWAN\_DEVICE\_CAPS\_EX](oid-wwan-device-caps-ex.md) + +[OID\_WWAN\_DEVICE\_CAPS](oid-wwan-device-caps.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_SYS_CAPS_INFO%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-ussd.md b/windows-driver-docs-pr/network/oid-wwan-ussd.md new file mode 100644 index 0000000000..2884ba829e --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-ussd.md @@ -0,0 +1,63 @@ +--- +title: OID\_WWAN\_USSD +author: windows-driver-content +description: OID\_WWAN\_USSD sends Unstructured Supplementary Service Data (USSD) requests to the underlying MB device. +ms.assetid: 9DFAAABD-8213-4B83-8FE8-1EC2BB9F735B +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_USSD Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_USSD + + +OID\_WWAN\_USSD sends Unstructured Supplementary Service Data (USSD) requests to the underlying MB device. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [NDIS\_STATUS\_WWAN\_USSD](https://msdn.microsoft.com/library/windows/hardware/hh439822) status notification containing the status of the initial USSD request when they have completed the transaction. + +Windows does not send an OID\_WWAN\_USSD request to a miniport driver if a previous request is still in progress, with the exception of a request to cancel a pending operation by setting the [WWAN\_USSD\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh464138) **RequestType** member of the request to *WwanUssdRequestCancel*. + +When a request is canceled, the miniport driver must respond to both the canceled request and the cancel request. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Supported starting with Windows 8.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[NDIS\_STATUS\_WWAN\_USSD](https://msdn.microsoft.com/library/windows/hardware/hh439822) + +[WWAN\_USSD\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/hh464138) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_USSD%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-vendor-specific.md b/windows-driver-docs-pr/network/oid-wwan-vendor-specific.md new file mode 100644 index 0000000000..619771234b --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-vendor-specific.md @@ -0,0 +1,66 @@ +--- +title: OID\_WWAN\_VENDOR\_SPECIFIC +author: windows-driver-content +description: OID\_WWAN\_VENDOR\_SPECIFIC allows miniport drivers to implement vendor specific objects. +ms.assetid: 7c1843bc-3d60-437c-a24d-6da82262a468 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_VENDOR_SPECIFIC Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_VENDOR\_SPECIFIC + + +OID\_WWAN\_VENDOR\_SPECIFIC allows miniport drivers to implement vendor specific objects. + +Query requests are not supported. + +Miniport drivers must process set requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending a [**NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC**](ndis-status-wwan-vendor-specific.md) status notification containing a vendor-defined structure to implement private objects when they have completed the transaction. + +Remarks +------- + +For more information about using this OID, see [WWAN Vendor Specific Operations](https://msdn.microsoft.com/library/windows/hardware/ff559138). + +Miniport drivers should return NDIS\_STATUS\_NOT\_SUPPORTED if they do not support vendor-specific operations. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[WWAN Vendor Specific Operations](https://msdn.microsoft.com/library/windows/hardware/ff559138) + +[**NDIS\_STATUS\_WWAN\_VENDOR\_SPECIFIC**](ndis-status-wwan-vendor-specific.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_VENDOR_SPECIFIC%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/oid-wwan-visible-providers.md b/windows-driver-docs-pr/network/oid-wwan-visible-providers.md new file mode 100644 index 0000000000..3912627916 --- /dev/null +++ b/windows-driver-docs-pr/network/oid-wwan-visible-providers.md @@ -0,0 +1,82 @@ +--- +title: OID\_WWAN\_VISIBLE\_PROVIDERS +author: windows-driver-content +description: OID\_WWAN\_VISIBLE\_PROVIDERS returns a list of network providers currently visible within the MB device's range. +ms.assetid: 4dfd4477-6332-4163-8b3e-a1604b11d175 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -OID_WWAN_VISIBLE_PROVIDERS Network Drivers Starting with Windows Vista +--- + +# OID\_WWAN\_VISIBLE\_PROVIDERS + + +OID\_WWAN\_VISIBLE\_PROVIDERS returns a list of network providers currently visible within the MB device's range. + +Set requests are not supported. + +Miniport drivers must process query requests asynchronously, initially returning NDIS\_STATUS\_INDICATION\_REQUIRED to the original request, and later sending an [**NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS**](ndis-status-wwan-visible-providers.md) status notification containing an [**NDIS\_WWAN\_VISIBLE\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567948) structure to provide information about visible network providers when completing query requests. + +*Query* requests specify NDIS\_WWAN\_GET\_VISIBLE\_PROVIDERS structure as input. When the **Action** member in WWAN\_GET\_VISIBLE\_PROVIDERS is set to WWAN\_GET\_VISIBLE\_PROVIDERS\_ALL the miniport should return all visible providers. When the **Action** member in WWAN\_GET\_VISIBLE\_PROVIDERS is set to WWAN\_GET\_VISIBLE\_PROVIDERS\_MULTICARRIER the miniport should only return visible multi-carrier providers that can be set as the home provider. + +The visible provider list returned by the device should have the provider state set correctly for each of the providers. For example, the multicarrier preferred providers should be tagged as WWAN\_PROVIDER\_STATE\_PREFERRED\_MULTICARRIER, the current home provider if any should be tagged as WWAN\_PROVIDER\_STATE\_HOME, The current registered provider if any should be tagged as WWAN\_PROVIDER\_STATE\_REGISTERED. + +The **Rssi** and **ErrorRate** members of WWAN\_PROVIDER2 structure should be set if available. + +Remarks +------- + +For more information about using this OID, see [WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101). + +Miniport drivers can access the Subscriber Identity Module (SIM card) when processing query operations, but should not access the provider network. + +Miniport drivers should set the **VisibleListHeader.ElementType** member to *WwanStructProvider*. + +For CDMA-based networks, miniport driver should return only the home provider, if any of the networks in the Preferred Roaming List (PRL) is currently visible. For GSM-based networks, more than one provider may be present in the visible provider list. + +Devices that do not support scanning for visible providers while connected should return the WWAN\_STATUS\_BUSY error value in the **uStatus** member of the NDIS\_WWAN\_VISIBLE\_PROVIDERS structure. + +Both GSM-based and CDMA-based devices must support scanning for visible providers while in registered mode. However, miniport drivers are not required to support scanning for visible provider while a Packet Data Protocol (PDP) context is active (for example, the device is connected to the provider's network). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 7 and later versions of Windows.

Header

Ntddndis.h (include Ndis.h)
+ +## See also + + +[**NDIS\_WWAN\_VISIBLE\_PROVIDERS**](https://msdn.microsoft.com/library/windows/hardware/ff567948) + +[**NDIS\_STATUS\_WWAN\_VISIBLE\_PROVIDERS**](ndis-status-wwan-visible-providers.md) + +[WWAN Provider Operations](https://msdn.microsoft.com/library/windows/hardware/ff559101) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20OID_WWAN_VISIBLE_PROVIDERS%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/overview-of-ndis-support-for-header-versions.md b/windows-driver-docs-pr/network/overview-of-ndis-support-for-header-versions.md index 2dcfa51f56..ddc70e93fd 100644 --- a/windows-driver-docs-pr/network/overview-of-ndis-support-for-header-versions.md +++ b/windows-driver-docs-pr/network/overview-of-ndis-support-for-header-versions.md @@ -40,7 +40,7 @@ Structures that include the **Header** member meet the following requirements: ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md) [Specifying NDIS Version Information](specifying-ndis-version-information.md) diff --git a/windows-driver-docs-pr/network/ndis-versions-in-network-drivers.md b/windows-driver-docs-pr/network/overview-of-ndis-versions.md similarity index 76% rename from windows-driver-docs-pr/network/ndis-versions-in-network-drivers.md rename to windows-driver-docs-pr/network/overview-of-ndis-versions.md index 2aa4fe690b..2d97cf4e77 100644 --- a/windows-driver-docs-pr/network/ndis-versions-in-network-drivers.md +++ b/windows-driver-docs-pr/network/overview-of-ndis-versions.md @@ -1,6 +1,6 @@ --- -title: NDIS Versions in Network Drivers -description: NDIS Versions in Network Drivers +title: Overview of NDIS versions +description: Overview of NDIS versions ms.assetid: 6ecd4040-2831-4238-8080-97edc6a7c3ba keywords: - network drivers WDK , NDIS versions @@ -14,7 +14,7 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# NDIS Versions in Network Drivers +# Overview of NDIS versions ## @@ -24,9 +24,8 @@ If you are writing an NDIS driver for more than one version of Microsoft Windows This set of design guide documentation is targeted at Windows Vista and later operating systems and NDIS 6.0 and later drivers. Documentation for earlier Windows and NDIS versions is contained in prior releases of the documentation. For the Windows XP and NDIS 5.1 documentation, see [Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849). -**Note**  A driver can query the NDIS version by calling the [**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511) function with the *Keyword* parameter set to **NdisVersion**. - -  +> [!NOTE] +> A driver can query the NDIS version by calling the [**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511) function with the *Keyword* parameter set to **NdisVersion**.  Windows operating system, Microsoft Windows Driver Kit (WDK), and Driver Development Kit (DDK) version support for NDIS versions, as well as support for major NDIS features across NDIS versions, are described in the following table. @@ -64,3 +63,13 @@ Windows operating system, Microsoft Windows Driver Kit (WDK), and Driver Develop | | | For information about NDIS 6.30 features, see [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md). | | Windows 8.1 and Windows Server 2012 R2 | See [Download kits for Windows hardware development](http://go.microsoft.com/fwlink/p/?linkid=239721). | 6.40 | X | X | X | | | | For information about NDIS 6.40 features, see [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md). | +| Windows 10, version 1507 | See [Download kits for Windows hardware development](http://go.microsoft.com/fwlink/p/?linkid=239721). | 6.50 | X | X | X | +| | | For more information about NDIS 6.50 features, see [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md). | +| Windows 10, version 1511 | See [Download kits for Windows hardware development](http://go.microsoft.com/fwlink/p/?linkid=239721). | 6.51 | X | X | X | +| Windows 10, version 1607 and Windows Server 2016 | See [Download kits for Windows hardware development](http://go.microsoft.com/fwlink/p/?linkid=239721). | 6.60 | X | X | X | +| | | For more information about NDIS 6.60 features, see [Introduction to NDIS 6.60](introduction-to-ndis-6-60.md). | +| Windows 10, version 1703 | See [Download kits for Windows hardware development](http://go.microsoft.com/fwlink/p/?linkid=239721). | 6.70 | X | X | X | +| | | NDIS 6.70 coincided with a preview release of the Network Adapter WDF Class Extension, a.k.a. [NetAdapterCx](../netcx/index.md).

For more information about NDIS 6.70 features, see [Introduction to NDIS 6.70](introduction-to-ndis-6-70.md).

| + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + diff --git a/windows-driver-docs-pr/network/packetdirect-provider-interface--pdpi--status-indications.md b/windows-driver-docs-pr/network/packetdirect-provider-interface--pdpi--status-indications.md new file mode 100644 index 0000000000..448663689c --- /dev/null +++ b/windows-driver-docs-pr/network/packetdirect-provider-interface--pdpi--status-indications.md @@ -0,0 +1,28 @@ +--- +title: PacketDirect Provider Interface (PDPI) Status Indications +author: windows-driver-content +description: This section includes +ms.assetid: 1EDCCC23-2C0C-4D54-AB78-3AB802BCD4BA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# PacketDirect Provider Interface (PDPI) Status Indications + + +This section includes: + +- [NDIS\_STATUS\_PD\_CURRENT\_CONFIG](ndis-status-pd-current-config.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20PacketDirect%20Provider%20Interface%20%28PDPI%29%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-40.md b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-40.md index 4c976f1b16..6a9abdcbb3 100644 --- a/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-40.md +++ b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-40.md @@ -11,18 +11,11 @@ ms.technology: windows-devices # Porting NDIS 6.x Drivers to NDIS 6.40 +NDIS 6.40 is substantially the same as NDIS 6.30. For detailed information about new features for NDIS 6.40, including implementation and compilation details specific to this version of NDIS, see [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md). -NDIS 6.40 is substantially the same as NDIS 6.30. For detailed information about new features for NDIS 6.40, see [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md). - -- For information about porting NDIS 6.x drivers to NDIS 6.30, see [Porting NDIS 6.x Drivers to NDIS 6.30](porting-ndis-6-x-drivers-to-ndis-6-30.md). -- For information about porting NDIS 6.x drivers to NDIS 6.20, see [Porting NDIS 6.x Drivers to NDIS 6.20](porting-ndis-6-x-drivers-to-ndis-6-20.md). -- For information about porting NDIS 5.x and earlier drivers to NDIS 6.x, see [Porting NDIS 5.x Drivers to NDIS 6.0](porting-ndis-5-x-drivers-to-ndis-6-0.md). - -  - -  - - - - +If you are porting an NDIS 6.x driver to NDIS 6.40, you should be familiar with the changes to each version between your driver's version and 6.40. For more information about previous NDIS 6.x versions, see the following topics: +- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) \ No newline at end of file diff --git a/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-50.md b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-50.md new file mode 100644 index 0000000000..5e397d6f88 --- /dev/null +++ b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-50.md @@ -0,0 +1,24 @@ +--- +title: Porting NDIS 6.x drivers to NDIS 6.50 +description: NDIS 6.50 is substantially the same as NDIS 6.40. For detailed information about new features for NDIS 6.50, see Introduction to NDIS 6.50. +ms.assetid: ADB2C602-C115-43ED-B77C-BB18C4AE6E45 +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Porting NDIS 6.x drivers to NDIS 6.50 + +NDIS 6.50 is substantially the same as NDIS 6.40. For detailed information about new features for NDIS 6.50, including implementation and compilation details specific to this version of NDIS, see [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md). + +If you are porting an NDIS 6.x driver to NDIS 6.50, you should be familiar with the changes to each version between your driver's version and 6.50. For more information about previous NDIS 6.x versions, see the following topics: + +- [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) +- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-60.md b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-60.md new file mode 100644 index 0000000000..06dcf7b245 --- /dev/null +++ b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-60.md @@ -0,0 +1,25 @@ +--- +title: Porting NDIS 6.x drivers to NDIS 6.60 +description: NDIS 6.60 is substantially the same as NDIS 6.50. For detailed information about new features for NDIS 6.60, see Introduction to NDIS 6.60. +ms.assetid: EEDB1D20-BF50-4970-ACCB-FA289C8A7065 +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Porting NDIS 6.x drivers to NDIS 6.60 + +NDIS 6.60 is substantially the same as NDIS 6.50. For detailed information about new features for NDIS 6.60, including implementation and compilation details specific to this version of NDIS, see [Introduction to NDIS 6.60](introduction-to-ndis-6-60.md). + +If you are porting an NDIS 6.x driver to NDIS 6.60, you should be familiar with the changes to each version between your driver's version and 6.60. For more information about previous NDIS 6.x versions, see the following topics: + +- [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md) +- [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) +- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-70.md b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-70.md new file mode 100644 index 0000000000..faf0ad2ea6 --- /dev/null +++ b/windows-driver-docs-pr/network/porting-ndis-6-x-drivers-to-ndis-6-70.md @@ -0,0 +1,28 @@ +--- +title: Porting NDIS 6.x drivers to NDIS 6.70 +description: For NDIS protocol, filter, and intermediate drivers, NDIS 6.70 is substantially the same as NDIS 6.60. For detailed information about new features for NDIS 6.70, see Introduction to NDIS 6.70. +ms.assetid: DB099908-E8EF-4D4B-95FF-9B17702D4A7B +ms.author: windowsdriverdev +ms.date: 06/01/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Porting NDIS 6.x drivers to NDIS 6.70 + +For NDIS miniport, protocol, filter, and intermediate drivers, NDIS 6.70 is substantially the same as NDIS 6.60. Starting in NDIS 6.70, however, NDIS driver developers can also write a NIC driver using the new Network Adapter WDF Class Extension, a.k.a. [NetAdapterCx](../netcx/index.md). To port an NDIS 6.x miniport driver to the NetAdapter class extension, see [Porting NDIS miniport drivers to NetAdapter class extension](../netcx/porting-ndis-to-netadapter-cx.md). + +For detailed information about new features for NDIS 6.70, including implementation and compilation details specific to this version of NDIS, see [Introduction to NDIS 6.70](introduction-to-ndis-6-70.md). + +If you are porting an NDIS 6.x miniport, protocol, filter, or intermediate driver to NDIS 6.70, you should be familiar with the changes to each version between your driver's version and 6.70. For more information about previous NDIS 6.x versions, see the following topics: + +- [Introduction to NDIS 6.60](introduction-to-ndis-6-60.md) +- [Introduction to NDIS 6.50](introduction-to-ndis-6-50.md) +- [Introduction to NDIS 6.40](introduction-to-ndis-6-40.md) +- [Introduction to NDIS 6.30](introduction-to-ndis-6-30.md) +- [Introduction to NDIS 6.20](introduction-to-ndis-6-20.md) +- [Introduction to NDIS 6.1](introduction-to-ndis-6-1.md) +- [Introduction to NDIS 6.0](introduction-to-ndis-6-0.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/porting-ndis-drivers-to-newer-ndis-versions.md b/windows-driver-docs-pr/network/porting-ndis-drivers-to-newer-ndis-versions.md index 2f6a040d0a..0de1bc38b4 100644 --- a/windows-driver-docs-pr/network/porting-ndis-drivers-to-newer-ndis-versions.md +++ b/windows-driver-docs-pr/network/porting-ndis-drivers-to-newer-ndis-versions.md @@ -14,10 +14,13 @@ ms.technology: windows-devices This section describes the steps that are involved with porting an NDIS driver that was developed for an earlier version of NDIS to newer versions of NDIS. This section includes the following topics: -- [Porting NDIS 6.x Drivers to NDIS 6.40](porting-ndis-6-x-drivers-to-ndis-6-40.md) -- [Porting NDIS 6.x Drivers to NDIS 6.30](porting-ndis-6-x-drivers-to-ndis-6-30.md) -- [Porting NDIS 6.x Drivers to NDIS 6.20](porting-ndis-6-x-drivers-to-ndis-6-20.md) -- [Porting NDIS 5.x Drivers to NDIS 6.0](porting-ndis-5-x-drivers-to-ndis-6-0.md) +- [Porting NDIS 6.x drivers to NDIS 6.70](porting-ndis-6-x-drivers-to-ndis-6-70.md) +- [Porting NDIS 6.x drivers to NDIS 6.60](porting-ndis-6-x-drivers-to-ndis-6-60.md) +- [Porting NDIS 6.x drivers to NDIS 6.50](porting-ndis-6-x-drivers-to-ndis-6-50.md) +- [Porting NDIS 6.x Drivers to NDIS 6.40](porting-ndis-6-x-drivers-to-ndis-6-40.md) +- [Porting NDIS 6.x Drivers to NDIS 6.30](porting-ndis-6-x-drivers-to-ndis-6-30.md) +- [Porting NDIS 6.x Drivers to NDIS 6.20](porting-ndis-6-x-drivers-to-ndis-6-20.md) +- [Porting NDIS 5.x Drivers to NDIS 6.0](porting-ndis-5-x-drivers-to-ndis-6-0.md)   diff --git a/windows-driver-docs-pr/network/power-management-status-indications.md b/windows-driver-docs-pr/network/power-management-status-indications.md new file mode 100644 index 0000000000..17089887b6 --- /dev/null +++ b/windows-driver-docs-pr/network/power-management-status-indications.md @@ -0,0 +1,44 @@ +--- +title: Power Management Status Indications +author: windows-driver-content +description: Power Management Status Indications +ms.assetid: f6a8fef7-2bdd-42b1-8afa-c93a7d6dcce6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - NDIS 6.20 WDK + - power management status indications + - power management WDK networking NDIS 6.20 status indications + - power management WDK NDIS 6.20 status indications +--- + +# Power Management Status Indications + + +## + + +This section includes the reference topics for the status indications that are used in the NDIS 6.20 power management interface. This interface is supported in NDIS 6.20 and later. + +This section includes the following reference topics: + +[**NDIS\_STATUS\_PM\_CAPABILITIES\_CHANGE**](ndis-status-pm-capabilities-change.md) + +[**NDIS\_STATUS\_PM\_HARDWARE\_CAPABILITIES**](ndis-status-pm-hardware-capabilities.md) + +[**NDIS\_STATUS\_PM\_OFFLOAD\_REJECTED**](ndis-status-pm-offload-rejected.md) + +[**NDIS\_STATUS\_PM\_WOL\_PATTERN\_REJECTED**](ndis-status-pm-wol-pattern-rejected.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Power%20Management%20Status%20Indications%20%20RELEASE:%20%287/6/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/reassembled-net-buffer-list-structures.md b/windows-driver-docs-pr/network/reassembled-net-buffer-list-structures.md index 2b2312993a..85b7b6d080 100644 --- a/windows-driver-docs-pr/network/reassembled-net-buffer-list-structures.md +++ b/windows-driver-docs-pr/network/reassembled-net-buffer-list-structures.md @@ -1,6 +1,6 @@ --- -title: Reassembled NET\_BUFFER\_LIST Structures -description: Reassembled NET\_BUFFER\_LIST Structures +title: Reassembled NET_BUFFER_LIST Structures +description: Reassembled NET_BUFFER_LIST Structures ms.assetid: 0bfbfef3-c3ac-4add-b3b8-a4c3a96c8baa keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/receive-filter-status-indications.md b/windows-driver-docs-pr/network/receive-filter-status-indications.md new file mode 100644 index 0000000000..b32e46e4bb --- /dev/null +++ b/windows-driver-docs-pr/network/receive-filter-status-indications.md @@ -0,0 +1,33 @@ +--- +title: Receive Filter Status Indications +author: windows-driver-content +description: Receive Filter Status Indications +ms.assetid: 7AB6FC3B-DBBF-4561-B975-455E78AB8285 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Receive Filter Status Indications + + +## + + +This section describes the following NDIS status indications that can be used by a miniport driver miniport driver for receive filtering: + +[**NDIS\_STATUS\_RECEIVE\_FILTER\_CURRENT\_CAPABILITIES**](ndis-status-receive-filter-current-capabilities.md) + +[**NDIS\_STATUS\_RECEIVE\_FILTER\_HARDWARE\_CAPABILITIES**](ndis-status-receive-filter-hardware-capabilities.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Receive%20Filter%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/receive-scaling-macros.md b/windows-driver-docs-pr/network/receive-scaling-macros.md new file mode 100644 index 0000000000..b90b9da4fd --- /dev/null +++ b/windows-driver-docs-pr/network/receive-scaling-macros.md @@ -0,0 +1,47 @@ +--- +title: Receive Side Scaling Macros +author: windows-driver-content +description: Receive Side Scaling Macros +ms.assetid: 0bee7c9d-a528-43c2-b8dc-4fb30dcc256a +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Receive Side Scaling Macros + + +## + + +This section includes the following topics: + +[**NET\_BUFFER\_LIST\_SET\_HASH\_TYPE**](net-buffer-list-set-hash-type.md) + +[**NET\_BUFFER\_LIST\_SET\_HASH\_FUNCTION**](net-buffer-list-set-hash-function.md) + +[**NET\_BUFFER\_LIST\_SET\_HASH\_VALUE**](net-buffer-list-set-hash-value.md) + +[**NET\_BUFFER\_LIST\_GET\_HASH\_TYPE**](net-buffer-list-get-hash-type.md) + +[**NET\_BUFFER\_LIST\_GET\_HASH\_FUNCTION**](net-buffer-list-get-hash-function.md) + +[**NET\_BUFFER\_LIST\_GET\_HASH\_VALUE**](net-buffer-list-get-hash-value.md) + +[**NDIS\_RSS\_HASH\_INFO\_FROM\_TYPE\_AND\_FUNC**](ndis-rss-hash-info-from-type-and-func.md) + +[**NDIS\_RSS\_HASH\_TYPE\_FROM\_HASH\_INFO**](ndis-rss-hash-type-from-hash-info.md) + +[**NDIS\_RSS\_HASH\_FUNC\_FROM\_HASH\_INFO**](ndis-rss-hash-func-from-hash-info.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Receive%20Side%20Scaling%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/receiving-net-buffer-structures-in-condis-drivers.md b/windows-driver-docs-pr/network/receiving-net-buffer-structures-in-condis-drivers.md index 68e94f4893..502c44898e 100644 --- a/windows-driver-docs-pr/network/receiving-net-buffer-structures-in-condis-drivers.md +++ b/windows-driver-docs-pr/network/receiving-net-buffer-structures-in-condis-drivers.md @@ -1,6 +1,6 @@ --- -title: Receiving NET\_BUFFER Structures in CoNDIS Drivers -description: Receiving NET\_BUFFER Structures in CoNDIS Drivers +title: Receiving NET_BUFFER Structures in CoNDIS Drivers +description: Receiving NET_BUFFER Structures in CoNDIS Drivers ms.assetid: b3bbd3ef-9206-4edc-8f7a-4ce896d77150 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/relationships-between-net-buffer-list-generations.md b/windows-driver-docs-pr/network/relationships-between-net-buffer-list-generations.md index 95aa918505..f136766910 100644 --- a/windows-driver-docs-pr/network/relationships-between-net-buffer-list-generations.md +++ b/windows-driver-docs-pr/network/relationships-between-net-buffer-list-generations.md @@ -1,6 +1,6 @@ --- -title: Relationships Between NET\_BUFFER\_LIST Generations -description: Relationships Between NET\_BUFFER\_LIST Generations +title: Relationships Between NET_BUFFER_LIST Generations +description: Relationships Between NET_BUFFER_LIST Generations ms.assetid: 37b3b08d-4656-47bc-b656-a03f208e4311 keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/remote-ndis--rndis-2.md b/windows-driver-docs-pr/network/remote-ndis--rndis-2.md index 32ec355dd5..8dd64a46f9 100644 --- a/windows-driver-docs-pr/network/remote-ndis--rndis-2.md +++ b/windows-driver-docs-pr/network/remote-ndis--rndis-2.md @@ -33,6 +33,7 @@ This section includes: [Remote NDIS To USB Mapping](remote-ndis-to-usb-mapping.md) +     diff --git a/windows-driver-docs-pr/network/remote-ndis-communication.md b/windows-driver-docs-pr/network/remote-ndis-communication.md index 65635b6d55..45c61c4415 100644 --- a/windows-driver-docs-pr/network/remote-ndis-communication.md +++ b/windows-driver-docs-pr/network/remote-ndis-communication.md @@ -1,11 +1,10 @@ --- -title: Remote NDIS Communication -description: Remote NDIS Communication -ms.assetid: c9fd6e3b-bdcc-48f7-8b5a-d571d20917df -keywords: -- Remote NDIS WDK networking , communication +title: 'Remote NDIS Communication' +author: windows-driver-content +Description: 'Remote NDIS Communication' +ms.assetid: abaa4434-4043-4265-92b9-81383c2080ce ms.author: windowsdriverdev -ms.date: 04/20/2017 +ms.date: 07/31/2017 ms.topic: article ms.prod: windows-hardware ms.technology: windows-devices @@ -14,14 +13,14 @@ ms.technology: windows-devices # Remote NDIS Communication -## +## This section includes the following topics: -[Remote NDIS Control Messages](https://msdn.microsoft.com/library/windows/hardware/ff570597) +[Remote NDIS Control Messages](remote-ndis-control-messages.md) -[Remote NDIS Data Message](https://msdn.microsoft.com/library/windows/hardware/ff570604) +[Remote NDIS Data Message](remote-ndis-data-message.md) [Setting Device-Specific Parameters](setting-device-specific-parameters.md) @@ -33,11 +32,5 @@ This section includes the following topics: [Status Values](status-values.md) -  - -  - - - - - +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Remote%20NDIS%20%28RNDIS%29%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/remote-ndis-control-messages.md b/windows-driver-docs-pr/network/remote-ndis-control-messages.md new file mode 100644 index 0000000000..ac0eab4481 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-control-messages.md @@ -0,0 +1,53 @@ +--- +title: Remote NDIS Control Messages +author: windows-driver-content +Description: Remote NDIS Control Messages +ms.assetid: b9cb2ef3-c664-4cb7-a235-229e9465a6b9 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote NDIS Control Messages + + +## + + +The following Remote NDIS control messages must be supported by an Ethernet 802.3 connectionless device: + +[**REMOTE\_NDIS\_INITIALIZE\_MSG**](remote-ndis-initialize-msg.md) + +[**REMOTE\_NDIS\_INITIALIZE\_CMPLT**](remote-ndis-initialize-cmplt.md) + +[**REMOTE\_NDIS\_HALT\_MSG**](remote-ndis-halt-msg.md) + +[**REMOTE\_NDIS\_QUERY\_MSG**](remote-ndis-query-msg.md) + +[**REMOTE\_NDIS\_QUERY\_CMPLT**](remote-ndis-query-cmplt.md) + +[**REMOTE\_NDIS\_SET\_MSG**](remote-ndis-set-msg.md) + +[**REMOTE\_NDIS\_SET\_CMPLT**](remote-ndis-set-cmplt.md) + +[**REMOTE\_NDIS\_RESET\_MSG**](remote-ndis-reset-msg.md) + +[**REMOTE\_NDIS\_RESET\_CMPLT**](remote-ndis-reset-cmplt.md) + +[**REMOTE\_NDIS\_INDICATE\_STATUS\_MSG**](remote-ndis-indicate-status-msg.md) + +[**REMOTE\_NDIS\_KEEPALIVE\_MSG**](remote-ndis-keepalive-msg.md) + +[**REMOTE\_NDIS\_KEEPALIVE\_CMPLT**](remote-ndis-keepalive-cmplt.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Remote%20NDIS%20Control%20Messages%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-control-messages2.md b/windows-driver-docs-pr/network/remote-ndis-control-messages2.md deleted file mode 100644 index 8bcb2ec57a..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-control-messages2.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Remote NDIS Control Messages -description: Remote NDIS Control Messages -ms.assetid: aefeb07c-f77e-40ca-adbd-fcc724a764aa -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# Remote NDIS Control Messages - - -## - - -Remote NDIS control messages are sent by the host to the Remote NDIS device and by the Remote NDIS device to the host. All Remote NDIS control messages indicate the type of message being sent and the total length of the message, from the beginning of the message. - -The following Remote NDIS control messages must be supported by an Ethernet 802.3 connectionless device. - - ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Message IdentifierValueDescription

[REMOTE_NDIS_INITIALIZE_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570624)

0x00000002

Initialize the device.

[REMOTE_NDIS_INITIALIZE_CMPLT](https://msdn.microsoft.com/library/windows/hardware/ff570621)

0x80000002

Device response to initialization request.

[REMOTE_NDIS_HALT_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570613)

0x00000003

Halt the device. This is the only host control message that doesn't get a response.

[REMOTE_NDIS_QUERY_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570641)

0x00000004

Send a 'query' OID.

[REMOTE_NDIS_QUERY_CMPLT](https://msdn.microsoft.com/library/windows/hardware/ff570638)

0x80000004

Device response to 'query' OID request.

[REMOTE_NDIS_SET_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570654)

0x00000005

Send a 'set' OID.

[REMOTE_NDIS_SET_CMPLT](https://msdn.microsoft.com/library/windows/hardware/ff570651)

0x80000005

Device response to 'set' OID request.

[REMOTE_NDIS_RESET_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570648)

0x00000006

Perform a soft reset on the device.

[REMOTE_NDIS_RESET_CMPLT](https://msdn.microsoft.com/library/windows/hardware/ff570645)

0x80000006

Device responses to reset request.

[REMOTE_NDIS_INDICATE_STATUS_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570617)

0x00000007

Indicates 802.3 link state or undefined message error.

[REMOTE_NDIS_KEEPALIVE_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570629)

0x00000008

During idle periods, sent every few seconds to check that the device is still responsive (may optionally also be sent by the device).

[REMOTE_NDIS_KEEPALIVE_CMPLT](https://msdn.microsoft.com/library/windows/hardware/ff570626)

0x80000008

Device response to keep alive message.

- -  - -For more details on these messages, see [Remote NDIS Control Messages Reference](https://msdn.microsoft.com/library/windows/hardware/ff570597). - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-data-message.md b/windows-driver-docs-pr/network/remote-ndis-data-message.md new file mode 100644 index 0000000000..c14f526c55 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-data-message.md @@ -0,0 +1,33 @@ +--- +title: Remote NDIS Data Message +author: windows-driver-content +Description: Remote NDIS Data Message +ms.assetid: 99ba2f83-9e2c-4681-a4ff-d61fedb20884 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Remote NDIS Data Message + + +## + + +A Remote NDIS device encapsulates NDIS packets to transfer them across the data channel. Data messages are used to do this because they can contain out-of-band (OOB) data or per-packet information. + +The data message that is used to encapsulate data for transfer across the data channel is described in the following topic: + +[**REMOTE\_NDIS\_PACKET\_MSG**](remote-ndis-packet-msg.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Remote%20NDIS%20Data%20Message%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-data-message2.md b/windows-driver-docs-pr/network/remote-ndis-data-message2.md deleted file mode 100644 index ba1a197252..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-data-message2.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Remote NDIS Data Message -description: Remote NDIS Data Message -ms.assetid: 04260f0b-b344-4a31-8978-828a4a4661a5 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# Remote NDIS Data Message - - -## - - -A Remote NDIS device transfers NDIS packets, encapsulated as [REMOTE\_NDIS\_PACKET\_MSG](https://msdn.microsoft.com/library/windows/hardware/ff570635) across the data channel. REMOTE\_NDIS\_PACKET\_MSG may contain out of band (OOB) data and/or per-packet information. - -For more details on these messages, see [Remote NDIS Data Message Reference](https://msdn.microsoft.com/library/windows/hardware/ff570604). - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-halt-msg.md b/windows-driver-docs-pr/network/remote-ndis-halt-msg.md new file mode 100644 index 0000000000..1e8764777a --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-halt-msg.md @@ -0,0 +1,92 @@ +--- +title: 'REMOTE\_NDIS\_HALT\_MSG' +author: windows-driver-content +Description: 'This message is sent by the host to terminate the network connection.' +ms.assetid: ad7802ff-20ee-4228-b236-a2ca39e8c478 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_HALT\_MSG + + +This message is sent by the host to terminate the network connection. Unlike the other host-initiated control messages, the device does not respond to REMOTE\_NDIS\_HALT\_MSG. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000003.

4

4

MessageLength

Specifies in bytes the total length of this message from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

+ +  + +Remarks +------- + +It is optional for the device to implement REMOTE\_NDIS\_HALT\_MSG. If implemented, the device sends this message to the host through the control channel only when the device is in a state initialized by Remote NDIS. The device must terminate all communication immediately after sending this message. Sending this message causes the device to enter a state not initialized by Remote NDIS. + +All outstanding requests and packets should be discarded on receipt of this message. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_HALT_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-halt-msg2.md b/windows-driver-docs-pr/network/remote-ndis-halt-msg2.md deleted file mode 100644 index d064a87f9b..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-halt-msg2.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: REMOTE\_NDIS\_HALT\_MSG -description: REMOTE\_NDIS\_HALT\_MSG -ms.assetid: 2e3a15fb-457d-4e81-b5ed-8d77e8e77901 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_HALT\_MSG - - -## - - -[**REMOTE\_NDIS\_HALT\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570613) is sent by either the host or the Remote NDIS device in order to terminate the network connection. Unlike the other host initiated control messages, there is no device response to **REMOTE\_NDIS\_HALT\_MSG**. The message may be sent at any time that the device is in a state not initialized by Remote NDIS. All outstanding requests and packets should be discarded on receipt of this message. - -It is optional for the device to implement sending the message [**REMOTE\_NDIS\_HALT\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570613). If implemented, the device sends this message to the host through the control channel only when the device is in a state not yet initialized by Remote NDIS. The device must terminate all communication immediately after sending this message. Sending this message causes the device to enter a state not initialized by Remote NDIS. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg.md b/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg.md new file mode 100644 index 0000000000..24262e2a91 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg.md @@ -0,0 +1,145 @@ +--- +title: 'REMOTE\_NDIS\_INDICATE\_STATUS\_MSG' +author: windows-driver-content +Description: 'This message is sent from a Remote NDIS device to a host to indicate a change in the status of the device.' +ms.assetid: 768aad13-3da6-436c-a7ba-d420af34643e +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_INDICATE\_STATUS\_MSG + + +This message is sent from a Remote NDIS device to a host to indicate a change in the status of the device. A REMOTE\_NDIS\_INDICATE\_STATUS\_MSG message can also be used to indicate an error event, such as an unrecognized message. The Remote NDIS device may send this message at any time that it is in a state initialized by Remote NDIS. There is no response to this message. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000007.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

Status

Specifies the current status of the host request.

12

4

StatusBufferLength

Specifies the length of the status data, in bytes.

16

4

StatusBufferOffset

Specifies the byte offset, from the beginning of this message, at which Rndis_Diagnostic_Info status data for the device indication is located.

+ +  + +Remarks +------- + +The most common use of REMOTE\_NDIS\_INDICATE\_STATUS\_MSG is to indicate the state of the link for an 802.3 device. A status value of RNDIS\_STATUS\_MEDIA\_CONNECT indicates a transition from disconnected (for example no 802.3 link pulse) to connected state (802.3 link pulse detected). A status value of RNDIS\_STATUS\_MEDIA\_DISCONNECT indicates a transition from connected to disconnected state. The device must send REMOTE\_NDIS\_INDICATE\_STATUS\_MSG with one of these values every time the 802.3 link state changes. No status buffer is required to return these two common indications. + +In the specific case where this message is sent in response to a host message that the device could not handle, the *Status* field must be set to RNDIS\_STATUS\_INVALID\_DATA, and the Rndis\_Diagnostic\_Info status buffer is formatted as follows. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

DiagStatus

Contains status information about the error itself (for example, RNDIS_STATUS_NOT_SUPPORTED)

4

4

ErrorOffset

Specifies the zero-based byte offset in the original message at which the error was detected.

+ +  + +If the error condition was caused by an Remote NDIS message (for example, the device can't recognize a particular RNDIS message), then the device should append the original message at the end of the status message defined above. + +This message is used to report an error condition only in circumstances where the device is not able to generate a response message with appropriate status. Examples of appropriate usage are: + +- On receiving a message with unsupported message type. + +- On receiving a [**REMOTE\_NDIS\_PACKET\_MSG**](remote-ndis-packet-msg.md) with unacceptable contents. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_INDICATE_STATUS_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg2.md b/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg2.md deleted file mode 100644 index 2e79d48b46..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-indicate-status-msg2.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: REMOTE\_NDIS\_INDICATE\_STATUS\_MSG -description: REMOTE\_NDIS\_INDICATE\_STATUS\_MSG -ms.assetid: 1858ac41-30d2-4ae0-86ba-ebdf6dc90d5a -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_INDICATE\_STATUS\_MSG - - -## - - -The device may send [**REMOTE\_NDIS\_INDICATE\_STATUS\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570617) to the host through the control channel in an unsolicited fashion at any time that the device is in a state initialized by Remote NDIS. This message is used to indicate a change in the status of the device. A common use of this message is to notify the host of changes in link state (media connect status), using RNDIS\_STATUS\_MEDIA\_CONNECT and RNDIS\_STATUS\_MEDIA\_DISCONNECT status values. The device must send **REMOTE\_NDIS\_INDICATE\_STATUS\_MSG** with one of these status values whenever its link state changes. **REMOTE\_NDIS\_INDICATE\_STATUS\_MSG** can also be used to indicate an error event, such as an unrecognized message. - -In the specific case where this message is sent in response to a host message that the device could not handle, the returned status value must be set to RNDIS\_STATUS\_INVALID\_DATA, and the status buffer is formatted to contain the following: - -- Additional status information about the error itself (for example, RNDIS\_STATUS\_NOT\_SUPPORTED). - -- Zero-based byte offset in the original message where the error was detected. - -If the error condition was caused by an Remote NDIS message, for example the device can't recognize a particular Remote NDIS message, the device should append the original message at the end of the status message defined above. - -[**REMOTE\_NDIS\_INDICATE\_STATUS\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570617) is used to report an error event only in circumstances where the device is not able to generate a response message with appropriate status. Examples of appropriate usage are: - -- On receiving a message with unsupported message type. - -- On receiving a [**REMOTE\_NDIS\_PACKET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570635) with unacceptable contents. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt.md b/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt.md new file mode 100644 index 0000000000..a88b47474d --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt.md @@ -0,0 +1,159 @@ +--- +title: 'REMOTE\_NDIS\_INITIALIZE\_CMPLT' +author: windows-driver-content +ms.assetid: e1e057bf-aa92-4b90-b993-a82cc260ff7f +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_INITIALIZE\_CMPLT + + +The REMOTE\_NDIS\_INITIALIZE\_CMPLT message is sent by the Remote NDIS device to the host in response to a [**REMOTE\_NDIS\_INITIALIZE\_MSG**](remote-ndis-initialize-msg.md) message. In the REMOTE\_NDIS\_INITIALIZE\_CMPLT message, the device reports its medium type, Remote NDIS version numbers, and its type (connectionless or connection-oriented or both). + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x80000002.

4

4

MessageLength

Specifies in bytes the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

12

4

Status

Specifies RNDIS_STATUS_SUCCESS if the device initialized successfully; otherwise, it specifies an error code that indicates the failure.

16

4

MajorVersion

Specifies the highest Remote NDIS major protocol version supported by the device.

20

4

MinorVersion

Specifies the highest Remote NDIS minor protocol version supported by the device.

24

4

DeviceFlags

Specifies the miniport driver type as either connectionless or connection-oriented. This value can be one of the following:

+

RNDIS_DF_CONNECTIONLESS 0x00000001

+

RNDIS_DF_CONNECTION_ORIENTED 0x00000002

28

4

Medium

Specifies the medium supported by the device. Set to RNDIS_MEDIUM_802_3 (0x00000000)

32

4

MaxPacketsPerMessage

Specifies the maximum number of Remote NDIS data messages that the device can handle in a single transfer to it. This value should be at least one.

36

4

MaxTransferSize

Specifies the maximum size in bytes of any single bus data transfer that the device expects to receive from the host.

40

4

PacketAlignmentFactor

Specifies the byte alignment that the device expects for each Remote NDIS message that is part of a multimessage transfer to it. This value is specified in powers of 2. For example, this value is set to three to indicate 8-byte alignment. This value has a maximum setting of seven, which specifies 128-byte alignment.

44

4

AFListOffset

Reserved for connection-oriented devices. Set value to zero.

48

4

AFListSize

Reserved for connection-oriented devices. Set value to zero.

+ +  + +Remarks +------- + +The *Status* field should be set to RNDIS\_STATUS\_SUCCESS if the device initialized successfully; otherwise, it is set to an error code that indicates the failure. The device should return the highest Remote NDIS protocol version that it can support, in *MajorVersion* and *MinorVersion*--the combined version number should be less than or equal to the version number the host specified in the [**REMOTE\_NDIS\_INITIALIZE\_MSG**](remote-ndis-initialize-msg.md) message. + +The *AFListSize* and *AFListOffset* fields are relevant only for connection-oriented devices that include a call manager. Connectionless devices should set these fields to zero. + +In this message, the Remote NDIS device indicates the following: + +- Highest Remote NDIS protocol version number that the device can support. The combined version number should be less than or equal to the version number that the host specifies in the [**REMOTE\_NDIS\_INITIALIZE\_MSG**](remote-ndis-initialize-msg.md) message. This allows the device to fall back to a compatibility mode when the host implements a Remote NDIS protocol version that is lower than that supported by the device. + +- Maximum size in bytes of a single data transfer that the device expects to receive from the host. The device can specify the byte alignment it expects for each Remote NDIS message that is part of a multimessage transfer to it. This alignment value is specified in terms of powers of two. For example, this value is set to 3 to indicate 8-byte alignment. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_INITIALIZE_CMPLT%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt2.md b/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt2.md deleted file mode 100644 index 31f12ca69c..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-initialize-cmplt2.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: REMOTE\_NDIS\_INITIALIZE\_CMPLT -description: REMOTE\_NDIS\_INITIALIZE\_CMPLT -ms.assetid: 1e8cf7f0-0c18-415f-bc2c-9758b9ea51d2 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_INITIALIZE\_CMPLT - - -## - - -[**REMOTE\_NDIS\_INITIALIZE\_CMPLT**](https://msdn.microsoft.com/library/windows/hardware/ff570621) is sent by the Remote NDIS device to the host in response to a [**REMOTE\_NDIS\_INITIALIZE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570624) message. - -In this message, the Remote NDIS device indicates the following: - -- Remote NDIS message ID value. This value is used to match the messages sent by the host with device responses. - -- Status value of RNDIS\_STATUS\_SUCCESS if the device initialized successfully, otherwise the status value is set to an error code indicating the failure. - -- Highest Remote NDIS protocol version number that the device can support. The combined version number should be less than or equal to the version number specified by the host in the [**REMOTE\_NDIS\_INITIALIZE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570624) message. This allows the device to fall back to a compatibility mode when the host implements a Remote NDIS protocol version that is lower than that supported by the device. - -- Medium type supported by the device. Set to RNDIS\_MEDIUM\_802\_3 (0x00000000). - -- Maximum number of Remote NDIS data messages that the device can handle in a single transfer to it. This value should be at least one. - -- Maximum size, in bytes, of a single data transfer that the device expects to receive from the host. The device can specify the byte alignment it expects for each Remote NDIS message that is part of a multimessage transfer to it. This alignment value is specified in terms of powers of two. For example, this value is set to 3 to indicate 8-byte alignment. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-initialize-msg.md b/windows-driver-docs-pr/network/remote-ndis-initialize-msg.md new file mode 100644 index 0000000000..7215c8c009 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-initialize-msg.md @@ -0,0 +1,103 @@ +--- +title: 'REMOTE\_NDIS\_INITIALIZE\_MSG' +author: windows-driver-content +Description: 'This message is sent by the host to a Remote NDIS device to initialize the network connection.' +ms.assetid: 08735ee8-7a4c-4a3d-9082-27c61cfd15e8 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_INITIALIZE\_MSG + + +This message is sent by the host to a Remote NDIS device to initialize the network connection. It is sent through the control channel and only when the device is not in a state initialized by Remote NDIS. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000002.

4

4

MessageLength

Specifies in bytes the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

12

4

MajorVersion

Specifies the Remote NDIS protocol version implemented by the host. The current specification uses RNDIS_MAJOR_VERSION = 1.

16

4

MinorVersion

Specifies the Remote NDIS protocol version implemented by the host. The current specification uses RNDIS_MINOR_VERSION = 0.

20

4

MaxTransferSize

Specifies the maximum size in bytes of any single bus data transfer that the host expects to receive from the device. Typically, each bus data transfer accommodates a single Remote NDIS message. However, the device may bundle several Remote NDIS messages that contain data packets into a single transfer (see [REMOTE_NDIS_PACKET_MSG](remote-ndis-packet-msg.md)).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_INITIALIZE_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-initialize-msg2.md b/windows-driver-docs-pr/network/remote-ndis-initialize-msg2.md deleted file mode 100644 index 1ca22d8752..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-initialize-msg2.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: REMOTE\_NDIS\_INITIALIZE\_MSG -description: REMOTE\_NDIS\_INITIALIZE\_MSG -ms.assetid: bc63390a-85b3-4df2-953d-7dc9fb01a787 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_INITIALIZE\_MSG - - -## - - -[**REMOTE\_NDIS\_INITIALIZE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570624) is sent by the host to a Remote NDIS device to initialize the network connection. It is sent through the control channel and only when the device is in a state not yet initialized by Remote NDIS. The message indicates the following: - -- Maximum size, in bytes, of any single bus data transfer that the host expects to receive from the device. Typically, each bus data transfer accommodates a single Remote NDIS message. However, as described in Remote NDIS Data Message, the device may bundle several Remote NDIS messages containing data packets into a single transfer. - -- Major and minor Remote NDIS protocol version implemented by the host. This value is the highest Remote NDIS protocol version supported by the host. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt.md b/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt.md new file mode 100644 index 0000000000..e8bdfd54aa --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt.md @@ -0,0 +1,96 @@ +--- +title: 'REMOTE\_NDIS\_KEEPALIVE\_CMPLT' +author: windows-driver-content +Description: 'A Remote NDIS device will respond to a REMOTE\_NDIS\_KEEPALIVE\_MSG message from the host by sending back a REMOTE\_NDIS\_KEEPALIVE\_CMPLT response message.' +ms.assetid: c090b781-73f1-4a7a-a0a2-60af366daa77 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_KEEPALIVE\_CMPLT + + +A Remote NDIS device will respond to a [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](remote-ndis-keepalive-msg.md) message from the host by sending back a REMOTE\_NDIS\_KEEPALIVE\_CMPLT response message. If the returned Status is not RNDIS\_STATUS\_SUCCESS, the host will send [**REMOTE\_NDIS\_RESET\_MSG**](remote-ndis-reset-msg.md) to reset the device. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x80000008.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

12

4

Status

Specifies the current status of the device. If the returned Status is not RNDIS_STATUS_SUCCESS, the host will send an [REMOTE_NDIS_RESET_MSG](remote-ndis-reset-msg.md) message to reset the device.

+ +  + +Remarks +------- + +If the device implements the option of sending [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](remote-ndis-keepalive-msg.md), the host will respond with REMOTE\_NDIS\_KEEPALIVE\_CMPLT through the control channel. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_KEEPALIVE_CMPLT%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt2.md b/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt2.md deleted file mode 100644 index c2b6b65efe..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-keepalive-cmplt2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_KEEPALIVE\_CMPLT -description: REMOTE\_NDIS\_KEEPALIVE\_CMPLT -ms.assetid: 07267e90-a0e5-41ac-8c0b-fca27f617e23 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_KEEPALIVE\_CMPLT - - -## - - -A Remote NDIS device will respond to a [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570629) message from the host by sending back a [**REMOTE\_NDIS\_KEEPALIVE\_CMPLT**](https://msdn.microsoft.com/library/windows/hardware/ff570626) response message. If the returned Status is not RNDIS\_STATUS\_SUCCESS, then the host will send [**REMOTE\_NDIS\_RESET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570648) to reset the device. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-keepalive-msg.md b/windows-driver-docs-pr/network/remote-ndis-keepalive-msg.md new file mode 100644 index 0000000000..e1ac25386b --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-keepalive-msg.md @@ -0,0 +1,98 @@ +--- +title: 'REMOTE\_NDIS\_KEEPALIVE\_MSG' +author: windows-driver-content +Description: 'The host sends this message periodically when there has been no other control or data traffic from the device to the host for the bus-defined KeepAliveTimeoutPeriod.' +ms.assetid: 7e0b329f-8ba7-488d-b99d-63e6b9bbc171 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_KEEPALIVE\_MSG + + +The host sends this message periodically when there has been no other control or data traffic from the device to the host for the bus-defined *KeepAliveTimeoutPeriod*. This message is sent by the host at least every RNDIS\_KEEPALIVE\_TIMEOUT seconds, in the absence of other message traffic, to detect the state of the remote device. The remote device may use the same message in the reverse direction, but it is not required. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000008.

4

4

MessageLength

Specifies in bytes the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

+ +  + +Remarks +------- + +The host will not send a REMOTE\_NDIS\_KEEPALIVE\_MSG message until RNDIS\_KEEPALIVE\_TIMEOUT seconds have elapsed since the last message received from the remote device. This avoids unnecessary exchange of keep-alive messages when the communication channel is active. + +The device can optionally send this message to the host as well. For example, the device may use this message to trigger a response from the host for computing round-trip delay time. If implemented, the device must send REMOTE\_NDIS\_KEEPALIVE\_MSG through the control channel and only when the device is in a state initialized by Remote NDIS. + +The host sends a **REMOTE\_NDIS\_KEEPALIVE\_MSG** message to the device through the control channel to check the health of the device. When the device is in a state initialized by Remote NDIS, the host sends this message periodically when there has been no other control or data traffic from the device to the host for the *KeepAliveTimeoutPeriod*. *KeepAliveTimeoutPeriod* is bus-dependent and is defined in the appropriate bus-mapping specifications. + +Upon receiving this message, the remote device must return a response whose *Status* field indicates whether the device solicits a [**REMOTE\_NDIS\_RESET\_MSG**](remote-ndis-reset-msg.md) message from the host. + +The device does not have to perform any specific action if it stops seeing **REMOTE\_NDIS\_KEEPALIVE\_MSG** messages from the host. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_KEEPALIVE_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-keepalive-msg2.md b/windows-driver-docs-pr/network/remote-ndis-keepalive-msg2.md deleted file mode 100644 index 26aa277586..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-keepalive-msg2.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: REMOTE\_NDIS\_KEEPALIVE\_MSG -description: REMOTE\_NDIS\_KEEPALIVE\_MSG -ms.assetid: 2da0be7e-db6d-4bc6-ad7a-20c74ed4604d -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_KEEPALIVE\_MSG - - -## - - -The host sends a [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570629) message to the device through the control channel in order to check the health of the device. When the device is in a state initialized by Remote NDIS, the host sends this message periodically when there has been no other control or data traffic from the device to the host for the *KeepAliveTimeoutPeriod*. *KeepAliveTimeoutPeriod* is bus-dependent and is defined in the appropriate bus-mapping specifications. - -Upon receiving this message, the remote device must send back a response whose *Status* field indicates whether the device solicits a [**REMOTE\_NDIS\_RESET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570648) message from the host. - -The host will not send [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570629) until the *KeepAliveTimeoutPeriod* has elapsed since the last message received from the remote device. This avoids unnecessary exchange of **REMOTE\_NDIS\_KEEPALIVE\_MSG** messages when the communication channel is active. - -The device may optionally send this message to the host as well. For example, the device may use this message to trigger a response from the host for the purpose of computing round-trip delay time. If implemented, the device must send [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570629) through the control channel and only when in a state initialized by Remote NDIS. - -The device does not need to perform any specific action if it stops seeing [**REMOTE\_NDIS\_KEEPALIVE\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570629) messages from the host. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-packet-msg.md b/windows-driver-docs-pr/network/remote-ndis-packet-msg.md new file mode 100644 index 0000000000..9dfa1e6fae --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-packet-msg.md @@ -0,0 +1,260 @@ +--- +title: 'REMOTE\_NDIS\_PACKET\_MSG' +author: windows-driver-content +Description: 'REMOTE\_NDIS\_PACKET\_MSG encapsulates NDIS data packets to form a single data message.' +ms.assetid: cc4efe94-6e2c-4201-b251-10e76cf5a553 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_PACKET\_MSG + + +REMOTE\_NDIS\_PACKET\_MSG encapsulates NDIS data packets to form a single data message. + +Concatenating multiple REMOTE\_NDIS\_PACKET\_MSG elements forms a multipacket message. Each individual REMOTE\_NDIS\_PACKET\_MSG component is constructed as described below. The difference from the single-packet message is that the *MessageLength* field in each REMOTE\_NDIS\_PACKET\_MSG header includes some additional padding bytes. These padding bytes are appended to all but the last REMOTE\_NDIS\_PACKET\_MSG so that the succeeding REMOTE\_NDIS\_PACKET\_MSG starts at an appropriate byte boundary. For messages sent from the device to the host, this padding should result in each REMOTE\_NDIS\_PACKET\_MSG starting at a byte offset that is a multiple of 8 bytes starting from the beginning of the multipacket message. When the host sends a multipacket message to the device, it will adhere to the *PacketAlignmentFactor* that the device specifies. + +The REMOTE\_NDIS\_PACKET\_MSG format is defined in the following table. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x1.

4

4

MessageLength

Message length in bytes, including appended packet data, OOB data, per-packet information data, and both internal and external padding.

8

4

DataOffset

Specifies the offset in bytes from the start of the DataOffset field of this message to the start of the data. This is an integer multiple of 4.

12

4

DataLength

Specifies the number of bytes in the data content of this message.

16

4

OOBDataOffset

Specifies the offset in bytes of the first OOB data record from the start of the DataOffset field of this message. Set to zero if there is no OOB data. Otherwise, this is an integer multiple of 4.

20

4

OOBDataLength

Specifies in bytes the total length of the OOB data.

24

4

NumOOBDataElements

Specifies the number of OOB records in this message.

28

4

PerPacketInfoOffset

Specifies in bytes the offset from the beginning of the DataOffset field in the REMOTE_NDIS_PACKET_MSG data message to the start of the first per-packet information data record. Set to zero if there is no per-packet data. Otherwise, this is an integer multiple of 4.

32

4

PerPacketInfoLength

Specifies in bytes the total length of the per-packet information contained in this message.

36

4

VcHandle

Reserved for connection-oriented devices. Set to zero.

40

4

Reserved

Reserved. Set to zero.

+ +  + +The format of a single OOB data record is indicated in the following table. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

Size

Length in bytes of this OOB header and appended OOB data and padding. This is an integer multiple of 4.

4

4

Type

None defined for 802.3 devices.

8

4

ClassInformationOffset

The byte offset from the beginning of this OOB data record to the beginning of the OOB data.

(N)

...

OOB Data

OOB Data; consult Microsoft Windows Driver Development Kit (DDK) documentation for more information.

+ +  + +**Note**   +(N) is equal to the value of *ClassInformationOffset*. + +  + +The following table defines the format of a per-packet information data record. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

Size

Length in bytes of this per-packet header and appended per-packet data and padding. This value is an integer multiple of 4.

4

4

Type

Set to one of the legal values for NDIS_PER_PACKET_INFO_FROM_PACKET, as described in the Windows 2000 Driver Development Kit (DDK).

8

4

PerPacketInformationOffset

The byte offset from the beginning of this per-packet information data record to the beginning of the per-packet information data.

(N)

...

Per-Packet Data

Per-Packet Data; consult Windows 2000 DDK documentation for more information.

+ +  + +**Note**   +(N) is equal to the value of *PerPacketInformationOffset*. + +  + +Remarks +------- + +Each REMOTE\_NDIS\_PACKET\_MSG may contain one or more OOB data records. *NumOOBDataElements* indicates the number of OOB data records in this message. The OOB data records must appear in sequence. The *OOBDataLength* field indicates the length in bytes of the entire OOB data block. The *OOBDataOffset* field indicates the byte offset from the beginning of the *DataOffset* field to the beginning of the OOB data block. For more information about OOB packet data, see the NDIS specification in the Windows 2000 DDK. + +If multiple OOB data blocks are attached to a REMOTE\_NDIS\_PACKET\_MSG message, each subsequent OOB data record must immediately follow the previous OOB record's data. + +No OOB information is currently defined for 802.3 devices. + +Each REMOTE\_NDIS\_PACKET\_MSG may contain one or more per-packet-info data records. Per-packet-info is used to convey packet metadata, such as TCP checksum. The *PerPacketInfoOffset* field indicates the byte offset from the beginning of the *DataOffset* field to the beginning of the per-packet information data record. The *OOBDataLength* field indicates the byte length of the per-packet information data record. For more information about per-packet information data, see the Windows 2000 DDK. + +If there are multiple per-packet information data blocks, each subsequent per-packet information data record must immediately follow the previous per-packet information record's data. + +A Remote NDIS device must send and receive data through NDIS data packets. The bus that the device uses determines how these packets are passed from host to device and device to host. It could be shared memory or, in the case of USB, Isoch and Bulk pipes. NDIS packets may also contain out-of-band (OOB) data as well as the data that goes across the network. + +A Remote NDIS device transfers NDIS packets, encapsulated as **REMOTE\_NDIS\_PACKET\_MSG** across the data channel. Both connectionless (such as 802.3) and connection-oriented (such as ATM) devices use the same packet message structure to facilitate common code for packet processing. Each **REMOTE\_NDIS\_PACKET\_MSG** message contains information about a single network data unit (such s an Ethernet 802.3 frame). + +For more information about out-of-band packet data or per-packet-info data, see the Windows 2000 DDK NDIS sections. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_PACKET_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-packet-msg2.md b/windows-driver-docs-pr/network/remote-ndis-packet-msg2.md deleted file mode 100644 index 3fdf110199..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-packet-msg2.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: REMOTE\_NDIS\_PACKET\_MSG -description: REMOTE\_NDIS\_PACKET\_MSG -ms.assetid: 334b0f74-7cc2-466b-9e12-5fac60911606 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_PACKET\_MSG - - -## - - -A Remote NDIS device must send and receive data through NDIS data packets. The bus used by the device determines how these packets are passed from host to device and device to host. It could be shared memory, or, in the case of USB for example, Isoch and Bulk pipes. NDIS packets may also contain out-of-band (OOB) data as well as the data that goes across the network. - -A Remote NDIS device transfers NDIS packets, encapsulated as [**REMOTE\_NDIS\_PACKET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570635) across the data channel. Both connectionless (for example, 802.3) and connection-oriented (for example, ATM) devices use the same packet message structure, in order to facilitate common code for packet processing. Each **REMOTE\_NDIS\_PACKET\_MSG** message contains information about a single network data unit (for example, an Ethernet 802.3 frame). - -Any out-of-band data records must appear in sequence. If there are multiple out-of-band data blocks attached to a [**REMOTE\_NDIS\_PACKET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570635), then each subsequent out-of-band data record must immediately follow the previous out-of-band record's data. There is no out-of-band information currently defined for Ethernet 802.3 devices. - -For more information about out-of-band packet data, see the [Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849) section. - -Each [**REMOTE\_NDIS\_PACKET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570635) may contain one or more per-packet-info data records. Per-packet-info is used to convey packet metadata such as TCP checksum. If there are multiple per-packet-info data blocks, then each subsequent per-packet-info data record must immediately follow the previous per-packet-info record's data. - -For more information about per-packet-info data, see the [Windows 2000 and Windows XP Networking Design Guide](https://msdn.microsoft.com/library/windows/hardware/ff565849) section. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-query-cmplt.md b/windows-driver-docs-pr/network/remote-ndis-query-cmplt.md new file mode 100644 index 0000000000..26afba883a --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-query-cmplt.md @@ -0,0 +1,103 @@ +--- +title: 'REMOTE\_NDIS\_QUERY\_CMPLT' +author: windows-driver-content +Description: 'A Remote NDIS device will respond to a REMOTE\_NDIS\_QUERY\_MSG message with a REMOTE\_NDIS\_QUERY\_CMPLT message.' +ms.assetid: 357e2ade-0b67-42c3-b1e1-dcc4b7ec5cda +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_QUERY\_CMPLT + + +A Remote NDIS device will respond to a [**REMOTE\_NDIS\_QUERY\_MSG**](remote-ndis-query-msg.md) message with a REMOTE\_NDIS\_QUERY\_CMPLT message. This message is used to relay the result of a query for a device parameter or statistics counter to the host. The Remote NDIS device also returns the requested information to the host in this message. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x80000004.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is copied from the REMOTE_NDIS_QUERY_MSG being responded to.

12

4

Status

Specifies the status of processing the OID query request.

16

4

InformationBufferLength

Specifies, in bytes, the length of the response data for the query. Set to zero when there is no OID result buffer.

20

4

InformationBufferOffset

Specifies the byte offset, from the beginning of the RequestId field, at which response data for the query is located. Set to zero if there is no response data.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_QUERY_CMPLT%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-query-cmplt2.md b/windows-driver-docs-pr/network/remote-ndis-query-cmplt2.md deleted file mode 100644 index 73b1bc9895..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-query-cmplt2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_QUERY\_CMPLT -description: REMOTE\_NDIS\_QUERY\_CMPLT -ms.assetid: a6c04c62-b241-49d8-98ca-3877eb378247 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_QUERY\_CMPLT - - -## - - -A Remote NDIS device will respond to a [**REMOTE\_NDIS\_QUERY\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570641) message with a REMOTE\_NDIS\_QUERY\_CMPLT message. This message is used to relay the result of a query for a device parameter or statistics counter. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-query-msg.md b/windows-driver-docs-pr/network/remote-ndis-query-msg.md new file mode 100644 index 0000000000..142cfb97f4 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-query-msg.md @@ -0,0 +1,109 @@ +--- +title: 'REMOTE\_NDIS\_QUERY\_MSG' +author: windows-driver-content +Description: 'This message is sent to a Remote NDIS device from a host when it needs to query the device for its characteristics, statistics information, or status.' +ms.assetid: 9cf79495-a115-49ce-a0cf-fa4fa2183a8a +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_QUERY\_MSG + + +This message is sent to a Remote NDIS device from a host when it needs to query the device for its characteristics, statistics information, or status. The parameter or statistics counter being queried for is identified by means of an NDIS Object Identifier (OID). The host may send REMOTE\_NDIS\_QUERY\_MSG to the device through the control channel at any time that the device is in either a state initialized by Remote NDIS. The Remote NDIS device will respond to this message by sending a REMOTE\_NDIS\_QUERY\_CMPLT to the host. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000004.

4

4

MessageLength

Specifies in bytes the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

12

4

Oid

Specifies the NDIS OID that identifies the parameter being queried.

16

4

InformationBufferLength

Specifies in bytes the length of the input data for the query. Set to zero when there is no OID input buffer.

20

4

InformationBufferOffset

Specifies the byte offset, from the beginning of the RequestId field, at which input data for the query is located. Set to zero if there is no OID input buffer.

24

4

DeviceVcHandle

Reserved for connection-oriented devices. Set to zero.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_QUERY_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-query-msg2.md b/windows-driver-docs-pr/network/remote-ndis-query-msg2.md deleted file mode 100644 index ba2919bd9d..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-query-msg2.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: REMOTE\_NDIS\_QUERY\_MSG -description: REMOTE\_NDIS\_QUERY\_MSG -ms.assetid: 36da5e67-384b-4d3c-93e6-5c09a9bc7cf6 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_QUERY\_MSG - - -## - - -[**REMOTE\_NDIS\_QUERY\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570641) is sent to a Remote NDIS device from a host when it needs to query the device for its characteristics or statistics information or status. The parameter or statistics counter being queried for is identified by means of an NDIS Object Identifier (OID). - -The host may send [**REMOTE\_NDIS\_QUERY\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570641) to the device through the control channel at any time that the device is in a state not initialized by Remote NDIS. A Remote NDIS device will respond to **REMOTE\_NDIS\_QUERY\_MSG** with information about the desired capabilities or status. - -The host sends the following information in this message: - -- Remote NDIS message ID value. This value is used to match the messages sent by the host with device's responses. - -- NDIS OID. - -- Length of the input data, if any, for the query. - -- Byte offset from the beginning of the Remote NDIS message ID value where the input data, if any, for the query is located. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-reset-cmplt.md b/windows-driver-docs-pr/network/remote-ndis-reset-cmplt.md new file mode 100644 index 0000000000..02a1ed9ef1 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-reset-cmplt.md @@ -0,0 +1,91 @@ +--- +title: 'REMOTE\_NDIS\_RESET\_CMPLT' +author: windows-driver-content +Description: 'A Remote NDIS device will respond to a REMOTE\_NDIS\_RESET\_MSG message from the host by resetting the device and returning the status of the request in the REMOTE\_NDIS\_RESET\_CMPLT message.' +ms.assetid: 80ab998f-9690-49d3-bb47-1937c832d13e +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_RESET\_CMPLT + + +A Remote NDIS device will respond to a [**REMOTE\_NDIS\_RESET\_MSG**](remote-ndis-reset-msg.md) message from the host by resetting the device and returning the status of the request in the REMOTE\_NDIS\_RESET\_CMPLT message. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x80000006.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

Status

Specifies the status of processing the Reset request.

12

4

AddressingReset

Indicates if addressing information (multicast address list, packet filter) has been lost during the concluded reset operation. If the device requires the host to resend addressing information, set this field to one; otherwise set it to zero.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_RESET_CMPLT%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-reset-cmplt2.md b/windows-driver-docs-pr/network/remote-ndis-reset-cmplt2.md deleted file mode 100644 index b70921d4ba..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-reset-cmplt2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_RESET\_CMPLT -description: REMOTE\_NDIS\_RESET\_CMPLT -ms.assetid: ae0e2c8a-3fc9-44e5-9f67-c255fdf7dbc4 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_RESET\_CMPLT - - -## - - -When the device receives [**REMOTE\_NDIS\_RESET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570648), it performs a reset and then sends [**REMOTE\_NDIS\_RESET\_CMPLT**](https://msdn.microsoft.com/library/windows/hardware/ff570645) to the host with the result status. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-reset-msg.md b/windows-driver-docs-pr/network/remote-ndis-reset-msg.md new file mode 100644 index 0000000000..efdc25a1d7 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-reset-msg.md @@ -0,0 +1,85 @@ +--- +title: 'REMOTE\_NDIS\_RESET\_MSG' +author: windows-driver-content +Description: 'This message is sent to a Remote NDIS device from a host to reset the device and return status.' +ms.assetid: b5938b0d-75bf-497f-afeb-9950b383af5e +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_RESET\_MSG + + +This message is sent to a Remote NDIS device from a host to reset the device and return status. The host may send REMOTE\_NDIS\_RESET\_MSG to the device through the control channel at any time that the device is in a state initialized by Remote NDIS. The Remote NDIS device will respond to this message by sending a REMOTE\_NDIS\_RESET\_CMPLT to the host. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000006.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

Reserved

Reserved. Set to zero.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_RESET_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-reset-msg2.md b/windows-driver-docs-pr/network/remote-ndis-reset-msg2.md deleted file mode 100644 index 7459007196..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-reset-msg2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_RESET\_MSG -description: REMOTE\_NDIS\_RESET\_MSG -ms.assetid: 9cd848c9-85f9-4bc5-bd54-2936270889d4 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_RESET\_MSG - - -## - - -A [**REMOTE\_NDIS\_RESET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570648) message is sent to a Remote NDIS device from a host through the control channel to reset the device and return status. This message may be sent at any time that the device is in a state initialized by Remote NDIS. A reset does not affect Remote NDIS message communication with the host. The device typically resets its network-side controller(s) during this process. A Remote NDIS device will respond to a **REMOTE\_NDIS\_RESET\_MSG** message with a status. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-set-cmplt.md b/windows-driver-docs-pr/network/remote-ndis-set-cmplt.md new file mode 100644 index 0000000000..79cfdcf399 --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-set-cmplt.md @@ -0,0 +1,91 @@ +--- +title: 'REMOTE\_NDIS\_SET\_CMPLT' +author: windows-driver-content +Description: 'A Remote NDIS device will respond to a REMOTE\_NDIS\_SET\_MSG message with a REMOTE\_NDIS\_SET\_CMPLT message.' +ms.assetid: 97436a5f-7516-46cf-b789-a6b1c8c067a2 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# REMOTE\_NDIS\_SET\_CMPLT + + +A Remote NDIS device will respond to a [**REMOTE\_NDIS\_SET\_MSG**](remote-ndis-set-msg.md) message with a REMOTE\_NDIS\_SET\_CMPLT message. This message is used to relay the result of setting the value of a device operational parameter to the host. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x80000005.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is copied from the REMOTE_NDIS_SET_MSG being responded to.

12

4

Status

Specifies the status of processing the OID set request.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_SET_CMPLT%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-set-cmplt2.md b/windows-driver-docs-pr/network/remote-ndis-set-cmplt2.md deleted file mode 100644 index b6d5040b8a..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-set-cmplt2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_SET\_CMPLT -description: REMOTE\_NDIS\_SET\_CMPLT -ms.assetid: 6ad576d0-07e7-433c-a193-944e03887754 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_SET\_CMPLT - - -## - - -The device sends the [**REMOTE\_NDIS\_SET\_CMPLT**](https://msdn.microsoft.com/library/windows/hardware/ff570638) message to the host in response to [**REMOTE\_NDIS\_SET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570654). This message is used to relay the result of setting the value of a device parameter. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/remote-ndis-set-msg.md b/windows-driver-docs-pr/network/remote-ndis-set-msg.md new file mode 100644 index 0000000000..3a374b114a --- /dev/null +++ b/windows-driver-docs-pr/network/remote-ndis-set-msg.md @@ -0,0 +1,110 @@ +--- +title: 'REMOTE\_NDIS\_SET\_MSG' +author: windows-driver-content +Description: 'This message is sent to a Remote NDIS device from a host, when it requires to set the value of some operational parameter on the device.' +ms.assetid: d39032e2-e3a5-415f-8bd6-b60b9049ce33 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices + +--- + +# REMOTE\_NDIS\_SET\_MSG + + +This message is sent to a Remote NDIS device from a host, when it requires to set the value of some operational parameter on the device. The specific parameter being set is identified by means of an Object Identifier (OID), and the value it is to be set to is contained in an information buffer sent along with the message. The host may send REMOTE\_NDIS\_SET\_MSG to the device through the control channel at any time that the device is in a state initialized by Remote NDIS. The Remote NDIS device will respond to this message by sending a REMOTE\_NDIS\_SET\_CMPLT to the host. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetSizeFieldDescription

0

4

MessageType

Specifies the type of message being sent. Set to 0x00000005.

4

4

MessageLength

Specifies, in bytes, the total length of this message, from the beginning of the message.

8

4

RequestId

Specifies the Remote NDIS message ID value. This value is used to match messages sent by the host with device responses.

12

4

Oid

Specifies the NDIS OID that identifies the parameter being set.

16

4

InformationBufferLength

Specifies, in bytes, the length of the input data for the request.

20

4

InformationBufferOffset

Specifies the byte offset, from the beginning of the RequestId field, at which input data for the request is located.

24

4

DeviceVcHandle

Reserved for connection-oriented devices. Set to zero.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Microsoft Windows XP and later versions of the Windows operating systems. Also available in Windows 2000 as redistributable binaries.

Header

Rndis.h (include Rndis.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20REMOTE_NDIS_SET_MSG%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/en-us/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/remote-ndis-set-msg2.md b/windows-driver-docs-pr/network/remote-ndis-set-msg2.md deleted file mode 100644 index 28dba886b0..0000000000 --- a/windows-driver-docs-pr/network/remote-ndis-set-msg2.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REMOTE\_NDIS\_SET\_MSG -description: REMOTE\_NDIS\_SET\_MSG -ms.assetid: 28672557-bf29-480f-8f33-535dd70d3631 -ms.author: windowsdriverdev -ms.date: 04/20/2017 -ms.topic: article -ms.prod: windows-hardware -ms.technology: windows-devices ---- - -# REMOTE\_NDIS\_SET\_MSG - - -## - - -[**REMOTE\_NDIS\_SET\_MSG**](https://msdn.microsoft.com/library/windows/hardware/ff570654) is sent to a Remote NDIS device from a host, when it needs to set the value of some operational parameter on the device. The specific parameter being set is identified by means of an Object Identifier (OID), and the value it is to be set to is contained in an information buffer sent along with the message. The host may send **REMOTE\_NDIS\_SET\_MSG** to the device through the control channel at any time that the device is in a state not yet initialized by Remote NDIS. A Remote NDIS device will respond to a **REMOTE\_NDIS\_SET\_MSG** message with a status. - -  - -  - - - - - diff --git a/windows-driver-docs-pr/network/responding-to-an-oid-co-tapi-line-caps-query.md b/windows-driver-docs-pr/network/responding-to-an-oid-co-tapi-line-caps-query.md index 9f56f8f133..58653329db 100644 --- a/windows-driver-docs-pr/network/responding-to-an-oid-co-tapi-line-caps-query.md +++ b/windows-driver-docs-pr/network/responding-to-an-oid-co-tapi-line-caps-query.md @@ -1,6 +1,6 @@ --- -title: Responding to an OID\_CO\_TAPI\_LINE\_CAPS Query -description: Responding to an OID\_CO\_TAPI\_LINE\_CAPS Query +title: Responding to an OID_CO_TAPI_LINE_CAPS Query +description: Responding to an OID_CO_TAPI_LINE_CAPS Query ms.assetid: b1ca65c6-ecce-4d2c-b7ca-03b6a334f97b keywords: - voice streaming WDK networking , support specification diff --git a/windows-driver-docs-pr/network/reusing-an-ndis-miniport-offload-block-list-structure.md b/windows-driver-docs-pr/network/reusing-an-ndis-miniport-offload-block-list-structure.md index f6f0f43dbb..13f79331a9 100644 --- a/windows-driver-docs-pr/network/reusing-an-ndis-miniport-offload-block-list-structure.md +++ b/windows-driver-docs-pr/network/reusing-an-ndis-miniport-offload-block-list-structure.md @@ -1,6 +1,6 @@ --- -title: Reusing an NDIS\_MINIPORT\_OFFLOAD\_BLOCK\_LIST Structure -description: Reusing an NDIS\_MINIPORT\_OFFLOAD\_BLOCK\_LIST Structure +title: Reusing an NDIS_MINIPORT_OFFLOAD_BLOCK_LIST Structure +description: Reusing an NDIS_MINIPORT_OFFLOAD_BLOCK_LIST Structure ms.assetid: 5f5e2e00-a29a-48f9-8f87-6e2fe1026aad keywords: - propagating TCP chimney state-manipulation operations, block list types diff --git a/windows-driver-docs-pr/network/reusing-an-ndis-protocol-offload-block-list-structure.md b/windows-driver-docs-pr/network/reusing-an-ndis-protocol-offload-block-list-structure.md index 9e72924d40..326f3b7aa6 100644 --- a/windows-driver-docs-pr/network/reusing-an-ndis-protocol-offload-block-list-structure.md +++ b/windows-driver-docs-pr/network/reusing-an-ndis-protocol-offload-block-list-structure.md @@ -1,6 +1,6 @@ --- -title: Reusing an NDIS\_PROTOCOL\_OFFLOAD\_BLOCK\_LIST Structure -description: Reusing an NDIS\_PROTOCOL\_OFFLOAD\_BLOCK\_LIST Structure +title: Reusing an NDIS_PROTOCOL_OFFLOAD_BLOCK_LIST Structure +description: Reusing an NDIS_PROTOCOL_OFFLOAD_BLOCK_LIST Structure ms.assetid: da8c1d8e-87cc-46b0-a322-759abb162808 keywords: - propagating TCP chimney state-manipulation operations, block list types diff --git a/windows-driver-docs-pr/network/rss-hashing-functions.md b/windows-driver-docs-pr/network/rss-hashing-functions.md index 9b2d02bf2c..c2d3adc152 100644 --- a/windows-driver-docs-pr/network/rss-hashing-functions.md +++ b/windows-driver-docs-pr/network/rss-hashing-functions.md @@ -16,8 +16,7 @@ ms.technology: windows-devices # RSS Hashing Functions -## - +## Overview A NIC or its miniport driver uses the RSS hashing function to calculate an RSS hash value. @@ -25,20 +24,18 @@ Overlying drivers set the hash type, function, and table to assign connections t The hashing function can be one of the following: -**NdisHashFunctionToeplitz** - -**NdisHashFunctionReserved1** - -**NdisHashFunctionReserved2** - -**NdisHashFunctionReserved3** +- **NdisHashFunctionToeplitz** +- **NdisHashFunctionReserved1** +- **NdisHashFunctionReserved2** +- **NdisHashFunctionReserved3** -**Note**  Currently, **NdisHashFunctionToeplitz** is the only hashing function available to miniport drivers. The other hashing functions are reserved for NDIS. - -  +>[!NOTE] +> Currently, **NdisHashFunctionToeplitz** is the only hashing function available to miniport drivers. The other hashing functions are reserved for NDIS.  A miniport driver should identify the hashing function and value that it uses in each [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure before the driver indicates received data. For more information, see [Indicating RSS Receive Data](indicating-rss-receive-data.md). +## Examples + The following four pseudocode examples show how to calculate the **NdisHashFunctionToeplitz** hash value. These examples represent the four possible hash types that are available for **NdisHashFunctionToeplitz**. For more information about hash types, see [RSS Hashing Types](rss-hashing-types.md). To simplify the examples, a generalized algorithm that processes an input byte stream is required. Specific formats for the byte streams are defined later in the four examples. @@ -47,7 +44,7 @@ The overlying driver provides a secret key (K) to the miniport driver for use in Given an input array that contains *n* bytes, the byte stream is defined as follows: -``` +```c++ input[0] input[1] input[2] ... input[n-1] ``` @@ -55,7 +52,7 @@ The left-most byte is input\[0\], and the most-significant bit of input\[0\] is Given the preceding definitions, the pseudocode for processing a general input byte stream is defined as follows: -``` +```c++ ComputeHash(input[], n) result = 0 @@ -74,7 +71,7 @@ The pseudocode contains entries of the form @n-m. These entries identify the byt Concatenate the SourceAddress, DestinationAddress, SourcePort, and DestinationPort fields of the packet into a byte array, preserving the order in which they occurred in the packet: -``` +```c++ Input[12] = @12-15, @16-19, @20-21, @22-23 Result = ComputeHash(Input, 12) ``` @@ -83,7 +80,7 @@ Result = ComputeHash(Input, 12) Concatenate the SourceAddress and DestinationAddress fields of the packet into a byte array. -``` +```c++ Input[8] = @12-15, @16-19 Result = ComputeHash(Input, 8) ``` @@ -92,7 +89,7 @@ Result = ComputeHash(Input, 8) Concatenate the SourceAddress, DestinationAddress, SourcePort, and DestinationPort fields of the packet into a byte array, preserving the order in which they occurred in the packet. -``` +```c++ Input[36] = @8-23, @24-39, @40-41, @42-43 Result = ComputeHash(Input, 36) ``` @@ -101,7 +98,7 @@ Result = ComputeHash(Input, 36) Concatenate the SourceAddress and DestinationAddress fields of the packet into a byte array. -``` +```c++ Input[32] = @8-23, @24-39 Result = ComputeHash(Input, 32) ``` diff --git a/windows-driver-docs-pr/network/rss-hashing-types.md b/windows-driver-docs-pr/network/rss-hashing-types.md index 331ac16150..15ef2b3701 100644 --- a/windows-driver-docs-pr/network/rss-hashing-types.md +++ b/windows-driver-docs-pr/network/rss-hashing-types.md @@ -15,9 +15,7 @@ ms.technology: windows-devices # RSS Hashing Types - -## - +## Overview The RSS hashing type specifies the portion of received network data that a NIC must use to calculate an RSS hash value. @@ -25,120 +23,189 @@ Overlying drivers set the hash type, function, and indirection table. The hash t The hash type is an OR of valid combinations of the following flags: -NDIS\_HASH\_IPV4 +- NDIS_HASH_IPV4 +- NDIS_HASH_TCP_IPV4 +- NDIS_HASH_UDP_IPV4 +- NDIS_HASH_IPV6 +- NDIS_HASH_TCP_IPV6 +- NDIS_HASH_UDP_IPV6 +- NDIS_HASH_IPV6_EX +- NDIS_HASH_TCP_IPV6_EX +- NDIS_HASH_UDP_IPV6_EX -NDIS\_HASH\_TCP\_IPV4 +These are the sets of valid flag combinations: -NDIS\_HASH\_IPV6 +- IPv4 (combinations of NDIS_HASH_IPV4, NDIS_HASH_TCP_IPV4, and NDIS_HASH_UDP_IPV4) +- IPv6 (combinations of NDIS_HASH_IPV6, NDIS_HASH_TCP_IPV6, and NDIS_HASH_UDP_IPV6) +- IPv6 with extension headers (combinations of NDIS_HASH_IPV6_EX, NDIS_HASH_TCP_IPV6_EX, and NDIS_HASH_UDP_IPV6_EX) -NDIS\_HASH\_TCP\_IPV6 +A NIC must support one of the combinations from the IPv4 set. The other sets and combinations are optional. A NIC can support more than one set at a time. In this case, the type of data received determines which hash type the NIC uses. -NDIS\_HASH\_IPV6\_EX +In general, if the NIC cannot interpret the received data correctly, it must not compute the hash value. For example, if the NIC only supports IPv4 and it receives an IPv6 packet, which it cannot interpret correctly, it must not compute the hash value. If the NIC receives a packet for a transport type that it does not support, it must not compute the hash value. For example, if the NIC receives a UDP packet when it is supposed to be calculating hash values for TCP packets, it must not compute the hash value. In this case, the packet is processed as in the non-RSS case. For more information about the non-RSS receive processing, see [Non-RSS Receive Processing](non-rss-receive-processing.md). -NDIS\_HASH\_TCP\_IPV6\_EX +## IPv4 hash type combinations -There are three sets of valid flag combinations. +The valid hash type combinations in the IPv4 set are: -IPv4 (combinations of NDIS\_HASH\_IPV4 and NDIS\_HASH\_TCP\_IPV4) +- [NDIS_HASH_IPV4](#ndishashipv4) +- [NDIS_HASH_TCP_IPV4](#ndishashtcpipv4) +- [NDIS_HASH_UDP_IPV4](#ndishashudpipv4) +- [NDIS_HASH_TCP_IPV4 | NDIS_HASH_IPV4](#ndishashtcpipv4--ndishashipv4) +- [NDIS_HASH_UDP_IPV4 | NDIS_HASH_IPV4](#ndishashudpipv4--ndishashipv4) +- [NDIS_HASH_TCP_IPV4 | NDIS_HASH_UDP_IPV4 | NDIS_HASH_IV4](#ndishashtcpipv4--ndishashudpipv4--ndishashipv4) -IPv6 (combinations of NDIS\_HASH\_IPV6 and NDIS\_HASH\_TCP\_IPV6) +### NDIS_HASH_IPV4 -IPv6 with extension headers (combinations of NDIS\_HASH\_IPV6\_EX and NDIS\_HASH\_TCP\_IPV6\_EX) +If this flag alone is set, the NIC should compute the hash value over the following IPv4 header fields: -A NIC must support one of the combinations from the IPv4 set. The other sets and combinations are optional. A NIC can support more than one set at a time. In this case, the type of data received determines which hash type the NIC uses. +- Source-IPv4-Address +- Destination-IPv4-Address -In general, if the NIC cannot interpret the received data correctly, it must not compute the hash value. For example, if the NIC only supports IPv4 and it receives anIPv6 packet, which it cannot interpret correctly, it must not compute the hash value. If the NIC receives a packet for a transport type that it does not support, it must not compute the hash value. For example, if the NIC receives a UDP packet when it is supposed to be calculating hash values for TCP packets, it must not compute the hash value. In this case, the packet is processed as in the non-RSS case. For more information about the non-RSS receive processing, see [Non-RSS Receive Processing](non-rss-receive-processing.md). +>[!NOTE] +> If a NIC receives a packet that has both IP and TCP headers, NDIS_HASH_TCP_IPV4 should not always be used. In the case of a fragmented IP packet, NDIS_HASH_IPV4 must be used. This includes the first fragment which contains both IP and TCP headers. -The three valid hash type combinations in the IPv4 set: +### NDIS_HASH_TCP_IPV4 -NDIS\_HASH\_IPV4 -If this flag alone is set, the NIC should compute the hash value over the following IPv4 header fields: +If this flag alone is set, the NIC should parse the received data to identify an IPv4 packet that contains a TCP segment. -Source-IPv4-Address +The NIC must identify and skip over any IP options that are present. If the NIC cannot skip over any IP options, it should not calculate a hash value. + +The NIC should compute the hash value over the following fields: -Destination-IPv4-Address +- Source-IPv4-Address +- Destination-IPv4-Address +- Source TCP Port +- Destination TCP Port -Note that if a NIC receives a packet that has both IP and TCP headers, NDIS\_HASH\_TCP\_IPV4 should not always be used. In the case of a fragmented IP packet, NDIS\_HASH\_IPV4 must be used. This includes the first fragment which contains both IP and TCP headers. +### NDIS_HASH_UDP_IPV4 -NDIS\_HASH\_TCP\_IPV4 -If this flag alone is set, the NIC should parse the received data to identify an IPv4 packet that contains a TCP segment. +If this flag alone is set, the NIC should parse the received data to identify an IPv4 packet that contains a UDP datagram. The NIC must identify and skip over any IP options that are present. If the NIC cannot skip over any IP options, it should not calculate a hash value. The NIC should compute the hash value over the following fields: -Source-IPv4-Address +- Source-IPv4-Address +- Destination-IPv4-Address +- Source UDP Port +- Destination UDP Port + +### NDIS_HASH_TCP_IPV4 | NDIS_HASH_IPV4 + +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_TCP_IPV4 case. However, if the packet does not contain a TCP header, the NIC should compute the hash value as specified for the NDIS_HASH_IPV4 case. + +### NDIS_HASH_UDP_IPV4 | NDIS_HASH_IPV4 -Destination-IPv4-Address +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_TCP_IPV4 case. However, if the packet does not contain a UDP header, the NIC should compute the hash value as specified for the NDIS_HASH_IPV4 case. -Source TCP Port +### NDIS_HASH_TCP_IPV4 | NDIS_HASH_UDP_IPV4 | NDIS_HASH_IPV4 -Destination TCP Port +If this flag combination is set, the NIC should perform the hash calculation as specified by the transport in the packet. However, if the packet does not contain a TCP or UDP header, the NIC should compute the hash value as specified for the NDIS_HASH_IPV4 case. -NDIS\_HASH\_TCP\_IPV4 | NDIS\_HASH\_IPV4 -If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS\_HASH\_TCP\_IPV4 case. +## IPv6 hash type combinations -However, if the packet does not contain a TCP header, the NIC should compute the hash value as specified in the NDIS\_HASH\_IPV4 case. +The valid hash type combinations in the IPv6 set are: -The three valid hash type combinations in the IPv6 set are: +- [NDIS_HASH_IPV6](#ndishashipv6) +- [NDIS_HASH_TCP_IPV6](#ndishashtcpipv6) +- [NDIS_HASH_UDP_IPV6](#ndishashudpipv6) +- [NDIS_HASH_TCP_IPV6 | NDIS_HASH_IPV6](#ndishashtcpipv6--ndishashipv6) +- [NDIS_HASH_UDP_IPV6 | NDIS_HASH_IPV6](#ndishashudpipv6--ndishashipv6) +- [NDIS_HASH_TCP_IPV6 | NDIS_HASH_UDP_IPV6 | NDIS_HASH_IPV6](#ndishashtcpipv6--ndishashudpipv6--ndishashipv6) + +### NDIS_HASH_IPV6 -NDIS\_HASH\_IPV6 If this flag alone is set, the NIC should compute the hash over the following fields: -Source-IPv6-Address +- Source-IPv6-Address +- Destination-IPv6-Address + +### NDIS_HASH_TCP_IPV6 -Destination-IPv6-Address +If this flag alone is set, the NIC should parse the received data to identify an IPv6 packet that contains a TCP segment. The NIC must identify and skip over any IPv6 extension headers that are present in the packet. If the NIC cannot skip over any IPv6 extension headers, it should not calculate a hash value. + +The NIC should compute the hash value over the following fields: -NDIS\_HASH\_TCP\_IPV6 -If this flag alone is set, the NIC should parse the received data to identify an IPv6 packet that contains a TCP segment. +- Source-IPv6 -Address +- Destination-IPv6 -Address +- Source TCP Port +- Destination TCP Port -The NIC must identify and skip over any IPv6 extension headers that are present in the packet. If the NIC cannot skip over any IPv6 extension headers, it should not calculate a hash value. +### NDIS_HASH_UDP_IPV6 + +If this flag alone is set, the NIC should parse the received data to identify an IPv6 packet that contains a UDP datagram. The NIC must identify and skip over any IPv6 extension headers that are present in the packet. If the NIC cannot skip over any IPv6 extension headers, it should not calculate a hash value. The NIC should compute the hash value over the following fields: -Source-IPv6 -Address +- Source-IPv6-Address +- Destination-IPv6-Address +- Source UDP Port +- Destination UDP Port + +### NDIS_HASH_TCP_IPV6 | NDIS_HASH_IPV6 + +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_TCP_IPV6 case. However, if the packet does not contain a TCP header, the NIC should compute the hash as specified for the NDIS_HASH_IPV6 case. -Destination-IPv6 -Address +### NDIS_HASH_UDP_IPV6 | NDIS_HASH_IPV6 -Source TCP Port +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_UDP_IPV6 case. However, if the packet does not contain a UDP header, the NIC should compute the hash as specified for the NDIS_HASH_IPV6 case. -Destination TCP Port +### NDIS_HASH_TCP_IPV6 | NDIS_HASH_UDP_IPV6 | NDIS_HASH_IPV6 -NDIS\_HASH\_TCP\_IPV6 | NDIS\_HASH\_IPV6 -If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS\_HASH\_TCP\_IPV6 case. +If this flag combination is set, the NIC should perform the hash calculation as specified by the transport in the packet. However, if the packet does not contain a TCP or UDP header, the NIC should compute the hash value as specified in the NDIS_HASH_IPV6 case. -However, if the packet does not contain a TCP header, the NIC should compute the hash as specified for the NDIS\_HASH\_IPV6 case: +## IPv6 with extension headers hash type combinations -The three valid combinations in the IPv6 with extension headers set are: +The valid combinations in the IPv6 with extension headers set are: + +- [NDIS_HASH_IPV6_EX](#ndishashipv6ex) +- [NDIS_HASH_TCP_IPV6_EX](#ndishashtcpipv6ex) +- [NDIS_HASH_UDP_IPV6_EX](#ndishashudpipv6ex) +- [NDIS_HASH_TCP_IPV6_EX | NDIS_HASH_IPV6_EX](#ndishashtcpipv6ex--ndishashipv6ex) +- [NDIS_HASH_UDP_IPV6_EX | NDIS_HASH_IPV6_EX](#ndishashudpipv6ex--ndishashipv6ex) +- [NDIS_HASH_TCP_IPV6_EX | NDIS_HASH_UDP_IPV6_EX | NDIS_HASH_IPV6_EX](#ndishashtcpipv6ex--ndishashudpipv6ex--ndishashipv6ex) + +### NDIS_HASH_IPV6_EX -NDIS\_HASH\_IPV6\_EX If this flag alone is set, the NIC should compute the hash over the following fields: -Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 Address +- Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 Address. +- IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 Address. -IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 Address +### NDIS_HASH_TCP_IPV6_EX -NDIS\_HASH\_TCP\_IPV6\_EX If this flag alone is set, the NIC should compute the hash over the following fields: -Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 Address +- Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 Address. +- IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 Address. +- Source TCP Port +- Destination TCP Port -IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 Address +### NDIS_HASH_UDP_IPV6_EX -Source TCP Port +If this flag alone is set, the NIC should compute the hash over the following fields: -Destination TCP Port +- Home address from the home address option in the IPv6 destination options header. If the extension header is not present, use the Source IPv6 Address. +- IPv6 address that is contained in the Routing-Header-Type-2 from the associated extension header. If the extension header is not present, use the Destination IPv6 Address. +- Source UDP Port +- Destination UDP Port -NDIS\_HASH\_TCP\_IPV6\_EX | NDIS\_HASH\_IPV6\_EX -If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS\_HASH\_TCP\_IPV6\_EX case. +### NDIS_HASH_TCP_IPV6_EX | NDIS_HASH_IPV6_EX -However, if the packet does not contain a TCP header, the NIC should compute the hash as specified for the NDIS\_HASH\_IPV6\_EX case: +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_TCP_IPV6_EX case. However, if the packet does not contain a TCP header, the NIC should compute the hash as specified for the NDIS_HASH_IPV6_EX case. -**Note**  If a miniport driver reports NDIS\_RSS\_CAPS\_HASH\_TYPE\_TCP\_IPV6\_EX capability for a NIC, the NIC must calculate hash values (over fields in the IPv6 extension headers) in accordance with the IPv6 extension hash types that the protocol driver set. The NIC can store either the extension hash type or the regular hash type in the NET\_BUFFER\_LIST structure of the IPv6 packet for which a hash value is computed. +### NDIS_HASH_UDP_IPV6_EX | NDIS_HASH_IPV6_EX -  +If this flag combination is set, the NIC should perform the hash calculations as specified for the NDIS_HASH_UDP_IPV6_EX case. However, if the packet does not contain a UDP header, the NIC should compute the hash as specified for the NDIS_HASH_IPV6_EX case. + +### NDIS_HASH_TCP_IPV6_EX | NDIS_HASH_UDP_IPV6_EX | NDIS_HASH_IPV6_EX + +If this flag combination is set, the NIC should perform the hash calculations as specified by the packet transport. However, if the packet does not contain a TCP or UDP header, the NIC should compute the hash as specified for the NDIS_HASH_IPV6_EX case. + +> [!NOTE] +> If a miniport driver reports NDIS_RSS_CAPS_HASH_TYPE_TCP_IPV6_EX and/or NDIS_RSS_CAPS_HASH_TYPE_UDP_IPV6_EX capability for a NIC, the NIC must calculate hash values (over fields in the IPv6 extension headers) in accordance with the IPv6 extension hash types that the protocol driver set. The NIC can store either the extension hash type or the regular hash type in the NET_BUFFER_LIST structure of the IPv6 packet for which a hash value is computed.  -A miniport driver sets the hash type in a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure before indicating the received data. For more information, see [Indicating RSS Receive Data](indicating-rss-receive-data.md). +A miniport driver sets the hash type in a [**NET_BUFFER_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure before indicating the received data. For more information, see [Indicating RSS Receive Data](indicating-rss-receive-data.md).   diff --git a/windows-driver-docs-pr/network/sdk-topics-for-network-drivers.md b/windows-driver-docs-pr/network/sdk-topics-for-network-drivers.md new file mode 100644 index 0000000000..102a087070 --- /dev/null +++ b/windows-driver-docs-pr/network/sdk-topics-for-network-drivers.md @@ -0,0 +1,30 @@ +--- +title: SDK Topics for Network Drivers +description: SDK Topics for Network Drivers +ms.assetid: E621615F-5A6A-4FB6-88D6-2DD11E2537B2 +keywords: +- SDK topics for network drivers, SDK network drivers, Windows SDK network drivers, Microsoft Windows SDK network drivers +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SDK Topics for Network Drivers + +This section contains SDK topics for Windows networking device drivers starting with Windows Vista. These topics may also be shared with the user mode applications that interact with network drivers. The header files that contain the topics defined in this section are included in the Windows Software Development Kit (SDK). + +> [!IMPORTANT] +> This section's header topics contains pages for definitions, macros, OIDs, status indications, and other data structures that are not part of network driver reference (structures, enumerations, functions, and callbacks). +> +> For more information about network driver reference for these headers, see [SDK Topics for Network Drivers (Reference)](https://msdn.microsoft.com/library/windows/hardware/mt808525). + +This section contains: + +* [Mstcpip.h](mstcpip-h.md) +* [Ntddndis.h](ntddndis-h.md) +* [Windot11.h](windot11-h.md) +* [Ws2def.h](ws2def-h.md) + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/security-issues-for-network-drivers.md b/windows-driver-docs-pr/network/security-issues-for-network-drivers.md index 9b5c9e5166..27ce6edc6c 100644 --- a/windows-driver-docs-pr/network/security-issues-for-network-drivers.md +++ b/windows-driver-docs-pr/network/security-issues-for-network-drivers.md @@ -1,6 +1,6 @@ --- title: Security Issues for Network Drivers -description: Security Issues for Network Drivers +description: This section describes security issues specific to network drivers ms.assetid: 04400213-9bd4-4dbe-b302-24917450829f keywords: - network drivers WDK , security @@ -14,25 +14,146 @@ ms.technology: windows-devices # Security Issues for Network Drivers +For a general discussion on writing secure drivers, see [Creating Reliable Kernel-Mode Drivers](https://msdn.microsoft.com/library/windows/hardware/ff542904). -## +Beyond following safe coding practices and the general device driver guidance, network drivers should do the following to enhance security: +- All network drivers should validate values that they read from the registry. Specifically, the caller of [**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511) or [**NdisReadNetworkAddress**](https://msdn.microsoft.com/library/windows/hardware/ff564512) must not make any assumptions about values read from the registry and must validate each registry value that it reads. If the caller of **NdisReadConfiguration** determines that a value is out of bounds, it should use a default value instead. If the caller of **NdisReadNetworkAddress** determines that a value is out of bounds, it should use the permanent medium access control (MAC) address or a default address instead. -For a general discussion on writing secure drivers, see [Creating Reliable Kernel-Mode Drivers](https://msdn.microsoft.com/library/windows/hardware/ff542904). +## OID-specific issues + +- A miniport driver, in its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) or [**MiniportCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff559362) functions, should validate any object identifier (OID) value that the driver is requested to set. If the driver determines that the value to be set is out of bounds, it should fail the set request. For more information about object identifiers, see [Obtaining and Setting Miniport Driver Information and NDIS Support for WMI](obtaining-and-setting-miniport-driver-information-and-ndis-support-for.md). + +- If an intermediate driver's *MiniportOidRequest* function does not pass a set operation to an underlying miniport driver, the function should validate the OID value. For more information, see [Intermediate Driver Query and Set Operations](intermediate-driver-query-and-set-operations.md). + +### Query OID security guidelines + +Most Query OIDs can be issued by any usermode application on the system. Follow these specific guidelines for Query OIDs. + +1. Always validate the size of the buffer is large enough for the output. Any query OID handler without an output buffer size check has a security bug. + + ```c++ + if (oid->DATA.QUERY_INFORMATION.InformationBufferLength < sizeof(ULONG)) { + oid->DATA.QUERY_INFORMATION.BytesNeeded = sizeof(ULONG); + return NDIS_STATUS_INVALID_LENGTH; + } + ``` + +2. Always write a correct and minimal value to BytesWritten. It is a red flag to assign `oid->BytesWritten = oid->InformationBufferLength` like the following example does. + + ```c++ + // ALWAYS WRONG + oid->DATA.QUERY_INFORMATION.BytesWritten = DATA.QUERY_INFORMATION.InformationBufferLength; + ``` + + The OS will copy BytesWritten bytes back to a usermode application. If BytesWritten is larger than the number of bytes the driver actually wrote, then the OS might end up copying back uninitialized kernel memory to usermode, which would be an information disclosure vulnerability. Instead, use code similar to this: + + ```c++ + oid->DATA.QUERY_INFORMATION.BytesWritten = sizeof(ULONG); + ``` + +3. Never read values back from the buffer. In some cases, the output buffer of an OID is directly mapped into a hostile usermode process. The hostile process can change your output buffer after you’ve written to it. For example, the code below can be attacked, because an attacker can change NumElements after it is written: + + ```c++ + output->NumElements = 4; + for (i = 0 ; i < output->NumElements ; i++) { + output->Element[i] = . . .; + } + ``` + To avoid reading back from the buffer, keep a local copy. For example, to fix the above example, introduce a new stack variable: + + ```c++ + ULONG num = 4; + output->NumElements = num; + for (i = 0 ; i < num; i++) { + output->Element[i] = . . .; + } + ``` + + With this approach, the for loop reads back from the driver’s stack variable `num` and not from its output buffer. The driver should also mark the output buffer with the `volatile` keyword, to prevent the compiler from silently undoing this fix. + +### Set OID security guidelines -In particular, network drivers should do the following to enhance security: +Most Set OIDs can be issued by a usermode application running in the Administrators or System security groups. Although these are generally trusted applications, the miniport driver still must not permit memory corruption or injection of kernel code. Follow these specific rules for Set OIDs: -- All drivers should validate values that they read from the registry. Specifically, the caller of [**NdisReadConfiguration**](https://msdn.microsoft.com/library/windows/hardware/ff564511) or [**NdisReadNetworkAddress**](https://msdn.microsoft.com/library/windows/hardware/ff564512) must not make any assumptions about values read from the registry and must validate each registry value that it reads. If the caller of **NdisReadConfiguration** determines that a value is out of bounds, it should use a default value instead. If the caller of **NdisReadNetworkAddress** determines that a value is out of bounds, it should use the permanent medium access control (MAC) address or a default address instead. +1. Always validate the input is large enough. Any OID set handler without an input buffer size check has a security vulnerability. -- A miniport driver, in its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) or [**MiniportCoOidRequest**](https://msdn.microsoft.com/library/windows/hardware/ff559362) functions, should validate any object identifier (OID) value that the driver is requested to set. If the driver determines that the value to be set is out of bounds, it should fail the set request. For more information about object identifiers, see [Obtaining and Setting Miniport Driver Information and NDIS Support for WMI](obtaining-and-setting-miniport-driver-information-and-ndis-support-for.md). + ```c++ + if (oid->DATA.SET_INFORMATION.InformationBufferLength < sizeof(ULONG)) { + return NDIS_STATUS_INVALID_LENGTH; + } + ``` -- If an intermediate driver's *MiniportOidRequest* function does not pass a set operation to an underlying miniport driver, the function should validate the OID value. For more information, see [Intermediate Driver Query and Set Operations](intermediate-driver-query-and-set-operations.md). +2. Whenever validating an OID with an embedded offset, you must validate that the embedded buffer is within the OID payload. This requires several checks. For example, [OID_PM_ADD_WOL_PATTERN](https://msdn.microsoft.com/en-us/library/windows/hardware/ff569764) may deliver an embedded pattern, that needs to be checked. Correct validation requires checking: -  + 1. InformationBufferSize >= sizeof(NDIS_PM_PACKET_PATTERN) -  + ```c++ + PmPattern = (PNDIS_PM_PACKET_PATTERN) InformationBuffer; + if (InformationBufferLength < sizeof(NDIS_PM_PACKET_PATTERN)) + { + Status = NDIS_STATUS_BUFFER_TOO_SHORT; + *BytesNeeded = sizeof(NDIS_PM_PACKET_PATTERN); + break; + } + ``` + 2. Pattern->PatternOffset + Pattern->PatternSize does not overflow + ```c++ + ULONG TotalSize = 0; + if (!NT_SUCCESS(RtlUlongAdd(Pattern->PatternOffset, Pattern->PatternSize, &TotalSize) || + TotalSize > InformationBufferLength) + { + return NDIS_STATUS_INVALID_LENGTH; + } + ``` + These two checks can be combined using code like the following example: + ```c++ + ULONG TotalSize = 0; + if (InformationBufferLength < sizeof(NDIS_PM_PACKET_PATTERN) || + !NT_SUCCESS(RtlUlongAdd(Pattern->PatternSize, Pattern->PatternOffset, &TotalSize) || + TotalSize > InformationBufferLength) + { + return NDIS_STATUS_INVALID_LENGTH; + } + ``` + + 3. InformationBuffer + Pattern->PatternOffset + Pattern->PatternLength does not overflow + ```c++ + ULONG TotalSize = 0; + if (!NT_SUCCESS(RtlUlongAdd(Pattern->PatternOffset, Pattern->PatternLength, &TotalSize) || + (!NT_SUCCESS(RtlUlongAdd(TotalSize, InformationBuffer, &TotalSize) || + TotalSize > InformationBufferLength) + { + return NDIS_STATUS_INVALID_LENGTH; + } + ``` + + 4. Pattern->PatternOffset + Pattern->PatternLength <= InformationBufferSize + + ```c++ + ULONG TotalSize = 0; + if(!NT_SUCCESS(RtlUlongAdd(Pattern->PatternOffset, Pattern->PatternLength, &TotalSize) || + TotalSize > InformationBufferLength)) + { + return NDIS_STATUS_INVALID_LENGTH; + } + ``` + +### Method OID security guidelines + +Method OIDs can be issued by a usermode application running in the Administrators or System security groups. They are a combination of a Set and a Query, so both preceding lists of guidance also apply to Method OIDs. + +## Other network driver security issues + +- Many NDIS miniport drivers expose a control device by using NdisRegisterDeviceEx. Those that do this must audit their IOCTL handlers, with all the same security rules as a WDM driver. For more information, see [Security Issues for I/O Control Codes](https://msdn.microsoft.com/en-us/library/windows/hardware/ff563700(v=vs.85).aspx). + +- Well-designed NDIS miniport drivers should not rely on being called in a particular process context, nor interact very closely with usermode (with IOCTLs & OIDs being the exception). It would be a red flag to see a miniport that opened usermode handles, performed usermode waits, or allocated memory against usermode quota. That code should be investigated. + +- Most NDIS miniport drivers should not be involved in parsing packet payloads. In some cases, though, it may be necessary. If so, this code should be audited very carefully, as the driver is parsing data from an untrusted source. + +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bp_mb\p_mb%5D:%20Planning%20your%20APN%20database%20submission%20%20RELEASE:%20%281/18/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/network/sending-ethernet-frames.md b/windows-driver-docs-pr/network/sending-ethernet-frames.md index e8e26c00db..9705d5a145 100644 --- a/windows-driver-docs-pr/network/sending-ethernet-frames.md +++ b/windows-driver-docs-pr/network/sending-ethernet-frames.md @@ -30,7 +30,7 @@ For Ethernet send requests, drivers must support these requirements: - If a driver originates a send request, the driver should allocate a [**NET\_BUFFER\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff568388) structure for the Ethernet frames. The **NetBufferListInfo** member in each NET\_BUFFER\_LIST structure must include the out-of-band (OOB) data that is required for the particular use. The OOB data applies to all of the [**NET\_BUFFER**](https://msdn.microsoft.com/library/windows/hardware/ff568376) structures that are associated with a NET\_BUFFER\_LIST structure. -- If a driver originates a send request, the driver should allocate one or more NET\_BUFFER structures for the Ethernet frames and link these structures to the NET\_BUFFER\_LIST structure. Each NET\_BUFFER structure that is linked to a NET\_BUFFER\_LIST structure describes a single Ethernet frame. +- If a driver originates a send request, the driver should allocate one or more NET\_BUFFER structures for the Ethernet frames and link these structures to the NET\_BUFFER\_LIST structure. Each NET\_BUFFER structure that is linked to a NET\_BUFFER\_LIST structure describes a single Ethernet frame. The driver may chain multiple NET\_BUFFER\_LIST structures in a send request. - All NET\_BUFFER structures that are associated with a NET\_BUFFER\_LIST structure must have the same Ethernet frame type and IP protocol version (IPv4 or IPv6). diff --git a/windows-driver-docs-pr/network/sending-net-buffer-structures-from-condis-drivers.md b/windows-driver-docs-pr/network/sending-net-buffer-structures-from-condis-drivers.md index 43165bdf5f..1a6ea445ce 100644 --- a/windows-driver-docs-pr/network/sending-net-buffer-structures-from-condis-drivers.md +++ b/windows-driver-docs-pr/network/sending-net-buffer-structures-from-condis-drivers.md @@ -1,6 +1,6 @@ --- -title: Sending NET\_BUFFER Structures from CoNDIS Drivers -description: Sending NET\_BUFFER Structures from CoNDIS Drivers +title: Sending NET_BUFFER Structures from CoNDIS Drivers +description: Sending NET_BUFFER Structures from CoNDIS Drivers ms.assetid: 63bca3f0-b598-4006-bfd0-6df32ab2cbe7 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/setting-net-buffer-list-information.md b/windows-driver-docs-pr/network/setting-net-buffer-list-information.md index 80298202f5..f0c5a63ca5 100644 --- a/windows-driver-docs-pr/network/setting-net-buffer-list-information.md +++ b/windows-driver-docs-pr/network/setting-net-buffer-list-information.md @@ -1,6 +1,6 @@ --- -title: Setting NET\_BUFFER\_LIST Information -description: Setting NET\_BUFFER\_LIST Information +title: Setting NET_BUFFER_LIST Information +description: Setting NET_BUFFER_LIST Information ms.assetid: 28f50ab4-043b-47bb-af70-e8c892288f21 keywords: - NET_BUFFER_LIST diff --git a/windows-driver-docs-pr/network/sio-address-list-change.md b/windows-driver-docs-pr/network/sio-address-list-change.md new file mode 100644 index 0000000000..1c1d2b7b2d --- /dev/null +++ b/windows-driver-docs-pr/network/sio-address-list-change.md @@ -0,0 +1,105 @@ +--- +title: SIO\_ADDRESS\_LIST\_CHANGE +author: windows-driver-content +description: SIO\_ADDRESS\_LIST\_CHANGE +ms.assetid: d451208d-c850-4f2f-9ee0-d34139454ed4 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_ADDRESS_LIST_CHANGE Network Drivers Starting with Windows Vista +--- + +# SIO\_ADDRESS\_LIST\_CHANGE + + +The SIO\_ADDRESS\_LIST\_CHANGE socket I/O control operation notifies a WSK application when there has been a change to the list of local transport addresses for a socket's address family. This socket I/O control operation applies to all socket types. + +To be notified when there has been a change to the list of local transport addresses for a socket's address family, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_ADDRESS_LIST_CHANGE

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to be notified of a change to the list of local transport addresses for a socket's address family. The WSK subsystem queues the IRP and returns STATUS\_PENDING. If a change is made to the list of local transport addresses for the socket's address family, the WSK subsystem completes the IRP. When the IRP's completion routine is called, the WSK application can use the [**SIO\_ADDRESS\_LIST\_QUERY**](sio-address-list-query.md) socket I/O control operation to query the new list of local transport addresses for the socket's address family. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_ADDRESS_LIST_CHANGE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-address-list-query.md b/windows-driver-docs-pr/network/sio-address-list-query.md new file mode 100644 index 0000000000..ce3eaad57d --- /dev/null +++ b/windows-driver-docs-pr/network/sio-address-list-query.md @@ -0,0 +1,107 @@ +--- +title: SIO\_ADDRESS\_LIST\_QUERY +author: windows-driver-content +description: SIO\_ADDRESS\_LIST\_QUERY +ms.assetid: c50520a3-6ba3-448e-bbb4-bf3425dcbc41 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_ADDRESS_LIST_QUERY Network Drivers Starting with Windows Vista +--- + +# SIO\_ADDRESS\_LIST\_QUERY + + +The SIO\_ADDRESS\_LIST\_QUERY socket I/O control operation allows a WSK application to query the current list of local transport addresses for a socket's address family. This socket I/O control operation applies to all socket types. + +To query the current list of local transport addresses for a socket's address family, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_ADDRESS_LIST_QUERY

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

The size, in bytes, of the buffer that is pointed to by the OutputBuffer parameter.

OutputBuffer

A pointer to the buffer that receives the current list of local transport addresses. The size of the buffer is specified in the OutputSize parameter.

OutputSizeReturned

A pointer to a ULONG-typed variable that receives the number of bytes of data that is copied into the buffer that is pointed to by the OutputBuffer parameter.

+ +  + +A WSK application does not specify a pointer to an IRP when calling the **WskControlSocket** function to query the current list of local transport addresses for a socket's address family. + +If the call to the **WskControlSocket** function succeeds, the output buffer contains a [**SOCKET\_ADDRESS\_LIST**](https://msdn.microsoft.com/library/windows/hardware/ff570826) structure followed by the SOCKADDR structures for each of the local transport addresses for the socket's address family. + +If the **WskControlSocket** function returns STATUS\_BUFFER\_OVERFLOW, the variable that is pointed to by the *OutputSizeReturned* parameter contains the output buffer size, in bytes, that is required to contain the complete list of local transport addresses for the socket's address family. + +The [**SIO\_ADDRESS\_LIST\_CHANGE**](sio-address-list-change.md) socket I/O control operation allows a WSK application to be notified when there has been a change to the list of local transport addresses for a socket's address family. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_ADDRESS_LIST_QUERY%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-loopback-fast-path.md b/windows-driver-docs-pr/network/sio-loopback-fast-path.md new file mode 100644 index 0000000000..1ad796f01c --- /dev/null +++ b/windows-driver-docs-pr/network/sio-loopback-fast-path.md @@ -0,0 +1,159 @@ +--- +title: SIO\_LOOPBACK\_FAST\_PATH control code +author: windows-driver-content +description: The SIO\_LOOPBACK\_FAST\_PATH socket I/O control code allows a WSK application to configure a TCP socket for faster operations on the loopback interface. +ms.assetid: 5A5AD945-9EFD-4157-AFA4-F9C3995B7C43 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_LOOPBACK_FAST_PATH control code Network Drivers Starting with Windows Vista +--- + +# SIO\_LOOPBACK\_FAST\_PATH control code + + +**Important**  The **SIO\_LOOPBACK\_FAST\_PATH** is deprecated and is not recommended to be used in your code. + +  + +The **SIO\_LOOPBACK\_FAST\_PATH** socket I/O control code allows a WSK application to configure a TCP socket for faster operations on the loopback interface. + +To use this IOCTL, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_LOOPBACK_FAST_PATH

Level

0

InputSize

The size, in bytes, of the input buffer.

InputBuffer

A pointer to the input buffer. This parameter contains a pointer to a Boolean value that indicates if the socket should be configured for fast loopback operations.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

A pointer to an IRP.

+ +  + +An application can use the **SIO\_LOOPBACK\_FAST\_PATH** IOCTL to improve the performance of loopback operations on a TCP socket. This IOCTL requests that the TCP/IP stack use a special fast path for loopback operations on this socket. The **SIO\_LOOPBACK\_FAST\_PATH** IOCTL can be used only with TCP sockets. This IOCTL must be used on both sides of the loopback session. The TCP loopback fast path is supported using either the IPv4 or IPv6 loopback interface. + +The socket that plans to initiate the connection request must apply this IOCTL before making the connection request. The socket that is listening for the connection request must apply this IOCTL before accepting the connection. + +Once an application establishes the connection on a loopback interface using the fast path, all packets for the lifetime of the connection must use the fast path. + +Applying **SIO\_LOOPBACK\_FAST\_PATH** to a socket which will be connected to a non-loopback path will have no effect. + +This TCP loopback optimization results in packets that flow through Transport Layer (TL) instead of the traditional loopback through Network Layer. This optimization improves the latency for loopback packets. Once an applications opts in for a connection level setting to use the loopback fast path, all packets will follow the loopback path. For loopback communications, congestion and packet drop are not expected. The notion of congestion control and reliable delivery in TCP will be unnecessary. This, however, is not true for flow control. Without flow control, the sender can overwhelm the receive buffer, leading to erroneous TCP loopback behavior. The flow control in the TCP optimized loopback path is maintained by placing send requests in a queue. When the receive buffer is full, the TCP/IP stack guarantees that the sends won't complete until the queue is serviced, maintaining flow control. + +TCP fast path loopback connections in the presence of a Windows Filtering Platform (WFP) callout for connection data must take the unoptimized slow path for loopback. So WFP filters will prevent this new loopback fast path from being used. When a WFP filter is enabled, the system will use the slow path even if the **SIO\_LOOPBACK\_FAST\_PATH** IOCTL was set. This ensues that user-mode applications have the full WFP security capability. + +By default, **SIO\_LOOPBACK\_FAST\_PATH** is disabled. + +Only a subset of the TCP/IP socket options are supported when the **SIO\_LOOPBACK\_FAST\_PATH** IOCTL is used to enable the loopback fast path on a socket. The list of supported options includes the following: + +- IP\_TTL +- IP\_UNICAST\_IF +- IPV6\_UNICAST\_HOPS +- IPV6\_UNICAST\_IF +- IPV6\_V6ONLY +- [**SO\_CONDITIONAL\_ACCEPT**](https://msdn.microsoft.com/library/windows/desktop/dd264794) +- [SO\_EXCLUSIVEADDRUSE](https://msdn.microsoft.com/library/windows/desktop/cc150667) +- [**SO\_PORT\_SCALABILITY**](https://msdn.microsoft.com/library/windows/desktop/cc150670) +- SO\_RCVBUF +- SO\_REUSEADDR +- TCP\_BSDURGENT + +A WSK application must specify a pointer to an IRP and a completion routine when calling the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function for this type of request. The application must not release the buffer till the WSK subsystem has completed the IRP. When it completes the IRP, the subsystem invokes the completion routine. In the completion routine, the application must check the IRP status and release all resources that it had previously allocated for the request. + +For more information about WSK IRP handling, see [Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006). + +When completing the IRP, the subsystem will set *Irp->IoStatus.Status* to **STATUS\_SUCCESS** if the request is successful. Otherwise, *Irp->IoStatus.Status* will be set to **STATUS\_INVALID\_BUFFER\_SIZE** or **STATUS\_NOT\_SUPPORTED** if the call is not successful. + +## Return value + + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Mstcpip.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[**SIO\_LOOPBACK\_FAST\_PATH (SDK)**](https://msdn.microsoft.com/library/windows/desktop/jj841212) + +[Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_LOOPBACK_FAST_PATH%20control%20code%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-context.md b/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-context.md new file mode 100644 index 0000000000..a050b948de --- /dev/null +++ b/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-context.md @@ -0,0 +1,145 @@ +--- +title: SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT control code +author: windows-driver-content +description: The SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT socket I/O control operation allows a Winsock client to retrieve the redirect context for a redirect record for a redirected connection. +ms.assetid: D23971FC-D75F-4C39-BE6A-F0E17F7C1804 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT control code Network Drivers Starting with Windows Vista +--- + +# SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT control code + + +The **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT** socket I/O control operation allows a Winsock client to retrieve the redirect context for a redirect record for a redirected connection. + +A WFP redirect record is a buffer of opaque data that WFP must set on an outbound proxy connection so that the redirected connection and the original connection are logically related. + +**Note**  The [**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS**](sio-query-wfp-connection-redirect-records.md) query can only be used if the connection was redirected at the **FWPS\_LAYER\_ALE\_CONNECT\_REDIRECT\_V4** or **FWPS\_LAYER\_ALE\_CONNECT\_REDIRECT\_V6** layer by a WFP client. + +  + +For more information about redirection, see [Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005). + +To query the redirect context for a redirect record, a Winsock client calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

The size, in bytes, of the buffer that is pointed to by the OutputBuffer parameter.

OutputBuffer

A pointer to the buffer that receives the redirect context for the redirect record for the accepted TCP connection. The size of the buffer is specified in the OutputSize parameter.

OutputSizeReturned

A pointer to a ULONG-typed variable that receives the number of bytes of data that is copied into the buffer that is pointed to by the OutputBuffer parameter.

Irp

A pointer to an IRP.

+ +  + +The caller can perform this query in either of the following ways: + +- It can set the *OutputBuffer* to a large buffer approximately 1 KB in size. If the output buffer size is not large enough, [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) will return **STATUS\_BUFFER\_TOO\_SMALL** and *OutputSizeReturned* will contain the required size of the buffer. A larger buffer can then be allocated and **WskControlSocket** called again with the **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT** request and *OutputBuffer* set to the larger buffer. +- Or it can set the *OutputSize* parameter to 0 and the *OutputBuffer* to NULL and then call [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127). Upon completion, the **WskControlSocket** function retrieves the output buffer size, in bytes, in the *OutputSizeReturned* parameter. An appropriately sized buffer can then be allocated and **WskControlSocket** called again with the **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT** request and *OutputBuffer* set to the buffer. + +**Note**  It is also possible to perform this query in a user-mode application by using [**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859712). + +  + +For this type of request, the Winsock client must specify a pointer to an IRP and a pointer to its completion routine. The IRP can be passed to the client by a higher driver or the client can choose to allocate the IRP. To specify the completion routine, the client must call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). For more details, see [Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006). + +The Winsock client must not free the allocated buffer till the IRP is completed by WSK subsystem. When the WSK subsystem completes the IRP, it notifies the client by invoking the completion routine. A reference to that buffer is passed to the client by the WSK subsystem in the *Context* parameter of the completion routine. The size of the buffer is stored in *Irp->IoStatus.Information*. + +The client can get the status of the IRP by checking *Irp->IoStatus.Status*. *Irp->IoStatus.Status* will be set to **STATUS\_SUCCESS** if the request is successful. Otherwise, it will contain **STATUS\_INTEGER\_OVERFLOW**, **STATUS\_NOT\_FOUND**, **STATUS\_BUFFER\_TOO\_SMALL**, or **STATUS\_ACCESS\_DENIED** if the call is not successful. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Mstcpip.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005) + +[Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006) + +[**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS**](sio-query-wfp-connection-redirect-records.md) + +[**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859712) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_QUERY_WFP_CONNECTION_REDIRECT_CONTEXT%20control%20code%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-records.md b/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-records.md new file mode 100644 index 0000000000..1047955584 --- /dev/null +++ b/windows-driver-docs-pr/network/sio-query-wfp-connection-redirect-records.md @@ -0,0 +1,147 @@ +--- +title: SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS control code +author: windows-driver-content +description: The SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS socket I/O control operation allows a Winsock client to retrieve the redirect record for a redirected connection. +ms.assetid: D04C63B8-DD08-4943-9F83-B5D05F4F2CCF +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS control code Network Drivers Starting with Windows Vista +--- + +# SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS control code + + +The **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS** socket I/O control operation allows a Winsock client to retrieve the redirect record for a redirected connection. + +A WFP redirect record is a buffer of opaque data that WFP must set on an outbound proxy connection so that the redirected connection and the original connection are logically related. + +**Note**  The **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS** query can only be used if the connection was redirected at the **FWPS\_LAYER\_ALE\_CONNECT\_REDIRECT\_V4** or **FWPS\_LAYER\_ALE\_CONNECT\_REDIRECT\_V6** layer by a WFP client. + +  + +For more information about redirection, see [Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005). + +To query the redirect record for the redirected connection, a Winsock client calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

The size, in bytes, of the buffer that is pointed to by the OutputBuffer parameter.

OutputBuffer

A pointer to the buffer that receives the redirect record for the accepted TCP connection. The size of the buffer is specified in the OutputSize parameter.

OutputSizeReturned

A pointer to a ULONG-typed variable that receives the number of bytes of data that is copied into the buffer that is pointed to by the OutputBuffer parameter.

Irp

A pointer to an IRP.

+ +  + +The caller can perform this query in either of the following ways: + +- It can set the *OutputBuffer* to a large buffer approximately 1 KB in size. If the output buffer size is not large enough, [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) will return a **STATUS\_BUFFER\_TOO\_SMALL** and *OutputSizeReturned* will contain the required size of the buffer. A larger buffer can then be allocated and **WskControlSocket** called again with the **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS** request and *OutputBuffer* set to the larger buffer. +- Or it can set the *OutputSize* parameter to 0 and the *OutputBuffer* to NULL and then call [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127). Upon completion, the **WskControlSocket** function retrieves the output buffer size, in bytes, in the *OutputSizeReturned* parameter. An appropriately sized buffer can then be allocated and **WskControlSocket** called again with the **SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS** request and *OutputBuffer* set to the buffer. + +**Note**  It is also possible to perform this query in a user-mode application by using [**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859713). + +  + +For this type of request, the Winsock client must specify a pointer to an IRP and a pointer to its completion routine. The IRP can be passed to the client by a higher driver or the client can choose to allocate the IRP. To specify the completion routine, the client must call [**IoSetCompletionRoutine**](https://msdn.microsoft.com/library/windows/hardware/ff549679). For more details, see [Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006). + +The Winsock client must not free the allocated buffer till the IRP is completed by WSK subsystem. When the WSK subsystem completes the IRP, it notifies the client by invoking the completion routine. A reference to that buffer is passed to the client by the WSK subsystem in the *Context* parameter of the completion routine. The size of the buffer is stored in *Irp->IoStatus.Information*. + +The client can get the status of the IRP by checking *Irp->IoStatus.Status*. *Irp->IoStatus.Status* will be set to **STATUS\_SUCCESS** if the request is successful. Otherwise, it will contain **STATUS\_INTEGER\_OVERFLOW**, **STATUS\_NOT\_FOUND**, **STATUS\_BUFFER\_TOO\_SMALL**, or **STATUS\_ACCESS\_DENIED** if the call is not successful. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Mstcpip.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005) + +[Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006) + +[**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_CONTEXT**](sio-query-wfp-connection-redirect-context.md) + +[**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859713) + +[**SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS**](sio-set-wfp-connection-redirect-records.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_QUERY_WFP_CONNECTION_REDIRECT_RECORDS%20control%20code%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-set-wfp-connection-redirect-records.md b/windows-driver-docs-pr/network/sio-set-wfp-connection-redirect-records.md new file mode 100644 index 0000000000..e3ec6e7eed --- /dev/null +++ b/windows-driver-docs-pr/network/sio-set-wfp-connection-redirect-records.md @@ -0,0 +1,138 @@ +--- +title: SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS control code +author: windows-driver-content +description: The SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS socket I/O control operation allows a Winsock client to specify the redirect record to the new TCP socket used for connecting to the final destination. +ms.assetid: 51FC55BB-FD7A-4FDE-B1FC-02745AC03E33 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS control code Network Drivers Starting with Windows Vista +--- + +# SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS control code + + +The **SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS** socket I/O control operation allows a Winsock client to specify the redirect record to the new TCP socket used for connecting to the final destination. + +A WFP redirect record is a buffer of opaque data that WFP must set on an outbound proxy connection so that the redirected connection and the original connection are logically related. + +For more information about redirection, see [Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005). + +To set the redirect record to the new TCP socket used for connecting to the final destination, a Winsock client calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS

Level

0

InputSize

The size of the redirect record pointed to by the InputBuffer parameter.

InputBuffer

A pointer to the redirect record associated with the socket.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

A pointer to an IRP.

+ +  + +The Winsock client must allocate a buffer and specify a pointer to the buffer and its size in *InputBuffer* and *InputSize.* + +A Winsock client must specify a pointer to an IRP and a completion routine when calling the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function for this type of request. The client must not release the buffer till the WSK subsystem has completed the IRP. When it completes the IRP, the subsystem invokes the completion routine. In the completion routine, the client must check the IRP status and release all resources that it had previously allocated for the request. + +**Note**  It is also possible to perform this query in a user-mode application by using [**SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859714). + +  + +For more information about WSK IRP handling, see [Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006). + +The client can get the status of the IRP by checking *Irp->IoStatus.Status*. *Irp->IoStatus.Status* will be set to **STATUS\_SUCCESS** if the request is successful. Otherwise, it will contain **STATUS\_INTEGER\_OVERFLOW**, or **STATUS\_ACCESS\_DENIED** if the call is not successful. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + + + + + +

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Mstcpip.h

IRQL

PASSIVE_LEVEL

+ +## See also + + +[Using Bind or Connect Redirection](https://msdn.microsoft.com/library/windows/hardware/ff571005) + +[Using IRPs with Winsock Kernel Functions](https://msdn.microsoft.com/library/windows/hardware/ff571006) + +[**SIO\_QUERY\_WFP\_CONNECTION\_REDIRECT\_RECORDS**](sio-query-wfp-connection-redirect-records.md) + +[**SIO\_SET\_WFP\_CONNECTION\_REDIRECT\_RECORDS (SDK)**](https://msdn.microsoft.com/library/windows/desktop/hh859714) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_SET_WFP_CONNECTION_REDIRECT_RECORDS%20control%20code%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-query-ideal-send-backlog.md b/windows-driver-docs-pr/network/sio-wsk-query-ideal-send-backlog.md new file mode 100644 index 0000000000..b2cae02ded --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-query-ideal-send-backlog.md @@ -0,0 +1,111 @@ +--- +title: SIO_WSK_QUERY_IDEAL_SEND_BACKLOG +author: windows-driver-content +description: SIO_WSK_QUERY_IDEAL_SEND_BACKLOG +ms.assetid: 8d05b1dc-9dbf-4726-9eaf-721d1fb8282e +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_QUERY_IDEAL_SEND_BACKLOG Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_QUERY\_IDEAL\_SEND\_BACKLOG + + +The SIO\_WSK\_QUERY\_IDEAL\_SEND\_BACKLOG socket I/O control operation allows a WSK application to query the ideal send backlog size for a connection-oriented socket. This socket I/O control operation applies only to connection-oriented sockets. + +The ideal send backlog size for a connection-oriented socket is the optimal amount of send data that needs to be kept outstanding (that is, passed to the WSK subsystem but not yet completed) to keep the socket's data stream full at all times. A WSK application can use this size to incrementally probe and lock the buffers of data to be sent based on the underlying connection's flow control state. + +If a WSK application uses this socket I/O control operation to query the ideal send backlog size, it must do so after the connection-oriented socket has been connected to a remote transport address. + +To query the ideal send backlog size for a connection-oriented socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_QUERY_IDEAL_SEND_BACKLOG

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(SIZE_T)

OutputBuffer

A pointer to a SIZE_T-typed variable that receives the current ideal send backlog size

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to query the ideal send backlog size for a connection-oriented socket. + +A connection-oriented socket can be notified of changes to the ideal send backlog size by enabling its [*WskSendBacklogEvent*](https://msdn.microsoft.com/library/windows/hardware/ff571147) event callback function. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_QUERY_IDEAL_SEND_BACKLOG%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-query-inspect-id.md b/windows-driver-docs-pr/network/sio-wsk-query-inspect-id.md new file mode 100644 index 0000000000..d809548bf7 --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-query-inspect-id.md @@ -0,0 +1,111 @@ +--- +title: SIO_WSK_QUERY_INSPECT_ID +author: windows-driver-content +description: SIO_WSK_QUERY_INSPECT_ID +ms.assetid: 6fc3e5ea-61df-47fc-8f79-f9ae272b3544 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_QUERY_INSPECT_ID Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_QUERY\_INSPECT\_ID + + +The SIO\_WSK\_QUERY\_INSPECT\_ID socket I/O control operation allows a WSK application to query the inspection identification data for a connection-oriented socket that has been successfully accepted on a listening socket that has conditional accept mode enabled. This socket I/O control operation applies only to connection-oriented sockets that have been accepted on a listening socket that has conditional accept mode enabled. + +To query the inspection identification data for a connection-oriented socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_QUERY_INSPECT_ID

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(WSK_INSPECT_ID)

OutputBuffer

A pointer to a WSK_INSPECT_ID structure that receives the inspection identification data

OutputSizeReturned

A pointer to a ULONG-typed variable that receives the number of bytes of data that is copied into the buffer that is pointed to by the OutputBuffer parameter.

Irp

NULL

+ +  + +``` + +``` + +If a WSK application calls the **WskControlSocket** function to query the inspection identification data for any socket other than a connection-oriented socket that was accepted on a listening socket that has conditional accept mode enabled, the **WskControlSocket** function returns STATUS\_INVALID\_DEVICE\_REQUEST. + +For more information about conditionally accepting connections, see [Listening for and Accepting Incoming Connections](https://msdn.microsoft.com/library/windows/hardware/ff557059). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_QUERY_INSPECT_ID%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-query-receive-backlog.md b/windows-driver-docs-pr/network/sio-wsk-query-receive-backlog.md new file mode 100644 index 0000000000..69ad31ce76 --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-query-receive-backlog.md @@ -0,0 +1,107 @@ +--- +title: SIO_WSK_QUERY_RECEIVE_BACKLOG +author: windows-driver-content +description: SIO_WSK_QUERY_RECEIVE_BACKLOG +ms.assetid: 5924c6ae-fa9d-4a8c-acbe-65ca0664ad74 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_QUERY_RECEIVE_BACKLOG Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_QUERY\_RECEIVE\_BACKLOG + + +The SIO\_WSK\_QUERY\_RECEIVE\_BACKLOG socket I/O control operation allows a WSK application to query the current backlog of received data for a connection-oriented socket. This socket I/O control operation applies only to connection-oriented sockets. + +If a WSK application uses this socket I/O control operation to query the receive backlog, it must do so after the connection-oriented socket has been connected to a remote transport address. + +To query the current backlog of received data for a connection-oriented socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_QUERY_RECEIVE_BACKLOG

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(SIZE_T)

OutputBuffer

A pointer to a SIZE_T-typed variable that receives the current backlog of received data

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to query the current backlog of received data for a connection-oriented socket. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_QUERY_RECEIVE_BACKLOG%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-register-extension.md b/windows-driver-docs-pr/network/sio-wsk-register-extension.md new file mode 100644 index 0000000000..1834701ba0 --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-register-extension.md @@ -0,0 +1,109 @@ +--- +title: SIO_WSK_REGISTER_EXTENSION +author: windows-driver-content +description: SIO_WSK_REGISTER_EXTENSION +ms.assetid: e7fd6d68-85e8-4c5f-b67f-2193d200130d +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_REGISTER_EXTENSION Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_REGISTER\_EXTENSION + + +The SIO\_WSK\_REGISTER\_EXTENSION socket I/O control operation allows a WSK application to register for an extension interface that is supported by the WSK subsystem. This socket I/O control operation applies to all socket types. + +To register an extension interface, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_REGISTER_EXTENSION

Level

0

InputSize

sizeof(WSK_EXTENSION_CONTROL_IN)

InputBuffer

A pointer to a [WSK_EXTENSION_CONTROL_IN](https://msdn.microsoft.com/library/windows/hardware/ff571167) structure. This structure contains a pointer to the [Network Programming Interface (NPI)](https://msdn.microsoft.com/library/windows/hardware/ff568373) identifier for the extension interface and pointers to the dispatch table and to the context for the WSK application's implementation of the extension interface.

OutputSize

sizeof(WSK_EXTENSION_CONTROL_OUT)

OutputBuffer

A pointer to a [WSK_EXTENSION_CONTROL_OUT](https://msdn.microsoft.com/library/windows/hardware/ff571168) structure. This structure receives a pointer to the dispatch table and a pointer to the context for the WSK subsystem's implementation of the extension interface.

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application does not specify a pointer to an IRP when calling the **WskControlSocket** function to register an extension interface. + +The contents of the dispatch table structures are extension interface-specific. + +For more information about registering an extension interface, see [Registering an Extension Interface](https://msdn.microsoft.com/library/windows/hardware/ff570461). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_REGISTER_EXTENSION%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-set-remote-address.md b/windows-driver-docs-pr/network/sio-wsk-set-remote-address.md new file mode 100644 index 0000000000..5045a294a6 --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-set-remote-address.md @@ -0,0 +1,166 @@ +--- +title: SIO_WSK_SET_REMOTE_ADDRESS +author: windows-driver-content +description: SIO_WSK_SET_REMOTE_ADDRESS +ms.assetid: 1db11c7a-c9ce-428e-b4da-4a49904a9e4c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_SET_REMOTE_ADDRESS Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_SET\_REMOTE\_ADDRESS + + +The SIO\_WSK\_SET\_REMOTE\_ADDRESS socket I/O control operation allows a WSK application to specify a fixed remote transport address for a datagram socket. This socket I/O control operation applies only to datagram sockets. + +If a WSK application sets a fixed remote transport address for a datagram socket, all datagrams that are sent over the socket are sent to the fixed remote transport address, and only datagrams that are received from the fixed remote transport address are accepted. + +A WSK application can override a fixed remote transport address when it sends a datagram over the socket by specifying an alternative remote transport address in the *RemoteAddress* parameter when calling the [**WskSendTo**](https://msdn.microsoft.com/library/windows/hardware/ff571148) function. In this situation, the datagram is sent to the alternative remote transport address instead of the fixed remote transport address. However, any responses that are sent back from an alternative remote transport address will not be accepted. + +If a WSK application uses this socket I/O control operation to specify a fixed remote transport address, it must do so after the datagram socket has been bound to a local transport address. + +To set a fixed remote transport address for a datagram socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_SET_REMOTE_ADDRESS

Level

0

InputSize

The size of the SOCKADDR structure pointed to by the InputBuffer parameter.

InputBuffer

A pointer to a structure that specifies a fixed remote transport address for the datagram socket. The pointer must be a pointer to the specific SOCKADDR structure type that corresponds to the address family that the WSK application specified when it created the datagram socket.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To clear a fixed remote transport address for a datagram socket, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_SET_REMOTE_ADDRESS

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or clear a fixed remote transport address for a datagram socket. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_SET_REMOTE_ADDRESS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-set-sendto-address.md b/windows-driver-docs-pr/network/sio-wsk-set-sendto-address.md new file mode 100644 index 0000000000..f7840185bf --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-set-sendto-address.md @@ -0,0 +1,166 @@ +--- +title: SIO_WSK_SET_SENDTO_ADDRESS +author: windows-driver-content +description: SIO_WSK_SET_SENDTO_ADDRESS +ms.assetid: 2dd149d2-adc6-4e03-92de-ed76aa048886 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_SET_SENDTO_ADDRESS Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_SET\_SENDTO\_ADDRESS + + +The SIO\_WSK\_SET\_SENDTO\_ADDRESS socket I/O control operation allows a WSK application to specify a fixed destination transport address for a datagram socket. This socket I/O control operation applies only to datagram sockets. + +If a WSK application sets a fixed destination transport address for a datagram socket, all datagrams that are sent over the socket are sent to the fixed destination transport address. However, datagrams that are received on the socket will be accepted from any transport address. + +A WSK application can override a fixed destination transport address when it sends a datagram over the socket by specifying an alternative remote transport address in the *RemoteAddress* parameter when calling the [**WskSendTo**](https://msdn.microsoft.com/library/windows/hardware/ff571148) function. In this situation, the datagram is sent to the alternative remote transport address instead of the fixed destination transport address. + +If a WSK application uses this socket I/O control operation to specify a fixed destination transport address, it must do so after the datagram socket has been bound to a local transport address. + +To set a fixed destination transport address for a datagram socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_SET_SENDTO_ADDRESS

Level

0

InputSize

The size of the SOCKADDR structure that is pointed to by the InputBuffer parameter.

InputBuffer

A pointer to a structure that specifies a fixed destination transport address for the datagram socket. The pointer must be a pointer to the specific SOCKADDR structure type that corresponds to the address family that the WSK application specified when it created the datagram socket.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To clear a fixed destination transport address for a datagram socket, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskIoctl

ControlCode

SIO_WSK_SET_SENDTO_ADDRESS

Level

0

InputSize

0

InputBuffer

NULL

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or clear a fixed destination transport address for a datagram socket. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_SET_SENDTO_ADDRESS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/sio-wsk-set-tcp-silent-mode.md b/windows-driver-docs-pr/network/sio-wsk-set-tcp-silent-mode.md new file mode 100644 index 0000000000..36bb6a62ae --- /dev/null +++ b/windows-driver-docs-pr/network/sio-wsk-set-tcp-silent-mode.md @@ -0,0 +1,97 @@ +--- +title: SIO_WSK_SET_TCP_SILENT_MODE control code +author: windows-driver-content +description: The SIO_WSK_SET_TCP_SILENT_MODE socket I/O control operation allows a WSK client to enable silent mode on the TCP connection. +ms.assetid: 8ADC7FF4-86AC-4424-B763-8B62BF440D9F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SIO_WSK_SET_TCP_SILENT_MODE control code Network Drivers Starting with Windows Vista +--- + +# SIO\_WSK\_SET\_TCP\_SILENT\_MODE control code + + +The **SIO\_WSK\_SET\_TCP\_SILENT\_MODE** socket I/O control operation allows a WSK client to enable silent mode on the TCP connection. + +A TCP connection in silent mode will not send any data or control packets on the wire. This socket I/O control operation applies only to connected TCP sockets. It is not supported on loopback. + +To perform this operation, call the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + +Parameters +---------- + +*RequestType* \[in\] +Use **WskIoctl** for this operation. + +*ControlCode* \[in\] +The control code for the operation. Use **SIO\_WSK\_SET\_TCP\_SILENT\_MODE** for this operation. + +*Level* +Use zero for this operation. + +*InputSize* \[in\] +Use zero for this operation. + +*InputBuffer* \[in\] +Use **NULL** for this operation. + +*OutputSize* \[out\] +Use zero for this operation. + +*OutputBuffer* \[in\] +Use **NULL** for this operation. + +*OutputSizeReturned* \[out\] +Use **NULL** for this operation. + +Remarks +------- + +A WSK application must specify a pointer to an IRP when calling the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function to enable silent mode. + +The WSK application before calling [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) to enable silent mode must ensure that there are no pending send or disconnect requests. + +[**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) will return **STATUS\_SUCCESS** when silent mode is enabled. Once silent mode is enabled, send and disconnect requests will be failed with **STATUS\_INVALID\_DEVICE\_STATE** and all received control or data packets will be discarded silently. + +The only valid operation on this socket is [**WskCloseSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571124). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows 8, Windows Server 2012, and later.

Header

Wsk.h (include Wsk.h)
+ +## See also + + +[**WskCloseSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571124) + +[**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SIO_WSK_SET_TCP_SILENT_MODE%20control%20code%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-broadcast.md b/windows-driver-docs-pr/network/so-broadcast.md new file mode 100644 index 0000000000..a9c7d6691b --- /dev/null +++ b/windows-driver-docs-pr/network/so-broadcast.md @@ -0,0 +1,158 @@ +--- +title: SO\_BROADCAST +author: windows-driver-content +description: SO\_BROADCAST +ms.assetid: 24b93d4e-461d-44c3-b721-85cf41a1680a +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_BROADCAST Network Drivers Starting with Windows Vista +--- + +# SO\_BROADCAST + + +The state of the SO\_BROADCAST socket option determines whether broadcast messages can be transmitted over a datagram socket. This socket option applies only to datagram sockets. + +To set the state of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_BROADCAST

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the value for the new state of the socket option:

+

0: Do not allow broadcast messages

+

1: Allow broadcast messages

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +To retrieve the state of this socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_BROADCAST

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the value of the state of the socket option:

+

0: Broadcast messages are not allowed

+

1: Broadcast messages are allowed

OutputSizeReturned

NULL

+ +  + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the state of the SO\_BROADCAST socket option. + +The default state of this socket option is that broadcast messages are not allowed. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_BROADCAST%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-conditional-accept.md b/windows-driver-docs-pr/network/so-conditional-accept.md new file mode 100644 index 0000000000..46c7ddc076 --- /dev/null +++ b/windows-driver-docs-pr/network/so-conditional-accept.md @@ -0,0 +1,172 @@ +--- +title: SO\_CONDITIONAL\_ACCEPT +author: windows-driver-content +description: SO\_CONDITIONAL\_ACCEPT +ms.assetid: 8aaaa08b-b239-4648-8c4f-8db2efbda551 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_CONDITIONAL_ACCEPT Network Drivers Starting with Windows Vista +--- + +# SO\_CONDITIONAL\_ACCEPT + + +The state of the SO\_CONDITIONAL\_ACCEPT socket option determines whether conditional acceptance mode is enabled on a listening socket. This socket option applies only to listening sockets. + +If a WSK application sets this socket option, it must do so before the listening socket is bound to a local transport address. + +To set the state of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_CONDITIONAL_ACCEPT

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the value for the new state of the socket option:

+

0: Disable conditional accept mode

+

1: Enable conditional accept mode

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To retrieve the state of this socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_CONDITIONAL_ACCEPT

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the value of the state of the socket option:

+

0: Conditional accept mode is disabled

+

1: Conditional accept mode is enabled

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the state of the SO\_CONDITIONAL\_ACCEPT socket option. + +The default state of this socket option is that conditional accept mode is disabled. + +Some transport protocols might not support conditional accept mode on listening sockets. + +For more information about conditionally accepting incoming connections, see [Listening for and Accepting Incoming Connections](https://msdn.microsoft.com/library/windows/hardware/ff557059). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_CONDITIONAL_ACCEPT%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-exclusiveaddruse.md b/windows-driver-docs-pr/network/so-exclusiveaddruse.md new file mode 100644 index 0000000000..72c3a06024 --- /dev/null +++ b/windows-driver-docs-pr/network/so-exclusiveaddruse.md @@ -0,0 +1,170 @@ +--- +title: SO\_EXCLUSIVEADDRUSE +author: windows-driver-content +description: SO\_EXCLUSIVEADDRUSE +ms.assetid: d281086f-4d8b-4e1e-b2bd-7b0a20338222 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_EXCLUSIVEADDRUSE Network Drivers Starting with Windows Vista +--- + +# SO\_EXCLUSIVEADDRUSE + + +The state of the SO\_EXCLUSIVEADDRUSE socket option determines whether the local transport address to which a socket will be bound is exclusively reserved for use by that socket. This socket option applies only to listening sockets, datagram sockets, and connection-oriented sockets. + +If a WSK application sets this socket option, it must do so before the socket is bound to a local transport address. + +To set the state of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_EXCLUSIVEADDRUSE

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the value for the new state of the socket option:

+

0: Disable exclusive use of the local transport address

+

1: Enable exclusive use of the local transport address

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To retrieve the state of this socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_EXCLUSIVEADDRUSE

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the value of the state of the socket option:

+

0: Exclusive use of the local transport address is disabled

+

1: Exclusive use of the local transport address is enabled

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the state of the SO\_EXCLUSIVEADDRUSE socket option. + +The default state of this socket option is that exclusive use of the local transport address is disabled. + +For more information about using the SO\_EXCLUSIVEADDRUSE socket option and its impact on the sharing of local transport addresses between sockets, see [Sharing Transport Addresses](https://msdn.microsoft.com/library/windows/hardware/ff570806). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_EXCLUSIVEADDRUSE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-keepalive.md b/windows-driver-docs-pr/network/so-keepalive.md new file mode 100644 index 0000000000..812b0658a8 --- /dev/null +++ b/windows-driver-docs-pr/network/so-keepalive.md @@ -0,0 +1,176 @@ +--- +title: SO\_KEEPALIVE +author: windows-driver-content +description: SO\_KEEPALIVE +ms.assetid: 47b29218-f227-4d36-b206-d8bf009252c0 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_KEEPALIVE Network Drivers Starting with Windows Vista +--- + +# SO\_KEEPALIVE + + +The state of the SO\_KEEPALIVE socket option determines whether keep-alive packets are sent on a connection-oriented socket. This socket option applies only to listening sockets and connection-oriented sockets. + +To set the state of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_KEEPALIVE

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the value for the new state of the socket option:

+
    +
  • 0: Disable sending keep-alive packets

  • +
  • 1: Enable sending keep-alive packets

  • +

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To retrieve the state of this socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_KEEPALIVE

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the value of the state of the socket option:

+
    +
  • 0: Sending keep-alive packets is disabled

  • +
  • 1: Sending keep-alive packets is enabled

  • +

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the state of the SO\_KEEPALIVE socket option. + +The default state of this socket option is that sending keep-alive packets is disabled. + +If this socket option is enabled on a listening socket, all incoming connections that are accepted on that listening socket have this socket option enabled by default. A WSK application can call the **WskControlSocket** function on an accepted socket to override the state of this socket option that was inherited from the listening socket. + +Keep-alive packets are sent by the underlying network transport. Not all network transports support sending keep-alive packets. + +For more information about using keep-alive packets, see *RFC 1122*, section 4.2.3.6, "TCP Keep-Alives". + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_KEEPALIVE%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-rcvbuf.md b/windows-driver-docs-pr/network/so-rcvbuf.md new file mode 100644 index 0000000000..bab40d6030 --- /dev/null +++ b/windows-driver-docs-pr/network/so-rcvbuf.md @@ -0,0 +1,164 @@ +--- +title: SO\_RCVBUF +author: windows-driver-content +description: SO\_RCVBUF +ms.assetid: 218b52ac-95ee-4047-ad75-76d6ae6ab14e +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_RCVBUF Network Drivers Starting with Windows Vista +--- + +# SO\_RCVBUF + + +The SO\_RCVBUF socket option determines the size of a socket's receive buffer that is used by the underlying transport. This socket option applies only to listening sockets, datagram sockets, and connection-oriented sockets. + +To set the value of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_RCVBUF

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the new size of the socket's receive buffer

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To retrieve the value of the SO\_RCVBUF socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_RCVBUF

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the current size of the socket's receive buffer

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the value of the SO\_RCVBUF socket option. + +The default size of a socket's receive buffer is transport-specific. Some transports might not support this socket option. + +If this socket option is set on a listening socket, all incoming connections that are accepted on that listening socket have their receive buffer set to the same size that is specified for the listening socket. A WSK application can call the **WskControlSocket** function on an accepted socket to override the size of the receive buffer that was inherited from the listening socket. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_RCVBUF%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-reuseaddr.md b/windows-driver-docs-pr/network/so-reuseaddr.md new file mode 100644 index 0000000000..a1542933ad --- /dev/null +++ b/windows-driver-docs-pr/network/so-reuseaddr.md @@ -0,0 +1,174 @@ +--- +title: SO\_REUSEADDR +author: windows-driver-content +description: SO\_REUSEADDR +ms.assetid: 9436492b-0bfb-4234-bcf3-c44657a846d7 +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + -SO_REUSEADDR Network Drivers Starting with Windows Vista +--- + +# SO\_REUSEADDR + + +The state of the SO\_REUSEADDR socket option determines whether the local transport address to which a socket will be bound is always shared with other sockets. This socket option applies only to listening sockets, datagram sockets, and connection-oriented sockets. + +If a WSK application sets this socket option, it must do so before the socket is bound to a local transport address. + +To set the state of this socket option, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_REUSEADDR

Level

SOL_SOCKET

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG-typed variable that contains the value for the new state of the socket option:

+
    +
  • 0: Disable always sharing the local transport address

  • +
  • 1: Enable always sharing the local transport address

  • +

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +To retrieve the state of this socket option, a WSK application calls the **WskControlSocket** function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_REUSEADDR

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(ULONG)

OutputBuffer

A pointer to a ULONG-typed variable that receives the value of the state of the socket option:

+
    +
  • 0: Always sharing the local transport address is disabled

  • +
  • 1: Always sharing the local transport address is enabled

  • +

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to set or retrieve the state of the SO\_REUSEADDR socket option. + +The default state of this socket option is that always sharing the local transport address is disabled. + +For more information about using the SO\_REUSEADDR socket option and its impact on the sharing of local transport addresses between sockets, see [Sharing Transport Addresses](https://msdn.microsoft.com/library/windows/hardware/ff570806). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_REUSEADDR%20%20RELEASE:%20%288/8/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-wsk-event-callback.md b/windows-driver-docs-pr/network/so-wsk-event-callback.md new file mode 100644 index 0000000000..0c27f6acd5 --- /dev/null +++ b/windows-driver-docs-pr/network/so-wsk-event-callback.md @@ -0,0 +1,222 @@ +--- +title: SO_WSK_EVENT_CALLBACK +author: windows-driver-content +description: SO_WSK_EVENT_CALLBACK +ms.assetid: cb697103-20ef-4667-8823-060a68d904c8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SO_WSK_EVENT_CALLBACK Network Drivers Starting with Windows Vista +--- + +# SO\_WSK\_EVENT\_CALLBACK + + +The SO\_WSK\_EVENT\_CALLBACK socket option allows a WSK application to enable and disable a socket's event callback functions. This socket option applies only to listening sockets, datagram sockets, connection-oriented sockets, and basic sockets that have registered an extension interface for which at least one event callback function is defined. + +If a WSK application uses this socket option to enable or disable event callback functions on either a listening socket or a datagram socket, it must do so after the socket has been bound to a local transport address. + +If a WSK application uses this socket option to enable or disable event callback functions on a connection-oriented socket, it must do so after the socket has been connected to a remote transport address. + +To enable or disable event callback functions on a socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_WSK_EVENT_CALLBACK

Level

SOL_SOCKET

InputSize

sizeof(WSK_EVENT_CALLBACK_CONTROL)

InputBuffer

A pointer to a [WSK_EVENT_CALLBACK_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff571166) structure

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application does not specify a pointer to an IRP when calling the **WskControlSocket** function to enable event callback functions on a socket. + +A WSK application can optionally specify a pointer to an IRP when calling the **WskControlSocket** function to disable an event callback function on a socket. + +When a WSK application calls **WskControlSocket** to disable an event callback function, the WSK subsystem behaves as follows: + +- If there are no in-progress calls to the event callback function that is being disabled when the WSK application calls the **WskControlSocket** function, the event callback function is disabled and the **WskControlSocket** function returns STATUS\_SUCCESS. If the WSK application specifies an IRP, the IRP is completed with success status. + +- If there are in-progress calls to the event callback function that is being disabled when the WSK application calls the **WskControlSocket** function and the WSK application specified an IRP, the **WskControlSocket** function returns STATUS\_PENDING. The WSK subsystem disables the event callback function and completes the IRP after all in-progress calls to the event callback function have returned. + +- If there are in-progress calls to the event callback function that is being disabled when the WSK application calls the **WskControlSocket** function and the WSK application did not specify an IRP, the **WskControlSocket** function returns STATUS\_EVENT\_PENDING. The WSK subsystem disables the event callback function after all in-progress calls to the event callback function have returned. + +When enabling or disabling any of the standard WSK event callback functions, a WSK application sets the **NpiId** member of the [**WSK\_EVENT\_CALLBACK\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff571166) structure to a pointer to the WSK [Network Programming Interface (NPI)](https://msdn.microsoft.com/library/windows/hardware/ff568373) identifier, NPI\_WSK\_INTERFACE\_ID. + +When enabling or disabling any callback functions for an extension interface, a WSK application sets the **NpiId** member of the WSK\_EVENT\_CALLBACK\_CONTROL structure to a pointer to the NPI identifier for that extension interface. + +When enabling event callback functions, a WSK application can simultaneously enable any combination of the event callback functions that are valid for a particular [category](https://msdn.microsoft.com/library/windows/hardware/ff571093) of WSK socket. The WSK application simultaneously enables these combinations by setting the **EventMask** member of the WSK\_EVENT\_CALLBACK\_CONTROL structure to a bitwise OR of the event flags for all of the event callback functions that are being enabled. + +When disabling event callback functions, a WSK application must disable each event callback function independently. A WSK application independently disables an event callback function by setting the **EventMask** member of the WSK\_EVENT\_CALLBACK\_CONTROL structure to a bitwise OR of the event flag for the event callback function that is being disabled and the WSK\_EVENT\_DISABLE flag. + +The following table shows the valid event flags for a listening socket. + + ++++ + + + + + + + + + + + + +
Event flagEvent callback function

WSK_EVENT_ACCEPT

[WskAcceptEvent](https://msdn.microsoft.com/library/windows/hardware/ff571120)

+ +  + +``` + +``` + +The following table shows the valid event flags for a datagram socket. + + ++++ + + + + + + + + + + + + +
Event flagEvent callback function

WSK_EVENT_RECEIVE_FROM

[WskReceiveFromEvent](https://msdn.microsoft.com/library/windows/hardware/ff571142)

+ +  + +``` + +``` + +The following table shows the valid event flags for a connection-oriented socket. + + ++++ + + + + + + + + + + + + + + + + + + + + +
Event flagEvent callback function

WSK_EVENT_DISCONNECT

[WskDisconnectEvent](https://msdn.microsoft.com/library/windows/hardware/ff571130)

WSK_EVENT_RECEIVE

[WskReceiveEvent](https://msdn.microsoft.com/library/windows/hardware/ff571140)

WSK_EVENT_SEND_BACKLOG

[WskSendBacklogEvent](https://msdn.microsoft.com/library/windows/hardware/ff571147)

+ +  + +``` + +``` + +A listening socket can automatically enable event callback functions on connection-oriented sockets that are accepted by the listening socket. A WSK application automatically enables these callback functions by enabling the connection-oriented socket event callback functions on the listening socket. The event callback functions are automatically enabled on an accepted connection-oriented socket only if the socket is accepted by the listening socket's [*WskAcceptEvent*](https://msdn.microsoft.com/library/windows/hardware/ff571120) event callback function. If the connection-oriented socket is accepted by the listening socket's [**WskAccept**](https://msdn.microsoft.com/library/windows/hardware/ff571109) function, the accepted socket's event callback functions are not automatically enabled. + +After any connection-oriented event callback functions are enabled on a listening socket, they cannot be disabled on the listening socket. If the *WskAcceptEvent* event callback function is disabled and then re-enabled on a listening socket, any connection-oriented event callback functions that were originally enabled on that listening socket will continue to be applied to all connection-oriented sockets that are accepted by the *WskAcceptEvent* event callback function. + +For more information about enabling and disabling a socket's event callback functions, see [Enabling and Disabling Event Callback Functions](https://msdn.microsoft.com/library/windows/hardware/ff548851). + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_WSK_EVENT_CALLBACK%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/so-wsk-security.md b/windows-driver-docs-pr/network/so-wsk-security.md new file mode 100644 index 0000000000..2564702839 --- /dev/null +++ b/windows-driver-docs-pr/network/so-wsk-security.md @@ -0,0 +1,178 @@ +--- +title: SO_WSK_SECURITY +author: windows-driver-content +description: SO_WSK_SECURITY +ms.assetid: 169680ba-6486-48fe-89d7-dcd4e5930605 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - SO_WSK_SECURITY Network Drivers Starting with Windows Vista +--- + +# SO\_WSK\_SECURITY + + +The SO\_WSK\_SECURITY socket option allows a WSK application to either apply a security descriptor to a socket or retrieve a cached copy of a socket's security descriptor from a socket. The security descriptor controls the sharing of the local transport address to which the socket is bound. + +This socket option applies only to listening sockets, datagram sockets, and connection-oriented sockets. + +If a WSK application uses this socket option to apply a security descriptor to a socket, it must do so before the socket is bound to a local transport address. + +To apply a security descriptor to a socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskSetOption

ControlCode

SO_WSK_SECURITY

Level

SOL_SOCKET

InputSize

sizeof(PSECURITY_DESCRIPTOR)

InputBuffer

A pointer to a PSECURITY_DESCRIPTOR-typed variable. This variable must contain a pointer to a cached copy of a security descriptor that was obtained by calling the [WskControlClient](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the [WSK_CACHE_SD](wsk-cache-sd.md) control code.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to apply a security descriptor to a socket. + +If a WSK application uses this socket option to apply a security descriptor to a socket, the new security descriptor replaces any security descriptor that was previously applied to the socket. + +A WSK application must not release the cached copy of the security descriptor until after the IRP is completed. + +A WSK application can also apply a security descriptor to a socket when the socket is initially created by specifying a pointer to a cached copy of a security descriptor in the *SecurityDescriptor* parameter when it calls the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149) or [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150) function. + +If a WSK application does not apply a security descriptor to a socket, the WSK subsystem uses a default security descriptor that does not allow sharing of the local transport address. + +To retrieve a cached copy of a socket's security descriptor from a socket, a WSK application calls the [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

RequestType

WskGetOption

ControlCode

SO_WSK_SECURITY

Level

SOL_SOCKET

InputSize

0

InputBuffer

NULL

OutputSize

sizeof(PSECURITY_DESCRIPTOR)

OutputBuffer

A pointer to a PSECURITY_DESCRIPTOR-typed variable. This variable receives a pointer to a cached copy of the socket's security descriptor.

OutputSizeReturned

NULL

+ +  + +``` + +``` + +A WSK application must specify a pointer to an IRP when calling the **WskControlSocket** function to retrieve a cached copy of a socket's security descriptor from a socket. + +A WSK application must call the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the [**WSK\_RELEASE\_SD**](wsk-release-sd.md) control code to release the cached copy of the security descriptor when it is no longer needed. + +For more information about the SECURITY\_DESCRIPTOR structure, see the reference page for SECURITY\_DESCRIPTOR in the Microsoft Windows SDK documentation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SO_WSK_SECURITY%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/specifying-ndis-version-information.md b/windows-driver-docs-pr/network/specifying-ndis-version-information.md index b2e16919c4..3eddbb3222 100644 --- a/windows-driver-docs-pr/network/specifying-ndis-version-information.md +++ b/windows-driver-docs-pr/network/specifying-ndis-version-information.md @@ -35,7 +35,7 @@ This section includes the following topics: ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md)   diff --git a/windows-driver-docs-pr/network/specifying-virtual-wifi-bus-dependencies.md b/windows-driver-docs-pr/network/specifying-virtual-wifi-bus-dependencies.md index b4d910f124..fd102da76b 100644 --- a/windows-driver-docs-pr/network/specifying-virtual-wifi-bus-dependencies.md +++ b/windows-driver-docs-pr/network/specifying-virtual-wifi-bus-dependencies.md @@ -35,9 +35,12 @@ Needs=VWiFiBus.Services [model.ndi.NT$ARCH$.HW] Include=netvwifibus.inf -Needs=VWiFiBus.PnPFilterRegistration +Needs=VWiFiBus.PnPFilterRegistration.HW ``` +> [!IMPORTANT] +> Starting in Windows 10, the **[VWiFiBus.PnPFilterRegistration]** section has been renamed to **[VWiFiBus.PnPFilterRegistration.HW]**. + For more information about the Ndi key, see [Creating the Ndi Key](add-registry-sections-in-a-network-inf-file.md#ddk-creating-the-ndi-key-ng). For more information about the structure of a network INF file, see [Sections in a Network INF File](sections-in-a-network-inf-file.md). diff --git a/windows-driver-docs-pr/network/sr-iov-macros.md b/windows-driver-docs-pr/network/sr-iov-macros.md new file mode 100644 index 0000000000..a9d32308a8 --- /dev/null +++ b/windows-driver-docs-pr/network/sr-iov-macros.md @@ -0,0 +1,30 @@ +--- +title: SR-IOV Macros +author: windows-driver-content +description: SR-IOV Macros +ms.assetid: 5B6B95F4-3F6E-4EE7-87AF-E4264FE95A92 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SR-IOV Macros + + +This section describes the following single root I/O virtualization (SR-IOV) macros: + +[**NDIS\_MAKE\_RID**](ndis-make-rid.md) + +[**NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID**](net-buffer-list-receive-queue-id.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20SR-IOV%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/standardized-inf-keywords-for-rss.md b/windows-driver-docs-pr/network/standardized-inf-keywords-for-rss.md index 1d7fd42ae7..958346af61 100644 --- a/windows-driver-docs-pr/network/standardized-inf-keywords-for-rss.md +++ b/windows-driver-docs-pr/network/standardized-inf-keywords-for-rss.md @@ -127,6 +127,8 @@ The number of the processor group for the processor number that is specified in **\*NumaNodeId** The preferred NUMA node that is used for the memory allocations of the network adapter. Also, the operating system attempts to use the CPUs from the preferred NUMA node first for RSS. +A driver for a PCI expansion card should not specify the NUMA node ID statically in its INF, since the closest node depends on which PCI slot the card is plugged into. Only specify **\*NumaNodeId** if the network adapter is integrated into the system, the NUMA node is known in advance, and the node cannot be determined at runtime by querying ACPI. + **Note**  If this keyword is present and its value is less than the number of NUMA nodes in the computer, NDIS uses this value in the **PreferredNumaNode** member in the [**NDIS\_RSS\_PROCESSOR\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567274) structure.   @@ -143,9 +145,23 @@ The maximum number of RSS processors. **\*RssMaxProcNumber** The maximum processor number of the RSS interface. +If **\*RssMaxProcNumber** is specified, then **\*RssMaxProcGroup** should also be specified. + + **\*RssMaxProcNumber** +The maximum processor number of the RSS interface. +If **\*RssMaxProcNumber** is specified, then **\*RssMaxProcGroup** should also be specified. + + **\*RssMaxProcGroup** +The maximum processor group of the RSS interface. - **\*NumRSSQueues** -The maximum number of the RSS queues that the device should use and advertise in the [**NDIS\_RECEIVE\_SCALE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff567220) structure. +**\*RssBaseProcGroup** together with **\*RssBaseProcNumber** form a PROCESSOR_NUMBER structure that identifies the smallest processor number that can be used with RSS. +**\*RssMaxProcGroup** together with **\*RssMaxProcNumber** form a PROCESSOR_NUMBER structure that identifies the maximum processor number that can be used with RSS. + +For example, suppose **\*RssBaseProcGroup** is set to 1, **\*RssBaseProcNumber** is set to 16, **\*RssMaxProcGroup** is set to 3, and **\*RssMaxProcNumber** is set to 8. +Using : notation, the base processor is 1:16 and the max processor is 3:8. +Then processors 0:0, 0:32, 1:0, and 1:15 will not be considered candidates for RSS, because they are below the base processor number. +Processors 1:16, 1:31, 2:0, 2:63, 3:0, and 3:8 will all be considered candidates for RSS, because they fall in the range 1:16 through 3:8. +Processors 3:9, 3:31, and 4:0 will not be considered candidates for RSS, because they are beyond the maximum processor number. NDIS 6.20 added support for the **\*RssBaseProcGroup**, **\*NumaNodeId**, **\*RssBaseProcNumber**, and **\*MaxRssProcessors** keywords. @@ -205,7 +221,7 @@ The following table describes all of the RSS keywords that can be edited.

*NumaNodeId

Preferred NUMA node

Int

-

65535 (Default)

+

65535 (Any node)

0

System specific - cannot exceed 65534

@@ -233,8 +249,8 @@ The following table describes all of the RSS keywords that can be edited.

*RssMaxProcNumber

Maximum RSS Processor Number

Int

-

0

MAXIMUM_PROC_PER_GROUP-1 (Default)

+

0

MAXIMUM_PROC_PER_GROUP-1

@@ -262,9 +278,9 @@ The following table describes all of the RSS keywords that can be edited.   -**Note**  The default value for **\*NumaNodeId** (65535) means the NUMA node identifier is not defined. +**Note**  The default value for **\*NumaNodeId** (65535) means the network adapter is agnostic to NUMA node, and NDIS should not attempt to prefer any node over another. +If the **\*NumaNodeId** keyword is not present, then NDIS automatically selects the closest node based on hints from ACPI. -  For more information about standardized INF keywords, see [Standardized INF Keywords for Network Devices](standardized-inf-keywords-for-network-devices.md). diff --git a/windows-driver-docs-pr/network/supporting-nvgre-in-checksum-offload.md b/windows-driver-docs-pr/network/supporting-nvgre-in-checksum-offload.md index cb57cc9a0c..5efdb20cf4 100644 --- a/windows-driver-docs-pr/network/supporting-nvgre-in-checksum-offload.md +++ b/windows-driver-docs-pr/network/supporting-nvgre-in-checksum-offload.md @@ -35,7 +35,7 @@ Checksum validation for NVGRE is largely the same as it would be otherwise. If a miniport receives an [OID\_TCP\_OFFLOAD\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569807) OID request and succeeds it for **NDIS\_ENCAPSULATION\_TYPE\_GRE\_MAC** (see [**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706)), the NIC must perform checksum validation on the tunnel (outer) IP header, transport (inner) IP header, and TCP or UDP header. -For encapsulated packets that have an IPv4 tunnel (outer) header and an IPv4 transport (inner) header, a miniport driver should set the **IpChecksumSucceeded** flag in the [**NDIS\_TCP\_IP\_CHECKSUM\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567877) structure only if both IP header checksum validations succeeded. For encapsulated packets that have both a tunnel (outer) IPv4 header and a transport (inner) IPv4 header, the miniport driver should set the **IpChecksumSucceeded** flag if either of the IP header checksum validations failed. +For encapsulated packets that have an IPv4 tunnel (outer) header and an IPv4 transport (inner) header, a miniport driver should set the **IpChecksumSucceeded** flag in the [**NDIS\_TCP\_IP\_CHECKSUM\_NET\_BUFFER\_LIST\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567877) structure only if both IP header checksum validations succeeded. For encapsulated packets that have both a tunnel (outer) IPv4 header and a transport (inner) IPv4 header, the miniport driver should set the **IpChecksumFailed** flag if either of the IP header checksum validations failed.   diff --git a/windows-driver-docs-pr/network/using-a-net-luid-index.md b/windows-driver-docs-pr/network/using-a-net-luid-index.md index 79c85de73c..564b94db47 100644 --- a/windows-driver-docs-pr/network/using-a-net-luid-index.md +++ b/windows-driver-docs-pr/network/using-a-net-luid-index.md @@ -1,6 +1,6 @@ --- -title: Using a NET\_LUID Index -description: Using a NET\_LUID Index +title: Using a NET_LUID Index +description: Using a NET_LUID Index ms.assetid: 21e0a73b-a02c-4ab4-b7c2-efcb8bfc806d keywords: - NDIS network interfaces WDK , NET_LUID diff --git a/windows-driver-docs-pr/network/using-layer-2-filtering.md b/windows-driver-docs-pr/network/using-layer-2-filtering.md index 8f8b60e6e1..b0938b6b3d 100644 --- a/windows-driver-docs-pr/network/using-layer-2-filtering.md +++ b/windows-driver-docs-pr/network/using-layer-2-filtering.md @@ -11,14 +11,12 @@ ms.technology: windows-devices # Using Layer 2 Filtering - Layer 2 filtering is supported in Windows 8 and later versions of Windows. This WFP feature allows filtering on fields of the layer 2 MAC header. These layers are invoked on a per-packet basis for all packets that are sent or received by the host machine. The layers are invoked prior to packet reassembly on the inbound path and after packet fragmentation on the outbound path. These layers are accessed from an NDIS lightweight filter (LWF) driver. -**Note**   A callout should not inject packets at a layer if it does not already have a corresponding filter at that layer. The injection of the [NET\_BUFFER\_LIST](net-buffer-list-structure.md) structures should be coordinated with the filter addition and removal so that injection is only performed when the filter exists in the corresponding layer. In addition, providers should not remove filters that belong to other providers. - -  +> [!NOTE] +> A callout should not inject packets at a layer if it does not already have a corresponding filter at that layer. The injection of the [NET\_BUFFER\_LIST](net-buffer-list-structure.md) structures should be coordinated with the filter addition and removal so that injection is only performed when the filter exists in the corresponding layer. In addition, providers should not remove filters that belong to other providers.  This section includes the following topics: @@ -26,7 +24,7 @@ This section includes the following topics: - [Classifying Chained Network Buffer Lists](#classifying-chained-network-buffer-lists) - [WFP Layer 2 Layers and Fields](#wfp-layer-2-layers-and-fields) -### Injecting MAC Frames +## Injecting MAC Frames A callback driver calls the [**FwpsInjectMacReceiveAsync0**](https://msdn.microsoft.com/library/windows/hardware/hh439588) function to reinject a previously absorbed MAC frame (or a clone of the frame) back to the layer 2 inbound data path it was intercepted from, or to inject an invented MAC frame in the inbound data path. @@ -40,14 +38,24 @@ Also, you must have callouts at the layer where you inject. Otherwise, your inje The [NET\_BUFFER\_LIST](net-buffer-list-structure.md)**Status** member contains the stack injection’s status result. The stack injection’s status result is the status that the stack puts in the NET\_BUFFER\_LIST after a WFP injection function returns **STATUS\_SUCCESS**. You should use the **NT\_SUCCESS** macro to check the stack injection's status in the **Status** member. If the **Status** value is **STATUS\_SUCCESS**, the injection succeeded with no further information. **Status** member values that are greater than **STATUS\_SUCCESS** mean that the injection succeeded, but there might be more information about the injection that should be considered. **Status** member values that are less than **STATUS\_SUCCESS** mean that the injection failed for the reason specified in the **Status** member. -### Classifying Chained Network Buffer Lists +## Classifying Chained Network Buffer Lists By default, a callout driver can only classify network buffer lists individually. However, a callout driver can classify [NET\_BUFFER\_LIST](net-buffer-list-structure.md) chains for better performance, if it does both of the following: - Specifies the **FWP\_CALLOUT\_FLAG\_ALLOW\_L2\_BATCH\_CLASSIFY** flag in the **Flags** member of the [**FWPS\_CALLOUT2**](https://msdn.microsoft.com/library/windows/hardware/hh439700) structure. - Registers a [*classifyFn2*](https://msdn.microsoft.com/library/windows/hardware/hh439337) function that can classify [NET\_BUFFER\_LIST](net-buffer-list-structure.md) chains. -### WFP Layer 2 Layers and Fields +> [!WARNING] +> However, if a callout driver does set the **FWP_CALLOUT_FLAG_ALLOW_L2_BATCH_CLASSIFY** flag, it cannot use the following functions to modify NET_BUFFER_LISTs. +> +> - [FwpsReferenceNetBufferList0](https://msdn.microsoft.com/library/windows/hardware/ff551206) +> - [FwpsDereferenceNetBufferList0](https://msdn.microsoft.com/library/windows/hardware/ff551159) +> - [FwpsAllocateCloneNetBufferList0](https://msdn.microsoft.com/library/windows/hardware/ff551134) +> - [FwpsFreeCloneNetBufferList0](https://msdn.microsoft.com/library/windows/hardware/ff551170) +> +> With this flag set, **FwpsAllocateCloneNetBufferList0** will always return an **INVALID_PARAMETER** error. This may unexpectedly cause a 3rd party callout driver to fail to manage the reference count of NET\_BUFFER\_LISTs, causing send and receive operations to stop. + +## WFP Layer 2 Layers and Fields Run-time Filtering Layer Identifiers for virtual switch filtering include: diff --git a/windows-driver-docs-pr/network/using-ndis-6-30-data-structures.md b/windows-driver-docs-pr/network/using-ndis-6-30-data-structures.md index f174573fdb..bf6f105c8e 100644 --- a/windows-driver-docs-pr/network/using-ndis-6-30-data-structures.md +++ b/windows-driver-docs-pr/network/using-ndis-6-30-data-structures.md @@ -20,26 +20,25 @@ NDIS can support multiple versions of the same data structure. For the Windows  The following structures were updated for NDIS 6.30: -[**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) -[**NDIS\_FILTER\_ATTACH\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff565481) -[**NDIS\_MINIPORT\_ADAPTER\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565920) -[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) -[**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) -[**NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565926) -[**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) -[**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) -[**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566705) -[**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) -[**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) -[**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) -[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) -[**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) -[**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) -[**NDIS\_RECEIVE\_QUEUE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567204) -[**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) -[**NDIS\_RECEIVE\_SCALE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff567220) -[**NDIS\_RSS\_PROCESSOR\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567274) -[**NDIS\_SHARED\_MEMORY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567303) +- [**NDIS\_BIND\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff564832) +- [**NDIS\_MINIPORT\_ADAPTER\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565920) +- [**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) +- [**NDIS\_MINIPORT\_ADAPTER\_HARDWARE\_ASSIST\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565924) +- [**NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565926) +- [**NDIS\_NET\_BUFFER\_LIST\_FILTERING\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff566567) +- [**NDIS\_NIC\_SWITCH\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566583) +- [**NDIS\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff566705) +- [**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) +- [**NDIS\_PM\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566748) +- [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759) +- [**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) +- [**NDIS\_RECEIVE\_FILTER\_INFO\_ARRAY**](https://msdn.microsoft.com/library/windows/hardware/ff567179) +- [**NDIS\_RECEIVE\_FILTER\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567181) +- [**NDIS\_RECEIVE\_QUEUE\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567204) +- [**NDIS\_RECEIVE\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567211) +- [**NDIS\_RECEIVE\_SCALE\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff567220) +- [**NDIS\_RSS\_PROCESSOR\_INFO**](https://msdn.microsoft.com/library/windows/hardware/ff567274) +- [**NDIS\_SHARED\_MEMORY\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff567303)     diff --git a/windows-driver-docs-pr/network/version-information-requirements-for-ndis-drivers.md b/windows-driver-docs-pr/network/version-information-requirements-for-ndis-drivers.md index 6f6c65b6a4..12ae8d852c 100644 --- a/windows-driver-docs-pr/network/version-information-requirements-for-ndis-drivers.md +++ b/windows-driver-docs-pr/network/version-information-requirements-for-ndis-drivers.md @@ -43,7 +43,7 @@ To access the members in structures that have version information, NDIS drivers ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md) [Specifying NDIS Version Information](specifying-ndis-version-information.md) diff --git a/windows-driver-docs-pr/network/version-information-requirements-for-ndis.md b/windows-driver-docs-pr/network/version-information-requirements-for-ndis.md index 2adbefdaf5..c7af41939e 100644 --- a/windows-driver-docs-pr/network/version-information-requirements-for-ndis.md +++ b/windows-driver-docs-pr/network/version-information-requirements-for-ndis.md @@ -24,7 +24,7 @@ NDIS supports various header version information requirements that guarantee con ## Related topics -[NDIS Versions in Network Drivers](ndis-versions-in-network-drivers.md) +[Overview of NDIS versions](overview-of-ndis-versions.md) [Specifying NDIS Version Information](specifying-ndis-version-information.md) diff --git a/windows-driver-docs-pr/network/virtual-machine-queue-status-indications.md b/windows-driver-docs-pr/network/virtual-machine-queue-status-indications.md new file mode 100644 index 0000000000..1338873ddf --- /dev/null +++ b/windows-driver-docs-pr/network/virtual-machine-queue-status-indications.md @@ -0,0 +1,35 @@ +--- +title: VMQ Status Indications +author: windows-driver-content +description: VMQ Status Indications +ms.assetid: 26f903b2-864b-48cf-b0ee-2761cb69d10b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# VMQ Status Indications + + +## + + +This section describes the following NDIS status indications that can be used by a miniport driver that supports the virtual machine queue (VMQ) interface: + +[**NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_ALLOCATION\_STATE**](https://msdn.microsoft.com/library/windows/hardware/hh439818) + +[**NDIS\_STATUS\_RECEIVE\_FILTER\_QUEUE\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/hh439820) + +[**NDIS\_STATUS\_RECEIVE\_QUEUE\_STATE**](ndis-status-receive-queue-state.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20VMQ%20Status%20Indications%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/vmq-macros.md b/windows-driver-docs-pr/network/vmq-macros.md new file mode 100644 index 0000000000..70730f36f9 --- /dev/null +++ b/windows-driver-docs-pr/network/vmq-macros.md @@ -0,0 +1,28 @@ +--- +title: VMQ Macros +author: windows-driver-content +description: VMQ Macros +ms.assetid: 7E90D97A-2F6D-4770-8AC3-A6899F578EB1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# VMQ Macros + + +This section includes the following virtual machine queue (VMQ) macros: + +[**NET\_BUFFER\_LIST\_RECEIVE\_QUEUE\_ID**](net-buffer-list-receive-queue-id.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20VMQ%20Macros%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-miniport-driver-property-oids.md b/windows-driver-docs-pr/network/wdi-miniport-driver-property-oids.md new file mode 100644 index 0000000000..15017b1245 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-miniport-driver-property-oids.md @@ -0,0 +1,76 @@ +--- +title: WDI Property OIDs +author: windows-driver-content +description: This section contains WDI property OIDs. +ms.assetid: 1B1B54B8-6CE4-4C17-AAF8-7394210B09E8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDI Property OIDs + + +This section contains WDI property OIDs. + +The Wi-Fi Driver Interface (WDI) object identifiers (OIDs) apply only to miniport drivers that implement WDI. + +The following table specifies whether WDI OID query (Q), set (S), and NDIS 6.0 method (M) requests are required or optional to implement: + +**R** +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning the status code NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**O** +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +| Name | Q | S | M | +|-----------------------------------------------------------------------------------------------------|-----|-----|-----| +| [OID\_WDI\_ABORT\_TASK](oid-wdi-abort-task.md) | | | R | +| [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](oid-wdi-get-adapter-capabilities.md) | | | R | +| [OID\_WDI\_GET\_AUTO\_POWER\_SAVE](oid-wdi-get-auto-power-save.md) | | | R | +| [OID\_WDI\_GET\_BSS\_ENTRY\_LIST](oid-wdi-get-bss-entry-list.md) | | | O | +| [OID\_WDI\_GET\_NEXT\_ACTION\_FRAME\_DIALOG\_TOKEN](oid-wdi-get-next-action-frame-dialog-token.md) | | | O | +| [OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-get-pm-protocol-offload.md) | | | O | +| [OID\_WDI\_GET\_RECEIVE\_COALESCING\_MATCH\_COUNT](oid-wdi-get-receive-coalescing-match-count.md) | | | O | +| [OID\_WDI\_GET\_STATISTICS](oid-wdi-get-statistics.md) | | | R | +| [OID\_WDI\_IHV\_REQUEST](oid-wdi-ihv-request.md) | | | O | +| [OID\_WDI\_SET\_ADAPTER\_CONFIGURATION](oid-wdi-set-adapter-configuration.md) | | | R | +| [OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](oid-wdi-set-add-cipher-keys.md) | | | R | +| [OID\_WDI\_SET\_ADD\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-add-pm-protocol-offload.md) | | | O | +| [OID\_WDI\_SET\_ADD\_WOL\_PATTERN](oid-wdi-set-add-wol-pattern.md) | | | O | +| [OID\_WDI\_SET\_ADVERTISEMENT\_INFORMATION](oid-wdi-set-advertisement-information.md) | | | O | +| [OID\_WDI\_SET\_ASSOCIATION\_PARAMETERS](oid-wdi-set-association-parameters.md) | | | R | +| [OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING](oid-wdi-set-clear-receive-coalescing.md) | | | O | +| [OID\_WDI\_SET\_CONNECTION\_QUALITY](oid-wdi-set-connection-quality.md) | | | R | +| [OID\_WDI\_SET\_DEFAULT\_KEY\_ID](oid-wdi-set-default-key-id.md) | | | R | +| [OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS](oid-wdi-set-delete-cipher-keys.md) | | | R | +| [OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD](oid-wdi-set-encapsulation-offload.md) | | | O | +| [OID\_WDI\_SET\_FLUSH\_BSS\_ENTRY](oid-wdi-set-flush-bss-entry.md) | | | O | +| [OID\_WDI\_SET\_MULTICAST\_LIST](oid-wdi-set-multicast-list.md) | | | R | +| [OID\_WDI\_SET\_NETWORK\_LIST\_OFFLOAD](oid-wdi-set-network-list-offload.md) | | | O | +| [OID\_WDI\_SET\_P2P\_LISTEN\_STATE](oid-wdi-set-p2p-listen-state.md) | | | O | +| [OID\_WDI\_SET\_P2P\_START\_BACKGROUND\_DISCOVERY](oid-wdi-set-p2p-start-background-discovery.md) | | | O | +| [OID\_WDI\_SET\_P2P\_STOP\_BACKGROUND\_DISCOVERY](oid-wdi-set-p2p-stop-background-discovery.md) | | | O | +| [OID\_WDI\_SET\_P2P\_WPS\_ENABLED](oid-wdi-set-p2p-wps-enabled.md) | | | O | +| [OID\_WDI\_SET\_POWER\_STATE](oid-wdi-set-power-state.md) | | | R | +| [OID\_WDI\_SET\_PRIVACY\_EXEMPTION\_LIST](oid-wdi-set-privacy-exemption-list.md) | | | R | +| [OID\_WDI\_SET\_RECEIVE\_COALESCING](oid-wdi-set-receive-coalescing.md) | | | O | +| [OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER](oid-wdi-set-receive-packet-filter.md) | | | R | +| [OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD](oid-wdi-set-remove-pm-protocol-offload.md) | | | O | +| [OID\_WDI\_SET\_REMOVE\_WOL\_PATTERN](oid-wdi-set-remove-wol-pattern.md) | | | O | +| [OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS](oid-wdi-set-tcp-offload-parameters.md) | | | O | +| [OID\_WDI\_TCP\_RSC\_STATISTICS](oid-wdi-tcp-rsc-statistics.md) | | | O | + +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI%20Property%20OIDs%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-miniport-driver-status-indications.md b/windows-driver-docs-pr/network/wdi-miniport-driver-status-indications.md new file mode 100644 index 0000000000..fe7e989c3d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-miniport-driver-status-indications.md @@ -0,0 +1,72 @@ +--- +title: WDI Miniport Driver Status Indications +author: windows-driver-content +description: This section contains WDI status notifications. +ms.assetid: CD873C33-72ED-4F99-A584-5C307F4FB65E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDI Miniport Driver Status Indications + + +This section contains WDI status notifications. + +## In this section + + +- [NDIS\_STATUS\_WDI\_INDICATION\_ACTION\_FRAME\_RECEIVED](ndis-status-wdi-indication-action-frame-received.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_AP\_ASSOCIATION\_REQUEST\_RECEIVED](ndis-status-wdi-indication-ap-association-request-received.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_PARAMETERS\_REQUEST](ndis-status-wdi-indication-association-parameters-request.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_ASSOCIATION\_RESULT](ndis-status-wdi-indication-association-result.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_BSS\_ENTRY\_LIST](ndis-status-wdi-indication-bss-entry-list.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP](ndis-status-wdi-indication-can-sustain-ap.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_CHANGE\_OPERATION\_MODE\_COMPLETE](ndis-status-wdi-indication-change-operation-mode-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_CLOSE\_COMPLETE](ndis-status-wdi-indication-close-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_CONNECT\_COMPLETE](ndis-status-wdi-indication-connect-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_CREATE\_PORT\_COMPLETE](ndis-status-wdi-indication-create-port-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_DELETE\_PORT\_COMPLETE](ndis-status-wdi-indication-delete-port-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION](ndis-status-wdi-indication-disassociation.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_DISCONNECT\_COMPLETE](ndis-status-wdi-indication-disconnect-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_DOT11\_RESET\_COMPLETE](ndis-status-wdi-indication-dot11-reset-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_FIRMWARE\_STALLED](ndis-status-wdi-indication-firmware-stalled.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_FT\_ASSOC\_PARAMS\_NEEDED](ndis-status-wdi-indication-ft-assoc-params-needed.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_EVENT](ndis-status-wdi-indication-ihv-event.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_COMPLETE](ndis-status-wdi-indication-ihv-task-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST](ndis-status-wdi-indication-ihv-task-request.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_LINK\_STATE\_CHANGE](ndis-status-wdi-indication-link-state-change.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_NLO\_DISCOVERY](ndis-status-wdi-indication-nlo-discovery.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_OPEN\_COMPLETE](ndis-status-wdi-indication-open-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_ACTION\_FRAME\_RECEIVED](ndis-status-wdi-indication-p2p-action-frame-received.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_DISCOVERY\_COMPLETE](ndis-status-wdi-indication-p2p-discovery-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_GROUP\_OPERATING\_CHANNEL](ndis-status-wdi-indication-p2p-group-operating-channel.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_OPERATING\_CHANNEL\_ATTRIBUTES](ndis-status-wdi-indication-p2p-operating-channel-attributes.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-p2p-send-request-action-frame-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-p2p-send-response-action-frame-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_RADIO\_STATUS](ndis-status-wdi-indication-radio-status.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_ROAM\_COMPLETE](ndis-status-wdi-indication-roam-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED](ndis-status-wdi-indication-roaming-needed.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_SCAN\_COMPLETE](ndis-status-wdi-indication-scan-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_SEND\_AP\_ASSOCIATION\_RESPONSE\_COMPLETE](ndis-status-wdi-indication-send-ap-association-response-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_SEND\_REQUEST\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-send-request-action-frame-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_SEND\_RESPONSE\_ACTION\_FRAME\_COMPLETE](ndis-status-wdi-indication-send-response-action-frame-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_SET\_RADIO\_STATE\_COMPLETE](ndis-status-wdi-indication-set-radio-state-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_START\_AP\_COMPLETE](ndis-status-wdi-indication-start-ap-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP](ndis-status-wdi-indication-stop-ap.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP\_COMPLETE](ndis-status-wdi-indication-stop-ap-complete.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_TASK\_OFFLOAD\_CURRENT\_CONFIG](ndis-status-wdi-indication-task-offload-current-config.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_TKIP\_MIC\_FAILURE](ndis-status-wdi-indication-tkip-mic-failure.md) +- [NDIS\_STATUS\_WDI\_INDICATION\_WAKE\_REASON](ndis-status-wdi-indication-wake-reason.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI%20Miniport%20Driver%20Status%20Indications%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-miniport-driver-task-oids.md b/windows-driver-docs-pr/network/wdi-miniport-driver-task-oids.md new file mode 100644 index 0000000000..b7e3058980 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-miniport-driver-task-oids.md @@ -0,0 +1,177 @@ +--- +title: WDI Task OIDs +author: windows-driver-content +description: This section contains WDI task OIDs. +ms.assetid: CAA92CA5-5CD6-4705-AA4C-54C1AA83ACA3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDI Task OIDs + + +This section contains WDI task OIDs. + +The Wi-Fi Driver Interface (WDI) object identifiers (OIDs) apply only to miniport drivers that implement WDI. + +The following table specifies whether WDI OID query (Q), set (S), and NDIS 6.0 method (M) requests are required or optional to implement: + +**R** +Indicates that support for the object is required. The miniport driver must not fail set or query requests for the object by returning the status code NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + +**O** +Indicates that support for the object is optional. The miniport driver can either support query or set requests for the object, or the driver can fail the request by returning NDIS\_STATUS\_NOT\_SUPPORTED from its [*MiniportOidRequest*](https://msdn.microsoft.com/library/windows/hardware/ff559416) function. + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameQSM

[OID_WDI_TASK_CHANGE_OPERATION_MODE](oid-wdi-task-change-operation-mode.md)

R

[OID_WDI_TASK_CLOSE](oid-wdi-task-close.md)

R

[OID_WDI_TASK_CONNECT](oid-wdi-task-connect.md)

R

[OID_WDI_TASK_CREATE_PORT](oid-wdi-task-create-port.md)

R

[OID_WDI_TASK_DELETE_PORT](oid-wdi-task-delete-port.md)

R

[OID_WDI_TASK_DISCONNECT](oid-wdi-task-disconnect.md)

R

[OID_WDI_TASK_DOT11_RESET](oid-wdi-task-dot11-reset.md)

R

[OID_WDI_TASK_IHV](oid-wdi-task-ihv.md)

O

[OID_WDI_TASK_OPEN](oid-wdi-task-open.md)

O

[OID_WDI_TASK_P2P_DISCOVER](oid-wdi-task-p2p-discover.md)

O

[OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME](oid-wdi-task-p2p-send-request-action-frame.md)

O

[OID_WDI_TASK_P2P_SEND_RESPONSE_ACTION_FRAME](oid-wdi-task-p2p-send-response-action-frame.md)

O

[OID_WDI_TASK_ROAM](oid-wdi-task-roam.md)

R

[OID_WDI_TASK_SCAN](oid-wdi-task-scan.md)

R

[OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE](oid-wdi-task-send-ap-association-response.md)

O

[OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME](oid-wdi-task-send-request-action-frame.md)

O

[OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME](oid-wdi-task-send-response-action-frame.md)

O

[OID_WDI_TASK_SET_RADIO_STATE](oid-wdi-task-set-radio-state.md)

R

[OID_WDI_TASK_START_AP](oid-wdi-task-start-ap.md)

O

[OID_WDI_TASK_STOP_AP](oid-wdi-task-stop-ap.md)

O

+ +  + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI%20Task%20OIDs%20%20RELEASE:%20%286/30/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-miniport-driver-tlvs.md b/windows-driver-docs-pr/network/wdi-miniport-driver-tlvs.md new file mode 100644 index 0000000000..ef5c0a3ce1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-miniport-driver-tlvs.md @@ -0,0 +1,321 @@ +--- +title: WDI Miniport Driver TLVs +author: windows-driver-content +description: This section contains WDI TLVs (Type-Length-Value). +ms.assetid: BAE1E159-F0CB-4A74-9E35-4361C94518E6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# WDI Miniport Driver TLVs + + +This section contains WDI TLVs (Type-Length-Value). + +## In this section + + +- [**WDI\_TLV\_ACCESS\_NETWORK\_TYPE**](wdi-tlv-access-network-type.md) +- [**WDI\_TLV\_ACTION\_FRAME\_BODY**](wdi-tlv-action-frame-body.md) +- [**WDI\_TLV\_ACTION\_FRAME\_DEVICE\_CONTEXT**](wdi-tlv-action-frame-device-context.md) +- [**WDI\_TLV\_ADAPTER\_NLO\_SCAN\_MODE**](wdi-tlv-adapter-nlo-scan-mode.md) +- [**WDI\_TLV\_ADAPTER\_RESUME\_REQUIRED**](wdi-tlv-adapter-resume-required.md) +- [**WDI\_TLV\_ADDITIONAL\_BEACON\_IES**](wdi-tlv-additional-beacon-ies.md) +- [**WDI\_TLV\_ADDITIONAL\_IES**](wdi-tlv-additional-ies.md) +- [**WDI\_TLV\_ADDITIONAL\_PROBE\_REQUEST\_DEFAULT\_IES**](wdi-tlv-additional-probe-request-default-ies.md) +- [**WDI\_TLV\_ADDITIONAL\_PROBE\_RESPONSE\_IES**](wdi-tlv-additional-probe-response-ies.md) +- [**WDI\_TLV\_ALLOWED\_BSSIDS\_LIST**](wdi-tlv-allowed-bssids-list.md) +- [**WDI\_TLV\_ANQP\_ELEMENTS**](wdi-tlv-anqp-elements.md) +- [**WDI\_TLV\_ANQP\_QUERY\_PARAMETERS**](wdi-tlv-anqp-query-parameters.md) +- [**WDI\_TLV\_ANQP\_QUERY\_STATUS**](wdi-tlv-anqp-query-status.md) +- [**WDI\_TLV\_AP\_ATTRIBUTES**](wdi-tlv-ap-attributes.md) +- [**WDI\_TLV\_AP\_BAND\_CHANNEL**](wdi-tlv-ap-band-channel.md) +- [**WDI\_TLV\_AP\_CAPABILITIES**](wdi-tlv-ap-capabilities.md) +- [**WDI\_TLV\_ASSOCIATION\_PARAMETERS\_REQUESTED\_TYPE**](wdi-tlv-association-parameters-requested-type.md) +- [**WDI\_TLV\_ASSOCIATION\_REQUEST\_DEVICE\_CONTEXT**](wdi-tlv-association-request-device-context.md) +- [**WDI\_TLV\_ASSOCIATION\_REQUEST\_FRAME**](wdi-tlv-association-request-frame.md) +- [**WDI\_TLV\_ASSOCIATION\_REQUEST\_IES**](wdi-tlv-association-request-ies.md) +- [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME**](wdi-tlv-association-response-frame.md) +- [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_IES**](wdi-tlv-association-response-ies.md) +- [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_PARAMETERS**](wdi-tlv-association-response-parameters.md) +- [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_RESULT\_PARAMETERS**](wdi-tlv-association-response-result-parameters.md) +- [**WDI\_TLV\_ASSOCIATION\_RESULT**](wdi-tlv-association-result.md) +- [**WDI\_TLV\_ASSOCIATION\_RESULT\_PARAMETERS**](wdi-tlv-association-result-parameters.md) +- [**WDI\_TLV\_AUTH\_ALGO\_LIST**](wdi-tlv-auth-algo-list.md) +- [**WDI\_TLV\_AUTHENTICATION\_RESPONSE\_FRAME**](wdi-tlv-authentication-response-frame.md) +- [**WDI\_TLV\_BAND\_CAPABILITIES**](wdi-tlv-band-capabilities.md) +- [**WDI\_TLV\_BAND\_CHANNEL**](wdi-tlv-band-channel.md) +- [**WDI\_TLV\_BAND\_ID\_LIST**](wdi-tlv-band-id-list.md) +- [**WDI\_TLV\_BAND\_INFO**](wdi-tlv-band-info.md) +- [**WDI\_TLV\_BANDID**](wdi-tlv-bandid.md) +- [**WDI\_TLV\_BEACON\_FRAME**](wdi-tlv-beacon-frame.md) +- [**WDI\_TLV\_BEACON\_IES**](wdi-tlv-beacon-ies.md) +- [**WDI\_TLV\_BEACON\_PROBE\_RESPONSE**](wdi-tlv-beacon-probe-response.md) +- [**WDI\_TLV\_BITMAP\_PATTERN**](wdi-tlv-bitmap-pattern.md) +- [**WDI\_TLV\_BITMAP\_PATTERN\_AND\_MASK**](wdi-tlv-bitmap-pattern-and-mask.md) +- [**WDI\_TLV\_BITMAP\_PATTERN\_MASK**](wdi-tlv-bitmap-pattern-mask.md) +- [**WDI\_TLV\_BSS\_ENTRY**](wdi-tlv-bss-entry.md) +- [**WDI\_TLV\_BSS\_ENTRY\_AGE\_INFO**](wdi-tlv-bss-entry-age-info.md) +- [**WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO**](wdi-tlv-bss-entry-channel-info.md) +- [**WDI\_TLV\_BSS\_ENTRY\_DEVICE\_CONTEXT**](wdi-tlv-bss-entry-device-context.md) +- [**WDI\_TLV\_BSS\_ENTRY\_PHY\_INFO**](wdi-tlv-bss-entry-phy-info.md) +- [**WDI\_TLV\_BSS\_ENTRY\_SIGNAL\_INFO**](wdi-tlv-bss-entry-signal-info.md) +- [**WDI\_TLV\_BSS\_SELECTION\_PARAMETERS**](wdi-tlv-bss-selection-parameters.md) +- [**WDI\_TLV\_BSSID**](wdi-tlv-bssid.md) +- [**WDI\_TLV\_BSSID\_INFO**](wdi-tlv-bssid-info.md) +- [**WDI\_TLV\_CANCEL\_PARAMETERS**](wdi-tlv-cancel-parameters.md) +- [**WDI\_TLV\_CHANNEL\_INFO\_LIST**](wdi-tlv-channel-info-list.md) +- [**WDI\_TLV\_CHANNEL\_LIST**](wdi-tlv-channel-list.md) +- [**WDI\_TLV\_CHANNEL\_NUMBER**](wdi-tlv-channel-number.md) +- [**WDI\_TLV\_CHANNEL\_WIDTH\_LIST**](wdi-tlv-channel-width-list.md) +- [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_CAPABILITIES**](wdi-tlv-checksum-offload-capabilities.md) +- [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_RX\_PARAMETERS**](wdi-tlv-checksum-offload-v4-rx-parameters.md) +- [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_TX\_PARAMETERS**](wdi-tlv-checksum-offload-v4-tx-parameters.md) +- [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_RX\_PARAMETERS**](wdi-tlv-checksum-offload-v6-rx-parameters.md) +- [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_TX\_PARAMETERS**](wdi-tlv-checksum-offload-v6-tx-parameters.md) +- [**WDI\_TLV\_CIPHER\_KEY\_BIP\_KEY**](wdi-tlv-cipher-key-bip-key.md) +- [**WDI\_TLV\_CIPHER\_KEY\_CCMP\_KEY**](wdi-tlv-cipher-key-ccmp-key.md) +- [**WDI\_TLV\_CIPHER\_KEY\_GCMP\_KEY**](wdi-tlv-cipher-key-gcmp-key.md) +- [**WDI\_TLV\_CIPHER\_KEY\_ID**](wdi-tlv-cipher-key-id.md) +- [**WDI\_TLV\_CIPHER\_KEY\_IHV\_KEY**](wdi-tlv-cipher-key-ihv-key.md) +- [**WDI\_TLV\_CIPHER\_KEY\_RECEIVE\_SEQUENCE\_COUNT**](wdi-tlv-cipher-key-receive-sequence-count.md) +- [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_INFO**](wdi-tlv-cipher-key-tkip-info.md) +- [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_KEY**](wdi-tlv-cipher-key-tkip-key.md) +- [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_MIC**](wdi-tlv-cipher-key-tkip-mic.md) +- [**WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO**](wdi-tlv-cipher-key-type-info.md) +- [**WDI\_TLV\_CIPHER\_KEY\_WEP\_KEY**](wdi-tlv-cipher-key-wep-key.md) +- [**WDI\_TLV\_COALESCING\_FILTER\_MATCH\_COUNT**](wdi-tlv-coalescing-filter-match-count.md) +- [**WDI\_TLV\_COMMUNICATION\_CAPABILITIES**](wdi-tlv-communication-capabilities.md) +- [**WDI\_TLV\_COMMUNICATION\_CONFIGURATION\_ATTRIBUTES**](wdi-tlv-communication-configuration-attributes.md) +- [**WDI\_TLV\_CONFIGURED\_MAC\_ADDRESS**](wdi-tlv-configured-mac-address.md) +- [**WDI\_TLV\_CONNECT\_BSS\_ENTRY**](wdi-tlv-connect-bss-entry.md) +- [**WDI\_TLV\_CONNECT\_PARAMETERS**](wdi-tlv-connect-parameters.md) +- [**WDI\_TLV\_CONNECTION\_QUALITY\_PARAMETERS**](wdi-tlv-connection-quality-parameters.md) +- [**WDI\_TLV\_CONNECTION\_SETTINGS**](wdi-tlv-connection-settings.md) +- [**WDI\_TLV\_COUNTRY\_REGION\_LIST**](wdi-tlv-country-region-list.md) +- [**WDI\_TLV\_CREATE\_PORT\_MAC\_ADDRESS**](wdi-tlv-create-port-mac-address.md) +- [**WDI\_TLV\_CREATE\_PORT\_PARAMETERS**](wdi-tlv-create-port-parameters.md) +- [**WDI\_TLV\_CURRENT\_CHANNEL\_PARAMETERS**](wdi-tlv-current-channel-parameters.md) +- [**WDI\_TLV\_DATAPATH\_ATTRIBUTES**](wdi-tlv-datapath-attributes.md) +- [**WDI\_TLV\_DATAPATH\_CAPABILITIES**](wdi-tlv-datapath-capabilities.md) +- [**WDI\_TLV\_DEFAULT\_TX\_KEY\_ID\_PARAMETERS**](wdi-tlv-default-tx-key-id-parameters.md) +- [**WDI\_TLV\_DELETE\_CIPHER\_KEY\_INFO**](wdi-tlv-delete-cipher-key-info.md) +- [**WDI\_TLV\_DELETE\_PEER\_STATE\_PARAMETERS**](wdi-tlv-delete-peer-state-parameters.md) +- [**WDI\_TLV\_DELETE\_PORT\_PARAMETERS**](wdi-tlv-delete-port-parameters.md) +- [**WDI\_TLV\_DISALLOWED\_BSSIDS\_LIST**](wdi-tlv-disallowed-bssids-list.md) +- [**WDI\_TLV\_DISASSOCIATION\_INDICATION\_PARAMETERS**](wdi-tlv-disassociation-indication-parameters.md) +- [**WDI\_TLV\_DISASSOCIATION\_PARAMETERS**](wdi-tlv-disassociation-parameters.md) +- [**WDI\_TLV\_DISCONNECT\_DEAUTH\_FRAME**](wdi-tlv-disconnect-deauth-frame.md) +- [**WDI\_TLV\_DISCONNECT\_DISASSOCIATION\_FRAME**](wdi-tlv-disconnect-disassociation-frame.md) +- [**WDI\_TLV\_DISCONNECT\_PARAMETERS**](wdi-tlv-disconnect-parameters.md) +- [**WDI\_TLV\_DOT11\_RESET\_PARAMETERS**](wdi-tlv-dot11-reset-parameters.md) +- [**WDI\_TLV\_ENABLE\_WAKE\_EVENTS**](wdi-tlv-enable-wake-events.md) +- [**WDI\_TLV\_ETHERTYPE\_ENCAP\_TABLE**](wdi-tlv-ethertype-encap-table.md) +- [**WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES**](wdi-tlv-extra-association-request-ies.md) +- [**WDI\_TLV\_FIRMWARE\_VERSION**](wdi-tlv-firmware-version.md) +- [**WDI\_TLV\_FT\_AUTH\_REQUEST**](wdi-tlv-ft-auth-request.md) +- [**WDI\_TLV\_FT\_AUTH\_RESPONSE**](wdi-tlv-ft-auth-response.md) +- [**WDI\_TLV\_FT\_FTE**](wdi-tlv-ft-fte.md) +- [**WDI\_TLV\_FT\_INITIAL\_ASSOC\_PARAMETERS**](wdi-tlv-ft-initial-assoc-parameters.md) +- [**WDI\_TLV\_FT\_MDE**](wdi-tlv-ft-mde.md) +- [**WDI\_TLV\_FT\_PMKR0NAME**](wdi-tlv-ft-pmkr0name.md) +- [**WDI\_TLV\_FT\_R0KHID**](wdi-tlv-ft-r0khid.md) +- [**WDI\_TLV\_FT\_R1KHID**](wdi-tlv-ft-r1khid.md) +- [**WDI\_TLV\_FT\_REASSOC\_PARAMETERS**](wdi-tlv-ft-reassoc-parameters.md) +- [**WDI\_TLV\_FT\_RSNIE**](wdi-tlv-ft-rsnie.md) +- [**WDI\_TLV\_FT\_SNONCE**](wdi-tlv-ft-snonce.md) +- [**WDI\_TLV\_GET\_AUTO\_POWER\_SAVE**](wdi-tlv-get-auto-power-save.md) +- [**WDI\_TLV\_HESSID**](wdi-tlv-hessid.md) +- [**WDI\_TLV\_HESSID\_INFO**](wdi-tlv-hessid-info.md) +- [**WDI\_TLV\_HOTSPOT\_DOMAIN\_PARTNER**](wdi-tlv-hotspot-domain-partner.md) +- [**WDI\_TLV\_HOTSPOT\_INDICATION\_ELEMENT**](wdi-tlv-hotspot-indication-element.md) +- [**WDI\_TLV\_IHV\_DATA**](wdi-tlv-ihv-data.md) +- [**WDI\_TLV\_IHV\_NON\_WDI\_OIDS\_LIST**](wdi-tlv-ihv-non-wdi-oids-list.md) +- [**WDI\_TLV\_IHV\_TASK\_DEVICE\_CONTEXT**](wdi-tlv-ihv-task-device-context.md) +- [**WDI\_TLV\_IHV\_TASK\_REQUEST\_PARAMETERS**](wdi-tlv-ihv-task-request-parameters.md) +- [**WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_INFO**](wdi-tlv-incoming-association-request-info.md) +- [**WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_PARAMETERS**](wdi-tlv-incoming-association-request-parameters.md) +- [**WDI\_TLV\_INDICATION\_CAN\_SUSTAIN\_AP**](wdi-tlv-indication-can-sustain-ap.md) +- [**WDI\_TLV\_INDICATION\_STOP\_AP**](wdi-tlv-indication-stop-ap.md) +- [**WDI\_TLV\_INDICATION\_WAKE\_PACKET**](wdi-tlv-indication-wake-packet.md) +- [**WDI\_TLV\_INDICATION\_WAKE\_PACKET\_PATTERN\_ID**](wdi-tlv-indication-wake-packet-pattern-id.md) +- [**WDI\_TLV\_INDICATION\_WAKE\_REASON**](wdi-tlv-indication-wake-reason.md) +- [**WDI\_TLV\_INTERFACE\_ATTRIBUTES**](wdi-tlv-interface-attributes.md) +- [**WDI\_TLV\_INTERFACE\_CAPABILITIES**](wdi-tlv-interface-capabilities.md) +- [**WDI\_TLV\_IPV4\_CHECKSUM\_OFFLOAD**](wdi-tlv-ipv4-checksum-offload.md) +- [**WDI\_TLV\_IPV4\_LSO\_V2**](wdi-tlv-ipv4-lso-v2.md) +- [**WDI\_TLV\_IPV6\_CHECKSUM\_OFFLOAD**](wdi-tlv-ipv6-checksum-offload.md) +- [**WDI\_TLV\_IPV6\_LSO\_V2**](wdi-tlv-ipv6-lso-v2.md) +- [**WDI\_TLV\_LINK\_QUALITY\_BAR\_MAP**](wdi-tlv-link-quality-bar-map.md) +- [**WDI\_TLV\_LINK\_STATE\_CHANGE\_PARAMETERS**](wdi-tlv-link-state-change-parameters.md) +- [**WDI\_TLV\_LOW\_LATENCY\_CONNECTION\_QUALITY\_PARAMETERS**](wdi-tlv-low-latency-connection-quality-parameters.md) +- [**WDI\_TLV\_LSO\_V1\_CAPABILITIES**](wdi-tlv-lso-v1-capabilities.md) +- [**WDI\_TLV\_LSO\_V2\_CAPABILITIES**](wdi-tlv-lso-v2-capabilities.md) +- [**WDI\_TLV\_MAC\_STATISTICS**](wdi-tlv-mac-statistics.md) +- [**WDI\_TLV\_MULTICAST\_CIPHER\_ALGO\_LIST**](wdi-tlv-multicast-cipher-algo-list.md) +- [**WDI\_TLV\_MULTICAST\_DATA\_ALGORITHM\_LIST**](wdi-tlv-multicast-data-algorithm-list.md) +- [**WDI\_TLV\_MULTICAST\_LIST**](wdi-tlv-multicast-list.md) +- [**WDI\_TLV\_MULTICAST\_MGMT\_ALGORITHM\_LIST**](wdi-tlv-multicast-mgmt-algorithm-list.md) +- [**WDI\_TLV\_NEIGHBOR\_REPORT\_ENTRY**](wdi-tlv-neighbor-report-entry.md) +- [**WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_CONFIG**](wdi-tlv-network-list-offload-config.md) +- [**WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_PARAMETERS**](wdi-tlv-network-list-offload-parameters.md) +- [**WDI\_TLV\_NETWORK\_OFFLOAD\_CHANNELS**](wdi-tlv-network-offload-channels.md) +- [**WDI\_TLV\_NEXT\_DIALOG\_TOKEN**](wdi-tlv-next-dialog-token.md) +- [**WDI\_TLV\_OPERATING\_CLASS**](wdi-tlv-operating-class.md) +- [**WDI\_TLV\_OPERATION\_MODE**](wdi-tlv-operation-mode.md) +- [**WDI\_TLV\_P2P\_ACTION\_FRAME\_DEVICE\_CONTEXT**](wdi-tlv-p2p-action-frame-device-context.md) +- [**WDI\_TLV\_P2P\_ACTION\_FRAME\_IES**](wdi-tlv-p2p-action-frame-ies.md) +- [**WDI\_TLV\_P2P\_ACTION\_FRAME\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-action-frame-response-parameters.md) +- [**WDI\_TLV\_P2P\_ADVERTISED\_PREFIX\_ENTRY**](wdi-tlv-p2p-advertised-prefix-entry.md) +- [**WDI\_TLV\_P2P\_ADVERTISED\_SERVICE\_ENTRY**](wdi-tlv-p2p-advertised-service-entry.md) +- [**WDI\_TLV\_P2P\_ADVERTISED\_SERVICES**](wdi-tlv-p2p-advertised-services.md) +- [**WDI\_TLV\_P2P\_ADVERTISEMENT\_ID**](wdi-tlv-p2p-advertisement-id.md) +- [**WDI\_TLV\_P2P\_ASP2\_ADVERTISED\_SERVICE\_ENTRY**](wdi-tlv-p2p-asp2-advertised-service-entry.md) +- [**WDI\_TLV\_P2P\_ASP2\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY**](wdi-tlv-p2p-asp2-service-information-discovery-entry.md) +- [**WDI\_TLV\_P2P\_ATTRIBUTES**](wdi-tlv-p2p-attributes.md) +- [**WDI\_TLV\_P2P\_BACKGROUND\_DISCOVER\_MODE**](wdi-tlv-p2p-background-discover-mode.md) +- [**WDI\_TLV\_P2P\_CAPABILITIES**](wdi-tlv-p2p-capabilities.md) +- [**WDI\_TLV\_P2P\_CHANNEL\_ENTRY\_LIST**](wdi-tlv-p2p-channel-entry-list.md) +- [**WDI\_TLV\_P2P\_CHANNEL\_INDICATE\_REASON**](wdi-tlv-p2p-channel-indicate-reason.md) +- [**WDI\_TLV\_P2P\_CHANNEL\_LIST\_ATTRIBUTE**](wdi-tlv-p2p-channel-list-attribute.md) +- [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](wdi-tlv-p2p-channel-number.md) +- [**WDI\_TLV\_P2P\_CONFIG\_METHODS**](wdi-tlv-p2p-config-methods.md) +- [**WDI\_TLV\_P2P\_DEVICE\_ADDRESS**](wdi-tlv-p2p-device-address.md) +- [**WDI\_TLV\_P2P\_DEVICE\_CAPABILITY**](wdi-tlv-p2p-device-capability.md) +- [**WDI\_TLV\_P2P\_DEVICE\_FILTER\_LIST**](wdi-tlv-p2p-device-filter-list.md) +- [**WDI\_TLV\_P2P\_DEVICE\_INFO**](wdi-tlv-p2p-device-info.md) +- [**WDI\_TLV\_P2P\_DEVICE\_INFO\_PARAMETERS**](wdi-tlv-p2p-device-info-parameters.md) +- [**WDI\_TLV\_P2P\_DEVICE\_NAME**](wdi-tlv-p2p-device-name.md) +- [**WDI\_TLV\_P2P\_DISCOVER\_MODE**](wdi-tlv-p2p-discover-mode.md) +- [**WDI\_TLV\_P2P\_DISCOVERED\_SERVICE\_ENTRY**](wdi-tlv-p2p-discovered-service-entry.md) +- [**WDI\_TLV\_P2P\_DISCOVERY\_CHANNEL\_SETTINGS**](wdi-tlv-p2p-discovery-channel-settings.md) +- [**WDI\_TLV\_P2P\_GO\_INTERNAL\_RESET\_POLICY**](wdi-tlv-p2p-go-internal-reset-policy.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_INFO**](wdi-tlv-p2p-go-negotiation-confirmation-info.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-confirmation-parameters.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_INFO**](wdi-tlv-p2p-go-negotiation-request-info.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-request-parameters.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_INFO**](wdi-tlv-p2p-go-negotiation-response-info.md) +- [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-response-parameters.md) +- [**WDI\_TLV\_P2P\_GROUP\_BSSID**](wdi-tlv-p2p-group-bssid.md) +- [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) +- [**WDI\_TLV\_P2P\_GROUP\_OWNER\_CAPABILITY**](wdi-tlv-p2p-group-owner-capability.md) +- [**WDI\_TLV\_P2P\_INCLUDE\_LISTEN\_CHANNEL**](wdi-tlv-p2p-include-listen-channel.md) +- [**WDI\_TLV\_P2P\_INCOMING\_FRAME\_INFORMATION**](wdi-tlv-p2p-incoming-frame-information.md) +- [**WDI\_TLV\_P2P\_INCOMING\_FRAME\_PARAMETERS**](wdi-tlv-p2p-incoming-frame-parameters.md) +- [**WDI\_TLV\_P2P\_INSTANCE\_NAME**](wdi-tlv-p2p-instance-name.md) +- [**WDI\_TLV\_P2P\_INSTANCE\_NAME\_HASH**](wdi-tlv-p2p-instance-name-hash.md) +- [**WDI\_TLV\_P2P\_INTERFACE\_ADDRESS\_LIST**](wdi-tlv-p2p-interface-address-list.md) +- [**WDI\_TLV\_P2P\_INVITATION\_REQUEST\_INFO**](wdi-tlv-p2p-invitation-request-info.md) +- [**WDI\_TLV\_P2P\_INVITATION\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-invitation-request-parameters.md) +- [**WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_INFO**](wdi-tlv-p2p-invitation-response-info.md) +- [**WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-invitation-response-parameters.md) +- [**WDI\_TLV\_P2P\_LISTEN\_CHANNEL**](wdi-tlv-p2p-listen-channel.md) +- [**WDI\_TLV\_P2P\_LISTEN\_DURATION**](wdi-tlv-p2p-listen-duration.md) +- [**WDI\_TLV\_P2P\_LISTEN\_STATE**](wdi-tlv-p2p-listen-state.md) +- [**WDI\_TLV\_P2P\_PERSISTENT\_GROUP\_ID**](wdi-tlv-p2p-persistent-group-id.md) +- [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_INFO**](wdi-tlv-p2p-provision-discovery-request-info.md) +- [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-provision-discovery-request-parameters.md) +- [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_INFO**](wdi-tlv-p2p-provision-discovery-response-info.md) +- [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-provision-discovery-response-parameters.md) +- [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) +- [**WDI\_TLV\_P2P\_RESPONSE\_FRAME\_PARAMETERS**](wdi-tlv-p2p-response-frame-parameters.md) +- [**WDI\_TLV\_P2P\_SECONDARY\_DEVICE\_TYPE\_LIST**](wdi-tlv-p2p-secondary-device-type-list.md) +- [**WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT**](wdi-tlv-p2p-send-action-frame-result.md) +- [**WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT\_PARAMETERS**](wdi-tlv-p2p-send-action-frame-result-parameters.md) +- [**WDI\_TLV\_P2P\_SEND\_ACTION\_REQUEST\_FRAME\_PARAMETERS**](wdi-tlv-p2p-send-action-request-frame-parameters.md) +- [**WDI\_TLV\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_RESULT**](wdi-tlv-p2p-send-request-action-frame-result.md) +- [**WDI\_TLV\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_RESULT**](wdi-tlv-p2p-send-response-action-frame-result.md) +- [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) +- [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY**](wdi-tlv-p2p-service-information-discovery-entry.md) +- [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_ENTRY**](wdi-tlv-p2p-service-information-entry.md) +- [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) +- [**WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH**](wdi-tlv-p2p-service-name-hash.md) +- [**WDI\_TLV\_P2P\_SERVICE\_SESSION\_INFO**](wdi-tlv-p2p-service-session-info.md) +- [**WDI\_TLV\_P2P\_SERVICE\_STATUS**](wdi-tlv-p2p-service-status.md) +- [**WDI\_TLV\_P2P\_SERVICE\_TRANSACTION\_ID**](wdi-tlv-p2p-service-transaction-id.md) +- [**WDI\_TLV\_P2P\_SERVICE\_TYPE**](wdi-tlv-p2p-service-type.md) +- [**WDI\_TLV\_P2P\_SERVICE\_TYPE\_HASH**](wdi-tlv-p2p-service-type-hash.md) +- [**WDI\_TLV\_P2P\_SERVICE\_UPDATE\_INDICATOR**](wdi-tlv-p2p-service-update-indicator.md) +- [**WDI\_TLV\_P2P\_WPS\_ENABLED**](wdi-tlv-p2p-wps-enabled.md) +- [**WDI\_TLV\_PACKET\_FILTER\_PARAMETERS**](wdi-tlv-packet-filter-parameters.md) +- [**WDI\_TLV\_PEER\_MAC\_ADDRESS**](wdi-tlv-peer-mac-address.md) +- [**WDI\_TLV\_PHY\_CAPABILITIES**](wdi-tlv-phy-capabilities.md) +- [**WDI\_TLV\_PHY\_DATA\_RATE\_LIST**](wdi-tlv-phy-data-rate-list.md) +- [**WDI\_TLV\_PHY\_INFO**](wdi-tlv-phy-info.md) +- [**WDI\_TLV\_PHY\_LIST**](wdi-tlv-phy-list.md) +- [**WDI\_TLV\_PHY\_STATISTICS**](wdi-tlv-phy-statistics.md) +- [**WDI\_TLV\_PHY\_SUPPORTED\_RX\_DATA\_RATES\_LIST**](wdi-tlv-phy-supported-rx-data-rates-list.md) +- [**WDI\_TLV\_PHY\_SUPPORTED\_TX\_DATA\_RATES\_LIST**](wdi-tlv-phy-supported-tx-data-rates-list.md) +- [**WDI\_TLV\_PHY\_TX\_POWER\_LEVEL\_LIST**](wdi-tlv-phy-tx-power-level-list.md) +- [**WDI\_TLV\_PHY\_TYPE**](wdi-tlv-phy-type.md) +- [**WDI\_TLV\_PHY\_TYPE\_LIST**](wdi-tlv-phy-type-list.md) +- [**WDI\_TLV\_PHY\_TYPE\_LIST (unused)**](wdi-tlv-phy-type-list--disabled.md) +- [**WDI\_TLV\_PLDR\_SUPPORT**](wdi-tlv-pldr-support.md) +- [**WDI\_TLV\_PM\_CAPABILITIES**](wdi-tlv-pm-capabilities.md) +- [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_80211RSN\_REKEY**](wdi-tlv-pm-protocol-offload-80211rsn-rekey.md) +- [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_GET**](wdi-tlv-pm-protocol-offload-get.md) +- [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv4ARP**](wdi-tlv-pm-protocol-offload-ipv4arp.md) +- [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv6NS**](wdi-tlv-pm-protocol-offload-ipv6ns.md) +- [**WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_REMOVE**](wdi-tlv-pm-protocol-offload-remove.md) +- [**WDI\_TLV\_PMKID**](wdi-tlv-pmkid.md) +- [**WDI\_TLV\_PORT\_ATTRIBUTES**](wdi-tlv-port-attributes.md) +- [**WDI\_TLV\_POWER\_MANAGMENT\_CAPABILITIES**](wdi-tlv-power-managment-capabilities.md) +- [**WDI\_TLV\_POWER\_STATE**](wdi-tlv-power-state.md) +- [**WDI\_TLV\_PRIVACY\_EXEMPTION\_ENTRY**](wdi-tlv-privacy-exemption-entry.md) +- [**WDI\_TLV\_PROBE\_RESPONSE\_FRAME**](wdi-tlv-probe-response-frame.md) +- [**WDI\_TLV\_RADIO\_STATE**](wdi-tlv-radio-state.md) +- [**WDI\_TLV\_RADIO\_STATE\_PARAMETERS**](wdi-tlv-radio-state-parameters.md) +- [**WDI\_TLV\_RECEIVE\_COALESCE\_OFFLOAD\_CAPABILITIES**](wdi-tlv-receive-coalesce-offload-capabilities.md) +- [**WDI\_TLV\_RECEIVE\_COALESCING\_CAPABILITIES**](wdi-tlv-receive-coalescing-capabilities.md) +- [**WDI\_TLV\_RECEIVE\_COALESCING\_CONFIG**](wdi-tlv-receive-coalescing-config.md) +- [**WDI\_TLV\_RECEIVE\_FILTER\_FIELD**](wdi-tlv-receive-filter-field.md) +- [**WDI\_TLV\_ROAMING\_NEEDED\_PARAMETERS**](wdi-tlv-roaming-needed-parameters.md) +- [**WDI\_TLV\_SAFE\_MODE\_PARAMETERS**](wdi-tlv-safe-mode-parameters.md) +- [**WDI\_TLV\_SCAN\_DWELL\_TIME**](wdi-tlv-scan-dwell-time.md) +- [**WDI\_TLV\_SCAN\_MODE**](wdi-tlv-scan-mode.md) +- [**WDI\_TLV\_SEND\_ACTION\_FRAME\_REQUEST\_PARAMETERS**](wdi-tlv-send-action-frame-request-parameters.md) +- [**WDI\_TLV\_SEND\_ACTION\_FRAME\_RESPONSE\_PARAMETERS**](wdi-tlv-send-action-frame-response-parameters.md) +- [**WDI\_TLV\_SET\_AUTO\_POWER\_SAVE**](wdi-tlv-set-auto-power-save.md) +- [**WDI\_TLV\_SET\_CIPHER\_KEY\_INFO**](wdi-tlv-set-cipher-key-info.md) +- [**WDI\_TLV\_SET\_CLEAR\_RECEIVE\_COALESCING**](wdi-tlv-set-clear-receive-coalescing.md) +- [**WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V4\_PARAMETERS**](wdi-tlv-set-encapsulation-offload-v4-parameters.md) +- [**WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V6\_PARAMETERS**](wdi-tlv-set-encapsulation-offload-v6-parameters.md) +- [**WDI\_TLV\_SET\_POWER\_DX\_REASON**](wdi-tlv-set-power-dx-reason.md) +- [**WDI\_TLV\_SET\_RECEIVE\_COALESCING**](wdi-tlv-set-receive-coalescing.md) +- [**WDI\_TLV\_SSID**](wdi-tlv-ssid.md) +- [**WDI\_TLV\_SSID\_LIST**](wdi-tlv-ssid-list.md) +- [**WDI\_TLV\_SSID\_OFFLOAD**](wdi-tlv-ssid-offload.md) +- [**WDI\_TLV\_START\_AP\_PARAMETERS**](wdi-tlv-start-ap-parameters.md) +- [**WDI\_TLV\_STATION\_ATTRIBUTES**](wdi-tlv-station-attributes.md) +- [**WDI\_TLV\_STATION\_CAPABILITIES**](wdi-tlv-station-capabilities.md) +- [**WDI\_TLV\_STATUS**](wdi-tlv-status.md) +- [**WDI\_TLV\_SUPPORTED\_GUIDS**](wdi-tlv-supported-guids.md) +- [**WDI\_TLV\_TCP\_OFFLOAD\_CAPABILITIES**](wdi-tlv-tcp-offload-capabilities.md) +- [**WDI\_TLV\_TCP\_RSC\_STATISTICS\_PARAMETERS**](wdi-tlv-tcp-rsc-statistics-parameters.md) +- [**WDI\_TLV\_TCP\_SET\_OFFLOAD\_PARAMETERS**](wdi-tlv-tcp-set-offload-parameters.md) +- [**WDI\_TLV\_TKIP\_MIC\_FAILURE\_INFO**](wdi-tlv-tkip-mic-failure-info.md) +- [**WDI\_TLV\_UNICAST\_ALGORITHM\_LIST**](wdi-tlv-unicast-algorithm-list.md) +- [**WDI\_TLV\_UNICAST\_CIPHER\_ALGO\_LIST**](wdi-tlv-unicast-cipher-algo-list.md) +- [**WDI\_TLV\_UNREACHABLE\_DETECTION\_THRESHOLD**](wdi-tlv-unreachable-detection-threshold.md) +- [**WDI\_TLV\_VENDOR\_SPECIFIC\_IE**](wdi-tlv-vendor-specific-ie.md) +- [**WDI\_TLV\_VIRTUALIZATION\_ATTRIBUTES**](wdi-tlv-virtualization-attributes.md) +- [**WDI\_TLV\_VIRTUALIZATION\_CAPABILITIES**](wdi-tlv-virtualization-capabilities.md) +- [**WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN**](wdi-tlv-wake-packet-bitmap-pattern.md) +- [**WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN\_ID**](wdi-tlv-wake-packet-bitmap-pattern-id.md) +- [**WDI\_TLV\_WAKE\_PACKET\_EAPOL\_REQUEST\_ID\_MESSAGE**](wdi-tlv-wake-packet-eapol-request-id-message.md) +- [**WDI\_TLV\_WAKE\_PACKET\_IPv4\_TCP\_SYNC**](wdi-tlv-wake-packet-ipv4-tcp-sync.md) +- [**WDI\_TLV\_WAKE\_PACKET\_IPv6\_TCP\_SYNC**](wdi-tlv-wake-packet-ipv6-tcp-sync.md) +- [**WDI\_TLV\_WAKE\_PACKET\_MAGIC\_PACKET**](wdi-tlv-wake-packet-magic-packet.md) +- [**WDI\_TLV\_WAKE\_PACKET\_PATTERN\_REMOVE**](wdi-tlv-wake-packet-pattern-remove.md) +- [**WDI\_TLV\_WFD\_ASSOCIATION\_STATUS**](wdi-tlv-wfd-association-status.md) + +## Related topics +[WDI message structure](https://msdn.microsoft.com/library/windows/hardware/mt269163) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI%20Miniport%20Driver%20TLVs%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-ndis-interface-restrictions.md b/windows-driver-docs-pr/network/wdi-ndis-interface-restrictions.md index 369eb4d895..0df878a1db 100644 --- a/windows-driver-docs-pr/network/wdi-ndis-interface-restrictions.md +++ b/windows-driver-docs-pr/network/wdi-ndis-interface-restrictions.md @@ -16,38 +16,13 @@ The WDI IHV miniport driver has access to all of the functionality provided by N The WDI IHV miniport driver needs to be aware of the following restrictions on NDIS interfaces. -Function -[**NdisMRegisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563654) -**Restrictions:** -Disallowed -*Alternative:* -[**NdisMRegisterWdiMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/mt297596) -[**NdisMDeregisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563578) -**Restrictions:** -Disallowed -*Alternative:* -[**NdisMDeregisterWdiMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/mt297595) -[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) -**Restrictions:** -Disallowed with **MiniportAttributes** types: -[**NDIS\_MINIPORT\_ADAPTER\_REGISTRATION\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565934) -[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923) -[**NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565926) -*Alternative:* -None. These are queried using WDI commands. -[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) -**Restrictions:** -Disallowed -*Alternative:* -The WDI data path receive handler to indicate received packets. -[**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) -**Restrictions:** -Disallowed -*Alternative:* -The WDI data path send handler to complete sent packets. -  - -  +Function | Restrictions | Alternative +---|---|--- +[**NdisMRegisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563654) | Disallowed | [**NdisMRegisterWdiMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/mt297596) +[**NdisMDeregisterMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/ff563578) | Disallowed | [**NdisMDeregisterWdiMiniportDriver**](https://msdn.microsoft.com/library/windows/hardware/mt297595) +[**NdisMSetMiniportAttributes**](https://msdn.microsoft.com/library/windows/hardware/ff563672) | Disallowed with **MiniportAttributes** types:
[**NDIS\_MINIPORT\_ADAPTER\_REGISTRATION\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565934)
[**NDIS\_MINIPORT\_ADAPTER\_GENERAL\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565923)
[**NDIS\_MINIPORT\_ADAPTER\_NATIVE\_802\_11\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/hardware/ff565926) | None. These are queried using WDI commands. +[**NdisMIndicateReceiveNetBufferLists**](https://msdn.microsoft.com/library/windows/hardware/ff563598) | Disallowed | The WDI data path receive handler to indicate received packets. +[**NdisMSendNetBufferListsComplete**](https://msdn.microsoft.com/library/windows/hardware/ff563668) | Disallowed | The WDI data path send handler to complete sent packets.   diff --git a/windows-driver-docs-pr/network/wdi-receive-operations-and-offloads.md b/windows-driver-docs-pr/network/wdi-receive-operations-and-offloads.md index a3aebe6b40..62ad417902 100644 --- a/windows-driver-docs-pr/network/wdi-receive-operations-and-offloads.md +++ b/windows-driver-docs-pr/network/wdi-receive-operations-and-offloads.md @@ -62,9 +62,9 @@ The following is a list of RX operations and offloads.

Rx decap

-

Replace the 802.3 header with a generic 802.11 header.

+

Replace non-initial A-MSDU subframe headers with 802.11 headers, using the 802.11 header fields from the initial A-MSDU subframe as appropriate.

Target/TAL

-

During A-MSDU deaggregation, the non-initial MSDUs of the A-MSDU need their 802.3 header replaced by a generic 802.11 header.

+

During A-MSDU deaggregation, the non-initial MSDUs of the A-MSDU need their 802.3 header replaced by a generic 802.11 header. WDI always expects 802.11 headers.

Rx reordering logic

@@ -126,10 +126,9 @@ The following is a list of RX operations and offloads.

Higher-level protocol (task) offloads

-

Checksum, LRO.

+

Checksum

Checksum: Configurable offload at boot-up if required.

-

Checksum: The target passes its checksum offload capabilities as part of device caps to WFCD during bring-up. For information about capabilities, see [NDIS_TCP_IP_ CHECKSUM_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/ff567878).

-

LRO: WFCD handles LRO transparently from the TAL/Target if applicable.

+

Checksum: The target passes its checksum offload capabilities as part of device caps to WDI during bring-up. For information about capabilities, see [NDIS_TCP_IP_ CHECKSUM_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/ff567878).

diff --git a/windows-driver-docs-pr/network/wdi-tlv-access-network-type.md b/windows-driver-docs-pr/network/wdi-tlv-access-network-type.md new file mode 100644 index 0000000000..1ca6391042 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-access-network-type.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ACCESS_NETWORK_TYPE +author: windows-driver-content +description: WDI_TLV_ACCESS_NETWORK_TYPE is a TLV that contains an Access Network Type. +ms.assetid: AE344FDB-3B87-4F4E-BFF5-4569918E8465 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ACCESS_NETWORK_TYPE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ACCESS\_NETWORK\_TYPE + + +WDI\_TLV\_ACCESS\_NETWORK\_TYPE is a TLV that contains an Access Network Type. + +## TLV Type + + +0x100 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|------------------------------------------------------------------------------------------| +| UINT8 | The Access Network Type to be used in probe requests for the network being connected to. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ACCESS_NETWORK_TYPE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-action-frame-body.md b/windows-driver-docs-pr/network/wdi-tlv-action-frame-body.md new file mode 100644 index 0000000000..f3d5ecebe6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-action-frame-body.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ACTION_FRAME_BODY +author: windows-driver-content +description: WDI_TLV_ACTION_FRAME_BODY is a TLV that contains the body of an Action Frame. +ms.assetid: 272782A9-F92E-4F32-A92B-B18EBE7C1803 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ACTION_FRAME_BODY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ACTION\_FRAME\_BODY + + +WDI\_TLV\_ACTION\_FRAME\_BODY is a TLV that contains the body of an Action Frame. + +## TLV Type + + +0xBE + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-----------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the body of an Action Frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ACTION_FRAME_BODY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-action-frame-device-context.md b/windows-driver-docs-pr/network/wdi-tlv-action-frame-device-context.md new file mode 100644 index 0000000000..7ee1ba945c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-action-frame-device-context.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ACTION_FRAME_DEVICE_CONTEXT +author: windows-driver-content +description: WDI_TLV_ACTION_FRAME_DEVICE_CONTEXT is a TLV that contains an Action Frame device context. +ms.assetid: D8AF374A-0AD0-4856-B05C-B8E3A3F1572B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ACTION_FRAME_DEVICE_CONTEXT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ACTION\_FRAME\_DEVICE\_CONTEXT + + +WDI\_TLV\_ACTION\_FRAME\_DEVICE\_CONTEXT is a TLV that contains an Action Frame device context. + +## TLV Type + + +0xAC + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains an Action Frame device context. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ACTION_FRAME_DEVICE_CONTEXT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-adapter-nlo-scan-mode.md b/windows-driver-docs-pr/network/wdi-tlv-adapter-nlo-scan-mode.md new file mode 100644 index 0000000000..f7f838a56c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-adapter-nlo-scan-mode.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ADAPTER_NLO_SCAN_MODE +author: windows-driver-content +description: WDI_TLV_ADAPTER_NLO_SCAN_MODE is a TLV that indicates whether scans should be performed in active or passive mode. +ms.assetid: 4294AF4D-587E-4978-9C54-E11D7368FBB8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADAPTER_NLO_SCAN_MODE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADAPTER\_NLO\_SCAN\_MODE + + +WDI\_TLV\_ADAPTER\_NLO\_SCAN\_MODE is a TLV that indicates whether scans should be performed in active or passive mode. + +## TLV Type + + +0x125 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | [**WDI\_SCAN\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926115) value that indicates whether scans should be performed in active or passive mode. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADAPTER_NLO_SCAN_MODE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-adapter-resume-required.md b/windows-driver-docs-pr/network/wdi-tlv-adapter-resume-required.md new file mode 100644 index 0000000000..18bb311eb5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-adapter-resume-required.md @@ -0,0 +1,87 @@ +--- +title: WDI_TLV_ADAPTER_RESUME_REQUIRED +author: windows-driver-content +description: WDI_TLV_ADAPTER_RESUME_REQUIRED is a TLV that specifies if adapter resume is required. +ms.assetid: 341B871A-F789-447E-A74C-3274B6B8B14A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADAPTER_RESUME_REQUIRED Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADAPTER\_RESUME\_REQUIRED + + +WDI\_TLV\_ADAPTER\_RESUME\_REQUIRED is a TLV that specifies if adapter resume is required. + +## TLV Type + + +0xB7 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT8Specifies if adapter resume is required. +

Valid values are 0 (not required) and 1 (required). If set to 1, the firmware requires OS assistance to resume its context.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADAPTER_RESUME_REQUIRED%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-additional-beacon-ies.md b/windows-driver-docs-pr/network/wdi-tlv-additional-beacon-ies.md new file mode 100644 index 0000000000..b21befab9e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-additional-beacon-ies.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ADDITIONAL_BEACON_IES +author: windows-driver-content +description: WDI_TLV_ADDITIONAL_BEACON_IES is a TLV that contains additional beacon IEs. +ms.assetid: 7B4D863A-1480-4283-A5E9-5F4F043B0CDE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADDITIONAL_BEACON_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADDITIONAL\_BEACON\_IES + + +WDI\_TLV\_ADDITIONAL\_BEACON\_IES is a TLV that contains additional beacon IEs. + +## TLV Type + + +0x98 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | The array of beacon IEs. The Wi-Fi Direct port must add these additional IEs to the beacon packets when it is acting as a Group Owner. These are ignored when the Wi-Fi Direct port is operating in device or client mode. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADDITIONAL_BEACON_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-additional-ies.md b/windows-driver-docs-pr/network/wdi-tlv-additional-ies.md new file mode 100644 index 0000000000..0692048ada --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-additional-ies.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_ADDITIONAL_IES +author: windows-driver-content +description: WDI_TLV_ADDITIONAL_IES is a TLV that contains additional Information Element (IE) settings. +ms.assetid: B9094E9D-894F-4B23-B4DA-126F87E908C9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADDITIONAL_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADDITIONAL\_IES + + +WDI\_TLV\_ADDITIONAL\_IES is a TLV that contains additional Information Element (IE) settings. + +## TLV Type + + +0x8A + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_ADDITIONAL\_BEACON\_IES**](wdi-tlv-additional-beacon-ies.md) | | X | An array of beacon IEs. The Wi-Fi Direct port must add these additional IEs to the beacon packets when it is acting as a Group Owner. This is ignored when the Wi-Fi Direct port is operating in device or client mode. | +| [**WDI\_TLV\_ADDITIONAL\_PROBE\_RESPONSE\_IES**](wdi-tlv-additional-probe-response-ies.md) | | X | An array of probe response IEs. The Wi-Fi Direct port must add these additional IEs to the probe response packets when it is acting as a Wi-Fi Direct device or Group Owner. This is ignored when the Wi-Fi Direct port is operating in client mode. | +| [**WDI\_TLV\_ADDITIONAL\_PROBE\_REQUEST\_DEFAULT\_IES**](wdi-tlv-additional-probe-request-default-ies.md) | | X | An array of additional probe request IEs. This offset is relative to the start of the buffer that contains this structure. The Wi-Fi Direct port must add these additional IEs to the probe request packets that it transmits. Note that a Wi-Fi Direct discover request may override the default probe request IEs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADDITIONAL_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-additional-probe-request-default-ies.md b/windows-driver-docs-pr/network/wdi-tlv-additional-probe-request-default-ies.md new file mode 100644 index 0000000000..1721224e38 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-additional-probe-request-default-ies.md @@ -0,0 +1,92 @@ +--- +title: WDI_TLV_ADDITIONAL_PROBE_REQUEST_DEFAULT_IES +author: windows-driver-content +description: WDI_TLV_ADDITIONAL_PROBE_REQUEST_DEFAULT_IES is a TLV that contains additional probe request IEs. +ms.assetid: E364B1BC-5A78-42C8-B04D-31BD21141477 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADDITIONAL_PROBE_REQUEST_DEFAULT_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADDITIONAL\_PROBE\_REQUEST\_DEFAULT\_IES + + +WDI\_TLV\_ADDITIONAL\_PROBE\_REQUEST\_DEFAULT\_IES is a TLV that contains additional probe request IEs. + +## TLV Type + + +0x70 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT8[]An array of probe request IEs. The Wi-Fi Direct port must add these additional IEs to transmitted probe request packets. +
+Note  A Wi-Fi Direct Discover Request may override the default probe request IEs. +
+
+  +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADDITIONAL_PROBE_REQUEST_DEFAULT_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-additional-probe-response-ies.md b/windows-driver-docs-pr/network/wdi-tlv-additional-probe-response-ies.md new file mode 100644 index 0000000000..705f9d6747 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-additional-probe-response-ies.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ADDITIONAL_PROBE_RESPONSE_IES +author: windows-driver-content +description: WDI_TLV_ADDITIONAL_PROBE_RESPONSE_IES is a TLV that contains probe response IEs. +ms.assetid: BDEDAD4D-A35B-4AE9-BC90-184CD75002B2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ADDITIONAL_PROBE_RESPONSE_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ADDITIONAL\_PROBE\_RESPONSE\_IES + + +WDI\_TLV\_ADDITIONAL\_PROBE\_RESPONSE\_IES is a TLV that contains probe response IEs. + +## TLV Type + + +0x93 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | The array of probe response IEs. The Wi-Fi Direct port must add these additional IEs to the probe response packets when it is acting as a Wi-Fi Direct device or Group Owner. This member is ignored when the Wi-Fi Direct port is operating in client mode. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ADDITIONAL_PROBE_RESPONSE_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-allowed-bssids-list.md b/windows-driver-docs-pr/network/wdi-tlv-allowed-bssids-list.md new file mode 100644 index 0000000000..7953c02a8d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-allowed-bssids-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ALLOWED_BSSIDS_LIST +author: windows-driver-content +description: WDI_TLV_ALLOWED_BSSIDS_LIST is a TLV that contains a list of BSSIDs that are allowed to be used for association. +ms.assetid: A53C5EB2-1D77-4380-86C7-291D2BF4FCFC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ALLOWED_BSSIDS_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ALLOWED\_BSSIDS\_LIST + + +WDI\_TLV\_ALLOWED\_BSSIDS\_LIST is a TLV that contains a list of BSSIDs that are allowed to be used for association. + +## TLV Type + + +0xC2 + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|---------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | A list of BSSIDs that are allowed to be used for association. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ALLOWED_BSSIDS_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-anqp-elements.md b/windows-driver-docs-pr/network/wdi-tlv-anqp-elements.md new file mode 100644 index 0000000000..c8d02929d8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-anqp-elements.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_ANQP_ELEMENTS +author: windows-driver-content +description: WDI_TLV_ANQP_ELEMENTS is an unused TLV. +ms.assetid: 84B0987B-9CF1-432D-A290-1BC75BCAEFED +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ANQP_ELEMENTS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ANQP\_ELEMENTS + + +WDI\_TLV\_ANQP\_ELEMENTS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ANQP_ELEMENTS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-anqp-query-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-anqp-query-parameters.md new file mode 100644 index 0000000000..59dd250236 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-anqp-query-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_ANQP_QUERY_PARAMETERS +author: windows-driver-content +description: WDI_TLV_ANQP_QUERY_PARAMETERS is an unused TLV. +ms.assetid: 9A6C4033-ABE7-439D-B745-0E1E413D9318 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ANQP_QUERY_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ANQP\_QUERY\_PARAMETERS + + +WDI\_TLV\_ANQP\_QUERY\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ANQP_QUERY_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-anqp-query-status.md b/windows-driver-docs-pr/network/wdi-tlv-anqp-query-status.md new file mode 100644 index 0000000000..111304c865 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-anqp-query-status.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_ANQP_QUERY_STATUS +author: windows-driver-content +description: WDI_TLV_ANQP_QUERY_STATUS is an unused TLV. +ms.assetid: C1843AC2-C12E-4F11-B36C-66D75CAA12CD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ANQP_QUERY_STATUS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ANQP\_QUERY\_STATUS + + +WDI\_TLV\_ANQP\_QUERY\_STATUS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ANQP_QUERY_STATUS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ap-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-ap-attributes.md new file mode 100644 index 0000000000..ed213ddaf7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ap-attributes.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_AP_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_AP_ATTRIBUTES is a TLV that contains the attributes of an access point. +ms.assetid: FD6F635C-85FF-4668-AA17-12677A61F84D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_AP_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_AP\_ATTRIBUTES + + +WDI\_TLV\_AP\_ATTRIBUTES is a TLV that contains the attributes of an access point. + +## TLV Type + + +0x23 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------| +| [**WDI\_TLV\_AP\_CAPABILITIES**](wdi-tlv-ap-capabilities.md) | | | The access point capabilities. | +| [**WDI\_TLV\_UNICAST\_ALGORITHM\_LIST**](wdi-tlv-unicast-algorithm-list.md) | | | The supported unicast algorithms. | +| [**WDI\_TLV\_MULTICAST\_DATA\_ALGORITHM\_LIST**](wdi-tlv-multicast-data-algorithm-list.md) | | | The supported multicast data algorithms. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_AP_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ap-band-channel.md b/windows-driver-docs-pr/network/wdi-tlv-ap-band-channel.md new file mode 100644 index 0000000000..8c84d303fa --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ap-band-channel.md @@ -0,0 +1,81 @@ +--- +title: WDI_TLV_AP_BAND_CHANNEL +author: windows-driver-content +description: WDI_TLV_AP_BAND_CHANNEL is a TLV that specifies access point band and channel information. +ms.assetid: 5659CFA1-7FA9-490D-83DE-A56A895602A0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_AP_BAND_CHANNEL Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_AP\_BAND\_CHANNEL + + +WDI\_TLV\_AP\_BAND\_CHANNEL is a TLV that specifies access point band and channel information. + +**Note**  This TLV was added in Windows 10, version 1511, WDI version 1.0.10. + +  + +## TLV Type + + +0x127 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------| +| [**WDI\_TLV\_BANDID**](wdi-tlv-bandid.md) | | | Specifies the identifier for the band. | +| [**WDI\_TLV\_CHANNEL\_INFO\_LIST**](wdi-tlv-channel-info-list.md) | | X | Specifies a list of channels to start the access point on. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_TASK\_START\_AP](https://msdn.microsoft.com/library/windows/hardware/dn925964) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_AP_BAND_CHANNEL%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ap-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-ap-capabilities.md new file mode 100644 index 0000000000..880fd10972 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ap-capabilities.md @@ -0,0 +1,115 @@ +--- +title: WDI_TLV_AP_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_AP_CAPABILITIES is a TLV that contains the capabilities of an access point. +ms.assetid: 2DE866C8-9414-46D8-A156-3A35F1E325EF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_AP_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_AP\_CAPABILITIES + + +WDI\_TLV\_AP\_CAPABILITIES is a TLV that contains the capabilities of an access point. + +## TLV Type + + +0x16 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32The scan SSID list size.
UINT32The desired SSID list size.
UINT32The privacy exemption list size.
UINT32The association table size.
UINT32The key mapping table size.
UINT32The default key table size.
UINT32The maximum length of the WEP key value.
UINT8Specifies whether the AP supports radar detection. +

Valid values are 0 (not supported) and 1 (supported).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_AP_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-parameters-requested-type.md b/windows-driver-docs-pr/network/wdi-tlv-association-parameters-requested-type.md new file mode 100644 index 0000000000..5df1149dbd --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-parameters-requested-type.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ASSOCIATION_PARAMETERS_REQUESTED_TYPE +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_PARAMETERS_REQUESTED_TYPE is a TLV that contains the requested Association Parameter TLV types. +ms.assetid: BF4FE327-56A6-4EEE-B6C2-9B93D5C1DD47 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_PARAMETERS_REQUESTED_TYPE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_PARAMETERS\_REQUESTED\_TYPE + + +WDI\_TLV\_ASSOCIATION\_PARAMETERS\_REQUESTED\_TYPE is a TLV that contains the requested Association Parameter TLV types. + +## TLV Type + + +0xBB + +## Length + + +The size (in bytes) of the array of UINT16 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT16\[\] | The list of Association Parameters TLV types that are requested. Valid TLV types are [**WDI\_TLV\_PMKID**](wdi-tlv-pmkid.md) (0x9F) and [**WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES**](wdi-tlv-extra-association-request-ies.md) (0x40). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_PARAMETERS_REQUESTED_TYPE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-request-device-context.md b/windows-driver-docs-pr/network/wdi-tlv-association-request-device-context.md new file mode 100644 index 0000000000..3aa35599ef --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-request-device-context.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ASSOCIATION_REQUEST_DEVICE_CONTEXT +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_REQUEST_DEVICE_CONTEXT is a TLV that contains vendor-specific information that is passed down to the port if the host decides to send a response to a incoming association request. +ms.assetid: 5C684769-77A0-446D-81F6-A90E54806A1F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_REQUEST_DEVICE_CONTEXT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_REQUEST\_DEVICE\_CONTEXT + + +WDI\_TLV\_ASSOCIATION\_REQUEST\_DEVICE\_CONTEXT is a TLV that contains vendor-specific information that is passed down to the port if the host decides to send a response to a incoming association request. + +## TLV Type + + +0x72 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | Vendor-specific information that is passed down to the port if the host decides to send a response to a incoming association request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_REQUEST_DEVICE_CONTEXT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-request-frame.md b/windows-driver-docs-pr/network/wdi-tlv-association-request-frame.md new file mode 100644 index 0000000000..aee06fc32c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-request-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ASSOCIATION_REQUEST_FRAME +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_REQUEST_FRAME is a TLV that contains the association request that was used for the association. +ms.assetid: C2323DFE-2B13-4E35-BF9B-4A0B5F3B2076 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_REQUEST_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_REQUEST\_FRAME + + +WDI\_TLV\_ASSOCIATION\_REQUEST\_FRAME is a TLV that contains the association request that was used for the association. + +## TLV Type + + +0x2E + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the association request that was used for the association. This does not include the 802.11 MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_REQUEST_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-request-ies.md b/windows-driver-docs-pr/network/wdi-tlv-association-request-ies.md new file mode 100644 index 0000000000..c78cdf2405 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-request-ies.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_ASSOCIATION_REQUEST_IES +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_REQUEST_IES is an unused TLV. +ms.assetid: 7D057406-7017-46F8-80DD-857F38AFF5D5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_REQUEST_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_REQUEST\_IES + + +WDI\_TLV\_ASSOCIATION\_REQUEST\_IES is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_REQUEST_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-response-frame.md b/windows-driver-docs-pr/network/wdi-tlv-association-response-frame.md new file mode 100644 index 0000000000..f7384f7a8c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-response-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ASSOCIATION_RESPONSE_FRAME +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESPONSE_FRAME is a TLV that contains the received association response. +ms.assetid: FA71F8CA-BA22-4EF2-8DF4-2A08C83A54A7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESPONSE_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME + + +WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME is a TLV that contains the received association response. + +## TLV Type + + +0x2F + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the received association response. This does not include the 802.11 MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESPONSE_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-response-ies.md b/windows-driver-docs-pr/network/wdi-tlv-association-response-ies.md new file mode 100644 index 0000000000..506a862591 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-response-ies.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_ASSOCIATION_RESPONSE_IES +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESPONSE_IES is an unused TLV. +ms.assetid: 3882FFB2-D77B-4433-BFD2-F55A91C58985 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESPONSE_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESPONSE\_IES + + +WDI\_TLV\_ASSOCIATION\_RESPONSE\_IES is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESPONSE_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-association-response-parameters.md new file mode 100644 index 0000000000..c0016b125f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-response-parameters.md @@ -0,0 +1,91 @@ +--- +title: WDI_TLV_ASSOCIATION_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESPONSE_PARAMETERS is a TLV that contains association response parameters for OID_WDI_TASK_SEND_AP_ASSOCIATION_RESPONSE. +ms.assetid: FB116762-2064-48FA-B630-D5AE54657D10 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_ASSOCIATION\_RESPONSE\_PARAMETERS is a TLV that contains association response parameters for [OID\_WDI\_TASK\_SEND\_AP\_ASSOCIATION\_RESPONSE](https://msdn.microsoft.com/library/windows/hardware/dn925960). + +## TLV Type + + +0x97 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + +
TypeDescription
UINT8Specifies whether or not to accept the association request. +

Valid values are 0 (do not accept) and 1 (accept).

UINT16Specifies the reason code. If accept request is set to 0, this field provides a reason code to send back to the peer adapter.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-response-result-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-association-response-result-parameters.md new file mode 100644 index 0000000000..e505280081 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-response-result-parameters.md @@ -0,0 +1,108 @@ +--- +title: WDI_TLV_ASSOCIATION_RESPONSE_RESULT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESPONSE_RESULT_PARAMETERS is a TLV that contains association response result parameters. +ms.assetid: 8BF2C8B4-207E-479A-9903-3FCDEED5BA2C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESPONSE_RESULT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESPONSE\_RESULT\_PARAMETERS + + +WDI\_TLV\_ASSOCIATION\_RESPONSE\_RESULT\_PARAMETERS is a TLV that contains association response result parameters. + +## TLV Type + + +0x76 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
[WDI_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/dn926071)The MAC address of the peer adapter.
UINT8A bit value that indicates whether the request from the peer station is a reassociation request. +

Valid values are 0 and 1. A value of 1 indicates that it is a reassociation request.

UINT8A bit value that indicates whether the response from the peer station is a reassociation response. +

Valid values are 0 and 1. A value of 1 indicates that it is a reassociation response.

[WDI_AUTH_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/dn897792)The authentication algorithm for the association.
[WDI_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/dn897802)The unicast cipher algorithm for the association.
[WDI_CIPHER_ALGORITHM](https://msdn.microsoft.com/library/windows/hardware/dn897802)The multicast cipher algorithm for the association.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESPONSE_RESULT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-result-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-association-result-parameters.md new file mode 100644 index 0000000000..d89d3f000c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-result-parameters.md @@ -0,0 +1,84 @@ +--- +title: WDI_TLV_ASSOCIATION_RESULT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESULT_PARAMETERS is a TLV that contains parameters for an association result. +ms.assetid: A6F29084-EF36-43C4-B646-E071E755E110 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESULT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESULT\_PARAMETERS + + +WDI\_TLV\_ASSOCIATION\_RESULT\_PARAMETERS is a TLV that contains parameters for an association result. + +## TLV Type + + +0x2D + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the completion status of the association attempt as defined in [**WDI\_ASSOC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn897725). | +| UINT32 | The 802.11 status code sent by the peer in response to an authentication or association request from this port. | +| UINT8 | Specifies whether the port sent an 802.11 association or an 802.11 reassociation request to the AP. This value should be set to 1 if a reassociation request was used. | +| [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792) | The authentication algorithm that the port negotiated with the peer during association. | +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) | The unicast cipher algorithm that the port negotiated with the peer during association. | +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) | The multicast data cipher algorithm that the port negotiated with the peer during association. | +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) | The multicast management cipher algorithm that the port negotiated with the peer during association. | +| UINT8 | Specifies if the port has associated with a peer that supports distribution system (DS) services for ISO Layer 2 bridging on any station in the BSS network, including mobile stations and APs. This value should be set to 1 if this is supported. | +| UINT8 | Specifies whether the port has performed port authorization during the association operation. | +| UINT8 | Specifies whether 802.11 WMM QoS protocol has been negotiated for this association. This value should be set to 1 if it has been negotiated. | +| [**WDI\_DS\_INFO**](https://msdn.microsoft.com/library/windows/hardware/dn897813) | Specifies whether the port is connected to the same DS as its previous association. | +| UINT32 | When a (re)association fails with an 802.11 reason code of 30, this value indicates the value of the association comeback time requested by the peer. | +| WDI\_BAND\_ID (UINT32) | The band ID on which the association is established. | +| UINT32 | The IHV association status. If the association failed, this can contain an IHV-defined status code. This is only used for debugging purpose. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESULT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-association-result.md b/windows-driver-docs-pr/network/wdi-tlv-association-result.md new file mode 100644 index 0000000000..343fe6e48b --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-association-result.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_ASSOCIATION_RESULT +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESULT is a TLV that contains the results of an association. +ms.assetid: E0059A7A-0D20-403E-9A46-9633396A87C4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ASSOCIATION_RESULT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ASSOCIATION\_RESULT + + +WDI\_TLV\_ASSOCIATION\_RESULT is a TLV that contains the results of an association. + +## TLV Type + + +0x35 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](wdi-tlv-bssid.md) | | | The BSSID of the BSS. | +| [**WDI\_TLV\_ASSOCIATION\_RESULT\_PARAMETERS**](wdi-tlv-association-result-parameters.md) | | | The association result parameters. | +| [**WDI\_TLV\_ASSOCIATION\_REQUEST\_FRAME**](wdi-tlv-association-request-frame.md) | | X | The association request that was used for association. This does not include the 802.11 MAC header. | +| [**WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME**](wdi-tlv-association-response-frame.md) | | X | The association response that was received. This does not include the 802.11 MAC header. | +| [**WDI\_TLV\_AUTHENTICATION\_RESPONSE\_FRAME**](wdi-tlv-authentication-response-frame.md) | | X | The authentication response that was received with a failure code. This does not include the 802.11 MAC header. It should only be included if the connection attempt failed during authentication exchange. | +| [**WDI\_TLV\_BEACON\_PROBE\_RESPONSE**](wdi-tlv-beacon-probe-response.md) | | X | The latest beacon or probe response frame received by the port. This does not include the 802.11 MAC header. | +| [**WDI\_TLV\_ETHERTYPE\_ENCAP\_TABLE**](wdi-tlv-ethertype-encap-table.md) | | X | The Ethertype encapsulations for the association. | +| [**WDI\_TLV\_PHY\_TYPE\_LIST**](wdi-tlv-phy-type-list.md) | | X | The list of PHY identifiers that the 802.11 station uses to send or receive packets on the BSS network connection. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ASSOCIATION_RESULT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-auth-algo-list.md b/windows-driver-docs-pr/network/wdi-tlv-auth-algo-list.md new file mode 100644 index 0000000000..bb71cdbecc --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-auth-algo-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_AUTH_ALGO_LIST +author: windows-driver-content +description: WDI_TLV_AUTH_ALGO_LIST is a TLV that contains a list of authentication algorithms. +ms.assetid: 6F5EC21B-C923-45ED-B62E-302D916AABE5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_AUTH_ALGO_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_AUTH\_ALGO\_LIST + + +WDI\_TLV\_AUTH\_ALGO\_LIST is a TLV that contains a list of authentication algorithms. + +## TLV Type + + +0x3C + +## Length + + +The size (in bytes) of the array of [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792) structures. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-------------------------------------------------------------|----------------------------------------| +| [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792)\[\] | An array of authentication algorithms. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_AUTH_ALGO_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-authentication-response-frame.md b/windows-driver-docs-pr/network/wdi-tlv-authentication-response-frame.md new file mode 100644 index 0000000000..2c602e7145 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-authentication-response-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_AUTHENTICATION_RESPONSE_FRAME +author: windows-driver-content +description: WDI_TLV_ASSOCIATION_RESPONSE_FRAME is a TLV that contains an authentication response frame. +ms.assetid: 0BD8BDD9-7D51-413F-8740-FD49F71249B1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_AUTHENTICATION_RESPONSE_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_AUTHENTICATION\_RESPONSE\_FRAME + + +WDI\_TLV\_ASSOCIATION\_RESPONSE\_FRAME is a TLV that contains an authentication response frame. + +## TLV Type + + +0x124 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the authentication response that was received with a failure code. This does not include the 802.11 MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_AUTHENTICATION_RESPONSE_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-band-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-band-capabilities.md new file mode 100644 index 0000000000..eee6afa7a7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-band-capabilities.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_BAND_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_BAND_CAPABILITIES is a TLV that contains the capabilities of a band. +ms.assetid: ABD198FE-8E81-4AF3-BB3D-D78AEB75782F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BAND_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BAND\_CAPABILITIES + + +WDI\_TLV\_BAND\_CAPABILITIES is a TLV that contains the capabilities of a band. + +## TLV Type + + +0x1A + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------| +| UINT32 | The identifier for the band. | +| UINT8 | Specifies whether the band is enabled or not. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BAND_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-band-channel.md b/windows-driver-docs-pr/network/wdi-tlv-band-channel.md new file mode 100644 index 0000000000..bd26f9268e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-band-channel.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_BAND_CHANNEL +author: windows-driver-content +description: WDI_TLV_BAND_CHANNEL is a TLV that contains the channels to scan for a specified band. +ms.assetid: CC3142BE-45CC-4064-A203-ADAF5BE05C01 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BAND_CHANNEL Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BAND\_CHANNEL + + +WDI\_TLV\_BAND\_CHANNEL is a TLV that contains the channels to scan for a specified band. + +## TLV Type + + +0x2C + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BANDID**](wdi-tlv-bandid.md) | | | Specifies the identifier for the band. | +| [**WDI\_TLV\_CHANNEL\_INFO\_LIST**](wdi-tlv-channel-info-list.md) | | | Specifies a list of channels to scan. If the list is empty, the port must scan on all channels. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BAND_CHANNEL%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-band-id-list.md b/windows-driver-docs-pr/network/wdi-tlv-band-id-list.md new file mode 100644 index 0000000000..ee03476942 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-band-id-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BAND_ID_LIST +author: windows-driver-content +description: WDI_TLV_BAND_ID_LIST is a TLV that contains a list of band IDs. +ms.assetid: 415EF9E3-9441-420D-AC8A-0F819369E20E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BAND_ID_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BAND\_ID\_LIST + + +WDI\_TLV\_BAND\_ID\_LIST is a TLV that contains a list of band IDs. + +## TLV Type + + +0xB6 + +## Length + + +The size (in bytes) of the array of WDI\_BAND\_ID (UINT32) elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-------------------|-----------------------| +| WDI\_BAND\_ID\[\] | An array of band IDs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BAND_ID_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-band-info.md b/windows-driver-docs-pr/network/wdi-tlv-band-info.md new file mode 100644 index 0000000000..07bb88e8d4 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-band-info.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_BAND_INFO +author: windows-driver-content +description: WDI_TLV_BAND_INFO is a TLV that contains band information. +ms.assetid: 37F1CE39-5471-489A-8DA2-F058B631B31F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BAND_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BAND\_INFO + + +WDI\_TLV\_BAND\_INFO is a TLV that contains band information. + +## TLV Type + + +0x27 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------| +| [**WDI\_TLV\_BAND\_CAPABILITIES**](wdi-tlv-band-capabilities.md) | | | The capabilities of the band. | +| [**WDI\_TLV\_PHY\_TYPE\_LIST**](wdi-tlv-phy-type-list.md) | | | A list of valid PHY types in this band. | +| [**WDI\_TLV\_CHANNEL\_LIST**](wdi-tlv-channel-list.md) | | | A list of valid channel numbers in this band. | +| [**WDI\_TLV\_CHANNEL\_WIDTH\_LIST**](wdi-tlv-channel-width-list.md) | | | A list of channel widths in MHz | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BAND_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bandid.md b/windows-driver-docs-pr/network/wdi-tlv-bandid.md new file mode 100644 index 0000000000..5669123a7f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bandid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BANDID +author: windows-driver-content +description: WDI_TLV_BANDID is a TLV that contains a band ID. +ms.assetid: 1D0CBFED-C460-447B-BB03-CEAE57EE09F2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BANDID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BANDID + + +WDI\_TLV\_BANDID is a TLV that contains a band ID. + +## TLV Type + + +0x39 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|------------------------------| +| UINT32 | The identifier for the band. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BANDID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-beacon-frame.md b/windows-driver-docs-pr/network/wdi-tlv-beacon-frame.md new file mode 100644 index 0000000000..e452675c6a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-beacon-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BEACON_FRAME +author: windows-driver-content +description: WDI_TLV_BEACON_FRAME is a TLV that contains a beacon frame. +ms.assetid: 4022B721-B56E-482C-8F97-C4F7820CF6D1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BEACON_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BEACON\_FRAME + + +WDI\_TLV\_BEACON\_FRAME is a TLV that contains a beacon frame. + +## TLV Type + + +0xA + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the beacon frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BEACON_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-beacon-ies.md b/windows-driver-docs-pr/network/wdi-tlv-beacon-ies.md new file mode 100644 index 0000000000..b479c7014d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-beacon-ies.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BEACON_IES +author: windows-driver-content +description: WDI_TLV_BEACON_IES is a TLV that contains beacon IEs from an association. +ms.assetid: A3E70310-2130-4248-B730-2DEF41C25993 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BEACON_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BEACON\_IES + + +WDI\_TLV\_BEACON\_IES is a TLV that contains beacon IEs from an association. + +## TLV Type + + +0x78 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-------------------------------------| +| UINT8\[\] | The beacon IEs from an association. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BEACON_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-beacon-probe-response.md b/windows-driver-docs-pr/network/wdi-tlv-beacon-probe-response.md new file mode 100644 index 0000000000..9efe6d6655 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-beacon-probe-response.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BEACON_PROBE_RESPONSE +author: windows-driver-content +description: WDI_TLV_BEACON_PROBE_RESPONSE is a TLV that contains the latest beacon or probe response frame received by the port. +ms.assetid: D1148F9B-D25F-4AF0-8C55-43453441C667 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BEACON_PROBE_RESPONSE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BEACON\_PROBE\_RESPONSE + + +WDI\_TLV\_BEACON\_PROBE\_RESPONSE is a TLV that contains the latest beacon or probe response frame received by the port. + +## TLV Type + + +0x30 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the latest beacon or probe response frame received by the port. This does not include the 802.11 MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BEACON_PROBE_RESPONSE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-and-mask.md b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-and-mask.md new file mode 100644 index 0000000000..090ea96047 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-and-mask.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_BITMAP_PATTERN_AND_MASK +author: windows-driver-content +description: WDI_TLV_BITMAP_PATTERN_AND_MASK is an unused TLV. +ms.assetid: 665529FA-7BAF-4700-86EF-ADA7D8781423 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BITMAP_PATTERN_AND_MASK Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BITMAP\_PATTERN\_AND\_MASK + + +WDI\_TLV\_BITMAP\_PATTERN\_AND\_MASK is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BITMAP_PATTERN_AND_MASK%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-mask.md b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-mask.md new file mode 100644 index 0000000000..644c0ffa71 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern-mask.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BITMAP_PATTERN_MASK +author: windows-driver-content +description: WDI_TLV_BITMAP_PATTERN_MASK is a TLV that contains the bitmap pattern mask. +ms.assetid: 251B3496-04CE-419B-BE5E-C46265F50B7A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BITMAP_PATTERN_MASK Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BITMAP\_PATTERN\_MASK + + +WDI\_TLV\_BITMAP\_PATTERN\_MASK is a TLV that contains the bitmap pattern mask. + +## TLV Type + + +0xE4 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the byte array of the pattern mask. The mask must have 1 bit per pattern byte, therefore the mask length should equal (pattern length + 7) / 8. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BITMAP_PATTERN_MASK%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern.md b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern.md new file mode 100644 index 0000000000..331ec46376 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bitmap-pattern.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BITMAP_PATTERN +author: windows-driver-content +description: WDI_TLV_BITMAP_PATTERN is a TLV that contains the byte array of a pattern. +ms.assetid: 44A18754-3D04-4B62-B8C2-861A47129F08 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BITMAP_PATTERN Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BITMAP\_PATTERN + + +WDI\_TLV\_BITMAP\_PATTERN is a TLV that contains the byte array of a pattern. + +## TLV Type + + +0x68 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the byte array of the pattern. Length = (Pattern length + 7)/8. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BITMAP_PATTERN%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry-age-info.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-age-info.md new file mode 100644 index 0000000000..7ccfdce05b --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-age-info.md @@ -0,0 +1,91 @@ +--- +title: WDI_TLV_BSS_ENTRY_AGE_INFO +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY_AGE_INFO is a TLV that contains age information for a BSS entry. +ms.assetid: 3D0DC599-2A66-45E9-B02C-32291A028139 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY_AGE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY\_AGE\_INFO + + +WDI\_TLV\_BSS\_ENTRY\_AGE\_INFO is a TLV that contains age information for a BSS entry. + +## TLV Type + + +0xBA + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + +
TypeDescription
UINT64Timestamp of when this BSS entry was most recently discovered. The timestamp should be obtained with [NdisGetCurrentSystemTime](https://msdn.microsoft.com/library/windows/hardware/ff562629) or [KeQuerySystemTime](https://msdn.microsoft.com/library/windows/hardware/ff553068).
UINT8Specifies whether this information is live (found during a currently running scan) or is coming from the IHV component's BSS list cache. +

Valid values are 0 (live) or 1 (cached).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY_AGE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry-channel-info.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-channel-info.md new file mode 100644 index 0000000000..232ef4fef2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-channel-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_BSS_ENTRY_CHANNEL_INFO +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY_CHANNEL_INFO is a TLV that contains BSS entry channel information. +ms.assetid: 01DA2EDA-2BE2-4E4F-AE5D-8E07EEF691FE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY_CHANNEL_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO + + +WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO is a TLV that contains BSS entry channel information. + +## TLV Type + + +0x3A + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------|--------------------------------------------------------------| +| WDI\_CHANNEL\_NUMBER (UINT32) | The logical channel number on which the peer was discovered. | +| UINT32 | The band ID for the BSS entry. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY_CHANNEL_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry-device-context.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-device-context.md new file mode 100644 index 0000000000..db7281c286 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-device-context.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BSS_ENTRY_DEVICE_CONTEXT +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY_DEVICE_CONTEXT is a TLV that contains device context for the BSS entry. +ms.assetid: 5672294B-C6C0-43A3-9553-D6309F64F4A6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY_DEVICE_CONTEXT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY\_DEVICE\_CONTEXT + + +WDI\_TLV\_BSS\_ENTRY\_DEVICE\_CONTEXT is a TLV that contains device context for the BSS entry. + +## TLV Type + + +0xD + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the context data. This context is provided by the IHV component and can be used to store per-BSS entry state that the IHV component wants to maintain. To avoid lifetime management issues, the IHV component must not use pointers in this TLV. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY_DEVICE_CONTEXT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry-phy-info.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-phy-info.md new file mode 100644 index 0000000000..aec5cfd529 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-phy-info.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_BSS_ENTRY_PHY_INFO +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY_PHY_INFO is an unused TLV. +ms.assetid: BF96172C-BAD1-4A48-A680-4956430DB5D1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY_PHY_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY\_PHY\_INFO + + +WDI\_TLV\_BSS\_ENTRY\_PHY\_INFO is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY_PHY_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry-signal-info.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-signal-info.md new file mode 100644 index 0000000000..661ea9c08e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry-signal-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_BSS_ENTRY_SIGNAL_INFO +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY_SIGNAL_INFO is a TLV that contains signal information for a BSS entry. +ms.assetid: 4410F447-5226-4DF4-923D-11D10D0159CC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY_SIGNAL_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY\_SIGNAL\_INFO + + +WDI\_TLV\_BSS\_ENTRY\_SIGNAL\_INFO is a TLV that contains signal information for a BSS entry. + +## TLV Type + + +0xB + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| INT32 | The received signal strength indicator (RSSI) value of the beacon or probe response from the peer. This value is specified in units of decibels referenced to 1.0 milliwatts (dBm) | +| UINT32 | The link quality specified by a value from 0 to 100. A value of 100 specifies the highest link quality. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY_SIGNAL_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-entry.md b/windows-driver-docs-pr/network/wdi-tlv-bss-entry.md new file mode 100644 index 0000000000..afa00a145a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-entry.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_BSS_ENTRY +author: windows-driver-content +description: WDI_TLV_BSS_ENTRY is a TLV that contains BSS entry information. +ms.assetid: 1D3AAB94-9FCE-4243-994A-7195440DDFCA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_ENTRY + + +WDI\_TLV\_BSS\_ENTRY is a TLV that contains BSS entry information. + +## TLV Type + + +0x8 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------|--------------------------------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](wdi-tlv-bssid.md) | | | The BSSID of the BSS. | +| [**WDI\_TLV\_PROBE\_RESPONSE\_FRAME**](wdi-tlv-probe-response-frame.md) | | X | The probe response frame. If no probe response frame has been received, this is empty. | +| [**WDI\_TLV\_BEACON\_FRAME**](wdi-tlv-beacon-frame.md) | | X | The beacon frame. If no beacon has been received, this is empty. | +| [**WDI\_TLV\_BSS\_ENTRY\_SIGNAL\_INFO**](wdi-tlv-bss-entry-signal-info.md) | | | The signal information (received signal strength and link quality) of the BSS. | +| [**WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO**](wdi-tlv-bss-entry-channel-info.md) | | | The logical channel number and band ID for the BSS entry. | +| [**WDI\_TLV\_BSS\_ENTRY\_DEVICE\_CONTEXT**](wdi-tlv-bss-entry-device-context.md) | | X | Device context about the peer. This context is provided from the IHV component and can be used to store per-BSS entry state that the IHV component wants to maintain. To avoid lifetime management issues, the IHV component must not use pointers in this field. | +| [**WDI\_TLV\_BSS\_ENTRY\_AGE\_INFO**](wdi-tlv-bss-entry-age-info.md) | | X (Note: This TLV is mandatory if the BSS list is maintained by the IHV component.) | The age information for this BSS entry, including the timestamp of when this entry was most recently discovered. | +| [**WDI\_TLV\_P2P\_DISCOVERED\_SERVICE\_ENTRY**](wdi-tlv-p2p-discovered-service-entry.md) | X | X | The list of services found on the remote device, including the service information retrieved with a GAS query if the discovery request specified WDI\_P2P\_SERVICE\_DISCOVERY\_TYPE\_SERVICE\_INFORMATION as the discovery type. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bss-selection-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-bss-selection-parameters.md new file mode 100644 index 0000000000..1ff6e1fb04 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bss-selection-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BSS_SELECTION_PARAMETERS +author: windows-driver-content +description: WDI_TLV_BSS_SELECTION_PARAMETERS is a TLV that contains WDI_BSS_SELECTION_FLAGS that are used by host for BSS selection. +ms.assetid: 5EDA0FAC-DF2E-437B-BB4F-F69468CE856E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSS_SELECTION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSS\_SELECTION\_PARAMETERS + + +WDI\_TLV\_BSS\_SELECTION\_PARAMETERS is a TLV that contains [**WDI\_BSS\_SELECTION\_FLAGS**](https://msdn.microsoft.com/library/windows/hardware/mt297629) that are used by host for BSS selection. + +## TLV Type + + +0x10F + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------------------------| +| UINT32 | [**WDI\_BSS\_SELECTION\_FLAGS**](https://msdn.microsoft.com/library/windows/hardware/mt297629) that are used by the host for BSS selection. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSS_SELECTION_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bssid-info.md b/windows-driver-docs-pr/network/wdi-tlv-bssid-info.md new file mode 100644 index 0000000000..754db8c9a2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bssid-info.md @@ -0,0 +1,81 @@ +--- +title: WDI_TLV_BSSID_INFO +author: windows-driver-content +description: WDI_TLV_BSSID_INFO is a TLV that contains BSSID information. +ms.assetid: C9E2B2D5-16CA-438D-AD86-1FA4F4F11CD1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSSID_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSSID\_INFO + + +WDI\_TLV\_BSSID\_INFO is a TLV that contains BSSID information. + +## TLV Type + + +0x120 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | AP reachability. Valid values are 1 (not reachable), 2 (unknown), and 3 (reachable). | +| UINT8 | Security. If this is set to 1, it indicates that the AP identified by this BSSID supports the same security provisioning as used by the STA in its current association. If this is set to 0, it indicates that either this AP does not support the same security provisioning, or the security information is not available at this time. | +| UINT8 | Key scope bit. If it is set to 1, it indicates the AP indicated by this BSSID has the same authenticator as the AP sending the report. If this bit is set to 0, it indicates a distinct authenticator or the information is not available. | +| UINT8 | This is set to 1 if dot11SpectrumManagementRequired is true. | +| UINT8 | This is set to 1 if dot11QosOptionImplemented is true. | +| UINT8 | An AP sets the APSD subfield to 1 within the Capability Information field when dot11APSDOptionImplemented is true, and sets it to 0 otherwise. | +| UINT8 | This is set to 1 if dot11RadioMeasurementActivated is true. | +| UINT8 | This is set to 1 if dot11DelayedBlockAckOptionImplemented is true. | +| UINT8 | This is set to 1 if dot11ImmediateBlockAckOptionImplemented is true. | +| UINT8 | This is set to 1 if the AP represented by this BSSID includes an MDE in its Beacon frames. | +| UINT8 | This is set to 1 to indicate that the AP represented by this BSSID is an HT AP, including the HT Capabilities element in its Beacon. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSSID_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-bssid.md b/windows-driver-docs-pr/network/wdi-tlv-bssid.md new file mode 100644 index 0000000000..af71c5f5f3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-bssid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_BSSID +author: windows-driver-content +description: WDI_TLV_BSSID is a TLV that contains the BSSID of a BSS. +ms.assetid: 0B3AB317-D1E7-4E61-9F6E-C3134B5A3984 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_BSSID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_BSSID + + +WDI\_TLV\_BSSID is a TLV that contains the BSSID of a BSS. + +## TLV Type + + +0x2 + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|---------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | A Wi-Fi MAC address that specifies a BSSID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_BSSID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cancel-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-cancel-parameters.md new file mode 100644 index 0000000000..1082d89ea2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cancel-parameters.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_CANCEL_PARAMETERS +author: windows-driver-content +description: WDI_TLV_CANCEL_PARAMETERS is a TLV that contains parameters for OID_WDI_ABORT_TASK. +ms.assetid: 7C071743-5DF9-4CA8-873A-64B06C94388F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CANCEL_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CANCEL\_PARAMETERS + + +WDI\_TLV\_CANCEL\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_ABORT\_TASK](https://msdn.microsoft.com/library/windows/hardware/dn925835). + +## TLV Type + + +0x2B + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|------------------------|---------------------------------------------------------| +| NDIS\_OID | Specifies the OID from the original task being aborted. | +| UINT32 | Specifies the transaction ID from the original task. | +| WDI\_PORT\_ID (UINT16) | Specifies the port ID from the original task. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CANCEL_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-channel-info-list.md b/windows-driver-docs-pr/network/wdi-tlv-channel-info-list.md new file mode 100644 index 0000000000..c93f16f93c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-channel-info-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CHANNEL_INFO_LIST +author: windows-driver-content +description: WDI_TLV_CHANNEL_INFO_LIST is a TLV that contains a list of channels. +ms.assetid: D1B82F4F-6722-4D54-B6FF-B7F1309F8C0E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHANNEL_INFO_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHANNEL\_INFO\_LIST + + +WDI\_TLV\_CHANNEL\_INFO\_LIST is a TLV that contains a list of channels. + +## TLV Type + + +0x41 + +## Length + + +The size (in bytes) of the array of WDI\_CHANNEL\_NUMBER (UINT32) structures. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|------------|-----------------------------| +| UINT32\[\] | An array of Wi-Fi channels. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHANNEL_INFO_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-channel-list.md b/windows-driver-docs-pr/network/wdi-tlv-channel-list.md new file mode 100644 index 0000000000..5848c68b9d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-channel-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CHANNEL_LIST +author: windows-driver-content +description: WDI_TLV_CHANNEL_LIST is a TLV that contains one or more channel numbers. +ms.assetid: DBBA28C2-D80F-409B-BEE6-81B6FEDF7484 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHANNEL_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHANNEL\_LIST + + +WDI\_TLV\_CHANNEL\_LIST is a TLV that contains one or more channel numbers. + +## TLV Type + + +0x4 + +## Length + + +The size (in bytes) of the array of [**WDI\_CHANNEL\_MAPPING\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897799) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|----------------------------------------------------------------------------|--------------------------------------| +| [**WDI\_CHANNEL\_MAPPING\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897799)\[\] | An array of channel mapping entries. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHANNEL_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-channel-number.md b/windows-driver-docs-pr/network/wdi-tlv-channel-number.md new file mode 100644 index 0000000000..e13554f156 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-channel-number.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CHANNEL_NUMBER +author: windows-driver-content +description: WDI_TLV_CHANNEL_NUMBER is a TLV that contains a channel number. +ms.assetid: 254831C8-8AE0-4742-8FCC-0310214696A7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHANNEL_NUMBER Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHANNEL\_NUMBER + + +WDI\_TLV\_CHANNEL\_NUMBER is a TLV that contains a channel number. + +## TLV Type + + +0x121 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|---------------------| +| UINT8 | The channel number. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHANNEL_NUMBER%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-channel-width-list.md b/windows-driver-docs-pr/network/wdi-tlv-channel-width-list.md new file mode 100644 index 0000000000..94c7a668ba --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-channel-width-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CHANNEL_WIDTH_LIST +author: windows-driver-content +description: WDI_TLV_CHANNEL_WIDTH_LIST is a TLV that contains a list of channel widths. +ms.assetid: 9869157D-2E71-4F08-92D0-A4FFA085ACE7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHANNEL_WIDTH_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHANNEL\_WIDTH\_LIST + + +WDI\_TLV\_CHANNEL\_WIDTH\_LIST is a TLV that contains a list of channel widths. + +## TLV Type + + +0xF5 + +## Length + + +The size (in bytes) of the array of UINT32 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|------------|---------------------------------------------| +| UINT32\[\] | A list of channel widths, specified in MHz. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHANNEL_WIDTH_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-capabilities.md new file mode 100644 index 0000000000..75c7945142 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-capabilities.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_CHECKSUM_OFFLOAD_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_CHECKSUM_OFFLOAD_CAPABILITIES is a TLV that contains checksum offload capabilities for IPv4 and IPv6. +ms.assetid: 400D532F-CAAA-40F9-8001-EE460D4C89F9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHECKSUM_OFFLOAD_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHECKSUM\_OFFLOAD\_CAPABILITIES + + +WDI\_TLV\_CHECKSUM\_OFFLOAD\_CAPABILITIES is a TLV that contains checksum offload capabilities for IPv4 and IPv6. + +## TLV Type + + +0xCB + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------| +| [**WDI\_TLV\_IPV4\_CHECKSUM\_OFFLOAD**](wdi-tlv-ipv4-checksum-offload.md) | | | Parameters for IPv4 checksum offload. | +| [**WDI\_TLV\_IPV6\_CHECKSUM\_OFFLOAD**](wdi-tlv-ipv6-checksum-offload.md) | | | Parameters for IPv6 checksum offload. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHECKSUM_OFFLOAD_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-rx-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-rx-parameters.md new file mode 100644 index 0000000000..bbe0b4aa62 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-rx-parameters.md @@ -0,0 +1,111 @@ +--- +title: WDI_TLV_CHECKSUM_OFFLOAD_V4_RX_PARAMETERS (0xD2) +author: windows-driver-content +description: WDI_TLV_CHECKSUM_OFFLOAD_V4_RX_PARAMETERS is a TLV that contains parameters for Rx checksum offload for IPv4. +ms.assetid: A06E0534-CD5E-4D81-AEC8-CFC6106AAD85 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHECKSUM_OFFLOAD_V4_RX_PARAMETERS (0xD2) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_RX\_PARAMETERS (0xD2) + + +WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_RX\_PARAMETERS is a TLV that contains parameters for Rx checksum offload for IPv4. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xD2 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation settings. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32Specifies if offload of checksum with IP options is supported.
UINT32Specifies if offload of checksum with TCP options is supported.
UINT32Specifies if TCP checksum offload is enabled.
UINT32Specifies if UDP offload is enabled.
UINT32Specifies if IP checksum is enabled.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHECKSUM_OFFLOAD_V4_RX_PARAMETERS%20%280xD2%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-tx-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-tx-parameters.md new file mode 100644 index 0000000000..ff6df6bec8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v4-tx-parameters.md @@ -0,0 +1,111 @@ +--- +title: WDI_TLV_CHECKSUM_OFFLOAD_V4_TX_PARAMETERS (0xD1) +author: windows-driver-content +description: WDI_TLV_CHECKSUM_OFFLOAD_V4_TX_PARAMETERS is a TLV that contains parameters for Tx checksum offload for IPv4. +ms.assetid: EA862CDA-5FF4-4C5F-A522-224714640F34 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHECKSUM_OFFLOAD_V4_TX_PARAMETERS (0xD1) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_TX\_PARAMETERS (0xD1) + + +WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_TX\_PARAMETERS is a TLV that contains parameters for Tx checksum offload for IPv4. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xD1 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation settings. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32Specifies if offload of checksum with IP options is supported.
UINT32Specifies if offload of checksum with TCP options is supported.
UINT32Specifies if TCP checksum offload is enabled.
UINT32Specifies if UDP offload is enabled.
UINT32Specifies if IP checksum is enabled.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHECKSUM_OFFLOAD_V4_TX_PARAMETERS%20%280xD1%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-rx-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-rx-parameters.md new file mode 100644 index 0000000000..79d9b43864 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-rx-parameters.md @@ -0,0 +1,107 @@ +--- +title: WDI_TLV_CHECKSUM_OFFLOAD_V6_RX_PARAMETERS (0xDD) +author: windows-driver-content +description: WDI_TLV_CHECKSUM_OFFLOAD_V6_RX_PARAMETERS is a TLV that contains for Rx checksum offload for IPv6. +ms.assetid: F647B2B6-F535-4AE2-B7A9-DF08AADB2A95 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHECKSUM_OFFLOAD_V6_RX_PARAMETERS (0xDD) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_RX\_PARAMETERS (0xDD) + + +WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_RX\_PARAMETERS is a TLV that contains for Rx checksum offload for IPv6. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xDD + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation type. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32Specifies if offload of checksum of packets with IP extension headers is supported.
UINT32Specifies if offload of checksum with TCP options is supported.
UINT32Specifies if TCP checksum offload is enabled.
UINT32Specifies if UDP offload is enabled.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHECKSUM_OFFLOAD_V6_RX_PARAMETERS%20%280xDD%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-tx-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-tx-parameters.md new file mode 100644 index 0000000000..e25b3d7a44 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-checksum-offload-v6-tx-parameters.md @@ -0,0 +1,107 @@ +--- +title: WDI_TLV_CHECKSUM_OFFLOAD_V6_TX_PARAMETERS (0xDC) +author: windows-driver-content +description: WDI_TLV_CHECKSUM_OFFLOAD_V6_TX_PARAMETERS is a TLV that contains for Tx checksum offload for IPv6. +ms.assetid: F0340707-4E81-4E66-AF0E-A2918F4F5C7A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CHECKSUM_OFFLOAD_V6_TX_PARAMETERS (0xDC) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_TX\_PARAMETERS (0xDC) + + +WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_TX\_PARAMETERS is a TLV that contains for Tx checksum offload for IPv6. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xDC + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation type. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32Specifies if offload of checksum of packets with IP extension headers is supported.
UINT32Specifies if offload of checksum with TCP options is supported.
UINT32Specifies if TCP checksum offload is enabled.
UINT32Specifies if UDP offload is enabled.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CHECKSUM_OFFLOAD_V6_TX_PARAMETERS%20%280xDC%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-bip-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-bip-key.md new file mode 100644 index 0000000000..2cc0ffe26c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-bip-key.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_BIP_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_BIP_KEY is a TLV that contains BIP cipher algorithm key data for OID_WDI_SET_ADD_CIPHER_KEYS. +ms.assetid: 99630BDF-9845-4E3D-AB18-5F5BAFCF7198 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_BIP_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_BIP\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_BIP\_KEY is a TLV that contains BIP cipher algorithm key data for [OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925855). + +## TLV Type + + +0x51 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------| +| UINT8\[\] | Specifies BIP cipher algorithm key data. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_BIP_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ccmp-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ccmp-key.md new file mode 100644 index 0000000000..3601243212 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ccmp-key.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_CCMP_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_CCMP_KEY is a TLV that contains CCMP cipher algorithm key data for OID_WDI_SET_ADD_CIPHER_KEY. +ms.assetid: A4754EAC-AA54-45CC-A7C5-B78A2757E012 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_CCMP_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_CCMP\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_CCMP\_KEY is a TLV that contains CCMP cipher algorithm key data for [OID\_WDI\_SET\_ADD\_CIPHER\_KEY](https://msdn.microsoft.com/library/windows/hardware/dn925855). + +## TLV Type + + +0x50 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-------------------------------------------| +| UINT8\[\] | Specifies CCMP cipher algorithm key data. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_CCMP_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-gcmp-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-gcmp-key.md new file mode 100644 index 0000000000..69b1f66886 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-gcmp-key.md @@ -0,0 +1,57 @@ +--- +title: WDI_TLV_CIPHER_KEY_GCMP_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_GCMP_KEY (0x12F) is an unused TLV. +ms.assetid: 5F857D71-10B0-48B9-861F-382228E9B7AD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_GCMP_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_GCMP\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_GCMP\_KEY (0x12F) is an unused TLV. + +## TLV Type + + +0x12F + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_GCMP_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-id.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-id.md new file mode 100644 index 0000000000..0a53982913 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-id.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_ID +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_ID is a TLV that contains a cipher key ID for OID_WDI_SET_ADD_CIPHER_KEYS and OID_WDI_SET_DELETE_CIPHER_KEYS. +ms.assetid: 24076B2A-FAC2-4509-9F1C-7F2AF57883CF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_ID + + +WDI\_TLV\_CIPHER\_KEY\_ID is a TLV that contains a cipher key ID for [OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925855) and [OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925929). + +## TLV Type + + +0x4D + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|------------------------------| +| UINT32 | Specifies the cipher key ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ihv-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ihv-key.md new file mode 100644 index 0000000000..d94230d8a7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-ihv-key.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_IHV_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_IHV_KEY is a TLV that contains an IHV key. +ms.assetid: 5814DEA6-038A-4CA6-8518-E8830BBA6B7F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_IHV_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_IHV\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_IHV\_KEY is a TLV that contains an IHV key. + +## TLV Type + + +0x118 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the IHV key. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_IHV_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-receive-sequence-count.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-receive-sequence-count.md new file mode 100644 index 0000000000..cd15df6812 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-receive-sequence-count.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_RECEIVE_SEQUENCE_COUNT +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_RECEIVE_SEQUENCE_COUNT is a TLV that contains the receive sequence count. +ms.assetid: 29AA9D90-834F-4043-B12A-87705EDC1DF0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_RECEIVE_SEQUENCE_COUNT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_RECEIVE\_SEQUENCE\_COUNT + + +WDI\_TLV\_CIPHER\_KEY\_RECEIVE\_SEQUENCE\_COUNT is a TLV that contains the receive sequence count. + +## TLV Type + + +0x4F + +## Length + + +The size (in bytes) of the array of UINT8 elements. + +## Values + + +| Type | Description | +|------------|------------------------------------------------------------------------------------------------| +| UINT8\[6\] | Specifies the initial 48-bit value of Packet Number (PN), which is used for replay protection. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_RECEIVE_SEQUENCE_COUNT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-info.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-info.md new file mode 100644 index 0000000000..8d14bba69c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_CIPHER_KEY_TKIP_INFO +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_TKIP_INFO is a TLV that contains TKIP information. +ms.assetid: 330A93F5-43E7-4A4A-A6BD-EF276D6F09A1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_TKIP_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_TKIP\_INFO + + +WDI\_TLV\_CIPHER\_KEY\_TKIP\_INFO is a TLV that contains TKIP information. + +## TLV Type + + +0x4B + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------|--------------------------------|----------|----------------------------------| +| [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_KEY**](wdi-tlv-cipher-key-tkip-key.md) | | | Specifies the TKIP key material. | +| [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_MIC**](wdi-tlv-cipher-key-tkip-mic.md) | | | Specifies the TKIP MIC material. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_TKIP_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-key.md new file mode 100644 index 0000000000..d73046f931 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-key.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_TKIP_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_TKIP_KEY is a TLV that contains TKIP key material. +ms.assetid: 73E4F051-5CC3-4F9E-9AFD-F33FAAC5A39D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_TKIP_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_TKIP\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_TKIP\_KEY is a TLV that contains TKIP key material. + +## TLV Type + + +0x49 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the TKIP key material. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_TKIP_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-mic.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-mic.md new file mode 100644 index 0000000000..f04f8167f0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-tkip-mic.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_TKIP_MIC +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_TKIP_MIC is a TLV that contains the TKIP MIC material. +ms.assetid: 5F1AE81C-6AB4-468C-9DEE-D1BB16A2EC4D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_TKIP_MIC Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_TKIP\_MIC + + +WDI\_TLV\_CIPHER\_KEY\_TKIP\_MIC is a TLV that contains the TKIP MIC material. + +## TLV Type + + +0x4A + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the TKIP MIC material. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_TKIP_MIC%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-type-info.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-type-info.md new file mode 100644 index 0000000000..183f0d8f8a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-type-info.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_CIPHER_KEY_TYPE_INFO +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_TYPE_INFO is a TLV that contains cipher key type information for OID_WDI_SET_ADD_CIPHER_KEYS and OID_WDI_SET_DELETE_CIPHER_KEYS. +ms.assetid: 1168D53D-A837-4E3F-8E31-FB86CF866BA3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_TYPE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO + + +WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO is a TLV that contains cipher key type information for [OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925855) and [OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925929). + +## TLV Type + + +0x4E + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) | Specifies the cipher algorithm that uses the key. | +| [**WDI\_CIPHER\_KEY\_DIRECTION**](https://msdn.microsoft.com/library/windows/hardware/dn897803) | Specifies whether the key should be used for transmit only, receive only, or both. | +| UINT8 | Specifies whether the port should delete the key on a roam. If this value is set to 0, the key must be deleted when the port disconnects from the BSS network or connects to the BSS network. If this value is set to 1, the key should be deleted on an explicit delete or on a reset request. | +| [**WDI\_CIPHER\_KEY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn897806) | Specifies the type of key being published. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_TYPE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-cipher-key-wep-key.md b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-wep-key.md new file mode 100644 index 0000000000..7a2aa9c53a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-cipher-key-wep-key.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CIPHER_KEY_WEP_KEY +author: windows-driver-content +description: WDI_TLV_CIPHER_KEY_WEP_KEY is a TLV that contains a WEP key. +ms.assetid: 22C332B4-A9A7-4205-9ADA-80914FB34642 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CIPHER_KEY_WEP_KEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CIPHER\_KEY\_WEP\_KEY + + +WDI\_TLV\_CIPHER\_KEY\_WEP\_KEY is a TLV that contains a WEP key. + +## TLV Type + + +0x58 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the WEP key. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CIPHER_KEY_WEP_KEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-coalescing-filter-match-count.md b/windows-driver-docs-pr/network/wdi-tlv-coalescing-filter-match-count.md new file mode 100644 index 0000000000..15b5a53d37 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-coalescing-filter-match-count.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_COALESCING_FILTER_MATCH_COUNT +author: windows-driver-content +description: WDI_TLV_COALESCING_FILTER_MATCH_COUNT is a TLV that contains the number of packets that have matched receive filters on the network port. +ms.assetid: 9B9A1ED9-B842-4788-94C9-829876EB5D73 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_COALESCING_FILTER_MATCH_COUNT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_COALESCING\_FILTER\_MATCH\_COUNT + + +WDI\_TLV\_COALESCING\_FILTER\_MATCH\_COUNT is a TLV that contains the number of packets that have matched receive filters on the network port. + +## TLV Type + + +0x66 + +## Length + + +The size (in bytes) of the a UINT64. + +## Values + + +| Type | Description | +|--------|------------------------------------------------------------------------------| +| UINT64 | The number of packets that have matched receive filters on the network port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_COALESCING_FILTER_MATCH_COUNT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-communication-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-communication-capabilities.md new file mode 100644 index 0000000000..d4a814b937 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-communication-capabilities.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_COMMUNICATION_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_COMMUNICATION_CAPABILITIES is a TLV that specifies the communication capabilities. +ms.assetid: 0A603358-05EA-4796-8D7F-E8F86F1C30F1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_COMMUNICATION_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_COMMUNICATION\_CAPABILITIES + + +WDI\_TLV\_COMMUNICATION\_CAPABILITIES is a TLV that specifies the communication capabilities. + +## TLV Type + + +0xE + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|------------------------------------| +| UINT32 | The maximum command size in bytes. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_COMMUNICATION_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-communication-configuration-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-communication-configuration-attributes.md new file mode 100644 index 0000000000..fb01de2f3d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-communication-configuration-attributes.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES is a TLV that contains the host-adapter communication protocol configuration attributes. +ms.assetid: A779FA2D-D3E0-4FC9-9A8A-09B6E3CFF758 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_COMMUNICATION\_CONFIGURATION\_ATTRIBUTES + + +WDI\_TLV\_COMMUNICATION\_CONFIGURATION\_ATTRIBUTES is a TLV that contains the host-adapter communication protocol configuration attributes. + +## TLV Type + + +0x20 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------| +| [**WDI\_TLV\_COMMUNICATION\_CAPABILITIES**](wdi-tlv-communication-capabilities.md) | | X | The communication capabilities. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_COMMUNICATION_CONFIGURATION_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-configured-mac-address.md b/windows-driver-docs-pr/network/wdi-tlv-configured-mac-address.md new file mode 100644 index 0000000000..8ab1f13e05 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-configured-mac-address.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CONFIGURED_MAC_ADDRESS +author: windows-driver-content +description: WDI_TLV_CONFIGURED_MAC_ADDRESS is a TLV that contains a custom MAC address. +ms.assetid: 2AB4AFF3-70E9-4E4B-885D-2578A5810A38 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CONFIGURED_MAC_ADDRESS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CONFIGURED\_MAC\_ADDRESS + + +WDI\_TLV\_CONFIGURED\_MAC\_ADDRESS is a TLV that contains a custom MAC address. + +## TLV Type + + +0x99 + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|---------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address that should be used for the port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CONFIGURED_MAC_ADDRESS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-connect-bss-entry.md b/windows-driver-docs-pr/network/wdi-tlv-connect-bss-entry.md new file mode 100644 index 0000000000..0dad026626 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-connect-bss-entry.md @@ -0,0 +1,81 @@ +--- +title: WDI_TLV_CONNECT_BSS_ENTRY +author: windows-driver-content +description: WDI_TLV_CONNECT_BSS_ENTRY is a TLV that contains a list of candidate connect BSS entries. +ms.assetid: 0D74B2DE-9224-4FDF-8EA8-B22CEC0B5F26 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CONNECT_BSS_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CONNECT\_BSS\_ENTRY + + +WDI\_TLV\_CONNECT\_BSS\_ENTRY is a TLV that contains a list of candidate connect BSS entries. + +## TLV Type + + +0x34 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](wdi-tlv-bssid.md) | | | The BSSID of the BSS. | +| [**WDI\_TLV\_PROBE\_RESPONSE\_FRAME**](wdi-tlv-probe-response-frame.md) | | X | The probe response frame. If no probe response has been received, this would be empty. | +| [**WDI\_TLV\_BEACON\_FRAME**](wdi-tlv-beacon-frame.md) | | X | The beacon frame. If no beacon has been received, this would be empty. | +| [**WDI\_TLV\_BSS\_ENTRY\_SIGNAL\_INFO**](wdi-tlv-bss-entry-signal-info.md) | | | The signal information for this BSS entry. | +| [**WDI\_TLV\_BSS\_ENTRY\_CHANNEL\_INFO**](wdi-tlv-bss-entry-channel-info.md) | | | The channel information for this BSS entry. | +| [**WDI\_TLV\_BSS\_ENTRY\_DEVICE\_CONTEXT**](wdi-tlv-bss-entry-device-context.md) | | X | The IHV provided context data about this peer. | +| [**WDI\_TLV\_PMKID**](wdi-tlv-pmkid.md) | | X | The 16 byte PMKID value for this BSS entry. | +| [**WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES**](wdi-tlv-extra-association-request-ies.md) | | X | The IE to be included in the (re)association request frame for this BSSID. If present, this should be included in addition to the common IE. | +| [**WDI\_TLV\_FT\_INITIAL\_ASSOC\_PARAMETERS**](wdi-tlv-ft-initial-assoc-parameters.md) | | X | The initial Mobility Domain association parameters. | +| [**WDI\_TLV\_FT\_REASSOC\_PARAMETERS**](wdi-tlv-ft-reassoc-parameters.md) | | X | The fast transition parameters (MDIE, R0KH-ID, PMKR0Name, SNonce). This is only present for Fast Transition (not during initial mobility domain association). | +| [**WDI\_TLV\_BSS\_SELECTION\_PARAMETERS**](wdi-tlv-bss-selection-parameters.md) | | X | [**WDI\_BSS\_SELECTION\_FLAGS**](https://msdn.microsoft.com/library/windows/hardware/mt297629) that provide information used by the host for BSS selection. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CONNECT_BSS_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-connect-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-connect-parameters.md new file mode 100644 index 0000000000..25a88fa43f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-connect-parameters.md @@ -0,0 +1,97 @@ +--- +title: WDI_TLV_CONNECT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_CONNECT_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_CONNECT and OID_WDI_TASK_ROAM. +ms.assetid: 6B2B4E5D-4BF9-4803-A373-FDF64AD3C99B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CONNECT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CONNECT\_PARAMETERS + + +WDI\_TLV\_CONNECT\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_CONNECT](https://msdn.microsoft.com/library/windows/hardware/dn925948) and [OID\_WDI\_TASK\_ROAM](https://msdn.microsoft.com/library/windows/hardware/dn925958). + +## TLV Type + + +0x33 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +Type +Multiple TLV instances allowed +Optional +Description +[**WDI\_TLV\_CONNECTION\_SETTINGS**](wdi-tlv-connection-settings.md) +The settings for the connection. +[**WDI\_TLV\_SSID**](wdi-tlv-ssid.md) +X +List of SSIDs that the port is allowed to connect to. +[**WDI\_TLV\_HESSID**](wdi-tlv-hessid.md) +X +List of HESSIDs that the port is allowed to connect to. This is an additional requirement to the SSID list. +[**WDI\_TLV\_AUTH\_ALGO\_LIST**](wdi-tlv-auth-algo-list.md) +The list of authentication algorithms that the connection can use. +[**WDI\_TLV\_MULTICAST\_CIPHER\_ALGO\_LIST**](wdi-tlv-multicast-cipher-algo-list.md) +The list of multicast cipher algorithms that the connection can use. +[**WDI\_TLV\_UNICAST\_CIPHER\_ALGO\_LIST**](wdi-tlv-unicast-cipher-algo-list.md) +The list of unicast cipher algorithms that the connection can use. +[**WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES**](wdi-tlv-extra-association-request-ies.md) +X +The IE blobs that must be included in the association requests sent by the port. This is applicable to any BSSID that the device would associate with. It should be used in addition to the BSSID specific IEs. +[**WDI\_TLV\_PHY\_TYPE\_LIST**](wdi-tlv-phy-type-list.md) +X +The list of PHYs that are allowed to be used for the association. If not specified, any supported PHY can be used. If specified, the device must only use the listed PHYs. +[**WDI\_TLV\_DISALLOWED\_BSSIDS\_LIST**](wdi-tlv-disallowed-bssids-list.md) +X +The list of BSSIDs that are not allowed to be used for association. If specified, the adapter must not associate to any AP that is not in this list. +[**WDI\_TLV\_ALLOWED\_BSSIDS\_LIST**](wdi-tlv-allowed-bssids-list.md) +X +The list of BSSIDs that are allowed to be used for association. If WDI specifies 255.255.255.255 then all BSSIDs are allowed. +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CONNECT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-connection-quality-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-connection-quality-parameters.md new file mode 100644 index 0000000000..a5d4ffab10 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-connection-quality-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CONNECTION_QUALITY_PARAMETERS +author: windows-driver-content +description: WDI_TLV_CONNECTION_QUALITY_PARAMETERS is a TLV that contains the desired Wi-Fi Connection Quality Hint. +ms.assetid: A371FD3A-5BF9-4921-AB8E-1651789FA9A1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CONNECTION_QUALITY_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CONNECTION\_QUALITY\_PARAMETERS + + +WDI\_TLV\_CONNECTION\_QUALITY\_PARAMETERS is a TLV that contains the desired Wi-Fi Connection Quality Hint. + +## TLV Type + + +0xA3 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|--------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The desired Wi-Fi Connection Quality Hint, as defined in [**WDI\_CONNECTION\_QUALITY\_HINT**](https://msdn.microsoft.com/library/windows/hardware/dn897807). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CONNECTION_QUALITY_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-connection-settings.md b/windows-driver-docs-pr/network/wdi-tlv-connection-settings.md new file mode 100644 index 0000000000..6d5afe443d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-connection-settings.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_CONNECTION_SETTINGS +author: windows-driver-content +description: WDI_TLV_CONNECTION_SETTINGS is a TLV that contains connection settings for OID_WDI_TASK_CONNECT. +ms.assetid: E08E895D-BFD6-496E-82FE-881FDDB0B88E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CONNECTION_SETTINGS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CONNECTION\_SETTINGS + + +WDI\_TLV\_CONNECTION\_SETTINGS is a TLV that contains connection settings for [OID\_WDI\_TASK\_CONNECT](https://msdn.microsoft.com/library/windows/hardware/dn925948). + +## TLV Type + + +0x3F + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies if this is a first-time connection request (value of 0) or a roaming connection (value of 1). | +| UINT8 | Specifies if this is a connection to a network with hidden/non-broadcast SSIDs. This value is 1 when connecting to a hidden network. | +| UINT8 | This sets the dot11ExcludeUnencrypted MIB. When this value is false (0) and the cipher algorithm is WEP, the port must connect to APs that do not set the privacy field in management frames. | +| UINT8 | Specifies if MFP is enabled (1) or disabled (0). The station must advertise its 802.11w capabilities in the association request if and only if this value is set to 1 (enabled). | +| UINT8 | Specifies if host-FIPS mode is enabled (1) or disabled (0). | +| [**WDI\_ASSOC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn897725) (UINT32) | Specifies the roaming needed reason. If this is triggered due to [NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED](https://msdn.microsoft.com/library/windows/hardware/dn925648), this contains the reason from the roam indication. | +| [**WDI\_ROAM\_TRIGGER**](https://msdn.microsoft.com/library/windows/hardware/mt269103) (UINT32) | Specifies whether this roam is a critical roam because the AP has set the Disassociation Imminent bit in its BSS Transition Request action frame. | +| UINT8 | Specifies if 802.11v BSS transition is supported. If this bit is set to 1, the Station must set the BSS Transition field of the Extended capabilities element (Bit 19) to 1 in the association request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CONNECTION_SETTINGS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-country-region-list.md b/windows-driver-docs-pr/network/wdi-tlv-country-region-list.md new file mode 100644 index 0000000000..192f15dc51 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-country-region-list.md @@ -0,0 +1,83 @@ +--- +title: WDI_TLV_COUNTRY_REGION_LIST +author: windows-driver-content +description: WDI_TLV_COUNTRY_REGION_LIST is a TLV that contains a list of country or region codes. +ms.assetid: 675C176F-EE7A-41E0-9770-4D810F29E7BF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_COUNTRY_REGION_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_COUNTRY\_REGION\_LIST + + +WDI\_TLV\_COUNTRY\_REGION\_LIST is a TLV that contains a list of country or region codes. + +## TLV Type + + +0x12 + +## Length + + +The size (in bytes) of the array of WDI\_COUNTRY\_REGION\_LIST elements. The array must contain 1 or more elements. + +**Note**  WDI\_COUNTRY\_REGION\_LIST is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|--------------------------------|--------------------------------------| +| WDI\_COUNTRY\_REGION\_LIST\[\] | An array of country or region codes. | + +  + +WDI\_COUNTRY\_REGION\_LIST consists of the following elements. + +| Type | Description | +|------------|---------------------------| +| UINT8\[3\] | A country or region code. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_COUNTRY_REGION_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-create-port-mac-address.md b/windows-driver-docs-pr/network/wdi-tlv-create-port-mac-address.md new file mode 100644 index 0000000000..1cb2a7a31e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-create-port-mac-address.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_CREATE_PORT_MAC_ADDRESS +author: windows-driver-content +description: WDI_TLV_CREATE_PORT_MAC_ADDRESS is a TLV that contains a MAC address for OID_WDI_TASK_CREATE_PORT. +ms.assetid: CE2174E2-CFD7-40E7-B8A2-B96DDB6D6AA4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CREATE_PORT_MAC_ADDRESS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CREATE\_PORT\_MAC\_ADDRESS + + +WDI\_TLV\_CREATE\_PORT\_MAC\_ADDRESS is a TLV that contains a MAC address for [OID\_WDI\_TASK\_CREATE\_PORT](https://msdn.microsoft.com/library/windows/hardware/dn925949). + +## TLV Type + + +0xD9 + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|-----------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address to be used for port creation. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CREATE_PORT_MAC_ADDRESS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-create-port-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-create-port-parameters.md new file mode 100644 index 0000000000..396ffe7a58 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-create-port-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_CREATE_PORT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_CREATE_PORT_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_CREATE_PORT. +ms.assetid: CE0ACE11-5E7A-43E1-BE0B-8BA8F7FF8432 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CREATE_PORT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CREATE\_PORT\_PARAMETERS + + +WDI\_TLV\_CREATE\_PORT\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_CREATE\_PORT](https://msdn.microsoft.com/library/windows/hardware/dn925949). + +## TLV Type + + +0x28 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT16 | A bitwise OR value of the operation modes the host may configure on the port being created. The operation modes are defined in [**WDI\_OPERATION\_MODE**](https://msdn.microsoft.com/library/windows/hardware/dn926085). | +| UINT32 | The NDIS\_PORT\_NUMBER that will be associated with the created port. Unless the adapter wants to handle non-WDI OIDs, it does not need to do anything with this field. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CREATE_PORT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-current-channel-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-current-channel-parameters.md new file mode 100644 index 0000000000..0beae32091 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-current-channel-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_CURRENT_CHANNEL_PARAMETERS +author: windows-driver-content +description: WDI_TLV_CURRENT_CHANNEL_PARAMETERS is an unused TLV. +ms.assetid: C2447497-0C71-4EF8-B8AE-A7C34DF42405 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_CURRENT_CHANNEL_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_CURRENT\_CHANNEL\_PARAMETERS + + +WDI\_TLV\_CURRENT\_CHANNEL\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_CURRENT_CHANNEL_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-datapath-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-datapath-attributes.md new file mode 100644 index 0000000000..d5561ae685 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-datapath-attributes.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DATAPATH_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_DATAPATH_ATTRIBUTES is a TLV that contains datapath attributes. +ms.assetid: 3477054B-01CE-4D08-8A58-49FD8840B237 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DATAPATH_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DATAPATH\_ATTRIBUTES + + +WDI\_TLV\_DATAPATH\_ATTRIBUTES is a TLV that contains datapath attributes. + +## TLV Type + + +0xB8 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------|--------------------------------|----------|----------------------------| +| [**WDI\_TLV\_DATAPATH\_CAPABILITIES**](wdi-tlv-datapath-capabilities.md) | | X | The datapath capabilities. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DATAPATH_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-datapath-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-datapath-capabilities.md new file mode 100644 index 0000000000..e210176c69 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-datapath-capabilities.md @@ -0,0 +1,125 @@ +--- +title: WDI_TLV_DATAPATH_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_DATAPATH_CAPABILITIES is a TLV that contains datapath capabilities. +ms.assetid: 7B545858-56A2-4655-91D5-37CA4EB61E1E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DATAPATH_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DATAPATH\_CAPABILITIES + + +WDI\_TLV\_DATAPATH\_CAPABILITIES is a TLV that contains datapath capabilities. + +## TLV Type + + +0xB9 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
[WDI_INTERCONNECT_TYPE](https://msdn.microsoft.com/library/windows/hardware/dn926068) (UINT32)Interconnect type.
UINT8Maximum number of peers.
UINT8Specifies transmit capability: Target priority queuing. +

Valid values are 0 and 1. If set to 0, WDI classifies Tx frames by Peer and TID and utilizes the full scheduler to select TX queues to transfer. It is recommended that this is set to false unless the target is capable of classification and Peer-TID queueing. If set to 1, WDI classifies Tx frames by Peer and TID and only provides queuing at a port level. WDI schedules backlogged port queues using a global DRR.

UINT16Specifies transmit capability: Maximum number of Scatter Gather elements in frame. +

WDI coalesces frames as necessary such that the IHV miniport does not receive a frame that requires more scatter gather elements than specified by this capability. For best performance, it is suggested that this capability is set higher than the typical frame as the coalescing requires a memory copy. If this capability is not greater than max frame size divided by page size, WDI may be unable to successfully coalesce the frame and it may be dropped.

UINT8Specifies transmit capability: Explicit Send Complete flag required. +

Valid values are 0 and 1. If set to 0, the target/TAL generates a TX send complete for all frames. If set to 1, the target/TAL generates TX send completion indication only for frames that have this flag set in the frame’s metadata.

UINT16Specifies transmit capability: Minimum effective frame size. +

When dequeuing frames, the TxMgr treats frames smaller than this value as having an effective size of this value.

UINT16Specifies transmit capability: Frame size granularity. +

This value is equal to the granularity of memory allocation per frame. For the purposes of dequeuing, the TxMgr treats a frame as having an effective size equal to the frame size plus the least amount of padding such that the effective size is an integer multiple of this value. This value must be set to a power of two.

UINT8Specifies transmit capability: Rx Tx forwarding. +

Valid values are 0 and 1. If set to 1, the target is capable of forwarding received frames.

UINT32Specifies transmit capability: Maximum throughput, in units of 0.5 Mbps. +

This value is used for the allocation of descriptors and buffers.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DATAPATH_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-default-tx-key-id-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-default-tx-key-id-parameters.md new file mode 100644 index 0000000000..a44e7ee46c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-default-tx-key-id-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DEFAULT_TX_KEY_ID_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DEFAULT_TX_KEY_ID_PARAMETERS is a TLV that contains the default key ID for packet transmission on a port for OID_WDI_SET_DEFAULT_KEY_ID. +ms.assetid: 24E7E758-FEED-4D2A-BAA8-6DBC08726FBA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DEFAULT_TX_KEY_ID_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DEFAULT\_TX\_KEY\_ID\_PARAMETERS + + +WDI\_TLV\_DEFAULT\_TX\_KEY\_ID\_PARAMETERS is a TLV that contains the default key ID for packet transmission on a port for [OID\_WDI\_SET\_DEFAULT\_KEY\_ID](https://msdn.microsoft.com/library/windows/hardware/dn925928). + +## TLV Type + + +0x54 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------| +| UINT32 | Specifies the default key ID for packet transmission on a port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DEFAULT_TX_KEY_ID_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-delete-cipher-key-info.md b/windows-driver-docs-pr/network/wdi-tlv-delete-cipher-key-info.md new file mode 100644 index 0000000000..c81e981451 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-delete-cipher-key-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_DELETE_CIPHER_KEY_INFO +author: windows-driver-content +description: WDI_TLV_DELETE_CIPHER_KEY_INFO is a TLV that contains information to identify a single cipher key to remove with OID_WDI_SET_DELETE_CIPHER_KEYS. +ms.assetid: 5AD84E05-9A25-4FE8-BDF4-CCBA89D09A3F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DELETE_CIPHER_KEY_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DELETE\_CIPHER\_KEY\_INFO + + +WDI\_TLV\_DELETE\_CIPHER\_KEY\_INFO is a TLV that contains information to identify a single cipher key to remove with [OID\_WDI\_SET\_DELETE\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925929). + +## TLV Type + + +0x53 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_PEER\_MAC\_ADDRESS**](wdi-tlv-peer-mac-address.md) | | X | Specifies the peer MAC address. At least one of WDI\_TLV\_PEER\_MAC\_ADDRESS or WDI\_TLV\_CIPHER\_KEY\_ID must be present. | +| [**WDI\_TLV\_CIPHER\_KEY\_ID**](wdi-tlv-cipher-key-id.md) | | X | Specifies the cipher key ID. At least one of WDI\_TLV\_PEER\_MAC\_ADDRESS or WDI\_TLV\_CIPHER\_KEY\_ID must be present. | +| [**WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO**](wdi-tlv-cipher-key-type-info.md) | | | Specifies the cipher key type information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DELETE_CIPHER_KEY_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-delete-peer-state-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-delete-peer-state-parameters.md new file mode 100644 index 0000000000..130e3e3818 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-delete-peer-state-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_DELETE_PEER_STATE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DELETE_PEER_STATE_PARAMETERS is an unused TLV. +ms.assetid: 784FC7E3-8922-44D1-B46D-BEC6CE7EF3EF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DELETE_PEER_STATE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DELETE\_PEER\_STATE\_PARAMETERS + + +WDI\_TLV\_DELETE\_PEER\_STATE\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DELETE_PEER_STATE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-delete-port-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-delete-port-parameters.md new file mode 100644 index 0000000000..4d9044d31e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-delete-port-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DELETE_PORT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DELETE_PORT_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_DELETE_PORT. +ms.assetid: F3DDECDC-1A92-4022-9E2C-780ED480172C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DELETE_PORT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DELETE\_PORT\_PARAMETERS + + +WDI\_TLV\_DELETE\_PORT\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_DELETE\_PORT](https://msdn.microsoft.com/library/windows/hardware/dn925950). + +## TLV Type + + +0x2A + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|--------------------------------------| +| UINT16 | Specifies the port number to delete. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DELETE_PORT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disallowed-bssids-list.md b/windows-driver-docs-pr/network/wdi-tlv-disallowed-bssids-list.md new file mode 100644 index 0000000000..9b922af817 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disallowed-bssids-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DISALLOWED_BSSIDS_LIST +author: windows-driver-content +description: WDI_TLV_DISALLOWED_BSSIDS_LIST is a TLV that contains a list of BSSIDs that are not allowed to be used for association. +ms.assetid: A65A6C05-C4E1-4880-BF83-48B62D0C2FD3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISALLOWED_BSSIDS_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISALLOWED\_BSSIDS\_LIST + + +WDI\_TLV\_DISALLOWED\_BSSIDS\_LIST is a TLV that contains a list of BSSIDs that are not allowed to be used for association. + +## TLV Type + + +0xC3 + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | A list of BSSIDs that are not allowed to be used for association. If this is specified, the adapter must not associate to any AP that is not in this list | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISALLOWED_BSSIDS_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disassociation-indication-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-disassociation-indication-parameters.md new file mode 100644 index 0000000000..d60fb12515 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disassociation-indication-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_DISASSOCIATION_INDICATION_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DISASSOCIATION_INDICATION_PARAMETERS is a TLV that contains disassociation indication parameters for NDIS_STATUS_WDI_INDICATION_DISASSOCIATION. +ms.assetid: AD799DAA-B89D-4015-8DC5-53057C4DA43E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISASSOCIATION_INDICATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISASSOCIATION\_INDICATION\_PARAMETERS + + +WDI\_TLV\_DISASSOCIATION\_INDICATION\_PARAMETERS is a TLV that contains disassociation indication parameters for [NDIS\_STATUS\_WDI\_INDICATION\_DISASSOCIATION](https://msdn.microsoft.com/library/windows/hardware/dn925631). + +## TLV Type + + +0xBC + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------------------------------------------------------------|----------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the peer associated with the disassociation indication. | +| [**WDI\_ASSOC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn897725) (UINT32) | The trigger for the disassociation indication. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISASSOCIATION_INDICATION_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disassociation-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-disassociation-parameters.md new file mode 100644 index 0000000000..514a4eaa35 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disassociation-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_DISASSOCIATION_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DISASSOCIATION_PARAMETERS is an unused TLV. +ms.assetid: F056B5B3-900C-4D00-9330-F1FD8FA0993F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISASSOCIATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISASSOCIATION\_PARAMETERS + + +WDI\_TLV\_DISASSOCIATION\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISASSOCIATION_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disconnect-deauth-frame.md b/windows-driver-docs-pr/network/wdi-tlv-disconnect-deauth-frame.md new file mode 100644 index 0000000000..d6698043de --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disconnect-deauth-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DISCONNECT_DEAUTH_FRAME +author: windows-driver-content +description: WDI_TLV_DISCONNECT_DEAUTH_FRAME is a TLV that contains the received deauthentication frame. +ms.assetid: 394B83C7-D001-4816-BC38-42325469863C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISCONNECT_DEAUTH_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISCONNECT\_DEAUTH\_FRAME + + +WDI\_TLV\_DISCONNECT\_DEAUTH\_FRAME is a TLV that contains the received deauthentication frame. + +## TLV Type + + +0x37 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the received deauthentication frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISCONNECT_DEAUTH_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disconnect-disassociation-frame.md b/windows-driver-docs-pr/network/wdi-tlv-disconnect-disassociation-frame.md new file mode 100644 index 0000000000..5a4fc747d5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disconnect-disassociation-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DISCONNECT_DISASSOCIATION_FRAME +author: windows-driver-content +description: WDI_TLV_DISCONNECT_DISASSOCIATION_FRAME is a TLV that contains the received disassociation frame. +ms.assetid: 0AE2A543-DA01-4CFB-853D-2511AB18F92C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISCONNECT_DISASSOCIATION_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISCONNECT\_DISASSOCIATION\_FRAME + + +WDI\_TLV\_DISCONNECT\_DISASSOCIATION\_FRAME is a TLV that contains the received disassociation frame. + +## TLV Type + + +0x38 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the received disassociation frame. This does not include the 802.11 MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISCONNECT_DISASSOCIATION_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-disconnect-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-disconnect-parameters.md new file mode 100644 index 0000000000..1125d4d3a2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-disconnect-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_DISCONNECT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DISCONNECT_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_DISCONNECT. +ms.assetid: D0FF83A0-CD3B-47A6-BB08-842927F1D3BC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DISCONNECT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DISCONNECT\_PARAMETERS + + +WDI\_TLV\_DISCONNECT\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_DISCONNECT](https://msdn.microsoft.com/library/windows/hardware/dn925951). + +## TLV Type + + +0x36 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the peer to disassociate. | +| UINT16 | The reason for the host-triggered disassociation. This value is provided in little endian byte order and should be appropriately copied into the reason code of the outgoing frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DISCONNECT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-dot11-reset-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-dot11-reset-parameters.md new file mode 100644 index 0000000000..33e5c43994 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-dot11-reset-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_DOT11_RESET_PARAMETERS +author: windows-driver-content +description: WDI_TLV_DOT11_RESET_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_DOT11_RESET. +ms.assetid: 14F3DECD-E875-44BB-969B-705B075E4636 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_DOT11_RESET_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_DOT11\_RESET\_PARAMETERS + + +WDI\_TLV\_DOT11\_RESET\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_DOT11\_RESET](https://msdn.microsoft.com/library/windows/hardware/dn925952). + +## TLV Type + + +0xA2 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-----------------------------------------------------------------------------------------------------------------| +| UINT8 | If (and only if) this is set to 1, all MIB attributes for the port being reset are set to their default values. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_DOT11_RESET_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-enable-wake-events.md b/windows-driver-docs-pr/network/wdi-tlv-enable-wake-events.md new file mode 100644 index 0000000000..e4eefb334b --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-enable-wake-events.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_ENABLE_WAKE_EVENTS +author: windows-driver-content +description: WDI_TLV_ENABLE_WAKE_EVENTS is a TLV that contains the enabled wake events. +ms.assetid: 5F348D9A-5575-46EE-A524-687E9D030754 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ENABLE_WAKE_EVENTS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ENABLE\_WAKE\_EVENTS + + +WDI\_TLV\_ENABLE\_WAKE\_EVENTS is a TLV that contains the enabled wake events. + +## TLV Type + + +0x60 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the enabled wake-on-LAN packet patterns using the flags as documented in [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759).EnabledWoLPacketPatterns. | +| UINT32 | Specifies the enabled protocol offloads using the flags as documented in [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759).EnabledProtocolOffloads. | +| UINT32 | Specifies the wake-up flags using the flags as documented in [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759).WakeUpFlags. | +| UINT32 | Specifies the media-specific wake up events using the flags as documented in [**NDIS\_PM\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566759).MediaSpecificWakeUpEvents. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ENABLE_WAKE_EVENTS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ethertype-encap-table.md b/windows-driver-docs-pr/network/wdi-tlv-ethertype-encap-table.md new file mode 100644 index 0000000000..85f7c1ae8d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ethertype-encap-table.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ETHERTYPE_ENCAP_TABLE +author: windows-driver-content +description: WDI_TLV_ETHERTYPE_ENCAP_TABLE is a TLV that contains the Ethertype encapsulations for the association. +ms.assetid: BAAC7E5B-F13F-4AC8-A3F9-76197F92C7E3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ETHERTYPE_ENCAP_TABLE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ETHERTYPE\_ENCAP\_TABLE + + +WDI\_TLV\_ETHERTYPE\_ENCAP\_TABLE is a TLV that contains the Ethertype encapsulations for the association. + +## TLV Type + + +0x31 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_ETHERTYPE\_ENCAPSULATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897818)\[\] | An array of [**WDI\_ETHERTYPE\_ENCAPSULATION\_ENTRY**](https://msdn.microsoft.com/library/windows/hardware/dn897818) elements that specifies the Ethertype encapsulations for the association. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ETHERTYPE_ENCAP_TABLE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-extra-association-request-ies.md b/windows-driver-docs-pr/network/wdi-tlv-extra-association-request-ies.md new file mode 100644 index 0000000000..af37dc900a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-extra-association-request-ies.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_EXTRA_ASSOCIATION_REQUEST_IES +author: windows-driver-content +description: WDI_TLV_EXTRA_ASSOCIATION_REQUEST_IES is a TLV that contains Information Elements (IEs) that must be included in association requests sent by the port. +ms.assetid: 2275B8F2-1FE4-4518-AD67-E9A65F2F37DA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_EXTRA_ASSOCIATION_REQUEST_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES + + +WDI\_TLV\_EXTRA\_ASSOCIATION\_REQUEST\_IES is a TLV that contains Information Elements (IEs) that must be included in association requests sent by the port. + +## TLV Type + + +0x40 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the IEs that must be included in association requests sent by the port. These are applicable to any BSSID that the device associates with. They should be used in addition to the common and BSSID specific IEs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_EXTRA_ASSOCIATION_REQUEST_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-firmware-version.md b/windows-driver-docs-pr/network/wdi-tlv-firmware-version.md new file mode 100644 index 0000000000..ff7505404c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-firmware-version.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FIRMWARE_VERSION +author: windows-driver-content +description: WDI_TLV_FIRMWARE_VERSION is a TLV that contains the firmware version. +ms.assetid: 31E61ACA-AF2F-4E5D-9448-363630A27E39 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FIRMWARE_VERSION Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FIRMWARE\_VERSION + + +WDI\_TLV\_FIRMWARE\_VERSION is a TLV that contains the firmware version. + +## TLV Type + + +0xF4 + +## Length + + +The size (in bytes) of the array of char elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|----------|-----------------------------------------------------------------| +| char\[\] | The firmware version, stored as a null-terminated ASCII string. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FIRMWARE_VERSION%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-auth-request.md b/windows-driver-docs-pr/network/wdi-tlv-ft-auth-request.md new file mode 100644 index 0000000000..a18011da38 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-auth-request.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_AUTH_REQUEST +author: windows-driver-content +description: WDI_TLV_FT_AUTH_REQUEST is a TLV that contains the Fast Transition authentication request byte blob. +ms.assetid: 4107314E-3C0A-4610-A4FB-BCBDBD1A8E65 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_AUTH_REQUEST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_AUTH\_REQUEST + + +WDI\_TLV\_FT\_AUTH\_REQUEST is a TLV that contains the Fast Transition authentication request byte blob. + +## TLV Type + + +0x119 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the Fast Transition authentication request byte blob. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_AUTH_REQUEST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-auth-response.md b/windows-driver-docs-pr/network/wdi-tlv-ft-auth-response.md new file mode 100644 index 0000000000..1d02a43da4 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-auth-response.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_AUTH_RESPONSE +author: windows-driver-content +description: WDI_TLV_FT_AUTH_RESPONSE is a TLV that contains the Fast Transition authentication response byte blob. +ms.assetid: BF9B37B4-EC5D-46AA-B334-C1214310964B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_AUTH_RESPONSE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_AUTH\_RESPONSE + + +WDI\_TLV\_FT\_AUTH\_RESPONSE is a TLV that contains the Fast Transition authentication response byte blob. + +## TLV Type + + +0x10E + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-------------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the Fast Transition authentication response byte blob. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_AUTH_RESPONSE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-fte.md b/windows-driver-docs-pr/network/wdi-tlv-ft-fte.md new file mode 100644 index 0000000000..a63994c908 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-fte.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_FTE +author: windows-driver-content +description: WDI_TLV_FT_FTE is a TLV that contains a Fast Transition Element. +ms.assetid: E502508A-FB01-4F1E-9A68-40AA88894C61 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_FTE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_FTE + + +WDI\_TLV\_FT\_FTE is a TLV that contains a Fast Transition Element. + +## TLV Type + + +0x10B + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------| +| UINT8\[\] | A Fast Transition Element that contains the R0KHID and SNonce. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_FTE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-initial-assoc-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-ft-initial-assoc-parameters.md new file mode 100644 index 0000000000..16229156f5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-initial-assoc-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_INITIAL_ASSOC_PARAMETERS +author: windows-driver-content +description: WDI_TLV_FT_INITIAL_ASSOC_PARAMETERS is a TLV that contains initial association parameters for Fast Transition. +ms.assetid: 3A91AC2F-5654-488D-89A5-36A0AC71A836 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_INITIAL_ASSOC_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_INITIAL\_ASSOC\_PARAMETERS + + +WDI\_TLV\_FT\_INITIAL\_ASSOC\_PARAMETERS is a TLV that contains initial association parameters for Fast Transition. + +## TLV Type + + +0x105 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------|----------------------------| +| [**WDI\_TLV\_FT\_MDE**](wdi-tlv-ft-mde.md) | The MDIE of the BSS entry. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_INITIAL_ASSOC_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-mde.md b/windows-driver-docs-pr/network/wdi-tlv-ft-mde.md new file mode 100644 index 0000000000..1d36a5fd4d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-mde.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_MDE +author: windows-driver-content +description: WDI_TLV_FT_MDE is a TLV that contains the MDIE of a BSS entry. +ms.assetid: 2D075487-9B1E-4DEE-B3C3-3208C1CBAB64 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_MDE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_MDE + + +WDI\_TLV\_FT\_MDE is a TLV that contains the MDIE of a BSS entry. + +## TLV Type + + +0x10D + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------| +| UINT8\[\] | The MDIE of a BSS entry. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_MDE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-pmkr0name.md b/windows-driver-docs-pr/network/wdi-tlv-ft-pmkr0name.md new file mode 100644 index 0000000000..cb6afdb7b5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-pmkr0name.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_PMKR0NAME +author: windows-driver-content +description: WDI_TLV_FT_PMKR0NAME is a TLV that contains a PMKR0Name or PMKR1Name (802.11r). +ms.assetid: F280FB10-D6CD-4410-8F3C-CD114F62B091 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_PMKR0NAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_PMKR0NAME + + +WDI\_TLV\_FT\_PMKR0NAME is a TLV that contains a PMKR0Name or PMKR1Name (802.11r). + +## TLV Type + + +0x107 + +## Length + + +The size (in bytes) of a [**WDI\_TYPE\_PMK\_NAME**](https://msdn.microsoft.com/library/windows/hardware/mt269156) structure. + +## Values + + +| Type | Description | +|--------------------------------------------------------|-------------------------------------| +| [**WDI\_TYPE\_PMK\_NAME**](https://msdn.microsoft.com/library/windows/hardware/mt269156) | A PMKR0Name or PMKR1Name (802.11r). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_PMKR0NAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-r0khid.md b/windows-driver-docs-pr/network/wdi-tlv-ft-r0khid.md new file mode 100644 index 0000000000..c8dcab3c70 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-r0khid.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_FT_R0KHID +author: windows-driver-content +description: WDI_TLV_FT_R0KHID is an unused TLV. +ms.assetid: A9E8B09E-8EB8-4832-8F3D-148C2F0DF6BE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_R0KHID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_R0KHID + + +WDI\_TLV\_FT\_R0KHID is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_R0KHID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-r1khid.md b/windows-driver-docs-pr/network/wdi-tlv-ft-r1khid.md new file mode 100644 index 0000000000..bc9d8a1add --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-r1khid.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_FT_R1KHID +author: windows-driver-content +description: WDI_TLV_FT_R1KHID is an unused TLV. +ms.assetid: E032EF3C-6028-4481-B41A-6B9377B9A88B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_R1KHID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_R1KHID + + +WDI\_TLV\_FT\_R1KHID is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_R1KHID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-reassoc-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-ft-reassoc-parameters.md new file mode 100644 index 0000000000..6c367fbef8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-reassoc-parameters.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_FT_REASSOC_PARAMETERS +author: windows-driver-content +description: WDI_TLV_FT_REASSOC_PARAMETERS is a TLV that contains reassociation parameters for Fast Transition. +ms.assetid: 36F260FF-E80A-4EFF-B009-B06446229470 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_REASSOC_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_REASSOC\_PARAMETERS + + +WDI\_TLV\_FT\_REASSOC\_PARAMETERS is a TLV that contains reassociation parameters for Fast Transition. + +## TLV Type + + +0x106 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_FT\_MDE**](wdi-tlv-ft-mde.md) | The MDIE of the BSS entry. | +| [**WDI\_TLV\_FT\_PMKR0NAME**](wdi-tlv-ft-pmkr0name.md) | The PMKR0Name. This is needed during Fast Transition. The STA needs to send the PMKR0Name during the authentication request to the AP. | +| [**WDI\_TLV\_FT\_FTE**](wdi-tlv-ft-fte.md) | The Fast Transition Element that contains the R0KHID and SNonce. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_REASSOC_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-rsnie.md b/windows-driver-docs-pr/network/wdi-tlv-ft-rsnie.md new file mode 100644 index 0000000000..6ea476b829 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-rsnie.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_FT_RSNIE +author: windows-driver-content +description: WDI_TLV_FT_RSNIE is a TLV that contains the Fast Transition RSN IE byte blob. +ms.assetid: 1EB22517-472C-461D-A32F-175E4281FFF0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_RSNIE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_RSNIE + + +WDI\_TLV\_FT\_RSNIE is a TLV that contains the Fast Transition RSN IE byte blob. + +## TLV Type + + +0x10C + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that contains the Fast Transition RSN IE byte blob. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_RSNIE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ft-snonce.md b/windows-driver-docs-pr/network/wdi-tlv-ft-snonce.md new file mode 100644 index 0000000000..54f9127cc3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ft-snonce.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_FT_SNONCE +author: windows-driver-content +description: WDI_TLV_FT_SNONCE is an unused TLV. +ms.assetid: 43702677-C19B-4185-AFCD-9D8BF0CA31F9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_FT_SNONCE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_FT\_SNONCE + + +WDI\_TLV\_FT\_SNONCE is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_FT_SNONCE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-get-auto-power-save.md b/windows-driver-docs-pr/network/wdi-tlv-get-auto-power-save.md new file mode 100644 index 0000000000..bf9d2ab7c2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-get-auto-power-save.md @@ -0,0 +1,85 @@ +--- +title: WDI_TLV_GET_AUTO_POWER_SAVE +author: windows-driver-content +description: WDI_TLV_GET_AUTO_POWER_SAVE is a TLV that contains auto power save information for OID_WDI_GET_AUTO_POWER_SAVE. +ms.assetid: E57AD1CE-A252-4BB5-B983-11D3E46B7EC1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_GET_AUTO_POWER_SAVE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_GET\_AUTO\_POWER\_SAVE + + +WDI\_TLV\_GET\_AUTO\_POWER\_SAVE is a TLV that contains auto power save information for [OID\_WDI\_GET\_AUTO\_POWER\_SAVE](https://msdn.microsoft.com/library/windows/hardware/dn925840). + +## TLV Type + + +0xB3 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| UINT8 | The firmware current AutoPSM state. | +| UINT8 | Reserved. | +| UINT16 | Reserved. | +| UINT16 | The beacon interval in milliseconds. | +| UINT8 | The listen interval, in the unit of the beacon interval (for example, 1). | +| UINT8 | The listen interval in the last low power state (for example, 5). If there is no last low power state, set to 255. | +| [**WDI\_POWER\_SAVE\_LEVEL**](https://msdn.microsoft.com/library/windows/hardware/dn926107) (UINT32) | The power mode. | +| [**WDI\_POWER\_SAVE\_LEVEL**](https://msdn.microsoft.com/library/windows/hardware/dn926107) (UINT32) | The power mode in Dx. | +| [**WDI\_POWER\_MODE\_REASON\_CODE**](https://msdn.microsoft.com/library/windows/hardware/dn926106) (UINT32) | The reason for entering the Power Save state and listen interval. | +| UINT64 | Milliseconds since start. | +| UINT64 | Milliseconds in power save mode. | +| UINT64 | Number of received multicast packets, including broadcast. | +| UINT64 | Number of sent multicast packets, including broadcast. | +| UINT64 | Number of received unicast packets. | +| UINT64 | Number of sent unicast packets. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_GET_AUTO_POWER_SAVE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-hessid-info.md b/windows-driver-docs-pr/network/wdi-tlv-hessid-info.md new file mode 100644 index 0000000000..286811c430 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-hessid-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_HESSID_INFO +author: windows-driver-content +description: WDI_TLV_HESSID_INFO is a TLV that contains HESSID information, which includes a list of HESSIDs, the Access Network Type, and Hotspot Indication Element. +ms.assetid: 60D130AC-8249-4B60-B46C-8B83FDDB148F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_HESSID_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_HESSID\_INFO + + +WDI\_TLV\_HESSID\_INFO is a TLV that contains HESSID information, which includes a list of HESSIDs, the Access Network Type, and Hotspot Indication Element. + +## TLV Type + + +0xFF + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_ACCESS\_NETWORK\_TYPE**](wdi-tlv-access-network-type.md) | | | The Access Network Type to be used in probe requests for the network being connected to. | +| [**WDI\_TLV\_HESSID**](wdi-tlv-hessid.md) | | | The list of HESSIDs that the port is allowed to connect to. | +| [**WDI\_TLV\_HOTSPOT\_INDICATION\_ELEMENT**](wdi-tlv-hotspot-indication-element.md) | | | The Hotspot Indication Element to be used in the Association Request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_HESSID_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-hessid.md b/windows-driver-docs-pr/network/wdi-tlv-hessid.md new file mode 100644 index 0000000000..15501e956c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-hessid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_HESSID +author: windows-driver-content +description: WDI_TLV_HESSID is a TLV that contains a list of HESSIDs. +ms.assetid: 630A1824-7722-4B03-8073-EFC44E142400 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_HESSID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_HESSID + + +WDI\_TLV\_HESSID is a TLV that contains a list of HESSIDs. + +## TLV Type + + +0xC8 + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|--------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | A list of HESSIDs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_HESSID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-hotspot-domain-partner.md b/windows-driver-docs-pr/network/wdi-tlv-hotspot-domain-partner.md new file mode 100644 index 0000000000..dbb626c73d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-hotspot-domain-partner.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_HOTSPOT_DOMAIN_PARTNER +author: windows-driver-content +description: WDI_TLV_HOTSPOT_DOMAIN_PARTNER is an unused TLV. +ms.assetid: A2613190-2DE8-4B38-80F2-09F91A41656F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_HOTSPOT_DOMAIN_PARTNER Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_HOTSPOT\_DOMAIN\_PARTNER + + +WDI\_TLV\_HOTSPOT\_DOMAIN\_PARTNER is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_HOTSPOT_DOMAIN_PARTNER%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-hotspot-indication-element.md b/windows-driver-docs-pr/network/wdi-tlv-hotspot-indication-element.md new file mode 100644 index 0000000000..3eeffafd33 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-hotspot-indication-element.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_HOTSPOT_INDICATION_ELEMENT +author: windows-driver-content +description: WDI_TLV_HOTSPOT_INDICATION_ELEMENT is a TLV that contains a Hotspot Indication Element that is used in a Association Request. +ms.assetid: 7A5B61B5-DFFF-4525-A6CD-2AC2822D8B86 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_HOTSPOT_INDICATION_ELEMENT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_HOTSPOT\_INDICATION\_ELEMENT + + +WDI\_TLV\_HOTSPOT\_INDICATION\_ELEMENT is a TLV that contains a Hotspot Indication Element that is used in a Association Request. + +## TLV Type + + +0x101 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|---------------------------------------------------------------------| +| UINT8\[\] | A Hotspot Indication Element that is used in a Association Request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_HOTSPOT_INDICATION_ELEMENT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ihv-data.md b/windows-driver-docs-pr/network/wdi-tlv-ihv-data.md new file mode 100644 index 0000000000..c48c130d4e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ihv-data.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_IHV_DATA +author: windows-driver-content +description: WDI_TLV_IHV_DATA is a TLV that contains IHV-specific information that is used by the IHV extensibility module. +ms.assetid: 50D80D9E-C3FF-41E5-A054-A5A28ED499FD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IHV_DATA Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IHV\_DATA + + +WDI\_TLV\_IHV\_DATA is a TLV that contains IHV-specific information that is used by the IHV extensibility module. + +## TLV Type + + +0xBD + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------------------------------------| +| UINT8\[\] | IHV specific information that is used by the IHV extensibility module. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IHV_DATA%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ihv-non-wdi-oids-list.md b/windows-driver-docs-pr/network/wdi-tlv-ihv-non-wdi-oids-list.md new file mode 100644 index 0000000000..c298985284 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ihv-non-wdi-oids-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_IHV_NON_WDI_OIDS_LIST +author: windows-driver-content +description: WDI_TLV_IHV_NON_WDI_OIDS_LIST is a TLV that contains a list of non-WDI OIDs that the adapter wants to advertise to the operating system. +ms.assetid: 84929276-F098-4C24-A499-E252D5FB71A6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IHV_NON_WDI_OIDS_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IHV\_NON\_WDI\_OIDS\_LIST + + +WDI\_TLV\_IHV\_NON\_WDI\_OIDS\_LIST is a TLV that contains a list of non-WDI OIDs that the adapter wants to advertise to the operating system. + +## TLV Type + + +0x104 + +## Length + + +The size (in bytes) of the array of UINT32 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32\[\] | A list of non-WDI OIDs that the adapter wants to advertise to the operating system. The adapter should not assume that the operating system has already filtered non-WDI OIDs to match this list. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IHV_NON_WDI_OIDS_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ihv-task-device-context.md b/windows-driver-docs-pr/network/wdi-tlv-ihv-task-device-context.md new file mode 100644 index 0000000000..25f0ce39bf --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ihv-task-device-context.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_IHV_TASK_DEVICE_CONTEXT +author: windows-driver-content +description: WDI_TLV_IHV_TASK_DEVICE_CONTEXT is a TLV that contains IHV-provided device context for NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST. +ms.assetid: FBFE8931-DF29-4605-A14D-12CEC0433086 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IHV_TASK_DEVICE_CONTEXT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IHV\_TASK\_DEVICE\_CONTEXT + + +WDI\_TLV\_IHV\_TASK\_DEVICE\_CONTEXT is a TLV that contains IHV-provided device context for [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/dn925637). + +## TLV Type + + +0xE0 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------------------| +| UINT8\[\] | The IHV-provided device context information that is forwarded to the IHV task. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IHV_TASK_DEVICE_CONTEXT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ihv-task-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-ihv-task-request-parameters.md new file mode 100644 index 0000000000..71e4114597 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ihv-task-request-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_IHV_TASK_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_IHV_TASK_REQUEST_PARAMETERS is a TLV that contains the requested priority for NDIS_STATUS_WDI_INDICATION_IHV_TASK_REQUEST. +ms.assetid: C33CF8FE-EDBC-41D1-A63C-E43650E9570E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IHV_TASK_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IHV\_TASK\_REQUEST\_PARAMETERS + + +WDI\_TLV\_IHV\_TASK\_REQUEST\_PARAMETERS is a TLV that contains the requested priority for [NDIS\_STATUS\_WDI\_INDICATION\_IHV\_TASK\_REQUEST](https://msdn.microsoft.com/library/windows/hardware/dn925637). + +## TLV Type + + +0xDF + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The IHV-requested priority for this task. See [**WDI\_IHV\_TASK\_PRIORITY**](https://msdn.microsoft.com/library/windows/hardware/dn926064) for valid priority values. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IHV_TASK_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-info.md b/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-info.md new file mode 100644 index 0000000000..c903bb7f42 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_INCOMING_ASSOCIATION_REQUEST_INFO +author: windows-driver-content +description: WDI_TLV_INCOMING_ASSOCIATION_REQUEST_INFO is a TLV that contains information about the incoming association request. +ms.assetid: E36ADD95-1751-4FCE-9032-900968878DEE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INCOMING_ASSOCIATION_REQUEST_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_INFO + + +WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_INFO is a TLV that contains information about the incoming association request. + +## TLV Type + + +0x8F + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------| +| [**WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_PARAMETERS**](wdi-tlv-incoming-association-request-parameters.md) | | | The parameters for the incoming association request. | +| [**WDI\_TLV\_ASSOCIATION\_REQUEST\_FRAME**](wdi-tlv-association-request-frame.md) | | | The association request frame. | +| [**WDI\_TLV\_ASSOCIATION\_REQUEST\_DEVICE\_CONTEXT**](wdi-tlv-association-request-device-context.md) | | X | The vendor-specific information that is passed down to the port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INCOMING_ASSOCIATION_REQUEST_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-parameters.md new file mode 100644 index 0000000000..8b3fcbdc40 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-incoming-association-request-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_INCOMING_ASSOCIATION_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_INCOMING_ASSOCIATION_REQUEST_PARAMETERS is a TLV that contains association request parameters. +ms.assetid: DC3439A2-2221-4489-AB38-3752624EA4B2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INCOMING_ASSOCIATION_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_PARAMETERS + + +WDI\_TLV\_INCOMING\_ASSOCIATION\_REQUEST\_PARAMETERS is a TLV that contains association request parameters. + +## TLV Type + + +0x7D + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the sender. | +| UINT8 | A bit that indicates whether or not it is a reassociation request. A value of 1 indicates that it is a reassociation request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INCOMING_ASSOCIATION_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-indication-can-sustain-ap.md b/windows-driver-docs-pr/network/wdi-tlv-indication-can-sustain-ap.md new file mode 100644 index 0000000000..efc27e45d1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-indication-can-sustain-ap.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_INDICATION_CAN_SUSTAIN_AP +author: windows-driver-content +description: WDI_TLV_INDICATION_CAN_SUSTAIN_AP is a TLV that contains the reason for a Can Sustain AP indication. +ms.assetid: 9C7B8E8D-BAF4-4DC7-A020-5B0DEC7CC2FB +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INDICATION_CAN_SUSTAIN_AP Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INDICATION\_CAN\_SUSTAIN\_AP + + +WDI\_TLV\_INDICATION\_CAN\_SUSTAIN\_AP is a TLV that contains the reason for a Can Sustain AP indication. + +## TLV Type + + +0xE7 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The Can Sustain AP reason. See [**WDI\_CAN\_SUSTAIN\_AP\_REASON**](https://msdn.microsoft.com/library/windows/hardware/dn897797) for possible reason values. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[NDIS\_STATUS\_WDI\_INDICATION\_CAN\_SUSTAIN\_AP](https://msdn.microsoft.com/library/windows/hardware/dn925570) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INDICATION_CAN_SUSTAIN_AP%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-indication-stop-ap.md b/windows-driver-docs-pr/network/wdi-tlv-indication-stop-ap.md new file mode 100644 index 0000000000..14724937e3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-indication-stop-ap.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_INDICATION_STOP_AP +author: windows-driver-content +description: WDI_TLV_INDICATION_STOP_AP is a TLV that contains the reason for a Stop AP indication. +ms.assetid: 49FA6AF6-68BE-437B-9715-5090F52F0109 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INDICATION_STOP_AP Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INDICATION\_STOP\_AP + + +WDI\_TLV\_INDICATION\_STOP\_AP is a TLV that contains the reason for a Stop AP indication. + +## TLV Type + + +0xE6 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|--------------------------------------------------------------------------------------------------------------| +| UINT32 | The Stop AP reason. See [**WDI\_STOP\_AP\_REASON**](https://msdn.microsoft.com/library/windows/hardware/dn926116) for possible reason values. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[NDIS\_STATUS\_WDI\_INDICATION\_STOP\_AP](https://msdn.microsoft.com/library/windows/hardware/dn925661) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INDICATION_STOP_AP%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet-pattern-id.md b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet-pattern-id.md new file mode 100644 index 0000000000..fa308603df --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet-pattern-id.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_INDICATION_WAKE_PACKET_PATTERN_ID +author: windows-driver-content +description: WDI_TLV_INDICATION_WAKE_PACKET_PATTERN_ID is a TLV that contains the ID of the pattern that matches a wake packet. +ms.assetid: 3E1D4CC4-0369-4C1F-94C6-AFC34C861E0D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INDICATION_WAKE_PACKET_PATTERN_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INDICATION\_WAKE\_PACKET\_PATTERN\_ID + + +WDI\_TLV\_INDICATION\_WAKE\_PACKET\_PATTERN\_ID is a TLV that contains the ID of the pattern that matches a wake packet. + +## TLV Type + + +0xB0 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The ID of the pattern that matches the wake packet. The ID is defined when the pattern is added with [OID\_WDI\_SET\_ADD\_WOL\_PATTERN](https://msdn.microsoft.com/library/windows/hardware/dn925858). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INDICATION_WAKE_PACKET_PATTERN_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet.md b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet.md new file mode 100644 index 0000000000..ba9dcfd0ef --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-packet.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_INDICATION_WAKE_PACKET +author: windows-driver-content +description: WDI_TLV_INDICATION_WAKE_PACKET is a TLV that contains a wake packet for NDIS_STATUS_WDI_INDICATION_WAKE_REASON. When the wake reason is WDI_WAKE_REASON_CODE PACKET, the status must include the wake packet encapsulated in a WDI_TLV_INDICATION_WAKE_PACKET. +ms.assetid: 3C566FED-4594-403F-93D4-1CA6F2F655F9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INDICATION_WAKE_PACKET Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INDICATION\_WAKE\_PACKET + + +WDI\_TLV\_INDICATION\_WAKE\_PACKET is a TLV that contains a wake packet for [NDIS\_STATUS\_WDI\_INDICATION\_WAKE\_REASON](https://msdn.microsoft.com/library/windows/hardware/dn925669). When the wake reason is WDI\_WAKE\_REASON\_CODE PACKET, the status must include the wake packet encapsulated in a WDI\_TLV\_INDICATION\_WAKE\_PACKET. + +## TLV Type + + +0x9D + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-----------------------------------------------------------------------------------------------------------------------------------| +| UINT8\[\] | The wake packet. The size is the size of the flat memory version of the packet that will be indicated in the normal receive path. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INDICATION_WAKE_PACKET%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-indication-wake-reason.md b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-reason.md new file mode 100644 index 0000000000..b0b0c13123 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-indication-wake-reason.md @@ -0,0 +1,89 @@ +--- +title: WDI_TLV_INDICATION_WAKE_REASON +author: windows-driver-content +description: WDI_TLV_INDICATION_WAKE_REASON is a TLV that contains a wake reason for NDIS_STATUS_WDI_INDICATION_WAKE_REASON. +ms.assetid: 3D3F93EA-4733-44FC-9CB3-721F0552F3E2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INDICATION_WAKE_REASON Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INDICATION\_WAKE\_REASON + + +WDI\_TLV\_INDICATION\_WAKE\_REASON is a TLV that contains a wake reason for [NDIS\_STATUS\_WDI\_INDICATION\_WAKE\_REASON](https://msdn.microsoft.com/library/windows/hardware/dn925669). + +## TLV Type + + +0x9C + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|----------------------------| +| UINT32 | Specifies the wake reason. | + +  + +Valid wake reason values are: + +| Wake reason | Value | Description | +|---------------------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------| +| WDI\_WAKE\_REASON\_CODE\_PACKET | 0x0001 | A received packet matches the wake pattern. | +| WDI\_WAKE\_REASON\_CODE\_MEDIA\_DISCONNECT | 0x0002 | Media disconnection. | +| WDI\_WAKE\_REASON\_CODE\_MEDIA\_CONNECT | 0x0003 | Media connection. | +| WDI\_WAKE\_REASON\_CODE\_NLO\_DISCOVERY | 0x1000 | NLO discovery. | +| WDI\_WAKE\_REASON\_CODE\_AP\_ASSOCIATION\_LOST | 0x1001 | Access point association lost. | +| WDI\_WAKE\_REASON\_CODE\_GTK\_HANDSHAKE\_ERROR | 0x1002 | GTK handshake error. | +| WDI\_WAKE\_REASON\_CODE\_4WAY\_HANDSHAKE\_REQUEST | 0x1003 | 4-Way Handshake request. | +| WDI\_WAKE\_REASON\_CODE\_EAPID\_REQUEST | 0x1004 | Reserved for future use. | +| WDI\_WAKE\_ REASON \_CODE\_INCOMING\_M1 | 0x1005 | Use WDI\_WAKE\_REASON\_CODE\_4WAY\_HANDSHAKE\_REQUEST instead. | +| WDI\_WAKE\_REASON\_CODE\_FIRMWARE\_STALLED | 0x1010 | Firmware hang is detected (for example, by the watchdog timer) and wake logic is still functioning to wake the host. | +| WDI\_WAKE\_REASON\_CODE\_GTK\_HANDSHAKE\_REQUEST | 0x1020 | Group Key rekey request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INDICATION_WAKE_REASON%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-interface-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-interface-attributes.md new file mode 100644 index 0000000000..6efffd2959 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-interface-attributes.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_INTERFACE_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_INTERFACE_ATTRIBUTES is a TLV that contains the attributes of an interface. +ms.assetid: A36AC0A7-6F5B-4461-841D-3B4C19BD49EB +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INTERFACE_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INTERFACE\_ATTRIBUTES + + +WDI\_TLV\_INTERFACE\_ATTRIBUTES is a TLV that contains the attributes of an interface. + +## TLV Type + + +0x21 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_INTERFACE\_CAPABILITIES**](wdi-tlv-interface-capabilities.md) | | | The capabilities of the interface. | +| [**WDI\_TLV\_FIRMWARE\_VERSION**](wdi-tlv-firmware-version.md) | | | An ASCII string that specifies the firmware version. | +| [**WDI\_TLV\_IHV\_NON\_WDI\_OIDS\_LIST**](wdi-tlv-ihv-non-wdi-oids-list.md) | | X | List of non-WDI OIDs that the adapter wants to advertise to the operating system. The adapter should not assume that the operating system has already filtered non-WDI OIDs to match this list. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INTERFACE_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-interface-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-interface-capabilities.md new file mode 100644 index 0000000000..542f111f74 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-interface-capabilities.md @@ -0,0 +1,127 @@ +--- +title: WDI_TLV_INTERFACE_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_INTERFACE_CAPABILITIES is a TLV that contains the capabilities of the Wi-Fi interface. +ms.assetid: 308331DD-FEEB-4C49-BEBD-117AE58D4792 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_INTERFACE_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_INTERFACE\_CAPABILITIES + + +WDI\_TLV\_INTERFACE\_CAPABILITIES is a TLV that contains the capabilities of the Wi-Fi interface. + +## TLV Type + + +0xF + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +Type +Description +UINT32 +The maximum transfer unit (MTU) size. +UINT32 +The multicast list size for the adapter. +UINT16 +The backfill size in bytes. This value cannot be greater than 256 bytes. +[**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) +The permanent MAC address for the adapter. If the device supports multiple permanent MAC addresses, the first MAC address that will be used by the device should be returned. +UINT32 +The maximum supported send rate for this adapter in kbps. +UINT32 +The maximum supported receive rate for this adapter in kbps. +UINT8 +Specifies whether the radio is enabled by hardware. Valid values are 0 (disabled) and 1 (enabled). +UINT8 +Specifies whether they radio is enabled by software. Valid values are 0 (disabled) and 1 (enabled). +UINT8 +Specifies whether the interface supports PLR. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies whether the interface supports FLR. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies whether sending and receiving action frames is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 +The supported number of RX spatial streams. +UINT8 +The supported number of TX spatial streams. +UINT8 +The number of channels that the adapter can work in concurrently, regardless of operation mode. +UINT8 +Specifies whether antenna diversity is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies whether eCSA is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies whether the adapter supports MAC address randomization. Valid values are 0 (not supported) and 1 (supported). +[**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) +A bit mask that specifies for each address bit whether it can be randomized (0) or should keep the same value as the permanent address (1). The default is all zeros. +[**WDI\_BLUETOOTH\_COEXISTENCE\_SUPPORT**](https://msdn.microsoft.com/library/windows/hardware/dn897795) (UINT32) +The supported level of Wi-Fi - Bluetooth coexistence. +UINT8 +Specifies non-WDI OID support. Valid values are: +- 0 : Not supported. OIDs that the Microsoft component does not understand are not forwarded to the adapter. +- 1 : Supported. OIDs that the Microsoft component does not understand are forwarded to the adapter. + +These OIDs will not contain WDI headers. To identify the adapter's port that the request came in on, use NdisPortNumber in the NDIS\_OID\_REQUEST and match it to the one in [WDI\_TASK\_CREATE\_PORT](https://msdn.microsoft.com/library/windows/hardware/dn925949). + +UINT8 +Specifies whether the Fast Transition is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies whether Mu-MIMO is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 +Specifies if the interface cannot support Miracast Sink. Valid values are 0 (supported) and 1 (not supported). +UINT8 +Specifies if 802.11v BSS transition is supported. Valid values are 0 (not supported) and 1 (supported). +UINT8 + +Added in Windows 10, version 1607, WDI version 1.0.21. + +Specifies if the device supports IP docking capability. Valid values are 0 (not supported) and 1 (supported). +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_INTERFACE_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ipv4-checksum-offload.md b/windows-driver-docs-pr/network/wdi-tlv-ipv4-checksum-offload.md new file mode 100644 index 0000000000..0e17d272f1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ipv4-checksum-offload.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_IPV4_CHECKSUM_OFFLOAD +author: windows-driver-content +description: WDI_TLV_IPV4_CHECKSUM_OFFLOAD is a TLV that contains checksum offload capabilities for IPv4. +ms.assetid: FCC5880E-4323-4A24-98C6-CE7C84D03C16 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IPV4_CHECKSUM_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IPV4\_CHECKSUM\_OFFLOAD + + +WDI\_TLV\_IPV4\_CHECKSUM\_OFFLOAD is a TLV that contains checksum offload capabilities for IPv4. + +## TLV Type + + +0xCF + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------| +| [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_TX\_PARAMETERS**](wdi-tlv-checksum-offload-v4-tx-parameters.md) | | | Parameters for Tx checksum offload for IPv4. | +| [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V4\_RX\_PARAMETERS**](wdi-tlv-checksum-offload-v4-rx-parameters.md) | | | Parameters for Rx checksum offload for IPv4. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IPV4_CHECKSUM_OFFLOAD%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ipv4-lso-v2.md b/windows-driver-docs-pr/network/wdi-tlv-ipv4-lso-v2.md new file mode 100644 index 0000000000..29d9d1a4e5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ipv4-lso-v2.md @@ -0,0 +1,97 @@ +--- +title: WDI_TLV_IPV4_LSO_V2 (0xD3) +author: windows-driver-content +description: WDI_TLV_IPV4_LSO_V2 is a TLV that contains Large Send Offload V2 parameters for IPv4. +ms.assetid: 912D5F1B-260F-43B3-93F6-3C38E9D7F1E5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IPV4_LSO_V2 (0xD3) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IPV4\_LSO\_V2 (0xD3) + + +WDI\_TLV\_IPV4\_LSO\_V2 is a TLV that contains Large Send Offload V2 parameters for IPv4. + +## TLV Type + + +0xD3 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation type. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32The maximum offload size. Specified by the maximum number of bytes of TCP user data per packet.
UINT32The minimum segment count. Specified by the minimum number of segments that should be present after segmentation.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IPV4_LSO_V2%20%280xD3%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ipv6-checksum-offload.md b/windows-driver-docs-pr/network/wdi-tlv-ipv6-checksum-offload.md new file mode 100644 index 0000000000..a4ca67b4c2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ipv6-checksum-offload.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_IPV6_CHECKSUM_OFFLOAD +author: windows-driver-content +description: WDI_TLV_IPV6_CHECKSUM_OFFLOAD is a TLV that contains checksum offload capabilities for IPv6. +ms.assetid: 878471F5-8118-4D0A-87BC-E44DE7A713DF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IPV6_CHECKSUM_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IPV6\_CHECKSUM\_OFFLOAD + + +WDI\_TLV\_IPV6\_CHECKSUM\_OFFLOAD is a TLV that contains checksum offload capabilities for IPv6. + +## TLV Type + + +0xD0 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------| +| [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_TX\_PARAMETERS**](wdi-tlv-checksum-offload-v6-tx-parameters.md) | | | Parameters for Tx checksum offload for IPv6. | +| [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_V6\_RX\_PARAMETERS**](wdi-tlv-checksum-offload-v6-rx-parameters.md) | | | Parameters for Rx checksum offload for IPv6. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IPV6_CHECKSUM_OFFLOAD%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ipv6-lso-v2.md b/windows-driver-docs-pr/network/wdi-tlv-ipv6-lso-v2.md new file mode 100644 index 0000000000..eda90dbed3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ipv6-lso-v2.md @@ -0,0 +1,107 @@ +--- +title: WDI_TLV_IPV6_LSO_V2 (0xD4) +author: windows-driver-content +description: WDI_TLV_IPV6_LSO_V2 is a TLV that contains Large Send Offload V2 parameters for IPv6. +ms.assetid: 898257D1-405A-46A3-AE63-26DFA8C1FAAC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_IPV6_LSO_V2 (0xD4) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_IPV6\_LSO\_V2 (0xD4) + + +WDI\_TLV\_IPV6\_LSO\_V2 is a TLV that contains Large Send Offload V2 parameters for IPv6. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xD4 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Encapsulation type. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32The maximum offload size. Specified by the maximum number of bytes of TCP user data per packet.
UINT32The minimum segment count. Specified by the minimum number of segments that should be present after segmentation.
UINT32Specifies if offload of checksum of packets with IP extension headers is supported.
UINT32Specifies if offload of checksum with TCP options is supported.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_IPV6_LSO_V2%20%280xD4%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-link-quality-bar-map.md b/windows-driver-docs-pr/network/wdi-tlv-link-quality-bar-map.md new file mode 100644 index 0000000000..4ce8db1473 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-link-quality-bar-map.md @@ -0,0 +1,85 @@ +--- +title: WDI_TLV_LINK_QUALITY_BAR_MAP +author: windows-driver-content +description: WDI_TLV_LINK_QUALITY_BAR_MAP is a TLV that contains the mapping of signal quality to Wi-Fi signal strength bars. +ms.assetid: 35E073F4-D372-466A-98FF-0AAB1695284E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_LINK_QUALITY_BAR_MAP Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_LINK\_QUALITY\_BAR\_MAP + + +WDI\_TLV\_LINK\_QUALITY\_BAR\_MAP is a TLV that contains the mapping of signal quality to Wi-Fi signal strength bars. + +## TLV Type + + +0xD8 + +## Length + + +The size (in bytes) of the array of WDI\_LINK\_QUALITY\_BAR\_MAP\_PARAMETERS elements. The array must contain 1 or more elements. + +**Note**  WDI\_LINK\_QUALITY\_BAR\_MAP\_PARAMETERS is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|----------------------------------------------|-----------------------------------------------------| +| WDI\_LINK\_QUALITY\_BAR\_MAP\_PARAMETERS\[\] | An array of signal strength bar mapping parameters. | + +  + +WDI\_LINK\_QUALITY\_BAR\_MAP\_PARAMETERS consists of the following elements. + +| Type | Description | +|-------|------------------------------------------------------------------------------| +| UINT8 | The lower limit link quality (0-100) for the current signal strength bar. | +| UINT8 | The upper limit of link quality (0-100) for the current signal strength bar. | +| UINT8 | The signal strength bar number. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Dot11wdi.h
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_LINK_QUALITY_BAR_MAP%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-link-state-change-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-link-state-change-parameters.md new file mode 100644 index 0000000000..45020a6f24 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-link-state-change-parameters.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_LINK_STATE_CHANGE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_LINK_STATE_CHANGE_PARAMETERS is a TLV that contains link state change parameters for NDIS_STATUS_WDI_INDICATION_LINK_STATE_CHANGE. +ms.assetid: 808C2E69-B713-41A3-AFB9-7441D2A96867 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_LINK_STATE_CHANGE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_LINK\_STATE\_CHANGE\_PARAMETERS + + +WDI\_TLV\_LINK\_STATE\_CHANGE\_PARAMETERS is a TLV that contains link state change parameters for [NDIS\_STATUS\_WDI\_INDICATION\_LINK\_STATE\_CHANGE](https://msdn.microsoft.com/library/windows/hardware/dn925638). + +## TLV Type + + +0x56 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the MAC address of the remote peer. | +| UINT32 | Specifies the current TX link speed. This is a value, in kilobits per second, that is the current TX link speed for this virtualized port. The conversion is 1 kbps = 1000 bps. | +| UINT32 | Specifies the current RX link speed. This is a value, in kilobits per second, that is the current RX link speed for this virtualized port. The conversion is 1 kbps = 1000 bps. | +| UINT8 | Specifies the current link quality. This is a value between 0 and 100 that is the current link quality for this virtualized port. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_LINK_STATE_CHANGE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-low-latency-connection-quality-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-low-latency-connection-quality-parameters.md new file mode 100644 index 0000000000..68fa16e6c1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-low-latency-connection-quality-parameters.md @@ -0,0 +1,79 @@ +--- +title: WDI_TLV_LOW_LATENCY_CONNECTION_QUALITY_PARAMETERS +author: windows-driver-content +description: WDI_TLV_LOW_LATENCY_CONNECTION_QUALITY_PARAMETERS is a TLV that contains low latency connection quality parameters. +ms.assetid: F6C26267-AC6F-4810-913B-46DA99498BE2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_LOW_LATENCY_CONNECTION_QUALITY_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_LOW\_LATENCY\_CONNECTION\_QUALITY\_PARAMETERS + + +WDI\_TLV\_LOW\_LATENCY\_CONNECTION\_QUALITY\_PARAMETERS is a TLV that contains low latency connection quality parameters. + +## TLV Type + + +0xF6 + +## Length + + +The size (in bytes) of the array of all contained elements. + +## Values + + +| Type | Description | +|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies the maximum number of milliseconds that the port can be on a different channel during Active Scan or other multi-channel operations. The only instance in which this off-channel can be higher is if the adapter needs to do a passive scan. | +| UINT8 | Specifies the link quality threshold for [NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED](https://msdn.microsoft.com/library/windows/hardware/dn925648). When the link quality is below this threshold, it is acceptable for the adapter to send NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_SET\_CONNECTION\_QUALITY](https://msdn.microsoft.com/library/windows/hardware/dn925927) + +[NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED](https://msdn.microsoft.com/library/windows/hardware/dn925648) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_LOW_LATENCY_CONNECTION_QUALITY_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-lso-v1-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-lso-v1-capabilities.md new file mode 100644 index 0000000000..4b346b5823 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-lso-v1-capabilities.md @@ -0,0 +1,107 @@ +--- +title: WDI_TLV_LSO_V1_CAPABILITIES (0xCC) +author: windows-driver-content +description: WDI_TLV_LSO_V1_CAPABILITIES is a TLV that contains Large Send Offload V1 capabilities. +ms.assetid: 22C5778A-F551-4931-A19C-7AA399221B3D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_LSO_V1_CAPABILITIES (0xCC) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_LSO\_V1\_CAPABILITIES (0xCC) + + +WDI\_TLV\_LSO\_V1\_CAPABILITIES is a TLV that contains Large Send Offload V1 capabilities. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). + +## TLV Type + + +0xCC + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32The encapsulation type. Valid values are: +
    +
  • WDI_ENCAPSULATION_IEEE_802_11
  • +
UINT32The maximum offload size. Specified by the maximum number of bytes of TCP user data per packet.
UINT32The minimum number of segments that a large TCP packet must be divisible by before the transport can offload it to the hardware for segmentation.
UINT32Specifies whether or not TCP options are supported for this offload.
UINT32Specifies whether or not IP options are supported for this offload.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_LSO_V1_CAPABILITIES%20%280xCC%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-lso-v2-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-lso-v2-capabilities.md new file mode 100644 index 0000000000..17134c89f0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-lso-v2-capabilities.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_LSO_V2_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_LSO_V2_CAPABILITIES is a TLV that contains Large Send Offload V2 capabilities. +ms.assetid: 6F7C83BA-B004-431F-90AF-AD7DE1B13546 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_LSO_V2_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_LSO\_V2\_CAPABILITIES + + +WDI\_TLV\_LSO\_V2\_CAPABILITIES is a TLV that contains Large Send Offload V2 capabilities. + +## TLV Type + + +0xCD + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------|--------------------------------|----------|----------------------------------------------| +| [**WDI\_TLV\_IPV4\_LSO\_V2**](wdi-tlv-ipv4-lso-v2.md) | | | Large Send Offload V2 capabilities for IPv4. | +| [**WDI\_TLV\_IPV6\_LSO\_V2**](wdi-tlv-ipv6-lso-v2.md) | | | Large Send Offload V2 capabilities for IPv6. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_LSO_V2_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-mac-statistics.md b/windows-driver-docs-pr/network/wdi-tlv-mac-statistics.md new file mode 100644 index 0000000000..c87c70aa27 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-mac-statistics.md @@ -0,0 +1,141 @@ +--- +title: WDI_TLV_MAC_STATISTICS +author: windows-driver-content +description: WDI_TLV_MAC_STATISTICS is a TLV that contains per-peer MAC statistics for OID_WDI_GET_STATISTICS. +ms.assetid: 47ABF170-76D7-4F17-BA92-56E1FEFF729D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_MAC_STATISTICS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_MAC\_STATISTICS + + +WDI\_TLV\_MAC\_STATISTICS is a TLV that contains per-peer MAC statistics for [OID\_WDI\_GET\_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/dn925850). + +## TLV Type + + +0xA6 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
[WDI_MAC_ADDRESS](https://msdn.microsoft.com/library/windows/hardware/dn926071)The MAC address of the peer that these counts are set for. For multicast and broadcast packets, this value is set to FF-FF-FF-FF-FF-FF-FF.
UINT64The number of MSDU packets and MMPDU frames that the IEEE MAC layer of the 802.11 station successfully transmitted.
UINT64The number of MSDU packets and MMPDU frames that the IEEE MAC layer of the 802.11 station successfully received. This member should not be incremented for received packets that failed cipher decryption or MIC validation.
UINT64The number of unencrypted received MPDU frames that the MAC layer discarded when the IEEE 802.11 dot11ExcludeUnencrypted management information base (MIB) object is enabled. +

For more information about this MIB object, see [OID_DOT11_EXCLUDE_UNENCRYPTED](https://msdn.microsoft.com/library/windows/hardware/ff569365). MPDU frames are considered unencrypted when the Protected Frame subfield of the Frame Control field in the IEEE 802.11 MAC header is set to zero.

UINT64The number of received MSDU packets that the 802.11 station discarded because of MIC failures.
UINT64The number of received MPDU frames that the 802.11 station discarded because of the TKIP replay protection procedure.
UINT64The number of encrypted MPDU frames that the 802.11 station failed to decrypt because of a TKIP ICV error.
UINT64The number of received MPDU frames that the 802.11 discarded because of an invalid AES-CCMP format.
UINT64The number of received MPDU frames that the 802.11 station discarded because of the AES-CCMP replay protection procedure.
UINT64The number of received MPDU frames that the 802.11 station discarded because of errors detected by the AES-CCMP decryption algorithm.
UINT64The number of encrypted MPDU frames received for which a WEP decryption key was not available on the 802.11 station.
UINT64The number of encrypted MPDU frames that the 802.11 station failed to decrypt because of a WEP ICV error.
UINT64The number of received encrypted packets that the 802.11 station successfully decrypted. +

For the WEP and TKIP cipher algorithms, the port must increment this counter for each received encrypted MPDU that was successfully decrypted. For the AES-CCMP cipher algorithm, the port must increment this counter on each received encrypted MSDU packet that was successfully decrypted.

UINT64The number of encrypted packets that the 802.11 station failed to decrypt. +

For the WEP and TKIP cipher algorithms, the port must increment this counter for each received encrypted MPDU that was not successfully decrypted. For the AES-CCMP cipher algorithm, the port must increment this counter on each received encrypted MSDU packet that was not successfully decrypted. The port must not increment this counter for packets that are decrypted successfully, but are discarded for other reasons. For example, the port must not increment this counter for packets that are discarded because of TKIP MIC failures or TKIP/CCMP replays.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_MAC_STATISTICS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-multicast-cipher-algo-list.md b/windows-driver-docs-pr/network/wdi-tlv-multicast-cipher-algo-list.md new file mode 100644 index 0000000000..48da741d1e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-multicast-cipher-algo-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_MULTICAST_CIPHER_ALGO_LIST +author: windows-driver-content +description: WDI_TLV_MULTICAST_CIPHER_ALGO_LIST is a TLV that contains a list of multicast cipher algorithms. +ms.assetid: 55CDD295-6BDA-4F3A-B01F-FC9D5FB38355 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_MULTICAST_CIPHER_ALGO_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_MULTICAST\_CIPHER\_ALGO\_LIST + + +WDI\_TLV\_MULTICAST\_CIPHER\_ALGO\_LIST is a TLV that contains a list of multicast cipher algorithms. + +## TLV Type + + +0x3D + +## Length + + +The size (in bytes) of the array of [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) structures. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------------------------------------------------------------|------------------------------------------| +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802)\[\] | An array of multicast cipher algorithms. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_MULTICAST_CIPHER_ALGO_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-multicast-data-algorithm-list.md b/windows-driver-docs-pr/network/wdi-tlv-multicast-data-algorithm-list.md new file mode 100644 index 0000000000..b6f9ed2042 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-multicast-data-algorithm-list.md @@ -0,0 +1,84 @@ +--- +title: WDI_TLV_MULTICAST_DATA_ALGORITHM_LIST +author: windows-driver-content +description: WDI_TLV_MULTICAST_DATA_ALGORITHM_LIST is a TLV that contains an array of multicast data algorithm pairs. +ms.assetid: BF07170E-CF4E-4E93-85E1-3276E414BDD9 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_MULTICAST_DATA_ALGORITHM_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_MULTICAST\_DATA\_ALGORITHM\_LIST + + +WDI\_TLV\_MULTICAST\_DATA\_ALGORITHM\_LIST is a TLV that contains an array of multicast data algorithm pairs. + +## TLV Type + + +0x14 + +## Length + + +The size (in bytes) of the array of WDI\_ALGO\_PAIRS elements. The array must contain 1 or more elements. + +**Note**  WDI\_ALGO\_PAIRS is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|----------------------|--------------------------------------------------------| +| WDI\_ALGO\_PAIRS\[\] | An array of authentication and cipher algorithm pairs. | + +  + +WDI\_ALGO\_PAIRS consists of the following elements. + +| Type | Description | +|-------|-------------------------------------------------------------------------------------------------| +| UINT8 | Authentication algorithm as defined in [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792). | +| UINT8 | Cipher algorithm as defined in [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_MULTICAST_DATA_ALGORITHM_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-multicast-list.md b/windows-driver-docs-pr/network/wdi-tlv-multicast-list.md new file mode 100644 index 0000000000..de1610bc91 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-multicast-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_MULTICAST_LIST +author: windows-driver-content +description: WDI_TLV_MULTICAST_LIST is a TLV that contains an array of multicast MAC addresses. +ms.assetid: 5023557A-1BC5-4A4E-A77C-20353C0CA3FD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_MULTICAST_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_MULTICAST\_LIST + + +WDI\_TLV\_MULTICAST\_LIST is a TLV that contains an array of multicast MAC addresses. + +## TLV Type + + +0x6A + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|--------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | An array of multicast MAC addresses. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_MULTICAST_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-multicast-mgmt-algorithm-list.md b/windows-driver-docs-pr/network/wdi-tlv-multicast-mgmt-algorithm-list.md new file mode 100644 index 0000000000..2aacd3f120 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-multicast-mgmt-algorithm-list.md @@ -0,0 +1,86 @@ +--- +title: WDI_TLV_MULTICAST_MGMT_ALGORITHM_LIST +author: windows-driver-content +description: WDI_TLV_MULTICAST_MGMT_ALGORITHM_LIST is a TLV that contains an array of multicast management algorithm pairs. +ms.assetid: 96EAD5FE-71C7-4B3E-BB52-06FA50F375D8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_MULTICAST_MGMT_ALGORITHM_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_MULTICAST\_MGMT\_ALGORITHM\_LIST + + +WDI\_TLV\_MULTICAST\_MGMT\_ALGORITHM\_LIST is a TLV that contains an array of multicast management algorithm pairs. + +## TLV Type + + +0x15 + +## Length + + +The size (in bytes) of the array of WDI\_ALGO\_PAIRS elements. The array must contain 1 or more elements. + +**Note**  WDI\_ALGO\_PAIRS is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +The size (in bytes) of the array of algorithm pairs. + +## Values + + +| Type | Description | +|----------------------|--------------------------------------------------------| +| WDI\_ALGO\_PAIRS\[\] | An array of authentication and cipher algorithm pairs. | + +  + +WDI\_ALGO\_PAIRS consists of the following elements. + +| Type | Description | +|-------|-------------------------------------------------------------------------------------------------| +| UINT8 | Authentication algorithm as defined in [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792). | +| UINT8 | Cipher algorithm as defined in [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_MULTICAST_MGMT_ALGORITHM_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-neighbor-report-entry.md b/windows-driver-docs-pr/network/wdi-tlv-neighbor-report-entry.md new file mode 100644 index 0000000000..774557f311 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-neighbor-report-entry.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_NEIGHBOR_REPORT_ENTRY +author: windows-driver-content +description: WDI_TLV_NEIGHBOR_REPORT_ENTRY is a TLV that contains a neighbor report. +ms.assetid: 23A0AA84-3EDA-4D6F-9140-2361C0CF55AA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_NEIGHBOR_REPORT_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_NEIGHBOR\_REPORT\_ENTRY + + +WDI\_TLV\_NEIGHBOR\_REPORT\_ENTRY is a TLV that contains a neighbor report. + +## TLV Type + + +0x123 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------| +| [**WDI\_TLV\_BSSID**](wdi-tlv-bssid.md) | | | The BSSID of the AP in the neighbor report. | +| [**WDI\_TLV\_BSSID\_INFO**](wdi-tlv-bssid-info.md) | | | The BSSID information of the AP. | +| [**WDI\_TLV\_OPERATING\_CLASS**](wdi-tlv-operating-class.md) | | | The operating class of the AP indicated by this BSSID. | +| [**WDI\_TLV\_CHANNEL\_NUMBER**](wdi-tlv-channel-number.md) | | | The last known operating channel of the AP indicated by this BSSID. | +| [**WDI\_TLV\_PHY\_TYPE**](wdi-tlv-phy-type.md) | | | The PHY type of the AP indicated by this BSSID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_NEIGHBOR_REPORT_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-config.md b/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-config.md new file mode 100644 index 0000000000..918ef04fc2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-config.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_NETWORK_LIST_OFFLOAD_CONFIG +author: windows-driver-content +description: WDI_TLV_NETWORK_LIST_OFFLOAD_CONFIG is a TLV that contains Network List Offload (NLO) configuration. +ms.assetid: 8805B31C-7601-4045-AD52-21B91E2D3722 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_NETWORK_LIST_OFFLOAD_CONFIG Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_CONFIG + + +WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_CONFIG is a TLV that contains Network List Offload (NLO) configuration. + +## TLV Type + + +0xDA + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------------------------------| +| UINT32 | Reserved field. | +| UINT32 | The delay (in seconds) before the scan schedule starts. | +| UINT32 | The period (in seconds) to scan in the first phase. | +| UINT32 | The number of iterations in the fast scan phase. | +| UINT32 | The period (in seconds) to scan in the slow scan phase. This phase lasts indefinitely until a new NLO command is set. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_NETWORK_LIST_OFFLOAD_CONFIG%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-parameters.md new file mode 100644 index 0000000000..e0cac6bb62 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-network-list-offload-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_NETWORK_LIST_OFFLOAD_PARAMETERS +author: windows-driver-content +description: WDI_TLV_NETWORK_LIST_OFFLOAD_PARAMETERS is a TLV that contains Network List Offload (NLO) parameters for OID_WDI_SET_NETWORK_LIST_OFFLOAD. +ms.assetid: B8DD3BB6-DB90-4500-9BD5-252230F4BAAD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_NETWORK_LIST_OFFLOAD_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_PARAMETERS + + +WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_PARAMETERS is a TLV that contains Network List Offload (NLO) parameters for [OID\_WDI\_SET\_NETWORK\_LIST\_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/dn925933). + +## TLV Type + + +0x59 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_NETWORK\_LIST\_OFFLOAD\_CONFIG**](wdi-tlv-network-list-offload-config.md) | | | Specifies NLO configuration. | +| [**WDI\_TLV\_SSID\_OFFLOAD**](wdi-tlv-ssid-offload.md) | X | X | Specifies offload SSIDs. When this element is absent, the firmware should stop NLO scanning. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_NETWORK_LIST_OFFLOAD_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-network-offload-channels.md b/windows-driver-docs-pr/network/wdi-tlv-network-offload-channels.md new file mode 100644 index 0000000000..d7dcedd0ca --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-network-offload-channels.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_NETWORK_OFFLOAD_CHANNELS +author: windows-driver-content +description: WDI_TLV_NETWORK_OFFLOAD_CHANNELS is an unused TLV. +ms.assetid: D1F376FE-4DA8-4154-B9C4-14BCABDE4D74 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_NETWORK_OFFLOAD_CHANNELS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_NETWORK\_OFFLOAD\_CHANNELS + + +WDI\_TLV\_NETWORK\_OFFLOAD\_CHANNELS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_NETWORK_OFFLOAD_CHANNELS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-next-dialog-token.md b/windows-driver-docs-pr/network/wdi-tlv-next-dialog-token.md new file mode 100644 index 0000000000..f129650f17 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-next-dialog-token.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_NEXT_DIALOG_TOKEN +author: windows-driver-content +description: WDI_TLV_NEXT_DIALOG_TOKEN is a TLV that contains the dialog token to be used in the next Action frame. +ms.assetid: B11331CB-50D3-4A3B-93A5-359ABD918E70 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_NEXT_DIALOG_TOKEN Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_NEXT\_DIALOG\_TOKEN + + +WDI\_TLV\_NEXT\_DIALOG\_TOKEN is a TLV that contains the dialog token to be used in the next Action frame. + +## TLV Type + + +0xE1 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-------------------------------------------------------| +| UINT8 | The dialog token to be used in the next Action frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_GET\_NEXT\_ACTION\_FRAME\_DIALOG\_TOKEN](https://msdn.microsoft.com/library/windows/hardware/dn925844) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_NEXT_DIALOG_TOKEN%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-operating-class.md b/windows-driver-docs-pr/network/wdi-tlv-operating-class.md new file mode 100644 index 0000000000..57490009a6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-operating-class.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_OPERATING_CLASS +author: windows-driver-content +description: WDI_TLV_OPERATING_CLASS is a TLV that contains the frequency band for a channel. +ms.assetid: 58F2D174-EB47-4163-AFFD-C119E5E7CE53 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_OPERATING_CLASS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_OPERATING\_CLASS + + +WDI\_TLV\_OPERATING\_CLASS is a TLV that contains the frequency band for a channel. + +## TLV Type + + +0xFA + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-----------------------------------| +| UINT8 | The frequency band for a channel. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_OPERATING_CLASS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-operation-mode.md b/windows-driver-docs-pr/network/wdi-tlv-operation-mode.md new file mode 100644 index 0000000000..7a383aab94 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-operation-mode.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_OPERATION_MODE +author: windows-driver-content +description: WDI_TLV_OPERATION_MODE is a TLV that contains the desired operation mode. +ms.assetid: CF5D9148-E50B-4F39-B37C-2495DE9A1488 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_OPERATION_MODE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_OPERATION\_MODE + + +WDI\_TLV\_OPERATION\_MODE is a TLV that contains the desired operation mode. + +## TLV Type + + +0x95 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|----------------------------------------------------------------------------------------------------| +| UINT32 | The desired operation mode, as defined in [**WDI\_OPERATION\_MODE**](https://msdn.microsoft.com/library/windows/hardware/dn926085). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_OPERATION_MODE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-device-context.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-device-context.md new file mode 100644 index 0000000000..75c09829be --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-device-context.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_P2P_ACTION_FRAME_DEVICE_CONTEXT +author: windows-driver-content +description: WDI_TLV_P2P_ACTION_FRAME_DEVICE_CONTEXT is an unused TLV. +ms.assetid: 7CF83378-BBCA-4A51-ACDE-8F52FC825C5D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ACTION_FRAME_DEVICE_CONTEXT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ACTION\_FRAME\_DEVICE\_CONTEXT + + +WDI\_TLV\_P2P\_ACTION\_FRAME\_DEVICE\_CONTEXT is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ACTION_FRAME_DEVICE_CONTEXT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-ies.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-ies.md new file mode 100644 index 0000000000..69da3feb85 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-ies.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_ACTION_FRAME_IES +author: windows-driver-content +description: WDI_TLV_P2P_ACTION_FRAME_IES is a TLV that contains action frame IEs. +ms.assetid: 7F5DD866-AD7D-4E3E-B352-78FAE4AFD995 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ACTION_FRAME_IES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ACTION\_FRAME\_IES + + +WDI\_TLV\_P2P\_ACTION\_FRAME\_IES is a TLV that contains action frame IEs. + +## TLV Type + + +0x90 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the set of IEs that are sent to the remote device. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ACTION_FRAME_IES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-response-parameters.md new file mode 100644 index 0000000000..cc89923590 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-action-frame-response-parameters.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_ACTION_FRAME_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_ACTION_FRAME_RESPONSE_PARAMETERS is a TLV that contains Wi-Fi Direct Action Frame response parameters. +ms.assetid: 2DFF00A6-FDE2-43EF-93C2-EEA3DBC00D52 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ACTION_FRAME_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ACTION\_FRAME\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_P2P\_ACTION\_FRAME\_RESPONSE\_PARAMETERS is a TLV that contains Wi-Fi Direct Action Frame response parameters. + +## TLV Type + + +0xAD + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_P2P\_ACTION\_FRAME\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926086) | The type of Response Frame to be sent. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The device address of the target peer Wi-Fi Direct device. | +| UINT8 | The Wi-Fi Direct Dialog Token for this transaction. | +| UINT32 | The send timeout. Specifies the maximum time, in milliseconds, to send this action frame. | +| UINT32 | The post-ACK dwell time. Specifies the time to remain on listen channel, in milliseconds, after the incoming packet is acknowledged. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ACTION_FRAME_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-prefix-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-prefix-entry.md new file mode 100644 index 0000000000..a63f9fefb6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-prefix-entry.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY is a TLV that contains a Wi-Fi Direct advertised prefix entry. +ms.assetid: 484A7784-EDD5-46F0-91E0-060D23ADC0BD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ADVERTISED\_PREFIX\_ENTRY + + +WDI\_TLV\_P2P\_ADVERTISED\_PREFIX\_ENTRY is a TLV that contains a Wi-Fi Direct advertised prefix entry. + +## TLV Type + + +0x110 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) | | | Name of the service, in UTF-8, with a maximum size of 255 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH**](wdi-tlv-p2p-service-name-hash.md) | | | Hash of Service Name. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-service-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-service-entry.md new file mode 100644 index 0000000000..6ddfc0084e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-service-entry.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY is a TLV that contains an advertised service entry. +ms.assetid: C9BBA5D4-EC51-4D03-B997-A95B3168E64F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ADVERTISED\_SERVICE\_ENTRY + + +WDI\_TLV\_P2P\_ADVERTISED\_SERVICE\_ENTRY is a TLV that contains an advertised service entry. + +## TLV Type + + +0xFC + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) | | | Name of the service, in UTF-8, up to 255 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH**](wdi-tlv-p2p-service-name-hash.md) | | | Hash of Service Name. | +| [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) | | X | Service Information for this service. | +| [**WDI\_TLV\_P2P\_SERVICE\_STATUS**](wdi-tlv-p2p-service-status.md) | | | Service Status of this service. | +| [**WDI\_TLV\_P2P\_ADVERTISEMENT\_ID**](wdi-tlv-p2p-advertisement-id.md) | | | An ID that uniquely identifies the service instance. | +| [**WDI\_TLV\_P2P\_CONFIG\_METHODS**](wdi-tlv-p2p-config-methods.md) | | | Configuration methods as defined in [**WDI\_WPS\_CONFIGURATION\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/dn898198). Only PIN display, PIN keypad, and WFDS are applicable. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-services.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-services.md new file mode 100644 index 0000000000..ac6fd169b8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertised-services.md @@ -0,0 +1,111 @@ +--- +title: WDI_TLV_P2P_ADVERTISED_SERVICES +author: windows-driver-content +description: WDI_TLV_P2P_ADVERTISED_SERVICES is a TLV that contains a list of advertised services. +ms.assetid: C210DDF3-0349-4108-82EC-1823F562E5D7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ADVERTISED_SERVICES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ADVERTISED\_SERVICES + + +WDI\_TLV\_P2P\_ADVERTISED\_SERVICES is a TLV that contains a list of advertised services. + +## TLV Type + + +0xEF + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeMultiple TLV instances allowedOptionalDescription

[WDI_TLV_P2P_ADVERTISED_SERVICE_ENTRY](wdi-tlv-p2p-advertised-service-entry.md)

X

X

A list of advertised services.

[WDI_TLV_P2P_ADVERTISED_PREFIX_ENTRY](wdi-tlv-p2p-advertised-prefix-entry.md)

X

X

A list of advertised prefixes that are derived from the list of advertised services.

[WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY](wdi-tlv-p2p-asp2-advertised-service-entry.md)

X

X

Added in Windows 10, version 1607, WDI version 1.0.21.

+

A list of advertised ASP2 services.

[WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR](wdi-tlv-p2p-service-update-indicator.md)

The service update indicator to include in ANQP responses if the driver supports responding to service information discovery ANQP requests.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ADVERTISED_SERVICES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-advertisement-id.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertisement-id.md new file mode 100644 index 0000000000..5f791dfa14 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-advertisement-id.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_ADVERTISEMENT_ID +author: windows-driver-content +description: WDI_TLV_P2P_ADVERTISEMENT_ID is a TLV that contains an ID that uniquely identifies a service instance. +ms.assetid: 04F8200C-54A3-4B2F-9EDF-15E2BBB19201 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ADVERTISEMENT_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ADVERTISEMENT\_ID + + +WDI\_TLV\_P2P\_ADVERTISEMENT\_ID is a TLV that contains an ID that uniquely identifies a service instance. + +## TLV Type + + +0xEA + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|----------------------------------------------------| +| UINT32 | An ID that uniquely identifies a service instance. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ADVERTISEMENT_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-advertised-service-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-advertised-service-entry.md new file mode 100644 index 0000000000..a49f9c45fc --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-advertised-service-entry.md @@ -0,0 +1,82 @@ +--- +title: WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY is a TLV that contains an ASP2 Advertised Service Entry. +ms.assetid: CF7ED750-1987-4784-9E61-516EBBA22B9B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ASP2\_ADVERTISED\_SERVICE\_ENTRY + + +WDI\_TLV\_P2P\_ASP2\_ADVERTISED\_SERVICE\_ENTRY is a TLV that contains an ASP2 Advertised Service Entry. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x12E + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_TYPE**](wdi-tlv-p2p-service-type.md) | | | Service Type of the service (UTF-8), up to 21 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_TYPE\_HASH**](wdi-tlv-p2p-service-type-hash.md) | | | Hash of Service Type. | +| [**WDI\_TLV\_P2P\_INSTANCE\_NAME**](wdi-tlv-p2p-instance-name.md) | | | Instance Type of the service (UTF-8), up to 63 bytes. | +| [**WDI\_TLV\_P2P\_INSTANCE\_NAME\_HASH**](wdi-tlv-p2p-instance-name-hash.md) | | | Hash of "Instance Name, Service Type". | +| [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) | | X | Service Information for the service. | +| [**WDI\_TLV\_P2P\_SERVICE\_STATUS**](wdi-tlv-p2p-service-status.md) | | | Service Status of the service. | +| [**WDI\_TLV\_P2P\_ADVERTISEMENT\_ID**](wdi-tlv-p2p-advertisement-id.md) | | | An ID that uniquely identifies the service instance. | +| [**WDI\_TLV\_P2P\_CONFIG\_METHODS**](wdi-tlv-p2p-config-methods.md) | | | Configuration methods as defined in [**WDI\_WPS\_CONFIGURATION\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/dn898198). Only **WDI\_WPS\_CONFIGURATION\_METHOD\_DISPLAY**, **WDI\_WPS\_CONFIGURATION\_METHOD\_KEYPAD**, and **WDI\_WPS\_CONFIGURATION\_METHOD\_WFDS\_DEFAULT** are applicable. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ASP2_ADVERTISED_SERVICE_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-service-information-discovery-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-service-information-discovery-entry.md new file mode 100644 index 0000000000..1f37791b53 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-asp2-service-information-discovery-entry.md @@ -0,0 +1,79 @@ +--- +title: WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY is a TLV that contains an ASP2 Service Information Discovery Entry. +ms.assetid: 67F1CDE2-8003-44D3-B338-FE7C5EA48C29 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ASP2\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY + + +WDI\_TLV\_P2P\_ASP2\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY is a TLV that contains an ASP2 Service Information Discovery Entry. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x12D + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) | | | Name of the service (UTF-8), up to 21 bytes. | +| [**WDI\_TLV\_P2P\_INSTANCE\_NAME**](wdi-tlv-p2p-instance-name.md) | | | Instance name of the service (UTF-8), up to 63 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) | | X | Request service information to be used for the ANQP query request to download service information for this Service. | +| [**WDI\_TLV\_P2P\_SERVICE\_UPDATE\_INDICATOR**](wdi-tlv-p2p-service-update-indicator.md) | | X | Service Update indicator to be used for the ANQP query request. | +| [**WDI\_TLV\_P2P\_SERVICE\_TRANSACTION\_ID**](wdi-tlv-p2p-service-transaction-id.md) | | X | Service transaction ID to be used for the ANQP query request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ASP2_SERVICE_INFORMATION_DISCOVERY_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-attributes.md new file mode 100644 index 0000000000..a79286605d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-attributes.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_P2P_ATTRIBUTES is a TLV that contains Wi-Fi Direct attributes. +ms.assetid: 2EC99A30-3D2F-4552-A763-B77E030B5CE5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_ATTRIBUTES + + +WDI\_TLV\_P2P\_ATTRIBUTES is a TLV that contains Wi-Fi Direct attributes. + +## TLV Type + + +0x25 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------| +| [**WDI\_TLV\_P2P\_CAPABILITIES**](wdi-tlv-p2p-capabilities.md) | | | The Wi-Fi Direct capabilities. | +| [**WDI\_TLV\_P2P\_INTERFACE\_ADDRESS\_LIST**](wdi-tlv-p2p-interface-address-list.md) | | | An array of Wi-Fi Direct interface MAC addresses. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-background-discover-mode.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-background-discover-mode.md new file mode 100644 index 0000000000..bf23edff47 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-background-discover-mode.md @@ -0,0 +1,95 @@ +--- +title: WDI_TLV_P2P_BACKGROUND_DISCOVER_MODE +author: windows-driver-content +description: WDI_TLV_P2P_BACKGROUND_DISCOVER_MODE is a TLV that contains Wi-Fi Direct Background Discover Mode parameters. +ms.assetid: 987DB282-A992-497F-98B5-0D3DD477B91C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_BACKGROUND_DISCOVER_MODE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_BACKGROUND\_DISCOVER\_MODE + + +WDI\_TLV\_P2P\_BACKGROUND\_DISCOVER\_MODE is a TLV that contains Wi-Fi Direct Background Discover Mode parameters. + +## TLV Type + + +0xCE + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + +
TypeDescription
[WDI_P2P_DISCOVER_TYPE](https://msdn.microsoft.com/library/windows/hardware/dn926093)The type of discovery to be performed by the port.
[WDI_P2P_SERVICE_DISCOVERY_TYPE](https://msdn.microsoft.com/library/windows/hardware/dn926101)The type of Service Discovery to be performed by the port. +

The only valid values are WDI_P2P_SERVICE_DISCOVERY_TYPE_NO_SERVICE_DISCOVERY and WDI_P2P_SERVICE_DISCOVERY_TYPE_SERVICE_NAME_ONLY.

UINT32The device visibility timeout. Specifies the maximum timeout (in milliseconds) for reporting a device entry. This is required for background scan only.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_BACKGROUND_DISCOVER_MODE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-capabilities.md new file mode 100644 index 0000000000..c5ae5aceab --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-capabilities.md @@ -0,0 +1,178 @@ +--- +title: WDI_TLV_P2P_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_P2P_CAPABILITIES is a TLV that contains Wi-Fi Direct capabilities. +ms.assetid: 3BE13A87-ECA2-4204-87F1-2BE393F33D4C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CAPABILITIES + + +WDI\_TLV\_P2P\_CAPABILITIES is a TLV that contains Wi-Fi Direct capabilities. + +## TLV Type + + +0x17 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT8Specifies the concurrent Group Owner count.
UINT8Specifies the concurrent Client count.
UINT32Specifies the supported WPS version.
UINT8Specifies whether Service discovery is supported. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Wi-Fi Direct Service Names Discovery support. Specifies whether, when given a list of service name hashes, the adapter can probe for service hashes and indicate the responses as they arrive. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Wi-Fi Direct Service Information Discovery support. Specifies whether, when given a list of service name hashes, the adapter can perform probes and ANQP queries to get full service information. +

Valid values are 0 (not supported) and 1 (supported).

UINT32Specifies the maximum supported number of Service Name Advertisements bytes (to be sent in the beacon and probe responses). This sets a hard limit on the number of services that can be advertised.
UINT32Specifies the maximum supported number of Service Information Advertisement bytes the adapter can respond to using the GAS protocol. This is only valid if the device supports responding to Service Advertisement queries. This value is for firmware optimization so that the firmware does not wake up the host to respond to every query. The operating system does not limit the number of service advertisements if the firmware has a limitation because there is a fallback in the operating system. If the firmware cannot handle the ANQP query response, it should pass up the request and the operating system handles it.
UINT8Background discovery of Wi-Fi Direct devices and services. Specifies whether the adapter can periodically query for Wi-Fi Direct devices and service names so any new devices show up within 5 minutes of becoming visible. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether Client Discoverability is supported. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether infrastructure management is supported. +

Valid values are 0 (not supported) and 1 (supported).

UINT8The maximum size of the secondary adapter type list.
UINT8[6]The device address in network byte order.
UINT32The discovery filter list size.
UINT8The GO client table size.
UINT32The maximum size, in bytes, of vendor specific extension IEs that can be added to WFD management frames.
UINT8Specifies whether the adapter supports OID_WDI_P2P_LISTEN_STATE_PASSIVE_AVAILABILITY. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether the adapter supports indicating updates to the GO operating channel(s). +

Valid values are 0 (not supported) and 1 (supported).

UINT8Added in Windows 10, version 1511, WDI version 1.0.10. +

Specifies whether the adapter supports operating a GO on the 5GHz band.

+

Valid values are 0 (not supported) and 1 (supported).

UINT8

Added in Windows 10, version 1607, WDI version 1.0.21.

+Specifies if the adapter, when provided with a list of ASP2 Service name instances, can probe for service hashes and indicate the responses as they arrive. Valid values are 0 (not supported) and 1 (supported).

UINT8

Added in Windows 10, version 1607, WDI version 1.0.21.

+Specifies if the adapter, when given a set of service name instances, can perform probes and ANQP queries to get the full service information. Valid values are 0 (not supported) and 1 (supported).
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-entry-list.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-entry-list.md new file mode 100644 index 0000000000..ec47d2e784 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-entry-list.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_CHANNEL_ENTRY_LIST +author: windows-driver-content +description: WDI_TLV_P2P_CHANNEL_ENTRY_LIST is a TLV that contains a channel number list. +ms.assetid: 10739684-C00C-4AE7-A3B2-D4A6F1E9829B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CHANNEL_ENTRY_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CHANNEL\_ENTRY\_LIST + + +WDI\_TLV\_P2P\_CHANNEL\_ENTRY\_LIST is a TLV that contains a channel number list. + +## TLV Type + + +0xF9 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------|--------------------------------|----------|--------------------------------------| +| [**WDI\_TLV\_OPERATING\_CLASS**](wdi-tlv-operating-class.md) | | | The frequency band for the channels. | +| [**WDI\_TLV\_CHANNEL\_INFO\_LIST**](wdi-tlv-channel-info-list.md) | | | The channel number list. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CHANNEL_ENTRY_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-indicate-reason.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-indicate-reason.md new file mode 100644 index 0000000000..56b8d925ac --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-indicate-reason.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_CHANNEL_INDICATE_REASON +author: windows-driver-content +description: WDI_TLV_P2P_CHANNEL_INDICATE_REASON is a TLV that contains a reason for sending an indication. +ms.assetid: DD746492-82C5-4458-94A2-778F7F0F30B4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CHANNEL_INDICATE_REASON Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CHANNEL\_INDICATE\_REASON + + +WDI\_TLV\_P2P\_CHANNEL\_INDICATE\_REASON is a TLV that contains a reason for sending an indication. + +## TLV Type + + +0x102 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The reason for sending an indication. See [**WDI\_P2P\_CHANNEL\_INDICATE\_REASON**](https://msdn.microsoft.com/library/windows/hardware/dn926090) for possible reasons. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CHANNEL_INDICATE_REASON%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-list-attribute.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-list-attribute.md new file mode 100644 index 0000000000..5ab49be7d2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-list-attribute.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_CHANNEL_LIST_ATTRIBUTE +author: windows-driver-content +description: WDI_TLV_P2P_CHANNEL_LIST_ATTRIBUTE is a TLV that contains channel list attributes. +ms.assetid: 2378AC49-1530-45E2-A7C8-FEAF5E6CDBE5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CHANNEL_LIST_ATTRIBUTE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CHANNEL\_LIST\_ATTRIBUTE + + +WDI\_TLV\_P2P\_CHANNEL\_LIST\_ATTRIBUTE is a TLV that contains channel list attributes. + +## TLV Type + + +0xD5 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------|--------------------------------|----------|--------------------------| +| [**WDI\_TLV\_COUNTRY\_REGION\_LIST**](wdi-tlv-country-region-list.md) | | | The country/region list. | +| [**WDI\_TLV\_P2P\_CHANNEL\_ENTRY\_LIST**](wdi-tlv-p2p-channel-entry-list.md) | X | | The list of channels. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CHANNEL_LIST_ATTRIBUTE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-number.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-number.md new file mode 100644 index 0000000000..5c110900ff --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-channel-number.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_CHANNEL_NUMBER +author: windows-driver-content +description: WDI_TLV_P2P_CHANNEL_NUMBER is a TLV that contains Wi-Fi Direct channel number information. +ms.assetid: CE17143E-5DA1-4F5B-A2E0-2BD480030129 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CHANNEL_NUMBER Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CHANNEL\_NUMBER + + +WDI\_TLV\_P2P\_CHANNEL\_NUMBER is a TLV that contains Wi-Fi Direct channel number information. + +## TLV Type + + +0x82 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------|------------------------------------------------------------------------------------| +| UINT8\[3\] | The country or region code where the operating class and channel number are valid. | +| UINT8 | The operating class/frequency band for the channel number. | +| WDI\_CHANNEL\_NUMBER (UINT32) | The channel number for the Wi-Fi Direct Device or Group. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CHANNEL_NUMBER%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-config-methods.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-config-methods.md new file mode 100644 index 0000000000..222b1443dd --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-config-methods.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_CONFIG_METHODS +author: windows-driver-content +description: WDI_TLV_P2P_CONFIG_METHODS is a TLV that contains Wi-Fi Direct configuration methods. +ms.assetid: 95F81FBB-CF78-47EC-8DB3-90F639C30865 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_CONFIG_METHODS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_CONFIG\_METHODS + + +WDI\_TLV\_P2P\_CONFIG\_METHODS is a TLV that contains Wi-Fi Direct configuration methods. + +## TLV Type + + +0xEB + +## Length + + +The size (in bytes) of a UINT16. + +## Values + + +| Type | Description | +|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT16 | Configuration methods as defined in [**WDI\_WPS\_CONFIGURATION\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/dn898198). Only PIN display, PIN keypad, and WFDS are applicable. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_CONFIG_METHODS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-address.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-address.md new file mode 100644 index 0000000000..4f3000d49e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-address.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_DEVICE_ADDRESS +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_ADDRESS is a TLV that contains the device address of the Group Owner. +ms.assetid: EAC1972E-3D9B-4248-BAC3-3C2EB15D6817 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_ADDRESS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_ADDRESS + + +WDI\_TLV\_P2P\_DEVICE\_ADDRESS is a TLV that contains the device address of the Group Owner. + +## TLV Type + + +0x91 + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|----------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The device address of the Group Owner. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_ADDRESS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-capability.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-capability.md new file mode 100644 index 0000000000..f989d75004 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-capability.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_DEVICE_CAPABILITY +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_CAPABILITY is a TLV that contains Wi-Fi Direct device capabilities. +ms.assetid: 490CA066-998F-4F15-AFC2-028299042496 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_CAPABILITY + + +WDI\_TLV\_P2P\_DEVICE\_CAPABILITY is a TLV that contains Wi-Fi Direct device capabilities. + +## TLV Type + + +0x84 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | A bitmap of the Wi-Fi Direct device capabilities as defined in Table 12 of the Wi-Fi Direct technical specification. | +| UINT8 | A bitmap of the Wi-Fi Direct capabilities in the above device capability bitmap that are currently set by the operating system. | +| UINT32 | A bitmask that indicates which WPS versions are enabled. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_CAPABILITY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-filter-list.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-filter-list.md new file mode 100644 index 0000000000..06e9e3286a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-filter-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_DEVICE_FILTER_LIST +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_FILTER_LIST is a TLV that contains a list of Wi-Fi Direct devices and Group Owners to search for during Wi-Fi Direct device discovery. +ms.assetid: 56D1E6BD-41E3-4869-A821-334012B781A7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_FILTER_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_FILTER\_LIST + + +WDI\_TLV\_P2P\_DEVICE\_FILTER\_LIST is a TLV that contains a list of Wi-Fi Direct devices and Group Owners to search for during Wi-Fi Direct device discovery. + +## TLV Type + + +0xCE + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | A list of Wi-Fi Direct devices and Group Owners to search for during Wi-Fi Direct device discovery. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_FILTER_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info-parameters.md new file mode 100644 index 0000000000..a8dc77d44d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info-parameters.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_DEVICE_INFO_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_INFO_PARAMETERS is a TLV that contains Wi-Fi Direct device information parameters. +ms.assetid: A0B1AC85-5F99-4674-A1C4-E25554BDD89F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_INFO_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_INFO\_PARAMETERS + + +WDI\_TLV\_P2P\_DEVICE\_INFO\_PARAMETERS is a TLV that contains Wi-Fi Direct device information parameters. + +## TLV Type + + +0x86 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|------------|--------------------------------------------------------| +| UINT8\[6\] | The Wi-Fi Direct Device Address of the peer. | +| UINT16 | The configuration methods supported by the device. | +| UINT16 | Primary device type: Main type category identifier. | +| UINT8\[4\] | Primary device type: OUI assigned to this device type. | +| UINT16 | Primary device type: Subcategory type identifier. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_INFO_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info.md new file mode 100644 index 0000000000..413f268118 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_DEVICE_INFO +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_INFO is a TLV that contains Wi-Fi Direct device information. +ms.assetid: 6B68F334-4C21-4088-AD47-9EB41F9A1CB8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_INFO + + +WDI\_TLV\_P2P\_DEVICE\_INFO is a TLV that contains Wi-Fi Direct device information. + +## TLV Type + + +0x96 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_DEVICE\_INFO\_PARAMETERS**](wdi-tlv-p2p-device-info-parameters.md) | | | The device information, including Wi-Fi Direct device address, supported configuration methods, and primary device type. | +| [**WDI\_TLV\_P2P\_DEVICE\_NAME**](wdi-tlv-p2p-device-name.md) | | | The device name for this device. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-device-name.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-name.md new file mode 100644 index 0000000000..cf91d2fc65 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-device-name.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_DEVICE_NAME +author: windows-driver-content +description: WDI_TLV_P2P_DEVICE_NAME is a TLV that contains a device name. +ms.assetid: 7FB04079-7F82-4D7B-95BA-45B5832B36C0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DEVICE_NAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DEVICE\_NAME + + +WDI\_TLV\_P2P\_DEVICE\_NAME is a TLV that contains a device name. + +## TLV Type + + +0x92 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|---------------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the device name for the device. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DEVICE_NAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-discover-mode.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-discover-mode.md new file mode 100644 index 0000000000..b771d80c6e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-discover-mode.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_P2P_DISCOVER_MODE +author: windows-driver-content +description: WDI_TLV_P2P_DISCOVER_MODE is a TLV that contains Wi-Fi Direct discovery mode information for OID_WDI_TASK_P2P_DISCOVER. +ms.assetid: 430DDDBE-C861-4E85-BFAB-31670F77696D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DISCOVER_MODE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DISCOVER\_MODE + + +WDI\_TLV\_P2P\_DISCOVER\_MODE is a TLV that contains Wi-Fi Direct discovery mode information for [OID\_WDI\_TASK\_P2P\_DISCOVER](https://msdn.microsoft.com/library/windows/hardware/dn925955). + +## TLV Type + + +0xA9 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_P2P\_DISCOVER\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926093) (UINT32) | The type of discovery to be performed by the port. | +| UINT8 | A flag that indicates if a complete device discovery is required. Valid values are 0 (not required) and 1 (required). If this flag is set to 0, a partial discovery may be performed. | +| [**WDI\_P2P\_SCAN\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926099) (UINT32) | The type of scan to be performed by the port in scan phase. | +| [**WDI\_P2P\_SERVICE\_DISCOVERY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926101) (UINT32) | The type of Service Discovery to be performed. | +| UINT8 | The scan repeat count. Specifies if the full scan procedure should be repeated. If set to 0, the scan should be repeated until the task is aborted by the host. | +| UINT32 | The time between scans. If the scan repeat count is not set to 1, this time specifies how long (in milliseconds) device should wait before repeating the scan procedure after completing a full scan of the requested channels. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DISCOVER_MODE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-discovered-service-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-discovered-service-entry.md new file mode 100644 index 0000000000..c7592bf9b8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-discovered-service-entry.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_DISCOVERED_SERVICE_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_DISCOVERED_SERVICE_ENTRY is a TLV that contains a discovered service entry. +ms.assetid: B8D453FF-49CA-4106-97DA-008893760E92 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DISCOVERED_SERVICE_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DISCOVERED\_SERVICE\_ENTRY + + +WDI\_TLV\_P2P\_DISCOVERED\_SERVICE\_ENTRY is a TLV that contains a discovered service entry. + +## TLV Type + + +0x112 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) | | | The name of the service, in UTF-8, up to 255 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) | | X | The Service Information for the service. | +| [**WDI\_TLV\_P2P\_SERVICE\_STATUS**](wdi-tlv-p2p-service-status.md) | | | The Service Status of the service. | +| [**WDI\_TLV\_P2P\_ADVERTISEMENT\_ID**](wdi-tlv-p2p-advertisement-id.md) | | | An ID that uniquely identifies the service instance. | +| [**WDI\_TLV\_P2P\_CONFIG\_METHODS**](wdi-tlv-p2p-config-methods.md) | | | The Configuration Methods as defined in [**WDI\_WPS\_CONFIGURATION\_METHOD**](https://msdn.microsoft.com/library/windows/hardware/dn898198). Only PinDisplay, PinKeypad and WFDS are applicable. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DISCOVERED_SERVICE_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-discovery-channel-settings.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-discovery-channel-settings.md new file mode 100644 index 0000000000..b1f8bb2285 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-discovery-channel-settings.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_DISCOVERY_CHANNEL_SETTINGS +author: windows-driver-content +description: WDI_TLV_P2P_DISCOVERY_CHANNEL_SETTINGS is a TLV that contains Wi-Fi Direct discovery channel settings. +ms.assetid: 50BD3F70-4C12-4984-8E3F-AEC9F5C3CDCA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_DISCOVERY_CHANNEL_SETTINGS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_DISCOVERY\_CHANNEL\_SETTINGS + + +WDI\_TLV\_P2P\_DISCOVERY\_CHANNEL\_SETTINGS is a TLV that contains Wi-Fi Direct discovery channel settings. + +## TLV Type + + +0xE8 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------| +| [**WDI\_TLV\_P2P\_LISTEN\_DURATION**](wdi-tlv-p2p-listen-duration.md) | | | The cycle duration and listen time. | +| [**WDI\_TLV\_BAND\_CHANNEL**](wdi-tlv-band-channel.md) | X | | The list of channels to scan. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_DISCOVERY_CHANNEL_SETTINGS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-internal-reset-policy.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-internal-reset-policy.md new file mode 100644 index 0000000000..5082f00828 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-internal-reset-policy.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY +author: windows-driver-content +description: WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY is a TLV that contains the policy used by the firmware for operating channel selection after a Wi-Fi Direct GO Reset is stopped/restarted. +ms.assetid: 6EA61C65-8573-491D-9268-8A02440A1175 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_INTERNAL\_RESET\_POLICY + + +WDI\_TLV\_P2P\_GO\_INTERNAL\_RESET\_POLICY is a TLV that contains the policy used by the firmware for operating channel selection after a Wi-Fi Direct GO Reset is stopped/restarted. + +## TLV Type + + +0xB2 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_P2P\_GO\_INTERNAL\_RESET\_POLICY**](https://msdn.microsoft.com/library/windows/hardware/dn926096) (UINT32) | If an Wi-Fi Direct GO Reset is stopped/restarted by the IHV component on its own (for example, for Bluetooth co-ex spatial stream downgrade), this configuration defines the policy to be adopted by the firmware for operating channel selection after the reset. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_INTERNAL_RESET_POLICY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-info.md new file mode 100644 index 0000000000..9da677e789 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_INFO +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_INFO is a TLV that contains Wi-Fi Direct GO Negotiation Confirmation information. +ms.assetid: 1CC470FF-9301-4DF9-BE52-5FB1DCBF5415 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_INFO + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_INFO is a TLV that contains Wi-Fi Direct GO Negotiation Confirmation information. + +## TLV Type + + +0x88 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-confirmation-parameters.md) | | | The Wi-Fi Direct GO Negotiation Confirmation parameters. | +| [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) | | X | The Wi-Fi Direct Group ID. | +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](wdi-tlv-p2p-channel-number.md) | | X | The listen channel of the remote device. The GO negotiation confirmation frame must be sent on this channel whenever this is specified. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-parameters.md new file mode 100644 index 0000000000..7147fdb278 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-confirmation-parameters.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_PARAMETERS is a TLV that contains incoming GO Negotiation Confirmation parameters. +ms.assetid: 69A20B64-C2B9-4C96-8119-EE64E80201EB +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_CONFIRMATION\_PARAMETERS is a TLV that contains incoming GO Negotiation Confirmation parameters. + +## TLV Type + + +0xAA + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | The Wi-Fi Direct Status Code, as defined by the Wi-Fi Direct specification. | +| UINT8 | Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi Direct technical specification. | +| UINT8 | The bits in the Group capability bitmap above that are set by the operating system. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_CONFIRMATION_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-info.md new file mode 100644 index 0000000000..e6b99d6f79 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_INFO +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_INFO is a TLV that contains Wi-Fi Direct Group Owner negotiation request information. +ms.assetid: 4F505DF1-8D02-4421-956F-B7E1AF99D367 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_INFO + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_INFO is a TLV that contains Wi-Fi Direct Group Owner negotiation request information. + +## TLV Type + + +0x6D + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-request-parameters.md) | | | The Wi-Fi Direct Group Owner negotiation request parameters. | +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](wdi-tlv-p2p-channel-number.md) | | X | The listen channel of the remote device. Whenever this is specified, the GO negotiation request frame must be sent on this channel. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-parameters.md new file mode 100644 index 0000000000..1ecfd31b7a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-request-parameters.md @@ -0,0 +1,77 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_PARAMETERS is a TLV that contains Wi-Fi Direct Group Owner negotiation request parameters. +ms.assetid: C0B1832A-D315-47F8-87B8-73373CF55D44 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_REQUEST\_PARAMETERS is a TLV that contains Wi-Fi Direct Group Owner negotiation request parameters. + +## TLV Type + + +0x6E + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies the local Wi-Fi Direct GO Intent. Valid values are between 0 and 15. | +| UINT8 | Specifies the tie-breaker field of GO Intent. | +| UINT16 | Specifies the GO Configuration Timeout in milliseconds. | +| UINT16 | Specifies the Client Configuration Timeout in milliseconds. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Intended interface address. Specifies the local MAC address for future Wi-Fi Direct connections. | +| UINT8 | Specifies the Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi P2P technical specification. | +| UINT8 | Specifies the bits set by the operating system in the Group capability bitmap above. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-info.md new file mode 100644 index 0000000000..c164b66be8 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-info.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_INFO +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_INFO is a TLV that contains Wi-Fi Direct Group Owner negotiation response information. +ms.assetid: A0BB2CF6-4168-4973-92D0-EFF9F596F1BE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_INFO + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_INFO is a TLV that contains Wi-Fi Direct Group Owner negotiation response information. + +## TLV Type + + +0x6F + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-go-negotiation-response-parameters.md) | | | Specifies the Wi-Fi Direct Group Owner negotiation response parameters. | +| [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) | | X | Specifies the Group ID for local Wi-Fi Direct GO. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-parameters.md new file mode 100644 index 0000000000..4ce549a117 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-go-negotiation-response-parameters.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_PARAMETERS is a TLV that contains incoming GO Negotiation Response parameters. +ms.assetid: 78C9B274-FAF0-4B2E-98A9-865A65105DA1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_P2P\_GO\_NEGOTIATION\_RESPONSE\_PARAMETERS is a TLV that contains incoming GO Negotiation Response parameters. + +## TLV Type + + +0x71 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies the Wi-Fi Direct Status Code, as defined by the Wi-Fi Direct specification. | +| UINT8 | Specifies the local Wi-Fi Direct GO Intent. This is a value between 0 and 15. | +| UINT8 | Specifies the tie-breaker field of the GO Intent. | +| UINT16 | Specifies the GO Configuration Timeout in milliseconds. | +| UINT16 | Specifies the Client Configuration Timeout in milliseconds. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Intended interface address. Specifies the local MAC Address for future Wi-Fi Direct connection. | +| UINT8 | Specifies the Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi P2P technical specification. | +| UINT8 | Specifies the bits set by the operating system in the Group capability bitmap above. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GO_NEGOTIATION_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-group-bssid.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-bssid.md new file mode 100644 index 0000000000..3ff45d0efc --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-bssid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_GROUP_BSSID +author: windows-driver-content +description: WDI_TLV_P2P_GROUP_BSSID is a TLV that contains the Group BSSID for local Wi-Fi Direct GO. +ms.assetid: C9BC2209-DF72-4775-A3B5-EC37D404CFED +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GROUP_BSSID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GROUP\_BSSID + + +WDI\_TLV\_P2P\_GROUP\_BSSID is a TLV that contains the Group BSSID for local Wi-Fi Direct GO. + +## TLV Type + + +0x73 + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the Group BSSID for local Wi-Fi Direct GO. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GROUP_BSSID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-group-id.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-id.md new file mode 100644 index 0000000000..2239dad614 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-id.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_GROUP_ID +author: windows-driver-content +description: WDI_TLV_P2P_GROUP_ID is a TLV that contains the Group ID for Wi-Fi Direct GO. +ms.assetid: 5DF5E7AA-4A5A-4AF5-90E6-40791C8DBB56 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GROUP_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GROUP\_ID + + +WDI\_TLV\_P2P\_GROUP\_ID is a TLV that contains the Group ID for Wi-Fi Direct GO. + +## TLV Type + + +0x75 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------| +| [**WDI\_TLV\_P2P\_DEVICE\_ADDRESS**](wdi-tlv-p2p-device-address.md) | | | Specifies the device address of the Wi-Fi Direct GO. | +| [**WDI\_TLV\_SSID**](wdi-tlv-ssid-list.md) | | | Specifies the Group SSID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GROUP_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-group-owner-capability.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-owner-capability.md new file mode 100644 index 0000000000..954efe9211 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-group-owner-capability.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_GROUP_OWNER_CAPABILITY +author: windows-driver-content +description: WDI_TLV_P2P_GROUP_OWNER_CAPABILITY is a TLV that contains Wi-Fi Direct Group Owner capability information. +ms.assetid: 3F07665C-0212-465C-9118-CC213198EFB7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_GROUP_OWNER_CAPABILITY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_GROUP\_OWNER\_CAPABILITY + + +WDI\_TLV\_P2P\_GROUP\_OWNER\_CAPABILITY is a TLV that contains Wi-Fi Direct Group Owner capability information. + +## TLV Type + + +0x77 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies the Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi P2P technical specification. | +| UINT8 | Specifies the bits set by the operating system in the Group capability bitmap above. | +| UINT32 | Maximum client count for this Group Owner. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_GROUP_OWNER_CAPABILITY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-include-listen-channel.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-include-listen-channel.md new file mode 100644 index 0000000000..5b2e984c1f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-include-listen-channel.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL +author: windows-driver-content +description: WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL is a TLV that specifies whether the probe request should include the Listen Channel attribute during discovery. +ms.assetid: 75662669-102A-4186-951C-58D1B36D1686 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INCLUDE\_LISTEN\_CHANNEL + + +WDI\_TLV\_P2P\_INCLUDE\_LISTEN\_CHANNEL is a TLV that specifies whether the probe request should include the Listen Channel attribute during discovery. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x128 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | This parameter specifies whether the probe request should include the Listen Channel attribute during discovery. Valid values are 0 (do not include) and 1 (include). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INCLUDE_LISTEN_CHANNEL%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-information.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-information.md new file mode 100644 index 0000000000..780458b00f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-information.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_INCOMING_FRAME_INFORMATION +author: windows-driver-content +description: WDI_TLV_P2P_INCOMING_FRAME_INFORMATION is a TLV that contains incoming Wi-Fi Direct action frame information. +ms.assetid: 7E7EF56D-625B-4B79-9AE4-A9C9B7C8547A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INCOMING_FRAME_INFORMATION Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INCOMING\_FRAME\_INFORMATION + + +WDI\_TLV\_P2P\_INCOMING\_FRAME\_INFORMATION is a TLV that contains incoming Wi-Fi Direct action frame information. + +## TLV Type + + +0x79 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_INCOMING\_FRAME\_PARAMETERS**](wdi-tlv-p2p-incoming-frame-parameters.md) | | | Specifies the incoming frame parameters. | +| [**WDI\_TLV\_P2P\_ACTION\_FRAME\_IES**](wdi-tlv-p2p-action-frame-ies.md) | | | Specifies the IEs section of the received public action frame. | +| [**WDI\_TLV\_ACTION\_FRAME\_DEVICE\_CONTEXT**](wdi-tlv-action-frame-device-context.md) | | X | Specifies the vendor-specific information that is passed back down if the host decides to send a response to this incoming message. To avoid lifetime management issues, the IHV component must not use pointers in this field. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INCOMING_FRAME_INFORMATION%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-parameters.md new file mode 100644 index 0000000000..5c4cf55862 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-incoming-frame-parameters.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_INCOMING_FRAME_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_INCOMING_FRAME_PARAMETERS is a TLV that contains incoming Wi-Fi Direct action frame parameters. +ms.assetid: 8E530962-E4DC-4845-8A5F-87AC4E000DA8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INCOMING_FRAME_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INCOMING\_FRAME\_PARAMETERS + + +WDI\_TLV\_P2P\_INCOMING\_FRAME\_PARAMETERS is a TLV that contains incoming Wi-Fi Direct action frame parameters. + +## TLV Type + + +0x7A + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|----------------------------------------------------| +| [**WDI\_P2P\_ACTION\_FRAME\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926086) | The type of the incoming action frame. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the remote peer. | +| UINT8 | The Wi-Fi Direct Dialog Token for the transaction. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INCOMING_FRAME_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name-hash.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name-hash.md new file mode 100644 index 0000000000..aee45c8b6d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name-hash.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_INSTANCE_NAME_HASH +author: windows-driver-content +description: WDI_TLV_P2P_INSTANCE_NAME_HASH is a TLV that contains the hash of "Instance Name, Service Type". +ms.assetid: A29D0339-93A8-43EB-8C22-DD7A7DC2147C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INSTANCE_NAME_HASH Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INSTANCE\_NAME\_HASH + + +WDI\_TLV\_P2P\_INSTANCE\_NAME\_HASH is a TLV that contains the hash of "Instance Name, Service Type". + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x12C + +## Length + + +The size (in bytes) of a [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) structure. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|--------------------------------------------| +| [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) | The hash of "Instance Name, Service Type". | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INSTANCE_NAME_HASH%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name.md new file mode 100644 index 0000000000..84c9572409 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-instance-name.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_INSTANCE_NAME +author: windows-driver-content +description: WDI_TLV_P2P_INSTANCE_NAME is a TLV that contains the Instance Name of the service. +ms.assetid: 36CB51E2-D8CB-4C71-B2DB-77F4FDBB8B90 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INSTANCE_NAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INSTANCE\_NAME + + +WDI\_TLV\_P2P\_INSTANCE\_NAME is a TLV that contains the Instance Name of the service. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x12B + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-----------------------------------------------------------------| +| UINT8\[\] | The Instance Name of the service in UTF-8, up to 63 bytes long. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INSTANCE_NAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-interface-address-list.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-interface-address-list.md new file mode 100644 index 0000000000..f9b946f0a0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-interface-address-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_INTERFACE_ADDRESS_LIST +author: windows-driver-content +description: WDI_TLV_P2P_INTERFACE_ADDRESS_LIST is a TLV that contains an address list for a Wi-Fi Direct interface. +ms.assetid: B7FCB047-28D2-43E2-B4D6-B24E7BC74D47 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INTERFACE_ADDRESS_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INTERFACE\_ADDRESS\_LIST + + +WDI\_TLV\_P2P\_INTERFACE\_ADDRESS\_LIST is a TLV that contains an address list for a Wi-Fi Direct interface. + +## TLV Type + + +0x18 + +## Length + + +The size (in bytes) of the array of [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structures. The array must contain 1 or more structures. + +## Values + + +| Type | Description | +|-------------------------------------------------------|----------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071)\[\] | An array of Wi-Fi MAC addresses. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INTERFACE_ADDRESS_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-info.md new file mode 100644 index 0000000000..9e344ec877 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-info.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_P2P_INVITATION_REQUEST_INFO +author: windows-driver-content +description: WDI_TLV_P2P_INVITATION_REQUEST_INFO is a TLV that contains Wi-Fi Direct Invitation Request information. +ms.assetid: 055B0F6D-2B68-495D-8253-2D213D699383 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INVITATION_REQUEST_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INVITATION\_REQUEST\_INFO + + +WDI\_TLV\_P2P\_INVITATION\_REQUEST\_INFO is a TLV that contains Wi-Fi Direct Invitation Request information. + +## TLV Type + + +0x7B + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-----------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------| +| [**WDI\_TLV\_P2P\_INVITATION\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-invitation-request-parameters.md) | | | The Wi-Fi Direct Invitation Request parameters. | +| [**WDI\_TLV\_P2P\_GROUP\_BSSID**](wdi-tlv-p2p-group-bssid.md) | | X | The Group BSSID. | +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](wdi-tlv-p2p-channel-number.md) | | X | The operating channel for Wi-Fi Direct GO. | +| [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) | | | The Group ID for target Wi-Fi Direct GO. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INVITATION_REQUEST_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-parameters.md new file mode 100644 index 0000000000..4c4ab9bc72 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-request-parameters.md @@ -0,0 +1,99 @@ +--- +title: WDI_TLV_P2P_INVITATION_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_INVITATION_REQUEST_PARAMETERS is a TLV that contains Wi-Fi Direct Invitation Request parameters. +ms.assetid: CC9B0454-4522-4589-8E21-4986BAEBC6D0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INVITATION_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INVITATION\_REQUEST\_PARAMETERS + + +WDI\_TLV\_P2P\_INVITATION\_REQUEST\_PARAMETERS is a TLV that contains Wi-Fi Direct Invitation Request parameters. + +## TLV Type + + +0x7C + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT16The Group Owner Configuration Timeout in milliseconds.
UINT16The Client Configuration Timeout in milliseconds.
UINT8The invitation flags as defined by the Wi-Fi Direct specification.
UINT8A bit that indicates whether or not the outgoing Invitation Request is an invitation to a local Group Owner. +

Valid values are 0 and 1. This bit is set to 1 if it is an invitation to a local GO.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INVITATION_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-info.md new file mode 100644 index 0000000000..eb5ca45a08 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_INVITATION_RESPONSE_INFO +author: windows-driver-content +description: WDI_TLV_P2P_INVITATION_RESPONSE_INFO is a TLV that contains Wi-Fi Direct Invitation Response information. +ms.assetid: DFF1649A-1CBE-4E0B-8EB2-6E10F539C72F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INVITATION_RESPONSE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_INFO + + +WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_INFO is a TLV that contains Wi-Fi Direct Invitation Response information. + +## TLV Type + + +0x7E + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------------| +| [**WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-invitation-response-parameters.md) | | | The Wi-Fi Direct Invitation Response parameters. | +| [**WDI\_TLV\_P2P\_GROUP\_BSSID**](wdi-tlv-p2p-group-bssid.md) | | X | The Group BSSID for local Wi-Fi Direct GO. | +| [**WDI\_TLV\_P2P\_CHANNEL\_NUMBER**](wdi-tlv-p2p-channel-number.md) | | X | The operating channel for Wi-Fi Direct GO. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INVITATION_RESPONSE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-parameters.md new file mode 100644 index 0000000000..ddf4c77cca --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-invitation-response-parameters.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_INVITATION_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_INVITATION_RESPONSE_PARAMETERS is a TLV that contains Wi-Fi Direct Invitation Response parameters. +ms.assetid: A242F40C-D062-4A62-8F47-E42E74EAEFE8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_INVITATION_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_P2P\_INVITATION\_RESPONSE\_PARAMETERS is a TLV that contains Wi-Fi Direct Invitation Response parameters. + +## TLV Type + + +0x80 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|--------------------------------------------------------------------------------| +| UINT8 | The Wi-Fi Direct Status Code, as specified by the Wi-Fi Direct specification.. | +| UINT16 | The GO Configuration Timeout, in milliseconds. | +| UINT16 | The Client Configuration Timeout, in milliseconds. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_INVITATION_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-channel.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-channel.md new file mode 100644 index 0000000000..b6a0d33469 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-channel.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_P2P_LISTEN_CHANNEL +author: windows-driver-content +description: WDI_TLV_P2P_LISTEN_CHANNEL is a TLV that contains Wi-Fi Direct channel information. +ms.assetid: 45D1B507-C02B-432B-A552-78F2539ECE68 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_LISTEN_CHANNEL Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_LISTEN\_CHANNEL + + +WDI\_TLV\_P2P\_LISTEN\_CHANNEL is a TLV that contains Wi-Fi Direct channel information. + +## TLV Type + + +0x114 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------|------------------------------------------------------------------------------------| +| UINT8\[3\] | The country or region code where the operating class and channel number are valid. | +| UINT8 | The operating class/frequency band for the channel number. | +| WDI\_CHANNEL\_NUMBER (UINT32) | The channel number for the Wi-Fi Direct Device or Group. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_LISTEN_CHANNEL%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-duration.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-duration.md new file mode 100644 index 0000000000..eb4e7f2316 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-duration.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_LISTEN_DURATION +author: windows-driver-content +description: WDI_TLV_P2P_LISTEN_DURATION is a TLV that contains Wi-Fi Direct listen duration information. +ms.assetid: 6C14BB67-89E1-4795-9327-2B5B87BF2D7C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_LISTEN_DURATION Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_LISTEN\_DURATION + + +WDI\_TLV\_P2P\_LISTEN\_DURATION is a TLV that contains Wi-Fi Direct listen duration information. + +## TLV Type + + +0xE9 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The duration, in milliseconds, of the listen cycle. The adapter is in listen state during this time. | +| UINT32 | The duration, in milliseconds, that the adapter is expected to actively listen during the listen cycle. This duration must be less than listen cycle duration. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_LISTEN_DURATION%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-state.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-state.md new file mode 100644 index 0000000000..ad70867368 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-listen-state.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_LISTEN_STATE +author: windows-driver-content +description: WDI_TLV_P2P_LISTEN_STATE is a TLV that contains a Wi-Fi Direct listen state. +ms.assetid: 66BDF96A-2B9D-4188-AFC8-465786924B47 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_LISTEN_STATE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_LISTEN\_STATE + + +WDI\_TLV\_P2P\_LISTEN\_STATE is a TLV that contains a Wi-Fi Direct listen state. + +## TLV Type + + +0x81 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------------------------------------------------------------|----------------------------------------| +| [**WDI\_P2P\_LISTEN\_STATE**](https://msdn.microsoft.com/library/windows/hardware/dn926097) | The desired Wi-Fi Direct listen state. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_LISTEN_STATE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-persistent-group-id.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-persistent-group-id.md new file mode 100644 index 0000000000..253da99a5c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-persistent-group-id.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_PERSISTENT_GROUP_ID +author: windows-driver-content +description: WDI_TLV_P2P_PERSISTENT_GROUP_ID is a TLV that contains a Group ID of a Persistent Group to be used for a connection. +ms.assetid: 0C759D34-3197-4CAB-A691-187BC3457C04 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PERSISTENT_GROUP_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PERSISTENT\_GROUP\_ID + + +WDI\_TLV\_P2P\_PERSISTENT\_GROUP\_ID is a TLV that contains a Group ID of a Persistent Group to be used for a connection. + +## TLV Type + + +0xF1 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------|--------------------------------|----------|----------------------------------------| +| [**WDI\_TLV\_P2P\_DEVICE\_ADDRESS**](wdi-tlv-p2p-device-address.md) | | | The device address of the Group Owner. | +| [**WDI\_TLV\_SSID**](wdi-tlv-ssid.md) | | | The Group SSID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PERSISTENT_GROUP_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-info.md new file mode 100644 index 0000000000..0392223789 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-info.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_INFO +author: windows-driver-content +description: WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_INFO is a TLV that contains Wi-Fi Direct Provision Discovery Request information. +ms.assetid: C71F2FA9-2255-45E9-83CD-FA8DBEF5EA74 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_INFO + + +WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_INFO is a TLV that contains Wi-Fi Direct Provision Discovery Request information. + +## TLV Type + + +0x83 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS**](wdi-tlv-p2p-provision-discovery-request-parameters.md) | | | The Wi-Fi Direct Provision Discovery Request parameters. | +| [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) | | X | The Group ID for the target Wi-Fi Direct GO. The Group ID is optional. In the case of Wi-Fi Direct services, this is the Group ID for the local Wi-Fi Direct GO that the remote side should join. | +| [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) | | X | The Wi-Fi Direct Provision Service attributes. | +| [**WDI\_TLV\_P2P\_PERSISTENT\_GROUP\_ID**](wdi-tlv-p2p-persistent-group-id.md) | | X | The Group IP for the Persistent Group to be used for the connection. This field is valid if the Persistent Group flag in [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) is set to 1. | +| [**WDI\_TLV\_P2P\_SERVICE\_SESSION\_INFO**](wdi-tlv-p2p-service-session-info.md) | | X | Service Session information. This field is valid if [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) is present. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-parameters.md new file mode 100644 index 0000000000..fd78ea08a3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-request-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_PARAMETERS is a TLV that contains Wi-Fi Provision Discovery Request parameters. +ms.assetid: 938F9CA0-0B34-4507-86CC-731C969335F7 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS + + +WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_REQUEST\_PARAMETERS is a TLV that contains Wi-Fi Provision Discovery Request parameters. + +## TLV Type + + +0x85 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi Direct technical specification. | +| UINT8 | The bits in the Group capability bitmap above that are set by the operating system. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PROVISION_DISCOVERY_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-info.md new file mode 100644 index 0000000000..92e97336bf --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-info.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_INFO +author: windows-driver-content +description: WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_INFO is a TLV that contains Wi-Fi Direct Provision Discovery Response information. +ms.assetid: EB7C4A5C-27D8-4A84-BC91-0DED51FB74C2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_INFO + + +WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_INFO is a TLV that contains Wi-Fi Direct Provision Discovery Response information. + +## TLV Type + + +0x87 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|--------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS**](wdi-tlv-p2p-provision-discovery-response-parameters.md) | | | The provision discovery response parameters. | +| [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) | | X | The Provision Service attributes. | +| [**WDI\_TLV\_P2P\_GROUP\_ID**](wdi-tlv-p2p-group-id.md) | | X | The Group ID if Wi-Fi Direct Service is supported. | +| [**WDI\_TLV\_P2P\_PERSISTENT\_GROUP\_ID**](wdi-tlv-p2p-persistent-group-id.md) | | X | The Group IP for the Persistent Group to be used for the connection. This field is valid if the Persistent Group flag in [**WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES**](wdi-tlv-p2p-provision-service-attributes.md) is set to 1. | +| [**WDI\_TLV\_P2P\_SERVICE\_SESSION\_INFO**](wdi-tlv-p2p-service-session-info.md) | | X | The Service Session information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-parameters.md new file mode 100644 index 0000000000..4c59185b93 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-discovery-response-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_PARAMETERS is a TLV that contains provision discovery response parameters. +ms.assetid: 0732C370-108E-4C9A-AF13-2B7D54AEB984 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_P2P\_PROVISION\_DISCOVERY\_RESPONSE\_PARAMETERS is a TLV that contains provision discovery response parameters. + +## TLV Type + + +0x113 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | The Wi-Fi Direct Group capability bitmask. The bitmask matches those defined in Table 13-Group Capability Bitmap definition of the Wi-Fi P2P technical specification. | +| UINT8 | The bits set by the operating system in the above Group capability bitmap. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PROVISION_DISCOVERY_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-service-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-service-attributes.md new file mode 100644 index 0000000000..3ad3c2b0ec --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-provision-service-attributes.md @@ -0,0 +1,82 @@ +--- +title: WDI_TLV_P2P_PROVISION_SERVICE_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_P2P_PROVISION_SERVICE_ATTRIBUTES is a TLV that contains Wi-Fi Direct Provision Service attributes. +ms.assetid: CA318E91-660A-4F17-827B-F27E18643CC6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_PROVISION_SERVICE_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES + + +WDI\_TLV\_P2P\_PROVISION\_SERVICE\_ATTRIBUTES is a TLV that contains Wi-Fi Direct Provision Service attributes. + +## TLV Type + + +0xC6 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Wi-Fi Direct Status Code, as defined by the Wi-Fi Direct specification. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Local MAC Address for future Wi-Fi Direct connection. | +| UINT8 | Connection Capability bitmask. | +| UINT32 | Feature Capability bitmask. | +| UINT32 | Advertisement ID for the Service Instance. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Service address for the Service instance. | +| UINT32 | Session ID that uniquely identifies the Session to the Service. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Session address that uniquely identifies the Session to the Service. | +| UINT16 | GO Configuration Timeout in milliseconds. | +| UINT16 | Client Configuration Timeout in milliseconds. | +| UINT8 | A flag indicating if a Persistent Group will be used for the connection. The flag is set to 1 if a Persistent Group will be used. | +| UINT8 | A flag indicating if this frame is part of a follow-on provision discovery. The flag is set to 1 if it is part of a follow-on provision discovery. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_PROVISION_SERVICE_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-response-frame-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-response-frame-parameters.md new file mode 100644 index 0000000000..b5c4eac663 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-response-frame-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_P2P_RESPONSE_FRAME_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_RESPONSE_FRAME_PARAMETERS is an unused TLV. +ms.assetid: DA2F2BA8-4F30-4F10-8A0C-6A950CB933EE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_RESPONSE_FRAME_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_RESPONSE\_FRAME\_PARAMETERS + + +WDI\_TLV\_P2P\_RESPONSE\_FRAME\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_RESPONSE_FRAME_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-secondary-device-type-list.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-secondary-device-type-list.md new file mode 100644 index 0000000000..49a27c56d5 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-secondary-device-type-list.md @@ -0,0 +1,85 @@ +--- +title: WDI_TLV_P2P_SECONDARY_DEVICE_TYPE_LIST +author: windows-driver-content +description: WDI_TLV_P2P_SECONDARY_DEVICE_TYPE_LIST is a TLV that contains a list of secondary device types. +ms.assetid: 278F3D2B-6729-4F7A-B3B2-B12D79C04530 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SECONDARY_DEVICE_TYPE_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SECONDARY\_DEVICE\_TYPE\_LIST + + +WDI\_TLV\_P2P\_SECONDARY\_DEVICE\_TYPE\_LIST is a TLV that contains a list of secondary device types. + +## TLV Type + + +0x94 + +## Length + + +The size (in bytes) of the array of WDI\_P2P\_DEVICE\_TYPE elements. An array length of 0 is allowed. + +**Note**  WDI\_P2P\_DEVICE\_TYPE is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|----------------------------|----------------------------------------| +| WDI\_P2P\_DEVICE\_TYPE\[\] | An array of Wi-Fi Direct device types. | + +  + +WDI\_P2P\_DEVICE\_TYPE consists of the following elements. + +| Type | Description | +|------------|-----------------------------------------------| +| UINT16 | The main type category ID. | +| UINT8\[4\] | The OUI that is assigned to this device type. | +| UINT16 | The subcategory ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SECONDARY_DEVICE_TYPE_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result-parameters.md new file mode 100644 index 0000000000..48700e63b3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result-parameters.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT_PARAMETERS is a TLV that contains Wi-Fi Direct send Action Frame result parameters. +ms.assetid: A0B234F2-081B-4027-9B42-76401F600707 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT\_PARAMETERS + + +WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT\_PARAMETERS is a TLV that contains Wi-Fi Direct send Action Frame result parameters. + +## TLV Type + + +0xAE + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The device address of the target Wi-Fi Direct device. | +| UINT8 | The Wi-Fi Direct Dialog Token for this transaction. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result.md new file mode 100644 index 0000000000..79cc933063 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-frame-result.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT +author: windows-driver-content +description: WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT is a TLV that contains information about an Action Frame that was sent to a peer. +ms.assetid: DA469DF2-4C59-495C-A4B5-DC7B3B157566 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT + + +WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT is a TLV that contains information about an Action Frame that was sent to a peer. + +## TLV Type + + +0xAF + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SEND\_ACTION\_FRAME\_RESULT\_PARAMETERS**](wdi-tlv-p2p-send-action-frame-result-parameters.md) | | | The Wi-Fi Direct send Action Frame result parameters. | +| [**WDI\_TLV\_P2P\_ACTION\_FRAME\_IES**](wdi-tlv-p2p-action-frame-ies.md) | | | The set of IEs sent to the remote device. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SEND_ACTION_FRAME_RESULT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-request-frame-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-request-frame-parameters.md new file mode 100644 index 0000000000..428713e625 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-action-request-frame-parameters.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_SEND_ACTION_REQUEST_FRAME_PARAMETERS +author: windows-driver-content +description: WDI_TLV_P2P_SEND_ACTION_REQUEST_FRAME_PARAMETERS is a TLV that contains parameters for sending a Wi-Fi Direct action request frame with OID_WDI_TASK_P2P_SEND_REQUEST_ACTION_FRAME. +ms.assetid: 802654D0-CC8E-4808-8C1B-BAAF4C6E53F1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SEND_ACTION_REQUEST_FRAME_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SEND\_ACTION\_REQUEST\_FRAME\_PARAMETERS + + +WDI\_TLV\_P2P\_SEND\_ACTION\_REQUEST\_FRAME\_PARAMETERS is a TLV that contains parameters for sending a Wi-Fi Direct action request frame with [OID\_WDI\_TASK\_P2P\_SEND\_REQUEST\_ACTION\_FRAME](https://msdn.microsoft.com/library/windows/hardware/dn925956). + +## TLV Type + + +0x8B + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_P2P\_ACTION\_FRAME\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926086) | The type of request to send. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the target peer device. | +| UINT8 | The Direct Dialog Token for the transaction. | +| UINT32 | The send timeout. The maximum time, in milliseconds, to send the action frame. | +| UINT32 | The post-ACK dwell time. The time, in milliseconds, to remain on the listen channel after the incoming packet is acknowledged. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SEND_ACTION_REQUEST_FRAME_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-send-request-action-frame-result.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-request-action-frame-result.md new file mode 100644 index 0000000000..9dc7a06924 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-request-action-frame-result.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_P2P_SEND_REQUEST_ACTION_FRAME_RESULT +author: windows-driver-content +description: WDI_TLV_P2P_SEND_REQUEST_ACTION_FRAME_RESULT is an unused TLV. +ms.assetid: F819A33C-C9C7-4208-B236-338BDFEA7764 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SEND_REQUEST_ACTION_FRAME_RESULT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_RESULT + + +WDI\_TLV\_P2P\_SEND\_REQUEST\_ACTION\_FRAME\_RESULT is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SEND_REQUEST_ACTION_FRAME_RESULT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-send-response-action-frame-result.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-response-action-frame-result.md new file mode 100644 index 0000000000..5e62a1c2f6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-send-response-action-frame-result.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_P2P_SEND_RESPONSE_ACTION_FRAME_RESULT +author: windows-driver-content +description: WDI_TLV_P2P_SEND_RESPONSE_ACTION_FRAME_RESULT is an unused TLV. +ms.assetid: E1014E02-C17B-4161-82EF-47C880411A57 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SEND_RESPONSE_ACTION_FRAME_RESULT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_RESULT + + +WDI\_TLV\_P2P\_SEND\_RESPONSE\_ACTION\_FRAME\_RESULT is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SEND_RESPONSE_ACTION_FRAME_RESULT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-discovery-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-discovery-entry.md new file mode 100644 index 0000000000..938d12375a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-discovery-entry.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY is a TLV that contains a Service Information Discovery Entry. +ms.assetid: 344A1E76-26E0-4816-8BA5-24F4784B48A1 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY + + +WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_DISCOVERY\_ENTRY is a TLV that contains a Service Information Discovery Entry. + +## TLV Type + + +0x117 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------|--------------------------------|----------|---------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_P2P\_SERVICE\_NAME**](wdi-tlv-p2p-service-name.md) | | | Name of the service (UTF-8), up to 255 bytes. | +| [**WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH**](wdi-tlv-p2p-service-name-hash.md) | | | Hash of Service Name. | +| [**WDI\_TLV\_P2P\_SERVICE\_INFORMATION**](wdi-tlv-p2p-service-information.md) | | X | Request service information to be used for the ANQP query request to download service information for this Service. | +| [**WDI\_TLV\_P2P\_SERVICE\_UPDATE\_INDICATOR**](wdi-tlv-p2p-service-update-indicator.md) | | X | Service Update indicator to be used for the ANQP query request. | +| [**WDI\_TLV\_P2P\_SERVICE\_TRANSACTION\_ID**](wdi-tlv-p2p-service-transaction-id.md) | | X | Service transaction ID to be used for the ANQP query request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_INFORMATION_DISCOVERY_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-entry.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-entry.md new file mode 100644 index 0000000000..0ebc247bf2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information-entry.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_P2P_SERVICE_INFORMATION_ENTRY +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_INFORMATION_ENTRY is an unused TLV. +ms.assetid: E9848752-DC4B-44A2-96FA-C81E9E5795AA +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_INFORMATION_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_ENTRY + + +WDI\_TLV\_P2P\_SERVICE\_INFORMATION\_ENTRY is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_INFORMATION_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information.md new file mode 100644 index 0000000000..0d14a17ba6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-information.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_INFORMATION +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_INFORMATION is a TLV that contains Wi-Fi Direct Service Information. +ms.assetid: C377FA31-1D78-4087-A600-18F10D9022B6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_INFORMATION Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_INFORMATION + + +WDI\_TLV\_P2P\_SERVICE\_INFORMATION is a TLV that contains Wi-Fi Direct Service Information. + +## TLV Type + + +0xEE + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------------------| +| UINT8\[\] | The Service Information for the service. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_INFORMATION%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name-hash.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name-hash.md new file mode 100644 index 0000000000..10fbabab7f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name-hash.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_NAME_HASH +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_NAME_HASH is a TLV that contains the hash of a service name. +ms.assetid: C6204FA9-BDCB-4BF7-8590-FA019B0E41EC +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_NAME_HASH Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH + + +WDI\_TLV\_P2P\_SERVICE\_NAME\_HASH is a TLV that contains the hash of a service name. + +## TLV Type + + +0xED + +## Length + + +The size (in bytes) of a [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) structure. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|----------------------------------| +| [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) | The hash of a WFDS Service Name. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_NAME_HASH%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name.md new file mode 100644 index 0000000000..9475b2b408 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-name.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_NAME +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_NAME is a TLV that contains the name of a service. +ms.assetid: 6394F781-BFE7-4009-8F5E-72D7C8CCF036 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_NAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_NAME + + +WDI\_TLV\_P2P\_SERVICE\_NAME is a TLV that contains the name of a service. + +## TLV Type + + +0xEC + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|-----------------------------------------------------| +| UINT8\[\] | The name of the service, in UTF-8, up to 255 bytes. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_NAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-session-info.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-session-info.md new file mode 100644 index 0000000000..47437ee8cf --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-session-info.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_SESSION_INFO +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_SESSION_INFO is a TLV that contains Service Session information. +ms.assetid: ED1FF2F5-82BA-48AC-A986-8B75F099DCA0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_SESSION_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_SESSION\_INFO + + +WDI\_TLV\_P2P\_SERVICE\_SESSION\_INFO is a TLV that contains Service Session information. + +## TLV Type + + +0xF0 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------------| +| UINT8\[\] | Service Session Information. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_SESSION_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-status.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-status.md new file mode 100644 index 0000000000..ddf7dc0c78 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-status.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_STATUS +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_STATUS is a TLV that contains the Service Status of a service. +ms.assetid: C7001661-8496-4C5B-9AD2-EF92332AF377 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_STATUS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_STATUS + + +WDI\_TLV\_P2P\_SERVICE\_STATUS is a TLV that contains the Service Status of a service. + +## TLV Type + + +0xFB + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|----------------------------------| +| UINT8 | The Service Status of a service. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_STATUS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-transaction-id.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-transaction-id.md new file mode 100644 index 0000000000..d29f79cb64 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-transaction-id.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_TRANSACTION_ID +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_TRANSACTION_ID is a TLV that contains the Service transaction ID to be used for the ANQP query request. +ms.assetid: 93CBE158-4595-40FC-A574-B818B2324DBF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_TRANSACTION_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_TRANSACTION\_ID + + +WDI\_TLV\_P2P\_SERVICE\_TRANSACTION\_ID is a TLV that contains the Service transaction ID to be used for the ANQP query request. + +## TLV Type + + +0x116 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-------------------------------------------------------------------| +| UINT8 | The Service transaction ID to be used for the ANQP query request. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_TRANSACTION_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type-hash.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type-hash.md new file mode 100644 index 0000000000..65c5aeba15 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type-hash.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_SERVICE_TYPE_HASH +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_TYPE_HASH is a TLV that contains the hash of Service Type. +ms.assetid: A475C2E3-F558-47EC-9708-87887AE2D8AF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_TYPE_HASH Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_TYPE\_HASH + + +WDI\_TLV\_P2P\_SERVICE\_TYPE\_HASH is a TLV that contains the hash of Service Type. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x12A + +## Length + + +The size (in bytes) of a [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) structure. + +## Values + + +| Type | Description | +|-------------------------------------------------------------------------|---------------------------| +| [**WDI\_P2P\_SERVICE\_NAME\_HASH**](https://msdn.microsoft.com/library/windows/hardware/dn926103) | The hash of Service Type. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_TYPE_HASH%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type.md new file mode 100644 index 0000000000..356dc5729b --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-type.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_P2P_SERVICE_TYPE +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_TYPE is a TLV that contains the Service Type of the service. +ms.assetid: D9C3F099-DED1-400E-9D3F-7AF6D2D286DF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_TYPE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_TYPE + + +WDI\_TLV\_P2P\_SERVICE\_TYPE is a TLV that contains the Service Type of the service. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x129 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------------------| +| UINT8\[\] | The Service Type of the service in UTF-8, up to 21 bytes long. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_TYPE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-service-update-indicator.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-update-indicator.md new file mode 100644 index 0000000000..0872d8ce6f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-service-update-indicator.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR +author: windows-driver-content +description: WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR is a TLV that contains a Wi-Fi Direct service update indicator. +ms.assetid: C90579C9-55DD-4E32-BEA3-EB156F4A422C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_SERVICE\_UPDATE\_INDICATOR + + +WDI\_TLV\_P2P\_SERVICE\_UPDATE\_INDICATOR is a TLV that contains a Wi-Fi Direct service update indicator. + +## TLV Type + + +0x115 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------| +| UINT16 | The service update indicator to include in ANQP responses if the driver supports responding to service information discovery ANQP requests. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_SERVICE_UPDATE_INDICATOR%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-p2p-wps-enabled.md b/windows-driver-docs-pr/network/wdi-tlv-p2p-wps-enabled.md new file mode 100644 index 0000000000..205f36e41e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-p2p-wps-enabled.md @@ -0,0 +1,92 @@ +--- +title: WDI_TLV_P2P_WPS_ENABLED +author: windows-driver-content +description: WDI_TLV_P2P_WPS_ENABLED is a TLV that specifies if Wi-Fi Protected Setup is enabled. +ms.assetid: B923DA17-451C-4BF1-8B8B-C2846EDE9774 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_P2P_WPS_ENABLED Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_P2P\_WPS\_ENABLED + + +WDI\_TLV\_P2P\_WPS\_ENABLED is a TLV that specifies if Wi-Fi Protected Setup is enabled. + +## TLV Type + + +0xF7 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT8Specifies if Wi-Fi Protected Setup is enabled. +

Valid values are 0 (not enabled) and 1 (enabled).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_SET\_P2P\_WPS\_ENABLED](https://msdn.microsoft.com/library/windows/hardware/dn925938) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_P2P_WPS_ENABLED%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-packet-filter-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-packet-filter-parameters.md new file mode 100644 index 0000000000..8fab728d4c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-packet-filter-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PACKET_FILTER_PARAMETERS +author: windows-driver-content +description: WDI_TLV_PACKET_FILTER_PARAMETERS is a TLV that contains packet filter parameters for OID_WDI_SET_RECEIVE_PACKET_FILTER. +ms.assetid: 5B26DA60-BC5D-4CC5-A620-C076CECF22C0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PACKET_FILTER_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PACKET\_FILTER\_PARAMETERS + + +WDI\_TLV\_PACKET\_FILTER\_PARAMETERS is a TLV that contains packet filter parameters for [OID\_WDI\_SET\_RECEIVE\_PACKET\_FILTER](https://msdn.microsoft.com/library/windows/hardware/dn925942). + +## TLV Type + + +0x47 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|---------------------------------------------------------------------------|--------------------------------------------| +| [**WDI\_PACKET\_FILTER\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926104) (UINT32) | Specifies the desired Wi-Fi packet filter. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PACKET_FILTER_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-peer-mac-address.md b/windows-driver-docs-pr/network/wdi-tlv-peer-mac-address.md new file mode 100644 index 0000000000..87da037aba --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-peer-mac-address.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PEER_MAC_ADDRESS +author: windows-driver-content +description: WDI_TLV_PEER_MAC_ADDRESS is a TLV that contains the MAC address of the peer. +ms.assetid: A936BAA6-96AD-4187-9933-FA02CCFED2AE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PEER_MAC_ADDRESS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PEER\_MAC\_ADDRESS + + +WDI\_TLV\_PEER\_MAC\_ADDRESS is a TLV that contains the MAC address of the peer. + +## TLV Type + + +0x4C + +## Length + + +The size (in bytes) of a [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) structure. + +## Values + + +| Type | Description | +|---------------------------------------------------|----------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the Wi-Fi MAC address of the peer. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PEER_MAC_ADDRESS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-phy-capabilities.md new file mode 100644 index 0000000000..93bfb7e888 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-capabilities.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_PHY_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_PHY_CAPABILITIES is a TLV that contains PHY capabilities. +ms.assetid: 8F482ED6-6594-4DB5-B53B-4424DAD32D36 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_CAPABILITIES + + +WDI\_TLV\_PHY\_CAPABILITIES is a TLV that contains PHY capabilities. + +## TLV Type + + +0x1B + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------|----------------------------------------------------| +| [**WDI\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926105) | Specifies the PHY types. | +| UINT8 | Specifies whether or not the PHY supports CF Poll. | +| UINT32 | Specifies the MPDU maximum length. | +| UINT32 | Specifies the operating temperature class. | +| UINT32 | Specifies the antenna diversity support. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-data-rate-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-data-rate-list.md new file mode 100644 index 0000000000..f360933c8f --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-data-rate-list.md @@ -0,0 +1,84 @@ +--- +title: WDI_TLV_PHY_DATA_RATE_LIST +author: windows-driver-content +description: WDI_TLV_PHY_DATA_RATE_LIST is a TLV that contains a list of data rates. +ms.assetid: FFD28866-4983-4C0B-A74D-4EF9A819571E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_DATA_RATE_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_DATA\_RATE\_LIST + + +WDI\_TLV\_PHY\_DATA\_RATE\_LIST is a TLV that contains a list of data rates. + +## TLV Type + + +0x13 + +## Length + + +The size (in bytes) of the array of WDI\_DATA\_RATE\_LIST elements. The array must contain 1 or more elements. + +**Note**  WDI\_DATA\_RATE\_LIST is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|---------------------------|---------------------------------------------------------------------------------------------------------| +| WDI\_DATA\_RATE\_LIST\[\] | An array of data rates. Each data rate in the array must contain data rate flags and a data rate value. | + +  + +WDI\_DATA\_RATE\_LIST consists of the following elements. + +| Type | Description | +|--------|-----------------------------------------------------------------------------------------------| +| UINT8 | The data rate flags as defined in [**WDI\_DATA\_RATE\_FLAGS**](https://msdn.microsoft.com/library/windows/hardware/dn897811). | +| UINT16 | The data rate value. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_DATA_RATE_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-info.md b/windows-driver-docs-pr/network/wdi-tlv-phy-info.md new file mode 100644 index 0000000000..73ee6d5752 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_PHY_INFO +author: windows-driver-content +description: WDI_TLV_PHY_INFO is a TLV that contains PHY information. +ms.assetid: 3A363FDC-FE79-42C4-AD19-A6B960857CBD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_INFO + + +WDI\_TLV\_PHY\_INFO is a TLV that contains PHY information. + +## TLV Type + + +0x26 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------|--------------------------------|----------|----------------------------| +| [**WDI\_TLV\_PHY\_CAPABILITIES**](wdi-tlv-phy-capabilities.md) | | | The phy capabilities. | +| [**WDI\_TLV\_PHY\_TX\_POWER\_LEVEL\_LIST**](wdi-tlv-phy-tx-power-level-list.md) | | | A list of TX power levels. | +| [**WDI\_TLV\_PHY\_DATA\_RATE\_LIST**](wdi-tlv-phy-data-rate-list.md) | | | A list of data rates. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-list.md new file mode 100644 index 0000000000..5c21e3caef --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-list.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_PHY_LIST +author: windows-driver-content +description: WDI_TLV_PHY_LIST is an unused TLV. +ms.assetid: C05BCEAB-B44B-4DF4-99E6-848C99234C3B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_LIST + + +WDI\_TLV\_PHY\_LIST is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-statistics.md b/windows-driver-docs-pr/network/wdi-tlv-phy-statistics.md new file mode 100644 index 0000000000..d0739ebece --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-statistics.md @@ -0,0 +1,161 @@ +--- +title: WDI_TLV_PHY_STATISTICS +author: windows-driver-content +description: WDI_TLV_PHY_STATISTICS is a TLV that contains per-PHY statistics for OID_WDI_GET_STATISTICS. +ms.assetid: 2F27FF4E-54AC-4518-AEB0-3518FBC8BE0F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_STATISTICS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_STATISTICS + + +WDI\_TLV\_PHY\_STATISTICS is a TLV that contains per-PHY statistics for [OID\_WDI\_GET\_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/dn925850). + +## TLV Type + + +0xA7 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
[WDI_PHY_TYPE](https://msdn.microsoft.com/library/windows/hardware/dn926105)The type for this PHY.
UINT64The number of MSDU packets and MMPDU frames that the IEEE PHY layer of the 802.11 station has successfully transmitted.
UINT64The number of multicast or broadcast MSDU packets and MMPDU frames that the IEEE PHY layer of the 802.11 station has successfully transmitted.
UINT64The number of MSDU packets and MMPDU frames that the 802.11 station failed to transmit after exceeding the retry limits defined by the 802.11 IEEE dot11ShortRetryLimit or dot11LongRetryLimit MIB counters.
UINT64The number of MSDU packets and MMPDU frames that the 802.11 station successfully transmitted after one or more attempts.
UINT64The number of MSDU packets and MMPDU frames that the 802.11 station successfully transmitted after more than one retransmission attempts. +

For MSDU packets, the port must increment this counter for each packet that was transmitted successfully after one or more of its MPDU fragments required retransmission.

UINT64The number of MSDU packets and MMPDU frames that the 802.11 station failed to transmit because of a timeout as defined by the IEEE 802.11 dot11MaxTransmitMSDULifetime MIB object.
UINT64The number of MPDU frames that the 802.11 station transmitted and acknowledged through a received 802.11 ACK frame.
UINT64The number of times that the 802.11 station received a Clear To Send (CTS) frame in response to a Request To Send (RTS) frame. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number of times that the 802.11 station did not receive a CTS frame in response to an RTS frame. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number of times that the 802.11 station expected and did not receive an Acknowledgment (ACK) frame. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number of MSDU packets and MMPDU frames that the 802.11 station has successfully received. +

For MSDU packets, the port must increment this counter for each packet whose MPDU fragments were received and passed frame check sequence (FCS) verification and replay detection. The port must increment this member regardless of whether the received MSDU packet or MPDU fragment fail MAC-layer cipher decryption.

UINT64The number of multicast or broadcast MSDU packets and MMPDU frames that the 802.11 station has successfully received. +

For MSDU packets, the port must increment this counter for each packet whose MPDU fragments were received and passed FCS verification and replay detection. The port must increment this member regardless of whether the received MSDU packet or MPDU fragment fail MAC-layer cipher decryption.

UINT64The number of MSDU packets or MMPDU frames received by the 802.11 station when a promiscuous packet filter is enabled. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number if MSDU packets and MMPDU frames that the 802.11 station discarded because of a timeout as defined by the IEEE 802.11 dot11MaxReceiveLifetime MIB object. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number of duplicate MPDU frames that the 802.11 station received. The 802.11 station determines duplicate frames through the Sequence Control field of the 802.11 MAC header. If this cannot be maintained per port, it can be maintained per channel.
UINT64The number of MPDU frames received by the 802.11 station for MSDU packets or MMPDU frames.
UINT64The number of MPDU frames received by the 802.11 station for MSDU packets or MMPDU frames when a promiscuous packet filter was enabled.
UINT64The number of MPDU frames that the 802.11 station received with FCS errors. If this cannot be maintained per port, it can be maintained per channel.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_STATISTICS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-supported-rx-data-rates-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-supported-rx-data-rates-list.md new file mode 100644 index 0000000000..f7ec29b128 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-supported-rx-data-rates-list.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_PHY_SUPPORTED_RX_DATA_RATES_LIST +author: windows-driver-content +description: WDI_TLV_PHY_SUPPORTED_RX_DATA_RATES_LIST is an unused TLV. +ms.assetid: B034CBE0-EAC2-4EBE-BF7D-A5D05E792AD0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_SUPPORTED_RX_DATA_RATES_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_SUPPORTED\_RX\_DATA\_RATES\_LIST + + +WDI\_TLV\_PHY\_SUPPORTED\_RX\_DATA\_RATES\_LIST is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_SUPPORTED_RX_DATA_RATES_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-supported-tx-data-rates-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-supported-tx-data-rates-list.md new file mode 100644 index 0000000000..a266850271 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-supported-tx-data-rates-list.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_PHY_SUPPORTED_TX_DATA_RATES_LIST +author: windows-driver-content +description: WDI_TLV_PHY_SUPPORTED_TX_DATA_RATES_LIST is an unused TLV. +ms.assetid: 27C441C5-BAC3-43F3-97FE-481CD7241D6A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_SUPPORTED_TX_DATA_RATES_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_SUPPORTED\_TX\_DATA\_RATES\_LIST + + +WDI\_TLV\_PHY\_SUPPORTED\_TX\_DATA\_RATES\_LIST is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_SUPPORTED_TX_DATA_RATES_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-tx-power-level-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-tx-power-level-list.md new file mode 100644 index 0000000000..b6036cbbcc --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-tx-power-level-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PHY_TX_POWER_LEVEL_LIST +author: windows-driver-content +description: WDI_TLV_PHY_TX_POWER_LEVEL_LIST is a TLV that contains a list of power levels. +ms.assetid: DDBF9BBA-9700-4FD2-9521-6D0970E99893 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_TX_POWER_LEVEL_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_TX\_POWER\_LEVEL\_LIST + + +WDI\_TLV\_PHY\_TX\_POWER\_LEVEL\_LIST is a TLV that contains a list of power levels. + +## TLV Type + + +0x1C + +## Length + + +The size (in bytes) of the array of UINT32 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|------------|----------------------------------------------------------| +| UINT32\[\] | An array of UINT32 elements that specifies power levels. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_TX_POWER_LEVEL_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-type-list--disabled.md b/windows-driver-docs-pr/network/wdi-tlv-phy-type-list--disabled.md new file mode 100644 index 0000000000..1babf8ef87 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-type-list--disabled.md @@ -0,0 +1,62 @@ +--- +title: WDI_TLV_PHY_TYPE_LIST (unused) +author: windows-driver-content +description: WDI_TLV_PHY_TYPE_LIST (0x69) is an unused TLV. +ms.assetid: FBC425DB-6822-48CA-9340-2436891F7857 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_TYPE_LIST (unused) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_TYPE\_LIST (unused) + + +WDI\_TLV\_PHY\_TYPE\_LIST (0x69) is an unused TLV. + +## TLV Type + + +0x69 + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[**WDI\_TLV\_PHY\_TYPE\_LIST**](wdi-tlv-phy-type-list.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_TYPE_LIST%20%28unused%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-type-list.md b/windows-driver-docs-pr/network/wdi-tlv-phy-type-list.md new file mode 100644 index 0000000000..b9dfc7c0d0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-type-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PHY_TYPE_LIST +author: windows-driver-content +description: WDI_TLV_PHY_TYPE_LIST is a TLV that contains an array of PHY types. +ms.assetid: 4066E4CE-D63E-4499-AE27-11F6BD57795D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_TYPE_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_TYPE\_LIST + + +WDI\_TLV\_PHY\_TYPE\_LIST is a TLV that contains an array of PHY types. + +## TLV Type + + +0x19 + +## Length + + +The size (in bytes) of the array of [**WDI\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926105) values. The array must contain 1 or more values. + +## Values + + +| Type | Description | +|-------------------------------------------------|------------------------------| +| [**WDI\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926105)\[\] | An array of PHY type values. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_TYPE_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-phy-type.md b/windows-driver-docs-pr/network/wdi-tlv-phy-type.md new file mode 100644 index 0000000000..14ee0ba074 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-phy-type.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PHY_TYPE +author: windows-driver-content +description: WDI_TLV_PHY_TYPE is a TLV that contains a PHY type. +ms.assetid: 0CEC5B02-EA75-4B04-84AE-6079A294F542 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PHY_TYPE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PHY\_TYPE + + +WDI\_TLV\_PHY\_TYPE is a TLV that contains a PHY type. + +## TLV Type + + +0x122 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|------------------------------------------------------|---------------| +| [**WDI\_PHY\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926105) (UINT32) | The PHY type. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PHY_TYPE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pldr-support.md b/windows-driver-docs-pr/network/wdi-tlv-pldr-support.md new file mode 100644 index 0000000000..52bcc1c9d2 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pldr-support.md @@ -0,0 +1,80 @@ +--- +title: WDI_TLV_PLDR_SUPPORT +author: windows-driver-content +description: WDI_TLV_PLDR_SUPPORT is a TLV that specifies if PLDR (Platform Level Reset) is supported. +ms.assetid: BC1BE1A7-AA2D-4D11-A75A-EC0143343F33 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PLDR_SUPPORT Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PLDR\_SUPPORT + + +WDI\_TLV\_PLDR\_SUPPORT is a TLV that specifies if PLDR (Platform Level Reset) is supported. + +**Note**  This TLV was added in Windows 10, version 1511, WDI version 1.0.10. + +  + +## TLV Type + + +0x11A + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies if PLDR is supported. This value is set to 0 if the device or bus does not support reset functionality (usually by querying the ACPI or PCI methods). A non-zero value specifies that reset functionality is supported. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[PLDR](https://msdn.microsoft.com/library/windows/hardware/mt269098) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PLDR_SUPPORT%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-pm-capabilities.md new file mode 100644 index 0000000000..631d30d7a9 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-capabilities.md @@ -0,0 +1,171 @@ +--- +title: WDI_TLV_PM_CAPABILITIES (0x42) +author: windows-driver-content +description: WDI_TLV_PM_CAPABILITIES is a TLV that contains power management capabilities. +ms.assetid: DE8A5333-BE2B-4CBB-8C75-45ABBE35A635 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_CAPABILITIES (0x42) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_CAPABILITIES (0x42) + + +WDI\_TLV\_PM\_CAPABILITIES is a TLV that contains power management capabilities. + +## TLV Type + + +0x42 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Specifies the power management supported flags. +

Valid flags are:

+
    +
  • NDIS_PM_WAKE_PACKET_INDICATION_SUPPORTED
  • +
  • NDIS_PM_SELECTIVE_SUSPEND_SUPPORTED (0x00000002)
  • +
UINT32Specifies the supported Wake-on-LAN patterns. +

Valid patterns are:

+
    +
  • NDIS_PM_WOL_BITMAP_PATTERN_SUPPORTED (0x00000001)
  • +
  • NDIS_PM_WOL_MAGIC_PACKET_SUPPORTED (0x00000002)
  • +
  • NDIS_PM_WOL_IPV4_TCP_SYN_SUPPORTED (0x00000004)
  • +
  • NDIS_PM_WOL_IPV6_TCP_SYN_SUPPORTED (0x00000008)
  • +
  • NDIS_PM_WOL_IPV4_DEST_ADDR_WILDCARD_SUPPORTED (0x00000200)
  • +
  • NDIS_PM_WOL_IPV6_DEST_ADDR_WILDCARD_SUPPORTED (0x00000800)
  • +
  • NDIS_PM_WOL_EAPOL_REQUEST_ID_MESSAGE_SUPPORTED (0x00010000)
  • +
UINT32Specifies the total number of Wake-on-LAN patterns.
UINT32Specifies the maximum Wake-on-LAN pattern size.
UINT32Specifies the maximum Wake-on-LAN pattern offset.
UINT32Specifies the maximum Wake-on-LAN packet save buffer.
UINT32Specifies the supported protocol offloads. +

Valid offloads are:

+
    +
  • NDIS_PM_PROTOCOL_OFFLOAD_ARP_SUPPORTED (0x00000001)
  • +
  • NDIS_PM_PROTOCOL_OFFLOAD_NS_SUPPORTED (0x00000002)
  • +
  • NDIS_PM_PROTOCOL_OFFLOAD_80211_RSN_REKEY_SUPPORTED (0x00000080)
  • +
UINT32Specifies the number of ARP offload IPv4 addresses.
UINT32Specifies the number of NS offload IPv6 addresses.
[NDIS_DEVICE_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/gg602135)Specifies the minimum magic packet wake-up.
[NDIS_DEVICE_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/gg602135)Specifies the minimum pattern wake-up.
[NDIS_DEVICE_POWER_STATE](https://msdn.microsoft.com/library/windows/hardware/gg602135)Specifies the minimum link change wake-up.
UINT32Specifies the supported wake-up events. +

Valid events are:

+
    +
  • NDIS_PM_WAKE_ON_MEDIA_CONNECT_SUPPORTED (0x00000001)
  • +
  • NDIS_PM_WAKE_ON_MEDIA_DISCONNECT_SUPPORTED (0x00000002)
  • +
UINT32Specifies the media-specific wake-up events. +

Valid events are:

+
    +
  • NDIS_WLAN_WAKE_ON_NLO_DISCOVERY_SUPPORTED (0x00000001)
  • +
  • NDIS_WLAN_WAKE_ON_AP_ASSOCIATION_LOST_SUPPORTED (0x00000002)
  • +
  • NDIS_WLAN_WAKE_ON_GTK_HANDSHAKE_ERROR_SUPPORTED (0x00000004)
  • +
  • NDIS_WLAN_WAKE_ON_4WAY_HANDSHAKE_REQUEST_SUPPORTED (0x00000008)
  • +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_CAPABILITIES%20%280x42%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-80211rsn-rekey.md b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-80211rsn-rekey.md new file mode 100644 index 0000000000..eff9a49a5a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-80211rsn-rekey.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_PM_PROTOCOL_OFFLOAD_80211RSN_REKEY +author: windows-driver-content +description: WDI_TLV_PM_PROTOCOL_OFFLOAD_80211RSN_REKEY is a TLV that contains RSN Rekey protocol offload parameters. +ms.assetid: 4FDB56EA-444B-4EA2-B8D1-5E740734EEED +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_PROTOCOL_OFFLOAD_80211RSN_REKEY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_80211RSN\_REKEY + + +WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_80211RSN\_REKEY is a TLV that contains RSN Rekey protocol offload parameters. + +## TLV Type + + +0x63 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the protocol offload ID. This is an OS-provided value that identifies the offloaded protocol. Before the OS sends an Add request down or completes the request to the overlying driver, the OS sets ProtocolOffloadId to a value that is unique among the protocol offloads on a network adapter. | +| UINT64 | Specifies the replay counter. | +| UINT8\[16\] | Specifies the IEEE 802.11 key confirmation key (KCK). | +| UINT8\[16\] | Specifies the IEEE 802.11 key encryption key (KEK). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_PROTOCOL_OFFLOAD_80211RSN_REKEY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-get.md b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-get.md new file mode 100644 index 0000000000..07438bc308 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-get.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PM_PROTOCOL_OFFLOAD_GET +author: windows-driver-content +description: WDI_TLV_PM_PROTOCOL_OFFLOAD_GET is a TLV that contains a protocol offload ID for OID_WDI_GET_PM_PROTOCOL_OFFLOAD. +ms.assetid: 71BBAA8F-0EE3-4315-AEB1-E9FD394218AD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_PROTOCOL_OFFLOAD_GET Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_GET + + +WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_GET is a TLV that contains a protocol offload ID for [OID\_WDI\_GET\_PM\_PROTOCOL\_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/dn925846). + +## TLV Type + + +0xA8 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the protocol offload ID. This is an OS-provided value that identifies the offloaded protocol. Before the OS sends an Add request down or completes the request to the overlying driver, the OS sets ProtocolOffloadId to a value that is unique among the protocol offloads on a network adapter. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_PROTOCOL_OFFLOAD_GET%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv4arp.md b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv4arp.md new file mode 100644 index 0000000000..8480aad638 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv4arp.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv4ARP +author: windows-driver-content +description: WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv4ARP is a TLV that contains IPv4 ARP protocol offload parameters. +ms.assetid: 03894B22-3D4B-4262-893A-660FC88AA93D +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv4ARP Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv4ARP + + +WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv4ARP is a TLV that contains IPv4 ARP protocol offload parameters. + +## TLV Type + + +0x61 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the protocol offload ID. This is an OS-provided value that identifies the offloaded protocol. Before the OS sends an Add request down or completes the request to the overlying driver, the OS sets ProtocolOffloadId to a value that is unique among the protocol offloads on a network adapter. | +| UINT8\[4\] | Specifies an optional IPv4 address to match with the Source Protocol Address (SPA) field of the ARP request. If the incoming ARP request has an SPA value that matches this IPv4 address, the network adapter sends an ARP response when it is in a low power state. If this is set to zero, the network adapter should respond to ARP requests from any remote IPv4 address. | +| UINT8\[4\] | Specifies the host IPv4 address the network adapter uses for the Source Protocol Address (SPA) field when sending an ARP response. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the MAC address that the network adapter must use for the Source Hardware Address (SHA) field of the ARP response packet that it generates. However, it should use the current MAC address of the network adapter as the source address in the MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv4ARP%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv6ns.md b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv6ns.md new file mode 100644 index 0000000000..ac9639ceef --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-ipv6ns.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv6NS +author: windows-driver-content +description: WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv6NS is a TLV that contains IPv6 NS protocol offload parameters. +ms.assetid: 0385449B-82C6-44B4-BBD3-A708ADE54AC4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv6NS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv6NS + + +WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_IPv6NS is a TLV that contains IPv6 NS protocol offload parameters. + +## TLV Type + + +0x62 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the protocol offload ID. This is an OS-provided value that identifies the offloaded protocol. Before the OS sends an Add request down or completes the request to the overlying driver, the OS sets ProtocolOffloadId to a value that is unique among the protocol offloads on a network adapter. | +| UINT8\[16\] | Specifies an optional IPv6 address to match with the Source Address field in the IPv6 header of the NS message. If the incoming NS message has a Source Address value that matches this IPv6 address, the network adapter sends a neighbor advertisement (NA) message when it is in a low power state. If this is set to zero, the network adapter should respond to NS messages from any remote IPv6 address. | +| UINT8\[16\] | Specifies the solicited node IPv6 address. | +| UINT8\[16\] | Specifies one or two IPv6 addresses to match the Target Address field of an incoming NS message. If there is only one address, that address is stored in Target address 1, and Target address 2 is filled with zeros. If one of these addresses matches the Target Address field of an incoming NS message, the network adapter sends an NA message in response. | +| UINT8\[16\] | See description of Target address 1. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the MAC address that the network adapter must use for the target link-layer address (TLLA) field of the NA message that it generates. However, it should use the current MAC address of the network adapter as the source address in the MAC header. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_PROTOCOL_OFFLOAD_IPv6NS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-remove.md b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-remove.md new file mode 100644 index 0000000000..cc0a35d24d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pm-protocol-offload-remove.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PM_PROTOCOL_OFFLOAD_REMOVE +author: windows-driver-content +description: WDI_TLV_PM_PROTOCOL_OFFLOAD_REMOVE is a TLV that contains the protocol offload ID to be removed with OID_WDI_SET_REMOVE_PM_PROTOCOL_OFFLOAD. +ms.assetid: BD74C9F7-6370-41D5-841F-6949D7748E30 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PM_PROTOCOL_OFFLOAD_REMOVE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_REMOVE + + +WDI\_TLV\_PM\_PROTOCOL\_OFFLOAD\_REMOVE is a TLV that contains the protocol offload ID to be removed with [OID\_WDI\_SET\_REMOVE\_PM\_PROTOCOL\_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/dn925943). + +## TLV Type + + +0x6C + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|------------------------------------| +| UINT32 | Specifies the protocol offload ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PM_PROTOCOL_OFFLOAD_REMOVE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-pmkid.md b/windows-driver-docs-pr/network/wdi-tlv-pmkid.md new file mode 100644 index 0000000000..2bacd5b641 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-pmkid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PMKID +author: windows-driver-content +description: WDI_TLV_PMKID is a TLV that contains a PMKID value. +ms.assetid: 6873928B-7843-434F-AB80-6A7895D751A4 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PMKID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PMKID + + +WDI\_TLV\_PMKID is a TLV that contains a PMKID value. + +## TLV Type + + +0x9F + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|------------------------| +| UINT8\[\] | A 16-byte PMKID value. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PMKID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-port-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-port-attributes.md new file mode 100644 index 0000000000..9a17608d7c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-port-attributes.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_PORT_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_PORT_ATTRIBUTES is a TLV that contains port attributes. +ms.assetid: F5A0BC8D-1B86-41C2-A530-860E15775695 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PORT_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PORT\_ATTRIBUTES + + +WDI\_TLV\_PORT\_ATTRIBUTES is a TLV that contains port attributes. + +## TLV Type + + +0x29 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-----------------------------------------------------| +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the MAC address associated with the port. | +| UINT16 | Specifies the port number. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PORT_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-power-managment-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-power-managment-capabilities.md new file mode 100644 index 0000000000..e19c797db1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-power-managment-capabilities.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_POWER_MANAGMENT_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_POWER_MANAGMENT_CAPABILITIES is an unused TLV. +ms.assetid: 6DD19576-4762-4460-8134-45D4270D9FAE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_POWER_MANAGMENT_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_POWER\_MANAGMENT\_CAPABILITIES + + +WDI\_TLV\_POWER\_MANAGMENT\_CAPABILITIES is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_POWER_MANAGMENT_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-power-state.md b/windows-driver-docs-pr/network/wdi-tlv-power-state.md new file mode 100644 index 0000000000..f6976ab67c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-power-state.md @@ -0,0 +1,92 @@ +--- +title: WDI_TLV_POWER_STATE +author: windows-driver-content +description: WDI_TLV_POWER_STATE is a TLV that contains a power state. +ms.assetid: EC65FE08-ABF0-488A-A6FA-21B1794418B3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_POWER_STATE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_POWER\_STATE + + +WDI\_TLV\_POWER\_STATE is a TLV that contains a power state. + +## TLV Type + + +0x44 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT32Specifies a power state. +

Valid values are:

+
    +
  • 0x0001: Exit low power (D0)
  • +
  • 0x0003: Enter low power (D2)
  • +
  • 0x0004: Enter power off (D3, may not actually be powered off on some platforms)
  • +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_POWER_STATE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-privacy-exemption-entry.md b/windows-driver-docs-pr/network/wdi-tlv-privacy-exemption-entry.md new file mode 100644 index 0000000000..adf4370b54 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-privacy-exemption-entry.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_PRIVACY_EXEMPTION_ENTRY +author: windows-driver-content +description: WDI_TLV_PRIVACY_EXEMPTION_ENTRY is a TLV that contains a privacy exemption entry. +ms.assetid: 086BD366-F54C-4BF4-8544-CC2AB2472EB2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PRIVACY_EXEMPTION_ENTRY Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PRIVACY\_EXEMPTION\_ENTRY + + +WDI\_TLV\_PRIVACY\_EXEMPTION\_ENTRY is a TLV that contains a privacy exemption entry. + +## TLV Type + + +0x48 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|------------------------------------------------------------------------|-------------------------------------------------------------| +| UINT16 | Specifies the IEEE EtherType in big-endian byte order. | +| [**WDI\_EXEMPTION\_ACTION\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn897820) | Specifies the action type of the exemption. | +| [**WDI\_EXEMPTION\_PACKET\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn897823) | Specifies the type of packet that the exemption applies to. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PRIVACY_EXEMPTION_ENTRY%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-probe-response-frame.md b/windows-driver-docs-pr/network/wdi-tlv-probe-response-frame.md new file mode 100644 index 0000000000..70dd36c278 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-probe-response-frame.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_PROBE_RESPONSE_FRAME +author: windows-driver-content +description: WDI_TLV_PROBE_RESPONSE_FRAME is a TLV that contains a probe response frame. +ms.assetid: 600019AB-55D2-4EE1-9500-0AFCB07C3AB2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_PROBE_RESPONSE_FRAME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_PROBE\_RESPONSE\_FRAME + + +WDI\_TLV\_PROBE\_RESPONSE\_FRAME is a TLV that contains a probe response frame. + +## TLV Type + + +0x9 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|---------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the probe response frame. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_PROBE_RESPONSE_FRAME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-radio-state-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-radio-state-parameters.md new file mode 100644 index 0000000000..287048da46 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-radio-state-parameters.md @@ -0,0 +1,87 @@ +--- +title: WDI_TLV_RADIO_STATE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_RADIO_STATE_PARAMETERS is a TLV that contains radio state parameters for OID_WDI_TASK_SET_RADIO_STATE. +ms.assetid: D977DF8A-146C-4921-AE7C-5FBEC7FBA4C8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RADIO_STATE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RADIO\_STATE\_PARAMETERS + + +WDI\_TLV\_RADIO\_STATE\_PARAMETERS is a TLV that contains radio state parameters for [OID\_WDI\_TASK\_SET\_RADIO\_STATE](https://msdn.microsoft.com/library/windows/hardware/dn925963). + +## TLV Type + + +0xA0 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT8The desired radio state. +

Valid values are 0 (the radio is turned off) and 1 (the radio is enabled).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RADIO_STATE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-radio-state.md b/windows-driver-docs-pr/network/wdi-tlv-radio-state.md new file mode 100644 index 0000000000..c5d62eb6e7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-radio-state.md @@ -0,0 +1,92 @@ +--- +title: WDI_TLV_RADIO_STATE +author: windows-driver-content +description: WDI_TLV_RADIO_STATE is a TLV that contains the state of the radio in hardware and software. +ms.assetid: 0DAE1D0A-4EEC-4054-A67C-EC3B5EDF77A5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RADIO_STATE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RADIO\_STATE + + +WDI\_TLV\_RADIO\_STATE is a TLV that contains the state of the radio in hardware and software. + +## TLV Type + + +0xA1 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + +
TypeDescription
UINT8The current state of the radio in hardware. +

Valid values are 0 and 1.

UINT8The current state of the radio in software. +

Valid values are 0 and 1.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RADIO_STATE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-receive-coalesce-offload-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-receive-coalesce-offload-capabilities.md new file mode 100644 index 0000000000..d4717805a0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-receive-coalesce-offload-capabilities.md @@ -0,0 +1,92 @@ +--- +title: WDI_TLV_RECEIVE_COALESCE_OFFLOAD_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_RECEIVE_COALESCE_OFFLOAD_CAPABILITIES is a TLV that contains Rx coalesce offload capabilities. +ms.assetid: AF13B304-3E94-42EE-8BBB-107F5F238758 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RECEIVE_COALESCE_OFFLOAD_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RECEIVE\_COALESCE\_OFFLOAD\_CAPABILITIES + + +WDI\_TLV\_RECEIVE\_COALESCE\_OFFLOAD\_CAPABILITIES is a TLV that contains Rx coalesce offload capabilities. + +## TLV Type + + +0xCE + +## Length + + +The size (in bytes) of the below values. + +## Values + + + ++++ + + + + + + + + + + + + + + + + +
TypeDescription
UINT8Specifies whether or not Rx coalesce is enabled for IPv4. +

Valid values are 0 (not enabled) and 1 (enabled).

UINT8Specifies whether or not Rx coalesce is enabled for IPv6. +

Valid values are 0 (not enabled) and 1 (enabled).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RECEIVE_COALESCE_OFFLOAD_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-capabilities.md new file mode 100644 index 0000000000..fb11ed398d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-capabilities.md @@ -0,0 +1,341 @@ +--- +title: WDI_TLV_RECEIVE_COALESCING_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_RECEIVE_COALESCING_CAPABILITIES is a TLV that contains hardware assisted receive filter capabilities. +ms.assetid: 87BC1F55-90C6-4B22-9E8E-A54FF42515F3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RECEIVE_COALESCING_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RECEIVE\_COALESCING\_CAPABILITIES + + +WDI\_TLV\_RECEIVE\_COALESCING\_CAPABILITIES is a TLV that contains hardware assisted receive filter capabilities. + +## TLV Type + + +0x9A + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Enabled filter types. A bitwise OR of flags that specify the types of receive filters that are enabled. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_VMQ_FILTERS_ENABLED
+

Specifies that VMQ filters are enabled.

+
+
NDIS_RECEIVE_FILTER_PACKET_COALESCING_FILTERS_ENABLED
+

Specifies that NDIS packet coalescing receive filters are enabled.

+
+
UINT32Enabled queue types. A bitwise OR of flags that specify the types of receive queues that are enabled. The following flag is valid. +

+
+
NDIS_RECEIVE_FILTER_VM_QUEUES_ENABLED
+

Specifies that virtual machine (VM) queues are enabled. VM queues are used when the miniport driver is enabled to use the VMQ interface.

+
+
UINT32The number of VM queues that the network adapter supports.
UINT32Supported VM queue properties. A bitwise OR of flags that specify the VM queue properties that the network adapter supports. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_MSI_X_SUPPORTED
+

The network adapter assigned an MSI-X table entry for each receive queue. Network adapters must not use one MSI-X table entry for multiple receive queues. This flag is mandatory for miniport drivers that support the VMQ or SR-IOV interface.

+
+
NDIS_RECEIVE_FILTER_VM_QUEUE_SUPPORTED
+

The network adapter provides the minimum requirements to support VM queue packet filtering. The miniport driver must set this flag if it is enabled to use the VMQ or SR-IOV interface.

+

For more information about VMQ requirements for VM queue packet filtering, see [Setting and Clearing VMQ Filters](https://msdn.microsoft.com/library/windows/hardware/ff570780).

+

For more information about SR-IOV requirements for VM queue packet filtering, see [Setting a Receive Filter on a Virtual Port](https://msdn.microsoft.com/library/windows/hardware/hh440224).

+
+
NDIS_RECEIVE_FILTER_LOOKAHEAD_SPLIT_SUPPORTED
+

The network adapter supports VM queues that split an incoming received packet at the lookahead offset. This offset is equal to or greater than the requested lookahead size. The network adapter uses DMA to transfer the lookahead and post-lookahead data to separate shared memory segments.

+
+Note  Starting with NDIS 6.30, splitting packet data into separate lookahead buffers is no longer supported. Miniport drivers that support this version of NDIS must not set this flag. +
+
+  +
+
+
NDIS_RECEIVE_FILTER_DYNAMIC_PROCESSOR_AFFINITY_CHANGE_SUPPORTED
+

The network adapter supports the ability to dynamically change one of the following processor affinity attributes:

+
    +
  • The processor affinity of a VM queue in the VMQ interface. The processor affinity is changed through an OID set request of [OID_RECEIVE_FILTER_QUEUE_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff569794).

  • +
  • The processor affinity of a nondefault virtual port (VPort), which was created in the SR-IOV interface and is attached to the PCI Express (PCIe) physical function (PF) of the network adapter. The processor affinity is changed through an OID set request of [OID_NIC_SWITCH_VPORT_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/hh451825).

  • +
+
+
NDIS_RECEIVE_FILTER_INTERRUPT_VECTOR_COALESCING_SUPPORTED
+

The network adapter supports interrupt coalescing for received packets on any of the following:

+
    +
  • Multiple VM queues in the VMQ interface.

  • +
  • Multiple VPorts that are attached to the PF in the SR-IOV interface.

  • +
+

If this flag is set, the network adapter must coalesce receive interrupts for VM queues or VPorts that have the same processor affinity.

+
+
NDIS_RECEIVE_FILTER_IMPLAT_MIN_OF_QUEUES_MODE
+

Indicates that the number of VM queues available is the minimum number of queues available from any member of a Load Balancing Failover (LBFO) team. This flag applies to LBFO filters only. This flag is not set for miniports.

+
+
NDIS_RECEIVE_FILTER_IMPLAT_SUM_OF_QUEUES_MODE
+

Indicates that the number of VM queues available is the sum of all the queues available from every member of an LBFO team. This flag applies to LBFO filters only. This flag is not set for miniports.

+
+
NDIS_RECEIVE_FILTER_PACKET_COALESCING_SUPPORTED_ON_DEFAULT_QUEUE
+

The network adapter supports NDIS packet coalescing. Packet coalescing is only supported on the default receive queue of the network adapter. This receive queue has an identifier of NDIS_DEFAULT_RECEIVE_QUEUE_ID.

+
+
UINT32Supported filter tests. A bitwise OR of flags that specify the test operations that a miniport driver supports. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_TEST_HEADER_FIELD_EQUAL_SUPPORTED
+

The network adapter supports testing the selected header field to determine whether it is equal to a given value.

+
+Note  If the miniport driver supports the VMQ or SR-IOV interfaces, it must set this flag. +
+
+  +
+
+
NDIS_RECEIVE_FILTER_TEST_HEADER_FIELD_MASK_EQUAL_SUPPORTED
+

The network adapter supports masking (that is, a bitwise AND) of the selected header field to determine whether the result is equal to a specified value.

+
+
NDIS_RECEIVE_FILTER_TEST_HEADER_FIELD_NOT_EQUAL_SUPPORTED
+

The network adapter supports testing the selected header field to determine whether it is not equal to a specified value.

+
+
UINT32Supported headers. A bitwise OR of flags that specify the types of network packet headers that a miniport driver can inspect. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_SUPPORTED
+

The network adapter can inspect the media access control (MAC) header of a network packet. The SupportedMacHeaderFields member defines the various fields from the MAC header that can be inspected.

+
+
NDIS_RECEIVE_FILTER_ARP_HEADER_SUPPORTED
+

The network adapter can inspect the Address Resolution Protocol (ARP) header of a network packet. The SupportedArpHeaderFields member defines the various fields from the ARP header that can be inspected.

+
+
NDIS_RECEIVE_FILTER_IPV4_HEADER_SUPPORTED
+

The network adapter can inspect the IP version 4 (IPv4) header of a network packet. The SupportedIPv4HeaderFields member defines the various fields from the IPv4 header that can be inspected.

+
+
NDIS_RECEIVE_FILTER_IPV6_HEADER_SUPPORTED
+

The network adapter can inspect the IP version 6 (IPv6) header of a network packet. The SupportedIPv6HeaderFields member defines the various fields from the IPv6 header that can be inspected.

+
+
NDIS_RECEIVE_FILTER_UDP_HEADER_SUPPORTED
+

The network adapter can inspect the User Datagram Protocol (UDP) header of a network packet. The SupportedIPv6HeaderFields member defines the various fields from the UDP header that can be inspected.

+
+
UINT32Supported MAC header fields. A bitwise OR of flags that specify the types of MAC header fields that a miniport driver can inspect. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_DEST_ADDR_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the destination MAC address in the MAC header.

+
+Note  Starting with NDIS 6.30, miniport drivers that support the VMQ or SR-IOV interface must set this flag. +
+
+  +
+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_SOURCE_ADDR_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the source MAC address in the MAC header.

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_PROTOCOL_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the EtherType identifier in the MAC header. For example, the EtherType identifier for IPv4 packets is 0x0800.

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_VLAN_ID_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the VLAN identifier in the MAC header.

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_PRIORITY_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the priority tag in the MAC header.

+
+
NDIS_RECEIVE_FILTER_MAC_HEADER_PACKET_TYPE_SUPPORTED
+

The network adapter supports inspecting and filtering that are based on the packet type field of the IEEE 802.2 subnetwork access protocol (SNAP) header in an 802.3 MAC header.

+
+
UINT32The maximum number of MAC header filters that the miniport driver supports.
UINT32Maximum queue groups. This value is reserved.
UINT32Maximum queues per queue group. This value is reserved.
UINT32The minimum size, in bytes, that the network adapter supports for lookahead packet buffers. +
+Note  Starting with NDIS 6.30, splitting packet data into separate lookahead buffers is no longer supported. Miniport drivers that support this version of NDIS must set this member to zero. +
+
+  +
UINT32The maximum size, in bytes, that the network adapter supports for lookahead packet buffers. +
+Note  Starting with NDIS 6.30, splitting packet data into separate lookahead buffers is no longer supported. Miniport drivers that support this version of NDIS must set this member to zero. +
+
+  +
UINT32Supported ARP header fields. A bitwise OR of flags that specify the types of ARP header fields that a miniport driver can inspect. The following flags are valid. +

+
+
NDIS_RECEIVE_FILTER_ARP_HEADER_OPERATION_SUPPORTED
+

The network adapter supports receive filtering on the ARP operation field.

+
+
NDIS_RECEIVE_FILTER_ARP_HEADER_SPA_SUPPORTED
+

The network adapter supports receive filtering on the ARP source protocol address (SPA) field.

+
+
NDIS_RECEIVE_FILTER_ARP_HEADER_TPA_SUPPORTED
+

The network adapter supports receive filtering on the ARP target protocol address (TPA) field.

+
+
UINT32Supported IPv4 header fields. A bitwise OR of flags that specify the types of IPv4 header fields that a miniport driver can inspect. The following flag is valid. +

+
+
NDIS_RECEIVE_FILTER_IPV4_HEADER_PROTOCOL_SUPPORTED
+

The network adapter supports receive filtering on the IPv4 protocol field.

+
+
UINT32Supported IPv6 header fields. A bitwise OR of flags that specify the types of IPv6 header fields that a miniport driver can inspect. The following flag is valid. +

+
+
NDIS_RECEIVE_FILTER_IPV6_HEADER_PROTOCOL_SUPPORTED
+

The network adapter supports receive filtering on the IPv6 protocol field.

+
+
UINT32Supported UDP header fields. A bitwise OR of flags that specify the types of IPv6 header fields that a miniport driver can inspect. The following flag is valid. +

+
+
NDIS_RECEIVE_FILTER_UDP_HEADER_DEST_PORT_SUPPORTED
+

The network adapter supports receive filtering on the UDP destination port field.

+
+Note  If the received UDP packet contains IPv4 options or IPv6 extension headers, the network adapter can automatically drop the received packet and treat it as if it failed the UDP filter test. +
+
+  +
+
+
UINT32The maximum number of tests on packet header fields that can be specified for a single packet coalescing filter. For more information about packet coalescing, see [NDIS Packet Coalescing](https://msdn.microsoft.com/library/windows/hardware/hh451601). +
+Note  Network adapters that support packet coalescing must support five or more packet header fields that can be specified for a single packet coalescing filter. If the adapter does not support packet coalescing, the miniport driver must set this value to zero. +
+
+  +
UINT32The maximum number of packet coalescing receive filters that are supported by the network adapter. +
+Note  Network adapters that support packet coalescing must support ten or more packet coalescing filters. If the adapter does not support packet coalescing, the miniport driver must set this value to zero. +
+
+  +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[**NDIS\_RECEIVE\_FILTER\_CAPABILITIES**](https://msdn.microsoft.com/library/windows/hardware/ff566864) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RECEIVE_COALESCING_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-config.md b/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-config.md new file mode 100644 index 0000000000..8298979542 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-receive-coalescing-config.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_RECEIVE_COALESCING_CONFIG +author: windows-driver-content +description: WDI_TLV_RECEIVE_COALESCING_CONFIG is a TLV that contains receive coalescing configuration. +ms.assetid: 32542203-14DE-4F91-AB85-D2FA75ECAB9E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RECEIVE_COALESCING_CONFIG Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RECEIVE\_COALESCING\_CONFIG + + +WDI\_TLV\_RECEIVE\_COALESCING\_CONFIG is a TLV that contains receive coalescing configuration. + +## TLV Type + + +0xDB + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------| +| UINT32 | A unique queue ID to queue packets matching this filter. | +| UINT32 | A filter ID with a value from 1 to the number of filters supported. | +| UINT32 | The maximum coalescing delay in milliseconds. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_SET\_RECEIVE\_COALESCING](https://msdn.microsoft.com/library/windows/hardware/dn925941) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RECEIVE_COALESCING_CONFIG%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-receive-filter-field.md b/windows-driver-docs-pr/network/wdi-tlv-receive-filter-field.md new file mode 100644 index 0000000000..9bde01d172 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-receive-filter-field.md @@ -0,0 +1,110 @@ +--- +title: WDI_TLV_RECEIVE_FILTER_FIELD (0x65) +author: windows-driver-content +description: WDI_TLV_RECEIVE_FILTER_FIELD is a TLV that contains a receive filter test criterion for one field in a network header. +ms.assetid: 9037CD08-742E-4A99-A37B-9969A2BC666A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_RECEIVE_FILTER_FIELD (0x65) Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_RECEIVE\_FILTER\_FIELD (0x65) + + +WDI\_TLV\_RECEIVE\_FILTER\_FIELD is a TLV that contains a receive filter test criterion for one field in a network header. + +## TLV Type + + +0x65 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32Specifies a bitwise OR of flags. The possible flag value is WDI_RECEIVE_FILTER_FIELD_MAC_HEADER_VLAN_UNTAGGED_OR_ZERO. If this flag is set, the network adapter must only indicate received packets that pass the following criteria: +
    +
  • The packet's MAC address matches the specified MAC header field test.
  • +
  • The packet either does not contain a VLAN tag or has a VLAN tag with an ID of zero.
  • +
[NDIS_FRAME_HEADER](https://msdn.microsoft.com/library/windows/hardware/ff565581) (UINT32)Frame header. Specifies the type of the frame header.
[NDIS_RECEIVE_FILTER_TEST](https://msdn.microsoft.com/library/windows/hardware/ff567183) (UINT32)Receive filter test. Specifies the type of test that the receive filter performs.
UINT32Header field. Specifies the protocol-specific header field type with the union as documented in the [NDIS_RECEIVE_FILTER_FIELD_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff567169).HeaderField.
UINT8[16]Field value. Specifies the value that the miniport adapter compares to the corresponding header field value in incoming packets. The location of the header field value is determined by the field type that is specified in the header field element. This value is in network byte order and is specified with the union as documented in the [NDIS_RECEIVE_FILTER_FIELD_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff567169).FieldValue.
UINT8[16]Test result value. If the receive filter test element is set to ReceiveFilterTestMaskEqual, the network adapter first calculates a result from the value in the field value member and the header field value as specified by the header field member. The adapter then compares the calculated result with result value. This value is specified with the union as documented in the [NDIS_RECEIVE_FILTER_FIELD_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/ff567169).ResultValue.
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_RECEIVE_FILTER_FIELD%20%280x65%29%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-roaming-needed-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-roaming-needed-parameters.md new file mode 100644 index 0000000000..c53eb24392 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-roaming-needed-parameters.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_ROAMING_NEEDED_PARAMETERS +author: windows-driver-content +description: WDI_TLV_ROAMING_NEEDED_PARAMETERS is a TLV that contains the reason for a roam trigger. This is used in the NDIS_STATUS_WDI_INDICATION_ROAMING_NEEDED payload. +ms.assetid: 152F923C-ECAE-4D50-A7B4-4B2309D5A3B5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_ROAMING_NEEDED_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_ROAMING\_NEEDED\_PARAMETERS + + +WDI\_TLV\_ROAMING\_NEEDED\_PARAMETERS is a TLV that contains the reason for a roam trigger. This is used in the [NDIS\_STATUS\_WDI\_INDICATION\_ROAMING\_NEEDED](https://msdn.microsoft.com/library/windows/hardware/dn925648) payload. + +## TLV Type + + +0x55 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_ASSOC\_STATUS**](https://msdn.microsoft.com/library/windows/hardware/dn897725) | Specifies the reason for a roam trigger. When a [OID\_WDI\_TASK\_ROAM](https://msdn.microsoft.com/library/windows/hardware/dn925958) is triggered, this reason is forwarded to it. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_ROAMING_NEEDED_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-safe-mode-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-safe-mode-parameters.md new file mode 100644 index 0000000000..bdbdb0f15c --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-safe-mode-parameters.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_SAFE_MODE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_SAFE_MODE_PARAMETERS is an unused TLV. +ms.assetid: 64B79454-174E-4FAF-9400-5AEF9F1D7400 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SAFE_MODE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SAFE\_MODE\_PARAMETERS + + +WDI\_TLV\_SAFE\_MODE\_PARAMETERS is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SAFE_MODE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-scan-dwell-time.md b/windows-driver-docs-pr/network/wdi-tlv-scan-dwell-time.md new file mode 100644 index 0000000000..51b17f17b0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-scan-dwell-time.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_SCAN_DWELL_TIME +author: windows-driver-content +description: WDI_TLV_SCAN_DWELL_TIME is a TLV that contains scanning dwell time settings. +ms.assetid: A0C597E7-879C-43CC-BB86-4908AC31828F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SCAN_DWELL_TIME Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SCAN\_DWELL\_TIME + + +WDI\_TLV\_SCAN\_DWELL\_TIME is a TLV that contains scanning dwell time settings. + +## TLV Type + + +0x7 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | Specifies the time in milliseconds to dwell on active channels. This is a hint and if the adapter decides to use its own dwell time, it must meet the Maximum Scan Time requirement. | +| UINT32 | Specifies the time in milliseconds to dwell on passive channels. This is a hint and if the adapter decides to use its own dwell time, it must meet the Maximum Scan Time requirement. | +| UINT32 | Specifies the time in milliseconds for total scan. If the adapter limits its dwell times to below the values specified above, it can ignore the Maximum Scan Time parameter. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SCAN_DWELL_TIME%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-scan-mode.md b/windows-driver-docs-pr/network/wdi-tlv-scan-mode.md new file mode 100644 index 0000000000..7df7ab1485 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-scan-mode.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_SCAN_MODE +author: windows-driver-content +description: WDI_TLV_SCAN_MODE is a TLV that contains scan mode parameters. +ms.assetid: 9F954B66-4F1D-48F2-9316-BE623DF0CAE6 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SCAN_MODE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SCAN\_MODE + + +WDI\_TLV\_SCAN\_MODE is a TLV that contains scan mode parameters. + +## TLV Type + + +0x6 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | The number of times the full scan procedure should be repeated. If this value is set to 0, the scan should be repeated until the task is aborted by the host. | +| [**WDI\_SCAN\_TYPE**](https://msdn.microsoft.com/library/windows/hardware/dn926115) | Specifies the type of scan that should be performed. If WDI\_SCAN\_TYPE\_ACTIVE is set, the device must only scan active channels. | +| UINT8 | Specifies if live updates are needed and discovered entries must be reported when they are found, with the recommended throttling logic above. This value is always true when the Microsoft component manages the BSS list cache. | +| [**WDI\_SCAN\_TRIGGER**](https://msdn.microsoft.com/library/windows/hardware/dn926114) | Specifies the trigger for the scan. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SCAN_MODE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-request-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-request-parameters.md new file mode 100644 index 0000000000..9a58a30945 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-request-parameters.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_SEND_ACTION_FRAME_REQUEST_PARAMETERS +author: windows-driver-content +description: WDI_TLV_SEND_ACTION_FRAME_REQUEST_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_SEND_REQUEST_ACTION_FRAME. +ms.assetid: 92629752-A94B-442A-97E9-D8E1C7924855 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SEND_ACTION_FRAME_REQUEST_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SEND\_ACTION\_FRAME\_REQUEST\_PARAMETERS + + +WDI\_TLV\_SEND\_ACTION\_FRAME\_REQUEST\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_SEND\_REQUEST\_ACTION\_FRAME](https://msdn.microsoft.com/library/windows/hardware/dn925961). + +## TLV Type + + +0xBF + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| WDI\_CHANNEL\_NUMBER (UINT32) | The channel on which to send the action frame and also to linger on as specified in the post-ACK dwell time. | +| WDI\_BAND\_ID (UINT32) | The ID of the band on which to send the action frame. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the target access point or peer adapter. | +| UINT32 | The send timeout. Specifies the maximum time (in milliseconds) to send this Action Frame. | +| UINT32 | The post-acknowledgment dwell time. Specifies the time (in milliseconds) to remain on listen channel after the incoming packet is acknowledged. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SEND_ACTION_FRAME_REQUEST_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-response-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-response-parameters.md new file mode 100644 index 0000000000..48640d37f0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-send-action-frame-response-parameters.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_SEND_ACTION_FRAME_RESPONSE_PARAMETERS +author: windows-driver-content +description: WDI_TLV_SEND_ACTION_FRAME_RESPONSE_PARAMETERS is a TLV that contains parameters for OID_WDI_TASK_SEND_RESPONSE_ACTION_FRAME. +ms.assetid: F062F8A2-EEEF-4EFC-AEC8-F1D7AB13C899 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SEND_ACTION_FRAME_RESPONSE_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SEND\_ACTION\_FRAME\_RESPONSE\_PARAMETERS + + +WDI\_TLV\_SEND\_ACTION\_FRAME\_RESPONSE\_PARAMETERS is a TLV that contains parameters for [OID\_WDI\_TASK\_SEND\_RESPONSE\_ACTION\_FRAME](https://msdn.microsoft.com/library/windows/hardware/dn925962). + +## TLV Type + + +0xE2 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| WDI\_CHANNEL\_NUMBER (UINT32) | The channel on which to send the action frame and also to linger on as specified in the post-ACK dwell time. | +| WDI\_BAND\_ID (UINT32) | The ID of the band on which to send the action frame. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | The MAC address of the target access point or peer adapter. | +| UINT32 | The send timeout. Specifies the maximum time (in milliseconds) to send this Action Frame. | +| UINT32 | The post-acknowledgment dwell time. Specifies the time (in milliseconds) to remain on listen channel after the incoming packet is acknowledged. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SEND_ACTION_FRAME_RESPONSE_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-auto-power-save.md b/windows-driver-docs-pr/network/wdi-tlv-set-auto-power-save.md new file mode 100644 index 0000000000..144532a847 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-auto-power-save.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_SET_AUTO_POWER_SAVE +author: windows-driver-content +description: WDI_TLV_SET_AUTO_POWER_SAVE is an unused TLV. +ms.assetid: 897696D0-72C0-471A-9A43-1D1FAA78260F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_AUTO_POWER_SAVE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_AUTO\_POWER\_SAVE + + +WDI\_TLV\_SET\_AUTO\_POWER\_SAVE is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_AUTO_POWER_SAVE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-cipher-key-info.md b/windows-driver-docs-pr/network/wdi-tlv-set-cipher-key-info.md new file mode 100644 index 0000000000..4565abfff6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-cipher-key-info.md @@ -0,0 +1,79 @@ +--- +title: WDI_TLV_SET_CIPHER_KEY_INFO +author: windows-driver-content +description: WDI_TLV_SET_CIPHER_KEY_INFO is a TLV that contains cipher key mapping key information for OID_WDI_SET_ADD_CIPHER_KEYS. +ms.assetid: 6352284A-73CD-4B15-A057-80D0C8518CD5 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_CIPHER_KEY_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_CIPHER\_KEY\_INFO + + +WDI\_TLV\_SET\_CIPHER\_KEY\_INFO is a TLV that contains cipher key mapping key information for [OID\_WDI\_SET\_ADD\_CIPHER\_KEYS](https://msdn.microsoft.com/library/windows/hardware/dn925855). + +## TLV Type + + +0x52 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**WDI\_TLV\_PEER\_MAC\_ADDRESS**](wdi-tlv-peer-mac-address.md) | | X | Specifies the MAC address of the peer that this key is associated with. If not present, assume this is a default key. At least one of peer MAC Address or cipher key ID must be present. This field must be present when key type is set to WDI\_CIPHER\_KEY\_TYPE\_PAIRWISE\_KEY, and may be present when key type is set to WDI\_CIPHER\_KEY\_TYPE\_GROUP\_KEY. | +| [**WDI\_TLV\_CIPHER\_KEY\_ID**](wdi-tlv-cipher-key-id.md) | | X | Specifies the ID for this cipher key. At least one of peer MAC address or cipher key ID must be present. This field is not required for pairwise keys. | +| [**WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO**](wdi-tlv-cipher-key-type-info.md) | | | Specifies the cipher key type information. | +| [**WDI\_TLV\_CIPHER\_KEY\_RECEIVE\_SEQUENCE\_COUNT**](wdi-tlv-cipher-key-receive-sequence-count.md) | | X | Specifies the initial 48-bit value of Packet Number (PN), which is used for replay protection. This is optional if the cipher algorithm is WDI\_CIPHER\_ALGO\_WEP40, WDI\_CIPHER\_ALGO\_WEP104, or WDI\_CIPHER\_ALGO\_WEP. | +| [**WDI\_TLV\_CIPHER\_KEY\_CCMP\_KEY**](wdi-tlv-cipher-key-ccmp-key.md) | | X | Specifies the CCMP cipher algorithm key data. This is only present if the cipher algorithm is WDI\_CIPHER\_ALGO\_CCMP. | +| [**WDI\_TLV\_CIPHER\_KEY\_TKIP\_INFO**](wdi-tlv-cipher-key-tkip-info.md) | | X | Specifies the TKIP information. This is only present if the cipher algorithm is WDI\_CIPHER\_ALGO\_TKIP. | +| [**WDI\_TLV\_CIPHER\_KEY\_BIP\_KEY**](wdi-tlv-cipher-key-bip-key.md) | | X | Specifies the BIP key. This is only present if the cipher algorithm is WDI\_CIPHER\_ALGO\_BIP. | +| [**WDI\_TLV\_CIPHER\_KEY\_WEP\_KEY**](wdi-tlv-cipher-key-wep-key.md) | | X | Specifies the WEP key. This is only present if the cipher algorithm is WDI\_CIPHER\_ALGO\_WEP40, WDI\_CIPHER\_ALGO\_WEP104, or WDI\_CIPHER\_ALGO\_WEP. | +| [**WDI\_TLV\_CIPHER\_KEY\_IHV\_KEY**](wdi-tlv-cipher-key-ihv-key.md) | | X | Specifies the IHV cipher key. This is only present if [**WDI\_TLV\_CIPHER\_KEY\_TYPE\_INFO**](wdi-tlv-cipher-key-type-info.md) is in the range WDI\_CIPHER\_ALGO\_IHV\_START to WDI\_CIPHER\_ALGO\_IHV\_END. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_CIPHER_KEY_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-clear-receive-coalescing.md b/windows-driver-docs-pr/network/wdi-tlv-set-clear-receive-coalescing.md new file mode 100644 index 0000000000..f9b72c0a57 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-clear-receive-coalescing.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_SET_CLEAR_RECEIVE_COALESCING +author: windows-driver-content +description: WDI_TLV_SET_CLEAR_RECEIVE_COALESCING is a TLV that contains a filter ID for OID_WDI_SET_CLEAR_RECEIVE_COALESCING. +ms.assetid: 4AF7A1A4-A1B4-48AD-9989-B9E317F93459 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_CLEAR_RECEIVE_COALESCING Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_CLEAR\_RECEIVE\_COALESCING + + +WDI\_TLV\_SET\_CLEAR\_RECEIVE\_COALESCING is a TLV that contains a filter ID for [OID\_WDI\_SET\_CLEAR\_RECEIVE\_COALESCING](https://msdn.microsoft.com/library/windows/hardware/dn925926). + +## TLV Type + + +0x9B + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------| +| UINT32 | The ID of the filter. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_CLEAR_RECEIVE_COALESCING%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v4-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v4-parameters.md new file mode 100644 index 0000000000..59d80d49fe --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v4-parameters.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V4_PARAMETERS +author: windows-driver-content +description: WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V4_PARAMETERS is a TLV that is used by OID_WDI_SET_ENCAPSULATION_OFFLOAD to indicate if IPv4 offloading should be started. +ms.assetid: DC474D05-BF41-48F4-90CC-96C3B7F41ED0 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V4_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V4\_PARAMETERS + + +WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V4\_PARAMETERS is a TLV that is used by [OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/dn925930) to indicate if IPv4 offloading should be started. + +## TLV Type + + +0xFD + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies if IPv4 offloading should be started. This value is set to NDIS\_OFFLOAD\_SET\_ON if enabled, and set to NDIS\_OFFLOAD\_SET\_OFF if disabled. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V4_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v6-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v6-parameters.md new file mode 100644 index 0000000000..5eeef43e12 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-encapsulation-offload-v6-parameters.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V6_PARAMETERS +author: windows-driver-content +description: WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V6_PARAMETERS is a TLV that is used by OID_WDI_SET_ENCAPSULATION_OFFLOAD to indicate if IPv6 offloading should be started. +ms.assetid: 7036AFD0-197E-4A94-8580-A42889BE6798 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V6_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V6\_PARAMETERS + + +WDI\_TLV\_SET\_ENCAPSULATION\_OFFLOAD\_V6\_PARAMETERS is a TLV that is used by [OID\_WDI\_SET\_ENCAPSULATION\_OFFLOAD](https://msdn.microsoft.com/library/windows/hardware/dn925930) to indicate if IPv6 offloading should be started. + +## TLV Type + + +0xFE + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies if IPv6 offloading should be started. This value is set to NDIS\_OFFLOAD\_SET\_ON if enabled, and set to NDIS\_OFFLOAD\_SET\_OFF if disabled. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_ENCAPSULATION_OFFLOAD_V6_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-power-dx-reason.md b/windows-driver-docs-pr/network/wdi-tlv-set-power-dx-reason.md new file mode 100644 index 0000000000..2209ff44b4 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-power-dx-reason.md @@ -0,0 +1,91 @@ +--- +title: WDI_TLV_SET_POWER_DX_REASON +author: windows-driver-content +description: WDI_TLV_SET_POWER_DX_REASON is a TLV that contains the reason for a set power Dx. +ms.assetid: 339F3461-3478-4C54-B6FB-9F5541859C76 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_POWER_DX_REASON Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_POWER\_DX\_REASON + + +WDI\_TLV\_SET\_POWER\_DX\_REASON is a TLV that contains the reason for a set power Dx. + +## TLV Type + + +0x103 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + + ++++ + + + + + + + + + + + + +
TypeDescription
UINT32The reason for a set power Dx. +

Valid values are:

+
    +
  • WDI_SET_POWER_DX_REASON_SELETIVE_SUSPEND (1)

    +

    When this value is set, it implies waking on any interesting external events without explicit [WDI_TLV_ENABLE_WAKE_EVENTS](wdi-tlv-enable-wake-events.md). This is an idle low power where the device functions transparently to end users as if it were in D0. See [WDI USB remote wake sequence](https://msdn.microsoft.com/library/windows/hardware/mt269159) for more information.

  • +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_POWER_DX_REASON%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-set-receive-coalescing.md b/windows-driver-docs-pr/network/wdi-tlv-set-receive-coalescing.md new file mode 100644 index 0000000000..f20e6ba8a0 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-set-receive-coalescing.md @@ -0,0 +1,72 @@ +--- +title: WDI_TLV_SET_RECEIVE_COALESCING +author: windows-driver-content +description: WDI_TLV_SET_RECEIVE_COALESCING is a TLV that contains received packet coalescing parameters for OID_WDI_SET_RECEIVE_COALESCING. +ms.assetid: 7937517E-79E5-4BF6-9C22-79E1D73CA97C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SET_RECEIVE_COALESCING Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SET\_RECEIVE\_COALESCING + + +WDI\_TLV\_SET\_RECEIVE\_COALESCING is a TLV that contains received packet coalescing parameters for [OID\_WDI\_SET\_RECEIVE\_COALESCING](https://msdn.microsoft.com/library/windows/hardware/dn925941). + +## TLV Type + + +0x64 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------------|--------------------------------|----------|--------------------------------------------| +| [**WDI\_TLV\_RECEIVE\_COALESCING\_CONFIG**](wdi-tlv-receive-coalescing-config.md) | | | Specifies coalescing filter configuration. | +| [**WDI\_TLV\_RECEIVE\_FILTER\_FIELD**](wdi-tlv-receive-filter-field.md) | X | X | Specifies a receive filter field. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SET_RECEIVE_COALESCING%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ssid-list.md b/windows-driver-docs-pr/network/wdi-tlv-ssid-list.md new file mode 100644 index 0000000000..428d79ebb9 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ssid-list.md @@ -0,0 +1,52 @@ +--- +title: WDI_TLV_SSID_LIST +author: windows-driver-content +description: WDI_TLV_SSID_LIST is an unused TLV. +ms.assetid: 931EEA38-C380-4647-AAE6-25A7CFE39101 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SSID_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SSID\_LIST + + +WDI\_TLV\_SSID\_LIST is an unused TLV. + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SSID_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ssid-offload.md b/windows-driver-docs-pr/network/wdi-tlv-ssid-offload.md new file mode 100644 index 0000000000..c089fd1c46 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ssid-offload.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_SSID_OFFLOAD +author: windows-driver-content +description: WDI_TLV_SSID_OFFLOAD is a TLV that contains an SSID and hints about the SSID. +ms.assetid: 6CF08BEB-8CEE-4C07-B63B-7FAC7AEAB24F +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SSID_OFFLOAD Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SSID\_OFFLOAD + + +WDI\_TLV\_SSID\_OFFLOAD is a TLV that contains an SSID and hints about the SSID. + +## TLV Type + + +0x9E + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|------------------------------------------------------------------------------|--------------------------------|----------|-----------------------------| +| [**WDI\_TLV\_SSID**](wdi-tlv-ssid.md) | | | The SSID. | +| [**WDI\_TLV\_UNICAST\_ALGORITHM\_LIST**](wdi-tlv-unicast-algorithm-list.md) | | | The unicast algorithm list. | +| [**WDI\_TLV\_CHANNEL\_LIST**](wdi-tlv-channel-list.md) | | | The channel list. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SSID_OFFLOAD%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-ssid.md b/windows-driver-docs-pr/network/wdi-tlv-ssid.md new file mode 100644 index 0000000000..c4ac55eaa6 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-ssid.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_SSID +author: windows-driver-content +description: WDI_TLV_SSID is a TLV that contains an SSID. +ms.assetid: 31391E25-B507-4652-9D70-9DA0D6245CA8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SSID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SSID + + +WDI\_TLV\_SSID is a TLV that contains an SSID. + +## TLV Type + + +0x3B + +## Length + + +The size (in bytes) of the array of UINT8 elements. An array length of 0 is allowed. + +## Values + + +| Type | Description | +|-----------|----------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies an SSID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SSID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-start-ap-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-start-ap-parameters.md new file mode 100644 index 0000000000..74974ec0b9 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-start-ap-parameters.md @@ -0,0 +1,113 @@ +--- +title: WDI_TLV_START_AP_PARAMETERS +author: windows-driver-content +description: WDI_TLV_START_AP_PARAMETERS is a TLV that contains the parameters for OID_WDI_TASK_START_AP. +ms.assetid: 6791754C-9786-4BE4-9915-7333E4E0AFB8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_START_AP_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_START\_AP\_PARAMETERS + + +WDI\_TLV\_START\_AP\_PARAMETERS is a TLV that contains the parameters for [OID\_WDI\_TASK\_START\_AP](https://msdn.microsoft.com/library/windows/hardware/dn925964). + +## TLV Type + + +0xAB + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32The beacon period. If non-zero, this parameter specifies the beacon interval.
UINT32The DTIM period. If non-zero, this parameter specifies the number of beacon intervals between transmissions of beacon frames that contain a TIM element with a DTIM Count field that equals zero. This value is transmitted in the DTIM Period field of beacon frames.
UINT8This parameter sets the dot11ExcludeUnencrypted MIB. Valid values are 0 and 1.
UINT8This parameter specifies if the device supports 802.11b speeds. Valid values are 0 (not supported) and 1 (supported). When this value is set to 1, the access point should allow clients using 11b rates to connect to it.
UINT8Added in Windows 10, version 1511, WDI version 1.0.10. +

This parameter specifies whether to allow legacy SoftAP clients to connect. Valid values are 0 (not allowed) and 1 (allowed).

UINT8Added in Windows 10, version 1511, WDI version 1.0.10. +

MustUseSpecifiedChannels. This parameter specifies whether the AP can only be started on the channels specified in [OID_WDI_TASK_START_AP](https://msdn.microsoft.com/library/windows/hardware/dn925964) task parameters with [WDI_TLV_AP_BAND_CHANNEL](wdi-tlv-ap-band-channel.md). Valid values are 0 and 1. If it is set to 1, the AP can only be started from the specified list. If it is not set, the list is meant to be a recommendation of channels that the firmware can pick from, and it may pick another channel if it is not possible to start the AP on any of the specified channels.

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_TASK\_START\_AP](https://msdn.microsoft.com/library/windows/hardware/dn925964) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_START_AP_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-station-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-station-attributes.md new file mode 100644 index 0000000000..fedc27d317 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-station-attributes.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_STATION_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_STATION_ATTRIBUTES is a TLV that contains the attributes of a station. +ms.assetid: CB15D3A4-5B42-44ED-A8A8-3E7F09B65F8B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_STATION_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_STATION\_ATTRIBUTES + + +WDI\_TLV\_STATION\_ATTRIBUTES is a TLV that contains the attributes of a station. + +## TLV Type + + +0x22 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------| +| [**WDI\_TLV\_STATION\_CAPABILITIES**](wdi-tlv-station-capabilities.md) | | | The station capabilities. | +| [**WDI\_TLV\_UNICAST\_ALGORITHM\_LIST**](wdi-tlv-unicast-algorithm-list.md) | | X | The supported unicast algorithms. | +| [**WDI\_TLV\_MULTICAST\_DATA\_ALGORITHM\_LIST**](wdi-tlv-multicast-data-algorithm-list.md) | | X | The supported multicast data algorithms. | +| [**WDI\_TLV\_MULTICAST\_MGMT\_ALGORITHM\_LIST**](wdi-tlv-multicast-mgmt-algorithm-list.md) | | X | The supported multicast management algorithms. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_STATION_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-station-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-station-capabilities.md new file mode 100644 index 0000000000..8b50c02803 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-station-capabilities.md @@ -0,0 +1,164 @@ +--- +title: WDI_TLV_STATION_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_STATION_CAPABILITIES is a TLV that contains the capabilities of a station. +ms.assetid: 567445F1-EEDC-4302-B709-ED76D044A971 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_STATION_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_STATION\_CAPABILITIES + + +WDI\_TLV\_STATION\_CAPABILITIES is a TLV that contains the capabilities of a station. + +## TLV Type + + +0x11 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT32The scan SSID list size.
UINT32The desired BSSID list size.
UINT32The desired SSID list size.
UINT32The privacy exemption list size.
UINT32The key mapping table size.
UINT32The default key table size.
UINT32The maximum length of the WEP key value.
UINT32The maximum number per STA default key tables.
UINT8Supported QoS flags. Specifies whether the device supports WMM. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether host-FIPS mode is implemented. +

If the field is set to DOT11_EXTSTA_ATTRIBUTES_SAFEMODE_OID_SUPPORTED with no other bits set, the driver implements the 802.11 safe mode of operation.

+

If the field is set to DOT11_EXTSTA_ATTRIBUTES_SAFEMODE_CERTIFIED, the NIC has received a validation certificate from the National Institute of Standards and Technology (NIST) under Federal Information Processing Standards (FIPS) Publication 140-2, Security Requirements for Cryptographic Modules. In this mode, the hardware is responsible for ensuring compliance to FIPS standard.

+

If the field is set to zero (0), FIPS mode is not implemented by the NIC.

UINT8Specifies whether 802.11w MFP capability is supported. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether auto power save is supported. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether the adapter maintains the Station BSS List cache. +

Valid values are 0 (no) and 1 (yes).

UINT8Specifies whether the adapter may attempt association to a BSSID that is not specified in the Preferred BSSID list during a Station connect. +

Valid values are 0 (no) and 1 (yes).

UINT32The maximum supported Network Offload List size.
UINT8Specifies whether or not the adapter can track HESSIDs associated with SSIDs and connect/roam only to those APs that match the specified SSID+HESSID. +

Valid values are 0 (not supported) and 1 (supported).

UINT8Specifies whether the adapter can offload connectivity to networks belonging to specific HESSIDs.
UINT8Specifies whether disconnected standby is supported. +

Valid values are 0 (not supported) and 1 (supported).

+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_STATION_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-status.md b/windows-driver-docs-pr/network/wdi-tlv-status.md new file mode 100644 index 0000000000..d24ee4e702 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-status.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_STATUS +author: windows-driver-content +description: WDI_TLV_STATUS is a TLV that contains a status value. +ms.assetid: 62A331EB-5765-41E9-A1CC-0CFF69BC4EF3 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_STATUS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_STATUS + + +WDI\_TLV\_STATUS is a TLV that contains a status value. + +## TLV Type + + +0x1 + +## Length + + +The size (in bytes) of an NDIS\_STATUS. + +## Values + + +| Type | Description | +|--------------|-------------------------| +| NDIS\_STATUS | The NDIS\_STATUS value. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_STATUS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-supported-guids.md b/windows-driver-docs-pr/network/wdi-tlv-supported-guids.md new file mode 100644 index 0000000000..07feb05922 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-supported-guids.md @@ -0,0 +1,80 @@ +--- +title: WDI_TLV_SUPPORTED_GUIDS +author: windows-driver-content +description: WDI_TLV_SUPPORTED_GUIDS is a TLV that contains a supported NDIS GUID. +ms.assetid: 957645EE-A6E3-402E-B18B-B2E7C73D6F6B +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_SUPPORTED_GUIDS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_SUPPORTED\_GUIDS + + +WDI\_TLV\_SUPPORTED\_GUIDS is a TLV that contains a supported NDIS GUID. + +**Note**  This TLV was added in Windows 10, version 1607, WDI version 1.0.21. + +  + +## TLV Type + + +0x130 + +## Length + + +The size (in bytes) of a [NDIS\_GUID](https://msdn.microsoft.com/library/windows/hardware/ff549898) structure. + +## Values + + +| Type | Description | +|------------|------------------------| +| NDIS\_GUID | A supported NDIS GUID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_SUPPORTED_GUIDS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-tcp-offload-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-tcp-offload-capabilities.md new file mode 100644 index 0000000000..30be3e5443 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-tcp-offload-capabilities.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_TCP_OFFLOAD_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_TCP_OFFLOAD_CAPABILITIES is a TLV that contains TCP/IP offload capabilities. +ms.assetid: 9B3428CC-C9B4-4769-BD97-F25920C4AAF2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_TCP_OFFLOAD_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_TCP\_OFFLOAD\_CAPABILITIES + + +WDI\_TLV\_TCP\_OFFLOAD\_CAPABILITIES is a TLV that contains TCP/IP offload capabilities. + +Capability values are reported as documented in [**NDIS\_TCP\_IP\_CHECKSUM\_OFFLOAD**](https://msdn.microsoft.com/library/windows/hardware/ff567878). Use NDIS\_OFFLOAD\_NOT\_SUPPORTED and NDIS\_OFFLOAD\_SUPPORTED when indicating capabilities through [OID\_WDI\_GET\_ADAPTER\_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/dn925838). For a connection with FIPS mode, offloads are turned OFF by the UE. + +## TLV Type + + +0xCA + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|-------------------------------------------------------------------------------------------------------------|--------------------------------|----------|-------------------------------------| +| [**WDI\_TLV\_CHECKSUM\_OFFLOAD\_CAPABILITIES**](wdi-tlv-checksum-offload-capabilities.md) | | | Checksum offload capabilities. | +| [**WDI\_TLV\_LSO\_V1\_CAPABILITIES**](wdi-tlv-lso-v1-capabilities.md) | | | Large Send Offload V1 capabilities. | +| [**WDI\_TLV\_LSO\_V2\_CAPABILITIES**](wdi-tlv-lso-v2-capabilities.md) | | | Large Send Offload V2 capabilities. | +| [**WDI\_TLV\_RECEIVE\_COALESCE\_OFFLOAD\_CAPABILITIES**](wdi-tlv-receive-coalesce-offload-capabilities.md) | | | Receive Offload capabilities. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_TCP_OFFLOAD_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-tcp-rsc-statistics-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-tcp-rsc-statistics-parameters.md new file mode 100644 index 0000000000..6652942c6d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-tcp-rsc-statistics-parameters.md @@ -0,0 +1,74 @@ +--- +title: WDI_TLV_TCP_RSC_STATISTICS_PARAMETERS +author: windows-driver-content +description: WDI_TLV_TCP_RSC_STATISTICS_PARAMETERS is a TLV that contains TCP RSC statistics for OID_WDI_TCP_RSC_STATISTICS. +ms.assetid: C1459DF6-6492-4C1F-A22D-2BDC6492B29C +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_TCP_RSC_STATISTICS_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_TCP\_RSC\_STATISTICS\_PARAMETERS + + +WDI\_TLV\_TCP\_RSC\_STATISTICS\_PARAMETERS is a TLV that contains TCP RSC statistics for [OID\_WDI\_TCP\_RSC\_STATISTICS](https://msdn.microsoft.com/library/windows/hardware/dn925966). + +## TLV Type + + +0xF3 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT64 | The total number of packets that were coalesced. | +| UINT64 | The total number of bytes that were coalesced. | +| UINT64 | The total number of coalescing events, which is the total number of packets that were formed from coalescing packets. | +| UINT64 | The total number of RSC abort events, which is the number of exceptions other than the IP datagram length being exceeded. This count should include the cases where a packet is not coalesced because of insufficient hardware resources. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_TCP_RSC_STATISTICS_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-tcp-set-offload-parameters.md b/windows-driver-docs-pr/network/wdi-tlv-tcp-set-offload-parameters.md new file mode 100644 index 0000000000..d6ce61e132 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-tcp-set-offload-parameters.md @@ -0,0 +1,273 @@ +--- +title: WDI_TLV_TCP_SET_OFFLOAD_PARAMETERS +author: windows-driver-content +description: WDI_TLV_TCP_SET_OFFLOAD_PARAMETERS is a TLV that contains TCP offload capabilities of a miniport adapter for OID_WDI_SET_TCP_OFFLOAD_PARAMETERS. +ms.assetid: 1DE1114A-E718-473F-B0EB-92AEFA4E7F13 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_TCP_SET_OFFLOAD_PARAMETERS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_TCP\_SET\_OFFLOAD\_PARAMETERS + + +WDI\_TLV\_TCP\_SET\_OFFLOAD\_PARAMETERS is a TLV that contains TCP offload capabilities of a miniport adapter for [OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn925945). + +## TLV Type + + +0xF2 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
UINT8The IPv4 checksum setting of the miniport adapter. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_DISABLED - Disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_ENABLED_RX_DISABLED - Enabled for transmit and disabled for receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RX_ENABLED_TX_DISABLED - Enabled for receive and disabled for transmit.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_ENABLED - Enabled for transmit and receive.
  • +
UINT8The IPv4 checksum setting for TCP packets. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_DISABLED - Disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_ENABLED_RX_DISABLED - Enabled for transmit and disabled for receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RX_ENABLED_TX_DISABLED - Enabled for receive and disabled for transmit.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_ENABLED - Enabled for transmit and receive.
  • +
UINT8The IPv4 checksum setting for UDP packets. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_DISABLED - Disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_ENABLED_RX_DISABLED - Enabled for transmit and disabled for receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RX_ENABLED_TX_DISABLED - Enabled for receive and disabled for transmit.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_ENABLED - Enabled for transmit and receive.
  • +
UINT8The IPv6 checksum setting for TCP packets. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_DISABLED - Disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_ENABLED_RX_DISABLED - Enabled for transmit and disabled for receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RX_ENABLED_TX_DISABLED - Enabled for receive and disabled for transmit.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_ENABLED - Enabled for transmit and receive.
  • +
UINT8The IPv6 checksum setting for UDP packets. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_DISABLED - Disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_ENABLED_RX_DISABLED - Enabled for transmit and disabled for receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RX_ENABLED_TX_DISABLED - Enabled for receive and disabled for transmit.
  • +
  • NDIS_OFFLOAD_PARAMETERS_TX_RX_ENABLED - Enabled for transmit and receive.
  • +
UINT8The Large Send Offload version 1 (LSOV1) setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV1_ENABLED - LSOV1 is enabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV1_DISABLED - LSOV1 is disabled.
  • +
UINT8The Internet Protocol Security (IPsec) offload setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV1_DISABLED - IPsec offload is disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV1_AH_ENABLED - The IPsec offload Authentication Header (AH) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV1_ESP_ENABLED - The IPsec offload Encapsulating Security Payload (ESP) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV1_AH_AND_ESP_ENABLED - The IPsec offload AH and ESP features are enabled for transmit and receive.
  • +
UINT8The IPv4 Large Send Offload version 2 (LSOV2) setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV2_ENABLED - LSOV2 for IPv4 is enabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV2_DISABLED - LSOV2 for IPv4 is disabled.
  • +
UINT8The IPv6 Large Send Offload version 2 (LSOV2) setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV2_ENABLED - LSOV2 for IPv6 is enabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_LSOV2_DISABLED - LSOV2 for IPv6 is disabled.
  • +
UINT8The IPv4 connection offload setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
UINT8The IPv6 connection offload setting. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
UINT8Indicates Receive Segment Coalescing state for IPv4. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The RSC state is unchanged.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RSC_ENABLED - The RSC state is enabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RSC_DISABLED - The RSC state is disabled.
  • +
UINT8Indicates Receive Segment Coalescing state for IPv6. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The RSC state is unchanged.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RSC_ENABLED - The RSC state is enabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_RSC_DISABLED - The RSC state is disabled.
  • +
UINT32The value is a bitwise OR of flags. This must be set to 0. There are no flags currently defined.
UINT8The Internet protocol security (IPsec) offload version 2 setting of a miniport adapter that supports both IPv6 and IPv4. This specifies the setting for both IPv6 and IPv4 support. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_DISABLED - IPsec offload version 2 is disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_AH_ENABLED - The IPsec offload version 2 Authentication Header (AH) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_ESP_ENABLED - The IPsec offload version 2 Encapsulating Security Payload (ESP) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_AH_AND_ESP_ENABLED - The IPsec offload version 2 AH and ESP features are enabled for transmit and receive.
  • +
UINT8The Internet protocol security (IPsec) offload version 2 setting of a miniport adapter that supports IPv4 and does not support IPv6. If the miniport driver supports IPv6, the IPsecV2 member specifies the IPv4 setting and this member is not used. +

Valid values are:

+
    +
  • NDIS_OFFLOAD_PARAMETERS_NO_CHANGE - The miniport driver should not change the current setting.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_DISABLED - IPsec offload version 2 is disabled.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_AH_ENABLED - The IPsec offload version 2 Authentication Header (AH) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_ESP_ENABLED - The IPsec offload version 2 Encapsulating Security Payload (ESP) feature should be enabled for transmit and receive.
  • +
  • NDIS_OFFLOAD_PARAMETERS_IPSECV2_AH_AND_ESP_ENABLED - The IPsec offload version 2 AH and ESP features are enabled for transmit and receive.
  • +
UINT8Encapsulated Packet Task Offload. A protocol driver sets this field to one of the following values. +

+
    +
  • NDIS_OFFLOAD_SET_NO_CHANGE (0) - The NVGRE task offload state is unchanged.
  • +
  • NDIS_OFFLOAD_SET_ON (1) - Enables NVGRE task offloads.
  • +
  • NDIS_OFFLOAD_SET_OFF (2) - Disables NVGRE task offloads.
  • +
UINT8Encapsulation types. This field is effective only when the Encapsulated Packet Task Offload is set to NDIS_OFFLOAD_SET_ON. If the Encapsulated Packet Task Offload member is not set to NDIS_OFFLOAD_SET_ON, this member is zero. A protocol driver must set Encapsulation Types to the bitwise OR of the flags corresponding to encapsulation types that it requires. It can select from the following flags. +

+
    +
  • NDIS_ENCAPSULATION_TYPE_GRE_MAC (0x00000001) - Specifies GRE MAC encapsulation (NVGRE).
  • +
+ +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[**NDIS\_OFFLOAD\_PARAMETERS**](https://msdn.microsoft.com/library/windows/hardware/ff566706) + +[OID\_WDI\_SET\_TCP\_OFFLOAD\_PARAMETERS](https://msdn.microsoft.com/library/windows/hardware/dn925945) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_TCP_SET_OFFLOAD_PARAMETERS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-tkip-mic-failure-info.md b/windows-driver-docs-pr/network/wdi-tlv-tkip-mic-failure-info.md new file mode 100644 index 0000000000..fa936c47ad --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-tkip-mic-failure-info.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_TKIP_MIC_FAILURE_INFO +author: windows-driver-content +description: WDI_TLV_TKIP_MIC_FAILURE_INFO is a TLV that contains TKIP-MIC failure information. +ms.assetid: BBF168BE-6223-4C54-AFF5-17878D07EFBD +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_TKIP_MIC_FAILURE_INFO Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_TKIP\_MIC\_FAILURE\_INFO + + +WDI\_TLV\_TKIP\_MIC\_FAILURE\_INFO is a TLV that contains TKIP-MIC failure information. + +## TLV Type + + +0x57 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | Specifies which cipher key type detected that the TKIP-MIC failure occurred. If this value is 1, the TKIP-MIC failure was detected through a default cipher key. If this value is 0, the TKIP-MIC failure was detected through a key mapping cipher key. | +| UINT32 | Specifies the index of the cipher key in the default key array. Valid value range is from 0 through 3. | +| [**WDI\_MAC\_ADDRESS**](https://msdn.microsoft.com/library/windows/hardware/dn926071) | Specifies the MAC address of the peer that transmitted the packet that failed MIC verification. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_TKIP_MIC_FAILURE_INFO%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-unicast-algorithm-list.md b/windows-driver-docs-pr/network/wdi-tlv-unicast-algorithm-list.md new file mode 100644 index 0000000000..6e0bb858b1 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-unicast-algorithm-list.md @@ -0,0 +1,84 @@ +--- +title: WDI_TLV_UNICAST_ALGORITHM_LIST +author: windows-driver-content +description: WDI_TLV_UNICAST_ALGORITHM_LIST is a TLV that contains an array of unicast data algorithm pairs. +ms.assetid: E216BE6A-5425-498F-ABDE-1229170DA5DB +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_UNICAST_ALGORITHM_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_UNICAST\_ALGORITHM\_LIST + + +WDI\_TLV\_UNICAST\_ALGORITHM\_LIST is a TLV that contains an array of unicast data algorithm pairs. + +## TLV Type + + +0x13 + +## Length + + +The size (in bytes) of the array of WDI\_ALGO\_PAIRS elements. The array must contain 1 or more elements. + +**Note**  WDI\_ALGO\_PAIRS is not a WDI structure. It is defined in the WDI TLV parser generator, and is used for documentation purposes only. + +  + +## Values + + +| Type | Description | +|----------------------|--------------------------------------------------------| +| WDI\_ALGO\_PAIRS\[\] | An array of authentication and cipher algorithm pairs. | + +  + +WDI\_ALGO\_PAIRS consists of the following elements. + +| Type | Description | +|-------|-------------------------------------------------------------------------------------------------| +| UINT8 | Authentication algorithm as defined in [**WDI\_AUTH\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897792). | +| UINT8 | Cipher algorithm as defined in [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802). | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_UNICAST_ALGORITHM_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-unicast-cipher-algo-list.md b/windows-driver-docs-pr/network/wdi-tlv-unicast-cipher-algo-list.md new file mode 100644 index 0000000000..72ab57d519 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-unicast-cipher-algo-list.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_UNICAST_CIPHER_ALGO_LIST +author: windows-driver-content +description: WDI_TLV_UNICAST_CIPHER_ALGO_LIST is a TLV that contains a list of unicast cipher algorithms. +ms.assetid: 67FAEE8A-1CD6-4430-92C1-84E9F43BEF63 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_UNICAST_CIPHER_ALGO_LIST Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_UNICAST\_CIPHER\_ALGO\_LIST + + +WDI\_TLV\_UNICAST\_CIPHER\_ALGO\_LIST is a TLV that contains a list of unicast cipher algorithms. + +## TLV Type + + +0x3E + +## Length + + +The size (in bytes) of the array of [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802) structures. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------------------------------------------------------------|----------------------------------------| +| [**WDI\_CIPHER\_ALGORITHM**](https://msdn.microsoft.com/library/windows/hardware/dn897802)\[\] | An array of unicast cipher algorithms. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_UNICAST_CIPHER_ALGO_LIST%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-unreachable-detection-threshold.md b/windows-driver-docs-pr/network/wdi-tlv-unreachable-detection-threshold.md new file mode 100644 index 0000000000..18e6aed29d --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-unreachable-detection-threshold.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD +author: windows-driver-content +description: WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD is a TLV that contains the unreachable detection threshold. +ms.assetid: D2C41B26-90EF-4A62-A105-DBEF3822BA6E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_UNREACHABLE\_DETECTION\_THRESHOLD + + +WDI\_TLV\_UNREACHABLE\_DETECTION\_THRESHOLD is a TLV that contains the unreachable detection threshold. + +## TLV Type + + +0xB1 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT32 | The unreachable detection threshold. Specifies the maximum amount of time, in milliseconds, before the 802.11 station determines that it has lost connectivity to a peer device. The station must include missed beacons in making this connectivity loss determination but can also use any other heuristics it desires. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_UNREACHABLE_DETECTION_THRESHOLD%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-vendor-specific-ie.md b/windows-driver-docs-pr/network/wdi-tlv-vendor-specific-ie.md new file mode 100644 index 0000000000..433677684e --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-vendor-specific-ie.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_VENDOR_SPECIFIC_IE +author: windows-driver-content +description: WDI_TLV_VENDOR_SPECIFIC_IE is a TLV that contains a list of vendor-specific IEs. +ms.assetid: 66995086-329A-49F1-B531-2AD2383473CF +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_VENDOR_SPECIFIC_IE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_VENDOR\_SPECIFIC\_IE + + +WDI\_TLV\_VENDOR\_SPECIFIC\_IE is a TLV that contains a list of vendor-specific IEs. + +## TLV Type + + +0x5 + +## Length + + +The size (in bytes) of the array of UINT8 elements. The array must contain 1 or more elements. + +## Values + + +| Type | Description | +|-----------|--------------------------------------------------------------------| +| UINT8\[\] | An array of UINT8 elements that specifies the vendor-specific IEs. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_VENDOR_SPECIFIC_IE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-virtualization-attributes.md b/windows-driver-docs-pr/network/wdi-tlv-virtualization-attributes.md new file mode 100644 index 0000000000..9ea747f0d7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-virtualization-attributes.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_VIRTUALIZATION_ATTRIBUTES +author: windows-driver-content +description: WDI_TLV_VIRTUALIZATION_ATTRIBUTES is a TLV that contains virtualization attributes. +ms.assetid: BFB21903-2532-46FB-97E3-6AF254B6BB1E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_VIRTUALIZATION_ATTRIBUTES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_VIRTUALIZATION\_ATTRIBUTES + + +WDI\_TLV\_VIRTUALIZATION\_ATTRIBUTES is a TLV that contains virtualization attributes. + +## TLV Type + + +0x24 + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|---------------------------------------------------------------------------------------|--------------------------------|----------|----------------------------------| +| [**WDI\_TLV\_VIRTUALIZATION\_CAPABILITIES**](wdi-tlv-virtualization-capabilities.md) | | | The virtualization capabilities. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_VIRTUALIZATION_ATTRIBUTES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-virtualization-capabilities.md b/windows-driver-docs-pr/network/wdi-tlv-virtualization-capabilities.md new file mode 100644 index 0000000000..63723eb9e7 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-virtualization-capabilities.md @@ -0,0 +1,76 @@ +--- +title: WDI_TLV_VIRTUALIZATION_CAPABILITIES +author: windows-driver-content +description: WDI_TLV_VIRTUALIZATION_CAPABILITIES is a TLV that contains virtualization capabilities. +ms.assetid: D72E9984-7193-406C-8BA3-006E54400B30 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_VIRTUALIZATION_CAPABILITIES Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_VIRTUALIZATION\_CAPABILITIES + + +WDI\_TLV\_VIRTUALIZATION\_CAPABILITIES is a TLV that contains virtualization capabilities. + +## TLV Type + + +0x10 + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| UINT8 | The number of supported ExtSTA ports. | +| UINT8 | The number of supported Wi-Fi Direct Group ports. This count should only include Role ports. If this value is non-zero, it is assumed that a Wi-Fi Direct Device port is available. | +| UINT8 | The number of supported legacy ExtAP ports. | +| UINT8 | The maximum number of supported simultaneous AP/WFD Group Owners. | +| UINT8 | The maximum number of separate channels that the device can operate in and maintain data connections on simultaneously. This limit should not include temporary multichannel operations like scans and Wi-Fi Direct negotiations. | +| UINT8 | The maximum number of supported simultaneous STA/WFD clients. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_VIRTUALIZATION_CAPABILITIES%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern-id.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern-id.md new file mode 100644 index 0000000000..c6d2b0cd8b --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern-id.md @@ -0,0 +1,78 @@ +--- +title: WDI_TLV_WAKE_PACKET_BITMAP_PATTERN_ID +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_BITMAP_PATTERN_ID is a TLV that contains a wake-on-LAN pattern ID. +ms.assetid: 78807D91-189B-4E66-B3DC-500E9A59AEF2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_BITMAP_PATTERN_ID Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN\_ID + + +WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN\_ID is a TLV that contains a wake-on-LAN pattern ID. + +The pattern ID is an OS-provided value that identifies the wake-on-LAN pattern and is set to a value that is unique among the wake-on-LAN patterns on a network adapter. The pattern ID is set before the OS sends an add to the underlying drivers or completes the request to the overlying driver. + +## TLV Type + + +0xE3 + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|-----------------------------| +| UINT32 | The wake-on-LAN pattern ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +## See also + + +[OID\_WDI\_SET\_ADD\_WOL\_PATTERN](https://msdn.microsoft.com/library/windows/hardware/dn925858) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_BITMAP_PATTERN_ID%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern.md new file mode 100644 index 0000000000..dc622c0e14 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-bitmap-pattern.md @@ -0,0 +1,73 @@ +--- +title: WDI_TLV_WAKE_PACKET_BITMAP_PATTERN +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_BITMAP_PATTERN is a TLV that contains a wake-on-LAN pattern. +ms.assetid: 5BE0F668-A3B4-4ECF-B963-EC4DD1B1A8AE +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_BITMAP_PATTERN Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN + + +WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN is a TLV that contains a wake-on-LAN pattern. + +## TLV Type + + +0x5B + +## Length + + +The sum (in bytes) of the sizes of all contained TLVs. + +## Values + + +| Type | Multiple TLV instances allowed | Optional | Description | +|----------------------------------------------------------------------------------------------|--------------------------------|----------|------------------------------------------------------------------------------| +| [**WDI\_TLV\_WAKE\_PACKET\_BITMAP\_PATTERN\_ID**](wdi-tlv-wake-packet-bitmap-pattern-id.md) | | | Specifies the wake-on-LAN pattern ID. | +| [**WDI\_TLV\_BITMAP\_PATTERN**](wdi-tlv-bitmap-pattern.md) | | | Specifies the wake-on-LAN pattern. | +| [**WDI\_TLV\_BITMAP\_PATTERN\_MASK**](wdi-tlv-bitmap-pattern-mask.md) | | | Specifies the wake-on-LAN pattern mask. The length is (PatternLength + 7)/8. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_BITMAP_PATTERN%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-eapol-request-id-message.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-eapol-request-id-message.md new file mode 100644 index 0000000000..43e67e262a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-eapol-request-id-message.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_WAKE_PACKET_EAPOL_REQUEST_ID_MESSAGE +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_EAPOL_REQUEST_ID_MESSAGE is a TLV that contains the wake-on-LAN pattern ID of a EAPOL request ID message. +ms.assetid: CB898EF0-3ACF-4026-8650-91EF18E93766 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_EAPOL_REQUEST_ID_MESSAGE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_EAPOL\_REQUEST\_ID\_MESSAGE + + +WDI\_TLV\_WAKE\_PACKET\_EAPOL\_REQUEST\_ID\_MESSAGE is a TLV that contains the wake-on-LAN pattern ID of a EAPOL request ID message. + +## TLV Type + + +0x5F + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|---------------------------------------| +| UINT32 | Specifies the wake-on-LAN pattern ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_EAPOL_REQUEST_ID_MESSAGE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv4-tcp-sync.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv4-tcp-sync.md new file mode 100644 index 0000000000..6487a370b3 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv4-tcp-sync.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_WAKE_PACKET_IPv4_TCP_SYNC +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_IPv4_TCP_SYNC is a TLV that contains wake-on-LAN IPv4 TCP sync packet information. +ms.assetid: C1237747-721C-4E44-B2BA-1B93E81174A8 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_IPv4_TCP_SYNC Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_IPv4\_TCP\_SYNC + + +WDI\_TLV\_WAKE\_PACKET\_IPv4\_TCP\_SYNC is a TLV that contains wake-on-LAN IPv4 TCP sync packet information. + +## TLV Type + + +0x5D + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|------------|------------------------------------------------------------------| +| UINT32 | Specifies the wake-on-LAN pattern ID. | +| UINT8\[4\] | Specifies the IPv4 source address in the TCP SYN packet. | +| UINT8\[4\] | Specifies the IPv4 destination address in the TCP SYN packet. | +| UINT16 | Specifies the TCP source port number in the TCP SYN packet. | +| UINT16 | Specifies the TCP destination port number in the TCP SYN packet. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_IPv4_TCP_SYNC%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv6-tcp-sync.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv6-tcp-sync.md new file mode 100644 index 0000000000..8d773fc472 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-ipv6-tcp-sync.md @@ -0,0 +1,75 @@ +--- +title: WDI_TLV_WAKE_PACKET_IPv6_TCP_SYNC +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_IPv6_TCP_SYNC is a TLV that contains wake-on-LAN IPv6 TCP sync packet information. +ms.assetid: CBC0EA08-FDB4-415B-948C-E906F0471AD2 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_IPv6_TCP_SYNC Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_IPv6\_TCP\_SYNC + + +WDI\_TLV\_WAKE\_PACKET\_IPv6\_TCP\_SYNC is a TLV that contains wake-on-LAN IPv6 TCP sync packet information. + +## TLV Type + + +0x5E + +## Length + + +The sum (in bytes) of the sizes of all contained elements. + +## Values + + +| Type | Description | +|-------------|------------------------------------------------------------------| +| UINT32 | Specifies the WoL pattern ID. | +| UINT8\[16\] | Specifies the IPv6 source address in the TCP SYN packet. | +| UINT8\[16\] | Specifies the IPv6 destination address in the TCP SYN packet. | +| UINT16 | Specifies the TCP source port number in the TCP SYN packet. | +| UINT16 | Specifies the TCP destination port number in the TCP SYN packet. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_IPv6_TCP_SYNC%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-magic-packet.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-magic-packet.md new file mode 100644 index 0000000000..dbd34923bd --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-magic-packet.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_WAKE_PACKET_MAGIC_PACKET +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_MAGIC_PACKET is a TLV that contains a pattern ID of a magic packet for OID_WDI_SET_ADD_WOL_PATTERN. +ms.assetid: F1DEB65B-8DD4-4D4A-9DCB-950C3B562F0A +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_MAGIC_PACKET Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_MAGIC\_PACKET + + +WDI\_TLV\_WAKE\_PACKET\_MAGIC\_PACKET is a TLV that contains a pattern ID of a magic packet for [OID\_WDI\_SET\_ADD\_WOL\_PATTERN](https://msdn.microsoft.com/library/windows/hardware/dn925858). + +## TLV Type + + +0x5C + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|----------------------------------------------------| +| UINT32 | Specifies the wake-on-LAN magic packet pattern ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_MAGIC_PACKET%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wake-packet-pattern-remove.md b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-pattern-remove.md new file mode 100644 index 0000000000..1127df4664 --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wake-packet-pattern-remove.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_WAKE_PACKET_PATTERN_REMOVE +author: windows-driver-content +description: WDI_TLV_WAKE_PACKET_PATTERN_REMOVE is a TLV that contains the wake packet pattern ID to be removed with OID_WDI_SET_REMOVE_WOL_PATTERN. +ms.assetid: 69C87D35-AE6B-4F69-B099-A55B65EDAC58 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WAKE_PACKET_PATTERN_REMOVE Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WAKE\_PACKET\_PATTERN\_REMOVE + + +WDI\_TLV\_WAKE\_PACKET\_PATTERN\_REMOVE is a TLV that contains the wake packet pattern ID to be removed with [OID\_WDI\_SET\_REMOVE\_WOL\_PATTERN](https://msdn.microsoft.com/library/windows/hardware/dn925944). + +## TLV Type + + +0x6B + +## Length + + +The size (in bytes) of a UINT32. + +## Values + + +| Type | Description | +|--------|---------------------------------------| +| UINT32 | Specifies the wake packet pattern ID. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WAKE_PACKET_PATTERN_REMOVE%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-tlv-wfd-association-status.md b/windows-driver-docs-pr/network/wdi-tlv-wfd-association-status.md new file mode 100644 index 0000000000..cef6bfbe4a --- /dev/null +++ b/windows-driver-docs-pr/network/wdi-tlv-wfd-association-status.md @@ -0,0 +1,71 @@ +--- +title: WDI_TLV_WFD_ASSOCIATION_STATUS +author: windows-driver-content +description: WDI_TLV_WFD_ASSOCIATION_STATUS is a TLV that contains the status code to be set when an association request is denied. +ms.assetid: E97868FA-3F18-4EEF-B5EF-E2009381A16E +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WDI_TLV_WFD_ASSOCIATION_STATUS Network Drivers Starting with Windows Vista +--- + +# WDI\_TLV\_WFD\_ASSOCIATION\_STATUS + + +WDI\_TLV\_WFD\_ASSOCIATION\_STATUS is a TLV that contains the status code to be set when an association request is denied. + +## TLV Type + + +0x126 + +## Length + + +The size (in bytes) of a UINT8. + +## Values + + +| Type | Description | +|-------|-------------------------------------------------------------------------------| +| UINT8 | The DOT11\_WFD\_STATUS\_CODE to be set when an association request is denied. | + +  + +Requirements +------------ + + ++++ + + + + + + + + + + + + + + +

Minimum supported client

Windows 10

Minimum supported server

Windows Server 2016

Header

Wditypes.hpp
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WDI_TLV_WFD_ASSOCIATION_STATUS%20%20RELEASE:%20%287/10/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wdi-transmit-operations-and-offloads.md b/windows-driver-docs-pr/network/wdi-transmit-operations-and-offloads.md index 6714262bec..4a922e53a2 100644 --- a/windows-driver-docs-pr/network/wdi-transmit-operations-and-offloads.md +++ b/windows-driver-docs-pr/network/wdi-transmit-operations-and-offloads.md @@ -131,88 +131,31 @@ In the more common case where host-FIPS mode is not enabled (target-implemented The network data is submitted in 802.11 packet format to the port (target device). Each transmitted frame starts with a 802.11 MAC header. The host sets some of the fields of the MAC header, while the target sets other fields. The table below describes which fields of the 802.11 MAC header and cipher headers are populated by the host, and which should be populated by the target device. -Field name -Subfield name -Target-implemented encryption mode -Host-implemented FIPS mode -Set by host -Set by target -Set by host -Set by target -Frame Control -Protocol Version -X -X -Frame Control -Type -X -X -Frame Control -Subtype -X -X -Frame Control -To DS -X -X -Frame Control -From DS -X -X -Frame Control -More Fragments -X -X -Frame Control -Retry -X -X -Frame Control -Pwr Mgmt -X -X -Frame Control -More Data -X -X -Frame Control -Protected Frame -X -X -Frame Control -Order -X -X -Duration/Id -X -X -Address 1 -X -X -Address 2 -X -X -Address 3 -X -X -Sequence Control -Fragment Number -X -X -Sequence Control -Sequence Number -X -X -Address 4 -X -X -QoS Control -Added/populated by target. -Added/populated by target in the case of 11n QoS association. -HT Control -Added/populated by target. -Added/populated by target. -  + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameSubfield nameTarget-implemented encryption modeHost-implemented FIPS mode
Set by hostSet by targetSet by hostSet by target
Frame ControlProtocol VersionXX
Frame ControlTypeXX
Frame ControlSubtypeXX
Frame ControlTo DSXX
Frame ControlFrom DSXX
Frame ControlMore FragmentsXX
Frame ControlRetryXX
Frame ControlPwr MgmtXX
Frame ControlMore DataXX
Frame ControlProtected FrameXX
Frame ControlOrderXX
Duration/IdXX
Address 1XX
Address 2XX
Address 3XX
Sequence ControlFragment NumberXX
Sequence ControlSequence NumberXX
Address 4XX
QoS ControlAdded/populated by target.Added/populated by target in the case of 11n QoS association.
HT ControlAdded/populated by target.Added/populated by target.
## Related topics diff --git a/windows-driver-docs-pr/network/wdi-usb-selective-suspend.md b/windows-driver-docs-pr/network/wdi-usb-selective-suspend.md index 26002593ab..7a11e69b9e 100644 --- a/windows-driver-docs-pr/network/wdi-usb-selective-suspend.md +++ b/windows-driver-docs-pr/network/wdi-usb-selective-suspend.md @@ -17,9 +17,13 @@ To save power, a USB device (such as a Wi-Fi NIC on USB) may go to low power sta In this section: [WDI NDIS idle detection](wdi-ndis-idle-detection.md) + [WDI and WLAN Selective Suspend capability](wdi-and-wlan-selective-suspend-capability.md) + [WDI USB suspend sequence](wdi-usb-suspend-sequence.md) + [WDI USB resume sequence](wdi-usb-resume-sequence.md) + [WDI USB remote wake sequence](wdi-usb-remote-wake-sequence.md)   diff --git a/windows-driver-docs-pr/network/wi-fi-direct-client-operation.md b/windows-driver-docs-pr/network/wi-fi-direct-client-operation.md index b823e160fd..471012ded5 100644 --- a/windows-driver-docs-pr/network/wi-fi-direct-client-operation.md +++ b/windows-driver-docs-pr/network/wi-fi-direct-client-operation.md @@ -1,6 +1,6 @@ --- title: Wi-Fi Direct Client Operation -description: A Wi-Fi Direct Role port is configured in operation mode DOT11\_OPERATION\_MODE\_WFD\_CLIENT before it can function as a Client. +description: A Wi-Fi Direct Role port is configured in operation mode DOT11_OPERATION_MODE_WFD_CLIENT before it can function as a Client. ms.assetid: 5DE4D86F-7EE0-4BB0-87AC-36E99CE3D209 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-constants.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-constants.md new file mode 100644 index 0000000000..ea0b5af294 --- /dev/null +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-constants.md @@ -0,0 +1,161 @@ +--- +title: Wi-Fi Hotspot Offloading Constants +author: windows-driver-content +description: This section describes the constants that are defined for the Wi-Fi Hotspot Offloading framework. +ms.assetid: F09DCB81-C9FF-493B-AE8F-97DE441A4BC3 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wi-Fi Hotspot Offloading Constants + + +This section describes the constants that are defined for the Wi-Fi Hotspot Offloading framework. + +**HS\_CONST\_HOST\_CURRENT\_API\_VERSION** +1 +Current API version number. + +**HS\_CONST\_MAX\_NETWORK\_DISPLAY\_NAME\_LENGTH** +32 +Maximum length of the network display name string. + +**HS\_CONST\_MAX\_REALM\_LENGTH** +255 +Maximum length of the realm value string. + +**HS\_CONST\_MIN\_CONN\_KEEPALIVE\_TIME\_IN\_MINS** +5 +Minimum time between keep-alive message transmissions + +**HS\_CONST\_PROFILE\_UPDATE\_TIME\_IN\_DAYS** +7 +Minimum time between checks for profile updates. + +**HS\_CONST\_MIN\_NETWORK\_PRIORITY\_VALUE** +1 +Minimum network priority value. + +**HS\_CONST\_MAX\_NETWORK\_PRIORITY\_VALUE** +65000 +Maximum network priority value. + +**HS\_MAX\_PHONE\_NUMBER\_LENGTH** +32 +Maximum length of the phone number string. + +**HS\_CONST\_MAX\_HOST\_NAME\_LENGTH** +255 +Maximum length of the host name string. + +**HS\_CONST\_PLUGIN\_MIN\_RANK\_VALUE** +1 +Minimum Rank value. Must be greater than 0. + +**HS\_CONST\_PLUGIN\_MAX\_RANK\_VALUE** +250 +Maximum rank value. Must be less than or equal to 250. + +**HS\_CONST\_MAX\_PROVIDER\_NAME\_LENGTH** +63 +Maximum length of provider name string. + +**HS\_CONST\_MAX\_ADVANCED\_PAGE\_STRING\_LENGTH** +255 +Maximum length of the advanced page string. + +**HS\_CONST\_MAX\_PHONE\_NUMBER\_LENGTH** +32 +Maximum length of the phone number string. + +**HS\_CONST\_MAX\_SUPPORTED\_SIMS** +1000 +Maximum size of the list of supported SIM configurations. + +**HS\_CONST\_MAX\_CELLULAR\_EXCEPTION\_HOSTS** +5 +Maximum size of the list of cellular bearers. + +**HS\_CONST\_MAX\_AUTH\_ERROR\_MSG\_LENGTH** +512 +Maximum length of an authentication error message. + +**HS\_CONST\_MAX\_USER\_MESSAGES\_IN\_MINUTES** +7\*24\*60 +Maximum user messages, in minutes (7 days). + +The following flags are defined for the plug-in and the host to indicate their requirements and capabilities respectively. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_VISIBLE** +0x00000001 +Specifies visible network. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_TYPE\_HIDDEN** +0x00000002 +Specifies hidden network. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_DISPLAY\_NAME** +0x00000010 +Specifies use of display name for EAP-SIM or EAP-AKA authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_AUTH\_NO\_SIM** +0x00000100 +Specifies no-SIM authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_AUTH\_HTTP** +0x00000200 +Specifies HTTP authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_AUTH\_EAP\_SIM** +0x00001000 +Specifies EAP-SIM authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_AUTH\_EAP\_AKA** +0x00002000 +Specifies EAP-AKA authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_AUTH\_EAP\_AKA\_PRIME** +0x00004000 +Specifies EAP-AKA’ (AKA Prime) authentication. + +**HS\_FLAG\_CAPABILITY\_NETWORK\_CUSTOM\_REALM** +0x00010000 +Specifies use of custom realm value for network authentication. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Windows 10 Mobile

Header

Hotspotoffloadplugin.h (include Hotspotoffloadplugin.h)
+ +## See also + + +[Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Wi-Fi%20Hotspot%20Offloading%20Constants%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-enumerations.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-enumerations.md new file mode 100644 index 0000000000..32ffae3eb2 --- /dev/null +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-enumerations.md @@ -0,0 +1,57 @@ +--- +title: Wi-Fi Hotspot Offloading Enumerations +author: windows-driver-content +description: Wi-Fi Hotspot Offloading Enumerations +ms.assetid: f8f5f13a-30e4-4a7a-9ea7-ca0e9c3746f7 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wi-Fi Hotspot Offloading Enumerations + + +This section describes the hotspot offloading enumerations. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

[eHS_AUTHENTICATION_RESULT](ehs-authentication-result.md)

Indicates the result of the authentication attempt.

[eHS_NETWORK_STATE](ehs-network-state.md)

Indicates whether a network is a hotspot network.

[eHS_UNLOAD_REASON](ehs-unload-reason.md)

Indicates the reason why the plug-in was unloaded.

[eHS_UPDATE_RESULT](ehs-update-result.md)

Indicates the result of a “check for updates” request.

+ +  + +## Related topics +[Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Wi-Fi%20Hotspot%20Offloading%20Enumerations%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-functions.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-functions.md new file mode 100644 index 0000000000..dbdd030ebc --- /dev/null +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-functions.md @@ -0,0 +1,147 @@ +--- +title: Wi-Fi Hotspot Offloading Functions +author: windows-driver-content +description: Wi-Fi Hotspot Offloading Functions +ms.assetid: 114e1604-0d9a-418c-aee1-a9b615d13d21 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wi-Fi Hotspot Offloading Functions + + +This section describes the Wi-Fi Hotspot Offloading framework functions. These functions facilitate the interaction between the hotspot plug-in and hotspot plug-in host. + +The following functions are exported by the plug-in DLL. + + ++++ + + + + + + + + + + + + + + + + +
NameDescription

[HSPluginGetVersion](hsplugingetversion.md)

This function verifies that the plug-in and the host versions match.

[HSPluginInitPlugin](hsplugininitplugin.md)

This function is called by the host to initialize the plug-in.

+ +  + +The hotspot plug-in exposes the following functions through the [HOTSPOT\_PLUGIN\_APIS](hotspot-plugin-apis.md) structure. This structure is passed to the hotspot plug-in host during initialization. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

[HS_PLUGIN_CHECK_FOR_UPDATES](hs-plugin-check-for-updates.md)

This function checks for configuration updates.

[HS_PLUGIN_DEINIT](hs-plugin-deinit.md)

This function is called to notify the plug-in that it will be unloaded.

[HS_PLUGIN_DISCONNECT_FROM_NETWORK](hs-plugin-disconnect-from-network.md)

This function is called to notify the plug-in when a device will be disconnected from the network.

[HS_PLUGIN_IS_HOTSPOT_NETWORK](hs-plugin-is-hotspot-network.md)

This function is called by the host to determine if a specified network is a hotspot network.

[HS_PLUGIN_PRE_CONNECT_INIT](hs-plugin-pre-connect-init.md)

This function is called to notify the plug-in to initialize its state when a connection to a hotspot network is in progress.

[HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS](hs-plugin-query-cellular-exception-hosts.md)

This function is called to retrieve the list of hosts that the plug-in will be required to connect to over cellular as part of its authentication process.

[HS_PLUGIN_QUERY_HIDDEN_NETWORK](hs-plugin-query-hidden-network.md)

This function returns the network identity and network profile for a hidden network

[HS_PLUGIN_RESET](hs-plugin-reset.md)

This function is called to reset the plug-in.

[HS_PLUGIN_SEND_KEEP_ALIVE](hs-plugin-send-keep-alive.md)

This function sends a network connection keep-alive message.

[HS_PLUGIN_START_POST_CONNECT_AUTH](hs-plugin-start-post-connect-auth.md)

This function is called to perform any post-connect authentication required to authenticate the device over the network.

[HS_PLUGIN_STOP_POST_CONNECT_AUTH](hs-plugin-stop-post-connect-auth.md)

This function is called to stop the authentication process.

+ +  + +The hotspot plug-in host exposes the following functions through the [HOTSPOT\_HOST\_HANDLERS](hotspot-host-handlers.md) structure. This structure is passed to the hotspot plug-in during initialization. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

[HS_HOST_ALLOCATE_MEMORY](hs-host-allocate-memory.md)

This function returns an amount of memory specified by the caller.

[HS_HOST_FREE_MEMORY](hs-host-free-memory.md)

This function frees any memory that was allocated by the caller.

[HS_HOST_POST_CONNECT_AUTH_COMPLETION](hs-host-post-connect-auth-completion.md)

This function indicates the success or failure of an authentication attempt.

[HS_HOST_SEND_KEEP_ALIVE_COMPLETION](hs-host-send-keep-alive-completion.md)

This function indicates the success or failure of a "Send keep-alive" request.

[HS_HOST_UPDATE_CONFIGURATION_COMPLETION](hs-host-update-configuration-completion.md)

This function indicates the success or failure of a "Check for updates" request.

+ +  + +## Related topics +[Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Wi-Fi%20Hotspot%20Offloading%20Functions%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-guide.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-guide.md index 4e054357cd..c6b14c6dde 100644 --- a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-guide.md +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-guide.md @@ -17,10 +17,10 @@ Wi-Fi Hotspot Offloading enables Windows 10 Mobile to automatically identify and * [Wi-Fi Hotspot Offloading Architecture](wi-fi-hotspot-offloading-architecture.md) * [Wi-Fi Hotspot Offloading Plugin](wi-fi-hotspot-offloading-plugin.md) * [Wi-Fi Discovery Service](wi-fi-discovery-service.md) +* [Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) ## Related Topics -* [Wi-Fi Hotspot Offloading Reference](https://go.microsoft.com/fwlink/p/?linkid=842820) -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20Slicer%20settings%20%20RELEASE:%20%289/2/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-reference.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-reference.md new file mode 100644 index 0000000000..f70a00cef1 --- /dev/null +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-reference.md @@ -0,0 +1,35 @@ +--- +title: Wi-Fi Hotspot Offloading Reference +author: windows-driver-content +description: Wi-Fi Hotspot Offloading Reference +ms.assetid: 2e8dd1a1-a0bc-4f8a-a2ef-0e349dc433a1 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wi-Fi Hotspot Offloading Reference + + +This section contains descriptions of the Wi-Fi Hotspot Offloading programming elements and related information. + +## In this section + + +[Wi-Fi Hotspot Offloading Constants](wi-fi-hotspot-offloading-constants.md) + +[Wi-Fi Hotspot Offloading Structures](wi-fi-hotspot-offloading-structures.md) + +[Wi-Fi Hotspot Offloading Functions](wi-fi-hotspot-offloading-functions.md) + +[Wi-Fi Hotspot Offloading Enumerations](wi-fi-hotspot-offloading-enumerations.md) + +## Related topics +[Wi-Fi Hotspot Offloading Guide](https://go.microsoft.com/fwlink/p/?linkid=842858) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Wi-Fi%20Hotspot%20Offloading%20Reference%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-structures.md b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-structures.md new file mode 100644 index 0000000000..8f1042978e --- /dev/null +++ b/windows-driver-docs-pr/network/wi-fi-hotspot-offloading-structures.md @@ -0,0 +1,97 @@ +--- +title: Wi-Fi Hotspot Offloading Structures +author: windows-driver-content +description: Wi-Fi Hotspot Offloading Structures +ms.assetid: 7ec80296-1ac9-48df-a250-6fd856c57901 +ms.author: windowsdriverdev +ms.date: 07/31/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Wi-Fi Hotspot Offloading Structures + + +This section describes the data structures for the Wi-Fi Hotspot Offloading framework. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

[HOTSPOT_HOST_HANDLERS](hotspot-host-handlers.md)

This structure contains the hotspot host handlers function table.

[HOTSPOT_PLUGIN_APIS](hotspot-plugin-apis.md)

This structure contains the hotspot plug-in APIs function table.

[HS_CONNECTION_CONTEXT](hs-connection-context.md)

This structure contains information required by the Plug-in for post connect authentication.

[HS_DEVICE_IDENTITY](hs-device-identity.md)

This structure contains information about the device manufacturer and phone model.

[HS_MAC_ADDRESS](hs-mac-address.md)

This structure contains the host Media Access Control (MAC) address.

[HS_NETWORK_IDENTITY](hs-network-identity.md)

This structure contains information that uniquely identifies a Wi-Fi network.

[HS_NETWORK_PROFILE](hs-network-profile.md)

This structure contains information required for connection the target network.

[HS_PLUGIN_CELLULAR_EXCEPTION_HOSTS](hs-plugin-cellular-exception-hosts.md)

This structure contains the list of hosts to which the plug-in must connect over a cellular bearer.

[HS_PLUGIN_HOST_NAME](hs-plugin-host-name.md)

This structure contains the host name.

[HS_PLUGIN_PROFILE](hs-plugin-profile.md)

This structure contains information about the plug-in.

[HS_PLUGIN_SUPPORTED_SIMS](hs-plugin-supported-sims.md)

This structure contains the list of supported SIM configurations.

[HS_PLUGIN_VERSION](hs-plugin-version.md)

This structure contains the minimum and maximum hotspot host versions supported by the plug-in.

[HS_SIM_DATA](hs-sim-data.md)

This structure contains identification information acquired from a SIM card.

[HS_SIM_IDENTITY](hs-sim-identity.md)

This structure contains SIM identification information required for EAP-SIM or EAP-AKA authentication.

+ +  + +## Related topics +[Wi-Fi Hotspot Offloading Reference](wi-fi-hotspot-offloading-reference.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Wi-Fi%20Hotspot%20Offloading%20Structures%20%20RELEASE:%20%287/31/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/windot11-h.md b/windows-driver-docs-pr/network/windot11-h.md new file mode 100644 index 0000000000..13c3d59bfe --- /dev/null +++ b/windows-driver-docs-pr/network/windot11-h.md @@ -0,0 +1,219 @@ +--- +title: Windot11.h +author: windows-driver-content +description: This section contains network driver topics for the Windot11.h header. +ms.assetid: 3C31D5E1-39FE-4344-BD40-D0199ACCB670 +keywords: +- Windot11.h network drivers +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Windot11.h + +This section contains network driver topics for the Windot11.h header. These topics may also be shared with the user mode applications that interact with network drivers. + +The Windot11.h header contains definitions for Native 802.11 miniport driver specifications. + +> [!IMPORTANT] +> This section's topics contains pages for definitions, macros, OIDs, status indications, and other data structures that are not part of network driver reference (structures, enumerations, functions, and callbacks). +> +> For more information about network driver reference for this header, see [Windot11.h (reference)](https://msdn.microsoft.com/library/windows/hardware/mt808751). + +## In this section + +* [DOT11_COUNTRY_OR_REGION_STRING](dot11-country-or-region-string.md) +* [DOT11_COUNTRY_STRING](dot11-country-string.md) +* [DOT11_PMKID_VALUE](dot11-pmkid-value.md) +* [NDIS_STATUS_DOT11_ASSOCIATION_COMPLETION](ndis-status-dot11-association-completion.md) +* [NDIS_STATUS_DOT11_ASSOCIATION_START](ndis-status-dot11-association-start.md) +* [NDIS_STATUS_DOT11_CAN_SUSTAIN_AP](ndis-status-dot11-can-sustain-ap.md) +* [NDIS_STATUS_DOT11_CONNECTION_COMPLETION](ndis-status-dot11-connection-completion.md) +* [NDIS_STATUS_DOT11_CONNECTION_START](ndis-status-dot11-connection-start.md) +* [NDIS_STATUS_DOT11_DISASSOCIATION](ndis-status-dot11-disassociation.md) +* [NDIS_STATUS_DOT11_INCOMING_ASSOC_COMPLETION](ndis-status-dot11-incoming-assoc-completion.md) +* [NDIS_STATUS_DOT11_INCOMING_ASSOC_REQUEST_RECEIVED](ndis-status-dot11-incoming-assoc-request-received.md) +* [NDIS_STATUS_DOT11_INCOMING_ASSOC_STARTED](ndis-status-dot11-incoming-assoc-started.md) +* [NDIS_STATUS_DOT11_LINK_QUALITY](ndis-status-dot11-link-quality.md) +* [NDIS_STATUS_DOT11_MPDU_MAX_LENGTH_CHANGED](ndis-status-dot11-mpdu-max-length-changed.md) +* [NDIS_STATUS_DOT11_PHY_FREQUENCY_ADOPTED](ndis-status-dot11-phy-frequency-adopted.md) +* [NDIS_STATUS_DOT11_PHY_STATE_CHANGED](ndis-status-dot11-phy-state-changed.md) +* [NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST](ndis-status-dot11-pmkid-candidate-list.md) +* [NDIS_STATUS_DOT11_ROAMING_COMPLETION](ndis-status-dot11-roaming-completion.md) +* [NDIS_STATUS_DOT11_ROAMING_START](ndis-status-dot11-roaming-start.md) +* [NDIS_STATUS_DOT11_SCAN_CONFIRM](ndis-status-dot11-scan-confirm.md) +* [NDIS_STATUS_DOT11_STOP_AP](ndis-status-dot11-stop-ap.md) +* [NDIS_STATUS_DOT11_TKIPMIC_FAILURE](ndis-status-dot11-tkipmic-failure.md) +* [OID_DOT11_ACTIVE_PHY_LIST](oid-dot11-active-phy-list.md) +* [OID_DOT11_ADDITIONAL_IE](oid-dot11-additional-ie.md) +* [OID_DOT11_ASSOCIATION_PARAMS](oid-dot11-association-params.md) +* [OID_DOT11_ATIM_WINDOW](oid-dot11-atim-window.md) +* [OID_DOT11_AUTO_CONFIG_ENABLED](oid-dot11-auto-config-enabled.md) +* [OID_DOT11_AVAILABLE_CHANNEL_LIST](oid-dot11-available-channel-list.md) +* [OID_DOT11_AVAILABLE_FREQUENCY_LIST](oid-dot11-available-frequency-list.md) +* [OID_DOT11_BEACON_PERIOD](oid-dot11-beacon-period.md) +* [OID_DOT11_CCA_MODE_SUPPORTED](oid-dot11-cca-mode-supported.md) +* [OID_DOT11_CCA_WATCHDOG_COUNT_MAX](oid-dot11-cca-watchdog-count-max.md) +* [OID_DOT11_CCA_WATCHDOG_COUNT_MIN](oid-dot11-cca-watchdog-count-min.md) +* [OID_DOT11_CCA_WATCHDOG_TIMER_MAX](oid-dot11-cca-watchdog-timer-max.md) +* [OID_DOT11_CCA_WATCHDOG_TIMER_MIN](oid-dot11-cca-watchdog-timer-min.md) +* [OID_DOT11_CF_POLLABLE](oid-dot11-cf-pollable.md) +* [OID_DOT11_CHANNEL_AGILITY_ENABLED](oid-dot11-channel-agility-enabled.md) +* [OID_DOT11_CHANNEL_AGILITY_PRESENT](oid-dot11-channel-agility-present.md) +* [OID_DOT11_CIPHER_DEFAULT_KEY](oid-dot11-cipher-default-key.md) +* [OID_DOT11_CIPHER_DEFAULT_KEY_ID](oid-dot11-cipher-default-key-id.md) +* [OID_DOT11_CIPHER_KEY_MAPPING_KEY](oid-dot11-cipher-key-mapping-key.md) +* [OID_DOT11_CONNECT_REQUEST](oid-dot11-connect-request.md) +* [OID_DOT11_COUNTRY_STRING](oid-dot11-country-string.md) +* [OID_DOT11_CREATE_MAC](oid-dot11-create-mac.md) +* [OID_DOT11_CURRENT_ADDRESS](oid-dot11-current-address.md) +* [OID_DOT11_CURRENT_CCA_MODE](oid-dot11-current-cca-mode.md) +* [OID_DOT11_CURRENT_CHANNEL](oid-dot11-current-channel.md) +* [OID_DOT11_CURRENT_CHANNEL_NUMBER](oid-dot11-current-channel-number.md) +* [OID_DOT11_CURRENT_DWELL_TIME](oid-dot11-current-dwell-time.md) +* [OID_DOT11_CURRENT_FREQUENCY](oid-dot11-current-frequency.md) +* [OID_DOT11_CURRENT_INDEX](oid-dot11-current-index.md) +* [OID_DOT11_CURRENT_OPERATION_MODE](oid-dot11-current-operation-mode.md) +* [OID_DOT11_CURRENT_OPTIONAL_CAPABILITY](oid-dot11-current-optional-capability.md) +* [OID_DOT11_CURRENT_PATTERN](oid-dot11-current-pattern.md) +* [OID_DOT11_CURRENT_PHY_ID](oid-dot11-current-phy-id.md) +* [OID_DOT11_CURRENT_REG_DOMAIN](oid-dot11-current-reg-domain.md) +* [OID_DOT11_CURRENT_SET](oid-dot11-current-set.md) +* [OID_DOT11_CURRENT_TX_POWER_LEVEL](oid-dot11-current-tx-power-level.md) +* [OID_DOT11_DATA_RATE_MAPPING_TABLE](oid-dot11-data-rate-mapping-table.md) +* [OID_DOT11_DELETE_MAC](oid-dot11-delete-mac.md) +* [OID_DOT11_DESIRED_BSS_TYPE](oid-dot11-desired-bss-type.md) +* [OID_DOT11_DESIRED_BSSID_LIST](oid-dot11-desired-bssid-list.md) +* [OID_DOT11_DESIRED_COUNTRY_OR_REGION_STRING](oid-dot11-desired-country-or-region-string.md) +* [OID_DOT11_DESIRED_PHY_LIST](oid-dot11-desired-phy-list.md) +* [OID_DOT11_DESIRED_SSID_LIST](oid-dot11-desired-ssid-list.md) +* [OID_DOT11_DISASSOCIATE_PEER_REQUEST](oid-dot11-disassociate-peer-request.md) +* [OID_DOT11_DISCONNECT_REQUEST](oid-dot11-disconnect-request.md) +* [OID_DOT11_DIVERSITY_SELECTION_RX](oid-dot11-diversity-selection-rx.md) +* [OID_DOT11_DIVERSITY_SUPPORT](oid-dot11-diversity-support.md) +* [OID_DOT11_DSSS_OFDM_OPTION_ENABLED](oid-dot11-dsss-ofdm-option-enabled.md) +* [OID_DOT11_DSSS_OFDM_OPTION_IMPLEMENTED](oid-dot11-dsss-ofdm-option-implemented.md) +* [OID_DOT11_DTIM_PERIOD](oid-dot11-dtim-period.md) +* [OID_DOT11_ED_THRESHOLD](oid-dot11-ed-threshold.md) +* [OID_DOT11_EHCC_CAPABILITY_ENABLED](oid-dot11-ehcc-capability-enabled.md) +* [OID_DOT11_EHCC_CAPABILITY_IMPLEMENTED](oid-dot11-ehcc-capability-implemented.md) +* [OID_DOT11_EHCC_NUMBER_OF_CHANNELS_FAMILY_INDEX](oid-dot11-ehcc-number-of-channels-family-index.md) +* [OID_DOT11_EHCC_PRIME_RADIX](oid-dot11-ehcc-prime-radix.md) +* [OID_DOT11_ENABLED_AUTHENTICATION_ALGORITHM](oid-dot11-enabled-authentication-algorithm.md) +* [OID_DOT11_ENABLED_MULTICAST_CIPHER_ALGORITHM](oid-dot11-enabled-multicast-cipher-algorithm.md) +* [OID_DOT11_ENABLED_UNICAST_CIPHER_ALGORITHM](oid-dot11-enabled-unicast-cipher-algorithm.md) +* [OID_DOT11_ENUM_ASSOCIATION_INFO](oid-dot11-enum-association-info.md) +* [OID_DOT11_ENUM_BSS_LIST](oid-dot11-enum-bss-list.md) +* [OID_DOT11_ENUM_PEER_INFO](oid-dot11-enum-peer-info.md) +* [OID_DOT11_ERP_PBCC_OPTION_ENABLED](oid-dot11-erp-pbcc-option-enabled.md) +* [OID_DOT11_ERP_PBCC_OPTION_IMPLEMENTED](oid-dot11-erp-pbcc-option-implemented.md) +* [OID_DOT11_EXCLUDE_UNENCRYPTED](oid-dot11-exclude-unencrypted.md) +* [OID_DOT11_EXCLUDED_MAC_ADDRESS_LIST](oid-dot11-excluded-mac-address-list.md) +* [OID_DOT11_EXTSTA_CAPABILITY](oid-dot11-extsta-capability.md) +* [OID_DOT11_FLUSH_BSS_LIST](oid-dot11-flush-bss-list.md) +* [OID_DOT11_FRAGMENTATION_THRESHOLD](oid-dot11-fragmentation-threshold.md) +* [OID_DOT11_FREQUENCY_BANDS_SUPPORTED](oid-dot11-frequency-bands-supported.md) +* [OID_DOT11_HARDWARE_PHY_STATE](oid-dot11-hardware-phy-state.md) +* [OID_DOT11_HIDDEN_NETWORK_ENABLED](oid-dot11-hidden-network-enabled.md) +* [OID_DOT11_HOP_ALGORITHM_ADOPTED](oid-dot11-hop-algorithm-adopted.md) +* [OID_DOT11_HOP_MODULUS](oid-dot11-hop-modulus.md) +* [OID_DOT11_HOP_OFFSET](oid-dot11-hop-offset.md) +* [OID_DOT11_HOP_TIME](oid-dot11-hop-time.md) +* [OID_DOT11_HOPPING_PATTERN](oid-dot11-hopping-pattern.md) +* [OID_DOT11_HR_CCA_MODE_SUPPORTED](oid-dot11-hr-cca-mode-supported.md) +* [OID_DOT11_IBSS_PARAMS](oid-dot11-ibss-params.md) +* [OID_DOT11_INCOMING_ASSOCIATION_DECISION](oid-dot11-incoming-association-decision.md) +* [OID_DOT11_LONG_RETRY_LIMIT](oid-dot11-long-retry-limit.md) +* [OID_DOT11_MAC_ADDRESS](oid-dot11-mac-address.md) +* [OID_DOT11_MAX_DWELL_TIME](oid-dot11-max-dwell-time.md) +* [OID_DOT11_MAX_RECEIVE_LIFETIME](oid-dot11-max-receive-lifetime.md) +* [OID_DOT11_MAX_TRANSMIT_MSDU_LIFETIME](oid-dot11-max-transmit-msdu-lifetime.md) +* [OID_DOT11_MAXIMUM_LIST_SIZE](oid-dot11-maximum-list-size.md) +* [OID_DOT11_MEDIA_STREAMING_ENABLED](oid-dot11-media-streaming-enabled.md) +* [OID_DOT11_MPDU_MAX_LENGTH](oid-dot11-mpdu-max-length.md) +* [OID_DOT11_MULTI_DOMAIN_CAPABILITY](oid-dot11-multi-domain-capability.md) +* [OID_DOT11_MULTI_DOMAIN_CAPABILITY_ENABLED](oid-dot11-multi-domain-capability-enabled.md) +* [OID_DOT11_MULTI_DOMAIN_CAPABILITY_IMPLEMENTED](oid-dot11-multi-domain-capability-implemented.md) +* [OID_DOT11_MULTICAST_LIST](oid-dot11-multicast-list.md) +* [OID_DOT11_NIC_POWER_STATE](oid-dot11-nic-power-state.md) +* [OID_DOT11_NIC_SPECIFIC_EXTENSION](oid-dot11-nic-specific-extension.md) +* [OID_DOT11_NUMBER_OF_HOPPING_SETS](oid-dot11-number-of-hopping-sets.md) +* [OID_DOT11_OFFLOAD_NETWORK_LIST](oid-dot11-offload-network-list.md) +* [OID_DOT11_OPERATION_MODE_CAPABILITY](oid-dot11-operation-mode-capability.md) +* [OID_DOT11_OPERATIONAL_RATE_SET](oid-dot11-operational-rate-set.md) +* [OID_DOT11_OPTIONAL_CAPABILITY](oid-dot11-optional-capability.md) +* [OID_DOT11_PBCC_OPTION_IMPLEMENTED](oid-dot11-pbcc-option-implemented.md) +* [OID_DOT11_PERMANENT_ADDRESS](oid-dot11-permanent-address.md) +* [OID_DOT11_PMKID_LIST](oid-dot11-pmkid-list.md) +* [OID_DOT11_PORT_STATE_NOTIFICATION](oid-dot11-port-state-notification.md) +* [OID_DOT11_POWER_MGMT_MODE_AUTO_ENABLED](oid-dot11-powermgmt-mode-auto-enabled.md) +* [OID_DOT11_POWER_MGMT_MODE_STATUS](oid-dot11-power-mgmt-mode-status.md) +* [OID_DOT11_POWER_MGMT_REQUEST](oid-dot11-power-mgmt-request.md) +* [OID_DOT11_PREFERRED_MAC](oid-dot11-preferred-mac.md) +* [OID_DOT11_PRIVACY_EXEMPTION_LIST](oid-dot11-privacy-exemption-list.md) +* [OID_DOT11_QOS_PARAMS](oid-dot11-qos-params.md) +* [OID_DOT11_RANDOM_TABLE_FLAG](oid-dot11-random-table-flag.md) +* [OID_DOT11_RECV_SENSITIVITY_LIST](oid-dot11-recv-sensitivity-list.md) +* [OID_DOT11_REG_DOMAINS_SUPPORT_VALUE](oid-dot11-reg-domains-support-value.md) +* [OID_DOT11_RESET_REQUEST](oid-dot11-reset-request.md) +* [OID_DOT11_RF_USAGE](oid-dot11-rf-usage.md) +* [OID_DOT11_RTS_THRESHOLD](oid-dot11-rts-threshold.md) +* [OID_DOT11_SAFE_MODE_ENABLED](oid-dot11-safe-mode-enabled.md) +* [OID_DOT11_SAFE_MODE_HT_ENABLED](oid-dot11-safe-mode-ht-enabled.md) +* [OID_DOT11_SCAN_REQUEST](oid-dot11-scan-request.md) +* [OID_DOT11_SHORT_PREAMBLE_OPTION_IMPLEMENTED](oid-dot11-short-preamble-option-implemented.md) +* [OID_DOT11_SHORT_RETRY_LIMIT](oid-dot11-short-retry-limit.md) +* [OID_DOT11_SHORT_SLOT_TIME_OPTION_ENABLED](oid-dot11-short-slot-time-option-enabled.md) +* [OID_DOT11_SHORT_SLOT_TIME_OPTION_IMPLEMENTED](oid-dot11-short-slot-time-option-implemented.md) +* [OID_DOT11_START_AP_REQUEST](oid-dot11-start-ap-request.md) +* [OID_DOT11_STATION_ID](oid-dot11-station-id.md) +* [OID_DOT11_STATISTICS](oid-dot11-statistics.md) +* [OID_DOT11_SUPPORTED_COUNTRY_OR_REGION_STRING](oid-dot11-supported-country-or-region-string.md) +* [OID_DOT11_SUPPORTED_DATA_RATES_VALUE](oid-dot11-supported-data-rates-value.md) +* [OID_DOT11_SUPPORTED_DSSS_CHANNEL_LIST](oid-dot11-supported-dsss-channel-list.md) +* [OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR](oid-dot11-supported-multicast-algorithm-pair.md) +* [OID_DOT11_SUPPORTED_OFDM_FREQUENCY_LIST](oid-dot11-supported-ofdm-frequency-list.md) +* [OID_DOT11_SUPPORTED_PHY_TYPES](oid-dot11-supported-phy-types.md) +* [OID_DOT11_SUPPORTED_POWER_LEVELS](oid-dot11-supported-power-levels.md) +* [OID_DOT11_SUPPORTED_RX_ANTENNA](oid-dot11-supported-rx-antenna.md) +* [OID_DOT11_SUPPORTED_TX_ANTENNA](oid-dot11-supported-tx-antenna.md) +* [OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR](oid-dot11-supported-unicast-algorithm-pair.md) +* [OID_DOT11_TEMP_TYPE](oid-dot11-temp-type.md) +* [OID_DOT11_TI_THRESHOLD](oid-dot11-ti-threshold.md) +* [OID_DOT11_UNICAST_USE_GROUP_ENABLED](oid-dot11-unicast-use-group-enabled.md) +* [OID_DOT11_UNREACHABLE_DETECTION_THRESHOLD](oid-dot11-unreachable-detection-threshold.md) +* [OID_DOT11_VIRTUAL_STATION_CAPABILITY](oid-dot11-virtual-station-capability.md) +* [OID_DOT11_WFD_ADDITIONAL_IE](oid-dot11-wfd-additional-ie.md) +* [OID_DOT11_WFD_CONNECT_TO_GROUP_REQUEST](-oid-dot11-wfd-connect-to-group-request.md) +* [OID_DOT11_WFD_DESIRED_GROUP_ID](oid-dot11-wfd-desired-group-id.md) +* [OID_DOT11_WFD_DEVICE_CAPABILITY](oid-dot11-wfd-device-capability.md) +* [OID_DOT11_WFD_DEVICE_INFO](oid-dot11-wfd-device-info.md) +* [OID_DOT11_WFD_DEVICE_LISTEN_CHANNEL](oid-dot11-wfd-device-listen-channel.md) +* [OID_DOT11_WFD_DISCONNECT_FROM_GROUP_REQUEST](oid-dot11-wfd-disconnect-from-group-request.md) +* [OID_DOT11_WFD_DISCOVER_REQUEST](oid-dot11-wfd-discover-request.md) +* [OID_DOT11_WFD_ENUM_DEVICE_LIST](oid-dot11-wfd-enum-device-list.md) +* [OID_DOT11_WFD_FLUSH_DEVICE_LIST](oid-dot11-wfd-flush-device-list.md) +* [OID_DOT11_WFD_GET_DIALOG_TOKEN](oid-dot11-wfd-get-dialog-token.md) +* [OID_DOT11_WFD_GROUP_JOIN_PARAMETERS](-oid-dot11-wfd-group-join-parameters.md) +* [OID_DOT11_WFD_GROUP_OWNER_CAPABILITY](oid-dot11-wfd-group-owner-capability.md) +* [OID_DOT11_WFD_GROUP_START_PARAMETERS](oid-dot11-wfd-group-start-parameters.md) +* [OID_DOT11_WFD_LISTEN_STATE_DISCOVERABILITY](oid-dot11-wfd-listen-state-discoverability.md) +* [OID_DOT11_WFD_SECONDARY_DEVICE_TYPE_LIST](oid-dot11-wfd-secondary-device-type-list.md) +* [OID_DOT11_WFD_SEND_GO_NEGOTIATION_CONFIRMATION](oid-dot11-wfd-send-go-negotiation-confirmation.md) +* [OID_DOT11_WFD_SEND_GO_NEGOTIATION_REQUEST](oid-dot11-wfd-send-go-negotiation-request.md) +* [OID_DOT11_WFD_SEND_GO_NEGOTIATION_RESPONSE](oid-dot11-wfd-send-go-negotiation-response.md) +* [OID_DOT11_WFD_SEND_INVITATION_REQUEST](oid-dot11-wfd-send-invitation-request.md) +* [OID_DOT11_WFD_SEND_INVITATION_RESPONSE](oid-dot11-wfd-send-invitation-response.md) +* [OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_REQUEST](-oid-dot11-wfd-send-provision-discovery-request.md) +* [OID_DOT11_WFD_SEND_PROVISION_DISCOVERY_RESPONSE](oid-dot11-wfd-send-provision-discovery-response.md) +* [OID_DOT11_WFD_START_GO_REQUEST](oid-dot11-wfd-start-go-request.md) +* [OID_DOT11_WFD_STOP_DISCOVERY](oid-dot11-wfd-stop-discovery.md) +* [OID_DOT11_WPS_ENABLED](oid-dot11-wps-enabled.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Windot11.h%20%20RELEASE:%20%288/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/ws2def-h.md b/windows-driver-docs-pr/network/ws2def-h.md new file mode 100644 index 0000000000..2dab159e3c --- /dev/null +++ b/windows-driver-docs-pr/network/ws2def-h.md @@ -0,0 +1,42 @@ +--- +title: Ws2def.h +author: windows-driver-content +description: This section contains network driver topics for the Ws2def.h header. +ms.assetid: D84A448E-5810-485F-9CAC-4366E4223DBE +keywords: +- Ws2def.h network drivers +ms.author: windowsdriverdev +ms.date: 08/08/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# Ws2def.h + +This section contains network driver topics for the Ws2def.h header. These topics may also be shared with the user mode applications that interact with network drivers. + +The Ws2def.h header contains definitions for the Winsock2 specification. It is included in Winsock2.h. User mode applications should include Winsock2.h rather than including Ws2def.h directly. Ws2def.h cannot be included by a module that also includes Winsock.h. + +> [!IMPORTANT] +> This section's topics contains pages for definitions, macros, OIDs, status indications, and other data structures that are not part of network driver reference (structures, enumerations, functions, and callbacks). +> +> For more information about network driver reference for this header, see [Ws2def.h (reference)](https://msdn.microsoft.com/library/windows/hardware/mt808757). + +## In this section + +* [AF_INET](af-inet.md) +* [AF_INET6](af-inet6.md) +* [SIO_ADDRESS_LIST_CHANGE](sio-address-list-change.md) +* [SIO_ADDRESS_LIST_QUERY](sio-address-list-query.md) +* [SO_BROADCAST](so-broadcast.md) +* [SO_CONDITIONAL_ACCEPT](so-conditional-accept.md) +* [SO_EXCLUSIVEADDRUSE](so-exclusiveaddruse.md) +* [SO_KEEPALIVE](so-keepalive.md) +* [SO_RCVBUF](so-rcvbuf.md) +* [SO_REUSEADDR](so-reuseaddr.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20Ws2def.h%20%20RELEASE:%20%288/3/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-cache-sd.md b/windows-driver-docs-pr/network/wsk-cache-sd.md new file mode 100644 index 0000000000..77542d9432 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-cache-sd.md @@ -0,0 +1,105 @@ +--- +title: WSK_CACHE_SD +author: windows-driver-content +description: WSK_CACHE_SD +ms.assetid: 60a4c7f9-d7e3-4378-b22b-93c69a9b8a37 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_CACHE_SD Network Drivers Starting with Windows Vista +--- + +# WSK\_CACHE\_SD + + +A WSK application uses the WSK\_CACHE\_SD client control operation to obtain a cached copy of a security descriptor that can be passed to the [**WskSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571149), [**WskSocketConnect**](https://msdn.microsoft.com/library/windows/hardware/ff571150), and [**WskControlSocket**](https://msdn.microsoft.com/library/windows/hardware/ff571127) functions. + +To obtain a cached copy of a security descriptor, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_CACHE_SD

InputSize

sizeof(PSECURITY_DESCRIPTOR)

InputBuffer

A pointer to a PSECURITY_DESCRIPTOR-typed variable. This variable contains a pointer to the SECURITY_DESCRIPTOR structure that defines the uncached security descriptor that is being cached.

OutputSize

sizeof(PSECURITY_DESCRIPTOR)

OutputBuffer

A pointer to a PSECURITY_DESCRIPTOR-typed variable. This variable receives a pointer to a SECURITY_DESCRIPTOR structure that describes the cached security descriptor.

OutputSizeReturned

NULL

Irp

NULL

+ +  + +``` + +``` + +A WSK application must release the cached copy of the security descriptor by using the [**WSK\_RELEASE\_SD**](wsk-release-sd.md) client control operation when the security descriptor is no longer needed. + +For more information about the SECURITY\_DESCRIPTOR structure, see the reference page for SECURITY\_DESCRIPTOR in the Microsoft Windows SDK documentation. + +The *Irp* parameter must be **NULL** for this client control operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_CACHE_SD%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-client-control-operations.md b/windows-driver-docs-pr/network/wsk-client-control-operations.md new file mode 100644 index 0000000000..df33fa8af5 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-client-control-operations.md @@ -0,0 +1,45 @@ +--- +title: WSK Client Control Operations +author: windows-driver-content +description: WSK Client Control Operations +ms.assetid: aa1159f5-defd-440e-9628-906a246c11df +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK WDK networking, control operations + - Winsock Kernel WDK networking, control operations + - WSK WDK networking, operations + - Winsock Kernel WDK networking, operations +--- + +# WSK Client Control Operations + + +The WSK subsystem supports the following WSK client control operations: + +[**WSK\_CACHE\_SD**](wsk-cache-sd.md) + +[**WSK\_RELEASE\_SD**](wsk-release-sd.md) + +[**WSK\_SET\_STATIC\_EVENT\_CALLBACKS**](wsk-set-static-event-callbacks.md) + +[**WSK\_TDI\_BEHAVIOR**](wsk-tdi-behavior.md) + +[**WSK\_TDI\_DEVICENAME\_MAPPING**](wsk-tdi-devicename-mapping.md) + +[**WSK\_TRANSPORT\_LIST\_CHANGE**](wsk-transport-list-change.md) + +[**WSK\_TRANSPORT\_LIST\_QUERY**](wsk-transport-list-query.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK%20Client%20Control%20Operations%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-release-sd.md b/windows-driver-docs-pr/network/wsk-release-sd.md new file mode 100644 index 0000000000..c179d105f0 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-release-sd.md @@ -0,0 +1,103 @@ +--- +title: WSK_RELEASE_SD +author: windows-driver-content +description: WSK_RELEASE_SD +ms.assetid: de8cc759-c778-464e-9e19-984ea20c0d29 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_RELEASE_SD Network Drivers Starting with Windows Vista +--- + +# WSK\_RELEASE\_SD + + +A WSK application uses the WSK\_RELEASE\_SD client control operation to release a cached copy of a security descriptor that either was previously obtained by using the [**WSK\_CACHE\_SD**](wsk-cache-sd.md) client control operation or was retrieved by using the [**SO\_WSK\_SECURITY**](so-wsk-security.md) socket option. + +To release a cached copy of a security descriptor, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_RELEASE_SD

InputSize

sizeof(PSECURITY_DESCRIPTOR)

InputBuffer

A pointer to a PSECURITY_DESCRIPTOR-typed variable. This variable contains a pointer to the SECURITY_DESCRIPTOR structure that defines the cached security descriptor that is being released.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

NULL

+ +  + +``` + +``` + +For more information about the SECURITY\_DESCRIPTOR structure, see the reference page for SECURITY\_DESCRIPTOR in the Microsoft Windows SDK documentation. + +The *Irp* parameter must be **NULL** for this client control operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_RELEASE_SD%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-set-static-event-callbacks.md b/windows-driver-docs-pr/network/wsk-set-static-event-callbacks.md new file mode 100644 index 0000000000..083fdab248 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-set-static-event-callbacks.md @@ -0,0 +1,109 @@ +--- +title: WSK_SET_STATIC_EVENT_CALLBACKS +author: windows-driver-content +description: WSK_SET_STATIC_EVENT_CALLBACKS +ms.assetid: fa95bc7d-c7b2-4cca-a419-ef5eb2520976 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_SET_STATIC_EVENT_CALLBACKS Network Drivers Starting with Windows Vista +--- + +# WSK\_SET\_STATIC\_EVENT\_CALLBACKS + + +A WSK application uses the WSK\_SET\_STATIC\_EVENT\_CALLBACKS client control operation to automatically enable certain event callback functions on every socket that it creates. The event callback functions that are enabled in this manner are always enabled and cannot be disabled or re-enabled later by the WSK application. However, if a WSK application always enables certain event callback functions on every socket that it creates, the application should use this method to automatically enable those event callback functions because it will yield much better performance. + +If a WSK application uses the WSK\_SET\_STATIC\_EVENT\_CALLBACKS client control operation, it must do so before it creates any sockets. + +To automatically enable certain event callback functions on every socket it creates, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_SET_STATIC_EVENT_CALLBACKS

InputSize

sizeof(WSK_EVENT_CALLBACK_CONTROL)

InputBuffer

A pointer to a [WSK_EVENT_CALLBACK_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff571166) structure that specifies the desired event callback functions to be automatically enabled

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

NULL

+ +  + +``` + +``` + +A WSK application can specify a combination of event flags for different socket types in the **EventMask** member of the [**WSK\_EVENT\_CALLBACK\_CONTROL**](https://msdn.microsoft.com/library/windows/hardware/ff571166) structure. When the WSK application creates a new socket, the WSK subsystem will automatically enable the appropriate event callback functions for the specific [category](https://msdn.microsoft.com/library/windows/hardware/ff571093) of WSK socket that is being created. + +For more information about the event flags for the standard WSK event callback functions, see [**SO\_WSK\_EVENT\_CALLBACK**](so-wsk-event-callback.md). + +For more information about enabling and disabling a socket's event callback functions, see [Enabling and Disabling Event Callback Functions](https://msdn.microsoft.com/library/windows/hardware/ff548851). + +The *Irp* parameter must be **NULL** for this client control operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_SET_STATIC_EVENT_CALLBACKS%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-socket-ioctl-operations.md b/windows-driver-docs-pr/network/wsk-socket-ioctl-operations.md new file mode 100644 index 0000000000..c95ba56029 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-socket-ioctl-operations.md @@ -0,0 +1,44 @@ +--- +title: WSK Socket IOCTL Operations +author: windows-driver-content +description: The WSK subsystem supports the following socket I/O control operations +ms.assetid: ffdf74d4-4795-4d3f-aaf0-49db89f5ad93 +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK WDK networking, IOCTL operations + - Winsock Kernel WDK networking, IOCTL operations + - WSK WDK networking , operations + - Winsock Kernel WDK networking, operations +--- + +# WSK Socket IOCTL Operations + + +The WSK subsystem supports the following socket I/O control operations: + +The underlying network protocol might support additional socket I/O control operations. + +## In this section + + +- [**SIO\_WSK\_QUERY\_IDEAL\_SEND\_BACKLOG**](sio-wsk-query-ideal-send-backlog.md) +- [**SIO\_WSK\_QUERY\_INSPECT\_ID**](sio-wsk-query-inspect-id.md) +- [**SIO\_WSK\_QUERY\_RECEIVE\_BACKLOG**](sio-wsk-query-receive-backlog.md) +- [**SIO\_WSK\_REGISTER\_EXTENSION**](sio-wsk-register-extension.md) +- [**SIO\_WSK\_SET\_REMOTE\_ADDRESS**](sio-wsk-set-remote-address.md) +- [**SIO\_WSK\_SET\_SENDTO\_ADDRESS**](sio-wsk-set-sendto-address.md) +- [**SIO\_WSK\_SET\_TCP\_SILENT\_MODE**](sio-wsk-set-tcp-silent-mode.md) + +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK%20Socket%20IOCTL%20Operations%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-socket-options.md b/windows-driver-docs-pr/network/wsk-socket-options.md new file mode 100644 index 0000000000..17f439d69b --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-socket-options.md @@ -0,0 +1,68 @@ +--- +title: WSK Socket Options +author: windows-driver-content +description: WSK Socket Options +ms.assetid: 640681a3-ea68-44c5-be2b-a3bc21bfdb7c +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK Socket Options Network Drivers Starting with Windows Vista +--- + +# WSK Socket Options + + +The WSK subsystem supports the following socket options at the SOL\_SOCKET level: + +[**SO\_BROADCAST**](https://msdn.microsoft.com/library/windows/hardware/ff570828) + +[**SO\_CONDITIONAL\_ACCEPT**](https://msdn.microsoft.com/library/windows/hardware/ff570829) + +[**SO\_EXCLUSIVEADDRUSE**](https://msdn.microsoft.com/library/windows/hardware/ff570830) + +[**SO\_KEEPALIVE**](https://msdn.microsoft.com/library/windows/hardware/ff570831) + +[**SO\_RCVBUF**](https://msdn.microsoft.com/library/windows/hardware/ff570832) + +[**SO\_REUSEADDR**](https://msdn.microsoft.com/library/windows/hardware/ff570833) + +[**SO\_WSK\_EVENT\_CALLBACK**](so-wsk-event-callback.md) + +[**SO\_WSK\_SECURITY**](so-wsk-security.md) + +The underlying network protocol might support additional socket options. + +For more information about each of these socket options, as well as information about socket options at levels other than SOL\_SOCKET, see the "Windows Sockets 2" section of the Microsoft Windows SDK documentation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Ws2def.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK%20Socket%20Options%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-tdi-behavior.md b/windows-driver-docs-pr/network/wsk-tdi-behavior.md new file mode 100644 index 0000000000..108c98ea99 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-tdi-behavior.md @@ -0,0 +1,118 @@ +--- +title: WSK_TDI_BEHAVIOR +author: windows-driver-content +description: WSK_TDI_BEHAVIOR +ms.assetid: 84e4c8c3-2c31-4db5-bb25-309c6bb176ff +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_TDI_BEHAVIOR Network Drivers Starting with Windows Vista +--- + +# WSK\_TDI\_BEHAVIOR + + +**Note**   The TDI feature is deprecated and will be removed in future versions of Microsoft Windows. + +  + +A WSK application uses the WSK\_TDI\_BEHAVIOR client control operation to control whether the WSK subsystem will divert network I/O to [TDI](https://msdn.microsoft.com/library/windows/hardware/ff565094) transports. A WSK application uses this client control operation only if it needs to override the default behavior of the WSK subsystem. + +If a WSK application uses the WSK\_TDI\_BEHAVIOR client control operation, it must do so before it creates any sockets. + +To control whether the WSK subsystem will divert network I/O to TDI transports, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_TDI_BEHAVIOR

InputSize

sizeof(ULONG)

InputBuffer

A pointer to a ULONG typed variable that contains flags that control the behavior of the WSK subsystem.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

NULL

+ +  + +``` + +``` + +The following flags are defined for the WSK\_TDI\_BEHAVIOR client control operation. + +WSK\_TDI\_BEHAVIOR\_BYPASS\_TDI +If a native WSK transport exists for the address family, socket type, and protocol that are specified when the WSK application creates a socket, then, if this flag is set, the WSK subsystem ignores any TDI filter drivers and always uses the native WSK transport. + +The default behavior is that if a TDI filter driver is detected for the address family, socket type, and protocol that are specified when the WSK application creates a new socket, the WSK subsystem diverts the network I/O for the new socket to the TDI transport so that the network traffic and other socket operations pass through the TDI filter driver. + +The *Irp* parameter must be **NULL** for this client control operation. + +**Note**  TDI is not supported in Microsoft Windows versions after Windows Vista. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_TDI_BEHAVIOR%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-tdi-devicename-mapping.md b/windows-driver-docs-pr/network/wsk-tdi-devicename-mapping.md new file mode 100644 index 0000000000..943d9403ca --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-tdi-devicename-mapping.md @@ -0,0 +1,109 @@ +--- +title: WSK_TDI_DEVICENAME_MAPPING +author: windows-driver-content +description: WSK_TDI_DEVICENAME_MAPPING +ms.assetid: 7636fa80-3908-4808-8fb8-6227ec6e023b +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_TDI_DEVICENAME_MAPPING Network Drivers Starting with Windows Vista +--- + +# WSK\_TDI\_DEVICENAME\_MAPPING + + +A WSK application uses the WSK\_TDI\_DEVICENAME\_MAPPING client control operation to map combinations of address family, socket type, and protocol to device names of [TDI](https://msdn.microsoft.com/library/windows/hardware/ff565094) transports. A WSK application uses this client control operation only if it requires support for TDI transports. When a WSK application creates a socket, the WSK subsystem refer to the list of mappings only if there is no native support for the combination of address family, socket type, and protocol specified by the WSK application. + +If a WSK application uses the WSK\_TDI\_DEVICENAME\_MAPPING client control operation to map combinations of address family, socket type, and protocol to device names of TDI transports, it must do so before it creates any sockets. + +To map combinations of address family, socket type, and protocol to device names of TDI transports, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_TDI_DEVICENAME_MAPPING

InputSize

sizeof(WSK_TDI_MAP_INFO)

InputBuffer

A pointer to a [WSK_TDI_MAP_INFO](https://msdn.microsoft.com/library/windows/hardware/ff571192) structure that contains a list of mappings of combinations of address family, socket type, and protocol to [TDI](https://msdn.microsoft.com/library/windows/hardware/ff565091) device names.

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

NULL

+ +  + +``` + +``` + +For more information about using TDI transports, see [Using TDI Transports](https://msdn.microsoft.com/library/windows/hardware/ff571015). + +The *Irp* parameter must be **NULL** for this client control operation. + +**Note**  TDI will not be supported in Microsoft Windows versions after Windows Vista. Use [Windows Filtering Platform](https://msdn.microsoft.com/library/windows/hardware/ff571068) or [Winsock Kernel](https://msdn.microsoft.com/library/windows/hardware/ff571083) instead. + +  + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_TDI_DEVICENAME_MAPPING%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-transport-list-change.md b/windows-driver-docs-pr/network/wsk-transport-list-change.md new file mode 100644 index 0000000000..4478577393 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-transport-list-change.md @@ -0,0 +1,103 @@ +--- +title: WSK_TRANSPORT_LIST_CHANGE +author: windows-driver-content +description: WSK_TRANSPORT_LIST_CHANGE +ms.assetid: 3b12d692-467c-4d31-bd2a-bb6e34d87fde +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_TRANSPORT_LIST_CHANGE Network Drivers Starting with Windows Vista +--- + +# WSK\_TRANSPORT\_LIST\_CHANGE + + +A WSK application uses the WSK\_TRANSPORT\_LIST\_CHANGE client control operation to receive notification if the list of available network transports changes. + +To receive notification of when the list of available network transports changes, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_TRANSPORT_LIST_CHANGE

InputSize

0

InputBuffer

NULL

OutputSize

0

OutputBuffer

NULL

OutputSizeReturned

NULL

Irp

A pointer to an IRP that is queued by the WSK subsystem until the list of available network transports changes. The WSK subsystem will complete the IRP after either a new network transport is added or an existing network transport is removed.

+ +  + +``` + +``` + +An IRP is required for this client control operation. + +The WSK subsystem will cancel any pending IRPs if the WSK application calls [**WskDeregister**](https://msdn.microsoft.com/library/windows/hardware/ff571128) to detach itself from the WSK subsystem. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_TRANSPORT_LIST_CHANGE%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/network/wsk-transport-list-query.md b/windows-driver-docs-pr/network/wsk-transport-list-query.md new file mode 100644 index 0000000000..e9b911faf8 --- /dev/null +++ b/windows-driver-docs-pr/network/wsk-transport-list-query.md @@ -0,0 +1,103 @@ +--- +title: WSK_TRANSPORT_LIST_QUERY +author: windows-driver-content +description: WSK_TRANSPORT_LIST_QUERY +ms.assetid: feb6aed2-fac9-4d3f-a36b-f721c737aacf +ms.author: windowsdriverdev +ms.date: 07/18/2017 +ms.topic: article +ms.prod: windows-hardware +ms.technology: windows-devices +keywords: + - WSK_TRANSPORT_LIST_QUERY Network Drivers Starting with Windows Vista +--- + +# WSK\_TRANSPORT\_LIST\_QUERY + + +A WSK application uses the WSK\_TRANSPORT\_LIST\_QUERY client control operation to retrieve a list of available network transports that can be specified when creating a new socket. + +To retrieve a list of available network transports, a WSK application calls the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function with the following parameters. + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterValue

ControlCode

WSK_TRANSPORT_LIST_QUERY

InputSize

0

InputBuffer

NULL

OutputSize

The size, in bytes, of the array of structures that is pointed to by the OutputBuffer parameter

OutputBuffer

A pointer to an array of [WSK_TRANSPORT](https://msdn.microsoft.com/library/windows/hardware/ff571193) structures that receives the list of available network transports

OutputSizeReturned

A pointer to a SIZE_T-typed variable that receives the number of bytes of data that are copied into the array of structures that is pointed to by the OutputBuffer parameter

Irp

NULL

+ +  + +``` + +``` + +A WSK application can specify zero in the *OutputSize* parameter and **NULL** in the *OutputBuffer* parameter to determine the size of the array of [**WSK\_TRANSPORT**](https://msdn.microsoft.com/library/windows/hardware/ff571193) structures, in bytes, that is required to contain the complete list of available network transports. In such a situation, the call to the [**WskControlClient**](https://msdn.microsoft.com/library/windows/hardware/ff571126) function returns STATUS\_BUFFER\_OVERFLOW, and the variable that is pointed to by the *OutputSizeReturned* parameter contains the required buffer size. The application can then allocate a buffer that is large enough to contain the complete list of available network transports and can call the **WskControlClient** function a second time, specifying the parameters that are shown in the preceding table. + +The *Irp* parameter must be **NULL** for this client control operation. + +Requirements +------------ + + ++++ + + + + + + + + + + +

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

Wsk.h (include Wsk.h)
+ +  + +  + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bnetvista\netvista%5D:%20WSK_TRANSPORT_LIST_QUERY%20%20RELEASE:%20%287/5/2017%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/nfc/enabling.md b/windows-driver-docs-pr/nfc/enabling.md index 2486d9dddb..c818886016 100644 --- a/windows-driver-docs-pr/nfc/enabling.md +++ b/windows-driver-docs-pr/nfc/enabling.md @@ -1,7 +1,7 @@ --- title: Enabling NFP author: windows-driver-content -description: A client can re-enable previously disabled subscriptions, publications, and presence with IOCTL\_NFP\_ENABLE. +description: A client can re-enable previously disabled subscriptions, publications, and presence with IOCTL_NFP_ENABLE. ms.assetid: 5F5F3C85-6B66-4335-ADA1-E4B6E702FFCB keywords: - NFC diff --git a/windows-driver-docs-pr/parports/TOC.md b/windows-driver-docs-pr/parports/TOC.md index 42a26b6f78..fad9859fdd 100644 --- a/windows-driver-docs-pr/parports/TOC.md +++ b/windows-driver-docs-pr/parports/TOC.md @@ -26,5 +26,7 @@ #### [Setting and Clearing a Communication Mode for a Parallel Device](setting-and-clearing-a-communication-mode-for-a-parallel-device.md) #### [Setting Attributes on a Parallel Device](setting-attributes-on-a-parallel-device.md) #### [Reading and Writing a Parallel Device](reading-and-writing-a-parallel-device.md) +#### [Device-specific operations for I/O requests for parallel devices](device-specific-operations-io-requests-parallel-devices.md) +#### [Device-specific operations for I/O requests for parallel ports](device-specific-operations-io-requests-parallel-ports.md) ### [Installing Parallel Ports and Devices](installing-parallel-ports-and-devices.md) diff --git a/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-devices.md b/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-devices.md new file mode 100644 index 0000000000..993057f57d --- /dev/null +++ b/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-devices.md @@ -0,0 +1,362 @@ +--- +title: Device-specific operations for I/O requests for parallel devices +author: windows-driver-content +description: Documents device-specific operations for I/O requests for parallel devices +keywords: ["Parallel devices WDK", "Parallel drivers WDK", "Parallel IRP codes"] +--- + +# Device-specific operations for I/O requests for parallel devices +This topic documents the following device-specific operations for I/O requests for parallel devices + +* [IRP_MJ_CREATE](#irp_mj_create) +* [IRP_MJ_DEVICE_CONTROL](#irp_mj_device_control) +* [IRP_MJ_INTERNAL_DEVICE_CONTROL](#irp_mj_internal_device_control) +* [IRP_MJ_QUERY_INFORMATION](#irp_mj_query_information) +* [IRP_MJ_READ](#irp_mj_read) +* [IRP_MJ_WRITE](#irp_mj_write) + + +## IRP_MJ_CREATE +The [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) request opens a parallel device. + +### When Sent +A client must use an [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) request to open a parallel device before it can access the device. + +### Input Parameters +None. + +### Output Parameters +None. + +### I/O Status Block +The Information member is set to zero. + +The Status member is set to one of the following values: + + +STATUS_SUCCESS + +The device was opened successfully. + +STATUS_ACCESS_DENIED + +The device is already open. + +STATUS_DELETE_PENDING + +The device is in a Plug and Play surprised-removed state. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +STATUS_INVALID_DEVICE_REQUEST + +There is no hardware present. + +STATUS_NOT_A_DIRECTORY + +The device is not a directory. + +### Operation +A parallel device is an exclusive device. If a parallel device is open, the system-supplied bus driver for parallel ports fails any subsequent [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) requests for the device until the device has been closed. A client must open a parallel device before it sends other I/O requests to the device or calls the [parallel device callback routines](https://msdn.microsoft.com/library/windows/hardware/ff544275). + +For more information, see [Opening and Using a Parallel Device](https://msdn.microsoft.com/windows/hardware/drivers/parports/opening-and-using-a-parallel-device). + + +## IRP_MJ_DEVICE_CONTROL +The [IRP_MJ_DEVICE_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff550744) request operates a parallel device. + +### When Sent +A client uses device control requests for the following types of operations: + +* Obtain information about a device +* Set the operating mode of the device + +See [Device Control Requests for Parallel Devices](https://msdn.microsoft.com/library/windows/hardware/ff543945). + +### Input Parameters +Request-specific. + +### Output Parameters +Request-specific. + +### I/O Status Block +The **Information** member is request-specific. + +The **Status** member is set to a request-specific value or to one of following generic status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +The request was canceled. + +STATUS_DELETE_PENDING + +The device is in the process of being removed. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +STATUS_INVALID_PARAMETER + +The system-supplied bus driver for parallel ports does not support the request. + +STATUS_PENDING + +The request is pending. + +STATUS_UNSUCCESSFUL + +The request did not complete successfully. + +### Operation +The operation is request-specific. + + +## IRP_MJ_INTERNAL_DEVICE_CONTROL +The [IRP_MJ_INTERNAL_DEVICE_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff550766) request sets internal operating modes on a parallel device. + +### When Sent +A client uses internal device control requests for the following types of operations: + +* Set the parallel port's communication mode to IEEE 1284-compatible +* Obtain connection information about a parallel port +* Lock and unlock a parallel port for exclusive use by the device + +See Internal [Device Control Requests for Parallel Devices](https://msdn.microsoft.com/library/windows/hardware/ff543945). + +### Input Parameters +Request-specific. + +### Output Parameters +Request-specific. + +### I/O Status Block +The **Information** member is request-specific. + +The **Status** member is set to a request-specific value or to one of following generic status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +The request was canceled. + +STATUS_DELETE_PENDING + +The device is in the process of being removed. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +STATUS_INVALID_PARAMETER + +The parallel bus driver does not support the request. + +STATUS_PENDING + +The request is pending. + +STATUS_UNSUCCESSFUL + +The request did not complete successfully. + +### Operation + +The operation is request-specific. + + +## IRP_MJ_QUERY_INFORMATION +The [IRP_MJ_QUERY_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff550788) request obtains information about the file that represents the parallel device. + +### When Sent +A client sends a query information request to determine the file size or current byte offset of the file pointer. + +### Input Parameters +The **Parameters.QueryFile.FileInformationClass** member is set to **FileStandardInformation** or **FilePositionInformation**. + + +**FileStandardInformation** request: + +The **AssociatedIrp.SystemBuffer** member points to a [FILE_STANDARD_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff545855) structure that the client allocates for output of file information. + +The **Parameters.QueryFile.Length** member is set to the size, in bytes, of a **FILE_STANDARD_INFORMATION** structure. + +**FilePositionInformation** request: + +**AssociatedIrp.SystemBuffer** points to a [FILE_POSITION_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff545848) structure that the client allocates for output of file information. + +The **Parameters.SetFile.Length** member is set to the size, in bytes, of a **FILE_POSITION_INFORMATION** structure. + +### Output Parameters +**AssociatedIrp.SystemBuffer** points to the requested information. + +**FileStandardInformation** request type: + +Sets the following members in the **FILE_STANDARD_INFORMATION** structure: + +* **AllocationSize.QuadPart** set to zero. +* **EndOfFile** is set to the value of the **AllocationSize** member. +* **NumberOfLinks** is set to zero. +* **DeletePending** is set to **FALSE**. +* **Directory** is set to **FALSE**. + +**FilePositionInformation** request type: + +Sets the **CurrentByteOffset.QuadPart** member of a **FILE_POSITION_INFORMATION** structure to zero. + +### I/O Status Block +If the request succeeds, the **Information** member is set to the size, in bytes, of the structure associated with the type of request. Otherwise, the **Information** member is set to zero. + +The **Status** member is set to one of the following status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_BUFFER_TOO_SMALL + +The size, in bytes, of the structure, specified by the input parameter, is less than the size, in bytes, of the structure associated with the request type. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +STATUS_INVALID_PARAMETER + +The specified type of information is not valid. + +### Operation +The system-supplied bus driver for parallel ports supports queries for the following types of information: + +* **FileStandardInformation** +* **FilePositionInformation** + + +## IRP_MJ_READ +The [IRP_MJ_READ](https://msdn.microsoft.com/library/windows/hardware/ff550794) request obtains input data from a parallel device. + +### When Sent +A client uses an [IRP_MJ_READ](https://msdn.microsoft.com/library/windows/hardware/ff550794) request to obtain input from a parallel device. + +### Input Parameters +The **Parameters.Read.Length** member points to the number of bytes to read from the parallel device. + +### Output Parameters +The **AssociatedIrp.SystemBuffer** member points to a read buffer that the client allocates for the read data. The buffer must be large enough to hold the requested number of bytes. + +### I/O Status Block +The **Information** member is set to the number of bytes actually read from the parallel device. + +The **Status** member is set to one of the following status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_DELETE_PENDING + +The device is in the process of being removed. + +STATUS_CANCELLED + +The request was canceled. + +STATUS_PENDING + +The request is queued on a work queue for the parallel device. + +STATUS_INVALID_PARAMETER + +The **Parameters.Write.ByteOffset** member is not zero. Note that both read and write requests use this member. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +### Operation +The system-supplied bus driver for parallel ports uses the read protocol set for the parallel device. The default read protocol is NIBBLE_MODE. A client can negotiate a read protocol by using an [IOCTL_IEEE1284_NEGOTIATE](https://msdn.microsoft.com/library/windows/hardware/ff543978) request. + +The parallel port bus driver sets a cancel routine for the read request, marks the read request as pending, and queues the read request on a work queue. The read request is held in the work queue in a state that can be canceled until the read request is either completed or canceled by the client. + +For more information, see [Reading and Writing a Parallel Device](https://msdn.microsoft.com/windows/hardware/drivers/parports/reading-and-writing-a-parallel-device). + + +## IRP_MJ_WRITE +The [IRP_MJ_WRITE](https://msdn.microsoft.com/library/windows/hardware/ff550819) request transfers output data to a parallel device. + +### When Sent +A client uses an [IRP_MJ_WRITE](https://msdn.microsoft.com/library/windows/hardware/ff550819) request whenever it transfers output data to a parallel device. + +### Input Parameters +The **AssociatedIrp.SystemBuffer** points to a write buffer that the client allocates for write data. The buffer must be large enough to hold the requested number of bytes to write to the parallel device. + +The **Parameters.Write.Length** member points to the number of bytes to write to the parallel device. + +### Output Parameters +None. + +### I/O Status Block +The **Information** member is set to the number of bytes actually written to the parallel device. + +The **Status** member is set to one of the following values: + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_DELETE_PENDING + +The device is in the process of being removed. + +STATUS_CANCELLED + +The request was canceled. + +STATUS_PENDING + +The request is queued on a work queue for the parallel device. + +STATUS_INVALID_PARAMETER + +The **Parameters.Write.ByteOffset** member is not zero. + +STATUS_DEVICE_REMOVED + +The device has been removed. + +### Operation +The system-supplied bus driver for parallel ports transfers data by using the write protocol that is set for the parallel device. The default write protocol is CENTRONICS. A client can negotiate a write protocol by using an [IOCTL_IEEE1284_NEGOTIATE](https://msdn.microsoft.com/library/windows/hardware/ff543978) request. + +The parallel port bus driver sets a cancel routine for the write request, marks the write request as pending, and queues the write request on a work queue. The write request is held in a state that can be canceled until the request is either completed or canceled. + +For more information, see [Reading and Writing a Parallel Device](https://msdn.microsoft.com/windows/hardware/drivers/parports/reading-and-writing-a-parallel-device). + +## Related topics + +[Device Control Requests for Parallel Devices](https://msdn.microsoft.com/library/windows/hardware/ff543945). + +[FILE_POSITION_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff545848) [FILE_STANDARD_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff545855) + +[Opening and Using a Parallel Device](https://msdn.microsoft.com/windows/hardware/drivers/parports/opening-and-using-a-parallel-device) + +[Operating a Parallel Device Attached to a Parallel Port](https://msdn.microsoft.com/windows/hardware/drivers/parports/operating-a-parallel-device-attached-to-a-parallel-port.md) + +[Parallel device callback routines](https://msdn.microsoft.com/library/windows/hardware/ff544275) + +[Reading and Writing a Parallel Device](https://msdn.microsoft.com/windows/hardware/drivers/parports/reading-and-writing-a-parallel-device) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20Slicer%20settings%20%20RELEASE:%20%289/2/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-ports.md b/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-ports.md new file mode 100644 index 0000000000..7ff36ffc94 --- /dev/null +++ b/windows-driver-docs-pr/parports/device-specific-operations-io-requests-parallel-ports.md @@ -0,0 +1,99 @@ +--- +title: Device-specific operations for I/O requests for parallel ports +author: windows-driver-content +description: Documents device-specific operations for I/O requests for parallel ports +keywords: ["Parallel ports WDK", "Parallel drivers WDK", "Parallel IRP codes"] +--- + +# Device-specific operations for I/O requests for parallel ports +This topic documents the following device-specific operations for I/O requests for parallel ports: + +* [IRP_MJ_CREATE](#irp_mj_create) +* [IRP_MJ_INTERNAL_DEVICE_CONTROL](#irp_mj_internal_device_control) + + +## IRP_MJ_CREATE +The [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) request opens a parallel port. + +### When Sent +A client must use an [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) request to open a parallel port before it can access the port or a device connected to the port. + +### Input Parameters +None. + +### Output Parameters +None. + +### I/O Status Block +The **Information** member is set to zero. + +The **Status** member is set to one of the following values: + + +STATUS_SUCCESS + +The parallel port was successfully opened. + +STATUS_DELETE_PENDING + +The device is in the process of being removed by the Plug and Play manager. + +### Operation +A parallel port is a shared device. When the system-supplied function driver for parallel ports receives an open request for an parallel port, it simply increments the count of open files on the parallel port. + + +## IRP_MJ_INTERNAL_DEVICE_CONTROL +The [IRP_MJ_INTERNAL_DEVICE_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff550766) request sets internal operating modes on a parallel port. + +### When Sent +A client sends an internal device control request to do the following types of operations: + +* Obtain information about the port +* Allocate the port or select a device on the port +* Set the communication mode + +See [Internal Device Control Requests for Parallel Ports](https://msdn.microsoft.com/library/windows/hardware/ff543963). + +### Input Parameters +The input is request-specific. + +### Output Parameters +The output is request-specific. + +### I/O Status Block +The Information member is request-specific. + +The Status member is set to a request-specific value or to one of the following generic status values: + + +STATUS_SUCCESS + +The request was completed successfully. + +STATUS_CANCELLED + +The request was canceled. + +STATUS_DELETE_PENDING + +The drive is in the process of being removed. + +STATUS_INVALID_PARAMETER + +The system-supplied function driver for parallel ports does not support the request. + +STATUS_PENDING + +The request is pending. + +### Operation +The operation is request-specific. + +## Related topics + +[Internal Device Control Requests for Parallel Ports](https://msdn.microsoft.com/library/windows/hardware/ff543963) + +[Operating a Parallel Device Attached to a Parallel Port](https://msdn.microsoft.com/windows/hardware/drivers/parports/operating-a-parallel-device-attached-to-a-parallel-port.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20Slicer%20settings%20%20RELEASE:%20%289/2/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/partnerapps/create-a-system-settings-application.md b/windows-driver-docs-pr/partnerapps/create-a-system-settings-application.md index 65fe8fd18f..fdc631bbd8 100644 --- a/windows-driver-docs-pr/partnerapps/create-a-system-settings-application.md +++ b/windows-driver-docs-pr/partnerapps/create-a-system-settings-application.md @@ -11,15 +11,31 @@ ms.technology: windows-devices # Create a partner settings app +OEMs and mobile operators can expose custom settings for hardware components that they add to a device to differentiate it from other devices, such as speakers, sensors, or microphones. Up to five of these settings appear as additional links in one of the Settings app's level two pages. -OEMs and mobile operators can expose custom settings for hardware components that they add to a device to differentiate it from other devices, such as speakers, sensors, or microphones. These settings appear in the **Extras** page of the **Settings** application, along with other system settings provided by the operating system. To add custom settings, partners create an partner settings app. +For example, in the **Devices** tab of the **Settings** app, the following pages can have up to five additional links to custom settings apps: +* Printers & scanners +* Connected devices +* Bluetooth +* Mouse +* Touchpad +* Typing +* Pen and Windows Ink +* AutoPlay +* USB + +![Devices list in Settings app](images/devices-list-in-settings.png) + +You can find a list of all level two pages in the [Launch the Windows Settings app](https://msdn.microsoft.com/en-us/windows/uwp/launch-resume/launch-settings-app) topic. It is important to note that all links must relevant to the page they are placed on. + +In addition to the five links, you are able to add up to five search terms on each page. Search terms must be relevant to the content on the page. For the best experience, use specific phrases for your terms, as general and one-word terms may cause your links to not be displayed in relevant searchs. For example, if you have a “Fabricam multipen” device, create a search phrase like “set up fabricam mulitipen” instead of a generic search term such as “pen”. ## Characteristics of partner settings app Partner settings apps have the following characteristics: -- They are Universal Windows Platform (UWP) apps, or, in the case of Windows Phone, they can also be Microsoft Silverlight apps on Windows Phone . +- They are Universal Windows Platform (UWP) apps, or, in the case of Windows Phone, can also be Windows Phone Silverlight apps. - Users can uninstall them directly just like any other application. They can be upgraded by updating the settings application in the Store like any other Windows app. @@ -27,78 +43,44 @@ Partner settings apps have the following characteristics: - They are published to a hidden location in the Store that users cannot browse to or find by using search. -- They can have their own tile but cannot be pinned to the Start menu. - ## Creating system settings applications -Settings applications are Windows apps and should therefore conform to all programming guidelines for Windows apps (see [Guidelines for Windows Runtime apps)](https://msdn.microsoft.com/library/windows/apps/hh465424.aspx): - -1. Use the Windows Software Development Kit (SDK) to create a Windows app. For more information on creating a Windows app, see [Build a Universal Windows app](https://msdn.microsoft.com/library/windows/apps/xaml/dn609832.aspx). This application will be the system settings application. If you're writing a settings app targeting the phone, you can also create a Silverlight app on Windows Phone . -2. Declare the settings app capability in the application manifest, as in this xml: ` xmlns:rescap=http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities` -3. Add the extension to the application manifest, as in the following xml. Note that the rescap declaration needs to be part of the Package node. - - ``` - - ``` +Settings applications are Windows Universal apps and should therefore conform to all programming guidelines for Windows Universal apps (see [Guidelines for Universal Windows Platform (UWP) apps](https://msdn.microsoft.com/en-us/library/windows/apps/hh465424.aspx) for more information): - Add the following extension element to you application manifest: +1. Use the Windows Software Development Kit (SDK) to create a Windows Universal app. For more information on creating a Windows Universal app, see [Build UWP apps with Visual Studio](https://msdn.microsoft.com/en-us/library/windows/apps/xaml/dn609832.aspx). This application will be a system settings application. If you're writing a settings app targeting Windows Phone, you can also create a Windows Phone Silverlight app. +2. Declare the settings app capability and the SettingPageUri to describe the page that your application link is listed. Also add the AppActivationMode setting to point to the link. Do this in the application manifest: `xmlns:rescap=http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities` ``` - - - + + + + + + + setup foo + disable foo + + + + ``` - The extension element needs to be added inside of the application node, as in the following example. - - ``` - - - - - - - - - - - - - - ``` - - **Note**  If a settings application is detected by the operating system when the system boots up, a custom settings category called **Extras** is created at the bottom of the settings page. This category name cannot be changed, and all settings apps not created by Microsoft will populate this same category. - -   - -4. Configure the system settings application as a preinstalled application by submitting the application to Windows Dev Center to sign the .appx and obtain a license file, and then include the application in a device image using Windows Imaging and Configuration Designer (ICD). For more information about creating a preinstalled application, see [Preinstalled apps](https://msdn.microsoft.com/library/windows/hardware/mt269740). For more information about Windows ICD, including how to download and install it, see [Getting started with Windows ICD](https://msdn.microsoft.com/library/windows/hardware/dn916112.aspx). To learn how to add an application to the an image using Windows ICD, see the **To add an app** section of the [Configure customizations using Windows ICD](https://msdn.microsoft.com/library/windows/hardware/dn916109.aspx) topic. +3. Configure the system settings application as a preinstalled application by submitting the application to Windows Dev Center to sign the .appx and obtain a license file, and then include the application in the device image. ## Updated system settings applications Settings applications follow the typical process for any Windows app. Partners can submit updates to system settings applications to the Store. After an update is submitted, customers who have the system settings application installed are notified of the update and can install the update through the Store. -Because a system settings application does not appear in the application list on devices, users might be confused when they are notified of an update for the application on the Store. To help avoid confusion, Microsoft recommends providing some context for users by specifying in the Store description for the application that it provides system-level settings that appear in **Settings** on the device. +Because system settings applications don't appear in devices' application list, users might be confused when they are notified of an update for the application on the Store. To help avoid confusion, Microsoft recommends providing some context for users by specifying in the Store description for the application that it provides system-level settings that appear in **Settings** on the device. ## What happens to legacy Control Panel or system settings apps when the OS upgrades to Windows 10? -If your Control Panel application was written for Windows 7, Windows 8, or Windows 8.1, it will continue to work in the legacy Control Panel, but it will not support any of the features of the Windows 10 system settings app. Likewise, if your legacy system settings app was written for Windows 8 or Windows 8.1, it will continue to work but it will not support any of the features of the Windows 10 system settings app. Legacy apps cannot display in the Windows 10 system settings app. +If your Control Panel application was written for Windows 7, Windows 8, or Windows 8.1, it will continue to work in the legacy Control Panel, but it will not support any of the features of the Windows 10 system settings app. Likewise, if your legacy system settings app was written for Windows 8 or Windows 8.1, it will continue to work but it will not support any of the features of the Windows 10 system settings app. Legacy apps cannot display in the Windows 10 system settings app. All UWP apps in the Windows 10 settings app must be preinstalled on the machine. Control Panel is deprecated and will be removed in an upcoming release.   diff --git a/windows-driver-docs-pr/partnerapps/images/devices-list-in-settings.png b/windows-driver-docs-pr/partnerapps/images/devices-list-in-settings.png new file mode 100644 index 0000000000..7a2abd5e21 Binary files /dev/null and b/windows-driver-docs-pr/partnerapps/images/devices-list-in-settings.png differ diff --git a/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-bus-interface-standard-inter.md b/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-bus-interface-standard-inter.md index a66a043b62..3b6d03155d 100644 --- a/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-bus-interface-standard-inter.md +++ b/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-bus-interface-standard-inter.md @@ -1,6 +1,6 @@ --- -title: Access Memory by Using a BUS\_INTERFACE\_STANDARD -description: Access PCMCIA Attribute Memory by Using a BUS\_INTERFACE\_STANDARD Interface +title: Access Memory by Using a BUS_INTERFACE_STANDARD +description: Access PCMCIA Attribute Memory by Using a BUS_INTERFACE_STANDARD Interface ms.assetid: 2696a9ca-38b5-47f2-9639-029bba1173b5 keywords: - attribute memory WDK PCMCIA bus , BUS_INTERFACE_STANDARD interface diff --git a/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-pcmcia-interface-standard-in.md b/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-pcmcia-interface-standard-in.md index ab928372e8..569f2fb1b6 100644 --- a/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-pcmcia-interface-standard-in.md +++ b/windows-driver-docs-pr/pcmcia/access-pcmcia-attribute-memory-by-using-a-pcmcia-interface-standard-in.md @@ -1,6 +1,6 @@ --- title: Access Memory by Using PCMCIA_INTERFACE_STANDARD -description: Access PCMCIA Attribute Memory by Using a PCMCIA\_INTERFACE\_STANDARD Interface +description: Access PCMCIA Attribute Memory by Using a PCMCIA_INTERFACE_STANDARD Interface ms.assetid: cd73a8da-1441-4e95-a955-97235ad091ce keywords: - PCMCIA_INTERFACE_STANDARD diff --git a/windows-driver-docs-pr/pcmcia/calling-a-pcmcia-interface-standard-interface-routine.md b/windows-driver-docs-pr/pcmcia/calling-a-pcmcia-interface-standard-interface-routine.md index 973f792751..ccae3a4e18 100644 --- a/windows-driver-docs-pr/pcmcia/calling-a-pcmcia-interface-standard-interface-routine.md +++ b/windows-driver-docs-pr/pcmcia/calling-a-pcmcia-interface-standard-interface-routine.md @@ -1,6 +1,6 @@ --- -title: Calling a PCMCIA\_INTERFACE\_STANDARD Interface Routine -description: Calling a PCMCIA\_INTERFACE\_STANDARD Interface Routine +title: Calling a PCMCIA_INTERFACE_STANDARD Interface Routine +description: Calling a PCMCIA_INTERFACE_STANDARD Interface Routine ms.assetid: 468d2037-a7d5-4851-9f41-d1e6c9006750 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/pcmcia/functionality-of-the-pcmcia-interface-standard-interface.md b/windows-driver-docs-pr/pcmcia/functionality-of-the-pcmcia-interface-standard-interface.md index 304826a000..97244913ab 100644 --- a/windows-driver-docs-pr/pcmcia/functionality-of-the-pcmcia-interface-standard-interface.md +++ b/windows-driver-docs-pr/pcmcia/functionality-of-the-pcmcia-interface-standard-interface.md @@ -1,6 +1,6 @@ --- -title: Functionality of the PCMCIA\_INTERFACE\_STANDARD Interface -description: Functionality of the PCMCIA\_INTERFACE\_STANDARD Interface +title: Functionality of the PCMCIA_INTERFACE_STANDARD Interface +description: Functionality of the PCMCIA_INTERFACE_STANDARD Interface ms.assetid: 301b4165-4753-4d55-9760-17628174c043 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/pcmcia/obtaining-a-pcmcia-interface-standard-interface.md b/windows-driver-docs-pr/pcmcia/obtaining-a-pcmcia-interface-standard-interface.md index 25f39ebe74..2ee8346048 100644 --- a/windows-driver-docs-pr/pcmcia/obtaining-a-pcmcia-interface-standard-interface.md +++ b/windows-driver-docs-pr/pcmcia/obtaining-a-pcmcia-interface-standard-interface.md @@ -1,6 +1,6 @@ --- -title: Obtaining a PCMCIA\_INTERFACE\_STANDARD Interface -description: Obtaining a PCMCIA\_INTERFACE\_STANDARD Interface +title: Obtaining a PCMCIA_INTERFACE_STANDARD Interface +description: Obtaining a PCMCIA_INTERFACE_STANDARD Interface ms.assetid: 475bf66a-5b6e-4a06-95f7-b7280dd7276d ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/pcmcia/pcmcia-interface-standard-interface-for-memory-cards.md b/windows-driver-docs-pr/pcmcia/pcmcia-interface-standard-interface-for-memory-cards.md index cedd596c31..bf40c789a4 100644 --- a/windows-driver-docs-pr/pcmcia/pcmcia-interface-standard-interface-for-memory-cards.md +++ b/windows-driver-docs-pr/pcmcia/pcmcia-interface-standard-interface-for-memory-cards.md @@ -1,6 +1,6 @@ --- -title: PCMCIA\_INTERFACE\_STANDARD Interface for Memory Cards -description: PCMCIA\_INTERFACE\_STANDARD Interface for Memory Cards +title: PCMCIA_INTERFACE_STANDARD Interface for Memory Cards +description: PCMCIA_INTERFACE_STANDARD Interface for Memory Cards ms.assetid: 3bb48ba8-388d-46c9-96a7-4cd0829e6f78 keywords: - PCMCIA WDK buses , PCMCIA_INTERFACE_STANDARD interface diff --git a/windows-driver-docs-pr/print/-define-preprocessor-directive.md b/windows-driver-docs-pr/print/-define-preprocessor-directive.md index 7447230124..6dede7e495 100644 --- a/windows-driver-docs-pr/print/-define-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-define-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Define Preprocessor Directive' +title: '#Define Preprocessor Directive' author: windows-driver-content -description: '\ Define Preprocessor Directive' +description: '#Define Preprocessor Directive' ms.assetid: e2fab866-dc81-4e4a-bac7-291d0b803962 keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-disableppdirective-preprocessor-directive.md b/windows-driver-docs-pr/print/-disableppdirective-preprocessor-directive.md index 6a915618a4..4c4ae7cc78 100644 --- a/windows-driver-docs-pr/print/-disableppdirective-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-disableppdirective-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ DisablePPDirective Preprocessor Directive' +title: '#DisablePPDirective Preprocessor Directive' author: windows-driver-content -description: '\ DisablePPDirective Preprocessor Directive' +description: '#DisablePPDirective Preprocessor Directive' ms.assetid: 5f85a6b1-a72f-45e2-901a-7bce94b4793c keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-else-conditional-preprocessor-directive.md b/windows-driver-docs-pr/print/-else-conditional-preprocessor-directive.md index 70e2551247..95b9f430e5 100644 --- a/windows-driver-docs-pr/print/-else-conditional-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-else-conditional-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Else Conditional Preprocessor Directive' +title: '#Else Conditional Preprocessor Directive' author: windows-driver-content -description: '\ Else Conditional Preprocessor Directive' +description: '#Else Conditional Preprocessor Directive' ms.assetid: 3a8ddc60-1db9-4db0-9e55-405c88b84849 keywords: - preprocessor directives WDK GDL , conditional directives diff --git a/windows-driver-docs-pr/print/-elseifdef-conditional-preprocessor-directive.md b/windows-driver-docs-pr/print/-elseifdef-conditional-preprocessor-directive.md index f5029daae4..a18656dcfd 100644 --- a/windows-driver-docs-pr/print/-elseifdef-conditional-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-elseifdef-conditional-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Elseifdef Conditional Preprocessor Directive' +title: '#Elseifdef Conditional Preprocessor Directive' author: windows-driver-content -description: '\ Elseifdef Conditional Preprocessor Directive' +description: '#Elseifdef Conditional Preprocessor Directive' ms.assetid: 0239696a-ea6a-4fd4-b4ca-870a87022c81 keywords: - preprocessor directives WDK GDL , conditional directives diff --git a/windows-driver-docs-pr/print/-enableppdirective-preprocessor-directive.md b/windows-driver-docs-pr/print/-enableppdirective-preprocessor-directive.md index 0842d2326c..b6df4024ad 100644 --- a/windows-driver-docs-pr/print/-enableppdirective-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-enableppdirective-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ EnablePPDirective Preprocessor Directive' +title: '#EnablePPDirective Preprocessor Directive' author: windows-driver-content -description: '\ EnablePPDirective Preprocessor Directive' +description: '#EnablePPDirective Preprocessor Directive' ms.assetid: aebb11ec-b281-461e-b3fd-65e9b2773049 keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-endif-conditional-preprocessor-directive.md b/windows-driver-docs-pr/print/-endif-conditional-preprocessor-directive.md index 865d9d6716..3a78c6542e 100644 --- a/windows-driver-docs-pr/print/-endif-conditional-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-endif-conditional-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Endif Conditional Preprocessor Directive' +title: '#Endif Conditional Preprocessor Directive' author: windows-driver-content -description: '\ Endif Conditional Preprocessor Directive' +description: '#Endif Conditional Preprocessor Directive' ms.assetid: dfbfdb4a-955b-4ccf-b496-c8c5ddc42d2b keywords: - preprocessor directives WDK GDL , conditional directives diff --git a/windows-driver-docs-pr/print/-ifdef-conditional-preprocessor-directive.md b/windows-driver-docs-pr/print/-ifdef-conditional-preprocessor-directive.md index 5b6354536b..fca04a9097 100644 --- a/windows-driver-docs-pr/print/-ifdef-conditional-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-ifdef-conditional-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Ifdef Conditional Preprocessor Directive' +title: '#Ifdef Conditional Preprocessor Directive' author: windows-driver-content -description: '\ Ifdef Conditional Preprocessor Directive' +description: '#Ifdef Conditional Preprocessor Directive' ms.assetid: 57c59bf8-19bd-47bc-858d-ea500d44fb4d keywords: - preprocessor directives WDK GDL , conditional directives diff --git a/windows-driver-docs-pr/print/-include-preprocessor-directive.md b/windows-driver-docs-pr/print/-include-preprocessor-directive.md index e93a3b6499..5633e8c133 100644 --- a/windows-driver-docs-pr/print/-include-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-include-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Include Preprocessor Directive' +title: '#Include Preprocessor Directive' author: windows-driver-content -description: '\ Include Preprocessor Directive' +description: '#Include Preprocessor Directive' ms.assetid: 6c3e4de7-2007-4a1a-bdb0-fd5b2b64f489 keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-precompiled-preprocessor-directive.md b/windows-driver-docs-pr/print/-precompiled-preprocessor-directive.md index 5f2f9e02b7..b3c8576079 100644 --- a/windows-driver-docs-pr/print/-precompiled-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-precompiled-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ PreCompiled Preprocessor Directive' +title: '#PreCompiled Preprocessor Directive' author: windows-driver-content -description: '\ PreCompiled Preprocessor Directive' +description: '#PreCompiled Preprocessor Directive' ms.assetid: 639db56d-7677-4d21-8329-a0f35d68151e keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-setppprefix-preprocessor-directive.md b/windows-driver-docs-pr/print/-setppprefix-preprocessor-directive.md index e9914ce95f..88c7d6a669 100644 --- a/windows-driver-docs-pr/print/-setppprefix-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-setppprefix-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ SetPPPrefix Preprocessor Directive' +title: '#SetPPPrefix Preprocessor Directive' author: windows-driver-content -description: '\ SetPPPrefix Preprocessor Directive' +description: '#SetPPPrefix Preprocessor Directive' ms.assetid: 3520aa66-1090-40db-9c9f-cfba0e6e2bee keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-undefine-preprocessor-directive.md b/windows-driver-docs-pr/print/-undefine-preprocessor-directive.md index 3dc514f4fc..ff3d6914be 100644 --- a/windows-driver-docs-pr/print/-undefine-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-undefine-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ Undefine Preprocessor Directive' +title: '#Undefine Preprocessor Directive' author: windows-driver-content -description: '\ Undefine Preprocessor Directive' +description: '#Undefine Preprocessor Directive' ms.assetid: 78f6a895-2c30-4a6f-8916-4c18e22e4e70 keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/-undefineprefix-preprocessor-directive.md b/windows-driver-docs-pr/print/-undefineprefix-preprocessor-directive.md index 539c4ead4a..f13e0d768c 100644 --- a/windows-driver-docs-pr/print/-undefineprefix-preprocessor-directive.md +++ b/windows-driver-docs-pr/print/-undefineprefix-preprocessor-directive.md @@ -1,7 +1,7 @@ --- -title: '\ UndefinePrefix Preprocessor Directive' +title: '#UndefinePrefix Preprocessor Directive' author: windows-driver-content -description: '\ UndefinePrefix Preprocessor Directive' +description: '#UndefinePrefix Preprocessor Directive' ms.assetid: 7c99c2cf-6609-4fec-ae21-1477699ba5c8 keywords: - preprocessor directives WDK GDL , keywords diff --git a/windows-driver-docs-pr/print/building-a-basic-v4-printer-driver.md b/windows-driver-docs-pr/print/building-a-basic-v4-printer-driver.md index cfb3b2390c..ba3fa73dc2 100644 --- a/windows-driver-docs-pr/print/building-a-basic-v4-printer-driver.md +++ b/windows-driver-docs-pr/print/building-a-basic-v4-printer-driver.md @@ -28,7 +28,7 @@ The instructions in this topic will focus on the steps required for building a d 3. In the middle pane, select **Printer Driver V4**. -4. Type a name for your driver in the **Name** field, and then click **OK**. For example, you could type *MyV4PrintDriver*. +4. Type a name for your driver in the **Name** field, and then click **OK**. For example, you could type *MyV4PrinterDriver*. 5. In the **Create a v4 Print Driver Wizard**, under **Choose the driver rendering type:**, click **V4 print driver with custom rendering filters (accepts XPS only)**. @@ -38,24 +38,24 @@ The instructions in this topic will focus on the steps required for building a d 8. In the **Setup information (page 2)** section of the Wizard, leave all options at their default settings, then click **Next**. -Microsoft Visual Studio uses the preceding selections to generate the project files for *MyV4PrintDriver*. +Microsoft Visual Studio uses the preceding selections to generate the project files for *MyV4PrinterDriver*. ## Verify the generated driver files -1. Navigate to the folder for the generated driver files. For example, if you named your project *MyV4PrintDriver*, then by default, the files would be saved to the following location: *My Documents > Visual Studio 2013 > Projects > MyV4PrintDriver > MyV4PrintDriver*. +1. Navigate to the folder for the generated driver files. For example, if you named your project *MyV4PrinterDriver*, then by default, the files would be saved to the following location: *My Documents > Visual Studio 2013 > Projects > MyV4PrinterDriver > MyV4PrinterDriver*. 2. Verify that the folder contains the following files: | File name | File type | |--------------------------------------------------------|------------------------------------------------------------| -| MyV4PrintDriver-manifest.ini | Configuration settings file (a.k.a. print driver manifest) | -| MyV4PrintDriver.gpd | Printer description file | -| MyV4PrintDriverPackage-Intellisense.js | JavaScript file for Intellisense | -| MyV4PrintDriverRenderFilter-Intellisense-Windows8.1.js | JavaScript file for Intellisense | -| MyV4PrintDriverRenderFilter.ini | Setup information file | -| MyV4PrintDriverRenderFilter.vcxproj.filters | C++ Project filters file | -| MyV4PrintDriverRenderFilter.vcxproj | Project file | +| MyV4PrinterDriver-manifest.ini | Configuration settings file (a.k.a. print driver manifest) | +| MyV4PrinterDriver.gpd | Printer description file | +| MyV4PrinterDriverPackage-Intellisense.js | JavaScript file for Intellisense | +| MyV4PrinterDriverRenderFilter-Intellisense-Windows8.1.js | JavaScript file for Intellisense | +| MyV4PrinterDriverRenderFilter.ini | Setup information file | +| MyV4PrinterDriverRenderFilter.vcxproj.filters | C++ Project filters file | +| MyV4PrinterDriverRenderFilter.vcxproj | Project file |   @@ -64,42 +64,60 @@ Notice from the preceding table that one of the files that is created is an INF ## Complete the INF file -Configure the \[Version\] section +### Configure the \[Version\] section + 1. Check and make sure that you see this line: **ClassVer**=4.0 + 2. Check and make sure that you see this line: **Signature**=”$WINDOWS NT$” -Configure the \[SourceDiskFiles\] section + +### Configure the \[SourceDiskFiles\] section + Type the following lines: +```Text MyV4PrinterDriver.gpd=1 MyV4PrinterDriver-manifest.ini=1 MyV4PrinterDriverRenderFilter-PipelineConfig.xml=1 -MyV4PrintDriverRenderFilter.dll=1 -Create a section called \[DriverInstall\] at the bottom of the INF file, and configure it +MyV4PrinterDriverRenderFilter.dll=1 +``` + +### Create a section called \[DriverInstall\] at the bottom of the INF file, and configure it + Type the following line in the newly created \[DriverInstall\] section: **CopyFiles**=DriverFiles -Create a section called \[DriverFiles\] at the bottom of the INF file, and configure it + +### Create a section called \[DriverFiles\] at the bottom of the INF file, and configure it + Type the following lines in the newly created \[DriverFiles\] section: +```Text MyV4PrinterDriver.gpd MyV4PrinterDriver-manifest.ini MyV4PrinterDriverRenderFilter-PipelineConfig.xml -MyV4PrintDriverRenderFilter.dll -Configure the \[Standard.NT$ARCH$\] section +MyV4PrinterDriverRenderFilter.dll +``` + +### Configure the \[Standard.NT$ARCH$\] section + Type the following lines to target a particular printer model. For example, if the model of your printer is Fabrikam1234, then you would type the following: -“Model name”=DriverInstall, USBPRINT\\Fabrikam1234 -“Model name”=DriverInstall, WSDPRINT\\Fabrikam1234 -Add **PrinterDriverID** to the INF file +```Text +"Model name"=DriverInstall, USBPRINT\\Fabrikam1234 +"Model name"=DriverInstall, WSDPRINT\\Fabrikam1234 +``` + +### Add **PrinterDriverID** to the INF file + 1. In Visual Studio, in the Solution Explorer, expand the *MyV4PrinterDriver Package* node. @@ -107,16 +125,22 @@ Add **PrinterDriverID** to the INF file 3. In the INF file, in the \[Standard.NT$ARCH$\] section, type the following line: -“Model name”=DriverInstall, +"Model name"=DriverInstall, + And then after the comma, paste the GUID that you copied in the preceding step. The completed \[Standard.NT$ARCH$\] section should like the following: -“Model name”=DriverInstall, USBPRINT\\Fabrikam1234 -“Model name”=DriverInstall, WSDPRINT\\Fabrikam1234 -“Model name”=DriverInstall, {GUID} -Configure the \[String\] section + +```Text +"Model name"=DriverInstall, USBPRINT\\Fabrikam1234 +"Model name"=DriverInstall, WSDPRINT\\Fabrikam1234 +"Model name"=DriverInstall, {GUID} +``` + +### Configure the \[String\] section 1. Type the following, to provide a manufacturer’s name for the target printer. For example, if your company’s name is My Company, you would type the following: -**ManufacturerName** = “My Company” +**ManufacturerName** = "My Company" + 2. Save the INF file. When you complete the INF file, it should look like the following. Note that in place of the *{GUID}* entry that is shown in this sample INF file, your INF file should contain the GUID that you retrieved using the steps in the preceding *Add PrinterDriverID to the INF file* section. @@ -141,15 +165,15 @@ DefaultDestDir = 66000 MyV4PrinterDriver.gpd=1 MyV4PrinterDriver-manifest.ini=1 MyV4PrinterDriverRenderFilter-PipelineConfig.xml=1 -MyV4PrintDriverRenderFilter.dll=1 +MyV4PrinterDriverRenderFilter.dll=1 [Manufacturer] %ManufacturerName%=Standard,NT$ARCH$ [Standard.NT$ARCH$] -“Model name”=DriverInstall, USBPRINT\Fabrikam1234 -“Model name”=DriverInstall, WSDPRINT\Fabrikam1234 -“Model name”=DriverInstall, {GUID} +"Model name"=DriverInstall, USBPRINT\Fabrikam1234 +"Model name"=DriverInstall, WSDPRINT\Fabrikam1234 +"Model name"=DriverInstall, {GUID} [DriverInstall] CopyFiles=DriverFiles @@ -158,7 +182,7 @@ CopyFiles=DriverFiles MyV4PrinterDriver.gpd MyV4PrinterDriver-manifest.ini MyV4PrinterDriverRenderFilter-PipelineConfig.xml -MyV4PrintDriverRenderFilter.dll +MyV4PrinterDriverRenderFilter.dll [Strings] ManufacturerName="My Company" @@ -168,15 +192,15 @@ DiskName="MyV4PrinterDriver Installation Disk" ## Configure driver solution for debugging and deployment -1. In the Solution Explorer, right-click MyV4PrinterDriver Package, then click Properties. +1. In the Solution Explorer, right-click *MyV4PrinterDriver Package*, then click **Properties**. -2. In the MyV4PrinterDriver Package Property Pages window, expand Configuration Properties in the left pane. +2. In the **MyV4PrinterDriver Package Property Pages** window, expand **Configuration Properties** in the left pane. -3. Expand Driver Install, then click Deployment do the following in the right pane: +3. Expand **Driver Install**, then click **Deployment** do the following in the right pane: - Click **Enable deployment** - Check **Remove previous driver versions before deployment** -- Ensure that the **Target Computer Name** is configured. If it isn’t, click “…” and follow the prompts in the **Computer Configuration** wizard to set up a remote target computer +- Ensure that the **Target Computer Name** is configured. If it isn’t, click "…" and follow the prompts in the **Computer Configuration** wizard to set up a remote target computer - Select **Install and Verify**, then select **Default Printer Driver Package Installation Task** from the drop-down box - Type the name of the driver in the **Optional Arguments** field (without any quotes around the name) - Click **OK** @@ -184,7 +208,7 @@ DiskName="MyV4PrinterDriver Installation Disk" ## Configure Driver Signing -1. In the Solution Explorer, right-click MyV4PrinterDriver Package, then click **Properties.** +1. In the Solution Explorer, right-click *MyV4PrinterDriver Package*, then click **Properties**. 2. In the **MyV4PrinterDriver Package Property Pages** window, expand **Configuration Properties** in the left pane. @@ -213,7 +237,7 @@ Create a print queue using either plug-and-play or the Add Printer Wizard. For more information about INF files for the v4 printer driver, see [V4 Driver INF](v4-driver-inf.md). **Note**   -In addition to the files in the preceding table, notice that a *MyV4PrintDriver Render Filter* folder was created. This is the render filter project template and it provides a good foundation for building an XPS rendering filter and an XPS filter pipeline configuration file. For more information about XPS rendering filters, see [XPSDrv Render Module](xpsdrv-render-module.md), and to see an example of an XPS rendering filter, see the [XPS Rasterization Filter Service](http://go.microsoft.com/fwlink/p/?LinkId=617951) sample. +In addition to the files in the preceding table, notice that a *MyV4PrinterDriver Render Filter* folder was created. This is the render filter project template and it provides a good foundation for building an XPS rendering filter and an XPS filter pipeline configuration file. For more information about XPS rendering filters, see [XPSDrv Render Module](xpsdrv-render-module.md), and to see an example of an XPS rendering filter, see the [XPS Rasterization Filter Service](http://go.microsoft.com/fwlink/p/?LinkId=617951) sample.   diff --git a/windows-driver-docs-pr/print/driver-support-for-openxps.md b/windows-driver-docs-pr/print/driver-support-for-openxps.md index f0f58d2844..4a667b6055 100644 --- a/windows-driver-docs-pr/print/driver-support-for-openxps.md +++ b/windows-driver-docs-pr/print/driver-support-for-openxps.md @@ -15,7 +15,7 @@ ms.technology: windows-devices OpenXPS is the Open XML Paper Specification format for documents, and it’s based on the Ecma International standard specification. -For the most up to date information about this specification, see [Open XML Paper Specification](http://www.ecma-international.org/publications/standards/Ecma-388.md). +For the most up to date information about this specification, see [Open XML Paper Specification](http://www.ecma-international.org/publications/standards/Ecma-388.htm). Windows 8 provides full support for OpenXPS, side-by-side with continued support for the existing Microsoft XPS format. This topic focuses on support for OpenXPS via the v4 driver model. For OpenXPS support that is relevant to Windows application developers, see [App Support for OpenXPS Printing](http://msdn.microsoft.com/library/windows/desktop/dn495653.aspx). @@ -137,7 +137,7 @@ For additional information about other options for the File Save section of the ## Related topics [App Support for OpenXPS Printing](http://msdn.microsoft.com/library/windows/desktop/dn495653.aspx) -[Open XML Paper Specification](http://www.ecma-international.org/publications/standards/Ecma-388.md) +[Open XML Paper Specification](http://www.ecma-international.org/publications/standards/Ecma-388.htm) [V4 Driver Manifest](v4-driver-manifest.md) -------------------- diff --git a/windows-driver-docs-pr/print/form-info-2-data-structure.md b/windows-driver-docs-pr/print/form-info-2-data-structure.md index f492482ec6..b958652d27 100644 --- a/windows-driver-docs-pr/print/form-info-2-data-structure.md +++ b/windows-driver-docs-pr/print/form-info-2-data-structure.md @@ -1,7 +1,7 @@ --- -title: FORM\_INFO\_2 Data Structure +title: FORM_INFO_2 Data Structure author: windows-driver-content -description: FORM\_INFO\_2 Data Structure +description: FORM_INFO_2 Data Structure ms.assetid: df953fe9-00a2-468a-a2ae-ba8f3fce9982 keywords: - FORM_INFO_2 data structure WDK printer diff --git a/windows-driver-docs-pr/print/improvements-in-xpsdrv.md b/windows-driver-docs-pr/print/improvements-in-xpsdrv.md index ef9e8b8363..3da67b5489 100644 --- a/windows-driver-docs-pr/print/improvements-in-xpsdrv.md +++ b/windows-driver-docs-pr/print/improvements-in-xpsdrv.md @@ -17,7 +17,7 @@ This topic provides information about updates that have been made to the XPSDrv **XPS Format** -The XPS Print API and/or the print filter pipeline will convert seamlessly between [Microsoft Xml Paper Specification 1.0](http://msdn.microsoft.com/windows/hardware/gg463375) (MS XPS), and [OpenXPS](http://www.ecma-international.org/publications/standards/Ecma-388.md) (ECMA-388). Unless otherwise specified, v4 print drivers default to consuming MS XPS. Using the manifest directive XpsFormat, drivers may choose to support one or both of the available XPS formats. For more information about OpenXPS support, see [OpenXPS Support in Windows](http://msdn.microsoft.com/library/windows/hardware/br259130). +The XPS Print API and/or the print filter pipeline will convert seamlessly between [Microsoft Xml Paper Specification 1.0](http://msdn.microsoft.com/windows/hardware/gg463375) (MS XPS), and [OpenXPS](http://www.ecma-international.org/publications/standards/Ecma-388.htm) (ECMA-388). Unless otherwise specified, v4 print drivers default to consuming MS XPS. Using the manifest directive XpsFormat, drivers may choose to support one or both of the available XPS formats. For more information about OpenXPS support, see [OpenXPS Support in Windows](http://msdn.microsoft.com/library/windows/hardware/br259130). **XPS Rasterization Service Improvements** @@ -42,7 +42,7 @@ The [IPrintCoreHelperUni2](https://msdn.microsoft.com/library/windows/hardware/h [IPrintCoreHelperUni2](https://msdn.microsoft.com/library/windows/hardware/hh406580) [Microsoft Xml Paper Specification 1.0](http://msdn.microsoft.com/windows/hardware/gg463375) [Native Pixel Formats Overview](http://msdn.microsoft.com/library/windows/hardware/ee719797.aspx) -[OpenXPS](http://www.ecma-international.org/publications/standards/Ecma-388.md) +[OpenXPS](http://www.ecma-international.org/publications/standards/Ecma-388.htm) [OpenXPS Support in Windows](http://msdn.microsoft.com/library/windows/hardware/br259130) [V4 Printer Driver Rendering Architecture](v4-driver-rendering-architecture.md) [**XPSRaterizationFactory1::CreateRasterizer1**](https://msdn.microsoft.com/library/windows/hardware/hh802468) diff --git a/windows-driver-docs-pr/print/standard-options.md b/windows-driver-docs-pr/print/standard-options.md index 1175a2949e..b7bbab193c 100644 --- a/windows-driver-docs-pr/print/standard-options.md +++ b/windows-driver-docs-pr/print/standard-options.md @@ -1,7 +1,6 @@ --- title: Standard Options -author: windows-driver-content -description: Standard Options +description: Standard options are associated with standard features and are identified by predefined names that the GPD language recognizes. ms.assetid: db4578c1-0954-4c51-a11a-923ab7df2b5b keywords: - printer options WDK Unidrv , standard @@ -16,328 +15,217 @@ ms.technology: windows-devices # Standard Options -## +Standard options are those that are associated with [standard features](standard-features.md). They are identified by predefined names that the GPD language recognizes. Resource identifiers for strings that represent these names are contained in stdnames.gpd, which is supplied with the Microsoft Windows Driver Kit (WDK). +**Note** This resource may not be available in some languages and countries. -Standard options are those that are associated with [standard features](standard-features.md). They are identified by predefined names that the GPD language recognizes. Resource identifiers for strings that represent these names are contained in stdnames.gpd, which is supplied with the Microsoft Windows Driver Kit \[WDK\]. (This resource may not be available in some languages and countries.) +The following table lists the standard option names that are permitted for each standard feature. Use these names as arguments to **\*Option** entries. The features that include Print Schema option keywords are option names that are automatically mapped to Print Schema option keywords. You can also map GPD options to Print Schema keywords manually by using the **PrintSchemaKeywordMap** attribute. The Print Schema is documented in the Microsoft Windows SDK. -The following table lists the standard option names that are permitted for each standard feature. Use these names as arguments to \*Option entries. The features that include Print Schema option keywords are option names that are automatically mapped to Print Schema option keywords. You can also map GPD options to Print Schema keywords manually by using the PrintSchemaKeywordMap attribute. The Print Schema is documented in the Microsoft Windows SDK. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature nameStandard option namesDefault Print Schema option keywordsCustomized options allowed?
CollateOFF
ON
Uncollated
Collated
No
ColorModeNo standard optionsYes
Also see Handling Color Formats and Controlling Image Quality.
DuplexHORIZONTAL
VERTICAL
NONE
TwoSidedShortEdge
TwoSidedLongEdge
OneSided
No
HalftoneHT_PATSIZE_2x2
HT_PATSIZE_2x2_M
HT_PATSIZE_4x4
HT_PATSIZE_4x4_M
HT_PATSIZE_6x6
HT_PATSIZE_6x6_M
HT_PATSIZE_8x8
HT_PATSIZE_8x8_M
HT_PATSIZE_10x10
HT_PATSIZE_10x10_M
HT_PATSIZE_12x12
HT_PATSIZE_12x12_M
HT_PATSIZE_14x14
HT_PATSIZE_14x14_M
HT_PATSIZE_16x16
HT_PATSIZE_16x16_M
HT_PATSIZE_SUPERCELL
HT_PATSIZE_SUPERCELL_M
HT_PATSIZE_AUTO
Yes
Also see Halftoning with Unidrv.
InputBinAUTO
CASSETTE
ENVFEED
ENVMANUAL
CassetteYes
FORMSOURCEAutoSelect
LARGECAPACITY
LARGEFMT
LOWER
High
MANUAL
MIDDLE
SMALLFMT
Manual
TRACTOR
UPPER
Tractor
MediaTypeGLOSSY
STANDARD
TRANSPARENCY
PhotographicGlossy
Plain
Transparency
Yes
Also see Controlling Image Quality.
MemoryNo standard optionsYes
OrientationPORTRAIT
LANDSCAPE_CC90
LANDSCAPE_CC270

For more information about the latter two options, see Specifying Paper Orientation.
Portrait
Landscape
ReverseLandscape
No
PageProtectON
OFF
No
PaperSize10X11
10X14
11X17
NorthAmerica10x11
NorthAmerica10x14
NorthAmerica11x17
Yes
Note Customized names must not exceed the length specified by CCHFORMNAME in wingdi.h.
12X11
15X11
9X11
A_PLUS
NorthAmerica9x11
NorthAmericaSuperA
A2
A3
ISOA2
ISOA3
A3_EXTRA
A3_EXTRA_TRANSVERSE
ISOA3Extra
A3_ROTATED
A3_TRANSVERSE
ISOA3Rotated
A4
A4_EXTRA
A4_PLUS
ISOA4
ISOA4Extra
OtherMetricA4Plus
A4_ROTATED
A4_TRANSVERSE
ISOA4Rotated
A4SMALL
A5
A5_EXTRA
ISOA5
ISOA5Extra
A5_ROTATED
A5_TRANSVERSE
ISOA5Rotated
A6
A6_ROTATED
B_PLUS
B4
B4_JIS_ROTATED
B5
B5_EXTRA
ISOA6
ISOA6Rotated
NorthAmericaSuperB
JISB4
JISB4Rotated
JISB5
ISOB5Extra
B5_JIS_ROTATED
B5_TRANSVERSE
JISB5Rotated
B6_JIS
B6_JIS_ROTATED
JISB6
JISB6Rotated
CSHEET
CUSTOMSIZE
NorthAmericaCSheet
DBL_JAPANESE_POSTCARD
DBL_JAPANESE_POSTCARD_ROTATED
DSHEET
ENV_10
ENV_11
ENV_12
ENV_14
ENV_9
ENV_B4
ENV_B5
JapanDoubleHagakiPostcard
JapanDoubleHagakiPostcardRotated
NorthAmericaDSheet
NorthAmericaNumber10Envelope
NorthAmericaNumber11Envelope
NorthAmericaNumber12Envelope
NorthAmericaNumber14Envelope
NorthAmericaNumber9Envelope
ISOB4Envelope
ISOB5Envelope
ENV_B6
ENV_C3
ENV_C4
ENV_C5
ENV_C6
ENV_C65
ENV_DL
ENV_INVITE
ENV_ITALY
ENV_MONARCH
ENV_PERSONAL
ESHEET
EXECUTIVE
FANFOLD_LGL_GERMAN
ISOC3Envelope
ISOC4Envelope
ISOC5Envelope
ISOC6Envelope
ISOC6C5Envelope
ISODLEnvelope
OtherMetricInviteEnvelope
OtherMetricItalianEnvelope
NorthAmericaMonarchEnvelope
NorthAmericaPersonalEnvelope
NorthAmericaESheet
NorthAmericaExecutive
NorthAmericaGermanLegalFanfold
FANFOLD_STD_GERMAN
FANFOLD_US
NorthAmericaGermanStandardFanfold
FOLIO
ISO_B4
JAPANESE_POSTCARD
JAPANESE_POSTCARD_ROTATED
JENV_CHOU3
JENV_CHOU3_ROTATED
JENV_CHOU4
JENV_CHOU4_ROTATED
JENV_KAKU2
JENV_KAKU2_ROTATED
JENV_KAKU3
JENV_KAKU3_ROTATED
JENV_YOU4
JENV_YOU4_ROTATED
OtherMetricFolio
ISOB4
JapanHagakiPostcard
JapanHagakiPostcardRotated
JapanChou3Envelope
JapanChou3EnvelopeRotated
JapanChou4Envelope
JapanChou4EnvelopeRotated
JapanKaku2Envelope
JapanKaku2EnvelopeRotated
JapanKaku3Envelope
JapanKaku3EnvelopeRotated
JapanYou4Envelope
JapanYou4EnvelopeRotated
LEDGER
LEGAL
LEGAL_EXTRA
LETTER
NorthAmericaLegal
NorthAmericaLegalExtra
NorthAmericaLetter
LETTER_EXTRA
LETTER_EXTRA_TRANSVERSE
NorthAmericaLetterExtra
LETTER_PLUSNorthAmericaLetterPlus
LETTER_ROTATED
LETTER_TRANSVERSE
NorthAmericaLetterRotated
LETTERSMALL
NOTE
P16K
P16K_ROTATED
P32K
P32K_ROTATED
NorthAmericaNote
PRC16K
PRC16KRotated
PRC32K
PRC32KRotated
P32KBIG
P32KBIG_ROTATED
PRC32KBig
PENV_1
PENV_1_ROTATED
PENV_10
PENV_10_ROTATED
PENV_2
PENV_2_ROTATED
PENV_3
PENV_3_ROTATED
PENV_4
PENV_4_ROTATED
PENV_5
PENV_5_ROTATED
PENV_6
PENV_6_ROTATED
PENV_7
PENV_7_ROTATED
PENV_8
PENV_8_ROTATED
PENV_9
PENV_9_ROTATED
QUARTO
STATEMENT
TABLOID
TABLOID_EXTRA
PRC1Envelope
PRC1EnvelopeRotated
PRC10Envelope
PRC10EnvelopeRotated
PRC2Envelope
PRC2EnvelopeRotated
PRC3Envelope
PRC3EnvelopeRotated
PRC4Envelope
PRC4EnvelopeRotated
PRC5Envelope
PRC5EnvelopeRotated
PRC6Envelope
PRC6EnvelopeRotated
PRC7Envelope
PRC7EnvelopeRotated
PRC8Envelope
PRC8EnvelopeRotated
PRC9Envelope
PRC9EnvelopeRotated
NorthAmericaQuarto
NorthAmericaStatement
NorthAmericaTabloid
NorthAmericaTabloidExtra
ResolutionNo standard optionsYes
-Feature name -Standard option names -Default Print Schema option keywords -Customized options allowed? -**Collate** -OFF -ON -Uncollated -Collated -No -**ColorMode** -No standard options. -Yes. Also see [Handling Color Formats](handling-color-formats.md) and [Controlling Image Quality](controlling-image-quality.md). -**Duplex** -HORIZONTAL -VERTICAL -NONE -TwoSidedShortEdge -TwoSidedLongEdge -OneSided -No -**Halftone** -HT\_PATSIZE\_2x2 -HT\_PATSIZE\_2x2\_M -HT\_PATSIZE\_4x4 -HT\_PATSIZE\_4x4\_M -HT\_PATSIZE\_6x6 -HT\_PATSIZE\_6x6\_M -HT\_PATSIZE\_8x8 -HT\_PATSIZE\_8x8\_M -HT\_PATSIZE\_10x10 -HT\_PATSIZE\_10x10\_M -HT\_PATSIZE\_12x12 -HT\_PATSIZE\_12x12\_M -HT\_PATSIZE\_14x14 -HT\_PATSIZE\_14x14\_M -HT\_PATSIZE\_16x16 -HT\_PATSIZE\_16x16\_M -HT\_PATSIZE\_SUPERCELL -HT\_PATSIZE\_SUPERCELL\_M -HT\_PATSIZE\_AUTO -Yes. Also see [Halftoning with Unidrv](halftoning-with-unidrv.md). -**InputBin** -AUTO -CASSETTE -ENVFEED -ENVMANUAL -Cassette -Yes -FORMSOURCE -AutoSelect -LARGECAPACITY -LARGEFMT -LOWER -High -MANUAL -MIDDLE -SMALLFMT -Manual -TRACTOR -UPPER -Tractor -**MediaType** -GLOSSY -STANDARD -TRANSPARENCY -PhotographicGlossy -Plain -Transparency -Yes. Also see [Controlling Image Quality](controlling-image-quality.md). -**Memory** -No standard options. -Yes -**Orientation** -PORTRAIT -LANDSCAPE\_CC90 -LANDSCAPE\_CC270 -(For more information about the latter two options, see [Specifying Paper Orientation](specifying-paper-orientation.md).) -Portrait -Landscape -ReverseLandscape -No -**PageProtect** -ON, OFF -No -10X11 -10X14 -11X17 -NorthAmerica10x11 -NorthAmerica10x14 -NorthAmerica11x17 -**PaperSize** -12X11 -15X11 -Yes. Customized names must not exceed the length specified by CCHFORMNAME in *wingdi.h*. -9X11 -A\_PLUS -NorthAmerica9x11 -NorthAmericaSuperA -A2 -A3 -ISOA2 -ISOA3 -A3\_EXTRA -A3\_EXTRA\_TRANSVERSE -ISOA3Extra -A3\_ROTATED -A3\_TRANSVERSE -ISOA3Rotated -A4 -A4\_EXTRA -A4\_PLUS -ISOA4 -ISOA4Extra -OtherMetricA4Plus -A4\_ROTATED -A4\_TRANSVERSE -ISOA4Rotated -A4SMALL -A5 -A5\_EXTRA -ISOA5 -ISOA5Extra -A5\_ROTATED -A5\_TRANSVERSE -ISOA5Rotated -A6 -A6\_ROTATED -B\_PLUS -B4 -B4\_JIS\_ROTATED -B5 -B5\_EXTRA -ISOA6 -ISOA6Rotated -NorthAmericaSuperB -JISB4 -JISB4Rotated -JISB5 -ISOB5Extra -B5\_JIS\_ROTATED -B5\_TRANSVERSE -JISB5Rotated -B6\_JIS -B6\_JIS\_ROTATED -JISB6 -JISB6Rotated -CSHEET -CUSTOMSIZE -NorthAmericaCSheet -DBL\_JAPANESE\_POSTCARD -DBL\_JAPANESE\_POSTCARD\_ROTATED -DSHEET -ENV\_10 -ENV\_11 -ENV\_12 -ENV\_14 -ENV\_9 -ENV\_B4 -ENV\_B5 -JapanDoubleHagakiPostcard -JapanDoubleHagakiPostcardRotated -NorthAmericaDSheet -NorthAmericaNumber10Envelope -NorthAmericaNumber11Envelope -NorthAmericaNumber12Envelope -NorthAmericaNumber14Envelope -NorthAmericaNumber9Envelope -ISOB4Envelope -ISOB5Envelope -ENV\_B6 -ENV\_C3 -ENV\_C4 -ENV\_C5 -ENV\_C6 -ENV\_C65 -ENV\_DL -ENV\_INVITE -ENV\_ITALY -ENV\_MONARCH -ENV\_PERSONAL -ESHEET -EXECUTIVE -FANFOLD\_LGL\_GERMAN -ISOC3Envelope -ISOC4Envelope -ISOC5Envelope -ISOC6Envelope -ISOC6C5Envelope -ISODLEnvelope -OtherMetricInviteEnvelope -OtherMetricItalianEnvelope -NorthAmericaMonarchEnvelope -NorthAmericaPersonalEnvelope -NorthAmericaESheet -NorthAmericaExecutive -NorthAmericaGermanLegalFanfold -FANFOLD\_STD\_GERMAN -FANFOLD\_US -NorthAmericaGermanStandardFanfold -FOLIO -ISO\_B4 -JAPANESE\_POSTCARD -JAPANESE\_POSTCARD\_ROTATED -JENV\_CHOU3 -JENV\_CHOU3\_ROTATED -JENV\_CHOU4 -JENV\_CHOU4\_ROTATED -JENV\_KAKU2 -JENV\_KAKU2\_ROTATED -JENV\_KAKU3 -JENV\_KAKU3\_ROTATED -JENV\_YOU4 -JENV\_YOU4\_ROTATED -OtherMetricFolio -ISOB4 -JapanHagakiPostcard -JapanHagakiPostcardRotated -JapanChou3Envelope -JapanChou3EnvelopeRotated -JapanChou4Envelope -JapanChou4EnvelopeRotated -JapanKaku2Envelope -JapanKaku2EnvelopeRotated -JapanKaku3Envelope -JapanKaku3EnvelopeRotated -JapanYou4Envelope -JapanYou4EnvelopeRotated -LEDGER -LEGAL -LEGAL\_EXTRA -LETTER -NorthAmericaLegal -NorthAmericaLegalExtra -NorthAmericaLetter -LETTER\_EXTRA -LETTER\_EXTRA\_TRANSVERSE -NorthAmericaLetterExtra -LETTER\_PLUS -NorthAmericaLetterPlus -LETTER\_ROTATED -LETTER\_TRANSVERSE -NorthAmericaLetterRotated -LETTERSMALL -NOTE -P16K -P16K\_ROTATED -P32K -P32K\_ROTATED -NorthAmericaNote -PRC16K -PRC16KRotated -PRC32K -PRC32KRotated -P32KBIG -P32KBIG\_ROTATED -PRC32KBig -PENV\_1 -PENV\_1\_ROTATED -PENV\_10 -PENV\_10\_ROTATED -PENV\_2 -PENV\_2\_ROTATED -PENV\_3 -PENV\_3\_ROTATED -PENV\_4 -PENV\_4\_ROTATED -PENV\_5 -PENV\_5\_ROTATED -PENV\_6 -PENV\_6\_ROTATED -PENV\_7 -PENV\_7\_ROTATED -PENV\_8 -PENV\_8\_ROTATED -PENV\_9 -PENV\_9\_ROTATED -QUARTO -STATEMENT -TABLOID -TABLOID\_EXTRA -PRC1Envelope -PRC1EnvelopeRotated -PRC10Envelope -PRC10EnvelopeRotated -PRC2Envelope -PRC2EnvelopeRotated -PRC3Envelope -PRC3EnvelopeRotated -PRC4Envelope -PRC4EnvelopeRotated -PRC5Envelope -PRC5EnvelopeRotated -PRC6Envelope -PRC6EnvelopeRotated -PRC7Envelope -PRC7EnvelopeRotated -PRC8Envelope -PRC8EnvelopeRotated -PRC9Envelope -PRC9EnvelopeRotated -NorthAmericaQuarto -NorthAmericaStatement -NorthAmericaTabloid -NorthAmericaTabloidExtra -**Resolution** -No standard options. -Yes. -  ## Related topics + + [Controlling Image Quality](controlling-image-quality.md) [Halftoning with Unidrv](halftoning-with-unidrv.md) [Specifying Paper Orientation](specifying-paper-orientation.md) -[standard features](standard-features.md) +[Standard features](standard-features.md) + + -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20Standard%20Options%20%20RELEASE:%20%289/1/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/print/v4-driver-setup-concepts.md b/windows-driver-docs-pr/print/v4-driver-setup-concepts.md index d11e964b98..8d8157cbbc 100644 --- a/windows-driver-docs-pr/print/v4-driver-setup-concepts.md +++ b/windows-driver-docs-pr/print/v4-driver-setup-concepts.md @@ -109,7 +109,7 @@ i. If both are specified, Windows will concatenate them into "MANUFACTURER MODEL ii. If only one of these fails, Windows will use the value from the other key as the queue name. -**The Add Printer Wizard**. The driver name will continue to be the only identifier available to users choosing a driver in the **Add Printer Wizard**. TCP/IP-based devices should implement the [Port Monitor MIB (PWG 5107.1-2005)](http://www.pwg.org/standards.mdl) to support TCP/IP auto-detection. Existing devices that are added to a print class driver using a hardware ID (HWID) mapping may additionally use a device-specific model name. +**The Add Printer Wizard**. The driver name will continue to be the only identifier available to users choosing a driver in the **Add Printer Wizard**. TCP/IP-based devices should implement the [Port Monitor MIB (PWG 5107.1-2005)](http://www.pwg.org/standards.html) to support TCP/IP auto-detection. Existing devices that are added to a print class driver using a hardware ID (HWID) mapping may additionally use a device-specific model name. ## Changing Ports and Dealing with Printer Devnodes @@ -182,7 +182,7 @@ c. CompatibleID lines: "Print Class Driver name" = INSTALL\_SECTION,,1284\_CID\_ ## Related topics [How to Implement Compatible IDs in Printing Devices](http://msdn.microsoft.com/library/windows/hardware/gg463313.aspx) [How Windows Ranks Drivers](http://msdn.microsoft.com/library/windows/hardware/ff546225.aspx) -[Port Monitor MIB (PWG 5107.1-2005)](http://www.pwg.org/standards.mdl) +[Port Monitor MIB (PWG 5107.1-2005)](http://www.pwg.org/standards.html) -------------------- [Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20V4%20Driver%20Setup%20Concepts%20%20RELEASE:%20%289/1/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") diff --git a/windows-driver-docs-pr/sensors/about-the-parameter-types.md b/windows-driver-docs-pr/sensors/about-the-parameter-types.md index 1cc9a6451a..2cfd53a488 100644 --- a/windows-driver-docs-pr/sensors/about-the-parameter-types.md +++ b/windows-driver-docs-pr/sensors/about-the-parameter-types.md @@ -32,7 +32,7 @@ You should understand how the sensor class extension uses some data types as met

[IWDFFile](https://msdn.microsoft.com/library/windows/hardware/ff558912)

pClientFile

-

This UMDF COM interface represents a file object that the platform associates with a client application. Although sensor method calls always supply this type as a valid interface pointer, it is intended to be used as an ID for the application. The address that the pointer contains is a unique number that can identify the client application. Be aware that this value is distinct from the address of the pointer itself. Do not use the address-of operator (&) to retrieve an ID. Use the pointer itself.

+

This UMDF COM interface represents a file object that the platform associates with a client application. Although sensor method calls always supply this type as a valid interface pointer, it is intended to be used as an ID for the application. The address that the pointer contains is a unique number that can identify the client application. Be aware that this value is distinct from the address of the pointer itself. Do not use the address-of operator (&) to retrieve an ID. Use the pointer itself.

If you choose to use this pointer to access the underlying object, remember to call AddRef through the pointer initially, and to call Release when you have finished.

diff --git a/windows-driver-docs-pr/sensors/architecture-overview-for-sensor-drivers.md b/windows-driver-docs-pr/sensors/architecture-overview-for-sensor-drivers.md index ddff098607..2bb207486f 100644 --- a/windows-driver-docs-pr/sensors/architecture-overview-for-sensor-drivers.md +++ b/windows-driver-docs-pr/sensors/architecture-overview-for-sensor-drivers.md @@ -21,13 +21,13 @@ A sensor driver uses a special **class extension** object. The sensor class exte For more information about the class extension object, see [About the Sensor Class Extension](about-the-sensor-class-extension.md). -**Important**Sensor drivers must be free threaded and thread safe. +**Important** Sensor drivers must be free threaded and thread safe. - + - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/connect-to-hardware.md b/windows-driver-docs-pr/sensors/connect-to-hardware.md index a646c3386e..045bd601e6 100644 --- a/windows-driver-docs-pr/sensors/connect-to-hardware.md +++ b/windows-driver-docs-pr/sensors/connect-to-hardware.md @@ -26,7 +26,7 @@ These code snippets highlight some of the important sections of the sensor drive ```ManagedCPlusPlus // Create WDFOBJECT for the sensor WDF_OBJECT_ATTRIBUTES sensorAttributes; - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&sensorAttributes, ADXL345AccDevice); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&sensorAttributes, ADXL345AccDevice); ``` The preceding code creates a sensor object and assigns the appropriate device context to it. @@ -35,7 +35,7 @@ The preceding code creates a sensor object and assigns the appropriate device co ```ManagedCPlusPlus // Register sensor instance with clx SENSOROBJECT SensorInstance = NULL; - NTSTATUS Status = SensorsCxSensorCreate(Device, &sensorAttributes, &SensorInstance); + NTSTATUS Status = SensorsCxSensorCreate(Device, &sensorAttributes, &SensorInstance); ``` The preceding code registers the sensor instance with the sensor class extension. A sensor instance is created instead of a device instance, to allow for the scenario where you have multiple sensors within the same chip. @@ -44,9 +44,9 @@ The preceding code registers the sensor instance with the sensor class extension ```ManagedCPlusPlus // Initialize sensor instance with clx SENSOR_CONFIG SensorConfig; - SENSOR_CONFIG_INIT(&SensorConfig); + SENSOR_CONFIG_INIT(&SensorConfig); SensorConfig.pEnumerationList = pAccDevice->m_pEnumerationProperties; - Status = SensorsCxSensorInitialize(SensorInstance, &SensorConfig); + Status = SensorsCxSensorInitialize(SensorInstance, &SensorConfig); ``` The preceding code uses the sensor class extension to initialize the sensor instance. @@ -77,7 +77,7 @@ The preceding code is used to acquire a lock for the I2C bus. For (DWORD i = 0; i < ARRAYSIZE(g_ConfigurationSettings); i++) { REGISTER_SETTING setting = g_ConfigurationSettings[i]; - Status = I2CSensorWriteRegister(m_I2CIoTarget, setting.Register, &setting.Value, sizeof(setting.Value)); + Status = I2CSensorWriteRegister(m_I2CIoTarget, setting.Register, &setting.Value, sizeof(setting.Value)); if (!NT_SUCCESS(Status)) { TraceError("ACC %!FUNC! I2CSensorReadRegister from 0x%02x failed! %!STATUS!", setting.Register, Status); @@ -95,7 +95,7 @@ The For-loop is used to write the default configuration settings to the device r // Release the I2C bus lock WdfWaitLockRelease(pAccDevice->m_I2CWaitLock); - InitPropVariantFromUInt32(SensorState_Idle, &(m_pSensorProperties->List[SENSOR_PROPERTY_STATE].Value)); + InitPropVariantFromUInt32(SensorState_Idle, &(m_pSensorProperties->List[SENSOR_PROPERTY_STATE].Value)); m_PoweredOn = true; ``` @@ -115,16 +115,16 @@ WdfWaitLockAcquire(pAccDevice->m_I2CWaitLock, NULL); ```ManagedCPlusPlus // Set accelerometer to measurement mode REGISTER_SETTING RegisterSetting = { ADXL345_POWER_CTL, ADXL345_POWER_CTL_MEASURE }; - Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); + Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); ``` -In the preceding code, the I2C connection is used to set the accelerometer to measure mode to make it ready for reading sensor values. See the *adxl345.h* header file for the definitions of ADXL345\_POWER\_CTL, ADXL345\_POWER\_CTL\_MEASURE and some other constants used in the sample sensor driver. +In the preceding code, the I2C connection is used to set the accelerometer to *measure mode* to make it ready for reading sensor values. See the *adxl345.h* header file for the definitions of ADXL345\_POWER\_CTL, ADXL345\_POWER\_CTL\_MEASURE and some other constants used in the sample sensor driver. 4. Find the following code: ```ManagedCPlusPlus // Enable interrupts RegisterSetting = { ADXL345_INT_ENABLE, ADXL345_INT_ACTIVITY }; - Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); + Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); WdfWaitLockRelease(pAccDevice->m_I2CWaitLock); ``` @@ -138,7 +138,7 @@ The *RegisterSetting* parameter enables interrupts for the sensor. WdfWaitLockRe // Disable interrupts REGISTER_SETTING RegisterSetting = { ADXL345_INT_ENABLE, 0 }; WdfWaitLockAcquire(pAccDevice->m_I2CWaitLock, NULL); - Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); + Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); ``` In the preceding code, the *RegisterSetting* parameter captures a register address and configuration code. In this case RegisterSetting.Register is the address of an interrupt enable register, while RegisterSetting.Value configures the register to stop the device from issuing interrupts. @@ -147,14 +147,14 @@ In the preceding code, the *RegisterSetting* parameter captures a register addre ```ManagedCPlusPlus // Clear any stale interrupts RegisterSetting = { ADXL345_INT_SOURCE, 0 }; - Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); + Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); ``` 3. Find the following code, which sets the device to standby mode. This setting stops the device activity: ```ManagedCPlusPlus // Set accelerometer to standby RegisterSetting = { ADXL345_POWER_CTL, ADXL345_POWER_CTL_STANDBY }; - Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); + Status = I2CSensorWriteRegister(pAccDevice->m_I2CIoTarget, RegisterSetting.Register, &RegisterSetting.Value, sizeof(RegisterSetting.Value)); ``` ## Disconnect hardware resources @@ -178,9 +178,9 @@ The preceding code is used to delete the wait lock on the device object. ``` 3. Close the *client.cpp* file. - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/creating-a-persistent-unique-identifier.md b/windows-driver-docs-pr/sensors/creating-a-persistent-unique-identifier.md index dc510c8a17..516569a26b 100644 --- a/windows-driver-docs-pr/sensors/creating-a-persistent-unique-identifier.md +++ b/windows-driver-docs-pr/sensors/creating-a-persistent-unique-identifier.md @@ -36,7 +36,7 @@ HRESULT CMyDevice::GetUniqueID(__in IWDFDevice* pWdfDevice, { // Create the property store for this device or // retrieve the existing one. - hr = pWdfDevice->RetrieveDevicePropertyStore(NULL, WdfPropertyStoreCreateIfMissing, &spPropStore, NULL); + hr = pWdfDevice->RetrieveDevicePropertyStore(NULL, WdfPropertyStoreCreateIfMissing, &spPropStore, NULL); } if(SUCCEEDED(hr)) @@ -46,30 +46,30 @@ HRESULT CMyDevice::GetUniqueID(__in IWDFDevice* pWdfDevice, PROPVARIANT vID; // Try to get the PUID value previously stored as a string. - hr = spPropStore->GetNamedValue(wszSensorID, &vID); + hr = spPropStore->GetNamedValue(wszSensorID, &vID); if (SUCCEEDED(hr)) { // Convert the PUID string to a GUID. - hr = ::CLSIDFromString(vID.bstrVal, &idGuid); + hr = ::CLSIDFromString(vID.bstrVal, &idGuid); } else { // There was no value in the store, so create a new value. - hr = ::CoCreateGuid(&idGuid); + hr = ::CoCreateGuid(&idGuid); if (SUCCEEDED(hr)) { // Convert the GUID to a string. LPOLESTR lpszGUID = NULL; - hr = ::StringFromCLSID(idGuid, &lpszGUID); + hr = ::StringFromCLSID(idGuid, &lpszGUID); if (SUCCEEDED(hr)) { // Put the new value into the property store. - PropVariantInit(&vID); + PropVariantInit(&vID); vID.vt = VT_LPWSTR; vID.pwszVal = lpszGUID; - hr = spPropStore->SetNamedValue(wszSensorID, &vID); - PropVariantClear(&vID); + hr = spPropStore->SetNamedValue(wszSensorID, &vID); + PropVariantClear(&vID); } } } diff --git a/windows-driver-docs-pr/sensors/driver-interface-methods.md b/windows-driver-docs-pr/sensors/driver-interface-methods.md index aef9e92492..0325a873cf 100644 --- a/windows-driver-docs-pr/sensors/driver-interface-methods.md +++ b/windows-driver-docs-pr/sensors/driver-interface-methods.md @@ -277,7 +277,7 @@ DDIOnGetProperties(sensorID, CRI, CS[], LDA) ```ManagedCPlusPlus DDIOnGetDatafields(sensorID, datafields[]) { - if (((false == flagCRI) && (0 == subscriberCount)) || (false == initalDataReceived)) + if (((false == flagCRI) && (0 == subscriberCount)) || (false == initalDataReceived)) { //poll sensorID device for data DriverUpdateDatafields(sensorID) diff --git a/windows-driver-docs-pr/sensors/how-to-build-a-universal-sensor-driver.md b/windows-driver-docs-pr/sensors/how-to-build-a-universal-sensor-driver.md index c7c888cb50..d28a8098c8 100644 --- a/windows-driver-docs-pr/sensors/how-to-build-a-universal-sensor-driver.md +++ b/windows-driver-docs-pr/sensors/how-to-build-a-universal-sensor-driver.md @@ -1,7 +1,7 @@ --- title: How to build a universal sensor driver author: windows-driver-content -description: A universal sensor driver is a sensor driver that is developed based on the universal sensor driver model for Windows10. +description: A universal sensor driver is a sensor driver that is developed based on the universal sensor driver model for Windows 10. ms.assetid: 759E01CA-9838-4CBF-B5D1-2DCD2230A48A ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -13,7 +13,7 @@ ms.technology: windows-devices # How to build a universal sensor driver -A *universal sensor driver* is a sensor driver that is developed based on the universal sensor driver model for Windows10. And the topics in this section show you how to build such a sensor driver. +A *universal sensor driver* is a sensor driver that is developed based on the universal sensor driver model for Windows 10. And the topics in this section show you how to build such a sensor driver. This universal sensor driver development exercise is based on a development board called [Sharks Cove]( http://firmware.intel.com/projects/sharks-cove-uefi-firmware). @@ -25,9 +25,9 @@ The following topics provide detailed guidance for the tasks that you need to pe - [Write and deploy your universal sensor driver](write-and-deploy-your-universal-sensor-driver.md) - [Test your universal sensor driver](test-your-universal-sensor-driver.md) - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/install-the-sensor-driver.md b/windows-driver-docs-pr/sensors/install-the-sensor-driver.md index 90a4ebc562..5639e046c5 100644 --- a/windows-driver-docs-pr/sensors/install-the-sensor-driver.md +++ b/windows-driver-docs-pr/sensors/install-the-sensor-driver.md @@ -15,13 +15,13 @@ ms.technology: windows-devices This topic shows you how to install the sensor driver on a development board, after you update the secondary system description table (SSDT) for the development board. -This topic uses the Sharks Cove development board and an ADXL345 accelerometer as a case study, to help explain the process of installing a sensor driver on a development board. So if you want to perform the tasks presented in this topic, you must first install an operating system on the Sharks Cove. For more information about how to do that, see [Download kits and tools for Windows10](https://msdn.microsoft.com/windows/hardware/dn913721.aspx), and follow the instructions in **Step 1** (Install Windows10). +This topic uses the Sharks Cove development board and an ADXL345 accelerometer as a case study, to help explain the process of installing a sensor driver on a development board. So if you want to perform the tasks presented in this topic, you must first install an operating system on the Sharks Cove. For more information about how to do that, see [Download kits and tools for Windows 10](https://msdn.microsoft.com/windows/hardware/dn913721.aspx), and follow the instructions in **Step 1** (Install Windows 10). After you finish installing the operating system on the Sharks Cove, See [Build the sensor driver](build-the-sensor-driver.md) to learn how to build a driver in Microsoft Visual Studio. Then return here to continue. The accelerometer is attached to the Sharks Cove via the I2C bus. Peripherals that are connected to the I2C bus are enumerated via the Advanced Configuration and Power Interface (ACPI). So the sample driver for the accelerometer was developed to support ACPI instead of Plug and Play. -To make the Sharks Coves ACPI driver aware of the new device (the accelerometer) on the I2C bus, you must add information about the accelerometer to the SSDT on the Sharks Cove. This table describes the hardware resources and interrupt requirements for a hardware platforms devices, including attached peripherals like the accelerometer. +To make the Sharks Cove's ACPI driver aware of the new device (the accelerometer) on the I2C bus, you must add information about the accelerometer to the SSDT on the Sharks Cove. This table describes the hardware resources and interrupt requirements for a hardware platform's devices, including attached peripherals like the accelerometer. ## Before you begin @@ -177,12 +177,13 @@ Before you install the sample sensor driver, you must turn on testsigning. Perfo 1. In the Command prompt window, enter the following command to see whether testsigning is already turned on. **bcdedit /enum** -2. If you see a listing similar to the following, showing an entry for testsigning, with its value set to yes then skip to **Step 5**. +2. If you see a listing similar to the following, showing an entry for testsigning, with its value set to `yes` then skip to **Step 5**. ![command prompt window showing testsigning set to yes.](images/testsigning.png) 3. If you need to turn on test signing, then enter the following command: **bcdedit /set testsigning on** -4. Repeat **Step 1** (in this exercise) to verify that the value of the testsigning system variable is now set to yes in the Windows Boot Loader list. + +4. Repeat **Step 1** (in this exercise) to verify that the value of the testsigning system variable is now set to 'yes' in the Windows Boot Loader list. 5. Restart the Sharks Cove. As the board restarts, hold the Volume-up button for about 2 seconds, to enter system setup (UEFI) window. @@ -224,9 +225,9 @@ For information about how to use Visual Studio to deploy a driver to a client co After successfully installing the sample sensor driver, see [Test your universal sensor driver](test-your-universal-sensor-driver.md) for information about how to test a sensor. - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/make-the-driver-loadable.md b/windows-driver-docs-pr/sensors/make-the-driver-loadable.md index 0255165930..65ed1c2364 100644 --- a/windows-driver-docs-pr/sensors/make-the-driver-loadable.md +++ b/windows-driver-docs-pr/sensors/make-the-driver-loadable.md @@ -32,12 +32,12 @@ This code configures logging for the driver. 3. Find the WDF\_DRIVER\_CONFIG\_INIT statement. The WDF\_DRIVER\_CONFIG\_INIT function is called to set the **DeviceAdd** callback. ```ManagedCPlusPlus -WDF_DRIVER_CONFIG_INIT(&DriverConfig, ADXL345AccDevice::OnDeviceAdd); +WDF_DRIVER_CONFIG_INIT(&DriverConfig, ADXL345AccDevice::OnDeviceAdd); ``` 4. Find the code block that starts with NTSTATUS Status = WdfDriverCreate. ```ManagedCPlusPlus -NTSTATUS Status = WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &DriverConfig, WDF_NO_HANDLE); +NTSTATUS Status = WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, &DriverConfig, WDF_NO_HANDLE); ``` The WdfDriverCreate function is used to initialize the driver object. @@ -51,7 +51,7 @@ The WdfDriverCreate function is used to initialize the driver object. ```ManagedCPlusPlus // Create WDFOBJECT for the sensor WDF_OBJECT_ATTRIBUTES attributes; - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(WDFDRIVER Driver, &attributes, ADXL345AccDevice); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(WDFDRIVER Driver, &attributes, ADXL345AccDevice); ``` This code sets up a context structure of type ADXL345AccDevice for the device object. @@ -59,7 +59,7 @@ This code sets up a context structure of type ADXL345AccDevice for the device ob 3. Find the following code: ```ManagedCPlusPlus // Call the framework to create the device -NTSTATUS Status = WdfDeviceCreate(&pAccDeviceInit, &FdoAttributes, &Device); +NTSTATUS Status = WdfDeviceCreate(&pAccDeviceInit, &FdoAttributes, &Device); ``` This function is used to create a WDFDEVICE object. WDF creates the device object, and then allocates an ADXL345 accelerometer context to it. diff --git a/windows-driver-docs-pr/sensors/raising-events.md b/windows-driver-docs-pr/sensors/raising-events.md index 9a9446cbb6..d1aa427c20 100644 --- a/windows-driver-docs-pr/sensors/raising-events.md +++ b/windows-driver-docs-pr/sensors/raising-events.md @@ -105,7 +105,7 @@ HRESULT CSampleEvents::Initialize(ISensorClassExtension *pSensorCXT, CSensorDdi* { m_hEventThread = ::CreateThread(NULL, // Cannot be inherited by child process 0, // Default stack size - &CSampleEvents::_EventThreadProc, // Thread proc + &CSampleEvents::_EventThreadProc, // Thread proc (LPVOID)this, // Thread proc argument 0, // Starting state = running NULL); // No thread identifier @@ -157,7 +157,7 @@ HRESULT CSampleEvents::PostStateEvent() if (SUCCEEDED(hr)) { SensorState st; - hr = m_pDdi->GetSensorState(&st); + hr = m_pDdi->GetSensorState(&st); if (SUCCEEDED(hr)) { @@ -225,7 +225,7 @@ DWORD WINAPI CSampleEvents::_EventThreadProc(__in LPVOID pvData) if(SUCCEEDED(hr)) { // Use the Ddi class to create the key collection. - hr = pThis->m_pDdi->OnGetSupportedDataFields(g_wszSensorID, &spKeys); + hr = pThis->m_pDdi->OnGetSupportedDataFields(g_wszSensorID, &spKeys); } if(SUCCEEDED(hr)) @@ -239,7 +239,7 @@ DWORD WINAPI CSampleEvents::_EventThreadProc(__in LPVOID pvData) // This sample does not do so, therefore this is a safe thing to do // in this code. hr = pThis->m_pDdi->OnGetDataFields(spTemp, g_wszSensorID, spKeys, - &spEventParams); + &spEventParams); } if(SUCCEEDED(hr)) diff --git a/windows-driver-docs-pr/sensors/read-data-from-hardware.md b/windows-driver-docs-pr/sensors/read-data-from-hardware.md index 0a2fbac955..ef8411e48e 100644 --- a/windows-driver-docs-pr/sensors/read-data-from-hardware.md +++ b/windows-driver-docs-pr/sensors/read-data-from-hardware.md @@ -26,7 +26,7 @@ Typically the “top end” of the sensor driver is designed to be accessible to // Read the Interrupt source BYTE IntSrcBuffer = 0; WdfWaitLockAcquire(pAccDevice->m_I2CWaitLock, NULL); - Status = I2CSensorReadRegister(pAccDevice->m_I2CIoTarget, ADXL345_INT_SOURCE, &IntSrcBuffer, sizeof(IntSrcBuffer)); + Status = I2CSensorReadRegister(pAccDevice->m_I2CIoTarget, ADXL345_INT_SOURCE, &IntSrcBuffer, sizeof(IntSrcBuffer)); WdfWaitLockRelease(pAccDevice->m_I2CWaitLock); ``` @@ -61,7 +61,7 @@ The sample sensor driver uses **GetData** to retrieve the sensor instance, acqui // Read the device data BYTE DataBuffer[ADXL345_DATA_REPORT_SIZE_BYTES]; WdfWaitLockAcquire(m_I2CWaitLock, NULL); - Status = I2CSensorReadRegister(m_I2CIoTarget, ADXL345_DATA_X0, &DataBuffer[0], sizeof(DataBuffer)); + Status = I2CSensorReadRegister(m_I2CIoTarget, ADXL345_DATA_X0, &DataBuffer[0], sizeof(DataBuffer)); WdfWaitLockRelease(m_I2CWaitLock); ``` @@ -71,8 +71,8 @@ The preceding code sets aside a buffer of size *DataBuffer*, and reads the devic ```ManagedCPlusPlus // Add timestamp FILETIME Timestamp = {}; - GetSystemTimeAsFileTime(&Timestamp); - InitPropVariantFromFileTime(&Timestamp, &(m_pSensorData->List[SENSOR_DATA_TIMESTAMP].Value)); + GetSystemTimeAsFileTime(&Timestamp); + InitPropVariantFromFileTime(&Timestamp, &(m_pSensorData->List[SENSOR_DATA_TIMESTAMP].Value)); SensorsCxSensorDataReady(m_SensorInstance, m_pSensorData); ``` diff --git a/windows-driver-docs-pr/sensors/sensors-acpi-entries.md b/windows-driver-docs-pr/sensors/sensors-acpi-entries.md index 65d297ede8..c1e5065701 100644 --- a/windows-driver-docs-pr/sensors/sensors-acpi-entries.md +++ b/windows-driver-docs-pr/sensors/sensors-acpi-entries.md @@ -1,7 +1,7 @@ --- title: Sensors ACPI entries author: windows-driver-content -description: This topic describes the advanced configuration and power management interface (ACPI) entries that are specific to sensors in Windows10. +description: This topic describes the advanced configuration and power management interface (ACPI) entries that are specific to sensors in Windows 10. ms.assetid: DFDD5603-18F5-4F6C-8D09-D6905587F3CE ms.author: windowsdriverdev ms.date: 04/20/2017 @@ -13,7 +13,7 @@ ms.technology: windows-devices # Sensors ACPI entries -This topic describes the advanced configuration and power management interface (ACPI) entries that are specific to sensors in Windows10 Mobile. These entries are to be added to the ACPI source language (ASL) file. +This topic describes the advanced configuration and power management interface (ACPI) entries that are specific to sensors in Windows 10 Mobile. These entries are to be added to the ACPI source language (ASL) file. ## ROTM @@ -49,9 +49,9 @@ Method(PRIM, 0x0, NotSerialized) { **Note:** If there are multiple sensors of the same kind on the mobile device (for example, multiple accelerometers), then one of them must be marked as primary using the **PRIM** keyword. The primary sensor will be used by the WinRT API when the sensor's GetDefault method is invoked. The primary sensor will also be used by any operating system features that are dependent on that sensor type. - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/spbaccelerometer-driver-overview.md b/windows-driver-docs-pr/sensors/spbaccelerometer-driver-overview.md index 5bcfff85d8..5fc3a2e463 100644 --- a/windows-driver-docs-pr/sensors/spbaccelerometer-driver-overview.md +++ b/windows-driver-docs-pr/sensors/spbaccelerometer-driver-overview.md @@ -17,9 +17,9 @@ This sample UMDF driver controls an ADXL345 accelerometer that is connected to a Even if your system doesn't support this sensor, you can use the sample driver as a reference for integrating other devices over I2C. - + - + -------------------- diff --git a/windows-driver-docs-pr/sensors/testing-and-logging-sensor-data.md b/windows-driver-docs-pr/sensors/testing-and-logging-sensor-data.md index 7af0a92a57..a47d39f3a9 100644 --- a/windows-driver-docs-pr/sensors/testing-and-logging-sensor-data.md +++ b/windows-driver-docs-pr/sensors/testing-and-logging-sensor-data.md @@ -14,10 +14,7 @@ ms.technology: windows-devices Use the Sensor Diagnostic Tool to test whether your driver and firmware support property retrieval. The tool invokes properties in the Sensor API to determine whether you support property retrieval. - -**Note**The Sensor Diagnostic Tool is acceptable for testing on Windows8.1 and earlier operating systems. The tool is now deprecated for Windows10, so for sensor driver testing and diagnostics on Windows10 and later operating systems, please use the SensorInfo App from the Windows Store. - - +  ## Configuring the Sensor Diagnostic Tool to Retrieve Sensor Properties diff --git a/windows-driver-docs-pr/sensors/testing-location-functionality.md b/windows-driver-docs-pr/sensors/testing-location-functionality.md index 7005221ada..16f3d9aeda 100644 --- a/windows-driver-docs-pr/sensors/testing-location-functionality.md +++ b/windows-driver-docs-pr/sensors/testing-location-functionality.md @@ -15,9 +15,9 @@ ms.technology: windows-devices The Sensor Diagnostic Tool includes a separate Location tab that logs properties that are specific to location. These properties include Latitude, Longitude, and Civic Address. -**Note**The Sensor Diagnostic Tool is acceptable for testing on Windows8.1 and earlier operating systems. The tool is now deprecated for Windows10, so for sensor driver testing and diagnostics on Windows10 and later operating systems, please use the SensorInfo App from the Windows Store. +**Note** The Sensor Diagnostic Tool is acceptable for testing on Windows 8.1 and earlier operating systems. The tool is now deprecated for Windows 10, so for sensor driver testing and diagnostics on Windows 10 and later operating systems, please use the SensorInfo App from the Windows Store. - + ## Configuring the Sensor Diagnostic Tool to Capture Location Data diff --git a/windows-driver-docs-pr/sensors/testing-sensor-events.md b/windows-driver-docs-pr/sensors/testing-sensor-events.md index 13b440d65a..c793ba2c42 100644 --- a/windows-driver-docs-pr/sensors/testing-sensor-events.md +++ b/windows-driver-docs-pr/sensors/testing-sensor-events.md @@ -14,9 +14,6 @@ ms.technology: windows-devices The Sensor Diagnostic Tool lets you test support for events in your driver and firmware. - -**Note**  The Sensor Diagnostic Tool is acceptable for testing on Windows 8.1 and earlier operating systems. The tool is now deprecated for Windows 10, so for sensor driver testing and diagnostics on Windows 10 and later operating systems, please use the SensorInfo App from the Windows Store. -   ## Configuring the Sensor Diagnostic Tool to Capture Event Data @@ -24,35 +21,15 @@ The Sensor Diagnostic Tool lets you test support for events in your driver and f The following procedure describes how to configure the diagnostic tool to capture events for an accelerometer. -1. Expand the node for the accelerometer in the left Sensors pane and check the **CONNECTED** and **SUBSCRIBED** boxes. -2. In the **Events** menu, choose **Show Events**. -3. Click the Accelerometer node in the left pane. -4. Rotate the accelerometer and view the event data in the right pane +1. Expand the node for the accelerometer in the left Sensors pane and make sure both the **CONNECTED** and **SUBSCRIBED** boxes are checked. +2. In the **Events** menu, verify that **Show Events** is checked. +3. Select the Accelerometer node in the left pane. +4. Rotate the device and view the event data in the right pane. The following illustration shows the tool after it begins capturing accelerometer events. ![sensor diagnostic tool: capturing accelerometer events](images/sdt-events.png) -## Testing Support for Change Sensitivity - - -Use the Sensor Diagnostic Tool to test new change-sensitivity values. The procedure describes how to alter change sensitivity for an accelerometer. - -1. Configure the Sensor Diagnostic Tool to capture event data. (See previous section in this topic.) -2. In the upper right pane, choose **Change Sensitivity/Change**. -3. In the dialog that appears, replace the default value (or values) for each axis with the new change sensitivity values that you wish to test. -4. Press the **Update** button at the bottom of the dialog. -5. Rotate the accelerometer and view the **Data** fields to verify that the new change sensitivity values were applied. - -## Testing Support for the Current Report Interval - - -Use the Sensor Diagnostic Tool to test new current report-interval values. The following procedure describes how to alter the report interval for an accelerometer. - -1. Configure the Sensor Diagnostic Tool to capture event data. (See the first section in this topic.) -2. In the upper right pane, enter a new value (in milliseconds) in the **Report Interval** box. -3. Press the **Execute** button. -4. Rotate the accelerometer and view the timestamp for the accelerometer events to verify that the new report interval was applied. ## Logging Event Data to an XML File @@ -69,12 +46,15 @@ Your data will be logged to the file that you specified in step 3. XML logging i ## Logging Event Data to a CSV File -In addition to logging sensor data as XML, you can also log it in CSV files. If this is necessary, follow these steps. +In addition to logging sensor data as XML, you can also log it in CSV files. If this is necessary, follow these steps. + +> [!NOTE] +> You may need to run the program as an administrator for this to work properly. 1. Configure the Sensor Diagnostic Tool to capture event data (See the first section in this topic.) 2. In the **Sensors** menu, choose the **Enable CSV Logging** menu option. 3. Begin testing your device. For example, if it's an accelerometer, begin rotating, or moving, the sensor. -4. Once your tests are complete, uncheck the **Enable CSV Logging** menu option. This will stop logging and save your data to the output file. +4. Once your tests are complete, uncheck the **Enable CSV Logging** menu option. This will stop logging and save your data to the output file. The files are placed into the same directory as the executable. Your data will be logged to one or more CSV files. The tool creates a file for each connected sensor if a collection exists. CSV logging is supported for both events and data retrieval, while XML logging is only supported for events. diff --git a/windows-driver-docs-pr/sensors/testing-sensor-functionality.md b/windows-driver-docs-pr/sensors/testing-sensor-functionality.md index d72f5eda75..6f33d9f8cc 100644 --- a/windows-driver-docs-pr/sensors/testing-sensor-functionality.md +++ b/windows-driver-docs-pr/sensors/testing-sensor-functionality.md @@ -25,17 +25,14 @@ ms.technology: windows-devices You can use the Sensor Diagnostic Tool to test your sensor's functionality. Use the tool to ensure that your driver and firmware correctly forwards data from the device, and correctly responds to requests from applications. In addition, you can use the tool to verify that your driver correctly supports changes to the current report interval and change sensitivity. - -**Note**  The Sensor Diagnostic Tool is acceptable for testing on Windows 8.1 and earlier operating systems. The tool is now deprecated for Windows 10, so for sensor driver testing and diagnostics on Windows 10 and later operating systems, please use the SensorInfo App from the Windows Store. -   The Sensor platform (API and DDI) supports both event notifications and property retrieval. -- An application can register to receive events (or notifications) from a device. The driver fires these events when a specified report interval occurs, or when a certain change-sensitivity value is exceeded. For example, a game application can register to receive accelerometer event notifications twenty times a second, or whenever the sensor detects movement in excess of 0.2 g. +- A user can register to receive events (or notifications) from a device. The driver fires these events to all subscribers at the most restrictive subscriber's rate. Data can also be manually requested. For example, a game application can request to receive accelerometer event notifications twenty times a second, or subscribe to get updates whenever the driver fires events. - There are instances where an application retrieves sensor data by using a property rather than an event. For example, an application that controls brightness of a display may choose to only retrieve the current light level, after a human-presence sensor has detected the user's presence. -For a more complete description of events, report intervals, and change sensitivity (and their interrelationship), see the [Filtering data](filtering-data.md) topic. For information about using the Sensor Diagnostic Tool to test event handling, see the [Testing Sensor Events](testing-sensor-events.md) topic. +For a more complete description of events, change sensitivity (and their interrelationship), see the [Filtering data](filtering-data.md) topic. For information about using the Sensor Diagnostic Tool to test event handling, see the [Testing Sensor Events](testing-sensor-events.md) topic. For information about using the Sensor Diagnostic tool to test property retrieval, see the [Testing Sensor Properties](testing-sensor-properties.md) topic. diff --git a/windows-driver-docs-pr/sensors/testing-sensor-properties.md b/windows-driver-docs-pr/sensors/testing-sensor-properties.md index 54a3df293a..aa9d6de04b 100644 --- a/windows-driver-docs-pr/sensors/testing-sensor-properties.md +++ b/windows-driver-docs-pr/sensors/testing-sensor-properties.md @@ -14,9 +14,6 @@ ms.technology: windows-devices The Sensor Diagnostic Tool lets you test your driver and firmware support for data retrieval by invoking properties in the Sensor API. - -**Note**  The Sensor Diagnostic Tool is acceptable for testing on Windows 8.1 and earlier operating systems. The tool is now deprecated for Windows 10, so for sensor driver testing and diagnostics on Windows 10 and later operating systems, please use the SensorInfo App from the Windows Store. -   ## Configuring the Sensor Diagnostic Tool to retrieve a single sensor reading @@ -24,7 +21,7 @@ The Sensor Diagnostic Tool lets you test your driver and firmware support for da The following procedure describes how to configure the diagnostic tool to retrieve an accelerometer reading. -1. Expand the node for the accelerometer in the left Sensors pane and check the **CONNECTED** box. +1. Expand the node for the accelerometer in the left Sensors pane. Check the **CONNECTED** box and uncheck the **SUBSCRIBED** box. 2. Rotate the accelerometer and hold in place. 3. Click the **Refresh Data/Execute** button and view the retrieved data in the Data section of the right pane. @@ -33,7 +30,7 @@ The Data section of the right pane contains the updated data for your sensor. Th ## Configuring the Sensor Diagnostic Tool for synchronous polling -The following procedure describes how to configure the diagnostic tool to conduct synchronous polling of the accelerometer. +The following procedure describes how to configure the diagnostic tool to conduct synchronous polling of the accelerometer. In other words, this allows you to get a data reading from the sensor at a regular interval. 1. Expand the node for the accelerometer in the left Sensors pane; check the **CONNECTED** box and uncheck the **SUBSCRIBED** box. 2. In the **Automatic Data Request** textbox, enter your desired polling interval in milliseconds. (Note that an interval of zero disables synchronous polling.) diff --git a/windows-driver-docs-pr/sensors/the-driver-sample-file-list.md b/windows-driver-docs-pr/sensors/the-driver-sample-file-list.md index c96ef0b813..929d55b57a 100644 --- a/windows-driver-docs-pr/sensors/the-driver-sample-file-list.md +++ b/windows-driver-docs-pr/sensors/the-driver-sample-file-list.md @@ -1,7 +1,7 @@ --- title: The driver sample file list author: windows-driver-content -description: The following source files are in the src\\SPB\\SpbAccelerometer folder and are used to build the SpbAccelerometer.sys and SpbAccelerometer.inf files. +description: The following source files are in the src\SPB\SpbAccelerometer folder and are used to build the SpbAccelerometer.sys and SpbAccelerometer.inf files. ms.assetid: 48965F7F-1396-4E08-974B-3613684FAA6E ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/sensors/the-sensor-diagnostic-tool.md b/windows-driver-docs-pr/sensors/the-sensor-diagnostic-tool.md index e9c69392d1..147212147c 100644 --- a/windows-driver-docs-pr/sensors/the-sensor-diagnostic-tool.md +++ b/windows-driver-docs-pr/sensors/the-sensor-diagnostic-tool.md @@ -27,10 +27,6 @@ ms.technology: windows-devices Use the Sensor Diagnostic Tool to test your driver, firmware, and hardware functionality. -**Note**  The Sensor Diagnostic Tool is acceptable for testing on Windows 8.1 and earlier operating systems. The tool is now deprecated for Windows 10, so for sensor driver testing and diagnostics on Windows 10 and later operating systems, please use the SensorInfo App from the Windows Store. - -  - The tool invokes the Sensor and Location API to test: - Data Retrieval @@ -43,10 +39,10 @@ Instead of writing an application to perform these tests, you can use the Sensor For example, if your driver development computer is an x64-based machine, and you installed the WDK to the default location, then you will find the sensor diagnostic tool in the following folder: -*C:\\Program Files (x86)\\Windows Kits\\8.1\\Tools\\x64\\sensordiagnostictool.exe* +*C:\\Program Files (x86)\\Windows Kits\\10\\Tools\\x64\\sensordiagnostictool.exe* Once your sensor or location driver is installed and your hardware is attached to your PC, the tool immediately recognizes and records your device in the list of available sensors. -The following image shows the Sensor Diagnostic Tool startup screen when several sensors are connected to a PC. +The following image shows the Sensor Diagnostic Tool startup screen when several sensors are connected to a PC. The sensors available on the PC are shown in the left pane. ![sensor diagnostic tool: startup](images/sdt-startup.png) diff --git a/windows-driver-docs-pr/sensors/using-vector-types.md b/windows-driver-docs-pr/sensors/using-vector-types.md index 706b96613f..677ed0a6ae 100644 --- a/windows-driver-docs-pr/sensors/using-vector-types.md +++ b/windows-driver-docs-pr/sensors/using-vector-types.md @@ -39,12 +39,12 @@ responseCurve[8] = 90; responseCurve[9] = 150; // Create the buffer. PROPVARIANT pvCurve = {0}; -InitPropVariantFromBuffer(responseCurve, 10 * sizeof (UINT), &pvCurve); +InitPropVariantFromBuffer(responseCurve, 10 * sizeof (UINT), &pvCurve); // Add the values to the IPortableDeviceValues object. -hr = m_pSensorProperties->SetValue(SENSOR_PROPERTY_LIGHT_RESPONSE_CURVE, &pvCurve); +hr = m_pSensorProperties->SetValue(SENSOR_PROPERTY_LIGHT_RESPONSE_CURVE, &pvCurve); -PropVariantClear(&pvCurve); +PropVariantClear(&pvCurve); ``` diff --git a/windows-driver-docs-pr/serports/TOC.md b/windows-driver-docs-pr/serports/TOC.md index 8170090d5b..31a8aad1b3 100644 --- a/windows-driver-docs-pr/serports/TOC.md +++ b/windows-driver-docs-pr/serports/TOC.md @@ -22,6 +22,7 @@ ##### [Connecting a KMDF Peripheral Driver to a Serial Port](connecting-a-kmdf-peripheral-device-driver-to-a-serial-port.md) #### [SerCx2 Handling of Read and Write Requests](sercx2-handling-of-read-and-write-requests.md) #### [Reading Data from a SerCx2-Managed Serial Port](reading-data-from-a-sercx2-managed-serial-port.md) +### [SerCx2 Object Handles](sercx2-object-handles.md) ## [Using Serial.sys and Serenum.sys](using-serial-sys-and-serenum-sys.md) ### [Features of Serial and Serenum](features-of-serial-and-serenum.md) ### [Configuration of Serial Devices and Drivers](configuration-of-serial-devices-and-drivers.md) @@ -57,4 +58,4 @@ #### [Installing an Advanced Properties Page for a COM Port](installing-an-advanced-properties-page-for-a-com-port.md) #### [Installing Serial Devices that Use a 16550 UART-Compatible Interface](installing-serial-devices-that-use-a-16550-uart-compatible-interface.md) #### [Installing Serenum Devices](installing-serenum-devices.md) - +## [Serial IRP major function codes](serial-irp-major-function-codes.md) diff --git a/windows-driver-docs-pr/serports/sercx2-handling-of-read-and-write-requests.md b/windows-driver-docs-pr/serports/sercx2-handling-of-read-and-write-requests.md index f75235b713..b98df82bea 100644 --- a/windows-driver-docs-pr/serports/sercx2-handling-of-read-and-write-requests.md +++ b/windows-driver-docs-pr/serports/sercx2-handling-of-read-and-write-requests.md @@ -1,7 +1,7 @@ --- title: SerCx2 Handling of Read and Write Requests author: windows-driver-content -description: A peripheral driver sends write (IRP\_MJ\_WRITE) and read (IRP\_MJ\_READ) requests to a port on a serial controller to transfer data to and from a peripheral device that is connected to the port. +description: A peripheral driver sends write (IRP_MJ_WRITE) and read (IRP_MJ_READ) requests to a port on a serial controller to transfer data to and from a peripheral device that is connected to the port. ms.assetid: 98100680-7D27-42B7-A445-C539B2DF95AD ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/serports/sercx2-i-o-transactions.md b/windows-driver-docs-pr/serports/sercx2-i-o-transactions.md index 48e13669ae..49d74d3aed 100644 --- a/windows-driver-docs-pr/serports/sercx2-i-o-transactions.md +++ b/windows-driver-docs-pr/serports/sercx2-i-o-transactions.md @@ -1,7 +1,7 @@ --- title: SerCx2 I/O Transactions author: windows-driver-content -description: SerCx2 simplifies the handling of read (IRP\_MJ\_READ) and write (IRP\_MJ\_WRITE) requests for your serial controller driver. +description: SerCx2 simplifies the handling of read (IRP_MJ_READ) and write (IRP_MJ_WRITE) requests for your serial controller driver. ms.assetid: C1B3F059-A445-4224-8316-DBF194CE6A80 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/serports/sercx2-object-handles.md b/windows-driver-docs-pr/serports/sercx2-object-handles.md new file mode 100644 index 0000000000..e627f8f87a --- /dev/null +++ b/windows-driver-docs-pr/serports/sercx2-object-handles.md @@ -0,0 +1,246 @@ +--- +title: SerCx2 Object Handles +author: windows-driver-content +description: This topic describes object handle types that are specifically defined for version 2 of the serial framework extension (SerCx2). +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SerCx2 Object Handles + +This topic describes object handle types that are specifically defined for version 2 of the serial framework extension (SerCx2). +The SerCx2 device driver interface (DDI) uses these handle types to refer to objects that have features and capabilities that are specific to SerCx2. + +Additionally, the SerCx2 DDI uses two of the generic object handle types, WDFDEVICE and WDFREQUEST, that are defined by the Kernel-Mode Driver Framework (KMDF). +For more information about framework handle types, see [Summary of Framework Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/summary-of-framework-objects). + +This topic describes the following object handles: + +* [SERCX2CUSTOMRECEIVE Object Handle](#SERCX2CUSTOMRECEIVE) +* [SERCX2CUSTOMRECEIVETRANSACTION Object Handle](#SERCX2CUSTOMRECEIVETRANSACTION) +* [SERCX2CUSTOMTRANSMIT Object Handle](#SERCX2CUSTOMTRANSMIT) +* [SERCX2CUSTOMTRANSMITTRANSACTION Object Handle](#SERCX2CUSTOMTRANSMITTRANSACTION) +* [SERCX2PIORECEIVE Object Handle](#SERCX2PIORECEIVE) +* [SERCX2PIOTRANSMIT Object Handle](#SERCX2PIOTRANSMIT) +* [SERCX2SYSTEMDMARECEIVE Object Handle](#SERCX2SYSTEMDMARECEIVE) +* [SERCX2SYSTEMDMATRANSMIT Object Handle](#SERCX2SYSTEMDMATRANSMIT) + +Header: 2.0\Sercx.h + +## SERCX2CUSTOMRECEIVE Object Handle +A **SERCX2CUSTOMRECEIVE** object handle is an opaque reference to a custom-receive object in version 2 of the serial framework extension (SerCx2). + +The **SerCx2CustomReceiveCreate** method creates a custom-receive object. +SerCx2 uses this object to manage I/O transactions that use a custom data-transfer mechanism to read data from the serial controller. +This object is opaque to serial controller drivers. +**SerCx2CustomReceiveCreate** supplies, as an output parameter, a SERCX2CUSTOMRECEIVE handle to the newly created custom-receive object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent calls to SerCx2 methods and event callback functions. + +After **SerCx2CustomReceiveCreate** creates the custom-receive object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The custom-receive object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the custom-receive object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver can, as an option, create a custom-receive object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-receive object. +* The driver has *not* created a system-DMA-receive object. + +For more information about PIO-receive objects, see [SERCX2PIORECEIVE Object Handle](#SERCX2PIORECEIVE). +For more information about system-DMA-receive objects, see [SERCX2SYSTEMDMARECEIVE Object Handle](#SERCX2SYSTEMDMARECEIVE). + + +## SERCX2CUSTOMRECEIVETRANSACTION Object Handle +A **SERCX2CUSTOMRECEIVETRANSACTION** object handle is an opaque reference to a custom-receive-transaction object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2CustomReceiveTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265251) method creates a custom-receive-transaction object. +SerCx2 uses this object to manage I/O transactions that use a custom data-transfer mechanism to read data received by the serial controller. +This object is opaque to serial controller drivers. +[SerCx2CustomReceiveTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265251) supplies, as an output parameter, a SERCX2CUSTOMRECEIVETRANSACTION handle to the newly created custom-receive-transaction object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent custom-receive transactions. +For more information, see [SerCx2 Custom-Receive Transactions](https://docs.microsoft.com/en-us/windows-hardware/drivers/serports/sercx2-custom-receive-transactions). + +After [SerCx2CustomReceiveTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265251) creates the custom-receive-transaction object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The custom-receive-transaction object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the custom-receive-transaction object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver can, as an option, create a custom-receive-transaction object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-receive object. +* The driver previously created a custom-receive object. + +For more information about PIO-receive objects, see [SERCX2PIORECEIVE Object Handle](#SERCX2PIORECEIVE). +For more information about custom-receive objects, see [SERCX2CUSTOMRECEIVE Object Handle](#SERCX2CUSTOMRECEIVE). + +Despite the similar lifetimes of custom-receive and custom-receive-transaction objects, these are defined as separate object types (and not combined into one type) to support the possible future expansion of the SerCx2 device driver interface. + +## SERCX2CUSTOMTRANSMIT Object Handle +A SERCX2CUSTOMTRANSMIT object handle is an opaque reference to a custom-transmit object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2CustomTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265256) method creates a custom-transmit object.h SerCx2 uses this object to manage I/O transactions that write data to the serial controller. +This object is opaque to serial controller drivers. +[SerCx2CustomTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265256) supplies, as an output parameter, a SERCX2CUSTOMTRANSMIT handle to the newly created custom-transmit object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent calls to SerCx2 methods and event callback functions. + +After [SerCx2CustomTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265256) creates the custom-transmit object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The custom-transmit object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the custom-transmit object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver can, as an option, create a custom-transmit object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-transmit object. +* The driver has _not_ created a system-DMA-transmit object. + +For more information about PIO-transmit objects, see [SERCX2PIOTRANSMIT Object Handle](#SERCX2PIOTRANSMIT). +For more information about system-DMA-transmit objects, see [SERCX2SYSTEMDMATRANSMIT Object Handle](#SERCX2SYSTEMDMATRANSMIT). + +## SERCX2CUSTOMTRANSMITTRANSACTION Object Handle +A SERCX2CUSTOMTRANSMITTRANSACTION object handle is an opaque reference to a custom-transmit-transaction object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2CustomTransmitTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265259) method creates a custom-transmit-transaction object. +SerCx2 uses this object to manage I/O transactions that use a custom data-transfer mechanism to write data to the serial controller. +This object is opaque to serial controller drivers. +[SerCx2CustomTransmitTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265259) supplies, as an output parameter, a SERCX2CUSTOMTRANSMITTRANSACTION handle to the newly created custom-transmit-transaction object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent custom-transmit transactions. +For more information, see [SerCx2 Custom-Transmit Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265320). + +After [SerCx2CustomTransmitTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265259) creates the custom-transmit-transaction object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The custom-transmit-transaction object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the custom-transmit-transaction object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver can, as an option, create a custom-transmit object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-transmit object. +* The driver has _not_ created a system-DMA-transmit object. + +For more information about PIO-transmit objects, see [SERCX2PIOTRANSMIT Object Handle](#SERCX2PIOTRANSMIT). +For more information about custom-transmit objects, see [SERCX2CUSTOMTRANSMIT Object Handle](#SERCX2CUSTOMTRANSMIT). + +Despite the similar lifetimes of custom-transmit and custom-transmit-transaction objects, these are defined as separate object types (and not combined into one type) to support the possible future expansion of the SerCx2 device driver interface. + +## SERCX2PIORECEIVE Object Handle +A SERCX2PIORECEIVE object handle is an opaque reference to a PIO-receive object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2PioReceiveCreate](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265264) method creates a PIO-receive object. +SerCx2 uses object to manage programmed I/O (PIO) transactions that read data from the serial controller. +This object is opaque to serial controller drivers. + supplies, as an output parameter, a SERCX2PIORECEIVE handle to the newly created PIO-receive object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent PIO-receive transactions. + +For more information, see [SerCx2 PIO-Receive Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265332). +After [SerCx2PioReceiveCreate](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265264) creates the PIO-receive object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The PIO-receive object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the PIO-receive object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver must create one and only one PIO-receive object. +The driver must create this object before creating either a system-DMA-receive object or a custom-receive object. +For more information about system-DMA-receive objects, see [SERCX2SYSTEMDMARECEIVE Object Handle](#SERCX2SYSTEMDMARECEIVE). +For more information about custom-receive objects, see [SERCX2CUSTOMRECEIVE Object Handle](#SERCX2CUSTOMRECEIVE). + +## SERCX2PIOTRANSMIT Object Handle +A SERCX2PIOTRANSMIT object handle is an opaque reference to a PIO-transmit object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2PioTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265269) method creates a PIO-transmit object. +SerCx2 uses this object to manage I/O transactions that use programmed I/O (PIO) to write data to the serial controller. +This object is opaque to serial controller drivers. +[SerCx2PioTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265269) supplies, as an output parameter, a SERCX2PIOTRANSMIT handle to the newly created PIO-transmit object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent PIO-transmit transactions. +For more information, see [SerCx2 PIO-Transmit Transactions](https://msdn.microsoft.com/library/windows/hardware/dn265336). + + +After [SerCx2PioTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265269) creates the PIO-transmit object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The PIO-transmit object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the PIO-transmit object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver must create one and only one PIO-transmit object. +The driver must create this object before creating either a system-DMA-transmit object or a custom-transmit object. +For more information about system-DMA-transmit objects, see [SERCX2SYSTEMDMATRANSMIT Object Handle](#SERCX2SYSTEMDMATRANSMIT). +For more information about custom-transmit objects, see [SERCX2CUSTOMTRANSMIT Object Handle](#SERCX2CUSTOMTRANSMIT). + +## SERCX2SYSTEMDMARECEIVE Object Handle +A SERCX2SYSTEMDMARECEIVE object handle is an opaque reference to a system-DMA-receive object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2SystemDmaReceiveCreate] (https://msdn.microsoft.com/library/windows/hardware/dn265279) method creates a system-DMA-receive object. +SerCx2 uses this object to manage system DMA transactions that read data from the serial controller. +This object is opaque to serial controller drivers. +[SerCx2SystemDmaReceiveCreate] (https://msdn.microsoft.com/library/windows/hardware/dn265279) supplies, as an output parameter, a SERCX2SYSTEMDMARECEIVE handle to the newly created system-DMA-receive object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent system-DMA-receive transactions. +For more information, see [SerCx2 System-DMA-Receive Transactions](https://msdn.microsoft.com/library/windows/hardware/dn265343). + +After [SerCx2SystemDmaReceiveCreate](https://msdn.microsoft.com/library/windows/hardware/dn265279) creates the system-DMA-receive object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The system-DMA-receive object is automatically deleted when the device object is deleted. +A serial controller driver can, as an option, create a system-DMA-receive object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-receive object. +* The driver has _not_ created a custom-receive object. + +For more information about PIO-receive objects, see [SERCX2PIORECEIVE Object Handle](#SERCX2PIORECEIVE). +For more information about custom-receive objects, see [SERCX2CUSTOMRECEIVE Object Handle](#SERCX2CUSTOMRECEIVE). + +## SERCX2SYSTEMDMATRANSMIT Object Handle +A SERCX2SYSTEMDMATRANSMIT object handle is an opaque reference to a system-DMA-transmit object in version 2 of the serial framework extension (SerCx2). + +The [SerCx2SystemDmaTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265288) method creates a system-DMA-transmit object. +SerCx2 uses this object to manage system DMA transactions that write data to the serial controller. +This object is opaque to serial controller drivers. +[SerCx2SystemDmaTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265288) supplies, as an output parameter, a SERCX2SYSTEMDMATRANSMIT handle to the newly created system-DMA-transmit object. +SerCx2 and the serial controller driver use this handle to refer to the object in subsequent system-DMA-transmit transactions. +For more information, see [SerCx2 System-DMA-Transmit Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265338). + +After [SerCx2SystemDmaTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265288) creates the system-DMA-transmit object, this object exists for the lifetime of the framework device object that represents the serial controller device. +The system-DMA-transmit object is automatically deleted when the device object is deleted. +The serial controller driver must _not_ try to delete the system-DMA-transmit object by calling a method such as [WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734). + +A serial controller driver can, as an option, create a system-DMA-transmit object, but can create no more than one such object. +The driver can create this object only under the following conditions: + +* The driver previously created a PIO-transmit object. +* The driver has _not_ created a custom-transmit object. + +For more information about PIO-transmit objects, see [SERCX2PIOTRANSMIT Object Handle](#SERCX2PIOTRANSMIT). +For more information about custom-transmit objects, see [SERCX2CUSTOMTRANSMIT Object Handle](#SERCX2CUSTOMTRANSMIT). + +## Related topics + +[SerCx2 Custom-Receive Transactions](https://docs.microsoft.com/en-us/windows-hardware/drivers/serports/sercx2-custom-receive-transactions) + +[SerCx2 Custom-Transmit Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265320) + +[SerCx2 PIO-Receive Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265332) + +[SerCx2 PIO-Transmit Transactions](https://msdn.microsoft.com/library/windows/hardware/dn265336) + +[SerCx2 System-DMA-Receive Transactions](https://msdn.microsoft.com/library/windows/hardware/dn265343) + +[SerCx2 System-DMA-Transmit Transactions](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265338) + +[SerCx2CustomReceiveTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265251) + +[SerCx2CustomTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265256) + +[SerCx2CustomTransmitTransactionCreate](https://msdn.microsoft.com/library/windows/hardware/dn265259) + +[SerCx2PioReceiveCreate](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265264) + +[SerCx2PioReceiveCreate](https://msdn.microsoft.com/en-us/library/windows/hardware/dn265264) + +[SerCx2PioTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265269) + +[SerCx2SystemDmaReceiveCreate](https://msdn.microsoft.com/library/windows/hardware/dn265279) + +[SerCx2SystemDmaTransmitCreate](https://msdn.microsoft.com/library/windows/hardware/dn265288) + +[Summary of Framework Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/summary-of-framework-objects) + +[WdfObjectDelete](https://msdn.microsoft.com/library/windows/hardware/ff548734) + + + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bserports\serports%5D:%20SerCx2%20Object%20Handles%20%20RELEASE:%20%288/4/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/serports/serial-irp-major-function-codes.md b/windows-driver-docs-pr/serports/serial-irp-major-function-codes.md new file mode 100644 index 0000000000..0bac77d8e5 --- /dev/null +++ b/windows-driver-docs-pr/serports/serial-irp-major-function-codes.md @@ -0,0 +1,484 @@ +--- +title: Serial IRP major function codes +author: windows-driver-content +description: Documents serial IRP major function codes +keywords: ["serial devices WDK", "serial drivers WDK", "Serial IRP codes"] +--- + +# Serial IRP major function codes +This topic documents the following serial IRP major function codes: + +* [IRP_MJ_CREATE](#irp_mj_create) +* [IRP_MJ_DEVICE_CONTROL](#irp_mj_device_control) +* [IRP_MJ_FLUSH_BUFFERS](#irp_mj_flush_buffers) +* [IRP_MJ_INTERNAL_DEVICE_CONTROL](#irp_mj_internal_device_control) +* [IRP_MJ_PNP](#irp_mj_pnp) +* [IRP_MJ_POWER](#irp_mj_power) +* [IRP_MJ_QUERY_INFORMATION](#irp_mj_query_information) +* [IRP_MJ_READ](#irp_mj_read) +* [IRP_MJ_SET_INFORMATION](#irp_mj_set_information) +* [IRP_MJ_SYSTEM_CONTROL](#irp_mj_system_control) +* [IRP_MJ_WRITE](#irp_mj_write) + +Header: Wdm.h (include Wdm.h or Ntddk.h) + +## IRP_MJ_CREATE +The [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff550729) request opens a serial device. + +### When Sent +A client must open a serial device before it can access the port or a device connected to the port. + +### Input Parameters +None. + +### Output Parameters +None. + +### I/O Status Block +The **Information** field is set to zero. + +The **Status** field is set to one of the following values: + + +STATUS_SUCCESS + +The serial device was successfully opened. + +STATUS_ACCESS_DENIED + +The device is already open. + +STATUS_DELETE_PENDING + +Serial is in the process of removing the device. + +STATUS_INSUFFICIENT_RESOURCES + +The device is not in a Plug and Play Started state, or the driver could not allocate an internal data structure. + +STATUS_NOT_A_DIRECTORY + +A serial device cannot be opened as a directory. + +STATUS_PENDING + +Serial queued the request for later processing. + +STATUS_SHARED_IRQ_BUSY + +The interrupt assigned to the device is in use by another open device. + +### Operation +A serial device must be opened before it can be used. A serial device is an exclusive device; only one file can be open on a port at any given time. + +## IRP_MJ_DEVICE_CONTROL +The IRP_MJ_DEVICE_CONTROL request operates a serial port. + +### When Sent +A client uses device control requests to do the following: + +* Get information about the port +* Get and set registers +* Get and set operating modes + +For a description of the device control requests supported by Serial, see [Serial Device Control Requests](https://msdn.microsoft.com/library/windows/hardware/ff547466). + +### Input Parameters +Request specific + +### Output Parameters +Request specific + +### I/O Status Block +Request specific + +### Operation +Request specific + +## IRP_MJ_FLUSH_BUFFERS +The [IRP_MJ_FLUSH_BUFFER](https://msdn.microsoft.com/library/windows/hardware/ff550760) request flushes the internal write buffer of a serial device. + +### When Sent +A client uses a flush request to determine when Serial has completed all write requests the client sent before the flush request. + +### Input Parameters +None. + +### Output Parameters +None. + +### I/O Status Block +The **Information** member is set to zero. + +The **Status** member is set to one of the following status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +A client canceled the request. Serial also cancels a request if a device error occurs and Serial is configured to cancel a request if there is a device error. + +STATUS_DELETE_PENDING + +The driver is in the process of removing the device. + +STATUS_PENDING + +Serial queued the request for later processing. + +### Operation +Serial queues and starts processing write and flush requests in the order in which the requests are received. Serial completes a flush request after it calls **IoCompleteRequest** for all write requests that it received before a flush request. *However, completion of the flush request does not indicate that all the previously started write requests are completed by other drivers in the device stack.* For example, a filter driver might still be processing a write request. A client must check that a write request is completed by all drivers in the device stack before the client attempts to free or reuse a write request's IRP. + + +## IRP_MJ_INTERNAL_DEVICE_CONTROL +The [IRP_MJ_INTERNAL_DEVICE_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff550766) request sets internal operating modes on a serial device. + +### When Sent +A client uses internal device control requests to do the following: + +* Get and reset basic settings +* Control wait/wake operation + +For a description of the internal device control requests, see [Serial Internal Device Control Requests](https://msdn.microsoft.com/library/windows/hardware/ff547480). + +### Input Parameters +Request specific + +### Output Parameters +Request specific + +### I/O Status Block +Request specific + +### Operation +Request specific + + +## IRP_MJ_PNP +The [IRP_MJ_PNP](https://msdn.microsoft.com/library/windows/hardware/ff550772) request supports Plug and Play. + +### When Sent +The PnP Manager sends IRP_MJ_PNP requests to query devices and to start, stop, and remove devices. + +### Input Parameters +Request specific + +### Output Parameters +Request specific + +### I/O Status Block +Request specific + +### Operation +Serial supports the following Plug and Play requests: + +* [IRP_MN_CANCEL_REMOVE_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff550823) +* [IRP_MN_CANCEL_STOP_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff550826) +* [IRP_MN_FILTER_RESOURCE_REQUIREMENTS](https://msdn.microsoft.com/library/windows/hardware/ff550874) +* [IRP_MN_QUERY_CAPABILITIES](https://msdn.microsoft.com/library/windows/hardware/ff551664) +* [IRP_MN_QUERY_DEVICE_RELATIONS](https://msdn.microsoft.com/library/windows/hardware/ff551670) +* [IRP_MN_QUERY_ID](https://msdn.microsoft.com/library/windows/hardware/ff551679) +* [IRP_MN_QUERY_PNP_DEVICE_STATE](https://msdn.microsoft.com/library/windows/hardware/ff551698) +* [IRP_MN_QUERY_REMOVE_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551705) +* [IRP_MN_QUERY_RESOURCE_REQUIREMENTS](https://msdn.microsoft.com/library/windows/hardware/ff551715) +* [IRP_MN_QUERY_STOP_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551725) +* [IRP_MN_REMOVE_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551738) +* [IRP_MN_START_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551749) +* [IRP_MN_STOP_DEVICE](https://msdn.microsoft.com/library/windows/hardware/ff551755) +* [IRP_MN_SURPRISE_REMOVAL](https://msdn.microsoft.com/library/windows/hardware/ff551760) + +Serial sends all other Plug and Play requests down the device stack without further processing. + +Serial performs the following Serial-specific processing for Plug and Play requests: + + +IRP_MN_QUERY_ID (type BusQueryHardwardIDs) + +If a serial device is on a multiport ISA card, Serial appends the wide character string "*PNP0502" to the string of hardware IDs. + +IRP_MN_FILTER_RESOURCE_REQUIREMENTS + +serial devices on a multiport ISA card share the same interrupt status register and the same interrupt. + +For a description of the generic operation of Plug and Play requests, see [Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807). + +## IRP_MJ_POWER +The [IRP_MJ_POWER](https://msdn.microsoft.com/library/windows/hardware/ff550784) request controls power management. + +### When Sent +The power manager uses power requests to query and set power states. + +### Input Parameters +Request specific + +### Output Parameters +Request specific + +### I/O Status Block +Request specific + +### Operation +Serial supports the following power requests: + +* [IRP_MN_QUERY_POWER](https://msdn.microsoft.com/library/windows/hardware/ff551699) +* [IRP_MN_SET_POWER](https://msdn.microsoft.com/library/windows/hardware/ff551744) + +Serial sends all other power requests down the device stack to be completed by a lower-level driver. + +Serial is the default power policy owner for a serial device stack that uses Serial as a function driver or a lower-level filter driver. + +For more information about the generic operation of these requests, see [Rules for Handling Power IRPs](https://msdn.microsoft.com/library/windows/hardware/ff563629). + + +## IRP_MJ_QUERY_INFORMATION +The [IRP_MJ_QUERY_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff550788) request queries the end-of-file information for a serial device. + +### When Sent +A client uses a query information request to obtain standard information and position information about a file opened on a serial device. + +### Input Parameters +The **Parameters.QueryFile.FileInformationClass** is set to **FileStandardInformation** or **FilePositionInformation**. + +### Output Parameters + +**FileStandardInformation** +The **AssociatedIrp.SystemBuffer** member points to a client-allocated FILE_STANDARD_INFORMATION structure that Serial uses to output standard information. + +**FilePositionInformation** +The **AssociatedIrp.SystemBuffer** member points to a client-allocated FILE_POSITION_INFORMATION structure that Serial uses to output position information. + +### I/O Status Block +If the request is successful, the **Information** member is set to zero. + +The **Status** member is set to one of the following status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +A client canceled the request. Serial also cancels a request if a device error occurs and Serial is configured to cancel a request if there is a device error. + +STATUS_DELETE_PENDING + +Serial is in the process of removing the device. + +STATUS_INVALID_PARAMETER + +The requested information is not supported. + +STATUS_PENDING + +Serial queued the request for later processing. + +### Operation +Serial supports requests of type **FileStandardInformation** and **FilePositionInformation**. + +The standard file information is always set to zero or **FALSE**, as appropriate. The position information is always set to zero. + + +## IRP_MJ_READ +A [IRP_MJ_READ](https://msdn.microsoft.com/library/windows/hardware/ff550794) request transfers data from a serial device to a client. + +### When Sent +A client uses a read request whenever it reads data on a serial device. + +### Input Parameters +The **Parameters.Read.Length** member is set to the number of bytes to transfer to the client's read buffer. + +### Output Parameters +The **AssociatedIrp.SystemBuffer** member points to a client-allocated read buffer to which Serial copies data read on the serial device. + +### I/O Status Block +The **Information** member is set to the number of bytes transferred to the client's read buffer. + +The **Status** member is set to one of the following values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +A client canceled the request. Serial also cancels a request if a device error occurs and Serial is configured to cancel a request if there is a device error. + +STATUS_DELETE_PENDING + +Serial is in the process of removing the device. + +STATUS_PENDING + +Serial queued the request for later processing. + +STATUS_TIMEOUT + +The time to complete the request exceeded the total time-out value or the interval time-out value. + +### Operation +A client can use time-out events to terminate a read request. Note, however, that when a serial device is opened, the time-out settings for the device are undefined. A kernel-mode client can use an [IOCTL_SERIAL_INTERNAL_BASIC_SETTINGS](https://msdn.microsoft.com/library/windows/hardware/ff546626) to set time-out parameters to zero (no time-out events are used). User-mode and kernel-mode clients can use an [IOCTL_SERIAL_SET_TIMEOUTS](https://msdn.microsoft.com/library/windows/hardware/ff546772) request to set time-out parameters. + +For more information about read and write time-outs, see [Setting Read and Write Timeouts for a Serial Device](https://msdn.microsoft.com/library/windows/hardware/ff547486). + + +## IRP_MJ_SET_INFORMATION +The [IRP_MJ_SET_INFORMATION](https://msdn.microsoft.com/library/windows/hardware/ff550807) request sets the end-of-file information about a serial device. + +### When Sent +A client uses a set information request to change the current end-of-file position of a file opened on a serial device. + +### Input Parameters +The **Parameters.SetFile.FileInformationClass** member is set to **FileEndOfFileInformation** or **FileAllocationInformation**. + +### Output Parameters +None. + +### I/O Status Block +If the request is successful, the **Information** member is set to zero. + +The **Status** member is set to one of the following status values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +A client canceled the request. Serial also cancels a request if a device error occurs and Serial is configured to cancel a request if there is a device error. + +STATUS_DELETE_PENDING + +Serial is in the process of removing the device. + +STATUS_INVALID_PARAMETER + +The specified end-of-file information is not supported. + +STATUS_PENDING + +Serial queued the request for later processing. + +### Operation +Serial supports requests of type **FileEndOfFileInformation** and **FileAllocationInformation**. However, Serial does not actually set file information. The end-of-file position is always set to zero. + + +## IRP_MJ_SYSTEM_CONTROL +The [IRP_MJ_SYSTEM_CONTROL](https://msdn.microsoft.com/library/windows/hardware/ff550813) request supports WMI requests. + +### When Sent +A WMI kernel-mode component can send an IRP_MJ_SYSTEM_CONTROL request any time after Serial registers as a WMI provider for a serial device. WMI IRPs typically are sent when a user-mode data consumer has requested WMI data. + +### Input Parameters +Request specific + +### Output Parameters +Request specific + +### I/O Status Block +For WMI requests, Serial sets the Status field to one of the following values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_BUFFER_TOO_SMALL + +The size, in bytes, of the output buffer is less than the required size of the requested information. + +STATUS_INSUFFICIENT_RESOURCES + +There were insufficient system resources to save the serial port name. + +STATUS_INVALID_DEVICE_REQUEST + +The request is not valid. + +STATUS_WMI_GUID_NOT_FOUND + +The WMI GUID is not supported. + +### Operation +Serial uses [WmiSystemControl](https://msdn.microsoft.com/library/windows/hardware/ff565834) to handle WMI system control requests. Serial registers the following types of WMI library callback routines, which **WmiSystemControl** calls to handle WMI requests sent to a device: + +* [DpWmiQueryReginfo](https://msdn.microsoft.com/library/windows/hardware/ff544097) +* [DpWmiQueryDataBlock](https://msdn.microsoft.com/library/windows/hardware/ff544096) +* [DpWmiSetDataBlock](https://msdn.microsoft.com/library/windows/hardware/ff544104) +* [DpWmiSetDataItem](https://msdn.microsoft.com/library/windows/hardware/ff544108) + +Serial does not support any other system control requests. For non-WMI requests, Serial skips the current stack location, and sends the request down the device stack. + +Serial registers the WMI GUIDS described in the following table. + +Serial WMI GUID Associated data structure + +| SERIAL_PORT_WMI_NAME_GUID | USHORT followed by a WCSTR | +| ------------------------- | -------------------------- | +| SERIAL_PORT_WMI_COMM_GUID | SERIAL_WMI_COMM_DATA | +| SERIAL_PORT_WMI_HW_GUID | SERIAL_WMI_HW_DATA | +| SERIAL_PORT_WMI_PERF_GUID | SERIAL_WMI_PERF_DATA | +| SERIAL_PORT_WMI_PROPERTIES_GUID | WMI_SERIAL_PORT_PROPERTIES | + + +The WMI name of a serial device is the value of the entry value **PortName** under the Plug and Play registry key for the device. + + +## IRP_MJ_WRITE +An [IRP_MJ_WRITE](https://msdn.microsoft.com/library/windows/hardware/ff550819) request transfers data from a client to a serial device. + +### When Sent +A client uses a write request whenever it writes data to a serial device. + +### Input Parameters +The **Parameters.Write.Length** member is set to the number of bytes to copy from a client-allocated write buffer to a serial device. + +The **AssociatedIrp.SystemBuffer** member points to a client-allocated write buffer from which Serial copies data to the serial device. + +### Output Parameters +None. + +### I/O Status Block +The *Information* member is set to the number of bytes actually copied from the client's write buffer to the serial device. + +The *Status* member is set to one of the following values: + + +STATUS_SUCCESS + +The request completed successfully. + +STATUS_CANCELLED + +A client canceled the request. Serial also cancels a request if a device error occurs and Serial is configured to cancel a request if there is a device error. + +STATUS_DELETE_PENDING + +Serial is in the process of removing the device. + +STATUS_PENDING + +Serial queued the request for later processing. + +STATUS_TIMEOUT + +The total time allowed for the write request was exceeded. + +### Operation +A client can use time-out events to terminate a write request. Note, however, that when a serial device is opened, the time-out events set on a device are undefined. A kernel-mode client can use an [IOCTL_SERIAL_INTERNAL_BASIC_SETTINGS](https://msdn.microsoft.com/library/windows/hardware/ff546626) to set time-out parameters to zero (no time-out events are used) and an [IOCTL_SERIAL_SET_TIMEOUTS](https://msdn.microsoft.com/library/windows/hardware/ff546772) request to set time-out parameters. For more information about read and write time-outs, see [Setting Read and Write Timeouts for a Serial Device](https://msdn.microsoft.com/library/windows/hardware/ff547486). + +## Related topics + +[Plug and Play Minor IRPs](https://msdn.microsoft.com/library/windows/hardware/ff558807) + +[Rules for Handling Power IRPs](https://msdn.microsoft.com/library/windows/hardware/ff563629) + +[Serial Controller Driver Design Guide](https://msdn.microsoft.com/windows/hardware/drivers/serports/index.md) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bprint\print%5D:%20Slicer%20settings%20%20RELEASE:%20%289/2/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default. "Send comments about this topic to Microsoft") \ No newline at end of file diff --git a/windows-driver-docs-pr/spb/TOC.md b/windows-driver-docs-pr/spb/TOC.md index 12f4d3ad21..5a5cd6dfc0 100644 --- a/windows-driver-docs-pr/spb/TOC.md +++ b/windows-driver-docs-pr/spb/TOC.md @@ -7,6 +7,7 @@ ### [Using the SPB_TRANSFER_LIST Structure for Custom IOCTLs](using-the-spb-transfer-list-structure.md) ### [Handling IOCTL_SPB_FULL_DUPLEX Requests](handling-ioctl-spb-full-duplex-requests.md) ### [How to Get the Connection Settings for a Device](how-to-get-the-connection-settings-for-a-device.md) +### [SpbCx Object Handles](spbcx-object-handles.md) ## [SPB peripheral device drivers](spb-peripheral-device-drivers.md) ### [Using the SPB I/O Request Interface](using-the-spb-i-o-request-interface.md) ### [Connection IDs for SPB-Connected Peripheral Devices](connection-ids-for-spb-connected-peripheral-devices.md) diff --git a/windows-driver-docs-pr/spb/handling-ioctl-spb-full-duplex-requests.md b/windows-driver-docs-pr/spb/handling-ioctl-spb-full-duplex-requests.md index 7dc5b4485a..b5551afbf2 100644 --- a/windows-driver-docs-pr/spb/handling-ioctl-spb-full-duplex-requests.md +++ b/windows-driver-docs-pr/spb/handling-ioctl-spb-full-duplex-requests.md @@ -1,5 +1,5 @@ --- -title: Handling IOCTL\_SPB\_FULL\_DUPLEX Requests +title: Handling IOCTL_SPB_FULL_DUPLEX Requests author: windows-driver-content description: Some buses, such as SPI, enable read and write transfers to simultaneously occur between the bus controller and a device on the bus. ms.assetid: B200461F-9F9C-43A7-BA78-0864FD58C64E diff --git a/windows-driver-docs-pr/spb/how-to-get-the-connection-settings-for-a-device.md b/windows-driver-docs-pr/spb/how-to-get-the-connection-settings-for-a-device.md index 4234cabb1c..a66b61ca8c 100644 --- a/windows-driver-docs-pr/spb/how-to-get-the-connection-settings-for-a-device.md +++ b/windows-driver-docs-pr/spb/how-to-get-the-connection-settings-for-a-device.md @@ -1,7 +1,7 @@ --- title: How to Get the Connection Settings for a Device author: windows-driver-content -description: If your SPB controller driver registers an EvtSpbTargetConnect callback function, the SPB framework extension (SpbCx) calls this function when a client (peripheral driver) of the controller sends an IRP\_MJ\_CREATE request to open a logical connection to a target device on the bus. In response to the EvtSpbTargetConnect callback, the SPB controller driver should call the SpbTargetGetConnectionParameters method to get the connection settings for the target device. The SPB controller driver stores these settings and uses them later to access the device in response to I/O requests from the client. +description: If your SPB controller driver registers an EvtSpbTargetConnect callback function, the SPB framework extension (SpbCx) calls this function when a client (peripheral driver) of the controller sends an IRP_MJ_CREATE request to open a logical connection to a target device on the bus. In response to the EvtSpbTargetConnect callback, the SPB controller driver should call the SpbTargetGetConnectionParameters method to get the connection settings for the target device. The SPB controller driver stores these settings and uses them later to access the device in response to I/O requests from the client. ms.assetid: B614993A-0EA9-4B91-A336-80EEF9BE3E69 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/spb/spbcx-object-handles.md b/windows-driver-docs-pr/spb/spbcx-object-handles.md new file mode 100644 index 0000000000..b9925b19eb --- /dev/null +++ b/windows-driver-docs-pr/spb/spbcx-object-handles.md @@ -0,0 +1,115 @@ +--- +title: SpbCx Object Handles +author: windows-driver-content +description: This topic describes object handles that are defined for the SPB framework extension (SpbCx) library. +ms.prod: windows-hardware +ms.technology: windows-devices +--- + +# SpbCx Object Handles +This topic describes object handles that are defined for the SPB framework extension (SpbCx) library. + +Additionally, the SerCx2 DDI uses two of the generic object handle types, WDFDEVICE and WDFREQUEST, that are defined by the Kernel-Mode Driver Framework (KMDF). +For more information about framework handle types, see [Summary of Framework Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/summary-of-framework-objects). + +This topic describes the following object handles: + +* [SPBREQUEST Object Handle](#SPBREQUEST) +* [SPBTARGET Object Handle](#SPBTARGET) + +Header: Spbcx.h + +## SPBREQUEST Object Handle +An **SPBREQUEST** object handle represents an I/O request that is issued to a target device on the bus. + +```cpp +DECLARE_HANDLE(SPBREQUEST) +``` + +The **SPBREQUEST** object class is derived from the **WDFREQUEST** object class, which represents an I/O request that is dispatched by the I/O manager. +Thus, **WdfRequestXxx** methods that take **WDFREQUEST** handle values as parameters accept **SPBREQUEST** handle values as valid parameter values. +For more information about these methods, see [Framework Request Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/framework-request-objects). + +However, some SpbCx methods and callback functions specifically require **SPBREQUEST** handles as parameters. +For such a parameter, substituting a **WDFREQUEST** handle that is not also an **SPBREQUEST** handle is an error. + +For example, the [SpbRequestGetTransferParameters](https://msdn.microsoft.com/library/windows/hardware/hh450924) method takes an **SPBREQUEST** handle as a parameter. +To supply, for this parameter, a **WDFREQUEST** handle that is not also an **SPBREQUEST** handle is an error. +The reason for this requirement is that an **SPBREQUEST** object must store additional, SPB-specific state information to support [I/O transfer sequences](https://docs.microsoft.com/en-us/windows-hardware/drivers/spb/i-o-transfer-sequences). +The **WDFREQUEST** base object class does not provide this support. + +During device initialization, your SPB controller driver can assign a per-request context to an **SPBREQUEST** handle by calling the [SpbControllerSetRequestAttributes](https://msdn.microsoft.com/library/windows/hardware/hh450908) method. + +## SPBTARGET Object Handle +An **SPBTARGET** object handle identifies a logical connection from a client (peripheral driver) to an addressable port or peripheral device on the bus. + + ```cpp + DECLARE_HANDLE(SPBTARGET) + ``` +For an I2C bus, an **SPBTARGET** handle corresponds to a specific device address. +For an SPI bus, an **SPBTARGET** handle corresponds to a device-select line. + +Typically, an **SPBTARGET** object exists from the start of the [EvtSpbTargetConnect](https://msdn.microsoft.com/library/windows/hardware/hh450818) event callback through the end of the corresponding [EvtSpbTargetDisconnect](https://msdn.microsoft.com/library/windows/hardware/hh450820) event callback. However, the lifetime of the **SPBTARGET** object might extend beyond the second callback if the SPB controller driver takes an additional reference on the **SPBTARGET** object to prevent the object from unexpectedly disappearing during the processing of an I/O request for the target. + +The SPB controller driver performs all hardware-specific operations for an SPB controller device. +When a client sends an [IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff548630) request to open a connection to a target on the bus, the SPB framework extension (SpbCx), which manages the I/O queue for the controller driver, passes this request to the SPB controller driver by calling this driver's [EvtSpbTargetConnect](https://msdn.microsoft.com/library/windows/hardware/hh450818) callback function. +This _Target_ parameter of this function is an **SPBTARGET** handle. +The function can use this handle to retrieve connection-specific resource information (for example, the device address) from the PnP manager. +When the client sends an [IRP_MJ_CLOSE](https://msdn.microsoft.com/library/windows/hardware/ff550720) request to close the connection, SpbCx passes this request to the SPB controller driver's [EvtSpbTargetDisconnect](https://msdn.microsoft.com/library/windows/hardware/hh450820) callback function, which releases these resources. + +### Exclusive-Mode Access +Clients have exclusive-mode to access target devices. Only one client can have a connection to a particular target device at a time. +SpbCx ensures that only one **SPBTARGET** handle exists for a target device address on the bus. +This restriction is necessary because SpbCx does not support the interleaving of I/O requests that are sent by two or more clients to a target device. +If a target device must be able to receive requests from several clients, this device requires a MUX driver—separate from the controller driver—that can properly interleave the requested operations. + +### Interoperability with KMDF +The [SerCx2 Driver Support Methods](https://msdn.microsoft.com/library/windows/hardware/dn265323) and [SpbCx Event Callback Functions](https://msdn.microsoft.com/library/windows/hardware/hh450911) that are defined by SpbCx use **SPBTARGET** handles to represent open connections to target devices on the bus. +However, a controller driver must typically call KMDF methods that require WDFFILEOBJECT handles, instead of **SPBTARGET** handles, to designate target devices. + +An **SPBTARGET** object is similar to a WDFFILEOBJECT object. However, an **SPBTARGET** object contains additional, SPB-specific information. +For example, during the processing of an [IOCTL_SPB_EXECUTE_SEQUENCE](https://msdn.microsoft.com/library/windows/hardware/hh450857) I/O control request, the **SPBTARGET** object for the target device tracks the state of the transfers in the [I/O transfer sequence](https://docs.microsoft.com/en-us/windows-hardware/drivers/spb/i-o-transfer-sequences). + +To obtain the WDFFILEOBJECT handle to a target, the SPB controller driver calls the [SpbTargetGetFileObject](https://msdn.microsoft.com/library/windows/hardware/hh450927) method. +This method accepts, as an input parameter, an **SPBTARGET** handle to an open target device, and returns the corresponding WDFFILEOBJECT handle to this target. + +In accordance with KMDF conventions, the SPB controller driver can attach its own context to the **SPBTARGET** object for a target device, and this context can include associated [EvtCleanupCallback](https://msdn.microsoft.com/library/windows/hardware/ff540840) and [EvtDestroyCallback](https://msdn.microsoft.com/library/windows/hardware/ff540841) callback functions. +The SPB controller driver uses this context to track information that is specific to the controller driver and to the target device. +In addition, this driver can create child objects of the **SPBTARGET** object, such as timers, DPCs, or, if needed, I/O requests and I/O queues. + +## Related topics + +[EvtCleanupCallback](https://msdn.microsoft.com/library/windows/hardware/ff540840) + +[EvtDestroyCallback](https://msdn.microsoft.com/library/windows/hardware/ff540841) + +[EvtSpbTargetConnect](https://msdn.microsoft.com/library/windows/hardware/hh450818) + +[EvtSpbTargetDisconnect](https://msdn.microsoft.com/library/windows/hardware/hh450820) + +[Framework Request Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/framework-request-objects) + +[I/O transfer sequence](https://docs.microsoft.com/en-us/windows-hardware/drivers/spb/i-o-transfer-sequences) + +[IOCTL_SPB_EXECUTE_SEQUENCE](https://msdn.microsoft.com/library/windows/hardware/hh450857) + +[IRP_MJ_CLOSE](https://msdn.microsoft.com/library/windows/hardware/ff550720) + +[IRP_MJ_CREATE](https://msdn.microsoft.com/library/windows/hardware/ff548630) + +[SerCx2 Driver Support Methods](https://msdn.microsoft.com/library/windows/hardware/dn265323) + +[SpbControllerSetRequestAttributes](https://msdn.microsoft.com/library/windows/hardware/hh450908) + +[SpbCx Event Callback Functions](https://msdn.microsoft.com/library/windows/hardware/hh450911) + +[SpbRequestGetTransferParameters](https://msdn.microsoft.com/library/windows/hardware/hh450924) + +[SpbTargetGetFileObject](https://msdn.microsoft.com/library/windows/hardware/hh450927) + +[Summary of Framework Objects](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/summary-of-framework-objects) + +-------------------- +[Send comments about this topic to Microsoft](mailto:wsddocfb@microsoft.com?subject=Documentation%20feedback%20%5Bserports\serports%5D:%20SpbCx%20Object%20Handles%20%20RELEASE:%20%288/4/2016%29&body=%0A%0APRIVACY%20STATEMENT%0A%0AWe%20use%20your%20feedback%20to%20improve%20the%20documentation.%20We%20don't%20use%20your%20email%20address%20for%20any%20other%20purpose,%20and%20we'll%20remove%20your%20email%20address%20from%20our%20system%20after%20the%20issue%20that%20you're%20reporting%20is%20fixed.%20While%20we're%20working%20to%20fix%20this%20issue,%20we%20might%20send%20you%20an%20email%20message%20to%20ask%20for%20more%20info.%20Later,%20we%20might%20also%20send%20you%20an%20email%20message%20to%20let%20you%20know%20that%20we've%20addressed%20your%20feedback.%0A%0AFor%20more%20info%20about%20Microsoft's%20privacy%20policy,%20see%20http://privacy.microsoft.com/default.aspx. "Send comments about this topic to Microsoft") + + diff --git a/windows-driver-docs-pr/spb/using-the-spb-transfer-list-structure.md b/windows-driver-docs-pr/spb/using-the-spb-transfer-list-structure.md index 6a53df4c6c..96aac2cfb3 100644 --- a/windows-driver-docs-pr/spb/using-the-spb-transfer-list-structure.md +++ b/windows-driver-docs-pr/spb/using-the-spb-transfer-list-structure.md @@ -1,7 +1,7 @@ --- -title: Using the SPB\_TRANSFER\_LIST Structure for Custom IOCTLs +title: Using the SPB_TRANSFER_LIST Structure for Custom IOCTLs author: windows-driver-content -description: If your simple peripheral bus (SPB) controller driver supports one or more custom I/O control (IOCTL) requests, use the SPB\_TRANSFER\_LIST structure to describe the read and write buffers in these requests. +description: If your simple peripheral bus (SPB) controller driver supports one or more custom I/O control (IOCTL) requests, use the SPB_TRANSFER_LIST structure to describe the read and write buffers in these requests. ms.assetid: 577122CC-D1F8-41C5-BE77-A22FC8516B82 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/storage/handling-srb-function-abort-command.md b/windows-driver-docs-pr/storage/handling-srb-function-abort-command.md index 5370e3c738..c6439384e2 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-abort-command.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-abort-command.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_ABORT\_COMMAND +title: Handling SRB_FUNCTION_ABORT_COMMAND author: windows-driver-content -description: Handling SRB\_FUNCTION\_ABORT\_COMMAND +description: Handling SRB_FUNCTION_ABORT_COMMAND ms.assetid: 74d46df6-2e3e-45d8-bedb-a81a80a0aec1 keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-execute-scsi.md b/windows-driver-docs-pr/storage/handling-srb-function-execute-scsi.md index 6ed83634d9..b4897d5e5b 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-execute-scsi.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-execute-scsi.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_EXECUTE\_SCSI +title: Handling SRB_FUNCTION_EXECUTE_SCSI author: windows-driver-content -description: Handling SRB\_FUNCTION\_EXECUTE\_SCSI +description: Handling SRB_FUNCTION_EXECUTE_SCSI ms.assetid: 221e1070-12d8-4870-a23c-426ed4a25b84 keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-flush-and-srb-function-shutdown.md b/windows-driver-docs-pr/storage/handling-srb-function-flush-and-srb-function-shutdown.md index 9d35ba7521..6cb782b618 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-flush-and-srb-function-shutdown.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-flush-and-srb-function-shutdown.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_FLUSH and SRB\_FUNCTION\_SHUTDOWN +title: Handling SRB_FUNCTION_FLUSH and SRB_FUNCTION_SHUTDOWN author: windows-driver-content -description: Handling SRB\_FUNCTION\_FLUSH and SRB\_FUNCTION\_SHUTDOWN +description: Handling SRB_FUNCTION_FLUSH and SRB_FUNCTION_SHUTDOWN ms.assetid: d4b8b3e5-d895-42ca-bd28-9d3cef805654 keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-io-control.md b/windows-driver-docs-pr/storage/handling-srb-function-io-control.md index 4bbdb640da..639e73364a 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-io-control.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-io-control.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_IO\_CONTROL +title: Handling SRB_FUNCTION_IO_CONTROL author: windows-driver-content -description: Handling SRB\_FUNCTION\_IO\_CONTROL +description: Handling SRB_FUNCTION_IO_CONTROL ms.assetid: 92d09a49-d8e8-4d97-b334-c42d5b04ee8d keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-pnp.md b/windows-driver-docs-pr/storage/handling-srb-function-pnp.md index 8dbfffb5b0..1e1cff8ad1 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-pnp.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-pnp.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_PNP +title: Handling SRB_FUNCTION_PNP author: windows-driver-content -description: Handling SRB\_FUNCTION\_PNP +description: Handling SRB_FUNCTION_PNP ms.assetid: 25490320-8d6b-4c5a-a585-4f628ea72393 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/storage/handling-srb-function-reset-bus.md b/windows-driver-docs-pr/storage/handling-srb-function-reset-bus.md index cc34b718ad..c97d2ab311 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-reset-bus.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-reset-bus.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_RESET\_BUS +title: Handling SRB_FUNCTION_RESET_BUS author: windows-driver-content -description: Handling SRB\_FUNCTION\_RESET\_BUS +description: Handling SRB_FUNCTION_RESET_BUS ms.assetid: 285cbd5c-e364-4f0f-9020-0bc6f3d45cac keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-reset-device.md b/windows-driver-docs-pr/storage/handling-srb-function-reset-device.md index 18e95467ca..ed62ff594f 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-reset-device.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-reset-device.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_RESET\_DEVICE +title: Handling SRB_FUNCTION_RESET_DEVICE author: windows-driver-content -description: Handling SRB\_FUNCTION\_RESET\_DEVICE +description: Handling SRB_FUNCTION_RESET_DEVICE ms.assetid: d95bca21-306e-4598-a8c6-04990885e23d keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-srb-function-wmi.md b/windows-driver-docs-pr/storage/handling-srb-function-wmi.md index c42b9042a4..16eab54376 100644 --- a/windows-driver-docs-pr/storage/handling-srb-function-wmi.md +++ b/windows-driver-docs-pr/storage/handling-srb-function-wmi.md @@ -1,7 +1,7 @@ --- -title: Handling SRB\_FUNCTION\_WMI +title: Handling SRB_FUNCTION_WMI author: windows-driver-content -description: Handling SRB\_FUNCTION\_WMI +description: Handling SRB_FUNCTION_WMI ms.assetid: df20b9dc-1b67-4044-8abe-3cf5714076b3 keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/handling-unsupported-srb-function-xxx.md b/windows-driver-docs-pr/storage/handling-unsupported-srb-function-xxx.md index ec7912fbbc..ed56dbb93d 100644 --- a/windows-driver-docs-pr/storage/handling-unsupported-srb-function-xxx.md +++ b/windows-driver-docs-pr/storage/handling-unsupported-srb-function-xxx.md @@ -1,7 +1,7 @@ --- -title: Handling Unsupported SRB\_FUNCTION\_XXX +title: Handling Unsupported SRB_FUNCTION_XXX author: windows-driver-content -description: Handling Unsupported SRB\_FUNCTION\_XXX +description: Handling Unsupported SRB_FUNCTION_XXX ms.assetid: 95b9288c-290f-4908-9de3-11d68ed624e2 keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/other-srb-function-xxx--requests.md b/windows-driver-docs-pr/storage/other-srb-function-xxx--requests.md index 31a1e326e1..7b9ccf41bf 100644 --- a/windows-driver-docs-pr/storage/other-srb-function-xxx--requests.md +++ b/windows-driver-docs-pr/storage/other-srb-function-xxx--requests.md @@ -1,7 +1,7 @@ --- -title: Other SRB\_FUNCTION\_XXX Requests +title: Other SRB_FUNCTION_XXX Requests author: windows-driver-content -description: Other SRB\_FUNCTION\_XXX Requests +description: Other SRB_FUNCTION_XXX Requests ms.assetid: b0430d8e-e5cd-4f17-b77f-ec608b1469da keywords: - SCSI miniport drivers WDK storage , HwScsiStartIo diff --git a/windows-driver-docs-pr/storage/sample-storport-miniport-driver-for-an-lsi-u3-device.md b/windows-driver-docs-pr/storage/sample-storport-miniport-driver-for-an-lsi-u3-device.md index 24f3231a2c..403c78f7d2 100644 --- a/windows-driver-docs-pr/storage/sample-storport-miniport-driver-for-an-lsi-u3-device.md +++ b/windows-driver-docs-pr/storage/sample-storport-miniport-driver-for-an-lsi-u3-device.md @@ -1,7 +1,7 @@ --- -title: Sample Storport Miniport Driver for an LSI\_U3 Device +title: Sample Storport Miniport Driver for an LSI_U3 Device author: windows-driver-content -description: Sample Storport Miniport Driver for an LSI\_U3 Device +description: Sample Storport Miniport Driver for an LSI_U3 Device ms.assetid: 1ac63d07-f85c-492b-9886-f40a19d7c0b2 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/stream/extended-camera-control-payloads.md b/windows-driver-docs-pr/stream/extended-camera-control-payloads.md index f552f175dd..b8f6a4b9f9 100644 --- a/windows-driver-docs-pr/stream/extended-camera-control-payloads.md +++ b/windows-driver-docs-pr/stream/extended-camera-control-payloads.md @@ -1,7 +1,7 @@ --- title: Extended Camera Control Payloads author: windows-driver-content -description: The control properties within the KSPROPERTYSETID\_ExtendedCameraControl property set use a common payload format for getting and setting the property data. +description: The control properties within the KSPROPERTYSETID_ExtendedCameraControl property set use a common payload format for getting and setting the property data. ms.assetid: 347413DB-229B-40D7-BD3E-931493EE1FBC ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/stream/how-to-implement-extended-camera-control-properties.md b/windows-driver-docs-pr/stream/how-to-implement-extended-camera-control-properties.md index 27c8770ce3..ebe977496b 100644 --- a/windows-driver-docs-pr/stream/how-to-implement-extended-camera-control-properties.md +++ b/windows-driver-docs-pr/stream/how-to-implement-extended-camera-control-properties.md @@ -1,7 +1,7 @@ --- title: How To Implement Extended Camera Control Properties author: windows-driver-content -description: The camera driver should implement extended camera control properties as individual property sets \ 8212;that is, each property should be implemented as a single property set. +description: Implementing extended camera control properties for a camera driver. ms.assetid: BF5B2F1F-AC1D-4ED1-B1FC-64E8FA1218DA ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/taef/authoring-tests-in-c-.md b/windows-driver-docs-pr/taef/authoring-tests-in-c-.md index 917b438883..8d0d49ead3 100644 --- a/windows-driver-docs-pr/taef/authoring-tests-in-c-.md +++ b/windows-driver-docs-pr/taef/authoring-tests-in-c-.md @@ -1,6 +1,6 @@ --- -title: Authoring Tests in C\ -description: Authoring Tests in C\ +title: Authoring Tests in C# +description: Authoring Tests in C# ms.assetid: 4DD1D673-FEAF-44a4-8BAD-0E55318DC64B ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/taef/getting-started.md b/windows-driver-docs-pr/taef/getting-started.md index 99f4f1ba78..a495d71805 100644 --- a/windows-driver-docs-pr/taef/getting-started.md +++ b/windows-driver-docs-pr/taef/getting-started.md @@ -1,4 +1,4 @@ ---- +[--- title: Getting Started with TAEF description: Getting Started with Test Authoring and Execution Framework (TAEF) ms.assetid: 7F57C5EF-141A-4303-9B9F-2EC118324BF8 @@ -15,7 +15,7 @@ ms.technology: windows-devices ## Installation -When you install the Windows Driver Kit, the TAEF files are placed in the Testing\\Runtimes\\TAEF subdirectory of the WDK. When you set up a test computer for deployment, following the instructions to [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909) or [Provision a computer for driver deployment and testing (WDK 8)](https://msdn.microsoft.com/library/windows/hardware/hh698272), the TAEF files are installed on the test computer. +When you install the [Windows Driver Kit](https://developer.microsoft.com/en-us/windows/hardware/windows-driver-kit), the TAEF files are placed in the Testing\\Runtimes\\TAEF subdirectory of the WDK. When you set up a test computer for deployment, following the instructions to [Provision a computer for driver deployment and testing (WDK 8.1)](https://msdn.microsoft.com/library/windows/hardware/dn745909) or [Provision a computer for driver deployment and testing (WDK 8)](https://msdn.microsoft.com/library/windows/hardware/hh698272), the TAEF files are installed on the test computer. You can also install the TAEF files manually, see [Manually installing and uninstalling TAEF on a test computer](#manually-installing-and-uninstalling-taef-on-a-test-computer). diff --git a/windows-driver-docs-pr/umdf-1-deprecation.md b/windows-driver-docs-pr/umdf-1-deprecation.md new file mode 100644 index 0000000000..b6ee38db05 --- /dev/null +++ b/windows-driver-docs-pr/umdf-1-deprecation.md @@ -0,0 +1,7 @@ +--- +title: UMDF 1 Deprecation +--- +> [!WARNING] +> UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. +> +> For more info, see [Getting Started with UMDF](https://docs.microsoft.com/en-us/windows-hardware/drivers/wdf/getting-started-with-umdf-version-2). \ No newline at end of file diff --git a/windows-driver-docs-pr/usbcon/TOC.md b/windows-driver-docs-pr/usbcon/TOC.md index 7523d9c96f..6c558dc411 100644 --- a/windows-driver-docs-pr/usbcon/TOC.md +++ b/windows-driver-docs-pr/usbcon/TOC.md @@ -129,7 +129,7 @@ #### [USBStress](usbstress.md) #### [USBTCD](usbtcd.md) #### [USB XHCIWMI](usb-xhciwmi.md) -### [Test USB Type-C systems with MUTT ConnEx-C](test-usb-type-c-systems-with-mutt-connex-c.md) +### [Test USB Type-C systems with USB Type-C ConnEx](test-usb-type-c-systems-with-mutt-connex-c.md) ### [USB Type-C manual interoperability test procedures](type.md) ### [How to prepare the test system to run MUTT test tools](mutt-testing-options.md) ### [How to run stress and transfer performance tests for MUTT devices](how-to-run-stress-and-transfer-and-super-mutt-performance-tests-for-mutt-devices.md) diff --git a/windows-driver-docs-pr/usbcon/architecture--usb-type-c-in-a-windows-system.md b/windows-driver-docs-pr/usbcon/architecture--usb-type-c-in-a-windows-system.md index 81d5266371..1ce933a60d 100644 --- a/windows-driver-docs-pr/usbcon/architecture--usb-type-c-in-a-windows-system.md +++ b/windows-driver-docs-pr/usbcon/architecture--usb-type-c-in-a-windows-system.md @@ -1,6 +1,7 @@ --- Description: Describes a typical hardware design of a USB Type-C system and the Microsoft-provided drivers that support the hardware components. title: Architecture of USB Type-C design for a Windows system +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/bring-up-a-usb-type-c-connector-on-a-windows-system.md b/windows-driver-docs-pr/usbcon/bring-up-a-usb-type-c-connector-on-a-windows-system.md index cb0eb7a5d0..539d6240d0 100644 --- a/windows-driver-docs-pr/usbcon/bring-up-a-usb-type-c-connector-on-a-windows-system.md +++ b/windows-driver-docs-pr/usbcon/bring-up-a-usb-type-c-connector-on-a-windows-system.md @@ -1,6 +1,7 @@ --- Description: Describes the USB connector manager (UCM) that manages a USB Type-C connector and the expected behavior of a connector driver. title: Write a USB Type-C connector driver +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -28,7 +29,7 @@ ms.technology: windows-devices **WDF version** -- KMDF version 1.15. +- KMDF version 1.15 - UMDF version 2.15 **Last updated:** @@ -63,7 +64,7 @@ To enable a USB Type-C connector on a system, you must write the client driver. This support enables you to build Windows devices with USB Type-C connectors, USB Type-C docks and accessories, and USB Type-C chargers. The client driver reports connector events that allow the operating system to implement policies around USB and power consumption in the system. -- Install Windows 10 for desktop editions (Home, Pro, Enterprise, and Education) on your target computer or Windows 10 Mobile with the USB Type-C connector. +- Install Windows 10 for desktop editions (Home, Pro, Enterprise, and Education) on your target computer or Windows 10 Mobile with a USB Type-C connector. - Familiarize yourself with UCM and how it interacts with other Windows drivers. See [Architecture: USB Type-C design for a Windows system](architecture--usb-type-c-in-a-windows-system.md). - Familiarize yourself with Windows Driver Foundation (WDF). Recommended reading: [Developing Drivers with Windows Driver Foundation]( http://go.microsoft.com/fwlink/p/?LinkId=691676), written by Penny Orwick and Guy Smith. @@ -168,9 +169,9 @@ EvtDevicePrepareHardware( // // Initialize UCM Manager // - UCM_MANAGER_CONFIG_INIT(&ucmCfg); + UCM_MANAGER_CONFIG_INIT(&ucmCfg); - status = UcmInitializeDevice(Device, &ucmCfg); + status = UcmInitializeDevice(Device, &ucmCfg); if (!NT_SUCCESS(status)) { TRACE_ERROR( @@ -184,23 +185,23 @@ EvtDevicePrepareHardware( // // Create a USB Type-C connector #0 with PD // - UCM_CONNECTOR_CONFIG_INIT(&connCfg, 0); + UCM_CONNECTOR_CONFIG_INIT(&connCfg, 0); UCM_CONNECTOR_TYPEC_CONFIG_INIT( - &typeCConfig, + &typeCConfig, UcmTypeCOperatingModeDrp, UcmTypeCCurrentDefaultUsb | UcmTypeCCurrent1500mA | UcmTypeCCurrent3000mA); typeCConfig.EvtSetDataRole = EvtSetDataRole; - UCM_CONNECTOR_PD_CONFIG_INIT(&pdConfig, UcmPowerRoleSink | UcmPowerRoleSource); + UCM_CONNECTOR_PD_CONFIG_INIT(&pdConfig, UcmPowerRoleSink | UcmPowerRoleSource); - connCfg.TypeCConfig = &typeCConfig; - connCfg.PdConfig = &pdConfig; + connCfg.TypeCConfig = &typeCConfig; + connCfg.PdConfig = &pdConfig; - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attr, CONNECTOR_CONTEXT); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attr, CONNECTOR_CONTEXT); - status = UcmConnectorCreate(Device, &connCfg, &attr, &devCtx->Connector); + status = UcmConnectorCreate(Device, &connCfg, &attr, &devCtx->Connector); if (!NT_SUCCESS(status)) { TRACE_ERROR( @@ -211,7 +212,7 @@ EvtDevicePrepareHardware( connCtx = GetConnectorContext(devCtx->Connector); - UcmEventInitialize(&connCtx->EventSetDataRole); + UcmEventInitialize(&connCtx->EventSetDataRole); TRACE_INFO("UcmConnectorCreate() succeeded."); @@ -233,13 +234,13 @@ The UCM class extension also notifies the USB role-switch drivers (URS). Based o UCM_CONNECTOR_TYPEC_ATTACH_PARAMS attachParams; UCM_CONNECTOR_TYPEC_ATTACH_PARAMS_INIT( - &attachParams, + &attachParams, UcmTypeCPortStateDfp); attachParams.CurrentAdvertisement = UcmTypeCCurrent1500mA; status = UcmConnectorTypeCAttach( Connector, - &attachParams); + &attachParams); if (!NT_SUCCESS(status)) { TRACE_ERROR( diff --git a/windows-driver-docs-pr/usbcon/capture-and-view-ing-usb-traces-with-microsoft-message-analyzer-.md b/windows-driver-docs-pr/usbcon/capture-and-view-ing-usb-traces-with-microsoft-message-analyzer-.md index 0c2b486ed7..e30adb27d5 100644 --- a/windows-driver-docs-pr/usbcon/capture-and-view-ing-usb-traces-with-microsoft-message-analyzer-.md +++ b/windows-driver-docs-pr/usbcon/capture-and-view-ing-usb-traces-with-microsoft-message-analyzer-.md @@ -25,7 +25,7 @@ Instead of capturing traces by using the command line tool, logman, and then par ## Install and launch Microsoft Message Analyzer -1. [Download Microsoft Message Analyzer](http://www.microsoft.com/download/details.aspx?id=40308) and install the tool by following **Install Instructions** on the download page. After downloading, follow the install prompts and select **Update items**. +1. [Download Microsoft Message Analyzer](https://www.microsoft.com/en-us/download/details.aspx?id=44226) and install the tool by following **Install Instructions** on the download page. After downloading, follow the install prompts and select **Update items**. 2. After installation completes, the tool launches and the start page is shown. diff --git a/windows-driver-docs-pr/usbcon/case-study--troubleshooting-an-unknown-usb-device-by-using-etw-and-netmon.md b/windows-driver-docs-pr/usbcon/case-study--troubleshooting-an-unknown-usb-device-by-using-etw-and-netmon.md index 07d21eae2a..8457882103 100644 --- a/windows-driver-docs-pr/usbcon/case-study--troubleshooting-an-unknown-usb-device-by-using-etw-and-netmon.md +++ b/windows-driver-docs-pr/usbcon/case-study--troubleshooting-an-unknown-usb-device-by-using-etw-and-netmon.md @@ -1,6 +1,7 @@ --- Description: Provides an example of how to use USB ETW and Netmon to troubleshoot a USB device that Windows does not recognize. title: Case Study - Troubleshooting an unknown USB device +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/cdc-atm-networking-control-model.md b/windows-driver-docs-pr/usbcon/cdc-atm-networking-control-model.md index c8e44da5db..9c6869a089 100644 --- a/windows-driver-docs-pr/usbcon/cdc-atm-networking-control-model.md +++ b/windows-driver-docs-pr/usbcon/cdc-atm-networking-control-model.md @@ -1,6 +1,7 @@ --- Description: CDC ATM Networking Control Model title: CDC ATM Networking Control Model +author: windows-driver-content --- # CDC ATM Networking Control Model @@ -46,15 +47,15 @@ USB CDC ATM Networking Control Model (ANCM) interface collections have the follo

Hardware IDs

-
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07&MI_%02x
-USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07
-USB\Vid_%04x&Pid_%04x&Cdc_07&MI_%02x
-USB\Vid_%04x&Pid_%04x&Cdc_07
+
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07&MI_%02x
+USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07
+USB\Vid_%04x&Pid_%04x&Cdc_07&MI_%02x
+USB\Vid_%04x&Pid_%04x&Cdc_07

Compatible IDs

-
USB\Class_02&SubClass_07&Prot_00
-USB\Class_02&SubClass_07
+
USB\Class_02&SubClass_07&Prot_00
+USB\Class_02&SubClass_07
 USB\Class_02
diff --git a/windows-driver-docs-pr/usbcon/cdc-direct-line-control-model.md b/windows-driver-docs-pr/usbcon/cdc-direct-line-control-model.md index 4da1da432b..2ecceeba3a 100644 --- a/windows-driver-docs-pr/usbcon/cdc-direct-line-control-model.md +++ b/windows-driver-docs-pr/usbcon/cdc-direct-line-control-model.md @@ -1,6 +1,7 @@ --- Description: CDC Direct Line Control Model title: CDC Direct Line Control Model +author: windows-driver-content --- # CDC Direct Line Control Model @@ -46,15 +47,15 @@ USB CDC Direct Line Control Model (DLCM) interface collections have the followin

Hardware IDs

-
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01&MI_%02x
-USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01
-USB\Vid_%04x&Pid_%04x&Cdc_01&MI_%02x
-USB\Vid_%04x&Pid_%04x&Cdc_01
+
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01&MI_%02x
+USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01
+USB\Vid_%04x&Pid_%04x&Cdc_01&MI_%02x
+USB\Vid_%04x&Pid_%04x&Cdc_01

Compatible IDs

-
USB\Class_02&SubClass_01&Prot_00
-USB\Class_02&SubClass_01
+
USB\Class_02&SubClass_01&Prot_00
+USB\Class_02&SubClass_01
 USB\Class_02
diff --git a/windows-driver-docs-pr/usbcon/cdc-multi-channel-isdn-control-model.md b/windows-driver-docs-pr/usbcon/cdc-multi-channel-isdn-control-model.md index 26cb10c8ce..27d316868a 100644 --- a/windows-driver-docs-pr/usbcon/cdc-multi-channel-isdn-control-model.md +++ b/windows-driver-docs-pr/usbcon/cdc-multi-channel-isdn-control-model.md @@ -1,6 +1,7 @@ --- Description: CDC Multi-Channel ISDN Control Model title: CDC Multi-Channel ISDN Control Model +author: windows-driver-content --- # CDC Multi-Channel ISDN Control Model @@ -46,15 +47,15 @@ USB CDC Multi-Channel ISDN Control Model (MCCM) interface collections have the f

Hardware IDs

-
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04&MI_%02x
-USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04
-USB\Vid_%04x&Pid_%04x&Cdc_04&MI_%02x
-USB\Vid_%04x&Pid_%04x&Cdc_04
+
USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04&MI_%02x
+USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04
+USB\Vid_%04x&Pid_%04x&Cdc_04&MI_%02x
+USB\Vid_%04x&Pid_%04x&Cdc_04

Compatible IDs

-
USB\Class_02&SubClass_04&Prot_00
-USB\Class_02&SubClass_04
+
USB\Class_02&SubClass_04&Prot_00
+USB\Class_02&SubClass_04
 USB\Class_02
diff --git a/windows-driver-docs-pr/usbcon/communicating-with-a-usb-device.md b/windows-driver-docs-pr/usbcon/communicating-with-a-usb-device.md index eba85ffc0b..57987062b0 100644 --- a/windows-driver-docs-pr/usbcon/communicating-with-a-usb-device.md +++ b/windows-driver-docs-pr/usbcon/communicating-with-a-usb-device.md @@ -1,6 +1,7 @@ --- Description: Information about how a USB client driver can allocate, build, and submit URBs to the USB driver stack. title: USB Request Blocks (URBs) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/content-security-features-in-the-composite-client-generic-parent-drive.md b/windows-driver-docs-pr/usbcon/content-security-features-in-the-composite-client-generic-parent-drive.md index 33322f2a6e..045812df3e 100644 --- a/windows-driver-docs-pr/usbcon/content-security-features-in-the-composite-client-generic-parent-drive.md +++ b/windows-driver-docs-pr/usbcon/content-security-features-in-the-composite-client-generic-parent-drive.md @@ -1,6 +1,7 @@ --- Description: Digital Rights Management (DRM) systems often make use of device serial numbers to ensure that legitimate customers have access to digitized intellectual property. title: Content Security Features in Usbccgp.sys +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices.md b/windows-driver-docs-pr/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices.md index 746e28f49b..8d3a61b243 100644 --- a/windows-driver-docs-pr/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices.md +++ b/windows-driver-docs-pr/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices.md @@ -1,6 +1,7 @@ --- Description: Developing Windows drivers for emulated USB devices (UDE) title: Developing Windows drivers for emulated USB devices (UDE) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/dual-role-controller-bringup-for-a-usb-type-c-system.md b/windows-driver-docs-pr/usbcon/dual-role-controller-bringup-for-a-usb-type-c-system.md index c020d21d90..2ee14e25ca 100644 --- a/windows-driver-docs-pr/usbcon/dual-role-controller-bringup-for-a-usb-type-c-system.md +++ b/windows-driver-docs-pr/usbcon/dual-role-controller-bringup-for-a-usb-type-c-system.md @@ -1,6 +1,7 @@ --- Description: The USB role-switch driver and its client driver that handle the role-switching capability of a dual-role controller. title: Bring up the dual-role controller for a USB Type-C Windows system +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/enabling-selective-suspend.md b/windows-driver-docs-pr/usbcon/enabling-selective-suspend.md index 0e0b3c9130..2636fd614b 100644 --- a/windows-driver-docs-pr/usbcon/enabling-selective-suspend.md +++ b/windows-driver-docs-pr/usbcon/enabling-selective-suspend.md @@ -1,6 +1,7 @@ --- Description: Selective suspend is disabled for upgrade versions of Microsoft Windows XP. It is enabled for clean installations of Windows XP, Windows Vista, and later versions of Windows. title: Enabling Selective Suspend +author: windows-driver-content --- # Enabling Selective Suspend diff --git a/windows-driver-docs-pr/usbcon/faq--usb-type-c-connector-on-a-windows-system.md b/windows-driver-docs-pr/usbcon/faq--usb-type-c-connector-on-a-windows-system.md index 82af2fa0be..54a40d8147 100644 --- a/windows-driver-docs-pr/usbcon/faq--usb-type-c-connector-on-a-windows-system.md +++ b/windows-driver-docs-pr/usbcon/faq--usb-type-c-connector-on-a-windows-system.md @@ -1,6 +1,7 @@ --- Description: Frequently asked questions for OEMs who want to build Windows systems with USB Type-C connectors. title: FAQ - USB Type-C connector on a Windows system +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/function-controller-bringup-for-a-usb-type-c-system.md b/windows-driver-docs-pr/usbcon/function-controller-bringup-for-a-usb-type-c-system.md index ed2372ac58..b82fd11a40 100644 --- a/windows-driver-docs-pr/usbcon/function-controller-bringup-for-a-usb-type-c-system.md +++ b/windows-driver-docs-pr/usbcon/function-controller-bringup-for-a-usb-type-c-system.md @@ -1,6 +1,7 @@ --- Description: The driver for the function controller informs the operating system about the charging levels that its USB Type-C connector supports and notifies the battery subsystem when it can begin charging and the maximum amount of current the device can draw. title: Bring up the function controller on a USB Type-C Windows system +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/get-started-with-host-controller-driver-development.md b/windows-driver-docs-pr/usbcon/get-started-with-host-controller-driver-development.md index c6ca8ef21e..712591e845 100644 --- a/windows-driver-docs-pr/usbcon/get-started-with-host-controller-driver-development.md +++ b/windows-driver-docs-pr/usbcon/get-started-with-host-controller-driver-development.md @@ -1,6 +1,7 @@ --- Description: This section introduces you to high-level concepts and tasks for host driver development. title: Architecture of USB host controller extension (UCX) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/getting-set-up-to-use-windows-devices-usb.md b/windows-driver-docs-pr/usbcon/getting-set-up-to-use-windows-devices-usb.md index 8ce17d621e..4d234b4820 100644 --- a/windows-driver-docs-pr/usbcon/getting-set-up-to-use-windows-devices-usb.md +++ b/windows-driver-docs-pr/usbcon/getting-set-up-to-use-windows-devices-usb.md @@ -126,7 +126,7 @@ HRESULT result = WinUsb_QueryInterfaceSettings(DeviceData->WinusbHandle, 0, - &usbInterface); + &usbInterface); if (result == FALSE) { @@ -142,7 +142,7 @@ HRESULT DeviceData->WinusbHandle, 1, (UCHAR) i, - &pipe); + &pipe); if (result == FALSE) { @@ -152,7 +152,7 @@ HRESULT return hr; } - if ((pipe.PipeType == UsbdPipeTypeIsochronous) && (!(pipe.PipeId == 0x80))) + if ((pipe.PipeType == UsbdPipeTypeIsochronous) && (!(pipe.PipeId == 0x80))) { DeviceData->IsochOutPipe = pipe.PipeId; } @@ -210,7 +210,7 @@ typedef struct _DEVICE_DATA { ... -if ((pipe.PipeType == UsbdPipeTypeIsochronous) && (!(pipe.PipeId == 0x80))) +if ((pipe.PipeType == UsbdPipeTypeIsochronous) && (!(pipe.PipeId == 0x80))) { DeviceData->IsochOutPipe = pipe.PipeId; @@ -346,7 +346,7 @@ VOID DeviceData->IsochOutPipe, writeBuffer, totalTransferSize, - &isochWriteBufferHandle); + &isochWriteBufferHandle); if (!result) { @@ -356,8 +356,8 @@ VOID result = WinUsb_GetCurrentFrameNumber( DeviceData->WinusbHandle, - &frameNumber, - &timeStamp); + &frameNumber, + &timeStamp); if (!result) { @@ -377,7 +377,7 @@ VOID DeviceData->IsochOutTransferSize * i, DeviceData->IsochOutTransferSize, (i == 0) ? FALSE : TRUE, - &overlapped[i]); + &overlapped[i]); printf(_T("Write transfer sent by using ASAP flag.\n")); } @@ -390,8 +390,8 @@ VOID isochWriteBufferHandle, i * DeviceData->IsochOutTransferSize, DeviceData->IsochOutTransferSize, - &startFrame, - &overlapped[i]); + &startFrame, + &overlapped[i]); printf("Next transfer frame %d.\n", startFrame); @@ -412,8 +412,8 @@ VOID { result = WinUsb_GetOverlappedResult( DeviceData->WinusbHandle, - &overlapped[i], - &numBytes, + &overlapped[i], + &numBytes, TRUE); if (!result) @@ -554,7 +554,7 @@ VOID DeviceData->IsochInPipe, readBuffer, DeviceData->IsochInTransferSize * ISOCH_TRANSFER_COUNT, - &isochReadBufferHandle); + &isochReadBufferHandle); if (!result) { @@ -564,8 +564,8 @@ VOID result = WinUsb_GetCurrentFrameNumber( DeviceData->WinusbHandle, - &frameNumber, - &timeStamp); + &frameNumber, + &timeStamp); if (!result) { @@ -585,8 +585,8 @@ VOID DeviceData->IsochInTransferSize, (i == 0) ? FALSE : TRUE, DeviceData->IsochInPacketCount, - &isochPackets[i * DeviceData->IsochInPacketCount], - &overlapped[i]); + &isochPackets[i * DeviceData->IsochInPacketCount], + &overlapped[i]); printf(_T("Read transfer sent by using ASAP flag.\n")); @@ -600,10 +600,10 @@ VOID isochReadBufferHandle, DeviceData->IsochInTransferSize * i, DeviceData->IsochInTransferSize, - &startFrame, + &startFrame, DeviceData->IsochInPacketCount, - &isochPackets[i * DeviceData->IsochInPacketCount], - &overlapped[i]); + &isochPackets[i * DeviceData->IsochInPacketCount], + &overlapped[i]); printf("Next transfer frame %d.\n", startFrame); @@ -624,8 +624,8 @@ VOID { result = WinUsb_GetOverlappedResult( DeviceData->WinusbHandle, - &overlapped[i], - &numBytes, + &overlapped[i], + &numBytes, TRUE); if (!result) diff --git a/windows-driver-docs-pr/usbcon/handling-i-o-requests-in-a-host-controller-driver.md b/windows-driver-docs-pr/usbcon/handling-i-o-requests-in-a-host-controller-driver.md index 1df90aa8e6..bee8f53243 100644 --- a/windows-driver-docs-pr/usbcon/handling-i-o-requests-in-a-host-controller-driver.md +++ b/windows-driver-docs-pr/usbcon/handling-i-o-requests-in-a-host-controller-driver.md @@ -1,6 +1,7 @@ --- Description: Best practices for a host controller driver for handling I/O requests sent by UCX. title: Handle I/O requests in a USB host controller driver +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/hardware-design-of-a-usb-type-c-system.md b/windows-driver-docs-pr/usbcon/hardware-design-of-a-usb-type-c-system.md index 6fc902df56..6cb1dc57af 100644 --- a/windows-driver-docs-pr/usbcon/hardware-design-of-a-usb-type-c-system.md +++ b/windows-driver-docs-pr/usbcon/hardware-design-of-a-usb-type-c-system.md @@ -1,6 +1,7 @@ --- Description: Here are some example designs for USB Type-C system. title: Hardware design of USB Type-C systems +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to--implement-remote-and-function-wake-support.md b/windows-driver-docs-pr/usbcon/how-to--implement-remote-and-function-wake-support.md index e6e8546327..4d479927cb 100644 --- a/windows-driver-docs-pr/usbcon/how-to--implement-remote-and-function-wake-support.md +++ b/windows-driver-docs-pr/usbcon/how-to--implement-remote-and-function-wake-support.md @@ -116,7 +116,7 @@ SendRequestForRemoteWakeNotification( nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL; nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION; - nextStack->Parameters.Others.Argument1 = &remoteWake; + nextStack->Parameters.Others.Argument1 = &remoteWake; // Caller's completion routine will free the IRP when it completes. @@ -179,7 +179,7 @@ VOID PIO_STACK_LOCATION nextStack; NTSTATUS status; - status = USBD_UrbAllocate(parentFdoExt->usbdHandle, &urb); + status = USBD_UrbAllocate(parentFdoExt->usbdHandle, &urb); if (!NT_SUCCESS(status)) { diff --git a/windows-driver-docs-pr/usbcon/how-to-connect-to-a-usb-device--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-connect-to-a-usb-device--windows-store-app-.md index 31dedd734d..c04900dd49 100644 --- a/windows-driver-docs-pr/usbcon/how-to-connect-to-a-usb-device--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-connect-to-a-usb-device--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: In Windows 8.1, you can write a Windows Store app that interacts with a USB device. title: How to connect to a USB device (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-get-usb-descriptors--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-get-usb-descriptors--windows-store-app-.md index e867a152a9..5d7b84b2e5 100644 --- a/windows-driver-docs-pr/usbcon/how-to-get-usb-descriptors--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-get-usb-descriptors--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: One of the main tasks of interacting with a USB device is to get information about it. title: How to get USB descriptors (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-get-usb-pipe-handles.md b/windows-driver-docs-pr/usbcon/how-to-get-usb-pipe-handles.md index 6e924af9b5..a92417824f 100644 --- a/windows-driver-docs-pr/usbcon/how-to-get-usb-pipe-handles.md +++ b/windows-driver-docs-pr/usbcon/how-to-get-usb-pipe-handles.md @@ -167,12 +167,12 @@ NTSTATUS // Enumerate the pipes and get pipe information for each pipe. for (i = 0; i < pDeviceContext->NumberConfiguredPipes; i++) { - WDF_USB_PIPE_INFORMATION_INIT(&pipeInfo); + WDF_USB_PIPE_INFORMATION_INIT(&pipeInfo); pipe = WdfUsbInterfaceGetConfiguredPipe( pDeviceContext->UsbInterface, i, - &pipeInfo); + &pipeInfo); if (pipe == NULL) { @@ -186,7 +186,7 @@ NTSTATUS // Use the endpoint as an IN bulk endpoint. // Store the maximum packet size. - if ((WdfUsbPipeTypeBulk == pipeInfo.PipeType) && + if ((WdfUsbPipeTypeBulk == pipeInfo.PipeType) && WdfUsbTargetPipeIsInEndpoint (pipe)) { @@ -197,7 +197,7 @@ NTSTATUS Device, pipe); - if ((pipeContext->IsStreamsCapable) && + if ((pipeContext->IsStreamsCapable) && (pipeContext->MaxStreamsSupported > 0)) { status = OpenStreams ( @@ -230,7 +230,7 @@ NTSTATUS continue; } - if ((WdfUsbPipeTypeBulk == pipeInfo.PipeType) && + if ((WdfUsbPipeTypeBulk == pipeInfo.PipeType) && WdfUsbTargetPipeIsOutEndpoint (pipe)) { // Check if this is a streams IN endpoint. If it is, @@ -240,7 +240,7 @@ NTSTATUS Device, pipe); - if ((pipeContext->IsStreamsCapable) && + if ((pipeContext->IsStreamsCapable) && (pipeContext->MaxStreamsSupported > 0)) { status = OpenStreams ( @@ -273,7 +273,7 @@ NTSTATUS continue; } - if ((WdfUsbPipeTypeInterrupt == pipeInfo.PipeType) && + if ((WdfUsbPipeTypeInterrupt == pipeInfo.PipeType) && WdfUsbTargetPipeIsInEndpoint (pipe)) { pDeviceContext->InterruptPipe = pipe; @@ -348,8 +348,8 @@ VOID RetrieveStreamInfoFromEndpointDesc ( // Get the configuration descriptor of the currently selected configuration status = FX3RetrieveConfigurationDescriptor ( deviceContext->UsbDevice, - &deviceContext->ConfigurationNumber, - &configDescriptor); + &deviceContext->ConfigurationNumber, + &configDescriptor); if (!NT_SUCCESS (status)) { @@ -371,8 +371,8 @@ VOID RetrieveStreamInfoFromEndpointDesc ( } // Get the Endpoint Address of the pipe - WDF_USB_PIPE_INFORMATION_INIT(&pipeInfo); - WdfUsbTargetPipeGetInformation (Pipe, &pipeInfo); + WDF_USB_PIPE_INFORMATION_INIT(&pipeInfo); + WdfUsbTargetPipeGetInformation (Pipe, &pipeInfo); // Parse the ConfigurationDescriptor (including all Interface and @@ -607,7 +607,7 @@ HRESULT CMyDevice::CreateUsbIoTargets() WUDF_TEST_DRIVER_ASSERT(1 == NumInterfaces); - hr = pIUsbTargetDevice->RetrieveUsbInterface(0, &pIUsbInterface); + hr = pIUsbTargetDevice->RetrieveUsbInterface(0, &pIUsbInterface); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -646,7 +646,7 @@ HRESULT CMyDevice::CreateUsbIoTargets() for (UCHAR PipeIndex = 0; PipeIndex < NumEndPoints; PipeIndex++) { hr = pIUsbInterface->RetrieveUsbPipeObject(PipeIndex, - &pIUsbPipe); + &pIUsbPipe); if (FAILED(hr)) { @@ -674,7 +674,7 @@ HRESULT CMyDevice::CreateUsbIoTargets() pIUsbPipe->DeleteWdfObject(); } } - else if ( pIUsbPipe->IsOutEndPoint() && (UsbdPipeTypeBulk == pIUsbPipe->GetType()) ) + else if ( pIUsbPipe->IsOutEndPoint() && (UsbdPipeTypeBulk == pIUsbPipe->GetType()) ) { m_pIUsbOutputPipe = pIUsbPipe; } diff --git a/windows-driver-docs-pr/usbcon/how-to-open-streams-in-a-usb-endpoint.md b/windows-driver-docs-pr/usbcon/how-to-open-streams-in-a-usb-endpoint.md index a00514ba84..7849ba6fef 100644 --- a/windows-driver-docs-pr/usbcon/how-to-open-streams-in-a-usb-endpoint.md +++ b/windows-driver-docs-pr/usbcon/how-to-open-streams-in-a-usb-endpoint.md @@ -264,8 +264,8 @@ NTSTATUS status = WdfUsbTargetDeviceCreateUrb ( deviceContext->UsbDevice, NULL, - &urbMemory, - &urb); + &urbMemory, + &urb); if (status != STATUS_SUCCESS) { diff --git a/windows-driver-docs-pr/usbcon/how-to-retrieve-information-about-a-usb-device.md b/windows-driver-docs-pr/usbcon/how-to-retrieve-information-about-a-usb-device.md index 22456af037..c1523d8b95 100644 --- a/windows-driver-docs-pr/usbcon/how-to-retrieve-information-about-a-usb-device.md +++ b/windows-driver-docs-pr/usbcon/how-to-retrieve-information-about-a-usb-device.md @@ -1,6 +1,7 @@ --- Description: This topic describes the USB hardware verifier tool (USB3HWVerifierAnalyzer.exe) that is used for testing and debugging specific hardware events. title: USB hardware verifier (USB3HWVerifierAnalyzer.exe) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-run-bios-uefi-testing-with-the-mutt-device.md b/windows-driver-docs-pr/usbcon/how-to-run-bios-uefi-testing-with-the-mutt-device.md index 518eda5fa9..5da2316ca9 100644 --- a/windows-driver-docs-pr/usbcon/how-to-run-bios-uefi-testing-with-the-mutt-device.md +++ b/windows-driver-docs-pr/usbcon/how-to-run-bios-uefi-testing-with-the-mutt-device.md @@ -1,6 +1,7 @@ --- Description: BIOS/UEFI testing validates USB boot and handoff of the controller to the operating system. title: BIOS/UEFI testing with the MUTT devices +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-select-a-configuration-for-a-usb-device.md b/windows-driver-docs-pr/usbcon/how-to-select-a-configuration-for-a-usb-device.md index d839cffa48..f4a511b67a 100644 --- a/windows-driver-docs-pr/usbcon/how-to-select-a-configuration-for-a-usb-device.md +++ b/windows-driver-docs-pr/usbcon/how-to-select-a-configuration-for-a-usb-device.md @@ -178,7 +178,7 @@ NTSTATUS SelectConfiguration (PDEVICE_OBJECT DeviceObject, deviceExtension->UsbdHandle, ConfigurationDescriptor, interfaceList, - &urb); + &urb); if(!NT_SUCCESS(ntStatus)) { @@ -221,11 +221,11 @@ NTSTATUS SelectConfiguration (PDEVICE_OBJECT DeviceObject, { deviceExtension->InterruptPipe = pipeHandle; } - if (Interface->Pipes[i].PipeType == UsbdPipeTypeBulk && USB_ENDPOINT_DIRECTION_IN (Interface->Pipes[i].EndpointAddress)) + if (Interface->Pipes[i].PipeType == UsbdPipeTypeBulk && USB_ENDPOINT_DIRECTION_IN (Interface->Pipes[i].EndpointAddress)) { deviceExtension->BulkInPipe = pipeHandle; } - if (Interface->Pipes[i].PipeType == UsbdPipeTypeBulk && USB_ENDPOINT_DIRECTION_OUT (Interface->Pipes[i].EndpointAddress)) + if (Interface->Pipes[i].PipeType == UsbdPipeTypeBulk && USB_ENDPOINT_DIRECTION_OUT (Interface->Pipes[i].EndpointAddress)) { deviceExtension->BulkOutPipe = pipeHandle; } @@ -280,7 +280,7 @@ To disable a USB device, create and submit a select-configuration request with a ```ManagedCPlusPlus URB Urb; UsbBuildSelectConfigurationRequest( - &Urb, + &Urb, sizeof(_URB_SELECT_CONFIGURATION), NULL ); diff --git a/windows-driver-docs-pr/usbcon/how-to-select-a-usb-interface-setting--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-select-a-usb-interface-setting--windows-store-app-.md index a0e2722f32..2df56fd54d 100644 --- a/windows-driver-docs-pr/usbcon/how-to-select-a-usb-interface-setting--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-select-a-usb-interface-setting--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: Use the UsbInterfaceSetting object to get the current setting and set a setting in the interface. title: How to select a USB interface setting (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-bulk-transfer--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-bulk-transfer--windows-store-app-.md index 74f0d3ba78..8794fc9167 100644 --- a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-bulk-transfer--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-bulk-transfer--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: Learn about a USB bulk transfer and how to initiate a transfer request from your Windows Store app that communicates with a USB device. title: How to send a USB bulk transfer request (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-control-transfer--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-control-transfer--windows-store-app-.md index ee28719715..f22efc7c8a 100644 --- a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-control-transfer--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-control-transfer--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: An app that communicates with a USB device usually sends several control transfers requests. title: How to send a USB control transfer (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-interrupt-transfer--windows-store-app-.md b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-interrupt-transfer--windows-store-app-.md index 188cf9ca99..858395f6b3 100644 --- a/windows-driver-docs-pr/usbcon/how-to-send-a-usb-interrupt-transfer--windows-store-app-.md +++ b/windows-driver-docs-pr/usbcon/how-to-send-a-usb-interrupt-transfer--windows-store-app-.md @@ -1,6 +1,7 @@ --- Description: A USB device can support interrupt endpoints so that it can send or receive data at regular intervals. title: How to send a USB interrupt transfer request (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/how-to-use-the-continous-reader-for-getting-data-from-a-usb-endpoint--umdf-.md b/windows-driver-docs-pr/usbcon/how-to-use-the-continous-reader-for-getting-data-from-a-usb-endpoint--umdf-.md index 23b62bb341..81110a4b4b 100644 --- a/windows-driver-docs-pr/usbcon/how-to-use-the-continous-reader-for-getting-data-from-a-usb-endpoint--umdf-.md +++ b/windows-driver-docs-pr/usbcon/how-to-use-the-continous-reader-for-getting-data-from-a-usb-endpoint--umdf-.md @@ -92,7 +92,7 @@ Instructions pipeContext = GetPipeContext (Pipe); WDF_USB_CONTINUOUS_READER_CONFIG_INIT( - &readerConfig, + &readerConfig, FX3EvtReadComplete, pDeviceContext, pipeContext->MaxPacketSize); @@ -102,7 +102,7 @@ Instructions status = WdfUsbTargetPipeConfigContinuousReader( Pipe, - &readerConfig); + &readerConfig); if (!NT_SUCCESS (status)) { @@ -304,21 +304,21 @@ HRESULT CDeviceCallback::ConfigureContinuousReader (IWDFUsbTargetPipe* pFxPipe) // Set up the continuous reader to read from the target pipe object. //Get a pointer to the target pipe2 object. - hr = pFxPipe->QueryInterface(IID_PPV_ARGS(&pFxUsbPipe2)); + hr = pFxPipe->QueryInterface(IID_PPV_ARGS(&pFxUsbPipe2)); if (FAILED(hr)) { goto ConfigureContinuousReaderExit; } //Get a pointer to the completion callback. - hr = QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback)); + hr = QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback)); if (FAILED(hr)) { goto ConfigureContinuousReaderExit; } //Get a pointer to the failure callback. - hr = QueryInterface(IID_PPV_ARGS(&pOnFailureCallback)); + hr = QueryInterface(IID_PPV_ARGS(&pOnFailureCallback)); if (FAILED(hr)) { goto ConfigureContinuousReaderExit; @@ -419,15 +419,15 @@ The following example code shows how to get a pointer to the IWDFIoTargetStateMa for (UCHAR index = 0; index < NumEndpoints; index++) { - hr = pFxInterface->RetrieveUsbPipeObject(index, &pFxPipe); + hr = pFxInterface->RetrieveUsbPipeObject(index, &pFxPipe); - if (SUCCEEDED (hr) && pFxPipe) + if (SUCCEEDED (hr) && pFxPipe) { - if ((pFxPipe->IsInEndPoint()) && (pFxPipe->GetType()==UsbdPipeTypeInterrupt)) + if ((pFxPipe->IsInEndPoint()) && (pFxPipe->GetType()==UsbdPipeTypeInterrupt)) { //Pipe is for an interrupt IN endpoint. - hr = pFxPipe->QueryInterface(IID_PPV_ARGS(&m_pFxIoTargetInterruptPipeStateMgmt)); + hr = pFxPipe->QueryInterface(IID_PPV_ARGS(&m_pFxIoTargetInterruptPipeStateMgmt)); if (m_pFxIoTargetInterruptPipeStateMgmt) { @@ -616,7 +616,7 @@ The following example code shows how to get data from the buffer returned by [** if (pBuff) { - CopyMemory(&CurrentData, pBuff, sizeof(CurrentData)); + CopyMemory(&CurrentData, pBuff, sizeof(CurrentData)); sprintf_s(data, 20, "%d\n", CurrentData); OutputDebugString(data); pBuff = NULL; diff --git a/windows-driver-docs-pr/usbcon/how-to-write-a-windows-desktop-app-that-communicates-with-a-usb-device.md b/windows-driver-docs-pr/usbcon/how-to-write-a-windows-desktop-app-that-communicates-with-a-usb-device.md index b5248acaed..19d653172d 100644 --- a/windows-driver-docs-pr/usbcon/how-to-write-a-windows-desktop-app-that-communicates-with-a-usb-device.md +++ b/windows-driver-docs-pr/usbcon/how-to-write-a-windows-desktop-app-that-communicates-with-a-usb-device.md @@ -229,7 +229,7 @@ Return value: // // Enumerate all devices exposing the interface // - deviceInfo = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USBApplication1, + deviceInfo = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USBApplication1, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE); @@ -247,16 +247,16 @@ Return value: // bResult = SetupDiEnumDeviceInterfaces(deviceInfo, NULL, - &GUID_DEVINTERFACE_USBApplication1, + &GUID_DEVINTERFACE_USBApplication1, 0, - &interfaceData); + &interfaceData); if (FALSE == bResult) { // // We would see this error if no devices were found // - if (ERROR_NO_MORE_ITEMS == GetLastError() && + if (ERROR_NO_MORE_ITEMS == GetLastError() && NULL != FailureDeviceNotFound) { *FailureDeviceNotFound = TRUE; @@ -272,13 +272,13 @@ Return value: // We expect to get a failure with insufficient buffer // bResult = SetupDiGetDeviceInterfaceDetail(deviceInfo, - &interfaceData, + &interfaceData, NULL, 0, - &requiredLength, + &requiredLength, NULL); - if (FALSE == bResult && ERROR_INSUFFICIENT_BUFFER != GetLastError()) { + if (FALSE == bResult && ERROR_INSUFFICIENT_BUFFER != GetLastError()) { hr = HRESULT_FROM_WIN32(GetLastError()); SetupDiDestroyDeviceInfoList(deviceInfo); @@ -305,10 +305,10 @@ Return value: // Get the interface's path string // bResult = SetupDiGetDeviceInterfaceDetail(deviceInfo, - &interfaceData, + &interfaceData, detailData, length, - &requiredLength, + &requiredLength, NULL); if(FALSE == bResult) @@ -424,7 +424,7 @@ Return value: } bResult = WinUsb_Initialize(DeviceData->DeviceHandle, - &DeviceData->WinusbHandle); + &DeviceData->WinusbHandle); if (FALSE == bResult) { diff --git a/windows-driver-docs-pr/usbcon/images/ConnexC.png b/windows-driver-docs-pr/usbcon/images/ConnexC.png index 805cf94bdd..365286ee23 100644 Binary files a/windows-driver-docs-pr/usbcon/images/ConnexC.png and b/windows-driver-docs-pr/usbcon/images/ConnexC.png differ diff --git a/windows-driver-docs-pr/usbcon/images/ConnexC.vsdx b/windows-driver-docs-pr/usbcon/images/ConnexC.vsdx index 25af1bd2f4..4fe96d4413 100644 Binary files a/windows-driver-docs-pr/usbcon/images/ConnexC.vsdx and b/windows-driver-docs-pr/usbcon/images/ConnexC.vsdx differ diff --git a/windows-driver-docs-pr/usbcon/images/tcpci-arch.png b/windows-driver-docs-pr/usbcon/images/tcpci-arch.png index 05ed1bdd73..d78c31c0af 100644 Binary files a/windows-driver-docs-pr/usbcon/images/tcpci-arch.png and b/windows-driver-docs-pr/usbcon/images/tcpci-arch.png differ diff --git a/windows-driver-docs-pr/usbcon/images/~$$tcpci-arch.~vsdx b/windows-driver-docs-pr/usbcon/images/~$$tcpci-arch.~vsdx index d129d082f9..0dbb54e0db 100644 Binary files a/windows-driver-docs-pr/usbcon/images/~$$tcpci-arch.~vsdx and b/windows-driver-docs-pr/usbcon/images/~$$tcpci-arch.~vsdx differ diff --git a/windows-driver-docs-pr/usbcon/implement-driver-entry-for-a-usb-driver--umdf-.md b/windows-driver-docs-pr/usbcon/implement-driver-entry-for-a-usb-driver--umdf-.md index 592863137a..8da088b9b9 100644 --- a/windows-driver-docs-pr/usbcon/implement-driver-entry-for-a-usb-driver--umdf-.md +++ b/windows-driver-docs-pr/usbcon/implement-driver-entry-for-a-usb-driver--umdf-.md @@ -1,6 +1,7 @@ --- Description: Use the USB User-Mode Driver template provided with Microsoft Visual Studio to write a UMDF client driver. title: How to write your first USB client driver (UMDF) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/index.md b/windows-driver-docs-pr/usbcon/index.md index 2269d5a15c..bd816b3f91 100644 --- a/windows-driver-docs-pr/usbcon/index.md +++ b/windows-driver-docs-pr/usbcon/index.md @@ -1,6 +1,7 @@ --- Description: Universal Serial Bus (USB) provides an expandable, hot-pluggable Plug and Play serial interface that ensures a standard, low-cost connection for peripheral devices such as keyboards, mice, joysticks, printers, scanners, storage devices, modems, and video conferencing cameras. Migration to USB is recommended for all peripheral devices that use legacy ports such as PS/2, serial, and parallel ports. The USB-IF is a Special Interest Groups (SIGs) that maintains the Official USB Specification, test specifications and tools. Windows operating systems include native support for USB host controllers, hubs, and devices and systems that comply with the official USB specification. Windows also provides programming interfaces that you can use to develop device drivers and applications that communicate with a USB device. title: Universal Serial Bus (USB) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -71,7 +72,7 @@ Windows operating systems include native support for USB host controllers, hubs, [Windows Store apps for USB devices](http://channel9.msdn.com/Events/Build/2013/3-924a) [Understanding USB 3.0 in Windows 8](http://channel9.msdn.com/events/BUILD/BUILD2011/HW-256T) [Building great USB 3.0 devices](http://channel9.msdn.com/events/BUILD/BUILD2011/HW-773T) -[USB Debugging Innovations in Windows 8 (Part I, II, & III)](http://channel9.msdn.com/events/BUILD/BUILD2011/HW-258P) +[USB Debugging Innovations in Windows 8 (Part I, II, & III)](http://channel9.msdn.com/events/BUILD/BUILD2011/HW-258P)

USB hardware for learning

[MUTT devices](microsoft-usb-test-tool--mutt--devices.md)

MUTT and SuperMUTT devices and the accompanying software package are integrated into the HCK suite of USB tests. They provide automated testing that can be used during the development cycle of USB controllers, devices and systems, especially stress testing.

diff --git a/windows-driver-docs-pr/usbcon/introduction-to-usb-type-c-connectors.md b/windows-driver-docs-pr/usbcon/introduction-to-usb-type-c-connectors.md index 5fcbb412d6..334ce30c68 100644 --- a/windows-driver-docs-pr/usbcon/introduction-to-usb-type-c-connectors.md +++ b/windows-driver-docs-pr/usbcon/introduction-to-usb-type-c-connectors.md @@ -1,6 +1,7 @@ --- Description: Possible causes and resolutions to troubleshooting messages in Windows 10 that users might get on USB Type-C systems running Windows. title: Troubleshoot messages for a USB Type-C Windows system +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/limitations-of-usb-2-0-mechanism.md b/windows-driver-docs-pr/usbcon/limitations-of-usb-2-0-mechanism.md index 0265106bcf..c9c9ffc322 100644 --- a/windows-driver-docs-pr/usbcon/limitations-of-usb-2-0-mechanism.md +++ b/windows-driver-docs-pr/usbcon/limitations-of-usb-2-0-mechanism.md @@ -1,6 +1,7 @@ --- Description: Describes the limitations of the Universal Serial Bus (USB) 2.0 Selective Suspend mechanism. title: Limitations of USB 2.0 mechanism +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/link-power-management-in-usb-3-0-hardware.md b/windows-driver-docs-pr/usbcon/link-power-management-in-usb-3-0-hardware.md index d4d9a7ad6b..497ed9cf8c 100644 --- a/windows-driver-docs-pr/usbcon/link-power-management-in-usb-3-0-hardware.md +++ b/windows-driver-docs-pr/usbcon/link-power-management-in-usb-3-0-hardware.md @@ -1,6 +1,7 @@ --- Description: This section provides information about certain limitations of the Universal Serial Bus (USB) 2.0 Selective Suspend mechanism. title: Link power management in USB 3.0 hardware +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/microsoft-defined-usb-frameworks.md b/windows-driver-docs-pr/usbcon/microsoft-defined-usb-frameworks.md index 08006adc26..2f27084e7b 100644 --- a/windows-driver-docs-pr/usbcon/microsoft-defined-usb-frameworks.md +++ b/windows-driver-docs-pr/usbcon/microsoft-defined-usb-frameworks.md @@ -1,6 +1,7 @@ --- Description: This topic describes the Microsoft-provided driver framework for USB devices that do not have their own USB device class specification. title: Microsoft-Defined USB Driver Frameworks +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/microsoft-usb-test-tool--mutt--devices.md b/windows-driver-docs-pr/usbcon/microsoft-usb-test-tool--mutt--devices.md index 63ed195390..5474ee0760 100644 --- a/windows-driver-docs-pr/usbcon/microsoft-usb-test-tool--mutt--devices.md +++ b/windows-driver-docs-pr/usbcon/microsoft-usb-test-tool--mutt--devices.md @@ -1,6 +1,7 @@ --- Description: The Microsoft USB Test Tool (MUTT) is collection of devices for testing interoperability of your USB hardware with the Microsoft USB driver stack. title: Microsoft USB Test Tool (MUTT) devices +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -41,7 +42,7 @@ To communicate with MUTT devices, you need the MUTT software package. This packa DR MUTT [JJG Technologies]( http://go.microsoft.com/fwlink/p/?linkid=618287) -MUTT ConnEx-C +USB Type-C ConnEx [MCCI](http://go.microsoft.com/fwlink/p/?LinkId=733488) [JJG Technologies]( http://go.microsoft.com/fwlink/p/?linkid=618287) @@ -124,12 +125,12 @@ The SuperMUTT Pack is two devices in one. It is a USB 3.0 hub with a Cypress FX2 The DR MUTT acts like a SuperMutt when testing host mode of the device under test, but it can also switch to host mode to test the function mode of the device under test. -## MUTT ConnEx-C +## USB Type-C ConnEx -The MUTT Connection Exerciser for USB Type-C (MUTT ConnEx-C) is a custom shield that has a four-to-one switch to automate USB Type-C interoperability scenarios. The shield has been designed to work with Arduino as the microcontroller. For more information, see [Test USB Type-C systems with MUTT ConnEx-C](test-usb-type-c-systems-with-mutt-connex-c.md). +The MUTT Connection Exerciser for USB Type-C (USB Type-C ConnEx) is a custom shield that has a four-to-one switch to automate USB Type-C interoperability scenarios. The shield has been designed to work with Arduino as the microcontroller. For more information, see [Test USB Type-C systems with USB Type-C ConnEx](test-usb-type-c-systems-with-mutt-connex-c.md). -![mutt connex-c](images/connexc-side.jpg) +![USB Type-C ConnEx](images/connexc-side.jpg) ## Related topics [USB](https://msdn.microsoft.com/library/windows/hardware/ff538930) diff --git a/windows-driver-docs-pr/usbcon/oem-tasks-for-bringing-up-a-usb-typec.md b/windows-driver-docs-pr/usbcon/oem-tasks-for-bringing-up-a-usb-typec.md index 3c25a8c932..e0c9d4b01f 100644 --- a/windows-driver-docs-pr/usbcon/oem-tasks-for-bringing-up-a-usb-typec.md +++ b/windows-driver-docs-pr/usbcon/oem-tasks-for-bringing-up-a-usb-typec.md @@ -1,6 +1,7 @@ --- Description: Windows support for USB Type-C connector and tasks for OEMs who are building USB Type-C systems. title: Windows support for USB Type-C connectors +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -91,7 +92,7 @@ The USB Type-C connector, introduced by the USB-IF, defined in the USB 3.1 speci Test
  • Perform various functional and stress tests on systems and devices that expose a USB Type-C connector.

    -

    [Test USB Type-C systems with MUTT ConnEx-C](test-usb-type-c-systems-with-mutt-connex-c.md)

  • +

    [Test USB Type-C systems with USB Type-C ConnEx](test-usb-type-c-systems-with-mutt-connex-c.md)

  • Run USB tests included in the Windows Hardware Lab Kit (HLK) for Windows 10.
    Note  Run USB function HLK tests with a C-to-A cable (searc for "Windows USB Device" in the HLK search box. diff --git a/windows-driver-docs-pr/usbcon/oem-tasks-for-usb-type-c-systems-running-windows.md b/windows-driver-docs-pr/usbcon/oem-tasks-for-usb-type-c-systems-running-windows.md index ff4edd4e95..ef2bdca66f 100644 --- a/windows-driver-docs-pr/usbcon/oem-tasks-for-usb-type-c-systems-running-windows.md +++ b/windows-driver-docs-pr/usbcon/oem-tasks-for-usb-type-c-systems-running-windows.md @@ -1,6 +1,7 @@ --- Description: This table describes the use cases is supported by Windows 10, and the additional tasks OEMs must perform for those use case to work. title: OEM tasks for USB Type-C systems +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/querying-for-usb-interfaces.md b/windows-driver-docs-pr/usbcon/querying-for-usb-interfaces.md index ef61b01af2..b2df4280b8 100644 --- a/windows-driver-docs-pr/usbcon/querying-for-usb-interfaces.md +++ b/windows-driver-docs-pr/usbcon/querying-for-usb-interfaces.md @@ -46,7 +46,7 @@ To get a bus driver interface, the client driver must send an [**IRP\_MN\_QUERY\ 4. Initialize the IRP stack with the appropriate interface GUID, the size of the interface, and the version of the interface. ``` - irpstack->Parameters.QueryInterface.InterfaceType = &USB_BUS_INTERFACE_USBDI_GUID; + irpstack->Parameters.QueryInterface.InterfaceType = &USB_BUS_INTERFACE_USBDI_GUID; irpstack->Parameters.QueryInterface.Size = sizeof(USB_BUS_INTERFACE_USBDI_V0); irpstack->Parameters.QueryInterface.Version = USB_BUSIF_USBDI_VERSION_0; ntStatus = IoCallDriver(PDO that the client passes URBs to, irp); diff --git a/windows-driver-docs-pr/usbcon/register-a-composite-driver.md b/windows-driver-docs-pr/usbcon/register-a-composite-driver.md index 165d01f760..02e1fadde6 100644 --- a/windows-driver-docs-pr/usbcon/register-a-composite-driver.md +++ b/windows-driver-docs-pr/usbcon/register-a-composite-driver.md @@ -70,13 +70,13 @@ VOID RegisterCompositeDriver(PPARENT_FDO_EXT parentFdoExt) buffer = NULL; - COMPOSITE_DRIVER_CAPABILITIES_INIT(&capabilities); + COMPOSITE_DRIVER_CAPABILITIES_INIT(&capabilities); capabilities.CapabilityFunctionSuspend = 1; USBD_BuildRegisterCompositeDriver(parentFdoExt->usbdHandle, capabilities, parentFdoExt->numFunctions, - &registerInfo); + ®isterInfo); irp = IoAllocateIrp(parentFdoExt->topDevObj->StackSize, FALSE); @@ -104,7 +104,7 @@ VOID RegisterCompositeDriver(PPARENT_FDO_EXT parentFdoExt) nextSp->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DRIVER; //Set the input buffer in Argument1 - nextSp->Parameters.Others.Argument1 = &registerInfo; + nextSp->Parameters.Others.Argument1 = ®isterInfo; //Set the output buffer in SystemBuffer field for USBD_FUNCTION_HANDLE. irp->AssociatedIrp.SystemBuffer = buffer; diff --git a/windows-driver-docs-pr/usbcon/select-a-usb-alternate-setting.md b/windows-driver-docs-pr/usbcon/select-a-usb-alternate-setting.md index d74ee1293a..ba1b5194df 100644 --- a/windows-driver-docs-pr/usbcon/select-a-usb-alternate-setting.md +++ b/windows-driver-docs-pr/usbcon/select-a-usb-alternate-setting.md @@ -106,16 +106,16 @@ NTSTATUS FX3SelectInterfaceSetting( goto Exit; } - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&pipeAttributes, PIPE_CONTEXT); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&pipeAttributes, PIPE_CONTEXT); pipeAttributes.EvtCleanupCallback = FX3EvtPipeContextCleanup; - WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING (&settingParams, SettingIndex); + WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING (&settingParams, SettingIndex); status = WdfUsbInterfaceSelectSetting ( pDeviceContext->UsbInterface, - &pipeAttributes, - &settingParams); + &pipeAttributes, + &settingParams); if (status != STATUS_SUCCESS) { diff --git a/windows-driver-docs-pr/usbcon/selecting-the-configuration-for-a-multiple-interface--composite--usb-d.md b/windows-driver-docs-pr/usbcon/selecting-the-configuration-for-a-multiple-interface--composite--usb-d.md index 7235592f03..232f08eb63 100644 --- a/windows-driver-docs-pr/usbcon/selecting-the-configuration-for-a-multiple-interface--composite--usb-d.md +++ b/windows-driver-docs-pr/usbcon/selecting-the-configuration-for-a-multiple-interface--composite--usb-d.md @@ -1,6 +1,7 @@ --- Description: This topic provides information about registry settings that configure the way Usbccgp.sys selects a USB configuration. title: Configuring Usbccgp.sys to Select a Non-Default USB Configuration +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/selective-suspend-in-a-kmdf-function-driver.md b/windows-driver-docs-pr/usbcon/selective-suspend-in-a-kmdf-function-driver.md index 7ee7670e82..3309524354 100644 --- a/windows-driver-docs-pr/usbcon/selective-suspend-in-a-kmdf-function-driver.md +++ b/windows-driver-docs-pr/usbcon/selective-suspend-in-a-kmdf-function-driver.md @@ -108,11 +108,11 @@ NTSTATUS status = STATUS_SUCCESS; // // Initialize the idle policy structure. // -WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(&idleSettings, +WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(&idleSettings, IdleUsbSelectiveSuspend); idleSettings.IdleTimeout = 10000; // 10 sec -status = WdfDeviceAssignS0IdleSettings(Device, &idleSettings); +status = WdfDeviceAssignS0IdleSettings(Device, &idleSettings); if ( !NT_SUCCESS(status)) { TraceEvents(TRACE_LEVEL_ERROR, DBG_PNP, "WdfDeviceSetPowerPolicyS0IdlePolicy failed %x\n", @@ -172,12 +172,12 @@ The following example from the Osrusbfx2 KMDF sample shows how to call this meth // capabilites such as speed, power, etc. // -WDF_USB_DEVICE_INFORMATION_INIT(&deviceInfo); +WDF_USB_DEVICE_INFORMATION_INIT(&deviceInfo); status = WdfUsbTargetDeviceRetrieveInformation( pDeviceContext->UsbDevice, - &deviceInfo); -waitWakeEnable = deviceInfo.Traits & WDF_USB_DEVICE_TRAIT_REMOTE_WAKE_CAPABLE; + &deviceInfo); +waitWakeEnable = deviceInfo.Traits & WDF_USB_DEVICE_TRAIT_REMOTE_WAKE_CAPABLE; ``` ### Enabling remote wakeup @@ -194,8 +194,8 @@ The following code snippet from the Osrusbfx2 sample shows how to initialize wak ``` WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS wakeSettings; -WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT(&wakeSettings); -status = WdfDeviceAssignSxWakeSettings(Device, &wakeSettings); +WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT(&wakeSettings); +status = WdfDeviceAssignSxWakeSettings(Device, &wakeSettings); if (!NT_SUCCESS(status)) { return status; } diff --git a/windows-driver-docs-pr/usbcon/selective-suspend-in-umdf-drivers.md b/windows-driver-docs-pr/usbcon/selective-suspend-in-umdf-drivers.md index 947069e05d..f0eace22f6 100644 --- a/windows-driver-docs-pr/usbcon/selective-suspend-in-umdf-drivers.md +++ b/windows-driver-docs-pr/usbcon/selective-suspend-in-umdf-drivers.md @@ -100,7 +100,7 @@ hr = m_FxDevice->CreateIoQueue( DispatchType, PowerManaged, FALSE, - &fxQueue + &fxQueue ); ``` @@ -177,7 +177,7 @@ A UMDF USB driver can enable USB selective suspend either at runtime or during i BOOL AutoSuspend = TRUE; hr = m_pIUsbTargetDevice->SetPowerPolicy( AUTO_SUSPEND, sizeof(BOOL), - (PVOID) &AutoSuspend ); + (PVOID) &AutoSuspend ); ``` - To enable support during installation, the INF includes an AddReg directive that adds the DefaultIdleState value to the device’s hardware key and sets the value to 1. For example: @@ -201,7 +201,7 @@ By default, WinUSB suspends the device after 5 seconds if no transfers are pendi value = 10 * 1000; hr = m_pIUsbTargetDevice->SetPowerPolicy( SUSPEND_DELAY, sizeof(ULONG), - (PVOID) &value ); + (PVOID) &value ); ``` **To provide user control of USB selective suspend** diff --git a/windows-driver-docs-pr/usbcon/selective-suspend-in-usb-drivers-wdf.md b/windows-driver-docs-pr/usbcon/selective-suspend-in-usb-drivers-wdf.md index 3e0f80cef3..355316d4b6 100644 --- a/windows-driver-docs-pr/usbcon/selective-suspend-in-usb-drivers-wdf.md +++ b/windows-driver-docs-pr/usbcon/selective-suspend-in-usb-drivers-wdf.md @@ -1,6 +1,7 @@ --- Description: A USB function driver supports runtime idle detection by implementing USB selective suspend. title: Selective suspend in USB drivers (WDF) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/send-requests-to-the-usb-driver-stack.md b/windows-driver-docs-pr/usbcon/send-requests-to-the-usb-driver-stack.md index 08e19d3e1b..ae8faf530b 100644 --- a/windows-driver-docs-pr/usbcon/send-requests-to-the-usb-driver-stack.md +++ b/windows-driver-docs-pr/usbcon/send-requests-to-the-usb-driver-stack.md @@ -88,12 +88,12 @@ NTSTATUS SubmitUrbSync( PDEVICE_EXTENSION DeviceExtension, // USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild. USBD_AssignUrbToIoStackLocation (DeviceExtension->UsbdHandle, nextStack, Urb); - KeInitializeEvent(&kEvent, NotificationEvent, FALSE); + KeInitializeEvent(&kEvent, NotificationEvent, FALSE); ntStatus = IoSetCompletionRoutineEx ( DeviceExtension->NextDeviceObject, Irp, SyncCompletionRoutine, - (PVOID) &kEvent, + (PVOID) &kEvent, TRUE, TRUE, TRUE); @@ -108,7 +108,7 @@ NTSTATUS SubmitUrbSync( PDEVICE_EXTENSION DeviceExtension, if (ntStatus == STATUS_PENDING) { - KeWaitForSingleObject ( &kEvent, + KeWaitForSingleObject ( &kEvent, Executive, KernelMode, FALSE, diff --git a/windows-driver-docs-pr/usbcon/support-for-interface-collections.md b/windows-driver-docs-pr/usbcon/support-for-interface-collections.md index 856918ec6e..696d4d1e5c 100644 --- a/windows-driver-docs-pr/usbcon/support-for-interface-collections.md +++ b/windows-driver-docs-pr/usbcon/support-for-interface-collections.md @@ -200,7 +200,7 @@ ExcludeFromSelect=* CompanyName=CompanyName [CompanyName] -%COMPANYNAME.DeviceDesc%=CCGPDriverInstall,USB\Vid_????&Pid_???? +%COMPANYNAME.DeviceDesc%=CCGPDriverInstall,USB\Vid_????&Pid_???? [CCGPDriverInstall.NT] Include=usb.inf @@ -285,14 +285,14 @@ USB Audio Device class interface collections that occur on CDC and WMCDC devices

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&MI_%02x
    -USB\Vid_%04x&Pid_%04x&MI_%02x
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&MI_%02x
    +USB\Vid_%04x&Pid_%04x&MI_%02x

    The hardware IDs for audio interface collections do not contain interface class-specific information. For an explanation of the formatting of hardware IDs that are associated with audio interface collections, see [Support for the Wireless Mobile Communication Device Class](support-for-the-wireless-mobile-communication-device-class--wmcdc-.md).

    Compatible IDs

    -
    USB\Class_01&SubClass_01&Prot_00
    -USB\Class_01&SubClass_01
    +
    USB\Class_01&SubClass_01&Prot_00
    +USB\Class_01&SubClass_01
     USB\Class_01

    The format of compatible IDs for audio interface collections contains embedded information about the interface class, interface subclass, and the protocol. For audio interface collections on a CDC or WMCDC device, the interface class is 01, the subclass is 01, and the protocol is 00.

    @@ -346,15 +346,15 @@ Interface collections that comply with the CDC specification have the following

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_02&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_02
    -USB\Vid_%04x&Pid_%04x&Cdc_02&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_02
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_02&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_02
    +USB\Vid_%04x&Pid_%04x&Cdc_02&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_02

    Compatible IDs

    -
    USB\Class_02&SubClass_02&Prot_%02X
    -USB\Class_02&SubClass_02
    +
    USB\Class_02&SubClass_02&Prot_%02X
    +USB\Class_02&SubClass_02
     USB\Class_02
    @@ -407,15 +407,15 @@ USB CDC ATM Networking Control Model (ANCM) interface collections have the follo

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07
    -USB\Vid_%04x&Pid_%04x&Cdc_07&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_07
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_07
    +USB\Vid_%04x&Pid_%04x&Cdc_07&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_07

    Compatible IDs

    -
    USB\Class_02&SubClass_07&Prot_00
    -USB\Class_02&SubClass_07
    +
    USB\Class_02&SubClass_07&Prot_00
    +USB\Class_02&SubClass_07
     USB\Class_02
    @@ -470,13 +470,13 @@ USB CDC Common ISDN API (CAPI) Control Model interface collections have the foll

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_05&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_05
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_05&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_05

    Compatible IDs

    -
    USB\Class_02&SubClass_05&Prot_00
    -USB\Class_02&SubClass_05
    +
    USB\Class_02&SubClass_05&Prot_00
    +USB\Class_02&SubClass_05

    Special handling

    @@ -528,15 +528,15 @@ USB CDC Direct Line Control Model (DLCM) interface collections have the followin

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01
    -USB\Vid_%04x&Pid_%04x&Cdc_01&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_01
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_01
    +USB\Vid_%04x&Pid_%04x&Cdc_01&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_01

    Compatible IDs

    -
    USB\Class_02&SubClass_01&Prot_00
    -USB\Class_02&SubClass_01
    +
    USB\Class_02&SubClass_01&Prot_00
    +USB\Class_02&SubClass_01
     USB\Class_02
    @@ -589,15 +589,15 @@ USB CDC Ethernet Networking Control Model (ENCM) interface collections have the

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_06&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_06
    -USB\Vid_%04x&Pid_%04x&Cdc_06&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_06
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_06&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_06
    +USB\Vid_%04x&Pid_%04x&Cdc_06&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_06

    Compatible IDs

    -
    USB\Class_02&SubClass_06&Prot_00
    -USB\Class_02&SubClass_06
    +
    USB\Class_02&SubClass_06&Prot_00
    +USB\Class_02&SubClass_06
     USB\Class_02
    @@ -650,15 +650,15 @@ USB CDC Multi-Channel ISDN Control Model (MCCM) interface collections have the f

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04
    -USB\Vid_%04x&Pid_%04x&Cdc_04&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_04
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_04
    +USB\Vid_%04x&Pid_%04x&Cdc_04&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_04

    Compatible IDs

    -
    USB\Class_02&SubClass_04&Prot_00
    -USB\Class_02&SubClass_04
    +
    USB\Class_02&SubClass_04&Prot_00
    +USB\Class_02&SubClass_04
     USB\Class_02
    @@ -712,15 +712,15 @@ USB CDC Telephone Control Model (TCM) interface collections have the following p

    Hardware ID

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_03&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_03
    -USB\Vid_%04x&Pid_%04x&Cdc_03&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_03
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_03&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_03
    +USB\Vid_%04x&Pid_%04x&Cdc_03&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_03

    Compatible ID

    -
    USB\Class_02&SubClass_03&Prot_%02X
    -USB\Class_02&SubClass_03
    +
    USB\Class_02&SubClass_03&Prot_%02X
    +USB\Class_02&SubClass_03
     USB\Class_02
    @@ -775,15 +775,15 @@ However, the USB generic parent driver can enumerate MCPC interface collections

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_88&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_88
    -USB\Vid_%04x&Pid_%04x&Cdc_88&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_88
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_88&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_88
    +USB\Vid_%04x&Pid_%04x&Cdc_88&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_88

    Compatible IDs

    -
    USB\Class_02&SubClass_88&Prot_00
    -USB\Class_02&SubClass_88
    +
    USB\Class_02&SubClass_88&Prot_00
    +USB\Class_02&SubClass_88
     USB\Class_02
    @@ -836,13 +836,13 @@ USB Video Device Class interface collections that occur on CDC and WMCDC devices

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&MI_%02x
    -USB\Vid_%04x&Pid_%04x&MI_%02x
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&MI_%02x
    +USB\Vid_%04x&Pid_%04x&MI_%02x

    Compatible IDs

    -
    USB\Class_0E&SubClass_01&Prot_00
    -USB\Class_0E&SubClass_01
    +
    USB\Class_0E&SubClass_01&Prot_00
    +USB\Class_0E&SubClass_01
     USB\Class_0E
    @@ -899,15 +899,15 @@ Interface collections that comply with the WMCDC specification have the followin

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_Modem&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_Modem
    -USB\Vid_%04x&Pid_%04x&Cdc_Modem&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_Modem
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_Modem&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_Modem
    +USB\Vid_%04x&Pid_%04x&Cdc_Modem&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_Modem

    Compatible IDs

    -
    USB\Class_02&SubClass_Modem&Prot_%02X
    -USB\Class_02&SubClass_Modem
    +
    USB\Class_02&SubClass_Modem&Prot_%02X
    +USB\Class_02&SubClass_Modem
     USB\Class_02
    @@ -962,15 +962,15 @@ USB WMCDC Device Management Model (DMM) interface collections have the following

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09
    -USB\Vid_%04x&Pid_%04x&Cdc_09&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_09
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09
    +USB\Vid_%04x&Pid_%04x&Cdc_09&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_09

    Compatible IDs

    -
    USB\Class_02&SubClass_09&Prot_%02X
    -USB\Class_02&SubClass_09
    +
    USB\Class_02&SubClass_09&Prot_%02X
    +USB\Class_02&SubClass_09
     USB\Class_02
    @@ -1023,15 +1023,15 @@ USB WMCDC Mobile Direct Line Model (MDLM) interface collections have the followi

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0A&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0A
    -USB\Vid_%04x&Pid_%04x&Cdc_0A&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_0A
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0A&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0A
    +USB\Vid_%04x&Pid_%04x&Cdc_0A&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_0A

    Compatible IDs

    -
    USB\Class_02&SubClass_0A&Prot_%02X
    -USB\Class_02&SubClass_0A
    +
    USB\Class_02&SubClass_0A&Prot_%02X
    +USB\Class_02&SubClass_0A
     USB\Class_02
    @@ -1086,15 +1086,15 @@ When the USB generic parent driver assigns separate PDOs to each OBEX interface,

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0B&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0B
    -USB\Vid_%04x&Pid_%04x&Cdc_0B&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_0B
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0B&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_0B
    +USB\Vid_%04x&Pid_%04x&Cdc_0B&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_0B

    Compatible IDs

    -
    USB\Class_02&SubClass_0B&Prot_00
    -USB\Class_02&SubClass_0B
    +
    USB\Class_02&SubClass_0B&Prot_00
    +USB\Class_02&SubClass_0B
     USB\Class_02
    @@ -1149,14 +1149,14 @@ When the USB generic parent driver assigns a single PDO to all of the OBEX inter

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&WPD_OBEX&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&WPD_OBEX
    -USB\Vid_%04x&Pid_%04x&WPD_OBEX&MI_%02x
    -USB\Vid_%04x&Pid_%04x&WPD_OBEX
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&WPD_OBEX&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&WPD_OBEX
    +USB\Vid_%04x&Pid_%04x&WPD_OBEX&MI_%02x
    +USB\Vid_%04x&Pid_%04x&WPD_OBEX

    Compatible IDs

    -
    USB\Class_02&WPD_OBEX
    +
    USB\Class_02&WPD_OBEX
     USB\Class_02
    @@ -1211,15 +1211,15 @@ Enumerated WHCM interface collections have the following properties.

    Hardware IDs

    -
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_08&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_08
    -USB\Vid_%04x&Pid_%04x&Cdc_08&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_08
    +
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_08&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_08
    +USB\Vid_%04x&Pid_%04x&Cdc_08&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_08

    Compatible IDs

    -
    USB\Class_02&SubClass_08&Prot_00
    -USB\Class_02&SubClass_08
    +
    USB\Class_02&SubClass_08&Prot_00
    +USB\Class_02&SubClass_08
     USB\Class_02
    diff --git a/windows-driver-docs-pr/usbcon/system-supplied-usb-drivers.md b/windows-driver-docs-pr/usbcon/system-supplied-usb-drivers.md index 411cf04c30..a714f00425 100644 --- a/windows-driver-docs-pr/usbcon/system-supplied-usb-drivers.md +++ b/windows-driver-docs-pr/usbcon/system-supplied-usb-drivers.md @@ -1,6 +1,7 @@ --- Description: This topics in this section describe the class drivers, generic client driver, and the parent composite driver that are provided by Microsoft. title: Microsoft-provided USB drivers +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/talking-to-usb-devices-start-to-finish.md b/windows-driver-docs-pr/usbcon/talking-to-usb-devices-start-to-finish.md index c5c5ddac35..d3ad7c0f8f 100644 --- a/windows-driver-docs-pr/usbcon/talking-to-usb-devices-start-to-finish.md +++ b/windows-driver-docs-pr/usbcon/talking-to-usb-devices-start-to-finish.md @@ -1,6 +1,7 @@ --- Description: Use the Windows Runtime APIs, introduced in Windows 8.1, to write Windows Store apps that gives users access to their peripheral USB device. title: Talking to USB devices, start to finish (Windows Store app) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -85,7 +86,7 @@ Follow the steps in this section or, skip directly to the [Custom USB device acc

    You can obtain that information from the device manufacturer.

    • Vendor and product identifiers

      -

      In Device Manager, view the device properties. On the Details tab, view the Hardware Id property value. That value is a combination of those two identifiers. For example, for the SuperMUTT device, the Hardware Id is "USB\VID_045E&PID_F001"; vendor ID is "0x045E" and product ID is "0xF001".

    • +

      In Device Manager, view the device properties. On the Details tab, view the Hardware Id property value. That value is a combination of those two identifiers. For example, for the SuperMUTT device, the Hardware Id is "USB\VID_045E&PID_F001"; vendor ID is "0x045E" and product ID is "0xF001".

    • Device class, subclass, and protocol codes
    • Device interface GUID
    diff --git a/windows-driver-docs-pr/usbcon/test-usb-type-c-systems-with-mutt-connex-c.md b/windows-driver-docs-pr/usbcon/test-usb-type-c-systems-with-mutt-connex-c.md index 8bc976dc30..c151c0b3e1 100644 --- a/windows-driver-docs-pr/usbcon/test-usb-type-c-systems-with-mutt-connex-c.md +++ b/windows-driver-docs-pr/usbcon/test-usb-type-c-systems-with-mutt-connex-c.md @@ -1,6 +1,7 @@ --- -Description: The MUTT Connection Exerciser Type-C (MUTT ConnEx-C) hardware board is a custom shield for the Arduino board. -title: Test USB Type-C systems with MUTT ConnEx-C +Description: The MUTT Connection Exerciser Type-C (USB Type-C ConnEx) hardware board is a custom shield for the Arduino board. +title: Test USB Type-C systems with USB Type-C ConnEx +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -8,12 +9,12 @@ ms.prod: windows-hardware ms.technology: windows-devices --- -# Test USB Type-C systems with MUTT ConnEx-C +# Test USB Type-C systems with USB Type-C ConnEx **Summary** -- Automated testing by using MUTT ConnEx-C +- Automated testing by using USB Type-C ConnEx - USB Type-C interoperability test procedures in Windows 10: functional testing (FT) and stress testing (ST). - Diagnostic procedures and tips to confirm scenarios, such as device addition and removal. @@ -32,7 +33,7 @@ ms.technology: windows-devices \[Some information relates to pre-released 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.\] -The MUTT Connection Exerciser Type-C (MUTT ConnEx-C) hardware board is a custom shield for the Arduino board. The shield provides a four-to-one switch to automate interoperability tests for USB Type-C scenarios. +The MUTT Connection Exerciser Type-C (USB Type-C ConnEx) hardware board is a custom shield for the Arduino board. The shield provides a four-to-one switch to automate interoperability tests for USB Type-C scenarios. This topic provides guidelines to automate the testing of systems, devices, docks with USB Type-C connectors and their interoperability with the Windows operating system. You can test hardware that belong to one of the following categories: @@ -43,7 +44,7 @@ This topic provides guidelines to automate the testing of systems, devices, dock ## Hardware requirements -To perform the USB Type-C interoperability test procedures by using MUTT ConnEx-C, you need: +To perform the USB Type-C interoperability test procedures by using USB Type-C ConnEx, you need: - **System under test (SUT)** @@ -59,11 +60,11 @@ To perform the USB Type-C interoperability test procedures by using MUTT ConnEx- For information about compatible adapters for the Arduino Mega 2560 R3 board, [see this site](http://go.microsoft.com/fwlink/p/?LinkID=733660). -- **MUTT ConnEx-C** +- **USB Type-C ConnEx** The shield has one male USB Type-C port (labeled **J1**) to which the SUT is connected. The shield also has four other USB ports (labeled **J2**, **J3**, **J4**, **J6**) to which devices can be attached that act as peripherals to the SUT. The shield monitors amperage and voltage being drawn from the SUT. You can buy this board from [MCCI](http://go.microsoft.com/fwlink/p/?LinkId=733488) or [JJG Technologies]( http://go.microsoft.com/fwlink/p/?linkid=618287). - ![mutt connex-c](images/connexc-top.png) + ![USB Type-C ConnEx](images/connexc-top.png) - **USB A-to-B cable** @@ -79,7 +80,7 @@ To perform the USB Type-C interoperability test procedures by using MUTT ConnEx- - **Proxy controller** - The MUTT ConnEx-C can be controlled by using a proxy for running the tests. The proxy controller can be one of these entities: + The USB Type-C ConnEx can be controlled by using a proxy for running the tests. The proxy controller can be one of these entities: - Secondary desktop PC or a laptop. @@ -106,7 +107,7 @@ Make sure you meet these requirements: - Your SUT must have the version of the Windows operating system with which you want to test interoperability. - The proxy controller must be running Windows 10. - [![download the mutt software package](images/download.png)](http://go.microsoft.com/fwlink/p/?LinkId=786621) and install the latest MUTT software package on the proxy controller. -- The package is a suite of tools used to run tests with MUTT ConnEx-C . +- The package is a suite of tools used to run tests with USB Type-C ConnEx . It includes utilities to update the firmware, switch between the peripheral ports, and send requests to simulate test cases. It also contains test driver packages that test the functionality of the buses, its controller, and devices connected to the bus. @@ -114,13 +115,13 @@ Make sure you meet these requirements: To open an elevated command window, the user must be a member of the **Administrators** group on the proxy controller. To open an elevated Command Prompt window, create a desktop shortcut to Cmd.exe, right-click the Cmd.exe shortcut, and select **Run as administrator**. -### MUTT ConnEx-C tools +### USB Type-C ConnEx tools -Here are the tools in MUTT software package that are specific to MUTT ConnEx-C +Here are the tools in MUTT software package that are specific to USB Type-C ConnEx | Tool | Description | |-------------------------------|------------------------------------------------------------------------------------------------------| -| [ConnExUtil.exe](#connexutil) | Command line tool for exercising MUTT ConnEx-C features. | +| [ConnExUtil.exe](#connexutil) | Command line tool for exercising USB Type-C ConnEx features. | | [CxLoop.cmd](#cxloop) | Connects and disconnects each port once. | | [CxStress.cmd](#cxstress) | Randomized stress script. | | [CxPower.cmd](#cxpower) | Captures power data (voltage and amperage) over a period of time and sends the output to a CSV file. | @@ -134,15 +135,15 @@ For information about all other tools, see [Tools in the MUTT software package]( Follow this procedure to set up your test environment. -![mutt connex-c configuration](images/connexc.png) +![USB Type-C ConnEx configuration](images/connexc.png) -The configuration should be similar to this image. Note that the USB Type-C port on the microcontroller provides control over MUTT ConnEx-C when connected to a PC. +The configuration should be similar to this image. Note that the USB Type-C port on the microcontroller provides control over USB Type-C ConnEx when connected to a PC. -In these steps, you will connect the hardware pieces, update the firmware on the microcontroller, and validate the installation. The DTMF shield provides control over MUTT ConnEx-C when connected to the audio port of a phone or tablet. +In these steps, you will connect the hardware pieces, update the firmware on the microcontroller, and validate the installation. The DTMF shield provides control over USB Type-C ConnEx when connected to the audio port of a phone or tablet. 1. Connect the microcontroller to the USB Type-C shield. - If the MUTT ConnEx-C did not come assembled, then continue with step 1. If your MUTT ConnEx-C has been assembled, then proceed to step 2. + If the USB Type-C ConnEx did not come assembled, then continue with step 1. If your USB Type-C ConnEx has been assembled, then proceed to step 2. **Caution**  ![caution](images/caution.png) This step must be performed carefully because the pins bend easily. @@ -150,25 +151,25 @@ In these steps, you will connect the hardware pieces, update the firmware on the 1. Align the pins of the USB Type-C shield with the receptors on the microcontroller by making sure that the boards are level to each other. - ![align pins of the mutt connex-c](images/connexc-align.png) + ![align pins of the USB Type-C ConnEx](images/connexc-align.png) 2. Gently press the two boards together. Be careful not to bend the pins on the shield. - ![assembling the mutt connex-c](images/connexc-connect.png) + ![assembling the USB Type-C ConnEx](images/connexc-connect.png) Your assembled unit should be similar to this image: ![connected connex-c board](images/connexc-connect1.png) -2. Power the MUTT ConnEx-C from the attached microcontroller by using either the USB Type-B (connected to the proxy controller) or from an external power adapter. The LCD display is similar to this image: +2. Power the USB Type-C ConnEx from the attached microcontroller by using either the USB Type-B (connected to the proxy controller) or from an external power adapter. The LCD display is similar to this image: After five seconds, the LCD display shows the current and voltage. - ![mutt connex-c before firmware boot](images/connexc-connect2.png)![mutt connex-c before firmware boot](images/connexc-connect3.png) + ![USB Type-C ConnEx before firmware boot](images/connexc-connect2.png)![USB Type-C ConnEx before firmware boot](images/connexc-connect3.png) If you do not the see display as shown in the previous image, make sure your have assembled the unit correctly. -3. Update the microcontroller with the MUTT ConnEx-C firmware. +3. Update the microcontroller with the USB Type-C ConnEx firmware. - Open an elevated Command Prompt window. - Navigate to the location of the MUTT software package, such as C:\\Program Files (x86)\\USBTest\\*<arch>*. - Run the following command: @@ -185,7 +186,7 @@ In these steps, you will connect the hardware pieces, update the firmware on the 5. Attach the peripherals to the USB ports labeled **J2**, **J3**, **J4**, **J6**. - ![attach peripherals to the mutt connex-c](images/connexc-connect7.png) + ![attach peripherals to the USB Type-C ConnEx](images/connexc-connect7.png) 6. Attach the proxy controller to the microcontroller. - If the proxy controller is a desktop PC or laptop, establish connection over USB. Connect the USB Type-B port on the microcontroller to a USB port on the proxy controller, as shown in the preceding image. @@ -200,16 +201,16 @@ In these steps, you will connect the hardware pieces, update the firmware on the ![attaching system under test (sut) with dtmf](images/connexc-connect5.png) -7. Make sure MUTT ConnEx-C is recognized by Device Manager on the proxy controller. +7. Make sure USB Type-C ConnEx is recognized by Device Manager on the proxy controller. 1. Right-click the Start button in the task bar and select **Device Manager**. 2. Expand the **Ports (COM & LPT)** node and note the COM port that is used by the microcontroller. In this example, it is connected to COM 4. - ![mutt connex-c in device manager](images/connexc-connect8.png) + ![USB Type-C ConnEx in device manager](images/connexc-connect8.png) ## ConnExUtil.exe -Here are the command line options that ConnExUtil.exe supports for controlling the MUTT ConnEx-C board. +Here are the command line options that ConnExUtil.exe supports for controlling the USB Type-C ConnEx board. @@ -227,24 +228,24 @@ Here are the command line options that ConnExUtil.exe supports for controlling t +

    List all devices connected to USB Type-C ConnEx

    +

    Select all devices connected to USB Type-C ConnEx, including audio.

    +

    Select a specific device connected to USB Type-C ConnEx ‘n’.

    +

    Input n is a 1-based index of the available devices connected to USB Type-C ConnEx which can be viewed by using the /list parameter. Without this parameter, the default behavior is to run each command on all USB Type-C ConnEx boards.

    @@ -356,10 +357,10 @@ do ( ) ``` -## Scripts for controlling the MUTT ConnEx-C board +## Scripts for controlling the USB Type-C ConnEx board -These scripts exercise the control interface supported by ConnExUtil.exe to run sequential and stress type tests with the MUTT ConnEx-C through the command line. All of these scripts support the optional command line parameter **audio** to indicate that the MUTT ConnEx-C board is connected over the 3.5 mm audio interface. By default they will only attempt to use USB connected boards. +These scripts exercise the control interface supported by ConnExUtil.exe to run sequential and stress type tests with the USB Type-C ConnEx through the command line. All of these scripts support the optional command line parameter **audio** to indicate that the USB Type-C ConnEx board is connected over the 3.5 mm audio interface. By default they will only attempt to use USB connected boards. ### Simple connect / disconnect sequence: CXLOOP.CMD @@ -373,7 +374,7 @@ The command line parameter **C** causes the script to only switch between the US ### Long running power measurement: CXPOWER.CMD -Saves the amperage and voltage reported by the MUTT ConnEx-C to output file power.csv at 2 second intervals. The data is formatted as comma-separated variables as follows: +Saves the amperage and voltage reported by the USB Type-C ConnEx to output file power.csv at 2 second intervals. The data is formatted as comma-separated variables as follows: *index***,***time***,***volts***,***amps* @@ -390,7 +391,7 @@ After capture is complete, this data may be post processed into charts showing p The USB Type-C interoperability test procedures are divided into two sections: functional testing (FT) and stress testing (ST). Each test section describes the test case and identifies the category that applies to the test. The product must be tested against the entire applicable category. Certain test cases contain links to relevant hints and tips for additional information. This section is focused on USB Type-C functionality and experience. A USB Type-C solution may contains other USB components such as a USB hub or USB controller. Detailed testing of USB hubs and controllers is covered in both the USB-IF's [xHCI interoperability test procedures](http://go.microsoft.com/fwlink/p/?LinkId=623257) and the Windows Hardware Certification Kit. -These test cases are based on the ConnExUtil commands and example scripts [Scripts for controlling the MUTT ConnEx-C board](#scripts). The test cases refer to the scripts. Customize the scripts as required for your test scenario. +These test cases are based on the ConnExUtil commands and example scripts [Scripts for controlling the USB Type-C ConnEx board](#scripts). The test cases refer to the scripts. Customize the scripts as required for your test scenario. [Device Enumeration](#ft1) Confirms that core aspects of device enumeration are functional. @@ -428,9 +429,9 @@ Confirms charging with USB Type-C.   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXLOOP.CMD script. When script pauses, confirm the newly activated peripheral is operational. 7. Reverse the orientation of USB Type-C cable and repeat step 5 - 7. @@ -453,9 +454,9 @@ For configuration images related to step 2 -4, see [Get started...](#config).   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXLOOP.CMD script. When script pauses, confirm the newly activated peripheral is operational. 7. Reverse the orientation of USB Type-C cable and repeat step 5 - 7. @@ -478,13 +479,13 @@ For configuration images related to step 2 -4, see [Get started...](#config).   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXLOOP.CMD script. When script pauses, confirm the newly activated peripheral is operational. 7. Reverse the orientation of USB Type-C cable and repeat step 5 - 7. -8. Connect MUTT ConnEx-C to port **J2**. +8. Connect USB Type-C ConnEx to port **J2**. **ConnExUtil.exe /setPort 2** @@ -516,13 +517,13 @@ For configuration images related to step 2 -4, see [Get started...](#config).   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXLOOP.CMD script. When script pauses, confirm the newly activated peripheral is operational. 7. Reverse the orientation of USB Type-C cable and repeat step 5 - 7. -8. Connect MUTT ConnEx-C to port **J2**. +8. Connect USB Type-C ConnEx to port **J2**. Confirm role swap. The Amperage shown on the LCD screen indicates power roles. **+ve** if **J1** is the power sink; **-ve** if **J1** is the power source. @@ -546,9 +547,9 @@ For configuration images related to step 2 -4, see [Get started...](#config).   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXSTRESS.CMD for 12 hours. @@ -574,9 +575,9 @@ For configuration images related to step 2 -4, see [Get started...](#config).   1. Power off the SUT. -2. Connect the SUT to the port labeled as **J1** on MUTT ConnEx-C. -3. Connect the proxy controller to MUTT ConnEx-C. -4. Connect peripherals to MUTT ConnEx-C. +2. Connect the SUT to the port labeled as **J1** on USB Type-C ConnEx. +3. Connect the proxy controller to USB Type-C ConnEx. +4. Connect peripherals to USB Type-C ConnEx. 5. Power on the SUT and log on to Windows. 6. At an elevated Command prompt, run the CXSTRESS.CMD for 12 hours. . @@ -615,7 +616,7 @@ The following stress tests can be adapted from the SuperMUTT test documentation ### Confirming charging and power -The onboard LCD on the MUTT ConnEx-C displays power (volts, amps, and direction). Confirm that it matches expectations from power sources plugged in and actively enabled with the MUTT ConnEx-C . +The onboard LCD on the USB Type-C ConnEx displays power (volts, amps, and direction). Confirm that it matches expectations from power sources plugged in and actively enabled with the USB Type-C ConnEx . ![confirming charging and power](images/connexc-connect9.png) diff --git a/windows-driver-docs-pr/usbcon/transfer-data-to-isochronous-endpoints.md b/windows-driver-docs-pr/usbcon/transfer-data-to-isochronous-endpoints.md index c62ded3010..f2f954b04c 100644 --- a/windows-driver-docs-pr/usbcon/transfer-data-to-isochronous-endpoints.md +++ b/windows-driver-docs-pr/usbcon/transfer-data-to-isochronous-endpoints.md @@ -383,7 +383,7 @@ NTSTATUS CreateIsochURB ( PDEVICE_OBJECT DeviceObject, // Allocate an isochronous URB for the transfer ntStatus = USBD_IsochUrbAllocate (deviceExtension->UsbdHandle, numberOfPackets, - &Urb); + &Urb); if (!NT_SUCCESS(ntStatus)) { diff --git a/windows-driver-docs-pr/usbcon/tutorial--write-your-first-usb-client-driver--kmdf-.md b/windows-driver-docs-pr/usbcon/tutorial--write-your-first-usb-client-driver--kmdf-.md index 457b3410ce..6661625e1b 100644 --- a/windows-driver-docs-pr/usbcon/tutorial--write-your-first-usb-client-driver--kmdf-.md +++ b/windows-driver-docs-pr/usbcon/tutorial--write-your-first-usb-client-driver--kmdf-.md @@ -1,6 +1,7 @@ --- Description: In this topic you'll use the USB Kernel-Mode Driver template provided with Microsoft Visual Studio Professional 2012 to write a simple kernel-mode driver framework (KMDF)-based client driver. title: How to write your first USB client driver (KMDF) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/type.md b/windows-driver-docs-pr/usbcon/type.md index 94dcf5a27d..be50681886 100644 --- a/windows-driver-docs-pr/usbcon/type.md +++ b/windows-driver-docs-pr/usbcon/type.md @@ -1,6 +1,7 @@ --- Description: This topic explains how to test the interoperability of USB Type-C enabled systems and Windows. title: USB Type-C manual interoperability test procedures +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -32,7 +33,7 @@ ms.technology: windows-devices This topic explains how to test the interoperability of USB Type-C enabled systems and Windows. It provides guidelines for device and system manufacturers to perform various functional and stress tests on systems and devices that expose a USB Type-C connector. It assumes that the reader is familiar with the official USB specification and xHCI interoperability test procedures, which can be downloaded from USB.ORG. -To run these tests by using the MUTT ConnEx-C board, see [Test USB Type-C systems with MUTT ConnEx-C](test-usb-type-c-systems-with-mutt-connex-c.md). +To run these tests by using the USB Type-C ConnEx board, see [Test USB Type-C systems with USB Type-C ConnEx](test-usb-type-c-systems-with-mutt-connex-c.md). The test product can belong to one or more of the following categories: diff --git a/windows-driver-docs-pr/usbcon/ucsi.md b/windows-driver-docs-pr/usbcon/ucsi.md index 78a17c89f5..04472ab3ec 100644 --- a/windows-driver-docs-pr/usbcon/ucsi.md +++ b/windows-driver-docs-pr/usbcon/ucsi.md @@ -1,6 +1,7 @@ --- Description: Microsoft provides a USB Type-C Connector System Software Interface (UCSI) Specification-compliant driver. title: USB Type-C Connector System Software Interface (UCSI) driver +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/understanding-the-kmdf-template-code-for-usb.md b/windows-driver-docs-pr/usbcon/understanding-the-kmdf-template-code-for-usb.md index b40df0d3c3..d2197617a2 100644 --- a/windows-driver-docs-pr/usbcon/understanding-the-kmdf-template-code-for-usb.md +++ b/windows-driver-docs-pr/usbcon/understanding-the-kmdf-template-code-for-usb.md @@ -1,6 +1,7 @@ --- Description: Learn about the source code for KMDF-based USB client driver. title: USB client driver code structure (KMDF) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -99,17 +100,17 @@ DriverEntry( // Register a cleanup callback so that we can call WPP_CLEANUP when // the framework driver object is deleted during driver unload. // - WDF_OBJECT_ATTRIBUTES_INIT(&attributes); + WDF_OBJECT_ATTRIBUTES_INIT(&attributes); attributes.EvtCleanupCallback = MyUSBDriver_EvtDriverContextCleanup; - WDF_DRIVER_CONFIG_INIT(&config, + WDF_DRIVER_CONFIG_INIT(&config, MyUSBDriver_EvtDeviceAdd ); status = WdfDriverCreate(DriverObject, RegistryPath, - &attributes, - &config, + &attributes, + &config, WDF_NO_HANDLE ); @@ -227,13 +228,13 @@ MyUSBDriver_CreateDevice( PAGED_CODE(); - WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks); + WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks); pnpPowerCallbacks.EvtDevicePrepareHardware = MyUSBDriver_EvtDevicePrepareHardware; - WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks); + WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpPowerCallbacks); - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&deviceAttributes, DEVICE_CONTEXT); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&deviceAttributes, DEVICE_CONTEXT); - status = WdfDeviceCreate(&DeviceInit, &deviceAttributes, &device); + status = WdfDeviceCreate(&DeviceInit, &deviceAttributes, &device); if (NT_SUCCESS(status)) { // @@ -252,7 +253,7 @@ MyUSBDriver_CreateDevice( // status = WdfDeviceCreateDeviceInterface( device, - &GUID_DEVINTERFACE_MyUSBDriver_, + &GUID_DEVINTERFACE_MyUSBDriver_, NULL // ReferenceString ); @@ -388,14 +389,14 @@ MyUSBDriver_EvtDevicePrepareHardware( // It also implies that we conform to rules mentioned in MSDN // documentation for WdfUsbTargetDeviceCreateWithParameters. // - WDF_USB_DEVICE_CREATE_CONFIG_INIT(&createParams, + WDF_USB_DEVICE_CREATE_CONFIG_INIT(&createParams, USBD_CLIENT_CONTRACT_VERSION_602 ); status = WdfUsbTargetDeviceCreateWithParameters(Device, - &createParams, + &createParams, WDF_NO_OBJECT_ATTRIBUTES, - &pDeviceContext->UsbDevice + &pDeviceContext->UsbDevice ); if (!NT_SUCCESS(status)) { @@ -408,13 +409,13 @@ MyUSBDriver_EvtDevicePrepareHardware( // Select the first configuration of the device, using the first alternate // setting of each interface // - WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(&configParams, + WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(&configParams, 0, NULL ); status = WdfUsbTargetDeviceSelectConfig(pDeviceContext->UsbDevice, WDF_NO_OBJECT_ATTRIBUTES, - &configParams + &configParams ); if (!NT_SUCCESS(status)) { @@ -537,7 +538,7 @@ MyUSBDriver_QueueInitialize( // other queues get dispatched here. // WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE( - &queueConfig, + &queueConfig, WdfIoQueueDispatchParallel ); @@ -545,9 +546,9 @@ MyUSBDriver_QueueInitialize( status = WdfIoQueueCreate( Device, - &queueConfig, + &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, - &queue + &queue ); if( !NT_SUCCESS(status) ) { diff --git a/windows-driver-docs-pr/usbcon/understanding-the-umdf-template-code-for-usb.md b/windows-driver-docs-pr/usbcon/understanding-the-umdf-template-code-for-usb.md index b4a4b8dacd..1829e93386 100644 --- a/windows-driver-docs-pr/usbcon/understanding-the-umdf-template-code-for-usb.md +++ b/windows-driver-docs-pr/usbcon/understanding-the-umdf-template-code-for-usb.md @@ -1,6 +1,7 @@ --- Description: Learn about the source code for a UMDF-based USB client driver. title: USB client driver code structure (UMDF) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -65,14 +66,14 @@ The next portion declares the tracing macro and the tracing GUID. Note the traci WPP_LEVEL_LOGGER(flag) #define WPP_FLAG_LEVEL_ENABLED(flag, level) \ - (WPP_LEVEL_ENABLED(flag) && \ + (WPP_LEVEL_ENABLED(flag) && \ WPP_CONTROL(WPP_BIT_ ## flag).Level >= level) #define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \ WPP_LEVEL_LOGGER(flags) #define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \ - (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl) + (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl) ``` @@ -118,7 +119,7 @@ EXTERN_C const CLSID CLSID_Driver; class CMyDriver : public CComObjectRootEx, - public CComCoClass, + public CComCoClass, public IDriverEntry { public: @@ -203,7 +204,7 @@ CMyDriver::OnDeviceAdd( hr = CMyDevice::CreateInstanceAndInitialize(FxWdfDriver, FxDeviceInit, - &device); + &device); if (SUCCEEDED(hr)) { @@ -344,7 +345,7 @@ CMyDevice::Initialize( FxDeviceInit->SetPowerPolicyOwnership(TRUE); - hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown); + hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -354,7 +355,7 @@ CMyDevice::Initialize( goto Exit; } - hr = FxDriver->CreateDevice(FxDeviceInit, unknown, &fxDevice); + hr = FxDriver->CreateDevice(FxDeviceInit, unknown, &fxDevice); DriverSafeRelease(unknown); if (FAILED(hr)) { @@ -401,7 +402,7 @@ CMyDevice::Configure( TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry"); - hr = CMyIoQueue::CreateInstanceAndInitialize(m_FxDevice, this, &m_IoQueue); + hr = CMyIoQueue::CreateInstanceAndInitialize(m_FxDevice, this, &m_IoQueue); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -421,7 +422,7 @@ CMyDevice::Configure( goto Exit; } - hr = m_FxDevice->CreateDeviceInterface(&GUID_DEVINTERFACE_MyUSBDriver_UMDF_,NULL); + hr = m_FxDevice->CreateDeviceInterface(&GUID_DEVINTERFACE_MyUSBDriver_UMDF_,NULL); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -488,7 +489,7 @@ CMyDevice::OnPrepareHardware( TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry"); - hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&usbFactory)); + hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&usbFactory)); if (FAILED(hr)) { @@ -499,7 +500,7 @@ CMyDevice::OnPrepareHardware( goto Exit; } - hr = usbFactory->CreateUsbTargetDevice(&usbDevice); + hr = usbFactory->CreateUsbTargetDevice(&usbDevice); if (FAILED(hr)) { @@ -655,7 +656,7 @@ CMyIoQueue::CreateInstanceAndInitialize( TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Entry"); - hr = CComObject::CreateInstance( &pMyQueue ); + hr = CComObject::CreateInstance( &pMyQueue ); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -703,7 +704,7 @@ CMyIoQueue::Initialize( assert(FxDevice != NULL); assert(MyDevice != NULL); - hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown); + hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown); if (FAILED(hr)) { TraceEvents(TRACE_LEVEL_ERROR, @@ -718,7 +719,7 @@ CMyIoQueue::Initialize( WdfIoQueueDispatchParallel, // Dispatch type TRUE, // Power managed? FALSE, // Allow zero-length requests? - &fxQueue); // I/O queue + &fxQueue); // I/O queue DriverSafeRelease(unknown); if (FAILED(hr)) diff --git a/windows-driver-docs-pr/usbcon/usb-3-0-driver-stack-architecture.md b/windows-driver-docs-pr/usbcon/usb-3-0-driver-stack-architecture.md index 3c97c0a312..5df2348f99 100644 --- a/windows-driver-docs-pr/usbcon/usb-3-0-driver-stack-architecture.md +++ b/windows-driver-docs-pr/usbcon/usb-3-0-driver-stack-architecture.md @@ -1,6 +1,7 @@ --- Description: This topic provides an overview of the Universal Serial Bus (USB) driver stack architecture. title: USB host-side drivers in Windows +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-3-0-lpm-mechanism-.md b/windows-driver-docs-pr/usbcon/usb-3-0-lpm-mechanism-.md index c61bcc82bc..f65d1f54fc 100644 --- a/windows-driver-docs-pr/usbcon/usb-3-0-lpm-mechanism-.md +++ b/windows-driver-docs-pr/usbcon/usb-3-0-lpm-mechanism-.md @@ -1,6 +1,7 @@ --- -Description: This topic describes the USB 3.0 LPM mechanism.There is an addendum to the official USB 2.0 Specification (USB2\_LinkPowerMangement\_ECN), which defines LPM for newer USB 2.0 hardware. +Description: This topic describes the USB 3.0 LPM mechanism.There is an addendum to the official USB 2.0 Specification (USB2_LinkPowerMangement_ECN), which defines LPM for newer USB 2.0 hardware. title: USB 3.0 LPM mechanism +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-bulk-and-interrupt-transfer.md b/windows-driver-docs-pr/usbcon/usb-bulk-and-interrupt-transfer.md index 832824cc80..19da8c0000 100644 --- a/windows-driver-docs-pr/usbcon/usb-bulk-and-interrupt-transfer.md +++ b/windows-driver-docs-pr/usbcon/usb-bulk-and-interrupt-transfer.md @@ -225,7 +225,7 @@ VOID Fx3EvtIoWrite( status = WdfRequestRetrieveInputMemory( Request, - &reqMemory + &reqMemory ); if (!NT_SUCCESS(status)) { diff --git a/windows-driver-docs-pr/usbcon/usb-client-driver-contract-in-windows-8.md b/windows-driver-docs-pr/usbcon/usb-client-driver-contract-in-windows-8.md index 169b264957..3591cf4394 100644 --- a/windows-driver-docs-pr/usbcon/usb-client-driver-contract-in-windows-8.md +++ b/windows-driver-docs-pr/usbcon/usb-client-driver-contract-in-windows-8.md @@ -1,6 +1,7 @@ --- Description: This topic describes best practices for a client driver for allocating, building, and sending an URB to the USB driver stack included with Windows 8. title: Best Practices - Using URBs +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-common-class-generic-parent-driver.md b/windows-driver-docs-pr/usbcon/usb-common-class-generic-parent-driver.md index abf4b93ea4..db7f4cac8f 100644 --- a/windows-driver-docs-pr/usbcon/usb-common-class-generic-parent-driver.md +++ b/windows-driver-docs-pr/usbcon/usb-common-class-generic-parent-driver.md @@ -1,6 +1,7 @@ --- Description: This section describes the Usbccgp.sys driver provided by Microsoft for composite devices. title: USB Generic Parent Driver (Usbccgp.sys) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-configuration-descriptors.md b/windows-driver-docs-pr/usbcon/usb-configuration-descriptors.md index e6fc569be0..3a98e89746 100644 --- a/windows-driver-docs-pr/usbcon/usb-configuration-descriptors.md +++ b/windows-driver-docs-pr/usbcon/usb-configuration-descriptors.md @@ -108,7 +108,7 @@ Within a USB configuration, the number of interfaces and their alternate setting ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor ( UsbDevice, NULL, - &sizeConfigDesc); + &sizeConfigDesc); if (sizeConfigDesc == 0) { @@ -136,7 +136,7 @@ Within a USB configuration, the number of interfaces and their alternate setting ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor ( UsbDevice, fullConfigDesc, - &sizeConfigDesc); + &sizeConfigDesc); if (!NT_SUCCESS(ntStatus)) { @@ -184,7 +184,7 @@ NTSTATUS FX3_RetrieveConfigurationDescriptor ( PAGED_CODE(); - RtlZeroMemory (&configDesc, sizeof(USB_CONFIGURATION_DESCRIPTOR)); + RtlZeroMemory (&configDesc, sizeof(USB_CONFIGURATION_DESCRIPTOR)); *ConfigDescriptor = NULL; // Allocate an URB for the get-descriptor request. @@ -195,8 +195,8 @@ NTSTATUS FX3_RetrieveConfigurationDescriptor ( ntStatus = WdfUsbTargetDeviceCreateUrb ( UsbDevice, NULL, - &urbMemory, - &urb); + &urbMemory, + &urb); if (!NT_SUCCESS (ntStatus)) { @@ -213,7 +213,7 @@ NTSTATUS FX3_RetrieveConfigurationDescriptor ( USB_CONFIGURATION_DESCRIPTOR_TYPE, // Type of descriptor *ConfigurationIndex, // Index of the configuration 0, // Not used for configuration descriptors - &configDesc, // Points to a USB_CONFIGURATION_DESCRIPTOR structure + &configDesc, // Points to a USB_CONFIGURATION_DESCRIPTOR structure NULL, // Not required because we are providing a buffer not MDL sizeof(USB_CONFIGURATION_DESCRIPTOR), // Size of the USB_CONFIGURATION_DESCRIPTOR structure. NULL // Reserved. diff --git a/windows-driver-docs-pr/usbcon/usb-control-transfer.md b/windows-driver-docs-pr/usbcon/usb-control-transfer.md index f8a6720114..9f5c20e235 100644 --- a/windows-driver-docs-pr/usbcon/usb-control-transfer.md +++ b/windows-driver-docs-pr/usbcon/usb-control-transfer.md @@ -603,19 +603,19 @@ VOID GetFirmwareVersion( firmwareVersion = 0; - WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &firmwareVersion, sizeof(firmwareVersion)); + WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &firmwareVersion, sizeof(firmwareVersion)); WDF_REQUEST_SEND_OPTIONS_INIT( - &sendOptions, + &sendOptions, WDF_REQUEST_SEND_OPTION_TIMEOUT ); WDF_REQUEST_SEND_OPTIONS_SET_TIMEOUT( - &sendOptions, + &sendOptions, DEFAULT_CONTROL_TRANSFER_TIMEOUT ); - WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(&controlSetupPacket, + WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(&controlSetupPacket, BmRequestDeviceToHost, // Direction of the request BmRequestToDevice, // Recipient USBFX2_GET_FIRMWARE_VERSION, // Vendor command @@ -625,9 +625,9 @@ VOID GetFirmwareVersion( status = WdfUsbTargetDeviceSendControlTransferSynchronously( DeviceContext->UsbDevice, WDF_NO_HANDLE, // Optional WDFREQUEST - &sendOptions, - &controlSetupPacket, - &memoryDescriptor, // MemoryDescriptor + &sendOptions, + &controlSetupPacket, + &memoryDescriptor, // MemoryDescriptor NULL); // BytesTransferred if (!NT_SUCCESS(status)) @@ -694,24 +694,24 @@ CDevice::GetDeviceStatus () WINUSB_CONTROL_SETUP_PACKET setupPacket; WINUSB_CONTROL_SETUP_PACKET_INIT_GET_STATUS( - &setupPacket, + &setupPacket, BmRequestToDevice, 0); hr = SendControlTransferSynchronously( - &(setupPacket.WinUsb), - & deviceStatus, + &(setupPacket.WinUsb), + & deviceStatus, sizeof(USHORT), - &bytesReturned + &bytesReturned ); if (SUCCEEDED(hr)) { - if (deviceStatus & USB_GETSTATUS_SELF_POWERED) + if (deviceStatus & USB_GETSTATUS_SELF_POWERED) { m_Self_Powered = true; } - if (deviceStatus & USB_GETSTATUS_REMOTE_WAKEUP_ENABLED) + if (deviceStatus & USB_GETSTATUS_REMOTE_WAKEUP_ENABLED) { m_remote_wake-enabled = true; } @@ -746,17 +746,17 @@ CDevice::SendControlTransferSynchronously( hr = m_FxDevice->CreateRequest( NULL, //pCallbackInterface NULL, //pParentObject - &pWdfRequest); + &pWdfRequest); if (SUCCEEDED(hr)) { - m_FxDevice->GetDriver(&FxDriver); + m_FxDevice->GetDriver(&FxDriver); hr = FxDriver->CreatePreallocatedWdfMemory( Buffer, BufferLength, NULL, //pCallbackInterface pWdfRequest, //pParetObject - &FxMemory ); + &FxMemory ); } if (SUCCEEDED(hr)) @@ -775,14 +775,14 @@ CDevice::SendControlTransferSynchronously( if (SUCCEEDED(hr)) { - pWdfRequest->GetCompletionParams(&FxComplParams); + pWdfRequest->GetCompletionParams(&FxComplParams); hr = FxComplParams->GetCompletionStatus(); } if (SUCCEEDED(hr)) { - HRESULT hrQI = FxComplParams->QueryInterface(IID_PPV_ARGS(&FxUsbComplParams)); + HRESULT hrQI = FxComplParams->QueryInterface(IID_PPV_ARGS(&FxUsbComplParams)); WUDF_TEST_DRIVER_ASSERT(SUCCEEDED(hrQI)); WUDF_TEST_DRIVER_ASSERT( WdfUsbRequestTypeDeviceControlTransfer == diff --git a/windows-driver-docs-pr/usbcon/usb-device-descriptors.md b/windows-driver-docs-pr/usbcon/usb-device-descriptors.md index 2a42212a3f..cd8dd92c0e 100644 --- a/windows-driver-docs-pr/usbcon/usb-device-descriptors.md +++ b/windows-driver-docs-pr/usbcon/usb-device-descriptors.md @@ -1,5 +1,5 @@ --- -Description: The device descriptor contains information about a USB device as a whole. This topic describes the USB\_DEVICE\_DESCRIPTOR structure and includes information about how a client driver can send a get-descriptor request to obtain the device descriptor. +Description: The device descriptor contains information about a USB device as a whole. This topic describes the USB_DEVICE_DESCRIPTOR structure and includes information about how a client driver can send a get-descriptor request to obtain the device descriptor. title: USB device descriptors author: windows-driver-content ms.author: windowsdriverdev diff --git a/windows-driver-docs-pr/usbcon/usb-device-side-drivers-in-windows.md b/windows-driver-docs-pr/usbcon/usb-device-side-drivers-in-windows.md index 1bb0385d0e..772613929e 100644 --- a/windows-driver-docs-pr/usbcon/usb-device-side-drivers-in-windows.md +++ b/windows-driver-docs-pr/usbcon/usb-device-side-drivers-in-windows.md @@ -1,6 +1,7 @@ --- Description: Describes the architecture of the USB function stack. title: USB device-side drivers in Windows +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-driver-installation-based-on-compatible-ids.md b/windows-driver-docs-pr/usbcon/usb-driver-installation-based-on-compatible-ids.md index a3839266d4..c28511b244 100644 --- a/windows-driver-docs-pr/usbcon/usb-driver-installation-based-on-compatible-ids.md +++ b/windows-driver-docs-pr/usbcon/usb-driver-installation-based-on-compatible-ids.md @@ -1,6 +1,7 @@ --- Description: Microsoft-provided in-box driver (Usbser.sys) for your Communications and CDC Control device. title: USB serial driver (Usbser.sys) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-driver-testing-guide.md b/windows-driver-docs-pr/usbcon/usb-driver-testing-guide.md index 193e4ba699..8e5b830133 100644 --- a/windows-driver-docs-pr/usbcon/usb-driver-testing-guide.md +++ b/windows-driver-docs-pr/usbcon/usb-driver-testing-guide.md @@ -1,6 +1,7 @@ --- Description: This section describes tools that you can use to test your USB hardware or software, capture traces of operations and other system events, and observe how the USB driver stack responds to a request sent by a client driver or an application. title: Testing USB hardware, drivers, and apps in Windows +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article @@ -38,8 +39,8 @@ This section describes tools that you can use to test your USB hardware or softw - - + + diff --git a/windows-driver-docs-pr/usbcon/usb-dual-role-driver-stack-architecture.md b/windows-driver-docs-pr/usbcon/usb-dual-role-driver-stack-architecture.md index a10e566ec5..549fe03d09 100644 --- a/windows-driver-docs-pr/usbcon/usb-dual-role-driver-stack-architecture.md +++ b/windows-driver-docs-pr/usbcon/usb-dual-role-driver-stack-architecture.md @@ -146,7 +146,7 @@ Device(URS0) { // // Replace with your own hardware ID. Microsoft will add it to the inbox INF, - // or you may choose to author a custom INF that uses Needs & Includes directives + // or you may choose to author a custom INF that uses Needs & Includes directives // to include sections from the inbox INF. // Name(_HID, "ABCD1234") diff --git a/windows-driver-docs-pr/usbcon/usb-emulated-device--ude--architecture.md b/windows-driver-docs-pr/usbcon/usb-emulated-device--ude--architecture.md index 85747b41bf..29e4c9d8e9 100644 --- a/windows-driver-docs-pr/usbcon/usb-emulated-device--ude--architecture.md +++ b/windows-driver-docs-pr/usbcon/usb-emulated-device--ude--architecture.md @@ -1,6 +1,7 @@ --- Description: The section describes architecture of USB Device Emulation(UDE) that emulates the behavior of a USB host controller and a connected device. title: Architecture of USB Device Emulation (UDE) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-faq--introductory-level.md b/windows-driver-docs-pr/usbcon/usb-faq--introductory-level.md index d73f6e6ba9..2ffd4dbc97 100644 --- a/windows-driver-docs-pr/usbcon/usb-faq--introductory-level.md +++ b/windows-driver-docs-pr/usbcon/usb-faq--introductory-level.md @@ -1,6 +1,7 @@ --- Description: This topic presents frequently asked questions for driver developers who are new to developing and integrating USB devices and drivers with Windows operating systems. title: USB in Windows - FAQ +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-if-certification-tests.md b/windows-driver-docs-pr/usbcon/usb-if-certification-tests.md index 26940e552d..f6b5392790 100644 --- a/windows-driver-docs-pr/usbcon/usb-if-certification-tests.md +++ b/windows-driver-docs-pr/usbcon/usb-if-certification-tests.md @@ -1,6 +1,7 @@ --- Description: Guidelines for hardware vendors and device manufacturers to prepare USB devices and host controllers for Windows Hardware Certification Program submission. title: USB-IF Certification Tests +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/usb-selective-suspend.md b/windows-driver-docs-pr/usbcon/usb-selective-suspend.md index 72b4f3aebd..7e7f053bc3 100644 --- a/windows-driver-docs-pr/usbcon/usb-selective-suspend.md +++ b/windows-driver-docs-pr/usbcon/usb-selective-suspend.md @@ -226,7 +226,7 @@ IdleNotificationRequestComplete( ntStatus = Irp->IoStatus.Status; - if(!NT_SUCCESS(ntStatus) && ntStatus != STATUS_NOT_SUPPORTED) + if(!NT_SUCCESS(ntStatus) && ntStatus != STATUS_NOT_SUPPORTED) { //Idle IRP completes with error. @@ -292,7 +292,7 @@ IdleNotificationRequestComplete_Exit: DeviceExtension->PendingIdleIrp = NULL; - InterlockedExchange(&DeviceExtension->IdleReqPend, 0); + InterlockedExchange(&DeviceExtension->IdleReqPend, 0); if(idleCallbackInfo) { @@ -308,7 +308,7 @@ IdleNotificationRequestComplete_Exit: IoFreeIrp(Irp); - KeSetEvent(&DeviceExtension->IdleIrpCompleteEvent, IO_NO_INCREMENT, FALSE); + KeSetEvent(&DeviceExtension->IdleIrpCompleteEvent, IO_NO_INCREMENT, FALSE); return STATUS_MORE_PROCESSING_REQUIRED; } diff --git a/windows-driver-docs-pr/usbcon/usb-string-descriptors.md b/windows-driver-docs-pr/usbcon/usb-string-descriptors.md index a082b62ea9..58eafc2b36 100644 --- a/windows-driver-docs-pr/usbcon/usb-string-descriptors.md +++ b/windows-driver-docs-pr/usbcon/usb-string-descriptors.md @@ -33,7 +33,7 @@ UsbBuildGetDescriptorRequest( USB_STRING_DESCRIPTOR_TYPE, i, // index of string descriptor langID, // language ID of string. - &USD, // points to a USB_STRING_DESCRIPTOR. + &USD, // points to a USB_STRING_DESCRIPTOR. NULL, sizeof(USB_STRING_DESCRIPTOR), NULL diff --git a/windows-driver-docs-pr/usbcon/using-usb-etw.md b/windows-driver-docs-pr/usbcon/using-usb-etw.md index 2911970e8b..43e5c0cc55 100644 --- a/windows-driver-docs-pr/usbcon/using-usb-etw.md +++ b/windows-driver-docs-pr/usbcon/using-usb-etw.md @@ -36,12 +36,12 @@ An application can include activity ID GUIDs by calling [**EventActivityIdContro This example code shows how an application can set an activity ID GUID and send it to the ETW provider, a UMDF driver. ``` -EventActivityIdControl(EVENT_ACTIVITY_CTRL_CREATE_ID, &activityIdStruct.ActivityId); -EventActivityIdControl(EVENT_ACTIVITY_CTRL_SET_ID, &activityIdStruct.ActivityId); +EventActivityIdControl(EVENT_ACTIVITY_CTRL_CREATE_ID, &activityIdStruct.ActivityId); +EventActivityIdControl(EVENT_ACTIVITY_CTRL_SET_ID, &activityIdStruct.ActivityId); if (!DeviceIoControl(hRead, IOCTL_OSRUSBFX2_SET_ACTIVITY_ID, - &activityIdStruct, // Ptr to InBuffer + &activityIdStruct, // Ptr to InBuffer sizeof(activityIdStruct), // Length of InBuffer NULL, // Ptr to OutBuffer 0, // Length of OutBuffer @@ -54,7 +54,7 @@ if (!DeviceIoControl(hRead, ... -success = ReadFile(hRead, pinBuf, G_ReadLen, (PULONG) &nBytesRead, NULL); +success = ReadFile(hRead, pinBuf, G_ReadLen, (PULONG) &nBytesRead, NULL); if(success == 0) { @@ -126,15 +126,15 @@ Return Value: } else { - FxRequest->GetInputMemory(&memory ); + FxRequest->GetInputMemory(&memory ); } if (SUCCEEDED(hr)) { - buffer = memory->GetDataBuffer(&bigBufferCb); + buffer = memory->GetDataBuffer(&bigBufferCb); memory->Release(); - m_Device->SetActivityId(&((PUMDF_ACTIVITY_ID)buffer)->ActivityId); + m_Device->SetActivityId(&((PUMDF_ACTIVITY_ID)buffer)->ActivityId); hr = S_OK; } @@ -148,7 +148,7 @@ VOID LPCGUID ActivityId ) { - CopyMemory(&m_ActivityId, ActivityId, sizeof(m_ActivityId)); + CopyMemory(&m_ActivityId, ActivityId, sizeof(m_ActivityId)); } @@ -173,11 +173,11 @@ CMyReadWriteQueue::ForwardFormattedRequest( ... if (FAILED(hrSend)) { - contextHr = pRequest->RetrieveContext((void**)&pRequestContext); + contextHr = pRequest->RetrieveContext((void**)&pRequestContext); if (SUCCEEDED(contextHr)) { - EventActivityIdControl(EVENT_ACTIVITY_CTRL_SET_ID, &pRequestContext->ActivityId); + EventActivityIdControl(EVENT_ACTIVITY_CTRL_SET_ID, &pRequestContext->ActivityId); if (pRequestContext->RequestType == RequestTypeRead) { diff --git a/windows-driver-docs-pr/usbcon/using-winusb-api-to-communicate-with-a-usb-device.md b/windows-driver-docs-pr/usbcon/using-winusb-api-to-communicate-with-a-usb-device.md index ea5ead6827..8dfa707fdb 100644 --- a/windows-driver-docs-pr/usbcon/using-winusb-api-to-communicate-with-a-usb-device.md +++ b/windows-driver-docs-pr/usbcon/using-winusb-api-to-communicate-with-a-usb-device.md @@ -91,7 +91,7 @@ BOOL GetUSBDeviceSpeed(WINUSB_INTERFACE_HANDLE hDeviceHandle, UCHAR* pDeviceSpee ULONG length = sizeof(UCHAR); - bResult = WinUsb_QueryDeviceInformation(hDeviceHandle, DEVICE_SPEED, &length, pDeviceSpeed); + bResult = WinUsb_QueryDeviceInformation(hDeviceHandle, DEVICE_SPEED, &length, pDeviceSpeed); if(!bResult) { printf("Error getting device speed: %d.\n", GetLastError()); @@ -138,19 +138,19 @@ BOOL QueryDeviceEndpoints (WINUSB_INTERFACE_HANDLE hDeviceHandle, PIPE_ID* pipei BOOL bResult = TRUE; USB_INTERFACE_DESCRIPTOR InterfaceDescriptor; - ZeroMemory(&InterfaceDescriptor, sizeof(USB_INTERFACE_DESCRIPTOR)); + ZeroMemory(&InterfaceDescriptor, sizeof(USB_INTERFACE_DESCRIPTOR)); WINUSB_PIPE_INFORMATION Pipe; - ZeroMemory(&Pipe, sizeof(WINUSB_PIPE_INFORMATION)); + ZeroMemory(&Pipe, sizeof(WINUSB_PIPE_INFORMATION)); - bResult = WinUsb_QueryInterfaceSettings(hDeviceHandle, 0, &InterfaceDescriptor); + bResult = WinUsb_QueryInterfaceSettings(hDeviceHandle, 0, &InterfaceDescriptor); if (bResult) { for (int index = 0; index < InterfaceDescriptor.bNumEndpoints; index++) { - bResult = WinUsb_QueryPipe(hDeviceHandle, 0, index, &Pipe); + bResult = WinUsb_QueryPipe(hDeviceHandle, 0, index, &Pipe); if (bResult) { @@ -231,7 +231,7 @@ BOOL SendDatatoDefaultEndpoint(WINUSB_INTERFACE_HANDLE hDeviceHandle) UCHAR bars = 0; WINUSB_SETUP_PACKET SetupPacket; - ZeroMemory(&SetupPacket, sizeof(WINUSB_SETUP_PACKET)); + ZeroMemory(&SetupPacket, sizeof(WINUSB_SETUP_PACKET)); ULONG cbSent = 0; //Set bits to light alternate bars @@ -247,7 +247,7 @@ BOOL SendDatatoDefaultEndpoint(WINUSB_INTERFACE_HANDLE hDeviceHandle) SetupPacket.Index = 0; SetupPacket.Length = sizeof(UCHAR); - bResult = WinUsb_ControlTransfer(hDeviceHandle, SetupPacket, &bars, sizeof(UCHAR), &cbSent, 0); + bResult = WinUsb_ControlTransfer(hDeviceHandle, SetupPacket, &bars, sizeof(UCHAR), &cbSent, 0); if(!bResult) { goto done; @@ -292,7 +292,7 @@ BOOL WriteToBulkEndpoint(WINUSB_INTERFACE_HANDLE hDeviceHandle, UCHAR* pID, ULON ULONG cbSize = strlen(szBuffer); ULONG cbSent = 0; - bResult = WinUsb_WritePipe(hDeviceHandle, *pID, szBuffer, cbSize, &cbSent, 0); + bResult = WinUsb_WritePipe(hDeviceHandle, *pID, szBuffer, cbSize, &cbSent, 0); if(!bResult) { goto done; @@ -329,7 +329,7 @@ BOOL ReadFromBulkEndpoint(WINUSB_INTERFACE_HANDLE hDeviceHandle, UCHAR* pID, ULO ULONG cbRead = 0; - bResult = WinUsb_ReadPipe(hDeviceHandle, *pID, szBuffer, cbSize, &cbRead, 0); + bResult = WinUsb_ReadPipe(hDeviceHandle, *pID, szBuffer, cbSize, &cbRead, 0); if(!bResult) { goto done; @@ -374,25 +374,25 @@ int _tmain(int argc, _TCHAR* argv[]) UCHAR DeviceSpeed; ULONG cbSize = 0; - bResult = GetDeviceHandle(guidDeviceInterface, &hDeviceHandle); + bResult = GetDeviceHandle(guidDeviceInterface, &hDeviceHandle); if(!bResult) { goto done; } - bResult = GetWinUSBHandle(hDeviceHandle, &hWinUSBHandle); + bResult = GetWinUSBHandle(hDeviceHandle, &hWinUSBHandle); if(!bResult) { goto done; } - bResult = GetUSBDeviceSpeed(hWinUSBHandle, &DeviceSpeed); + bResult = GetUSBDeviceSpeed(hWinUSBHandle, &DeviceSpeed); if(!bResult) { goto done; } - bResult = QueryDeviceEndpoints(hWinUSBHandle, &PipeID); + bResult = QueryDeviceEndpoints(hWinUSBHandle, &PipeID); if(!bResult) { goto done; @@ -404,13 +404,13 @@ int _tmain(int argc, _TCHAR* argv[]) goto done; } - bResult = WriteToBulkEndpoint(hWinUSBHandle, &PipeID.PipeOutId, &cbSize); + bResult = WriteToBulkEndpoint(hWinUSBHandle, &PipeID.PipeOutId, &cbSize); if(!bResult) { goto done; } - bResult = ReadFromBulkEndpoint(hWinUSBHandle, &PipeID.PipeInId, cbSize); + bResult = ReadFromBulkEndpoint(hWinUSBHandle, &PipeID.PipeInId, cbSize); if(!bResult) { goto done; diff --git a/windows-driver-docs-pr/usbcon/wdk-resources-for-usb-driver-development.md b/windows-driver-docs-pr/usbcon/wdk-resources-for-usb-driver-development.md index 975edbf5b1..acee98220e 100644 --- a/windows-driver-docs-pr/usbcon/wdk-resources-for-usb-driver-development.md +++ b/windows-driver-docs-pr/usbcon/wdk-resources-for-usb-driver-development.md @@ -1,5 +1,5 @@ --- -Description: This topic lists the &\#0034;How to&\#0034; topics in this documentation set. Each how-to topic presents a set of tasks as a sequence of steps with code examples. +Description: This topic lists the "How to" topics in the USB driver documentation set. Each how-to topic presents a set of tasks as a sequence of steps with code examples. title: Common tasks for USB client drivers author: windows-driver-content ms.author: windowsdriverdev diff --git a/windows-driver-docs-pr/usbcon/what-s-new-for-usb-in-windows-blue.md b/windows-driver-docs-pr/usbcon/what-s-new-for-usb-in-windows-blue.md index 02a086e7f5..3c9e79ab85 100644 --- a/windows-driver-docs-pr/usbcon/what-s-new-for-usb-in-windows-blue.md +++ b/windows-driver-docs-pr/usbcon/what-s-new-for-usb-in-windows-blue.md @@ -1,6 +1,7 @@ --- Description: Here are the new features and improvements for Universal Serial Bus (USB) in Windows 8.1. title: Windows 8.1 - What's new for USB +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/what-s-new-in-usb-in-windows-8.md b/windows-driver-docs-pr/usbcon/what-s-new-in-usb-in-windows-8.md index dca4834bae..676d42944c 100644 --- a/windows-driver-docs-pr/usbcon/what-s-new-in-usb-in-windows-8.md +++ b/windows-driver-docs-pr/usbcon/what-s-new-in-usb-in-windows-8.md @@ -1,6 +1,7 @@ --- Description: This topic summarizes the new features and improvements for Universal Serial Bus (USB) client drivers in Windows 8. title: Windows 8 - What's new for USB +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/windows-10--what-s-new-for-usb.md b/windows-driver-docs-pr/usbcon/windows-10--what-s-new-for-usb.md index 2533de7761..ee1c96f153 100644 --- a/windows-driver-docs-pr/usbcon/windows-10--what-s-new-for-usb.md +++ b/windows-driver-docs-pr/usbcon/windows-10--what-s-new-for-usb.md @@ -1,6 +1,7 @@ --- Description: Highlights the new features and improvements for Universal Serial Bus (USB) in Windows 10. title: Windows 10 - What's new for USB +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/windows-hardware-certification-kit-tests-for-usb.md b/windows-driver-docs-pr/usbcon/windows-hardware-certification-kit-tests-for-usb.md index a180ae8bc3..9950db38f3 100644 --- a/windows-driver-docs-pr/usbcon/windows-hardware-certification-kit-tests-for-usb.md +++ b/windows-driver-docs-pr/usbcon/windows-hardware-certification-kit-tests-for-usb.md @@ -1,6 +1,7 @@ --- Description: The Windows Hardware Certification Kit (HCK) tests can be used for additional testing of Systems, USB host controllers, hubs, and devices. title: Windows Hardware Certification Kit (HCK) Tests for USB +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/winusb-functions-for-pipe-policy-modification.md b/windows-driver-docs-pr/usbcon/winusb-functions-for-pipe-policy-modification.md index 3ad6c9b375..fb21ef5897 100644 --- a/windows-driver-docs-pr/usbcon/winusb-functions-for-pipe-policy-modification.md +++ b/windows-driver-docs-pr/usbcon/winusb-functions-for-pipe-policy-modification.md @@ -1,5 +1,5 @@ --- -Description: Winusb.dll exposes the WinUsb\_GetPipePolicy function to retrieve the pipe's default policy. +Description: Winusb.dll exposes the WinUsb_GetPipePolicy function to retrieve the pipe's default policy. title: WinUSB Functions for Pipe Policy Modification author: windows-driver-content ms.author: windowsdriverdev diff --git a/windows-driver-docs-pr/usbcon/winusb-installation.md b/windows-driver-docs-pr/usbcon/winusb-installation.md index a21f1752a0..ac153d5836 100644 --- a/windows-driver-docs-pr/usbcon/winusb-installation.md +++ b/windows-driver-docs-pr/usbcon/winusb-installation.md @@ -1,6 +1,7 @@ --- Description: Install WinUSB (Winusb.sys) in the device's kernel-mode stack as the USB device's function driver instead of implementing a driver. title: WinUSB (Winusb.sys) Installation +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/winusb.md b/windows-driver-docs-pr/usbcon/winusb.md index 3292dbfd9a..9f0d99b6ad 100644 --- a/windows-driver-docs-pr/usbcon/winusb.md +++ b/windows-driver-docs-pr/usbcon/winusb.md @@ -1,6 +1,7 @@ --- Description: This section describes the generic WinUSB driver (Winusb.sys) and its user-mode component (Winusb.dll) provided by Microsoft for all USB devices. title: WinUSB (Winusb.sys) +author: windows-driver-content ms.author: windowsdriverdev ms.date: 04/20/2017 ms.topic: article diff --git a/windows-driver-docs-pr/usbcon/wmcdc-device-management-model.md b/windows-driver-docs-pr/usbcon/wmcdc-device-management-model.md index 82fbcf8894..0d55402226 100644 --- a/windows-driver-docs-pr/usbcon/wmcdc-device-management-model.md +++ b/windows-driver-docs-pr/usbcon/wmcdc-device-management-model.md @@ -1,6 +1,7 @@ --- Description: WMCDC Device Management Model title: WMCDC Device Management Model +author: windows-driver-content --- # WMCDC Device Management Model @@ -46,15 +47,15 @@ USB WMCDC Device Management Model (DMM) interface collections have the following - + - diff --git a/windows-driver-docs-pr/usbcon/writing-a-ude-client-driver.md b/windows-driver-docs-pr/usbcon/writing-a-ude-client-driver.md index 552007b058..4416e69355 100644 --- a/windows-driver-docs-pr/usbcon/writing-a-ude-client-driver.md +++ b/windows-driver-docs-pr/usbcon/writing-a-ude-client-driver.md @@ -117,17 +117,17 @@ Here is the summary of the sequence in which the client driver retrieves a WDFDE ... - WdfDeviceInitSetPnpPowerEventCallbacks(WdfDeviceInit, &wdfPnpPowerCallbacks); + WdfDeviceInitSetPnpPowerEventCallbacks(WdfDeviceInit, &wdfPnpPowerCallbacks); - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfRequestAttributes, REQUEST_CONTEXT); - WdfDeviceInitSetRequestAttributes(WdfDeviceInit, &wdfRequestAttributes); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfRequestAttributes, REQUEST_CONTEXT); + WdfDeviceInitSetRequestAttributes(WdfDeviceInit, &wdfRequestAttributes); // To distinguish I/O sent to GUID_DEVINTERFACE_USB_HOST_CONTROLLER, we will enable // enable interface reference strings by calling WdfDeviceInitSetFileObjectConfig // with FileObjectClass WdfFileObjectWdfXxx. - WDF_FILEOBJECT_CONFIG_INIT(&fileConfig, + WDF_FILEOBJECT_CONFIG_INIT(&fileConfig, WDF_NO_EVENT_CALLBACK, WDF_NO_EVENT_CALLBACK, WDF_NO_EVENT_CALLBACK // No cleanup callback function @@ -136,7 +136,7 @@ Here is the summary of the sequence in which the client driver retrieves a WDFDE ... WdfDeviceInitSetFileObjectConfig(WdfDeviceInit, - &fileConfig, + &fileConfig, WDF_NO_OBJECT_ATTRIBUTES); ... @@ -147,7 +147,7 @@ Here is the summary of the sequence in which the client driver retrieves a WDFDE ... - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfDeviceAttributes, WDFDEVICE_CONTEXT); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&wdfDeviceAttributes, WDFDEVICE_CONTEXT); wdfDeviceAttributes.EvtCleanupCallback = _ControllerWdfEvtCleanupCallback; @@ -159,14 +159,14 @@ Here is the summary of the sequence in which the client driver retrieves a WDFDE for (instanceNumber = 0; instanceNumber < ULONG_MAX; instanceNumber++) { - status = RtlUnicodeStringPrintf(&uniDeviceName, + status = RtlUnicodeStringPrintf(&uniDeviceName, L"%ws%d", BASE_DEVICE_NAME, instanceNumber); ... - status = WdfDeviceInitAssignName(*WdfDeviceInit, &uniDeviceName); + status = WdfDeviceInitAssignName(*WdfDeviceInit, &uniDeviceName); ... @@ -198,45 +198,45 @@ Here is the summary of the sequence in which the client driver retrieves a WDFDE // Create the symbolic link (also for compatibility). - status = RtlUnicodeStringPrintf(&uniSymLinkName, + status = RtlUnicodeStringPrintf(&uniSymLinkName, L"%ws%d", BASE_SYMBOLIC_LINK_NAME, instanceNumber); ... - status = WdfDeviceCreateSymbolicLink(*WdfDevice, &uniSymLinkName); + status = WdfDeviceCreateSymbolicLink(*WdfDevice, &uniSymLinkName); ... // Create the device interface. - RtlInitUnicodeString(&refString, + RtlInitUnicodeString(&refString, USB_HOST_DEVINTERFACE_REF_STRING); status = WdfDeviceCreateDeviceInterface(wdfDevice, - (LPGUID)&GUID_DEVINTERFACE_USB_HOST_CONTROLLER, - &refString); + (LPGUID)&GUID_DEVINTERFACE_USB_HOST_CONTROLLER, + &refString); ... - UDECX_WDF_DEVICE_CONFIG_INIT(&controllerConfig, Controller_EvtUdecxWdfDeviceQueryUsbCapability); + UDECX_WDF_DEVICE_CONFIG_INIT(&controllerConfig, Controller_EvtUdecxWdfDeviceQueryUsbCapability); status = UdecxWdfDeviceAddUsbDeviceEmulation(wdfDevice, - &controllerConfig); + &controllerConfig); // Create default queue. It only supports USB controller IOCTLs. (USB I/O will come through // in separate USB device queues.) // Shown later in this topic. - WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&defaultQueueConfig, WdfIoQueueDispatchSequential); + WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(&defaultQueueConfig, WdfIoQueueDispatchSequential); defaultQueueConfig.EvtIoDeviceControl = ControllerEvtIoDeviceControl; defaultQueueConfig.PowerManaged = WdfFalse; status = WdfIoQueueCreate(wdfDevice, - &defaultQueueConfig, + &defaultQueueConfig, WDF_NO_OBJECT_ATTRIBUTES, - &pControllerContext->DefaultQueue); + &pControllerContext->DefaultQueue); ... @@ -333,7 +333,7 @@ Controller_EvtControllerQueryUsbCapability( *ResultLength = 0; if (RtlCompareMemory(CapabilityType, - &GUID_USB_CAPABILITY_CHAINED_MDLS, + &GUID_USB_CAPABILITY_CHAINED_MDLS, sizeof(GUID)) == sizeof(GUID)) { // @@ -464,7 +464,7 @@ Usb_Initialize( // State changed callbacks - UDECX_USB_DEVICE_CALLBACKS_INIT(&callbacks); + UDECX_USB_DEVICE_CALLBACKS_INIT(&callbacks); #ifndef SIMPLEENDPOINTS callbacks.EvtUsbDeviceDefaultEndpointAdd = UsbDevice_EvtUsbDeviceDefaultEndpointAdd; callbacks.EvtUsbDeviceEndpointAdd = UsbDevice_EvtUsbDeviceEndpointAdd; @@ -474,7 +474,7 @@ Usb_Initialize( callbacks.EvtUsbDeviceLinkPowerExit = UsbDevice_EvtUsbDeviceLinkPowerExit; callbacks.EvtUsbDeviceSetFunctionSuspendAndWake = UsbDevice_EvtUsbDeviceSetFunctionSuspendAndWake; - UdecxUsbDeviceInitSetStateChangeCallbacks(usbContext->UdecxUsbDeviceInit, &callbacks); + UdecxUsbDeviceInitSetStateChangeCallbacks(usbContext->UdecxUsbDeviceInit, &callbacks); // Set required attributes. @@ -527,7 +527,7 @@ Usb_Initialize( } status = UdecxUsbDeviceInitAddStringDescriptor(usbContext->UdecxUsbDeviceInit, - &g_ManufacturerStringEnUs, + &g_ManufacturerStringEnUs, g_ManufacturerIndex, US_ENGLISH); @@ -536,11 +536,11 @@ Usb_Initialize( goto exit; } - WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, UDECX_USBDEVICE_CONTEXT); + WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, UDECX_USBDEVICE_CONTEXT); - status = UdecxUsbDeviceCreate(&usbContext->UdecxUsbDeviceInit, - &attributes, - &usbContext->UdecxUsbDevice); + status = UdecxUsbDeviceCreate(&usbContext->UdecxUsbDeviceInit, + &attributes, + &usbContext->UdecxUsbDevice); if (!NT_SUCCESS(status)) { @@ -560,13 +560,13 @@ Usb_Initialize( #endif - UDECX_USB_DEVICE_PLUG_IN_OPTIONS_INIT(&pluginOptions); + UDECX_USB_DEVICE_PLUG_IN_OPTIONS_INIT(&pluginOptions); #ifdef USB30 pluginOptions.Usb30PortNumber = 2; #else pluginOptions.Usb20PortNumber = 1; #endif - status = UdecxUsbDevicePlugIn(usbContext->UdecxUsbDevice, &pluginOptions); + status = UdecxUsbDevicePlugIn(usbContext->UdecxUsbDevice, &pluginOptions); exit: @@ -651,14 +651,14 @@ UsbCreateControlEndpoint( pUsbContext = WdfDeviceGetUsbContext(WdfDevice); endpointInit = NULL; - WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential); + WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential); queueConfig.EvtIoInternalDeviceControl = IoEvtControlUrb; status = WdfIoQueueCreate (Device, - &queueConfig, + &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, - &controlQueue); + &controlQueue); if (!NT_SUCCESS(status)) { @@ -676,15 +676,15 @@ UsbCreateControlEndpoint( UdecxUsbEndpointInitSetEndpointAddress(endpointInit, USB_DEFAULT_ENDPOINT_ADDRESS); - UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset); - UdecxUsbEndpointInitSetCallbacks(endpointInit, &callbacks); + UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset); + UdecxUsbEndpointInitSetCallbacks(endpointInit, &callbacks); callbacks.EvtUsbEndpointStart = UsbEndpointEvtStart; callbacks.EvtUsbEndpointPurge = UsEndpointEvtPurge; - status = UdecxUsbEndpointCreate(&endpointInit, + status = UdecxUsbEndpointCreate(&endpointInit, WDF_NO_OBJECT_ATTRIBUTES, - &pUsbContext->UdecxUsbControlEndpoint); + &pUsbContext->UdecxUsbControlEndpoint); if (!NT_SUCCESS(status)) { goto exit; @@ -753,14 +753,14 @@ UsbDevice_EvtUsbDeviceDefaultEndpointAdd( deviceContext = UdecxDeviceGetContext(UdecxUsbDevice); - WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential); + WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential); queueConfig.EvtIoInternalDeviceControl = IoEvtControlUrb; status = WdfIoQueueCreate (deviceContext->WdfDevice, - &queueConfig, + &queueConfig, WDF_NO_OBJECT_ATTRIBUTES, - &controlQueue); + &controlQueue); if (!NT_SUCCESS(status)) { @@ -769,12 +769,12 @@ UsbDevice_EvtUsbDeviceDefaultEndpointAdd( UdecxUsbEndpointInitSetEndpointAddress(UdecxUsbEndpointInit, USB_DEFAULT_DEVICE_ADDRESS); - UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset); - UdecxUsbEndpointInitSetCallbacks(UdecxUsbEndpointInit, &callbacks); + UDECX_USB_ENDPOINT_CALLBACKS_INIT(&callbacks, UsbEndpointReset); + UdecxUsbEndpointInitSetCallbacks(UdecxUsbEndpointInit, &callbacks); status = UdecxUsbEndpointCreate(UdecxUsbEndpointInit, WDF_NO_OBJECT_ATTRIBUTES, - &deviceContext->UdecxUsbControlEndpoint); + &deviceContext->UdecxUsbControlEndpoint); if (!NT_SUCCESS(status)) { goto exit; diff --git a/windows-driver-docs-pr/wdf/a-device-enters-a-low-power-state-umdf.md b/windows-driver-docs-pr/wdf/a-device-enters-a-low-power-state-umdf.md index af8b6c22f0..cc7dc2560f 100644 --- a/windows-driver-docs-pr/wdf/a-device-enters-a-low-power-state-umdf.md +++ b/windows-driver-docs-pr/wdf/a-device-enters-a-low-power-state-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # A Device Enters a Low-Power State -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A device leaves its working (D0) state and enters a low-power state if one of the following occurs: diff --git a/windows-driver-docs-pr/wdf/a-device-returns-to-its-working-state-umdf.md b/windows-driver-docs-pr/wdf/a-device-returns-to-its-working-state-umdf.md index f161ae811c..329cb34ae8 100644 --- a/windows-driver-docs-pr/wdf/a-device-returns-to-its-working-state-umdf.md +++ b/windows-driver-docs-pr/wdf/a-device-returns-to-its-working-state-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # A Device Returns to Its Working State -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A device that is in a low-power state returns to its working state if one of the following occurs: diff --git a/windows-driver-docs-pr/wdf/a-user-plugs-in-a-device-umdf.md b/windows-driver-docs-pr/wdf/a-user-plugs-in-a-device-umdf.md index c553d6876d..dfdb931d34 100644 --- a/windows-driver-docs-pr/wdf/a-user-plugs-in-a-device-umdf.md +++ b/windows-driver-docs-pr/wdf/a-user-plugs-in-a-device-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # A User Plugs in a Device -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a user plugs in a device, the framework calls a UMDF driver's PnP and Power Management callback methods in the following sequence, starting from the Device Arrived state at the bottom of the figure: diff --git a/windows-driver-docs-pr/wdf/a-user-unplugs-a-device-umdf.md b/windows-driver-docs-pr/wdf/a-user-unplugs-a-device-umdf.md index b5a5ad4ace..3d483c5b8a 100644 --- a/windows-driver-docs-pr/wdf/a-user-unplugs-a-device-umdf.md +++ b/windows-driver-docs-pr/wdf/a-user-unplugs-a-device-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # A User Unplugs a Device -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] While a system is running, a user can remove a device in one of the following two ways: by *orderly removal*, which means that the user informs the system that the device is about to be removed (for example, by using the Unplug or Eject Hardware program); or by *surprise removal*, which means that the user unplugs the device without informing the system. If the bus supports surprise removal (for example, USB), the device's drivers must be able to handle the device's sudden disappearance. diff --git a/windows-driver-docs-pr/wdf/accessing-data-buffers-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/accessing-data-buffers-in-umdf-1-x-drivers.md index a45edf6156..09e59bddfc 100644 --- a/windows-driver-docs-pr/wdf/accessing-data-buffers-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/accessing-data-buffers-in-umdf-1-x-drivers.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Accessing Data Buffers in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a driver receives a read, write, or device I/O control request, the request object contains either an input buffer or an output buffer, or both. (A few device I/O control requests provide two input, two output, or two input/output buffers.) diff --git a/windows-driver-docs-pr/wdf/accessing-hardware-and-handling-interrupts.md b/windows-driver-docs-pr/wdf/accessing-hardware-and-handling-interrupts.md index 8301b56fd5..4236ddc567 100644 --- a/windows-driver-docs-pr/wdf/accessing-hardware-and-handling-interrupts.md +++ b/windows-driver-docs-pr/wdf/accessing-hardware-and-handling-interrupts.md @@ -12,6 +12,7 @@ ms.technology: windows-devices # Accessing Hardware and Handling Interrupts +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Starting in UMDF 1.11, UMDF drivers can retrieve hardware resources that the system has assigned to the device, directly read or write to device registers that the system has assigned and mapped to memory space or I/O port space, and connect and service hardware interrupts. diff --git a/windows-driver-docs-pr/wdf/accessing-umdf-metadata-in-wer-reports.md b/windows-driver-docs-pr/wdf/accessing-umdf-metadata-in-wer-reports.md index 6569975d1f..e3d73f35b0 100644 --- a/windows-driver-docs-pr/wdf/accessing-umdf-metadata-in-wer-reports.md +++ b/windows-driver-docs-pr/wdf/accessing-umdf-metadata-in-wer-reports.md @@ -32,7 +32,7 @@ get-winevent -providername "Windows Error Reporting" | where-object {$_.Message The following is a sample UMDF WER report of type **WUDFHostProblem**. It was obtained from the ReportQueue directory described above. If you use PowerShell to retrieve the reports, the fields may be labeled P0, P1, P2 instead of Sig\[0\], Sig\[1\], Sig\[2\]. Otherwise, the fields are the same and contain the same possible values. This sample was generated from one of the WDK samples that use the OSR USB-FX2 hardware reference board. -``` syntax +``` Sig[0].Name=EventClass Sig[0].Value=HostProblem Sig[1].Name=Problem diff --git a/windows-driver-docs-pr/wdf/adding-a-device-overview.md b/windows-driver-docs-pr/wdf/adding-a-device-overview.md index f37999f0e4..beeb45aa69 100644 --- a/windows-driver-docs-pr/wdf/adding-a-device-overview.md +++ b/windows-driver-docs-pr/wdf/adding-a-device-overview.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # Adding a Device Overview -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following figure shows an overview of how the framework adds a new device: diff --git a/windows-driver-docs-pr/wdf/adding-a-device.md b/windows-driver-docs-pr/wdf/adding-a-device.md index 027c27b990..99eafcc301 100644 --- a/windows-driver-docs-pr/wdf/adding-a-device.md +++ b/windows-driver-docs-pr/wdf/adding-a-device.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # Adding a Device -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework adds a device object for each device loaded in the driver host process. To add the device, the framework calls the driver's [**IDriverEntry::OnDeviceAdd**](https://msdn.microsoft.com/library/windows/hardware/ff554896) method and passes the [IWDFDriver](https://msdn.microsoft.com/library/windows/hardware/ff558893) and [IWDFDeviceInitialize](https://msdn.microsoft.com/library/windows/hardware/ff556965) interfaces in the call. The supplied **IWDFDeviceInitialize** interface is only valid before the driver calls [**IWDFDriver::CreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff558899). The driver can call the following methods of **IWDFDeviceInitialize** to perform the following operations: diff --git a/windows-driver-docs-pr/wdf/associating-callback-interfaces-example.md b/windows-driver-docs-pr/wdf/associating-callback-interfaces-example.md index 3f9a153c76..d287fe34cb 100644 --- a/windows-driver-docs-pr/wdf/associating-callback-interfaces-example.md +++ b/windows-driver-docs-pr/wdf/associating-callback-interfaces-example.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Associating Callback Interfaces Example -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following code example shows how a driver implements a create-instance method that the driver uses to [create the device callback object](creating-callback-objects-example.md). The driver allocates the callback context and associates the supplied **IUnknown** with one or more callback interfaces. The framework can subsequently use **QueryInterface** to discover the callback interfaces supported by the driver. diff --git a/windows-driver-docs-pr/wdf/canceling-i-o-requests-umdf.md b/windows-driver-docs-pr/wdf/canceling-i-o-requests-umdf.md index 888f5e3909..a7f52c1e69 100644 --- a/windows-driver-docs-pr/wdf/canceling-i-o-requests-umdf.md +++ b/windows-driver-docs-pr/wdf/canceling-i-o-requests-umdf.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Canceling I/O Requests in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A device's in-progress I/O operation (such as a request to read several blocks from a disk) can be canceled by an application, the system, or a driver. If a device's I/O operation is canceled, the I/O Manager attempts to cancel all unprocessed I/O requests that are associated with the I/O operation. The device's drivers can register to be notified when the I/O Manager attempts to cancel I/O requests, and the drivers can cancel the requests that they own by [completing](completing-i-o-requests.md) them with a completion status of HRESULT\_FROM\_WIN32(ERROR\_OPERATION\_ABORTED). diff --git a/windows-driver-docs-pr/wdf/choosing-a-driver-model-for-a-usb-device.md b/windows-driver-docs-pr/wdf/choosing-a-driver-model-for-a-usb-device.md index 2b7872c5f9..1454665cb4 100644 --- a/windows-driver-docs-pr/wdf/choosing-a-driver-model-for-a-usb-device.md +++ b/windows-driver-docs-pr/wdf/choosing-a-driver-model-for-a-usb-device.md @@ -19,6 +19,7 @@ ms.technology: windows-devices # Choosing a Driver Model for a USB Device +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] For information about how to determine what type of driver you need for your USB device, see [Choosing a driver model for developing a USB client driver](https://msdn.microsoft.com/library/windows/hardware/ff540215). diff --git a/windows-driver-docs-pr/wdf/combining-dispatch-and-synchronization-modes.md b/windows-driver-docs-pr/wdf/combining-dispatch-and-synchronization-modes.md index 74cde78683..0be228b9ee 100644 --- a/windows-driver-docs-pr/wdf/combining-dispatch-and-synchronization-modes.md +++ b/windows-driver-docs-pr/wdf/combining-dispatch-and-synchronization-modes.md @@ -21,6 +21,7 @@ ms.technology: windows-devices # Combining Dispatch and Synchronization Modes +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Combining a particular [queue dispatch mode](configuring-dispatch-mode-for-an-i-o-queue.md) with a [synchronization mode](specifying-a-callback-synchronization-mode.md) provides the mode of operation, as shown in the following diagram. diff --git a/windows-driver-docs-pr/wdf/completing-i-o-requests-umdf.md b/windows-driver-docs-pr/wdf/completing-i-o-requests-umdf.md index a100194224..282a56ad42 100644 --- a/windows-driver-docs-pr/wdf/completing-i-o-requests-umdf.md +++ b/windows-driver-docs-pr/wdf/completing-i-o-requests-umdf.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Completing I/O Requests in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Every I/O request must eventually be completed by a UMDF driver. To complete a request, the driver must call either the [**IWDFIoRequest::Complete**](https://msdn.microsoft.com/library/windows/hardware/ff559070) or [**IWDFIoRequest::CompleteWithInformation**](https://msdn.microsoft.com/library/windows/hardware/ff559074) method. When the driver completes the request, it indicates one of the following scenarios: diff --git a/windows-driver-docs-pr/wdf/configuring-dispatch-mode-for-an-i-o-queue.md b/windows-driver-docs-pr/wdf/configuring-dispatch-mode-for-an-i-o-queue.md index b75ccd3b31..d16f38816b 100644 --- a/windows-driver-docs-pr/wdf/configuring-dispatch-mode-for-an-i-o-queue.md +++ b/windows-driver-docs-pr/wdf/configuring-dispatch-mode-for-an-i-o-queue.md @@ -22,7 +22,7 @@ ms.technology: windows-devices # Configuring Dispatch Mode for an I/O Queue -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When I/O requests from applications arrive, the framework places each request in the appropriate I/O queue. How and when the requests are delivered to the driver depend on how the driver configures dispatching for the I/O queue and on how the driver [specifies callback-function synchronization](specifying-a-callback-synchronization-mode.md). The I/O queue also interacts with the PnP and power management subsystem of UMDF to hold I/O requests in the queue until the device reaches the proper state. diff --git a/windows-driver-docs-pr/wdf/controlling-a-general-i-o-target-s-state-in-umdf.md b/windows-driver-docs-pr/wdf/controlling-a-general-i-o-target-s-state-in-umdf.md index b881d38cdc..7bef14e6de 100644 --- a/windows-driver-docs-pr/wdf/controlling-a-general-i-o-target-s-state-in-umdf.md +++ b/windows-driver-docs-pr/wdf/controlling-a-general-i-o-target-s-state-in-umdf.md @@ -24,7 +24,7 @@ ms.technology: windows-devices # Controlling a General I/O Target's State in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework defines the following states for general I/O targets: diff --git a/windows-driver-docs-pr/wdf/controlling-device-access-in-kmdf-drivers.md b/windows-driver-docs-pr/wdf/controlling-device-access-in-kmdf-drivers.md index 2301f5bd04..6d9c6e2ee2 100644 --- a/windows-driver-docs-pr/wdf/controlling-device-access-in-kmdf-drivers.md +++ b/windows-driver-docs-pr/wdf/controlling-device-access-in-kmdf-drivers.md @@ -35,7 +35,7 @@ Physical device objects (PDOs) must have names. Typically, framework-based bus d On the other hand, a framework-based driver can assign a device name to a device object by calling [**WdfDeviceInitAssignName**](https://msdn.microsoft.com/library/windows/hardware/ff546029). A driver should name a functional device object (FDO), filter device object (filter DO), or PDO only if the driver must support an older application that expects a specific device name, or if the driver belongs to an older driver stack whose architecture requires object names. -Instead of naming FDOs and filter DOs, WDM drivers and framework-based drivers should provide raw mode, without a function driver. +Instead of naming FDOs and filter DOs, WDM drivers and framework-based drivers should provide device interfaces that applications can access. The operating system obtains a device interface's security descriptor from the device's PDO and from registry entries that a driver package's INF file specifies. A bus driver can provide device interfaces for a PDO if the driver's devices operate in raw mode, without a function driver. Some drivers must call [**WdfDeviceCreateSymbolicLink**](https://msdn.microsoft.com/library/windows/hardware/ff545939) to create symbolic link names for their devices. For example, a driver might create an [MS-DOS device name](https://msdn.microsoft.com/library/windows/hardware/ff548088) if applications expect to see an MS-DOS name for the device. If your driver creates a symbolic link name for an unnamed FDO or filter DO, the framework associates the symbolic link name with the PDO's name. (Control devices are not associated with a PDO, so your driver cannot create a symbolic link name for an unnamed control device.) diff --git a/windows-driver-docs-pr/wdf/controlling-device-access.md b/windows-driver-docs-pr/wdf/controlling-device-access.md index c210301850..888b74a21a 100644 --- a/windows-driver-docs-pr/wdf/controlling-device-access.md +++ b/windows-driver-docs-pr/wdf/controlling-device-access.md @@ -19,7 +19,7 @@ Starting in Windows 8, the operating system includes a security identifier (SID The SID for UMDF drivers is SDDL\_USER\_MODE\_DRIVERS, and the definition is in sddl.h. The full representation of this SID is: -``` syntax +``` S-1-5-84-0-0-0-0-0 ``` @@ -34,13 +34,13 @@ In the INF file, you can use either the abbreviated form or the fully specified The abbreviated form is available starting in Windows 8: -``` syntax +``` HKR,,Security,,"D:P(A;;GA;;;BA)(A;;GA;;;SY)(A;;GA;;;UD)" ``` On operating systems earlier than Windows 8, you must use the fully specified form: -``` syntax +``` HKR,,Security,,"D:P(A;;GA;;;BA)(A;;GA;;;SY)(A;;GA;;;S-1-5-84-0-0-0-0-0)" ``` diff --git a/windows-driver-docs-pr/wdf/creating-a-file-object-to-handle-i-o.md b/windows-driver-docs-pr/wdf/creating-a-file-object-to-handle-i-o.md index 6f70f549ef..a99ec750bc 100644 --- a/windows-driver-docs-pr/wdf/creating-a-file-object-to-handle-i-o.md +++ b/windows-driver-docs-pr/wdf/creating-a-file-object-to-handle-i-o.md @@ -19,6 +19,7 @@ ms.technology: windows-devices # Creating a File Object to Handle I/O +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When an application opens a file handle, the I/O manager creates a file object. The framework in turn creates a framework file object to represent the I/O manager's file object. diff --git a/windows-driver-docs-pr/wdf/creating-an-interrupt-object-umdf.md b/windows-driver-docs-pr/wdf/creating-an-interrupt-object-umdf.md index 11ad38086b..2bcc76ca0f 100644 --- a/windows-driver-docs-pr/wdf/creating-an-interrupt-object-umdf.md +++ b/windows-driver-docs-pr/wdf/creating-an-interrupt-object-umdf.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Creating an Interrupt Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A UMDF driver that handles a device's hardware interrupts must create a framework interrupt object for each interrupt that each device can support. diff --git a/windows-driver-docs-pr/wdf/creating-and-using-driver-created-file-objects.md b/windows-driver-docs-pr/wdf/creating-and-using-driver-created-file-objects.md index b29117781a..0c56ef126c 100644 --- a/windows-driver-docs-pr/wdf/creating-and-using-driver-created-file-objects.md +++ b/windows-driver-docs-pr/wdf/creating-and-using-driver-created-file-objects.md @@ -21,7 +21,7 @@ ms.technology: windows-devices # Creating and Using Driver-Created File Objects -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If your driver needs to create and send an I/O request that is independent of the application to the next driver in the stack (the default I/O target), the driver must create and close its own file objects. diff --git a/windows-driver-docs-pr/wdf/creating-callback-objects-example.md b/windows-driver-docs-pr/wdf/creating-callback-objects-example.md index eef3df303a..084cf4ce1b 100644 --- a/windows-driver-docs-pr/wdf/creating-callback-objects-example.md +++ b/windows-driver-docs-pr/wdf/creating-callback-objects-example.md @@ -15,7 +15,7 @@ ms.technology: windows-devices # Creating Callback Objects Example -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following code example shows how a driver creates a device callback object in the implementation of its [**IDriverEntry::OnDeviceAdd**](https://msdn.microsoft.com/library/windows/hardware/ff554896) method and then passes a pointer to the device callback interface in its call to the [**IWDFDriver::CreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff558899) method to create the device. diff --git a/windows-driver-docs-pr/wdf/creating-callback-objects.md b/windows-driver-docs-pr/wdf/creating-callback-objects.md index c70b855015..57490231ae 100644 --- a/windows-driver-docs-pr/wdf/creating-callback-objects.md +++ b/windows-driver-docs-pr/wdf/creating-callback-objects.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Creating Callback Objects -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A UMDF driver can create *callback objects*, which consist of context data and interface methods. The framework accesses the driver's callback objects through the driver's callback interface methods. diff --git a/windows-driver-docs-pr/wdf/debugging-power-reference-leaks-in-wdf.md b/windows-driver-docs-pr/wdf/debugging-power-reference-leaks-in-wdf.md index 1ae79f9d8e..476e3416d6 100644 --- a/windows-driver-docs-pr/wdf/debugging-power-reference-leaks-in-wdf.md +++ b/windows-driver-docs-pr/wdf/debugging-power-reference-leaks-in-wdf.md @@ -41,7 +41,7 @@ For a UMDF driver: **HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\WUDF\\Services\\<Driver Service Name>\\Parameters\\Wdf** -``` syntax +``` (REG_DWORD) VerifierOn = 0x1 (REG_DWORD) TrackPower = 0x0 (disabled) = 0x1 (capture tick count, file name, line number) @@ -71,14 +71,14 @@ if (NT_SUCCESS(status)) { To display the power references taken on the device, as well as a tag tracker that shows the reference history, use [**!wdfkd.wdfdevice**](https://msdn.microsoft.com/library/windows/hardware/ff565703) with verbose flags: -``` syntax +``` kd> !wdfkd.wdfdevice 0x6d939790 ff Power references: 0 !wdftagtracker 0x9ea030a8 ``` Calling the [**!wdfkd.wdftagtracker**](https://msdn.microsoft.com/library/windows/hardware/ff566126) shows the device’s power reference history: -``` syntax +``` kd> !wdftagtracker 0x9ea030a8 Reference and Release History: # (showing most recent first; refcount is approximate in multi-threaded scenarios) @@ -99,7 +99,7 @@ Reference and Release History: Optionally, specify a tag name to facilitate identification of specific power references. To do so, use [**WdfDeviceStopIdleWithTag**](https://msdn.microsoft.com/library/windows/hardware/dn932460) and [**WdfDeviceResumeIdleWithTag**](https://msdn.microsoft.com/library/windows/hardware/dn932459): -``` syntax +``` status = WdfDeviceStopIdleWithTag(device, FALSE, (PVOID)'oyeH'); if (NT_SUCCESS(status)) { WdfDeviceResumeIdleWithTag(device, (PVOID)'oyeH'); @@ -108,7 +108,7 @@ if (NT_SUCCESS(status)) { Corresponding [**!wdftagtracker**](https://msdn.microsoft.com/library/windows/hardware/ff566126) sample output: -``` syntax +``` (--) 0 ref: Tag 'Heyo' at Time 0x24e40 ticks ## path\to\your\driver\code.c @ 374 diff --git a/windows-driver-docs-pr/wdf/defining-callback-objects-example.md b/windows-driver-docs-pr/wdf/defining-callback-objects-example.md index 931c02240f..e51311b664 100644 --- a/windows-driver-docs-pr/wdf/defining-callback-objects-example.md +++ b/windows-driver-docs-pr/wdf/defining-callback-objects-example.md @@ -15,7 +15,7 @@ ms.technology: windows-devices # Defining Callback Objects Example -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following code example shows how a driver inherits from the [IPnpCallbackHardware](https://msdn.microsoft.com/library/windows/hardware/ff556764) interface to define a device callback object. diff --git a/windows-driver-docs-pr/wdf/deleting-an-interrupt-object.md b/windows-driver-docs-pr/wdf/deleting-an-interrupt-object.md index e518768c27..bf3b8d9b36 100644 --- a/windows-driver-docs-pr/wdf/deleting-an-interrupt-object.md +++ b/windows-driver-docs-pr/wdf/deleting-an-interrupt-object.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Deleting an Interrupt Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If the driver creates an interrupt object by calling [**IWDFDevice3::CreateInterrupt**](https://msdn.microsoft.com/library/windows/hardware/hh451208), the driver does not need to delete the interrupt object. The framework deletes the interrupt object automatically because the interrupt object is a child object of the framework device object. diff --git a/windows-driver-docs-pr/wdf/determining-why-a-umdf-driver-consumes-an-excessive-amount-of-memory.md b/windows-driver-docs-pr/wdf/determining-why-a-umdf-driver-consumes-an-excessive-amount-of-memory.md index df651f0331..2e86be6f7f 100644 --- a/windows-driver-docs-pr/wdf/determining-why-a-umdf-driver-consumes-an-excessive-amount-of-memory.md +++ b/windows-driver-docs-pr/wdf/determining-why-a-umdf-driver-consumes-an-excessive-amount-of-memory.md @@ -16,6 +16,7 @@ ms.technology: windows-devices # Determining Why a UMDF Driver Consumes an Excessive Amount of Memory +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] This topic describes how you can use the Wudfext.dll debugger extensions in conjunction with a User-Mode Driver Framework (UMDF) version 1 driver to determine why a UMDF driver consumes an excessive amount of memory. diff --git a/windows-driver-docs-pr/wdf/driver-created-versus-application-created-file-objects.md b/windows-driver-docs-pr/wdf/driver-created-versus-application-created-file-objects.md index f73f43d8e9..17b4fef274 100644 --- a/windows-driver-docs-pr/wdf/driver-created-versus-application-created-file-objects.md +++ b/windows-driver-docs-pr/wdf/driver-created-versus-application-created-file-objects.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Driver-Created Versus Application-Created File Objects -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When an application opens a handle to a device, the framework calls your driver's [**IQueueCallbackCreate::OnCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff556841) method and supplies a pointer to the [**IWDFFile**](https://msdn.microsoft.com/library/windows/hardware/ff558912) interface for the file object that is associated with the device. Any I/O requests that the application sends to the opened handle are associated with the created file object. When such requests arrive, the framework calls the appropriate method from one of the driver-supplied [UMDF Queue Object Interfaces](https://msdn.microsoft.com/library/windows/hardware/ff561301). The driver can then call [**IWDFIoRequest::GetFileObject**](https://msdn.microsoft.com/library/windows/hardware/ff559099) to determine the file object associated with the request. The driver can call [**AssignContext**](https://msdn.microsoft.com/library/windows/hardware/ff560208) on the file object to associate context that is is specific to the I/O session. diff --git a/windows-driver-docs-pr/wdf/enabling-a-debugger.md b/windows-driver-docs-pr/wdf/enabling-a-debugger.md index 830c63ae57..b38db29261 100644 --- a/windows-driver-docs-pr/wdf/enabling-a-debugger.md +++ b/windows-driver-docs-pr/wdf/enabling-a-debugger.md @@ -38,7 +38,7 @@ The following are recommended settings. You can set these manually, or use the [ - Enable Application Verifier on WUDFHost.exe: - ``` syntax + ``` AppVerif –enable Heaps Exceptions Handles Locks Memory TLS Leak –for WudfHost.exe ``` diff --git a/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts-umdf.md b/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts-umdf.md index 8831a5c8a6..6fa5adcac6 100644 --- a/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts-umdf.md +++ b/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts-umdf.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Enabling and Disabling Interrupts -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If your driver handles device interrupts, it must provide [*OnInterruptEnable*](https://msdn.microsoft.com/library/windows/hardware/hh463899) and [*OnInterruptDisable*](https://msdn.microsoft.com/library/windows/hardware/hh463895) callback functions that enable and disable the interrupts. These callback functions must do whatever is necessary to enable and disable a device's interrupt mechanism. diff --git a/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts.md b/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts.md index a6de9b4db7..dc0817ad87 100644 --- a/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts.md +++ b/windows-driver-docs-pr/wdf/enabling-and-disabling-interrupts.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Enabling and Disabling Interrupts -If your driver handles device interrupts, it must provide DIRQL and must do whatever is necessary to enable and disable a device's interrupt mechanism. For [passive-level interrupts](supporting-passive-level-interrupts.md), these callback functions run at IRQL = PASSIVE\_LEVEL while holding the passive-level interrupt lock. +If your driver handles device interrupts, it must provide [*EvtInterruptEnable*](https://msdn.microsoft.com/library/windows/hardware/ff541730) and [*EvtInterruptDisable*](https://msdn.microsoft.com/library/windows/hardware/ff541714) callback functions that enable and disable the interrupts. Typically, these callback functions run at the device's DIRQL and must do whatever is necessary to enable and disable a device's interrupt mechanism. For [passive-level interrupts](supporting-passive-level-interrupts.md), these callback functions run at IRQL = PASSIVE_LEVEL while holding the passive-level interrupt lock. If your driver must perform additional operations that are related to enabling or disabling interrupts, and if these additional operations cannot be performed at IRQL = DIRQL, the driver can also provide [*EvtDeviceD0EntryPostInterruptsEnabled*](https://msdn.microsoft.com/library/windows/hardware/ff540853) and [*EvtDeviceD0ExitPreInterruptsDisabled*](https://msdn.microsoft.com/library/windows/hardware/ff540856) callback functions. These two callback functions run at IRQL = PASSIVE\_LEVEL with no interrupt lock held, and can call framework object methods that are unavailable at IRQL = DIRQL. diff --git a/windows-driver-docs-pr/wdf/enabling-hardware-access.md b/windows-driver-docs-pr/wdf/enabling-hardware-access.md index b391dda8db..e796ab957e 100644 --- a/windows-driver-docs-pr/wdf/enabling-hardware-access.md +++ b/windows-driver-docs-pr/wdf/enabling-hardware-access.md @@ -12,6 +12,7 @@ ms.technology: windows-devices # Enabling Hardware Access +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] To enable hardware access, a UMDF driver must set the **UmdfDirectHardwareAccess** INF directive to **AllowDirectHardwareAccess**. diff --git a/windows-driver-docs-pr/wdf/escaping-to-winusb.md b/windows-driver-docs-pr/wdf/escaping-to-winusb.md index b62c241272..90c21dc1d1 100644 --- a/windows-driver-docs-pr/wdf/escaping-to-winusb.md +++ b/windows-driver-docs-pr/wdf/escaping-to-winusb.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Calling WinUSB from UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A UMDF driver can call [WinUSB Functions](https://msdn.microsoft.com/library/windows/hardware/ff540046#winusb) directly if the driver cannot use the USB-specific UMDF interfaces to perform a specific operation. To call WinUSB Functions, the driver must first obtain a WinUSB interface handle by calling [**IWDFUsbTargetDevice::GetWinUsbHandle**](https://msdn.microsoft.com/library/windows/hardware/ff560369) or [**IWDFUsbInterface::GetWinUsbHandle**](https://msdn.microsoft.com/library/windows/hardware/ff560337). A WinUSB interface handle is used to define the first interface in the selected configuration. diff --git a/windows-driver-docs-pr/wdf/file-creation-by-a-usb-i-o-target.md b/windows-driver-docs-pr/wdf/file-creation-by-a-usb-i-o-target.md index 4e526a7c20..3b53d32362 100644 --- a/windows-driver-docs-pr/wdf/file-creation-by-a-usb-i-o-target.md +++ b/windows-driver-docs-pr/wdf/file-creation-by-a-usb-i-o-target.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # File Creation by a USB I/O Target -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] During its initialization, the USB I/O target creates an intra-stack file object, which represents a default session that the USB I/O target keeps open. For more information about an intra-stack file object, see [Creating a File Object to Handle I/O](creating-a-file-object-to-handle-i-o.md). The USB I/O target or its USB pipe target children use this file object to send any I/O that they originate (for example, I/O to obtain the USB configuration descriptor). diff --git a/windows-driver-docs-pr/wdf/finding-and-mapping-hardware-resources-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/finding-and-mapping-hardware-resources-in-umdf-1-x-drivers.md index c320b3807b..4e3a3837c7 100644 --- a/windows-driver-docs-pr/wdf/finding-and-mapping-hardware-resources-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/finding-and-mapping-hardware-resources-in-umdf-1-x-drivers.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Finding and Mapping Hardware Resources in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If you are using UMDF version 2.0 or later, see [Finding and Mapping Hardware Resources](finding-and-mapping-hardware-resources.md). diff --git a/windows-driver-docs-pr/wdf/framework-base-object.md b/windows-driver-docs-pr/wdf/framework-base-object.md index 959d20dee4..83ddb0c210 100644 --- a/windows-driver-docs-pr/wdf/framework-base-object.md +++ b/windows-driver-docs-pr/wdf/framework-base-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework Base Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework base object is exposed to drivers by the [IWDFObject](https://msdn.microsoft.com/library/windows/hardware/ff560200) interface. It provides basic functionality that is common across all framework object types. All framework objects are derived from this root object. diff --git a/windows-driver-docs-pr/wdf/framework-device-object.md b/windows-driver-docs-pr/wdf/framework-device-object.md index 6e5bcfcf56..043383b8ba 100644 --- a/windows-driver-docs-pr/wdf/framework-device-object.md +++ b/windows-driver-docs-pr/wdf/framework-device-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework Device Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework device object is exposed to drivers by the [IWDFDevice](https://msdn.microsoft.com/library/windows/hardware/ff556917) interface. The framework device object is the framework representation of the device on the system. Each device object has a parent driver object. diff --git a/windows-driver-docs-pr/wdf/framework-driver-object.md b/windows-driver-docs-pr/wdf/framework-driver-object.md index ac6bad1324..e842e03d7d 100644 --- a/windows-driver-docs-pr/wdf/framework-driver-object.md +++ b/windows-driver-docs-pr/wdf/framework-driver-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework Driver Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework driver object is exposed to drivers by the [IWDFDriver](https://msdn.microsoft.com/library/windows/hardware/ff558893) interface. It is the framework representation of the driver image loaded in the driver host process. The framework creates a new driver object for each driver loaded in the driver host process. The **IWDFDriver** interface is passed to the driver by the [**IDriverEntry::OnInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff554900) method, which is the main entry point for the user-mode driver. diff --git a/windows-driver-docs-pr/wdf/framework-file-object.md b/windows-driver-docs-pr/wdf/framework-file-object.md index a4672a2575..77a9d71dd6 100644 --- a/windows-driver-docs-pr/wdf/framework-file-object.md +++ b/windows-driver-docs-pr/wdf/framework-file-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework File Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework file object is exposed to drivers by the [IWDFFile](https://msdn.microsoft.com/library/windows/hardware/ff558912) interface. It is the framework representation of the opened device. When an application opens the device through the Microsoft Win32 [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function, the framework creates a file object to represent the opened device instance. Therefore, the framework file object is conceptually equivalent to the Win32 handle that is returned from the application's call to **CreateFile**. The framework can create multiple file objects associated with a single device. Each file object is created for each successful call to **CreateFile**. All I/O operations, like reads and writes, are targeted to a specific file-object instance. diff --git a/windows-driver-docs-pr/wdf/framework-i-o-queue-object.md b/windows-driver-docs-pr/wdf/framework-i-o-queue-object.md index 1b831799b2..5be6410dd3 100644 --- a/windows-driver-docs-pr/wdf/framework-i-o-queue-object.md +++ b/windows-driver-docs-pr/wdf/framework-i-o-queue-object.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # Framework I/O Queue Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework I/O queue object is exposed to drivers by the [IWDFIoQueue](https://msdn.microsoft.com/library/windows/hardware/ff558943) interface. It represents an I/O queue, which is a container for I/O requests. An I/O queue controls the flow of requests into the driver. When an I/O request arrives, it is placed in the appropriate queue. I/O queue objects are children of [UMDF device objects](framework-device-object.md). A driver can call the [**IWDFDevice::CreateIoQueue**](https://msdn.microsoft.com/library/windows/hardware/ff557020) method to create I/O queue objects. In the call to **IWDFDevice::CreateIoQueue**, the driver can specify whether the queue is the default queue. diff --git a/windows-driver-docs-pr/wdf/framework-i-o-request-object.md b/windows-driver-docs-pr/wdf/framework-i-o-request-object.md index 8d541906db..06949441e0 100644 --- a/windows-driver-docs-pr/wdf/framework-i-o-request-object.md +++ b/windows-driver-docs-pr/wdf/framework-i-o-request-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework I/O Request Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework I/O request object is exposed to drivers by the [IWDFIoRequest](https://msdn.microsoft.com/library/windows/hardware/ff558985) interface. It encapsulates the details of an I/O operation. All I/O requests are represented as framework I/O request objects. The reflector notifies the driver host process when the reflector receives an I/O request packet (IRP) as the result of an application I/O operation, such as, a call to the Microsoft Win32 [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) or **ReadFile** function. The framework, in response to the reflector notification, constructs a new request object and puts it in the appropriate I/O queue. The queue configuration and the locking model chosen by the user-mode driver determine when the request is presented to the driver. For more information, see [Configuring Dispatch Mode for an I/O Queue](configuring-dispatch-mode-for-an-i-o-queue.md) and [Specifying a Callback Synchronization Mode](specifying-a-callback-synchronization-mode.md). diff --git a/windows-driver-docs-pr/wdf/framework-i-o-target-object.md b/windows-driver-docs-pr/wdf/framework-i-o-target-object.md index a3fa2bd0ff..5db9fa74b0 100644 --- a/windows-driver-docs-pr/wdf/framework-i-o-target-object.md +++ b/windows-driver-docs-pr/wdf/framework-i-o-target-object.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # Framework I/O Target Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework I/O target object is exposed to drivers by the [IWDFIoTarget](https://msdn.microsoft.com/library/windows/hardware/ff559170) interface. It retrieves information about an I/O target, which typically represents a lower driver in the stack but can also represent another UMDF driver or the kernel-mode portion of the stack. The I/O target object provides UMDF drivers a way to send requests to another device. diff --git a/windows-driver-docs-pr/wdf/framework-interrupt-object.md b/windows-driver-docs-pr/wdf/framework-interrupt-object.md index 22c1975097..61417654f8 100644 --- a/windows-driver-docs-pr/wdf/framework-interrupt-object.md +++ b/windows-driver-docs-pr/wdf/framework-interrupt-object.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Framework Interrupt Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework interrupt object is exposed to drivers by the [**IWDFInterrupt**](https://msdn.microsoft.com/library/windows/hardware/hh451283) interface. It represents a hardware interrupt. Interrupt objects are children of [UMDF device objects](framework-device-object.md). A driver can call the [**IWDFDevice3::CreateInterrupt**](https://msdn.microsoft.com/library/windows/hardware/hh451208) method to create an interrupt object. diff --git a/windows-driver-docs-pr/wdf/framework-memory-object.md b/windows-driver-docs-pr/wdf/framework-memory-object.md index c96e84da83..a6f605389f 100644 --- a/windows-driver-docs-pr/wdf/framework-memory-object.md +++ b/windows-driver-docs-pr/wdf/framework-memory-object.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Framework Memory Object -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework memory object is exposed to drivers by the [IWDFMemory](https://msdn.microsoft.com/library/windows/hardware/ff559249) interface. It provides access to a memory block. diff --git a/windows-driver-docs-pr/wdf/framework-object-custom-types.md b/windows-driver-docs-pr/wdf/framework-object-custom-types.md index 23d4c5fbfa..021c572051 100644 --- a/windows-driver-docs-pr/wdf/framework-object-custom-types.md +++ b/windows-driver-docs-pr/wdf/framework-object-custom-types.md @@ -26,7 +26,7 @@ A driver can associate multiple custom types with a single framework object. A d In output from KMDF debugger extensions, custom type names are displayed along with other WDF object information. -``` syntax +``` WDF_Object_Name, [custom_Type1_Name, custom_Type2_Name] ``` diff --git a/windows-driver-docs-pr/wdf/framework-object-hierarchy.md b/windows-driver-docs-pr/wdf/framework-object-hierarchy.md index 328992cbd8..6b4c7970ba 100644 --- a/windows-driver-docs-pr/wdf/framework-object-hierarchy.md +++ b/windows-driver-docs-pr/wdf/framework-object-hierarchy.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Framework Object Hierarchy -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following figure shows the parent-child framework object hierarchy. diff --git a/windows-driver-docs-pr/wdf/framework-objects.md b/windows-driver-docs-pr/wdf/framework-objects.md index 192c5fd634..9ac21ba737 100644 --- a/windows-driver-docs-pr/wdf/framework-objects.md +++ b/windows-driver-docs-pr/wdf/framework-objects.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Framework Objects -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following table provides basic information about each framework object, links to the object's interface, and links to more information about the core framework objects. diff --git a/windows-driver-docs-pr/wdf/general-i-o-targets-in-umdf.md b/windows-driver-docs-pr/wdf/general-i-o-targets-in-umdf.md index c1487e7ddc..98f6203bcb 100644 --- a/windows-driver-docs-pr/wdf/general-i-o-targets-in-umdf.md +++ b/windows-driver-docs-pr/wdf/general-i-o-targets-in-umdf.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # General I/O Targets in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] General I/O targets, which can be either *local* or *remote*, are I/O targets that do not support special, device-specific data formats, such as USB request blocks. Before drivers send data to a general I/O target, they must put data into a write buffer in a format that the I/O target and device can interpret. Likewise, when drivers read data from a general I/O target, the drivers must be able to interpret the contents of data buffers that they receive from the target. diff --git a/windows-driver-docs-pr/wdf/handling-client-impersonation-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/handling-client-impersonation-in-umdf-1-x-drivers.md index 00ec522fd2..9f6cefc409 100644 --- a/windows-driver-docs-pr/wdf/handling-client-impersonation-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/handling-client-impersonation-in-umdf-1-x-drivers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Handling Client Impersonation in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] UMDF drivers typically run under the LocalService account and cannot access files or resources that require user credentials, such as protected files or other protected resources. A UMDF driver typically operates on commands and data that flow between a client application and a device. Therefore, most UMDF drivers do not access protected resources. diff --git a/windows-driver-docs-pr/wdf/handling-interrupts.md b/windows-driver-docs-pr/wdf/handling-interrupts.md index 9c9b6f2dff..f15cd16f51 100644 --- a/windows-driver-docs-pr/wdf/handling-interrupts.md +++ b/windows-driver-docs-pr/wdf/handling-interrupts.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Handling interrupts in UMDF drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Starting in UMDF version 1.11, UMDF drivers can handle hardware interrupts. UMDF supports both line-based (both level-triggered and edge-triggered) and message-signaled (MSI) interrupts. diff --git a/windows-driver-docs-pr/wdf/i-o-queue-event-callback-functions.md b/windows-driver-docs-pr/wdf/i-o-queue-event-callback-functions.md index 45a80a9667..6effd97e2c 100644 --- a/windows-driver-docs-pr/wdf/i-o-queue-event-callback-functions.md +++ b/windows-driver-docs-pr/wdf/i-o-queue-event-callback-functions.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # I/O Queue Event Callback Functions -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When drivers create I/O queues, or configure default I/O queues, they can register the following interfaces so that the framework notifies the driver--by calling the methods associated with the interfaces--when events related to the interfaces occur. For more information about I/O queues and creating and configuring I/O queues, see [Framework I/O Queue Object](framework-i-o-queue-object.md). diff --git a/windows-driver-docs-pr/wdf/i-o-request-processing-operation-flow.md b/windows-driver-docs-pr/wdf/i-o-request-processing-operation-flow.md index 1534d0480b..1c74fed748 100644 --- a/windows-driver-docs-pr/wdf/i-o-request-processing-operation-flow.md +++ b/windows-driver-docs-pr/wdf/i-o-request-processing-operation-flow.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # I/O Request Processing Operation Flow -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] All I/O operations occur in the context of a file object (that is, all I/O operations occur between calls that an application makes to the Microsoft Win32 [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) and **CloseHandle** functions). I/O operations are calls that an application makes to, for example, the Win32 **ReadFileEx**, **WriteFileEx**, and [**DeviceIoControl**](https://msdn.microsoft.com/library/windows/desktop/aa363216) functions. diff --git a/windows-driver-docs-pr/wdf/index.md b/windows-driver-docs-pr/wdf/index.md index 06f72a6db3..0f02882aa2 100644 --- a/windows-driver-docs-pr/wdf/index.md +++ b/windows-driver-docs-pr/wdf/index.md @@ -20,7 +20,6 @@ ms.technology: windows-devices # What's New for WDF Drivers in Windows 10 - This topic summarizes the new features and improvements for Windows Driver Frameworks (WDF) drivers in Windows 10. Windows 10, version 1703 includes Kernel-Mode Driver Framework (KMDF) version 1.21 and User-Mode Driver Framework (UMDF) version 2.21. @@ -32,7 +31,7 @@ You can use these framework versions to build drivers for: For version history, see [KMDF Version History](kmdf-version-history.md) and [UMDF Version History](umdf-version-history.md). Except where noted, UMDF references on this page describe version 2 functionality that is not available in UMDF version 1. -## New in WDF for Redstone 2 +## New in WDF for Windows 10, version 1703 In Windows 10, version 1703, WDF includes the following enhancements: diff --git a/windows-driver-docs-pr/wdf/initializing-a-general-i-o-target-in-umdf.md b/windows-driver-docs-pr/wdf/initializing-a-general-i-o-target-in-umdf.md index 786172f310..73bbbd7518 100644 --- a/windows-driver-docs-pr/wdf/initializing-a-general-i-o-target-in-umdf.md +++ b/windows-driver-docs-pr/wdf/initializing-a-general-i-o-target-in-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Initializing a General I/O Target in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The steps that your driver uses to initialize a general I/O target depend on whether the I/O target is [local](general-i-o-targets-in-umdf.md) or remote. diff --git a/windows-driver-docs-pr/wdf/initializing-umdf-drivers.md b/windows-driver-docs-pr/wdf/initializing-umdf-drivers.md index 35b670bc80..00291537d9 100644 --- a/windows-driver-docs-pr/wdf/initializing-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/initializing-umdf-drivers.md @@ -21,7 +21,7 @@ ms.technology: windows-devices # Initializing UMDF Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Before a UMDF driver for a device is initialized, the driver manager and the reflector are loaded by the operating system and the driver host process is created. To ensure that a device starts successfully, the driver manager is loaded and fully initialized by the time the reflector initializes. diff --git a/windows-driver-docs-pr/wdf/managing-the-lifetime-of-objects.md b/windows-driver-docs-pr/wdf/managing-the-lifetime-of-objects.md index 04f21da19e..036024db50 100644 --- a/windows-driver-docs-pr/wdf/managing-the-lifetime-of-objects.md +++ b/windows-driver-docs-pr/wdf/managing-the-lifetime-of-objects.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Managing the Lifetime of Objects -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] UMDF uses a reference-counting scheme to manage the lifetime of [callback objects](creating-callback-objects.md) and [framework objects](framework-objects.md). diff --git a/windows-driver-docs-pr/wdf/obtaining-information-about-a-general-i-o-target-in-umdf.md b/windows-driver-docs-pr/wdf/obtaining-information-about-a-general-i-o-target-in-umdf.md index de9fc3c4e0..c357c57e36 100644 --- a/windows-driver-docs-pr/wdf/obtaining-information-about-a-general-i-o-target-in-umdf.md +++ b/windows-driver-docs-pr/wdf/obtaining-information-about-a-general-i-o-target-in-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Obtaining Information About a General I/O Target in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] To obtain information about an I/O target, a UMDF driver can call the following methods that the I/O target object defines: diff --git a/windows-driver-docs-pr/wdf/obtaining-parameters-for-i-o-requests.md b/windows-driver-docs-pr/wdf/obtaining-parameters-for-i-o-requests.md index a4704eb733..efc5ff8fdb 100644 --- a/windows-driver-docs-pr/wdf/obtaining-parameters-for-i-o-requests.md +++ b/windows-driver-docs-pr/wdf/obtaining-parameters-for-i-o-requests.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Obtaining Parameters for I/O Requests -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a driver receives an I/O request, the driver can use the following methods of the [IWDFIoRequest](https://msdn.microsoft.com/library/windows/hardware/ff558985) interface to obtain parameters related to the request: diff --git a/windows-driver-docs-pr/wdf/obtaining-wdm-information.md b/windows-driver-docs-pr/wdf/obtaining-wdm-information.md index 271fae289b..50435e04a9 100644 --- a/windows-driver-docs-pr/wdf/obtaining-wdm-information.md +++ b/windows-driver-docs-pr/wdf/obtaining-wdm-information.md @@ -25,7 +25,7 @@ The framework provides several object methods that enable your driver to obtain To obtain WDM information about a driver and its devices, the driver can call the following methods: [**WdfFdoInitWdmGetPhysicalDevice**](https://msdn.microsoft.com/library/windows/hardware/ff547281) -Retrieves the physical device object (PDO). A driver can call this method before the driver has created a framework device object for the device. +Retrieves the [**DEVICE_OBJECT**](https://msdn.microsoft.com/library/windows/hardware/ff543147) structure that represents a device's physical device object (PDO). A driver can call this method before the driver has created a framework device object for the device. [**WdfDeviceWdmGetPhysicalDevice**](https://msdn.microsoft.com/library/windows/hardware/ff546946) Retrieves the WDM DEVICE\_OBJECT structure that represents a device's PDO. A driver can call this method after it has created a framework device object for the device. diff --git a/windows-driver-docs-pr/wdf/operation-flow-with-double-device-stack.md b/windows-driver-docs-pr/wdf/operation-flow-with-double-device-stack.md index 169ff6d246..9dda12691b 100644 --- a/windows-driver-docs-pr/wdf/operation-flow-with-double-device-stack.md +++ b/windows-driver-docs-pr/wdf/operation-flow-with-double-device-stack.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Operation Flow with Double Device Stack -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following figure shows the flow of operations that occur to and from UMDF filter and functional drivers in a double device stack. diff --git a/windows-driver-docs-pr/wdf/operation-flow-with-single-device-stack.md b/windows-driver-docs-pr/wdf/operation-flow-with-single-device-stack.md index 4b8d58e42f..e6f3a38ece 100644 --- a/windows-driver-docs-pr/wdf/operation-flow-with-single-device-stack.md +++ b/windows-driver-docs-pr/wdf/operation-flow-with-single-device-stack.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Operation Flow with Single Device Stack -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following figure shows the flow of operations that occur to and from the UMDF functional driver in a single device stack. diff --git a/windows-driver-docs-pr/wdf/pnp-and-power-management-in-umdf-drivers.md b/windows-driver-docs-pr/wdf/pnp-and-power-management-in-umdf-drivers.md index d6190bc989..50092decdd 100644 --- a/windows-driver-docs-pr/wdf/pnp-and-power-management-in-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/pnp-and-power-management-in-umdf-drivers.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # PnP and Power Management in UMDF Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] ## In this section diff --git a/windows-driver-docs-pr/wdf/pnp-and-power-management-interfaces.md b/windows-driver-docs-pr/wdf/pnp-and-power-management-interfaces.md index c9c44dee13..e05f4db839 100644 --- a/windows-driver-docs-pr/wdf/pnp-and-power-management-interfaces.md +++ b/windows-driver-docs-pr/wdf/pnp-and-power-management-interfaces.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # PnP and Power Management Interfaces -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a new device arrives in the system, the framework calls the [**IDriverEntry::OnDeviceAdd**](https://msdn.microsoft.com/library/windows/hardware/ff554896) method to notify the UMDF driver of the arrival and passes the [**IWDFDriver**](https://msdn.microsoft.com/library/windows/hardware/ff558893) and [**IWDFDeviceInitialize**](https://msdn.microsoft.com/library/windows/hardware/ff556965) interfaces in the call. The driver calls the [**IWDFDriver::CreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff558899) method to create a framework device object for the device. diff --git a/windows-driver-docs-pr/wdf/pnp-and-power-management-scenarios-in-umdf.md b/windows-driver-docs-pr/wdf/pnp-and-power-management-scenarios-in-umdf.md index 6df26bdbbf..7422d4850a 100644 --- a/windows-driver-docs-pr/wdf/pnp-and-power-management-scenarios-in-umdf.md +++ b/windows-driver-docs-pr/wdf/pnp-and-power-management-scenarios-in-umdf.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # PnP and Power Management Scenarios in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The following PnP and power management scenarios show the sequences in which the framework calls a UMDF driver's event callback functions: diff --git a/windows-driver-docs-pr/wdf/power-policy-ownership-in-umdf.md b/windows-driver-docs-pr/wdf/power-policy-ownership-in-umdf.md index a85b5b215c..ddf2ab53e5 100644 --- a/windows-driver-docs-pr/wdf/power-policy-ownership-in-umdf.md +++ b/windows-driver-docs-pr/wdf/power-policy-ownership-in-umdf.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # Power Policy Ownership in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] For each device, one (and only one) of the device's drivers must be the device's *power policy owner*. The power policy owner determines the appropriate [device power state](https://msdn.microsoft.com/library/windows/hardware/ff543162) for a device and sends requests to the device's driver stack whenever the device's power state should change. diff --git a/windows-driver-docs-pr/wdf/preventing-an-imbalance-of-create-and-close-notifications-to-a-driver.md b/windows-driver-docs-pr/wdf/preventing-an-imbalance-of-create-and-close-notifications-to-a-driver.md index 05e477ac23..76797d6f61 100644 --- a/windows-driver-docs-pr/wdf/preventing-an-imbalance-of-create-and-close-notifications-to-a-driver.md +++ b/windows-driver-docs-pr/wdf/preventing-an-imbalance-of-create-and-close-notifications-to-a-driver.md @@ -19,7 +19,7 @@ ms.technology: windows-devices # Preventing an Imbalance of Create and Close Notifications to a Driver -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] An upper UMDF driver can use the [**IWDFDeviceInitialize::AutoForwardCreateCleanupClose**](https://msdn.microsoft.com/library/windows/hardware/ff556971) method to control when the framework automatically forwards create-file, cleanup-file, and close-file notifications to the next lower driver in the device stack. However, because the upper driver sets **AutoForwardCreateCleanupClose** to automatically forward only on a device level and not on a per-file level, forwarding must be the same for all files for a device. The framework ensures this forwarding behavior for cleanup-file and close-file notifications. If the upper driver implements the [**IQueueCallbackCreate::OnCreateFile**](https://msdn.microsoft.com/library/windows/hardware/ff556841) callback function, it must ensure that its forwarding behavior is the same for all create-file requests and is consistent with the forwarding behavior for cleanup-file and close-file notifications. Failing to do so might cause lower drivers to receive an unequal amount of calls to their **IQueueCallbackCreate::OnCreateFile** method and [**IFileCallbackCleanup::OnCleanupFile**](https://msdn.microsoft.com/library/windows/hardware/ff554905) and [**IFileCallbackClose::OnCloseFile**](https://msdn.microsoft.com/library/windows/hardware/ff554910) methods. diff --git a/windows-driver-docs-pr/wdf/processing-i-o-requests-umdf.md b/windows-driver-docs-pr/wdf/processing-i-o-requests-umdf.md index de4e5be220..f07c360a6b 100644 --- a/windows-driver-docs-pr/wdf/processing-i-o-requests-umdf.md +++ b/windows-driver-docs-pr/wdf/processing-i-o-requests-umdf.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Processing I/O Requests -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] ## In this section diff --git a/windows-driver-docs-pr/wdf/reading-and-writing-to-device-registers-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/reading-and-writing-to-device-registers-in-umdf-1-x-drivers.md index ca354d80da..74a6479945 100644 --- a/windows-driver-docs-pr/wdf/reading-and-writing-to-device-registers-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/reading-and-writing-to-device-registers-in-umdf-1-x-drivers.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Reading and Writing to Device Registers in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Starting in UMDF version 1.11, the framework provides a set of routines to access registers in memory space and I/O port space. The [UMDF register/port access routines](https://msdn.microsoft.com/library/windows/hardware/hh463975) are very similar to the HAL routines used by kernel-mode drivers. After a driver has mapped registers as described in [Finding and Mapping Hardware Resources in a UMDF Driver](https://msdn.microsoft.com/library/windows/hardware/hh439594), the driver uses the READ/WRITE\_REGISTER\_Xxx routines to read and write to individual registers. For I/O ports, the driver calls the READ/WRITE\_PORT\_Xxx routines. diff --git a/windows-driver-docs-pr/wdf/reusing-framework-request-objects-umdf.md b/windows-driver-docs-pr/wdf/reusing-framework-request-objects-umdf.md index e97af337e7..01c90c9e0b 100644 --- a/windows-driver-docs-pr/wdf/reusing-framework-request-objects-umdf.md +++ b/windows-driver-docs-pr/wdf/reusing-framework-request-objects-umdf.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Reusing Framework Request Objects in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] To improve driver performance, framework-based drivers that create and send many nearly identical asynchronous requests to an I/O target can reuse request objects instead of creating a new request object for each request. A driver can reuse a request object after the request has been completed. diff --git a/windows-driver-docs-pr/wdf/sending-i-o-requests-to-a-general-i-o-target-in-umdf.md b/windows-driver-docs-pr/wdf/sending-i-o-requests-to-a-general-i-o-target-in-umdf.md index ca9e8e8263..14c2d70754 100644 --- a/windows-driver-docs-pr/wdf/sending-i-o-requests-to-a-general-i-o-target-in-umdf.md +++ b/windows-driver-docs-pr/wdf/sending-i-o-requests-to-a-general-i-o-target-in-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Sending I/O Requests to a General I/O Target in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A UMDF driver can send I/O requests to general I/O targets either synchronously or asynchronously. diff --git a/windows-driver-docs-pr/wdf/sending-i-o-requests-to-lower-drivers.md b/windows-driver-docs-pr/wdf/sending-i-o-requests-to-lower-drivers.md index 853f258061..5261c406fd 100644 --- a/windows-driver-docs-pr/wdf/sending-i-o-requests-to-lower-drivers.md +++ b/windows-driver-docs-pr/wdf/sending-i-o-requests-to-lower-drivers.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Sending I/O Requests to Lower Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a driver receives an I/O request that it cannot fully process, the driver typically forwards the received request to the next lower driver in the stack. The driver calls the [**IWDFIoRequest::Send**](https://msdn.microsoft.com/library/windows/hardware/ff559149) method to forward the request. To forward synchronously, the driver passes the WDF\_REQUEST\_SEND\_OPTION\_SYNCHRONOUS flag in the *Flags* parameter. Otherwise, the driver forwards the request asynchronously. Before the driver forwards the request, it should register a completion routine. For more information, see [Completing I/O Requests](completing-i-o-requests.md). diff --git a/windows-driver-docs-pr/wdf/servicing-an-interrupt-umdf.md b/windows-driver-docs-pr/wdf/servicing-an-interrupt-umdf.md index cb106c158d..ada882265b 100644 --- a/windows-driver-docs-pr/wdf/servicing-an-interrupt-umdf.md +++ b/windows-driver-docs-pr/wdf/servicing-an-interrupt-umdf.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Servicing an Interrupt -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Servicing an interrupt consists of two steps: diff --git a/windows-driver-docs-pr/wdf/servicing-an-interrupt.md b/windows-driver-docs-pr/wdf/servicing-an-interrupt.md index 59c0caedde..0b2c8f7a57 100644 --- a/windows-driver-docs-pr/wdf/servicing-an-interrupt.md +++ b/windows-driver-docs-pr/wdf/servicing-an-interrupt.md @@ -32,7 +32,7 @@ Servicing an interrupt consists of two, and sometimes three, steps: When a device generates a hardware interrupt, the framework calls the driver's interrupt service routine (ISR), which framework-based drivers implement as an [*EvtInterruptIsr*](https://msdn.microsoft.com/library/windows/hardware/ff541735) callback function. -The DIRQL, must quickly save interrupt information, such as register contents, that will be lost if another interrupt occurs. +The [*EvtInterruptIsr*](https://msdn.microsoft.com/library/windows/hardware/ff541735) callback function, which runs at the device's DIRQL, must quickly save interrupt information, such as register contents, that will be lost if another interrupt occurs. Typically, the [*EvtInterruptIsr*](https://msdn.microsoft.com/library/windows/hardware/ff541735) callback function schedules a deferred procedure call (DPC) to process the saved information later at a lower IRQL (DISPATCH\_LEVEL). Framework-based drivers implement DPC routines as [*EvtInterruptDpc*](https://msdn.microsoft.com/library/windows/hardware/ff541721) or [*EvtDpcFunc*](https://msdn.microsoft.com/library/windows/hardware/ff541683) callback functions. diff --git a/windows-driver-docs-pr/wdf/specifying-a-callback-synchronization-mode.md b/windows-driver-docs-pr/wdf/specifying-a-callback-synchronization-mode.md index 48f3bf3aff..1ee4faf754 100644 --- a/windows-driver-docs-pr/wdf/specifying-a-callback-synchronization-mode.md +++ b/windows-driver-docs-pr/wdf/specifying-a-callback-synchronization-mode.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Specifying a Callback Synchronization Mode -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The driver can specify how its callback functions are called by the framework. The driver specifies a synchronization (or locking) mode for a device before it calls the [**IWDFDriver::CreateDevice**](https://msdn.microsoft.com/library/windows/hardware/ff558899) method to create a [device object](framework-device-object.md) for the device. To specify synchronization mode, the driver should call the [**IWDFDeviceInitialize::SetLockingConstraint**](https://msdn.microsoft.com/library/windows/hardware/ff556991) method. The driver receives a pointer to the [IWDFDeviceInitialize](https://msdn.microsoft.com/library/windows/hardware/ff556965) interface when its [**IDriverEntry::OnDeviceAdd**](https://msdn.microsoft.com/library/windows/hardware/ff554896) method is called to add the device to the system. diff --git a/windows-driver-docs-pr/wdf/supporting-idle-power-down-in-umdf-drivers.md b/windows-driver-docs-pr/wdf/supporting-idle-power-down-in-umdf-drivers.md index bd2d868e58..cb3ce19b25 100644 --- a/windows-driver-docs-pr/wdf/supporting-idle-power-down-in-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/supporting-idle-power-down-in-umdf-drivers.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Supporting Idle Power-Down in UMDF Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Some devices can enter a sleeping state while the system remains in its working state. For such devices, the framework initiates lowering the device's power after the device has been idle (not used) for a predetermined (and settable) amount of time. diff --git a/windows-driver-docs-pr/wdf/supporting-kernel-mode-clients-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/supporting-kernel-mode-clients-in-umdf-1-x-drivers.md index 9179b1944f..62227663eb 100644 --- a/windows-driver-docs-pr/wdf/supporting-kernel-mode-clients-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/supporting-kernel-mode-clients-in-umdf-1-x-drivers.md @@ -18,6 +18,7 @@ ms.technology: windows-devices # Supporting Kernel-Mode Clients in UMDF 1.x Drivers +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] UMDF versions 1.9 and later allow UMDF drivers to support *kernel-mode clients*. A kernel-mode client can be either of the following: diff --git a/windows-driver-docs-pr/wdf/supporting-passive-level-interrupts.md b/windows-driver-docs-pr/wdf/supporting-passive-level-interrupts.md index 6603d4aee9..f71392974e 100644 --- a/windows-driver-docs-pr/wdf/supporting-passive-level-interrupts.md +++ b/windows-driver-docs-pr/wdf/supporting-passive-level-interrupts.md @@ -49,7 +49,7 @@ Drivers typically complete I/O requests in their [*EvtInterruptWorkItem*](https: The following code example demonstrates how a driver using passive-level interrupts might schedule a [*EvtInterruptWorkItem*](https://msdn.microsoft.com/library/windows/hardware/hh406422) callback from within its [*EvtInterruptIsr*](https://msdn.microsoft.com/library/windows/hardware/ff541735) function. -``` syntax +``` BOOLEAN EvtInterruptIsr( diff --git a/windows-driver-docs-pr/wdf/supporting-system-wake-up-in-umdf-drivers.md b/windows-driver-docs-pr/wdf/supporting-system-wake-up-in-umdf-drivers.md index d1dc6c7d3f..ddcaa849fa 100644 --- a/windows-driver-docs-pr/wdf/supporting-system-wake-up-in-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/supporting-system-wake-up-in-umdf-drivers.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # Supporting System Wake-Up in UMDF Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] While the system is in a low-power state, some devices can detect an external event, such as an incoming network packet, and then wake the system. For example, if a PCI device has a system wake-up capability, as indicated in the device's Power Management Capabilities (PMC) register, it wakes the system by raising the Power Management Event (PME) signal on the PCI bus. diff --git a/windows-driver-docs-pr/wdf/synchronizing-interrupt-code-umdf.md b/windows-driver-docs-pr/wdf/synchronizing-interrupt-code-umdf.md index d17e08125b..394ea86b3d 100644 --- a/windows-driver-docs-pr/wdf/synchronizing-interrupt-code-umdf.md +++ b/windows-driver-docs-pr/wdf/synchronizing-interrupt-code-umdf.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Synchronizing Interrupt Code -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] All driver code that accesses the interrupt data buffer must be synchronized so that only one routine accesses the data at a time. diff --git a/windows-driver-docs-pr/wdf/the-pnp-manager-redistributes-system-resources-umdf.md b/windows-driver-docs-pr/wdf/the-pnp-manager-redistributes-system-resources-umdf.md index 1e1e8fdb31..f6af4cacb3 100644 --- a/windows-driver-docs-pr/wdf/the-pnp-manager-redistributes-system-resources-umdf.md +++ b/windows-driver-docs-pr/wdf/the-pnp-manager-redistributes-system-resources-umdf.md @@ -16,7 +16,7 @@ ms.technology: windows-devices # The PnP Manager Redistributes System Resources -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If a user adds a device to a system, and if the device requires system resources that the PnP manager has already assigned to another device, the PnP manager attempts to reassign resources. diff --git a/windows-driver-docs-pr/wdf/umdf-based-on-com-subset.md b/windows-driver-docs-pr/wdf/umdf-based-on-com-subset.md index 85f99836e3..cb1ee076cb 100644 --- a/windows-driver-docs-pr/wdf/umdf-based-on-com-subset.md +++ b/windows-driver-docs-pr/wdf/umdf-based-on-com-subset.md @@ -17,7 +17,7 @@ ms.technology: windows-devices # UMDF Based on COM Subset -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework objects and interfaces are based on the Component Object Model (COM) for the following reasons: diff --git a/windows-driver-docs-pr/wdf/umdf-ddi-programming-model.md b/windows-driver-docs-pr/wdf/umdf-ddi-programming-model.md index f8a9b89025..1ffe52387a 100644 --- a/windows-driver-docs-pr/wdf/umdf-ddi-programming-model.md +++ b/windows-driver-docs-pr/wdf/umdf-ddi-programming-model.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # UMDF DDI Programming Model -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework and the UMDF driver communicate through the UMDF DDI. The UMDF DDI is similar to the KMDF DDI except that the UMDF DDI is based on COM. Therefore, driver writers familiar with KMDF will understand UMDF. diff --git a/windows-driver-docs-pr/wdf/umdf-driver-tasks.md b/windows-driver-docs-pr/wdf/umdf-driver-tasks.md index f75b89a0ab..3eccaef6f2 100644 --- a/windows-driver-docs-pr/wdf/umdf-driver-tasks.md +++ b/windows-driver-docs-pr/wdf/umdf-driver-tasks.md @@ -16,6 +16,7 @@ ms.technology: windows-devices # UMDF Driver Tasks +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] ## In this section diff --git a/windows-driver-docs-pr/wdf/umdf-objects-and-interfaces.md b/windows-driver-docs-pr/wdf/umdf-objects-and-interfaces.md index 5aa090f70f..2bf21e337e 100644 --- a/windows-driver-docs-pr/wdf/umdf-objects-and-interfaces.md +++ b/windows-driver-docs-pr/wdf/umdf-objects-and-interfaces.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # UMDF Objects and Interfaces -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The User-Mode Driver Framework (UMDF) is composed of a set of cooperating objects. The UMDF creates and manages a series of objects exposed to the user-mode device driver. Some of theses objects are created by the UMDF in response to application-triggered actions, such as an I/O request, while other UMDF objects are created when the driver calls UMDF interface methods. For example, to create an I/O queue object, the driver calls the [**IWDFDevice::CreateIoQueue**](https://msdn.microsoft.com/library/windows/hardware/ff557020) method. diff --git a/windows-driver-docs-pr/wdf/usb-i-o-targets-in-umdf.md b/windows-driver-docs-pr/wdf/usb-i-o-targets-in-umdf.md index 1850008d80..c2b97b790f 100644 --- a/windows-driver-docs-pr/wdf/usb-i-o-targets-in-umdf.md +++ b/windows-driver-docs-pr/wdf/usb-i-o-targets-in-umdf.md @@ -19,6 +19,7 @@ ms.technology: windows-devices # USB I/O Targets in UMDF +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] Each universal serial bus (USB) device, and each pipe that a USB device interface supports, has a separate I/O target. I/O that the USB device processes is sent to the device's I/O target. I/O that a specific pipe processes is sent to that pipe's I/O target. diff --git a/windows-driver-docs-pr/wdf/usb-specific-umdf-1-x-interfaces.md b/windows-driver-docs-pr/wdf/usb-specific-umdf-1-x-interfaces.md index 0a014c9695..1f4567cd2c 100644 --- a/windows-driver-docs-pr/wdf/usb-specific-umdf-1-x-interfaces.md +++ b/windows-driver-docs-pr/wdf/usb-specific-umdf-1-x-interfaces.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # USB-Specific UMDF 1.x Interfaces -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A USB device can have one or more configurations. Each configuration can have one or more interfaces. Each interface is associated with one or more alternate settings, and each alternate setting defines one or more endpoints. An endpoint represents a buffer on the device hardware. diff --git a/windows-driver-docs-pr/wdf/user-control-of-device-idle-and-wake-behavior-in-umdf.md b/windows-driver-docs-pr/wdf/user-control-of-device-idle-and-wake-behavior-in-umdf.md index 583fea8618..4db2fa13a4 100644 --- a/windows-driver-docs-pr/wdf/user-control-of-device-idle-and-wake-behavior-in-umdf.md +++ b/windows-driver-docs-pr/wdf/user-control-of-device-idle-and-wake-behavior-in-umdf.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # User Control of Device Idle and Wake Behavior in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] If a device has idle power-down or wake-up capabilities, you can decide whether users should be allowed to enable or disable these capabilities. diff --git a/windows-driver-docs-pr/wdf/user-mode-driver-framework-design-guide.md b/windows-driver-docs-pr/wdf/user-mode-driver-framework-design-guide.md index 7aa5bf839a..33603af76d 100644 --- a/windows-driver-docs-pr/wdf/user-mode-driver-framework-design-guide.md +++ b/windows-driver-docs-pr/wdf/user-mode-driver-framework-design-guide.md @@ -12,6 +12,7 @@ ms.technology: windows-devices # UMDF 1.x Design Guide +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] This section contains information that applies only to User-Mode Driver Framework (UMDF) versions 1.11 and earlier. diff --git a/windows-driver-docs-pr/wdf/using-automatic-synchronization.md b/windows-driver-docs-pr/wdf/using-automatic-synchronization.md index 234b5f5e26..e51e2081cc 100644 --- a/windows-driver-docs-pr/wdf/using-automatic-synchronization.md +++ b/windows-driver-docs-pr/wdf/using-automatic-synchronization.md @@ -39,7 +39,7 @@ The framework implements this automatic synchronization by using a set of intern Your driver should store object-specific data in [object context space](framework-object-context-space.md). If your driver uses only framework-defined interfaces, only callback functions that receive a handle to the object can access this data. If the framework is synchronizing calls to the driver's callback functions, only one callback function will be called at a time and the object's context space will be accessible to only one callback function at a time. -Unless your driver implements DIRQL) and requires additional synchronization. For more information, see [Synchronizing Interrupt Code](synchronizing-interrupt-code.md). +Unless your driver implements [passive-level interrupt handling](supporting-passive-level-interrupts.md), code that services interrupts and accesses interrupt data must run at the device's IRQL (DIRQL) and requires additional synchronization. For more information, see [Synchronizing Interrupt Code](synchronizing-interrupt-code.md). If your driver enables automatic synchronization of the callback functions that handle I/O requests, the framework synchronizes these callback functions so that they run one at a time. The following table lists the callback functions that the framework synchronizes. diff --git a/windows-driver-docs-pr/wdf/using-control-device-objects.md b/windows-driver-docs-pr/wdf/using-control-device-objects.md index 3fa3e58f97..ed0822061b 100644 --- a/windows-driver-docs-pr/wdf/using-control-device-objects.md +++ b/windows-driver-docs-pr/wdf/using-control-device-objects.md @@ -38,7 +38,7 @@ Two typical uses for control devices are: If an application attempted to send the custom I/O control codes to the top of the driver stack (by using, for example, the symbolic link name of a [device interface](using-device-interfaces.md)), a driver above the filter driver might fail the I/O request if the driver did not recognize the custom I/O control codes. To avoid this problem, the filter driver can create a control device object. Applications can use the control device object's symbolic link name to send I/O control codes directly to the filter driver. - (Note that a better way for the filter driver to avoid the problem is to act as a bus driver and raw mode. In other words, for each device that the filter driver supports, the driver can create a physical device object (PDO) that does not require a function driver. The driver calls [**WdfPdoInitAssignRawDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548802) and [**WdfDeviceInitAssignName**](https://msdn.microsoft.com/library/windows/hardware/ff546029) for each of these devices, and the application can identify a device by name when it sends a custom I/O control code.) + (Note that a better way for the filter driver to avoid the problem is to act as a bus driver and [enumerate](enumerating-the-devices-on-a-bus.md) child devices that operate in raw mode. In other words, for each device that the filter driver supports, the driver can create a physical device object (PDO) that does not require a function driver. The driver calls [**WdfPdoInitAssignRawDevice**](https://msdn.microsoft.com/library/windows/hardware/ff548802) and [**WdfDeviceInitAssignName**](https://msdn.microsoft.com/library/windows/hardware/ff546029) for each of these devices, and the application can identify a device by name when it sends a custom I/O control code.) 2. A driver for a device that does not support PnP. diff --git a/windows-driver-docs-pr/wdf/using-device-interfaces-in-umdf-drivers.md b/windows-driver-docs-pr/wdf/using-device-interfaces-in-umdf-drivers.md index 87a631fbac..27d6987712 100644 --- a/windows-driver-docs-pr/wdf/using-device-interfaces-in-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/using-device-interfaces-in-umdf-drivers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Using Device Interfaces in UMDF Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A *device interface* is a symbolic link to a Plug and Play (PnP) device that an application can use to access the device. A user-mode application can pass the interface's symbolic link name to an API element, such as the Microsoft Win32 [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function. To obtain a device interface's symbolic link name, the user-mode application can call **SetupDi** functions. For more information about SetupDi functions, see SetupDi Device Interface Functions. diff --git a/windows-driver-docs-pr/wdf/using-i-o-targets-in-umdf.md b/windows-driver-docs-pr/wdf/using-i-o-targets-in-umdf.md index 9e0f92ec46..b555a1c1bd 100644 --- a/windows-driver-docs-pr/wdf/using-i-o-targets-in-umdf.md +++ b/windows-driver-docs-pr/wdf/using-i-o-targets-in-umdf.md @@ -20,7 +20,7 @@ ms.technology: windows-devices # Using I/O Targets in UMDF -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] When a driver receives an I/O request, the driver might be able to process the request by itself, or it might require the assistance of other drivers. If the driver requires assistance, it can forward the request to another driver, or it can create one or more new requests and send them to another driver. diff --git a/windows-driver-docs-pr/wdf/using-the-registry-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/using-the-registry-in-umdf-1-x-drivers.md index d5f6cee8ec..506a7825c8 100644 --- a/windows-driver-docs-pr/wdf/using-the-registry-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/using-the-registry-in-umdf-1-x-drivers.md @@ -21,7 +21,7 @@ ms.technology: windows-devices # Using the Registry in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] UMDF-based drivers can read and write values in the registry by using interfaces of the property store object. diff --git a/windows-driver-docs-pr/wdf/using-the-windows-performance-toolkit--wpt--with-wdf.md b/windows-driver-docs-pr/wdf/using-the-windows-performance-toolkit--wpt--with-wdf.md index 89776690df..74ba5975bf 100644 --- a/windows-driver-docs-pr/wdf/using-the-windows-performance-toolkit--wpt--with-wdf.md +++ b/windows-driver-docs-pr/wdf/using-the-windows-performance-toolkit--wpt--with-wdf.md @@ -155,7 +155,7 @@ Finally, to determine callback duration for PnP/Power callbacks, the framework r - Be sure to reboot after you run the WdfPerfEnhancedVerifier.cmd script. - To determine if your driver is configured to record an event log, use the **!WdfKd.wdfdriverinfo** kernel debugger command. If the driver is configured for performance tracing, you will see output like this: - ``` syntax + ``` !WdfKd.WdfDriverInfo Echo.sys … … diff --git a/windows-driver-docs-pr/wdf/using-umdf-debugger-extensions.md b/windows-driver-docs-pr/wdf/using-umdf-debugger-extensions.md index 2938319fb8..dcafdd231c 100644 --- a/windows-driver-docs-pr/wdf/using-umdf-debugger-extensions.md +++ b/windows-driver-docs-pr/wdf/using-umdf-debugger-extensions.md @@ -1,7 +1,7 @@ --- title: Summary of Debugger Extensions in Wudfext.dll author: windows-driver-content -description: The Windows Driver Kit (WDK) includes a debugger extension library, named WudfExt.dll, which is located in the DDKROOT \\bin subdirectory. +description: This topic describes the debugger extension commands in WudfExt.dll, which you can use to debug certain User-Mode Driver Framework (UMDF) drivers. ms.assetid: af84ed3a-33a1-4736-9080-c43e87052064 keywords: - UMDF debugger extensions WDK @@ -17,7 +17,7 @@ ms.technology: windows-devices # Summary of Debugger Extensions in Wudfext.dll -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The Windows Driver Kit (WDK) includes a debugger extension library, named *WudfExt.dll*, which is located in the %DDKROOT%\\bin subdirectory. This topic describes the debugger extension commands in *WudfExt.dll*, which you can use to debug User-Mode Driver Framework (UMDF) version 1.*x* drivers. diff --git a/windows-driver-docs-pr/wdf/using-umdf-verifier.md b/windows-driver-docs-pr/wdf/using-umdf-verifier.md index 9b7e5da702..cb8aebc62e 100644 --- a/windows-driver-docs-pr/wdf/using-umdf-verifier.md +++ b/windows-driver-docs-pr/wdf/using-umdf-verifier.md @@ -35,7 +35,7 @@ Starting in UMDF 2.0, UMDF Verifier issues breakpoints in some cases, and causes We recommend running [Application Verifier (AppVerif.exe)](http://www.microsoft.com/download/details.aspx?id=20028) on WUDFHost.exe while testing or debugging your UMDF driver. Use the following command, and then reboot. -``` syntax +``` AppVerif –enable Heaps Exceptions Handles Locks Memory TLS Leak –for WudfHost.exe ``` diff --git a/windows-driver-docs-pr/wdf/using-workitems.md b/windows-driver-docs-pr/wdf/using-workitems.md index 86fe21479b..ca422bf4d1 100644 --- a/windows-driver-docs-pr/wdf/using-workitems.md +++ b/windows-driver-docs-pr/wdf/using-workitems.md @@ -13,7 +13,7 @@ ms.technology: windows-devices # Using Work Items -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] A work item is a task that a driver performs in an [*OnWorkItem*](https://msdn.microsoft.com/library/windows/hardware/hh463909) event callback function. These functions run asynchronously. diff --git a/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-kmdf-drivers.md b/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-kmdf-drivers.md index fd45ab1d77..4d41ad83a1 100644 --- a/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-kmdf-drivers.md +++ b/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-kmdf-drivers.md @@ -48,14 +48,14 @@ To add tracing messages to your framework-based driver, you must: - Open the Property Pages for your driver project. Right-click the driver project in Solution Explorer and select **Properties**. In the Property Pages for the driver, click **Configuration Properties**, and then **Wpp**. Under the **General** menu, set **Run WPP Tracing** to Yes. Under the **File Options** menu, you should also specify the framework's WPP template file, for example: - ``` syntax + ``` {km-WdfDefault.tpl}*.tmh ``` - To specify additional WPP trace settings for your driver project in Visual Studio, right-click on the driver project in Solutions Explorer. Then follow the link to Properties->Configuration Properties->WPP Tracing. - To specify a trace configuration file use the 'Scan Configuration Data' setting. For more than one trace configuration file add it under the 'Command Line'-> 'Additional Options' as follows - ``` syntax + ``` -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\wdftraceenums.h" ``` For more information about adding tracing messages to your driver, see [Adding WPP Macros to a Driver](https://msdn.microsoft.com/library/windows/hardware/ff541243). diff --git a/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-umdf-drivers.md b/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-umdf-drivers.md index 8a3ae3414a..3c303357d9 100644 --- a/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-umdf-drivers.md +++ b/windows-driver-docs-pr/wdf/using-wpp-software-tracing-in-umdf-drivers.md @@ -48,7 +48,7 @@ To add tracing messages to your framework-based driver, you must: - Open the Property Pages for your driver project. Right-click the driver project in Solution Explorer and select **Properties**. In the Property Pages for the driver, click **Configuration Properties**, and then **Wpp**. Under the **General** menu, set **Run WPP Tracing** to Yes. Under the **File Options** menu, you should also specify the framework's WPP template file, for example: - ``` syntax + ``` {km-WdfDefault.tpl}*.tmh ``` @@ -83,7 +83,7 @@ You can also use the [**!wmitrace**](https://msdn.microsoft.com/library/windows/ 3. Use the [**!wmitrace.logdump**](https://msdn.microsoft.com/library/windows/hardware/ff566159) command to display the contents of the trace buffers: - ``` syntax + ``` !wmitrace.logdump WudfTrace ``` diff --git a/windows-driver-docs-pr/wdf/viewing-umdf-objects.md b/windows-driver-docs-pr/wdf/viewing-umdf-objects.md index 3305009a95..a544814166 100644 --- a/windows-driver-docs-pr/wdf/viewing-umdf-objects.md +++ b/windows-driver-docs-pr/wdf/viewing-umdf-objects.md @@ -16,6 +16,7 @@ ms.technology: windows-devices # Viewing UMDF Objects +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] This topic describes how you can use the Wudfext.dll debugger extensions to view information about objects used by a User-Mode Driver Framework (UMDF) version 1 driver. diff --git a/windows-driver-docs-pr/wdf/working-with-usb-devices-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/working-with-usb-devices-in-umdf-1-x-drivers.md index 9d7e9dbeb3..3de7efcf23 100644 --- a/windows-driver-docs-pr/wdf/working-with-usb-devices-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/working-with-usb-devices-in-umdf-1-x-drivers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Working with USB Devices in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework represents each USB device as a framework USB device object. A UMDF driver must create a framework USB device object before the driver can access the framework's support for USB I/O targets. UMDF provides USB device object methods that enable a UMDF driver to: diff --git a/windows-driver-docs-pr/wdf/working-with-usb-interfaces-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/working-with-usb-interfaces-in-umdf-1-x-drivers.md index 46110fe4ea..6808c1db9c 100644 --- a/windows-driver-docs-pr/wdf/working-with-usb-interfaces-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/working-with-usb-interfaces-in-umdf-1-x-drivers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Working with USB Interfaces in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework represents each USB interface as a framework USB interface object. When a UMDF driver creates a framework USB device object, the framework creates a framework USB interface object for each USB interface that the device supports. diff --git a/windows-driver-docs-pr/wdf/working-with-usb-pipes-in-umdf-1-x-drivers.md b/windows-driver-docs-pr/wdf/working-with-usb-pipes-in-umdf-1-x-drivers.md index eecce95719..629d5e184a 100644 --- a/windows-driver-docs-pr/wdf/working-with-usb-pipes-in-umdf-1-x-drivers.md +++ b/windows-driver-docs-pr/wdf/working-with-usb-pipes-in-umdf-1-x-drivers.md @@ -18,7 +18,7 @@ ms.technology: windows-devices # Working with USB Pipes in UMDF 1.x Drivers -\[This topic applies to UMDF 1.*x*.\] +[!include[UMDF 1 Deprecation](../umdf-1-deprecation.md)] The framework represents each pipe in a USB interface as a framework USB pipe object. When a driver configures a USB device, the framework creates a framework USB pipe object for each pipe in each selected interface. Pipe object methods enable a driver to: diff --git a/windows-driver-docs-pr/wdtf/wdtf-object-name-tags.md b/windows-driver-docs-pr/wdtf/wdtf-object-name-tags.md index 14d42924b7..45f85f0dc3 100644 --- a/windows-driver-docs-pr/wdtf/wdtf-object-name-tags.md +++ b/windows-driver-docs-pr/wdtf/wdtf-object-name-tags.md @@ -1,7 +1,7 @@ --- title: WDTF Object Name tags author: windows-driver-content -description: The WDTF OBJECT\_NAME tags are used in WDTF object logging. +description: The WDTF OBJECT_NAME tags are used in WDTF object logging. ms.assetid: 25C669DD-12D0-4C78-802F-CB8E26C4FD80 ms.author: windowsdriverdev ms.date: 04/20/2017 diff --git a/windows-driver-docs-pr/what-s-new-in-driver-development.md b/windows-driver-docs-pr/what-s-new-in-driver-development.md index 03b844b8e1..3978627fc6 100644 --- a/windows-driver-docs-pr/what-s-new-in-driver-development.md +++ b/windows-driver-docs-pr/what-s-new-in-driver-development.md @@ -59,9 +59,9 @@ We're making the docs more community-driven. On many pages of the Windows driver ![screenshot of contribute button](contribute-button.png) -When you click **Contribute**, you'll arrive at the Markdown source file for that topic in a [GitHub repository](https://github.com/Microsoft/windows-driver-docs). You can click **Edit** and suggest changes right here. +When you click **Contribute**, you'll arrive at the Markdown source file for that topic in a [GitHub repository](https://github.com/MicrosoftDocs/windows-driver-docs). You can click **Edit** and suggest changes right here. -For more details, see [CONTRIBUTING.md](https://github.com/Microsoft/windows-driver-docs/blob/staging/CONTRIBUTING.md) in the repo. And thanks for taking the time to improve the docs! +For more details, see [CONTRIBUTING.md](https://github.com/MicrosoftDocs/windows-driver-docs/blob/staging/CONTRIBUTING.md) in the repo. And thanks for taking the time to improve the docs! ### Debugging Tools for Windows @@ -158,8 +158,12 @@ This section describes new features and improvements for driver development in W New topics: -* New DDIs to support APO Module Communications discovery -* Implementing Audio Module Communication +* [Implementing Audio Module Communication](https://docs.microsoft.com/en-us/windows-hardware/drivers/audio/implementing-audio-module-communication) - Describes the support for communication from Universal Windows Platform (UWP) apps to kernel mode audio device drivers. +* New DDIs and properties reference topics to support APO Module Communications discovery: + - [KSPROPSETID_AudioModule](https://msdn.microsoft.com/en-us/library/windows/hardware/mt808144.aspx) - A new KS Property Set that defines three properties specific to audio modules. + - [KSPROPERTY_AUDIOMODULE_COMMAND](https://msdn.microsoft.com/library/windows/hardware/mt808141.aspx) property - Allows Audio Module clients to send custom commands to query and set parameters on Audio Modules. + - [IPortClsNotifications](https://msdn.microsoft.com/library/windows/hardware/mt808133.aspx) - New Port Class Notifications that provide notification helpers to miniports, to support audio module communication. + ### Battery
    Device Discovery -

    List all devices connected to MUTT ConnEx-C

    /list For USB connected devices, this option lists the device instance path. For audio connected devices it shows Audio.

    To view audio devices, use this in combination with the /all parameter. Lists with 1-based index that can be used for input to the /# parameter.

    Device Selection -

    Select all devices connected to MUTT ConnEx-C, including audio.

    /all Optional.

    Without this parameter, the utility addresses USB connected devices. Use this parameter only if an audio connected device is in use. Audio discovery is time consuming and disabled by default.

    Device Selection -

    Select a specific device connected to MUTT ConnEx-C ‘n’.

    /# n (Optional) -

    Input n is a 1-based index of the available devices connected to MUTT ConnEx-C which can be viewed by using the /list parameter. Without this parameter, the default behavior is to run each command on all MUTT ConnEx-C boards.

    Device Command

    Describes various tools you can use to test USB devices and drivers.

    [Test USB Type-C systems with MUTT ConnEx-C](test-usb-type-c-systems-with-mutt-connex-c.md)

    The MUTT Connection Exerciser Type-C (MUTT ConnEx-C) hardware board is a custom shield for the Arduino board. The shield provides a four-to-one switch to automate interoperability tests for USB Type-C scenarios.

    [Test USB Type-C systems with USB Type-C ConnEx](test-usb-type-c-systems-with-mutt-connex-c.md)

    The MUTT Connection Exerciser Type-C (USB Type-C ConnEx) hardware board is a custom shield for the Arduino board. The shield provides a four-to-one switch to automate interoperability tests for USB Type-C scenarios.

    [USB Type-C manual interoperability test procedures](type.md)

    Hardware IDs

    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09
    -USB\Vid_%04x&Pid_%04x&Cdc_09&MI_%02x
    -USB\Vid_%04x&Pid_%04x&Cdc_09
    USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Rev_%04x&Cdc_09
    +USB\Vid_%04x&Pid_%04x&Cdc_09&MI_%02x
    +USB\Vid_%04x&Pid_%04x&Cdc_09

    Compatible IDs

    USB\Class_02&SubClass_09&Prot_%02X
    -USB\Class_02&SubClass_09
    +
    USB\Class_02&SubClass_09&Prot_%02X
    +USB\Class_02&SubClass_09
     USB\Class_02